302 lines
8.1 KiB
Markdown
302 lines
8.1 KiB
Markdown
# 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` 接入当前生产主链。
|