bootstrap-monorepo

启动多语言 Monorepo（moon + proto + Bun，兼容 Nx）

权威参考位于本技能中：

→ 参见：references/bootstrap-monorepo.md → 跨语言边界：references/cross-language-interop.md — 边界决策阶梯 + 已验证的工具状态（经研究验证，2026-06）

自我演进的技能：本技能会随着使用不断改进。如果说明有误、参数发生偏移，或需要采用变通方案，请立即修复此文件，不要延后。仅针对真实且可复现的问题进行更新。

何时使用本技能

在以下情况下使用本技能：

• 启动任何新代码仓库——无论是单语言还是多语言（此结构可按需精简）
• 设置由 moon 编排、由 proto 固定版本、接入 Bun/TypeScript 的 Monorepo
• 在 TS 控制平面下，通过契约接入引擎（Rust/Python/Go）
• 希望代码仓库从第一天起就兼容 Nx（之后执行 nx init 是机械式操作，无需重构）

技术栈

工具	职责
proto	固定代码仓库本地 .prototools 中的工具链版本（bun、python、rust、node 等）
moon	项目图 + 任务编排 + 缓存 + 受影响项检测（moon ci）
Bun	为所有脚本、CLI、胶水工具和测试提供 TS 运行时；根工作区
uv / cargo	由 moon script: 任务原生调用的 Python / Rust 引擎
TypeScript	类型安全的控制平面（7.0.2+）；参见下文的 TypeScript 配置

TypeScript 是控制平面；其他语言则是引擎，通过带漂移检查门禁和一致性测试的语言无关契约（JSON Schema 2020-12 / proto）接入。

TypeScript 配置

本技能会将 tsconfig.base.json 作为所有新代码仓库的规范参考实现进行搭建。样板路径：[templates/tsconfig.base.json](templates/tsconfig.base.json) — TS7 配置结构的唯一可信来源。

每个新 Monorepo 都会在根目录获得一个 tsconfig.base.json，其中包含：

• moduleResolution: bundler、target: ESNext、strict: true、noEmit、skipLibCheck
• allowImportingTsExtensions、lib: ["ESNext"]、verbatimModuleSyntax、noUncheckedIndexedAccess、noImplicitOverride、exactOptionalPropertyTypes
• 基础配置中刻意省略 types — TS7 默认将其设为 []（停止解析 @types/*、process、JSX 全局类型）。每个包都通过 "types": ["bun"] 或 ["node"] 等声明自己的类型——仅使用裸名称，绝不使用 @types/bun 或 bun-types。

包级 tsconfig.json 文件继承基础配置，并添加自己的 types 数组以及任何合理的包专属覆盖项。

参考：~/.claude/typescript-latest-CLAUDE.md（适用于整个代码库）。Package.json 声明 "typescript": "latest"（TS7.0.2+）。

有关 TS 7 迁移详情和各代码仓库的采用方式，请查阅已搭建技能的文档字符串和上游参考。

语言选择默认原则（新项目平局时的裁决规则）

在选择如何跨语言交互之前，先决定由哪种语言编写代码。此规则用于平局裁决，并非强制规定——SOTA 原生生态系统和现有仓库惯例优先。

• 控制平面默认使用 TypeScript：应用逻辑、编排、CLI、API、配置、验证、Agent/工作流自动化，以及未来的 Agent 必须重构的所有内容。（TS 默认采用结构化类型，是 Agent 最容易理解和导航的代码表面。）
• 仅在某种语言的生态系统原生达到 SOTA 时使用该引擎语言：ML/数据/科学/量化领域或仅支持 Python 的库使用 Python；热点内核和系统工作使用 Rust/Go（平局时 Go 优先于 Rust）。
• 绝不让引擎语言渗透到整个仓库。 仅支持 Python 的库并不会让项目变成 Python 项目——通过一个有类型的边界将其封装起来（见下方阶梯），并将 TS 保留为公共接口。在边界处进行验证：TS 类型仅在编译时生效，Python 类型提示不会在运行时强制执行。

跨越语言边界（决策阶梯）

当工作必须跨语言进行时，从成本最低到耦合度最高逐级选择——遇到第一个满足需求的选项即停止（完整原则和已验证的工具状态：references/cross-language-interop.md）：

1. 进程边界——通过 stdio 使用 CLI + JSON/NDJSON（moon script: 任务）。默认选项。
2. Schema 类型化 RPC——使用 protobuf + buf / ConnectRPC，适用于存在长期运行的服务或流的情况。
3. 数据平面——两个语言需要交换_表格_时，使用 Apache Arrow IPC/Flight/ADBC。
4. 进程内 FFI——调用频率使第 1–3 项过慢时，使用 PyO3/maturin、napi-rs、Bun FFI。
5. 单一 WASM 组件核心——仅当内核不需要线程时使用 WIT + Component Model（截至 2026 年中，WASI 线程支持仍未发布）。

Pattern B 门槛修订：8-float-op 测试选出 Pattern B 后，询问“内核是否需要线程？”→ 如果需要，使用原生核心（cdylib/PyO3），而非 WASM。

TypeScript ↔ Python（最常见的语言组合）已验证的选择，2026 年 6 月：第 1 级 = 使用 Bun.spawn/child_process 通过 uv run 运行 Python，版本取自 .python-version（不要使用 bun:ffi——仅支持 C-ABI）；第 2 级 = FastAPI + @hey-api/openapi-ts（HTTP），或由 buf 生成的 protobuf-es + protocolbuffers/python 存根（RPC）；Schema 单一事实来源 = Pydantic v2 → JSON Schema 2020-12 → TS，并设置 CI 漂移检查。完整表格见参考文档。

快速命令

# After bootstrap:
moon ci                          # affected quality pipeline
moon run <project>:check         # one project's full gate (lint+test+drift)
moon query projects              # machine-readable project graph (agents read this)
moon query tasks                 # machine-readable task surface
proto use                        # install all .prototools pins on a fresh machine

旧版路径

2026-06 之前使用 Pants + mise 的仓库（mise 已退役；不再保留任何 mise 时代的参考）：按仓库逐个迁移到此技术栈（优先保持功能对等，逐项切换任务），绝不一次性全面切换。旧→新的映射见 references/bootstrap-monorepo.md 中的迁移映射表。

发布（本地优先）

两种情况（完整方案见 references/bootstrap-monorepo.md 第 9 阶段）：

• 一个可发布单元 → 使用原版 semantic-release、单个 .releaserc.yml，标签为 v${version}。
• 多个独立版本的项目（单一仓库的标准做法）→ 使用 @rimac-technology/semantic-release-monorepo 创建每个项目的命名空间标签（<project>/v${version}）（原版 semantic-release 会忽略 commitPaths——上游 #1279/#1212），通过按 RELEASE_PROFILE 选择的 .releaserc.cjs 分发器实现；该分发器根据各发布流的 commitPaths 派生其 processCommits，并使用原版 semantic-release 进行全仓库级发布。使用 npm i -D --ignore-scripts 安装此分支。参考实现：example-org/monorepo。

相关技能

• itp:semantic-release - 发布自动化（本地优先；仅在发布/CodeQL/Dependabot/部署时使用 Actions）

---

故障排查

问题	原因	解决方案
moon 出现 proto::detect::failed	工具已安装，但未固定版本	proto pin --to global moon <version>（或添加到 .prototools）
通过 ssh 找不到 moon	非交互式 PATH 中没有 shims	在 ~/.zshenv 中导出 PROTO_HOME 和 shims PATH（不能只在 .zshrc 中设置）
Python 测试提示“No module named pytest”	uv run 会移除 dev 扩展项	从仓库根目录运行 uv run --extra dev pytest <path>
PyO3 crate 的 cargo test 出现链接错误（_PyBool_Type）	测试在 extension-module 下引用了 #[pyfunction]	将逻辑保留在纯 Rust 核心函数中；测试调用核心函数，包装层保持精简
任务在错误的 cwd 中运行	脚本假定当前目录为仓库根目录	在任务中设置 options: { runFromWorkspaceRoot: true }
Guard 任务被错误缓存	moon 默认会缓存	在 guard/parity/network 任务中设置 options: { cache: false }
提交显示“passed”，但并未成功提交	钩子自动修复了文件并中止提交	重新暂存并重试；提交后务必通过 git log --oneline -1 验证

执行后反思

此技能完成后，在结束前检查：

1. 命令是否成功？ — 如果没有，请修复导致失败的指令或错误表。
2. 参数或输出是否发生变化？ — 如果底层工具的接口发生变化，请更新 Usage 示例和 Parameters 表，使之保持一致。
3. 是否需要变通方案？ — 如果你不得不临时采用其他做法（不同的标志、额外步骤），请更新此 SKILL.md，避免下次调用时需要同样变通。

仅在问题真实且可复现时才更新，不要基于猜测更新。