Dev guide writer

Tech Tutorial Builder

一个主题 → 完整技术教程：通过结构化 SOP 流程，将技术主题转化为包含前置知识、环境搭建、核心步骤、常见报错排查和进阶拓展的完整教程，并附带速查表（Cheatsheet）。

Quick Start

用户只需提供技术主题或操作目标，Agent 按照以下流程自动生成完整教程：

用户：帮我写一个 Docker 入门教程
Agent：[按 SOP 流程输出完整技术教程 + Cheatsheet]

SOP 流程

Phase 1: 主题定位与受众分析

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

操作步骤：

1. 解析主题：从用户输入中识别核心技术、操作目标和预期产出物
2. 提出澄清问题（最多 4 个关键问题）：
   • 目标读者的技术水平？（零基础 / 有一定基础 / 有经验的开发者）
   • 读者的操作系统环境？（macOS / Windows / Linux / 不限）
   • 教程完成后读者应该能做什么？（具体可交付的成果）
   • 有没有特定版本或技术栈的约束？
3. 如果用户要求跳过澄清，则基于以下默认假设继续：
   • 读者：有基本编程经验但不熟悉该技术
   • 环境：同时覆盖 macOS 和 Linux（必要时注明 Windows 差异）
   • 目标：能独立完成一个最小可工作的示例

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

---

Phase 2: 前置知识梳理（Prerequisites）

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

操作步骤：

1. 知识依赖分析：

   • 列出本教程涉及的所有技术概念
   • 逐项判断：该概念是"教程内讲解"还是"读者应已掌握"
   • 判断标准：如果展开讲解会偏离主题超过 200 字，则归为前置知识

2. 前置知识清单：

   • 按"必须掌握"和"了解即可"两个层次分类

   • 每项附带一句话说明"为什么需要它"

   • 格式：

     **必须掌握**：
     - [知识点]：[为什么需要它]（推荐学习资源名称）
     
     **了解即可**：
     - [知识点]：[在教程中会涉及哪些方面]
     

3. 自检规则：

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

输出：分层前置知识清单

---

Phase 3: 环境搭建（Environment Setup）

目标：提供一条可复现的环境配置路径，确保读者在动手核心步骤前环境就绪。

操作步骤：

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 Key、密码、token 等敏感信息的真实值
   • 涉及配置文件时，使用占位符（如 YOUR_API_KEY）并说明获取途径

输出：分操作系统的安装配置指南 + 验证命令

---

Phase 4: 核心步骤（Core Steps）

目标：以递进式结构带领读者从零完成核心操作，每一步都可独立验证。

操作步骤：

1. 步骤规划：

   • 将整个操作拆分为 5-10 个步骤（每步聚焦一个子目标）
   • 步骤之间严格按依赖关系排序
   • 每步包含：步骤编号、标题、目标说明

2. 步骤编写格式：

   #### 步骤 N：[步骤标题]
   
   **目标**：[这一步完成后达到什么状态]
   
   **操作**：
   [代码块或操作说明]
   
   **解释**：
   - [逐行/逐段解释关键部分的含义]
   
   **验证**：
   [运行什么命令/检查什么结果来确认这一步成功]
   预期输出：[具体的预期结果]
   

3. 编写规范：

   • 代码块必须标注语言类型（如 bash、python）
   • 占位符使用全大写 + 下划线格式（如 YOUR_PROJECT_NAME），并在首次出现时说明含义
   • 每个代码块不超过 30 行；超过时拆分并分段解释
   • 文件路径使用相对路径，开头说明项目根目录
   • 每一步结尾必须有验证环节

4. 渐进复杂度：

   • 前 1-3 步：最小可运行示例（Hello World 级别）
   • 中间步骤：逐步加入真实场景的特性
   • 最后 1-2 步：组合所有内容形成完整示例

输出：编号步骤列表，每步含操作 + 解释 + 验证

---

Phase 5: 常见报错与排查（Troubleshooting）

目标：预判读者可能遇到的问题，提供从错误信息到解决方案的直达路径。

操作步骤：

1. 报错收集：基于技术主题，列出 5-8 个最常见的报错场景

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

2. 报错条目格式：

   **报错 N：[错误信息摘要]**
   
   完整错误信息：
   [实际错误输出]
   
   原因：[一句话解释为什么会出现这个错误]
   
   解决方案：
   [具体的修复命令或操作步骤]
   
   验证修复：
   [运行什么来确认问题已解决]
   

3. 编写规范：

   • 错误信息必须是真实存在的（不编造错误信息）
   • 解决方案必须对应具体的操作，不使用"请检查配置"等模糊指引
   • 如果一个报错有多种可能原因，按概率从高到低排列
   • 涉及权限问题时，解释为什么需要该权限，而非直接给出 sudo 或 chmod 777

4. 自检规则：

   • 解决方案中不包含可能导致安全风险的操作（如 chmod 777、禁用防火墙等）
   • 不建议读者关闭安全特性来"解决"问题

输出：结构化报错排查表

---

Phase 6: 进阶拓展（Advanced Topics）

目标：为完成基础教程的读者指明进阶方向，提供从入门到深入的学习路径。

操作步骤：

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

   • 每个方向用一段话说明：它是什么、为什么值得学、适用于什么场景

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

   • 格式：

     **方向 N：[主题名称]** ｜ 难度：[中级/高级]
     
     [一段话说明]
     
     推荐资源：
     - [资源名称]（[类型：文档/书籍/课程]）
     

2. 实战项目建议：

   • 提供 2-3 个可以用本教程所学知识独立完成的小项目
   • 每个项目包含：项目名称、一句话描述、涉及的知识点

3. 最佳实践提示（3-5 条）：

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

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

---

Phase 7: Cheatsheet 速查表

目标：提炼教程精华为一页速查表，供读者日常参考。

操作步骤：

1. 速查表结构：

   # [技术名称] Cheatsheet
   
   ## 环境信息
   | 项目 | 命令/路径 |
   |------|-----------|
   | 安装 | `命令` |
   | 版本检查 | `命令` |
   | 配置文件位置 | `路径` |
   
   ## 常用命令
   | 操作 | 命令 | 说明 |
   |------|------|------|
   | xxx  | `xxx` | xxx |
   
   ## 常用代码片段
   [最多 5 个高频使用的代码片段，每个不超过 10 行]
   
   ## 快速排错
   | 症状 | 可能原因 | 快速修复 |
   |------|----------|----------|
   | xxx  | xxx      | `xxx`    |
   

2. 编写规范：

   • 速查表总长度控制在可打印的 2 页 A4 纸以内
   • 命令必须是完整可直接复制执行的
   • 不包含解释性文字，只保留"做什么 → 怎么做"的映射
   • 排列顺序按使用频率从高到低

输出：一页式 Cheatsheet

---

Phase 8: 文档组装与输出

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

教程文档模板：

# [技术主题] 完整教程

> 最后更新：[当前日期] | 适用版本：[版本号]
> 难度：[入门/中级/高级] | 预计耗时：[N 小时/分钟]

## 教程概览

[Phase 1 的教程元信息摘要，说明学完能做什么]

## 1. 前置知识

[Phase 2 的前置知识清单]

## 2. 环境搭建

[Phase 3 的安装配置指南]

## 3. 核心步骤

[Phase 4 的编号步骤列表]

## 4. 常见报错与排查

[Phase 5 的报错排查表]

## 5. 进阶拓展

[Phase 6 的进阶路线图和实战项目]

## 6. Cheatsheet 速查表

[Phase 7 的速查表]

## 附录

- 术语表（如有领域专业术语，用表格列出：术语 | 解释）
- 参考链接（官方文档、社区资源等）

文档输出要求：

• 所有代码块标注语言类型
• 所有命令可直接复制执行（不包含行号、提示符等干扰字符）
• 所有占位符使用 YOUR_XXX 格式并在首次出现时说明
• 配置文件中不包含真实密钥或 token
• 日期使用当前实际日期

---

流程控制规则

交互模式选择

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

用户输入	模式	行为
只有技术名称（如"Docker 教程"）	引导模式	执行 Phase 1 提问，等用户回答后继续
有具体目标（如"用 Docker 部署 Node.js 应用"）	半自动模式	提出 1-2 个关键问题，同时开始规划步骤
详细描述（含受众、环境、目标）	全自动模式	直接从 Phase 2 开始输出
用户说"直接写/不用问"	快速模式	基于默认假设直接输出完整教程

质量检查清单

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

• 前置知识清单完整，无知识断层
• 环境搭建步骤每条命令都有验证方式
• 核心步骤每步都包含"操作 + 解释 + 验证"三部分
• 步骤之间的依赖关系正确（不会出现用到未安装工具的情况）
• 常见报错不少于 5 个，且解决方案具体可操作
• 进阶方向至少 3 个，附带资源推荐
• Cheatsheet 可独立使用，包含常用命令和排错信息
• 所有代码块标注语言类型
• 不包含任何硬编码的密钥、token 或个人路径
• 不包含可能导致安全问题的操作建议（如 chmod 777）
• 不依赖任何付费 API 或需要付费订阅的工具（除非该工具本身是教程主题）

迭代优化

如果用户对教程有反馈：

1. 定位反馈涉及的 Phase
2. 从该 Phase 重新执行
3. 向下级联更新所有受影响的内容（如环境变更需同步更新后续步骤和 Cheatsheet）
4. 保持步骤编号的连续性

适用场景

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

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