问题

Claude Code（以及所有其他AI编码CLI）将你的完整对话历史以明文JSONL格式存储在磁盘上——对于Claude Code是 ~/.claude/projects/，对于OpenAI Codex是 ~/.codex/sessions/。你粘贴的任何内容——AWS密钥、.env 文件、数据库URL——都会无限期地以明文形式存在。一个典型的开发者历史会在数月内累积数十个机密信息，而他们往往没有意识到。

agentsweep 可以扫描这些历史，告诉你哪些内容泄露了，并且可以在原地编辑机密值，同时逐字节保留JSONL结构。它还会告诉你需要轮换哪些密钥，并为每个提供商提供正确的撤销URL。

保护范围： agentsweep 本身是完全本地和离线的——它只读取和写入你机器上的文件，不进行任何网络调用。它消除了一个攻击向量：机密信息存在于本地历史文件中。它不影响你的AI提供商已经接收到的内容：当你将密钥粘贴到Claude Code、Cursor或任何云支持的代理中时，该密钥在到达磁盘之前已经经过了提供商的服务器。如果你担心这一点，请考虑使用本地托管的模型（Ollama、LM Studio、OpenCode），其中没有任何内容离开你的机器——agentsweep 尤其适合与本地模型设置配合使用。

为什么现在这很重要

供应链攻击正在加速。在2024-2025年，一波恶意的npm和PyPI软件包——例如 sha256-universal、shailulid 以及数百个拼写相似攻击——被发现只做一件事：从安装它们的机器上泄露开发者凭据。它们针对环境变量、.env 文件、shell历史、SSH密钥，现在还包括AI代理历史文件。

AI编码助手创造了一种两年前不存在的新的凭据暴露类别：

• 你将生产API密钥粘贴到Claude Code中以调试某些内容 → 现在它永远存在于 ~/.claude/projects/*/conversations/*.jsonl 中
• 一个被感染的npm软件包运行 postinstall → 扫描常见路径 → 找到你的JSONL历史 → 在一次请求中泄露50个API密钥
• 你轮换了你公开使用的密钥，但忘记了历史中的其他十几个
• 同时你的历史不断增长：你请AI帮忙处理的每个 .env 文件、你为了调试而分享的每个数据库URL、你粘贴的每个用于一行命令的令牌

AI代理历史是新的 .bash_history——只是它包含完整的上下文，而不仅仅是命令。 攻击工具已经知道这一点。agentsweep 的存在是为了在被利用之前进行清理。

快速开始

pip install uv                  # 获取 uv（如果你已经有了则跳过）
uv tool install agentsweep      # 安装 — 将 `agentsweep` 和 `asweep` 添加到 PATH
asweep                          # 运行 — 交互式菜单指导你完成所有步骤

就是这样。无需激活虚拟环境，无需配置PATH——uv tool install 为命令提供了自己隔离的环境。

工作原理

agentsweep 运行一个固定的5阶段管道。scan 在阶段3停止；fix 继续进行编辑。

flowchart LR
    A("🔍 发现\n遍历历史目录\n流式文件列表") --> B("⚡ 扫描\nAho-Corasick 预过滤\n191条正则规则 + BIP-39")
    B --> C{"发现\n机密？"}
    C -- "没有" --> D("✅ 干净\nexit 0")
    C -- "发现" --> E("📋 发现结果\n显示报告\nexit 1")
    E -. "仅扫描" .-> F("⚠️ 轮换\n密钥仍然有效")
    E -- "输入 REDACT" --> G("✏️ 编辑\n原子写入 · .bak 备份\n写入后 JSON 验证")
    G --> H("🔑 轮换\n按提供商\n撤销链接")

    style A fill:#1e3a5f,color:#fff,stroke:#2d5986
    style B fill:#1e3a5f,color:#fff,stroke:#2d5986
    style C fill:#4a3728,color:#fff,stroke:#7a5c3f
    style D fill:#1a4731,color:#fff,stroke:#2d7a52
    style E fill:#4a3a1e,color:#fff,stroke:#7a6030
    style F fill:#4a2020,color:#fff,stroke:#8b3a3a
    style G fill:#1e3a5f,color:#fff,stroke:#2d5986
    style H fill:#2d1e4a,color:#fff,stroke:#5a3a8b

每次写入都由8个安全不变量保护——原子替换、强制性 .bak 备份、拒绝符号链接、mtime/进程门控以及写入后JSONL验证。agentsweep undo 从备份中恢复。

安装

推荐——隔离，无虚拟环境冲突：

uv tool install agentsweep      # 一次性安装
uv tool upgrade agentsweep      # 更新到最新版本

无需安装即可尝试（始终运行最新版本）：

uvx agentsweep@latest

经典 pip：

pip install agentsweep
pip install --upgrade agentsweep

没有 uv？请执行 pip install uv 或参见 astral.sh/uv。需要 Python 3.11+。

使用

交互模式

在终端中不带参数运行，你将获得完整的体验——横幅、编号菜单、在破坏性操作之前输入的确认，以及一键撤销（恢复 .bak 备份）。任何找到机密信息的交互式扫描都会就地提供编辑选项（输入 REDACT 确认）：

agentsweep

脚本编写不受影响：任何标志或管道/重定向流都会跳过菜单，并完全按照下文所述行为运行。

动词

旧的标志形式 agentsweep --fix 仍然被接受，行为与 agentsweep fix 相同。

来源选择

使用 --source 选择要定位哪个代理的历史。默认为 claude-code。

agentsweep scan --source claude-code          # ~/.claude/projects/（默认）
agentsweep scan --source codex                # ~/.codex/sessions/
agentsweep scan --source opencode             # OpenCode SQLite 存储
agentsweep scan --source cursor               # Cursor 历史
agentsweep scan --source windsurf             # Windsurf 历史
agentsweep scan --source aider                # ~/.aider/
agentsweep scan --source cline                # Cline 历史
agentsweep scan --source gemini-cli           # Gemini CLI 历史
agentsweep scan --source continue-vscode      # Continue (VS Code) 历史
agentsweep scan --source github-copilot-chat  # GitHub Copilot Chat 历史
agentsweep scan --source openclaw             # OpenClaw ~/.openclaw/
agentsweep scan --source hermes               # Hermes Agent ~/.hermes/state.db
agentsweep scan --source goose                # Goose ~/.local/share/goose/

不确定你安装了哪些代理？list-sources 会打印每个支持的来源、其历史位置，以及该历史是否存在于本机——这样你就知道哪些 --source 值值得扫描。它不读取任何内容，也不写入任何内容。

agentsweep list-sources             # 全部29个来源 + 哪些存在于磁盘上
agentsweep list-sources --detected  # 仅本机上找到的
agentsweep list-sources --json      # 机器可读（用于脚本/CI）

一次扫描所有已注册的代理（聚合发现结果；编辑按来源进行）：

agentsweep scan --all                 # 所有已注册的来源
agentsweep scan --all --detected      # 仅在磁盘上拥有历史根目录的来源
agentsweep scan --all --json          # 聚合的 JSON（每个发现结果包含 "source"）
agentsweep scan --all --json -o out.json

覆盖默认根目录以扫描任意文件夹：

agentsweep scan --root ~/backups/claude-history
agentsweep fix  --root /tmp/history-copy --allow-production

扫描 / fix 标志

# 机器可读的 JSON 输出到 stdout（exit 0 = 干净，1 = 发现结果，2 = 错误）
agentsweep scan --json

# 将发现结果 JSON 写入文件而不是 stdout
agentsweep scan --json -o findings.json
agentsweep scan --json --output /tmp/report.json

# 跳过 .agentsweepignore 文件
agentsweep scan --no-ignore

仅 fix 标志

# 原地编辑 Claude Code 历史（在 alpha 阶段对默认根目录需要 --allow-production）
agentsweep fix --allow-production

# 跳过创建 .bak 备份（不推荐）
agentsweep fix --allow-production --no-backup

# 绕过软安全检查：mtime 门控（< 60 秒前修改的文件）和正在运行的进程门控
agentsweep fix --allow-production --force

# 组合：针对自定义根目录的非交互式 JSON 模式编辑
agentsweep fix --root ~/history-copy --json

Undo 标志

# 撤销特定来源的编辑
agentsweep undo --source codex

# 针对自定义根目录撤销
agentsweep undo --root ~/history-copy

防损坏保证

一个会损坏你历史的编辑器比它要修复的泄露更糟糕。agentsweep 在每个 --fix 中强制执行以下不变量：

1. 编辑在解析的 JSON 中执行，而不是在原始字节上。 机密信息在解析结构内作为字符串值被替换，然后重新序列化。结构损坏在构造上是不可能的。
2. 原子写入。 每次重写都遵循：临时文件 → fsync() → os.replace() 覆盖原始文件。在任何时刻崩溃都会留下完整的旧文件或完整的新文件——绝不会出现部分写入。
3. 写入后验证。 在提交之前，新内容必须通过格式感知检查：JSONL——每个非空行都解析为 JSON 且行数与原始文件匹配；整个文件 JSON——文档解析；markdown/纯文本——行数与原始文件匹配；SQLite——重写的副本通过 PRAGMA integrity_check。如果检查失败，写入被中止，原始文件不受影响。
4. 默认创建 .bak 备份。 仅所有者可读（模式 0600），因为它包含编辑前的机密信息；如果 .bak 已存在则拒绝运行（因此不会覆盖先前的备份）。
5. 路径限制。 拒绝任何未解析到来源历史树内部的目标（例如 Windsurf 的 User 目录及其 ~/.codeium/windsurf/memories/）。
6. 拒绝符号链接。 直接拒绝符号链接。
7. mtime 窗口。 拒绝在过去 60 秒内修改的文件（可能为活动会话）。--force 可覆盖。
8. 正在运行的进程检查。 如果检测到 Claude Code 进程正在运行，则拒绝执行。--force 可覆盖。
9. Alpha 阶段生产环境门控。 针对默认的 ~/.claude/projects/ 根目录执行 --fix 需要 ，直到 v1.0。

恢复

每个被编辑的文件都有一个包含原始字节的同级 *.bak 文件。撤销某来源所有编辑的最简单方法是：

agentsweep undo                        # 撤销 Claude Code（默认）
agentsweep undo --source codex         # 撤销特定来源
agentsweep undo --root ~/history-copy  # 针对自定义根目录撤销

如果需要手动恢复单个文件（例如你删除了 undo 命令的来源）：

mv session.jsonl.bak session.jsonl

备份文件中包含编辑前的原始内容——明文机密信息，因此在泄露的密钥被轮换且备份被删除之前，一次扫描才算完成。轮换后：

agentsweep purge                       # 删除 Claude Code 备份（会询问）
agentsweep purge --source windsurf     # 删除特定来源的备份
agentsweep purge --yes                 # 非交互式（脚本/CI）

检测内容

191条高置信度模式外加一个经过校验和验证的加密种子短语检测器——BIP-39助记词（12/15/18/21/24个单词；这是BTC、ETH、SOL、BNB、ADA、DOGE、LTC、DOT、AVAX以及几乎所有主流链使用的钱包格式）和Electrum种子会经过加密验证（BIP-39校验和/Electrum版本标签），因此恰好使用钱包单词的英文散文永远不会误报。

这些模式包括：AWS访问密钥、GitHub令牌（PAT/OAuth/App/fine-grained）、Stripe live/test、OpenAI、Anthropic、Google API、Slack bot/user/webhook、Hugging Face、JWT、PEM私钥、包含嵌入密码的数据库URL、npm/PyPI/SendGrid/Twilio令牌——此外还有167条规则移植自gitleaks包，覆盖GitLab、Grafana、HashiCorp Vault/Terraform、DigitalOcean、Shopify、PlanetScale、Databricks、Atlassian、Azure AD、1Password、Sentry、New Relic、Mailgun、Datadog、Twilio、Twitter/X、Twitch、Yandex、JFrog、Snyk、Mailchimp、命令行中的curl凭据以及更多。模式具有高精度——误报很少见，并且提供者上下文规则受关键词门控，因此大型粘贴内容仍能保持快速。

未检测内容

• 没有可识别前缀的自定义/专有机密。
• Monero种子短语（25个单词，来自Monero自己的词表——计划中）。
• 看起来像任意base64的未知令牌。
• 跨多条消息拆分的机密信息。
• 二进制/非UTF-8文件中的任何内容。

要进行更深入的检测，请同时运行 gitleaks 或 trufflehog——它们的规则包更全面。agentsweep的价值在于针对代理历史特定的表面，而不是检测引擎本身。

常见问题

为什么 uvx agentsweep 显示的是旧版本？ uvx会在本地缓存工具。请使用 uvx agentsweep@latest 来始终运行最新版本（推荐），或者使用 uvx --reinstall agentsweep 强制刷新缓存。

OpenCode 在哪里？ OpenCode支持是在v0.1.1中添加的。运行 pip install --upgrade agentsweep 或 uvx agentsweep@latest 以获取它。

agentsweep 会向任何地方发送我的数据吗？ 不会。它完全离线——在扫描或编辑期间不进行任何网络调用。唯一可选的网络调用是后台更新检查，它仅从PyPI获取最新版本号。

贡献者

感谢所有贡献代码、错误报告和想法的人。

许可证

MIT。请参见 LICENSE。