第 8 章 · 01 四要素与目录结构

第 8 章 · 01 四要素与目录结构

本节摘要:插件的本质是捆绑:把斜杠命令、子代理、MCP 服务器、Hooks 四要素装进一个目录,配上一份 manifest,用户一条命令装好整套工作流。目录结构有固定约定(commands/、agents/、skills/、hooks/、.mcp.json 等),manifest 声明身份与元数据。插件还能带 LSP 语言服务器、把 bin/ 加进 PATH、声明用户可配选项、持有跨会话持久数据、注册背景监视器。先看清"什么时候该用插件",再动手搭。

学习目标

阅读完本节,你应当能够:

1. 说出插件四要素与各自所在目录,画出插件目录结构。
2. 写出最小 plugin.json manifest 并解释每个字段。
3. 说出 LSP、bin/、userConfig、CLAUDE_PLUGIN_DATA、monitors、inline 插件各自解决什么问题。
4. 用"插件 vs 独立功能"决策矩阵判断该不该做成插件。

一、插件是什么:扩展能力的"分发单元"

第 2、4、6、7 章分别讲了斜杠命令、子代理、MCP、Hooks——它们是单点能力。插件把这些能力打包成可安装的分发单元:

Plugin
├── Slash Commands   ← 命令入口
├── Subagents        ← 角色分工
├── MCP Servers      ← 外部连接
├── Hooks            ← 自动化守门
└── Configuration    ← 默认配置
​

一条命令安装(/plugin install pr-review),所有组件自动配置好。这是它相对手工配置的核心价值:可分发、可版本化、可精确复现——团队每个人装的都是同一套。

插件 vs 独立功能

决策规则:需要多个组件组合 → 做插件;团队共享 → 做插件;需要自动配置 → 做插件。单个快捷任务用命令,单一领域专长用技能,专项分析用子代理,实时数据用 MCP——别拿大炮打蚊子。

二、目录结构:标准布局

my-plugin/
├── .claude-plugin/
│   └── plugin.json       # 清单:name/description/version/author
├── commands/             # 斜杠命令(Markdown 文件,可嵌套 workflows/)
├── agents/               # 子代理定义
├── skills/               # 技能(SKILL.md 文件)
├── hooks/                # hooks.json 事件处理器
├── .mcp.json             # MCP 服务器配置
├── .lsp.json             # LSP 语言服务器配置
├── bin/                  # 可执行文件,插件启用时加入 PATH
├── settings.json         # 默认设置(目前仅支持 agent 键)
├── themes/               # 自定义主题(v2.1.118+)
├── templates/            # 模板(issue 模板等)
├── scripts/              # 辅助脚本
├── docs/                 # 文档
└── tests/                # 测试
​

三、manifest:插件的身份证

.claude-plugin/plugin.json 声明插件身份:

{
  "name": "my-first-plugin",
  "description": "A greeting plugin",
  "version": "1.0.0",
  "author": { "name": "Your Name" },
  "homepage": "https://example.com",
  "repository": "https://github.com/user/repo",
  "license": "MIT"
}
​

最小必备:name(kebab-case)、description、version(semver)、author。这是市场展示、依赖解析与版本锁定的依据。

四、扩展部件:插件里还能装什么

LSP 语言服务器

插件可以带 Language Server Protocol 支持,提供实时诊断、跳转定义、悬停信息、符号列表。配置在插件根的 .lsp.json 或 plugin.json 的 lsp 键,按语言注册:

{
  "python": {
    "command": "pyright-langserver",
    "args": ["--stdio"],
    "extensionToLanguage": { ".py": "python", ".pyi": "python" }
  }
}
​

必填 command(须在 PATH 中)与 extensionToLanguage(扩展名→语言 ID);可选 args/transport(stdio 默认或 socket)/env/initializationOptions/settings/startupTimeout/restartOnCrash 等。官方市场已有 pyright-lsp、typescript-lsp、rust-lsp 预配置插件。

bin/ 目录加入 PATH

插件启用时,其 bin/ 目录被前置到会话 PATH,里面的可执行文件可直接按名调用:

# 插件内:bin/my-tool(记得 chmod +x,git 会保留可执行位)
$ my-tool --help   # 会话内直接调用,无需路径
​

适合给插件内的钩子、技能、命令做 CLI 帮手。

userConfig:用户可配选项

manifest 里用 userConfig 声明可配置项,sensitive: true 的值存入系统钥匙串而不是明文设置文件:

{
  "name": "my-plugin",
  "version": "1.0.0",
  "userConfig": {
    "apiKey": { "description": "API key for the service", "sensitive": true },
    "region": { "description": "Deployment region", "default": "us-east-1" }
  }
}
​

$:持久数据目录

每个插件拥有独立的持久状态目录(安装时自动创建,卸载时清理),跨会话存活,适合缓存与数据库:

{ "hooks": { "PostToolUse": [{ "command": "node ${CLAUDE_PLUGIN_DATA}/track-usage.js" }] } }
​

背景监视器(v2.1.105+)

manifest 顶层 monitors 可注册背景监视器:trigger 为 session_start(会话开始自动布防)或 skill_invoke(技能被调用时布防),底层复用 Monitor 工具,把 stdout 行流式转成 Claude 可响应的事件:

{
  "name": "my-plugin",
  "version": "1.0.0",
  "monitors": [{ "command": "tail -f /var/log/app.log", "trigger": "session_start" }]
}
​

inline 插件与零市场启动

插件可以内联定义在 settings 文件里(source: "settings"),无需独立仓库;也可以直接放进 .claude/skills 目录免市场自动加载(v2.1.157+,claude plugin init <name> 可脚手架)。另外几个值得知道的形态:根级放 SKILL.md 且无 skills/ 目录时,插件本身就是一个技能(v2.1.142+);plugin.json 的 skills 条目不再隐藏默认 skills/ 目录,两处声明会合并(v2.1.136+);插件斜杠命令支持空格调用 /myplugin review 等价于 /myplugin:review(冒号形式是规范写法,v2.1.136+)。

五、settings.json:默认配置

插件可带 settings.json 提供默认设置,目前支持 agent 键(设置主线程代理):

{ "agent": "agents/specialist-1.md" }
​

安装时应用默认值,用户可在项目/用户配置里覆盖。

小结

插件 = 四要素(命令/代理/MCP/钩子) + manifest + 标准目录。扩展部件丰富:可带 LSP 实时补全、bin/ 注入 PATH、钥匙串级 userConfig、跨会话持久数据目录、背景监视器、inline 免市场加载。判断标准:多组件、要共享、需自动配置 → 插件;否则用更轻的独立能力。下一节讲怎么把插件分发出去——市场机制。

下一节预告:第 2 节讲市场(marketplace)机制、六种来源语法与完整生命周期。