35 KiB

Raw Blame History

title	status	created	plan-type	depth	origin
feat: AgentKit Platform Experience Upgrade	active	2026-06-13	feat	deep	docs/brainstorms/2026-06-13-agentkit-platform-experience-upgrade-requirements.md

feat: AgentKit Platform Experience Upgrade

Summary

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

Problem Frame

AgentKit 后端能力丰富（ReAct、Skill、Pipeline、记忆、自进化、多 Agent 市场），但 GUI 仍处于"功能可用但体验粗糙"状态。核心痛点：对话空间被压缩到 1/4 屏幕、消息纯文本无高亮、首 Token 延迟 5-10 秒、无暗色主题、无交互反馈、Computer Use 为占位。需求文档（见 origin）定义了 25 个需求（R1-R25），本计划定义如何实现。

Key Technical Decisions

KTD-1: 布局重构通过调整 SplitPane 嵌套实现，子视图零修改。 当前 AgentLayout 使用三层 SplitPane（水平→左垂直+右垂直），重构为两层（水平→右垂直），ChatView 直接作为水平 SplitPane 的 first slot。QuadrantPanel 和 SplitPane 组件不变，只改 AgentLayout 的嵌套结构和路由映射。(see origin: R1)

KTD-2: 消息格式增强基于 MarkdownIt 插件扩展 + DOMPurify 白名单扩展。 当前 ChatMessage 已使用 MarkdownIt 渲染，添加 markdown-it-highlightjs 插件实现代码高亮，自定义 tool_call 和 file_preview 块级渲染器实现工具调用卡片和文件预览。关键：当前 DOMPurify 的 ALLOWED_TAGS 白名单不包含 div、img、button，自定义渲染器输出的 HTML 元素会被过滤，必须扩展白名单。不引入新的 Markdown 渲染引擎。(see origin: R8, R9, R10)

KTD-3: @-mention 通过扩展 WebSocket 消息协议实现。 在现有 WsClientMessage 的 sources 字段基础上扩展，引用项编码为 {type: "mention", mention_type: "file"|"skill"|"workflow"|"agent", id: string, label: string}，后端解析后注入 Agent 上下文。新增 /api/v1/portal/mention-suggest REST 端点提供 autocomplete 数据。(see origin: R13, R14)

KTD-4: Computer Use MVP 使用 pyautogui + screencapture 实现截屏和点击。 替换 DockerComputerUseSession 的 stub 为 LocalComputerUseSession，macOS 使用 screencapture 截屏 + pyautogui 执行点击/输入操作，Linux 使用 xdotool + scrot。不依赖 Docker 容器化。前端新增 ComputerUseView 实际界面替代占位页。(see origin: R19, R20)

KTD-5: 暗色主题通过 [data-theme="dark"] CSS 选择器覆盖 + 响应式 Ant Design token。 在现有 tokens.css 中添加 [data-theme="dark"] 块覆盖同名 CSS 变量，新增 stores/theme.ts 管理主题状态和 localStorage 持久化。关键：styles/theme.ts 的 readToken() 是模块加载时一次性执行的，切换主题后需重新调用生成新的 themeConfig 并传给 ConfigProvider，否则 Ant Design 组件不跟随暗色主题。(see origin: R11)

KTD-6: 响应速度优化 U1-U4 已实现，仅补充 portal.py 的 ReActEngine 复用。 HeuristicClassifier、_classify_merged、parallel_tools、AsyncWriteQueue 均已在代码中。chat.py 已有 ReActEngine 复用逻辑，但 portal.py 每次创建新实例，需对齐。(see origin: R5, R6, R7)

High-Level Technical Design

迭代 1 架构：对话体验质变

flowchart TB
    subgraph Frontend
        AL[AgentLayout] --> SP_H[SplitPane horizontal 55:45]
        SP_H --> CV[ChatView 全高]
        SP_H --> SP_V[SplitPane vertical 60:40]
        SP_V --> QP_TR[QuadrantPanel 右上]
        SP_V --> QP_BR[QuadrantPanel 右下]

        CV --> CI[ChatInput]
        CV --> CM[ChatMessage]
        CM --> MD[MarkdownIt + highlightjs]
        CM --> TC[ToolCallCard 渲染器]
        CM --> FP[FilePreview 渲染器]

        CI --> WS[WebSocket]
    end

    subgraph Backend
        WS --> PORTAL[portal.py]
        PORTAL --> HC[HeuristicClassifier 已实现]
        PORTAL --> MERGE[_classify_merged 已实现]
        PORTAL --> RE[ReActEngine 复用]
        RE --> STREAM[execute_stream]
        STREAM --> |token 事件| WS
    end

@-mention 数据流（迭代 2）

sequenceDiagram
    participant U as User
    participant CI as ChatInput
    participant API as /mention-suggest
    participant WS as WebSocket
    participant PORTAL as portal.py
    participant AGENT as Agent

    U->>CI: 输入 @
    CI->>API: GET /mention-suggest?q=keyword
    API-->>CI: [{type, id, label, icon}]
    U->>CI: 选择引用项
    CI->>CI: 添加 ContextPill
    U->>CI: 发送消息
    CI->>WS: {type:chat, message, mentions:[...]}
    WS->>PORTAL: 解析 mentions
    PORTAL->>PORTAL: 查询引用内容
    PORTAL->>AGENT: 注入上下文
    AGENT-->>WS: 流式响应
    WS-->>CI: 渲染响应

Requirements Traceability

Requirement	Iteration	Implementation Unit(s)
R1. 左对话+右双栏	1	U1
R2. 面板折叠	1	U1
R3. 侧边导航图标	1	U2
R4. 小屏幕适配	1	U1
R5. 启发式分类器	1	已实现
R6. 合并路由调用	1	已实现
R7. 首 Token 即渲染	1	U3
R8. 代码块高亮	1	U4
R9. 工具调用可视化	1	U5
R10. 图片/文件预览	1	U6
R11. 暗色主题	2	U7
R12. 组件样式统一	2	U8
R13. @-mention Autocomplete	2	U9
R14. @-mention 上下文注入	2	U10
R15. @-mention 引用标签	2	U9
R16. 过渡动画	2	U11
R17. 操作反馈	2	U12
R18. 空状态设计	2	U13
R19. 截屏查看	3	U14
R20. 简单点击操作	3	U14
R21. Computer Use 面板	3	U15
R22. 并行工具执行	3	已实现
R23. 异步会话写入	3	已实现
R24. 分割线拖拽增强	3	U16
R25. 面板折叠缩略预览	3	U17

Implementation Units

迭代 1：对话体验质变

U1. AgentLayout 布局重构

Goal: 将四象限等分布局重构为左对话+右双栏布局，对话面板占满左半屏。

Requirements: R1, R2, R4

Dependencies: None

Files:

src/agentkit/server/frontend/src/components/layout/AgentLayout.vue — 重构 SplitPane 嵌套
src/agentkit/server/frontend/src/router/index.ts — 移除 terminal 路由，调整 quadrant 元数据
src/agentkit/server/frontend/src/styles/responsive.css — 调整断点

Approach:

移除左侧垂直 SplitPane，ChatView 直接作为水平 SplitPane 的 #first slot
保留右侧垂直 SplitPane（右上：代码/工作流/知识库，右下：监控/技能/设置）
水平 SplitPane 默认比例改为 0.55（55:45）
移除 agent-terminal 路由定义
调整 responsive.css：≥1280px 完整展示，1024-1280px 右下面板默认折叠，<1024px 提示。注意： 当前 responsive.css 的选择器基于四象限布局结构（如 .split-pane--horizontal > .split-pane__second .split-pane--vertical > .split-pane__second .quadrant-panel），重构后这些选择器完全失效，必须根据新的两层 SplitPane 结构重写所有象限相关选择器

Patterns to follow: 现有 SplitPane 嵌套模式；QuadrantPanel 的 Tab 配置模式；localStorage 持久化 key 命名 agent-*

Test scenarios:

布局渲染为左对话+右双栏，ChatView 占满左半屏高度
左右分割线可拖拽，默认 55:45，范围 20%-80%
右侧上下分割线可拖拽，默认 60:40
分割比例保存到 localStorage，刷新后恢复
右上面板折叠后仅显示 Tab 栏（约 38px）
右下面板折叠后仅显示 Tab 栏
两个面板可同时折叠
折叠/展开有 200ms ease 过渡动画
屏幕宽度 <1024px 显示提示
屏幕宽度 1024-1280px 右下面板默认折叠
terminal 路由不再存在

Verification: 手动测试布局在不同屏幕宽度下的表现；折叠/展开动画流畅；localStorage 持久化正常。

U2. 侧边导航精简为图标模式

Goal: 将侧边导航精简为 32px 宽图标导航栏，点击图标切换右侧面板 Tab 并展开。

Requirements: R3

Dependencies: U1

Files:

src/agentkit/server/frontend/src/components/layout/TopNav.vue — 添加侧边导航切换按钮
src/agentkit/server/frontend/src/components/layout/IconNav.vue — 新建 32px 图标导航组件
src/agentkit/server/frontend/src/components/layout/AgentLayout.vue — 集成 IconNav

Approach:

新建 IconNav.vue：32px 宽图标导航栏，只显示图标（对话、工作流、知识库、技能、监控、设置）。注意：现有 SideNav.vue 是遗留的 AppLayout 组件（240px 宽暗色侧边栏），不在 AgentLayout 中使用，不需要修改。
点击图标：调用对应 QuadrantPanel 的 setActiveTab() 并展开面板
当前激活图标高亮（使用 --color-primary Token）
TopNav 添加折叠/展开 SideNav 的按钮
SideNav 状态保存到 localStorage

Patterns to follow: QuadrantPanel 的 setActiveTab() 暴露方法；现有 SideNav 的导航项定义模式

Test scenarios:

SideNav 宽度为 32px，只显示图标
点击对话图标，ChatView 获得焦点
点击工作流图标，右上面板切换到 workflow Tab 并展开
点击监控图标，右下面板切换到 monitor Tab 并展开
当前激活图标高亮
TopNav 按钮可折叠/展开 SideNav
折叠状态保存到 localStorage

Verification: 手动测试图标导航与面板联动；折叠/展开正常。

U3. 首步骤即渲染 + portal.py ReActEngine 复用

Goal: 前端接收到首个流式步骤即开始渲染；后端 portal.py 复用 ReActEngine 实例。

Requirements: R7

Dependencies: None

Files:

src/agentkit/server/frontend/src/stores/chat.ts — 确认流式渲染逻辑正确处理首个步骤
src/agentkit/server/frontend/src/components/chat/ChatMessage.vue — 确认流式内容渲染无闪烁
src/agentkit/server/routes/portal.py — ReActEngine 复用（对齐 chat.py 模式，覆盖 SSE + WS 两个路径）

Approach:

前端：当前 handleWsMessage 的 step 事件在 event_type === 'final_answer' 时逐块累加 content，确认首个步骤到达即渲染。注意：后端当前按"步骤"粒度推送（thinking/tool_call/tool_result/final_answer），不是逐 Token 推送。"首 Token 即渲染"在此架构下实际含义是"首步骤即渲染"——final_answer 事件的 data.output 是文本块，到达即显示。
后端：portal.py 有两处创建 ReActEngine（SSE 路径约第 342 行，WS 路径约第 661 行），均需改为复用 agent 上已绑定的 _react_engine（对齐 chat.py 第 197 行的 getattr(agent, "_react_engine", None) 模式）。复用时调用 react_engine.reset() 重置内部状态。
注意 agent_pool.py 的 create_agent_from_skill() 已在 agent 上绑定 agent._react_engine，portal.py 应优先使用该实例。

Patterns to follow: chat.py 的 getattr(agent, "_react_engine", None) 复用模式

Test scenarios:

发送简单问候，首 Token 在 1 秒内渲染
流式输出逐字显示，无整体延迟
ReActEngine 在同一会话中复用，不创建新实例
会话结束后 ReActEngine 正确重置
token 事件和 final_answer 事件均触发前端渲染更新

Verification: 手动测试对话首 Token 延迟；检查 portal.py 日志确认 ReActEngine 复用。

U4. 代码块语法高亮

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

Requirements: R8

Dependencies: None

Files:

src/agentkit/server/frontend/src/components/chat/ChatMessage.vue — 添加 highlight.js 插件 + 扩展 DOMPurify 白名单
src/agentkit/server/frontend/src/styles/ — 代码高亮主题样式
src/agentkit/server/frontend/package.json — 添加 highlight.js 依赖

Approach:

安装 highlight.js 和 markdown-it-highlightjs（或手动配置 MarkdownIt 的 highlight 选项）
在 ChatMessage 的 MarkdownIt 实例中配置 highlight 函数使用 highlight.js
代码高亮主题使用 Catppuccin Mocha（与 tokens.css 中的代码主题一致）
添加代码块复制按钮（点击复制代码内容到剪贴板，显示 Toast 反馈）
代码块语言标签显示在右上角
扩展 DOMPurify 白名单：当前 ALLOWED_TAGS 不包含 code、pre、span（highlight.js 生成的标签），需添加这些标签及 class、data-language 属性

Patterns to follow: 现有 MarkdownIt 配置模式；tokens.css 中的代码主题色（--color-code-*）

Test scenarios:

Python 代码块正确高亮（关键字、字符串、注释、函数名）
JavaScript 代码块正确高亮
未指定语言的代码块使用自动检测
复制按钮点击后内容复制到剪贴板，显示 Toast
代码块语言标签正确显示
流式输出时代码块逐步高亮（不闪烁）

Verification: 手动测试不同语言代码块的渲染效果。

U5. 工具调用可视化

Goal: 工具调用显示为可折叠的步骤卡片，展示工具名称、参数摘要、执行状态、结果预览。

Requirements: R9

Dependencies: U3

Files:

src/agentkit/server/frontend/src/components/chat/ChatMessage.vue — 添加工具调用渲染逻辑 + 扩展 DOMPurify 白名单
src/agentkit/server/frontend/src/components/chat/ToolCallCard.vue — 新建工具调用卡片组件

Approach:

创建 ToolCallCard.vue 组件：可折叠卡片，显示工具名称（图标+名称）、参数摘要（截断显示）、执行状态（pending/running/completed/error）、结果预览（折叠时显示前 2 行）
在 ChatMessage 中，检测 step 事件中的 tool_call 和 tool_result 事件类型，将配对的工具调用渲染为 ToolCallCard
利用 chat store 中 streamingSteps 的数据，匹配工具调用和结果
折叠/展开动画使用现有 transitions.css 的 collapse 类
扩展 DOMPurify 白名单：添加 div、button、data-tool-call、data-tool-result 等标签和属性，确保 ToolCallCard 的 HTML 不被过滤

Patterns to follow: 现有 streamingSteps 数据结构；transitions.css 的 collapse 动画；QuadrantPanel 的折叠模式

Test scenarios:

工具调用显示为卡片，包含工具名称和参数摘要
执行中状态显示 loading 指示器
完成后显示结果预览（前 2 行）
点击卡片展开查看完整参数和结果
多个工具调用按顺序显示
折叠/展开有平滑过渡动画
错误状态的工具调用显示错误信息

Verification: 手动测试触发工具调用的对话，验证卡片渲染和交互。

U6. 图片和文件预览

Goal: 消息中的图片内联显示缩略图，文件显示为可下载卡片。

Requirements: R10

Dependencies: U4

Files:

src/agentkit/server/frontend/src/components/chat/ChatMessage.vue — 添加图片/文件渲染逻辑 + 扩展 DOMPurify 白名单
src/agentkit/server/frontend/src/components/chat/FilePreview.vue — 新建文件预览卡片组件

Approach:

创建 FilePreview.vue 组件：文件名+大小+类型图标+下载按钮
在 ChatMessage 的 MarkdownIt 渲染中，自定义 image 渲染规则：内联缩略图，点击放大
检测消息中的文件链接（URL 以常见文件扩展名结尾），渲染为 FilePreview 卡片
图片缩略图使用 CSS object-fit: contain，最大高度 200px
扩展 DOMPurify 白名单：添加 img 标签及 src、alt、loading 属性

Patterns to follow: 现有 MarkdownIt 自定义渲染器模式；tokens.css 的间距和圆角 Token

Test scenarios:

消息中的图片 URL 显示为内联缩略图
点击缩略图放大查看
文件链接显示为卡片（文件名+大小+类型图标）
下载按钮点击触发文件下载
非图片/文件链接正常渲染为超链接

Verification: 手动测试包含图片和文件链接的消息渲染。

迭代 2：专业感 + 精准度

U7. 暗色主题 Token 定义与切换

Goal: 在浅色 Token 基础上新增暗色主题 Token 变体，支持一键切换。

Requirements: R11

Dependencies: U1

Files:

src/agentkit/server/frontend/src/styles/tokens.css — 添加 [data-theme="dark"] 块
src/agentkit/server/frontend/src/stores/theme.ts — 新建主题 store
src/agentkit/server/frontend/src/styles/theme.ts — 改造 readToken() 为可重复调用的函数，支持主题切换时重新生成 themeConfig
src/agentkit/server/frontend/src/components/layout/TopNav.vue — 添加主题切换按钮
src/agentkit/server/frontend/src/App.vue — 监听主题变化，更新 data-theme 属性和 ConfigProvider

Approach:

在 tokens.css 末尾添加 [data-theme="dark"] 选择器块，覆盖所有颜色变量（背景、前景、边框、品牌色、语义色、代码主题色）
暗色配色方案：深色背景 #1a1a2e 系列、荧光强调色、终端原生感
创建 stores/theme.ts：currentTheme ref（'light'|'dark'），toggleTheme() 方法，localStorage 持久化
改造 styles/theme.ts：当前 readToken() 在模块加载时一次性执行，生成静态 themeConfig。切换暗色主题后 CSS 变量值变了，但 themeConfig 不会重新计算。需将 themeConfig 改为响应式：导出 getThemeConfig() 函数，App.vue 监听 currentTheme 变化时重新调用生成新 config 并传给 ConfigProvider
App.vue 监听 currentTheme 变化，更新 document.documentElement.dataset.theme 和 ConfigProvider 的 theme prop
TopNav 添加太阳/月亮图标切换按钮

Patterns to follow: 现有 tokens.css 的变量命名模式；theme.ts 的 readToken() 运行时映射

Test scenarios:

点击切换按钮，界面从浅色切换到暗色
所有组件在暗色主题下正常显示（文字可读、对比度足够）
代码块在暗色主题下使用 Catppuccin Mocha 配色
主题偏好保存到 localStorage，刷新后恢复
切换过渡平滑（CSS transition on color variables）

Verification: 手动测试暗色主题下所有页面的显示效果。

U8. 组件样式统一

Goal: 所有组件统一引用 Design Token，消除硬编码值。

Requirements: R12

Dependencies: U7

Files:

src/agentkit/server/frontend/src/components/layout/SideNav.vue — 替换硬编码颜色
src/agentkit/server/frontend/src/App.vue — 替换 !important 全局覆盖为 Token 驱动
各组件 scoped 样式中的硬编码值逐一替换

Approach:

全局搜索 rgba(、# 开头的硬编码颜色值（排除 tokens.css 本身）
逐一替换为对应的 CSS 变量引用
App.vue 中的 Ant Design 全局覆盖从 !important 改为通过 ConfigProvider token 注入
确保暗色主题下替换后的变量值正确

Patterns to follow: tokens.css 的变量命名；theme.ts 的 readToken() 映射

Test scenarios:

零硬编码颜色值（tokens.css 除外）
浅色和暗色主题下所有组件样式一致
Ant Design 组件通过 ConfigProvider token 驱动样式
无 !important 覆盖（特殊情况除外）

Verification: 代码搜索确认无硬编码颜色值；双主题视觉验证。

U9. @-mention Autocomplete 前端

Goal: 对话输入框中输入 @ 触发下拉选择器，支持四类引用，选中后显示为 ContextPill。

Requirements: R13, R15

Dependencies: U1

Files:

src/agentkit/server/frontend/src/components/chat/ChatInput.vue — 添加 @-mention 触发和选择逻辑
src/agentkit/server/frontend/src/components/chat/MentionDropdown.vue — 新建下拉选择器组件
src/agentkit/server/frontend/src/api/client.ts — 添加 mention-suggest API 调用
src/agentkit/server/frontend/src/api/types.ts — 添加 MentionItem 类型定义 + 扩展 WsClientMessage 添加 mentions 字段

Approach:

定义 MentionItem 类型：{type: 'file'|'skill'|'workflow'|'agent', id: string, label: string, icon?: string, description?: string}
ChatInput 监听输入，检测 @ 字符触发 MentionDropdown
MentionDropdown 调用 /api/v1/portal/mention-suggest?q=keyword 获取建议列表
选中后生成 ContextPill 添加到 contextPills 数组（复用现有 ContextPillData 接口，扩展 type/id 字段）
发送消息时，将 mentions 数组附加到 WebSocket 消息
R15 覆盖：ChatMessage 渲染时检测消息的 mentions 元数据，将 @引用渲染为可点击的标签/链接（点击跳转到对应面板或打开详情）

⚠ 前后端协议耦合：U9 和 U10 必须在同一迭代内同步交付，否则 WebSocket 协议不兼容。

Patterns to follow: 现有 ContextPill 数据结构；Ant Design Vue 的 AutoComplete/Select 组件模式

Test scenarios:

输入 @ 触发下拉选择器
输入 @文件名 过滤显示匹配的知识库文档
输入 @技能名 过滤显示匹配的技能
输入 @工作流名 过滤显示匹配的工作流
输入 @Agent名 过滤显示匹配的 Agent
选中引用项后显示为 ContextPill
ContextPill 可点击删除
发送消息时 mentions 数组正确附加

Verification: 手动测试四类 @-mention 的 autocomplete 和选择流程。

U10. @-mention 后端上下文注入

Goal: 后端解析 @-mention 引用，将对应内容注入 Agent 推理上下文。

Requirements: R14

Dependencies: U9

Files:

src/agentkit/server/routes/portal.py — 解析 mentions，注入上下文
src/agentkit/server/routes/portal.py — 新增 /portal/mention-suggest 端点

Approach:

新增 GET /api/v1/portal/mention-suggest?q=keyword 端点，聚合查询知识库文档、技能、工作流、Agent，返回 MentionItem[]
WebSocket 消息中解析 mentions 字段
根据 mention_type 和 id 查询对应内容：
- file → 从 KnowledgeBase 检索文档片段
- skill → 从 SkillRegistry 获取技能描述和工具定义
- workflow → 从 WorkflowStore 获取工作流定义
- agent → 从 AgentPool 获取 Agent 配置
将引用内容作为结构化上下文注入 system_prompt 或 messages

Patterns to follow: 现有 portal.py 的路由和 CostAwareRouter 模式；各 Registry 的查询 API

Test scenarios:

/mention-suggest?q=test 返回匹配的文件、技能、工作流、Agent
@文件引用后，Agent 回复中引用了文档内容
@技能引用后，Agent 使用了指定技能
@工作流引用后，Agent 了解工作流定义
@Agent 引用后，Agent 了解目标 Agent 的能力
多个 @-mention 同时使用，所有引用内容均注入
无效引用（ID 不存在）优雅降级，不阻塞对话

Verification: 手动测试各类 @-mention 的上下文注入效果。

U11. 过渡动画

Goal: 为所有交互添加过渡动画。

Requirements: R16

Dependencies: U1

Files:

src/agentkit/server/frontend/src/styles/transitions.css — 确认/补充动画类
src/agentkit/server/frontend/src/components/layout/QuadrantPanel.vue — Tab 切换淡入淡出
src/agentkit/server/frontend/src/components/layout/AgentLayout.vue — 路由切换动画
各列表渲染组件 — 交错渐入

Approach:

确认 transitions.css 中已有 fade、collapse、scale、stagger-list 类
QuadrantPanel Tab 切换添加 <Transition name="fade"> 包裹
AgentLayout 路由切换添加 <Transition name="fade">
列表项使用 <TransitionGroup name="stagger-list">
所有时长引用 Design Token：--transition-fast: 150ms、--transition-normal: 200ms

Patterns to follow: 现有 transitions.css 的动画类定义模式

Test scenarios:

面板折叠/展开有 200ms ease 过渡
Tab 切换有 150ms 淡入淡出
列表项交错渐入（stagger 50ms）
路由切换有 200ms 淡入淡出
动画不阻塞交互（使用 CSS transition 而非 JS 动画）

Verification: 手动测试各交互动画效果。

U12. 操作反馈

Goal: 为用户操作提供即时反馈。

Requirements: R17

Dependencies: U7

Files:

src/agentkit/server/frontend/src/components/common/ToastService.ts — 新建 Toast 服务
src/agentkit/server/frontend/src/components/chat/ChatInput.vue — 按钮点击反馈
src/agentkit/server/frontend/src/components/layout/TopNav.vue — WebSocket 断连横幅
各加载状态组件 — 骨架屏替代 a-spin

Approach:

创建 ToastService：基于 Ant Design Vue 的 message 组件，封装 success/error/warning/info 方法
按钮点击添加 :active 缩放反馈（CSS transform: scale(0.97)）
加载状态：关键区域使用骨架屏（复用 transitions.css 的 skeleton-pulse 动画）
WebSocket 断连：TopNav 下方显示红色横幅提示，重连后自动消失

Patterns to follow: Ant Design Vue message 组件；transitions.css 的 skeleton-pulse 动画

Test scenarios:

操作成功显示绿色 Toast
操作失败显示红色 Toast
按钮点击有缩放反馈
加载状态显示骨架屏而非 Spin
WebSocket 断连时顶部显示红色横幅
重连后横幅自动消失

Verification: 手动测试各类操作反馈。

U13. 空状态设计

Goal: 为所有空状态提供品牌化插图和引导文案。

Requirements: R18

Dependencies: U7

Files:

src/agentkit/server/frontend/src/components/common/EmptyState.vue — 新建空状态组件
src/agentkit/server/frontend/src/views/ChatView.vue — 对话空状态
src/agentkit/server/frontend/src/views/WorkflowView.vue — 工作流空状态
src/agentkit/server/frontend/src/views/EvolutionView.vue — 监控空状态
src/agentkit/server/frontend/src/views/KnowledgeBaseView.vue — 知识库空状态
src/agentkit/server/frontend/src/views/SkillsView.vue — 技能空状态

Approach:

创建 EmptyState.vue 通用组件：接受 title、description、icon、action props
各视图在数据为空时渲染 EmptyState，提供引导文案和操作按钮
图标使用 Ant Design Vue 的内置图标，配合品牌色

Patterns to follow: Ant Design Vue 的 a-empty 组件模式

Test scenarios:

对话空状态显示"开始你的第一次对话"引导
工作流空状态显示"创建第一个工作流"引导
监控空状态显示数据来源说明
知识库空状态显示"上传文档或配置信息源"引导
技能空状态显示"注册技能"引导
空状态组件在暗色主题下正常显示

Verification: 手动测试各视图的空状态显示。

迭代 3：能力扩展

U14. Computer Use MVP 后端（pyautogui + screencapture）

Goal: 实现本地截屏和点击操作的后端闭环。

Requirements: R19, R20

Dependencies: None

Files:

src/agentkit/tools/computer_use_session.py — 新增 LocalComputerUseSession 类
src/agentkit/tools/computer_use.py — 确保工具注册和降级链正确

Approach:

创建 LocalComputerUseSession 类，实现 start()、stop()、screenshot()、execute_action() 方法
screenshot() 实现：macOS 使用 screencapture -x -t png <path> 命令截屏，读取文件返回 base64；Linux 使用 scrot 或 xdg-screenshot
execute_action() 实现：使用 pyautogui 库执行点击（pyautogui.click(x, y)）、输入（pyautogui.typewrite()）、滚动等操作
注册到 ComputerUseSessionManager，作为默认会话类型（替代 Docker stub）
确保降级链正确：Anthropic API → LocalComputerUseSession → Shell 替代建议
添加 pyautogui 到项目依赖（pyproject.toml）

Patterns to follow: 现有 InMemoryComputerUseSession 的接口模式；ToolRegistry 注册模式

Test scenarios:

OpenCLI 会话创建和销毁正常
截屏返回有效的 base64 PNG 数据
点击操作执行并返回结果
ComputerUseTool 的降级链正确工作
会话管理器正确管理 OpenCLI 会话生命周期

Verification: 手动测试通过对话触发截屏和点击操作。

U15. Computer Use 前端面板

Goal: 右上面板新增 Computer Use Tab，展示截屏画面和操作历史。

Requirements: R21

Dependencies: U14

Files:

src/agentkit/server/frontend/src/views/ComputerUseView.vue — 替换占位页为实际界面
src/agentkit/server/frontend/src/components/layout/AgentLayout.vue — 右上面板添加 Computer Use Tab
src/agentkit/server/frontend/src/router/index.ts — 添加 Computer Use 路由

Approach:

重写 ComputerUseView.vue：截屏画面显示区域（支持缩放和滚动）、操作历史列表、手动截屏按钮
截屏画面通过 WebSocket 接收 base64 图片数据，渲染为 <img> 标签
操作历史显示时间戳、操作类型、坐标/参数、结果摘要
手动截屏按钮触发后端截屏命令
右上面板 QuadrantPanel 添加 Computer Use Tab

Patterns to follow: 现有 QuadrantPanel Tab 配置模式；WebSocket 消息处理模式

Test scenarios:

Computer Use Tab 在右上面板显示
截屏画面正确渲染
截屏画面支持缩放和滚动
操作历史按时间倒序显示
手动截屏按钮触发截屏
暗色主题下正常显示

Verification: 手动测试 Computer Use 面板的截屏显示和操作历史。

U16. 分割线拖拽增强

Goal: 拖拽分割线时高亮显示，显示当前比例百分比。

Requirements: R24

Dependencies: U1

Files:

src/agentkit/server/frontend/src/components/layout/SplitPane.vue — 添加拖拽高亮和比例显示

Approach:

拖拽时 handle 元素添加高亮样式（加宽 + 品牌色背景）
拖拽时显示比例百分比标签（如 "55%"），定位在 handle 旁边
使用 CSS transition 确保高亮和标签的显示/隐藏平滑

Patterns to follow: 现有 SplitPane 的拖拽逻辑和 handle 样式

Test scenarios:

拖拽时分割线高亮
拖拽时显示当前比例百分比
百分比标签定位正确不遮挡内容
拖拽结束后高亮和标签消失

Verification: 手动测试拖拽交互。

U17. 面板折叠缩略预览

Goal: 面板折叠时显示缩略内容预览。

Requirements: R25

Dependencies: U1

Files:

src/agentkit/server/frontend/src/components/layout/QuadrantPanel.vue — 折叠时显示缩略预览

Approach:

折叠状态下，在 Tab 栏下方显示约 60px 高的缩略预览区域
预览内容根据当前活跃 Tab 类型显示：监控显示关键指标数字、技能显示技能数量、工作流显示节点缩略图
预览区域使用半透明背景，不占用过多空间

Patterns to follow: QuadrantPanel 的折叠模式；Design Token 的间距和圆角

Test scenarios:

右上面板折叠后显示缩略预览
右下面板折叠后显示缩略预览
预览内容根据活跃 Tab 更新
预览区域不遮挡 Tab 栏
暗色主题下预览区域正常显示

Verification: 手动测试折叠预览效果。

Scope Boundaries

在范围内： 见需求文档的 Scope Boundaries。

延迟到后续迭代：

Cmd+K 内联编辑
Computer Use Docker 容器化隔离
代码 Diff 查看器实现
代码 Diff Accept/Reject 回滚
响应式移动端适配
httpx 连接池配置优化（U5 已实现，无需额外工作）
A/B 测试框架和性能基准 CI
Ant Design Vue 按需引入（unplugin-vue-components）
ECharts 按需引入

不在本产品身份内：

多用户协作/实时协同编辑
插件市场
代码编辑器

Risks & Mitigations

Risk	Likelihood	Impact	Mitigation
@-mention 后端查询聚合性能差	Medium	Medium — 慢速 autocomplete 影响体验	mention-suggest 端点添加缓存（TTL 30s），结果集限制 20 条
本地截屏兼容性问题	Medium	High — 不同 OS 环境截屏命令不同	检测 OS 类型选择对应命令，添加 fallback 到 InMemory 模式
暗色主题对比度不足	Low	Medium — 部分组件在暗色下不可读	使用 WCAG AA 标准验证对比度，添加自动化对比度检查
消息格式增强破坏现有渲染	Low	High — 已有消息显示异常	MarkdownIt 插件添加 fallback，解析失败时回退到纯文本；DOMPurify 白名单扩展需谨慎测试
布局重构影响现有路由和状态	Medium	Medium — localStorage 旧 key 导致异常	添加 key 版本化，旧 key 自动迁移或清理
DOMPurify 白名单扩展引入 XSS	Low	High — 恶意内容可能注入	仅添加必要的标签和属性，不开放 `on*` 事件属性，`img` 的 `src` 限制为相对路径和已知域名
Ant Design token 不跟随暗色切换	Medium	Medium — 组件颜色不一致	改造 theme.ts 为响应式，切换时重新生成 themeConfig
与 001 计划的 U-unit 重叠	High	High — 并行执行产生合并冲突	003 吸收 001 的重叠 U-unit，001 标注为"由 003 覆盖"，不并行执行

System-Wide Impact

前端布局： AgentLayout 从三层 SplitPane 改为两层，所有依赖象限位置的路由和状态需调整
前端样式： 暗色主题影响所有组件，需全面测试
WebSocket 协议： @-mention 扩展了 WsClientMessage 的 mentions 字段，需前后端同步升级
后端路由： 新增 /portal/mention-suggest 端点，portal.py 需解析 mentions
工具系统： 新增 OpenCLIComputerUseSession，ComputerUseTool 降级链调整
响应速度： portal.py 的 ReActEngine 复用减少实例创建开销

Outstanding Questions

Deferred to Implementation:

@-mention 后端解析的具体协议细节：mentions 字段在 WebSocket 消息中的 JSON 结构
工具调用步骤卡片的折叠/展开交互细节：默认折叠还是展开
骨架屏的具体形状和占位内容
暗色主题的具体色值需要视觉调优
R22/R23 对 portal.py 路径无效的决策：portal.py 使用自己的 ConversationStore（内存 dict），不使用 SessionManager，异步写入和并行工具执行对 portal 路径无影响。是否需要迁移 portal.py 到 SessionManager？

Plan Relationship:

本计划（003）吸收了 001 计划（GUI 产品化）的所有重叠 U-unit（布局重构、暗色主题、交互增强），001 计划应标注为"由 003 覆盖"，避免并行执行产生合并冲突

Sources & Research

需求文档：docs/brainstorms/2026-06-13-agentkit-platform-experience-upgrade-requirements.md
响应速度优化计划（U1-U4 已实现）：docs/plans/2026-06-12-021-feat-chat-response-speed-optimization-plan.md
GUI 产品化计划（前一轮）：docs/plans/2026-06-13-001-feat-gui-productization-plan.md
前端产品化计划：docs/plans/2026-06-12-023-feat-frontend-productization-plan.md
现有 Design Token 体系：src/agentkit/server/frontend/src/styles/tokens.css
现有 WebSocket 协议：src/agentkit/server/frontend/src/api/types.ts
现有 Computer Use 工具：src/agentkit/tools/computer_use.py、src/agentkit/tools/computer_use_session.py

35 KiB Raw Blame History Unescape Escape

feat: AgentKit Platform Experience Upgrade

Summary

Problem Frame

Key Technical Decisions

High-Level Technical Design

迭代 1 架构：对话体验质变

@-mention 数据流（迭代 2）

Requirements Traceability

Implementation Units

迭代 1：对话体验质变

U1. AgentLayout 布局重构

U2. 侧边导航精简为图标模式

U3. 首步骤即渲染 + portal.py ReActEngine 复用

U4. 代码块语法高亮

U5. 工具调用可视化

U6. 图片和文件预览

迭代 2：专业感 + 精准度

U7. 暗色主题 Token 定义与切换

U8. 组件样式统一

U9. @-mention Autocomplete 前端

U10. @-mention 后端上下文注入

U11. 过渡动画

U12. 操作反馈

U13. 空状态设计

迭代 3：能力扩展

U14. Computer Use MVP 后端（pyautogui + screencapture）

U15. Computer Use 前端面板

U16. 分割线拖拽增强

U17. 面板折叠缩略预览

Scope Boundaries

Risks & Mitigations

System-Wide Impact

Outstanding Questions

Sources & Research

35 KiB

Raw Blame History