zclaw_openfang/plans/abundant-frolicking-ember.md

# ZCLAW 功能完善计划

## 背景

根据功能验证结果，ZCLAW 项目存在以下需要完善的问题：

| 问题 | 严重程度 | 影响范围 |
|------|---------|---------|
| **Hands 后端缺失** | 高 | 10/11 Hands 不可用 |
| **Skills 动态扫描未实现** | 中 | 61 个技能无法被发现 |
| **自主授权模块分散** | 中 | 功能不完整 |
| **LLM 集成未激活** | 中 | 高级功能受限 |
| **向量嵌入未使用** | 低 | 语义搜索不可用 |

---

## 一、Hands 后端实现计划

### 1.1 实现优先级

| 优先级 | Hand | 复杂度 | 工作量 | 理由 |
|--------|------|--------|--------|------|
| **P1** | Slideshow | 低 | 2-3天 | 实现简单，教育场景价值高 |
| **P1** | Speech | 低 | 2-3天 | 实现简单，无障碍功能 |
| **P1** | Quiz | 中 | 3-4天 | 教育场景核心功能 |
| **P1** | Researcher | 中 | 3-5天 | 核心能力，用户需求高 |
| **P1** | Collector | 中 | 3-5天 | 与 Researcher 协同 |
| **P2** | Whiteboard | 中 | 4-6天 | 教育场景 |
| **P2** | Clip | 高 | 5-7天 | 依赖 FFmpeg |
| **P2** | Twitter | 中 | 3-5天 | 需要外部 API Key |
| **P3** | Lead | 高 | 7-10天 | 依赖多个付费 API |
| **P3** | Predictor | 高 | 7-14天 | ML 复杂度高 |

### 1.2 公共模块提取

```
desktop/src-tauri/src/hands/
├── mod.rs              # 模块导出
├── common/
│   ├── http_client.rs  # HTTP 客户端 (供 Researcher/Collector/Lead/Twitter)
│   ├── html_parser.rs  # HTML 解析 (供 Researcher/Collector)
│   ├── scheduler.rs    # 任务调度 (供支持 schedule 的 Hands)
│   └── approval.rs     # 审批流程 (供 requires_approval 的 Hands)
├── slideshow/          # P1 - 幻灯片控制
├── speech/             # P1 - 语音合成
├── quiz/               # P1 - 测验系统
├── researcher/         # P1 - 深度研究
└── collector/          # P1 - 数据收集
```

### 1.3 参考实现

Browser Hand 已有完整实现，位于 `desktop/src-tauri/src/browser/`：
- `client.rs` - 核心客户端 (494行)
- `session.rs` - 会话管理 (191行)
- `commands.rs` - Tauri 命令 (534行)
- `actions.rs` - 动作定义 (314行)
- `error.rs` - 错误类型 (90行)

---

## 二、Skills 动态扫描实现计划

### 2.1 当前问题

- 存在 73 个 SKILL.md 文件
- `skill-discovery.ts` 使用静态 `BUILT_IN_SKILLS` 数组（仅 12 个）
- Rust 后端 `SkillRegistry.discover_skills()` 已存在但未连接到 Tauri

### 2.2 实现方案

**方案：后端扫描 + Tauri 命令暴露**

```
Tauri 启动
    ↓
kernel_init()
    ↓
SkillRegistry::add_skill_dir("skills/")
    ↓
discover_skills() + parse_skill_md()
    ↓
kernel_list_skills 命令暴露
    ↓
前端调用 Tauri 命令
```

### 2.3 实现任务

| 任务 | 文件 | 工作量 |
|------|------|--------|
| 增强 SKILL.md 解析器 | `crates/zclaw-skills/src/loader.rs` | 2-4小时 |
| 添加 skill_registry 到 Kernel | `crates/zclaw-kernel/src/kernel.rs` | 2-4小时 |
| 创建 kernel_list_skills 命令 | `desktop/src-tauri/src/kernel_commands.rs` | 1-2小时 |
| 更新前端调用 | `desktop/src/store/configStore.ts` | 2-3小时 |
| 添加索引缓存 | 新建文件 | 2-4小时 |

**总工作量**: 9-17 小时

---

## 三、智能层功能完善计划

### 3.1 自主授权管理器

**当前状态**: 功能分散在 `HeartbeatConfig.proactivity_level`

**实现任务**:

| 任务 | 工作量 |
|------|--------|
| 创建 `autonomy_manager.rs` 模块 | 3天 |
| 定义操作风险分级 | 1天 |
| 扩展审批流程 | 2天 |

**新建文件**: `desktop/src-tauri/src/intelligence/autonomy.rs`

```rust
pub enum AutonomyLevel {
    Supervised,   // 所有操作需确认
    Assisted,     // 低风险自动，中高风险需确认
    Autonomous,   // 低中风险自动，高风险需确认
}

pub enum RiskLevel {
    Low,    // memory_save, reflection_run
    Medium, // hand_trigger, skill_install
    High,   // memory_delete, identity_update
}
```

### 3.2 LLM 集成激活

**当前状态**:
- `compactor.rs`: `use_llm: false`
- `reflection.rs`: `use_llm: true` 但未实际调用

**实现任务**:

| 任务 | 工作量 |
|------|--------|
| 定义 LLM 客户端接口 | 2天 |
| 实现 Compactor LLM 摘要 | 2天 |
| 实现 Reflection LLM 分析 | 3天 |
| 添加降级策略 | 1天 |

### 3.3 向量嵌入

**当前状态**: `PersistentMemory.embedding` 字段已定义但未使用

**实现任务**:

| 任务 | 工作量 |
|------|--------|
| 选择并集成 Embedding 模型 | 2天 |
| 实现语义搜索 | 2天 |
| 添加 FTS5 全文搜索 | 1天 |
| 实现混合搜索 | 2天 |

**推荐模型**: `paraphrase-multilingual-MiniLM-L12-v2` (支持中文, 118MB)

---

## 四、实施时间线

### Week 1-2: P0 基础设施

```
Week 1:
├── 统一自主授权管理器 (5天)
└── LLM 客户端接口 (2天)

Week 2:
├── Skills 动态扫描 (3天)
├── Compactor LLM 摘要 (2天)
└── Reflection LLM 分析 (开始)
```

### Week 3-4: P1 Hands 实现

```
Week 3:
├── Slideshow Hand (2-3天)
├── Speech Hand (2-3天)
└── Quiz Hand (开始)

Week 4:
├── Quiz Hand (完成)
├── Researcher Hand (3-5天)
└── Collector Hand (开始)
```

### Week 5-6: P1 智能层 + P2 Hands

```
Week 5:
├── Collector Hand (完成)
├── Embedding 模型集成 (2天)
└── 语义搜索实现 (2天)

Week 6:
├── Whiteboard Hand (4-6天)
├── Clip Hand (开始)
└── Twitter Hand (开始)
```

---

## 五、关键文件清单

### 需要修改的文件

| 文件 | 修改内容 |
|------|---------|
| `desktop/src-tauri/src/intelligence/mod.rs` | 添加 autonomy 模块 |
| `desktop/src-tauri/src/intelligence/compactor.rs` | 激活 LLM 摘要 |
| `desktop/src-tauri/src/intelligence/reflection.rs` | 实现 LLM 分析 |
| `desktop/src-tauri/src/memory/persistent.rs` | 添加向量搜索 |
| `desktop/src-tauri/src/kernel_commands.rs` | 添加 skill_list 命令 |
| `desktop/src-tauri/src/lib.rs` | 注册新命令 |
| `desktop/src/store/configStore.ts` | 更新技能加载逻辑 |
| `docs/features/05-hands-system/00-hands-overview.md` | 更新实现状态 |

### 需要新建的文件

| 文件 | 用途 |
|------|------|
| `desktop/src-tauri/src/intelligence/autonomy.rs` | 自主授权管理器 |
| `desktop/src-tauri/src/intelligence/llm_client.rs` | LLM 客户端接口 |
| `desktop/src-tauri/src/hands/mod.rs` | Hands 模块入口 |
| `desktop/src-tauri/src/hands/common/*.rs` | 公共模块 |
| `desktop/src-tauri/src/hands/slideshow/*.rs` | Slideshow Hand |
| `desktop/src-tauri/src/hands/speech/*.rs` | Speech Hand |
| `desktop/src-tauri/src/hands/quiz/*.rs` | Quiz Hand |
| `desktop/src-tauri/src/hands/researcher/*.rs` | Researcher Hand |
| `desktop/src-tauri/src/hands/collector/*.rs` | Collector Hand |

---

## 六、验证方法

### 单元测试

```bash
# Rust 测试
cd desktop/src-tauri
cargo test

# TypeScript 测试
cd desktop
pnpm vitest run
```

### 集成测试

```bash
# 启动应用
pnpm desktop

# 验证 Skills 动态扫描
# - 打开技能市场
# - 确认显示 73 个技能

# 验证 Hands
# - 触发 Slideshow Hand
# - 触发 Speech Hand
# - 触发 Quiz Hand

# 验证智能层
# - 测试 LLM 摘要功能
# - 测试语义搜索
# - 测试自主授权级别
```

### 手动验证清单

- [ ] Skills 市场显示全部 73 个技能
- [ ] Slideshow Hand 可控制幻灯片
- [ ] Speech Hand 可进行语音合成
- [ ] Quiz Hand 可生成测验
- [ ] Researcher Hand 可执行研究任务
- [ ] Collector Hand 可收集数据
- [ ] LLM 摘要生成正常
- [ ] 语义搜索返回相关结果
- [ ] 自主授权级别切换正常

---

## 七、风险评估

| 风险 | 影响 | 缓解措施 |
|------|------|----------|
| Embedding 模型体积大 | 下载存储成本 | 提供模型管理，支持用户选择 |
| LLM API 调用成本 | 频繁使用增加费用 | 配置阈值，提供降级策略 |
| 外部 API 依赖 | Twitter/Lead 需付费 | 标注为可选功能 |
| FFmpeg 依赖 | Clip Hand 需预装 | 检测依赖并提示用户 |

---

## 八、成功标准

| 指标 | 当前 | 目标 |
|------|------|------|
| 可用 Hands | 1/11 (9%) | 6/11 (55%) |
| 可发现 Skills | 12/73 (16%) | 73/73 (100%) |
| LLM 功能激活 | 0% | 100% |
| 语义搜索 | 不可用 | 可用 |
| 自主授权 | 分散 | 统一管理 |