Lujo-MCP API 参考手册

September 25, 2026 · View on GitHub

当前版本：v0.9.4（已发布稳定版）/ v0.9.5（代码库候选/未发布，2026-09-24）。npm 线上最新已发布稳定版本为 v0.9.4；虚拟帧扫描守卫核心修复已合入 main 分支（commit 390849f / 2dc9c1c），相关候选内容已进入 main（commit e39aeb7）；v0.9.5 仍待发布（强化 Trae / Cursor 智能体协同体验与防超时）。公开工具面、REST 契约与数据库 schema 不变。上一版 v0.9.4 为运行时上下文断层修复与端点收敛。本文档覆盖 Lujo-MCP 对外暴露的 REST API、MCP 工具，以及 Node SDK 的客户端契约。接口清单以代码为准；启动后可用 GET /mcp（非 SSE）查看协议元信息，GET /health 查看运行状况。

1. 鉴权与角色（RBAC）

Lujo-MCP 采用 fail-closed（默认拒绝） 的 API Key 鉴权：

请求头：Authorization: Bearer <key> 或 X-API-Key: <key>（二者等价，Authorization: Bearer 优先）。
仅当 sendBeacon / EventSource 等无法自定义 header 的场景，允许 ?token=<beacon短时令牌> 或 ?api_key= 查询参数降级（不推荐长期使用）。
未配置任何 API_KEY 时 = 不鉴权（仅限内网/回环使用；绑定非回环地址会启动校验拒绝或告警）。

⚠️ 前端安全性与 CORS 规范：

安全警告：若在前端页面引入 Browser SDK 时填入 apiKey，该密钥会直接暴露给所有页面访问者与客户端代码，严禁将高权限/共享服务端密钥直接写入公开前端代码。需要注意：所有 /ingest/* 数据接入端点硬性要求 admin 或 developer 角色（viewer 角色会被 403 拒绝），系统不存在可用于浏览器上报的“只读 Key”或“仅上报 Key”。本地回环（127.0.0.1）开发推荐免 key 运行；若必须在远程/容器网络开启鉴权，应当由服务端应用代理（如 BFF 或反向代理）保管密钥并限制转发上报路由，避免直接把高权限/共享服务端密钥写进公开前端。

跨域 CORS：当被调试页面与 Lujo-MCP 服务端不在同一端口（例如页面在 http://localhost:3000、服务在 http://127.0.0.1:8000）时，浏览器在发送上报前会发起 OPTIONS 预检。服务端必须配置 CORS_ORIGINS 包含前端源，否则预检失败导致上报被拦截。

三角色分级（RBAC_ENABLED=true 时生效）：

角色	权限
`admin`	完全控制（含诊断端点 `/api/debug/echo`、`/api/debug/token`）
`developer`	读 + 写（调试、修复、验证、规范 CRUD、数据接入）
`viewer`	只读（Dashboard、上下文查询、trace 查询、修复结果轮询）

RBAC_ENABLED=false（默认）时，所有 key 视为 admin（向后兼容）。
未在 RBAC_ROLE_MAPPING 中映射的 key，默认 viewer（fail-closed，防配置遗漏越权）。

2. REST API

每个端点标注了所需最低角色。请求/响应均为 JSON；Content-Type: application/json。

2.1 调试 `/api/debug`

方法	路径	角色	说明
POST	`/api/debug/run`	developer	执行调试流程：记录请求 → 处理 → 构建上下文
POST	`/api/debug/analyze`	developer	对指定 request_id 做 LLM 根因分析
POST	`/api/debug/analyze/stream`	developer	流式 LLM 分析（SSE）
POST	`/api/debug/analyze/async`	developer	异步 LLM 分析（削峰队列，返回 job_id）
GET	`/api/debug/analyze/result/{job_id}`	viewer	查询异步分析任务状态/结果
POST	`/api/debug/repair/async`	developer	异步生成修复方案（AI Debug Agent；有效 Agent 模式非 `off`，显式 `AGENT_MODE` 优先，未显式时兼容旧布尔开关）
GET	`/api/debug/repair/result/{job_id}`	viewer	查询异步修复任务状态/结果
GET	`/api/debug/runtime`	viewer	获取当前进程运行时快照（CPU/内存/线程）
GET	`/api/debug/session`	viewer	列出活跃调试会话
POST	`/api/debug/verify`	developer	比对实际结果 vs 期望规范，检测静默失败
POST	`/api/debug/verify/ui`	developer	Playwright 按 UI 规范自动遍历并验证（FR14）
GET	`/api/debug/health`	viewer	调试健康检查（`{"status":"ok","timestamp":...}`）
GET	`/api/debug/prompt?request_id={id}`	viewer	生成纯文本调试提示词（FR12，非 MCP 场景一键复制；模板可经 `PROMPT_TEMPLATE_PATH` 自定义）
POST	`/api/debug/sourcemap`	developer	上传 Source Map（v0.5.1，需 `SOURCEMAP_ENABLED=true`）
POST	`/api/debug/echo`	admin	回显请求体（需 `DEBUG_ENDPOINTS_ENABLED=true`）
GET	`/api/debug/token`	admin	探测响应脱敏的测试端点（需 `DEBUG_ENDPOINTS_ENABLED=true`）

POST /api/debug/run 示例：

// 请求
{ "payload": { "user_id": 1 }, "metadata": { "trace_kind": "debug" } }

// 响应（节选）
{
  "request_id": "req-xxx",
  "result": { "echo": { "user_id": 1 }, "status": "success" },
  "trace": [ { "timestamp": ..., "step": "request_start", "data": {...} } ],
  "context": { ... }
}

POST /api/debug/verify 示例：

// 请求：actual 为实际结果，spec 为期望（或传 spec_id）
{
  "actual": { "status_code": 200, "body": {"data": null} },
  "spec": { "kind": "api", "target": "POST /login",
            "expect": { "body": { "data": {"type": "object", "required": true} } } },
  "trace_id": "req-xxx"
}

// 响应
{ "matched": false, "diffs": [{ "field": "body.data", "expected": "object", "actual": null }], "silent_failure": true }

GET /api/debug/prompt?request_id=req-xxx 示例（FR12，v0.5.5）：

// 响应：prompt 为可一键复制的纯文本提示词
{
  "request_id": "req-xxx",
  "prompt": "你是一位资深排障专家。以下是程序运行时的调试上下文，请分析并定位问题根因：\n\n== 调试上下文（request_id: req-xxx）==\n\n请求 ID: req-xxx\n执行流程: request_start → processing → error\n异常详情: {\n  \"type\": \"ValueError\",\n  \"message\": \"bad value\",\n  ...\n}\n\n请基于以上上下文给出分析结论，包括：..."
}

说明：prompt 字段内容 = 完整调试上下文（异常帧/源码片段/运行时/git 归因等）经脱敏 + 截断后的纯文本渲染；可直接粘贴给任意 AI 助手。默认使用内置模板，可用 PROMPT_TEMPLATE_PATH 指定自定义模板文件（占位符 $context / $request_id）。

2.2 数据接入 `/ingest`

供 Browser SDK、Node SDK、外部服务和其他非 Python 运行时直接上报原始数据，入库前统一脱敏。Browser SDK 负责浏览器自动采集；Node SDK 只提供服务端显式上报，不依赖 DOM 或浏览器全局对象。

方法	路径	角色	说明
POST	`/ingest/network`	developer	单条网络请求记录上报
GET	`/ingest/network/{trace_id}`	viewer	查询某 trace 关联的网络记录
POST	`/ingest/silent-failure`	developer	上报前端静默失败（含 UI 事件链 + 网络链）
POST	`/ingest/error`	developer	任意语言主动上报异常（不限于 Python）
POST	`/ingest/console`	developer	上报浏览器控制台日志
POST	`/ingest/ui-event`	developer	上报 UI 交互事件
POST	`/ingest/batch`	developer	批量上报（事件数组，单次 ≤100 条，支持 gzip）

POST /ingest/batch 示例（V5，支持 Content-Encoding: gzip）：

{
  "events": [
    { "path": "/ingest/error", "payload": { "exc_type": "TypeError", "message": "...", "frames": [] } },
    { "path": "/ingest/network", "payload": { "record": { "method": "GET", "url": "/api/x" } } }
  ]
}
// 响应
{ "results": [ { "path": "/ingest/error", "ok": true, "result": {...} }, ... ], "count": 2 }

2.3 控制台 `/api/dashboard`

方法	路径	角色	说明
GET	`/api/dashboard/stats`	viewer	控制台概览统计（trace 数 / 静默失败数 / 异常数 / 规范数）
GET	`/api/dashboard/kb-stats`	viewer	KB 学习闭环统计：条目总数 / seed vs llm 来源分布 / 学习占比 / 重复验证条数 + 闭环指标快照（kb_hits/kb_writeback/kb_experience_recall，进程级累计；store 为空返回零值）
GET	`/api/dashboard/traces?limit=100`	viewer	列出最近 traces（limit 1–1000）
GET	`/api/dashboard/trace/{trace_id}`	viewer	trace 详情（含 spec_diffs + quality_report）
GET	`/api/dashboard/trace/{trace_id}/quality`	viewer	单独获取 trace 质量报告
GET	`/api/dashboard/specs`	viewer	列出所有已存规范
GET	`/api/dashboard/stream`	viewer	Dashboard 实时 SSE 推送（需 `DASHBOARD_SSE_ENABLED=true`）
GET	`/api/dashboard/errors/aggregated`	viewer	按指纹聚合错误统计
GET	`/api/dashboard/errors/ranked`	viewer	按影响程度排序错误
GET	`/api/dashboard/errors/history`	viewer	查询错误历史（memory 进程内最近记录；历史长期持久化已随 PostgreSQL 后端移除而不再提供）

2.4 规范 CRUD `/api/spec`

方法	路径	角色	说明
POST	`/api/spec`	developer	创建一条期望规范
GET	`/api/spec?kind=&target=`	viewer	列出规范（可按 kind/target 过滤）
GET	`/api/spec/{spec_id}`	viewer	取一条规范
PATCH	`/api/spec/{spec_id}`	developer	部分更新规范（id 不可修改）
DELETE	`/api/spec/{spec_id}`	developer	删除一条规范

2.5 MCP 传输 `/mcp`

符合 MCP Streamable HTTP 规范：

方法	路径	说明
POST	`/mcp`	客户端 → 服务端消息（`initialize` / `tools/list` / `tools/call` / 通知）
GET	`/mcp`	`Accept: text/event-stream` 时返回 SSE 长连接；否则返回服务健康信息
DELETE	`/mcp`	终止会话（携带 `Mcp-Session-Id`）

会话经 Mcp-Session-Id 响应头维护；initialize 总是新建会话（防会话固定）。

2.6 令牌签发 `/auth`

方法	路径	角色	说明
POST	`/auth/beacon-token`	viewer	换取短时 beacon 令牌（供 `sendBeacon`/`EventSource` 场景，避免永久 Key 进 URL）

3. MCP 工具

可选依赖：auto_test / verify_ui 依赖 Playwright。运行时缺少该依赖时，它们不会出现在 tools/list；如果客户端已经缓存了工具名而直接调用，服务端仍会返回结构化失败结果并标记 isError=true。

工具经 HTTP（POST /mcp → tools/call）或 stdio 传输调用。HTTP 传输下受 RBAC 工具级门控（见每项「角色」）。类别含义：agent = 供 AI Agent 调用的查询/分析/验证类；sdk = 供 Browser SDK 上报的数据采集类。

tools/list 口径（v0.7.3）：tools/list 默认只暴露 agent 类工具（含下表全部查询/验证工具与三个近期错误查询工具）；sdk 类上报工具不进 tools/list，但 tools/call 按名调用仍然有效（REST/SDK 上报链路不受影响）。工具清单以 tools/list 实际返回为准，勿以本文档数目为准。

3.1 查询 / 分析类工具（agent）

工具名	角色	说明
`diagnose_issue`	viewer	统一诊断入口（优先调用）：无需 request_id 自动定位最近错误并返回完整调试上下文；支持 query 关键词 / request_id 精确查询
`list_recent_traces`	viewer	列出近期错误摘要（trace_id/类型/消息/时间/top_frame）
`search_logs`	viewer	按关键词搜索近期错误（类型/消息匹配，含发生次数）
`debug`	developer	执行完整调试流程，返回结构化调试上下文
`context`	viewer	按 request_id 获取调试上下文（流程/输入输出/错误）
`trace`	viewer	获取请求完整原始追踪日志
`stacktrace`	viewer	获取错误堆栈（含源码片段）：无 request_id 时自动返回最近一次捕获的错误
`get_network_trace`	viewer	查询某 trace 关联的网络请求记录
`get_blame_for_frame`	viewer	查询文件/行最后一次的修改 commit（git blame）
`get_recent_diff`	viewer	返回文件最近 N 次 commit 的 diff
`get_related_specs`	viewer	按文件路径返回相关项目规范片段
`ingest_specs`	developer	OpenAPI/Swagger 一键生成断言规范并入库，激活静默失败自动校验（同 target 自动去重）
`verify`	developer	比对实际结果 vs 期望规范，检测静默失败
`verify_ui`	developer	Playwright 按 UI 规范自动遍历并验证

关键参数 / 返回：

工具	入参（必填标 *）	返回要点
`diagnose_issue`	无必填；`request_id`(string)/`query`(string)/`since_minutes`(int=30)/`session_id`(string) 可选	`found`, `trace_id`, `summary`, `debug_context`；无数据时 `found=false` + `setup_hint` + `next_step`
`list_recent_traces`	`limit`(int=10), `session_id`(string) 可选	`count`, `traces[]`（含 trace_id/type/message/top_frame）
`search_logs`	`keyword`*(string), `since_minutes`(int=30), `session_id`(string) 可选	`count`, `results[]`
`debug`	`payload`*(object), `metadata`(object)	`request_id`, `result`, `trace`, `context`
`context`	`request_id`*(string)	结构化上下文 + `code_snippets`
`trace`	`request_id`*(string)	`trace`(时序列表), `step_count`
`stacktrace`	`request_id`(string, 可选；无参时自动取最近错误)	`exception`, `code_snippets`, `ai_summary`
`get_network_trace`	`trace_id`*(string)	`found`, `count`, `records`
`get_blame_for_frame`	`file`(string), `line`(int)	`found`, `blame`
`get_recent_diff`	`file`*(string), `commits_back`(int=3)	`found`, `diff`
`get_related_specs`	`file`*(string)	`found`, `count`, `specs`
`ingest_specs`	`openapi`*(object), `store`(bool=true)	`count`, `stored`, `skipped`, `spec_ids[]`
`verify`	`actual`*(object), `spec`/`spec_id`/`sample`(三选一), `trace_id`(可选)	`matched`, `diffs`, `silent_failure`
`verify_ui`	`spec` 或 `spec_id`(二选一), `timeout_ms`(int=30000)	`matched`, `diffs`, `silent_failure`, `interactions[]`, `security?`

`diagnose_issue` 参数语义与推荐回退顺序

diagnose_issue({})：不传任何参数 = 读取最近一次错误（跨页面/标签的最新一条，可再用 session_id 过滤）。
diagnose_issue({"query": "..."})：按关键词过滤近期错误，匹配范围是错误的 type / message 字段。query 是关键词过滤，不是自然语言全字段检索，也不保证匹配 selector、trace 元数据（如 trace_kind、extra）或其他上下文字段。
query 未命中不等于 Lujo 没有现场——可能只是关键词没出现在 type/message 里，或错误超出 since_minutes（默认 30 分钟）时间窗。

推荐查询回退顺序（从宽到深）：

diagnose_issue({}) —— 先拿最近错误；
list_recent_traces —— 无结果时列出近期全部错误摘要；
依返回的 trace_id / request_id 调用 context、trace、stacktrace、get_network_trace 深挖完整现场。

3.2 数据采集类工具（sdk）

工具名	角色	说明
`ingest_network`	developer	单条网络请求记录上报
`ingest_silent_failure`	developer	上报前端静默失败（UI 事件链 + 网络链 + 期望描述）
`ingest_error`	developer	任意语言主动上报异常
`ingest_console`	developer	上报浏览器控制台日志

关键参数：

工具	入参（必填标 *）
`ingest_network`	`record`*(object), `trace_id`, `request_id`
`ingest_silent_failure`	`message`*(string), `frames`[], `ui_events`[], `network_records`[], `expectation`, `observed`, `observed_events`[], `source`
`ingest_error`	`exc_type`(string), `message`(string), `frames`[], `source`, `extra`
`ingest_console`	`message`*(string), `level`(error/warn/info), `source`, `extra`, `trace_id`, `request_id`

3.3 实验工具（experimental）

experimental=true：接口可能变更，需显式环境/开关启用。

工具名	角色	说明	前置条件
`auto_test`	developer	自动遍历页面可交互元素并捕获控制台错误 + 网络 4xx/5xx	Playwright
`repair_async`	developer	异步生成修复方案（AI Debug Agent）	有效 Agent 模式非 `off`（显式 `AGENT_MODE` 优先；未显式时按旧布尔开关兼容派生）
`repair_result`	viewer	查询 repair_async 任务状态/结果	有效 Agent 模式非 `off`（显式 `AGENT_MODE` 优先；未显式时按旧布尔开关兼容派生）
`resolve_stack`	viewer	用 Source Map 还原 minified 堆栈	`SOURCEMAP_ENABLED=true` + 已上传 .map

关键参数：

工具	入参（必填标 *）
`auto_test`	`url`*(string), `max_actions`(int=20), `capture_console`(bool=true), `capture_network`(bool=true)
`repair_async`	`request_id`*(string) 或 `trace_id`(二选一)
`repair_result`	`job_id`*(string)
`resolve_stack`	`frames`*(array, 帧含 file/line/column/function), `artifact`(string)

3.4 工具执行控制与错误处理

背压与并发控制：同步工具调用通过有界并发槽位执行（tool_executor_workers，默认 8）。排队等待超过 tool_busy_queue_timeout（默认 1.5s；设为 0 时立即拒绝）将快速返回业务级错误，避免高负载下请求无限堆积。
返回结构与错误层级说明：
- 工具执行结果中的业务错误（当前实现）：工具调用超时（TOOL_TIMEOUT）、服务繁忙（TOOL_BUSY）或内部异常（TOOL_INTERNAL）时，服务端在 JSON-RPC 的 result 中返回业务错误信息（isError: true 及对应的 error_code 字段），而非顶层 JSON-RPC error。
- JSON-RPC 顶层协议错误：当请求无法解析（如 -32700 Parse Error）、方法未找到（-32601 Method Not Found）或入参结构校验失败（-32602 Invalid Params）时，服务端返回顶层 JSON-RPC error 对象。
- 错误码常量定义：代码中预定义了 TOOL_BUSY_ERROR = -32004 等扩展错误码常量供协议层备用；客户端在处理工具调用结果时，应以 result.error_code（如 "TOOL_BUSY"）作为判定标准。

3.4.1 两条传输的错误形态（有意差异，宿主按 `error_code` 分支，不要按文案）

同一个工具失败在 HTTP（POST /mcp）与 stdio（官方 SDK 适配层）上的外层载体不同，这是既有设计而非缺陷，两侧形态各自被 wire / parity 测试锁定：

场景	HTTP（JSON-RPC）	stdio（官方 SDK）
协议级错误（解析失败、方法不存在、入参结构非法、会话/权限）	顶层 `error` 对象 + 数字 `code`	同为顶层 JSON-RPC 错误（由 SDK 承载）
工具级失败（`TOOL_BUSY` / `TOOL_TIMEOUT` / `TOOL_INTERNAL` / 业务失败）	`result.isError = true`，`result.error_code` 与 `_busy` / `_timed_out` 标记位于 `result` 顶层	`CallToolResult.isError = true`，`error_code` 与标记位于 `content[0].text` 里的 JSON 载荷内（工具失败以 `ToolExecutionError` 上抛，由 SDK 包成 isError）
错误文案	中文（如「工具执行队列已满，请稍后重试。」）	部分为英文（如 `Tool execution failed`）

因此：判定失败一律用 isError + error_code，绝不要匹配文案（文案两传输不一致，且属可变的诊断信息）。error_code 取值集合由 app/mcp/protocol/tool_errors.py 的 MCP_TOOL_ERROR_CODES 单一声明，两传输同源。

两处刻意的口径决定（勿当缺陷重开）：

未知工具用 -32601 而不是 MCP 规范建议的 -32602：工具名确实是 tools/call 的 params 之一，按规范可归 Invalid Params；但 -32601 是本服务自 v0.5 起的既有 wire 契约，宿主可能已按码分支，改码属破坏性变更，收益不抵风险。
params 缺 name 键归入「未知工具 -32601」而不是 -32602：缺键与「工具名为空串」在注册表查找上不可区分；只有 name 存在但非字符串才按 malformed params 返回 -32602（B25 的三层防线之一）。

还有一处不由本项目控制的形态差异（已用真实调用取证并被单测锁定，升级 MCP SDK 后若变化会红灯）：stdio 上「参数类型错误」的载体取决于该工具是否出现在 tools/list——

路径	校验方	形态
stdio + listed 工具	官方 SDK 的 jsonschema	`isError=true`，`content[0].text` 是裸文本 `Input validation error: ...`，不含 `error_code`
stdio + unlisted 工具（`agent_visible=false` 的 SDK 上报类）	本项目 `_validate_tool_arguments`（SDK 对未列出工具明确不校验）	`isError=true`，文本是 JSON 载荷，含 `error_code="INVALID_PARAMS"`
HTTP（两类工具一致）	本项目 `_validate_tool_arguments`	顶层 `error.code = -32602`

因此宿主在 stdio 上不能假定参数错误一定带 error_code：对 listed 工具它是 SDK 的裸文本。要统一只能放弃 SDK 校验（代价更大——SDK 会校验嵌套结构，项目自己的校验只做顶层两层），故按现状文档化。

错误标识	出现层级	触发条件	处理建议
`TOOL_BUSY`	`result.error_code`（常量 `-32004`）	同步工具执行槽位满且等待超时（或 timeout=0 立即拒绝）；服务正在关闭时对重型工具的 fast-fail 也用本码（关闭路径从未消耗超时预算，不记 `TOOL_TIMEOUT`）	客户端稍后重试 / 指数退避，或调大 `TOOL_EXECUTOR_WORKERS`
`TOOL_TIMEOUT`	`result.error_code`（当前工具响应不使用顶层数字错误码）	工具执行耗时超过 `tool_timeout_seconds`（默认 60s）	检查操作耗时或调大超时阈值
`TOOL_INTERNAL`	`result.error_code`	工具执行中抛出未捕获异常	检查服务端日志排查工具内部异常
`INVALID_PARAMS`	顶层 `error.code = -32602`	工具入参 Schema 校验失败（Pydantic 校验不通过）	检查参数类型与必填字段
`METHOD_NOT_FOUND`	顶层 `error.code = -32601`	请求了不存在的 MCP 方法或工具	检查方法名与工具注册列表
`AUTH_ERROR`	顶层 `error.code = -32003`（HTTP 403）	RBAC 角色不足，无法调用该工具	换用具备所需角色的 API Key（角色映射见 `RBAC_ROLE_MAPPING`）
`INTERNAL_ERROR`	顶层 `error.code = -32603`	MCP 协议层未捕获内部错误	检查服务端日志与运行环境

4. Node SDK（npm 稳定版 v0.9.4 / 代码库候选 v0.9.5）

包名固定为 @lujoai/lujo-mcp-node-sdk。当前 npm 线上最新已发布版本为 v0.9.4（请勿假设 npm 上已存在 0.9.5）；当前代码库处于 v0.9.5 候选阶段。SDK 支持 Node 18、20、22，提供 CommonJS 和 ESM 根入口，engines.node 为 >=18。

npm install @lujoai/lujo-mcp-node-sdk

import { createClient } from "@lujoai/lujo-mcp-node-sdk";

const client = createClient({
  endpoint: "http://127.0.0.1:8000",
  apiKey: process.env.LUJO_MCP_API_KEY,
  release: "orders-service@1.4.0",
});

try {
  client.reportError(new Error("order lookup failed"), { operation: "getOrder" });
  client.reportNetworkError({
    method: "GET",
    url: "https://api.example.com/orders/42",
    status: 503,
  });
  await client.flush();
} finally {
  await client.close();
}

API	语义
`createClient({ endpoint?, apiKey?, release?, ... })`	创建进程内客户端。`endpoint` 使用 Lujo-MCP 服务根地址，省略时默认为 `http://127.0.0.1:8000`；`apiKey` 通过 `X-API-Key` 或等价鉴权请求头发送。
`reportError(error, extra?)`	显式上报错误；事件先进入内存批量队列，调用返回不代表已经发送完成。
`reportNetworkError(record)`	显式上报网络失败记录；可包含 `method`、`url`、`status_code`、`duration_ms` 等字段。
`flush()`	发送当前队列并等待结果，返回 `sent`、`failed`、`batches`、`attempts` 计数；单批不超过 100 条，429/5xx 按有限退避策略重试，永久 4xx 不无限重试。
`close()`	退出前完成最后一次 flush，停止后台定时器并释放资源；幂等，关闭后不要继续调用上报 API。
`getSessionId()` / `getTraceId()` / `setTraceId(id)`	读取或设置关联标识，便于把同一业务操作的错误与网络现场串起来。

可选传输参数包括 batchSize（1–100）、batchIntervalMs、maxRetries、retryDelayMs、maxRetryDelayMs 和 requestTimeoutMs；测试或自定义传输时可注入 fetch 实现。

Node SDK 在发送前递归脱敏错误、网络记录和 extra；默认敏感键包括 password、token、secret、authorization、cookie、api_key 和 private_key。它不自动拦截 fetch、http、undici、axios，也不提供浏览器 UI/console/XHR 采集；这些能力由 Browser SDK 提供。详见 SDK_GUIDE.md。

5. 常用字段速查

字段	含义
`request_id`	一次调试流程的唯一标识（`/api/debug/run`、`debug` 工具生成）
`trace_id`	SDK 生命周期内的追踪标识（贯穿所有上报），也可作为 request_id 关联
`error_id`	自动捕获异常的唯一标识（内存异常缓冲条目；原独立 `errors` 表已随 PostgreSQL 后端移除）
`fingerprint`	错误指纹（归一化 message + type），用于知识库精确命中去重
`silent_failure`	静默失败标志：`matched=false` 且无异常、无 4xx/5xx
`spec_diffs`	规范比对差异列表（expected vs actual）
`quality_report`	v0.4.0 QualityScorer 9 维度评分报告