辅助脚本与副作用

docs/ 为维护者本地资料，不随 GitHub 仓库提供；下文本地资料路径仅供已有资料时参考，不是构建或使用前提。

文件地图

• set-version.mjs：同步已确认的新版本声明和变更日志；先完整预检，不构建或提交。
• check-dependencies.mjs：逐项核对实际依赖与锁文件；只读，可检查独立依赖目录。
• build-update-packages.mjs：在全新本地目录依次检查、构建和生成两端完整程序 ZIP，输出大小/哈希，不签名、不上传；流程见 UPDATES.md。
• check-update-package.ts：用真实更新器解压刚构建的 ZIP，验证应用身份、版本和架构；仅写临时目录，不安装或启动。已接入在线包构建门禁，不能以该检查代替系统实机更新。
• dev.ts：启动 Vite 和 Electron；启动前依次构建主进程与加载项部署入口（build:main + build:addons）。
• prepare-update.ts：离线复制并重新校验已验收的包，使用调用方提供的已有 Ed25519 私钥签名清单，只写新的本地目录；不生成密钥、不上传、不覆盖输出。信任配置、Nginx 目录映射与先包后清单发布顺序见更新指南。
• prepare-upgrade-acceptance.mjs：按本地 A/B 计划把公开输入复制到全新验收目录，只在副本写入测试版本/清单、独立应用身份/用户数据/端口与禁止宿主配置写入的隔离覆盖，并记录逐文件前后指纹；不读取私钥、不安装、不部署。根工作区版本和正式更新源保持不变。
• windows-update-preflight.ts：构建成独立 CJS 后由 Windows 已安装 Electron 的 Node 模式运行；只写临时合成安装目录和脱敏 JSON 报告，验证短路径/junction、12 进程单次授权、撤销/重试和签名交接。使用临时测试密钥，不读取生产密钥，不安装、不联网、不替代完整 Windows CI 或 GUI 升级验收。
• build-windows-update-preflight.mjs：将上项打成独立离线检查文件及双击 CMD，固定本次测试运行时哈希和源码指纹，只写全新输出目录；命令见 UPDATES.md。不把诊断工具放入正式程序包。
• windows-update-handoff-probe.ts、build-windows-handoff-probe.mjs：对已安装的独立 Windows 验收 A 创建新诊断票据，先验签验包，再运行原包自带助手、采集退出码/准备回执/脱敏错误；始终不创建 grant，结束撤销新票据，只停止自己启动的助手。不安装、不清理旧记录、不改安全策略；生成到全新目录，不进入正式程序包。
• lib/diagnostic-report.mjs：把调用者已脱敏、有界的报告同时写入标准输出与独立 JSON；文件写入失败仍在 CMD 控制台日志保留 JSON 和错误码。CMD 不向运行时传递带尾部反斜杠的引号目录参数，脚本默认使用自身目录；回归见 diagnostic-report.test.ts。
• lib/update-probe-paths.ts：只用于诊断的缓存归属比较；先拒绝链接/硬链接，再对缓存和包同时作 native 物理路径解析以兼容 Windows 短长名，重放仍保留原 GUI 路径拼写。票据验证在独立子进程执行，不能为诊断删掉生产 parentPid 防护；旧票据只借用签名上下文，新建 nonce/时间且永不授权。回归见 update-probe-paths.test.ts 与 update-install 的独立 PID 用例。
• init-update-signing-key.mjs：仅显式初始化项目内 Git 忽略的本地生产更新密钥；先核对排除规则，排他创建，已有密钥只复用/校验，不轮换、不覆盖、不输出私钥。构建不得调用它。
• check-update-secrets.mjs、lib/update-key-safety.mjs：本地签名目录的 Git/归档/应用包/发布白名单门禁；可显式扫描目录、ASAR、ZIP、tar/tgz 的路径及生产私钥字节，报告只有计数和通过状态，不输出材料。私钥不能作为构建输入，扫描器只读校验。
• inspect.ts：启动服务并探测宿主。
• verify-all-mcp-tools.ts：访问真实 Microsoft 宿主的工具验证。
• verify_all_tiers.ts：真实 Bridge 集成操作。
• build_beautified_sheet.ts：真实表格写入与排版。
• create-icons.mjs：生成图标文件。
• check-agents.mjs：只读检查协作导航。
• check-version.mjs：以 package.json 为基准，只读核对锁文件、Bridge、加载项源码/清单、界面默认值和 CHANGELOG；npm run check:version 已接入 prebuild、beforePack 与 CI，不同步版本或执行发布。制度见 release-policy.md（本地 docs/release-policy.md）。
• check-brand.mjs：只读检查当前文本与相对路径中的旧品牌标识；历史验收及既有发布包例外，构建输出和发布副本分别检查。范围见 品牌声明（本地 docs/branding.md）。
• snapshot-tools.ts：只读导出工具契约与能力快照（npm run snapshot:tools）。
• check-capability-claims.ts：只读核对 skill、官网与加载项页面中的能力数量表述与元数据源（npm run check:claims）。
• check-param-forwarding.ts：只读核对"schema 声明了参数、网关处理器却没读取"的静默丢参（npm run check:params）；带自检，证明能抓到未转发参数且读过的不误报。
• build-win-icon.mjs：由 build/icon.png 生成 Windows 用的多尺寸 build/icon.ico（npm run build:win-icon）；纯 Node 实现（自带 PNG 解码/缩放/编码与 DIB 封装），写完自检格式，不通过不落盘。
• build-windows-bootstrap.mjs、pack-windows-bootstrap.mjs：Windows 专属；从已验收 ZIP、应用源码完整 SHA、引导源码完整 SHA 生成独立 Electron 引导，再由 portable NSIS 打成用户权限 EXE。品牌输入固定在 windows-bootstrap/assets（源自 website/public/character）；不运行安装、不改 Mac、不部署。详细命令和产物见 双平台发布路径（本地 docs/windows-bootstrap.md）。
• lib/windows-portable.mjs：锁定 builder 25.1.8 和 portable 模板指纹，在本次编译输入 .onInit 中显式初始化插件目录，无外壳 splash；适配器仅在 pack 进程临时挂接并在 finally 恢复，不修改 node_modules。模板或编译接口变化须停止重审。
• dist-parallel.mjs：现有双平台并行入口（dist:all / dist:fast）；两平台虽输出到不同目录，beforePack 仍增删共享发布副本的 CLI 回退文件。副本隔离前正式验收构建须串行，见 发布制度（本地 docs/release-policy.md）；不要把输出目录不同当作共享输入安全的证明。
• build-cli-bytecode.mjs：把 dist/bridge/cli.cjs 编译成 V8 字节码 cli.jsc，并把 cli.cjs 就地替换为加载器（npm run build:bytecode，已串进 npm run build）。必须用 Electron 的 Node 编译（V8 版本与运行时锁死）。详见 code-protection.md（本地 docs/code-protection.md）。
• check-cli-protection.mjs：旧命令兼容入口，委托包级检查，不移动开发文件或连接默认用户服务。
• build-release-assets.mjs：仅生成 dist/release-app/ 发布副本；输入白名单见 release-files.json，保护策略与过期校验见 lib/release-protection.mjs。
• check-release-protection.mjs：校验最终 ZIP/ASAR，底层见 lib/check-release.mjs。
• before-pack.cjs、after-pack.cjs、after-artifact.cjs：打包前防过期、包内/解包路径检查、最终 ZIP 哈希证据。
• probe-release-mcp.mjs：隔离运行发布 CLI，比较完整工具契约、提示词、能力资源；只使用临时 HOME 和随机端口，关闭自己的子进程，不控制真实宿主。
• probe-mcp-tools.mjs：以 stdio 启动 cli.cjs 做一次 MCP 握手、只输出工具数量；供上面的校验脚本复用。
• sync-addon-panel-style.mjs：从 Office 唯一样式源生成 WPS 自包含 CSS，加载项构建自动同步，--check 只检查一致性。
• build-wps-ribbon-icons.mjs：从 App 原图生成 32px / 64px @2x 工具栏资源，主加载项构建自动调用，--check 只校验。
• build-wps-addon.mjs：由 wps-addon/src/** 生成含后台与侧栏两种运行模式的部署入口 wps-addon/addon-core.js（npm run build:wps-addon，--check 只校验）。
• lib/wps-addon-modules.mjs：构建器共用的递归源码枚举与双向清单校验；只读，不导入加载项片段。显式清单决定拼接顺序，目录枚举只检查遗漏、缺失和重复。
• build-office-addon.mjs：由 office-addon/src/** 生成部署入口 office-addon/public/taskpane.js（npm run build:office-addon，--check 只校验）。

定位与联动

先看脚本入口、目标、连接地址和写操作，再决定能否运行。命令入口见 package.json。

双平台构建入口

公开仓库不提供本地 docs/，平台构建以本节和实际脚本为准：

• macOS arm64：npm run dist:mac 生成 release/<版本>/mac/ 内的 ZIP 和解包应用；发布前用 node scripts/check-release-protection.mjs <实际ZIP路径> 核验。不能套用 Windows 引导命令。
• Windows x64 载荷：npm run dist:win 先生成 release/<版本>/win/ 内的应用 ZIP；它同时用于客户端在线更新、引导载荷和备用交付，不包含品牌配置界面。
• Windows 当前用户引导：在隔离构建目录中执行 node scripts/build-windows-bootstrap.mjs <已验证WindowsZIP> <应用源码完整SHA> <引导源码完整SHA>，再执行 node scripts/pack-windows-bootstrap.mjs。输入 ZIP 必须先通过包级检查；产物为 dist/windows-bootstrap/artifacts/CharFloat-<版本>-win-x64.exe。脚本使用 windows-bootstrap/assets/，不依赖本地官网或 docs/。必须重新生成 stage，不能复用旧 main.cjs。
• 验证与发布：分别运行版本、导航、能力声明、类型、构建与单测门禁；Windows 引导另用完整 Electron 执行 tests/windows-bootstrap-electron.cjs <payload.zip> <manifest.json> <新report.json>，并单独验证 UI、外壳、普通用户路径和 Windows 实机行为。模拟测试不能代替实机；不得自动发布、覆盖正式版本或移动标签。发布需有用户授权，并记录两个源码 SHA、产物哈希与验证范围；本地诊断包和用户日志不得上传。

修改边界

文件名带 inspect/verify 不代表只读；实际宿主脚本不能作为普通单元测试执行。不要沿用示例里写死的端口、认证和目标。新增脚本说明输入、输出与副作用，避免打印凭据。

验证

导航检查用 npm run check:agents；能力声明一致性用 npm run check:claims（两者都只读）。加载项构建用 npm run build:addons（会覆写部署入口，属写操作但只写生成物）。其余按实际副作用选择隔离环境和验证方式。

避坑

Windows 包 exe 图标显示空白 → 只看"RT_GROUP_ICON 条目数够不够"会得出错误结论：条目数量正确、图标画面正确，仍然可能不显示 → 已证实原因：Windows 只对 256×256 支持 PNG 内嵌条目，小于 256 的条目必须是 BMP(DIB)；全部用 PNG 时资源管理器的小/中/大图标视图拿不到可解码的条目 → 正确做法：<256 写 32bpp DIB（BITMAPINFOHEADER 40 字节 + 自下而上 BGRA + 1bpp AND 掩码），256 写 PNG，与原版 electron.exe 的资源结构一致 → 由 build-win-icon.mjs 生成并在写完自检，npm run dist 已串联该步 → 校验方法：用 resedit 读 exe 的 RT_ICON，逐条判断是 DIB 还是 PNG（对照 win-icon.test.ts）。另注意 PE 版本资源是 UTF-16LE，strings -a 只找 ASCII 会漏判。

直接手改 wps-addon/addon-core.js 或 office-addon/public/taskpane.js → 下次构建即被覆盖，且源码与部署产物不一致 → 两者都是生成物（顶部有"请勿手改"） → 改 */src/** 后跑对应构建 → --check 模式可检出漂移。

能力文案检查只看 skills/ 与官网 → 加载项页面这类手写文件里的数量文案会漏网 → 已证实：office-addon/public/taskpane.html 长期显示"42 项能力已就绪"，与四个口径（路由 30 / 对外工具 91 / WPS 26 / Microsoft 27）都对不上，并随发布包出厂；生成器只产 taskpane.js，检查器既不扫该目录、模式也不含"N 项…能力" → 扫描范围加入 office-addon/public 与 wps-addon，模式加入 (\d+)\s*项[^，。；、\n]{0,16}?能力；文案里的宿主必须写明（写 Microsoft Excel，不能只写"Excel"），否则按"未指明宿主"报错 → 反向验证：把 27 改回 42 即 exit 1。

直接执行 verify 脚本 → 可能修改真实文件 → 先检查请求列表和目标 → 使用明确测试文档并读回，不能靠脚本名称判断安全性。

用本机 node 编译 V8 字节码 → 在 Electron 里加载即失败 → 字节码与 V8 版本锁死（实测本机 V8 14.1 / Electron V8 13.4）→ 必须用目标运行时的二进制编译（ELECTRON_RUN_AS_NODE=1 node_modules/electron/dist/...），并把编译时版本写进加载器；版本不符时报可操作错误而不是 undefined → build-cli-bytecode.mjs。

编译字节码前不删旧文件 → bytenode 按输入文件名产出（cli-full.cjs → cli-full.jsc），产物缺失时会被上一轮的陈旧文件蒙混过关，打出来的包跑的是旧代码 → 编译前先 unlink 目标，编译后校验再改名。

以为"加了 minify 就没有源码了" → 注释和函数名没了，但逻辑仍可读；而且明文产物（cli-full.cjs）若没进 build.files 的排除清单，等于白做 → 排除清单与保护手段必须同时到位 → check-release-protection.mjs 的包内检查。

给 esbuild 的 minify 加 mangleProps → 连 args?.workbookName 这类属性名一起改名，双宿主靠属性名对接，功能全废 → esbuild 默认不重命名属性名，不要开这个开关。

只验证"构建成功"就发布代码保护改动 → 字节码不会因构建失败而失败：它只会在运行时加载不了 → 必须验证「把明文包临时移走仍能跑」，才证明真的走字节码而非悄悄回退 → probe-release-mcp.mjs 只接受无明文回退的发布入口。

只验证 app.asar 里的内容就认为打包没问题 → 实际跑不起来、且全平台都挂（不只是出问题的那个平台）→ src/main/index.ts 会把入口重定向到 app.asar.unpacked，而 asarUnpack 是按文件名逐个列的：漏列 cli.jsc 或 bytenode 就缺文件/缺模块，进程起来即死，主进程等 6 秒后报"后台启动失败" → 新增可执行文件后必须同步 asarUnpack，并用安装器实际使用的那条路径跑一次 → lib/check-release.mjs 的 unpacked 检查。

只比 V8 版本号就认为字节码可用 → Windows 上仍报 Invalid or incompatible cached data (cachedDataRejected)，界面表现是「后台启动失败」且 service.log 为空（V8 在原生层中止，不抛 JS 异常）→ V8 字节码的缓存头除版本号外还含平台/编译配置的 flags hash，macOS 与 Windows 都是 V8 13.4 也不通用；加载器必须真正 try 一次并在失败时回退，不能只做版本比较 → build-cli-bytecode.mjs 的加载器模板；兜底策略见 before-pack.cjs。

Windows 包没有明文兜底（这是有意保留的设计，不是待办——2026-09-23 使用者已拍板：Windows 侧就用 minify，不配 Windows 构建机）→ 字节码被拒后无处可退，直接起不来 → 在 macOS 上无法生成 Windows 的字节码（跑不了 PE），只能让 Windows 包附带 dist/bridge/cli-full.cjs，由加载器回退；代价是 Windows 侧保护降为 minify → before-pack.cjs 按平台增删该文件，校验侧用 allowPlainCli 放行（只放行这一个文件），macOS 侧仍移除它 → release-protection.mjs 的 checkFiles。

cli-full.cjs 只放进 asar、没解包 → 加载器在 __dirname（解包目录）里找不到它，回退静默失效 → asarUnpack 是按文件名逐个列的，必需文件不在清单里就只进 asar → 新增运行文件必须同步 asarUnpack，并用安装路径实跑一次 → check-release.mjs 的"Windows 明文兜底未解包"断点。

重复执行 build:bytecode 而不先重建明文包 → 上一次的加载器被当成源码编译，产出 1 KB 的假字节码，构建照样"成功"，但打出的包必然起不来 → 脚本开头校验输入 cli.cjs 是否为明文包（含 require('bytenode') 即判为加载器并拒绝） → build-cli-bytecode.mjs。

发布副本不先清空就重建 → beforePack 会按平台往副本里增删文件（Windows 加明文兜底、macOS 移除），上一轮 Windows 留下的兜底文件让本次 verifyStage() 直接报「禁止发布」，看起来像源码问题 → 重建前 rmSync(STAGE) → build-release-assets.mjs。

同步维护

文件入口、职责、调用关系或验证方式变化时同步更新本页；新增已证实的重复问题时补充原因、处理方式及证据。其余遵循根目录协作规范。