@kevlns/v-cli 0.2.0-beta.4 → 0.2.0

package/AGENTS.md

@@ -7,12 +7,13 @@
 
 ## 核心约定（v-cli 本体）
 
-- 环境要求 Node.js >= 20；v-cli 版本 @kevlns/v-cli@0.2.0-beta.4
+- 环境要求 Node.js >= 20；v-cli 版本 @kevlns/v-cli@0.2.0
 - 命令分三类：builtin（内置）、local（~/.v-cli/commands/ 下的本地插件）、official（官方插件白名单）；
   **最新、live 的命令集合以实际发现为准**：先运行 `v-cli agent index --json` 获取全部命令与 agent 元数据
 - 单个命令的完整元数据用 `v-cli agent describe <命令名> --json` 查看
 - AI Agent 引导文档：`v-cli agent docs` 输出本文件原文（`--json` 含 sha256/content）；
-  `v-cli agent init .` 把它写入工作区（已存在默认拒绝，`--force` 覆盖，`--dry-run` 预览；符号链接目标 fail-closed）
+  `v-cli agent init .` 把它写入工作区（已存在默认拒绝，`--force` 覆盖，`--dry-run` 预览；符号链接目标 fail-closed）；
+  同时把随包发布的 v-cli skill（skills/v-cli）装配到 <目录> 下匹配的 agent 技能目录（如 .claude/skills、.agent/skill、AgentHome/skills 等，清单见 src/core/agent-dirs.ts），无匹配则跳过
 - **首次调用规范**：首次调用任何 official 插件命令前，必须先运行 `v-cli agent docs <命令名>`，
   掌握该插件包内 `AGENTS.md`；使用规范、快速流程与禁止事项以插件 AGENTS.md 为准。
 - 官方插件命令（`v-cli xlmerge …`、`v-cli unity …`）在子进程中运行（stdio 继承）：v-cli 只做路由，
@@ -22,7 +23,7 @@
 
 ## @kevlns/u-cli-mod — 命令 `v-cli unity …`
 
-**版本**：0.1.0-beta.4
+**版本**：0.1.0
 **描述**：Pin a Unity project to its exact editor version route, download the verified Unity CLI and install the adapted com.unity.pipeline package for Unity 2022 (Windows-first, non-official Unity tooling).
 **平台**：win32（仅 Windows 主机可用；非 Windows 上 v-cli 会拒绝路由）
 
@@ -33,7 +34,7 @@
 
 ## @kevlns/xlmerge — 命令 `v-cli xlmerge …`
 
-**版本**：1.2.1-beta.5
+**版本**：1.2.1
 **描述**：Visual resolver for Git merge conflicts in .xlsx/.xlsm planning tables: three-way sheet/row/cell diff, local UI, write-back and commit.
 **平台**：darwin, linux, win32
 

package/dist/cli.mjs

@@ -75,8 +75,8 @@ function defaultHomeDir() {
 }
 
 // src/core/loader.ts
-import fs5 from "fs";
-import path7 from "path";
+import fs6 from "fs";
+import path8 from "path";
 import { pathToFileURL } from "url";
 
 // src/core/official.ts
@@ -618,7 +618,7 @@ function validateLocalCommand(candidate, options = {}) {
 }
 
 // src/commands/agent.ts
-import path5 from "path";
+import path6 from "path";
 
 // src/core/agent-docs.ts
 import fs3 from "fs";
@@ -627,7 +627,7 @@ import { createHash, randomBytes } from "crypto";
 import { fileURLToPath as fileURLToPath2 } from "url";
 
 // src/version.ts
-var VERSION = "0.2.0-beta.4";
+var VERSION = "0.2.0";
 
 // src/core/agent-docs.ts
 var BUNDLED_DOCS_FILE = "AGENTS.md";
@@ -849,7 +849,140 @@ function atomicWrite(target, content) {
   throw new Error(`\u539F\u5B50\u5199\u5165\u5931\u8D25\uFF08\u4E34\u65F6\u6587\u4EF6\u547D\u540D\u78B0\u649E\u91CD\u8BD5 ${MAX_TMP_RETRIES} \u6B21\u672A\u679C\uFF09: ${detail}`);
 }
 
+// src/core/agent-skill.ts
+import fs4 from "fs";
+import path5 from "path";
+
+// src/core/agent-dirs.ts
+var AGENT_SKILL_DIRS = [
+  ".claude/skills",
+  ".claude/skill",
+  ".cursor/skills",
+  ".cursor/rules",
+  ".github/prompts",
+  ".gemini/skills",
+  ".codex/skills",
+  ".agents/skills",
+  ".agent/skills",
+  ".agent/skill",
+  "AgentHome/skills",
+  ".windsurf/skills",
+  ".trae/skills",
+  ".kilocode/skills",
+  ".roo/skills",
+  ".opencode/skills",
+  ".augment/skills",
+  ".kiro/skills",
+  ".amazonq/skills",
+  ".continue/skills"
+];
+
+// src/core/agent-skill.ts
+var SKILL_NAME = "v-cli";
+var SKILL_FILE = "SKILL.md";
+function resolveSkillSourceRoot(opts = {}) {
+  const agentsMd = resolveBundledAgentsMd(opts);
+  if (!agentsMd) return void 0;
+  const root = path5.join(path5.dirname(agentsMd), "skills", SKILL_NAME);
+  try {
+    if (fs4.statSync(root).isDirectory()) return root;
+  } catch {
+  }
+  return void 0;
+}
+function readSkillSource(opts = {}) {
+  const root = resolveSkillSourceRoot(opts);
+  if (!root) {
+    throw new Error(
+      `\u65E0\u6CD5\u5B9A\u4F4D ${BUNDLED_DOCS_PACKAGE} \u5185\u7F6E skill\uFF08skills/${SKILL_NAME}\uFF09\uFF1A\u8BF7\u786E\u8BA4\u5B89\u88C5\u7684\u5305\u5185\u5305\u542B skills/ \u76EE\u5F55\uFF08\u91CD\u65B0\u5B89\u88C5 @kevlns/v-cli \u540E\u91CD\u8BD5\uFF09\u3002`
+    );
+  }
+  const file = path5.join(root, SKILL_FILE);
+  let content;
+  try {
+    if (!fs4.lstatSync(file).isFile()) throw new Error("\u5165\u53E3\u4E0D\u662F\u666E\u901A\u6587\u4EF6");
+    content = fs4.readFileSync(file, "utf-8");
+  } catch (err) {
+    throw new Error(
+      `\u65E0\u6CD5\u8BFB\u53D6 ${BUNDLED_DOCS_PACKAGE} \u5185\u7F6E skill\uFF08${file}\uFF09: ${err instanceof Error ? err.message : String(err)}`
+    );
+  }
+  return {
+    root,
+    file,
+    content,
+    sha256: sha256Hex(content),
+    bytes: Buffer.byteLength(content, "utf-8")
+  };
+}
+function collectAgentSkillDirs(directory) {
+  const hits = [];
+  for (const rel of AGENT_SKILL_DIRS) {
+    const abs = path5.join(directory, rel);
+    try {
+      if (fs4.statSync(abs).isDirectory()) hits.push(abs);
+    } catch {
+    }
+  }
+  return hits;
+}
+function copySkillDir(srcRoot, destDir) {
+  fs4.rmSync(destDir, { recursive: true, force: true });
+  fs4.cpSync(srcRoot, destDir, { recursive: true });
+}
+function performAgentSkillAssembly(opts) {
+  const { directory, source, dryRun = false } = opts;
+  const base = {
+    ok: true,
+    dryRun,
+    directory,
+    assembled: [],
+    skill: { name: SKILL_NAME, sha256: source.sha256, bytes: source.bytes }
+  };
+  let dirStat;
+  try {
+    dirStat = fs4.statSync(directory);
+  } catch {
+    return { ...base, ok: false, reason: `\u76EE\u6807\u76EE\u5F55\u4E0D\u5B58\u5728\u6216\u4E0D\u53EF\u8BBF\u95EE: ${directory}` };
+  }
+  if (!dirStat.isDirectory()) {
+    return { ...base, ok: false, reason: `\u76EE\u6807\u4E0D\u662F\u76EE\u5F55: ${directory}` };
+  }
+  const hits = collectAgentSkillDirs(directory);
+  for (const dir of hits) {
+    const target = path5.join(dir, SKILL_NAME);
+    let overwrite = false;
+    try {
+      fs4.lstatSync(target);
+      overwrite = true;
+    } catch {
+      overwrite = false;
+    }
+    const action = dryRun ? "assemble" : "assembled";
+    if (!dryRun) {
+      copySkillDir(source.root, target);
+    }
+    base.assembled.push({ dir, target, action, overwrite });
+  }
+  return base;
+}
+
 // src/commands/agent.ts
+function skillOutcomeText(outcome, dryRun) {
+  const verb = dryRun ? "\u5C06\u88C5\u914D\u5230" : "\u5DF2\u88C5\u914D\u5230";
+  switch (outcome.status) {
+    case "assembled": {
+      const dirs = outcome.assembled.map((t) => t.dir).join(", ");
+      return `[skill v-cli] ${verb} ${outcome.assembled.length} \u4E2A agent \u76EE\u5F55\uFF1A${dirs}`;
+    }
+    case "skipped-none":
+      return "[skill v-cli] \u672A\u68C0\u6D4B\u5230\u5339\u914D\u7684 agent \u6280\u80FD\u76EE\u5F55\uFF0C\u8DF3\u8FC7\u88C5\u914D";
+    case "skipped-source-missing":
+      return `[skill v-cli] \u8DF3\u8FC7\u88C5\u914D\uFF08\u6E90\u7F3A\u5931\uFF09\uFF1A${outcome.reason}`;
+    case "skipped-init-failed":
+      return "[skill v-cli] \u8DF3\u8FC7\u88C5\u914D\uFF08AGENTS.md \u672A\u5C31\u7EEA\uFF09";
+  }
+}
 function buildAgentIndex(builtin, local, official) {
   const rows = [];
   for (const cmd of builtin) {
@@ -964,7 +1097,8 @@ var DOCS_HELP_TEXT = [
   "  v-cli agent docs xlmerge --json"
 ].join("\n");
 var INIT_HELP_TEXT = [
-  "\u628A\u5F53\u524D @kevlns/v-cli \u5305\u5185\u7F6E AGENTS.md \u539F\u6837\u5199\u5165 <\u76EE\u5F55>/AGENTS.md\uFF0CAI Agent \u4F1A\u81EA\u52A8\u8BFB\u53D6\u5DE5\u4F5C\u533A\u6587\u6863\u3002",
+  "\u628A\u5F53\u524D @kevlns/v-cli \u5305\u5185\u7F6E AGENTS.md \u539F\u6837\u5199\u5165 <\u76EE\u5F55>/AGENTS.md\uFF0CAI Agent \u4F1A\u81EA\u52A8\u8BFB\u53D6\u5DE5\u4F5C\u533A\u6587\u6863\uFF1B",
+  "\u540C\u65F6\u628A\u968F\u5305\u53D1\u5E03\u7684 v-cli skill\uFF08skills/v-cli\uFF09\u88C5\u914D\u5230 <\u76EE\u5F55> \u4E0B\u5339\u914D\u7684 agent \u6280\u80FD\u76EE\u5F55\uFF08\u5982 .claude/skills\u3001.agent/skill\u3001AgentHome/skills \u7B49\uFF0C\u6E05\u5355\u89C1 src/core/agent-dirs.ts\uFF09\uFF0C\u65E0\u5339\u914D\u76EE\u5F55\u5219\u8DF3\u8FC7\u3002",
   "",
   "\u53C2\u6570\uFF1A",
   "  [directory]  \u76EE\u6807\u76EE\u5F55\uFF0C\u9ED8\u8BA4\u5F53\u524D\u5DE5\u4F5C\u76EE\u5F55\uFF1B\u5FC5\u987B\u5DF2\u5B58\u5728\u4E14\u4E3A\u76EE\u5F55",
@@ -1036,7 +1170,7 @@ var agent = {
       {
         path: ["init"],
         usage: "v-cli agent init [directory] [--force] [--dry-run] [--json]",
-        description: "\u628A\u5185\u7F6E AGENTS.md \u5199\u5165 <\u76EE\u5F55>/AGENTS.md\uFF1B\u9ED8\u8BA4\u5F53\u524D\u76EE\u5F55\uFF1B\u5DF2\u5B58\u5728\u9ED8\u8BA4\u62D2\u7EDD",
+        description: "\u521D\u59CB\u5316 <\u76EE\u5F55>\uFF1A\u5199\u5165 AGENTS.md \u5E76\u88C5\u914D v-cli skill \u5230\u5339\u914D\u7684 agent \u6280\u80FD\u76EE\u5F55\uFF1B\u9ED8\u8BA4\u5F53\u524D\u76EE\u5F55\uFF1B\u5DF2\u5B58\u5728\u9ED8\u8BA4\u62D2\u7EDD",
         arguments: [
           { name: "directory", required: false, description: "\u76EE\u6807\u76EE\u5F55\uFF08\u9ED8\u8BA4\u5F53\u524D\u5DE5\u4F5C\u76EE\u5F55\uFF1B\u987B\u5DF2\u5B58\u5728\u4E14\u4E3A\u76EE\u5F55\uFF09" }
         ],
@@ -1047,7 +1181,7 @@ var agent = {
         ],
         output: {
           format: "stdout",
-          description: "\u7ED3\u679C\u6587\u672C\u8F93\u51FA\u5230 stdout\uFF1B--json \u65F6\u8F93\u51FA\u7A33\u5B9A JSON\uFF08ok/dryRun/action/directory/target/package/version/sha256/bytes\uFF09"
+          description: "\u7ED3\u679C\u6587\u672C\u8F93\u51FA\u5230 stdout\uFF1B--json \u65F6\u8F93\u51FA\u7A33\u5B9A JSON\uFF08ok/dryRun/action/directory/target/package/version/sha256/bytes \u53CA skill \u88C5\u914D\u7ED3\u679C\uFF09"
         },
         exitCodes: {
           "0": "\u6210\u529F\u6216\u5E72\u8DD1",
@@ -1058,7 +1192,8 @@ var agent = {
           "refuses-existing",
           "fail-closed-symlink",
           "dry-run-supported",
-          "no-commit"
+          "no-commit",
+          "assembles-skill"
         ]
       }
     ]
@@ -1153,16 +1288,48 @@ var agent = {
           process.exitCode = 1;
           return;
         }
+        const resolvedDir = path6.resolve(directory ?? process.cwd());
         const result = performAgentInit({
-          directory: path5.resolve(directory ?? process.cwd()),
+          directory: resolvedDir,
           docs,
           force: opts.force,
           dryRun: opts.dryRun,
           // 显式传入目录才做目录符号链接/联接 fail-closed；默认 cwd 不受限
           explicitDirectory: directory !== void 0
         });
+        let skillOutcome;
+        if (result.ok) {
+          try {
+            const source = readSkillSource();
+            const skill = performAgentSkillAssembly({
+              directory: resolvedDir,
+              source,
+              dryRun: opts.dryRun
+            });
+            skillOutcome = skill.assembled.length > 0 ? {
+              status: "assembled",
+              assembled: skill.assembled,
+              name: skill.skill.name,
+              sha256: skill.skill.sha256,
+              bytes: skill.skill.bytes
+            } : {
+              status: "skipped-none",
+              assembled: [],
+              name: skill.skill.name,
+              sha256: skill.skill.sha256,
+              bytes: skill.skill.bytes
+            };
+          } catch (err) {
+            skillOutcome = {
+              status: "skipped-source-missing",
+              reason: err instanceof Error ? err.message : String(err)
+            };
+          }
+        } else {
+          skillOutcome = { status: "skipped-init-failed" };
+        }
         if (json) {
-          ctx.log.result(result);
+          ctx.log.result({ ...result, skill: skillOutcome });
           if (!result.ok && result.reason) ctx.log.error(result.reason);
           if (!result.ok) process.exitCode = 1;
           return;
@@ -1172,15 +1339,8 @@ var agent = {
           process.exitCode = 1;
           return;
         }
-        if (result.dryRun) {
-          ctx.log.result(
-            `[dry-run] \u5C06${result.action === "overwrite" ? "\u8986\u76D6" : "\u5199\u5165"} ${result.target}\uFF08${result.bytes} \u5B57\u8282\uFF09`
-          );
-        } else {
-          ctx.log.result(
-            `\u5DF2${result.action === "overwritten" ? "\u8986\u76D6" : "\u5199\u5165"} ${result.target}\uFF08${result.bytes} \u5B57\u8282\uFF0CSHA-256 ${result.sha256.slice(0, 12)}\u2026\uFF09`
-          );
-        }
+        const head = result.dryRun ? `[dry-run] \u5C06${result.action === "overwrite" ? "\u8986\u76D6" : "\u5199\u5165"} ${result.target}\uFF08${result.bytes} \u5B57\u8282\uFF09` : `\u5DF2${result.action === "overwritten" ? "\u8986\u76D6" : "\u5199\u5165"} ${result.target}\uFF08${result.bytes} \u5B57\u8282\uFF0CSHA-256 ${result.sha256.slice(0, 12)}\u2026\uFF09`;
+        ctx.log.result([head, skillOutcomeText(skillOutcome, result.dryRun)].join("\n"));
       }
     );
     program.addHelpText("after", AGENT_HELP_TEXT);
@@ -1188,7 +1348,7 @@ var agent = {
 };
 
 // src/commands/doctor.ts
-import fs4 from "fs";
+import fs5 from "fs";
 var doctor = {
   name: "doctor",
   description: "\u4F53\u68C0\uFF1Anode/v-cli \u7248\u672C\u3001homeDir\u3001config\u3001\u63D2\u4EF6\u72B6\u6001",
@@ -1197,7 +1357,7 @@ var doctor = {
     program.option("--json", "\u8F93\u51FA\u673A\u5668\u53EF\u8BFB JSON").action(async (opts) => {
       const json = ctx.json || opts.json;
       const homeDir = ctx.homeDir;
-      const exists = fs4.existsSync(homeDir);
+      const exists = fs5.existsSync(homeDir);
       let configWritable = false;
       try {
         ctx.config.set((cfg) => cfg);
@@ -1251,7 +1411,7 @@ var doctor = {
 };
 
 // src/commands/plugin.ts
-import path6 from "path";
+import path7 from "path";
 var plugin = {
   name: "plugin",
   description: "\u63D2\u4EF6\u7BA1\u7406\uFF1Alist \u5217\u51FA\u547D\u4EE4\uFF0Cpath \u663E\u793A\u672C\u5730\u63D2\u4EF6\u76EE\u5F55",
@@ -1290,7 +1450,7 @@ var plugin = {
       }
     });
     program.command("path").description("\u6253\u5370\u672C\u5730\u63D2\u4EF6\u76EE\u5F55\uFF08\u653E\u5165 .mjs \u6587\u4EF6\u5373\u751F\u6548\uFF09").option("--json", "\u8F93\u51FA\u673A\u5668\u53EF\u8BFB JSON").action((opts) => {
-      const dir = path6.join(ctx.homeDir, "commands");
+      const dir = path7.join(ctx.homeDir, "commands");
       if (ctx.json || opts.json) {
         ctx.log.result({ dir });
       } else {
@@ -1358,12 +1518,12 @@ async function loadBuiltinCommands() {
   return builtinCommands.map((command) => ({ command, source: "builtin" }));
 }
 async function loadLocalPlugins(ctx) {
-  const dir = path7.join(ctx.homeDir, "commands");
+  const dir = path8.join(ctx.homeDir, "commands");
   const loaded = [];
-  if (!fs5.existsSync(dir)) return loaded;
-  const files = fs5.readdirSync(dir).filter((f) => f.endsWith(".mjs")).sort();
+  if (!fs6.existsSync(dir)) return loaded;
+  const files = fs6.readdirSync(dir).filter((f) => f.endsWith(".mjs")).sort();
   for (const file of files) {
-    const abs = path7.join(dir, file);
+    const abs = path8.join(dir, file);
     try {
       const mod = await import(
         /* @vite-ignore */

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@kevlns/v-cli",
-  "version": "0.2.0-beta.4",
+  "version": "0.2.0",
   "description": "kevlns 的个人工具箱 CLI（插件化架构，内置 + 本地插件）+ doctor/plugin/ts 命令",
   "type": "module",
   "bin": {
@@ -9,6 +9,7 @@
   "files": [
     "dist/",
     "schemas/",
+    "skills/",
     "AGENTS.md"
   ],
   "scripts": {
@@ -46,8 +47,8 @@
   ],
   "dependencies": {
     "commander": "^12.1.0",
-    "@kevlns/xlmerge": "1.2.1-beta.5",
-    "@kevlns/u-cli-mod": "0.1.0-beta.4"
+    "@kevlns/xlmerge": "1.2.1",
+    "@kevlns/u-cli-mod": "0.1.0"
   },
   "devDependencies": {
     "@types/node": "^20.14.0",

package/skills/v-cli/SKILL.md

@@ -0,0 +1,80 @@
+---
+name: v-cli
+description: >
+  使用 kevlns 的个人工具箱 CLI（v-cli）处理配置表冲突与 Unity 工程精确版本工具链。当任务提到 v-cli、xlmerge、
+  unity 命令、配置表 .xlsx/.xlsm Git 冲突处理、Unity CLI 安装、Unity 工程诊断/体检（doctor）、
+  com.unity.pipeline 适配包安装时使用本 skill。
+---
+
+# v-cli 使用规范
+
+## 工具概述
+
+- `@kevlns/v-cli` 是 npm 全局安装的个人工具箱 CLI（当前 0.2.0-beta.x），插件化架构。
+- 命令分三类：
+  - **builtin**（内置）：`doctor`（环境体检）、`plugin list/path`（插件管理）、`ts`（时间戳互转）、`agent index/describe/docs/init`（agent 引导）。
+  - **local**：`~/.v-cli/commands/` 下的本地插件（本项目未使用）。
+  - **official**（官方插件，经 v-cli 路由）：`xlmerge`、`unity`。
+- 环境要求：Node.js >= 20（仅 Windows 主机可使用 `unity` 插件，其他平台 v-cli 拒绝路由）。
+
+## 能力发现协议（核心规则，必须遵守）
+
+**一切能力、参数、用法以 v-cli 自己的 agent 命令输出为准，严禁无头搜索 npm 安装目录、源码或 README 猜测用法。**
+
+- `v-cli agent docs` — 输出 v-cli 内置 AGENTS.md（宿主规范全文；`--json` 含 sha256/content）。
+- `v-cli agent index --json` — 枚举全部命令（builtin/local/official）与 agent 元数据，获取最新命令集合。
+- `v-cli agent describe <命令名> --json` — 单个命令的完整记录：用法、参数、选项、输出格式、退出码、安全标签。
+- `v-cli agent docs <命令名>` — 输出官方插件包内 AGENTS.md（该插件的使用规范正本）。
+- `v-cli agent init .` — 可选：把内置 AGENTS.md 写入工作区（已存在默认拒绝，`--force` 覆盖，`--dry-run` 预览）。
+- live 命令集合以实际发现为准：先 `agent index --json`，再对目标命令 `agent describe <命令> --json`。
+
+## 首调规范
+
+**首次调用任何 official 插件命令（`v-cli xlmerge …`、`v-cli unity …`）前，必须先运行 `v-cli agent docs <命令名>` 读取该插件包内的 AGENTS.md 规范正本。** 使用规范、快速流程与禁止事项以插件自身 AGENTS.md 为准。
+
+官方插件命令在子进程中运行（stdio 继承）：v-cli 只做路由，不解析、不改写插件输出；插件 `--help`/`--json` 等参数由插件自己消费。插件对 worktree 的写入/提交行为以插件清单的安全标签为准；**未经显式 flag 不得 push**。
+
+## 官方插件一：xlmerge（跨平台）
+
+Git 中 `.xlsx` / `.xlsm` 策划表/配置表冲突的可视化解决工具。
+
+- 流程：
+  1. `v-cli xlmerge --repo <仓库路径> detect` — 检测冲突。
+  2. 冲突数 > 0 时运行 `launch`，**把返回的 URL 交给用户在本地 UI 处理**。
+- **agent 不得自行检查工作簿单元格、不得自己总结 diff**：resolver 拥有 diff、选择、写回与提交。
+- 用户要求「解决配置表冲突」时：先 detect；count > 0 时 launch 并给出 URL。
+
+## 官方插件二：unity（仅 win32）
+
+Unity 2022 工程**精确版本路由**（版本号 + revision 双重匹配）+ 下载经验证的 Unity CLI（SHA-256 + Authenticode）+ 事务式安装适配版 `com.unity.pipeline` 包。
+
+### 核心命令
+
+| 命令 | 说明 |
+|---|---|
+| `v-cli unity doctor <project>` | 只读体检：路由匹配 / CLI 状态 / Pipeline 状态 / 运行中的 Unity 进程 / 支持版本列表 |
+| `v-cli unity setup <project>` | CLI + 适配包一键就绪（**推荐首次入口**，等价 cli install + pipeline install；`--dry-run` 预览、`--skip-cli` 跳过下载） |
+| `v-cli unity pipeline install <project>` | 事务式安装适配包（staging → 校验 → 备份 → 替换 → 再校验 → receipt，失败自动回滚；`--dry-run` 只预览不写入） |
+| `v-cli unity cli install` | 下载并校验固定版本 Unity CLI（`--editor <版本>` 限定、`--force` 重下） |
+| `v-cli unity exec <project> -- <unity-cli-args>` | 调用路由 CLI 执行 Unity Pipeline 命令 |
+| `v-cli unity routes` | 列出所有已配置的 Editor 精确路由（`-e <版本>` 过滤） |
+| `v-cli unity cache clean` | 清理下载缓存与生成的适配包（`--all` 连 CLI 缓存一起清） |
+
+### 关键规则（违反即报错或导致损坏，必须遵守）
+
+1. **exec 前必须 doctor 通过且适配包已安装**（setup 或 pipeline install 已完成）；未就绪时先跑 setup，不要直接 exec。
+2. **禁止在 exec 参数中传入任何 `--project-path` 变体**（`-projectPath`、`--project_path`、大小写混合、`=` 形式等）：目标工程由工具统一绑定，exec 会拒绝所有变体并把解析后的 `--project-path` 作为最后一个参数附加；`--` 分隔符被包装器消费，不转发给 Unity CLI。
+3. **运行中的 Unity Editor 是 fail-closed**：安装被阻止时引导用户先关闭目标工程的 Editor；**除非用户显式要求，不得使用 `--allow-running-editor` 绕过**。
+4. **安装是事务式的**：不要手动清理工程内 `Packages/com.unity.pipeline` 或 `Library/editor-pipeline-cli`；失败会自动回滚，人为清理会破坏回滚与 receipt 校验。
+5. **版本路由是精确匹配**（`m_EditorVersion` + revision 同时一致），无"就近版本"回退；工程版本不在路由表内时如实报告支持列表（`doctor` 输出的 `supportedVersions`），不得猜测、不得改写 `ProjectVersion.txt`。
+6. **exec 每次调用前都会重新校验 CLI 哈希**（防篡改，属正常行为）；校验失败按提示 `v-cli unity cli install --force` 修复即可。
+
+## 典型流程
+
+```bash
+v-cli agent docs unity                                    # 首调前必读插件规范正本
+v-cli unity doctor <project>                              # 1. 体检（只读）
+v-cli unity setup <project> --dry-run                     # 2.（可选）先预览
+v-cli unity setup <project>                               # 3. 就绪（CLI + 适配包）
+v-cli unity exec <project> -- command editor_status       # 4. 执行 Pipeline 命令
+```