系统架构
AgentHub 的架构说起来简单：把 AI Agent 的运行过程和团队协作流程，变成聊天界面里看得见、审得了、可回溯的事件流。
你在群聊里发一条消息给 Agent，消息经过 Desktop 或 Web，到达 Hub 或 Edge 服务层，服务层调度真正的 AI 执行引擎跑任务。引擎的输出再逆流而上，变成聊天里的结构化消息、文件对比和产出物——你的团队全程可见。
NOTE
本页描述目标架构和当前组件边界。Desktop、Web、Mobile 共享同一套工作台界面。Hub 和 Edge 具备本地开发链路。飞书/Lark 生产入口、Remote/Cloud Edge、完整的端到端路由仍在开发中。
大图：一次请求走什么路径
在深入五层结构之前，先看端到端的数据流：
sequenceDiagram
participant U as 用户
participant C as 客户端（Desktop/Web/Mobile）
participant H as Hub Server
participant E as Local Edge
participant AD as 执行引擎适配器
participant R as 引擎 CLI
U->>C: 在群聊里发消息给 Agent
C->>E: 创建任务（Desktop 直连，或 Web/Mobile 经 Hub）
E->>E: 检查工作区白名单和审批策略
E->>AD: 从注册表启动适配器
AD->>R: 调用 Claude Code / Codex / OpenCode
R-->>AD: 输出消息、工具调用、文件改动、产出物
AD-->>E: 将事件归一并写入存储
E-->>C: 流式推送结构化消息和产出引用
C-->>H: 同步会话、团队状态、审计记录（Hub 路径时）
H-->>C: 返回协作状态和路由策略5 层架构
AgentHub 从用户界面到引擎 CLI 分为五层，每一层只干自己该干的事：
| 层 | 组件 | 职责 |
|---|---|---|
| Shared UI | 共享工作台模块 | Desktop、Web、Mobile 共用的界面：Agent 消息流、文件变更面板、审批控件 |
| Platform Adapter | Desktop（Tauri 2）、Web、Mobile（Expo RN） | 平台特定外壳：窗口管理、通知、深度链接、原生菜单 |
| Edge / Hub | Edge Server（Go）、Hub Server（Go） | 本地执行和引擎生命周期（Edge）；账号、会话、项目、消息、团队协作（Hub） |
| Agent Adapter | Edge 内的适配器注册表 | Claude Code、Codex、OpenCode 适配器实例，管理进程生命周期和事件记录 |
| Runtime CLI | Claude Code CLI、Codex CLI、OpenCode CLI | 实际 AI 执行进程，由适配器调用 |
三个客户端渲染同一套工作台界面。Platform Adapter 层处理各自平台的特殊需求，让共享界面保持干净。
组件拓扑
flowchart TB
TDID["TokenDance ID\n登录 / 账号绑定"] --> HUB["Hub Server\nGo: 认证 / 会话 / 项目 / 消息 / 团队协作"]
WEB["AgentHub Web"] --> HUB
DESK["AgentHub Desktop\nTauri 2"] --> EDGE["Local Edge\nGo: 工作区 / 任务 / 适配器 / 事件存储"]
MOBILE["AgentHub Mobile\nExpo RN"] --> HUB
DESK --> HUB
HUB --> ROUTE["路由策略\n权限 / 目标选择"]
ROUTE --> EDGE
FEISHU["飞书 / Lark\n机器人消息 / 事件订阅 / 卡片回调"] --> IGW["集成网关\nwebhook / 异步队列"]
IGW --> HUB
subgraph SHARED["共享工作台界面"]
TB["Agent 消息流"]
ER["产出物引用"]
DIFF["文件对比面板"]
APPR["审批控件"]
end
subgraph EDGEL["Edge Server"]
EDGE --> RUNS["任务生命周期管理"]
EDGE --> WS["工作区白名单"]
EDGE --> ART["diff / 文件 / 预览产出"]
EDGE --> REG["适配器注册表"]
EDGE --> ES["事件存储"]
end
subgraph ADAPTERS["执行引擎适配层"]
CC["Claude Code"]
CX["Codex"]
OC["OpenCode"]
end
REG --> CC
REG --> CX
REG --> OC
DESK -.-> SHARED
WEB -.-> SHARED
MOBILE -.-> SHARED核心组件
Desktop（Tauri 2 桌面应用）
Desktop 是 Tauri 2 原生客户端，专为本地执行设计。它渲染共享工作台界面，提供 IM 式群聊体验：Agent 的每一条输出都是聊天里的结构化消息，改动的文件和产出物在审查面板里一目了然。任何涉及写入文件、执行命令或连接外部的操作，都需要你明确审批。团队协作时，Desktop 同步会话和审计状态到 Hub。
Web（浏览器端）
Web 是浏览器端的团队协作入口。它和 Desktop 共用同一套工作台界面，视觉和交互完全一致。Web 连 Hub 获取身份、项目上下文、团队状态和消息路由。它不启动本机命令行进程，文件执行由 Edge 负责。
Mobile（移动端 App）
Mobile 是 Expo React Native 客户端，面向 iOS 和 Android。它提供 IM 式聊天工作台，用于移动端审查 Agent 产出和创建新任务。Mobile 通过 Hub 获取协作状态，不持有本机 workspace 访问权。
共享工作台界面
三端共用的工作台是 AgentHub 体验的核心。它包含两个关键抽象：
- 结构化 Agent 消息：Agent 在聊天流中的输出以统一格式呈现，支持代码块、文件引用、工具调用等富内容。
- 产出物引用：Agent 改动的文件、生成的 diff、产出的内容，在所有客户端的审查面板中统一展示。
Hub Server
Hub 是产品协作和权限的核心。它消费 TokenDance ID 登录结果，签发 AgentHub 产品会话，管理项目、消息、团队和审计记录。Hub 决定哪些客户端可以把任务路由到哪个 Edge。Hub 不持有本地 provider key。
Local Edge
Local Edge 贴近文件系统和进程边界。它管理：工作区白名单、任务生命周期、适配器注册表（已注册执行引擎的索引）、事件存储（归一化后的任务事件）、产出物（diff、文件、预览）。本地事实流式推送给 Desktop，授权后同步到 Hub。
适配器注册表
Edge Server 维护一个适配器注册表，把执行引擎标识映射到具体适配器实现。每个适配器负责：管理对应引擎 CLI 的进程生命周期、把引擎输出归一化为结构化消息和产出引用、写入事件存储。当前已注册适配器：Claude Code、Codex、OpenCode。
集成网关
集成网关是飞书/Lark 等外部入口的服务端边界。它负责：webhook challenge 校验、签名验证、加密解密、卡片回调快速确认、耗时任务异步入队、向 Hub 转发精简后的 payload。
职责归属
判断一个功能或改动应该放在哪里，参考这张表：
| 关注点 | 归属于 |
|---|---|
| 产品登录和账号身份 | TokenDance ID + Hub Server（OIDC PKCE） |
| 产品会话、项目成员、路由策略 | Hub Server |
| 本地工作区白名单和进程执行 | Local Edge |
| 本地执行和审批 UI | AgentHub Desktop（Tauri 2） |
| 共享工作台界面渲染 | 共享工作台模块 |
| 团队审查、历史记录和路由状态 | Hub-backed Web / Mobile |
| 引擎进程生命周期和事件归一化 | Edge 内适配器注册表 |
| 飞书/Lark webhook 校验和异步队列 | 集成网关 |
| 公开产品文案、文档、SEO 和视觉 QA | AgentHub Home |
数据归属
AgentHub 的数据遵循”谁执行、谁持有”的原则：
| 数据 | 主要归属 | 共享规则 |
|---|---|---|
| TokenDance ID 身份和登录凭证 | TokenDance ID | Hub 消费已验证凭据；产品不存 provider OAuth secret |
| 产品会话、项目、角色、审计 | Hub Server | Web/Desktop/Mobile 只接收授权后的视图 |
| 工作区路径、文件预览、diff、产出物 | Local Edge | 公开截图和文档使用脱敏或相对路径示例 |
| 引擎 CLI 登录状态和 provider key | 本机或服务端凭据存储 | 不进入浏览器存储、文档、IM payload 或静态打包 |
| 任务事件流 | Edge 事件存储，授权后同步 Hub | 未知事件字段保持可版本化，客户端安全忽略 |
| IM 事件和卡片动作 | 集成网关 + Hub | 完整提示词、凭据和本地路径不进入卡片 payload |
运行模式
AgentHub 支持多种运行模式，每种模式的验证标准不同：
| 模式 | 组件 | 当前表述 | 表述成立需要的证据 |
|---|---|---|---|
| 本地预览 | Desktop + Local Edge + mock engine | 本地链路可预览 | Edge 健康、Desktop 连接、结构化消息和产出引用正常 |
| 真实本地引擎 | Desktop + Local Edge + Claude Code/Codex/OpenCode | 引擎适配链路可本地测试 | CLI 已安装鉴权、适配器输出事件、失败状态可见 |
| Hub 团队协作 | Hub + Web/Mobile + Desktop/Edge 同步 | IM 式团队协作推进中 | PKCE 会话、团队成员、任务/运行同步、审计记录 |
| IM 入口 | 集成网关 + Hub + 飞书/Lark | 协作入口开发中 | 签名校验、回调确认、异步队列、账号绑定 |
| Remote/Cloud Edge | Hub + 远端 Edge + 路由/中继 | 证据完成前保持开发中 | 设备身份、目标授权、工作区策略、降级状态、审计 |
设计原则
- IM 式协作：AI Agent 以队友身份加入群聊。发消息就是派任务，聊天即工作台。
- 共享工作台：Desktop、Web、Mobile 渲染同一套界面，切设备不掉上下文。
- 本地执行优先：本地 workspace 和进程优先由 Desktop + Local Edge 承接。
- Hub 管协作：身份、项目、团队、路由和审计统一由 Hub 管理。
- 松耦合：各组件通过明确接口连接，可独立替换。
- 全程可观测：Agent 的每一步操作、工具调用和决策都可追踪。
- 优雅降级：单个 Agent 失败不影响其他 Agent 继续推进。
- 引擎无关：模型后端通过 Provider 抽象统一接入，不绑定特定厂商。