企业官网建设流程全解析

ECC Codex Native Plugin：plugin.json 清单、安装命令、Hooks 与 MCP 配置的完整解析

【免费下载链接】ECCThe agent harness performance optimization system. Skills, instincts, memory, security, and research-first development for Claude Code, Codex, Opencode, Cursor and beyond.项目地址: https://gitcode.com/GitHub_Trending/ev/ECC

本篇基于 ECC 仓库中的 .codex-plugin/README.md 展开，系统讲解 ECC 如何以 Codex 原生插件的形式被安装与运行：包括plugin.json清单各字段的实际取值、codex plugin系列命令的完整安装与升级流程、SessionStart生命周期 Hook 的投影机制、默认 MCP 服务器为何只剩chrome-devtools一个，以及如何用仓库自带脚本校验已安装缓存。读完本文，你可以独立完成 ECC 在 Codex 0.146+ 上的原生插件安装、Hook 信任配置与安装后验证。

插件包由哪些文件构成

Codex 原生插件的入口是 .codex-plugin/plugin.json 清单文件。仓库中该目录只包含README.md与plugin.json两个文件——这是一个刻意的“瘦目录”设计：清单中所有运行时内容都指向仓库根目录下的文件。清单当前版本为2.2.1（与 VERSION 及package.json中的版本一致），核心字段如下：

其中defaultPrompt预置了三条典型用法：“使用 tdd-workflow 技能先写测试再实现”“使用 security-review 技能扫描 OWASP Top 10”“使用 verification-loop 技能在交付前验证正确性”，体现了 ECC “技能优先（skills-first）”的工作面定位。

清单的三层内容各自有明确落点：

• 技能：skills/ 是唯一的技能源，当前仓库中该目录实际包含 286 个子目录（清单与 README 文案标注为 281，随技能持续入库会增长），README 明确要求不要在.codex-plugin/内复制技能内容，以避免双份维护；
• MCP：.mcp.json 目前只定义了一个服务器；
• Hooks：hooks/codex-hooks.json 是一份“provider 特定投影”，只收录能通过 Codex Hook 协议校验的处理器。

安装流程：marketplace add + plugin add

Codex 0.146.0 起使用plugin add替代旧的plugin install。标准安装三步为：

codex plugin marketplace add affaan-m/ECC codex plugin add ecc@ecc codex plugin list --json

第一条命令把 ECC 仓库登记为 Codex 的市场来源，第二条以插件@市场语法安装原生插件，第三条以 JSON 输出核对注册结果。两条 add 命令都是幂等的：重复执行 marketplace add 会报告alreadyAdded: true，重复执行 plugin add 会保留同一个已启用的插件注册，不会产生第二个作用域或重复的 Hook 注册。

应用新的 ECC 版本前，先拉取更新的市场快照再安装：

codex plugin marketplace upgrade ecc codex plugin add ecc@ecc

本地开发场景下，marketplace add 可以直接接受 checkout 路径：

codex plugin marketplace add /absolute/path/to/ECC codex plugin add ecc@ecc

为什么市场入口必须指向仓库根目录：Codex 会把选中的插件源整体拷贝进自己的缓存，仓库根作为入口才能让skills/、.mcp.json、hooks/、Hook 脚本与展示资源保持在一起。README 特别指出，如果用一个“瘦插件目录”作为入口、再以父级相对路径（../）引用运行时内容，这些引用会逃逸出缓存边界，导致安装注册成功但运行期文件缺失——后文的缓存检查脚本正是为拦截这种故障而存在的。

安装完成后需重启 Codex。也可以进入 Codex CLI 的/plugins面板检查、启用、禁用或移除插件。与 Claude 不同，原生 Codex 插件不使用user、project、local三种安装作用域：其启用状态一次性保存在当前激活的CODEX_HOME（通常为~/.codex）中，对使用该 home 的所有 Codex 会话生效。

Hooks：SessionStart 同步投影与信任机制

ECC 的 Claude Hook 配置是一套较丰富的异步体系，但 Codex 原生插件只投影其中已对 Codex 0.146 验证过的同步部分。当前 hooks/codex-hooks.json 只定义了一个 Hook：

{ "hooks": { "SessionStart": [{ "matcher": ".*", "hooks": [{ "type": "command", "command": "node -e \"...\" node scripts/hooks/session-start-bootstrap.js" }], "description": "Load previous context and detect package manager on new session", "id": "session:start" }] } }

这个SessionStartHook 在每次新会话启动时同步执行，职责是加载上一次会话留下的上下文并检测项目使用的包管理器。其命令是一个内联的node -e引导器：先校验 Codex 注入的PLUGIN_ROOT环境变量存在，将其映射为CLAUDE_PLUGIN_ROOT，再解析出 ECC 插件根目录，最终调用scripts/hooks/session-start-bootstrap.js。该引导器的设计动机可以追溯到仓库内 scripts/hooks/session-start-bootstrap.js 头部注释：早期把逻辑直接内联在hooks.json字符串里时，!等字符会触发 shell 历史展开，引发SessionStart:startup hook error；独立文件化后 shell 不再接触 JavaScript 源码，行为保持一致（读取 stdin 的 JSON 事件 → 解析插件根 → 经run-with-flags.js做 Hook profile 门控后执行session-start.js）。

README 同时划清了边界：Claude 的 Hook profile 不是 Codex Hook profile——会阻断工具、使用不受支持事件、异步执行或不满足 Codex Hook 协议的处理器，都会被排除在原生包之外。

信任模型上有两个独立控制面，不要混淆：

1. /plugins管插件启用——插件装好后是启用状态；
2. /hooks管 Hook 信任——Codex 默认开启 Hook 支持，但原生插件安装不会静默授权命令。需要新开一个 Codex 会话，进入/hooks，审阅并信任 ECC 的 Hook 定义后才可启用。信任是针对每条定义哈希记录的，Hook 内容一旦变更就需要重新审阅。

当缓存中的技能可用后，可在 Codex 内直接调用$configure-ecc进入 ECC 的引导式配置流程。

MCP 服务器：为什么默认只剩 chrome-devtools

.mcp.json 当前内容只有一个条目：

{ "mcpServers": { "chrome-devtools": { "command": "npx", "args": ["-y", "chrome-devtools-mcp@latest"] } } }

chrome-devtools提供交互式浏览器调试：CDP 会话、性能 trace、控制台与网络检查。此前的六个默认连接器github、context7、exa、memory、playwright、sequential-thinking在 2026 年 6 月的连接器审计中被退役，其职能改由“技能包 CLI/REST API”或 harness 原生能力承担，但全部保留为 mcp-configs/mcp-servers.json 中的可选项。退役的具体裁定记录在 docs/MCP-CONNECTOR-POLICY.md，摘要如下：

政策规则是：默认连接器必须同时满足“通用性”与“MCP 优于 CLI 封装”两条，且默认集合保持在 10 个以内（实践上 0–2 个）。mcp-configs/mcp-servers.json中还提供了大量其他可选条目（jira、supabase、evalview、squish等），文件内_comments段说明了使用方式：复制所需服务器到自身的mcpServers配置、替换YOUR_*_HERE占位符、启用数量建议不超过 10 个以保全上下文窗口。

一个重要的继承关系：MCP 服务器的凭据从启动环境（环境变量）继承，插件清单不自行管理密钥。

安装后验证：registration 不等于可运行

codex plugin list只能确认市场注册，不能证明运行期技能可以加载。仓库提供了专门的缓存检查脚本 scripts/codex/check-plugin-cache.js：

node scripts/codex/check-plugin-cache.js

从源码看，它的校验逻辑分三步：

1. 定位缓存目录：默认为$CODEX_HOME（或~/.codex）下的plugins/cache/ecc/ecc/<version>，版本号默认读取package.json（见 check-plugin-cache.js#L107-L119）。支持--codex-home、--plugin-dir、--marketplace、--plugin、--version五个选项覆盖默认值；
2. 读取缓存中的.codex-plugin/plugin.json：若清单缺失，会列出已安装的版本目录并给出修复建议（例如提示先运行codex plugin marketplace add affaan-m/ECC）；
3. 逐一解析清单中的字符串路径引用：skills目录、mcpServers文件、interface.composerIcon、interface.logo，逐项报告[OK]/[FAIL]。特别地，它还会检查引用是否逃逸出缓存边界（相对路径出现..或解析为绝对路径即判失败）——这正是对前文“瘦目录 + 父级相对路径”故障模式的直接防御（见 check-plugin-cache.js#L204-L218）。

检查通过时输出All cached manifest references resolve.；失败时明确提示codex plugin list only confirms marketplace registration; it is not proof of runtime skill loading.，并指回受支持的同步路径。

原生插件 vs 遗留 managed sync

仓库同时保留了一条已弃用的兼容路径：bash scripts/sync-ecc-to-codex.sh（scripts/sync-ecc-to-codex.sh）。它的行为是把文件合并进~/.codex：备份config.toml与AGENTS.md、以标记方式合并 ECC 的 AGENTS.md、从commands/*.md生成提示文件、安装全局 git 安全钩子、把 ECC MCP 服务器合并进config.toml。它不是原生插件安装，不产生任何市场注册。当前 Codex 上应优先使用原生路径；只有刻意需要那套“拷贝配置层”时才走遗留同步。

清理方面，新版同步运行会记录版本化的所有权清单，可用以下命令显式检查与移除该层：

ecc uninstall --legacy-codex-sync --dry-run ecc uninstall --legacy-codex-sync

清理永远不触碰会话历史与原生插件缓存；对清单引入前的老安装采取保守策略，无法确认归属的文件会保留并附带警告。

使用边界与设计约定

README 的 Notes 部分给出了三条长期约定，对日常使用有直接约束力：

• skills/ 是 Codex 插件包的技能唯一事实来源，不要在.codex-plugin/内重复技能内容；
• ECC 正向 skills-first 工作面迁移，遗留的 commands/ 仅为仍期望斜杠命令 shim 的 harness 保留兼容；
• 插件清单不覆盖~/.codex/config.toml中的既有设置——原生插件安装是增量能力注入，而非配置接管。

整体来看，ECC 的 Codex 原生插件遵循一套清晰的分层：plugin.json做声明式引用、仓库根做内容承载、缓存检查脚本做安装后验证、/plugins与/hooks两个面板分别掌管启用与信任。理解这套结构后，无论是排查“技能未加载”（跑缓存检查）还是“Hook 未生效”（查/hooks信任状态），都有了明确的定位路径。

【免费下载链接】ECCThe agent harness performance optimization system. Skills, instincts, memory, security, and research-first development for Claude Code, Codex, Opencode, Cursor and beyond.项目地址: https://gitcode.com/GitHub_Trending/ev/ECC