zclaw_openfang/docs/superpowers/specs/2026-04-03-production-readiness-design.md

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 方法一致

自动化验证

# 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 持久化优化
• 云同步服务