zclaw_openfang/docs/features/V11_REMEDIATION_PLAN.md

ZCLAW V11 修复优先级计划

生成日期: 2026-04-02 关联审计: COMPREHENSIVE_AUDIT_V11.md + V11_GAP_ANALYSIS.md

---

Sprint 分配建议

Sprint 1 (P1 — 紧急修复)

V11-P1-01: trigger_update 参数修复

• 影响: Trigger 配置更新静默失败
• 修复复杂度: 低（1 文件修改）
• 文件: desktop/src/lib/kernel-triggers.ts:99
• 方案: 将嵌套 updates 对象展开为扁平参数

// 修复前:
await invoke('trigger_update', { id, updates });

// 修复后:
await invoke('trigger_update', {
  id,
  name: updates.name,
  enabled: updates.enabled,
  handId: updates.handId,
});

• 同时修复: Rust 端添加 trigger_type 参数支持（trigger.rs:183-189）
• 验证: 修改 trigger 配置后检查 Kernel 状态

V11-P1-02: SaaS 配置同步传播

• 影响: SaaS 管理员修改配置后不影响 Kernel 运行时
• 修复复杂度: 中（需要新增 Tauri 命令或事件机制）
• 方案:
  • 选项 A: saasStore.pullConfig 完成后调用 Tauri command 通知 Kernel 重新加载配置
  • 选项 B: Kernel 定期检查配置文件变更（watcher）
  • 选项 C: 明确记录为 "前端缓存同步，不影响 Kernel"
• 建议: 先选 C（文档对齐），后续迭代实现 A
• 验证: 在 SaaS 后台修改配置 → 检查 Kernel 日志是否反映变更

V11-P1-03: 孤立 SQL 表处理

• 影响: 数据写入但无法读取，浪费存储
• 修复复杂度: 低
• 方案:
  • prompt_sync_status: 实现读取查询（OTA 端点需要）
  • telemetry_reports: 添加 admin-v2 查询端点
  • key_usage_window: 确认是否需要（限流可能已改用内存方案）
• 验证: grep -rn "SELECT.*FROM.*<table>" crates/zclaw-saas/src/ 有结果

---

Sprint 2 (P2 — 高优先级)

V11-P2-01: 删除 saas-admin.ts

• 修复复杂度: 低（删除 1 文件 + saas-client.ts 中的 install 调用）
• 前置条件: 确认 admin-v2 完全不依赖此文件
• 验证: admin-v2 所有页面功能正常

V11-P2-02: Role/Permission 管理

• 选项 A: 为 admin-v2 添加 roles service 和页面
• 选项 B: 移除 SaaS role 路由（如果当前不需要 RBAC）
• 建议: 评估业务需求后决定

V11-P2-03: 迁移 deprecated gateway-storage 调用者

• 文件: gateway-client.ts:44,71,211, configStore.ts:252
• 方案: 将 sync 方法调用替换为 async 版本
• 验证: Gateway 连接功能测试

V11-P2-04: ToolDefinition 去重

• 文件: zclaw-runtime/src/driver/mod.rs:94
• 方案: 重导出 zclaw-types::tool::ToolDefinition
• 验证: cargo build 通过

V11-P2-05: 未调用 Tauri 命令评估

• 62 个命令需逐一评估：
  • classroom_*: 确认 classroomStore 是否真正调用（可能是 store 中调用的）
  • pipeline_*: 确认 workflowStore 是否调用
  • gateway_*: 确认是否有侧车进程调用
  • viking_*: 确认 Settings 页面是否调用
• 验证: 对每个命令 grep invoke('command_name'

V11-P2-06: SQL LIMIT 添加

• 文件: migration/service.rs, knowledge/service.rs
• 方案: 为 config_items SELECT 添加 LIMIT 1000，knowledge_categories 添加 LIMIT 100
• 验证: SQL 执行计划验证

---

Sprint 3 (P3 — 中优先级)

V11-P3-01: audit-logger 接入

• 方案: 在 ApprovalsPanel、AutonomyConfig、chatStore 的关键操作中添加 logAudit 调用
• 或: 标记为 reserved 并从 index 导出中移除

V11-P3-02: OFP 能力处理

• 方案: 添加 // Reserved for OpenFang Protocol 注释或移除变体

V11-P3-03: 移除 deprecated extract_structured_facts

• 方案: 删除 growth.rs:224 的 deprecated 方法
• 验证: cargo build 通过

V11-P3-04: SaaS knowledge stub 实现

• 文件: knowledge/handlers.rs:91,293,321
• 方案: 实现真正的分页查询、回滚、推荐算法
• 验证: admin-v2 Knowledge 页面功能测试

V11-P3-05: 定时任务执行结果持久化

• 方案: 添加 last_result/last_error 列到 scheduled_tasks 表
• 迁移: 新增 SQL migration
• 验证: 创建定时任务 → 执行 → 检查结果是否存储

V11-P3-06 ~ P3-08: 其他清理

• 移除 secure-storage sync 方法
• 启用 embedding 生成或注释
• 清理 config 预留参数注释

---

Sprint 4 (P4 — 低优先级 / 文档)

V11-P4-01: ContentBlock 命名规范

• 方案: 为每个 crate 的 ContentBlock 添加 crate 前缀注释
• zclaw_types::ContentBlock = LLM 消息内容
• zclaw_hands::ContentBlock = 幻灯片渲染
• zclaw_protocols::ContentBlock = MCP 协议格式

V11-P4-02: 类型名称统一

• 方案: 建立共享类型包 @zclaw/types 或使用 OpenAPI schema 生成
• 13+ 类型名称不一致需要协调

V11-P4-03: 文档数字更新

• Skills: 76
• Hands: 9 目录（CLAUDE.md 应更新 "11" → "9 目录 + 2 禁用配置"）
• Tauri 命令: 175
• SaaS 路由: 58
• Stores: 15

V11-P4-04/05: Feature-gated 代码保持现状

• Director/A2A/WASM: 等产品路线图决定
• Embedding 生成: 等 OpenViking 集成完成后启用

---

依赖关系图

V11-P1-01 (trigger_update 修复)
  └── 无依赖，可独立完成

V11-P1-02 (配置同步传播)
  └── 依赖设计决策（选项 A/B/C）

V11-P1-03 (孤立表处理)
  └── V11-P2-06 (SQL LIMIT) 可同时处理

V11-P2-01 (删除 saas-admin.ts)
  └── V11-P2-04 (ToolDefinition 去重) 可同时完成

V11-P2-03 (迁移 deprecated 调用)
  └── 需要先确认 async 版本稳定性

V11-P3-04 (knowledge stub 实现)
  └── 依赖 V11-P1-03（确认表用途后实现读取）

V11-P4-02 (类型统一)
  └── 长期任务，不阻塞其他修复

---

修复工作量估算

Sprint	项数	预估工作量	风险等级
Sprint 1 (P1)	3	中	高（P1-02 需设计决策）
Sprint 2 (P2)	6	高	中（P2-05 工作量大）
Sprint 3 (P3)	8	中	低
Sprint 4 (P4)	5	低	低

---

验证检查清单

编译验证

cargo build --workspace
pnpm tsc --noEmit

功能验证

• 创建/更新/删除 Trigger → 检查 Kernel 状态
• SaaS 后台修改配置 → 检查 desktop 前端行为
• Admin-v2 Knowledge 页面 CRUD
• 定时任务执行 → 检查结果存储
• Agent 审批 → Hand 自动执行
• Pipeline 运行 → 完成事件通知

回归验证

# Rust 测试
cargo test --workspace

# 前端测试
pnpm vitest run

# Admin-v2 测试
cd admin-v2 && pnpm test