Pi Jev Guard

# Pi Jev Guard

原版 Pi Coding Agent 插件：按时机配置规则，并自带风险检查、输出脱敏、重复失败和缺少验证提醒。

0.2.1 支持 `/jevguard login` 配置 API key，验证后立即生效。

支持交互添加规则：安装后运行 `/jevguard add`，依次选择 **检查时机 → 本地匹配或 Jev 判断 → 命中后的动作**。无需修改插件源码。

适配并测试：`@earendil-works/pi-coding-agent 0.85.1`，Node.js 22.19+。这是独立的实验性插件，不是 TypeSafe 或 Pi 官方产品。当前提供 Pi 适配器；DSH 适配器尚未实现，判断与追踪模块可复用。

## 可以做什么

| 场景 | 默认 guard 模式 |
| --- | --- |
| 凭据上传，例如 curl 上传 `.ssh/id_rsa` | 不设置专门的本地拦截或确认；走普通 Jev／自定义规则，未配置时放行 |
| 递归删除、丢弃 Git 修改、强制推送、非传输类凭据文件访问 | 确认这一次操作；没有交互界面时拦截 |
| 其他 shell、write、edit、自定义工具调用 | Jev 同时判断破坏性、未经授权的数据外传、偏离任务和规则冲突 |
| 疑似违反 AGENTS.md 或偏离要求 | 给 Agent 一条可见提醒，不自动回滚文件 |
| 相同参数产生三次相同错误 | 提示检查原因、换方法或说明阻塞，每种错误只在第三次提醒 |
| 观察到源码或配置写入，之后没有成功验证记录 | 收尾时提醒执行相关检查，或说明为什么不适用／未执行 |
| 工具结果包含已知凭据样式 | 本地替换文本及元数据中的凭据；可再用 Jev 判断残留凭据并隐藏结果 |

`read`、`grep`、`find`、`ls` 的执行前检查只运行本地凭据路径规则。它们的结果仍接受输出处理。一次 Jev 动作检查同时发送四个问题；默认额外检查一次非空文本输出。默认配置下，未配置 API key 时不发送网络请求，只有本地规则、脱敏与证据追踪生效。自定义语义规则会执行自己声明的 onError。

## 安装与试用

直接从 GitHub 安装：

```sh
pi install https://github.com/zszz3/Pi-Jev-Guide
```

已打开的 Pi 会话运行 `/reload`，然后运行 `/jevguard login` 配置 key，用 `/jevguard add` 添加规则。

在这个项目目录安装运行依赖，然后登记为本地 Pi 包：

```sh
npm install --omit=dev
pi install /absolute/path/to/pi-jev-guard
```

### 配置 API key

在 Pi 里输入一个命令：

```text
/jevguard login
```

在隐藏输入框粘贴 TypeSafe API key，按 Enter。插件用一条固定测试请求验证，成功后保存并立即启用 Jev，后续启动自动读取，不需要环境变量或重启。Esc 取消；验证或保存失败时保留原配置。

- `/jevguard status`：查看是否启用以及 key 来源，不显示 key。
- `/jevguard login`：也可用来更换 key。
- `/jevguard logout`：删除保存的 key，回到本地检查；自定义语义规则仍按 `onError` 处理。

Key 保存在 Pi 用户目录的 `jev-guard/auth.json`（通常为 `~/.pi/agent/jev-guard/auth.json`），是权限为 `0600` 的明文凭据文件，不在项目配置或会话记录中。输入框只显示星号；不要把 key 放在命令参数中。验证请求只包含固定测试文本，不包含项目内容；启用后，正常语义检查会将脱敏后的相关上下文发送到 TypeSafe。

无交互界面的自动化仍可使用 `TYPESAFE_API_KEY`。保存的 key 优先于环境变量；退出登录后，如环境变量仍存在，会回退到该 key 并明确提示。模型、超时和阈值环境变量