@really-nothing/shell-contracts

主系统平台 微前端 主壳与所有子系统的协议单一事实来源：manifest、Bridge、Overlay、Feedback、Viewport、事件、micro-app、page 等 TypeScript 类型与常量。

本包是一个独立发布到公共 npm 的纯类型/常量包，主壳（shell）与各子系统（sub-apps）在各自仓库中按 SemVer 版本范围独立安装，禁止各自复制协议类型。

安装

npm install @really-nothing/shell-contracts@^1

使用

import {
  CONTRACTS_SCHEMA_MAJOR,
  SHELL_BASELINE_VERSION,
} from '@really-nothing/shell-contracts'
import type { Manifest, MicroApp, OverlayRequest } from '@really-nothing/shell-contracts'

纯 ESM 包（"type": "module"），发布产物只含 dist/（.js + .d.ts）。

版本规则（SemVer）

• patch：向后兼容的修订（补注释、修类型笔误等）。
• minor：向后兼容的新增（新增可选字段、新事件类型等）。
• major：breaking change 必须升主版本，并给子系统留升级窗口（先双版本共存，过渡期结束再下线旧范围）。

主壳通过 CONTRACTS_SCHEMA_MAJOR 声明支持的 schema 主版本；子系统 manifest 通过 schemaVersion / minShellVersion / features 表达兼容能力。

本地开发

npm install
npm run build       # 生成 dist/
npm run typecheck   # 仅类型检查，不产出

与主壳/子系统本地联调（发布前）

包发布前，消费方（主壳、子系统）无法从 npm 拉到新版本，可用 npm link 临时联调：

# 在本包目录
npm run build
npm link

# 在主壳或子系统仓库
npm link @really-nothing/shell-contracts

发布到公共 npm（手动）

npm login                 # 登录 really-nothing 账号（个人 scope）
npm whoami                # 确认显示 really-nothing
npm publish --dry-run --access public   # 先干跑，检查将要发布的文件
npm publish --access public             # 正式发布

升级版本时先按 SemVer 改 package.json 的 version（或用 npm version patch|minor|major），再执行上面的发布命令。

首次发布 scoped 公共包必须带 --access public（本包已在 publishConfig.access 声明，正常情况可省略）。

迁移说明

本包由 Main-System-Shell 主仓库中的 packages/shell-contracts 抽离为独立仓库。将本目录 git init 后推送到独立远端即可：

cd shell-contracts
git init
git add .
git commit -m "chore: init shell-contracts as standalone package"
git remote add origin <你的独立仓库地址>
git push -u origin main

抽离后，主壳与子系统不再通过 workspace 软链引用，而是从 npm 按版本安装。请把 package.json 中的 repository / homepage / bugs 字段改为你实际的仓库地址。