# Guardian 改编来源

本插件 `0.4.0` 引入 OpenAI 官方 [openai/codex](https://github.com/openai/codex) 的 Guardian 策略与实现设计；`0.5.0` 进一步移除本地候选操作白名单、采用上游默认风险阈值并加入只读调查。固定上游提交为 [`388aee4b26226778701a7fa749354c44f74b4394`](https://github.com/openai/codex/tree/388aee4b26226778701a7fa749354c44f74b4394)，不是随 `main` 动态变化。

上游许可为 Apache-2.0，原文及原始 NOTICE 完整保存在 [许可证](third-party/codex/LICENSE) 和 [上游 NOTICE](third-party/codex/NOTICE)。本包的 [NOTICE](NOTICE) 标明改编。上游 NOTICE 中的 Ratatui 说明随原文保留；本次没有移植 Ratatui 代码。

| 本包文件 | 固定上游路径 | 改编内容 |
| --- | --- | --- |
| `src/guardian-policy.md` | `codex-rs/prompts/templates/guardian/policy.md` | 原文保留 |
| `src/guardian-template.md` | `codex-rs/prompts/templates/guardian/policy_template.md` | 保留风险、授权、证据与精确操作评估；使用 Pi 来源标签、宿主指令、本地只读 API 和人工回退；采用原默认风险阈值 |
| `src/guardian-assessment.ts` | `codex-rs/ext/guardian-reviewer/src/assessment.rs` | TypeScript 实现；接受低风险 `{"outcome":"allow"}` 及上游字段默认值；保留严格 JSON、重复键/额外字段检查，额外支持 `ask`；Navigator 要求本地新增的 `navigator_scope`，独立限制最终任务实现 |
| `src/auto-policy.ts`、`extensions/permissions.ts` 的路由部分 | `codex-rs/core/src/tools/approvals.rs`、`codex-rs/core/src/guardian/review.rs` | 将注册工具的完整操作及来源送审；不再用文件/命令白名单代替风险审阅；保留普通只读快速路径 |
| `src/review-context.ts` | `codex-rs/guardian-context/src/lib.rs`、`codex-rs/guardian-context/src/cursor.rs` | 将来源分离与上下文边界适配到 Pi 当前分支和正式 SessionProjection；遵循 compaction、branch summary 和 context_edit；本地额外区分无消息与证据不可用，后者跳过 Guardian、清空 checkpoint 并转人工，状态绑定审批指纹 |
| `src/reviewer.ts` | `codex-rs/ext/guardian-reviewer/src/conversation.rs`、`prompt.rs`、`review_state.rs`、`deadline.rs` | 独立审核会话、完整/增量证据、checkpoint、预算重建、只读调查续轮、统一取消与截止时间 |
| `src/review-tools.ts` | `codex-rs/core/src/guardian/review.rs` 中只读审阅环境的设计 | 本地重新实现三个有界文件 API；不移植 shell 或 OS 沙箱；读取事实在批准执行前复核 |
| `src/approved-input.ts`、`extensions/permissions.ts` 的绑定/提交部分 | `codex-rs/core/src/guardian/review_request.rs`、`review.rs` | 将不可变操作和授权版本复核适配为参数快照、证据指纹、目标再检查和获批 JSON 参数冻结；JSON 类型依赖 Pi 校验，冻结实现由包内 plan-mode 共用；不是逐行 Rust 翻译 |

以上路径均相对于固定提交的仓库根目录。`guardian-policy.md` 的上游 SHA-256 为 `e6b0cf0a2e1c4cabc0a37ac2a0bc424ddd7c89e85d049e32d281a8db6e8d3ce6`。0.5.0 重新下载核对了 assessment、policy_template、review、review_request、reviewer_config 与 approvals，哈希均与固定记录一致。原始文件 URL、哈希及历史验收保存在维护者工作副本的 `quality/` 目录，不入库、不随 npm 包分发。

## 与官方实现的差异

- 本插件覆盖 Pi `tool_call`；没有移植 Codex 的执行沙箱、授权缓存、异步审查、插件/技能信任注册表、认证历史检索、后台会话服务或模型选择策略。
- 普通只读操作由本地规则直接放行；其余已注册工具均可审阅，包括任意命令、配置修改、项目外路径和 MCP。注册元数据是事实，不是信任或授权证明。
- 默认阈值与固定上游对齐：没有更严格规则时，low/medium 不额外要求授权等级；high 要求范围明确、至少 medium 授权且不违反禁止规则；critical 拒绝。额外的 `ask` 用于必要事实不明、服务故障等人工回退。
- auto 支持上游低风险短格式和字段默认值；Navigator 在该风险规则上增加本地用途策略及必填 `navigator_scope`：仅调查可自动放行，最终任务实现拒绝，不确定用途转人工。用途策略与上游 Guardian 无关，不改写固定来源原文；两种模式的审核 checkpoint 分离。
- 仍不接受上游容错解析所接受的外围文字、重复键和模式契约外的额外字段。无效输出不会猜测为允许。
- 审阅器只有本地路径元数据、文件片段和目录列举三个只读 API，没有 shell、网络、写入、MCP 或任意代码执行。敏感文件正文与疑似秘密不提供，图片与已压缩移除的授权也无法恢复；必要事实无法获得时可能转人工。
- 用户授权来自当前投影保留的原始 user 文字和宿主提供的主代理指令；assistant、摘要、工具状态和调查结果有独立来源。混合图片消息只保留文字，并标记图片缺失。改写或省略的条目不能制造新授权。角色标签不是身份签名，同进程的恶意扩展不在本插件隔离能力之内。
- 审批模型由使用者选择，复用 Pi 的提供方和认证；没有依赖 Codex 登录，也没有复制、训练或分发 `codex-auto-review` 模型。调查的普通文件片段与完整操作会发送到该模型服务。
- 上下文只在内存中短期保留并逐次发送；不缓存许可，不保证服务端缓存、费用或延迟。取消、故障及模式/模型/运行/会话变化会清空状态，不写独立正文日志。

Pi 的加载、人工确认、模型偏好恢复和界面适配仍由本仓库实现。验证过的具体行为见验收记录，不将这次适配描述为完整 Codex 权限运行时的移植。

## Plan Mode 参考来源

Plan Mode 参考同一个固定的 Codex 提交 `388aee4b26226778701a7fa749354c44f74b4394`。Pi 侧使用 Apache-2.0 来源中的工作流设计和交互文案，界面由 Pi 的 Markdown、对话与输入框组件实现。

| 固定上游路径 | 本地适配 |
| --- | --- |
| [`codex-rs/collaboration-mode-templates/templates/plan.md`](https://github.com/openai/codex/blob/388aee4b26226778701a7fa749354c44f74b4394/codex-rs/collaboration-mode-templates/templates/plan.md) | `plan-mode/src/prompts.ts` 采用调查、澄清和实施决策三阶段。通过普通对话收集必要的选择，用 Pi 的 `save_plan` 保存和 `exit_plan_mode` 提交完整版本。只读范围沿用 Pi 的工具规则。 |
| [`codex-rs/tui/src/history_cell/plans.rs`](https://github.com/openai/codex/blob/388aee4b26226778701a7fa749354c44f74b4394/codex-rs/tui/src/history_cell/plans.rs) | `plan-mode/src/proposal-card.ts` 参考置于底色之外的 `Proposed Plan` 标题和可重排的 Markdown 正文，使用 Pi 的主题和会话记录。 |
| [`codex-rs/tui/src/chatwidget/plan_implementation.rs`](https://github.com/openai/codex/blob/388aee4b26226778701a7fa749354c44f74b4394/codex-rs/tui/src/chatwidget/plan_implementation.rs) | `plan-mode/src/review-dialog.ts` 采用底部 `Implement this plan?` 选择，保留原有修订入口。实施在同一 Pi 会话中通过已保存版本获得审批。 |
