krisolo/boss
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity
Files
codex/wechat-native-ui-rollback
boss/docs/architecture/claw_code_integration_strategy_cn.md
kris 3a03ec4cbd docs: add claw-code integration strategy
2026-04-02 19:09:41 +08:00

8.1 KiB
Raw Permalink Blame History

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