feat(models): add models configuration page with provider management and token usage

- 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
This commit is contained in:
duanshuwen
2026-04-09 21:49:52 +08:00
parent 6d2991e595
commit 5f542715cb
18 changed files with 2040 additions and 25 deletions

View File

@@ -0,0 +1,84 @@
# 模型配置 (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 开发,以杜绝代码缺失或状态不一致的问题。