3.2 pi-shepherd 原理:规则驱动的钩子系统

Shepherd 是 pi-atelier 的“神经系统“–它不提供工具或命令,而是通过事件钩子连接所有其他扩展。

架构概览

pi 事件总线
     │
     ├─ before_provider_request  ← Shepherd 在此注入临时提示
     │
     ├─ tool_call                ← Shepherd 拦截/改写工具调用
     │      │
     │      ▼
     │   工具执行
     │      │
     │      ▼
     ├─ tool_result              ← Shepherd 检查结果、触发后续动作
     │
     ├─ agent_end                ← Shepherd 触发收尾工作
     │
     └─ session_shutdown         ← Shepherd 清理临时状态

核心概念

规则(Rule)

每条规则是一个 JSON 对象,定义了“什么时机、什么条件、做什么动作“:

规则 = 钩子时机(hook) + 匹配条件(conditions/pattern) + 动作(action) + 提示(reason)

动作类型详解

状态追踪（State）

Shepherd 内部维护了工具调用的状态计数器：

"state": { "countKind": "errors", "gte": 5 }

这表示“累计错误 ≥ 5 次时触发”。countKind 支持：

• "errors"：工具返回错误时计数
• "calls"：工具被调用时计数

message_end 钩子

message_end 是一个特殊的钩子时机：它在 AI 回复完成之后触发，匹配的是 AI 输出的文本内容，而不是工具参数。这让 Shepherd 可以“监听” AI 说了什么，并在发现问题时注入纠正。

AI 回复完成
     │
     ▼
┌──────────────────────────────┐
│  Shepherd message_end 钩子    │
│  正则匹配 AI 回复文本         │
└──────┬───────────────────────┘
       │
   匹配到了？
   ├── 是 → steer 静默注入纠正（下一轮生效）
   └── 否 → 无操作

与 tool_call/tool_result 的区别：

典型用法见 场景 7：拦截 AI 的错误归因猜测。

跨扩展通信

Shepherd 通过 pi.events 事件总线接收其他扩展的“提示“(hint):

其他扩展发出 hint → pi.events.emit("ephemeral:hint") → Shepherd 收集
                                                                 │
before_provider_request 时 → Shepherd 把收集的 hints 注入 AI 上下文

这种机制让扩展之间可以协作而不需要直接依赖。

规则加载流程

1. 加载扩展包内的 rules.json(全局默认规则)
     │
     ▼
2. 加载全局自定义规则 ~/?pi/agent/shepherd-rules.json(通过 shepherd_rules 工具管理)
     │
     ▼
3. 扫描项目目录下的 .pi/shepherd-rules-*.json(项目规则)
     │
     ▼
4. 规则叠加生效(项目规则覆盖同名全局规则)

规则文件变更后即时生效,无需任何操作。

shepherd_rules 工具的 scope 参数

shepherd_rules 工具的 scope 参数控制操作目标:

• global(默认):操作 ~/.pi/agent/shepherd-rules.json,所有项目生效
• project:操作 .pi/shepherd-rules.json,仅当前项目生效

list 操作不传 scope 时,返回全局 + 项目合并列表(标注每条规则的来源)。

配置

Shepherd 的配置支持三层合并（默认值 → 全局 settings → 项目 settings），可以在 .pi/settings.json 中按需覆盖。

📖 完整配置参数，见 pi-shepherd README。

下一步

了解 Shepherd 如何守卫 AI 行为后,下一节我们看 Context Manager 如何控制信息质量。