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

csDocs :: DocsRequest -> DocsOutcome
csDocs req | attentionMissing req.repoFacts = NeedsHuman "route to cs-onboard"
           | otherwise = either Blocked (\s -> restoreDocsStage s req) (applyDocsResume req.resumeInput (restoreDocsState req.repoFacts))

data DocsRequest = DocsRequest
  { requestedMode : Maybe Mode           -- tutorial | api
  , userTopic     : Maybe Text
  , resumeInput   : Maybe DocsResume
  , 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 是否已变
  , workflowStage : Maybe Stage           -- draft 的临时 workflow_stage；current 时必须清除
  , pendingCheckpoint : Maybe CheckpointReason
  , rejectedCheckpoint : Maybe CheckpointReason
  }

data DocsOutcome
  = RoutedTo Stage
  | HumanCheckpoint CheckpointReason
  | Completed DocsSummary
  | NeedsHuman Reason
  | Blocked Reason

data CheckpointReason
  = ReviewDraft | ReviewManifest | ConfirmOverwrite | ConfirmContractWording
  | ReviewEntry | ReviewSamples | ReviewAllDrafts
data DocsDecision = ApproveDocs | ReviseDocs | RejectDocs
data DocsResume = ResumeDocsCheckpoint CheckpointReason DocsDecision

applyDocsResume :: Maybe DocsResume -> DocsState -> Either Reason DocsState
applyDocsResume Nothing s = Right s
applyDocsResume (Just (ResumeDocsCheckpoint reason decision)) s
  | s.pendingCheckpoint == Just reason = Right (persistDocsDecision reason decision s)
  | otherwise                          = Left InvalidDocsResume
-- 目标读者/类型模糊不是 checkpoint：走 NeedsHuman "which reader?"（见 restoreDocsStage 与 Failure Behavior）

restoreDocsStage 从仓库事实选下一步（全局同步 / 记忆整理 → 路由 cs-docs-neat）：

restoreDocsStage :: DocsState -> DocsRequest -> DocsOutcome
restoreDocsStage(s, intent)
  | needsGlobalSync(intent)                              -> RoutedTo NeatHandoff   -- 全局同步/README/agent 入口/记忆整理，转 `cs-docs-neat`
  | ambiguousReader(s, intent)                           -> NeedsHuman "which reader?"
  | s.rejectedCheckpoint == Just ConfirmOverwrite       -> Completed (preservedExistingDocSummary s)
  | Just reason <- s.rejectedCheckpoint                 -> Blocked (OwnerRejectedDocsCheckpoint reason)
  | Just reason <- s.pendingCheckpoint                   -> HumanCheckpoint reason
  | s.docStatus == Draft && s.workflowStage == Just FocusedEdit
                                                         -> RoutedTo FocusedEdit   -- 批准后跨会话完成最小 patch
  | requestedMode intent == Just 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；先用 applyDocsResume 精确匹配并持久化 typed resume，再选 next stage；全局同步 / 记忆整理（非对外文档）→ route to cs-docs-neat。
4. loadStageProtocol — progressive reference loading：进某 stage 才按 stageProtocol 加载该 stage 一个 protocol，禁止 eager 读全部 references。
5. executeOrRoute — 先读代码和既有文档再落盘；tutorial/api 生成或增量更新，status 落到合法值；遇 HumanCheckpoint 必停。
6. exitRecoverable — 文档 status / manifest 状态明确、可从源码追溯，next stage 或 checkpoint reason 明确。

---

Reference 加载

stageProtocol :: Stage -> Protocol
stageProtocol TutorialStage = "references/tutorial/protocol.md"
stageProtocol ApiStage      = "references/api/protocol.md"      -- 必要时 references/api/reference.md
stageProtocol FocusedEdit   = "references/focused-edit/protocol.md"
stageProtocol NeatHandoff   = skill "cs-docs-neat"

先读代码和既有文档，再按对应模式生成或更新文档。不要凭记忆写 API。

---

人工 checkpoint

必须停下等用户明确确认的点：

1. 目标读者、文档类型（tutorial / api）或落点路径缺失时返回 NeedsHuman "which reader?"；草稿完成后以 ReviewDraft / ReviewEntry / ReviewSamples / ReviewAllDrafts 放行。
2. 覆盖或重写已有 current 文档前：确认旧内容确实过期，不是并行有效版本。
3. 文档表述会改变 user-facing 契约或公开理解时：让用户确认口径后再落盘。

checkpoint 以 ResumeDocsCheckpoint reason decision 作为 typed resume input；草稿或 manifest 必须先以 draft 状态持久化，reason 精确匹配后再改为 current / approved，因此跨会话也能恢复待确认对象。无 pending、reason 不匹配或旧状态无法证明 checkpoint 时 Blocked InvalidDocsResume。API manifest 初次生成后用 ReviewManifest 放行，不能把“文件已存在”当作“用户已确认”。

---

Failure Behavior

返回 NeedsHuman 当：.codestable/attention.md 缺失（→ cs-onboard）；无法识别目标文档或落点路径；目标读者/文档类型模糊无法从仓库事实判定；requested mode 与仓库事实冲突；写 API 时源码事实源不足只能靠猜。覆盖当前文档、公开契约口径和各类草稿 review 属 HumanCheckpoint；全局同步 / 记忆整理属于 RoutedTo NeatHandoff，不得混成 NeedsHuman。报告：当前目标文档、阻塞或 checkpoint 原因、下一步用户动作、已写文件、是否可安全重试。

---

退出条件

• 文档目标读者、入口路径和状态已明确。
• 新增/更新文档的 status 或 manifest 状态已落到 draft / current / outdated / pending / skipped 中的合法值。
• 新增/更新的文档能从源码或现有项目事实追溯。
• 需要同步 README、agent 入口或记忆时，明确提示后续运行 cs-docs-neat。