416399e7a8
feat: add provider API service for managing provider accounts and keys feat: create provider runtime sync service for agent runtime management feat: introduce script execution service for running automation scripts feat: develop script store service for managing script metadata and storage feat: implement theme service for managing application theme settings feat: add updater service for handling application updates feat: create window service for managing application windows and their states
751 lines
30 KiB
Markdown
751 lines
30 KiB
Markdown
# zn-ai 对话功能重构迁移规划（对齐 ClawX 网关架构）
|
||
|
||
> 目标：彻底抛弃 zn-ai 现有的「WebSocket 直连云端后端」对话模型对接方式，全面对齐 ClawX 的「本地 Gateway Service」架构，使对话调用链路完全由本地网关接管。
|
||
|
||
---
|
||
|
||
## 一、问题诊断与架构差异
|
||
|
||
### 1.1 当前现象
|
||
- Agents 页面成功添加 DeepSeek 自定义模型；
|
||
- 对话页面提问「你是什么模型？」；
|
||
- 返回内容自称「阿里百炼千问」。
|
||
|
||
### 1.2 根因分析
|
||
**zn-ai 对话系统与模型管理完全割裂：**
|
||
|
||
| 维度 | Agents 模型管理 | 对话功能 (Chat) |
|
||
|------|----------------|-----------------|
|
||
| **存储位置** | 本地 JSON (`provider-accounts.json` + `provider-keys.json`) | 无本地模型概念 |
|
||
| **调用链路** | `hostapi:fetch` -> `providerApiService` | WebSocket -> `wss://onefeel.brother7.cn` |
|
||
| **模型决策** | 前端本地维护账户列表 | 远端后端根据固定 `agentId` 决定 |
|
||
| **鉴权方式** | 用户填写的 API Key | 后端统一配置的千问密钥 |
|
||
|
||
**结论**：对话消息从未读取本地 provider 配置，而是直接发给 zn-ai 云端后端；该后端绑定的默认模型就是阿里百炼千问。
|
||
|
||
### 1.3 与 ClawX 的核心架构差异
|
||
|
||
**ClawX 架构：**
|
||
```
|
||
Renderer Chat Store
|
||
│ invokeIpc('gateway:rpc', 'chat.send', { sessionKey, message, ... })
|
||
▼
|
||
Electron Main: GatewayManager
|
||
│ 管理 OpenClaw 子进程生命周期 + WebSocket JSON-RPC 连接
|
||
▼
|
||
Gateway Process (OpenClaw)
|
||
│ 读取 openclaw.json 的 provider 配置
|
||
│ 负责真正的 LLM HTTP 请求、流式响应、工具调用、会话历史
|
||
▼
|
||
调用实际 LLM API -> 流式返回 chunk -> GatewayManager -> Renderer
|
||
```
|
||
|
||
**zn-ai 当前架构：**
|
||
```
|
||
Renderer Chat Store
|
||
│ WebSocketManager.sendMessage() -> 云端后端
|
||
▼
|
||
zn-ai Cloud Backend (wss://onefeel.brother7.cn)
|
||
│ 固定使用阿里百炼千问
|
||
▼
|
||
返回响应
|
||
```
|
||
|
||
**关键差异：**
|
||
- ClawX 有**本地 Gateway 子进程**，zn-ai 没有；
|
||
- ClawX Chat Store **只与 Gateway 通信**（`gateway:rpc`），zn-ai Chat Store 直接与云端 WebSocket 通信；
|
||
- ClawX 的模型切换/调用完全由 Gateway 内部决定，zn-ai 由远端后端硬编码决定。
|
||
|
||
---
|
||
|
||
## 二、重构总体目标
|
||
|
||
建立 zn-ai 的**轻量级本地 Gateway Service**，完全替代现有的云端 WebSocket 对话后端：
|
||
|
||
1. **Gateway 作为唯一对话入口**：Renderer Chat Store 仅通过 `gateway:rpc` IPC 与 Gateway 通信；
|
||
2. **本地 Provider 直连 LLM**：Gateway 读取 `provider-api-service` 的配置，直接调用 OpenAI/Anthropic 等 LLM API；
|
||
3. **流式响应本地处理**：Gateway 负责流式接收 chunk，并通过事件通道推回 Renderer；
|
||
4. **会话历史本地管理**：Gateway 维护会话历史，支持 `chat.history` 查询；
|
||
5. **Provider 变更自动 reload**：修改 provider 配置后，Gateway 自动热重载配置；
|
||
6. **未来可扩展 Tool Calling/Agent Loop**：所有复杂逻辑集中在 Gateway，Renderer 保持简单。
|
||
|
||
---
|
||
|
||
## 三、目标架构设计
|
||
|
||
### 3.1 整体数据流
|
||
|
||
```
|
||
┌─────────────────────────────────────────────────────────────────────────────┐
|
||
│ Renderer 进程 │
|
||
│ ┌──────────────┐ ┌──────────────┐ │
|
||
│ │ ChatBox.vue │◄──►│ chatStore │ │
|
||
│ └──────────────┘ └──────┬───────┘ │
|
||
│ │ │
|
||
│ invokeIpc('gateway:rpc', ...) │
|
||
└─────────────────────────────┼───────────────────────────────────────────────┘
|
||
│ IPC
|
||
┌─────────────────────────────┼───────────────────────────────────────────────┐
|
||
│ Electron Main │
|
||
│ ┌──────────────────────────┴────────────────────────────────────┐ │
|
||
│ │ GatewayManager (新建) │ │
|
||
│ │ ┌─────────────┐ ┌─────────────┐ ┌─────────────────────┐ │ │
|
||
│ │ │ Gateway RPC │ │ Provider │ │ Session Store │ │ │
|
||
│ │ │ Server │ │ Resolver │ │ (内存/本地持久化) │ │ │
|
||
│ │ └──────┬──────┘ └──────┬──────┘ └─────────────────────┘ │ │
|
||
│ │ │ │ │ │
|
||
│ │ └────────────────┘ │ │
|
||
│ │ │ │ │
|
||
│ │ ┌──────────▼──────────┐ │ │
|
||
│ │ │ ChatHandler │ │ │
|
||
│ │ │ (chat.send/history)│ │ │
|
||
│ │ └──────────┬──────────┘ │ │
|
||
│ │ │ │ │
|
||
│ │ ┌──────────▼──────────┐ │ │
|
||
│ │ │ Provider Factory │ │ │
|
||
│ │ │ (createProvider) │ │ │
|
||
│ │ └──────────┬──────────┘ │ │
|
||
│ │ │ │ │
|
||
│ │ ┌───────────────┼───────────────┐ │ │
|
||
│ │ ▼ ▼ ▼ │ │
|
||
│ │ OpenAIProvider AnthropicProvider OllamaProvider │ │
|
||
│ └─────────────────────────────────────────────────────────────────┘ │
|
||
│ │ │
|
||
│ ┌────────────────────┼────────────────────┐ │
|
||
│ ▼ ▼ ▼ │
|
||
│ provider-accounts.json provider-keys.json (可选) IndexedDB │
|
||
│ │
|
||
└──────────────────────────────────────────────────────────────────────────────┘
|
||
```
|
||
|
||
### 3.2 Gateway 接口契约（对齐 ClawX）
|
||
|
||
Renderer 通过 `gateway:rpc` IPC 调用 Gateway 方法：
|
||
|
||
```ts
|
||
// IPC 调用方式
|
||
window.api.invoke('gateway:rpc', method: string, params: any)
|
||
|
||
// 示例
|
||
invokeIpc('gateway:rpc', 'chat.send', {
|
||
sessionKey: 'agent:deepseek:xxx',
|
||
message: { role: 'user', content: '你好' },
|
||
options: { providerAccountId: 'deepseek-xxx' }
|
||
})
|
||
|
||
invokeIpc('gateway:rpc', 'chat.history', {
|
||
sessionKey: 'agent:deepseek:xxx',
|
||
limit: 50,
|
||
})
|
||
|
||
invokeIpc('gateway:rpc', 'chat.abort', {
|
||
sessionKey: 'agent:deepseek:xxx',
|
||
})
|
||
```
|
||
|
||
Gateway 向 Renderer 推送事件（通过 `ipcMain` -> `mainWindow.webContents.send`）：
|
||
|
||
```ts
|
||
// 事件名称对齐 ClawX
|
||
type GatewayEvent =
|
||
| { type: 'chat:delta'; sessionKey: string; runId: string; delta: string }
|
||
| { type: 'chat:final'; sessionKey: string; runId: string; message: ChatMessage }
|
||
| { type: 'chat:error'; sessionKey: string; runId: string; error: string }
|
||
| { type: 'chat:aborted'; sessionKey: string; runId: string }
|
||
| { type: 'gateway:status'; status: 'connected' | 'disconnected' | 'reconnecting' }
|
||
```
|
||
|
||
---
|
||
|
||
## 四、迁移开发规划
|
||
|
||
### Phase 1: 轻量级 Gateway Service 骨架（基础设施）
|
||
|
||
#### 4.1.1 新建 `electron/gateway/` 目录
|
||
文件清单：
|
||
- `electron/gateway/manager.ts` — GatewayManager 主类
|
||
- `electron/gateway/types.ts` — Gateway RPC 类型定义
|
||
- `electron/gateway/handlers/chat.ts` — Chat RPC 处理器
|
||
- `electron/gateway/handlers/provider.ts` — Provider 查询 RPC 处理器
|
||
- `electron/gateway/session-store.ts` — 会话历史内存存储
|
||
|
||
#### 4.1.2 `GatewayManager` 核心职责
|
||
```ts
|
||
class GatewayManager {
|
||
// 初始化时加载 provider 配置
|
||
async init(): Promise<void>
|
||
|
||
// RPC 入口，被 ipcMain.handle('gateway:rpc') 调用
|
||
async rpc(method: string, params: any): Promise<any>
|
||
|
||
// 向所有 renderer 窗口广播事件
|
||
broadcast(event: GatewayEvent): void
|
||
|
||
// 监听 provider 配置变化并热重载
|
||
reloadProviders(): void
|
||
}
|
||
```
|
||
|
||
**设计决策**：zn-ai 不需要像 ClawX 那样启动独立的 OpenClaw 子进程。Gateway 直接以**Electron Main 进程内的 Service 类**形式存在，避免进程间通信的复杂度，同时保持接口与 ClawX 完全一致。
|
||
|
||
#### 4.1.3 注册 `gateway:rpc` IPC Handler
|
||
在 `electron/main.ts` 中新增：
|
||
```ts
|
||
import { gatewayManager } from '@electron/gateway/manager';
|
||
|
||
app.whenReady().then(() => {
|
||
gatewayManager.init();
|
||
// ... existing code
|
||
});
|
||
|
||
ipcMain.handle('gateway:rpc', async (_event, method: string, params: any) => {
|
||
return gatewayManager.rpc(method, params);
|
||
});
|
||
|
||
// 转发 Gateway 事件到 Renderer
|
||
ipcMain.on('gateway:subscribe', (event) => {
|
||
// 可选：若需要按需订阅
|
||
});
|
||
```
|
||
|
||
---
|
||
|
||
### Phase 2: Provider 层改造（能力层）
|
||
|
||
#### 4.2.1 重构 `electron/providers/index.ts`
|
||
废弃旧的 `CONFIG_KEYS.PROVIDER` base64 解析逻辑，改为从 `providerApiService` 读取：
|
||
|
||
```ts
|
||
import { providerApiService } from '@electron/service/provider-api-service';
|
||
|
||
export function createProvider(accountId: string): BaseProvider {
|
||
const account = providerApiService.getAccounts().find(a => a.id === accountId);
|
||
if (!account) throw new Error(`Provider account ${accountId} not found`);
|
||
|
||
const apiKey = providerApiService.getApiKey(accountId).apiKey;
|
||
if (!apiKey) throw new Error(`API key for account ${accountId} not found`);
|
||
|
||
const baseURL = account.baseUrl || getProviderTypeInfo(account.vendorId)?.defaultBaseUrl;
|
||
if (!baseURL) throw new Error(`Base URL for account ${accountId} not found`);
|
||
|
||
switch (account.apiProtocol) {
|
||
case 'anthropic-messages':
|
||
// return new AnthropicProvider(apiKey, baseURL, account.headers);
|
||
throw new Error('Anthropic provider not yet implemented');
|
||
case 'openai-completions':
|
||
case 'openai-responses':
|
||
default:
|
||
return new OpenAIProvider(apiKey, baseURL, account.headers);
|
||
}
|
||
}
|
||
```
|
||
|
||
#### 4.2.2 扩展 `OpenAIProvider`
|
||
- 构造函数增加 `headers?: Record<string, string>` 参数；
|
||
- `chat()` 方法增加 `options?: { signal?: AbortSignal }` 支持；
|
||
- 在 `client` 初始化时透传自定义 headers（如 Ark 的额外认证头）。
|
||
|
||
#### 4.2.3 `BaseProvider` 接口统一
|
||
```ts
|
||
export abstract class BaseProvider {
|
||
abstract chat(
|
||
messages: ChatMessage[],
|
||
model: string,
|
||
options?: { signal?: AbortSignal }
|
||
): Promise<AsyncIterable<UniversalChunk>>;
|
||
}
|
||
```
|
||
|
||
---
|
||
|
||
### Phase 3: Gateway Chat 处理器实现（核心链路）
|
||
|
||
#### 4.3.1 `electron/gateway/handlers/chat.ts`
|
||
实现三个核心 RPC 方法：
|
||
|
||
**A. `chat.send`**
|
||
```ts
|
||
async function handleChatSend(params: {
|
||
sessionKey: string;
|
||
message: ChatMessage;
|
||
options?: { providerAccountId?: string };
|
||
}): Promise<{ runId: string }> {
|
||
const runId = crypto.randomUUID();
|
||
const session = sessionStore.getOrCreate(params.sessionKey);
|
||
|
||
// 1. 追加用户消息到会话历史
|
||
session.appendMessage(params.message);
|
||
|
||
// 2. 解析 Provider
|
||
const accountId = params.options?.providerAccountId || providerApiService.getDefault().accountId;
|
||
if (!accountId) throw new Error('No provider account selected');
|
||
|
||
const provider = createProvider(accountId);
|
||
const account = providerApiService.getAccounts().find(a => a.id === accountId)!;
|
||
|
||
// 3. 构建 messages 数组（历史 + 当前消息）
|
||
const messages = buildChatMessages(session.messages, account);
|
||
|
||
// 4. 启动流式调用
|
||
const abortController = new AbortController();
|
||
session.setActiveRun(runId, abortController);
|
||
|
||
// 5. 异步流式处理
|
||
processChatStream(session, runId, provider, account.model!, messages, abortController.signal);
|
||
|
||
return { runId };
|
||
}
|
||
```
|
||
|
||
**B. `chat.history`**
|
||
```ts
|
||
function handleChatHistory(params: { sessionKey: string; limit?: number }): ChatMessage[] {
|
||
const session = sessionStore.get(params.sessionKey);
|
||
return session?.getMessages(params.limit) ?? [];
|
||
}
|
||
```
|
||
|
||
**C. `chat.abort`**
|
||
```ts
|
||
function handleChatAbort(params: { sessionKey: string }): void {
|
||
const session = sessionStore.get(params.sessionKey);
|
||
if (session?.activeRun) {
|
||
session.activeRun.abortController.abort();
|
||
session.clearActiveRun();
|
||
gatewayManager.broadcast({
|
||
type: 'chat:aborted',
|
||
sessionKey: params.sessionKey,
|
||
runId: session.activeRun.runId,
|
||
});
|
||
}
|
||
}
|
||
```
|
||
|
||
#### 4.3.2 流式处理逻辑 `processChatStream`
|
||
```ts
|
||
async function processChatStream(
|
||
session: Session,
|
||
runId: string,
|
||
provider: BaseProvider,
|
||
model: string,
|
||
messages: ChatMessage[],
|
||
signal: AbortSignal
|
||
) {
|
||
let assistantContent = '';
|
||
|
||
try {
|
||
const chunks = await provider.chat(messages, model, { signal });
|
||
|
||
for await (const chunk of chunks) {
|
||
if (signal.aborted) break;
|
||
|
||
if (chunk.result) {
|
||
assistantContent += chunk.result;
|
||
gatewayManager.broadcast({
|
||
type: 'chat:delta',
|
||
sessionKey: session.key,
|
||
runId,
|
||
delta: chunk.result,
|
||
});
|
||
}
|
||
|
||
if (chunk.isEnd) {
|
||
break;
|
||
}
|
||
}
|
||
|
||
if (!signal.aborted) {
|
||
const finalMessage: ChatMessage = {
|
||
role: 'assistant',
|
||
content: assistantContent,
|
||
timestamp: Date.now(),
|
||
};
|
||
session.appendMessage(finalMessage);
|
||
session.clearActiveRun();
|
||
|
||
gatewayManager.broadcast({
|
||
type: 'chat:final',
|
||
sessionKey: session.key,
|
||
runId,
|
||
message: finalMessage,
|
||
});
|
||
}
|
||
} catch (error) {
|
||
session.clearActiveRun();
|
||
gatewayManager.broadcast({
|
||
type: 'chat:error',
|
||
sessionKey: session.key,
|
||
runId,
|
||
error: error instanceof Error ? error.message : String(error),
|
||
});
|
||
}
|
||
}
|
||
```
|
||
|
||
---
|
||
|
||
### Phase 4: Renderer Chat Store 重构（UI 层）
|
||
|
||
#### 4.4.1 新增 `src/lib/gateway-client.ts`
|
||
封装 `gateway:rpc` 调用，与 ClawX 的 `api-client.ts` 对齐：
|
||
|
||
```ts
|
||
export async function gatewayRpc<T>(method: string, params?: any): Promise<T> {
|
||
if (!window.api?.invoke) {
|
||
throw new Error('IPC not available');
|
||
}
|
||
return window.api.invoke('gateway:rpc', method, params);
|
||
}
|
||
|
||
export function onGatewayEvent(
|
||
callback: (event: GatewayEvent) => void
|
||
): () => void {
|
||
const handler = (_event: any, payload: GatewayEvent) => callback(payload);
|
||
window.api.on('gateway:event', handler);
|
||
return () => window.api.off('gateway:event', handler);
|
||
}
|
||
```
|
||
|
||
**注意**：需要在 `electron/preload/index.ts` 中暴露对应的 IPC 通道。
|
||
|
||
#### 4.4.2 重构 `src/store/chat.ts`
|
||
|
||
**废弃内容：**
|
||
- `WebSocketManager` 及其所有生命周期管理（`initConnection`, `_wsManager`, `_adaptWsMessage`）；
|
||
- 云端 WebSocket URL 和消息格式；
|
||
- 基于 HTTP API 的 `getSessionMessages` 历史加载（逐步替换为 `gateway:rpc chat.history`）。
|
||
|
||
**新增/改造内容：**
|
||
|
||
**A. 状态扩展**
|
||
```ts
|
||
interface ChatState {
|
||
// ... 现有状态保留
|
||
gatewayStatus: 'connected' | 'disconnected' | 'reconnecting';
|
||
}
|
||
```
|
||
|
||
**B. `sendMessage` 重构**
|
||
```ts
|
||
async sendMessage(text, attachments) {
|
||
const trimmed = text.trim();
|
||
if (!trimmed && (!attachments || attachments.length === 0)) return;
|
||
|
||
const providerStore = useProviderStore();
|
||
const defaultAccountId = providerStore.defaultAccountId;
|
||
if (!defaultAccountId) {
|
||
this.error = '请先前往模型管理页面配置并设置一个默认模型';
|
||
return;
|
||
}
|
||
|
||
// 确保有有效 sessionKey
|
||
const sessionKey = this.currentSessionKey;
|
||
if (!sessionKey || sessionKey === DEFAULT_SESSION_KEY) {
|
||
// 本地会话：使用本地生成的 key
|
||
const localKey = `local:${defaultAccountId}:${crypto.randomUUID()}`;
|
||
this.currentSessionKey = localKey;
|
||
this.sessions = ensureSessionEntry(this.sessions, { key: localKey, displayName: 'New Chat' });
|
||
}
|
||
|
||
// 乐观添加用户消息
|
||
const userMsg = buildUserMessage(trimmed, attachments);
|
||
this.messages = [...this.messages, userMsg];
|
||
this.sending = true;
|
||
this.error = null;
|
||
this.streamingText = '';
|
||
this.streamingMessage = null;
|
||
|
||
// 通过 Gateway 发送（复用 Gateway 返回的 runId）
|
||
try {
|
||
const { runId } = await gatewayRpc<{ runId: string }>('chat.send', {
|
||
sessionKey: this.currentSessionKey,
|
||
message: { role: 'user', content: trimmed },
|
||
options: {
|
||
providerAccountId: defaultAccountId,
|
||
},
|
||
});
|
||
this.activeRunId = runId;
|
||
} catch (err) {
|
||
this.error = String(err);
|
||
this.sending = false;
|
||
this.activeRunId = null;
|
||
}
|
||
}
|
||
```
|
||
|
||
**C. `handleChatEvent` 适配 Gateway 事件**
|
||
现有 `handleChatEvent` 的逻辑基本无需改动，只需调整事件来源：
|
||
- 在 chat store 初始化时订阅 `gateway:event`；
|
||
- 将 Gateway 推送的 `chat:delta` / `chat:final` / `chat:error` / `chat:aborted` 映射到现有状态机。
|
||
|
||
**D. `loadHistory` 重构**
|
||
```ts
|
||
async loadHistory(quiet = false) {
|
||
const { currentSessionKey } = this;
|
||
if (!currentSessionKey || currentSessionKey === DEFAULT_SESSION_KEY) {
|
||
this.messages = [];
|
||
return;
|
||
}
|
||
|
||
// 本地会话走 Gateway
|
||
if (currentSessionKey.startsWith('local:')) {
|
||
if (!quiet) this.loading = true;
|
||
try {
|
||
const messages = await gatewayRpc<RawMessage[]>('chat.history', {
|
||
sessionKey: currentSessionKey,
|
||
limit: 50,
|
||
});
|
||
this.messages = messages;
|
||
} catch (err) {
|
||
console.warn('Failed to load local history:', err);
|
||
} finally {
|
||
this.loading = false;
|
||
}
|
||
return;
|
||
}
|
||
|
||
// 遗留的云端会话暂时保留原有 HTTP API 加载逻辑（用于兼容）
|
||
// ... 现有 getSessionMessages 逻辑
|
||
}
|
||
```
|
||
|
||
**E. `abortRun` 重构**
|
||
```ts
|
||
async abortRun() {
|
||
clearHistoryPoll();
|
||
this.sending = false;
|
||
this.streamingText = '';
|
||
this.streamingMessage = null;
|
||
this.activeRunId = null;
|
||
|
||
try {
|
||
await gatewayRpc('chat.abort', {
|
||
sessionKey: this.currentSessionKey,
|
||
});
|
||
} catch (err) {
|
||
console.warn('Abort failed:', err);
|
||
}
|
||
}
|
||
```
|
||
|
||
#### 4.4.3 Preload 脚本扩展
|
||
在 `electron/preload/index.ts` 中确保暴露：
|
||
```ts
|
||
contextBridge.exposeInMainWorld('api', {
|
||
invoke: (channel: string, ...args: any[]) => ipcRenderer.invoke(channel, ...args),
|
||
on: (channel: string, callback: (...args: any[]) => void) => ipcRenderer.on(channel, callback),
|
||
off: (channel: string, callback: (...args: any[]) => void) => ipcRenderer.off(channel, callback),
|
||
// ... 现有方法
|
||
});
|
||
```
|
||
|
||
---
|
||
|
||
### Phase 5: Provider Store 与默认模型（UI 层）
|
||
|
||
#### 4.5.1 精简 `src/store/providers.ts`
|
||
- 移除 `selectedAccountId` 状态及相关 `localStorage` 持久化；
|
||
- 对话层不再维护独立的模型选中态，直接复用 `defaultAccountId`。
|
||
|
||
#### 4.5.2 Chat 页面移除模型选择器
|
||
- 从 `ChatBox.vue` 中移除 `ModelSelector` 组件及其引用；
|
||
- 对话功能直接使用 provider 管理中「设置为默认」的模型账户；
|
||
- 对话页面 `onMounted` 时主动调用 `providerStore.init()` 加载模型配置。
|
||
|
||
#### 4.5.3 自动默认模型兜底
|
||
当 `providerStore.init()` 初始化后发现用户已存在 provider accounts 但未设置 `defaultAccountId` 时，自动将第一个 account 设为默认，确保用户无需手动点击"设为默认"即可直接开始对话。若用户没有任何账户，则保持原有提示行为。
|
||
|
||
---
|
||
|
||
### Phase 6: 会话历史持久化（数据层）
|
||
|
||
#### 4.6.1 会话历史存储策略
|
||
当前 `session-store.ts` 使用内存存储。为支持应用重启后恢复，引入本地持久化：
|
||
|
||
**方案 A（推荐，MVP 阶段）**：
|
||
- Gateway 的 `sessionStore` 在进程退出时将数据写入 `userData/chat-sessions.json`；
|
||
- 启动时从该文件加载；
|
||
- 数据结构：`Record<sessionKey, { messages: ChatMessage[], updatedAt: number }>`。
|
||
|
||
**方案 B（进阶）**：
|
||
- 使用 `electron-store` 或 IndexedDB 存储；
|
||
- 支持按会话搜索、导出、删除。
|
||
|
||
#### 4.6.2 会话标识区分
|
||
- **本地 Gateway 会话**：`local:{providerAccountId}:{uuid}`；
|
||
- **云端遗留会话**：保持原有的 `agent:{agentId}:main` 或后端分配的 `session_id`。
|
||
|
||
#### 4.6.3 会话列表混合显示
|
||
- `loadSessions()` 中：
|
||
- 云端会话继续调用 `getSessionList`；
|
||
- 本地会话从 `sessionStore` 读取；
|
||
- 合并后按 `updatedAt` 排序显示。
|
||
- 短期可先只显示本地会话（如果决定完全废弃云端）。
|
||
|
||
---
|
||
|
||
### Phase 7: Provider 配置变更与 Gateway 热重载
|
||
|
||
#### 4.7.1 Provider 变更通知机制
|
||
在 `electron/service/provider-api-service.ts` 中引入订阅模式：
|
||
```ts
|
||
type ProviderChangeListener = () => void;
|
||
const listeners: ProviderChangeListener[] = [];
|
||
|
||
export function onProviderChange(listener: ProviderChangeListener): () => void {
|
||
listeners.push(listener);
|
||
return () => {
|
||
const idx = listeners.indexOf(listener);
|
||
if (idx > -1) listeners.splice(idx, 1);
|
||
};
|
||
}
|
||
|
||
function notifyChange() {
|
||
listeners.forEach(l => l());
|
||
}
|
||
```
|
||
|
||
在 `createAccount`, `updateAccount`, `deleteAccount`, `setDefault` 等写操作后调用 `notifyChange()`。
|
||
|
||
#### 4.7.2 Gateway 监听并重载
|
||
在 `GatewayManager.init()` 中：
|
||
```ts
|
||
onProviderChange(() => {
|
||
this.reloadProviders();
|
||
});
|
||
```
|
||
|
||
`reloadProviders()` 实现：
|
||
- 重新读取所有 provider 账户和 API keys；
|
||
- 对于**没有活跃 run** 的 provider，立即替换内存中的配置；
|
||
- 对于有活跃 run 的 provider，标记为「待更新」，在 run 结束后应用新配置。
|
||
|
||
---
|
||
|
||
### Phase 8: 多 Provider 适配矩阵（能力扩展）
|
||
|
||
| Vendor | 实现类 | 协议 | 优先级 |
|
||
|--------|--------|------|--------|
|
||
| OpenAI | `OpenAIProvider` | `openai` SDK | P0 |
|
||
| DeepSeek | `OpenAIProvider` | `openai` SDK | P0 |
|
||
| Moonshot | `OpenAIProvider` | `openai` SDK | P0 |
|
||
| SiliconFlow | `OpenAIProvider` | `openai` SDK | P0 |
|
||
| Ark (豆包) | `OpenAIProvider` | `openai` SDK + headers | P0 |
|
||
| 百度千帆 | `OpenAIProvider` | `openai` SDK | P1 |
|
||
| Ollama | `OpenAIProvider` | `openai` SDK | P1 |
|
||
| Anthropic | `AnthropicProvider` | `@anthropic-ai/sdk` | P2 |
|
||
| Google Gemini | `GeminiProvider` | `@google/generative-ai` | P2 |
|
||
|
||
所有 OpenAI-compatible 的厂商优先通过 `OpenAIProvider` + `baseURL` + `headers` 支持。
|
||
|
||
---
|
||
|
||
## 五、实施优先级与里程碑
|
||
|
||
### Milestone 1: Gateway 骨架 + 本地 Provider 可对话（2 周）
|
||
- [ ] Phase 1: 创建 `electron/gateway/` 目录与 `GatewayManager` 骨架
|
||
- [ ] Phase 2: 重构 `createProvider` 读取 `provider-api-service`
|
||
- [ ] Phase 3: 实现 `chat.send` / `chat.history` / `chat.abort` RPC 处理器
|
||
- [ ] Phase 4: 重构 `chatStore.sendMessage` 走 `gateway:rpc`
|
||
- [ ] Phase 5: 对话页面移除模型选择器，直接使用默认模型
|
||
- [ ] 验证：添加 DeepSeek 并设为默认 -> 对话返回 DeepSeek 模型内容
|
||
|
||
### Milestone 2: 历史持久化 + 体验优化（1 周）
|
||
- [ ] Phase 6: 实现 `chat-sessions.json` 本地持久化
|
||
- [ ] 支持会话列表混合显示（本地 + 云端遗留）
|
||
- [ ] 支持图片附件输入、Abort、重发
|
||
- [ ] API Key 失效、网络超时等错误友好提示
|
||
|
||
### Milestone 3: 完全废弃云端 WebSocket + 架构收尾（1-2 周）
|
||
- [ ] Phase 7: Provider 变更自动通知 Gateway 重载
|
||
- [ ] 彻底移除 `WebSocketManager` 及相关代码
|
||
- [ ] 废弃 `START_A_DIALOGUE` IPC（被 `gateway:rpc` 完全替代）
|
||
- [ ] 清理云端后端相关的历史兼容代码
|
||
- [ ] 引入 Anthropic/Gemini Provider 支持（可选）
|
||
|
||
---
|
||
|
||
## 五之一、Sub Agent 分工与数量估算
|
||
|
||
基于本次更新后的迁移规划，建议分配 **6 个 Sub Agent** 并行作业：
|
||
|
||
### 对话功能核心检查（4 个 Agent）
|
||
|
||
| Sub Agent | 负责领域 | 对应 Phase | 核心任务 |
|
||
|-----------|----------|------------|----------|
|
||
| **Agent 1** | Gateway 主进程 | Phase 1, 3, 6, 7 | 检查并修复 `GatewayManager` 骨架；验证 `chat.send` / `chat.history` / `chat.abort` 实现；会话持久化到 `chat-sessions.json`；Provider 变更热重载 |
|
||
| **Agent 2** | Provider 层 | Phase 2, 8 | 检查并修复 `createProvider` 本地配置读取；验证 `OpenAIProvider`（headers、AbortSignal、错误处理）；扩展 DeepSeek 等内置厂商 |
|
||
| **Agent 3** | Renderer Chat Store | Phase 4 | 检查并修复 `src/store/chat.ts`：废弃 WebSocket，接入 `gateway:rpc`；验证事件映射 `chat:delta/final/error/aborted`；维护流式状态机 |
|
||
| **Agent 4** | UI 与交互 | Phase 5 | 检查并修复 `ChatBox.vue` 中 `ModelSelector` 移除情况；验证对话直接使用 `defaultAccountId`；空状态、错误提示、附件输入等 UI 细节 |
|
||
|
||
### 集成与模型管理（2 个 Agent）
|
||
|
||
| Sub Agent | 负责领域 | 核心任务 |
|
||
|-----------|----------|----------|
|
||
| **Agent 5** | 对话功能集成 | 运行端到端类型检查与编译；验证 `gateway:rpc` → Provider → Renderer 的完整链路；确认流式响应、会话历史、Abort 等功能闭环 |
|
||
| **Agent 6** | 模型管理功能 | 检查并修复「设置为默认模型」功能；验证 `defaultAccountId` 在 Provider 管理页的正确设置与持久化；确保对话层能正确读取默认模型 |
|
||
|
||
**估算依据：**
|
||
- 前 4 个 Agent 分别对应「主进程网关 → Provider 能力 → 渲染层状态 → 前端 UI」四层架构，边界清晰、耦合最小。
|
||
- Agent 5 作为独立集成 Agent，专门负责跨层契约验证（`gateway:rpc` / `gateway:event` / `createProvider()`）和端到端测试，不与其他 4 个 Agent 的职责重叠。
|
||
- Agent 6 单独负责模型管理模块的「设置默认模型」功能，这是对话层能正确调用默认 Provider 的前置依赖。
|
||
- 6 个 Agent 并行可最大化效率：Agent 1-4 检查各自层的实现，Agent 5 等待 1-4 完成后做集成验证，Agent 6 可与 1-4 并行检查模型管理页面。
|
||
|
||
## 六、风险与应对
|
||
|
||
| 风险 | 影响 | 应对策略 |
|
||
|------|------|----------|
|
||
| **云端后端有其他业务逻辑**（如 Agent 工具链、RAG） | 完全废弃云端后这些能力丢失 | 短期保留云端会话的只读访问；长期将这些能力迁移到本地 Gateway 中实现 |
|
||
| **图片/文件输入格式差异** | 不同厂商 vision API 格式不同 | Gateway 内部统一转换为 OpenAI vision 格式再发送 |
|
||
| **会话历史分裂** | 本地和云端会话无法统一管理 | 本地会话使用 `local:` 前缀区分；会话列表合并显示 |
|
||
| **AbortController 兼容性** | 旧 Electron 版本可能不支持 | Electron 40 基于 Chromium 124，完全支持 `AbortController` |
|
||
| **Gateway 阻塞主进程** | 大量并发流式响应可能阻塞 Electron Main | Gateway 使用异步迭代器，不会阻塞事件循环；必要时将来可拆分为 Worker 线程 |
|
||
|
||
---
|
||
|
||
## 七、关键文件变更清单
|
||
|
||
### 新建文件
|
||
- `electron/gateway/manager.ts`
|
||
- `electron/gateway/types.ts`
|
||
- `electron/gateway/handlers/chat.ts`
|
||
- `electron/gateway/handlers/provider.ts`
|
||
- `electron/gateway/session-store.ts`
|
||
- `src/lib/gateway-client.ts`
|
||
|
||
### 主进程修改
|
||
- `electron/main.ts` — 注册 `gateway:rpc` IPC，初始化 `GatewayManager`
|
||
- `electron/providers/index.ts` — 废弃旧配置读取，改为从 `providerApiService` 读取
|
||
- `electron/providers/OpenAIProvider.ts` — 扩展 headers、AbortSignal 支持
|
||
- `electron/service/provider-api-service.ts` — 增加变更通知机制
|
||
- `electron/wins/index.ts` — 废弃 `START_A_DIALOGUE` IPC Handler
|
||
- `electron/preload/index.ts` — 确保暴露 `gateway:event` 通道
|
||
|
||
### 渲染进程修改
|
||
- `src/store/chat.ts` — 全面重构：废弃 WebSocket，接入 `gateway:rpc`
|
||
- `src/store/providers.ts` — 移除 `selectedAccountId`，对话直接使用 `defaultAccountId`
|
||
- `src/pages/home/ChatBox.vue` — 移除模型选择器，简化输入区
|
||
|
||
### 待废弃文件
|
||
- `src/lib/WebSocketManager.ts`（Milestone 3 移除）
|
||
- `src/api/SessionsApi.ts` 中的部分云端接口（Milestone 3 评估后移除）
|
||
|
||
---
|
||
|
||
## 八、总结
|
||
|
||
**当前问题本质**：zn-ai 的对话系统绕过了本地模型管理，直接连接了一个使用固定模型的云端后端。
|
||
|
||
**对齐 ClawX 的核心路径**：
|
||
1. 在 Electron Main 进程内建立**轻量级 Gateway Service**；
|
||
2. 让 Gateway 成为 Renderer Chat Store 的**唯一对话入口**（`gateway:rpc`）；
|
||
3. Gateway 内部读取 `provider-api-service` 配置，**直接调用 LLM API**；
|
||
4. 流式响应通过 Gateway 事件通道推回 Renderer；
|
||
5. 对话页面**移除模型选择器**，直接使用 Provider 管理中「设置为默认」的模型；
|
||
6. 逐步废弃 WebSocket 云端后端和 `START_A_DIALOGUE` 旧 IPC。
|
||
|
||
**最终收益**：
|
||
- Renderer 代码大幅简化，与 ClawX 100% 对齐；
|
||
- 模型选择、LLM 调用、流式处理、会话历史全部本地化；
|
||
- 未来接入 Tool Calling、Agent Loop 可直接在 Gateway 中实现，无需改动 UI。
|