SuperAPI AI 工具集
合作ENAI 行业资讯收藏
Skill 广场session-bash-audit

session-bash-audit

安全与审计

查看项目

更新于 10-16 02:21

技能介绍

Session Bash audit 用于衡量 Claude Code 会话实际如何使用 Bash 工具，并与常驻指令文件所声明的 Bash 规则进行对照，最终帮助判断修复应当落在何处。

一、用途 该技能解决的是「会话是否遵守了 Bash 使用规则」以及「规则改动的效果如何」这类问题。它不依赖记忆或主观感受，而是从转录记录中统计真实调用，把数字变成可比较、可决策的依据。资料明确指出：让 agent 自述「效果如何」不能替代这个数字——已两次确认，刚写完规则的会话自身违规率反而更高，且自评「进展顺利」。

二、主要能力

  1. 统计并分类 Bash 调用形态：命令链式拼接（&&、;、|）、cd 进入会话自身仓库、git -C 指向自身仓库、head/tail 截断、exit-masked（管道掩盖退出码）、rg-replace（错误使用 -r 类标志）、heredoc、sed -n、cat、find-not-fd、grep-r-not-rg 等。
  2. 与基线对比：打印各模型当前比率相对基线的百分点差值，并按 EXPECTATIONS 给出 OK/MISS 判定。任一运行中调用数少于 50 次的模型显示为 ?，不做判定。
  3. 会话级视图：以单次会话为单位对照基线，是唯一能在会话仍可行动时给出答案的模式。报告按行输出，计数在前，百分比在后；每一行都会打印，包括 0 值。
  4. 细分拆解：exit-masked 区分「包裹了门禁（gate）」与「包裹了列表输出」；rg-replace 会指出具体标志拼写（-rn、-ril、lone -r 等不同含义）。
  5. 压缩会话拆分：当转录带有 continuation turn 时，会在整体之后分别打印压缩前后两侧的数据行，依据 harness 自身的 isCompactSummary 标志判定。
  6. 时间窗口：--since 与 --until 互为两端，一个窗口用两个参数而非两次运行加相减；计数可相减，但样本、门禁/列表拆分与截断行不可相减。

三、使用方式 技能位于 S=~/.agents/skills/session-bash-audit，提供四个流程：

  • Measure：python3 $S/scripts/audit.py --days 4 --samples 5；或 python3 $S/scripts/audit.py --days 7 --project <repo> --json <scratch-dir>/calls.json。只读、仅用标准库，一周转录约 10 秒。--samples 0 只输出表格。
  • 单会话对照基线：python3 $S/scripts/audit.py --session <session-id> --compare ~/.local/state/session-bash-audit/<file>.json。id 为转录文件名主干，唯一前缀即可。
  • Compare：python3 $S/scripts/audit.py --days 7 --samples 0 --compare $S/references/baselines/2026-08-24-auto-mode.json。
  • 窗口：python3 $S/scripts/audit.py --session <session-id> --since <instant> --samples 4。

读写范围：读取 ~/.claude/projects/*.jsonl 与 ~/.claude/settings.json（均为只读，从不写入）；可选读取用户自身的 $XDG_CONFIG_HOME/session-bash-audit/expectations.json（Windows 为 %APPDATA%\…）或由 --expectations <path> 指定的路径。运行时仅执行三条针对其自身目录的只读 git 命令（ls-files、rev-parse HEAD、status --porcelain），且仅在写入基线时执行；prompts.py 在进程内重放权限规则。仅在显式使用 --save-baseline 时写入基线到 $XDG_STATE_HOME/session-bash-audit/（Windows 为 %LOCALAPPDATA%\session-bash-audit\），已存在时拒绝覆盖，需 --force 才故意销毁；--json <path> 时导出快照。从不写转录、设置或自身安装目录。无网络访问。

四、适用场景 适用于运行 Claude Code 且其 Bash 工具执行 POSIX shell 的任意机器（Windows 上为 Git Bash 或 WSL 会话，行为不变）。可用于日常测量、规则改动后的复核、权限模式编辑后的行为校验、分析频繁弹窗原因，以及单次会话的自查。

五、限制与已知问题

  1. PowerShell 会话不适用：其命令不匹配这些 POSIX 模式，报告会显示「未发现问题」，实际含义是「工具用错了转录」。
  2. 自身仓库判定：cd-own-repo 与 git-C-own-repo 通过 slug 化命令目标来判定，曾长期在含下划线路径、Windows 路径上出错并报 0（读起来像完全遵守）；现已改用 harness 自身规则，但仅在该 slug 形状可辨识的布局下有效。
  3. git worktree 会话：这两行会对来自 worktree 的会话静默出错，因为 slug 是 worktree 路径而非仓库路径；这是声明式限制而非修复，脚本离线读取、无法向 git 询问 checkout，唯一信号是 slug 形状，且只覆盖多种布局中的一种。凡会话可能来自 worktree，这两行的 0 应视为未验证。
  4. exit-masked 只统计形态，是否造成代价需按机器回答：管道默认报最后一段状态，但设置了 pipefail 的 shell 会报最右侧非零状态，此时并无隐藏。转录只记录命令不记录 shell，需在被审计会话中实际运行 setopt | rg pipefail（zsh）或 set -o | rg pipefail（bash）确认后再解读高比例。配置文件不能作为答案，因为该选项常被 harness 变量守护。
  5. 与 session-harvest 的口径差异：harvest.py 的 EXIT_MASKED_RE 匹配原始命令，会把引号内或 heredoc 正文中的管道计为真实管道；audit.py 会剥离两者。两者数字方向相反地「错」，不应互为校验，预期 harvest 的 claims 略高。
  6. 基线数据是作者一台机器在一套规则下的参考点，不是用户自身基线；已发布的一行基线仅供参照，--compare 到它会报告的是「你的会话与别人的设置有何差异」。应在首次运行就用 --save-baseline 保存自己的基线，即便数字难看也应保存，只从满意的运行保存会破坏序列。
  7. 历史缺陷：--session 路径曾在读取 --json 标志前返回，导致该模式下无法导出且无报错；--session 模式会拒绝 --save-baseline 而非静默跳过；heredoc 曾在提交密集会话中过度计数，2026-09-01 因规则改为内联 -m 而停止；样本需盖上对应的 ~/.agents/AGENTS.md 提交，否则看似漂移的比率可能只是会话正确遵循了更早的规则。
  8. 使用陷阱：所有模式都应不加管道运行；| head -N 在以 head/tail 截断为主题的报告中会造成错误结论（已确认，截断后误判 --compare 未产生对比）。
  9. 期望值 EXPECTATIONS 是作者个人规则集的读法，而非 Bash 的事实，应使用自己的规则打分。