Aspicio

Aspicio 是一个开源（MIT）、TypeScript 优先的绘图引擎：采用一套不依赖框架的 parse → tessellate 流程，可在浏览器、Node 和无服务器运行时中运行。它能读取 DXF 和 PDF 中的矢量内容——这类 PDF 包含图稿和刀模线，而非扫描图。人们可以通过交互式 WebGL 查看器查看 CAD 图纸；AI Agent 则能获取同一文件的结构化 JSON 信息和渲染后的 PNG。所有入口——浏览器查看器、Web 组件及其 React、Vue 和 Svelte 绑定、无头渲染器、HTTP API 和 MCP 服务——都是同一引擎上的轻量适配器，因此无论在哪里，图纸都同样易于读取。

DXF / PDF bytes ─parse─▶ DrawingDocument ─tessellate─▶ Tessellation ──┬─▶ WebGL renderer (viewer)
                        (normalized model)   (batched geometry)       ├─▶ SVG string (export / API / MCP)
                                                                      └─▶ DrawingSummary (describe)

构建方式：docs/architecture.md · 行为规格：docs/product-specs/

嵌入

一次嵌入，适配各种场景——下面每种方式都会渲染相同的 Web 组件，因此无论选择哪种，结果都完全一致。

Web 组件 — 纯 HTML，适用于任何框架

只需一个标签，即可获得图层面板和交互式预览；无需绑定：

<script type="module">
  import "@aspicio/elements";
  import "@aspicio/elements/formats/dxf";
</script>

<aspicio-embed src-url="/drawing.dxf" style="height: 480px"></aspicio-embed>

通过导入来选择格式：软件包提供组件，formats/* 入口提供解析器。这样，DXF 应用就无需打包其他所有格式的代码——下面的每种方式也都采用相同做法。

React

通过 @aspicio/react，使用惯用的属性和一个可访问完整查看器的 ref，实现相同的嵌入方式：

import { AspicioEmbed } from "@aspicio/react";
import "@aspicio/react/formats/dxf";

<AspicioEmbed src={file} style={{ height: 480 }} />;

Vue

通过 @aspicio/vue，使用带类型的属性和事件，并自动解包载荷：

<script setup>
import { AspicioEmbed } from "@aspicio/vue";
import "@aspicio/vue/formats/dxf";
</script>

<template>
  <AspicioEmbed src-url="/drawing.dxf" style="height: 480px" />
</template>

Svelte

通过 @aspicio/svelte，以原生 Svelte 5 源码形式使用相同组件，并提供带类型的回调属性：

<script>
  import { AspicioEmbed } from "@aspicio/svelte";
  import "@aspicio/svelte/formats/dxf";
</script>

<AspicioEmbed srcUrl="/drawing.dxf" style="height: 480px" />

原生 TypeScript

跳过现成的 UI，直接通过 @aspicio/core 驱动查看器——界面由你自定义：

import { DrawingViewer } from "@aspicio/core";
import { dxfParser } from "@aspicio/core/dxf";

const viewer = new DrawingViewer(document.querySelector("#preview")!, {
  parsers: [dxfParser],
});
await viewer.load(file); // File | Blob | ArrayBuffer | DXF text (ASCII or binary)

无头 — Node 和无服务器

无需浏览器即可解析、描述和渲染（用于服务端预览、缩略图、流水线）：

import {
  describeDrawing,
  parseWith,
  tessellate,
  tessellateSpace,
  tessellationToSvg,
} from "@aspicio/core";
import { dxfParser } from "@aspicio/core/dxf";

const doc = await parseWith([dxfParser], bytes); // ASCII or binary DXF
const summary = describeDrawing(doc); // units, bounds, layers, texts, spaces…
const svg = tessellationToSvg(tessellate(doc)); // model space (a PDF's page 1)

// Multi-page PDFs and multi-sheet DXFs: describe covers all of them, and
// either verb can be scoped to one.
const page3 = describeDrawing(doc, { space: "Page 3" });
const sheet = tessellationToSvg(tessellateSpace(doc, "Layout1"));

你将获得：WebGL 渲染，每个图层批量合并为一次绘制调用（大型图纸仍可交互）；广泛的实体覆盖范围（直线、圆弧、圆、椭圆、带凸度的多段线、样条曲线、TEXT/MTEXT、DIMENSION、SOLID/HATCH 填充、嵌套 INSERT 块——任何不支持的内容都会计数并报告，绝不会导致失败）；图层列表及其_实际绘制_的颜色（包括每个实体的颜色覆盖，而不仅仅是图层表中的颜色）；支持对象捕捉的测量、实体拾取、图纸空间布局、SVG/PNG 导出，以及一流的触控支持。不在支持范围内：编辑和 3D。

交给 Agent

同一引擎同时支持 MCP 和 HTTP，因此 Agent 可以_读取_图纸，而不是靠猜测：

• describe_dxf — 单位、边界、大小、带有效颜色的图层、实体计数，以及图纸中的文本内容。Agent 可以直接读取标题栏或尺寸值——无需 OCR，也无需经过视觉识别。
• render_dxf — 模型可以查看的图纸 PNG。
• view_dxf（托管服务）— 通过开放的 MCP Apps 扩展，为对话中的_用户_提供交互式聊天内查看器：平移、缩放、切换图层、全屏，以及跟随宿主切换浅色/深色主题。该组件仅限查看工具调用所提供的图纸，不会发出网络请求；不支持 MCP Apps 的宿主仍会获得结构化信息。

接入方式	本地文件	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 提供自描述文档

URL 获取受到防护（阻止访问私有网络、限制大小、验证重定向、设置超时）。stdio 服务会在进程内读取本地文件，绝不会将 DXF 上传到任何 Aspicio 服务——不过，与任何工具结果一样，你的 MCP 客户端会将返回的摘要或图像传给其模型提供商。详情请见： 隐私政策 · 条款。

当前已提供 · 发展方向

以上所有内容均已发布并上线：查看器和演示、核心库、Web 组件、React、Vue 和 Svelte 包、无头描述/渲染、stdio 和托管 MCP、聊天内 MCP Apps 查看器、带 OpenAPI 的 HTTP API，以及 Claude Code 和 Codex 插件打包。

发展方向（意向而非承诺——请参阅 议题）：MCP 注册表收录、结构化实体查询和聚焦渲染，以及让远程接入方式能够处理本地文件的上传流程。

软件包

软件包	描述
@aspicio/core	查看器库：解析、镶嵌、渲染、相机、输入
@aspicio/elements	Web 组件：<aspicio-embed>、<aspicio-preview>、<aspicio-layer-panel> — 纯 HTML、Svelte、任意框架
@aspicio/react	React 绑定：<AspicioEmbed>、<AspicioPreview>、<AspicioLayerPanel>
@aspicio/vue	Vue 3 绑定：相同的三个组件，带有类型化 props 和 emits
@aspicio/svelte	Svelte 5 绑定：相同的三个组件，以原始 .svelte 源码提供
@aspicio/mcp	面向 AI Agent 的 MCP 服务：describe_dxf + render_dxf
@aspicio/api	DXF HTTP API 服务（私有）：/describe、/render、/mcp
@aspicio/widget	MCP Apps 聊天内查看器小组件（私有），由 api 服务提供
@aspicio/demo	独立演示应用（私有）— 同时也是参考集成

查看器软件包的协作方式：所有框架路径都会汇入相同的 Lit Web 组件 — 嵌入式 UI 的单一实现 — 并构建在不依赖框架的核心之上。React、Vue 和 Svelte 使用符合各自惯用方式的轻量封装，并提供 props；纯 HTML 则直接使用这些元素。

flowchart TD
    REACTAPP["React app"]
    HTMLAPP["Plain HTML / vanilla JS app"]
    VUEAPP["Vue app"]
    SVELTEAPP["Svelte app"]

    REACT["<b>@aspicio/react</b><br/>&lt;AspicioEmbed&gt; · &lt;AspicioPreview&gt; · &lt;AspicioLayerPanel&gt;<br/><i>thin @lit/react veneer, API-stable</i>"]
    VUE["<b>@aspicio/vue</b><br/>&lt;AspicioEmbed&gt; · &lt;AspicioPreview&gt; · &lt;AspicioLayerPanel&gt;<br/><i>thin Vue 3 veneer, typed emits</i>"]
    SVELTE["<b>@aspicio/svelte</b><br/>&lt;AspicioEmbed&gt; · &lt;AspicioPreview&gt; · &lt;AspicioLayerPanel&gt;<br/><i>raw Svelte 5 source, compiled by your bundler</i>"]
    ELEMENTS["<b>@aspicio/elements</b><br/>&lt;aspicio-embed&gt; · &lt;aspicio-preview&gt; · &lt;aspicio-layer-panel&gt;<br/><i>Lit web components — the one embed-UI implementation</i>"]
    CORE["<b>@aspicio/core</b><br/>parse → tessellate → render<br/><i>camera · input · picking · SVG/PNG export · headless describe</i>"]

    REACTAPP -->|"idiomatic props, ref → DrawingViewer"| REACT
    REACT -->|"wraps"| ELEMENTS
    HTMLAPP -->|"attributes + DOM events"| ELEMENTS
    VUEAPP -->|"idiomatic props + emits"| VUE
    VUE -->|"wraps"| ELEMENTS
    SVELTEAPP -->|"typed callback props"| SVELTE
    SVELTE -->|"wraps"| ELEMENTS
    ELEMENTS -->|"drives"| CORE
    HTMLAPP -.->|"or hand-rolled UI on the DrawingViewer API"| 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

开发

工具链：基于 bun 的 Vite+（vp）。

vp install       # install dependencies
vp run dev       # start the demo app
vp run ready     # check + test + build everything (the repo gate)

测试、CI/部署、发布和贡献指南： CONTRIBUTING.md。

---

Aspicio 由 FrontSail AI 开发和维护。