# SketchUp Codex Bridge

通过 Codex 的自然语言指令，读取和修改本机当前打开的 SketchUp 模型。

这是面向 **Windows + SketchUp 2023 + Codex** 的可复用部署包，基于 [2ez4gcx/sketchup-mcp](https://github.com/2ez4gcx/sketchup-mcp) 的 **v1.2.0**。上游 MCP 服务、Ruby 桥接及许可证保留原样；本仓库提供中文部署、保护原配置的注册脚本、只读诊断、测试示例和自动检查。

不包含任何住宅施工图、客户模型、现场照片、效果图、账号配置或密钥。它是本地桌面控制工具，**不是部署在 GitHub Pages 上的远程建模服务**。

```mermaid
flowchart LR
  A[Codex] -->|本地 stdio / MCP| B[Node.js MCP 服务]
  B -->|127.0.0.1:9876| C[SketchUp SU MCP Bridge]
  C --> D[Ruby API / 当前模型]
```

## 能做什么

- 读取模型、单位、组件、材质、标签、选中内容及工程量。
- 创建几何、复制移动旋转缩放、贴材质、分阶段建模和撤销。
- 设置视角、截图、导出及运行 Ruby API 代码。
- 配合客户端的生图工具生成效果图；**桥接本身不提供GPT生图或照片级渲染**。

## 环境

- Windows、可正常运行并加载扩展的 SketchUp 2023。
- Node.js 18 或以上；Codex 桌面端或 CLI。
- SketchUp 与 Codex 必须运行在同一台电脑。GitHub Actions 仅测试部署包，不运行 SketchUp。
- 上游声明测试过 Windows SketchUp 2021/2023；本部署方案在2026-10-20的本机 SketchUp 2023 环境完成过建模操作验证。其他版本不据此宣称已验证。

仓库已包含固定版本的官方程序文件，无需 `npm install`，不执行下载后直接运行的远程安装脚本。

## 快速开始

### 1. 下载并检查

```powershell
git clone https://github.com/wc970321-collab/sketchup-codex-bridge.git
cd sketchup-codex-bridge
node --version
node scripts/verify-vendor.mjs
npm test
```

从 GitHub 下载 ZIP 也可以，先解压到长期保留的目录。路径可以包含中文和空格；注册后不要移动目录，否则需手动更新 Codex 中的路径。

### 2. 安装 SketchUp 桥接

在 SketchUp 2023 的「扩展程序 → 扩展程序管理器 → 安装扩展」选择：

```text
vendor/sketchup-mcp-1.2.0/bridge/su_mcp.rbz
```

完全退出并重新打开 SketchUp，查看「扩展程序 → SU MCP Bridge → Status」，应显示 `RUNNING on 127.0.0.1:9876`。

不覆盖 SketchUp 安装目录，不要求在 Program Files 中写入。若未签名插件受到组织策略限制，请通过正常扩展管理流程处理，不绕过策略。

### 3. 注册 Codex

建议先注册只读工具，验证目标模型：

```powershell
node scripts/configure-codex.mjs
```

需要直接建模时，在**尚未注册本服务的新环境**可改用：

```powershell
node scripts/configure-codex.mjs --enable-write
```

注册脚本使用当前 Node 与仓库的绝对路径，目标为 `CODEX_HOME/config.toml`，未设置时为用户目录下 `.codex/config.toml`。有原配置会先备份并保留原字节；**检测到已有 sketchup 项就停止，不替换、不自动迁移当前环境**。

已经注册只读、现在需要写操作：手动删除 `[mcp_servers.sketchup]` 下的 `enabled_tools` 白名单这一行，保留 `default_tools_approval_mode = "prompt"`，重载 Codex。可用下列命令预览完整配置，不修改文件：

```powershell
node scripts/configure-codex.mjs --enable-write --print
```

全量写工具包括 `run_ruby`；只对信任的请求开放。提示行为还受客户端版本和管理策略影响，并非操作系统沙箱。配置字段依据 [OpenAI 官方 MCP 文档](https://learn.chatgpt.com/docs/extend/mcp?surface=cli)。

### 4. 重载并验证

重启或重新加载 Codex 后，先测试：

```powershell
npm run tools
npm run health
node scripts/mcp-client.mjs model_info
```

`tools` 列出26项上游工具，不需要 SketchUp；`health` 与 `model_info` 需要桥接已启动。模型信息可能包含私人文件名，不要直接公开终端输出。

在 Codex 中说：

> 使用 SketchUp MCP，读取当前模型路径、单位和组件信息，暂不修改。

确认是目标工作副本后，再请求逐阶段建模。更多用法见 [自然语言示例](examples/prompts.zh-CN.md)。

## 验证与文件保护

`examples/test-box.rb` 只允许在未保存、实体为空、未进入组件编辑的测试模型执行，创建并核验1200×600×900mm盒体组件，不保存或关闭模型。它是连接/尺寸示例，不是施工柜体设计。

每次新会话先读 `model_info`，重新获取实体ID；先另存副本再修改。一次处理一个小阶段：建实体 → 刷新视图 → 核验尺寸 → 保存到新路径。Undo只针对模型事务，不能撤销外部文件、联网或进程行为。

## 文件结构

| 文件 | 用途 |
|---|---|
| `vendor/sketchup-mcp-1.2.0/` | 官方固定版本服务与RBZ，原样保留 |
| `upstream.lock.json` | 官方下载地址、包哈希与逐文件哈希 |
| `scripts/configure-codex.mjs` | 备份并追加Codex配置，已有服务时拒绝覆盖 |
| `scripts/mcp-client.mjs` | 本地诊断客户端，命令行写操作需显式 `--allow-write` |
| `scripts/verify-vendor.mjs` | 校验上游文件未被修改 |
| `examples/` | Ruby测试示例与中文提示词 |
| `test/`、`.github/workflows/ci.yml` | 配置保护、MCP握手及上游完整性测试 |

## 排障

| 现象 | 处理 |
|---|---|
| 工具列表成功，ping失败 | 打开目标SketchUp，检查桥接Status或Start server |
| 控制了另一个窗口 | 多个窗口争用同一端口；停止非目标窗口桥接，再启动目标窗口，勿丢弃未保存工作 |
| Codex没有新工具 | 核对绝对路径，完全退出并重启Codex；插件内注册与手动配置不要重复启用 |
| 只读模式不能建模 | 按第3步手动启用写工具；不要重跑脚本覆盖既有配置 |
| 端口改过 | 同步修改SketchUp桥接与Codex环境变量；诊断CLI用 `SKETCHUP_MCP_PORT` |
| 写操作超时 | 等待SketchUp空闲后先检查状态，勿立即重复执行，否则可能生成重复几何 |
| Codex自身执行宿主缺失 | 与MCP桥接分开排查；不要把不同版本EXE混拷到缓存目录，不设置固定哈希目录的 `CODEX_CLI_PATH` |

## 安全与开源来源

先阅读 [SECURITY.md](SECURITY.md)。桥接只绑定本机回环地址，但无身份认证；任意 Ruby 以当前用户权限执行，**不在文件系统沙箱中**。使用后可从SketchUp菜单停止桥接；重开SketchUp可能自动启动。

上游 [v1.2.0 Release](https://github.com/2ez4gcx/sketchup-mcp/releases/tag/v1.2.0) 的 MCPB SHA-256：

```text
be6864a1f18bea06655be40e8a259f24a2457ba6c1300c13ed287dd11f6df234
```

2026-10-21发布整理时，已从官方地址重新下载校验，并将本仓库8个上游文件与包内逐字节比对。升级时服务和RBZ需成套更新，重做哈希校验与兼容验证，不自动追踪最新版。

本仓库的部署胶水和文档采用MIT。原作者 Khuong Doan 的版权与MIT许可证保留在vendor目录；内嵌依赖许可证见 `server/THIRD_PARTY_NOTICES.txt`。本仓库不是OpenAI或SketchUp官方产品，也未声称重写了上游桥接。