@forgeax/game 0.3.6 → 0.3.8

package/docs/asset3d.md

@@ -1,207 +1,57 @@
-# Asset3D local provider and Engine transaction
+# Asset3D：Skill + CLI
 
-Asset3D is a project-local integration composed from three separately reviewed
-inputs: the `asset3d-search` provider bundle, the `art-3d-asset-library` workflow
-package, and the released ForgeaX Engine SDK. `@forgeax/game` owns installation,
-configuration, quarantine validation, transaction state, and the handoff to the
-Engine CLI. It does not call an asset service directly and does not implement a
-second importer or Preview server.
+Asset3D 默认关闭。插件内的 TypeScript CLI 直接调用 AW/EA HybridSearch，下载原生
+Pack 或 GLB，再交给固定版本 Engine 导入。没有 Python Provider、Asset3D MCP 或转换服务。
 
-> [!IMPORTANT]
-> Asset3D is disabled by default. `install` and ordinary `init` neither contact the
-> internal catalog nor write Asset3D project state. The user must run `asset3d enable`
-> inside an already initialized Engine game.
+## 使用
 
-> [!IMPORTANT]
-> Provider archives are platform-specific artifacts. The npm package embeds the
-> currently released Darwin arm64 and Linux x64 archives so a cache-empty user does
-> not depend on a private source repository or release download. Linux requires an
-> x86-64 host and Python 3.11 or 3.12. Installation deliberately returns
-> `provider_platform_mismatch` when an archive target differs from the current host.
-> Unsupported targets such as Linux arm64 and Windows fail closed. Each bundled
-> target therefore needs its own digest, offline verification, MCP handshake, and
-> real service-path evidence.
-
-## Trust and data flow
-
-```mermaid
-flowchart LR
-    U["Hidden key input or automation secret"] --> CRED["Private user credential file"]
-    B["Provider archive bundled in npm"] --> C["Managed digest cache"]
-    PKG["Exact K0 workflow TGZ"] --> S["Nine project Skill mounts"]
-    C --> M["Project-local stdio MCP"]
-    CRED --> M
-    M --> H["AW HybridSearch access check"]
-    H --> D["Exact signed-download origins"]
-    M --> Q["Private transaction quarantine"]
-    Q --> V["Checked result and file manifest"]
-    V --> A["Atomic asset-directory publication"]
-    A --> E["Exact Engine semantic-only asset add"]
-    E --> R["Engine verify, list, and inspect"]
-    R --> P["Per-file provenance and terminal result"]
-```
-
-The provider is the only network adapter. `asset3d enable` invokes its bounded
-`--check-aw-access` mode before publishing project configuration. That mode calls AW
-`HybridSearch` with the documented `X-Sandbox-Key` header and required 3D search
-fields, then emits only `authentication=sandbox-key` plus the canonical origins of
-returned short-lived `res_url` values. Asset IDs, candidates, signed URLs, request
-bodies, and the key are never returned by the access check.
-
-Installed download authorities are
-lexically exact `http://host:port` or `https://host:port` values: explicit port,
-no path (including `/`), no query, fragment, userinfo, or wildcard. The canonical
-one-to-eight member set is sorted and encoded as compact JSON in
-`AW_DOWNLOAD_ORIGINS`; `.forgeax/asset3d-install.json` records only its SHA-256
-digest. The provider is responsible for enforcing that set on both initial and
-redirect requests.
-
-Normal installation writes the selected service root to `AW_API_BASE_URL`, the
-matching `AW_API_DEPOT_NAME=aw|ea`, and an absolute user credential-file path to
-`AW_API_CREDENTIAL_FILE`. The `AW_API_*` names are the packaged Provider's legacy
-environment contract. Installation never writes `AW_API_SANDBOX_KEY` into project
-MCP configuration. `--catalog-base-url` remains a
-maintainer-only compatibility adapter for the retired directory service; when used,
-its authority must also appear in `--download-origin`.
-
-## Installation ownership
-
-`asset3d enable` keeps the public AW depot by default. `--library ea` selects the EA
-depot and its office-network local gateway; `FORGEAX_ASSET_LIBRARY=ea` is the
-deployment equivalent. Gateway selection precedence is explicit `--base-url`, then
-`FORGEAX_ASSET_LIBRARY_BASE_URL`, then the selected library's built-in service.
-Gateway overrides never change the selected depot. The first interactive run asks
-for the Sandbox Key with terminal echo
-disabled. Automation can supply `FORGEAX_ASSET3D_AW_SANDBOX_KEY` from a secret store;
-command-line key arguments are deliberately unsupported.
-
-The credential is stored outside the project at
-`~/.forgeax/credentials/asset3d-aw.json` by default. The directory is `0700`; the
-file must be regular, owned by the current user, non-symlink, at most 4 KiB, and
-`0600`. The Provider accepts only the versioned AW credential schema. A failed access
-check or downstream installation rolls back a newly written value. An existing valid
-credential makes repeat enablement idempotent. The plugin never treats Anthropic or
-another model-provider credential as an Asset3D key.
-
-The command reuses an exact verified cache when present. Otherwise it opens the
-platform archive carried by the installed `@forgeax/game` package and verifies the
-pinned SHA-256 before any provisioning. No Provider download or source-repository
-authentication occurs during `asset3d enable`. Bundle schema, provider commit,
-platform, Python range, and checked result/receipt schema digests are then verified
-before invoking the offline bundle verifier. Provisioning uses system
-Python 3.11 or 3.12 and the Provider's hash-locked `--provision` flow. The published
-cache is keyed by archive digest under `~/.forgeax/providers/asset3d-search/`.
-
-The low-level `asset3d install --provider-bundle ...` command remains a maintainer
-surface for bundle production and controlled evidence; users enable the pinned
-archive carried by their installed Game Plugin rather than selecting an arbitrary
-archive.
-
-The installer merges, rather than replaces, the complete `.forgeax/mcp.json` object.
-Unrelated top-level keys and servers survive. The owned entries are local stdio only:
-
-| Server | Tool timeout | Operation bound |
-|:--|--:|--:|
-| `asset3d-search` / `search_asset` | 195,000 ms | provider work 180,000 ms plus cleanup and bridge margin |
-| `forgeax` / `forgeax_run_current_game` | 165,000 ms | Game Plugin build/readiness 150,000 ms plus cleanup and bridge margin |
-| either server, unknown tool | 30,000 ms | project-MCP default |
-
-A conflicting server is not overwritten. `--replace-owned` is accepted only when the
-current entry still matches the prior ownership digest. Configuration, manifests,
-journals, locks, and provenance are private; file publication uses same-directory
-temporary files, file and directory fsync, and atomic rename. Reinstall is byte
-idempotent. Uninstall removes only entries and Skill files that still match owned
-digests, leaving user-modified or unrelated content in place and reporting the
-collision.
-
-For user-scoped MCP hosts such as Codex, Cursor, and Claude, `enable` additionally
-registers a non-secret `asset3d-search` bridge command. The bridge resolves
-`.forgeax/asset3d-install.json` and the owned `.forgeax/mcp.json` entry from the host
-process working directory, rather than pinning a user config to one project. A
-project without an Asset3D installation receives a healthy MCP handshake with an
-empty tool list. Start a new Agent session after enabling so `search_asset` appears.
-
-The workflow package is projected beneath `art-3d-asset-library/` in exactly these
-mounts unless `--ide` selects a subset:
-
-```text
-.agents/skills                 .claude/skills
-.cursor/skills                 .trae/skills
-.codebuddy/skills              .codeium/windsurf/skills
-.vscode/skills                 .zcode/skills
-.config/opencode/skills
+```bash
+npx -y @forgeax/game@0.3.8 install --ide codex
+# 在空目录
+npx -y @forgeax/game@0.3.8 init
+npx -y @forgeax/game@0.3.8 asset3d enable --ide codex
+npx -y @forgeax/game@0.3.8 asset3d candidates --query "wooden crate" --json
+# 阅读候选后选择 ID
+npx -y @forgeax/game@0.3.8 asset3d import --query "wooden crate" --asset-id "<返回的ID>" --json
 ```
 
-`workbuddy` is an input alias for the `.codebuddy/skills` mount. Every projected file
-has its path, byte count, and digest in the ownership manifest.
+以上版本为当前本地候选，发布前不能通过 npm 获取；本地验证使用已安装候选的
+`node "/absolute/consumer/node_modules/@forgeax/game/dist/main.js"` 替代 npx 前缀。
+本地候选启用时加 `--local`；安装后的 Skill 自动包含匹配的命令。
 
-## Transaction protocol
+默认库为 AW；EA 需要 `--library ea --base-url "<获授权的网关>"`，
+也可设置 `FORGEAX_ASSET_LIBRARY_BASE_URL`。显式 URL 不会在失败后回退。
+当前服务采用 `X-Sandbox-Key`，首次 enable 隐藏输入并执行真实搜索探测。
+自动化使用 `FORGEAX_ASSET3D_AW_SANDBOX_KEY`；`--json` 缺凭证不会等待输入。
 
-For native Packs, first call `list_asset_candidates` with English queries and
-choose a suitable returned `assetId` by name and format. This does not download
-assets or call an auxiliary LLM. Keep the same query text in `asset3d begin`, then
-call `search_asset` with `queries: [{content: "<query>", assetId: "<selected ID>"}]`
-and `output_format: "asset"`. The Provider checks that the ID still belongs to the
-live query results; an invented or stale ID fails instead of selecting another
-asset. A GLB result does not prove native Pack support.
+凭证保存在项目外的私有文件；项目 `.forgeax/extensions/asset3d/config.json` 只保存服务地址、
+库、凭证文件引用、允许的下载来源和版本。Skill 归属由统一的 install.json 记录。
+只挂载所选 Host 的一个 SKILL.md。
+`install/update` 会移除可确认由旧插件创建的 Asset3D MCP 注册；自定义注册保留并提示。
 
-1. `asset3d begin` records a private journal with a new execution UUID, query digest,
-   provider identity, exact Engine identity, requested count, and the only allowed
-   quarantine root.
-2. `search_asset` accepts that execution UUID instead of an output path. The Game
-   Plugin bridge verifies the exact queries and injects the transaction-owned
-   provider directory beneath its private `workspace/` root.
-3. The configured provider writes beneath that directory and returns one checked
-   `forgeax.asset3d-search-result/1.0.0` TextContent JSON object. The bridge stores
-   those exact bytes against the execution; the agent does not copy the object.
-4. `asset3d commit --execution <uuid>` reads the stored result (at most 1 MiB),
-   validates exact fields/counts/roles/digests/sorted relative paths, and ignores
-   `downloaded_to`.
-5. The transaction rejects symlinks, special files, undeclared files, realpath escape,
-   byte mismatch, or digest mismatch before a project asset write.
-6. A 30-second per-asset lock serializes publication at
-   `assets/3d/ea-3d/<safeAssetId>`. The complete prior directory is preserved as the
-   refresh/rollback snapshot.
-7. With the game root as `cwd`, Game Plugin runs the exact released Engine CLI.
-   For GLB imports:
+## 命令和结果
 
-   ```text
-   asset add assets/3d/ea-3d/<safeAssetId> --reimport-policy semantic-only --json
-   asset verify --json
-   asset list --json
-   asset inspect <guid> --json
-   ```
+| 命令 | 语义 |
+|:--|:--|
+| enable | 探测服务，保存配置和 Skill |
+| doctor --json | 本地配置、Engine 与 CLI 身份；可恢复中断的提交，不代表远端可访问 |
+| candidates --query … --json | 返回候选 ID、名称、格式；不暴露签名下载 URL |
+| import --query … --asset-id … --json | 重新确认候选，下载、完整性校验、Engine 导入和身份读回 |
+| disable --json | 撤销 Skill、配置和临时数据；修改过的 Skill 移到非发现目录备份，保留资产和共享凭证 |
 
-   Each command must produce exactly one newline-terminated, at-most-1-MiB
-   `CommandEnvelope@1.0.0`. Game Plugin does not filter diagnostic stdout into a
-   synthetic success.
-   Native Pack sources instead use the Engine build and verified build catalog;
-   the plugin preserves the complete source closure and reads cooked scene/mesh
-   GUIDs back. It does not run `asset add` on `.pack.ts` or `.pack.json`.
-8. Only after Engine readback succeeds does `.forgeax-asset.json` publish the provider
-   commit, origin-set digest, exact Engine version/commit, per-file role/digest/bytes,
-   Engine rows, and catalog readback. An Engine failure restores the whole previous
-   asset directory.
+原生 `.pack.ts/.pack.json` 及其辅助文件保留完整；不伪装成 GLB。
+导入源位于 `assets/3d/ea-3d/<assetId>`，结果返回 `deliveredFormat` 与 Engine GUID。
+同摘要资产校验后可复用；已有内容发生变化时失败，不静默覆盖。
 
-Same provider ID and aggregate digest can reuse the existing directory only when all
-declared live files still match and recorded Engine GUIDs remain in list/inspect
-readback. A changed digest fails unless `--refresh` is explicit. `asset3d doctor`
-restores a stale `committing` snapshot and never reports the interrupted operation as
-successful; `asset3d abort` removes only its transaction quarantine.
+请求不跟随重定向，下载只允许 enable 确认的来源，不带 API Key；
+ZIP 解压限制路径、文件数、单文件和总大小。下载器不执行源码，
+但 Engine 构建 Pack 会执行其中代码，因此资产库必须受信。
 
-## Distribution and evidence boundary
+## 验收边界
 
-The packed Game Plugin includes the self-contained CLI bundle, existing connector
-Skill, exact K0 TGZ, checked P0 result/receipt schemas, and an inert, digest-pinned
-Provider archive for every supported target. It does not embed a provisioned Python
-environment, managed Provider cache, Engine payload, source checkout, credentials, or
-workspace links. A disabled installation neither extracts an archive nor contacts a
-network service. The package artifact gate recomputes every embedded predecessor
-digest.
+导入成功不是游戏完成。用返回 GUID 接入游戏，启动 Engine-owned Preview，再验证
+可见资产和操作。分别报告服务探测、真实搜索、导入、构建和可玩验证。
 
-Controlled external-consumer evidence may establish package installation, raw MCP
-framing, local redirect/ZIP handling, multi-GLB and texture import, reuse, refresh,
-failure rollback, offline recovery, Engine build/Preview health, uninstall, and
-process cleanup. Its status is `PASS_SUPPORTING`. Real provider network results,
-Studio project-MCP discovery, supported-host permission behavior, RuntimeInstance UI,
-visible Play, and final independent acceptance remain outside this repository unit.
+本次是破坏式精简：旧 begin/search/commit、Provider install 和 asset3d mcp 不再公开。
+旧项目资产不会改动；建议全新目录验证。旧 Skill 若有冲突，先人工保存/移走旧目录后 enable，
+不要强制覆盖用户修改。Windows 未经真实验证；macOS/Linux 以本轮测试证据为准。

package/docs/plugin-integration-standard.md

@@ -0,0 +1,196 @@
+# 扩展接入规范：一个目录，Skill + CLI
+
+适用范围：统一目录扩展实现 `d3fd8d7d`，本地 `@forgeax/game 0.3.8` 候选，尚未发布。本文是扩展作者和集成同学的交付契约，不是已发布版本的功能承诺。
+
+扩展作者交付自包含目录，放入 `extensions/`。不修改主 CLI 分发或安装器，不注册 MCP、全局命令或后台服务。扩展是随包审核发布的可信代码，不是沙箱代码。
+
+## 谁负责什么
+
+| 角色 | 交付与职责 | 不需要做 |
+|:--|:--|:--|
+| 扩展作者 | 一个目录：清单、Skill、CLI 业务模块，以及业务测试/配置说明 | 修改主 CLI、操作 Agent 配置、实现 enable/disable 安装逻辑 |
+| 主插件维护者 | 审核目录与依赖，构建打包，执行接入验收，随主包发布 | 为每个扩展添加命令分支 |
+| 最终用户 | 安装主插件、初始化项目、显式启用需要的扩展 | 全局安装每个扩展的 CLI、配置资产 MCP |
+
+当前只支持随主包交付的内置扩展。把目录放进游戏项目不会自动加载；也没有 `install <第三方目录或URL>` 命令。作者把目录交给主插件维护者或提交到主仓的 `extensions/`。
+
+## 目录契约
+
+```text
+extensions/example/
+  extension.json
+  cli.mjs
+  skills/example-use/SKILL.md
+```
+
+```json
+{"schemaVersion":1,"id":"example","version":"1.0.0","skills":["skills/example-use"],"cli":"cli.mjs"}
+```
+
+CLI 为 Node ESM 模块。仓内可用 `cli.ts` 编写，打包器自动编译成 `cli.mjs` 并收拢依赖；交付目录可直接提供 `cli.mjs`。清单路径不得越界或通过软链接逃逸。第一版 Skill 只交付 `SKILL.md`。
+
+| 字段 | 当前约束 |
+|:--|:--|
+| `schemaVersion` | 固定数字 `1` |
+| `id` | 与目录名一致；小写字母开头，后接小写字母、数字或连字符，总长不超过 64 |
+| `version` | `数字.数字.数字`，如 `1.0.0`；当前不接受预发布后缀 |
+| `skills` | 至少一个 `skills/<名称>`；名称使用小写字母开头及小写字母、数字、连字符 |
+| `cli` | 构建契约固定为 `cli.mjs`；源文件二选一 `cli.mjs` 或 `cli.ts`，不要同时提交过期 JS 和新 TS |
+
+ID 不得占用主命令：`install/init/uninstall/update/use/doctor/preview/devkit/agents/help/version`。
+Skill 名应带能力前缀并保持唯一，避免不同扩展占用同一个 Agent 目录。
+可以有 `src/` 辅助模块，通过静态 import 收入 CLI 构建产物；当前不自动复制扩展的任意资源目录、额外 Skill 文件或独立 `node_modules`。
+新增第三方依赖须由维护者加入主仓依赖并审核许可；不要求用户在游戏里为扩展运行 npm install。
+
+## CLI 契约
+
+```js
+export async function check(context, args) {
+  // 校验启用参数、服务和认证。失败抛错，不写 Agent 配置。
+  return { endpoint: "https://example.com" }; // 仅非秘密配置
+}
+
+export async function run(context, args) {
+  // 实现领域操作；返回可 JSON 序列化的结果，失败抛 Error。
+  return { items: [] };
+}
+```
+
+`context` 提供 `projectRoot`、`stateDir`、`packageVersion`。读取 `stateDir/config.json` 获取 check 返回的配置；临时业务状态只能放 `stateDir/data/`。用户明确要求导入的成果写入项目资产目录，不属于卸载垃圾。
+
+| 字段 | 含义 |
+|:--|:--|
+| `projectRoot` | 当前游戏的根目录 |
+| `stateDir` | 当前扩展的受管目录：`.forgeax/extensions/<id>` |
+| `packageVersion` | 正在运行的主插件版本，不是扩展清单版本 |
+
+这里的 CLI 是由 `forgeax-game <id> ...` 加载的业务模块，不是要求用户直接执行 `node cli.mjs`。模块顶层不得启动业务、读写项目或等待输入；行为放在导出的函数内。当前在主进程内加载，没有隔离沙箱。
+
+- `check(context, args)`：接收移除 `--ide` 和 `--local` 后的 enable 参数；`--json` 仍会传入。返回非秘密 JSON 配置，不自行创建 `install.json` 或挂载 Skill。不能要求已有 stateDir，因为发布在检查成功后发生。
+- `run(context, args)`：接收业务操作名及剩余参数，如 `["query", "--json"]`。所有领域参数由扩展自己校验。`doctor` 不是自动生成的，确有需要时由扩展实现。
+- 返回值必须能 JSON 序列化；不要返回 `undefined`、BigInt、循环对象或完整秘密请求。失败抛出 `Error("稳定错误码: 安全说明")`，不要把含 Key 的原始错误直接上抛。
+- 交互认证提示只用于交互终端；`--json` 缺凭证时立即失败，不无限等待。当前没有公共凭证存储 API，扩展自行使用受控私有文件/环境变量；不要声称安装器会自动管理任意凭证。
+
+主入口统一处理 `enable/disable`、选定 Agent、版本固定、Skill 发布、失败回滚、文件所有权和项目登记。`run` 只收到业务操作；未启用时主入口拒绝调用。业务实现不能输出额外 stdout，诊断用 stderr；主入口输出 JSON envelope 和退出码。
+
+```json
+{"schemaVersion":"1.0.0","command":"example.query","ok":true,"value":{"items":[]}}
+```
+
+```json
+{"schemaVersion":"1.0.0","command":"example.query","ok":false,"error":{"code":"example_access_denied","message":"example_access_denied: access rejected"}}
+```
+
+正常完成退出 0，失败非 0。顶层 `failed` 是批处理失败计数字段；当前主入口看到 `failed > 0` 会报告失败，普通业务不要用这个字段表达其他含义。合法空列表与服务失败要分开。
+
+| 操作 | 约定 |
+|:--|:--|
+| `forgeax-game example enable --ide codex` | check 成功后发布配置、Skills 和安装记录 |
+| `forgeax-game example query --json` | 通用路由调用 run，业务名由扩展决定 |
+| `forgeax-game example disable` | 离线撤销 Skills、启用记录、配置和临时数据；重复调用安全 |
+| `forgeax-game uninstall` | 当前项目级联停用所有扩展，再清理主插件注册 |
+| `forgeax-game uninstall --all-projects` | 清理已登记项目；不可访问项目报错，不能声称完全卸载 |
+
+`npm uninstall` 只删除 npm 安装，不替代产品的卸载命令。项目登记位于用户 `.forgeax/extension-projects.json`；不扫描磁盘。可用 `FORGEAX_USER_STATE_DIR` 隔离管理状态。
+
+**作用域注意**：扩展 Skill/启用记录属于项目；主 `forgeax` MCP 的作用域由 Agent 决定，Codex 是用户级。主插件 `uninstall` 不只是当前目录文件清理，也会移除所选 Agent 的主注册。只想停用当前项目的某项能力，使用 `<id> disable`。
+
+`enable --ide` 是增量挂载：再次选择其他 Agent 会保留此前登记的挂载；`disable` 一次回收该扩展的所有已登记挂载，不支持按 Agent 单独停用。主插件或扩展版本改变后要重新 enable；`update` 当前不会自动重新检查并启用各扩展。
+
+受管目录只记录由新安装器登记的项目。`--all-projects` 不是旧版本目录或用户手工配置的全盘清理工具。npm 包内的扩展代码是共享分发内容，disable 撤销的是运行资格与项目注册，不删除共享包文件。
+
+## Skill 契约
+
+````markdown
+---
+name: example-use
+description: Query the example service when the user requests its data.
+---
+
+从项目目录执行 `{{CLI}} query --json`，根据返回结果继续操作。
+失败时说明阻塞，不伪造结果。
+````
+
+安装器把 `{{CLI}}` 替换为固定版本 npx 命令或本地候选的绝对入口。无需全局 CLI，不添加每个 Skill 的转发脚本。Skill 不拼 curl，不读取密钥，不规定固定候选或游戏风格。
+
+## 作者与维护者的接入步骤
+
+1. 作者交付上述目录，并说明外部服务、网络前提、凭证环境变量、业务命令、返回结构和写入位置。没有外部服务的扩展不增加认证步骤。
+2. 维护者把目录放入主仓 `extensions/<id>`，审核所有权、依赖和安全边界；不要在主 `src/cli/dispatch.ts` 添加领域分支。
+3. 在主仓执行以下检查并打候选包。源码单测不能替代已安装包验证。
+
+```bash
+bun run typecheck
+bun test test/*.test.ts
+npm pack --pack-destination /absolute/path/to/artifacts
+bun run release:check -- /absolute/path/to/artifacts/forgeax-game-<版本>.tgz
+```
+
+4. 安装候选到独立 consumer，创建空项目，在项目目录使用该候选的绝对 CLI。下列路径为示例，须替换；`install --ide codex --local` 会更新本机 Codex 注册，测试前应明确这是预期操作。
+
+```bash
+npm install --prefix /absolute/path/to/consumer /absolute/path/to/artifacts/forgeax-game-<版本>.tgz
+mkdir /absolute/path/to/new-game
+cd /absolute/path/to/new-game
+node /absolute/path/to/consumer/node_modules/@forgeax/game/dist/main.js install --ide codex --local
+node /absolute/path/to/consumer/node_modules/@forgeax/game/dist/main.js init
+node /absolute/path/to/consumer/node_modules/@forgeax/game/dist/main.js example enable --ide codex --local --json
+node /absolute/path/to/consumer/node_modules/@forgeax/game/dist/main.js example query --json
+node /absolute/path/to/consumer/node_modules/@forgeax/game/dist/main.js example disable --json
+```
+
+`query` 是业务示例，作者须提供对应实现。发布到 npm 前不要让使用者执行指向未发布版本的 npx 命令。Skill 会写入当前候选的绝对 CLI；不要移动或删除该 consumer。
+
+5. 验证停用后的调用失败、重新启用及主插件卸载。涉及远端服务必须补真实业务证据；维护者 review 后才发布主包。
+
+## 发布后的用户操作
+
+下列 `<已发布版本>` 必须替换为实际已发布版本，不能直接照抄占位符。用户不必全局安装 `forgeax-game`。
+
+```bash
+npx -y @forgeax/game@<已发布版本> install --ide codex
+# 进入一个空白项目目录
+npx -y @forgeax/game@<已发布版本> init
+npx -y @forgeax/game@<已发布版本> example enable --ide codex
+# 新开 Agent 会话，让模型按项目 Skill 使用能力
+```
+
+停用某项能力用 `... example disable`；卸载主插件用 `... uninstall`，需要清理登记项目时加 `--all-projects`。部分 Agent 需要新会话或重启才能更新 Skill/MCP 列表。Asset3D 的服务参数和认证见 [资产库使用说明](asset3d.md)。
+
+## 清理和安全边界
+
+- 安装器维护 `.forgeax/extensions/<id>/install.json` 中的路径和摘要；扩展不自行挂载或删除 Skill。
+- 停用时，修改过的受管 Skill 移入 `.forgeax/extension-backups/`，退出 Agent 发现目录。其他用户文件保留。
+- 已导入资产和游戏成果保留。项目外用户提供的共享凭证保留，卸载不销毁其他项目仍在使用的 Key。
+- 凭证仅从专属环境变量或私有文件读取，不写 Skill、命令参数、日志、config.json 或包产物。扩展有责任验证认证并在失败时终止。
+- 网络操作限时限量；下载解压检查来源、路径和体积。Pack 源码交给 Engine 构建会执行代码，只接入受信服务。
+- 只支持可信 Node CLI 目录；不引入市场、任意运行时、常驻服务或扩展依赖管理。
+- 同一项目的扩展操作串行互斥；遇到 `extension_busy` 先确认是否仍有操作运行。进程异常终止可能留下锁，不把盲删锁写进 Skill 的自动恢复流程。
+
+## 接入验收
+
+- [ ] 新增目录，不修改主源码，打包后能启用和调用。
+- [ ] check 失败不留下可发现 Skill 或启用记录。
+- [ ] 重复 enable/disable 可执行；自定义文件不被覆盖或误删。
+- [ ] disable 后 Skill 不被发现，业务操作报未启用。
+- [ ] 主插件卸载级联回收，保留用户资产；不可访问项目明确报错。
+- [ ] 真实业务路径通过；搜索、导入、可玩 Preview 分别记录，不互相替代。
+- [ ] 发布包不含凭证、开发者路径、旧 Provider、维护脚本。
+
+参考目录：[Asset3D](../extensions/asset3d/)；统一安装器：[manager.ts](../src/extensions/manager.ts)。
+
+## 源码 review 索引
+
+| 想看什么 | 文件 |
+|:--|:--|
+| 作者交付清单 | [extensions/asset3d/extension.json](../extensions/asset3d/extension.json) |
+| 模型实际读取的指令 | [资产 Skill](../extensions/asset3d/skills/art-3d-asset-library/SKILL.md) |
+| check/run 业务入口 | [extensions/asset3d/cli.ts](../extensions/asset3d/cli.ts) |
+| HTTP 搜索、下载导入 | [aw-access.ts](../extensions/asset3d/src/aw-access.ts)、[library.ts](../extensions/asset3d/src/library.ts) |
+| Engine 事务、Pack 身份读回 | [transaction.ts](../extensions/asset3d/src/transaction.ts)、[pack-readback.ts](../extensions/asset3d/src/pack-readback.ts) |
+| 统一生命周期与接口 | [manager.ts](../src/extensions/manager.ts)、[contract.ts](../src/extensions/contract.ts) |
+| 命令分发与主插件级联卸载 | [dispatch.ts](../src/cli/dispatch.ts) |
+| 自动发现和打包扩展 | [build.mjs](../build.mjs) |
+| 生命周期测试 | [extensions.test.ts](../test/extensions.test.ts)、[真实已安装包验收脚本](../scripts/accept-extension-lifecycle.mjs) |
+
+Asset3D 是复杂业务示例，不要求其他作者照搬其事务、下载解压或文件数量。最小扩展只需清单、一个 Skill 和一个 check/run 模块。

package/package.json

@@ -1,7 +1,7 @@
 {
   "packageManager": "bun@1.4.0",
   "name": "@forgeax/game",
-  "version": "0.3.6",
+  "version": "0.3.8",
   "private": false,
   "type": "module",
   "description": "@forgeax/game — an MCP/CLI connector for exact released ForgeaX Engine games and Engine-owned Preview.",
@@ -21,20 +21,13 @@
     "dist",
     "assets",
     "docs/asset3d.md",
-    "docs/release-0.3.0.md",
-    "docs/release-0.3.1.md",
-    "docs/release-0.3.2.md",
-    "docs/release-0.3.3.md",
-    "docs/release-0.3.4.md",
-    "docs/release-0.3.5.md",
+    "docs/plugin-integration-standard.md",
     "README.md"
   ],
   "scripts": {
     "build": "bun build.mjs",
     "release:check": "bun scripts/check-package-artifact.ts",
     "acceptance": "bun scripts/accept-packed-consumer.ts",
-    "acceptance:asset3d": "bun scripts/accept-asset3d-packed-consumer.ts",
-    "verify:asset3d-linux": "bun scripts/verify-linux-asset3d-provider.ts",
     "release:publish": "bun scripts/publish-package.ts",
     "prepack": "bun build.mjs",
     "typecheck": "tsc --noEmit",
@@ -56,6 +49,7 @@
     "pnpm": "11.7.0"
   },
   "devDependencies": {
+    "fflate": "0.8.2",
     "@types/bun": "^1.2.0",
     "typescript": "^5.9.2"
   },

package/assets/asset3d/adapter/SKILL.md

@@ -1,56 +0,0 @@
----
-name: art-3d-asset-library
-description: Search and import reusable EA/AW assets, including native Pack sources, through the installed ForgeaX game plugin. Use when making games with existing library assets.
----
-
-# Asset library: Game Plugin adapter
-
-This entry is owned by `@forgeax/game` and matches its pinned Provider. The original
-`@vibegame/art-3d-asset-library@2.0.0` documents remain under `legacy/` for provenance;
-their GLB-only transport and asset-add-only instructions are not this version's contract.
-
-## Search and import
-
-1. Check the project has Asset3D enabled and the current session exposes
-   `asset3d-search/list_asset_candidates` and `search_asset`. Missing tools are a configuration blocker, not
-   an empty library. Do not substitute generated geometry or handwritten HTTP.
-2. Use the same installed `forgeax-game` CLI as the project's `forgeax` MCP server.
-   For a local candidate, use its installed absolute CLI path, not npm's older release.
-   `pnpm exec` can resolve a global CLI when no project dependency exists; verify
-   that executable matches the MCP launcher before starting a transaction.
-   Call `list_asset_candidates` with English queries. Choose a suitable returned
-   `assetId` using its name and format; do not invent an ID or silently take the
-   first candidate. If none fits, refine the query or report no suitable result.
-   Run `forgeax-game asset3d begin --query "<same English query>" --json`.
-3. Call `search_asset` with `queries: [{content: "<same English query>", assetId: "<selected ID>"}]`, returned `execution`, and
-   `output_format: "asset"` to preserve native `.pack.ts` / `.pack.json` when returned.
-   `asset` is the request enum, not `pack.json`. Explicit `glb` requests retain the
-   GLB conversion route. The tool schema must advertise `asset`; otherwise report
-   a Provider version mismatch. Never supply an output directory. Explicit selection
-   uses the calling Agent's judgment and does not need a separate LLM service.
-4. Run `forgeax-game asset3d commit --execution <execution> --json`.
-   The MCP bridge already stores the checked receipt. Inspect per-item failures,
-   `deliveredFormat` in the search result, and the actual returned Engine identities.
-   A successful GLB result is not evidence of a Pack result. If Pack is required but
-   none is returned, report that mismatch rather than renaming or converting source.
-
-## Use the returned assets
-
-- Pack: commit uses the exact Engine build and verified build catalog; use its
-  returned scene/mesh GUIDs. Do not run `asset add` on native Pack source or infer
-  failure solely from a source-only `asset list/inspect` result.
-- GLB: commit uses Engine asset add and catalog readback.
-- Keep the full declared source/helper/texture closure, material parameters and
-  stable identities. Runtime loads cooked assets by GUID. Do not execute downloaded
-  helpers directly. Executable Pack build requires a trusted source; Engine is not
-  itself a security sandbox.
-- Integrate the selected asset into the requested game's normal scene/plugin path,
-  using the installed Engine skills. Choose gameplay, camera and composition to suit
-  the user rather than following a fixed sample game.
-- Call `forgeax_run_current_game`, then verify visible assets and requested input in
-  its verified Preview URL. Search, import, build, and visible gameplay are separate
-  results. Preserve failures, attribution/license gaps and unverified stages.
-
-Asset3D is opt-in. Configure EA using `forgeax-game asset3d enable --library ea
---ide codex` (choose the requested host). Missing credentials require user setup;
-do not read or expose keys in prompts. Use doctor for diagnosis, not proof of search.

package/assets/asset3d/schemas/receipt-1.0.0.json

@@ -1,29 +0,0 @@
-{
-  "$schema": "https://json-schema.org/draft/2020-12/schema",
-  "$id": "forgeax.asset3d-search-receipt/1.0.0",
-  "title": "ForgeaX Asset3D Search Receipt",
-  "type": "object",
-  "additionalProperties": false,
-  "required": [
-    "schemaVersion",
-    "provider",
-    "providerCommit",
-    "originSetDigest"
-  ],
-  "properties": {
-    "schemaVersion": {
-      "const": "forgeax.asset3d-search-receipt/1.0.0"
-    },
-    "provider": {
-      "const": "ea-3d"
-    },
-    "providerCommit": {
-      "type": "string",
-      "pattern": "^[0-9a-f]{40}$"
-    },
-    "originSetDigest": {
-      "type": "string",
-      "pattern": "^[0-9a-f]{64}$"
-    }
-  }
-}