RFC Proposal:gateway与飞书接入探讨方案

[creatang]

1. 目标问题

当前 NeoCode 已有 Gateway 对外协议，但缺少“飞书作为第三方入口”的标准接入方案，导致：

1. 外部消息入口与 NeoCode 运行链路未统一。
2. 事件回流、异常处理、重连恢复缺少一致约定。
3. 协议升级时第三方客户端兼容风险高。

本 RFC 目标是定义一套可落地、可恢复、可演进的飞书接入方案。

2. 现状与边界

2.1 现状

1. Gateway 已提供稳定核心方法：authenticate/ping/bindStream/run/cancel/list/load/resolvePermission/event。
2. gateway.run 为异步受理模型，最终态依赖 gateway.event。
3. 错误语义已标准化（gateway_code），并有兼容性规范（Stable/Experimental）。

2.2 边界分工（必须遵守）

1. 飞书适配器：负责飞书协议、签名校验、幂等去重、消息编排与回写。
2. Gateway：负责鉴权、ACL、协议归一、路由转发、事件中继。
3. Runtime：负责推理执行、工具调用、权限请求与结果事件生成。
4. 非目标：不在 Gateway 内实现飞书逻辑；不把 Gateway 暴露公网；主链路不依赖 wake.openUrl。

3. 核心设计

3.1 方案选择

采用“飞书适配器进程 + Gateway WS 长连接”模式。

3.2 为什么是这个方案

1. 与现有第三方接入手册完全一致，复用稳定 RPC 契约。
2. WS 可同时承载请求与 gateway.event，适合飞书流式回写。
3. 最小侵入：不改 Gateway/Runtime 核心行为，交付风险低。
4. 兼容可控：只依赖 Stable Core，避免 Experimental 波动。

3.3 协议流程（强约束）

1. 连接 GET /ws
2. gateway.authenticate
3. gateway.bindStream(session_id, run_id?)
4. gateway.run(...)
5. 消费 gateway.event（以 run_done/run_error 判终态）
6. 用户中断时 gateway.cancel(run_id)
7. 权限场景走 gateway.resolvePermission

3.4 关键数据模型

1. session_id：hash(app_id:chat_id:thread_id)（稳定映射会话上下文）。
2. run_id：每条飞书触发消息唯一（ULID/UUID），用于取消与追踪。
3. request_id：每次 RPC 唯一。
4. 幂等键：飞书 event_id。

3.5 异常与恢复策略

1. 以 gateway_code 做错误分支主键，不依赖 message 文本。
2. 重连顺序固定：reconnect -> authenticate -> bindStream。
3. run accepted 后若长时间无终态事件，触发超时告警并执行兜底取消/补偿逻辑。

4. 落地清单

Phase 1（MVP）

1. 实现飞书适配器进程骨架（配置、日志、健康检查）。
2. 打通 WS + authenticate/bindStream/run/event 闭环。
3. 支持文本请求与最终答复回写。

Phase 2（可靠性）

1. 增量流式回写（chunk 聚合 + 节流）。
2. 支持 cancel(run_id)。
3. 接入错误字典分级处理与重试策略。

Phase 3（交互完善）

1. 权限审批卡片（请求->用户决策->resolvePermission）。
2. 事件幂等去重与重放保护。
3. 指标与告警（终态超时、连接抖动、鉴权失败）。

Phase 4（生产化）

1. 多群/多租户路由策略。
2. 升级兼容回归（双版本）。
3. 运维手册与故障演练脚本。

5. 验收标准

5.1 正常路径

1. 飞书消息可触发 gateway.run 并收到 run accepted。
2. gateway.event 持续回流，最终收到 run_done。
3. 回写内容与 run/session 对应关系正确（无串话）。

5.2 异常路径

1. 缺 token/错误 token 时返回 unauthorized，且不进入执行。
2. 参数缺失或非法字段返回 missing_required_field/invalid_frame/invalid_action。
3. Runtime 超时返回 timeout，客户端执行退避重试或失败收敛。
4. ACL 拒绝返回 access_denied，客户端不盲重试。

5.3 恢复路径

1. 网关断连后可自动重连并完成 authenticate + bindStream 恢复。
2. 恢复后新请求可正常执行，旧 run 的状态可查询或有明确终止策略。
3. 连接恢复过程中无重复执行（幂等有效）。

6. 风险与回滚

6.1 主要风险

1. 事件消费背压导致延迟或断连。
2. 第三方参数不规范导致高比例请求失败。
3. 升级造成字段兼容偏差。
4. token 泄露带来安全风险。

6.2 风险缓解

1. 请求协程与事件协程解耦，回写节流与队列监控。
2. 接入前置参数校验层，严格对齐 RPC Schema。
3. 仅依赖 Stable Core；忽略未知字段；上线前双版本回归。
4. token 仅本地安全存储，日志脱敏，定期轮换。

6.3 回滚方案

1. 保留飞书适配器功能开关（按租户/群维度关闭）。
2. 回滚到“仅同步结果模式”（关闭流式）。
3. 必要时完全切回人工/旧机器人链路，不影响 Gateway 主服务。
4. 回滚后保留 run/session 审计日志用于问题复盘。

[creatang]

@xgopilot 这个issue请按.skills目录下的提案skill重写，最好能加一些必要的时序图，并且需要检查是否符合gateway第三方介入规范文档（https://github.com/1024XEngineer/neo-code/blob/main/docs/reference）

[fennoai]

按提案 Skill 重写稿（可直接替换 Issue 正文）

说明：仓库内可用提案模板位于 .agents/skills/issue-rfc-proposal/SKILL.md，以下内容按其要求组织为「目标问题 -> 设计方案 -> 落地清单 -> 验收标准 -> 风险与回滚」。

标题

RFC Proposal：Gateway 与飞书接入标准化方案（Adapter over Gateway WS）

1. 目标问题（Why）

NeoCode 已具备稳定 Gateway 协议，但缺少“飞书第三方入口”的标准接入规范，导致：

1. 外部入口与 TUI -> Gateway -> Runtime -> Tools -> UI 主链路未形成统一约束。
2. 运行结果依赖 gateway.event 回流，但客户端对终态判定、异常分级、断线恢复策略不一致。
3. 协议演进时，第三方客户端缺少可验证的兼容与回滚路径。

本 RFC 目标：定义一套可落地、可恢复、可演进的飞书适配方案，严格复用 Gateway Stable Core，不向 Runtime/TUI 泄漏飞书协议细节。

2. 非目标（Out of Scope）

1. 不在 Gateway 内实现飞书专有逻辑。
2. 不将 Gateway 直接暴露公网。
3. 不依赖 wake.openUrl（Experimental）作为主链路。
4. 不修改 Gateway/Runtime 核心协议语义。

3. 设计方案（How）

3.1 总体架构

采用“飞书适配器进程 + Gateway WebSocket 长连接”模式。

• 飞书适配器：飞书事件接入、签名校验、幂等去重、消息编排、回写飞书。
• Gateway：鉴权、ACL、JSON-RPC 归一、运行受理、事件中继。
• Runtime：推理执行、工具调用、权限请求、运行事件产出。

3.2 强约束流程

1. GET /ws 建立连接。
2. gateway.authenticate(token)。
3. gateway.bindStream(session_id, run_id?)。
4. gateway.run(...)（异步受理）。
5. 消费 gateway.event，以 run_done/run_error 判终态。
6. 用户取消时调用 gateway.cancel(run_id)。
7. 权限场景使用 gateway.resolvePermission(request_id, decision)。

3.3 关键标识模型

1. session_id = hash(app_id:chat_id:thread_id)，用于稳定会话映射。
2. run_id：每条飞书触发唯一（建议 ULID），用于追踪/取消/幂等关联。
3. request_id：每次 JSON-RPC 请求唯一。
4. 幂等键：飞书 event_id。

3.4 时序图（主流程）

sequenceDiagram
  participant F as Feishu
  participant A as Adapter
  participant G as Gateway
  participant R as Runtime

  F->>A: message event(event_id, chat_id, thread_id, text)
  A->>A: verify signature + dedup(event_id)
  A->>G: gateway.authenticate(token)
  G-->>A: ack(authenticate)
  A->>G: gateway.bindStream(session_id, run_id)
  G-->>A: ack(bind_stream)
  A->>G: gateway.run(session_id, run_id, input_text)
  G-->>A: ack(run accepted)
  R-->>G: runtime event(progress)
  G-->>A: gateway.event(run_progress)
  R-->>G: runtime event(done|error)
  G-->>A: gateway.event(run_done|run_error)
  A-->>F: final reply

Loading

3.5 时序图（取消与权限）

sequenceDiagram
  participant U as User
  participant F as Feishu
  participant A as Adapter
  participant G as Gateway

  U->>F: click cancel
  F->>A: cancel action(run_id)
  A->>G: gateway.cancel(run_id)
  G-->>A: ack(cancel)
  G-->>A: gateway.event(run_error/canceled)
  A-->>F: canceled notice

Loading

sequenceDiagram
  participant R as Runtime
  participant G as Gateway
  participant A as Adapter
  participant F as FeishuUser

  R-->>G: permission_request(request_id)
  G-->>A: gateway.event(permission_request)
  A-->>F: approval card
  F-->>A: allow_once|allow_session|reject
  A->>G: gateway.resolvePermission(request_id, decision)
  G-->>A: ack(resolve_permission)

Loading

3.6 时序图（断线恢复）

sequenceDiagram
  participant A as Adapter
  participant G as Gateway

  A-xG: ws disconnected
  A->>A: backoff reconnect
  A->>G: connect /ws
  A->>G: gateway.authenticate
  G-->>A: ack(authenticate)
  A->>G: gateway.bindStream(session_id, run_id?)
  G-->>A: ack(bind_stream)
  A->>A: resume event consumption + timeout watchdog

Loading

4. 落地清单（What）

Phase 1（MVP）

1. 适配器骨架：配置、日志、健康检查、飞书签名校验。
2. 打通 authenticate/bindStream/run/event 闭环。
3. 支持文本请求与最终答复回写。

Phase 2（可靠性）

1. 增量流式回写（chunk 聚合 + 节流）。
2. 支持 cancel(run_id)。
3. 错误字典分级处理：以 gateway_code 为主键。
4. ACK 后终态超时 watchdog + 兜底取消/补偿。

Phase 3（交互完善）

1. 权限审批卡片与 resolvePermission 闭环。
2. 事件幂等去重与重放保护。
3. 指标与告警：终态超时、连接抖动、鉴权失败、事件积压。

Phase 4（生产化）

1. 多群/多租户路由策略。
2. 双版本兼容回归（current/target）。
3. 运维手册与故障演练脚本。

5. 验收标准（可验证）

5.1 正常路径

1. 飞书消息可触发 gateway.run 并收到 run accepted。
2. 能持续收到 gateway.event，最终出现 run_done 或 run_error。
3. session_id/run_id/request_id 全链路一致，无串话。

5.2 异常路径

1. 认证失败返回 unauthorized（/rpc 映射 401），不进入执行。
2. 参数错误返回 missing_required_field/invalid_frame/invalid_action。
3. Runtime 超时返回 timeout，客户端执行退避重试（带幂等键）。
4. ACL 拒绝返回 access_denied（/rpc 映射 403），客户端不盲重试。

5.3 恢复路径

1. 断连后自动重连并完成 authenticate + bindStream。
2. 恢复后新请求可执行；旧 run 有明确终止或补偿策略。
3. 恢复过程中不重复执行（event_id/run_id 幂等生效）。

6. 风险与回滚

6.1 主要风险

1. 事件背压导致延迟或断连。
2. 三方参数不规范导致高失败率。
3. 升级引发字段兼容偏差。
4. token 泄露风险。

6.2 风险缓解

1. 请求协程与事件协程解耦；队列长度与丢弃率监控。
2. 接入前置严格校验（含未知字段拒绝）。
3. 仅依赖 Stable Core；忽略未知返回字段；上线前双版本回归。
4. token 本地安全存储、日志脱敏、定期轮换。

6.3 回滚方案

1. 按租户/群维度关闭飞书适配器开关。
2. 回滚到“仅最终结果回写”模式（关闭流式）。
3. 必要时切回旧机器人链路，不影响 Gateway 主服务。
4. 保留 run/session 审计日志用于复盘。

---

与 docs/reference 规范符合性检查

已符合

1. 使用 Stable Core：authenticate/ping/bindStream/run/cancel/resolvePermission/event。
2. gateway.run 作为异步受理，终态由 gateway.event(run_done/run_error) 判定。
3. 异常分支使用 gateway_code，不依赖 message 文本。
4. 恢复顺序采用 reconnect -> authenticate -> bindStream。
5. 不依赖 wake.openUrl（Experimental）。

建议补充（使提案更严谨）

1. 明确 bindStream.channel 与连接通道一致（WS 场景可用 all 或 ws，不得非法值）。
2. 明确请求侧使用严格 schema（未知字段按 invalid_frame 处理）。
3. 在“客户端实现要点”里补一条：ping 周期续期绑定 TTL。
4. 明确 run_id 生成策略优先级与固定化（显式 run_id 优先）。

结果说明

已完成：按提案 skill 重写、补充必要时序图、并给出对照 docs/reference 的符合性检查与待补充项。未执行代码改动。

View job run

[creatang]

@xgopilot 所以这个方案在审查代码后是可执行的，并且可操作性是最大的？请你给出用户实际的使用场景进行验证

[fennoai]

结论

是，可执行；在当前仓库边界下也基本是“可操作性最大”的方案，但前提是按 RFC 的约束完整实现适配器侧可靠性（幂等、重连、终态超时兜底）。

我做了两层核验：

1. 协议与文档一致性：docs/reference/gateway-rpc-api.md、gateway-compatibility.md、gateway-error-catalog.md 与你提案的主流程一致（authenticate -> bindStream -> run -> gateway.event -> done/error，错误主键用 gateway_code，重连后重新绑定流）。
2. 代码可执行性：网关已有对应方法和事件链路（gateway.authenticate/bindStream/run/cancel/resolvePermission/event），并且相关测试通过：go test ./internal/gateway/... ./internal/tui/services/... 全绿。

为什么说“当前最可操作”

和其它接入思路相比，这个方案改动最小、复用现有稳定契约最多：

1. 不改 Gateway/Runtime 核心行为，只新增飞书适配器进程。
2. 直接复用 WS 双向通道承载 RPC + 事件回流，避免多通道拼接复杂度。
3. 终态语义已在现有协议里固定（run_done/run_error），便于做生产级兜底。

用户实际场景验证

场景 1：飞书群聊里发“帮我分析这个报错日志并给修复建议”

1. 适配器收飞书 event_id，验签并做幂等去重。
2. 生成 session_id=hash(app_id:chat_id:thread_id)，同线程复用上下文。
3. gateway.run 返回 accepted 后，持续消费 gateway.event。
4. 飞书侧先回“处理中”，最终在 run_done 时回写完整答案。
   验证点：同一 thread 不串话，且最终态只由 run_done/run_error 决定。

场景 2：用户在飞书点击“取消生成”

1. 适配器拿到 run_id 调 gateway.cancel(run_id)。
2. 继续等 gateway.event 终态（通常 run_error/canceled 语义）。
3. 飞书回写“已取消”。
   验证点：取消是精确到 run_id，不会误杀同会话其它任务。

场景 3：工具权限审批（如命令执行）

1. Runtime 触发权限请求事件。
2. 适配器将请求渲染为飞书审批卡片。
3. 用户点允许/拒绝后，适配器调用 gateway.resolvePermission。
4. 运行继续或终止，并通过事件流回写。
   验证点：审批决策闭环可追踪（request_id 关联）。

场景 4：网关连接抖动后自动恢复

1. WS 断开，适配器按退避重连。
2. 固定顺序：reconnect -> authenticate -> bindStream。
3. 新请求恢复可用；对旧 run_id 执行超时告警 + 取消/补偿。
   验证点：恢复过程中不重复执行（event_id 幂等 + run_id 关联）。

边界与补强建议

要让“可操作性最大”在生产上成立，建议把这三项作为 MVP 必做：

1. ping 保活 + TTL 续期监控（防止静默断链）。
2. run accepted 后终态 watchdog（超时触发取消/补偿）。
3. 严格参数校验与错误分级仅依赖 gateway_code（不依赖 message 文本）。

未做事项：本次仅做方案可执行性审查与场景验证，未改代码。

View job run

[pionxe]

@xgopilot 我有几个问题，希望你能够一一详细回答：

1. 这个飞书群聊是只有用户和本地neocode的群聊？还是什么？
2. 在pr feat(gateway): RFC#420 全量落地（双产物发布、统一启动内核、第三方接入文档与CI验收） #423 中提到正在落地不带客户端的gateway版本，与你当前设计的计划是否冲突？
3. 你的方案是否是插件形式的？供用户选择下载后方能使用？
4. 你的方案中是怎么唤醒飞书适配器的？如果后台没有gateway监听进程以及并没有拉起runtime，你又是如何处理的？

[fennoai]

逐条答复

1. 这个“飞书群聊”不是“用户和本地 NeoCode 专属私有群聊”的固定形态。它本质是飞书里的一个会话入口（可单聊、群聊、线程）。
   适配器把飞书会话映射成 session_id=hash(app_id:chat_id:thread_id)，再通过 Gateway 进入 NeoCode 主链路。也就是说，飞书侧是否多人群聊由业务场景决定，NeoCode 只把它当外部消息源处理。

2. 与 PR feat(gateway): RFC#420 全量落地（双产物发布、统一启动内核、第三方接入文档与CI验收） #423 不冲突，且是互补关系。
   PR feat(gateway): RFC#420 全量落地（双产物发布、统一启动内核、第三方接入文档与CI验收） #423 的核心是落地 neocode-gateway（gateway-only 发布物）和自动拉起契约；本 RFC 讨论的是“飞书如何通过标准协议接入 Gateway”。前者提供稳定承载底座，后者定义第三方入口接法。只要飞书适配器继续走 Stable Core（authenticate/bindStream/run/event/cancel/resolvePermission），两者方向一致。

3. 当前方案不是“NeoCode 内核插件”形态，而是“独立飞书适配器进程”。
   它作为 Gateway 的外部客户端接入，不侵入 runtime/gateway 核心实现。交付上可以做成可选安装（按需启用），但架构上它是独立进程，不是把飞书逻辑编进核心链路。

4. 唤醒与兜底建议如下（也是你问的关键）：

5. 适配器启动后先尝试连接 Gateway WS（/ws）。

6. 若连接失败，按固定顺序执行“拉起后重拨”：尝试拉起 neocode-gateway（复用 feat(gateway): RFC#420 全量落地（双产物发布、统一启动内核、第三方接入文档与CI验收） #423 约定的发现顺序），等待健康检查通过，再 authenticate -> bindStream。

7. 若 Gateway 最终仍不可用：飞书侧回写“服务暂不可用”，请求不进入执行队列（避免假受理）。

8. 关于 Runtime：在当前 gateway-only 设计里，Runtime 是 Gateway 服务能力的一部分（不是由飞书适配器直接拉起）。所以适配器只负责“Gateway 可达性与会话绑定”，不跨层控制 Runtime。

9. 对已 run accepted 但长时间无终态事件的请求，必须有 watchdog：超时告警 + cancel(run_id)/补偿收敛，避免会话悬挂。

结论

你的 4 个问题对应的边界可以收敛为一句话：飞书接入是“独立适配器进程接 Gateway”，与 #423 的 gateway-only 落地是上下游配合关系，不是冲突关系；可选安装、按需启用；无 Gateway 时先自动拉起再重连，仍失败就明确失败回写，不做隐式执行。

本次仅完成方案答复与边界澄清，未做代码改动。

View job run

[creatang]

@xgopilot 根据comment你是否还认为本次的RFC无误？请给出最终的RFC版本

[fennoai]

结论

基于现有评论与仓库规范，我仍认为该 RFC 方向正确且可执行；但为保证“可操作性最大”，最终版需把保活续期、终态 watchdog、严格 schema 校验明确为强约束（MVP 必做）。

最终 RFC 版本（建议替换 Issue 正文）

RFC Proposal：Gateway 与飞书接入标准化方案（Adapter over Gateway WS）

1. 目标问题（Why）

当前 NeoCode 已有 Gateway 对外协议，但缺少“飞书作为第三方入口”的标准接入方案，导致：

1. 外部消息入口与 NeoCode 主链路未统一。
2. 事件回流、异常处理、重连恢复缺少一致约定。
3. 协议升级时第三方客户端兼容风险高。

本 RFC 目标：定义一套可落地、可恢复、可演进的飞书接入方案，严格复用 Gateway Stable Core，不向 Runtime/TUI 泄漏飞书协议细节。

2. 范围与边界

2.1 范围内

1. 飞书适配器进程设计（协议接入、鉴权、幂等、回写）。
2. 基于 Gateway WS 的请求与事件闭环。
3. 异常分级、重连恢复、取消与权限审批闭环。

2.2 非目标

1. 不在 Gateway 内实现飞书逻辑。
2. 不将 Gateway 直接暴露公网。
3. 主链路不依赖 wake.openUrl（Experimental）。
4. 不修改 Gateway/Runtime 核心协议语义。

3. 设计方案（How）

3.1 架构选择

采用“飞书适配器进程 + Gateway WebSocket 长连接”模式。

职责分工：

1. 飞书适配器：飞书事件接入、签名校验、幂等去重、消息编排与回写。
2. Gateway：鉴权、ACL、协议归一、路由转发、事件中继。
3. Runtime：推理执行、工具调用、权限请求与结果事件生成。

3.2 强约束流程

1. GET /ws 建立连接。
2. gateway.authenticate(token)。
3. gateway.bindStream(session_id, run_id?)。
4. gateway.run(...)（异步受理）。
5. 消费 gateway.event，以 run_done/run_error 判终态。
6. 用户中断调用 gateway.cancel(run_id)。
7. 权限场景调用 gateway.resolvePermission。

3.3 关键数据模型

1. session_id = hash(app_id:chat_id:thread_id)（稳定映射会话）。
2. run_id：每条飞书触发唯一（建议 ULID）。
3. request_id：每次 RPC 唯一。
4. 幂等键：飞书 event_id。

3.4 可靠性强约束（MVP 必做）

1. ping 保活与 TTL 续期监控，防止静默断链。
2. run accepted 后终态 watchdog；超时触发告警并执行取消/补偿。
3. 请求侧严格 schema 校验，非法/未知字段按 invalid_frame 收敛。
4. 错误分支仅依赖 gateway_code，不依赖 message 文本。
5. 重连顺序固定：reconnect -> authenticate -> bindStream。

4. 时序（简版）

4.1 主流程

Feishu Event -> Adapter(验签/幂等) -> authenticate -> bindStream -> run -> gateway.event* -> run_done|run_error -> 回写飞书

4.2 取消流程

用户取消 -> Adapter -> cancel(run_id) -> gateway.event(终态) -> 回写“已取消”

4.3 权限流程

permission_request -> 飞书审批卡片 -> resolvePermission -> 继续执行或终止

4.4 断线恢复

WS 断开 -> 退避重连 -> authenticate -> bindStream -> 恢复事件消费

5. 落地清单（What）

Phase 1（MVP）

1. 适配器骨架：配置、日志、健康检查、签名校验。
2. 打通 authenticate/bindStream/run/event 闭环。
3. 支持文本请求与最终答复回写。
4. 完成 ping + TTL、终态 watchdog、严格 schema 校验。

Phase 2（可靠性）

1. 增量流式回写（chunk 聚合 + 节流）。
2. 支持 cancel(run_id)。
3. 错误字典分级处理与重试策略。
4. 幂等去重与重放保护。

Phase 3（交互完善）

1. 权限审批卡片与 resolvePermission 闭环。
2. 指标与告警：终态超时、连接抖动、鉴权失败、事件积压。
3. 运行审计与追踪（session/run/request 关联）。

Phase 4（生产化）

1. 多群/多租户路由策略。
2. 双版本兼容回归（current/target）。
3. 运维手册与故障演练脚本。

6. 验收标准（可验证）

6.1 正常路径

1. 飞书消息可触发 gateway.run 并收到 run accepted。
2. gateway.event 持续回流，最终出现 run_done 或 run_error。
3. session_id/run_id/request_id 关联一致，无串话。

6.2 异常路径

1. 缺 token/错误 token 返回 unauthorized，且不进入执行。
2. 参数缺失或非法字段返回 missing_required_field/invalid_frame/invalid_action。
3. Runtime 超时返回 timeout，客户端退避重试或失败收敛。
4. ACL 拒绝返回 access_denied，客户端不盲重试。

6.3 恢复路径

1. 网关断连后可自动重连并完成 authenticate + bindStream。
2. 恢复后新请求可执行；旧 run 有明确终止或补偿策略。
3. 恢复过程中无重复执行（event_id/run_id 幂等生效）。

7. 风险与回滚

7.1 主要风险

1. 事件消费背压导致延迟或断连。
2. 三方参数不规范导致高比例失败。
3. 升级造成字段兼容偏差。
4. token 泄露带来安全风险。

7.2 风险缓解

1. 请求协程与事件协程解耦，回写节流与队列监控。
2. 接入前置参数校验层，严格对齐 RPC Schema。
3. 仅依赖 Stable Core，忽略未知返回字段，上线前双版本回归。
4. token 仅本地安全存储，日志脱敏，定期轮换。

7.3 回滚方案

1. 保留飞书适配器功能开关（按租户/群维度关闭）。
2. 回滚到“仅同步最终结果模式”（关闭流式）。
3. 必要时切回旧机器人链路，不影响 Gateway 主服务。
4. 回滚后保留 run/session 审计日志用于复盘。

说明

本次为 RFC 分析与定稿，不涉及代码改动。

View job run

[creatang]

@xgopilot 现在完成了RFC的提案版本，并且确认无误，请按.skills目录下的实现类skill，完成实现类issue

[fennoai]

执行结果

已按 .agents/skills/issue-rfc-implementation/SKILL.md 完成“实现类 issue”创建：

• 新 Issue：【实现】 Gateway与飞书接入方案落地实施 #428
• 链接：【实现】 Gateway与飞书接入方案落地实施 #428
• 标题：【实现】 Gateway与飞书接入方案落地实施

本次完成内容

1. 基于已确认 RFC（RFC Proposal:gateway与飞书接入探讨方案 #424）提炼实现执行单结构。
2. 按实现类模板补齐：关联 RFC、实现设计、任务拆解、测试验证、风险与回滚。
3. 将 Phase 1~4 落地项转为可追踪 checklist，并补充正常/边界/异常验证项。

未执行内容

• 未进行代码改动与测试运行（本次仅创建实施类 issue）。

View job run