06/Documentation
手机上的持久 agent
持久 agent 的分区、对话、提问与回执的外观展示
实验性功能。 durable agent 在手机上显示的内容可能会在后续的次要版本中发生变化，或者该特性可能会被移除。持久 agent 说明了决定其是否保留的条件。
本页展示了 durable agent 在你手机上出现的所有位置：仪表盘中的行、会话列表、其提出的问题、聊天界面、启动配置以及推送。持久 agent 说明如何先关联一个 durable agent。
durable agent 仅针对其在 hello 中声明能够支持的能力渲染控件。下文中提及控件的行均假定 durable agent 已声明了该控件。
仪表盘上的 Durable agents 部分
除 spaces 之外，每个 durable agent 在 Durable agents 部分各占一行。
| 行的一部分 | 显示内容 |
|---|---|
| 第 1 行 | 来自 sources.json 的持久 agent 名称，以及一个 Experimental 徽标 |
| 第 2 行 | 其运行时，即持久 agent 在其 hello 中为自己指定的名称，否则为 durable。随后是 local 或 remote |
| 右侧边缘，就绪 | 其打开的会话计数，并以 needs-you 颜色显示等待你的会话计数。第二个计数为零时隐藏 |
| 右侧边缘，未就绪 | 文字 Starting、Unreachable 或 Version mismatch，无计数 |
通过套接字，或通过 http://127.0.0.1 或 http://localhost 访问的持久 agent 为 local。其他所有 URL 均为 remote。
该部分位于你的空间下方。当任何持久 agent 有等待你的会话时，它会移至空间上方；当最后一个会话得到答复时，它会移回下方。未连接任何持久 agent 时，完全不绘制该部分。
开启“仅显示需要你的窗格”后，该部分仅列出等待你的持久 agent。点按任意状态下的某一行，即可打开该持久 agent 的会话列表。
会话列表
持久 agent 的主页列出其会话，方式类似于即时通讯应用列出其聊天。
等待你的内容排在最前，随后是其他打开的会话，最新的排在最前。已关闭的会话紧随其后，位于 Closed 标签下。每行显示标题、其状态标记、上次活动时间，并在其下方显示一行：等待中的问题，否则为持久 agent 的副标题。等待中的行还会统计其待解决的问题数。没有标题的行显示“未命名会话”。
点按打开的行可在 Chat 中打开它。点按已关闭的行可查看它，只读。当持久 agent 能够重新打开会话时，已关闭的会话会显示 Reopen 按钮。
打开的行来自仪表盘自身的数据，因此会立即绘制。已关闭的行来自持久 agent，Collie 每次访问请求一次，会话打开或关闭时再请求一次，绝不会每次轮询都请求。
| 在列表底部 | 当 |
|---|---|
| 加载更多 | 持久 agent 拥有超过 100 个会话。每次点按都会读取接下来的 100 个 |
| “此持久 agent 未保存其会话列表。” | 持久 agent 答复其未保存列表 |
| “持久 agent 未应答。请稍后再试。” | 持久 agent 未应答读取请求 |
| “持久 agent 使用 wire v2，此 Collie 使用 v1。请更新 Collie，或更新该 agent 的 SDK。” | Collie 因持久 agent 的 wire 版本（回执）而拒绝了该 agent |
| “无法加载会话。请重试。” | 读取在途中失败 |
不保留历史记录的 durable agent 仅显示其开启的会话，没有 Closed 分组，也没有备注。已绘制的列表在后续读取失败时仍会保留。
手机上的提问
durable agent 的提问是聊天中的一张卡片，位于其对应的工具调用下方。
说明文字指明了 durable agent 名称：“Needs your answer · desk”。当 durable agent 设置了过期时间时，标题下方的文本行会倒计时：“Expires in 4 min”，然后是“Expires in 40 s”，最后是“Expired”。超过过期时间后按钮仍然保留，durable agent 会自行处理迟到的点击。
| 类型 | 卡片显示的内容 | 限制 |
|---|---|---|
permission | 每个选项一个按钮，采用 Collie 的措辞：Allow、Always allow、Deny 或 Cancel。durable agent 自身的标签显示为较淡的第二行 | 最多 6 个选项 |
choice | 每个选项一行。点击一次即可发送选择。若为 multiple，选项行在“Pick any number”下方切换状态，点击 Send 发送整套选择 | 最多 8 个选项 |
text | 一行输入框、一个类似“12 of 500”的计数，以及 Send | 500 个字符，或 durable agent 的上限（最高 2000 个字符） |
form | 字段堆叠在同一个 Send 下方：单行文本、供选择的列表或开关。必填字段会标明 Required | 最多 6 个字段 |
“Always allow”需要点击两次。第一次点击将按钮变为“Tap again to always allow”并显示工具名称。第二次点击发送。若提问未指定工具，Collie 不提供该选项。
当 Collie 必须截断或清理 durable agent 的文字时，卡片会显示“Text shortened”且不提供“Always allow”，因为你并未看到完整文本。
当前 Collie 无法识别的卡片类型会显示其文字并提示“This ask cannot be answered from the phone.”。会话将其前 5 个提问绘制为卡片，点击“Show N more”行可展开其余提问。
点击后会发生什么
每次点击携带一个请求 ID，且只有点击才会发送答案。
| 发生的情况 | 卡片显示的内容 | 操作方法 |
|---|---|---|
| durable agent 已接收答案 | 无：卡片关闭 | 无 |
| durable agent 已先行决策 | “Decided in the durable agent.” | 无。聊天中为其保留一行 |
| 提问先超时了 | “在获得回答前超时。” | 无。聊天中为其保留一行 |
| 已有其他回答先一步提交 | “已回答。此卡片将在下次更新时消失。” | 无 |
| 提问未开放，且 durable agent 未说明原因 | “未采纳。提问稍后可能会再次显示。” | 请等待。重启后的 durable agent 会重新提问 |
| 提问内容已发生变动 | “此提问已更改。请重新阅读后再点击回答。” | 阅读新表单并重新点击 |
| 回答可能未送达 | “无法确认回答是否送达。点击重试将重新发送一次。” | 点击重试。这会发送相同的请求 ID，因此 durable agent 只会收到一次通知 |
| 重试时发现提问已关闭或已更改 | “可能已经应用。请查看聊天记录。” | 查看聊天记录 |
| Collie 拒绝了该回答 | Collie 给出的原因，否则为“回答被拒绝。” | 阅读原因 |
| 运行 durable agent 的机器安装了较旧版本的 Collie | “此机器运行较旧版本的 Collie，无法在此处接收回答。请更新该机器，或在 durable agent 中回答。” | 更新该机器 |
回执
Collie 会在你未回答时告知提问如何结束，以及 durable agent 为何被拒绝。
| 情况 | 你看到的内容 |
|---|---|
| 提问设有过期时间 | 卡片在标题下方显示剩余时间 |
| 你在 durable agent 做出决定后或过期后进行了点击 | 卡片冻结并显示“已在 durable agent 中做出决定。”或“在获得回答前超时。” |
| 问题已超时，或 durable agent 自行做出决定，未等待你点击 | 聊天中显示一行：“Timed out before an answer:”或“Decided in the durable agent:”，随后是问题标题 |
| Collie 因线缆协议版本拒绝了 durable agent | durable agent 主页显示警告框，仪表盘行显示 Version mismatch |
你从手机回答的问题，或因你停止当前回合而结束的问题，不会留下此类行。你的点击已有对应卡片。
警告框会标明各方使用的线缆协议版本，例如“Program speaks wire v2, this Collie speaks v1. Update Collie, or the durable agent's SDK.”。请更新较旧的一方。规则见 版本。
聊天
durable agent 的对话在 Chat 中打开，这是其唯一的视图。
| 来自 durable agent 的条目 | Chat 绘制的内容 |
|---|---|
user | 你发送的一行内容 |
reply | agent 的回答 |
thinking | agent 的思考过程 |
notice | 线程中的简短备注 |
markdown | 渲染后的 markdown：标题、列表、强调、代码和链接。原生 HTML 显示为文本 |
code | 代码块，若 durable agent 指定了语言则一并显示 |
link | 链接行及其标签，若无标签则显示地址。仅限 https:// 链接 |
tool | 工具调用：运行中、已完成并附带输出、失败或被拒绝 |
仍在生成的 reply、thinking、notice 或 markdown 条目末尾带有光标，不显示时间。最终文本到达后光标消失。你停止的回合会留下备注“stopped”。
你发送的一行内容
点击发送的瞬间，你的一行内容便会显示在线程中，并带有小时钟图标。当 durable agent 自身的副本到达时，会取代该行。
| 状态 | 该行显示的内容 |
|---|---|
| 正在发送，或已发送 | 时钟图标。当 durable agent 接收后，输入框显示“Sent” |
| 回答未返回 | “Sending, not confirmed”。再次发送会使用相同的 request id 重试 |
| 被拒绝，或回合已继续推进 | “Not sent”，你输入的文字会退回输入框中 |
未回传 request id 的 durable agent 会在 30 秒内通过相同文本进行匹配。durable agent 从未回写的内容在 10 分钟后停止显示。
当你发送的内容是线程中最新的条目且 durable agent 尚未回答时，一行三个点表示其正在处理。
页头
页头由两行组成。第 1 行是对话标题和 Experimental 徽标。
| 第 2 行显示 | 当 |
|---|---|
| “第 2 步，共 3 步：保存便签” | durable agent 上报了步骤，且某一步正在运行 |
| “42%：正在上传” | durable agent 上报了百分比及其标签 |
| durable agent 的副标题 | 无进度，或所有步骤均已完成 |
| 工作区 | durable agent 未设置上述任何项 |
仅在对话处理中或等待您操作时显示进度。
工具栏
工具栏包含 Steer 和 Stop，随后最多可容纳 4 个 durable agent 自带的按钮。
Steer 将文本发送到当前运行的轮次中，而不是开启新轮次。Stop 会结束当前运行的轮次。当前无法执行操作的按钮会原地变暗，因此界面元素不会移位。
| durable agent 按钮 | 规则 |
|---|---|
| 标签 | 最多 16 个字符 |
| 图标 | 12 个图标之一：play、pause、check、x、refresh、archive、flag、star、send、note、search、more。使用任何其他名称均不绘制图标 |
| 忙碌 | 显示旋转指示器，且不可点击 |
| 已禁用 | 变暗，且不可点击 |
点击操作会指定手机所见的最新轮次。若对话已继续推进，则不会运行任何操作，手机会提示：“对话已推进，因此操作未运行。”请核对内容，若仍需要执行该操作，请再次点击该按钮。
durable agent 窗格中不包含的内容
durable agent 没有屏幕，因此其窗格中没有 Terminal 视图，没有标签页或窗格栏，也没有 Keys、Type 或 Quick 按钮。其菜单中没有 History、Pane settings 或 Pin to top row。菜单中的 Close 显示为“Close conversation”。
新对话与 starter
durable agent 的 New 页面标题为 New conversation，其中列出了该 durable agent 的 starter。
starter 不接受文件夹和文本：由 durable agent 决定工作位置。点击一个 starter，durable agent 就会开启新对话。该页面不提供机器的 agent、shell 或命令。没有 starter 的 durable agent 会提示：“此机器的 durable agent 尚不提供任何 starter。”
推送
问题可以推送到你的手机，但受限于每个 durable agent 的配额。
| 上限 | 限制 | 超过限制 |
|---|---|---|
| 单个窗格 | 每分钟 3 次推送 | 问题会显示在手机上，但不发送推送 |
| 单台机器上的单个 durable agent | 每分钟 10 次推送 | 同上 |
| 单台机器上的单个 durable agent | 每小时 30 次推送 | 推送一次 "A durable agent on {host} is raising many asks"，随后该 durable agent 在一小时内不再推送 |
推送内容显示 "Permission needed in" 和窗格名称。durable agent 可以添加自己的标题（最多 60 个字符）和一行文字（最多 120 个字符）。Collie 对每台机器、每个 durable agent 和每次工具调用只推送一次问题，因此重启后再次提出的问题仅显示而不推送。来自 durable agent 的推送 包含其余说明。
脱敏
启用机密脱敏后（COLLIE_REDACT，默认启用），Collie 会对 durable agent 会话列表标题和副标题中的机密内容进行脱敏处理。
在 crew 中
lead 的仪表盘为 crew 的每台机器各设一个 Durable agents 区域。成员的 durable agent 会在第 2 行加上成员名称，例如 pi-durable, local, workshop，而 lead 自己的 durable agent 则不指明机器。任何机器上出现问题，都会将该区域移到各 space 上方。crew 中的 durable agent 说明了谁负责响应哪些内容。