Pling

简体中文

English

简体中文

English

主题

查看一次 Agent 运行 ​

可运行示例在浏览器中运行本章示例

这里运行与本地夹具相同的 React 源码。模型请求由服务端网关转发，供应商密钥不会进入浏览器。

本地运行pnpm tutorial:dev r-04 --locale zh源码examples/tutorials/r-04-inspect-one-agent-run/

上一章的 Todo 助手已经能读取页面并使用其中的控件。成功时，结果看起来很简单：多了一条待办、某一行的状态变了，或者助手说它没能完成。

最终结果并不能解释 Agent 为什么走到这一步。一个动作没有出现，可能是没有声明、当前不可用、被遮挡，或者不在活跃区域内；选错动作，可能是名称和说明不够清楚；工具调用成功，页面也可能没有产生预期变化。要区分这些原因，必须看模型实际收到了什么。

本章给现有的 React 示例加一个只读运行检查器。它不增加页面动作，也不改变 Todo 的业务流程，只展示当前这次运行使用的页面投影、工具定义、对话消息和模型响应。

为什么只看最终回答不够 ​

下面三种故障，助手可能给出同一句话：

用户看到的现象可能发生了什么
“我找不到添加待办的方法。”提交动作没有声明、处于禁用状态，或不在活跃区域内
助手操作了错误的待办记录字段或动作说明没有把不同行区分开
助手说已经添加，但列表没有变化模型选错了控件，或者页面没有渲染这次改动

助手的措辞不能证明其中任何一种原因。运行记录可以。

检查器只回答三个范围更窄的问题：

  1. 发起请求时，页面向模型提供了哪些事实？
  2. 实际发出的消息和工具定义是什么？
  3. 模型返回了什么，这个结果又如何进入下一次请求？

这三个问题把页面和模型分开。动作从未进入请求，改提示词也选不中它；动作存在但说明含糊，需要改页面声明；工具结果正确而下一轮仍使用旧页面，则要检查运行时或页面更新。

在 React 示例中开启检查器 ​

快速上手示例的页面已经渲染了 <AgentDock>。只需要增加一个属性：

tsx
<AgentDock
  title={copy.dockTitle}
  quick={copy.quick}
  debug={{ maxCalls: 8 }}
/>

debug 默认关闭。传 true 会按默认上限保留最近 20 次模型调用；传对象同样开启，并显式设置上限。教程使用 maxCalls: 8，足够观察一次任务，也能把内存占用控制在可预期的范围。

检查器会原样展示出站对话和页面投影。公开构建里无条件开启它，意味着任何能打开助手的人都能看到这些内容。应通过环境、构建开关或角色控制是否开启；它是开发工具，不是隐私边界。

除这个属性外，React 组件和页面声明都不需要变化。

Activity 里的两个时间视角 ​

打开助手，发送一条任务，再从 对话 切到 运行（英文界面为 Activity）。在执行记录顶部选择 诊断信息（英文界面为 Diagnostics）。

检查器同时保留两个时间视角：

  • 页面投影是打开检查器这一刻的注册表状态，包括页面身份、动作、不可用动作、区域、记录、状态和页面反馈；
  • 模型调用保存每次请求发出前的页面快照，也就是模型当时看到的那一页。

动作执行后，这两个视角往往不同。当前页面可能已经出现刚刚解锁的提交按钮，而第一次请求根本看不到它。判断模型为什么这样选，应先看请求时快照。

检查器没有执行按钮，也不创建第二套 Agent 会话。它读取的是当前对话正在使用的运行时；唯一的按钮只刷新只读投影数据。

一次请求由什么组成 ​

模型 API 是无状态的。每次调用都必须携带模型完成这一步所需的全部规则和对话状态。Pling 会组装四层内容：

层来源回答什么
system稳定的操作规则、应用自己的角色说明、当前页面投影、回答语言约束模型应当怎样工作，当前页面是什么样
tools从同一份快照投影出的动作定义这次请求可以调用哪些操作
messages用户请求、之前的助手消息、助手工具调用和工具结果这段对话已经发生了什么
response本次请求返回的文本和工具调用模型这次选择了什么

createPling 里的应用提示词会出现在系统消息的 ## This application 段，框架的操作规则保留在它前面。界面为中文时，运行时会额外要求模型使用用户最近一条消息的语言，应用提示词不需要重复这条策略。

页面部分会在每次请求时重建。对话历史单独保存，当前系统消息在发请求时组装，因此 Pling 不会为每一轮再累积一份完整页面。稳定规则在前，变化的页面事实在后。部分模型服务商可以复用这段未变化的前缀做提示词缓存；检查器不假设缓存一定发生，也不会把它报告成业务结果。

每次调用的出站对话都收在 请求消息 下。这里展示的是实际发给模型的消息数组，不是事后重写的摘要。

页面内容属于数据，不是指令。记录、页面反馈或工具结果里的文字，不能因为在上下文中出现就改变操作规则。

跟随一次真实的多轮调用 ​

在英文示例里发送：

Add “Reply to the customer” to my tasks.

本章的页面仍使用两个原生控件：文本输入框和提交按钮。输入框为空时提交按钮处于禁用状态，所以 Agent 通常需要不止一次模型调用。

一次典型的运行如下：

调用这次请求新增的内容模型的选择
1用户请求、Tasks 区域、记录 t1–t3、composer_text，以及折叠后的行内动作 toggle调用 composer_text，写入新待办文字
2上一次的助手工具调用及其结果，以及输入框已有文字后的新页面投影调用 composer_submit
3提交结果和更新后的记录给出简短的最终回答

第一次请求不会列出 composer_submit，因为输入文字之前按钮是禁用的；第二次请求会列出它。这不是 API 在变化，而是同一条快照规则在两个时刻得到不同结果。

行内动作会折叠。框架不会把 toggle@t1、toggle@t2、toggle@t3 作为三份工具定义发送，而是提供一个带 record 参数的 toggle。记录段给出可用 id。展开 发送的工具 可以看到定义，展开 本次调用时的页面 可以看到让 id 有意义的记录。

不要把“三次调用”当成固定契约。模型可能给出不同答案、在一次响应里调用多个工具，或者无法继续时提前停止。应当跟随实际记录，而不是拿调用次数和固定数字对照。

完成一条已有待办通常更短：模型读取记录，用已知 id 调用 toggle，再根据更新后的页面回答。

用记录回答三个排障问题 ​

动作一直没有出现 ​

先看那次调用的页面投影。动作是否声明过？是否出现在 不可用 里并有原因？所在区域是否活跃？目标是否被遮挡或在视口之外？现在可用的动作，在更早的请求里未必可用。

模型选错了动作 ​

把系统消息和工具清单放在一起看：动作 id、说明、区域路径和记录字段要共同成立。两个名称相近的控件，必须能通过结果或位置区分。单看工具定义，通常不足以补足业务上下文。

动作执行了，但页面没有变化 ​

先读工具结果，再看执行记录里的变更证据，最后看下一次请求的页面投影。原因可能在目标元素、业务处理函数、异步更新，或者页面根本没有暴露这项数据。助手最后那句话是最弱的证据。

边界 ​

检查器的范围有意保持很窄：

  • 只读。 不执行动作，也不提供绕过正常执行链路的入口；
  • 有界。 只保留 maxCalls 以内的最新调用，先丢弃更早的记录；
  • 随会话清空。 清空对话时，请求记录一起清空；
  • 面向开发。 它不是服务端审计、计费、长期可观测性，也不替代浏览器开发者工具；
  • 不承担脱敏。 已 token 化的值仍是代号，但其他页面数据和消息可能包含敏感上下文。是否允许打开检查器，应按环境决定。

这些限制不是缺少功能，而是工具的边界。一个会悄悄执行动作、无限期保存内容或绕过正常运行时的“检查器”，已经不再是检查器。

运行并验证 ​

在仓库根目录执行：

bash
pnpm tutorial:dev r-04

打开 http://127.0.0.1:5244/。示例源码位于 examples/tutorials/r-04-inspect-one-agent-run。

依次检查：

  1. 发送 Add “Reply to the customer” to my tasks.；
  2. 打开 运行，再选择 诊断信息；
  3. 展开第一次调用。系统消息应包含 Tasks 区域和三条待办记录，发送的工具 应包含 composer_text，不包含 composer_submit；
  4. 展开第二次调用。请求消息应包含第一次工具结果，工具清单里应出现 composer_submit；
  5. 展开最后一次调用。回答应基于更新后的记录；
  6. 发送 Mark the first task as completed.，检查折叠后的 toggle 工具及其 record 参数；
  7. 清空对话，确认请求记录也一起消失。

中文界面执行 pnpm tutorial:dev r-04 --locale zh，打开 http://127.0.0.1:5244/?lang=zh。界面文案和示例数据会随语言变化；API 名、id 和工具定义不变。

常见问题 ​

现象可能原因处理
运行里没有诊断入口<AgentDock> 没有传 debug传入 debug，或传入带 maxCalls 的配置对象
有页面投影，但没有模型调用还没有发过请求，或者对话已被清空先完成一条任务，再打开调用列表
第一次调用里没有 composer_submit输入框为空，按钮处于禁用状态对照下一次调用的工具清单
工具里的行内动作少于页面动作行内动作被折叠成一个带 record 参数的定义查看记录段和折叠后的工具
较早的调用不见了已达到 maxCalls 上限提高上限，或用更少的调用复现
检查器里能看到敏感文字检查器展示的是出站内容在不可信环境里保持关闭

下一步 ​

现在可以看到模型收到了什么、又选择了什么。下一个接入问题比“加上诊断”更具体：Todo 示例仍然要求 Agent 先填写输入框，再单独点击提交。

下一章会把这两步合并成一个业务动作 add_task，为它声明输入、可用条件和可验证结果。检查器会直接显示差异：一次工具调用取代两步操作，明确成功判据取代从页面变化中猜测。