Metaform 组件安装 CLI

@james_sww/metaform-asset-distribution 在已有应用工程内安装组件源码、依赖和资料，提供安装计划、来源摘要、基线、冲突检查及恢复。应用初始化、外壳和页面骨架由平台侧 Code Base 提供。本包不包含应用模板，不提供 init、prepare 或页面生成。

采用流程

1. 通过组件 MCP 检索关注项对应的组件，核对真实契约、源码、版本和适用条件。
2. 获取所选组件的安装交付，保存到已有工程。
3. 执行 plan add 检查变更、依赖和冲突，再执行 add。
4. 在应用内完成对象绑定和区域挂载，运行当前工程的验证。

可用命令为 search、inspect、export、plan add、add、official add、diff、doctor 和 reconcile。版本以安装的 npm 包和工程内工具实际回执为准。

metaform-assets inspect common.crud-query-detail --registry /path/to/selected-release.json --json
metaform-assets plan add common.crud-query-detail --registry /path/to/selected-release.json --json
metaform-assets add common.crud-query-detail --registry /path/to/selected-release.json
metaform-assets reconcile

official add 在暂存目录执行固定版本官方组件工具，核对冲突后合入已有工程，不接受覆盖人工修改。--no-install 只落源码和依赖声明，随后仍需由宿主安装依赖。

沙箱固定工具与 MCP 交付

build:project 将同一套安装逻辑打包为独立 Node ESM 工具及版本、摘要、许可证。平台可将其交付到工程内的 tooling/metaform-assets.mjs。工具不下载 npm CLI，不包含完整 Registry，也不初始化应用；固定副本不会随维护源码自动更新。

MCP 的 resolve_assets({ ids: ["common.crud-query-detail"], includeInstallation: true }) 返回 installation.status=available 时，由 Agent 使用工作区工具将响应写到 .metaform-install/resolve-assets.json。CLI 接受整个 MCP 响应、标准 envelope 或其中的选定发行。仅 reference 或未提供安装数据时明确拒绝，不伪造安装基线。

node tooling/metaform-assets.mjs --version
node tooling/metaform-assets.mjs plan add common.crud-query-detail --registry .metaform-install/resolve-assets.json --expect-digest <installation.expectedDigest> --json > .metaform-install/adoption-plan.json
node tooling/metaform-assets.mjs add --plan .metaform-install/adoption-plan.json
node tooling/metaform-assets.mjs reconcile

项目工具必须显式提供 --registry，不回退完整 Registry。维护端可以 export <id#variant> 导出所选源码闭包。交付保留 upstreamReleaseDigest 和来源信息。metadata.installation.releaseDigest 对应完整目录发行，installation.expectedDigest 对应所选闭包并等于 installation.release.digest；安装只使用后者作为 --expect-digest。目录的 resolveRequest 指向安装交付，必须先保存交付文件并传 --registry。摘要是完整性检查，不是上游签名。

发行文件的 sha256 校验实际写入字节；有改写时，sourceSha256 追溯改写前的维护源字节。两者可以不同，不应拿上游源码摘要校验改写后的导入路径。业务 reference 仅用于读取与适配，不作为已绑定业务能力直接安装。

MCP 只读，不执行沙箱命令、不写工程、不返回服务凭据。只有 Agent 的工作区工具负责写入和执行。build:installation 生成 MCP 读取安装发行所需的固定运行时，不携带应用模板。

来源和修改保护

组件的基础 UI、工具函数和主题来自 vendor/design-system 固定快照，维护源为平台设计系统。导出时核对来源锁内的字节摘要；UI 与工具函数安装到 src/components/vendor/metaform/，组件导入随之改写，宿主已有的 src/components/ui/ 和 src/lib/utils.ts 保持原样。不再从应用模板替换原语，也不要求为组件安装修改 cn 版本。

已有同路径文件与所选组件内容不同会返回冲突。CLI 不覆盖它们，不猜测模板版本，也不自动更新外壳、路由或应用入口。同版本重复安装保留应用人工修改；升级、路径迁移和非托管文件冲突必须审阅。

若升级只涉及已验证基线上的组件资料，检查计划与 planDigest 后，可使用相同组件、发行和工程执行 add ... --accept-documentation-plan <planDigest>。该选项不允许覆盖其他冲突，也不绕过摘要、路径或基线保护。

工程内 .metaform-install 保存事务、锁及恢复备份。活动事务先执行 doctor --recover，不可保存半安装结果。安装后的组件源码、assets.lock.json 和 .metaform/asset-baselines/<sha256> 由平台一起保存；缓存和事务备份不属于应用源码。

维护验证

pnpm test
pnpm typecheck
pnpm build
pnpm prepare:release
pnpm build:project
pnpm build:installation
pnpm test:project
pnpm test:standalone

test:standalone 将已有构建产物打包到仓库外，解包后使用独立工具对最小已有工程执行组件安装、重复安装和修改保护验收；可用 METAFORM_ACCEPTANCE_PROJECT 指定平台已初始化的真实工程。测试 fixture 不属于可分发模板。验收产物写到 METAFORM_ACCEPTANCE_DIR 或临时目录。普通验证不发布 npm、不更新平台模板、不部署 MCP。

沙箱采用后续 CLI 发行

项目运行件元数据提供 autoUpdate.protocol=metaform-project-cli-v1、支持的 Registry 格式和最低 Node 版本。接入该协议的平台在获授权的源码任务内，经固定 npm 网关核验精确版本包的 SHA-512，再在原生执行租约内检查并更新 CLI 文件；CLI 不自行下载或跟随 latest。同一轮固定版本与摘要，后续新任务才重新发现。

工具文件仍为 tooling/metaform-assets.mjs、.metaform/asset-cli.json 和 LICENSES/asset-cli.md，采用来源保存在 .metaform/asset-cli-adoption.json，一起走现有源码接纳和 Git 保存。来源回执不能代替官方旧包或模板原始基线验证。人工改写、误删、混装及摘要冲突不覆盖；单独更新工具不修改已安装组件、assets.lock.json、资产基线或整体 Code Base 身份。

Registry 读取不可用或新工具不兼容时明确保留状态，不声称已采用最新发行，也不升级 Node/pnpm/DSH。组件资料仍来自当前 MCP 的独立固定发行；CLI、组件、模板和服务不要求版本号一致。

MCP envelope 的最低 CLI 要求由执行入口检查；需要新兼容要求的发行正文使用 schema 2 和 metaform-cli-release-v2，计划也使用 schema 2 并携带 minimumCliVersion，防止历史解析器忽略要求。schema 1 的历史发行及无新要求计划继续支持，资产锁保持 schema 1。程序调用 planAdd/applyPlan 遇到版本要求时需提供实际 cliVersion；readRegistryInput 仅解析资料，不证明可执行或已安装。

维护源码支持此协议不代表线上已启用。首次启用仍需发布兼容 CLI 新版本和平台接入代码；后续协议兼容的 CLI 新发行不需要反复发布平台或升级模板。当前工作区构建的产物与已发布 npm 同版本历史内容必须按摘要区分。

受管沙箱更新器进程是否结束不明时，平台保留持久隔离，普通源码恢复不能解除；需要用户显式停止并重新准备沙箱，已保存源码及 Git 仍保留。首次启用应先完成平台接入版本滚动发布，再发布带自动采用标识的 CLI，避免旧平台实例处理新协议状态。