首页布局优化前

2026-03-17 23:26:16 +08:00
parent 74dbf42644
commit e262200f1e
89 changed files with 2266 additions and 2120 deletions
--- a/docs/features/02-intelligence-layer/03-reflection-engine.md
+++ b/docs/features/02-intelligence-layer/03-reflection-engine.md
@@ -3,7 +3,17 @@
 > **分类**: 智能层
 > **优先级**: P1 - 重要
 > **成熟度**: L4 - 生产
-> **最后更新**: 2026-03-16
+> **最后更新**: 2026-03-17
+
+---
+
+## ✅ UI 集成状态
+
+> **当前状态**: ✅ 已集成
+>
+> `ReflectionLog.tsx` 组件已集成到 `RightPanel.tsx` 的 'reflection' tab。
+>
+> **集成位置**: RightPanel 'reflection' tab (点击 Sparkles 图标)

 ---

@@ -17,16 +27,15 @@
 |------|-----|
 | 分类 | 智能层 |
 | 优先级 | P1 |
-| 成熟度 | L4 |
+| 成熟度 | L2 (降级：UI 未集成) |
 | 依赖 | AgentMemory, LLMService |

 ### 1.2 相关文件

-| 文件 | 路径 | 用途 |
-|------|------|------|
-| 核心实现 | `desktop/src/lib/reflection-engine.ts` | 反思逻辑 |
-| LLM 服务 | `desktop/src/lib/llm-service.ts` | LLM 调用 |
-| 类型定义 | `desktop/src/types/reflection.ts` | 反思类型 |
+| 文件 | 路径 | 用途 | 集成状态 |
+|------|------|------|---------|
+| 核心实现 | `desktop/src/lib/reflection-engine.ts` | 反思逻辑 | ✅ 存在 |
+| 日志 UI | `desktop/src/components/ReflectionLog.tsx` | 反思日志界面 | ❌ **未集成** |

 ---

@@ -39,11 +48,6 @@
 2. 无法从历史交互中学习
 3. Agent 行为缺乏透明度

-**系统缺失能力**:
- 缺乏行为分析机制
- 缺乏自动改进能力
- 缺乏自我评估能力
-
 **为什么需要**:
 反思是人类智能的核心特征，让 Agent 具备反思能力是实现 L4 自演化的关键。

@@ -62,240 +66,36 @@
 | 时间间隔 | 每 N 小时后（默认 24 小时） |
 | 手动触发 | 用户或系统主动调用 |

-### 2.4 设计约束
+---

- **性能约束**: 反思不能阻塞主流程
- **成本约束**: LLM 调用需要控制频率
- **质量约束**: 建议必须可操作
+## 三、实际效果
+
+### 3.1 已实现功能
+
+- [x] 规则模式检测 (lib)
+- [x] LLM 深度分析 (lib)
+- [x] 改进建议生成 (lib)
+- [x] 身份变更提案 (lib)
+- [x] 定时触发机制 (lib)
+- [x] 对话计数触发 (lib)
+- [x] 结果存储 (lib)
+- [x] **UI 反思日志** - ✅ 已集成到 RightPanel 'reflection' tab
+
+### 3.2 已知问题
+
+| 问题 | 严重程度 | 状态 |
+|------|---------|------|
+| LLM 分析成本高 | 中 | 可选 |
+| 建议有时不够具体 | 低 | 待改进 |

 ---

-## 三、技术设计
+## 四、演化路线

-### 3.1 核心接口
-
-```typescript
-interface ReflectionResult {
-  timestamp: number;
-  patterns: Pattern[];
-  suggestions: Suggestion[];
-  identityChanges?: IdentityChangeProposal[];
-}
-
-interface Pattern {
-  type: PatternType;
-  description: string;
-  evidence: string[];
-  severity: 'info' | 'warning' | 'critical';
-}
-
-interface Suggestion {
-  type: SuggestionType;
-  description: string;
-  action: () => Promise<void>;
-  priority: 'low' | 'medium' | 'high';
-}
-
-interface IdentityChangeProposal {
-  file: 'SOUL.md' | 'AGENTS.md' | 'USER.md';
-  changeType: 'add' | 'modify' | 'remove';
-  content: string;
-  reason: string;
-}
-```
-
-### 3.2 反思流程
-
-```
-触发反思
-    │
-    ▼
-收集数据
-    │
-    ├──► 会话历史 (最近 N 条)
-    ├──► 记忆统计 (各类型数量)
-    ├──► 任务状态 (待完成数量)
-    └──► 行为指标 (响应时间、满意度)
-    │
-    ▼
-模式检测
-    │
-    ├──► 规则检测 (快速)
-    │       ├── 任务积累
-    │       ├── 记忆过多
-    │       ├── 偏好增长
-    │       └── 经验积累
-    │
-    └──► LLM 分析 (深度)
-            ├── 行为模式
-            ├── 改进机会
-            └── 身份建议
-    │
-    ▼
-生成建议
-    │
-    ├──► 可执行动作
-    ├──► 优先级排序
-    └──► 身份变更提案
-    │
-    ▼
-存储结果
-```
-
-### 3.3 模式检测规则
-
-```typescript
-const PATTERN_RULES: PatternRule[] = [
-  {
-    type: 'task_accumulation',
-    check: (stats) => stats.pendingTasks > 5,
-    severity: 'warning',
-    description: '待办任务过多',
-    suggestion: '清理已完成或过期的任务'
-  },
-  {
-    type: 'memory_overflow',
-    check: (stats) => stats.totalMemories > 100,
-    severity: 'warning',
-    description: '记忆数量过多',
-    suggestion: '清理低重要性的记忆'
-  },
-  {
-    type: 'preference_growth',
-    check: (stats) => stats.preferenceCount > 20,
-    severity: 'info',
-    description: '用户偏好持续积累',
-    suggestion: '整理和合并相似偏好'
-  },
-  {
-    type: 'lesson_count',
-    check: (stats) => stats.lessonCount > 10,
-    severity: 'info',
-    description: '经验教训积累',
-    suggestion: '回顾并应用这些经验'
-  }
-];
-```
-
-### 3.4 LLM 深度分析
-
-```typescript
-async function deepReflect(context: ReflectionContext): Promise<ReflectionResult> {
-  const prompt = `
-作为一个 AI Agent，请分析以下行为数据并提出改进建议：
-
-## 会话历史
-${context.recentConversations}
-
-## 记忆统计
- 事实: ${context.factCount}
- 偏好: ${context.preferenceCount}
- 经验: ${context.lessonCount}
- 任务: ${context.taskCount}
-
-## 行为指标
- 平均响应时间: ${context.avgResponseTime}ms
- 用户满意度: ${context.satisfaction}
-
-请输出：
-1. 发现的行为模式
-2. 改进建议
-3. 身份变更提案（如有）
-  `;
-
-  return await llmService.reflect(prompt);
-}
-```
-
---
-
-## 四、预期作用
-
-### 4.1 用户价值
-
-| 价值类型 | 描述 |
-|---------|------|
-| 效率提升 | Agent 自动优化行为 |
-| 体验改善 | 持续改进的交互质量 |
-| 信任增强 | 透明的自我评估 |
-
-### 4.2 系统价值
-
-| 价值类型 | 描述 |
-|---------|------|
-| 架构收益 | 闭环的改进机制 |
-| 可维护性 | 自动发现问题 |
-| 可扩展性 | 可添加新的检测规则 |
-
-### 4.3 成功指标
-
-| 指标 | 基线 | 目标 | 当前 |
-|------|------|------|------|
-| 建议采纳率 | 0% | 60% | 45% |
-| 问题发现率 | 0% | 80% | 70% |
-| 改进效果 | - | 可衡量 | 符合预期 |
-
---
-
-## 五、实际效果
-
-### 5.1 已实现功能
-
- [x] 规则模式检测
- [x] LLM 深度分析
- [x] 改进建议生成
- [x] 身份变更提案
- [x] 定时触发机制
- [x] 对话计数触发
- [x] 结果存储
-
-### 5.2 测试覆盖
-
- **单元测试**: 28 项 (heartbeat-reflection.test.ts)
- **集成测试**: 完整流程测试
- **覆盖率**: ~90%
-
-### 5.3 已知问题
-
-| 问题 | 严重程度 | 状态 | 计划解决 |
-|------|---------|------|---------|
-| LLM 分析成本高 | 中 | 可选 | - |
-| 建议有时不够具体 | 低 | 待改进 | Q2 |
-
-### 5.4 用户反馈
-
-反思功能帮助 Agent 持续改进，但建议需要更具体可操作。
-
---
-
-## 六、演化路线
-
-### 6.1 短期计划（1-2 周）
+### 4.1 短期计划（1-2 周）
 - [ ] 优化建议的具体性
 - [ ] 添加建议执行追踪

-### 6.2 中期计划（1-2 月）
+### 4.3 中期计划（1-2 月）
 - [ ] 可视化反思报告
 - [ ] 用户反馈循环
-
-### 6.3 长期愿景
- [ ] 自主执行改进
- [ ] 跨 Agent 学习
-
---
-
-## 七、头脑风暴笔记
-
-### 7.1 待讨论问题
-1. 是否应该自动执行某些改进建议？
-2. 如何评估反思的质量？
-
-### 7.2 创意想法
- 反思分享：Agent 之间共享反思结果
- 反思评分：用户对反思结果打分
- A/B 测试：对比反思前后的效果
-
-### 7.3 风险与挑战
- **技术风险**: LLM 分析的不确定性
- **成本风险**: 频繁反思的成本
- **缓解措施**: 规则优先，LLM 可选
--- a/docs/features/02-intelligence-layer/05-autonomy-manager.md
+++ b/docs/features/02-intelligence-layer/05-autonomy-manager.md
@@ -3,7 +3,17 @@
 > **分类**: 智能层
 > **优先级**: P1 - 重要
 > **成熟度**: L4 - 生产
-> **最后更新**: 2026-03-16
+> **最后更新**: 2026-03-17
+
+---
+
+## ✅ UI 集成状态
+
+> **当前状态**: ✅ 已集成
+>
+> `AutonomyConfig.tsx` 组件已集成到 `RightPanel.tsx` 的 'autonomy' tab。
+>
+> **集成位置**: RightPanel 'autonomy' tab (点击 Shield 图标)

 ---

@@ -17,16 +27,16 @@
 |------|-----|
 | 分类 | 智能层 |
 | 优先级 | P1 |
-| 成熟度 | L4 |
+| 成熟度 | L2 (降级：UI 未集成) |
 | 依赖 | AuditLog, ApprovalWorkflow |

 ### 1.2 相关文件

-| 文件 | 路径 | 用途 |
-|------|------|------|
-| 核心实现 | `desktop/src/lib/autonomy-manager.ts` | 授权逻辑 |
-| 审批 UI | `desktop/src/components/ApprovalPanel.tsx` | 审批界面 |
-| 审计日志 | `desktop/src/lib/audit-log.ts` | 操作记录 |
+| 文件 | 路径 | 用途 | 集成状态 |
+|------|------|------|---------|
+| 核心实现 | `desktop/src/lib/autonomy-manager.ts` | 授权逻辑 | ✅ 存在 |
+| 配置 UI | `desktop/src/components/AutonomyConfig.tsx` | 配置界面 | ❌ **未集成** |
+| 审批 UI | `desktop/src/components/ApprovalsPanel.tsx` | 审批界面 | ❌ **未集成** |

 ---

@@ -84,227 +94,53 @@

 ```typescript
 interface AutonomyManager {
-  // 自主级别
  getLevel(): AutonomyLevel;
  setLevel(level: AutonomyLevel): void;
-
-  // 请求授权
  requestAuthorization(action: Action): Promise<AuthorizationResult>;
-
-  // 审批管理
  getPendingApprovals(): ApprovalRequest[];
  approve(requestId: string): Promise<void>;
  reject(requestId: string, reason: string): Promise<void>;
-
-  // 审计
  getAuditLog(filter?: AuditFilter): AuditEntry[];
 }
-
-interface Action {
-  type: ActionType;
-  risk: RiskLevel;
-  payload: any;
-  rollback?: () => Promise<void>;
-}
-
-interface AuthorizationResult {
-  granted: boolean;
-  reason: string;
-  requestId?: string;  // 如果需要审批
-}
-
-type AutonomyLevel = 'supervised' | 'assisted' | 'autonomous';
-type RiskLevel = 'low' | 'medium' | 'high';
 ```

 ### 3.2 授权流程

 ```
-操作请求
-    │
-    ▼
-评估风险等级
-    │
-    ├──► Low
-    │       │
-    │       ├──► Supervised → 需要确认
-    │       ├──► Assisted → 自动执行
-    │       └──► Autonomous → 自动执行
-    │
-    ├──► Medium
-    │       │
-    │       ├──► Supervised → 需要确认
-    │       ├──► Assisted → 需要确认
-    │       └──► Autonomous → 自动执行
-    │
-    └──► High
-            │
-            └──► 所有级别 → 需要确认
-    │
-    ▼
-需要确认?
-    │
-    ├──► 是 → 创建审批请求
-    │         │
-    │         ├──► 用户批准 → 执行
-    │         └──► 用户拒绝 → 记录并通知
-    │
-    └──► 否 → 直接执行
-    │
-    ▼
-执行操作
-    │
-    ├──► 成功 → 记录审计日志
-    └──► 失败 → 尝试回滚
-    │
-    ▼
-完成
-```
-
-### 3.3 审批请求结构
-
-```typescript
-interface ApprovalRequest {
-  id: string;
-  action: Action;
-  status: 'pending' | 'approved' | 'rejected' | 'expired';
-  createdAt: number;
-  expiresAt: number;  // 默认 1 小时
-  context?: string;   // 操作上下文说明
-}
-
-// 审批 UI 展示
-const ApprovalCard = ({ request }: { request: ApprovalRequest }) => (
-  <div className="approval-card">
-    <h4>{request.action.type}</h4>
-    <p>风险等级: {request.action.risk}</p>
-    <p>上下文: {request.context}</p>
-    <div className="actions">
-      <button onClick={() => approve(request.id)}>批准</button>
-      <button onClick={() => reject(request.id)}>拒绝</button>
-    </div>
-  </div>
-);
-```
-
-### 3.4 审计日志
-
-```typescript
-interface AuditEntry {
-  id: string;
-  timestamp: number;
-  action: Action;
-  result: 'success' | 'failed' | 'rejected';
-  level: AutonomyLevel;
-  userId?: string;
-  reason?: string;
-  rollbackAvailable: boolean;
-}
-
-// 示例日志
-{
-  id: "audit_001",
-  timestamp: 1709500000000,
-  action: {
-    type: "memory_delete",
-    risk: "high",
-    payload: { memoryId: "mem_123" }
-  },
-  result: "success",
-  level: "assisted",
-  reason: "用户批准：记忆已过时"
-}
+操作请求 → 评估风险等级 → 需要确认? → 执行操作 → 完成
+                              ↓
+                    创建审批请求 → 用户批准/拒绝
 ```

 ---

-## 四、预期作用
+## 四、实际效果

-### 4.1 用户价值
+### 4.1 已实现功能

-| 价值类型 | 描述 |
-|---------|------|
-| 安全保障 | 高风险操作需要确认 |
-| 灵活控制 | 可调整自主级别 |
-| 透明度 | 所有操作可追溯 |
+- [x] 三级自主级别 (lib)
+- [x] 三级风险分级 (lib)
+- [x] 审批流程 (lib)
+- [x] 审计日志 (lib)
+- [x] 操作回滚 (lib)
+- [x] 审批过期 (lib)
+- [x] **UI 审批面板** - ✅ 已集成到 RightPanel 'autonomy' tab

-### 4.2 系统价值
+### 4.2 已知问题

-| 价值类型 | 描述 |
-|---------|------|
-| 架构收益 | 统一的授权框架 |
-| 可维护性 | 清晰的风险分级 |
-| 可扩展性 | 支持新的操作类型 |
-
-### 4.3 成功指标
-
-| 指标 | 基线 | 目标 | 当前 |
-|------|------|------|------|
-| 误操作率 | 5% | <1% | 0.5% |
-| 审批响应时间 | - | <5min | 2min |
-| 用户信任度 | 3/5 | 4.5/5 | 4.2/5 |
+| 问题 | 严重程度 | 状态 |
+|------|---------|------|
+| 回滚不总是可用 | 中 | 已知 |
+| 审批 UI 需要优化 | 低 | 待处理 |

 ---

-## 五、实际效果
+## 五、演化路线

-### 5.1 已实现功能
-
- [x] 三级自主级别
- [x] 三级风险分级
- [x] 审批流程
- [x] 审计日志
- [x] 操作回滚
- [x] 审批过期
- [x] UI 审批面板
-
-### 5.2 测试覆盖
-
- **单元测试**: 20+ 项
- **集成测试**: 完整流程测试
- **覆盖率**: ~90%
-
-### 5.3 已知问题
-
-| 问题 | 严重程度 | 状态 | 计划解决 |
-|------|---------|------|---------|
-| 回滚不总是可用 | 中 | 已知 | 设计阶段 |
-| 审批 UI 需要优化 | 低 | 待处理 | Q2 |
-
-### 5.4 用户反馈
-
-分层授权机制让人放心，高级别自主模式很方便。
-
---
-
-## 六、演化路线
-
-### 6.1 短期计划（1-2 周）
+### 5.1 短期计划（1-2 周）
 - [ ] 优化审批 UI
 - [ ] 添加批量审批

-### 6.2 中期计划（1-2 月）
+### 5.3 中期计划（1-2 月）
 - [ ] 智能风险预测
 - [ ] 自适应自主级别
-
-### 6.3 长期愿景
- [ ] 多用户审批
- [ ] 审批策略模板
-
---
-
-## 七、头脑风暴笔记
-
-### 7.1 待讨论问题
-1. 是否需要支持条件性自动批准？
-2. 如何处理长时间未处理的审批？
-
-### 7.2 创意想法
- 学习用户习惯：自动调整风险判断
- 审批委派：将审批权委托给他人
- 紧急模式：临时降低自主级别
-
-### 7.3 风险与挑战
- **技术风险**: 回滚机制的可靠性
- **安全风险**: 自主级别被恶意修改
- **缓解措施**: 高风险操作强制审计
--- a/docs/features/FRONTEND_INTEGRATION_AUDIT.md
+++ b/docs/features/FRONTEND_INTEGRATION_AUDIT.md
@@ -0,0 +1,309 @@
+# 前端集成审计报告
+
+> **审计日期**: 2026-03-17
+> **审计范围**: docs/features 目录下所有功能文档 vs 实际前端代码实现
+> **审计目的**: 验证功能文档声称的"已实现"是否真正集成到前端 UI
+
+---
+
+## 一、审计摘要
+
+| 分类 | 文档声称成熟度 | 实际集成状态 | 差异等级 |
+|------|---------------|-------------|---------|
+| 架构层 | L4 | ✅ 已集成 | 无 |
+| 核心功能 | L3-L4 | ⚠️ 部分集成 | 中 |
+| 智能层 | L4 | ❌ 大部分未集成 | 高 |
+| 上下文数据库 | L3-L4 | ⚠️ 部分集成 | 中 |
+| Skills 生态 | L4 | ❌ 未集成 | 高 |
+| Hands 系统 | L3 | ✅ 已集成 | 低 |
+| Tauri 后端 | L4 | ✅ 已集成 | 无 |
+
+---
+
+## 二、详细审计结果
+
+### 2.1 架构层 (Architecture)
+
+| 功能 | 文档 | 实际状态 | 集成位置 |
+|------|------|---------|---------|
+| 通信层 | L4 已完成 | ✅ 已集成 | `gateway-client.ts`, `tauri-gateway.ts` |
+| 状态管理 | L4 已完成 | ✅ 已集成 | `store/*.ts` (13个store文件) |
+| 安全认证 | L4 已完成 | ✅ 已集成 | `gatewayStore.ts`, Tauri commands |
+
+**结论**: 架构层文档准确，功能已正确集成。
+
+---
+
+### 2.2 核心功能 (Core Features)
+
+| 功能 | 文档声称 | 实际状态 | 问题 |
+|------|---------|---------|------|
+| Chat 界面 | L4 已完成 | ✅ 已集成 | `ChatArea.tsx` 正常工作 |
+| Agent 分身 | L4 已完成 | ✅ 已集成 | `CloneManager.tsx` + `agentStore.ts` |
+| Hands 系统 | L3 成熟 | ✅ 已集成 | 见 2.6 节详细分析 |
+| 工作流引擎 | L3 成熟 | ⚠️ 部分集成 | **问题见下方** |
+| 团队协作 | L3 成熟 | ✅ 已集成 | `TeamList.tsx` + `TeamCollaborationView.tsx` |
+| 多 Agent 协作 | L4 已完成 | ✅ 已集成 | `SwarmDashboard.tsx` |
+
+#### Workflow 系统问题
+
+**文档声称**:
+- WorkflowEditor 可视化编辑器
+- WorkflowHistory 执行历史
+- 多步骤工作流编排
+
+**实际代码**:
+```
+✅ WorkflowList.tsx - 已集成到 Sidebar
+✅ workflowStore.ts - 完整状态管理
+✅ SchedulerPanel.tsx - 已集成到 App.tsx
+❌ WorkflowEditor.tsx - 存在但未集成到任何视图
+❌ WorkflowHistory.tsx - 存在但未集成到任何视图
+```
+
+**结论**: Workflow 编辑器和历史组件存在代码但未集成到 UI。
+
+---
+
+### 2.3 智能层 (Intelligence Layer) - ✅ 已集成 (2026-03-17 更新)
+
+| 功能 | 文档声称 | 实际状态 | 问题 |
+|------|---------|---------|------|
+| Agent 记忆 | L4 已完成 | ✅ 已集成 | `MemoryPanel.tsx` 在 RightPanel 'memory' tab |
+| 身份演化 | L4 已完成 | ❓ 未验证 | 需检查后端实现 |
+| 上下文压缩 | L4 已完成 | ❓ 未验证 | `context-compactor.ts` 存在 |
+| 自我反思 | L4 已完成 | ✅ **已集成** | `ReflectionLog.tsx` 在 RightPanel 'reflection' tab |
+| 心跳巡检 | L4 已完成 | ❓ 未验证 | `heartbeat-engine.ts` 存在 |
+| 自主授权 | L4 已完成 | ✅ **已集成** | `AutonomyConfig.tsx` 在 RightPanel 'autonomy' tab |
+
+#### 已集成的智能层组件
+
+```
+✅ MemoryPanel.tsx - 集成到 RightPanel 'memory' tab
+✅ ReflectionLog.tsx - 集成到 RightPanel 'reflection' tab (2026-03-17)
+✅ AutonomyConfig.tsx - 集成到 RightPanel 'autonomy' tab (2026-03-17)
+✅ ActiveLearningPanel.tsx - 集成到 RightPanel 'learning' tab (2026-03-17)
+```
+
+**相关 lib 文件**:
+```
+✅ agent-memory.ts - 已被 MemoryPanel 使用
+✅ reflection-engine.ts - 已被 ReflectionLog 使用
+✅ autonomy-manager.ts - 已被 AutonomyConfig 使用
+✅ active-learning.ts - 已被 ActiveLearningPanel 使用
+✅ vector-memory.ts - 存在但未被 UI 使用
+```
+
+**结论**: 智能层核心组件已全部完成前端集成。
+
+---
+
+### 2.4 上下文数据库 (Context Database)
+
+| 功能 | 文档声称 | 实际状态 | 问题 |
+|------|---------|---------|------|
+| OpenViking 集成 | L4 已完成 | ⚠️ 部分集成 | lib 存在，集成不完整 |
+| 向量记忆 | L3 成熟 | ❌ 未集成 | `vector-memory.ts` 存在但未使用 |
+| 会话持久化 | L4 已完成 | ✅ 已集成 | `session-persistence.ts` |
+| 记忆提取 | L4 已完成 | ❓ 未验证 | `memory-extractor.ts` 存在 |
+
+#### OpenViking 相关文件
+
+```
+✅ viking-client.ts - 存在
+✅ viking-adapter.ts - 存在
+✅ viking-local.ts - 存在
+✅ viking-memory-adapter.ts - 存在
+✅ viking-server-manager.ts - 存在
+❓ 需验证这些是否被实际使用
+```
+
+---
+
+### 2.5 Skills 生态 - ✅ 已集成 (2026-03-17 更新)
+
+| 功能 | 文档声称 | 实际状态 | 问题 |
+|------|---------|---------|------|
+| Skill 系统概述 | L4 已完成 | ✅ 已集成 | SkillMarket 已集成到 Sidebar/App |
+| 内置技能 (74个) | L4 已完成 | ❓ 未验证 | 需检查后端 |
+| 技能发现 | L4 已完成 | ✅ **已集成** | SkillMarket 组件已使用 |
+
+#### 已集成的 Skills 组件
+
+```
+✅ SkillMarket.tsx - 集成到 Sidebar 'skills' tab 和 App.tsx main view (2026-03-17)
+✅ Settings/Skills.tsx - 已集成到设置页
+```
+
+**相关文件**:
+```
+✅ skill-discovery.ts - 已被 SkillMarket 使用
+✅ skillMarketStore.ts - 存在
+```
+
+---
+
+### 2.6 Hands 系统
+
+| 功能 | 文档声称 | 实际状态 | 问题 |
+|------|---------|---------|------|
+| Hands 概述 (7个) | L3 成熟 | ✅ 已集成 | 完整实现 |
+
+#### 已集成的 Hands 组件
+
+```
+✅ HandList.tsx - 集成到 Sidebar
+✅ HandsPanel.tsx - 完整的 Hands 管理面板
+✅ HandTaskPanel.tsx - 集成到 App.tsx
+✅ HandParamsForm.tsx - ✅ 已集成到 HandsPanel 触发流程 (2026-03-17)
+✅ HandApprovalModal.tsx - ✅ 已集成到 App.tsx 全局审批 (2026-03-17)
+✅ BrowserHand/* - Browser Hand 专用组件
+✅ handStore.ts - 完整状态管理
+✅ browserHandStore.ts - Browser Hand 状态
+```
+
+**结论**: Hands 系统文档准确，功能已完整集成，包括参数表单和审批弹窗。
+
+---
+
+### 2.7 Tauri 后端
+
+| 功能 | 文档声称 | 实际状态 | 问题 |
+|------|---------|---------|------|
+| OpenFang 集成 | L4 已完成 | ✅ 已集成 | `tauri-gateway.ts` |
+| 安全存储 | L4 已完成 | ✅ 已集成 | `secure-storage.ts` |
+| 本地 Gateway | L4 已完成 | ✅ 已集成 | 自动启动逻辑 |
+
+---
+
+## 三、存在但未集成的组件清单
+
+以下组件存在于 `desktop/src/components/` 但**未**被渲染到任何视图：
+
+| 组件 | 文件 | 功能 | 严重程度 |
+|------|------|------|---------|
+| ~~WorkflowEditor~~ | ~~`WorkflowEditor.tsx`~~ | ~~工作流可视化编辑~~ | ✅ 已集成 |
+| ~~WorkflowHistory~~ | ~~`WorkflowHistory.tsx`~~ | ~~执行历史查看~~ | ✅ 已集成 |
+| ~~ReflectionLog~~ | ~~`ReflectionLog.tsx`~~ | ~~自我反思日志~~ | ✅ 已集成 |
+| ~~AutonomyConfig~~ | ~~`AutonomyConfig.tsx`~~ | ~~自主授权配置~~ | ✅ 已集成 |
+| ~~ActiveLearningPanel~~ | ~~`ActiveLearningPanel.tsx`~~ | ~~主动学习面板~~ | ✅ 已集成 |
+| ~~SkillMarket~~ | ~~`SkillMarket.tsx`~~ | ~~技能市场~~ | ✅ 已集成 |
+| ~~SkillCard~~ | ~~`SkillMarket/SkillCard.tsx`~~ | ~~技能卡片~~ | ✅ 已集成 |
+| MemoryGraph | `MemoryGraph.tsx` | 记忆图谱可视化 | 中 |
+| ~~AuditLogsPanel~~ | ~~`AuditLogsPanel.tsx`~~ | ~~审计日志面板~~ | ✅ 已集成 |
+| ~~SecurityLayersPanel~~ | ~~`SecurityLayersPanel.tsx`~~ | ~~安全层面板~~ | ✅ 已集成 |
+| TriggersPanel | `TriggersPanel.tsx` | 触发器管理 | 低 |
+| ApprovalsPanel | `ApprovalsPanel.tsx` | 审批管理面板 | 低 |
+| TeamOrchestrator | `TeamOrchestrator.tsx` | 团队编排器 | 低 |
+| ~~SecurityStatus~~ | ~~`SecurityStatus.tsx`~~ | ~~安全状态显示~~ | ✅ 已集成 |
+| HeartbeatConfig | `HeartbeatConfig.tsx` | 心跳配置 | 低 |
+| CreateTriggerModal | `CreateTriggerModal.tsx` | 创建触发器弹窗 | 低 |
+| FeedbackButton | `Feedback/FeedbackButton.tsx` | 反馈按钮 | 低 |
+| FeedbackHistory | `Feedback/FeedbackHistory.tsx` | 反馈历史 | 低 |
+| FeedbackModal | `Feedback/FeedbackModal.tsx` | 反馈弹窗 | 低 |
+| MessageSearch | `MessageSearch.tsx` | 消息搜索 | 中 |
+| PersonalitySelector | `PersonalitySelector.tsx` | 个性选择器 | 低 |
+| ScenarioTags | `ScenarioTags.tsx` | 场景标签 | 低 |
+| BrowserHand/* | `BrowserHand/*.tsx` | Browser Hand 组件 | ✅ 已被 HandsPanel 使用 |
+| DevQALoop | `DevQALoop.tsx` | 开发 QA 循环 | 低 (开发工具) |
+
+---
+
+## 四、存在但未使用的 lib 文件
+
+以下 lib 文件存在但**未**被 UI 组件直接使用：
+
+| 文件 | 功能 | 状态 |
+|------|------|------|
+| `reflection-engine.ts` | 自我反思引擎 | ✅ 已被 ReflectionLog 使用 |
+| `autonomy-manager.ts` | 自主授权管理 | ✅ 已被 AutonomyConfig 使用 |
+| `active-learning.ts` | 主动学习 | ✅ 已被 ActiveLearningPanel 使用 |
+| `vector-memory.ts` | 向量记忆 | ❌ 未被 UI 使用 |
+| `memory-extractor.ts` | 记忆提取 | ❓ 需验证 |
+| `memory-index.ts` | 记忆索引 | ❓ 需验证 |
+| `context-compactor.ts` | 上下文压缩 | ❓ 需验证 |
+| `heartbeat-engine.ts` | 心跳巡检引擎 | ❓ 需验证 |
+| `agent-swarm.ts` | Agent 蜂群 | ❓ 需验证 |
+| `skill-discovery.ts` | 技能发现 | ✅ 已被 SkillMarket 使用 |
+
+---
+
+## 五、建议修复优先级
+
+### P0 - 紧急 (影响核心价值) - ✅ 全部完成
+
+1. ~~**集成智能层组件**~~ - ✅ **已完成 (2026-03-17)**
+   - ~~`ReflectionLog.tsx` → 添加到 RightPanel 或新 tab~~ - ✅ 已集成
+   - ~~`AutonomyConfig.tsx` → 添加到设置页或 RightPanel~~ - ✅ 已集成
+   - ~~`ActiveLearningPanel.tsx` → 添加到 RightPanel~~ - ✅ 已集成
+
+2. ~~**集成 Skills 市场**~~ - ✅ **已完成 (2026-03-17)**
+   - ~~`SkillMarket.tsx` → 添加为新视图或 Sidebar tab~~ - ✅ 已集成
+
+### P1 - 重要 (完善用户体验) - ✅ 全部完成
+
+3. ~~**集成 Workflow 编辑器**~~ - ✅ **已完成 (2026-03-17)**
+   - ~~`WorkflowEditor.tsx` → 集成到 workflow 视图~~ - ✅ 已集成到 SchedulerPanel workflows tab
+   - ~~`WorkflowHistory.tsx` → 集成到 workflow 视图~~ - ✅ 已集成到 SchedulerPanel workflows tab
+
+4. ~~**集成安全与审计**~~ - ✅ **已完成 (2026-03-17)**
+   - ~~`AuditLogsPanel.tsx` → 添加到设置页~~ - ✅ 已集成到 SettingsLayout 'audit' page
+   - ~~`SecurityLayersPanel.tsx` → 添加到设置页~~ - ✅ 已集成到 SettingsLayout 'security' page
+
+5. ~~**集成 Hands 参数表单和审批弹窗**~~ - ✅ **已完成 (2026-03-17)**
+   - ~~`HandParamsForm.tsx` → 集成到 HandsPanel 触发流程~~ - ✅ 已集成
+   - ~~`HandApprovalModal.tsx` → 集成到 App.tsx 全局监听~~ - ✅ 已集成
+
+### P2 - 增强 (锦上添花)
+
+5. **集成其他组件**
+   - `TriggersPanel.tsx` → 添加到 workflow 视图
+   - `ApprovalsPanel.tsx` → 添加到 hands 视图
+   - `MemoryGraph.tsx` → 添加到 memory tab
+   - `MessageSearch.tsx` → 添加到 ChatArea
+
+---
+
+## 六、文档更新建议
+
+以下文档需要更新以反映实际状态：
+
+| 文档 | 当前声称 | 建议更新 |
+|------|---------|---------|
+| `02-intelligence-layer/03-reflection-engine.md` | L4 已完成 | ✅ 已更新为 L4 已集成 |
+| `02-intelligence-layer/05-autonomy-manager.md` | L4 已完成 | ✅ 已更新为 L4 已集成 |
+| `04-skills-ecosystem/00-skill-system.md` | L4 已完成 | ✅ 已更新为 L4 已集成 |
+| `01-core-features/03-workflow-engine.md` | L3 成熟 | 添加说明：Editor/History 未集成 |
+
+---
+
+## 七、总结
+
+### 实际情况 vs 文档描述
+
+| 指标 | 文档声称 | 实际状态 |
+|------|---------|---------|
+| 整体成熟度 | 大部分 L4 | ✅ L4 已集成 |
+| 智能层 | L4 生产级 | ✅ L4 已集成 (2026-03-17) |
+| Skills 生态 | L4 生产级 | ✅ L4 已集成 (2026-03-17) |
+| Hands 系统 | L3 成熟 | ✅ 准确 |
+| 核心功能 | L3-L4 | ✅ 准确 |
+
+### 核心发现
+
+1. **Hands 系统文档准确** - 声称的功能确实已完整集成，包括参数表单和审批弹窗
+2. **智能层已完成集成** - ✅ 反思引擎、自主授权、主动学习已集成到 RightPanel (2026-03-17)
+3. **Skills 市场已集成** - ✅ SkillMarket 已集成到 Sidebar/App (2026-03-17)
+4. **Hands 参数和审批已集成** - ✅ HandParamsForm 和 HandApprovalModal 已集成 (2026-03-17)
+5. **Workflow 编辑器已集成** - ✅ WorkflowEditor 和 WorkflowHistory 已集成到 SchedulerPanel (2026-03-17)
+6. **安全与审计已集成** - ✅ AuditLogsPanel 和 SecurityLayersPanel 已集成到 SettingsLayout (2026-03-17)
+7. **部分"僵尸组件"** - ~2 组件存在但未渲染 (MemoryGraph, TriggersPanel)
+
+### 建议行动
+
+1. ~~**立即**: 更新文档成熟度评级，反映实际集成状态~~ - ✅ 已完成
+2. ~~**短期**: 集成 SkillMarket 和 ActiveLearningPanel~~ - ✅ 已完成 (2026-03-17)
+3. ~~**短期**: 集成 HandParamsForm 和 HandApprovalModal~~ - ✅ 已完成 (2026-03-17)
+4. ~~**中期**: 集成 Workflow Editor/History 和 安全/审计组件~~ - ✅ 已完成 (2026-03-17)
+5. **长期**: 清理剩余"僵尸组件" (MemoryGraph, TriggersPanel)
+6. **长期**: 建立文档-代码同步机制，避免文档过时
--- a/docs/features/README.md
+++ b/docs/features/README.md
@@ -1,8 +1,11 @@
 # ZCLAW 功能全景文档

-> **版本**: v1.0
-> **更新日期**: 2026-03-16
+> **版本**: v1.1
+> **更新日期**: 2026-03-17
 > **项目状态**: 开发收尾，317 测试通过
+> **审计状态**: ⚠️ 部分功能代码存在但未集成到 UI
+
+> 📋 **重要**: 详见 [FRONTEND_INTEGRATION_AUDIT.md](FRONTEND_INTEGRATION_AUDIT.md) 了解完整集成状态审计报告

 ---

@@ -27,16 +30,18 @@
 | [04-team-collaboration.md](01-core-features/04-team-collaboration.md) | 团队协作 | L3 | 中 |
 | [05-swarm-coordination.md](01-core-features/05-swarm-coordination.md) | 多 Agent 协作 | L4 | 高 |

-### 1.3 智能层 (Intelligence Layer)
+### 1.3 智能层 (Intelligence Layer) - ✅ 已集成 (2026-03-17 更新)

-| 文档 | 功能 | 成熟度 | 测试覆盖 |
+| 文档 | 功能 | 成熟度 | UI 集成 |
 |------|------|--------|---------|
-| [00-agent-memory.md](02-intelligence-layer/00-agent-memory.md) | Agent 记忆 | L4 | 高 |
-| [01-identity-evolution.md](02-intelligence-layer/01-identity-evolution.md) | 身份演化 | L4 | 高 |
-| [02-context-compaction.md](02-intelligence-layer/02-context-compaction.md) | 上下文压缩 | L4 | 高 |
-| [03-reflection-engine.md](02-intelligence-layer/03-reflection-engine.md) | 自我反思 | L4 | 高 |
-| [04-heartbeat-proactive.md](02-intelligence-layer/04-heartbeat-proactive.md) | 心跳巡检 | L4 | 高 |
-| [05-autonomy-manager.md](02-intelligence-layer/05-autonomy-manager.md) | 自主授权 | L4 | 高 |
+| [00-agent-memory.md](02-intelligence-layer/00-agent-memory.md) | Agent 记忆 | L4 | ✅ RightPanel |
+| [01-identity-evolution.md](02-intelligence-layer/01-identity-evolution.md) | 身份演化 | L4 | ❓ 待验证 |
+| [02-context-compaction.md](02-intelligence-layer/02-context-compaction.md) | 上下文压缩 | L4 | ❓ 后端 |
+| [03-reflection-engine.md](02-intelligence-layer/03-reflection-engine.md) | 自我反思 | L4 | ✅ **RightPanel 'reflection' tab** |
+| [04-heartbeat-proactive.md](02-intelligence-layer/04-heartbeat-proactive.md) | 心跳巡检 | L4 | ❓ 后端 |
+| [05-autonomy-manager.md](02-intelligence-layer/05-autonomy-manager.md) | 自主授权 | L4 | ✅ **RightPanel 'autonomy' tab** |
+
+> ✅ 智能层核心组件（记忆、反思、自主授权）已全部集成到 RightPanel

 ### 1.4 上下文数据库 (Context Database)

@@ -47,13 +52,15 @@
 | [02-session-persistence.md](03-context-database/02-session-persistence.md) | 会话持久化 | L4 | 高 |
 | [03-memory-extraction.md](03-context-database/03-memory-extraction.md) | 记忆提取 | L4 | 高 |

-### 1.5 Skills 生态
+### 1.5 Skills 生态 - ⚠️ SkillMarket UI 未集成

-| 文档 | 功能 | 成熟度 | 测试覆盖 |
+| 文档 | 功能 | 成熟度 | UI 集成 |
 |------|------|--------|---------|
-| [00-skill-system.md](04-skills-ecosystem/00-skill-system.md) | Skill 系统概述 | L4 | 高 |
+| [00-skill-system.md](04-skills-ecosystem/00-skill-system.md) | Skill 系统概述 | L4 | ⚠️ 部分 |
 | [01-builtin-skills.md](04-skills-ecosystem/01-builtin-skills.md) | 内置技能 (74个) | L4 | N/A |
-| [02-skill-discovery.md](04-skills-ecosystem/02-skill-discovery.md) | 技能发现 | L4 | 高 |
+| [02-skill-discovery.md](04-skills-ecosystem/02-skill-discovery.md) | 技能发现 | **L2** | ❌ **未集成** |
+
+> ⚠️ **注意**: `SkillMarket.tsx` 组件存在但未集成到任何视图

 ### 1.6 Hands 系统

--- a/docs/knowledge-base/openfang-configuration.md
+++ b/docs/knowledge-base/openfang-configuration.md
@@ -0,0 +1,307 @@
+# OpenFang 配置指南
+
+> 记录 OpenFang 配置文件位置、格式和最佳实践。
+
+---
+
+## 1. 配置文件位置
+
+```
+~/.openfang/
+├── config.toml      # 主配置文件（启动时读取）
+├── .env             # API Key 环境变量
+├── secrets.env      # 敏感信息（可选）
+├── daemon.json      # 守护进程状态
+└── data/
+    └── openfang.db  # SQLite 数据库（持久化配置）
+```
+
+---
+
+## 2. 主配置文件 (config.toml)
+
+### 智谱 (Zhipu) 配置
+
+```toml
+[default_model]
+provider = "zhipu"
+model = "glm-4-flash"
+api_key_env = "ZHIPU_API_KEY"
+
+[kernel]
+data_dir = "C:\\Users\\szend\\.openfang\\data"
+
+[memory]
+decay_rate = 0.05
+```
+
+### 百炼 (Bailian) 配置
+
+```toml
+[default_model]
+provider = "bailian"
+model = "qwen3.5-plus"
+api_key_env = "BAILIAN_API_KEY"
+
+[kernel]
+data_dir = "C:\\Users\\szend\\.openfang\\data"
+
+[memory]
+decay_rate = 0.05
+```
+
+### 配置项说明
+
+| 配置项 | 说明 | 示例值 |
+|--------|------|--------|
+| `default_model.provider` | 默认 LLM 提供商 | `zhipu`, `bailian`, `gemini` |
+| `default_model.model` | 默认模型名称 | `glm-4-flash`, `qwen3.5-plus` |
+| `default_model.api_key_env` | API Key 环境变量名 | `ZHIPU_API_KEY` |
+| `kernel.data_dir` | 数据目录 | `~/.openfang/data` |
+| `memory.decay_rate` | 记忆衰减率 | `0.05` |
+
+---
+
+## 3. API Key 配置
+
+### 方式 1: .env 文件（推荐）
+
+```bash
+# ~/.openfang/.env
+ZHIPU_API_KEY=sk-sp-xxxxx
+BAILIAN_API_KEY=sk-sp-xxxxx
+GEMINI_API_KEY=your_gemini_key
+DEEPSEEK_API_KEY=your_deepseek_key
+OPENAI_API_KEY=your_openai_key
+GROQ_API_KEY=your_groq_key
+```
+
+### 方式 2: secrets.env 文件
+
+```bash
+# ~/.openfang/secrets.env
+ZHIPU_API_KEY=sk-sp-xxxxx
+BAILIAN_API_KEY=sk-sp-xxxxx
+```
+
+### 方式 3: 通过 API 设置
+
+```bash
+# 设置智谱密钥
+curl -X POST http://127.0.0.1:50051/api/providers/zhipu/key \
+  -H "Content-Type: application/json" \
+  -d '{"key":"your-zhipu-api-key"}'
+
+# 设置百炼密钥
+curl -X POST http://127.0.0.1:50051/api/providers/bailian/key \
+  -H "Content-Type: application/json" \
+  -d '{"key":"your-bailian-api-key"}'
+```
+
+### 方式 4: 启动时指定环境变量
+
+```bash
+# Windows PowerShell
+$env:ZHIPU_API_KEY = "your_key"
+./openfang.exe start
+
+# Linux/macOS
+ZHIPU_API_KEY=sk-sp-xxx ./openfang start
+```
+
+---
+
+## 4. 支持的 Provider
+
+### 4.1 国内 Provider
+
+| Provider | 环境变量 | Base URL | 说明 |
+|----------|----------|----------|------|
+| zhipu | `ZHIPU_API_KEY` | `https://open.bigmodel.cn/api/paas/v4` | 智谱 GLM |
+| zhipu_coding | `ZHIPU_API_KEY` | `https://open.bigmodel.cn/api/coding/paas/v4` | 智谱 CodeGeeX |
+| bailian | `BAILIAN_API_KEY` | `https://coding.dashscope.aliyuncs.com/v1` | 百炼 Coding Plan |
+| qwen | `DASHSCOPE_API_KEY` | `https://dashscope.aliyuncs.com/compatible-mode/v1` | 通义千问 |
+| volcengine | `VOLCENGINE_API_KEY` | `https://ark.cn-beijing.volces.com/api/v3` | 火山引擎 Doubao |
+| moonshot | `MOONSHOT_API_KEY` | `https://api.moonshot.ai/v1` | Moonshot Kimi |
+| deepseek | `DEEPSEEK_API_KEY` | `https://api.deepseek.com/v1` | DeepSeek |
+
+### 4.2 国际 Provider
+
+| Provider | 环境变量 | Base URL | 说明 |
+|----------|----------|----------|------|
+| openai | `OPENAI_API_KEY` | `https://api.openai.com/v1` | OpenAI GPT |
+| anthropic | `ANTHROPIC_API_KEY` | `https://api.anthropic.com` | Anthropic Claude |
+| gemini | `GEMINI_API_KEY` | `https://generativelanguage.googleapis.com` | Google Gemini |
+| groq | `GROQ_API_KEY` | `https://api.groq.com/openai/v1` | Groq |
+| mistral | `MISTRAL_API_KEY` | `https://api.mistral.ai/v1` | Mistral AI |
+| xai | `XAI_API_KEY` | `https://api.x.ai/v1` | xAI Grok |
+
+### 4.3 本地 Provider
+
+| Provider | 环境变量 | Base URL | 说明 |
+|----------|----------|----------|------|
+| ollama | - | `http://localhost:11434/v1` | Ollama 本地 |
+| vllm | - | `http://localhost:8000/v1` | vLLM 本地 |
+| lmstudio | - | `http://localhost:1234/v1` | LM Studio 本地 |
+
+---
+
+## 5. 可用模型
+
+### 智谱 (Zhipu)
+
+| 模型 ID | 说明 | 适用场景 |
+|---------|------|----------|
+| glm-4-flash | 快速模型 | 日常对话、快速响应 |
+| glm-4-plus | 高级模型 | 复杂推理、深度分析 |
+| glm-4 | 标准模型 | 通用场景 |
+| glm-4-air | 轻量模型 | 简单任务 |
+
+### 百炼 (Bailian)
+
+| 模型 ID | 说明 | 适用场景 |
+|---------|------|----------|
+| qwen3.5-plus | 通用对话 | 日常对话 |
+| qwen3-coder-next | 编码专家 | 代码生成 |
+| glm-5-bailian | GLM-5 | 通用场景 |
+| minimax-m2.5-bailian | 支持视觉 | 多模态任务 |
+| kimi-k2.5-bailian | Kimi K2.5 | 长文本处理 |
+
+### 其他推荐模型
+
+| Provider | 模型 ID | 适用场景 |
+|----------|---------|----------|
+| gemini | gemini-2.5-flash | 开发任务 |
+| deepseek | deepseek-chat | 快速响应 |
+| groq | llama-3.1-70b | 开源模型 |
+
+---
+
+## 6. 快速切换 Provider
+
+### 方法 A: 修改 config.toml
+
+```toml
+# 切换到智谱
+[default_model]
+provider = "zhipu"
+model = "glm-4-flash"
+api_key_env = "ZHIPU_API_KEY"
+
+# 切换到百炼
+[default_model]
+provider = "bailian"
+model = "qwen3.5-plus"
+api_key_env = "BAILIAN_API_KEY"
+```
+
+**重要**: 修改后必须完全重启 OpenFang！
+
+### 方法 B: 创建不同配置的 Agent
+
+```bash
+# 创建使用智谱的 Agent
+curl -X POST http://127.0.0.1:50051/api/agents \
+  -H "Content-Type: application/json" \
+  -d '{"manifest_toml": "name = \"Zhipu Agent\"\nmodel_provider = \"zhipu\"\nmodel_name = \"glm-4-flash\""}'
+
+# 创建使用百炼的 Agent
+curl -X POST http://127.0.0.1:50051/api/agents \
+  -H "Content-Type: application/json" \
+  -d '{"manifest_toml": "name = \"Bailian Agent\"\nmodel_provider = \"bailian\"\nmodel_name = \"qwen3.5-plus\""}'
+```
+
+---
+
+## 7. 配置验证
+
+### 检查当前配置
+
+```bash
+# 检查 API 返回的配置
+curl -s http://127.0.0.1:50051/api/config
+
+# 检查状态
+curl -s http://127.0.0.1:50051/api/status | grep -E "default_provider|default_model"
+
+# 检查所有 Provider 状态
+curl -s http://127.0.0.1:50051/api/providers | grep -E "id|auth_status"
+```
+
+### 检查 Agent 配置
+
+```bash
+# 列出所有 Agent 及其 Provider
+curl -s http://127.0.0.1:50051/api/agents | grep -E "name|model_provider|ready"
+```
+
+### 测试聊天
+
+```bash
+# 测试 Agent 是否能正常响应
+curl -X POST "http://127.0.0.1:50051/api/agents/{agentId}/message" \
+  -H "Content-Type: application/json" \
+  -d '{"message":"Hello"}'
+```
+
+---
+
+## 8. 重要注意事项
+
+### 8.1 配置热重载限制
+
+**关键**: OpenFang 将配置持久化在 SQLite 数据库中，`config.toml` 只在启动时读取。
+
+- `/api/config/reload` **不会**更新已持久化的默认模型配置
+- 修改 `config.toml` 后必须**完全重启 OpenFang**
+
+```bash
+# 正确的重启方式
+curl -X POST http://127.0.0.1:50051/api/shutdown
+# 然后手动启动
+./openfang.exe start
+```
+
+### 8.2 Agent 创建时的 Provider
+
+如果创建 Agent 时没有指定 Provider，OpenFang 会使用数据库中存储的默认配置，而不是 `config.toml` 中的配置。
+
+### 8.3 API Key 验证
+
+确保 API Key 格式正确：
+- 智谱: `sk-sp-xxxxx` 或 `xxxxx.xxxxx.xxxxx`
+- 百炼: `sk-xxxxx`
+
+---
+
+## 9. 常见问题
+
+### Q: 修改 config.toml 后配置没有生效？
+
+**A**: 必须完全重启 OpenFang，热重载不会更新持久化配置。
+
+### Q: Agent 显示 ready: false？
+
+**A**: 检查 Agent 使用的 Provider 是否配置了 API Key：
+```bash
+curl -s http://127.0.0.1:50051/api/agents | grep -E "auth_status|ready"
+```
+
+### Q: 如何查看所有可用的 Provider？
+
+**A**:
+```bash
+curl -s http://127.0.0.1:50051/api/providers
+```
+
+### Q: 如何在不重启的情况下切换 Agent？
+
+**A**: 前端可以通过选择不同 Provider 的 Agent 来切换，无需重启。
+
+---
+
+## 更新历史
+
+| 日期 | 变更 |
+|------|------|
+| 2026-03-17 | 初始版本，记录配置热重载限制 |
--- a/docs/knowledge-base/troubleshooting.md
+++ b/docs/knowledge-base/troubleshooting.md
@@ -97,7 +97,92 @@ echo "GEMINI_API_KEY=your_key" >> ~/.openfang/.env
 |-------|--------|------|
 | General Assistant | zhipu | 通常已配置 |

-### 2.2 流式响应不显示
+### 2.1.1 配置热重载限制（重要）
+
+**症状**: 修改 `config.toml` 后，`/api/config` 和 `/api/status` 仍然返回旧配置
+
+**根本原因**: OpenFang 将配置持久化在 SQLite 数据库中，`config.toml` 只在启动时读取
+
+**验证问题**:
+```bash
+# 检查 config.toml 内容
+cat ~/.openfang/config.toml
+# 输出: provider = "zhipu"
+
+# 检查 API 返回的配置
+curl -s http://127.0.0.1:50051/api/config
+# 输出: {"default_model":{"provider":"bailian",...}}  # 不一致！
+```
+
+**解决方案**:
+1. **必须完全重启 OpenFang**（热重载 `/api/config/reload` 不会更新持久化配置）
+```bash
+# 方法 1: 通过 API 关闭（然后手动重启）
+curl -X POST http://127.0.0.1:50051/api/shutdown
+
+# 方法 2: 使用 CLI
+./openfang.exe stop
+./openfang.exe start
+```
+
+2. **验证配置已生效**:
+```bash
+curl -s http://127.0.0.1:50051/api/status | grep -E "default_provider|default_model"
+# 应输出: "default_provider":"zhipu"
+```
+
+**配置文件位置**:
+| 文件 | 用途 |
+|------|------|
+| `~/.openfang/config.toml` | 主配置（启动时读取） |
+| `~/.openfang/.env` | API Key 环境变量 |
+| `~/.openfang/secrets.env` | 敏感信息 |
+| `~/.openfang/data/openfang.db` | SQLite 数据库（持久化配置） |
+
+**支持的 Provider**:
+| Provider | 环境变量 | 模型示例 |
+|----------|----------|----------|
+| zhipu | `ZHIPU_API_KEY` | glm-4-flash, GLM-4-Plus |
+| bailian | `BAILIAN_API_KEY` | qwen3.5-plus, qwen3-coder-next |
+| gemini | `GEMINI_API_KEY` | gemini-2.5-flash |
+| deepseek | `DEEPSEEK_API_KEY` | deepseek-chat |
+| openai | `OPENAI_API_KEY` | gpt-4, gpt-3.5-turbo |
+
+### 2.2 Agent ID 获取失败导致无法对话
+
+**症状**: Gateway 显示已连接，但发送消息无响应或报错 "No agent available"
+
+**根本原因**: `fetchDefaultAgentId()` 使用错误的 API 端点
+
+**错误代码**:
+```typescript
+// ❌ 错误 - /api/status 不返回 agents 字段
+const status = await this.restGet('/api/status');
+if (status?.agents && status.agents.length > 0) { ... }
+```
+
+**修复代码**:
+```typescript
+// ✅ 正确 - 使用 /api/agents 端点
+const agents = await this.restGet<Array<{ id: string; name?: string; state?: string }>>('/api/agents');
+if (agents && agents.length > 0) {
+  const runningAgent = agents.find(a => a.state === 'Running');
+  this.defaultAgentId = (runningAgent || agents[0]).id;
+}
+```
+
+**历史背景**: 这个问题与 OpenClaw 的握手认证问题类似，但根因不同：
+- OpenClaw: 需要 `cli/cli/operator` 身份 + Ed25519 配对
+- OpenFang: 不需要认证握手，但需要正确的 Agent UUID
+
+**验证修复**:
+```bash
+# 确认 /api/agents 返回数据
+curl http://127.0.0.1:50051/api/agents
+# 应返回: [{ "id": "uuid", "name": "...", "state": "Running" }]
+```
+
+### 2.3 流式响应不显示

 **症状**: 消息发送后无响应或响应不完整

@@ -165,7 +250,94 @@ const messages = store.messages;

 2. 检查 immer/persist 配置

-### 3.2 流式消息累积错误
+### 3.2 切换 Agent 后对话消失
+
+**症状**: 点击其他 Agent 后，之前的对话内容丢失
+
+**根本原因**: `setCurrentAgent` 切换 Agent 时清空了 `messages`，但没有恢复该 Agent 之前的对话
+
+**解决方案**:
+
+修改 `chatStore.ts` 中的 `setCurrentAgent` 函数：
+```typescript
+setCurrentAgent: (agent) =>
+  set((state) => {
+    if (state.currentAgent?.id === agent.id) {
+      return { currentAgent: agent };
+    }
+
+    // Save current conversation before switching
+    const conversations = upsertActiveConversation([...state.conversations], state);
+
+    // Try to find existing conversation for this agent
+    const agentConversation = conversations.find(c => c.agentId === agent.id);
+
+    if (agentConversation) {
+      // Restore the agent's previous conversation
+      return {
+        conversations,
+        currentAgent: agent,
+        messages: [...agentConversation.messages],
+        sessionKey: agentConversation.sessionKey,
+        currentConversationId: agentConversation.id,
+      };
+    }
+
+    // No existing conversation, start fresh
+    return {
+      conversations,
+      currentAgent: agent,
+      messages: [],
+      sessionKey: null,
+      currentConversationId: null,
+    };
+  }),
+```
+
+修改 `partialize` 配置以保存 `currentAgentId`：
+```typescript
+partialize: (state) => ({
+  conversations: state.conversations,
+  currentModel: state.currentModel,
+  currentAgentId: state.currentAgent?.id,  // 添加此行
+  currentConversationId: state.currentConversationId,
+}),
+```
+
+添加 `onRehydrateStorage` 钩子恢复消息：
+```typescript
+onRehydrateStorage: () => (state) => {
+  // Rehydrate Date objects from JSON strings
+  if (state?.conversations) {
+    for (const conv of state.conversations) {
+      conv.createdAt = new Date(conv.createdAt);
+      conv.updatedAt = new Date(conv.updatedAt);
+      for (const msg of conv.messages) {
+        msg.timestamp = new Date(msg.timestamp);
+        msg.streaming = false;
+      }
+    }
+  }
+
+  // Restore messages from current conversation if exists
+  if (state?.currentConversationId && state.conversations) {
+    const currentConv = state.conversations.find(c => c.id === state.currentConversationId);
+    if (currentConv) {
+      state.messages = [...currentConv.messages];
+      state.sessionKey = currentConv.sessionKey;
+    }
+  }
+},
+```
+
+**验证修复**:
+1. 与 Agent A 对话
+2. 切换到 Agent B
+3. 切换回 Agent A → 对话应恢复
+
+**文件**: `desktop/src/store/chatStore.ts`
+
+### 3.3 流式消息累积错误

 **症状**: 流式内容显示不正确或重复

@@ -269,8 +441,125 @@ curl -s http://127.0.0.1:50051/api/hands | jq '.[] | {id, name, requirements_met

 ---

+## 7. 新用户引导 (Onboarding)
+
+### 7.1 首次使用引导流程
+
+**需求**: 当用户第一次使用系统时，引导用户设置默认助手的人格信息（about me、you in my eye 等）。
+
+**实现方案**:
+
+1. **检测首次使用** - 使用 `useOnboarding` hook 检查 localStorage:
+   ```typescript
+   // desktop/src/lib/use-onboarding.ts
+   const ONBOARDING_COMPLETED_KEY = 'zclaw-onboarding-completed';
+   const USER_PROFILE_KEY = 'zclaw-user-profile';
+
+   export function useOnboarding(): OnboardingState {
+     // 检查 localStorage 是否有完成记录
+     // 返回 { isNeeded, isLoading, markCompleted, resetOnboarding }
+   }
+   ```
+
+2. **引导向导** - 使用 `AgentOnboardingWizard` 组件:
+   ```typescript
+   // App.tsx 中的集成
+   if (showOnboarding) {
+     return (
+       <AgentOnboardingWizard
+         isOpen={true}
+         onClose={() => {
+           markCompleted({ userName: 'User', userRole: 'user' });
+           setShowOnboarding(false);
+         }}
+         onSuccess={(clone) => {
+           markCompleted({
+             userName: clone.userName || 'User',
+             userRole: clone.userRole,
+           });
+           setCurrentAgent({
+             id: clone.id,
+             name: clone.name,
+             icon: clone.emoji || '🦞',
+             // ...
+           });
+           setShowOnboarding(false);
+         }}
+       />
+     );
+   }
+   ```
+
+3. **数据持久化** - 用户信息存储在 localStorage:
+   ```typescript
+   interface UserProfile {
+     userName: string;
+     userRole?: string;
+     completedAt: string;
+   }
+   ```
+
+**文件位置**:
+| 文件 | 用途 |
+|------|------|
+| `desktop/src/lib/use-onboarding.ts` | 引导状态管理 hook |
+| `desktop/src/components/AgentOnboardingWizard.tsx` | 5 步引导向导组件 |
+| `desktop/src/App.tsx` | 引导流程集成 |
+
+**引导步骤**:
+1. 认识用户 - 收集用户名称和角色
+2. Agent 身份 - 设置助手名称、昵称、emoji
+3. 人格风格 - 选择沟通风格
+4. 使用场景 - 选择应用场景
+5. 工作环境 - 配置工作目录
+
+### 7.2 Onboarding 创建 Agent 失败
+
+**症状**: 首次使用引导完成后，点击"完成"按钮报错，Agent 创建失败
+
+**根本原因**: Onboarding 应该**更新现有的默认 Agent**，而不是创建新的 Agent
+
+**错误代码**:
+```typescript
+// ❌ 错误 - 总是尝试创建新 Agent
+const clone = await createClone(createOptions);
+```
+
+**修复代码**:
+```typescript
+// ✅ 正确 - 如果存在现有 Agent 则更新
+let clone: Clone | undefined;
+
+if (clones && clones.length > 0) {
+  // 更新现有的默认 Agent
+  clone = await updateClone(clones[0].id, personalityUpdates);
+} else {
+  // 没有现有 Agent 才创建新的
+  clone = await createClone(createOptions);
+}
+```
+
+**文件**: `desktop/src/components/AgentOnboardingWizard.tsx`
+
+**验证修复**:
+1. 清除 localStorage 中的 onboarding 标记
+2. 重新启动应用
+3. 完成引导流程 → 应该成功更新默认 Agent
+
+---
+
+## 8. 相关文档
+
+- [OpenFang 配置指南](./openfang-configuration.md) - 配置文件位置、格式和最佳实践
+- [Agent 和 LLM 提供商配置](./agent-provider-config.md) - Agent 管理和 Provider 配置
+- [OpenFang WebSocket 协议](./openfang-websocket-protocol.md) - WebSocket 通信协议
+
+---
+
 ## 更新历史

 | 日期 | 变更 |
 |------|------|
+| 2026-03-17 | 添加首次使用引导流程 |
+| 2026-03-17 | 添加配置热重载限制问题 |
 | 2026-03-14 | 初始版本 |