Chat2Agent
by xiaoxiao341
README.md
<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>
This server cannot be deployed
Maintenance
ActivityMaintained
ResponsivenessNo issues