Univer 仓库责任边界图：职责划分、对外提供包、跨仓依赖与发布契约

Univer 仓库责任边界图：职责划分、对外提供包、跨仓依赖与发布契约

【免费下载链接】univerUniver is a full-stack framework for creating and editing spreadsheets / word processor / presentation on both web and server.项目地址: https://gitcode.com/GitHub_Trending/un/univer

DREAMNUM.md 是 Univer 开源仓库（dream-num/univer）的“责任边界图”（ownership map）：它集中声明了该仓库拥有什么、对外提供哪些包与事件、依赖哪些外部仓库，以及这些事实变化时应同步更新的规则。读完本文，你能快速定位 Univer 各能力域的归属、从 monorepo 中找到对应的包契约文件，并理解其版本发布与跨仓同步的完整链路。

文档定位：一份面向 Agent 与贡献者的仓库契约

DREAMNUM.md 不是功能使用手册，而是仓库级的“元文档”，由四部分构成：

• Responsibilities（职责）：仓库拥有什么能力，以及明确不拥有什么（商业 Pro 层）；
• Provides（提供物）：对外发布的 npm 包与事件，以及每类提供物对应的契约文件；
• Depends on（依赖）：跨仓库的上下游依赖；
• Authoritative sources（权威来源）+ Update contract（更新契约）：事实查证入口与文档自身的保鲜规则。

这种写法把“代码在哪个包里、契约以哪个文件为准、什么时候必须改这份文档”显式化，便于贡献者、自动化 Agent 和新成员在不通读全部源码的情况下建立正确的仓库心智模型。

Responsibilities：开源仓库拥有什么，不拥有什么

DREAMNUM.md 的 Owns 一节列出五个能力域，每一项都指向仓库内可验证的契约位置：

其中边界声明值得单独强调：本仓库不拥有 Univer Pro 的商业协作、导入/导出、服务端与企业能力，这些是独立扩展层，在 README.md 的开源与 Pro 边界章节中另行描述。也就是说，如果你在开源仓库中找不到实时协作或文件导入导出的实现，这不是缺失，而是刻意划出的商业边界。

工作区定义：能力域的物理落点

pnpm-workspace.yaml 把上述能力域映射为具体的包目录：

packages: - common/* - examples - mockdata - presets - presets/packages/* - packages/* - tests/*

可以看到：packages/*承载各能力包（core、sheets、engine-render 等），presets与presets/packages/*承载预设集合，common/*存放共享的构建工具链（eslint、tsdown、tailwind 等），examples与tests/*则是用于“exercise the SDK”的示例和测试工程——这与 DREAMNUM.md 中“第一方预设 + 示例测试工程”的职责描述完全对应。

Provides：对外提供的包、适配器与仓库事件

DREAMNUM.md 的 Provides 一节是理解 Univer 发布面的核心，按“提供物 → 说明 → 契约文件”的结构列出：

核心运行时包

• @univerjs/core、@univerjs/engine-formula、@univerjs/engine-render：核心运行时与数据模型、Facade API、公式计算、共享渲染。契约以 packages/core/package.json 等包清单为准，API 以官方 API Reference（Facade API，见 DREAMNUM.md 权威来源一节）为准。

办公套件包

• @univerjs/sheets、@univerjs/docs、@univerjs/slides及其 UI 与功能包：可组合的办公模型、插件与编辑界面。对应 packages/ 目录下大量sheets-*、docs-*、slides*功能包（条件格式、数据校验、过滤、公式、表格、线程评论等），兼容性规则由 docs/API_STABILITY.md 约束。

预设包

• @univerjs/presets与@univerjs/preset-*：面向浏览器与 Node.js 集成的精选插件集合。仓库中 presets/packages 目录下可见完整的预设清单，覆盖 docs、sheets 两大族的 core、drawing、hyper-link、thread-comment、conditional-formatting、data-validation、filter、find-replace、note、sort、table 等场景，以及preset-docs-node-core、preset-sheets-node-core等 Node.js 无头预设。

框架适配器

• @univerjs/ui-adapter-vue3（README）与@univerjs/ui-adapter-web-component（README）：把 Univer 的 UI 服务接入 Vue 3 与 Web Component 环境的适配层。

仓库分派事件：sync-univer

Provides 一节还声明了一个非包类的对外提供物：sync-univerrepository-dispatch 事件，用于在改动进入dev分支后通知独立的 Univer Pro 仓库。其实现契约是 .github/workflows/dispatch-sync-univer-pro.yml：

on: push: branches: - dev jobs: dispatch-sync: if: github.repository == 'dream-num/univer' steps: - name: Dispatch sync event to univer-pro uses: peter-evans/repository-dispatch@v4 with: repository: dream-num/univer-pro event-type: sync-univer client-payload: > { "ref": "${{ github.ref_name }}", "sha": "${{ github.sha }}" }

从源码看，该工作流仅在dev分支 push 时触发，通过repository_dispatch把ref与sha作为 payload 投递给 Pro 仓库——这正是“开源改动 → 商业扩展层同步”这条跨仓流水线的具体落点。

Depends on：两条跨仓库依赖

DREAMNUM.md 声明了仓库对外的两条上游依赖，每条都给出了验证契约的文件：

1. univer-icons 仓库：拥有 Univer UI 包消费的 React 图标组件与 SVG 资产。契约佐证：packages/ui/package.json（@univerjs/ui包清单）与 packages/sheets-conditional-formatting/package.json（SVG 资产依赖）。
2. verso 仓库：拥有本仓库使用的 workspace 发布 CLI，负责给 Univer 各包定版与打标签。契约佐证：根 package.json 中的"release": "verso"脚本与 devDependency@amamo/verso（当前版本 1.2.0）。

verso 在本仓库中的实际配置

仓库根的 verso.toml 展示了这条依赖的具体配置：

[version] root_package = "package.json" [workspaces] patterns = [ "common/*", "packages/*", "presets", "presets/packages/*", ] include_root = true [changelog] infile = "CHANGELOG.md" preset = "angular" [git] commit_message = "chore(release): release v${version}" tag_name = "v${version}" push = "follow-tags"

从配置看，verso 的定版范围覆盖了common/*、packages/*与全部 presets，changelog 以 angular preset 写入 CHANGELOG.md，发布提交信息与标签格式统一为chore(release): release v<version>和v<version>——标签格式正是下游 npm 发布工作流的触发条件（见下节）。

Authoritative sources：事实查证入口

DREAMNUM.md 把“去哪查证”也列为契约的一部分，列出了五类权威来源：产品文档（docs.univer.ai）、API Reference（Univer Facade API）、开发指引（README.md 与 CONTRIBUTING.md）、包契约（packages/、presets/、docs/API_STABILITY.md）、npm 发布来源（.github/workflows/release-npm.yml）以及安全策略（SECURITY.md）。

API 稳定性策略要点

docs/API_STABILITY.md 是 DREAMNUM 所引用的核心兼容性契约，定义了四级稳定性：

• Stable：从公开包入口导出且无实验性警告、被 API Reference/README/示例文档化的接口（如@univerjs/core、@univerjs/sheets、@univerjs/presets入口与 Facade API），未经弃用路径不得不兼容地移除或修改；
• Experimental：行为、命名、参数或包位置可能变化的接口，需在文档或 JSDoc 中标注不稳定，破坏性变更仍应在 release notes 中说明；
• Internal：controllers、views、models 等实现目录中无公开导出契约的代码，不受兼容保证约束，用户应用不应依赖；
• Deprecated：JSDoc 标记@deprecated并给出替代链接，运行时可检测时通过ILogService输出弃用警告；pre-1.0 阶段移除可发生在 minor 版本，但必须记录为破坏性变更。

此外该文档要求引入破坏性变更的 PR 在描述中携带BREAKING CHANGE:小节，并强调所有@univerjs/*包必须保持同一版本——版本混用会绕过兼容性检查，在插件注册、Facade API 组合、locale、命令与共享数据模型周围产生运行时故障。

npm 发布链路

.github/workflows/release-npm.yml 定义了发布触发与流程：

on: push: tags: - 'v*.*.*' - 'v*.*.*-alpha.*' - 'v*.*.*-beta.*' - 'v*.*.*-rc.*'

发布 Job 依次执行pnpm install --frozen-lockfile与pnpm build，然后按标签区分通道发布：alpha/beta/rc 标签走对应的 dist-tag，正式版走 default tag，两者均为pnpm publish --access public -r --no-git-checks --provenance（带 npm provenance）。结合 verso.toml 的tag_name = "v${version}"，完整链路是：verso 定版并打v*标签 → 标签推送触发 release 工作流 → 构建并以 provenance 发布全部-r包，这与 DREAMNUM.md 中“Package release source: npm release workflow”的声明一一对应。

Update contract：文档自身的保鲜规则

DREAMNUM.md 末尾给出了一份自检清单——当以下任一事实变化时，必须在同一变更中更新该文件：

1. 仓库职责或边界变化；
2. 对外跨仓库依赖变化；
3. 公开包、API、协议、事件、图片或数据契约变化；
4. 部署来源、运维手册或数据分级变化。

这条契约让“责任边界图”不再是静态描述：每当 provides 增删一个包、dep 增删一条上游依赖、或sync-univer事件语义变化时，文档与代码强制同 PR 演进，避免边界图与真实仓库结构漂移。

小结：如何把这份责任图用起来

• 找包归属：从 Provides 表的“契约”列跳到对应package.json或 packages/ 目录；
• 找兼容性依据：一切 stable/experimental/internal 判定以 docs/API_STABILITY.md 为准；
• 找发布链路：package.json 的release脚本 + verso.toml + .github/workflows/release-npm.yml 三者串联；
• 找跨仓同步：.github/workflows/dispatch-sync-univer-pro.yml 是开源到 Pro 的唯一事件桥梁；
• 判断边界：商业协作/导入导出/企业能力不在本仓库职责内，属于独立扩展层。

DREAMNUM.md 的价值正在于此：它把散落在包清单、工作流与策略文档中的“谁拥有什么、以谁为准”收敛为一份可随 PR 持续更新的可执行契约。

【免费下载链接】univerUniver is a full-stack framework for creating and editing spreadsheets / word processor / presentation on both web and server.项目地址: https://gitcode.com/GitHub_Trending/un/univer