Skill: hiqishen/tech-doc-writer (version 1.3.4)

--- name: tech-doc-writer description: This skill should be used when the user wants to write detailed technical learning documentation, study notes, or knowledge summaries for deep learning, machine learning, or any technical topic. Use when user says "技术文档写作", "写一篇...文档", "整理...笔记", "写一篇关于...的学习资料", "结合文章写一份文档", or requests comprehensive technical documentation with formulas, code examples, and comparisons. Produces structured, detailed markdown documents with mathematical formulas, code examples, comparison tables, and decision guides following a consistent high-quality format. version: 1.5.0 --- # 技术学习文档写作 Skill 本 skill 指导如何写高质量、结构清晰、内容详细的技术学习文档（markdown 格式），适用于深度学习、机器学习、算法原理等技术主题。风格参考：激活函数文档、归一化方法文档。 **核心目标**：确保文档内容全面、及时反映技术最新发展，避免遗漏重要的新兴技术和实践。 --- ## 核心写作流程 ### Step 1：信息收集 如果用户提供了参考文章 URL，**先获取原文内容**，然后： 1. 识别原文覆盖的知识点 2. 获取当前系统时间,找出原文的**错误、缺失、过时**的内容 3. 结合自身知识**补充原文没有的重要内容**，特别是**最新的技术发展和实践** > **重要原则**：不是"翻译"原文，而是以原文为基础，用自己的理解**重写和扩充**，确保内容的全面性和时效性。 > > **特别注意**：对于技术领域的文档，要重点关注近 3-5 年内的重要进展，如大模型中使用的 RMSNorm、SwiGLU 等新兴技术。 ### Step 1.5：穷举知识点 Checklist（⚠️ 强制步骤，不可跳过） > **这是防止内容遗漏的核心机制。** 过去的教训：直接进入写作模式会导致「写作驱动」而非「规划驱动」，靠「想到什么写什么」会遗漏非显眼但重要的技术点（如 MMR、RAG-Fusion、Semantic Cache 等）。 **在动笔之前，必须先完成以下 3 个动作：** **动作 1：按维度分类，穷举所有候选技术点** 对文档主题，按照以下维度系统扫描，列出所有相关技术点： ``` 维度扫描框架（根据主题调整）： - 算法/方法类：基础方法 + 变体 + 新兴方法 - 工程实现类：库/框架 + 工具 + 部署 - 评估/对比类：指标 + 基准测试 + 对比维度 - 优化/改进类：性能优化 + 成本优化 + 质量优化 - 生态/周边类：相关工具 + 集成方案 ``` **动作 2：参照权威来源交叉验证**，防止遗漏： - 主流框架文档的 **API/模块目录**（最完整的技术地图，如 LangChain Retrievers 文档） - 最新 **Survey 论文**的技术分类表 - 相关 **GitHub Awesome 列表** **动作 3：将所有技术点组织为带复选框的 Checklist** ```markdown 示例（RAG 主题）： 【分块策略】 □ 固定字符分块 □ 递归字符分块 □ Token 分块 □ 语义分块 □ 父文档检索 □ 命题分块 ← 容易遗漏（偏论文，不如框架API显眼） 【检索方式】 □ 纯向量检索 □ BM25 关键词检索 □ 混合检索 + RRF □ MMR 多样性检索 ← 容易遗漏（解决多样性，方向与精度类不同） □ Metadata Filtering ← 容易遗漏（工程技巧，不像算法显眼） 【查询增强】 □ Multi-Query □ RAG-Fusion ← 容易遗漏（与 Multi-Query 相似，常被合并忽视） □ HyDE □ Step-Back Prompting 【工程优化】 □ Semantic Cache ← 容易遗漏（工程优化类，非核心算法） □ 增量更新策略 ``` **完成 Checklist 后，对照着写文档，每完成一项打勾。** 最终检查未打勾的项是否有意跳过还是遗漏。 --- ### Step 2：确定文档结构 每篇技术文档必须包含以下模块（按需取舍）： **通用结构（算法/框架类）：** ``` 1. 引言（为什么需要 XXX） 2. 统一视角 / 核心框架（用一个视角统一理解所有方法） 3. 各方法详解（每个方法独立一节） 4. 方法对比表（综合横向比较） 5. 选择指南 / 决策树（实用建议） 6. 代码示例（PyTorch / Python） 7. 参考资料 ``` **命令行工具专属结构（⚠️ 如文档主题是 CLI 工具/命令行程序，必须额外包含参数完整索引章节）：** ``` 1. 引言（工具简介、与其他工具对比、安装） 2. 核心概念（命令/子命令体系、配置文件等） 3. 各子命令详解（每个子命令独立一节，含常用选项示例） 4. 配置详解（配置文件格式、优先级等） 5. 工程集成（CI/CD、编辑器、预提交钩子等） 6. 最佳实践与常见陷阱 N-1. 参数完整索引（⚠️ 必须包含，见下方格式规范） N. 参考资料 ``` > **判断标准**：文档主题涉及命令行工具（如 ruff、curl、git、uv、docker、kubectl 等）时，必须包含「参数完整索引」章节作为倒数第二章节。 **工具/框架类专属结构（⚠️ 如文档主题是有配置项的工具/框架，必须包含环境变量章节）：** > **判断标准**：文档主题涉及有环境变量支持的工具/框架（如 uv、docker、node、python、git 等）时，必须包含「环境变量」章节，完整列出所有支持的环境变量。 环境变量章节规范： - **位置**：放在「安装与配置」章节内，或作为独立章节（配置后、实战案例前） - **分组**：按功能分组（如「路径/目录」「网络/代理」「认证」「行为控制」等） - **格式**：每组一张 3 列表格 `变量名 | 说明 | 示例/默认值`，重要变量标注加入版本 - **完整性**：必须覆盖官方文档的全部环境变量，不可只列「常用」的几个 - **弃用标注**：已弃用的变量须注明 ⚠️ 已弃用及替代变量 - **外部变量**：除工具自身定义的变量外，还需列出工具读取的外部系统变量（如代理、TLS 证书等） ```markdown ### X.X 环境变量（完整列表） > 官方参考：https://docs.xxx.xxx/reference/environment/ #### X.X.1 <工具名> 自身定义的环境变量 **📁 路径与目录** | 变量 | 说明 | 示例/默认值 | |------|------|-----------| | `TOOL_CACHE_DIR` | 缓存目录 | `~/.cache/tool` | **🌐 网络与代理** | 变量 | 说明 | 示例/默认值 | |------|------|-----------| | `TOOL_HTTP_TIMEOUT` | HTTP 超时（秒） | `30` | #### X.X.2 <工具名> 读取的外部变量 | 变量 | 说明 | |------|------| | `HTTP_PROXY` | HTTP 代理 | | `HTTPS_PROXY` | HTTPS 代理 | #### X.X.3 使用示例 ```bash # 示例注释 TOOL_VAR=value tool command ``` ``` ### Step 3：写各方法详解 每个方法/概念的详解必须包含： - **论文出处**：作者、机构、年份、论文名 - **提出动机**：解决什么问题（why） - **数学定义**：完整公式（LaTeX 格式） - **导数 / 梯度**：反向传播必要信息 - **直觉解释**：用类比或图示帮助理解（why it works） - **优点表格**：结构化列出 - **缺点表格**：结构化列出，包含已知的反驳/修正 - **适用场景**：具体的任务、架构、数据类型 - **代码示例**：可运行的代码片段 ### Step 4：补充原文没有的视角 优先添加以下高价值内容： 1. **统一理论框架**：如"所有归一化方法的本质区别是在哪个维度做统计" 2. **历史演进脉络**：用时间线梳理技术发展，突出技术迭代的逻辑 3. **已被推翻的叙事**：如"BN 有效不是因为解决了 ICS，而是平滑了损失曲面" 4. **现代实践**：最新的大模型 / SOTA 方法在用什么（如 RMSNorm、SwiGLU、LayerNorm 的变体等） 5. **新兴技术覆盖**：重点关注近 3-5 年内提出的重要技术，确保文档反映技术前沿 6. **跨领域应用**：不同领域（如 NLP、CV、生成模型）中归一化方法的选择差异 7. **常见陷阱**：实践中容易踩的坑（如 PyTorch BN 的 momentum 定义与数学相反） 8. **决策树**：帮助读者快速找到适合自己场景的方法 ### Step 5：写综合对比表 必须包含横向对比表，列出： | 字段 | 说明 | |------|------| | 方法名 + 提出年份 | 时间感 | | 核心公式摘要 | 快速对比 | | 关键特性（布尔值）| 一目了然 | | 计算效率（星级）| 相对成本 | | 主要应用场景 | 实用导向 | ### Step 6：分步输出（⚠️ 强制步骤） 对于**大型技术文档**（预计超过 500 行 / 5 个以上章节），必须采用分步输出策略： 1. **建立 todo list**，将文档拆分为 5~8 个 Part，每个 Part 对应 1~2 个章节 2. **每次只输出一个 Part**，完成后立即继续下一个 Part，无需等待用户催促 3. **自动推进**：每个 Part 完成后，标记 todo 为 completed，立即开始下一个 4. **告知进度**：在每个 Part 开头说明"当前是第 X/N 部分" > **原因**：一次性生成过长内容容易截断、遗漏章节、丢失上下文。分步输出确保每部分质量，也让用户实时看到进展。 5. **结构完整性校验（⚠️ 强制）**：所有 Part 写完后，执行以下命令验证章节结构： ```bash grep -n "^## " 文档文件名.md ``` 确认输出中章节编号**从 1 开始连续递增，无跳号、无缺失**。若发现如「第3章后直接是第8章」的跳号，必须立即补全缺失章节，再进行后续输出。 ### Step 7：完成后遗漏自检（⚠️ 强制步骤） **文档全部写完后**，必须执行一次遗漏自检，步骤如下： 1. 列出文档现有的所有章节/技术点（`grep "^### \|^####"` 扫描） 2. 重新过一遍 Step 1.5 的 Checklist，逐项确认是否已覆盖 3. **重点核查容易遗漏的维度**： - 工程优化类（缓存、增量更新、可观测性） - 多样性/效率类（与主流精度类方向不同） - 新兴/小众但重要的技术（近 1~2 年新提出） 4. 若发现遗漏，立即补充到对应章节 > **教训**：本规则来自实际 RAG 文档写作经验——初版遗漏了 MMR、RAG-Fusion、Semantic Cache、Multi-Vector Index、ColBERT、LLMLingua 等多项重要技术，均在事后检查中发现补充。 --- ## 格式规范 ### 数学公式 - 所有公式使用 LaTeX 格式 - 行内公式：`$f(x) = ...$` - 块级公式：`$$f(x) = ...$$` - 必须给出**导数/梯度**公式（反向传播需要） - 重要变量要注解其含义 ```markdown **数学定义：** $$\sigma(x) = \frac{1}{1 + e^{-x}}$$ **导数：** $$\sigma'(x) = \sigma(x)\big(1 - \sigma(x)\big)$$ ``` ### 代码示例 - 使用 Python / PyTorch（深度学习场景） - 代码要**可运行**，包含必要的 import - 加中文注释 - 示例要体现**实际使用场景**，而非只是 API 调用 ```python # 示例：SwiGLU（LLaMA FFN 层） class SwiGLU(nn.Module): """LLaMA / PaLM 使用的前馈层，用 SwiGLU 替代标准 FFN""" def __init__(self, in_dim, hidden_dim): super().__init__() self.w1 = nn.Linear(in_dim, hidden_dim, bias=False) self.w2 = nn.Linear(hidden_dim, in_dim, bias=False) self.w3 = nn.Linear(in_dim, hidden_dim, bias=False) def forward(self, x): # SiLU(xW1) ⊙ (xW3)，再经过 W2 投影 return self.w2(F.silu(self.w1(x)) * self.w3(x)) ``` ### ASCII 图示 对于维度关系、架构结构，使用 ASCII 图增强可视化： ``` N (Batch) │ ┌─────┼─────┐ │ S1 │ S2 │ └──┬──┘──┬──┘ │ C │ ┌──┴──┐ │ch1 │ch2│ H×W └─────┴───┘ BN: 在 N×H×W 上统计（跨样本） LN: 在 C×H×W 上统计（跨通道） ``` ### 表格规范 优缺点用**结构化表格**，不用列表： ```markdown | 优点 | 说明 | |------|------| | 加速训练 | 允许更大学习率，收敛快 | | 正则化效果 | mini-batch 噪声类似 Dropout | ``` ### 参数完整索引规范（CLI 工具文档专用） 当文档主题为命令行工具时，**倒数第二章节**必须是「参数完整索引」，按功能分组，每个分组一张 4 列表格。 **列顺序**：`短参数 | 长参数 | 说明 | 示例` **格式要求**： - 无短参数的行，短参数列**留空**（不写 `—` 或 `/`） - 示例列必须是**可直接运行**的完整命令片段 - 同一子命令的参数按「修复/输出/规则选择/文件选择/其他」等功能子分组，用 `####` 小标题分隔 - 子命令本身单独列一张「子命令一览」表，包含「子命令 / 说明 / 是否修改文件 / 示例」4 列 **标准模板：** ```markdown ## N. 参数完整索引 > 按功能分类整理所有常用参数，便于快速查阅。 ### N.1 子命令一览 | 子命令 | 说明 | 是否修改文件 | 示例 | |--------|------|------------|------| | `check` | 执行 lint 检查 | 否（`--fix` 时是） | `ruff check .` | | `format` | 执行代码格式化 | 是（`--check` 时否） | `ruff format .` | ### N.2 全局选项 | 短参数 | 长参数 | 说明 | 示例 | |--------|--------|------|------| | `-v` | `--verbose` | 启用详细日志 | `-v` | | | `--config <FILE>` | 指定配置文件 | `--config ruff.toml` | ### N.3 <子命令名> 选项 #### 修复相关 | 短参数 | 长参数 | 说明 | 示例 | |--------|--------|------|------| | | `--fix` | 应用安全修复 | `ruff check --fix .` | ``` **参考示例**：见 `zwy/stats/py_base/002_doc_ruff.md` 第 9 章、`zwy/stats/shell/004_doc_curl_wget_shell.md` 第 10 章。 ### 引用、警告块 用 blockquote 标注重要修正或补充： ```markdown > **重要修正**：后续研究表明，BN 的有效性主要来自平滑损失曲面， > 而非解决 ICS——这是对原始论文叙事的重要修正。 ``` --- ## 质量检查清单 写完文档后，获取当前系统时间,仔细检查文档，简单梳理结构，看看是否有过时内容，遗漏内容和改进的地方,未解释的缩写或名词,并进行改进。 然后逐项确认： **【分步输出检查（Step 6 相关）】** - [ ] 大型文档已建立 **todo list** 并分 Part 输出 - [ ] 每个 Part 完成后**立即自动继续**下一 Part，未等待用户催促 - [ ] 用 `grep -n "^## "` 扫描最终文件，验证章节编号**从 1 开始连续递增**，无跳号、无缺失 **【完成后遗漏自检（Step 7 相关）】** - [ ] 已用 `grep` 扫描当前文档所有章节，重新过 Checklist - [ ] 已重点核查「**工程优化类**」是否有遗漏 - [ ] 已重点核查「**多样性/效率类**」是否有遗漏 - [ ] 已重点核查「**近 1~2 年新技术**」是否有遗漏 **【防遗漏检查（Step 1.5 相关）】** - [ ] 写作前已完成**维度化穷举 Checklist**（Step 1.5） - [ ] 已对照框架文档/Survey 论文的**模块目录**交叉验证 - [ ] Checklist 中所有条目均已**有意决定**（写入文档 or 明确标注跳过原因） - [ ] 检查是否遗漏「**工程优化类**」技术（如缓存、增量更新等，常被算法类掩盖） - [ ] 检查是否遗漏「**多样性/效率类**」技术（与主流精度类方向不同，易被忽视） **【内容质量检查】** - [ ] 每个方法都有**完整的数学公式**（含导数） - [ ] 每个方法都有**代码示例**（可运行） - [ ] 包含**综合对比表** - [ ] 包含**选择指南/决策树** - [ ] 补充了原文**缺失的重要方法**（如 RMSNorm、SwiGLU 等现代方法） - [ ] 重点覆盖了**近 3-5 年内的重要技术进展** - [ ] 指出了原文的**错误或过时信息** - [ ] 有**直觉解释**（不只是公式堆砌） - [ ] 提到了**实际使用中的陷阱** - [ ] 参考了**最新的 SOTA 实践** - [ ] 考虑了**跨领域应用**的差异 **【CLI 工具文档专项检查】** - [ ] 文档主题是 CLI 工具时，已包含**参数完整索引**章节（倒数第二章） - [ ] 参数索引表列顺序为「**短参数 / 长参数 / 说明 / 示例**」 - [ ] 无短参数的行，短参数列**留空**（不写 `—`） - [ ] 每行示例列为**可直接运行**的命令片段 - [ ] 参数按**功能分组**，用 `####` 小标题分隔（修复/输出/规则选择/文件/其他） - [ ] 包含**子命令一览**表（含「是否修改文件」列） **【环境变量章节检查（有环境变量支持的工具/框架类文档专用）】** - [ ] 已包含**环境变量完整列表**章节（不仅仅是「常用」几个） - [ ] 环境变量按**功能分组**，每组一张 3 列表格 - [ ] 已弃用的变量已标注 ⚠️ 并注明**替代变量** - [ ] 列出了工具读取的**外部系统变量**（代理、TLS 证书、认证 token 等） - [ ] 包含**使用示例**小节（至少 5 个实用场景） - [ ] 变量来源于**官方文档**，而非仅凭记忆列举（关键变量需标注加入版本） --- ## 参考示例 详见 `references/` 目录： - `references/activation-functions-example.md` — 激活函数文档节选示例 - `references/normalization-example.md` — 归一化文档节选示例

path: references/activation-functions-example.md
content: # 激活函数文档节选示例

> 本文件展示了 tech-doc-writer skill 的写作风格，以激活函数文档中的 ReLU 和 GELU 两节为例。

---

## 示例 1：ReLU（展示基础方法的写法）

### ReLU（修正线性单元）

**论文**：Rectified Linear Units Improve Restricted Boltzmann Machines（Nair & Hinton，2010）

**数学定义：**

$$\text{ReLU}(x) = \max(0, x) = \begin{cases} x & x > 0 \\ 0 & x \leq 0 \end{cases}$$

**导数：**

$$\text{ReLU}'(x) = \begin{cases} 1 & x > 0 \\ 0 & x < 0 \end{cases}$$

**直觉解释**：只保留正信号，负信号清零。计算只需一次比较，极其高效。正半轴梯度恒为 1，梯度可以无衰减地反向传播——这是解决梯度消失的核心。

**优点：**

| 优势 | 说明 |
|------|------|
| 缓解梯度消失 | 正半轴梯度恒为 1 |
| 稀疏激活 | 约 50% 输出为 0，正则化效果 |
| 计算高效 | 仅一次比较，无指数运算 |

**缺点：**

| 问题 | 说明 |
|------|------|
| Dead ReLU | 负输入区梯度为 0，神经元可能永久死亡 |
| 非零中心 | 输出均值大于 0，收敛略慢 |

```python
import torch.nn.functional as F

out = F.relu(x)
```

---

## 示例 2：GELU（展示现代方法的写法，含直觉解释）

### GELU（高斯误差线性单元）

**论文**：Gaussian Error Linear Units（Hendrycks & Gimpel，2016）

**数学定义：**

$$\text{GELU}(x) = x \cdot \Phi(x) = x \cdot P(X \leq x), \quad X \sim \mathcal{N}(0,1)$$

**近似公式**（实际实现常用）：

$$\text{GELU}(x) \approx 0.5x\left(1 + \tanh\left(\sqrt{\frac{2}{\pi}}\left(x + 0.044715 x^3\right)\right)\right)$$

**直觉解释**：GELU 是"概率门控"的 ReLU——以概率 $\Phi(x)$ 通过输入，概率随 $x$ 大小平滑变化。大正值几乎全部通过，小负值几乎全部被抑制，但不是硬截断而是平滑过渡。

**与 ReLU 对比：**

| 特性 | ReLU | GELU |
|------|------|------|
| 负半轴处理 | 硬截断为 0 | 平滑衰减 |
| 可微性 | x=0 不可微 | 处处可微 |
| 在 Transformer 中 | 较少使用 | 主流选择 |

```python
# 精确版本
out = F.gelu(x)

# 近似版本（速度稍快）
out = F.gelu(x, approximate='tanh')
```


path: references/normalization-example.md
content: # 归一化文档节选示例

> 本文件展示了 tech-doc-writer skill 的写作风格，以归一化文档中的"统一视角"章节和 BN 章节为例。

---

## 示例 1：统一视角（这种"元框架"是文档质量的关键）

### 归一化的统一视角：在哪个维度做统计

几乎所有归一化方法的本质区别，就在于**在哪些维度上计算均值和方差**。

对于 4D 特征张量 $\mathbf{X} \in \mathbb{R}^{N \times C \times H \times W}$：

| 方法 | 统计维度 | 对应轴 |
|------|---------|--------|
| **BN** | N, H, W（跨样本，每通道独立） | `axis=[0, 2, 3]` |
| **LN** | C, H, W（跨通道，每样本独立） | `axis=[1, 2, 3]` |
| **IN** | H, W（空间维度，每样本每通道独立） | `axis=[2, 3]` |
| **GN** | C/G, H, W（按组分通道） | 按组划分 |

> 这个"统一视角"框架是原文没有的——它帮助读者从根本上理解各方法，而不是机械地记忆各个公式。

---

## 示例 2：BN（展示"重要修正"的写法）

### Batch Normalization

**提出动机**：Ioffe & Szegedy（2015）认为 BN 解决了 **Internal Covariate Shift（ICS）**——每层输入分布随参数更新而变化，导致训练不稳定。

> **⚠️ 重要修正**：Santurkar et al.（2018）在论文《How Does Batch Normalization Help Optimization?》中通过实验证明，BN 的有效性**并非**主要来自解决 ICS，而是通过**平滑损失曲面（loss landscape）**使梯度更稳定。这是对原始论文叙事的重要修正，不必迷信 ICS 叙事。

**训练 vs 推理的差异**（原文常忽略的细节）：

- **训练阶段**：用当前 mini-batch 的均值和方差
- **推理阶段**：用训练期间积累的**移动平均**（Running Statistics）

$$\mu_{\text{running}} \leftarrow (1 - \alpha) \mu_{\text{running}} + \alpha \mu_\mathcal{B}$$

**常见陷阱**：

```python
# ⚠️ PyTorch BN 的 momentum 定义与数学通常写法相反！
# PyTorch: new = (1 - momentum) * old + momentum * batch_stat
# 数学写法通常: new = momentum * old + (1-momentum) * new_val
# PyTorch 默认 momentum=0.1，表示"当前 batch 权重 0.1，历史权重 0.9"

bn = nn.BatchNorm2d(64, momentum=0.1)  # 这是 PyTorch 默认值

# 另一个常见错误：忘记切换 eval 模式
model.eval()  # 必须切换！否则推理用 batch 统计，batch=1 时不稳定
with torch.no_grad():
    output = model(x)
```


Security scan verdicts — ClawScan: clean | static analysis: clean | VirusTotal: clean | SkillSpector: suspicious (HIGH)