⚡

技术教程生成器Skill dev-guide-writer

技术教程生成器：将任意技术主题转化为结构化教程，涵盖前置知识、环境搭建、核心步骤、常见报错排查、进阶拓展和速查表，适合编写入门指南、操作手册和开发教程。关键词：技术教程、速查表、环境搭建、报错排查、DevOps、编程入门、教程生成。

课程设计 0 次安装 2 次浏览 更新于 7/8/2026

name: dev-guide-writer description: “技术教程生成器：将任何技术主题转化为完整教程，包含前置知识、环境搭建、核心步骤、常见报错和进阶拓展，并生成速查表（Cheatsheet）。当用户提到编写教程、操作指南、入门手册、环境搭建步骤，或使用如“tutorial”、“step-by-step”、“getting started”、“how-to guide”、“速查表”、“快速上手”、“帮我写个教程”、“怎么从零开始搭这个环境”等关键词或请求时触发。” license: MIT

技术教程生成器

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

快速入门

用户只需提供技术主题或操作目标，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 流程、数据分析工具使用等