插件打包指南

CLI、TUI 和桌面 GUI 使用同一个 App Server 插件目录、安装缓存、配置和组件快照。插件提供 Skills、MCP、Apps 或 Hooks 声明，运行和权限由对应的共享后端处理。

标准包

最小目录：

example-plugin/
  plugin.json
  skills/
    release-check/
      SKILL.md

根 plugin.json 声明 Agent Plugins 标准 schema：

{
  "$schema": "https://agent-plugins.org/schemas/1.0.0/plugin.schema.json",
  "name": "example-plugin",
  "version": "1.0.0",
  "description": "Check a release before publishing.",
  "author": { "name": "Example" }
}

标准包从 skills/ 的直接子目录读取 SKILL.md，从根 mcp.json 读取 MCP 配置。 Codex 扩展元数据放在 extensions.com.openai；包内资源必须使用受约束的相对路径。 标准包省略版本时使用 1.0.0。

原生生态格式

加载器也识别 Codex 支持的原生 manifest，依次为 .codex-plugin/plugin.json、.claude-plugin/plugin.json、.cursor-plugin/plugin.json。 这类包按 manifest 声明的组件路径加载，省略版本时使用 local。

声明标准 schema 的根 manifest 优先；如果标准版本不受支持，加载失败。 不能靠另放一份原生 manifest 绕过失败。无关根 JSON 不抢占合法原生 manifest。

身份与生命周期

插件身份为 name@marketplace。同名但不同市场的插件分别安装、启停和卸载； 启停通过共享配置 plugins.<name@marketplace>.enabled 完成。 插件 Skill 的可见名称为 plugin:skill，内部仍保留完整包身份。

新包必须经过同一个 App Server owner 安装并读取，不能恢复旧安装 records、 独立 worker、iframe SDK、私有模型 token 或旧 Connector 发布脚本。 LimeCore 上传扫描与客户端使用相同的 manifest 选择及有效身份规则。

开发验证

包解析、身份隔离、安装失败回滚和配置原子写入已有定向回归。 完整的市场发布、下载、安装、授权和真实 Turn 闭环仍需逐项验证。 CLI、真实 PTY 和 Electron 分别验收，局部测试通过不能代替整个产品流程完成。

仓库内的目标合同位于 internal/roadmap/plugin/codex-contract.md， 执行状态与证据位于 internal/exec-plans/codex-plugin-reconstruction.md。