d97e194383
- 注册表:docs/architecture/README.md §2,37 份 canonical(frontmatter topic+canonical:true)与表双向机器对账
- 门:.agents/tools/docs-gate.py 六检(品牌根/canonical唯一/死链/入口卫生/留痕隔离/设计档申报),挂 .githooks/pre-commit(本仓已激活)+ .gitea/workflows/docs-gate.yml(待runner)+ wave-close 第8步;旧 check-deadlinks.sh 退役并入 G3
- 清缩:删 54 项历史档(plans 16/agent-specs 设计与spike 20/brainstorms 5/memorys 3/goals+作战清单完成史归档/王蓝莓design/SAA现状html/add-game-template);channel-spike 564K 代码资产迁仓级 spikes/;六件删前蒸馏已迁(代码评审16条open项→进度总账§5、prefix-cache字段表→cheap-model skill、意图基线29条→需求清单附录、九门降级rationale→验收门、A11 TODO→tech-decisions、3layer边界→littlejs-game-dev 指针)
- 修口径约90处:六处SAA『现行主线』旧标、Nacos/RocketMQ『未部署』旧述(07-01反转)、gameDefinition残留、全部死链改 git show 定位;AGENTS.md 249→136行(决策史归tech-decisions);_index 改纯在飞板;对外演示版 md→html
- 依据:docs/agent-specs/2026-07-02-文档治理-{全量普查与裁决-report,SoT注册表与治理门-设计}.md(四路普查191份md+Codex/Opus双评审必修项已折入);恢复基线 8ea97234(单档 git checkout 8ea97234 -- <路径>)
8.9 KiB
date, topic, status, superseded-by
| date | topic | status | superseded-by |
|---|---|---|---|
| 2026-07-02 | 文档治理-全量普查与裁决 | report · 四路并行普查(191 份 md)+ Codex/Opus 双评审结论合并;裁决执行见同日设计档 |
文档治理 · 全量普查与裁决报告(2026-07-02)
四个只读普查代理分区扫过 docs/ 与 .agents/ 全部 191 份 md(架构树 / 留痕层 / mvp 活账与根散档 / .agents 与治理门),Codex 与 Opus 随后对清缩设计做了对抗评审。本报告是删除与精简动作的依据留痕;逐项动作见 2026-07-02-文档治理-SoT注册表与治理门-设计.md。所有删除对象在 git 中可恢复(基线 8ea97234)。
一、治理门现状(为什么熵增没被拦住)
- §10.7 宣称的四道门零脚本落地:
.agents/tools/只有 check-deadlinks.sh(无人跑、探不到反引号裸路径引用、白名单里还留着为已删 spike 目录开的口)与 doc-organizer 三件(内嵌 TRUTH 基准已过期:仍写"RocketMQ/Nacos 未部署"、"SAA 降级"前口径;脚本硬编码他机绝对路径,本机失效;state 记录停在 2026-06-17)。 - 无 git hook(.git/hooks 空、core.hooksPath 未设);唯一 CI 是 game-cloud 的 maven.yml,只在 master 触发且跳测试,零文档检查。
- canonical 无机器锚:49 份文档口头自称 canonical,带
canonical: truefrontmatter 的只有 16 周主计划等极少数;门②无从机检。 - 索引五头并管、四处漂移实证:_index.md 给昨日(commit
6d2f8789,-23,286 行)已删的_archive/与三个 spike 目录维持 ★ACTIVE/白名单标;进度总账表头仍引已归档的 Doc A/B/C;架构 README 索引已改为 html 的 md;check-deadlinks 实跑报 28 处死链。 - 07-01 Nacos/RocketMQ/Sentinel 反转只回填了两处(tech-decisions §10、AGENTS.md §3.1),漏了 product-and-architecture、doc-organizer TRUTH、00-系统总览图说(:35,88,174)、后端/README(:80)、运维/README(:152)、鉴权与权限 §7——同一事实当天起两种口径并存。
二、裁决汇总(按区)
docs/architecture(47 md + 2 html,82 SVG)
全树 SoT 保留,修口径不删。系统性问题三类:①六处活层仍标 SAA 为"现行生成主线"(架构/README:35、02-架构图说:47/187、07-运维图说:186、观测体系多处、prompt治理:35、变现与单位经济:211/218,另 13模块 §3.2 卡片、护城河 B3、OpenGame对照与数据飞轮的 gameDefinition 残留);②图说 00-07 内联复制域树 Mermaid,声称的"防漂移收口脚本"不存在=无门双源(裁:域树为 SoT、图集为派生视图,横幅明示);③运行时合并后 tombstone 已删但 03/05 图说与 WG1基准仍指旧路径。唯一删除:2026-06-23-saa-现状架构图.html(reframe 前对外快照)。_archive(204K,7 份带 tombstone)与 _recall(创始人判定录)保留。需求计数 155/158 漂移按表内实际行数统一;P-FED-12 致 55/56 总数冲突列待拍板。
docs/agent-specs + plans + brainstorms + superpowers(留痕层)
- 在飞保留(仅此):plans 5 份(2026-06-25 统一执行计划[canonical]、2026-06-22-003 tier2、2026-06-28-002 n5 收敛环、2026-06-30 便宜档 M3 生产 cutover、2026-07-01 配置控制面)+ assets;agent-specs 设计 2 份(2026-06-29 便宜档减摩擦、2026-06-30 配置控制面);superpowers 的 mvp-execution-spec(16 周主计划的视图,精简保留)。
- 删除:agent-specs 17 份日期档(SUPERSEDED 自标 / 被 2026-06-25 reframe 推翻 / 已折入运行时 SoT 与生成引擎 README——含 2026-06-12 总体架构、2026-06-16 两份、2026-06-17 五份、2026-06-20 域化重构两份、2026-06-21 三份、2026-06-22-3layer[先迁代码组织三层边界]、2026-06-23 design-agent 两份、2026-06-24 代码评审[先迁 16 条 open 项]、2026-06-28 母语实验[已蒸馏且结论被 06-29 推翻]、生成主线架构演进路线[⛔自标]);spike 目录 tier1-engine-spike(84K)与前端UI走查(12K);plans 16 份非在飞(均有完成/取代证据);brainstorms 5 份(意图清单先迁 29 条全量表);superpowers 王蓝莓黄金闭环。
- channel-spike(564K)不删:渠道发行.md:248 明标"代码资产,请勿误清理"——
git mv迁仓级spikes/(§10.3 本就禁 spike 代码入文档树),渠道发行同步改指针。 - _index.md 十二处死链 + 整条 A-model 设计链漏记 → 重写为在飞板。
docs/mvp + memorys + ip + 根
16 周主计划(canonical)、进度总账、作战清单、A1 闸门看板、单位经济敏感性模型、人办清单、全成本收益测算模型(与单位经济互补:per-DAU 拍板资产 vs 全成本财务模型;但 eCPM 口径分歧待拍板)、律所 brief、创始人汇报(视图,留存口径漂移修回 SoT 值)全保留;删 MVP作战清单-完成史归档(纯历史)与 goals.md(全 ✅ 的 06-16 快照;AGENTS.md 与 16 周 §5 指针同步改)。docs/memorys 整目录删(prefix-cache 的前缀缓存字段表先蒸馏进 cheap-model skill)。docs/ip 44 文件全保留(法律红线)。内网凭据与端点=密钥单一源保留(NEWAPI_KEY 全仓唯一,Redis/MySQL 口令在 07-01 plan 内联属可精简项)。
.agents(31 md + tools)
删 add-game-template.md(自标 🛑 DEPRECATED 整篇退役,README 却描述为 active=索引失真)。精简/修口径:product-and-architecture(Nacos 反转 + 品牌根残留 L69/L135)、security-and-reliability(Dify Guardrails 等从未部署项)、runtime-and-multichannel(Cocos+MCP 档轴已被正交两轴纠正)、sim-business-game-design(SAA framing→AgentScope 设计阶段)、agentic-amodel-generation(§8 过时快照;定位改"底层 harness 手册,被 cheap-worker 复用")、cheap-model-game-generation(gamedef 历史压缩留跨路有效核)、saa-graph-orchestration(压为远期适配备查,112 行硬坑保精华)、ui-walkthrough(:40 品牌根)、ai-development-protocol(:75 Dify 示例)、doc-organizer 三件(TRUTH 更新+路径参数化,skill 保留:创始人手动清理流程与门互补)、README 重写(一行一条)。glossary.md 已随 6d2f8789 删除,三处死链改为删引(不复建)。knowledge 与域树非双源(速查 vs 深文档),但内容冲突处以域树+最新裁定为准修齐。
三、双评审结论(2026-07-02,均"需修后执行",必修项已全部折入设计 v2)
- Codex P0:channel-spike 按名单删会丢渠道 SoT 依赖的代码资产 → 改迁
spikes/。P1:注册表数目算不平(定为显式 37 行表)、G2 需状态列区分 canonical/视图、G5 对 mvp 整体豁免过宽(收敛为"G3 死链+doc-organizer 巡检兜底"并明示)、波A 里 architecture/README 归主代理独占、goals.md 删前改 AGENTS.md:42 与 16 周:137 两处入口指针、add-game-template 的两处反向引用同步改、00-系统总览三处 Nacos 漏网补修、P-FED-12 55/56 总数冲突单列待拍板。P2:门脚本避免 shell here-doc(独立 .py)、G3 增反引号仓内路径检查并对git show定位放行。 - Opus P0:2026-06-22-3layer-review 承载的代码组织三层边界(L1 工程骨架/L2 能力库/L3 游戏代码、writeFileTool 拒写、canonical 键、createGame 签名、11 插件表)与运行时 SoT 的"三层校验"(硬约束/设计符合/效果)是两回事,且在飞 plan 2026-06-22-003:404 引它作"边界源" → 先迁运行时图说再删、改 plan 指针。P1:普查裁决须入仓可审(即本报告)、意图清单去留矛盾(定:29 条全量表并入产品/需求清单附录后删)、G1 品牌根白名单要机器可判(定:活层散文去字面量,唯一字面量留门脚本常量,支持行内
brand-ok豁免标)、pre-commit 是自愿门(定:补 .gitea/workflows 服务端门文件,runner 可用性列待办;wave-close 第 8 步为流程兜底)。P2:文档数字口径(126 份不含 ip)、生命周期范式实际在生成引擎 README §3.1-3.3、"确认日"列删除(装饰列)。
四、待拍板(不代裁,维持现状)
- 全成本收益测算模型-v2 与单位经济敏感性模型的 eCPM 口径分歧(完整观看单价折算 200/562.5/1080 vs 每次曝光 15/30/60,差一个数量级)——对外财务口径,须创始人收敛。
- docs/architecture/**_archive(7 份)与 _recall(创始人 199+43 条判定录)**是否对称清除(现保留:体量小、已隔离、是"为何不做"的决策史)。
- 绘境AI-总架构图说-对外演示版.html(未跟踪)是否纳入版本库并由 README 正式索引。
- MVP作战清单内容整体刷新(末次回填 2026-06-15,未反映切片一/plan①/16 周口径)——进度维护,非本次文档治理范围。
- RTM 缺 P-CRT-16/17、P-ACC-06 登记(产品事实补录)。
- 观测体系若 SAA 观测地基已从 game-cloud 拆除则需整体重写(本次仅按实核修口径/挂横幅)。
P0 总数 55 vs 56已消解(执行中实核):需求清单实测 P0=55 行且已含 P-FED-12(P-PUB-01 降 P1 抵平),全仓"55 P0"口径正确;数据飞轮"55→56"系误述,已订正。- Gitea Actions runner 是否已配(决定服务端门文件即刻生效与否)。