zizi 824183864e docs(architecture): 重构为产品/技术/映射三文档 + MVP 迁移产品功能口径

- 去版本化：能力清单拆为三文档（产品需求清单/技术架构与模块/需求模块映射），
  文件名去 v2.1 版本号为唯一权威副本；删除混合视角旧档《业务能力全景与模块归属》，
  ~20 处交叉引用重定向（git 留史）
- 模块 12→13：新增 game-module-studio（创作编排域），aigc 收敛为无状态生成原子；
  锁风门 Gate(owner=compliance)、专区 Zone(owner=project) 两横切显式建模
- MVP 口径迁移：验收单位由"能力项(131)"改为 Doc A 的 55 项 P0 产品功能，
  工作量≈137 技术项；CLAUDE/AGENTS/mvp-scope/执行 spec §7/工作流 全链同步
- 三轮评审（人工 + 3 独立 Opus）findings 已修复：0 断链/0 孤儿/0 重复 ID，
  计数 155/204/137 实测自洽；glossary 补锁风门/专区/创作会话/资产图术语
- 新增 docs/memorys 任务记忆与 agent-specs 重划/prompt 治理评审依据

Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>

2026-06-07 12:38:14 +00:00

8.3 KiB

Raw Blame History

Prompt 工程治理手册（prompt-governance）

蒸馏来源：评审版 ../../docs/agent-specs/2026-06-07-prompt治理体系-review.md（HJ-PROMPT-GOV-001，2026-06-07 六项裁决全采纳 a）。适用：新增/修改任何生命周期 prompt（意图/代码生成/素材/剧情/锁风/测试/平台转换/运营诊断）、搭建 Prompt Registry 与 eval 门禁、对接人在环（HITL）节点。配套：契约先行见 ./contract-first-development.md；AI 生成链路见 ./ai-generation-pipeline.md；运行时/Cocos 见 ./runtime-and-multichannel.md；选型见 ../knowledge/tech-decisions.md §1.1；降级红线见 ../rules/security-and-reliability.md。

核心理念：Prompt 即第 8 类契约资产

所有 prompt 进 git contracts/prompts/ 单一事实源，与 Day-0 七契约同级。每条 prompt 绑定一份完整契约：输入 Schema + 输出 Schema + 硬约束块 + Golden 样本集 + owner + version。运行时按 id@version 加载注入，不在 Dify/OpenGame/Cocos 内核里内嵌——延续"能力增强放壳层、不动内核"的纪律（与 ai-generation-pipeline 同源）。

为什么必须治理：双引擎（OpenGame + Cocos-MCP）使 prompt 数量与形态膨胀；无单一事实源 → 跨引擎无法统一治理、改动无法回归验证。

1. Registry 目录结构

contracts/prompts/
├── registry.yaml              # 索引：所有 prompt 的 id/版本/owner/绑定 schema/eval 集
├── _schemas/                  # 输入/输出 JSON Schema（prompt 的契约）
├── intent/                    # 意图解析、模板匹配（owner=aigc）
├── codegen-opengame/          # Tier1 文生代码（owner=aigc）
├── codegen-cocos-mcp/         # Tier2/3 agentic 工具编排（owner=studio）
├── asset/                     # 素材生成（图/音/角色/特效）+ IP LoRA 约束（owner=aigc）
├── narrative/                 # 剧情/分支对白/关卡（owner=studio）
├── lockstyle/                 # 锁风约束（风格-版权一致性，owner=compliance）
├── qa/                        # 测试用例 + 可玩性脚本（owner=aigc，T-AGC-09）
├── convert/                   # 打包/平台转换约束（尺寸/资质/违禁词，owner=runtime）
└── ops/                       # AI 诊断/改版任务（owner=telemetry）

每条 prompt = frontmatter 契约头 + 模板体：

---
id: codegen-opengame.scaffold        # 唯一 id（目录.阶段）
version: 1.2.0                        # 语义化版本
owner: WS2/aigc                       # 唯一负责工位/模块
tier: tier1                          # tier1 | tier2 | tier3
engine: opengame                     # opengame | cocos-mcp | dify | comfyui | runtime
stage: scaffold
input_schema: _schemas/codegen-input.json
output_schema: _schemas/game-config.json
constraints:                         # 硬约束块（产物必须满足）
  - 首屏≤2MB, 总包≤10MB
  - 游戏内零网络请求（CSP connect-src none）
eval_set: eval/codegen-opengame.scaffold/
guardrails: [injection-detect, schema-validate, asset-ref-check]
---
{{system_prompt}}
... 模板体，带 {{变量槽}} ...

2. 加载 / 注入机制

aigc / studio 壳层 持有 PromptRegistryLoader：按 id@version 取 prompt 文本并用变量渲染。
Dify 节点：prompt 用 {{registry:intent.parse@1.2.0}} 引用，壳层调用前注入实际文本。
OpenGame / Cocos-MCP / ComfyUI：壳层把对应 prompt 作为参数/ system prompt 传入。
DB 镜像（可选）：只读，仅为运行时热加载提速；写入路径唯一为 git。

部署时强制校验 registry 版本一致；CI 卡 Schema。改 prompt = 改 git → PR → eval 门禁 → 合入 → 同步运行时。

3. 两套 Prompt 形态

维度	OpenGame prompt（Tier1）	Cocos-MCP prompt（Tier2/3）
形态	生成式：文本 → 游戏代码	agentic：驱动 158 个编辑器工具的工具编排
调用	单次/6 阶段 pipeline	多步、有状态、多轮工具调用
归属	aigc（无状态生成原子）	studio（有状态创作编排，T-STU-05）
失败降级	退化为模板填充	退化为 Tier1/OpenGame；MVP 仅探针

目录分治（codegen-opengame/ vs codegen-cocos-mcp/），加载器按 engine 字段分发，不强行统一模板。

4. 新增一条 Prompt（操作步骤）

在对应阶段目录建 prompt 文件，写全 frontmatter（id/version/owner/tier/engine/stage）。
定义或复用 _schemas/ 下的输入/输出 JSON Schema，frontmatter 绑定。
写硬约束块 + guardrails（注入检测/Schema 校验/资源引用校验）。
建 Golden eval 集 eval/<id>/：inputs.jsonl（5–10 条核心样本）+ expect.yaml（期望属性/阈值）+ baseline/（基线产物快照）。
在 registry.yaml 登记索引。
提 PR → eval 门禁绿 + 人工抽检 → 合入 → 部署同步。

5. 修改一条 Prompt 并验证效果（操作步骤）

改 prompt 文件，version 必须 bump（语义化）。
PR 触发 eval：跑绑定的 Golden 集 → 四道闸比对（见 §6）。
全绿 + 人工抽检 K 条 → 合入；任一红 → 阻断 PR + 给 diff 报告。
合入后灰度新版本 → 观察 telemetry 行为指标（完玩/重玩率）→ 全量或一键回滚（version 切换）。

常用 prompt 预留参数槽：运营改参数（如难度/时长）不改结构，免 PR；改结构才走 PR+eval。

6. Eval 轻量门禁（四道闸）

闸	判定	来源
① Schema 通过率	输出符合 output_schema 的比例 ≥ 阈值	评审版 §4.4
② 生成成功率	可运行 + 质量通过 ≥ 80%	MVP 验收线
③ Golden 回归	与 `baseline/` 关键字段 diff，防退化	泛化自 T-AGC-08
④ 成本/延迟	token/耗时不劣化	评审版 §4.4

四闸全绿 → 人工抽检 K 条（主观质量/可玩性）→ 合入。可玩性 MVP 不自动评分（结构校验测不了"好玩"），靠人工抽检 + 上线后行为指标反哺下一轮。

7. HITL 人在环节点

创作者（C 端·每次生成）：输入一句话/选 IP 附件 → 任务链进度可中断 → 预览试玩 → 接受/带修改重生成 → 锁风强度 → 对白调试 → 发布前检查 → AI 诊断一键迭代。（P-CRT-01/04/05/08/09、P-LIC-04/05、P-PUB-03、P-OPS-03/04）
运营（B 端·Prompt 生命周期）：提 PR 改 prompt → eval 门禁+人工抽检批准 → 模板库策展 → 人工复核队列（T-CMP-05）→ 新版灰度+回滚。

8. 测试脚本生成（T-AGC-09）

aigc 新增无状态原子：输入 GameConfig → 输出可玩性测试脚本（启动/输入响应/边界）；由 runtime 编译流水线执行为入库门禁的一环。其 prompt 归 contracts/prompts/qa/。不新增模块。

9. 降级铁律

失败点	降级
prompt 加载失败（缺 id/version）	回退内置默认 prompt + 告警，不中断生成
LLM 不可用	退化为确定性 Fallback 生成器（模板填充，见 ai-generation-pipeline §7）
Cocos-MCP 工具调用失败	降级 Tier1/OpenGame 路径；MVP Tier2/3 仅探针
eval CI 跑不通（LLM 限流）	标记 skip + 人工兜底审，不阻塞紧急修复

10. 常见坑

坑	排查 / 应对
改了 prompt 没 bump version	CI 卡：version 未变拒绝合入（防静默覆盖）
Golden 集过拟合	样本要覆盖典型+边界，bad case 增量补；勿只放"好跑"的样本
registry 与运行时不同步	部署强制版本校验；DB 镜像只读；改 prompt 必同步 registry.yaml
Cocos-MCP prompt 当文生代码写	它是 agentic 工具编排（多步），不是单次文本；归 studio 编排
运营绕过 eval 直接改 DB	DB 是 git 只读镜像，无写入路径；改 prompt 唯一入口=PR
prompt 注入攻击	guardrails 内置 injection-detect + 输出 Schema 校验，与内容安全双层链路同治理

8.3 KiB Raw Blame History Unescape Escape