zizi-al/games-development-ai
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity
games-development-ai/.agents/skills/prompt-governance.md

9.3 KiB
Raw Blame History

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

蒸馏来源：执行版 ../../docs/agent-specs/prompt治理体系-execution.md（HJ-PROMPT-GOV-EXEC-001）。 适用：新增/修改任何生命周期 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。

⚠️ 引擎上下文纠偏（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）仍现行有效。

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

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

为什么必须治理：多引擎/多链路使 prompt 数量与形态膨胀；无单一事实源 → 跨链路无法统一治理、改动无法回归验证。（原述"双引擎 OpenGame+Cocos-MCP" 中 OpenGame 已退役，见上方纠偏。）

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}} 引用，壳层调用前注入实际文本。（Dify 已退役；现行=壳层/编排器调 new-api 前按 id@version 渲染注入。）
  • OpenGame / Cocos-MCP / ComfyUI：壳层把对应 prompt 作为参数/ system prompt 传入（OpenGame 已退役，Tier1 改 agent 写码于 LittleJS 插件库；Cocos-MCP/素材链不变）。
  • 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；MVP 仅探针

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

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

  1. 在对应阶段目录建 prompt 文件，写全 frontmatter（id/version/owner/tier/engine/stage）。
  2. 定义或复用 _schemas/ 下的输入/输出 JSON Schema，frontmatter 绑定。
  3. 写硬约束块 + guardrails（注入检测/Schema 校验/资源引用校验）。
  4. 建 Golden eval 集 eval/<id>/：inputs.jsonl（5–10 条核心样本）+ expect.yaml（期望属性/阈值）+ baseline/（基线产物快照）。
  5. 在 registry.yaml 登记索引。
  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/ 关键字段 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 校验，与内容安全双层链路同治理