docs: reorganize docs — archive outdated, create brainstorming folder

- Create docs/brainstorming/ with 5 discussion records (Mar 16 - Apr 7) - Archive ~30 outdated audit reports (V5-V11) to docs/archive/old-audits/ - Archive superseded analysis docs to docs/archive/old-analysis/ - Archive completed session plans to docs/archive/old-plans/ - Archive old test reports/validations to respective archive folders - Remove empty directories left after moves - Keep current docs: TRUTH.md, feature docs, deployment, knowledge-base, superpowers
2026-04-07 09:54:30 +08:00
parent 8e9fc54d92
commit 2e5f63be32
101 changed files with 1829 additions and 17 deletions
--- a/docs/archive/old-handoffs/2024-03-20-store-migration.md
+++ b/docs/archive/old-handoffs/2024-03-20-store-migration.md
@@ -0,0 +1,136 @@
+# Store Migration Progress Report
+
+**Date:** 2024-03-20
+**Status:** P0 Complete, P1 In Progress
+
+## Summary
+
+Successfully migrated all 14 components from `useGatewayStore` to domain-specific stores.
+
+## Completed Tasks
+
+### P0: Critical Path
+| Task | Status | Details |
+|------|--------|---------|
+| Store Migration | ✅ Complete | 14 components migrated |
+| gateway-client.ts Split | ✅ Complete | 4 modules: api, auth, storage, types |
+| E2E Verification | ✅ Complete | 312 tests passing |
+
+### P1: Quality Improvements
+| Task | Status | Details |
+|------|--------|---------|
+| viking-*.ts Cleanup | ✅ Complete | Archived to docs/archive/v1-viking-dead-code/ |
+| HeartbeatConfig UI | ✅ Complete | Integrated in SettingsLayout |
+| E2E Test Framework | 🔄 In Progress | Playwright config created |
+
+## Migration Details
+
+### Components Migrated
+1. **Security Components** (3)
+   - SecurityStatus.tsx → useConnectionStore, useSecurityStore
+   - AuditLogsPanel.tsx → useSecurityStore
+   - SecurityLayersPanel.tsx → useSecurityStore
+
+2. **Settings Components** (4)
+   - General.tsx → useConnectionStore, useConfigStore, useChatStore
+   - SettingsLayout.tsx → useSecurityStore
+   - Skills.tsx → useConnectionStore, useConfigStore
+   - IMChannels.tsx → useConfigStore, useConnectionStore, useAgentStore
+
+3. **Automation Components** (4)
+   - WorkflowEditor.tsx → useHandStore
+   - AutomationPanel.tsx → useHandStore, useWorkflowStore
+   - SchedulerPanel.tsx → useHandStore, useWorkflowStore, useAgentStore, useConfigStore
+   - CreateTriggerModal.tsx → useHandStore, useWorkflowStore
+
+4. **Other Components** (3)
+   - RightPanel.tsx → useHandStore, useAgentStore
+   - ChannelList.tsx → useConnectionStore, useConfigStore
+   - TaskList.tsx → useHandStore, useConfigStore
+
+### Store Architecture
+```
+connectionStore  - Gateway connection state
+configStore      - User configuration
+chatStore        - Chat messages and state
+agentStore       - Agent/clone management
+handStore        - Hands and triggers
+workflowStore    - Workflows
+securityStore    - Security status and audit logs
+teamStore        - Team collaboration
+```
+
+## Test Results
+- **Unit Tests:** 312/312 passing
+- **TypeScript:** No errors
+- **E2E Framework:** Playwright configured, ready for expansion
+
+## Next Steps
+1. ~~Expand E2E test coverage~~ ✅ Done (74 tests passing)
+2. ~~Implement Skill Market MVP (P2)~~ ✅ Already implemented
+3. Manual testing of full user flow
+
+## P2: Skill Market MVP
+
+**Status:** ✅ Already Complete
+
+The Skill Market MVP was already fully implemented:
+
+| Component | File | Status |
+|-----------|------|--------|
+| UI Component | `SkillMarket.tsx` | ✅ Complete |
+| State Store | `skillMarketStore.ts` | ✅ Complete |
+| Discovery Engine | `skill-discovery.ts` | ✅ Complete |
+| Types | `types/skill-market.ts` | ✅ Complete |
+| App Integration | `App.tsx` | ✅ Integrated |
+| Predefined Skills | 15 skills | ✅ Ready |
+
+### Features
+- Browse skills by category
+- Search by keyword/capability
+- View skill details
+- Install/uninstall skills
+- AI-powered skill suggestions
+- Persistent installation state
+
+## Technical Notes
+- All components now use selector pattern for Zustand
+- `useCompositeStore` deleted (was dead code)
+- `useGatewayStore` marked @deprecated, only used as compatibility layer
+
+---
+
+## 2026-03-20 Update
+
+### Additional Work Completed
+
+| Task | Status | Details |
+|------|--------|---------|
+| DevQALoop Integration | ✅ Complete | Integrated into TeamOrchestrator with new "Review" tab |
+| Integration Test Checklist | ✅ Complete | Created docs/testing/INTEGRATION-CHECKLIST.md with 22 test cases |
+| Component Status Analysis | ✅ Complete | Created docs/analysis/COMPONENT-INTEGRATION-STATUS.md |
+
+### DevQALoop Integration Details
+
+The DevQALoop component was previously implemented but not integrated into any parent component. Added:
+- New "Review" tab in TeamOrchestrator
+- Import of DevQALoopPanel component
+- Display of active Dev↔QA loops with iteration tracking
+- Start Review Loop button for teams with tasks and members
+
+### Files Modified
+- `desktop/src/components/TeamOrchestrator.tsx` - Added Review view and DevQALoopPanel integration
+
+### Files Created
+- `docs/testing/INTEGRATION-CHECKLIST.md` - Comprehensive integration test checklist
+- `docs/analysis/COMPONENT-INTEGRATION-STATUS.md` - Component integration status report
+
+### Key Findings from Analysis
+
+1. **PersonalitySelector** ✅ Already integrated via AgentOnboardingWizard
+2. **ScenarioTags** ✅ Already integrated via AgentOnboardingWizard
+3. **DevQALoop** ✅ Now integrated into TeamOrchestrator
+4. **HeartbeatConfig** ✅ Already integrated in SettingsLayout
+5. **CreateTriggerModal** ✅ Already migrated to useHandStore
+
+The documentation in `ZCLAW-DEEP-ANALYSIS.md` underestimated the actual integration completeness. Most components were already integrated through indirect paths.
--- a/docs/archive/old-handoffs/2026-03-21-phase1-security.md
+++ b/docs/archive/old-handoffs/2026-03-21-phase1-security.md
@@ -0,0 +1,133 @@
+# Phase 1: Security + Testing
+
+> Date: 2026-03-21
+> Status: Complete
+
+## Overview
+
+This phase establishes the security foundation and testing framework for the ZCLAW architecture optimization project. It implements encrypted credential storage and enforces secure WebSocket connections.
+
+## Changes
+
+### Security Enhancements
+
+#### 1. Encrypted localStorage Fallback (`secure-storage.ts`)
+
+- **Issue**: Credentials were stored in plaintext in localStorage when OS keyring was unavailable
+- **Solution**: Implemented AES-GCM encryption for localStorage fallback
+- **Details**:
+  - Added `crypto-utils.ts` with encryption/decryption functions
+  - Uses PBKDF2 (100,000 iterations) for key derivation
+  - Uses AES-GCM (256-bit) for encryption
+  - Unique IV per encryption operation
+  - Backward compatible with existing unencrypted data
+
+#### 2. WSS Enforcement (`gateway-client.ts`)
+
+- **Issue**: Non-localhost connections could use insecure `ws://` protocol
+- **Solution**: Block non-localhost connections that don't use WSS
+- **Details**:
+  - Added `SecurityError` class for clear error handling
+  - Added `validateWebSocketSecurity()` function
+  - Throws error for `ws://` connections to non-localhost hosts
+  - Allows `ws://` for localhost (development convenience)
+  - Allows `wss://` for any host
+
+### Testing Infrastructure
+
+#### 1. Vitest Framework Setup
+
+- Installed Vitest 2.1.8 with jsdom environment
+- Added @testing-library/react for component testing
+- Added @testing-library/jest-dom for DOM matchers
+- Configured coverage thresholds (60% initial target)
+
+#### 2. Test Files Created
+
+| File | Tests | Coverage |
+|------|-------|----------|
+| `crypto-utils.test.ts` | 10 | arrayToBase64, base64ToArray, encrypt, decrypt, deriveKey, generateMasterKey |
+| `secure-storage.test.ts` | 11 | Encryption fallback, backward compatibility, special characters |
+| `gateway-security.test.ts` | 13 | isLocalhost, WSS enforcement, SecurityError |
+| `chatStore.test.ts` | 39 | Messages, conversations, agents, streaming |
+
+## Files Changed
+
+### New Files
+
+```
+desktop/
+├── src/lib/crypto-utils.ts          # AES-GCM encryption utilities
+├── tests/lib/crypto-utils.test.ts   # Encryption tests
+├── tests/lib/secure-storage.test.ts # Secure storage tests
+├── tests/lib/gateway-security.test.ts # WSS security tests
+├── tests/setup.ts                   # Vitest setup with mocks
+└── vitest.config.ts                 # Vitest configuration
+```
+
+### Modified Files
+
+```
+desktop/
+├── src/lib/secure-storage.ts        # Added encryption fallback
+├── src/lib/gateway-client.ts        # Added WSS enforcement
+└── package.json                     # Added test dependencies
+```
+
+## Migration Notes
+
+- **Automatic Migration**: Existing unencrypted localStorage data will be automatically migrated on first read
+- **No Manual Intervention**: The encryption/decryption is transparent to users
+- **Key Generation**: A master key is automatically generated and stored in localStorage
+
+## Breaking Changes
+
+### WSS Required for Remote Connections
+
+- `ws://` protocol is no longer allowed for non-localhost connections
+- **Impact**: Users connecting to remote servers must use `wss://`
+- **Migration**: Update gateway URLs to use `wss://` protocol
+
+```javascript
+// Before (now throws SecurityError)
+const client = new GatewayClient('ws://example.com:4200/ws');
+
+// After (required)
+const client = new GatewayClient('wss://example.com:4200/ws');
+
+// Localhost still works with ws://
+const client = new GatewayClient('ws://localhost:4200/ws'); // OK
+```
+
+## Test Results
+
+```
+Test Files  4 passed (4)
+Tests       73 passed (73)
+
+New modules coverage:
+- crypto-utils.ts:     100%
+- secure-storage.ts:   95%+
+- gateway-security:    100%
+- chatStore.ts:        80%+
+```
+
+## Security Verification
+
+- [x] localStorage credentials encrypted (AES-GCM)
+- [x] Non-localhost connections require WSS
+- [x] Encryption keys not exposed in logs
+- [x] Backward compatible with unencrypted data
+- [x] Unique IV per encryption operation
+
+## Next Steps (Phase 2)
+
+- Domain reorganization
+- Migrate Chat Store to Valtio
+- Migrate Hands Store + XState
+- Enhance Intelligence caching
+- Extract shared modules
+
+---
+
+*Generated by Claude Code - Phase 1 Implementation*
--- a/docs/archive/old-handoffs/WORK_SUMMARY_2026-03-16.md
+++ b/docs/archive/old-handoffs/WORK_SUMMARY_2026-03-16.md
@@ -0,0 +1,193 @@
+# ZCLAW 工作总结 - 2026-03-16
+
+## 完成的工作
+
+### 1. OpenViking 本地服务器管理（隐私优先部署）
+
+**问题**：用户可能有隐私顾虑，会话数据不能上传到远程服务器。
+
+**解决方案**：实现本地 OpenViking 服务器管理功能。
+
+#### 新增文件
+
+| 文件 | 功能 |
+|------|------|
+| `desktop/src-tauri/src/viking_server.rs` | Rust 后端服务器管理（启动/停止/状态） |
+| `desktop/src/lib/viking-server-manager.ts` | TypeScript 服务器管理客户端 |
+| `desktop/src/lib/viking-adapter.ts` | 更新为多模式适配器（local/sidecar/remote） |
+
+#### 功能特性
+
+- **自动模式检测**：优先尝试本地服务器 → sidecar → remote
+- **隐私保证**：所有数据存储在 `~/.openviking/`，服务器只监听 `127.0.0.1`
+- **优雅降级**：当本地服务器不可用时自动回退
+
+#### Tauri 命令
+
+```rust
+viking_server_status()   // 获取服务器状态
+viking_server_start()    // 启动本地服务器
+viking_server_stop()     // 停止服务器
+viking_server_restart()  // 重启服务器
+```
+
+### 2. 文档整理与归档
+
+**之前**：文档散落在多个位置，文件名混乱（如 `greedy-prancing-cocke.md`）
+
+**之后**：规范化文档结构
+
+```
+docs/
+├── DEVELOPMENT.md                    # 开发指南
+├── OPENVIKING_INTEGRATION.md         # OpenViking 集成文档（已更新）
+├── USER_MANUAL.md                    # 用户手册
+├── ZCLAW_AGENT_INTELLIGENCE_EVOLUTION.md  # Agent 进化计划
+├── archive/                          # 归档文档
+│   ├── completed-plans/              # 已完成的计划
+│   ├── research-reports/             # 研究报告
+│   └── zclaw-legacy/              # ZCLAW 遗留文档
+├── knowledge-base/                   # 技术知识库
+│   ├── zclaw-technical-reference.md
+│   ├── zclaw-websocket-protocol.md
+│   └── ...
+├── plans/                            # 执行计划
+└── test-reports/                     # 测试报告
+```
+
+### 3. 测试验证
+
+| 测试类型 | 结果 |
+|---------|------|
+| TypeScript 编译 | ✅ 无错误 |
+| Viking Adapter 测试 | ✅ 21 passed |
+| Rust 测试 | ✅ 10 passed |
+| Cargo Build | ✅ 成功 |
+| OpenViking 服务器启动 | ✅ 成功（端口 1933） |
+| API 健康检查 | ✅ `/health` 返回 `{"status":"ok"}` |
+| 会话创建 | ✅ 成功 |
+| 消息添加 | ✅ 成功 |
+
+## 提交记录
+
+```
+c8202d0 feat(viking): add local server management for privacy-first deployment
+```
+
+## 当前项目状态
+
+### 已完成
+
+- [x] Agent 智能层 Phase 1-3（274 passing tests）
+- [x] OpenViking 本地服务器管理
+- [x] 文档结构整理
+- [x] Python 3.12 安装（通过 winget）
+- [x] OpenViking pip 安装成功（v0.2.6）
+- [x] 火山引擎 API 密钥配置
+- [x] OpenViking 服务器启动验证
+- [x] 基础 API 测试（健康检查、会话创建、消息添加）
+- [x] **火山引擎 Embedding 模型激活** (`ep-20260316102010-cq422`)
+- [x] **向量搜索功能验证** ✅
+
+### 进行中
+
+- [ ] 多 Agent 协作 UI 产品化
+
+### 待办
+
+- [ ] RuntimeAdapter 接口抽象
+- [ ] 领域模型标准化
+
+## OpenViking 集成状态
+
+### 已验证功能
+
+| 功能 | 状态 | 说明 |
+|------|------|------|
+| 服务器启动 | ✅ | `http://127.0.0.1:1933` |
+| 健康检查 | ✅ | `GET /health` → `{"status":"ok"}` |
+| 系统状态 | ✅ | `GET /api/v1/system/status` |
+| 会话创建 | ✅ | `POST /api/v1/sessions` |
+| 消息添加 | ✅ | `POST /api/v1/sessions/{id}/messages` |
+| 向量搜索 | ⚠️ | 需要激活 Embedding 模型 |
+
+### ✅ 已解决：火山引擎 Embedding 模型激活
+
+**Endpoint ID**: `ep-20260316102010-cq422`
+
+**配置文件** (`~/.openviking/ov.conf`)：
+```json
+{
+  "embedding": {
+    "dense": {
+      "api_base": "https://ark.cn-beijing.volces.com/api/v3",
+      "api_key": "3739b6b2-2bff-4a13-9f82-c0674dd4a05e",
+      "provider": "volcengine",
+      "model": "ep-20260316102010-cq422",
+      "dimension": 1024
+    }
+  }
+}
+```
+
+**验证结果**：
+- 向量搜索 API: ✅ 正常
+- 会话创建: ✅ 正常
+- 消息添加: ✅ 正常
+- TypeScript 测试: ✅ 21 passed
+
+### 备选方案：使用 OpenAI Embedding
+
+如果不想激活火山引擎 Embedding，可以改用 OpenAI：
+
+```json
+{
+  "embedding": {
+    "dense": {
+      "api_base": "https://api.openai.com/v1",
+      "api_key": "${OPENAI_API_KEY}",
+      "provider": "openai",
+      "model": "text-embedding-3-small",
+      "dimension": 1536
+    }
+  }
+}
+```
+
+## 配置文件
+
+当前配置 (`~/.openviking/ov.conf`)：
+
+```json
+{
+  "storage": {
+    "workspace": "C:/Users/szend/.openviking/workspace",
+    "vectordb": { "name": "context", "backend": "local" },
+    "agfs": { "port": 1833, "log_level": "warn", "backend": "local" }
+  },
+  "embedding": {
+    "dense": {
+      "api_base": "https://ark.cn-beijing.volces.com/api/v3",
+      "api_key": "3739b6b2-2bff-4a13-9f82-c0674dd4a05e",
+      "provider": "volcengine",
+      "dimension": 1024,
+      "model": "doubao-embedding"
+    }
+  },
+  "server": { "host": "127.0.0.1", "port": 1933 }
+}
+```
+
+## 文件变更统计
+
+- 新增文件：4 个
+- 修改文件：3 个
+- 归档文件：10+ 个
+- 文档更新：2 个
+
+## 下一步工作
+
+1. **完成 Embedding 模型激活**（阻塞项）
+2. 验证向量搜索功能
+3. 测试 ZCLAW 记忆面板集成
+4. 提交完整集成代码
--- a/docs/archive/old-handoffs/handoff-agent-onboarding-2026-03-16.md
+++ b/docs/archive/old-handoffs/handoff-agent-onboarding-2026-03-16.md
@@ -0,0 +1,142 @@
+# Agent 人格设置引导功能 - 会话交接文档
+
+> **创建时间**: 2026-03-16
+> **状态**: Phase 2 进行中
+
+---
+
+## 一、功能概述
+
+为 ZCLAW 添加类似 ZCLAW 的 Agent 创建引导向导，包括人格风格设置、Emoji 选择、使用场景标签选择等。
+
+**计划文档**: `plans/vast-stirring-wilkinson.md`
+
+---
+
+## 二、已完成工作
+
+### Phase 1: 数据层 ✅ 已完成
+
+1. **扩展 Clone 接口** (`desktop/src/store/agentStore.ts`)
+   - 添加字段: `emoji`, `personality`, `communicationStyle`, `notes`, `onboardingCompleted`
+
+2. **扩展 Clone 和 QuickConfig 接口** (`desktop/src/store/gatewayStore.ts`)
+   - 添加相同的人格相关字段
+
+3. **创建人格预设配置** (`desktop/src/lib/personality-presets.ts`)
+   - `PERSONALITY_OPTIONS`: 4种人格风格 (专业严谨/友好亲切/创意灵活/简洁高效)
+   - `SCENARIO_TAGS`: 9个使用场景标签 (编程开发/内容写作/产品策划等)
+   - `EMOJI_PRESETS`: Emoji 预设分组 (动物/物体/表情)
+   - `QUICK_START_SUGGESTIONS`: 首次对话快速建议
+   - 辅助函数: `generateWelcomeMessage`, `generateSoulContent`, `generateUserContent`
+
+### Phase 2: 核心组件 ✅ 已完成
+
+1. **EmojiPicker** (`desktop/src/components/ui/EmojiPicker.tsx`)
+   - 分类标签 (全部/动物/物体/表情)
+   - 8列网格布局
+   - 选中状态显示
+
+2. **PersonalitySelector** (`desktop/src/components/PersonalitySelector.tsx`)
+   - 4种人格卡片选择
+   - 特质标签显示
+   - `PersonalityBadge` 显示组件
+
+3. **ScenarioTags** (`desktop/src/components/ScenarioTags.tsx`)
+   - 多选标签
+   - 最多选择5个
+   - `ScenarioBadges` 显示组件
+
+4. **AgentOnboardingWizard** (`desktop/src/components/AgentOnboardingWizard.tsx`)
+   - 5步向导: 认识用户 → Agent身份 → 人格风格 → 使用场景 → 工作环境
+   - 进度条显示
+   - 表单验证
+   - 配置预览
+   - 创建提交
+
+---
+
+## 三、待完成工作
+
+### Phase 3: 集成 (优先级高)
+
+1. **修改 CloneManager** (`desktop/src/components/CloneManager.tsx`)
+   - 集成 AgentOnboardingWizard 模态框
+   - 替换或增强现有的内联表单
+
+2. **实现 FirstConversationPrompt**
+   - 创建 `desktop/src/components/FirstConversationPrompt.tsx`
+   - 显示个性化欢迎消息
+   - 显示快速开始建议按钮
+   - 集成到 `ChatArea.tsx`
+
+3. **修改 RightPanel** (`desktop/src/components/RightPanel.tsx`)
+   - 显示 Agent 的 emoji
+   - 显示人格风格标签
+   - 显示使用场景标签
+
+### Phase 4: 测试
+
+1. 测试创建流程
+2. 测试持久化
+3. 测试首次对话引导
+
+---
+
+## 四、关键文件路径
+
+```
+desktop/src/
+├── components/
+│   ├── AgentOnboardingWizard.tsx  # ✅ 已创建
+│   ├── PersonalitySelector.tsx    # ✅ 已创建
+│   ├── ScenarioTags.tsx           # ✅ 已创建
+│   ├── CloneManager.tsx           # 🔧 需修改
+│   ├── ChatArea.tsx               # 🔧 需修改
+│   └── RightPanel.tsx             # 🔧 需修改
+├── components/ui/
+│   └── EmojiPicker.tsx            # ✅ 已创建
+├── lib/
+│   └── personality-presets.ts     # ✅ 已创建
+└── store/
+    ├── agentStore.ts              # ✅ 已修改
+    └── gatewayStore.ts            # ✅ 已修改
+```
+
+---
+
+## 五、参考资源
+
+- ZCLAW 快速配置: `docs/archive/zclaw-legacy/autoclaw界面/html版/4.html`
+- ZCLAW Agent 面板: `docs/archive/zclaw-legacy/autoclaw界面/html版/3.html`
+- 现有 Modal 模式: `desktop/src/components/CreateTriggerModal.tsx`
+
+---
+
+## 六、新会话提示词
+
+```
+我正在实现 ZCLAW 的 Agent 人格设置引导功能，参考 ZCLAW 的设计。
+
+**当前进度**:
+- Phase 1 (数据层) ✅ 已完成
+- Phase 2 (核心组件) ✅ 已完成
+- Phase 3 (集成) ⏳ 待开始
+- Phase 4 (测试) ⏳ 待开始
+
+**已完成的文件**:
+- `desktop/src/store/agentStore.ts` - 扩展了 Clone 接口
+- `desktop/src/store/gatewayStore.ts` - 扩展了 Clone 和 QuickConfig 接口
+- `desktop/src/lib/personality-presets.ts` - 人格预设配置
+- `desktop/src/components/ui/EmojiPicker.tsx` - Emoji 选择器
+- `desktop/src/components/PersonalitySelector.tsx` - 人格选择器
+- `desktop/src/components/ScenarioTags.tsx` - 场景标签选择器
+- `desktop/src/components/AgentOnboardingWizard.tsx` - 向导主组件
+
+**下一步工作**:
+1. 修改 `CloneManager.tsx` 集成 AgentOnboardingWizard
+2. 创建 `FirstConversationPrompt.tsx` 并集成到 ChatArea
+3. 修改 `RightPanel.tsx` 显示人格信息
+
+请继续完成 Phase 3 的集成工作。详细计划见 `plans/vast-stirring-wilkinson.md`。
+```
--- a/docs/archive/old-handoffs/handoff-audit-fix-2026-03-26.md
+++ b/docs/archive/old-handoffs/handoff-audit-fix-2026-03-26.md
@@ -0,0 +1,223 @@
+# 功能审计修复 — 会话交接文档
+
+> **创建时间**: 2026-03-26
+> **审计报告**: `plans/piped-wondering-thompson.md`
+> **旧审计对比**: `docs/analysis/FEATURE-INTEGRITY-AUDIT.md`（含 6 处事实错误，勿参考）
+
+---
+
+## 背景
+
+对 ZCLAW 全系统 12 个子系统执行了五步审计（文档对齐→追踪数据流→识别dead_code→检查trait实现→端到端验证），发现 19 处差距、22 处 dead_code、8 项文档不一致。核心问题模式：**"写了没接"** — 大量代码已实现但从未接入实际运行流程。
+
+---
+
+## 修复任务清单（严格按优先级执行）
+
+### P0 — 影响核心功能可用性
+
+#### P0-1: Context Compaction 内核集成
+
+**问题**: 上下文压缩仅在前端 `chatStore.ts` 执行，`kernel.rs` 的 `send_message_stream()` 不感知压缩，LLM 实际收到完整历史，前端压缩只是视觉隐藏。
+
+**差距模式**: 双系统不同步
+
+**修复路径**:
+- `crates/zclaw-kernel/src/kernel.rs` — 在 `send_message_stream()` 中添加 token 估算 + 阈值检查 + 压缩逻辑
+- 参考前端实现: `desktop/src/store/chatStore.ts:333-359`（`checkThreshold` + `compact`）
+- 参考后端压缩器: `desktop/src-tauri/src/intelligence/compactor.rs`（462 行，已有完整实现）
+- 修复后删除前端 `chatStore.ts` 中的重复压缩调用，改为依赖内核
+
+**验证**: 发送 20+ 条消息后，检查发给 LLM 的实际 context 长度是否被压缩
+
+---
+
+#### P0-2: 文档虚假声称清理
+
+**问题**: README、CLAUDE.md 中多处状态描述与代码不符
+
+**修复清单**:
+| 文件 | 行/位置 | 当前声称 | 应改为 |
+|------|---------|---------|-------|
+| `CLAUDE.md` | 项目结构 crates 列表 | `zclaw-channels (Telegram, Discord, Slack)` | `zclaw-channels (仅 ConsoleChannel 测试适配器)` |
+| `CLAUDE.md` | Hands 表格 Lead 行 | `✅ 可用` | `❌ 仅有配置文件，无 Rust 实现` |
+| `CLAUDE.md` | Hands 表格 Predictor 行 | `✅ 可用` | `❌ 仅有配置文件，无 Rust 实现` |
+| `docs/features/README.md` | Hands 统计 | `9 implemented = 82%` | `7 fully working, 2 config-only (Lead/Predictor)` |
+| `docs/features/README.md` | Lead/Predictor 注册状态 | 标记为已注册 | 标记为未实现 |
+| `docs/features/06-context-compaction.md` | 成熟度标签 | L4 Production | L2 (前端仅视觉压缩，内核未集成) |
+| `docs/features/README.md` | 删除引用 6 个不存在的文档链接 | 01-vector-memory.md 等 | 删除这些引用 |
+
+**验证**: `rg "Lead|Predictor|Telegram|Discord|Slack" CLAUDE.md` 确认已修正
+
+---
+
+#### P0-3: Quiz Hand 占位符生成器替换
+
+**问题**: `DefaultQuizGenerator` 生成 "Question N about X" / "Option A/B/C/D"，正确答案永远是 Option A
+
+**修复路径**:
+- `crates/zclaw-hands/src/hands/quiz.rs:35-68` — 替换 `DefaultQuizGenerator::generate()` 实现
+- 利用已有的 `QuizGenerator` trait（同文件），实现 LLM 驱动的生成器
+- 参考同类模式: `crates/zclaw-runtime/src/tools/web_fetch.rs` 中的 LLM 调用方式
+- 生成器需要接收 LLM driver 引用（通过 `QuizHand::new()` 或 `with_generator()` 传入）
+
+**验证**: 触发 Quiz Hand，检查生成的题目是否有真实内容和随机正确答案
+
+---
+
+### P1 — 减少技术债务
+
+#### P1-1: Intelligence 死代码清理
+
+**问题**: 4 个模块有完整代码但从未被前端调用
+
+**清理清单**:
+| 文件 | 大小 | Tauri 命令数 | 前端调用 | 建议 |
+|------|------|------------|---------|------|
+| `desktop/src-tauri/src/intelligence/mesh.rs` | ~300+ 行 | 8 个 | 0 | 删除或移到 `#[cfg(feature = "experimental")]` |
+| `desktop/src-tauri/src/intelligence/persona_evolver.rs` | ~300+ 行 | 7 个 | 0 | 同上 |
+| `desktop/src-tauri/src/intelligence/pattern_detector.rs` | ~200+ 行 | 0 | 0 | 删除 |
+| `desktop/src-tauri/src/intelligence/trigger_evaluator.rs` | ~500+ 行 | 0 | 0 | 删除 |
+
+**注意**: `recommender.rs` **不是**死代码（被 `mesh.rs` 使用），但若 mesh.rs 被移除则 recommender 也变为死代码。
+
+**修复步骤**:
+1. 删除上述 4 个文件
+2. 从 `desktop/src-tauri/src/intelligence/mod.rs` 移除对应 `pub mod` 声明
+3. 从 `desktop/src-tauri/src/lib.rs` invoke_handler 移除对应 15 个命令注册（mesh 8 个 + persona_evolver 7 个）
+4. 运行 `cargo check` 确认编译通过
+
+**验证**: `cargo check` + `rg "mesh_|persona_evolver_|pattern_detector|trigger_evaluator" desktop/src-tauri/src/`
+
+---
+
+#### P1-2: Heartbeat Engine 整理
+
+**问题**: Heartbeat 实际完成度 ~75%（App.tsx 启动时调用 init/start，有 tokio 定时循环），但 `trigger_evaluator` 子模块为死代码
+
+**修复路径**:
+- 若 P1-1 已删除 trigger_evaluator，则 Heartbeat 中对它的引用也需要处理
+- 检查 `heartbeat.rs` 中是否有对 `trigger_evaluator` 的 import，若有则移除
+- 移除 `heartbeat.rs` 的 `#![allow(dead_code)]`（既然模块是活的，不需要此标记）
+- 确认 `heartbeat_tick` 中 trigger 评估逻辑降级为简单实现
+
+**验证**: `cargo check` + 启动应用确认 heartbeat 仍正常运行
+
+---
+
+#### P1-3: Identity 持久化
+
+**问题**: `AgentIdentityManager` 使用 InMemory 存储，重启后身份数据丢失
+
+**修复路径**:
+- `desktop/src-tauri/src/intelligence/identity.rs` — 将 InMemory 存储替换为 SQLite
+- 参考已有的持久化模式: `crates/zclaw-growth/src/storage/sqlite.rs`
+- SOUL.md 内容、人格预设、变更提案历史需要持久化到 SQLite 表
+- 启动时从 SQLite 恢复状态
+
+**验证**: 设置人格后重启应用，检查人格是否保留
+
+---
+
+#### P1-4: Channels 文档修正
+
+**问题**: CLAUDE.md 声称 zclaw-channels 支持 Telegram/Discord/Slack，实际只有 ConsoleChannel
+
+**修复路径**:
+- 已在 P0-2 中覆盖（同一处 CLAUDE.md 修改）
+
+---
+
+### P2 — 改善开发体验
+
+#### P2-1: KernelConfig::load() 实现
+
+**问题**: `crates/zclaw-kernel/src/config.rs:256-259` 的 `load()` 始终返回 `Self::default()`
+
+**修复路径**:
+- 实现 TOML 文件读取（项目已依赖 `toml` crate）
+- 默认路径: `~/.zclaw/config.toml` 或项目根 `config/config.toml`
+- 支持 `${VAR_NAME}` 环境变量插值（参考 `desktop/src/lib/toml-utils.ts`）
+- 保留 `from_provider()` 作为运行时覆盖
+
+**验证**: 修改 config.toml 中的某个值，重启后端确认生效
+
+---
+
+#### P2-2: PPTX/PDF 导出修复或明确禁用
+
+**问题**: Pipeline 的 ActionRegistry 对 PPTX/PDF 返回 "feature in development" 错误
+
+**修复路径**（二选一）:
+- **方案 A**: 修复导出 — `crates/zclaw-kernel/src/export/pptx.rs` 已有实现，检查为什么 Pipeline 层面报错
+- **方案 B**: 明确禁用 — 从 Pipeline 前端 UI 中隐藏 PPTX/PDF 选项，避免用户触发报错
+
+**验证**: 在 Pipeline 编辑器中尝试 PPTX 导出
+
+---
+
+#### P2-3: Embedding 搜索统一
+
+**问题**: 向量嵌入仅连接到 Viking 侧车存储，内核原生 MemoryStore 不使用
+
+**修复路径**:
+- `desktop/src-tauri/src/embedding_adapter.rs` 已实现 EmbeddingClient trait
+- 将相同 adapter 注入到 `zclaw-growth` 的 `SemanticScorer`（已有 `with_embedding()` 方法）
+- 在 `intelligence_hooks.rs` 的 `build_memory_context()` 中启用嵌入搜索
+
+**验证**: 配置 embedding provider 后，搜索记忆时确认使用了向量搜索
+
+---
+
+## 不在本次修复范围的事项
+
+| 项目 | 原因 |
+|------|------|
+| 新增 Telegram/Discord/Slack 适配器 | 需求未确认，工作量大于修复 |
+| Pipeline 智能路由（01-intelligent-routing.md） | 纯新功能，非修复 |
+| WASM/Native 技能执行模式 | 纯新功能 |
+| Agent 导入/导出、模板库 | 纯新功能 |
+| 生物识别支持 | 纯新功能 |
+| 旧报告提到的 6 个 404 API 端点 | ZCLAW 是 Tauri 桌面应用，不走 HTTP API，这些端点不适用 |
+
+---
+
+## 验证命令速查
+
+```bash
+# 编译检查（每次修改后必跑）
+cargo check 2>&1 | grep -i "warning\|error"
+
+# TypeScript 类型检查
+cd desktop && pnpm tsc --noEmit
+
+# 单元测试
+cargo test -p zclaw-growth 2>&1 | tail -5
+cd desktop && pnpm vitest run
+
+# 验证文档修正
+rg "Lead.*可用|Predictor.*可用|Telegram|Discord|Slack" CLAUDE.md
+
+# 验证死代码清理
+rg "mesh_|persona_evolver_|pattern_detector|trigger_evaluator" desktop/src-tauri/src/
+
+# 验证 heartbeat 清理
+rg "allow\(dead_code\)" desktop/src-tauri/src/intelligence/heartbeat.rs
+```
+
+---
+
+## 关键文件索引
+
+| 文件 | 用途 |
+|------|------|
+| `plans/piped-wondering-thompson.md` | 完整审计报告（本文档的详细版本） |
+| `crates/zclaw-kernel/src/kernel.rs` | 内核，P0-1 修改目标 |
+| `crates/zclaw-hands/src/hands/quiz.rs` | Quiz Hand，P0-3 修改目标 |
+| `desktop/src-tauri/src/intelligence/` | 智能层，P1-1/P1-2 修改目标 |
+| `desktop/src-tauri/src/intelligence/identity.rs` | 身份管理，P1-3 修改目标 |
+| `desktop/src-tauri/src/lib.rs:1376-1566` | Tauri 命令注册表 |
+| `desktop/src-tauri/src/intelligence_hooks.rs` | 智能 hooks 集成点 |
+| `crates/zclaw-kernel/src/config.rs:256-259` | 配置加载，P2-1 修改目标 |
+| `CLAUDE.md` | 项目文档，P0-2 修改目标 |
+| `docs/features/README.md` | 功能索引，P0-2 修改目标 |