@kevlns/v-cli 0.2.14 → 0.2.15

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (5) hide show
  1. package/AGENTS.md +20 -8
  2. package/README.md +36 -22
  3. package/dist/cli.mjs +7 -2
  4. package/package.json +6 -5
  5. package/skills/v-cli/SKILL.md +13 -7
package/AGENTS.md CHANGED
@@ -7,24 +7,25 @@
7
7
 
8
8
  ## 核心约定（v-cli 本体）
9
9
 
10
- - 环境要求 Node.js >= 20；v-cli 版本 @kevlns/v-cli@0.2.14
10
+ - 环境要求 Node.js >= 20；v-cli 版本 @kevlns/v-cli@0.2.15
11
11
  - 命令分三类：builtin（内置）、local（~/.v-cli/commands/ 下的本地插件）、official（官方插件白名单）；
12
- **最新、live 的命令集合以实际发现为准**：先运行 `v-cli agent index --json` 获取全部命令与 agent 元数据
12
+ **命令集合以实际发现为准**：先运行 `v-cli agent index --json` 获取全部命令与 agent 元数据
13
13
  - 单个命令的完整元数据用 `v-cli agent describe <命令名> --json` 查看
14
14
  - AI Agent 引导文档：`v-cli agent docs` 输出本文件原文（`--json` 含 sha256/content）；
15
15
  `v-cli agent init .` 把它写入工作区（已存在默认拒绝，`--force` 覆盖，`--dry-run` 预览；符号链接目标 fail-closed）；
16
- 同时把随包发布的 v-cli skill（skills/v-cli）装配到 <目录> 下匹配的 agent 技能目录（如 .claude/skills、.agent/skill、AgentHome/skills 等，清单见 src/core/agent-dirs.ts），无匹配则跳过；
16
+ 同时把随包发布的 v-cli skill（skills/v-cli）装配到 <目录> 下匹配的 agent 技能目录（如 .claude/skills、.agent/skill、AgentHome/skills 等），无匹配则跳过；
17
17
  随包版本是规范唯一权威：同名 SKILL.md 一律按随包版本刷新（本地修改会被覆盖并提示）；随包没有的文件（项目扩展，如 PROJECT.md）默认保留，`--force` 时完全同步
18
- - **首次调用规范**：首次调用任何 official 插件命令前，必须先运行 `v-cli agent docs <命令名>`，
18
+ - **首调规范**：首次调用任何 official 插件命令前，必须先运行 `v-cli agent docs <命令名>`，
19
19
  掌握该插件包内 `AGENTS.md`；使用规范、快速流程与禁止事项以插件 AGENTS.md 为准。
20
- - 官方插件命令（`v-cli xlmerge …`、`v-cli unity …`、`v-cli figma …`）在子进程中运行（stdio 继承）：v-cli 只做路由，
20
+ - 官方插件命令（`v-cli xlmerge …`、`v-cli unity …`、`v-cli figma …`、`v-cli ship …`）在子进程中运行（stdio 继承）：v-cli 只做路由，
21
+ - `ship` 是随包官方插件（@kevlns/ship-cli），随 v-cli 安装并自动发现；先运行 `v-cli agent docs ship`、`v-cli ship doctor --json`，再按 Steam / 微信小游戏流程执行。缺失时明确报告 missing，不在运行时自动安装。
21
22
  不解析、不改写插件的 stdout/stderr；插件 `--help`/`--json` 等参数由插件自己消费
22
23
  - 插件对 worktree 的写入/提交行为以插件清单 v-cli.plugin.json 的 `agent.safety` 为准：
23
24
  v-cli 不替插件做 diff/write-back/commit；**未经显式 flag 不得 push**
24
25
 
25
26
  ## @kevlns/figma-to-uprefab — 命令 `v-cli figma …`
26
27
 
27
- **版本**：0.1.1
28
+ **版本**：0.1.2
28
29
  **描述**：Figma REST -> staging-only Unity UGUI prefabs. Node orchestrates export/contract/install/build; the embedded Unity Editor package (source manifest + approximation overlay -> IR -> Prefab) is the only source->IR converter.
29
30
  **平台**：win32（仅 Windows 主机可用；非 Windows 上 v-cli 会拒绝路由）
30
31
 
@@ -33,9 +34,20 @@
33
34
  **首次调用前必读**：`v-cli agent docs figma`（插件包内 AGENTS.md 规范正本）
34
35
  **实时参数/命令**：`v-cli agent describe figma --json`
35
36
 
37
+ ## @kevlns/ship-cli — 命令 `v-cli ship …`
38
+
39
+ **版本**：0.1.1
40
+ **描述**：Cross-platform game shipping CLI: offline validation + packaging + push to platform test channels. Steam (steamcmd/SteamPipe VDF builds, branch set-live guard) and WeChat mini games (structure/size validation, miniprogram-ci preview QR and dev-version upload). Never publishes to players on its own.
41
+ **平台**：win32, linux, darwin
42
+
43
+ **何时使用**：Shipping a built game to distribution platforms: packaging/upload to Steam (depot builds via steamcmd) or WeChat mini games (dev-version upload via miniprogram-ci), plus offline package validation and environment preflight. NOT for: making content player-visible (Steam default-branch set-live, WeChat review submission/release/gray rollout are always human steps in platform backends), building engine players (produce artifacts first), or account/credential setup beyond pointing at env vars.
44
+
45
+ **首次调用前必读**：`v-cli agent docs ship`（插件包内 AGENTS.md 规范正本）
46
+ **实时参数/命令**：`v-cli agent describe ship --json`
47
+
36
48
  ## @kevlns/u-cli-mod — 命令 `v-cli unity …`
37
49
 
38
- **版本**：0.2.3
50
+ **版本**：0.2.4
39
51
  **描述**：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).
40
52
  **平台**：win32（仅 Windows 主机可用；非 Windows 上 v-cli 会拒绝路由）
41
53
 
@@ -46,7 +58,7 @@
46
58
 
47
59
  ## @kevlns/xlmerge — 命令 `v-cli xlmerge …`
48
60
 
49
- **版本**：2.0.0
61
+ **版本**：2.0.1
50
62
  **描述**：Formula-aware visual resolver for Git merge conflicts in .xlsx/.xlsm planning tables: three-way sheet/row/cell diff, local UI, atomic write-back and commit.
51
63
  **平台**：darwin, linux, win32
52
64
 
package/README.md CHANGED
@@ -11,7 +11,7 @@
11
11
  [![CI](https://img.shields.io/github/actions/workflow/status/kevlns/v-cli/test.yml?branch=main&style=flat-square&label=CI)](https://github.com/kevlns/v-cli/actions/workflows/test.yml)
12
12
  [![license](https://img.shields.io/github/license/kevlns/v-cli?style=flat-square&color=2e8b57)](./LICENSE)
13
13
 
14
- [Getting started](#getting-started) · [API](#api) · [Examples](#examples) · [Package family](#package-family)
14
+ [Getting started](#getting-started) · [Examples](#examples) · [API](#api) · [Package family](#package-family)
15
15
 
16
16
  </div>
17
17
 
@@ -20,7 +20,7 @@
20
20
  ## Why v-cli?
21
21
 
22
22
  v-cli 让你**用一个命令沉淀所有个人小工具**，而不用为每个工具建仓库、发包、记命令。
23
- 它被设计为**依赖极少、秒级启动、写个文件就能扩展**，与 kevlns 工具家族的其余部分可自由组合。
23
+ 它被设计为**依赖极少、秒级启动、写个文件就能扩展**。
24
24
 
25
25
  - **插件化架构** - 内置命令走注册表随版本发布；本地插件放进 `~/.v-cli/commands/` 立即生效，无需发版
26
26
  - **官方插件白名单** - `@kevlns/xlmerge`（`xlmerge`）、`@kevlns/u-cli-mod`（`unity`）与 `@kevlns/figma-to-uprefab`（`figma`），安装后在子进程中运行
@@ -37,7 +37,7 @@ v-cli 让你**用一个命令沉淀所有个人小工具**，而不用为每个
37
37
  # 正式版直接安装
38
38
  npm install -g @kevlns/v-cli
39
39
 
40
- # 或直接从 GitHub 仓库安装开发版本
40
+ # 或从 GitHub 仓库安装开发版本
41
41
  npm install -g git+https://github.com/kevlns/v-cli.git
42
42
  ```
43
43
 
@@ -53,7 +53,7 @@ v-cli ts 1710000000 # 时间戳互转
53
53
 
54
54
  ### AI Agent 快速开始
55
55
 
56
- v-cli 内置 AGENTS.md 随包发布，AI Agent 自行发现读取，无需人工粘贴：
56
+ v-cli 内置 AGENTS.md 随包发布，AI Agent 可自行发现读取：
57
57
 
58
58
  ```bash
59
59
  v-cli agent docs # 内置 AGENTS.md 原文（--json 拿 package/version/sha256/content）
@@ -65,26 +65,26 @@ v-cli agent init . # （可选）把 AGENTS.md 写入工作区
65
65
  `agent init [directory]`（默认当前目录）：已存在 AGENTS.md 时默认拒绝退出 1（`--force` 原子覆盖）；
66
66
  `--dry-run` 只报告不写入；符号链接目标 fail-closed 拒绝；`--json` 输出稳定结果。
67
67
 
68
- ### 控制器命令（官方插件）
68
+ ### 官方插件命令
69
+
70
+ 官方插件随 v-cli 一起安装（精确固定依赖），装完即可路由：
69
71
 
70
72
  ```bash
71
- npm install -g @kevlns/xlmerge@2.0.0 # 安装后即可
72
73
  v-cli xlmerge --repo <repo> detect # 路由到 xlmerge 子进程
73
74
  v-cli xlmerge --repo <repo> resolve
74
75
 
75
76
  # Unity 工具链（仅 Windows 主机可用；其他平台 v-cli 会拒绝路由并说明原因）
76
- npm install -g @kevlns/u-cli-mod@0.2.3
77
77
  v-cli unity doctor <project>
78
78
 
79
79
  # Figma -> Unity UGUI staging Prefab（仅 Windows，依赖 Vant Framework）
80
- v-cli agent docs figma
80
+ v-cli agent docs figma # 首调必读
81
81
  v-cli figma --help
82
82
  v-cli figma config init --project C:/path/to/UnityProject
83
83
  v-cli figma export <fileKey> --project C:/path/to/UnityProject
84
- v-cli figma contract --project C:/path/to/UnityProject --allow-missing-ir
84
+ v-cli figma contract --project C:/path/to/UnityProject --allow-missing-ir # 构建前（允许缺 IR）
85
85
  v-cli figma unity install --project C:/path/to/UnityProject
86
86
  v-cli figma build --project C:/path/to/UnityProject
87
- v-cli figma contract --project C:/path/to/UnityProject
87
+ v-cli figma contract --project C:/path/to/UnityProject # 构建后（完整校验）
88
88
  ```
89
89
 
90
90
  `v-cli <插件命令> …` 的执行语义：插件在**子进程**中运行（stdio 继承），
@@ -99,7 +99,7 @@ v-cli figma contract --project C:/path/to/UnityProject
99
99
  export default {
100
100
  name: "hello",
101
101
  description: "示例插件",
102
- apiVersion: 1, // v-cli 0.2 起的插件契约版本，必填
102
+ apiVersion: 1, // 插件契约版本（要求 v-cli >= 0.2），必填
103
103
  register(program, ctx) {
104
104
  program.action(() => ctx.log.result("hello world"));
105
105
  },
@@ -113,7 +113,7 @@ v-cli hello # hello world
113
113
  v-cli plugin list # [local] hello 已出现
114
114
  ```
115
115
 
116
- > 旧版插件（无 `apiVersion: 1`）会被拒绝并给出解释性错误，请补上字段后重载。
116
+ > 缺少 `apiVersion: 1` 的插件会被拒绝并给出解释性错误，补上字段后重载即可。
117
117
  > 本地插件不能占用内置命令名（`doctor`/`plugin`/`ts`/`agent`/`help`）或官方命令名（`xlmerge`/`unity`/`figma`）。
118
118
 
119
119
  ### 在脚本中消费输出
@@ -123,7 +123,7 @@ v-cli ts 1710000000 --json | jq .seconds
123
123
  v-cli --json ts 1710000000 | jq .seconds # 前置全局 --json 同样生效
124
124
  ```
125
125
 
126
- ## `--json` 语义（v-cli 0.2）
126
+ ## `--json` 语义
127
127
 
128
128
  - **前置全局**：`v-cli --json <cmd> …` —— `--json` 出现在首个命令词之前时被 v-cli 消费，`ctx.json` 为真
129
129
  - **命令自有**：`<cmd> --json …` —— 属于该命令：内置命令（`ts`、`doctor`、`plugin list`、`agent index`、`agent describe`、`agent docs`、`agent init`）各自声明 `--json` 并消费；官方插件命令则**原样转发**给插件
@@ -151,7 +151,7 @@ v-cli --json ts 1710000000 | jq .seconds # 前置全局 --json 同样生效
151
151
  interface CliCommand {
152
152
  name: string; // 子命令名
153
153
  description: string;
154
- apiVersion: 1; // v-cli 0.2 起必填
154
+ apiVersion: 1; // 插件契约版本，必填（要求 v-cli >= 0.2）
155
155
  hidden?: boolean;
156
156
  agent?: { // agent 索引元数据（可选）
157
157
  whenToUse?: string; // 什么场景该调用
@@ -199,11 +199,11 @@ npm run check:agents # AGENTS.md 漂移检查（默认与已安装依赖比
199
199
  npm run pack:guard # 发布内容护栏：身份/必需文件/禁止内容/依赖精确固定/engines
200
200
  npm run test:package # 发布后安装冒烟：npm pack → 隔离 prefix 全局安装 → 运行 bin wrapper 断言
201
201
  npm run check # build + typecheck + test + check:agents + pack:guard
202
+ ```
202
203
 
203
204
  > 发版除 `npm version` 外，还需同步全仓版本断言（`grep -rn 旧版本号 tests/ scripts/ src/` 应为零，含 pack-guard 依赖精确固定与 smoke 的插件版本期望），再打 tag。
204
- ```
205
205
 
206
- > `@kevlns/xlmerge@2.0.0` / `@kevlns/u-cli-mod@0.2.3` / `@kevlns/figma-to-uprefab@0.1.1` 随 `npm install` 装入仓库
206
+ > `@kevlns/xlmerge@2.0.1` / `@kevlns/u-cli-mod@0.2.4` / `@kevlns/figma-to-uprefab@0.1.2` 随 `npm install` 装入仓库
207
207
  > node_modules，`check:agents` 的 installed-deps 检查即为最终形态；预发布阶段需要以本地
208
208
  > 清单 bootstrap 时显式传 `--manifest <path>`。
209
209
 
@@ -211,12 +211,12 @@ npm run check # build + typecheck + test + check:agents + pack:guard
211
211
 
212
212
  kevlns 工具家族共享同一套发布约定（tag 驱动、CI 护栏、MIT）。
213
213
 
214
- | Package | Purpose | Status |
214
+ | Package | Purpose | Version |
215
215
  | --- | --- | --- |
216
- | [`v-cli`](https://github.com/kevlns/v-cli) | 个人工具箱 CLI（本仓库） | v0.2.14 |
217
- | [`xlmerge`](https://github.com/kevlns/xlmerge) | Git 中 .xlsx/.xlsm 冲突可视化解决工具 | v2.0.0 |
218
- | [`u-cli-mod`](https://github.com/kevlns/u-cli-mod) | Unity 精确版本路由 + CLI + pipeline 包（Windows-first） | v0.2.3 |
219
- | [`figma-to-uprefab`](https://github.com/kevlns/figma-to-uprefab) | Figma 导出、契约校验与 Unity UGUI staging Prefab 构建 | v0.1.1 |
216
+ | [`v-cli`](https://github.com/kevlns/v-cli) | 个人工具箱 CLI（本仓库） | v0.2.15 |
217
+ | [`xlmerge`](https://github.com/kevlns/xlmerge) | Git 中 .xlsx/.xlsm 冲突可视化解决工具 | v2.0.1 |
218
+ | [`u-cli-mod`](https://github.com/kevlns/u-cli-mod) | Unity 精确版本路由 + CLI + pipeline 包（Windows-first） | v0.2.4 |
219
+ | [`figma-to-uprefab`](https://github.com/kevlns/figma-to-uprefab) | Figma 导出、契约校验与 Unity UGUI staging Prefab 构建 | v0.1.2 |
220
220
 
221
221
  ## Compatibility
222
222
 
@@ -227,7 +227,7 @@ kevlns 工具家族共享同一套发布约定（tag 驱动、CI 护栏、MIT）
227
227
 
228
228
  CLI 核心逻辑以单文件 ESM（`dist/cli.mjs`）分发，运行时依赖 `commander` 与三个官方插件包
229
229
  （`@kevlns/xlmerge`、`@kevlns/u-cli-mod`、`@kevlns/figma-to-uprefab`，均为精确固定版本；安装 v-cli 时一起安装，
230
- 未装时 `plugin list`/`doctor`/`agent index` 会诚实报告 `missing` 状态）。
230
+ 未装时 `plugin list`/`doctor`/`agent index` 会如实报告 `missing` 状态）。
231
231
 
232
232
  ## Contributing
233
233
 
@@ -250,3 +250,17 @@ Released under the [MIT License](./LICENSE).
250
250
  Part of the **kevlns** tool family.
251
251
 
252
252
  </div>
253
+ # ship 官方插件
254
+
255
+ `ship` 已加入官方插件白名单，`@kevlns/ship-cli@0.1.1` 为随包官方依赖。将 ship-cli 安装到与 v-cli 相同的 npm prefix 后自动发现；发布后随 v-cli 安装，不需要本地插件注册。
256
+
257
+ ```bash
258
+ v-cli plugin list --json
259
+ v-cli agent docs ship
260
+ v-cli agent describe ship --json
261
+ v-cli ship doctor --json
262
+ v-cli ship wx validate --json
263
+ v-cli ship wx push --version 1.0.0 --json
264
+ ```
265
+
266
+ 缺失时会显示 missing。完整 Steam / 微信小游戏流程以 ship 的随包规范为准。隔离接入验证：`npm run test:package`，覆盖四个官方依赖的安装、发现、清单、规范哈希与真实子进程路由。
package/dist/cli.mjs CHANGED
@@ -317,6 +317,11 @@ var OFFICIAL_PLUGINS = [
317
317
  package: "@kevlns/figma-to-uprefab",
318
318
  command: "figma",
319
319
  description: "Figma \u6807\u8BB0\u754C\u9762\u5BFC\u51FA\u3001\u5951\u7EA6\u6821\u9A8C\u4E0E Unity UGUI staging Prefab \u6784\u5EFA\uFF08Windows-first\uFF09"
320
+ },
321
+ {
322
+ package: "@kevlns/ship-cli",
323
+ command: "ship",
324
+ description: "\u5DF2\u6784\u5EFA\u6E38\u620F\u7684 Steam/\u5FAE\u4FE1\u5C0F\u6E38\u620F\u6821\u9A8C\u3001\u9884\u6F14\u548C\u6D4B\u8BD5\u901A\u9053\u4E0A\u4F20"
320
325
  }
321
326
  ];
322
327
  var OFFICIAL_COMMAND_NAMES = new Set(
@@ -632,7 +637,7 @@ import { createHash, randomBytes } from "crypto";
632
637
  import { fileURLToPath as fileURLToPath2 } from "url";
633
638
 
634
639
  // src/version.ts
635
- var VERSION = "0.2.14";
640
+ var VERSION = "0.2.15";
636
641
 
637
642
  // src/core/agent-docs.ts
638
643
  var BUNDLED_DOCS_FILE = "AGENTS.md";
@@ -1114,7 +1119,7 @@ var DOCS_HELP_TEXT = [
1114
1119
  ].join("\n");
1115
1120
  var INIT_HELP_TEXT = [
1116
1121
  "\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",
1117
- "\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",
1122
+ "\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\uFF09\uFF0C\u65E0\u5339\u914D\u76EE\u5F55\u5219\u8DF3\u8FC7\u3002",
1118
1123
  "",
1119
1124
  "\u53C2\u6570\uFF1A",
1120
1125
  " [directory] \u76EE\u6807\u76EE\u5F55\uFF0C\u9ED8\u8BA4\u5F53\u524D\u5DE5\u4F5C\u76EE\u5F55\uFF1B\u5FC5\u987B\u5DF2\u5B58\u5728\u4E14\u4E3A\u76EE\u5F55",
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@kevlns/v-cli",
3
- "version": "0.2.14",
3
+ "version": "0.2.15",
4
4
  "description": "kevlns 的个人工具箱 CLI（插件化架构，内置 + 本地插件）+ doctor/plugin/ts 命令",
5
5
  "type": "module",
6
6
  "bin": {
@@ -46,10 +46,11 @@
46
46
  "personal"
47
47
  ],
48
48
  "dependencies": {
49
- "@kevlns/figma-to-uprefab": "0.1.1",
50
- "@kevlns/u-cli-mod": "0.2.3",
51
- "@kevlns/xlmerge": "2.0.0",
52
- "commander": "^12.1.0"
49
+ "@kevlns/figma-to-uprefab": "0.1.2",
50
+ "@kevlns/u-cli-mod": "0.2.4",
51
+ "@kevlns/xlmerge": "2.0.1",
52
+ "commander": "^12.1.0",
53
+ "@kevlns/ship-cli": "0.1.1"
53
54
  },
54
55
  "devDependencies": {
55
56
  "@types/node": "^20.14.0",
package/skills/v-cli/SKILL.md CHANGED
@@ -1,7 +1,7 @@
1
1
  ---
2
2
  name: v-cli
3
3
  description: >
4
- 使用 kevlns 的个人工具箱 CLI（v-cli）处理配置表冲突、Unity 工程精确版本工具链与 Figma 转 Unity UGUI Prefab。当任务提到 v-cli、xlmerge、
4
+ 使用 kevlns 的个人工具箱 CLI（v-cli）处理配置表冲突、Unity 工程精确版本工具链、Figma 转 Unity UGUI Prefab 和 Steam/微信小游戏交付。当任务提到 v-cli、xlmerge、ship-cli、
5
5
  unity / figma 命令、figma-to-uprefab、配置表 .xlsx/.xlsm Git 冲突处理、Unity CLI 安装、Unity 工程诊断/体检（doctor）、
6
6
  com.unity.pipeline 适配包安装、v-cli agent init 工作区初始化时使用本 skill。
7
7
  ---
@@ -14,12 +14,12 @@ description: >
14
14
  - 命令分三类：
15
15
  - **builtin**（内置）：`doctor`（环境体检）、`plugin list/path`（插件管理）、`ts`（时间戳互转）、`agent index/describe/docs/init`（agent 引导）。
16
16
  - **local**：`~/.v-cli/commands/` 下的本地插件。
17
- - **official**（官方插件，经 v-cli 路由）：`xlmerge`、`unity`、`figma`。
17
+ - **official**（官方插件，经 v-cli 路由）：`xlmerge`、`unity`、`figma`，以及`ship`。
18
18
  - **本文件不写死任何版本号**：v-cli 本体与官方插件的实际版本、命令集合、参数一律以 `v-cli doctor` 与 `v-cli agent index --json` 的实时输出为准。
19
19
 
20
20
  ## 能力发现协议（核心规则，必须遵守）
21
21
 
22
- **一切能力、参数、用法以 v-cli 自己的 agent 命令输出为准，严禁无头搜索 npm 安装目录、源码或 README 猜测用法。**
22
+ **一切能力、参数、用法以 v-cli 自己的 agent 命令输出为准，严禁自行翻查 npm 安装目录、源码或 README 来猜测用法。**
23
23
 
24
24
  - `v-cli agent docs` — 输出 v-cli 内置 AGENTS.md（宿主规范全文；`--json` 含 sha256/content）。
25
25
  - `v-cli agent index --json` — 枚举全部命令（builtin/local/official）与 agent 元数据，获取最新命令集合。
@@ -35,18 +35,18 @@ description: >
35
35
 
36
36
  ## 工程初始化（agent init）
37
37
 
38
- - `v-cli agent init [目录] [--force] [--dry-run] [--json]`：把内置 AGENTS.md 写入工作区，并把随包的 v-cli skill 装配到该目录下匹配的 agent 技能目录（如 `.claude/skills`、`.agent/skill`、`AgentHome/skills` 等，清单见 `src/core/agent-dirs.ts`）；无匹配目录则跳过。
39
- - **强制约束**：只能在本仓 Git 根目录执行，先 `git rev-parse --show-toplevel` 定位并切换到根，禁止在任何子目录执行。
38
+ - `v-cli agent init [目录] [--force] [--dry-run] [--json]`：把内置 AGENTS.md 写入工作区，并把随包的 v-cli skill 装配到该目录下匹配的 agent 技能目录（如 `.claude/skills`、`.agent/skill`、`AgentHome/skills` 等）；无匹配目录则跳过。
39
+ - **强制约束**：只能在目标工程的 Git 根目录执行，先 `git rev-parse --show-toplevel` 定位并切换到根，禁止在任何子目录执行。
40
40
  - 命中以下任一场景必须执行一次：① `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 …`。
41
41
  - 产物与归属：
42
- - 根 `AGENTS.md` 为**工具生成物**（建议纳入 `.gitignore`），禁止手改；需要更新内容时升级 v-cli 后重跑 init。
42
+ - 根 `AGENTS.md` 为**工具生成物**（建议纳入 `.gitignore`），禁止手改；需要更新内容时升级 v-cli 后重跑 `agent init --force`。
43
43
  - `AGENTS.md` 已存在且未加 `--force` 时**整体拒绝**，不做任何改动；`--force` 同时覆盖 AGENTS.md 与 skill。
44
44
  - **skill 同步**：随包版本是唯一权威——已有 `v-cli/SKILL.md` 一律按随包刷新（本地修改被覆盖并提示）；随包没有的文件（项目扩展，如 `PROJECT.md`）默认保留，`--force` 时完全同步。项目不要直接改 `SKILL.md`，专属内容写扩展文件。
45
45
  - 先 `--dry-run --json` 预览目标与动作（含 `skill.assembled[].action` 与 `overwrite`），再实际写入。
46
46
 
47
47
  ## 官方插件一：xlmerge（跨平台）
48
48
 
49
- Git 中 `.xlsx` / `.xlsm` 策划表/配置表冲突的公式感知可视化解决工具（三向 Sheet/行/列/Cell diff + 本地 UI + 原子写回与提交）。
49
+ Git 中 `.xlsx` / `.xlsm` 策划表/配置表冲突的公式感知可视化解决工具（三向 Sheet/行/Cell diff + 本地 UI + 原子写回与提交）。
50
50
 
51
51
  - 命令面：`detect`、`filter add`、`prepare`、`resolve`、`launch`、`apply`（参数以 `v-cli agent describe xlmerge --json` 为准）。
52
52
  - 正常流程（只做命令路由，不做表格分析）：
@@ -138,3 +138,9 @@ v-cli unity exec <project> -- command run_tests --mode EditMode --async_tests
138
138
  v-cli xlmerge --repo . detect # 配置表：只读检测
139
139
  v-cli xlmerge --repo . launch # 有冲突时启动本地 UI，把 url 交给用户
140
140
  ```
141
+
142
+ ## 游戏交付插件 ship
143
+
144
+ 对已构建游戏进行 Steam / 微信小游戏校验、扫码预览或开发版上传时，先 `v-cli agent describe ship --json` 确认可用，再读取 `v-cli agent docs ship`。`ship` 是官方插件，与 v-cli 安装在同一 npm prefix 后自动发现；缺失时报告 missing，安装需要对应任务授权。
145
+
146
+ 选择正确工程后执行 `v-cli ship --project <工程目录> doctor --json`，检查体检 ok 和 fail 项。具体平台命令、上传授权边界、凭据和体积口径以 ship 随包规范为准。Steam preview 不上传；微信 preview 调用服务并返回二维码路径。正式发布由平台后台处理。