games-development-ai/docs/agent-specs/prompt治理体系-execution.md

造梦AI — 全生命周期 Prompt 工程治理体系（执行版）

文档类型：执行版（供 agent 实现，含落地步骤/接口契约/验证/回滚，不预写无法验证的代码细节） 文档 ID：HJ-PROMPT-GOV-EXEC-001　｜　生成时间：2026-06-07 配套 playbook：../../.agents/skills/prompt-governance.md 选型依据：../../.agents/knowledge/tech-decisions.md §1.1（引擎二次裁决）

---

1. 目标与范围边界

目标：把分散在 6 个消费点的所有 prompt 收为 git contracts/prompts/ 单一事实源（第 8 类契约），实现版本化管理、改动可自动回归验证、HITL 治理节点落地。

范围（MVP）：覆盖 Tier1 全链路 prompt —— intent / codegen-opengame / asset / narrative / lockstyle / qa / convert / ops。codegen-cocos-mcp 仅留探针目录，不投入工程。

非目标：LLM-as-judge 自动打分、eval 看板、运营 DB 热改、prompt 可玩性自动评分（均 MVP 后）。

---

2. 前置条件

• contracts/ 目录已存在（Day-0 契约已锁，本体系作为第 8 类契约纳入）。
• aigc Java 壳已可运行（DifyClient/TaskDispatcher 已就位，见 ai-generation-pipeline §1）。
• Dify workflow 已发布；OpenGame /generate 可调通。
• CI（GitHub Actions 或等价）可对 PR 跑脚本。

---

3. 涉及模块与文件路径

模块/位置	新增/改动	说明
contracts/prompts/	新增	Registry 目录（结构见 playbook §1）
contracts/prompts/registry.yaml	新增	prompt 索引
contracts/prompts/_schemas/*.json	新增	输入/输出 JSON Schema
contracts/prompts/eval/<id>/	新增	每条 prompt 的 Golden 集
game-cloud aigc/.../prompt/PromptRegistryLoader.java	新增	加载/渲染 prompt
game-cloud aigc/.../prompt/PromptTemplate.java	新增	prompt 数据结构（frontmatter+body）
game-cloud aigc/.../service/qa/TestScriptService.java	新增	T-AGC-09 测试脚本生成原子
game-cloud runtime/.../service/compiler/	改动	编译后执行测试脚本为入库门禁
Dify workflow LLM 节点	改动	prompt 文本改为 {{registry:id@ver}} 引用
game-admin views/prompt/	新增（P1）	运营查看/触发 prompt PR 流程页
.github/workflows/prompt-eval.yml	新增	PR 触发 eval 门禁

---

4. 数据流与依赖

graph LR
  GIT["contracts/prompts/（git 单一事实源）"] --> LOADER["PromptRegistryLoader（aigc/studio 壳）"]
  LOADER -->|id@version 注入| DIFY["Dify 节点"]
  LOADER -->|参数传入| OG["OpenGame"]
  LOADER -->|system prompt| CC["Cocos-MCP（studio，探针）"]
  PR["Prompt 改动 PR"] --> CI["prompt-eval CI"]
  CI -->|读| GIT
  CI --> GATE["四道闸 + 人工抽检"]
  GATE -->|绿| MERGE["合入→部署同步"]
  TEL["telemetry 行为指标"] -.反哺.-> PR

依赖方向：壳层 → Registry（读）；CI → Registry（读）+ LLM/OpenGame（跑样本）；runtime → T-AGC-09（执行测试）。不引入新的跨模块强耦合（Registry 是文件契约，非服务）。

---

5. 接口 / 数据契约

5.1 Prompt frontmatter schema（_schemas/prompt-frontmatter.json）

必填：id(string, 唯一)、version(semver)、owner(string)、tier(enum tier1/2/3)、engine(enum)、stage(string)、input_schema(path)、output_schema(path)。选填：constraints(string[])、eval_set(path)、guardrails(string[])。

5.2 PromptRegistryLoader 接口（契约，非实现）

PromptTemplate load(String id, String version)      // 取一条 prompt（含 frontmatter+body）；缺失抛 PromptNotFoundException
String        render(String id, String version, Map<String,Object> vars)  // 变量渲染为最终文本
List<PromptMeta> list(String stageOrEngine)         // 按 stage/engine 列出
boolean       validate(PromptTemplate t)            // 校验 frontmatter + schema 绑定有效

加载策略：优先 DB 只读镜像（命中即返回），未命中回源 git checkout；启动期全量校验 registry.yaml 与文件一致。

5.3 Eval 配置格式（eval/<id>/）

• inputs.jsonl：每行一个输入样本（符合 input_schema）。
• expect.yaml：schema_pass_rate(≥)、success_rate(≥0.8)、golden_diff_fields(关键字段列表)、max_cost_delta、max_latency_delta。
• baseline/：基线产物快照（合入新基线时更新）。

5.4 T-AGC-09 契约

TestScript generate(GameConfig config)   // 输入 GameConfig → 输出测试脚本（启动/输入响应/边界断言）
// runtime 编译后执行：通过=可入库；失败=拒绝入库 + 原因分类

---

6. 关键实现步骤（分阶段，按 MVP 节奏）

阶段	步骤	完成判据
P0 骨架	建 contracts/prompts/ 目录树 + registry.yaml + _schemas/；把现有散落 prompt（Dify 节点/OpenGame）抽取迁入 Tier1 全链路目录	8 个阶段目录就位，现有 prompt 全部入库且有 frontmatter
P1 加载	实现 PromptRegistryLoader + PromptTemplate；Dify 节点改 {{registry:id@ver}} 引用；壳层注入	Dify 跑通时 prompt 来自 Registry（非内嵌），改文件即生效
P2 门禁	写 prompt-eval.yml CI + 四道闸脚本；为每条 prompt 建 Golden 集（5–10 样本）	改一条 prompt 的 PR 能被 eval 拦截/放行
P3 测试原子	实现 T-AGC-09 TestScriptService；runtime 编译流水线挂载执行	生成游戏入库前自动跑可玩性测试脚本
P4 HITL	创作者侧复用现有"重生成/锁风"节点；运营侧 game-admin prompt 管理页（P1，可先用 PR 流程文档替代）	运营能走"改 prompt→eval→批准"闭环

---

7. 边缘失败路径

失败	处理
prompt id/version 不存在	load 抛异常 → 壳层回退内置默认 prompt + 告警，不中断生成
frontmatter/schema 校验失败	启动期/CI 拒绝该 prompt 上线，报具体字段
eval 跑不通（LLM 限流/超时）	CI 标记 skip + 通知人工兜底审，不阻塞紧急修复
改 prompt 未 bump version	CI 卡：version 未变 → 拒绝合入
registry.yaml 与文件不一致	启动期校验失败 → 阻止部署
Cocos-MCP 工具调用失败（探针）	降级 Tier1/OpenGame；不影响 MVP 主链路

---

8. 验证方法

• registry lint（CI）：frontmatter schema 校验 + registry.yaml 一致性。
• loader 单测：load/render/validate 覆盖正常 + 缺失 + 校验失败。
• eval 门禁端到端：故意改坏一条 prompt → PR 应被四道闸拦截；正常改 → 放行。
• T-AGC-09 验证：对 3 个模板生成游戏跑测试脚本，确认能拦住"不可运行"产物。
• 注入注入注入回归：prompt 注入样本应被 guardrails 拦截。

---

9. 完成条件

1. contracts/prompts/ Tier1 全链路 prompt 入库 + registry.yaml 索引完整。
2. PromptRegistryLoader 跑通：Dify 生成时 prompt 真实来自 Registry。
3. prompt-eval CI 对至少 1 条 prompt 生效（能拦截退化）。
4. T-AGC-09 产出测试脚本，runtime 编译流水线执行为入库门禁。
5. 运营"改 prompt→eval→批准"闭环可走（页面或文档化流程）。

---

10. 回滚策略

层级	回滚
单条 prompt	version 切换 / git revert 该 prompt 文件
加载机制	loader 失败回退内置默认 prompt（不中断生成）
整体体系	关闭 Registry 加载开关，回到 Dify-native（保留旧 workflow 内嵌 prompt 作兜底）

整体回滚成本低：Registry 是叠加层，旧 Dify-native prompt 不删除、仅不被引用；开关回切即恢复。

---

执行版"通过"= 你确认 §6 阶段拆分与 §5 接口契约无异议；通过后由子代理按阶段拆分 spec 并子代理评审（按 CLAUDE.md 两轮评审）。