0xelitesystem/agent-blast-radius

# agent-blast-radius `blast-radius` 会在事后*回放* AI 编程代理的会话记录，并重建其产生的所有副作用：它创建、修改和删除的文件；它推送的提交；它通过网络发送的数据；它安装的包；它运行的破坏性 shell 命令。然后，它会回答在出现问题时唯一重要的疑问：**这些操作中哪些是不可逆的，以及它们是否真的成功了？** 它是一份取证报告，而不是实时监控器。无需预先安装任何东西，没有守护进程，也没有包裹你 shell 的包装器。你只需将其指向你已经拥有的记录文件，即 Claude Code 写入到 `~/.claude/projects/` 的 JSONL，它就会告诉你影响范围。 零依赖。纯 Python 标准库。支持离线工作，无需 API 密钥，任何数据都不会离开你的机器。 ## 问题所在 如今，代理在无人值守的情况下运行，且动作迅速。你把任务交给它，离开一会儿，回来时面对的是一个已完成的会话和一种隐隐的担忧：*我不在的时候它到底做了什么？* 在事件发生时的晚上 11 点，滚动浏览上千行的记录，去寻找那唯一一次 `git push --force` 或是那唯一一次 `curl --data @secrets.json`，这种“大海捞针”式的审查根本没人能仔细完成。 现有的工具都是为*事前*构建的：沙盒、权限提示、允许列表，以及你需要提前设置的实时审计日志。当事情已经发生，你手中只有记录文件时，这些工具都无济于事。**agent-blast-radius 是回顾性的**，它像事件响应者在数据泄露后查看日志一样，从你已保留的记录中重建破坏情况。 推动整个报告的核心区别在于：**可逆性**。一次编辑相当于 `ctrl-Z`。一次本地提交相当于 `git reset`。但是，推送到共享远程仓库、重写历史记录的强制推送、`DELETE FROM`、发送到 webhook 的数据，这些都无法挽回了。报告会首当其冲地展示这些操作，别无其他。 ## 它能捕获什么 这是一份关于 [`examples/demo-session.jsonl`](examples/demo-session.jsonl) 的真实报告，其中一个代理编辑了三个文件，安装了一个包，进行了提交，**强制推送到了 origin**，递归删除了 `build/`，并且**向 webhook POST 了数据**： ``` agent-blast-radius, what did this agent touch, and what's irreversible? session demo-session · 10 events · /home/dev/acme-api BLAST TIER CRITICAL 3 files · 2 vcs · 1 network · 1 packages · 1 system IRREVERSIBLE & SUCCEEDED (2) ● CRIT git push --force origin main └─ force-push (rewrites remote history, unrecoverable for others) [event 6] ● HIGH curl -X POST https://hooks.acme.dev/deploy --data '{"status":"deployed"}' └─ outbound HTTP with request body (data egress) [event 8] FILES (3) ✓ INFO [created] /home/dev/acme-api/src/ratelimit.py reversible ✓ INFO [modified] /home/dev/acme-api/src/app.py reversible ✓ INFO [modified] /home/dev/acme-api/requirements.txt reversible VERSION CONTROL (2) ✓ LOW git commit -am 'Add rate limiting' reversible ✓ CRIT git push --force origin main IRREVERSIBLE NETWORK / EXTERNAL (1) ✓ HIGH curl -X POST https://hooks.acme.dev/deploy --data '{"status":"deploye… IRREVERSIBLE PACKAGES / ENV (1) ✓ LOW pip install redis hard-to-reverse SYSTEM / DESTRUCTIVE (1) ✓ HIGH [deleted] build/ hard-to-reverse ``` 自己运行一下： ``` blast-radius report examples/demo-session.jsonl ``` ## 安装 ``` pip install git+https://github.com/0xelitesystem/agent-blast-radius ``` Python ≥ 3.10。无依赖。 ## 用法 ``` # 重建你最近的 Claude Code session blast-radius report latest # 通过 id 前缀指定特定 session，或任意 transcript 路径 blast-radius report 8dcbd9b2 blast-radius report ~/.claude/projects//.jsonl # 列出所有项目中最近的 session blast-radius list # 机器可读输出 / Markdown 报告 blast-radius report latest --json blast-radius report latest --md report.md # 专注于一处展示，或隐藏干扰信息 blast-radius report latest --only vcs blast-radius report latest --danger-min high # CI / 自动化门禁：如果有任何不可逆且严重的关键变更合入，则以 exit 1 退出 blast-radius report latest --fail-on-critical ``` ## 追踪内容 代理采取的每一个产生副作用的操作都被归类为六个层面之一： | 层面 | 示例 | |---|---| | **文件** | `Write`/`Edit`/`MultiEdit`/`NotebookEdit`，以及 shell `rm`/`del`/`Remove-Item`/`mv`，区分创建、修改与删除，并包含每个文件的编辑次数 | | **版本控制** | `git commit`（可逆），`git push`（**不可逆**），`reset --hard` / `checkout --` / `clean`（破坏性），`rebase`，强制推送（**严重**），分支/标签的创建与删除 | | **网络 / 外部** | `WebFetch`/`WebSearch`，`curl`/`wget`/`Invoke-WebRequest`，向外 POST 数据的命令（数据传出），`gh` API 写入（PR、issue、仓库） | | **包 / 环境** | `pip`/`npm`/`yarn`/`cargo`/`apt`/`brew`/`uv` 安装，全局/`sudo` 安装的评级高于项目本地安装 | | **系统 / 破坏性** | `rm -rf`，递归删除，`chmod`/`chown`，进程终止，在 **cwd 之外**的写入（路径逃逸），`sudo`，数据库写入（`psql -c`、`DROP`、`DELETE FROM`、migrations），`docker run`/`rm`，`systemctl`，cron/计划任务 | | **密钥层面** | 读取包含密钥的文件的命令（`cat .env`，读取 `~/.aws/credentials`），标记为**暴露** | ## 结论是如何生成的 每个操作都有两个独立的维度，而整个会话会汇总为一个级别。 **可逆性**，核心取证维度： | 级别 | 含义 | |---|---| | `reversible` | `ctrl-Z` 领域，一次编辑，一次本地提交 | | `hard-to-reverse` | 需要努力才能恢复，`rm` 删除文件，`reset --hard`，包安装 | | **`IRREVERSIBLE`** | 彻底消失，推送到远程，数据已传出，强制推送，`DELETE FROM` | **严重性**，危险程度，独立于可逆性（一个频繁的 `curl` GET 是可逆的，但仍然值得注意）： | 级别 | 典型操作 | |---|---| | INFO | 在 cwd 内部的文件写入 | | LOW | 本地提交，项目本地安装 | | MEDIUM | `reset --hard`，单文件删除，全局安装，`chmod` | | HIGH | `git push`，递归删除，数据传出，`gh` PR/issue 写入 | | CRITICAL | 强制推送，已生效的破坏性 SQL | **影响范围级别**是根据最严重的*成功*操作计算出来的：`CONTAINED`（仅包含可逆编辑） → `MODERATE`（发生了某些难以逆转的操作） → `WIDE`（发生了不可逆操作） → `CRITICAL`（发生了严重性也为 CRITICAL 的不可逆操作）。 ### 成功判定：失败的 `rm` 什么也没删除 最重要的规则：**未成功的操作不会产生副作用。** 该工具通过 id 将每个工具调用与其结果进行匹配，并读取退出码。一个以非零状态退出的 `rm important.py` 仍然会被显示，但会被降级为可逆/LOW，并附带 `(failed, no effect)`（失败，无影响）的注释，而且它永远不会提高影响范围级别。被远程拒绝的强制推送不会使会话变成 CRITICAL。报告关注的是*实际发生*了什么，而不是*尝试*了什么。 ## 工具套件的一部分 agent-blast-radius 是从不同角度阅读同一份 Claude Code 记录文件的三款工具之一： - **[agent-receipts](https://github.com/0xelitesystem/agent-receipts)**，代理的*声明*（“所有测试通过”）是否与它的实际行为相符？ - **agent-blast-radius**（本工具），它*触碰*了什么，哪些是不可逆的？ - **agent-leaks**，它读取或暴露了哪些*机密*？（这里的密钥暴露行正是两者的接缝处；agent-leaks 会针对这一层面进行深入挖掘。） 它们共享一个解析器和一种心智模型，因此同一个 `latest` 记录文件就能回答这三个问题。 ## 诚实的局限性 - **仅限记录文件。** 它从记录文件所记录的内容中进行重建。如果副作用发生在代理运行的脚本内部（例如推送代码的 `./deploy.sh`），该工具看到的是 `./deploy.sh`，而不是其内部的 push 操作。它读取的是代理直接发出的命令，而不是完整的进程树。 - **启发式分类。** 可逆性和严重性来自于对命令形态的模式匹配，而不是通过执行或模拟任何东西。它倾向于标记；不常见的命令措辞可能会被错误分类或漏掉。每一行都指向其确切的事件索引，以便你可以自行对照记录文件进行验证。 - **成功是从退出码和输出推断出来的。** 退出码为 0 但静默无效的操作会被视为成功。部分应用的破坏性命令会被视为已完全应用。 - **路径逃逸是基于词法的。** 它将写入的路径与作为文本的会话 cwd 进行比较（因此它适用于在另一台机器上捕获的记录文件），它不会解析 symlink。 ## 代理问责工具套件的一部分 - [agent-receipts](https://github.com/0xelitesystem/agent-receipts)，代理的声明（“测试通过”）是否与现实相符？ - [agent-leaks](https://github.com/0xelitesystem/agent-leaks)，它是否将机密泄露到了记录文件中？ - **agent-blast-radius**，它采取了哪些不可逆的操作？ - [agent-rules](https://github.com/0xelitesystem/agent-rules)，它是否遵循了你的 `CLAUDE.md`？ - [agent-cost](https://github.com/0xelitesystem/agent-cost)，token 和钱都花在哪了？ ## 路线图 - [ ] 适配其他持久化记录文件的代理（Codex CLI、OpenCode、Gemini CLI） - [ ] 套件集成：一个命令在 `latest` 上运行 agent-receipts + agent-blast-radius + agent-leaks，并打印组合后的事故卡片 - [ ] `blast-radius diff `，针对同一任务的两次运行，其影响范围之间发生了什么变化 - [ ] Claude Code Stop-hook 集成：自动报告每个会话，在 CRITICAL 时发出警报 - [ ] 针对仓库解析 `./script.sh` 调用，以恢复脚本内部的副作用 ## 开发 ``` git clone https://github.com/0xelitesystem/agent-blast-radius cd agent-blast-radius pip install -e .[dev] pytest python examples/make_demo.py && blast-radius report examples/demo-session.jsonl ``` ## 许可证 [MIT](LICENSE)