---
date: "2026-06-13"
topic: "agentkit-platform-experience-upgrade"
---

## Summary

Fischer AgentKit 平台体验全面升级——布局重构为左对话+右双栏、对话体验深化（首 Token 即渲染+消息格式增强+@-mention 四类引用）、响应速度核心优化（启发式路由+合并 LLM 调用）、暗色主题与交互增强、Computer Use MVP——分三个冲击波迭代交付。

## Problem Frame

当前 AgentKit 处于"后端能力丰富、前端体验粗糙"的失衡状态。后端已实现 ReAct 推理、Skill 系统、Pipeline 编排、三层记忆、自进化、多 Agent 市场等完整能力，但 GUI 仍停留在功能可用层面：四象限等分布局让对话空间被压缩到 1/4 屏幕；消息仅支持纯文本渲染，代码块无高亮、工具调用无可视化；用户输入后需等待 5-10 秒才看到首个响应 Token；无暗色主题、无过渡动画、无操作反馈；Computer Use 前后端均为占位状态。

竞品（Devin、Cursor、v0.dev）已普遍采用 Agent-First 布局 + 统一设计系统 + 流式渲染 + 视觉操作能力。AgentKit 需要对齐这一标准，将"能用"升级为"好用"。

## Key Decisions

**冲击波迭代策略。** 三个迭代各聚焦一个体验质变：迭代 1 解决对话"快且宽敞"（布局+速度+格式），迭代 2 解决"丰富且精准"（双主题+@-mention+交互），迭代 3 解决"专业且全能"（Computer Use+剩余优化）。每个迭代交付后用户都能感受到明确的体验提升。

**四线并行。** GUI 产品化、Chat 体验深化、响应速度优化、Computer Use 四条线并行推进，每个迭代从每条线各取一部分，交叉组合为端到端可交付的体验升级。

**Computer Use MVP 先截屏后容器。** 先实现截屏查看+简单点击操作的前后端闭环，Docker 容器化隔离延后。MVP 让用户能通过对话让 Agent"看到"屏幕并执行简单操作，验证价值后再投入容器化成本。

**@-mention 四类全覆盖。** 支持 @文件、@技能、@工作流、@Agent 四类引用，在对话输入框中通过 autocomplete 下拉选择，选中后作为上下文注入 Agent 推理。

**Cmd+K 内联编辑延后。** AgentKit 当前没有代码编辑器，Cmd+K 的场景定义不清，延后到代码预览集成完成后再评估。

## Actors

- A1. **开发者/运维工程师** — 通过对话面板与 Agent 交互，使用 @-mention 引用上下文，通过 Computer Use 让 Agent 操作远程环境
- A2. **Agent** — 接收用户消息，执行推理和工具调用，流式返回结果，响应 @-mention 注入的上下文

## Requirements

### 迭代 1：对话体验质变

#### 布局重构

R1. 左对话 + 右双栏布局 — AgentLayout 从四象限等分布局重构为左半屏对话面板 + 右半屏上下双栏（上：代码/工作流/知识库，下：监控/技能/设置），左右分割默认 55:45，右侧上下分割默认 60:40，分割比例保存到 localStorage

R2. 面板折叠为 Tab 栏 — 每个面板可独立折叠为约 38px 的 Tab 栏，折叠状态保存到 localStorage，折叠/展开有 200ms ease 过渡动画

R3. 侧边导航精简为图标模式 — 32px 宽图标导航栏，点击图标切换右侧面板 Tab 并展开，当前激活图标高亮，导航栏可通过 TopNav 按钮折叠/展开

R4. 小屏幕适配 — <1024px 显示提示，1024-1280px 右下面板默认折叠，≥1280px 完整展示

#### 响应速度核心

R5. 启发式分类器替代 LLM quick_classify — 用零成本的本地启发式规则（消息长度、关键词密度、工具提示检测）替代 `CostAwareRouter.quick_classify()` 的 LLM 调用，通过配置开关可回退到 LLM 模式

R6. 合并路由 LLM 调用 — 当启发式不确定需要 LLM 路由时，将复杂度评分和意图分类合并为单次 LLM 调用，而非两次串行调用

R7. 首 Token 即渲染 — 前端 WebSocket 接收到首个流式 Token 即开始渲染，不等完整块；后端 ReActEngine 流式输出与前端渲染对齐

#### 消息格式增强

R8. 代码块语法高亮 — 消息中的代码块自动识别语言并语法高亮，支持复制按钮

R9. 工具调用可视化 — 工具调用显示为可折叠的步骤卡片，展示工具名称、参数摘要、执行状态、结果预览，替代当前的纯文本标签

R10. 图片和文件预览 — 消息中的图片内联显示缩略图，文件显示为可下载卡片（文件名+大小+类型图标）

### 迭代 2：专业感 + 精准度

#### 设计系统

R11. 暗色主题 — 在浅色 Token 基础上新增暗色主题 Token 变体，TopNav 增加主题切换按钮，偏好保存到 localStorage，暗色配色为深色背景+荧光强调色+终端原生感

R12. 组件样式统一 — 所有组件统一引用 Design Token，消除硬编码值，Ant Design 全局覆盖通过 Token 驱动

#### @-mention 上下文引用

R13. @-mention Autocomplete — 对话输入框中输入 `@` 触发下拉选择器，支持 @文件（知识库文档）、@技能（已注册技能）、@工作流（已有工作流）、@Agent（已配置 Agent），支持模糊搜索

R14. @-mention 上下文注入 — 选中的引用项作为结构化上下文注入 Agent 推理，后端解析引用类型和 ID，将对应内容（文档片段、技能描述、工作流定义、Agent 配置）加入对话上下文

R15. @-mention 引用标签 — 输入框中已选引用显示为可删除的标签（类似 ContextPill），发送后消息中显示为可点击的引用链接

#### 交互增强

R16. 过渡动画 — 面板折叠/展开 200ms ease、Tab 切换 150ms 淡入淡出、列表项交错渐入 stagger 50ms、路由切换 200ms 淡入淡出

R17. 操作反馈 — 按钮点击波纹/缩放反馈、加载状态骨架屏替代 `a-spin`、成功/失败 Toast 提示、WebSocket 断连顶部横幅

R18. 空状态设计 — 对话/工作流/监控/知识库/技能空状态各有品牌化插图和引导文案

### 迭代 3：能力扩展

#### Computer Use MVP

R19. 截屏查看 — Agent 可对目标环境执行截屏操作，截图实时显示在 Computer Use 面板中，支持缩放和滚动

R20. 简单点击操作 — Agent 可在截屏上执行点击操作（指定坐标），操作结果通过新的截屏反馈

R21. Computer Use 面板 — 右上面板新增 Computer Use Tab，展示截屏画面和操作历史，支持手动截屏触发

#### 响应速度剩余优化

R22. 并行工具执行 — ReActEngine 中多个独立 tool_calls 使用 `asyncio.gather()` 并行执行，结果按 tool_call_id 顺序追加，通过配置开关可回退串行模式

R23. 异步会话写入 — SessionManager 的 `append_message()` 改为非阻塞，使用写前缓冲区防止消息丢失，优雅关闭时 flush

#### 拖拽交互增强

R24. 分割线拖拽增强 — 拖拽时高亮分割线，显示当前比例百分比

R25. 面板折叠缩略预览 — 面板折叠时显示缩略内容预览

## Key Flows

- F1. 对话为主的工作流
  - **Trigger:** 用户打开 AgentKit
  - **Steps:** 左侧对话面板占满左半屏 → 用户输入消息 → 启发式分类器即时判断复杂度 → ReActEngine 流式推理 → 首 Token 即渲染 → 工具调用显示为步骤卡片 → 代码块语法高亮 → 右侧按需展示辅助信息
  - **Covered by:** R1, R5, R7, R8, R9

- F2. @-mention 上下文引用
  - **Trigger:** 用户在对话输入框输入 `@`
  - **Steps:** 下拉选择器弹出 → 用户输入关键词模糊搜索 → 选择引用项 → 引用显示为标签 → 发送消息 → 后端解析引用 → 对应内容注入 Agent 上下文 → Agent 基于引用内容推理
  - **Covered by:** R13, R14, R15

- F3. Computer Use 操作
  - **Trigger:** 用户让 Agent 执行视觉操作（如"帮我点击屏幕上的保存按钮"）
  - **Steps:** Agent 调用截屏工具 → 截图显示在 Computer Use 面板 → Agent 分析截图定位目标 → 执行点击操作 → 新截屏反馈操作结果 → 用户可在面板中查看操作历史
  - **Covered by:** R19, R20, R21

- F4. 主题切换
  - **Trigger:** 用户点击 TopNav 主题切换按钮
  - **Steps:** 点击月亮/太阳图标 → 所有 Token 变量切换 → 界面平滑过渡 → 偏好保存到 localStorage
  - **Covered by:** R11

## Scope Boundaries

**在范围内：**
- 布局重构（左对话 + 右双栏）
- Design Token 体系 + 双主题
- 组件样式统一
- 首 Token 即渲染
- 消息格式增强（代码高亮、工具调用卡片、图片/文件预览）
- @-mention 四类引用（文件、技能、工作流、Agent）
- 响应速度优化（启发式路由、合并调用、并行工具、异步写入）
- Computer Use MVP（截屏+点击，不含 Docker 容器化）
- 过渡动画、操作反馈、空状态、拖拽增强
- 侧边导航精简
- 小屏幕适配

**延迟到后续迭代：**
- Cmd+K 内联编辑
- Computer Use Docker 容器化隔离
- 代码 Diff 查看器实现（右上「代码」Tab 仍为占位）
- 代码 Diff 的 Accept/Reject 实际回滚功能
- 响应式移动端适配
- httpx 连接池配置优化
- A/B 测试框架和性能基准 CI

**不在本产品身份内：**
- 多用户协作/实时协同编辑
- 插件市场
- 代码编辑器（只读预览，不提供编辑能力）

## Success Criteria

1. **布局合理** — 对话面板占左半屏，右侧辅助信息可按需折叠
2. **首 Token <1s** — 简单对话（问候、Q&A）首 Token 延迟低于 1 秒
3. **消息丰富** — 代码块有语法高亮，工具调用有可视化卡片，图片/文件有预览
4. **@-mention 可用** — 四类引用均可 autocomplete 选择并注入上下文
5. **双主题可用** — 浅色/暗色一键切换，所有组件在两种主题下正常显示
6. **Computer Use MVP** — Agent 能截屏查看并执行点击操作
7. **交互流畅** — 所有过渡动画 ≤200ms，操作有即时反馈
8. **渐进交付** — 分 3 个迭代完成，每个迭代可独立部署

## Dependencies / Assumptions

- 现有 SplitPane 和 QuadrantPanel 组件支持水平和垂直分割，可直接复用
- Ant Design Vue 4.x 的 ConfigProvider 支持 CSS 变量主题注入
- ChatView 的 ChatSidebar 默认折叠，不影响左侧对话面板的空间利用
- Vue 3 的 `<Transition>` 和 `<TransitionGroup>` 可满足过渡动画需求
- `CostAwareRouter` 已有 `_tokenize_content()` 和 `_match_layer0()` 规则基础，启发式分类器可复用
- `IntentRouter._classify_with_llm()` 的 prompt 结构可扩展为同时返回复杂度评分
- Computer Use MVP 不依赖 Docker，可直接在宿主环境执行截屏和点击
- 现有 `tools/computer_use_session.py` 的 TODO 占位需要替换为实际实现
- 响应速度优化已有详细实施计划（docs/plans/2026-06-12-021-feat-chat-response-speed-optimization-plan.md），U1-U6 可直接沿用

## Outstanding Questions

**Resolved:**
- Computer Use MVP 的截屏实现方式：使用 OpenCLI

**Deferred to Planning:**
- @-mention 后端解析的具体协议：引用项如何在 WebSocket 消息中编码，与现有 `chat` 消息类型如何兼容
- 工具调用步骤卡片的折叠/展开交互细节
- 骨架屏的具体形状和占位内容