@kevlns/v-cli 0.2.11 → 0.2.13

package/AGENTS.md

@@ -7,7 +7,7 @@
 
 ## 核心约定（v-cli 本体）
 
-- 环境要求 Node.js >= 20；v-cli 版本 @kevlns/v-cli@0.2.11
+- 环境要求 Node.js >= 20；v-cli 版本 @kevlns/v-cli@0.2.13
 - 命令分三类：builtin（内置）、local（~/.v-cli/commands/ 下的本地插件）、official（官方插件白名单）；
   **最新、live 的命令集合以实际发现为准**：先运行 `v-cli agent index --json` 获取全部命令与 agent 元数据
 - 单个命令的完整元数据用 `v-cli agent describe <命令名> --json` 查看
@@ -24,7 +24,7 @@
 
 ## @kevlns/u-cli-mod — 命令 `v-cli unity …`
 
-**版本**：0.2.1
+**版本**：0.2.3
 **描述**：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 会拒绝路由）
 

package/README.md

@@ -49,32 +49,21 @@ npm install -g git+https://github.com/kevlns/v-cli.git
 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 可自行发现并读取引导文档，无需人工粘贴：
+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 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 自动读取
+v-cli agent init .                  # （可选）把 AGENTS.md 写入工作区并装配 skill
 ```
 
-`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/…`）。
+`agent init [directory]`（默认当前目录）：已存在 AGENTS.md 时默认拒绝退出 1（`--force` 原子覆盖）；
+`--dry-run` 只报告不写入；符号链接目标 fail-closed 拒绝；`--json` 输出稳定结果。
 
 ### 控制器命令（官方插件）
 
@@ -84,7 +73,7 @@ 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.2.1
+npm install -g @kevlns/u-cli-mod@0.2.3
 v-cli unity doctor <project>
 ```
 
@@ -200,13 +189,13 @@ 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
+
+> 发版除 `npm version` 外，还需同步全仓版本断言（`grep -rn 旧版本号 tests/ scripts/ src/` 应为零，含 pack-guard 依赖精确固定与 smoke 的插件版本期望），再打 tag。
 ```
 
-> `@kevlns/xlmerge@2.0.0` / `@kevlns/u-cli-mod@0.2.1` 已发布并由 `npm install`
-> 装入仓库 node_modules：`generate:agents`/`check:agents` 的默认（installed-deps）检查即为
-> 最终形态，`npm run check` 因此才能全绿，CI 的 `check:agents` 步骤也随之总是生效
-> （不依赖 sibling 仓库检出；若未来仍需要在预发布阶段以 sibling 清单 bootstrap，
-> 可显式传 `--manifest <path>`）。
+> `@kevlns/xlmerge@2.0.0` / `@kevlns/u-cli-mod@0.2.3` 已发布并随 `npm install` 装入仓库
+> node_modules，`check:agents` 的 installed-deps 检查即为最终形态；预发布阶段需要以本地
+> 清单 bootstrap 时显式传 `--manifest <path>`。
 
 ## Package family
 
@@ -214,9 +203,9 @@ kevlns 工具家族共享同一套发布约定（tag 驱动、CI 护栏、MIT）
 
 | Package | Purpose | Status |
 | --- | --- | --- |
-| [`v-cli`](https://github.com/kevlns/v-cli) | 个人工具箱 CLI（本仓库） | v0.2.11 |
+| [`v-cli`](https://github.com/kevlns/v-cli) | 个人工具箱 CLI（本仓库） | v0.2.13 |
 | [`xlmerge`](https://github.com/kevlns/xlmerge) | Git 中 .xlsx/.xlsm 冲突可视化解决工具 | v2.0.0 |
-| [`u-cli-mod`](https://github.com/kevlns/u-cli-mod) | Unity 精确版本路由 + CLI + pipeline 包（Windows-first） | v0.2.1 |
+| [`u-cli-mod`](https://github.com/kevlns/u-cli-mod) | Unity 精确版本路由 + CLI + pipeline 包（Windows-first） | v0.2.3 |
 
 ## Compatibility
 

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.11";
+var VERSION = "0.2.13";
 
 // src/core/agent-docs.ts
 var BUNDLED_DOCS_FILE = "AGENTS.md";

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@kevlns/v-cli",
-  "version": "0.2.11",
+  "version": "0.2.13",
   "description": "kevlns 的个人工具箱 CLI（插件化架构，内置 + 本地插件）+ doctor/plugin/ts 命令",
   "type": "module",
   "bin": {
@@ -46,7 +46,7 @@
     "personal"
   ],
   "dependencies": {
-    "@kevlns/u-cli-mod": "0.2.1",
+    "@kevlns/u-cli-mod": "0.2.3",
     "@kevlns/xlmerge": "2.0.0",
     "commander": "^12.1.0"
   },
@@ -59,4 +59,4 @@
   "allowScripts": {
     "esbuild@0.27.2": true
   }
-}
+}

package/skills/v-cli/SKILL.md

@@ -40,8 +40,8 @@ description: >
 - 命中以下任一场景必须执行一次：① `v-cli` 未安装（先确认 Node.js >= 20 与 npm 可用，`npm install -g @kevlns/v-cli`，用 `v-cli --version` 与 `v-cli agent index --json` 验证）；② 项目内 skill（`<技能目录>/v-cli/SKILL.md`）缺失。两个场景同时命中只执行一次；命令用单数 `agent`，不得写成 `v-cli agents …`。
 - 产物与归属：
   - 根 `AGENTS.md` 为**工具生成物**（建议纳入 `.gitignore`），禁止手改；需要更新内容时升级 v-cli 后重跑 init。
-  - 分支不变式（实测）：① `AGENTS.md` 不存在 → 写入它**并**装配 skill；② `AGENTS.md` 已存在且未加 `--force` → **整体拒绝**（`action=refused`、`skill.status=skipped-init-failed`），不做任何改动；`--force` 会同时覆盖两者。
-  - **skill 同步**：**随包版本是规范的唯一权威**——命中目录下已有 `v-cli/SKILL.md` 时一律按随包版本刷新（本地修改会被覆盖，工具在 `localModified=true` 时给出提示）；目标目录中随包**没有**的文件默认保留，供项目放扩展说明（如 `PROJECT.md`）；`--force` 时做完全同步（连扩展文件一起清掉，目录与随包逐文件一致）。因此项目**不要**直接改 `SKILL.md`，项目专属内容写进扩展文件或项目规则文档。
+  - `AGENTS.md` 已存在且未加 `--force` 时**整体拒绝**，不做任何改动；`--force` 同时覆盖 AGENTS.md 与 skill。
+  - **skill 同步**：随包版本是唯一权威——已有 `v-cli/SKILL.md` 一律按随包刷新（本地修改被覆盖并提示）；随包没有的文件（项目扩展，如 `PROJECT.md`）默认保留，`--force` 时完全同步。项目不要直接改 `SKILL.md`，专属内容写扩展文件。
 - 先 `--dry-run --json` 预览目标与动作（含 `skill.assembled[].action` 与 `overwrite`），再实际写入。
 
 ## 官方插件一：xlmerge（跨平台）
@@ -92,7 +92,7 @@ Unity 2022 工程**精确版本路由**（版本号 + revision 双重匹配）+
 | `outdated` / `invalid` | 先关闭目标工程 Editor，再 `v-cli unity pipeline install <project> --force`（自动备份，备份与 receipt 都在 `Library/editor-pipeline-cli/`，已被 gitignore） |
 | `current` | 可直接 `exec` |
 
-receipt 属工程本地生成物：新克隆 / 清理 Library 后即使 `Packages/com.unity.pipeline` 已入库且文件树完好，`state` 仍会是 `invalid`，需按上一行重装一次补齐 receipt。
+receipt 属工程本地生成物；就绪以当前路由的完整文件树校验为准。新克隆 / 清理 Library 后，文件树完好仍为 `current`，不因 receipt 缺失或陈旧要求重装。`pipeline.verification` 列出不匹配文件与仅行尾差异；`sourceReady=false` 只表示生成缓存需重建，不代表已安装包失效。新生成文本统一 LF，已安装文本兼容 LF/CRLF 等价，二进制和实际内容仍严格校验。
 
 ### 关键规则（违反即报错或导致损坏，必须遵守）
 
@@ -105,13 +105,12 @@ receipt 属工程本地生成物：新克隆 / 清理 Library 后即使 `Package
 7. **读取 Editor 当前 Console 首选 `command read_console`**；`get_console_logs` 是兼容别名，`command console` 是回调捕获流，适合 cursor/since 跟随，不能替代原生 Console 快照。若 schema 中缺 `read_console`，先核对 `doctor` 的 `patchVersion`/`installedPatchVersion`/`state`，不要把它当成 `console` 的别名。
 8. 工程内适配包已随仓入库；工具重装写出的文件树与仓库版本一致时（行尾由 `.gitattributes` 归一）**不应产生 git diff**，若出现大面积 diff 应先判定为行尾/编码现象再复核内容，不得据此手工回滚适配包。
 
-### 长任务命令：启动即让出，用状态命令轮询
+### 长任务命令：全量测试走异步，小范围走同步
 
-- `run_tests` 这类同步长任务默认只等 **5 秒**：到点后任务仍在 Editor 内继续执行，工具打印输出日志路径（`<工程>/Library/editor-pipeline-cli/exec-logs/*.log`）并立即返回（退出码 0）。
-- 让出后**不要重复发起同一命令**，改用状态命令轮询：测试 `-- command test_status`（直到读到 `summary`），烘焙 `-- command <xxx>_bake_status`。
-- 需要同步拿到完整 `Summary` 时用 `--wait <秒>` 扩大等待（写在 `--` 之前，u-cli-mod 自行剥离，不会透传给 Unity CLI）；`--wait 0` = 立即返回。
-- **优先缩小范围**（最省事）：`run_tests --mode EditMode --filter <命名空间或测试类>` 通常数秒内就同步返回完整 `Summary`，无需轮询。
-- 让出后任务仍在跑，不要重复发起；如需取消用 `-- command cancel_tests`（运行中可能被拒，稍后重试）。
+- Unity CLI 对同步命令有 30 秒硬性等待上限（`--wait`/`--timeout` 均无法延长），同步 `run_tests` 全量必然超时。
+- 全量：`-- command run_tests --mode EditMode --async_tests`（立即返回）→ 轮询 `-- command test_status` 至 `completed` 拿完整 Summary。
+- 小范围：`--filter <命名空间或类>` 通常数秒内同步返回完整 Summary。
+- 5 秒让位机制只保证 CLI 子进程存活并把输出写入 `Library/editor-pipeline-cli/exec-logs/*.log`，不改变 Editor 侧任务的同步语义；让出后不要重复发起同一命令，取消用 `-- command cancel_tests`。
 
 ## 典型流程
 
@@ -126,6 +125,7 @@ v-cli unity setup <project>                                         # 6. 就绪
 v-cli unity exec <project> -- command editor_status                 # 7. 执行 Pipeline 命令
 v-cli unity exec <project> -- command read_console --types error,warning --count 100
 v-cli unity exec <project> -- command run_tests --mode EditMode --filter <类名>   # 8. 测试（小范围同步返回）
+v-cli unity exec <project> -- command run_tests --mode EditMode --async_tests     #    全量：立即返回，轮询 test_status
 v-cli xlmerge --repo . detect                                       # 配置表：只读检测
 v-cli xlmerge --repo . launch                                       # 有冲突时启动本地 UI，把 url 交给用户
-```
+```