dev-guide-generator

Dev Guide Generator

一个主题 → 完整技术教程：通过结构化的 SOP 工作流，将一个技术主题转化为全面的教程，涵盖前置知识、环境配置、核心步骤、常见错误排查和进阶主题，并附带速查表。

快速开始

用户只需提供一个技术主题或操作目标，Agent 就会按照此工作流自动生成完整教程：

User: Help me write a Docker beginner's tutorial
Agent: [Outputs complete technical tutorial + Cheatsheet following the SOP workflow]

SOP 工作流

阶段 1：主题界定与受众分析

目标：明确教程的技术主题、目标受众和范围边界。

步骤：

1. 解析主题：从用户输入中识别核心技术、操作目标和预期交付成果
2. 提出澄清问题（最多 4 个关键问题）：
   • 目标受众的技术水平如何？（完全初学者 / 有一些经验 / 有经验的开发者）
   • 读者将使用什么操作系统？（macOS / Windows / Linux / 任意）
   • 完成教程后，读者应能做什么？（具体交付成果）
   • 是否有版本或技术栈方面的限制？
3. 如果用户要求跳过澄清，则采用以下默认假设：
   • 受众：具备基础编程经验，但不熟悉该主题技术
   • 环境：涵盖 macOS 和 Linux（必要时注明 Windows 的差异）
   • 目标：能够独立完成一个最小可运行示例

输出：教程元数据摘要（主题、受众、目标、范围，不超过 150 个字）

---

阶段 2：前置知识

目标：列出读者开始本教程前需要掌握的所有知识和工具，确保不存在知识缺口。

步骤：

1. 依赖分析：

   • 列出本教程涉及的所有技术概念
   • 对每个概念，判断应在“教程中讲解”还是“假定读者已掌握”
   • 判断规则：如果讲解某个概念会使内容偏离主题超过 200 个字，则将其归类为前置知识

2. 前置知识清单：

   • 分为“必须了解”和“了解更佳”两类

   • 为每项附上一句说明：“为什么需要它”

   • 格式：

     **必须了解**：
     - [概念]：[为什么需要它]（推荐资源）
     
     **了解更佳**：
     - [概念]：[与教程哪些方面相关]
     

3. 自检规则：

   • 如果前置知识超过 5 项，请考虑缩小教程范围或拆分为系列
   • 每项前置知识都必须提供公开可用的学习资源

输出：分级前置知识清单

---

第 3 阶段：环境设置

目标：提供可复现的环境配置路径，确保读者在开始核心步骤前完成所有设置。

步骤：

1. 环境清单：列出所有需要安装或配置的工具，并注明建议版本

   • 格式：工具名称 版本要求（例如，>= x.y）| 用途
   • 明确区分“必需”和“可选”安装

2. 安装步骤：为每种操作系统提供命令

   • 每条命令前添加一句说明，解释其作用

   • 仅使用官方推荐的方法或主流包管理器

   • 格式：

     **macOS**：
     # 安装 xxx（通过 Homebrew）
     brew install xxx
     
     **Linux (Ubuntu/Debian)**：
     # 安装 xxx（通过 apt）
     sudo apt update && sudo apt install -y xxx
     

3. 环境验证：每个工具安装后提供验证命令和预期输出

   • 格式：

     # 验证安装
     xxx --version
     # 预期输出：xxx x.y.z
     

4. 自检规则：

   • 所有安装命令都必须来自官方文档或主流包管理器，不得使用第三方脚本
   • 切勿包含真实的 API 密钥、密码、令牌或其他敏感值
   • 涉及配置文件时，使用占位符（例如，YOUR_API_KEY），并说明如何获取真实值

输出：针对不同操作系统的安装和配置指南 + 验证命令

---

第 4 阶段：核心步骤

目标：通过渐进式结构引导读者完成核心操作，每个步骤都可以单独验证。

步骤：

1. 步骤规划：

   • 将整个操作拆分为 5–10 个步骤（每个步骤专注于一个子目标）
   • 严格按照依赖关系排列步骤
   • 每个步骤包括：步骤编号、标题和目标说明

2. 步骤编写格式：

   #### Step N: [Step Title]
   
   **Objective**: [What state is achieved after this step]
   
   **Actions**:
   [Code block or operational instructions]
   
   **Explanation**:
   - [Line-by-line or section-by-section explanation of key parts]
   
   **Verification**:
   [What command to run / what result to check to confirm success]
   Expected output: [Specific expected result]
   

3. 编写指南：

   • 代码块必须注明语言（例如，bash、python）
   • 占位符使用 ALL_CAPS_WITH_UNDERSCORES 格式（例如，YOUR_PROJECT_NAME），并在首次出现时说明
   • 每个代码块不应超过 30 行；如果更长，应拆分并分节说明
   • 使用相对文件路径；在开头注明项目根目录
   • 每个步骤都必须以验证部分结尾

4. 循序渐进的复杂度：

   • 步骤 1–3：最小可运行示例（Hello World 级别）
   • 中间步骤：逐步引入实际功能
   • 最后 1–2 个步骤：将所有内容整合为完整示例

输出：编号步骤列表，每个步骤都包含操作 + 说明 + 验证

---

第 5 阶段：故障排除

目标：预判读者可能遇到的问题，并提供从错误消息到解决方案的直接指引。

步骤：

1. 收集错误：根据技术主题列出 5–8 个最常见的错误情形

   • 来源：环境配置错误、版本不兼容、权限问题、拼写错误、网络问题等

2. 错误条目格式：

   **Error N: [Error message summary]**
   
   Full error message:
   [Actual error output]
   
   Cause: [One-sentence explanation of why this error occurs]
   
   Solution:
   [Specific fix commands or steps]
   
   Verify the fix:
   [What to run to confirm the issue is resolved]
   

3. 编写指南：

   • 错误消息必须真实存在（不得伪造错误消息）
   • 解决方案必须可执行，避免“检查你的配置”这类含糊建议
   • 如果错误可能有多种原因，应按可能性从高到低列出
   • 对于权限相关问题，解释为何需要该权限，而不是直接使用 sudo 或 chmod 777

4. 自检规则：

   • 解决方案不得包含可能造成安全风险的操作（例如，chmod 777、禁用防火墙）
   • 切勿建议读者禁用安全功能来“解决”问题

输出：结构化故障排除表

阶段 6：进阶主题

目标：为已完成基础内容的读者指明后续学习方向，提供从入门到进阶的学习路径。

步骤：

1. 进阶主题推荐（3–5 个方向）：

   • 对每个方向，写一段简短介绍：说明它是什么、为什么值得学习，以及适用场景

   • 标注难度级别：中级 / 高级

   • 格式：

     **方向 N：[主题名称]** | 难度：[中级/高级]
     
     [简短介绍]
     
     推荐资源：
     - [资源名称]（[类型：文档/书籍/课程]）
     

2. 动手项目建议：

   • 提供 2–3 个小项目，让读者可以运用所学内容独立完成
   • 每个项目包括：项目名称、一句话描述和相关概念

3. 最佳实践提示（3–5 项）：

   • 生产环境与教程环境之间的关键差异
   • 安全注意事项
   • 性能优化方向

输出：进阶学习路线图 + 动手项目建议 + 最佳实践

---

阶段 7：速查表

目标：将教程的核心内容提炼为一页速查表，供日常使用。

步骤：

1. 速查表结构：

   # [Technology Name] Cheatsheet
   
   ## Environment Info
   | Item | Command/Path |
   |------|--------------|
   | Install | `command` |
   | Version check | `command` |
   | Config file location | `path` |
   
   ## Common Commands
   | Action | Command | Description |
   |--------|---------|-------------|
   | xxx    | `xxx`   | xxx         |
   
   ## Common Code Snippets
   [Up to 5 frequently used code snippets, each no more than 10 lines]
   
   ## Quick Troubleshooting
   | Symptom | Possible Cause | Quick Fix |
   |---------|---------------|-----------|
   | xxx     | xxx           | `xxx`     |
   

2. 编写指南：

   • 速查表总长度应控制在 2 张 A4 打印纸以内
   • 命令必须完整，可直接复制粘贴
   • 不要写解释性文字——只保留“要做什么 → 如何操作”的对应关系
   • 按使用频率从高到低排列条目

输出：一页速查表

---

阶段 8：文档组装与输出

目标：将前七个阶段的输出组装成一份完整的教程文档。

教程文档模板：

# [Technical Topic] Complete Tutorial

> Last updated: [Current date] | Applicable version: [Version number]
> Difficulty: [Beginner/Intermediate/Advanced] | Estimated time: [N hours/minutes]

## Tutorial Overview

[Phase 1 metadata summary — what the reader will be able to do after completion]

## 1. Prerequisites

[Phase 2 prerequisites checklist]

## 2. Environment Setup

[Phase 3 installation and configuration guide]

## 3. Core Steps

[Phase 4 numbered step list]

## 4. Troubleshooting

[Phase 5 troubleshooting table]

## 5. Advanced Topics

[Phase 6 advanced roadmap and hands-on projects]

## 6. Cheatsheet

[Phase 7 cheatsheet]

## Appendix

- Glossary (if domain-specific terminology is used, list in a table: Term | Definition)
- Reference links (official documentation, community resources, etc.)

文档输出要求：

• 所有代码块都必须指定语言
• 所有命令都必须可直接复制粘贴（不得包含行号、提示符或其他无关内容）
• 所有占位符都使用 YOUR_XXX 格式，并在首次出现时加以说明
• 配置文件不得包含真实密钥或令牌
• 日期必须使用当前实际日期

---

流程控制规则

交互模式选择

根据用户输入的详细程度选择模式：

用户输入	模式	行为
仅提供技术名称（例如，“Docker 教程”）	引导模式	执行阶段 1 的提问，等待用户回答后再继续
提供具体目标（例如，“使用 Docker 部署 Node.js 应用”）	半自动模式	提出 1–2 个关键问题，同时规划步骤
提供详细描述（包含受众、环境和目标）	全自动模式	直接从阶段 2 开始输出
用户表示“直接写／别提问”	快速模式	根据默认假设输出完整教程

质量检查清单

输出最终教程前，逐项检查：

• 先决条件清单完整，没有知识缺口
• 每条环境设置命令都有验证步骤
• 每个核心步骤都包括“操作 + 说明 + 验证”
• 步骤依赖关系正确（步骤不会使用尚未安装的工具）
• 至少包含 5 个常见错误及具体、可执行的解决方案
• 至少包含 3 个进阶方向及推荐资源
• 速查表内容完整，包含常用命令和故障排查信息
• 所有代码块都指定了语言
• 不含硬编码的密钥、令牌或个人路径
• 不包含可能造成安全漏洞的建议（例如 chmod 777）
• 不依赖付费 API 或仅限订阅使用的工具（除非教程主题本身就是该工具）

迭代优化

如果用户对教程提供反馈：

1. 确定反馈涉及哪个阶段
2. 从该阶段重新执行
3. 将更新传递至所有后续内容（例如，环境变更必须同步到后续步骤和速查表）
4. 保持步骤编号连续

使用场景

此教程生成器适用于以下类型的技术教程：

• 工具使用：Git、Docker、Kubernetes、Vim 等工具的教程
• 环境配置：开发环境、CI/CD 流水线、服务器配置等
• 编程入门：语言基础、框架快速入门、库的使用等
• 运维手册：部署、监控、日志记录、备份与恢复等
• 数据处理：数据库操作、ETL 工作流、数据分析工具的使用等