krisolo/boss
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity
Files
4ab0414d43c0dc047405b4c9bfaef64a086a0aba
boss/docs/architecture/boss_external_runtime_fusion_strategy_cn.md
kris 22442979fe docs: add external runtime fusion strategy
2026-04-02 19:13:43 +08:00

10 KiB
Raw Blame History

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. 推荐目标架构

推荐调用链如下：

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 接入当前生产主链。