@kevlns/v-cli 0.2.13 → 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 (7) hide show
  1. package/AGENTS.md +30 -7
  2. package/LICENSE +21 -21
  3. package/README.md +48 -23
  4. package/dist/cli.mjs +12 -2
  5. package/package.json +6 -4
  6. package/schemas/v-cli-plugin.schema.json +143 -143
  7. package/skills/v-cli/SKILL.md +25 -10
package/AGENTS.md CHANGED
@@ -7,24 +7,47 @@
7
7
 
8
8
  ## 核心约定（v-cli 本体）
9
9
 
10
- - 环境要求 Node.js >= 20；v-cli 版本 @kevlns/v-cli@0.2.13
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 …`）在子进程中运行（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
 
26
+ ## @kevlns/figma-to-uprefab — 命令 `v-cli figma …`
27
+
28
+ **版本**：0.1.2
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.
30
+ **平台**：win32（仅 Windows 主机可用；非 Windows 上 v-cli 会拒绝路由）
31
+
32
+ **何时使用**：Use to convert tagged Figma frames into staging-only Unity UGUI prefabs: export source manifests + node PNGs, validate the staging contract, install the embedded Unity converter package, or run the C# converter in Unity batch. Never use for promoting generated assets into runtime paths or writing UIConfig.
33
+
34
+ **首次调用前必读**：`v-cli agent docs figma`（插件包内 AGENTS.md 规范正本）
35
+ **实时参数/命令**：`v-cli agent describe figma --json`
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
+
25
48
  ## @kevlns/u-cli-mod — 命令 `v-cli unity …`
26
49
 
27
- **版本**：0.2.3
50
+ **版本**：0.2.4
28
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).
29
52
  **平台**：win32（仅 Windows 主机可用；非 Windows 上 v-cli 会拒绝路由）
30
53
 
@@ -35,7 +58,7 @@
35
58
 
36
59
  ## @kevlns/xlmerge — 命令 `v-cli xlmerge …`
37
60
 
38
- **版本**：2.0.0
61
+ **版本**：2.0.1
39
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.
40
63
  **平台**：darwin, linux, win32
41
64
 
package/LICENSE CHANGED
@@ -1,21 +1,21 @@
1
- MIT License
2
-
3
- Copyright (c) 2026 kevlns <936277610@qq.com>
4
-
5
- Permission is hereby granted, free of charge, to any person obtaining a copy
6
- of this software and associated documentation files (the "Software"), to deal
7
- in the Software without restriction, including without limitation the rights
8
- to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
9
- copies of the Software, and to permit persons to whom the Software is
10
- furnished to do so, subject to the following conditions:
11
-
12
- The above copyright notice and this permission notice shall be included in all
13
- copies or substantial portions of the Software.
14
-
15
- THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
16
- IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
17
- FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
18
- AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
19
- LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
20
- OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
21
- SOFTWARE.
1
+ MIT License
2
+
3
+ Copyright (c) 2026 kevlns <936277610@qq.com>
4
+
5
+ Permission is hereby granted, free of charge, to any person obtaining a copy
6
+ of this software and associated documentation files (the "Software"), to deal
7
+ in the Software without restriction, including without limitation the rights
8
+ to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
9
+ copies of the Software, and to permit persons to whom the Software is
10
+ furnished to do so, subject to the following conditions:
11
+
12
+ The above copyright notice and this permission notice shall be included in all
13
+ copies or substantial portions of the Software.
14
+
15
+ THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
16
+ IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
17
+ FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
18
+ AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
19
+ LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
20
+ OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
21
+ SOFTWARE.
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,10 +20,10 @@
20
20
  ## Why v-cli?
21
21
 
22
22
  v-cli 让你**用一个命令沉淀所有个人小工具**，而不用为每个工具建仓库、发包、记命令。
23
- 它被设计为**依赖极少、秒级启动、写个文件就能扩展**，与 kevlns 工具家族的其余部分可自由组合。
23
+ 它被设计为**依赖极少、秒级启动、写个文件就能扩展**。
24
24
 
25
25
  - **插件化架构** - 内置命令走注册表随版本发布；本地插件放进 `~/.v-cli/commands/` 立即生效，无需发版
26
- - **官方插件白名单** - `@kevlns/xlmerge`（`xlmerge`）与 `@kevlns/u-cli-mod`（`unity`）是唯一被路由的官方插件，安装后在子进程中运行
26
+ - **官方插件白名单** - `@kevlns/xlmerge`（`xlmerge`）、`@kevlns/u-cli-mod`（`unity`）与 `@kevlns/figma-to-uprefab`（`figma`），安装后在子进程中运行
27
27
  - **容错加载** - 单个插件语法错误、契约不符或注册异常只会被跳过并报告，绝不阻断其他命令
28
28
  - **双通道输出** - 结果走 stdout（可管道、可脚本化），诊断走 stderr
29
29
  - **agent 友好** - `agent docs`/`agent init` 让 AI Agent 自举读取引导文档；`agent index/describe` 输出统一索引与完整元数据；仓库内 AGENTS.md 自动生成并有漂移检查
@@ -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,16 +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
+
79
+ # Figma -> Unity UGUI staging Prefab（仅 Windows，依赖 Vant Framework）
80
+ v-cli agent docs figma # 首调必读
81
+ v-cli figma --help
82
+ v-cli figma config init --project C:/path/to/UnityProject
83
+ v-cli figma export <fileKey> --project C:/path/to/UnityProject
84
+ v-cli figma contract --project C:/path/to/UnityProject --allow-missing-ir # 构建前（允许缺 IR）
85
+ v-cli figma unity install --project C:/path/to/UnityProject
86
+ v-cli figma build --project C:/path/to/UnityProject
87
+ v-cli figma contract --project C:/path/to/UnityProject # 构建后（完整校验）
78
88
  ```
79
89
 
80
90
  `v-cli <插件命令> …` 的执行语义：插件在**子进程**中运行（stdio 继承），
@@ -89,7 +99,7 @@ v-cli unity doctor <project>
89
99
  export default {
90
100
  name: "hello",
91
101
  description: "示例插件",
92
- apiVersion: 1, // v-cli 0.2 起的插件契约版本，必填
102
+ apiVersion: 1, // 插件契约版本（要求 v-cli >= 0.2），必填
93
103
  register(program, ctx) {
94
104
  program.action(() => ctx.log.result("hello world"));
95
105
  },
@@ -103,8 +113,8 @@ v-cli hello # hello world
103
113
  v-cli plugin list # [local] hello 已出现
104
114
  ```
105
115
 
106
- > 旧版插件（无 `apiVersion: 1`）会被拒绝并给出解释性错误，请补上字段后重载。
107
- > 本地插件不能占用内置命令名（`doctor`/`plugin`/`ts`/`agent`/`help`）或官方命令名（`xlmerge`/`unity`）。
116
+ > 缺少 `apiVersion: 1` 的插件会被拒绝并给出解释性错误，补上字段后重载即可。
117
+ > 本地插件不能占用内置命令名（`doctor`/`plugin`/`ts`/`agent`/`help`）或官方命令名（`xlmerge`/`unity`/`figma`）。
108
118
 
109
119
  ### 在脚本中消费输出
110
120
 
@@ -113,7 +123,7 @@ v-cli ts 1710000000 --json | jq .seconds
113
123
  v-cli --json ts 1710000000 | jq .seconds # 前置全局 --json 同样生效
114
124
  ```
115
125
 
116
- ## `--json` 语义（v-cli 0.2）
126
+ ## `--json` 语义
117
127
 
118
128
  - **前置全局**：`v-cli --json <cmd> …` —— `--json` 出现在首个命令词之前时被 v-cli 消费，`ctx.json` 为真
119
129
  - **命令自有**：`<cmd> --json …` —— 属于该命令：内置命令（`ts`、`doctor`、`plugin list`、`agent index`、`agent describe`、`agent docs`、`agent init`）各自声明 `--json` 并消费；官方插件命令则**原样转发**给插件
@@ -141,7 +151,7 @@ v-cli --json ts 1710000000 | jq .seconds # 前置全局 --json 同样生效
141
151
  interface CliCommand {
142
152
  name: string; // 子命令名
143
153
  description: string;
144
- apiVersion: 1; // v-cli 0.2 起必填
154
+ apiVersion: 1; // 插件契约版本，必填（要求 v-cli >= 0.2）
145
155
  hidden?: boolean;
146
156
  agent?: { // agent 索引元数据（可选）
147
157
  whenToUse?: string; // 什么场景该调用
@@ -189,11 +199,11 @@ npm run check:agents # AGENTS.md 漂移检查（默认与已安装依赖比
189
199
  npm run pack:guard # 发布内容护栏：身份/必需文件/禁止内容/依赖精确固定/engines
190
200
  npm run test:package # 发布后安装冒烟：npm pack → 隔离 prefix 全局安装 → 运行 bin wrapper 断言
191
201
  npm run check # build + typecheck + test + check:agents + pack:guard
202
+ ```
192
203
 
193
204
  > 发版除 `npm version` 外，还需同步全仓版本断言（`grep -rn 旧版本号 tests/ scripts/ src/` 应为零，含 pack-guard 依赖精确固定与 smoke 的插件版本期望），再打 tag。
194
- ```
195
205
 
196
- > `@kevlns/xlmerge@2.0.0` / `@kevlns/u-cli-mod@0.2.3` 已发布并随 `npm install` 装入仓库
206
+ > `@kevlns/xlmerge@2.0.1` / `@kevlns/u-cli-mod@0.2.4` / `@kevlns/figma-to-uprefab@0.1.2` 随 `npm install` 装入仓库
197
207
  > node_modules，`check:agents` 的 installed-deps 检查即为最终形态；预发布阶段需要以本地
198
208
  > 清单 bootstrap 时显式传 `--manifest <path>`。
199
209
 
@@ -201,11 +211,12 @@ npm run check # build + typecheck + test + check:agents + pack:guard
201
211
 
202
212
  kevlns 工具家族共享同一套发布约定（tag 驱动、CI 护栏、MIT）。
203
213
 
204
- | Package | Purpose | Status |
214
+ | Package | Purpose | Version |
205
215
  | --- | --- | --- |
206
- | [`v-cli`](https://github.com/kevlns/v-cli) | 个人工具箱 CLI（本仓库） | v0.2.13 |
207
- | [`xlmerge`](https://github.com/kevlns/xlmerge) | Git 中 .xlsx/.xlsm 冲突可视化解决工具 | v2.0.0 |
208
- | [`u-cli-mod`](https://github.com/kevlns/u-cli-mod) | Unity 精确版本路由 + CLI + pipeline 包（Windows-first） | v0.2.3 |
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 |
209
220
 
210
221
  ## Compatibility
211
222
 
@@ -214,9 +225,9 @@ kevlns 工具家族共享同一套发布约定（tag 驱动、CI 护栏、MIT）
214
225
  | Node.js | `20` and later |
215
226
  | TypeScript | `5.6` and later（仅开发时） |
216
227
 
217
- CLI 核心逻辑以单文件 ESM（`dist/cli.mjs`）分发，运行时依赖 `commander` 与两个官方插件包
218
- （`@kevlns/xlmerge`、`@kevlns/u-cli-mod`，均为精确固定版本；安装 v-cli 时一起安装，
219
- 未装时 `plugin list`/`doctor`/`agent index` 会诚实报告 `missing` 状态）。
228
+ CLI 核心逻辑以单文件 ESM（`dist/cli.mjs`）分发，运行时依赖 `commander` 与三个官方插件包
229
+ （`@kevlns/xlmerge`、`@kevlns/u-cli-mod`、`@kevlns/figma-to-uprefab`，均为精确固定版本；安装 v-cli 时一起安装，
230
+ 未装时 `plugin list`/`doctor`/`agent index` 会如实报告 `missing` 状态）。
220
231
 
221
232
  ## Contributing
222
233
 
@@ -238,4 +249,18 @@ Released under the [MIT License](./LICENSE).
238
249
 
239
250
  Part of the **kevlns** tool family.
240
251
 
241
- </div>
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
@@ -312,6 +312,16 @@ var OFFICIAL_PLUGINS = [
312
312
  package: "@kevlns/u-cli-mod",
313
313
  command: "unity",
314
314
  description: "Unity \u5DE5\u7A0B\u7CBE\u786E\u7248\u672C\u8DEF\u7531 + \u5B98\u65B9 CLI \u4E0B\u8F7D + com.unity.pipeline \u9002\u914D\u5305\uFF08Windows-first\uFF09"
315
+ },
316
+ {
317
+ package: "@kevlns/figma-to-uprefab",
318
+ command: "figma",
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"
315
325
  }
316
326
  ];
317
327
  var OFFICIAL_COMMAND_NAMES = new Set(
@@ -627,7 +637,7 @@ import { createHash, randomBytes } from "crypto";
627
637
  import { fileURLToPath as fileURLToPath2 } from "url";
628
638
 
629
639
  // src/version.ts
630
- var VERSION = "0.2.13";
640
+ var VERSION = "0.2.15";
631
641
 
632
642
  // src/core/agent-docs.ts
633
643
  var BUNDLED_DOCS_FILE = "AGENTS.md";
@@ -1109,7 +1119,7 @@ var DOCS_HELP_TEXT = [
1109
1119
  ].join("\n");
1110
1120
  var INIT_HELP_TEXT = [
1111
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",
1112
- "\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",
1113
1123
  "",
1114
1124
  "\u53C2\u6570\uFF1A",
1115
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.13",
3
+ "version": "0.2.15",
4
4
  "description": "kevlns 的个人工具箱 CLI（插件化架构，内置 + 本地插件）+ doctor/plugin/ts 命令",
5
5
  "type": "module",
6
6
  "bin": {
@@ -46,9 +46,11 @@
46
46
  "personal"
47
47
  ],
48
48
  "dependencies": {
49
- "@kevlns/u-cli-mod": "0.2.3",
50
- "@kevlns/xlmerge": "2.0.0",
51
- "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"
52
54
  },
53
55
  "devDependencies": {
54
56
  "@types/node": "^20.14.0",
package/schemas/v-cli-plugin.schema.json CHANGED
@@ -1,144 +1,144 @@
1
- {
2
- "$schema": "http://json-schema.org/draft-07/schema#",
3
- "$id": "https://github.com/kevlns/v-cli/schemas/v-cli-plugin.schema.json",
4
- "title": "v-cli plugin manifest",
5
- "description": "官方插件清单（v-cli.plugin.json）契约，schemaVersion 1。v-cli 使用内置校验器（src/core/manifest.ts）执行等价规则；本文件供编辑器提示与文档使用。",
6
- "type": "object",
7
- "additionalProperties": true,
8
- "required": [
9
- "schemaVersion",
10
- "package",
11
- "command",
12
- "bin",
13
- "description",
14
- "platforms",
15
- "runtime",
16
- "environment",
17
- "agent"
18
- ],
19
- "properties": {
20
- "schemaVersion": {
21
- "const": 1,
22
- "description": "清单契约版本。v-cli 0.2 仅支持 1；未知 major（>=2）会被拒绝。"
23
- },
24
- "package": {
25
- "type": "string",
26
- "pattern": "^@[a-zA-Z0-9][a-zA-Z0-9._~-]*/[a-zA-Z0-9][a-zA-Z0-9._~-]*$",
27
- "description": "npm 包名（@scope/name），必须与 package.json 的 name 一致。"
28
- },
29
- "command": {
30
- "type": "string",
31
- "pattern": "^[a-z][a-z0-9-]*$",
32
- "description": "v-cli 路由命令名。不可与内置命令（doctor/plugin/ts/agent/help）重名。"
33
- },
34
- "bin": {
35
- "type": "string",
36
- "description": "package.json bin 中的键名；由 v-cli 以子进程方式调用。"
37
- },
38
- "description": {
39
- "type": "string",
40
- "minLength": 1
41
- },
42
- "platforms": {
43
- "type": "array",
44
- "minItems": 1,
45
- "uniqueItems": true,
46
- "items": {
47
- "type": "string",
48
- "enum": ["darwin", "linux", "win32"]
49
- }
50
- },
51
- "runtime": {
52
- "type": "object",
53
- "description": "运行时要求（node/python/os 等，自由形状）。"
54
- },
55
- "environment": {
56
- "type": "array",
57
- "items": {
58
- "type": "object",
59
- "required": ["name", "description"],
60
- "properties": {
61
- "name": { "type": "string", "minLength": 1 },
62
- "description": { "type": "string", "minLength": 1 }
63
- }
64
- }
65
- },
66
- "agent": {
67
- "type": "object",
68
- "required": ["whenToUse", "globalOptions", "commands"],
69
- "properties": {
70
- "whenToUse": {
71
- "type": "string",
72
- "description": "给 AI agent 的判断条件：什么场景该调用本插件。"
73
- },
74
- "globalOptions": {
75
- "type": "array",
76
- "items": {
77
- "type": "object",
78
- "required": ["flags", "description"],
79
- "properties": {
80
- "flags": { "type": "string", "minLength": 1 },
81
- "description": { "type": "string", "minLength": 1 }
82
- }
83
- }
84
- },
85
- "commands": {
86
- "type": "array",
87
- "items": {
88
- "type": "object",
89
- "required": ["path", "usage", "description", "arguments", "options", "output", "exitCodes", "safety"],
90
- "properties": {
91
- "path": {
92
- "type": "array",
93
- "minItems": 1,
94
- "items": { "type": "string", "pattern": "^[a-z][a-z0-9-]*$" }
95
- },
96
- "usage": { "type": "string", "minLength": 1 },
97
- "description": { "type": "string", "minLength": 1 },
98
- "arguments": {
99
- "type": "array",
100
- "items": {
101
- "type": "object",
102
- "required": ["name", "required", "description"],
103
- "properties": {
104
- "name": { "type": "string", "minLength": 1 },
105
- "required": { "type": "boolean" },
106
- "description": { "type": "string", "minLength": 1 }
107
- }
108
- }
109
- },
110
- "options": {
111
- "type": "array",
112
- "items": {
113
- "type": "object",
114
- "required": ["flags", "description"],
115
- "properties": {
116
- "flags": { "type": "string", "minLength": 1 },
117
- "description": { "type": "string", "minLength": 1 }
118
- }
119
- }
120
- },
121
- "output": {
122
- "type": "object",
123
- "required": ["format", "description"],
124
- "properties": {
125
- "format": { "type": "string", "enum": ["json", "stdout", "text"] },
126
- "description": { "type": "string", "minLength": 1 }
127
- }
128
- },
129
- "exitCodes": {
130
- "type": "object",
131
- "description": "code -> 含义 映射。",
132
- "additionalProperties": { "type": "string" }
133
- },
134
- "safety": {
135
- "type": "array",
136
- "items": { "type": "string" }
137
- }
138
- }
139
- }
140
- }
141
- }
142
- }
143
- }
1
+ {
2
+ "$schema": "http://json-schema.org/draft-07/schema#",
3
+ "$id": "https://github.com/kevlns/v-cli/schemas/v-cli-plugin.schema.json",
4
+ "title": "v-cli plugin manifest",
5
+ "description": "官方插件清单（v-cli.plugin.json）契约，schemaVersion 1。v-cli 使用内置校验器（src/core/manifest.ts）执行等价规则；本文件供编辑器提示与文档使用。",
6
+ "type": "object",
7
+ "additionalProperties": true,
8
+ "required": [
9
+ "schemaVersion",
10
+ "package",
11
+ "command",
12
+ "bin",
13
+ "description",
14
+ "platforms",
15
+ "runtime",
16
+ "environment",
17
+ "agent"
18
+ ],
19
+ "properties": {
20
+ "schemaVersion": {
21
+ "const": 1,
22
+ "description": "清单契约版本。v-cli 0.2 仅支持 1；未知 major（>=2）会被拒绝。"
23
+ },
24
+ "package": {
25
+ "type": "string",
26
+ "pattern": "^@[a-zA-Z0-9][a-zA-Z0-9._~-]*/[a-zA-Z0-9][a-zA-Z0-9._~-]*$",
27
+ "description": "npm 包名（@scope/name），必须与 package.json 的 name 一致。"
28
+ },
29
+ "command": {
30
+ "type": "string",
31
+ "pattern": "^[a-z][a-z0-9-]*$",
32
+ "description": "v-cli 路由命令名。不可与内置命令（doctor/plugin/ts/agent/help）重名。"
33
+ },
34
+ "bin": {
35
+ "type": "string",
36
+ "description": "package.json bin 中的键名；由 v-cli 以子进程方式调用。"
37
+ },
38
+ "description": {
39
+ "type": "string",
40
+ "minLength": 1
41
+ },
42
+ "platforms": {
43
+ "type": "array",
44
+ "minItems": 1,
45
+ "uniqueItems": true,
46
+ "items": {
47
+ "type": "string",
48
+ "enum": ["darwin", "linux", "win32"]
49
+ }
50
+ },
51
+ "runtime": {
52
+ "type": "object",
53
+ "description": "运行时要求（node/python/os 等，自由形状）。"
54
+ },
55
+ "environment": {
56
+ "type": "array",
57
+ "items": {
58
+ "type": "object",
59
+ "required": ["name", "description"],
60
+ "properties": {
61
+ "name": { "type": "string", "minLength": 1 },
62
+ "description": { "type": "string", "minLength": 1 }
63
+ }
64
+ }
65
+ },
66
+ "agent": {
67
+ "type": "object",
68
+ "required": ["whenToUse", "globalOptions", "commands"],
69
+ "properties": {
70
+ "whenToUse": {
71
+ "type": "string",
72
+ "description": "给 AI agent 的判断条件：什么场景该调用本插件。"
73
+ },
74
+ "globalOptions": {
75
+ "type": "array",
76
+ "items": {
77
+ "type": "object",
78
+ "required": ["flags", "description"],
79
+ "properties": {
80
+ "flags": { "type": "string", "minLength": 1 },
81
+ "description": { "type": "string", "minLength": 1 }
82
+ }
83
+ }
84
+ },
85
+ "commands": {
86
+ "type": "array",
87
+ "items": {
88
+ "type": "object",
89
+ "required": ["path", "usage", "description", "arguments", "options", "output", "exitCodes", "safety"],
90
+ "properties": {
91
+ "path": {
92
+ "type": "array",
93
+ "minItems": 1,
94
+ "items": { "type": "string", "pattern": "^[a-z][a-z0-9-]*$" }
95
+ },
96
+ "usage": { "type": "string", "minLength": 1 },
97
+ "description": { "type": "string", "minLength": 1 },
98
+ "arguments": {
99
+ "type": "array",
100
+ "items": {
101
+ "type": "object",
102
+ "required": ["name", "required", "description"],
103
+ "properties": {
104
+ "name": { "type": "string", "minLength": 1 },
105
+ "required": { "type": "boolean" },
106
+ "description": { "type": "string", "minLength": 1 }
107
+ }
108
+ }
109
+ },
110
+ "options": {
111
+ "type": "array",
112
+ "items": {
113
+ "type": "object",
114
+ "required": ["flags", "description"],
115
+ "properties": {
116
+ "flags": { "type": "string", "minLength": 1 },
117
+ "description": { "type": "string", "minLength": 1 }
118
+ }
119
+ }
120
+ },
121
+ "output": {
122
+ "type": "object",
123
+ "required": ["format", "description"],
124
+ "properties": {
125
+ "format": { "type": "string", "enum": ["json", "stdout", "text"] },
126
+ "description": { "type": "string", "minLength": 1 }
127
+ }
128
+ },
129
+ "exitCodes": {
130
+ "type": "object",
131
+ "description": "code -> 含义 映射。",
132
+ "additionalProperties": { "type": "string" }
133
+ },
134
+ "safety": {
135
+ "type": "array",
136
+ "items": { "type": "string" }
137
+ }
138
+ }
139
+ }
140
+ }
141
+ }
142
+ }
143
+ }
144
144
  }
package/skills/v-cli/SKILL.md CHANGED
@@ -1,8 +1,8 @@
1
1
  ---
2
2
  name: v-cli
3
3
  description: >
4
- 使用 kevlns 的个人工具箱 CLI（v-cli）处理配置表冲突与 Unity 工程精确版本工具链。当任务提到 v-cli、xlmerge、
5
- unity 命令、配置表 .xlsx/.xlsm Git 冲突处理、Unity CLI 安装、Unity 工程诊断/体检（doctor）、
4
+ 使用 kevlns 的个人工具箱 CLI（v-cli）处理配置表冲突、Unity 工程精确版本工具链、Figma 转 Unity UGUI Prefab 和 Steam/微信小游戏交付。当任务提到 v-cli、xlmerge、ship-cli、
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
  ---
8
8
 
@@ -10,16 +10,16 @@ description: >
10
10
 
11
11
  ## 工具概述
12
12
 
13
- - `@kevlns/v-cli` 是 npm 全局安装的个人工具箱 CLI，插件化架构；环境要求 Node.js >= 20（`unity` 插件仅 win32，其他平台 v-cli 拒绝路由）。
13
+ - `@kevlns/v-cli` 是 npm 全局安装的个人工具箱 CLI，插件化架构；环境要求 Node.js >= 20（`unity` 与 `figma` 插件仅 win32，其他平台 v-cli 拒绝路由）。
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`。
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 元数据，获取最新命令集合。
@@ -29,24 +29,24 @@ description: >
29
29
 
30
30
  ## 首调规范
31
31
 
32
- **首次调用任何 official 插件命令（`v-cli xlmerge …`、`v-cli unity …`）前，必须先运行 `v-cli agent docs <命令名>` 读取该插件包内的 AGENTS.md 规范正本。** 使用规范、快速流程与禁止事项以插件自身 AGENTS.md 为准。
32
+ **首次调用任何 official 插件命令（`v-cli xlmerge …`、`v-cli unity …`、`v-cli figma …`）前，必须先运行 `v-cli agent docs <命令名>` 读取该插件包内的 AGENTS.md 规范正本。** 使用规范、快速流程与禁止事项以插件自身 AGENTS.md 为准。
33
33
 
34
34
  官方插件命令在子进程中运行（stdio 继承）：v-cli 只做路由，不解析、不改写插件输出；插件 `--help`/`--json` 等参数由插件自己消费。插件对 worktree 的写入/提交行为以插件清单的安全标签为准；**未经显式 flag 不得 push**。
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
  - 正常流程（只做命令路由，不做表格分析）：
@@ -112,6 +112,15 @@ receipt 属工程本地生成物；就绪以当前路由的完整文件树校验
112
112
  - 小范围：`--filter <命名空间或类>` 通常数秒内同步返回完整 Summary。
113
113
  - 5 秒让位机制只保证 CLI 子进程存活并把输出写入 `Library/editor-pipeline-cli/exec-logs/*.log`，不改变 Editor 侧任务的同步语义；让出后不要重复发起同一命令，取消用 `-- command cancel_tests`。
114
114
 
115
+ ## 官方插件三：figma（仅 win32）
116
+
117
+ - 用于标记 Figma 界面导出、staging 契约校验、Unity 转换包安装与 UGUI Prefab 构建；目标工程需要 Unity 2022.3 和 Vant Framework。
118
+ - 首次调用先读 `v-cli agent docs figma`，参数以 `v-cli agent describe figma --json` 为准。
119
+ - 用户配置按工程保存在 `~/.config/figma-to-uprefab/config.json`；token 来自 `FIGMA_ACCESS_TOKEN` 或工程配置段，不写入仓库。
120
+ - `export` 只导出 source manifest、节点 PNG 和根索引；source → IR → Prefab 由嵌入式 C# 转换器完成。
121
+ - 构建前使用 `contract --allow-missing-ir`；安装转换包并 `build` 后运行完整 `contract`。
122
+ - 输出限于 staging；不自动迁入正式资源目录、不写 UIConfig。NGUI 当前不支持。
123
+
115
124
  ## 典型流程
116
125
 
117
126
  ```bash
@@ -129,3 +138,9 @@ v-cli unity exec <project> -- command run_tests --mode EditMode --async_tests
129
138
  v-cli xlmerge --repo . detect # 配置表：只读检测
130
139
  v-cli xlmerge --repo . launch # 有冲突时启动本地 UI，把 url 交给用户
131
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 调用服务并返回二维码路径。正式发布由平台后台处理。