# claw-code 融合策略（可升级外部后端方案）

这份文档定义 `claw-code` 与 Boss 的推荐融合方式。目标不是把 `claw-code` 代码直接写死进 Boss，而是把它抽成一个可替换、可升级、可回退的执行后端能力层，使 Boss 后续可以持续吸收 `claw-code` 的 runtime 演进，而不破坏现有 Web、Android、多租户和会话业务主链。

## 1. 结论

采用方案二：**外部后端适配层**。

具体含义：

- Boss 不直接依赖 `claw-code` 的内部目录结构、状态文件格式或 CLI 交互层。
- Boss 只依赖一组由自己定义的稳定接口：
  - `ExecutionBackend`
  - `SessionRuntime`
  - `PermissionPolicy`
  - `ToolRegistry`
  - `PromptAssembler`
  - `RemoteRuntimeAdapter`
- `claw-code` 作为这些接口的一种实现，通过 `ClawBackendAdapter` 接入。
- Boss 的产品层保持不变：
  - 多租户
  - 登录与账号体系
  - 会话/群聊/审批
  - 设备导入
  - Web 与 Android 页面
  - 账本、投影与业务状态

## 2. 为什么不能写死集成

`claw-code` 当前仍处于快速迭代期，最近更新重点已经明显转向：

- Rust runtime
- OAuth 登录
- MCP orchestration
- tool permissions
- agent delegation
- long-session compaction / anti-stall

如果把它直接 vendoring 到 Boss 仓库里：

- 后续升级成本会快速变高
- Boss 会被上游内部重构牵着走
- 产品层与执行层耦合过深
- 出现问题时很难判断是 Boss 业务问题，还是上游 runtime 变化导致

Boss 当前已经有一条复杂但真实的产品主链：

- Web
- Android
- 多设备、多线程、多群聊
- 主 Agent
- 审批流
- 设备导入
- 提示词与记忆

这条主链不适合被外部 runtime 结构反向塑形。

## 3. 融合目标

引入 `claw-code` 的目的不是替换 Boss，而是补强 Boss 目前较弱的执行底座能力：

1. 更清晰的 runtime contract
2. 更独立的 tool registry
3. 更稳定的 permission policy
4. 更明确的 remote runtime adapter
5. 更可升级的后端选择机制

简化理解：

- Boss 继续做产品与业务壳
- `claw-code` 提供可替换的执行内核能力

## 4. 边界划分

### 4.1 Boss 继续负责的部分

- 用户、账号、多租户
- Web 和 Android 前台
- 会话模型
- 项目归档与线程下钻
- 群聊与审批
- 设备导入
- 提示词与记忆的数据归属
- 文件账本与聚合投影
- 业务事件流和 OTA

### 4.2 claw-code 适合承载的部分

- runtime / session orchestration
- tool execution
- permission enforcement
- remote runtime abstraction
- 可恢复的执行状态
- 未来更强的 MCP / plugin / tool delegation 能力

### 4.3 明确不做的事

- 不把 `claw-code` 的 CLI 直接暴露给 Boss 最终用户
- 不把 Boss 会话页改造成 CLI 运行时投影
- 不让 Boss 业务逻辑直接依赖 `claw-code` 私有状态文件
- 不让 Android 或 Web 前台直接理解 `claw-code` 内部概念

## 5. 推荐架构

### 5.1 新增稳定抽象层

Boss 内部新增一层执行接口，不直接面向具体实现：

- `ExecutionBackend`
  - 统一描述“谁来执行一次主 Agent / 线程任务”
- `SessionRuntime`
  - 统一描述“如何创建、恢复、终止、观察一次运行态会话”
- `PermissionPolicy`
  - 统一描述“当前任务允许哪些工具、哪些行为、哪些审批前置条件”
- `ToolRegistry`
  - 统一描述“Boss 可声明和可下发的工具能力”
- `PromptAssembler`
  - 统一组装：
    - 管理员全局主提示词
    - 用户提示词
    - 当前对话附加提示词
    - 用户记忆
    - 项目记忆
    - 当前运行时上下文
- `RemoteRuntimeAdapter`
  - 统一接设备上的远程执行能力

### 5.2 新增具体适配器

Boss 后续逐步形成这些实现：

- `MasterCodexNodeBackend`
- `OpenAIBackend`
- `AliyunQwenBackend`
- `ClawBackendAdapter`
- 后续如需要，也可以补：
  - `OmxTeamBackendAdapter`

### 5.3 调用链

Boss 业务层不直接调 `claw-code`，而是走：

`Boss 业务逻辑 -> ExecutionBackend 选择器 -> ClawBackendAdapter -> claw runtime`

这样后续上游变化时，只需要改适配器，而不需要重写会话、群聊、审批、导入和 UI 逻辑。

## 6. 先接什么，后接什么

### 第一阶段：只接抽象，不接真实 claw runtime

目标：

- 先把 Boss 当前执行底座抽成稳定接口
- 不改变现有 `local-agent -> codex exec resume` 主链

输出：

- `ExecutionBackend`
- `PermissionPolicy`
- `PromptAssembler`
- `RemoteRuntimeAdapter`

这样做的意义：

- 先把 Boss 内部结构理顺
- 避免后面直接接 `claw-code` 时，边接边重构导致主链抖动

### 第二阶段：做 `ClawBackendAdapter`

目标：

- 把 `claw-code` 接成一个可选后端
- 仅用于受控实验路径，不切主默认链

建议先支持的能力：

- session create / resume
- tool permission handoff
- remote runtime selection
- result normalization

这阶段的定位是：

- 可运行
- 可验证
- 可对比现有 Codex backend

而不是立即替代默认生产主链

### 第三阶段：按能力逐项放量

只有在这些能力验证稳定后，才逐步提升 `claw-code` 的使用范围：

- 单线程任务执行
- 主 Agent 某些特定模式
- 长任务 / 可恢复执行
- 更复杂的工具代理

群聊审批、多租户关键链路、设备导入主链，默认不要第一时间切到 `claw-code`。

## 7. 升级策略

这是本方案最关键的一部分。

### 7.1 版本跟踪原则

Boss 不跟踪 `claw-code` 的“任意最新 main”，而是：

- 定期观察上游更新
- 做版本评估
- 选择一个明确 checkpoint
- 更新适配器
- 通过 Boss 自己的验证矩阵后再升级

### 7.2 升级入口

建议新增一份长期维护文档或记录源，用于持续跟踪：

- 上游最新提交方向
- 对 Boss 有价值的新能力
- 是否影响 adapter contract
- 是否需要升级

### 7.3 升级流程

每次升级 `claw-code` 时，固定执行：

1. 拉取上游新代码
2. 评估 runtime / permissions / tools / session 契约变化
3. 对照 `ClawBackendAdapter` 检查 breakage
4. 更新适配器
5. 跑 Boss 现有验证矩阵：
   - 主 Agent 单聊
   - 普通线程单聊
   - 群聊 dispatch
   - approval_required
   - 设备导入
   - 提示词与记忆
6. 只在验证通过后提升可用范围

## 8. 风险与约束

### 8.1 技术风险

- `claw-code` 仍在快速变化，接口稳定性不能假设
- Rust runtime 最终结构可能继续调整
- OAuth / MCP / tool permission 能力可能持续改名或重组

### 8.2 产品风险

- 如果让前台直接理解 `claw-code` 语义，会破坏 Boss 当前产品模型
- 如果默认主链切换过早，可能影响：
  - 主 Agent 对话
  - 群聊审批
  - 设备导入
  - 多租户隔离

### 8.3 维护风险

- vendoring/fork 会让 Boss 承担双倍维护成本
- 直接写死集成会让未来每次上游升级都变成“重构 Boss”

## 9. 当前建议

当前建议非常明确：

1. 采用方案二：外部后端适配层
2. 先重构 Boss 自己的执行抽象层
3. 再实现 `ClawBackendAdapter`
4. 初期只作为可选 backend，不接默认生产主链
5. 建立上游版本评估和适配升级流程

## 10. 验收标准

只有满足下面条件，才能认为这条融合策略落地正确：

1. Boss 产品层不直接依赖 `claw-code` 私有目录结构
2. 替换或升级 `claw-code` 时，只需要主要修改 adapter 层
3. 不影响现有：
   - 主 Agent 单聊
   - 普通线程单聊
   - 群聊审批
   - 设备导入
   - 提示词与记忆
4. `claw-code` 可以按 checkpoint 升级，而不是写死某个历史版本
5. Boss 保持自己的产品节奏，不被外部 runtime 主导

## 11. 下一步

这份文档之后，推荐直接进入下一份实现设计：

- 主题：`Boss 执行底座抽象层重构`

优先拆成 4 个子任务：

1. 定义 `ExecutionBackend` 与后端选择器
2. 定义 `PermissionPolicy` 与 `ToolRegistry`
3. 抽离 `PromptAssembler` 与 `RemoteRuntimeAdapter`
4. 实现 `ClawBackendAdapter` 的最小可运行版本

在这 4 个子任务完成前，不建议直接把 `claw-code` 接入当前生产主链。