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

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

## 1. 计划目标

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

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

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

---

## 2. 当前基线

### 2.1 已完成的关键能力

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

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

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

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

2. **当前仍默认依赖用户独立安装 ZCLAW**
   - 这与最终产品目标不一致
   - 最终必须做到：安装 ZCLAW 后即可直接使用 ZCLAW 能力
   - 因此现阶段的 CLI/PATH 依赖只能作为开发期和过渡期方案

3. **真实桌面链路缺少本地运行闭环验证**
   - 需要验证 Tauri 内从启动 Gateway 到连接、到拉数据、到发消息的完整过程

4. **设置体系中仍有若干页面/按钮处于占位状态**
   - 部分页面已有 UI 但尚未连接真实能力
   - 会影响“可用”判断，尤其是用户首次体验

5. **交付收尾缺少固定验收流程**
   - 需要统一 smoke test、安装前检查、文档更新、阶段提交点

---

## 3. 总体推进策略

### 3.1 核心原则

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

### 3.2 本轮优先级

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

---

## 4. 分阶段执行计划

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

### A.1 目标

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

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

### A.2 实现策略

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

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

说明：

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

### 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”状态卡片
- 用户可点击启动/停止/重启
- 启动成功后，前端可继续连接并拉取基础数据
- 浏览器模式不因该改动而报错或白屏
- 开发环境下，即使仍依赖系统 `zclaw`，也已经明确与最终 bundling 方案解耦

### A.5 风险与应对

- **风险**：不同机器上 `zclaw` 不在 PATH
  - **应对**：前端明确提示“未安装 ZCLAW 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：ZCLAW 随包分发与运行时托管

### C.1 目标

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

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

### C.2 目标形态

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

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

### C.3 方案比较

#### 方案 1：继续依赖系统安装的 `zclaw`

优点：

- 当前开发改造最少

缺点：

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

结论：

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

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

优点：

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

缺点：

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

结论：

- **这是最终推荐方案**

### C.4 实施任务

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

### C.5 验收标准

- 全新机器上，未单独安装 ZCLAW 的情况下，可直接安装并启动 ZCLAW
- ZCLAW 可成功拉起内置 ZCLAW Gateway
- Agent / 聊天 / 设置等核心功能可正常工作
- 用户文档不再要求“先安装 ZCLAW 再使用 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 不应再把系统级 `zclaw --version` 作为前置要求
- 应改为验证 ZCLAW 内置运行时是否可用

#### 桌面启动检查

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

#### Gateway 闭环检查

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

#### 核心功能检查

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

#### 配置检查

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

#### 安装闭环检查

- 全新环境中无需单独安装 ZCLAW
- 安装 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：ZCLAW 随包分发打通

输出物：

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

完成标志：

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

## Milestone 4：设置页与交付收尾

输出物：

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

完成标志：

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

---

## 6. 本轮立即执行项

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

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

---

## 7. 阶段提交策略

本轮按以下 checkpoint 推进：

### Checkpoint A

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

### Checkpoint B

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

### Checkpoint C

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

### Checkpoint D

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

说明：

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

---

## 8. 结论

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

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

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

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