用途
qa-probe 是一个本地运行的 QA 智能体，以 Node.js 命令行工具形式提供。它解决的问题是：仪表盘能加载、程序不崩溃，但表格空白、图表为零，开发者难以快速定位原因。它把前端 API 调用与后端实时响应建立“源码感知”的映射，然后逐条解释失败原因并给出修复提示。它定位于补足 Playwright（用户旅程）和 Schemathesis（契约 fuzzing）之外的那一层——优先回答“这个页面为什么是空的”。
主要能力
- 源码感知映射：使用 Babel 解析前端，检测 axios/fetch 调用与常见 hook 模式，从 React Router（JSX 与 createBrowserRouter）及 TanStack Router 提取路由。
- 带真实认证的实时探测：支持 bearer、cookie、api-key 或 none；并发受限，并有单请求硬性超时，避免流式端点挂起整个运行。
- 根因分类：约 25 种原因，每种附带修复提示。常见原因包括尾斜杠不匹配（前端 /api/users/ 对后端 /api/users）、功能开关（如 HAS_BILLING=false）静默禁用整个路由、数据库已连接但表无数据、后端重构重命名字段而前端仍读旧名、端点缺少认证守卫或无 token 泄漏数据等。
- ID 链式探测：先探测集合端点，取回真实 id，再用它探测详情路由，而不是使用猜测值，默认开启。
- 自适应基线：从近期运行中学习每个端点的正常延迟与行数，并标记偏离自身基线的行为；不依赖模型，完全可检查。
- 反馈机制：qa-probe label 或 MCP 工具可记录判定，并在后续运行中重新应用；范围化标签在行为变化时自动撤销，避免掩盖回归。
- 安全检查（可选）：匿名认证绕过复测、PII 扫描、按角色的权限提升矩阵；仅 GET，不发起写入。
- 响应断言：声明不变量（in、type、gte、pattern、present、minItems 等），qa-probe 在每个 2xx 响应上验证。
- 写入流程（可选、会修改数据）：完整的增删改查链，带保证清理；默认关闭，仅适用于一次性/测试租户环境。
- 其他：SSE 与 WebSocket 检查、schema 漂移检测、爆炸半径、回归 diff、覆盖率、为动态前端提供 HAR 导入、OpenAPI 自动发现（尝试常见规范路径并支持本地规范文件）。
使用方式
通过 npm 安装后，在项目根目录创建配置文件 qa-probe.config.js（文档示例见官方仓库 README）。工具分三个阶段，且各自缓存，可独立重跑：
- 分析：解析前端 AST，提取路由，获取 OpenAPI 规范（或导入 HAR），构建带爆炸半径的依赖图。
- 探测：认证一次，然后对每个发现的端点进行实时探测（HTTP、SSE、WebSocket），带硬性超时和 ID 链式探测。
- 报告：分类根因，应用基线与反馈，为路由打 0-100 分，写出 JSON / Markdown / ai-context / HTML 报告（写入 .qaprobe/ 目录），并在终端输出汇总表。
命令行提供 --fail-under <N> 选项，当总分低于 N 时以非零状态退出，可用于 CI 门禁（例如 qa-probe run --fail-under 80）。
与 AI 助手配合：qa-probe 附带 Model Context Protocol（MCP）服务器。先运行一次 qa-probe 填充缓存，再在仓库根目录的 .mcp.json 中配置 MCP 服务器，重启助手后即可用自然语言提问，例如“为什么 /reports 没有数据？”“如果 users 端点宕机，哪些页面会受影响？”“列出所有损坏的路由。”以及标记预期结果。MCP 工具的输出经过脱敏，SQL 错误、堆栈跟踪和表名在到达助手前会被删改；原始数据保留在磁盘上。也可直接在 AI 编码工具中打开包含 .qaprobe/ 的目录，让它读取 ai-context.md。
适用场景
- “这个页面为什么是空的”日常排查：一次运行即得到根因与修复提示，无需翻网络面板和日志。
- CI 门禁：分数低于阈值时阻止部署。
- 演示/预发布签核：在客户会议前确认环境真正可用，而不只是返回 200。
- 发现契约漂移：后端重构重命名字段或移动路由时，指出受影响的具体端点与前端调用。
- 安全冒烟检查：发现缺少认证守卫或泄漏 PII 的端点（可选、只读）。
- 逻辑检查：断言响应不变量，无需编写测试套件。
- AI 辅助调试：让 Claude、Cursor 或 Codex 查询 QA 状态并用自然语言解释失败。
限制与安全
已知限制：只能检测可见的 HTTP 调用和常见 hook 模式；生成的 SDK 客户端、GraphQL 客户端、tRPC 路由器和自定义服务层可能需要适配器，或用 HAR 导入从真实流量中发现；由任意工厂函数构建的动态 URL 无法检测；最佳效果需要 OpenAPI 规范，无规范的头less 模式会丢失依赖规范的规则，但仍能检测观测到的形状漂移。
安全方面：凭据仅在运行期间保存在内存中，绝不写入任何报告；配置文件作为 JavaScript 执行，只应使用可信配置运行 qa-probe；ignoreHTTPSErrors: true 会禁用 TLS 验证，仅限开发/预发布环境；安全检查复测仅 GET、不写入；写入流程默认关闭并会自行清理，仅用于一次性环境。
许可与品牌
采用 Apache License 2.0（见仓库 LICENSE 与 NOTICE）。在 Apache-2.0 条款下可使用、修改和再分发 qa-probe；版权及商标仍归 LS-SIEM LLP 所有。“qa-probe”“LightShield”“LS-SIEM”是 LS-SIEM LLP 的商标，Apache 许可不授予使用这些名称或标志的权限。贡献需遵守 CONTRIBUTING.md 并签署开发者原创声明（git commit -s）。
