主题
多入口与 Channel 路由方案
1. 方案摘要
本方案把 Web、IM、OpenAPI 和 Schedule 视为不同协议适配器，而不是四套独立业务链路。所有入口最终形成统一任务上下文；差异只保留在身份解析、绑定规则、流式交付和回调协议中。
2. 设计目标与非目标
设计目标
- 统一入口到 Agent 执行的任务语义。
- 隔离 Web 的实时 SSE 与 IM/OpenAPI 的回调交付。
- 让 Gateway / Runtime 拆分不改变入口行为。
非目标
- 不让所有入口共享同一套外部鉴权协议。
- 不让 Web 复用 IM bind 规则。
- 不在本方案中定义各 IM 平台的卡片细节。
3. 架构范围与视图
Web、IM、OpenAPI 与 Schedule 如何进入统一执行链路，并按入口语义返回结果？
同时展示组合部署与 Gateway / Runtime 分离部署，不展开副本心跳和恢复。
图中绿色实线表示当前能力，紫色虚线表示规划或待完善能力。图片用于建立空间关系，本文正文定义方案语义、边界和落地规则。
4. 组件与责任边界
| 组件 | 责任 |
|---|---|
| Web | 内置 Web Channel 由 URL / 参数直接指定 Agent，不读取 IM bind。 |
| IM | 适配器把平台事件归一化为 InboundMessage，经 bind 查找 Agent。 |
| OpenAPI | 外部鉴权和租户解析后创建 headless 任务。 |
| Schedule | Gateway 或组合角色负责调度触发。 |
| Dispatcher | 统一执行内容过滤、去重、触发和 Agent 预检。 |
| RuntimeClient | gateway 角色将非 Web 任务通过内部 HTTP 派发给 Runtime。 |
| 返回路径 | Web 使用本地 SSE；IM 和 OpenAPI 使用 Runtime 事件回调到 Gateway。 |
组件之间只通过明确的输入、输出和生命周期契约协作。上层可以编排下层能力，但不能绕过下层的权限、租户和状态边界直接读写内部对象。
5. 核心设计决策
- Web 通过 URL/参数直接确定 Agent，保持本地 SSE。
- IM 通过适配器、身份绑定和去重形成 InboundMessage。
- Gateway 负责非 Web 入口的调度和内部派发，Runtime 负责执行与事件生成。
这些决策共同保证：入口可以替换、执行可以迁移、状态可以恢复，而不会改变用户可见的任务和会话语义。
6. 关键流程与时序
主流程
- 入口适配并解析身份租户
- 形成统一任务或 InboundMessage
- 根据运行拓扑本地执行或内部派发
- Runtime 执行 Agent
- 按入口返回 SSE、IM 回复或回调
流程解释
流程中的每一步都应产生可追踪的上下文：租户、Agent、Chat、Task、运行副本和结果引用。过程事件用于向用户反馈进度，终态写入和结果归档必须在事实源更新后再对外确认。
7. 数据、一致性与状态管理
- 入口解析得到的租户、Agent、Chat 和 route key 在任务生命周期内保持稳定。
- IM 去重和 Schedule 触发记录必须持久化。
- 回调事件是过程通知，最终消息和任务状态由 Runtime 持久化。
当前专题的关键约束
- Web 不进入 IM bind 表。
- Gateway 不能本地消费 Runtime 内存中的 pending tool。
- Web SSE 不经过 Gateway 回调。
8. 异常、恢复与安全边界
- 外部平台签名、权限或绑定失败时不创建任务。
- 内部派发超时返回可重试状态，不能在 Gateway 本地伪造执行结果。
- SSE 断开只影响订阅，不自动创建第二个任务。
异常处理遵循“先阻止错误扩散，再保留可恢复状态，最后由明确的补偿动作完成收口”。任何重试都必须具备幂等条件，任何恢复都必须重新校验租户、权限、版本和 ownership。
9. 部署与扩展边界
- 组合部署中入口和执行在同一进程。
- 拆分部署中 Web 直达 Runtime，IM/OpenAPI/Schedule 经 Gateway 派发。
部署形态可以变化，但不能把本地内存、临时文件或单副本事件队列当作跨副本事实源。需要横向扩展的能力应先明确共享状态、路由键、健康状态和故障补偿方式。
10. 当前能力与演进计划
当前已落地
- Web、飞书、企微、钉钉、OpenAPI 和 Schedule
- Gateway 到 Runtime 内部派发与事件回调
规划或待完善
- 扩展包贡献 Channel 的统一扩展点
演进方向
- 开放 Channel contribution 扩展点，统一生命周期、鉴权和回调契约。
- 为长连接入口增加断线重连和事件游标，而不改变任务状态机。
11. 方案验收要点
- 同一任务从不同入口产生一致的 Chat/Task 事实。
- Web SSE 不经过 Gateway 回调链路。
- 新增入口只需实现适配器和交付协议，不复制 Dispatcher。
验收时应同时检查正常链路、重复操作、空态或拒绝态、依赖不可用和副本切换，不能只验证图中最短路径。