# Asset3D：Skill + CLI

Asset3D 默认关闭。插件内的 TypeScript CLI 直接调用 AW/EA HybridSearch，下载原生
Pack 或 GLB，再交给固定版本 Engine 导入。没有 Python Provider、Asset3D MCP 或转换服务。

## 使用

```bash
npx -y @forgeax/game@latest install --ide codex
# 在空目录
npx -y @forgeax/game@latest init
npx -y @forgeax/game@latest asset3d enable --ide codex --library ea --base-url "<获授权的 EA 网关>"
scratch="$(mktemp -d /tmp/forgeax-selection.XXXXXX)"
npx -y @forgeax/game@latest asset3d candidates --query "wooden crate" --engine-version 0.4.3 --json > "$scratch/candidates.json"
npx -y @forgeax/game@latest asset3d import --query "wooden crate" --engine-version 0.4.3 \
  --candidate-file "$scratch/candidates.json" --candidate-name "<候选的完整名称>" --json
```

以上命令仅适用于本次升级版本发布后；当前 npm `@latest` 不代表本地候选。
发布前本地候选验证可用已安装包的
`node "/absolute/consumer/node_modules/@forgeax/game/dist/main.js"` 替代 npx 前缀，
启用时加 `--local`。`--candidate-name` 使用搜索响应中的完整名称；若短文件名唯一也可使用。

> [!IMPORTANT]
> 明确声明不兼容当前 Engine 的资产会被拒绝；缺少版本元数据属于兼容性未知，
> 不能据此承诺可用，必须继续通过导入、构建和 Preview 验证。若 `0.4.3` 筛选后无候选，
> 应请资产库发布兼容版本；不要去掉版本约束强行导入旧 Pack。

默认库为 AW；EA 需要 `--library ea --base-url "<获授权的网关>"`，
也可设置 `FORGEAX_ASSET_LIBRARY_BASE_URL`。显式 URL 不会在失败后回退。
当前服务采用 `X-Sandbox-Key`，首次 enable 隐藏输入并执行真实搜索探测。
自动化使用 `FORGEAX_ASSET3D_AW_SANDBOX_KEY`；`--json` 缺凭证不会等待输入。

凭证保存在项目外的私有文件；项目 `.forgeax/extensions/asset3d/config.json` 只保存服务地址、
库、凭证文件引用、允许的下载来源和版本。Skill 归属由统一的 install.json 记录。
只挂载所选 Host 的一个 SKILL.md。
`install/update` 会移除可确认由旧插件创建的 Asset3D MCP 注册；自定义注册保留并提示。

## 命令和结果

| 命令 | 语义 |
|:--|:--|
| enable | 探测服务，保存配置和 Skill |
| doctor --json | 本地配置、Engine 与 CLI 身份；可恢复中断的提交，不代表远端可访问 |
| candidates [--query …] --json | 返回描述、风格、缩略图、版本等选择信息；不暴露资产签名下载 URL |
| import [--query …] (--asset-id … \| --candidate-file … --candidate-name …) [--version …] --json | 从保存的候选按唯一名称取 ID/当前版本，或传入显式 ID；按同一查询/筛选重新确认，再下载、校验、Engine 导入和身份读回 |
| disable --json | 撤销 Skill、配置和临时数据；修改过的 Skill 移到非发现目录备份，保留资产和共享凭证 |

原生 `.pack.ts/.pack.json` 及其辅助文件保留完整；不伪装成 GLB。
导入源位于 `assets/3d/ea-3d/<assetId>`，结果返回 `deliveredFormat` 与 Engine GUID。
同摘要资产校验后可复用；已有内容发生变化时失败，不静默覆盖。

## 选择和使用资产

搜索以 1–3 个英文关键词表达对象/用途，默认类型为 1（3D 模型），混合检索阈值 0.3、
最多 10 个候选。`--query` 可省略，成功响应缺失/空 `asset_list` 返回空候选。
不在 CLI 中自动改写用户需求或取消筛选；Skill 引导模型在无结果时放宽非必要条件一次。

| 参数 | 含义 |
|:--|:--|
| `--asset-type` | 1 模型、2 纹理、3 BGM、5 动画模型、6 VFX、7 音效、8 材质、9 天空盒、11 Kit |
| `--category` | 类别硬筛选，3/11 不适用 |
| `--art-style` / `--theme-style` | 服务枚举硬筛选，3/7/11 不适用 |
| `--engine-version` | 单一 Engine 版本硬筛选；不推测版本号 |
| `--version` | 仅 import：明确选择候选 `versions[].versionName` |
| `--candidate-file` / `--candidate-name` | 仅 import：从已保存的 `candidates --json` 响应选唯一全名或文件名，避免手抄长 ID；不能与 `--asset-id` 同用 |

模型使用 `description`、`detailedDescription`、`category`、`artStyle`、`themeStyle`、
`customTags` 和可选 `thumbnailUrl` 判断用途与视觉匹配，不只按分数或排名。
缩略图链接是临时预览数据，不写入项目源文件；资产下载 URL 由 CLI 内部使用。
版本列表保留 `engineVersions`，缺失字段不等于兼容；版本筛选匹配到非当前版本时，
必须显式选择该版本，不能回退下载顶层/current URL。

搜索类型支持不等于导入格式支持：目前仍只导入 Pack/GLB 及包含它们的 ZIP，
不承诺独立音频、图片或任意 Kit 可被 Engine 导入。导入后读取资产 README/manifest，
检查尺寸、朝向、材质、动画和碰撞能力，再通过 GUID 实例化并在 Preview 验证。

请求不跟随重定向，下载只允许 enable 确认的来源，不带 API Key；
ZIP 解压限制路径、文件数、单文件和总大小。下载器不执行源码，
但 Engine 构建 Pack 会执行其中代码，因此资产库必须受信。

## 验收边界

导入成功不是游戏完成。用返回 GUID 接入游戏，启动 Engine-owned Preview，再验证
可见资产和操作。分别报告服务探测、真实搜索、导入、构建和可玩验证。

本次是破坏式精简：旧 begin/search/commit、Provider install 和 asset3d mcp 不再公开。
旧项目资产不会改动；建议全新目录验证。旧 Skill 若有冲突，先人工保存/移走旧目录后 enable，
不要强制覆盖用户修改。Windows 未经真实验证；macOS/Linux 以本轮测试证据为准。