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: 文档组装与输出 **目标**：将前七个阶段的产出组装成完整教程文档。 **教程文档模板**： ```markdown # [技术主题] 完整教程 > 最后更新：[当前日期] | 适用版本：[版本号] > 难度：[入门/中级/高级] | 预计耗时：[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 流程、数据分析工具使用等