波仔
🐎 第9章 集腋成裘：Plugins 生态
📄 一句话概括

一个能用的团队包，通常就六个文件：一份清单、一个子智能体、一个钩子、一个技能、一条命令、 一份说明。 实测两套包对比：缺 README 和钩子的那套照样能装。不报错的缺失，才是团队包里最难发现的问题。

📝 本章和前面几章的关系

前面四节讲结构和规则，这一节把它们拼成一个真东西。 这一节有真跑：真建了两套目录、逐文件对比，看缺了会怎样。

一、六个文件各干什么

plugin.json：清单。少它装不上。 agents/security-scan.md：只读扫描的子智能体。少它就没有隔离区。 hooks/scan.sh：每次工具调用后记一笔。少它就没有痕迹。

skills/deploy-check/SKILL.md：发布前检查的步骤。少它只能靠人记。 commands/audit.md：一条斜杠命令。少它要手打一长串。 README.md：怎么装、怎么用。少它别人不会用。

二、真跑：建出完整的一套

演示里真建了六个文件，一共不到二十行内容。 团队包的体量通常就这么小——它的价值不在代码量，在「一次配好、所有人一致」。 所以别指望包能有多大：一旦超过一两百行，就该考虑拆成两个包了。

三、真跑：两套包对比

演示里建两套：一套完整，一套缺 README 和 hooks。 缺的那两个不影响「能不能装」，只影响「别人会不会用」和「有没有痕迹」。 而这两类问题都不报错：装的时候一切正常，等到有人来问你、或者出了事要回溯，才发现缺。

所以团队包的检查清单里，「能装」只是一条，另外几条是「别人能用」「出事能查」。

四、那份子智能体为什么写成只读

扫描类任务不需要写权限。给它读和搜索就够，工具列表里直接不写写类工具。 这是「最小权限」最省事的落实方式：不是靠嘱咐，是靠「没给」。 而它输出的是「文件、行号、原因」三列——这正好是 4.7 节那套字段的简化版。

所以一个包的每个组件，都应该能对应到前面某一章讲过的某个约定。

五、发布流程的三步

先在本地目录里试：改一行就能看到效果，不用打包。 稳定后打版本号、写变更说明，进私有市场（9.6 节）。 别人装了之后收到的反馈，回到第一步改——不要直接改已经发布的版本。

第三条最容易违反：改已经发布的版本，会让「你装的是哪一版」这件事失去意义。 而版本号一旦失去意义，9.3 节那条回滚的链就断了。

六、动手 Demo：一个团队能力包，六个文件，缺两个会怎样

一个能用的团队包，通常就这几个文件：清单、子智能体、钩子、技能、命令、说明。 这里真建两套，逐个文件对比，看缺了会怎样。

FILES = [(u".claude-plugin/plugin.json", u"..."),
         (u"agents/security-scan.md", u"---\nname: security-scan\ntools: Read, Grep\n---"),
         (u"hooks/scan.sh", u"#!/bin/sh\n"),
         (u"README.md", u"# corp-security\n")]

实跑输出：

--------------------------------------------------------------------
一个团队能力包，六个文件，缺两个会怎样
--------------------------------------------------------------------

  一个能用的团队包，通常就这几个文件：一份清单、一个子智能体、一个钩子、一个技能、一条命令、
  一份说明。
  这里真建一遍，再逐个检查缺了会怎样。

  ① 六个文件各干什么
  --------------------------------------------------------------------
| 文件 | 作用 | 缺了会怎样 |
|---|---|---|
| plugin.json | 清单 | 少它装不上 |
| agents/security-scan.md | 只读扫描的子智能体 | 少它没有隔离区 |
| hooks/scan.sh | 每次工具调用后记一笔 | 少它没有痕迹 |
| skills/deploy-check/SKILL.md | 发布前检查的步骤 | 少它只能靠人记 |
| commands/audit.md | 一条斜杠命令 | 少它要手打一长串 |
| README.md | 怎么装、怎么用 | 少它别人不会用 |


  ② 真跑：建出完整的一套
  --------------------------------------------------------------------
    .claude-plugin/plugin.json
    agents/security-scan.md
    hooks/scan.sh
    skills/deploy-check/SKILL.md
    commands/audit.md
    README.md
  六个文件，一共不到二十行内容——团队包的体量通常就这么小。

  ③ 真跑：两套包对比，缺的那两个最容易被忽略
  --------------------------------------------------------------------
| 文件 | 完整包 | 缺两个的包 |
|---|:---:|:---:|
| .claude-plugin/plugin.json | 在 | 在 |
| agents/security-scan.md | 在 | 在 |
| hooks/scan.sh | 在 | 缺 |
| skills/deploy-check/SKILL.md | 在 | 在 |
| commands/audit.md | 在 | 在 |
| README.md | 在 | 缺 |

  缺的那两个是 README 和 hooks。它们不影响「能不能装」，只影响「别人会不会用」和「有没有痕迹」。
  而这两类问题都不报错：装的时候一切正常，等到有人来问你、或者出了事要回溯，才发现缺。
  所以团队包的检查清单里，「能装」只是一条，另外几条是「别人能用」「出事能查」。

  ④ 那份子智能体为什么写成只读
  --------------------------------------------------------------------
  扫描类任务不需要写权限。给它 Read 和 Grep 就够，工具列表里直接不写写类工具。
  这是「最小权限」最省事的落实方式：不是靠嘱咐，是靠「没给」。
  而它输出的是「文件、行号、原因」三列——这正好是 4.7 节那套字段的简化版。

  ⑤ 发布流程的三步
  --------------------------------------------------------------------
  - 先在本地目录里试：改一行就能看到效果，不用打包。
  - 稳定后打版本号、写变更说明，进私有市场（9.6 节）。
  - 别人装了之后收到的反馈，回到第一步改——不要直接改已经发布的版本。
  ! 这里的包是最小可用形态，真实包可能还有 MCP 配置、更细的权限声明。

①六个文件各管一件事：清单（装得上）、子智能体（隔离区）、钩子（痕迹）、技能（步骤）、 命令（少打字）、README（别人会用）。 ②六个文件一共不到二十行。团队包的价值不在代码量，在「一次配好、所有人一致」； 超过一两百行就该考虑拆包。 ③两套对比：缺 README 和 hooks 的那套照样能装。 缺的那两个只影响「别人会不会用」和「有没有痕迹」，而这两类问题都不报错。 ④子智能体只给读和搜索工具，是「最小权限」最省事的落实方式：不是靠嘱咐，是靠「没给」。

30 秒实验

  1. 把 hooks/scan.sh 里的日志改成写标准输出，重跑一遍。为什么这一改会让钩子失效？
  2. 给 README 补上「它不做什么」一段，再想一下：这段话能挡掉哪类问题？
  3. 把六件事拆成两个包（扫描一个、发布检查一个），重跑一遍。哪个包更容易被别人只装一部分？

常见误区

  1. 只写清单和组件，不写 README。别人装上了但不会用，问题还是来问你。
  2. 钩子写日志到标准输出。协议通道被污染，整条钩子失效。
  3. 直接改已经发布的版本。版本号失去意义，回滚的链就断了。
  4. 一个包塞下六件事。超出一两百行就该拆，否则别人没法只装他要的部分。
  5. 给扫描类子智能体写权限。它不需要，而「没给」比「嘱咐别用」可靠得多。
自测三问（点开对答案） 1. 一个团队包通常有哪六个文件？ —— 清单、子智能体、钩子、技能、命令、README。前五个让它能跑，最后一个让别人会用。 2. 缺哪两个文件的包照样能装？ —— README 和钩子。它们不影响能不能装，只影响别人会不会用、出事能不能查。 3. 发布流程的三步是什么？ —— 本地目录试、稳定后打版本进私有市场、反馈回到第一步改——不要直接改已发布的版本。

包做好了，下一节讲怎么发下去：私有市场与企业级管理。

相关笔记