feat: 支持 macOS arm64 打包，修复图标未入库

新增 build-mac.js，产出 ad-hoc 签名的 .app 与 DMG。只能在 macOS 上
构建：DMG 依赖 hdiutil，且 Apple Silicon 拒绝执行未签名二进制，改名
与改 plist 后必须用 codesign 重签。

按官方 darwin-arm64 运行时的真实结构处理四处易错点：用 ditto 解压以
保留 framework 符号链接、删除重打包后失效的 ElectronAsarIntegrity、
为改名后的 helper 补上 CFBundleExecutable、签名由内向外且单独签
Squirrel 的 ShipIt。

打包版数据目录改为按平台决定：macOS 走 appData，避免写进 DMG 挂载后
只读的 .app 内部并在升级覆盖时丢失书库；Windows 便携版行为不变。
窗口图标在非 Windows 平台改用 PNG。

.gitignore 的 dist 规则补上前导斜杠。此前它同时匹配 icons/dist/，
导致构建与单测依赖的图标从未入库，新克隆的仓库无法构建。

AGENTS.md

@@ -70,13 +70,26 @@ npx electron src/_test/electron/<name>.integration.js   # Electron 集成
 ## 构建
 
 ```bash
-npm run build     # 输出 dist/PeopleLib-windows-x64/
+npm run build     # Windows，输出 dist/PeopleLib-windows-x64/
+npm run build:mac # macOS arm64，输出 .app 与 .dmg，只能在 macOS 上跑
 ```
 
+Windows：
+
 - 输出目录固定，不带版本号。改名会导致 `data/` 被遗留在旧目录。
 - 构建保留 `data/`，但会清空其余内容。**构建前必须退出该目录下运行中的 `PeopleLib.exe`**，否则清理到一半失败，目录处于不完整状态。
 - 涉及 `data/` 的操作前后做逐文件哈希比对，确认书库、笔记、批注未被改动。
 
+macOS（`build-mac.js`，易踩坑）：
+
+- **不能交叉构建**。DMG 需要 `hdiutil`，且 Apple Silicon 内核直接拒绝执行未签名二进制；改名与改 plist 会让 Electron 原始签名失效，必须用 macOS 的 `codesign` 重签（ad-hoc `--sign -` 即可）。
+- 解压官方 zip 必须用 `ditto`。`Electron Framework.framework` 内有符号链接，用 Node 或 `unzip` 解压会展开成副本，签名随即失效。
+- 重打包后 `Info.plist` 里的 `ElectronAsarIntegrity` 必须删除，否则启动即报完整性错误。
+- helper 的 plist **没有** `CFBundleExecutable`，靠 bundle 名推断可执行文件名。重命名 helper 后必须显式补上该字段，否则渲染进程起不来，界面一片空白。
+- 签名严格由内向外：嵌套可执行文件 → helper → framework → 外层 `.app`。带版本的 framework 签 `Versions/A`；`Squirrel.framework` 的 `Resources/ShipIt` 是独立可执行文件，要单独签。
+- 数据目录走 `~/Library/Application Support/PeopleLib`，**不要**沿用 Windows 的便携布局：`.app` 在 DMG 里只读，且升级覆盖会删掉用户书库。
+- `.icns` 由 `npm run icons:icns` 生成，纯 Node 实现（icns 自 10.7 起内嵌 PNG），不依赖 macOS 的 `iconutil`。窗口图标在非 Windows 平台用 PNG，`.ico` 只有 Windows 认。
+
 ## 仓库
 
 两个远端，用途不同：
@@ -86,6 +99,6 @@ npm run build     # 输出 dist/PeopleLib-windows-x64/
 
 其他：
 
-- `dist/` 已 gitignore。诊断产物（`*-diagnostic.png`、`probe*.json`）也已忽略，不要提交。
+- 根目录 `dist/` 已 gitignore，规则写作 `/dist/`，**必须保留前导斜杠**：不加会连 `icons/dist/` 一起忽略，新克隆的仓库缺图标，构建直接失败。诊断产物（`*-diagnostic.png`、`probe*.json`）也已忽略，不要提交。
 - 未跟踪文件视为用户资产，不要删除或覆盖。清理前先看 `git status --porcelain`。
 - 提交前 `git diff --cached` 检查是否混入密钥。