> ## Documentation Index
> Fetch the complete documentation index at: https://aicoding.cscitech.top/llms.txt
> Use this file to discover all available pages before exploring further.

# 05-Plugins插件

> 掌握 Codex 插件的组成、目录和 manifest，完成插件的打包、安装、权限配置、版本管理、验证与卸载，并学会评估第三方风险。

## 用途

插件（Plugin）是把一组 Codex 扩展能力作为一个可分发、可版本化、可整体管理的单元。它可以把 Skills、MCP server、应用连接器以及可选的 hooks 放进同一个插件目录，供个人、项目或团队重复安装。

本页覆盖完整的工程链路：

* 判断何时应使用插件，而不是单独配置 Skill 或 MCP；
* 组织插件目录，编写 `.codex-plugin/plugin.json`；
* 组合 Skill、MCP 和连接器并控制数据流；
* 从本地目录、Git 市场或插件目录安装；
* 配置权限、版本、验证、升级、禁用和卸载；
* 识别第三方插件、脚本、hooks 和供应链风险。

插件不是更高权限的执行模式。安装插件不会自动批准命令、工具调用或外部账号授权，仍然受项目信任、沙箱、审批和凭据管理规则约束。

> 命令和界面会随 Codex 版本变化。执行前先运行 `codex --help`、`codex plugin --help` 或插件界面帮助，以本机显示为准。示例中的域名、令牌和仓库均为占位符。

## 开始前检查

首次安装应在测试项目或临时目录中进行，不要在生产仓库或包含客户数据的目录中直接试验。

```bash theme={null}
codex --version
codex --help
codex plugin --help
codex mcp --help
git status --short
```

先明确本次操作的范围：

| 项目   | 需要确认的内容                        |
| ---- | ------------------------------ |
| 作用范围 | 当前项目，还是当前用户的所有项目               |
| 外部服务 | 是否需要 GitHub、Slack、Drive、数据库等授权 |
| 写入能力 | 是否会改文件、发消息、改任务、合并或部署           |
| 分发方式 | 本地测试、私有市场、工作区分享或公开发布           |
| 回滚方式 | 如何禁用、撤销授权、恢复配置和删除安装内容          |

令牌应放在环境变量或系统凭据存储中，不要写进 `plugin.json`、`.mcp.json`、Skill 文件、提交记录或截图。开始前保存配置备份，并记录当前工作区状态。

## 一、插件与其他扩展的关系

### 1. 插件解决什么问题

散装配置通常包含一个 Skill 目录、一段 MCP 配置、外部应用授权、hooks 和安装说明。分别复制时容易漏文件、环境变量或版本。插件用一个 manifest 描述这套能力，使安装者能看到统一的名称、版本和组件，维护者也能对整体发布更新。

| 需求                 | 适合的方式           | 原因           |
| ------------------ | --------------- | ------------ |
| 在一个仓库试验一条流程        | 项目级 Skill       | 文件少，迭代快      |
| 个人跨仓库复用一个工作流       | 用户级 Skill       | 组件简单，维护直接    |
| 只连接一个外部系统          | 单独 MCP 或连接器     | 权限面更小，故障更易定位 |
| 同时交付多个 Skill 和 MCP | 插件              | 组件一起安装和版本化   |
| 团队统一分发工作流          | 私有 Git 市场或工作区分享 | 来源和版本可控      |
| 需要自动触发检查           | 插件加 hooks       | 必须额外审查和信任    |

先单独验证每个 Skill 或 MCP，再打包成插件。一个临时提示词不值得增加插件包装层。

### 2. 插件能包含什么

| 组件         | 作用                        | 安装后的行为               |
| ---------- | ------------------------- | -------------------- |
| Skill      | 描述可复用的任务流程和验收步骤           | 按描述隐式匹配，也可显式调用       |
| MCP server | 暴露外部工具或数据源                | 启动本地进程，或连接远程 HTTP 服务 |
| 应用连接器      | 连接 GitHub、Slack、Drive 等应用 | 安装或首次使用时可能要求登录       |
| Hook       | 在事件发生时执行检查或脚本             | 不应因安装而自动获得信任         |
| 资源文件       | 图标、模板、参考资料和脚本             | 由组件按需读取              |

Skill 负责“怎么做”，MCP 负责“能调用什么”，连接器负责“通过哪个应用账号访问”，hook 负责“什么时候自动执行”。每个组件都要单独说明权限和失败行为。

## 二、插件目录结构

### 1. 最小目录

```text theme={null}
review-kit/
├── .codex-plugin/
│   └── plugin.json
└── skills/
    └── review/
        └── SKILL.md
```

`.codex-plugin` 是元数据目录，里面应只放 `plugin.json`。不要把 `skills`、`.mcp.json`、`.app.json` 或 `hooks` 错放进去。

### 2. 完整目录

```text theme={null}
release-assistant/
├── .codex-plugin/
│   └── plugin.json
├── skills/
│   ├── release-check/
│   │   ├── SKILL.md
│   │   └── references/checklist.md
│   └── change-summary/
│       └── SKILL.md
├── scripts/check-changelog.sh
├── references/release-policy.md
├── assets/icon.svg
├── .mcp.json
├── .app.json
└── hooks/hooks.json
```

| 路径                          | 作用          | 注意事项                               |
| --------------------------- | ----------- | ---------------------------------- |
| `.codex-plugin/plugin.json` | 插件 manifest | 固定位置，合法 JSON                       |
| `skills/<name>/SKILL.md`    | Skill 主文件   | frontmatter 含 `name`、`description` |
| `.mcp.json`                 | MCP 声明      | 令牌只引用环境变量                          |
| `.app.json`                 | 应用连接器声明     | 不打包 OAuth 密钥                       |
| `hooks/hooks.json`          | hooks 声明    | 每条命令都要审查                           |
| `assets/`、`references/`     | 静态资源和参考资料   | 不放秘密或客户数据                          |

Skill 仍然使用普通 Skill 格式：

```markdown theme={null}
---
name: release-check
description: 检查发布准备情况。当用户要求核对版本、changelog 和测试时使用。
---

读取版本、changelog、git status，并运行项目已有的最小测试。
输出阻塞项、已通过项和需要人工确认的项目。
不要创建 tag、推送、部署或修改远程任务，除非用户明确授权。
```

插件不会改变 Skill 的显式或隐式调用机制。`description` 应具体、前置触发词并写清边界。

## 三、manifest：插件的身份证

### 1. 最小 `plugin.json`

```json theme={null}
{
  "name": "review-kit",
  "version": "1.0.0",
  "description": "项目代码审查与发布前检查工具集",
  "skills": "./skills/"
}
```

| 字段            | 用途                        |
| ------------- | ------------------------- |
| `name`        | 稳定的插件标识，建议使用小写 kebab-case |
| `version`     | 当前插件版本，建议采用语义化版本          |
| `description` | 面向目录和安装者的简短说明             |
| `skills`      | Skill 目录或路径，按需填写          |
| `mcpServers`  | MCP server 声明或配置入口，按需填写   |
| `apps`        | 应用连接器声明或配置入口，按需填写         |
| `hooks`       | hooks 配置入口；默认路径是否可省略以版本为准 |
| `author`      | 维护者或组织，发布时建议填写            |
| `homepage`    | 源码、主页或问题反馈地址              |
| `license`     | 许可证标识                     |
| `interface`   | 显示名、图标、品牌色和起始提示等界面信息      |

字段名称、值类型和默认路径以当前插件规范为准。先用最小 manifest 验证发现和安装，再逐项加入组件和展示字段。

### 2. 多组件示例

```json theme={null}
{
  "name": "release-assistant",
  "version": "1.2.0",
  "description": "发布检查、变更摘要和项目管理连接器",
  "author": "Example Engineering",
  "homepage": "https://github.com/example/release-assistant",
  "license": "MIT",
  "skills": "./skills/",
  "mcpServers": "./.mcp.json",
  "apps": "./.app.json",
  "interface": {
    "displayName": "Release Assistant",
    "shortDescription": "发布前检查与变更摘要",
    "icon": "./assets/icon.svg"
  }
}
```

路径以插件根目录为基准，使用 `./` 开头的相对路径。建议遵循以下规则：

1. 插件名使用小写字母、数字和连字符，例如 `release-assistant`。
2. Skill 目录名与其 frontmatter 的 `name` 保持一致。
3. manifest 只声明真实存在、已经验证的组件。
4. 不在文件名或配置中加入用户名、电脑路径和秘密。
5. 删除组件时同时删除 manifest 引用和安装说明。

## 四、组合 Skill、MCP 和连接器

### 1. 先划分职责

“发布助手”可以按下面方式设计：

| 组件                     | 负责什么                  | 不负责什么       |
| ---------------------- | --------------------- | ----------- |
| `release-check` Skill  | 版本、changelog、工作区和测试检查 | 不直接发布或推送    |
| `change-summary` Skill | 根据 diff 生成变更摘要        | 不读取无关目录     |
| `project-tracker` MCP  | 查询发布任务                | 不默认修改任务状态   |
| GitHub 连接器             | 读取 PR、Issue 和发布记录     | 不自动合并 PR    |
| preflight hook         | 执行必要的格式检查             | 不删除文件、不上传内容 |

Skill 应明确何时调用 MCP 或连接器，以及调用失败时如何降级。没有实际调用外部工具时，不要声称已经查过数据。

### 2. MCP 配置

插件中的 `.mcp.json` 只声明启动方式、URL 和环境变量名称。示意：

```json theme={null}
{
  "mcpServers": {
    "project-tracker": {
      "command": "npx",
      "args": ["-y", "@example/project-tracker-mcp"],
      "env": {
        "TRACKER_TOKEN": "${TRACKER_TOKEN}"
      }
    }
  }
}
```

远程服务示意：

```json theme={null}
{
  "mcpServers": {
    "docs": {
      "url": "https://mcp.example.com/mcp",
      "bearerTokenEnvVar": "DOCS_TOKEN"
    }
  }
}
```

真实字段应按当前 Codex 插件 schema 验证。无论字段名如何变化，都应遵守：令牌不进仓库，优先只读账号，只开放必要工具，对写入和外发操作要求人工审批。外部网页、Issue 和文档可能带提示注入，不能把返回文本当作可信指令。

### 3. 连接器与 MCP 的区别

连接器通常由 Codex 或 ChatGPT 管理应用授权，可能通过 OAuth 取得访问范围。MCP server 是工具协议服务，可以是本地进程，也可以是远程 HTTP 服务。两者的数据范围、授权界面、凭据存储和隐私条款都可能不同。

安装后要分别检查：

1. 插件是否已安装并启用；
2. Skill 是否被发现；
3. MCP 是否启动或连接成功；
4. 连接器是否完成授权；
5. 每个工具是否仍需审批。

## 五、制作、打包和版本管理

### 1. 推荐顺序

1. 单独写好并验证每个 Skill。
2. 单独配置并验证每个 MCP server。
3. 记录连接器所需账号、scope 和撤销方式。
4. 创建插件根目录和 manifest。
5. 将组件放到根目录的约定路径。
6. 用最小 manifest 做本地安装测试。
7. 新开线程验证 Skill、MCP 和连接器。
8. 检查权限、失败处理、日志和卸载。
9. 内容冻结后更新版本并分发。

如果本机提供 `plugin-creator` 一类内置 Skill，可以用它生成骨架，但生成结果仍需审查。脚手架不能替代安全审计。

### 2. 创建骨架

类 Unix shell 示例：

```bash theme={null}
mkdir -p release-assistant/.codex-plugin
mkdir -p release-assistant/skills/release-check
mkdir -p release-assistant/skills/change-summary
mkdir -p release-assistant/assets
```

写入最小 manifest：

```json theme={null}
{
  "name": "release-assistant",
  "version": "0.1.0",
  "description": "发布检查和变更摘要工作流",
  "skills": "./skills/"
}
```

Windows PowerShell 使用对应的 `New-Item -ItemType Directory` 或文件管理器创建目录即可。不要把空目录当成已实现组件。

### 3. 打包前检查

```bash theme={null}
find release-assistant -maxdepth 4 -type f | sort
jq empty release-assistant/.codex-plugin/plugin.json
```

没有 `jq` 时使用其他 JSON 解析器。重点检查：

* `plugin.json` 位于固定路径且能解析；
* `.codex-plugin` 中没有误放组件目录；
* 所有相对路径都指向真实文件；
* Skill frontmatter 可解析；
* 没有 `.env`、私钥、令牌、客户数据和本地日志；
* 脚本没有写死个人路径；
* MCP URL 使用 HTTPS（本地开发服务除外）；
* hooks 的命令、参数、网络访问和失败策略可解释；
* 许可证和第三方依赖声明完整。

### 4. 版本策略

| 变化               | 版本示例          | 建议   |
| ---------------- | ------------- | ---- |
| 修复文档、脚本或兼容性问题    | 1.2.0 到 1.2.1 | 补丁版本 |
| 增加兼容的新 Skill 或工具 | 1.2.0 到 1.3.0 | 次版本  |
| 删除组件、改变工具语义或权限模型 | 1.2.0 到 2.0.0 | 主版本  |

每次发布记录变更、环境要求、权限变化、迁移步骤和回滚方式。不要用 `latest` 代替版本，也不要让不同内容共用同一个版本号。

## 六、安装和启用

### 1. 插件目录和本地市场

Codex App 通常可在 Plugins 面板浏览市场、阅读详情并安装。CLI 的交互入口常见为：

```text theme={null}
/plugins
```

安装前查看维护者、版本、源码、组件、权限、外部服务和数据政策。CLI 添加 Git 市场的常见命令是：

```bash theme={null}
codex plugin marketplace add owner/repo
codex plugin marketplace list
codex plugin marketplace add owner/repo --ref main
codex plugin marketplace add ./local-marketplace-root
```

具体参数以 `codex plugin marketplace --help` 为准。添加市场只是登记来源，不会自动安装其中所有插件。陌生仓库先看提交历史、源码、依赖和发布说明。

### 2. 安装后的新线程

安装或升级后新开一个 Codex 线程，确保加载最新能力清单。安装不等于授权：首次使用连接器或 MCP 时，仍可能要求登录、认证或批准工具调用。

### 3. 禁用和启用

插件浏览器通常可在已安装插件上切换启用状态。也可以按本机配置格式设置开关，示意：

```toml theme={null}
[plugins."release-assistant@example-market"]
enabled = false
```

配置键常由插件名和市场标识组成，以本机实际生成的配置为准。修改后重启 Codex，并检查插件状态。禁用不会自动撤销外部应用授权。

## 七、权限和数据安全

### 1. 安装、启用、授权是三件事

| 动作 | 发生什么         | 不代表什么       |
| -- | ------------ | ----------- |
| 安装 | 插件文件进入可发现范围  | 不代表工具自动批准   |
| 启用 | 组件可以参与发现和调用  | 不代表外部账号已登录  |
| 授权 | 用户授予某个应用访问范围 | 不代表其他组件也获授权 |

Skill 通常不需要外部账号，但其脚本可能读写本地文件。MCP 可能启动第三方进程或访问网络。连接器受服务商条款和隐私政策约束。hooks 可能在事件发生时自动执行，必须单独审阅。

### 2. 工具审批分级

| 等级 | 例子                   | 建议           |
| -- | -------------------- | ------------ |
| 低  | 读取版本、列目录、查询只读文档      | 可信环境中可减少重复审批 |
| 中  | 读取 Issue、修改本地文件、生成草稿 | 默认提示并确认范围    |
| 高  | 删除数据、部署、合并 PR、发外部消息  | 每次明确审批，必要时禁用 |

不要为了方便把整个 MCP server 设为自动批准。使用工具白名单、单工具审批、只读令牌和测试环境组合收口风险。

### 3. hooks 必须单独信任

看到 hooks 时先检查：

* 触发事件和完整命令；
* 环境变量、网络目标和写入路径；
* 是否下载后立即执行脚本；
* 失败时是阻止还是忽略；
* 是否会访问工作区之外的目录。

安装或启用插件不应自动信任其 hooks。无法解释的 hook 不要信任；可先删除 hooks、禁用插件或只安装无 hooks 的版本。

### 4. 数据流检查

为每个外部组件画出数据流：

```text theme={null}
当前项目文件 -> release-check Skill -> project-tracker MCP -> 外部服务
```

回答四个问题：读取哪些文件？发送哪些字段？服务商如何保存和删除？如何撤销令牌并恢复配置？不要把 `.env`、SSH 配置、客户数据和生产日志作为调试输入。

## 八、完整案例：发布助手插件

### 1. 目标和非目标

目标是检查版本、changelog、工作区和测试，查询只读发布任务，生成本地 diff 摘要，并向团队分发统一版本。

非目标是自动创建 tag、推送、合并、部署、更新远程任务或读取生产数据库。

### 2. 目录和 manifest

```text theme={null}
release-assistant/
├── .codex-plugin/plugin.json
├── skills/release-check/SKILL.md
├── skills/change-summary/SKILL.md
├── .mcp.json
├── .app.json
└── references/release-policy.md
```

```json theme={null}
{
  "name": "release-assistant",
  "version": "1.0.0",
  "description": "发布前检查、变更摘要和项目任务查询",
  "author": "Example Engineering",
  "homepage": "https://github.com/example/release-assistant",
  "license": "MIT",
  "skills": "./skills/",
  "mcpServers": "./.mcp.json",
  "apps": "./.app.json"
}
```

### 3. 两个 Skill

`release-check/SKILL.md`：

```markdown theme={null}
---
name: release-check
description: 进行发布前检查。当用户要求检查版本、changelog、测试和工作区时使用。
---

读取版本定义、changelog 和 git status，运行项目指定的最小测试。
必要时使用只读 project-tracker 查询发布任务。
输出阻塞项、已通过项和人工确认项。
不要创建 tag、推送、合并、部署或修改任务。
```

`change-summary/SKILL.md`：

```markdown theme={null}
---
name: change-summary
description: 根据 git diff 生成发布说明和风险摘要。当用户要求整理变更或写 release notes 时使用。
---

读取 git diff --stat 和必要片段，输出功能变化、修复、配置影响、测试证据和未验证风险。
不要复制密钥、个人信息、完整日志或无关源码；没有证据时写“未验证”。
```

### 4. 只读 MCP 和连接器

`.mcp.json` 的示意：

```json theme={null}
{
  "mcpServers": {
    "project-tracker": {
      "url": "https://tracker.example.com/mcp",
      "bearerTokenEnvVar": "TRACKER_READ_TOKEN"
    }
  }
}
```

在本地设置只读令牌：

```bash theme={null}
export TRACKER_READ_TOKEN="<只读令牌>"
```

PowerShell：

```powershell theme={null}
$env:TRACKER_READ_TOKEN = "<只读令牌>"
```

`.app.json` 的概念示例：

```json theme={null}
{
  "apps": [
    {
      "name": "github",
      "purpose": "读取发布相关的 Pull Request 和 Issue",
      "scopes": ["read:org", "repo:status"]
    }
  ]
}
```

真实 schema、应用名和 scope 必须以当前插件规范为准。案例的原则是用途明确、权限只读、令牌不打包。

### 5. 安装验证

安装后新开线程，先检查：

```text theme={null}
/skills
/mcp
```

然后执行无副作用任务：

```text theme={null}
请使用 release-check 做一次只读发布前检查。不要修改文件、更新项目任务、创建 tag、推送或部署。报告每个外部工具的名称、查询范围和结果来源。
```

测试显式调用：

```text theme={null}
$change-summary 请根据当前 diff 生成发布说明，只读取本地文件，不要联网。
```

验收证据应证明：两个 Skill 能被发现；MCP 已连接或明确待认证；连接器按预期授权；没有未经批准的写操作；外部查询失败时没有伪造成功结果。

### 6. 案例排错

| 现象          | 检查顺序                               |
| ----------- | ---------------------------------- |
| 插件不在列表      | manifest 路径、JSON、市场刷新              |
| Skill 不出现   | `skills` 路径、`SKILL.md`、frontmatter |
| MCP 无法连接    | URL、环境变量、令牌、网络和超时                  |
| 连接器反复登录     | 当前账号、工作区、scope 和服务状态               |
| 调用了错误 Skill | 收窄 description，改用 `$` 显式调用         |
| 旧版本仍生效      | 新线程、市场刷新和实际版本                      |
| hook 被跳过    | 尚未信任；先读定义，不要强行放行                   |

## 九、验证、升级、卸载和回滚

### 1. 四层验证

**发现层**：插件列表显示名称、版本和描述，manifest 路径可解析。

**加载层**：Skill 出现在选择器，MCP 出现在状态列表，连接器显示正确授权状态。

**行为层**：用无副作用任务触发 Skill，调用只读 MCP，确认审批按预期出现。

**边界层**：拒绝一次高风险工具；测试缺少令牌、网络失败和权限拒绝；确认不会静默扩大权限或伪造外部结果。

建议保存不含秘密的验收记录：

```text theme={null}
插件：release-assistant
版本：1.0.0
来源：example/release-assistant@<已审查的 ref>
Codex：<本机版本>
已验证：Skill、只读 MCP、连接器、禁用、卸载
未验证：生产部署、写入权限、长时间运行
```

### 2. 升级

升级前对比 manifest 和组件文件，检查新增的 MCP、连接器、hooks、依赖、环境变量和权限 scope。在临时项目安装新版本，复跑发现、加载、行为和边界验证，再更新团队市场。不要因为版本说明写着“仅修复 bug”就跳过审查。

### 3. 禁用和卸载

暂时不用时先禁用，并用新线程确认组件不再加载。彻底卸载时使用插件浏览器的卸载操作或当前 CLI 帮助中的命令。卸载前确认没有任务依赖它，保存必要配置，检查外部授权和 MCP 环境变量。

卸载通常只移除插件文件，不一定删除应用授权、远程账号、缓存或已创建的数据。要完整清理，还需在 ChatGPT 或服务商页面撤销授权，删除或轮换令牌，移除市场登记，并清理本地配置。

### 4. 回滚

升级异常时先禁用新版本，恢复经过验证的旧版本或固定 Git ref。共享市场中的错误版本应发布修复版本或按团队流程撤回，不要改写安装记录。令牌疑似泄露时，立即在服务端撤销并重新签发，不能只删除本地文件。

## 十、第三方插件风险

### 1. 风险来源

第三方插件可能包含恶意 Skill 指令、hooks、MCP 进程、过宽 OAuth scope、未固定的下载依赖，也可能把本地文件和环境变量外发。外部网页、Issue、文档和服务响应还可能携带提示注入。

插件目录收录或市场可访问不等于对所有第三方代码、server 和外部服务完成安全审计。仍需按组织供应链和数据安全要求评估。

### 2. 安装前检查

| 检查 | 证据                         |
| -- | -------------------------- |
| 来源 | 官方组织、仓库所有者、固定 ref 和发布渠道    |
| 代码 | manifest、脚本、hooks、启动命令和依赖  |
| 权限 | 工具清单、OAuth scope、环境变量和网络目标 |
| 数据 | 读取范围、外发字段、保存和删除政策          |
| 维护 | 更新频率、问题响应、版本记录和变更日志        |
| 许可 | LICENSE、依赖许可和商用限制          |
| 回滚 | 禁用、卸载、撤销令牌和旧版本恢复           |

无法获得源码或无法解释某项权限时，不要在敏感环境安装。先用隔离账号和空项目静态检查、行为测试。

### 3. 使用中的防护

* 第三方 MCP 默认使用人工审批模式；
* 只开放任务实际需要的工具；
* 生产系统优先使用只读账号；
* 不把外部文本中的指令直接转成本地命令；
* 不让插件读取整个用户主目录；
* 不信任未审阅的 hooks；
* 固定依赖版本和 Git ref；
* 记录插件版本、授权范围和实际调用。

发现未授权修改、删除、上传、未知域名访问、异常 scope 请求或更新后新增未披露组件时，立即禁用插件并撤销令牌。保存版本、来源、日志和配置快照，通知安全负责人，不要继续运行可疑脚本确认行为。

## 十一、常见错误

### 把组件放进 `.codex-plugin`

错误：

```text theme={null}
plugin/.codex-plugin/plugin.json
plugin/.codex-plugin/skills/review/SKILL.md
```

正确：

```text theme={null}
plugin/.codex-plugin/plugin.json
plugin/skills/review/SKILL.md
```

### 把令牌写进 manifest

manifest 会进入源码、市场和安装包，只能写环境变量名称或连接器引用。

### 认为安装等于授权

安装只让插件可发现。连接器、MCP 和工具仍可能分别需要登录、认证和审批。

### 安装后不新开线程

当前线程可能仍使用旧的能力清单。新开线程，再用 `/skills`、`/mcp` 和无副作用任务验证。

### description 过于宽泛

“处理所有代码任务”会导致隐式匹配不稳定。写具体任务、用户表达和不适用边界；有副作用的 Skill 可关闭隐式调用，只允许显式触发。

### 把市场当成可信边界

市场只是分发渠道。添加市场不会审查其中所有插件，仍需检查每个插件的源码、版本、权限和数据流。

## 十二、验收清单

* [ ] 插件名稳定唯一，版本与内容一致。
* [ ] `.codex-plugin/plugin.json` 存在且是合法 JSON。
* [ ] `.codex-plugin` 中没有误放组件目录。
* [ ] manifest 的每个路径都能解析。
* [ ] Skill frontmatter 可解析，description 具体且有边界。
* [ ] MCP 使用最小工具集、最小权限和环境变量引用。
* [ ] 连接器 scope 与用途匹配。
* [ ] hooks 已逐条审阅，未信任前不会自动运行。
* [ ] 包内没有密钥、客户数据、`.env` 和临时日志。
* [ ] 本地安装成功，插件列表显示正确版本。
* [ ] `/skills` 能发现预期 Skill，`/mcp` 显示预期 MCP 状态。
* [ ] 已完成只读或无副作用任务。
* [ ] 已测试缺少凭据、网络失败和权限拒绝。
* [ ] 已验证禁用、卸载和外部授权撤销。
* [ ] 已记录来源、版本、验证结果和未覆盖范围。

## 小结

插件是 Codex 的分发和组合单元：用 `.codex-plugin/plugin.json` 描述身份，用根目录下的 `skills/`、`.mcp.json`、`.app.json`、`hooks/` 和资源文件装配能力。它适合把已经单独验证过的一组工作流、外部工具和连接器交付给团队，而不是替代所有单独配置。

完整链路是：

```text theme={null}
拆分职责 -> 单独验证组件 -> 创建 manifest -> 组织目录 -> 本地安装
-> 新开线程加载 -> 检查 Skill/MCP/连接器 -> 审查权限和 hooks
-> 固定版本分发 -> 升级复验 -> 禁用、卸载和撤销授权
```

最重要的边界是：安装不等于授权，启用不等于自动批准，市场不等于可信，hooks 不应未经审查运行，令牌不应进入插件文件。只要能说明插件包含什么、读写什么、连接哪里、何时执行，以及如何停用和回滚，这套插件才算可维护。

参考资料：`参考/codex/23-plugins.md`、`参考/codex/22-skills.md`、`参考/codex/20-mcp.md`。