内容
# ChatGPT 审查代理技能
使用 ChatGPT 作为 Codex 的外部代码审查者。
[中文说明](README.zh-CN.md)
支持两种模式：
- **数据包审查：** 无需 MCP。Codex 打包代码，发送/上传到任意 ChatGPT 审查模型，然后捕获回复到本地 Markdown。
- **MCP 连接器审查：** 让 ChatGPT 通过小型 MCP 服务器读取选定的本地文件。在 ChatGPT 选择的模型可以调用连接器工具时使用此功能。
在当前测试的 ChatGPT 行为中，**Pro 无法调用 MCP 连接器工具**。对 Pro 使用数据包审查。对 **高/极高** 使用 MCP 连接器审查。
## 开始前
使用此技能无需 MCP。
如果您只想使用 GPT 作为审查代理，或者不想设置连接器：
1. 请求 Codex 使用 `$chatgpt-review-agent`。
2. Codex 从相关文件中构建一个数据包 zip。
3. Codex 将其上传/发送到 ChatGPT 侧浏览器。
4. ChatGPT 回复。
5. Codex 捕获最新的回复并保存到本地。
这通常足以进行外部 GPT 审查。MCP 仅适用于更强大的工作流程，其中 ChatGPT 本身通过连接器读取本地文件。
## 安装技能
将技能文件夹复制到您的 Codex 技能目录：
```powershell
Copy-Item -Recurse .\skills\chatgpt-review-agent $env:USERPROFILE\.codex\skills\
```
安装后重启 Codex。
像这样使用：
```text
使用 $chatgpt-review-agent 请求 ChatGPT Pro 审查此更改并将审查 Markdown 保存到本地。
```
## 数据包审查
在没有 MCP、不可用、波动或不值得设置的情况下，对于任何 GPT 审查模型都使用此功能。
`<skill-dir>`、`<repo-root>` 和 `<relative/file.py>` 等路径是占位符。编码代理应从其当前工作区和技能源位置解析实际路径。
构建一个数据包：
```bash
python <skill-dir>/scripts/build_review_packet.py \
--repo <repo-root> \
--out .chatgpt-review/review-packet.md \
--zip .chatgpt-review/review-packet.zip \
--goal "审查此更改的错误和缺失测试。" \
--file <relative/file.py> \
--dir tests
```
zip 包括 `review-packet.md` 和支持文件。ChatGPT 可以读取上传的 zip 内容，因此对于多文件审查，优先使用 zip。
然后 Codex 应该：
1. 在 Codex 侧浏览器/标签页中打开 ChatGPT。
2. 选择 Pro 或任何所需的无工具审查模型。
3. 上传 `.chatgpt-review/review-packet.zip`。
4. 请求 ChatGPT 仅审查数据包，不要调用工具。
5. 等待生成完成。
6. 保存最新的助手回复，通常保存到 `.chatgpt-review/review.md`。
## MCP 连接器审查
仅当您希望 ChatGPT 通过连接器读取本地文件时使用此功能。
流程如下：
1. 启动本地 MCP 服务器。
2. 通过 HTTPS URL 使其公开。
3. 创建 ChatGPT 应用/连接器。
4. 在 ChatGPT 创作器中选择该应用，带有 `+` 按钮。
5. 烟雾测试 `list_allowed_roots`。
6. 然后请求 ChatGPT 审查文件。
### 一次性引导设置
对于初学者友好型设置，请将 `AGENT_SETUP_PROMPT.md` 提供给 Codex。
如果当前 Codex 回转无法显示选择提示，代理应告诉用户：
```text
请先单独输入 /plan 并回车。
进入 Plan 模式后，再发送：引导设置 MCP。
```
在 Plan 模式下，Codex 应推断：
- 当前仓库根目录
- Codex 技能根目录
- 操作系统
- 感性的端口，通常为 `8765`
- 公共 HTTPS URL（如果已提供）
- 是否应启用源编辑
设置助手不是问卷调查。它们读取环境变量并生成一键启动器。
Windows：
```cmd
setup.cmd
```
macOS/Linux：
```bash
sh setup.sh
```
生成的启动器：
```text
start-review-mcp.cmd
start-review-mcp.sh
```
生成的启动器默认使用持久令牌文件：
```text
.review-mcp-token
```
请保留此文件。如果它被删除，ChatGPT 可能需要连接器重新身份验证。
有用的设置变量：
```text
REVIEW_REPO_ROOT=<repo-root>
REVIEW_SKILLS_ROOT=<skills-root>
REVIEW_PUBLIC_URL=<public-url>
REVIEW_HOST=127.0.0.1
REVIEW_PORT=8765
REVIEW_ENABLE_EDIT=n
REVIEW_TOKEN_FILE=<local-token-file>
```
默认值：
- 在 `.chatgpt-review/` 下启用审查写入工件
- 允许列出的 shell 工具启用
- 源编辑禁用
- 令牌文件位于 `<this-repo>/.review-mcp-token`
仅当您明确希望 ChatGPT 端模型修改文件时，才启用直接源编辑：
```text
REVIEW_ENABLE_EDIT=yes
```
### 手动服务器启动
从此仓库运行：
```bash
python mcp_server.py \
--root <repo-root> \
--root <skills-root> \
--host 127.0.0.1 \
--port 8765 \
--public-url <public-url> \
--token-file .review-mcp-token
```
仅当您希望 ChatGPT 写入源文件时，请添加 `--enable-edit`。
健康检查：
```powershell
Invoke-RestMethod http://127.0.0.1:8765/health
```
预期：
```json
{"status":"ok","root":"<repo-root>"}
```
## HTTPS URL 选项
ChatGPT 自定义应用/连接器需要 HTTPS 端点。
临时测试可以使用任何 HTTPS 隧道 URL：
```text
https://temporary-url.example/mcp
```
稳定使用最好使用您自己的域名：
```text
https://repo.example.com/mcp
```
使用公共基准 URL 启动 MCP 服务器，而不是 `/mcp` 后缀：
```bash
python mcp_server.py \
--root <repo-root> \
--root <skills-root> \
--host 127.0.0.1 \
--port 8765 \
--public-url https://repo.example.com \
--token-file .review-mcp-token
```
检查：
```powershell
Invoke-RestMethod https://repo.example.com/.well-known/oauth-authorization-server
Invoke-WebRequest https://repo.example.com/mcp
```
`/mcp` 拒绝未经身份验证的请求是可以的。这意味着路由到达服务器。
## Cloudflare 与您自己的域名
当随机的 `trycloudflare.com` URL 太烦人时，请使用此功能。
1. 将域名放入 Cloudflare，或使用 Cloudflare 已管理的域名。
2. 打开 Cloudflare Zero Trust。
3. 进入 **Networks -> Tunnels**。
4. 创建或重用隧道。
5. 在此机器上安装/运行 Cloudflare 连接器。在 Windows 上，Cloudflare 可能提供类似的命令：
```cmd
cloudflared.exe service install <token>
```
6. 在隧道中添加 **Public Hostname**:
```text
Subdomain: repo
Domain: example.com
Type: HTTP
URL: http://127.0.0.1:8765
```
7. 您的公共 MCP 基准 URL 为：
```text
https://repo.example.com
```
8. 您的 ChatGPT 连接器端点为：
```text
https://repo.example.com/mcp
```
如果 Cloudflare 表示已存在 A、AAAA 或 CNAME 记录，请删除冲突的 DNS 记录或选择其他子域名。
如果 Cloudflare 显示 `1016`，则主机名未路由到活动隧道服务。修复隧道公共主机名映射到 `http://127.0.0.1:8765`。
## ChatGPT 应用/连接器设置
在 ChatGPT 中：
连接审查示例：
1. 打开 **Apps**。
2. 打开 **Advanced settings**。
3. 启用 **Developer mode**。
4. 创建应用。
5. 为其命名包含 `connect`，例如：
```text
connectcodex
```
`connect` 名称不是协议要求，但它使应用在创作器 `+` 菜单中易于查找，并与测试的工作流程相匹配。
6. 对于连接器/MCP URL，输入：
```text
https://repo.example.com/mcp
```
7. 完成 OAuth 流。
8. 刷新/重新扫描工具（如果 ChatGPT 提供此操作）。
9. 在 ChatGPT 创作器中，单击左下角的 `+`。
10. 选择您的应用，例如 `connectcodex`。
11. 使用可以调用工具的模型，通常为高/极高。
烟雾提示：
```text
仅使用选定的连接器。烟雾测试：仅调用 list_allowed_roots。回复是否发生了实际工具调用，并粘贴返回的根目录或确切错误。不要调用任何其他工具。
```
通过条件：
- ChatGPT UI 显示实际工具调用，并且
- 回复返回诸如 `<repo-root>` 和 `<skills-root>` 的根目录。
如果 Pro 无法调用工具，请使用数据包审查。
如果 ChatGPT 卡在寻找工具，请从创作器 `+` 菜单中重新选择应用并重试一次。
## MCP 工具
捆绑服务器公开：
- `list_allowed_roots`
- `tree`
- `read_text`
- `search_text`
- `write_review`
- `list_review_artifacts`
- `run_command`
- 仅 `--enable-edit` 时的 `write_text`
安全限制：
- 根目录必须使用 `--root` 显式允许
- 审查写入仅限于 `.chatgpt-review/`
- 源编辑需要 `--enable-edit`
- shell 是固定允许列表
- `.env`、私钥和 `.git` 等秘密路径被阻止
- `tree`、`read_text` 和 `search_text` 被限制
- 仅限标准库 Python，无包安装
允许的 `run_command` 值：
```text
git status --short
git diff --stat
git diff
python -m pytest
npm test
```
## 故障排除
**获取 OAuth 配置时出错**
- 检查 `<public-url>/.well-known/oauth-authorization-server`。
- 使用 `--public-url <public-url>` 启动服务器。
- 检查隧道路由到 `http://127.0.0.1:8765`。
**查找工具时出现消息流错误**
- 使用 `/health` 确认服务器存活。
- 从 ChatGPT 创作器 `+` 菜单中重新选择连接器应用。
- 重试烟雾提示一次。
**Cloudflare 1016**
- 公共主机名未路由到隧道目标。
- 修复隧道公共主机名服务 URL：`http://127.0.0.1:8765`。
**Pro 无法调用工具**
某些 ChatGPT 界面中预期会出现这种情况。使用数据包审查。
**工具调用似乎是假的**
除非 ChatGPT UI 显示工具调用或 MCP 服务器日志显示匹配的 `/mcp` 请求，否则将其视为未经验证的。
## 文件
```text
AGENT_SETUP_PROMPT.md
mcp_server.py
setup.cmd
setup.sh
skills/chatgpt-review-agent/SKILL.md
skills/chatgpt-review-agent/scripts/build_review_packet.py
skills/chatgpt-review-agent/references/setup.md
skills/chatgpt-review-agent/references/browser-workflows.md
```
