From 31201634c418f512048448c84d850f9030f06b2e Mon Sep 17 00:00:00 2001
From: Jokul <wangshengshan011@163.com>
Date: Fri, 10 Jul 2026 23:58:19 +0800
Subject: [PATCH] =?UTF-8?q?docs:=20=E4=BF=AE=E6=AD=A3=20AGENTS.md=20-=20El?=
 =?UTF-8?q?ectron=20=E7=89=88=E6=9C=AC=E3=80=81=E6=9E=84=E5=BB=BA=E4=BA=A7?=
 =?UTF-8?q?=E7=89=A9=E7=BB=86=E8=8A=82=E3=80=81=E8=BF=90=E8=A1=8C=E6=97=B6?=
 =?UTF-8?q?=E8=B7=AF=E5=BE=84=E3=80=81=E5=B7=B2=E7=9F=A5=E9=97=AE=E9=A2=98?=
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

- Electron 版本 43 -> 33
- 补充 ESM 模块系统说明 (main .js / preload .mjs)
- 补充构建产物文件名和 package.json main 字段
- 新增运行时 __dirname 路径表 (preload/renderer/icon)
- 新增 Electron 二进制安装问题及修复方法
---
 AGENTS.md | 40 +++++++++++++++++++++++++++++++++++++---
 1 file changed, 37 insertions(+), 3 deletions(-)

diff --git a/AGENTS.md b/AGENTS.md
index 1c59677..04fab6f 100644
--- a/AGENTS.md
+++ b/AGENTS.md
@@ -6,11 +6,12 @@ Fork of [AnotherRedisDesktopManager](https://github.com/qishibo/AnotherRedisDesk
 
 ## Stack
 
-- **Shell:** Electron 43 (`src/main/index.ts`)
+- **Shell:** Electron 33 (`src/main/index.ts`)
 - **Preload:** `src/preload/index.ts` (contextBridge, typed API)
 - **Renderer:** Vue 3 + Pinia + Element Plus + Vue Router (`src/renderer/src/`)
 - **IPC types:** `src/preload/index.d.ts` (ElectronAPI interface, global Window augmentation)
 - **Build:** electron-vite + Vite 6 + TypeScript 5
+- **Module system:** `"type": "module"` (ESM) — main outputs `.js`, preload outputs `.mjs`
 - **Redis client:** ioredis 5 (main process only)
 - **Persistence:** electron-store + safeStorage (credentials)
 
@@ -207,13 +208,26 @@ Renderer (src/renderer/)
 ## Build config
 
 - `electron.vite.config.ts` defines three build targets: main, preload, renderer
-- Entry points auto-detected: `src/main/index.ts`, `src/preload/index.ts`, `src/renderer/index.html`
-- Build output: `out/main/`, `out/preload/`, `out/renderer/`
+- Entry points auto-detected (zero-config): `src/main/index.ts`, `src/preload/index.ts`, `src/renderer/index.html`
+- Build output: `out/main/index.js`, `out/preload/index.mjs`, `out/renderer/` (index.html + assets/)
+- `package.json` `"main"` points to `./out/main/index.js`
 - electron-builder packages into `release/`
 - Renderer dev server runs on port 5173
 - Main/preload use `externalizeDepsPlugin()` to keep node_modules external
 - `@renderer` alias resolves to `src/renderer/src`
 
+### Runtime paths in main process
+
+`src/main/index.ts` uses `__dirname` (resolved to `out/main/` at runtime) to locate siblings:
+
+| Target | Expression |
+|--------|-----------|
+| Preload script | `join(__dirname, '../preload/index.mjs')` |
+| Renderer HTML | `join(__dirname, '../renderer/index.html')` |
+| App icon | `join(__dirname, '../../build/icons/icon_256.png')` |
+
+If output directory or file extensions change, update these paths accordingly.
+
 ## TypeScript
 
 - Root `tsconfig.json` references `tsconfig.node.json` (main + preload) and `tsconfig.web.json` (renderer)
@@ -232,3 +246,23 @@ Renderer (src/renderer/)
 ## Legacy
 
 The `legacy/` directory contains the old Vue 2 + Webpack 4 codebase. It is gitignored and not part of the v2 build. See `legacy/AGENTS.md` for its documentation.
+
+## Known issues
+
+### Electron binary not installed after `npm install`
+
+The `allowScripts` field in `package.json` blocks electron's postinstall script (`node install.js`), so `npm install` only fetches the npm package without downloading the ~100 MB binary. `npm run dev` then fails with `Error: Electron failed to install correctly` or `spawn ... ENOENT`.
+
+**Fix:** Run the install script manually after `npm install`:
+
+```bash
+node node_modules/electron/install.js
+```
+
+If the download is slow (GitHub releases), use a mirror:
+
+```bash
+ELECTRON_MIRROR="https://npmmirror.com/mirrors/electron/" node node_modules/electron/install.js
+```
+
+> `package.json` references `scripts/fix-electron.sh` (`npm run fix:electron`) but the script does not exist yet.