English | 简体中文

“代码存在”“Demo 能跑”“npm dry-run 成功”“包已发布”是不同状态。本仓库的发布流程把类型、 行为、浏览器构建、隐私门禁和真实 tarball 消费验证拆开，任何一步失败都不能用下一步替代。

1. 本地命令矩阵

Command 验证内容 是否修改外部状态
pnpm typecheck library、examples、React、Vue 类型诊断 否
pnpm test Vitest 单元/集成测试 否
pnpm test:coverage 测试 + 覆盖率阈值 否
pnpm build:lib ESM、CJS、types 只写本地 dist
pnpm demos:build 六个无 Vite demo 只写本地 build
pnpm docs:check Markdown 本地链接 否
pnpm guard:public 仓库/教材敏感信息扫描 否
pnpm guard:package npm 精确文件列表和 tarball 文本门禁 仅 dry-run
pnpm smoke:package pack、临时目录安装、真实 consumer 验证 仅本地临时目录
pnpm release:check 组合全部发布门禁 不 publish

npm publish --dry-run 也不会发布。只有 maintainer 明确执行真实 npm publish，并且 registry 能够查询到该版本，才能标记为“已发布”。Git commit、push、npm publish 和站点部署同样是四个 独立动作。

2. 测试覆盖的契约

当前测试分层：

Area 关注点
Camera + WorkingSet 坐标换算、zoom、overscan、exit grace、pin
Document + Runtime revision commit、索引同步、可见挂载、destroy
Command + Agent 事务、幂等、Undo/Redo、上下文裁剪、远程 policy
ResourcePool + LOD 并发去重、lease、LRU、硬拒绝、tier hysteresis
Canvas2D hydrate/update/dehydrate/draw/export 生命周期
IndexedDB snapshot、workspace 原子性、history revision、asset blob
React / Vue mount 创建、unmount destroy、ref 生命周期
Server gateway auth、endpoint 规范化、SSRF/IP、body/response 限制
Course validator frontmatter、demo registry、Markdown 安全边界
Package factory 组合默认值、恢复、重复 destroy

覆盖率是最低回归门禁，不是质量结论。配置的全局阈值：

statements >= 65%
branches   >= 60%
functions  >= 70%
lines      >= 70%

高风险修改仍要增加对应行为测试。例如修改 cache eviction，必须覆盖 active lease 不可淘汰； 修改 history restore，必须覆盖 revision mismatch；修改 Agent proxy，必须覆盖 DNS/IP 与 redirect。

3. Demo 验证

pnpm demos:build
pnpm demos:serve
# open http://127.0.0.1:4174/

浏览器验收不是“页面打开”即可：

  • Vanilla/React/Vue：新增节点后 Document revision、node count、renderer count 合理。
  • Legacy Konva：平移后 Document 总节点不变，mounted group 随视口变化。
  • Cache-only：同 key 并发 acquire 只触发一次 loader；全部 release 后可 eviction/dispose。
  • Host Agent：合法计划一次 commit；业务 policy 拒绝时 revision 不变。
  • 全部页面：Console 无 error/warning，交互后没有持续增长的未释放对象。

Demo 的详细讲解见 examples/projects。

4. Public leak guard

guard:public 扫描仓库和显式候选目录中的文本文件：

  • 经过 hash 治理的业务禁止标识符；
  • macOS/Linux/Windows 用户绝对路径；
  • npm、OpenAI、GitHub、AWS 等凭证形状；
  • private key；
  • 私网地址和内部主机位置；
  • 个人邮箱、手机号和身份号码；
  • 宿主专属 import；
  • 跨 root 的相对 import。

命中结果只输出路径、错误码和脱敏说明。它是发布门禁，不是专业 secret scanner 的替代。 Git hosting 应继续启用 secret scanning 和 push protection。任何命中都应先移除并轮换真实 凭证，不能只把正则改弱。

源码归并必须先把有限、已通用化的候选放进临时目录，并用 --extra-root 扫描；禁止把私有消费 仓库整树反向复制进公共仓库。人工审查仍要排除产品 Schema、账号/Provider 行为、真实私有 Fixture、内部端点，以及与框架无关架构无关的代码。

5. Package guard：检查真正要发布的文件

guard:package 调用：

npm pack --dry-run --json --ignore-scripts

它不猜 .npmignore 最终会产生什么，而是读取 npm 计算出的精确 file list；随后执行 allowlist、 credential filename 和 packed text 扫描。只有以下内容允许进入包：

  • dist/ ESM + types；
  • dist-cjs/ CommonJS；
  • LICENSE、package.json、英文与简体中文包 README；
  • 白名单中明确列出的英文与简体中文 SDK 专题文档。

教材生成/部署/维护者文档、examples workspace、server、.env、.npmrc、coverage、截图和 私有参考路径不进入 npm tarball。

npm 凭证绝不能写入公开项目：

  • 本地使用用户目录中的 npm login；
  • CI 使用平台 secret store 注入短期 token；
  • 不提交含 _authToken、_auth、_password 的 .npmrc；
  • 日志不打印 token 或完整 Authorization header。

6. 隔离安装 smoke

smoke:package 执行真实 consumer 流程：

  1. 在临时目录 npm pack 生成 tarball；
  2. 新建最小 package.json；
  3. npm install <tarball> --omit=optional；
  4. 用 strict NodeNext TypeScript 编译自定义 node、Agent policy、persistence 示例；
  5. 分别通过 ESM import 与 CommonJS require 加载 root/agent/cache/persistence；
  6. 链接可选 peer 后验证 canvas2d/konva/rbush/indexeddb/react/vue subpath；
  7. 删除临时目录。

这能发现 workspace link 掩盖的 exports、types、CJS 或 peer 问题。只在仓库内跑单元测试无法 替代这一步。

7. release:check 顺序

发布门禁按以下顺序 fail fast：

  1. guard:public；
  2. 若设置教材根，lesson:validate；
  3. docs:check；
  4. typecheck；
  5. test:coverage；
  6. library build；
  7. 六个 demo build；
  8. guard:package；
  9. 隔离 package smoke。

建议保存每一步输出作为 release evidence。失败后只报告真正达到的状态，例如“代码与测试通过， tarball smoke 失败”，不能概括为“发布完成”。

8. SemVer 与扩展兼容性

以下变更通常需要 major：

  • 修改 CanvasNode、RendererPort、DocumentStore、SpatialIndex 必需字段/方法；
  • 删除/重命名 exports 或 subpath；
  • 改变 revision、commit、idempotency、history restore 语义；
  • 改变 ResourcePool lease/dispose 所有权；
  • 放宽 Agent parser 后又让既有合法输出失败。

向后兼容的新 optional API、新 adapter 和新可选 policy 字段通常可以 minor；只修内部 bug 且 不改变公共契约通常是 patch。任何版本都要补回归测试与迁移说明。

9. Maintainer 发布清单

  • 工作区只有本次发布范围内变更。
  • README/docs/demo 与真实 API 一致，文档链接通过。
  • 版本号与 CHANGELOG/发布说明一致。
  • release:check 通过。
  • npm pack --dry-run 文件列表人工复核。
  • 没有 npm key、模型 key、私有路径或业务 schema。
  • 使用最小权限、可轮换 token。
  • 真实 publish 后从空目录按 registry version 安装一次。
  • registry 查询版本、provenance/签名与 dist-tag。
  • Git commit/push/tag、npm publish、站点部署分别记录状态。