grahama1970/plugin-creator

插件创建器

快速开始

1. 运行脚手架脚本：

# 插件名称会规范化为小写连字符形式，且长度不能超过64个字符。
# 生成的文件夹和 plugin.json 的名称始终保持一致。
# 从技能根目录（包含此 `SKILL.md` 的目录）运行。
# 默认在 `~/plugins/<plugin-name>` 下创建。
python3 scripts/create_basic_plugin.py <plugin-name>

2. 当请求给出特定元数据时，编辑 <plugin-path>/.codex-plugin/plugin.json。 脚手架以有效的默认值开始，且不得包含 [TODO: ...] 占位符。

3. 当插件应出现在 Codex UI 排序中时，生成或更新个人市场条目：

# 个人市场条目默认位于 `~/.agents/plugins/marketplace.json`。
python3 scripts/create_basic_plugin.py my-plugin --with-marketplace

仅当默认的 personal 市场名称已被占用或安装，且需要填充不同的新市场文件时，才指定 --marketplace-name <name>：

python3 scripts/create_basic_plugin.py my-plugin \
  --with-marketplace \
  --marketplace-name team-local

仅当用户明确要求仓库/团队市场目标时，才使用该目标：

python3 scripts/create_basic_plugin.py my-plugin \
  --path <repo-root>/plugins \
  --marketplace-path <repo-root>/.agents/plugins/marketplace.json \
  --with-marketplace

当用户指定市场路径时，请确保该市场实际已安装，然后再告诉用户从中重新安装。默认的个人市场文件位于 ~/.agents/plugins/marketplace.json，会被隐式发现，但其他市场路径则不会。在 Windows 上，请使用用户配置文件下的等效路径。

4. 根据需要生成/调整可选的配套文件夹：

python3 scripts/create_basic_plugin.py my-plugin \
  --path <parent-plugin-directory> \
  --marketplace-path <marketplace-json-path> \
  --with-skills --with-hooks --with-scripts --with-assets --with-mcp --with-apps --with-marketplace

<parent-plugin-directory> 是将在其中创建插件文件夹 <plugin-name> 的目录（例如 ~/plugins）。

5. 在交付生成的插件之前，运行：

python3 scripts/validate_plugin.py <plugin-path>

对于开发过程中对现有本地插件的更新，请保持脚手架流程不变，并使用参考而非手动编辑市场文件：

python3 scripts/update_plugin_cachebuster.py <plugin-path>

除非用户明确要求特定的覆盖值，否则优先使用默认的缓存破坏辅助工具。有关在迭代现有本地插件时的预期缓存破坏和重新安装流程，请参见 references/installing-and-updating.md。

此技能创建的内容

• 默认的市场支持脚手架使用位于 ~/.agents/plugins/marketplace.json 的个人市场文件，插件通常存储在 ~/plugins/<plugin-name>/ 中。
• 在 /<parent-plugin-directory>/<plugin-name>/ 创建插件根目录。
• 始终创建 /<parent-plugin-directory>/<plugin-name>/.codex-plugin/plugin.json。
• 用验证过的模式形状填充清单，该模式是导入路径所接受的。
• 当设置了 --with-marketplace 时，创建或更新 ~/.agents/plugins/marketplace.json。
  • 如果市场文件尚不存在，则在添加第一个插件条目之前，先填充个人市场根节点。
• <plugin-name> 使用技能创建器的命名规则进行规范化：
  • My Plugin → my-plugin
  • My--Plugin → my-plugin
  • 下划线、空格和标点符号转换为 -
  • 结果为小写连字符分隔，连续的连字符会合并
• 支持可选创建：
  • skills/
  • hooks/
  • scripts/
  • assets/
  • .mcp.json
  • .app.json

市场工作流

• 个人市场创建默认位置为 ~/.agents/plugins/marketplace.json。这里的“个人市场”指的是其文件位于该路径的市场。
• 仓库/团队市场的创建需要同时通过 --path 和 --marketplace-path 明确选择，且仅在用户特别要求时使用。
• --marketplace-name 是一个例外路径。仅当默认的 personal 市场名称已被占用且需要填充不同的新市场文件时使用。
• 不要使用 --marketplace-name 来重命名现有的市场文件。如果文件已存在，其顶级 name 必须已匹配。
• 如果用户指定了不同的市场路径，则将该市场视为需要显式安装（通过 codex plugin marketplace add）。
• 当需要从任何 marketplace.json 文件中获取市场名称时，优先使用 scripts/read_marketplace_name.py。无参数时读取默认的个人市场；有显式路径时也适用于仓库/团队市场。
• 无论位置如何，生成的插件源路径始终保持为 ./plugins/<plugin-name>。
• 市场根节点元数据支持顶级 name 以及可选的 interface.displayName。
• 将 plugins[] 中的插件顺序视为 Codex 中的渲染顺序。除非用户明确要求重新排序列表，否则追加新条目。
• displayName 属于市场 interface 对象内部，而不是单个 plugins[] 条目。
• 每个生成的市场条目必须包含以下所有内容：
  • policy.installation
  • policy.authentication
  • category
• 新条目的默认值：
  • policy.installation: "AVAILABLE"
  • policy.authentication: "ON_INSTALL"
• 仅当用户明确指定其他允许的值时才覆盖默认值。
• 允许的 policy.installation 值：
  • NOT_AVAILABLE
  • AVAILABLE
  • INSTALLED_BY_DEFAULT
• 允许的 policy.authentication 值：
  • ON_INSTALL
  • ON_USE
• 将 policy.products 视为覆盖项。除非用户明确要求产品门控，否则省略它。
• 生成的插件条目形状为：

{
  "name": "plugin-name",
  "source": {
    "source": "local",
    "path": "./plugins/plugin-name"
  },
  "policy": {
    "installation": "AVAILABLE",
    "authentication": "ON_INSTALL"
  },
  "category": "Productivity"
}

• 仅在有意替换同一个插件名称的现有市场条目时使用 --force。

• 如果目标市场文件尚不存在，则创建包含顶级 "name"、包含 "displayName" 的 "interface" 对象以及 plugins 数组的文件，然后添加新条目。

• 对于全新的市场文件，根对象应如下所示：

{
  "name": "personal",
  "interface": {
    "displayName": "Personal"
  },
  "plugins": [
    {
      "name": "plugin-name",
      "source": {
        "source": "local",
        "path": "./plugins/plugin-name"
      },
      "policy": {
        "installation": "AVAILABLE",
        "authentication": "ON_INSTALL"
      },
      "category": "Productivity"
    }
  ]
}

必要行为

• 外层文件夹名称和 plugin.json 中的 "name" 始终是相同的规范化插件名称。
• 不要移除必需的结构；保持 .codex-plugin/plugin.json 的存在。
• 不要在插件清单中留下 [TODO: ...] 占位符。
• 除非实际创建了 apps 和 mcpServers 的配套文件，否则不要将它们包含在 plugin.json 中。
• 省略验证拒绝的不受支持的插件清单字段，包括 hooks。
• 如果在现有插件路径内创建文件，仅在有意覆盖时使用 --force。
• 保留任何现有的市场 interface.displayName。
• 生成市场条目时，始终写入 policy.installation、policy.authentication 和 category，即使它们的值是默认值。
• 仅当用户明确要求该覆盖项时，才添加 policy.products。
• 保持市场 source.path 相对于所选市场根目录的 ./plugins/<plugin-name>。
• 仅当需要创建一个名称不应该是 personal（因为该名称已被占用或安装在别处）的新市场文件时，才使用 --marketplace-name。
• 如果 Codex 需要批准才能写入市场文件，请先请求该批准。如果用户希望自己运行写入操作，则提供确切的脚手架命令，然后继续执行验证或后续插件编辑，而不是让工作流模糊不清。
• 对于开发过程中对现有本地插件的更新，不要手动编辑市场配置或 marketplace.json。请使用 references/installing-and-updating.md 和 scripts/update_plugin_cachebuster.py 中记录的更新流程。
• 不要告诉用户为默认的个人市场流程运行 codex plugin marketplace add。该命令用于显式的非默认市场配置，而不是标准的 ~/.agents/plugins/marketplace.json 路径。
• 如果用户提供了非默认的 --marketplace-path，请确保该市场已安装，然后再给出重新安装说明。当该显式市场尚未配置时，使用 codex plugin marketplace add <path-to-marketplace-root>。
• 当工作流创建或更新了市场支持的插件时，用简短的 Codex 应用交接结束最终的用户面向响应。说 在 Codex 应用中查看此插件： 并将 查看 <规范化的插件名称> 和 分享 <规范化的插件名称> 写为 Markdown 链接，而不是原始 URL 或代码跨度。
• 查看深度链接使用 codex://plugins/<规范化的插件名称>?marketplacePath=<绝对 marketplace.json 路径>。 分享深度链接使用相同的 URL，并附加 &mode=share。
• 将占位符替换为实际规范化的插件名称和脚手架化插件的绝对 marketplace.json 路径。必要时对路径段和查询值进行 URL 编码。
• 不要向这些深度链接添加 pluginName 或 hostId 查询参数。Codex 会在用户点击链接后派生这两者。
• 当没有创建或更新市场条目时，不要输出 查看 <规范化的插件名称> 或 分享 <规范化的插件名称> 链接。

精确规范示例的参考

有关插件清单和市场条目的规范示例 JSON，请使用：

• references/plugin-json-spec.md
• references/installing-and-updating.md 获取更新/重新安装指南，以便在迭代现有本地插件时使用，以及重新安装后的新线程拾取行为

验证

编辑 SKILL.md 后，运行：

python3 ../skill-creator/scripts/quick_validate.py .

在交付生成的插件之前，运行：

python3 scripts/validate_plugin.py <plugin-path>