easysdd-libdoc
guidedoc 教你"怎么用 X 做 Y"，libdoc 告诉你"X 的每个零件长什么样、怎么配"。两者性质完全不同，写法、信息源、粒度都不一样。
guidedoc 写错可能是表达不清，libdoc 写错就是错——因为它的信息源是源码本身，类型、默认值、签名都有唯一正确答案。libdoc 的核心规则是不靠猜、不复制改名、每个条目独立读源码。
和 guidedoc 的对比
| guidedoc | libdoc | |
|---|---|---|
| 性质 | 任务导向（Tutorial / How-to） | 参考导向（Reference） |
| 回答 | "如何用 X 实现某个目标" | "X 的每个零件长什么样、怎么配" |
| 粒度 | 一个 feature / 一个场景一篇 | 一个条目（组件/函数/命令）一篇 |
| 信息源 | 方案 doc + 用户知识 | 源码本身（类型定义、注释、默认值） |
| 数量级 | 几篇到十几篇 | 几十到上百篇 |
互补：guide 引用 libdoc 条目做详细参考（"完整 props 见 xxx"），libdoc 条目的"相关条目"链回对应 guide。
什么是"条目（entry）"
条目是 libdoc 的原子文档单位，粒度由项目类型决定：
| 项目类型 | 条目粒度 |
|---|---|
| UI 组件库 | 一个组件 = 一个条目 |
| 工具函数库 | 一个模块或函数族 = 一个条目 |
| API Client | 一个 endpoint 族 = 一个条目 |
| CLI 工具 | 一个子命令 = 一个条目 |
初始化阶段确认条目粒度，后续保持一致——粒度变来变去，清单和搜索都会乱。
涉及路径
libdoc 产物不在 easysdd/ 下——API 参考是面向外部读者的可发布产物。
- 条目文档 →
docs/api/{slug}.md - 条目清单 →
docs/api/manifest.yaml
docs/api/ 是默认约定，项目已有其他约定（reference/、components/）就以项目为准——开始前先确认。
manifest / 模板 / 源码提取
参考材料已拆到同目录 reference.md：
manifest.yaml完整格式与 status 语义- 条目文档的 frontmatter 和正文模板
- 源码提取清单（接口签名、默认值、导出方式等）
本技能正文只保留流程约束：libdoc 以源码为事实源，不靠猜，不复制上一个条目改名。
工作流
Phase 1：初始化——扫描与清单
目标：产出条目清单，锁定文档范围。
- 确认项目类型和条目粒度——这是什么类型的库？条目粒度是什么？输出路径用
docs/api/还是项目已有约定？ - 扫描源码目录——读
source_root下的文件结构，识别公开导出，按逻辑分组 - 生成
manifest.yaml——所有条目初始status: pending；落盘后用validate-yaml.py --file docs/api/manifest.yaml --yaml-only校验语法；展示给用户 review - 用户确认范围——用户可标
skipped（内部实现）、调整分类、合并或拆分；确认后清单落盘
Phase 2：生成——单条目 or 批量
模式 A：单条目模式
适用于 1-3 个条目，或首次试跑确认质量。
- 选定条目 → 读 source_files → 按模板生成 → 用户 review → 落盘
- 落盘后
validate-yaml.py --file {条目文档路径} --require doc_type --require entry --require status校验 - 更新
manifest.yaml对应条目status: current
模式 B：批量模式
适用于清单里有大量 pending 条目。
- 先出样板——从清单中选 2-3 个有代表性的条目（不同 category），按"读源码 → 提取 → 按模板生成"走一遍并落盘，状态先标
draft（不直接进 current——批量模式下样板的角色是"风格参考样本"，要等整体 review 一起转 current） - 用户确认质量标准——review 这 2-3 篇，确认模板、详略度、风格符合预期。这一步不能跳——50 篇全白写就因为用户想要的风格不一样
- 批量生成——剩余
pending条目逐条走"读源码 → 提取 → 生成"，可用 subagent 并行；每条生成后status: draft - 整体 review——批量完成展示概况（条目数、跳过数、待确认数）；review 前先
validate-yaml.py --dir docs/api --require doc_type --require entry --require status批量校验，有报错先修 - 确认落定——用户确认后把样板和批量产出一起批量改
status: current
批量模式硬规则：
- 每个条目独立读源码——即使批量也不允许复制上一个条目内容改名。两个看起来很像的接口经常有微妙差异，复制改名一定会漏掉
- 样板确认不可跳——理由见上
- 源码结构特殊（动态导出、代码生成）暂标
skipped加 note——硬猜出来的文档比没文档更有害
Phase 3：增量更新
代码变更后同步文档。
- 找出要更新的条目，三种入口任选：
- search-yaml.py 搜 status=outdated ——架构 check 或上次更新已经标记的 - 对比 manifest.yaml 里 last_scanned 之后变更的源码文件 - search-yaml.py --sort-by last_reviewed --order asc 按最久没复核的排在前，挑"应该看一下是不是还准"的条目主动复核
- 重新读源码 → 对比已有文档 → 增量更新变化部分
validate-yaml.py校验，确认 frontmatter 未被破坏status: current，last_reviewed填当天
与其他工作流的关系
| 来源 | 关系 |
|---|---|
easysdd-feature-acceptance | 验收后若新增/修改库公开接口 → 推送"需要更新 libdoc 吗？" |
easysdd-guidedoc | guide 引用 libdoc 做详细参考；libdoc "相关条目"链回 guide |
easysdd-architecture (check 模式) | 它检测到接口变更但 libdoc 未同步时，会把对应条目标成 outdated，本技能 Phase 3 据此处理 |
easysdd-feature-design | 方案第 2 节可作 libdoc 补充信息源（但以源码为准） |
easysdd-tricks | libdoc "注意事项"与 tricks 重合时交叉引用而不重复写 |
退出条件
Phase 1
manifest.yaml已落盘- 用户已确认条目范围（含 skipped 理由）
- 条目粒度和输出路径已确认
Phase 2 单条目
- 条目文档按模板生成，含完整 frontmatter
- API 参考节信息来源于源码提取（非编造）
- 用户确认
manifest.yaml对应条目 status 已更新
Phase 2 批量
- 样板（2-3 篇）已获用户确认
- 所有 pending 条目已生成或标 skipped
- 用户做了整体 review
manifest.yaml所有条目 status 已同步
Phase 3
- outdated 条目已全部更新或确认不需更新
manifest.yaml无残留 outdated（除非用户明确暂缓）
容易踩的坑
- ❌ 没扫清单就写文档——可能遗漏条目或重复写
- ❌ 没读源码就写 API 参考——libdoc 的核心价值是准确反映源码
- ❌ 复制上一个条目改改名字算下一个——必然漏掉微妙差异
- ❌ 批量模式跳过样板确认——50 篇全白写
- ❌ 把 spec 信息（不变量、测试约束）写进 libdoc——属于
easysdd/ - ❌ libdoc 和 guidedoc 内容高度重叠——重叠说明其中一份定位有误
- ❌
manifest.yaml直接删行——改status: skipped并写 note - ❌ 源码接口不存在却在文档里写了——以源码为事实源，不编造