technical-tutorials

用途

technical-tutorials 用于在开发者营销场景中创建真正可运行的分步技术教程、快速上手（quickstart）和代码讲解。它关注前置条件处理、渐进式复杂度、故障排查章节，以及打造读者获得“它跑起来了！”的满足感时刻。

开始之前

先加载受众上下文：读取 .agents/developer-audience-context.md，以了解：

开发者技能水平（初级、中级、高级）
技术栈熟悉度（可以假设他们已掌握什么？）
环境（macOS、Linux、Windows、云端）
学习动机（求职、副业项目、好奇）

如果上下文文件不存在，请先运行 developer-audience-context 技能。

教程类型

类型	篇幅	目的	示例
Quickstart（快速上手）	5-10 分钟	尽快获得首次成功	“完成你的第一次 API 调用”
Tutorial（教程）	20-45 分钟	深入学习一个概念	“用 Node.js 构建 REST API”
Workshop（工作坊）	1-3 小时	完整项目	“构建一个全栈应用”
Code walkthrough（代码讲解）	不定	讲解已有代码	“理解我们的 SDK 架构”

教程结构

优秀教程的解剖结构：

标题与元信息：你将构建什么、时间估计、前置条件
概览：你将学到什么、最终结果预览
前置条件检查：环境搭建、验证命令
构建过程（渐进式步骤）：
- 步骤 1：最简单的基础
- 步骤 2：加入一个概念
- 步骤 3：增加复杂度
- [检查点：“它跑起来了！”时刻]
- 步骤 4：继续构建
- ……
- [最终检查点]
你构建了什么：回顾、完整代码
故障排查：常见错误、调试技巧
后续步骤：接下来去哪、相关教程

前置条件处理

前置条件章节要明确，不要让开发者猜他们需要什么。使用表格列出要求、版本与检查命令，例如：

| 要求 | 版本 | 检查命令 |
|------|------|----------|
| Node.js | 18+ | `node --version` |
| npm | 9+ | `npm --version` |
| Git | 任意 | `git --version` |

同时说明需要熟悉的知识，如基础 JavaScript（变量、函数、async/await）、命令行基础（cd、mkdir、运行命令）、REST API 概念（HTTP 方法、JSON）。若读者不熟悉这些，应提供前置教程链接。

环境搭建章节要写得万无一失：创建项目目录、初始化项目、安装依赖、验证安装，并展示预期输出。

渐进式复杂度

采用“千层蛋糕”方法，按可理解的层次逐层构建：

层次	作用	示例
1. 骨架	可运行的最小可用代码	“Hello World”服务器
2. 核心功能	主要功能	添加一个 API 端点
3. 真实数据	替换硬编码值	连接数据库
4. 错误处理	生产级模式	添加 try/catch、校验
5. 打磨	锦上添花	日志、配置、测试

展示进展，而非完美。不要一次性给出包含全部内容的完整文件，而应先给最简基础，再逐步添加。例如先展示基础服务器代码，再展示添加第一个路由的代码。

便于复制的代码

每个代码块都必须通过以下检查：

测试	如何验证
可独立运行	复制到新文件、执行、能跑通
包含导入	所有 require/import 语句齐全
无未定义变量	不引用未展示的其他步骤代码
环境无关	在 Mac/Linux/Windows 均可运行
注释解释原因	不是解释“做什么”（代码已显示），而是解释“为什么”

代码块中要标注文件上下文（如 // server.js - 添加到你的现有文件），展示文件结构并标记正在编辑的文件，用注释高亮需要添加的改动。

“它跑起来了！”时刻

每 3-5 步给开发者一次胜利体验。检查点示例：启动服务器、在新终端用 curl 测试端点、展示预期 JSON 输出，并用“🎉 它跑起来了！”给予肯定；若未看到输出，则引导至故障排查章节。

尽可能给出成功的样子：终端输出用代码块展示预期文本，浏览器结果用截图或描述，API 响应用格式化 JSON，日志用代码块展示输出。

故障排查章节

为常见错误提供模板：错误信息、原因、修复方法。例如找不到模块时执行 npm install；端口被占用时用 lsof 查找进程并 kill，或换端口；语法错误时检查报错行号、缺失的逗号/括号/引号。

还要主动预防错误，在常见陷阱前加警告。例如 Windows 用户应使用 set 而非 export 设置环境变量（Windows Command Prompt 用 set，PowerShell 用 $env:API_KEY="your_key"）。

教程模板

技能提供 Quickstart 模板（5-10 分钟）和完整教程模板（20-45 分钟）。完整教程模板包含时间/级别/前置条件表格、你将构建什么、前置条件（所需软件表格与所需知识）、分步步骤与检查点、完整代码、故障排查、你学到了什么、后续步骤。

质量检查清单

发布前验证：

代码质量：每个代码块无需修改即可运行；所有导入齐全；展示预期输出；包含错误处理；环境变量使用 .env 模式。
结构质量：前置条件明确；时间估计准确（实际测试）；每 3-5 步设置检查点；提供最终完整代码；故障排查覆盖可能错误。
可访问性：在 Mac、Linux 和 Windows 上均可运行；命令在 bash/zsh/PowerShell 中可用；文件路径分隔符正确；不假设已安装工具。

工具

工具	用途
Octolens	发现开发者遇到的常见问题和错误；监控 Stack Overflow 与 GitHub issues 以撰写故障排查内容
Replit/CodeSandbox	嵌入可运行示例
Carbon/Ray.so	生成美观的代码截图
Excalidraw	架构图
Terminalizer	录制终端会话
Loom	快速视频补充

技能介绍

用途