Appearance
AI Agent — 文档组织结构说明
本文档面向参与项目开发的 AI Agent，说明项目的文档组织结构，以便 Agent 正确理解和操作项目文档。
文档组织结构
层级关系
docs/ai-agent/
├── index.md ← 本文档：文档组织结构说明
├── skills/ ← AI 技能库（跨版本通用）
│ └── index.md ← 技能库索引
└── v4/ ← v4 主线版本开发文档
├── index.md ← 版本文档索引
├── design/ ← 架构/功能设计文档
├── plans/ ← 开发计划文档
├── tests/ ← 测试文档
├── discussions/ ← 讨论记录文档
├── logs/ ← 开发日志
└── bugs/ ← 缺陷修复文档文档类型与规范
| 文档类型 | 目录 | 更新策略 | 说明 |
|---|---|---|---|
| AI 技能库 | skills/ | 持续更新 | 跨版本通用的最佳实践和规范 |
| 设计文档 | v4/design/ | 持续更新 | 保持最新，清理过时内容 |
| 测试文档 | v4/tests/ | 持续更新 | 只有软件验收员才能编写和更新测试用例 |
| 计划文档 | v4/plans/ | 持续更新 | 保持最新，清理已完成 / 过时内容 |
| 讨论记录 | v4/discussions/ | 只追加 | 历史记录，不对已有内容做更新 |
| 开发日志 | v4/logs/ | 只追加 | 历史记录，不对已有内容做更新 |
| 缺陷修复 | v4/bugs/ | 只追加 | 历史记录，不对已有内容做更新 |
文件命名规范
design/、plans/、discussions/目录下的文档以 三位数字 开头并根据内容确定文件名- 示例：
000-architecture-overview.md、100-keyboard-state-machine.md
- 示例：
logs/目录下的文档按 年 组织子目录，以 月-日 命名（月和日采用两位数字）- 示例：
2026/05-12.md
- 示例：
bugs/目录下的文档以 三位数字 开头和缺陷简要描述命名- 示例：
001-input-list-concurrent-modification.md
- 示例：
文档编写规范
中英文间距（参考 Snapmaker 中文写作风格指南 2.3）：
- 基本规则：汉字与西文（英文字母、数字）之间始终保留一个空格；西文与西文之间不加空格
- 正确：
使用 Kotlin 2.3.20 进行开发、第 3 步、MVI 架构 - 错误：
使用Kotlin 2.3.20进行开发、第3步、MVI架构
- 正确：
- 符号视作西文：百分号（%）、连字符（-）、斜杠（/）、加号（+，表非运算时）、冒号（:）、点（.）等符号与汉字之间空一格，与西文之间不空格
- 正确：
设置能量为 30%、输入 - 按键 - 反馈布局 - 错误：
设置能量为 30 %、输入-按键-反馈布局
- 正确：
- 运算符号前后各空一格：加号（+）、减号（−）、乘号（×）、除号（÷）、等于号（=）等运算符号前后无论汉字还是西文均空一格
- 正确：
300mm × 200mm × 200mm
- 正确：
- 型号与规格视作西文：版本号（V1.3.0）、尺寸（10mm-20mm）、型号（A350、M4×8）等整体视作西文，与汉字之间空一格，内部不加空格
- 日期数字视作西文：遵循与汉字（"年""月""日"）之间空一格的规则
- 正确：
2020 年 12 月 24 日
- 正确：
- 不适用的情况：
- 中文字符与标点符号（中文或英文标点）之间不需要加空格
- 代码块内的代码不受此规则约束
- 字符替换占位符（如
%s、%d、{0}等）与相邻中文之间不加空格 - 表示路径、目录、文件名的文本内部不加空格（如
values/文件夹、月-日命名格式）
- 适用范围：Markdown 文档、PlantUML 图表中的标签和注释、源码中的注释和中文文本字符串、配置与国际化资源文件中的文本
- 基本规则：汉字与西文（英文字母、数字）之间始终保留一个空格；西文与西文之间不加空格
PlantUML 语法注意事项：
- 混用类图与用例图：同一图表中同时使用
class/package和usecase时，必须在@startuml后添加allowmixing指令，否则渲染报错 - 跨分区注释：
note across只能用于泳道图（|分区|），非泳道图的分区注释应使用note bottom of <element>或note right of <element> - 多行方法体：类成员中的多行方法体不能直接换行书写，需用
\n转义为单行字符串，如dispatchToTarget(output) : {\n when(output) {\n ...\n }\n} - 外部文件导入：在 Markdown 中嵌入 PlantUML 必须使用
plantuml代码块 +@file:语法（而非> @file:引用块），否则 vitepress-plugin-diagrams 无法识别和渲染- 正确：以
```plantuml开头的代码块，内含@file:../diagrams/architecture.puml - 错误：
> @file:../diagrams/architecture.puml（引用块语法不会被插件处理）
- 正确：以
- PUML 中的
\n不是英文：\n是 PlantUML 的换行转义序列，不是英文字母，其与相邻中文之间不加空格
- 混用类图与用例图：同一图表中同时使用
Markdown 语法注意事项：
- 尖括号被识别为 HTML 标签：当
<...>成对出现时（如泛型StateFlow<ImeState>），Markdown 解析器会将其视为 HTML 标签并吞没内容。必须用反引号包裹：`StateFlow<ImeState>` - 文档交叉引用：
- 使用相对路径链接，不要使用「文档 160」「文档 800」等抽象编号
- 文件重命名后必须同步更新所有引用该文件的链接
- 跨目录引用注意相对路径层级（如从
architecture/引用engine/的文件需用../engine/）
- 尖括号被识别为 HTML 标签：当
参考工作树
| 工作树 | 分支 | 用途 |
|---|---|---|
kotlin/ | refactor-kotlin | 工作目录：Kotlin 版本的开发在此进行 |
java/ | java-frozen | 只读参考：Java 版本代码，仅在需要时查阅 |
重要：
java/工作树为只读，仅用于在需要时查阅 Java 版本的代码。不要修改 java 工作树中的任何文件。