5f542715cb
- Replace "Task Center" with "Models" in sidebar and routing - Add new models configuration page with AI provider account management - Implement token usage history with filtering, grouping, and visualization - Create provider store with Pinia for state management - Add internationalization support for models feature - Include development analysis documentation for feature implementation
84 lines
6.7 KiB
Markdown
84 lines
6.7 KiB
Markdown
# 模型配置 (Models) 功能分析报告与开发计划
|
||
|
||
本报告基于 `ClawX` 项目中 `/src/pages/Models` 及相关依赖的源码分析，为在 `zn-ai` (Vue 3 + Element Plus) 项目中实现一致且完整的模型配置功能提供分析报告与落地计划。
|
||
|
||
## 一、 功能实现分析报告
|
||
|
||
### 1. 核心功能模块划分
|
||
模型配置功能在逻辑上主要分为两大模块：
|
||
* **提供商与账号管理 (Providers Settings)**
|
||
* **配置列表**: 展示支持的 AI 模型提供商（如 OpenAI, Anthropic, Ollama, 硅基流动, 字节 Ark 等），并标识配置状态。
|
||
* **鉴权与网络配置**: 支持填写 API Key、Base URL，处理不同提供商的特定配置（如特定的请求头、API Protocol 等）。
|
||
* **高可用配置**: 允许为某个账号配置**备用模型 (Fallback Models)** 和 **备用账号 (Fallback Accounts)**，以在请求失败时重试。
|
||
* **账号级管理**: 支持同一提供商的多个账号管理（通过 `ProviderAccount` 模型），并支持设置默认提供商。
|
||
* **Token 用量历史 (Usage History)**
|
||
* **数据获取与轮询**: 从后端获取最近的 Token 消耗历史，支持通过定时器（15s）自动轮询和失焦/聚焦刷新。
|
||
* **统计与聚合图表**: 根据时间窗口（7天、30天、全部）过滤数据，支持按“模型 (Model)”或“日期 (Day)”聚合统计输入、输出及缓存 Token 数量。
|
||
* **明细列表与调试**: 分页展示每次对话的消耗明细（模型、来源、Token 数量、状态、预估费用）。在开发者模式下，可查看请求的原始 Content。
|
||
|
||
### 2. 技术栈与架构差异（ClawX vs zn-ai）
|
||
由于两个项目底层 UI 框架不同，迁移时需要进行范式转换：
|
||
| 维度 | ClawX (源项目) | zn-ai (目标项目) | 迁移策略 |
|
||
| :--- | :--- | :--- | :--- |
|
||
| **视图框架** | React 18 | Vue 3 (Composition API) | 将 React Hooks (`useEffect`, `useReducer`) 转换为 Vue 的 `ref`, `reactive`, `watch`, `computed`。 |
|
||
| **组件库** | shadcn/ui + lucide-react | Element Plus + @remixicon/vue | 将原生的 Tailwind 结构适配为 `el-form`, `el-table`, `el-dialog` 等组件，图标全量替换。 |
|
||
| **状态管理** | Zustand (`useProviderStore`) | Pinia | 重写 `src/stores/providers.ts` 为 Pinia Store 格式，保留 `init`, `refresh`, `create` 等核心 Action。 |
|
||
| **API 交互** | `hostApiFetch` (REST over IPC) | Axios / 封装的 IPC 请求 | 保持 Payload 结构一致，对接 `zn-ai` 主进程对应的路由。 |
|
||
|
||
### 3. 核心数据结构 (需无损迁移)
|
||
* **`ProviderAccount`**: 核心实体，包含 `id`, `vendorId`, `authMode`, `baseUrl`, `model`, `fallbackModels`, `fallbackAccountIds` 等。
|
||
* **`ProviderTypeInfo` / `PROVIDER_TYPE_INFO`**: 静态元数据，定义各个提供商的默认图标、占位符、文档链接、是否需要 API Key 等。
|
||
* **`UsageHistoryEntry`**: 用量记录，包含 `inputTokens`, `outputTokens`, `cacheReadTokens`, `usageStatus` 等。
|
||
|
||
---
|
||
|
||
## 二、 功能开发计划
|
||
|
||
为确保模型配置功能在 `zn-ai` 中**代码无缺失、功能高度一致**，制定以下四个阶段的开发计划：
|
||
|
||
### 阶段一：底层核心逻辑与状态层迁移 (预计 1-2 天)
|
||
**目标**：完成类型定义、静态配置和状态管理的 Vue 适配。
|
||
1. **移植基础配置与类型**：
|
||
* 在 `zn-ai/src/lib/providers.ts` 中，完整迁移 `ProviderType`, `ProviderConfig`, `ProviderAccount`, `PROVIDER_TYPE_INFO` 等静态元数据定义。
|
||
* 在 `zn-ai/src/lib/provider-accounts.ts` 中，迁移相关辅助函数（如 `buildProviderAccountId`, `hasConfiguredCredentials` 等）。
|
||
2. **创建 Pinia 状态管理**：
|
||
* 新建 `zn-ai/src/store/providers.ts`。
|
||
* 将 Zustand 逻辑重写为 Pinia，实现对 `/api/providers`, `/api/provider-accounts` 的增删改查方法，确保状态同步逻辑一致。
|
||
3. **移植用量统计核心算法**：
|
||
* 完整迁移 `ClawX/src/pages/Models/usage-history.ts`，包括 `groupUsageHistory`, `filterUsageHistoryByWindow`, `resolveStableUsageHistory` 等纯纯函数，确保数据处理逻辑 100% 一致。
|
||
|
||
### 阶段二：配置管理视图重构 (预计 2 天)
|
||
**目标**：实现“AI 提供商配置”交互界面。
|
||
1. **开发 ProviderSettings 组件**：
|
||
* 新建 `zn-ai/src/pages/models/components/ProvidersSettings.vue`。
|
||
* 使用 `Element Plus` 还原 ClawX 的卡片式配置列表和展开面板。
|
||
* 实现复杂的表单逻辑：API Key 的掩码与更新、Base URL 覆盖、默认模型设置、Fallback 备用链路的选择交互。
|
||
2. **API Key 连通性测试**：
|
||
* 实现“验证 Key”按钮交互，调用后端的 `validateApiKey` 服务，根据返回结果给出 `ElMessage` 成功/失败提示。
|
||
|
||
### 阶段三：Token 用量历史与主页面组装 (预计 1-2 天)
|
||
**目标**：实现 Token 用量大盘及主页面。
|
||
1. **实现用量统计图表组件 (UsageBarChart)**：
|
||
* 新建 Vue 组件，使用 Tailwind CSS 的 Flex 布局精确还原 ClawX 的自定义多色进度条图表（输入/输出/缓存 Token 比例展示）。
|
||
2. **开发 Models 主页面**：
|
||
* 新建 `zn-ai/src/pages/models/index.vue`。
|
||
* 引入 `ProvidersSettings.vue`。
|
||
* 实现下半部分的用量记录（Usage History）展示：
|
||
* 集成基于时间（7天/30天/全部）和聚合方式（模型/日期）的筛选器。
|
||
* 实现 `fetchUsageHistoryWithRetry` 带重试机制和自动轮询（15s/窗口聚焦）的数据拉取逻辑。
|
||
* 实现列表分页和各项 Token 详细消耗展示。
|
||
3. **开发者模式弹窗**：
|
||
* 实现点击用量记录查看请求详情（Content）的 `el-dialog`。
|
||
|
||
### 阶段四：国际化、联调与收尾 (预计 1 天)
|
||
**目标**：多语言支持与端到端可用性保障。
|
||
1. **多语言词条补全**：
|
||
* 提取上述页面中的硬编码中文，写入 `zn-ai/src/i18n/locales/{zh,en,ja}/models.json`。
|
||
* 使用 `useI18n()` 进行全量替换，确保一致性。
|
||
2. **主进程接口对齐联调**：
|
||
* 验证 Electron 主进程是否已完全实现 `/api/provider-accounts`, `/api/providers`, `/api/usage/recent-token-history` 路由，并保证响应结构一致。若有差异，需在前后端通信层进行抹平。
|
||
3. **UI 细节走查**：
|
||
* 测试亮色/暗色模式下的颜色变量兼容性（如 `border-black/10 dark:border-white/10` 转换为合适的 Tailwind/Element 变量）。
|
||
|
||
---
|
||
**备注**：此计划遵循了从数据驱动到 UI 呈现的构建原则，由于源项目高度依赖于状态的订阅分发，强烈建议在实施阶段严格按照【阶段一】优先完成 Pinia Store，再推进后续 UI 开发，以杜绝代码缺失或状态不一致的问题。 |