1. 背景与项目概述

  • Pi (@earendil-works/pi)：由 Earendil Works 开发的极简终端编程 Agent Harness。其核心哲学是模块化与零臃肿，支持通过 TypeScript 扩展、Skills、Prompt 模板进行定制。
  • Jev (TypeSafe AI)：非自回归 System One 决策模型，以毫秒级响应（~100ms）和极低成本（$0.042/MTok）专门进行结构化判断。
  • pi-typesafe 与 pi-warden：社区将 Jev 接入 Pi 编程 Harness 的官方/主流实现方案。

2. pi-warden 的核心架构与机制

pi-warden 充当主编程智能体的“第二双眼睛（副驾驶/监工 Warden）”，在不打扰人类用户的前提下实时监督和纠偏主 Agent 的行为。

[用户指令]
   ↓
[Pi 主 Coding Agent] (如 Claude / DeepSeek / GPT-4o 负责写代码、跑命令)
   │
   ├── (每次写文件 / 运行命令前)
   ▼
[pi-warden 监工插件] ───→ 调用 [TypeSafe Jev (System 1)]
   │                            │
   │                            ├── 检查是否违反 pi-warden.md 规范
   │                            ├── 检查是否陷入重复报错死循环
   │                            ├── 检查是否未经测试就自称 "done"
   │                            └── 检查是否产生低质无用废话 (slop)
   ▼
[纠偏 Nudge] ─── (将规则精确回灌给主 Agent 上下文，纠偏其路径)

3. 核心监控与拦截能力

  1. 项目规则确定性执行 (Rule Enforcement)

    • 在项目根目录维护 pi-warden.md；
    • 智能体每次触发文件写入（write/edit）时，Jev 快速评估是否违规；
    • 违规时直接在上下文中提供轻量 Nudge，引用被违背的规则进行纠偏。

  2. 防卡死与死循环打破 (Loop Breaking)

    • 监控工具调用历史，利用 Jev 的 stuck 概率评估，一旦识别到智能体在同一个报错上反复重试，主动阻断并强制切换思路。

  3. 虚假完成拦截 (Fake-Done Verification)

    • 严厉制止智能体“宣称已完成但实际上单元测试尚未通过”的行为。

  4. 废话与劣质代码治理 (Slop Management)

    • 拦截大模型生成的冗长样板代码、过度解释等废话输出。

  5. 高危命令截留 (Destructive Action Hold)

    • 拦截未经审计的破坏性 shell 指令。

4. 安装与使用指南

安装依赖

# 在 Pi Agent 中直接通过包管理安装
pi install npm:pi-warden

启用插件

在 Pi 终端交互中执行：

/warden enable

底层依赖链

  • pi-warden 基于 pi-typesafe 统一 SDK 构建，需配置 TYPESAFE_API_KEY 环境变量。

5. 关联知识与扩展

本文归档于个人知识库 · 领域：CS & AI · 模块：04 Project_CS_AI/AI apps