跳到主要内容

插件脚手架与工程集成

目录​

脚手架解决什么问题​

手写插件目录容易漏掉：manifest 字段、marketplace 条目、权限占位、Skills/Hooks 样例。脚手架用于 一次性生成可编辑骨架，减少「能跑但缺元数据」的低级错误。

不同团队使用的脚本路径不同；若你使用 Codex 生态常见脚手架，通常满足：

  • 插件名规范化（小写、连字符、长度上限）。
  • 生成 .codex-plugin/plugin.json 完整占位。
  • 可选生成 skills/、hooks/、scripts/、.mcp.json 等目录。

典型目录结构（概念）​

<plugin-name>/
  .codex-plugin/
    plugin.json
  skills/
    <skill-id>/SKILL.md
  hooks/              # 可选
  scripts/            # 可选
  assets/             # 可选

实际以你运行的脚手架与宿主规范为准。

创建插件的常见步骤​

  1. 选定安装位置：仓库内 plugins/<name> 或用户目录下 ~/plugins/<name>（依团队规范）。
  2. 运行脚手架生成目录与 plugin.json。
  3. 填写 manifest：替换 [TODO]，补全 description、入口与接口段。
  4. （可选）写入 marketplace：让插件出现在 UI 列表中；注意 policy.installation / policy.authentication 等策略字段。
  5. 内置或链接 Skills：把团队已验证的 SKILL.md 放入 skills/。
  6. 本地加载验证：在宿主中启用插件，跑一条最小路径。

marketplace 条目形状（示例）​

以下为教学示例，字段以你环境生成的 marketplace.json 为准：

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

与 Skill 仓库协作​

推荐做法：

  • Skill 作为独立文档仓库或 monorepo 子目录 维护版本；
  • 发 Plugin 版本时 锁定 Skill 的 Git SHA 或版本号，避免「插件 1.2 引用未发布的 Skill 草稿」。

与 CI/CD 集成​

可对插件目录做：

  • JSON schema 校验（若宿主提供 schema）。
  • Markdown lint 对 SKILL.md。
  • 单元测试：对 scripts/ 内脚本做最小测试。

本地调试与发布检查清单​

项说明
manifest 无 TODO关键字段已填
Skill 可单独执行不依赖未文档化的隐式状态
权限最小化仅申请必要权限
回滚方案旧版本路径或版本号可恢复

延伸阅读​