pi-loop-guard
v1.0.4
Published
Pi coding agent extension that detects repeating tool-call loops and breaks them before they waste tokens.
Maintainers
gdwhisperReadme
pi-loop-guard
检测 pi 的 LLM 是否陷入重复工具调用循环，并在浪费 token 之前强制中断。
快速安装
pi install npm:pi-loop-guard它能做什么
pi-loop-guard 监控每一轮对话，检测两种循环模式：
| 模式 | 示例 |
|------|------|
| 连续重复 | AAAA — 连续多轮调用相同工具 + 相同参数 |
| 交替重复 | ABABAB — 两个调用来回交替，永不停止 |
检测到循环后，pi-loop-guard 会向模型注入一条引导消息，要求它尝试不同方法，或停止并汇报结果。
配置
在项目根目录创建 .pi/loop-guard.json（可选）：
{
"maxRepeats": 5,
"windowSize": 5,
"enabled": true
}| 选项 | 默认值 | 说明 |
|------|--------|------|
| maxRepeats | 5 | 连续多少轮相同调用后触发 |
| windowSize | 5 | 回溯检查最近多少轮 |
| enabled | true | 设为 false 可临时禁用 |
为什么模型自己不会停？
即使提示写得再好，模型在工具调用场景下也可能陷入循环 —— 尤其当它对结果困惑时，可能会连续读取同一个文件十几次。pi-loop-guard 是一个低成本的安全网：没有循环时不产生任何开销，检测到循环时立刻止损。
工作原理
- 每次
turn_end时，提取助手消息中的工具调用 - 与最近
windowSize轮的历史记录比较 - 如果发现
maxRepeats轮相同的调用（连续或交替），注入引导消息并重置历史 session_shutdown时清空历史
开源协议
MIT License
Copyright (c) 2026 GDWhisper