agent-insight 0.5.0 → 0.5.2

package/.next/standalone/Evaluation_and_Research/agent_evaluator_research_qna.md

@@ -0,0 +1,1379 @@
+# Agent 评估器调研问答
+
+调研日期：2026-07-06
+
+这份文档用于承接 `agent_evaluator_industry_research.md` 里的细节问题。每个问题独立回答，后续可以继续追加。
+
+## Q1：DeepEval 和 Ragas 的“任务完成度”逻辑是怎么样？
+
+### 简短结论
+
+DeepEval 和 Ragas 都把“任务完成度”理解成：**Agent 最终有没有达成用户目标**，而不是中间有没有严格按照某条路径执行。
+
+但两者的评估形态不一样：
+
+| 项目 | 指标名 | 主要输入 | 是否需要参考答案 | 输出形态 | 核心逻辑 |
+| --- | --- | --- | --- | --- | --- |
+| DeepEval | [`TaskCompletionMetric`](https://deepeval.com/docs/metrics-task-completion) | 完整 agent trace，可选显式 `task` | 默认不需要 | 0-1 分数，可带 reason | 从 trace 中抽取 task 和 outcome，再用 LLM judge 评估 outcome 与 task 的对齐程度 |
+| Ragas | [`AgentGoalAccuracyWithReference`](https://docs.ragas.io/en/stable/concepts/metrics/available_metrics/agents/#with-reference) | 多轮消息/工具调用 + reference | 需要 | 0/1 | 判断工作流最终状态/结果是否符合给定 reference outcome |
+| Ragas | [`AgentGoalAccuracyWithoutReference`](https://docs.ragas.io/en/stable/concepts/metrics/available_metrics/agents/#without-reference) | 多轮消息/工具调用 | 不需要 | 0/1 | 从对话中推断用户目标和实际达成结果，再判断是否达成 |
+
+### DeepEval：TaskCompletionMetric 的逻辑
+
+DeepEval 的任务完成度是一个 **LLM-as-a-judge、trace-level、referenceless** 指标。它不是拿最终回答和标准答案做字符串比较，而是读取 agent 的完整执行 trace，判断这次运行最终是否完成了任务。
+
+官方给出的计算口径可以概括为：
+
+```text
+Task Completion Score = AlignmentScore(Task, Outcome)
+```
+
+其中：
+
+- `Task`：从 trace 中抽取出来的用户任务；也可以由调用方通过 `task` 参数显式传入。
+- `Outcome`：从 trace 中抽取出来的最终结果/实际完成状态。
+- `AlignmentScore`：由 LLM judge 判断 `Outcome` 与 `Task` 的对齐程度。
+
+DeepEval 的几个关键点：
+
+1. **默认无参考答案**
+   它默认不需要 expected output / reference。`task` 参数也默认是 `None`，由评估器从 trace 里推断。如果你想固定评估目标，可以显式传入 `task`。
+
+2. **依赖 trace，而不是只看 final answer**
+   DeepEval 文档明确说该指标会分析 agent 的 full trace 来判断任务成功，因此需要先设置 tracing，并把 `TaskCompletionMetric()` 绑定到被观测的 agent run。
+
+3. **分数是连续分**
+   默认输出 0-1 的分数，并用 `threshold` 判断是否通过。默认 threshold 是 0.5。也可以开 `strict_mode`，这时变成严格二值：完美完成给 1，否则给 0。
+
+4. **可以输出 reason**
+   `include_reason` 默认开启，所以它不只是给分，还会解释为什么这么判。这一点适合 Agent Insight 后续做 `SkillIssue` / failure attribution。
+
+5. **它评估 outcome，不评估是否按计划执行**
+   DeepEval 自己也把 `TaskCompletionMetric` 和 `PlanAdherenceMetric` 区分开：前者回答“是否完成任务”，后者回答“是否遵守计划”。所以一个 agent 可以没按原计划走，但最终完成任务；也可以严格按计划走，但任务失败。
+
+#### DeepEval 的例子怎么理解
+
+官方示例是一个 trip planner agent：它根据目的地和天数生成 itinerary，并找餐厅。评估器会读取 trace 中的函数/工具调用和最终返回结果，抽取：
+
+```text
+Task: 用户希望完成一次旅行规划
+Outcome: agent 返回了景点行程和餐厅列表
+```
+
+然后由 LLM judge 判断 outcome 是否足够满足 task。它不要求你提前写一个标准答案，比如“必须包含 Eiffel Tower”；而是判断最终结果是否和任务目标对齐。
+
+#### DeepEval 适合 Agent Insight 怎么借鉴
+
+DeepEval 的逻辑很适合作为 Agent Insight 里的“无参考任务完成度”版本：
+
+```text
+输入：
+- 用户原始任务
+- 完整 trace summary
+- 最终输出
+- 可选：显式目标 task / rubric
+
+评估：
+- 从 trace 中抽取用户目标
+- 从 trace 和最终输出中抽取实际达成结果
+- 判断达成程度，输出 score + reason + evidence
+```
+
+但如果要落地到 Agent Insight，我建议比 DeepEval 多做两点：
+
+1. **要求 evidence span**
+   给分理由必须引用具体 message/tool/span，否则很难用于后续优化。
+
+2. **把“任务完成度”和“失败类型”分开**
+   任务完成度给总分；失败类型单独标注，例如 `missing_key_requirement`、`wrong_final_answer`、`tool_result_ignored`、`asked_user_when_should_act`。
+
+### Ragas：AgentGoalAccuracy 的逻辑
+
+Ragas 把 agent 任务完成度叫做 **Agent Goal Accuracy**。它评估的是 agent 是否识别并达成用户目标。官方文档明确说这是一个 **binary metric**：达成给 1，没有达成给 0。
+
+Ragas 提供两个版本。
+
+### Ragas 版本 1：With Reference
+
+[`AgentGoalAccuracyWithReference`](https://docs.ragas.io/en/stable/concepts/metrics/available_metrics/agents/#with-reference) 的输入包括：
+
+- `user_input`：多轮会话消息，通常包含 `HumanMessage`、`AIMessage`、`ToolCall`、`ToolMessage`。
+- `reference`：期望/理想结果，也就是 reference outcome。
+
+它的判断方式是：
+
+```text
+用户目标 + agent 多轮执行过程 + 最终状态
+对比 reference outcome
+=> 判断是否达成，输出 1 或 0
+```
+
+官方例子是订餐：
+
+```text
+用户：帮我订 8 点最近最好的中餐厅
+agent：搜索中餐厅
+工具：返回 Golden Dragon / Jade Palace
+用户：选 Golden Dragon
+agent：调用订座工具
+工具：返回订座成功
+agent：告诉用户订座成功
+
+reference：8 点订到了某家中餐厅
+score：1.0
+```
+
+这里重点不是 agent 有没有用某个固定工具名，也不是中间话术是否完全一样，而是最终结果是否满足 reference：**8 点中餐厅订座成功**。
+
+#### With Reference 的优点
+
+- 更适合离线数据集评测。
+- 判断更稳定，因为目标状态由 reference 固定。
+- 很适合业务流程型 agent：订票、下单、改配置、生成报告、修 bug、查询并汇总等。
+
+#### With Reference 的缺点
+
+- 需要为每个 case 写 reference outcome。
+- reference 写得太宽会放过错误；写得太窄会误伤合理替代方案。
+- 二值评分不够细，难以表达“部分完成”。
+
+### Ragas 版本 2：Without Reference
+
+[`AgentGoalAccuracyWithoutReference`](https://docs.ragas.io/en/stable/concepts/metrics/available_metrics/agents/#without-reference) 不需要 reference。它会从 conversation 中同时推断：
+
+- 用户原本想达成什么目标。
+- agent 最终实际达成了什么结果。
+
+然后判断两者是否一致：
+
+```text
+从对话推断 intended goal
+从对话和工具结果推断 achieved outcome
+比较 intended goal 与 achieved outcome
+=> 输出 1 或 0
+```
+
+它和 DeepEval 的无参考任务完成度很像，但差别在于：
+
+- DeepEval 输出连续分数，Ragas AgentGoalAccuracy 输出二值。
+- DeepEval 更强调 full trace 中抽取 task/outcome 后做 alignment score。
+- Ragas 更强调多轮消息和最终 goal achieved / not achieved 的判断。
+
+#### Without Reference 的优点
+
+- 不需要预先标注 reference，适合线上 trace 抽样评估。
+- 适合用户目标比较自然、最终是否达成相对清楚的任务。
+
+#### Without Reference 的风险
+
+- 用户目标模糊时，LLM judge 可能推断错。
+- 多目标任务里，二值结果会丢失“完成了 3/5 个要求”的信息。
+- 如果 trace 缺少工具返回或最终状态，judge 可能只能根据 agent 自述判断，容易被“我已经完成了”误导。
+
+### 两者最核心的差异
+
+| 对比点 | DeepEval TaskCompletionMetric | Ragas AgentGoalAccuracy |
+| --- | --- | --- |
+| 默认是否需要 reference | 不需要 | 有 with-reference 和 without-reference 两种 |
+| 分数类型 | 连续分 0-1，可 strict 二值 | 二值 0/1 |
+| 主要评估对象 | trace 中抽取的 task 与 outcome 的对齐程度 | 用户目标是否被达成 |
+| 是否强调完整 trace | 是，官方要求 tracing | 是，输入是多轮消息/工具调用 |
+| 是否适合数据集离线评测 | 适合，但无参考时稳定性依赖 judge | with-reference 很适合 |
+| 是否适合线上质量监控 | 适合 | without-reference 适合 |
+| 对“部分完成”的表达 | 更自然，连续分可表达部分完成 | 原生表达较弱，除非拆成多个 goal 或扩展 rubric |
+
+### 参考链接
+
+- DeepEval Task Completion: https://deepeval.com/docs/metrics-task-completion
+- Ragas Agentic or Tool use metrics: https://docs.ragas.io/en/stable/concepts/metrics/available_metrics/agents/
+- Ragas Agent Goal Accuracy with reference: https://docs.ragas.io/en/stable/concepts/metrics/available_metrics/agents/#with-reference
+- Ragas Agent Goal Accuracy without reference: https://docs.ragas.io/en/stable/concepts/metrics/available_metrics/agents/#without-reference
+
+## Q2：DeepEval / Ragas 的工具评估是否需要参考工具调用？Phoenix 是否不需要？
+
+### 简短回答
+
+基本是的。
+
+| 项目 | 指标 | 是否需要参考工具调用 | 说明 |
+| --- | --- | --- | --- |
+| DeepEval | [`ToolCorrectnessMetric`](https://deepeval.com/docs/metrics-tool-correctness) | 需要 | `expected_tools` 是必填；核心分数是把 `tools_called` 和 `expected_tools` 做匹配。`available_tools` 可选，用于让 LLM 额外判断工具选择是否最优。 |
+| Ragas | [`ToolCallAccuracy`](https://docs.ragas.io/en/stable/concepts/metrics/available_metrics/agents/#tool-call-accuracy) | 需要 | 需要 `reference_tool_calls`，比较实际调用和期望调用的顺序、工具名、参数。 |
+| Ragas | [`ToolCallF1`](https://docs.ragas.io/en/stable/concepts/metrics/available_metrics/agents/#tool-call-f1) | 需要 | 需要 `reference_tool_calls`，用 precision / recall / F1 统计实际工具调用与期望工具调用的匹配程度。 |
+| Phoenix | [`Tool Selection`](https://arize.com/docs/phoenix/evaluation/pre-built-metrics/tool-selection) | 不需要 reference tool calls | 需要 `input`、`available_tools`、`tool_selection`，由 LLM judge 判断选的工具是否正确。 |
+| Phoenix | [`Tool Invocation`](https://arize.com/docs/phoenix/evaluation/pre-built-metrics/tool-invocation) | 不需要 reference tool calls | 需要 `input`、`available_tools`、`tool_selection`，其中 `available_tools` 应包含 schema / 参数说明，LLM judge 判断调用参数和格式是否正确。 |
+
+所以更精确地说：Phoenix 不是“什么参考都不需要”，它仍然需要 **可用工具列表 / 工具 schema** 作为判断依据；只是它不要求你为每个 case 预先标注一组“标准工具调用答案”。
+
+### 它们也是局部片段级，而不是整条 trace 级吗？
+
+是的，同理。
+
+Phoenix `Tool Selection` 和 `Tool Invocation` 的默认粒度也更接近 **span-level / 局部工具决策级**，不是天然对整条 trace 给一个综合分。
+
+官方文档里：
+
+- `Tool Selection` 的 Supported Levels 是 `Span: Yes`，适合包含 tool calls 的 LLM spans，用来评估 individual tool selection decisions。
+- `Tool Invocation` 的 Supported Levels 也是 `Span: Yes`，适合 tool spans 或包含 tool calls 的 LLM spans，用来评估 individual tool-calling decisions。
+
+也就是说，典型用法是：
+
+```text
+Tool Selection:
+  一次 LLM 决定要不要调用工具、调用哪些工具
+  => 跑一次 Tool Selection
+
+Tool Invocation:
+  一次 LLM 生成具体工具调用参数
+  => 跑一次 Tool Invocation
+```
+
+如果一条 trace 里有多次工具选择/调用，通常也是逐个片段评估后再聚合：
+
+```text
+trace_tool_selection_score =
+  所有工具选择片段的平均分 / 加权平均分
+
+trace_tool_invocation_score =
+  所有工具调用片段的平均分 / 加权平均分
+```
+
+Phoenix 文档也支持 multi-tool selection / multi-tool invocation：可以把一次 LLM 输出里的多个工具选择或多个工具调用放进同一个 `tool_selection` 字段里评估。但这仍然更像是“一个局部 LLM span 里包含多个工具调用”的评估，不等于整条 trace 的全局 evaluator。
+
+### Phoenix Tool Selection 的评估逻辑
+
+Phoenix `Tool Selection` 回答的是：**LLM 是否为当前任务选择了正确的工具**。
+
+它关注 tool calling 的 **what**：
+
+```text
+用户要做什么？
+系统有哪些可用工具？
+LLM 实际选择了哪个/哪些工具？
+=> 这些工具选得对不对？
+```
+
+它不关心参数是否完整、JSON 是否格式正确、日期是否转成了正确格式；这些属于 `Tool Invocation` 的范围。
+
+#### 输入
+
+Phoenix 官方文档中，`Tool Selection` 需要三个字段：
+
+- `input`：用户问题或多轮会话上下文。
+- `available_tools`：可用工具列表及描述。
+- `tool_selection`：LLM 实际选择的工具。
+
+例如：
+
+```text
+input:
+User: I need to book a flight from New York to Los Angeles.
+User: Tomorrow morning, the earliest available.
+
+available_tools:
+book_flight: Book a flight between two cities. Requires origin, destination, and date.
+search_hotels: Search for hotel accommodations by city and dates.
+get_weather: Get current weather conditions for a location.
+cancel_booking: Cancel an existing flight or hotel reservation.
+
+tool_selection:
+book_flight
+```
+
+#### 判断标准
+
+Phoenix 会用 LLM evaluator 产出二分类结果：
+
+```text
+label: correct | incorrect
+score: 1.0 | 0.0
+explanation: 评估理由
+```
+
+判为 `correct` 的典型条件：
+
+- 工具存在于 `available_tools` 中。
+- 该工具是当前用户任务下最合适的工具。
+- 工具使用是安全且合适的。
+- 如果任务需要多个工具，选择的工具数量也合理。
+
+判为 `incorrect` 的典型条件：
+
+- 调用了不存在的工具，也就是 hallucinated tool。
+- 本来不需要工具，却调用了工具。
+- 本来需要工具，却没有调用工具。
+- 选择了无关或次优工具。
+
+#### 它和 reference-based 工具评估的差异
+
+DeepEval / Ragas 的工具评估通常是：
+
+```text
+实际工具调用 vs 预期工具调用
+```
+
+Phoenix `Tool Selection` 更像是：
+
+```text
+实际工具选择 + 可用工具说明 + 用户任务
+=> LLM judge 判断是否合理
+```
+
+所以它更适合没有标准答案的线上 trace 抽样；但也更依赖 judge 的判断质量，稳定性通常不如有 reference 的精确匹配。
+
+### Phoenix Tool Invocation 的评估逻辑
+
+Phoenix `Tool Invocation` 回答的是：**LLM 在调用工具时，参数、格式和内容是否正确**。
+
+它关注 tool calling 的 **how**：
+
+```text
+工具选了以后，调用方式对不对？
+参数有没有缺？
+参数值是否符合用户上下文？
+格式是否符合 schema？
+有没有幻觉字段或不安全内容？
+```
+
+Phoenix 文档明确说，`Tool Invocation` 不负责判断“是不是选对了工具”；如果要判断工具是否选对，应使用 `Tool Selection`。两个评估器是互补的。
+
+#### 输入
+
+`Tool Invocation` 同样需要三个字段：
+
+- `input`：对话上下文，可以包含多轮历史。
+- `available_tools`：工具 schema 或人类可读的工具参数说明。
+- `tool_selection`：LLM 实际产生的工具调用，包含参数。
+
+例如：
+
+```text
+input:
+User: I need to book a flight from New York to Los Angeles.
+User: Tomorrow morning, the earliest available.
+
+available_tools:
+book_flight: Book a flight between two cities
+  - origin (required): Departure city code, e.g. "JFK", "LAX"
+  - destination (required): Arrival city code
+  - date (required): Flight date in YYYY-MM-DD format
+  - time_preference (optional): "morning", "afternoon", or "evening"
+
+tool_selection:
+book_flight(origin="JFK", destination="LAX", date="2024-01-15", time_preference="morning")
+```
+
+这里 `available_tools` 最好不只是工具名，而是包含参数 schema、必填项、枚举值、格式要求。否则 evaluator 很难判断参数是否正确。
+
+#### 判断标准
+
+Phoenix 会检查：
+
+- **必填参数是否存在**：例如 `origin`、`destination`、`date` 是否都有。
+- **参数值是否来自对话上下文**：例如用户说 New York 到 Los Angeles，参数却填 Paris 就不对。
+- **参数格式是否正确**：例如日期是否符合 `YYYY-MM-DD`。
+- **是否出现 schema 外字段**：例如工具 schema 没有 `meal_preference`，LLM 却编了这个字段。
+- **参数内容是否安全**：例如是否包含不该传给工具的 PII、token、敏感信息。
+- **多工具调用是否都格式正确**：如果一次调用多个工具，需要一起判断。
+
+输出同样是：
+
+```text
+label: correct | incorrect
+score: 1.0 | 0.0
+explanation: 评估理由
+```
+
+#### 一个边界例子
+
+假设用户说：
+
+```text
+Book the earliest flight from New York to Los Angeles tomorrow morning.
+```
+
+工具调用是：
+
+```text
+book_flight(origin="NYC", destination="LAX", date="tomorrow")
+```
+
+这个调用可能在 `Tool Selection` 上是正确的，因为确实选了 `book_flight`。但在 `Tool Invocation` 上可能是错误的，因为：
+
+- `origin` schema 要求 airport code，`NYC` 可能不是可接受机场码。
+- `date` schema 要求 `YYYY-MM-DD`，但实际传了自然语言 `tomorrow`。
+- 如果 schema 要求 `time_preference`，这里也可能缺参数。
+
+这正是 Phoenix 把二者拆开的意义：
+
+```text
+Tool Selection: 选没选对工具
+Tool Invocation: 选对工具后，调用方式对不对
+```
+
+### 参考链接
+
+- DeepEval Tool Correctness: https://deepeval.com/docs/metrics-tool-correctness
+- Ragas Tool Call Accuracy / Tool Call F1: https://docs.ragas.io/en/stable/concepts/metrics/available_metrics/agents/
+- Phoenix Tool Selection: https://arize.com/docs/phoenix/evaluation/pre-built-metrics/tool-selection
+- Phoenix Tool Invocation: https://arize.com/docs/phoenix/evaluation/pre-built-metrics/tool-invocation
+
+## Q3：Phoenix Tool Response Handling 的详细执行逻辑是什么？
+
+### 简短结论
+
+Phoenix [`Tool Response Handling`](https://arize.com/docs/phoenix/evaluation/pre-built-metrics/tool-response-handling) 评估的是：**Agent 拿到工具返回之后，是否正确处理了工具结果，并据此产生了合适输出**。
+
+它的默认评估粒度更接近 **一次工具调用/工具返回被后续 agent 输出消费的局部片段**，也就是 span-level evaluator，而不是天然对整条 trace 直接给一个总分。
+
+它不回答：
+
+- 工具是否选对：这是 `Tool Selection` 的职责。
+- 工具参数是否正确：这是 `Tool Invocation` 的职责。
+
+它回答：
+
+```text
+工具返回了什么？
+Agent 后续输出/重试/跟进动作如何处理这个返回？
+Agent 有没有准确使用工具结果、处理错误、避免泄露敏感信息？
+```
+
+### 它是针对一次工具调用，还是整条 trace？
+
+更准确地说：**它主要针对工具调用后的局部处理片段，不是整条 trace 级别的综合 evaluator**。
+
+Phoenix 官方文档在 Supported Levels 里标的是：
+
+```text
+Span: Yes
+```
+
+适用对象是包含工具结果和 agent 后续输出的 LLM span / tool-consuming span。也就是说，典型用法是：
+
+```text
+一次工具调用 tool_call
++ 这次工具返回 tool_result
++ agent 随后的处理 output
+=> 跑一次 Tool Response Handling
+```
+
+如果一条 trace 里有很多次工具调用，通常有两种做法：
+
+1. **逐个工具调用/工具结果片段评估**
+   对每个“工具结果 -> agent 后续处理”的片段分别跑一次 evaluator，然后得到多条局部评分。
+
+2. **把多个工具调用和结果合并成一次输入**
+   Phoenix 文档也说支持 multi-tool calls：如果 agent 调了多个工具，可以把所有 tool calls 和 results 放进输入里，让 evaluator 判断 agent 是否正确处理了所有结果。
+
+但第二种更像是“手工构造一个包含多工具上下文的局部评估输入”，不等于 Phoenix 自动理解整条 trace 的所有节点、依赖关系和全局任务完成度。
+
+所以如果要对整条 trace 得出一个 Tool Response Handling 总分，需要额外做聚合，例如：
+
+```text
+trace_tool_response_score =
+  所有可评估工具结果片段的平均分
+```
+
+或者更严格：
+
+```text
+trace_tool_response_pass =
+  所有关键工具结果片段都 correct
+```
+
+还可以按工具重要性加权：
+
+```text
+关键业务工具 > 辅助查询工具 > 非关键观察工具
+```
+
+### 输入是什么？
+
+官方要求 4 个输入字段：
+
+| 字段 | 类型 | 含义 |
+| --- | --- | --- |
+| `input` | string | 用户问题或对话上下文 |
+| `tool_call` | string | Agent 发起的工具调用，包括工具名和参数 |
+| `tool_result` | string | 工具返回结果，可以是正常数据、错误、部分结果 |
+| `output` | string | Agent 收到工具结果后的处理结果，可以包含重试、后续调用、最终回复 |
+
+TypeScript 版本字段名是 camelCase：
+
+```text
+toolCall
+toolResult
+```
+
+一个最小例子：
+
+```text
+input:
+What's the weather in Seattle?
+
+tool_call:
+get_weather(location="Seattle")
+
+tool_result:
+{"temperature": 58, "unit": "fahrenheit", "conditions": "cloudy"}
+
+output:
+Seattle is currently 58°F and cloudy.
+```
+
+如果 agent 在工具失败后做了重试，或者调用了多个工具，Phoenix 建议把完整处理序列放进 `output`，不要只放最后一句。多工具调用也可以放在同一次评估里。
+
+### 中间处理逻辑是什么？
+
+Phoenix 的实现形态是 **LLM classification evaluator**。它会把 `input`、`tool_call`、`tool_result`、`output` 放进内置 prompt，让 LLM judge 判断 `output` 是否正确处理了 `tool_result`。
+
+可以把中间判断拆成 6 类检查。
+
+#### 1. 是否准确抽取工具结果里的数据
+
+检查 agent 输出中的实体、数字、日期、状态、字段是否来自 `tool_result`，有没有漏读或错读。
+
+```text
+tool_result:
+{"restaurant": "Cafe Luna", "rating": 4.2}
+
+output:
+Cafe Luna has a 4.2 rating.
+
+=> correct
+```
+
+如果输出把 4.2 写成 4.8，或者把 Cafe Luna 写成另一个餐厅，就是错误处理。
+
+#### 2. 是否编造了工具结果中不存在的信息
+
+这是 Tool Response Handling 的核心用途之一：检测 hallucinated data。
+
+```text
+tool_result:
+{"results": [{"name": "Cafe Luna", "rating": 4.2}]}
+
+output:
+I found Cafe Luna (4.2 stars) and Mario's Italian (4.8 stars).
+
+=> incorrect
+```
+
+因为 `Mario's Italian` 不在工具返回里，是 agent 自己编出来的。
+
+#### 3. 是否正确转换日期、数字和结构化字段
+
+工具结果经常是结构化数据，agent 需要转换给用户看。Phoenix 会判断转换是否正确：
+
+- 数字单位是否正确。
+- 日期格式是否正确。
+- 状态字段是否正确解释。
+- 结构化字段是否被正确组合。
+
+例如工具返回 `temperature: 58, unit: fahrenheit`，输出成 `58°F` 是正确的；输出成 `58°C` 或 `14°F` 就可能是错误转换。
+
+#### 4. 是否正确处理工具错误
+
+如果 `tool_result` 是错误或部分结果，Phoenix 会看 agent 是否合理处理：
+
+- transient error，例如 timeout、rate limit：是否重试。
+- invalid argument error：是否修正参数再调用。
+- partial result：是否说明限制，或继续补齐信息。
+
+错误例子：
+
+```text
+tool_result:
+{"error": "rate_limit", "retry_after": "5s"}
+
+output:
+I couldn't find any results.
+
+=> incorrect
+```
+
+因为工具不是“没结果”，而是限流；更合理的处理是等待/重试或告诉用户暂时无法访问。
+
+#### 5. 是否重复相同失败调用
+
+Phoenix 把“重复 identical failed calls”也列为 incorrect 条件。如果工具已经因为同一个参数错误失败，agent 继续原样重试，多半说明它没有理解工具错误。
+
+```text
+tool_call:
+book_flight(date="tomorrow")
+
+tool_result:
+{"error": "date must be YYYY-MM-DD"}
+
+output:
+Retry book_flight(date="tomorrow")
+Retry book_flight(date="tomorrow")
+
+=> incorrect
+```
+
+正确处理应该是把 `tomorrow` 转换成具体日期，再重新调用。
+
+#### 6. 是否泄露工具返回中的敏感信息
+
+如果工具返回里含有 credentials、internal URLs、PII 等，agent 不应该原样暴露给用户。
+
+```text
+tool_result:
+{"status": "ok", "internal_url": "https://internal.service.local", "token": "sk-..."}
+
+output:
+Request succeeded. Debug token: sk-...
+
+=> incorrect
+```
+
+即使工具结果本身真实存在，泄露敏感字段也是错误处理。
+
+### 输出是什么？
+
+Phoenix 输出一个 `Score` 对象，核心字段是：
+
+| 字段 | 值 | 含义 |
+| --- | --- | --- |
+| `label` | `"correct"` 或 `"incorrect"` | 二分类判断 |
+| `score` | `1.0` 或 `0.0` | 数值分，1 表示正确，0 表示错误 |
+| `explanation` | string | LLM 生成的判定理由 |
+| `direction` | `"maximize"` | 分数越高越好 |
+| `metadata` | object | 额外信息，例如模型名；启用 tracing 时可包含 evaluation trace id |
+
+正确条件可以概括为：
+
+```text
+label = correct
+score = 1.0
+```
+
+当且仅当：
+
+- 输出准确使用了工具结果。
+- 没有编造工具结果中不存在的数据。
+- 日期、数字、结构化字段转换正确。
+- 可重试错误被合理重试，可修正参数错误被修正。
+- 没有泄露敏感信息。
+- 没有忽略工具结果。
+
+错误条件可以概括为：
+
+```text
+label = incorrect
+score = 0.0
+```
+
+典型错误包括：
+
+- 输出包含工具结果中不存在的信息。
+- 反转或误解工具结果含义。
+- 日期、数字、结构化数据转换错误。
+- 没有重试可重试错误。
+- 没有修正可修正参数错误。
+- 重复相同失败调用。
+- 泄露工具返回中的敏感信息。
+- 完全忽略工具结果。
+
+### 和另外两个 Phoenix 工具评估器的关系
+
+Phoenix 把工具调用链路拆成三段：
+
+```text
+Tool Selection:
+  该不该用这个工具？工具选得对不对？
+
+Tool Invocation:
+  工具调用参数、格式、schema 是否正确？
+
+Tool Response Handling:
+  工具返回之后，agent 是否正确使用结果、处理错误、避免泄露？
+```
+
+一个 agent 可能：
+
+- `Tool Selection = correct`：选对了搜索天气工具。
+- `Tool Invocation = correct`：参数也传对了 Seattle。
+- `Tool Response Handling = incorrect`：工具返回 58°F cloudy，但 agent 输出成 80°F sunny。
+
+所以 Tool Response Handling 补的是最后一段能力：**工具结果到最终行为/回复之间的正确性**。
+
+### 参考链接
+
+- Phoenix Tool Response Handling: https://arize.com/docs/phoenix/evaluation/pre-built-metrics/tool-response-handling
+- Phoenix Tool Selection: https://arize.com/docs/phoenix/evaluation/pre-built-metrics/tool-selection
+- Phoenix Tool Invocation: https://arize.com/docs/phoenix/evaluation/pre-built-metrics/tool-invocation
+
+## Q4：当前轨迹评估里的“冗余”和 DeepEval StepEfficiencyMetric 有何不同？还需要怎么优化？
+
+### 简短结论
+
+两者都关注“agent 有没有走弯路、重复调用、无效重试”，但定位不同。
+
+当前 Agent Insight 的“冗余”是 **轨迹质量综合评估里的一个维度**；DeepEval [`StepEfficiencyMetric`](https://deepeval.com/docs/metrics-step-efficiency) 是 **独立的 trace-only 步骤效率评估器**。
+
+更关键的是：DeepEval 的 Step Efficiency 以“用户任务是否需要这些步骤”为中心；当前轨迹冗余更多是“这条 trace 里有没有明显重复、高频无效调用、绕路”的质量维度。
+
+### 当前 Agent Insight 轨迹冗余的逻辑
+
+当前预置轨迹评估器是 `preset-agent-trace-quality`，实现入口主要在：
+
+- `src/lib/engine/evaluation/opencode-trajectory-evaluator.ts`
+- `src/lib/engine/evaluation/trajectory-evaluator.ts`
+- `src/lib/engine/evaluation/trace-summarizer.ts`
+
+它先把完整 trace 压缩成事件级步骤：
+
+```text
+user / llm / tool / skill / task
+```
+
+每个步骤保留：
+
+```text
+index
+agent
+depth
+kind
+name
+argsSummary
+outputSummary
+textContent
+durationMs
+```
+
+然后让 LLM judge 输出三维分：
+
+```text
+completeness: 关键动作覆盖完整性
+tool_choice: 工具/Skill 选择合理性
+redundancy: 冗余程度
+```
+
+其中冗余维度的 prompt 口径是：
+
+```text
+基于 actual_flat_trace_steps 中是否有明显重复、绕路、高频无效调用，0.0 到 1.0。
+```
+
+并要求在 `dimension_details.redundancy` 中输出：
+
+```text
+consecutive_same_runs: 连续重复调用
+heavy_repeated_calls: 高频重复调用
+explanation: 冗余说明
+```
+
+所以当前“冗余”主要依赖 LLM 根据压缩步骤判断：
+
+- 是否连续重复调用同一个工具。
+- 是否某类工具调用次数异常高。
+- 是否存在明显绕路。
+- 是否有无效消耗。
+
+代码里还有一个轻量规则辅助：`normalizeTrajectoryRedundancyDetails()` 会统计 tool / skill / task 调用次数，用来补齐 LLM 返回的 repeated call 名称和位置。但它更像是 **结果规范化 / 证据补齐**，不是一个完整的规则冗余评分器。
+
+最终轨迹分是代码侧加权聚合：
+
+```text
+trajectory_score =
+  0.45 * completeness
++ 0.35 * tool_choice
++ 0.20 * redundancy
+```
+
+trace-only 模式下，没有 completeness，则只用：
+
+```text
+tool_choice + redundancy
+```
+
+### DeepEval StepEfficiencyMetric 的逻辑
+
+DeepEval `StepEfficiencyMetric` 是一个 **LLM-as-a-judge、single-turn、referenceless、agent trace-only** 指标。
+
+官方计算逻辑是：
+
+```text
+Step Efficiency Score = AlignmentScore(Task, Execution Steps)
+```
+
+它会做两件事：
+
+1. **从 trace 中抽取 Task**
+   也就是用户真正想让 agent 完成的目标。
+
+2. **评估 Execution Steps 是否高效服务于这个 Task**
+   LLM judge 会判断 agent 的执行步骤是否对完成任务严格必要。
+
+DeepEval 明确说 Step Efficiency 会惩罚：
+
+- duplicates：重复步骤。
+- retries：不必要重试。
+- detours：绕路。
+- any actions not strictly required：任何不是完成任务严格需要的动作。
+
+它和 `TaskCompletionMetric` 是分开的：一个 agent 可以最终完成任务，但路径很臃肿；也可以路径很短，但没有完成任务。
+
+### 两者核心差异
+
+| 对比点 | Agent Insight 当前“冗余” | DeepEval StepEfficiencyMetric |
+| --- | --- | --- |
+| 所属位置 | 轨迹质量综合评估的一个维度 | 独立步骤效率评估器 |
+| 输入 | 压缩后的 `actual_flat_trace_steps`，可结合关键动作/Skill 上下文 | 完整 agent trace |
+| 是否需要 reference | 不需要标准路径；可结合 Skill 关键动作 | 不需要 reference |
+| 评估中心 | trace 中是否有明显重复、绕路、高频无效调用 | 执行步骤是否严格服务于用户 Task |
+| 评分方式 | LLM 输出 `redundancy` 维度分，再进入总轨迹分加权 | LLM 输出独立 efficiency score |
+| 证据形态 | `consecutive_same_runs`、`heavy_repeated_calls`、explanation | reason 中说明哪些步骤低效 |
+| 粒度 | trace-level 的一个维度 | trace-level 专项指标 |
+| 当前确定性规则 | 主要用于补齐重复调用详情，不主导评分 | 官方文档描述为 LLM judge 评分 |
+
+### 当前实现存在的关键问题
+
+#### 1. 分数方向不清晰，甚至可能反向
+
+当前文档写的是：
+
+```text
+冗余：高 = 浪费明显，路径不够精炼
+```
+
+也就是说，`redundancy` 越高越坏。
+
+但代码聚合里是：
+
+```text
++ 0.20 * redundancy
+```
+
+这会导致一个问题：如果 `redundancy=1.0` 表示“非常冗余”，它反而会提高总轨迹分。
+
+当前 prompt 也写“redundancy：冗余程度，0.0 到 1.0”，从语义看更像高分=更冗余；但代码 fallback 又在缺失时给 `redundancy=1`，这又像高分=更好。这里需要先统一方向。
+
+这是最优先要修的地方。
+
+#### 2. 冗余不是独立 evaluator，解释力有限
+
+当前冗余只是三维中的一个维度，输出主要是 explanation 和重复调用列表。它没有像 DeepEval Step Efficiency 那样明确抽取：
+
+```text
+Task
+Execution Steps
+每一步是否 strictly required
+```
+
+所以它能发现“明显重复”，但不一定能系统判断：
+
+- 这一步对任务是否必要。
+- 这个重试是否合理。
+- 这段搜索是否属于必要探索还是绕路。
+- 多 agent 分工里的额外步骤是否有价值。
+
+#### 3. 确定性统计还不够强
+
+当前有调用次数统计，但没有形成完整的规则指标，例如：
+
+- 相同工具 + 相同参数 + 相同错误的重复率。
+- 连续失败后是否改变参数。
+- 空结果工具调用比例。
+- 无后续消费的工具结果比例。
+- 工具调用 token / 耗时占比。
+- 同一文件/URL/资源被重复读取次数。
+- 截断 trace 下的统计可信度。
+
+这些不该全交给 LLM judge。
+
+#### 4. trace 压缩可能影响冗余判断
+
+`trace-summarizer.ts` 默认最多保留 80 步，并且中间过长会截断为前半 + 后半。每个字段也会截到 200 字符。
+
+这对上下文成本友好，但对“冗余/效率”有风险：
+
+- 中间重复调用可能被截掉。
+- 工具输出被截短后，judge 不知道重试是否合理。
+- 多轮探索过程被压缩后，可能误判为绕路或漏判冗余。
+
+### 建议怎么优化
+
+#### 1. 先统一分数语义
+
+建议二选一：
+
+方案 A：把维度改名为 `efficiency`
+
+```text
+efficiency 高 = 路径精炼、高效
+efficiency 低 = 冗余、绕路、无效消耗
+```
+
+然后聚合可以继续：
+
+```text
++ 0.20 * efficiency
+```
+
+方案 B：保留 `redundancy`
+
+```text
+redundancy 高 = 冗余严重
+redundancy 低 = 路径精炼
+```
+
+但聚合必须改成：
+
+```text
++ 0.20 * (1 - redundancy)
+```
+
+并且 UI 文案、文档、字段名都要说明它是“缺陷分”，不是质量分。
+
+我更建议方案 A。因为综合分里各维度最好都是“高分=好”，用户理解成本低。
+
+#### 2. 增加 DeepEval 式的独立 Step Efficiency 评估器
+
+把当前冗余维度升级/拆出为一个独立预置评估器：
+
+```text
+Step Efficiency / 步骤效率
+```
+
+输入：
+
+```text
+- 用户任务
+- 完整或分层压缩 trace
+- execution steps
+- 工具调用统计
+- 可选：最终任务完成度
+```
+
+中间逻辑：
+
+```text
+1. 抽取用户 Task
+2. 抽取所有 execution steps
+3. 标注每一步：
+   required | helpful | redundant | harmful | justified_retry | unjustified_retry | detour
+4. 汇总低效步骤
+5. 输出效率分和证据
+```
+
+输出：
+
+```text
+score: 0-1，高分=高效
+redundant_steps: [...]
+unjustified_retries: [...]
+detours: [...]
+repeated_calls: [...]
+reason
+confidence
+```
+
+这样它就和 DeepEval StepEfficiencyMetric 更接近，也能和现有轨迹质量总分解耦。
+
+#### 3. 做“确定性规则 + LLM judge”的混合评分
+
+建议先由代码生成派生特征：
+
+```text
+total_steps
+tool_calls
+same_tool_same_args_repeats
+consecutive_same_tool_runs
+failed_tool_retries
+unchanged_failed_retries
+empty_result_calls
+unused_tool_results
+duration_ms
+token_cost
+trace_truncated
+```
+
+再把这些结构化特征交给 LLM judge 做语义判断：
+
+```text
+这些重复是否合理？
+这些重试是否必要？
+这些额外步骤是否服务于用户任务？
+```
+
+这样比单纯让 LLM 看压缩 trace 更稳，也比纯规则更能处理探索型任务。
+
+#### 4. 区分“合理重试”和“无效重复”
+
+不要把所有重复都判坏。需要单独标注：
+
+```text
+justified_retry:
+  transient error 后换参数/等待/换工具重试
+
+unjustified_retry:
+  相同参数、相同错误、连续重复
+
+progressive_search:
+  搜索关键词逐步收敛，有新信息
+
+dead_loop:
+  搜索/读取/命令没有产生新信息
+```
+
+这是当前“冗余”最容易误判的地方。
+
+#### 5. 把冗余证据从“工具名级别”升级到“调用签名级别”
+
+现在 `heavy_repeated_calls` 更偏工具名统计，例如：
+
+```text
+read: 8
+bash: 3
+```
+
+但真正有意义的是调用签名：
+
+```text
+read(path="same_file.ts"): 5
+bash(cmd="npm test"): 3
+web_search(query="same keywords"): 4
+```
+
+建议按：
+
+```text
+tool name + normalized args + output/error fingerprint
+```
+
+来识别重复。
+
+#### 6. 支持 trace-level 聚合和 span-level 证据
+
+最终应该是：
+
+```text
+trace_efficiency_score: 整条 trace 的步骤效率
+```
+
+但证据必须落到具体步骤：
+
+```text
+step_index
+tool_name
+args_fingerprint
+issue_type
+why_redundant
+severity
+```
+
+这样用户看到低分时，能直接知道是哪几步浪费。
+
+#### 7. 处理 trace 截断带来的置信度
+
+如果 `traceSummary.truncated=true`，效率评估应该降低 confidence，或者标记：
+
+```text
+efficiency_score_confidence = low
+reason = 中间步骤被截断，可能漏掉重复/重试证据
+```
+
+否则长 trace 的效率分会显得过于确定。
+
+### 一个推荐的优化方向总结
+
+短期：
+
+1. 修正 `redundancy` 分数方向。
+2. 明确 UI/文档里“高分=好”还是“高分=坏”。
+3. 增加确定性重复统计：相同工具+相同参数、连续失败重试、重复读取。
+
+中期：
+
+1. 把“冗余”改造成 `efficiency` 正向质量维度。
+2. 输出 step-level 证据列表，而不只是 explanation。
+3. 对合理重试和无效重复做分类。
+
+长期：
+
+1. 新增独立的 `Step Efficiency / 步骤效率` 预置评估器。
+2. 采用 DeepEval 式 `AlignmentScore(Task, Execution Steps)` 逻辑。
+3. 与任务完成度联动展示：完成但低效、未完成但路径高效、未完成且低效。
+
+### 参考链接
+
+- DeepEval Step Efficiency: https://deepeval.com/docs/metrics-step-efficiency
+- Agent Insight 轨迹评估实现：`src/lib/engine/evaluation/opencode-trajectory-evaluator.ts`
+- Agent Insight 轨迹分聚合：`src/lib/engine/evaluation/trajectory-evaluator.ts`
+- Agent Insight trace summarizer：`src/lib/engine/evaluation/trace-summarizer.ts`
+
+## Q5：DeepEval PlanQualityMetric 对 agent 的意义在哪？对评估改进有什么作用？适用场景是什么？
+
+### 简短结论
+
+DeepEval [`PlanQualityMetric`](https://deepeval.com/docs/metrics-plan-quality) 评估的是：**agent 在执行前或执行中形成的计划，本身是否是一个能完成任务的好计划**。
+
+它不是评估最终结果，也不是评估 agent 有没有照计划执行。它只看：
+
+```text
+用户要完成什么任务？
+agent 想出来的 plan 是否合理、完整、可执行？
+```
+
+官方计算公式是：
+
+```text
+Plan Quality Score = AlignmentScore(Task, Plan)
+```
+
+其中：
+
+- `Task`：从 trace 中抽取的用户目标或任务意图。
+- `Plan`：从 trace 中 agent 的 thinking / reasoning 里抽取出来的计划。
+- `AlignmentScore`：LLM judge 判断这个计划和任务是否对齐。
+
+### 对 agent 的意义
+
+Plan Quality 的价值在于：它把 agent 失败原因里的 **“想错了”** 和 **“执行错了”** 分开。
+
+很多 agent 失败不是因为工具调用能力差，而是第一步就规划错了：
+
+- 没有识别任务的关键约束。
+- 漏掉必要步骤。
+- 把任务拆错方向。
+- 计划里用了不可用工具。
+- 计划过度复杂，导致后续执行绕路。
+- 没有先验证条件就直接行动。
+- 多 agent 场景里没有规划谁负责什么。
+
+如果只看任务完成度，最终失败只能知道“没完成”；如果只看工具调用，只能看到“某个工具用错了”。Plan Quality 则能提前指出：
+
+```text
+这个 agent 的路线图本身就不对。
+```
+
+这对 agent 很重要，因为计划通常决定了后面工具选择、步骤效率、错误恢复和最终结果。
+
+### 它和其他指标的区别
+
+| 指标 | 回答的问题 |
+| --- | --- |
+| Task Completion | 最终有没有完成任务？ |
+| Plan Quality | 一开始/过程中形成的计划本身好不好？ |
+| Plan Adherence | agent 实际有没有遵守这个计划？ |
+| Step Efficiency | 实际执行路径是否高效？ |
+| Tool Correctness / Tool Selection | 工具是否选对？ |
+
+典型组合判断：
+
+| 现象 | 说明 |
+| --- | --- |
+| Plan Quality 高，Plan Adherence 低 | 计划是好的，但执行偏离了。问题在执行控制、工具使用或中途决策。 |
+| Plan Quality 低，Plan Adherence 高 | agent 很认真地执行了一个坏计划。问题在规划能力或 prompt/skill 指导。 |
+| Plan Quality 高，Task Completion 低 | 计划方向对，但执行失败，可能是工具、环境、参数、权限、错误恢复问题。 |
+| Plan Quality 低，Task Completion 高 | 可能是靠运气、模型补救或任务简单完成了；长期稳定性风险较高。 |
+
+### 对 agent 评估改进有什么作用？
+
+#### 1. 帮助定位失败发生在“规划阶段”还是“执行阶段”
+
+没有 Plan Quality 时，评估器常常只能看到最终失败和中间工具错误。
+
+有了 Plan Quality 后，可以把失败拆成：
+
+```text
+计划错了：
+  agent 不知道该怎么做
+
+计划对了但执行错了：
+  agent 知道该怎么做，但执行控制/工具使用出问题
+```
+
+这对优化方向非常关键。
+
+例如：
+
+- 如果 Plan Quality 低，应改 system prompt、skill 指令、任务拆解模板、few-shot planning 示例。
+- 如果 Plan Quality 高但执行失败，应改工具 schema、工具选择、参数校验、错误恢复、执行 guardrail。
+
+#### 2. 提前发现“表面成功但不可复用”的 agent
+
+有些 agent 最终能完成任务，但计划是混乱的：
+
+- 先乱查一堆信息，再偶然找到答案。
+- 没有先确认约束，但最后输出碰巧符合。
+- 计划漏了验证步骤，但样例刚好没暴露问题。
+
+这种 agent 在单个 case 上可能分数不错，但换任务就容易崩。Plan Quality 能作为稳定性前置信号：
+
+```text
+好结果 + 坏计划 = 潜在不稳定
+```
+
+#### 3. 改进 prompt / skill 的可操作性
+
+如果 agent 总是计划不好，通常说明指导材料不够好：
+
+- skill 没有说明标准流程。
+- prompt 只告诉 agent 目标，没有告诉它关键约束。
+- 工具说明缺少适用场景。
+- 缺少“先判断、再行动、最后验证”的操作框架。
+
+Plan Quality 的 reason 可以直接转成优化建议：
+
+```text
+缺少验证步骤
+=> 在 skill 中增加“修改后必须运行测试/检查结果”的规则
+
+计划没有处理异常路径
+=> 增加错误恢复策略
+
+计划没有区分信息收集和执行动作
+=> 增加分阶段流程模板
+```
+
+#### 4. 支持多 agent / 子 agent 编排评估
+
+多 agent 系统里，计划质量不只是“步骤列表是否合理”，还包括：
+
+- 是否应该派发子 agent。
+- 子 agent 分工是否清楚。
+- 依赖关系是否正确。
+- 父 agent 是否保留最终整合责任。
+- 是否避免重复派发或互相等待。
+
+Plan Quality 可以帮助发现：
+
+```text
+agent 一开始就把任务交给了错误角色
+agent 没有规划父子 agent 的信息回流
+agent 把一个需要并行拆分的任务串行处理了
+```
+
+#### 5. 和 Step Efficiency 互补
+
+Step Efficiency 看的是实际走过的路是否精炼；Plan Quality 看的是原本设计的路线是否合理。
+
+两者可以组合判断：
+
+```text
+Plan Quality 高 + Step Efficiency 低:
+  好计划被执行得很啰嗦
+
+Plan Quality 低 + Step Efficiency 高:
+  计划很差，但执行很短；可能是“快速走错”
+
+Plan Quality 高 + Step Efficiency 高:
+  理想状态，计划好且执行精炼
+
+Plan Quality 低 + Step Efficiency 低:
+  规划和执行都需要优化
+```
+
+### 适用场景
+
+#### 1. 复杂多步任务
+
+例如：
+
+- 调研并形成报告。
+- 修复 bug 并验证。
+- 数据分析。
+- 多文件代码修改。
+- 自动化运维。
+- 业务流程办理。
+
+这些任务如果没有好计划，后面很容易工具乱用、步骤重复或漏验证。
+
+#### 2. 高风险任务
+
+例如：
+
+- 修改生产配置。
+- 执行数据库操作。
+- 删除/迁移文件。
+- 调用外部 API 完成不可逆业务动作。
+
+这类场景里，先看计划是否包含确认、备份、验证、回滚，比只看最终结果更安全。
+
+#### 3. Agent / Skill 调优
+
+当你想判断一个 skill 是否真的让 agent 更会做事，而不是只让它某次碰巧答对时，Plan Quality 很有用。
+
+它能回答：
+
+```text
+新版 skill 是否让 agent 更早识别关键步骤？
+新版 prompt 是否减少了错误分解？
+agent 是否学会先验证再行动？
+```
+
+#### 4. 多 agent 编排
+
+适用于需要判断：
+
+- 是否应该拆给子 agent。
+- 子任务划分是否合理。
+- 子 agent 顺序/依赖是否正确。
+- 父 agent 是否规划了最终合并和验证。
+
+#### 5. 失败复盘
+
+当一个 trace 最终失败时，Plan Quality 可以帮助排查：
+
+```text
+失败是因为一开始计划错了？
+还是计划没问题，但某一步执行崩了？
+```
+
+这能减少“所有失败都归因到工具调用”的误判。
+
+### 不太适用的场景
+
+#### 1. 单步问答或简单检索
+
+例如：
+
+```text
+“北京今天星期几？”
+“把这句话翻译成英文”
+```
+
+这类任务几乎不需要显式计划，Plan Quality 的增益很小。
+
+#### 2. trace 中没有可见计划
+
+DeepEval 官方文档明确说：Plan Quality 会从 agent 的 thinking / reasoning 中抽取 plan；如果 trace 中没有清楚定义或暗示计划的语句，它会默认通过，给 `1`。
+
+这点非常重要：如果你的 agent 不暴露 planning 信息，Plan Quality 分数可能虚高。
+
+所以在不暴露推理/计划的框架里，需要谨慎使用。更合理的做法是只评估“可见计划”，例如：
+
+- agent 明确输出的 Todo。
+- 对用户可见的行动计划。
+- tool call 之前的步骤说明。
+- 子 agent 派发说明。
+
+不能为了评估而要求模型泄露隐藏推理。
+
+#### 3. 高探索型任务
+
+开放研究、创意生成、问题尚不清楚的诊断任务，计划可能需要动态变化。此时不能过度惩罚计划变化，而应区分：
+
+```text
+合理重规划：根据新证据调整路线
+坏计划：一开始就漏掉核心目标或约束
+```
+
+### 总结
+
+Plan Quality 的意义不是替代任务完成度，而是补上一个关键诊断维度：
+
+```text
+最终结果之前，agent 有没有先想出一条靠谱路线？
+```
+
+它最适合多步、高风险、多工具、多 agent 的场景。对评估改进来说，它能把优化方向从“结果错了”推进到“规划错了还是执行错了”，从而更准确地指导 prompt、skill、工具说明和 agent 编排的改动。
+
+### 参考链接
+
+- DeepEval Plan Quality: https://deepeval.com/docs/metrics-plan-quality