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

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

---

六、验证方法

单元测试

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

# TypeScript 测试
cd desktop
pnpm vitest run

集成测试

# 启动应用
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%
语义搜索	不可用	可用
自主授权	分散	统一管理