# Channel 内 Multi-Agent 协作手册 本文档解释“现在 AgentTeam 里，一个 channel 内多 human / 多 agent / 多 machine 应该怎么协作”。 如果你要看行为规格和长期约束，请同时参考： - [specs/collaboration.md](../specs/collaboration/collaboration.md) ## 1. 先记住四条规则 ### 1. 普通消息默认静默 在 channel 主线里发一条普通消息： - 不会自动通知所有 agent - 不会把该消息悄悄塞进所有 agent 的 delivery / wake pipeline 这是当前系统最重要的降噪和降 token 规则。 ### 2. `@agent` 才是默认派工入口 如果你希望某个 agent 真正处理一件事，最直接的方式是： - 在 channel 主线里 `@agent` - 或在 thread 里 `@agent` 这会形成明确的 recipient fact，只有被命中的 agent 会进入通知边界。 ### 3. thread 用来收敛局部上下文 主 channel 适合： - 发起需求 - 同步结果 - 做高层协调 thread 适合： - 深挖一个子问题 - 跟进某个任务 - 局部 review - 避免所有 agent 和 human 都被主线噪音淹没 ### 4. task 用来表达 ownership 消息只是讨论，task 才是执行项。 推荐把“谁来做、正在做什么、做到什么状态了”尽量落到 task board，而不是长期散在聊天记录里。 ## 2. 当前协作边界怎么划分 当前模型是： - `workspace`：真实协作边界 - `channel`：协调边界 - `task`：ownership 边界 - `thread`：局部上下文边界 - `machine`：runtime 所在位置 - `agent`：实际执行 actor organization 不替代这些消息边界。 ## 3. 几种常见消息的行为 ### 3.1 普通 channel 消息 示例： ```text 这个问题我们下午一起看 ``` 行为： - 不通知 agent - 不唤醒 agent - 只保留为普通聊天消息 适合： - human 之间同步 - 不需要 agent 立即处理的上下文沉淀 ### 3.2 定向 `@agent` 示例： ```text @alpha-agent 帮我看一下登录重定向为什么会丢 state ``` 行为： - 只命中被 mention 且属于你的 agent - 其它 agent，或不属于你的 agent，保持静默 - 被命中的 agent 会以当前协作面的上下文来处理这条消息 这里的“当前协作面”很重要： - 在 channel 主线里 mention，context 是这个 channel 的主线历史 - 在 thread 里 mention，context 是这个 thread 的历史 - 在 DM 里 mention，context 是这个 DM 的历史 ### 3.3 thread reply 当一个 thread 已经和某些 agent 形成协作关系后，thread 内后续回复会继承该局部协作面。 当前实现已经支持： - thread participant inheritance - 被命中的 agent 在 thread 范围内继续收到相关跟进 这意味着你不需要在每一条 thread reply 里重复 mention 同一个 agent。 ### 3.4 `@all` 示例： ```text @all 请一起 review 这个事故复盘 ``` 行为： - 这是高成本广播 - 当前 channel 中属于你的 public/private agent membership 会进入本次 routing / diagnostics 结果 - machine / daemon 当前可连接的 agent 会立即被 wake/start；不要求 agent runtime 已经 active - machine / daemon 当前不可连接的 agent 不会在恢复在线后补跑这段离线 backlog；需要上下文时 agent 仍可主动 read_history - agent 收到后会自己判断是否该在主频道公开回复；如果已有 owner / task，通常应避免重复回执 约束： - 只能命中当前发送者在该 channel 中已有 membership 的自有 agent - 不会命中不在当前 channel 的 agent，也不会唤醒其他 owner 的 agent - 发送前 UI 会弹出二次确认 - thread 里不允许使用 ### 3.5 `@online` 示例： ```text @online 谁现在有空处理这个告警 ``` 行为： - 只面向当前 channel 中属于你的 agent；实时 wake/start 是 best-effort，只会发送到当前 daemon hub 中可连接的 machine - 可连接 machine 上的 agent 会被 wake/start；不要求 agent runtime 已经 active - machine / daemon 当前不可连接时不会通过 DB 在线快照补发；是否成功以 realtime wake status / daemon 连接状态为准 - agent 收到后会自己判断是否该公开回复；如果只是重复已有 owner / task 的状态，通常不应抢答 约束同样是： - 只能命中当前发送者在该 channel 中已有 membership、且 machine / daemon 当前可连接的自有 agent - 不会命中不在当前 channel 的 agent，也不会唤醒其他 owner 的 agent - 发送前 UI 会二次确认 - thread 里不允许使用 ## 4. `Threads` 侧栏怎么用 当前 sidebar 里的 `Threads` 是订阅中的 reply thread 聚合视图。 它适合做三件事： - 快速回到你正在跟进的 thread - 查看哪些 thread 还有未读 - 从主频道噪音里把局部上下文抽出来 当前实现中，thread subscription 会因为这些行为出现或恢复： - 你自己在 thread 里回复 - 你是 parent message 的发送者 - 有人在线程里 `@你` - 你手动 `subscribe` 你也可以对单个 thread `unsubscribe`，把它从自己的 thread inbox 里移除。 ## 5. task 应该怎么配合聊天使用 ### 5.1 在 channel board 上创建 task 行为： - 创建一个 backlog task - 不指定具体 agent - 后续默认在 task detail / task discussion 里继续补充执行细节 适合： - 先把事情落到 task board - ownership 稍后再认领 ### 5.2 创建时指定 assignee 行为： - 创建 task - 可选地把 Human 或 Agent 记录为 canonical assignee - assignee 不是 creator 时，通过创建 Activity 的 Task attention 投递 - 如果这是一个较大的请求，默认应先形成一个 root task，再在 task 内继续拆成 subtasks - create 不隐式改变 status；需要进入 `in_progress` 时另行更新 status 适合： - 你已经知道这件事希望谁先看 ### 5.3 从 thread 上下文创建 task 这是当前非常有价值的一条路径。 行为： - task 会落到父 channel 的 task board - 系统会在父 channel 写一条 system message，带上来源 thread 引用 - thread 保持安静，不插入内嵌 task card；来源关系保存在 task detail 中 - 如果创建时指定 Agent assignee，会记录 assignee，并由创建 Activity 的 Task attention 投递给对应 Agent - 之后默认在 task discussion 里继续执行，不必强制回到原 thread 才能补充任务进展 这条链路很适合把“thread 里已经讨论清楚的事情”正式转成执行项。 ## 6. Multi-Machine 协作怎么理解 workspace 内 agent 视图是 workspace-global 的，不是某一台 machine 的局部视图。 你应当这样理解： - channel 协作发生在 workspace 级 - agent 可以分布在不同 machine 上 - 是否在线、能否被立即唤醒，要看 agent 当前 runtime 状态和 machine 是否在线 所以“这个 agent 在不在线”和“这个 agent 属于哪台 machine”是两回事。 ## 7. `Delivery diagnostics` 怎么排查问题 当你怀疑某条消息没有命中预期 agent 时，优先先看消息行里的 inline `Delivery snapshot`；如果还需要更细粒度解释，再点 `Inspect delivery`。 当前 diagnostics 会告诉你至少这些事实： - 这条消息的 `routingMode` - 这条消息处理时应使用哪个 `context scope`（channel mainline / thread / DM） - 当前有哪些 targeted agent 处于 thinking / working / offline 等 runtime 状态 - 这条消息的 routing / context / wake inference 都有 server-owned explanation copy，不需要自己翻译 enum token - modal 顶部 summary 会把 `Excluded` 和真正的 `Wake blocked` 分开，避免把“没命中 agent”误读成“命中了但 wake 被拦住” - 哪些 agent 仍在当前 message scope 里，哪些只是因为 historical fanout payload/status 才继续显示 - 某个 agent 是被 `targeted` 还是 `excluded` - 为什么 excluded - 当前 runtime 推断下是会 `deliver` 还是会 `start agent` 几个最常见的结果： - `silent` - 说明这是一条普通消息，没有 agent scope - `direct_mentions` - 说明命中的是显式 `@agent` - `thread_reply` - 说明命中来自 thread participant inheritance - `channel_broadcast_all` - 说明使用了 `@all` - `channel_broadcast_online` - 说明使用了 `@online` 最常见的排查顺序是： 1. 先看 routing explanation 和 `routingMode` 对不对 2. 再看 context scope explanation，确认这条消息应该按 channel mainline / thread / DM 哪个上下文面处理 3. 再看目标 agent 的 `scope status`：它现在还在当前 message scope，还是只是保留作历史 durable fact explainability 4. 再看 agent card 里的 delivery / wake explanation 5. 最后看 `autoWakeEnabled`、realtime wake status、当前 daemon 连接状态 ## 8. 当前推荐协作模式 ### 模式一：主频道只做协调 推荐做法： - 主频道里发起问题 - 用 `@agent` 点名 - 进入 thread 深挖 - 用 task 固化 ownership 这是最稳的默认模式。 ### 模式二：thread 承接局部问题 适合： - 单个 bug - 单个 PR review - 单个事故跟进 好处： - 上下文收敛 - 减少无关 agent 被动介入 - thread participant inheritance 可以让局部协作持续成立 ### 模式三：广播只用于明确的协调升级 只有在这些场景才建议用： - `@all`：确实要让你在这个 channel 里的 agent 后续都看到 - `@online`：只想 best-effort 唤醒当前 daemon 连接可达的自有 agent 不要把它们当成日常默认发言方式。 ## 9. 常见误区 ### 误区一：agent 加进了 channel，就会自动处理所有消息 不是。 当前实现明确不是“channel 内全体 agent 默认旁听”。 ### 误区二：thread 只是 UI 展示，不影响路由 不是。 thread 是独立的局部协作面，会影响： - 上下文读取 - participant inheritance - thread inbox / subscription ### 误区三：task 只是聊天快捷语法 也不是。 task 是 task board 的结构化执行对象，会影响： - task 创建 - canonical assignee - Watch / direct mention attention - 通知边界 - source thread 引用 ## 10. 相关文档 - [../README.md](../README.md) - [specs/collaboration.md](../specs/collaboration/collaboration.md) - [tech_design.md](tech_design.md)