6.9 KiB
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 项”。
- 用户展开后可以看到完整工具清单。
摘要示例：
工具摘要
Read (6)
✓ SKILL.md:1-80
✓ README.md:1-80
✓ workbench/PRODUCT.md
Write (4)
✓ wiki/sources/...
Bash (2)
✓ npm run typecheck
底层升级策略
先开分支验证项目内 pi-agent 依赖升级，而不是直接改功能。
验证目标：
- 项目能安装成功。
- 后端能启动。
- 前端能连接后端。
- 基础对话能跑通。
- 当前知识库上下文仍能注入。
- Skill 调用仍能工作。
- 会话历史仍能读取。
- 新版事件里能拿到工具名、工具参数、工具状态、必要时的运行中更新。
如果新版依赖改了包名、导出路径或事件格式，后端要增加一个适配层，把新版事件统一整理成前端使用的稳定事件。
如果升级验证失败，不应退回到简陋前端方案；应记录失败点，并决定是补适配层、锁定可用版本，还是分阶段迁移。
事件设计
前端不直接依赖底层 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 应用里的静态日志。