cs-docs

# 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 ```haskell 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`）： ```haskell 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，本节只定顺序与边界）： 1. **`preflight`** — 读 `.codestable/attention.md`；缺失则 `route to cs-onboard`；不得用 `AGENTS.md`/`CLAUDE.md` 代替 CodeStable attention。 2. **`parseEntryIntent`** — 优先级 `flag > compat-preset > utterance`；`repoFacts override requestedMode`；空参不推断 mode，先按仓库事实恢复。 3. **`restoreDocsStage`** — 扫 `docs/`、`README*`、`manifest.yaml` + 相关源码公开表面恢复 `DocsState`，选 next stage；全局同步 / 记忆整理（非对外文档）→ `route to cs-docs-neat`。 4. **`loadStageProtocol`** — progressive reference loading：进某 stage 才加载该 stage 一个 protocol，禁止 eager 读全部 references。 5. **`executeOrRoute`** — 先读代码和既有文档再落盘；tutorial/api 生成或增量更新，`status` 落到合法值；遇 `HumanCheckpoint` 必停。 6. **`exitRecoverable`** — 文档 `status` / manifest 状态明确、可从源码追溯，next stage 或 checkpoint reason 明确。 --- ## Reference 加载 - tutorial：`references/tutorial/protocol.md` - api：`references/api/protocol.md`，必要时 `references/api/reference.md` 先读代码和既有文档，再按对应模式生成或更新文档。不要凭记忆写 API。 --- ## 人工 checkpoint 必须停下等用户明确确认的点： 1. 新建文档前：目标读者、文档类型（tutorial / api）和落点路径。 2. 覆盖或重写已有 `current` 文档前：确认旧内容确实过期，不是并行有效版本。 3. 文档表述会改变 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`。