# contracts/prompts/ —— 第 8 类契约：Prompt Registry

> Prompt 即契约。所有生成链路的 LLM prompt 在此 Git 化注册、版本化、过门禁，禁止散落在 Dify 节点/代码里。
> 治理细则见 [`.agents/skills/prompt-governance.md`](../../.agents/skills/prompt-governance.md)(单一 how-to 源);历史执行档已退役进 git 史(`git show bb7c2baf:docs/agent-specs/prompt治理体系-execution.md`)。

## 目录结构（8 阶段）
```
prompts/
├── registry.yaml          # 注册表：id@version / owner / stage / file / eval
├── 01-safety/             # Prompt 安全/注入检测
├── 02-intent/             # 意图解析
├── 03-template/           # 模板匹配
├── 04-config/             # GameConfig 生成
├── 05-asset/              # 素材生成（ComfyUI 引导）
├── 06-quality/            # 质量评估
├── 07-fix/                # 失败修复/重生成
├── 08-meta/               # 标题/简介/封面文案
└── eval/<id>/             # 每条 prompt 的 Golden eval 集（inputs/expect/baseline）
```

## 引用与变更
- 引用：aigc 壳层用 `{{registry:id@ver}}` 引用，`PromptResourceLoader` 加载注入（Dify 已降级远期，原 Dify 节点引用方式随之退役）。
- 变更：改 prompt **必须升 version**，并过四道闸 CI（Schema 通过率 / 生成成功率≥80% / Golden 回归 diff / 成本延迟）；四闸绿后运营 HITL 抽检 K 条方可合入。

## Registry 一致性 CI 门（check_registry.py）

`check_registry.py`（本目录同级）验证 `registry.yaml` 里每条 `version` 与对应 `.md` frontmatter 的 `version` 是否完全一致。防止 Java `PromptResourceLoader` 构建期快照加载的 prompt 版本与注册表宣称版本漂移（二者不一致会导致日志/追溯/审计失真）。

**手动跑：**
```bash
python3 contracts/prompts/check_registry.py
# exit 0 = 全部对齐；exit 1 = 有漂移（打印具体 id + 两侧 version）
```

**已挂载（2026-07-03）：**
- pre-commit：`.githooks/pre-commit` 在本次暂存触及 `contracts/prompts/` 时跑本脚本，非零即拦（紧急绕过 `git commit --no-verify`，服务端门仍兜）。
- CI：`.gitea/workflows/contract-gates.yml`(与 docs-gate 平级的服务端门)每次 push / PR 全量跑，不可绕。

触发时机：任何 prompt `.md` 或 `registry.yaml` 变更（pre-commit 按路径条件触发）；CI 每次全量跑。