【架构】飞书混合接入：远程触发本机 Runner 执行

[Cai-Tang-www]

Summary

为 NeoCode 提供“飞书远程控制 + 本机执行”的混合接入架构：用户可在手机/桌面飞书发消息触发任务，由云端 Feishu Adapter 编排并路由到本机 Runner，安全地执行本地代码改动、文件操作与 URL 预览回传。

Background

当前 NeoCode 已具备 Gateway / Runtime / Tools 主链路能力，但缺少“企业 IM 入口”和“远程触发本机执行”的产品化闭环。

用户诉求明确：

• 在飞书聊天中直接下发任务；
• 任务可路由到本机工作区执行（改代码、读写文件、预览 URL）；
• 过程可观测、可审批、可追踪；
• 不希望暴露本机端口或引入高风险默认权限。

Problem

当前行为：

• 只能在本地 TUI/CLI 直接使用 NeoCode；
• 没有飞书事件入口和消息回传协议映射；
• 没有“云端消息 -> 本机执行”安全通道。

期望行为：

• 飞书中 @机器人或私聊可触发 NeoCode 任务；
• 支持把任务路由到本机 Runner 执行；
• 支持权限审批、运行进度、结果回传、失败可解释；
• 全程通过 Gateway 协议接入，不破坏既有架构边界。

User Scenario

场景：开发者在地铁上用手机飞书发消息“在 neo-code 仓库创建 2.txt 内容为 2，并给我预览链接”。

系统应当：

1. Feishu Adapter 接收事件并鉴权；
2. 将指令映射为 gateway.run 请求；
3. 根据会话路由到该开发者在线的本机 Runner；
4. Runner 在受限工作区执行工具链；
5. 执行事件和结果回传飞书（含审批/拒绝原因/预览链接）。

Goals

• 提供飞书到 NeoCode Gateway 的标准接入面（事件、消息、审批回调）。
• 提供“云端编排 + 本机执行”混合模式，支持本地文件与代码操作。
• 确保最小权限与可审计：工作区白名单、工具权限、审批与日志。
• 两阶段落地：先可用 MVP，再增强稳定性与体验。

Non-Goals

• 不在本 Issue 内实现完整多租户 SaaS 控制台。
• 不实现第三方 IM（企业微信/钉钉）统一抽象。
• 不在本轮引入新的 provider 协议重构。
• 不将本机端口直接公网暴露作为默认方案。

Proposed Design

架构分层

1. Feishu Adapter（云端）
   • 负责飞书事件订阅、签名校验、challenge、幂等去重。
   • 将飞书消息映射为 Gateway 请求（gateway.run / gateway.resolvePermission / snapshot 查询）。
2. Gateway（现有）
   • 继续作为 TUI/Runtime 的协议边界，不感知飞书细节。
3. Runner Router（新增能力，优先最小实现）
   • 维护“用户/会话 -> 本机 Runner”在线映射。
   • 仅在 Runner 在线且授权时将任务路由到本机。
4. Local Runner（本机）
   • 执行 Runtime + Tools，受工作区与工具权限约束。
   • 回传事件流给 Feishu Adapter 以消息化展示。

安全策略（MVP）

• Runner 主动长连，不暴露入站端口。
• 每次会话绑定 capability token + TTL。
• 工具权限默认最小化：先读再写，写操作可审批。
• 工作区 allowlist（禁止越界访问）。

Scope

涉及模块：

• internal/gateway（协议动作复用与可能的桥接扩展）
• 新增 internal/integrations/feishu（或等价目录）
• 本机 runner 连接管理（可新模块）
• 文档与示例配置（飞书 app、Runner 配置、权限策略）

交付拆分：

• 子 Issue A：Feishu Adapter 与 Gateway 协议桥接（云端控制面）
• 子 Issue B：本机 Runner 安全执行通道（远程本地操作）

Acceptance Criteria

• 手机/桌面飞书发消息可触发一次 NeoCode 任务。
• 任务可路由到本机 Runner 并返回执行结果。
• 至少一条审批链路可用（允许/拒绝均可回传）。
• 至少一条 URL 预览或结果链接回传链路可用。
• 无配置/Runner 离线时有清晰错误提示，不崩溃。

Test Plan

• 单元测试：
  • 飞书事件签名校验/去重；
  • 请求映射（飞书消息 -> gateway.run）；
  • Runner 路由策略与离线处理。
• 集成测试：
  • 消息触发 -> 执行 -> 回传全链路；
  • 审批回调 -> gateway.resolvePermission 闭环。
• 手工验收：
  • 手机飞书发任务，电脑执行本地文件操作并回显。

Risks / Compatibility

风险：

• 企业网络导致回调/长连不稳定；
• 权限策略过宽导致本机安全风险；
• 飞书限流或回调重试导致重复执行。

缓解：

• 幂等键（event_id / message_id）；
• 任务去重与重试保护；
• 默认只读 + 显式授权写入。

回滚：

• 保持 Gateway 原主链路不变；
• 关闭 Feishu Adapter 即可回退到本地 TUI/CLI 模式。

Follow-ups

• 子 Issue A（云端桥接）
• 子 Issue B（本机 Runner）
• 后续增强：多设备选择、会话历史同步、富卡片 UI

[Cai-Tang-www]

已拆分子 Issue：

• Phase 1（云端控制面）：【实现】Phase 1：Feishu Adapter 与 Gateway 协议桥接（云端控制面） #554 【实现】Phase 1：Feishu Adapter 与 Gateway 协议桥接（云端控制面）
• Phase 2（本机执行通道）：【实现】Phase 2：本机 Runner 安全执行通道（远程本地操作） #555 【实现】Phase 2：本机 Runner 安全执行通道（远程本地操作）

建议实施顺序：#554 -> #555。

完成定义（父 Issue 关闭条件）：

1. 飞书消息可触发 NeoCode 任务并回传结果；
2. 可路由到本机 Runner 执行受限工作区操作；
3. 审批、离线、越界、token 失效路径可解释且可追踪。