过程文档生成器 (Process Documentation)

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

核心原则

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

详细标准见：references/black_box_principle.md

使用场景

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

工作流程

第一步：选择模板复杂度

根据内容复杂度选择：

轻量版（适合 80% 场景）：

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

完整版（适合复杂问题）：

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

判断标准：

• 1-2 次操作 → 轻量版
• 3 次以上真实试错 → 完整版
• 不确定时 → 优先轻量版

第二步：执行生成

模式 A：基于现有笔记扩展

1. 读取现有笔记内容
2. 识别是否有真实的试错过程
3. 根据复杂度选择模板
4. 在 Problem + Solution 基础上补充细节
5. 保留所有截图引用和代码块

模式 B：从对话直接生成

1. 回溯对话历史
2. 提取所有关键信息（包括截图、日志、代码）
3. 根据实际复杂度选择模板
4. 生成文档并保留所有原始素材

输出格式

轻量版结构

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

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

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

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

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

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

完整版结构

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

完整模板见：

• 轻量版模板
• 完整版模板

关键要求

必须保留

视觉元素：

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

文本记录：

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

严禁操作

真实性原则：

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

保持真实：

• ✅ 有多少材料写多少
• ✅ 一次操作就记录一次
• ✅ 没有就留空，不强求完整

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

与其他技能协作

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

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

参考资料

• 轻量版模板（推荐优先使用）
• 完整版模板
• 黑匣子原则