docs: add external runtime fusion strategy

2026-04-02 19:13:43 +08:00
parent 3a03ec4cbd
commit 22442979fe
1 changed files with 503 additions and 0 deletions
--- a/docs/architecture/boss_external_runtime_fusion_strategy_cn.md
+++ b/docs/architecture/boss_external_runtime_fusion_strategy_cn.md
@@ -0,0 +1,503 @@
+# Boss 外部执行生态融合方案
+
+这份文档定义 Boss 与两个外部项目的统一融合策略：
+
+- `claw-code`
+- `oh-my-codex`
+
+目标不是把外部项目直接写死进 Boss，而是在 Boss 现有产品主链保持稳定的前提下，引入可升级、可替换、可回退的执行底座与编排能力，让 Boss 能持续吸收外部 runtime 和 orchestration 的迭代成果。
+
+---
+
+## 1. 总结论
+
+采用统一的“三层融合”方案：
+
+1. **Boss 保留产品层**
+2. **`claw-code` 作为执行内核候选**
+3. **`oh-my-codex` 作为编排增强层**
+
+一句话概括：
+
+- Boss 负责整车
+- `claw-code` 负责发动机候选
+- `oh-my-codex` 负责多 worker 编排和变速系统
+
+### 1.1 不做的事
+
+明确不做：
+
+- 不把 `claw-code` 或 `oh-my-codex` 整仓直接 vendoring 进 Boss 作为主实现
+- 不让 Boss 的 Web / Android 前台直接理解外部 runtime 的内部概念
+- 不把群聊、审批、设备导入、多租户这类 Boss 核心业务逻辑下沉到外部项目
+- 不让外部项目反向塑形 Boss 的产品结构
+
+### 1.2 要做的事
+
+明确要做：
+
+- 在 Boss 内部先抽一层稳定执行抽象
+- 用适配器接入 `claw-code`
+- 用独立编排适配器接入 `oh-my-codex`
+- 通过 checkpoint 升级机制持续吸收上游更新
+
+---
+
+## 2. 为什么要统一规划，而不是分别硬接
+
+Boss 当前已经有一条完整但复杂的产品主链：
+
+- Web
+- Android
+- 多租户
+- 会话 / 群聊 / 审批
+- 设备导入
+- 主 Agent
+- 提示词 / 记忆
+- 文件账本与聚合投影
+
+而外部两个项目的强项并不相同：
+
+### 2.1 `claw-code` 的价值
+
+更适合提供：
+
+- runtime
+- session
+- tool registry
+- permission model
+- remote runtime 抽象
+- 可恢复执行语义
+
+它的优势在“执行内核”。
+
+### 2.2 `oh-my-codex` 的价值
+
+更适合提供：
+
+- 多 worker 编排
+- mailbox
+- dispatch lock
+- approvals
+- team runtime
+- tmux / worktree 驱动的 durable coordination
+
+它的优势在“编排层”。
+
+如果分别直接硬接：
+
+- Boss 会同时被两个上游内部结构牵动
+- 维护成本会迅速升高
+- 运行时边界会变得模糊
+
+所以必须先由 Boss 定义自己的稳定抽象层，再接两个外部后端。
+
+---
+
+## 3. 三者分工
+
+### 3.1 Boss 负责的部分
+
+Boss 永远继续负责：
+
+- 多租户与账号体系
+- Web 与 Android 前台
+- 会话模型
+- 项目归档与线程下钻
+- 群聊
+- 审批流
+- 设备导入
+- 提示词与记忆数据归属
+- 账本、聚合投影与事件流
+- OTA 与移动端分发
+
+### 3.2 `claw-code` 负责的部分
+
+`claw-code` 只适合承载：
+
+- 单次执行 runtime
+- 会话级执行状态
+- tool execution contract
+- permission enforcement
+- remote runtime adapter
+- 长任务恢复语义
+
+定位：**执行内核候选**。
+
+### 3.3 `oh-my-codex` 负责的部分
+
+`oh-my-codex` 只适合承载：
+
+- 并行 worker 编排
+- team state
+- mailbox / approvals / dispatch locks
+- durable multi-agent runtime
+- worktree / tmux 协作执行
+
+定位：**编排增强层**。
+
+---
+
+## 4. Boss 内部必须先抽出来的稳定接口
+
+在真正接任何外部项目之前，Boss 先抽一组内部稳定接口。
+
+### 4.1 ExecutionBackend
+
+职责：
+
+- 统一描述“谁来执行一次任务”
+
+建议能力：
+
+- `executeTask`
+- `resumeTask`
+- `cancelTask`
+- `getExecutionStatus`
+
+候选实现：
+
+- `MasterCodexNodeBackend`
+- `OpenAIBackend`
+- `AliyunQwenBackend`
+- `ClawBackendAdapter`
+
+### 4.2 SessionRuntime
+
+职责：
+
+- 统一描述运行态会话
+
+建议能力：
+
+- create
+- resume
+- compact
+- inspect
+- close
+
+### 4.3 PermissionPolicy
+
+职责：
+
+- 统一描述某次任务允许哪些工具、哪些行为、是否需要审批
+
+建议覆盖：
+
+- 工具级权限
+- 下发权限
+- 群聊协作模式
+- approval_required 闸口
+
+### 4.4 ToolRegistry
+
+职责：
+
+- 统一描述 Boss 对外声明和下发的工具能力
+
+未来来源可包括：
+
+- Boss 自己的内建工具
+- `claw-code` 的 tool surface
+- `oh-my-codex` 的 workflow/skill surface
+
+### 4.5 PromptAssembler
+
+职责：
+
+- 统一组装主 Agent 与线程执行时的提示词输入
+
+必须覆盖：
+
+- 管理员全局主提示词
+- 用户私有主提示词
+- 当前对话附加提示词
+- 用户通用记忆
+- 项目记忆
+- 运行时上下文
+
+### 4.6 MemoryResolver
+
+职责：
+
+- 按当前任务和项目筛选真正需要注入的记忆
+
+### 4.7 RemoteRuntimeAdapter
+
+职责：
+
+- 统一接不同设备上的远程执行能力
+
+当前已有来源：
+
+- `local-agent -> codex exec resume`
+
+未来可扩：
+
+- `claw remote runtime`
+- `omx team runtime`
+
+### 4.8 OrchestrationBackend
+
+职责：
+
+- 统一承载“多线程 / 多 worker / 群聊分发”级别的编排能力
+
+候选实现：
+
+- `BossNativeOrchestrator`
+- `OmxTeamBackendAdapter`
+
+---
+
+## 5. 推荐目标架构
+
+推荐调用链如下：
+
+```text
+Boss Product Layer
+  -> Boss Domain Services
+    -> Execution/Prompt/Permission Abstraction Layer
+      -> Backend Selector
+        -> MasterCodexNodeBackend
+        -> OpenAIBackend
+        -> AliyunQwenBackend
+        -> ClawBackendAdapter
+      -> Orchestration Selector
+        -> BossNativeOrchestrator
+        -> OmxTeamBackendAdapter
+```
+
+### 5.1 关键原则
+
+1. Boss 业务层不直接调用外部仓库私有代码结构
+2. 外部项目只能通过 adapter 层进入 Boss
+3. 单线程执行和多线程编排要分成两类 backend
+4. 前台页面只感知 Boss 自己的业务语义，不感知外部 runtime 术语
+
+---
+
+## 6. 推荐接入顺序
+
+### 第一阶段：重构 Boss 执行底座抽象层
+
+目标：
+
+- 只做内部重构
+- 不改变当前生产主链
+
+范围：
+
+- `ExecutionBackend`
+- `PermissionPolicy`
+- `ToolRegistry`
+- `PromptAssembler`
+- `MemoryResolver`
+- `RemoteRuntimeAdapter`
+- `OrchestrationBackend`
+
+目的：
+
+- 先把 Boss 自己的结构理顺
+- 避免后面接外部项目时边接边重构
+
+### 第二阶段：接 `ClawBackendAdapter`
+
+目标：
+
+- 把 `claw-code` 接成一个可选执行后端
+
+先支持：
+
+- session create / resume
+- tool permission handoff
+- remote runtime selection
+- result normalization
+
+不先支持：
+
+- 群聊审批主链
+- 设备导入主链
+- 多租户关键主链默认切换
+
+定位：
+
+- 受控实验 backend
+- 可运行、可验证、可对比
+
+### 第三阶段：接 `OmxTeamBackendAdapter`
+
+目标：
+
+- 把 `oh-my-codex` 接成可选编排后端
+
+优先适用场景：
+
+- 多线程协作
+- 长任务
+- 需要 durable worker state 的任务
+- 复杂群聊 dispatch
+
+不建议一上来就用它替代普通单线程执行。
+
+### 第四阶段：形成统一调度策略
+
+Boss 再根据任务特征自动选择后端：
+
+- 单线程任务：优先执行 backend
+- 群聊复杂协作：优先 orchestration backend
+- 高风险审批任务：优先 Boss 原生审批流
+
+---
+
+## 7. 哪些能力适合先借
+
+### 7.1 从 `claw-code` 先借
+
+优先级最高：
+
+1. runtime / session contract
+2. execution registry
+3. permission context
+4. remote runtime adapter
+
+原因：
+
+- 这些能直接提升 Boss 当前执行底座稳定性
+- 不会立刻冲击前台产品模型
+
+### 7.2 从 `oh-my-codex` 先借
+
+优先级最高：
+
+1. approvals
+2. mailbox
+3. dispatch-lock
+4. worktree-aware worker coordination
+
+原因：
+
+- 这些非常契合 Boss 现有群聊、审批、线程调度主链
+- 但更适合作为编排层，而不是执行内核
+
+---
+
+## 8. 哪些能力不要直接借
+
+### 8.1 不要直接借 `claw-code` 的部分
+
+- 整体 CLI 产品壳
+- 直接面向终端用户的 slash command 产品模型
+- 直接绑定它当前仓库私有状态布局
+
+### 8.2 不要直接借 `oh-my-codex` 的部分
+
+- 直接把 tmux/worktree/runtime 概念暴露给 Boss 终端用户
+- 直接把 `.omx/` 状态目录作为 Boss 账本
+- 让 `team` 机制替代 Boss 自己的产品审批与群聊模型
+
+---
+
+## 9. 升级策略
+
+### 9.1 总原则
+
+Boss 不追“任意最新 main”，只做 checkpoint 升级。
+
+### 9.2 上游跟踪方式
+
+需要长期维护两类信息：
+
+1. `claw-code` 更新观察
+   - runtime
+   - permissions
+   - tools
+   - OAuth
+   - remote runtime
+
+2. `oh-my-codex` 更新观察
+   - team runtime
+   - approvals
+   - mailbox
+   - worktree
+   - dispatch orchestration
+
+### 9.3 升级流程
+
+每次升级时固定执行：
+
+1. 拉取上游代码
+2. 评估契约变化
+3. 检查 adapter breakage
+4. 更新 adapter
+5. 跑 Boss 自己的验证矩阵
+6. 通过后再提升使用范围
+
+### 9.4 验证矩阵
+
+至少覆盖：
+
+- 主 Agent 单聊
+- 普通线程单聊
+- 群聊 dispatch
+- approval_required
+- 设备导入
+- 提示词与记忆
+- 主控切换与备用链回退
+
+---
+
+## 10. 风险
+
+### 10.1 技术风险
+
+- `claw-code` 仍在快速变化，Rust 线可能继续重构
+- `oh-my-codex` 的 runtime/state 机制也会持续演进
+- 直接依赖其私有文件布局会让 Boss 非常脆弱
+
+### 10.2 产品风险
+
+- 如果前台直接承载外部 runtime 概念，会破坏 Boss 当前产品心智
+- 如果太早把生产主链切给外部后端，群聊/审批/导入可能被拖坏
+
+### 10.3 维护风险
+
+- vendoring/fork 会让升级成本指数上升
+- 没有 adapter contract 的情况下，任何上游变动都会扩散到 Boss 业务层
+
+---
+
+## 11. 推荐最终路线
+
+当前推荐路线非常明确：
+
+1. 先完成 Boss 执行底座抽象层重构
+2. 先接 `ClawBackendAdapter`
+3. 再接 `OmxTeamBackendAdapter`
+4. 初期都作为可选后端，不替代默认生产主链
+5. 形成 checkpoint 升级机制，而不是写死版本
+
+---
+
+## 12. 验收标准
+
+只有满足下面条件，才算这条融合路线设计正确：
+
+1. Boss 产品层不直接依赖外部仓库私有目录结构
+2. 升级 `claw-code` 或 `oh-my-codex` 时，主要改动只在 adapter 层
+3. Boss 主链不因为外部 runtime 变化而被动重构
+4. 单线程执行与多线程编排明确分层
+5. 前台仍然只暴露 Boss 自己的产品语义
+6. 外部项目可以持续升级，而 Boss 不会被写死在某个旧版本上
+
+---
+
+## 13. 后续文档建议
+
+这份总方案之后，建议拆出 3 份后续设计文档：
+
+1. `Boss 执行底座抽象层重构`
+2. `ClawBackendAdapter 最小接入设计`
+3. `OmxTeamBackendAdapter 编排接入设计`
+
+在这 3 份文档完成前，不建议直接开始把 `claw-code` 或 `oh-my-codex` 接入当前生产主链。