【实现】Phase 2：本机 Runner 安全执行通道（远程本地操作）

[Cai-Tang-www]

关联父 RFC

• 父 Issue：【架构】飞书混合接入：远程触发本机 Runner 执行 #553
• 依赖子 Issue A：【实现】Phase 1：Feishu Adapter 与 Gateway 协议桥接（云端控制面） #554（先有云端控制面，再接本机执行通道）

Summary

实现“远程飞书消息 -> 本机 Runner 执行”的安全最小闭环：Runner 主动长连、会话路由、最小权限执行、结果回传。

用户价值

• 用户可在手机飞书远程驱动电脑上的本地仓库操作。
• 不需要公网暴露本机端口，降低接入门槛与安全风险。
• 在保留 NeoCode 本地执行能力的前提下，获得远程控制体验。

用户故事

• 作为开发者，我在外出时希望通过飞书让家里/办公室电脑的 NeoCode 修改本地仓库文件并回传结果。
• 作为安全负责人，我希望默认策略是受限工作区+最小工具权限，写操作可审批且可审计。

Goals

• 实现本机 Runner 到云端 Adapter 的主动连接机制（不暴露入站端口）。
• 实现会话路由：用户/会话 -> 指定 Runner。
• 实现受限执行：workdir allowlist + 工具权限控制。
• 实现 capability token + TTL + 失效处理。
• 实现 Runner 离线/拒绝/超时等可解释回传。

Non-Goals

• 不做多租户设备编排平台。
• 不做全自动高危命令放行。
• 不做跨 IM 平台统一 Runner 协议。

设计方案

1) 连接模型

• Runner 主动向 Adapter 发起长连接（WebSocket/gRPC-stream 任选其一，按现有栈最小实现）。
• Adapter 维护在线 Runner registry（心跳、租约、最后活跃时间）。

2) 路由模型

• 飞书请求进入后，根据 user_id/chat_id/session_id 解析目标 Runner。
• Runner 不在线时，立即返回“离线不可执行”并给出恢复建议。

3) 安全模型（MVP）

• capability token 绑定：runner_id + session_id + 过期时间。
• allowlist：仅允许指定工作区路径。
• 工具策略：默认只读；写入/batch shell 需显式审批。
• 审计：记录请求人、工具、路径、结果与拒绝原因。

4) 回传与状态

• 回传 started/progress/completed/failed。
• 关键异常：token 失效、权限拒绝、路径越界、Runner 离线。

Scope

涉及模块（建议）：

• internal/runner（新增或等价目录）
• internal/integrations/feishu（路由/会话绑定扩展）
• internal/gateway（保持协议边界，不耦合飞书细节）
• 文档：本机部署、token 策略、安全注意事项

Acceptance Criteria

• 本机 Runner 在线时，飞书消息可触发本地工作区任务。
• Runner 离线时返回可解释错误，不阻塞系统。
• 越界路径访问被拒绝并回传拒绝原因。
• 写操作审批链路可用（允许/拒绝均可回传）。
• capability token 过期后请求被拒绝，刷新后恢复。

Test Plan

• 单元测试：
  • Runner 注册/心跳/租约失效
  • token 验证与过期处理
  • 路由命中/离线路由
  • 路径越界拒绝
• 集成测试：
  • 飞书触发 -> Adapter -> Runner -> Gateway -> 回传
  • 审批拒绝路径与超时路径

风险与回滚

风险：本机网络抖动导致连接中断、权限配置错误导致误拒绝。
缓解：重连机制、租约与退避、默认最小权限与清晰日志。
回滚：关闭 Runner 路由，退回云端只读机器人模式。