[Priority: High] [Refactor] 解耦 Executor 核心模块，拆分为独立服务类

[liujuanjuan1984]

🔍 发现的问题 / 原始需求描述

src/opencode_a2a_server/execution/executor.py 目前承担了过多的职责（1500+ 行代码），包括协议映射、会话控制、策略校验、中断管理等，导致维护难度大，测试耦合度高。

🛠️ 详细实施方案

• 涉及文件: src/opencode_a2a_server/execution/
• 核心逻辑:
  1. 抽取 SessionManager: 负责 (identity, contextId) -> session_id 的映射、TTL 维护及所有权校验逻辑。
  2. 抽取 PolicyEnforcer: 处理 A2A_SANDBOX_MODE、目录边界校验（_normalize_and_validate_directory）等声明式策略。
  3. 抽取 InterruptCoordinator: 独立管理 a2a.interrupt.* 相关请求的缓存、匹配和过期处理。
• 伪代码:

  class SessionManager:
      def get_or_create_session(self, identity: str, context_id: str) -> str: ...
  
  class PolicyEnforcer:
      def validate_directory(self, path: str) -> Path: ...

🧪 回归测试建议

• 为各子模块编写单元测试，模拟不同租户/路径的边界条件。
• 验证 A2A 消息转发链路在拆分后行为完全一致。

[liujuanjuan1984]

273 需求评审结论（基于当前 main）

1. 需求有效性

• src/opencode_a2a/execution/executor.py 仍有 1749 行，核心职责（执行编排、会话管理、目录策略、流式消费、interrupt 处理、错误分发、取消控制）未彻底解耦，拆分价值依然成立。
• 该 issue 的核心目标仍成立：当前重构仍有明显收益空间。

2. 现有实施方案与最佳实践匹配度

• 用户提出的方向正确：
  • 引入 SessionManager 管理 (identity, context_id) -> session、TTL 与所有权
  • 引入 PolicyEnforcer 管理 sandbox 与目录边界校验
  • 独立 InterruptCoordinator 管理 a2a interrupt 的生命周期
• 目前代码已有部分基础：
  • _ExecutionCoordinator 已初步承接执行生命周期。
  • _get_or_create_session/_claim_preferred_session 与 _resolve_and_validate_directory 已具备抽离条件。
• 但目前仍未形成“服务边界”：仍在单文件单类中共享大量状态与锁，测试耦合度高，后续变更风险未显著下降。
• 建议采用“模块+服务”而非继续在 executor.py 内细拆：
  • execution/session_manager.py
  • execution/policy.py
  • execution/interrupt.py
  • execution/streaming.py

3. 高相关 open issue 建议一并处理

• #278：目录/沙箱策略与 resolve_and_validate_directory 与 resolve_directory_for_control 强相关。
• #276：并发控制与背压问题与 run/cancel/stream 的共享运行态状态、重试/退避逻辑耦合，重构时应一起处理。
• #274：错误体系分散，建议统一为 ErrorTranslator 与该 issue 对齐。
• #279：指标调用与统计缺口在重构过程中可顺带修复（_emit_metric 当前仅日志输出）。

如果你同意，我建议下一步把 #273 扩展为一个 epic：先分三次提交完成 Session/Policy/Interrupt 三域迁移，并在每次迁移后补齐对应单元测试。

[liujuanjuan1984]

273 结论补充（简版）

• 结论：Issue 273 仍然有效。executor.py 仍为 1749 行且核心职责集中，重构收益高。
• 现状：已经有 _ExecutionCoordinator，说明已有分层意识，但未形成真正的服务边界。
• 建议：按 SessionManager / PolicyEnforcer / InterruptCoordinator / StreamCoordinator 四域拆分到独立模块。
• 高相关建议同步处理的 open issues：
  1. #278（沙箱策略）
  2. #276（并发与背压）
  3. #274（中心化错误映射）
  4. #279（Metrics 匹配）
• 备注：[Priority: Med] [Refactor/Ops] 迁移配置管理至 pydantic-settings #275 可作为后续优化项（配置对象化）

[liujuanjuan1984]

273 实施方案更新（基于当前代码重新评估）

原方案中的 Session / Policy / Interrupt / Streaming 四等分需要调整。

重新评估后的结论

• Session 适合作为一级模块：当前 (identity, context_id) -> session 映射、owner claim、pending claim、inflight create、session lock 等职责集中，边界清晰。
• Policy 适合作为一级模块：目录解析、路径边界校验、控制面复用入口已集中，适合独立。
• Streaming 适合作为一级模块：流式主循环仍在 executor.py，但事件解析、状态缓存、错误格式化已散落在周边模块，适合统一收口。
• Interrupt 当前不适合作为独立一级模块：其职责跨越 stream_events.py、stream_state.py、opencode_upstream_client.py、jsonrpc/application.py。此时强行抽成单独服务，容易制造新的跨层耦合。

调整后的拆分方案

本次 #273 聚焦为“三大模块 + 一个薄协调层”:

1. execution/session_manager.py

• 管理 session cache
• 管理 owner / pending claim
• 管理 inflight create 与 session lock
• 暴露 control 面复用接口

2. execution/policy.py

• 管理 directory normalize / validate
• 管理控制面复用的 directory policy
• 为后续 #278 的系统化 sandbox 策略预留边界

3. execution/stream_runtime.py

• 承接 _consume_opencode_stream
• 统一 chunk / progress / interrupt / terminal signal 发射流程
• 复用现有 stream_events.py、stream_state.py、upstream_errors.py

4. execution/executor.py

• 收缩为 facade / orchestrator
• 负责 execute / cancel / upstream tool dispatch / error 出口
• 不再承载 session / policy / streaming 的具体实现细节

关于 Interrupt 的处理策略

• 第一阶段不单独抽一级模块。
• 先作为 stream_runtime 内部子职责收口。
• 等 callback registry、request lifecycle、tombstone policy 进一步演进后，再考虑独立为 interrupt_registry.py 或 interrupt_service.py。

与相关 issue 的关系

• #278：与 policy.py 强相关，后续可直接沿用边界。
• #276：与 streaming/cancel/running state 强相关，需在本次拆分时避免加深共享状态耦合。
• #274：error translator 可在 executor 变薄后进一步引入。
• #279：streaming 与指标出口收口后更容易修正。