# ZCLAW 后端功能前端集成审查方案

## 背景

用户反馈在 Tauri 端没有看到一些已开发的功能。本方案旨在系统性地审查所有后端已实现的功能是否正确集成到前端 UI。

---

## 1. 审查发现总结

### 1.1 后端命令统计

| 模块 | 命令数量 | 前端集成状态 |
|------|---------|-------------|
| Kernel 核心 | 20 | ✅ 完整 |
| Pipeline 工作流 | 8 | ✅ 完整 |
| OpenFang/Gateway | 16 | ⚠️ 部分 |
| OpenViking CLI | 9 | ❌ 无 |
| OpenViking Server | 4 | ❌ 无 |
| Memory 记忆 | 10 | ✅ 完整 |
| Browser 自动化 | 20 | ✅ 完整 |
| Secure Storage | 4 | ❌ 无 |
| Heartbeat Engine | 9 | ✅ 完整 |
| Context Compactor | 4 | ✅ 完整 |
| Reflection Engine | 6 | ✅ 完整 |
| Identity Manager | 14 | ✅ 完整 |
| Adaptive Mesh | 8 | ⚠️ 部分 |
| **总计** | **135** | - |

### 1.2 已识别的集成缺口

#### 完全缺失前端入口

| 功能 | 后端实现位置 | 影响等级 |
|------|-------------|---------|
| **Channels 通道** | `crates/zclaw-channels/` | P1 - 用户无法配置 Discord/Slack/Telegram |
| **OpenViking CLI** | `viking_commands.rs` | P2 - 语义搜索功能不可用 |
| **Secure Storage** | `secure_storage.rs` | P2 - 密钥管理无 UI |
| **Memory Extraction** | `memory/extractor.rs` | P3 - 自动记忆提取未暴露 |
| **LLM Complete** | `llm/mod.rs` | P3 - 独立 LLM 调用无入口 |

#### 部分集成需完善

| 功能 | 当前状态 | 缺失部分 |
|------|---------|---------|
| **Triggers 触发器** | Store 存在，UI 不完整 | 编辑、测试触发器 UI |
| **Approvals 审批** | Store 存在，UI 不完整 | 批量操作、历史记录 |
| **Adaptive Mesh** | Store 存在，无专用 UI | 模式可视化、推荐展示 |
| **Persona Evolver** | Store 存在，无 UI | 人格演化展示 |

---

## 2. 详细审查清单

### 2.1 核心功能 (P0) - 必须可用

```markdown
聊天系统
- [ ] agent_chat - 发送消息
- [ ] agent_chat_stream - 流式响应
- [ ] 消息列表正常显示
- [ ] 多模型切换生效

Agent 管理
- [ ] agent_create - 创建分身
- [ ] agent_list - 列出分身
- [ ] agent_get - 获取详情
- [ ] agent_delete - 删除分身
- [ ] 分身配置持久化

技能系统
- [ ] skill_list - 技能列表
- [ ] skill_refresh - 刷新技能
- [ ] skill_execute - 执行技能
- [ ] 技能执行结果显示

Hands 系统
- [ ] hand_list - Hands 列表
- [ ] hand_execute - 执行 Hand
- [ ] Hand 参数配置
- [ ] 执行状态反馈
```

### 2.2 重要功能 (P1) - 影响体验

```markdown
Pipeline 工作流
- [ ] pipeline_list - 发现 Pipeline
- [ ] pipeline_run - 执行 Pipeline
- [ ] pipeline_progress - 进度显示
- [ ] pipeline_result - 结果展示
- [ ] pipeline_cancel - 取消执行

Memory 记忆
- [ ] memory_store - 存储记忆
- [ ] memory_search - 搜索记忆
- [ ] memory_stats - 统计信息
- [ ] 记忆在聊天中自动使用

Identity 身份
- [ ] identity_get - 获取身份
- [ ] identity_build_prompt - 构建提示
- [ ] identity_propose_change - 提案变更
- [ ] identity_approve/reject - 审批

Browser 自动化
- [ ] browser_create_session - 创建会话
- [ ] browser_navigate - 导航
- [ ] browser_click/type - 交互
- [ ] browser_screenshot - 截图
- [ ] browser_scrape_page - 抓取

Triggers 触发器
- [ ] trigger_list - 列表
- [ ] trigger_create - 创建
- [ ] trigger_update - 更新
- [ ] trigger_delete - 删除
- [ ] trigger_execute - 手动执行

Approvals 审批
- [ ] approval_list - 待审批列表
- [ ] approval_respond - 响应审批
```

### 2.3 缺失功能 (需新增 UI)

```markdown
Channels 通道管理 (新增)
- [ ] Discord 配置界面
- [ ] Slack 配置界面
- [ ] Telegram 配置界面
- [ ] 通道状态显示
- [ ] 消息桥接测试

OpenViking CLI (新增)
- [ ] viking_add - 添加资源
- [ ] viking_find - 语义搜索
- [ ] viking_grep - 模式搜索
- [ ] viking_ls/tree - 资源浏览

Secure Storage (新增)
- [ ] 密钥列表
- [ ] 添加/删除密钥
- [ ] 安全存储可用性检查

Adaptive Mesh (完善)
- [ ] 模式检测可视化
- [ ] 推荐展示面板
- [ ] 活动记录查看

Persona Evolver (完善)
- [ ] 人格演化历史
- [ ] 人格调整界面
```

---

## 3. 验证方法

### 3.1 代码层面验证

```bash
# 检查前端客户端是否调用所有后端命令
cd desktop/src/lib
grep -r "invoke(" *.ts | grep -oP "'[^']+'" | sort -u

# 对比后端暴露的命令
cd src-tauri/src
grep -r "#\[tauri::command\]" *.rs -A 5 | grep "pub async fn" | awk '{print $3}'
```

### 3.2 功能测试验证

```bash
# 启动开发环境
pnpm start:dev

# 检查清单
1. 打开每个面板，确认无报错
2. 测试每个按钮和交互
3. 检查浏览器控制台错误
4. 验证数据持久化
```

### 3.3 集成测试脚本

创建 `tests/integration/api-coverage.test.ts`:
- 自动扫描后端命令
- 检查前端是否有对应调用
- 生成覆盖率报告

---

## 4. 实施计划

### Phase 1: 完善现有功能 (优先级最高)

**目标**: 让已实现的后端功能在前端完全可用

| 任务 | 涉及文件 | 预估工时 |
|------|---------|---------|
| 完善 TriggersPanel | `TriggersPanel.tsx`, `CreateTriggerModal.tsx` | 4h |
| 完善 ApprovalsPanel | `ApprovalsPanel.tsx`, `ApprovalQueue.tsx` | 3h |
| 连接 Mesh 推荐 | `WorkflowRecommendations.tsx`, `meshStore.ts` | 4h |
| 完善 Persona Evolver | `personaStore.ts`, 新增 UI | 4h |

### Phase 2: 添加缺失的 UI 入口

**目标**: 为无 UI 的后端功能创建管理界面

| 任务 | 涉及文件 | 预估工时 |
|------|---------|---------|
| 创建 ChannelsPanel | 新增 `ChannelsPanel.tsx` | 6h |
| 创建 VikingPanel | 新增 `VikingPanel.tsx` | 5h |
| 创建 SecureStoragePanel | 新增 `SecureStoragePanel.tsx` | 3h |
| 集成到设置页面 | `Settings/` 目录 | 2h |

### Phase 3: 优化用户体验

| 任务 | 涉及文件 | 预估工时 |
|------|---------|---------|
| 添加功能引导 | `use-onboarding.ts` | 3h |
| 完善错误提示 | `ErrorNotification.tsx` | 2h |
| 添加操作审计 | `AuditLogsPanel.tsx` | 3h |
| 更新文档 | `docs/features/` | 2h |

---

## 5. 关键文件路径

### 后端命令注册
- `g:\ZClaw_openfang\desktop\src-tauri\src\lib.rs` - 命令汇总入口
- `g:\ZClaw_openfang\desktop\src-tauri\src\kernel_commands.rs` - 核心 API
- `g:\ZClaw_openfang\desktop\src-tauri\src\viking_commands.rs` - OpenViking CLI
- `g:\ZClaw_openfang\desktop\src-tauri\src\secure_storage.rs` - 安全存储

### 前端客户端层
- `g:\ZClaw_openfang\desktop\src\lib\kernel-client.ts` - Kernel 客户端
- `g:\ZClaw_openfang\desktop\src\lib\intelligence-client.ts` - Intelligence 客户端
- `g:\ZClaw_openfang\desktop\src\lib\browser-client.ts` - 浏览器客户端

### 前端状态管理
- `g:\ZClaw_openfang\desktop\src\store\handStore.ts` - Hands 状态
- `g:\ZClaw_openfang\desktop\src\store\meshStore.ts` - Mesh 状态
- `g:\ZClaw_openfang\desktop\src\store\personaStore.ts` - 人格状态

### 前端组件
- `g:\ZClaw_openfang\desktop\src\components\TriggersPanel.tsx`
- `g:\ZClaw_openfang\desktop\src\components\ApprovalsPanel.tsx`
- `g:\ZClaw_openfang\desktop\src\components\WorkflowRecommendations.tsx`

---

## 6. 预期成果

1. **完整的功能清单文档** - 列出所有后端功能及其前端集成状态
2. **可执行的检查清单** - 用于验证每个功能是否正常工作
3. **缺失功能 UI** - 为无 UI 的功能创建管理界面
4. **完善的现有功能** - 修复部分集成的功能
5. **更新的文档** - 反映当前系统的完整能力

---

## 7. 审查结果 - 功能集成覆盖率

### 7.1 完整集成的功能 ✅

| 功能模块 | 后端命令 | 前端客户端 | UI 组件 | Store |
|---------|---------|-----------|---------|-------|
| 聊天对话 | agent_chat, agent_chat_stream | kernel-client.ts | ChatArea.tsx | chatStore.ts |
| Agent 管理 | agent_* | kernel-client.ts | CloneManager.tsx | agentStore.ts |
| 技能系统 | skill_* | kernel-client.ts | SkillMarket.tsx | skillMarketStore.ts |
| Hands 系统 | hand_* | kernel-client.ts | HandsPanel.tsx | handStore.ts |
| Pipeline | pipeline_* | pipeline-client.ts | PipelinesPanel.tsx | workflowStore.ts |
| Browser | browser_* | browser-client.ts | BrowserHand/* | browserHandStore.ts |
| Memory | memory_* | intelligence-client.ts | MemoryPanel.tsx | - |
| Heartbeat | heartbeat_* | intelligence-client.ts | HeartbeatConfig.tsx | - |
| Compactor | compactor_* | intelligence-client.ts | (自动) | - |
| Reflection | reflection_* | intelligence-client.ts | ReflectionLog.tsx | - |
| Identity | identity_* | intelligence-client.ts | IdentityChangeProposal.tsx | - |
| Triggers | trigger_* | kernel-client.ts | TriggersPanel.tsx | handStore.ts |
| Approvals | approval_* | kernel-client.ts | ApprovalsPanel.tsx | handStore.ts |
| Mesh 推荐 | mesh_* | intelligence-client.ts | WorkflowRecommendations.tsx | meshStore.ts |

### 7.2 部分集成的功能 ⚠️

| 功能模块 | 问题 | 缺失部分 |
|---------|------|---------|
| **Persona Evolver** | 后端命令可能不存在 | `persona_evolve` 命令在 Tauri 未注册 |
| **Channels** | 只读展示，无配置入口 | 无法配置 Discord/Slack/Telegram |
| **Secure Storage** | 无专用 UI 入口 | 仅用于 API Key 存储，无管理界面 |
| **OpenFang 进程** | 无前端客户端 | openfang_process_* 命令无 UI |

### 7.3 完全缺失前端的功能 ❌ (已部分完成)

| 功能模块 | 后端实现 | 前端状态 |
|---------|---------|---------|
| **OpenViking CLI** | viking_* (9命令) | ✅ 已创建 [viking-client.ts](desktop/src/lib/viking-client.ts) 和 [VikingPanel.tsx](desktop/src/components/VikingPanel.tsx) |
| **OpenViking Server** | viking_server_* (4命令) | ✅ 已集成到 viking-client.ts |
| **Memory Extraction** | extract_session_memories | P3 - 无前端调用 |
| **LLM Complete** | llm_complete | P3 - 无专用入口 |

### 7.4 集成覆盖率统计

| 状态 | 模块数 | 百分比 |
|------|--------|--------|
| ✅ 完整集成 | 14 | 67% |
| ⚠️ 部分集成 | 4 | 19% |
| ❌ 无前端 | 4 | 14% |
| **总计** | 22 | 100% |

---

## 8. 优先修复建议

### P0 - ✅ 已完成

1. **Persona Evolver** - 在 [lib.rs](desktop/src-tauri/src/lib.rs) 添加状态初始化和命令注册
   - 緻加 7 个命令: `persona_evolver_init`, `persona_evolve`, `persona_evolution_history`, `persona_evolver_state`, `persona_evolver_config`, `persona_evolver_update_config`, `persona_apply_proposal`
   - 緻加状态管理: `.manage(persona_evolver_state)`

### P1 - ✅ 已完成

2. **Channels 配置 UI** - 完整重写 [IMChannels.tsx](desktop/src/components/Settings/IMChannels.tsx)
   - 添加 `ChannelConfigModal` 组件
   - 添加配置 Discord/Slack/Telegram/Feishu/QQ/WeChat
   - 更新 [configStore.ts](desktop/src/store/configStore.ts) 添加 `name`/`config` 字段

   - 集成到设置页面导航

3. **Secure Storage 管理** - 创建 [SecureStorage.tsx](desktop/src/components/Settings/SecureStorage.tsx)
   - OS Keyring/Keychain 管理界面
   - 查看/添加/删除/显示密钥值
   - 检测 Keyring 可用性
   - 集成到设置页面导航

### P2 - ✅ 已完成

4. **OpenViking UI** - 创建客户端和 UI 面板
   - 创建 [viking-client.ts](desktop/src/lib/viking-client.ts) - API 客户端
   - 创建 [VikingPanel.tsx](desktop/src/components/VikingPanel.tsx) - 语义搜索 UI
   - 服务器状态控制、 语义搜索功能
   - 集成到设置页面导航

---

## 9. 风险与注意事项

1. **Breaking Changes**: 修改现有 Store 可能影响其他组件
2. **测试覆盖**: 新增 UI 需要添加对应的测试
3. **向后兼容**: 保持现有 API 不变
4. **性能影响**: 新增功能不应影响核心聊天体验
5. **Persona Evolver**: 需要先确认后端命令是否已实现