zclaw_openfang/docs/archive/old-directives/STABILIZATION_DIRECTIVE.md

ZCLAW 稳定化指令 v1.0

生效日期: 2026-04-02 状态: ✅ 已完成（2026-04-03） — 降级为建议级别 目标: 将系统从"功能堆叠模式"切换到"端到端可用模式" 结论: 7 项完成标准全部达标，稳定化阶段结束。本文件保留作为历史记录和后续质量参考。

---

0. 核心原则

新增功能冻结。 在以下 P0 问题全部修复之前，不接受任何新功能 PR。

判断标准：这个改动是否让用户今天就能用上？
- 是 → 可以做
- 否 → 记录到 backlog，不做

---

1. P0 紧急修复（阻塞一切）

ID	问题	文件	修复方案
SEC2-P0-01	skill_execute 反序列化崩溃	desktop/src/lib/kernel-skills.ts:110-114 + desktop/src-tauri/src/kernel_commands/skill.rs:290-296	前端传入真实 agentId/sessionId，或 Rust 端改为 Option<String>
SEC2-P0-02	TaskTool::default() panic	crates/zclaw-runtime/src/tool/builtin/task.rs:59	移除 impl Default for TaskTool，或提供合理默认值

验收标准: 用户能在 UI 中执行一个 Skill 且不崩溃。

---

2. P1 集成修复（接通断链）

按以下顺序修复，每个修复后立即验证端到端：

2.1 API 路径对齐

ID	问题	修复
SEC2-P1-02	agent-templates 缺少 /api/v1 前缀	saas-client.ts:376,384 添加前缀
V11-P1-01	trigger_update 参数格式不匹配	kernel-triggers.ts:99 展开嵌套对象

2.2 事件监听补全

ID	问题	修复
SEC2-P1-03	hand-execution-complete 无前端监听	ChatArea/RightPanel 添加 listen()

2.3 静默错误消除

将所有 let _ = 错误忽略改为至少 log::warn!，逐个评估是否需要用户可见反馈：

• HandRun 持久化 (3 处) — 已修复
• FTS 索引更新 — 已修复
• Worker dispatch — 已修复
• Billing key usage — 已修复（移除冗余 let _ =）
• Relay SSE error send — 已修复（改为 if-let + debug log）

2.4 FactStore 实现

• 方案 A: MemoryStore 实现 FactStore trait
• 方案 B: 移除 FactStore trait，直接用 MemoryStore 方法
• 已选 B — 移除死 trait，保留值类型（已修复 SEC2-P1-01）

---

3. 死代码清理

3.1 删除（确认无引用后）

文件	行数	状态
desktop/src/lib/audit-logger.ts	170	已删除
desktop/src/lib/saas-admin.ts	234	已在之前清理中删除
desktop/src/lib/gateway-reconnect.ts	~100	已删除 (零生产引用)
admin/ 目录	~整目录	已删除 (空目录壳)
admin-temp-dir/ 目录	~整目录	已删除
crates/zclaw-channels/	Cargo.toml only	已在之前清理中删除
docs/analysis/ISSUE-TRACKER.md	-	已删除
.superpowers/plans/	-	已不存在

3.2 Feature-gate 清理

模块	行数	处理
Director (multi-agent)	912	已标注 — "gated behind multi-agent feature"
A2A 协议	~400	已标注 — feature gate 注释完整
WASM runner	~200	已标注 — "Active module — fully implemented"
OFP capability variants	~10	已修复 — 3 个方法改为穷举匹配，grants() 保留通配符+注释

3.3 未连接的 Tauri 命令

24 个 Tauri 命令无前端调用（经二次审计修正）。不删除 Rust 代码，但：

• 已完成: 171/171 个命令已标注 // @connected 或 // @reserved: 暂无前端集成
• 二次审计修正 19 个误标命令（8+11），当前 147 @connected / 24 @reserved

---

4. 文档真相校准

4.1 数值修正

指标	当前文档值	实际值	状态
Skills	66/75/77	75	已校准 (TRUTH.md)
Hands	11	9 启用 + 2 禁用	已校准 (CLAUDE.md)
Tauri 命令	58+/130+	171	已校准 + 171 个已标注（147 @connected / 24 @reserved）
SaaS 路由	72+	93（含 2 dev-only mock）	已校准
前端测试	1 文件	21 文件	已校准 (TRUTH.md)
Zustand Store	15	18	已校准 (TRUTH.md)
Admin V2 页面	11	13	已校准 (TRUTH.md)

4.2 文档归档

以下审计报告已从 docs/ 根目录移除（已归档或已删除）：

• COMPREHENSIVE_AUDIT_V5~V9（5 个文件，已被 V10/V11 取代）已完成
• AUDIT_TRACKER.md 已完成
• VERIFICATION_REPORT.md 已完成
• FEATURE_AUDIT_REPORT.md 已完成
• FRONTEND_INTEGRATION_AUDIT.md 已完成
• DEEP_AUDIT_REPORT.md 已完成
• JOINT_DEBUG_REPORT_V1.md 已完成
• QA_REVIEW_V1.md 已完成

4.3 ISSUED-TRACKER 重置

创建新的 docs/TRUTH.md，只记录：

• 实际可工作的端到端功能清单
• 已知缺陷清单（来自 V11 审计）
• 每次修复后更新此文件

---

5. 前端测试底线

在 P0/P1 修复完成后，为以下关键路径添加最基本测试：

1. Skill 执行 — 调用 → 不崩溃 → 返回结果
2. Hand 触发 — emit event → 前端收到通知
3. 消息发送 — Store → invoke → 流式响应
4. 配置同步 — SaaS pull → Store 更新

目标：从 1 个测试文件提升到至少覆盖 4 条核心路径。

---

6. 禁止事项

在稳定化完成前，以下行为被禁止：

行为	原因
新增 SaaS API 端点	已有 93 个，前端只调用了一部分
新增 SKILL.md 文件	已有 75 个，大部分未被调用
新增 Tauri 命令	已有 171 个，24 个无前端调用
新增中间件	已有 11 层，足够
扩展 Pipeline 模板	已有 10 个行业模板
新增 Zustand Store	已有 18 个
新增 admin 页面	已有 11 个

唯一例外: 修复 P0/P1 问题需要的新代码。

---

7. 完成标准

稳定化阶段完成的定义：

• P0 全部修复，用户可执行 Skill 不崩溃
• P1 集成修复完成，hand-execution-complete 有监听
• 死代码清理完成，至少删除 5 个孤立文件
• docs/TRUTH.md 创建并反映真实状态
• 文档数值与代码一致
• 前端测试覆盖 4 条核心路径
• cargo check --workspace 通过 + pnpm tsc --noEmit 通过

达到以上标准后，本指令自动降级为"建议"级别，恢复正常功能开发。

2026-04-03 确认: 全部 7 项标准已达标。功能冻结解除，恢复正常的迭代开发节奏。后续新增功能仍需遵循 CLAUDE.md §1.2 的决策原则（"这对用户今天能产生价值吗？"）。

---

8. 执行节奏

每个修复独立提交，格式：

fix(<scope>): <描述>

Stabilization: SEC2-P0-01

不批量提交。每个修复可独立 revert。