使用 Cookbook

这份 cookbook 把 AgentHub 的架构、API、Desktop、Hub/Edge 和发布文档转成任务配方。你已经知道要做什么时，从这里找最短且安全的执行路径。

配方地图

本地只读审查

新机器或新 runtime profile 的第一条任务，用这个配方。

1. 用 mock runtime 在 loopback 上启动 Local Edge。
2. 启动 Desktop，并连接到同一个 Local Edge URL。
3. 选择 allowlist 内的 workspace。
4. 发起只读审查，例如：

Review the README and suggest the smallest documentation improvement.

期望证据：

公开截图要把私有绝对路径替换成 workspace/app 这类短占位。

可审查 Diff

当 Agent 可以提出改动，但是否应用必须由人决定时，用这个配方。

1. 从干净或已明确审查的 Git 状态开始。
2. 发起聚焦任务，明确目标文件或行为。
3. 在 diff 面板渲染前，保持写入处于 proposal mode。
4. 审查 changed files、生成的 artifact 和 event timeline。
5. apply、commit 和 publish 必须作为单独动作审批。

界面需要把边界显示清楚：

不要把模型回复完成当成改动已经应用。完成只代表 run 到达 terminal state；仓库仍然由 diff review、approval、commit 和 CI 管理。

Runtime Adapter 对比

比较 Claude Code、Codex、OpenCode 或自定义 adapter 时，用这个配方。

保持任务、workspace、approval policy 和预期输出一致：

Inspect the docs navigation and report one missing consistency check. Do not edit files.

对比维度：

这些文档里的 adapter 示例是契约预览。所属 SDK 或 package 发布并版本化前，不要把占位 import path 复制进生产代码。

失败 Run 排查

任务失败或卡住时，用这个配方。

1. 记录 run id 和最后一个 event type。
2. 检查 Local Edge health 和 runtime inventory。
3. 用 mock runtime 复现。
4. 如果 mock 通过，检查真实 runtime CLI 安装、登录、quota 和 adapter profile。
5. 如果涉及 Hub/Web，先查 Hub authorization 和 target Edge presence，再考虑改 UI。
6. 如果涉及飞书/Lark，检查 gateway verification、idempotency、queue handoff、TokenDance ID binding 和 Hub task creation。

优先看的 error code：

公开 issue 只放 route class、error code、request id 或 run id 占位、最后一个安全的 event type。私有日志、原始 prompt、真实文件内容、provider key 和 callback payload 留在私有运维证据里。

团队任务准备

把本地任务推进到团队可见 workflow 前，用这个配方。

最低 readiness 清单：

• TokenDance ID login 和 Hub product session 是两层边界，并且都被正确理解。
• queue 工作前检查 project membership 和 target Edge authorization。
• 任务用 project 或 workspace target id，不用私有绝对路径。
• apply 或 publish 前能看到可审查 diff 和 artifact。
• audit 同时记录被拒绝和成功的动作。
• Web 渲染 Hub-owned state，不直接访问 Local Edge 或本地文件。

如果任何一项缺失，就保持在本地预览或受控集成测试，不要写成一般可用。

飞书/Lark 任务准备

规划 bot message、card action 和 H5/workbench 入口时，用这个配方。

耐久形态是：

1. Integration Gateway 验证并解密 provider event。
2. Gateway 快速 ack。
3. 慢任务进入异步队列。
4. TokenDance ID binding 把飞书/Lark actor 映射到产品身份。
5. Hub 在产品授权下创建或更新 AgentHub task。
6. 进度通过 card、message、H5 或 Web 返回，但不泄露完整 workspace context。

不要把 verification token、app secret、tenant token、完整 prompt、原始 provider payload 或本地绝对路径放进卡片、前端代码或公开文档。

Docs 和站点发布

新增或修改公开文档时，用这个配方。

每个新增 docs route 都需要：

公开 release note 应该说明改了什么、读者如何验证。不要写生产 web-root、SSH alias、rollback command、日志或 secret。

证据模板

私有 PR、内部 issue 或 handoff note 可用这个模板：

goal:
route_or_surface:
language:
theme:
viewport:
edge:
runtime:
run_id:
last_event:
artifact_or_diff:
checks:
result:
private_evidence_location:

公开 docs 只保留脱敏状态和稳定边界。真实本地路径、原始日志、provider output 和部署路径留在私有证据里。

相关页面

• 工作流
• 快速上手
• Desktop 使用手册
• API 与事件
• 运维 Runbook