Chat2Agent

<div align="center"> # 🌉 Chat2Agent **让 ChatGPT 网页端通过官方 MCP 拥有本地工作区能力的开源桥接套件** [](https://nodejs.org/) [](LICENSE) [](https://github.com/xiaoxiao341/Chat2Agent/actions) [](https://github.com/xiaoxiao341/Chat2Agent) [](https://github.com/xiaoxiao341/Chat2Agent) [](https://github.com/Embracecactus/devspace-mcp-tunnel) [](https://github.com/Waishnav/devspace) <p align="center"> <a href="#-为什么选择-chat2agent相比原版重大升级">核心升级对比</a> • <a href="#-零成本与绝对安全保障">安全与账号保障</a> • <a href="#-核心特性与硬核工程实现">核心特性与硬核实现</a> • <a href="#-windows-快速开始推荐">Windows 快速开始</a> • <a href="#-免费-ngrok-配置指南">ngrok 免费配置</a> • <a href="#-踩坑记录troubleshooting">踩坑排查</a> • <a href="#-致谢与开源协议credits--license">致谢与协议</a> </p> </div> --- > 💡 **核心定位** > 本项目的主要目标是：让**网页版 ChatGPT（包括免费版及付费版）**通过 OpenAI 官方 MCP (Model Context Protocol) 开发者连接器直接对接本机工作区，获得如同 Codex Agent 般的代码检索、文件修改、测试执行与审查能力。 > > 完整设计边界请参阅 📑 [ADR 0001: Web Agent Boundary](docs/adr/0001-web-agent-boundary.md) 与 🗺️ [产品路线图](docs/roadmap.md)。 --- ## 🛡️ 零成本与绝对安全保障 ### 1. 💰 100% 免费，普通免费账号直接起飞 - **ChatGPT 免费版可用**：OpenAI 官方已在网页端开放 **Developer Mode / MCP Connector**，普通免费账号无需订阅 Plus/Team/Pro 即可直接添加自定义 MCP 连接器！ - **免费公网隧道**：无论是自带的 **ngrok 免费套餐** 还是 **Pinggy 免费隧道**，全程无需任何花费，即可稳定打通本地与网页端通信。 ### 2. 🔒 官方正规协议，绝对 0 封号风险 - **官方开放标准**：完全基于 OpenAI 官方推行的 Model Context Protocol (MCP) 规范与标准 OAuth 2.0 流程。 - **杜绝逆向与黑产手段**：**绝不**注入网页 Cookie、**绝不**抓取网页非公开私有接口、**绝不**逆向 Token、**绝不**使用任何违规自动化爬虫脚本。对于 OpenAI 而言，这就是一个正规的第三方标准连接器，完全符合官方使用条款（TOS），**从技术底层确保 0 封号风险**。 --- ## 🚀 为什么选择 Chat2Agent？（相比原作者版本的重大升级） 本项目是在 [Embracecactus/devspace-mcp-tunnel](https://github.com/Embracecactus/devspace-mcp-tunnel) 优秀创意的基础上进行深度重构演进而来的。 原作者版本主要是 Linux 下的简易 Bash 启动脚本 Demo（共 11 个文件）。**Chat2Agent 扩展到了 66 个文件、新增 6400+ 行代码、内置 40 个自动化单元测试**，实现了工业级蜕变： | 维度 | 原作者版本 (devspace-mcp-tunnel) | Chat2Agent 增强重构版 (本项目) | | :--- | :--- | :--- | | **跨平台架构** | 仅支持 Linux/WSL 基础 Bash 运行 | **原生支持 Windows 企业级受管守护进程**（`start.bat`/`stop.bat`），同时完美兼容 Linux/WSL | | **进程生命周期** | `pkill -f` 模糊匹配，易误杀当前脚本或其它 Node | **基于 PID 树与 Linux `/proc` 启动时间戳双重校验**，100% 精准启停，杜绝误杀 | | **长进程异步轮询** | 无进程会话保持，短命令易卡死 | **实现长任务 Process Session 保持**，解决 ChatGPT 丢失 0 序列化 Bug（`yieldTimeMs: 1`），支持 `write_stdin` 异步轮询与跨 Session 恢复 | | **启动与恢复健康门控** | 启动后无探测，不知道服务是否真正可用 | **同时监测本地与公网 `/healthz`**，休眠或网络中断后自动重建 ngrok 隧道，只有两端均正常才报告就绪 | | **网页 Diff 渲染** | 使用 DevSpace 原生输出，网页端频繁**卡死、白屏** | **自研版本化内联 Diff 卡片**，解决 ngrok 拦截；仅对 `show_changes` 绑定 UI，告别 iframe 页面卡顿 | | **Codex 资源复用** | 粗暴读取全局配置或缺乏隔离 | **实现 Codex 资源只读安全镜像与隔离（ADR 0001）**，严选 3 大 Skills，绝不污染修改本地全局 Codex | | **安全沙箱 Hook** | 无工具拦截审计与安全保护 | **新增 `after_tool`/`tool_failure` 沙箱 Hook 适配器**，自动剥离密码/API Key 等敏感环境变量 | | **安全与白名单** | 粗暴继承全局 `*` 主机白名单 | **主动剔除全局通配符**，根据公网域名与回环动态派生白名单；凭据由 `.env.local` 严密保护 | | **OAuth 会话治理** | 无法管理已授权的客户端与令牌 | **内置 OAuth 数据库管理工具**，支持 Token 过期自动裁剪、按客户端撤销及一键全局吊销 | | **诊断探针工具箱** | 无配套排错与测试脚本 | **新增 6 大 CLI 探针**（`doctor:web` 深度诊断、`mcp-probe` 能力探针、沙箱自动验收测试等） | | **协议元数据监测** | 无法感知工具更新与缓存污染 | **自研版本化 URI 缓存穿透策略**（`diff-card-inline-v3.html`），Doctor 实时检测 ChatGPT 端元数据新鲜度 | | **隐私保护机制** | 无执行状态审计 | **Fail-closed 隐私最小化执行证据收集**，仅记录退出码，绝不收集用户源码和指令内容 | | **双重真实验收** | 无验收标准 | **确立自动化探针与真实网页双重验收体系**（`npm run accept:web:verify`），保证实测可见性 | | **工程与自动化测试** | 无测试用例 | **内置 16 个测试套件、40 个单元与集成测试**，配备 Windows / Ubuntu 双系统 GitHub Actions CI | --- ## ✨ 核心特性与硬核工程实现 <table> <tr> <td width="50%" valign="top"> <h3>🪟 Windows 受管进程与会话恢复</h3> <ul> <li><b>精准启停</b>：按 PID 树精准终止相关进程，绝不误杀其他 Node 或 Codex 进程。</li> <li><b>长进程 Session 轮询</b>：针对 ChatGPT 序列化丢失 <code>0</code> 的 Bug 自研 <code>yieldTimeMs: 1</code> 机制，支持 <code>write_stdin</code> 异步轮询与跨 MCP 重连恢复。</li> <li><b>健康门控</b>：<code>start.bat</code> 启动前自动执行 <code>/healthz</code> 探测与端口健康门。</li> </ul> </td> <td width="50%" valign="top"> <h3>🎨 自研版本化 Diff 与元数据穿透</h3> <ul> <li><b>解决白屏与卡死</b>：绕过 ngrok 免费隧道对外部 JS 拦截；仅对 <code>show_changes</code> 挂载内联 UI，杜绝普通工具创建 iframe 导致页面卡顿。</li> <li><b>版本化缓存穿透</b>：采用 <code>diff-card-inline-v3.html</code> 版本化资源 URI，配合 Doctor 实时监控 ChatGPT 端元数据新鲜度（Metadata Freshness）。</li> <li><b>高颜值对比</b>：按文件状态分类展示、带行号与红绿背景高亮，折叠支持原始 Git Patch。</li> </ul> </td> </tr> <tr> <td width="50%" valign="top"> <h3>🔒 严苛安全边界与 Codex 资源隔离</h3> <ul> <li><b>ADR 0001 隔离原则</b>：只读镜像 3 大审查通过的 Skills（<code>reliable-downloads</code>、<code>frame-independent-judgment</code>、<code>review-agent</code>），绝不污染修改本地全局 Codex。</li> <li><b>安全沙箱 Hook 调度</b>：支持 <code>after_tool</code>/<code>tool_failure</code> 钩子，自动清洗过滤敏感环境变量（API Key/密码）。</li> <li><b>凭据保护与白名单</b>：凭据隔离在 <code>.env.local</code>，动态派生 Host 白名单，剔除全局 <code>*</code>。</li> </ul> </td> <td width="50%" valign="top"> <h3>🩺 全套诊断探针与双重真实验收</h3> <ul> <li><b>OAuth 会话治理</b>：支持客户端列表、Token 定期清理、单客户端撤销及一键全局吊销。</li> <li><b>Web Doctor 矩阵</b>：<code>npm run doctor:web</code> 检查健康状态、401 拦截、工具清单及新鲜度。</li> <li><b>双重真实验收体系</b>：严格区分自动化探针数据与真实网页卡片渲染确认（<code>npm run accept:web:verify</code>），Fail-closed 脱敏记录退出状态。</li> </ul> </td> </tr> </table> --- ## 🏗️ 工作原理 ```text ┌─────────────────┐ HTTPS / OAuth ┌──────────────┐ loopback ┌────────────────────────┐ │ 网页版 ChatGPT │ ───────────────────────▶ │ 公网隧道 │ ────────────────────▶ │ DevSpace (127.0.0.1) │ └─────────────────┘ (ngrok / Pinggy) └──────────────┘ (Port: 7676) └───────────┬────────────┘ │ ┌──────────────────────────┴───────────────┐ ▼ ▼ ┌──────────────────────────┐ ┌──────────────────────────┐ │ 允许的本地目录 / Shell │ │ 选定的 AGENTS.md / Skills│ └──────────────────────────┘ └──────────────────────────┘ ``` - **隔离监听**：DevSpace 仅监听本机回环地址 `127.0.0.1:7676`，并通过 OAuth（Owner 密码）进行严格的授权审批。 - **反向代理**：隧道工具将公网 HTTPS 流量代理至本地 7676 端口。 - **端点规则**：MCP 客户端连接 URL 为 `https://<隧道域名>/mcp`，OAuth `issuer` 来自 `publicBaseUrl`（即纯域名根，**不带 `/mcp`**）。 - **零全局污染**： - **Windows 启动器**：仅更新项目目录下的 `.mcp.json`，不篡改本机全局 Codex 配置。 - **Linux 刷新脚本**：默认不修改 `~/.codex/config.toml`，仅在显式追加 `--sync-codex` 时作为遗留兼容同步。 --- ## 🌐 免费 ngrok 配置指南（手把手白嫖） 推荐使用免费的 **ngrok** 提供稳定的公网隧道支持（完全免费）： 1. **注册账号**：访问 [ngrok 官网 (ngrok.com)](https://ngrok.com/) 免费注册一个账号。 2. **获取 Authtoken**： - 登录后进入 [ngrok Dashboard -> Your Authtoken](https://dashboard.ngrok.com/get-started/your-authtoken)。 - 复制生成的这串 Token。 3. **（强烈推荐）领取 1 个免费静态域名**： - 在左侧菜单点击 **Cloud Edge** -> **Domains**。 - 点击 **Claim a domain**，免费领取一个专属静态域名（如 `your-name.ngrok-free.app`）。 - *好处：固定域名后，每次重启服务都不需要在 ChatGPT 网页端重新更新 URL！* 4. **填入项目配置**： - 在项目根目录复制一份配置文件： ```powershell Copy-Item .env.example .env.local ``` - 编辑 `.env.local` 填入刚刚的信息： ```env NGROK_AUTHTOKEN=你的ngrok_authtoken NGROK_DOMAIN=your-name.ngrok-free.app # 如果没有申请固定域名则留空 ``` --- ## 🚀 Windows 快速开始（推荐） ### 1. 安装依赖并初始化 DevSpace > 要求环境：Node.js `>=22.19 <27` ```powershell # 1. 全局安装 DevSpace CLI 并安装项目依赖 npm install --global @waishnav/devspace npm ci # 2. 初始化 DevSpace 配置 devspace init ``` *`devspace init` 会引导输入允许访问的目录、端口（填 `7676`）和公网 base URL（可先填 `https://placeholder.invalid`，启动器会自动改写）。* ```text # 目录授权示例（按需开放）： D:/AI/project-one,D:/AI/project-two # 明确接受风险后，也可以全盘开放： C:/,D:/ ``` ### 2. 一键启动、查看状态与停止 ```powershell # 运行启动前预检 npm run preflight # 启动后台受管服务（通过 /healthz 门控后返回成功） ./start.bat # 查看运行状态与诊断 npm run status # 精准停止受管进程树 ./stop.bat ``` --- ## 🐧 Linux / WSL 快速开始 ### 1. 安装与初始化 ```bash git clone https://github.com/xiaoxiao341/Chat2Agent.git cd Chat2Agent chmod +x setup.sh refresh-devspace-mcp.sh # 国内网络建议追加 --mirror 加速 npm 安装 ./setup.sh --mirror ``` ### 2. 启动隧道与自动同步 ```bash # 方式 A：使用 Pinggy 隧道（默认无需配置任何账号） ./refresh-devspace-mcp.sh --tunnel-cmd "ssh -o StrictHostKeyChecking=no -o UserKnownHostsFile=/dev/null -p 443 -R0:localhost:7676 a.pinggy.io" # 方式 B：使用 ngrok ./refresh-devspace-mcp.sh --tunnel-cmd "ngrok http 7676" --url-regex 'https://[a-z0-9-]+\.ngrok-free\.app' # 方式 C：使用已有的公网隧道地址 ./refresh-devspace-mcp.sh --known-url "https://abc-123.ngrok-free.app/mcp" ``` --- ## 📱 客户端配置与授权 ### 网页版 ChatGPT 配置（支持免费账号） 1. 打开 ChatGPT 网页端，点击左下角头像进入 **Settings** → **Apps & Connectors** → **Advanced** → **Developer Mode**。 2. 点击 **Create connector**，填入您的公网 MCP 地址：`https://<您的隧道域名>/mcp`。 3. 按照页面弹出的 OAuth 窗口输入 DevSpace 的 **Owner 密码**（保存在 `~/.devspace/auth.json` 中）完成授权。 4. 开启新对话，点击工具栏中的连接器图标，即可让 ChatGPT 读取、编写、运行你的本地代码！ --- ## 🛠️ 诊断工具箱与命令行命令 本仓库内置了一套完善的诊断与运维命令： ```powershell # 🔍 综合诊断与能力探针 npm run probe # 完整 OAuth + tools/list 诊断 node mcp-probe.mjs --workspace D:/AI/x --json # 输出 Skills、Subagents 与指令清单 node mcp-probe.mjs --test-delete --test-dir D:/AI/tmp # 安全沙箱删除测试 npm run probe:accept # 隔离式编辑、测试、长进程与 diff 自动验收 npm run doctor:web # ChatGPT 网页 Connector 专用深度排错 # 📦 资源与 Hook 审计 npm run resources # 查看已发现/显式选择的 Codex Skills npm run hooks # 检查网页兼容 Hook（明确标注不支持 before_tool） # 🔐 OAuth 审计与令牌管控 npm run oauth:list # 列出所有已注册的客户端 node oauth-admin.mjs prune # 清理过期的访问令牌 node oauth-admin.mjs revoke-client <client-id> --yes # 撤销指定客户端 node oauth-admin.mjs revoke-all --yes # 全局吊销所有授权令牌 ``` --- ## 📂 项目结构与文件说明 ```text ├── 🪟 Windows 受管核心 │ ├── start.bat / stop.bat # Windows 快捷启停入口 │ ├── start-ngrok.mjs # ngrok 隧道守护与 DevSpace 进程生命周期管理 │ ├── stop-service.mjs # 基于 PID 树与进程签名的精准安全停止 │ └── service-status.mjs # 进程状态诊断与健康探测 ├── 🐧 Linux / WSL 工具 │ ├── setup.sh # 依赖安装与交互初始化 │ ├── refresh-devspace-mcp.sh # 隧道刷新与配置原子重载 │ └── linux-process-utils.sh # Linux /proc 标识安全验证与进程管理 ├── 🔍 诊断与验收体系 │ ├── web-doctor.mjs # 网页 Connector 诊断套件 │ ├── mcp-probe.mjs # MCP 协议与能力边界探针 │ ├── execution-evidence.mjs # 隐私最小化执行证据收录 │ └── web-acceptance.mjs # 真实 ChatGPT 网页交互验收工具 ├── 🔐 权限与资源配置 │ ├── oauth-admin.mjs / oauth-db.mjs # OAuth 数据库管理与 Token 撤销 │ ├── resource-admin.mjs # Codex Skills 与 AGENTS.md 资源镜像 │ └── hook-admin.mjs # after_tool / tool_failure Hook 适配器 └── 📄 模板与规范 ├── .env.example # 环境变量模板 ├── .mcp.json.example # MCP 客户端配置示例 ├── review.sh / templates/ # 静态审查脚手架与报告模板 └── docs/ # ADR 决策记录、路线图与验收报告 ``` --- ## 💡 踩坑记录（Troubleshooting） <details> <summary><b>1. Authorization server issuer mismatch</b></summary> <br> * **报错表现**：客户端提示 `expected .../ , received .../mcp`。 * **原因剖析**：`config.json` 的 `publicBaseUrl` 被填成了带 `/mcp` 的地址。DevSpace 用 `publicBaseUrl` 推导 OAuth issuer，再拼接 `/mcp` 作为 MCP 端点。 * **解决方案**：确保 `publicBaseUrl` 为纯域名根（无后缀），仅在客户端填写的连接 URL 中携带 `/mcp`。本项目脚本已做自动化修正。 </details> <details> <summary><b>2. devspace: command not found 或 Permission denied</b></summary> <br> * **报错表现**：非交互环境下找不到命令，或 npm 软链无执行权限。 * **解决方案**：本项目启动脚本会自动补全 PATH 环境变量，并内置 `chmod +x` 自愈逻辑。如需手动修复可执行： ```bash chmod +x $(readlink -f $(which devspace)) ``` </details> <details> <summary><b>3. 进程自杀（重启或清理时误杀当前脚本）</b></summary> <br> * **原因剖析**：传统的 `pkill -f` 模式会匹配到当前脚本自身的命令行参数导致误伤。 * **解决方案**：本项目改为记录 PID 并结合 Linux `/proc` 启动标识/Windows 进程归属链进行精准终止。 </details> <details> <summary><b>4. setsid: failed to execute eval</b></summary> <br> * **原因剖析**：`setsid` 无法直接调用 Shell 内建命令 `eval`。 * **解决方案**：统一封装为 `setsid bash -c "$CMD"` 调用。 </details> <details> <summary><b>5. 网页反复弹出「Waiting for a tool result.」卡片且页面卡顿</b></summary> <br> * **原因剖析**：上游 DevSpace 默认会在 `open_workspace` 等工具调用时挂载完整 MCP App，导致频繁创建 iframe；且原组件依赖从 ngrok 加载资源，会被免费隧道的安全拦截页阻断。 * **解决方案**：本项目在内存中对模块进行兼容性适配： 1. 仅对最终的 `show_changes` 挂载 UI 资源； 2. 使用完全自包含且版本化的内联 Diff 组件（`ui://devspace/diff-card-inline-v3.html`）； 3. 修改后请在 ChatGPT Connector 设置中点击 **Refresh** 并开启新对话测试。 </details> <details> <summary><b>6. 免费隧道断连或过期</b></summary> <br> * **说明**：如果不配置固定域名，免费隧道每次重启域名可能变更。建议在 ngrok Dashboard 免费领取 1 个静态域名，即可一劳永逸无需重复更新 ChatGPT 端点。 * **休眠恢复**：Windows 唤醒或网络恢复后，受管进程会监测公网健康并自动重建 ngrok 会话。透明恢复依赖 `NGROK_DOMAIN` 固定域名；随机域名变化后 ChatGPT 保存的连接器地址无法自动更新。 </details> --- ## 🛡️ 安全规范与免责声明 1. **凭据隔离**：严禁提交 `.env.local`、`~/.devspace/auth.json`、运行日志或真实 `.mcp.json` 到任何公共代码库。 2. **风险可控**：公网隧道具备可访问性，请仅在需要时开启；如怀疑凭据泄露，请立即运行 `node oauth-admin.mjs revoke-all --yes` 并轮换 Token。 3. **额度提示**：`You've hit your usage limit` 是 OpenAI / ChatGPT 侧的模型调用额度限制，与本地隧道及本项目无关。 4. 详尽的威胁模型与安全响应指引请参考 🔒 [SECURITY.md](SECURITY.md)。 --- ## 🤝 致谢与开源协议（Credits & License） 本项目是在 [Embracecactus/devspace-mcp-tunnel](https://github.com/Embracecactus/devspace-mcp-tunnel) 优秀创意的基础上继续重构与演进开发的。 - **原作者仓库**：[Embracecactus/devspace-mcp-tunnel](https://github.com/Embracecactus/devspace-mcp-tunnel) (感谢原作者奠定的 Linux 自动化脚本雏形与实践思路) - **底层底座支持**：[DevSpace (@waishnav/devspace)](https://github.com/Waishnav/devspace) - **开源协议**：本项目基于 **[MIT License](LICENSE)** 协议完全开源。根据 MIT 协议规范，项目完好保留了原作者的版权声明（Copyright (c) 2026 Embracecactus），您可以在合法合规的前提下自由学习、修改与二次分发。 --- <div align="center"> 如果这个项目对你有帮助，欢迎点个 ⭐️ <b>Star</b> 支持一下！ </div>