# @galcraft/plugins 中文文档

规范地址：https://npmcn.com/package/%40galcraft/plugins/

版本：0\.1\.0
npm 元数据更新时间：2026-11-01T04:24:33.098Z
中文译文更新时间：2026-11-01T05:16:50.334Z
软件包许可：MPL-2\.0

本文由上游 README 机器翻译，可能存在偏差，请结合原文核对 API、命令与配置。版权与许可归原作者所有。

原始 npm 页面：https://www.npmjs.com/package/%40galcraft/plugins
原文对照：https://npmcn.com/package/%40galcraft/plugins/?lang=original
项目主页：https://github.com/TianyuEric/GalCraft#readme
源码仓库：https://github.com/TianyuEric/GalCraft

## 关键信息（来自 npm 元数据）

- 包体积（解压后）：428 kB，93 个文件
- 模块格式：ES Module
- TypeScript 类型：包内自带
- Node.js 要求：\>=22\.12\.0
- 运行依赖：9 个
- 首次发布：2026-11-01T04:23:16.318Z
- 最新版本发布：2026-11-01T04:24:32.966Z
- 已发布版本数：2（近 12 个月 2 个）

## 中文简介

这个 `galcraft-plugin` development CLI支持Node.js 22.12.0及以上版本。为独立的插件项目使用最新的Node.js 24 LTS补丁；源代码开发和CI使用Node.js 24.21.0和pnpm 12.3.4。生成的节点服务和本机条目目标

## 安装

```sh
npm install @galcraft/plugins
```

也可以使用：`pnpm add @galcraft/plugins`、`yarn add @galcraft/plugins`、`bun add @galcraft/plugins`

## README

# GalCraft插件SDK

这个 `galcraft-plugin` development CLI支持Node.js 22.12.0及以上版本。为独立的插件项目使用最新的Node.js 24 LTS补丁；源代码开发和CI使用Node.js 24.21.0和pnpm 12.3.4。生成的Node服务和本地条目目标Node.js 22.12；浏览器条目保留其浏览器目标。契约和可选的DSL解析器导出也为浏览器消费者提供服务，并且不需要在这些消费者中使用Node运行时。插件作者从npm安装准确的SDK版本： `npm install @galcraft/contracts@0.1.0 @galcraft/plugins@0.1.0`． 解析器使用者还安装 `@galcraft/dsl@0.1.0`.

SDK导出插件契约 `@galcraft/plugins/contracts`，主机共享的React实例在 `@galcraft/plugins/react`，主机共享的Pixi名称空间在 `@galcraft/plugins/pixi`，以及创作工具 `@galcraft/plugins/development`． 插件使用这些公共导出；主机程序集使用 `@galcraft/plugins/host` 和 `@galcraft/plugins/registry`.

`galcraft-plugin create <directory> <pluginId> <template>` 创建一个独立的TypeScript项目。模板是 `author-tool`， `game-system`， `resource-stage`， `service-provider`, `complete`． 安装合同和插件 `npm install @galcraft/contracts@0.1.0 @galcraft/plugins@0.1.0`，然后跑 `npm run typecheck`， `npm run build`， `npm run check`, `npm run pack`． 包目录支持Studio开发加载； `.galplugin` 文件支持普通安装程序。

清单v1仍然受支持。Manifest v2需要一个无dom的定义条目，并支持单独的编辑器、Node服务和运行时条目以及环境依赖项。主机与声明的引擎范围一起检查SDK major 0。当前本地开发的引擎、插件和SDK包版本保持在0.1.0；示例插件声明 `^0.1.0`． 普通安装可以刷新相同的包版本，活动租约在可替换包目录之外保留完整的图，直到发布。精确的项目锁对包版本保持权威，包括版本缺失诊断。插件状态对每个插件使用一个系统贡献。

包版本不能替代清单版本， `contractVersion: 1`或独立的类型、操作和状态数据版本。现有的文档、资产索引、快照、任务、候选、草稿和配方信封保留在schemaVersion 1中。旧的记录保留其原始的读映射；打开它们不会写入扩展字段或提交生成请求。

清单 `name` 和 `description` 包含作者的原始文本。可选 `localizations` 将区域设置键映射为complete `{ name, description }` 比如翻译 `localizations.en` 和 `localizations.ja`． Studio使用当前界面区域设置解析显示文本，然后是其语言，然后是源文本。 `pluginDisplayMetadata(manifest, locale)` 通过以下方式公开此规则 `@galcraft/plugins/contracts`． 显示文本不会更改包id、版本或项目锁。

SDK发行版包括契约和插件包构件，以及可选的DSL解析器构件，用于编写读取《GalCraft》语句的插件 `@galcraft/dsl/parser`． 分发命令构建并打包这些构件；普通插件安装契约/插件，而解析器使用者也安装匹配的DSL工件。构建捆绑普通依赖项，保留主机共享的React条目，并为每个执行环境验证ESM图。在测量清单文件大小之前，构建将从每个环境中生成的JavaScript语法（包括本地条目）中删除尾随空格和制表符。 通过复制的文字内容和文件 `include` 保留其原始字节。服务可以使用 `node:` 进口。定义项包含同步数据回调，并且独立于UI和服务执行。

参见存储库开发人员指南 `docs/reference/plugins.md` 对于生命周期、文档映射、服务和接受边界。GalCraft SDK代码采用了mpls -2.0。分布式SDK包带有许可证和源代码可用性通知 `dist/licenses/project/`． 开发构建器收集插件项目自己的许可证，复制，通知和 `licenses/` 文件加上捆绑的依赖项许可证报告；它保留了作者声明的许可。新项目从“未授权”开始，直到其作者选择条款。读 `LICENSING.md` 在项目材料范围的源代码树中。

资产UI扩展使用 `AssetEditorContribution`， `AssetPreviewContribution`, `AssetThumbnailContribution` 从合同出口。类型描述符关联 `editorKey`， `previewKey`, `thumbnailKey` 具有匹配的清单声明和编辑器贡献。编辑器目标区分资产元数据、命令字段和阶段实例；只通过上下文回调提交。上下文还公开所选资源/版本和只读标志。

预览上下文标识一个已索引的资产或未采用的候选资产，携带其确切的变体/typeData和只读资源集合，并提供 `signal` 加上 `onDispose`． 挂载可能返回同步清理或清理承诺。将等待操作之前获得的资源注册为 `onDispose`;检查 `signal` 在附加异步结果之前。Studio隔离每个挂载，并在切换、停用、重新加载和关闭时释放旧范围。外部 `custom-asset` 示例演示了真实的顶点/颜色编辑，静态预览，缩略图，正式引用和精确的标量 `filterFields` 声明。

类型化的生产操作在无dom的定义中声明它们的字段和媒体端口。主机为每个端口的类型、MIME、所需规则和多个规则提供通用控制，包括选择、替换和单独删除，同时保留其他端口。一个公共 `fieldEditor` 是可选的;它的提交回调更新个人M10草案，检查其修订并使先前的发送计划无效。它不提交M02工作编辑。看到 `plugins/development-examples/video-generation/README.md` 对于本地视频协议的示例及其验证限制。

## 常见问题

### @galcraft/plugins 是什么？

这个 galcraft-plugin development CLI支持Node\.js 22\.12\.0及以上版本。为独立的插件项目使用最新的Node\.js 24 LTS补丁；源代码开发和CI使用Node\.js 24\.21\.0和pnpm 12\.3\.4。生成的节点服务和本机条目目标

### 如何安装 @galcraft/plugins？

在项目目录运行 npm install @galcraft/plugins，或使用 pnpm add / yarn add / bun add。它还提供命令行工具 galcraft-plugin，可以用 npx galcraft-plugin 直接运行。

### @galcraft/plugins 支持 TypeScript 吗？

支持。包内自带 TypeScript 类型声明（package\.json 声明了 types 入口），安装后即可获得类型提示，无需再安装 @types 包。

### @galcraft/plugins 支持 ESM 还是 CommonJS？

以 ES Module 形式发布，推荐使用 import 引入。在 CommonJS 项目中，Node\.js 20\.19\+ / 22\.12\+ 可以直接 require\(\) 不含顶层 await 的 ES Module，更早的版本需要改用动态 import\(\)。

### @galcraft/plugins 需要什么版本的 Node\.js？

package\.json 的 engines 字段要求 Node\.js \>=22\.12\.0。版本不符时 npm 默认只给出警告，开启 engine-strict 后会拒绝安装。

### @galcraft/plugins 可以商用吗？

@galcraft/plugins 使用 MPL-2\.0 许可。弱 Copyleft：可以商用，也可以和闭源代码一起使用；但如果分发时修改了 MPL 授权的文件，这些文件的修改需以 MPL 开源。以上为概括，不构成法律意见，请以许可原文为准。

### @galcraft/plugins 还在维护吗？

最新版本 0\.1\.0 发布于 2026/11/01（2 天前）；至今共发布 2 个版本，其中过去 12 个月发布了 2 个；首次发布于 2026/11/01。发布频率只是参考信号：功能稳定的工具可能很少需要更新，建议结合源码仓库的 issue 和提交记录判断。