# ZCLAW 稳定化指令 v1.0

> **生效日期**: 2026-04-02
> **状态**: 强制执行
> **目标**: 将系统从"功能堆叠模式"切换到"端到端可用模式"

---

## 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. 完成标准

稳定化阶段完成的定义：

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

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

---

## 8. 执行节奏

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

```
fix(<scope>): <描述>

Stabilization: SEC2-P0-01
```

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