@alpsckr/unitycli 0.4.2 → 0.4.3
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.
|
@@ -1,8 +1,8 @@
|
|
|
1
1
|
{
|
|
2
2
|
"schemaVersion": 1,
|
|
3
3
|
"packageName": "com.alpsckr.unitycli",
|
|
4
|
-
"packageVersion": "0.4.
|
|
5
|
-
"sourceHash": "
|
|
4
|
+
"packageVersion": "0.4.3",
|
|
5
|
+
"sourceHash": "1dc579796f92655e727bc4409af186091a9ba460ac76477af260f2955d1ca29a",
|
|
6
6
|
"files": [
|
|
7
7
|
{
|
|
8
8
|
"path": "Editor/Bridge/BridgeCommandContext.cs",
|
|
@@ -1947,7 +1947,7 @@
|
|
|
1947
1947
|
{
|
|
1948
1948
|
"path": "package.json",
|
|
1949
1949
|
"size": 268,
|
|
1950
|
-
"sha256": "
|
|
1950
|
+
"sha256": "ebd1f3b6489fdb9916f254b81e3976c7258fe697308c01ca4912aa779403e20a"
|
|
1951
1951
|
}
|
|
1952
1952
|
]
|
|
1953
1953
|
}
|
package/package.json
CHANGED
package/skills/unitycli/SKILL.md
CHANGED
|
@@ -1,70 +1,54 @@
|
|
|
1
1
|
---
|
|
2
2
|
name: unitycli
|
|
3
|
-
description: 所有涉及 Unity
|
|
3
|
+
description: 所有涉及 Unity、Unity Editor 或 UnityPipeline 的任务都优先使用本 Skill，用于判断直接处理项目文件，或通过`unitycli` 入口发现当前 Editor 能力。
|
|
4
4
|
---
|
|
5
|
-
|
|
6
5
|
# UnityCLI
|
|
7
6
|
|
|
8
7
|
FeedbackMode: off
|
|
9
8
|
|
|
10
|
-
`unitycli` 是 AI 操作已打开 Unity Editor
|
|
9
|
+
`unitycli` 是 AI 操作已打开 Unity Editor 的运行时导航入口，不是固定工具手册。根据任务发现当前 catalog，读取所选 descriptor，再构造调用。
|
|
11
10
|
|
|
12
11
|
## 路由
|
|
13
12
|
|
|
14
|
-
-
|
|
15
|
-
-
|
|
16
|
-
-
|
|
17
|
-
-
|
|
18
|
-
- Extension 管理只用 `extensions list`、`extensions install`、`extensions remove`、`extensions doctor`。
|
|
19
|
-
- 已连接实例的目录同时包含 built-in、Extension、project、Editor 和 Runtime 能力，不按 `source` 或当前模式过滤。
|
|
20
|
-
- 完全兼容 Unity 官方 CLI 特性体系：项目与第三方 Package 中以官方 `[CliCommand]`/`[CliArg]`/`IStructuredCommandInput` 声明的命令直接进入同一 catalog，固定投影为 `UnityPipeline_<原名>`、group `UnityPipeline`，用 `command <原名>` 或完整前缀名调用；`com.unity.pipeline` 包自身命令已由 native 能力吸收并按 provider identity 抑制。native 精确重名优先。
|
|
21
|
-
|
|
22
|
-
## 安装协议
|
|
23
|
-
|
|
24
|
-
当用户要求安装、配置、检查或修复 UnityCLI 时，唯一学习入口是：
|
|
25
|
-
|
|
26
|
-
```powershell
|
|
27
|
-
unitycli init help
|
|
28
|
-
```
|
|
29
|
-
|
|
30
|
-
严格执行返回的版本化`aiInstructions`，不要依赖本Skill记忆安装步骤。先运行`init discover`；当前目录只有一个Unity项目时直接采用，用户已经指定的项目、scope、host或Skill目录都是最终决定，不得重复询问。未指定Skill目录时使用发现结果的当前workspace推荐目标；明确目录使用`init skill --target <SkillDirectory>`。准确目标Unity正在运行时只询问一次是否正常关闭；同意后使用`init package --close-editor`，不得强制终止，也不得替用户决定未保存场景弹窗。Bridge与Skill是独立授权效果，一个失败只阻断自身检查，不阻断另一个；每个成功效果都立即执行对应`--check`并最终汇总全部状态。安装流程不得启动或重启Unity。用户安装请求授权所选效果，除关闭Editor外不增加确认。
|
|
13
|
+
- 需要 Unity 内存、Editor API、导入/编译、PlayMode 或业务效果证明时使用 CLI。
|
|
14
|
+
- Unity 动作与观察能力都从同一 Tool catalog 发现。公开顶层只有 `tools`、`command`、`init`、`extensions`、`target`、`instances`、`doctor`；不要猜 Unity 能力域是顶层命令。
|
|
15
|
+
- 不知道能力领域时可看 group，已有业务关键词时可 search，得到 exact Tool 名后 describe。返回的 `name` 是调用名，group 和 `source` 不参与名称拼接或 owner 路由。
|
|
16
|
+
- `tools run` 与 `command` 复用同一 descriptor 和 schema。`[CliCommand("name")]` 投影为 `UnityPipeline_name`，也可由 `command name` 选择；native exact name 优先。
|
|
31
17
|
|
|
32
|
-
##
|
|
18
|
+
## 发现与调用
|
|
33
19
|
|
|
34
20
|
```powershell
|
|
35
|
-
#
|
|
21
|
+
# 目标未知、需要审计当前连接或错误要求检查实例时
|
|
36
22
|
unitycli instances list
|
|
37
|
-
|
|
38
|
-
unitycli instances prune --instance <id|projectPath|alias>
|
|
23
|
+
|
|
39
24
|
unitycli tools group --instance <id|projectPath|alias>
|
|
40
|
-
unitycli tools group list <group> --
|
|
41
|
-
unitycli tools search '<k1|k2|...>' --
|
|
25
|
+
unitycli tools group list <group> --instance <id|projectPath|alias>
|
|
26
|
+
unitycli tools search '<k1|k2|...>' --instance <id|projectPath|alias>
|
|
42
27
|
unitycli tools describe <tool> --instance <id|projectPath|alias>
|
|
43
28
|
unitycli tools run <tool> --input '<json>' --instance <id|projectPath|alias>
|
|
44
29
|
|
|
45
|
-
|
|
46
|
-
unitycli command --project-path <projectPath> --page-size 20
|
|
30
|
+
unitycli command --project-path <projectPath>
|
|
47
31
|
unitycli command <name> --field <value> --instance <id|projectPath|alias>
|
|
48
32
|
```
|
|
49
33
|
|
|
50
|
-
|
|
34
|
+
用户已给出目标或当前 Unity 项目 CWD 能唯一解析时可以直接使用；需要 selector 时优先只传一种，冲突的 `--instance` 与 `command --project-path` 会失败。不了解能力领域时可先看 group，已有业务关键词时可直接 search，第一次执行不了解的 Tool 前先 describe。
|
|
35
|
+
|
|
36
|
+
PowerShell 中以单引号包住内联 JSON 和 `tools search '<k1|k2|...>'`。任务业务值优先于 schema default 和 example；default/example 只说明合法形状，不作为 probe。分页、artifact、大输出、弹窗和 host 等待按需读取 `references/operation-protocol.md`。
|
|
37
|
+
|
|
38
|
+
## 通用规则
|
|
51
39
|
|
|
52
|
-
|
|
40
|
+
- descriptor 是输入、风险、availability、PlayMode 和依赖的当前契约；根据任务决定是否切换状态、预览或改用其他能力。
|
|
41
|
+
- 调用公开 Tool 或 CLI 控制面即为授权。风险 metadata 只描述效果与可选 dry-run；Skill 不增加确认或预定义操作范围。
|
|
42
|
+
- 等待 CLI 进程退出。`ok:true` 后检查任务相关的关键业务字段；返回结果不足或任务明确要求验证时，再使用只读 Tool 或业务 readback。
|
|
43
|
+
- 失败时根据结构化 error 和 `nextActions` 形成恢复决策。`transient:true` 与 `nextActions` 仍是建议，不构成额外授权门。
|
|
44
|
+
- `E_EXECUTION_TIMEOUT`、放行后连接丢失或缺少可信 terminal envelope只表示没有可信终态。先用只读Tool或业务readback观察并形成新的业务决策；CLI不自动重放，首次mutation POST后Editor session改变时也不会向新session重投。
|
|
45
|
+
- 状态观察使用 `instances`、`doctor` 或 `editor.state`，不操作内部 registry 或 transport。
|
|
53
46
|
|
|
54
|
-
|
|
47
|
+
## 能力扩展
|
|
55
48
|
|
|
56
|
-
|
|
49
|
+
现有 Tool 不适合时，先判断是否真的需要 Unity 侧执行。普通源码或文本仍可直接处理；有界的临时 Unity 内存或 Editor API 逻辑可以考虑 `code.exec`。同步 C# 开始后不能由 CLI timeout 中止，复杂等待或不确定终态先读 `references/operation-protocol.md`。
|
|
57
50
|
|
|
58
|
-
|
|
59
|
-
- 建议通过 `instances`、`doctor`、`tools run editor.state` 观察状态，不读取内部 Bridge 注册文件、端口或 URL，也不直接 ping transport。
|
|
60
|
-
- CLI会在发送Unity业务请求前自行等待首次ready记录、编译/导入/重载完成和target session任务池放行；不得手工每100毫秒循环调用，也不得读取或操作内部状态。`--timeout-ms T`分别提供最多`T`的准入等待与放行后最多`T`的业务执行。
|
|
61
|
-
- 准入deadline返回的`E_UNITY_BUSY`会明确证明`no business request was sent`，effect未开始，可以稍后提交新root。已进入池后的mutation lease busy不得解释为effect未开始。
|
|
62
|
-
- `E_EXECUTION_TIMEOUT`、放行后连接丢失或缺少可信terminal envelope只表示没有可信终态。先用只读Tool或业务readback观察并形成新的业务决策；CLI不自动重放，首次mutation POST后Editor session改变时也不会向新session重投。`transient:true`与`nextActions`仍是建议，不构成额外授权门。
|
|
63
|
-
- 运行公开CLI时必须等待该进程退出，不得后台分离。传入`--timeout-ms T`时，命令host至少等待`2 * T + 5000`毫秒；CLI在stdout完成或最多1秒后退出。host提前超时不等于CLI、准入grant或Unity effect已经停止。
|
|
64
|
-
- `available:false`、`unavailableReason` 和 `playModeSupport` 说明当前可执行性；`source` 不参与路由。
|
|
65
|
-
- blocker 在 `error.details.blockers` 时，可先读 `editor.dialogs`，再按返回的 dialogId 与 enabled button 调用 `editor.dialog.click`。
|
|
66
|
-
- 大输出、envelope、artifact、分页、host等待预算和 session 说明见 `references/operation-protocol.md`。
|
|
67
|
-
- 内置能力不足时，一次性操作可使用 `code.exec`；反复需要再读 `references/custom-tools.md`。`code.exec`不限制提交的同步C#，也不会拒绝死循环、长时间sleep、阻塞等待、锁等待或长期占用Unity API的代码。提交这类代码前必须先判断它对当前结果是否确有必要，并考虑有界写法或现有Tool能否达到同一结果；确有必要时可以原样执行。代码一旦在Unity主线程开始，`--timeout-ms`只能停止CLI等待，不能中止代码；Unity可能无响应、mutation owner不能收尾、业务状态部分改变或未知，恢复可能需要结束Editor进程。timeout不证明代码已停止，重试前必须观察业务状态。`--dry-run`只预览source hash，不编译、不执行，也不证明代码会结束。
|
|
51
|
+
当能力需要稳定发现、typed schema、结构化结果、明确副作用、重复使用或团队共享时，读取 `references/custom-tools.md` 并实现项目自定义 `IUnityCliTool<TReq,TRes>`。自定义 Tool 仍从当前 catalog 发现、describe 和调用，不假设名称、group 或输入。
|
|
68
52
|
|
|
69
53
|
## 问题反馈
|
|
70
54
|
|