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

package/AGENTS.md

@@ -7,12 +7,14 @@
 
 ## 核心约定（v-cli 本体）
 
-- 环境要求 Node.js >= 20；v-cli 版本 @kevlns/v-cli@0.2.0-beta.2
+- 环境要求 Node.js >= 20；v-cli 版本 @kevlns/v-cli@0.2.0-beta.4
 - 命令分三类：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）
+- **首次调用规范**：首次调用任何 official 插件命令前，必须先运行 `v-cli agent docs <命令名>`，
+  掌握该插件包内 `AGENTS.md`；使用规范、快速流程与禁止事项以插件 AGENTS.md 为准。
 - 官方插件命令（`v-cli xlmerge …`、`v-cli unity …`）在子进程中运行（stdio 继承）：v-cli 只做路由，
   不解析、不改写插件的 stdout/stderr；插件 `--help`/`--json` 等参数由插件自己消费
 - 插件对 worktree 的写入/提交行为以插件清单 v-cli.plugin.json 的 `agent.safety` 为准：
@@ -20,55 +22,25 @@
 
 ## @kevlns/u-cli-mod — 命令 `v-cli unity …`
 
-**版本**：0.1.0-beta.2
+**版本**：0.1.0-beta.4
 **描述**：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 会拒绝路由）
 
 **何时使用**：Use for Windows-first Unity Editor 2022 workflows that must stay pinned to an exact editor version: diagnose a project against its route, list pinned routes, download the verified Unity CLI, transactionally install the adapted com.unity.pipeline package, or run Unity Pipeline CLI commands with enforced project targeting. Never use on non-Windows hosts.
 
-**全局选项**：
-- `-V, --version` — output the version number
-- `-h, --help` — display help for command
-
-**子命令**：
-- `doctor` — 检查工程版本、路由、CLI 与 Pipeline 状态（用法：`v-cli unity doctor <project> [options]`）
-  - 安全标签：read-only; never writes the project or the cache；fail-closed exact m_EditorVersion + m_EditorVersionWithRevision match (no wildcard, no fallback)；queries running Unity.exe processes via PowerShell; a failed query is reported in the unityProcesses output, not fatal
-- `routes` — 列出所有已配置的 Editor 精确路由（用法：`v-cli unity routes [options]`）
-  - 安全标签：read-only; no network access；uses only embedded pinned route metadata shipped in the package
-- `cli install` — 下载并校验固定版本的 Unity CLI（SHA-256 + Authenticode）（用法：`v-cli unity cli install [options]`）
-  - 安全标签：writes only under the user cache: %LOCALAPPDATA%\editor-pipeline-cli\cache\cli；downloads from the pinned Unity official CDN HTTPS URL only；verifies fixed SHA-256 + expected size + Authenticode signer subject and certificate thumbprint before the binary is placed；unverified temp download is deleted on any failure; the final file is created by atomic rename
-- `pipeline install` — 按工程 Editor 版本事务式安装适配后的 com.unity.pipeline（用法：`v-cli unity pipeline install <project> [options]`）
-  - 安全标签：transactional install: stage -> verify -> backup -> replace -> re-verify -> receipt; automatic rollback on any failure；fail-closed when a matching Unity Editor is running, unless --allow-running-editor；--dry-run never writes the project and never writes a receipt；source and destination trees must match the pinned expected-tree (385 files, SHA-256) before and after placement；writes only under <project>/Packages/com.unity.pipeline and <project>/Library/editor-pipeline-cli
-- `setup` — cli install + pipeline install（用法：`v-cli unity setup <project> [options]`）
-  - 安全标签：combines the cli install and pipeline install safety contracts；fail-closed running-Editor guard unless --allow-running-editor；--dry-run never writes the project；--skip-cli avoids all CLI downloads
-- `exec` — 调用路由 CLI 执行 Unity Pipeline 命令；--project-path 由工具统一绑定（用法：`v-cli unity exec <project> [options] -- <unity-cli-args...>`）
-  - 安全标签：re-verifies the pinned CLI SHA-256 before every invocation (fail-closed on tamper)；rejects every --project-path variant (case-insensitive: --project-path, --projectPath, -projectPath, --project_path, mixed case)；always appends the resolved --project-path as the final argument; the wrapper owns project targeting；no route fallback: the project must match a pinned route exactly；the documented -- separator is consumed by the wrapper and never forwarded to the Unity CLI
-- `cache clean` — 清理下载缓存与生成的适配包（用法：`v-cli unity cache clean [options]`）
-  - 安全标签：removes only directories under the user cache root %LOCALAPPDATA%\editor-pipeline-cli；default scope: generated packages + pipeline downloads only; without --all the CLI cache and logs are preserved
+**首次调用前必读**：`v-cli agent docs unity`（插件包内 AGENTS.md 规范正本）
+**实时参数/命令**：`v-cli agent describe unity --json`
 
 ## @kevlns/xlmerge — 命令 `v-cli xlmerge …`
 
-**版本**：1.2.1-beta.2
+**版本**：1.2.1-beta.5
 **描述**：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
 
 **何时使用**：When a user asks to resolve Git merge conflicts in .xlsx/.xlsm planning or configuration tables (策划表/配置表冲突): run detect first; when count > 0 run launch and give the returned url to the user. Do not inspect workbook cells or summarize diffs yourself; the resolver owns diff, choices, write-back and commit.
 
-**全局选项**：
-- `--repo <path>` — Git repository (default: current directory; searches upward for the Git root).
-- `--runtime-dir <dir>` — Optional directory for extracted Git stage workbooks and manifest (default: system temp). Used by prepare, resolve and launch.
-
-**子命令**：
-- `detect` — List unresolved .xlsx/.xlsm files in the repository.（用法：`v-cli xlmerge --repo <repo> detect`）
-  - 安全标签：read-only；no-worktree-modification
-- `prepare` — Extract base/ours/theirs stage versions from the Git index and build a sheet-aware manifest.（用法：`v-cli xlmerge --repo <repo> prepare [--path <file>]`）
-  - 安全标签：writes-runtime-dir；no-worktree-modification；no-commit
-- `resolve` — Prepare conflicts and serve the local visual resolver in the foreground (blocking).（用法：`v-cli xlmerge --repo <repo> resolve [--path <file>] [--no-browser]`）
-  - 安全标签：blocking；binds-loopback；opens-browser-by-default；no-push；writes-runtime-dir；writes-worktree-via-ui；commits-by-default-via-ui
-- `launch` — Prepare conflicts, start the visual resolver in the background and return its URL.（用法：`v-cli xlmerge --repo <repo> launch [--path <file>] [--no-browser]`）
-  - 安全标签：starts-background-server；binds-loopback；opens-browser-by-default；no-push；writes-runtime-dir；writes-worktree-via-ui；commits-by-default-via-ui
-- `apply` — Write back decisions from a decisions JSON without launching the UI.（用法：`v-cli xlmerge --repo <repo> apply --manifest <manifest.json> --decisions <decisions.json> [--no-commit] [--push] [--message <text>]`）
-  - 安全标签：writes-worktree；commits-by-default；pushes-only-with-flag
+**首次调用前必读**：`v-cli agent docs xlmerge`（插件包内 AGENTS.md 规范正本）
+**实时参数/命令**：`v-cli agent describe xlmerge --json`
 
 ---
 

package/dist/cli.mjs

@@ -627,7 +627,7 @@ import { createHash, randomBytes } from "crypto";
 import { fileURLToPath as fileURLToPath2 } from "url";
 
 // src/version.ts
-var VERSION = "0.2.0-beta.2";
+var VERSION = "0.2.0-beta.4";
 
 // src/core/agent-docs.ts
 var BUNDLED_DOCS_FILE = "AGENTS.md";
@@ -699,6 +699,51 @@ function readBundledAgentsMd(opts = {}) {
     bytes: Buffer.byteLength(content, "utf-8")
   };
 }
+function readOfficialAgentsMd(command, opts = {}) {
+  const spec = OFFICIAL_PLUGINS.find((item) => item.command === command);
+  if (!spec) {
+    throw new Error(
+      `\u672A\u627E\u5230\u5B98\u65B9\u63D2\u4EF6\u547D\u4EE4: ${command}\u3002\u8BF7\u5148\u8FD0\u884C v-cli agent index --json \u67E5\u770B\u53EF\u7528\u5B98\u65B9\u63D2\u4EF6\u3002`
+    );
+  }
+  const resolvePackage = opts.resolvePackage ?? defaultResolvePackage;
+  const pkgJsonPath = resolvePackage(spec.package);
+  if (!pkgJsonPath) {
+    throw new Error(
+      `\u672A\u5B89\u88C5\u5B98\u65B9\u63D2\u4EF6\u5305 ${spec.package}\uFF08\u547D\u4EE4 ${command}\uFF09\uFF0C\u6216\u5B83\u4E0D\u5728\u53EF\u89E3\u6790\u8DEF\u5F84\u3002\u8BF7\u5148\u5B89\u88C5\u540E\u91CD\u8BD5\u3002`
+    );
+  }
+  let pkgJson;
+  try {
+    pkgJson = JSON.parse(fs3.readFileSync(pkgJsonPath, "utf-8"));
+  } catch (err) {
+    throw new Error(
+      `\u65E0\u6CD5\u8BFB\u53D6\u5B98\u65B9\u63D2\u4EF6 ${spec.package} \u7684 package.json\uFF08${pkgJsonPath}\uFF09: ${err instanceof Error ? err.message : String(err)}`
+    );
+  }
+  if (pkgJson.name !== spec.package || typeof pkgJson.version !== "string") {
+    throw new Error(`\u5B98\u65B9\u63D2\u4EF6 package.json \u8EAB\u4EFD\u65E0\u6548: \u671F\u671B ${spec.package} \u4E14 version \u4E3A\u5B57\u7B26\u4E32\u3002`);
+  }
+  const file = path4.join(path4.dirname(pkgJsonPath), BUNDLED_DOCS_FILE);
+  let content;
+  try {
+    if (!fs3.lstatSync(file).isFile()) throw new Error("\u76EE\u6807\u4E0D\u662F\u666E\u901A\u6587\u4EF6");
+    content = fs3.readFileSync(file, "utf-8");
+  } catch (err) {
+    throw new Error(
+      `\u5B98\u65B9\u63D2\u4EF6 ${spec.package}@${pkgJson.version} \u672A\u63D0\u4F9B\u53EF\u8BFB\u7684 ${BUNDLED_DOCS_FILE}\uFF08${file}\uFF09: ${err instanceof Error ? err.message : String(err)}\u3002\u8BF7\u5347\u7EA7\u6216\u91CD\u65B0\u5B89\u88C5\u8BE5\u63D2\u4EF6\u3002`
+    );
+  }
+  return {
+    package: spec.package,
+    command,
+    version: pkgJson.version,
+    file,
+    content,
+    sha256: sha256Hex(content),
+    bytes: Buffer.byteLength(content, "utf-8")
+  };
+}
 function sha256Hex(content) {
   return createHash("sha256").update(content, "utf-8").digest("hex");
 }
@@ -880,7 +925,7 @@ var AGENT_HELP_TEXT = [
   "agent \u5B50\u547D\u4EE4\u4E00\u89C8\uFF1A",
   "  index    \u5217\u51FA\u5168\u90E8\u547D\u4EE4\uFF08builtin/local/official\uFF09\u4E0E agent \u5143\u6570\u636E\uFF1B--json \u8F93\u51FA\u7A33\u5B9A JSON \u6570\u7EC4",
   "  describe \u67E5\u770B\u5355\u4E2A\u547D\u4EE4\u7684\u5B8C\u6574\u8BB0\u5F55\uFF08\u7528\u6CD5/\u53C2\u6570/\u9009\u9879/\u8F93\u51FA/\u9000\u51FA\u7801/\u5B89\u5168\u6807\u7B7E\uFF09\uFF1B--json \u8F93\u51FA\u5355\u6761\u8BB0\u5F55",
-  "  docs     \u8F93\u51FA\u5F53\u524D @kevlns/v-cli \u5305\u5185\u7F6E AGENTS.md \u539F\u6587\uFF1B--json \u8F93\u51FA { package, version, sha256, content }",
+  "  docs     \u65E0\u53C2\u8F93\u51FA v-cli AGENTS.md\uFF1B\u4F20 <command> \u8F93\u51FA\u5DF2\u5B89\u88C5\u5B98\u65B9\u63D2\u4EF6\u5305\u5185 AGENTS.md",
   "  init     \u628A\u5185\u7F6E AGENTS.md \u5199\u5165\u5DE5\u4F5C\u533A\uFF08\u9ED8\u8BA4\u5F53\u524D\u76EE\u5F55\uFF09\uFF1B\u5DF2\u5B58\u5728\u9ED8\u8BA4\u62D2\u7EDD\uFF0C--force \u8986\u76D6\uFF0C--dry-run \u9884\u89C8",
   "",
   "JSON\uFF1A\u6240\u6709\u5B50\u547D\u4EE4\u652F\u6301 --json\uFF08\u6216\u524D\u7F6E\u5168\u5C40 --json\uFF0C\u5982 v-cli --json agent index\uFF09",
@@ -894,25 +939,29 @@ var AGENT_HELP_TEXT = [
   "\u793A\u4F8B\uFF1A",
   "  v-cli agent index --json            # \u5168\u91CF\u547D\u4EE4\u7D22\u5F15",
   "  v-cli agent describe ts --json      # \u5355\u547D\u4EE4\u8BE6\u60C5",
-  "  v-cli agent docs                    # \u5185\u7F6E\u5F15\u5BFC\u6587\u6863\u539F\u6587",
+  "  v-cli agent docs                    # v-cli \u7626\u7D22\u5F15\u539F\u6587",
+  "  v-cli agent docs unity              # u-cli-mod \u5305\u5185\u4F7F\u7528\u89C4\u8303",
+  "  v-cli agent docs xlmerge --json     # xlmerge \u5305\u5185\u89C4\u8303\uFF08JSON\uFF09",
   "  v-cli agent init . --dry-run        # \u9884\u89C8\u521D\u59CB\u5316\u76EE\u6807"
 ].join("\n");
 var DOCS_HELP_TEXT = [
-  "\u8F93\u51FA\u5F53\u524D\u5B89\u88C5\u7684 @kevlns/v-cli \u5305\u5185\u7F6E AGENTS.md \u539F\u6587\uFF08AI Agent \u5F15\u5BFC\u6587\u6863\uFF09\uFF0C\u9010\u5B57\u8282\u539F\u6837\u8F93\u51FA\u3001\u4E0D\u8FFD\u52A0\u6362\u884C\u3002",
+  "\u8F93\u51FA AGENTS.md \u539F\u6587\uFF08\u9010\u5B57\u8282\u539F\u6837\u8F93\u51FA\u3001\u4E0D\u8FFD\u52A0\u6362\u884C\uFF09\u3002",
+  "  \u7701\u7565 [command]\uFF1A\u5F53\u524D @kevlns/v-cli \u5305\u5185\u7F6E\u7626\u7D22\u5F15\u3002",
+  "  \u4F20\u5165 [command]\uFF1A\u5DF2\u5B89\u88C5\u5B98\u65B9\u63D2\u4EF6\u5305\u6839 AGENTS.md\uFF08\u5982 unity / xlmerge\uFF09\u3002",
+  "",
+  "\u53C2\u6570\uFF1A",
+  "  [command]  official \u63D2\u4EF6\u547D\u4EE4\u540D\uFF1B\u5148\u7528 v-cli agent index --json \u67E5\u770B",
   "",
   "JSON \u884C\u4E3A\uFF08--json \u6216\u524D\u7F6E\u5168\u5C40 --json\uFF09\uFF1A",
   "  \u6210\u529F\uFF1Astdout \u8F93\u51FA\u7A33\u5B9A\u5BF9\u8C61 { package, version, sha256, content }",
-  "    package  \u5305\u540D @kevlns/v-cli",
-  "    version  \u5F53\u524D\u5305\u7248\u672C",
-  "    sha256   content \u7684 SHA-256\uFF08hex\uFF09\uFF0C\u53EF\u6821\u9A8C\u5F15\u5BFC\u6587\u6863\u672A\u88AB\u7BE1\u6539",
-  "    content  AGENTS.md \u539F\u6587",
   "  \u5931\u8D25\uFF1Astdout \u8F93\u51FA\u7A00\u758F\u5BF9\u8C61 { ok: false, error }\uFF0Cstderr \u518D\u8F93\u51FA\u540C\u4E00 error\uFF0C\u9000\u51FA\u7801 1",
   "",
-  "\u9000\u51FA\u7801\uFF1A0 \u6210\u529F\uFF1B1 \u5185\u7F6E AGENTS.md \u7F3A\u5931/\u4E0D\u53EF\u8BFB",
+  "\u9000\u51FA\u7801\uFF1A0 \u6210\u529F\uFF1B1 \u547D\u4EE4\u672A\u77E5 / \u63D2\u4EF6\u672A\u5B89\u88C5 / AGENTS.md \u7F3A\u5931\u6216\u4E0D\u53EF\u8BFB",
   "",
   "\u793A\u4F8B\uFF1A",
   "  v-cli agent docs",
-  "  v-cli agent docs --json"
+  "  v-cli agent docs unity",
+  "  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",
@@ -973,15 +1022,15 @@ var agent = {
       },
       {
         path: ["docs"],
-        usage: "v-cli agent docs [--json]",
-        description: "\u8F93\u51FA\u5F53\u524D @kevlns/v-cli \u5305\u5185\u7F6E AGENTS.md \u539F\u6587",
-        arguments: [],
+        usage: "v-cli agent docs [command] [--json]",
+        description: "\u65E0\u53C2\u8F93\u51FA v-cli AGENTS.md\uFF1B\u4F20 command \u8F93\u51FA\u5B98\u65B9\u63D2\u4EF6\u5305\u5185 AGENTS.md",
+        arguments: [{ name: "command", required: false, description: "\u5B98\u65B9\u63D2\u4EF6\u547D\u4EE4\u540D\uFF08\u5982 unity\u3001xlmerge\uFF09" }],
         options: [{ flags: "--json", description: "\u8F93\u51FA { package, version, sha256, content }" }],
         output: {
           format: "stdout",
           description: "AGENTS.md \u539F\u6587\u9010\u5B57\u8282\u8F93\u51FA\u5230 stdout\uFF1B--json \u65F6\u8F93\u51FA\u542B sha256/content \u7684\u7A33\u5B9A JSON"
         },
-        exitCodes: { "0": "\u6210\u529F", "1": "\u5185\u7F6E AGENTS.md \u7F3A\u5931/\u4E0D\u53EF\u8BFB" },
+        exitCodes: { "0": "\u6210\u529F", "1": "\u547D\u4EE4\u672A\u77E5 / \u63D2\u4EF6\u672A\u5B89\u88C5 / AGENTS.md \u7F3A\u5931\u6216\u4E0D\u53EF\u8BFB" },
         safety: ["read-only", "no-network"]
       },
       {
@@ -1059,11 +1108,20 @@ var agent = {
       }
       ctx.log.result(lines.join("\n"));
     });
-    program.command("docs").description("\u8F93\u51FA\u5F53\u524D @kevlns/v-cli \u5305\u5185\u7F6E AGENTS.md \u539F\u6587\uFF08AI Agent \u5F15\u5BFC\u6587\u6863\uFF09").option("--json", "\u8F93\u51FA\u673A\u5668\u53EF\u8BFB JSON\uFF08\u542B sha256/content\uFF09").addHelpText("after", DOCS_HELP_TEXT).action((opts) => {
+    program.command("docs").description("\u65E0\u53C2\u8F93\u51FA v-cli AGENTS.md\uFF1B\u4F20 command \u8F93\u51FA\u5B98\u65B9\u63D2\u4EF6\u5305\u5185 AGENTS.md").argument("[command]", "\u5B98\u65B9\u63D2\u4EF6\u547D\u4EE4\u540D\uFF08\u5982 unity\u3001xlmerge\uFF09").option("--json", "\u8F93\u51FA\u673A\u5668\u53EF\u8BFB JSON\uFF08\u542B sha256/content\uFF09").addHelpText("after", DOCS_HELP_TEXT).action((command, opts) => {
       const json = ctx.json || opts.json;
       let docs;
+      let packageName = BUNDLED_DOCS_PACKAGE;
+      let version = VERSION;
       try {
-        docs = readBundledAgentsMd();
+        if (command) {
+          const pluginDocs = readOfficialAgentsMd(command);
+          docs = pluginDocs;
+          packageName = pluginDocs.package;
+          version = pluginDocs.version;
+        } else {
+          docs = readBundledAgentsMd();
+        }
       } catch (err) {
         const message = err instanceof Error ? err.message : String(err);
         if (json) ctx.log.result({ ok: false, error: message });
@@ -1073,8 +1131,8 @@ var agent = {
       }
       if (json) {
         ctx.log.result({
-          package: BUNDLED_DOCS_PACKAGE,
-          version: VERSION,
+          package: packageName,
+          version,
           sha256: docs.sha256,
           content: docs.content
         });

package/package.json

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