断点续跑：用 session 续接打造崩溃自愈的 Claude Agent

~/.claude/projects/<把工作目录路径编码后的串>/<session-id>.jsonl

flowchart LR
    subgraph 一次claude-p调用
      A["claude -p '任务'<br/>--output-format json"] -->|stdout| B["JSON: result / session_id /<br/>is_error / stop_reason"]
    end
    B --> C["解析出 session_id<br/>写入状态文件"]
    C --> D[("~/.claude/projects/<cwd>/<sid>.jsonl<br/>持续落盘的对话转录")]
    D -.崩溃后.-> E["claude -p '继续' --resume SID"]
    E --> B

# 跑一次审查任务，拿到 session_id 并落盘
out=$(claude -p "审查 src/ 目录里的性能问题，先列出 top 5" \
  --allowedTools "Read,Grep,Glob" \
  --output-format json)

# 提取关键字段
session_id=$(jq -r '.session_id'    <<<"$out")
cost=$(jq -r '.total_cost_usd // 0' <<<"$out")
result=$(jq -r '.result'            <<<"$out")

# 落盘，供后续续跑或排障使用
echo "$session_id" > .last-session
printf '%s\t%s\t%s\n' "$(date -u +%FT%TZ)" "$session_id" "$cost" >> .agent-runs.tsv

echo "$result"
echo "session_id = $session_id （已保存到 .last-session）"

session_id=$(cat .last-session)
claude -p "刚才你列了 top 5，现在重点看数据库查询那两条，给出优化方案" \
  --resume "$session_id" \
  --allowedTools "Read,Grep,Glob" \
  --output-format json | jq -r '.result'

claude -n dep-upgrade-api -p "升级 services/api 的依赖" --output-format json | jq -r .session_id
# 之后任意位置、同仓库内：
claude -p "继续" --resume dep-upgrade-api

{
  "hooks": {
    "StopFailure": [
      {
        "matcher": "rate_limit|overloaded|server_error",
        "hooks": [
          {
            "type": "command",
            "command": "${CLAUDE_PROJECT_DIR}/.claude/hooks/on-failure.sh",
            "args": []
          }
        ]
      }
    ]
    ,
    "Stop": [
      {
        "hooks": [
          { "type": "command", "command": "${CLAUDE_PROJECT_DIR}/.claude/hooks/on-stop.sh", "args": [] }
        ]
      }
    ]
  }
}

#!/usr/bin/env bash
# .claude/hooks/on-failure.sh  —— chmod +x
input=$(cat)
sid=$(jq -r '.session_id'         <<<"$input")
evt=$(jq -r '.hook_event_name'    <<<"$input")
ts=$(date -u +%FT%TZ)

# 写失败日志
printf '%s\t%s\t%s\n' "$ts" "$sid" "$evt" >> "${CLAUDE_PROJECT_DIR}/.agent-failures.log"

# 打一个"待续跑"标记，供包装脚本或定时器读取
echo "$sid" > "${CLAUDE_PROJECT_DIR}/.resume-needed"
exit 0

#!/usr/bin/env bash
# .claude/hooks/on-stop.sh  —— chmod +x
input=$(cat)
sid=$(jq -r '.session_id' <<<"$input")
rm -f "${CLAUDE_PROJECT_DIR}/.resume-needed"
printf '%s\t%s\tCLEAN_STOP\n' "$(date -u +%FT%TZ)" "$sid" >> "${CLAUDE_PROJECT_DIR}/.agent-runs.tsv"
exit 0

#!/usr/bin/env bash
# selfheal.sh —— 在 API 错误后自动用 --resume 续跑，直到完成或超上限
set -uo pipefail

PROMPT="$1"
MAX_ATTEMPTS="${2:-5}"
SESSION_ID=""
PERMISSIONS="Read,Edit,Bash(git *),Bash(npm test)"

for attempt in $(seq 1 "$MAX_ATTEMPTS"); do
  if [[ -z "$SESSION_ID" ]]; then
    # 首次运行
    out=$(claude -p "$PROMPT" \
            --permission-mode acceptEdits \
            --allowedTools "$PERMISSIONS" \
            --output-format json 2>.selfheal.err)
  else
    # 续跑：明确告知中断、要求接着干
    out=$(claude -p "上一次运行因错误中断（第 ${attempt} 次重试）。请从断点继续，不要重复已完成的工作。" \
            --resume "$SESSION_ID" \
            --permission-mode acceptEdits \
            --allowedTools "$PERMISSIONS" \
            --output-format json 2>.selfheal.err)
  fi

  # 进程本身崩了（OOM/网络断/SIGKILL），没有 JSON
  if ! jq -e . >/dev/null 2>&1 <<<"$out"; then
    echo "⚠️ 第 $attempt 次：进程异常退出（见 .selfheal.err）" >&2
    sleep $((attempt * 5))
    continue
  fi

  SESSION_ID=$(jq -r '.session_id // ""' <<<"$out")
  is_error=$(jq -r '.is_error // false'   <<<"$out")
  reason=$(jq -r '.stop_reason // ""'      <<<"$out")

  if [[ "$is_error" == "false" ]]; then
    jq -r '.result' <<<"$out"
    exit 0
  fi

  echo "⚠️ 第 $attempt 次失败 (stop_reason=$reason)，session=$SESSION_ID，退避后续跑..." >&2
  sleep $((attempt * 5))   # 简单指数退避
done

echo "❌ 超过最大重试次数 $MAX_ATTEMPTS。最终会话：$SESSION_ID" >&2
echo "手动续跑：claude --resume $SESSION_ID" >&2
exit 1

./selfheal.sh "把 auth 模块的老式回调改写成 async/await，并保证 npm test 全绿"

claude -p "生成迁移脚本" \
  --output-format stream-json --verbose \
  | jq -rc 'select(.type=="system" and .subtype=="api_retry")
            | "[retry] #\(.attempt)/\(.max_retries) 等 \(.retry_delay_ms)ms — \(.error)"' \
  >> .retry-trace.log &

claude -n "patrol-$(basename "$PWD")-$(date +%Y%m%d)" -p "..." --output-format json

export CLAUDE_CONFIG_DIR=/data/agent-state

// .claude/settings.json
{ "cleanupPeriodDays": 90 }

git diff main > /tmp/d.diff
claude -p "审查 /tmp/d.diff 这个 diff 里的拼写和明显 bug" --allowedTools Read

#!/usr/bin/env bash
# repo-upgrade-patrol.sh
set -uo pipefail
ROOT=$(pwd)
REPOS=(services/api services/auth services/billing web/frontend)
STATE="$ROOT/.patrol-state.tsv"
PERMISSIONS="Read,Edit,Bash(npm install),Bash(npm test),Bash(git *)"
printf 'repo\tsession_id\tstatus\tattempts\n' > "$STATE"

upgrade_one() {
  local repo="$1" sid="" n=0
  cd "$ROOT/$repo" || { printf '%s\t-\tSKIP\t-\n' "$repo" >> "$STATE"; return; }

  while (( n < 3 )); do
    n=$((n+1))
    local out
    if [[ -z "$sid" ]]; then
      out=$(claude -n "patrol-$repo" -p \
            "升级 package.json 中所有 patch 版本依赖到最新，npm install 后跑 npm test，全绿就 git commit。" \
            --permission-mode acceptEdits --allowedTools "$PERMISSIONS" \
            --output-format json)
    else
      out=$(claude -p "上次中断，从断点继续，不要重复已完成步骤。" \
            --resume "$sid" --permission-mode acceptEdits \
            --allowedTools "$PERMISSIONS" --output-format json)
    fi

    jq -e . >/dev/null 2>&1 <<<"$out" || { sleep 5; continue; }
    sid=$(jq -r '.session_id // ""' <<<"$out")
    if [[ "$(jq -r '.is_error // false' <<<"$out")" == "false" ]]; then
      printf '%s\t%s\tOK\t%s\n' "$repo" "$sid" "$n" >> "$STATE"
      cd "$ROOT"; return 0
    fi
    sleep $((n*5))
  done
  printf '%s\t%s\tFAILED\t%s\n' "$repo" "$sid" "$n" >> "$STATE"
  cd "$ROOT"
}

for r in "${REPOS[@]}"; do upgrade_one "$r"; done
echo "===== 巡检结果 ====="; column -t -s$'\t' "$STATE"

flowchart TD
    S([巡检脚本启动]) --> L{"遍历仓库列表"}
    L -->|每个 repo| R["cd repo; claude -p ... --output-format json"]
    R --> J{解析 JSON}
    J -->|is_error=false / 非 JSON 重试| OK["记 OK<br/>下一个仓库"]
    J -->|is_error=true| CAP["记 session_id"]
    CAP --> RT{重试<3?}
    RT -->|是| RES["claude -p '继续' --resume SID"]
    RES --> J
    RT -->|否| FAIL["记 FAILED + SID<br/>留待人工 --resume"]
    OK --> L
    FAIL --> L
    L -->|全部完成| T[[输出状态表]]