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

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

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

```yaml
- 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`](../../contracts/prompts/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`](../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`](./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 单轮全净门最硬，补同义词后才收敛。