# 工具链、分发与发布

## 目标组合

TypeScript 用于自有源码、检查与声明生成；Vite/Rollup 保留现有产物能力；Node 继续运行现有测试和必要脚本；Bun 先作为包管理器及脚本入口试点。浏览器消费者不依赖 Bun。

这是项目方向，不是已完成的切换。工具版本必须在 ENG-01 / MOD-01 通过干净环境试点后固定，不能沿用开发机器上偶然存在的传递依赖。

## TypeScript

1. 根目录管理基础配置，核心、插件、工具、构建脚本、worker/Worklet 各自配置环境。
2. typescript 和必要测试工具显式声明为开发依赖。区分本仓库根工具依赖与每个发布包运行依赖。
3. allowJs 过渡，逐包 strict；声明输出保持既有路径，禁止发布内部测试类型。
4. 类型消费者矩阵包含旧支持的最低 TS 版本与选定当前版本，解析方式包含 bundler 和 Node；不能默认借重构抬高最低 TS 版本。
5. docs/assets/ts 的编辑器声明由可验证的生成流程产出；不再依赖简单删除 import/拼字符串保证正确性。
6. 保留直接消费 JS 的例子；TS 是维护手段，不成为用户必须使用的语言。

## Bun 试点

| 步骤 | 检查 |
| --- | --- |
| 依赖基线 | 保存当前依赖和工作区行为，明确唯一锁文件与版本 pin；初次固定锁不夹带大规模升级 |
| 安装对比 | 在独立干净目录执行 Bun 安装，检查 lifecycle scripts、workspace/peer 解析、原生依赖、缓存和许可 |
| 命令对比 | `bun run` 只是脚本入口；脚本中的 node 仍由 Node 执行，不能声称已经换运行时 |
| 构建对比 | 相同版本和源码下构建全部包、文档、worker/WASM，比较包内容与消费者行为 |
| Node 回归 | npm/Node 消费发布包仍通过；现有 node:test 不因包管理器变化被替换 |
| 采用或保留 | 证据充分才改默认文档/CI/锁文件；否则保留 Node 工具链，登记试点结论 |

评估时本机 Bun 1.3.14 直接运行现有测试遇到 node:test mock.fn 不兼容；这是具体版本的观察，未来升级应重测。Bun bundler 不作为本轮替换目标，因为需要保留 UMD、legacy 语法降级和现有资源处理。参考：[Bun bundler](https://bun.com/docs/bundler)、[workspaces](https://bun.com/docs/pm/workspaces)、[lifecycle](https://bun.com/docs/pm/lifecycle)、[TS allowJs](https://www.typescriptlang.org/tsconfig/allowJs.html)。执行时重新核对官方文档。

## 构建改造

- 当前 scripts/build.js 和 dev.js 写死 src/index.js；迁移时支持 JS/TS 入口及非交互指定包，并保留旧交互调用。
- 保留现代 UMD、legacy UMD、ESM、banner、全局名称、AMD 处理、Less/SVG 与 worker 行为。
- 统一内部构建配置不代表统一公开文件名。thumbnail tool 的 .esm.js 等历史路径必须有生成兼容产物或明确核实结论。
- 区分源码构建、类型、文档、测试和站点部署；禁止验证步骤顺带修改源码或推送 gh-pages。
- 移动文件不要与改变运行行为同时铺满全仓库；每次检查 imports、exports、demo URL 和产物。
- Lerna independent 版本模式保持。是否移除安装/链接脚本要先确认作用，不能因 workspaces 存在就直接删除。

## 发布流程

1. BASE-01 确定旧核心和插件的支持矩阵，登记 npm tarball integrity。起点 SHA 不能代替消费者产物基线。
2. REL 阶段为每个发生变化的包生成候选 tarball，用隔离消费者验证，无需先公开发布。
3. 决定独立版本号、变更日志和包依赖；纯内部兼容重构不自动提升全部包 major，也不自动把所有包改成同一版本。
4. 预发布 tag、npm 发布、站点部署及推送属于后续实际发布步骤；当前仅创建本地分支与文档，不执行这些动作。
5. 经授权后按风险批次发布候选版本。优先简单包，再核心兼容候选，最后高风险生态包；不要求用户同时升级整个生态。
6. 收集有复现步骤的反馈，与旧版本 A/B 对照。达到记录好的验收条件后才能更新正式 tag；不设无依据的自动等待天数。
7. 记录发布后的 tarball integrity、版本组合、测试、已知限制和回退版本。

## 回退与维护

- 不删除旧包版本和历史 CDN 文件。包回退通过恢复已验证版本/tag/锁定依赖；不把 unpublish 作为默认方案。
- 核心和插件可分别回退；候选插件不得只能依赖尚未广泛发布的新核心内部方法。
- 在发布清单中维护每包的旧版本、新版本、依赖范围和消费者回退命令。
- 保持 master 的必要修复，并记录如何同步到重构分支；发布前重新建立准确差分基线。
- 新漏洞、外部 SDK 不兼容和类型破坏单独记录，不能藏在“代码整理”变更日志里。