@tgeniepress/create-plugin

TGeniePress 官方插件工程生成器。仓库目录名是 plugin-create，正式 npm 包名是 @tgeniepress/create-plugin。

生成的后端运行在独立进程或容器中，前端作为宿主同源模块加载，工程符合 Plugin Manifest V1、Plugin SDK V1 和 RPC Protocol V2。

快速开始

pnpm create @tgeniepress/plugin my-plugin
pnpm dlx @tgeniepress/create-plugin my-plugin
npx @tgeniepress/create-plugin@latest my-plugin

直接运行且不提供插件 ID 时，会启动类似 Vite 的交互式向导：

pnpm dlx @tgeniepress/create-plugin

向导会依次选择或填写目标目录、插件 ID、显示名称、发布者、描述、TypeScript/JavaScript、完整/仅后端/仅前端、process/container、包管理器、安装依赖和初始化 Git。目标已存在时必须再次确认，确认后才会原子替换。

交互式默认值为 TypeScript、前后端完整插件、process 和 pnpm。传入插件 ID 时保持非交互模式，适合 CI；使用 --interactive 可强制进入向导，使用 --yes 可无提示接受全部推荐默认值。

pnpm dlx @tgeniepress/create-plugin my-plugin \
  --name "My Plugin" \
  --publisher "acme" \
  --runtime container \
  --package-manager pnpm \
  --install \
  --git

CLI 参数

| 参数 | 作用 | | --- | --- | | <plugin-id> | 必填，小写稳定标识符，最长 64 个字符 | | --name <name> | 插件显示名称 | | --description <text> | manifest 与 package 描述 | | --publisher <name> | 发布者，默认 local | | --directory, -d <path> | 当前目录下的目标相对路径 | | --runtime <mode> | process 或 container | | --package-manager <name> | pnpm、npm、yarn 或 bun | | --language <ts\|js> | TypeScript 或 JavaScript，默认 TypeScript | | --backend-only | 仅生成独立后端 | | --frontend-only | 仅生成同源前端，不能指定 runtime | | --install / --no-install | 是否安装依赖，默认不安装 | | --git / --no-git | 是否初始化 Git，默认不初始化 | | --force | 原子替换现有目标，失败时恢复旧目录 | | --dry-run | 只校验并列出文件，不写磁盘 | | --json | 输出机器可读 JSON | | --interactive / --no-interactive | 强制启用或禁用向导 | | --yes, -y | 无提示采用推荐默认值 |

未知参数、缺少参数值、冲突参数和目录逃逸都会返回非零退出码及稳定错误码。

编程 API

import { createPluginScaffold } from "@tgeniepress/create-plugin";

const result = await createPluginScaffold({
    pluginId: "acme-search",
    pluginName: "Acme Search",
    publisher: "acme",
    runtime: "process",
    language: "ts",
    packageManager: "pnpm",
});

console.log(result.pluginRoot, result.createdFiles);

核心方法

• createPluginScaffold(options)：原子生成工程，可取消、dry-run、安装依赖和初始化 Git。
• resolveScaffoldOptions(options)：解析默认值并校验全部组合约束。
• getTemplates(id, name, options)：返回确定性排序的文件内容，不写磁盘。
• normalizePluginId(raw) / validatePluginId(raw)：规范化和严格校验插件 ID。
• getPluginRoot(...) / pluginScaffoldExists(...)：安全解析和检查目标。
• getInstallCommand(manager) / installPluginDependencies(...)：包管理器支持。
• initializeGitRepository(...)：初始化 Git。
• parseCreatePluginArgs(argv)：从 @tgeniepress/create-plugin/cli-args 导入，用于自定义 CLI。

所有公开 API 都提供 TypeScript 类型声明。失败时抛出 PluginScaffoldError，包含稳定的 code 和只读 details。

生成内容

• 合法的 plugin.json。
• server/index.ts|js 中的 defineServerPlugin 独立后端源码和健康检查路由。
• src/index.ts|js 中的 defineClientPlugin 同源前端源码与样式。
• 基于 @tgeniepress/plugin-testing 的隔离测试。
• ESLint、TypeScript、Vitest、Vite 配置。
• 开发、验证、检查、测试、构建和打包脚本。
• EditorConfig、GitIgnore、npm 配置、环境变量样例、MIT License 和工程 README。

开发工程目录

my-plugin/
├─ src/
│  ├─ index.ts
│  └─ style.css
├─ server/
│  └─ index.ts
├─ shared/
├─ resources/
├─ tests/
├─ scripts/
├─ plugin.json
├─ package.json
├─ vite.config.mjs
├─ tsconfig.json
├─ eslint.config.js
└─ vitest.config.js

TypeScript 后端的本地可执行入口生成到 .tgeniepress/runtime/server/index.js。该目录和 build/ 都是生成产物，已加入 .gitignore。前端修改 src/，后端修改 server/，共享协议和静态资源分别放入 shared/、resources/。

可安装包目录

执行 pnpm build 后，build/ 严格采用宿主安装结构：

build/
├─ plugin.json
├─ package.json
├─ server/index.js
├─ dist/
│  ├─ index.js
│  ├─ style.css
│  └─ assets/
├─ README.md
└─ LICENSE

发布 Manifest 会自动把后端入口改写为 server/index.js，前端入口改写为 dist/index.js。开发 Manifest 则指向 src/ 和 .tgeniepress/runtime/，两种用途不会混放。

pnpm build 只生成标准生产目录；pnpm pack 会继续校验该目录，并通过 tgp pack 生成 artifacts/<plugin-id>-v<version>.zip。ZIP 根目录直接包含 plugin.json，不再生成 npm .tgz。

容器模式使用宿主统一维护的 @tgeniepress/plugin-runtime-node 镜像，因此不会复制宿主源码，也不生成插件私有运行时镜像。

安全保证

• 目标必须位于 baseDir 内，模板文件必须位于目标目录内。
• 默认不覆盖、不安装依赖、不执行 Git。
• force 使用临时目录和备份切换，不会先删除原工程。
• 模板不导入宿主源码、数据库客户端或宿主内部路径。
• 生成后使用 tgp verify . 检查 manifest、入口和 SDK 边界。