175 lines
6.9 KiB
Markdown
175 lines
6.9 KiB
Markdown
# OMP 风格动态工具状态设计
|
||
|
||
日期：2026-06-15
|
||
|
||
## 背景
|
||
|
||
当前工作台已经能接收 agent 的工具开始和工具结束事件，但前端会把每次工具调用都追加到当前回复里。复杂任务一多，聊天区会变成工具流水账，用户很难看清“agent 此刻到底在做什么”。
|
||
|
||
目标不是做一个简陋的工具提示，而是对齐 `omp` 的体验：当前动作始终以彩色动态状态呈现，历史动作沉淀为可折叠摘要。
|
||
|
||
## 已确认方向
|
||
|
||
- 动态工具条放在当前 assistant 回复内部，跟着当前回复走。
|
||
- 工具条是彩色、动态、持续刷新的“跑马灯”状态，而不是普通灰色文本。
|
||
- 工具结束后不再把所有动作摊开显示，改为丰富但折叠的历史摘要。
|
||
- 不走 MVP 思维，优先做完整体验。
|
||
- 采用“升级项目内 pi-agent 依赖 + 对齐新版 `omp` 事件模型”的路线。
|
||
- 升级对象是本项目的依赖，不是用户本机全局安装的 `omp` 或 `pi-agent`。
|
||
|
||
## 目标体验
|
||
|
||
当 agent 开始调用工具时，当前 assistant 回复内部、正文之前出现一条动态工具条。它显示当前正在执行的动作，例如：
|
||
|
||
- Reading `workbench/PRODUCT.md`
|
||
- Writing `wiki/topics/agent-tools.md`
|
||
- Running `npm run typecheck`
|
||
- Searching current knowledge base
|
||
|
||
同一轮回复里，如果工具连续切换，工具条只显示当前正在进行的一项，之前完成的动作进入折叠摘要。
|
||
|
||
当 agent 开始输出正文时，工具条仍留在同一条回复内，固定在正文上方，不抢正文阅读。当前工具全部结束后，工具条消失或变为短暂完成态，历史摘要保留。
|
||
|
||
## 历史摘要
|
||
|
||
历史摘要默认折叠，但不是只显示一个数字。它要像 `omp` 一样让用户快速判断 agent 做过什么：
|
||
|
||
- 按工具类型分组：Read、Write、Bash、Search、Skill 等。
|
||
- 每组显示数量。
|
||
- 每组显示少量关键目标，例如文件名、页面名、命令摘要。
|
||
- 超过展示上限时显示“还有 N 项”。
|
||
- 用户展开后可以看到完整工具清单。
|
||
|
||
摘要示例：
|
||
|
||
```text
|
||
工具摘要
|
||
Read (6)
|
||
✓ SKILL.md:1-80
|
||
✓ README.md:1-80
|
||
✓ workbench/PRODUCT.md
|
||
Write (4)
|
||
✓ wiki/sources/...
|
||
Bash (2)
|
||
✓ npm run typecheck
|
||
```
|
||
|
||
## 底层升级策略
|
||
|
||
先开分支验证项目内 `pi-agent` 依赖升级，而不是直接改功能。
|
||
|
||
验证目标：
|
||
|
||
1. 项目能安装成功。
|
||
2. 后端能启动。
|
||
3. 前端能连接后端。
|
||
4. 基础对话能跑通。
|
||
5. 当前知识库上下文仍能注入。
|
||
6. Skill 调用仍能工作。
|
||
7. 会话历史仍能读取。
|
||
8. 新版事件里能拿到工具名、工具参数、工具状态、必要时的运行中更新。
|
||
|
||
如果新版依赖改了包名、导出路径或事件格式，后端要增加一个适配层，把新版事件统一整理成前端使用的稳定事件。
|
||
|
||
如果升级验证失败，不应退回到简陋前端方案；应记录失败点，并决定是补适配层、锁定可用版本，还是分阶段迁移。
|
||
|
||
## 事件设计
|
||
|
||
前端不直接依赖底层 `pi-agent` 原始事件。后端提供工作台自己的稳定事件：
|
||
|
||
- `assistant_text_delta`：assistant 正文增量。
|
||
- `tool_status_start`：一个工具开始或当前工具切换。
|
||
- `tool_status_update`：工具参数、目标、运行中描述更新。
|
||
- `tool_status_end`：工具完成、失败或取消。
|
||
- `tool_status_summary`：一轮回复的工具摘要更新。
|
||
- `assistant_done`：本轮回复完成。
|
||
- `assistant_error`：本轮回复异常。
|
||
|
||
每个工具事件至少包含：
|
||
|
||
- 工具调用 ID。
|
||
- 工具名。
|
||
- 面向用户的动作标签。
|
||
- 目标对象，例如文件名、页面名、命令摘要。
|
||
- 状态：运行中、完成、失败、取消。
|
||
- 分组类型。
|
||
- 是否可放入折叠摘要。
|
||
|
||
面向用户的动作标签优先来自新版事件里的自然语言意图；如果没有，就由后端根据工具名和参数生成。
|
||
|
||
## 前端结构
|
||
|
||
当前 `ChatPanel` 已经同时承担消息流、工具流、输入框、命令菜单、引用菜单等职责。实现时应把工具状态拆成独立小模块，而不是继续把逻辑塞进消息数组。
|
||
|
||
建议拆分：
|
||
|
||
- `ToolStatusRunway`：当前动态工具条。
|
||
- `ToolHistorySummary`：折叠工具摘要。
|
||
- `tool-status-model`：把 start/update/end 事件归并成当前状态和历史摘要。
|
||
- `formatToolStatus`：把工具名和参数转成人能看懂的短句。
|
||
|
||
消息对象里不再存一长串实时工具标记。工具状态应作为当前 assistant 回复的附属状态存在；历史消息只保留完成后的摘要数据。
|
||
|
||
## 视觉设计
|
||
|
||
动态工具条应满足：
|
||
|
||
- 彩色流动背景或流动边框。
|
||
- 有明确的当前动作动词。
|
||
- 目标文字可截断，不撑破布局。
|
||
- 工具切换时有轻微过渡。
|
||
- 深色和浅色主题都可读。
|
||
- 在手机宽度下不遮挡正文，不横向溢出。
|
||
|
||
折叠摘要应满足：
|
||
|
||
- 默认占用空间小。
|
||
- 能一眼看出做过哪些类型的事。
|
||
- 展开后清单结构清楚。
|
||
- 不和正文 Markdown 表格、列表样式混在一起。
|
||
|
||
## 错误和边界状态
|
||
|
||
- 工具失败：当前工具条变为失败态，摘要中该项标红或标记失败。
|
||
- 工具取消：当前工具条显示取消态，摘要保留已完成部分。
|
||
- 工具事件缺参数：显示工具名和通用动作，不显示空目标。
|
||
- 多个工具并行：工具条显示最近活跃工具，摘要中保留所有工具；如新版事件能提供并行状态，可显示“另有 N 项运行中”。
|
||
- 长文件路径：中间截断，保留文件名或末尾路径。
|
||
- 长命令：保留主命令和关键参数，展开后看完整命令。
|
||
- 会话恢复：历史消息显示折叠摘要，不恢复动态跑马灯。
|
||
|
||
## 验证方式
|
||
|
||
升级依赖后先做底层验证：
|
||
|
||
- 安装依赖。
|
||
- 类型检查。
|
||
- 启动后端和前端。
|
||
- 发送普通对话。
|
||
- 发送会触发知识库检索的问题。
|
||
- 发送会触发 read/write/bash 的任务。
|
||
- 检查 Skill 调用是否仍可用。
|
||
|
||
界面实现后做体验验证：
|
||
|
||
- 打开本地页面实际跑一次长任务。
|
||
- 确认屏幕上始终只有一个当前工具条，而不是一长串工具。
|
||
- 确认工具结束后出现折叠摘要。
|
||
- 展开摘要，确认分组和明细正确。
|
||
- 在深色和浅色主题下检查可读性。
|
||
- 在窄屏尺寸下检查不溢出、不遮挡输入框。
|
||
|
||
## 不做的事
|
||
|
||
- 不改用户本机全局 `omp`。
|
||
- 不直接修改 `node_modules`。
|
||
- 不为了工具条重做整个聊天系统。
|
||
- 不把完整工具输出全部展示在主聊天区。
|
||
- 不把这次升级扩展成桌面打包或新知识库能力。
|
||
|
||
## 成功标准
|
||
|
||
用户给 agent 一个复杂任务时，聊天区不再被工具流水账占满。用户始终能看到 agent 当前正在做什么；任务结束后，也能通过折叠摘要快速确认 agent 读了什么、写了什么、跑了什么。
|
||
|
||
最终观感应接近 `omp`：活、清楚、有节奏，而不是普通 Web 应用里的静态日志。
|