过程文档生成器 (Process Documentation)
职责：生成可复现的过程文档，保留完整的上下文、决策路径和试错过程，确保两个月后能完整复现解决方案。
核心原则
- 保真优先：保留所有截图、日志、代码块，禁止简化或虚构内容
- 真实性 > 结构性：有多少材料写多少，不强求模板完整
- 黑匣子测试：两个月后断网失忆，能否仅凭文档复现解决方案
详细标准见：references/black_box_principle.md
使用场景
- 完成了复杂的 Bug 修复，需要记录排查过程
- 实现了有技术难度的功能，需要记录决策路径
- 经历了多次试错才找到答案，需要记录"此路不通"
- 需要对基础笔记进行深度扩展
工作流程
第一步：选择模板复杂度
根据内容复杂度选择：
轻量版（适合 80% 场景）：
- 适用于：单次操作、流程记录、配置笔记
- 结构：问题 + 解决方案 + 关键步骤 + 避坑指南
- 特点：5-10 分钟完成，不强求深度思考
完整版（适合复杂问题）：
- 适用于：复杂 Bug、架构决策、多次试错
- 结构：问题 + 解决方案 + 过程 + 思考 + 原始记录
- 特点：详细记录决策上下文和认知升级
判断标准：
- 1-2 次操作 → 轻量版
- 3 次以上真实试错 → 完整版
- 不确定时 → 优先轻量版
第二步：确定文档生成方式
重要原则：⚠️ 始终生成新文档，绝不修改原文档内容
文档命名规则：
- 基于现有笔记扩展：
{原文件名}-详细过程文档.md - 从对话直接生成：
{日期}-{任务名称}-过程文档.md
文档存放位置：
- 默认与原文档同目录（模式 A）
- 用户指定路径（模式 B）
第三步：执行生成
模式 A：基于现有笔记扩展
- 读取现有笔记内容（仅读取，不修改）
- 识别是否有真实的试错过程
- 根据复杂度选择模板
- 【新增】执行图片重命名：
- 扫描markdown中的所有图片引用（
![[image.png]]格式） - AI分析每张图片的上下文，提取关键对象和状态动作
- 按文档顺序生成序号（01, 02, 03...）
- 重命名图片文件为规范格式（
序号-对象-动作.扩展名） - 自动更新markdown中的图片引用
- 智能跳过已规范化的图片
- 扫描markdown中的所有图片引用（
- 创建新文档，在 Problem + Solution 基础上补充详细过程
- 保留所有截图引用和代码块（引用已更新为新文件名）
- 原文档保持不变
模式 B：从对话直接生成
- 回溯对话历史
- 提取所有关键信息（包括截图、日志、代码）
- 根据实际复杂度选择模板
- 【新增】执行图片重命名（同模式A）：
- 扫描提取的图片引用
- AI分析上下文提取语义
- 规范化重命名图片文件
- 更新文档中的图片引用
- 创建新文档并保留所有原始素材
输出格式
轻量版结构
# {日期}-{任务名称}
## 问题
[简要描述背景和问题]
## 解决方案
[核心答案 + 关键代码/配置]
## 关键步骤
1. [具体操作步骤]
2. [保留所有截图和日志]
## 避坑指南
- 坑点：[为什么会错]
- 原因：[底层原因]
- 避坑：[以后怎么避开]
## 原始记录（可选）
[保留原始对话片段、完整日志输出]
完整版结构
- 问题：背景、问题描述、关键信息
- 解决方案：最终生效的方案 + 代码
- 过程：真实的试错路径（如果有）
- 思考：坑点、洞察、认知升级（如果有）
- 原始记录：截图、日志、关键对话片段
完整模板见：
关键要求
文档生成原则
⚠️ 重要：
- ✅ 始终创建新文档，文件名格式：
{原文件名}-详细过程文档.md或{日期}-{任务名称}-过程文档.md - ✅ 绝不修改原文档，保持原文档完整性
- ✅ 新文档默认与原文档同目录，除非用户指定其他路径
必须保留
视觉元素：
- 所有截图：
![[image.png]]一个都不能丢 - 所有图表：流程图、架构图、示意图
- 操作界面：安装界面、配置界面、错误提示框
文本记录：
- 完整报错堆栈（未来搜索的"指纹"）
- 完整日志输出（成功项、失败项）
- 具体命令和参数（完整可执行）
- 配置文件位置（路径、文件名、配置项）
- 环境参数（版本号、OS、依赖库）
- 原始对话片段（关键问答、分析过程）
严禁操作
真实性原则：
- ❌ 虚构不存在的"试错过程"
- ❌ 删除或简化截图、日志
- ❌ 添加原文没有的"认知升级"
- ❌ 用总结性语言替代具体操作
保持真实：
- ✅ 有多少材料写多少
- ✅ 一次操作就记录一次
- ✅ 没有就留空，不强求完整
详细记录标准和检查清单见：references/black_box_principle.md
与其他技能协作
上游：conversation-extractor 生成基础笔记（Problem + Solution）
下游：qa-appender 在过程文档上追加问答