【实现】Phase 1：Feishu Adapter 与 Gateway 协议桥接（云端控制面）

[Cai-Tang-www]

关联父 RFC

• 父 Issue：【架构】飞书混合接入：远程触发本机 Runner 执行 #553
• 本 Issue 是 Phase 1（云端控制面），聚焦飞书接入与网关协议桥接。

Summary

实现 Feishu Adapter（云端）最小闭环：飞书事件 -> Gateway 调用 -> 结果回飞书，支持消息触发、进度回传、审批回调。

用户价值

• 用户可直接在飞书中发起 NeoCode 任务，不必先打开本地 TUI。
• 任务状态可在飞书可视化回显，降低“是否在执行/是否卡死”的不确定性。
• 后续本机 Runner 接入前，先形成稳定控制面与协议边界。

用户故事

• 作为开发者，我希望在手机飞书输入“检查某仓库 README 并总结”，系统能执行并把结果回到当前会话。
• 作为管理员，我希望审批事件可回调到系统并控制是否继续执行高风险操作。

Goals

• 实现飞书事件订阅入口（challenge、签名校验、幂等去重）。
• 实现飞书消息到 gateway.run 的协议映射。
• 实现执行事件回传飞书（开始/进行中/完成/失败）。
• 实现审批回调到 gateway.resolvePermission。
• 形成最小可运行 Demo（不依赖本机写入能力也可验证）。

Non-Goals

• 不实现本机 Runner 连接管理（见子 Issue B）。
• 不实现完整富卡片交互系统。
• 不实现第三方 IM 通用抽象层。

设计方案

1) 事件入口

• 路由：POST /integrations/feishu/events
• 处理：challenge 应答、签名校验、事件反序列化、去重（event_id / message_id）

2) 指令映射

• 从飞书消息提取用户输入、chat_id、sender_id
• 生成 gateway 请求：
  • gateway.run（含 session 映射 key）
  • 根据业务可查询 runtime.snapshot.get / session.todos.list

3) 回传与可观测

• 将 gateway 关键事件映射为飞书消息：
  • started / progress / permission_required / completed / failed
• 事件日志需含：trace_id、session_id、chat_id、run_id

4) 审批闭环

• 飞书卡片回调 -> Adapter -> gateway.resolvePermission
• 允许与拒绝路径都要可追踪与可回显。

Scope

涉及模块（建议）：

• internal/integrations/feishu（新增）
• internal/gateway（复用现有 action，不泄漏飞书细节）
• 文档：飞书 app 配置、事件订阅、鉴权说明

Acceptance Criteria

• 飞书消息可触发一次 gateway.run。
• 能在飞书收到执行完成/失败消息。
• 审批回调可驱动 gateway.resolvePermission。
• 重复回调不会重复执行同一任务（幂等生效）。
• 未配置或签名失败时返回明确错误且不崩溃。

Test Plan

• 单元测试：
  • challenge / 签名校验
  • 去重逻辑
  • 飞书消息 -> gateway.run 映射
  • 审批回调 -> gateway.resolvePermission 映射
• 集成测试：
  • 事件触发 -> gateway -> 回传消息闭环
  • 重放同一 event 不重复执行

风险与回滚

风险：飞书限流、回调重试、消息顺序错乱。
缓解：幂等键 + 重试退避 + 事件序列日志。
回滚：关闭 Adapter 路由，不影响 Gateway/TUI 主链。