插件与 Skills

Codex 的插件系统不是只提供一个工具列表。插件可以贡献 skills、MCP servers、apps、hooks 和 UI/模型可见 metadata。Skills 则是可按需注入的任务工作流说明。

插件与 Skills

Plugin Manifest

基础 manifest 类型在 codex-rs/plugin/src/manifest.rs：

  • name
  • version
  • description
  • keywords
  • paths.skills
  • paths.mcp_servers
  • paths.apps
  • paths.hooks
  • interface

加载和校验在 codex-rs/core-plugins/src/manifest.rs。它支持：

  • skills 路径为单个 path 或 path list。
  • MCP servers 为 path 或 inline object。
  • hooks 为 path、path list、inline object 或 inline list。
  • interface 里声明 display name、description、capabilities、brand color、logo、screenshots、default prompt 等。

路径解析要求资源在 plugin root 下，避免 manifest 随意引用外部路径。

PluginsManager

ThreadManager::new 会创建 PluginsManager，并把它交给 McpManager、skills 注入和工具推荐逻辑。核心流程里常见调用：

  • plugins_for_config
  • effective_apps
  • effective_plugin_skill_roots
  • plugin_skill_snapshots_for_config

Skill 加载与注入

skills 的核心在 codex-rs/core-skills 和 codex-rs/core/src/skills.rs。

一次 turn 中，build_skills_and_plugins 会：

  1. 读取当前配置下的 plugin 和 skill snapshot。
  2. 从用户输入里收集显式 skill mention。
  3. 结合 connectors，避免 skill 名和 app slug 冲突。
  4. 必要时提示安装 MCP 依赖。
  5. 调用 build_skill_injections 生成模型可见 instruction。
  6. 把 skill instruction 作为 ContextualUserFragment 记录进 history。

这说明 Skill 不是“总是塞进 prompt”，而是按显式 mention 和配置动态注入。

Plugin mention

用户输入中的 plugin mention 会被解析为 turn-scoped guidance。Codex 会从当前启用插件和 MCP/app inventory 中构建关于插件能力的上下文，让模型知道当前插件具体能做什么。

Apps 与 Connectors

当 apps enabled 时，Codex 会把插件声明的 apps 与 MCP 里可访问 connector 合并，并通过配置里的 app tool policy 控制具体工具是否可用。

相关源码：

  • codex-rs/core/src/connectors.rs
  • codex-rs/core/src/mcp_tool_exposure.rs
  • codex-rs/core-plugins/src/app_mcp_routing.rs

可学习的设计

插件和 skills 的关键点是分层：

  • 插件是 bundle：资源、manifest、MCP、hooks、apps、skills。
  • Skill 是模型工作流说明：按需注入，不等同于工具。
  • MCP server 是 live capability：通过工具协议真正执行外部动作。
  • Hook 是生命周期策略：可以管控输入、工具、权限和压缩等流程。

这种分层让“给模型说明”和“给模型工具”不会混在一起。