u-space

Appearance

一键发布 ​

仓库提供一个手动 GitHub Actions 工作流，一次发布四个交付面：

  1. u-space npm 包
  2. u-space-mcp npm 包
  3. VitePress 文档
  4. /examples/ 在线示例

npm 发布使用 Trusted Publishing/OIDC，不保存 NPM_TOKEN，日常发布不再要求输入 OTP。docs 和 examples 使用同一个 Vercel production deployment；scripts/build-vercel-docs.mjs 会在文档构建完成后复制 examples/，将发布中的 u-space 版本写入部署产物的 import map，并用独立 Vite 构建将 Offscreen 示例转换为浏览器可直接执行的主线程 JavaScript、module Worker 和 WASM 资源。

一次性配置 ​

1. 配置两个 npm Trusted Publisher ​

分别打开 npmjs.com 上 u-space 和 u-space-mcp 的 package settings，在 Trusted Publisher 中添加相同的 GitHub Actions 配置：

字段值
Organization or userspatial-claw
Repositoryu-space
Workflow filenamerelease.yml
Environment留空
Allowed actionsnpm publish

两个包都必须单独配置一次。工作流运行在 GitHub-hosted runner，授予 id-token: write，使用 Node.js 24 和满足 Trusted Publishing 要求的 npm 11；package metadata 中的 repository URL 已统一为 https://github.com/spatial-claw/u-space。

配置成功后不需要创建 NPM_TOKEN。npm 官方也建议在验证 Trusted Publisher 可用后，将传统 publishing access 调整为 “Require two-factor authentication and disallow tokens”。

2. 配置 Vercel Token ​

仓库已经提交 .vercel/project.json，因此 GitHub Actions 只需要一个 repository secret：

bash
gh secret set VERCEL_TOKEN

输入有权部署 u-space Vercel 项目的 token。工作流会依次运行 vercel pull、vercel build --prod 和 vercel deploy --prebuilt --prod。

工作流已经显式声明 contents: write 和 id-token: write。因此组织或仓库可以继续保持默认的只读 GITHUB_TOKEN 权限；GitHub 会按该 workflow 的最小权限声明授权。工作流需要把版本提交和 release tags 推回 main，如果 main 启用了 branch protection，还需要允许该 release workflow 写入，或为 github-actions[bot] 配置对应 bypass。

发布 ​

默认递增两个 npm 包的 patch 版本，并等待 GitHub Actions 完成：

bash
pnpm release:all

也可以显式选择版本级别：

bash
pnpm release:all patch
pnpm release:all minor
pnpm release:all major

不想在本地等待时使用：

bash
pnpm release:all patch --no-wait

也可以打开 GitHub 仓库的 Actions → Release all → Run workflow，选择 patch、minor 或 major 后运行。

发布顺序 ​

工作流按以下顺序执行：

  1. 递增 u-space 和 u-space-mcp 版本，同步 examples/docs 中的当前版本引用；将更新日志的“未发布”内容归档到新的 X.Y.Z 版本标题，并创建新的空“未发布”区。
  2. 执行完整测试、库构建、MCP 文档索引构建和 VitePress 构建。
  3. 将版本元数据提交并推送到 main。
  4. 通过 npm OIDC 发布两个包；精确版本已经存在时自动跳过。
  5. 构建并部署 docs 和 examples 到 Vercel production；Offscreen TypeScript 入口会通过 examples/offscreen/vite.config.ts 单独打包，不会以原始 .ts 作为线上运行入口。
  6. 推送 vX.Y.Z 和 u-space-mcp-vX.Y.Z 标签。

release-all concurrency group 会阻止两次发布并发运行。

失败重试 ​

版本提交已经推送，但 npm 或 Vercel 后续步骤失败时，不要再次选择 patch，否则会再递增一次版本。使用 current 重试当前提交版本：

bash
pnpm release:all current

工作流会跳过 registry 中已经存在的精确版本，只重试尚未完成的 npm 包、Vercel 部署和标签。

current 不会再次修改更新日志，因此重试不会生成重复的版本标题。

本地旧命令 pnpm release、pnpm publish:mcp 和 pnpm docs:deploy 继续保留，但它们不使用 GitHub OIDC，可能请求 npm OTP 或本机 Vercel 登录。

参考 ​

u-space docs