homegraph 1.1.2 → 1.2.0

package/scripts/qa_eval/README.md

@@ -1,404 +1,407 @@
-# QA Eval — 四段式 A/B 评测流水线
-
-内置多轮 Agent + Judge + 统计 + 报告，对齐 CodeGenie / Trae 评测框架：**Agent 跑题 → Judge 打分 → 分数统计 → 效率统计 → A/B 对比**。
-
-- **国内可用**：Agent / Judge 均走 OpenAI 兼容接口，支持 **DashScope Qwen** 或 **智谱 GLM**
-- **不依赖** Claude / ragas / langchain
-- **被测仓库**：运行时用 `--repo` / `-r` 指定，无默认路径
-## 目录
-
-```
-scripts/qa_eval/
-├── agent_runner.py         # Stage 1：内置多轮 Agent（with / without 两路）
-├── my_answer_accuracy.py   # Judge 指标（双 prompt 0–5 归一化）
-├── eval_metrics.py         # Stage 2：对 JSONL 批量打分
-├── stats_scores.py         # Stage 3：answer_accuracy_score 汇总
-├── stats_efficiency.py     # Stage 4：解析 Agent 日志（首响应/轮次/耗时/Token/内存）
-├── memory_monitor.py       # 进程树 RSS 采样（Linux /proc）
-├── external_agent.py       # Claude Code / DevEco Code 外部 Agent 跑题
-├── run_pipeline.py         # 编排 Stage 1–4 + A/B 报告
-├── requirements.txt
-├── data/                   # 仅测试集 + 报告（可入库）
-│   ├── test-set.jsonl
-│   └── report-{host}.txt
-└── log/                    # 流水线中间产物（不入库）
-    ├── result-with-{host}.jsonl
-    ├── result-without-{host}.jsonl
-    ├── result-*-{host}-scored.jsonl
-    ├── agent-with-{host}.log
-    ├── agent-without-{host}.log
-    └── eval_metrics.log
-```
-
-**Git 入库规则**
-
-| 路径 | 是否提交 |
-|------|----------|
-| `scripts/qa_eval/*.py`、`README.md`、`requirements.txt` | 是 |
-| `data/test-set.jsonl` | 是（测试集） |
-| `data/report*.txt` | 否（报告，留在 data/ 但不入库） |
-| `log/` 下全部 | 否 |
-| `__pycache__/` | 否 |
-
-## 整体流程
-
-```
-test-set.jsonl
-    ↓
-Stage 1  agent_runner.py（run_pipeline ab 内置）
-         with    : HomegraphQuery + ReadFile
-         without : SearchText(rg) + FindFiles + ReadFile
-         产出: log/result-*-{host}.jsonl + log/agent-*-{host}.log
-    ↓
-Stage 2  eval_metrics.py     → log/result-*-{host}-scored.jsonl
-    ↓
-Stage 3  stats_scores.py     → 准确率汇总（并入 report-{host}.txt）
-Stage 4  stats_efficiency.py → 效率汇总（终端 + report-{host}.txt）
-    ↓
-run_pipeline.py ab           → data/report-{host}.txt
-```
-
-**A/B 唯一变量**：Agent 是否可用 homegraph。两臂使用**同一模型、同一 max_turns**；without **不是裸 LLM**，仍是多轮 grep/read Agent。
-
-## 快速开始
-
-```bash
-pip install -r scripts/qa_eval/requirements.txt \
-  -i https://pypi.tuna.tsinghua.edu.cn/simple
-
-export DASHSCOPE_API_KEY="sk-xxxxxxxx"
-# 或使用智谱（Key 格式 id.secret，不要加 sk- 前缀）：
-# export ZHIPU_API_KEY="xxxxxxxx.yyyyyyyy"
-
-cd /path/to/homegraph && npm run build
-node dist/bin/homegraph.js sync /path/to/your/repo
-
-python scripts/qa_eval/run_pipeline.py ab -r /path/to/your/repo
-# 智谱显式指定：
-# python scripts/qa_eval/run_pipeline.py ab -r /path/to/your/repo --provider zhipu
-# python scripts/qa_eval/run_pipeline.py ab -r /path/to/your/repo --provider zhipu --model glm-4-flash```
-
-### Agent 宿主（`--agent-host`）
-
-| 宿主 | 说明 | Agent 前置条件 | 报告文件 |
-|------|------|----------------|----------|
-| `builtin`（默认） | Python 内置多轮 Agent + 智谱/DashScope | `ZHIPU_API_KEY` 或 `DASHSCOPE_API_KEY` | `report-builtin.txt` |
-| `claude-code` | **Claude Code CLI**（`claude -p` + MCP） | `claude login` 已登录 | `report-claude.txt` |
-| `deveco-code` | **DevEco Code / opencode CLI** | `deveco` 在 PATH，且 **DevEco 自己的** provider 已登录（见下） | `report-deveco.txt` |
-
-**注意**：`--provider zhipu` 只影响 **builtin Agent** 和 **Judge**；`deveco-code` / `claude-code` 使用各自 CLI 的账号与凭证，不会读取 `ZHIPU_API_KEY`。
-
-DevEco 首次使用需配置模型（凭证保存在用户目录，**不是** DEVECO_HOME）：
-
-```bash
-deveco providers login    # 选 Zhipu AI，输入 API Key
-# 凭证目录（Windows）: C:\Users\<你>\.config\deveco
-```
-
-TUI 若提示 **DEVECO_HOME**，那是 DevEco **Studio** 安装路径（需 6.1+），仅编译/推包需要；**跑 qa_eval 可跳过**。你当前 Studio 为 5.1，填 `C:\Program Files\Huawei\DevEco Studio` 会校验失败，属正常。
-
-homegraph MCP 写在**被测仓库**的 `.deveco/deveco.jsonc`；智谱 Key 仍读 `~/.config/deveco`。
-
-**Judge 打分**（Stage 2）三种宿主共用，仍需 `ZHIPU_API_KEY` 或 `DASHSCOPE_API_KEY`（与 `--provider` 一致）。
-
-#### 怎么跑
-
-```bash
-cd /path/to/homegraph
-npm run build
-node dist/bin/homegraph.js sync /path/to/your/repo
-
-# ① 内置 Agent（智谱）
-export ZHIPU_API_KEY="your-id.your-secret"
-python scripts/qa_eval/run_pipeline.py ab -r /path/to/your/repo --provider zhipu --agent-host builtin
-# → report-builtin.txt
-
-# ② Claude Code（Agent 用 Claude 自己的账号，Judge 仍用上面的 Key）
-which claude && claude login        # 必须先登录，否则每题返回 Not logged in
-python scripts/qa_eval/run_pipeline.py ab -r /path/to/your/repo --provider zhipu --agent-host claude-code
-# → report-claude.txt
-
-# ③ DevEco Code（Agent 用 DevEco 自己的 provider，Judge 仍用 ZHIPU_API_KEY）
-where deveco
-deveco providers reset   # 仅凭证损坏/换机时需要
-deveco                   # TUI 里配置智谱等模型后再跑评测
-python scripts/qa_eval/run_pipeline.py ab -r /path/to/your/repo --provider zhipu --agent-host deveco-code
-# 指定 DevEco 模型（可选，格式 provider/model）：
-# python scripts/qa_eval/run_pipeline.py ab -r /path/to/your/repo --provider zhipu --agent-host deveco-code --deveco-model zhipuai/glm-4.5-flash
-# → report-deveco.txt
-
-# ④ 三种依次跑（各写各的报告，不会互相覆盖）
-python scripts/qa_eval/run_pipeline.py hosts -r /path/to/your/repo --provider zhipu
-
-# 等价于 hosts 的子集：
-python scripts/qa_eval/run_pipeline.py hosts -r /path/to/your/repo --agent-hosts claude-code,deveco-code --provider zhipu```
-
-产出示例（每种宿主一套，互不覆盖）：
-
-| 宿主 | JSONL / 日志（`log/`） | 报告（`data/`） |
-|------|------------------------|-----------------|
-| builtin | `log/result-with-builtin.jsonl`、`log/agent-with-builtin.log` | `data/report-builtin.txt` |
-| claude-code | `log/result-with-claude.jsonl`、`log/agent-with-claude.log` | `data/report-claude.txt` |
-| deveco-code | `log/result-with-deveco.jsonl`、`log/agent-with-deveco.log` | `data/report-deveco.txt` |
-
-（without 臂同理：`result-without-{host}.jsonl`、`agent-without-{host}.log`）
-
-**若全局 `homegraph sync` 报 `Cannot find module 'arkanalyzer'`**：用本地 `dist/bin/homegraph.js`（pipeline 会自动优先找本地 build）。
-
-### `ab` 各阶段产出
-
-| 阶段 | 终端 | 文件 |
-|------|------|------|
-| Stage 1 Agent | 每题进度 | `log/result-*.jsonl`、`log/agent-*.log` |
-| Stage 2 Judge | eval_metrics 进度 | `log/result-*-scored.jsonl` |
-| Stage 3–4 报告 | **效率明细**（两路任务列表 + 平均值） | **`data/report-{host}.txt`** |
-
-终端最后一行示例：
-
-```
-A/B 完整报告已写入: .../scripts/qa_eval/data/report-deveco.txt
-```
-
-### `report-{host}.txt` 结构
-
-```
-################################################################################
-#                         A/B 完整评测报告                                      #
-################################################################################
-
-【输入文件】
-【WITH homegraph】效率明细      ← 逐题 + 汇总（见下方「效率指标」）
-【WITHOUT homegraph】效率明细
-【WITH / WITHOUT homegraph】准确率统计  ← 见下方「准确率指标」
-按类别准确率                    ← category_l1 分组 with/without 均分与 Δ
-逐题对比                        ← 每题得分、答案摘要；末尾 with 赢/平/输 计数
-【A/B 汇总表】                  ← 两臂核心指标并排 + Δ（with−without）
-```
-
-只重打报告、不重跑 Agent/Judge（无需 `--repo`）：
-
-```bash
-python scripts/qa_eval/run_pipeline.py ab --no-agent --no-judge
-```
-## Stage 1 — Agent（`agent_runner.py`）
-
-内置 Qwen 多轮工具 Agent，默认最多 **8 轮**（`--max-turns`）。
-
-| 臂 | 工具 | 说明 |
-|----|------|------|
-| **with** | `HomegraphQuery`、`ReadFile` | 先 homegraph 检索符号，再读源码 |
-| **without** | `SearchText`、`FindFiles`、`ReadFile` | rg 全文搜索 + glob 找文件 |
-
-with 臂跑前会检查被测仓库已索引（`.homegraph/` 或 `.homegraph/`）；without 臂不需要索引。
-
-每条 JSONL 写入字段示例：
-
-```json
-{
-  "id": "R01",
-  "query": "getColorString 函数在哪个文件里定义？",
-  "reference_answer": "...",
-  "output_answer": "---\nHomegraphQuery\nquery: getColorString\n...\n---\n\n定义在 camera/common/.../ColorUtil.ets。",
-  "agent_backend": "agent-with-homegraph",
-  "agent_usage": { "total_tokens": 1296 },
-  "agent_duration_ms": 7830,
-  "agent_memory_mb": { "peak_rss_mb": 412.5, "avg_rss_mb": 380.2 }
-}
-```
-
-`agent_memory_mb` 为 Agent 进程树（含 homegraph MCP 子进程）在答题期间的 RSS 采样。
-
-`output_answer` 中工具调用包在 `--- ... ---` 块里（与 CodeGenie 格式一致）；Judge 会自动剥掉再打分。
-
-### Agent 日志格式（`agent-*.log`）
-
-```
-2026-06-23 09:25:21.052447 Evaluate 1:
-2026-06-23 09:25:21.052571 the 1 turn
-2026-06-23 09:25:22.321954 first token          ← 第一次 LLM API 返回后写入
-2026-06-23 09:25:22.321954 totalTokenCount = 349
-2026-06-23 09:25:27.771606 the 2 turn
-2026-06-23 09:25:28.861895 totalTokenCount = 947
-2026-06-23 09:25:30.102441 peakRssMb = 412.5
-2026-06-23 09:25:30.102441 avgRssMb = 380.2
-...
-```
-
-`stats_efficiency.py` 解析这些行得到逐题效率与**内存**。**首响应** = 从 `Evaluate N:` 到第一次 LLM API 返回的耗时；**峰值内存** = 该题进程树 RSS 峰值（MB，Linux `/proc`）。
-
-### 外部 Agent（可选）
-
-若用 CodeGenie / Trae 等外部 Agent 产出同格式 JSONL + 日志：
-
-```bash
-python scripts/qa_eval/run_pipeline.py ab --no-agent
-# 或只重打 Judge + 报告
-python scripts/qa_eval/run_pipeline.py ab --no-agent --no-judge
-```
-
-## Stage 2 — Judge 打分（`eval_metrics.py`）
-
-```bash
-python scripts/qa_eval/eval_metrics.py \
-  -i scripts/qa_eval/log/result-with-builtin.jsonl \
-  -o scripts/qa_eval/log/result-with-builtin-scored.jsonl \
-  -w 2
-```
-
-| 参数 | 默认 | 说明 |
-|------|------|------|
-| `-i` / `--input` | — | Agent 产出 JSONL |
-| `-o` / `--output` | `*-scored.jsonl` | 打分结果 |
-| `-w` / `--workers` | `1` | 并发线程数 |
-| `-m` / `--model` | `qwen3-235b-a22b-instruct-2507` | Judge 模型 |
-
-追加字段：`answer_accuracy_score`（0–1）、`evaluation_status`（`success` / `failed`）。
-
-## Stage 3 — 分数统计（`stats_scores.py`）
-
-```bash
-python scripts/qa_eval/stats_scores.py \
-  -i scripts/qa_eval/log/result-with-builtin-scored.jsonl
-```
-
-输出（每臂各一份）：总/成功/失败样本数，均值、中位数、最小/最大、标准差、方差，五档分数分布，评估成功率。`run_pipeline ab` 会将其并入 `report-{host}.txt`。
-
-## Stage 4 — 效率统计（`stats_efficiency.py`）
-
-```bash
-python scripts/qa_eval/stats_efficiency.py \
-  -l scripts/qa_eval/log/agent-with-builtin.log
-```
-
-输出：
-
-- **逐题**（任务明细）：首响应、轮次、总时间、总 Token、**峰值内存 (MB)**
-- **汇总**（统计结果）：任务总数、平均首响应、平均轮次、平均总时间、平均总 Token、**平均/最大峰值内存**、合计总 Token
-
-日志缺失时回退为 JSONL 的 `agent_usage` 逐题 Token（无轮次/耗时/首响应）。
-
-**homegraph 价值**：对比 with / without 汇总行的**平均轮次、平均总时间、平均总 Token**（汇总表同列）；轮次越少、耗时越短、Token 越少，说明 homegraph 减少了盲目 grep/read。
-
-## `run_pipeline.py` 命令
-
-### `ab` — A/B 全流程
-
-```bash
-python scripts/qa_eval/run_pipeline.py ab -r /path/to/your/repo [选项]
-```
-
-| 参数 | 默认 | 说明 |
-|------|------|------|
-| `--repo`, `-r` | — | **被测仓库**（跑 Agent 时必填） || `--dataset`, `-d` | `data/test-set.jsonl` | 测试集 |
-| `--with-jsonl` / `--without-jsonl` | `log/result-*.jsonl` | Agent 产出 |
-| `--with-scored` / `--without-scored` | `log/result-*-scored.jsonl` | Judge 产出 |
-| `--with-log` / `--without-log` | `log/agent-*.log` | Agent 日志 |
-| `--report` | `data/report-{host}.txt` | 完整报告路径（默认随 `--agent-host`） |
-| `--model`, `-m` | `qwen3-235b-a22b-instruct-2507` | Agent + Judge 模型 |
-| `--workers`, `-w` | `1` | Judge 并发 |
-| `--max-turns` | `8` | Agent 最多工具轮次（仅 builtin） |
-| `--agent-host` | `builtin` | `builtin` / `claude-code` / `deveco-code` / `all` |
-| `--homegraph-bin` | 自动检测 | 本地 `dist/bin/homegraph.js` 优先 |
-| `--no-agent` | — | 跳过 Stage 1，沿用已有 JSONL |
-| `--no-judge` | — | 跳过 Stage 2，沿用已有 scored |
-
-### `score` — 单路 Judge + 统计
-
-```bash
-python scripts/qa_eval/run_pipeline.py score \
-  -i scripts/qa_eval/log/result-with-builtin.jsonl \
-  -l scripts/qa_eval/log/agent-with-builtin.log
-```
-
-## 测试集格式（`test-set.jsonl`）
-
-每行一条：
-
-```json
-{
-  "id": "R01",
-  "query": "getColorString 函数在哪个文件里定义？",
-  "reference_answer": "getColorString 定义在 camera/common/src/main/ets/utils/ColorUtil.ets。",
-  "category_l1": "检索",
-  "category_l2": "函数",
-  "level0": "camera",
-  "level1": "ColorUtil",
-  "difficulty": "简单",
-  "language": "ArkTS"
-}
-```
-
-`category_*`、`level*`、`difficulty` 仅用于报告分组，Judge 不读取。
-
-## 结果怎么读
-
-### 【A/B 汇总表】— 核心对比（`report-{host}.txt` 末尾）
-
-| 指标 | 含义 | A/B 怎么看 |
-|------|------|------------|
-| 准确率 均值 | Judge 给出的 `answer_accuracy_score`（0–1）全题平均 | Δ > 0 表示 with 答案质量更高 |
-| 准确率 中位数 | 同上，中位数（抗极端值） | 与均值交叉验证 |
-| Judge 成功/总数 | 成功打分的题数 / 总题数 | 应接近 100%；失败需查 API/JSONL |
-| 平均轮次 | 每题 Agent 调用 LLM 的工具循环次数（日志 `the N turn` 的最大 N）再求平均 | **越低越好**；with 理想上更低 |
-| 平均耗时 (秒) | 每题从 `Evaluate N:` 到下一题开始的端到端时间再求平均 | **越短越好** |
-| 平均 Token (k) | 每题 Agent 消耗 Token（日志 `totalTokenCount` 累加）再求平均，单位 k | **越少越好** |
-| 平均首响应 (秒) | 每题从 `Evaluate N:` 到第一次 LLM API 返回再求平均 | 参考项，非 homegraph 主指标 |
-| 平均峰值内存 (MB) | 每题 Agent+MCP 进程树 RSS 峰值再求平均 | **越低越好**；with 不应显著高于 without |
-| 最大峰值内存 (MB) | 单题 RSS 峰值的最大值 | 观察是否 OOM 风险 |
-
-Δ 列均为 **with − without**（正数表示 with 更高/更多/更慢，视指标而定）。
-
-### 准确率明细（每臂「准确率统计」段）
-
-| 指标 | 含义 |
-|------|------|
-| `answer_accuracy_score` 均值 / 中位数 | 该臂答案质量 |
-| 最小值 / 最大值 | 最差、最好单题得分 |
-| 标准差 / 方差 | 分数离散程度 |
-| 分数分布（五档） | 0–0.2 … 0.8–1.0 各档题数与占比 |
-| 评估成功率 | 成功 Judge 数 / 总样本数 |
-
-### 效率明细（每臂「效率明细」段）
-
-| 粒度 | 指标 | 含义 |
-|------|------|------|
-| 逐题 | 首响应 | 该题第一次 LLM 返回耗时 |
-| 逐题 | 轮次 | 该题 LLM 工具循环次数 |
-| 逐题 | 总时间 | 该题端到端耗时 |
-| 逐题 | 总 Token | 该题 Agent Token 消耗 |
-| 逐题 | 峰值内存 | 该题进程树 RSS 峰值 (MB) |
-| 汇总 | 平均峰值内存 / 最大峰值内存 | 内存占用汇总 |
-| 汇总 | 平均首响应 / 平均轮次 / 平均总时间 / 平均总 Token | 上表逐题指标的平均值 |
-| 汇总 | 合计总 Token | 该臂 20 题 Token 总和 |
-
-### 分组与逐题（report-{host}.txt 中部）
-
-| 区块 | 内容 |
-|------|------|
-| 按类别准确率 | 按 `category_l1`（检索 / 解读 / 依赖）分组的 with/without 均分与 Δ |
-| 逐题对比 | 每题 ID、类别、with/without 得分与 Δ、问题与答案摘要 |
-| 逐题对比末尾 | **with 更高 / 持平 / without 更高** 题数统计 |
-
-## 常见问题
-
-| 现象 | 处理 |
-|------|------|
-| Claude 准确率全 < 0.1 / `Not logged in` | Agent 未登录：`claude login` 后重跑；pipeline 现会在首题探测并 fail-fast |
-| `deveco-code` exit 1 / `Model not found: glm-4-flash` | `--provider zhipu` 的模型只给 Judge/builtin；deveco 用 `deveco models` 里的 `zhipuai/...` 名，或加 `--deveco-model zhipuai/glm-4.5-flash` |
-| `401` / Judge 全失败 | 检查 API Key：`DASHSCOPE_API_KEY`（DashScope）或 `ZHIPU_API_KEY`（智谱，格式 `id.secret`）；智谱请加 `--provider zhipu`，勿把智谱 Key 设到 `DASHSCOPE_API_KEY` |
-| `Cannot find module 'arkanalyzer'` | `npm run build`，用 `node dist/bin/homegraph.js sync` |
-| `rg not found on PATH` | `sudo apt install ripgrep`（without 臂需要） |
-| 日志解析 0 条任务 | 确认 log 含 `Evaluate N:` 行 |
-| 首响应全为 0 | 旧 log bug；重跑 Agent 或依赖自动回退逻辑 |
-| `claude` / `opencode` 未找到 | 安装 Claude Code 或 DevEco Code，并加入 PATH |
-| 内存全为 N/A | Windows 无 `/proc`，内存采样自动跳过（不影响跑题）；Linux/WSL 上才有峰值内存 || 分数偏低但答案看起来对 | 检查 `output_answer` 是否只剩工具块、无最终自然语言答案 |
-| pip 慢 | 用清华镜像（见快速开始） |
-
-## 最小通路（仅 Judge 单条）
-
-```bash
-export DASHSCOPE_API_KEY="sk-xxx"
-head -1 scripts/qa_eval/log/result-with-builtin.jsonl > /tmp/one.jsonl
-python scripts/qa_eval/eval_metrics.py -i /tmp/one.jsonl -o /tmp/one-scored.jsonl
-python scripts/qa_eval/stats_scores.py -i /tmp/one-scored.jsonl
-```
+# QA Eval — 四段式 A/B 评测流水线
+
+内置多轮 Agent + Judge + 统计 + 报告，对齐 CodeGenie / Trae 评测框架：**Agent 跑题 → Judge 打分 → 分数统计 → 效率统计 → A/B 对比**。
+
+- **国内可用**：builtin Agent / Judge 走 OpenAI 兼容接口（DashScope Qwen 或智谱 GLM）
+- **多 Agent 宿主**：builtin Python Agent、Claude Code CLI、DevEco Code CLI
+- **不依赖** ragas / langchain
+- **被测仓库**：运行时用 `--repo` / `-r` 指定，无默认路径
+
+## 测试输入
+
+**格式**：JSONL，一行一条，UTF-8。
+
+```json
+{
+  "id": "R01",
+  "query": "...",
+  "reference_answer": "...",
+  "category_l1": "检索",
+  "category_l2": "函数"
+}
+```
+
+| 字段 | 必填 | 说明 |
+|------|------|------|
+| `id` | 是 | 题号，如 `R01` / `E03` / `D05` |
+| `query` | 是 | 给 Agent 的问题 |
+| `reference_answer` | 是 | 参考答案（Judge 对照） |
+| `category_l1` | 建议 | 一级分类：`检索` / `解读` / `依赖`（仅报告分组） |
+| `category_l2` | 可选 | 二级分类（仅报告分组） |
+| `level0` / `level1` / `difficulty` / `language` | 可选 | 元数据，Judge 不读取 |
+
+**默认测试集**：`scripts/qa_eval/data/test-set.jsonl`（完整集 20 条：检索 7 + 解读 7 + 依赖 6；可按需增删行）。
+
+## 目录结构
+
+```
+scripts/qa_eval/
+├── agent_runner.py         # Stage 1a：builtin 多轮 Agent（with / without）
+├── external_agent.py       # Stage 1b：Claude Code / DevEco Code 外部 Agent
+├── my_answer_accuracy.py   # Judge 指标（双 prompt 0–5 归一化）
+├── eval_metrics.py         # Stage 2：对 JSONL 批量打分
+├── stats_scores.py         # Stage 3：answer_accuracy_score 汇总
+├── stats_efficiency.py     # Stage 4：解析 Agent 日志（首响应/轮次/耗时/Token/内存）
+├── memory_monitor.py       # 进程树 RSS 采样（Linux /proc；WSL 可用）
+├── llm_config.py           # DashScope / 智谱 provider 预设
+├── run_pipeline.py         # 编排 Stage 1–4 + A/B 报告
+├── _test_deveco_probe.py   # DevEco 单题探测脚本（开发调试用）
+├── requirements.txt
+├── data/                   # 测试集 + 报告（报告不入库）
+│   ├── test-set.jsonl      # 测试集（入库）
+│   └── report-{host}.txt   # 完整 A/B 报告（gitignore，留在 data/）
+└── log/                    # 流水线中间产物（整目录 gitignore）
+    ├── result-with-{host}.jsonl
+    ├── result-without-{host}.jsonl
+    ├── result-*-{host}-scored.jsonl
+    ├── agent-with-{host}.log
+    ├── agent-without-{host}.log
+    ├── eval_metrics.log    # Judge 运行日志（若有）
+    └── traces/             # DevEco session 导出（仅 deveco-code 宿主）
+        ├── with-deveco/
+        │   └── R01-ses_*.json
+        └── without-deveco/
+            └── R01-ses_*.json
+```
+
+**Git 入库规则**
+
+| 路径 | 是否提交 |
+|------|----------|
+| `scripts/qa_eval/*.py`、`README.md`、`requirements.txt` | 是 |
+| `data/test-set.jsonl` | 是 |
+| `data/report*.txt` | 否 |
+| `log/` 下全部 | 否 |
+| `__pycache__/` | 否 |
+
+**与旧版路径对照**（若你手头是早期文档）：
+
+| 旧路径 | 现路径 |
+|--------|--------|
+| `data/test.jsonl` | `data/test-set.jsonl` |
+| `data/result-*.jsonl` | `log/result-*-{host}.jsonl` |
+| `data/agent-*.log` | `log/agent-*-{host}.log` |
+| `data/report.txt` | `data/report-{host}.txt` |
+
+## 测试流程
+
+```
+test-set.jsonl
+    ↓
+Stage 1  agent_runner.py / external_agent.py（run_pipeline ab 内置）
+         with    : homegraph MCP / HomegraphQuery + ReadFile
+         without : grep/rg + read（无 homegraph）
+         产出: log/result-*-{host}.jsonl + log/agent-*-{host}.log
+         （deveco-code 额外产出 log/traces/{arm}-deveco/*.json）
+    ↓
+Stage 2  eval_metrics.py     → log/result-*-{host}-scored.jsonl
+    ↓
+Stage 3  stats_scores.py     → 准确率汇总（并入 report-{host}.txt）
+Stage 4  stats_efficiency.py → 效率 + 内存汇总（终端 + report-{host}.txt）
+    ↓
+run_pipeline.py ab           → data/report-{host}.txt
+```
+
+**A/B 唯一变量**：Agent 是否可用 homegraph。两臂使用**同一 Agent 宿主、同一 max_turns（builtin）**；without **不是裸 LLM**，仍是多轮 grep/read Agent。
+
+### Stage 1 工具对照
+
+| 臂 | builtin 工具 | Claude / DevEco |
+|----|--------------|-----------------|
+| **with** | `HomegraphQuery`、`ReadFile` | MCP `homegraph_explore` / `homegraph_node` 等 + 内置 read/grep |
+| **without** | `SearchText`(rg)、`FindFiles`、`ReadFile` | 仅内置 grep/read；DevEco 在 `.deveco/deveco.jsonc` 中 deny homegraph 工具 |
+
+## 测试输出
+
+### 核心指标（`report-{host}.txt` 末尾【A/B 汇总表】）
+
+| 指标 | 含义 | A/B 怎么看 |
+|------|------|------------|
+| 准确率 均值 | Judge 的 `answer_accuracy_score`（0–1）全题平均 | Δ > 0 表示 with 答案质量更高 |
+| 准确率 中位数 | 同上，中位数（抗极端值） | 与均值交叉验证 |
+| Judge 成功/总数 | 成功打分数 / 总题数 | 应接近 100%；失败查 API/JSONL |
+| 平均轮次 | 每题 LLM 工具循环次数（日志 `the N turn` 最大 N）再平均 | **越低越好**；with 理想上更低 |
+| 平均耗时 (秒) | 每题从 `Evaluate N:` 到下一题开始的端到端时间再平均 | **越短越好** |
+| 平均 Token (k) | 每题 `totalTokenCount` 累加再平均，单位 k | **越少越好** |
+| 平均首响应 (秒) | 每题从 `Evaluate N:` 到第一次 LLM 返回再平均 | 参考项 |
+| 平均峰值内存 (MB) | Agent + MCP 子进程树 RSS 峰值再平均 | **越低越好**；Linux/WSL 才有数 |
+| 最大峰值内存 (MB) | 单题 RSS 峰值最大值 | 观察 OOM 风险 |
+
+Δ 列均为 **with − without**。
+
+### JSONL 产出字段（Stage 1）
+
+每条在测试集字段基础上追加：
+
+```json
+{
+  "output_answer": "---\nHomegraphQuery\n...\n---\n\n最终自然语言答案…",
+  "agent_status": "success",
+  "agent_error": null,
+  "agent_backend": "deveco-code-with-homegraph",
+  "agent_host": "deveco-code",
+  "agent_model": "glm-4.5-flash",
+  "agent_turns": 2,
+  "agent_duration_ms": 73200,
+  "agent_usage": { "total_tokens": 9249 },
+  "agent_memory_mb": { "peak_rss_mb": 412.5, "avg_rss_mb": 380.2 },
+  "ab_arm": "with-homegraph",
+  "deveco_session_id": "ses_101dd0359ffeWUPIajCOuBEQtx",
+  "agent_trace_file": "log/traces/with-deveco/R02-ses_101dd0359ffeWUPIajCOuBEQtx.json",
+  "agent_tools_used": ["homegraph_homegraph_explore", "read"],
+  "agent_used_homegraph": true,
+  "agent_answer_source": "session_export"
+}
+```
+
+| 字段 | 说明 |
+|------|------|
+| `output_answer` | 工具调用块（`---` 包裹）+ 最终答案；Judge 会剥工具块再打分 |
+| `agent_status` | `success` / `error` |
+| `agent_memory_mb` | 答题期间进程树 RSS（见「内存采样」） |
+| `deveco_session_id` | DevEco 会话 ID（`deveco-code` 宿主） |
+| `agent_trace_file` | 相对 `scripts/qa_eval/` 的 session 导出 JSON 路径 |
+| `agent_used_homegraph` | with 臂是否实际调用了 homegraph MCP 工具 |
+
+Judge 追加：`answer_accuracy_score`（0–1）、`evaluation_status`（`success` / `failed`）。
+
+### Agent 日志格式（`agent-*-{host}.log`）
+
+```
+2026-06-23 09:25:21.052447 Evaluate 1:
+2026-06-23 09:25:21.052571 the 1 turn
+2026-06-23 09:25:22.321954 first token          ← 第一次 LLM API 返回
+2026-06-23 09:25:22.321954 totalTokenCount = 349
+2026-06-23 09:25:27.771606 the 2 turn
+2026-06-23 09:25:28.861895 totalTokenCount = 947
+2026-06-23 09:25:30.102441 sessionID = ses_...   ← DevEco 专有
+2026-06-23 09:25:30.102441 tools = homegraph_homegraph_explore, read
+2026-06-23 09:25:30.102441 session export → log/traces/with-deveco/R01-ses_....json
+2026-06-23 09:25:30.102441 peakRssMb = 412.5
+2026-06-23 09:25:30.102441 avgRssMb = 380.2
+2026-06-23 09:25:30.102441 completed (73200ms)
+```
+
+## Agent 轨迹（Trace）
+
+**适用宿主**：主要为 `deveco-code`（每题自动 `deveco export <session_id>`）。
+
+| 查看方式 | 命令 / 路径 |
+|----------|-------------|
+| 导出 JSON | `log/traces/{with\|without}-deveco/<ID>-ses_<session>.json` |
+| DevEco CLI | `deveco export <session_id>` 或 `deveco session list`（标题 `qa-eval-{arm}-{id}`） |
+| 报告索引 | `report-{host}.txt` 中【Agent 轨迹 / DevEco Session】表 |
+
+轨迹 JSON 含完整 `messages` / `parts`（用户问题、工具 input/output、assistant 文本、token 统计），用于人工复盘 Agent 是否按预期调用 `homegraph_explore`。
+
+`claude-code` 宿主将 stream-json 解析进 `output_answer`，不单独落 trace 文件。
+
+## 内存采样
+
+- **实现**：`memory_monitor.py` 在 Agent 子进程存活期间每 0.25s 采样进程树 RSS（Linux `/proc`）。
+- **写入**：JSONL `agent_memory_mb`；日志 `peakRssMb` / `avgRssMb`；报告「平均/最大峰值内存」。
+- **平台**：**Linux 原生 / WSL** 有数据；**Windows 原生** 无 `/proc`，显示 `N/A`，不影响跑题与准确率/耗时/Token 指标。
+- **采样范围**：builtin / 外部 CLI 的 **子进程树**（含 homegraph MCP 子进程）。
+
+## Agent 宿主（`--agent-host`）
+
+| 宿主 | 说明 | Agent 前置条件 | 报告文件 |
+|------|------|----------------|----------|
+| `builtin`（默认） | Python 内置多轮 Agent + 智谱/DashScope | `ZHIPU_API_KEY` 或 `DASHSCOPE_API_KEY` | `report-builtin.txt` |
+| `claude-code` | Claude Code CLI（`claude -p` + MCP） | `claude login` 已登录 | `report-claude.txt` |
+| `deveco-code` | DevEco Code / opencode CLI | `deveco` 在 PATH，DevEco provider 已配置 | `report-deveco.txt` |
+
+**注意**：`--provider zhipu` 只影响 **builtin Agent** 和 **Judge**；`deveco-code` / `claude-code` 使用各自 CLI 的账号，不读 `ZHIPU_API_KEY`。
+
+### DevEco Code 配置要点
+
+```bash
+deveco providers login    # 选 Zhipu AI，输入 API Key
+# 凭证目录（Windows）: C:\Users\<你>\.config\deveco
+```
+
+- pipeline 会在被测仓库写入 `.deveco/deveco.jsonc`（with 臂挂 homegraph MCP + agent prompt；without 臂 deny homegraph 工具）。
+- TUI 若提示 **DEVECO_HOME**，那是 DevEco **Studio** 安装路径（编译用）；**跑 qa_eval 可跳过**。
+- 可选 `--deveco-model zhipuai/glm-4.5-flash`（格式 `provider/model`，用 `deveco models` 查看）。
+- 可选 `--deveco-attach http://127.0.0.1:4096` 或 `QA_EVAL_DEVECO_ATTACH` 复用已运行的 `deveco serve`，减少冷启动。
+
+Judge（Stage 2）三种宿主共用，仍需 `ZHIPU_API_KEY` 或 `DASHSCOPE_API_KEY`。
+
+## 快速开始
+
+```bash
+pip install -r scripts/qa_eval/requirements.txt \
+  -i https://pypi.tuna.tsinghua.edu.cn/simple
+
+export DASHSCOPE_API_KEY="sk-xxxxxxxx"
+# 或智谱（Key 格式 id.secret，不要加 sk- 前缀）：
+# export ZHIPU_API_KEY="xxxxxxxx.yyyyyyyy"
+
+cd /path/to/homegraph && npm run build
+node dist/bin/homegraph.js sync /path/to/your/repo
+
+python scripts/qa_eval/run_pipeline.py ab -r /path/to/your/repo
+# 智谱：
+# python scripts/qa_eval/run_pipeline.py ab -r /path/to/your/repo --provider zhipu
+```
+
+### 三种宿主示例
+
+```bash
+# ① builtin
+export ZHIPU_API_KEY="your-id.your-secret"
+python scripts/qa_eval/run_pipeline.py ab -r /path/to/repo --provider zhipu --agent-host builtin
+
+# ② Claude Code（Agent 用 Claude 账号，Judge 仍用 ZHIPU_API_KEY）
+claude login
+python scripts/qa_eval/run_pipeline.py ab -r /path/to/repo --provider zhipu --agent-host claude-code
+
+# ③ DevEco Code
+deveco providers login
+python scripts/qa_eval/run_pipeline.py ab -r /path/to/repo --provider zhipu --agent-host deveco-code
+# python scripts/qa_eval/run_pipeline.py ab -r /path/to/repo --provider zhipu --agent-host deveco-code --deveco-model zhipuai/glm-4.5-flash
+
+# ④ 三种依次跑（各写各的报告）
+python scripts/qa_eval/run_pipeline.py hosts -r /path/to/repo --provider zhipu
+```
+
+产出示例（每种宿主一套，互不覆盖）：
+
+| 宿主 | JSONL / 日志（`log/`） | 报告（`data/`） |
+|------|------------------------|-----------------|
+| builtin | `result-with-builtin.jsonl`、`agent-with-builtin.log` | `report-builtin.txt` |
+| claude-code | `result-with-claude.jsonl`、`agent-with-claude.log` | `report-claude.txt` |
+| deveco-code | `result-with-deveco.jsonl`、`agent-with-deveco.log`、`traces/` | `report-deveco.txt` |
+
+只重打报告、不重跑 Agent/Judge（无需 `--repo`）：
+
+```bash
+python scripts/qa_eval/run_pipeline.py ab --no-agent --no-judge
+# 保留上次 log 中间文件：
+python scripts/qa_eval/run_pipeline.py ab -r /path/to/repo --keep-log
+```
+
+### `report-{host}.txt` 结构
+
+```
+################################################################################
+#                         A/B 完整评测报告                                      #
+################################################################################
+
+【输入文件】
+【WITH homegraph】效率明细          ← 逐题 + 汇总（首响应/轮次/耗时/Token/内存）
+【WITHOUT homegraph】效率明细
+【WITH / WITHOUT homegraph】准确率统计
+按类别准确率                        ← category_l1 分组 with/without 均分与 Δ
+逐题对比                            ← 得分、答案摘要；with 赢/平/输 计数
+【Agent 轨迹 / DevEco Session】      ← deveco-code 专有（session_id + 轨迹路径）
+【A/B 汇总表】                      ← 两臂核心指标并排 + Δ
+```
+
+## Stage 2 — Judge（`eval_metrics.py`）
+
+```bash
+python scripts/qa_eval/eval_metrics.py \
+  -i scripts/qa_eval/log/result-with-builtin.jsonl \
+  -o scripts/qa_eval/log/result-with-builtin-scored.jsonl \
+  -w 2 --provider zhipu
+```
+
+| 参数 | 默认 | 说明 |
+|------|------|------|
+| `-i` / `--input` | — | Agent 产出 JSONL |
+| `-o` / `--output` | `*-scored.jsonl` | 打分结果 |
+| `-w` / `--workers` | `1` | 并发线程数 |
+| `-m` / `--model` | 随 provider | Judge 模型 |
+| `--provider` | 自动检测 | `dashscope` / `zhipu` |
+
+## Stage 3 / 4 — 统计脚本
+
+```bash
+python scripts/qa_eval/stats_scores.py \
+  -i scripts/qa_eval/log/result-with-builtin-scored.jsonl
+
+python scripts/qa_eval/stats_efficiency.py \
+  -l scripts/qa_eval/log/agent-with-builtin.log
+```
+
+`stats_efficiency.py` 输出逐题首响应、轮次、总时间、总 Token、**峰值内存**；日志缺失时回退 JSONL `agent_usage`（无轮次/耗时/首响应）。
+
+## `run_pipeline.py` 命令
+
+### `ab` — A/B 全流程
+
+```bash
+python scripts/qa_eval/run_pipeline.py ab -r /path/to/your/repo [选项]
+```
+
+| 参数 | 默认 | 说明 |
+|------|------|------|
+| `--repo`, `-r` | — | **被测仓库**（跑 Agent 时必填） |
+| `--dataset`, `-d` | `data/test-set.jsonl` | 测试集 |
+| `--with-jsonl` / `--without-jsonl` | `log/result-*.jsonl` | Agent 产出 |
+| `--with-scored` / `--without-scored` | `log/result-*-scored.jsonl` | Judge 产出 |
+| `--with-log` / `--without-log` | `log/agent-*.log` | Agent 日志 |
+| `--report` | `data/report-{host}.txt` | 完整报告路径 |
+| `--model`, `-m` | 随 provider | builtin Agent + Judge 模型 |
+| `--provider` | 自动检测 | `dashscope` / `zhipu` |
+| `--workers`, `-w` | `1` | Judge 并发 |
+| `--max-turns` | `8` | builtin Agent 最多工具轮次 |
+| `--agent-host` | `builtin` | `builtin` / `claude-code` / `deveco-code` / `all` |
+| `--homegraph-bin` | 自动检测 | 优先本地 `dist/bin/homegraph.js` |
+| `--deveco-model` | `zhipuai/glm-4.5-flash` | DevEco Agent 模型（仅 deveco-code） |
+| `--deveco-attach` | `$QA_EVAL_DEVECO_ATTACH` | 复用 `deveco serve` 地址 |
+| `--no-agent` | — | 跳过 Stage 1 |
+| `--no-judge` | — | 跳过 Stage 2 |
+| `--keep-log` | — | 跑 Agent 前**不清空** `log/` |
+
+### `hosts` — 多宿主依次跑
+
+等价于对 `builtin,claude-code,deveco-code` 各跑一遍 `ab`：
+
+```bash
+python scripts/qa_eval/run_pipeline.py hosts -r /path/to/repo --provider zhipu
+python scripts/qa_eval/run_pipeline.py hosts -r /path/to/repo --agent-hosts claude-code,deveco-code
+```
+
+### `score` — 单路 Judge + 统计
+
+```bash
+python scripts/qa_eval/run_pipeline.py score \
+  -i scripts/qa_eval/log/result-with-builtin.jsonl \
+  -l scripts/qa_eval/log/agent-with-builtin.log
+```
+
+## 外部 Agent 产出（可选）
+
+若用 CodeGenie / Trae 等外部系统产出**同格式** JSONL + 日志：
+
+```bash
+python scripts/qa_eval/run_pipeline.py ab --no-agent -r /path/to/repo
+```
+
+## 常见问题
+
+| 现象 | 处理 |
+|------|------|
+| Claude 准确率全低 / `Not logged in` | `claude login` 后重跑；pipeline 首题会 fail-fast |
+| `deveco-code` exit 1 / `Model not found` | 用 `deveco models` 里的 `zhipuai/...` 名，或 `--deveco-model zhipuai/glm-4.5-flash` |
+| DevEco `ServeError` / 端口占用 | `netstat -ano \| findstr :4096` 后结束进程，或不加 `--deveco-attach` |
+| DevEco 凭证损坏 | `deveco providers reset` 后重新 login |
+| `401` / Judge 全失败 | 检查 Key；智谱用 `--provider zhipu`，Key 格式 `id.secret` |
+| `Cannot find module 'arkanalyzer'` | 发布包 < 下一版时未打进 bundle；升级 homegraph，或源码路径 `npm install && npm run build` 后用 `node dist/bin/homegraph.js sync` |
+| `rg not found on PATH` | 安装 ripgrep（without 臂 builtin 需要） |
+| 日志解析 0 条任务 | 确认 log 含 `Evaluate N:` 行 |
+| 内存全为 N/A | Windows 原生无 `/proc`；用 WSL/Linux 测内存，或忽略该列 |
+| with 臂未用 homegraph | 看报告轨迹表 `HG` 列或 `agent_used_homegraph`；DevEco with 臂有专用 prompt |
+| 分数偏低但答案看起来对 | 检查 `output_answer` 是否只剩工具块、无最终自然语言答案 |
+| pip 慢 | 清华镜像（见快速开始） |
+
+## 最小通路（仅 Judge 单条）
+
+```bash
+export DASHSCOPE_API_KEY="sk-xxx"
+head -1 scripts/qa_eval/log/result-with-builtin.jsonl > /tmp/one.jsonl
+python scripts/qa_eval/eval_metrics.py -i /tmp/one.jsonl -o /tmp/one-scored.jsonl
+python scripts/qa_eval/stats_scores.py -i /tmp/one-scored.jsonl
+```