@kevlns/u-cli-mod 0.1.0-beta.3 → 0.1.0-beta.4
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.
- package/AGENTS.md +34 -0
- package/README.md +2 -1
- package/package.json +2 -1
package/AGENTS.md
ADDED
|
@@ -0,0 +1,34 @@
|
|
|
1
|
+
# u-cli-mod Agent 使用规范
|
|
2
|
+
|
|
3
|
+
> 本文件是 AI Agent 调用本工具的规范正本。参数全集以 `u-cli-mod <命令> --help` 与 `v-cli.plugin.json`(经 v-cli 路由时用 `v-cli agent describe unity`)为准;本文件只锁定使用场景、调用规范与典型流程。
|
|
4
|
+
|
|
5
|
+
## 何时使用
|
|
6
|
+
|
|
7
|
+
- Windows 主机上,需要按**精确 Unity Editor 版本**(版本号 + revision 双重匹配)对 Unity 工程执行:体检诊断、下载固定版本 Unity CLI、事务式安装适配版 `com.unity.pipeline`、执行 Unity Pipeline 命令。
|
|
8
|
+
- 命令名 `unity`(经 v-cli 路由:`v-cli unity …`;独立安装时为 `u-cli-mod …`)。
|
|
9
|
+
|
|
10
|
+
## 核心命令速览
|
|
11
|
+
|
|
12
|
+
- `u-cli-mod doctor <project>` - 只读体检:路由匹配 / CLI 状态 / 适配包状态
|
|
13
|
+
- `u-cli-mod setup <project>` - CLI + 适配包一键就绪(推荐首次入口)
|
|
14
|
+
- `u-cli-mod pipeline install <project> --dry-run` - 安装预览(不写入工程)
|
|
15
|
+
- `u-cli-mod pipeline install <project>` - 事务式安装适配包(自动备份/回滚/receipt)
|
|
16
|
+
- `u-cli-mod exec <project> -- <pipeline-args>` - 执行 Pipeline 命令(工具统一绑定 `--project-path`)
|
|
17
|
+
- `u-cli-mod routes` / `u-cli-mod cache clean` - 路由表 / 缓存清理
|
|
18
|
+
|
|
19
|
+
## 使用规范(Agent 必须遵守)
|
|
20
|
+
|
|
21
|
+
1. **首次对某工程执行 `exec` 前**,必须确保 `doctor` 通过且适配包已安装(`setup` 或 `pipeline install` 已完成);未就绪时先跑 `setup`,不要直接 `exec`。
|
|
22
|
+
2. **禁止在 `exec` 参数中传入任何 `--project-path` 变体**(`-projectPath`、`--project_path`、大小写混合、`=` 形式等)——目标工程由工具统一绑定,传入即报错是预期保护,不要尝试绕过。
|
|
23
|
+
3. **运行中的 Unity Editor 是 fail-closed**:安装被阻止时引导用户先关闭目标工程的 Editor;除非用户显式要求,不得使用 `--allow-running-editor` 绕过。
|
|
24
|
+
4. **安装是事务式的**(staging → 校验 → 备份 → 替换 → 再校验 → receipt,失败自动回滚):不要手动清理工程内 `Packages/com.unity.pipeline` 或 `Library/editor-pipeline-cli`。
|
|
25
|
+
5. **版本路由是精确匹配**(`m_EditorVersion` + revision 同时一致),没有"就近版本"回退;工程版本不在路由表内时如实报告支持列表,不得猜测、不得改写 `ProjectVersion.txt`。
|
|
26
|
+
6. `exec` 每次调用前都会重新校验 CLI 哈希(防篡改),属正常行为;校验失败按提示跑 `u-cli-mod cli install --force` 修复即可。
|
|
27
|
+
|
|
28
|
+
## 典型流程
|
|
29
|
+
|
|
30
|
+
```bash
|
|
31
|
+
u-cli-mod doctor <project> # 1. 体检(只读)
|
|
32
|
+
u-cli-mod setup <project> # 2. 就绪(CLI + 适配包)
|
|
33
|
+
u-cli-mod exec <project> -- command editor_status # 3. 执行
|
|
34
|
+
```
|
package/README.md
CHANGED
|
@@ -90,7 +90,7 @@ npm run check # build + lint + 107 个 vitest 测试 + pack guard
|
|
|
90
90
|
|
|
91
91
|
`pack:guard` 会执行真实 `npm pack`(含文件清单校验),断言发布包:
|
|
92
92
|
|
|
93
|
-
- 包名为 `@kevlns/u-cli-mod`,tgz 文件名精确为 `kevlns-u-cli-mod-0.1.0-beta.
|
|
93
|
+
- 包名为 `@kevlns/u-cli-mod`,tgz 文件名精确为 `kevlns-u-cli-mod-0.1.0-beta.4.tgz`(与 package.json 版本一致);
|
|
94
94
|
- `files` 必须包含 `v-cli.plugin.json`,且清单身份字段(schemaVersion/package/command/bin/platforms)与包一致;
|
|
95
95
|
- 不出现:
|
|
96
96
|
|
|
@@ -147,6 +147,7 @@ npm run e2e:windows # 完整 Unity E2E(真实下载/转换/编译/命
|
|
|
147
147
|
routes/ 精确版本路由 + expected-tree 哈希清单
|
|
148
148
|
routes/expected-tree/ 385 文件 SHA-256 清单(含 Tests.meta)
|
|
149
149
|
templates/ Unity 生成的 .meta 模板(数据,非 Unity 源码)
|
|
150
|
+
AGENTS.md AI Agent 使用规范(场景/规范/速览)
|
|
150
151
|
src/ TypeScript 实现
|
|
151
152
|
tests/ Vitest 单元测试(自编合成 fixture,不含 Unity 源码)
|
|
152
153
|
scripts/ pack-guard / preflight-runner / e2e-windows / test-package-install
|
package/package.json
CHANGED
|
@@ -1,6 +1,6 @@
|
|
|
1
1
|
{
|
|
2
2
|
"name": "@kevlns/u-cli-mod",
|
|
3
|
-
"version": "0.1.0-beta.
|
|
3
|
+
"version": "0.1.0-beta.4",
|
|
4
4
|
"description": "u-cli-mod: pin exact Unity Editor version routes and install the adapted com.unity.pipeline package for Unity 2022 (Windows-first). Downloads Unity assets at runtime into the user cache; the package itself contains no Unity binaries or package source. Not an official Unity project.",
|
|
5
5
|
"private": false,
|
|
6
6
|
"publishConfig": {
|
|
@@ -19,6 +19,7 @@
|
|
|
19
19
|
"routes",
|
|
20
20
|
"templates",
|
|
21
21
|
"v-cli.plugin.json",
|
|
22
|
+
"AGENTS.md",
|
|
22
23
|
"README.md",
|
|
23
24
|
"LICENSE"
|
|
24
25
|
],
|