Pi Hooks

Pi 原生扩展 —— 质量门控、安全扫描、fact-force 守卫和会话指标追踪。

移植自 ECC hooks 系统，使用 pi 的同进程事件系统替代外部进程钩子。

安装

pi install npm:@rotart/pi-hooks

安装后通过 pi.extensions 清单自动发现，无需额外配置。

架构

tool_call  → pre-tool-guards   (工具执行前拦截/告警)
tool_result → post-tool-checks  (工具执行后分析结果)
tool_result → post-bash-checks  (Bash 执行后分析结果)
agent_end  → agent-metrics     (tokens/sec, 上下文用量, 成本追踪)
session_*  → session-lifecycle (启动上下文加载, 关闭状态持久化)

功能列表

Pre-Tool Guards（工具执行前）

| 守卫 | 行为 | 说明 | |------|------|------| | GateGuard 编辑门控 | 拦截 → 重试放行 | 首次 Edit/Write/MultiEdit 每个文件时拦截，要求 agent 调查 importers、公开 API、数据 schema 并引用用户指令 | | GateGuard 破坏性命令 | 拦截 → 重试放行 | 检测 rm -rf、git reset --hard、git push --force、git clean -f、git branch -D、git stash drop、chmod 777、chown root 等不可逆命令 | | GateGuard 首次 Bash | 拦截 → 重试放行 | 每个会话首个非自省 Bash 命令被拦截，要求 agent 重申任务目标 | | Dev Server 告警 | 通知 | 提示 npm run dev 等应在独立终端运行 | | 长时间命令提醒 | 通知 | npm install、cargo build、docker build 等建议在独立终端运行 | | Git Push 提醒 | 通知 | git push 前提醒审查变更 | | Git Commit 格式检查 | 通知 | 检查 commit message 是否符合 Conventional Commits 格式 | | Linter 配置保护 | 拦截 | 禁止修改 .eslintrc、.prettierrc、biome.json 等配置文件 | | 文档文件告警 | 通知 | 创建非结构化 .md/.txt 文件时提示使用 docs/、.pi/、skills/ 等结构化路径 | | 敏感文件告警 | 通知 | 写入 .env、credentials、.pem、id_rsa 等安全敏感文件时发出提醒 |

Post-Tool Checks（工具执行后）

| 检查 | 行为 | 说明 | |------|------|------| | Console.log 检测 | 通知 | 编辑后的 JS/TS 文件中检测到 console.log 等调试语句时告警 | | 密钥检测 | 通知 | 扫描编辑内容中的硬编码密钥（AWS Key、GitHub Token、JWT、SSH 私钥、加密密钥） | | 设计质量检查 | 通知 | 前端文件编辑中检测硬编码颜色值、通用阴影等模板化反模式 | | Quality Gate | 预留 | 根据项目配置选择 Biome/Prettier/gofmt/ruff 对编辑后的文件运行格式化检查 |

Post-Bash Checks（Bash 执行后）

| 检查 | 行为 | 说明 | |------|------|------| | PR Logger | 通知 | 检测 gh pr create 完成，自动提取 PR URL 和审查命令 | | Build Analysis | 通知 | 检测 npm run build / pnpm build / yarn build / bun build 完成 |

Agent Metrics（Agent 指标）

| 指标 | 说明 | |------|------| | Tokens/sec | 每个 agent 循环的推理速度 | | 上下文用量 | 当前上下文窗口使用率（>80% 告警） | | 缓存命中 | prompt cache 读写统计 | | 会话 Token 累计 | 整个会话的 input/output token 汇总 |

Session Lifecycle（会话生命周期）

| 事件 | 说明 | |------|------| | Session Start | 恢复会话时显示消息统计和 GateGuard 状态 | | Session Shutdown | 持久化 GateGuard checkpoint 和会话结束标记 |

文件结构

hooks/
├── index.ts                # 扩展入口，注册 flags 和全部模块
├── pre-tool-guards.ts      # Pre-tool-use 守卫（11 个）
├── post-tool-checks.ts     # Post-tool-use 检查（4 个）
├── post-bash-checks.ts     # Bash 执行后检查（2 个）
├── agent-metrics.ts        # Agent 指标追踪
├── session-lifecycle.ts    # 会话生命周期管理
└── lib/
    ├── file-patterns.ts    # 文件/命令模式匹配工具
    ├── command-analyzer.ts # 破坏性命令检测
    ├── gateguard-state.ts  # GateGuard 运行时状态
    ├── secret-detector.ts  # 硬编码密钥检测
    └── formatter-resolver.ts # 项目格式化工具检测

配置

# 钩子严格度配置
pi --hooks-profile minimal    # 仅保留核心生命周期和安全钩子
pi --hooks-profile strict     # 启用全部钩子和额外提醒

# 禁用特定钩子
pi --hooks-disabled pre:edit-write:gateguard-fact-force,post:edit:console-warn

# 禁用 GateGuard（恢复/配置场景）
# 通过 --hooks-disabled 禁用对应 ID 即可

与 ECC Hooks 的对应关系

| ECC Hook ID | Pi 实现 | 行为差异 | |-------------|---------|----------| | pre:bash:gateguard-fact-force | GateGuard 编辑门控 | 同进程事件 → 更快的响应 | | pre:bash:dev-server-block | Dev Server 告警 | 通知而非拦截 | | pre:bash:tmux-reminder | 未移植 | pi 无 tmux 集成 | | pre:config-protection | Linter 配置保护 | 功能等价 | | pre:write:doc-file-warning | 文档文件告警 | 功能等价 | | post:edit:console-warn | Console.log 检测 | 功能等价 | | post:quality-gate | Quality Gate | 工具选择已实现，执行引擎预留 | | post:bash:pr-created | PR Logger | 功能等价 | | post:bash:build-complete | Build Analysis | 扩展了构建命令覆盖 | | pre:governance-capture | 密钥检测 + 敏感文件 + 提权检测 | 拆分为三个独立能力，删除了高误报的通用模式 | | stop:cost-tracker | Agent Metrics | 功能等价 | | session:start / stop:session-end | Session Lifecycle | 功能等价 |

许可证

MIT