jiezeng2004-design/PatchWarden

English · 简体中文
> **让 ChatGPT 规划，本地 Agent 执行，但别把整台电脑直接交给它。**
>
> PatchWarden 把 ChatGPT 和 Codex CLI、Claude Code、OpenCode 等本地 Agent 连起来，只在你批准的工作区和验证边界内执行，并留下可检查的 Diff、验证和审计证据。
它不是通用远程 Shell，而是一条 **受控、可验证、可审计的 Agent 执行通道**。
下载最新 Windows 版本 · 快速开始 · 连接 ChatGPT · 安全边界
真实工作流演示。敏感信息已遮挡。
为什么需要 PatchWarden
直接让远程 AI 控制本地开发环境，最难的不是“能不能执行”，而是：
- 它到底能访问哪些目录？
- 能不能随便跑命令？
- Agent 说“测试通过”时，有没有独立证据？
- 改了哪些文件，是否超出批准范围？
- 最终是谁、基于什么证据接受了这次修改？
PatchWarden 把这些问题放进执行链路本身：
你能得到什么
- **工作区边界**：任务只能在配置的 workspaceRoot 内运行。
- **Agent 边界**：只调用你本机已经安装并配置好的 Agent。
- **命令边界**：验证命令必须匹配允许列表。
- **真实 Diff**：不只相信 Agent 的自然语言总结。
- **独立验证**：验证步骤和任务执行分开记录。
- **审计记录**：保留 request / task / lineage / audit 状态。
- **人工验收**：最终接受动作绑定到当前证据，而不是简单改一个 JSON 状态。
适合谁
如果你想：
- 在 ChatGPT 里规划和监督本地开发任务；
- 继续使用 Codex CLI / Claude Code / OpenCode 作为真正执行者；
- 又不想给远程模型一个无限制 Shell；
- 希望每次修改都有可复查证据；
PatchWarden 就是为这种工作流做的。
5 分钟快速上手
1. 下载
从 Latest Release 下载 Windows x64 安装版或便携版。
当前安装包若未代码签名，Windows SmartScreen 可能提示未知发布者。请先用同一 Release 中的 SHA-256 校验文件核对安装包。
PowerShell：
2. 准备本地 Agent
至少安装并登录一个：
- Codex CLI
- Claude Code
- OpenCode
从源码或 npm 运行时需要 Node.js 20+；建议同时安装 Git 以生成可靠 Diff。
3. 选一个专用工作区
不要把磁盘根目录、用户主目录、桌面、下载目录直接作为 workspaceRoot。
建议给 PatchWarden 一个专门的项目目录，只放你明确允许它操作的仓库。
4. 检测 Agent
打开 PatchWarden Desktop：
至少一个 Agent 应显示可调用。如果 CLI 尚未登录，先在独立终端完成登录，再回到 PatchWarden 重新检测。
5. 确认本地健康状态
在 **开始使用** / **高级控制台** 中确认工作区、Agent 和 Core 服务正常。
到这里，即使还没连接 ChatGPT，PatchWarden 的本地执行边界也已经可以先单独验证。
连接 ChatGPT
ChatGPT Web 需要通过当前 OpenAI 支持的安全 MCP Tunnel / custom app 连接方式访问本地 PatchWarden。
典型流程：
1. 准备 tunnel-client；
2. 创建名为 PatchWarden 的专用 Core Tunnel；
3. 使用具备 **Tunnels Read + Use** 权限的专用 runtime key；
4. 在 PatchWarden 的 **设置 → MCP 与隧道** 中配置并验证；
5. 在 ChatGPT Developer mode 中添加 PatchWarden，Authentication 选 **No Auth**；
6. 保留适合你工作区风险等级的确认策略。
连接时请保持这些边界：
- 这个 runtime key 对应 CONTROL_PLANE_API_KEY，不是普通 OPENAI_API_KEY；
- OPENAI_ADMIN_KEY 可以用于管理 Tunnel，但不应作为长期运行密钥；
- 不要把 runtime key 填进 ChatGPT 的 Authentication 字段；
- Direct 是可选的第二 Tunnel，只有需要 Direct 工具时才创建；
- Direct 不是只读通道。它提供受工作区边界、敏感路径和确认策略约束的文件编辑能力（包括补丁、创建、移动和删除）；只有明确需要时才启用，并保留人工确认；
- 如果直接启用本地 HTTP MCP（不经过 stdio Tunnel），必须先配置 PATCHWARDEN_OWNER_TOKEN。匿名 /healthz 只返回最小状态，详细 health 与 /mcp 都要求 owner token。
> Tunnel runtime key 是运行连接所需的本地秘密，不要写进 README、Prompt、截图或 Git 仓库。
连接完成后，先做只读检查：
第一个可审计任务
建议第一次只在可丢弃的 Demo 仓库中测试：
不要只看 Agent 说“完成了”
一次可靠的任务结果至少应该能回答：
| 证据 | 你要确认什么 |
| --- | --- |
| task_id / lineage_id | 这次工作能否唯一追踪 |
| changed files | 是否只改了批准范围 |
| verification | 真实验证命令是否通过 |
| out-of-scope changes | 是否为 0 |
| audit | 独立审计是否接受 |
| local attestation | 是否用 patchwarden-attest 对当前证据做了人工验收 |
| final lineage | 整条工作流是否完整结束 |
审计通过后，任务通常仍是 ready_for_review。权威验收需要在本地 TTY 执行：
PatchWarden 的目标不是让 Agent “更会说自己做对了”，而是让你能检查它到底做了什么。
安全边界
PatchWarden 的核心原则：**能力最小化 + 证据优先**。
- 工作区必须显式配置；
- 不把任意本机路径默认暴露给远程模型；
- 验证命令受允许列表限制；
- Direct 是可选的受限编辑能力，不是只读验证通道；它应保持更严格的工作区边界、敏感路径和确认策略，未启用时不要在提示词里引用它；
- 本地 HTTP MCP 的敏感接口要求 owner token；