Harness Marketplace 剖析系列 - 之 Codex：Plugin、Marketplace 与通用插件目录

前面三篇，我们已经依次拆解了 Codex 扩展体系的三个基础层：

text 复制代码

目录与配置结构
    ↓
AGENTS.md
    ↓
Skill

其中：

text 复制代码

AGENTS.md
    → 持续生效的项目指导

Skill
    → 某类任务的可复用 Workflow

如果只是自己在一个项目里使用 Skill，到这里其实已经够了。

例如：

text 复制代码

repo/
└── .agents/
    └── skills/
        └── database-migration/
            └── SKILL.md

提交到 Git 后，团队成员就可以一起使用。

但很快会出现新的问题：

text 复制代码

一个能力不只有一个 Skill 怎么办？

多个 Skill 如何一起发布？

Skill 还依赖 GitHub、Slack、Google Drive 怎么办？

需要同时携带 MCP Server 怎么办？

希望安装一次就获得完整能力怎么办？

如何让一个能力同时出现在 ChatGPT 和 Codex？

如何在团队内建立自己的能力目录？

这时候就进入了下一层：

Plugin

OpenAI 当前对 Skill 与 Plugin 的边界定义得非常明确：

text 复制代码

Skill
    → 可复用工作流定义

Plugin
    → 可安装的能力分发单元

Plugin 可以包含：

text 复制代码

Skills
Connectors / Apps
MCP Servers
Hooks
Browser Extensions
Scheduled Task Templates
Assets

并通过统一的 Plugin Directory 或自定义 Marketplace 进行发现和分发。

所以，Codex 的扩展架构已经可以进一步写成：

text 复制代码

AGENTS.md
    → 项目长期规则

Skill
    → Workflow

MCP / App
    → 外部能力

Plugin
    → Distribution Package

Marketplace
    → Distribution Catalog

这一篇重点回答：

text 复制代码

Codex Plugin 到底是什么？
Plugin 与 Skill 的边界在哪里？
一个真实 Plugin 的目录是什么样？
plugin.json 负责什么？
Plugin 如何携带多个 Skill？
Plugin 如何连接 App / MCP？
Marketplace 与 Plugin 是什么关系？
Universal Plugin Directory 是什么？
OpenAI / Workspace / Personal 如何区分？
Repo Marketplace 与 Personal Marketplace 怎么实现？
Plugin 安装后如何进入 Codex？
Plugin 能力如何进入 Skill Registry 和 Tool Runtime？
Plugin 的安装目录和 Cache 到底在哪里？
Plugin 如何跨 ChatGPT 与 Codex 复用？

一、Codex Plugin 到底是什么

1. 从 Skill 到 Plugin

前一篇已经分析过，一个 Skill 本质上是：

text 复制代码

Metadata
+
Instructions
+
References
+
Scripts
+
Assets

例如：

text 复制代码

gh-fix-ci/
├── SKILL.md
├── scripts/
└── references/

它主要回答：

这个任务应该怎么做？

而 Plugin 解决的问题变成：

如何把一组 Workflow 和外部能力打包成一个可以安装、启用和分发的产品单元？

官方当前的定义是：

Plugin 是一个 installable bundle，可以包含 Skills、Connectors，或者二者同时包含。

所以：

text 复制代码

Skill
    → Authoring Unit

Plugin
    → Distribution Unit

这两个概念不能混在一起。

2. 一个 Plugin 可以只有 Skill

最简单的 Plugin 完全不需要 MCP。

例如：

text 复制代码

meeting-follow-up/
├── .codex-plugin/
│   └── plugin.json
└── skills/
    └── meeting-follow-up/
        └── SKILL.md

这个 Plugin 的能力就是：

text 复制代码

会议记录
    ↓
提取决策
    ↓
提取 Owner
    ↓
提取 Next Steps

官方 Build Plugins 文档就提供了这种最小结构。

3. Plugin 也可以是多个 Skill 的集合

例如企业开发一个：

text 复制代码

engineering-productivity

Plugin：

text 复制代码

engineering-productivity/
├── .codex-plugin/
│   └── plugin.json
│
└── skills/
    ├── code-review/
    ├── fix-ci/
    ├── release/
    └── dependency-review/

一次安装，就把整个工程团队的标准 Workflow 带进 Codex。

所以 Plugin 天然适合：

text 复制代码

能力集合
领域能力包
团队标准包
岗位能力包

4. Plugin 还可以把 Workflow 和 Tool 组合起来

例如：

text 复制代码

github-engineering/
├── skills/
│   ├── review-pr/
│   ├── fix-ci/
│   └── create-release/
│
└── GitHub App / MCP

这里：

text 复制代码

Skill
    → 告诉 Agent GitHub 工作流该怎么完成

App / MCP
    → 真正提供 GitHub 数据和操作能力

这就形成：

text 复制代码

Workflow
+
Connected Capability

官方 Plugins 文档明确说明，Plugin 可以组合 Skills 与 Connectors，而 Connector 背后由 MCP Server 提供 Tool、认证、结构化数据和外部动作能力。

所以 Plugin 的核心价值不是：

text 复制代码

把几个目录压缩在一起

而是：

把"怎么做"和"能做什么"封装为一个可安装能力。

二、一个 Codex Plugin 在磁盘上长什么样

这一层先不讨论 Marketplace，只看 Plugin Package 自己。

当前官方 Plugin 结构已经比较明确。

一个 Plugin 是一个目录，其中必须包含：

text 复制代码

.codex-plugin/plugin.json

可选包含：

text 复制代码

skills/
.app.json
.mcp.json
assets/

OpenAI 2026 年的 Codex Changelog 也明确公开了这套结构。

可以抽象成：

text 复制代码

my-plugin/
├── .codex-plugin/
│   └── plugin.json
│
├── skills/
│   ├── skill-a/
│   │   └── SKILL.md
│   └── skill-b/
│       └── SKILL.md
│
├── .app.json
├── .mcp.json
└── assets/

1. `.codex-plugin/plugin.json`：Plugin Manifest

最小 Manifest 可以是：

json 复制代码

{
  "name": "my-first-plugin",
  "version": "1.0.0",
  "description": "Reusable greeting workflow",
  "skills": "./skills/"
}

官方明确要求使用稳定的 kebab-case name，因为 Plugin Host 会将它作为：

text 复制代码

Plugin Identifier
+
Component Namespace

使用。

这点非常重要。

它意味着 Plugin Name 不只是显示名，而是运行时身份的一部分。

2. Plugin Manifest 与 Skill Frontmatter 的职责不同

Skill：

yaml 复制代码

---
name: hello
description: Greet the user...
---

负责：

text 复制代码

Skill Semantic Identity
Skill Routing

Plugin：

json 复制代码

{
  "name": "my-first-plugin",
  "version": "1.0.0"
}

负责：

text 复制代码

Package Identity
Package Version
Component Location

可以理解为：

text 复制代码

plugin.json
    → Package Manifest

SKILL.md
    → Capability Manifest

3. `skills/`：Plugin 内的 Workflow 集合

Manifest 可以声明：

json 复制代码

{
  "skills": "./skills/"
}

然后：

text 复制代码

skills/
├── hello/
│   └── SKILL.md
├── review/
│   └── SKILL.md
└── release/
    └── SKILL.md

Plugin Host 扫描后，可以把这些 Skill 暴露给 Codex。

这里产生一个很重要的结构：

text 复制代码

Plugin
    ↓
skills/
    ↓
Skill Metadata
    ↓
Codex Skill Catalog

后面 Runtime 部分再详细分析。

4. `.app.json`：App / Connector 映射层

如果 Plugin 需要连接一个已经注册的 App / Connector，则可以使用：

text 复制代码

.app.json

当前官方 Plugin Builder 流程中，创建带 MCP Server 的 Plugin 时：

text 复制代码

先注册 MCP Server Connection
    ↓
获得 plugin_asdk_app... ID
    ↓
写入 .app.json
    ↓
plugin.json 通过 apps 字段引用 .app.json

官方明确要求作者检查 .app.json 是否映射到正确的 MCP Connection ID。

因此：

text 复制代码

.app.json

可以理解为：

text 复制代码

Plugin
    ↔
已注册 App / Connector

的兼容和映射层。

5. `.mcp.json`：直接 MCP 配置

当前 Codex Plugin 结构还允许携带：

text 复制代码

.mcp.json

官方 Changelog 明确将其描述为：

text 复制代码

Optional MCP server configuration

所以 Plugin 可以有两类外部能力路径：

text 复制代码

Plugin
├── App / Connector
│   └── .app.json
│
└── MCP Server
    └── .mcp.json

两者最终都会给 Agent 提供外部 Tool，但生命周期、认证和产品 UI 可能不同。

这一点后面的 MCP 专篇再深入。

6. `assets/`：Plugin 展示与工作流资源

Plugin 还可以包含：

text 复制代码

assets/

用于：

text 复制代码

Icon
Logo
Screenshots
其他展示资源

这与 Skill 内部的 assets/ 角色有所不同。

可以区分为：

text 复制代码

Plugin Assets
    → Package / Directory 展示

Skill Assets
    → Workflow 执行产物资源

三、Marketplace 如何把 Plugin 组织起来

有 Plugin Folder 后，还需要解决：

text 复制代码

用户怎么发现它？

这就是 Marketplace。

1. Marketplace 本质是 Catalog

官方定义非常直接：

Marketplace 是一个 Plugin 的 JSON Catalog。

例如：

json 复制代码

{
  "name": "local-example-plugins",
  "interface": {
    "displayName": "Local Example Plugins"
  },
  "plugins": [
    {
      "name": "my-plugin",
      "source": {
        "source": "local",
        "path": "./plugins/my-plugin"
      },
      "policy": {
        "installation": "AVAILABLE",
        "authentication": "ON_INSTALL"
      },
      "category": "Productivity"
    }
  ]
}

这里并不包含 Plugin 的全部实现。

它只是告诉 Codex：

text 复制代码

Plugin 是什么
在哪里
是否可安装
什么时候认证
显示在哪个分类

因此：

text 复制代码

Marketplace
≠
Plugin

Marketplace
=
Plugin Index

2. Repo Marketplace

项目级 Marketplace 默认可以放在：

text 复制代码

$REPO_ROOT/.agents/plugins/marketplace.json

Plugin 则常见放在：

text 复制代码

$REPO_ROOT/plugins/

例如：

text 复制代码

project/
├── .agents/
│   └── plugins/
│       └── marketplace.json
│
└── plugins/
    ├── java-review/
    ├── database-tools/
    └── release-manager/

Marketplace Entry：

json 复制代码

{
  "name": "java-review",
  "source": {
    "source": "local",
    "path": "./plugins/java-review"
  }
}

官方强调：

text 复制代码

source.path

是相对于 Marketplace Root 解析，而不是相对于：

text 复制代码

.agents/plugins/

目录本身。

这个细节非常重要。

3. Personal Marketplace

用户自己的 Marketplace 位于：

text 复制代码

~/.agents/plugins/marketplace.json

常见 Plugin 目录示例：

text 复制代码

~/.codex/plugins/

例如：

text 复制代码

~/
├── .agents/
│   └── plugins/
│       └── marketplace.json
│
└── .codex/
    └── plugins/
        └── my-plugin/

官方 Build Plugins 文档就是这样给出 Personal Marketplace 示例的。

但需要注意：

~/.codex/plugins/ 是官方推荐示例路径之一，不是 Marketplace 强制要求的固定物理目录。

因为 Marketplace Entry 可以指向其他合法路径。

官方明确说这些目录是：

text 复制代码

examples rather than fixed requirements

Marketplace 真正决定位置的是：

text 复制代码

source.path

4. Marketplace 不一定是本地目录

Codex CLI 当前支持：

text 复制代码

GitHub shorthand
Git HTTP / HTTPS
Git SSH
Local Marketplace Root

例如：

bash 复制代码

codex plugin marketplace add owner/repo

codex plugin marketplace add owner/repo --ref main

codex plugin marketplace add https://github.com/example/plugins.git

codex plugin marketplace add ./local-marketplace-root

还支持：

text 复制代码

--ref

固定 Git Ref，以及：

text 复制代码

--sparse

进行 Git sparse checkout。

所以 Marketplace Source 可以理解为：

text 复制代码

Local Catalog
或
Remote Catalog

5. Marketplace 生命周期已经有独立 CLI

Codex 当前提供：

bash 复制代码

codex plugin marketplace list

codex plugin marketplace upgrade

codex plugin marketplace upgrade marketplace-name

codex plugin marketplace remove marketplace-name

这说明 Marketplace 已经不是一个简单静态 JSON 文件。

在 Codex Harness 中，它实际上存在：

text 复制代码

Marketplace Source Registry

概念。

可以抽象为：

text 复制代码

Configured Marketplace Source
    ↓
Resolve / Clone / Snapshot
    ↓
marketplace.json
    ↓
Plugin Entries

这里的 Marketplace Source Registry 是工程抽象，不代表 OpenAI 源码中的具体类名。

四、Universal Plugin Directory：从本地 Catalog 到统一能力市场

本地 Marketplace 解决：

text 复制代码

个人
项目
小团队

的能力分发。

但 OpenAI 当前还建立了更上一层：

Universal Plugin Directory

官方明确说明：

text 复制代码

ChatGPT
+
Codex

共享同一个 Public Plugin Catalog

同一个 Public Plugin 只需要发布一次，就可以在支持的 ChatGPT 和 Codex Surface 中被发现。

这意味着 Plugin 不再只是：

text 复制代码

Codex CLI Extension

而成为：

text 复制代码

OpenAI Agent Ecosystem Distribution Unit

1. Plugin Directory 的三个主要来源

当前 Plugins Directory 将 Plugin 分为：

text 复制代码

OpenAI
Workspace
Personal

官方页面具体描述为：

text 复制代码

OpenAI
    → OpenAI 构建的 Plugin

Your workspace
    → 当前 Workspace 提供的 Plugin

Personal
    → 用户自己的 Marketplace Plugin
       包括 Created by me / Shared with me

另外还有：

text 复制代码

Installed

区域用于查看已经安装的 Plugin。

所以 UI 上可以建立：

text 复制代码

Plugin Directory
├── OpenAI
├── Workspace
├── Personal
└── Installed

这比 Claude Code 的 Marketplace 更偏"产品化能力商店"。

2. Workspace Plugin 不是 Public Plugin

本地 Plugin 可以发布到 Workspace。

官方当前要求：

text 复制代码

必须是 Workspace Admin

并且发布时可以指定：

text 复制代码

哪些 Workspace Role 可以访问

这类 Plugin：

text 复制代码

只属于当前组织

不会自动进入：

text 复制代码

Universal Public Plugin Directory

官方明确区分：

text 复制代码

Workspace Published Plugin
    → Organization Boundary

Public Plugin
    → Universal Directory

企业可以在：

text 复制代码

requirements.toml

中配置：

toml 复制代码

features.plugin_sharing = false

阻止 Workspace Plugin Publishing。

这说明 Plugin 已经进入 Codex 企业治理体系。

它不只是：

text 复制代码

开发者自己的插件目录

而是受到：

text 复制代码

Workspace Policy
Admin Role
Requirements

共同管理的企业能力。

五、Plugin 安装后如何进入 Codex Runtime

这是本文最关键的一层。

前面的流程还是：

text 复制代码

Catalog
Package
Installation

真正的问题是：

安装一个 Plugin 后，它里面的 Skill、MCP 和其他能力怎么进入 Codex？

当前官方文档已经明确部分行为，但并没有公开完整 Loader 内部实现。

因此这里需要分成：

text 复制代码

官方明确事实
和
工程抽象

1. 安装并不等于当前 Session 立即拥有能力

在 ChatGPT / Desktop 中，官方安装步骤明确要求：

text 复制代码

安装 Plugin
    ↓
如果需要 Connector，则完成连接
    ↓
启动新的 Chat
    ↓
使用 Plugin

在 Codex CLI 中同样明确：

text 复制代码

/plugins
    ↓
安装 Plugin
    ↓
开始一个新 Session
    ↓
才能使用其 bundled skills / tools

因此可以明确判断：

text 复制代码

Plugin Installation
    ≠
当前 Agent Context 的即时热注入

至少官方当前推荐流程仍是：

text 复制代码

Install
    ↓
New Session
    ↓
Capability Discovery

2. Codex CLI 有独立 Plugin Browser

Codex CLI 使用：

text 复制代码

/plugins

打开 Plugin Browser。

当前可以：

text 复制代码

按 Marketplace 切换来源
查看 Plugin Detail
Install
Uninstall
Enable
Disable

已经安装的 Plugin 可以通过：

text 复制代码

Space

切换启用状态。

因此 Plugin 至少存在三个概念状态：

text 复制代码

Available
Installed
Enabled

可以抽象为：

text 复制代码

Marketplace Entry
    ↓
Install
    ↓
Installed Plugin
    ↓
Enable
    ↓
Runtime-visible Plugin

3. Plugin 中的 Skill 如何进入 Codex

官方当前明确说明：

Installed plugins can add skills、connectors 和 MCP tools 到新的 Chat / Session。

结合前一篇 Skill Loader，可以做一个非常自然的运行模型：

text 复制代码

Enabled Plugin
    ↓
读取 plugin.json
    ↓
解析 skills 路径
    ↓
扫描 Plugin Skills
    ↓
解析 Skill Metadata
    ↓
加入 Skill Catalog

于是：

text 复制代码

Local Skill
Repo Skill
System Skill
Plugin Skill
        ↓
统一进入逻辑 Skill Catalog

这个"统一 Skill Catalog"是根据官方 Skill / Plugin 行为形成的架构抽象，并不是 OpenAI 文档公布的具体 Registry 类名称。

4. Plugin Skill 仍然遵守 Skill 的 Progressive Disclosure

Plugin 并没有改变 Skill 的基本运行方式。

例如：

text 复制代码

github-plugin/
└── skills/
    └── fix-ci/
        ├── SKILL.md
        └── scripts/

安装 Plugin 后：

text 复制代码

fix-ci

仍然是一个 Skill。

所以其运行过程仍然可以理解为：

text 复制代码

Plugin Enabled
    ↓
Skill Metadata 注册
    ↓
User Prompt
    ↓
Skill Match
    ↓
加载 SKILL.md
    ↓
按需执行 Script

也就是说：

text 复制代码

Plugin
    → 改变 Skill 来源

不会改变：
Skill Execution Model

5. MCP / Connector 如何进入 Tool Runtime

如果 Plugin 携带：

text 复制代码

Connector
MCP Server

安装时可能要求：

text 复制代码

Connection
Authentication

有些 Plugin：

text 复制代码

安装时认证

有些：

text 复制代码

第一次使用时认证

官方 Marketplace Metadata 中也存在：

text 复制代码

policy.authentication

例如：

text 复制代码

ON_INSTALL

运行逻辑可以抽象为：

text 复制代码

Plugin Installed
    ↓
Connector / MCP Definition
    ↓
Connection Setup
    ↓
Authentication
    ↓
Tool Registration
    ↓
Codex Agent Runtime

6. Plugin 不会突破 Codex 自己的 Sandbox

这是一个非常重要的安全边界。

官方明确说明：

当 Plugin Capability 通过 Codex Host 运行时，仍然受 Codex Host 的 Sandbox 和 Approval Policy 管理。

因此：

text 复制代码

Plugin
    → 增加能力

但不能天然获得：
无限本地权限

最终仍然是：

text 复制代码

Plugin Capability
    ↓
Codex Host
    ↓
Approval
    ↓
Sandbox

对于外部服务，则：

text 复制代码

Connector / App
    ↓
外部服务自己的认证与权限系统

也就是说，一个 Plugin 的最终权限是两个安全域共同决定的：

text 复制代码

Codex Runtime Policy
+
External Service Authorization

六、Plugin 如何跨 ChatGPT 与 Codex 复用

这是 Codex Plugin 和 Claude Code Plugin 最大的架构差异之一。

OpenAI 当前正在把 Plugin 设计成：

text 复制代码

跨 Surface Distribution Package

而不是某一个 CLI 的私有扩展格式。

1. 同一个 Plugin 可以服务不同 Surface

官方当前明确的支持范围包括：

text 复制代码

ChatGPT Web
ChatGPT Desktop
ChatGPT Mobile
ChatGPT Work
Codex in ChatGPT Desktop
Codex CLI

不同 Surface 支持程度并不完全一致。

Plugin 可以包含：

text 复制代码

Skill
    → ChatGPT 与 Codex 都可理解的 Workflow

App / Connector
    → 外部系统能力

MCP
    → Tool Runtime

UI
    → ChatGPT 产品展示

因此它本质上是：

text 复制代码

Workflow Package
+
Capability Package
+
Presentation Package

2. ChatGPT 使用 `@`

在 ChatGPT 中：

text 复制代码

@plugin

或者：

text 复制代码

@bundled-skill

进行显式选择。

官方 Plugins 页面当前说明可以通过：

text 复制代码

选择具体 Plugin 或其中 Skill。

3. Codex Skill 使用 `$`

前一篇已经分析：

text 复制代码

$skill-name

是 Codex 的 Skill 显式调用方式。官方 Skills & Plugins 文档仍然明确保留这一点。

因此：

text 复制代码

同一个 Skill Package

在不同 Host 上：

text 复制代码

ChatGPT
    → @

Codex
    → $

Host UI 不同，但底层 Workflow Package 可以复用。

4. "一次发布，多个 Surface 发现"

Universal Plugin Directory 的核心价值就是：

text 复制代码

Plugin Author
    ↓
Publish Once
    ↓
Universal Plugin Directory
    ↓
ChatGPT
+
Codex

从平台架构角度看，这意味着：

text 复制代码

Authoring Format
和
Distribution Format

正在被统一。

七、Plugin Directory 与 App Directory 的演进

这里有一个当前版本非常值得记录的变化。

OpenAI Help Center 明确说明：

text 复制代码

截至 2026 年 7 月 9 日，
App Directory 已迁移为 Plugin Directory。

Plugin 现在成为 ChatGPT 与 Codex 中发现 Workflow Capability 的主要单位。

以前更容易理解为：

text 复制代码

App
    → 外部系统集成

现在架构变成：

text 复制代码

Plugin
    → Workflow Container

Plugin 内部可以包含：
    Skill
    App
    App Template

而：

text 复制代码

App

仍然负责：

text 复制代码

外部数据
外部动作
身份认证
权限

所以：

text 复制代码

Plugin
    → Product Capability Boundary

App
    → External Integration Boundary

这是一个非常重要的概念变化。

八、Plugin 与 App / MCP 的权限边界

一个 Plugin 包含 App，并不意味着 Plugin 自己决定 App 权限。

官方 Help Center 明确说明：

text 复制代码

已有 App 权限继续生效

包括：

text 复制代码

哪些用户或角色可以访问
只读还是可执行动作
是否需要动作确认
Sync 限制
Domain 限制
Source Boundary

Plugin 使用某个 App 时，会继承这些 App Policy。

例如：

text 复制代码

GitHub Plugin
    ↓
依赖 GitHub App

如果某用户在 GitHub App 中：

text 复制代码

只能读取 Repository A

Plugin 不应该通过 Codex 突破成：

text 复制代码

读取 Repository B

所以权限链是：

text 复制代码

Plugin
    ↓
App / MCP
    ↓
Workspace Policy
    ↓
External Service ACL

九、一个完整 Plugin 案例

现在可以设计一个更接近企业真实使用的 Plugin。

假设：

text 复制代码

engineering-release/

text 复制代码

engineering-release/
├── .codex-plugin/
│   └── plugin.json
│
├── skills/
│   ├── prepare-release/
│   │   └── SKILL.md
│   │
│   ├── review-release/
│   │   └── SKILL.md
│   │
│   └── rollback-release/
│       └── SKILL.md
│
├── .app.json
├── .mcp.json
└── assets/
    └── icon.png

Manifest：

json 复制代码

{
  "name": "engineering-release",
  "version": "2.1.0",
  "description": "Release workflow for engineering teams",
  "skills": "./skills/"
}

Marketplace：

text 复制代码

company-marketplace/
├── .agents/
│   └── plugins/
│       └── marketplace.json
│
└── plugins/
    └── engineering-release/

Entry：

json 复制代码

{
  "name": "engineering-release",
  "source": {
    "source": "local",
    "path": "./plugins/engineering-release"
  },
  "policy": {
    "installation": "AVAILABLE",
    "authentication": "ON_INSTALL"
  },
  "category": "Engineering"
}

运行链：

text 复制代码

Marketplace
    ↓
发现 engineering-release
    ↓
用户 Install
    ↓
完成 GitHub / Deployment App 认证
    ↓
Plugin Enabled
    ↓
新建 Codex Session
    ↓
加载 Plugin Manifest
    ↓
发现三个 Skills
    ↓
加入 Skill Catalog
    ↓
连接 MCP / App Tools

用户提出：

text 复制代码

帮我准备 v2.4.0 发布。

模型可能匹配：

text 复制代码

prepare-release

然后：

text 复制代码

加载 SKILL.md
    ↓
读取当前 Git 状态
    ↓
调用 GitHub Tool
    ↓
生成 Release Notes
    ↓
运行测试
    ↓
Approval
    ↓
Sandbox
    ↓
创建 Release

完整链就变成：

text 复制代码

Plugin
    ↓
Skill
    ↓
Workflow
    ↓
Tool
    ↓
Approval
    ↓
Sandbox
    ↓
External Service

十、Codex Plugin 的安装和存储边界

这一部分要特别谨慎。

目前官方已经明确：

text 复制代码

Repo Marketplace：
$REPO_ROOT/.agents/plugins/marketplace.json

Personal Marketplace：
~/.agents/plugins/marketplace.json

以及 Personal Plugin 的推荐示例路径：

text 复制代码

~/.codex/plugins/

Repo Plugin 则可以：

text 复制代码

./plugins/

但还不能简单断言：

text 复制代码

~/.codex/plugins
=
Codex 所有 Plugin 的统一安装 Cache

因为官方明确说明：

text 复制代码

这些 Plugin 目录只是示例
Marketplace Source 可以指向其他位置

所以目前应该区分：

text 复制代码

Plugin Source Directory
和
Host Internal Installation State

已经公开稳定的是：

text 复制代码

Marketplace JSON
Plugin Folder
plugin.json

而像：

text 复制代码

Marketplace Snapshot Cache
Installed Plugin Internal Registry
Resolved Version Cache
Remote Marketplace Clone Location

虽然 Codex CLI 显然存在这些运行状态，但其内部目录不应在没有源码确认的情况下当成稳定 API。

十一、一个当前文档中的 Surface 差异

这里还有一个很值得记录的当前版本问题。

Plugins 主文档当前写的是：

text 复制代码

IDE Extension 不支持 Plugin

并建议使用：

text 复制代码

ChatGPT Desktop
或
Codex CLI

进行浏览和安装。

但 Codex Changelog 的 2026 年 Plugin 发布条目又写到：

text 复制代码

Plugins are available in the Codex app, CLI, and IDE extensions.

这说明截至当前官方公开资料之间仍存在一定版本或 Surface 文档不同步。

因此这篇文章不宜直接写成：

text 复制代码

Codex IDE 一定支持完整 Plugin Browser

更稳妥的说法是：

Plugin 已经进入 Codex App 与 CLI 的正式能力体系；IDE Extension 的具体支持范围当前官方页面存在差异，应以用户当前版本的客户端能力为准。

这是技术文章中应该明确标注的"版本敏感点"。

十二、从 Plugin 看 Codex 的整体扩展架构

分析到这里，可以把 Codex 的扩展层重新整理一次。

1. AGENTS.md：长期指导层

text 复制代码

项目长期规则

2. Skill：Workflow 层

text 复制代码

某类任务应该怎么做

3. App / MCP：Capability 层

text 复制代码

可以访问哪些外部系统
可以执行哪些动作

4. Plugin：Packaging 层

text 复制代码

哪些 Skill
+
哪些 Tool
+
哪些资源

属于同一能力包

5. Marketplace：Catalog 层

text 复制代码

有哪些 Plugin
从哪里获取
是否可安装
如何认证

6. Universal Plugin Directory：生态分发层

text 复制代码

Public
Workspace
Personal

让同一 Plugin 可以跨 ChatGPT 与 Codex Surface 被发现。

完整关系：

text 复制代码

AGENTS.md
    ↓
长期指导

Skill
    ↓
Workflow

App / MCP
    ↓
Tool Capability

Plugin
    ↓
Package

Marketplace
    ↓
Catalog

Universal Directory
    ↓
Ecosystem Distribution

Codex Harness
    ↓
Runtime

十三、Codex Plugin 设计的几个关键优点

1. Workflow 与 Distribution 解耦

Skill 可以先独立开发。

成熟以后再：

text 复制代码

Skill
    ↓
Plugin

不需要从一开始就建立完整 Marketplace。

2. Tool 与 Workflow 可以一起交付

Plugin 不只提供 Prompt，还可以提供：

text 复制代码

外部系统连接
MCP
App
Hook

更像真正的能力包。

3. Plugin 可以跨产品

同一包可以服务：

text 复制代码

ChatGPT
Codex

而不局限于某一个 CLI。

4. 支持从个人到企业逐级扩展

text 复制代码

Personal Marketplace
    ↓
Repo Marketplace
    ↓
Workspace Plugin
    ↓
Universal Public Directory

开发者可以逐层扩大分发范围。

5. 企业治理边界更加明确

Plugin Distribution 受：

text 复制代码

Workspace Admin
Role
requirements.toml
App Permissions

共同控制。

十四、Codex Plugin 当前仍存在的几个局限

1. Runtime 内部 Loader 仍未完全公开

官方公开了文件格式与使用行为，但：

text 复制代码

Plugin Registry
Marketplace Snapshot
Version Resolution
Cache
Hot Reload

等底层细节还需要继续结合 Codex 源码验证。

2. Plugin 与 Skill 同名冲突规则需要进一步验证

例如：

text 复制代码

Local Skill：review
Plugin A Skill：review
Plugin B Skill：review

最终 UI 和 Routing 如何区分，目前需要在运行时专篇中进一步测试。

3. 多 Surface 支持存在版本差异

尤其是 IDE Extension，官方不同页面当前存在描述不同步。

4. Plugin 依赖 App 后，治理复杂度明显增加

一个普通 Workflow 安装后可能带来：

text 复制代码

OAuth
External Data
External Actions
Workspace RBAC
Confirmation Policy

所以 Plugin 的风险级别通常高于单纯 Skill。

十五、对自研 Harness Marketplace 的启发

Codex 的 Plugin 模型其实非常值得借鉴，因为它明确把：

text 复制代码

Capability Authoring
和
Capability Distribution

拆成两层。

1. SkillDescriptor

text 复制代码

Skill
    → Workflow Definition

例如：

java 复制代码

public record SkillDescriptor(
    String id,
    String name,
    String description,
    String entry,
    List<ToolDependency> dependencies
) {}

2. PluginDescriptor

java 复制代码

public record PluginDescriptor(
    String id,
    String version,
    String description,
    List<String> skillEntries,
    List<McpDescriptor> mcpServers,
    PluginSource source
) {}

它负责：

text 复制代码

Package
Version
Source
Capabilities

3. MarketplaceDescriptor

java 复制代码

public record MarketplaceDescriptor(
    String name,
    String displayName,
    List<PluginCatalogEntry> plugins
) {}

只负责：

text 复制代码

Catalog

而不是直接承担 Runtime。

4. 清晰拆成三层 Registry

text 复制代码

MarketplaceRegistry
    ↓
PluginRegistry
    ↓
CapabilityRegistry

对应：

text 复制代码

Marketplace
    → 我有哪些包？

Plugin
    → 每个包里有什么？

Capability
    → Agent 最终能用什么？

5. Runtime 不直接依赖 Marketplace

这是一个很重要的设计原则。

不要：

text 复制代码

Agent
    → 查询 Marketplace
    → 直接执行 Plugin

而应该：

text 复制代码

Marketplace
    ↓
Install
    ↓
Plugin Resolve
    ↓
Capability Registration
    ↓
Agent Runtime

也就是说：

text 复制代码

Marketplace
属于 Control Plane

Capability Registry
属于 Runtime Plane

6. Plugin 安装应生成不可变 Runtime Snapshot

相比只保存目录，可以增加：

yaml 复制代码

plugin:
  id: engineering-release
  version: 2.1.0

source:
  marketplace: company-market
  commit: abc123

capabilities:
  skills:
    - prepare-release
    - review-release

  mcp:
    - github
    - deployment

installedAt: 2026-08-11

这样 Agent Runtime 不需要每次重新解析 Marketplace。

总结

Codex 当前已经形成了一套非常清晰的：

text 复制代码

Skill
    → Workflow Authoring

Plugin
    → Capability Packaging

Marketplace
    → Capability Catalog

Universal Plugin Directory
    → Ecosystem Distribution

Plugin 的最小结构是：

text 复制代码

my-plugin/
├── .codex-plugin/
│   └── plugin.json
└── skills/
    └── hello/
        └── SKILL.md

其中：

text 复制代码

plugin.json
    → Package Identity

SKILL.md
    → Workflow Definition

Plugin 还可以进一步携带：

text 复制代码

.app.json
.mcp.json
assets/
多个 Skills
Hooks
其他 Runtime Capabilities

官方当前明确将 Plugin 定义为可以包含 Skill、Connector 或二者组合的可安装能力包。

Marketplace 则是独立的 JSON Catalog：

text 复制代码

Repo：
$REPO_ROOT/.agents/plugins/marketplace.json

Personal：
~/.agents/plugins/marketplace.json

Plugin Source 可以来自本地目录，也可以来自 GitHub、Git HTTP/HTTPS、SSH Git 等远程来源。

安装过程可以概括为：

text 复制代码

Marketplace
    ↓
Plugin Entry
    ↓
Install
    ↓
Enable
    ↓
New Session
    ↓
Plugin Manifest
    ↓
Skills / MCP / Apps
    ↓
Capability Registration
    ↓
Codex Runtime

而更上一层的 Universal Plugin Directory，则让同一个 Public Plugin 能够同时被 ChatGPT 与 Codex 的支持 Surface 发现。

因此，从 Harness 角度看：

Skill 是 Agent Workflow 的创作格式，Plugin 是能力的安装和分发格式，Marketplace 是 Plugin 的发现目录，而 Codex Harness 最终负责把已启用 Plugin 中的 Workflow 和 Tool 转化成真正的运行时能力。

这使 Codex 的扩展体系从：

text 复制代码

一个项目里的 .agents/skills

进一步升级为：

text 复制代码

Local Skill
    ↓
Plugin
    ↓
Marketplace
    ↓
Workspace
    ↓
Universal Directory

也就是从：

text 复制代码

个人 Workflow

逐步走向：

text 复制代码

企业乃至平台级 Agent Capability Marketplace

下一篇建议继续进入：

Harness Marketplace 剖析系列 - 之 Codex：Custom Agent、Subagent 与多线程执行

重点分析：

text 复制代码

Custom Agent 到底是什么
[agents] 如何注册 Agent Role
独立 Agent config_file 有什么作用
Main Agent 如何选择 Subagent
Subagent 是否拥有独立 Context
AGENTS.md 如何继承
Skill 如何继承
MCP 如何继承
Sandbox 如何覆盖
Subagent 之间如何并行
Thread 与 Subagent 有什么区别
App Worktree 与 Subagent 有什么区别
结果如何回到 Main Agent

这样整个 Codex 系列就会继续从：

text 复制代码

"能力如何被定义和分发"

进入：

text 复制代码

"能力最终由谁执行，以及如何形成真正的多 Agent Harness"

Harness Marketplace 剖析系列 - 之 Codex：Plugin、Marketplace 与通用插件目录

Plugin

一、Codex Plugin 到底是什么

1. 从 Skill 到 Plugin

2. 一个 Plugin 可以只有 Skill

3. Plugin 也可以是多个 Skill 的集合

4. Plugin 还可以把 Workflow 和 Tool 组合起来

二、一个 Codex Plugin 在磁盘上长什么样

1. .codex-plugin/plugin.json：Plugin Manifest

2. Plugin Manifest 与 Skill Frontmatter 的职责不同

3. skills/：Plugin 内的 Workflow 集合

4. .app.json：App / Connector 映射层

5. .mcp.json：直接 MCP 配置

6. assets/：Plugin 展示与工作流资源

三、Marketplace 如何把 Plugin 组织起来

1. Marketplace 本质是 Catalog

2. Repo Marketplace

3. Personal Marketplace

4. Marketplace 不一定是本地目录

5. Marketplace 生命周期已经有独立 CLI

四、Universal Plugin Directory：从本地 Catalog 到统一能力市场

Universal Plugin Directory

1. Plugin Directory 的三个主要来源

2. Workspace Plugin 不是 Public Plugin

3. Workspace Admin 可以关闭 Plugin Sharing

五、Plugin 安装后如何进入 Codex Runtime

1. 安装并不等于当前 Session 立即拥有能力

2. Codex CLI 有独立 Plugin Browser

3. Plugin 中的 Skill 如何进入 Codex

4. Plugin Skill 仍然遵守 Skill 的 Progressive Disclosure

5. MCP / Connector 如何进入 Tool Runtime

6. Plugin 不会突破 Codex 自己的 Sandbox

六、Plugin 如何跨 ChatGPT 与 Codex 复用

1. 同一个 Plugin 可以服务不同 Surface

2. ChatGPT 使用 @

3. Codex Skill 使用 $

4. "一次发布，多个 Surface 发现"

七、Plugin Directory 与 App Directory 的演进

八、Plugin 与 App / MCP 的权限边界

九、一个完整 Plugin 案例

十、Codex Plugin 的安装和存储边界

十一、一个当前文档中的 Surface 差异

十二、从 Plugin 看 Codex 的整体扩展架构

1. AGENTS.md：长期指导层

2. Skill：Workflow 层

3. App / MCP：Capability 层

4. Plugin：Packaging 层

5. Marketplace：Catalog 层

6. Universal Plugin Directory：生态分发层

十三、Codex Plugin 设计的几个关键优点

1. Workflow 与 Distribution 解耦

2. Tool 与 Workflow 可以一起交付

3. Plugin 可以跨产品

4. 支持从个人到企业逐级扩展

5. 企业治理边界更加明确

十四、Codex Plugin 当前仍存在的几个局限

1. Runtime 内部 Loader 仍未完全公开

2. Plugin 与 Skill 同名冲突规则需要进一步验证

3. 多 Surface 支持存在版本差异

4. Plugin 依赖 App 后，治理复杂度明显增加

十五、对自研 Harness Marketplace 的启发

1. SkillDescriptor

2. PluginDescriptor

3. MarketplaceDescriptor

4. 清晰拆成三层 Registry

5. Runtime 不直接依赖 Marketplace

6. Plugin 安装应生成不可变 Runtime Snapshot

总结

Harness Marketplace 剖析系列 - 之 Codex：Custom Agent、Subagent 与多线程执行

1. `.codex-plugin/plugin.json`：Plugin Manifest

3. `skills/`：Plugin 内的 Workflow 集合

4. `.app.json`：App / Connector 映射层

5. `.mcp.json`：直接 MCP 配置

6. `assets/`：Plugin 展示与工作流资源

2. ChatGPT 使用 `@`

3. Codex Skill 使用 `$`