draft-docs

草拟文档

在 docs/drafts/ 中生成教程、操作指南、参考文档或说明文档草稿，以供发布前审核。这是 Diataxis 的四种类型——完整的类型选择流程请参阅 docs-style/references/diataxis-compass.md。

参数

• 主题提示词： 对要编写文档内容的描述（例如，“编写 WebSocket API 文档”）
• --publish [file]： 将已审核的草稿移至最终位置并更新导航

模式 1：生成草稿

提供主题提示词来调用 draft-docs 技能，例如 draft-docs "Document the authentication middleware"。

步骤 0：收集上下文

解析输入前，先收集项目上下文：

# Check for existing docs structure
ls -la docs/ 2>/dev/null || echo "No docs/ directory found"

# Identify documentation framework
ls docs/navigation.json docs/mint.json docs/docusaurus.config.js docs/mkdocs.yml 2>/dev/null | head -1

# Check for existing drafts
ls docs/drafts/*.md 2>/dev/null || echo "No existing drafts"

# Get recent code changes for context
git diff --name-only $(git merge-base HEAD main)..HEAD 2>/dev/null | head -20

收集以下信息：

• 文档结构：docs/ 中现有的子目录
• 导航系统：navigation.json、mint.json 或其他配置
• 技术栈线索：从已更改文件的扩展名和导入信息中获取
• 现有草稿：避免重复

步骤 1：解析输入

从提示词中提取：

1. 主题： 要编写文档的内容（例如，“身份验证中间件”）
2. 内容类型： 根据关键词判断：

关键词	类型	技能
"tutorial", "learn", "getting started", "first", "onboarding", "introduction", "build a/your"	教程	tutorial-docs
"how to", "guide", "steps", "configure", "set up"	操作指南	howto-docs
"API", "reference", "parameters", "function", "endpoint"	参考文档	reference-docs
"why", "how does it work", "concept", "background", "rationale", "design decision", "architecture", "trade-offs"	说明文档	explanation-docs

这四种类型是 Diátaxis 框架的四个象限——教程（学习）、操作指南（任务）、参考文档（信息）和说明文档（理解）。根据指南针的两个问题进行判断——行动还是认知？习得还是应用？ 详细说明见 docs-style/references/diataxis-compass.md。以下两个区别可以解决大多数模糊情况：

• 教程与操作指南都提供行动步骤，但教程通过确保成功的课程（学习）来教初学者，而操作指南则引导有经验的用户实现实际目标（工作）。如果读者是第一次学习该产品，这是教程；如果他们已经了解该产品，只是想完成某项任务，则是操作指南。
• 参考文档与说明文档都服务于理论知识，但参考文档会陈述可在使用时查阅的中立事实，而说明文档则探讨适合离开操作环境后阅读的原理和背景。如果请求涉及观点、历史或权衡，则属于说明文档；如果请求需要权威规范，则属于参考文档。

如果无法确定，请询问：“这应该是教程（边做边学）、操作指南（完成任务）、参考文档（查询技术信息），还是说明文档（理解概念背后的原因）？”

步骤 2：加载技能

始终加载以下两项：

1. docs-style - 核心写作原则
2. 检测到的类型技能：
   • 教程使用 tutorial-docs
   • 操作指南使用 howto-docs
   • 参考文档使用 reference-docs
   • 说明文档使用 explanation-docs

步骤 3：分析代码

在代码库中搜索相关代码：

1. 符号搜索： 查找与主题匹配的函数、类和类型
2. 文件搜索： 根据名称模式定位相关文件
3. 引用搜索： 查找用法示例

收集：

• 函数／方法签名
• 类型定义
• 现有注释／文档字符串
• 测试或示例中的用法模式

第 4 步：生成草稿

应用已加载的技能生成文档：

对于教程文档：

• 遵循 tutorial-docs 模板结构
• 标题应说明读者将构建什么（“构建你的第一个 X”），而不是读者将学到什么
• 使用第一人称复数——“在本教程中，我们将……”——保持教师与学习者的叙述视角
• 提供一条清晰的路径，不提供选择或替代方案
• 每一步之后，说明读者应该看到什么（“你应该会看到……”）
• 尽可能精简说明；关于“为什么”的内容链接到说明文档

对于参考文档：

• 遵循 reference-docs 模板结构
• 记录所有参数及其类型
• 包含来自实际代码的完整、可运行示例
• 添加链接到相关符号的 Related 部分

对于操作指南文档：

• 遵循 howto-docs 模板结构
• 标题以“How to”开头
• 列出具体的先决条件
• 将操作拆分为单一动作步骤
• 包含验证部分

对于说明文档：

• 遵循 explanation-docs 模板结构
• 标题围绕理解某个概念来命名（“理解 X”），而不是围绕某项任务
• 开篇说明读者阅读后将理解什么
• 解释设计决策背后的原因，而不只是说明现有内容
• 诚实地讨论权衡，并承认考虑过的替代方案
• 使用连贯的散文体，方便读者离开键盘阅读——不要提供操作步骤

第 5 步：撰写草稿

1. 创建输出路径：

   • docs/drafts/{slug}.md
   • 根据主题生成 slug：“WebSocket API” → websocket-api.md

2. 确保目录存在：

   mkdir -p docs/drafts
   

3. 撰写草稿文件（参见 硬性门槛 → 写入门槛：在进行下一步之前，确认文件已写入磁盘）

4. 向用户报告：

   ## Draft Created
   
   **File:** `docs/drafts/{slug}.md`
   **Type:** Tutorial | How-To | Reference | Explanation
   **Based on:** [list of analyzed symbols/files]
   
   ### Next Steps
   
   1. Review the draft for accuracy
   2. Add any missing context or examples
   3. When ready, publish by invoking the **draft-docs** skill with `--publish docs/drafts/{slug}.md`
   

第 6 步：运行结束时验证

验证草稿是否已成功生成：

# Confirm draft file exists
ls -la docs/drafts/{slug}.md

# Validate frontmatter (YAML header)
head -10 docs/drafts/{slug}.md | grep -E "^---$|^title:|^description:"

# Check markdown syntax (if markdownlint available)
markdownlint docs/drafts/{slug}.md 2>/dev/null || echo "markdownlint not available"

验证清单：

• 草稿文件已创建于 docs/drafts/{slug}.md
• Frontmatter 包含 title 和 description
• 内容类型与检测到的类型一致（教程、操作指南、参考或说明）
• 代码示例完整且可运行（教程／操作指南／参考）；概念以真实设计决策为依据（说明）
• 教程草稿仅提供一条路径，并在每一步给出可观察的“你应该会看到……”结果
• 草稿中引用了所有已分析的符号

如果任何验证失败，请报告具体问题并提出重新生成的方案。

模式 2：发布草稿

使用 --publish 标志调用 draft-docs 技能，例如 draft-docs --publish docs/drafts/websocket-api.md。

第 1 步：读取草稿

读取草稿文件并提取：

• 标题
• 内容类型（从 frontmatter 或结构中获取）

第 2 步：确定目标位置

询问用户要放在哪个部分：

Where should this document go?

1. **Tutorials** → `docs/tutorials/{slug}.md`
2. **API Reference** → `docs/api/{slug}.md`
3. **Guides** → `docs/guides/{slug}.md`
4. **How-To** → `docs/how-to/{slug}.md`
5. **Concepts / Explanation** → `docs/concepts/{slug}.md`
6. **Other** → Specify path

第 3 步：移动文件

mv docs/drafts/{slug}.md {destination}/{slug}.md

第 4 步：更新导航

检查 docs/navigation.json 是否存在，并更新导航：

1. 读取当前的 navigation.json
2. 找到合适的导航分组
3. 添加新页面条目
4. 写入更新后的 navigation.json

更新示例：

{
  "navigation": [
    {
      "group": "API Reference",
      "pages": [
        "api/existing-page",
        "api/websocket-api"
      ]
    }
  ]
}

第 5 步：报告

## Published

**From:** `docs/drafts/{slug}.md`
**To:** `{destination}/{slug}.md`
**Navigation:** Updated `docs/navigation.json`

The document is now live in your docs.

第 6 步：运行结束时验证

验证发布是否成功完成：

# Confirm file moved to destination
ls -la {destination}/{slug}.md

# Confirm draft removed
ls docs/drafts/{slug}.md 2>/dev/null && echo "WARNING: Draft still exists" || echo "Draft cleaned up"

# Verify navigation updated
grep -q "{slug}" docs/navigation.json && echo "Navigation includes new page" || echo "WARNING: Navigation may need manual update"

# Check markdown syntax at final location
markdownlint {destination}/{slug}.md 2>/dev/null || echo "markdownlint not available"

验证清单：

• 文档已移动到 {destination}/{slug}.md
• 草稿已从 docs/drafts/ 中移除
• 导航文件已更新，并包含新页面条目
• 导航结构中没有失效链接
• 可通过预期的 URL 路径访问文档

如果任何验证失败，请报告具体问题并提供补救步骤。

内容类型检测

教程指标

• 提示中提到：教程、学习、入门、首次、引导、介绍、“构建一个／你的……”
• 目标是让初学者首次成功体验产品
• 用户希望获得循序渐进、边做边学的课程，而不是完成某项任务或查找信息

参考文档指标

• 提示中提到：API、端点、函数、方法、类、类型、参数、返回值
• 目标是特定符号或一组符号
• 用户希望获得技术规范

操作指南的判断指标

• 提示中提到：如何操作、指南、步骤、配置、设置、集成
• 目标是某项任务或工作流
• 用户希望获得操作说明

解释性文档的判断指标

• 提示中提到：原因、工作原理、概念、背景、理由、设计决策、架构、权衡
• 目标是读者想要理解的概念或系统，而非要操作的对象
• 用户希望了解背景和推理，以便离开键盘后阅读，而不是遵循操作步骤

规则

• 每次起草都必须加载 docs-style 技能
• 将内容生成到 docs/drafts/，绝不直接生成到最终位置
• 添加包含标题和描述的 frontmatter
• 使用代码库中的真实示例
• 在草稿元数据中引用分析过的符号
• 发布时保留现有导航结构
• 覆盖现有文件前先征求同意

硬性关卡（按顺序执行）

不得跳过步骤：必须先通过每个 Pass，才能进入下一步。使用命令或明确的产物，不要只在内部确认。

生成草稿（模式 1）

1. **上下文关卡 — Pass：**已运行步骤 0 的命令（或等效操作），并记录了至少一项具体结果，例如 docs/ 列表片段，或明确说明 docs/ 不存在且将创建该目录。
2. **类型关卡 — Pass：**根据关键词表和两个判断问题，或根据用户的明确回答，确定文档类型是教程、操作指南、参考文档还是解释性文档。在此关卡完成前，不得开始 步骤 3：分析代码。
3. **技能关卡 — Pass：**分析前，必须同时启用以下两项：docs-style 和对应类型的技能（tutorial-docs、howto-docs、reference-docs 或 explanation-docs）。在执行过程中，注明已加载的两项技能及其路径，不要只说“我查看了写作指南”。
4. **写入关卡 — Pass：**写完草稿后，test -f docs/drafts/{slug}.md 命令执行成功（或 ls 显示该文件）。只有此后才能输出 Draft Created 区块。

发布草稿（模式 2）

1. **目标位置关卡 — Pass：**用户已从菜单中选择目标位置，或指定了具体路径。将 {destination} 解析为完整路径；当父目录存在（test -d "$(dirname "$path")" 或项目适用的检查），且未经用户明确批准不会覆盖现有文件时，判定为 Pass。
2. **移动关卡 — Pass：**执行 mv 后，文件已存在于 {destination}/{slug}.md（test -f 检查通过），并且已应用导航更新（如适用），之后才能声称已 Published。