W
AI-Wiki
← 开源项目

y0usaf/pi-jev

已整理
https://github.com/y0usaf/pi-jev

pi-jev 为 Pi 编程代理增加了一层自动风险判断,帮助在执行命令、写文件或编辑文件前发现破坏性操作、越权操作和数据外传风险。它适合使用 Pi coding agent、希望让自动化编码流程更可控并减少误操作的人。

项目简介

pi-jev 为 Pi 编程代理增加了一层自动风险判断,帮助在执行命令、写文件或编辑文件前发现破坏性操作、越权操作和数据外传风险。它适合使用 Pi coding agent、希望让自动化编码流程更可控并减少误操作的人。

官方仓库资料

主要语言
TypeScript
许可证
MIT
默认分支
main
Stars
140
Forks
9
Open Issues
1
仓库状态
正常运行
派生仓库
非 Fork
数据采样
2026/9/23 19:08:15
资料抓取
2026/9/23 19:08:15
首次收录
2026/9/23 19:04:11

Topics:guardrails · jev · pi-extension · pi-package · typesafe

AI 整理 · 基于已抓取的官方资料

核心功能

  • 工具调用前置 gate:在 bash、write、edit 调用执行前判断是否具有破坏性、是否会外传本地数据或密钥、是否超出用户请求范围,以及潜在影响程度。
  • 默认 shadow 模式:被标记的调用只产生通知和状态提示;enforce 模式下会在有界面时要求确认。
  • 失败开放策略:缺少 API key、超时、429、响应格式错误等情况下不会阻止工具调用。
  • 缓存与请求合并:相同输入会在 cacheSeconds 时间内复用判断,同一助手消息中的同级调用共享进行中的请求。
  • 输出判断器:对 bash 的 tool_result 判断是否泄露密钥,以及将失败归类为 transient、environment、code_bug、permission、user_error 或 no_failure。
  • 泄露提示:当输出可能包含密钥时,会追加不要重复该值的提示并发送通知。
  • 失败建议:根据失败分类追加对应处理建议,例如重试、修复环境、修复代码、不要重试或修正调用方式。
  • jev_ask 工具:支持 noul、choice、score 等类型化问题,返回概率、选项分布或评分,供代码分支使用。
  • 会话命令:提供 /jev、/jev on、/jev off、/jev mode、/jev last、/jev output、/jev check 等命令查看状态和调试判断。
  • 配置分层:支持用户级 ~/.pi/agent/pi-jev.json 和项目级 .pi/pi-jev.json,项目配置优先且按键覆盖。
  • 敏感内容裁剪:发送给 TypeSafe API 的工具参数和输出会按配置截断,避免超长内容完整离开本机。

适用场景

  • 在 Pi coding agent 执行 bash、write、edit 之前提示潜在危险操作。
  • 在自动化编码会话中识别可能删除文件、强推代码或修改非用户请求范围内容的操作。
  • 检测 bash 输出中是否出现密钥、凭据或私钥内容,并提醒不要在回复、文件或命令中重复。
  • 根据命令输出判断失败原因,辅助决定是重试、修复环境、修复代码还是停止重试。
  • 让模型通过 jev_ask 对工具输出、diff 或消息提出结构化问题,并获得概率、分类或评分结果。
  • 在 shadow 模式下观察风险判断结果,评估是否适合切换到 enforce 模式。

使用方式

install: pi install npm:@y0usaf/pi-jev api_key: - TYPESAFE_API_KEY 环境变量

  • 配置文件中的 apiKey
  • 配置文件中的 apiKeyFile,支持 ~/ 展开 config_files: - ~/.pi/agent/pi-jev.json
  • .pi/pi-jev.json example_config: apiKeyFile: ~/keys/typesafe.txt model: jev-latest maxStateChars: gate: enabled: mode: shadow tools: - bash
  • write
  • edit argumentChars: cacheSeconds: minConfidence: blockWithoutUI: blockOn: destructive: exfiltration: beyondScope: impact: output: enabled: tools: - bash outputChars: leakThreshold: minConfidence: commands: - /jev 显示模式、模型、密钥来源、被判断的工具和缓存大小
  • /jev on 启用本会话中的 gate 和输出判断器
  • /jev off 关闭本会话中的 gate 和输出判断器
  • /jev mode shadow|enforce 切换 gate 模式
  • /jev last 打印最近一次 gate 判断结果
  • /jev output 打印最近一次输出判断结果
  • /jev check <text> 对给定文本运行 gate 问题 jev_ask_example: state: the tool output, diff, or message to judge questions: - id: relevant type: noul instructions: Is this relevant to the user's question?
  • id: label type: choice instructions: Which bucket? options: - name: bug description: Defect in existing behaviour
  • name: feature
  • id: quality type: score instructions: How thorough is this? levels: - Superficial
  • Adequate
  • Thorough

技术特点

  • 项目语言为 TypeScript。
  • Jev 返回的是可供代码分支使用的数字化、类型化结果,而不是自然语言文本。
  • gate 的四个问题会合并为一次请求。
  • 默认 gate 阈值包括 destructive 0.90、exfiltration 0.70、beyond_scope 0.85、impact 2.50。
  • headless 运行无法显示确认提示;enforce 模式在这种情况下会退回警告,除非设置 gate.blockWithoutUI。
  • 输出判断默认只判断 bash,README 说明判断每个 read 会导致每打开一个文件就产生一次请求。
  • 每次判断会向 api.typesafe.ai 发送工作目录、工具名、最近用户消息的前 1200 个字符和工具参数。
  • write 和 edit 的工具参数可能包含文件内容。
  • 输出判断会发送 bash 结果的前 output.outputChars 个字符以及相同工具参数。
  • 超过 gate.argumentChars 的字符串字段会被截断并替换为省略标记;输出按 output.outputChars 截断。
  • API key 通过 Authorization header 发送。
  • 通知文本会在进入会话 transcript 前移除已注册的 key。
  • README 表示项目无 runtime dependencies;Pi 捆绑导入位于 peerDependencies 且不打包。
  • src/client.ts 不导入 Pi,可在 node --input-type=module 下独立运行。

限制与边界

  • 需要 TypeSafe API key;没有 key 时扩展会加载并提示一次,但不会介入。
  • 所有错误路径都失败开放,不会阻止工具调用。
  • shadow 模式是默认模式,只提示不阻止。
  • enforce 模式在无界面运行时不能显示确认提示,默认退回警告,除非配置 gate.blockWithoutUI。
  • gate 只能看到工具调用意图,不能看到命令实际输出。
  • 输出判断器不会阻止操作,只会在命中时追加提示。
  • 默认输出判断只覆盖 bash。
  • 发送到 api.typesafe.ai 的数据包括工作目录、工具名、最近用户消息片段、工具参数;write/edit 参数可能包含文件内容。
  • README 中的 gate 校准被描述为 smoke calibration,不是带标签的完整评估集,因此不足以将 gate 默认切换为 enforce。
  • 多因素问题可靠性较低,README 建议把问题拆成单因素问题。

README

README 介绍 pi-jev 是一个面向 Pi coding agent 的 TypeSafe Jev 扩展,用于把工具调用和命令输出交给类型化判断层处理。它包含工具调用前的 gate、bash 输出后的输出判断器,以及可由模型主动调用的 jev_ask。文档说明了安装方式、API key 解析顺序、配置文件位置、gate 与输出判断的阈值、运行模式、命令列表、哪些数据会离开本机,以及作者用于设定阈值的校准结果。README 还强调默认 shadow 模式、错误时失败开放、输出判断不阻塞,以及敏感字段会按配置截断。

关联 Wiki 词条

暂无已建立的词条关联。