npm 发行产物、原生模块与平台限制
产物布局
npm run pack:npm 构建 Agent SDK 和桌面应用，输出 .tgz 到 release/npm/。SDK 将内部运行时打包并生成独立类型声明；桌面包收集 bin、dist、scripts、README 和 NOTICE。Quick Chat 在独立仓库构建并发布 npm 包。
桌面 CLI 设置 ZPI_NPM_LAUNCH=1，通过 Electron 运行包内的 dist/main/index.js。Electron、node-pty 和 Sharp 是 npm 运行依赖，内部 workspace 模块已包含在构建中。用户不需要源码仓库或本地构建。
主 renderer、preload、history/diff workers、PDF.js 资源以及 CSS、字体和媒体都必须随构建产物存在。开发服务器路径不能泄漏到发行配置中。
Electron 与原生 ABI
npm 安装需允许依赖安装脚本下载 Electron 运行环境；桌面包的 postinstall 为 macOS 的 node-pty spawn helper 补齐执行权限。源码开发依赖显式 install:terminal 提前重建 node-pty。升级 Electron 或切换架构后重新准备，不能沿用 Node 自身 ABI 的二进制。
Sharp/@img 的二进制选择与平台/架构有关。能在开发目录 require 成功，不代表 npm 安装后的依赖满足目标平台；需要在安装后的 npm 包中验证启动、媒体和终端。
正式与 Preview
npm 启动使用正式版 ZPI 数据目录，正式 appId 为 local.zpi.desktop。开发模式采用 Preview 身份 local.zpi.desktop.preview；Preview 数据和钥匙串行为需按开发指南理解。
根应用 version 与 workspace 支持包版本是不同字段；发布补丁版通常修改应用版本及 lockfile 对应根记录，不应无理由重写所有内部包版本。
许可和分发
第三方必要署名与许可原文保存在 licenses/third-party-notices.txt，SDK 和桌面构建脚本将其复制为各自包内的 NOTICE，随 npm 包分发。减少 README 内容不会取消分发时需要随包保留的文本。
当前限制与验收
桌面端不支持 Windows：npm 包通过 os: ["!win32"] 拒绝 Windows 安装，CLI 在加载 Electron 前拒绝 Windows 启动，源码不再提供 Windows 打包目标。当前主要在 macOS Apple Silicon 上验证，其他平台的原生依赖和运行行为仍需验收。Quick Chat 当前仅支持 macOS arm64。
此限制仅作用于桌面端。Agent SDK 保持跨平台，Windows 的 Bash 查找、路径归一化与进程清理保留在共享运行时中；共享 UI 的外来路径识别、BMP/ICO 解析也不因桌面端平台限制而移除。
发布前检查 npm 包内容并执行适用桌面测试。版本号、数据 schema、transcript version 分别管理；旧程序遇到未知新 schema 应拒绝，而非自动降级覆盖数据。