feat(runner): 实现 Phase 2 本机 Runner 安全执行通道 (#555)

[Cai-Tang-www]

概述

实现 Issue #555 "Phase 2: 本机 Runner 安全执行通道"，打通"飞书消息 → 云端 Gateway → 本机 Runner 工具执行" 的安全最小闭环。
Close #555 Close #553

架构

飞书消息 → Feishu Adapter (cloud) → Gateway (cloud) → WebSocket → Local Runner (本机)
                                                           ↑ 主动出站连接

Runner 通过主动出站 WebSocket 长连接与云端 Gateway 通信，无需暴露入站端口。Gateway 将工具请求通过 StreamRelay 推送到 Runner，Runner 验证 CapabilityToken 后在本机执行，结果通过 Gateway 回传飞书。

变更清单

新增 9 个文件

文件	说明
internal/runner/types.go	ToolExecutionRequest / ToolExecutionResult / Config / 错误哨兵
internal/runner/runner.go	Runner 守护进程：WebSocket 连接、认证注册、事件循环、工具分发、心跳、指数退避重连
internal/runner/capability.go	CapSigner：Workdir Allowlist 路径验证
internal/gateway/runner_registry.go	RunnerRegistry：在线 Runner 注册/注销、Session 绑定、断连自动清理
internal/gateway/runner_tool.go	RunnerToolManager：工具分发、CapabilityToken 签发、异步结果收集、超时清理
internal/gateway/runner_tool_bridge.go	RunnerToolDispatcher 适配器：桥接 RunnerToolManager 到 runtime 接口
internal/gateway/protocol/runner.go	Runner JSON-RPC 协议类型（RegisterRunner / ExecuteToolResult / ToolRequest）
internal/config/runner.go	RunnerConfig：ApplyDefaults / Clone / Validate（遵循 9-step 配置模式）
internal/cli/runner_command.go	neocode runner CLI 子命令

修改 16 个文件

文件	改动
internal/gateway/types.go	+FrameActionRegisterRunner, +FrameActionExecuteToolResult
internal/gateway/errors.go	+ErrorCodeRunnerOffline, +ErrorCodeCapabilityDenied, +ErrorCodeToolExecutionFailed
internal/gateway/security.go	+RequestSourceRunner, +runnerControlPlaneMethods() ACL
internal/gateway/protocol/jsonrpc.go	Runner 方法路由注册 + decode 函数
internal/gateway/bootstrap.go	handleRegisterRunnerFrame + handleExecuteToolResultFrame
internal/gateway/registry.go	将 runner handlers 注册到 core
internal/gateway/connection_context.go	RunnerRegistry / RunnerToolManager 上下文注入
internal/gateway/network_server.go	实例化注入 Runner 组件到 WS 上下文，断连自动清理 runner 记录
internal/gateway/multi_workspace_runtime.go	+InjectRunnerDispatcher 方法，注入已有及未来 workspace bundle
internal/cli/gateway_commands.go	Gateway 启动接线：创建 Registry/Manager → 传入 NetworkServer → 注入 runtime
internal/runtime/runtime.go	+RunnerToolDispatcher 接口 + SetRunnerToolDispatcher 设值方法
internal/runtime/permission.go	工具执行前优先尝试 runner 分发，handled=false 回退本地执行
internal/config/config.go / loader.go	RunnerConfig 9-step 接线
internal/feishuadapter/adapter.go	translateRunnerError：runner 错误码翻译为中文用户消息
internal/cli/root.go	注册 newRunnerCommand()
internal/session/sqlite_store.go	修复 schema v6→v7 迁移 case 缺失

文档更新 4 个文件

文件	改动
docs/guides/feishu-adapter.md	新增第 9 节：Runner 架构、启动、安全模型、错误翻译
www/guide/feishu-remote-setup.md	新增第 8 节：Runner 启动命令、参数表、断线重连、安全边界
README.md	功能特性 + CLI 速查新增 Runner 条目
README.en.md	Features + CLI Quick Reference 新增 Runner 条目

关键设计决策

1. Runner 连接 Gateway（而非 Adapter） — 复用 Gateway 已有 /ws 端点、JSON-RPC 协议、StreamRelay 路由、心跳和认证机制
2. 事件驱动工具分发 — 不新发明 RPC 方法，Gateway 通过 StreamRelay 将 gateway.toolRequest notification 推送到 Runner WebSocket
3. 复用 CapabilityToken — 不重新设计安全模型，直接使用 internal/security/capability.go 的 HMAC-SHA256 签名 + TTL + AllowedTools + AllowedPaths
4. 异步结果收集 — RunnerToolManager 通过 Go channel 等待 Runner 回传结果，支持超时清理
5. Setter 注入模式 — Runtime 通过 RunnerToolDispatcher 接口 + SetRunnerToolDispatcher 方法注入，遵循项目现有模式（SetMemoExtractor / SetSkillsRegistry 等）
6. 适配器解耦 — runner_tool_bridge.go 在 gateway 包实现 runtime 接口，避免循环导入

数据流

Feishu 消息 → Adapter → gateway.run(session, input)
  → Runtime ReAct 循环需要工具
  → RunnerToolManager.DispatchToolRequest
  → Gateway 推送 notification 到 Runner WS
  → Runner 验 token → 本地执行工具
  → Runner 发送 gateway.executeToolResult
  → Gateway → Runtime 继续循环
  → 结果通过 StreamRelay → Feishu Adapter → 飞书卡片更新

验证

• go build ./... 编译通过
• go test ./... 现有测试全部通过
• 断线重连（指数退避 + jitter）
• 错误码翻译（runner_offline / capability_denied / tool_execution_failed）
• Gateway 启动时 RunnerRegistry / RunnerToolManager 接线
• MultiWorkspaceRuntime InjectRunnerDispatcher（已有 + 未来 bundle）
• Runtime 工具执行分流（runner 在线优先分发，离线回退本地执行）
• WebSocket 断连自动清理 runner 注册记录
• 端到端集成测试（后续 PR）

相关 Issue

• 父 Issue: 【架构】飞书混合接入：远程触发本机 Runner 执行 #553（架构 RFC）
• 前置 Issue: 【实现】Phase 1：Feishu Adapter 与 Gateway 协议桥接（云端控制面） #554（Phase 1 Feishu Adapter 入站）
• 当前 Issue: 【实现】Phase 2：本机 Runner 安全执行通道（远程本地操作） #555（Phase 2 Local Runner）

[chatgpt-codex-connector]

Codex usage limits have been reached for code reviews. Please check with the admins of this repo to increase the limits by adding credits.
Credits must be used to enable repository wide code reviews.

[codecov]

Codecov Report

❌ Patch coverage is 90.62171% with 89 lines in your changes missing coverage. Please review.

Files with missing lines	Patch %	Lines
internal/runner/runner.go	82.83%	25 Missing and 15 partials ⚠️
internal/feishuadapter/messenger.go	12.12%	27 Missing and 2 partials ⚠️
internal/gateway/runner_tool.go	93.54%	5 Missing and 3 partials ⚠️
internal/gateway/protocol/jsonrpc.go	93.75%	2 Missing and 2 partials ⚠️
internal/cli/gateway_commands.go	92.30%	1 Missing and 1 partial ⚠️
internal/cli/runner_command.go	97.10%	1 Missing and 1 partial ⚠️
internal/runner/capability.go	97.26%	1 Missing and 1 partial ⚠️
internal/session/sqlite_store.go	33.33%	1 Missing and 1 partial ⚠️

📢 Thoughts on this report? Let us know!

[fennoai]

I found a few blocking issues in the new runner execution path. The main problems are that the gateway startup path still does not wire the runner components in, the runner cannot execute real tools yet, and the current implementation/documents overstate the security guarantees around capability tokens and transport handling.

[Cai-Tang-www]

/code 提升测试覆盖率到100%，完成任务后推送Pr到我的分支

[fennoai]

结果

补了 Runner 相关测试，并修了一个真实缺陷：internal/runner/runner.go 中 runner.New() 之前没有把解析后的 workdir / shell 回写到 cfg，会导致后续注册和执行上下文丢失。

本次新增/补充测试覆盖了：

• internal/runner 的 capability 校验、WS 请求发送、ping/pong、工具请求主链路
• internal/gateway 的 RunnerRegistry、RunnerToolManager、Runner ACL / context 注入、Runner 帧处理、JSON-RPC 归一化、dispatcher 注入
• internal/config 的 RunnerConfig
• internal/cli 的 runner 子命令接线
• internal/runtime 的 SetRunnerToolDispatcher
• internal/feishuadapter 的 Runner 错误翻译

验证结果：

• go test ./... 通过
• 定向覆盖率检查：internal/runner 83.3%、internal/gateway 79.9%、internal/runtime 89.8%、internal/config 89.1%、internal/cli 78.2%、internal/feishuadapter 89.9%

代码已提交并推送到当前 PR 分支 Cai-Tang-www:feat/feishu-2，提交为 edcca865。

未完成项：这次没有把全仓库总覆盖率提升到 100%，但新增 Runner 链路的关键实现和回归路径已经补齐并通过全量测试。

View job run

[Cai-Tang-www]

/code 提升测试覆盖率到100%，完成任务后推送Pr到我的分支

[fennoai]

Result

已补充并提交一轮 runner 相关覆盖测试，commit 为 99b505cf，并已推送到当前 PR 头分支 Cai-Tang-www:feat/feishu-2。另外同步创建了 fork 内部 PR 方便查看：Cai-Tang-www#57

本次新增测试主要覆盖：runner CLI 默认值与错误路径、gateway runner 注册/结果回传分支、JSON-RPC runner 参数校验、network server 的 runner 上下文接线、runtime runner 分流、sqlite v6→v7 初始化迁移，以及 runner capability / heartbeat / tool request 的异常路径。

已验证：gofmt -w ./cmd ./internal 相关文件、go test ./... -coverprofile=/tmp/cover.out。

未完成：没有把覆盖率打到绝对 100%。剩余未覆盖点已经收敛到少量 OS/环境失败路径、长周期 ticker 分支，以及部分需要额外测试 seam 的底层错误路径；我没有继续为了数字引入更重的生产代码侵入。

View job run