forge-fupan

文档落地路径：遵循 forge-doc-policy 规范。完整白名单 + frontmatter schema 见 ~/.claude/skills/forge-doc-policy/doc-paths.md。

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

设计说明（v3，2026-07-17 重构）

v3 = v1 的 Workbench 门禁流程 + v2 的账本复利机制：

• Workbench 是复盘的确认门禁：AI 分析会话后把学习地图推到本地网页，用户在独立会话页（/session/{task_id}）勾选知识点和深度，提交后 AI 才继续调研写作。
• Workbench 首页是所有复盘会话的历史列表：进行中的在上，历史的（含已完成）在下，每个会话可点进独立页面回看当时的选择和生成的文档。
• 账本是副产出（保留自 v2）：每次复盘顺手落 2-3 条 learnings.jsonl 条目，bugfix/eng 开工时回放、下次复盘时做复发检测。写法见 references/learnings-schema.md。

使用建议

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

优先在上下文压缩或清空之前复盘。 这是最佳路径，因为当前模型上下文和本地 JSONL 都可用。若已经压缩，必须先检查原始 JSONL 是否仍包含 user_message/agent_message 或 Claude message.role；有原始日志则可正常复盘，无原始日志则只能做轻量复盘。

长会话 token 管理：单次功能完成后先复盘，再压缩或新开会话；隔夜/隔天继续时新开会话；超过 200 条消息无论如何都该压缩或新开。

---

输出位置

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

• 项目名由 AI 根据当前项目判断（如 info2action、skill-system、视频转文本），用户可覆盖。
• 文件名格式：{YYYY-MM-DD}-{HHMM}-[任务标签]-{主题关键词}.md。
• 示例路径：~/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"

# === 会话日志定位（Claude Code / Codex）===
_SESSION_SOURCE="unknown"
_JSONL_FILE=""
_CLAUDE_PROJECT_DIR="$HOME/.claude/projects"
_CODEX_HOME="${CODEX_HOME:-$HOME/.codex}"
_PARSE_TOKENS="$HOME/.claude/skills/forge-fupan/parse_tokens.py"
[ -f "$_PARSE_TOKENS" ] || _PARSE_TOKENS=$(find ~ -maxdepth 6 -path '*/forge-fupan/parse_tokens.py' -type f 2>/dev/null | head -1)

_latest_jsonl() {
  _name_pattern="$1"
  shift
  find "$@" -type f -name "$_name_pattern" -print 2>/dev/null | while IFS= read -r _f; do
    [ -f "$_f" ] || continue
    _mtime=$(stat -f %m "$_f" 2>/dev/null || stat -c %Y "$_f" 2>/dev/null || echo 0)
    printf "%s\t%s\n" "$_mtime" "$_f"
  done | sort -rn | head -1 | cut -f2-
}

if [ -n "${CODEX_THREAD_ID:-}" ] && [ -d "$_CODEX_HOME" ]; then
  _JSONL_FILE=$(_latest_jsonl "*${CODEX_THREAD_ID}*.jsonl" "$_CODEX_HOME/sessions" "$_CODEX_HOME/archived_sessions")
  [ -n "$_JSONL_FILE" ] && _SESSION_SOURCE="codex"
fi
if [ -z "$_JSONL_FILE" ] && [ -n "${CODEX_THREAD_ID:-}" ] && [ -d "$_CODEX_HOME" ]; then
  _JSONL_FILE=$(_latest_jsonl "*.jsonl" "$_CODEX_HOME/sessions" "$_CODEX_HOME/archived_sessions")
  [ -n "$_JSONL_FILE" ] && _SESSION_SOURCE="codex"
fi
if [ -z "$_JSONL_FILE" ] && [ -d "$_CLAUDE_PROJECT_DIR" ]; then
  _JSONL_FILE=$(_latest_jsonl "*.jsonl" "$_CLAUDE_PROJECT_DIR")
  [ -n "$_JSONL_FILE" ] && _SESSION_SOURCE="claude"
fi
if [ -z "$_JSONL_FILE" ] && [ -z "${CODEX_THREAD_ID:-}" ] && [ -d "$_CODEX_HOME" ]; then
  _JSONL_FILE=$(_latest_jsonl "*.jsonl" "$_CODEX_HOME/sessions" "$_CODEX_HOME/archived_sessions")
  [ -n "$_JSONL_FILE" ] && _SESSION_SOURCE="codex"
fi

echo "--- 会话日志 ---"
echo "会话来源: $_SESSION_SOURCE"
echo "会话日志: ${_JSONL_FILE:-未找到}"

if [ -n "$_JSONL_FILE" ]; then
  echo "--- Token 统计 ---"
  if [ -n "$_PARSE_TOKENS" ]; then
    python3 "$_PARSE_TOKENS" "$_JSONL_FILE" 2>/dev/null || echo "⚠️ Token 解析失败，将使用轮次估算"
  else
    echo "⚠️ parse_tokens.py 未找到，将使用轮次估算"
  fi
fi

if [ -n "$_JSONL_FILE" ]; then
  echo "--- 原始会话可用性 ---"
  python3 - "$_JSONL_FILE" "$_SESSION_SOURCE" <<'PY' 2>/dev/null || echo "⚠️ 原始会话检查失败，将按摘要降级判断"
import json
import sys

path = sys.argv[1]
source = sys.argv[2]
counts = {"user": 0, "agent": 0, "tool": 0, "compacted": 0}

with open(path, encoding="utf-8") as f:
    for line in f:
        try:
            data = json.loads(line)
        except Exception:
            continue

        payload = data.get("payload") or {}
        top_type = data.get("type")
        payload_type = payload.get("type") if isinstance(payload, dict) else None

        if top_type == "compacted" or payload_type == "context_compacted":
            counts["compacted"] += 1

        if source == "codex":
            if top_type == "event_msg" and payload_type == "user_message":
                counts["user"] += 1
            elif top_type == "event_msg" and payload_type == "agent_message":
                counts["agent"] += 1
            elif top_type == "event_msg" and payload_type in {"exec_command_end", "patch_apply_end"}:
                counts["tool"] += 1
        else:
            msg = data.get("message") or data.get("data", {}).get("message") or {}
            role = msg.get("role")
            if role == "user":
                counts["user"] += 1
            elif role == "assistant":
                counts["agent"] += 1
            if data.get("type") in {"tool_result", "tool_use"}:
                counts["tool"] += 1

if counts["user"] > 0 and counts["agent"] > 0:
    status = "FULL_LOG_AVAILABLE"
elif counts["user"] > 0:
    status = "PARTIAL_LOG_AVAILABLE"
else:
    status = "SUMMARY_ONLY_OR_MISSING"

print(f"原始消息: user={counts['user']} agent={counts['agent']} tool={counts['tool']} compacted={counts['compacted']}")
print(f"复盘可用性: {status}")
PY
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

# === 账本读取（复发检测对照组，v2 机制保留） ===
_LEDGER="$_FUPAN_DIR/learnings.jsonl"
_PROJECT=$(basename "$_ROOT")
if [ -f "$_LEDGER" ]; then
  echo "--- 账本已有条目（本项目 + global）---"
  grep -h "\"project\":\"$_PROJECT\"\|\"project\":\"global\"" "$_LEDGER" | tail -30
else
  echo "账本尚不存在，本次将创建：$_LEDGER"
fi