ZCLAW 生产就绪收尾设计文档

> **日期**: 2026-04-03
> **状态**: 已批准
> **预估总工时**: 12h（3 批次）
> **策略**: 分层收敛 — 个人端优先、企业端跟进

---

## 1. 背景与动机

ZCLAW 经过 3 周密集开发，已修复全部 P0/P1 缺陷，核心功能完成度 90-98%。功能全景审计发现：

- **12 个前后端一致性问题**: 5 个孤立 invoke、Pipeline 文档过时、14 个 SaaS 端点无前端调用
- **9 个功能缺失**: WASM/Native 执行未实现、Identity 回滚无 UI、MessageSearch 被禁用
- **10 个可用性风险**: api-fallbacks 静默掩盖、MessageSearch 被禁用、Viking 孤立调用运行时崩溃
- **7 处文档漂移**: SaaS API 数量差距最大（文档 58，实际 132）

本设计旨在通过 3 个批次高效收尾，使 ZCLAW 达到产品级可用状态。

---

## 2. 关键决策

| 决策 | 选择 | 理由 |
|------|------|------|
| 功能冻结状态 | 全面解冻 → 修复 → 再冻结 | P0/P1 已全部修复，审计发现的断链需要新增前端代码 |
| 目标用户优先级 | 个人优先，企业跟进 | 桌面端核心体验（聊天、Pipeline、Hand、记忆）先保障 |
| 未接入端点策略 | 分批处理 | 个人端断链先接通，企业端（Scheduled Task/Config）先标注 @reserved |
| Viking 发展方向 | 优化现有原生实现 | 原生 SqliteStorage 优于外部 sidecar，删除孤立 invoke |
| Pipeline 状态 | 验证而非重连 | 代码审计显示前后端已完全连接，可能是文档过时 |

---

## 3. 执行计划

### Batch 1: 用户直接感知 (5h)

**目标**: 修复个人端用户能直接感知的问题

#### B1-1: Pipeline 端到端验证 (1h)

**问题**: TRUTH.md 记录"Pipeline DSL 引擎完整但无前端 invoke 调用"，但代码审计显示前端 `pipeline-client.ts` 有 8 个 invoke 调用（pipeline_list/get/run/progress/result/cancel/runs/refresh）、Rust 端 `discovery.rs` 有完整 `#[tauri::command]` 注册。

**操作**:
1. 启动 Tauri 开发环境，在 PipelinesPanel 中触发一个 education 模板
2. 确认 `pipeline_list` → `pipeline_run` → `pipeline_progress` → `pipeline_result` 完整流程
3. 如果不工作，排查断链点并修复
4. 更新 TRUTH.md 中过时的 Pipeline 记录

**关键文件**:
- `desktop/src/components/PipelinesPanel.tsx` — 使用 `usePipelines()` hook
- `desktop/src/lib/pipeline-client.ts` — 8 个 Tauri invoke 调用 (list/get/run/progress/result/cancel/runs/refresh)
- `desktop/src-tauri/src/pipeline_commands/discovery.rs` — `#[tauri::command]` 注册
- `docs/TRUTH.md` — 修正过时记录

#### B1-2: MessageSearch 恢复 (1h)

**问题**: DeerFlow 重设计期间 MessageSearch 被注释掉（ChatArea.tsx 第 21 行）。组件本身完整，支持 session 搜索和 global 记忆搜索。

**操作**:
1. 取消 `ChatArea.tsx` 第 21 行注释，恢复 MessageSearch 导入
2. 在 DeerFlow 极简布局中找到合适的搜索入口位置（建议放在 TopBar 中）
3. 确认 `intelligence-backend.ts` 的 `searchGlobalMemory()` 仍正常工作
4. 验证 session 搜索和 global 搜索均可触发

**关键文件**:
- `desktop/src/components/ChatArea.tsx` — 第 21 行注释
- `desktop/src/components/MessageSearch.tsx` — 完整的搜索组件
- `desktop/src/lib/intelligence-backend.ts` — global 搜索后端

#### B1-3: Viking 清理与优化 (2h)

**问题**: 5 个前端 invoke 调用在 Rust 端无对应命令，运行时必然返回 "command not found"。2 个有 Rust 后端的命令（`viking_add_with_metadata`、`viking_store_with_summaries`）无前端调用。

**操作**:
1. 删除 `viking-client.ts` 中 5 个孤立方法：`viking_add_inline`、`viking_server_start/stop/status/restart`
2. 删除相关的 `VikingServerStatus` 类型定义
3. 在 `viking-client.ts` 中添加 `addWithMetadata()` 方法（调用已有的 `viking_add_with_metadata`）
4. 在 `viking-client.ts` 中添加 `storeWithSummaries()` 方法（调用已有的 `viking_store_with_summaries`）
5. 在 VikingPanel 中添加"生成摘要"按钮，调用 `storeWithSummaries()`
6. 更新 TRUTH.md 中 Viking 命令的前端连接标注

**关键文件**:
- `desktop/src/lib/viking-client.ts` — 删除 5 个孤立方法，添加 2 个新方法
- `desktop/src/components/VikingPanel.tsx` — 添加摘要生成触发
- `desktop/src-tauri/src/viking_commands.rs` — 已有 Rust 命令，无需修改
- `docs/features/03-context-database/00-openviking-integration.md` — 更新架构描述

#### B1-4: api-fallbacks 透明化 (1h)

**问题**: `api-fallbacks.ts` 在后端返回 404 时静默返回假数据，用户无法区分真实功能和降级。

**操作**:
1. 每个 fallback 函数返回数据中添加 `_isFallback: true` 标记
2. 添加 `console.warn('[fallback] 使用降级数据: <函数名>')` 日志
3. 在消费 fallback 数据的 Store 中检测标记，设置 `isDegraded: true` 状态
4. UI 组件根据 `isDegraded` 显示黄色提示条"该功能需要连接后端服务"

**关键文件**:
- `desktop/src/lib/api-fallbacks.ts` — 添加标记和日志
- `desktop/src/store/configStore.ts` — 检测降级状态
- `desktop/src/store/handStore.ts` — 检测降级状态
- 相关 UI 组件 — 显示降级提示

---

### Batch 2: 系统健康 (4h)

**目标**: 校准文档真相源，标注企业端断链

#### B2-1: 文档漂移校准 (1.5h)

**问题**: 7 处文档数字与实际代码不符。

**操作**:
更新以下文档中的过时数字：

| 文档 | 过时值 | 正确值 |
|------|--------|--------|
| `docs/features/README.md` | SaaS API: 58 | 132 |
| `docs/features/README.md` | Zustand Store: 15 | 18 |
| `docs/features/README.md` | SQL Schema: v6 | v8 |
| `docs/features/README.md` | Admin 页面: 11 | 13 |
| `docs/README.md` | 8 Rust Crates | 10 |
| `docs/features/roadmap.md` | Tauri 命令: 175 | 171 (TRUTH) |
| `docs/TRUTH.md` | SaaS API: 93 | 132 (含 Knowledge Base 模块 23 个新端点: category CRUD + item CRUD + search + recommend + analytics 5 端点 + 版本管理) |

同步更新 `docs/features/README.md` 中所有模块的成熟度评估。

**关键文件**:
- `docs/TRUTH.md`
- `docs/features/README.md`
- `docs/features/roadmap.md`
- `docs/README.md`

#### B2-2: 无前端端点标注 (0.5h)

**问题**: 14 个 SaaS 端点无前端调用，但代码中无任何标注。

**操作**:
在以下 handler 函数上添加 `// @reserved - no frontend caller` 注释：

| 端点 | 模块 |
|------|------|
| `POST /api/v1/config/items` | migration |
| `GET /api/v1/config/items/:id` | migration |
| `DELETE /api/v1/config/items/:id` | migration |
| `GET /api/v1/config/analysis` | migration |
| `POST /api/v1/config/seed` | migration |
| `GET /api/v1/config/sync-logs` | migration |
| `POST /api/v1/keys/:id/rotate` | model_config |
| `GET /api/v1/knowledge/items/:id/versions/:v` | knowledge |
| `GET /api/scheduler/tasks` | scheduled_task |
| `POST /api/scheduler/tasks` | scheduled_task |
| `GET /api/scheduler/tasks/:id` | scheduled_task |
| `PATCH /api/scheduler/tasks/:id` | scheduled_task |
| `DELETE /api/scheduler/tasks/:id` | scheduled_task |

**关键文件**:
- `crates/zclaw-saas/src/migration/handlers.rs`
- `crates/zclaw-saas/src/model_config/handlers.rs`
- `crates/zclaw-saas/src/knowledge/handlers.rs`
- `crates/zclaw-saas/src/scheduled_task/handlers.rs`

#### B2-3: Scheduled Task Admin UI (1.5h)

**问题**: Scheduled Task 后端 5 个 CRUD 端点完整，但桌面端和 Admin 端均无 UI。

**操作**:
1. 在 `admin-v2/src/services/` 添加 `scheduled-tasks.ts` 服务文件
2. 在 `admin-v2/src/pages/` 添加 ScheduledTasks 页面（列表+创建/编辑/删除）
3. 在 `admin-v2/src/router/index.tsx` 添加路由
4. 在 `admin-v2/src/layouts/AdminLayout.tsx` 侧边栏添加导航入口
5. 复用 Admin 现有的 Ant Design Pro 组件模式

**关键文件**:
- `admin-v2/src/services/scheduled-tasks.ts` — 新建
- `admin-v2/src/pages/ScheduledTasks.tsx` — 新建
- `admin-v2/src/router/index.tsx` — 添加路由
- `admin-v2/src/layouts/AdminLayout.tsx` — 添加侧边栏导航

#### B2-4: TRUTH.md Pipeline 记录修正 (0.5h)

**问题**: TRUTH.md 记录"Pipeline 无前端 invoke 调用"，但代码审计显示已完全连接。

**操作**:
1. 将 Pipeline 从"已实现但未接通前端"移到"确认可用"列表
2. 添加 Pipeline 验证结果记录

**关键文件**:
- `docs/TRUTH.md`

---

### Batch 3: 长期质量 (3h)

**目标**: 验证功能性缺陷，清理 P2 代码质量问题

#### B3-1: hand_run_status 端到端验证 (0.5h)

**问题**: TRUTH.md 和审计报告记录 `hand_run_status` 和 `hand_run_list` 为 stub 命令，但代码审计显示它们已在 `desktop/src-tauri/src/kernel_commands/hand.rs`（第 358-416 行）完整实现，前端 `desktop/src/lib/kernel-hands.ts`（第 105-153 行）已有 invoke 调用。与 Pipeline 情况类似，可能需要的是验证而非实现。

**操作**:
1. 验证 hand_run_status/hand_run_list 的端到端流程
2. 如果工作正常，更新 TRUTH.md 修正过时记录
3. 如果有问题，修复断链

**关键文件**:
- `desktop/src-tauri/src/kernel_commands/hand.rs` — 已有完整实现（第 358-416 行）
- `desktop/src/lib/kernel-hands.ts` — 已有 invoke 调用（第 105-153 行）
- `docs/TRUTH.md` — 修正过时记录

#### B3-2: Identity 快照回滚 UI (1h)

**问题**: `identity_get_snapshots` 和 `identity_restore_snapshot` API 存在，但前端无回滚入口。

**操作**:
1. 在 RightPanel 的 identity tab 中添加"历史快照"区域
2. 调用 `identityClient.getSnapshots(agentId)` 显示快照列表
3. 每个快照显示时间戳和变更摘要
4. 添加"回滚到此版本"按钮，调用 `identityClient.restoreSnapshot(agentId, snapshotId)`

**关键文件**:
- `desktop/src/components/RightPanel.tsx` — 添加快照区域
- `desktop/src/lib/intelligence-client/` — 已有 identity 方法

#### B3-3: P2 代码质量清理 (1h)

**问题**: TRUTH.md 记录 10 个 P2 代码质量问题。

**操作**:
根据 TRUTH.md 中的 SEC2-P2-01~10 清单，逐项修复。具体项目需在执行时确认。

#### B3-4: Config HTTP 方法对齐 (0.5h)

**问题**: Admin `config.ts` 使用 PATCH 更新，SaaS 后端定义 PUT。

**操作**:
1. 确认 SaaS 后端是否同时支持 PUT 和 PATCH
2. 如果只支持 PUT，更新 Admin 服务文件使用 PUT
3. 如果同时支持，无需修改

**关键文件**:
- `admin-v2/src/services/config.ts`

---

## 4. 验证方案

### Batch 1 完成标准

- [ ] Pipeline: 能在 UI 中成功执行一个模板
- [ ] MessageSearch: 在聊天界面能搜索消息（session + global）
- [ ] Viking: VikingPanel 不再触发 "command not found"，摘要生成可触发
- [ ] api-fallbacks: 降级数据有明确提示

### Batch 2 完成标准

- [ ] 文档: TRUTH.md 和 README.md 数字与代码一致
- [ ] 端点标注: 14 个无前端端点有 @reserved 注释
- [ ] Scheduled Task: Admin 中能创建/查看/删除定时任务

### Batch 3 完成标准

- [ ] hand_run_status: 端到端验证通过，返回真实执行状态数据
- [ ] Identity: 能查看历史快照并执行回滚
- [ ] P2: 10 个代码质量问题已处理
- [ ] Config: Admin 和 SaaS HTTP 方法一致

### 自动化验证

```bash
# TypeScript 编译
cd desktop && pnpm tsc --noEmit

# Rust 编译
cargo check --workspace

# 单元测试
cargo test --workspace
pnpm vitest run
cd ../admin-v2 && pnpm vitest run
```

---

## 5. 风险评估

| 风险 | 概率 | 影响 | 缓解 |
|------|------|------|------|
| Pipeline 实际有隐藏断链 | 中 | B1-1 时间翻倍 | 先验证再修复 |
| DeerFlow 布局不适配 MessageSearch | 低 | 需调整 CSS | 复用现有搜索 UI |
| Viking 摘要生成需要 LLM 配置 | 中 | 用户需先配置模型 | 显示配置引导 |
| Scheduled Task Admin 页面超出预估 | 低 | 复用 Ant Design 模板 | 控制复杂度 |
| P2 清理发现新问题 | 中 | 时间增加 | 按优先级截断 |

---

## 6. 不在本设计范围内

以下功能明确**不在**本次收尾范围内：

- WASM/Native Skill 执行模式（中期计划 M1）
- 智能路由 Phase 3 多技能编排
- Active Learning Phase 2 SQLite+向量化
- Predictor/Lead Hands 实现
- A2A 协议完整实现
- Agent 持久化优化
- 云同步服务