本仓库文档按"层"组织：每层一个关注点、一个事实源；越上层越稳定、越下层越易变；下层依赖上层、不反向依赖。新人 / 新 agent 按下方"阅读顺序"进入。
┌──────────────────────────────────────────────────┐
治理 │ AGENTS.md 行为规范 · 黄金法则（跨层约束） │
└──────────────────────────────────────────────────┘
▲ ┌──────────────────────────────────────────────────┐
│ 稳定 │ ① 愿景 Vision 为什么做 · 设计赌注 · 哲学 │
│ ├──────────────────────────────────────────────────┤
│ │ ② 领域 Domain 设计空间 · 意图本体 schema │
│ ├──────────────────────────────────────────────────┤
│ │ ③ 架构 Architecture 技术栈 · 编排图 · 持久化 · 落地序 │
│ ├──────────────────────────────────────────────────┤
│ │ ④ 契约 Contracts Widget / IntentState / 脚本 / API│
│ ├──────────────────────────────────────────────────┤
│ 易变 │ ⑤ 模块 Modules 各 agent / 节点详规 │
▼ └──────────────────────────────────────────────────┘
┌──────────────────────────────────────────────────┐
参考 │ 决策 Decisions(ADR) · 术语 Glossary │
└──────────────────────────────────────────────────┘
依赖方向：模块 → 契约 → 架构 → 领域 → 愿景。改上层要想清楚对下层的冲击；改下层不应反推上层。
| 层 | 文档 | 路径 | 作用 | 稳定性 | 状态 |
|---|---|---|---|---|---|
| 治理 | AGENTS | /AGENTS.md |
agent 行为规范 · 黄金法则 | 高 | ✅ |
| ① 愿景 | 终版 proposal | /final_proposal.md |
问题 / 赌注 / 哲学（权威） | 高 | ✅ 用户维护；生成路径以 ADR-0010 为准 |
| ② 领域 | 本体 schema v3 | domain/ontology-spec.md |
12×56 分类 + 元结构 + 知识卡规格 | 高 | ✅ v3 已落地 (ADR-0010) |
| ② 领域(数据) | 导演意图分类 v3 | /labels_v3.json |
本体内容权威源（编辑入口 导演意图分类_v3_中文.xlsx） |
高 | ✅ 知识卡/元字段在 backend/app/ontology/ |
| ③ 架构 | 系统架构 | /架构设计.md |
栈 / 编排图 / 持久化 / 落地序 | 中 | ✅ ADR-0010 已同步 |
| ④ 契约 | 接口契约 | contracts.md |
前后端 / 节点间 schema | 中 | ✅ 开发阶段已激活 |
| ⑤ 模块 | 模块详规 | modules.md |
各 agent / 节点 I/O 与行为 | 低 | ✅ 纯推理链路已同步 (ADR-0010) |
| 参考 | ADR 日志 | decisions.md |
已定决策追溯 | 追加 | ✅ 已 seed |
| 参考 | 术语表 | glossary.md |
统一用语 | 低 | ✅ |
阅读顺序：AGENTS.md → 本页 → final_proposal.md → domain/ontology-spec.md → 架构设计.md → contracts.md → modules.md；decisions / glossary 随用随查。
- 新文档去哪：先判断属于哪一层，放对应位置；若无合适层，先在本页地图加一行，再写文档。
- 命名：领域 / 模块用英文短名（
ontology-spec.md）；跨层索引文档用README.md；ADR 用decisions.md内的ADR-000X。 - 引用：跨文档用相对路径链接；契约只在契约 / 架构层定义一次，别处引用，禁止复制粘贴 schema。
- 状态标记：✅ 就绪 · 🚧 骨架 / 进行中 · 📦 归档参考 · ❓ 待决策。
- 同步地图：任何增 / 删 / 移动文档，都要回来改本页这张表（AGENTS.md 的硬要求）。
现状：愿景与架构文档在根目录，新层文档在 docs/。如想完全统一，可把 final_proposal.md、架构设计.md 移入 docs/ 并加数字前缀（01-vision.md / 03-architecture.md），原始 proposal 归入 docs/archive/。默认不动用户已有文件——要整合请明示。