# 商服意图识别 PE 评测链路一键化
类型：`diagnostic-tool`
## 1.1 为什么值得做
这个主题不是噪音：片段显示用户反复围绕同一条链路推进，从 Fornax trace 还原线上 PlanAgent 输入，到按线上 prompt format 注入新增意图 PE，再到扩充测试集并写回飞书表。当前痛点集中在 trace/span 定位、线上竞争环境复现、PE 注入粒度和评测集回写，适合沉淀成一键诊断与小规模评测工具。
## 1.2 学习实验 / Before-After
## 诊断流程样例
### 入口
```bash
cd /Users/bytedance/Documents/job-bu/data-analysis-workspace
python -m intent_pe_eval build \
--fornax-url 'https://fornax/trace?id=4d506c544f44882a' \
--out runs/intent_pe_eval/2026-05-19-a
python -m intent_pe_eval eval \
--input runs/intent_pe_eval/2026-05-19-a/normalized_input.json \
--dataset projects/.../商品领域已打标session.xlsx \
--pe-file runs/intent_pe_eval/2026-05-19-a/new_intents_pe.md
```
### 输入来源
| 输入 | 作用 | 必查点 |
| --- | --- | --- |
| Fornax URL / span id | 回溯线上 PromptFormat | 区分 span id 与 trace id |
| trace 里的 agent_list/tool_list | 复现线上 PlanAgent 竞争环境 | 只能追加或替换 PE，不重造环境 |
| 已打标 session 表 | 构建评测集 | 每个意图样本数、sessionId、来源可追溯 |
| PE 定义 | 注入新增意图 | 新意图逐个放入 PE，不包成总入口 |
| Ark 输出 | 计算准召 | 解析命中意图、理由、异常 |
### 核心检查
1. URL 中的 `id` 如果是 PromptFormat span id，工具自动反查完整 trace id。
2. 还原模板、变量和最终 system message，记录字符数与变量清单。
3. 保留线上原始 `agent_list/tool_list`，只按配置注入新增意图 PE。
4. 按每个意图至少 100 条的目标检查样本覆盖，并保留 sessionId 与反查来源。
5. 调 Ark 小流量评测，生成 intent_metrics.xlsx、error_cases.csv、run_manifest.json。
### 成功信号
- `trace_resolved=true`，同时有 span id 与 trace id。
- `agent_env_mode=online_competition`，线上 agent/tool 未被重建。
- 每个新增意图都有独立 PE 条目和独立样本统计。
- 输出表能直接写回飞书，且本地审计表可从 sessionId 反查原始会话。
### 失败信号
- 把 span id 当 trace id 导致上下文缺失。
- 把多个新意图包成一个测试 skill，破坏真实竞争粒度。
- 只看模型单条输出，不统计分意图准召和误召样例。
- 写回飞书后缺少本地 run_manifest，无法复现实验。
## 1.3 落地动作
- 新增工具入口：在 /Users/bytedance/Documents/job-bu/data-analysis-workspace/tools/ 下增加 intent_pe_eval/cli.py，提供 `python -m intent_pe_eval build --fornax-url <url>`、`eval --dataset <xlsx/csv> --pe-file <md/json>`、`audit --run-id <id>` 三个命令；同时保留一个轻量 README，说明 trace URL、span id、飞书表导出、本地标注表的使用方式。
- 输入来源标准化：支持 Fornax URL 或 trace_id/span_id、本地已打标商品领域 session 表、PE 定义文件、线上 trace 还原出的 agent_list/tool_list、Ark 调用配置；解析阶段显式区分 PromptFormat span id 与完整 trace id，输出 normalized_input.json、rendered_system_message.txt 和 source_manifest.csv。
- 核心检查步骤：先校验 trace/span 是否能定位到目标 PromptFormat，再检查模板条数、变量数、最终 system message 长度、agent_list/tool_list 是否保留线上原貌；随后按用户纠正后的粒度把新增意图逐个写入 PE，而不是包成一个总入口；最后用 Ark 对分层抽样集跑准召、误召和未召回样例。
- 成功/失败信号与落地路径：成功信号是每个意图样本数达标、线上竞争环境复现、每条样本有 sessionId/来源/模型输出/命中意图/证据、结果可写回飞书或本地 xlsx；失败信号包括 span/trace 混淆、PE 被合并成总入口、agent_list 被重建、样本覆盖不足或 Ark 输出无法解析。建议先落地为 job-bu 本地工具，再抽成 Codex skill `intent-pe-eval`，把常用检查表和错误修复建议写入 SKILL.md。