eo-doc-manager · diff
git:20260724.2f43c94 to git:20260901.016f129
49 added, 114 removed. Audit A to A.
---
name: eo-doc-manager
- description: 管理 eo-doc/ 代码侧文档体系（init / sync / re-sync / modify / select）。所有 eo-doc 下的文档维护操作必须走此 skill。触发：初始化文档 / 同步文档 / 重建文档 / re-sync / 修改文档 / 整理文档 / 只同步 state 或 agent-handbook / /eo-doc-manager。NOT FOR：查询与解释文档内容（走 /eo-recall）。
+ description: 管理 eo-doc/ 代码侧文档体系（init / modify / sync）：维护 changes/INDEX.md、agent-handbook/ 规范篇与 templates/；`state.enabled` 时cursor 增量再生 state/ 现状篇。所有 eo-doc 下的文档维护操作必须走此 skill。触发：初始化文档 / 修改文档 / 整理文档 / 同步文档 / /eo-doc-manager。NOT FOR：查询与解释文档内容（走 /eo-recall）。
---
# eo-doc-manager
**代码侧**文档管理。项目管理侧（roadmap / decisions / lessons / design / docs）由 `eo-project-*` skill 管。
## 前置
除 `init` 外的所有命令必须能找到 `.eo-project.json`（cwd 或父目录）。同目录存在 `.eo-project.local.json` 时顶层字段覆盖合并（local 优先）。找不到 → 报错退出，提示运行 `/eo-project-init`。
`init` 通常由 `/eo-project-init` 内部调用；用户直接调用 `/eo-doc-manager init` 时，若 `.eo-project.json` 不存在会提示先走 `/eo-project-init`。
## 命令路由
| 命令 | 触发词 | 流程 |
|------|--------|------|
- | `init` | 初始化文档、init docs | 创建 eo-doc/ 最小骨架（3 个必建目录） |
- | `modify` | 修改文档、结构化、整理 | 分流到 agent-handbook / state → 更新 INDEX.md |
- | `sync` | 同步文档、sync docs、更新文档 | git diff 增量 → 更新 agent-handbook/ + state/ |
- | `re-sync` | 重建文档、全量同步 | 全量扫描源码 → 重建 agent-handbook/ + state/ |
- | `select` | 只操作 agent-handbook / state | 缩小作用域 → 后续命令 |
+ | `init` | 初始化文档、init docs | 创建 eo-doc/ 最小骨架（changes/ + agent-handbook/INDEX + templates/） |
+ | `modify` | 修改文档、整理文档 | 维护 changes/INDEX.md / agent-handbook/ 规范篇 / templates/ |
+ | `sync` | 同步文档、同步 state、重新生成现状文档 | cursor 增量再生 `state/` 现状篇（需 `state.enabled`，流程见下） |
- > 「查文档 / 当时怎么设计的 / 这个逻辑怎么实现的」→ 走 `/eo-recall`（本 skill 不再提供 query，回归纯维护职责）。
+ > 「查文档 / 当时怎么设计的 / 这个逻辑怎么实现的」→ 走 `/eo-recall`（本 skill 不提供 query，回归纯维护职责）。
**路由规则**：
- 1. 明确命令（如 `/eo-doc-manager sync`） → 直接路由
+ 1. 明确命令 → 直接路由
2. 自然语言 → 按触发词匹配
3. 无法判断 → 列出可用命令
## 目录结构（代码侧 `eo-doc/`）
- 所有文档存放在项目根目录 `eo-doc/` 下（**无顶级 INDEX.md**；CLAUDE.md 中的目录表即一级索引）：
+ 所有文档存放在项目根目录 `eo-doc/` 下（**无顶级 INDEX.md**；agent 配置注入段中的目录表即一级索引）：
```text
eo-doc/
- ├── agent-handbook/ # 必建，代码架构（AI 地图）
- │ └── INDEX.md
- ├── changes/ # 必建，change 工件流（由 eo-* 工作流 skill 维护）
- │ └── INDEX.md
- ├── templates/ # 必建（空），eo-* 技能扩展点
- ├── state/ # 按需，系统当前状态（首次 sync 时 lazy 建）
- │ └── INDEX.md
- └── .sync-cursor # sync 基线与计数（随 eo-doc/ 入库，不进 .gitignore）
+ ├── changes/ # 必建，change 工件流（子目录由 eo-* 工作流 skill 产出）
+ │ └── INDEX.md # 项目级 change 时间线
+ ├── agent-handbook/ # 可选，Agent 操作手册（篇目含 INDEX.md）
+ ├── state/ # 可选（`state.enabled` 时由 sync 增量再生维护）
+ └── templates/ # 必建（空），eo-* 技能扩展点
```
- ### 不处理的旧目录
+ ### 不处理的历史目录
- 遇到 `eo-doc/` 下存在 `doc/`、`dev/`、`design/`、`research/`、`knowledgebase/` 时：**不读取、不重建、不同步**，口头提示用户「这是 v1 遗留目录，处理方式见 eo-skills 仓库的 docs/migration-v1-to-v2.md（迁移指南）」。
+ `eo-doc/` 下可能存在的历史目录（`doc/`、`dev/`、`design/`、`research/`、`knowledgebase/`）：**不读取、不重建、不删除**，仅供历史查阅；v1 遗留的迁移处理见 eo-skills 仓库的 docs/migration-v1-to-v2.md。
+ `state/` 单独处置：配置 `state.enabled: true` → 由本 skill `sync` 维护的活文档层；未启用 → 视同历史目录冻结留存（不删除）。
## 目录职责
- | 目录 | 职责 | 面向 | 核心问题 | type 值 |
- |------|------|------|----------|---------|
- | `agent-handbook/` | 代码架构 — 模块入口、接口索引、依赖关系 | AI | "代码**怎么**组织的？" | `agent` |
- | `changes/` | change 工件流 — 每次变更的 change/review/test 产出 | 都 | "变更**进行**到哪了？" | — |
- | `state/` | 当前实现 — 系统实际做了什么，业务规则、状态流转、配置 | 人 | "系统**现在**是什么样？" | `state` |
- | `templates/` | eo-* 技能的扩展点 — 项目类型、工作流定制 | AI | "项目**怎么**定制？" | — |
-
- ### 关键区分
+ | 目录 | 职责 | 面向 | 核心问题 |
+ |------|------|------|----------|
+ | `changes/` | change 工件流 — 每次变更的 change/review/test 产出 | 都 | "变更**进行**到哪了？" |
+ | `agent-handbook/` | Agent 操作手册 — 相对固定的操作规范（worktree 协作 / 架构分工 / 目录约定 / UI token 用法 / agent 协作），非 SSOT（代码为准），不挂自动同步 | AI | "操作时按什么**规范**？" |
+ | `state/` | 业务现状活文档 — 模块现状篇（`state.enabled` 时存在），代码为唯一信源cursor 增量再生，非 SSOT | 都 | "系统**现在**是什么样？" |
+ | `templates/` | eo-* 技能的扩展点 — 项目类型、工作流定制 | AI | "项目**怎么**定制？" |
- **state vs agent-handbook**：
- - state = 给人看的系统描述（业务规则、状态流转、配置含义）
- - agent-handbook = 给 AI 看的代码地图（文件入口、接口签名、依赖关系）
- - state 回答"系统做了什么"，agent-handbook 回答"代码在哪里、怎么调用"
+ **changes/**：
+ - 子目录由 eo-change、eo-implement、eo-review、eo-archive 等技能按约定产出
+ - 本 skill 负责 `changes/INDEX.md` 的整理与修复（条目对应、孤儿清理、seq 查重）
**templates/**：
- 不是文档，是 eo-* 技能的扩展点（如项目类型画像 `project-profile.md`）
- 模板可选，不存在时 eo-* 技能使用内置默认行为
- - sync / re-sync 不处理 templates/（它们不是从源码生成的）
-
- **changes/**（v2，取代原 dev/）：
- - 子目录由 eo-change、eo-implement、eo-review、eo-archive 等技能按约定产出
- - changes/ 不参与 sync / re-sync，由开发流程技能管理
-
- ## 代码优先原则
-
- state/ 和 agent-handbook/ 的内容必须从**源码**生成，不是从已有文档迁移。
-
- **正确路径**：读源码 → 提取模块/接口/规则 → 生成文档 → 最后参考旧文档补充人工业务背景
- **禁止路径**：读旧文档 → 改格式/改名 → 放入 eo-doc/（这是迁移，不是生成）
-
- 此原则适用于 init 和 re-sync。sync 是增量更新，不受此约束。
-
- ## state/ 写作规范
-
- 见 [references/doc-style.md](references/doc-style.md)。
+ - 由项目按需自建，本 skill 只建空目录、不生成模板内容
## 核心工作流
### init — 初始化最小骨架
通常由 `/eo-project-init` 内部调用。直接调用时：
1. 检查 `.eo-project.json` 是否存在；不存在 → 提示先走 `/eo-project-init` 并退出
2. 读取 `.eo-project.json` 的 `doc_root`（默认 `eo-doc`）作为根
3. 创建最小骨架：
- - `<doc_root>/agent-handbook/INDEX.md`（骨架）
- `<doc_root>/changes/INDEX.md`（骨架）
+ - `<doc_root>/agent-handbook/INDEX.md`（骨架；篇目内容由 /eo-project-init 的 handbook 初始化流程按需产出）
- `<doc_root>/templates/`（空目录，不自动生成模板文件）
- 4. **不创建** `state/`（首次 sync 时 lazy 建）
- 5. 初始化 `<doc_root>/.sync-cursor`（当前 HEAD 作为首次基线）——**随 `<doc_root>/` 入库，不写进 `.gitignore`**（理由与合并冲突处理见 [references/git-sync.md](references/git-sync.md)）
- 6. CLAUDE.md 注入（见下方"CLAUDE.md 注入规则"）
- 8. **不自动生成 state/ 和 agent-handbook/ 内容**——留待 `/eo-doc-manager sync` 或 `re-sync` 首次触发
-
-
- ### modify — 修改/创建文档
-
- 1. **分析输入**：识别输入类型（单篇/多篇/更新已有）
- 2. **分流**：判断归属 `agent-handbook/` 还是 `state/`（参考 [splitting.md](references/splitting.md)）
- 3. **拆分**：同目录内按主题拆分（参考 [splitting.md](references/splitting.md)）
- 4. **结构化**：按模板格式化（参考 [templates.md](references/templates.md)）
- 5. **更新子目录 INDEX.md**
- 6. **验证**：frontmatter 完整、INDEX 对应、行数达标
-
- ### sync — 增量同步
-
- 基于 git diff 将代码变更同步到 state/ 和 agent-handbook/。完整流程见 [git-sync.md](references/git-sync.md)。
-
- 要点：
- 1. 读 `.sync-cursor` 取上次同步 commit，范围 = `<last_commit>..HEAD`
- 2. **工作区有脏变更时问用户三选一**（默认推荐：只取已提交增量，不扫脏变更；详见 git-sync.md）
- 3. **diff 分析排除 `eo-doc/` 路径**（change/INDEX 等元数据提交直接跳过）
- 4. 同时更新 `agent-handbook/`（代码地图）与 `state/`（系统现状，不存在则首次 lazy 建）
- 5. 更新受影响 INDEX.md → cursor 推进到 HEAD，`sync_count` +1
- 6. 汇报变更；`sync_count` 达到阈值（5）→ 提示做一次一致性抽查（见 [maintenance.md](references/maintenance.md)），完成后计数清零
-
- **触发点有两个**：用户手动 `/eo-doc-manager sync`，以及 `/eo-archive` 归档第四层的内嵌调用——同一机制、同一游标，无独立的按 change 定界模式。
-
- ### re-sync — 全量重建
-
- 参考 [re-sync.md](references/re-sync.md)。
-
- 1. 扫描全部源码
- 2. **重建** agent-handbook/ 和 state/（清空后重新生成）
- 3. 更新 CLAUDE.md 注入
- 4. 重置 `.sync-cursor`
-
-
- ### select — 选择性操作
+ 4. 注入段刷新（见下方「注入规则」）
- 1. 解析指定目录（`agent-handbook` / `state`）
- 2. 将后续命令作用域限制到指定目录
- 3. 组合：`select state sync`（只同步 state/）
+ ### modify — 维护 changes/INDEX.md、agent-handbook/ 与 templates/
- ## 结构化规则
+ 1. **changes/INDEX.md 整理**：条目与 `changes/` 子目录一一对应（无孤儿、无漏收），状态/摘要列与各 change.md frontmatter 一致；seq 列顺手查重（重号 → created 晚者让号，见 [../eo-shared/conventions.md](../eo-shared/conventions.md) §2）
+ 2. **agent-handbook/ 篇目维护**：按用户输入或 init 扫描结果创建/修改规范篇；内容不从源码生成、不挂自动同步；只写方向性规范，细节判断交运行时
+ 3. **templates/ 管理**：按用户输入创建/修改项目定制模板；模板内容来自用户输入，不从源码生成
+ 4. **验证**：INDEX 与目录一一对应、交叉引用指向真实存在的文件
+ ### sync — cursor 增量再生 state/ 现状篇
- frontmatter 规格与正文结构以 [references/templates.md](references/templates.md) 为唯一来源（要点：frontmatter 含 type/tags/summary/conclusions 供 AI 免读全文判断相关性；正文 `##` 扁平章节、自包含可扫读）。
+ 前置：合并配置 `state.enabled: true`；未启用 → 告知该层未开启（可由 `/eo-project-init` 更新分支开启）并退出。
- ### 拆分规则
+ **机制**：单游标、单机制——游标文件 `eo-doc/.sync-cursor`（YAML：`last_commit` / `sync_count` / `archive_count`）记录上次同步到的 commit；每次 sync 只处理 `cursor..HEAD` 的已提交增量，完成后推进游标到 HEAD。archive 收口与手动调用是**同一机制的两个触发点**；不提供按 change 定界的 range 同步（range 不动游标会被下次重扫，动游标会跳过区间外交错的直改/其他 change 提交）。
- 参考 [splitting.md](references/splitting.md)。
+ 1. **读游标**：`.sync-cursor` 不存在 → 首次 sync = 全量生成（全部模块逐篇生成），完成后写游标 = HEAD
+ 2. **脏变更三选项**（检测到工作区脏时按封闭选择协议问）：① 只取 cursor..HEAD 增量，不扫脏变更（默认推荐——脏变更提交后自然被下次 sync 覆盖）② 含脏变更一起同步（代码即将定稿时用）③ 全部重扫（等价重新首同步，游标仍推进到 HEAD）
+ 3. **算增量**：`git diff --name-only <cursor>..HEAD`；**排除 `eo-doc/` 路径**（归档元数据等纯文档提交直接跳过，不做影响分析）
+ 4. **路径映射模块**：按 `agent-handbook/architecture.md` 的划分（无该篇则按顶层目录）把变更文件映射到受影响模块集合；映射不到任何模块的路径（根配置等）→ 速报列出并跳过
+ 5. **逐受影响模块读码重写** `state/<module>.md`（未受影响的篇不动）：
+ - 篇头：`> 非 SSOT：代码为准，本篇为派生快照｜基线 <commit-short-sha>｜last_sync <date>｜由 /eo-doc-manager sync 生成`
+ - 三节：**入口**（主要文件/符号）、**行为契约**（对外可观测行为与规则）、**依赖**（依赖谁、被谁依赖）
+ 6. **孤儿篇处置**：模块已不存在的存量篇 → 列出并请用户确认后删除
+ 7. **推进游标**：`.sync-cursor` 写入新 HEAD 并累计 `sync_count`；archive 联动触发的本次另累计 `archive_count`
+ 8. **一致性抽查**：`sync_count` 每满 5 → 抽查 state ↔ agent-handbook 同源文档是否前后矛盾、篇头与正文是否漂移，只报告不自动改
+ 9. **速报**：触达 N 篇（模块清单）/ 删除 M 篇 / 游标 `<old-sha>..<new-sha>`
## INDEX.md 规范
见 [references/index-templates.md](references/index-templates.md)。
- ## CLAUDE.md 注入规则
+ ## 注入规则
见 [references/claude-injection.md](references/claude-injection.md)。
## 验证清单
每次操作后：
- - [ ] 每篇文档 frontmatter 完整
- - [ ] 子目录 INDEX.md 与目录内文档一一对应
- - [ ] 单篇不超 500 行（超出建议拆分）
- - [ ] 标签体系统一（无近义重复）
+ - [ ] `changes/INDEX.md` 与 `changes/` 子目录一一对应
- [ ] 所有交叉引用指向真实存在的文件
- ## Token 效率准则
-
- - frontmatter summary 让 AI 不读全文即可判断相关性
- - conclusions 数组支持快速提取要点
- - INDEX.md 表格每条约 50 token，可一次扫描整个集合
- - `##` 扁平结构，避免深层嵌套
-
## 维护协议
- 参考 [maintenance.md](references/maintenance.md)：
- - 更新工作流（新增/修改/批量导入）
- - state↔agent-handbook 一致性检查
- - 臃肿检测与重组
- - 归档流程
+ 参考 [maintenance.md](references/maintenance.md)。