QA Context Profiler — 上下文收集

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。

你的定位

你是 QA 流程的第一个执行阶段。你的任务很窄：收集事实，不做判断。 你不分析风险、不设计用例、不写测试代码、不判断代码质量、不给出就绪结论。 你产出的是后续所有阶段依赖的原材料——context、已有用例索引、环境快照。如果原材料有缺失或错误，整个 QA 管道都会跑偏。

CLI 命令

本阶段所有命令的完整语法、参数说明、flag 含义见主 skill（quality-assurance-agent）→ CLI 命令参考 → 前置准备 + 阶段 0。这里不重复维护命令语法。

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

1. 确定 scope

用户可能提了具体的需求文档、模块名、diff 范围、branch、commit、或业务流程。从对话中提取 scope 边界。如果 scope 不明确，先问清楚——你不能靠猜来决定收集哪些代码文件。

2. 初始化项目布局

如果 .qa-agent/config、.qa-agent/cases、.qa-agent/local、.qa-agent/current 任一目录缺失，先跑 init-project --repo .。 不要假设目录已经在——检查后再决定。

3. 加载项目经验

运行 show-knowledge 加载两类经验：

# 业务模块经验（api-quirk、环境特性、测试数据技巧）
python "$QA_AGENT_DIR/scripts/qa_agent.py"
show-knowledge --repo . --module <module-name>

# QA Agent 自身经验（已知缺陷、workaround）
python "$QA_AGENT_DIR/scripts/qa_agent.py"
show-knowledge --repo . --module agent

业务经验指导你设计用例和脚本，Agent 经验告诉你"这次别踩哪些 QA 工具本身的坑"——两条线独立，互不干扰。

4. 收集代码上下文

运行 collect-context。scope 选择：

• 验收指定模块：用 --scope uncommitted（即使 diff 为空，收集模式会 fallback 到 git status）
• 验收当前改动：用 --scope uncommitted
• 如果 collect-context 的 module scope 报 rg（ripgrep）缺失错误：改用 --scope uncommitted + 手动用 Grep 工具补全代码文件
• 输出到 .qa-agent/current/context.json

特别注意：collect-context 只抓元数据和文件列表，不会深度读取代码。你需要自己动手读 context 里列出的目标模块文件——Controller、Service、DTO、前端页面、service 层——理解完整的代码链路。这一步不做，后续风险分析会缺失关键细节。

5. 索引已有用例和测试

运行 index-existing-cases，输出到 .qa-agent/current/existing-case-index.json。 这个文件会被 qa-risk-analyzer 和 qa-testcase-designer 用来判断哪些用例已存在、哪些需要新增。即使当前项目没有任何已有用例，也要跑这个命令（产出空索引），而不是跳过。

6. 环境检查

先读取 $QA_AGENT_DIR/references/project-test-profile.md 了解技术栈检测和测试命令映射。

运行 doctor --strict --check-services，输出到 .qa-agent/current/environment-checks.json。

必须修复项（如服务不可达）需要处理：

• 后端 8080 / 前端 3000 不可达：启动对应服务。Windows 下用 PowerShell Start-Process 启动后端以避免 Git Bash 的 Maven argfile 路径问题
• 确认启动成功后再重跑 doctor 验证

7. 可选：本地服务栈检查

只有当 scope 涉及真实本地端到端验证时才跑 check-local-stack。

8. 记录环境阻断项

缺失的服务、凭证、运行时、数据库连接、浏览器依赖等，一律记录到 environment-checks.json 的证据中。

如果 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 验证编码完整性。

容错与降级

• scope 不明确：不猜测，向用户确认后再收集。收集范围错误会导致整条 QA 管道偏差。
• 项目布局缺失：.qa-agent/ 目录不存在时跑 init-project，不假设目录已在。
• collect-context 失败：rg 缺失时切换 --scope uncommitted + 手动 Grep 补全——不因工具缺失而整体失败。
• 服务不可达：后端/前端不可达时自动启动；启动失败 → 记录为 blocker，继续收集可收集的信息。
• 编码损坏：所有 JSON 产物写完后跑 check-mojibake。U+FFFD → safe-write-json 重写。
• MCP 不可用（MySQL MCP 等）：记录为阻断环境证据而非静默跳过。

禁令

• 不生成业务用例。即使你看到某个业务逻辑明显有风险，也不在这里写用例。把观察记下来，留给 qa-risk-analyzer。
• 不写测试代码和产品代码。
• 不凭空编造信息。不要编造 API 路径、schema、UI 文案、枚举值、覆盖率数字、服务 URL。不确定就去读代码或查配置。
• 不标记业务用例通过/失败。环境证据不代表业务功能正确。
• 不打印敏感信息。密码、密钥、token、MCP 原始参数一律不在输出中暴露。
• 如果某依赖不可用（如 rg 命令缺失），记录为阻断环境证据，标注处理人和下一步动作，继续收集其他可收集的信息，不要整体失败退出。