technical-tutorials

技术教程

此技能可帮助你创建真正能运行的分步教程。内容涵盖前置条件处理、循序渐进地增加复杂度、故障排除部分，以及打造令人满意的“成功了！”时刻。

---

开始之前

先加载受众背景信息。 阅读 .agents/developer-audience-context.md，了解：

• 开发者的技能水平（初级、中级、高级）
• 对技术栈的熟悉程度（可以假定他们了解什么？）
• 使用环境（macOS、Linux、Windows、云端）
• 学习原因（工作、副项目、兴趣）

如果背景信息文件不存在，请先运行 developer-audience-context 技能。

---

教程类型

类型	时长	目的	示例
快速入门	5-10 分钟	尽快取得首次成功	“发起你的首次 API 调用”
教程	20-45 分钟	深入学习一个概念	“使用 Node.js 构建 REST API”
实践工作坊	1-3 小时	完成综合项目	“构建全栈应用”
代码讲解	不定	讲解现有代码	“了解我们的 SDK 架构”

---

教程结构

优秀教程的组成

1. Title & Meta
   - What you'll build
   - Time estimate
   - Prerequisites

2. Overview
   - What you'll learn
   - Final result preview

3. Prerequisites Check
   - Environment setup
   - Verification commands

4. The Build (Progressive Steps)
   - Step 1: Simplest foundation
   - Step 2: Add one concept
   - Step 3: Add complexity
   - [Checkpoint: "It works!" moment]
   - Step 4: Continue building
   - ...
   - [Final checkpoint]

5. What You Built
   - Recap
   - Complete code

6. Troubleshooting
   - Common errors
   - Debugging tips

7. Next Steps
   - Where to go from here
   - Related tutorials

---

前置条件处理

前置条件部分

明确说明。不要让开发者猜测需要什么。

## Prerequisites

Before starting, make sure you have:

| Requirement | Version | Check Command |
|-------------|---------|---------------|
| Node.js | 18+ | `node --version` |
| npm | 9+ | `npm --version` |
| Git | Any | `git --version` |

You should also be comfortable with:
- Basic JavaScript (variables, functions, async/await)
- Command line basics (cd, mkdir, running commands)
- REST API concepts (HTTP methods, JSON)

**New to any of these?** Check out [link to prerequisite tutorial].

环境设置部分

让设置过程万无一失：

## Setting Up Your Environment

### 1. Create Project Directory

\`\`\`bash
mkdir my-awesome-project
cd my-awesome-project
\`\`\`

### 2. Initialize the Project

\`\`\`bash
npm init -y
\`\`\`

You should see output like:
\`\`\`json
{
  "name": "my-awesome-project",
  "version": "1.0.0",
  ...
}
\`\`\`

### 3. Install Dependencies

\`\`\`bash
npm install express dotenv
\`\`\`

### 4. Verify Installation

\`\`\`bash
node -e "require('express'); console.log('Express installed!')"
\`\`\`

Expected output: `Express installed!`

---

循序渐进地增加复杂度

分层递进方法

逐层构建，确保每一层都易于理解：

层级	功能	示例
1. 骨架	可运行的最小可行代码	“Hello World” 服务
2. 核心功能	主要功能	添加一个 API 端点
3. 真实数据	替换硬编码值	连接数据库
4. 错误处理	面向生产环境的模式	添加 try/catch、验证
5. 润色	可选增强项	日志记录、配置、测试

展示进步，而非追求完美

错误做法（令人应接不暇）：

// Here's the complete file with everything
const express = require('express');
const { Pool } = require('pg');
const helmet = require('helmet');
const rateLimit = require('express-rate-limit');
const winston = require('winston');
// ... 200 more lines

正确做法（循序渐进）：

步骤 1：基础服务

const express = require('express');
const app = express();

app.get('/', (req, res) => {
  res.send('Hello World!');
});

app.listen(3000, () => {
  console.log('Server running on http://localhost:3000');
});

步骤 2：添加你的第一个路由

// Add this below your existing route
app.get('/api/users', (req, res) => {
  res.json([{ id: 1, name: 'Jane' }]);
});

---

便于复制粘贴的代码

复制粘贴检查清单

每个代码块都必须通过以下测试：

测试	验证方法
可独立运行	复制到新文件中并执行，确认可以正常运行
包含导入语句	包含所有 require/import 语句
没有未定义变量	不引用其他步骤中的代码，除非已将其展示出来
不依赖特定环境	在 Mac/Linux/Windows 上都能运行
注释解释原因	解释为什么这样做，而不是做什么（代码会展示做什么）

代码块模式

文件上下文至关重要：

// server.js - Add this to your existing file
const rateLimit = require('express-rate-limit');

// Add this BEFORE your routes
const limiter = rateLimit({
  windowMs: 15 * 60 * 1000, // 15 minutes
  max: 100 // limit each IP to 100 requests per window
});

app.use(limiter);

展示文件结构：

my-project/
├── src/
│   ├── index.js      ← You're editing this
│   ├── routes/
│   │   └── users.js
│   └── db/
│       └── connection.js
├── package.json
└── .env

在上下文中突出显示改动：

// src/index.js
const express = require('express');
const app = express();

// ✅ ADD THIS: Import your new route
const userRoutes = require('./routes/users');

// ✅ ADD THIS: Use the route
app.use('/api/users', userRoutes);

app.listen(3000);

---

“成功了！”时刻

检查点能带来动力

每隔 3-5 个步骤，就让开发者获得一次成就：

## Checkpoint: Test Your API

Let's make sure everything works before continuing.

**Start your server:**
\`\`\`bash
node server.js
\`\`\`

**In a new terminal, test the endpoint:**
\`\`\`bash
curl http://localhost:3000/api/users
\`\`\`

**You should see:**
\`\`\`json
[{"id": 1, "name": "Jane"}]
\`\`\`

🎉 **It works!** Your API is returning data.

If you don't see this output, check the [Troubleshooting](#troubleshooting) section.

视觉确认

尽可能展示成功的样子：

输出类型	展示方式
终端输出	使用代码块展示预期文本
浏览器结果	截图或描述
API 响应	格式化后的 JSON
日志	使用代码块展示日志输出

---

故障排除部分

常见错误模板

## Troubleshooting

### "Error: Cannot find module 'express'"

**Cause:** Dependencies weren't installed.

**Fix:**
\`\`\`bash
npm install
\`\`\`

---

### "EADDRINUSE: address already in use :::3000"

**Cause:** Another process is using port 3000.

**Fix (macOS/Linux):**
\`\`\`bash
# Find the process
lsof -i :3000

# Kill it (replace PID with actual number)
kill -9 PID
\`\`\`

**Or use a different port:**
\`\`\`javascript
app.listen(process.env.PORT || 3001);
\`\`\`

---

### "SyntaxError: Unexpected token"

**Cause:** Likely a typo or missing bracket.

**Debug steps:**
1. Check the line number in the error
2. Look for missing `,`, `}`, or `)`
3. Verify all strings are closed with matching quotes

主动预防错误

在常见陷阱出现前添加警告：

⚠️ **Windows users:** Use `set` instead of `export`:
\`\`\`bash
# macOS/Linux
export API_KEY=your_key

# Windows Command Prompt
set API_KEY=your_key

# Windows PowerShell
$env:API_KEY="your_key"
\`\`\`

---

教程模板

快速入门模板（5-10 分钟）

# [Product] Quickstart: [What You'll Do] in 5 Minutes

Get [specific outcome] in under 5 minutes.

## Prerequisites

- [Requirement 1]
- [Requirement 2]

## Step 1: Install

\`\`\`bash
npm install your-package
\`\`\`

## Step 2: Configure

Create a `.env` file:
\`\`\`
API_KEY=your_key_here
\`\`\`

## Step 3: Write Code

Create `index.js`:
\`\`\`javascript
// Complete, working code
\`\`\`

## Step 4: Run It

\`\`\`bash
node index.js
\`\`\`

Expected output:
\`\`\`
[Output here]
\`\`\`

## 🎉 You Did It!

You just [accomplished thing].

**Next steps:**
- [Link to full tutorial]
- [Link to API docs]
- [Link to examples repo]

完整教程模板（20-45 分钟）

# Build a [Thing] with [Technology]

Learn how to [outcome] by building [specific project].

| | |
|---|---|
| **Time** | 30 minutes |
| **Level** | Intermediate |
| **Prerequisites** | Node.js 18+, basic JavaScript |

## What You'll Build

[Screenshot or diagram of final result]

By the end, you'll have:
- ✅ [Capability 1]
- ✅ [Capability 2]
- ✅ [Capability 3]

## Prerequisites

### Required Software

| Tool | Version | Verify |
|------|---------|--------|
| Node.js | 18+ | `node -v` |

### Required Knowledge

- [Concept 1] — [link to learn]
- [Concept 2] — [link to learn]

## Step 1: Project Setup

[Setup instructions with verification]

**Checkpoint:** You should see `[expected output]`.

## Step 2: [First Feature]

[Instructions]

**Checkpoint:** Test with `[command]`.

## Step 3: [Second Feature]

[Instructions]

## Step 4: [Third Feature]

[Instructions]

**Checkpoint:** Your app should now [do thing].

## Complete Code

Here's everything together:

\`\`\`javascript
// Full final code
\`\`\`

## Troubleshooting

### [Common Error 1]
[Solution]

### [Common Error 2]
[Solution]

## What You Learned

- [Key concept 1]
- [Key concept 2]
- [Key concept 3]

## Next Steps

- **Go deeper:** [Link to advanced tutorial]
- **Explore:** [Link to related feature]
- **Get help:** [Link to Discord/community]

---

质量检查清单

发布前，请确认：

代码质量

• 每个代码块都能直接运行，无需修改
• 包含所有导入语句和 require 语句
• 展示预期输出
• 包含错误处理
• 环境变量采用 .env 模式

结构质量

• 明确列出前置条件
• 时间估算准确（请实际测试！）
• 每隔 3-5 个步骤设置检查点
• 提供最终完整代码
• 故障排除部分涵盖可能遇到的错误

无障碍性

• 支持 Mac、Linux 和 Windows
• 命令可在 bash/zsh/PowerShell 中运行
• 文件路径使用正确的分隔符
• 不假设已安装任何工具

---

工具

工具	用途
Octolens	查找开发者遇到的常见问题和错误。监控 Stack Overflow 和 GitHub issues，获取疑难排解内容。
Replit/CodeSandbox	嵌入可运行的示例
Carbon/Ray.so	制作精美的代码截图
Excalidraw	绘制架构图
Terminalizer	录制终端会话
Loom	快速补充视频

---

相关技能

• developer-audience-context — 了解技能水平和环境
• devrel-content — 通用技术写作原则
• developer-onboarding — 缩短首次成功所需时间
• developer-seo — 让教程更容易通过搜索找到