Hub 与 Edge
AgentHub 把协作和执行分开。Hub 管身份、项目、路由和审计；Edge 管本地 workspace、run、runtime adapter、diff、artifact 和审批。
职责拆分
| 能力 | Hub Server | Edge Server |
|---|---|---|
| TokenDance ID 登录 | 消费 OIDC 结果并创建产品 session | 不负责用户登录 |
| 项目成员 | 管 project、member、role 和 route policy | 接收授权后的 target 决策 |
| 设备与 target 路由 | 授权 Desktop/Web/集成入口能否触达某个 Edge | 暴露 health、target 和 workspace 能力 |
| Workspace 访问 | 存策略和审计状态 | 在文件系统旁执行 allowlist |
| Runtime 执行 | 记录 task 和 run metadata | 启动、取消和观测 runtime adapter |
| 文件、diff、artifact | 保存可共享审计/审查事实 | 产生本地事实和审批事件 |
| Secret | 服务端保存产品签名和集成 secret | 从受控本地环境使用 local/runtime secret |
Local Edge 模式
Local Edge 是默认的开发和个人执行模式。它运行在 loopback，靠近 workspace，只通过 Desktop 配置的本地 URL 访问。
Local Edge 负责执行：
- workspace allowlist；
- 写入、shell、网络和发布动作的审批策略；
- runtime adapter 可用性检查；
- run lifecycle 和 cancellation；
- 本地 artifact 与 diff 边界；
- 面向 Desktop 的安全事件流。
Hub-backed Web 模式
Web 是 Hub-backed 协作面。它可以展示 project、task、session history、review state 和 audit facts，但不直接启动本地 CLI 进程或读取本地文件。
正确链路是：
- 用户通过 TokenDance ID 登录。
- Hub 创建 AgentHub 产品 session。
- Web 向 Hub 请求 project 和 task 状态。
- 任务需要执行时，Hub 授权目标 Edge。
- Edge 通过授权路由返回 event 和 artifact。
- Hub 保存可审查、可审计摘要。
Remote 与 Cloud Edge
Remote/Cloud Edge 仍在开发中。在以下事实被证明前，不要写成通用可用：
| 要求 | 需要证明 |
|---|---|
| Device identity | Edge 注册、key 轮换和 revoke 路径 |
| Target authorization | Hub policy 决定谁能路由到 Edge |
| Workspace policy | allowlist 和 tenant/project 边界被执行 |
| Relay behavior | 失败模式明确且可观测 |
| Audit trail | user、project、run、target、approval、artifact 状态被记录 |
| Degraded state | Web/Desktop 清楚显示 unavailable、unauthorized、timed out、cancelled |
集成入口
飞书/Lark、未来 IM 入口和自动化触发应通过 Integration Gateway 或 Hub API 进入，不直接进入 Edge。
集成入口必须：
- 校验 webhook signature 或 app credential；
- 解析 TokenDance ID 绑定；
- 耗时任务异步创建 Hub task；
- 避免把 provider secret 或 workspace 路径放进卡片；
- 只在 Hub 授权后路由到 Edge。
Event 契约
Edge 把 runtime 输出归一化为稳定的产品事件。最小可用分组：
| 分组 | 示例 |
|---|---|
| Run lifecycle | run.started、run.completed、run.failed、run.cancelled |
| Messages | run.message.delta、run.message.completed |
| Tools | run.tool.call、run.tool.result、run.tool.failed |
| Review | run.diff.ready、run.artifact.ready、run.approval.requested、run.approval.resolved |
| Runtime state | runtime.unavailable、runtime.timeout、schema.validation_failed |
Event 携带足够的 ID 来关联 user、project、run、agent、sequence、timestamp 和版本化 payload，但不泄漏本地 secret。
边界排障
工作流失败时，先判断 owner，再改代码：
| 症状 | 可能归属 |
|---|---|
| 登录成功但 API unauthorized | Hub session 或产品授权 |
| Web 读不到本地文件 | 预期边界；使用 Desktop + Edge |
| Desktop 连不上 | Local Edge health、端口或 URL |
| Runtime 没有事件 | Edge adapter、本地 CLI、provider credential 或 event schema |
| 飞书卡片超时 | Integration Gateway ack/queue 链路 |
| 远程 target 不可用 | Hub route policy、Edge registration 或 relay state |