AgentHub
文档

Desktop 使用手册

AgentHub Desktop 是本地工作台，用来运行、审查和批准 Agent 工作。只要任务涉及本地文件、本地工具、终端或不应暴露给 Web 的凭据，都应优先使用 Desktop。

范围

本页描述 Desktop + Local Edge 的目标体验。Desktop 仍在活跃开发，具体菜单名称可能调整，但职责边界保持稳定。

何时使用 Desktop

适合使用 Desktop 的场景：

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

如果任务已经由 Hub 承载且不需要本地进程访问，可以使用 Web。Web 不能绕过 Hub 直接访问 Local Edge 或本地文件。

界面地图

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

第一轮会话检查

运行真实任务前：

  1. 启动 Local Edge 并确认 health。
  2. 打开 Desktop，确认显示的 Edge URL 与 Local Edge URL 一致。
  3. 选择一个小的 allowlisted workspace。
  4. 第一轮使用 mock runtime。
  5. 发送只读任务。
  6. 确认 transcript、run event、文件预览和最终状态正常渲染且没有溢出。
  7. mock 链路健康后，再切换 Claude Code、Codex、OpenCode 或自定义 adapter。
powershell
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避免误操作到非目标项目
Approval policy说明 Agent 是否可以读、写、运行 shell 或发布
Model/provider 边界防止 provider 凭据进入网站或 UI 文案
Timeout 和 cancellation让挂起 runtime 可恢复

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

Diff 与文件审查

Desktop 的审查链路保持保守：

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

漂亮的 preview 不等于批准。批准必须是显式的产品事件。

主题与语言

Desktop 与公开官网共享同一套产品词汇和视觉方向：

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

需要留存的证据

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

证据示例
Edge healthloopback URL 和 2xx 结果
Runtimemock、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、私有日志或完整模型输出。