Aira Interface 原生接口概览

Aira Interface 原生接口概览

最高原则：为 AI 设计。核心建模能力必须通过原生 Aira Interface 可发现、可查询、可执行、可诊断和可恢复；不能依赖鼠标操作、阅读实现源码、预装 Aira Skills 或猜测内部索引才能使用。

Aira 是一套为 AI 与人类工程师协同设计而生的本地优先（Local-First）工业 CAD 平台。在 Aira 的体系中，AI Agent 不是通过模拟屏幕点击或操作人类 GUI 来完成建模，而是直接与统一的原生建模接口通信。

---

一、 接口架构分层

Aira 原生接口由四个严密协作的层级构成：

graph TD
  Agent[AI Agent / LLM 规划器] -->|AI SDK Tool Call| CadTools["@aira/cad-tools 建模契约层"]
  CadTools -->|JSON Schema / AMIR 协议| Contracts["@aira/contracts 语义契约层"]
  Contracts -->|事务原子提交与求解| Core["@aira/core Rust/WASM 确定性状态机"]
  Core -->|参数化 B-Rep 与拓扑算子| Kernel["@aira/geometry-kernel 深度自研几何内核"]

1. 建模工具层 (@aira/cad-tools)：

   • 使用 Vercel AI SDK 统一声明参数契约、工具描述和执行入口。
   • 内置模型与公开 Interface 共享一份权威能力定义，避免多套声明出现漂移。

2. 语义契约层 (@aira/contracts)：

   • 托管 AMIR（Aira Model Intermediate Representation）的规范与 TypeScript 类型。
   • 负责参数化特征图（Feature Graph）、几何关系编译、版本追踪与语义引用（SemanticRef）。

3. 确定性状态机 (crates/aira-core)：

   • Rust / WASM 实现的高性能事务核心。
   • 保证原子提交（Atomic Commit）、历史操作回退与数据确定性。

4. 几何内核底座 (@aira/geometry-kernel)：

   • Aira 自主维护的深度二次开发几何内核。
   • 封装 OCCT 原生 B-Rep 构造器、PlaneGCS 2D 草图约束求解与 CasADi 连续优化求解器。

---

二、 核心接口分类

接口分类	对应模块	核心能力描述
AI 原生工具集	@aira/cad-tools	面向 Agent 的结构化读、查、编、验、阶段暂存工具
AMIR 数据契约	@aira/contracts	特征定义、草图图元、实体关系与多体装配协议
几何拓扑操作	@aira/geometry-kernel	基础 Shape、布尔求交、倒角、抽壳、拉伸、旋转
服务与网关	apps/server	遵循有界步循环（Bounded-Step Loop）的 /api/step 调用契约

---

三、 设计与协作保证

1. 单一事实原则 (Single Source of Truth)： 内置模型与外部人类操作共享同一套 Interface 与事务管线，UI 只是同一能力的交互投影。
2. 原子提交与幂等重放： 所有建模调用必须产生确定性的数据证据（Evidence）与 Revision 增量。在出现几何拓扑失败时，能安全诊断并无缝恢复到上一稳定状态。