AI 编码 Agent 黑盒问题如何解决？AgentProbe 实时可观测性实战

当你使用 Cursor、Claude Code 或 OpenCode 编写代码时，Agent 在后台做了什么？它在搜索文件、读取代码库，还是正在执行危险的命令？如果 Agent 卡住了，你只能看到终端里的等待提示符——这就是 AI 编码 Agent 的「黑盒问题」。

传统的 LLM 可观测性工具（如 LangSmith、AgentOps）需要你在代码中主动埋点插桩。但问题是：你并不拥有 Cursor 或 Claude Code 的内部代码。你无法修改它们的 LLM 调用链来插入 instrumentation。

AgentProbe 正是为解决这个问题而生的开源方案。

AgentProbe 是什么？

AgentProbe 是一个 TypeScript 库，通过被动可观测性（Passive Observability） 技术，将 AI 编码 Agent 的转录文件（transcripts）转化为标准化的实时事件流。它不需要修改 Agent 工具本身的代码，也不需要接入 LLM API——只需读取 Agent 已经留下的日志痕迹。

目前支持四大主流 AI 编码工具：

• Cursor — 解析本地 transcript 文件
• Claude Code — 读取 session 记录
• Codex — 解析 JSONL session 文件
• OpenCode — 读取 SQLite 数据库

项目采用 MIT 开源协议，可通过 npm 安装：@agentprobe/core。

快速体验：监控你的 Agent

安装 AgentProbe 只需要一行命令：

npm install @agentprobe/core

然后几行代码就能启动实时监控：

import { createObserver } from "@agentprobe/core";

const observer = createObserver({
  workspacePaths: ["/Users/me/my-project"],
});

observer.subscribe((event) => {
  console.log(`[${event.agent.id}] ${event.change.kind} → ${event.agent.status}`);
});

await observer.start();

// 当 agent 启动时会输出：
// [cursor-1] joined → running
// [cursor-1] statusChanged → idle
// [cursor-1] left → completed

createObserver 默认启用所有四个内置 Provider（Cursor、Claude Code、Codex、OpenCode），开箱即用。你只需要指定工作目录路径，AgentProbe 会自动发现并监控该目录下所有 AI 编码工具的活动。

被动可观测性：不插桩，也可见

AgentProbe 的核心设计理念是不依赖主动埋点。每个 AI 编码工具都会在本地留下运行痕迹：

• Cursor 在 ~/.cursor/transcripts/ 中保存操作记录
• Claude Code 在 ~/.claude/sessions/ 中记录 session 信息
• Codex 输出 JSONL 格式的运行日志
• OpenCode 使用 SQLite 数据库存储会话

AgentProbe 的 Provider 层负责发现这些文件路径、解析格式、提取状态变更。上层的事件总线（event bus）则负责将原始文件变更转化为生命周期事件。

状态机驱动的事件流

AgentProbe 内部实现了一个精心设计的状态机，确保事件按顺序处理，不会出现竞态条件：

stopped → starting → started → stopping → stopped
     ↑                        ↓
    start()               stop()

在 started 状态下，运行时的核心工作流如下：

1. file-changed：fs.watch 检测到转录文件变更，去抖后读取快照
2. check-idle：定时器重新读取快照，检测 running → idle → completed 等时间驱动状态转换
3. refresh-requested：手动刷新，立即读取当前快照

所有事件串行处理（无重叠读取），订阅者仅在 Agent 状态实际变更时收到通知。心跳周期不产生噪声，内部轮询对外透明。

配置参数

AgentProbe 提供了灵活的配置选项：

const observer = createObserver({
  workspacePaths: ["/path/to/project"],
  providers: ["cursor", "claude-code"], // 只启用指定 Provider
  debounceMs: 500,     // 文件变更去抖时间（毫秒）
  checkIdleDelayMs: 2000, // 空闲检测间隔
});

• debounceMs：控制文件变更事件的收集窗口，适合高频写入场景
• checkIdleDelayMs：Agent 停止活动后多久标记为 idle，设为 false 可禁用自动空闲检测
• providers：选择性启用特定工具，减少不必要的文件监听

实战场景：开发者面板

AgentProbe 的 examples 目录 提供了 9 个完整示例，从最小化的 Observer 到终端仪表盘再到 macOS 浮动叠加层。

想象这样一个场景：你在 Claude Code 中运行一个大规模重构任务。传统做法是盯着终端干等，不知道 Agent 正在做什么。用 AgentProbe 可以搭建一个实时状态面板：

import { createObserver } from "@agentprobe/core";

const observer = createObserver({
  workspacePaths: [process.cwd()],
});

const agents = new Map();

observer.subscribe((event) => {
  const id = event.agent.id;
  if (event.change.kind === "joined") {
    agents.set(id, { ...event.agent, startTime: Date.now() });
    console.log(`🚀 Agent ${id} 开始工作`);
  } else if (event.change.kind === "statusChanged") {
    agents.set(id, { ...agents.get(id), status: event.agent.status });
    console.log(`⏳ Agent ${id}: ${event.agent.status}`);
  } else if (event.change.kind === "left") {
    const elapsed = Math.round((Date.now() - agents.get(id).startTime) / 1000);
    console.log(`✅ Agent ${id} 完成，耗时 ${elapsed}s`);
    agents.delete(id);
  }
});

await observer.start();

// 输出示例：
// 🚀 Agent claude-1 开始工作
// ⏳ Agent claude-1: running
// ⏳ Agent claude-1: idle
// ✅ Agent claude-1 完成，耗时 45s

这个模式非常适合 CI/CD 场景或需要批量运行多个 Agent 任务的开发者。

与现有方案的对比

AgentProbe 最大的优势就是无需修改任何代码。它可以监控所有已经在使用的 AI 编码工具，即使这些工具是闭源的。

技巧和最佳实践

1. 结合 CI/CD 使用

在 CI 流水线中，可以用 AgentProbe 观察 Agent 任务是否卡住超过预期时间，自动发送告警：

const timeout = setTimeout(() => {
  console.error("❌ Agent 超时！");
  observer.stop();
  process.exit(1);
}, 300_000); // 5 分钟超时

2. 多项目并行监控

传入多个工作区路径可以同时监控多个项目的 Agent 活动：

createObserver({
  workspacePaths: ["/projects/frontend", "/projects/backend", "/projects/api"],
});

3. 自定义 Provider

如果你使用自定义的 AI 编码工具，可以实现自己的 Provider 来接入 AgentProbe 的事件系统。只需实现 Provider 接口，提供文件的发现、解析和变更订阅能力。

4. 选择合适的事件粒度

对于日常开发，默认配置已经够用。如果在高频写入场景（如 Cursor 连续补全），可以适当提高 debounceMs 减少事件频率。

结语

AI 编码 Agent 正在快速成为开发者工作流的核心组成部分，但它们的透明度和可观测性远落后于传统工具。AgentProbe 通过被动可观测性的创新方案，让开发者无需改变工具链就能获得 Agent 运行状态的实时可见性。

如果你正在将 Cursor、Claude Code 等 AI 编码工具纳入日常工作流程，AgentProbe 是一个值得关注的开源项目——它让黑盒变透明，让不可见变可见。

项目地址：https://github.com/vtemian/agentprobe 详细博文：https://blog.vtemian.com/project/agentprobe/