本项目当前依赖的 xterm.js 不能直接使用官方最新发布版本。
原因是：官方已发布版本存在项目当前无法接受的 bug，而对应修复虽然已经出现在上游 master 代码中，但修复后的正式版本尚未发布。
因此，本项目现阶段必须采用以下方式使用 xterm.js：
- 基于上游
xterm.js master源码自行打包； - 将打包产物放到本项目
package.json已经约定好的依赖位置； - 绝对不能为了适配本地环境去修改本项目的
package.json。
以下规则是本项目关于 xterm.js 依赖的强制约束，所有开发者都必须遵守：
- 禁止修改
package.json中的xterm.js依赖声明。 - 禁止把
@xterm/xterm或@xterm/addon-fit改成其他版本号、其他文件名、其他本地路径或 npm 官方版本。 - 必须将自行打包得到的 tgz 包放到
package.json当前依赖所指向的固定位置。 - 如果你打出来的包名与当前依赖约定不一致，应该重命名或替换产物到既定位置，而不是修改
package.json。 - 在项目明确完成依赖升级决策之前，这个约束长期有效。
本项目当前在 package.json 中固定引用了以下两个本地包：
@xterm/xterm→file:vendor/xterm/xterm-xterm-6.0.0-custom.tgz@xterm/addon-fit→file:vendor/xterm/xterm-addon-fit-0.11.0-custom.tgz
这些包文件已经提交到项目仓库的 vendor/xterm/ 目录中，确保 CI/CD 环境和所有开发者都能正常构建。
项目目录结构：
synapse/
├─ vendor/
│ └─ xterm/
│ ├─ xterm-xterm-6.0.0-custom.tgz
│ └─ xterm-addon-fit-0.11.0-custom.tgz
├─ package.json
└─ ...
当需要更新或重新生成 xterm.js 依赖包时，必须按下面的原则操作：
- 从包含目标修复的上游
xterm.js master源码进行构建和打包。 - 产出
@xterm/xterm与@xterm/addon-fit对应的 tgz 包。 - 将打包结果复制、移动或覆盖到项目的
vendor/xterm/目录。 - 提交更新后的 tgz 包文件到代码仓库。
- 确认
package.json没有因为本次操作发生任何改动。
一句话原则：改包文件，不改依赖声明。
以下做法都不允许：
- 为了使用新打出的包，直接修改
package.json中的文件名或路径。 - 把本地临时目录、个人电脑专用路径或其他任意路径写入
package.json。 - 因为官方最新版有 bug，就临时把依赖改回 npm 官方发布版本。
- 通过修改依赖声明让“只有自己机器能工作”，破坏团队统一约定。
- 未经项目明确决策，就擅自把这套约定替换成新的接入方式。
这样约束的目的，是保证以下几点：
- 项目始终使用包含修复的
xterm.js自行打包版本； - 团队成员之间的依赖接入方式保持一致；
- 任何人在遵守约定的前提下，都能正常执行安装、构建和打包；
- 避免因为修改
package.json导致环境漂移、路径不一致或后续协作问题。
只有在以下条件同时满足时，才可以考虑调整这套约束：
- 上游正式发布了包含所需修复的稳定版本；
- 项目明确决定切换到新的正式版本；
- 对
package.json、必要的锁文件以及本文档进行一次完整且一致的更新。
在此之前，默认规则始终是：继续使用基于 master 自行打包的产物，并保持 package.json 不变。