安装与本地环境
本页说明 AgentHub Desktop、Local Edge、Hub Server、Web 和 runtime adapter 的本地开发环境。第一次运行 AgentHub 前，先读本页，再进入 快速上手。
范围
这里描述开发工作站，不写私有部署主机、SSH alias、provider key 或生产回滚路径。
支持的环境
AgentHub 是多产品面的系统。完整本地工作站通常需要：
| 区域 | 要求 | 作用 |
|---|---|---|
| 源码 | Git | 克隆 AgentHub 仓库并检查分支 |
| Desktop/Web | Node.js 20+ 和 pnpm | 安装前端依赖并运行本地预览 |
| Edge/Hub | Go 1.25+ | 运行本地 Edge 和 Hub 服务 |
| Runtime | 先 mock，再 Claude Code、Codex 或 OpenCode | 先验证 UI，再接真实凭据 |
| 浏览器 | Chromium、Edge 或 Chrome | 测试 Desktop/Web preview 和文档页 |
第一次设置建议使用 mock runtime。真实 runtime 会引入 CLI 登录、provider quota、shell、workspace policy 等额外失败面，应在 mock 链路健康后再接入。
克隆和初始化
克隆源码仓库并运行仓库设置脚本：
git clone https://github.com/TokenDanceLab/AgentHub.git
cd AgentHub
.\scripts\setup.ps1
如果 setup 脚本发生变化，以 AgentHub 仓库 README 为准。公开官网只描述预期结构，不复制每一条可能快速变化的私有或本地命令。
设置后检查仓库结构：
| 路径 | 作用 |
|---|---|
app/desktop | 面向本地 workspace 和 Local Edge 的 Desktop UI |
app/web | Hub-backed Web 工作台 |
edge-server | 本地执行、runtime adapter、diff、artifact、approval |
hub-server | TokenDance ID 会话、项目、设备、路由、审计 |
api | 公开契约词汇、OpenAPI 和事件参考 |
Runtime CLI 准备
Runtime adapter 包装已有编码 Agent 工具。只准备你要测试的 runtime：
| Runtime | 准备方式 |
|---|---|
| Mock | 不需要 provider credential，适合第一次验证 |
| Claude Code | 在用户 shell 里安装并完成本地鉴权 |
| Codex | 在用户 shell 里安装并完成本地鉴权 |
| OpenCode | 在用户 shell 里安装并完成本地鉴权 |
| Custom | 提供本地 adapter 实现和安全 profile |
不要将 provider key 粘到官网、浏览器 local storage、公开文档、issue 评论或飞书/Lark 卡片 payload。真实 key 应根据 runtime owner 放在本地 shell 环境或服务端 secret store。
端口和进程
推荐本地端口形状：
| 进程 | 默认形状 | 说明 |
|---|---|---|
| Local Edge | 127.0.0.1:3210 | 本地执行建议只绑定 loopback |
| Desktop dev server | Vite 分配，常见为 localhost:5173 | 以终端输出为准 |
| Web dev server | Next/Vite 分配 | Web 应调用 Hub，不直接调用 Local Edge |
| Hub Server | 仓库定义的本地端口 | 仅在测试 session、project、device、audit、routing 时需要 |
如果端口被占用，选择另一个本地端口并同步客户端配置。不要为某个操作者的本地端口去改公开文档。
校验工作站
运行真实任务前，先确认基础工具：
git --version
go version
node --version
pnpm --version
然后启动 mock Local Edge 并检查 health：
cd edge-server
go run ./cmd/agenthub-edge --addr 127.0.0.1:3210 --runner-profile agenthub-runner-mock
curl.exe http://127.0.0.1:3210/health
Edge 收敛过程中，具体 health endpoint 可能变化。稳定要求是：Local Edge 应以安全可检查的方式暴露进程状态、runtime profile 状态和 workspace policy 状态。
初次故障分流
| 现象 | 先检查 |
|---|---|
pnpm install 失败 | Node.js 主版本和 package.json 里的 package manager |
| Edge 启动失败 | Go 版本、runtime profile、端口占用 |
| Desktop 连接不上 | Desktop 是否指向同一个 loopback Edge URL |
| Mock 正常但真实 runtime 失败 | Runtime CLI 安装和本地登录 |
| 浏览器看到旧文档 | 使用 cache-busting URL，并检查线上 sitemap.xml / llms.txt |
工作站能启动 Local Edge 和 Desktop 后，继续 快速上手。