AgentHub
更新于 2026-06-19

快速上手

本指南帮你跑通本地预览链路：Desktop 连接 Local Edge，接入 runtime adapter，再根据需要加入 Web。Mobile 走独立路径。

NOTE

预览范围 本页覆盖 Desktop（Tauri 2，端口 5173）、Web（端口 5174）和 Local Edge 的本地开发和预览。Mobile（Expo RN，端口 5177）、飞书/Lark 生产集成、Remote/Cloud Edge 和完整的 Web + Hub + Edge 路由仍在开发中。

准备条件

你需要：

  • Git、Go 1.25+、Node.js 20+ 和 pnpm。
  • AgentHub 源码仓库。
  • 一个可本地运行的 runtime，例如 Claude Code、Codex、OpenCode 或 mock runtime。
  • 使用真实 runtime 时，把模型 provider 凭据放在本地环境变量中。

模型 API key 只放在本地环境变量或服务端 secret 存储里，不要写进公开文档、前端代码、飞书卡片 payload 或浏览器存储。

步骤 1：克隆 AgentHub

git clone https://github.com/TokenDanceLab/AgentHub.git
cd AgentHub
.\scripts\setup.ps1

macOS 或 Linux 环境请按 AgentHub 仓库 README 中的等价方式安装本地依赖。

克隆后确认自己所在的子系统：

路径作用本指南是否需要
app/desktopDesktop UI（Tauri 2），本地执行的主要入口需要
app/webHub 驱动的 Web 协作界面（端口 5174）可选
app/sharedDesktop 和 Web 共享的工作台 UI 组件阅读
app/mobileExpo React Native 移动客户端（端口 5177）独立路径
edge-serverLocal Edge，管理 workspace、run、adapter 注册和事件日志需要
hub-serverHub API，管理 session、project、message、agent 协作和审计可选
api/OpenAPI、事件词汇和协议约定阅读

步骤 2：启动 Local Edge

在 AgentHub 仓库中运行：

cd edge-server
go run ./cmd/agenthub-edge --addr 127.0.0.1:3210 --runner-profile agenthub-runner-mock

如果只是验证 UI、事件流和 diff 渲染，建议先用 mock runtime。本地 UI 链路稳定后，再切到真实 runtime：

go run ./cmd/agenthub-edge --addr 127.0.0.1:3210 --runner-profile claude-code --agent-default claude-code
go run ./cmd/agenthub-edge --addr 127.0.0.1:3210 --runner-profile codex --agent-default codex
go run ./cmd/agenthub-edge --addr 127.0.0.1:3210 --runner-profile opencode --agent-default opencode

--runner-profile 选择兼容 runtime preset。--agent-default 选择 run 未指定 agentId 时使用的默认 adapter。真实 CLI 必须已在本地 shell 中安装并完成鉴权。

启动后做最小健康检查：

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

如果其中一个 endpoint 尚未实现，以当前 AgentHub 仓库 README 或 OpenAPI 为准，但 Local Edge 需要暴露一个能说明进程、runtime 和 workspace 状态的健康检查。

步骤 3：启动 Desktop

打开第二个终端：

cd app\desktop
pnpm install
pnpm dev

打开 Desktop 预览地址：

http://localhost:5173

Desktop 应连接到 127.0.0.1:3210 上的 Local Edge。

如果 5173 被占用，开发服务器可能自动换端口，以终端输出的本地 URL 为准，同时确认 Desktop 配置仍指向上一步的 Edge 地址。

步骤 3b：启动 Web（可选）

Web 与 Desktop 共享同一套工作台 UI。在第三个终端启动：

cd app\web
pnpm install
pnpm dev

打开 Web 预览地址：

http://localhost:5174

Web 连接 Hub Server 获取身份和协作状态，不直连 Local Edge。要让 Web 展示有意义的数据，需先启动 Hub Server 并持有有效 TokenDance ID session。

步骤 3c：Mobile Expo RN（独立路径）

Mobile 是 Expo React Native 客户端，端口 5177。从 AgentHub 仓库启动：

cd app\mobile
pnpm install
npx expo start

Mobile 仅连接 Hub Server，与 Desktop、Web 共享相同的 IM 式工作台设计。Mobile 不直接访问 Local Edge 或本地文件。完整的 transcript 渲染、diff 审查和 runtime 控制尚未在移动端可用。

步骤 4：运行第一个本地任务

创建或选择一个本地 workspace，然后发起一个小任务：

审查 README，给出最小的文档改进建议。

第一次运行建议选择低风险只读请求。确认 event stream、会话记录、diff 和结果预览可见后，再进入写入任务和审批流。

第一次运行应看到这些信号：

界面需要确认
Edge healthloopback health check 成功，并能看到 runtime/adapter 状态
Desktop 连接Desktop 显示选中的 Local Edge 在线
会话用户任务和 Agent 回复正常渲染，没有横向溢出
事件run start、消息块、工具状态和终止状态可见
产出diff、文件、preview 面板在用户批准前保持只读

如果 mock runtime 正常但真实 runtime 失败，应先按本地 CLI 或凭据问题排查。

建议把第一轮证据记录成复查项：

edge:     http://127.0.0.1:3210 health ok
desktop:  dev server url + connected edge url
runtime:  mock / claude-code / codex / opencode
workspace: 脱敏路径，不放入公开截图
run:      run id, terminal status, diff/artifact presence

这些证据可以放在私有 PR、内部 issue 或本地 handoff 里。

已知良好的 mock run

mock-first 预览应该能稳定给出下面这些公开安全信号：

{
  "ok": true,
  "service": "agenthub-edge",
  "mode": "local",
  "runtimes": [
    {
      "id": "agenthub-runner-mock",
      "state": "ready"
    }
  ]
}

创建只读任务后，事件流应至少表达这些阶段：

{"type":"run.started","runId":"run_123","agentId":"agenthub-runner-mock"}
{"type":"run.transcript_block","runId":"run_123","payload":{"text":"Reading README"}}
{"type":"run.evidence_ref","runId":"run_123","payload":{"kind":"summary"}}
{"type":"run.completed","runId":"run_123","payload":{"status":"completed"}}

Desktop 侧应看到：

区域已知良好状态
Edge selector127.0.0.1:3210 在线，runtime 显示 ready
Chat用户输入和 mock 回复稳定显示，无蓝色浏览器 focus 框
Files/Diff只读任务没有直接写入；如有候选 diff，先进入审查面
Timelinerun started、message、artifact、completed 顺序可追踪
Theme/Language切换后 mock UI 和页面语言同步，不重置 run 状态

常见失败和第一动作：

症状可能原因第一动作
Edge health 连接被拒绝Edge 未启动或端口不同看 Edge 终端输出，确认实际监听地址
Desktop 显示离线Desktop 配置仍指向旧端口更新 Desktop 的 Edge URL，不改 UI dev-server 端口
mock 有输出但真实 runtime 无输出CLI 未安装、未登录、quota 或 adapter profile 问题先在同一个 shell 跑 codex --version 或对应 CLI 自检
workspace 被拒绝workspace 不在允许列表使用允许的 workspace 或更新 Edge 本地策略
事件顺序异常adapter event schema 或 replay 问题记录 run id 和 event id，先按 adapter/schema 问题排查

步骤 5：接入 Hub 或 Web

本地链路跑通后：

  • 需要身份会话（OIDC PKCE）、项目、消息、agent 协作、同步、路由和审计时，启动 Hub Server。
  • 需要 Hub 驱动的 IM 式协作预览时，启动 Web（端口 5174）。Web 与 Desktop 共享同一套工作台 UI。
  • Mobile（端口 5177）作为独立 Expo RN 路径，用于移动端任务审查和创建。
  • Web 和 Mobile 通过 Hub 访问协作状态，不直接访问 Local Edge 或本机文件。
  • 完整 Web + Hub + Edge 路由属于集成中的链路。

建议顺序：

  1. 先让 Desktop + Local Edge + mock runtime 稳定通过。
  2. 接入一个真实 runtime adapter，确认同一套 UI 仍可用。
  3. 接入 Hub，承接 session、agent 协作、project 和 audit 边界。
  4. Hub 拥有协作状态后，再接 Web。
  5. Hub 能授权目标 Edge 后，再接远程路由或 IM 入口。

这个顺序可以避免把本地执行、产品授权和团队协作混在同一个故障里排查。

步骤 6：规划飞书/Lark 集成

飞书/Lark 是协作入口：机器人消息、事件订阅、卡片回调、H5/工作台入口和 TokenDance ID 绑定。

实现或部署飞书/Lark 流程前，请阅读 飞书/Lark 集成 和 安全边界。生产入口、异步队列、卡片 schema 和账号绑定仍在开发中。

步骤 7：Mobile 路径

Mobile（Expo React Native）是 Hub 驱动的客户端，在 iOS 和 Android 上渲染 IM 式聊天工作台。它与 Desktop、Web 共享相同的工作台设计，但是独立的开发轨道。从 app/mobile/ 目录用 npx expo start 启动，通过 Hub Server 连接。Mobile 功能尚未与 Desktop 对等。

下一步

  • 阅读 核心概念，理解术语和交付状态。
  • 阅读 系统架构，理解 Hub、Edge、Desktop、Web 和 adapter 边界。
  • 阅读 API 与事件，再开发 client 或 integration gateway。
相关文档
安装与本地环境Desktop 使用手册核心概念
在 GitHub 编辑此页