zclaw_openfang/docs/archive/ZCLAW_NEXT_EVOLUTION_STRATEGY.md

# ZCLAW 下一阶段系统演化对比分析与实施方案

> **文档日期**：2026-03-15  
> **适用对象**：项目负责人、架构负责人、客户端/后端/平台研发、测试与产品团队  
> **文档目的**：基于 OpenClaw / NanoClaw / ZeroClaw 等相关系统的公开资料与当前仓库现状，形成可执行的下一阶段演化决策依据  
> **说明**：用户需求中提到 `zeraoclaw`。基于公开可验证资料，当前最接近且资料完备的目标项目为 `ZeroClaw`，本报告按 `ZeroClaw` 纳入对比。如后续确认另有特定项目，可在同一分析框架下快速替换。
>
> **关联文档**：本文档聚焦**架构层**的全景对比与演化方案。关于 **Agent 智能层**（记忆系统、主动引擎、自我演化、上下文治理等）的深度差距分析与实施方案，请参阅 [`ZCLAW_AGENT_INTELLIGENCE_EVOLUTION.md`](./ZCLAW_AGENT_INTELLIGENCE_EVOLUTION.md)。

---

## 一、执行摘要

### 1.1 结论概览

当前项目已经具备继续独立演化的基础，但从仓库现状看，仍存在三类关键问题：

- **叙事未统一**
  - 仓库内同时存在 `OpenClaw 定制化`、`OpenFang 迁移`、`独立系统演化` 三套表述。
  - 这说明产品定位和架构边界还没有形成统一的外部口径与内部治理口径。

- **能力边界未完全内聚**
  - 当前 ZCLAW 的 UI、配置、Agent/Profile、Workflow/Team 等产品层能力已逐步形成，但运行时、协议、插件、配置模型仍然明显带有上游系统痕迹。
  - 若继续直接绑定单一上游，后续演化速度、可控性和品牌独立性都会受限。

- **下一阶段不宜继续做“上游壳层产品”**
  - 对比结果显示：
    - `OpenClaw` 的优势在于生态广、能力全、社区强。
    - `NanoClaw` 的优势在于小而可控、容器隔离、极易定制。
    - `ZeroClaw` 的优势在于性能、可移植性、部署效率与 trait 化扩展。
  - 对 ZCLAW 最优的路径不是简单“选边站队”，而是**形成自己的产品控制面与领域模型，在运行时层通过适配器吸收上游优势**。

### 1.2 推荐战略

推荐采用：**“ZCLAW Core 独立化 + Runtime Adapter 双层演化战略”**。

即：

- **上层**：沉淀 ZCLAW 自有的产品控制面
  - Agent/Persona/Profile
  - Session/Conversation/Workspace
  - Team/Workflow/Task/Approval
  - 插件市场、配置中心、审计与运营面板

- **下层**：将具体运行时封装为可替换适配器
  - `OpenClaw Adapter`
  - `ZeroClaw-style Adapter`
  - `NanoClaw-style Secure Sandbox Adapter`
  - 后续保留 `ZCLAW Native Runtime` 的演化空间

### 1.3 对业务与研发的直接意义

- **短期**：不打断现有交付，继续复用现有可用能力。
- **中期**：把“依赖某个上游框架”变成“兼容多个运行时后端”。
- **长期**：ZCLAW 可以作为独立产品和独立架构持续演进，不再被单一上游路线牵引。

---

## 二、当前项目基线判断

### 2.1 基于仓库现状的判断

从当前仓库文档可见：

- `README.md` 仍以 **OpenClaw 定制版** 为主叙述。
- `docs/architecture-v2.md` 描述的是 **OpenClaw + Tauri + 自定义插件** 的 v2 架构。
- `docs/SYSTEM_ANALYSIS.md` 又显示项目已经大量引入 **OpenFang 风格能力与 API 面**。
- 其他文档还包含对 OpenFang 迁移、ZeroClaw/NanoClaw/OpenClaw 生态分析等内容。

这说明项目技术上已经不再只是“某个上游的 UI 壳层”，而是在向一个更独立的产品系统演化；但**架构叙事、模块边界和对外定位还没有完全收敛**。

### 2.2 对“独立于上游框架”的工作定义

本报告对“独立演化”的定义不是“彻底断开所有上游依赖”，而是：

- ZCLAW 的**产品模型**由自己定义；
- ZCLAW 的**协议边界**由自己掌握；
- ZCLAW 的**插件与扩展接口**由自己维护；
- 上游运行时只作为**能力提供者**，而不再主导产品结构。

这一定义更现实，也更适合当前项目阶段。

---

## 三、调研范围与方法

### 3.1 调研对象

本次纳入对比的主要系统：

- **OpenClaw**
- **NanoClaw**
- **ZeroClaw**
- **ZCLAW 当前系统**（作为被决策对象）

### 3.2 调研维度

按用户要求，覆盖以下维度：

- 技术架构
- 核心功能
- 性能指标
- 扩展性
- 兼容性
- 安全与治理
- 社区支持
- 产品化与交付适配性

### 3.3 资料来源原则

优先使用公开可验证的一手或准一手资料：

- 官方 GitHub README / Releases / Contributors 页面
- 官方项目站点或官方文档页
- 当前仓库已有分析文档与架构文档

对于无法直接在线抓取的文档页，本报告只引用已能稳定复核的公开摘要，不扩展为未经验证的细节结论。

---

## 四、四个系统的定位概览

| 系统 | 核心定位 | 技术路线 | 适合场景 | 主要优势 | 主要代价 |
|------|----------|----------|----------|----------|----------|
| **OpenClaw** | 功能完备的个人 AI 助手与 Gateway 控制平面 | Node.js + TypeScript + 多端/多渠道生态 | 多渠道接入、完整能力复用、社区协作 | 生态成熟、通道丰富、能力全 | 复杂度高、资源占用较高 |
| **NanoClaw** | 轻量、可理解、容器隔离的个人 AI 助手 | 单 Node 进程 + Docker/Apple Container + Claude Agent SDK | 个人定制、快速 fork、强隔离 | 架构简单、容器隔离、改造门槛低 | 生态广度不足、对 Claude 体系依赖更强 |
| **ZeroClaw** | Rust 单二进制、强调高性能与可替换组件的自主 Agent 运行时 | Rust + trait 化模块 + binary-first | 边缘部署、低资源环境、性能敏感场景 | 低内存、快启动、跨平台部署轻量 | 生态成熟度仍弱于 OpenClaw |
| **ZCLAW 当前系统** | 已形成自有产品控制面雏形的桌面 Agent 平台 | Tauri + React + Store + 上游运行时耦合能力 | 中文化产品、桌面交互、企业/团队可视化 | UI/产品层较完整、定制能力强 | 上下游边界仍混杂、叙事未统一 |

---

## 五、多维深度对比分析

## 5.1 技术架构对比

### OpenClaw

架构核心是 **Gateway 作为统一控制平面**：

- 多消息渠道统一接入
- Agent、工具、事件、配置、会话统一通过 Gateway 暴露
- 支持 CLI、WebChat、移动节点、桌面端等多入口
- 适合作为“功能完备的基础设施层”被产品二次封装

优点是体系完整；缺点是当产品侧试图深度定制时，很容易在配置、协议、Agent 身份、运行时模型上被上游约束。

### NanoClaw

架构核心是 **极简 orchestrator + 容器沙箱**：

- 单 Node 进程承担调度、轮询、路由
- 每个群组/上下文在独立容器中运行
- SQLite + 文件系统 IPC + 每组独立 `CLAUDE.md`
- 功能通过 skill 注入，不走大而全框架

它代表一种“小系统哲学”：把复杂度压缩到最少，使单人团队也能真正理解和修改全栈行为。

### ZeroClaw

架构核心是 **Rust 单二进制 + trait 化能力抽象**：

- Provider / Channel / Memory / Tools 等能力可替换
- binary-first，部署成本低
- 天然更适合边缘环境、长期驻留进程、轻量平台扩展

它的启发在于：**ZCLAW 后续应该把“运行时能力”变成接口，而不是直接埋在产品层逻辑里。**

### 对 ZCLAW 的启示

最适合 ZCLAW 的不是复制任何一方，而是组合三者优点：

- 学 OpenClaw 的 **控制平面与生态广度**
- 学 NanoClaw 的 **安全隔离与可理解性**
- 学 ZeroClaw 的 **适配器化和低负载运行时设计**

---

## 5.2 核心功能对比

| 维度 | OpenClaw | NanoClaw | ZeroClaw | 对 ZCLAW 的启示 |
|------|----------|----------|----------|------------------|
| **多渠道接入** | 强，覆盖广 | 中，靠 skills 扩展 | 中，强调可插拔 | ZCLAW 应保留渠道抽象层，不把单一 IM 深绑在 UI 上 |
| **会话与消息控制平面** | 强 | 中 | 中到强 | ZCLAW 要沉淀自己的 `Conversation/Session/Run` 模型 |
| **工具调用** | 强 | 中 | 中到强 | 工具事件流需要统一成 ZCLAW 内部协议 |
| **技能系统** | 强，生态成熟 | 有，但偏技能驱动定制 | 可扩展，但生态尚小 | ZCLAW 需要自己的插件/技能清单与兼容层 |
| **团队/多 Agent 协作** | 有基础能力 | 有 Agent Swarms | 有自主化定位 | ZCLAW 可将多 Agent 协作作为核心差异化方向 |
| **工作流/定时任务** | 支持 | 支持 scheduled tasks | 支持自治流程 | ZCLAW 应将工作流从 UI 功能提升为平台能力 |
| **桌面产品化** | 非核心主轴 | 非核心主轴 | 非核心主轴 | 这是 ZCLAW 的主战场，应继续扩大优势 |

### 判断

- 如果目标是**尽快做全功能产品**，OpenClaw 价值最高。
- 如果目标是**单人/小团队快速安全定制**，NanoClaw 的方法更高效。
- 如果目标是**高性能、可替换、长期独立演化**，ZeroClaw 的路线更先进。

ZCLAW 应把自己的主轴明确为：**产品化桌面控制面 + 中文场景 + 团队协作 + 可替换运行时**。

---

## 5.3 性能指标对比

### 可验证的公开信息

- **OpenClaw**
  - 运行依赖 `Node.js >= 22`
  - 社区规模极大，功能体系最重
  - 从 ZeroClaw 官方 benchmark 描述中可见，OpenClaw 需要额外 Node 运行时开销，内存画像明显高于 Rust 单二进制方案

- **ZeroClaw**
  - 官方 benchmark 示例给出：
    - release binary size 约 `8.8MB`
    - `zeroclaw --help` 峰值内存约 `3.9MB`
    - `zeroclaw status` 峰值内存约 `4.1MB`
    - 启动时延在 `0.01s ~ 0.02s` 量级

- **NanoClaw**
  - 官方强调单进程 orchestrator，但真实执行依赖 Docker/Apple Container
  - 因容器与 Claude Agent SDK 参与运行，整体资源画像通常不会像 Rust 单二进制那样轻
  - 其优势更多体现在“可控安全边界”而非极致性能

### 对 ZCLAW 的结论

ZCLAW 若继续强化桌面端与 7x24 运行能力，必须尽快解决两个问题：

- **产品层与运行时层的资源耦合**
- **桌面壳、Agent 运行时、浏览器/工具进程之间的生命周期治理**

建议把性能目标分两层定义：

- **产品性能目标**
  - 启动可交互时间
  - 首屏渲染时间
  - 会话恢复时间
  - 事件流显示延迟

- **运行时性能目标**
  - 空闲内存
  - 单任务峰值内存
  - 冷启动时延
  - 工具调用平均延迟

---

## 5.4 扩展性对比

### OpenClaw

扩展生态最强，适合“接入更多能力”；但产品二开时要承担：

- 上游协议变化成本
- 配置模型变化成本
- 插件语义变化成本

### NanoClaw

扩展方式偏向“改自己的 fork”，非常适合高度个性化，但对平台型产品不够友好。

### ZeroClaw

扩展方式偏向“接口替换与模块替换”，适合做平台底座。

### 对 ZCLAW 的建议

ZCLAW 的扩展性应该分三层设计：

- **L1：UI Extension**
  - 面板、视图、表单、工作台插件

- **L2：Domain Extension**
  - AgentProfile、ToolPolicy、WorkflowStep、ChannelBinding、ApprovalRule

- **L3：Runtime Adapter Extension**
  - Channel Adapter
  - Model Adapter
  - Tool Adapter
  - Agent Runtime Adapter
  - Memory Adapter

只有做到这三层分离，ZCLAW 才能真正脱离“上游 API 变动即牵一发而动全身”的状态。

---

## 5.5 兼容性对比

| 维度 | OpenClaw | NanoClaw | ZeroClaw | 对 ZCLAW 的建议 |
|------|----------|----------|----------|------------------|
| **与现有 ZCLAW 文档/代码语义贴近度** | 高 | 中 | 中 | 短期最适合作为兼容基线 |
| **桌面端交互兼容性** | 高 | 中 | 中 | 通过中间协议层抽象 |
| **技能/配置迁移难度** | 低到中 | 中 | 中 | 需要建立 `ZCLAW Canonical Config` |
| **二次开发可控性** | 中 | 高 | 高 | 中长期应逐步从“兼容”转向“主导” |

### 关键判断

下一阶段不应继续让 UI 直接理解上游协议细节，而应改为：

- UI 只理解 ZCLAW 自己的协议模型
- 上游协议转换在 adapter 层完成

这将显著降低未来兼容多个运行时的成本。

---

## 5.6 安全与治理对比

### OpenClaw

安全模型强调：

- pairing
- allowlist
- gateway auth
- loopback / tailscale 暴露治理

更适合“真实消息渠道 + 本地网关”的安全边界管理。

### NanoClaw

安全模型强调：

- 容器隔离
- 显式挂载目录
- 每组独立执行环境

优点是安全直观，容易让团队达成共识。

### ZeroClaw

安全模型强调：

- 低权限默认值
- allowlist
- workspace scoping
- secret handling
- sandbox controls

更接近“可治理的运行时内核”。

### 对 ZCLAW 的建议

ZCLAW 必须形成自己的安全治理分层：

- **产品层**：审批、权限提示、可视化审计、风险提示
- **策略层**：路径范围、工具白名单、渠道白名单、模型策略
- **运行时层**：容器/子进程/沙箱/凭证隔离

也就是说，未来 ZCLAW 不应只展示安全状态，而要**拥有自己的安全策略编排能力**。

---

## 5.7 社区支持对比

### OpenClaw

依据官方 GitHub 页面：

- Stars：约 `314k`
- Forks：约 `60k`
- Contributors：`1,217`
- Releases：`68`

这是目前三者中社区最强、成熟度最高的体系。

### NanoClaw

依据官方 GitHub 页面：

- Stars：约 `23k`
- Forks：约 `5.6k`
- Releases/Tags：公开可见较少
- 社区组织方式更偏 Discord + 个人定制 fork 模式

说明其讨论热度不低，但工程治理和生态标准化程度相对弱于 OpenClaw。

### ZeroClaw

依据官方 GitHub 页面：

- Stars：约 `27.1k`
- Forks：约 `3.6k`
- Releases：`46`
- 官方站点与仓库强调持续更新和轻量架构路线

说明它正在形成稳定社区，但仍处于“快速成长、尚未成为默认生态中心”的阶段。

### 对 ZCLAW 的启示

如果 ZCLAW 想作为独立系统持续演化，就必须尽早做两件事：

- **建立自己的文档与架构标准**
- **建立自己的插件/技能/API 兼容策略**

否则项目虽然代码独立，但心智上仍是“上游分支产品”。

---

## 六、综合判断：ZCLAW 应该吸收什么，不吸收什么

## 6.1 应该吸收的能力

### 来自 OpenClaw

- 多渠道控制平面理念
- 会话/消息/工具事件统一流模型
- 丰富生态与外部兼容思维
- 产品可用性优先的设计方式

### 来自 NanoClaw

- 容器隔离优先的安全思路
- 小而清晰的模块边界
- “功能通过技能注入而不是不断堆框架”的治理方式
- 面向 fork/定制的可理解性

### 来自 ZeroClaw

- trait / adapter 风格的可替换运行时设计
- binary-first / low-overhead 的交付思想
- 跨平台轻量部署能力
- 更清晰的系统内核与接口边界

## 6.2 不建议直接照搬的部分

- **不建议直接把 ZCLAW 继续做成单一上游的深度 UI 壳层**
- **不建议完全走 NanoClaw 式“所有差异化都通过 fork 改代码”的路线**
- **不建议在当前阶段就彻底重写原有可用能力，导致交付停滞**

## 6.3 推荐的目标态

推荐目标态为：

> **ZCLAW = 独立产品控制面 + 统一领域模型 + 可插拔运行时内核适配层 + 中文化协作场景能力集**

---

## 七、专题头脑风暴会议方案

## 7.1 会议目标

围绕“ZCLAW 下一阶段如何独立演化”形成团队共识，输出：

- 下一阶段主战略
- 目标架构形态
- 首批优先能力清单
- 风险清单与约束条件
- 90 天执行路线

## 7.2 建议参会角色

- **项目负责人 / 架构负责人**
- **桌面端负责人**
- **前端负责人**
- **后端/运行时负责人**
- **插件/工具链负责人**
- **测试/质量负责人**
- **产品负责人**
- **若有条件，邀请 1 名熟悉上游生态的顾问型开发者**

## 7.3 会前准备材料

要求参会者提前阅读：

- 本文档
- `docs/architecture-v2.md`
- `docs/SYSTEM_ANALYSIS.md`
- 当前 `README.md`

并在会前回答三件事：

- 当前系统最不想再被哪个上游约束？
- 当前系统最值得保留的核心资产是什么？
- 下一阶段最怕失去的交付能力是什么？

## 7.4 会议议程（建议 2.5 小时）

### 第一阶段：统一认知（20 分钟）

- 当前项目到底是不是独立系统？
- 当前哪些模块仍深度依赖上游？
- 当前哪些能力已经形成 ZCLAW 自有资产？

### 第二阶段：三条路线讨论（40 分钟）

讨论三种备选路线：

- **路线 A：继续深度绑定 OpenClaw 生态**
- **路线 B：向 ZeroClaw/NanoClaw 风格的轻量内核迁移**
- **路线 C：构建 ZCLAW Core + Adapter 的独立架构**

每条路线必须回答：

- 带来什么收益
- 会引入什么代价
- 三个月内最可能失败在哪里

### 第三阶段：能力优先级排序（35 分钟）

把候选能力放进四象限：

- 高价值 / 低成本
- 高价值 / 高成本
- 低价值 / 低成本
- 低价值 / 高成本

重点筛出下一阶段的：

- 必做项
- 应做项
- 可延后项
- 不做项

### 第四阶段：目标架构与边界划分（35 分钟）

讨论并确认：

- 哪些是 ZCLAW Core
- 哪些属于 Adapter
- 哪些属于 Plugin/Skill Extension
- 哪些属于可选上游兼容能力

### 第五阶段：决策与收尾（20 分钟）

现场形成：

- 一页战略结论
- 一张目标架构图
- 一份 90 天路线图
- 一份风险与前提清单

## 7.5 会议产出模板

建议会后统一使用以下模板沉淀：

### 产出 A：战略结论卡

- 我们的主路线是什么？
- 为什么不是另外两条路线？
- 接下来 90 天的成败标准是什么？

### 产出 B：架构边界卡

- ZCLAW Core 模块
- Adapter 模块
- 可复用上游能力
- 禁止继续耦合的区域

### 产出 C：优先级清单

- P0：必须完成
- P1：强烈建议完成
- P2：可延后
- P3：明确不做

### 产出 D：风险台账

- 风险描述
- 触发条件
- 影响范围
- 监测指标
- 应对策略

---

## 八、下一阶段详细实施方案

## 8.1 备选技术路线

### 路线 A：继续以 OpenClaw 为单一主干

**优点**：

- 改造成本最低
- 社区与生态最好借力
- 短期交付最稳

**缺点**：

- 品牌与架构独立性不足
- 上游变化会持续传导到产品层
- 难以同时吸收 NanoClaw/ZeroClaw 风格能力

### 路线 B：转向轻量运行时路线

**优点**：

- 性能、部署、资源占用明显改善
- 易于塑造独立技术品牌

**缺点**：

- 迁移成本高
- 短期内功能回退风险大
- 团队需要重构大量兼容层

### 路线 C：ZCLAW Core + Runtime Adapter（推荐）

**优点**：

- 兼顾短期交付与长期独立演化
- 能吸收多个上游的能力优势
- 将未来替换运行时的成本前置为架构治理问题，而不是产品灾难

**缺点**：

- 前期需要投入抽象层建设
- 对架构治理和接口定义要求更高

## 8.2 推荐实施路线

推荐采用 **路线 C**，并按“三层五阶段”推进。

### 三层结构

#### 第一层：ZCLAW Product Layer

负责：

- 桌面工作台
- 聊天与会话体验
- Agent/Profile 管理
- Team / Workflow / Approval / Settings
- 统计、审计、诊断、运维视图

#### 第二层：ZCLAW Domain Core

负责：

- Canonical Agent Model
- Canonical Conversation / Session / Run Model
- Tool Event Model
- Channel Binding Model
- Workflow / Task / Approval Model
- Policy / Audit / Capability Descriptor Model

#### 第三层：Runtime Adapter Layer

负责：

- OpenClaw Adapter
- ZeroClaw-style Adapter
- NanoClaw-style Sandbox Adapter
- 后续 Native Runtime Adapter

---

## 九、分阶段执行计划

## 9.1 Phase 0：统一叙事与架构边界（1-2 周）

### 目标

解决当前文档、定位、模块边界混杂的问题，为后续技术演化扫清治理障碍。

### 关键任务

- 统一 README、架构文档、路线图文档口径
- 输出一份正式 ADR：`ZCLAW 是否继续作为单一上游壳层产品` 
- 画出当前系统的真实分层图
- 标记所有直接理解上游协议的 UI/Store/Client 模块

### 交付物

- `ZCLAW Architecture Positioning ADR`
- 最新版系统边界图
- 耦合点清单

### 验收标准

- 团队对“ZCLAW 是什么”表述一致
- 能明确说出哪些模块是 Core，哪些模块是 Adapter 候选

## 9.2 Phase 1：领域模型标准化（2-3 周）

### 目标

建立 ZCLAW 自己的 canonical domain model。

### 关键任务

- 定义统一的 AgentProfile schema
- 定义统一的 Session / Conversation / Run schema
- 定义统一的 ToolEvent / StreamEvent schema
- 定义统一的 Workflow / Task / Approval schema
- 统一配置模型，形成 `ZCLAW Canonical Config`

### 交付物

- `types/` 或 `schema/` 下的统一模型
- 协议映射说明文档
- 配置迁移与兼容规则

### 验收标准

- UI 不再直接依赖上游原始字段名
- 任一运行时返回的数据都能映射到统一领域模型

## 9.3 Phase 2：Adapter 层落地（3-4 周）

### 目标

把现有直连逻辑收口到适配器层。

### 关键任务

- 建立 `RuntimeAdapter` 接口
- 首先实现 `OpenClawAdapter`
- 将当前 gateway client / store 中的协议特化逻辑迁出
- 建立 adapter contract tests
- 对连接、流式输出、工具调用、配置读写、会话管理做统一抽象

### 交付物

- `adapters/runtime/*`
- 合同测试
- 适配器错误码映射表

### 验收标准

- Product Layer 不再直接解析上游特有 payload
- 新增第二个 adapter 时无需改 UI 主逻辑

## 9.4 Phase 3：独立平台能力增强（4-6 周）

### 目标

把 ZCLAW 的独立价值从“桌面 UI”升级为“产品控制面”。

### 候选优先功能

- Team 协作编排
- Workflow 可视化与执行追踪
- 审批中心
- Agent 资产管理（角色、场景、能力画像）
- 安全策略面板
- 运行诊断与审计中心

### 交付物

- 可演示的独立平台特性
- 与上游无关的用户价值闭环

### 验收标准

- 至少 3 项核心能力可在不强调上游品牌的前提下独立展示

## 9.5 Phase 4：安全与运行时治理升级（3-4 周）

### 目标

吸收 NanoClaw/ZeroClaw 的安全与运行时思路。

### 关键任务

- 引入工具白名单 / 路径作用域 / 渠道白名单
- 定义容器执行、子进程执行、宿主执行三级策略
- 设计凭证隔离方案
- 补充审批、审计、风险提示机制
- 建立性能基准测试脚本

### 交付物

- `Security Policy Model`
- `Execution Sandbox Policy`
- 基线 benchmark 报告

### 验收标准

- 能对每类工具执行给出明确策略归属
- 能对外说明系统的安全边界和治理路径

## 9.6 Phase 5：产品化与生态化（4-6 周）

### 目标

形成真正可持续演化的产品与生态接口。

### 关键任务

- 统一插件 / 技能扩展规范
- 建立扩展清单与安装管理
- 输出 SDK 或最小开发指南
- 完善打包、升级、诊断与迁移流程
- 形成可灰度发布的版本策略

### 交付物

- 插件开发指南
- 版本发布规范
- 诊断与迁移工具

### 验收标准

- 第三方或内部团队可以按统一规则扩展 ZCLAW
- 版本升级不再高度依赖人工排障

---

## 十、技术选型建议

## 10.1 总体原则

- **产品层稳定优先**：Tauri + React 的桌面产品层继续保留。
- **领域模型先行**：先统一 schema，再做替换和迁移。
- **兼容优先于重写**：短期不要大爆炸式重写运行时。
- **安全能力前移**：把安全策略设计到中台层，而不是留到发布前补救。

## 10.2 关键技术建议

### 前端与桌面层

- 继续使用 `Tauri + React + Zustand/拆分 Store`
- 逐步把 Store 从“协议状态容器”改成“领域状态容器”
- 将连接状态、Agent 状态、Workflow 状态、Approval 状态解耦

### 协议与模型层

- 推荐引入统一 schema 定义方式
  - 例如 TypeScript schema + runtime validation
- 建立内部事件总线模型
  - `run.started`
  - `run.delta`
  - `tool.started`
  - `tool.completed`
  - `approval.required`
  - `session.updated`

### 运行时层

- 短期保留现有兼容运行时
- 中期抽象 `RuntimeAdapter`
- 长期预留 native runtime 空间

### 安全层

- 审批模型、路径模型、工具策略模型、凭证模型分离
- 将安全策略做成可视配置，但底层仍保留强约束默认值

---

## 十一、资源需求与组织建议

## 11.1 建议团队编制

最小建议编制：

- **1 名架构/技术负责人**
- **1 名桌面前端负责人**
- **1 名运行时/后端负责人**
- **1 名平台/插件负责人**
- **1 名测试/质量负责人**
- **0.5 名产品/项目协调角色**

## 11.2 角色分工建议

- **架构负责人**
  - 定义领域模型、Adapter 边界、ADR

- **前端负责人**
  - 收口 UI 对上游协议的直接理解
  - 建立产品层统一状态模型

- **运行时负责人**
  - 适配器、流式事件、执行治理、性能基线

- **平台负责人**
  - 插件、配置、技能/扩展规范

- **测试负责人**
  - 合同测试、回归测试、性能测试、安装/升级测试

---

## 十二、时间节点建议（90 天版本）

| 时间段 | 目标 | 核心产出 |
|--------|------|----------|
| 第 1-2 周 | 统一叙事与边界 | ADR、系统边界图、耦合点清单 |
| 第 3-5 周 | 统一领域模型 | Canonical schema、配置模型、事件模型 |
| 第 6-9 周 | Adapter 层落地 | RuntimeAdapter、OpenClawAdapter、合同测试 |
| 第 10-13 周 | 平台能力增强 | Workflow/Approval/Team 等独立能力强化 |
| 第 14-16 周 | 安全与产品化 | 安全策略、基准测试、插件规范、发布策略 |

---

## 十三、预期成果

如果按推荐路线推进，预期可获得以下成果：

### 13.1 技术成果

- ZCLAW 不再被视为单一上游的桌面壳层
- UI 与运行时解耦
- 具备多运行时兼容能力
- 形成自己的 canonical domain model
- 安全策略、审计策略、扩展策略可治理

### 13.2 产品成果

- 对外叙事更稳定
- 团队可围绕独立能力持续扩展
- 可更自然地支持企业/团队协作场景
- 后续能构建插件市场、行业模板、工作流模板等更高层能力

### 13.3 组织成果

- 减少“上游变更驱动项目节奏”的被动状态
- 让架构决策从“修兼容”转为“做平台”

---

## 十四、风险与缓解措施

| 风险 | 描述 | 影响 | 缓解措施 |
|------|------|------|----------|
| **抽象过度** | 过早设计过多 adapter/interface | 开发变慢 | 先只抽象已验证的最小公共集 |
| **交付中断** | 大规模重构影响现有功能 | 用户体验下降 | 采用分层替换，保持旧接口短期兼容 |
| **文档与代码再度分离** | 叙事更新了，代码边界没跟上 | 决策失真 | 每阶段必须同步更新 ADR 与边界图 |
| **安全治理落空** | 只做 UI，不做底层策略 | 风险不可控 | 安全策略与执行策略必须双落地 |
| **多上游兼容失控** | 兼容目标过多导致复杂度爆炸 | 架构失稳 | 先实现单 adapter，第二个 adapter 仅做验证，不追求全量支持 |

---

## 十五、建议的近期优先动作（本周即可启动）

### P0

- 召开专题头脑风暴会议并完成路线确认
- 输出正式 ADR：确认是否采用 `ZCLAW Core + Runtime Adapter`
- 梳理当前直接依赖上游协议的模块列表

### P1

- 建立 `Canonical Agent / Session / Stream Event` 草案
- 明确 `README / architecture / system analysis` 三份文档的统一口径
- 定义 adapter 接口最小集合

### P2

- 选择一个现有关键流（例如聊天流式回复）作为 adapter 化试点
- 建立最小合同测试样例

---

## 十六、最终建议

**结论很明确：**

ZCLAW 下一阶段最重要的工作，不是继续在某个上游上“加功能”，而是**完成从“上游定制壳层”到“独立产品平台”的架构转身**。

具体建议如下：

- **战略上**：选择 `ZCLAW Core + Runtime Adapter` 作为主路线。
- **组织上**：通过专题头脑风暴会议统一路线与边界。
- **实施上**：优先做叙事统一、领域模型统一、适配器收口三件事。
- **价值上**：把 OpenClaw 的生态、NanoClaw 的隔离思路、ZeroClaw 的轻量架构，吸收到 ZCLAW 自己的产品体系中。

如果这一轮推进顺利，ZCLAW 将不再只是“基于某个框架的定制版”，而会成为一个**能够独立定义产品、独立定义扩展模型、独立定义演化节奏**的系统。

---

## 十七、参考依据

### 当前仓库文档

- `README.md`
- `docs/architecture-v2.md`
- `docs/SYSTEM_ANALYSIS.md`
- `docs/openclaw-to-openfang-migration-brainstorm.md`
- `docs/claw-ecosystem-deep-dive-report.md`

### 公开资料（本次已核验部分）

- OpenClaw 官方仓库：`https://github.com/openclaw/openclaw`
- OpenClaw 官方文档入口：`https://docs.openclaw.ai`
- NanoClaw 官方站点：`https://nanoclaw.dev/`
- NanoClaw 官方仓库：`https://github.com/qwibitai/nanoclaw`
- ZeroClaw 官方站点：`https://zeroclaw.bot/`
- ZeroClaw 官方仓库：`https://github.com/zeroclaw-labs/zeroclaw`

> 注：部分官方文档页在本次抓取过程中存在超时，因此文中对 OpenClaw 官方文档细节的引用，优先采用其官方 GitHub README 与可稳定访问的官方摘要信息，不对未成功直读页面做超出摘要范围的延展解释。