Copilot Addins for Revit - 插件开发模板

AI 友好的 Revit 插件开发脚手架，帮助开发者快速创建符合 Copilot For Revit 框架标准的命令插件。

仓库地址：https://github.com/ryanchan720/copilot-addins-for-revit-template

Copilot 生态

本仓库是 Copilot For Revit 生态的一部分：

仓库	定位	说明
copilot-for-revit	主框架	AI 驱动 Revit 的核心平台，支持 MCP 协议。负责插件加载、命令调度、与 AI 对话工具（Cline、Claude、Cherry Studio 等）通信。需先安装此框架才能使用插件。
本仓库	开发模板	AI 友好的插件开发脚手架。提供项目模板、开发规范、最佳实践，帮助开发者快速创建符合框架标准的命令插件。适合想要开发自定义命令的用户。
general-copilot-addins-for-revit	通用插件	提供现成的常用命令，覆盖元素查询、参数修改、标注创建、视图管理等高频场景。开箱即用，可直接安装到框架中。适合普通用户和快速上手。
openclaw-bridge	OpenClaw 桥接器	连接 OpenClaw 和 Copilot for Revit 的 CLI 工具，支持健康检查、工具发现、命令执行。
copilot-for-revit-skill	OpenClaw Skill	OpenClaw skill 包，安装后可在聊天工具中直接操作 Revit。

快速选择指南：

• 想用 AI 控制 Revit → 安装主框架 + 通用插件
• 想开发自己的命令 → 使用本模板（你正在看的这个）
• 想直接用现成功能 → 安装通用插件

---

阅读此文档以了解如何使用此开发环境

使用本模板开发的插件，需要配合 Copilot For Revit 框架运行：https://github.com/ryanchan720/copilot-for-revit

前置条件

• 已安装 Revit ( 2019 - 2024 )
• 已安装 Visual Studio 或 Rider
• 已安装 Git

准备工作

配置 Git

如果你尚未配置过 Git 凭据，可以运行以下命令进行配置：

git config --global user.name "你的用户名"
git config --global user.email "你的邮箱"

克隆仓库

导航至准备安装的位置运行以下命令克隆仓库：

git clone https://github.com/ryanchan720/copilot-addins-for-revit.git

完整流程示例

打开解决方案

导航至仓库目录，找到 CopilotAddins.sln 文件。使用 IDE 打开文件加载解决方案

了解文件结构

在解决方案资源管理器中，你将看到以下结构：

• Solution: README.md: 本开发环境的使用说明
• Project: HelloRevit: 一个简单的 Revit 插件示例项目。每个项目代表一组相关 ExternalCommand 的集合，你应该创建不同的新项目来管理每组相关的命令集
• HelloRevit/xxxCommand.cs 根目录: 存放实现 IExternalCommand 接口的类文件
• HelloRevit/Static/: 存放插件所需的外部静态文件，如配置文件等
• HelloRevit/Utils/: 存放开发过程中所需的工具类文件
• HelloRevit/Resource.resx: 资源管理类，你可以在这里添加一些静态资源如固定字符串、图片等，这些资源将直接编译进项目的 dll 文件中而无需外部引用
• HelloRevit/README.md: 在插件开发完成后，需要你填写的插件说明文档

构建示例插件

1. 确保当前解决方案配置为 Release 模式，目标框架为 x64
2. 在方案资源管理器中，右键点击 HelloRevit 项目并选择“生成”以编译插件

安装和分发

1. 导航至输出目录： HelloRevit\bin\
2. 检查 Release 文件夹，确保其中包含：
   • 生成的 dll 文件
   • 所有新增依赖
   • 程序运行所需的静态文件
   • README.md 文件
3. 复制并粘贴 Release 文件夹
4. 重命名文件夹为插件的项目名称，即文件夹名称与项目 dll 文件同名，如 HelloRevit
5. 将整个文件夹移动到 Copilot For Revit 框架指定的文件夹，通常是 %ProgramData%\RevitCopilot\RevitAddinPlatform\Addins\
6. Revit 启动后将自动识别和注册（也可在 Revit 运行时放入）

测试运行

参考 Copilot For Revit 说明

开始开发

现在你已经成功安装并运行了示例插件，可以开始根据需求复制、修改、扩展 HelloRevit 的代码或新建你自己的项目，实现你自己的功能。每次修改后，重复构建和安装步骤以测试新的功能。祝开发顺利！ 开发前，建议阅读下方开发原则和最佳实践

开发原则

插件开发应面向 AI 而非面向人类，如此在使用 AI 时才可达到高效和智能的体验，基于此核心原则，命令的开发应当尽量仿照 接口 的开发模式：无界面、无状态、单次交互

• 无界面：使用传参而非弹窗，代码中提供了传参入口和出口，用于插件与框架通信
• 无状态：每次发起的命令调用是独立的，它们之间互不影响，互不依赖，没有缓存状态的传递
• 单次交互：接口是单次交互的，一个请求对应一次响应，套用到插件上可以这么表述：非必要情况下，应将命令运行过程中所需的全部输入在调用时一次性传入，确保命令可以完整执行

最佳实践

每套相关的命令集使用一个独立项目用于统一管理

每个实现 IExternalCommand 接口的 Command 文件，使用 Command 作为文件名后缀，如 HelloRevitCommand.cs，帮助系统快速定位筛选命令入口

入参：在实现 IExternalCommand 的类中声明 public JObject Parameters { get; set; } 属性，运行时框架会将外部参数以 JSON 形式注入至 Parameters 属性，用法详见下方 Q&A 一节

当一个命令执行逻辑特别复杂，执行时间特别长时，建议将命令拆分为多个命令，并在 README 文档中对每个命令说明调用顺序和依赖关系

关于外部依赖（包括外部 dll 依赖库、 json 配置文件以及其他运行过程中需要的全部静态文件）：

• 代码中对外部依赖的引用必须使用相对路径，并确保输出的文件结构同开发时一致
• 所有你新增的外部依赖属性中 Copy Local 项必须设置为 True
• 有条件情况下做好自身依赖隔离，降低多插件环境下的出错概率

插件开发过程中，可将解决方案配置为 Debug 模式，通过 Addin Manager 工具进行常规调试

开发完成后，使用文档模板（README.md）为每个项目提供 README 文档，说明每个 Command 的具体使用方法，如果命令有入参的，需要声明入参的结构，这将决定 Revit Copilot 如何调用这些工具，详见下方 Q&A 一节

现有插件处理

现有插件改造，主要涉及 入口改造 和 交互改造 两个方面

入口改造

入口改造是必须的，它决定了插件能否被 Revit Copilot 识别和调用

工作内容比较简单，代码方面，将原有逻辑代码包装为一个类，放置到模板的 Command 逻辑部分，在 结果返回部分 传入命令执行结果

文档方面，在插件的 README.md 中，参照示例为每个命令填写说明

此改造完成后，Revit Copilot 将能够识别该命令，并适时调用

交互改造

交互改造是可选的，但强烈建议一同完成，它决定了插件的智能化水平

主要工作内容是依据于上述 开发原则，合理切分命令职责，让命令具备更高的通用性、原子性和灵活性，将原有的显式交互逻辑，如弹窗、对话框等这种 面向人类 的交互方式改为出入参传递这种 面向 AI 的交互方式

此改造完成后，Revit Copilot 将能够更智能地使用该命令，包括自动推理入参、编排多命令任务等，使得插件更加简单、通用和高效，接近真正的 Agent 级体验

Q&A

入参是如何由 AI 传递给命令的

Revit Copilot 在调用命令时，会将用户提供的相关信息，依据命令在 README 中定义的参数格式，动态注入至命令类中的 Parameters 属性，以便命令在执行过程中使用

这意味着，入参的结构定义和取值使用，都取决于命令开发者，Revit Copilot 只负责与用户对话并按结构传递参数

如何在 README 中定义参数结构

参数结构使用 Json Schema 进行定义，其规则比较复杂，建议直接定义好你的入参 Json 格式，发送给 AI 让它将其转换为 Json Schema 格式，人工检查即可

也可使用在线 Json Schema 生成工具

Json Schema 规范：Json Schema 规范（中文版）

如何从 Parameters 取值

// 假设 Parameters 注入的 JSON 参数为以下结构
JObject person = new JObject
{
    "name": "张三",
    "age": 25,
    "address": {
        "city": "北京",
        "street": "长安街"
    },
    "hobbies": ["读书", "游泳", "编程"]
};

// 直接访问
string name = (string)person["name"];
int age = (int)person["age"];

// 安全访问（避免异常）
string name2 = person["name"]?.Value<string>();
int? age2 = person["age"]?.Value<int>();

// 访问嵌套对象
string city = (string)person["address"]["city"];

// 访问数组
string firstHobby = (string)person["hobbies"][0];

超时时长意味着什么

超时时长是指命令从 AI 发起执行到返回结果的最长等待时间，单位为秒。如果命令在该时长内未能完成执行，AI 将不再等待结果，并返回超时错误信息给用户

注意，命令实际在继续进行，但其结果信息将不再通过 AI 返回给用户

超时时长的设置应根据命令的复杂度和预期执行时间来合理配置，避免过短导致频繁超时，或过长导致用户等待时间过久

建议最短不低于 20 秒，这中间包含了一部分系统处理时间