01-插件系统架构

插件系统架构

学习目标

本章将带你深入理解 Claude Code 的插件系统架构，通过官方仓库中 14 个插件的实际案例，掌握：

约定优于配置的组件自动发现机制在 Claude Code 中的具体落地
四类核心组件（Commands、Agents、Skills、Hooks）在 Claude Code 中的设计模式
多插件市场清单（marketplace.json）的组织方式
插件的权限约束和工具隔离策略

前置知识

本章涉及插件系统的通用原理，建议先阅读：

插件系统架构与组件发现

下文假设你已理解插件系统的基础概念，直接聚焦 Claude Code 的具体实现。

项目实践

仓库定位

Claude Code 的 GitHub 仓库并非 CLI 源码仓库（CLI 本身闭源），而是一个插件市场与配置仓库。所有插件位于 plugins/ 目录下，包含 14 个官方插件：

插件	作者	组件	用途
`agent-sdk-dev`	Ashwin Bhat	1 Command + 2 Agents	Agent SDK 开发工具链
`claude-opus-4-5-migration`	William Hu	1 Skill	模型版本迁移
`code-review`	Boris Cherny	1 Command + 5 Agents	PR 自动化代码审查
`commit-commands`	Anthropic	3 Commands	git 工作流自动化
`explanatory-output-style`	Dickson Tsai	1 Hook (SessionStart)	教育性输出风格
`feature-dev`	Sid Bidasaria	1 Command + 3 Agents	7 阶段功能开发
`frontend-design`	Prithvi Rajasekaran	1 Skill	前端界面生成
`hookify`	Daisy Hollman	4 Commands + 1 Agent + 1 Skill + 4 Hooks	Hook 规则管理
`learning-output-style`	Boris Cherny	1 Hook (SessionStart)	交互式学习模式
`plugin-dev`	Daisy Hollman	1 Command + 3 Agents + 7 Skills	插件开发全生命周期
`pr-review-toolkit`	Anthropic	1 Command + 6 Agents	PR 专项审查工具包
`ralph-wiggum`	Daisy Hollman	3 Commands + 1 Hook (Stop)	迭代循环开发
`security-guidance`	David Dworken	1 Hook (PreToolUse)	安全模式监控

市场清单格式

根目录的 .claude-plugin/marketplace.json 声明了所有捆绑插件：

{
  "name": "claude-code-plugins",
  "version": "1.0.0",
  "plugins": [
    {
      "name": "feature-dev",
      "source": "./plugins/feature-dev",
      "category": "development"
    }
  ]
}

每个插件通过 source 字段指向本地相对路径，通过 category 分类（development / productivity / learning / security）。

目录约定实战

以 feature-dev 插件为例，展示约定优于配置的发现机制：

plugins/feature-dev/
├── .claude-plugin/
│   └── plugin.json          # 仅元数据：name, version, description, author
├── agents/
│   ├── code-architect.md     # → Agent: code-architect
│   ├── code-explorer.md      # → Agent: code-explorer
│   └── code-reviewer.md      # → Agent: code-reviewer
├── commands/
│   └── feature-dev.md        # → Command: /feature-dev
└── README.md                 # 人类可读文档

plugin.json 中没有声明 agents 或 commands 列表。Claude Code 通过扫描 agents/ 和 commands/ 目录自动发现组件。

Agent Frontmatter 协议

所有 Agent .md 文件使用统一的 YAML frontmatter：

---
name: code-explorer
description: Deeply analyzes existing codebase features...
tools: Glob, Grep, LS, Read, NotebookRead, WebFetch, TodoWrite, WebSearch, KillShell, BashOutput
model: sonnet
color: yellow
---

关键设计点：

tools 为只读集合：三个分析 Agent 均不包含 Write、Edit、Bash 等写入工具，确保分析 ≠ 实现
model 路由：重度分析用 sonnet，审查用 opus，轻量任务用 inherit
color 分类：yellow（探索）、green（架构/正向）、red（告警/审查）、cyan（测试）、magenta（SDK）、pink（类型设计）

Command Frontmatter 协议

Command 的 frontmatter 定义命令的元数据和权限约束：

---
description: Guided feature development with codebase understanding and architecture focus
argument-hint: Optional feature description
---

与 Agent 不同，Command 通常不声明 model 和 tools，使用默认值（Opus 模型，完整工具集）。

权限约束实践

ralph-wiggum 插件展示了精确的工具权限控制：

---
description: "Start Ralph Wiggum loop in current session"
allowed-tools: ["Bash(${CLAUDE_PLUGIN_ROOT}/scripts/setup-ralph-loop.sh:*)"]
hide-from-slash-command-tool: "true"
---

allowed-tools 使用精确路径匹配语法，仅允许执行插件内的特定脚本，防止命令被滥用于其他 Bash 操作。

多组件协作：hookify 案例

hookify 是组件最丰富的插件（4 Commands + 1 Agent + 1 Skill + 4 Hooks），展示了多组件协作模式：

陷阱与对策

陷阱	表现	对策
插件名称与目录名不匹配	插件无法被发现	确保 `.claude-plugin/plugin.json` 中的 `name` 与目录名一致
组件发现遗漏	`commands/` 下放了非 `.md` 文件	只有 `.md` 文件会被自动发现为命令
重叠路径导致重复计数	统计显示组件数量翻倍	CHANGELOG v2.1.147 已修复此 bug，但仍应避免 `plugin.json` 声明与实际目录重叠
`allowed-tools` 过宽	命令拥有超出需要的权限	使用精确路径匹配，如 `Bash(${CLAUDE_PLUGIN_ROOT}/scripts/:)`

设计取舍

为什么插件用 Markdown 定义而非 JSON/YAML？

Agent 的系统提示本质上是自然语言指令。用 Markdown 定义，人类可以直接阅读和编辑，模型也可以直接理解其中的指令。如果用 JSON，系统提示需要转义和结构化，降低可读性。

为什么 plugin.json 不声明组件列表？

避免清单文件与实际文件不同步。以文件系统为准（Single Source of Truth），减少维护负担。新增组件只需添加文件，不需要同时修改清单。

代价：缺少编译期检查，格式错误只能在运行时发现。为此 plugin-dev 插件提供了 plugin-validator Agent 进行事后验证。

参考来源

Claude Code Plugins 文档
Claude Code Plugin Development 文档
源码: plugins/ 目录下 14 个插件的全部组件定义

版本信息

📅 2026-05-24 🏷️ v2.1.150 🔀 39e853e