测试与调试页面能力

当 Agent 点错控件、动作调用成功却没有效果，或者人一眼能看到的按钮在 Agent 那里不存在时，只查看聊天记录通常无法解释原因。更有用的问题是：这一次模型调用究竟收到了什么，页面当时向它暴露了什么？

Pling 把这部分与普通业务测试分开。确定性测试负责验证声明、执行和状态变化；内置检查器负责展示正在运行的会话实际发出的请求。它不会创建第二个 Agent 循环，也不会另做一份页面模型。

开启检查器

检查器默认关闭。在现有的助手入口上打开即可：

<AgentDock debug />

调用较多时，可以缩小内存中的记录数：

<AgentDock :debug="{ maxCalls: 8 }" />

<AgentInline> 接受相同的 debug 属性。默认保留最近 20 次调用；刷新页面或清空会话后，这些记录都会消失。

也可以在整个应用上统一开启：

createPling({ agent: { trace: true } });

没有显式设置 debug 的问答入口会继承这项配置并获得检查器入口；在单个入口上写 :debug="false" 可以关闭。

开启后，任何能打开该聊天窗口的人都能看到请求消息、系统提示词、工具清单和页面数据。上线环境应通过构建开关或角色校验决定是否启用。它的默认定位是开发工具，不是运营控制台。

检查器里有什么

运行状态

展示当前模型、模型是否就绪、上下文占用、已用轮数和保留的调用数。这些读数来自聊天窗口正在使用的那个 runtime。

当前页面投影

这是能力注册表现在看到的页面：

• 可用动作及其原语、风险级别、区域路径和说明；
• 存在但当前不可用的动作及原因；
• 活跃区域、记录、暴露状态和页面反馈；
• 开发期交互控件覆盖率。

覆盖率只做诊断，不会注册动作。没有声明的控件仍然不可操作。

模型调用

每次调用包含：

• 轮次、完成状态、耗时和上下文 token；
• 循环实际发送的请求消息；
• 与本次请求一起发送的 function tools；
• 模型回复的文本和 tool calls；
• 本次调用发生时的页面快照；
• 调用失败时的错误码与消息。

页面会在调用后继续变化。本次调用时的页面保留了模型当时真正看到的内容，通常也是判断问题最关键的证据。

如何阅读一次调用

一次正常任务通常包含三次请求：用户指令、工具结果、最终回答。排查时按顺序对照。

1. 在第一次请求中找到用户指令。
2. 检查目标动作是否出现在工具清单和本次页面快照中。
3. 在下一次请求中读取 tool call 和它的结果。
4. 查看最后一次快照，确认模型认为页面处于什么状态。

这样可以区分三种看起来相似、原因却不同的问题：

• 动作从未暴露；
• 动作已暴露，但模型选错了；
• 动作选对了，但执行没有产生预期状态。

敏感值

检查器展示实际出站内容，不提供还原后的方便视图。页面已经 token 化的敏感值仍显示为 {{p:…}}。打开检查器不会把真实值恢复出来。

如果某个值连开发者也不应在聊天窗口看到，应通过 Pling 的敏感数据声明把它排除在模型上下文之外。调试开关不是隐私边界。

确定性测试与检查器

需要稳定、离线运行的测试应使用回放或脚本化模型输出：

const llm = createReplayLlm([
  { toolCalls: [{ id: "call_1", name: "toggle", arguments: { record: "t2" } }] },
  { content: "已标记为完成。" },
]);

测试应断言页面最终状态、执行结果，以及下一次请求里的工具清单。只保留少量真实模型检查，用来覆盖依赖模型判断的行为；主测试集不应依赖远程服务。

检查器解决的是测试无法预先回答的问题，尤其是“模型为什么会做出这个意外决定”。

常见失败

人能看到，但工具清单里没有

先看当前页面投影和覆盖率。没有声明的控件本来就不会开放。如果控件位于未打开的弹窗或非活跃区域，应先满足该条件。不要用检查器绕过声明模型，新增通用点击入口。

模型调用了错误的动作

对照请求快照中的动作说明、区域路径和记录折叠结果。两个名称相近的按钮需要能区分效果的说明；相比继续增加同义词，更清楚的大区域描述通常更有效。

调用成功，但页面没有变化

先读动作回执，再看模型的最终回答。changed 表示框架实际观察到的差异；期望失败说明动作已经发出，但声明的后置条件没有成立。请求快照可以确认页面当时是否真的提供了这个条件。

请求比预想的大

先检查记录、动作折叠和页面数据部分。每次调用都会显示上下文 token，便于看出导航、筛选或重复工具结果带来的增长。

边界

检查器的限制是刻意的：

• 只读取现有 runtime 和注册表，不创建新的运行实例；
• 不提供执行按钮；
• 只在内存中保留最近若干次调用；
• 记录主循环的模型调用，不记录历史压缩调用；
• 目前接入 Vue 入口；底层 trace 位于 @plingjs/agent，其他适配器可以复用。

审计、计费和长期排障应使用运行时遥测与服务端审计记录。检查器回答的是一个开发期问题：这段会话看到了什么，又发送了什么？

本地验证

Vue 3 示例用有界的调用记录开启内置检查器：

pnpm --filter @plingjs/recipe-vue3 dev

发送一个任务，切到 Activity，点击“执行记录”标题旁的“诊断信息”。随后清空会话，确认调用记录与对话一起消失。