Desktop 使用手册

AgentHub Desktop 是 Tauri 2 原生本地工作台，用来运行、审查和批准 Agent 工作。它与 Web 和 Mobile 共享同一套工作台 UI，以聊天消息展示对话内容，以独立面板展示 diff、文件和产出。

什么时候使用 Desktop

适合使用 Desktop 的场景：

• workspace 在本机；
• runtime 需要本地 CLI 登录、本地 shell 或本地文件上下文；
• 写入前需要检查 diff、文件、preview 或终端输出；
• 任务之后需要同步到 Hub，作为审计、评审或团队可见记录。

如果任务已经由 Hub 承载且不需要直接访问本地进程，可以使用 Web（端口 5174）。Web 与 Desktop 共享同一套工作台 UI，通过 Hub 访问协作状态而不是直接连接 Local Edge。

界面地图

界面	归属	作用
Workspace 选择	Desktop	选择本地 workspace，并显示是否被 Local Edge 允许
Edge 选择	Desktop	选择本地 Edge 或授权后的远程 target
聊天流	Desktop	展示用户指令、Agent 回复消息、工具进度和 run 状态
文件面板	Desktop + Edge	展示变更文件、只读预览和产出
Diff 面板	Desktop + Edge	apply、commit 或 publish 前审查变更
终端面板	Desktop + Edge	展示命令状态，不隐藏 exit code、cwd 和审批上下文
审批控件	Desktop	对写入、shell、网络和发布动作做显式审批

第一轮会话检查

运行真实任务前：

1. 启动 Local Edge 并确认 health。
2. 打开 Desktop，确认显示的 Edge URL 与 Local Edge URL 一致。
3. 选择一个小的 workspace。
4. 第一轮使用 mock runtime。
5. 发送只读任务。
6. 确认会话记录、run event、文件预览和最终状态正常渲染且没有溢出。
7. mock 链路健康后，再切换 Claude Code、Codex、OpenCode 或自定义 adapter。

curl.exe http://127.0.0.1:3210/health
curl.exe http://127.0.0.1:3210/v1/health

Runtime 控制

Desktop 在 run 开始前明确显示所选 runtime。可用的 run 记录至少包含：

字段	为什么重要
Runtime adapter	区分 mock、Claude Code、Codex、OpenCode 和自定义引擎
Workspace	避免误操作到非目标项目
审批策略	说明 Agent 是否可以读、写、运行 shell 或发布
Model/provider 边界	将 provider 凭据和 UI 文案分离
Timeout 和 cancellation	让挂起 runtime 可恢复

如果真实 runtime 失败但 mock 正常，先排查本地 CLI 安装、登录、provider key 和 adapter 日志。

Diff 与文件审查

Desktop 的审查链路是保守的：

1. Runtime 流式输出消息和工具状态。
2. Edge 归一化 file、diff 和产出事件。
3. Desktop 以只读方式渲染候选变更。
4. 用户批准 apply、reject、continue 或 escalate。
5. Edge 记录审批和结果状态。
6. Hub 在授权后同步 review 和 audit 事实。

批准必须是显式产品事件，preview 与审批是两回事。

主题与语言

Desktop 与公开官网共享同一套产品词汇和视觉方向，与 Web 和 Mobile 保持一致：

• TokenDance Blue 是主强调色。
• 默认是浅色优先的玻璃界面。
• runtime logo 尽量使用 canonical brand icon。
• zh/en 文案描述同一能力和状态。
• 官网 mock 的主题切换能代表 Desktop 界面对主题变化的响应。

需要留存的证据

一条有用的 Desktop QA 记录应包含：

证据	示例
Edge health	loopback URL 和 2xx 结果
Runtime	mock、Claude Code、Codex、OpenCode 或自定义 adapter
Workspace	脱敏路径或项目别名
Run 状态	started、streaming、awaiting approval、completed、failed 或 cancelled
Review 状态	files changed、diff visible、approval requested、approval resolved
UI 状态	主题/语言切换后，桌面端和移动端网站 mock 仍可读

公开截图不要包含私有 workspace 路径、真实 provider key、私有日志或完整模型输出。

在 GitHub 编辑此页