核心概念

本页定义 AgentHub 文档里反复出现的术语，并明确哪些能力已经可预览、哪些仍在开发。

产品形态

AgentHub 不是单一网页，也不是 CLI 外壳。它由多个协作面组成：

形态	职责	当前状态
AgentHub Desktop	本地工作台，连接 Local Edge，展示聊天、diff、文件、preview 和运行状态	可本地预览
AgentHub Web	Hub 驱动的协作工作台，面向多端和团队协作	可预览，生产接线进行中
Hub Server	管理身份会话、项目、设备、IM 入口、同步、审计和权限	可本地开发
Edge Server	管理 workspace、run lifecycle、runtime adapter、artifact、diff、preview event	可本地开发
Feishu/Lark App	机器人、事件、卡片、H5/工作台入口	开发中

Agent Profile 与 Runtime Adapter

Agent Profile 是用户和团队能看到、能选择的 Agent 配置，例如“审查 Agent”“文档 Agent”“Codex 实现 Agent”。Profile 描述名称、用途、权限、默认模型、可用 workspace 和执行策略。

Runtime Adapter 是 Edge Server 内部承载真实执行引擎的组件，例如 Claude Code adapter、Codex adapter、OpenCode adapter。一个 Profile 可以绑定一个 Runtime adapter，但二者并非同一概念。

这个区分很重要：团队协作层关心 Profile，执行层关心 Runtime adapter。

Hub 与 Edge

Hub 和 Edge 的边界如下：

Hub Server 负责账号、团队、项目、设备、IM 入口、跨端同步、权限和审计。
Edge Server 负责实际 workspace、进程生命周期、文件读写、runtime adapter、diff、artifact 和 preview。
Desktop 默认连接 Local Edge，本地执行不依赖 Hub 登录。
Web 通过 Hub 协作，不直接启动本机 CLI，也不绕过 Hub 直连 Local Edge。

Session、Task、Run、Event

Session：一次协作上下文，可以来自 Desktop、Web 或 IM 会话。
Task：用户希望 Agent 完成的工作，例如“审查这个 PR”“整理文档”“修复测试”。
Run：某个 Agent Profile 对 Task 的一次执行实例。
Event：Run 生命周期中的结构化事件，例如 run.started、run.message.delta、run.tool.call、run.diff.ready、run.approval.requested、run.completed。

这些对象用于将 Agent 执行从“终端里的一段输出”变成团队可检索、可审计、可回放的工作记录。

一次请求怎么流动

最小链路从 Desktop 开始：

Text

User -> AgentHub Desktop -> Local Edge -> Runtime Adapter -> Runtime CLI
                         <- structured events / diff / artifacts <-

团队链路会多出 Hub：

Text

User/Web/IM -> Hub Server -> authorized Edge target -> Runtime Adapter
                    |                |
                    |                -> workspace policy / approvals / artifacts
                    -> session / project / device / audit

这两个链路不能混用。Desktop 本地预览可以直接连 Local Edge；Web 和 IM 入口必须经过 Hub 的身份、项目、目标授权和审计。公开文档里如果出现“Web 执行任务”，应该同时说明它是 Hub-backed，而不是浏览器直连本机 CLI。

谁拥有哪类数据

数据	Owner	公开文档里的规则
TokenDance ID subject、profile、session claim	TokenDance ID + Hub relying party	只说明身份边界，不发布真实 token 或 callback payload
Project、device、task、audit	Hub Server	可写资源模型和错误码，不写私有数据库或日志路径
Workspace、file preview、diff、artifact	Edge Server	只使用相对路径和合成示例，避免真实本机绝对路径
Runtime stdout/stderr/raw JSONL	Runtime adapter	默认转换成结构化 event；raw 附件必须脱敏
Feishu/Lark event 和 card action	Integration Gateway + Hub	payload 只放紧凑 id/action，不放完整 prompt、secret 或私有文件

这个所有权划分能避免将“产品登录”“模型 API key”“本地 CLI 鉴权”“飞书事件”混成一个凭据面。

例子：文档审查任务

一个低风险任务可以这样理解：

用户在 Desktop 选择 allowlisted workspace。
用户选择 docs-agent 这类 Agent Profile。
Desktop 请求 Local Edge 创建 read-only run。
Edge 用 mock、Codex、Claude Code 或 OpenCode adapter 启动 runtime。
Adapter 把 message、tool、file-read、diff-ready 和 final-result 转成结构化 event。
Desktop 渲染 transcript、文件列表、diff 和 artifact。
如果任务要写文件、运行 shell、commit 或 publish，进入 approval gate。

这个例子只说明本地预览链路。团队 Web、飞书/Lark 或 Remote Edge 需要额外的 Hub session、target authorization、audit 和异步队列证据。

当前交付状态

已可预览或本地验证：

Desktop -> Local Edge -> Runtime adapter 的本地链路。
Claude Code、Codex、OpenCode preset 的 Edge 执行路径。
Hub Server 的 OIDC code exchange、Hub session 和本地开发链路。
Web 工作台的 Hub-only 预览姿态。

开发中：

Feishu/Lark 生产事件入口、卡片动作、H5/工作台和 TokenDance ID 绑定闭环。
Remote/Cloud Edge、设备证明、relay/provisioning 和 workspace allowlist。
Contacts、Docs、Tasks、Projects、Settings 等数据库驱动界面。
完整 Web + Hub + Edge 路由的生产级 E2E 验证。

不要混淆的边界

TokenDance ID 是身份权威；AgentHub 不直接实现 GitHub、Google 或飞书第三方登录。
飞书/Lark 是协作入口，不是产品登录系统。
TokenDance API key 用于模型 API 调用，不是 AgentHub Web/Desktop 登录凭据。
Runtime adapter 尚非公开稳定 SDK；公开包和第三方提交流程仍在整理。