iven/zclaw_openfang
1
0
Fork 0
Code Issues Pull Requests Actions 1 Packages Projects Releases Wiki Activity

release(v0.2.0): streaming, MCP protocol, Browser Hand, security enhancements

Browse Source 
## Major Features

### Streaming Response System
- Implement LlmDriver trait with `stream()` method returning async Stream
- Add SSE parsing for Anthropic and OpenAI API streaming
- Integrate Tauri event system for frontend streaming (`stream:chunk` events)
- Add StreamChunk types: Delta, ToolStart, ToolEnd, Complete, Error

### MCP Protocol Implementation
- Add MCP JSON-RPC 2.0 types (mcp_types.rs)
- Implement stdio-based MCP transport (mcp_transport.rs)
- Support tool discovery, execution, and resource operations

### Browser Hand Implementation
- Complete browser automation with Playwright-style actions
- Support Navigate, Click, Type, Scrape, Screenshot, Wait actions
- Add educational Hands: Whiteboard, Slideshow, Speech, Quiz

### Security Enhancements
- Implement command whitelist/blacklist for shell_exec tool
- Add SSRF protection with private IP blocking
- Create security.toml configuration file

## Test Improvements
- Fix test import paths (security-utils, setup)
- Fix vi.mock hoisting issues with vi.hoisted()
- Update test expectations for validateUrl and sanitizeFilename
- Add getUnsupportedLocalGatewayStatus mock

## Documentation Updates
- Update architecture documentation
- Improve configuration reference
- Add quick-start guide updates

Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
This commit is contained in:
iven
2026-03-24 03:24:24 +08:00
parent e49ba4460b
commit 3ff08faa56
78 changed files with 29575 additions and 1682 deletions
Download Patch File Download Diff File Expand all files Collapse all files

265
plans/encapsulated-beaming-clover.md Normal file
View File

@@ -0,0 +1,265 @@
# OpenMAIC 功能借鉴与 ZCLAW 实现计划
## Context
用户希望借鉴 [OpenMAIC](https://github.com/THU-MAIC/OpenMAIC) 的多智能体课堂功能，但该项目采用 **AGPL-3.0** 许可证，直接整合有法律风险。
**关键决策**: 不整合 OpenMAIC 代码，而是**借鉴架构思想**，利用 ZCLAW 现有的 workflow、协作、Hands、Skills 等能力实现类似功能。
---
## 1. AGPL-3.0 风险分析
| 风险点 | 影响 |
|--------|------|
| **Copyleft 传染** | 整合代码可能要求 ZCLAW 也开源 |
| **网络条款** | AGPL-3.0 的网络使用条款比 GPL 更严格 |
| **商业影响** | 可能影响 ZCLAW 的商业化能力 |
**结论**: ❌ 不直接整合代码，✅ 仅借鉴架构思想和设计模式
---
## 2. ZCLAW 现有能力 vs OpenMAIC 功能
### 2.1 能力对照表
| OpenMAIC 功能 | ZCLAW 对应 | 成熟度 | 差距 |
|---------------|------------|--------|------|
| **多 Agent 编排** (Director Graph) | A2A 协议 + Kernel Registry | 框架完成 | 需实现实际通信 |
| **Agent 角色配置** | Skills + Agent 分身 | 完成 | 需扩展角色定义 |
| **动作执行引擎** (28+ Actions) | Hands 能力系统 | 完成 | 需补充教育类动作 |
| **工作流编排** | Trigger + EventBus | 基础完成 | 缺 DAG 编排 |
| **状态管理** | MemoryStore (SQLite) | 完成 | 无需改动 |
| **多模态支持** | 依赖 LLM Provider | 完成 | 需补充 TTS/白板 |
| **外部集成** | Channels (Telegram/Discord/Slack) | 框架完成 | 无需改动 |
### 2.2 ZCLAW 已有的核心能力
```
┌─────────────────────────────────────────────────────────────┐
│ ZCLAW 现有能力架构 │
├─────────────────────────────────────────────────────────────┤
│ A2A 协议 │ Direct/Group/Broadcast 路由 │
│ EventBus │ 发布订阅，1000 条消息容量 │
│ Trigger 系统 │ Schedule/Event/Webhook/FileSystem/Manual │
│ Hands 系统 │ 7 个自主能力 (browser/researcher/...) │
│ Skills 系统 │ 12+ 技能 (code-review/translation/...) │
│ Registry │ Agent 注册、状态管理、持久化恢复 │
│ Channels │ Telegram/Discord/Slack/Console 适配器 │
└─────────────────────────────────────────────────────────────┘
```
---
## 3. 实现方案：基于 ZCLAW 现有能力
### 3.1 多 Agent 协作（替代 Director Graph）
**利用**: A2A 协议 + Trigger 系统
**设计方案**:
```
用户请求 → Orchestrator Agent
↓
Trigger 触发 (Event 模式)
↓
┌──────────┼──────────┐
↓ ↓ ↓
Agent A Agent B Agent C
(老师) (助教) (学生)
↓ ↓ ↓
└──────────┼──────────┘
↓
结果聚合 → 响应用户
```
**实现要点**:
1. 使用 A2A `Group` 路由实现组播
2. 使用 EventBus 实现异步消息传递
3. 定义 Agent 角色 (teacher/assistant/student)
### 3.2 动作执行引擎（替代 OpenMAIC Actions）
**利用**: Hands 能力系统
**新增 Hand 类型**:
| Hand | 功能 | 对应 OpenMAIC Action |
|------|------|---------------------|
| `whiteboard` | 白板绘制 | wb_draw_text/shape/chart |
| `slideshow` | 幻灯片控制 | spotlight/laser/next_slide |
| `speech` | 语音合成 | speech (TTS) |
| `quiz` | 测验生成 | quiz_generate/grade |
**扩展 Hand 配置**:
```toml
# hands/whiteboard.HAND.toml
[hand]
id = "whiteboard"
name = "白板能力"
description = "绘制图表、公式、文本"
needs_approval = false
[capabilities]
actions = ["draw_text", "draw_shape", "draw_chart", "draw_latex", "clear"]
```
### 3.3 工作流编排（替代 LangGraph）
**利用**: Trigger + EventBus + Skills
**设计方案**:
```rust
// 工作流定义
struct Workflow {
id: String,
stages: Vec<WorkflowStage>,
transitions: Vec<Transition>,
}
struct WorkflowStage {
id: String,
agent_role: String, // 执行的 Agent 角色
skill: Option<String>, // 使用的 Skill
hand: Option<String>, // 使用的 Hand
}
struct Transition {
from: String,
to: String,
condition: Option<String>, // 条件表达式
}
```
**触发方式**:
- `Schedule` - 定时课堂
- `Event` - 用户提问触发
- `Manual` - 手动开始
### 3.4 场景生成（替代两阶段生成）
**利用**: Skills 系统 + LLM
**新增 Skill**:
```markdown
# skills/classroom-generator/SKILL.md
---
name: classroom-generator
description: 根据主题生成互动课堂
mode: prompt-only
---
## 输入
- topic: 课堂主题
- document: 可选参考文档
- style: 教学风格 (lecture/discussion/pbl)
## 输出
- 大纲 JSON
- 场景列表 (每个场景包含内容 + 动作)
## 提示模板
...
```
---
## 4. 实施路径
### Phase 1: 完善 A2A 通信 ✅ (已完成)
**实现内容**:
- 重写 `crates/zclaw-protocols/src/a2a.rs`
- 实现 `A2aRouter` 消息路由器
- 支持 Direct/Group/Broadcast 三种路由模式
- 实现能力发现和索引机制
- 添加 5 个单元测试（全部通过）
### Phase 2: 扩展 Hands 能力 ✅ (已完成)
**新增文件**:
- `hands/whiteboard.HAND.toml` - 白板绘制（8 种动作）
- `hands/slideshow.HAND.toml` - 幻灯片控制（8 种动作）
- `hands/speech.HAND.toml` - 语音合成（6 种动作）
- `hands/quiz.HAND.toml` - 测验系统（8 种动作）
### Phase 3: 创建课堂生成 Skill ✅ (已完成)
**新增文件**:
- `skills/classroom-generator/SKILL.md` - 课堂生成技能
### Phase 4: 工作流编排增强 📋 (后续迭代)
当前 Trigger + EventBus 已提供基础能力，DAG 编排可在后续迭代中实现。
---
## 5. 关键文件
### 需要修改的文件
| 文件 | 改动 |
|------|------|
| `crates/zclaw-protocols/src/a2a.rs` | 实现消息路由 |
| `crates/zclaw-kernel/src/workflow.rs` | 新增工作流引擎 |
| `crates/zclaw-hands/src/hand.rs` | 扩展 Hand 类型 |
### 需要新增的文件
| 文件 | 用途 |
|------|------|
| `hands/whiteboard.HAND.toml` | 白板能力配置 |
| `hands/slideshow.HAND.toml` | 幻灯片能力配置 |
| `hands/speech.HAND.toml` | 语音能力配置 |
| `hands/quiz.HAND.toml` | 测验能力配置 |
| `skills/classroom-generator/SKILL.md` | 课堂生成技能 |
---
## 6. 验证方式
1. **A2A 通信测试**
```bash
cargo test -p zclaw-protocols a2a
```
2. **Hand 调用测试**
```bash
# 启动桌面端，测试白板 Hand
pnpm desktop
```
3. **Skill 生成测试**
```bash
# 在聊天中输入: "生成一个关于 Rust 所有权的课堂"
```
4. **工作流执行测试**
```bash
# 定义工作流并手动触发
```
---
## 7. 风险与缓解
| 风险 | 缓解措施 |
|------|----------|
| A2A 实现复杂度高 | 先实现 Direct 模式，再扩展 Group/Broadcast |
| TTS 依赖外部服务 | 支持多种 TTS Provider，优先浏览器原生 |
| 白板渲染复杂 | 先实现基础功能，渐进增强 |
---
## 8. 总结
**策略**: ❌ 不整合 AGPL-3.0 代码 → ✅ 借鉴架构 + 利用现有能力
**优势**:
- 无许可证风险
- 复用 ZCLAW 成熟基础设施
- 保持代码库一致性
- 更好的桌面端适配
**核心价值**: 将 OpenMAIC 的**多智能体协作思想**融入 ZCLAW，而非复制代码。

303
plans/nifty-inventing-valiant.md Normal file
View File

@@ -0,0 +1,303 @@
# ZCLAW 自我进化系统审查与修复计划
## 背景
自我进化系统是 ZCLAW 的核心能力，包括四个组件：
- **心跳引擎** - 定期主动检查
- **反思引擎** - 分析模式并生成改进建议
- **身份管理** - 管理人格文件和变更提案
- **记忆存储** - 持久化对话和经验
---
## 审查结果摘要
### 实现状态
| 组件 | 函数/功能 | 状态 |
|------|----------|------|
| **心跳引擎** | check_pending_tasks | ✅ 完整 |
| | check_memory_health | ✅ 完整 |
| | check_correction_patterns | ✅ 完整 |
| | check_learning_opportunities | ✅ 完整 |
| | check_idle_greeting | ⚠️ 占位符 |
| **反思引擎** | analyze_patterns | ✅ 完整 |
| | generate_improvements | ✅ 完整 |
| | propose_identity_changes | ✅ 完整 |
| **身份管理** | 提案处理 | ✅ 完整 |
| | 持久化 | ✅ 完整 |
| **前端** | Intelligence Client | ✅ 完整 |
| | IdentityChangeProposal UI | ✅ 完整 |
| | 提案通知系统 | ✅ 存在 |
### 发现的问题
| 优先级 | 问题 | 影响 |
|--------|------|------|
| HIGH | MemoryStatsCache 同步问题 | 心跳检查依赖前端主动更新，可能跳过检查 |
| HIGH | API 命名不一致 | `updateMemoryStats` 参数名不匹配（camelCase vs snake_case） |
| MEDIUM | check_idle_greeting 占位符 | 空闲问候功能不可用 |
| MEDIUM | 类型定义不一致 | `totalEntries` vs `total_memories` 命名不统一 |
| MEDIUM | 提案审批错误处理 | 缺少详细的错误反馈 |
| LOW | storageSizeBytes fallback 为 0 | localStorage 模式下无法计算 |
| LOW | 硬编码配置值 | 历史限制、快照数量不可配置 |
---
## 修复计划
### Phase 1: 修复 HIGH 优先级问题
#### Fix 1.1: API 参数命名修正 ⚡ 5分钟
**文件**: [intelligence-client.ts](desktop/src/lib/intelligence-client.ts)
**问题**: `updateMemoryStats` 使用 camelCase 参数，但 Rust 后端期望 snake_case
**修改位置**: 第 989-1011 行
```typescript
// 修改前
await invoke('heartbeat_update_memory_stats', {
agentId,
taskCount,
totalEntries,
storageSizeBytes,
});
// 修改后
await invoke('heartbeat_update_memory_stats', {
agent_id: agentId,
task_count: taskCount,
total_entries: totalEntries,
storage_size_bytes: storageSizeBytes,
});
```
#### Fix 1.2: 添加周期性记忆统计同步 ⚡ 15分钟
**文件**: [App.tsx](desktop/src/App.tsx)
**问题**: 记忆统计仅在启动时同步一次，之后数据可能陈旧
**修改位置**: 第 213 行后（heartbeat.start 之后）
```typescript
// 添加周期性同步（每 5 分钟）
const MEMORY_STATS_SYNC_INTERVAL = 5 * 60 * 1000;
const statsSyncInterval = setInterval(async () => {
try {
const stats = await intelligenceClient.memory.stats();
const taskCount = stats.byType?.['task'] || 0;
await intelligenceClient.heartbeat.updateMemoryStats(
defaultAgentId,
taskCount,
stats.totalEntries,
stats.storageSizeBytes
);
console.log('[App] Memory stats synced (periodic)');
} catch (err) {
console.warn('[App] Periodic memory stats sync failed:', err);
}
}, MEMORY_STATS_SYNC_INTERVAL);
```
#### Fix 1.3: 心跳检查容错处理 ⚡ 20分钟
**文件**: [heartbeat.rs](desktop/src-tauri/src/intelligence/heartbeat.rs)
**问题**: 当缓存为空时，检查函数直接跳过，无告警
**修改**: 在 `check_pending_tasks` 和 `check_memory_health` 中添加缓存缺失告警
```rust
fn check_pending_tasks(agent_id: &str) -> Option<HeartbeatAlert> {
match get_cached_memory_stats(agent_id) {
Some(stats) if stats.task_count >= 5 => { /* 现有逻辑 */ },
Some(_) => None,
None => Some(HeartbeatAlert {
title: "记忆统计未同步".to_string(),
content: "心跳引擎未能获取记忆统计信息，部分检查被跳过".to_string(),
urgency: Urgency::Low,
source: "pending-tasks".to_string(),
timestamp: chrono::Utc::now().to_rfc3339(),
}),
}
}
```
### Phase 2: 修复 MEDIUM 优先级问题
#### Fix 2.1: 统一类型定义命名 ⚡ 10分钟
**文件**: [intelligence-backend.ts](desktop/src/lib/intelligence-backend.ts)
**问题**: 前端使用 `totalEntries`，后端返回 `total_memories`
**修改**: 更新接口定义以匹配后端
```typescript
export interface MemoryStats {
total_entries: number; // 匹配后端
by_type: Record<string, number>;
by_agent: Record<string, number>;
oldest_entry: string | null;
newest_entry: string | null;
storage_size_bytes: number;
}
```
**同时更新** [intelligence-client.ts](desktop/src/lib/intelligence-client.ts) 中的转换函数
#### Fix 2.2: 增强提案审批错误处理 ⚡ 10分钟
**文件**: [IdentityChangeProposal.tsx](desktop/src/components/IdentityChangeProposal.tsx)
**添加错误解析函数**:
```typescript
function parseProposalError(err: unknown, operation: 'approval' | 'rejection' | 'restore'): string {
const errorMessage = err instanceof Error ? err.message : String(err);
if (errorMessage.includes('not found')) {
return `提案不存在或已被处理`;
}
if (errorMessage.includes('not pending')) {
return '该提案已被处理，请刷新页面';
}
if (errorMessage.includes('network') || errorMessage.includes('fetch')) {
return '网络连接失败，请检查网络后重试';
}
return `${operation === 'approval' ? '审批' : operation === 'rejection' ? '拒绝' : '恢复'}失败: ${errorMessage}`;
}
```
#### Fix 2.3: 实现 check_idle_greeting（可选）⚡ 30分钟
**文件**: [heartbeat.rs](desktop/src-tauri/src/intelligence/heartbeat.rs)
**添加最后交互时间追踪**:
```rust
static LAST_INTERACTION: OnceLock<RwLock<StdHashMap<String, String>>> = OnceLock::new();
pub fn record_interaction(agent_id: &str) {
let map = get_last_interaction_map();
if let Ok(mut map) = map.write() {
map.insert(agent_id.to_string(), chrono::Utc::now().to_rfc3339());
}
}
fn check_idle_greeting(agent_id: &str) -> Option<HeartbeatAlert> {
let map = get_last_interaction_map();
let last_interaction = map.read().ok()?.get(agent_id).cloned()?;
let last_time = chrono::DateTime::parse_from_rfc3339(&last_interaction).ok()?;
let idle_hours = (chrono::Utc::now() - last_time).num_hours();
if idle_hours >= 24 {
Some(HeartbeatAlert {
title: "用户长时间未互动".to_string(),
content: format!("距离上次互动已过去 {} 小时", idle_hours),
urgency: Urgency::Low,
source: "idle-greeting".to_string(),
timestamp: chrono::Utc::now().to_rfc3339(),
})
} else {
None
}
}
```
**同时添加 Tauri 命令**:
```rust
#[tauri::command]
pub async fn heartbeat_record_interaction(agent_id: String) -> Result<(), String>
```
### Phase 3: 修复 LOW 优先级问题（可选）
#### Fix 3.1: localStorage fallback 存储大小计算
**文件**: [intelligence-client.ts](desktop/src/lib/intelligence-client.ts)
```typescript
// 在 fallbackMemory.stats() 中添加
let storageSizeBytes = 0;
try {
const serialized = JSON.stringify(store.memories);
storageSizeBytes = new Blob([serialized]).size;
} catch { /* ignore */ }
```
---
## 实现顺序
| 顺序 | 修复项 | 优先级 | 预估时间 |
|------|--------|--------|----------|
| 1 | Fix 1.1 - API 参数命名 | HIGH | 5 分钟 |
| 2 | Fix 1.2 - 周期性同步 | HIGH | 15 分钟 |
| 3 | Fix 1.3 - 心跳容错 | HIGH | 20 分钟 |
| 4 | Fix 2.1 - 类型统一 | MEDIUM | 10 分钟 |
| 5 | Fix 2.2 - 错误处理 | MEDIUM | 10 分钟 |
| 6 | Fix 2.3 - 空闲问候 | MEDIUM | 30 分钟 |
| 7 | Fix 3.1 - 存储大小 | LOW | 5 分钟 |
**总计**: 约 1.5 小时（不含可选项）
---
## 关键文件
| 文件 | 修改内容 |
|------|----------|
| [intelligence-client.ts](desktop/src/lib/intelligence-client.ts) | API 参数命名、类型转换、存储大小计算 |
| [App.tsx](desktop/src/App.tsx) | 周期性记忆统计同步 |
| [heartbeat.rs](desktop/src-tauri/src/intelligence/heartbeat.rs) | 缓存容错、空闲问候 |
| [intelligence-backend.ts](desktop/src/lib/intelligence-backend.ts) | 类型定义统一 |
| [IdentityChangeProposal.tsx](desktop/src/components/IdentityChangeProposal.tsx) | 错误处理增强 |
| [lib.rs](desktop/src-tauri/src/lib.rs) | 注册新 Tauri 命令（如实现 Fix 2.3） |
---
## 验证方法
### Fix 1.1 验证
```bash
# 启动应用，检查控制台
pnpm start:dev
# 观察 Tauri invoke 调用参数是否正确
```
### Fix 1.2 验证
```bash
# 启动后等待 5 分钟，检查控制台
# 应看到 "[App] Memory stats synced (periodic)" 日志
```
### Fix 1.3 验证
```bash
# 清除缓存后触发心跳
# 应看到 "记忆统计未同步" 告警
```
### 全量验证
```bash
# TypeScript 类型检查
pnpm tsc --noEmit
# 运行测试
pnpm vitest run
# 启动开发环境
pnpm start:dev
```
### 人工验证清单
- [ ] 应用启动无错误
- [ ] 心跳引擎正常初始化
- [ ] 记忆统计同步正常（启动 + 周期）
- [ ] 提案审批流程正常
- [ ] 错误信息清晰可读

276
plans/sharded-scribbling-dove.md Normal file
View File

@@ -0,0 +1,276 @@
# ZCLAW 自我进化功能实现计划
> **目标**: 让 ZCLAW 具备 OpenClaw 式的"自我进化"能力，让用户感受到 Agent 能够自我设置人格、持续学习改进。
---
## Context（背景）
### 用户反馈
> "没有 OpenClaw 那样懂得如何对自己进行人格设置，没有那种自我进化的感觉"
### 当前状态分析
**已实现（代码存在但体验不连贯）**：
| 功能 | 文件 | 状态 |
|------|------|------|
| 记忆系统 | `intelligence-client.ts` | ✅ L4 完成 |
| 反思引擎 | `intelligence-backend.ts:312-339` | ✅ L4 完成 |
| 自主授权 | `intelligence-backend.ts:352-433` | ✅ L4 完成 |
| 人格预设 | `personality-presets.ts` | ✅ 4种预设 |
| 引导向导 | `AgentOnboardingWizard.tsx` | ✅ 5步向导 |
| SOUL.md 生成 | `generateSoulContent()` | ⚠️ 只返回字符串，不写入文件 |
**核心问题** ~~（已全部解决 2025-03-24）~~：
1. ~~SOUL.md 生成后**不会写入文件系统**~~ ✅ 已解决
2. ~~反思结果**不会触发人格更新**~~ ✅ 已解决
3. ~~用户**无法审批/回滚人格变更**~~ ✅ 已解决
4. ~~缺少**人格演化历史可视化**~~ ✅ 已解决
5. ~~身份数据重启后丢失~~ ✅ 已解决（添加文件系统持久化）
---
## Part 1: 文档更新
### 1.1 需要创建的文档
| 优先级 | 文档路径 | 内容 |
|--------|----------|------|
| P0 | `docs/features/02-intelligence-layer/01-identity-evolution.md` | 身份演化系统设计 |
| P0 | `docs/features/02-intelligence-layer/04-heartbeat-engine.md` | 心跳巡检机制 |
| P0 | `docs/features/02-intelligence-layer/06-context-compaction.md` | 上下文压缩 |
### 1.2 需要更新的文档
| 优先级 | 文档路径 | 更新内容 |
|--------|----------|----------|
| P0 | `docs/ZCLAW_AGENT_INTELLIGENCE_EVOLUTION.md` | Phase 3-4 状态改为"已完成"，添加自我进化 UX 章节 |
| P1 | `docs/features/roadmap.md` | 添加自我进化功能到路线图 |
---
## Part 2: 自我进化功能架构
```
┌─────────────────────────────────────────────────────────────┐
│ Self-Evolution Flow │
├─────────────────────────────────────────────────────────────┤
│ │
│ ┌──────────┐ ┌───────────┐ ┌──────────────────┐ │
│ │ 对话历史 │───▶│ 反思引擎 │───▶│ 人格变更提案 │ │
│ │ │ │ │ │ (SOUL.md delta) │ │
│ └──────────┘ └───────────┘ └────────┬─────────┘ │
│ │ │
│ ▼ │
│ ┌──────────┐ ┌───────────┐ ┌──────────────────┐ │
│ │ 更新后的 │◀───│ 用户审批 │◀───│ 审批 UI │ │
│ │ SOUL.md │ │ │ │ (变更对比) │ │
│ └──────────┘ └───────────┘ └──────────────────┘ │
│ │ │
│ ▼ │
│ ┌──────────────────────────────────────────────────┐ │
│ │ 演化历史 │ │
│ │ - 时间戳快照 │ │
│ │ - 差异可视化 │ │
│ │ - 回滚能力 │ │
│ └──────────────────────────────────────────────────┘ │
│ │
└─────────────────────────────────────────────────────────────┘
```
---
## Part 3: 实现计划
### P0: 立即实现（快速见效） ✅ 已完成
#### P0.1: 连接 Onboarding 到 SOUL.md 持久化 ✅ 已完成
**目标**: 让人格选择真正写入文件
**修改文件**: `desktop/src/components/AgentOnboardingWizard.tsx`
**实现步骤**:
```typescript
// 在 handleSubmit() 中，创建 clone 后：
const soulContent = generateSoulContent({
agentName: formData.agentName,
emoji: formData.emoji,
personality: formData.personality,
scenarios: formData.scenarios,
});
await intelligenceClient.identity.updateFile(clone.id, 'soul', soulContent);
```
**验证**: 完成引导后检查 `~/.zclaw/agents/{agentId}/SOUL.md` 是否存在
---
#### P0.2: 创建缺失的智能层文档
**目标**: 文档化已实现的功能
**创建文件**:
1. `docs/features/02-intelligence-layer/01-identity-evolution.md`
2. `docs/features/02-intelligence-layer/04-heartbeat-engine.md`
3. `docs/features/02-intelligence-layer/06-context-compaction.md`
---
### P1: 核心自我进化功能 ✅ 已完成
#### P1.1: 人格变更提案 UI ✅ 已完成
**目标**: 展示人格变更供用户审批
**新建文件**:
- `desktop/src/components/IdentityChangeProposal.tsx` - 差异视图 + 接受/拒绝按钮
- `desktop/src/components/EvolutionHistory.tsx` - 变更时间线
**修改文件**:
- `desktop/src/components/RightPanel.tsx` - 添加 'evolution' tab
---
#### P1.2: 连接反思引擎到人格提案 ✅ 已完成
**目标**: 自动生成人格变更建议
**修改文件**:
- `desktop/src/lib/intelligence-backend.ts` - 增强 `reflection.reflect()` 生成提案
- `desktop/src/domains/intelligence/store.ts` - 添加提案状态管理
**实现逻辑**:
1. 反思运行后分析模式
2. 如果模式表明需要人格变更（如"用户偏好简洁回复"）：
- 生成 SOUL.md 修改建议
- 调用 `identity.proposeChange()`
3. 通知用户有待审批的提案
---
#### P1.3: 演化历史与回滚 ✅ 已完成
**目标**: 让用户查看和回滚人格变更
**新建文件**:
- `desktop/src/components/PersonalityVersionControl.tsx`
**实现**:
1. 每次 `identity.updateFile()` 前创建快照
2. 存储快照（时间戳 + 原因）
3. UI 显示变更时间线
4. 用户点击"恢复"可回滚
---
### P2: 增强体验 ✅ 已完成
#### P2.1: 主动人格建议 ✅ 已完成
**目标**: Agent 主动建议人格改进
**触发条件**:
- 用户重复纠正（"不要那么啰嗦"）
- 发现新偏好
- 上下文变化（新项目、不同角色）
**实现**: 心跳巡检时检测，达到阈值后排队提案
---
## Part 4: 关键文件清单
| 文件 | 修改类型 | 说明 |
|------|----------|------|
| `desktop/src/components/AgentOnboardingWizard.tsx` | 修改 | 添加 SOUL.md 持久化 |
| `desktop/src/lib/intelligence-client.ts` | 修改 | 确保 identity.updateFile() 正常工作 |
| `desktop/src/lib/intelligence-backend.ts` | 修改 | 反思→人格提案连接 |
| `desktop/src/components/RightPanel.tsx` | 修改 | 添加 evolution tab |
| `desktop/src/components/IdentityChangeProposal.tsx` | 新建 | 人格变更审批 UI |
| `desktop/src/components/EvolutionHistory.tsx` | 新建 | 演化历史时间线 |
| `docs/features/02-intelligence-layer/01-identity-evolution.md` | 新建 | 身份演化文档 |
---
## Part 5: 验证计划
### 用户体验验证
| 场景 | 预期结果 |
|------|----------|
| 完成引导向导 | SOUL.md 创建，包含选定人格 |
| Agent 反思对话 | 生成人格变更提案 |
| 用户批准提案 | SOUL.md 更新，创建快照 |
| 用户查看演化历史 | 显示时间线和差异 |
| 用户点击回滚 | 人格恢复到之前版本 |
### 技术验证
| 测试 | 命令 |
|------|------|
| 类型检查 | `pnpm tsc --noEmit` |
| 单元测试 | `pnpm vitest run` |
| E2E 测试 | `pnpm playwright test --project=tauri` |
---
## 实现优先级总结
| 优先级 | 任务 | 状态 |
|--------|------|------|
| P0.1 | SOUL.md 持久化 | ✅ 已完成 |
| P0.2 | 创建文档 | ✅ 已完成 |
| P1.1 | 人格变更 UI | ✅ 已完成 |
| P1.2 | 反思→人格连接 | ✅ 已完成 |
| P1.3 | 演化历史回滚 | ✅ 已完成 |
| P2.1 | 主动建议 | ✅ 已完成 |
| 额外 | 身份数据持久化 | ✅ 已完成 |
| 额外 | 错误反馈 UI | ✅ 已完成 |
| 额外 | 配置 localStorage 持久化 | ✅ 已完成 |
| 深度分析 | Fallback 反思引擎实现 | ✅ 已完成 |
| 深度分析 | 心跳人格改进检查实现 | ✅ 已完成 |
| 深度分析 | 心跳引擎自动启动 | ✅ 已完成 |
| 深度分析 | Fallback identity localStorage | ✅ 已完成 |
| 深度分析 | 配置默认值统一 | ✅ 已完成 |
**计划状态**: ✅ 全部完成 (2025-03-24)
---
## 深度分析修复记录 (2025-03-24)
### 发现的问题
| 优先级 | 问题 | 描述 |
|--------|------|------|
| CRITICAL | Fallback 反思引擎不产生提案 | `fallbackReflection.reflect()` 返回空数组 |
| HIGH | 心跳人格改进检查是占位符 | `check_personality_improvement()` 返回 None |
| HIGH | 心跳引擎未自动启动 | 需要手动调用 `heartbeat.start()` |
| MEDIUM | Fallback identity 不持久化 | 内存中的 Map，页面刷新后丢失 |
| LOW | 配置默认值不一致 | Rust: `allow_soul_modification: false`, TS: `true` |
### 修复内容
1. **Fallback 反思引擎** (`intelligence-client.ts:403-555`)
- 实现完整的模式分析逻辑
- 基于记忆类型、重要性、访问频率生成模式观察
- 自动生成改进建议和人格变更提案
2. **心跳人格改进检查** (`heartbeat.rs:330-460`)
- 添加 `CORRECTION_COUNTERS` 全局状态
- 实现 `record_user_correction()` 公共 API
- 基于用户纠正阈值触发人格改进建议
3. **心跳引擎自动启动** (`App.tsx:160-170`)
- 在应用 bootstrap 阶段自动初始化心跳引擎
- 使用默认配置启动 `zclaw-main` agent
4. **Fallback identity localStorage** (`intelligence-client.ts:558-680`)
- 添加 `IDENTITY_STORAGE_KEY` 和 `PROPOSALS_STORAGE_KEY`
- 所有修改操作后自动保存到 localStorage
- 启动时从 localStorage 加载已保存数据
5. **配置默认值统一** (`reflection.rs:41-51`)
- Rust `allow_soul_modification` 默认值改为 `true`
- 与 TypeScript 保持一致

211
plans/twinkly-frolicking-goblet.md Normal file
View File

@@ -0,0 +1,211 @@
# ZCLAW 上线发布分析 & 头脑风暴计划
## 一、项目现状总结
### 1.1 整体完成度评估
| 层级 | 完成度 | 关键问题 |
|------|--------|----------|
| **Rust 后端** | 72% | 流式响应、MCP 协议、驱动完整性 |
| **前端界面** | 85% | 技能创建 UI、工作流可视化 |
| **基础设施** | 60% | CI/CD 缺失、测试覆盖不足 |
### 1.2 各模块详细状态
#### Rust 后端 (72%)
| Crate | 完成度 | 关键缺失 | 风险 |
|-------|--------|----------|------|
| zclaw-types | 90% | 测试覆盖 | 低 |
| zclaw-memory | 85% | 迁移管理 | 中 |
| **zclaw-runtime** | **70%** | 流式响应未实现、Gemini/Local 驱动占位符 | **高** |
| zclaw-kernel | 80% | 配置加载、权限验证 | 中 |
| zclaw-skills | 75% | WASM/Native 执行器 | 中 |
| zclaw-hands | 85% | Browser Hand 未实现 | 中 |
| **zclaw-protocols** | **60%** | MCP 协议通信未实现 | **高** |
#### 前端界面 (85%)
| 模块 | 完成度 | 状态 |
|------|--------|------|
| 聊天界面 | 90% | 流式响应、多模型切换 ✅ |
| 分身管理 | 85% | CRUD 完成 |
| Hands 自动化 | 80% | 缺少实时执行进度 |
| 技能市场 | 70% | 缺少创建/编辑 UI |
| 工作流编辑 | 75% | 缺少可视化编辑器 |
| 配置管理 | 85% | 安全存储已实现 ✅ |
#### 基础设施 (60%)
| 项目 | 状态 | 影响 |
|------|------|------|
| E2E 测试 | 12 个 spec | 覆盖核心流程 |
| Rust 单元测试 | 34 个 | 需要扩展 |
| **CI/CD** | **缺失** | 无自动化构建/测试 |
| 文档 | 90+ md | 文档齐全 |
| Skills 定义 | 76+ | 生态丰富 |
| Hands 配置 | 11 个 | 核心能力覆盖 |
---
## 二、关键问题分级
### P0 - 阻塞发布 (必须有)
1. **流式响应实现**
- 位置: `crates/zclaw-runtime/src/loop_runner.rs:125`
- 状态: TODO 占位符
- 影响: 用户等待体验差，v0.2.0 核心卖点
2. **MCP 协议 MVP**
- 位置: `crates/zclaw-protocols/src/mcp.rs:151,155`
- 状态: 所有方法返回 "Not implemented"
- 影响: 无法接入 Claude Code 等工具生态
3. **Browser Hand 实现**
- 位置: `hands/browser.HAND.toml` (配置存在，实现缺失)
- 状态: 仅有配置，无 Rust 实现
- 影响: 最常用的自动化能力缺失
### P1 - 核心体验 (应该有)
4. **Ollama/Local 驱动**
- 位置: `crates/zclaw-runtime/src/driver/local.rs`
- 影响: 本地模型用户无法使用
5. **工具安全验证**
- 位置: `crates/zclaw-runtime/src/tool/builtin/shell_exec.rs`
- 状态: 返回模拟输出
- 影响: 安全风险
6. **测试覆盖提升**
- 当前: ~60%
- 目标: 70%+
### P2 - 完善功能 (可以有)
7. CI/CD 自动化
8. 技能创建 UI
9. 工作流可视化编辑器
10. Gemini 驱动
---
## 三、头脑风暴核心问题
### 3.1 发布策略
**Q1: 发布版本选择**
- A. v0.2.0-beta (内测) - 仅邀请用户
- B. v0.2.0-rc (公测) - 开放下载
- C. v0.2.0 (正式) - 完整发布
**Q2: 功能取舍**
- 流式响应: Plan A (完整实现) vs Plan B (SSE 简化) vs Plan C (优化模拟)
- MCP 协议: MVP (基础连接) vs 完整实现
- Browser Hand: 基础功能 vs 完整功能
**Q3: 时间线**
- 2 周内发布 (仅 P0)
- 4 周内发布 (P0 + P1)
- 6 周内发布 (完整功能)
### 3.2 技术决策
**Q4: 流式响应技术选型**
- 方案 A: 修改 LlmDriver trait + Tauri 事件
- 方案 B: SSE 端点 + EventSource
- 方案 C: WebSocket 流式通道
**Q5: Browser Hand 技术选型**
- headless-chrome (原生)
- playwright-rust
- puppeteer (Node.js 依赖)
**Q6: 代码签名**
- 自签名 (内测可接受)
- 购买证书 (正式发布必需)
### 3.3 用户策略
**Q7: 内测规模**
- 10-20 位核心用户
- 50-100 位早期用户
- 开放申请
**Q8: 反馈收集**
- GitHub Issues
- 专属反馈群
- 应用内反馈表单
---
## 四、推荐发布路径
```
Week 1-2: P0 完成
├── 流式响应实现 (Plan A/B)
├── MCP MVP 实现
└── 工具安全基础
Week 3-4: P1 完成
├── Browser Hand 基础
├── Ollama 驱动
└── 测试覆盖提升
Week 5-6: 测试+修复
├── 全量测试
├── Bug 修复
└── 文档完善
Week 7-8: 内测
├── 10-20 用户
├── 收集反馈
└── 问题修复
Week 9+: 公测/正式
├── 开放下载
├── 迭代优化
└── 正式发布
```
---
## 五、风险评估
| 风险 | 概率 | 影响 | 缓解措施 |
|------|------|------|----------|
| 流式响应延期 | 高 | 高 | SSE 简化方案备选 |
| MCP 兼容问题 | 中 | 中 | 先测试主流服务器 |
| Browser 依赖问题 | 中 | 中 | 预先验证 playwright |
| 内测反馈问题多 | 高 | 中 | 控制用户数量 |
| 安全漏洞 | 低 | 严重 | 安全审计 |
---
## 六、下一步行动
### 立即需要回答的问题
1. **发布时间目标**: 期望何时发布？
2. **功能优先级**: P0/P1 哪些必须完成？
3. **内测策略**: 邀请制还是开放申请？
4. **资源投入**: 全职开发还是兼职？
### 需要验证的技术点
1. `loop_runner.rs` 流式响应实现复杂度
2. `mcp.rs` MCP 协议最小实现范围
3. Browser Hand 技术选型验证
---
## 七、关键文件清单
| 文件 | 优先级 | 说明 |
|------|--------|------|
| `crates/zclaw-runtime/src/loop_runner.rs` | P0 | 流式响应核心 |
| `crates/zclaw-protocols/src/mcp.rs` | P0 | MCP 协议实现 |
| `crates/zclaw-runtime/src/tool/builtin/shell_exec.rs` | P1 | 工具安全 |
| `crates/zclaw-runtime/src/driver/local.rs` | P1 | 本地驱动 |
| `docs/superpowers/specs/2026-03-23-v0.2.0-release-design.md` | 参考 | v0.2.0 设计规格 |

307
plans/vast-enchanting-creek.md Normal file
View File

@@ -0,0 +1,307 @@
# ZCLAW 项目上线发布差距分析
## 上下文
本分析旨在评估 ZCLAW AI Agent 桌面客户端距离正式上线发布给用户使用还欠缺什么。通过对核心 Rust crates、桌面应用 UI/UX、测试覆盖和文档完善程度的深入分析，识别关键差距并制定优先级建议。
---
## 一、项目整体完成度评估
| 模块 | 完成度 | 状态 |
|------|--------|------|
| 核心类型层 (zclaw-types) | 95% | ✅ 生产就绪 |
| 存储层 (zclaw-memory) | 90% | ✅ 生产就绪 |
| 运行时 (zclaw-runtime) | 75% | ⚠️ 基本可用 |
| 核心协调 (zclaw-kernel) | 85% | ✅ 生产就绪 |
| 技能系统 (zclaw-skills) | 70% | ⚠️ 基本可用 |
| 自主能力 (zclaw-hands) | 80% | ⚠️ 教育场景完整 |
| 协议支持 (zclaw-protocols) | 60% | ⚠️ A2A 可用 |
| 通道适配 (zclaw-channels) | 40% | ❌ 框架阶段 |
| 桌面应用 UI | 75-80% | ⚠️ 主要功能完整 |
| 测试覆盖 | 60% | ⚠️ 需提升 |
| 文档完善 | 70% | ⚠️ 需补充 |
| 发布准备 | 50% | ❌ 不充分 |
**整体评估：约 70% 完成度**
---
## 二、关键差距分析
### 🔴 阻塞性问题 (必须修复才能发布)
#### 1. 流式响应未实现 (zclaw-runtime)
- **位置**: `crates/zclaw-runtime/src/loop_runner.rs:125`
- **问题**: `// TODO: Implement streaming` - 流式响应是占位符
- **影响**: 用户无法看到 AI 实时输出，体验极差
- **优先级**: P0 - 最高
#### 2. 版本号不一致
- **位置**: 多处
- `package.json`: 0.2.0
- `desktop/package.json`: 0.1.0
- `tauri.conf.json`: 0.2.0
- `Cargo.toml`: 0.1.0
- **影响**: 发布混乱，用户无法识别版本
- **优先级**: P0 - 最高
#### 3. MCP 协议未实现
- **位置**: `crates/zclaw-protocols/src/mcp.rs:151,155`
- **问题**: `// TODO: Implement actual MCP protocol communication`
- **影响**: 无法使用 Claude Code 等 MCP 工具生态
- **优先级**: P1 - 高
#### 4. 代码签名缺失
- **影响**: Windows 用户安装会遇到 SmartScreen 警告
- **优先级**: P1 - 高 (生产必需)
#### 5. CHANGELOG 缺失
- **影响**: 用户无法了解版本变更
- **优先级**: P1 - 高
### 🟠 重要问题 (影响用户体验)
#### 6. 无障碍支持不足
- **问题**: 大多数组件缺少 ARIA 属性和键盘导航
- **影响**: 无法服务残障用户
- **优先级**: P2 - 中
#### 7. 测试覆盖率低
- **当前**: 60% 阈值
- **目标**: 80%+
- **Rust 测试**: 仅 11 个文件有测试模块
- **优先级**: P2 - 中
#### 8. CI/CD 未集成测试
- **问题**: Gitea workflow 不运行测试
- **影响**: 质量无法自动保障
- **优先级**: P2 - 中
#### 9. 通道适配器未实现
- **问题**: Telegram/Discord/Slack 适配器仅有框架
- **影响**: 无法多平台使用
- **优先级**: P3 - 低 (取决于产品定位)
#### 10. 8 个通用 Hands 未实现
- **CLAUDE.md 提到**: Browser, Collector, Researcher, Predictor, Lead, Trader, Clip, Twitter
- **实际实现**: 仅 4 个教育类 Hands (Whiteboard, Slideshow, Speech, Quiz)
- **优先级**: P3 - 低 (取决于产品定位)
### 🟡 次要问题 (可后续迭代)
#### 11. API 文档缺失
- **问题**: 无专门的 API 参考文档
- **优先级**: P3
#### 12. 仅支持 Windows 构建
- **问题**: 无 macOS/Linux 构建
- **影响**: 限制用户群
- **优先级**: P3
#### 13. 国际化未实现
- **问题**: 所有 UI 字符串硬编码为中文
- **影响**: 无法国际化
- **优先级**: P4 (如果只面向中文用户)
---
## 三、功能可用性矩阵
| 功能 | UI | Store | Backend | 可用性 |
|------|----|----|---------|--------|
| 聊天 (流式) | ✅ | ✅ | ⚠️ 模拟 | 部分可用 |
| 多会话管理 | ✅ | ✅ | ✅ | 完全可用 |
| 分身管理 | ✅ | ✅ | ✅ | 完全可用 |
| 模型切换 | ✅ | ✅ | ✅ | 完全可用 |
| 自定义模型配置 | ✅ | ✅ | ✅ | 完全可用 |
| Hands 触发 | ✅ | ✅ | ⚠️ 部分 | 部分可用 |
| Hand 审批 | ✅ | ✅ | ✅ | 完全可用 |
| 工作流 | ✅ | ✅ | ✅ | 完全可用 |
| 技能市场 | ✅ | ✅ | ⚠️ 部分 | 部分可用 |
| 记忆图谱 | ✅ | ✅ | ⚠️ 部分 | 部分可用 |
| 离线模式 | ✅ | ✅ | N/A | 客户端完整 |
| 审计日志 | ✅ | ✅ | ✅ | 完全可用 |
| 安全层 | ✅ | ✅ | ✅ | 完全可用 |
---
## 四、发布前必须完成的工作清单
### Phase 1: 阻塞性修复 (1-2 周)
- [ ] **实现流式响应** - zclaw-runtime loop_runner.rs
- [ ] **统一版本号** - 所有配置文件同步
- [ ] **创建 CHANGELOG.md** - 记录版本变更
- [ ] **获取代码签名证书** - Windows 发布必需
### Phase 2: 质量保障 (1 周)
- [ ] **增加 Rust 单元测试** - 覆盖核心路径
- [ ] **CI 集成测试** - 自动运行测试
- [ ] **提升覆盖率阈值** - 从 60% 到 80%
### Phase 3: 用户体验 (1 周)
- [ ] **添加无障碍支持** - ARIA 属性、键盘导航
- [ ] **完善错误处理** - 用户友好的错误消息
- [ ] **性能优化** - 大消息列表虚拟化已有，需验证
### Phase 4: 文档与发布 (1 周)
- [ ] **补充 API 文档** - 公共接口参考
- [ ] **更新用户手册** - 所有功能说明
- [ ] **创建发布脚本** - 自动化发布流程
- [ ] **准备发布公告** - 产品介绍
---
## 五、可选功能路线图
### 短期 (v0.3.0)
1. MCP 协议实现
2. 代码签名
3. 无障碍改进
### 中期 (v0.4.0)
1. 通用 Hands (Browser, Collector 等)
2. macOS 支持
3. 视觉工作流构建器
### 长期 (v1.0.0)
1. 通道适配器 (Telegram, Discord)
2. 国际化
3. Linux 支持
---
## 六、风险评估
| 风险 | 概率 | 影响 | 缓解措施 |
|------|------|------|----------|
| 流式响应实现复杂度高 | 高 | 高 | 优先处理，可考虑降级方案 |
| 代码签名成本 | 中 | 高 | 预算规划，或使用自签名 |
| 测试覆盖不足导致回归 | 中 | 中 | CI 集成，增量提升 |
| MCP 协议变更 | 低 | 中 | 关注规范更新 |
| 第三方 API 变更 | 低 | 低 | 抽象层隔离 |
---
## 七、总结
### 项目优势
1. **架构清晰** - 分层设计，职责明确
2. **技术栈现代** - React 19, Tauri 2, Rust workspace
3. **安全意识强** - WSS 强制，设备认证，审计日志
4. **离线优先** - 消息队列，自动重连
### 关键差距
1. **流式响应** - 最影响用户体验的问题
2. **发布准备** - 版本管理、签名、CI/CD
3. **测试覆盖** - 低于行业标准
4. **生态集成** - MCP、通道适配器
### 建议发布策略
1. **先发布内测版 (v0.2.0-beta)** - 收集反馈
2. **修复阻塞性问题后发布公测版 (v0.3.0)**
3. **完善质量后发布正式版 (v1.0.0)**
---
---
## 八、头脑风暴决策结果
经过讨论，确定了以下关键决策：
### 决策 1：流式响应
**结论：必须实现真正流式**
- 不接受模拟方案
- 需要实现 SSE/WebSocket 真正的流式响应
### 决策 2：Hands 系统
**结论：补充核心通用 Hands**
- v0.2.0 必须包含 Browser Hand
- v0.2.0 必须包含 Collector Hand
- 保留现有 4 个教育类 Hands
### 决策 3：MCP 协议
**结论：必须实现**
- 完整的 MCP 协议通信
- 接入 Claude Code 等工具生态
### 决策 4：国际化
**结论：搭建多语言基础架构**
- 集成 react-i18next
- v0.2.0 仅支持中文
- 为未来国际化预留空间
### 决策 5：发布策略
**结论：内测 → 公测 → 正式**
- 内测版 (v0.2.0-beta)：邀请 10-20 位种子用户
- 公测版 (v0.2.0-rc)：开放下载
- 正式版 (v0.2.0)：稳定后发布
### 决策 6：时间线
**结论：灵活**
- 不设硬性日期
- 功能完成即发布
---
## 九、v0.2.0 发布计划
### 必须完成 (P0)
| 工作项 | 复杂度 | 说明 |
|--------|--------|------|
| 真正流式响应 | 高 | SSE/WebSocket 实现 |
| Browser Hand | 高 | 浏览器自动化能力 |
| Collector Hand | 中 | 数据收集聚合能力 |
| MCP 协议实现 | 高 | 完整 MCP 通信 |
### 应该完成 (P1)
| 工作项 | 复杂度 | 说明 |
|--------|--------|------|
| i18n 基础架构 | 中 | react-i18next 集成 |
| 版本号统一 | 低 | 所有配置同步 0.2.0 |
| CHANGELOG.md | 低 | 创建变更日志 |
| 代码签名 | 中 | Windows 发布必需 |
### 可以完成 (P2)
| 工作项 | 复杂度 | 说明 |
|--------|--------|------|
| 测试覆盖率提升 | 中 | 60% → 75%+ |
| 无障碍支持 | 中 | ARIA 属性 |
### 推迟到后续版本
| 工作项 | 推迟到 |
|--------|--------|
| 其他 6 个通用 Hands | v0.3.0 |
| 通道适配器 | v0.4.0 |
| macOS/Linux 构建 | v0.4.0 |
| 多语言翻译 | v0.3.0 |
### 成功标准
- [ ] 用户能正常进行流式对话
- [ ] Browser Hand 能完成基础网页自动化
- [ ] Collector Hand 能收集指定来源数据
- [ ] MCP 能连接至少 1 个外部工具
- [ ] Windows 安装无 SmartScreen 警告
- [ ] 内测用户无阻塞性问题反馈
---
## 十、下一步行动
1. **创建规格文档** - 写入 `docs/superpowers/specs/2026-03-23-v0.2.0-release-design.md`
2. **规格审查** - 确保设计完整性
3. **创建实现计划** - 详细的任务分解和时间估算
4. **开始实现** - 按优先级推进

164
plans/whimsical-humming-kite.md Normal file
View File

@@ -0,0 +1,164 @@
# 修复 LLM API 404 错误
## 问题描述
用户在对话时收到错误：
```
Chat failed: LLM error: API error 404 Not Found: {"error":{"message":"The requested resource was not found","type":"resource_not_found_error"}}
```
## 根因分析
### 1. 模型别名未被解析（主要原因）
**数据流问题：**
- 前端 `chatStore.ts:194` 默认模型是 `'glm-5'`
- 配置文件 `config.toml:131` 定义了别名映射 `"glm-5" = "zhipu/glm-4-plus"`
- **但是后端 `kernel.rs` 没有解析这个别名**，直接把 `'glm-5'` 发送给API
- 智谱API不认识 `'glm-5'`，返回404
### 2. 模型ID格式问题
配置文件使用带provider前缀的格式 `"zhipu/glm-4-plus"`，但：
- 智谱API只认识 `"glm-4-plus"`（不带前缀）
- `openai.rs:140` 直接传递模型ID，不做任何处理
### 3. 多处配置不一致
| 位置 | 默认Provider | 默认Model |
|------|-------------|-----------|
| `config.rs:84-88` | `"qwen"` | `"qwen-plus"` |
| `config.toml:115-116` | `"zhipu"` | `"glm-4-plus"` |
| `chatStore.ts:194` | - | `'glm-5'` (别名) |
| `loop_runner.rs:38` | - | `"claude-sonnet-4-20250514"` (硬编码) |
### 4. Kimi Base URL错误
`config.rs:92` 使用 `https://api.kimi.com/coding/v1`，正确应该是 `https://api.moonshot.cn/v1`
## 修复方案
### 修复1: 在Kernel中添加模型别名解析
**文件**: `crates/zclaw-kernel/src/kernel.rs`
在 `send_message` 和 `send_message_stream` 方法中，解析模型别名：
```rust
// 在 send_message 方法中，约第119行
// 添加模型别名解析函数
fn resolve_model_alias(model: &str, aliases: &HashMap<String, String>) -> String {
aliases.get(model).map(|s| s.as_str()).unwrap_or(model).to_string()
}
// 然后在确定模型后，检查是否是别名
let model = resolve_model_alias(model, &self.config.model_aliases);
```
### 修复2: 在KernelConfig中添加模型别名配置
**文件**: `crates/zclaw-kernel/src/config.rs`
1. 添加模型别名字段：
```rust
/// Model aliases (e.g., "glm-5" -> "zhipu/glm-4-plus")
#[serde(default)]
pub model_aliases: HashMap<String, String>,
```
2. 修正Kimi Base URL：
```rust
fn default_kimi_base_url() -> String {
"https://api.moonshot.cn/v1".to_string() // 修正
}
```
### 修复3: 在OpenAIDriver中规范化模型ID
**文件**: `crates/zclaw-runtime/src/driver/openai.rs`
在 `build_api_request` 方法中，去除provider前缀：
```rust
fn normalize_model_id(model: &str) -> String {
// 如果模型ID包含 "/"，取最后一部分
// 例如 "zhipu/glm-4-plus" -> "glm-4-plus"
if model.contains('/') {
model.split('/').last().unwrap_or(model).to_string()
} else {
model.to_string()
}
}
```
### 修复4: 统一默认配置
**文件**: `crates/zclaw-kernel/src/config.rs`
将默认provider和model改为与config.toml一致：
```rust
fn default_provider() -> String {
"zhipu".to_string()
}
fn default_model() -> String {
"glm-4-plus".to_string()
}
```
### 修复5: 移除loop_runner.rs中的硬编码默认值
**文件**: `crates/zclaw-runtime/src/loop_runner.rs`
第38行的硬编码模型应该移除，使用传入的配置：
```rust
// 移除硬编码，改为空字符串或从配置获取
model: String::new(), // 必须通过 with_model() 设置
```
## 关键文件
| 文件 | 修改内容 |
|------|----------|
| [config.rs](crates/zclaw-kernel/src/config.rs) | 添加model_aliases字段、修正Kimi URL、统一默认配置 |
| [kernel.rs](crates/zclaw-kernel/src/kernel.rs) | 添加模型别名解析逻辑 |
| [openai.rs](crates/zclaw-runtime/src/driver/openai.rs) | 添加模型ID规范化（去除provider前缀） |
| [loop_runner.rs](crates/zclaw-runtime/src/loop_runner.rs) | 移除硬编码默认模型 |
## 问题场景确认
用户使用**智谱 GLM** 模型时遇到404错误：
- 前端默认 `currentModel: 'glm-5'`
- 配置别名 `"glm-5" = "zhipu/glm-4-plus"`
- 后端未解析别名，直接发送 `'glm-5'` 给API
- 智谱API返回404
## 验证步骤
1. **单元测试**
```bash
cargo test -p zclaw-kernel --lib config::tests
cargo test -p zclaw-runtime --lib driver::openai::tests
```
2. **集成测试**
```bash
cargo test -p zclaw-kernel
```
3. **手动验证（智谱GLM）**
- 启动桌面应用：`pnpm start:dev`
- 在"模型与API"设置中配置智谱API Key
- 选择 `glm-5` 或 `glm-4-plus` 模型
- 发送消息，验证不再出现404错误
- 检查日志确认：
- 模型别名 `'glm-5'` 被解析为 `'zhipu/glm-4-plus'`
- provider前缀被去除，发送给API的是 `'glm-4-plus'`
## 实现顺序
1. **config.rs** - 添加model_aliases字段和修正Kimi URL
2. **openai.rs** - 添加模型ID规范化函数
3. **kernel.rs** - 添加别名解析逻辑
4. **loop_runner.rs** - 移除硬编码
5. **测试验证**