解剖edgeone-makers-tools：一个路由型AI技能包的架构设计与Hooks校验机制

edgeone-makers-tools是 EdgeOne Makers 平台官方的 AI 技能包，它用一个"路由型"架构把 11 个开发能力域装进单个技能，再用 Hooks 校验机制在 AI 写文件的瞬间自动拦截常见错误。这篇文章带你完整看懂它的三层技能路由设计、PreToolUse 钩子校验流程，以及几个体现工程功底的细节。🔍

一、为什么需要"路由型"技能包？

AI 编程助手（Claude Code、Cursor、Codex 等）越来越流行"技能"（Skills）机制：给 AI 喂一份结构化的领域知识，让它按文档规范写代码。但技能包有个天然矛盾：

• 技能太多→ 助手列表臃肿，加载时上下文爆炸；
• 技能太粗→ 一份巨型文档全量塞进上下文，token 浪费、命中率下降。

edgeone-makers-tools 的解法是：入口只有一个，内部按需分流。就像医院的分诊台——你不用认识所有科室医生，只需描述症状，护士把你领到对的诊室。

二、三层路由架构解剖

第 1 层：顶层路由表（分诊台）

skills/edgeone-makers-tools/SKILL.md 是整个技能包的入口，核心是一张"任务 → 文档"路由表：

文件末尾有一句关键纪律（见 SKILL.md 末尾）：

⚠️ Only read the Skill relevant to the current task. Do not load all skills at once.

只读当前任务相关的那一个，绝不一次性全量加载——这就是"路由型"的核心语义：SKILL.md不存知识，只负责分发。

第 2 层：能力域目录（诊室）

每个能力域都是references/<名称>/SKILL.md结构，例如 makers-agents/SKILL.md 覆盖五种 Agent 框架接入，makers-cloud-functions/SKILL.md 覆盖三种运行时。每个能力域的 frontmatter 还额外携带了"机器可读"的校验规则（后面详解）。

第 3 层：明细参考文档（病历档案）

以 makers-agents 为例，内部再细分出平台约定、能力说明、Node/Python 框架文档（见 makers-agents/references/ 下的 platform/、capabilities/、node-frameworks/、python-frameworks/ 四个子目录）。AI 只有深入到某一步时才会去翻这些文档，日常任务永远走不到这一层。

三层结构一句话总结：路由表 → 能力域 → 明细文档，越深入越具体，上下文消耗按需递增。

三、Hooks 校验机制：写文件路上的"质检员" 🛡️

技能文档只能"被动"被 AI 阅读，怎么保证 AI 真守规矩？答案是Hooks 钩子——在工具执行前插入一段检查逻辑。

1. 钩子注册：只盯写操作

hooks/hooks.json 把钩子挂在PreToolUse事件上，匹配Edit|Write|replace_in_file|write_to_file四类写文件工具，命中就执行 hooks/validate-write.mjs，超时 3 秒：

{ "hooks": { "PreToolUse": [{ "matcher": "Edit|Write|replace_in_file|write_to_file", "hooks": [{ "type": "command", "command": "node .../validate-write.mjs", "timeout": 3 }] }] } }

2. 规则从哪来：声明式 frontmatter

校验规则不集中在某处，而是分散声明在各能力域 SKILL.md 的 YAML frontmatter 里——文档即规则，改文档即改校验。以 makers-edge-functions/SKILL.md 为例：

• pathPatterns: edge-functions/**、functions/**→ 这条规则管辖哪些路径
• validate:列表 → 每条含pattern（正则）和message（提醒文案），例如命中Response.json(就提醒"该 V8 运行时不支持 Response.json()，请用 new Response(JSON.stringify(...)) 替代"

3. 完整校验流水线

validate-write.mjs 的buildValidateWriteOutput函数（第 206-241 行）串起整条流水线：

AI 发起写文件操作（stdin 传入 JSON 载荷） │ ▼ ① 工具名过滤 —— 只有 4 种写工具才继续，其余直接放行 │ ▼ ② 路径匹配 —— globToRegExp 把 frontmatter 里的 pathPatterns 转正则，筛出所有管辖该路径的规则 │ ▼ ③ 内容扫描 —— 用每条 validate 的 pattern 去匹配 待写入内容，命中即收集 message（按文案去重） │ ▼ ④ 双路输出 —— 生成 additionalContext 提醒注入回模型； 同时写 signal-log 归因日志

提醒以additionalContext的形式追加到模型上下文中（形如Validation reminder: - ...），模型下次生成会"看见"这条红线，但写入本身不被拦截——提醒优先于封杀，给 AI 留出自我修正的机会。

4. 四个体现功底的细节

① 静默兜底：宁可漏提醒，不可报错。钩子挡在每次写文件前面，main()入口吞掉所有异常（第 251-279 行）。源码注释写得很直白：校验器失效的正确表现是"不提醒"，而不是"报错"——否则用户每写一个文件都会看到一次红字。

② 收集全部命中，而不只取第一条。findSkillsForPath（第 177-182 行）返回所有匹配规则。因为规则按目录字母序加载，agents/**与cloud-functions/**这类前缀天然重叠，只取首条会让"哪条铁律生效"由目录名字母序偶然决定，多个能力域共管同一路径时会静默丢失提醒。

③ 信号日志可归因。每次命中都会通过 hooks/signal-log.mjs 追加一行 JSON 到.edgeone/signal-log.jsonl，记录hook / trigger / matchedSkill / reason——哪条规则、来自哪个技能域、为何触发，一目了然，方便评估规则质量。

④ 规则有测试守门。hooks/validate-write.test.mjs 用node --test固化了关键不变量：比如"提醒但不阻断"的输出结构、三条原始红线必须始终在场。断言的是不变量而非冻结数组，新增规则不会误伤测试。

四、自检体系：技能包如何不腐化

11 个能力域、数十篇 markdown，怎么保证链接不断、结构不漂？scripts/doctor.mjs 提供六项自检（退出码 0 = 全绿）：

底层扫描逻辑由 scripts/lib/skill-graph.mjs 提供（纯函数、只认 root 目录），连"目录树里塞个 FIFO 命名管道会永久阻塞扫描"这种边缘情况都做了防护（第 90-98 行）。配合 package.json 的npm test/npm run doctor两条脚本，CI 里一跑就知道技能包健不健康。

五、多平台适配与快速上手 🚀

同一个技能包要同时服务多家 AI 平台，仓库为此做了双轨适配：

• 标准 Skills 目录：skills/edgeone-makers-tools/，供npx skills、Claude Code 插件市场、SkillHub 安装；
• 提示词规则文件：codex/ 与 cursor/rules/ 下各能力域的 .md/.mdc 文件，供 Codex、Cursor 的 rules 机制直接引用。

上手只需一条命令（需 Node.js ≥ 16）：

npx skills add TencentEdgeOne/edgeone-makers-tools

安装后，助手会自动识别任务并加载对应能力域。直接对 AI 说"把这个 Next.js 项目部署到 EdgeOne"或"帮我写个带 KV 计数的边缘函数"，路由表和 Hooks 校验就会在背后默默工作。

六、架构启示：这套设计能抄到什么程度？

edgeone-makers-tools 给出的方法论，对任何做 AI 技能包 / MCP / Prompt 工程的项目都有参考价值：

1. 入口薄、纵深重：入口文件只做路由，知识按"访问频率 × 主题"分层存放；
2. 文档即规则：把校验正则写进 frontmatter，文档与守卫天然同步，不存在两份真相；
3. 守卫要软：注入提醒代替硬拦截，保留 AI 的裁量空间，也避免误杀；
4. 守卫要哑：自身出错时静默降级，绝不让工具链比业务代码更脆弱；
5. 可观测 + 可自检：signal-log 归因 + doctor 六项体检，让"知识资产"像代码一样可回归、可维护。

完整能力矩阵与目录结构见 README.md，路由入口见 SKILL.md。