AI代理行为审计工具vigilo：本地无侵入的MCP监控与安全实践

1. 项目概述：为什么我们需要一个AI代理的“行车记录仪”？

如果你和我一样，在日常开发中深度依赖像Cursor或Claude Code这样的AI编程助手，那你一定经历过这样的时刻：早上打开编辑器，发现AI助手在你离开的几小时里，已经自动运行了几十个命令，修改了十几个文件，而你却对这一切“幕后操作”一无所知。它到底改了哪些代码？执行了哪些可能有风险的命令？消耗了多少API令牌？这些疑问，在传统的AI工具工作流里，往往是一笔“糊涂账”。

这就是vigilo诞生的背景。它不是一个新工具，而是一个本地、无侵入的AI代理行为审计与观测平台。你可以把它理解为你AI助手的“行车记录仪”或“黑匣子”。它的核心承诺极其简单：Every tool call your AI agent makes — logged, timed, diff‘d. Nothing sent anywhere.（记录AI代理的每一次工具调用——记录、计时、对比差异。数据绝不外传。）

我最初接触这个项目，是因为一次“事故”。我的Claude Code助手在尝试修复一个依赖问题时，递归地运行了rm -rf命令（幸好是在一个临时目录），并且在我不知情的情况下，向一个我不熟悉的远程仓库推送了代码。事后排查，我完全无法追溯它具体做了什么。这让我意识到，赋予AI如此高的自主权，却没有相应的透明度和审计能力，本身就是一种风险。

vigilo完美地解决了这个痛点。它通过实现一个本地的MCP（Model Context Protocol）服务器，透明地拦截并记录所有通过MCP协议发起的工具调用（如文件读写、命令执行）。对于那些AI助手内置的、绕过MCP的工具（如Claude Code的Read/Write/Bash），它则通过一个轻量级的PostToolUse钩子进行捕获。所有数据都以加密形式存储在本地~/.vigilo/目录下，你可以通过丰富的CLI命令或一个实时的Web仪表盘，清晰地看到AI助手的所有活动轨迹、耗时、代码差异和成本估算。

简单来说，vigilo让你在享受AI自动化带来的效率红利时，依然能牢牢掌握控制权和知情权。这对于严肃的软件开发、团队协作以及对安全有要求的场景，是一个不可或缺的“安全网”。

2. 核心设计思路与工作原理拆解

2.1 无侵入的透明代理架构

vigilo最精妙的设计在于其“无侵入性”。它不需要你修改AI助手（Claude Code或Cursor）的任何一行代码，也不需要你改变现有的工作习惯。其工作原理可以概括为“透明代理”和“钩子捕获”两种模式。

1. MCP服务器模式（核心路径）MCP是Anthropic提出的一种标准协议，旨在让AI模型能够安全、可控地调用外部工具。当AI助手（配置了vigilo作为MCP服务器后）需要调用一个工具时（比如“读取文件src/main.rs”），这个请求不再直接由系统处理，而是先发送给vigilo。

vigilo此时扮演一个“中间人”：

• 第一步：记录。它立即将这次调用的所有元数据记录下来：工具名称、传入的参数、时间戳、当前Git仓库状态（分支、提交哈希）、风险评估等级（如read低风险，exec高风险）。
• 第二步：执行。然后，vigilo将这个调用原封不动地转发给真正的系统去执行（比如实际去读取src/main.rs文件）。
• 第三步：再记录。获取执行结果（成功的内容或错误信息）后，vigilo再次记录结果、耗时，并计算代码差异（对于写操作）。
• 第四步：返回。最后，将执行结果返回给AI助手。

对于AI助手来说，它感知不到vigilo的存在，整个过程与直接调用系统工具没有区别。但所有交互的“账本”已经被完整保存。

2. PostToolUse钩子模式（补充路径）像Claude Code这样的工具，其最核心的Read、Write、Bash、Edit操作是内置的，并不通过MCP。为了捕获这些调用，vigilo利用了AI工具提供的钩子（Hook）机制。当这些内置工具执行完毕后，AI工具会向一个预设的命令（即vigilo hook）发送本次调用的详情。vigilo hook命令接收这些数据，并以同样的格式记录到本地账本中。

这种双管齐下的设计，确保了无论AI助手通过何种方式操作你的系统，vigilo都能将其纳入监控范围。

2.2 安全与隐私第一的设计哲学

作为一个记录你所有开发活动的工具，安全是vigilo的生命线。它的设计充分体现了“零信任”和“隐私优先”的原则。

• 纯本地运行：vigilo的核心是一个本地的CLI工具和MCP服务器。它没有网络监听端口（除了可选的、仅绑定127.0.0.1的仪表盘），没有守护进程，绝不主动连接任何外部服务器。你的所有活动数据从生成、处理到存储，全程都在你的机器上完成。
• 内容加密存储：这是我认为非常关键的一个特性。在首次运行时，vigilo会在~/.vigilo/目录下生成一个唯一的AES-256-GCM加密密钥（encryption.key）。所有可能包含敏感信息的内容，如工具调用的具体参数（ls -la /home/user）、文件读取的原始内容、命令执行的完整输出等，都会用这个密钥加密后存储。而元数据（工具名、时间、风险等级、Git上下文）则保持明文，这样你即使不解密也能了解活动概貌。密钥在内存中使用后会被清零，你也可以通过环境变量VIGILO_ENCRYPTION_KEY提供自己的密钥，实现密钥的集中管理。
• 仪表盘安全隔离：vigilo dashboard启动的Web界面默认只绑定在127.0.0.1（本地回环地址），这意味着只有你本机的浏览器可以访问。它不会暴露在你的局域网或公网上。同时，它还设置了严格的CORS（跨域资源共享）和CSP（内容安全策略）响应头，进一步防止潜在的前端安全风险。
• 明确的例外：唯一需要网络请求的功能是vigilo cursor-usage，它用于获取你在Cursor平台的API使用量和费用估算。这个功能是**选择性加入（opt-in）**的，并且直接使用你本地Cursor客户端已有的认证信息，不会要求你输入额外的密码或密钥。数据流向非常明确和可控。

2.3 数据模型与账本格式

vigilo将数据组织得非常清晰，核心是events.jsonl文件（JSON Lines格式，即每行一个独立的JSON对象）。这种格式易于追加写入，也便于用命令行工具（如jq）进行处理。

一个典型的事件记录可能包含以下字段：

{ “id”: “a1b2c3d4”, “timestamp”: “2024-02-16T17:26:39.123Z”, “session_id”: “df66fc59”, // 一次连续的AI交互会话 “agent”: “claude-opus-4-6”, “tool”: “Bash”, “risk”: “exec”, // 风险等级：read, write, exec, err “arguments”: {“command”: “cargo test”}, // 加密字段 “result”: {“stdout”: “…”, “exit_code”: 0}, // 加密字段 “duration_ms”: 6300, “git”: { “repo”: “my-app”, “branch”: “feature/auth”, “commit”: “23dbb5e” }, “diff”: “+12 -3” // 针对Edit/Write工具 }

基于这个原子化的事件流，vigilo的CLI命令提供了不同维度的聚合视图：

• vigilo view：按**会话（Session）**分组，展示一次完整的AI工作流程，这是最符合人类阅读习惯的视图。
• vigilo stats：全局统计摘要，告诉你总共发生了多少次读写执行、哪些文件和工具最常被访问、各个模型的令牌消耗和成本估算。
• vigilo errors：专门聚焦于错误，帮助你快速定位AI助手在哪里遇到了问题。

这种从原始事件流到高层语义视图的构建，使得vigilo既提供了机器可读的原始数据，也提供了人性化的分析界面。

3. 从零开始：安装、配置与核心命令详解

3.1 安装与环境准备

vigilo使用Rust编写，因此安装非常便捷。官方推荐的一键安装脚本对于大多数用户来说是最快的方式。

一键安装（推荐）打开你的终端，执行以下命令：

curl -fsSL https://raw.githubusercontent.com/Idan3011/vigilo/main/install.sh | bash

这个脚本会自动检测你的操作系统（macOS/Linux），下载对应平台的最新预编译二进制文件，将其放置到你的系统路径（如/usr/local/bin）中，并赋予可执行权限。

注意：如果你对从网络直接运行脚本有安全顾虑，可以先下载该脚本文件，检查其内容后再执行。

curl -O https://raw.githubusercontent.com/Idan3011/vigilo/main/install.sh cat install.sh # 检查脚本内容 bash install.sh

从源码安装（适用于开发者或特定平台）如果你需要最新的开发版功能，或者你的系统架构比较特殊，可以从源码编译安装。前提是你需要安装Rust工具链（rustc和cargo）。

cargo install --git https://github.com/Idan3011/vigilo.git

编译过程可能需要几分钟，完成后vigilo命令同样会出现在你的Cargo二进制目录（通常是~/.cargo/bin）下，请确保该目录在你的PATH环境变量中。

3.2 交互式配置向导：vigilo setup

安装完成后，不要急着使用。最关键的一步是运行配置向导。这是vigilo能开始工作的前提。

vigilo setup

这个交互式命令会引导你完成以下步骤，体验非常流畅：

1. 检测AI工具：它会自动扫描你的系统，寻找已安装的Claude Code和Cursor。在我的机器上，它准确地找到了两者。
2. 配置Claude Code：它会询问你是否要为Claude Code设置MCP服务器和钩子。选择“是”后，它会自动在Claude Code的配置目录（~/.config/claude-code-desktop/）中创建或修改MCP服务器配置文件，将vigilo添加进去。同时，它也会配置PostToolUse钩子，指向vigilo hook命令。
3. 配置Cursor：过程与Claude Code类似，它会修改Cursor的MCP配置文件（位置因系统而异，如macOS在~/Library/Application Support/Cursor/User/globalStorage/下的相关目录）。
4. 生成加密密钥：它会提示你首次运行需要生成加密密钥。强烈建议选择“是”。密钥文件encryption.key将仅存储在~/.vigilo/目录下。请务必备份这个文件！如果丢失，你之前加密的记录将无法解密。当然，你也可以选择稍后通过vigilo generate-key手动生成，或通过环境变量VIGILO_ENCRYPTION_KEY指定一个Base64编码的密钥。
5. 完成：所有配置完成后，向导会给出摘要，并提示你需要重启你的AI编码助手（Claude Code/Cursor），以使新的MCP配置生效。

实操心得：运行setup后，一定要记得重启Claude Code和Cursor！我一开始忘了这一步，疑惑为什么vigilo没有记录到任何事件。重启后，一切立即开始正常工作。另外，vigilo的配置是增量的，你可以随时再次运行setup来添加对新发现的AI工具的支持。

3.3 核心CLI命令实战指南

配置完成并重启AI助手后，你就可以开始使用vigilo了。它的CLI设计得非常直观。下面我结合自己的使用场景，详细解读几个最常用的命令。

vigilo或vigilo view：查看会话日志这是我最常用的命令，它以一种清晰、紧凑的格式展示所有记录到的会话。

vigilo # 或 vigilo view

输出就像项目描述中展示的那样，按会话分组，每个会话显示其ID、时间、项目、模型，以及按时间顺序排列的工具调用列表。每个调用都有图标和颜色标识风险等级（●执行、○读取、◆写入、✖错误），并显示耗时和代码差异。最下方还有该会话的统计汇总（调用次数、读写执行分布、总耗时、令牌消耗和估算成本）。

vigilo stats：全局数据洞察当你想要了解一段时间的总体情况时，这个命令非常有用。

vigilo stats vigilo stats --since 2024-02-01 --until 2024-02-15 # 查看特定时间段 vigilo stats --last 7d # 查看最近7天

它会输出一个漂亮的表格，汇总总会话数、总调用数、错误率、最常使用的工具、最常被访问的文件、各模型的使用量和成本估算。这对于分析AI助手的工作模式、发现高频操作（可能是优化点）以及监控成本特别有帮助。看到“~$69.16 (list pricing)”这样的估算，能让你对AI助手的“消费能力”有个直观认识。

vigilo dashboard：实时可视化监控这是vigilo的“杀手锏”功能。运行后，它会启动一个本地Web服务器（默认端口7847），并在你的浏览器中打开一个仪表盘。

vigilo dashboard # 指定端口 vigilo dashboard --port 9000

这个仪表盘是实时更新的（基于Server-Sent Events）。左侧是会话时间线，用图表展示调用频率、成本和错误随时间的变化。右侧是实时事件流，每一个工具调用都会即时显示出来，你可以按服务器、风险等级、工具类型进行过滤。仪表盘还会自动将相关的对话片段合并成完整的会话，视图非常直观。所有图表都可以交互，点击数据点可以下钻查看详情。

注意事项：仪表盘默认绑定127.0.0.1，非常安全。如果默认端口被占用，vigilo会友好地提示你换一个端口。你可以放心使用，无需担心网络暴露风险。

vigilo diff：审查代码变更这个命令对于代码审查至关重要。它可以展示指定会话中所有文件的更改差异。

vigilo diff --last 1 # 显示最近一次会话的diff vigilo diff --session df66fc59 # 显示特定会话ID的diff

输出是标准的git diff格式，清晰地展示了AI助手对每一行代码的增删改。这让你在AI提交代码或发起Pull Request之前，能进行一次高效的人工复核，确保变更符合预期，没有引入奇怪的“AI风格”代码或错误。

vigilo cursor-usage：Cursor用量与成本分析这个命令专门用于连接Cursor的API（需要你的本地Cursor客户端已登录），获取你账户近30天的令牌使用情况和费用估算。

vigilo cursor-usage

它会展示你的订阅计划、剩余请求数，并按模型详细列出输入/输出令牌数、缓存读写量以及根据Cursor官方定价估算的费用。这对于管理团队预算或个人使用成本是一个极好的工具。

其他实用命令

• vigilo tail：查看最新的事件（扁平列表），适合快速检查刚刚发生了什么。
• vigilo watch：实时“尾随”模式，在终端中实时打印新产生的事件，像tail -f一样。
• vigilo errors：专门列出所有出错的事件，并按工具分组，方便集中排查问题。
• vigilo doctor：诊断你的vigilo配置和运行环境是否健康，连接是否正常。
• vigilo export：将所有事件导出为CSV格式，方便你用Excel或Numbers进行更深度的自定义分析。

4. 高级配置、数据管理与维护

4.1 配置文件与环境变量

vigilo的配置主要存储在~/.vigilo/config文件中。这个文件通常由vigilo setup自动生成和管理，但你也可以手动编辑。一个典型的配置包含MCP服务器列表和钩子命令路径。

更灵活的配置方式是通过环境变量：

• VIGILO_DATA_DIR：指定数据目录，默认为~/.vigilo。你可以将其改为其他路径，例如一个同步的云盘目录，以实现多台机器间的记录同步（注意加密密钥也需要同步）。
• VIGILO_ENCRYPTION_KEY：指定一个Base64编码的AES-256-GCM密钥。如果你需要在多台机器间共享加密数据，或者想使用自己密钥管理系统的密钥，可以通过这个变量设置。如果不设置，vigilo将使用data_dir下的encryption.key文件。
• VIGILO_LEDGER_PATH：直接指定账本文件events.jsonl的路径，覆盖默认位置。
• VIGILO_LOG_LEVEL：设置日志级别（如debug,info,warn,error），用于排查问题。

4.2 数据文件管理与清理

随着使用，events.jsonl文件会不断增长。vigilo采用了日志轮转（Log Rotation）机制来管理文件大小。

• 自动轮转：当当前账本文件达到一定大小（默认约10MB）时，vigilo会自动将其重命名为events-<timestamp>.jsonl，并创建一个新的events.jsonl文件。这保证了单个文件不会过大，影响读写性能。
• 手动清理：旧的轮转文件会一直保留。你可以使用vigilo prune命令来删除它们。

  vigilo prune --keep-days 30 # 删除30天前的轮转文件 vigilo prune --keep-files 5 # 只保留最新的5个轮转文件

  定期运行prune可以防止磁盘空间被历史数据无限占用。建议将此命令加入你的crontab或系统定时任务中。

4.3 加密、备份与迁移

密钥管理是重中之重。~/.vigilo/encryption.key文件是你所有加密记录的“钥匙”。务必将其备份到安全的地方（如密码管理器或加密的云存储）。如果丢失，历史加密内容将无法恢复。

备份整个数据目录：最简单的备份方式就是打包整个~/.vigilo/目录。因为密钥和数据在一起，恢复时只需解压到相同路径即可。

迁移到新机器：

1. 在新机器上安装vigilo。
2. 将旧机器的~/.vigilo/目录完整地复制到新机器的相同位置。
3. 确保文件权限正确（用户可读）。
4. 在新机器上运行vigilo doctor检查配置健康状态。
5. 重新配置AI工具的MCP设置（或直接复制对应的配置文件），因为MCP服务器路径可能与机器相关。

4.4 集成与自动化

vigilo的产出（如stats输出、export的CSV）可以很容易地集成到你的自动化流程中。

例如，你可以创建一个每日运行的脚本，将vigilo stats的输出追加到一个日志文件中，用于长期趋势分析：

#!/bin/bash echo “=== $(date) ===" >> ~/vigilo_daily_stats.log vigilo stats --last 1d >> ~/vigilo_daily_stats.log echo “” >> ~/vigilo_daily_stats.log

或者，你可以设置一个监控，当vigilo errors检测到特定高风险工具（如rm,chmod）出现错误时，发送一个通知（如桌面弹窗、邮件）给你，让你能立即介入检查。

5. 常见问题排查与实战经验分享

在实际使用vigilo的几个月里，我遇到并解决了一些典型问题。这里分享出来，希望能帮你绕过这些坑。

5.1 问题：vigilo启动后没有记录到任何事件

可能原因及排查步骤：

1. AI助手未重启：这是最常见的原因。修改MCP配置后，必须完全退出并重启Claude Code或Cursor，新的配置才会生效。仅仅关闭窗口可能不够，需要从任务栏/活动监视器中彻底退出进程。
2. 配置未正确应用：运行vigilo doctor检查配置。它会验证MCP服务器配置文件和钩子配置是否存在且格式正确。如果doctor报错，可以尝试重新运行vigilo setup。
3. 权限问题：确保vigilo二进制文件有可执行权限，并且你对~/.vigilo目录有读写权限。
4. 查看日志：设置环境变量RUST_LOG=vigilo=debug然后运行vigilo，或者查看AI助手自身的日志（如果它们有提供），看是否有连接vigilo失败的错误信息。

5.2 问题：vigilo dashboard无法打开或页面空白

可能原因及排查步骤：

1. 端口冲突：默认端口7847可能被其他程序占用。尝试指定另一个端口：vigilo dashboard --port 9000。vigilo在端口被占用时会自动提示可用的端口。
2. 浏览器缓存：尝试使用浏览器的无痕模式打开，或强制刷新页面（Ctrl/Cmd + Shift + R）。
3. 防火墙/安全软件：极少数情况下，本地回环地址的特定端口可能被安全软件阻止。检查相关设置。
4. 检查控制台输出：运行vigilo dashboard时，终端会输出访问URL。确保你访问的正是这个URL（通常是http://127.0.0.1:7847）。

5.3 问题：vigilo cursor-usage命令报错或没有数据

可能原因及排查步骤：

1. Cursor未登录或已过期：该命令需要有效的本地Cursor认证。请确保你的Cursor桌面客户端处于已登录状态。
2. 网络问题：该命令需要访问Cursor的API。检查你的网络连接，并确保没有阻止对cursor.com域名的访问。
3. API限制或变更：Cursor的API可能会有更新。如果之前正常，突然失效，可以查看vigilo的GitHub仓库的Issue页面，看是否有类似问题或新版本发布。

5.4 性能与资源占用考量

• 对AI助手性能的影响：vigilo的日志记录是异步和非阻塞的。工具调用的执行路径几乎没有额外开销，因为记录动作发生在调用前后，且写入本地文件是很快的。在我的M1 MacBook Pro上，完全感知不到因vigilo引入的延迟。钩子模式更是仅在工具执行完成后才被触发，对执行过程零影响。
• 磁盘空间占用：加密的日志文件比纯文本要小一些。在我的日常使用强度下（每天数十个会话，数百次调用），一周产生的数据量大约在几MB到十几MB。通过定期使用vigilo prune清理旧文件，可以轻松管理磁盘占用。
• 内存占用：vigilo作为命令行工具，仅在执行命令时占用内存。vigilo dashboard作为长期运行的Web服务器，内存占用也很小，通常只有几十MB。

5.5 我的实战经验与技巧

1. 将vigilo view集成到日常流程：我习惯在结束一段长时间的AI辅助编程后，运行一下vigilo view --last 1，快速回顾一下刚才AI都做了什么。这就像飞机降落后机长查看飞行记录一样，能让你对工作成果有更全面的把握。
2. 利用diff进行代码审查：在让AI执行大规模的代码重构或生成新模块后，我一定会用vigilo diff仔细检查变更。AI生成的代码有时会引入一些不必要的抽象或奇怪的注释，手动审查一遍能有效提升代码质量。
3. 关注stats中的“高频文件”和“高频工具”：这能反映出你项目中的热点区域或AI的常用操作模式。例如，如果Bash工具调用异常频繁，可能意味着你的项目构建/测试流程比较复杂，可以考虑编写一些脚本让AI直接调用，而不是反复执行零散的Bash命令。
4. 成本意识培养：vigilo stats和vigilo cursor-usage提供的成本估算非常直观。看着数字的增长，你会自然而然地思考：这个重构值得消耗这么多令牌吗？有没有更高效的方式向AI描述问题？这有助于你更精明地使用AI资源。
5. 错误是学习的机会：不要忽视vigilo errors。AI助手犯的错误往往揭示了项目环境配置的模糊之处、文档的缺失，或者你提示词（prompt）的不精确。分析这些错误，能帮助你优化与AI协作的上下文和指令。

vigilo从一个解决具体痛点（AI操作不透明）的工具，已经逐渐演变成了我开发工作流中一个不可或缺的“观察层”。它带来的不仅仅是安全感，更是一种可观测性（Observability），让我能定量、定性地分析和优化我与AI助手之间的协作效率。对于任何严肃使用AI编程助手的开发者来说，我认为这都是一款值得投入时间配置和使用的基石型工具。它的设计哲学——本地优先、隐私至上、无侵入集成——也代表了开发者工具一个非常正确的发展方向。