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 -- <路径>)
.agents/ —— 绘境AI 项目的 Agent 能力中枢
本目录沉淀并复利累积项目的 Agent 能力、知识、规则与流程，让团队在长期跨会话开发中持续抬高 AI 驱动开发的能力、准确率与稳定性。
工作入口、项目定位/目标/目录均见
../AGENTS.md（项目唯一入口）；CLAUDE.md仅以@AGENTS.md导入它。
一、目录结构与职责
| 子目录 | 职责 | 回答的问题 |
|---|---|---|
knowledge/ |
事实与蓝图蒸馏（产品、架构、范围） | 是什么 |
rules/ |
必守的硬约束（工程规范、安全可靠性、build-vs-buy） | 必须怎样 |
skills/ |
可复用操作手册 playbook（怎么做某一类事） | 怎么做 |
workflows/ |
元流程（如何承接、推进、收尾一个任务） | 如何承接任务 |
tools/ |
治理门与文档整理的机械脚本（检测/归档/死链/品牌门） | 机器怎么把门 |
通用顺序：先 knowledge 对齐事实 → 看 rules 划红线 → 用 skills 落地 → 按 workflows 推进收尾。
二、文件清单（每条一句话）
knowledge/
| 文件 | 一句话说明 |
|---|---|
product-and-architecture.md |
产品定位、13 模块与依赖、三仓三端分层架构蒸馏（中间件 Nacos/RocketMQ/Sentinel 三件套已自托管 mini-infra） |
tech-decisions.md |
技术栈与关键选型 ADR + 待确认项 + 生成主线口径（AgentScope 三档统一收敛）+ 便宜档 M1-M3 实测（§5.1） |
mvp-scope-and-milestones.md |
MVP 的 55 项 P0 产品功能范围、5 工位分工、M0-M5 里程碑与验收指标 |
agentscope-2.0-facts.md |
AgentScope 2.0.2 真实架构速查 + 便宜档 cheap-worker 实现 API 速查（免重查） |
rules/
| 文件 | 一句话说明 |
|---|---|
engineering-conventions.md |
命名/分层/API 路径/错误码/提交/PR 等工程规范 + §10 文档治理机器门 |
security-and-reliability.md |
安全基线/幂等/超时重试/合规/可靠性红线（§1 @PermitAll 三条 + §4 外部 IO 不入事务 + §4.1 资金打款） |
build-vs-buy.md |
自研偏误防线 R1-R7：现货尽调前置门/形态终点/约束血统/prior-art 强制步/名义采用禁令/抽象墙审计 |
skills/
| 文件 | 一句话说明 |
|---|---|
add-business-module.md |
新增一个 game-module 业务模块的标准步骤 |
littlejs-game-dev.md |
AI 写 LittleJS 游戏代码作业手册（code 层）：12 插件 API + 代码结构 + 工厂五法 + 资产/mmx 流 + 受控面铁律，终态产物 = src/ 多文件工程 |
sim-business-game-design.md |
经营模拟小游戏玩法设计手册（给生成 agent 的设计阶段）：爆款范式/数值/美术/UI/音 → 映射 12 插件 + 反"无趣"8 条自检；与 littlejs-game-dev 配对 |
runtime-and-multichannel.md |
运行时打包、iframe 沙箱、SDK 注入与多渠道（微信/抖音/快手）导出手册 |
contract-first-development.md |
契约先行：8 类契约对齐与各工位 mock 并行解耦 |
prompt-governance.md |
Prompt 即第 8 契约：Registry/加载注入/eval 门禁/HITL 治理手册 |
wave-close-checklist.md |
波次收口八步检查单——所有收口铁律指向的唯一可执行清单 |
staging-ops.md |
staging 运维配方：机器分工/代码同步/后端重部署/前端构建门/冒烟门 |
ui-walkthrough-cdp.md |
真 UI 走查配方（CDP on mini-desktop）：studio/admin 走查 + CDP 七坑 + 信道探针 |
game-e2e-cdp-harness.md |
Canvas 游戏 e2e 证据 harness：驱动器六律 + 出厂红线 + 九门真玩（A–G 假绿守卫 + H 机制/latch + I 控制手感） |
cheap-model-game-generation.md |
便宜模型生成跨路通用蒸馏：成本/前缀缓存降本/L1 纪律坑/质量三层/scale-20 模型画像（旧 gamedef/factory 路已压缩留指针，现行走 cheap-worker） |
agentic-amodel-generation.md |
底层 A-model 生成 harness（gen.mjs ReAct 工具循环：scaffold→读写检构→循环外 play）：8 坑 + M3 实证；现行被 cheap-worker shell-out 复用 |
gen-path-parity-harness.md |
两条生成路对照（parity）harness + 按品类 ≥80% 达标门 + auto-vs-golden 双驱动 delta 门：验换实现不回退 / 判够不够格上线 |
saa-graph-orchestration.md |
SAA 图编排远期备查（SAA 降最低优先级）：依赖集/接 new-api 剥 /v1 坑/checkpoint saved_at 无 tiebreaker + 显式 checkPointId 修法 |
tier2-service-generation.md |
tier2 富游戏服务态生成驱动配方（create_app :8200 + 控制面有界 resume）：真玩 driver 是头号收敛杠杆 + 驱动六口径 + C1 trace |
doc-organizer.md |
文档整理助手（创始人手动触发）：增量窗口 + 两阶段审批门 + 三轴（过期清理/措辞对齐/总账回填）；底层脚本在 tools/ |
drive-remote-claude-tmux.md |
远程驱动交互式 Claude Code（ssh + tmux）：双向通道派活读屏 + 每设备配置 + 完成判据 = git push |
architecture-diagram-atlas.md |
架构图集生成配方：house style / 图说结构 / 三范式纪律（单源·防漂移·状态双层）/ 按域并行编排 / 双评审六坑 |
feature-design-doc.md |
功能设计文档作业手册：WHAT+HOW 合一、一式两份（文字+Mermaid 给人/AI · SVG/HTML 给人）、防漂移单源 |
execution-plan-slicing.md |
执行 plan 切分轴：横切关注面 vs 纵切成果切片；诊断信号 + 换轴 + 三层文档 + 必查五坑 |
workflows/
| 文件 | 一句话说明 |
|---|---|
ai-development-protocol.md |
任务承接→分析→评审→执行→验证→沉淀的完整协议 + 子代理 model 成本分档 |
mvp-execution-orchestration.md |
MVP 10-Agent×3 周执行编排 + 8 条复利提效策略 |
tools/
| 文件 | 一句话说明 |
|---|---|
docs-gate.py / docs-gate.sh |
文档治理机器门（engineering-conventions §10.7）：六检——品牌不变量 / canonical 唯一 / 死链 / 入口卫生 / 留痕隔离 / 设计档申报 |
doc-organizer.{sh,-analyze.mjs} + doc-organizer-state.json |
doc-organizer 底层：检测（scan/health/stale/ledger）+ 可逆归档 + 记时 + 三轴分析 Workflow + 增量窗口锚点 |
三、按任务类型查阅
| 任务类型 | 先读 | 再读 |
|---|---|---|
| 分析 | workflows/ai-development-protocol.md + 相关 knowledge/ |
原始 docs/architecture/ 长文档 |
| 评审 | rules/（拿约束当尺子）+ knowledge/ |
对应 skills/ 看实践标准 |
| 编码 | 对应 skills/ + rules/engineering-conventions.md |
knowledge/ 对齐上下文 |
| 调试 | 相关 skills/ + knowledge/ |
rules/security-and-reliability.md |
四、维护规则（要点）
- 先查重再新增：全新主题才新建文件；补充/修正既有主题一律更新现有文件，不造重复。
- 过时即处理：信息失效立即修正或删除；与代码/文档冲突时以已验证事实为准。
- 同步索引：任何结构性变更（增/删/改名）同步更新本 README 清单与
../AGENTS.md导航。 - 单一主题、精炼、可检索：每文件聚焦一个主题，用表格与要点，做蒸馏而非照搬源文档。
- 相对路径 + 简体中文：交叉引用用相对路径（仓库迁移不失效）；一律简体中文；死链改
git show <sha>^:<path>定位（见tools/docs-gate.pyG3）。
维护本身是任务收尾的一部分——见
workflows/ai-development-protocol.md的"沉淀"环节与skills/wave-close-checklist.md。