外观主题
阅读语言

Agent Debug Bridge —— 智能体调试桥，全量落库可回放

人工智能 创意 3天前 更新于 20小时前
https://yxp.hk/p/dqfImm

📦 开源仓库：yxpil/ADB

gh-card · yxpil/ADB

📦 仓库名片 · Powered by gh-card

ADB — Agent Debug Bridge

智能体调试桥梁：一个零依赖的 Node.js 转发代理，把 Agent（或任意 SDK）的 API 请求
转发到你随便指定的上游，同时全量、不中断地记录每一笔请求/响应到 SQLite，
并提供会话分组、统计分析与黑白圆角简约风格的 Web 面板。

  • 流式转发：SSE 逐事件透传，客户端收到的字节与上游产生的字节逐字节一致（多字节字符跨 TCP 分块安全）
  • 全量记录：请求/响应体不截断（大体积经临时文件 spool 落盘），SSE 存完整 transcript 与精确事件数
  • 随便填上游：请求头（URL 或预设名）、路径前缀、默认目标三种方式，面板设置页随时改
  • 虚拟调试：内置虚拟 MCP 服务器、人工扮演 AI（manual）、虚拟 E2E 场景端点（见下文「调试 BIT」）
  • 会话分析：按 session_id 分组统计 token 用量、错误数、SSE 流数；统计按模型 / 目标 / 工具 / 日期聚合
  • 零依赖：仅用 Node.js 内置模块（含 node:sqlite），无需 npm install

与 BIT 配合使用：BIT 侧怎么填、请求怎么发、API 规范与数据隐私的图文说明，见 BIT 开发者文档
osbt.space/docs（本文档与其互相引用：BIT 文档的「ADB 调试桥」章节即指向本 Wiki）。

环境要求

  • Node.js >= 22.5.0（需要内置 node:sqlite）

启动

node server.js              # 默认监听 8987（仅绑定 127.0.0.1）
PORT=9000 node server.js    # 自定义端口
ADB_DB=./my.db node server.js   # 自定义 SQLite 路径（默认 data/adb.db，WAL 模式）

打开面板：http://127.0.0.1:8987

面板导览

页签 内容
请求 全部记录流水：分类标签过滤、关键词/会话/状态筛选，点开单条查看完整请求头/响应头/请求体/响应体（SSE 存完整 transcript）
会话 按 session_id 分组：笔数、token 用量、错误数、SSE 流数，快速定位一轮完整对话
统计 总量/错误率/耗时/token 聚合，按模型 / 目标 / 工具 / 日期分组
虚拟 调试 BIT 专属：待应答队列（人工扮演 AI / 人工应答 MCP 工具）、虚拟 MCP 自定义工具编辑、BIT 接入指引
BIT 联动控制 BIT：连接配置（地址 / Client Key / 访问密码）、运行快照、工具注册表、MCP 服务器、会话浏览、审计日志，可直接发送对话与调用工具
设置 默认转发目标、预设名列表、AI 主动发消息（注入系统指令）开关与文本、清空记录

调试 BIT（三种玩法）

ADB 面板新增「虚拟」页，专为 BIT 用户设计——不用改 BIT 代码，填个地址就能调试问题、
分析问题、报告问题。

1. 虚拟 MCP 服务器

BIT「设置 → MCP 服务器」里把服务器 URL 填成：

http://127.0.0.1:8987/mcp

完全遵循 Streamable HTTP / JSON-RPC 2.0（initialize 握手 → Mcp-Session-Id →
notifications/initialized → tools/list → tools/call），与 BIT 的 MCP 客户端完全兼容。

  • 内置工具：echo（回显）/ add（加法）/ now（时间）
  • 面板「虚拟」页可添加自定义工具：
    • fixed 模式：返回你预设的固定结果——模拟任意工具行为，观察 AI 拿到结果后

🛠 技术栈与开发

  • 开发语言：JavaScript（Node.js ≥ 22.5），零 npm 依赖——只用内置模块，含 node:sqlite 落库
  • 存储：SQLite（WAL 模式）全量记录，大体积响应经临时文件 spool，绝不截断；SSE 存完整 transcript 与精确事件数
  • 转发内核：原生 http 代理 + SSE 逐事件透传，客户端收到的字节与上游逐字节一致（多字节字符跨 TCP 分块安全）
  • 面板：内置零构建 Web 控制台（黑白圆角简约风），请求/会话/统计/虚拟/BIT/设置六个页签

📚 文档与链接

  • 仓库：https://github.com/yxpil/ADB（Wiki 含 BIT 调试图文）
  • 与 BIT 的配合规范见 BIT 开发者文档：https://osbt.space/docs（双方文档互相引用）
  • 上手：node server.js → 打开 http://127.0.0.1:8987，默认仅绑 127.0.0.1