按功能域组织，不按代码目录。一个功能域可能横跨多个代码包，文档描述的是"做什么"而不是"代码在哪"。
最多两跳到达任何文档：docs/<domain>/<file>.md。
docs/
├── architecture.md ← 全局架构入口（分层设计、Schema、包结构）
│
├── agent-llm/ ← Agent 编排 + LLM 接入
│ ├── overview.md ← AG-UI 协议架构、事件流、迭代路线
│ └── mimo-provider.md ← MiMo 模型 API 配置、SSE 解析
│
├── chat-model/ ← 聊天领域模型 + 数据流
│ └── overview.md ← Part 消息内容体系、JSON 持久化、扩展步骤
│
├── voice/ ← 语音识别
│ └── overview.md ← sherpa-onnx 集成、模型下载、assets 结构
│
├── vault/ ← Obsidian 知识库集成
│ ├── overview.md ← 技术选型（JGit vs GitHub API）、实施路线
│ └── agent-knowledge-todo.md ← Agent × Vault 知识库集成 TODO 计划
│
├── ui-compose/ ← UI 框架 + Compose 模式
│ ├── side-effects.md ← LaunchedEffect vs rememberCoroutineScope
│ └── edge-to-edge.md ← 沉浸式适配、系统栏处理
│
├── build-toolchain/ ← 构建、测试、依赖管理
│ ├── overview.md ← Gradle 命令、测试框架、Version Catalog
│ ├── gradle-pipeline.md ← assembleDebug 流水线拆解、jlink 排查
│ └── troubleshooting.md ← SDK package.xml 损坏等构建异常修复
│
└── code-standards/ ← 代码风格 + 提交规范
├── style-guide.md ← Kotlin/Compose 编码规范
└── commit-conventions.md ← 分支策略、提交信息格式
| 功能域 | 涉及的代码路径 |
|---|---|
agent-llm |
app/src/.../agent/ |
chat-model |
app/src/.../chat/（领域模型）、app/src/.../data/（Room 持久化） |
voice |
app/src/.../voice/ |
vault |
app/src/.../vault/ |
ui-compose |
app/src/.../chat/（UI 组件）、app/src/.../drawer/、app/src/.../markdown/、app/src/.../ui/theme/ |
build-toolchain |
build.gradle.kts、gradle/libs.versions.toml、scripts/ |
code-standards |
全局适用 |
| 想了解… | 去看 |
|---|---|
| 整体分层和包结构 | architecture.md |
| AG-UI 事件怎么流转 | agent-llm/overview.md |
| 怎么加新 Part 类型 | chat-model/overview.md |
| 语音模型怎么配置 | voice/overview.md |
| Vault 集成方案和选型 | vault/overview.md |
| Agent × Vault 知识库集成计划 | vault/agent-knowledge-todo.md |
| Compose 副作用怎么写 | ui-compose/side-effects.md |
| 构建失败怎么排查 | build-toolchain/troubleshooting.md |
| 提交信息怎么写 | code-standards/commit-conventions.md |
- 文件名：小写英文 + 连字符（
side-effects.md） - 目录深度：最多 3 层（
docs/<domain>/<file>.md） - 每个功能域目录以
overview.md为入口 - 跨域内容在文档开头注明关联域：
> 关联域：[agent-llm](agent-llm/overview.md)