type
Post
status
Published
date
Oct 8, 2026
slug
summary
一个为别的 Agent 写的 skill 搬过来，变量替换、hooks 形态、更新路径三处全断。
tags
Write
插件兼容
环境变量
排障方法
DSH 插件开发
category
DSH
icon
password
url
我最近把一个开源的 skill 装进了自己的 Agent 环境。仓库说明写得很清楚：克隆、放到 skill 目录、重启即可。我照着做了，命令也确实能跑起来。那一刻我以为事情结束了。
真正的问题在第二天才浮出来。我让它按最小示例出一页 HTML，出来的东西是对的；可当我换一个工作目录再跑，命令直接失败。回头翻文档才发现，这个 skill 里到处写着一种变量占位符，用来指代它自己所在的目录——那是它原来那个宿主提供的语法，我这边根本不认。它没有报「变量未定义」，它只是把那一串字符原样当成了路径。
这就是「装完就能用」的幻觉：安装动作成功，不等于运行链路完整。一个 skill 从 A 宿主搬到 B 宿主，中间断掉的地方往往不在主流程上，而在那些原宿主替你默默兜住的边角。这篇写的就是我踩到的三处，以及我最后固化成的一份检查清单。
一、命令能跑，不代表它知道自己在哪
那个占位符的问题最典型。原宿主会在加载 skill 时，把占位符替换成 skill 所在目录的绝对路径，作者就可以放心地在文档里写「运行本目录下的脚本」。我这边的宿主不做这件事，于是文档里那句命令展开后变成一串没有意义的字符。
修法很土：把占位符全部换成真实路径。但我没有手动改一遍就完事——手动改的代价是，下次这个 skill 更新，我又得改一遍，而且很容易漏。我写了个小脚本，把「替换占位符」这一步固化成安装流程的一部分。安装时自动扫描 skill 文档，发现占位符就替换成落地目录，替换完再回读一遍确认生效。
这里有个容易忽略的细节：同一个 skill 里可能有不止一种占位符。有的影响主流程，有的只在边缘场景用到。我的做法是全部替换，而不是只修报错的那一个——报错只暴露了当前路径上的问题，没报错不代表剩下的占位符是安全的。
二、hooks 的参数形态，桥接层不认
第二个坑更隐蔽。这个 skill 附带一个 always-on 插件，作用是让 Agent 在每轮对话开始时都收到一条提醒，从而「记得」自己有这么个能力。它原本是照着另一个宿主的 hooks 规范写的，参数以数组形式声明。
我这边提供了一个兼容桥接，理论上能接住那种格式。实际接不住。桥接层期望的是一个完整的命令字符串，而不是拆开的数组；数组递进去，它既不报错也不执行，静默失效。这种失败最难查——没有日志，没有异常，只是那条提醒永远不出现。
我的处理是自己写一份 hooks 配置，把数组形式的参数拼成单条命令字符串，再挂到桥接上。改完之后我没有立刻相信它生效了，而是重启了环境，看下一轮对话的上下文里有没有出现那条提醒标记。它出现了。到这一步，我才敢说这条链路是通的。
回头看，这里的教训不是「数组要拼成字符串」这么具体，而是：跨宿主移植时，配置文件里的参数形态和参数内容一样重要。内容对了、形态错了，结果是静默失败，比报错难查十倍。
三、能装不能升，是半个工具
第三个坑是我自己发现的：这个 skill 完全没有更新路径。原仓库的安装方式是一次性复制，装完之后，上游改了、修了 bug、加了功能，你这边一无所知。
一个只能装不能升的工具，用久了就会变成负债——你手里那份和上游越差越远，最后要么不敢动，要么只能推倒重装。所以我顺手补了一个安装器，支持四个动作：安装、更新、列出已装的、体检。更新就是重新拉取上游、重跑一遍占位符替换、再校验一次。
体检这一项是我后来加的，也是我觉得最值钱的。它检查的不是「文件在不在」，而是「链路通不通」：占位符有没有残留、hooks 配置形态对不对、依赖的运行时版本够不够。装的时候跑一次，出问题的时候再跑一次，能把排查范围一下子缩小到具体某一环。
四、为什么我坚持要一份手册
链路打通之后，我做的最后一件事是写一份面向使用者的操作手册。不是给开发者看的架构说明，是「我想用这个能力时，具体敲什么、看到什么算成功」。
这件事看起来多余——功能都能用了，还写什么手册。但我的判断是：一个装在自己环境里的能力，如果只有我自己知道怎么触发、怎么验证、坏了怎么查，那它其实还没有真正交付。过两周我大概率会忘掉 hooks 是怎么挂的，忘掉体检脚本叫什么。手册是给未来的自己写的，也是给「这个环境不止我一个人用」这个前提写的。
手册里我特意写清了三件事：怎么确认它活着（看那条提醒标记）、怎么手动触发一次（跑最小示例）、失败时先查哪一项（跑体检）。这三条覆盖了我这次踩坑的全部场景。
可迁移的判据
如果你也要把一个为别的 Agent 写的 skill 搬过来，我建议按这个顺序查，而不是等它报错：
- 先搜占位符。把 skill 文档里所有形如变量引用的写法找出来，确认新宿主是否支持。不支持就全部替换成落地路径，并且把替换固化成脚本，别手动改。
- 再查 hooks 参数形态。兼容层往往只认某一种声明形式，形态不对会静默失效。改完必须重启验证端到端，看到预期的那条信号才算通。
- 确认有没有更新路径。只能装不能升的工具会随时间腐化。没有就自己补一个，更新流程要和安装流程走同一套校验。
- 加一个体检动作。检查链路而不是检查文件，把「装好了」和「能用」区分开。
- 写一份给使用者的手册。写清怎么验证活着、怎么手动触发、坏了先查哪。手册不是文档负担，是交付的一部分。
最后补一句我这次判断错的地方：我一开始以为「命令能跑」就等于「装好了」，所以第一轮验证只跑了最小示例，没换目录、没重启、没看上下文。三处坑里有两处，只要我当时多做一个动作就能提前发现。移植这件事，验证的成本远低于事后排查的成本——这个账，值得先算清楚。