ShellBridge

<p align="center"> <img src="./assets/readme/hero.svg" width="100%" alt="ShellBridge — 让 ChatGPT 看见你的 VPS 而无需提供 SSH。MCP 服务器提供给 ChatGPT 一个只读、掩码和编辑的 Ubuntu VPS 视图。"> </p> # ShellBridge 简体中文 | [English](README.en.md) [](https://github.com/fengyincheng/ShellBridge/actions/workflows/ci.yml) [](LICENSE) [](#supported-platform) ## 无需提供 SSH，让 ChatGPT 看见你的 VPS **告别“复制此命令到你的 VPS 并发送输出”。** ShellBridge 通过 MCP 将普通的 ChatGPT 对话连接到你的 Linux VPS。它为 ChatGPT 提供足够的当前、可控和可审计的信息来调查你的服务器，解释正在发生的事情，并编写基于实际系统的计划。 向 ChatGPT 提问： - “什么占用了所有的磁盘空间？” - “为什么这个项目测试失败？” - “这个 Git 仓库发生了什么变化？” - “检查此配置是否完整而不泄露其秘密。” - “审查当前实现并为 Codex 编写详细计划。” - “检查 Codex 完成后结果并告诉我是否可以提交。” 常规诊断在只读、网络隔离的沙箱中运行。敏感路径会自动隐藏。持久功能范围狭窄，默认禁用，由服务器所有者单独控制。 > **公共预览版 · v0.3.0** > > Ubuntu 24.04 · Linux x86_64 · Node.js 22+ --- ## 为什么使用 ShellBridge？ ### 1. 给 ChatGPT 足够的信息来编写真正有用的计划 ChatGPT 特别适用于对话、综合、解释和长篇写作。它可以将复杂的技術情况转化为架构审查、故障排除指南、迁移计划、实施简介或另一个开发人员的精确交接。 但是好的计划需要好的上下文。 如果没有访问 VPS，ChatGPT 只知道你记住的片段。重要的文件、仓库状态、测试结果、日志和配置详细信息很容易被遗忘。 ShellBridge 让 ChatGPT 直接检查相关证据。当信息完整时，生成的计划可以是针对你真实系统的具体计划，而不是通用检查清单。 然后你可以审查计划并将其交给 Codex、ChatGPT Work、另一个代码代理或人类开发人员。 ### 2. 停止成为人类复制粘贴桥 如果没有 ShellBridge，技术对话通常会变成： <p align="center"> <img src="./assets/readme/manual-relay.svg" width="100%" alt="没有 ShellBridge：ChatGPT 给你一个命令，你复制到 SSH，你复制输出回来，ChatGPT 请求另一个命令 — 重复。"> </p> 这很慢而且容易出错。输出被截断，命令在错误目录下运行，上下文在消息之间丢失，用户成为两个窗口之间手动传输层。 ShellBridge 消除了这种重复中继。ChatGPT 可以执行只读检查，检查结果，跟进另一个诊断，并在一次对话中完成调查。 你保持控制而不必在手动移动文本。 ### 3. 使用聊天进行理解 — 为执行保存 Codex 和 Work ShellBridge **不** 尝试替换 Codex。 将 ChatGPT Chat 与 ShellBridge 结合使用： - 检查 VPS 的真实状态； - 交互式讨论问题； - 组合文件、日志、测试和仓库状态； - 用通俗语言解释不熟悉的系统； - 比较可能的方法； - 编写详细实施计划； - 准备精确的交接说明； - 审查已完成的工作。 然后在任务真正需要持续执行、广泛文件编辑或自主实施时，使用 Codex 或 ChatGPT Work。 OpenAI 当前的文档将 Codex 和 ChatGPT Work 放在同一个代理使用池中，而 ChatGPT 仍然是单独的对话体验。ShellBridge 让您使用普通聊天进行调查、解释和长期规划，同时为执行繁重的任务保留共享 Codex/Work 津贴。用法策略可能会发生变化，因此请查看 [ChatGPT Work 和 Codex](https://help.openai.com/en/articles/20001275-chatgpt-work-and-codex) 和 [当前 Codex 用法文档](https://help.openai.com/en/articles/11369540) 以获取您的计划。 <p align="center"> <img src="./assets/readme/plan-execute-review.svg" width="100%" alt="ChatGPT Chat 与 ShellBridge 检查、理解、讨论并编写计划；Codex 或 ChatGPT Work 执行实施；ChatGPT Chat 与 ShellBridge 检查和审查结果。"> </p> --- ## ShellBridge 会将 ChatGPT 变成另一个 Codex 吗？ **否 — 那不是目标。** Codex 是一个执行重点的代码代理。它旨在进入工作区、编辑文件、运行命令和完成实施任务。 ShellBridge 为 ChatGPT 提供不同的功能：足够安全、当前和结构化的信息，以便了解您的 VPS 上发生了什么。 ChatGPT 仍然是一个对话模型。ShellBridge 不授予它不受限制的工作区控制，不将其变成自主代码代理，也不提供通用的远程 shell。 相反，ShellBridge 将推理和规划层连接到现实： ```text ShellBridge 提供可见性，而不是不受限制的权限。 ChatGPT 调查和计划。 Codex 或 Work 执行。 您保持控制。 ``` --- ## 为什么不直接暴露 SSH？ 普通的 SSH 会话为其调用者提供广泛的交互权限。大多数诊断问题不需要那么多权限。 ShellBridge 公开的是狭窄的 MCP 工具： <p align="center"> <img src="./assets/readme/security-boundary.svg" width="100%" alt="ChatGPT 通过 HTTPS 和 OAuth 连接到 ShellBridge — 只读诊断沙箱，带有敏感路径掩码、输出编辑、时间和资源限制，以及可选的狭窄作用域写入工具 — 在您的 VPS 前面。"> </p> ChatGPT 可以有效地调查而无需获得不受限制的 SSH 访问权限。 该服务仍然是安全敏感的基础设施：一个 root 管理的进程构建这些边界并控制哪些主机路径可见。请在部署前阅读[威胁模型](docs/threat-model.md)。 --- ## ChatGPT 可以做什么？ ### 了解您的 VPS ChatGPT 可以在您选择的目录的只读视图中使用完整的 Bash 语法。 典型任务包括： - 检查文件和目录结构； - 检查磁盘使用情况和文件大小； - 搜索源代码和日志； - 读取项目元数据； - 比较配置状态； - 运行诊断管道； - 在一个批次中执行多个相关检查。 通用诊断 shell 不能持久更改主机。 ### 安全检查配置 您可以注册特定的 JSON 或环境文件，并显式允许检查选定的字段。 凭证值永远不会直接返回。敏感字段减少为以下状态： ```text 缺失 为空 设置 / 已编辑 ``` 这允许 ChatGPT 回答以下问题： > “此应用程序是否配置了所需的凭证？” 而无需公开凭证本身。 ### 运行现有项目任务 ChatGPT 可以在项目的可写副本中运行现有的包脚本或项目脚本。 示例包括： ```text npm test npm run check python scripts/validate.py ``` 临时副本是可写的，以便构建和测试缓存可以工作，但所有更改都会在任务结束时被丢弃。原始项目不会被修改，并且任务无网络访问。 ### 审查本地 Git 仓库 ShellBridge 支持狭义的本地 Git 操作： - 检查仓库状态； - 暂存显式路径； - 取消暂存显式路径； - 准备精确的本地提交； - 执行仅限之前准备的提交。 它不支持远程 Git 操作，如推送、拉取或获取。 ### 执行可选的受控更改 当服务器所有者明确启用时，ShellBridge 可以： - 创建、替换、修补和移动 Markdown 或文本文档； - 暂存和取消暂存本地 Git 路径； - 准备和执行不可变的本地提交提议； - 准备预先存在的维护或部署脚本以执行。 这些功能默认禁用。ShellBridge 不提供任意主机写入 shell。 --- ## ShellBridge 如何保持安全？ ShellBridge 将模型生成的命令、参数、仓库内容和命令输出视为不受信任的输入。 ### 默认只读 一般诊断在只读 Bubblewrap 文件系统视图中作为非特权身份运行。 ### 无网络访问 诊断沙箱接收隔离的网络命名空间。网络和 Unix 套接字创建额外受到 seccomp 限制。 ### 隐藏敏感路径 已知凭证、会话、私钥、数据库、shell 历史记录、浏览器配置文件、云客户端和控制套接字路径被沙箱屏蔽。管理员可以阻止其他路径。 ### 输出被编辑 ShellBridge 在将命令输出返回给 ChatGPT 之前，会扫描输出中的凭证样内容。注册的配置读取器应用更严格的字段级公开规则。 ### 命令有界限 诊断和项目任务受到超时、输出限制、进程限制、文件大小限制、内存限制、rlimit 和 cgroup 控制的约束。 ### 写入工具是独立的 持久功能不继承只读 shell 访问权限。它们需要同时启用全局写入开关和正在使用的确切功能开关。 ### 结果动作被冻结 本地 Git 提交和预先存在的脚本执行使用不可变的准备/执行流程。 准备记录了确切的仓库或脚本标识、内容状态、参数、工作目录、资源限制和相关的 Git 状态。执行仅接受生成的提议 ID，重新验证冻结状态并防止重放。 --- ## 快速开始 ### 要求 ShellBridge 公共预览版当前需要： - Ubuntu 24.04； - Linux x86_64； - Node.js 22 或更新版本； - Bubblewrap； - cgroup v2； - C17 编译器； - 支持的部署模型的 root 访问权限。 安装 Ubuntu 先决条件： ```bash sudo apt-get update sudo apt-get install --yes build-essential bubblewrap ``` ### 构建 ShellBridge ```bash git clone https://github.com/fengyincheng/ShellBridge.git cd ShellBridge npm ci npm run build cp .env.example .env ``` 打开 `.env` 并按照注释填写所需的凭证、数据库路径、公共 URL 和可读根目录。 使用以下命令生成所需的 32 字节数据密钥： ```bash openssl rand -base64 32 ``` 加载环境并运行只读预检查： ```bash set -a . ./.env set +a npm run doctor ``` 然后启动 ShellBridge： ```bash npm start ``` ShellBridge 仅监听回环。默认地址是： ```text 127.0.0.1:8765 ``` 监听主机不能更改为 `0.0.0.0`。 --- ## 连接 ChatGPT 对于远程访问，在 ShellBridge 前面放置 HTTPS 反向代理或身份验证隧道： ```text ChatGPT │ │ HTTPS ▼ 反向代理或身份验证隧道 │ │ 回环 ▼ 127.0.0.1:8765 ``` 将 `SHELLBRIDGE_PUBLIC_BASE_URL` 设置为部署的精确公共 HTTPS 源。 MCP 端点将是： ```text https://shellbridge.example.com/mcp ``` ShellBridge 发布 OAuth 授权服务器和受保护资源元数据，ChatGPT 需要从同一个公共 URL 中获取。 参见 [ChatGPT 连接指南](docs/chatgpt-guidance.md)，了解连接合约和预期客户端行为。 永远不要将 `8765` 端口直接暴露给公共互联网。 --- ## systemd 部署 一个示例 root 管理单元包含在以下路径中： ```text deploy/systemd/ ``` 该单元假定 ShellBridge 安装在 `/opt/shellbridge`。 安装模板： ```bash sudo install -d -o root -g root -m 0700 \ /etc/shellbridge \ /var/lib/shellbridge sudo install -o root -g root -m 0600 \ deploy/systemd/shellbridge.env.example \ /etc/shellbridge/shellbridge.env sudo install -o root -g root -m 0644 \ deploy/systemd/shellbridge.service \ /etc/systemd/system/shellbridge.service ``` 填充 `/etc/shellbridge/shellbridge.env` 中的所有必需值，然后： ```bash sudo systemctl daemon-reload sudo systemctl enable --now shellbridge ``` 在启动服务之前查看所有路径和设置。包含的单元是 Ubuntu 24.04 示例，不是通用分发包。 --- ## 功能开关 所有持久功能默认禁用： ```text SHELLBRIDGE_WRITE_ACTIONS_ENABLED=false SHELLBRIDGE_DOCUMENT_WRITES_ENABLED=false SHELLBRIDGE_LOCAL_GIT_WRITES_ENABLED=false SHELLBRIDGE_EXISTING_SCRIPT_RUNS_ENABLED=false ``` 全局开关和相关功能开关都必须启用。启用一个功能不会解锁无关的写入操作。 --- ## ShellBridge 不具备的功能 ShellBridge 故意不提供： - 无限制的 SSH 访问； - 任意主机写入 shell 命令； - 从诊断命令进行一般的互联网访问； - 远程 Git 推送、拉取或获取； - 包安装或系统升级； - 自动部署或服务管理； - 自动 DNS、TLS、隧道或防火墙配置； - 多租户授权； - ARM64、Docker 或 Kubernetes 支持在此预览版中。 这些是产品边界，而不是需要绕过的缺失快捷方式。 --- ## 支持的平台 当前支持矩阵故意狭窄： | 组件 | 支持 | |---|---| | 操作系统 | Ubuntu 24.04 | | 架构 | Linux x86_64 | | Node.js | 22 或更新版本 | | 沙箱 | Bubblewrap | | 资源控制 | cgroup v2 | | 服务模型 | 根管理 | | ARM64 | 不支持 | | Docker / Kubernetes | 不支持 | 原生构建在不受支持的操作系统和 CPU 架构上会明确失败。 --- ## 文档 - [ChatGPT 连接指南](docs/chatgpt-guidance.md) - [MCP 接口](docs/mcp.md) - [已实现功能](docs/implementation-status.md) - [后果工具合约](docs/consequential-tools.md) - [安全威胁模型](docs/threat-model.md) - [实现默认值](docs/implementation-defaults.md) - [安全策略](SECURITY.md) - [贡献指南](CONTRIBUTING.md) - [更新日志](CHANGELOG.md) --- ## 开发 运行普通的测试并构建： ```bash npm run check ``` 普通套件使用受控的测试替身进行通用 shell 执行。 特权原生验收测试需要一个具有 root 访问权限、Bubblewrap 和可写 cgroup v2 的受支持、可丢弃的 Ubuntu 24.04 x86_64 主机： ```bash sudo --preserve-env=PATH npm run test:privileged ``` 不要在您未为其准备挂载和 cgroup 夹具的主机上运行特权验收测试。 --- ## 安全 ShellBridge 是安全敏感的基础设施。 在部署它之前： - 阅读[威胁模型](docs/threat-model.md)； - 查看配置的可读路径和阻止的路径； - 将服务绑定到回环； - 在其前面添加经过身份验证的 HTTPS； - 保持持久功能禁用，除非需要； - 在可能的情况下，将其部署在专用或明确隔离的 VPS 上。 ShellBridge 不会取代操作系统的强化、账户隔离、备份或仔细管理。 如果要报告漏洞，请遵循 [SECURITY.md](SECURITY.md) 而不是打开公共问题。 --- ## 公共预览版 ShellBridge v0.3.0 是一个早期的公共版本。安全模型、支持的平台、配置格式和 MCP 工具可能会随着项目接收现实世界的审查而发生变化。 欢迎提供反馈、测试、文档改进和仔细范围内的贡献。 --- ## 许可证 ShellBridge 遵循 [Apache License 2.0](LICENSE) 许可。