内容
<div align="center">
<img src="apps/demo/public/favicon.svg" width="72" height="72" alt="Aspicio logo" />
<h1>Aspicio</h1>
<p><strong>DXF理解，为人、应用程序和AI代理提供服务。</strong></p>
<p><em>Aspicio</em>（拉丁语：“我观察”）</p>
<p>
<a href="https://github.com/frontsail-ai/aspicio/actions/workflows/ci.yml"><img src="https://github.com/frontsail-ai/aspicio/actions/workflows/ci.yml/badge.svg" alt="CI" /></a>
<a href="https://www.npmjs.com/package/@aspicio/core"><img src="https://img.shields.io/npm/v/%40aspicio%2Fcore?label=%40aspicio%2Fcore" alt="npm: @aspicio/core" /></a>
<a href="https://www.npmjs.com/package/@aspicio/elements"><img src="https://img.shields.io/npm/v/%40aspicio%2Felements?label=%40aspicio%2Felements" alt="npm: @aspicio/elements" /></a>
<a href="https://www.npmjs.com/package/@aspicio/react"><img src="https://img.shields.io/npm/v/%40aspicio%2Freact?label=%40aspicio%2Freact" alt="npm: @aspicio/react" /></a>
<a href="https://www.npmjs.com/package/@aspicio/vue"><img src="https://img.shields.io/npm/v/%40aspicio%2Fvue?label=%40aspicio%2Fvue" alt="npm: @aspicio/vue" /></a>
<a href="https://www.npmjs.com/package/@aspicio/svelte"><img src="https://img.shields.io/npm/v/%40aspicio%2Fsvelte?label=%40aspicio%2Fsvelte" alt="npm: @aspicio/svelte" /></a>
<a href="https://www.npmjs.com/package/@aspicio/mcp"><img src="https://img.shields.io/npm/v/%40aspicio%2Fmcp?label=%40aspicio%2Fmcp" alt="npm: @aspicio/mcp" /></a>
<a href="LICENSE"><img src="https://img.shields.io/badge/license-MIT-blue.svg" alt="License: MIT" /></a>
</p>
<p><a href="https://aspicio.frontsail.app"><strong>▶ 在线演示</strong></a></p>
</div>
Aspicio 是一个开源（MIT）的、TypeScript-first 的 DXF 引擎：一个框架无关的 `parse → tessellate` 管道，可以在浏览器、Node 和 Cloudflare Workers 中运行。一个人可以获得一个交互式的 WebGL 查看器，用于查看 CAD 绘图；AI 代理可以获得结构化的 JSON 事实和相同文件的渲染 PNG。每种表面 - 浏览器查看器、Web 组件及其 React、Vue 和 Svelte 绑定、头文件渲染器、HTTP API 和 MCP 服务器 - 都是同一个引擎上的一个薄适配器，因此绘图在任何地方都同样可读。
```
DXF 字节 ──parse──▶ DxfDocument ──tessellate──▶ Tessellation ──┬─▶ WebGL 渲染器（查看器）
（标准化模型） （批处理几何体） ├─▶ SVG 字符串（导出 / API / MCP）
└─▶ DrawingSummary（描述）
```
构建方式：[docs/architecture.md](docs/architecture.md) · 行为规范：[docs/product-specs/](docs/product-specs/README.md)
<img src="docs/sample-demo.png" alt="Aspicio 查看一个示例楼层计划 DXF - 层面板、着色几何体、文本和尺寸" />
## 嵌入
一个嵌入，所有风格 - 并且下面的每个路径都渲染相同的 Web 组件，因此无论您选择哪一个，结果都是像素相同的。
### Web 组件 - 普通 HTML，任意框架
一个标签为您提供层面板和交互式预览；不需要绑定：
```html
<script type="module">
import "@aspicio/elements";
</script>
<aspicio-embed src-url="/drawing.dxf" style="height: 480px"></aspicio-embed>
```
### React
具有惯用道具和 `ref` 暴露的完整查看器的相同嵌入，通过 [`@aspicio/react`](packages/react)：
```tsx
import { DxfEmbed } from "@aspicio/react";
<DxfEmbed src={file} style={{ height: 480 }} />;
```
### Vue
具有类型化道具和发出的数据包的相同嵌入，通过 [`@aspicio/vue`](packages/vue)：
```vue
<script setup>
import { DxfEmbed } from "@aspicio/vue";
</script>
<template>
<DxfEmbed src-url="/drawing.dxf" style="height: 480px" />
</template>
```
### Svelte
具有类型化回调道具的相同组件，作为原始 Svelte 5 源代码，通过 [`@aspicio/svelte`](packages/svelte)：
```svelte
<script>
import { DxfEmbed } from "@aspicio/svelte";
</script>
<DxfEmbed srcUrl="/drawing.dxf" style="height: 480px" />
```
### 纯 TypeScript
跳过现成的 UI，直接从 [`@aspicio/core`](packages/core) 驱动查看器 - 自带 Chrome：
```ts
import { DxfViewer } from "@aspicio/core";
const viewer = new DxfViewer(document.querySelector("#preview")!);
await viewer.load(file); // 文件 | Blob | ArrayBuffer | DXF 文本（ASCII 或二进制）
```
### 无头 - Node 和 Workers
在没有浏览器的情况下解析、描述和渲染（服务器端预览、缩略图、管道）：
```ts
import { parseDxfBytes, tessellate, describeDrawing, tessellationToSvg } from "@aspicio/core";
const doc = parseDxfBytes(bytes); // ASCII 或二进制 DXF
const drawing = tessellate(doc);
const summary = describeDrawing(doc, drawing); // 单位、边界、层、文本...
const svg = tessellationToSvg(drawing);
```
您获得的是：每层批处理到一个绘制调用的大型绘图保持交互性，广泛的实体覆盖（线、弧、圆、椭圆、多线段与膨胀、样条曲线、TEXT/MTEXT、DIMENSION、SOLID/HATCH 填充、嵌套 INSERT 块 - 任何不支持的都被计数和报告，从不致命），一个具有实际绘制的颜色的层列表（包括实体重写，不只是层表），用对象捕捉测量，实体拾取，纸空间布局，SVG/PNG 导出和一流的触摸。超出范围：编辑和 3D。
## 交给代理
同一个引擎讲 MCP 和 HTTP，因此代理可以读取绘图而不是猜测它：
- **`describe_dxf`** - 单位、边界、大小、具有有效颜色的层、实体计数和绘图的文本内容。代理直接读取标题块或尺寸值 - 无需 OCR，无需视觉往返。
- **`render_dxf`** - 模型可以查看的绘图 PNG。
- **`view_dxf`**（托管服务器）- 聊天中的交互式查看器，供会话中的人员使用，通过开放的 [MCP Apps 扩展](https://modelcontextprotocol.io/seps/1865-mcp-apps-interactive-user-interfaces-for-mcp)：平移、缩放、层切换、全屏、主机主题切换。窗口小部件锁定到绘图工具调用的绘图，不进行网络请求；不支持 MCP Apps 的主机仍然获得结构化事实。
<img src="docs/demo-widget.gif" alt="聊天查看器加载 1.1 MB 楼层计划 DXF，切换尺寸和文本层，并展开到全屏" />
| 表面 | 本地文件 | URL | 内联 DXF |
| -------------------------------------------- | ----------- | ---- | ---------- |
| stdio MCP - `npx -y @aspicio/mcp` | | | |
| 主机 MCP - `aspicio-api.frontsail.app/mcp` | - | | |
| HTTP API - `/describe`, `/render` | POST 正文 | | |
连接：
- **Claude Code** - 一个步骤安装 MCP 服务器和捆绑的技能（`aspicio-inspect-dxf`，`aspicio-embed`）：`/plugin marketplace add frontsail-ai/aspicio` 然后 `/plugin install aspicio@aspicio`
- **Codex** - 同一个存储库作为 Codex 市场：`codex plugin marketplace add https://github.com/frontsail-ai/aspicio`，`codex plugin add aspicio@aspicio`，然后 `codex mcp add aspicio -- npx -y @aspicio/mcp`
- **任何启动 stdio MCP 服务器的客户端** - 注册 `npx -y @aspicio/mcp`
- **任何支持远程 MCP（Streamable HTTP）的客户端** - 指向 `https://aspicio-api.frontsail.app/mcp`（无需安装；讲 MCP，而不是浏览器页面）
- **纯 HTTP** - `GET /describe?src=<dxf-url>`，`GET /render?src=<dxf-url>&format=png|svg`；API 自描述于 [`/openapi.json`](https://aspicio-api.frontsail.app/openapi.json)
URL 获取是受保护的（私有网络阻止、大小上限、重定向验证、超时）。stdio 服务器在进程中读取本地文件，从不将 DXF 上传到任何 Aspicio 服务 - 但是，与任何工具结果一样，您的 MCP 客户端将返回的摘要或图像传递给其模型提供商。完整详细信息：[隐私政策](https://aspicio.frontsail.app/privacy/) · [条款](https://aspicio.frontsail.app/terms/)。
## 今日可用 · 方向
上述所有内容都已发布并上线：查看器 + 演示、核心、Web 组件、React、Vue 和 Svelte 包、无头描述/渲染、stdio 和托管 MCP、聊天查看器、具有 OpenAPI 的 HTTP API 以及用于 Claude Code 和 Codex 的插件打包。
方向（意图，不是承诺 - 参见 [问题](https://github.com/frontsail-ai/aspicio/issues)）：MCP 注册列表、结构化实体查询和聚焦渲染，以及上传流程，以便远程表面可以处理本地文件。
## 包
| 包 | 描述 |
| ---------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| [`@aspicio/core`](packages/core) | 查看器库：解析、曲面细分、渲染、相机、输入 |
| [`@aspicio/elements`](packages/elements) | Web 组件：`<aspicio-embed>`、`<aspicio-preview>`、`<aspicio-layer-panel>` - 普通 HTML、Svelte、任意框架 |
| [`@aspicio/react`](packages/react) | React 绑定：`<DxfEmbed>`、`<DxfPreview>`、`<DxfLayerPanel>` |
| [`@aspicio/vue`](packages/vue) | Vue 3 绑定：相同的三个组件，具有类型化道具和发射器 |
| [`@aspicio/svelte`](packages/svelte) | Svelte 5 绑定：相同的三个组件作为原始 `.svelte` 源代码 |
| [`@aspicio/mcp`](packages/mcp) | 用于 AI 代理的 MCP 服务器：`describe_dxf` + `render_dxf` |
| [`@aspicio/api`](apps/api) | DXF HTTP API 服务器（私有）：`/describe`，`/render`，`/mcp` |
| [`@aspicio/widget`](apps/widget) | MCP Apps 聊天查看器小部件（私有），由 API 服务器提供 |
| [`@aspicio/demo`](apps/demo) | 独立演示应用（私有）- 也是参考集成 |
查看器包的集成方式：每个框架路径都流入同一个 Lit Web 组件 - 嵌入式 UI 的一个实现 - 它位于框架无关的核心。React、Vue 和 Svelte 获得具有惯用道具的薄层；普通 HTML 直接使用元素。
```mermaid
flowchart TD
REACTAPP["React 应用"]
HTMLAPP["纯 HTML / 普通 JS 应用"]
VUEAPP["Vue 应用"]
SVELTEAPP["Svelte 应用"]
REACT["<b>@aspicio/react</b><br/><DxfEmbed> · <DxfPreview> · <DxfLayerPanel><br/><i>薄 @lit/react 层，API 稳定</i>"]
VUE["<b>@aspicio/vue</b><br/><DxfEmbed> · <DxfPreview> · <DxfLayerPanel><br/><i>薄 Vue 3 层，类型化发射器</i>"]
SVELTE["<b>@aspicio/svelte</b><br/><DxfEmbed> · <DxfPreview> · <DxfLayerPanel><br/><i>原始 Svelte 5 源代码，由您的打包器编译</i>"]
ELEMENTS["<b>@aspicio/elements</b><br/><aspicio-embed> · <aspicio-preview> · <aspicio-layer-panel><br/><i>Lit Web 组件 - 嵌入式 UI 实现</i>"]
CORE["<b>@aspicio/core</b><br/>解析 → 曲面细分 → 渲染<br/><i>相机 · 输入 · 拾取 · SVG/PNG 导出 · 无头描述</i>"]
REACTAPP -->|"惯用道具，ref → DxfViewer"| REACT
REACT -->|"包装"| ELEMENTS
HTMLAPP -->|"属性 + DOM 事件"| ELEMENTS
VUEAPP -->|"惯用道具 + 发出"| VUE
VUE -->|"包装"| ELEMENTS
SVELTEAPP -->|"类型化回调道具"| SVELTE
SVELTE -->|"包装"| ELEMENTS
ELEMENTS -->|"驱动"| CORE
HTMLAPP -.->|"或在 DxfViewer API 上滚动自己的 UI"| CORE
classDef pkg fill:#191c22,stroke:#4c8dff,color:#e7e3da
classDef app fill:#1f232b,stroke:#3a3f4a,color:#9aa0ab
class REACT,VUE,SVELTE,ELEMENTS,CORE pkg
class REACTAPP,HTMLAPP,VUEAPP,SVELTEAPP app
```
## 开发
工具链：[Vite+](https://viteplus.dev)（`vp`）建立在 bun 之上。
```bash
vp install # 安装依赖
vp run dev # 启动演示应用
vp run ready # 检查 + 测试 + 构建所有内容（存储库门控）
```
测试、CI/部署、发布和贡献指南：[CONTRIBUTING.md](CONTRIBUTING.md)。
---
Aspicio 由 [FrontSail AI](https://frontsail.ai/) 开发和维护。
