目录

• 核心特性
• 架构
• 快速开始
  • 运行前提
  • 安装
  • 启动
  • AC28 + AC29 双版本并存
• 客户端配置
• 沙箱白名单
• 验证连接
• 测试与基准
• 项目结构
• 工具一览
• 图片识别 → 建模计划
• 安全设计
• 版本历史
• 实机验证进度
• 参考文档

核心特性

架构

flowchart TB
    subgraph Client["MCP 客户端"]
        C[Claude Desktop / Cursor / Kimi / Trae / Codex / WorkBuddy]
    end
    subgraph Server["ArchiCAD MCP Server"]
        S[Python FastMCP<br/>66 工具]
    end
    subgraph AC["ArchiCAD 实例"]
        A1[AC29 + Tapir]
        A2[AC28 + Tapir]
    end
    C -->|stdio| S
    S -->|TCP 19723| A1
    S -->|TCP 19724| A2
    style C fill:#4a90e2,color:#fff
    style S fill:#7ed321,color:#fff
    style A1 fill:#f5a623,color:#fff
    style A2 fill:#f5a623,color:#fff

技术栈：Python ≥ 3.10 · FastMCP · 官方 archicad Python 包 · Tapir Add-On

快速开始

运行前提

1. ArchiCAD 26–29 已启动并打开项目（主目标 AC29 build 3000+）
2. 选项 → 工作环境 → 连接端口 已启用
3. Python ≥ 3.10
4. 对应版本的 Tapir Add-On 已加载
   • 下载：https://github.com/ENZYME-APD/tapir-archicad-automation
   • 通过 选项 → Add-On 管理器 → 添加 加载

安装

方式一：从 PyPI 安装（推荐，发布后可用）

pip install archilinkai
# 启动（archilinkai 命令）
archilinkai
# 或
python -m archilinkai

方式二：从源码安装（当前开发态）

pip install -e ".[dev]"

启动

三种启动方式等价：

archilinkai          # PyPI 安装后的命令入口（等价 archilinkai serve）
python -m archilinkai
python server.py     # 源码目录兼容壳（保留旧配置可用）

无 ArchiCAD 实例时 server 仍会启动并打印提示，工具调用时返回结构化错误（NO_INSTANCE_AVAILABLE，retryable=true），便于 LLM 引导排查。

环境自检与客户端配置

archilinkai doctor            # 六项环境自检：Python/依赖/实例/Tapir，逐项给修复建议
archilinkai install claude    # 自动写入 Claude Desktop 配置（先备份原文件）
archilinkai install cursor    # 写入 Cursor ~/.cursor/mcp.json
archilinkai install generic   # 打印通用 MCP JSON 片段，任意客户端手动粘贴

支持的客户端矩阵见 src/archilinkai/data/clients.json（Claude/Cursor/Cline/Witsy/Cherry Studio/Codex 等，可随版本扩充）。

HTTP 远程模式（平台接入）

供 Dify/Coze/n8n 等非 stdio 平台及远程智能体接入（需 pip install 'archilinkai[http]'）：

archilinkai serve --http --port 8000 --token <你的密钥>
# 或环境变量：set ALAI_TOKEN=<密钥>

• 安全默认：无 token 拒绝启动；默认只绑 127.0.0.1（跨机访问显式 --host 0.0.0.0）
• Bearer 鉴权：请求头 Authorization: Bearer <token>，未带/错误一律 401
• 全量请求审计：output/http_audit.jsonl（时间/方法/路径/状态，不含正文）
• 接入点：POST http://<host>:<port>/mcp（MCP streamable-http 协议）

桌面安装器

非技术用户可下载双击安装（无需手动装 Python/写配置），见 docs/s2_installer.md：

• 安装器捆绑嵌入式 Python + 本地 wheel，pip install --no-index 离线安装
• 自动写入 MCP 客户端配置；Tapir 按 AC 版本从 GitHub 自动下载（download_tapir.py）
• AC 版本→Tapir 映射维护在 src/archilinkai/data/tapir_versions.json

AC28 + AC29 双版本并存说明

本项目支持同时连接多个 ArchiCAD 大版本实例。装的是 AC28 和 AC29 时需注意：

• Tapir Add-On 与大版本一一绑定：AC29 的 Tapir 不适用于 AC28，反之亦然。必须分别下载 AC28 和 AC29 对应版本的 .apx，在各自 ArchiCAD 里通过 选项 → Add-On 管理器 → 添加 加载。
• 端口分配：每个 ArchiCAD 实例占用 19723–19743 中的一个端口。先启动的实例占 19723，第二个占 19724，依此类推。建议先开 AC29 再开 AC28，便于按端口顺序识别。
• 实例 ID 规则：MCP Server 启动时扫描全部端口，按 ac + 主版本号 + 序号 命名，例如 ac29-1、ac28-1。多实例并存时，所有工具调用须带 instance 参数指定目标（仅一个实例时可省略）。
• 客户端切换：在 Kimi / Trae 里调用 list_instances 可看到当前所有实例；调 project_summary 等工具时传 instance="ac29-1" 或 instance="ac28-1"。

客户端配置

MCP Server 用 stdio 通信，主流客户端配置如下。server.py 路径换成你的绝对路径（Windows 用正斜杠或双反斜杠）。

{
  "mcpServers": {
    "archicad": {
      "command": "python",
      "args": ["E:/works/Aidev/kbitai绝对安全/kbitai_com_cn/aitools/acmcp/archilinkai/server.py"]
    }
  }
}

{
  "mcpServers": {
    "archicad": {
      "command": "python",
      "args": ["E:/works/Aidev/kbitai绝对安全/kbitai_com_cn/aitools/acmcp/archilinkai/server.py"]
    }
  }
}

{
  "mcpServers": {
    "archicad": {
      "command": "python",
      "args": ["${workspaceFolder}/archilinkai/server.py"]
    }
  }
}

[mcp_servers.archicad]
command = "C:/Python314/python.exe"
args = ["E:/works/Aidev/kbitai绝对安全/kbitai_com_cn/aitools/acmcp/archilinkai/server.py"]

{
  "mcpServers": {
    "archicad": {
      "type": "stdio",
      "command": "C:/Python314/python.exe",
      "args": [
        "E:/works/Aidev/kbitai绝对安全/kbitai_com_cn/aitools/acmcp/archilinkai/server.py"
      ]
    }
  }
}

⚠️ 重要：本地 server 限制

本 server 在本机运行、连本机 ArchiCAD，因此：

• 本地客户端可用：Codex CLI、WorkBuddy 桌面版、TRAE Work/Trae 桌面版
• 纯云端环境连不到本机：TRAE Work 网页版、WorkBuddy 云端智能体/手机端（WorkBuddy 手机远程指挥时，需电脑桌面端开着做桥接）

沙箱白名单（Python site-packages）

Trae CN 自带沙箱会拦截对 C:\Python314\Lib\site-packages 的写操作，导致跑 pytest 时报 hit restricted，必须 dangerouslyDisableSandbox=true 才能跑。沙箱配置按会话 ID 管理，重启 IDE 后会回到默认白名单（只放行 docx 子目录）。

仓库根提供了一键脚本 enable_pypath_sandbox.ps1，每次重启 Trae CN 后双击执行即可把 C:\Python314\Lib\site-packages 重新注入当前会话的沙箱白名单。脚本是幂等的，已存在会跳过。

powershell -ExecutionPolicy Bypass -File .\enable_pypath_sandbox.ps1

若以后装了新 Python 版本（如 3.15），把脚本里 $PySitePackages 参数改成对应路径再跑：

powershell -ExecutionPolicy Bypass -File .\enable_pypath_sandbox.ps1 `
  -PySitePackages "C:\Python315\Lib\site-packages"

验证连接

1. 启动 ArchiCAD 28 / 29 并打开项目，确认 Tapir Add-On 已加载
2. 在客户端里让模型调用 list_instances，应返回两个实例
3. 调 project_summary 传 instance="ac29-1" 看元素总数
4. 已实测：Trae 桌面端自然语言调用成功（2 实例 / 12 墙）

测试与基准

跑测试（在项目根目录）

python -m pytest tests/unit/           # 单元测试，无需真机
python -m pytest tests/integration/    # 集成测试，需开 ArchiCAD
python -m pytest tests/compatibility/  # AC 版本兼容矩阵，需真机
python regression.py                   # 一键回归（单测+集成+兼容+基准），--json 存报告

无真机时集成/兼容性测试会自动跳过。当前结果（AC28+AC29 真机）：

性能基准

测常用只读命令多次调用的平均/最小/最大耗时（毫秒）：

python benchmark.py --instance ac29-1 --rounds 3

结果自动存为 benchmark_results.json 和 benchmark_results.md。真机实测：轻命令 <1–15ms，批量读取（全部元素/属性名/分类）50–70ms，均在百毫秒级，适合对话式调用。

项目结构

archilinkai/
├── server.py              # FastMCP 入口：异常包装 + 四层工具注册
├── read_tools.py          # P0 只读工具注册（35 个，从 server.py 拆出）
├── write_tools.py         # P1 安全写入工具注册（16 个，从 server.py 拆出）
├── modify_tools.py        # 构件修改工具注册（2 个，V0.4）
├── delete_tools.py        # 构件删除工具注册（2 个，V0.7）
├── plan_tools.py          # 计划辅助工具注册（1 个，V0.10）
├── diagnostic_tools.py    # P2 诊断工具注册（4 个，从 server.py 拆出）
├── instance_manager.py    # ArchiCAD 实例发现/连接/重连/健康检查
├── tapir_adapter.py       # Tapir 命令统一封装
├── channel_base.py        # 建模通道抽象基类（可插拔通道）
├── tapir_channel.py       # 通道实现：Tapir（15类创建 + 7类修改 + 删除 + 存在性查询）
├── model_plan.py          # 建模计划：数据结构 + 类型注册表（15 类构件）
├── plan_values.py         # 计划基础数值/坐标校验（含 3D 点、3D 洞）
├── plan_framing.py        # 计划校验：墙/柱/梁/板
├── plan_openings.py       # 计划校验：门/窗
├── plan_special.py        # 计划校验：楼梯/屋顶/变形体/网面/洞口/区域/机电管线
├── modify_plan.py         # 构件修改计划：数据结构 + 校验（V0.4）
├── delete_plan.py         # 构件删除计划：GUID 列表校验（V0.7）
├── plan_preview.py        # 建模计划预览（人能看懂的明细）
├── create_service.py      # 建模计划调度：能力闸门/创建/验证
├── modify_service.py      # 修改调度：读当前值/修改/逐字段验证（V0.4）
├── delete_service.py      # 删除调度：预检/删除/details 读回确认（V0.7）
├── query_engine.py        # BIM 条件查询引擎（含分页）
├── property_service.py    # Property 读取/写入与类型校验
├── aggregate_service.py   # 工程量分组汇总（V0.16）
├── code_table.py          # GB 50500 构件类型→清单编码映射（V0.26）
├── report_service.py      # 工程量清单报表排版（V0.26）
├── formula_eval.py        # 算量规则公式安全求值（V0.25）
├── geometry_service.py    # 几何规整：长度/起止点/高程/包围盒
├── benchmark.py           # 性能基准：命令耗时统计（avg/min/max）
├── regression.py          # 一键回归：单测+集成+兼容+基准，汇总报告
├── gdl_service.py         # GDL 参数读写（从 server.py 拆出）
├── operation_service.py   # Preview / Confirm / Execute / Verify 四阶段
├── audit_log.py           # 操作日志（Operation ID）
├── schemas.py             # 输入/输出数据结构
├── errors.py              # 统一异常与错误码
├── requirements.txt
├── debug_log.md           # 变更日志（已满，续记见下）
├── debug_log_2.md         # 变更日志续篇（已满，2026-09-24 起）
├── debug_log_3.md         # 变更日志续篇三（2026-09-27 起）
├── benchmark_results.md   # 性能基准结果（跑 benchmark 自动生成）
├── benchmark_results.json
└── tests/
    ├── unit/              # 单元测试
    ├── integration/       # 集成测试（需真机）
    └── compatibility/     # AC26–29 兼容性测试矩阵

工具一览

P0 只读工具（35 个）

P1 安全写入工具（16 个）

构件修改 / 删除 / 计划辅助（5 个）

P2 诊断运维（4 个）

工具总数：66 个

已支持建模构件（15 类）

墙 · 柱 · 梁 · 板 · 门 · 窗 · 楼梯 · 屋顶 · 变形体 · 对象（家具）· 灯具 · 网面 · 独立洞口 · 房间区域 · 机电管线（风管/水管/桥架）

只读可算量构件（Tapir 不支持创建）

幕墙（CurtainWall）· 栏杆（Railing）· 壳体（Shell）· 天窗（Skylight）——可查询、可取工程量、可分组汇总，但不能通过建模计划创建（Tapir 未实现对应 Create 命令）。

图片识别 → 建模计划（P2 工作流）

识图由 LLM 客户端完成（把平面图照片/截图发给 Claude/Kimi 等视觉模型），server 负责消化计划。标准流程：

1. 标定比例：先问用户图上一个已知尺寸（如"这面墙 6 米"），建立像素→米换算；无已知尺寸时先用假设比例并在预览时声明
2. 定原点：选平面图左下角或某个房间角点为 (0,0)，所有坐标转成相对原点的米制坐标
3. 按序提取：先墙（起止点），再柱梁板，再门窗（wall 填墙序号），最后楼梯/屋顶/变形体。门窗必须落在某面墙上
4. lint 自检：调 lint_model_plan 离线校验，按报错修正，直到 ok=true。这步不连 ArchiCAD，可反复迭代
5. 预览确认：调 preview_model_plan 给用户看明细，用户确认后调 create_from_plan(confirm=true) 执行

常见坑：坐标别用像素直接填（必须是米）；墙起止点顺序影响门窗 offset 方向；屋顶/板建在非当前楼层会假成功（level 填当前楼层标高）。

安全设计

• 写操作统一四阶段：Preview → Confirm → Execute → Verify
• 写入默认 confirm=false，需明确 confirm=true 才执行
• 项目身份强校验：discover/refresh 时记录项目文件路径基线；写入前重新核对路径 + 目标元素 GUID 是否仍存在，项目被关闭/另存为/切换时拦截（错误码 PROJECT_IDENTITY_CHANGED），调 refresh_instances 建立新基线后才能继续
• 写入走 archicad 原生 API（SetPropertyValuesOfElements，内部已包 ACAPI_CallUndoableCommand，Ctrl+Z 可撤销）；读操作走 Tapir 通道（Tapir 写命令的参数 schema 与原生不一致，实测会拒绝，见 debug_log.md）
• 构件修改（V0.4）：项目身份与构件存在性分开校验，构件已删除时报直白错误；改后用 GetDetailsOfElements 逐字段读回比对（容差 1 厘米）
• 所有写操作生成唯一 Operation ID 并记录日志

版本历史

完整版本历史已迁移至 CHANGELOG.md。里程碑摘要：

实机验证进度（2026-09-23）

以下全部在真机（AC29 build 5003 + AC28 build 6003 双实例）验证通过：

MCP 传输层验证方式：_probe_mcp_client.py（mcp SDK 客户端，stdio 启动 server.py 子进程，走 initialize → list_tools → call_tool 完整协议）。

剩余可选项：把本 server 接入真实 LLM 客户端（Claude Desktop / Kimi / Trae，配置见「客户端配置」节）。

参考文档