From 3a03ec4cbd6e5eeba97f2f4a0a743c7981861563 Mon Sep 17 00:00:00 2001
From: kris <krisoso.com@gmail.com>
Date: Thu, 2 Apr 2026 19:09:41 +0800
Subject: [PATCH] docs: add claw-code integration strategy

---
 .../claw_code_integration_strategy_cn.md      | 301 ++++++++++++++++++
 1 file changed, 301 insertions(+)
 create mode 100644 docs/architecture/claw_code_integration_strategy_cn.md

diff --git a/docs/architecture/claw_code_integration_strategy_cn.md b/docs/architecture/claw_code_integration_strategy_cn.md
new file mode 100644
index 0000000..f719e80
--- /dev/null
+++ b/docs/architecture/claw_code_integration_strategy_cn.md
@@ -0,0 +1,301 @@
+# 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` 接入当前生产主链。