zclaw_openfang/docs/superpowers/specs/2026-03-31-pre-launch-dual-track-design.md

ZCLAW 上线前双轨并行改进设计

日期: 2026-03-31 阶段: 上线前准备 策略: 功能+质量并行 基于: 三维系统分析 + 代码审查验证（已排除已完成项）

---

1. 背景与动机

ZCLAW 系统经过多轮迭代（Sprint 1-8 完成，10 个 Batch 完成），核心功能完成度达 87-95%。系统当前处于 B+ 健康度，存在 41 个已知问题（0 Critical, 6 High, 20 Medium, 15 Low）。

已完成的关键项（经代码审查确认）:

• Token 刷新竞态: 已修复 (request.ts onTokenRefreshFailed)
• Dockerfile: 已存在 (多阶段构建, rust:1.85-bookworm)
• saas-env.example: 已存在
• 生产部署指南: 已存在 (docs/deployment/saas-production.md, 430 行)
• /api/health: 已在公开路由组
• Agent Template 详情: 已展示所有扩展字段
• AgentOnboardingWizard: 已使用 React hook 模式

实际剩余上线阻塞项:

• 反向代理场景下限流失效（ConnectInfo 返回代理 IP 而非客户端 IP）
• 前端测试覆盖率 0-15%，回归风险极高
• 调度任务执行器为 STUB，违反"不展示假数据"原则
• Desktop 废弃代码 + TS 遗留错误

目标: 在上线前完成所有阻塞项，同时推进 1-2 个高价值功能以提升产品竞争力。

---

2. 系统分析摘要

2.1 规模

组件	规模
Rust Crates	10 个 (types/memory/runtime/kernel/skills/hands/protocols/pipeline/growth/saas)
SaaS API	93 个端点 (5 公开 + 88 受保护)
Tauri Commands	106 个
Zustand Store	14 个 (desktop) + 2 个 (admin-v2)
技能	71 个 SKILL.md
Hands	9 个已启用 (7 完整 + 2 demo) + 2 个已禁用 (Predictor/Lead)
数据库	PostgreSQL, Schema v11, 25+ 表

2.2 实际系统性挑战（经验证）

1. 测试覆盖率缺口 — Admin V2 0%, Desktop ~15%, Rust 34%
2. 类型安全裂缝 — Desktop 50+ as any, Mixin 模式无编译时保障
3. 反向代理限流失效 — ConnectInfo 返回代理 IP，需 trusted_proxies 配置
4. 功能完整度断层 — 调度任务 STUB, Quiz 占位符, 5 个 404 API
5. 废弃代码残留 — gatewayStore.ts 废弃未清理, TS 遗留错误

2.3 关键洞察

• 技能系统是隐藏的宝石: 71 个 SKILL.md 是差异化资产，应优先展示
• 测试是最大风险: 0-15% 的覆盖率意味着任何改动都可能回归
• 部署基本就绪: Dockerfile + 部署指南已存在，需验证而非创建
• STUB 是隐性技术债: 违反 CLAUDE.md "不允许展示假数据" 原则

---

3. 设计：双轨并行方案

3.1 轨道 1 — 质量轨道 (Quality Track)

必须在上线前全部完成，阻塞发布。

Q1. 安全加固 (~2h)

Q1.1 反向代理场景限流修复 (唯一实际安全项)

• 文件: crates/zclaw-saas/src/middleware.rs:133-140
• 问题: 代码正确地不信任 X-Forwarded-For（使用 ConnectInfo），但当部署在 Nginx 反向代理后，ConnectInfo 返回的是代理 IP（如 127.0.0.1），导致所有客户端共享同一 IP 限流桶，限流失效
• 方案:
  • 在 saas-config.toml 添加 trusted_proxies = ["127.0.0.1", "::1"] 配置
  • 当请求来自可信代理 IP 时，解析 X-Forwarded-For 头获取真实客户端 IP
  • 非可信来源继续使用 ConnectInfo（保持当前安全行为）
• 验证: 单元测试验证：可信代理 + 有效头 → 使用头中 IP；可信代理 + 无头 → 使用代理 IP；非可信来源 → 忽略头

Q1.2 adminRouting 解析验证

• 文件: desktop/src/store/connectionStore.ts:358-372
• 问题: 从 localStorage 读取 adminRouting 时无类型校验，第 376 行 catch 块静默吞错误
• 方案: 添加 Zod schema 验证解析结果，无效值 fallback 到默认模式
• 验证: 测试各种非法输入（null, undefined, 畸形 JSON）

Q2. 部署验证 (~2h)

部署基础设施已存在，此任务为验证和完善。

验证项:

• docker compose up 端到端测试（PostgreSQL + SaaS 启动 → 健康检查通过）
• Nginx 配置引用的 deploy/nginx.conf 是否存在
• saas-env.example 环境变量是否与实际代码一致
• 生产部署指南步骤是否可执行

完善项（如验证中发现缺失）:

• 补充 deploy/nginx.conf（如果不存在）
• 更新 saas-env.example 中的遗漏项

Q3. 测试基础 (~10h)

Q3.1 Admin V2 测试基础设施 (~2h)

• 安装: vitest, @testing-library/react, @testing-library/jest-dom, msw
• 配置: admin-v2/vitest.config.ts + setup 文件
• MSW handlers 模拟 SaaS API 响应

Q3.2 Admin V2 核心测试 (~4h)

• request.ts: 已有 Token 刷新修复的回归测试、网络错误包装、401 自动重定向
• authStore: 登录/登出/Token 刷新状态管理
• 核心页面冒烟测试: Accounts, Providers, AgentTemplates 渲染验证

Q3.3 Desktop 关键 Store 测试 (~4h)

• connectionStore: 三种连接模式切换逻辑
• chatStore: 消息发送/接收/流式响应
• saasStore: 认证流程 + 心跳降级

Q4. 功能补全 (~6h)

Q4.1 调度任务执行器真实实现 (~4h)

• 文件: crates/zclaw-saas/src/scheduler.rs:132,166
• 方案: 在 scheduler loop 中实际触发任务执行：
  • Agent/Hand/Workflow 类型任务通过内部 HTTP 调用触发（而非外部 API）
  • 记录执行结果到 scheduled_tasks 表
  • 支持失败重试 (指数退避, 最多 3 次)
• 验证: 集成测试验证任务创建 → 执行 → 结果记录全流程

Q4.2 Admin V2 表格搜索/筛选 (~2h)

• 方案: 使用 ProTable 内置搜索能力，为 Accounts/Models/Providers/ApiKeys/Prompts 表格添加搜索栏
• 范围: 至少覆盖 Accounts 和 Models 两个最常用的表格

Q5. 代码清理 (~4h)

Q5.1 废弃 gatewayStore.ts 清理 (~2h)

• 文件: desktop/src/store/gatewayStore.ts (358 行)
• 方案:
  1. 审查所有 gatewayStore 导入（agentStore, configStore, handStore, workflowStore, sessionStore 等可能引用）
  2. 验证 facade 模式是否被组件间接使用
  3. 移除整个文件，更新所有引用改用 connectionStore
  4. 运行全量测试验证无回归
• 风险: facade 模式可能被组件间接依赖，需要充分验证

Q5.2 TS 遗留错误修复 (~1h)

• 文件: desktop/src/lib/gateway-api.ts, desktop/src/lib/kernel-hands.ts
• 方案: 修复之前重构引入的类型错误

Q5.3 未使用依赖清理 (~1h)

• 文件: admin-v2/package.json
• 方案: 移除 @ant-design/charts 未使用依赖

质量轨道实际总计: ~24h

3.2 轨道 2 — 功能轨道 (Feature Track)

不阻塞上线，但提升产品竞争力。可与质量轨道并行。

F1. 技能市场 UI (~16h)

目标: 展示 71 个 SKILL.md 技能，让用户浏览和发现可用能力

组件设计:

• SkillMarket.tsx — 主页面，网格布局展示技能卡片
• SkillCard.tsx — 单个技能卡片 (名称、描述、标签、激活状态)
• SkillDetail.tsx — 技能详情弹窗 (完整 SKILL.md 渲染 + 使用示例)
• SkillSearch.tsx — 搜索栏 + 分类筛选

数据流:

• 从 Kernel IPC skill_list 命令获取技能完整列表
• 搜索方案: 客户端过滤（71 个技能规模小，前端过滤足够高效）
  • 名称/描述模糊匹配 (Fuse.js 或手写 filter)
  • 按分类标签筛选
  • 无需后端搜索命令
• 激活/停用通过现有 skill_activate 命令

分类方案（基于 SKILL.md metadata）:

• 开发与工程 / 商业与营销 / 研究与内容 / 运营 / 专业技能

依赖: 需确认 skill_list 返回的数据结构包含分类信息

F2. 上下文压缩 + 记忆系统 (~12h)

上下文压缩 Kernel 集成:

• 将 zclaw-growth 的 Compactor 接入 Kernel 中间件链
• 触发条件: 上下文长度超过模型窗口的 80%
• 压缩策略: 保留最近 N 条完整消息 + 早期消息生成摘要
• 用户可见性: 压缩后在聊天界面显示"上下文已压缩"系统消息
• 存储: 摘要作为系统消息存储，原始消息保留但标记为已压缩

记忆系统升级:

• 向量化检索优化 (FTS5 → 混合 FTS5 + Embedding)
• MemoryMiddleware 30s 防抖实现
• 记忆提取后自动关联到 Agent Soul

F3. Quiz Hand 真实化 (~6h)

当前问题: Quiz Hand 使用占位符生成器，生成假数据

方案:

• 替换为 LLM 驱动的真实题目生成
• 使用 Pipeline 模板系统 (已有基础设施)
• 支持多题型: 选择题、填空题、问答题
• 难度自适应: 基于用户表现动态调整

功能轨道总计: ~34h

---

4. 时间线

Week 1-2: 质量轨道冲刺 (Q1-Q3) — 阻塞上线
  ├── Q1: 安全加固 (2h)
  ├── Q2: 部署验证 (2h)
  └── Q3: 测试基础 (10h)
  ┃ 可并行 ──→ F1: 技能市场 UI (16h)

Week 3-4: 质量收尾 + 功能启动
  ├── Q4: 功能补全 (6h)
  ├── Q5: 代码清理 (4h)
  ├── F2: 上下文压缩 + 记忆 (12h)
  └── F3: Quiz Hand 真实化 (6h)

Week 5+: 功能深化
  ├── Semantic Router 成熟化 (8h)
  ├── Pipeline 编辑器增强 (12h)
  └── i18n 框架 (12h)

=== 上线 Gate ===
质量轨道 Q1-Q5 全部完成 = 可发布

---

5. 成功标准

上线 Gate (必须全部通过)

• docker compose up 可成功启动 SaaS 后端（验证现有基础设施）
• 反向代理场景下限流正确区分不同客户端 IP
• Admin V2 测试套件 >10 个测试且全部通过
• Desktop 关键 Store 测试 >5 个且全部通过
• 调度任务可创建并可执行（非 STUB）
• tsc --noEmit 和 cargo check 零错误
• gatewayStore.ts 已完全移除

质量指标 (目标)

• Admin V2 测试覆盖率 >30%（后续迭代提升至 80%）
• Desktop 关键 Store 测试覆盖率 >40%
• TypeScript 严格模式 any 数量 Desktop <10 处
• Rust 测试覆盖率 >40%

---

6. 风险与缓解

风险	概率	影响	缓解
调度任务执行器集成复杂度超预期	中	高	先实现最简单的 HTTP 触发，后续迭代增加重试
测试编写发现更多 bug	高	中	这是好事，发现的 bug 加入修复列表
gatewayStore 移除导致间接依赖断裂	中	高	先审查所有导入，添加弃用警告阶段
技能市场 skill_list 返回数据不包含分类	中	低	前端基于 SKILL.md 路径或关键词自动分类

---

7. 不包含的内容

以下功能明确不在此设计范围内：

• Predictor/Lead Hand 实现（需产品定义）
• 插件系统（需安全沙盒设计）
• 多用户协作（需架构设计）
• Token Pool 计费系统（需商业化设计）
• 实时配置推送 WebSocket（当前拉取模式足够）
• Redis 持久化限流（单实例部署暂不需要）