ECC 插件与市场完全指南：从 Marketplace 安装到仓库级插件清单深度解析-平芜编程栈

ECC 插件与市场完全指南：从 Marketplace 安装到仓库级插件清单深度解析

【免费下载链接】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

本指南以 docs/ja-JP/plugins/README.md（对应英文原版 plugins/README.md）为骨架，系统讲解 Claude Code 插件市场的添加、插件的安装与管理，并延伸到 ECC 仓库自身的插件化形态——包括 Codex 原生插件清单、插件配置 Schema 与测试约束。读完本文，你将掌握完整的插件安装链路，理解~/.claude/plugins/目录的每一个文件职责，并能在 ECC 仓库中读懂一套真实可安装的插件清单。

一、什么是插件与市场

插件（Plugin）用于扩展 Claude Code 的功能，为其注入新的工具与能力。而市场（Marketplace）本质上是可安装插件的仓库（repository）：一个市场通常对应一个 Git 仓库，仓库内以固定目录结构声明可供安装的插件清单与版本信息。

本指南只覆盖"如何安装"，关于"何时以及为何使用插件"的选型讨论不属于本文范围；本文聚焦命令、目录与清单的可操作细节。

二、添加市场（Marketplace）

2.1 添加命令

使用claude plugin marketplace add命令，后接市场仓库的 URL：

# 添加官方 Anthropic 市场 claude plugin marketplace add https://github.com/anthropics/claude-plugins-official # 添加社区市场（mgrep 插件，作者 @mixedbread-ai） claude plugin marketplace add https://github.com/mixedbread-ai/mgrep

命令执行后，该市场会被登记到本地的known_marketplaces.json中（详见后文"插件文件位置"一节），市场本身的数据则缓存在marketplaces/目录中，用于后续解析可安装的插件列表。

2.2 推荐市场

市场	来源
claude-plugins-official	`anthropics/claude-plugins-official`
claude-code-plugins	`anthropics/claude-code`
Mixedbread-Grep	`mixedbread-ai/mgrep`

claude-plugins-official：Anthropic 官方插件市场，是typescript-lsp、pyright-lsp等官方插件的主要来源。
claude-code-plugins：来自 Claude Code 主仓库的插件集合。
Mixedbread-Grep：社区市场，提供mgrep增强搜索插件。

三、安装插件

3.1 两种安装方式

# 方式一：打开插件浏览器，交互式浏览并安装 /plugins # 方式二：直接指定插件名与所属市场安装 claude plugin install typescript-lsp@claude-plugins-official

/plugins是 Claude Code 内置的斜杠命令，会打开插件浏览器界面；而claude plugin install <插件名>@<市场名>则以"插件@市场"的语法精准定位某个市场中的某个插件，适合脚本化与批量安装。

3.2 推荐插件清单

开发类：

typescript-lsp- TypeScript 智能支持
pyright-lsp- Python 类型检查
hookify- 通过对话交互式创建钩子（hooks）
code-simplifier- 代码重构

代码质量类：

code-review- 代码审查
pr-review-toolkit- PR 自动化
security-guidance- 安全检查

搜索类：

mgrep- 增强搜索（提供优于 ripgrep 的检索能力）
context7- 实时文档查找（live documentation lookup）

工作流类：

commit-commands- Git 工作流
frontend-patterns- UI 模式
feature-dev- 功能开发

值得注意的是，ECC 仓库中的许多能力与上述插件目录一一对应：仓库的commands/目录下就有 hookify.md、code-review.md、feature-dev.md 等命令，skills/目录下同样存在hookify-rules、frontend-patterns、feature-dev等技能目录，可作为这些插件功能的仓库内参考实现。

四、快速设置

如果需要从零开始配置一套可用的插件环境，只需三步：

# 1. 添加官方市场 claude plugin marketplace add https://github.com/anthropics/claude-plugins-official # 2. 添加社区市场（mgrep 插件，作者 @mixedbread-ai） claude plugin marketplace add https://github.com/mixedbread-ai/mgrep # 3. 打开 /plugins，按需安装

这是原文推荐的"最短路径"：先登记两个市场，再通过/plugins浏览器可视化挑选安装，无需记忆插件名与市场的对应关系。

五、插件文件的存放位置

插件安装后，所有状态都落在用户主目录下的~/.claude/plugins/目录中，其结构如下：

~/.claude/plugins/ |-- cache/ # 已下载的插件 |-- installed_plugins.json # 已安装插件列表 |-- known_marketplaces.json # 已添加的市场 |-- marketplaces/ # 市场数据

路径	职责
`cache/`	插件被下载后的实体内容，是插件运行时的真实代码来源
`installed_plugins.json`	记录当前已安装插件及其版本、来源市场的清单文件
`known_marketplaces.json`	记录通过`marketplace add`登记过的所有市场
`marketplaces/`	市场本身的元数据快照，用于离线解析可安装插件

理解这四类文件的分工很有价值：marketplace add只写入known_marketplaces.json与marketplaces/；plugin install才会把插件内容拉入cache/并更新installed_plugins.json。清理或排障时，可以据此精准定位问题环节。

六、仓库源码纵深：ECC 自身的插件化形态

除了消费第三方插件，ECC 仓库本身也是一个可安装的插件/技能包。仓库根部存在.codex-plugin/目录与.agents/plugins/marketplace.json，分别对应 Codex 原生插件与市场发现入口。下面结合真实文件展开。

6.1 Codex 原生插件清单`.codex-plugin/plugin.json`

.codex-plugin/plugin.json 是 ECC 作为 Codex 原生插件时的清单，字段覆盖身份信息、内容引用与界面呈现：

{ "name": "ecc", "version": "2.2.1", "description": "Harness-native ECC workflows for Codex: shared skills, production-ready MCP configs, and selective-install-aligned conventions...", "author": { "name": "Affaan Mustafa" }, "license": "MIT", "skills": "./skills/", "mcpServers": "./.mcp.json", "hooks": "./hooks/codex-hooks.json", "interface": { "displayName": "ECC", "composerIcon": "./assets/ecc-icon.svg", "logo": "./assets/hero.png" } }

关键字段的含义如下：

skills：指向仓库根部的skills/目录（300+ 个技能目录），是插件内容的主体；
mcpServers：引用插件根部的 .mcp.json MCP 服务配置；
hooks：引用 hooks/codex-hooks.json，即 Codex 兼容的生命周期钩子投影；
interface：包含composerIcon、logo等品牌资源路径，指向assets/目录。

注意这里使用的是相对路径引用，且引用的是仓库根部内容。这正是 plugins/ecc/README.md 中强调的要点：ECC 的市场入口指向仓库根目录（self-contained repository root），Codex 安装时会连同所有被引用的运行时内容一起复制进缓存；而plugins/ecc/薄目录只是遗留兼容产物，其中基于父级相对路径的引用在安装后会逃逸出隔离的插件缓存，因此不应再把活跃市场指回该薄目录。

6.2 插件配置的 Schema 约束

仓库在 schemas/plugin.schema.json 中定义了一套完整的插件配置 JSON Schema，可作为插件清单字段的权威参考：

name：必填，插件名；
version：要求符合语义化版本^[0-9]+\.[0-9]+\.[0-9]+(?:-[0-9A-Za-z.-]+)?$；
author：可为字符串，也可为含name与url的对象；
skills/commands：声明插件携带的技能与命令（字符串数组）；
mcpServers：MCP 服务配置，支持字符串、数组或对象三种形态；
features：能力声明对象，可细分为agents、commands、skills、configAssets、hookEvents、customTools等子字段，其中agents/commands/skills为非负整数，configAssets为布尔值。

该 Schema 与仓库的 schemas/plugin.schema.json 命名空间下的其他 Schema（如hooks.schema.json、install-components.schema.json）共同构成 ECC 的插件配置体系。

6.3 清单一致性由测试强制保证

.codex-plugin/README.md 明确要求.codex-plugin/plugin.json与plugins/ecc/旧清单中的name、version保持同步，而 tests/plugin-manifest.test.js 正是这一约束的自动化执行者——测试同时校验.claude-plugin/plugin.json、.codex-plugin/plugin.json、.mcp.json与.agents/plugins/marketplace.json四份清单。也就是说，插件的元数据正确性不再是文档承诺，而是可以运行node tests/run-all.js直接验证的工程事实。

七、Codex 原生插件路径：与 Claude 插件命令的对应

Claude 侧使用claude plugin marketplace add与claude plugin install；在 Codex 0.146.0 及更新版本中，命令形态有所不同：

# 添加 ECC 仓库作为市场 codex plugin marketplace add affaan-m/ECC # 安装原生插件（使用短 slug 注册） codex plugin add ecc@ecc # 验证注册状态 codex plugin list --json

几个值得注意的实操要点（来自 .codex-plugin/README.md）：

幂等性：重复执行marketplace add会报告alreadyAdded: true，重复plugin add不会产生重复注册，可安全重跑；
更新市场快照：应用新版本前执行codex plugin marketplace upgrade ecc后再codex plugin add ecc@ecc；
本地开发：市场地址支持绝对路径，即codex plugin marketplace add /absolute/path/to/ECC；
安装后验证：codex plugin list只证明注册存在，不足以证明运行时能加载引用的技能与资源。从 ECC 检出目录运行node scripts/codex/check-plugin-cache.js，该检查会扫描CODEX_HOME（通常为~/.codex）下的安装缓存，一旦.codex-plugin/plugin.json引用的文件未被打入缓存即判定失败；
钩子信任独立于插件启用：Codex 原生插件不会静默授权命令，需在新会话中打开/hooks审阅并信任 ECC 钩子定义，信任状态按定义哈希记录，钩子变更后需重新审阅；插件启停走/plugins，钩子信任走/hooks，两者是独立控制；
安装范围：Codex 原生插件不使用 Claude 的user/project/local安装作用域，启用状态一次性存储在激活的CODEX_HOME中，对该 home 下的所有 Codex 会话生效。

与此对照，仓库中保留的bash scripts/sync-ecc-to-codex.sh属已弃用的传统托管同步路径，它把文件合并进~/.codex而非创建市场注册，仅在明确需要复制式配置层时才应使用，并可用ecc uninstall --legacy-codex-sync显式清理（先加--dry-run预览）。

八、ECC 插件内容概览：技能、MCP 与钩子

结合 .codex-plugin/README.md 与仓库目录，ECC 插件打包了三类运行时内容：

1. 技能（Skills）：仓库根部的 skills/ 目录是 Codex 插件包的唯一事实来源，包含 TDD 工作流（tdd-workflow）、安全审查（security-review）、代码审查（code-review）、架构决策、自动化运维等大量可复用技能。仓库实行"不重复"策略，plugins/ecc/薄目录内不复制任何技能或 MCP 内容。

2. MCP 服务：插件默认附带chrome-devtoolsMCP 服务（通过 Chrome DevTools 协议提供交互式浏览器调试、性能轨迹、控制台与网络检查）。原先默认的github、context7、exa、memory、playwright、sequential-thinking等在 2026 年 6 月的连接器审计中被退役，其职责由技能包装的 CLI/REST API 或 harness 原生特性覆盖，但仍作为可选条目保留在 mcp-configs/mcp-servers.json 中。MCP 凭据从启动环境的环境变量继承，清单本身不覆盖~/.codex/config.toml的设置。

3. 钩子（Hooks）：Codex 清单通过hooks字段捆绑hooks/codex-hooks.json，提供SessionStart等同步命令钩子。该投影针对 Codex 的钩子协议做了裁剪——阻塞工具、使用不受支持事件、异步运行或不符合 Codex 钩子协议的处理器不会被放进原生包。

安装完成后，即可在 Codex 会话中通过$configure-ecc触发 ECC 的引导式配置技能，插件再次安装是幂等的，不会产生第二个作用域或重复钩子注册。

九、总结

从 Claude Code 的claude plugin marketplace add/claude plugin install，到 Codex 的codex plugin marketplace add/codex plugin add，插件体系的完整链路是：登记市场 → 浏览/安装插件 → 落盘到~/.claude/plugins/（或~/.codex缓存）→ 通过installed_plugins.json/known_marketplaces.json持久化状态。

ECC 仓库本身即是这套体系的一个完整样例：.codex-plugin/plugin.json展示了清单字段的标准写法，schemas/plugin.schema.json 给出了字段约束，tests/plugin-manifest.test.js 保证了多份清单的一致性与可验证性，scripts/codex/check-plugin-cache.js 则提供了安装后"引用完整性"的兜底检查。对照阅读本文与这些文件，你既能熟练安装第三方插件，也能自己读懂并校验一个插件仓库的工程细节。

创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考

ECC 插件与市场完全指南：从 Marketplace 安装到仓库级插件清单深度解析