docs: stabilization directive + TRUTH document + AI session prompts + dockerignore
- STABILIZATION_DIRECTIVE.md: feature freeze rules, banned actions, priorities - TRUTH.md: single source of truth for system state (crate counts, store counts) - AI_SESSION_PROMPTS.md: three-layer prompt system for AI sessions - Industry agent delivery design spec - Stabilization test suite for regression prevention - Delete stale ISSUE-TRACKER.md - Add .dockerignore for container builds - Add brainstorm session artifacts
This commit is contained in:
iven
186
docs/STABILIZATION_DIRECTIVE.md
Normal file
186
docs/STABILIZATION_DIRECTIVE.md
Normal file
@@ -0,0 +1,186 @@
|
||||
# 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。
|
||||
Reference in New Issue
Block a user