Battenmark

面向 AI 智能体与软件的开源、后端中立 CAD 基础设施。

Battenmark 提供一套有类型、后端中立的接口，可在可互换的 CAD 后端之间创建、编辑、检查、验证和导出权威 CAD 几何体。调用方只请求 create_hole，而绝不直接调用 PartDesign::Hole。模型不由任何传输层持有，而由唯一权威服务统一持有。

ChatGPT / Claude / Gemini / Grok / Codex / local models / IDE agents / custom apps
                                   │
                    MCP / HTTP / Python / CLI
                                   │
                                   ▼
                         Battenmark Core
                                   │
                    typed CAD operations / CAD IR
                                   │
                        Backend Registry
                                   │
             ┌─────────────────────┼──────────────────────┐
             ▼                     ▼                      ▼
          FreeCAD                JSCAD              future adapters
     authoritative B-rep        preview        build123d/CadQuery/etc.

• FreeCAD / OpenCascade — 权威 B-rep 内核（无头 JSON-lines worker）

• JSCAD — 进程内预览/包络后端（并非事实来源）

快速上手

前置要求：Node.js ≥ 20 和 npm。FreeCAD 对核心服务是可选的，仅在权威 B-rep 后端中必需。

npm install
npx tsc --noEmit   # type check
npm test           # fast kernel-free suites (parametric, selectors, registry)

FreeCAD 后端

sh scripts/bootstrap-macos.sh      # macOS: discovers /Applications/FreeCAD.app
sh scripts/install-freecad.sh      # Linux: installs headless 1.0.2 AppImage (no FUSE)
npm run test:freecad               # proves the real worker end-to-end

发现顺序：$AGENTCAD_FREECAD_CMD → macOS FreeCAD.app 应用包 → Homebrew → 解压后的 Linux AppImage → PATH。参见 docs/MACOS.md 和 docs/LINUX.md。

传输方式

Python 客户端示例：

from agentcad import AgentCad

c = AgentCad(base_url="http://127.0.0.1:8787", token="secret-token")
pid = c.project_create("demo")["project_id"]
c.create_box(pid, 80, 50, 12)
print(c.rebuild(pid)["data"]["volume_mm3"])   # 48000

Related MCP server: freecad-tool-server

黄金冒烟测试模型

发布时验证的标准冒烟测试是 80 × 50 × 12 mm 的方块 = 48,000 mm³，已通过 JSCAD、FreeCAD、HTTP、CLI、MCP 和 Python 客户端验证（test:transport-parity）。请勿随意更改此测试夹具。

能力

• 后端中立的类型化 CAD 操作，带有显式 schema（agentcad_schema_version: 2）

• FreeCAD / OpenCascade 权威 B-rep；JSCAD 预览

• 标量参数表达式与依赖求值

• 语义化面 / 边选择器（top_perimeter 等），可在编辑后重新解析

• 持久化几何引用（gref），并带有明确的丢失 / 歧义错误

• 通孔 / 盲孔 / 沉孔 / 锥形沉孔

• 圆角与倒角 · 线性阵列与矩形阵列

• STEP / FCStd / STL 交换 · 四视图 PNG 预览

• 动态后端注册表，支持按后端进行能力发现

• 单一串行化的 FreeCAD worker，支持 kill / restart 恢复

平台状态

已知限制

这是 pre-1.0 的 alpha 阶段软件，API 可能发生变更。

• 尚无装配体、配合或装夹约束

• 暂无圆弧阵列

• 螺纹只是装饰性元数据，并非螺旋实体

• 导入的 STEP 仅作为几何数据导入——并非自动参数化重建

• 原生 FCStd 文档会保留历史 PartDesign 特征形状；Battenmark 度量最终的 Body Tip（将历史实体相加会产生重复）

• 单一串行化的 FreeCAD worker（无连接池）

• 预览渲染基于 JSCAD，而非 OCC 隐藏线算法

• 完整的拓扑命名问题尚未解决；持久化的 gref 可缓解这一困难

完整列表：docs/LIMITATIONS.md。

文档

兼容性标识符

对外品牌是 Battenmark。历史工程标识符有意保留，并作为兼容性表面而非第二品牌：AgentCadService、agentcad_schema_version、AGENTCAD_* 环境变量、agentcad / agentcad-mcp 可执行文件。内部服务版本 0.5.6 特意不同于发布 tag；详见 docs/VERSIONING.md。

贡献与安全

参见 CONTRIBUTING.md 和 SECURITY.md。 行为准则：CODE_OF_CONDUCT.md。

许可证

本仓库采用 Apache-2.0。FreeCAD / OpenCascade 以单独 LGPL 进程的方式被调用（worker 脚本在 FreeCADCmd 内部运行）。参见 LICENSE、NOTICE 和 THIRD_PARTY_NOTICES.md。