政策文件制定流程与数字化工具应用解析
2026/9/16 13:45:54
新技能为什么装好了却还看不到？GoWork 的技能发现缓存、刷新与重扫
如果你刚把一个新 skill 放进目录，GoWork 却没有显示，先看结论：多数时候不是 skill 写坏了，而是技能发现结果还停留在旧缓存里。等缓存 TTL 到期、手动刷新，或者触发一次全局重扫，技能通常就会出现。另一类常见原因是路径接入方式不对，比如旧版加载器不跟随 junction 或 symlink，于是扫描器看到了入口，却没有真的走进目标目录。
很多人把这类问题误判成“安装失败”。但更准确的说法是：技能已经在磁盘上，发现索引还没跟上。这也是为什么执行型 AI 助理不能只会说“可能是缓存问题”，而应该知道排查顺序：先看缓存，再看路径，再看 skill 本体。
为什么新技能不会在每次打开界面时立刻出现
技能发现通常不是每次渲染界面都全盘重扫。为了兼顾速度，系统一般会：
- 先读取已有发现缓存；
- 在 TTL 内复用这份缓存；
- TTL 到期后或用户主动刷新时再重扫；
- 只有在全局重扫时，才重新建立更完整的目录索引。
所以会出现一个常见现象：文件已经在磁盘上，但 UI 里还没有。这不是文件不存在，而是缓存快照还没失效。
为什么缓存 TTL 不是 bug，而是稳定性设计
技能发现并不只是“看目录里有没有文件”，它还要：
- 扫描多个技能目录；
- 读取
SKILL.md和元数据； - 解析标题、描述和适用范围；
- 处理坏文件、重复项和不可读目录；
- 生成最终可展示的技能列表。
如果每次打开技能面板都全量做一遍，界面反而会更慢、更抖。TTL 的意义，就是在“足够新”和“足够快”之间取平衡。
手动刷新、等 TTL 过期、全局重扫的区别
它们不是同一个动作：
- 等 TTL 过期：被动更新；
- 手动刷新：主动让系统丢弃旧索引并重扫；
- 全局重扫：适合目录入口变化、挂接方式变化，或你怀疑扫描范围本来就不完整的时候。
普通新增 skill，刷新一次往往就够；但如果问题在目录结构，只靠等待可能永远等不到。
一个真实坑点：旧版 GoWork 不跟随 junction / symlink
content-pipeline的跨 agent README 已经明确写过：GoWork ≤1.3.x 的技能加载器不跟随 junction/symlink，源码里已修复但旧版仍会踩坑。
这意味着：
- skill 本身可能完全正常；
- 文件管理器里也能看到；
- 终端里路径也访问得到；
- 但 GoWork 的技能列表里就是没有它。
原因不是 skill 内容错，而是发现器没真正走进目标目录。此时你刷新再多次也没用，因为扫描范围本身就不对。
为什么复制目录有时更稳
理论上，junction/symlink 很优雅：一份目录，多处复用。但前提是消费方真的支持这种目录语义。
如果发现器暂时不支持，继续坚持只用挂接，换来的不是优雅，而是持续不可见。所以content-pipelineREADME 的建议很务实：如果某些 agent 不跟随 junction/symlink，就直接把目录复制到它的技能目录里。
这不是说复制更先进，而是说在当前实现边界下，复制更稳定，因为扫描器能直接读到真实的SKILL.md。
更稳的排查顺序
当新技能看不到时，别一上来就重写 skill。更稳的顺序是：
- 先确认它是否真的在当前版本会扫描到的目录里；
- 再确认是不是缓存还没失效；
- 必要时触发全局重扫；
- 最后才检查
SKILL.md是否损坏或元数据缺失。
FAQ
新技能看不到，第一步该做什么？
先确认它是否真的在 GoWork 当前扫描目录里，再手动刷新一次；如果用了 junction 或 symlink，还要确认当前版本是否支持跟随。
为什么文件管理器里能看到，GoWork 里却没有？
因为“文件存在”只证明磁盘上有它，不证明发现器已经扫描到它。常见原因是缓存未失效，或旧版加载器不跟随 junction/symlink。
为什么复制目录反而更稳？
因为在不支持映射目录的加载器里，复制意味着扫描器能直接读到真实文件。它不够优雅，但更可靠。
本文首发于 OmniGoAI 官网：https://omnigoai.com/zh/blog/gowork-skills-refresh-and-cache-ttl/ ——OmniPost，把内容一键分发到 30+ 平台。