games-development-ai/docs/agent-specs/2026-06-17-agent-specs深度重构-plan.md

agent-specs 深度重构 · 压缩计划（2026-06-17 · 待创始人审批）

类型：review-first 计划（批准前零改动，仅本计划档已落）。分析=10 主题簇 opus fan-out 读全 42 档（1.1M tokens）。 目标：把 docs/agent-specs 从「按时间堆积的 review/execution/verdict 流水」收敛成「按子系统（产品功能×技术模块的交集），每主题一份 canonical 档，只留最新架构/目标/设计/现状，砍历史与过程」。

---

0. 结论先行

• 现状（量化"太多太乱"）：顶层 42 档 / 7441 行，同一主题散成 review+execution+verdict+runplan+report 多型重复；人读不懂、AI 接手超载。
• 目标：收敛为 ~10 份 canonical 档 / ~1400 行（↓81%），每份=一个子系统的「一页结论→目标/非目标→现行架构→现状(done/在飞/待办)→关键指针」，砍掉：演进流水/逐轮评审 transcript/逐 commit 过程/取证日志/已被 supersede 的旧方案（留 git 历史 + _archive/）。
• 42 源档处置：FOLD 进 canonical 24 / ARCHIVE 入 _archive 12 / KEEP 独立 3 / DELETE 2 / prompt治理体系-execution.md（无日期活档·Prompt 第8契约）= KEEP 直接转正 prompt canonical（评审 M1 补漏：原 ls 2026-* 口径漏了这份在飞档）。
• ⚠️ 头号约束：生成域 3 簇含他 session 06-17 未提交在飞 WIP（固定架构 review+execution、生成主线对话 v1/生命周期 v2、多session总账重写）——红线不擅动 → 拆两波：settled 域现在做，生成域待协调。
• 待你拍 5 项（§9）：① canonical 粒度 ② 生成域 WIP 怎么办 ③ 删 vs 归档 ④ 命名约定 ⑤ 分层定位。

---

1. 目标结构与分层（先定框架）

1.1 四层文档体系（canonical 档的定位）

层	位置	职责	本次动作
基线 WHAT/HOW	docs/architecture/ Doc A/B/C + 技术决策版	产品需求 / 13 模块卡片 / RTM / 架构基线	更新对齐现行（§5）
蒸馏速查	.agents/knowledge/*	AI 日常一句话事实	更新+补术语+加 canonical 指针（§5）
子系统 canonical（本次新建）	docs/agent-specs/*	每子系统：最新架构+目标+设计理由+现状+指针	新建 ~10 份，取代 42 流水档
跨线状态	docs/mvp/MVP进度总账.md	计划↔完成↔待办↔执行记录	更新+§6 波次史压缩（§6）
历史	docs/agent-specs/_archive/ + git	取证账本/收口报告/已死档	归档落点

分层铁律：canonical = 子系统完整可读档（深过 knowledge 一句话、窄过 architecture 全局）；不与 knowledge/architecture 双写——重叠处 canonical 是 SoT，knowledge/architecture 留速查+指针。

1.2 命名约定（§9-Q4 待定）

建议：canonical 档=无日期 + 主题名（活档持续更新，不是时点 spec）。当前混用（GEN-前缀/dated/无日期）→统一。引擎-conventions §10 同步加「canonical 活档」命名条。

---

2. 目标 canonical 档清单（要创建什么 + 装什么）

每份 ≤150 行；章节大纲来自 10 簇蒸馏。域分组便于 _index 导航。

生成域（核心子系统，4 档——§9-Q1 是否再合并）

canonical	~行	章节大纲	波
生成主线.md(HJ-GEN-001)	150	0一页结论/1目标·非目标/2现行架构(三级生成+固定架构+SAA studio)/3质量体系(九门harness+三层质量+救场阶梯)/4生命周期与契约(源项目模型+第9契约组)/5现状/6决策理由+指针	⚠Ph-B
agentic编排-SAA裸图.md(HJ-AGI-002)	140	0现状+决策口径/1为什么SAA-only/2现行架构(图+四类负载)/3六不变量/4落地要点(指skill)/5两治理铁律(split-brain)/6与orchestrator边界/7现状	Ph-A
开闸验收门-W-G1.md	150	0现状banner/1开闸模型6门排序/2组A控制平面+GP9/3组B 9d-D11-D9/4组C首局门/5 G0G1前置/6 follow-up	Ph-A
固定架构与SAA-agentic-studio.md	150	0是什么+范式血缘/1固定vs可填边界+2D3D/2 agent列表拓扑/3救场阶梯+硬观测/4八契约/5缓存+classify/6两开发线切分/7现状	⚠Ph-B(他session在设计)
prompt治理.md(Prompt 第8契约)	既有	Registry/load-inject/门禁/HITL 治理（评审 M1 补漏：现存 prompt治理体系-execution.md 已是无日期活档=canonical 形态，KEEP 直接转正，至多去 -execution 后缀）	Ph-A(KEEP)

其余子系统（settled，6 档——可现在做）

canonical	~行	章节大纲	波
引擎与运行时.md	135	0选型落锤/1为什么LittleJS+复议权/2模板哲学(术语纠偏)/3两层装载契约(Mermaid)/4 engineBundle交付+能力边界/5现状/6指针	Ph-A
渠道发行.md(HJ-CH-001)	135	0定位+横幅/1分工理由/2合规闸门/3 Channel Runner+红线/4生产管线三层/5引擎竞标C-A/C-B/6现状/7指针	Ph-A
studio前端设计体系.md(HJ-FE-DS-001)	140	1定位现状/2核心判断/3创始人5决议/4现行架构(token两层+i18n+主题)/5契约/6 vs demo勿误砍/7现状债/8指针	Ph-A
变现与单位经济.md	145	0硬边界/1两平面两钱包/2收益闭环④/3 new-api成本源/4单位经济模型/5资金一致性红线/6现状/7指针	Ph-A
战略与合规活账.md	110	0薄索引/1四雷收口/2三线变现排序/3合规闸门(指A1看板)/4经济模型(指敏感性模型)/5 demo纠偏/6待拍板/7修订清单	Ph-A
产品路线图与协作.md	150	0定位/1现状/2架构基线/3三阶段(MVP=Ph1)/4产品功能完成度/5模块完成度/6 Objective优先级/7多session协作/8集成节奏/9日历闸门/10待拍/11即起动作	⚠Ph-B(含多session总账WIP)

---

3. 源档处置总表（41 档：删什么 + 为什么）

处置义：FOLD=活内容蒸馏进 canonical 后删源(git 历史+canonical 留存)；ARCHIVE=移 _archive/(取证账本/收口报告有回查价值)；DELETE=直接删(过期/无意义)；KEEP=独立保留。

簇	FOLD→删(24)	ARCHIVE→_archive(12)	KEEP(3)	DELETE(2)
生成主线	总体架构-review·WG1基准·传承演进·任务清单普查·生命周期v2	并行编排(已桩)	开闸接线-review(里程碑)	对话生成修改素材v1(被v2 supersede·过期)
agentic-SAA	目标架构-review·round3-verdict·退役登记	form①-runplan·组B-execution	SAA能力API-dossier(逐键证据底座)	round2-verdict(已桩·无意义)
引擎运行时	—	终裁包·W-T1b-Runner·runner-v2-arc·T1b-β收口报告(4档全归档,精华已抽)	—	—
W-G1开闸	review·组A·组B·组C·G0G1-verdict(5档全FOLD)	—	—	—
渠道	渠道适配判定·W-CH-α-spike	—	channel-spike/(代码资产)	—
studio	视觉体系-review·studio-vs-demo	视觉体系-execution	—	—
固定架构	review·execution(⚠他session WIP·Ph-B)	—	—	—
变现	newapi计费·W4单位经济·消费侧钱包	M4变现真实化-review	—	—
战略合规	—	架构三向审计·demo审计(2档归档,结论抽canonical)	—	—
产品路线图	多session总账(⚠WIP)·产品功能census	产品开发路线图-review	—	—

另：治理/过程档 agent-specs目录治理-review、文档整理-plan(上轮) → ARCHIVE（治理留痕）。子目录 generation-spike/·channel-spike/·tier1-engine-spike/·模型评估矩阵/·agent-loop-v1/(orchestrator 白名单) → 维持（spike/证据/活工具箱，不在本次）。

---

4. 新 _index 长这样（活地图重构）

# agent-specs 活地图（canonical 档导航）
> 每子系统一份 canonical 档=该域 SoT;读它即知现行真相。历史见 _archive/+git。

## 生成域
- 生成主线.md — HJ-GEN-001 生成子系统总纲(架构/质量/生命周期/现状)
- agentic编排-SAA裸图.md — HJ-AGI-002 SAA 编排基建
- 开闸验收门-W-G1.md — 一句话开闸 6 门
- 固定架构与SAA-agentic-studio.md — 范式落地+8契约 [⚠在飞]
## 引擎/运行时
- 引擎与运行时.md — LittleJS+Runner v2 装载链
## 渠道发行
- 渠道发行.md — HJ-CH-001
## 前端
- studio前端设计体系.md — HJ-FE-DS-001
## 变现/战略
- 变现与单位经济.md / 战略与合规活账.md
## 跨线
- 产品路线图与协作.md — 三阶段/完成度/多session [⚠含WIP]

## 活工具箱/spike(白名单保留)
- agent-loop-v1/orchestrator/ · generation-spike/ · channel-spike/
## 历史
- _archive/(取证账本/收口报告/已死档,按文件名 git 可查)

删除当前 _index 的 §2 supersede 链表（已死档全归 _archive，不再需要"勿信"清单）+ §3 治理流水（移 canonical 或 _archive）。

---

5. 核心设计档怎么更新（你问的第 7 项）

原则：canonical 落地后，architecture/knowledge 不再重述细节，只保速查+指 canonical；同时把各 canonical 蒸出的"现行真相"回灌这些基线档。

档	更新动作
.agents/knowledge/tech-decisions.md	§1.1 加指针→引擎canonical；§4 补"范式=游戏全生命周期源项目+固定架构+cheap填槽+SAA studio"基座、SAA-only 固化结论(待对比N=17)；确认 Dify/OpenGame=long-term、MQ/Nacos=future-state 无回潮
.agents/knowledge/glossary.md	补词条：固定架构/游戏定义模型(实体-组件-行为-场景-规则)/SAA agentic studio/源项目工件/九门harness/H_progress/救场阶梯/游戏宿主装载契约(game-host.d.ts)/engineBundle；玩法模板vs游戏模板纠偏已在
.agents/knowledge/product-and-architecture.md	模块状态对齐现行(aigc=agent写码+SAA+generic / runtime=LittleJS+Runner v2+engineBundle / studio=设计体系收口)；加 canonical 指针
.agents/knowledge/mvp-scope-and-milestones.md	W-G1 开闸 6 门入 MVP 范围/验收；三阶段(MVP=Phase1)口径
docs/architecture/技术架构与模块.md(Doc B)	13 模块卡片状态字段对齐现行(各 canonical currentStatus 回灌)
docs/architecture/技术决策版.md	已对齐(上轮玩法模板);加各域 canonical 指针,大型决策史段可瘦身指向 _archive
.agents/skills/{cheap-model-game-generation,saa-graph-orchestration,add-game-template,runtime-and-multichannel}.md	各簇 keyDesignDocImpact 列的补充(固定架构范式/救场阶梯/SAA studio拓扑/玩法模板onboarding)
.agents/rules/engineering-conventions.md §10	加「canonical 活档」命名/分层约定（无日期主题名 + 一主题一活档）

---

6. R&D 总账怎么更新（你问的第 8 项）

1. §0 一句话现状 + §1 里程碑账：用各 canonical 的 currentStatus 回灌刷新（生成主线/引擎/变现/studio/W-G1 现状一句话）。
2. §6 执行记录（波次史）⚠️评审 M2 修正：不可压删！ §6 携带各闭线波"过没过验收门"的唯一综合证据（accept 19/20=95%≥80%门 / cal acceptRate=1.0 infra=0 / 逮修 3 真缺陷 / DB 行级实证），git log 只有 commit message、没有这些判决性综合。压成指针=不可逆销毁护城河取证账本（与 §8-5"不丢取证"自相矛盾）。修法=整段搬入 _archive/总账-波次史归档.md（原表一字不丢），总账正文 §6 仅留「M0-M5 里程碑摘要 + 一句『逐波收口验收证据见归档』指针」。瘦身=视觉折叠，底层取证零销毁。
3. §2 模块矩阵：状态对齐 Doc B 回灌。
4. 口径：现状一句话指向对应 canonical（总账=跨线状态，canonical=子系统详情，不重复）。

---

7. 执行波次（批准后；红线驱动拆波）

Phase A（settled 域，现在可做）：建 7 canonical（agentic-SAA / 引擎运行时 / W-G1开闸 / 渠道 / studio / 变现 / 战略合规）→ 删/归档其已提交源档 → 重构 _index → 更新核心档 + 总账。全部源档已 committed，零 WIP 纠缠。 Phase B（生成域，待协调）：生成主线 / 固定架构 / 产品路线图——含他 session 06-17 未提交 WIP（固定架构×2、对话v1/生命周期v2、多session总账重写）。红线：不擅删/改他人在飞档。待其 commit+设计落定后，或经你授权协调，再建这 3 canonical + 删 WIP 源。Phase A 的生成主线先建占位骨架引 WIP，不删 WIP。

---

8. 风险 / 红线

1. 阶段一只读：本计划批准前零改动。
2. 他 session 在飞 WIP 红线：4 个 06-17 未提交档（固定架构×2/对话v1/生命周期v2）+ 多session总账(被重写) = 另一 session 活跃设计中 → Phase B 协调，Phase A 不碰。
3. FOLD=删源前必先写好 canonical 并验活内容无丢（livingNuggets 清单逐项核）；删用 git rm（git 历史可恢复）或移 _archive（§9-Q3）。
4. 可逆：全程 git 跟踪；canonical 先建、源后删（同一提交内先 add canonical 再 rm 源，评审验过才提交）。
5. 不丢决策史：FOLD 档的"为什么"精炼进 canonical §决策理由；逐轮 transcript/取证留 git。
6. 多 session 共享树：守卫式 add，不扫他人 untracked。
7. 波次归属以 git tracking 实判为准（评审 S1）：workflow 的 isInFlightWIP 字段两向都不可信（agentic 簇误标 WIP 实则源档全 committed / 产品路线图簇误标 settled 实则含 多session总账 被重写）→ 执行 agent 必须 git status 核 untracked/modified 划波，不读 JSON flag。

---

9. 待创始人拍板（5 项）

• Q1 粒度：生成域 4 档（主线/SAA/开闸/固定架构）—— 保持 4 份（各有独立关切）/ 进一步合并为 1-2 份「生成大档」（更严格"一域一档"但单档变厚 ≥400 行）？其余 6 域已是一域一档。
• Q2 生成域 WIP：固定架构/对话/生命周期/多session总账=他 session 06-17 在飞 —— Phase B 待其落定再做（推荐，守红线） / 我现在协调那 session 一起做 / 你确认这些已定稿、当 settled 直接合并？
• Q3 删 vs 归档：FOLD 源档 → git rm（靠 canonical+git 历史，最干净，推荐） / 移 _archive（多留一份可浏览）？ARCHIVE-history 12 档 → _archive / 也 git rm（更激进）？
• Q4 命名（评审 S5：我自拍·知会，不占你决策位）：canonical = 无日期主题名（prompt治理体系-execution.md 即既有先例）；除非你否决，我直接采用。
• Q5 分层：确认 canonical=子系统 SoT、architecture/knowledge 降为速查+指针（不双写）—— 认可 / 调整？
• Q6 _archive 与放置（评审 S5 补）：① _archive/ 现 66 档（+本次归档）—— 维持（git 可查，但只增不减再膨胀）/ 也清理（git 历史是真 archive，最激进）？② canonical 放顶层（推荐，对齐你"docs/agent-specs 下一档"）/ 收子目录 _canon/？