84 lines
5.8 KiB
Markdown
84 lines
5.8 KiB
Markdown
# Electron 客户端 Review（2026-02）
|
||
|
||
## 1. 已做修正
|
||
|
||
### 1.1 Windows CI 上传步骤
|
||
- **问题**：`Upload artifacts to Release` 使用 bash 语法，Windows runner 默认 shell 为 PowerShell，会导致上传失败。
|
||
- **修正**：为该 step 增加 `shell: bash`，三平台统一用 bash 执行上传脚本。
|
||
|
||
---
|
||
|
||
## 2. 架构与脚本
|
||
|
||
### 2.1 打包脚本（package.json）
|
||
- **dist:mac** / **dist:win** / **dist:linux**：单平台、Mac 走签名/公证（需证书与 env）。
|
||
- **dist:mac:unsigned**：仅 Mac、无签名，用于无证书环境。
|
||
- **dist:unsigned:local**：当前平台无签名，避免在 Mac 上同时打 Win/Linux 时的 node-gyp 交叉编译。
|
||
- **dist:all** / **dist:unsigned**：一次传 `--mac --win --linux`，在 arm64 Mac 上会因 better-sqlite3 交叉编译失败，仅适合在无 native 依赖或非交叉编译场景使用；当前推荐用 CI 分平台打。
|
||
|
||
### 2.2 prepare 脚本
|
||
- **prepare:uv**：多平台，从 GitHub 下载或使用已有 uv，正常。
|
||
- **prepare:sign-uv**：仅 macOS 执行签名，其他平台跳过，正常。
|
||
- **prepare-lanproxy**：缺二进制时改为**仅警告 + 创建目录**，不 `process.exit(1)`，CI 可正常产出 Win/Linux 安装包，该平台下 lanproxy 功能不可用。
|
||
- **prepare-sdk**：若 `vendors/qimingcode-sdk` 不存在则 `process.exit(0)`；若仓库未包含或未 clone 该路径，后续 electron-builder 可能因 `file:` 依赖或符号链接报错，需保证 CI 与本地均有该目录（或等效依赖）。
|
||
|
||
### 2.3 主进程 import 路径
|
||
- 已按 `tsconfig.main.json` 的 rootDir 修正：`acpClient`、`engineManager`、`unifiedAgent`、`dependencies` 中对 `constants` / `@shared/constants` 的相对路径，`build:main` 可正常通过。
|
||
|
||
---
|
||
|
||
## 3. CI（release-electron.yml）
|
||
|
||
- **触发**：tag `electron-v*`，与 Tauri 的 `v*` 分离，设计合理。
|
||
- **prepare**：解析版本、读取 release notes、创建 Release，逻辑清晰。
|
||
- **build-electron**：matrix 三平台（macos / windows / ubuntu），各跑对应 `dist:*`，fail-fast: false 可接受。
|
||
- **macOS**：可选导入证书与公证 key，未配置时走 `dist:mac:unsigned`，合理。
|
||
- **上传**：已改为 `shell: bash`，Windows 上也可正确执行。
|
||
|
||
---
|
||
|
||
## 4. 风险与建议
|
||
|
||
| 项 | 说明 |
|
||
|----|------|
|
||
| **vendors/qimingcode-sdk** | 若未提交或 CI 未包含，prepare-sdk 会跳过，可能导致构建或打包失败。建议：CI 确保该路径存在或使用可选的 file 依赖策略。 |
|
||
| **lanproxy 缺失** | 已做：主进程返回友好错误文案；新增 `lanproxy:isAvailable` IPC；设置页在无二进制时展示「当前平台暂不支持内网穿透」并禁用启动。 |
|
||
| **dist:unsigned:local 语义** | 当前为「当前平台 + 无签名」。若希望本地默认走签名，保留 `dist:mac` 为默认 Mac 打包方式即可；`dist:unsigned:local` 明确为「快速无签名构建」即可。 |
|
||
| **Release 已存在** | 当前逻辑为 `gh release view` 存在则只打印 "Release already exists" 不报错，后续上传会覆盖同名的 asset（--clobber）。若需避免覆盖，可改为上传前检查或使用不同 artifact 名称。 |
|
||
|
||
---
|
||
|
||
## 5. 日志设计（logConfig）
|
||
|
||
### 5.1 实现要点
|
||
- **logConfig.ts**：`initLogging()` 在 main 入口最早调用，设置 electron-log 的 file transport：路径、maxSize、level、自定义 `archiveLogFn`（轮转时重命名为 `main.YYYY-MM-DD-HHmmss.log`），并在启动时执行 TTL 清理。
|
||
- **开发 vs 正式**：`isDev()` 用 `!app.isPackaged` 与 `NODE_ENV` 判断；开发 5MB/30 天、正式 2MB/7 天，文件级别分别为 debug / info。
|
||
- **cleanupOldLogs**：只删 `main`/`renderer` 的 `.old.log` 与 `.YYYY-MM-DD-*.log`，不删 `main.log`、`renderer.log` 及其他文件（如 app.json、mcp/ 等）。
|
||
|
||
### 5.2 审查结论
|
||
- 轮转与 TTL 逻辑清晰，归档命名可区分且便于按时间删除。
|
||
- `archiveLogFn` 内调用 `log.info` 会写入当前 main.log（轮转后为新文件），不会造成递归轮转。
|
||
- 已扩展 TTL 清理：对同一 logDir 下的 `renderer.old.log`、`renderer.YYYY-MM-DD-*.log` 应用相同 TTL，与 main 归档一并清理。
|
||
- **LOGGING.md** 已说明目录、行为与配置入口。
|
||
|
||
### 5.3 latest.log 统一入口（多平台）
|
||
- **实现**：`updateLatestLog(logDir)` 在 init 结束时通过 `setImmediate` 调用（保证 main.log 已存在）；轮转时仅在 Windows 下通过 `setImmediate` 再次调用，因硬链接指向 inode 需重新指向新 main.log。
|
||
- **macOS/Linux**：`fs.symlinkSync('main.log', latestPath, 'file')`，相对路径，轮转后无需更新。
|
||
- **Windows**：`fs.linkSync(mainPath, latestPath)` 硬链接，无需管理员/开发者模式；轮转后 setImmediate 时新 main.log 已由 transport 同步写入，时序正确。
|
||
- **log:list**：优先读 `latest.log`，不存在则回退 `getFile().path`；`log:getDir` / `log:openDir` 仍为目录，用户打开目录后可见 `latest.log`。
|
||
- **cleanupOldLogs** 不删 `latest.log`（`isArchiveLogName` 不匹配），符合预期。
|
||
- **可选改进已做**：`log:openDir` 在 macOS 上 `open -R <latest.log>`、在 Windows 上 `explorer /select,<latest.log>`，打开目录并选中当前日志入口；失败时回退为仅打开目录；Linux 仍为仅打开目录。
|
||
|
||
---
|
||
|
||
## 6. 文档与约定
|
||
|
||
- **SIGNING.md**：记录 Mac 签名/公证与 env，便于本地与 CI 配置。
|
||
- **release-notes/**：支持 `release-notes/electron-v<version>.md` 作为 Release 说明，与 workflow 一致。
|
||
- 应用名与目录：使用 `APP_DISPLAY_NAME` / `APP_NAME_IDENTIFIER`（及 `APP_DATA_DIR_NAME`）统一，避免硬编码 `.qimingclaw` / `qiming-agent`。
|
||
- **LOGGING.md**：日志轮转、TTL、开发/正式差异说明。
|
||
|
||
---
|
||
|
||
*Review 完成；Windows 上传步骤已修正；日志设计与 latest.log 多平台方案已纳入审查。*
|