pi-skill-path-hint

English | 中文

别再让 agent 反复输入 150 字符的长路径了。

pi 把技能包装在 ~/.pi/agent/npm/node_modules/<pkg>/skills/<skill>/scripts/ 这样的深层路径下。脚本本身没问题——问题是 agent 的每次调用都长成下面这张图的左边：

左：你 agent 的现状——每条命令都抄一遍完整 node_modules 地址，token 逐次燃烧，一旦文档与现实不符就在原地打转。右：安装后——裸文件名直调，同样的活，零头的开销。

问题，三行说完

• 脚本就在磁盘上，本来就能跑。
• agent 不知道可以按文件名裸调——于是每次都解析并输入完整 node_modules 路径。
• 每个 skill 的 SKILL.md 都各自写死了完整路径，"逐个修"等于要动所有包。

工作原理

两个通道，一个共同事实源：

1. 执行通道——会话启动时注册。 每次 agent 运行前，扩展读取 pi 的已加载技能信息（兜底扫描 node_modules），检查每个 skill 的 scripts/ 目录非空后，追加到 process.env.PATH。bash 子进程自动继承环境，裸文件名直接可用。只追加、永不前置——系统命令永远优先，即使某个 skill 脚本恰好叫 git 或 node 也不可能遮蔽它们。

2. 知识通道——落在最相关的位置。 当 agent 读取某个 SKILL.md 时，扩展在那次工具结果末尾追加：

[skill-path-hint] MANDATORY — the following script directories are on PATH:
- <scripts-dir>
You MUST invoke their scripts by bare filename (e.g. `cdp.mjs list`).
NEVER type node_modules paths for these scripts — ...

这是 agent 恰好在加载 skill 时读到的提示——语气故意强硬。老 skill 文档里"相对 SKILL.md 解析路径"的说法，输给工具结果里这张新鲜字条。

两个通道调用同一个 registerScriptsDir() 函数，所以提示里 "is on PATH" 的宣称由构造保证为真。每个目录每个会话只提示一次（会话级去重）。

为什么你会留下它

• 节省 token。 每次调用用裸文件名，不再重复近百字符的 node_modules 路径；文档与现实不一致时也少了绕弯调试。
• 缓存友好。 提示落在工具结果里，不碰 system prompt。你的 system prompt 跨会话字节级不变，服务端 prompt 缓存命中率不受影响。
• 零 system prompt 侵入。 提示配置一切照旧，扩展只在相关位置追加上下文。
• 机制性防遮蔽。 PATH 只追加不前置，skill 脚本不可能劫持系统命令。
• 优雅降级。 万一某次提示没送达，agent 退回长路径——只是慢一点，永远不会坏。

安装

pi install npm:pi-skill-path-hint

就这一条，无需改任何设置。下一个会话开始，你的 agent 就会敲 cdp.mjs list 而不是完整地址。

说明

• 零信任边界变化：这些脚本本来就能被 agent 全路径执行。
• 注册在每次运行时扫描 pi 的已加载技能；read 触发的提示是会话内的补充提醒，按目录去重。
• 空的或缺失的 scripts/ 目录会被跳过。
• 代价：每个 skill 每个会话追加几行；不改 system prompt。
• 支持 scoped 包（@scope/pkg）和任何以 /skills/<skill>/ 结尾的安装位置。

许可

MIT