Claude Code 进阶实战：用状态栏、输出风格与会话钩子造可观测自主代理

{
  "statusLine": {
    "type": "command",
    "command": "~/.claude/statusline.sh",
    "padding": 0
  }
}

{
  "hook_event_name": "Status",
  "session_id": "abc123def456",
  "transcript_path": "/home/you/.claude/projects/.../transcript.jsonl",
  "cwd": "/home/you/work/my-project",
  "model": { "id": "claude-sonnet-4-6", "display_name": "Sonnet" },
  "workspace": {
    "current_dir": "/home/you/work/my-project",
    "project_dir": "/home/you/work/my-project"
  },
  "version": "2.0.42",
  "output_style": { "name": "audit-report" },
  "cost": {
    "total_cost_usd": 0.1234,
    "total_duration_ms": 184000,
    "total_api_duration_ms": 9200,
    "total_lines_added": 412,
    "total_lines_removed": 57
  },
  "exceeds_200k_tokens": false
}

#!/usr/bin/env bash
# 读取 stdin 的会话 JSON
input=$(cat)

# 用 jq 安全取值，缺失字段给默认值
model=$(echo "$input"   | jq -r '.model.display_name // "?"')
cost=$(echo "$input"    | jq -r '.cost.total_cost_usd // 0')
added=$(echo "$input"   | jq -r '.cost.total_lines_added // 0')
removed=$(echo "$input" | jq -r '.cost.total_lines_removed // 0')
over=$(echo "$input"    | jq -r '.exceeds_200k_tokens // false')
cwd=$(echo "$input"     | jq -r '.workspace.current_dir')

# git 分支（不在仓库里就给兜底）
branch=$(git -C "$cwd" symbolic-ref --short HEAD 2>/dev/null || echo "no-git")

# 上下文警示色
ctx_flag="ok"
[ "$over" = "true" ] && ctx_flag="⚠️OVER200K"

# 组装输出（第一行即状态栏）
printf "🤖 %s | 💰\$%.4f | +%s/-%s | 🌿%s | 📊%s" \
  "$model" "$cost" "$added" "$removed" "$branch" "$ctx_flag"

chmod +x ~/.claude/statusline.sh

# 离线模拟一段输入，验证脚本不报错
echo '{"model":{"display_name":"Sonnet"},"cost":{"total_cost_usd":0.05,"total_lines_added":10,"total_lines_removed":2},"exceeds_200k_tokens":false,"workspace":{"current_dir":"'"$PWD"'"}}' | ~/.claude/statusline.sh

🤖 Sonnet | 💰$0.0500 | +10/-2 | 🌿main | 📊ok

---
name: audit-report
description: 输出结构化的代码审计报告，便于脚本解析与归档
---

你是一名严谨的代码审计员。每次输出必须遵循：

1. 先用一句话总结本次审计范围。
2. 用 Markdown 二级标题分节：## 🔴 高危 / ## 🟡 中危 / ## 🟢 提示。
3. 每条发现格式为：`- [文件:行号] 问题描述 → 建议修复`。
4. 结尾给出 `## 📊 统计` 小节，用列表写明高/中/低各多少条。
5. 不要寒暄、不要复述任务，直接出报告。

claude -p --output-style audit-report "审计 src/ 目录下所有未捕获异常"

claude -p --output-style audit-report "审计 ./src/parser.py 的错误处理"

{
  "hooks": {
    "SessionStart": [
      { "hooks": [ { "type": "command", "command": "~/.claude/hooks/on-start.sh" } ] }
    ],
    "UserPromptSubmit": [
      { "hooks": [ { "type": "command", "command": "~/.claude/hooks/on-prompt.sh" } ] }
    ],
    "PreCompact": [
      { "hooks": [ { "type": "command", "command": "~/.claude/hooks/on-compact.sh" } ] }
    ],
    "Stop": [
      { "hooks": [ { "type": "command", "command": "~/.claude/hooks/on-stop.sh" } ] }
    ],
    "Notification": [
      { "hooks": [ { "type": "command", "command": "~/.claude/hooks/on-notify.sh" } ] }
    ],
    "SessionEnd": [
      { "hooks": [ { "type": "command", "command": "~/.claude/hooks/on-end.sh" } ] }
    ]
  }
}

// 让代理"别停，继续干"——Stop 钩子最常用
{ "decision": "block", "reason": "尚未生成 ./reports/audit.md，请继续完成。" }

// 给模型追加附加上下文——SessionStart / UserPromptSubmit / PreCompact 通用
{ "hookSpecificOutput": {
    "hookEventName": "SessionStart",
    "additionalContext": "本次任务清单见 ./AUDIT_CHECKLIST.md，每完成一项就在文件里勾选。"
}}

// 阻断当前 prompt（UserPromptSubmit），把 reason 回喂
{ "decision": "block", "reason": "请先在 prompt 里指明目标目录。" }

#!/usr/bin/env bash
# on-notify.sh —— 无人值守时把"等待确认"信号发出来
msg=$(jq -r '.message // "Claude 需要你介入"')
# macOS
command -v osascript >/dev/null && osascript -e "display notification \"$msg\" with title \"Claude Code\""
# Linux
command -v notify-send >/dev/null && notify-send "Claude Code" "$msg"
# 跨平台兜底：写到一个被监控的文件
echo "$(date '+%H:%M:%S') $msg" >> ~/.claude/logs/notify.log

~/.claude/
├── settings.json                  # 挂状态栏 + 五个生命周期钩子
├── statusline.sh                  # 仪表盘
├── output-styles/audit-report.md  # 输出风格
└── hooks/
    ├── on-start.sh     # SessionStart：注入清单 + 打时间戳
    ├── on-prompt.sh    # UserPromptSubmit：追加"引用 file:line"
    ├── on-compact.sh   # PreCompact：抢救"已发现清单"
    ├── on-stop.sh      # Stop：报告未生成则 block
    ├── on-notify.sh    # Notification：桌面通知
    └── on-end.sh       # SessionEnd：落盘摘要 + 成本

#!/usr/bin/env bash
# on-start.sh
mkdir -p ~/.claude/logs ./reports
date '+%Y-%m-%d %H:%M:%S session-start' >> ~/.claude/logs/audit.log

cat <<'JSON'
{
  "hookSpecificOutput": {
    "hookEventName": "SessionStart",
    "additionalContext": "你是夜审代理。审计范围：今天相对 HEAD~1 的 git diff。完成后必须把结构化报告写入 ./reports/audit.md。每条发现引用 文件:行号。"
  }
}
JSON

#!/usr/bin/env bash
# on-prompt.sh
cat <<'JSON'
{
  "hookSpecificOutput": {
    "hookEventName": "UserPromptSubmit",
    "additionalContext": "提醒：所有结论必须以 `路径:行号` 形式给出证据，否则视为无效发现。"
  }
}
JSON

#!/usr/bin/env bash
# on-compact.sh
# 把已落盘报告里的统计摘要读回来，压缩后重新喂给模型
summary=""
if [ -f ./reports/audit.md ]; then
  summary=$(grep -E '^## 📊' -A 6 ./reports/audit.md | tr '\n' ' ')
fi
cat <<JSON
{
  "hookSpecificOutput": {
    "hookEventName": "PreCompact",
    "additionalContext": "压缩前抢救：当前已记录的审计统计为——${summary}。压缩后请基于此继续，不要重复已审项。"
  }
}
JSON

#!/usr/bin/env bash
# on-stop.sh
if [ -f ./reports/audit.md ] && [ -s ./reports/audit.md ]; then
  exit 0   # 报告已生成，放行结束
fi
cat <<'JSON'
{
  "decision": "block",
  "reason": "reports/audit.md 尚不存在或为空。请继续审计并按 audit-report 风格生成报告后写入该文件。"
}
JSON

#!/usr/bin/env bash
# on-end.sh
input=$(cat)
sid=$(echo "$input" | jq -r '.session_id')
# 把会话成本从 transcript 里扒出来太重，这里只记事件
date '+%Y-%m-%d %H:%M:%S session-end '"$sid" >> ~/.claude/logs/audit.log
command -v notify-send >/dev/null && notify-send "夜审完成" "报告见 ./reports/audit.md"

chmod +x ~/.claude/hooks/*.sh ~/.claude/statusline.sh

# 交互式：你会看到底部状态栏实时跳动，并感受钩子的"推背感"
claude --output-style audit-report

# 无人值守：挂上 --output-style，让钩子接管生命周期
nohup claude -p --output-style audit-report \
  "审计今天相对 HEAD~1 的改动，生成 ./reports/audit.md" \
  > ~/.claude/logs/run-$(date +%F).log 2>&1 &

flowchart TD
    A[启动 claude --output-style audit-report] --> B[SessionStart 钩子]
    B --> B1[注入任务清单 + 打时间戳]
    B1 --> C[模型开始审计]
    C --> D{上下文是否接近上限?}
    D -- 是 --> E[PreCompact 钩子]
    E --> E1[抢救已记录统计]
    E1 --> C
    D -- 否 --> F[模型声称完成 → Stop 钩子]
    F --> G{reports/audit.md 存在且非空?}
    G -- 否 --> H[decision:block 弹回继续]
    H --> C
    G -- 是 --> I[放行结束 → SessionEnd 钩子]
    I --> I1[落盘摘要 + 桌面通知]
    J[需要用户确认] -.触发.-> K[Notification 钩子]
    K --> K1[桌面/日志告警]
    L[底部 statusLine 全程实时显示<br/>成本·上下文·改行·分支] -.观测.-> C