复盘 — 协作知识沉淀与深度诊断

使用建议

在会话收尾时复盘，不要在中途插入。 中途复盘的问题：工作未收敛导致判断被推翻、全量重新生成浪费 token、知识调研的 subagent 是最重的环节重跑成本最高。最佳节奏：一个会话的工作做完 → 复盘一次 → 结束。同会话迭代机制仅作为兜底方案保留。

绝对不要在 /compact 之后复盘。 /compact 会将原始对话压缩为 LLM 摘要，用户的原始 prompt 文本、具体的消息序列、完整的工具调用结果都会丢失。而复盘的表达复盘（逐条分析用户表达）和行为模式检测（扫描行为序列）都依赖原始对话，二手摘要无法支撑。正确顺序：功能开发 → 复盘（在原始对话中）→ compact 或新开会话 → 下一个功能。

长会话的 token 管理：Claude Code 无状态，每轮重发全部历史，长会话 input tokens 会二次方增长。建议：单次功能完成后 /compact；隔夜/隔天继续时新开会话；超过 200 条消息无论如何都该压缩或新开。但压缩前务必先完成复盘。

---

输出位置

统一保存到 ~/claudecode_workspace/记录/复盘/{项目名}/ 目录：

• 项目名由 AI 根据当前项目判断（如 info2action、skill-system、视频转文本），用户可覆盖
• 文件名格式：{YYYY-MM-DD}-{HHMM}-[任务标签]-{主题关键词}.md
  • 日期在最前，后跟 24 小时制时分（取复盘文档创建时的当前时间），便于按时间排序
  • 任务标签应与具体功能点/任务挂钩，示例：[调整前端布局]、[视频转文本工具]、[安全加固]
• 示例路径：~/claudecode_workspace/记录/复盘/info2action/2026-04-06-1430-[多数据源聚合]-RSS-HN-Reddit-GitHub信息源扩展.md

---

前置脚本（每次先运行）

_ROOT=$(git rev-parse --show-toplevel 2>/dev/null || pwd)
_BRANCH=$(git branch --show-current 2>/dev/null || echo "unknown")
echo "当前分支: $_BRANCH"
echo "项目根目录: $_ROOT"

# === Git 卫生检查 ===
git fetch --quiet 2>/dev/null
_AHEAD=$(git rev-list @{u}..HEAD --count 2>/dev/null || echo "?")
_BEHIND=$(git rev-list HEAD..@{u} --count 2>/dev/null || echo "?")
echo "远程同步: 领先 $_AHEAD / 落后 $_BEHIND"
if [ "$_BEHIND" != "?" ] && [ "$_BEHIND" -gt 0 ]; then
  echo "⚠️ 落后远程 $_BEHIND 个提交，自动 rebase..."
  _HAS_CHANGES=$(git status --porcelain 2>/dev/null | head -1)
  [ -n "$_HAS_CHANGES" ] && git stash --quiet 2>/dev/null && _STASHED=1 || _STASHED=0
  git pull --rebase --quiet 2>/dev/null && echo "✅ 已同步远程" || echo "❌ rebase 失败，请手动处理"
  [ "$_STASHED" = "1" ] && git stash pop --quiet 2>/dev/null
fi
_DIRTY=$(git status --porcelain 2>/dev/null | head -5)
[ -n "$_DIRTY" ] && echo "⚠️ 工作区有未提交改动"

# === 项目上下文收集 ===
_RECENT_COMMITS=$(git log --oneline -20 2>/dev/null)
_DIFF_STAT=$(git diff --stat HEAD~10..HEAD 2>/dev/null)
_PROJECT_DOCS=$(ls docs/*.md 2>/dev/null)
echo "--- 最近提交 ---"
echo "$_RECENT_COMMITS"
echo "--- 变更统计 ---"
echo "$_DIFF_STAT"
echo "--- 项目文档 ---"
echo "$_PROJECT_DOCS"

# === Token 统计 ===
# 定位当前会话 JSONL 并解析 token 消耗
_CLAUDE_PROJECT_DIR="$HOME/.claude/projects"
_PARSE_TOKENS=$(find ~/claudecode_workspace -path '*/forge-fupan/parse_tokens.py' -type f 2>/dev/null | head -1)
if [ -d "$_CLAUDE_PROJECT_DIR" ]; then
  _JSONL_FILE=$(find "$_CLAUDE_PROJECT_DIR" -name "*.jsonl" -type f -print0 2>/dev/null | xargs -0 ls -t 2>/dev/null | head -1)
  if [ -n "$_JSONL_FILE" ]; then
    echo "--- Token 统计 ---"
    echo "会话日志: $_JSONL_FILE"
    if [ -n "$_PARSE_TOKENS" ]; then
      python3 "$_PARSE_TOKENS" "$_JSONL_FILE" 2>/dev/null || echo "⚠️ Token 解析失败，将使用轮次估算"
    else
      echo "⚠️ parse_tokens.py 未找到，将使用轮次估算"
    fi
  fi
fi

# === 同会话迭代检测 ===
_FUPAN_DIR="$HOME/claudecode_workspace/记录/复盘"
if [ -n "$_JSONL_FILE" ]; then
  _SESSION_ID=$(basename "$_JSONL_FILE")
  _EXISTING_FUPAN=$(grep -rl "session: $_SESSION_ID" "$_FUPAN_DIR" 2>/dev/null | head -1)
  if [ -n "$_EXISTING_FUPAN" ]; then
    echo "⚠️ 检测到同会话已有复盘: $_EXISTING_FUPAN"
    echo "将迭代更新该文档，而非新建"
  fi
fi

---

文档结构

复盘文档以 frontmatter 开头，包含会话标记：

---
session: {JSONL文件名}
iteration: {迭代次数，首次为1}
created: {首次创建时间}
updated: {最后更新时间}
---

随后先写 TLDR，再写导航目录和 7 个章节，信息密度从高到低排列。

---

TLDR（必须位于文档最上方）

TLDR 放在 frontmatter 之后、导航目录之前。它是给用户快速学习用的记忆卡，不是普通摘要。

## TLDR

- **关键词**：{本次最值得记住的 3-6 个术语 / 工具 / 判断标准}
- **表达方法**：下次可以说：{一条可直接复制的高质量指令}
- **关键知识**：{这次真正学到的原理、机制或工作流}
- **关键决策**：{本次最重要的取舍，以及为什么}
- **避坑提醒**：{下次最容易重犯的误区或检查点}
- **下次行动**：{一条最小、具体、可执行的后续动作}

硬性规则：

• TLDR 必须是分点陈述，6-10 条为宜；不得写成长段落。
• 每条都必须来自本次复盘正文中的证据、知识拓展或决策复盘，不得凭空发明。
• 至少包含 1 条 表达方法，格式必须出现“下次可以说：...”。
• 至少包含 1 条 关键知识，用人话讲清楚，不只堆专业名词。
• 至少包含 1 条 避坑提醒 或 下次行动，方便用户立刻迁移到下一次协作。
• 如果某类内容本次不明显，可以省略该类，但 TLDR 总条数不得少于 5 条。

---

导航目录

## 目录

- [TLDR](#tldr)
- [仪表盘速览](#仪表盘速览)
- [一、会话脉络](#一会话脉络)
- [二、表达复盘](#二表达复盘)
- [三、知识拓展](#三知识拓展)
- [四、决策复盘](#四决策复盘)
- [五、AI 表现复盘](#五ai-表现复盘)
- [六、速查手册](#六速查手册)
- [七、下次行动清单](#七下次行动清单)

---

仪表盘速览

放在导航目录之后、第一章之前。用 show-widget 生成，截图保存为 PNG 插入文档。

仪表盘必须包含以下区块：

1. 标题栏：复盘主题 + 日期 + 迭代次数（如有）
2. 精力分布：进度条可视化各阶段占比
3. 表达复盘摘要：按学习优先级分组，每条给出简要描述
   • 🔴 ×N 待补背景：逐条列出具体哪个领域需要补背景
   • 🟡 ×N 概念模糊：逐条列出具体哪个概念模糊
   • 🟢 ×N 表达可优化：逐条列出具体哪个表达可以更直接
4. 行为模式警示：每个模式一行描述（名称 + 一句话概括）
5. AI 表现：四维度评分 + 颜色标记
6. 知识拓展领域：列出本次覆盖的知识领域
7. 核心收获：top 3 最有价值的实践，一行一条

仪表盘设计原则：信息密度高，一屏看完核心内容。 看完仪表盘就知道这次复盘的全貌，再决定深入哪个章节。

---

一、会话脉络

用精力/Token 分布展示整个会话的工作过程。

精力分布（基于 output tokens 统计）

进度条 + 表格结合，每个阶段显示 input/output token 绝对值：

██████████░░░░░░░░░░ 方案探索与验证   ~48%  1.3M/23k  ← 5种方案对比，3种失败
████████░░░░░░░░░░░░ OCR管线搭建      ~35%  980k/18k  ← SDK失败→httpx切换+去重调参
███░░░░░░░░░░░░░░░░░ 合并与图片提取   ~12%  350k/6k
█░░░░░░░░░░░░░░░░░░░ 收尾              ~5%  140k/3k

阶段	占比	in/out	关键事件	⚠️ 问题点
方案探索	~48%	1.3M/23k	5种方案对比，CV方案全部失败	我没说清"手机拍屏幕"这个前提 → #P1
OCR管线	~35%	980k/18k	SDK→httpx切换，三层去重	"做个去重"没说清是哪层 → #P3
...	...	...	...	...

in/out 格式说明：1.3M/23k 表示 effective input 1.3M tokens / output 23k tokens。 effective input = cache_read + cache_create（真实输入侧消耗，raw input_tokens 是流式占位符不可用）。

工作叙事

按阶段展开，每个阶段标注关键转折和问题点：

阶段 1：方案探索（~48%）
  → 尝试纯 CV 方案检测全屏图 → 失败（手机拍屏幕像素特征太相似）
  → 🔀 转向 LLM 语义判断
  → ⚠️ 我在描述需求时完全没提到"手机拍屏幕"这个关键前提 [→ #P1]

阶段 2：OCR管线搭建（~35%）
  → openai SDK 解析失败 → 🔀 切换到 httpx 直调
  → 加入 SSIM 去重，阈值从 0.7 调到 0.9
  → ⚠️ "做个去重"没指定是图像级还是文本级 [→ #P3]
  ...

🔀 = 方向性转折，⚠️ = 沟通/表达/行为问题点（引用到第二章具体条目）。

同会话迭代时：在进度条中加入复盘分界线：

██████░░░░░░░░░░░░░░ 方案探索        ~30%
████░░░░░░░░░░░░░░░░ OCR管线         ~22%
██░░░░░░░░░░░░░░░░░░ 合并提取         ~8%
█░░░░░░░░░░░░░░░░░░░ 第一次复盘       ~3%
                      ─── 复盘分界线 ───
████░░░░░░░░░░░░░░░░ Bug修复+迭代    ~25%
██░░░░░░░░░░░░░░░░░░ 验证收尾        ~12%

Token 统计方法：

• 使用 parse_tokens.py 解析当前会话的 JSONL 日志
• effective input = cache_read + cache_create（raw input_tokens 是流式占位符，全部为 0/1，不可用）
• output tokens 经 message.id 去重后可信
• 每个阶段显示 in/out 绝对值（如 1.3M/23k）+ 占比百分比
• 用 ~ 前缀标注占比为估算值（因为阶段边界由 AI 人工划分）
• 如果 token 解析失败，降级为基于对话轮次数 + 工具调用数的粗估

---

二、表达复盘

本章是整篇复盘的信息入口。 目标：把本次会话里“我当时怎么说、其实想解决什么、下次可以怎么说”讲清楚。语气必须像老师帮用户补课，不像批改作业。

2.1 逐条 Prompt 分析

不设数量限制，有问题的全部挑出来。按严重度分级标注：

• 🔴 待补背景：用户描述了一个需求，但该领域的核心术语/概念没有出现。说明这里适合先补背景。重点展开对象，每条必须关联到第三章知识拓展的对应领域。
• 🟡 概念模糊：用户用了一些词但不精确，AI 需要猜测用户的意思。
• 🟢 表达可优化：用户知道要什么，但说法还可以更直接。

每条分析的格式：

<a id="p3"></a>
#### 🔴 #P3: "把去重做一下"

- **问题**：没指定是哪一层去重（图像/文本/合并阶段），没给判断标准
- **AI 做了什么**：只在合并阶段加了 prompt 级去重
- **实际需要的**：在 OCR 阶段加文本行级去重 + SSIM 图像级去重 + 合并 prompt 去重，三层递进
- **更好的说法**："在 OCR 阶段加文本行级去重，规则是：如果某行文本在上一帧的 OCR 结果中已存在则跳过。同时保留现有的 SSIM 图像去重和合并阶段的 prompt 去重"
- **学习线索**：🏷️ 待补背景 — 不了解视频处理管线中去重是分层策略
- **关联知识拓展**：[→ §三-领域1「视频内容理解」](#领域-1视频内容理解)
- **增加的沟通成本**：约 3 轮

2.2 模式诊断

不看单条 prompt，看整个对话的沟通、思维和行为模式。分三个独立维度：

a) 表达模式

分析用户的沟通习惯中有哪些结构性问题：

• 碎片化描述 vs 一次给完整需求
• 描述现象但从不描述期望的目标状态
• 使用模糊代词而非具体指称
• ...

b) 思考模式

分析用户的思维方式中有哪些缺口：

• 把多层问题当成单点操作（缺乏系统思维）
• 没有意识到前后端/多模块可能冲突（缺乏全链路思维）
• 直觉驱动而非假设驱动（缺乏实验思维）
• ...

c) 行为模式

分析用户的工作流程中有哪些低效模式。每个行为模式必须独立完成深度分析，由 subagent 执行（见 Phase 2），输出格式统一：

#### 行为模式 B1：碎片修复循环

1. **表现**：fix bug → QA → 发现新bug → fix → QA... 循环了4轮
2. **频率**：本次会话中出现 3 次，贯穿第二阶段始终
3. **根因**：急于看到"绿灯"的心理驱动，没有先建立全局视图
4. **影响**：浪费约 8 轮对话，每次 QA 都是全量运行但只验证一个修复
5. **正确做法**：先跑一次完整 QA 收集所有问题 → 分类分优先级 → 批量修复 → 再跑 QA 验证
6. **触发检查点**：当你准备说"帮我测一下这个改动"时，停下来问自己——"我是在修完所有已知问题后测试，还是刚改了一个就急着测？"
7. **关联**：与 B2「过早进入实现」相关——急于修复是因为跳过了问题全景扫描

---

三、知识拓展

核心目标：以本次实践为锚点，按用户在 Workbench 里选择的学习深度补齐知识。不只记录「本次用了什么」，而是系统性地展示「这个领域你还应该知道什么」。

每个知识领域标注来源 Prompt：

### 领域 1：视频内容理解与帧处理 [来自 #P1, #P3, #P7]

每个领域分两部分：

Part A：本次实践总结（精简版）

3-5 条核心收获，一行一条：

1. LLM 做语义判断 + CV 做像素操作 = 正确的职责分配
2. 多层去重 > 单层去重（SSIM → 文本行 → prompt）
3. 先 3 帧测试 API 再跑全量，避免 242 帧浪费

Part B：领域知识拓展

由 subagent 并行调研（见 Phase 2）。每个领域必须通过 web search 回答以下 6 个问题：

Q1. 标准术语（命名锚定）

这个问题在业界的标准术语叫什么？搜索该术语的权威定义。 输出：术语名 + 一句话定义 + "下次可以说：xxx"

Q2. 方案光谱（主流解决方案全景）

主流的解决方案有哪几类？各自适用什么场景？ 输出：方案列表，每个方案附适用场景和局限性

Q3. 工具箱（常用工具/库/服务）

目前最常用的工具/库/服务是哪些？ 输出：工具名 + 一句话定位 + 适用场景 + 是否活跃维护 → "下次可以说：用 {工具名} 做 {场景}"

Q4. 80% 核心知识（帕累托边界）

这个领域的从业者默认知道的核心知识点有哪些？ 输出：知识点列表，每个用 2-3 句话讲清楚

Q5. 常见反模式（避坑边界）

常见的错误做法有哪些？ 输出：反模式名 + 为什么是错的 + 正确做法

Q6. 学习路径（深入资源）

如果要深入学习，最值得看的 2-3 个资源是什么？ 输出：资源名（含链接）+ 看什么部分 + 解决什么问题 资源必须权威：官方文档、知名作者博客、高赞社区讨论，禁止低质量转载

每个知识点以「下次可以说：xxx」结尾，给用户可直接使用的 prompt 关键词。

---

四、决策复盘

只记录有权衡取舍的关键决策。不是每个决策都需要记录——只记录踩了坑的、有明确权衡的、或暴露认知问题的。

每个决策的格式：

#### 决策 1：放弃 openai SDK，改用 httpx 直调

- **触发**：SDK 解析 sub2api 返回格式失败
- **权衡**：SDK 便利性 vs 兼容性
- **结论**：非官方 API 都用 httpx，官方 API 用 SDK
- **反思**：应该在第一帧就测试 SDK 兼容性，而不是跑了 10 帧才发现

---

五、AI 表现复盘

评分总览

维度	评级	说明
需求理解准确度	🟢/🟡/🔴	一句话
自主决策质量	🟢/🟡/🔴	一句话
迭代效率	🟢/🟡/🔴	一句话
输出完整度	🟢/🟡/🔴	一句话

具体问题

每个问题用以下结构：

• 问题标题
  • 表现：发生了什么
  • 根因：AI 侧的具体失误（误解/遗漏/过度/低效）
  • 增加的沟通成本：N 轮
  • 应有做法：AI 当时应该怎么做

评级标准

全文档统一：

• 🔴 = 同一问题返工 ≥3 轮，或方向性错误
• 🟡 = 需要 1-2 轮修正，或有遗漏但不影响交付
• 🟢 = 一次到位或决策合理

---

六、速查手册

备查区，需要时来翻。合并概念速查表、避坑指南、效率词典为统一的备查区。

概念速查表

按知识领域分组：

概念	一句话解释	什么时候用	下次告诉 AI 的关键词

避坑指南

坑	触发条件	解决方案

效率词典

中文	英文	一句话解释	场景	下次怎么说

---

七、下次行动清单

不给通用建议，只给具体到可以直接执行的行动项。至少 3 条。

□ 下次描述去重需求时，明确指定在哪个环节做（采样/图像/文本/语义）
□ 涉及第三方 API 时，第一步永远是"用 1 条数据测通 API"
□ 了解 PySceneDetect 的基本用法，下次视频处理项目备用
□ 准备说"帮我测一下"之前，先问自己：已知问题是否全部修完？

---

执行流程

Phase 0：环境准备

运行前置脚本，完成：

1. Git 卫生检查 + 项目上下文收集
2. Token 统计（parse_tokens.py 解析 JSONL）
3. 同会话迭代检测
4. 读取 MEMORY.md 和 WORKSPACE-PULSE.json

Phase 1：对话分析（主 agent 串行）

回溯完整对话，串行完成以下分析：

1. 提取会话脉络：

   • 将对话按工作阶段分段
   • 标注每个阶段的关键转折（🔀）和问题点（⚠️）
   • 结合 parse_tokens.py 的输出，计算各阶段 token 占比

2. 逐条 Prompt 分析：

   • 扫描用户的每一条消息
   • 标注有问题的 prompt（🔴/🟡/🟢），不设数量限制
   • 重点标注 🔴 待补背景：核心术语一个都没出现的 prompt

3. 识别行为模式：

   • 扫描对话中的行为序列（如 fix→QA→fix 循环）
   • 提取所有疑似低效行为模式，列出清单
   • 为每个模式准备对话证据（具体轮次和用户原文）

4. 识别知识领域：

   • 从 🔴 级 Prompt 和工作内容中提取需要调研的知识领域
   • 为每个领域准备调研上下文（用户背景、已有认知、知识缺口）

5. 识别关键决策：

   • 提取有权衡取舍的关键决策点
   • 区分用户决策 vs AI 决策

6. AI 表现评估：

   • 评估四维度评分
   • 记录具体问题

Phase 1.5：学习地图确认（Workbench 优先）

Phase 1 完成后，不要直接进入 Phase 2 调研。先把你推测的学习内容交给用户确认。目标是让用户选择“学什么、学多少”，避免生成一篇专业但读不下去的复盘。

1. 生成学习地图 JSON

把 Phase 1 的分析整理为 /tmp/fupan-learning-map.json：

{
  "project": "{项目名}",
  "session": "{JSONL文件名}",
  "source_thread": "{可为空}",
  "active": true,
  "summary": "本次复盘背景，用人话概括",
  "user_questions": [
    "用户原话摘录 1",
    "用户原话摘录 2"
  ],
  "expression_issue_quotes": [
    {
      "quote": "用户表达有问题的原话，必须逐字摘录",
      "issue": "这句话为什么会增加歧义或沟通成本",
      "suggestion": "下次可以怎么说"
    }
  ],
  "topics": [
    {
      "id": "react",
      "title": "React",
      "plain_explanation": "用来搭网页界面的前端框架。",
      "why_relevant": "本次设计了 React + Vite 的本地页面。",
      "recommended_depth": "表达",
      "selected": true,
      "depth": "表达"
    }
  ]
}

Topic 规则：

• 数量由用户最终选择，AI 只提出候选。
• 每个 topic 必须有 plain_explanation，不能只写专业名词。
• recommended_depth 只能是 了解 / 表达 / 复现。
• 推荐深度只是建议，不代表替用户做决定。

表达原话规则：

• expression_issue_quotes 由 LLM 自行分析本次原始会话，不要求用户手动指出。
• 只摘录真实出现过的用户原话，不能改写、概括或美化。
• 只要用户表达导致目标、范围、验收标准、技术关键词、优先级或约束不清，就必须收入。
• 如果确实没有表达问题，写空数组 []。
• issue 和 suggestion 要服务学习：告诉用户为什么这句话不够清楚，以及下次可以怎么说。

2. 创建 task 并启动 Workbench

_WB="skills/forge-fupan/workbench/launcher.py"
_TASK_JSON="/tmp/fupan-learning-map.json"
_TASK=$(python3 "$_WB" create-task --input "$_TASK_JSON")
_TASK_ID=$(python3 -c 'import json,sys; print(json.load(sys.stdin)["id"])' <<< "$_TASK")
python3 "$_WB" start --task-id "$_TASK_ID" --open

启动成功后，在对话里只提示一句：

我已经打开 Fupan Workbench，请去页面确认这次想学习的知识区和深度；提交后我会自动继续。

不要要求用户回命令行输入“好了”。

3. 等待当前 task 提交

python3 "$_WB" wait --task-id "$_TASK_ID" --timeout 1800

硬性规则：

• 只轮询当前 _TASK_ID。
• 不得读取或消费其他会话创建的 task。
• 30 分钟未提交则停止等待，告诉用户页面仍可提交，下次可继续读取。
• 如果 workbench 启动失败、FastAPI/Uvicorn 缺失或浏览器无法打开，降级到对话内确认。

4. 对话内降级格式

只有在 Workbench 不可用时使用：

Workbench 暂时没启动成功，我先用对话内确认兜底。

我推测这次可以学：
1. React — 人话解释：... — 推荐：表达
2. FastAPI — 人话解释：... — 推荐：了解

请告诉我：
- 要学哪些编号
- 每个编号学到：了解 / 表达 / 复现
- 还有没有补充反馈

5. 后续写作约束

• Phase 2 只深度调研用户选择的 topic。
• 未选择 topic 不得长篇展开，只能在附录“未展开候选”里一行带过。
• 了解 输出：人话解释 + 本次为什么出现 + 暂时不用深入学什么。
• 表达 输出：关键词表 + 下次可以怎么说 + 常见误区。
• 复现 输出：原理拆解 + 最小可复现实例 + 检查清单 + 练习方向。

Phase 2：并行调研

Phase 1.5 完成后，为用户选择的每个知识领域和每个行为模式启动 subagent，全部并行。

知识调研 Subagent（每个知识领域一个）

Prompt 模板：

你正在为一次协作复盘做知识调研。

## 调研领域
{领域名称，如"视频内容理解与帧处理"}

## 项目背景
{本次项目做了什么，核心目标是什么}

## 用户背景
{用户的角色、技术水平、工作习惯}
{用户在本次会话中对该领域展现出的认知水平}
{用户用过的术语和没用到的术语}

## 用户的核心目标
通过复盘按用户选择的学习深度补齐该领域的关键背景。不只是知道"本次用了什么"，
还要知道"这个领域大家都怎么做、有哪些工具、有哪些坑"。

## 本次实践摘要
{用户在这个领域做了什么、用了什么方案、踩了什么坑}

## 用户需要补的背景
{具体列出哪些 Prompt 暴露了哪些知识缺口}

## 强制调研清单（每项必须通过 web search 验证，不凭记忆编造）

1. **标准术语**：这个问题在业界叫什么？搜索该术语的权威定义。
   输出格式：术语名 + 一句话定义 + "下次可以说：xxx"

2. **方案光谱**：主流解决方案有哪几类？各自适用场景？
   输出格式：方案列表，每个附适用场景和局限性

3. **工具箱**：最常用的工具/库/服务？
   输出格式：工具名 + 一句话定位 + 适用场景 + 是否活跃维护
   每个工具以"下次可以说：用 {工具名} 做 {场景}"结尾

4. **80% 核心知识**：这个领域从业者默认知道的核心知识点
   输出格式：知识点列表，每个 2-3 句话讲清楚

5. **常见反模式**：常见错误做法，搜索 "common mistakes in {领域}"
   输出格式：反模式名 + 为什么是错的 + 正确做法

6. **学习路径**：最值得看的 2-3 个资源
   输出格式：资源名（含链接）+ 看什么部分 + 解决什么问题
   资源必须权威：官方文档、知名作者博客、高赞社区讨论

## 约束
- 每项至少做一次 web search，不凭记忆编造
- 所有工具/库必须给出准确名称和当前维护状态
- 每个知识点以"下次可以说：xxx"结尾
- 控制篇幅：每项 3-8 条，不写百科全书
- 输出纯 markdown，不含代码块

行为模式分析 Subagent（每个模式一个）

Prompt 模板：

你正在分析一个用户的工作行为模式。

## 行为模式
{模式名称，如"碎片修复循环"}

## 对话中的证据
{主 agent 提取的具体对话片段，包括轮次编号和用户原文}

## 用户背景
{用户的角色、工作习惯、已知的偏好}

## 分析框架（全部 7 点必须完成，每点 2-5 句话，必须引用对话证据）

1. **表现**：用对话证据还原这个模式的完整过程
2. **频率**：本次会话中出现了几次？是偶发还是贯穿始终？
3. **根因**：为什么会形成这个行为模式？（心理驱动/认知缺口/习惯惯性）
4. **影响**：这个模式浪费了多少轮次/精力？如果不改会怎样？
5. **正确做法**：业界或高效协作者在同样场景下怎么做？
6. **触发检查点**：给用户一个具体的自检问题，在即将重蹈覆辙时能拦截自己
7. **关联**：这个模式是否和其他已识别的模式有关联？

## 约束
- 不要泛泛而谈，每个论点必须有对话证据支撑
- 触发检查点必须是一个具体的问句，而非笼统的建议
- 输出纯 markdown

Phase 3：组装文档（主 agent 串行）

收集所有 subagent 返回的结果，组装完整复盘文档：

1. 撰写文档：按 7 章结构组装，插入 subagent 的调研结果和分析结果
2. 提炼 TLDR：从表达复盘、知识拓展、决策复盘、速查手册和下次行动清单中提取最值得记住的内容，放到文档最上方
3. 建立锚点引用：表达复盘 ↔ 知识拓展双向引用
4. 保存文档：
   • 新文档：写入复盘目录
   • 迭代更新：覆写已有文档，更新 frontmatter 的 iteration 和 updated

文档内容 Checklist（全部 PASS 才能进入 Phase 4）

□ 每个知识领域的 6 问调研全部有内容（无空项）
□ 每个行为模式的 7 点分析全部有内容（无空项）
□ TLDR 位于 frontmatter 后、目录前，且至少 5 条
□ TLDR 至少包含 1 条“下次可以说：...”表达方法
□ TLDR 的关键词、知识、决策、避坑或行动均能在正文中找到支撑
□ 所有 🔴 级 Prompt 都有对应的知识拓展章节锚点
□ 导航目录的锚点跳转全部正确
□ 决策复盘至少包含 2 个关键决策（除非本次确实无权衡决策）
□ 下次行动清单至少 3 条且具体可执行
□ 速查手册中的概念表和避坑表不为空
□ frontmatter 中 session/iteration/created/updated 字段正确

如果某项 FAIL，必须修复后重新检查。

---

Phase 4：图表生成与验证（独立 Phase，不可跳过）

此 Phase 是独立的强制阶段。文档写完后必须立即执行图表生成，不能合并到其他步骤中，不能推迟，不能跳过。

本阶段默认使用 show-widget / HTML 截图生成结构化仪表盘。若本次复盘包含新的心智模型、复杂行为模式、设计/前端判断、或用户明确希望“可视化学习”，读取 ../_shared/visual-decision-layer.md，按需补充 Image 2 学习图。Image 2 图用于记忆和理解，不替代仪表盘，也不替代证据截图。

4.1 创建 assets 目录

mkdir -p ~/claudecode_workspace/记录/复盘/{项目名}/assets

4.2 生成仪表盘（强制）

1. 用 show-widget 生成仪表盘 HTML，必须包含全部 7 个区块：
   • 标题栏（主题 + 日期 + 迭代次数）
   • 精力分布（进度条）
   • 表达复盘摘要（按学习优先级分组，每条含具体描述）
   • 行为模式警示（名称 + 一句话概括）
   • AI 表现（四维度评分 + 颜色标记）
   • 知识拓展领域列表
   • 核心收获 top 3
2. 将 HTML 写入 /tmp/fupan_dashboard.html
3. 用 render_widget.js 截图：

   NODE_PATH=$(npm root -g 2>/dev/null || echo "/opt/homebrew/lib/node_modules") \
   node ~/claudecode_workspace/.claude/skills/render_widget.js \
   /tmp/fupan_dashboard.html \
   ~/claudecode_workspace/记录/复盘/{项目名}/assets/{日期}-{主题}_dashboard.png
   

4. 在复盘文档的「仪表盘速览」章节插入：![复盘仪表盘](assets/{日期}-{主题}_dashboard.png)

4.3 生成其他图表（按需）

如有需要（知识拓展中的方案对比图、决策流程图等），每张图表重复以下流程：

1. show-widget 生成 HTML
2. 写入 /tmp/fupan_chart_N.html
3. render_widget.js 截图保存 PNG 到 assets/
4. 文档中插入图片引用

4.3.1 Image 2 学习图（按需）

当 show-widget 只能表达结构、但用户更需要“看懂一个新心智模型”时，生成 1 张 Image 2 学习图：

• 行为模式图：把本次低效循环画成 before/after 工作流，不用批改感文案。
• 知识地图图：把 3-5 个关键知识领域画成一张学习地图，突出“下次可以怎么说”。
• 设计/前端判断图：把设计前置判断、真实截图和最终实现之间的关系画成一张决策路径图。

规则：

1. 先写清楚「这张学习图要帮助用户记住什么」。
2. 保存图片、prompt、meta 到复盘 assets/。
3. 在「仪表盘速览」之后或对应知识章节插入图片。
4. prompt 中不得使用真人人名，不得包含隐私、token、内部路径。
5. 如果没有可用生图能力，保存 prompt pack 并继续复盘，不阻塞 Phase 5。

4.4 强制验证（硬性拦截，不通过则禁止继续）

# 验证仪表盘 PNG 存在且非空
_DASHBOARD_PNG="$HOME/claudecode_workspace/记录/复盘/{项目名}/assets/{日期}-{主题}_dashboard.png"
if [ ! -s "$_DASHBOARD_PNG" ]; then
  echo "❌ 仪表盘 PNG 不存在或为空: $_DASHBOARD_PNG"
  echo "Phase 4 未通过，禁止进入 Phase 5。必须先生成仪表盘。"
  exit 1
fi
echo "✅ 仪表盘 PNG 已验证: $(ls -lh "$_DASHBOARD_PNG" | awk '{print $5}')"

如果仪表盘 PNG 不存在或为空文件，禁止执行 Phase 5 的 git commit。必须回到 4.2 重新生成。

---

Phase 5：回流与索引

0. 清理 .forge/active.md 本会话登记（v6.0 新增，forge-bugfix v6+ 产生的并行心跳文件）：

   _ROOT=$(git rev-parse --show-toplevel 2>/dev/null || pwd)
   ACTIVE="$_ROOT/.forge/active.md"
   
   if [ -f "$ACTIVE" ]; then
     # 获取当前 session id
     SID_SCRIPT=""
     for s in "$HOME/.claude/skills/forge-bugfix/scripts/get-session-id.sh" \
              "$HOME/.claude/skills/forge/skills/forge-bugfix/scripts/get-session-id.sh"; do
       [ -f "$s" ] && SID_SCRIPT="$s" && break
     done
     CURRENT_SID=$(bash "$SID_SCRIPT" 2>/dev/null || echo "")
   
     if [ -n "$CURRENT_SID" ]; then
       # 删除 active.md 里 session id 匹配当前会话的所有行（本会话可能登记了多个 bug）
       python3 -c "
   import pathlib
   p=pathlib.Path('$ACTIVE')
   txt=p.read_text()
   lines=txt.split('\n')
   sid='$CURRENT_SID'
   out=[l for l in lines if not (l.startswith('- session: ') and sid in l)]
   # 如果进行中会话区变空了，补回占位
   result='\n'.join(out)
   p.write_text(result)
   print(f'已清理 session {sid[:12]} 的 active 登记')
   "
     else
       echo "⚠️ 无法获取 session id，active.md 清理跳过，下次跑 /forge-status 兜底"
     fi
   fi
   

   硬性规则：

   • 只清当前会话自己的登记行（session id 匹配），不动别的会话
   • 无法获取 session id → 不清理 + 提示用户后续 /forge-status 兜底
   • 如果本会话有多个 bug 登记，一次全清（session id 一致）
   • 这一步在 Memory 回流之前执行，确保即使 Memory 写入失败 active 也已清理

1. Memory 回流：

   • 读取当前 MEMORY.md
   • 从复盘中提取跨会话有价值的内容：
     • Feedback：行为指令（"做X/不做Y" + 原因）
     • Project：项目状态更新
     • Reference：复盘文件索引
   • 写入规则：
     • 每条 Feedback 创建独立 .md 文件，在 MEMORY.md 加一行索引
     • 已有相同主题 → 更新而非新建
     • 只提取行为指令，不复制复盘全文
     • MEMORY.md 总行数控制在 40 行以内
   • 输出新增/更新的 memory 条目，让用户确认

2. WORKSPACE-PULSE 更新：

   • 读取 ~/claudecode_workspace/WORKSPACE-PULSE.json
   • 增量更新：active_work / recent_learnings / pain_points / itch_list / unsolved_questions 等
   • 更新 updated_at 和 updated_by

3. INDEX.md 维护：

   • 读取 ~/claudecode_workspace/记录/复盘/INDEX.md
   • 新文档：在对应日期下追加条目
   • 迭代更新：更新已有条目的描述和迭代标记
   • 条目格式：- **[标题](相对路径)** \项目标签` `领域标签` — 一句话描述`

4. 标记 Workbench task 已完成：

   • 如果本轮通过 Phase 1.5 创建了 _TASK_ID，最终复盘 Markdown 和索引写完后，必须把 task 标记为 consumed。
   • consumed task 会保留 JSON 追溯，但不再出现在 Workbench 首页任务队列。

   _WB="${_WB:-skills/forge-fupan/workbench/launcher.py}"
   if [ -n "${_TASK_ID:-}" ] && [ -f "$_WB" ]; then
     python3 "$_WB" consume --task-id "$_TASK_ID" || echo "⚠️ Workbench task 标记 consumed 失败，可稍后手动处理: $_TASK_ID"
   fi
   

5. 提交与推送：

   git add ~/claudecode_workspace/记录/复盘/ 2>/dev/null
   git add ~/.claude/projects/*/memory/ 2>/dev/null
   git add ~/claudecode_workspace/WORKSPACE-PULSE.json 2>/dev/null
   git commit -m "docs: 复盘 — [主题关键词]"
   git push origin "$_BRANCH" 2>/dev/null && echo "✅ 复盘已推送"
   

6. 最终输出：

   • 在对话中重新用 show-widget 渲染仪表盘（确保对话末尾能看到完整概览）
   • 列出所有生成的文件路径
   • 注意：此步骤的 widget 不需要再截图（Phase 4 已保存）

---

INDEX.md 规范

位置：~/claudecode_workspace/记录/复盘/INDEX.md

格式：

# 复盘索引

## 2026-04-06

- **[视频转文本工具：从 brainstorm 到端到端交付](视频转文本/2026-04-06-0100-[视频转文本工具]-从brainstorm到端到端交付.md)** `视频转文本` `工具开发` `视频处理` `LLM-API`
  录屏/截图→结构化文档的全自动管线。核心收获：LLM做语义+CV做像素。

## 2026-04-05

- **[v12.1 安全加固：密码重置+CORS+Rate-Limiting+法律合规](info2action/2026-04-05-1200-[v12.1安全加固]-密码重置+CORS+Rate-Limiting+法律合规.md)** `info2action` `安全` `后端`
  产品上线前安全审查，22项P0+P1全量实现。核心收获：安全配置分层dev/production。

规则：

• 按日期倒序（最新在上）
• 同一天多篇复盘按时间排列
• 每条：标题超链接 + 项目标签 + 领域标签 + 1-2 句话描述（含核心收获）
• 路径使用相对路径（相对于 INDEX.md 所在目录）
• 同会话迭代时更新已有条目，加 迭代×N 标签
• 每次 forge-fupan 执行完自动追加/更新

---

同会话迭代规范

当 Phase 0 检测到当前会话已有复盘文档时：

1. 读取已有文档，获取 frontmatter 中的 iteration 和 created
2. 全量重新分析整个对话（包括第一次复盘前后的所有内容）
3. 覆写原文件，更新 frontmatter：

   iteration: {原值+1}
   updated: {当前时间}
   

4. INDEX.md 更新已有条目，加 迭代×N 标签
5. 会话脉络中加入复盘分界线，展示复盘前后的精力对比
6. Git 提交信息：docs: 复盘迭代 — [主题关键词] (iter {N})

---

约束规范

图表双向同步铁律

• 所有 show-widget 必须在对话和复盘文档中同时可见，没有例外
• 每个 show-widget 都必须走完整流程：对话渲染 → 截图 PNG → 插入文档
• 仪表盘和精力分布图是强制生成项，其他图表按需生成
• Phase 5 最终输出的重渲染是唯一例外：复用 Phase 4 的截图

内容规范

• 不放代码片段：用自然语言描述概念
• 结构化优先：所有内容尽量分点论述，避免大段文字
• 表格从简：表格只用于天然适合对比/查找的内容，不用于表达因果关系
• 内容全面优先：不控制文档长度，确保每个分析点都有充分的内容

AI 表现复盘规范

• 必须归因到 AI 侧的具体失误，不能写"双方沟通不够"这类模糊归因
• 每个问题必须写"应有做法"
• 如果 AI 表现全部合格，仍需列出"做得好但可以更好"的点

Research 规范

• 每个知识领域至少做一次 web search（由 subagent 执行）
• 用户描述模糊的地方，必须调研该领域的标准表达方式并告诉用户"下次可以说"
• 资源必须权威：官方文档、知名作者博客、高赞社区讨论，禁止低质量转载
• 调研结果融入知识拓展章节，不单独成章

Memory 回流规范

• ✅ 行为指令："做X/不做Y" + 原因
• ✅ 项目活跃状态：架构、设计方向、待解决问题
• ✅ 外部资源指向：API 文档、监控地址、配置文件位置
• ❌ 代码实现细节
• ❌ 完整踩坑过程（已在复盘文件中）
• ❌ 一次性任务的临时状态

Memory 文件格式

---
name: 名称
description: 一行描述（用于判断是否相关，要具体）
type: feedback | project | reference
---

行为指令或项目状态描述。

**Why:** 原因
**How to apply:** 适用场景