| name | dev-guide-writer |
| description | 技术教程生成器：将任何技术主题转化为完整教程，包含前置知识、环境搭建、核心步骤、常见报错和进阶拓展，并生成速查表（Cheatsheet）。当用户提到编写教程、操作指南、入门手册、环境搭建步骤，或使用如“tutorial”、“step-by-step”、“getting started”、“how-to guide”、“速查表”、“快速上手”、“帮我写个教程”、“怎么从零开始搭这个环境”等关键词或请求时触发。 |
| license | MIT |
Tech Tutorial Builder
一个主题 → 完整技术教程：通过结构化 SOP 流程，将技术主题转化为包含前置知识、环境搭建、核心步骤、常见报错排查和进阶拓展的完整教程，并附带速查表（Cheatsheet）。
Quick Start
用户只需提供技术主题或操作目标，Agent 按照以下流程自动生成完整教程：
用户：帮我写一个 Docker 入门教程
Agent：[按 SOP 流程输出完整技术教程 + Cheatsheet]
SOP 流程
Phase 1: 主题定位与受众分析
目标：明确教程的技术主题、目标读者和范围边界。
操作步骤：
- 解析主题：从用户输入中识别核心技术、操作目标和预期产出物
- 提出澄清问题（最多 4 个关键问题）：
- 目标读者的技术水平？（零基础 / 有一定基础 / 有经验的开发者）
- 读者的操作系统环境？（macOS / Windows / Linux / 不限）
- 教程完成后读者应该能做什么？（具体可交付的成果）
- 有没有特定版本或技术栈的约束？
- 如果用户要求跳过澄清，则基于以下默认假设继续：
- 读者：有基本编程经验但不熟悉该技术
- 环境：同时覆盖 macOS 和 Linux（必要时注明 Windows 差异）
- 目标：能独立完成一个最小可工作的示例
输出：教程元信息摘要（主题、受众、目标、范围，不超过 150 字）
Phase 2: 前置知识梳理（Prerequisites）
目标：列出读者在开始本教程前需要掌握的所有知识和工具，确保没有知识断层。
操作步骤：
-
知识依赖分析：
- 列出本教程涉及的所有技术概念
- 逐项判断：该概念是"教程内讲解"还是"读者应已掌握"
- 判断标准：如果展开讲解会偏离主题超过 200 字，则归为前置知识
-
前置知识清单：
-
自检规则：
- 如果前置知识超过 5 项，考虑缩小教程范围或拆分为系列教程
- 每项前置知识必须有公开可获取的学习资源可供参考
输出：分层前置知识清单
Phase 3: 环境搭建（Environment Setup）
目标：提供一条可复现的环境配置路径，确保读者在动手核心步骤前环境就绪。
操作步骤：
-
环境清单：列出所有需要安装/配置的工具及推荐版本
- 格式：
工具名 版本要求（如 >= x.y）| 用途说明
- 明确区分"必须安装"和"可选安装"
-
安装步骤：按操作系统分别给出命令
-
环境验证：每个工具安装后提供验证命令和预期输出
-
自检规则：
- 所有安装命令必须来自官方文档或主流包管理器，不使用第三方脚本
- 不包含任何 API Key、密码、token 等敏感信息的真实值
- 涉及配置文件时，使用占位符（如
YOUR_API_KEY）并说明获取途径
输出：分操作系统的安装配置指南 + 验证命令
Phase 4: 核心步骤（Core Steps）
目标：以递进式结构带领读者从零完成核心操作，每一步都可独立验证。
操作步骤：
-
步骤规划：
- 将整个操作拆分为 5-10 个步骤（每步聚焦一个子目标）
- 步骤之间严格按依赖关系排序
- 每步包含：步骤编号、标题、目标说明
-
步骤编写格式：
#### 步骤 N：[步骤标题]
**目标**：[这一步完成后达到什么状态]
**操作**：
[代码块或操作说明]
**解释**：
- [逐行/逐段解释关键部分的含义]
**验证**：
[运行什么命令/检查什么结果来确认这一步成功]
预期输出：[具体的预期结果]
-
编写规范：
- 代码块必须标注语言类型（如
bash、python）
- 占位符使用全大写 + 下划线格式（如
YOUR_PROJECT_NAME），并在首次出现时说明含义
- 每个代码块不超过 30 行；超过时拆分并分段解释
- 文件路径使用相对路径，开头说明项目根目录
- 每一步结尾必须有验证环节
-
渐进复杂度：
- 前 1-3 步：最小可运行示例（Hello World 级别）
- 中间步骤：逐步加入真实场景的特性
- 最后 1-2 步：组合所有内容形成完整示例
输出：编号步骤列表，每步含操作 + 解释 + 验证
Phase 5: 常见报错与排查（Troubleshooting）
目标：预判读者可能遇到的问题，提供从错误信息到解决方案的直达路径。
操作步骤：
-
报错收集：基于技术主题，列出 5-8 个最常见的报错场景
- 来源：环境配置错误、版本不兼容、权限问题、拼写错误、网络问题等
-
报错条目格式：
**报错 N：[错误信息摘要]**
完整错误信息：
[实际错误输出]
原因：[一句话解释为什么会出现这个错误]
解决方案：
[具体的修复命令或操作步骤]
验证修复：
[运行什么来确认问题已解决]
-
编写规范：
- 错误信息必须是真实存在的（不编造错误信息）
- 解决方案必须对应具体的操作，不使用"请检查配置"等模糊指引
- 如果一个报错有多种可能原因，按概率从高到低排列
- 涉及权限问题时，解释为什么需要该权限，而非直接给出
sudo 或 chmod 777
-
自检规则：
- 解决方案中不包含可能导致安全风险的操作（如
chmod 777、禁用防火墙等）
- 不建议读者关闭安全特性来"解决"问题
输出：结构化报错排查表
Phase 6: 进阶拓展（Advanced Topics）
目标：为完成基础教程的读者指明进阶方向，提供从入门到深入的学习路径。
操作步骤：
-
进阶主题推荐（3-5 个方向）：
-
实战项目建议：
- 提供 2-3 个可以用本教程所学知识独立完成的小项目
- 每个项目包含：项目名称、一句话描述、涉及的知识点
-
最佳实践提示（3-5 条）：
- 生产环境与教程环境的关键差异
- 安全注意事项
- 性能优化方向
输出：进阶学习路线图 + 实战项目建议 + 最佳实践
Phase 7: Cheatsheet 速查表
目标：提炼教程精华为一页速查表，供读者日常参考。
操作步骤：
-
速查表结构：
# [技术名称] Cheatsheet
## 环境信息
| 项目 | 命令/路径 |
|------|-----------|
| 安装 | `命令` |
| 版本检查 | `命令` |
| 配置文件位置 | `路径` |
## 常用命令
| 操作 | 命令 | 说明 |
|------|------|------|
| xxx | `xxx` | xxx |
## 常用代码片段
[最多 5 个高频使用的代码片段，每个不超过 10 行]
## 快速排错
| 症状 | 可能原因 | 快速修复 |
|------|----------|----------|
| xxx | xxx | `xxx` |
-
编写规范：
- 速查表总长度控制在可打印的 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 开始输出 |
| 用户说"直接写/不用问" | 快速模式 | 基于默认假设直接输出完整教程 |
质量检查清单
在输出最终教程前，逐项检查：
迭代优化
如果用户对教程有反馈：
- 定位反馈涉及的 Phase
- 从该 Phase 重新执行
- 向下级联更新所有受影响的内容（如环境变更需同步更新后续步骤和 Cheatsheet）
- 保持步骤编号的连续性
适用场景
本教程生成器适用于以下类型的技术教程：
- 工具使用类：Git、Docker、Kubernetes、Vim 等工具的使用教程
- 环境搭建类：开发环境、CI/CD 流水线、服务器配置等
- 编程入门类：语言入门、框架上手、库的使用等
- 运维操作类：部署、监控、日志、备份恢复等操作手册
- 数据处理类：数据库操作、ETL 流程、数据分析工具使用等
