⚠️AI 生成大家参考食用

适用环境：macOS Sequoia 15.x | ArchiCAD 27/28 | Apple Silicon (M1/M2/M3)

写在前面：为什么必须用 Xcode?

在 AI 辅助开发的时代,很多建筑师习惯用 VS Code 编写 Python 脚本,通过 Cursor 或 Copilot 快速生成代码。但当你想为 ArchiCAD 开发原生菜单插件(Add-On)时,情况完全不同。

这不是工具偏好问题,而是技术架构决定的。

根据 Graphisoft 官方开发文档,ArchiCAD 在 macOS 平台的 API DevKit 深度依赖 Xcode 生态系统。其资源编译系统(.grc 文件)、框架链接(Frameworks)、代码签名机制都是为 Xcode 设计的。虽然理论上可以用其他工具,但官方明确表示”不支持其他开发环境”。

我的建议是采用混合工作流：

• • Xcode：负责编译、构建、签名(这是它的强项)
• • VS Code：负责编写算法逻辑、Python 脚本(这是你熟悉的)

本文聚焦第一步：如何在 macOS 上成功编译出你的第一个 .bundle 插件文件。

一、环境准备：版本对应很重要

根据 Graphisoft 官方兼容性文档,ArchiCAD 对开发环境的版本要求如下：

1. 必需软件清单

ArchiCAD 软件本体

• • ArchiCAD 27 或 28 完整版(非 DEMO 版需要注册 MDID)
• • macOS Sequoia (15.x) 完全兼容 AC 27/28

开发工具

• • Xcode：建议使用 Xcode 15 或 16
• • 安装后务必运行一次并同意协议
• • 或在终端执行：sudo xcodebuild -license
• • CMake：项目构建工具(最低版本 3.16)
• • 推荐通过 Homebrew 安装：brew install cmake
• • 或访问 cmake.org 下载安装包
• • API DevKit：从 Graphisoft 开发者网站 下载
• • 关键点：DevKit 版本必须与 ArchiCAD 版本精确匹配
• • 解压路径不能包含中文或空格

2. 版本匹配规则

根据官方文档,ArchiCAD 无法加载使用不同版本 DevKit 编译的插件。这是硬性限制,无法绕过。

示例：

• • 开发 AC 27 插件 → 必须用 AC 27 DevKit
• • 开发 AC 28 插件 → 必须用 AC 28 DevKit

二、获取官方项目模板

不要从零编写 C++ 代码。 Graphisoft 提供了官方 CMake 模板,已经配置好所有必需的构建参数。

下载模板

访问 GitHub 仓库：archicad-addon-cmake

操作步骤：

1. 1. 下载并解压
2. 2. 将文件夹重命名为有意义的名称,如 My_First_Plugin
3. 3. 确保路径中没有中文或空格

模板特点：

• • 支持 ArchiCAD 25 及以上版本
• • 包含完整的多语言支持框架
• • 预配置了所有必需的 ArchiCAD 模块

三、使用 CMake 生成 Xcode 项目

这是整个流程中最关键的一步。我们需要通过 CMake 将模板转换为 Xcode 可以打开的项目文件。

命令行操作

假设你的文件结构如下：

• • SDK 路径：~/Dev/AC27_SDK/
• • 项目路径：~/Dev/My_First_Plugin/

在终端(Terminal)中执行：

# 1. 进入项目目录cd ~/Dev/My_First_Plugin/# 2. 创建构建目录(保持源代码整洁)mkdir Buildcd Build# 3. 生成 Xcode 项目# 注意：路径末尾的 ".." 不能省略cmake -G "Xcode" \  -DAC_API_DEVKIT_DIR=~/Dev/AC27_SDK/Support \  ..

参数说明

• • -G "Xcode"：指定生成器为 Xcode
• • -DAC_API_DEVKIT_DIR：DevKit 的 Support 文件夹路径(这是核心参数)
• • ..：表示在父目录查找 CMakeLists.txt

成功标志：终端显示 -- Build files have been written to: ...

四、在 Xcode 中配置项目

1. 打开项目

进入 Build 文件夹,双击 .xcodeproj 文件用 Xcode 打开。

2. 修改插件名称

位置：左侧目录树 → Sources → Resources → RFIX → 打开 .grc 文件

修改内容示例：

// 原始内容'STR#' 32000 "Add-On Name and Description" {    "Example Add-On"    "Example Add-On Description"}// 修改为'STR#' 32000 "Add-On Name and Description" {    "AI 工具箱"    "ArchiCAD AI 辅助设计工具"}

3. 配置代码签名(macOS Sequoia 强制要求)

根据 Apple 的安全策略,macOS Sequoia 不允许运行未签名的应用扩展。

操作步骤：

1. 1. 点击左侧蓝色项目图标
2. 2. 选择 Signing & Capabilities 标签页
3. 3. Team：选择你的 Apple ID(Personal Team)
• • 如无 Apple Developer 账号,选择 Sign to Run Locally
4. 4. Bundle Identifier：修改为唯一标识符
• • 示例：com.yourname.archicad.plugin
• • 避免与其他插件冲突

五、编译与安装

1. 编译插件

在 Xcode 中：

• • 确保左上角目标设备选择 My Mac
• • 按 Command + B 或点击播放按钮
• • 等待编译完成,显示 Build Succeeded

编译产物：左侧 Products 目录下会生成 .bundle 文件

2. 安装到 ArchiCAD

方法一：通过 Add-On Manager(推荐用于测试)

1. 1. 右键 .bundle 文件 → Show in Finder
2. 2. 打开 ArchiCAD
3. 3. 菜单：Options → Add-On Manager
4. 4. 点击 Add 按钮,选择 .bundle 文件

重要提示：开发期间建议直接从构建目录加载,这样每次重新编译后 ArchiCAD 会自动更新,无需重启。

方法二：安装到 Add-Ons 目录(用于正式发布)

复制 .bundle 文件到：

/Applications/Graphisoft/ARCHICAD 27/Add-Ons/

3. 验证安装

重启 ArchiCAD,检查菜单栏是否出现你定义的插件名称。

六、常见问题与解决方案

问题 1：编译错误 “No member named ‘GS_realloc'”

原因：Xcode 16 在 macOS Sequoia 上编译 AC 27 DevKit 时存在兼容性问题

解决方案：

• • AC 27 用户：等待 Graphisoft 发布兼容性更新
• • AC 28 用户：此问题已修复

临时解决方案：参考 Graphisoft 社区的技术讨论串

问题 2：插件只能在 DEMO 版运行

原因：未注册 MDID(Module Developer ID)

解决方案：

1. 1. 访问 Graphisoft 开发者网站
2. 2. 注册成为开发者(免费)
3. 3. 为你的插件申请 MDID
4. 4. 在项目中配置 MDID

问题 3：macOS 阻止插件运行

原因：安全策略限制

解决方案：

• • 确保在 Xcode 中正确配置了代码签名
• • 首次运行时在 System Settings → Privacy & Security 中允许

七、下一步：混合开发工作流

完成上述步骤后,你已经获得了一个可以在 ArchiCAD 菜单栏显示的”入口”。

接下来的进阶路径：

1. 1. C++ 层：处理 ArchiCAD API 调用、UI 交互
• • 使用 Xcode 编写和调试
• • 参考 DevKit 中的 Examples 文件夹
2. 2. Python 层：实现算法逻辑、AI 模型调用
• • 使用 VS Code 编写
• • 通过 C++ 的 system() 或进程通信调用
3. 3. 数据交换：JSON 文件或内存共享
• • C++ 写入参数 → Python 处理 → 返回结果

这才是 BIM + AI 真正落地的实用工作流。

总结

本文基于 Graphisoft 官方文档和实际开发经验,梳理了 macOS 平台 ArchiCAD 插件开发的完整环境配置流程。

关键要点：

1. 1. 必须使用 Xcode 进行编译(官方唯一支持的 macOS IDE)
2. 2. DevKit 版本必须与 ArchiCAD 版本精确匹配
3. 3. macOS Sequoia 要求强制代码签名
4. 4. 推荐混合开发模式：Xcode + VS Code

参考资料：

• • ArchiCAD API 官方文档
• • archicad-addon-cmake GitHub 仓库
• • Graphisoft 开发者社区

作者信息环境：macOS Sequoia 15.7 | ArchiCAD 29 solo | Apple Silicon M1 Pro⚠️ AI 说：

本文所有技术细节均基于 Graphisoft 官方文档验证,欢迎指正交流。