第 8 章 · 03 三个示例插件精读

第 8 章 · 03 三个示例插件精读

本节摘要:官方仓库带三个完整示例插件——PR Review、DevOps Automation、Documentation。它们展示了插件的标准协作模式:斜杠命令是入口,子代理是分工,钩子是守门,模板/脚本是标准件。PR Review 演示"审查流水线"(钩子校验 → MCP 取数 → 三个子代理并行审查 → 汇总报告);DevOps 演示"部署全流程"(前后置钩子 + 专用子代理 + 脚本);Documentation 演示"模板驱动生产"(命令扫描 → 子代理提取 → 模板套用 → 生成文档)。

学习目标

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

1. 说出三个示例插件各自的组件构成(命令/代理/MCP/钩子)。
2. 复述 PR Review 的完整审查工作流(7 步)。
3. 说出三个插件的组件协作规律(入口/分工/守门/标准件)。

一、PR Review:审查流水线插件

定位:完整的 PR 审查工作流——安全、测试、文档、质量、性能五维检查。

组件构成:

• 斜杠命令 3 个:/review-pr(综合审查)、/check-security(仅安全)、/check-tests(仅测试覆盖)。
• 子代理 3 个:security-reviewer(漏洞检测)、test-checker(覆盖分析)、performance-analyzer(性能影响评估)。
• MCP:GitHub 集成(拉取 PR 数据)。
• 钩子:pre-review.js(审查前校验 git 仓库)。

完整工作流(7 步):

1. 用户敲 /review-pr
2. pre-review 钩子校验 git 仓库状态
3. GitHub MCP 拉取 PR 数据
4. 委派 security-reviewer 做安全审查
5. 委派 test-checker 核查测试覆盖
6. 委派 performance-analyzer 评估性能
7. 汇总三方结论,输出综合审查报告
​

产出示例:✅ 安全:无关键问题、⚠️ 测试覆盖 65%(建议 80%+)、📝 12 条建议。注意 3 个命令与 3 个代理的对应关系——/check-security 只调 security-reviewer,命令粒度决定审查深度。

二、DevOps Automation:部署全流程插件

定位:部署、回滚、监控、事故响应的一体化 DevOps 工作流。

组件构成:

• 斜杠命令 4 个:/deploy(部署到生产/预发)、/rollback(回滚)、/status(健康检查)、/incident(生产事故处理)。
• 子代理 3 个:deployment-specialist(部署操作)、incident-commander(事故协调)、alert-analyzer(告警分析)。
• MCP:Kubernetes 集成。
• 脚本 3 个:deploy.sh、rollback.sh、health-check.sh。
• 钩子 2 个:pre-deploy.js(部署前校验)、post-deploy.js(部署后任务)。

部署工作流:

1. 用户敲 /deploy production
2. pre-deploy 钩子校验 kubectl 与集群连接
3. 委派 deployment-specialist 子代理
4. 执行 deploy.sh 脚本
5. Kubernetes MCP 监控部署进度
6. post-deploy 钩子等待 Pod 就绪 + 冒烟测试
7. 输出部署总结(版本/Pod 就绪数/耗时)
​

这个插件示范了插件如何组织"过程":命令定义意图,钩子保证安全边界,子代理执行专业判断,脚本承载确定性操作,MCP 提供实时状态。回滚与事故场景同理——/rollback production、/incident 各自走"校验 → 委派 → 执行"。

三、Documentation:模板驱动生产插件

定位:文档的生成、维护与校验——API 文档、README、同步、验证。

组件构成:

• 斜杠命令 4 个:/generate-api-docs、/generate-readme、/sync-docs、/validate-docs。
• 子代理 3 个:api-documenter(API 文档专家)、code-commentator(注释改进)、example-generator(示例生成)。
• 模板 3 个:api-endpoint.md(REST 端点模板)、function-docs.md(函数文档模板)、adr-template.md(架构决策记录模板)。
• MCP:GitHub 集成(文档同步)。

文档生成工作流:

1. 用户敲 /generate-api-docs
2. 扫描 /src/api/ 全部端点
3. 委派 api-documenter 子代理
4. 提取函数签名与 JSDoc
5. 按模块/端点组织
6. 套用 api-endpoint.md 模板
7. 生成含 curl/JavaScript/Python 示例的 Markdown
​

产出示例:📄 docs/api/users.md、auth.md、products.md、📊 覆盖:23/23 端点。

这个插件的独特之处在 templates/:模板把"文档长什么样"沉淀为标准件,子代理只负责提取事实,格式统一由模板保证——多人协作时文档风格不再漂移。

四、规律总结:入口、分工、守门、标准件

三个插件殊途同归,组件角色高度一致:

安装输出也印证了这一点:✅ 3 slash commands installed → ✅ 3 subagents configured → ✅ 2 MCP servers connected → ✅ 4 hooks registered——四要素逐一落位。设计自己的插件时,先问四个问题:入口命令是什么?要哪些角色分工?哪里需要守门?哪些输出要标准化?

小结

三个示例覆盖了插件的三种典型形态:审查流水线(PR Review,多代理并行 + 汇总)、过程自动化(DevOps,钩子守门 + 脚本执行)、模板生产(Documentation,标准件套用)。共同规律:命令定义意图、代理执行分工、钩子守住边界、模板/脚本保证标准。照这个四问设计法(入口/分工/守门/标准化),你的插件结构不会跑偏。下一节讲安全与发布——插件能装什么不能装什么,以及如何上线。

下一节预告:第 4 节讲沙箱限制、受管设置与发布八步流程。