# ZCLAW 多端全链路调试提示词

> 基于 wiki 知识库 `g:\ZClaw_openfang\wiki\` 系统分析制定
> 用于新会话中系统性排查 ZCLAW 多端联调问题

---

## 系统架构概要

ZCLAW 是多层架构的 AI Agent 桌面客户端：

```
┌─────────────────────────────────────────────────────────────┐
│  前端层: React 19 + TypeScript + Zustand                    │
│  ├── 97 个 React 组件 (desktop/src/components/)            │
│  ├── 17 个 Zustand Store + 4 个 chat 子 store             │
│  └── 81 个 lib 文件 (desktop/src/lib/)                     │
├─────────────────────────────────────────────────────────────┤
│  桌面层: Tauri 2.x                                          │
│  ├── 189 个 Tauri 命令定义 / 182 个注册                     │
│  └── 3 种 ChatStream: KernelClient / SaaSRelay / Gateway   │
├─────────────────────────────────────────────────────────────┤
│  Rust 后端: 10 crates + src-tauri                          │
│  ├── ~95K 行 Rust 代码 (335 个 .rs 文件)                    │
│  └── 14 层中间件链 (middleware/butler_router.rs 等)        │
├─────────────────────────────────────────────────────────────┤
│  SaaS 平台: PostgreSQL + axum                              │
│  ├── 137 个 API 路由 (18 处 .merge() 汇聚)                │
│  └── 8 个后台 Worker (Token Pool / 计费 / 用量等)          │
└─────────────────────────────────────────────────────────────┘
```

---

## 核心数据流

### 客户端路由决策树

入口: `desktop/src/store/connectionStore.ts:349` → `connect(url?, token?)`

```
connect()
  │
  ├── [1] Admin 强制路由: localStorage llm_routing
  │     ├── "relay" → 强制 SaaS Relay 模式
  │     └── "local" → 强制本地 Kernel (adminForceLocal=true)
  │
  ├── [2] SaaS Relay 模式: localStorage('zclaw-connection-mode') === 'saas'
  │     ├── Tauri: KernelClient + baseUrl = saasUrl/api/v1/relay
  │     │         apiKey = SaaS JWT (不是 LLM Key!)
  │     ├── Browser: SaaSRelayGatewayClient (SSE)
  │     └── SaaS 不可达 → 降级到本地 Kernel
  │
  ├── [3] 本地 Kernel: isTauriRuntime() === true
  │     KernelClient + 用户自定义模型配置
  │
  └── [4] External Gateway (fallback)
        GatewayClient via WebSocket/REST
```

### 完整消息流 (Tauri SaaS Relay 主路径)

```
UI: ChatArea.tsx
    │
    ▼
streamStore.sendMessage(content)
    │
    ▼
kernelClient.chatStream()
    │
    ├── Tauri invoke('kernel_chat', ...)
    │    │
    │    ▼
    │  Kernel::boot()
    │    │
    │    ▼
    │  loop_runner → 14 层中间件链
    │    │
    │    ├── @80  ButlerRouter (TF-IDF 75 技能路由) ✅
    │    ├── @90  DataMasking (敏感数据脱敏)
    │    ├── @100 Compaction (对话压缩, 条件注册: threshold>0)
    │    ├── @150 Memory (记忆提取)
    │    ├── @180 Title (会话标题)
    │    ├── @200 SkillIndex (技能索引注入, 条件注册: entries非空)
    │    ├── @300 DanglingTool
    │    ├── @350 ToolError
    │    ├── @360 ToolOutputGuard
    │    ├── @400 Guardrail (安全规则)
    │    ├── @500 LoopGuard (防无限循环)
    │    ├── @550 SubagentLimit
    │    ├── @650 TrajectoryRecorder (✅ V13-GAP-01 已修复)
    │    └── @700 TokenCalibration
    │    │
    │    ▼
    │  LLM Driver (OpenAI compatible)
    │    │
    │    ▼
    │  POST {baseUrl}/chat/completions
    │  Bearer {SaaS JWT}
    │  model: {modelToUse}
    │    │
    │    ▼
    │  SaaS Relay Handler
    │  cache.resolve_model(model_name) ── 三级解析:
    │    1. 精确 model_id 匹配
    │    2. alias 字段匹配
    │    3. 前缀匹配 (e.g. "glm-4-flash" → "glm-4-flash-250414")
    │    │
    │    ▼
    │  Token Pool 轮换
    │  (priority → last_used → RPM/TPM 滑动窗口)
    │    │
    │    ▼
    │  真实 LLM API
    │    │
    │    ▼
    │  SSE 流式响应
    │    │
    ▼    ▼
Tauri Event emit('chat-response-delta', ...)
    │
    ├── onDelta(text)    → streamStore 追加
    ├── onThinkingDelta  → 显示思考过程
    ├── onTool(tool)    → toolStore 更新
    ├── onHand(hand)    → handStore 更新
    └── onComplete()    → conversationStore 持久化
```

---

## V13 已知断链清单（2026-04-14 验证更新）

> 验证时间: 2026-04-14 | 6 项中 5 项已修复，1 项已标注待清理

| ID | 优先级 | 状态 | 问题 | 验证位置 |
|----|--------|------|------|----------|
| **V13-GAP-01** | P1 | ✅ 已修复 | TrajectoryRecorderMiddleware @650 已注册到 `create_middleware_chain()` | `crates/zclaw-kernel/src/kernel/mod.rs:356-361` |
| **V13-GAP-02** | P1 | ✅ 已修复 | industryStore 已被 `ButlerPanel/index.tsx` 导入消费 | `desktop/src/components/ButlerPanel/index.tsx:4` |
| **V13-GAP-03** | P1 | ✅ 已修复 | Knowledge Search API 已接入: saas-knowledge.ts → saas-client.ts → VikingPanel.tsx | `desktop/src/components/VikingPanel.tsx:105` |
| **V13-GAP-04** | P2 | ⚠️ 标注 | Webhook 迁移文件已标 DEPRECATED，Rust 零消费，待物理删除 | `crates/zclaw-saas/migrations/20260403000002_webhooks.sql` |
| **V13-GAP-05** | P2 | ✅ 已修复 | Structured Data Source 有完整 Admin-v2 消费链: service → Knowledge.tsx → StructuredSourcesPanel | `admin-v2/src/services/knowledge.ts:67-207` |
| **V13-GAP-06** | P2 | ✅ 已修复 | PersistentMemoryStore struct 已移除，仅保留 API 响应类型 | `desktop/src-tauri/src/memory/persistent.rs` |

---

## 调试入口和关键文件

### 前端层

| 文件 | 职责 | 调试要点 |
|------|------|----------|
| `desktop/src/store/connectionStore.ts` | 路由决策核心 | `connect()` 方法, `getClient()` |
| `desktop/src/store/chat/streamStore.ts` | 流式消息编排 | `sendMessage()`, `chatStream()` 回调 |
| `desktop/src/store/chat/conversationStore.ts` | 会话管理 | `currentModel` 持久化 |
| `desktop/src/lib/kernel-chat.ts` | Kernel ChatStream (Tauri) | Tauri invoke 调用 |
| `desktop/src/lib/saas-relay-client.ts` | SaaS Relay ChatStream | SSE 连接 |
| `desktop/src/lib/gateway-client.ts` | Gateway ChatStream (WS) | WebSocket 连接 |
| `desktop/src/components/ButlerPanel.tsx` | 管家面板 | industryStore 已导入 ✅ (V13-GAP-02 已修复) |

### Tauri 命令层

| 文件 | 命令数 | 调试要点 |
|------|--------|----------|
| `desktop/src-tauri/src/lib.rs` | 189 定义 / 182 注册 | `kernel_chat`, `kernel_init` 等 |
| `desktop/src-tauri/src/kernel_commands/` | Hand/MCP/Skill | 8+4+? 命令 |
| `desktop/src-tauri/src/memory_commands.rs` | 13 个 | memory CRUD |

### Rust 中间件层

| 文件 | 中间件数 | 调试要点 |
|------|----------|----------|
| `crates/zclaw-runtime/src/middleware.rs` | AgentMiddleware trait | 4 个 hook 点 |
| `crates/zclaw-runtime/src/middleware/` | 14 个中间件实现 | TrajectoryRecorder @650 ✅ |
| `crates/zclaw-kernel/src/kernel/mod.rs:206-371` | `create_middleware_chain()` | V13-GAP-01 已修复 ✅ |

### SaaS 后端层

| 文件 | 路由数 | 调试要点 |
|------|--------|----------|
| `crates/zclaw-saas/src/main.rs` | 137 个 .route() | 18 个 .merge() 注册 |
| `crates/zclaw-saas/src/relay/handlers.rs` | 聊天中转 | `cache.resolve_model()` 三级解析 |
| `crates/zclaw-saas/src/workers/` | 8 个 Worker | Token Pool / 用量记录 |

---

## 系统性调试步骤

### 第一阶段：问题定位

**步骤 1：确定症状层级**

问题出现在哪一层？
- [ ] **前端 UI 层** — 组件渲染、用户交互异常
- [ ] **前端 Store 层** — 状态管理、数据流异常
- [ ] **Tauri 命令层** — invoke 调用失败或返回错误
- [ ] **Rust 中间件层** — 中间件链执行异常
- [ ] **LLM Driver 层** — 模型调用失败
- [ ] **SaaS Relay 层** — Token Pool / 模型匹配问题
- [ ] **SaaS 后端层** — API 路由 / 数据库问题

**步骤 2：缩小范围**

根据症状判断问题来源：

| 症状 | 怀疑层级 | 优先检查 |
|------|----------|----------|
| 模型 400 错误 | SaaS Relay | `cache.resolve_model()` 三级解析是否匹配到 model_id |
| 中间件未生效 | Rust 中间件层 | TrajectoryRecorder @650 已注册 ✅ |
| 行业配置不显示 | 前端 Store 层 | industryStore 已被 ButlerPanel 导入 ✅ |
| 流式响应中断 | Tauri 命令层 | kernel-chat.ts:76 超时守护 |
| Token Pool 耗尽 | SaaS 后端 | Workers 是否正常调度 |
| JWT 失效 | SaaS 认证 | password_version 是否匹配 |
| 记忆提取失败 | Rust Memory 层 | `MemoryExtractor` 是否正常工作 |
| Skill 未匹配 | 语义路由 | `SemanticSkillRouter` TF-IDF 计算 |

### 第二阶段：分层验证

**步骤 3：前端层验证**

```bash
# TypeScript 类型检查
cd desktop && pnpm tsc --noEmit

# 运行单元测试
cd desktop && pnpm vitest run

# 检查 Store 状态 (在 DevTools Console)
# streamStore.getState()
# conversationStore.getState()
# connectionStore.getState()

# 检查组件是否正确导入
grep -r "industryStore" desktop/src/components/
grep -r "saas-knowledge" desktop/src/
```

**步骤 4：Tauri 命令层验证**

```bash
# 列出所有注册的 Tauri 命令
grep "#[tauri::command]" desktop/src-tauri/src/ -r

# 验证 kernel 命令
grep "kernel_chat\|kernel_init" desktop/src-tauri/src/ -r

# 验证中间件注册
grep -A3 "TrajectoryRecorder" crates/zclaw-kernel/src/kernel/mod.rs
```

**步骤 5：Rust 中间件链验证**

```bash
# 验证 14 层中间件注册顺序
grep "chain.register" crates/zclaw-kernel/src/kernel/mod.rs

# 验证 ButlerRouter 语义路由
grep -r "SemanticSkillRouter\|TF-IDF" crates/zclaw-runtime/src/middleware/

# 验证 Memory 中间件
grep -r "Memory" crates/zclaw-runtime/src/middleware/
```

**步骤 6：SaaS Relay 验证**

```bash
# 验证路由注册
grep "\.route(" crates/zclaw-saas/src/main.rs

# 验证模型缓存匹配
grep "cache.get_model\|model_id" crates/zclaw-saas/src/relay/ -r

# 验证 Token Pool 轮换逻辑
grep -r "priority\|last_used\|cooldown" crates/zclaw-saas/src/relay/
```

### 第三阶段：完整链路检查

**步骤 7：按检查点逐步验证**

```
[检查点 1] streamStore.sendMessage()
    └── 验证: sessionKey, agentId, chatMode 是否正确传递
    └── 代码: desktop/src/store/chat/streamStore.ts

[检查点 2] KernelClient.chatStream()
    └── 验证: Tauri invoke 调用是否发出, 参数是否正确
    └── 代码: desktop/src/lib/kernel-chat.ts

[检查点 3] Kernel::boot()
    └── 验证: config.model, config.baseUrl, config.apiKey
    └── 代码: desktop/src-tauri/src/kernel/mod.rs

[检查点 4] Middleware Chain (14 层)
    └── 验证: 每层 middleware.before_completion() 是否按优先级执行
    └── 重点: TrajectoryRecorder @650 已注册 ✅ (V13-GAP-01 已修复)
    └── 代码: crates/zclaw-kernel/src/kernel/mod.rs:create_middleware_chain()

[检查点 5] LLM Driver
    └── 验证: 请求是否发往正确 baseUrl, Authorization header 是否正确
    └── 代码: crates/zclaw-runtime/src/driver/

[检查点 6] SaaS Relay Handler
    └── 验证: model_id 是否被 resolve_model() 三级解析命中, Token Pool 是否可用
    └── 代码: crates/zclaw-saas/src/relay/handlers.rs

[检查点 7] Token Pool 轮换
    └── 验证: RPM/TPM 是否在阈值内, cooldown 状态
    └── 代码: crates/zclaw-saas/src/relay/cache.rs

[检查点 8] SSE 流式响应
    └── 验证: Tauri Event 是否正确 emit, onDelta 回调是否触发
    └── 代码: desktop/src/lib/kernel-chat.ts

[检查点 9] Store 状态更新
    └── 验证: conversationStore 持久化, messageStore 更新
    └── 代码: desktop/src/store/chat/
```

---

## 根因分类与修复策略

### 协议问题

| 问题 | 原因 | 修复策略 |
|------|------|----------|
| 模型 400 | model_id 不在 SaaS 模型缓存中（三级解析均未命中） | 检查模型是否已在 Admin 启用，或 model_id 拼写 |
| JWT 失效 | password_version 不匹配 | 重新登录，或检查 JWT 刷新逻辑 |
| 流式中断 | 5 分钟超时守护触发 | 检查 kernel-chat.ts:76 超时配置 |

### 状态问题

| 问题 | 原因 | 修复策略 |
|------|------|----------|
| Store 不同步 | 多个 Store 实例 | 检查 store/index.ts 的 initializeStores() |
| 模型切换失败 | currentModel 未持久化 | 检查 conversationStore 的 persist 配置 |
| 行业配置不显示 | industryStore 导入 ✅ 已修复 | 如仍有问题检查 API 连接和 Store 初始化 |

### 中间件问题

| 问题 | 原因 | 修复策略 |
|------|------|----------|
| TrajectoryRecorder 未记录轨迹 | 数据库连接或 Store 初始化问题 | 检查 TrajectoryStore::new(pool) 连接 (V13-GAP-01 已修复) |
| Memory 提取失败 | MiddlewareContext 未正确传递 | 检查 middleware/memory.rs 的 before_completion |
| Skill 未匹配 | SemanticSkillRouter TF-IDF 计算异常 | 检查 crates/zclaw-skills/src/semantic_router.rs |

### 配置问题

| 问题 | 原因 | 修复策略 |
|------|------|----------|
| baseUrl 错误 | SaaS URL 未配置或硬编码错误 | 检查 config.toml 和环境变量 |
| API Key 错误 | SaaS JWT vs LLM Key 混淆 | 确认 kernelClient 使用 SaaS JWT |

---

## 执行命令参考

```bash
# 1. 前端验证
cd desktop && pnpm tsc --noEmit
cd desktop && pnpm vitest run

# 2. Rust 验证
cargo check --workspace --exclude zclaw-saas
cargo test --workspace --exclude zclaw-saas

# 3. SaaS 集成测试 (需要 PostgreSQL)
export TEST_DATABASE_URL="postgresql://postgres:123123@localhost:5432/zclaw"
cargo test -p zclaw-saas -- --test-threads=1

# 4. 检查中间件注册
grep -n "TrajectoryRecorder" crates/zclaw-kernel/src/kernel/mod.rs
grep -n "chain.register" crates/zclaw-kernel/src/kernel/mod.rs

# 5. 检查 V13 断链修复
grep -n "V13-GAP" crates/zclaw-kernel/src/kernel/mod.rs

# 6. 检查 industryStore 导入
grep -rn "industryStore" desktop/src/components/
```

---

## 调试记录模板

发现问题时，按以下格式记录：

```markdown
## [日期] [问题描述]

**症状**: [用户可见的问题表现]
**怀疑层级**: [前端/Tauri/Rust中间件/LLM/SaaS Relay/SaaS后端]
**怀疑位置**: [具体文件和行号]

**验证步骤**:
1. [x] [检查项]
2. [x] [检查项]
3. [ ] [检查项]

**根因**: [确定后填写]
**修复方案**: [确定后填写]
**影响范围**: [涉及的模块]
```

---

> 提示词版本: 2026-04-14-v2 (代码验证更新)
> 基于: wiki/index.md, wiki/routing.md, wiki/chat.md, wiki/middleware.md,
>      wiki/memory.md, wiki/hands-skills.md, wiki/saas.md, wiki/known-issues.md