feat: The version synchronization and skills generation are executed in the pre-commit hook

.github/workflows/ci.yml

@@ -25,16 +25,9 @@ jobs:
 
       - run: pnpm install --frozen-lockfile
 
-      - run: pnpm -r --filter "./packages/*" build
+      - run: pnpm run sync:skill-assets
 
-      - name: Verify generated skill assets are committed
-        run: |
-          if ! git diff --exit-code -- skills/bailian-cli/SKILL.md skills/bailian-cli/reference/; then
-            echo "::error::skills/bailian-cli/SKILL.md or reference/ differs from build output."
-            echo "Run: pnpm --filter bailian-cli run build"
-            echo "Then commit the updated files."
-            exit 1
-          fi
+      - run: pnpm -r --filter "./packages/*" build
 
       - run: pnpm run check
 

.vite-hooks/pre-commit

@@ -1 +1,10 @@
+#!/usr/bin/env sh
+set -eu
+
+# Regenerate skill reference + SKILL metadata (needs bailian-cli-core dist).
+pnpm run sync:skill-assets
+
+# Stage generator output so it is included in this commit.
+git add skills/bailian-cli/reference skills/bailian-cli/SKILL.md
+
 vp staged

AGENTS.md

@@ -25,13 +25,13 @@ packages/cli/
 └── tests/e2e/
 ```
 
-Skill / 命令手册随 `skills/bailian-cli/` 经 `npx skills add modelstudioai/cli` 安装。`tools/generate-reference.ts` 从 `catalog.ts` 生成命令手册到 `skills/bailian-cli/reference/`(纳入 git)。
+Skill / 命令手册随 `skills/bailian-cli/` 经 `npx skills add modelstudioai/cli` 安装。`tools/generate-reference.ts` 从 `catalog.ts` 生成命令手册到 `skills/bailian-cli/reference/`(纳入 git);与 `tools/sync-skill-metadata.ts` 一起在 **pre-commit**（`.vite-hooks/pre-commit`）及根脚本 `pnpm run sync:skill-assets` 中执行。
 
 非代码资产:
 
 - `tools/release/` — 发版自动化（CI 驱动，见 `.github/workflows/publish.yml`）
 - `tools/generate-reference.ts` — 从 `catalog.ts` 生成命令手册到 `skills/bailian-cli/reference/`
-- `tools/sync-skill-metadata.ts` — 从 `packages/cli/package.json` 同步 `skills/bailian-cli/SKILL.md` 的 `metadata.version`（`pnpm --filter bailian-cli run build` 时自动执行）
+- `tools/sync-skill-metadata.ts` — 从 `packages/cli/package.json` 同步 `skills/bailian-cli/SKILL.md` 的 `metadata.version`（与 `generate:reference` 一并由根目录 `pnpm run sync:skill-assets` 及 pre-commit 执行）
 - `README.md` / `README_CN.md` — npm 和 GitHub 主页
 
 约定:

docs/agents/command-add-remove.md

@@ -40,7 +40,7 @@ registry.ts  main.ts      tools/generate-reference.ts   export-schema.ts
 - **`packages/cli/src/commands/catalog.ts`**: `import` 命令模块 + `"<path>": handler` 映射;**不** `import registry.ts`(避免构建时循环依赖)
 - **`packages/cli/src/commands/index.ts`**: `export { commands } from "./catalog.ts"`(给包内 re-export 用)
 - **`packages/cli/src/registry.ts`**: `import { commands } from "./commands/catalog.ts"`,建树、`resolve`、`printHelp`;Commands / Global Flags 从 `Command` 元数据与 `GLOBAL_OPTIONS` **动态生成**
-- **`tools/generate-reference.ts`**: build 前读 `catalog.ts`,写 `skills/bailian-cli/reference/index.md`(索引) + `skills/bailian-cli/reference/<一级命令>.md`(详情,勿手改)。该目录**纳入 git**,随 `npx skills add modelstudioai/cli` 分发
+- **`tools/generate-reference.ts`**: pre-commit / `pnpm run sync:skill-assets` 时读 `catalog.ts`,写 `skills/bailian-cli/reference/index.md`(索引) + `skills/bailian-cli/reference/<一级命令>.md`(详情,勿手改)。该目录**纳入 git**,随 `npx skills add modelstudioai/cli` 分发
 
 已删除、勿再引用:`commands/help.ts`、`registry.ts` 内联 `new CommandRegistry({...})`、`printRootHelp` 手写命令行。
 
@@ -59,7 +59,7 @@ registry.ts  main.ts      tools/generate-reference.ts   export-schema.ts
 
 ### B. 文档层
 
-- [ ] 运行 `pnpm --filter bailian-cli run generate:reference`(或 `build`),刷新 `skills/bailian-cli/reference/` 下生成文件并提交
+- [ ] 运行 `pnpm run sync:skill-assets`(或正常 `git commit` 走 pre-commit),刷新 `skills/bailian-cli/reference/` 与 `SKILL.md` 的 `metadata.version` 并提交
 - [ ] `README.md` / `README_CN.md`: Quick Start、命令一览(用户向,与 help 对齐即可)
 - [ ] `skills/bailian-cli/SKILL.md`: 若安装说明或能力边界有变,同步更新
 
@@ -80,7 +80,7 @@ registry.ts  main.ts      tools/generate-reference.ts   export-schema.ts
 ## 完成后自查
 
 ```sh
-pnpm --filter bailian-cli run generate:reference   # reference/ 与 catalog 一致
+pnpm run sync:skill-assets   # reference/ + SKILL metadata.version 与 catalog / package.json 一致
 node packages/cli/src/main.ts <new-command> --help
 node packages/cli/src/main.ts                        # 根 help 列表含新命令
 vp test packages/cli/tests/e2e/<topic>.e2e.test.ts   # 相关 e2e

docs/agents/lint-toolchain.md

@@ -40,6 +40,7 @@
 
 - [ ] `.vite-hooks/pre-commit` 改动后,`pnpm install` 重新软链(走 `prepare: vp config`)
 - [ ] 增加 hook 时,确认在干净 clone 后能自动激活
+- [ ] pre-commit 会跑 `pnpm run sync:skill-assets`(先 build core,再 `generate:reference` + `sync:skill-version`)并 `git add` skill 资产,最后 `vp staged`
 
 ### F. CI / 发版工具
 

package.json

@@ -16,6 +16,7 @@
     "ready": "vp check && vp run -r test && vp run -r build",
     "prepare": "vp config",
     "check": "vp check",
+    "sync:skill-assets": "pnpm --filter bailian-cli-core run build && pnpm --filter bailian-cli run generate:reference && pnpm --filter bailian-cli run sync:skill-version",
     "dev": "pnpm -F bailian-cli-core dev",
     "bl": "pnpm -F bailian-cli dev",
     "test": "vp test",

packages/cli/package.json

@@ -38,7 +38,7 @@
   "scripts": {
     "generate:reference": "node --experimental-strip-types ../../tools/generate-reference.ts && sh -c 'cd ../.. && vp check --fix skills/bailian-cli/reference'",
     "sync:skill-version": "node --experimental-strip-types ../../tools/sync-skill-metadata.ts",
-    "build": "pnpm run generate:reference && pnpm run sync:skill-version && vp pack",
+    "build": "vp pack",
     "dev": "node src/main.ts",
     "test": "vp test",
     "check": "vp check"

tools/generate-reference.ts

@@ -6,6 +6,7 @@
  * Committed to git; consumed by the `bailian-cli` Agent Skill (`npx skills add modelstudioai/cli`).
  *
  * Run: pnpm --filter bailian-cli run generate:reference
+ * (Also run via `pnpm run sync:skill-assets` or the repo pre-commit hook; requires built `bailian-cli-core`.)
  */
 import { mkdirSync, readdirSync, rmSync, writeFileSync } from "node:fs";
 import { dirname, join } from "node:path";

tools/release/check.mjs

@@ -30,6 +30,19 @@ export async function runCheck() {
   step("build bailian-cli-core");
   run("pnpm", ["--filter", "bailian-cli-core", "run", "build"]);
 
+  step("generate skill reference + sync SKILL.md version");
+  run("pnpm", ["--filter", "bailian-cli", "run", "generate:reference"]);
+  run("pnpm", ["--filter", "bailian-cli", "run", "sync:skill-version"]);
+
+  step("verify committed skill assets match generators");
+  run("git", [
+    "diff",
+    "--exit-code",
+    "--",
+    "skills/bailian-cli/SKILL.md",
+    "skills/bailian-cli/reference/",
+  ]);
+
   step("build bailian-cli");
   run("pnpm", ["--filter", "bailian-cli", "run", "build"]);
 

tools/sync-skill-metadata.ts

@@ -3,7 +3,7 @@
  * `packages/cli/package.json` (single source of truth for CLI release version).
  *
  * Run: pnpm --filter bailian-cli run sync:skill-version
- * Invoked automatically by `pnpm --filter bailian-cli run build`.
+ * Invoked via `pnpm run sync:skill-assets` or the repo pre-commit hook (see `.vite-hooks/pre-commit`).
  */
 import { readFileSync, writeFileSync } from "node:fs";
 import { dirname, join } from "node:path";