debug-recorder: 后台自动落盘运行诊断数据,agent 不靠人类上 VM 就能自查
- Dominant language
- TypeScript
- Stars
- 0
- Forks
- 0
- Avg merge
- 1h 7m
- Merged PRs (30d)
- 969
Description
## 背景
#2873 的复盘:deep-agent 假死时**没有任何通道能拿到日志**,两条取证 workflow 拿到的都是空日志,最后靠人类上 VM 贴截图,卡了两小时。根因不只是 runner 权限——是运行时数据本来就**没有被记录到一个 agent 能查询的地方**。人类指令(2026-09-08):构建一个高效的调试模块,把数据记录在后台,一旦出问题 agent 能马上调试,不依赖人类手工。
## 目标
API 进程内置一个 **debug recorder**:
1. 自动记录每个 HTTP 请求(method/path/status/耗时/requestId/userId)、每个未捕获异常(栈 + 请求上下文)、以及业务代码显式打点的事件(agent run 生命周期、kernel 调用、tool call 等),带统一 `traceId` 串联。
2. 数据落在 Postgres 表 `debug_events`(结构化 JSON,环形保留:按条数 + 按时间自动裁剪),进程内先进 ring buffer 异步批量写,不阻塞请求路径;DB 不可用时降级到内存,不影响业务。
3. 提供查询接口 `GET /debug/events`(按 traceId / level / kind / 时间窗 / 文本过滤)和 `GET /debug/traces/:traceId`(一条链路的全部事件按时间排序),仅 org-admin / dev-mode 可访问,响应脱敏(token/密码/authorization 头)。
4. 提供 CLI/脚本 `pnpm harness debug ...` 让 agent 在会话里直接查(走同一 API 或直连 DB)。
5. 文档:`.harness/instructions/observability.md` 加「出问题先查 debug recorder」的操作路径。
## 非目标
- 不替代 OTel/journal;不做 UI 面板(后续迭代)。
- 不改 deep-agent-service 的 Python 侧(#2873 第 2/3 条另议)。
## 验收
- 单测:ring buffer 溢出/降级/脱敏/裁剪;e2e:发一个会 500 的请求,`GET /debug/traces/:traceId` 能看到 request + error 两条事件且栈完整。
- `verify:quick` 全绿;PR 用 `Refs #<本 issue>` 迭代。
Refs #2873
Contributor guide
No contributing guide indexed for this repository
Research direction
Start by locating the API process and its existing request/error instrumentation, then read .harness/instructions/observability.md. Use the stated debug_events schema, /debug/events and /debug/traces/:traceId endpoints, and pnpm harness debug entry point to map the work. Done means the ring-buffer, fallback, retention, redaction, access control, and trace tests pass, the 500-request e2e flow shows request and error events, and verify:quick is green.
Written by the indexing model from the issue text.
Assessment
- Tech stack
- postgresql, typescript
- Domain
- api, backend, databases, devtools, documentation, observability
- Issue type
- Feature
- Difficulty
- 5/5
- Estimated time
- Over a week
- Activity status
- Active
- Clarity
- Mostly clear
- Newbie friendliness
- 30/100