unity-package

**调用此模块中的任何技能之前：**如果你打算根据技能名称或描述猜测参数后调用技能，请停下——先阅读此文件（或通过 GET /skills/recommend?includeSchema=true 获取其架构）。如果你已从 recommend/schema 获取参数定义，可以直接进行 dryRun。

触发条件

• 添加或移除 UPM 包
• 检查已安装的版本
• 搜索 registry
• 脚本化包操作
• 添加或移除 UPM 包、检查已装版本、搜索 registry、脚本化包操作

包技能

管理已安装的 Unity 包，以及 Cinemachine 和 Splines 设置等与包相关的辅助流程。

防护措施

操作模式（v1.9 三层模式）：

• Approval（默认）：查询技能（package_list、package_check、package_search、package_get_dependencies、package_get_versions、package_get_cinemachine_status）可直接运行。package_refresh 是唯一的 FullAuto 修改操作——在 MODE_RESTRICTED 下，需为其运行授权协议。其他所有修改操作均会被自动禁止（见下一条），授权也不会解锁它们。
• Auto / Bypass：SemiAuto 和 FullAuto 可直接运行。
• 此模块中自动禁止的技能：package_install、package_remove、package_install_cinemachine、package_install_splines（它们均为 MayTriggerReload = true、RiskLevel = "high"；package_remove 还带有 SkillOperation.Delete）。在 Approval 和 Auto 模式下，它们都会返回 MODE_FORBIDDEN，只有在 Bypass 模式或通过用户管理的 Allowlist 条目才能使用；授权流程也会返回 MODE_FORBIDDEN，因此不要尝试。
• 安装、移除和刷新任务会立即返回 jobId；实际的包导入和 Domain Reload 会异步发生，并可能导致 REST 服务器暂时不可用。使用 job_status / job_wait 轮询。

不要（常见的幻觉）：

• package_add / package_update 不存在 -> 请使用 package_install
• package_get_info 不存在 -> 请使用 package_list、package_check、package_get_dependencies 或 package_get_versions
• package_search 只搜索已安装包缓存；它不会查询 Unity Registry
• 包查询技能会在 Domain Reload 后自动初始化缓存。在短暂的冷启动窗口内，它们会返回 { success: false, status: "refreshing", cacheReady: false, retryStrategy: "wait_and_retry", retryAfterSeconds: 2 }；请重试，不要将其视为 installed=false。
• 包安装、移除和刷新任务可能触发包导入和 Domain Reload；请预期服务器可能暂时不可用，并使用返回的任务 ID

路由：

• Cinemachine 快速设置 -> 使用 package_install_cinemachine
• Splines 快速设置 -> 使用 package_install_splines
• 检查项目清单 -> 使用 project_get_packages
• 安装包后更改定义符号 -> 使用 debug_set_defines

技能

package_list

列出 UnitySkills 当前缓存的所有已安装包。 **参数：**无。

返回：{ success, count, packages }

package_check

检查是否已安装某个包。

参数	类型	必填	默认值	描述
packageId	string	是	-	包 ID，例如 com.unity.cinemachine

返回：{ packageId, installed, version }

package_install

安装一个包。请求被接受后会返回一个异步任务。

参数	类型	必填	默认值	描述
packageId	string	是	-	要安装的包 ID
version	string	否	null	可选的显式版本

返回：{ success, status, jobId, message, serverAvailability }

package_remove

移除已安装的软件包。请求被接受后会返回一个异步任务。

参数	类型	必填	默认值	描述
packageId	string	是	-	要移除的已安装软件包 ID

返回： { success, status, jobId, message, serverAvailability }

package_refresh

刷新查询技能使用的已安装软件包缓存。 参数： 无。

返回： { success, status, jobId, message }

package_install_cinemachine

使用受支持的软件包／版本策略安装 Cinemachine。

参数	类型	必填	默认值	描述
version	int	否	3	2 表示 CM2，3 表示 CM3；其他值均会被拒绝

注意：

• CM3 会自动安装 Splines 依赖项。
• 如果所请求的版本系列已安装，此技能可以直接返回成功，而不创建任务。

返回： { success, status?, jobId?, message, serverAvailability? }

package_install_splines

根据当前 Unity 编辑器版本系列的推荐版本，安装或升级 Unity Splines。 参数： 无。

返回： { success, status?, jobId?, message, serverAvailability? }

package_get_cinemachine_status

获取当前 Cinemachine 和 Splines 的安装状态。 参数： 无。

返回： { cinemachine, splines }

package_search

按软件包名称或显示名称搜索已安装的软件包缓存。

参数	类型	必填	默认值	描述
query	string	是	-	搜索关键词

返回： { success, query, count, packages }

package_get_dependencies

获取一个已安装软件包的依赖信息。

参数	类型	必填	默认值	描述
packageId	string	是	-	已安装软件包 ID

返回： { success, packageId, version, dependencyCount, dependencies }

package_get_versions

获取一个已安装软件包的可用版本。

参数	类型	必填	默认值	描述
packageId	string	是	-	已安装软件包 ID

返回： { success, packageId, currentVersion, compatibleVersion, latestVersion, allVersions }

精确签名

精确的名称、参数、默认值和返回值由 GET /skills/schema 或 unity_skills.get_skill_schema() 定义，而非本文件。