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 个步骤（每步聚焦一个子目标）
   • 步骤之间严格按依赖关系排序
   • 每步包含：步骤编号、标题、目标说明