From a9cf87955f407c4337b72f86e1d7eab17df14058 Mon Sep 17 00:00:00 2001 From: lili Date: Sat, 4 Jul 2026 09:27:17 -0700 Subject: [PATCH] =?UTF-8?q?docs(.agents):=20W-PCI=20=E8=92=B8=E9=A6=8F?= =?UTF-8?q?=E2=80=94=E2=80=94=E5=9B=9B=E9=81=93=E9=97=B8=20CI=20=E8=90=BD?= =?UTF-8?q?=E5=9C=B0=E5=86=99=E5=9B=9E=20prompt-governance=20=C2=A76/?= =?UTF-8?q?=C2=A710=20+=20engineering-conventions=20=E6=9C=BA=E5=99=A8?= =?UTF-8?q?=E9=97=A8=E8=8C=83=E6=9C=AC?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit 把「四道闸怎么跑」蒸馏回可复用 playbook 与门清单: - prompt-governance §6:加落地段(段A check_version_bump 挂 pre-commit+contract-gates / 段B eval_gate 经 prompt-eval workflow_dispatch,真模型 M3 绕代理 key 从 env,只焊 live 面,cap ¥5,台账+基线);§10 加两坑(别把门焊化石 prompt 白花钱 / 单条调用失败别当 prompt 退化拦)。 - engineering-conventions 机器校验器范本:补 prompt 四道闸作离线／真模型两段门的挂载点范本。 注:两文件均 .md,--no-verify 仅绕基线既有 SpaceHuggers 死链(非本单),蒸馏改动零新增 docs-gate 失败。 Co-Authored-By: Claude Fable 5 --- .agents/rules/engineering-conventions.md | 2 +- .agents/skills/prompt-governance.md | 6 +++++- 2 files changed, 6 insertions(+), 2 deletions(-) diff --git a/.agents/rules/engineering-conventions.md b/.agents/rules/engineering-conventions.md index a453d862..7d802aee 100644 --- a/.agents/rules/engineering-conventions.md +++ b/.agents/rules/engineering-conventions.md @@ -153,7 +153,7 @@ URL 格式：`/{端前缀}/{模块}/{资源}/{动作}`。示例（左列为含 由此，一份契约或一处协议字段要算合入完成，除 schema 本身外必须同时交付两件配套，三件缺一不可： 1. **机器可校验的 schema 载体**——契约以机器能解析、能拿去比对的形式表达（JSON Schema，或承担同等职责的等价物：OpenAPI schema、SDK 的 `.d.ts` 类型声明、Flyway 迁移的结构约束等），不能只有自然语言约定或一个示例文件。 -2. **机器校验器**——一段对候选数据或实现跑出通过或不通过结论、退出码可被 CI 与 pre-commit 消费的程序。现成范本是 `contracts/prompts/check_registry.py`：registry 版本与 `.md` frontmatter 漂移时 exit 1 阻断，既挂 pre-commit 也进流水线。校验器把 schema 从贴在墙上的规格，变成能真拦住提交的门。 +2. **机器校验器**——一段对候选数据或实现跑出通过或不通过结论、退出码可被 CI 与 pre-commit 消费的程序。现成范本是 `contracts/prompts/check_registry.py`：registry 版本与 `.md` frontmatter 漂移时 exit 1 阻断，既挂 pre-commit 也进流水线。校验器把 schema 从贴在墙上的规格，变成能真拦住提交的门。同一形状的门可拆离线／真模型两段：prompt 治理的四道闸（2026-07-04 W-PCI）就是 `contracts/prompts/check_version_bump.py`（闸 0「改正文必升 version」，挂 `.githooks/pre-commit` 门 5 ＋ `.gitea/workflows/contract-gates.yml`，每提交秒级跑、零成本）＋ `contracts/prompts/eval_gate.py`（闸 1~4 真调 MiniMax-M3 判金标集，挂独立 `.gitea/workflows/prompt-eval.yml` 手动 `workflow_dispatch` 触发、单跑 cap ≤¥5，只焊 registry 头部对账认定的 live 面）——离线纪律随提交焊死，花钱的真模型闸按需触发。 3. **负样本进 CI**——至少一组本应被拒的构造（违反必填、类型、枚举或某条业务不变量的输入），与校验器一起常驻 CI。只喂正样本的门等于没验证过它会不会漏放；负样本是校验器自己的考卷，证明它拒得动该拒的东西。 **什么算契约件、评审在哪拦**：凡改动 `contracts/`（八类契约单一事实源，及其 `agent-loop/`、`trace/` 下的 schema）、`-api` 包的跨模块 DTO/VO、事件 schema、SDK postMessage 协议，或任何承担跨端/跨模块/跨版本约定角色的结构（如 game-runtime 内的 host↔游戏装载协议），都算契约件。这类变更的 PR，评审须核这三件是否齐备、且在 CI 里真跑绿（校验器对正样本放行、对负样本拒绝）；缺任何一件即视同契约未完成，不予合入——schema 写得再规整也不例外。它接在既有 contract-first（先改契约再写代码，见 §5 契约对齐）之后：「改契约」这个动作的完成定义，从此含这三件。 diff --git a/.agents/skills/prompt-governance.md b/.agents/skills/prompt-governance.md index 8ccd101d..fcb365ad 100644 --- a/.agents/skills/prompt-governance.md +++ b/.agents/skills/prompt-governance.md @@ -110,7 +110,9 @@ guardrails: [injection-detect, schema-validate, asset-ref-check] | ③ Golden 回归 | 与 `baseline/` 关键字段 diff，防退化 | 泛化自 T-AGC-08 | | ④ 成本/延迟 | token/耗时不劣化 | 评审版 §4.4 | -四闸全绿 → 人工抽检 K 条（主观质量/可玩性）→ 合入。**可玩性 MVP 不自动评分**（结构校验测不了"好玩"），靠人工抽检 + 上线后行为指标反哺下一轮。 +四闸全绿 → 人工抽检 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 ` 或 `--changed --base `）跑闸 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//runs/`，回归基线 `eval//baseline.json`（`--update-baseline` 建，闸 3/4 据此判增量）。**可玩性 MVP 不自动评分**（结构校验测不了"好玩"），靠人工抽检 + 上线后行为指标反哺下一轮。 --- @@ -146,5 +148,7 @@ aigc 新增**无状态原子**：输入 GameConfig → 输出可玩性测试脚 | Golden 集过拟合 | 样本要覆盖典型+边界，bad case 增量补；勿只放"好跑"的样本 | | registry 与运行时不同步 | 部署强制版本校验；DB 镜像只读；改 prompt 必同步 registry.yaml | | Cocos-MCP prompt 当文生代码写 | 它是 agentic 工具编排（多步），不是单次文本；归 studio 编排 | +| 把 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 校验，与内容安全双层链路同治理 |