cs-libdoc

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

cs-libdoc

guidedoc 教你"怎么用 X 做 Y"，libdoc 告诉你"X 的每个零件长什么样、怎么配"。两者性质完全不同，写法、信息源、粒度都不一样。

guidedoc 写错可能是表达不清，libdoc 写错就是错——因为它的信息源是源码本身，类型、默认值、签名都有唯一正确答案。libdoc 的核心规则是不靠猜、不复制改名、每个条目独立读源码。

guidedoc teaches you "how to use X to do Y", while libdoc tells you "what each part of X looks like and how to configure it". The two are completely different in nature, with different writing styles, information sources, and granularities.

guidedoc being wrong may be due to unclear expression, but libdoc being wrong is a factual error — because its information source is the source code itself, and there is only one correct answer for types, default values, and signatures. The core rule of libdoc is no guessing, no copying and renaming, and reading the source code independently for each entry.

和 guidedoc 的对比

Comparison with guidedoc

	guidedoc	libdoc
性质	任务导向（Tutorial / How-to）	参考导向（Reference）
回答	"如何用 X 实现某个目标"	"X 的每个零件长什么样、怎么配"
粒度	一个 feature / 一个场景一篇	一个条目（组件/函数/命令）一篇
信息源	方案 doc + 用户知识	源码本身（类型定义、注释、默认值）
数量级	几篇到十几篇	几十到上百篇

互补：guide 引用 libdoc 条目做详细参考（"完整 props 见 xxx"），libdoc 条目的"相关条目"链回对应 guide。

	guidedoc	libdoc
Nature	Task-oriented (Tutorial / How-to)	Reference-oriented (Reference)
Answer	"How to achieve a goal with X"	"What each part of X looks like and how to configure it"
Granularity	One per feature / one per scenario	One per entry (component/function/command)
Information Source	Solution docs + user knowledge	Source code itself (type definitions, comments, default values)
Quantity	A few to a dozen	Dozens to hundreds

Complementary: Guides reference libdoc entries for detailed references ("See xxx for complete props"), and libdoc entries link back to corresponding guides in the "Related Entries" section.

什么是"条目（entry）"

What is an "entry"

条目是 libdoc 的原子文档单位，粒度由项目类型决定：

项目类型	条目粒度
UI 组件库	一个组件 = 一个条目
工具函数库	一个模块或函数族 = 一个条目
API Client	一个 endpoint 族 = 一个条目
CLI 工具	一个子命令 = 一个条目

初始化阶段确认条目粒度，后续保持一致——粒度变来变去，清单和搜索都会乱。

An entry is the atomic documentation unit of libdoc, and its granularity is determined by the project type:

Project Type	Entry Granularity
UI Component Library	One component = one entry
Utility Function Library	One module or function family = one entry
API Client	One endpoint family = one entry
CLI Tool	One subcommand = one entry

Confirm the entry granularity during the initialization phase and keep it consistent later — changing granularity will disrupt the manifest and search.

涉及路径

Involved Paths

libdoc 产物不在
codestable/
下——API 参考是面向外部读者的可发布产物。

条目文档 →
```
docs/api/{slug}.md
```
条目清单 →
```
docs/api/manifest.yaml
```

docs/api/

是默认约定，项目已有其他约定（

reference/

、

components/

）就以项目为准——开始前先确认。

libdoc outputs are not under
codestable/
— API references are publishable products for external readers.

Entry documentation →
```
docs/api/{slug}.md
```
Entry manifest →
```
docs/api/manifest.yaml
```

docs/api/

is the default convention; if the project already has other conventions (such as

reference/

components/

), follow the project's existing rules — confirm this before starting.

manifest / 模板 / 源码提取

manifest / Template / Source Code Extraction

参考材料已拆到同目录

reference.md

：

```
manifest.yaml
```
完整格式与 status 语义
条目文档的 frontmatter 和正文模板
源码提取清单（接口签名、默认值、导出方式等）

本技能正文只保留流程约束：libdoc 以源码为事实源，不靠猜，不复制上一个条目改名。

Reference materials have been split into

reference.md

in the same directory:

Complete format and status semantics of
```
manifest.yaml
```
Frontmatter and body template for entry documentation
Source code extraction checklist (interface signatures, default values, export methods, etc.)

This skill's main body only retains process constraints: libdoc uses source code as the source of truth, no guessing, no copying and renaming the previous entry.

工作流

Workflow

Phase 1：初始化——扫描与清单

Phase 1: Initialization — Scanning and Manifest

目标：产出条目清单，锁定文档范围。

确认项目类型和条目粒度——这是什么类型的库？条目粒度是什么？输出路径用
```
docs/api/
```
还是项目已有约定？
扫描源码目录——读
```
source_root
```
下的文件结构，识别公开导出，按逻辑分组

生成
manifest.yaml
——所有条目初始

status: pending

；落盘后用

validate-yaml.py --file docs/api/manifest.yaml --yaml-only

校验语法；展示给用户 review

用户确认范围——用户可标
```
skipped
```
（内部实现）、调整分类、合并或拆分；确认后清单落盘

Goal: Produce the entry manifest and lock the documentation scope.

Confirm project type and entry granularity — What type of library is this? What is the entry granularity? Use
```
docs/api/
```
or the project's existing convention for the output path?
Scan the source code directory — Read the file structure under
```
source_root
```
, identify public exports, and group them logically
Generate
manifest.yaml
— All entries are initially
```
status: pending
```
; after saving to disk, validate the syntax with
```
validate-yaml.py --file docs/api/manifest.yaml --yaml-only
```
; show it to the user for review
User confirms the scope — The user can mark entries as
```
skipped
```
(internal implementation), adjust categories, merge or split entries; save the manifest to disk after confirmation

Phase 2：生成——单条目 or 批量

Phase 2: Generation — Single-entry or Batch

模式 A：单条目模式

Mode A: Single-entry Mode

适用于 1-3 个条目，或首次试跑确认质量。

选定条目 → 读 source_files → 按模板生成 → 用户 review → 落盘

落盘后

validate-yaml.py --file {条目文档路径} --require doc_type --require entry --require status

校验

更新
```
manifest.yaml
```
对应条目
```
status: current
```

Suitable for 1-3 entries, or initial trial runs to confirm quality.

Select an entry → Read source_files → Generate according to the template → User review → Save to disk

After saving, validate with

validate-yaml.py --file {entry documentation path} --require doc_type --require entry --require status

Update the corresponding entry's
```
status: current
```
in
```
manifest.yaml
```

模式 B：批量模式

Mode B: Batch Mode

适用于清单里有大量

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——硬猜出来的文档比没文档更有害

Suitable for a large number of

pending

entries in the manifest.

First create samples — Select 2-3 representative entries (different categories) from the manifest, go through "read source code → extract → generate according to template" and save them to disk, mark the status as
```
draft
```
first (do not directly set to current — in batch mode, samples serve as "style reference samples" and should be changed to current only after overall review)
User confirms quality standards — Review these 2-3 entries to confirm that the template, level of detail, and style meet expectations. This step cannot be skipped — 50 entries will be wasted if the user wants a different style
Batch generation — Process the remaining
```
pending
```
entries one by one through "read source code → extract → generate", subagents can be used for parallel processing; mark each generated entry as
```
status: draft
```
Overall review — After batch generation, show an overview (number of entries, number of skipped entries, number of pending confirmation entries); before review, run batch validation with
```
validate-yaml.py --dir docs/api --require doc_type --require entry --require status
```
, fix any errors first
Confirm and finalize — After user confirmation, batch change the status of samples and batch-generated entries to
```
status: current
```

Hard rules for batch mode:

Read source code independently for each entry — Even in batch mode, do not copy content from the previous entry and rename it. Two seemingly similar interfaces often have subtle differences, and copying and renaming will definitely miss them
Sample confirmation cannot be skipped — Reason as above
Mark entries with special source code structures (dynamic exports, code generation) as
skipped
with notes temporarily — Documentation guessed by force is more harmful than no documentation

Phase 3：增量更新

Phase 3: Incremental Updates

代码变更后同步文档。

找出要更新的条目，三种入口任选：
- ```
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
```
填当天

Synchronize documentation after code changes.

Identify entries to update, choose any of the three entry points:
- ```
search-yaml.py
```
  to search for
```
status=outdated
```
  — Marked by architecture check or last update
- Compare source code files changed after
```
last_scanned
```
  in
```
manifest.yaml
```
- ```
search-yaml.py --sort-by last_reviewed --order asc
```
  to sort by the longest unreviewed entries first, select entries that "should be checked for accuracy" for active review
Re-read the source code → Compare with existing documentation → Incrementally update changed parts
Validate with
```
validate-yaml.py
```
to confirm that frontmatter is not damaged
Set
```
status: current
```
and fill in
```
last_reviewed
```
with the current date

与其他工作流的关系

Relationship with Other Workflows

来源	关系
`cs-feat-accept`	验收后若新增/修改库公开接口 → 推送"需要更新 libdoc 吗？"
`cs-guide`	guide 引用 libdoc 做详细参考；libdoc "相关条目"链回 guide
`cs-arch` (check 模式)	它检测到接口变更但 libdoc 未同步时，会把对应条目标成 `outdated` ，本技能 Phase 3 据此处理
`cs-feat-design`	方案第 2 节可作 libdoc 补充信息源（但以源码为准）
`cs-trick`	libdoc "注意事项"与 tricks 重合时交叉引用而不重复写

Source	Relationship
`cs-feat-accept`	After acceptance, if new/modified public library interfaces are added → Push "Need to update libdoc?"
`cs-guide`	Guides reference libdoc for detailed references; libdoc links back to guides in the "Related Entries" section
`cs-arch` (check mode)	When it detects interface changes but libdoc is not synchronized, it marks the corresponding entry as `outdated` , which is handled in Phase 3 of this skill
`cs-feat-design`	Section 2 of the solution can be used as supplementary information source for libdoc (but source code takes precedence)
`cs-trick`	Cross-reference instead of duplicating content when libdoc's "Notes" overlap with tricks

退出条件

Exit Conditions

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（除非用户明确暂缓）

Phase 1

```
manifest.yaml
```
has been saved to disk
The user has confirmed the entry scope (including reasons for skipped entries)
Entry granularity and output path have been confirmed

Phase 2 Single-entry

Entry documentation is generated according to the template, including complete frontmatter
API reference section information is extracted from source code (not fabricated)
User confirmation obtained
Corresponding entry's status in
```
manifest.yaml
```
has been updated

Phase 2 Batch

Samples (2-3 entries) have been confirmed by the user
All pending entries have been generated or marked as skipped
User has conducted an overall review
Status of all entries in
```
manifest.yaml
```
has been synchronized

Phase 3

All outdated entries have been updated or confirmed as not needing updates
No remaining outdated entries in
```
manifest.yaml
```
(unless the user explicitly delays)

容易踩的坑

Common Pitfalls

❌ 没扫清单就写文档——可能遗漏条目或重复写
❌ 没读源码就写 API 参考——libdoc 的核心价值是准确反映源码
❌ 复制上一个条目改改名字算下一个——必然漏掉微妙差异
❌ 批量模式跳过样板确认——50 篇全白写
❌ 把 spec 信息（不变量、测试约束）写进 libdoc——属于
```
codestable/
```
❌ libdoc 和 guidedoc 内容高度重叠——重叠说明其中一份定位有误
❌
```
manifest.yaml
```
直接删行——改
```
status: skipped
```
并写 note
❌ 源码接口不存在却在文档里写了——以源码为事实源，不编造

❌ Writing documentation without scanning the manifest — may miss entries or duplicate content
❌ Writing API references without reading the source code — libdoc's core value is accurately reflecting the source code
❌ Copying the previous entry and renaming it for the next — will definitely miss subtle differences
❌ Skipping sample confirmation in batch mode — 50 entries will be wasted
❌ Writing spec information (invariants, test constraints) into libdoc — belongs to
```
codestable/
```
❌ High overlap between libdoc and guidedoc content — overlap indicates that one of them has a wrong positioning
❌ Deleting lines directly in
```
manifest.yaml
```
— change to
```
status: skipped
```
and add a note
❌ Writing documentation for non-existent source code interfaces — use source code as the source of truth, do not fabricate