# ChatGPT 网页版本地 Shell Agent 0.2.1（Windows + WSL）

这套实现把 ChatGPT 官方 Developer Mode 通过 OpenAI Secure MCP Tunnel 接到本机 Shell 与代码 workspace。模型推理只发生在 ChatGPT 网页会话中；服务端代码不会调用 Responses、Chat Completions、Realtime 或其他模型 API。Runtime API key 只交给官方 Tunnel 客户端建立传输链路。

项目没有截图、鼠标、键盘、UI Automation、桌面遥控或浏览器自动化工具，也不会把 `chatgpt.com` 包装成非官方 API。

## 能力

- 读取当前用户有权限访问的 Windows / WSL 普通文本文件。
- 保留原有 WSL bubblewrap `shell_run`：无授权倒计时，随服务长期可用；宿主 home、Windows mounts 与宿主 `/var` 不可见。
- PowerShell 7 与原生 Windows 可执行文件使用 `windows_shell_open → windows_shell_prepare → windows_shell_run`；首次本机批准后授权跨 Tunnel、MCP 与登录重启保留，直到显式 `windows_shell_close`。
- Windows 与 WSL repo 都支持 snapshot、diff、冲突检测、本机确认、原子写回与恢复副本。
- workspace 只复制 Git tracked / untracked nonignored 普通文件；排除 `.env`、凭据路径、检测到凭据内容的文件、symlink、junction、reparse point、特殊文件及 Git ignored 内容。
- Windows Shell 只继承白名单环境变量，secret-like 环境变量不会传入；输出最多各 2 MiB，并在返回 ChatGPT 前脱敏。
- Windows 子进程放入 kill-on-close Job Object；超时、撤销授权或 Agent 停止时终止命令树。
- 不提权、不调用 UAC。若 Gateway 本身处于提升状态，Windows Shell 会拒绝运行。

Windows snapshot 是可审核副本，不是强安全沙箱。标准用户进程仍可能访问该用户的其他文件，因此所有非严格只读的 Windows 命令都会被当作“可影响宿主”并逐次弹出本机确认。

详细边界见 [SECURITY.md](SECURITY.md)。

## MCP 工具

文件工具：

```text
system_health
fs_stat / fs_list / fs_search_paths
fs_inspect / fs_read / fs_release
```

共享 workspace 工具：

```text
workspace_open(executor="wsl" | "windows")
workspace_status
workspace_diff
workspace_apply_back
workspace_close
```

Shell 工具：

```text
shell_run                         # 只用于 WSL bubblewrap
windows_shell_status
windows_shell_open
windows_shell_prepare
windows_shell_run
windows_shell_close
```

`windows_shell_prepare` 会把 shell、完整命令或 argv、cwd、target、用途、超时、环境摘要、网络特征与风险绑定到 5 分钟的一次性 `review_id`。执行时不能替换字段；重启后 review token 失效，但 Windows Shell 的 DPAPI 持久授权仍有效。

## Windows 命令分级

| 等级 | 行为 |
|---|---|
| `safe_query` | Shell 已授权时可执行；接受 AST 可证明为静态只读的扩展 allowlist，包括文件/进程/服务/系统信息、哈希/ACL、PowerShell 元数据，以及 Git status/diff/log/show/rev-parse/ls-files/ls-tree 等查询。 |
| `workspace_write` | cwd 映射到 Windows snapshot；ChatGPT 工具确认与 Windows 本机逐命令确认。 |
| `host_write` | 直接影响宿主或有网络/状态改变能力；ChatGPT 工具确认与 Windows 本机逐命令确认。 |
| `denied` | 提权、RunAs、EncodedCommand、命令混淆、安全防护关闭、注入、键盘记录、凭据转储或审批绕过。 |

Shell 永不返回精确凭据。合法任务确实需要原始值时，必须继续走 `fs_inspect → fs_release(mode="exact")`，并由用户在本机弹窗确认。

## ChatGPT 中的用法

WSL workflow：

```text
system_health
workspace_open(platform="windows", path="C:\path\repo", executor="wsl")
shell_run(command="...")
workspace_diff
workspace_apply_back(review_id="...", purpose="具体写回用途")
workspace_close
```

Windows workflow：

```text
system_health
windows_shell_status
windows_shell_open(purpose="在本机 repo 中构建并运行测试")
workspace_open(platform="windows", path="C:\path\repo", executor="windows")
windows_shell_prepare(
  shell="powershell",
  command="python -m pytest",
  cwd="C:\path\repo",
  target="workspace",
  purpose="运行该 repo 的测试以验证当前修改",
  timeout_seconds=120
)
windows_shell_run(review_id="...")
workspace_diff
workspace_apply_back(review_id="...", purpose="测试通过后写回已审核 diff")
workspace_close
```

`windows_shell_open` 的旧 `duration_seconds` 参数为兼容保留，在 `authorization_mode="persistent"` 下会被忽略。不要在每次任务结束时调用 `windows_shell_close`；只有你希望撤销永久授权时才调用它。停止或重启 Tunnel 不会撤销授权。

对宿主做只读查询时使用 `target="host"`。任何安装、文件写入、注册表修改、进程/服务状态改变或网络传输都会逐命令弹出本机确认。

## 安装、升级与运行

默认安装位置：

```text
%LOCALAPPDATA%\ChatGPTMCP
```

全新安装前，先在 OpenAI 控制面创建 Secure MCP Tunnel 和专用 Runtime API key。安装脚本不包含任何预置 Tunnel ID，必须显式传入：

```powershell
& .\scripts\Install.ps1 -TunnelId 'tunnel_your_id'
```

默认 Tunnel profile 名为 `chatgpt-local-coding-agent`。如需自定义：

```powershell
& .\scripts\Install.ps1 -TunnelId 'tunnel_your_id' -ProfileName 'my-local-coding-agent'
```

安装脚本会把 profile 名写入本机 `config.toml`。旧安装若还没有该配置项，Operator CLI 仅在 profiles 目录恰好有一个 YAML 时兼容发现；缺失或多个候选时会拒绝猜测。

从旧版本升级：

```powershell
& .\scripts\Upgrade.ps1
```

升级脚本先在 `%LOCALAPPDATA%\ChatGPTMCP\backups` 保存配置、脚本、已安装包与依赖清单，再安装 0.2.1、运行完整测试；只有测试通过才把 `windows_shell.enabled` 改为 `true` 并设置 `authorization_mode="persistent"`。Runtime key 不会被读取、打印或删除。

常用命令：

```powershell
& "$env:LOCALAPPDATA\ChatGPTMCP\Doctor.ps1"
& "$env:LOCALAPPDATA\ChatGPTMCP\Start-Agent.ps1"
& "$env:LOCALAPPDATA\ChatGPTMCP\Status-Agent.ps1"
& "$env:LOCALAPPDATA\ChatGPTMCP\Stop-Agent.ps1"
& "$env:LOCALAPPDATA\ChatGPTMCP\Enable-Autostart.ps1" -StartNow
& "$env:LOCALAPPDATA\ChatGPTMCP\Disable-Autostart.ps1"
```

登录任务只为当前用户注册，`RunLevel=Limited`，不使用最高权限。Windows Shell 授权记录由当前 Windows 用户的 DPAPI 加密，第一次通过 `windows_shell_open` 批准后会在登录/Tunnel/MCP 重启时恢复。WSL Shell 没有倒计时。永久授权不等于永久放行命令：Windows 非只读命令、原 repo 写回和精确敏感内容仍逐次本机确认。

ChatGPT 网页自己的工具确认是另一层：OpenAI Developer Mode 对写 action 默认要求确认，网页端“记住”只适用于当前对话，刷新或新对话可能再次询问。本机服务不能也不会绕过这一层。参见 [Developer Mode 文档](https://developers.openai.com/api/docs/guides/developer-mode)。

部署新工具定义后，到 ChatGPT 的 App/Connector 详情页执行 Refresh，审核新增的五个 Windows Shell actions。OpenAI 不会自动替你启用变更后的工具定义。参见 [Developer Mode 文档](https://developers.openai.com/api/docs/guides/developer-mode)。

## 网页额度与 API

本项目不以节省 ChatGPT 网页额度为目标。ChatGPT Plus 的模型使用限制会动态变化，MCP App 调用沿用对应 ChatGPT 会话的限制，不构成额外模型 API 调用；OpenAI API 账户与 ChatGPT 订阅则是独立计费体系。参见 [ChatGPT Plus](https://help.openai.com/en/articles/6950777-what-is-chatgpt-plus) 与 [Apps in ChatGPT](https://help.openai.com/en/articles/11487775-connectors-in-chatgpt)。

## 开发验证

通用验证范围见 [docs/VALIDATION.md](docs/VALIDATION.md)。

```powershell
python -m venv .venv
.\.venv\Scripts\python.exe -m pip install -e ".[test]"
.\.venv\Scripts\python.exe -m pytest
```

测试覆盖文件敏感分级、MCP 工具发现、WSL 无到期状态、Windows DPAPI 持久授权与显式撤销、损坏授权拒绝、Windows snapshot、Git ignored 产物、diff/apply/冲突、扩展只读 allowlist、PowerShell AST、一次性 token、环境隔离、输出脱敏、本机拒绝、超时与多级子进程清理。