games-development-ai/docs/agent-specs/2026-06-20-设计文档域化重构-review.md

设计文档域化重构 · 设计评审版 v2（2026-06-20 · 过双评审后修订 · 待创始人签字）

类型=review-first 设计评审版(批准前零改动,仅本档已落)· 非 canonical 范围=重组 docs/architecture/ + docs/agent-specs/ 的设计文档内容;必然连带改动(指针/治理门/入向链接)同 commit 纳入,外溢到 .agents/ + docs/mvp|plans(详见 §2.5/§4) 决策(owner 已定 5 项)=① 全量重写 ② docs/architecture/ 为新 canonical 根 ③ 6 域生命周期(后端/运维瘦主档+指针)④ 生成域本次纳入 ⑤ 必然连带改动纳入同 commit 取代=取代 2026-06-17-agent-specs深度重构-plan.md 的「architecture↔agent-specs 分两层」,并接管其下游连锁(§6) 评审=2026-06-20 Codex + Opus 双评审已过(发现项处置见 §8);引用的 §6.8/§10/§11 均指 AGENTS.md,§10.x 指 .agents/rules/engineering-conventions.md 读法=结论先行 · 无代码级细节 · 执行计划(事实清单行/§10 新文本/逐文件改动)另出(writing-plans)

---

0. 结论先行

• 做什么:把散落在 docs/architecture/(7 档/3467 行)+ docs/agent-specs/(顶层 ~29 设计档)的设计文档,全量重写为一套 4 级域树(L1 总索引 → L2 域主档(6)→ L3 模块子档 → L4 详档),落 docs/architecture/ 单根,按产品生命周期 6 域组织,只留一份真值。
• 6 域:产品 / 架构 / 后端 / 前端 / 运营 / 运维;后端·运维=瘦主档+指针(有最低自洽内容,非纯链接转发,见 §2.2);生成引擎=架构域旗舰模块子树。
• 文档风格(大厂标准 · 给人看的):输出设计档为人读散文、多图(Mermaid 优先)、少黑话(专名首现即解释)、单档 ≤ 2000 行(超则拆 L3/L4);面向产品/新人/外部读者,非 agent 速查(详见 §2.7)。
• 现状(量化"太多太乱"):架构基线 系统概要设计-技术决策版 独占 1562 行;生成域散成 总体架构/固定架构 exec(698 行)+review/SAA/引擎运行时/对抗裁决/OpenGame/WG1/lifecycle×2/多session总账…… 同主题 review+execution+verdict 多型重复。
• 源档处置:FOLD≈24 / ARCHIVE≈11 / KEEP+迁移 1 / SPLIT 2 / POINTER 1(详见 §2.3,含完整性机校)。
• 全量重写≠白纸:每域配结构化「源档事实清单 → 回灌核对门」(§2.4),硬事实漏一条即红线。
• ⚠️ 头号事项 = 连带 blast radius:architecture 当 canonical 根,与 §10.5(line 284)现行判层序 canonical(agent-specs)＞knowledge＞architecture(基线) 对立,必须同 commit 改写 §10.5/§10.6/§10.7 + ~17 处入向引用 + doc-organizer.sh(枚举见 §2.5)。不改→死链 + 治理门与新结构互打。
• 生成域权属(更正 v1 错误):v1 误把"生成域撞 6c6g 在飞"列为头号约束。_index.md line 40 明写「SAA 2026-06-18 交本 session 独管;在飞红线解除」(commit 1101d016)——红线已解除,生成域可直接重组,双评审仅作质量门(非跨 session 合流点)。
• 诚实声明:这是 72h 内对同一批档的第二次结构搬迁(06-17 刚把内容蒸进 agent-specs canonical,本次反向搬回 architecture 并反转分层)。理由=owner 选 architecture 单根以彻底消除"三处 SoT 并存";本次接管 06-17 全部下游连锁(§6),不留半态。

---

1. 目标 / 非目标(范围边界)

	内容
IN·内容重组	docs/architecture/ 7 设计档 + docs/agent-specs/ 顶层 ~29 设计档(8 canonical + 生成域设计链 + dated trace)
IN·必然连带(同 commit · 只改引用/门,不重组其内容)	.agents/rules/engineering-conventions.md(§10.5/§10.6/§10.7)· .agents/knowledge/* canonical 指针与蒸馏来源 · .agents/rules/security-and-reliability.md · 6 份 .agents/skills/* 路径 · .agents/tools/doc-organizer.sh(SPECS=)+ doc-organizer.md · .agents/README.md · docs/mvp/{可行性方案16周-波次映射,全成本收益测算模型-v2,MVP作战清单,MVP进度总账} · docs/plans/2026-06-18-001-* · AGENTS.md §3.2-3.4/§4/§5 · _index.md(含修 line22↔line40 自相矛盾)
OUT(不动)	.agents/ 各文件的业务蒸馏正文(只改其指针/路径)· docs/ip(法律备案/品牌门白名单)· docs-design · docs/brainstorms(实测无入向引用)· agent-specs 的 spike 子目录(白名单,见下)· _archive/ 既有内容 · 任何代码逻辑
白名单 spike(原地保留)	2026-06-09-agent-loop-v1/ · 2026-06-09-generation-spike/ · 2026-06-10-模型评估矩阵/ · 2026-06-11-tier1-engine-spike/ · 2026-06-11-前端接线创作链路UI走查/(走查证据)· 2026-06-12-channel-spike/
非目标	不改 .agents/knowledge 蒸馏定位;不新建 docs/design/;不硬删(清理=git mv 归档,留 history)

"不动"语义澄清(消 v1 §1↔§4 矛盾):OUT 目录内容/结构不重组,但入向路径引用允许且必须随搬迁同步修(改一行链接 ≠ 重组该目录)。

---

2. 推荐方案

2.1 四级骨架 + docs/architecture/ 为根

docs/architecture/
  README.md                 # L1 总文档索引(唯一入口)
  产品/  README.md(L2) + 需求清单.md 需求模块映射.md 护城河话术.md 商业定位.md(L3)
  架构/  README.md(L2 · 分层/技术决策/13 模块)
        生成引擎/           # ★L3→L4 旗舰模块子树
          README.md         # 子树主档(承「生成主线架构演进路线」)
          固定游戏架构.md  SAA编排.md  引擎与运行时.md
          验收门-W-G1.md  prompt治理.md  设计合理性裁决.md
          OpenGame对照.md  WG1基准.md  SAA能力API-dossier.md  开闸接线.md
  后端/  README.md(瘦主档:边界声明+为何薄+指针→架构/13 模块)
  前端/  README.md(L2 · 承「studio前端设计体系」)
  运营/  README.md(L2) + 变现与单位经济.md 渠道发行.md 合规闸门.md(L3)
  运维/  README.md(瘦主档:环境/部署/smoke + 指针→deploy/)
  _archive/                 # 仅 architecture 源档退役(留 git 痕)

graph TD
  IDX["L1 总索引 README.md"] --> P[产品]
  IDX --> A[架构]; IDX --> BE["后端·瘦"]; IDX --> FE[前端]; IDX --> OP[运营]; IDX --> DO["运维·瘦"]
  A --> GE["★生成引擎 旗舰子树"]
  GE --> GE1[固定架构/SAA/引擎运行时]; GE --> GE2[验收门/prompt/裁决/OpenGame/WG1]
  BE -.指针.-> A; DO -.指针.-> A

• 归档落点规则(消 Codex Major-3 歧义):architecture 源档退役 → docs/architecture/_archive/;agent-specs 源档退役 → docs/agent-specs/_archive/(各归各家,引用修复与验收脚本不分叉)。
• agent-specs/ 重组后只留:6 白名单 spike + _archive + 瘦身 _index.md(settled 子系统指向新根;自身只索引 trace/spike)。canonical 内容迁入域树、原档 git mv 入 agent-specs/_archive。

2.2 六域定义

域	阶段	主档职责	厚薄
产品	需求/定位	需求、RTM、商业定位、护城河	厚
架构	架构设计	分层、技术决策、13 模块、生成引擎子树	最厚
后端	服务实现	13 后端模块服务视角	瘦主档+指针
前端	端实现	studio/admin 设计体系	中
运营	上线/变现	变现与单位经济、渠道发行、合规闸门	中
运维	部署/可用性	环境、部署、smoke、可用性	瘦主档+指针

瘦主档防空壳门(消 Opus m1 孤儿风险):后端/运维瘦主档不得是纯指针页,至少承载三段实质内容——①该域在本项目的边界声明 ②为何薄(内容主体在何处)③权威源指针。§5 验收设最低正文行数门。

2.3 旧→新映射(doc 级 · 处置)

处置	源档 → 落点
FOLD·产品	产品需求清单 / 需求模块映射 / 护城河对外话术 / 产品开发路线图
FOLD·架构	技术决策版(1562 行·拆解)/ 技术架构与模块(Doc B)/ 开发团队版(架构段)
FOLD·架构·生成引擎	生成主线架构演进路线(→子树主档)/ 固定架构 exec+review / agentic编排-SAA / 引擎与运行时 / 总体架构-review / WG1基准 / 对抗裁决 / OpenGame对照 / prompt治理 / 开闸验收门-W-G1 / 开闸-一句话入口接线-review(→生成引擎/开闸接线.md)/ 生命周期 v2(范式原则)
FOLD·前端	studio前端设计体系
FOLD·运营	变现与单位经济 / 渠道发行
SPLIT	战略与合规 →(战略→产品/商业定位 · 合规→运营/合规闸门)；开发团队版 →(架构段→架构 · 环境部署段→运维)
SPLIT·投资人版(消 Codex Major-5)	系统概要设计-投资人版 →(定位/商业模式→产品/商业定位 · 资本效率/成本对比→运营/单位经济 · 护城河话术→产品/护城河话术)
KEEP+迁移(计 1)	SAA-能力API接入-dossier(SAA §4 指向它,迁入生成引擎子树保留)
独立 FOLD(消 Opus M1 forensic 丢失)	产品功能与技术模块-完成度与优先级总账 → 独立迁入产品/运营域(其 155 功能×13 模块逐条读码 forensic ≠ docs/mvp/MVP进度总账,不可 POINTER 一笔带过)；事实进 §2.4 清单登记
ARCHIVE(纯 trace/被取代/治理/复盘)	多session分工总账 / 06-16 传承演进·任务普查·并行编排·目录治理 / 06-17 对话生成改素材 v1(被 v2 取代)·文档整理 plan·深度重构 plan(被本档取代)/ 06-20 根因复盘 report
POINTER	(无;v1 的"完成度总账 POINTER"已更正为上方独立 FOLD)
不动(白名单)	6 spike 子目录 + _archive/ 既有内容

完整性机校(消 M1 漏档):执行/验收时 comm -23 <(ls docs/agent-specs/*.md 去 _index/本档 后 basename|sort) <(本表覆盖文件名集|sort) 差集必须为空——漏一档即拦。

2.4 全量重写"不丢事实"门(可执行规格 · 消 Codex Critical-1)

每域重写前产出结构化源档事实清单(非散文),每条字段:

fact_id | source_file | source_line | fact(硬事实原文) | target_file | target_anchor | verify_mode(text|contract|code|manual) | evidence(命令/契约路径/reviewer)

• 覆盖硬事实:8 契约 / 门 ID(GP9·九门·G0G1)/ 单位经济数字 / 资本效率·成本 / SAA 六不变量 / split-brain 铁律 / new-api 剥 /v1 / LittleJS 55KB·终裁分数 / 对抗裁决 4 结论 等。
• 二阶来源规则(消 Opus C3 二次衰减):若 source 本身已是 06-17 蒸馏产物的 canonical,核对基准取其 git 历史中的原始源档,而非只对现态 canonical——防二次有损不可见。
• 回灌核对门:重写后逐条确认 target_anchor 可寻 + 按 verify_mode 交叉核验(contract/code 跑命令、text 人核、manual 记 reviewer)。漏一条或 anchor 不存在即红线、不予收口。

2.5 治理衔接 + 连带改动枚举(同 commit · 消 Opus C1 / Codex Critical-2)

A. 改写 engineering-conventions 治理门(architecture↔agent-specs 角色对调):

• §10.5 line 284 判层序:canonical(域树·architecture)＞ .agents/knowledge ＞ docs/mvp/MVP进度总账;agent-specs 从"canonical 家"降为"留痕+spike"。line 285 导航改指 docs/architecture/README.md。
• §10.6 line 292/294 策展层/判层规则:canonical 物理信号从"agent-specs 无日期主题名"改为"docs/architecture/ 域树"。
• §10.7 line 305 品牌门白名单:追加 docs/architecture/_archive/(对齐既有 agent-specs/_archive/);现行层路径表保持含 docs/architecture/。

B. 修入向引用(census 实测): .agents/knowledge/{product-and-architecture,tech-decisions,mvp-scope-and-milestones} + .agents/rules/{engineering-conventions,security-and-reliability} + .agents/skills/{ai-generation-pipeline,prompt-governance,saa-graph-orchestration,runtime-and-multichannel,contract-first-development,add-business-module} + .agents/tools/doc-organizer.sh(SPECS= 与 archive glob)+ .agents/README.md + docs/mvp/{可行性方案16周-波次映射,全成本收益测算模型-v2,MVP作战清单,MVP进度总账} + docs/plans/2026-06-18-001-* + AGENTS.md §3.2-3.4/§4/§5 + _index.md。

C. 门的现实(消 Opus M3):品牌门/canonical 唯一性门/死链门当前多为待落规格(prompt治理体系-execution.md 现就含旧名却未被拦=门脚本未真跑)。本次补最小死链门脚本(遍历 docs/+.agents/ 相对链接报不存在目标,落 .agents/tools/ + wave-close 第 8 步);canonical 唯一性门加迁移期豁免:旧档已打 SUPERSEDED 横幅 + 同提交归档,不计双 SoT。

D. 签字门:本 spec 过 AGENTS.md §6.8 Codex+Opus 双评审(✅ 已过,§8)+ §11 横切一致性主人(创始人+6c6g)签字。

2.6 推进次序(黄金模板先行 · 消 Opus m3 SPLIT 风险)

1. 建骨架 + L1 总索引 + 产品域纯 FOLD 子集(需求清单 + 需求模块映射 + 护城河话术,零 SPLIT)→ 跑通 4 级模板 → owner 验收。
2. 立即用一个 SPLIT 档(战略与合规)验证 SPLIT 动作 + 回灌门(因架构/运维/投资人版均含 SPLIT,不可推迟暴露)。
3. 复制模板 → 架构 / 生成引擎(最厚)→ 前端 → 运营 → 后端(瘦)→ 运维(瘦)。
4. 每域过 §2.4 回灌门 + §2.5 连带改动;全域完成总收口(wave-close 第 8 步 + _index/AGENTS.md 对账)。

2.7 文档风格规范(大厂标准 · 给人看的 · 2026-06-20 owner 补充)

输出的 6 域设计文档面向人类读者——产品、新同事、外部评审——而不是 agent 速查表。四条硬规范:

• 人读散文:用完整的句子和段落来写,有上下文、有逻辑过渡。结论先行,但把要点展开成可读的解释,而不是关键词的电报式堆叠。
• 多图:凡是图能说清楚的地方就用图——架构图、流程图、时序图、状态机,优先 Mermaid。每份域主档(L2)以及篇幅较大的模块子档(L3)至少配一张图。
• 少黑话:每个专有名词、缩写、内部代号(各类门、版本代号、项目内简称等)在首次出现时用一句话解释,或链接术语表;让没参与过本项目的人也能读懂。
• 单档 ≤ 2000 行:任何一份文档都不超过 2000 行;接近上限时按 4 级结构拆成 L3 模块子档或 L4 详档。

适用边界:这套风格只约束 docs/architecture/ 的输出设计文档;.agents/ 蒸馏层继续保持简洁的 agent 速查风格。两者各司其职——给人看的放在 architecture,给 agent 用的放在 .agents,正好强化分层。

---

3. 关键取舍

决策	选定	取舍
重写深度	全量重写	最彻底 vs 易丢事实 → §2.4 结构化回灌门兜底
物理落位	architecture 单根	单一真值 vs 反转 §10 判层 + 连带改动(§2.5)
域集	6 域 + 薄域瘦主档+指针	生命周期完整 vs 空壳 → 防空壳门(§2.2)
生成域	本次纳入	一步到位;红线已解除(C2 更正),无在飞阻塞
范围	纳入必然连带改动	单一真值真生效 vs blast radius 外溢两目录

为何 6 域树能解决"多型重复"(回应 Opus m2):横向 6 域解决归类;纵向"同主题 review+execution+verdict 多型重复"由全量重写收敛(一子系统一份域档 + dated 流水归档)解决——两者叠加,而非只换挂载点。

---

4. Blast radius / 风险与兼容性

1. 连带引用面(头号):§2.5 枚举的 ~17 文件 + doc-organizer.sh + §10 治理门。缓解=同 commit 全改 + §5 机校 rg 旧路径返 0。
2. 取代 06-17 下游连锁(C3):06-17 改过 §10.5/§10.6 + knowledge 指针 + doc-organizer + 总账分层。缓解=§6 接管清单逐条再处置。
3. 全量重写丢硬事实:缓解=§2.4 结构化清单 + 二阶来源规则 + 回灌门。
4. 品牌门白名单缺口(M4):新建 architecture/_archive 未在白名单 → 退役档含旧名会红线。缓解=§2.5-A 同 commit 扩白名单。
5. 生成域权属:红线已解除(C2);双评审 + 6c6g 签字作质量门。降级——非头号风险。
6. git mv history 语义(Codex minor-3):git mv 只保归档源档的 history;新域档不可 git log --follow 追旧史,改由 §2.4 清单 source_file/source_line 反链追溯。
7. 法律/品牌边界:docs/ip 不动;品牌门白名单不误伤。

---

5. 验收标准(每条配机校 · 消 Codex Major-6 / Opus M3)

验收	机校
L1 总索引存在	test -f docs/architecture/README.md
6 域主档齐全	for d in 产品 架构 后端 前端 运营 运维; do test -f docs/architecture/$d/README.md; done
瘦主档非纯指针	后端/运维 README 正文 ≥ 设定行数门
映射无漏档	§2.3 comm 差集 = 空
连带引用清零	rg -l "agent-specs/(agentic编排-SAA|开闸验收门|引擎与运行时|渠道发行|studio前端设计体系|变现与单位经济|战略与合规|prompt治理|生成主线架构演进)" .agents docs/mvp docs/plans = 0;architecture 旧源档路径同理
品牌门	rg "造梦AI" docs/architecture --glob '!_archive' = 0;白名单已含 architecture/_archive
死链=0	跑本次新落的最小死链门脚本 = 0
canonical 唯一	frontmatter topic 扫描每 topic ≤1 canonical(迁移期豁免:旧档 SUPERSEDED+同提交归档)
单档 ≤2000 行	脚本 wc -l 扫 docs/architecture 所有 md,无 >2000 者
多图/少黑话	每份 L2 域主档 + 较大 L3 含 ≥1 图;专名首现有解释/链接(评审人核)
双评审+签字	评审记录=§8;签字记录位置=本档头注/commit message

---

6. 与既有治理对账 + 06-17 取代连锁接管清单(§11)

取代 2026-06-17-agent-specs深度重构-plan.md 的两层定位(canonical 住 agent-specs / architecture 降基线)。逐条接管其下游:

06-17 改过的下游	本次再处置
§10.5 立"canonical 住 agent-specs·无日期主题名"	改为"canonical 住 architecture 域树"(§2.5-A)
§10.5 line284 判层序(architecture=基线)	反转为 architecture 域树=canonical 根
§10.6 策展层/判层规则	canonical 物理信号改 architecture 域树
.agents/knowledge/* canonical 指针	改指新域树路径(§2.5-B)
doc-organizer.sh SPECS=docs/agent-specs + 总账分层来源	改 SPECS/glob 适配新根
_index.md 四层定位 + line22↔line40 自相矛盾	瘦身为 trace/spike 索引 + 修 line22 标题对齐 line40(红线已解除)

与 AGENTS.md §3.3 两层(策展/留痕)不冲突:本设计把"策展层"的设计文档收进 architecture 单根 6 域树,留痕层定位不变。

---

7. 已决项(2026-06-20 · owner 批准)

1. 合规归并=✅ 合规→运营/合规闸门.md;战略→产品/商业定位(不单立"合规"域)。
2. 运维内容源=✅ 瘦主档,取开发团队版环境/部署段 + 指针→deploy/(范围外,只引不搬)。
3. 生成域排序=✅ 架构之后、其余之前。
4. 总索引文件名=✅ docs/architecture/README.md。
5. 执行编排=✅ Workflow 分域 fan-out + 回灌门并行验;writing-plans 细化。
6. 范围=✅ 纳入必然连带改动(§2.5)同 commit。
7. 文档风格=✅ 大厂标准:人读散文 / 多图 / 少黑话 / 单档 ≤2000 行(§2.7)。

---

8. 双评审门处置(2026-06-20 · Codex + Opus)

裁决:两位均判「需修后收口,无需架构返工」。下表为处置;已在本 v2 修掉的标 ✅,转执行计划的标 →PLAN,收口 TODO的标 →TODO。

来源	发现	处置
Opus C1 / Codex Crit-2	范围漏 .agents/ 治理层(§10 判层反转/指针/doc-organizer)	✅ §1·§2.5·§4·§6
Opus C2	头号约束建在过期前提(_index line40 红线已解除·误引)	✅ §0·§4-5 降级
Codex Crit-1	回灌门只是口号,无可执行规格	✅ §2.4 结构化 schema
Opus C3	72h 第二次搬迁 + 未接管 06-17 连锁 + 二阶衰减	✅ §0 诚实声明·§2.4 二阶规则·§6 接管清单
Opus M1 / Codex Maj-1	漏档:并行编排/完成度总账/开闸接线/投资人版	✅ §2.3 补全 + comm 机校
Codex Maj-2	UI走查目录非白名单非处置	✅ §1 纳入白名单 spike
Codex Maj-3	归档落点歧义	✅ §2.1 各归各家规则
Codex Maj-4	§6.8/§10/§11 引用未限定	✅ 头注限定为 AGENTS.md/§10.x
Codex Maj-5	投资人版漏资本效率/成本	✅ §2.3 SPLIT·投资人版
Opus M2	OUT 目录有入向链接·§1↔§4 矛盾	✅ §1 "不动"语义澄清
Opus M3 / Codex Maj-6	验收混不可机校词;死链/canonical 门无脚本	✅ §5 机校表·§2.5-C 补死链脚本
Opus M4	品牌门白名单漏 architecture/_archive	✅ §2.5-A·§4-4
Opus m1	薄域=孤儿空壳	✅ §2.2 防空壳门
Opus m2	6 域未论证解多型重复	✅ §3 注
Opus m3	产品域黄金模板含 SPLIT	✅ §2.6 改纯 FOLD 子集 + SPLIT 单验
Codex min-1/2/3	KEEP 计数 / 表格被 blockquote 断 / git mv history	✅ §0 计 1·§2.3 规范·§4-6
Opus·跨档	_index line22↔line40 自相矛盾	→PLAN §6(连带改 _index)
Opus/Codex	门脚本(死链/品牌/canonical)真正落地	→PLAN §2.5-C(随执行补脚本)