你激活了 sharp-skills 一个模块，但你的项目从来不是单点活儿

我维护 sharp-skills 一年多，后台数据显示一个有意思的现象：60% 以上的使用者只激活一个模块------通常是 sharp-tech-writing 或者 sharp-copywriting，挑一个用。剩下 40% 的人激活两个或三个，但往往不是按业务场景激活的，是"看着顺眼就勾上"。

实际工程里，单点活儿是少数。一个完整的开发任务至少跨三个品控维度：你写代码注释（tech-writing）、写 API 文档（api-design）、可能还要写 changelog 或者 commit message（copywriting）。只激活一个模块，剩下的两个维度 AI 会按自己的"平均水准"输出------没人约束它。

这套系统最初设计成 6 个模块，是因为"品控不能一锅炖"。但用户实际用起来，要么单点要么全开，中间状态很少。我花了大半年时间才想明白为什么，并补上了一个关键的中间层：模块协同层。

单模块激活的两个常见问题

问题一：交叉污染失效。

举一个具体例子。你激活了 sharp-api-design，希望 AI 写接口文档时遵循你的命名规范、错误码规范、cURL 示例规范。但项目同时还在用 Git，工程上需要写 commit message。AI 在写 commit message 的时候完全不受 api-design 约束，结果出来的 commit message 跟你期待的格式完全不一样（"feat: add user API" 而不是你团队习惯的 " $Backend$ $User-API$ feat: 新增用户接口"）。

这个问题是"模块只管自己的领域"。品控不应该是"我管哪块就只管哪块"，应该是有业务交集的地方能联动。

问题二：模块冲突。

更隐蔽的问题。你同时激活了 sharp-tech-writing 和 sharp-copywriting。前者要求"技术文档要客观、避免营销腔"，后者要求"营销文案要有感染力、避免干巴巴"。两个规则单独看都对，放一起就矛盾：AI 在写"产品发布说明"（半文档半文案）的时候，不知道该听谁。

这种冲突不是品控规则设计得不好，是"模块之间没说清楚优先级和场景"。sharp-skills 6 个模块在内部定义里有 priority 和 applies_to 字段，但用户激活的时候很少去配这两个。

模块协同层的核心思路

我做的是：模块协同层不强制激活所有模块，而是根据任务意图动态选择应该激活哪些，以及它们的优先级。

实现不复杂。在 Agent 调用 sharp-skills 之前，加一个"任务分类器"------根据用户当前的输入意图，决定激活哪些模块以及它们的权重。

yaml 复制代码

# 协同层配置示例
scenarios:
  - name: api_documentation
    trigger: ["接口文档", "API 文档", "swagger"]
    modules:
      - sharp-api-design: 1.0      # 主要约束
      - sharp-tech-writing: 0.7    # 次要约束
      - sharp-copywriting: 0.2     # 弱约束（接口文档基本不需要营销腔）

  - name: blog_post
    trigger: ["公众号", "博客", "技术文章"]
    modules:
      - sharp-copywriting: 1.0      # 主要约束
      - sharp-tech-writing: 0.8    # 次要约束
      - sharp-dataviz: 0.5         # 看场景激活

  - name: code_review_comment
    trigger: ["review", "CR", "代码审查"]
    modules:
      - sharp-tech-writing: 1.0
      - sharp-api-design: 0.6

关键不是这套配置本身，是它解决了什么问题：

第一，交叉污染失效的问题。API 文档场景下，commit message 不属于 api-design 管的领域，但因为任务意图是"开发任务"，协同层会同时激活 tech-writing 和 copywriting（低优先级）来兜底。哪怕用户只勾了 api-design，协同层会自动按场景补上。

第二，模块冲突的问题。不同场景下模块的优先级是显式声明的，AI 看到的规则顺序就是优先级顺序，不会两个模块规则相互打架。博客文章场景下 copywriting 在前、tech-writing 在后，AI 先满足"有感染力"的约束，再满足"客观"的约束。

协同层设计的三个坑

第一个坑：协同层自己也变成规则集。

我第一版做的是把"协同规则"也写成一组规则文件，让 AI 自己根据场景判断激活哪些模块。结果可想而知------AI 经常判断错场景，把 API 文档当成博客写，或者反过来。协同层不该让 AI 决策，应该用规则引擎或者简单的关键词匹配，把意图分类做硬。

python 复制代码

# 协同层的核心就是 if-else，不要套 AI
def get_active_modules(user_input: str) -> list:
    if "接口" in user_input or "API" in user_input:
        return [("sharp-api-design", 1.0), ("sharp-tech-writing", 0.7)]
    if "博客" in user_input or "公众号" in user_input:
        return [("sharp-copywriting", 1.0), ("sharp-tech-writing", 0.8)]
    # 默认：技术写作主导
    return [("sharp-tech-writing", 0.9)]

这 5 行代码做的事比让 AI 判断"我现在该激活哪些模块"靠谱 100 倍。

第二个坑：协同层权重配死。

一开始我把所有场景的模块权重都写死在配置文件里。结果一个新场景出现就要改配置，重启服务。生产环境不敢随便重启，配置延迟生效，最后协同层形同虚设。

正确做法是把权重放在调用方的 context 里。每次调用 sharp-skills 的时候带上"当前场景 + 当前模块权重"，协同层只是把这些信息组合成最终的规则列表，不持久化任何东西。这样新增场景不需要改协同层本身，改调用方就行。

第三个坑：协同层本身的可观测性。

协同层一旦上线，团队就会开始争论"AI 这次输出为什么这样"。如果协同层是黑盒，团队只能去查 sharp-skills 的日志、看激活了哪些规则。最好在协同层加一个"激活报告"------每次调用都返回"本次激活了哪些模块、为什么激活、权重是多少"。这个报告跟 AI 输出一起给到调用方，调试成本能降低 80%。

json 复制代码

{
  "scenario": "api_documentation",
  "trigger_match": ["接口文档"],
  "active_modules": [
    {"name": "sharp-api-design", "weight": 1.0, "rules_loaded": 24},
    {"name": "sharp-tech-writing", "weight": 0.7, "rules_loaded": 18}
  ],
  "context_budget_used": 12480
}

有了这份报告，AI 输出"诡异"的时候你能立刻定位到是协同层激活错了还是某个模块的规则有问题。

一个被忽略的真相

回到开头那个数据：60% 用户只用单模块。我后来发现这不是用户的问题，是产品的引导问题。sharp-skills 之前的 readme 只说"6 个模块独立可用"，没说"模块协同"这件事。用户自然就一个一个用，因为没人告诉他怎么用全套。

加完协同层之后，readme 里加了一段："默认激活协同模式，根据任务意图自动选择模块。如果你只想用某一个模块，请显式禁用协同模式。" 结果一周内协同模式使用率从 0 涨到 70%------不是技术变好了，是引导变好了。

很多时候品控系统做不好，不是规则不够多，是用户没被引导到正确的使用方式上。品控工具的设计者和使用者之间有一道认知鸿沟，规则写得再漂亮，跨不过去也是白搭。

我在做一个用卡皮巴拉讲设计模式的微信小程序「爪爪代码冒险记」，23 个设计模式用漫画 + 答题的方式讲，目前正在开发中。如果你觉得这类内容有意思，搜一下「爪爪代码冒险记」，或者等我后面的文章。