@kevlns/v-cli 0.1.1-beta.1 → 0.2.0-beta.2

package/AGENTS.md

@@ -0,0 +1,75 @@
+# AGENTS.md
+
+<!-- v-cli-agents:generated -->
+
+> 本文件由 `scripts/generate-agents.mjs` 自动生成，请勿手改。
+> 修改插件清单后运行 `npm run generate:agents` 重新生成，`npm run check:agents` 校验漂移。
+
+## 核心约定（v-cli 本体）
+
+- 环境要求 Node.js >= 20；v-cli 版本 @kevlns/v-cli@0.2.0-beta.2
+- 命令分三类：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 xlmerge …`、`v-cli unity …`）在子进程中运行（stdio 继承）：v-cli 只做路由，
+  不解析、不改写插件的 stdout/stderr；插件 `--help`/`--json` 等参数由插件自己消费
+- 插件对 worktree 的写入/提交行为以插件清单 v-cli.plugin.json 的 `agent.safety` 为准：
+  v-cli 不替插件做 diff/write-back/commit；**未经显式 flag 不得 push**
+
+## @kevlns/u-cli-mod — 命令 `v-cli unity …`
+
+**版本**：0.1.0-beta.2
+**描述**：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
+
+## @kevlns/xlmerge — 命令 `v-cli xlmerge …`
+
+**版本**：1.2.1-beta.2
+**描述**：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
+
+---
+
+所有清单字段的解释见 `schemas/v-cli-plugin.schema.json` 与 `v-cli agent describe` 输出。

package/README.md

@@ -23,8 +23,10 @@ v-cli 让你**用一个命令沉淀所有个人小工具**，而不用为每个
 它被设计为**依赖极少、秒级启动、写个文件就能扩展**，与 kevlns 工具家族的其余部分可自由组合。
 
 - **插件化架构** - 内置命令走注册表随版本发布；本地插件放进 `~/.v-cli/commands/` 立即生效，无需发版
-- **容错加载** - 单个插件语法错误或形状不符只会被跳过并报告，绝不阻断其他命令
-- **双通道输出** - 结果走 stdout（可管道、可脚本化），诊断走 stderr；全局 `--json` 任意位置生效
+- **官方插件白名单** - `@kevlns/xlmerge`（`xlmerge`）与 `@kevlns/u-cli-mod`（`unity`）是唯一被路由的官方插件，安装后在子进程中运行
+- **容错加载** - 单个插件语法错误、契约不符或注册异常只会被跳过并报告，绝不阻断其他命令
+- **双通道输出** - 结果走 stdout（可管道、可脚本化），诊断走 stderr
+- **agent 友好** - `agent docs`/`agent init` 让 AI Agent 自举读取引导文档；`agent index/describe` 输出统一索引与完整元数据；仓库内 AGENTS.md 自动生成并有漂移检查
 - **TypeScript-first** - 严格类型编写，tsup 将核心逻辑打包为单文件 ESM，仅保留 `commander` 运行依赖
 
 ## Getting started
@@ -41,16 +43,55 @@ npm install -g git+https://github.com/kevlns/v-cli.git
 
 发布稳定版并设置 `latest` 标签后，可直接使用 `npm install -g @kevlns/v-cli`。
 
+需要 Node.js **>= 20**。
+
 ### Quick start
 
 ```bash
-v-cli doctor          # 环境体检：node/版本、主目录、配置、插件状态
-v-cli plugin list     # 列出内置命令与本地插件
+v-cli doctor          # 环境体检：node/版本、主目录、配置、官方/本地插件状态
+v-cli plugin list     # 列出内置命令、本地插件与官方插件状态
 v-cli ts 1710000000   # 时间戳互转
+v-cli agent docs      # 输出当前安装包内置 AGENTS.md 原文（AI Agent 引导文档）
+v-cli agent index     # 命令 + agent 元数据索引（--json 输出机器可读）
+v-cli agent describe xlmerge --json
+v-cli agent init .    # （可选）把 AGENTS.md 初始化到当前目录
+```
+
+### AI Agent 快速开始
+
+v-cli 内置 AGENTS.md 随包发布，AI Agent 可自行发现并读取引导文档，无需人工粘贴：
+
+```bash
+v-cli agent docs                    # 读当前包内置 AGENTS.md 原文（--json 拿 package/version/sha256/content）
+v-cli agent index --json            # 枚举全部命令 + 元数据（builtin/local/official，live 发现）
+v-cli agent describe <name> --json  # 单命令：用法/参数/选项/输出/退出码/安全标签
+v-cli agent init .                  # （可选）把 AGENTS.md 写入工作区，AI Agent 自动读取
+```
+
+`agent docs` 文本模式逐字节输出内置 AGENTS.md，`--json` 输出稳定对象
+`{ package, version, sha256, content }`。
+
+`agent init [directory]`（默认当前目录；目录必须已存在且为目录）：
+
+- 已存在 AGENTS.md 时**默认拒绝并退出 1，绝不改动现有文件**（`--force` 才原子覆盖）；
+- `--dry-run` 只报告目标与将执行的动作，不写入任何文件；
+- 符号链接目标一律 fail-closed 拒绝（不跟随、不覆盖链接目标）；
+- `--json` 输出稳定结果（`ok/dryRun/action/directory/target/sha256/bytes/…`）。
+
+### 控制器命令（官方插件）
+
+```bash
+npm install -g @kevlns/xlmerge@1.2.1-beta.2   # 安装后即可
+v-cli xlmerge --repo <repo> detect            # 路由到 xlmerge 子进程
+v-cli xlmerge --repo <repo> resolve
+
+# Unity 工具链（仅 Windows 主机可用；其他平台 v-cli 会拒绝路由并说明原因）
+npm install -g @kevlns/u-cli-mod@0.1.0-beta.2
+v-cli unity doctor <project>
 ```
 
-> [!TIP]
-> 所有命令都支持 `--json`（任意位置）：`v-cli doctor --json` 输出机器可读结果，方便脚本消费。
+`v-cli <插件命令> …` 的执行语义：插件在**子进程**中运行（stdio 继承），
+`--json`/`--help`/`--`/插件自有选项一律**原样转发**给插件，v-cli 不解析、不改写插件输出。
 
 ## Examples
 
@@ -61,6 +102,7 @@ v-cli ts 1710000000   # 时间戳互转
 export default {
   name: "hello",
   description: "示例插件",
+  apiVersion: 1, // v-cli 0.2 起的插件契约版本，必填
   register(program, ctx) {
     program.action(() => ctx.log.result("hello world"));
   },
@@ -74,46 +116,99 @@ v-cli hello           # hello world
 v-cli plugin list     # [local] hello 已出现
 ```
 
+> 旧版插件（无 `apiVersion: 1`）会被拒绝并给出解释性错误，请补上字段后重载。
+> 本地插件不能占用内置命令名（`doctor`/`plugin`/`ts`/`agent`/`help`）或官方命令名（`xlmerge`/`unity`）。
+
 ### 在脚本中消费输出
 
 ```bash
 v-cli ts 1710000000 --json | jq .seconds
+v-cli --json ts 1710000000 | jq .seconds   # 前置全局 --json 同样生效
 ```
 
+## `--json` 语义（v-cli 0.2）
+
+- **前置全局**：`v-cli --json <cmd> …` —— `--json` 出现在首个命令词之前时被 v-cli 消费，`ctx.json` 为真
+- **命令自有**：`<cmd> --json …` —— 属于该命令：内置命令（`ts`、`doctor`、`plugin list`、`agent index`、`agent describe`、`agent docs`、`agent init`）各自声明 `--json` 并消费；官方插件命令则**原样转发**给插件
+- 其他中间位置（如 `v-cli plugin --json list`）不承诺 JSON 输出
+- 插件转发示例：`v-cli xlmerge detect --json` 会把 `--json` 转给 xlmerge；`v-cli --json xlmerge detect` 则消费掉全局 `--json`、只转发 `detect`
+
 ## API
 
 ### 内置命令
 
 | 命令 | 说明 |
 | --- | --- |
-| `v-cli doctor` | 环境体检：node/v-cli 版本、主目录、config 可写性、本地插件与加载错误 |
-| `v-cli plugin list` | 列出全部命令（标注 builtin/local 来源） |
+| `v-cli doctor` | 环境体检：node/v-cli 版本、主目录、config 可写性、本地插件与官方插件状态 |
+| `v-cli plugin list` | 列出全部命令（builtin/local/official 来源与状态） |
 | `v-cli plugin path` | 打印本地插件目录 |
 | `v-cli ts [value]` | 无参=当前时间；数字（秒/毫秒自动识别）=转可读时间；日期串=转时间戳 |
+| `v-cli agent index [--json]` | 全部命令的 agent 索引（builtin/local/official，含元数据状态） |
+| `v-cli agent describe <name> [--json]` | 单个命令的完整记录；未找到时 stderr 报错并退出 1 |
+| `v-cli agent docs [--json]` | 输出当前包内置 AGENTS.md 原文；`--json` 输出 `{ package, version, sha256, content }`；缺失时退出 1 |
+| `v-cli agent init [directory] [--force] [--dry-run] [--json]` | 把内置 AGENTS.md 写入目录（默认 cwd）；已存在默认拒绝退出 1，`--force` 原子覆盖，`--dry-run` 只报告 |
 
-### 插件契约 `CliCommand`
+### 插件契约 `CliCommand`（apiVersion 1）
 
 ```ts
 interface CliCommand {
   name: string;                                    // 子命令名
   description: string;
+  apiVersion: 1;                                   // v-cli 0.2 起必填
   hidden?: boolean;
+  agent?: {                                        // agent 索引元数据（可选）
+    whenToUse?: string;                            // 什么场景该调用
+    globalOptions?: { flags: string; description: string }[];
+    commands?: { path: string[]; description: string; usage?: string }[];
+  };
   register(program: Command, ctx: CliContext): void;
 }
 
 interface CliContext {
   log: Logger;        // result() 走 stdout，info/warn/error 走 stderr
   config: ConfigStore; // <home>/config.json 惰性读写
-  json: boolean;      // 全局 --json 开关，命令必须尊重
+  json: boolean;      // 全局 --json 开关（来自前置段扫描），命令必须尊重
   homeDir: string;    // 主目录（默认 ~/.v-cli）
 }
 ```
 
+#### 官方插件注入的环境变量
+
+| 变量 | 值 | 说明 |
+| --- | --- | --- |
+| `V_CLI_HOST_VERSION` | v-cli 版本 | 插件可据此判断宿主能力 |
+| `V_CLI_PLUGIN_API` | `1` | 插件契约版本 |
+| `V_CLI_INVOKED_BY` | `v-cli` | 标识本次调用来自 v-cli |
+
 #### 环境变量
 
 | 变量 | 默认值 | 说明 |
 | --- | --- | --- |
 | `V_CLI_HOME` | `~/.v-cli` | 覆盖主目录（配置、本地插件都从这里找） |
+| `V_CLI_PLUGIN_RESOLVE_FROM` | — | 测试/开发钩子：官方插件从 `<值>/node_modules/{包}` 解析 |
+
+## 官方插件清单契约
+
+- 每个官方插件包内包含 `v-cli.plugin.json`（`package.json` 的 `vCli.manifest` 可指向其他文件名）
+- 清单 schema 见 `schemas/v-cli-plugin.schema.json`（`schemaVersion: 1`）；v-cli 内置等价校验器
+- 身份校验：清单 `package`/`bin` 必须与包的 `package.json` 一致；`bin` 目标必须是字符串、解析后位于包目录内、且文件存在，否则视为 `invalid`/`missing` 并拒绝路由
+- 平台门禁：`platforms` 不含当前平台时拒绝路由（如 `unity` 仅 `win32`）
+
+## 仓库工具脚本
+
+```bash
+npm run generate:agents   # 默认从【已安装的官方依赖】确定性生成 AGENTS.md
+npm run check:agents      # AGENTS.md 漂移检查（默认与已安装依赖比对；不一致时非零退出）
+npm run pack:guard        # 发布内容护栏：身份/必需文件/禁止内容/依赖精确固定/engines
+npm run test:package      # 发布后安装冒烟：npm pack → 隔离 prefix 全局安装 → 运行 bin wrapper 断言
+npm run check             # build + typecheck + test + check:agents + pack:guard
+```
+
+> `@kevlns/xlmerge@1.2.1-beta.2` / `@kevlns/u-cli-mod@0.1.0-beta.2` 已发布并由 `npm install`
+> 装入仓库 node_modules：`generate:agents`/`check:agents` 的默认（installed-deps）检查即为
+> 最终形态，`npm run check` 因此才能全绿，CI 的 `check:agents` 步骤也随之总是生效
+> （不依赖 sibling 仓库检出；若未来仍需要在预发布阶段以 sibling 清单 bootstrap，
+> 可显式传 `--manifest <path>`）。
 
 ## Package family
 
@@ -121,17 +216,20 @@ kevlns 工具家族共享同一套发布约定（tag 驱动、CI 护栏、MIT）
 
 | Package | Purpose | Status |
 | --- | --- | --- |
-| [`v-cli`](https://github.com/kevlns/v-cli) | 个人工具箱 CLI（本仓库） | v0.1.1-beta.1 |
-| [`xlmerge`](https://github.com/kevlns/xlmerge) | Git 中 .xlsx/.xlsm 冲突可视化解决工具 | v1.2.1-beta.1 |
+| [`v-cli`](https://github.com/kevlns/v-cli) | 个人工具箱 CLI（本仓库） | v0.2.0-beta.2 |
+| [`xlmerge`](https://github.com/kevlns/xlmerge) | Git 中 .xlsx/.xlsm 冲突可视化解决工具 | v1.2.1-beta.2 |
+| [`u-cli-mod`](https://github.com/kevlns/u-cli-mod) | Unity 精确版本路由 + CLI + pipeline 包（Windows-first） | v0.1.0-beta.2 |
 
 ## Compatibility
 
 | Runtime | Supported versions |
 | --- | --- |
-| Node.js | `18` and later |
+| Node.js | `20` and later |
 | TypeScript | `5.6` and later（仅开发时） |
 
-CLI 核心逻辑以单文件 ESM（`dist/cli.mjs`）分发，运行时仅依赖 `commander`。
+CLI 核心逻辑以单文件 ESM（`dist/cli.mjs`）分发，运行时依赖 `commander` 与两个官方插件包
+（`@kevlns/xlmerge`、`@kevlns/u-cli-mod`，均为精确固定版本；安装 v-cli 时一起安装，
+未装时 `plugin list`/`doctor`/`agent index` 会诚实报告 `missing` 状态）。
 
 ## Contributing
 
@@ -139,7 +237,7 @@ CLI 核心逻辑以单文件 ESM（`dist/cli.mjs`）分发，运行时仅依赖
 git clone https://github.com/kevlns/v-cli.git
 cd v-cli
 npm install
-npm run build && npm test
+npm run check
 ```
 
 For bugs and feature requests, use
@@ -153,4 +251,4 @@ Released under the [MIT License](./LICENSE).
 
 Part of the **kevlns** tool family.
 
-</div>
+</div>