AI Agent / 系统课时
管理插件与扩展组合
管理插件与扩展组合
当多个项目需要相同的 Skills、子智能体、Hooks 和 MCP 配置时,逐项复制会造成版本漂移。插件把这些组件封装在一个可安装、可升级的目录中,并通过命名空间避免冲突,适合团队共享和受控发布。
学习目标
- 理解插件目录、清单和组件组合关系
- 能创建并验证一个最小插件
- 会控制插件来源、作用域、版本和更新风险
何时从独立配置升级为插件
单项目试验适合放在 .claude/;需要跨项目复用、团队分发和版本管理时再打包为插件。插件可以包含 Skills、agents、Hooks 和 MCP 服务器,Skill 命令通常以 /插件名:技能名 形式出现。:contentReference[oaicite:27]{index=27}

创建最小插件结构
team-quality/
├── .claude-plugin/
│ └── plugin.json
├── skills/
│ └── review/
│ └── SKILL.md
├── agents/
│ └── reviewer.md
└── hooks/
└── hooks.json只有清单放在 .claude-plugin/ 内,Skills、agents 和 Hooks 位于插件根目录的对应子目录。放错层级会导致插件加载但组件缺失。:contentReference[oaicite:28]{index=28}
创建 .claude-plugin/plugin.json:
{
"name": "team-quality",
"displayName": "Team Quality",
"version": "1.0.0",
"description": "团队共享的代码审查 Skill、只读审查员和格式化 Hook"
}如果提供清单,name 是唯一必需字段;实际团队插件还应补充作者、仓库、许可证和兼容说明。版本应随行为变化递增,避免用户无法判断本机加载的是哪一版。
本地验证插件
在插件父目录运行:
claude --plugin-dir ./team-quality预期结果
Claude Code 启动并从 ./team-quality 加载插件;插件组件可在当前会话中使用。修改插件组件后,可在会话中运行 /reload-plugins 重新加载。发布前再执行验证命令:
claude plugin validate ./team-quality --strict预期结果
Plugin validation passed实际措辞可能随版本变化;关键是命令以成功状态结束,且严格模式下没有未知字段、错误类型或目录结构问题。:contentReference[oaicite:29]{index=29}
控制安装作用域与来源
用户作用域适合个人跨项目使用;项目作用域会把启用状态写入 .claude/settings.json,便于团队共享;本地作用域适合当前机器例外。外部插件启用前仍需每个用户安装并信任,项目配置不应静默把任意代码带到成员机器。:contentReference[oaicite:30]{index=30}
只使用受控 marketplace 或固定仓库来源,审查清单、Hooks、MCP 命令和依赖。插件依赖若默认跟随最新版本,上游更新可能改变行为;关键环境应使用经过测试的版本约束,并在升级前运行验证和回归测试。:contentReference[oaicite:31]{index=31}
组合扩展时保持边界清晰
Skill 负责可复用流程,子智能体负责专业角色,Hook 负责确定性事件响应,MCP 负责外部能力。不要让四种组件重复实现同一规则。安全边界应放在权限与托管策略中,插件只声明所需能力;卸载或禁用插件后,项目仍应能以降级方式运行。