Mobius Mono

Overview

对象定位： Mobius Mono Project 是面向项目开发的一致性项目，由 Mobius Mono Specification（文本规范）和 Mobius Mono Toolkit（代码工具）组成。

存在目的： 项目开发中反复出现工程、设计和业务方面的共性判断。Mobius Mono Project 沉淀可跨项目复用的要求和工具，使不同项目能够依据一致的要求作出选择，并借助共享工具落实和检查结果。

提供能力： Mobius Mono Specification 用文档规定项目协作约定、文档要求、工程要求，Web 应用、服务端与可复用代码能力的设计及实现要求，以及可跨项目复用的业务能力要求；Mobius Mono Toolkit 以代码提供可以独立使用的软件开发工具包（software development kit，SDK）、命令行接口（command-line interface，CLI）、脚本和工程工具。SDK 供项目代码调用，CLI 供使用者通过命令执行工具能力。

职责边界： Mobius Mono Specification 说明可跨项目复用的协作与开发要求，Mobius Mono Toolkit 提供相应的工具能力。采用方根据自身目标判断适用要求并负责落实；项目的产品目标、具体业务模型和产品表达由项目自行决定，Mobius Mono Project 不替项目作出这些选择。加入 Mobius Mono Project 意味着项目遵循 Mobius Mono Specification 并使用 Mobius Mono Toolkit。

For Understanding

不同项目会反复面对相似的工程、设计、文档和业务判断：代码与配置如何组织，模块如何依赖，界面如何呈现信息，服务如何维护数据，公共能力如何组合。具体答案会随产品目标变化，但这些判断若只留在各项目的配置和实现中，后续维护者就难以区分可复用的约束与项目特有的选择，也难以将经验用于其它项目。

Mobius Mono Project 的思路是将可跨项目复用的判断与具体产品决策分开：前者形成明确的要求和工程边界，后者由项目根据自身目标选择并具体化。这样，共享的是作出选择的依据，项目仍可形成不同的业务模型和产品表达。

这一思路由文本规范与代码工具共同落实。Mobius Mono Specification 将协作、文档、工程、相关设计及实现和可复用业务能力中的共性判断写成可阅读、执行和检查的要求；Mobius Mono Toolkit 提供可独立使用的 SDK、CLI、脚本和共享配置，帮助项目落实其中适合由工具支持的工程能力。项目依据规范作出具体选择，并对实施和检查结果负责。

这一方案的预期结果是：不同项目形成更容易理解和检查的共同工程基础，维护经验能够在项目间复用，开发者与人工智能（artificial intelligence，AI）可以依据相同的要求协作，把更多注意力放在具体问题和产品价值上。这些是方案追求的效果，仍需在具体项目中通过实施与检查判断是否达成。

方案的主要限制是规范和工具都不替项目决定产品目标、具体业务模型或产品表达。代码工具也不能代替对职责划分、设计语义和使用结果的判断；这些内容仍需结合项目实际情况，通过设计材料、测试或评审验证。

For Using

当项目需要依据共同要求组织工程、文档和不同类型的包，或复用配置、开发、构建和变更管理能力时，可以采用 Mobius Mono。项目若要完整采用 Mobius Mono Project，需要遵循适用的 Mobius Mono Specification 并使用 Mobius Mono Toolkit；Toolkit 的具体能力也可以独立使用。按照 Toolkit 文档中的安装和命令示例操作，需要 Bun 环境。

开始时，先从 Specification 总纲确定当前项目和工作适用的子规范，按其中的要求作出选择并检查结果；再根据需要接入 Toolkit。当前 SDK 提供共享配置、开发与构建、变更管理等能力；CLI 提供库与服务的构建命令，以及添加变更记录、更新版本和发布的命令。使用者可以据此形成适用要求及其检查结论，并获得所选工具支持的工程能力。

Toolkit 不会自动证明项目满足全部规范；设计和业务要求仍需由项目结合设计材料、测试或评审检查。产品目标、具体业务模型和产品表达也由项目自行确定。

延伸阅读：

• Mobius Mono Specification 总纲：了解规范体系的范围、组成和适用关系。
• Mobius Mono Toolkit：查看安装方式、SDK 与 CLI 用法。

For Contributing

Mobius Mono 的变更分为规范与工具两部分。跨项目适用的要求应写入 docs/mobius-mono-specification/ 中职责相应的规范；可由代码复用的工程能力应放入 Toolkit 的 src/models/ 中职责相应的模块，并通过 SDK 公开。需要命令入口时，由 src/app/index.ts 组织调用；共享配置由相应的 SDK 模块提供，本包的构建脚本位于 scripts/。规范确定要求与边界，Toolkit 支持其中适合工具化的工作，修改一方时应检查另一方是否仍与之相符。

Toolkit 的关键外部依赖包括提供开发与配置能力的 Vite Plus、用于打包的 Rolldown、用于样式配置的 UnoCSS、用于执行外部命令的 zx，以及用于版本变更管理的 @changesets/cli。Mobius Mono 的实现不应该依赖同一仓库中的其它包；扩展能力时也应保持 SDK 模块、共享配置与 CLI 入口各自的职责。

判断改动是否符合项目要求时，先按适用规范核对职责、依赖边界和行为，再检查受影响的 SDK 导出或 CLI 命令；工具改动还应通过本包相应的格式、静态检查和构建流程。规范改动应检查适用范围及与其它子规范的关系，并遵循文档规范。

延伸阅读：

• Mobius Mono Specification 总纲：了解规范体系的范围、组成和适用关系。
• Mobius Mono Toolkit：核对公开的 SDK 与 CLI 用法。

Todos & Drafts

• [ ] 评估 Vite+ 与 Oxc VS Code 对 monorepo 子包级 lint/format 配置的支持，满足预期后再考虑迁移：
  • 预期： VS Code 始终以 monorepo 根目录作为工作区；packages/ 下的每个包可以维护自己的 vite.config.ts；Oxc 处理文件时能按文件所属包选择该包配置中的 lint 和 fmt，无需把每个包单独打开为工作区根目录。
  • 调查情况（截至 2026-10-29）：
    • Oxc VS Code 扩展具备一般性的 Vite+ 集成：找到工作区中的 vite-plus 后，通过 vp lint --lsp 和 vp fmt --lsp 使用 Vite+ 配置。但这不等于扩展会按当前文件所属包自动选择嵌套的 vite.config.ts。
    • Vite+ 的 monorepo 文档要求 lint/format 以工作区根 vite.config.ts 为配置入口，并通过 lint.overrides、fmt.overrides 区分文件或包；子目录配置不会逐文件覆盖根配置。Vite+ 在 nested lint/format 配置讨论 中说明，当前暂缓支持此语义，正在征集根级 overrides 或显式组合配置不能满足的具体用例。参见 Vite+ Monorepo 指南。
    • Oxc VS Code 的 子目录工具支持 issue #302 仍未关闭；PR #395 提议增加 oxc.workingDirectories，其依赖的 Oxc 语言服务器 PR #26848 也仍未合并。后者的方案明确指出 workingDirectories 在 Vite+ 模式下禁用，因此目前没有已发布的方案满足上述预期。
    • Oxc VS Code 的 issue #335 记录了 oxc.requireConfig 不把 vite.config.ts 视为 Oxlint 配置启动条件的问题。将其设为 false 只能绕过启动门槛，不能使 Oxc 按子包切换 Vite+ 配置。
  • 当前方案： 本轮对 Vite+ lint/format 集成的尝试已还原，继续使用独立 Oxlint、oxlint-tsgolint 和 Oxfmt。当前 lint/fmt 脚本分别运行 bun oxlint --type-aware --type-check 和 bun oxfmt --write，并使用 oxlint.config.ts、oxfmt.config.ts；工作区的 oxc.requireConfig 保持为 true。Vite+ 仍可用于包的其它工程能力，不替代当前 lint/format 命令和配置。
  • 重新评估条件： 上游正式支持在一个 monorepo 工作区中按文件所属子包解析各自的 Vite+ lint/format 配置，并且 Oxc VS Code 已在发布版本中支持该行为。若采用根级配置与 overrides，则应作为另一种明确的配置方案单独评估，而不是视为子包配置自动发现。
• [ ] 等 Oxc 正式支持在 monorepo 中按文件所在目录解析 oxlint-tsgolint 后，重新评估根级与包级依赖声明：
  • 用途： oxlint-tsgolint 是 Oxlint 类型感知规则的后端；只有启用 --type-aware 或 oxc.typeAware 时才需要。当前各包的 lint 脚本启用了 --type-aware --type-check，VS Code 工作区也启用了 oxc.typeAware。
  • 当前行为（截至 2026-10-29）： Oxc 语言服务器使用同一份 tsgolint 可执行程序处理工作区文件；仅在子包安装时，根目录工作区的默认解析无法自动找到它。因此，当前 Oxc 发布版和默认配置下，根 package.json 需要保留 oxlint-tsgolint 开发依赖。若改用 VS Code 的 oxc.path.tsgolint 显式指定路径，则可从其它位置加载。参见 Oxc issue #18995（原 #17227） 和 Oxc VS Code 配置。
  • 包级依赖： 根目录统一安装足以供当前 monorepo 工作区中的 Oxc 插件使用，不要求每个包各自安装一份。只有需要脱离根工作区独立安装、运行类型感知 lint 的包，才需要在自己的开发依赖中声明 oxlint-tsgolint；各包可以通过 workspace catalog 统一版本。
  • 上游进展： PR #26849 提议按每个待检查文件的位置解析 tsgolint，让子包安装可以各自生效、根目录不再必须安装；截至上述日期仍未合并，也未进入正式版本。该能力发布后，再检查根依赖是否可移除，以及哪些包仍需保留包级声明。
• [ ] 上游修复后，移除 UnoCSS @unocss/autocomplete 缺失运行时依赖的 packageExtensions：
  • 问题： @unocss/[email protected] 的发布代码导入 @unocss/core，但包清单只在 devDependencies 中声明它。Bun isolated linker 下，packages/mono 运行 bun run build 时会因该依赖无法解析而失败。
  • 当前方案： 根目录 package.json 通过 packageExtensions 将 @unocss/[email protected] 补充为 @unocss/autocomplete 的运行时依赖；Bun 将该扩展及依赖关系写入 bun.lock。
  • 上游调查（截至 2026-10-30）： 未找到直接报告此依赖漏声明或 Bun isolated install 错误的 issue/PR。PR #5402 修改了 autocomplete 的缓存实现并移除 lru-cache，但仍保留 @unocss/core 为开发依赖，未修复此问题。
  • 后续处理： UnoCSS 发布版本在 @unocss/autocomplete 的 dependencies 中声明 @unocss/core 后，移除根目录的 packageExtensions，同步锁文件并重新运行 packages/mono 构建。
• [ ] 持续评估 Changesets 与 Bun workspaces 的版本和发布兼容性：
  • 问题来源： Setting up Changesets with Bun Workspaces 记录了 Bun monorepo 中使用 Changesets 发布时的风险：Changesets 生成发布包时可能没有将 workspace:* 等 workspace 协议替换为实际版本，导致消费者拿到无法安装的依赖声明。该文章当时给出的绕行方式是先运行 changeset version && bun update，再逐包运行 bun publish，最后运行 changeset tag。
  • 当前上游情况（截至 2026-10-29）： Changesets v3 的迁移指南列出 npm、pnpm 和 Yarn 的受支持版本，没有列出 Bun；v3 的发布流程也说明通过相应包管理器 CLI 进行发布。因此，不能把 changeset publish 视为已获官方支持的 Bun 发布流程。另一方面，Bun 1.4.4 的发布说明修复了打包时从过期 bun.lock 读取 workspace:、catalog: 版本的问题，改为从包的 package.json 解析；当前 bun publish 文档也说明会在发布包中移除这些协议并解析版本。文章中为修正发布清单而运行 bun update 的理由已不再适用于当前 Bun，但锁文件仍需与变更后的包清单保持一致。
  • 本仓库状态： 根目录使用 Bun 1.4.4 和文本锁文件 bun.lock，workspace 范围为 packages/*，包清单使用 workspace:* 和 catalog:；Changesets CLI 锁定为 3.0.3。当前 change version 在 bun changeset version 后运行 bun install --lockfile-only，用于同步版本变更后的锁文件，避免 bun update 更新所有符合范围的直接和间接依赖。该做法保证锁文件同步，不承担发布时替换 workspace/catalog 协议的职责。
  • 当前发布方案： change publish 逐个读取 packages/*/package.json，跳过 private: true 的包，对公开包运行 bun publish --tolerate-republish；不使用 bun publish --recursive。所有包的发布尝试完成后都会运行 bun changeset git-tag，即使公开包发布失败也会尝试打 tag。.changeset/config.json 中 privatePackages.version 与 privatePackages.tag 均为 true，私有包虽不发布到 npm，仍需 Changesets tag 触发对应 GitHub Actions。发布或打 tag 的错误会在 tag 尝试完成后汇总返回。
  • 后续复核： 发布前后检查打包产物中的 package.json，确认没有残留 workspace: 或 catalog: 协议；确认版本更新后的 bun.lock 可用于 frozen install；验证私有包 tag 能触发预期 GitHub Actions，并确认真实公开包发布失败会被报告。当前逐包扫描以工作区目录为范围，而不是直接消费 Changesets 的 publish-plan；需要继续确认它不会发布未纳入本次 Changesets 发布计划的包。Bun 或 Changesets 升级后重新检查这些行为；只有 Changesets 官方明确支持 Bun 发布、并且发布目标与本仓库的 tag 触发需求相符时，才重新评估是否改用 Changesets 自身的发布命令。
• [ ] change publish 支持 dry-run 参数。
• [ ] 规则稳定之后，将其实现为代码。
• [ ] 实现一个自动检测 oxlint 官方规则是否有增减的机制。

几乎所有操作都可以理解为对文件的操作，包括但不限于：

• 新增不存在的文件。
• 检查已存在的文件。
• 修改已存在的文件。
• 删除已存在的文件。

以下命令是尚未实现的 CLI 设想，仅用于说明拟议的能力划分，不能作为当前操作步骤。<template-name> 表示拟议的模板名称参数。当前已实现命令及其用法参阅 Mobius Mono Toolkit。

bun mono repository init
bun mono repository check
bun mono repository correct
bun mono file check
bun mono package add --template <template-name>
bun mono package remove
bun mono package check
bun mono package correct
bun mono typescript check