工作流
本页把 AgentHub 的概念落到真实工作场景：本地运行、团队可见审查、Hub 协作、飞书/Lark 入口、Runtime adapter 开发和发布证据。
如何阅读
建议在读完核心概念后阅读本页，再进入 API、排障或发布检查。每个工作流都会说明 owner、需要的产品面、应该留下的证据和当前状态。
工作流地图
| 工作流 | 主要用户 | 需要的产品面 | 状态 |
|---|---|---|---|
| 本地单人运行 | 个人开发者 | Desktop、Local Edge、一个 runtime adapter | 可预览 |
| 可审查 diff | 开发者和审查者 | Desktop、Local Edge、artifact/diff 面板、审批状态 | 可预览 |
| 团队协作 | 团队成员 | Hub Server、Web、project/session/device 状态 | 开发中 |
| 远程路由 | 团队或运维 | Hub Server、授权 Edge 目标、审计 | 开发中 |
| 飞书/Lark 任务 | 群聊参与者 | Integration Gateway、Hub task、TokenDance ID 绑定 | 开发中 |
| Adapter 开发 | Runtime 集成者 | Edge adapter contract、event、validation | 契约已定 |
| 公开发布 | 维护者 | docs、sitemap、llms.txt、视觉 QA、治理检查 | 持续维护 |
本地单人运行
当开发者希望用 AgentHub Desktop 在本地 workspace 上运行本地编码 Agent 时，使用这个工作流。
- 用 mock runtime 在 loopback 上启动 Local Edge。
- 启动 Desktop，并连接 Local Edge URL。
- 选择一个在 allowlist 内的 workspace。
- 先运行只读任务，再测试写入。
- 确认 transcript、event、diff/artifact 和最终状态都正常渲染。
应保留的证据：
| 证据 | 记录什么 |
|---|---|
| Edge health | loopback URL、health 结果、runtime preset |
| Desktop 连接 | UI URL、选中的 Edge URL、连接状态 |
| Workspace | allowlist 状态，公开截图不要暴露私有路径 |
| Run | run id、agent id、终止状态、artifact 是否存在 |
| 安全 | 写入前被阻止，或出现明确的审批 |
如果 mock runtime 正常，但 Claude Code、Codex 或 OpenCode 失败，应先排查本地 CLI。不要把 provider 凭据放进前端代码、公开文档、截图或浏览器存储。
可审查 Diff
当一次输出在修改仓库前必须先被检查，或者需要另一个人审查结果时，使用这个工作流。
用户可见顺序应该是：
- 用户带着明确的 workspace 和任务启动 run。
- Runtime adapter 流式输出进度 event。
- Edge 提取文件变化并生成 diff artifact。
- Desktop/Web 把 diff 展示为可审查状态，而不是直接当成已完成事实。
- 写入、apply、commit 或 publish 步骤需要明确审批。
这里的产品边界是：AgentHub 让工作可观察、可审查。实际的 Agent 工作仍由 runtime 完成，代码历史的事实来源仍是仓库。
团队协作
当一次 run 需要被团队或多个设备看到时，Hub Server 成为必需组件。
Hub Server 负责：
- TokenDance ID 认证后的用户；
- project 和成员可见性；
- session 与消息历史；
- device 或 Edge 路由目标；
- 审批、失败和敏感动作的审计事件。
Web 是 Hub-backed。它不应该直接调用 Local Edge、读取本地文件或启动本地 CLI。Desktop 可以连接 Local Edge 做本地执行；Web 应通过 Hub 和授权目标完成协作。
远程路由
Remote/Cloud Edge 仍在开发中。公开文档可以说明目标边界，但不能写成已通用可用。
远程 run 进入可发布状态前，需要证明：
| 要求 | 为什么重要 |
|---|---|
| 目标授权 | Hub 必须判断当前用户或 session 是否能使用该 Edge |
| 设备身份 | Hub 必须知道哪个 Edge 在线，并且足够可信 |
| Workspace 策略 | Edge 必须在文件访问前执行 allowlist 和本地策略 |
| 审计链路 | 审批、拒绝、路由决策和失败都要可追踪 |
| 降级状态 | Edge 离线、设备过期、workspace 被拒绝、runtime 不可用都需要稳定的错误 |
飞书/Lark 任务
飞书/Lark 是协作入口，不是 AgentHub 登录。
预期流程：
- 消息或卡片动作进入 Integration Gateway。
- Gateway 校验飞书/Lark 事件并快速确认。
- 耗时 AgentHub 工作异步入队。
- Gateway 把飞书用户解析到 TokenDance ID 绑定。
- Hub Server 在产品本地授权下创建或更新 AgentHub task。
- 进度通过卡片、消息、H5/工作台或 Web session 回传。
Verification token、app secret、encrypt key、tenant token 和 OAuth refresh token 应保留在服务端或 TokenDance ID 内。不要存进 Desktop 或 Web 客户端。
Adapter 开发
当要接入新 runtime，或完善 Claude Code、Codex、OpenCode、自定义 Agent adapter 时，使用这个工作流。
Adapter 应稳定产出这些 AgentHub event：
- run started、completed、failed、cancelled；
- model text 和 message delta；
- tool call 和 tool result；
- file change、diff、artifact 和 preview；
- permission 或 user-input request；
- runtime unavailable、timeout 和 schema validation failure。
Adapter contract 已成型，但公开 SDK 包名和 import path 在正式发布与版本化前应保持保守。
公开发布
当改动产品站、docs、SEO 文件、公开截图或发布 claims 时，使用这个工作流。
最小发布证据：
| 门禁 | 必须证明 |
|---|---|
| 文档一致性 | zh/en 页面和导航覆盖同一组 claims |
| 公开发现 | robots.txt、sitemap.xml、llms.txt 包含改动路由 |
| 搜索 | docs search index 包含新增页面和关键术语 |
| 安全 | 公开文件里没有 secret、私有路径、回滚命令或真实 token |
| 视觉 QA | 桌面和移动端页面无溢出、无旧视觉语言 |
| 治理 | workspace root public surface、i18n、design、freshness、governance 检查通过，或只剩已接受债务的 warning |
状态词
公开文档里统一使用这些状态词：
| 状态 | 含义 |
|---|---|
| 已上线 | 公开页面或 endpoint 已部署并通过 smoke test |
| 可预览 | 本地或公开预览链路存在，并且可以验证 |
| 契约已定 | 接口方向已文档化，但不承诺公开 SDK 稳定 |
| 进行中 | 已有实现，但还不是可发布能力 |
| 开发中 | 正在规划或开发，不能描述为通用可用 |