灵伴桌面宠物 — 技术债务清理清单

日期: 2026-08-05
说明: 列出所有需要清理的一次性代码、架构优化建议、代码质量改进和依赖升级建议。

1. 一次性代码清理

1.1 config-store.js — Wallpaper Engine 硬编码

行号	内容	清理方案
L7	`const WALLPAPER_ENGINE = 'D:\\Games\\steam\\steamapps\\common\\wallpaper_engine\\wallpaper64.exe';`	删除。硬编码绝对路径，仅限开发者本机。
L9-51	`function wallpaperScript(wallpaperPath, shutdownAfterMinutes)`	删除整个函数。该函数为 Wallpaper Engine 定制，生成切换壁纸的 PowerShell 脚本。
L53-89	`function createDefaultTasks()`	重写。当前返回 3 个 Wallpaper Engine 模板任务（`wake-wallpaper`、`exercise-wallpaper`、`sleep-wallpaper`），全部指向硬编码的 workshop 路径。需替换为通用模板。

具体改动:

// 删除 L7
// 删除 L9-51 (wallpaperScript 函数)
// 重写 L53-89 (createDefaultTasks 函数)

// 新的 createDefaultTasks:
function createDefaultTasks() {
  return [
    {
      id: 'morning-wake',
      name: '晨间唤醒',
      description: '每天早上提醒你开启新的一天。',
      time: '07:00',
      enabled: false,
      script: [
        '$notification = New-Object -ComObject WScript.Shell',
        '$notification.Popup("早安！新的一天开始了~", 5, "灵伴桌面宠物", 64)',
      ].join('\r\n'),
      lastRunDate: null,
      lastRunAt: null,
      lastStatus: '从未运行'
    },
    // ... 更多通用模板
  ];
}

1.2 config-store.js — legacyTasksAdopted 设置

行号	内容	清理方案
L118	`legacyTasksAdopted: false`	删除。旧任务迁移系统移除后，该设置项不再需要。

1.3 main.js — adoptLegacyTasks 迁移系统

行号	内容	清理方案
L450-469	`async function adoptLegacyTasks()`	删除整个函数。该函数通过管理员权限禁用旧的 Windows 计划任务，并启用应用内 Wallpaper Engine 模板。v2.0 面向新用户，无需此迁移逻辑。
L538	`registerHandler('legacy:adopt', adoptLegacyTasks);`	删除。移除旧任务迁移的 IPC 通道注册。

1.4 preload.js — adoptLegacyTasks API

行号	内容	清理方案
L29	`adoptLegacyTasks: () => ipcRenderer.invoke('legacy:adopt'),`	删除。移除暴露给渲染进程的迁移 API。

1.5 manager.html — 迁移 UI 面板

行号	内容	清理方案
L56-61	`<section class="panel migration-card">` 整块	删除。移除”旧任务迁移”面板及其所有子元素。

1.6 manager.js — 迁移相关代码

行号	内容	清理方案
L15-16	`adoptLegacy: document.getElementById('adopt-legacy'),` 和 `migrationStatus: document.getElementById('migration-status'),`	删除。移除 DOM 引用。
L114-116	`elements.migrationStatus.textContent = state.settings.legacyTasksAdopted ? ...`	删除。移除迁移状态渲染逻辑。
L117	`elements.adoptLegacy.disabled = state.settings.legacyTasksAdopted;`	删除。移除按钮状态绑定。
L173-186	`elements.adoptLegacy.addEventListener('click', async () => {...})`	删除。移除迁移按钮的整个事件处理函数。

1.7 tests/integration.js — 测试适配

行号	内容	清理方案
L15	`assert.equal(store.snapshot().tasks.length, 3, ...)`	修改。默认任务数量从 3 变为 7（通用模板），断言需更新。
L16	`assert.ok(store.snapshot().tasks.every((task) => !task.enabled), ...)`	保留。默认关闭的逻辑不变。

2. 架构优化建议

2.1 模块拆分

当前问题: main.js 589 行，承载窗口管理、IPC 通信、系统托盘、任务迁移等所有逻辑。

建议:

当前文件	建议拆分
`src/main.js` (589行)	拆分为 `main.js`(入口) + `window-manager.js`(窗口) + `ipc-handlers.js`(IPC) + `tray-manager.js`(托盘)
`src/config-store.js` (212行)	保持单文件，但提取默认任务模板到独立文件 `task-templates.js`

2.2 渲染进程架构

当前问题: manager.js 263 行，包含状态管理、UI 渲染、事件处理混杂。

建议:

src/renderer/
  ├── manager/
  │   ├── state.js        # 状态管理
  │   ├── render.js       # UI 渲染
  │   ├── events.js       # 事件处理
  │   └── components/     # UI 组件
  └── pet/
      ├── state.js
      ├── animations.js
      └── interactions.js

2.3 事件系统升级

当前问题: 使用原生 EventEmitter + IPC 手动广播状态。

建议: 引入轻量状态管理方案：

主进程使用 EventEmitter（保持）
渲染进程使用简单的 Pub/Sub 模式
考虑引入 zustand 或手写简单的响应式 store

2.4 配置文件版本管理

当前问题: config.json 无 schema version，未来升级可能导致不兼容。

建议:

// 在 config-store.js 中增加版本迁移
const CONFIG_VERSION = 2; // 当前版本

defaults() {
  return {
    version: CONFIG_VERSION, // 已有 version 字段，需实际使用
    // ...
  };
}

migrate(data) {
  if (data.version < 2) {
    // v1 → v2: 移除 legacyTasksAdopted, 更新任务模板
    delete data.settings.legacyTasksAdopted;
    data.tasks = migrateTasks(data.tasks);
    data.version = 2;
  }
  return data;
}

3. 代码质量改进建议

3.1 魔法数字消除

文件	行号	内容	建议
`main.js`	L25-26	`BASE_PET_WIDTH = 320`, `BASE_PET_HEIGHT = 480`	移至 `constants.js`
`main.js`	L139	`setTimeout(..., 250)`	提取为 `POSITION_SAVE_DEBOUNCE_MS`
`main.js`	L223	`clamp(..., 0.5, 1.75)`	提取为 `SCALE_MIN`, `SCALE_MAX`
`task-scheduler.js`	L30	`setInterval(..., 5000)`	提取为 `TICK_INTERVAL_MS`
`task-scheduler.js`	L92	`.slice(-16000)`	提取为 `MAX_LOG_LENGTH`
`manager.js`	L44	`setTimeout(..., 3200)`	提取为 `TOAST_DURATION_MS`
`config-store.js`	L160-166	`slice(0, 80)`, `slice(0, 300)`, `slice(0, 200000)`	提取为命名常量

3.2 错误处理增强

问题	文件	建议
部分 catch 块吞没错误	`main.js:463`	`catch (_) {}` 应至少记录日志
缺少全局异常捕获	`main.js`	添加 `process.on('uncaughtException')` 和 `unhandledRejection`
PowerShell 路径硬编码	`main.js:431`, `task-scheduler.js:68`	提取为工具函数 `getPowerShellPath()`

3.3 类型安全

建议: 引入 JSDoc 类型注释，为后续可能的 TypeScript 迁移做准备。

/**
 * @typedef {Object} Task
 * @property {string} id
 * @property {string} name
 * @property {string} description
 * @property {string} time - HH:mm format
 * @property {boolean} enabled
 * @property {string} script
 * @property {string|null} lastRunDate
 * @property {string|null} lastRunAt
 * @property {string} lastStatus
 */

/**
 * @typedef {Object} Settings
 * @property {boolean} autoStart
 * @property {boolean} alwaysOnTop
 * @property {boolean} animationEnabled
 * @property {boolean} visible
 * @property {number} scale
 * @property {{x: number, y: number}|null} position
 * @property {string|null} customPetImage
 */

3.4 测试覆盖

问题	建议
仅 1 个集成测试文件	增加单元测试（config-store, task-scheduler）
无渲染进程测试	引入 Spectron 或 Playwright 进行 E2E 测试
无 CI/CD	配置 GitHub Actions 自动化测试和构建

4. 依赖升级建议

4.1 当前依赖

依赖	当前版本	最新版本	建议
`electron`	43.2.0	检查最新 LTS	每季度升级一次
`electron-builder`	26.15.3	检查最新版	跟随 Electron 升级

4.2 建议新增依赖

依赖	用途	优先级
`i18next` + `i18next-fs-backend`	国际化框架	P0
`greenworks`	Steamworks SDK Node.js 绑定	P0
`electron-log`	结构化日志	P1
`electron-updater`	自动更新（可选，Steam 自带更新）	P2

4.3 安全审计

npm audit

建议在 CI 中加入 npm audit 检查，定期修复已知漏洞。

5. 清理优先级与工时估算

序号	清理项	工作量	优先级
1	删除 config-store.js Wallpaper Engine 硬编码	0.5 天	最高
2	重写内置任务模板 (3 → 7 通用模板)	1 天	最高
3	删除 main.js adoptLegacyTasks + IPC 通道	0.5 天	最高
4	删除 preload.js adoptLegacyTasks API	0.1 天	最高
5	删除 manager.html 迁移面板	0.1 天	最高
6	删除 manager.js 迁移相关代码	0.3 天	最高
7	删除 config-store.js legacyTasksAdopted	0.1 天	最高
8	更新集成测试	0.3 天	最高
9	提取魔法数字为常量	0.5 天	高
10	增强错误处理	1 天	高
11	模块拆分 (main.js)	2 天	中
12	配置文件版本管理	1 天	中
13	渲染进程架构优化	2 天	中
14	JSDoc 类型注释	1.5 天	低
15	增加单元测试	2 天	低
16	依赖升级	0.5 天	低

合计: 约 12.5 人天