AgentHub
文档

快速上手

本指南先跑通本地预览链路：AgentHub Desktop -> Local Edge -> Runtime Adapter。它是测试 Hub、Web 或飞书/Lark 集成之前最小且最稳的路径。

预览范围

本页覆盖本地开发和预览。飞书/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

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

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

克隆后先确认自己在正确的子系统里工作：

路径作用本指南是否需要
app/desktopDesktop UI，本地执行的主要入口需要
edge-serverLocal Edge，负责 workspace、run、adapter 和 artifact需要
hub-serverHub API、会话、项目、设备、审计和远程路由可选
app/webHub-backed Web 协作界面可选
api/OpenAPI、event vocabulary 和协议约定阅读

步骤 2：启动 Local Edge

在 AgentHub 仓库中运行：

powershell
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：

powershell
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 中安装并完成鉴权。

启动后先做最小健康检查：

powershell
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 allowlist 状态的健康检查。

步骤 3：启动 Desktop

打开第二个终端：

powershell
cd app\desktop
pnpm install
pnpm dev

打开 Desktop 预览地址：

Text
http://localhost:5173

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

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

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

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

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

第一次运行建议选择低风险只读请求。确认 event stream、transcript、diff 和 artifact preview 可见后，再进入写入任务和审批流。

第一次运行应看到这些证据：

界面需要确认
Edge healthloopback health check 成功，并能看到 runtime/adapter 状态
Desktop 连接Desktop 显示选中的 Local Edge 在线
Transcript用户任务和 Agent 回复正常渲染，没有横向溢出
Eventsrun start、message delta 或 text block、tool 状态和终止状态可见
Artifactsdiff/file/preview 面板在用户批准前保持只读

如果 mock runtime 正常但真实 runtime 失败，应先按本地 CLI 或凭据问题排查。不要为了让预览通过而将 provider key 写进网站、文档或浏览器存储。

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

Text
edge:     http://127.0.0.1:3210 health ok
desktop:  dev server url + connected edge url
runtime:  mock / claude-code / codex / opencode
workspace: allowlisted path, not copied into public screenshots
run:      run id, terminal status, diff/artifact presence

这些证据可以放在私有 PR、内部 issue 或本地 handoff 里；公开官网和公开文档只保留脱敏后的状态说明。

已知良好的 mock run

mock-first 预览应该能稳定给出下面这些公开安全信号。具体字段以 AgentHub 仓库当前实现为准，但语义应保持一致：

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

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

JSON
{"type":"run.started","runId":"run_123","agentId":"agenthub-runner-mock"}
{"type":"run.message.delta","runId":"run_123","payload":{"text":"Reading README"}}
{"type":"run.artifact.ready","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 不在 allowlist使用 allowlisted workspace 或更新 Edge 本地策略
事件顺序异常adapter event schema 或 replay 问题记录 run id 和 event id，先按 adapter/schema 问题排查

步骤 5：接入 Hub 或 Web

本地链路跑通后：

  • 需要身份会话、项目、设备、同步、路由和审计时，再启动 Hub Server。
  • 需要 Hub-backed 协作预览时，再启动 Web。
  • Web 不能绕过 Hub 直接访问 Local Edge 或本机文件。
  • 完整 Web + Hub + Edge 路由仍属于集成中的链路。

建议顺序：

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

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

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

飞书/Lark 是协作入口：机器人事件、卡片动作、H5/工作台入口和 TokenDance ID 绑定。它不是产品登录系统。

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

下一步

  • 阅读 核心概念，理解术语和交付状态。
  • 阅读 系统架构，理解 Hub、Edge、Desktop、Web 和 adapter 边界。
  • 阅读 API 与事件，再开发 client 或 integration gateway。