games-development-ai/.agents/skills/prompt-governance.md

name, description

name	description
prompt-governance	当新增或修改生命周期 prompt、搭建 Prompt Registry 与四道闸 eval 门禁、或对接人在环节点时使用:prompt 即第 8 类契约,contracts/prompts 版本化单一事实源与治理流程(段A版本闸+段B真模型闸 CI 已接)。

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

蒸馏来源：执行版 ../../docs/architecture/架构/生成引擎/prompt治理.md（HJ-PROMPT-GOV-EXEC-001）。 适用：新增/修改任何生命周期 prompt（安全/意图/模板/生成/素材/质量/修复/元信息八阶段，及 tier2 富游戏线）、搭建 Prompt Registry 与 eval 门禁、对接人在环（HITL）节点。 配套：契约先行见 ./contract-first-development.md；AI 生成链路见 ./agentic-amodel-generation.md；运行时/Cocos 见 ./runtime-and-multichannel.md；选型见 ../knowledge/tech-decisions.md §1.1；降级红线见 ../rules/security-and-reliability.md。

⚠️ 引擎上下文纠偏（2026-06-12）：本手册核心理念（Prompt 即第 8 契约 / Registry / eval 门禁 / HITL）现行有效不变；但下文凡以 Dify / OpenGame 为注入目标/引擎载体的描述均按现行裁决改读——Dify/OpenGame=降级远期未部署（C2/HJ-GEN-001），Tier1 生成主线=new-api 网关 + agent 写码于插件库（引擎=LittleJS 增强发行版），agentic 编排基建=AgentScope 2.x（HJ-AGI-001）。"模板填充"措辞按模板哲学终裁更新（玩法模板层废除）。Cocos-MCP（Tier2/3）仍现行有效。

⚠️ 现行化重写（2026-07-05）：§1–§3 已按现行 registry.yaml（阶段编号目录重构 + 头部消费面三态对账）与 W-PCI 后口径整块重写——目录树、加载器类名（PromptResourceLoader）、两条 live 生成线（便宜档 cheap-worker / tier2 AgentScope）形态均改为现行事实，此前散在正文的划线改读不再需要、随句清理。上条 2026-06-12 记的「Cocos-MCP 仍现行有效」本次一并修正：Cocos-MCP 降为 3D 与渠道导出的人在环工具，非 live 生成形态。

---

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

所有 prompt 进 git contracts/prompts/ 单一事实源，与 Day-0 七契约同级，在 registry.yaml 按条目登记（id / version / stage / owner / file / desc / eval），各配 Golden eval 集与硬约束。运行时按注册条目正文加载注入、不在引擎/编排内核里内嵌——便宜档由 cheap-worker 读、tier2 由 AgentScope gen-worker 读、后端模板策划由 PromptResourceLoader 读，延续"能力增强放壳层、不动内核"的纪律。

为什么必须治理：多条生成线（便宜档 / tier2 / 后端模板策划）使 prompt 数量与形态膨胀；无单一事实源 → 跨链路无法统一治理、改动无法回归验证。

---

1. Registry 目录结构

Prompt 按生成链路阶段编号归档，registry.yaml 作索引（唯一事实源），eval/ 放各条 Golden 集，同级还摆着三个治理脚本：

contracts/prompts/
├── registry.yaml           # 注册表(索引):每条 prompt 的 id / version / stage / owner / file / desc / eval
├── README.md               # 目录说明 + registry 一致性 CI 门说明
├── check_registry.py       # CI 门:registry.yaml 各条 version 与对应 .md frontmatter version 对齐
├── check_version_bump.py   # 段 A 离线版本闸:改正文必升 version(见 §6)
├── eval_gate.py            # 段 B 真模型闸:对 live 条目跑四道闸、真调 M3(见 §6)
├── 01-safety/             # Prompt 安全/注入检测
├── 02-intent/             # 意图解析
├── 03-template/           # 模板匹配
├── 04-config/            # 生成主线:cheap-system(便宜档主 prompt) + 各品类 -designer(模板策划/编码)
├── 05-asset/             # 素材生成(ComfyUI 引导)
├── 06-quality/           # 质量评估
├── 07-fix/               # 失败修复/重生成
├── 08-meta/              # 标题/简介/封面文案
├── 09-tier2-richgame/    # tier2 富游戏自治生成线的 8 条 prompt(AgentScope 多 agent)
└── eval/<id>/            # 每条 prompt 的 Golden eval 集(inputs.jsonl / labels.jsonl / baseline.json / runs/)

01–08 是按生成链路顺序保留的阶段槽，眼下真正落有条目的是 01-safety、04-config（生成主线含便宜档）、06-quality 与 07-fix（agent 闭环批跑遗留），加上 09-tier2-richgame（tier2 八条）；其余为规划槽、暂无 prompt。

每条 prompt 在 registry.yaml 登记一条索引，字段固定为 id / version / stage / owner / file / desc / eval，没有 engine / tier——生成线归属由 stage 与消费方代码决定，不写进注册表。摘一条现行 live 条目为例：

- id: safety.prompt-check                    # 唯一 id = 阶段域.角色
  version: 1.0.0                             # 语义化版本;改正文必升(段 A 版本闸强制)
  stage: "01-safety"                         # 阶段编号目录(01-safety…08-meta / 09-tier2-richgame)
  owner: WS2                                 # 唯一负责工位
  file: 01-safety/prompt-safety-check.md     # 正文文件(其 frontmatter 至少含 id+version)
  desc: 创作者 Prompt 安全/注入检测（生成链路第 1 节点）
  eval: eval/safety.prompt-check/            # Golden eval 集(四道闸:Schema/成功率/回归diff/成本延迟)

注册表是索引与对账基准，prompt 正文另存于 file 指向的 .md，各带一份 frontmatter（至少 id 与 version，check_registry.py 逐条比对两侧 version 防漂移）。有的正文还内嵌 output_schema / hard_constraints（如 safety）或 tier / engine 注记（如 tier2 各条），那是正文自己的元信息，注册表条目只认上述七字段。

---

2. 加载 / 注入机制

三条生成线各有自己的加载器，共同纪律是按 file 指向的正文加载、best-effort 回落进程内内置原文、绝不因 prompt 读取失败中断生成：

• 后端模板策划 prompt（04-config 各品类 -designer） 由 game-module-aigc 的 PromptResourceLoader 加载。构建期 maven-resources-plugin 把 contracts 下的 prompt 与 schema 快照进 classpath:wanxiang-contracts/（jar 内只是构建时快照，git contracts/ 仍是唯一事实源）；启动逐模板自检，任一缺失或形态非法即整体 ready=false 自禁用，执行器 tick 首检不认领任务、不崩 app。渲染只做 {{input.xxx}} 替换加残留占位符检测；version 仅作可追溯日志，不做 registry 对账——那是 CI 四道闸的职责，Java 不复制治理逻辑。配了 aigc.prompts.dir / AIGC_PROMPTS_DIR 外置目录后每 60s 热取，运营改完 prompt 无需重启即生效，读失败保留上次、classpath 快照永久兜底。
• 便宜档 cheap-worker 由 cheap_roles.py 的 _load_system_prompt() 运行时读 04-config/cheap-system.md 正文，读不到、脏或缺文件即回落进程内 _SYSTEM_PROMPT。
• tier2 富游戏 gen-worker 由 roles.py 经 worker/prompts.py 的 prompts.load 运行时读 09-tier2-richgame/ 下八条正文，读不到或脏即回落 roles.py 内置原文。

版本一致性由 check_registry.py 守门：逐条比对 registry 的 version 与对应 .md frontmatter 的 version，不一致即拒绝合入（防 PromptResourceLoader 构建期快照版本与注册表宣称漂移、审计失真），已挂 pre-commit 与服务端 contract-gates.yml。

改 prompt = 改 git 正文加升 version → PR → eval 门禁 → 合入 → 下次构建或热取自动携带新版。

---

3. 两条 live 生成线的 prompt 形态

现行 runtime 只有两条生成线在跑，prompt 形态、加载器与失败回落各管一摊：

维度	便宜档 cheap-worker	tier2 富游戏 AgentScope 多 agent
主 prompt	单条 config.cheap-system	tier2.* 八条（leader + 四工作室专家 + 兜底 design-system + 单写 writer + 软检 player）
范式	A-model 一个 agent 写 LittleJS src/ 源工程（入口契约 + 插件 + 红线 + 输入契约 + 完成判据）	AgentScope 2.0.2 ReAct 两阶段：阶段 1 工作室多 agent 出设计稿 → 阶段 2 单写 ReAct 写 Phaser 源码 + L3 视觉软检玩家
AI 参与深度	轻（便宜档，插件库承重、AI 少写）	重（自治多轮、有状态工具编排）
归属目录	04-config/cheap-system.md	09-tier2-richgame/（八文件）
消费方	cheap_roles.py _load_system_prompt()	roles.py 经 worker/prompts.py prompts.load
失败回落	回落 cheap_roles._SYSTEM_PROMPT	回落 roles.py 内置原文

Cocos-MCP 不是 live 生成形态：它降为 3D 与渠道导出的人在环工具（人工在编辑器里操作），不进 MVP 生成 runtime，也不在本治理的形态对照内。素材生成链（ComfyUI 引导，归 05-asset/）另走各自门禁。

---

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

1. 在对应阶段编号目录建 prompt 正文 .md，写 frontmatter（至少 id + version，归属写 owner；stage 与注册表一致）。
2. 有输出约束的（如 04-config 各品类模板策划）绑定 contracts/templates/<id>.schema.json；纯 system prompt（cheap-system / tier2 各条）无外置输出 schema。
3. 写硬约束块 + guardrails（注入检测/Schema 校验/资源引用校验）。
4. 建 Golden eval 集 eval/<id>/：inputs.jsonl（核心样本）+ labels.jsonl（期望标注）+ baseline.json（基线快照，--update-baseline 建，闸 3/4 据此判增量）；每次跑的台账 append-only 落 runs/。
5. 在 registry.yaml 登记条目（id/version/stage/owner/file/desc/eval）。
6. 提 PR → eval 门禁绿 + 人工抽检 → 合入 → 部署同步。

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

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

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

---

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

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

四闸全绿 → 人工抽检 K 条（主观质量/可玩性）→ 合入。

怎么跑（2026-07-04 已接成 CI，W-PCI）：四道闸按成本分两段落地。段 A 离线版本闸（contracts/prompts/check_version_bump.py）兜闸 0「改正文必升 version」——相对基线剔除 frontmatter version 行后比正文，正文变而 version 没升即 exit 1；挂 .githooks/pre-commit 与 .gitea/workflows/contract-gates.yml 服务端门，每次提交自动跑、秒级零成本。段 B 真模型闸（contracts/prompts/eval_gate.py --id <id> 或 --changed --base <ref>）跑闸 1~4，对改动的 prompt 拿其金标集真调 MiniMax-M3（经 new-api、thinking 关、key 从 env 读、ProxyHandler({}) 绕系统代理）判定；.gitea/workflows/prompt-eval.yml 手动 workflow_dispatch 触发，单跑预算硬上限 ≤¥5。只焊 live 面：接门前先查 registry.yaml 头部消费面三态对账——非 live（fossil/batch-relic）条目 SKIP 豁免、live 但无金标集 fail-closed（绝不假绿），别把门焊在已下架的化石 prompt 上白花钱。调用失败（网关 500/限流）排除出判定分母、建议复跑（不阻塞、不误判 prompt）。台账 append-only 落 eval/<id>/runs/，回归基线 eval/<id>/baseline.json（--update-baseline 建，闸 3/4 据此判增量）。可玩性 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 若落地归质量评估阶段 06-quality/。（现行可玩性判定实走生成线九门真玩 harness，本条 T-AGC-09 独立测试脚本 prompt 尚未落地。）不新增模块。

---

9. 降级铁律

失败点	降级
prompt 加载失败（缺 id/version）	回退内置默认 prompt + 告警，不中断生成
LLM 不可用	退化为确定性 Fallback 生成器（确定性兜底产出，模板填充措辞已更新，见 ../rules/security-and-reliability.md §5.2）
tier2 / 便宜档 prompt 正文热取读到脏或缺失	回落进程内内置原文（roles.py 原文 / cheap_roles._SYSTEM_PROMPT / classpath 快照），best-effort 绝不中断生成
eval CI 跑不通（LLM 限流）	标记 skip + 人工兜底审，不阻塞紧急修复

---

10. 常见坑

坑	排查 / 应对
改了 prompt 没 bump version	CI 卡：version 未变拒绝合入（防静默覆盖）
Golden 集过拟合	样本要覆盖典型+边界，bad case 增量补；勿只放"好跑"的样本
registry 与运行时不同步	部署强制版本校验；DB 镜像只读；改 prompt 必同步 registry.yaml（commit 在途 M 触发 pre-commit 版本漂移闸的处置见 staging-ops.md §2）
tier2 多 agent prompt 当单次文生代码写	它是 AgentScope ReAct 多步有状态编排（工作室设计→单写→软检）；改一条只改对应 09-tier2-richgame/*.md 正文加升 version，不改 Python
把 CI 门焊在化石 prompt 上白花钱	段 B 真模型闸只焊 live 面；接门前先查 registry 头部消费面三态对账，非 live（fossil/batch-relic）SKIP 豁免、live 无金标 fail-closed；先用代码坐实「谁真被 live 路径喂 LLM」再决定跑不跑
单条模型调用失败当成 prompt 退化拦	网关 500/限流是基础设施问题，从判定分母排除 + 建议复跑（多数失败才判人工兜底），别让偶发抖动误判 prompt 质量
运营绕过 eval 直接改 DB	DB 是 git 只读镜像，无写入路径；改 prompt 唯一入口=PR
prompt 注入攻击	guardrails 内置 injection-detect + 输出 Schema 校验，与内容安全双层链路同治理

---

11. 稳定门在 MiniMax-M3 下的 flaky 与治法（2026-07 W-AXIS R1 实证）

段 B 真模型闸之上，actor/judge 类 prompt 还叠了一道稳定门，防单轮侥幸过。judge 要同一请求连续三轮金标全净（MIN_STABLE_RUNS=3，eval_gate.py:114；双 judge 各自 6/6、actor 至少 4/5，见 :12）再加第四轮复跑确认；actor 走 cohort 聚合（evaluate_repeat_stability，:2827），三轮里 correct_total≥12 且每键 ≥2/3（:2884-2885）。这套门在 MiniMax-M3 下很 flaky——judge-b 跑到第 33 轮才出一个三连净，单轮全净率只有 35–45%。

flaky 根因分三层，治法各不同，别混着调：

• ① 金标白名单同义词覆盖不全（主因，治本=补同义词）。labels 的 anyTerms/requiredConcepts 是自由文本白名单（eval_gate.py:1873-1886），M3 常用的近义表达落在白名单外就被判错：净利↔利润/净收益、零单↔0单（汉字「零」≠数字「0」）、通关↔胜利、time-over/end-state↔game over、缺少证据↔缺证、cannot↔不能、open shop≠open-shop（连字符差）、no proving evidence≠no evidence（非连续子串）。补这些进 requiredConcepts 同义组不是放松标准，是让金标覆盖合法的同义表达；flaky 的主要来源由此消掉。
• ② 格式类失败（正文加硬约束可消除）。JSON 尾部多游离 ]、problems 缺硬证引用、obligation id 笔误（如 sim-business 误写成 sem-business）。在 prompt 正文加硬约束即掉：输出 JSON 配平自检、obligation id 逐字复制不得改写、problems 逐条带硬证引用、summary 全引用、反事实视觉判定（文本说营收为正但画面还在开店前 → 判 contradicted，不得 accept）。
• ③ 视觉误判（正文约束仅边际改善）。把 GAME OVER 帧读成通关、漏 event 引用，属模型读图能力，正文加约束只能边际改善，治不了本。

做法：正文强化格式约束 + 补 anyTerms 同义词 + 几何退避等其收敛闭合，不降阈值、不 cherry-pick 净轮。actor 判据本就比 judge 宽（cohort 聚合而非单轮全净），闭合相对容易；judge 单轮全净门最硬，补同义词后才收敛。