@agents-team/debug-agent

v0.1.1

Published

a month ago

Lightweight code debug agent built on top of pi-coding-agent SDK

0High
0Medium
0Low

aio-lowcode

debug-agent

基于 pi-coding-agent SDK 的轻量代码 debug 服务：常驻 HTTP + SSE 流式 + 网页工作台 + 完整集成 API。

特性

网页工作台（/）：初始化向导 / Dashboard / Chat / KB 复盘 / 历史 / 设置
集成 API（/api/*）：配置 CRUD、Repos、Auth、Session steer/abort、KB 批量
SSE 流式 + Webhook 回调 + OpenAPI 3.0（/docs Swagger UI）
SQLite FTS5 知识库自学习（BM25 检索，零外部依赖）
每条会话完整记录（工具调用、最终结论、KB 引用）
零依赖前端：HTML/CSS/JS 直接以字符串形式 embed 进 server bundle，部署一个 dist 即可

文件布局（单一 BASE_DIR）

所有运行时数据落 $DEBUG_AGENT_BASE_DIR 下（默认 process.cwd()）：

$DEBUG_AGENT_BASE_DIR/
├── config.json            公开配置（model / repos / knowledge / server）
├── auth.json              LLM API keys（落 .gitignore）
├── debug-agent.sqlite     历史 + KB（含 -shm / -wal）
├── sessions/              pi SDK session 日志
└── repos/                 cloned git repos

全部 5 个东西在一个目录里。备份 = tar czf backup.tgz $DEBUG_AGENT_BASE_DIR/。

快速开始

# 1. 安装 + build
npm ci && npm run build

# 2. 初始化（交互式）
npx debug-agent init
# 或非交互：
npx debug-agent init --from config.json --api-key $ANTHROPIC_API_KEY

# 3. 启动常驻服务（默认 :8787）
npx debug-agent serve
# 启动 banner 打印完整 curl 示例和 docs URL

# 4. 打开工作台
open http://127.0.0.1:8787/
# 首次弹窗输入 server.authToken，存 localStorage

网页工作台

| 模块 | 路由 | 功能 | |---|---|---| | Dashboard | #/dashboard | 状态卡 + 待审 KB + 运行中会话 + 最近会话 | | Chat | #/chat | 选 repo 发问；流式显示 token / 工具调用 / KB 命中 / final 结果卡 | | KB 复盘 | #/kb | 列表、过滤、按 repo/status 筛选、批量 approve/reject、软删、编辑、导出 JSON | | 历史会话 | #/sessions | 分页列表 + 详情（含 SSE 重放） | | 设置 | #/settings | 改 Model / API key / Token / KB 参数 / Repo 增删 / 触发 sync |

工作台鉴权复用 server.authToken：浏览器打开后弹出 token 输入框，存到 localStorage 即可。

侧栏 "📖 API docs" 链接会跳到 /docs（server 的 Swagger UI 页面，新窗口打开）。

CLI 命令

| 命令 | 用途 | |---|---| | init [--from <file> --api-key <key>] | 一次性初始化（交互式或非交互） | | serve | 启动常驻 HTTP 服务 | | sync | 拉取所有配置的 repos | | review [--id <kbId> --approve/--reject] | 人工复盘 / 纠错 KB | | chat --repo <name> | 交互 REPL（不开 serve 也能玩） | | openapi [--yaml] | 打印 OpenAPI spec | | doctor | 校验 config + runtime 前置条件 |

配置

环境变量

| 变量 | 默认 | 作用 | |---|---|---| | DEBUG_AGENT_BASE_DIR | process.cwd() | 所有运行时数据落这 | | DEBUG_AGENT_CONFIG | <BASE_DIR>/config.json | 单独覆盖 config 路径（可选） | | PI_CODING_AGENT_DIR | <BASE_DIR>/sessions | 兜底；防止 SDK fallback 到 ~/.pi/agent（容器 EACCES） | | PORT | 8787 | HTTP 端口 | | HOST | 127.0.0.1 | 监听地址（生产 0.0.0.0） |

`config.json` 示例

init 生成在 BASE_DIR/config.json：

{
  "version": 1,
  "model": { "provider": "anthropic", "id": "claude-opus-4-5" },
  "repos": [
    {
      "name": "order-service",
      "url": "[email protected]:acme/order-service.git",
      "auth": { "type": "ssh", "sshKey": "~/.ssh/id_ed25519" },
      "branch": "main",
      "workdir": "./repos/order-service",
      "permissions": {
        "mode": "read-only",          // read-only | read-write
        "bash": {                     // bash 沙箱白名单
          "allow": ["^(git|npm|pnpm|yarn|go|make|pytest|node|python)\\b"],
          "deny":  ["rm\\s+-rf", ":\\(\\)\\s*\\{", "sudo\\b", "curl.*\\|\\s*sh"]
        },
        "network": "deny"             // deny | allow-known
      }
    }
  ],
  "knowledge": {
    "autoExtract": true,
    "reviewRequired": true,           // 抽取后默认进入待 review 队列
    "retrieval": { "topK": 5, "minScore": 0.1 }
  },
  "server": {
    "port": 8787,
    "host": "127.0.0.1",
    "authToken": "..."                // 外部调用 debug 时用的 Bearer
  }
}

auth.json 由 entrypoint 从 ANTHROPIC_API_KEY / OPENAI_API_KEY 等 env 写入，或工作台 Settings 手动存。

KB 条目

{
  "id": "kb_01HXYZ...",
  "repo": "order-service",
  "status": "approved" | "pending" | "rejected",
  "tags": ["p99", "concurrency", "connection-pool"],
  "problem":  "高并发下 P99 飙到 5s",
  "rootCause": "数据库连接池 max=10，并发 100 时请求排队",
  "fix":       "max 调到 50，并加 hikari leak detection",
  "evidence":  ["repos/order-service/src/main/resources/application.yml:14"],
  "repro":     "wrk -t4 -c100 -d30s http://localhost:8080/orders",
  "createdAt": 1718500000000,
  "sourceRecordId": "rec_..."
}

部署

Docker（推荐）

# 1. 准备 .env（API key）
echo "ANTHROPIC_API_KEY=sk-ant-..." > .env

# 2. 第一次启动（会进 BOOTSTRAP 模式）
docker compose up -d
open http://localhost:8787/  # 工作台里跑 wizard 写 config.json

# 3. Ctrl-C + 重启
docker compose restart
# 现在正常启动：监听 8787，workbench + Swagger UI 都能用

docker-compose.yml：

services:
  debug-agent:
    build: .
    image: debug-agent:latest
    container_name: debug-agent
    restart: unless-stopped
    ports: ["8787:8787"]
    environment:
      ANTHROPIC_API_KEY: ${ANTHROPIC_API_KEY:?set ANTHROPIC_API_KEY in .env}
    volumes:
      - agent-data:/var/lib/debug-agent   # 全部运行时数据 = BASE_DIR

volumes:
  agent-data:                            # named volume；备份/迁移只挂这一个

自定义基础镜像（CI/CD 在国内 / 用私库）

docker build \
  --build-arg BASE_IMAGE=docker.m.daocloud.io/library/node:22-bookworm-slim \
  --build-arg NPM_REGISTRY=https://nexus.aimstek.cn/repository/npm-taobao-proxy/ \
  --build-arg APT_MIRROR=mirrors.aliyun.com \
  -t debug-agent:latest .

反向代理 + TLS（生产）

docker-compose.yml 改成只 expose: 8787（不暴露端口），前边挂 Caddy：

debug.example.com {
    reverse_proxy debug-agent:8787
    encode gzip zstd
}

Caddy 自动申请 Let's Encrypt 证书。

备份 / 迁移

# 备份
docker run --rm -v debug-agent_agent-data:/d -v $(pwd):/b alpine tar czf /b/agent-data.tgz /d

# 恢复
docker run --rm -v debug-agent_agent-data:/d -v $(pwd):/b alpine sh -c \
  'cd / && tar xzf /b/agent-data.tgz'

# 整个 BASE_DIR 一个文件

集成到现有系统

用 /api/*（完整 OpenAPI 3.0 文档在 /openapi.json）：

# 生成任何语言的 SDK
npx openapi-typescript http://HOST:8787/openapi.json -o debug-agent.d.ts
npx openapi-generator-cli generate -i http://HOST:8787/openapi.json -g go -o ./client
npx openapi-generator-cli generate -i http://HOST:8787/openapi.json -g python -o ./client

最小集成示例（Node.js）：

const TOKEN = process.env.DEBUG_AGENT_TOKEN;

async function ask(repo, question) {
  const r = await fetch('http://debug-agent:8787/debug', {
    method: 'POST',
    headers: { 'Content-Type': 'application/json', 'Authorization': `Bearer ${TOKEN}` },
    body: JSON.stringify({ repo, question, stream: false }),
  });
  if (!r.ok) throw new Error(`${r.status} ${await r.text()}`);
  const { result } = await r.json();
  return result;
}

CI/CD 集成 — 报错时自动诊断：

# .gitlab-ci.yml
debug-on-failure:
  when: on_failure
  script:
    - |
      curl -X POST http://debug-agent.internal:8787/debug \
        -H "Authorization: Bearer ${DEBUG_AGENT_TOKEN}" \
        -H "Content-Type: application/json" \
        -d "{\"repo\":\"my-service\",\"question\":\"Why is build #${CI_PIPELINE_ID} failing?\",\"stream\":false,\"callback\":\"https://hooks.slack.com/...\"}"

HTTP API 端点

| Method | Path | Auth | 用途 | |---|---|---|---| | GET | / | — | 网页工作台 | | GET | /web/ | — | 同上 | | GET | /healthz | — | Liveness probe | | GET | /docs | — | Swagger UI | | GET | /openapi.json | — | OpenAPI 3.0 JSON | | GET | /openapi.yaml | — | OpenAPI 3.0 YAML | | POST | /debug | Bearer | 发起一次 debug（同步 / SSE / Webhook） | | GET | /sessions | Bearer | 列出历史记录 | | GET | /sessions/{id} | Bearer | 查一条记录 | | POST | /kb/list | Bearer | 列出 KB 条目 | | POST | /kb/{id}/approve | Bearer | 通过 KB | | POST | /kb/{id}/reject | Bearer | 拒绝 KB | | POST | /kb/{id}/edit | Bearer | 改 KB |

集成 API（`/api/*`）

| Method | Path | 用途 | |---|---|---| | GET | /api/status | 服务状态 / auth / 运行中会话 / uptime | | GET/PUT | /api/config | 读/写完整配置（PUT 后 token 立即生效，端口需重启） | | POST | /api/config/regenerate-token | 重发 server token | | GET/POST | /api/config/export, /api/config/import | 配置导入导出 | | GET | /api/providers | 列出支持的所有 LLM provider | | GET | /api/models/{provider} | 列模型 | | GET/POST | /api/repos | 列/新增仓库 | | PUT/DELETE | /api/repos/{name} | 改/删仓库 | | POST/GET | /api/sync, /api/sync/{jobId} | 触发 / 查询同步 | | GET | /api/auth | 查看每个 provider 是否已配 key | | POST | /api/auth | 设置 key（落 BASE_DIR/auth.json） | | DELETE | /api/auth/{provider} | 删除 key | | POST | /api/auth/test | 校验 key / model | | GET | /api/sessions | 列会话（分页 + 过滤） | | GET | /api/sessions/running | 运行中会话 | | GET | /api/sessions/{id} | 单条详情（in-flight 附 live events） | | POST | /api/sessions/{id}/steer | 追加 follow-up（SSE 流） | | POST | /api/sessions/{id}/abort | 中止 | | GET | /api/sessions/{id}/replay | 重放事件流（SSE） | | GET | /api/kb | KB 列表（分页 + 过滤） | | POST/PUT/DELETE | /api/kb/{id}/... | 审核 / 编辑 / 软删 | | POST | /api/kb/batch | 批量 approve/reject | | GET | /api/kb/export | 导出 JSON 备份 |

关键设计取舍

不引入向量库：默认用 BM25 检索（基于 SQLite FTS5），零外部依赖。knowledge.retrieval.embedder 字段可插拔换成真向量检索。
多仓库：每个 repo 独立 AgentSession，避免上下文污染。
可观测性：每个工具调用都被订阅，落到 debug_records 表，事后能完整重放。
可中断：Web 端 SSE 推送；中途换方向调 POST /sessions/:id/steer。
安全：默认 read-only + bash 白名单；token 不写日志，权限粒度到仓库。
零依赖前端：HTML/CSS/JS 直接以字符串形式 embed 进 server bundle，部署一个 dist 即可。
单目录部署：所有运行时数据落 $DEBUG_AGENT_BASE_DIR，备份 / 迁移 / docker volume 都是单 mount。

常见问题

| 现象 | 排查 | |---|---| | 工作台打不开 | curl http://HOST:8787/healthz；看 banner 是否显示 listening | | 401 满天飞 | GET /api/status 看 authRequired；确认 token 与 server.authToken 一致 | | 启动报 "No API key" | 在 .env 或容器 env 设 ANTHROPIC_API_KEY=... | | 工作台显示 wizard | 配置缺失；删 config.json 重新 init | | 卡死进程 | pkill -9 -f "dist/bin/debug-agent" | | 升级后没生效 | docker compose up -d（不会丢失数据）；docker compose down && up -d 强制重建 | | sqlite 锁 | 不要同时跑两个进程指向同一 BASE_DIR | | CI/CD 拉不到 Docker Hub | 加 --build-arg BASE_IMAGE=... 切镜像（见部署章节） |