lili e16c7e833d docs(agents): 蒸馏内部狗粮上线/W-AXIS R1 收口踩坑经验

prompt-governance §11 稳定门在 M3 下 flaky 与治法(anyTerms 同义词补全治本+格式硬约束+几何退避;actor cohort 聚合比 judge 宽松)
gen-path-parity §6.2 跨语言契约版本接缝(Python 切 acceptance/3 必同步升 Node runner /3 否则真浏览器整拒)
staging-ops §2 commit 在途 M 触发 pre-commit 版本漂移闸处置(机械对齐 registry 匹配 frontmatter)+§4 长任务前台串行+孤儿独立复核
ai-development-protocol §4.2 关键 hash 一律主代理独立重算(扩 commit-hash 自验到产物/基线 hash)
均补到既有文件无新建,带本会话实证行号

2026-07-25 19:27:05 -07:00

16 KiB

Raw Permalink Blame History

AI 驱动开发元流程

本文是绘境AI 项目承接任意任务的统一打法：从识别 → 分析 → 评审 → 执行 → 验证 → 沉淀的完整协议。所有 Agent / 工程师在本仓库做事都遵循它。配套硬规则：../rules/engineering-conventions.md、../rules/security-and-reliability.md；事实蓝图：../knowledge/product-and-architecture.md；操作手册：../skills/；目录索引：../README.md。

1. 总流程

flowchart TD
  A[识别任务类型与复杂度] --> B[读 .agents/knowledge 与 docs、docs/memorys]
  B --> C{复杂 / 高风险?}
  C -- 否 --> S[简单路径: 目标→最小改动→验证→报告]
  C -- 是 --> D[Restate 理解: 目标/范围/事实/假设/影响面/风险/验证计划]
  D --> E[评审版 spec: docs/agent-specs/YYYY-MM-DD-topic-review.md]
  E --> F[两轮评审]
  F --> G[执行版 spec: docs/agent-specs/YYYY-MM-DD-topic-execution.md]
  G --> H{需要并行?}
  H -- 是 --> I[子代理拆分: 互不重叠职责 + 共享事实包]
  H -- 否 --> J[实施: 最小改动/复用既有/契约先行/中文注释]
  I --> J
  J --> K[验证: 单测/集成/类型/构建/冒烟]
  S --> K
  K --> L[沉淀回 .agents: 更新 knowledge/rules/skills + 同步 README]

编号步骤：

识别任务类型与复杂度——先判断这是分析/评审/编码/调试/写作中的哪一类，是否复杂、高风险、跨模块、用户可见。
取经验——先读 ../knowledge/ 与 docs/（架构原档）；同类历史任务检索 docs/agent-specs/ 的收口报告与总账 §6 执行记录（留痕层 docs/plans/(旧 memorys 已删,git 可查) 为早期遗留、已停增）。
复杂/高风险任务先 Restate——复述理解，声明：目标、范围边界、已验证事实、假设、影响面（blast radius）、风险、验证计划。
评审版 spec——产出 docs/agent-specs/YYYY-MM-DD-topic-review.md：结论先行，只留背景/目标/非目标/推荐方案/关键权衡/影响面/风险兼容/验收标准/待确认项，多用 Mermaid，降低认知负荷，不写代码级细节。
两轮评审——评审版经两轮评审确认后再进入执行。
执行版 spec——产出 docs/agent-specs/YYYY-MM-DD-topic-execution.md：目标与范围边界、前置条件、涉及模块与文件路径、数据流与依赖、接口/数据契约、关键实现步骤、边界失败路径、验证方法、完成条件、回滚策略。不预写不可验证的代码细节。
（可选）子代理拆分执行——见 §4。
实施——最小必要改动、复用既有模式、契约先行、全中文注释、可追溯日志。
验证——见 §5；无证据不得声称完成。
沉淀——见 §6，把有价值的产出回写 .agents 并同步索引。

简单、低风险、局部、易验证的任务走简单路径：目标 → 最小改动 → 验证 → 报告，不必走全套 spec 流程。

2. 任务类型分支

类型	打法	产出形态
分析	第一性原理 + 金字塔原理拆解；给出问题、边界、假设、风险、推荐路径	结论先行的分析结论
评审	按严重度排序，每条给：影响 / 根因 / 修复建议	问题清单（先严重后次要）
编码	最小改动 + 复用既有模式 + 中文注释 + 验证；禁止顺手重构无关代码	可编译可验证的变更
调试	症状 → 复现 → 观察 → 缩小范围 → 根因 → 针对性修复 → 验证 → 清理临时调试代码	根因 + 修复 + 验证证据
写作	可评审、可直接落地的内容，多用表格与清单	即可入库的文档

2.1 简单路径 vs 全流程的分流判据

命中任一下列信号即走全流程（Restate → 评审版 spec → 两轮评审 → 执行版 spec）；全部不命中才走简单路径：

信号	判据
跨模块	改动牵动 ≥ 2 个 game-module，或触达 `-api` 契约 / 事件 schema
用户可见	改变产品端/管理端行为、API 出入参、SDK 对外签名
高风险面	涉及鉴权、支付、合规门禁、沙箱、幂等、分布式一致性（见 `../rules/security-and-reliability.md`）
数据结构	新增/变更 DO/表结构、Flyway 迁移、Redis/MQ 数据格式
不可逆	删除字段/接口、数据迁移、线上配置变更

简单路径仅适用：单文件局部改、纯文案/注释、补一个不改契约的单测、明确无副作用的 bugfix。拿不准时按全流程走。

2.2 本项目典型任务的落法（示例）

任务	类型	路径	关键动作
新增一个 game-module	编码	全流程	执行版 spec + 契约先行；落地照 `../skills/add-business-module.md`
给 aigc 加一个生成失败错误码	编码	简单	在 `-api` 错误码段登记 + 单测，不动契约
排查"生成任务一直 QUEUED"	调试	简单→视根因	先查 RocketMQ 异步 gen 队列消费者 / cheap-worker（AgentScope）Service 日志复现，再定位
评估是否引入 ClickHouse	分析	全流程	第一性原理 + 评审版 spec，结论先行
审查一个支付回调 PR	评审	——	按严重度列问题；重点幂等/状态机/乐观锁

2.3 agentic 设计/评审任务的强制过尺（2026-07-05，创始人拍定）

凡设计或评审生成运行时的 agent 席位划分、context 装配、prompt 结构、工具面、多 agent 协作、goal-loop 自治交付、创作者交互面，必须按 ../skills/agentic-seat-context-design.md §8 检查单过尺：设席八问 / 注入五查 / 场景四要素 / "规范进 prompt"先问模板与门。评审此类设计档时，把该检查单当评审尺逐条对；设计档内〔提案〕机制落地前须逐条验证可行性（该 skill 是需求基线，不是架构 SoT）。全新 agentic 子系统首次设计前，若尚无需求基线，先按该 skill §10 探针方法跑一轮第一人称需求探针产基线再设计（2026-07-06 立 W-PROBE；默认建议、升强制与否待创始人拍；探针对象排期唯一登记处 = 作战清单 W-PROBE 单）。

3. 证据规则

区分三种信息，不得混为一谈：

已验证事实——来自代码、文档、日志、测试、运行输出。
推断——基于上下文的合理判断，未直接验证，须标注"（推断）"。
假设——为推进临时采用，须后续确认。

铁律：

凡可只读核实的，先查代码/文档/配置/测试/日志，关键歧义仍在再问用户（只问影响决策的最小必要问题）。
没有验证证据，绝不声称"完成 / 修复 / 通过 / 无问题"。

4. 子代理使用规范

规则	说明
边界不重叠	拆分为互不重叠的文件 / 职责边界，避免写冲突（一个文件只由一个子代理负责）
共享事实包	为每个子代理提供同一份"事实包"（如 `../knowledge/` + 契约文件），保证多代理产出一致
并行前提	并行仅用于无共享状态、无顺序依赖的任务；有依赖的按序执行
模型档位	按裁量点三档分流（硬性成本规则，2026-06-11）：零裁量机械类→Haiku（固定配方执行/轮询盘点/证据搬运，结果可便宜验证）；有裁量的开发/设计/评审/调试→Opus（子代理默认档）；仅最高复杂度→Fable（架构裁决/主 spec 终裁/跨模块疑难根因；其新 tokenizer 同内容多 ~30% token，实际成本 ≈ Opus 2.6 倍）。派发子代理/Workflow `agent()` 必须显式传 `model`，禁止静默继承主会话档位（主会话为 Fable，继承=全员烧最贵档）；拿不准或涉契约/不可逆操作升一档，由验证门兜底低档错误；Sonnet 为中间档（Haiku 质量不够且 Opus 过杀时用）

契约先行 + 各工位 mock 对方接口独立开发，是本项目并行解耦的基础，见 ../skills/contract-first-development.md。

4.1 Fable 档适用清单（本项目具体映射，2026-06-11）

上表「模型档位」行是通用判据；本节把"哪些建设对象必须升 Fable"落到本项目具体功能/实现（Doc B T-id 可溯）。注意区分：本节只管开发期模型分流；产品侧（生产调用链）档位红线另见 ../knowledge/tech-decisions.md §4「生成模型档位」——生产主链路禁旗舰档，两者勿混。

① 架构单行门——设计终裁必须 Fable（实现仍 Opus）。共同特征 = 裁量大 × 错了不可逆 × 跨模块：

对象	涉及（Doc B）	不可逆点
资金域整体	trade T-TRD-01..12 + pay 接线 + 广告计费反作弊正式项（Doc B §11 📌注记）	钱 + 对抗域，分账/对账/打款错了直接资损
多渠道统一转译引擎	T-RT-26 + 渠道矩阵 T-RT-21..24/31/32	渠道格式 = 外部硬契约，引擎定错全渠道返工
agentic 编排引擎	T-STU-05/10 + T-AGC-18 DAG	~~全项目最重自研框架~~ 已终裁不自研（HJ-AGI-001→HJ-AGI-002→2026-06-25 框架收敛覆盖：生成框架统一收敛 AgentScope、三档按 AI 参与深度分（引擎随复杂度选 LittleJS / Phaser）；SAA / dify / coze 降为最低优先级，留作远期可插拔适配验证；Fable 只设计五资产契约边界与适配层；T-AGC-18 自研 DAG 引擎作废）
商用授权链域模型	T-IP-02/03 + T-CMP-12 锁风门聚合语义	资产积累后数据模型无法重构，且与法务耦合
推荐 + A/B 实验框架	T-FED-12/13（增长期）	离线/在线一致性、数据闭环正确性 = 护城河承重墙
一次性架构事件	monorepo→三仓拆分、MySQL→ClickHouse 迁移、沙箱安全边界对抗评审（T-RT-04/05/14 + T-CMP-26）	全仓级影响 / 安全边界

② master-spec 终审票：两轮评审中的最后一票在高危波次用 Fable——M4 变现波、转译引擎波、推荐波、biz 真实化波（电子签章/CRM/报价等外部契约对接）。反例：黄金模板克隆波（如 Wave4 community/biz 骨架）Opus 评审即可。

③ 跨模块疑难根因（按需升档，不预算）：症状横跨 ≥3 层（前端/桥/后端/构建链）或 Opus 两轮取证无果才升（先例 = 回包链路 v-for ref 全断案）；例外直升：并发/幂等/MQ 重复消费类数据一致性 bug（错果不可逆）。

④ 生产数据→Fable 离线分析→系统升级（常设用法，最高杠杆）：Fable 不进生产调用链，按"波次收口/批次/决策点"节奏喂生产数据做横切归因，产出必须蒸馏回 .agents/contracts/prompts（闭合 §6 复利沉淀）：

生成失败横切归因（batch 产物 + T-TEL-17 失败聚合）→ prompt registry / 模板 schema / 校验规则升级——成功率 80%→90% 爬坡主引擎（agent-loop QA 闭环/C6.1 对抗评审的正式化）；
质量分/推荐审计（T-TEL-20 解读层）→ 排序权重 w1..w6 的劣化与可刷性分析 → 调参建议；
单位经济复盘（new-api 成本账 + eCPM/分成实测）→ 迭代 docs/mvp/单位经济敏感性模型.md 与定价/档位决策；
反作弊态势（AnomalyFilter 拦截日志）→ 对抗者视角找绕过路径 → 规则升级；
模型评估矩阵争议样本终裁（judge 通道）。

前提红线：喂数前先聚合 + 脱敏（守 T-CMP-30 日志脱敏、T-CMP-33 最小化采集）。

升档触发判据（命中任一即升 Fable）：① 决策锁死 ≥3 模块或外部硬契约/资金/法务；② 错误不可逆（资损/数据模型固化/安全边界）；③ Opus 两轮取证无果的机制级疑难；④ 高危波次 master-spec/对抗评审终审票；⑤ 生产数据横切归因分析。

明确不升档：模板克隆、CRUD/admin 页面、渠道 adapter 批量复制（引擎定稿后）、批量验证、UI 走查执行——Opus/Haiku 照常，显式传 model 红线不变。

4.2 执行子代理的产出验证纪律（SDD 实录，2026-07-02）

派子代理执行编码任务、尤其走 subagent-driven-development 时，子代理回报的 DONE 是未验证声称，controller 不得据以标记完成。一次实录：子代理报「测试 8/8、已提交 commit 6837c8ee」，实际测试是 2 failed，那个 commit 在 git 里根本不存在——改动只落在工作树、从未提交。

五条硬纪律：

每个报 DONE 的 commit 自验：git rev-parse HEAD 与回报的 hash 对得上，真跑关键测试（不信回报的通过数），红线级改动亲读 diff。
生成 review 包时的 hash 校验是造假第一道自动拦网：编造的 commit hash 不在 git 里，一 git 就报错。把「生成 review 包 / diff」放在标 complete 之前当强制步，能第一时间撞破。
造假子代理弃用、不 resume：它带着「我已做完」的错误认知，resume 容易再造假；换 fresh 子代理，只补 controller 诊断出的精确缺口，prompt 里明写诚实红线（回传真实 HEAD 与原样测试输出，没全绿一律报 BLOCKED 而非 DONE）。
fix 子代理让其自证：要求「删掉修复→缺陷用例必红」这类反向验证，证明测试真在测行为而非桩自证，controller 再复核一遍。
关键 hash 一律主代理独立重算，绝不抄子代理报的值：不止 commit hash——runtime-tree.json 的 sha256、artifacts.sha256、baseline 的 promptBodySha256 这类产物/基线 hash，子代理报的长度或值也可能是错的（一实录：子代理报 runtime-tree hash 为 62 位却称 64 位）。主代理对这些 hash 必须自己 sha256sum / git rev-parse 重算比对，不直接采信报值；git rev-parse 验 commit hash 存在是反造假第一道（第一条），产物 hash 同理——报得出 ≠ 算得对。

5. 验证

收尾前跑最相关的验证，并在报告中给出证据：

改动行为的单元测试；涉及 DB/MQ 的集成测试（Testcontainers）。
类型检查 / lint / 构建（后端 mvn test/mvn verify；前端一律 npm run build——vue-tsc --noEmit 为假门禁不得作验证依据，mini-desktop 构建 game-studio 必须 --mode staging，详见 ../skills/staging-ops.md §4；SDK pnpm test:size 体积检查）。
必要的冒烟测试（核心链路）。
跑不了的，说明原因并给出下一步验证建议。

测试分层与覆盖率要求见 ../rules/engineering-conventions.md §7。

6. 与 .agents 的闭环沉淀

波次收口走唯一清单：../skills/wave-close-checklist.md（总账+表头 / 作战清单+归档 / 回填 / .agent / 蒸馏 / 索引 / 编排资产入库，七步）。本节是其中"蒸馏"一步的细则。

每次有价值的交付后，按"维护即收尾"原则回写：

判断新增 vs 更新：全新主题 → 新增文件；已有主题补充/修正 → 更新现有文件（先查重，不造重复）。
回写对应层：事实 → knowledge/；硬约束 → rules/；操作手册 → skills/；流程 → workflows/。
同步索引：任何结构性变更（增/删/改名）同步更新 ../README.md 的文件清单与交叉链接（统一相对路径）。
过时即处理：信息失效立即修正或删除；与代码/文档冲突时以已验证事实为准。
询问是否落 memorys：关键任务信息按需持久化到 docs/plans/(留痕层;旧 memorys 已删,git 可查)（描述 10–20 字），供同类任务复用。

7. 停止规则

能回答核心问题即止，不为润色措辞、堆砌细节、展示分析过程而扩张范围。
最小方案优先：够用就不引入更复杂设计；不为一次性代码建长期抽象。
关键证据缺失时，点明缺口；只有当它真会影响决策时，才问最小必要的问题。

16 KiB Raw Permalink Blame History Unescape Escape