MooTool Next Electron 完整指南：命令面板、离线工具链与 MCP 智能体接入

• 桌面应用
• 开发工具

本篇技术指南围绕 MooTool 的 Electron 桌面版（代号next/）展开，介绍这套基于 Electron + Vite + React + TypeScript 重写的开发者工具集如何通过命令面板、批量文件处理、离线 OCR、快速预览、翻译与 AI 集成（MCP / Skill）串起日常开发工作流。读完本文，你将掌握 MooTool Next Electron 的核心命令与配置方式、各工具模块的边界约束与源码实现位置，以及如何把它接入 Codex、Claude Code、Cursor 等本地 AI 客户端。

一、项目定位与技术栈

MooTool Next Electron 是 MooTool 的桌面重写版，采用 Electron + Vite + React + TypeScript 构建，位于仓库 next/ 目录。当前next/package.json标注的版本为1.3.3，产品名为 MooTool，应用 ID 为com.rememberber.mootool.next.electron。与 Java 原版、macOS 原生版、Tauri 版等并列，它是这套"开发者工具箱"在桌面端的主推实现之一。

目录结构与职责划分

从源码结构看，Next Electron 版把"界面"与"系统能力"严格分层：

• src/features/*：全部工具页面，如 JSON、时间、编码、正则、Cron、HTTP、图片、随手记等，按功能分目录组织（见 toolRegistry.ts）。
• src/shared/contracts/*：渲染进程与主进程共享的契约、参数校验与持久化规则。
• electron/main/*：主进程能力，包括批量重命名、全局快捷键、窗口材质、OCR、翻译、系统服务等。
• electron/preload/*：文件系统、存储、Shell 与系统能力对渲染进程的安全暴露层。
• electron/mcp/*：独立于桌面界面的 MCP 服务入口，供 AI 客户端调用。

常用命令

next/package.json定义了完整的开发与验证链路：

npm install # postinstall 会自动执行 scripts/install-electron.mjs npm run dev # 构建原生 OCR + 准备 PDF 预览资源 + electron-vite dev npm run typecheck # tsc --noEmit npm run build # 构建原生 OCR + 准备 PDF 资源 + 类型检查 + electron-vite build npm run check # typecheck + vitest 单元测试 + 生产构建，一站式验证 npx playwright test tests/electron/<spec>.spec.ts # 单个桌面 E2E 用例

其中dev与build都会先执行build:native-ocr（macOS 下编译 Swift OCR helper）与prepare:preview-pdf（将 PDF.js 的 CMap、字体、WASM 等复制到public/pdfjs），确保 OCR 与 PDF 预览能力开箱即用。

设计方向

项目第一版外壳遵循 macOS 风格参考：浅色原生观感的侧栏、隐藏内嵌式红绿灯、安静的 1px 分隔线与低对比 hover 状态、留白充足的大型中央工作区、以圆角命令输入框作为主要交互入口、图标优先的克制化导航，同时将渲染进程与本地系统能力严格分离。

二、开发者命令面板（Command Palette）

命令面板是 Next Electron 版最具特色的入口：在主窗口内按Cmd+K（macOS）或Ctrl+K（Windows/Linux），或点击侧栏搜索按钮即可打开。它同时搜索工具页面与可执行动作，用方向键选择、Enter 执行；工具名搜索会把工具页面放在第一结果。

内置动作与内联命令

README 给出了一张动作清单，均可在面板中直接输入别名执行：

关键约束与安全边界：

• 文本动作最多接受100,000 个字符。
• 无效 JSON、重复 JSON 键、非法 Base64、非法的 UTF-8 Base64 输出以及错误的 URL 百分号转义都会报错，且不会修改剪贴板。
• 输入与输出只在当前面板会话内保留；面板完全本地运行，不会把文本发送给任何 AI 服务。
• 动作预览后，Enter 或点击Copy result才更新剪贴板；Esc 返回搜索，再次 Esc 关闭面板。只有执行无内联参数的文本动作时才会读取剪贴板，打开或搜索面板不会读取。

常用（Pinned）与最近（Recent）动作

空搜索时面板按常用动作、最近运行、全部动作、工具分组展示。用方向键选中动作后点击Pin action（或在结果预览中固定）即可置顶；Unpin action取消固定。成功的执行会记录最多 5 个不同的最近动作，重复执行会移到最前；Clear recent actions清空最近列表但保留常用。

持久化规则值得注意：

• 常用与最近列表跨重启保留，但只保存校验过的动作 ID 与其顺序，不保存命令参数、剪贴板内容、预览或生成结果。
• 重新运行最近动作时，需要文本的地方读取当前剪贴板；失败或被替代的执行不会进入记录。

托盘菜单的Quick Actions子菜单与常用列表同步：无固定项时默认提供Generate UUID、Format JSON、Base64 decode。点击条目会恢复主窗口并执行动作进入预览，复制仍须显式确认；更新的快捷动作会取代进行中的请求，旧请求不能覆盖新预览或最近顺序。

这些元数据与持久化规则集中在 commandPalette.ts（含normalizeCommandPaletteState、updateCommandPaletteState、orderedCommandActions、trayCommandActions等纯函数），主进程负责校验、存储与托盘刷新。桌面测试 command-preferences.spec.ts 覆盖固定/取消、最近排序与清理、载荷排除、快捷动作在停靠工具之上的派发、重复派发、过期结果、失败与重启持久化。

动作注册与实现

动作元数据与执行逻辑位于 actionRegistry.ts，与页面导航用的 toolRegistry.ts 完全分离。每个动作通过ActionDefinition描述（id、标题、keywords、aliases、input类型与run实现），并采用动态import()按需加载实现，复用已有的 JSON、时间、编码与随手记转换函数。

值得关注的是searchActions的别名匹配策略：较长的别名优先，因此json minify {...}不会被json别名抢先消费；而executeAction统一处理 100,000 字符上限、空输入校验与剪贴板快照读取。

// 来自 src/app/actionRegistry.ts 的结构示意 export type ActionDefinition = { id: CommandActionId titleKey: MessageKey keywords: string[] aliases: string[] input: 'none' | 'text' | 'rich-text' | 'html' run: (input: string, context: ActionContext) => Promise<string> }

全局快捷键

在设置 → 键盘快捷键 → Global command palette可启用系统级快捷键。它默认关闭（升级安装也不会自动打开），默认组合为 macOSCmd+Shift+Space、Windows/LinuxCtrl+Shift+Space。输入自定义组合（如Ctrl+Alt+Space）保存后立即生效；设置页会报告注册状态、拒绝非法组合与内置搜索/设置/编辑器快捷键的冲突，操作系统拒绝注册时提供重试。

快捷键在 MooTool 后台运行也有效：它会恢复隐藏或最小化的主窗口，并打开同样的命令面板（置于任何停靠工具之上）。托盘菜单同样提供Command Palette…。关闭快捷键、更换组合或退出只会释放本功能持有的快捷键，不会改动其他应用，也不会注册剪贴板监听。

实现上，globalCommandShortcut.ts 负责注册与清理，维护active加速键与status状态机（disabled / registered / invalid / conflict / unavailable）；shortcuts.ts 提供normalizeShortcut与validateGlobalShortcut，在渲染进程与主进程间一致地校验组合（修饰键规范化、保留组合冲突检测等）。测试 global-shortcut.spec.ts 覆盖真实注册、模拟回调派发到隐藏/最小化窗口、注册失败重试、重启持久化与禁用后释放。

Linux 注意事项：安装包设置了desktopName与linux.syncDesktopName，使桌面入口与 Wayland 全局快捷键 portal 使用的 Electron 应用身份对齐；Wayland 可用性取决于桌面 portal 与桌面入口的安装，部分桌面会弹出自己的授权对话框。Windows/Linux 的运行时验收尚待进行，目前桌面测试在 macOS 上执行。

焦点细节：在原生工具视图之上打开面板后，移除工具视图会把键盘焦点交还主渲染进程，搜索输入框在移交完成后获得焦点。command-palette-focus.spec.ts 验证了停靠编辑器内的菜单加速键路径、侧栏快捷键与分离工具窗口三种来源下，键入与方向键/Enter/Escape 都路由到真正持有原生焦点的 WebContents；全局快捷键测试也校验了恢复隐藏/最小化窗口后先恢复原生焦点再填充输入。

三、批量重命名（Batch Rename）

Batch Rename位于日常工具组，也可在命令面板搜索rename/重命名。流程分四步：

1. 在原生文件选择器中最多选择500 个普通文件（新选择替换列表；可来自不同目录，各文件留在原目录）。
2. 设置字面量查找/替换文本、前缀、后缀与可选顺序编号。默认保留最终扩展名，.env视为无扩展名文件名；替换文本是字面量，$与正则元字符不会被特殊解释。
3. 勾选要处理的文件，点击Preview rename。编号按展示顺序只统计勾选文件；预览显示原名、新名、未变更项与冲突。
4. 点击Rename files精确应用该预览。修改规则或选择会使界面预览失效，生成新预览会作废旧的服务端 token；任一冲突都会阻止整批执行，预览阶段不写任何文件。

撤销与恢复：Undo last batch可恢复最近一次成功批次（应用重启后仍可撤销）；下一次成功批次会替换该撤销记录。失败批次在回滚成功时保留之前的撤销记录。

边界与安全设计

• 只处理普通文件：不支持目录、递归遍历、符号链接、正则匹配与任意目标目录。
• 依赖硬链接且目录可写；不支持的文件系统或权限问题会停止操作并触发回滚，不降级为复制或覆盖。
• 名称做跨平台保守校验：拒绝大小写/NFC 冲突、Windows 保留名与非法字符、结尾点/空格、255 字节 UTF-8 文件名上限；指向同一 inode 的多个所选硬链接名会被拒绝。
• 预览与执行都校验设备、inode、大小与修改时间，即使文件系统复用了 inode 号也能识别被替换的文件；执行阶段还复查目标占用。写入用独占式硬链接创建 + 删除旧名，绝不故意替换已存在的目标文件。这些检查不是针对并发改动的文件系统锁。

失败操作会尝试还原原名；若恢复无法完成，会保留恢复日志并阻止后续预览。Recover unfinished operation可重试恢复，冲突会报告而不覆盖文件。日志记录原名、目标名、临时路径与文件身份，位于<userData>/file-operations/batch-rename-journal.json。中断后文件可能临时停留在.mootool-rename-<uuid>名称下。损坏的恢复记录会被拒绝访问而不是静默丢弃；外部替换/移动文件或原名被占用会阻止撤销。只还原文件名，不回滚文件内容编辑。

源码实现

• batchRename.ts：定义有界的字面量命名规则与validRenameName。
• batchRenameService.ts：串行化选择/预览/文件操作，持有文件授权与预览 token，原子替换应用拥有的日志后移动文件。它先在原目录以唯一名称暂存（支持仅大小写变更与同批腾出的目标名），日志支持重启后恢复部分暂存或部分完成状态。
• BatchRenameTool.tsx：预览表与显式的执行/撤销控件。其写文件操作不会暴露为快捷文本动作或 MCP 工具。

验证路径：npm run check、batchRenameService.test.ts（owner/token 隔离、名称冲突、被替换源、仅大小写重命名、目标链、回滚、重启恢复、不支持硬链接、撤销冲突）与 batch-rename.spec.ts。运行时验证在 macOS 完成，Windows/Linux 实机验收待进行。

四、批量图片尺寸调整

在Image Assistant中导入图片、勾选后点击Resize。可用小（640×480）、中（1280×720）、大（1920×1080）预设，或填写自定义像素尺寸；留空一边时按各原图比例计算，至少填写一个正整数。弹窗内输出尺寸预览随参数实时更新但不写文件，点开始处理才执行。

三种缩放行为

仅缩小（shrink-only）默认开启：等比适应不放大原图；裁剪填充等比缩小目标框避免放大任何源像素；拉伸分别限制两边不超过原图对应边。每项输入最大 16384px，实际输出单边最大 16384px、总像素不超过 3200 万，超限会禁用整批开始按钮。

输出与文件范围

• 默认保留原图，在图片库生成原文件名_resized.png/jpg；同名时用-2、-3编号，写入采用独占创建避免覆盖。
• 覆盖模式只替换所选图片库文件；格式转换需要不同文件名时先成功写入新图再删除源文件；新名与另一张图冲突会先编号并保留另一张图。
• 自动格式：JPEG 原图输出 JPEG，其他输出静态 PNG；透明区域转 JPEG 时填充白色。不保留动画、EXIF 或原始编码参数。
• 逐张处理并复用既有进度、失败列表与取消机制；取消在解码/绘制结束、保存前或下一张开始前生效，已保存的图片保留。单张失败不撤销已完成结果。

验证见 image-resize.md：npm run check加 image-resize.spec.ts 覆盖混合横竖图预览、单边自动尺寸、真实输出尺寸、中心裁剪/拉伸像素、仅缩小、输入与像素限制、JPEG 格式、原图保护、重复输出、格式转换同名保护、并发独占创建与原生独立窗口窄宽布局。桌面验证运行于 macOS 并使用临时图片库。

五、剪贴板格式转换

命令面板包含四个剪贴板动作，全部遵循"执行后先预览、显式复制或保存"的模型：

这些动作可设为常用并进入最近执行，托盘快捷入口同步；只持久化动作 ID，不保存剪贴板内容、转换结果或导出路径。详细边界见 clipboard-actions.md。

富文本转 Markdown

读取一次文本/HTML 快照，有 HTML 时转换 HTML，只有纯文本时原样保留。支持常见段落、标题、加粗、斜体、删除线、引用、列表、链接、行内代码、代码块与普通表格（首行作表头）。HTML 存入惰性模板片段，绝不插入活动页面；脚本、样式、表单、嵌入对象不参与转换；图片只保留说明文字，不下载或嵌入；链接保留 HTTP/HTTPS/mailto，其他只保留可见文字。剪贴板 HTML 源码则原样预览与保存 HTML 文本（含原标签），应用不渲染或执行它；无 HTML 格式时报错。

表格转 JSON

优先转换 HTML 快照中的第一张表格，否则解析剪贴板文本。支持电子表格常见 TSV 与 CSV：优先选择首行引号外的制表符，否则用逗号；单列表格按换行解析。双引号字段可含换行与分隔符，两个双引号表示一个字面双引号。首行作列名并去除首尾空白；列名不能为空或重复，每行列数必须相同；不推断数字、布尔或日期（001、true、空单元格都保留为字符串）。合并单元格、嵌套表格与不完整行会报错，不会静默丢数据。上限为200 列、5000 行，输入最多 100,000 字符，HTML 最多 5000 个元素，Markdown 嵌套深度限 100 层。

保存预览

所有文本动作结果（包括 UUID、JSON、编码等）都可选.txt、.md、.json、.html后保存为文件。选.json时先做语法检查，非法则不打开保存对话框；取消保存不写文件；保存失败保留预览供重试。命令带文本参数时直接处理该参数而不读剪贴板。验证用 clipboard-actions.spec.ts、command-palette.spec.ts 与 command-preferences.spec.ts。

六、图片与截图文字识别（OCR）

Image Assistant → Recognize text识别当前图片，Screenshot OCR复用区域框选并保留截图进识别预览。选择语言后开始识别，编辑结果后再显式复制或保存为 UTF-8.txt。截图识字只保留窗口内快照，不新增图片库条目；识别可取消，不修改原图、不自动写剪贴板。

平台策略：

• macOS 13+ 使用本地 Apple Vision，不随应用分发 OCR 模型；可选语言按系统实际能力显示，含简体、繁体、英文与日文，「自动（中英）」尝试简繁英。
• Windows/Linux x64/arm64 使用离线 PP-OCRv6 small（完整 JavaScript CPU 流程，模型与推理运行时随包提供，无需 Python），同一多语言模型识别简繁英日；资源缺失、校验失败或不支持的架构会禁用入口并提示。

处理边界

• 使用打开预览时的图片快照（主进程统一收 PNG），原图不改写。
• 图片单边最大 16384px、总像素最大 3200 万，归一化 PNG 最大 32 MiB；结果最多 2000 行、100000 个 UTF-16 字符。PP-OCR 另有 200 个文字区域、单行归一化宽度 4096px 的计算上限。
• 一次运行一个识别任务，原生识别进程最长运行 120 秒；首次初始化推理缓存可能较慢（本机新编译曾约 70 秒），缓存就绪后通常远快于首次。
• 取消、关闭预览或销毁工具视图会停止识别，晚到的结果不能覆盖后续预览。
• 识别阶段不修改剪贴板、不自动保存；快照写入系统临时目录私有任务文件夹（权限0600），交给无 Shell 的 Vision helper 或独立 PP-OCR utility process，结束/失败/取消后删除；应用识别路径不发起网络请求。

构建与分发

npm run dev/npm run build会调用scripts/build-native-ocr.mjs。macOS 开发环境需 Xcode Command Line Tools，脚本编译 macOS 13 部署目标通用可执行文件到out/native/mootool-ocr；Windows/Linux 的打包 hook 生成按架构筛选的资源目录放至resources/ocr并严格校验模型与资源完整性。用户运行安装包不需要 Swift 编译器、Python 或自行下载模型。详情见 image-ocr.md 与 ppocr-backend.md。

PP-OCRv6 small 离线后端

识别每次创建 Electron utility process：校验本地资源后，用 PNG 解码与 OpenCV.js 将透明像素合成到白底并转 BGR，检测图按长边最多 1536（32 的倍数）缩放生成 CHW float32 张量；ONNX CPU 检测后做 DB 阈值、膨胀、轮廓、矩形打分与 unclip，文字裁剪按 48px 高度归一化后 CTC 解码，按近似行序拼接并保留包围框与置信度。CPU 内部线程 4、跨算子线程 1。模型固定 RapidOCR v3.10.0 的PP-OCRv6_det_small.onnx/PP-OCRv6_rec_small.onnx，合计29.72 MiB，SHA-256 校验，字典从 ONNX metadata 提取；运行时固定 ONNX Runtime Node 1.30.0、OpenCV.js 4.12.0、pngjs 7.0.0、clipper-lib 6.4.2（见 ocr-runtime/package.json）。

各目标离线资源体积（未压缩字节总量，含模型、原生库、JS/WASM、字典与声明）：

资源准备命令：

npm run ocr:prepare # 本机 Windows/Linux 开发 npm run ocr:prepare -- --platform win32 --arch x64 npm run package:win / npm run package:linux # 打包自动调用 beforePack

官方实测记录（macOS arm64、Electron 43.2.0 / Node 24.18.0、8 张固定截图）显示：首轮汉字 0/400 错误、全字符 2/684 错误（0.29%），16 次识别耗时中位数501.5 ms（范围 475–713ms，含进程/运行时/模型加载与清理）；单次打包进程工作集采样峰值约 309.64 MiB。这些来自小型合成语料，不能代表任意真实截图准确率；Windows/Linux 与 arm64 的目标系统实机验收仍在工作流推进中，详见 ppocr-backend.md 及其下的评估 JSON。

七、快速文件预览（Quick File Preview）

日常工具组中的Quick File Preview，命令面板搜索peek/preview/预览。参考 PowerToys Peek 的批量预览与切换交互，但入口是 MooTool 内的文件选择或拖入，不接管系统文件管理器的空格键。

• 每批最多100 个文件，新选择/拖入替换当前批次（超限保留上一批并提示）。
• 通过列表、上一/下一按钮或非文本控件上的左右键切换；文本选择、编码选择与 PDF 页码输入保留自己的按键行为。
• Cmd+F / Ctrl+F在当前文本/JSON 预览中查找字面文本，支持大小写、全词选项、匹配总数与前后跳转、循环提示；Enter 查找下一处，Esc 先关查找栏；查询最多 256 字符，不提供替换或正则。
• 同批往返切换时分别保留每个文件的编码、换行、JSON 格式化、选择/滚动位置、查找设置、图片缩放与 PDF 页码/缩放；缓存只存阅读设置，切换即释放旧内容与 PDF worker，重启不保存。
• 预览只读，仅复制时写剪贴板；不写源文件、图片库、JSON 库、历史或收藏。

格式与限制

文本自动编码 UTF-8 或带 BOM 的 UTF-16 LE/BE，也可显式选择 UTF-8、UTF-16 LE/BE、GB18030；严格解码失败时提示换编码，二进制内容拒绝作为文本展示。HTML、SVG、Markdown 显示源码，不创建页面或外部资源预览。PDF.js6.4.299固定为构建依赖，由 Vite 打包且离线工作（无 CDN、Python 或运行时下载）；仅渲染页面，不执行 PDF JavaScript，密码文档会提示暂不支持。单页 canvas 不超过 800 万像素、单边不超 8192，内部解码图片上限 3200 万像素。完整细节与验证（npm run check、file-preview.spec.ts）见 file-preview.md。

八、开发者翻译

• Split identifier：把getHTTPResponse/user_id拆分为单词后再翻译。
• 短英文翻译时，Copy name提供 camelCase、PascalCase、snake_case、UPPER_SNAKE_CASE、kebab-case，预览即所复制的确切内容。
• Google 与 Bing 保留自动翻译与相互回退。
• DeepL使用你自己的 API key：在设置 → 工具默认 → DeepL API key settings保存，选择 DeepL 后点击 Translate。Key 通过 Electron safeStorage 加密存储，仅主进程读取，不进入翻译历史或普通设置；以:fx结尾的 Free key 走 Free 端点，其余走 Pro。DeepL 请求是显式的，绝不自动回退到其他引擎；长输入被拆分为有界请求，部分失败后重试可能再次消耗配额。

引擎注册表与适配器位于 electron/main/translation/，共享 UI 能力在 translationEngines.ts。

九、AI 集成（MCP / Skill）

1.2.0 起，AI 集成把本地客户端连接到 MooTool 自带的运行时而无需单独安装 Node.js；MooTool 窗口关闭时工具仍可工作。

支持本地 stdio MCP 的其他客户端可用Copy MCP configuration获取配置；生成的可执行路径只对同机客户端有效。MCP 名称为mootool。

快速开始

1. 把 MooTool 安装到固定位置：macOS 应用移入 Applications、Windows 用安装器、Linux 装 deb。AppImage、Windows portable 与 macOS App Translocation 运行时无法注册。
2. 打开设置 → AI 集成，选择客户端与MCP/Skill/MCP + Skill，检查目标与生成内容。
3. 点击一键安装：会先完成 MCP 初始化、工具发现与一次 JSON 调用再写配置，写入前备份已有文件；Test connection可随时验证运行时。
4. 重启 AI 客户端或重新加载 MCP / Skills，按提示启用工具。可尝试提示词："用 MooTool 格式化这段 JSON 并按键排序"。使用已保存内容前，先在 MooTool 开启对应的只读开关。

各客户端安装位置（详见 mootool-ai-integration.md）：

可用工具

前七个工具只处理传入参数，不读文档库；普通文本上限 100,000 字符，结果上限 1 MB，diff 单侧 8,000 字符。工具不访问应用数据库、剪贴板或凭证，不执行 Shell、不发网络请求、不保存调用历史；错误以 MCPisError返回而非伪装成功。MD5/SHA-1 仅用于兼容旧摘要格式。工具参数 Schema 定义见 tools.ts。

只读文档库访问

文档访问默认关闭。在 AI 集成设置中分别开启允许读取随手记与允许读取 JSON 文档，页面显示每个授权目录；授权对所有使用该运行时的本地客户端生效，关闭开关在下一次调用生效，修改库位置会撤销授权。

• 搜索按标题、相对路径或内容匹配，返回相对路径、标题、摘要与修改时间；读取随手记时解析 YAML 元数据只返回正文，JSON 文档返回原文。
• 先搜索再分页读取，nextOffset表示下一页，truncated表示结果未穷尽，应缩小查询。
• 搜索每页最多 50 条、读取每页最多 50,000 字符；单文件最大 2 MB；单次搜索最多检查 4,000 个目录项、读取约 10 MB，目录深度最多 24。
• 排除隐藏路径、符号链接与库根.gitignore忽略的文件；禁止绝对路径与目录穿越。随手记支持.txt/.md/.json/.java/.js/.ts/.py/.xml/.yaml/.yml/.sql，JSON 库仅.json。
• 只读层不创建目录、欢迎笔记或索引。实现见 vaultTools.ts 与 vaultAccess.ts。

CLI 与独立 Skill

独立入口 electron/mcp/index.ts 复用 MooTool 工具函数，不初始化桌面窗口与数据仓库：

mootool-mcp # 以 stdio MCP server 运行 mootool-mcp --list # 输出全部工具 Schema mootool-mcp --call TOOL_NAME # 从 stdin 读取 JSON 参数并调用；isError 时退出码非零

该入口通过 Electron 的ELECTRON_RUN_AS_NODE使用自带运行时（构建时需保留runAsNodefuse）。Skill 安装包含SKILL.md与按安装路径生成的runtime.md；无 MCP 时 Agent 读取后者执行--list获取 Schema，再以 JSON 参数调用--call。调用入口为 Codex 的$mootool或 Claude Code 的/mootool。PowerShell 下会显式等待 GUI 子系统进程完成并检查退出码。

修复、更新与卸载

页面报告每个集成是未安装、已安装、需修复或与用户编辑冲突。移动/升级 MooTool 或丢失 Skill 文件后，从新位置打开应用并点修复 / 更新（用户改写过的条目会被保留，冲突内容先保存或调整）。卸载所选集成只移除所选客户端与方式中由安装器管理的mootoolMCP 项及SKILL.md、runtime.md，其他配置与用户文件保留；卸载某客户端不撤销其他客户端使用的文档授权。写入前备份，不完整变更尽量回滚；重复安装不追加重复项或生成多余备份；预览有效期 10 分钟。安装记录与文档授权保存在用户数据目录的ai-integration/中（默认仅当前用户可读写）。

验收与开发验证

1.2.0 记录了完整的跨平台 CI 验收与 macOS 打包版上真实 Codex CLI 的工具调用完成事件（原始事件见 ai-codex-1.2.0.json）。开发验证命令：

npm run build npm run test npx playwright test tests/electron/ai-integration.spec.ts node out/main/mcp.js --list node scripts/test-packaged-ai.mjs # 打包后验证 ASAR 内 MCP 入口

可设置MOOTOOL_TEST_EXECUTABLE指向打包应用以跑打包版 E2E，设置MOOTOOL_CODEX_EXECUTABLE额外运行真实codex exec验收（保留当前认证、使用临时示例文档、核对mcp_tool_call完成事件）。

十、发布流程

• 发布约定见根目录 RELEASE_CONVENTIONS.md。
• 更新清单与资源选择见 update-products-and-assets.md。
• 每个版本在next/release-notes/{version}.md写一个源文件（现有 release-notes 已积累 1.0.0–1.3.3 的版本记录），再推送next-electron-v{version}标签。
• 发布前 CI 工作流会校验标签、包版本、发布说明、安装包与更新元数据。

工具页面位于src/features/*；文件系统、存储、Shell 与系统能力经electron/preload暴露；独立 MCP 入口位于electron/mcp。桌面发布目标由electron-builder配置管理：macOS 产出 dmg、Windows 产出 nsis/portable、Linux 产出 AppImage/deb，OCR 与原生资源通过extraResources与beforePack钩子按平台/架构注入。

十一、窗口材质与顶部操作栏

设置 → 外观 → 窗口材质提供自动、实色、毛玻璃（vibrancy）与 Liquid Glass 四种选择，并增加沉浸式顶部操作栏（保留各工具自身的沉浸式顶部，不额外加统一标题栏）。

材质解析策略

从 windowMaterial.ts 的resolveWindowMaterial可看到完整决策链：

• 明确选择实色、系统减少透明度/高对比度/强制颜色偏好、或非 macOS 平台 →实色。
• 自动模式在macOS 26+尝试可选的electron-liquid-glass原生扩展（optionalDependencies，见 package.json）；加载或挂载失败回退 Electron vibrancy。
• 较早 macOS 使用 vibrancy；Windows/Linux 使用实色。
• 辅助功能偏好（减少透明度、高对比度、强制颜色）优先于材质选择，并在运行期间实时响应（通过实色原生背景遮蔽，不叠加另一层 vibrancy）。

生命周期与侧栏观感

材质选择在下次启动生效：原生扩展没有公开的移除接口，切换材质不会重建窗口，也不影响未保存编辑器和可拆卸工具视图。独立工具窗口沿用本次主窗口的材质选择，保持同会话一致。

侧栏通过浅色 0.4 / 深色 0.5 的背景 alpha 与平滑明度渐变显露材质，正文与按钮不降低 opacity；工具内容区与辅助窗口保持实色。设置页显示当前实际材质、降级原因与待重启提示。侧栏状态规则集中在 sidebar.css，主题只通过变量定制颜色、圆角、字重，避免重复覆盖；原生材质的透明背景链在 windowMaterial.css，沉浸式工具栏的红绿灯横向安全区与材质状态提示在 windowChrome.css。契约与状态类型见 windowMaterial.ts。浮动控件（边缘拆出/收回按钮、随手记视图切换组等）的玻璃效果由glassControls.css统一管理，是纯 CSS 效果，随保存的材质设置即时切换。

工具拆出时保留同一个 WebContentsView：创建 BaseWindow、连接全屏事件、应用材质后显示；关闭独立窗口仍收回工具，宿主意外销毁时重置子视图材质与全屏状态。验证命令：

npm run check npx playwright test tests/electron/window-material.spec.ts tests/electron/tool-windows.spec.ts

支持直接对打包产物跑 E2E（设置MOOTOOL_E2E_EXECUTABLE指向应用可执行文件并使用独立临时数据目录）。更完整的结构与生命周期说明见 window-material-and-chrome.md。

结语

MooTool Next Electron 以命令面板为效率中枢，把批量重命名、图片缩放、剪贴板转换、离线 OCR、文件快速预览、开发者翻译与 AI 集成串成一个完整闭环：既有本地优先、绝不静默改写数据的严谨边界，又有接入 Codex/Claude Code/Cursor 的 MCP 与 Skill 通道。无论是把它当作日常开发工具箱，还是作为 AI 客户端背后的本地工具运行时，这套实现都在"界面能力"与"系统能力"的分层、参数校验与故障回滚上都给出了可参考的工程范式。需要深入某模块时，README 指向的 doc/ 系列文档与对应源码、测试是最直接的下一站。

• 桌面应用
• 开发工具