3.0 KiB
3.0 KiB
实例自定义图标实施计划
目标
在设置页提供实例级图标选择能力，并让侧栏、浏览器页签等现有品牌图标消费点统一使用该图标。自定义图片与选择结果必须存放在 Git 管理之外，拉取/升级源码后仍保留。
验收边界
- 支持从本机选择常见栅格图上传，立即预览并保存。
- 支持恢复项目默认图标。
- 限制图片类型与大小，错误可理解且不破坏旧配置。
- 未配置时保持现有图标和行为，不引入升级迁移负担。
- 图标响应具备缓存更新机制；设置保存后当前页面可感知更新。
- 自定义文件和实例配置不进入 Git，不被
git pull覆盖。
阶段
| 步骤 | 状态 | 验收方式 |
|---|---|---|
| 1. 定位现有图标、设置和持久化链路 | DONE | 形成前后端入口、测试与数据目录清单 |
| 2. 明确实例级图标存储与兼容方案 | DONE | 记录接口、校验、缓存和升级兼容决策 |
| 3. 补充服务端配置、上传和图标响应回归测试 | DONE | 新测试先覆盖默认、上传、恢复、非法输入和持久化 |
| 4. 实现服务端实例图标持久化与接口 | DONE | 服务端测试通过，数据落在 Git 外置目录 |
| 5. 实现设置页图标选择、预览、恢复默认及全局应用 | DONE | 设置页可操作，现有图标消费点统一更新 |
| 6. 运行前后端测试与构建并修正问题 | DONE | 目标测试、完整相关测试和构建通过 |
| 7. 重新生成 CentOS 7 单文件发布包 | DONE | baseline Bun 构建成功，生成可执行文件与 tar.gz |
| 8. 验证发布包与工作区完整性 | DONE | 语法检查、MCP initialize 冒烟、归档读取和 diff 检查通过 |
| 9. 暂存并提交当前全部修改 | DONE | 按用户要求包含此前已暂存和本次全部修改 |
| 10. 推送到远端并核验结果 | DONE | 交付阶段推送 main 至 origin/main 并确认同步状态 |
设计原则
- 优先复用既有设置 API、数据目录与前端设置面板模式。
- 上传内容仅接受可安全解码/展示的图片类型，不允许用户控制落盘路径。
- 使用稳定的运行时 URL 暴露图标，并通过版本参数或响应缓存头避免旧图标残留。
- 不修改无关的用户工作区变更。
错误记录
| 错误 | 尝试 | 处理 |
|---|---|---|
项目内不存在 .codex/skills/todo-list-csv/scripts/todo_csv.py |
1 | 改用技能实际安装路径 /home/hdzx/.codex/skills/todo-list-csv/scripts/todo_csv.py |
| 并行调用 codebase-memory 架构与两项检索时连接被关闭 | 1 | 停止并行压测；等待只读代理完成 MCP 检索后，用 rg 做行号交叉验证 |
| Trellis 实现代理长时间运行但未产生产品改动或状态回报 | 1 | 中断代理，主线程按已固化的 TDD 契约接手实现 |
服务端已有预置 MAX_INSTANCE_ICON_SIZE，首次实现重复声明导致语法错误，测试等待端口超时 |
1 | 定位并复用既有常量，先单独语法检查，再重跑聚焦测试 |