内容
<div align="center">
# SAIE
**草图自动化与智能引擎**
*AI 代理与草图 2025 之间的模型-上下文-协议桥梁。*
[](https://pypi.org/project/saie/)
[](https://www.python.org/downloads/)
[](https://www.sketchup.com/)
[](LICENSE)
[](https://modelcontextprotocol.io/)
[](https://github.com/iamahsanmehmood/saie/actions)
</div>
---
SAIE 允许 **Claude, Cursor, Antigravity, Ollama 及任何 MCP 客户端** 原生驱动 SketchUp 2025。AI 代理可以构建墙壁，切割开口，放置组件，运行冲突检测，生成漫游动画，并检查模型中的任何实体 - 通过严格的声明式 JSON-RPC 合同，而不是原始的 Ruby 评估。
它包含：
- 一个 **Python MCP 服务器** (`saie-mcp`) - 向任何 MCP 兼容的主机公开 **67+ 工具**。
- 一个 **Ruby SketchUp 插件** - 在 SketchUp 2025 中运行，监听 WebSocket，执行工具调用。
- 一个 **CLI** (`saie`) - 20+ 个终端控制命令，无需 AI 参与。
- 一个 **实时 MJPEG 流** - 在任何浏览器中查看 SketchUp 视口，AI 工作时。
- 一个 **中心配置** - 一个 `saie.toml` 控制双方的所有端口，路径和功能标志。
---
## ✨ 亮点
| 能力 | 你可以做的事情 |
|---|---|
| **墙壁 + 开口** | 构建墙壁，自动解决对接/T/十字接头，切割门/窗户，自动生成框架。 |
| **板材 + 屋顶** | 基于多边形的板材，任意 Z；有檐口的倾斜/山墙/棚顶/臀顶屋顶。 |
| **组件** | 放置库组件，设置材质/图层，批量修改属性。 |
| **实时视图流** | `http://localhost:9877` 的 HTTP MJPEG - 捕获真实的帧缓冲区，包括轴，选择，操纵器。 |
| **AI 快照** | `view_snapshot` 返回内联 base64 JPEG；AI 每次调用都获得新鲜图像。 |
| **视图控制** | 通过 MCP 轨道，缩放，平移，设置/获取相机，选择/取消选择，隔离/取消隔离。 |
| **报告** | Markdown / CSV / JSON 模型报告；通过持久属性字典进行 BIM 元数据。 |
| **冲突检测** | AABB 重叠分析，严重程度分级。 |
| **漫游动画** | 轨道 / 飞越 / 电影动画渲染到磁盘。 |
| **高品质渲染** |高达 3840×2880 等距或任意预设。 |
| **DXF 导入** | 解析 2D CAD 平面图并构建它们。 |
| **项目系统** | 按项目文件夹，自动路由捕获，报告，资产。 |
| **BIM 数据库** | 读取/写入任意实体的属性字典 - 查询，列出，找到，批量设置。 |
---
## 🏗️ 架构
```
┌────────────────────┐ MCP stdio ┌─────────────────┐
│ Claude Desktop │ ────────────────────▶│ │
│ Cursor / Cline │ │ saie-mcp │
│ Antigravity │ │ (Python MCP │
└────────────────────┘ │ server) │
│ │
┌────────────────────┐ direct WS │ │
│ saie CLI │ ────────────────────▶│ │
└────────────────────┘ │ │
│ │
┌────────────────────┐ tool use │ │
│ Anthropic agent │ ────────────────────▶│ │
│ Ollama agent │ └────────┬────────┘
└────────────────────┘ │
│ JSON-RPC 2.0
│ over WebSocket
▼
┌─────────────────┐
│ SketchUp 2025 │
│ + Ruby plugin │
│ + MJPEG :9877 │
└─────────────────┘
```
Python 端和 Ruby 端都读取 **`saie.toml`** - 一个配置，两个部分保持同步。
---
## 🚀 快速开始
### 先决条件
- **SketchUp 2025** 已安装（Windows 或 macOS）
- **Python 3.10+**
- *可选：*Anthropic API 密钥或 Ollama（用于 AI 代理命令）
### 1. 安装
```bash
pip install saie
```
对于开发安装：
```bash
git clone https://github.com/iamahsanmehmood/saie.git
cd saie
pip install -e ".[dev,all]"
```
### 2. 安装 SketchUp 插件
**Windows (PowerShell):**
```powershell
.\scripts\install_plugin.ps1
```
**macOS:**
```bash
./scripts/install_plugin.sh
```
安装程序复制（或在开发模式下符号链接）`ruby_plugin/` 内容到您的 SketchUp 插件目录，并复制 `saie.toml` 到 `~/.saie/saie.toml`。
有关手动安装说明，请参阅 [docs/INSTALL.md](docs/INSTALL.md)。
### 3. 启动 SketchUp 2025
插件自动启动。您将在 `Extensions → SAIE` 下看到一个 **SAIE** 条目。默认情况下，桥梁监听 `ws://localhost:9876`。
### 4. 验证
```bash
saie ping
# → {"pong": true, "plugin_version": "1.0.0", ...}
```
### 5. 构建某些事物
```bash
# 使用 Claude
export ANTHROPIC_API_KEY="sk-ant-..."
saie agent "Build a 6x6m room with a door on the south wall"
# 使用本地 Ollama
saie agent --provider ollama --model gemma3:4b "Draw a table with 4 legs"
```
### 6. 观看实时直播
在任何浏览器中打开 `http://localhost:9877/`，实时查看 SketchUp 视口 - 轴，选择高亮等。
---
## 🔌 MCP 客户端设置
### Claude Desktop
添加到 `claude_desktop_config.json`：
```json
{
"mcpServers": {
"saie": {
"command": "saie-mcp"
}
}
}
```
### Cursor / Cline / Continue.dev
相同的模式 - 将它们指向 `saie-mcp` 控制台脚本。
### Antigravity
SAIE 捆绑为一流集成。有关供应商特定说明，请参阅 [docs/MCP_CLIENTS.md](docs/MCP_CLIENTS.md)。
### Anthropic Agent SDK（编程）
```python
import asyncio
from anthropic import Anthropic
from anthropic.types.beta import BetaMessageParam
# Spawn saie-mcp as a subprocess and connect via stdio.
# Full example: examples/agent_sdk_demo.py
```
---
## 🛠 CLI 参考
| 命令 | 目的 |
|---|---|
| `saie ping` | 测试桥梁连接性 |
| `saie status` | 桥梁状态 + 场景摘要 |
| `saie summary` | 令牌高效模型摘要 |
| `saie scan` | 深度递归扫描 |
| `saie report --format md\|csv\|json` | 生成模型报告 |
| `saie clash` | 运行冲突检测 |
| `saie verify W1 DOOR_1` | 确认实体 ID 存在 |
| `saie capture [preset]` | 捕获视图（计划/等距/高程_*） |
| `saie capture-all` | 捕获所有 6 个规范视图 |
| `saie render [preset]` | 超高品质渲染（高达 3840×2880） |
| `saie walkthrough [preset]` | 轨道 / 飞越 / 电影动画 |
| `saie save [path]` | 保存模型 |
| `saie open <path>` | 打开 `.skp` 文件 |
| `saie project create\|list\|open\|info` | 项目生命周期 |
| `saie agent "<prompt>"` | Anthropic 代理 |
| `saie agent --provider ollama "<prompt>"` | 本地 Ollama 代理 |
| `saie mcp` | 在 stdio 上运行 MCP 服务器（与 `saie-mcp` 相同） |
完整参考：[docs/CLI_REFERENCE.md](docs/CLI_REFERENCE.md)
`sb` 和 `sketchup-mcp` 被保留为旧别名，以便现有自动化不会中断。
---
## 📦 MCP 工具（67+）
工具在 `mcp__saie__*` 命名空间下公开。亮点：
**场景查询**
`ping` `hello` `scene_summary` `deep_scan` `model_info` `get_selection` `inspect_entity` `export_model_json` `verify_model`
**几何形状**
`create_wall` `modify_wall` `delete_wall` `cut_opening` `modify_opening` `delete_opening` `create_slab` `create_roof` `create_primitive` `place_component` `delete_entity`
**材质和图层**
`upsert_material` `assign_material` `upsert_layer` `assign_layer`
**BIM 元数据**
`get_entity_attribute` `list_entity_dictionaries` `find_entities_by_attribute` `set_entity_attribute` `set_entity_attributes_bulk`
**视图控制**
`orbit_view` `zoom_view` `zoom_extents` `zoom_selection` `pan_view` `set_camera` `get_camera` `select_entity` `deselect_entity` `clear_selection` `isolate_entity` `show_all`
**捕获和实时视图**
`view_snapshot` `capture_view` `capture_canonical` `capture_hq_render` `start_live_view` `stop_live_view` `live_view_status` `configure_live_view`
**报告和分析**
`generate_report` `detect_clashes` `parse_dxf_plan`
**生命周期**
`new_file` `open_file` `save_file` `save_as` `clear_model` `create_project` `set_active_project` `list_all_projects`
**动画**
`generate_walkthrough`
**批量/高级**
`batch_operations` `execute_ruby` *（禁用生产环境中的 `[experimental].enable_raw_ruby_exec = false`）*
完整工具参考，含参数和返回类型：[docs/MCP_TOOLS.md](docs/MCP_TOOLS.md)
---
## ⚙️ 配置
所有内容均由 **`saie.toml`** 控制。文件按以下顺序搜索：
1. `$SAIE_CONFIG` 环境变量
2. `./saie.toml` 在 CWD
3. `~/.saie/saie.toml`
4. 仓库捆绑的默认值
使用 `SAIE_<SECTION>_<KEY>` 环境变量覆盖任何值（例如 `SAIE_BRIDGE_PORT=9999`）。
| 部分 | 控制 |
|---|---|
| `[bridge]` | WebSocket 主机/端口，超时，端口文件路径 |
| `[stream]` | MJPEG 端口，FPS，JPEG 质量，捕获源 |
| `[sketchup]` | SketchUp 版本，安装路径，插件自动启动 |
| `[projects]` | 项目根目录和子文件夹布局 |
| `[capture]` | 捕获的默认预设/分辨率/样式 |
| `[agents]` | 默认 AI 提供商，模型名称，Ollama 端点 |
| `[logging]` | 日志级别，环形缓冲区大小，可选日志文件 |
| `[security]` | 仅限 localhost 标志，可选身份验证令牌 |
| `[experimental]` | `execute_ruby`，DXF 导入，漫游动画的功能标志 |
完整参考：[docs/CONFIGURATION.md](docs/CONFIGURATION.md) · 端口表：[docs/PORTS.md](docs/PORTS.md)
---
## 📚 文档
| 文档 | 它涵盖的内容 |
|---|---|
| [INSTALL.md](docs/INSTALL.md) | 每个平台的安装 + 卸载 |
| [CONFIGURATION.md](docs/CONFIGURATION.md) | 每个 `saie.toml` 字段 |
| [PORTS.md](docs/PORTS.md) | SAIE 使用的所有网络端口 |
| [MCP_TOOLS.md](docs/MCP_TOOLS.md) | 每个 MCP 工具及其参数 |
| [MCP_CLIENTS.md](docs/MCP_CLIENTS.md) | Claude Desktop，Cursor，Cline，Antigravity 接线 |
| [CLI_REFERENCE.md](docs/CLI_REFERENCE.md) | 所有 `saie` 子命令 |
| [ARCHITECTURE.md](docs/ARCHITECTURE.md) | 桥梁的工作原理 |
| [API_REFERENCE.md](docs/API_REFERENCE.md) | 嵌入式 Python API |
| [action_schema.md](docs/action_schema.md) | 声明性操作合约 |
| [bim_metadata_schema.md](docs/bim_metadata_schema.md) | BIM 属性约定 |
| [PUBLISHING.md](docs/PUBLISHING.md) | 发布到 PyPI / MCP 注册表 |
| [CONTRIBUTING.md](CONTRIBUTING.md) | 开发设置 |
| [CHANGELOG.md](CHANGELOG.md) | 版本历史 |
---
## 🌐 实时视图
启动流媒体并在任何浏览器中观看 SketchUp：
```bash
saie stream start --fps 8 # 或通过 MCP：start_live_view
# → http://localhost:9877/
```
流媒体从 SketchUp 的自身窗口缓冲区读取 Win32 GDI，因此它包含您在屏幕上看到的所有内容 - 坐标轴，选择轮廓，旋转操纵器，推理工具提示 - 即使 SketchUp 窗口在浏览器后面。
---
## 🔒 安全模型
- **默认仅限 localhost**。WebSocket 仅监听 `127.0.0.1`。不要在不受信任的网络上将 `[bridge].host` 更改为 `0.0.0.0` - 任何可以访问该端口的人都可以修改您的 SketchUp 模型。
- **可选共享令牌**。设置 `[security].auth_token` 并且每个请求都必须回显它。对于必须跨受信任的 LAN 暴露桥梁时很有用。
- **原始 Ruby 评估是按需启用的**。`execute_ruby` 工具对于 AI 代理很方便，但在共享/生产环境中使用时会在 SketchUp 内执行任意 Ruby 代码。请禁用它以用于共享/生产环境： `[experimental].enable_raw_ruby_exec = false`。
---
## 🧪 开发
```bash
# 克隆 + 安装开发依赖
git clone https://github.com/iamahsanmehmood/saie.git
cd saie
pip install -e ".[dev,all]"
# 运行单元测试
pytest tests/unit -v
# 运行集成测试（需要 SketchUp 运行并加载插件）
pytest tests/integration -v -m integration
# 整理代码
ruff check src/
# 类型检查
mypy src/saie src/su_mcp_bridge
```
有关完整的开发指南，请参阅 [CONTRIBUTING.md](CONTRIBUTING.md)。
---
## 📦 发布
SAIE 发布到：
- **PyPI** - `pip install saie`
- **GitHub Releases** - 轮子 + Ruby 插件 zip
- **Anthropic MCP 注册表** - 列出为一键式 Claude Desktop 安装
- **Smithery** - 列出在 <https://smithery.ai/server/saie>
- **mcp.so** - 社区 MCP 目录
- **Cline marketplace** - 插件安装卡
发布管道 + 清单：[docs/PUBLISHING.md](docs/PUBLISHING.md)
---
## 📄 许可证
[MIT](LICENSE) - © 2026 Ahsan Mehmood.
## 👤 作者
**Ahsan Mehmood** - [@iamahsanmehmood](https://github.com/iamahsanmehmood)
---
<div align="center">
*如果 SAIE 为您节省了时间，请 ⭐ 该仓库并告诉我们您构建了什么。*
</div>
MCP 配置
以下是此 MCP Server 的配置信息，可直接复制到 Cursor 或其他 MCP 客户端中使用。
mcp.json
连接信息
猜你喜欢
暂无推荐服务器