pi-skill-guard

一个 pi 扩展，用于防止常见的模型错误：错误的工具名称、缺失的 skill、损坏的参数模式以及字段名不匹配。

安装

pi install npm:pi-skill-guard

---

功能说明

该扩展通过 message_end 事件拦截工具错误，并在 LLM 看到失败之前静默修复。包含三种保护：

1. Skill 文档注入

当模型调用与可用 skill 同名的工具时（例如 brave-search），扩展将"未找到"错误替换为 skill 的 SKILL.md 内容。

修复前： Tool brave-search not found（错误） 修复后： 完整的 SKILL.md 内容作为成功的工具结果注入

2. Bash 命令执行

当模型调用包含 command 参数的未知工具时，扩展通过 pi 内置的 bash 工具执行。支持可选的 timeout（数字或字符串）。

修复前： Tool my-script not found（错误） 修复后： 实际的 bash 执行结果（含截断和临时文件管理）

3. 字段别名规范化（edit / write / read）

当工具调用因字段名错误而验证失败时，扩展扫描原始参数、重命名常见别名并重新执行。

工具	标准字段	接受的别名
edit	path	file、filePath、file_path、target、filename、file_name
edit	edits[].oldText	old_str、old_string、oldContent、old、original、search
edit	edits[].newText	new_str、new_string、newContent、new、replacement、replace
write	path	file、filePath、file_path、target、filename、file_name
write	content	text、body、code、data、fileContent、contents
read	path	file、filePath、file_path、target、filename、file_name
read	offset	start、startLine、start_line、from、line
read	limit	lines、maxLines、max_lines、count、numLines、num_lines

Edit 工具简写支持: 如果未提供 edits 数组，顶层的 oldText/newText（或它们的别名）会被自动包装为单元素 edits 数组。

Read 工具类型转换: offset 和 limit 的字符串值（例如 "10" 而不是 10）会在有效时自动转换为数字。

---

架构

所有拦截均在 message_end 事件中处理，该事件在每条消息完成后触发，并支持原地替换消息。每个工具调用通过 ID 跟踪，防止在替换链中重复处理。

• session_start：加载 skills，缓存文件路径
• turn_end：清除已处理的工具调用跟踪
• message_end：检查错误结果，应用保护机制