SuperAPI AI 工具集
合作ENAI 行业资讯收藏
Skill 广场qa-context-profiler

qa-context-profiler

测试与质量

查看项目

更新于 10-15 16:53

技能介绍

QA Context Profiler 是 QA 流程的第一个执行阶段，定位很窄：收集事实，不做判断。它不分析风险、不设计用例、不写测试代码、不判断代码质量、不给出就绪结论。它产出的是后续所有阶段依赖的原材料——context、已有用例索引、环境快照。

用途

为仓库构建事实画像和环境证据。当需要收集模块的代码上下文、索引已有用例和测试、检查前后端服务可达性、准备环境快照时触发。通常在 quality-assurance-agent 的调度下作为第一阶段执行。

主要能力

  • 收集代码上下文：运行 collect-context，输出到 .qa-agent/current/context.json。注意它只抓元数据和文件列表，不会深度读取代码，需要自己动手读 context 里列出的目标模块文件（Controller、Service、DTO、前端页面、service 层）以理解完整代码链路。
  • 索引已有用例和测试：运行 index-existing-cases，输出到 .qa-agent/current/existing-case-index.json。即使当前项目没有任何已有用例，也要跑这个命令（产出空索引），而不是跳过。
  • 环境检查：运行 doctor --strict --check-services，输出到 .qa-agent/current/environment-checks.json。
  • 可选本地服务栈检查：只有当 scope 涉及真实本地端到端验证时才跑 check-local-stack。
  • 记录环境阻断项：缺失的服务、凭证、运行时、数据库连接、浏览器依赖等，一律记录到 environment-checks.json 的证据中。

使用方式

CLI 调用约定：本工具包的 CLI 是 quality-assurance-agent/scripts/qa_agent.py。它不以 PATH 命令的形式分发——命令由 agent 执行，人不必手敲。开工前解析一次 skill 目录，之后所有命令一律写成 python "$QA_AGENT_DIR/scripts/qa_agent.py" <cmd>：

QA_AGENT_DIR="${QA_AGENT_CLI:-$(dirname "$(find ~/.claude/skills ~/.agents/skills ~/.codex/skills .claude/skills .agents/skills .codex/skills -maxdepth 2 -name SKILL.md -path 'quality-assurance-agent/' 2>/dev/null | head -1)")}"

运行环境若已告知本 skill 目录（Claude Code 会），直接用，不必跑上面的查找。完整命令语法见 $QA_AGENT_DIR/references/cli-reference.md。

工作流（按顺序执行，不要跳过）：

  1. 确定 scope：从对话中提取 scope 边界。如果 scope 不明确，先问清楚——不能靠猜来决定收集哪些代码文件。
  2. 初始化项目布局：如果 .qa-agent/config、.qa-agent/cases、.qa-agent/local、.qa-agent/current 任一目录缺失，先跑 init-project --repo .。不要假设目录已经在——检查后再决定。
  3. 加载项目经验：运行 show-knowledge 加载两类经验：业务模块经验（api-quirk、环境特性、测试数据技巧）和 QA Agent 自身经验（已知缺陷、workaround）。两条线独立，互不干扰。
  4. 收集代码上下文：运行 collect-context。scope 选择：验收指定模块用 --scope uncommitted（即使 diff 为空，收集模式会 fallback 到 git status）；验收当前改动用 --scope uncommitted。如果 collect-context 的 module scope 报 rg（ripgrep）缺失错误：改用 --scope uncommitted + 手动用 Grep 工具补全代码文件。
  5. 索引已有用例和测试：运行 index-existing-cases。
  6. 环境检查：先读取 $QA_AGENT_DIR/references/project-test-profile.md 了解技术栈检测和测试命令映射，再运行 doctor --strict --check-services。必须修复项（如服务不可达）需要处理：后端 8080 / 前端 3000 不可达时启动对应服务，Windows 下用 PowerShell Start-Process 启动后端以避免 Git Bash 的 Maven argfile 路径问题；确认启动成功后再重跑 doctor 验证。
  7. 可选：本地服务栈检查。
  8. 记录环境阻断项。如果 scope 涉及数据库层验证，读取 $QA_AGENT_DIR/references/mysql-mcp-integration.md 了解 MySQL MCP 的安装和连接要求。如果 MCP 不可用，记录为阻断环境证据而非静默跳过。
  9. 移交到下游：产物清单包括 .qa-agent/current/context.json、.qa-agent/current/existing-case-index.json、.qa-agent/current/environment-checks.json、.qa-agent/current/local-stack-check.json（如果跑了）。向上游（主 skill）报告收集完成，并明确指出：接下来需要调用 qa-risk-analyzer，不要在风险分析完成前设计用例。

编码安全：本阶段如果产生中文 JSON 文件（context.json 等），注意 Windows 下 AI Write/Edit 工具偶发 U+FFFD 编码损坏。如果发现文件写完后检查出替换字符，用 python "$QA_AGENT_DIR/scripts/qa_agent.py" safe-write-json --from-stdin 通过 Python 管道重写文件内容。写完文件后务必跑 python "$QA_AGENT_DIR/scripts/qa_agent.py" check-mojibake 验证编码完整性。

适用场景

  • 需要为仓库构建事实画像和环境证据时。
  • 需要收集模块的代码上下文、索引已有用例和测试、检查前后端服务可达性、准备环境快照时。
  • 作为 quality-assurance-agent 调度的第一阶段执行。

限制

  • 不生成业务用例。即使看到某个业务逻辑明显有风险，也不在这里写用例。把观察记下来，留给 qa-risk-analyzer。
  • 不写测试代码和产品代码。
  • 不凭空编造信息。不要编造 API 路径、schema、UI 文案、枚举值、覆盖率数字、服务 URL。不确定就去读代码或查配置。
  • 不标记业务用例通过/失败。环境证据不代表业务功能正确。
  • 不打印敏感信息。密码、密钥、token、MCP 原始参数一律不在输出中暴露。
  • 如果某依赖不可用（如 rg 命令缺失），记录为阻断环境证据，标注处理人和下一步动作，继续收集其他可收集的信息，不要整体失败退出。
  • scope 不明确：不猜测，向用户确认后再收集。收集范围错误会导致整条 QA 管道偏差。
  • 项目布局缺失：.qa-agent/ 目录不存在时跑 init-project，不假设目录已在。
  • collect-context 失败：rg 缺失时切换 --scope uncommitted + 手动 Grep 补全——不因工具缺失而整体失败。
  • 服务不可达：后端/前端不可达时自动启动；启动失败 → 记录为 blocker，继续收集可收集的信息。
  • 编码损坏：所有 JSON 产物写完后跑 check-mojibake。U+FFFD → safe-write-json 重写。
  • MCP 不可用（MySQL MCP 等）：记录为阻断环境证据而非静默跳过。