Qa Context Profiler

---
name: qa-context-profiler
description: >
  QA 上游阶段——为仓库构建事实画像和环境证据。当你需要收集模块的代码上下文、索引已有用例和测试、
  检查前后端服务可达性、准备环境快照时触发。只收集事实，不做风险分析、不写用例、不判断质量。
  通常在 quality-assurance-agent 的调度下作为第一阶段执行。
  不适用：风险分析、用例设计、测试执行、质量判定（由下游阶段负责）。
---

# 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` 加载两类经验：

```bash
# 业务模块经验（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 命令缺失），记录为阻断环境证据**，标注处理人和下一步动作，继续收集其他可收集的信息，不要整体失败退出。