让每个命令都能精准路由：HagiCode Preset Task 的多技能支持实战

先说点背景。HagiCode 的 preset task 是一套插件化的小工具系统。用户不必手敲命令只要在可视化面板里填几个字段点一下就能创建一个自动任务会话。每个 preset 本质上是一个目录里面通常长这样manifest.jsonpreset 的身份信息panel.json可视化面板的表单定义commands.json实际要执行的命令清单task-preset.json或prompts.json任务参数和技能要求这套东西用起来确实方便可我们很快就撞上了一个别扭的地方。早期版本里skill 只能在 preset 层级的requirements数组里声明。什么意思呢就是同一个 preset 内的所有命令共享同一份技能要求罢了。听起来好像没啥可实际用起来是这样的场景一个 preset 里有五条命令其中第一条想走last30days这个 skill第三条想走ui-master剩下三条不需要任何 skill。在旧设计下做不到。你想让不同命令路由到不同 skill就得把这些命令硬拆成好几个 preset配置一下就膨胀了。这就是提案extend-preset-task-multiple-skills-support想解决的问题让每条命令独立声明自己依赖的 skill并且把这种绑定在 UI 上可视化出来。关于 HagiCode本文分享的方案来自我们在 HagiCode 项目里的实践经验。HagiCode 是一个 AI 代码助手项目preset task 系统正是它面向用户的快捷操作入口。下面讲的每一处改动都是我们实际踩坑、实际优化出来的——毕竟纸上得来终觉浅。项目源码在 HagiCode-org/site感兴趣的可以先去点个 Star。先把问题想清楚为什么不是一张映射表动手之前最容易想到的方案是再开一张commandSkillMappings映射表把命令 ID → skill的关系单独存起来。听起来很干净职责分离嘛。可仔细一琢磨就发现不对劲。commands.json里每条命令已经有一个 ID映射表里又得把这个 ID 抄一遍。两份文件、同一个 ID只要哪天有人改了命令忘了同步映射表数据就漂移了。这种为了分离而分离的设计后期维护成本远大于它带来的那点整洁感。到头来只是徒增烦恼而已。所以我们最终选了一条更直接的路把可选的skill字段直接放到命令定义上。一条命令自己声明自己绑哪个 skill就近维护谁也不会跟谁失联。这个决定背后还有一条更重要的设计原则值得单独拎出来说。核心一两层数据职责分离这是整个改造里最关键的一个认知。很多人第一反应是既然命令上有了skill那做 requirement check技能门禁检查的时候是不是应该去扫每个命令的skill字段不是。我们刻意把这件事拆成了两层commands.json的skill字段只负责声明绑定。它告诉系统这条命令要绑哪个 skill用于渲染 prompt 前导和 UI 展示。task-preset.json的requirements数组才是权威枚举。它是真正的门禁决定一个 preset 需要满足哪些技能才能运行。换句话说skill回答的是绑哪个、渲染什么requirements回答的是到底允不允许跑。两件事别混在一起。这么分的好处是 check 逻辑天然简单。因为门禁始终基于 preset 层的requirements按CacheKey去重多条命令绑同一个 skill 也只会探测一次不会重复打点。命令级 skill 不引入任何额外的探测开销。这条原则也是我们否决映射表方案的根本原因——映射表会让人误以为绑定即门禁把两层职责又搅回去了。聪明反被聪明误不过如此。核心二命令定义长什么样改造后的命令定义就是在原来的基础上多了一个可选的skill字段。以last30days这个 bundled preset 为例它的commands.json大致长这样{$schema: ../../schemas/commands.schema.json,version: 1.1,commands: [{id: research,skill: last30days,prompt: 调研一下最近30天大家对 {topic} 的真实讨论},{id: summarize,prompt: 把上面的调研结果整理成一份摘要}]}几个要点说明version升到了1.1对应的 schema 也加了可选skill字段。第一条命令research绑了last30daysskill执行时会路由到这个技能。第二条命令summarize没绑 skill它只是一条普通指令走默认路径。注意这里没有在命令里写任何 requirement。真正的门禁在task-preset.json的requirements里{requirements: [{key: last30days,cacheKey: skill:last30days}]}research命令绑的last30days必须出现在这份requirements里否则就出问题了——这正是下一节要讲的硬约束。强扭的瓜不甜。核心三加载期的交叉校验光在数据上声明绑定还不够得有人兜底防止命令绑了一个 skill可 requirements 里压根没声明这种孤儿绑定溜到线上。这个兜底就是ValidateCommandSkills。它在 preset 包加载的时候跑一遍逐条检查每个命令的skill是否都能在 preset 层的requirements里找到对应项。找不到就判定为非法包直接禁用整个 preset并抛出诊断码command-skill-not-in-requirements。为什么要禁用整个包而不是只跳过那条命令因为 preset 是一个整体命令之间往往有依赖关系前一条的输出喂给下一条。如果悄悄跳过一条后面的命令拿到空输入行为就完全不可控了。毕竟人心隔肚皮代码也隔肚皮。宁可让用户看到明确的报错也不要让任务在半路上莫名其妙地跑歪。这一点马虎不得。这个校验是在加载期完成的也就是说问题在 preset 注册的那一刻就会被发现不会拖到用户真正点运行才暴雷。对用户体验来说早报错永远好过晚报错。核心四prompt 前导的幂等拼接接下来是执行链路上最微妙的一环。当一条命令绑了 skill比如last30days系统在真正执行前要把这个 skill 信息拼到命令前面形成一个完整的单行指令交给执行器。这个过程由CombineCommandSkillPrelude负责。举个具体的例子。research命令的 prompt 是调研一下最近30天大家对 {topic} 的真实讨论绑的 skill 是last30days那么最终交给执行器的指令大致是/last30days 调研一下最近30天大家对 {topic} 的真实讨论也就是在 prompt 前面加了/last30days这个前导。执行器看到这个前导就知道要先把上下文切到last30days这个 skill 上。这里有个容易踩的坑幂等性。为什么要强调幂等因为有些场景下prompt 本身可能已经带了这个 skill 前导比如用户手动写了一半或者从别的地方拷过来的。如果系统傻乎乎地再拼一次就会变成/last30days /last30days 调研...执行器要么报错要么行为异常。所以CombineCommandSkillPrelude在拼接前会先检测一下如果前缀已经存在就不重复加。这一步看似不起眼可能挡掉一类很隐蔽的 bug。值得一提的是这整套前导注入逻辑都在 preset 定义层PresetTaskCatalogProvider里的BuildCommandPrelude完成SessionsController这边的会话创建代码完全不用动。这也是职责分离带来的好处——执行入口保持稳定技能路由的复杂度被收敛在定义层内部。核心五前端怎么把绑定展示出来后端把数据模型和执行链路都理顺了最后一步是让用户在界面上能看见这种绑定。毕竟一个功能如果用户感知不到那约等于没做。前端这边做了三件事。第一命令选择器上加徽标。在 command-picker 里每条绑了 skill 的命令旁边会显示一个小徽标标明它依赖哪个 skill。用户扫一眼就知道哪条命令是带技能的哪条是普通命令。第二requirement-check 摘要区块。面板上有一个专门的摘要区域列出当前 preset 需要满足的所有 skill 要求以及每条命令分别绑了哪个。这个区块的数据来源于commandSkillsByRequirementKey这个映射——把命令按它绑的 requirement key 分组聚合方便用户一眼对照要求和实际绑定是不是对得上。画虎不成反类犬大概就是这样——所以聚合逻辑要做得直给别花哨。第三失败时的一键安装深链。如果 requirement check 发现某个 skill 没装用户不必自己去翻文档找安装入口。界面直接给出一个深链按钮点一下跳到对应的安装流程。这一步把发现问题和解决问题之间的距离压到了最短。前端类型这边也很克制命令类型只是加了一个skill?: string并且做了归一化处理|| undefined避免空字符串这种边界值在后续判断里惹麻烦。实践五步走完整套改造把前面零零碎碎的点串起来整套改造其实就是五步扩展 schemacommands.schema.json加上可选skill字段版本号升到1.1。解析 校验NormalizeCommands负责解析命令定义ValidateCommandSkills做交叉校验命令 skill 必须能在 preset 层 requirements 里找到。注入前导BuildCommandPrelude在执行前把/skill前导幂等地拼到命令前不需要改动SessionsController。迁移 bundled presetlast30days和ui-master这两个内置 preset 的commands.json改一下给相应命令补上skill字段。迁移只动 commands.json不碰其他文件。前端可视化类型补字段、command-picker 加徽标、requirement-check 加摘要区块、失败时给一键安装深链。几条实践中的注意事项单独列一下一条命令只能绑一个 skill。这是当前的约束。如果一个场景真的需要一条命令触发多个技能逃生舱是在 preset 层的requirements里声明多个 skill让它们在 preset 级别共存。校验失败的诊断码是command-skill-not-in-requirements排查问题时直接搜这个码。前端归一化记得|| undefined别让空串混进判断逻辑。迁移时只动 commands.jsonrequirements 那边保持不动避免引入意外变更。后端测试覆盖三类场景命令 skill 在 requirements 里通过、不在禁用包、多条命令绑同一 skill去重正常。总结