7bd9cd05e6
设计文档域化重构总收口: - §10 治理门反转(engineering-conventions §10.5/10.6/10.7):canonical 根从 agent-specs 改为 docs/architecture 6 域树;品牌门白名单加 architecture/_archive。 - 归档 11 settled 源档(7 根 architecture + 4 非生成 agent-specs canonical)→ 各自 _archive(git mv 保 history + tombstone redirect)。生成域设计链过渡期保留(架构演进中)。 - rewire 17 个活层文件(.agents/knowledge|rules|skills + docs/mvp + AGENTS.md + 新树)指向新树路径;活层零残留旧 canonical 路径。 - AGENTS.md §4 必读表/§3.2 目录树/§3.3-3.4 指针 → 新树;_index.md 瘦身为 trace/spike + 生成域演进链 + 修 line22↔40 自相矛盾。 - 新增死链门 .agents/tools/check-deadlinks.sh(§10.7 死链项的可执行脚本)。 - 全门齐跑:死链 0 / 新树无旧品牌 / 无超 2000 行 / 活层无残留。 Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
.agents/ —— 绘境AI 项目的 Agent 能力中枢
本目录沉淀并积累项目的全部 Agent 能力、技能与规则，让团队在长期开发中复利式积累知识、流程与能力，持续提升 AI 驱动开发的能力、准确率与稳定性。
工作入口、项目定位/目标/目录均见
../AGENTS.md（项目唯一入口）；CLAUDE.md仅以@AGENTS.md导入它。
一、本目录是什么
随着项目长期、跨会话推进，零散的认知和踩坑很容易丢失，AI 每次都"从零理解"。.agents/ 把这些沉淀成结构化、可检索、可复用的资产：事实蒸馏、硬约束、操作手册、元流程各归其位。每次任务从这里取经验、向这里存经验，能力随时间累积而非反复重置。
二、目录结构与职责
| 子目录 | 职责 | 回答的问题 |
|---|---|---|
knowledge/ |
事实与蓝图的蒸馏（产品、架构、范围、术语） | 是什么 |
rules/ |
必须遵守的硬约束（工程规范、安全可靠性） | 必须怎样 |
skills/ |
可复用操作手册 playbook（怎么做某一类事） | 怎么做 |
workflows/ |
元流程（如何承接、推进、收尾一个任务） | 如何承接任务 |
完整文件清单
knowledge/
| 文件 | 一句话说明 |
|---|---|
knowledge/product-and-architecture.md |
产品定位、13 模块与依赖、三仓三端架构蒸馏 |
knowledge/tech-decisions.md |
技术栈与关键选型理由 |
knowledge/mvp-scope-and-milestones.md |
MVP 的 55 项 P0 产品功能范围、里程碑与验收指标 |
knowledge/glossary.md |
术语表 |
rules/
| 文件 | 一句话说明 |
|---|---|
rules/engineering-conventions.md |
命名/分层/API 路径/错误码/提交/PR 等工程规范 |
rules/security-and-reliability.md |
安全基线、幂等、超时重试、合规与可靠性约束（§1 含「@PermitAll 公开读端点纪律」三条：裁字段/DataPermission/租户 scoping，P-OPN-08 实证；§4 含「外部 IO 一律不入 DB 事务」泛化红线 + §4.1 资金打款特例） |
rules/build-vs-buy.md |
自研偏误防线(R1-R7):现货尽调前置门/形态终点测试/约束血统/prior-art 强制步/名义采用禁令/抽象墙审计 |
skills/
| 文件 | 一句话说明 |
|---|---|
skills/add-business-module.md |
新增一个 game-module 业务模块的标准步骤 |
skills/add-game-template.md |
新玩法模板接入配方（契约→prompt→runtime→后端→编排器→五级验收门，merge 实战收口版） |
skills/ai-generation-pipeline.md |
AI 生成链路（Dify + OpenGame + aigc 壳）开发手册 |
skills/runtime-and-multichannel.md |
运行时打包、沙箱、SDK 与多渠道导出手册 |
skills/contract-first-development.md |
契约先行：契约对齐与并行解耦 |
skills/prompt-governance.md |
Prompt 即第 8 契约：Registry/加载注入/eval 门禁/HITL 治理手册 |
skills/wave-close-checklist.md |
波次收口八步检查单——所有收口铁律指向的唯一可执行清单（第 8 步=spec 退役/分层 + docs/agent-specs/_index.md 维护） |
skills/staging-ops.md |
staging 运维配方：机器分工/代码同步/后端重部署/前端构建门/冒烟门 |
skills/ui-walkthrough-cdp.md |
真 UI 走查配方（CDP on mini-desktop）：studio/admin 走查 + CDP 七坑 + 信道探针 |
skills/game-e2e-cdp-harness.md |
Canvas 游戏 e2e 证据 harness：编排形制/驱动器六律/出厂红线/四件套口径（T1b-α 实证；§7 = W-G1 生成游戏真玩九门 = 假绿守卫 G 门 + H 机制/latch + I 控制手感 + 自产 gatespec） |
skills/cheap-model-game-generation.md |
便宜模型（new-api DeepSeek/MiniMax）直出可真玩轻游戏 L1 worker：链路/模型与成本/L1 纪律/坑红线/latch 套壳/design agent 自产 gatespec/质量三层（W-G1 HJ-GEN-001 实证） |
skills/saa-graph-orchestration.md |
SAA（Spring AI Alibaba）裸 StateGraph 生成编排：拓扑/加节点/接 new-api(剥 /v1 坑)/checkpoint(含 saved_at 无 tiebreaker 框架坑+显式 checkPointId 修法)/observation/最小依赖集/派发契约/验证门（HJ-AGI-002 实证） |
skills/doc-organizer.md |
文档整理助手（创始人手动触发）：增量(上次清理→现在)+两阶段审批门——发起分析 Workflow→编清理计划→评审→批准后才执行；三轴=过期档清理(归档/压缩)/核心设计档措辞对齐现行真相/主任务总账回填；底层 tools/doc-organizer.{sh,-analyze.mjs,-state.json}（检测自动·判断留人·脚本不自删·最新日在飞档不碰） |
skills/drive-remote-claude-tmux.md |
远程驱动交互式 Claude Code（ssh + tmux）：双向通道 send-keys 派活 + capture-pane 读屏，不走 ACP/headless；每设备配置块 + onboarding 侦察配方 + 专用会话(独立 worktree 防撞树) + bypass-perms + 安全红线；完成判据=git push 非读屏（创始人 2026-06-18 拍板·多设备复用） |
workflows/
| 文件 | 一句话说明 |
|---|---|
workflows/ai-development-protocol.md |
任务承接→分析→评审→执行→验证→沉淀的完整协议 |
workflows/mvp-execution-orchestration.md |
MVP 10-Agent×3周 执行编排 + 8 条复利提效策略 |
三、使用方式（按任务类型查阅）
| 任务类型 | 先读 | 再读 |
|---|---|---|
| 分析 | workflows/ai-development-protocol.md + 相关 knowledge/ |
原始 docs/architecture/ 长文档 |
| 评审 | rules/（拿约束当尺子） + knowledge/ |
对应 skills/ 看实践标准 |
| 编码 | 对应 skills/（操作手册） + rules/engineering-conventions.md |
knowledge/ 对齐上下文 |
| 调试 | knowledge/glossary.md + 相关 skills/ |
rules/security-and-reliability.md（排查可靠性/幂等问题） |
通用顺序：先 knowledge 对齐事实 → 看 rules 划红线 → 用 skills 落地 → 按 workflows 推进与收尾。
四、维护规则（关键）
.agents/ 的价值取决于是否被持续、规范地维护。务必遵守：
- 何时新增 vs 更新现有
- 出现全新主题（新模块手册、新流程）→ 新增文件。
- 是对已有主题的补充/修正→ 更新现有文件，不要另起炉灶造重复。
- 先查重：新增前先检索本目录，避免重复条目和同义文件。
- 过时即处理：信息失效时立即修正或删除，不留误导性内容；与代码/文档冲突时以已验证事实为准。
- 单一主题、精炼、可检索：每个文件聚焦一个主题，用表格与要点，便于 Agent 快速定位；避免照搬源文档大段内容，做蒸馏与索引。
- 同步索引与交叉链接：任何对
.agents/的结构性变更（增/删/改名文件），都要同步更新本 README 的清单，以及../AGENTS.md中相关导航与交叉链接，保持全局一致。 - 语言：一律使用简体中文。
- 相对路径链接：文件间交叉引用使用相对路径，保证仓库迁移后链接不失效。
维护本身就是任务收尾的一部分——见
workflows/ai-development-protocol.md的"沉淀"环节。