zclaw_openfang/plans/abstract-weaving-crab.md

# ZCLAW 功能验证计划

> **版本**: v0.2.5
> **创建日期**: 2026-03-24
> **验证范围**: 所有已实现功能的完整性、可用性验证

---

## 一、验证概述

### 1.1 验证目标

基于 `docs/features` 目录的文档，系统化验证 ZCLAW 所有已实现功能的：
- **完整性** - 功能是否完整实现
- **可用性** - 功能是否可正常使用
- **集成性** - 前后端是否正确集成
- **持久性** - 数据是否正确持久化

### 1.2 验证范围统计

| 模块 | 功能数量 | 验证点数量 |
|------|---------|-----------|
| 架构层 | 3 | 45 |
| 核心功能 | 6 | 38 |
| 智能层 | 6 | 42 |
| 技能系统 | 3 | 15 |
| Hands 系统 | 9 | 20 |
| 后端集成 | 100+ | 25 |
| **总计** | **127+** | **185** |

---

## 二、Phase 1: 架构层验证

### 2.1 通信层验证 (01-communication-layer.md)

#### 2.1.1 LLM Provider 连接验证

| # | 验证项 | 测试方法 | 预期结果 |
|---|--------|---------|---------|
| 1.1 | Kimi Provider | 配置 Kimi API Key，发送消息 | 流式响应正常 |
| 1.2 | Qwen Provider | 配置通义千问 API Key | 流式响应正常 |
| 1.3 | DeepSeek Provider | 配置 DeepSeek API Key | 流式响应正常 |
| 1.4 | 智谱 Provider | 配置智谱 API Key | 流式响应正常 |
| 1.5 | OpenAI Provider | 配置 OpenAI Key | 流式响应正常 |
| 1.6 | Anthropic Provider | 配置 Claude API Key | 流式响应正常 |
| 1.7 | Gemini Provider | 配置 Gemini API Key | 流式响应正常 |
| 1.8 | Local Provider (Ollama) | 启动 Ollama，配置 localhost:11434 | 流式响应正常 |
| 1.9 | 自定义 baseUrl | 配置自定义 URL | 请求发送到自定义地址 |

**关键文件**: `desktop/src/lib/kernel-client.ts`, `crates/zclaw-runtime/src/driver/`

#### 2.1.2 Tauri 命令验证

| # | 命令 | 验证方法 | 预期结果 |
|---|------|---------|---------|
| 2.1 | `kernel_init` | 首次启动应用 | `initialized: true` |
| 2.2 | `kernel_status` | 调用状态 API | 返回当前状态 |
| 2.3 | `kernel_shutdown` | 关闭应用 | 优雅关闭 |
| 2.4 | `agent_create` | 创建新 Agent | 返回 `{ id, name, state }` |
| 2.5 | `agent_list` | 调用列表 API | 返回 Agent 数组 |
| 2.6 | `agent_get` | 获取 Agent 详情 | 返回完整信息 |
| 2.7 | `agent_delete` | 删除 Agent | 成功删除 |
| 2.8 | `agent_chat` | 发送非流式消息 | 返回完整响应 |
| 2.9 | `agent_chat_stream` | 发送流式消息 | 收到流式事件 |

**关键文件**: `desktop/src-tauri/src/kernel_commands.rs`

#### 2.1.3 流式响应验证

| # | 验证项 | 测试方法 | 预期结果 |
|---|--------|---------|---------|
| 3.1 | delta 事件 | 发送消息 | UI 逐字显示 |
| 3.2 | tool_start 事件 | 触发工具调用 | 显示工具开始状态 |
| 3.3 | tool_end 事件 | 工具完成 | 显示工具输出 |
| 3.4 | complete 事件 | 消息完成 | 停止流式，显示 token 统计 |
| 3.5 | error 事件 | 模拟错误 | 显示错误信息 |
| 3.6 | sessionId 路由 | 并发发送多条 | 事件正确路由 |
| 3.7 | 流式取消 | 调用 cancelStream | 清理监听器 |

#### 2.1.4 错误处理验证

| # | 场景 | 预期行为 |
|---|------|---------|
| 4.1 | 未配置模型 | 显示中文提示 |
| 4.2 | API Key 无效 | 显示 401 错误 |
| 4.3 | 网络中断 | 显示连接失败 |
| 4.4 | 流式错误 | UI 恢复可交互 |
| 4.5 | 自动重连 | reconnecting 状态 |

---

### 2.2 状态管理验证 (02-state-management.md)

#### 2.2.1 Store 持久化验证

| # | Store | 验证项 | 测试方法 |
|---|-------|--------|---------|
| 5.1 | chatStore | 对话历史保留 | 刷新页面后验证 |
| 5.2 | chatStore | partialize | 检查 localStorage 内容 |
| 5.3 | configStore | 配置保留 | 修改后刷新验证 |
| 5.4 | offlineStore | 离线队列保留 | 离线发送后刷新 |

**关键文件**: `desktop/src/store/chatStore.ts`, `desktop/src/store/configStore.ts`

#### 2.2.2 Store 间通信验证

| # | 验证项 | 测试方法 |
|---|--------|---------|
| 6.1 | 客户端注入 | 检查 initializeStores() |
| 6.2 | 连接状态同步 | 连接后验证 Agent 自动加载 |
| 6.3 | 跨 Store 访问 | 发送消息时检查连接状态 |
| 6.4 | 单例模式 | 多次调用验证同一实例 |

#### 2.2.3 Date 对象恢复验证

| # | 验证项 | 测试方法 |
|---|--------|---------|
| 7.1 | 日期转换 | 刷新后验证时间显示 |
| 7.2 | streaming 清除 | 流式中刷新验证 |
| 7.3 | 当前会话恢复 | 切换对话后刷新 |

---

### 2.3 安全认证验证 (03-security-auth.md)

#### 2.3.1 设备认证验证

| # | 验证项 | 测试方法 |
|---|--------|---------|
| 8.1 | 密钥生成 | 清空存储后启动 |
| 8.2 | 密钥持久化 | 验证 Keyring 调用 |
| 8.3 | JWT Token 存储 | 验证非明文存储 |
| 8.4 | Token 刷新 | 过期后自动刷新 |

**关键文件**: `desktop/src/lib/secure-storage.ts`

#### 2.3.2 存储后端验证

| # | 平台 | 存储后端 |
|---|------|---------|
| 9.1 | Windows | DPAPI |
| 9.2 | macOS | Keychain |
| 9.3 | Linux | Secret Service |
| 9.4 | 降级 | AES-GCM 加密 localStorage |

---

## 三、Phase 2: 核心功能验证

### 3.1 聊天界面验证

| # | 功能 | 验证方法 | 预期结果 |
|---|------|---------|---------|
| 10.1 | 流式响应展示 | 发送消息 | 实时显示 |
| 10.2 | Markdown 渲染 | 发送 Markdown 内容 | 正确渲染 |
| 10.3 | 代码块渲染 | 发送代码 | 语法高亮 |
| 10.4 | 多会话管理 | 创建/切换/删除 | 状态正确 |
| 10.5 | 模型选择 | 切换模型 | 使用新模型 |
| 10.6 | 消息自动滚动 | 长对话 | 自动滚动到底部 |
| 10.7 | 输入框调整 | 输入多行 | 高度自动调整 |
| 10.8 | 记忆增强注入 | 发送相关历史 | 自动注入上下文 |
| 10.9 | 上下文压缩 | 超过阈值 | 自动压缩 |

**关键文件**: `desktop/src/components/ChatArea.tsx`, `desktop/src/store/chatStore.ts`

### 3.2 Agent 分身管理验证

| # | 功能 | 验证方法 | 预期结果 |
|---|------|---------|---------|
| 11.1 | 创建 Agent | 通过向导创建 | 成功创建 |
| 11.2 | 配置 Agent | 修改 SOUL.md | 配置生效 |
| 11.3 | 切换 Agent | 切换当前 Agent | 状态更新 |
| 11.4 | 人格预设 | 选择不同预设 | SOUL.md 不同 |
| 11.5 | 身份持久化 | 重启应用 | Agent 保留 |

**关键文件**: `desktop/src/components/AgentOnboardingWizard.tsx`, `desktop/src/lib/personality-presets.ts`

### 3.3 多 Agent 协作验证

| # | 模式 | 验证方法 | 预期结果 |
|---|------|---------|---------|
| 12.1 | Sequential | 创建链式任务 | 按顺序执行 |
| 12.2 | Parallel | 创建并行任务 | 并发执行 |
| 12.3 | Debate | 创建辩论任务 | 多轮讨论后综合 |

**关键文件**: `desktop/src/components/SwarmDashboard.tsx`, `desktop/src/lib/agent-swarm.ts`

---

## 四、Phase 3: 智能层验证

### 4.1 Agent 记忆系统验证 (00-agent-memory.md)

#### 4.1.1 记忆类型验证

| # | 类型 | 测试方法 | 预期结果 |
|---|------|---------|---------|
| 13.1 | fact | 存储事实记忆 | 正确存储 |
| 13.2 | preference | 存储偏好记忆 | 正确存储 |
| 13.3 | lesson | 存储教训记忆 | 正确存储 |
| 13.4 | context | 存储上下文记忆 | 正确存储 |
| 13.5 | task | 存储任务记忆 | 正确存储 |

#### 4.1.2 记忆操作验证

| # | 操作 | Tauri 命令 | 验证方法 |
|---|------|-----------|---------|
| 14.1 | 初始化 | `memory_init` | 调用成功 |
| 14.2 | 存储 | `memory_store` | 存储成功 |
| 14.3 | 获取 | `memory_get` | 正确获取 |
| 14.4 | 搜索 | `memory_search` | 返回相关记忆 |
| 14.5 | 删除 | `memory_delete` | 删除成功 |
| 14.6 | 统计 | `memory_stats` | 返回统计 |
| 14.7 | 导出 | `memory_export` | 导出 Markdown |
| 14.8 | 导入 | `memory_import` | 导入成功 |

**关键文件**: `desktop/src-tauri/src/memory_commands.rs`, `desktop/src/components/MemoryPanel.tsx`

#### 4.1.3 记忆 UI 集成验证

| # | 组件 | 验证方法 |
|---|------|---------|
| 15.1 | MemoryPanel | 点击 RightPanel | 显示记忆面板 |
| 15.2 | MemoryGraph | 查看记忆图谱 | 正确渲染 |
| 15.3 | 统计显示 | 查看统计 | 显示正确 |
| 15.4 | 清理功能 | 点击清理 | 正确执行 |

### 4.2 身份演化验证 (01-identity-evolution.md)

| # | 功能 | API/命令 | 验证方法 |
|---|------|---------|---------|
| 16.1 | 获取身份 | `identity_get` | 返回身份文件 |
| 16.2 | 更新文件 | `identity_update_file` | 更新成功 |
| 16.3 | 变更提案 | `identity_propose_change` | 创建提案 |
| 16.4 | 批准提案 | `identity_approve_proposal` | 应用变更 |
| 16.5 | 拒绝提案 | `identity_reject_proposal` | 丢弃提案 |
| 16.6 | 快照历史 | `identity_get_snapshots` | 返回历史 |
| 16.7 | 回滚 | `identity_restore_snapshot` | 恢复成功 |

**关键文件**: `desktop/src/lib/intelligence-client.ts`, `desktop/src/components/IdentityChangeProposal.tsx`

### 4.3 反思引擎验证 (03-reflection-engine.md)

| # | 功能 | Tauri 命令 | 验证方法 |
|---|------|-----------|---------|
| 17.1 | 记录对话 | `reflection_record_conversation` | 记录成功 |
| 17.2 | 触发检查 | `reflection_should_reflect` | 返回是否触发 |
| 17.3 | 执行反思 | `reflection_reflect` | 返回结果 |
| 17.4 | 获取历史 | `reflection_get_history` | 返回历史 |

**验证触发条件**:
- 对话次数: 每 5 次后
- 时间间隔: 每 24 小时
- 首次触发: 3 次对话后

**关键文件**: `desktop/src-tauri/src/intelligence/reflection.rs`, `desktop/src/components/ReflectionLog.tsx`

### 4.4 心跳引擎验证 (04-heartbeat-engine.md)

| # | 功能 | Tauri 命令 | 验证方法 |
|---|------|-----------|---------|
| 18.1 | 初始化 | `heartbeat_init` | 初始化成功 |
| 18.2 | 启动 | `heartbeat_start` | 开始跳动 |
| 18.3 | 停止 | `heartbeat_stop` | 停止跳动 |
| 18.4 | 手动触发 | `heartbeat_tick` | 执行检查 |
| 18.5 | 获取配置 | `heartbeat_get_config` | 返回配置 |
| 18.6 | 更新配置 | `heartbeat_update_config` | 更新成功 |
| 18.7 | 获取历史 | `heartbeat_get_history` | 返回历史 |

**验证检查函数**:
- `check_pending_tasks` - 待办任务积压
- `check_memory_health` - 记忆健康
- `check_idle_greeting` - 长时间未互动
- `check_personality_improvement` - 人格改进
- `check_learning_opportunities` - 学习机会

**关键文件**: `desktop/src-tauri/src/intelligence/heartbeat.rs`

### 4.5 自主授权验证 (05-autonomy-manager.md)

#### 4.5.1 自主级别验证

| # | 级别 | 行为 | 验证方法 |
|---|------|------|---------|
| 19.1 | supervised | 所有操作需确认 | 设置后验证 |
| 19.2 | assisted | 低风险自动，中高需确认 | 设置后验证 |
| 19.3 | autonomous | 低中风险自动，高需确认 | 设置后验证 |

#### 4.5.2 风险等级验证

| # | 等级 | 操作类型 | 验证方法 |
|---|------|---------|---------|
| 20.1 | Low | memory_save, reflection_run | 验证自动执行 |
| 20.2 | Medium | hand_trigger, skill_install | 验证需确认 |
| 20.3 | High | memory_delete, identity_update | 验证始终需确认 |

**关键文件**: `desktop/src/lib/autonomy-manager.ts`, `desktop/src/components/AutonomyConfig.tsx`

### 4.6 上下文压缩验证

| # | 功能 | Tauri 命令 | 验证方法 |
|---|------|-----------|---------|
| 21.1 | Token 估算 | `compactor_estimate_tokens` | 返回估算值 |
| 21.2 | 阈值检查 | `compactor_check_threshold` | 返回是否超阈值 |
| 21.3 | 执行压缩 | `compactor_compact` | 返回压缩结果 |

**压缩配置**:
- 阈值: 15000 tokens
- 策略: 滑动窗口 + 摘要

---

## 五、Phase 4: 技能系统验证

### 5.1 技能发现验证

| # | 验证项 | 测试方法 | 预期结果 |
|---|--------|---------|---------|
| 22.1 | 技能扫描 | 调用 `skill_list` | 返回 77 个技能 |
| 22.2 | 技能刷新 | 调用 `skill_refresh` | 重新扫描成功 |
| 22.3 | 技能分类 | 检查分类 | 14 个分类正确 |

**关键文件**: `crates/zclaw-skills/src/registry.rs`, `desktop/src/lib/skill-discovery.ts`

### 5.2 技能执行验证

| # | 验证项 | 测试方法 | 预期结果 |
|---|--------|---------|---------|
| 23.1 | 执行技能 | 调用 `skill_execute` | 正确执行 |
| 23.2 | 触发词匹配 | 发送触发词消息 | 自动推荐技能 |
| 23.3 | 工具权限 | 检查 SKILL.md tools | 正确限制 |

### 5.3 技能分类抽样验证

| 分类 | 代表技能 | 验证项 |
|------|---------|-------|
| 开发工程 | senior-developer | 代码生成 |
| 测试/QA | code-reviewer | 代码审查 |
| 设计/UX | ui-designer | 设计建议 |
| 安全 | security-engineer | 安全分析 |
| 数据分析 | analytics-reporter | 数据报告 |
| 运维/DevOps | devops-automator | 自动化 |

---

## 六、Phase 5: Hands 系统验证

### 6.1 已实现 Hands 验证 (9/11)

| # | Hand | 触发方式 | 需审批 | 验证方法 |
|---|------|---------|-------|---------|
| 24.1 | browser | 手动/Webhook | 是 | 启动浏览器会话 |
| 24.2 | researcher | 手动/事件 | 否 | 执行研究任务 |
| 24.3 | collector | 定时/事件/手动 | 否 | 数据收集 |
| 24.4 | slideshow | 手动 | 否 | 生成幻灯片 |
| 24.5 | speech | 手动/事件 | 否 | 语音合成 |
| 24.6 | quiz | 手动 | 否 | 生成测验 |
| 24.7 | whiteboard | 手动 | 否 | 白板协作 |
| 24.8 | clip | 手动/定时 | 否 | **需 FFmpeg** |
| 24.9 | twitter | 定时/事件 | 是 | **需 API Key** |

**关键文件**: `crates/zclaw-hands/src/hands/`, `desktop/src/store/handStore.ts`

### 6.2 依赖检查验证

| # | Hand | 依赖 | 验证方法 |
|---|------|------|---------|
| 25.1 | clip | FFmpeg | 检测 FFmpeg 可用性 |
| 25.2 | twitter | Twitter API Key | 检测 API Key |
| 25.3 | browser | WebDriver | 检测浏览器驱动 |

### 6.3 审批流程验证

| # | 验证项 | 测试方法 |
|---|--------|---------|
| 26.1 | 状态流转 | 触发需审批 Hand | pending → needs_approval → completed |
| 26.2 | 批准操作 | 点击批准 | 继续执行 |
| 26.3 | 拒绝操作 | 点击拒绝 | 取消执行 |

---

## 七、Phase 6: 后端集成验证

### 7.1 Kernel 集成验证

| # | 验证项 | 测试方法 | 预期结果 |
|---|--------|---------|---------|
| 27.1 | 内部 Kernel | 调用 `kernel_init` | initialized: true |
| 27.2 | 多 LLM 支持 | 配置不同 Provider | 正确切换 |
| 27.3 | Agent 生命周期 | 创建/删除 Agent | 正确管理 |
| 27.4 | 流式响应 | 发送流式消息 | 事件正确 |
| 27.5 | MCP 协议 | 检查 MCP 支持 | 已实现 |

**关键文件**: `crates/zclaw-kernel/src/lib.rs`

### 7.2 浏览器自动化验证

| # | 命令 | 验证方法 |
|---|------|---------|
| 28.1 | `browser_create_session` | 创建会话 |
| 28.2 | `browser_navigate` | 导航页面 |
| 28.3 | `browser_click` | 点击元素 |
| 28.4 | `browser_type` | 输入文本 |
| 28.5 | `browser_screenshot` | 截图 |
| 28.6 | `browser_execute_script` | 执行 JS |
| 28.7 | `browser_scrape_page` | 抓取页面 |

---

## 八、验证执行顺序

### 8.1 推荐执行顺序

```
Phase 1 (架构层)
├── 通信层 (45 min)
├── 状态管理 (30 min)
└── 安全认证 (30 min)

Phase 2 (核心功能)
├── 聊天界面 (30 min)
├── Agent 管理 (20 min)
└── 多 Agent 协作 (20 min)

Phase 3 (智能层)
├── 记忆系统 (30 min)
├── 身份演化 (20 min)
├── 反思引擎 (15 min)
├── 心跳引擎 (15 min)
├── 自主授权 (15 min)
└── 上下文压缩 (10 min)

Phase 4 (技能系统)
└── 技能验证 (30 min)

Phase 5 (Hands 系统)
└── Hands 验证 (45 min)

Phase 6 (后端集成)
└── Kernel 验证 (30 min)
```

**预计总时间**: 约 6 小时

### 8.2 自动化测试

| 类型 | 位置 | 命令 |
|------|------|------|
| 单元测试 | `tests/desktop/` | `pnpm vitest run` |
| E2E 测试 | `desktop/tests/e2e/` | `pnpm test:e2e` |
| 类型检查 | - | `pnpm tsc --noEmit` |

---

## 九、验证记录模板

### 9.1 功能验证记录

```markdown
## [功能名称] 验证记录

**日期**: YYYY-MM-DD
**验证人**:
**环境**: Windows/macOS/Linux

### 验证结果

| # | 验证项 | 状态 | 备注 |
|---|--------|------|------|
| 1 | xxx | ✅/❌ | |

### 发现的问题

1. [问题描述]
   - 严重程度: 高/中/低
   - 复现步骤:
   - 预期结果:
   - 实际结果:

### 建议

- [改进建议]
```

---

## 十、关键文件路径汇总

### 10.1 前端文件

| 模块 | 路径 |
|------|------|
| Kernel Client | `desktop/src/lib/kernel-client.ts` |
| 智能客户端 | `desktop/src/lib/intelligence-client.ts` |
| 技能发现 | `desktop/src/lib/skill-discovery.ts` |
| 自主管理 | `desktop/src/lib/autonomy-manager.ts` |
| 安全存储 | `desktop/src/lib/secure-storage.ts` |
| 聊天 Store | `desktop/src/store/chatStore.ts` |
| Hand Store | `desktop/src/store/handStore.ts` |

### 10.2 后端文件

| 模块 | 路径 |
|------|------|
| Kernel 命令 | `desktop/src-tauri/src/kernel_commands.rs` |
| 记忆命令 | `desktop/src-tauri/src/memory_commands.rs` |
| 心跳引擎 | `desktop/src-tauri/src/intelligence/heartbeat.rs` |
| 反思引擎 | `desktop/src-tauri/src/intelligence/reflection.rs` |
| 身份管理 | `desktop/src-tauri/src/intelligence/identity.rs` |
| Kernel 核心 | `crates/zclaw-kernel/src/lib.rs` |
| 技能注册 | `crates/zclaw-skills/src/registry.rs` |
| Hands 实现 | `crates/zclaw-hands/src/hands/` |

### 10.3 文档文件

| 文档 | 路径 |
|------|------|
| 功能索引 | `docs/features/README.md` |
| 通信层 | `docs/features/00-architecture/01-communication-layer.md` |
| 状态管理 | `docs/features/00-architecture/02-state-management.md` |
| 记忆系统 | `docs/features/02-intelligence-layer/00-agent-memory.md` |
| 身份演化 | `docs/features/02-intelligence-layer/01-identity-evolution.md` |
| 技能系统 | `docs/features/04-skills-ecosystem/00-skill-system.md` |
| Hands 系统 | `docs/features/05-hands-system/00-hands-overview.md` |

---

## 十一、验收标准

### 11.1 通过标准

| 指标 | 标准 |
|------|------|
| 功能完整性 | ≥ 95% 验证点通过 |
| 关键功能 | 100% 通过 (聊天、Agent、记忆) |
| 无阻塞性问题 | 0 个 High 严重度问题 |
| 数据持久化 | 100% 正确 |

### 11.2 阻塞问题定义

- **High**: 功能完全不可用
- **Medium**: 功能部分可用，有规避方案
- **Low**: UI/体验问题，不影响核心功能

---

## 十二、硬编码问题审计报告

> **审计日期**: 2026-03-24
> **触发原因**: 发现 `skills_dir: None` 导致技能系统完全失效

### 12.1 已修复问题

#### 问题 #1: `skills_dir: None` 导致技能不加载 (CRITICAL - 已修复)

**文件**: `crates/zclaw-kernel/src/config.rs:337`

**问题描述**:
```rust
// 修复前
Self {
    database_url: default_database_url(),
    llm,
    skills_dir: None,  // ← 硬编码为 None！
}
```

**影响**: 通过 Tauri 初始化 Kernel 时，技能目录永远不会被扫描，导致：
- `skills.list()` 返回空列表
- 系统提示词中没有任何技能信息
- LLM 无法调用 `execute_skill` 工具

**修复**:
```rust
// 修复后
skills_dir: default_skills_dir(),  // 使用默认的 ./skills 目录
```

**验证方法**:
1. 启动应用，发送 "查询腾讯财报"
2. 预期: LLM 应调用 `execute_skill("finance-tracker", {...})`

---

### 12.2 待修复问题清单

#### 高优先级 (HIGH)

| # | 问题 | 文件:行号 | 影响 |
|---|------|----------|------|
| H1 | `default_skills_dir()` 依赖 `current_dir()` | `config.rs:161-165` | 工作目录不同时技能加载失败 |
| H2 | `categorize_skills()` 包含 50+ 硬编码技能 ID | `kernel.rs:173-185` | 新增/重命名技能后分类失效 |
| H3 | 前端 Hand ID 硬编码在多处 | `automation.ts`, `hands.ts` | Hand 配置变更后前端不一致 |

#### 中优先级 (MEDIUM)

| # | 问题 | 文件:行号 | 影响 |
|---|------|----------|------|
| M1 | 默认模型不一致 | `kernel_commands.rs` vs `config-parser.ts` | `gpt-4o-mini` vs `gpt-4` |
| M2 | API URL 硬编码在多处 | `config.rs`, `llm/mod.rs`, driver 文件 | 无法统一配置 |
| M3 | 系统提示词示例硬编码 `finance-tracker` | `kernel.rs:162` | 技能重命名后示例过时 |
| M4 | 前端存储键硬编码 | `gateway-storage.ts`, 多个 store | 无法自定义前缀 |

#### 低优先级 (LOW)

| # | 问题 | 文件:行号 | 影响 |
|---|------|----------|------|
| L1 | 工具名称有常量但未使用 | `tool.rs:79-90` vs builtin/*.rs | 代码不一致 |
| L2 | 超时/阈值等配置硬编码 | `compactor.rs`, `heartbeat.rs` | 无法动态调整 |
| L3 | Tauri 允许来源硬编码 | `lib.rs:97` | 安全配置不灵活 |

---

### 12.3 硬编码位置详细列表

#### 后端 (Rust)

| 类别 | 文件 | 内容 |
|------|------|------|
| **配置默认值** | `config.rs:200-247` | 9 个 LLM Provider URL |
| **配置默认值** | `config.rs:285-326` | 8 个 fallback URL |
| **驱动 URL** | `driver/local.rs:27,31,35` | Ollama/LM Studio/vLLM localhost |
| **驱动 URL** | `driver/gemini.rs:25` | Google Generative Language API |
| **驱动 URL** | `driver/anthropic.rs:27` | Anthropic API |
| **驱动 URL** | `driver/openai.rs:31` | OpenAI API |
| **模型默认值** | `kernel_commands.rs:43-46` | openai, gpt-4o-mini, 4096, 0.7 |
| **技能分类** | `kernel.rs:173-185` | 11 个分类，50+ 技能 ID |
| **阈值配置** | `compactor.rs:38-44` | 15000, 20000, 4000, 6, 800 |
| **心跳配置** | `heartbeat.rs:36-37` | 30s interval, 5 max alerts |
| **浏览器** | `browser/commands.rs:63` | localhost:4444 WebDriver |
| **网关** | `lib.rs:554` | ws://127.0.0.1:4200 |

#### 前端 (TypeScript)

| 类别 | 文件 | 内容 |
|------|------|------|
| **网关 URL** | `gateway-storage.ts:47,51` | 127.0.0.1:50051, 127.0.0.1:4200 |
| **模型默认值** | `config-parser.ts:77,81-82` | gpt-4, openai |
| **模型默认值** | `llm-service.ts:57-66` | gpt-4o-mini, doubao-pro-32k |
| **内核默认值** | `kernel-client.ts:248,340-341` | openai, anthropic, claude-sonnet-4 |
| **存储键** | 多个 store 文件 | zclaw-*, zclaw-main |
| **Hand ID** | `automation.ts:49-57,267-279` | 7 个 Hand 映射 |
| **Hand 定义** | `hands.ts:97-189` | 完整 Hand 定义 |
| **技能 ID** | `skillMarketStore.ts:304+` | 技能市场定义 |

---

### 12.4 建议修复方案

#### H1: `default_skills_dir()` 改进

```rust
// 当前 (不可靠)
fn default_skills_dir() -> Option<PathBuf> {
    std::env::current_dir().ok().map(|cwd| cwd.join("skills"))
}

// 建议 (更可靠)
fn default_skills_dir() -> Option<PathBuf> {
    // 1. 优先使用可执行文件目录
    std::env::current_exe()
        .ok()
        .and_then(|exe| exe.parent().map(|p| p.join("skills")))
        // 2. 回退到当前目录
        .or_else(|| std::env::current_dir().ok().map(|cwd| cwd.join("skills")))
}
```

#### H2: 技能分类改为动态

```rust
// 当前 (硬编码)
let category_patterns = [
    ("开发工程", vec!["senior-developer", ...]),
    ...
];

// 建议 (从 SKILL.md 读取)
// 在 SKILL.md frontmatter 中添加 category 字段
// categories:
//   - development
// 或从目录结构推断
```

#### H3: Hand ID 集中管理

```typescript
// 创建常量文件
// hands/constants.ts
export const HAND_IDS = {
  BROWSER: 'browser',
  RESEARCHER: 'researcher',
  COLLECTOR: 'collector',
  ...
} as const;

// 所有地方引用常量而非硬编码字符串
```

---

### 12.5 验证检查清单

修复后需验证：

- [ ] 从不同工作目录启动应用，技能仍能正确加载
- [ ] 新增技能后，系统提示词自动包含
- [ ] 重命名技能后，分类仍正确（如使用动态分类）
- [ ] 前端 Hand 配置与后端一致

---

*本验证计划基于 ZCLAW v0.2.5 代码状态生成*