refactor: 梳理 internal 模块边界与分阶段拆分路线

[Yumiue]

背景

internal/ 已经承载了 NeoCode 的核心链路：

TUI -> Gateway -> Runtime -> Provider / Tool Manager -> Tools

随着功能增加，一些模块开始同时承担多类职责，部分目录名也不能准确表达真实边界。这个 issue 用来统一 internal/ 模块整理的方向，并作为后续子 issue / PR 的总入口。

本轮重构不追求一次性大搬迁，而是按职责边界分阶段推进，确保主链路始终可运行、测试可验证、依赖方向不变差。

目标

1. 让 internal/ 的目录结构更贴近真实领域边界。
2. 拆开已经明显混合多类职责的模块。
3. 收敛命名语义，减少后续开发时的理解成本。
4. 为 runtime、gateway 等大模块后续拆分建立清晰路线。
5. 保持现有主链路行为稳定，不在重构中引入功能语义变化。

重构原则

• 以职责边界为依据，不以目录数量或代码行数为目标。
• 优先拆低内聚模块，再考虑小包合并或命名调整。
• 每个阶段单独落地，避免一个 PR 同时做包移动、命名替换和行为修改。
• 新边界必须让依赖方向更清晰，不能制造新的循环依赖或跨层直连。
• 可被模型调用的能力仍统一进入 internal/tools，不下沉到 runtime 或 tui。
• provider 差异仍限制在 internal/provider 内，不向 runtime、tui 或上层调用方泄漏。

分阶段路线

Phase 1：拆分 checkpoint 边界

internal/checkpoint 是优先级最高的整理对象。当前它同时承载会话 checkpoint、文件版本快照、工具写入捕获等能力，适合先拆出更明确的子边界。

建议方向：

• checkpoint/session：会话 checkpoint 的创建、恢复、列表、状态更新与 SQLite 持久化。
• checkpoint/fileversion：per-edit 文件版本链、恢复、diff、changed files。
• 工具写入捕获相关逻辑保持行为不变，先明确归属，再决定是否独立子包。

落地要求：

• 保持 checkpoint 创建、恢复、compact checkpoint、工具写入前后捕获行为不变。
• 更新 runtime、cli、app 等调用方 import。
• 覆盖 session checkpoint、file version snapshot、bash 写入判断的关键测试。

Phase 2：明确 security 权限引擎定位

internal/security 中同时存在简单规则引擎和策略引擎，需要明确各自定位，避免后续调用方随意选择。

建议方向：

• 明确生产装配默认使用的权限引擎。
• 将轻量实现定位为测试夹具或简单规则引擎，并补充注释。
• 如果确认存在废弃路径，再单独迁移测试和删除旧实现。

落地要求：

• 不改变工具权限判断结果。
• 不降低 workspace sandbox、capability token、网络与文件权限校验强度。
• 测试中允许保留轻量夹具，但生产装配路径必须清晰。

Phase 3：评估命名调整

部分包名可以进一步贴近领域语义，但命名调整影响面较大，应独立讨论和落地。

候选方向：

• memo：评估是否更名为 memory，同时梳理工具名、文档、用户可见文案是否同步调整。
• runner：评估是否更名为 toolrunner、remoteexec 或其他产品术语，避免与 gateway 内部 runner registry 混淆。

落地要求：

• 命名调整单独 PR，不和职责拆分混在一起。
• 明确是否影响 CLI 命令、协议字段、工具名、配置项和文档。
• 若仅调整内部包名，不应改变用户可见行为。

Phase 4：拆分 runtime 大模块

runtime 是推理循环与会话编排核心，拆分必须围绕稳定职责展开，不能影响主循环行为。

候选方向：

• planning：计划模式状态、计划解析、计划上下文同步。
• compact：runtime 层 compact 编排、事件派发、checkpoint 对接。
• budget：预算计算、预算事件、compact / stop 决策编排。

落地要求：

• 每次只移动一个稳定职责区域。
• 保持停止条件、tool result 回灌、事件派发、token 统计和上下文管理不回归。
• 相关测试覆盖正常路径、边界条件、异常分支和回归场景。

Phase 5：拆分 gateway 大模块

gateway 是 TUI 与 Runtime 的通信边界，拆分应围绕协议路由、连接管理和 runner relay 展开。

候选方向：

• rpc dispatch：JSON-RPC 分发、请求上下文、错误映射。
• runner relay：runner 注册、session 绑定、工具请求分发、结果回传。
• network server：网络监听、静态文件 handler 注入、服务生命周期。

落地要求：

• TUI 与 Runtime 仍只通过 gateway 协议通信。
• gateway 不直接执行工具，只负责路由、转发和边界隔离。
• 静态资源、监听地址、超时等环境差异项继续通过配置或装配注入。

不在本 issue 中处理

• 不做无关格式化或大规模机械重排。
• 不修改模型 provider 协议设计。
• 不改变工具 schema 或工具执行语义。
• 不调整 API Key、用户配置、会话数据和本地运行数据存储策略。
• 不为了减少目录数量而合并已有稳定边界。

验收标准

• go test ./... 通过。
• 主链路 TUI -> Gateway -> Runtime -> Provider / Tool Manager -> Tools -> UI 不回归。
• 没有新增跨层直连或 provider 字段泄漏。
• 受影响模块的测试覆盖正常路径、边界条件、异常分支和回归场景。
• 新目录、新职责或新命名已同步更新相关文档。
• git status 中不包含无关文件、密钥、本地配置或临时运行数据。

建议首个子 issue

refactor: 拆分 checkpoint 的 session checkpoint 与 file version snapshot 边界

范围：

• 只整理 internal/checkpoint。
• 不同时改名 memo、runner。
• 不拆 runtime、gateway。
• 不改变 checkpoint、compact、工具写入捕获和 diff 展示行为。