最后更新：2026-07-18
本文档是架构入口，只保留当前结构、边界和 owner 链接。旧长版架构说明见 history.md。
AgentHub 是 IM 形态的多 Agent 协作工作台。用户面对的是联系人、群聊、项目会话、Agent 队友、审批、Diff、Preview、产物和部署结果，而不是 runtime 下拉框。
AgentHub = shared IM workbench + local/remote Agent execution + Hub collaboration network
Desktop shared workbench
-> Desktop platform adapter
-> Local Edge Server
-> Hub Server
-> Agent Runtime adapter
-> Codex / OpenCode / Claude Code / SDK adapters
Web shared workbench
-> Web platform adapter
-> Hub Server
-> Edge routing / relay
-> Edge Server
-> Agent Runtime adapter
Mobile shared workbench (viewer / limited control)
-> Mobile platform adapter
-> Hub Server
-> Edge routing / relay (via Hub)
| 层 | 目录 | 职责 |
|---|---|---|
| Shared UI | app/shared/ |
workbench、transcript、composer、inspector、platform contracts |
| Desktop | app/desktop/ |
Tauri shell、Desktop adapter、Local Edge、本机能力 |
| Web | app/web/ |
Hub session、Web adapter、远程审批和查看 |
| Mobile | app/mobile-rn/ |
RN shell、Mobile adapter、Hub viewer surface |
| Edge | edge-server/ |
本地项目、Thread、Run lifecycle、Runtime adapter、Artifact index |
| Hub | hub-server/ |
TokenDance ID relying party、Hub session、IM、AgentTeam、同步、中继、审计 |
| API | api/ |
REST API 和 WebSocket event 契约 |
控制线 Workbench -> Platform Adapter -> Edge/Hub -> Runtime adapter -> Runtime；事件/证据/同步线的详细路径见 02-edge-server.md §事件流 与 04-frontend-data-flow.md。
- UI 不能直接启动 Agent CLI。
- Web 不能持有 TokenDance API key、本机文件系统能力或 Local Edge 直连能力；Web 只和 Hub 通信。
- Desktop renderer 不能获得 raw process execution 权限；危险能力必须经过 typed Tauri host API 和 allowlist。
- Hub 权限由 Hub-local membership/resource/action 决定，TokenDance ID 只证明身份。
- 所有来源必须 normalize 到统一 transcript contract 后再渲染。
- Mock、fixture、observed、approved-real、production 必须显式区分；stub/fixture/readiness-only 不能冒充真实登录、真实模型/API、packaged Desktop 或 release。
- Local Edge 负责本地执行、adapter 调用、runtime policy、日志和证据；Hub 负责账号、IM、同步、路由、权限、审计和远程控制面。
- Agent Profile、Agent Configuration、Agent Runtime 和 Execution Target 必须保持术语分离。
- 真实登录、真实模型消耗、部署、签名、公证、updater、release upload 都需要明确审批。
- UI 改动必须有任务和验收；禁止无关重设计、调试信息污染聊天流或绕过 shared workbench 合同。
| 概念 | 含义 | Owner |
|---|---|---|
| Agent Runtime | 能启动和解析某类 Agent CLI/SDK 的执行适配器 | Edge adapter registry |
| Agent Profile | 用户选择的 Agent 实体 | Hub profile store / Edge local profile |
| Agent Configuration | Profile 的上下文、Skill、MCP、模型、审批策略 | Edge Context Builder + Hub store |
| Execution Target | 一次 Run 的执行位置：local、remote、cloud、relay | Edge registration + Hub routing |
| Conversation | 用户可见 IM 会话：私聊、群聊、项目会话 | Hub/Edge conversation store |
| Run Session | 一次执行生命周期和事件序列 | Edge lifecycle + EventStore |
| Artifact | Agent 产物索引、预览、应用和版本 | Edge artifact index + workspace |
共享 UI 只消费 platform adapter，不直接调用 Tauri invoke、Hub client 或 Edge client。AgentHubPlatform 接口、Transcript 目标合同与消息流规则的完整定义见 04-frontend-data-flow.md（SSOT）。
| 主题 | 文档 |
|---|---|
| Hub Server | architecture/01-hub-server.md |
| Edge Server | architecture/02-edge-server.md |
| Runtime adapters | architecture/03-runtime-adapters.md |
| Frontend data flow | architecture/04-frontend-data-flow.md |
| Deployment | architecture/05-deployment.md |
| Auth and identity | architecture/06-auth-identity.md |
| Design system SSOT | architecture/07-design-system-ssot.md |
| Outbound HTTP | architecture/08-outbound-http.md |
| Architecture decisions | decisions.md |
| 变更 | 最低验收 |
|---|---|
| API/协议 | OpenAPI YAML parse + affected handler/service tests |
| Hub/Edge 逻辑 | focused Go tests; broad changes run go test ./... -short -count=1 in touched service |
| Backend performance/leak | reference/backend-performance-gates.md maps behavior gates, microbenchmarks, load smoke, and pprof/leak blockers |
| Shared transcript/UI | shared unit/contract + Desktop/Web Playwright + Visual QA；Visual QA gate 89/100（已收口 2026-07-20）· 视口 16:9 1440x810 light+dark via visual-qa-shell.mjs / visual:qa:shell（见 visual-qa-scorecard） |
| Desktop packaged claim | Tauri package/sidecar/icon/installer evidence, not Vite-only |
| Real login/model/API claim | approved-real evidence with explicit approval and no silent fallback |