系统架构
AgentHub 采用模块化、事件驱动架构，让 AI 智能体成为本地、Web、Hub、Edge 和集成入口中的一等协作者。
交付状态
本页描述目标架构和当前组件边界。Desktop、Local Edge、Hub、Web 与 runtime adapter 的本地开发链路已经可用；飞书/Lark 生产入口、Remote/Cloud Edge、完整 Web + Hub + Edge 路由仍在开发中。
目标拓扑
数据流
核心组件
Desktop
Desktop 是本地执行体验的主要入口，负责：
- 选择本地 workspace 和 Local Edge。
- 渲染多 Agent 聊天、运行进度、diff、文件和 preview。
- 在写入、shell、外部连接等动作前承接用户审批。
- 在需要团队协作时，把 session、device 和 audit 信息同步到 Hub。
Hub Server
Hub 是产品协作和权限边界，负责：
- 消费 TokenDance ID OIDC 登录结果并签发 AgentHub 产品 session。
- 管理 project、member、device、target 和 audit。
- 决定 Web、Desktop 或集成入口能否把任务路由到某个 Edge。
- 存储团队可见的协作状态，但不直接持有本地 provider key。
Web
Web 是 Hub-backed 协作界面，负责：
- 展示 Hub session、project 和 agent task。
- 通过 Hub 查看运行状态、审查结果和团队协作上下文。
- 不绕过 Hub 直接访问 Local Edge 或本机文件。
Local Edge
Local Edge 靠近文件系统和进程边界，负责：
- workspace allowlist、run lifecycle、runtime adapter 启动与取消。
- 产出 normalized event、diff、artifact 和 file preview。
- 执行本地审批桥和最小权限策略。
- 把本地事实流式返回 Desktop，并在授权后同步到 Hub。
Agent Runtime Adapter
每种 runtime 由 Edge Server 内的 runtime adapter 承载。Runtime adapter 不是用户管理的 Agent Profile，而是 Profile 可以绑定的执行引擎：
- Claude Code adapter：管理 Claude Code CLI 子进程和结构化输出解析。
- Codex adapter：对接 OpenAI Codex CLI / event stream，执行代码生成与分析。
- OpenCode adapter：通过统一 runtime 协议支持 OpenCode 的 provider/model 路由。
- 自定义 runtime adapter：基于 adapter SDK 构建，适配团队自研引擎。
Integration Gateway
Integration Gateway 是飞书/Lark 等入口的服务端边界，负责：
- 处理 webhook challenge、签名验证和加密解密。
- 在 3 秒内确认
card.action.trigger等回调。 - 把耗时 AgentHub 工作异步入队，再交给 Hub 生成 task。
- 只携带必要上下文，避免把 secret、workspace 路径或完整模型输出放进卡片 payload。
职责矩阵
判断一个功能、bug fix 或文档应该放在哪里时，优先使用这张表。
| 关注点 | 归属面 | 不能由谁承担 |
|---|---|---|
| 产品登录和账号身份 | TokenDance ID + Hub Server | Desktop、Web 静态客户端、飞书/Lark OAuth 直连 |
| 产品 session、项目成员、路由策略 | Hub Server | Local Edge、runtime adapter、官网 |
| 本地 workspace allowlist 和进程执行 | Local Edge | Web 浏览器、Hub-only 页面、IM 卡片 payload |
| 本地执行和审批 UI | AgentHub Desktop | Hub Server、官网 demo |
| 团队可见审查、历史和路由状态 | Hub-backed Web | 浏览器直连 Edge |
| runtime 进程解析和事件归一化 | Edge 内的 Runtime adapter | Agent Profile 元数据 |
| 飞书/Lark webhook 校验和队列 | Integration Gateway | Hub UI、Desktop、公开前端 |
| 公开产品文案、docs、SEO 和视觉 QA | AgentHub Home | 私有 server state 或线上运维清单 |
如果一个改动看起来需要两个 owner，先把职责拆开再实现。例如，Web 可以通过 Hub 请求一个 task，但文件系统访问和 runtime 进程执行仍由 Edge 负责；飞书/Lark 可以创建 Hub task，但不能变成第二套登录权威。
数据归属
AgentHub 的数据尽量留在能够执行对应边界的组件附近。
| 数据 | 主要归属 | 共享规则 |
|---|---|---|
| TokenDance ID subject、OIDC claim、账号绑定 | TokenDance ID | Hub 消费已验证 claim；产品不存 provider OAuth secret |
| 产品 session、组织、项目、角色、审计 | Hub Server | Web/Desktop 只接收授权后的视图 |
| Workspace path、file preview、diff、artifact、terminal state | Local Edge | 公开截图和 docs 使用脱敏或相对示例 |
| Runtime CLI 登录状态和 provider key | 本机或服务端 secret store | 不进入浏览器 storage、docs、IM payload 或静态 bundle |
| Run event stream | Edge 优先，授权后同步 Hub | 未知 event 字段保持可版本化，客户端应安全忽略 |
| IM event id、tenant/user 绑定摘要、card action id | Integration Gateway + Hub | 完整 prompt、secret、本地路径和 raw model output 不放进卡片 |
这也是文档归属模型：公开 docs 描述行为和边界，私有 server state 记录 live host path、backup、rollback command 和 credential。
运行模式
AgentHub 支持多种运行模式，不同模式需要不同的证据。
| 模式 | 组件 | 合适表述 | 写成公开口径前需要的证据 |
|---|---|---|---|
| 本地预览 | Desktop + Local Edge + mock runtime | 本地链路可预览 | Edge health、Desktop 连接、run event、截图或 artifact |
| 真实本地 runtime | Desktop + Local Edge + Claude Code/Codex/OpenCode | runtime adapter 链路可本地测试 | CLI 已安装/鉴权、adapter 产出 event、失败状态可见 |
| Hub-backed 协作 | Hub + Web + Desktop/Edge sync | 团队工作流进行中 | TokenDance ID session、项目成员、task/run sync、audit record |
| IM 入口 | Integration Gateway + Hub + 飞书/Lark | 协作入口开发中 | 签名校验、快速 callback ack、异步队列、绑定状态 |
| Remote/Cloud Edge | Hub + target Edge + routing/relay | 证据完成前保持开发中 | device identity、target authorization、workspace policy、degraded state、audit |
设计原则
- Desktop-first local execution：本地 workspace 和进程边界优先由 Desktop + Local Edge 承接。
- Hub-owned collaboration：身份、项目、设备、路由和审计由 Hub 管理。
- 松耦合：Web、Desktop、Hub、Edge、集成入口和 runtime adapter 通过明确接口连接，可独立替换。
- 可观测优先：每个智能体动作、API 调用和决策点都应可追踪。
- 优雅降级：单个智能体失败时，不影响其他无关工作继续推进。
- 提供商无关：模型后端通过 Provider 抽象统一接入。