用途
baoyu-electron-extract 用于查看已安装的 Electron 应用内部结构,或检查其打包后的代码。当用户希望“提取 Electron 应用”“反编译这个 Electron 应用”“解包 app.asar”“查看某某的源码”时使用。接受应用名称(如 Codex)或绝对路径(如 /Applications/Codex.app、.asar 文件、Windows 安装目录)。脚本会针对 macOS 与 Windows 进行应用发现。
主要能力
- 从已安装 Electron 应用的 app.asar 中提取资源与代码。
- 当存在 .js.map 时,从内嵌的 sourcesContent 还原原始源码文件。
- 当没有源码映射时,使用 Prettier 格式化压缩代码。
- 源码映射路径优先相对 .js.map 文件解析,使 ../../src/main.ts 这类打包路径还原为 restored/src/main.ts 这样的可读路径,而非哈希占位符。
- 始终跳过 node_modules。
- 同时支持 macOS 与 Windows。
使用方式
脚本位于 scripts/ 子目录,{baseDir} 为本 SKILL.md 所在目录路径。运行时解析 ${BUN_X}:若安装了 bun 则用 bun;若有 npx 则用 npx -y bun;否则建议安装 bun。将 {baseDir} 和 ${BUN_X} 替换为实际值。
基本命令:
${BUN_X} {baseDir}/scripts/main.ts "<app>" [--output <dir>] [--asar <path>] [--force]
若不确认发现逻辑能否找到正确包,可先用 --dry-run,它会打印解析后的路径并在不触碰文件系统的情况下退出。
工作流程:
- 确定输入。若用户未提供应用名称或路径则询问;若需自定义输出目录也一并询问。
- 运行脚本。
- 处理结果。成功则报告输出路径与计数(提取 / 还原 / 格式化);若匹配多个则脚本列出候选项并以非零码退出,向用户展示候选项并询问使用哪一个,然后用选定的绝对路径重跑;若输出目录已存在且非空,脚本在无 --force 时拒绝写入,询问用户是覆盖(--force)还是改用新的 --output 路径;若不支持平台或无匹配,建议用户在知道包位置时传入 --asar /full/path/to/app.asar。
- 引导用户查看结果。默认输出目录为 ~/Downloads/<AppName>-electron-extract/。若存在 restored/,说明已从 .js.map 重建原始源码树,应优先阅读;若只有 extracted/,说明 JS/CSS 已在原地用 Prettier 格式化,从此处阅读。
源码映射路径还原规则:
- 每个 sources[] 条目先结合 sourceRoot(若存在)解析,再相对 extracted/ 内 .js.map 文件所在目录解析。
- 将打包器相对路径折叠进还原后的项目树。例如 .vite/main/index.js.map + ../../src/main.ts 变为 restored/src/main.ts。
- 若源码路径爬升到 extracted/ 之上,则将剩余可读路径保留在 restored/ 下而非哈希。例如 .vite/main/index.js.map + ../../../shared/src/lib/foo.ts 变为 restored/shared/src/lib/foo.ts。
- 从源码名中去除 URL/查询装饰,包括常见的 webpack://、file://、?loader 后缀。
- 仅当源码名为空或无法归约为安全文件路径时,使用 restored/__unknown/<hash>.<ext>。
- 继续跳过 node_modules 与 webpack/runtime/* 条目;这些是打包器/运行时噪音,而非应用源码。
用法示例:
按应用名提取(默认输出:~/Downloads/Codex-electron-extract/)
${BUN_X} {baseDir}/scripts/main.ts Codex
按绝对路径提取(适用于 .app 包、安装目录或 .asar 文件)
${BUN_X} {baseDir}/scripts/main.ts "/Applications/Visual Studio Code.app" ${BUN_X} {baseDir}/scripts/main.ts "C:\Users\you\AppData\Local\Programs\codex" ${BUN_X} {baseDir}/scripts/main.ts --asar /Applications/Codex.app/Contents/Resources/app.asar Codex
自定义输出
${BUN_X} {baseDir}/scripts/main.ts Codex --output ~/work/codex-source
仅预览发现结果,不写入任何内容
${BUN_X} {baseDir}/scripts/main.ts Codex --dry-run
覆盖已有输出目录
${BUN_X} {baseDir}/scripts/main.ts Codex --force
机器可读结果(stdout 输出一行 JSON)
${BUN_X} {baseDir}/scripts/main.ts Codex --json
选项:
- <app>:应用名或绝对路径。除非给出 --asar,否则必填。默认无。
- --output / -o:输出目录。默认 ~/Downloads/<AppName>-electron-extract。
- --asar:覆盖解析出的 .asar 路径。默认自动发现。
- --force / -f:允许写入已存在的非空输出目录。默认 false。
- --skip-format:跳过 Prettier 格式化。默认 false。
- --skip-restore:跳过源码映射还原。默认 false。
- --no-unpacked:不复制 app.asar.unpacked/。默认 false。
- --dry-run:打印解析后的路径并在不写入的情况下退出。默认 false。
- --json:在 stdout 输出一行 JSON 摘要(抑制正常输出)。默认 false。
输出布局:
~/Downloads/<AppName>-electron-extract/ ├── extract-report.json # JSON 摘要:计数、警告、解析后的路径 ├── extracted/ # 原始 asar 内容(无 map 时 JS/CSS 用 Prettier 格式化) │ └── ... # node_modules 保持原样(跳过格式化) ├── extracted.unpacked/ # 若存在 <asar>.unpacked/ 则复制 │ └── ... # 原生模块(.node)、大型资源 └── restored/ # 仅当至少一个 .js.map 可用时存在 └── <original/source/tree> # 依据每个 .js.map 的 sourcesContent 重建
适用场景
- 检查已安装 Electron 应用的内部结构与打包代码。
- 在源码映射内嵌 sourcesContent 时还原原始源码树以便阅读。
- 对 Codex、Cursor、Discord、Slack、VS Code、Notion、Obsidian、ChatGPT 桌面端等 Electron 应用进行源码查看。
限制与说明
- node_modules 始终被跳过——源码映射还原与 Prettier 格式化均如此——因为查看应用时内置依赖属于噪音。
- 源码映射还原仅在 .js.map 内嵌 sourcesContent 时有效。这是现代打包器(webpack、esbuild、Vite、rollup)的常见情况。若 map 引用外部 .ts/.js 文件而未内嵌,则该 map 被跳过,对应 .js 改用 Prettier 格式化。被跳过的 map 列在 extract-report.json 的 warnings 下。
- 应用发现:macOS 搜索 /Applications + ~/Applications;Windows 搜索 %LOCALAPPDATA%\Programs、%PROGRAMFILES%、%PROGRAMFILES(X86)%、%APPDATA%。若发现多个匹配,脚本退出并列出它们——需用绝对路径重跑。在 Linux 或其他平台,需显式传入 --asar /path/to/app.asar。
- 安全:脚本拒绝写入 /、用户主目录本身或当前工作目录,且在无 --force 时拒绝填充已存在的非空输出目录。
- 无全局安装——@electron/asar 与 prettier 通过 npx -y 即时解析。首次运行会较慢,因为 npx 需要缓存它们。
- 未提供支持的平台范围之外的平台细节,其他平台需显式指定 .asar 路径。