chore: initialize qiming workspace repository

qimingclaw/crates/agent-electron-client/docs/REFACTOR-PLAN.md

@@ -0,0 +1,294 @@
+# agent-electron-client 重构执行计划（v3）
+
+> 适用范围：`/Users/apple/workspace/qiming-agent/crates/agent-electron-client`
+>
+> 基线日期：2026-03-03
+
+## 1. 重构目标
+
+本次重构以“目录与职责对齐”为核心，不改业务行为，优先解决以下问题：
+
+1. `main / preload / renderer` 边界不够清晰，`preload.ts` 仍位于 `src/main/`
+2. `src/main/` 与 `src/renderer/` 顶层存在平铺文件过多的问题
+3. `docs/` 与 `scripts/` 平铺，维护和检索成本高
+4. 部分设置组件疑似死代码，需要在重构窗口期完成判定
+
+同时，本轮重构明确以“开发/维护友好基座”为目标，要求后续新增需求可在不破坏边界的前提下快速接入。
+
+## 2. 现状核对（与仓库一致）
+
+已核对当前代码树，以下结论已确认：
+
+1. `src/main/preload.ts` 仍在 `main` 目录
+2. `src/main/startup.ts`、`logConfig.ts`、`serviceManager.ts`、`trayManager.ts`、`autoLaunchManager.ts` 均在顶层
+3. `src/renderer/components/` 和 `src/renderer/services/` 仍为平铺结构
+4. `docs/` 与 `scripts/` 仍为平铺结构
+5. `src/**/*.js` 编译产物目前未发现，旧计划中的“清理 src 下 js 产物”从必做项降为巡检项
+6. `AgentSettings`、`AgentRunnerSettings`、`LanproxySettings`、`SkillsSync`、`IMSettings`、`TaskSettings` 当前无引用；`MCPSettings` 被 `SettingsPage` 使用
+
+## 3. 目标结构
+
+### 3.1 src 重构目标
+
+```text
+src/
+  main/
+    main.ts
+    db.ts
+    processManager.ts
+    bootstrap/
+      startup.ts
+      logConfig.ts
+      startupPorts.ts
+    window/
+      serviceManager.ts
+      trayManager.ts
+      autoLaunchManager.ts
+    ipc/
+    services/
+  preload/
+    index.ts
+  renderer/
+    components/
+      pages/
+      settings/
+      setup/
+      modals/
+      dev/
+    services/
+      core/
+      agents/
+      integrations/
+      utils/
+  shared/
+```
+
+### 3.2 docs / scripts 重构目标
+
+```text
+docs/
+  architecture/
+  release/
+  operations/
+  reviews/
+
+scripts/
+  prepare/
+  build/
+  tools/
+```
+
+## 4. 迁移策略（新增）
+
+为降低大规模改路径风险，采用“兼容层迁移”：
+
+1. 文件迁移到新目录后，在旧路径保留一个短期桥接文件（`export * from 'new-path'`）
+2. 全量业务 import 更新完成后，再统一删除桥接文件
+3. 每个 Phase 完成必须通过 `npm run build`，否则不进入下一阶段
+4. 每个 Phase 一个提交，提交信息带 `refactor(phase-x): ...`
+
+## 5. 执行阶段（按提交拆分）
+
+### Phase 0：基线保护（先做）
+
+1. 记录当前可用命令结果：`npm run build`、`npm run test:run`
+2. 新增重构分支：`feature/electron-client-0.6`
+3. 将本文件作为总入口，后续每个阶段回填“已完成/阻塞/风险”
+4. 基线结果（2026-03-03）：
+   - `npm run build`：通过
+   - `npm run test:run`：通过（147 tests）
+   - 已知告警：vite chunk size > 500k、测试阶段 `electron-log` 写系统日志路径出现 EPERM（不影响测试通过）
+
+### Phase 1：main 顶层归类（中风险，优先）
+
+1. 新建 `src/main/bootstrap`、`src/main/window`
+2. 迁移并更新 import（先迁移再留桥接）：
+   - `startup.ts`、`logConfig.ts`、`startupPorts.ts` -> `bootstrap/`
+   - `serviceManager.ts`、`trayManager.ts`、`autoLaunchManager.ts` -> `window/`
+3. 回归验证：
+   - `npm run build:main`
+   - 主进程启动冒烟（`npm run dev:electron`）
+4. 完成记录（2026-03-03）：
+   - 已迁移到新目录：
+     - `src/main/bootstrap/{startup.ts,logConfig.ts}`
+     - `src/main/window/{serviceManager.ts,trayManager.ts,autoLaunchManager.ts}`
+   - 已更新直接引用到新路径：`main.ts`、`ipc/appHandlers.ts`
+   - 已添加旧路径桥接文件（短期兼容）：
+     - `src/main/startup.ts`
+     - `src/main/logConfig.ts`
+     - `src/main/serviceManager.ts`
+     - `src/main/trayManager.ts`
+     - `src/main/autoLaunchManager.ts`
+   - 验证结果：`npm run build:main` 通过，`npm run build` 通过
+
+### Phase 2：preload 提升为一级目录（中高风险）
+
+1. 移动 `src/main/preload.ts` -> `src/preload/index.ts`
+2. 更新 `main.ts` 的 preload 产物路径
+3. 更新配置：
+   - `tsconfig.main.json` include `src/preload/**/*`
+   - `tsconfig.json` 增加 `@preload/*`
+   - `vite.config.ts` / `vitest.config.ts` 增加 `@preload`
+4. 回归验证：
+   - `npm run build`
+   - `npm run dev` 并确认 IPC API 可用
+5. 完成记录（2026-03-03）：
+   - 已迁移：`src/main/preload.ts` -> `src/preload/index.ts`
+   - 已更新主进程路径：`main.ts` 使用 `../preload/index.js`
+   - 已更新配置：`tsconfig.main.json`、`tsconfig.json`、`vite.config.ts`、`vitest.config.ts`
+   - 已添加兼容桥接：`src/main/preload.ts`（转发到 `src/preload/index.ts`）
+   - 验证结果：`npm run build` 通过，`npm run test:run` 通过
+
+### Phase 3：renderer/services 分组（中风险）
+
+1. 新建 `core/agents/integrations/utils`
+2. 迁移 service 文件并维护 `services/index.ts` barrel（旧路径保留桥接）
+3. 批量修复组件中的服务 import
+4. 回归验证：
+   - `npm run build`
+   - 关键功能冒烟：setup、auth、mcp、agent runner、lanproxy
+5. 完成记录（2026-03-03）：
+   - 已迁移到新目录：
+     - `core/{api,setup,auth,ai}.ts`
+     - `agents/{agentRunner,sandbox,permissions}.ts`
+     - `integrations/{fileServer,lanproxy,skills,im,scheduler}.ts`
+     - `utils/logService.ts`
+   - 已更新调用方路径：`App.tsx` 与相关组件均改为新分组路径
+   - 已更新 `services/index.ts` barrel 到新结构
+   - 已添加旧路径桥接文件（短期兼容）
+   - 验证结果：`npm run build` 通过，`npm run test:run` 通过
+
+### Phase 4：renderer/components 分组（中风险）
+
+1. 迁移 page 组件到 `components/pages`
+2. 迁移 settings 组件到 `components/settings`
+3. 迁移 setup 与 modal 组件到对应目录
+4. 批量修复 import 路径，重点关注：
+   - `App.tsx`
+   - `SettingsPage.tsx`
+   - `ClientPage.tsx` 样式路径
+5. 回归验证：
+   - `npm run build:renderer`
+   - `npm run test:run`
+6. 完成记录（2026-03-03）：
+   - 已迁移到新目录：
+     - `pages/{ClientPage,SettingsPage,DependenciesPage,AboutPage,PermissionsPage,LogViewer}.tsx`
+     - `settings/{MCPSettings,AgentSettings,AgentRunnerSettings,LanproxySettings,SkillsSync,IMSettings,TaskSettings}.tsx`
+     - `setup/{SetupWizard,SetupDependencies}.tsx`
+     - `modals/PermissionModal.tsx`
+   - 已更新调用方路径：`App.tsx` 与相关组件的相对路径已全部修正
+   - 已添加旧路径桥接文件（短期兼容）
+   - 验证结果：`npm run build` 通过，`npm run test:run` 通过
+
+### Phase 5：文档与脚本目录重排（低风险，后置）
+
+1. 按主题迁移 `docs/*` 到 `architecture/release/operations/reviews`
+2. 按用途迁移 `scripts/*` 到 `prepare/build/tools`
+3. 更新 `package.json` scripts 路径与 electron-builder 的 `afterSign`
+4. 回归验证：
+   - `npm run check-ports`
+   - `npm run prepare:uv`
+   - `npm run build`
+5. 完成记录（2026-03-03）：
+   - 已迁移 docs：
+     - `docs/{architecture,release,operations,reviews}` 分组已落地
+     - 架构文档文件名已去掉 `ARCHITECTURE-` 前缀
+   - 已迁移 scripts：
+     - `scripts/{prepare,build,tools}` 分组已落地
+   - 已更新路径引用：
+     - `package.json` scripts
+     - `package.json` -> `build.afterSign`
+     - 相关 docs 与注释中的脚本路径
+   - 验证结果：
+     - `npm run check-ports` 通过
+     - `npm run build` 通过
+     - `npm run prepare:uv` 受当前环境网络限制失败（`ENOTFOUND github.com`），不属于代码回归
+
+### Phase 6：死代码判定与清理（建议）
+
+1. 对无引用组件进行逐项判定（保留/删除/后续接入）
+2. 若删除，需同步更新文档与 release note
+3. 回归验证：`npm run build && npm run test:run`
+4. 完成记录（2026-03-03）：
+   - 判定结果：
+     - `MCPSettings` 仍被 `SettingsPage` 使用
+     - `AgentSettings`、`AgentRunnerSettings`、`LanproxySettings`、`SkillsSync`、`IMSettings`、`TaskSettings` 目前无业务引用
+   - 处理决策：
+     - 本轮不做删除，仅完成目录重构和桥接兼容；死代码清理单独作为后续行为变更任务
+   - 验证结果：`npm run build` 通过，`npm run test:run` 通过
+
+## 6. 风险与约束
+
+1. `preload` 路径改动会直接影响 Electron 启动，必须在单独阶段完成
+2. `services/index.ts` barrel 重排容易引入循环依赖，需要逐步迁移并即时编译
+3. docs/scripts 重命名后可能影响 CI 或外部脚本，需全文检索 `docs/`、`scripts/` 引用
+4. 本次不调整业务协议、不变更 IPC contract、不触发数据库 schema 变更
+
+## 7. 验收标准
+
+满足以下条件才可视为本轮重构完成：
+
+1. `npm run build` 成功
+2. `npm run test:run` 成功
+3. `npm run dev` 可正常进入主界面，setup 和 settings 页面可访问
+4. `dist/main/main.js` 启动后 preload 正常加载，`window.electronAPI` 可用
+5. 文档路径、脚本路径引用无失效（`rg` 检查无旧路径残留）
+6. 新增功能可按分层目录直接落位（`main/preload/renderer/services/components`），无需再进行目录级重排
+
+## 8. 进度记录
+
+- [x] Phase 0 基线保护
+- [x] Phase 1 main 顶层归类
+- [x] Phase 2 preload 提升
+- [x] Phase 3 renderer/services 分组
+- [x] Phase 4 renderer/components 分组
+- [x] Phase 5 文档与脚本目录重排
+- [x] Phase 6 死代码判定与清理
+
+## 9. 本次版本说明
+
+相较 v2，本版新增了“低风险迁移机制”：
+
+1. 增加兼容层策略（迁移后短期桥接，最后统一删）
+2. 阶段顺序调整为先核心边界（main/preload/services），后外围目录（docs/scripts）
+3. 强化阶段门禁（每阶段必须可构建）
+
+## 10. 基座约束（后续开发准入）
+
+为保证后续新增需求和维护稳定性，后续提交应遵循以下约束：
+
+1. 边界约束：
+   - renderer 不直接依赖 main 代码；进程间只通过 IPC（`src/main/ipc` + `window.electronAPI`）
+   - preload 只做安全桥接，不承载业务逻辑
+2. 分层约束：
+   - renderer 新 service 必须落到 `core/agents/integrations/utils` 之一
+   - renderer 新页面组件落 `components/pages`，弹窗落 `components/modals`
+3. 兼容桥接约束：
+   - 旧路径桥接文件仅短期存在，发布 `0.6.x` 后统一清理
+   - 新代码禁止继续引用桥接文件
+4. 测试与门禁：
+   - 变更必须通过 `npm run build`、`npm run test:run`
+   - 影响 IPC、启动路径、权限模型的改动需补最小冒烟验证
+5. 文档同步：
+   - 新增模块时同步更新 `docs/architecture/INDEX.md`（或对应主题文档）
+
+## 11. 基座后续任务（建议）
+
+建议在本轮重构后追加三项治理任务，进一步提升长期可维护性：
+
+1. 增加 lint/import 规则，禁止跨层引用与旧桥接路径引用
+2. 为关键 IPC handler 增加 contract tests（请求/响应 schema）
+3. 清理无引用 settings 组件（单独评审，避免与结构重构混改）
+
+### 11.1 已落地（2026-03-03）
+
+1. 已新增 `scripts/tools/check-import-boundaries.js`
+2. 已新增 `npm run check:boundaries`
+3. 已新增 `tests/scripts/check-import-boundaries.test.ts`，覆盖：
+   - 合法 main/renderer 分层通过
+   - renderer 直接引用 main 失败
+   - bridge 文件引用失败
+4. 规则覆盖：
+   - 禁止引用 bridge 文件（`src/main/*` 与 `src/renderer/*` 顶层桥接）
+   - 禁止 renderer 直接引用 main/preload
+   - 禁止 main 直接引用 renderer