task-list.md

CodexSwitch 任务列表

文档状态：草案 v0.1

本任务列表基于当前 requirement.md 与 design.md 生成，目的是给首版实现提供一个清晰的执行顺序。等你下一轮修改需求文档后，这份任务列表应该重新生成一次。

0. 文档阶段

• 根据你的反馈继续修订 requirement.md
• 基于最终版需求回刷 design.md
• 基于最终版需求回刷 task-list.md

1. 项目初始化

• 使用 Wails 创建 Vue 3 + TypeScript 项目骨架
• 接入 Vuetify 3
• 接入 Pinia
• 约定前后端目录结构与命名规范
• 建立统一的错误提示与消息通知机制

交付标准：

• 应用可以本地启动
• 前端与 Go 后端可以正常互调

2. 设置与路径管理

• 实现默认 codexHomePath 推导
• 实现 settings.json 读写
• 实现设置弹窗
• 支持修改目标 Codex 配置目录并持久化
• 路径修改后自动触发重扫

交付标准：

• 重启应用后仍能记住上次设置的路径
• 更改路径后列表和激活状态会刷新

3. 后端基础能力

• 实现应用配置目录初始化
• 实现托管配置目录扫描
• 实现文件安全写入工具
• 实现 contentHash 计算
• 实现统一日志与错误包装

交付标准：

• 可以稳定读写托管仓库
• 文件操作失败时能返回明确错误

4. auth.json 与 config.toml 解析

• 实现 auth.json 最小结构体
• 实现账号类型识别规则
• 实现官方 auth.json 标准化
• 实现 CLI 扁平 JSON 转标准官方 auth.json
• 实现 CLI 敏感字段缺失校验
• 实现官方 JWT 元数据解析
• 实现 API Key 元数据提取
• 实现 config.toml 关键字段解析
• 实现 profile_id 生成规则

交付标准：

• 能正确识别 conf/codex 和 conf/api
• 能生成稳定的配置身份标识

5. 当前配置扫描与自动同步

• 实现当前目标目录扫描
• 让当前目录扫描兼容 CLI 扁平 auth.json
• 实现启动自动导入逻辑
• 实现启动自动更新逻辑
• 实现激活配置识别
• 实现异常配置状态标记

交付标准：

• 启动后可自动识别当前配置
• 当前配置未托管时会自动导入
• 当前配置已托管但有变化时会自动更新

6. 托管配置仓库

• 定义 meta.json 结构
• 实现新增托管配置
• 实现更新托管配置
• 实现读取单个托管配置
• 实现读取全部托管配置
• 实现删除托管配置

交付标准：

• 托管配置目录结构固定且可重建
• 配置列表可以稳定加载

7. 导入当前配置

• 实现“导入当前配置”后端接口
• 支持同身份配置更新而不是重复创建
• 导入后刷新列表

交付标准：

• 用户可以手工导入当前配置
• 重复导入不会产生重复记录

8. 导入官方账号文件

• 实现官方账号文件选择与导入后端接口
• 支持标准官方 auth.json 导入
• 支持 CLI 扁平 JSON 导入并标准化保存
• 固定使用官方 config.toml 模板生成托管配置
• 支持同身份配置更新而不是重复创建
• 导入成功后刷新列表但不自动切换
• 接入前端工具栏按钮与提示

交付标准：

• 用户可以通过文件选择框导入官方账号文件
• CLI 样例导入后仓库中保存的是标准官方 auth.json
• 重复导入不会产生重复记录

9. API 配置新增与编辑

• 将 conf/api 样例整理为内置模板
• 实现新增 API 配置表单
• 实现 API 配置模板渲染
• 实现 API 配置保存
• 实现 API 配置编辑
• 实现 API Key 掩码展示

交付标准：

• 用户可以新增 API 配置
• 用户可以编辑已有 API 配置
• 列表中不会泄露完整 API Key

10. 配置切换

• 实现切换前当前配置保护逻辑
• 实现切换前自动导入/自动更新
• 实现目标配置写入目标目录
• 实现切换后的重扫与状态刷新
• 实现重复切换同一配置的 no-op 优化

交付标准：

• 能在官方配置和 API 配置之间切换
• 切换后激活状态正确刷新

11. 配置删除

• 实现删除确认弹窗
• 实现删除后端接口
• 限制删除激活中的配置
• 删除后刷新列表

交付标准：

• 非激活配置可删除
• 激活配置删除会被拦截并提示

12. 官方额度信息

• 梳理 codext 中额度接口与数据结构
• 实现官方配置额度拉取服务
• 实现额度拉取状态缓存
• 实现手动刷新额度
• 实现 ChatGPT host 到 /backend-api 的归一化
• 将额度结果映射到列表展示
• 处理额度获取失败和过期状态

交付标准：

• 官方配置能显示主额度和次额度
• 获取失败不影响其他功能

13. 前端主界面

• 实现顶部工具栏
• 在工具栏接入“导入账号文件”
• 实现托管配置表格
• 实现激活配置高亮
• 实现加载中、空状态、异常状态
• 实现新增、编辑、切换、删除交互
• 实现设置弹窗

交付标准：

• 主界面可以完整完成核心操作闭环
• 官方与 API 两类配置都能正确显示

14. 测试与验证

• 为类型识别、官方标准化、模板生成、哈希生成编写单元测试
• 为导入、更新、切换编写集成测试
• 用 conf/codex 和 conf/api 做样例验证
• 用 CLI 样例文件做导入与启动扫描验证
• 做一次切换失败场景验证
• 做一次路径变更重扫验证

交付标准：

• MVP 主流程覆盖到位
• 关键异常路径至少有基本回归测试

15. 打包与发布准备

• 配置 Wails 打包脚本
• 生成 Windows 构建产物
• 生成 macOS 构建产物
• 生成 Linux 构建产物
• 补充运行说明和已知限制

交付标准：

• 三个平台至少具备基础构建能力
• 已知限制对用户可见

16. 建议实现顺序

建议按下面顺序推进：

1. 项目初始化
2. 设置与路径管理
3. auth.json / config.toml 解析
4. 当前配置扫描与自动同步
5. 托管配置仓库
6. 导入当前配置
7. 导入官方账号文件
8. API 配置新增与编辑
9. 配置切换
10. 配置删除
11. 前端主界面
12. 官方额度信息
13. 测试与打包

17. MVP 定义

满足以下条件即可视为 MVP 完成：

• 能识别官方配置与 API 配置
• 能兼容 CLI 扁平官方 auth 输入
• 能自动导入当前配置
• 能手动导入官方账号文件
• 能新增和编辑 API 配置
• 能在多个托管配置之间切换
• 能高亮显示当前激活配置
• 能修改目标 Codex 配置目录
• 主流程异常不会导致应用崩溃

18. 第二阶段候选项

• 扩展更多 config.toml 字段编辑
• 支持更完整的官方额度刷新与 Token 刷新
• 支持 keyring 或环境变量模式的兼容提示
• 增加搜索、排序、筛选
• 增加导出/备份能力