| name | cs-docs |
| description | Docs 主入口。触发：写/更新开发者指南、用户指南、API 参考；不包含 docs-neat 收尾整理。不要用于新功能实现(cs-feat)、修 bug / 诊断报错(cs-issue)、大需求拆解(cs-epic)、领域建模(cs-domain)、ADR 决策记录(best-adr)。 |
| argument-hint | [--mode tutorial|api] <topic> |
| contracts | [{"grep":"restoreDocsStage"},{"grep":"progressive reference loading"},{"grep":"manifest.yaml"},{"not-grep":"git push"},{"not-grep":"read all references"}] |
cs-docs
启动必读
动作前先跑 CodeStable preflight：读 .codestable/attention.md（缺失先 cs-onboard）；不要用 AGENTS.md/CLAUDE.md 等外部入口代替它；细则见 .codestable/reference/execution-conventions.md。
cs-docs 是对外文档写作的唯一推荐入口，只覆盖开发者/用户指南和 API 参考。阶段收尾、知识库卫生、agent 入口同步仍走独立的 cs-docs-neat。
旧技能 cs-doc-tutorial、cs-doc-api 长期保留为兼容入口，只传入 requested_mode。
入口意图
本次调用参数：$ARGUMENTS
意图来源按优先级：调用参数 flag > 兼容入口预设 > 用户话术。参数为空或未被替换（仍是字面 $ARGUMENTS）时跳过该来源；调用参数用 --mode tutorial|api 表示文档模式，其余文本作为文档主题。旧裸 token（如 api）只作为历史提示词兼容识别；新文档和新调用一律用 --mode。
无参数默认行为：没有 mode / topic 时，先扫既有文档和公开表面，按状态机找 pending / draft / outdated 文档；若没有可恢复文档目标，再根据用户原话判断目标读者，不清楚就问用户选择。
用户没有明确文档类型时先判断目标读者和使用场景；仍不清楚就问用户选择。
模式边界
| 模式 | 产物 | 适用 |
|---|
| tutorial | 开发者指南 / 用户指南 | 教读者怎么完成一个任务 |
| api | API / 组件 / 命令参考 | 给读者查公开表面、参数、返回值、示例 |
cs-docs 不做全局同步、不整理 .codestable/、不毕业 agent memory。发现这些需求时提示 cs-docs-neat。
Spec
csDocs :: DocsRequest -> DocsOutcome
data DocsRequest = DocsRequest
{ requestedMode : Maybe Mode -- tutorial | api
, userTopic : Maybe Text
, repoFacts : RepoFacts -- 优先于 args / 聊天历史
}
data Mode = Tutorial | Api
data Stage = TutorialStage | ApiStage | FocusedEdit | NeatHandoff
data DocsState = DocsState -- 全部从 docs/ + manifest.yaml + 源码公开表面恢复
{ targetDoc : Maybe Path
, docStatus : Missing | Draft | Current | Outdated -- frontmatter status
, manifest : NoManifest | HasManifest -- docs/api/manifest.yaml
, entryStatus : Pending | Draft | Current | Outdated | Skipped
, codeDrift : InSync | Drifted -- 相关源码/spec 是否已变
}
data DocsOutcome
= RoutedTo Stage
| HumanCheckpoint CheckpointReason
| Completed DocsSummary
| NeedsHuman Reason
data CheckpointReason = ConfirmNewDoc | ConfirmOverwrite | ConfirmContractWording
-- 目标读者/类型模糊不是 checkpoint：走 NeedsHuman "which reader?"（见 restoreDocsStage 与 Failure Behavior）
restoreDocsStage 从仓库事实选下一步（全局同步 / 记忆整理 → 路由 cs-docs-neat）：
restoreDocsStage :: DocsState -> EntryIntent -> DocsOutcome
restoreDocsStage(s, intent)
| needsGlobalSync(intent) -> RoutedTo NeatHandoff -- 全局同步/README/agent 入口/记忆整理，转 `cs-docs-neat`
| ambiguousReader(s, intent) -> NeedsHuman "which reader?"
| intent.mode == Api || wantsReference(intent) -> RoutedTo ApiStage -- 无 manifest 则初始化，缺条目则补
| s.manifest == HasManifest && s.entryStatus in [Pending, Draft, Outdated]
-> RoutedTo ApiStage -- 生成或增量更新条目
| wantsTaskGuide(intent) && s.docStatus == Missing -> RoutedTo TutorialStage -- 新建
| s.docStatus == Current && s.codeDrift == Drifted -> RoutedTo TutorialStage -- 更新
| s.docStatus == Outdated -> RoutedTo TutorialStage -- 更新
| s.docStatus == Current && smallEdit(intent) -> RoutedTo FocusedEdit -- 聚焦编辑，保持事实可追溯
| otherwise -> RoutedTo TutorialStage
restoreDocsStage 是唯一路由真相：启动后先扫既有文档和公开表面（docs/、README*、用户点名路径、相关源码导出/API/命令）恢复 DocsState，按上方分支选下一步。用户说“继续写文档”时，也按文件和 frontmatter / manifest 状态判断，不靠聊天历史。
Workflow
主执行主线（每次调用按序走；各 stage "怎么做" 的厚规则见对应 protocol，本节只定顺序与边界）：
preflight — 读 .codestable/attention.md；缺失则 route to cs-onboard；不得用 AGENTS.md/CLAUDE.md 代替 CodeStable attention。parseEntryIntent — 优先级 flag > compat-preset > utterance；repoFacts override requestedMode；空参不推断 mode，先按仓库事实恢复。restoreDocsStage — 扫 docs/、README*、manifest.yaml + 相关源码公开表面恢复 DocsState，选 next stage；全局同步 / 记忆整理（非对外文档）→ route to cs-docs-neat。loadStageProtocol — progressive reference loading：进某 stage 才加载该 stage 一个 protocol，禁止 eager 读全部 references。executeOrRoute — 先读代码和既有文档再落盘；tutorial/api 生成或增量更新，status 落到合法值；遇 HumanCheckpoint 必停。exitRecoverable — 文档 status / manifest 状态明确、可从源码追溯，next stage 或 checkpoint reason 明确。
Reference 加载
- tutorial：
references/tutorial/protocol.md
- api：
references/api/protocol.md，必要时 references/api/reference.md
先读代码和既有文档，再按对应模式生成或更新文档。不要凭记忆写 API。
人工 checkpoint
必须停下等用户明确确认的点：
- 新建文档前：目标读者、文档类型（tutorial / api）和落点路径。
- 覆盖或重写已有
current 文档前：确认旧内容确实过期，不是并行有效版本。
- 文档表述会改变 user-facing 契约或公开理解时：让用户确认口径后再落盘。
Failure Behavior
返回 NeedsHuman 当：.codestable/attention.md 缺失（→ cs-onboard）；无法识别目标文档或落点路径；目标读者/文档类型模糊无法从仓库事实判定；requested mode 与仓库事实冲突；文档表述会改变 user-facing 契约或公开理解而用户未确认口径；诉求实为全局同步 / 记忆整理（→ cs-docs-neat）；写 API 时源码事实源不足只能靠猜。报告：当前目标文档、阻塞原因、下一步用户动作、已写文件、是否可安全重试。
退出条件
- 文档目标读者、入口路径和状态已明确。
- 新增/更新文档的
status 或 manifest 状态已落到 draft / current / outdated / pending / skipped 中的合法值。
- 新增/更新的文档能从源码或现有项目事实追溯。
- 需要同步 README、agent 入口或记忆时，明确提示后续运行
cs-docs-neat。
