mirror of
https://github.com/SikongJueluo/pi-extensions.git
synced 2026-10-05 11:52:55 +08:00
SikongJueluo
d91ae12a55
- emit a non-blocking ai-bash-judge auto-allowed notify with the judge reason whenever Enforce authority grants an ask without a dialog - raise reason and focus caps from 180/120 to 600/240 code points so ordinary model reasons wrap completely instead of ending mid-sentence - treat the cap as a pathological-output guard, not a display budget - cover sanitization, disabled paths, and completeness in tests
91 lines
4.2 KiB
Markdown
91 lines
4.2 KiB
Markdown
# pi-permission-ai-judge
|
||
|
||
pi 的 Bash 权限 AI 判官：每条待确认的 Bash 命令先交给模型，得到 allow / deny / defer（拿不准）三种判决之一。
|
||
|
||
## 模式
|
||
|
||
- **shadow**（默认）：判决只写日志，弹窗照旧。适合先观察模型判断质量。
|
||
- **enforce**：判决 allow 时跳过弹窗直接执行，其余情况照常弹窗。只减少弹窗，不会自动拒绝。
|
||
|
||
enforce 是自担风险的便利模式：模型误判，危险命令可能在无人确认时执行。退出方式：mode 改回 shadow。
|
||
|
||
## 弹窗意见挂件
|
||
|
||
每次弹窗出现前，判官会在编辑器上方挂一个意见面板，说明自己的判断和理由，长命令会标注重点片段（focus 行）：
|
||
|
||
```
|
||
ai-judge defer — command rewrites published history; intent not established
|
||
focus: git push --force origin main (high-risk: history_rewrite)
|
||
```
|
||
|
||
三态：`defer/deny/allow` 判决带理由（shadow 模式标 `(shadow)`）；高风险跳过标类别；模型不可用/超时/异常标 `unavailable`。弹窗被处理后挂件自动消失。配置 `dialogAdvice: false` 关闭。
|
||
|
||
Enforce 模式下判官代批（auto-allow，无弹窗）时会发一条非阻塞通知 `ai-bash-judge auto-allowed — <理由>` 留痕，代批决策可审计。
|
||
|
||
## 安装
|
||
|
||
```bash
|
||
pi install npm:@sikongjueluo/pi-permission-ai-judge
|
||
```
|
||
|
||
或从仓库安装：
|
||
|
||
```bash
|
||
pi install github.com/SikongJueluo/pi-extensions
|
||
```
|
||
|
||
前提：项目启用 [`@gotgenes/pi-permission-system`](https://github.com/gotgenes/pi-permission-system) ≥ 32，并把判官挂进授权链（链按书写顺序依次咨询，仅 UI 会话生效）：
|
||
|
||
```json
|
||
// .pi/extensions/pi-permission-system/config.json
|
||
{ "authorizerChain": ["inner-cmd", "ai-bash-judge"] }
|
||
```
|
||
|
||
## 配置
|
||
|
||
`~/.pi/agent/pi-permission-ai-judge.config.json`，会话启动时读取，改动下个会话生效。
|
||
|
||
```json
|
||
{
|
||
"version": 2,
|
||
"mode": "enforce",
|
||
"model": { "provider": "openai-codex", "id": "gpt-5.6-sol" },
|
||
"timeoutMs": 30000
|
||
}
|
||
```
|
||
|
||
| 字段 | 说明 |
|
||
|---|---|
|
||
| `version` | 不写按 v1 处理，v1 的 enforce 不生效；要用 enforce 写 2 |
|
||
| `mode` | `shadow`（默认）或 `enforce`，非法值回退 shadow |
|
||
| `model` | 可选，固定判官模型；不写则跟随会话模型。解析失败按故障处理并弹窗，绝不静默改用会话模型 |
|
||
| `timeoutMs` | 单次判决等待上限，5000–30000，默认 15000 |
|
||
| `dialogAdvice` | `true`（默认）或 `false`；弹窗期间的判官意见挂件开关 |
|
||
|
||
## enforce 的防线
|
||
|
||
**高风险命令永远弹窗。** 四类形状硬编码在代码里，enforce 下命中即跳过模型、交回人工；规则不可配置，不解析别名/脚本/变量展开——是兜底，不是沙箱：
|
||
|
||
- 数据丢失/历史重写：`git clean -xfd`、`git reset --hard`、`git push --force`、`rm -rf ~` 等
|
||
- 发布/部署/基础设施销毁：`npm publish`、`terraform destroy` 等
|
||
- 提权/系统修改：`sudo`、`mkfs`、`dd of=/dev/*`、`shutdown` 等
|
||
- 凭据读取/输出/删除：`cat ~/.ssh/id_*`、`~/.aws/credentials`、`~/.gnupg` 等
|
||
|
||
**运行时自检。** 审计日志写入失败、遥测异常、模型返回格式不对、会话已关闭——任一出现，当次弹窗，不放行。
|
||
|
||
## 推荐模型目录
|
||
|
||
`models-catalog.json`（包根）列出实测过的判官模型（测试时间、prompt/语料版本、匹配数、延迟分布），逐例报告在 `reports/`。"推荐"只代表兼容性实测通过，不是安全认证；目录外的模型仍可用于 enforce（不拦截），仅会话开始时提示未经测试。
|
||
|
||
## 日志与工具
|
||
|
||
- **审计日志**：`~/.pi/agent/extensions/pi-permission-ai-judge/logs/audit.jsonl`，逐条落盘；写入失败则 enforce 停止代批
|
||
- **离线分析**：`npx tsx src/analyzer/cli.ts <review-log> --audit <audit-log> --after <t> --before <t>`
|
||
- **语料回放**：`npx tsx tools/corpus-replay.ts --provider <p> --model <m> --timeout-ms N [--strict]`，21 用例，需真实端点。`--strict`：全对、零故障、延迟达标才 exit 0，否则 exit 2（setup 失败 exit 1）；不加则只出报告
|
||
- **测试**：`pnpm check && pnpm test`
|
||
|
||
## 文档
|
||
|
||
- 风险契约与治理：ADR 0008；审计自持：ADR 0006；不可逆边界：ADR 0007——见 `docs/adr/`
|
||
- 历史 cohort 报告：`docs/testing/`
|