zclaw_openfang/docs/plans/2026-03-12-zclaw-delivery-execution-plan.md

ZCLAW 交付执行计划（2026-03-12）

1. 计划目标

本计划的目标不是继续做“功能堆叠”，而是把当前仓库推进到可安装、可启动、可连接、可对话、可配置、可验证的可交付状态。

当前对“完整可用 ZCLAW”的定义如下：

• 用户能够在本机启动 ZCLAW 桌面应用
• 用户安装 ZCLAW 时，OpenClaw 运行时已经随包提供，而不是要求用户另行安装
• 桌面应用能够引导并管理随 ZCLAW 一起分发的本地 OpenClaw Gateway
• 前端能够稳定连接 Gateway，并完成基础握手与鉴权
• 用户能够创建、编辑、切换 Agent（Clone）
• 用户能够发起真实对话并收到流式回复
• 关键设置页不再只是静态占位，而是尽量接到真实后端能力
• 有一套清晰的验收与收尾流程，支持阶段性提交与后续发布

---

2. 当前基线

2.1 已完成的关键能力

• Gateway 握手参数已修正，能够兼容 OpenClaw 2026.3.11
• Token 鉴权已接入前端连接流程
• zclaw-ui 插件可被 Gateway 正常加载
• Agent 的创建、编辑、保存链路已打通
• scripts/setup.ts 已可在已有 ~/.openclaw/openclaw.json 时非破坏性合并插件与 skills 路径
• 自定义插件 manifest/package id 对齐问题已修复

2.2 当前仍阻塞交付的核心问题

按交付优先级排序，当前最关键的缺口为：

1. 桌面端尚未真正接管 Gateway 生命周期

   • src/gateway/manager.ts 已存在，但未被 Tauri 壳使用
   • desktop/src-tauri/src/lib.rs 仍是默认模板
   • 当前产品更像“前端连接外部 Gateway”，还不是“完整桌面应用”

2. 当前仍默认依赖用户独立安装 OpenClaw

   • 这与最终产品目标不一致
   • 最终必须做到：安装 ZCLAW 后即可直接使用 OpenClaw 能力
   • 因此现阶段的 CLI/PATH 依赖只能作为开发期和过渡期方案

3. 真实桌面链路缺少本地运行闭环验证

   • 需要验证 Tauri 内从启动 Gateway 到连接、到拉数据、到发消息的完整过程

4. 设置体系中仍有若干页面/按钮处于占位状态

   • 部分页面已有 UI 但尚未连接真实能力
   • 会影响“可用”判断，尤其是用户首次体验

5. 交付收尾缺少固定验收流程

   • 需要统一 smoke test、安装前检查、文档更新、阶段提交点

---

3. 总体推进策略

3.1 核心原则

• 先打通闭环，再做扩展：优先修复阻塞真实使用的能力缺口，而不是继续加功能
• 优先最短交付路径：优先复用 OpenClaw 现有 CLI/service 能力，而不是一开始就做完整 sidecar 架构
• 最终必须内置 OpenClaw：开发阶段允许复用系统已安装的 OpenClaw，但交付阶段必须改为随 ZCLAW 一起分发和托管
• 浏览器模式不回退：新增 Tauri 能力必须有运行时保护，不影响现有浏览器预览/开发体验
• 阶段可提交：每个阶段都有独立验收标准，达到后可形成 clean checkpoint

3.2 本轮优先级

• P0：Tauri 桌面壳接入本地 Gateway 生命周期管理
• P0：完成真实桌面端基础闭环验证
• P0：确定并落地“ZCLAW 安装即内置 OpenClaw”的分发方案
• P1：补齐最影响可用性的设置页占位项
• P1：形成交付前 smoke checklist 和文档更新
• P2：补测试、清理遗留代码、准备打包发布

---

4. 分阶段执行计划

Phase A：桌面端本地 Gateway 生命周期管理（当前最高优先级）

A.1 目标

让 ZCLAW 桌面应用在 Tauri 环境下具备对本地 OpenClaw Gateway 的基础管理能力：

• 查询本地 Gateway 状态
• 启动本地 Gateway
• 停止本地 Gateway
• 重启本地 Gateway
• 在前端展示本地状态，并与现有 WebSocket 连接状态区分开

A.2 实现策略

优先采用Tauri Rust 命令封装 OpenClaw CLI 的方式，而不是直接引入完整 sidecar：

• Rust 侧封装以下命令：
  • openclaw gateway status --json
  • openclaw gateway start --json
  • openclaw gateway stop --json
  • openclaw gateway restart --json
• 前端通过 invoke 调用 Rust 命令
• 通过运行时判断，仅在 Tauri 环境中启用这组能力
• 浏览器模式继续保留“手工连接外部 Gateway”的现有逻辑

说明：

• 这一阶段是开发期过渡方案
• 它的价值是先把桌面端产品闭环跑通
• 但它不是最终交付形态
• 最终交付必须把 OpenClaw 运行时随 ZCLAW 一起打包，而不是要求用户本机已有 openclaw

A.3 代码范围

• desktop/src-tauri/src/lib.rs
• desktop/src/lib/tauri-gateway.ts（新增）
• desktop/src/store/gatewayStore.ts
• desktop/src/components/Settings/General.tsx
• 如有必要：desktop/src/components/RightPanel.tsx

A.4 验收标准

• Tauri 环境可正常调用本地 Gateway 管理命令
• 设置页能看到“本地 Gateway”状态卡片
• 用户可点击启动/停止/重启
• 启动成功后，前端可继续连接并拉取基础数据
• 浏览器模式不因该改动而报错或白屏
• 开发环境下，即使仍依赖系统 openclaw，也已经明确与最终 bundling 方案解耦

A.5 风险与应对

• 风险：不同机器上 openclaw 不在 PATH
  • 应对：前端明确提示“未安装 OpenClaw CLI”或“命令不可用”
• 风险：status --json / start --json 输出结构不稳定
  • 应对：Rust 侧优先使用 serde_json::Value 宽松解析，再映射到前端稳定结构
• 风险：服务模式与前台 gateway run 并存导致认知混乱
  • 应对：UI 文案明确说明“本地服务状态”和“当前 WebSocket 连接状态”是两层状态

---

Phase B：真实桌面端基础闭环验证

B.1 目标

确认 ZCLAW 在 Tauri 壳内已经不是“能打开 UI”，而是“能完成一次真实任务闭环”：

• 本地 Gateway 启动/可达
• 前端连接成功
• Clone 列表加载成功
• Agent 创建/编辑成功
• 首条消息发送成功
• 收到真实流式回复

B.2 任务清单

• 启动桌面应用并检查本地 Gateway 状态
• 验证连接状态、版本、插件状态、workspace 信息是否能拉取
• 验证创建 Agent
• 验证编辑 Agent 并刷新右侧面板数据
• 验证 bootstrap 文件生成状态
• 验证聊天发送与回复流
• 记录关键报错与回退路径

B.3 验收标准

• 至少完成一次完整桌面端对话闭环
• Agent 的创建与编辑在真实环境可用
• 连接失败、Gateway 未安装、未启动等错误能明确提示
• 关键路径没有阻塞性的控制台报错

---

Phase C：OpenClaw 随包分发与运行时托管

C.1 目标

把当前“依赖用户本机单独安装 OpenClaw”的开发态方案，推进到真正可交付的产品方案：

• 用户安装 ZCLAW 时，OpenClaw 运行时已经包含在安装包内
• ZCLAW 启动后，能够直接找到并启动内置 OpenClaw
• 用户不需要再单独安装一套 OpenClaw CLI / 环境

C.2 目标形态

最终交付建议采用以下形态：

• 安装包内包含 OpenClaw 可执行运行时或受控分发产物
• Tauri Rust 侧通过固定相对路径或 sidecar 机制调用该运行时
• ZCLAW 负责：
  • 初始化 OpenClaw home / workspace
  • 写入或合并默认配置
  • 启动 / 停止 / 重启 Gateway
  • 读取日志与状态

C.3 方案比较

方案 1：继续依赖系统安装的 openclaw

优点：

• 当前开发改造最少

缺点：

• 不符合最终产品目标
• 用户安装体验差
• 环境差异和 PATH 问题会显著增加支持成本

结论：

• 仅适合开发期，不可作为最终交付方案

方案 2：把 OpenClaw 作为 sidecar / bundled runtime 随 ZCLAW 分发

优点：

• 符合 QClaw / AutoClaw 式的一体化交付体验
• 可控性高
• 便于做安装后自启动、版本锁定、升级兼容

缺点：

• 需要处理体积、签名、跨平台打包、路径定位

结论：

• 这是最终推荐方案

C.4 实施任务

• 确认 OpenClaw 可分发形态
  • npm 包直接落地
  • 预构建二进制
  • 内置 Node + OpenClaw 组合运行时
• 确认 Tauri 2 下 sidecar / bundled binary 的最佳实现方式
• 为 Windows 优先落地一版 bundling 方案
• 调整 Rust 侧命令执行逻辑
  • 优先调用内置运行时
  • 开发模式可回退到系统 openclaw
• 验证安装后首次启动流程
  • 不依赖用户额外安装
  • 可直接启动 Gateway
  • 可连接、可聊天、可配置

C.5 验收标准

• 全新机器上，未单独安装 OpenClaw 的情况下，可直接安装并启动 ZCLAW
• ZCLAW 可成功拉起内置 OpenClaw Gateway
• Agent / 聊天 / 设置等核心功能可正常工作
• 用户文档不再要求“先安装 OpenClaw 再使用 ZCLAW”

---

Phase D：设置页可用性补齐

D.1 目标

梳理 Settings 体系中“看起来像功能、实际上还是占位”的部分，优先补齐最影响交付感知的项。

D.2 优先补齐范围

优先级从高到低建议如下：

1. General / ModelsAPI

   • Gateway 管理与连接语义统一
   • 去掉误导性按钮或接到真实逻辑

2. Workspace / Skills / MCPServices

   • 至少展示真实读取结果
   • 对未支持能力明确标注“暂未接入”而不是伪交互

3. IMChannels

   • 飞书状态尽量走真实探测
   • 对未完成渠道使用明确状态说明

4. Privacy / UsageStats / About

   • 以展示真实数据和静态说明为主，收尾体验

D.3 判定标准

• 对用户可点击的动作，尽量有真实效果
• 对暂未接入的能力，明确说明而不是假按钮
• 页面不出现明显“假功能”感

---

Phase E：交付前 smoke test 与文档收尾

E.1 目标

形成一套最小但明确的交付前检查流程，避免“本地看起来能用、别人拿到跑不起来”。

E.2 交付前 smoke checklist

环境检查

• pnpm -v
• pnpm --dir desktop tauri --version

说明：

• 最终交付 smoke test 不应再把系统级 openclaw --version 作为前置要求
• 应改为验证 ZCLAW 内置运行时是否可用

桌面启动检查

• pnpm --dir desktop tauri dev
• UI 能正常打开
• 设置页不白屏

Gateway 闭环检查

• 本地 Gateway 状态可读
• 能启动/停止/重启
• 前端连接成功

核心功能检查

• Clone 列表加载
• 新建 Clone
• 编辑 Clone
• 发送首条消息
• 收到流式回复

配置检查

• quick config 可读写
• workspace 信息可读取
• 插件状态可显示

安装闭环检查

• 全新环境中无需单独安装 OpenClaw
• 安装 ZCLAW 后首次启动即可使用
• 若内置运行时损坏或缺失，错误提示明确

E.3 文档更新项

• 更新 README：区分浏览器模式与 Tauri 桌面模式
• 补充本地 Gateway 启动/连接说明
• 补充已知限制与后续路线
• 在 PROGRESS.md 中登记本轮交付成果

---

Phase F：交付后加强项（不是当前阻塞项）

以下事项重要，但不应阻塞本轮“完整可用”目标：

• 更完整的 Tauri sidecar / 进程托管架构
• 安装包/自动更新
• 更高覆盖率测试
• v1 归档代码清理
• 微信 / QQ Channel 扩展
• 新 Session Prompt 等增强功能

这些能力应在当前闭环稳定后进入下一轮计划。

---

5. 实施顺序与里程碑

Milestone 1：桌面端本地 Gateway 管理打通

输出物：

• Tauri 命令桥
• 前端本地 Gateway 状态卡片
• 启停/重启操作

完成标志：

• 能在桌面应用中看到并操作本地 Gateway 服务状态

Milestone 2：真实桌面闭环通过

输出物：

• 真实运行验证记录
• 阻塞 bug 列表（若有）
• 修复后的可用路径

完成标志：

• 从桌面打开到完成一次对话全链路可用

Milestone 3：OpenClaw 随包分发打通

输出物：

• Windows 优先的一体化 bundling 方案
• ZCLAW 优先调用内置 OpenClaw 运行时
• 安装后无需用户额外安装 OpenClaw 的可运行链路

完成标志：

• 在未安装 OpenClaw 的机器/环境中，安装 ZCLAW 后即可直接使用

Milestone 4：设置页与交付收尾

输出物：

• 最小可交付设置体验
• smoke checklist
• README / PROGRESS 更新

完成标志：

• 仓库进入“可给他人试用”的状态

---

6. 本轮立即执行项

按当前优先级，接下来立刻执行：

1. 在 Tauri Rust 侧实现 Gateway 管理命令
2. 在前端新增 Tauri Gateway bridge
3. 在 gatewayStore 中接入本地 Gateway 状态与动作
4. 在 Settings > General 中增加本地 Gateway 管理卡片
5. 明确 OpenClaw 随包分发方案，避免把系统安装依赖固化为最终设计
6. 进行编译/运行级验证
7. 若验证通过，记录到 PROGRESS.md

---

7. 阶段提交策略

本轮按以下 checkpoint 推进：

Checkpoint A

• 完成计划文档
• 完成 Tauri 命令桥与前端接线

Checkpoint B

• 完成本地 Gateway 管理 UI
• 完成基础验证

Checkpoint C

• 完成 OpenClaw bundling / sidecar 方案设计
• 明确 Windows 优先的交付路径

Checkpoint D

• 完成设置页收尾 / 文档更新 / smoke checklist

说明：

• 代码会按干净阶段组织
• 如需执行远端 push，仍单独确认

---

8. 结论

当前最短、最正确的交付路径，不是继续扩展更多功能，而是先把 ZCLAW 从“能连 Gateway 的前端”推进成“能在桌面端真正管理并使用内置 OpenClaw 的产品”。

因此，本轮执行的核心结论是：

• 先做 Tauri 本地 Gateway 生命周期管理
• 再完成 OpenClaw 随包分发方案
• 然后做真实桌面端闭环验证
• 最后收尾设置页与交付文档

这条路线最符合当前仓库状态，也最接近“完整可用 ZCLAW”的真实交付目标。