yakumo

cordiverse（Koishi 生态）出品的 monorepo / workspace 任务编排 CLI，v3.2.1，MIT。名字来自东方 Project 的八云紫（Yakumo Yukari）——她管理的式神还有自己的式神，寓意 yakumo 能管理嵌套 workspace。

构建在 cordis 之上：每条命令都是一个 cordis 插件，yakumo.yml 就是插件配置文件，因此扩展性是其核心设计。

定位

对比项	yakumo	lerna / nx / turborepo
定位	轻量 workspace 脚本编排	大型 monorepo 构建系统
缓存/任务图	无	有（nx cloud / turbo cache）
特色	嵌套 workspace、零配置自定义脚本、发布流（version/publish）一体化	依赖图增量构建
适用	中小型 TS 库集合（Koishi/cordis 生态风格）	大型工程化 monorepo

核心机制

workspace 发现：从根 package.json 的 workspaces glob 扫描所有包（globby），支持嵌套 workspace（子包还可声明自己的 workspaces）
包管理器探测：自动识别 npm / yarn(1 & Berry) / pnpm，run、publish 等命令用对应 agent 执行
locate() 定位：命令的 [...packages] 参数接受包名或 workspace 路径；歧义时可用 yakumo.yml 的 alias 消歧
-- 透传：-- 之后的参数原样传给底层工具（如 yakumo vitest --import tsx）
配置即插件：yakumo.yml 是 cordis 插件列表，加载 yakumo-* 扩展即注册新子命令

yakumo.yml 格式

- name: yakumo            # 核心（内置 run/list/version/publish/upgrade/prepare/test）
- name: yakumo-tsc        # 扩展：加载后即获得 tsc 子命令
- name: yakumo-esbuild
- name: yakumo-vitest
  config:                 # 扩展可带配置
    alias:
      my-alias: /path/to/package

内置命令（core）

命令	说明
`yakumo run [...packages] -- <script>`	在每个定义了该 script 的包里执行（用探测到的包管理器）
`yakumo list`	树状打印所有包与嵌套层级，末尾统计 `N packages, M workspaces`
`yakumo version [...packages]`	版本号管理，自动同步 workspace 内 dependents 的依赖范围
`yakumo publish [...packages]`	批量发布到 npm，默认跳过 private 包
`yakumo upgrade [...packages]`	升级外部依赖到最新（并发 10），`--next` 允许不兼容版本
`yakumo prepare`	把嵌套 workspace 声明同步回根 `package.json` 的 workspaces 字段，`-c/--clean` 清理已移除的
`yakumo test [...packages]`	内置测试文件搜索（默认 `*/tests/.spec.ts`）

version 选项（发布流核心）

yakumo version -3          # patch +1（默认）
yakumo version -2          # minor
yakumo version -1          # major
yakumo version -p          # 预发布递进：alpha → beta → rc
yakumo version -P          # 预发布转正（去掉 prerelease 段）
yakumo version -v 2.0.0    # 精确设置版本
yakumo version -0          # reset（版本号回退一档，用于撤销）
yakumo version -r          # 递归 bump 依赖方
yakumo version -D          # 显示依赖更新明细
yakumo version -l          # 仅标记 local（不产生实际版本变化）

要点：bump 时自动遍历所有包的 dependencies/peerDependencies/optionalDependencies（含 npm: 别名链接），把引用范围同步为新版本并标记 dirty；devDependencies 同步但不触发递归 bump。

publish 选项

yakumo publish --tag next --access public
yakumo publish --registry <url> --otp <code> --debug

yarn Berry 环境自动改用 yarn workspace <name> npm publish。

官方扩展命令

扩展	命令与选项
yakumo-tsc	`yakumo tsc [...packages] [--clean]` — 按包编译 TypeScript
yakumo-esbuild	`yakumo esbuild [...packages] [--minify]` — 按包 esbuild 构建
yakumo-vitest	`yakumo vitest [...packages] [-w watch] [-u update] [-b bail] [-t timeout] [--coverage] [--coverage.reporter ...]`
yakumo-mocha	`yakumo mocha [...packages] [-t timeout] [-s slow] [-b bail] [--retries n]`，未知选项透传给 mocha

v3 起 publish/upgrade/version 已并入 core；npm 上旧的独立包（yakumo-publish、yakumo-version 等）是 v2 时代产物。

实战：cordis 仓库（本地 ~/6ai/opensources/cordis）

// package.json scripts
{
  "yakumo": "node --expose-internals --import tsx --import @cordisjs/unyaml node_modules/yakumo/lib/cli.js",
  "build": "yarn yakumo esbuild && yarn yakumo tsc",
  "test": "yarn yakumo vitest --import tsx"
}

# yakumo.yml
- name: yakumo
- name: yakumo-tsc
- name: yakumo-esbuild
- name: yakumo-vitest

注意：cordis 的 yakumo.yml 是 YAML 格式，需 @cordisjs/unyaml 加载器；--import tsx 让配置和脚本能直接用 TS。

踩坑点

run 只跑声明了该 script 的包，没声明的静默跳过——拼错 script 名不会有报错，只是”什么都没跑”
包名与路径歧义时报错会提示用包名消歧或在 yakumo.yml 加 alias
项目小、无嵌套 workspace、不需要一体化发布流时，lerna/nx/turborepo 的缓存与任务图更有价值
仓库已从 shigma/yakumo 迁到 cordiverse/yakumo，旧链接 301 跳转

zhaoweiguo 的知识库

目录