Revit 命令桥：让 AI 客户端直接操控 Revit 的本地桥接方案

一、这个项目要解决什么问题

如果你在做 BIM 自动化，大概会遇到这样几类需求：

想让 AI 助手帮你在 Revit 里批量建标高、轴网、墙体
想把 Revit 接到自己的工作流里（Python 脚本、后端服务、自动化平台）
想用不同厂商的模型（Codex、Claude、DeepSeek……），不想被某一个生态锁死
不想为了每个功能写一个插件命令，更不想在插件里开放任意代码执行

Revit 命令桥（Revit Command Bridge） 就是为这些场景设计的：一个面向 Revit 的本地命令桥。

它的定位可以用一句话概括：

Revit 插件只执行受控 Revit API 命令；Codex、WorkBuddy、任意 MCP 客户端、任意 Function Calling Harness 或 OpenAI 兼容模型 API，通过统一 JSON、CLI、REST 或 MCP 接口调用。

几个关键设计取向：

不依赖 Dynamo：纯 Revit API 实现，不引入 Dynamo 运行时
不绑定模型厂商：只要客户端能发 MCP、HTTP 或 Function Calling 参数即可
新建模统一走 execute_plan：一个计划可组合建筑、结构、机电、空间、出图、参数和选中显示，而不是为每一种构件增加一个插件命令
不开放任意代码执行：桥接层不执行任意 C#、Python 或自然语言，只接受已注册的顶层 operation 和受控原子步骤

二、版本支持：为什么不能用一个"万能 DLL"

这是 Revit 二次开发绕不过去的一条硬约束：

每个 Revit 年份必须使用对应 API 编译出的 DLL，不能共用一个"万能 DLL"。

原因是 Revit 的 API 程序集（RevitAPI.dll / RevitAPIUI.dll）与宿主版本强绑定，跨版本加载通常直接失败或行为异常。

本交付包支持 Revit 2020–2026，适配入口在 src/Adapter/ 下按 AdapterEntry20.cs ... 27.cs 组织，版本边界细节见仓库的 VERSION-SUPPORT.md。

对安装体验的优化在于：

单文件安装器会自动扫描本机 Revit 2020–2026，使用内置预编译适配包
普通用户不需要选择 DLL、安装 Visual Studio 或手工填写 Revit 路径
构建机器才需要准备对应年份的 Revit API NuGet 包（通过 Nice3point）和 .NET Framework 4.8 目标包 / .NET 8 SDK

三、工作方式与架构

原文给出的数据流非常清晰：

flowchart LR
    A["Codex / WorkBuddy / 任意模型或 Harness"] --> B["MCP / REST / CLI"]
    B --> C["本地原子 JSON 队列"]
    C --> D["对应年份的 Revit 插件"]
    D --> E["ExternalEvent 主线程调度"]
    E --> F["受控 Revit API + Transaction"]
    F --> G["结果 JSON / Revit 模型"]

    style A fill:#8b5cf6,stroke:#6d28d9,color:#fff
    style B fill:#3b82f6,stroke:#1e40af,color:#fff
    style C fill:#f59e0b,stroke:#b45309,color:#fff
    style D fill:#10b981,stroke:#047857,color:#fff
    style E fill:#10b981,stroke:#047857,color:#fff
    style F fill:#ef4444,stroke:#b91c1c,color:#fff
    style G fill:#64748b,stroke:#334155,color:#fff

这条链路里有几个值得注意的工程决策：

本地队列解耦：外部请求先落到本地原子 JSON 队列（inbox / outbox），插件再按需消费，避免外部进程直接触碰 Revit 线程模型
ExternalEvent 主线程调度：Revit API 不是线程安全的，所有操作必须回到主线程执行，ExternalEvent 是官方推荐的正规做法
事务化写入：execute_plan 中所有写步骤使用一个 all-or-nothing Revit Transaction，失败即整体回滚
网络面最小化：REST 默认只绑定 127.0.0.1，未检测到活动 Revit 桥时拒绝提交

四、安装

先看工具产出对照表，理解每个脚本干什么：

脚本	产出	说明
`dotnet build -c "Debug R26"`	`bin\R26\RevitCommandBridge.dll`	单版本 DLL，通过 .csproj + Nice3point NuGet
`build.ps1 -RevitVersion 2026`	`dist\RevitCommandBridge-2026\`	编译 DLL + 打包配套脚本
`build-all.ps1`	`dist\RevitCommandBridge-202{0..6}\`	全部版本 DLL
`build-installer.ps1`	`dist\RevitCommandBridgeSetup.exe`	单文件安装器（内置所有年份 DLL + Node）
`build-installer.ps1 -OutputPath ...`	自定义输出文件名	单版本安装器，方便版本区分
`install-revit.ps1`	→ `%LOCALAPPDATA%\RevitCommandBridge\{year}\`	复制文件 + 写 `.addin` 清单

01 方式 A：开发者模式（编译 → 安装）

# 0. 先关闭 Revit
# 1. 查看本机安装的 Revit 版本
.\install-revit.ps1 -ListDetected

# 2. 构建指定版本（编译 DLL + 打包安装器）
.\build.ps1 -RevitVersion 2026

# 或直接使用 dotnet：
dotnet build -c "Debug R26"

# 3. 安装到本机 Revit
.\install-revit.ps1 -RevitVersion 2026

build.ps1 产出：

dist\RevitCommandBridge-2026\
├── RevitCommandBridge.dll
├── RevitCommandBridge.pdb
├── bridge.config.json
├── scripts\      ← MCP Server、REST 网关、CLI 发送器
├── examples\     ← JSON 请求模板
├── deploy\       ← .addin 模板
├── schemas\      ← JSON Schema
├── install-revit.ps1
├── uninstall-revit.ps1
├── PROTOCOL.md 等文档

install-revit.ps1 自动完成六件事：

检测本机 Revit 安装路径（注册表 + C:\Program Files\Autodesk）
匹配 dist\RevitCommandBridge-{year}\ 包
复制所有文件至 %LOCALAPPDATA%\RevitCommandBridge\{year}\
写入 %APPDATA%\Autodesk\Revit\Addins\{year}\RevitCommandBridge.addin
清理旧版本残留文件（对比 install-manifest.json）
可选配置 AI 客户端连接（-Connector）

安装前确保 Revit 已关闭。install-revit.ps1 支持 -WhatIf 预览安装位置不实际写入。

02 方式 B：最终用户模式（单文件安装器）

# 步骤 1：编译指定版本
.\build.ps1 -RevitVersion 2026

# 步骤 2：打包安装器（默认输出 dist\RevitCommandBridgeSetup.exe）
.\build-installer.ps1

# 也可指定版本号后缀的输出文件名：
.\build-installer.ps1 -OutputPath "dist\RevitCommandBridgeSetup-2026.exe"

打包多个版本到同一个安装器：

.\build.ps1 -RevitVersion 2026
.\build.ps1 -RevitVersion 2027
.\build-installer.ps1 -RevitVersion 2026,2027 -OutputPath "dist\RevitCommandBridgeSetup-2026-2027.exe"

产出文件可分发到没有开发环境的机器：

dist\
├── RevitCommandBridgeSetup.exe ← 双击或命令行运行
├── RevitCommandBridge-2026\
└── RevitCommandBridge-2027\

RevitCommandBridgeSetup.exe 内置了 DLL 和 Node.js 运行时：

自动扫描本机 Revit
使用内置预编译适配包
自动配置已识别的 MCP 客户端（Codex、WorkBuddy、Claude Desktop、Cursor、Windsurf、Cline、Roo Code）

03 两条安装路径怎么选

flowchart TD
    S["要安装 Revit 命令桥"] --> Q{"你手上是
源码还是安装器？"}

    Q -->|"源码（自己编译）"| A["方式 A：开发者模式"]
    Q -->|"RevitCommandBridgeSetup.exe"| B["方式 B：最终用户模式"]

    A --> A1["install-revit.ps1 -ListDetected"]
    A1 --> A2["build.ps1 -RevitVersion 20XX"]
    A2 --> A3["install-revit.ps1 -RevitVersion 20XX"]
    A3 --> E["启动 Revit，桥接自动加载"]

    B --> B1["双击 Setup.exe"]
    B1 --> B2["自动扫描 Revit 2020–2026"]
    B2 --> B3["内置适配包 + Node 运行时"]
    B3 --> E

    E --> V["健康检查返回 status: ok"]

    style S fill:#8b5cf6,stroke:#6d28d9,color:#fff
    style A fill:#3b82f6,stroke:#1e40af,color:#fff
    style B fill:#10b981,stroke:#047857,color:#fff
    style V fill:#f59e0b,stroke:#b45309,color:#fff

04 验证安装

启动 Revit 并打开项目后，桥接自动启动。运行健康检查：

& "$env:LOCALAPPDATA\RevitCommandBridge\2026\scripts\send-revit-command.ps1" `
  -RequestPath "$env:LOCALAPPDATA\RevitCommandBridge\2026\examples\health.json"

返回 "status": "ok" 即安装成功。功能区"Revit 命令桥"选项卡的"启动桥接"按钮也可确认连接信息。

05 卸载

.\uninstall-revit.ps1 -RevitVersion 2026

卸载程序会移除桥接文件、.addin 注册清单和队列目录。不同年份的桥接互不干扰，只卸载指定版本。

五、快速开始

启动 Revit（以 2026 为例）：

& 'C:\Program Files\Autodesk\Revit 2026\Revit.exe'

打开 Revit 后，桥接会自动启动；功能区"Revit 命令桥"的"启动桥接"按钮可用于确认连接信息。

随后执行一次只读健康检查：

& "$env:LOCALAPPDATA\RevitCommandBridge\2026\scripts\send-revit-command.ps1" -RequestPath "$env:LOCALAPPDATA\RevitCommandBridge\2026\examples\health.json"

预览一个通用建模计划，不修改模型：

& "$env:LOCALAPPDATA\RevitCommandBridge\2026\scripts\send-revit-command.ps1" -RequestPath "$env:LOCALAPPDATA\RevitCommandBridge\2026\examples\preview-universal-plan.json"

确认预览返回正确后，把请求中的 preview 改为 false 再提交。实际写入使用 Revit Transaction，可在 Revit 中用原生撤销命令回退。

功能区"命令面板"提供当前桥接状态、最近操作和当前项目状态；点击"刷新项目状态"会提交只读 health 请求。“预览计划"不会修改模型，“确认执行"会再次要求确认；完成后用 Revit 原生 Ctrl+Z 撤销该事务。

一次典型的"预览 → 确认"流程

sequenceDiagram
    autonumber
    participant U as 用户 / AI 客户端
    participant S as send-revit-command.ps1
    participant Q as 本地 JSON 队列
    participant P as Revit 插件
    participant R as Revit 文档

    U->>S: 提交 health.json（只读）
    S->>Q: 写入 inbox
    Q->>P: 消费请求
    P->>R: 查询文档信息
    R-->>P: 标题 / 路径 / 活动视图
    P->>Q: 写入 outbox
    Q-->>U: 返回 status: ok

    U->>S: 提交计划（preview = true）
    S->>Q: 写入 inbox
    Q->>P: 消费请求
    P->>P: 校验 operation 与参数
    P-->>U: 返回预览结果（模型未变）

    U->>S: 同一请求（preview = false）
    S->>Q: 写入 inbox
    Q->>P: 消费请求
    P->>R: 开启 Transaction，执行写步骤
    alt 全部成功
        R-->>P: Commit（所有步骤生效）
    else 任一步骤失败
        R-->>P: Rollback（整体回滚）
    end
    P-->>U: 返回结果 JSON
    Note over R: 可用 Revit 原生 Ctrl+Z 撤销

六、接入不同客户端

安装器固定使用"自动识别并配置本机 AI 客户端”。它会生成并保存连接配置到安装目录的 connections 文件夹；未识别的客户端直接使用"复制 MCP"按钮提供的通用配置。

先看能力与入口的对照：

客户端能力	入口	适用场景
支持 stdio MCP	`scripts/revit-mcp-server.mjs`	Codex、WorkBuddy 和其它 MCP Harness
能调用 HTTP	`scripts/revit-http-gateway.mjs`	任意 Function Calling Harness、后端服务、自动化平台
只有 OpenAI 兼容模型 API	`scripts/revit-openai-compatible-chat.mjs`	DeepSeek 及其它支持 Chat Completions + Tool Calling 的模型
能运行 PowerShell	`scripts/send-revit-command.ps1`	Codex Shell、人工测试、批处理
只能读写文件	`%LOCALAPPDATA%\RevitCommandBridge\inbox/outbox`	自定义旧系统或最小 Harness

用一张图理解五种接入方式的定位：

flowchart LR
    C1["MCP 客户端
Codex / WorkBuddy"] -->|"stdio MCP"| BRIDGE
    C2["Function Calling Harness
后端服务 / 自动化平台"] -->|"HTTP"| BRIDGE
    C3["OpenAI 兼容模型 API
DeepSeek 等"] -->|"Chat Completions + Tool Calling"| BRIDGE
    C4["命令行 / 批处理"] -->|"PowerShell CLI"| BRIDGE
    C5["最小 Harness / 旧系统"] -->|"文件读写"| BRIDGE

    BRIDGE["本地原子 JSON 队列
inbox / outbox"]
    BRIDGE --> PLUGIN["对应年份 Revit 插件"]
    PLUGIN --> REVIT["Revit 模型"]

    style BRIDGE fill:#f59e0b,stroke:#b45309,color:#fff
    style PLUGIN fill:#10b981,stroke:#047857,color:#fff
    style REVIT fill:#3b82f6,stroke:#1e40af,color:#fff

01 Codex MCP

优先在 Revit 功能区点击"复制 MCP”，再粘贴到客户端的 MCP 配置页。手工配置时，使用安装器内置的年份 Node 运行时（不要求另装 Node.js）：

[mcp_servers.revit]
command = "C:\\Users\\<用户名>\\AppData\\Local\\RevitCommandBridge\\2026\\runtime\\node.exe"
args = ["C:\\Users\\<用户名>\\AppData\\Local\\RevitCommandBridge\\2026\\scripts\\revit-mcp-server.mjs"]

重新启动 Codex 任务后，客户端可发现 revit_execute_plan。这是长期主入口；旧的 revit_create_wall 等工具仅为兼容已有脚本保留。

02 通用 MCP JSON

使用 JSON MCP 配置的客户端采用相同进程参数：

{
  "mcpServers": {
    "revit-command-bridge": {
      "command": "C:\\Users\\<用户名>\\AppData\\Local\\RevitCommandBridge\\2026\\runtime\\node.exe",
      "args": [
        "C:\\Users\\<用户名>\\AppData\\Local\\RevitCommandBridge\\2026\\scripts\\revit-mcp-server.mjs"
      ]
    }
  }
}

03 REST 与通用 Function Calling Harness

启动仅监听本机的 REST 网关：

node "$env:LOCALAPPDATA\RevitCommandBridge\2026\scripts\revit-http-gateway.mjs"

查询状态：

Invoke-RestMethod 'http://127.0.0.1:8765/health'

提交并等待预览结果：

$body = @{
  operation = 'execute_plan'
  args = @{
    steps = @(
      @{ id = 'check'; operation = 'query_document'; args = @{} }
      @{ id = 'support'; operation = 'create_direct_shape'; args = @{ name = '测试支座' geometry = @(@{ kind = 'box'; min = @{ x = 0; y = 0; z = 0 }; max = @{ x = 3000; y = 2000; z = 2500 } }) } }
    )
  }
  preview = $true
} | ConvertTo-Json -Depth 12

Invoke-RestMethod -Method Post -Uri 'http://127.0.0.1:8765/commands?wait_seconds=60' -ContentType 'application/json; charset=utf-8' -Body $body

远程模型 API 本身不直接访问本机 Revit；本机 Harness 把 Function Calling 参数转发到这个 REST 端点，或直接启动 MCP Server。

需要使用模型 API 时，运行 scripts/configure-ai-provider.ps1 保存配置，再启动本机助手。API Key 使用 Windows DPAPI 按当前用户加密保存，不写入 MCP/REST 配置文件。

七、当前能力范围

模块	已实现的高频操作
查询与编辑	文档、目录、元素、参数、删除、选择与定位
建筑	标高、轴网、墙、楼板、墙洞口、模型线、房间、空间、DirectShape
结构	梁、柱、斜撑，以及已载入结构族的实例放置
MEP	管道、风管、线管、桥架、直连/弯头/三通/活接连接
族	样板查询、新建 `.rfa`、参数、类型、box/cylinder/extrusion 几何、保存、载入、放置
放置方式	非宿主、宿主、面宿主、工作平面、视图、线基和自适应族
出图与注释	3D / 平面 / 天花 / 结构平面 / 绘图 / 剖面 / 立面 / 详图索引视图、复制与样板、图纸、视图/明细表放图纸、详图线、文字、尺寸、标签、填充区域、修订及修订云线
导出与交付	PNG/JPG/TIFF/BMP 图像、DWG/DXF、IFC、明细表 CSV/TXT、保存 `.rvt`；导出/保存须作为独立计划执行

用于出图时，先以 query_catalog(kind=view_types|title_blocks|text_types|filled_region_types|revisions) 查询项目资源；需要尺寸或标签时，以 query_references 读取元素稳定引用，再提交 create_dimension 或 create_tag。

export 和 save_document 有外部文件副作用，须分别放在只含一个步骤的 execute_plan 中。

关于"为什么不做成万能执行器"，原文的态度很明确：

“Revit 的所有功能"包含数千个 API 对象，桥接不会开放任意 C# 执行；新增能力统一以受控原子步骤加入 execute_plan。

八、原子操作一览

所有顶层 operation 和 execute_plan 中的 steps[].operation 均由一张注册表调度。

01 顶层操作（直接传入 `operation` 字段）

操作名称	功能
`health`	桥接健康检查，返回状态、文档信息
`execute_plan`	主入口。执行多步骤建模/出图计划，写步骤合并为一个事务
`new_project`	创建新项目（可选 .rte 样板），可选保存为 .rvt
`create_family`	从 .rft 样板创建 .rfa 族，支持参数/类型/几何
`load_family`	载入已有 .rfa 到当前项目
`list_family_templates`	列出本机 Revit 族样板路径
`list_levels`	列出项目标高（兼容旧入口）
`list_wall_types`	列出基本墙类型（兼容旧入口）
`create_level`	创建标高（兼容旧入口）
`create_grid`	创建轴网（兼容旧入口）
`create_wall`	创建直墙（兼容旧入口）
`create_rectangle_walls`	创建四面闭合矩形墙（兼容旧入口）

02 查询类原子步骤

操作名称	功能
`query_document`	返回当前文档信息（标题、路径、活动视图等）
`query_catalog`	项目资源目录：标高、类别、视图、图纸、明细表、族类型、MEP 类型、链接等
`query_elements`	按类别/名称/族名/ID 过滤查询元素及其参数
`query_references`	返回元素的稳定几何引用（面/边）
`query_parameters`	列出单个元素的所有参数
`query_geometry`	返回元素包围盒、实体摘要或面信息
`query_room`	查询房间/空间，支持按点查找或全量列出
`query_selection`	读取 Revit 界面当前选中的图元 ID、名称、类别
`query_mep_network`	从种子元素遍历 MEP 连接拓扑
`query_view_range`	返回平面视图范围（顶/剖切面/底/视图深度）

03 创建类原子步骤

操作名称	功能
`create_level`	创建标高
`create_grid`	创建轴网
`create_wall`	创建直墙，支持新墙类型克隆
`create_floor`	从闭合轮廓创建楼板
`create_room`	创建房间
`create_space`	创建 MEP 空间
`create_model_curve`	创建模型线
`create_direct_shape`	从几何图元（box/cylinder/sphere 等）创建 DirectShape
`create_swept_shape`	沿路径扫掠创建实体（矩形/圆形/管道截面）
`create_mep_curve`	创建 MEP 管线（管道/风管/线管/桥架）
`connect_mep`	连接 MEP 元素，支持直连/弯头/三通/变径/四通
`create_mep_system`	创建管道或风管系统
`create_insulation`	添加管道/风管保温层
`place_family_instance`	放置族实例，支持多种放置方式
`load_family`	载入 .rfa 到项目
`create_structural_member`	创建结构构件（梁/斜撑/柱）
`create_view`	创建 3D/平面/天花/结构平面视图
`create_sheet`	创建图纸（可选标题栏）
`place_view_on_sheet`	将视图放置到图纸
`create_opening`	创建洞口（墙/楼板/竖井）
`create_drafting_view`	创建绘图视图
`create_section_view`	创建剖面/详图视图
`create_elevation_view`	创建立面视图
`create_callout`	创建详图索引视图
`duplicate_view`	复制视图，可选应用视图样板
`create_view_template`	从现有视图创建视图样板
`create_detail_curve`	创建详图线
`create_text_note`	创建文字注释
`create_dimension`	创建尺寸标注
`create_tag`	创建独立标记
`create_filled_region`	创建填充区域
`create_revision`	创建修订
`create_revision_cloud`	创建修订云线
`create_schedule`	创建明细表（常规/材质提取/关键字/视图列表/图纸列表/修订）
`place_schedule_on_sheet`	将明细表放置到图纸

04 视图属性与覆盖

操作名称	功能
`set_view_properties`	设置视图属性（比例、裁剪框、样板、详细程度、规程等）
`set_element_overrides`	设置元素图形覆盖（颜色、线宽、半色调等）
`set_category_overrides`	设置类别图形覆盖
`manage_view_filters`	管理视图过滤器（添加/删除，支持规则与覆盖）
`set_view_range`	设置平面视图范围（顶/剖切面/底/视图深度）
`manage_schedule_fields`	管理明细表字段（添加/删除/隐藏/排序/过滤）
`manage_graphics_resources`	管理图形资源（线样式子类别/填充图案）

05 编辑与变更

操作名称	功能
`set_parameters`	批量设置元素参数值
`manage_schema_data`	扩展数据读写与搬运
`manage_family_parameters`	编辑族参数（添加/重命名/删除/设公式）
`manage_project_parameters`	管理项目参数
`duplicate_type`	复制 ElementType，可选覆盖参数
`transform_elements`	移动/复制/旋转/镜像元素
`rename_element`	重命名元素（单个或批量前缀模式）
`set_element_curve`	修改线性元素的 LocationCurve
`delete_elements`	删除元素
`select_elements`	选中并显示/缩放至元素

06 外部操作（需单独执行）

操作名称	功能
`export`	导出视图（PNG/JPG/DWG/DXF/IFC/明细表 CSV）
`save_document`	保存当前文档

全部操作共约 73 个原子步骤。新增能力以受控原子步骤加入此表，不开放任意 C# 执行。完整参数定义见 PROTOCOL.md 和 schemas/execute-plan.schema.json。

九、目录结构

revit-mcp-local-bridge/
│
├── src/                    ← ★ 单一事实源（全部版本共享）
│   ├── BridgeModels.cs
│   ├── BridgeRuntime.cs
│   ├── PlanCommandExecutor.cs
│   ├── PlanValues.cs
│   ├── RevitApiExtensions.cs
│   ├── RevitCommandBridgeApp.cs
│   ├── RevitCommandExecutor.cs
│   ├── RevitFamilyOperations.cs
│   ├── RevitGeometryFactory.cs
│   ├── RevitLookups.cs
│   ├── RevitOutputOperations.cs
│   ├── RevitParameterAdmin.cs
│   ├── RevitPlanCreations.cs
│   ├── RevitPlanMutations.cs
│   ├── RevitPlanQueries.cs
│   ├── RevitPlanOperations.cs
│   ├── RevitSectionFactory.cs
│   ├── CommandPanelForm.cs
│   ├── BridgeFailurePreprocessor.cs
│   ├── BridgeFamilyLoadOptions.cs
│   ├── BridgeFileQueue.cs
│   ├── BridgeSchemas.cs
│   ├── BridgeBuildInfo.cs
│   ├── GlobalUsings.cs
│   │
│   ├── Adapter/             ← 版本适配入口（R20–R27）
│   │   ├── AdapterEntry20.cs .. 27.cs
│   │   └── Utils/           ← 工具类
│   │
│   ├── build/               ← 版本矩阵
│   └── version-manifest.json
│
├── scripts/                 ← 运行时脚本
│   ├── revit-mcp-server.mjs
│   ├── revit-http-gateway.mjs
│   ├── revit-openai-compatible-chat.mjs
│   ├── bridge-client.mjs
│   ├── send-revit-command.ps1
│   ├── configure-ai-provider.ps1
│   ├── configure-connector.ps1
│   ├── configure-detected-clients.ps1
│   └── start-openai-compatible-chat.ps1
│
├── examples/                ← 请求示例
│   ├── health.json
│   ├── create-level.json
│   ├── preview-rectangle-walls.json
│   ├── preview-universal-plan.json
│   ├── preview-create-family.json
│   ├── preview-export-image.json
│   ├── preview-architecture-output-plan.json
│   └── preview-output-documentation-plan.json
│
├── schemas/
│   └── execute-plan.schema.json
│
├── plans/                   ← 设计方案
│   ├── BUILD-PIPELINE.md
│   ├── EXTENSION-PLAN.md
│   ├── CAD-BRIDGE-PLAN.md
│   ├── ATOMIC-ANALYSIS.md
│   ├── FAQ.md
│   └── PR-DESCRIPTION.md
│
├── deploy/
│   ├── RevitCommandBridge.addin.template
│   └── RevitCommandBridge.2026.addin    ← 生成部署清单
│
├── verification/
│   └── 2026-08-19-regression.md
│
├── setup/
│   ├── RevitAIHubSetup.cs
│   └── RevitCommandBridge.ico
│
├── depandency/              ← 预编译依赖（SQLite、Json、RevitAPI 等）
├── release/                 ← 发布包输出
│
├── build.ps1                ← 单版本编译
├── build-all.ps1            ← 全版本批量编译
├── build-installer.ps1      ← 安装器打包
├── install-revit.ps1        ← 安装/检测
├── uninstall-revit.ps1
├── fix_all.ps1
├── fix_value.ps1
├── RevitCommandBridge.csproj      ← 单一项目，条件编译 R20–R26
├── RevitCommandBridge.slnx        ← .slnx 新格式解决方案
├── PROTOCOL.md
├── ARCHITECTURE.md
├── VERSION-SUPPORT.md
├── CONNECTORS.md
├── ENGINEERING-RECORD.md
├── NOTICE.md
├── LICENSE
├── SOURCE-PACKAGE.txt
└── README.md

更多构建管道细节见仓库内的 plans/BUILD-PIPELINE.md。

十、安全边界与设计约束

这部分虽然不是"功能清单”，但它决定了这个项目能否被放心地接进生产流程。

flowchart TD
    REQ["外部请求
MCP / REST / CLI / 文件"] --> V1{"顶层 operation
是否已注册？"}
    V1 -->|否| REJ1["拒绝"]
    V1 -->|是| V2{"原子步骤参数
是否合法？"}
    V2 -->|否| REJ2["拒绝"]
    V2 -->|是| V3{"目标文档
是否匹配？"}
    V3 -->|否| REJ3["拒绝"]
    V3 -->|是| TX["Revit Transaction
all-or-nothing"]
    TX -->|成功| OK["Commit + 结果 JSON"]
    TX -->|失败| RB["Rollback"]

    style REJ1 fill:#ef4444,stroke:#b91c1c,color:#fff
    style REJ2 fill:#ef4444,stroke:#b91c1c,color:#fff
    style REJ3 fill:#ef4444,stroke:#b91c1c,color:#fff
    style TX fill:#f59e0b,stroke:#b45309,color:#fff
    style OK fill:#10b981,stroke:#047857,color:#fff
    style RB fill:#64748b,stroke:#334155,color:#fff

核心约束可以归纳为四条：

不执行任意代码：不执行任意 C#、Python 或自然语言，只接受已注册的顶层 operation 和受控原子步骤
校验前置：校验参数和目标文档后才调用 Revit API
事务原子性：execute_plan 中所有写步骤使用一个 all-or-nothing Revit Transaction
网络面收敛：REST 默认只绑定 127.0.0.1，未检测到活动 Revit 桥时拒绝提交

关于可扩展性，原文的表述也很克制：

客户端识别只是安装层适配器，不进入 Revit 插件核心。以后支持新软件只增加一条配置适配规则，不需要重新设计 Revit 命令协议或建模功能。

十一、常见问题

现象	原因与处理
REST 返回 `503 bridge_not_running`	Revit 未启动、插件未加载，或启动后尚未完成初始化
返回"尚未打开项目文档"	在 Revit 中打开或新建 `.rvt` 项目后重试
返回文档标题不一致	请求指定了 `document_title`，但当前活动项目不是该文档
返回命令 ID 已存在	读取已有 outbox 结果，或生成新 id
Revit 功能区没有按钮	检查 `%APPDATA%\Autodesk\Revit\Addins\<year>\RevitCommandBridge.addin`
其它年份 Revit 不加载	为对应年份重新引用 `RevitAPI.dll` / `RevitAPIUI.dll` 并编译适配包

十二、写在最后

这个项目的思路其实很清晰：把"能力"和"接入方式"彻底分开。

Revit 插件这一侧只做一件事——执行受控的 Revit API 原子操作，用事务保证一致性
接入层这一侧则完全开放——MCP、REST、CLI、OpenAI 兼容 API、文件队列，随便什么 Harness 都能接

这种分层带来的好处是：换模型、换客户端、换编排框架，都不需要动 Revit 插件本体。对 BIM 这种工具链常年迭代、版本碎片化严重的领域来说，这个取舍很实用。

如果你也想让 AI 助手直接在你的 Revit 项目里干活，又不想开放"任意代码执行"这种危险的口子，这个桥接方案值得研究一下。

风险提示：本文为项目文档整理，所述脚本包含本机 Revit 插件安装、写入 %APPDATA%、启动本地服务（127.0.0.1:8765）以及保存 API 密钥配置等操作。实际使用前请自行评估环境风险，并在测试项目中先行验证。文中命令与配置以仓库文档为准，不同版本可能有所差异。