zn-ai/Models-Configuration-Analysis.md

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