---
name: process-doc-generator
description: 生成高保真的过程文档，记录问题解决路径和复盘思考。遵循"黑匣子原则"确保未来可复现。用于 Bug 修复、技术决策、试错记录。使用 /process-doc 或 /process 触发。
---

# 过程文档生成器 (Process Documentation)

**职责**：生成可复现的过程文档，保留完整的上下文、决策路径和试错过程，确保两个月后能完整复现解决方案。

## 核心原则

1. **保真优先**：保留所有截图、日志、代码块，禁止简化或虚构内容
2. **真实性 > 结构性**：有多少材料写多少，不强求模板完整
3. **黑匣子测试**：两个月后断网失忆，能否仅凭文档复现解决方案

详细标准见：[references/black_box_principle.md](references/black_box_principle.md)

## 使用场景

- 完成了复杂的 Bug 修复，需要记录排查过程
- 实现了有技术难度的功能，需要记录决策路径
- 经历了多次试错才找到答案，需要记录"此路不通"
- 需要对基础笔记进行深度扩展

## 图片重命名功能

### 功能说明

在生成过程文档时，**自动对图片文件进行规范化重命名**，遵循"线性排序 + 中文语义"的命名标准：

**命名格式**：`序号-关键对象-状态动作.扩展名`

**示例**：
- `01-网络-Ping不通.png` - Before状态（问题现象）
- `02-Clash-进程运行中.webp` - Process状态（执行中）
- `03-配置-环境变量.png` - Process状态（配置中）
- `04-网络-验证成功.png` - After状态（成功结果）

**核心价值**：
- 📂 **便于检索**：使用系统搜索（Everything/Spotlight）快速定位图片
- ⏱️ **时间线排序**：序号保证图片按文档顺序排列，还原案发现场
- 🧠 **语义化**：两个月后看文件名就知道图片内容，无需打开查看

### 工作原理

1. **智能扫描**：识别markdown中所有 `![[image.png]]` 格式的图片引用
2. **语义提取**：AI分析图片周围的上下文（前后3-5行），提取关键对象和状态动作
3. **规范重命名**：将随机命名（如 `PixPin_2026-02-07_09-55-45.webp`）重命名为规范格式
4. **引用同步**：自动更新markdown中的图片引用，保持文档完整性

### 智能跳过规则

已经符合规范的图片文件名会被**自动跳过**，避免重复处理：
- 匹配格式：`^\d{2}-[\u4e00-\u9fa5]+-[\u4e00-\u9fa5]+\.\w+$`
- 示例：`01-网络-Ping不通.png`（已规范，跳过）
- 示例：`image123.png`（未规范，需处理）

### 用户控制

**默认行为**：自动启用图片重命名功能

**禁用方式**：在调用技能时指定参数（未来支持）：
```
skip_rename=true
```

### 命名规范详解

详细的命名规范、语义提取指南、示例和反例见：
[图片命名规范](references/image_naming_convention.md)

## 工作流程

### 第一步：选择模板复杂度

根据内容复杂度选择：

**轻量版**（适合 80% 场景）：
- 适用于：单次操作、流程记录、配置笔记
- 结构：问题 + 解决方案 + 关键步骤 + 避坑指南
- 特点：5-10 分钟完成，不强求深度思考

**完整版**（适合复杂问题）：
- 适用于：复杂 Bug、架构决策、多次试错
- 结构：问题 + 解决方案 + 过程 + 思考 + 原始记录
- 特点：详细记录决策上下文和认知升级

**判断标准**：
- 1-2 次操作 → 轻量版
- 3 次以上真实试错 → 完整版
- 不确定时 → 优先轻量版

### 第二步：确定文档生成方式

**重要原则**：⚠️ **始终生成新文档，绝不修改原文档内容**

**文档命名规则**：
- 基于现有笔记扩展：`{原文件名}-详细过程文档.md`
- 从对话直接生成：`{日期}-{任务名称}-过程文档.md`

**文档存放位置**：
- 默认与原文档同目录（模式 A）
- 用户指定路径（模式 B）

### 第三步：执行生成

**模式 A：基于现有笔记扩展**
1. 读取现有笔记内容（仅读取，不修改）
2. 识别是否有真实的试错过程
3. 根据复杂度选择模板
4. **【新增】执行图片重命名**：
   - 扫描markdown中的所有图片引用（`![[image.png]]` 格式）
   - AI分析每张图片的上下文，提取关键对象和状态动作
   - 按文档顺序生成序号（01, 02, 03...）
   - 重命名图片文件为规范格式（`序号-对象-动作.扩展名`）
   - 自动更新markdown中的图片引用
   - 智能跳过已规范化的图片
5. **创建新文档**，在 Problem + Solution 基础上补充详细过程
6. 保留所有截图引用和代码块（引用已更新为新文件名）
7. 原文档保持不变

**模式 B：从对话直接生成**
1. 回溯对话历史
2. 提取所有关键信息（包括截图、日志、代码）
3. 根据实际复杂度选择模板
4. **【新增】执行图片重命名**（同模式A）：
   - 扫描提取的图片引用
   - AI分析上下文提取语义
   - 规范化重命名图片文件
   - 更新文档中的图片引用
5. **创建新文档**并保留所有原始素材

## 输出格式

### 轻量版结构

```markdown
# {日期}-{任务名称}

## 问题
[简要描述背景和问题]

## 解决方案
[核心答案 + 关键代码/配置]

## 关键步骤
1. [具体操作步骤]
2. [保留所有截图和日志]

## 避坑指南
- 坑点：[为什么会错]
- 原因：[底层原因]
- 避坑：[以后怎么避开]

## 原始记录（可选）
[保留原始对话片段、完整日志输出]
```

### 完整版结构

1. **问题**：背景、问题描述、关键信息
2. **解决方案**：最终生效的方案 + 代码
3. **过程**：真实的试错路径（如果有）
4. **思考**：坑点、洞察、认知升级（如果有）
5. **原始记录**：截图、日志、关键对话片段

完整模板见：
- [轻量版模板](references/lightweight_template.md)
- [完整版模板](references/complete_template.md)

## 关键要求

### 文档生成原则

⚠️ **重要**：
- ✅ **始终创建新文档**，文件名格式：`{原文件名}-详细过程文档.md` 或 `{日期}-{任务名称}-过程文档.md`
- ✅ **绝不修改原文档**，保持原文档完整性
- ✅ 新文档默认与原文档同目录，除非用户指定其他路径

### 必须保留

**视觉元素**：
- 所有截图：`![[image.png]]` 一个都不能丢
- 所有图表：流程图、架构图、示意图
- 操作界面：安装界面、配置界面、错误提示框

**文本记录**：
- 完整报错堆栈（未来搜索的"指纹"）
- 完整日志输出（成功项、失败项）
- 具体命令和参数（完整可执行）
- 配置文件位置（路径、文件名、配置项）
- 环境参数（版本号、OS、依赖库）
- 原始对话片段（关键问答、分析过程）

### 严禁操作

**真实性原则**：
- ❌ 虚构不存在的"试错过程"
- ❌ 删除或简化截图、日志
- ❌ 添加原文没有的"认知升级"
- ❌ 用总结性语言替代具体操作

**保持真实**：
- ✅ 有多少材料写多少
- ✅ 一次操作就记录一次
- ✅ 没有就留空，不强求完整

详细记录标准和检查清单见：[references/black_box_principle.md](references/black_box_principle.md)

## 与其他技能协作

**上游**：`conversation-extractor` 生成基础笔记（Problem + Solution）

**下游**：`qa-appender` 在过程文档上追加问答

## 参考资料

- [轻量版模板](references/lightweight_template.md)（推荐优先使用）
- [完整版模板](references/complete_template.md)
- [黑匣子原则](references/black_box_principle.md)
- [图片命名规范](references/image_naming_convention.md)（图片重命名功能详解）