Semiotic

一个专为 AI 辅助开发和流式数据设计的 React 数据可视化库。

从一个小型图表组件开始。根据任务需要，再添加网络图、流式数据和协调视图。结构化架构、诊断信息和渲染证据可帮助编码助手实现、检查和修复图表配置。

完成一个完整任务：检查类别总计、维护实时图表，或修正已发布的图表。 源任务包注明了其构建和证据范围；源文件可用并不能证明已安装或已部署的版本与之相符。

3.13.2 新特性

3.13.2 修复了嵌套主题继承和属性更新问题，在选择、过期状态和动画期间保留标记的不透明度，并减少了工具提示的测量开销。网络图改进了边的拾取和相机更新，并在布局提交期间提供相机句柄。发布构件准备还支持重命名后的检出目录，并可重试失败的构建。

完整的修复和新增内容请参阅更新日志。

为什么选择 Semiotic

Semiotic 是一个面向 React 的数据可视化库，将广泛的图表支持与 AI 工具相结合。它支持网络图、流式数据、统计分布和协调视图，并为每项任务提供架构、示例和诊断信息，便于实现和检查。请先检查项目现有的依赖项：对于小型改动，扩展当前的图表库可能是最佳选择。

为 AI 辅助开发而打造

Semiotic 提供一套用于生成、检查和修复图表配置的工作流。2026 年 7 月 27 日的评估 报告了针对不同模型和任务的结果；但不保证首次尝试就能正确。

• semiotic/ai — 通过单次导入即可使用由架构支持的图表能力目录（XY、ordinal、network、realtime、geo、value 和可移植配方），针对 LLM 代码生成进行了优化。有关生成的当前目录，请参阅 ai/surface-manifest.json。具名导入现在可跨已发布的代码块进行 tree-shaking。在生产代码中，优先使用系列子路径（semiotic/xy、semiotic/geo、semiotic/value 等），明确指定所需的图表系列；下方的冷启动使用者表格报告初始加载和按需加载的成本。
• ai/schema.json — 每个组件的机器可读属性架构
• npx -y -p semiotic semiotic-mcp — MCP 服务，可在任何 MCP 客户端中通过工具渲染图表
• npx -p semiotic semiotic-ai --doctor — 在命令行验证组件和属性 JSON，并提供拼写错误建议和反模式检测
• diagnoseConfig(component, props) — 可编程反模式检测器，提供可执行的修复方案，涵盖验证、编码、无障碍访问和误导性设计（欺骗）检查
• auditData(component, props, data?) — 针对通过架构验证但会破坏数学运算的输入执行图表感知数值预检：非有限值、跨度为零的定义域、无效的对数输入、负尺寸几何值、不安全的归一化总计，以及主导比例尺的离群值。返回有界的行级证据，并集成到 diagnoseConfig、Chart Clinic、CLI doctor 和选择启用通知的 ChartContainer 中
• AGENTS.md — 面向现代编码 Agent 的精简仓库工作流； CLAUDE.md 导入该文件，Copilot 则会收到简短的兼容性桥接内容
• ai/reference.md — 完整的按需产品参考文档，不会加载到常驻的编码 Agent 上下文中
• llms.txt — 遵循新兴标准的机器可读文档

每张图表都内置错误边界、开发模式下带拼写错误建议的验证警告，以及无障碍功能（canvas aria-label、支持键盘导航的图例、键盘实时区域播报、SVG <title>/<desc>），让 AI 生成的代码能够通过可执行的诊断优雅地处理错误，而不是只显示空白屏幕。

无障碍访问是发布的一部分

《欧洲无障碍法案》 自 2025 年 6 月 28 日起适用于相关产品和服务。图表 库无法认证应用是否符合法律要求：适用范围、内容、 周边控件、测试和国家层面的执法仍由应用所有者负责。Semiotic 为这项工作提供可测试的基础设施： 键盘交互、无障碍数据表、分层说明、结构化导航、减少动态效果和强制颜色模式，以及针对已发布主题预设的 WCAG 衍生对比度测试。请参阅 无障碍文档，并开展应用自身的辅助技术和用户测试。

超越标准图表

网络可视化。 力导向图、桑基图、弦图、树形布局、矩形树图、圆形打包图和轨道图——全部以 React 组件形式提供，且使用与 LineChart 相同的属性 API。

流式数据。 实时图表通过基于 ref 的推送 API，以 60fps 在 canvas 上渲染。快速推送网络边会合并为每个动画帧的一次布局，同时读写方法可保留同步的写后读语义。内置衰减、脉冲和陈旧度编码，适用于监控仪表板。

协调视图。 LinkedCharts 通过共享选择状态，为任意组合的图表类型提供悬停交叉高亮、画笔交叉筛选、基于坐标的联动十字准线和选择同步。

地理可视化。 分级统计地图、比例符号地图、带动画粒子的流向地图和距离变形地图——全部基于 d3-geo 投影在 canvas 上渲染，并支持缩放/平移、瓦片底图和拖动旋转地球。

统计摘要。 箱线图、小提琴图、蜂群图、直方图、LOESS 平滑、带置信区间包络的预测和异常检测。只需一个属性，即可在散点图坐标轴上添加边缘分布图形。

一流的注释。 注释是与数据绑定的对象，而非事后添加的图形。标签、标注框、阈值、包围区域、统计叠加层和 React 小组件会随图表移动，并通过浏览器、SSR 和导出路径渲染。当图表需要传达编码本身以外的信息时，可启用位置布局、层级、密度、渐进披露、受众感知的内容量、溯源信息和编辑生命周期。

选择 API 层

层	适用场景	示例
Charts	使用图表级属性的常见图表类型	<LineChart data={d} xAccessor="x" yAccessor="y" />
Frames	全面控制渲染、交互和布局	<StreamXYFrame chartType="line" lineStyle={...} />

Chart HOC 只会注册所需的 mark 插件。直接使用 StreamXYFrame 时，其余内置插件会在首次客户端绘制时加载。如果 SSR 或首帧必须包含 marks，请在首次渲染前从 semiotic/xy 或 semiotic/realtime/core 调用 registerBuiltInXYPlugins()。

每个 Chart 组件都接受 frameProps 属性，让你无需离开更简洁的接口即可使用底层 Frame API。

序列化与互操作

图表可序列化为 JSON 并还原：toConfig、fromConfig、toURL、copyConfig、configToJSX。有 Vega-Lite 规范吗？fromVegaLite(spec) 可将其转换为 Semiotic 配置——与 configToJSX() 配合使用，可从笔记本和 AI 生成的规范实现完整往返转换。

需要外部审查潜在问题？实验性的 unstable_toDataPitfallsChain() 会构建无依赖的链式输入，供 datapitfalls 使用，其中包含 Semiotic 配置、JSX、读者理解依据、诊断信息、无障碍审查，以及可选的渲染 SVG/图像证据：

import { unstable_toDataPitfallsChain } from "semiotic/experimental"
import { detectPitfalls } from "datapitfalls"

const input = unstable_toDataPitfallsChain("LineChart", props, {
  narrative: "Monthly sales are accelerating.",
  rendered: { svg, evidence },
})

const report = await detectPitfalls(input, { apiKey: process.env.ANTHROPIC_API_KEY })

返回路径同样无依赖。将整张图表级别的发现用作 ChartContainer 通知；只有在应用能够将发现定位到 marks 或语义位置之后，才将其转换为注释：

import { ChartContainer } from "semiotic"
import { LineChart } from "semiotic/xy"
import {
  unstable_toDataPitfallsAnnotations,
  unstable_toDataPitfallsNotifications,
} from "semiotic/experimental"

const notifications = unstable_toDataPitfallsNotifications(report)
const annotations = unstable_toDataPitfallsAnnotations(report, {
  anchorFor: (finding) =>
    finding.ruleId === "truncated-axis" ? { x: 9, y: 9000 } : null,
})

<ChartContainer notifications={notifications}>
  <LineChart {...props} annotations={annotations} />
</ChartContainer>

何时选择其他工具

需要一个用于仪表板的标准柱状图或折线图，且除了颜色和标签之外永远不需要自定义？Recharts 拥有更庞大的生态系统和更多社区示例。需要使用 GPU 加速渲染数百万个数据点？Apache ECharts 可以处理这种规模。

Semiotic 面向那些需求超出上述库能力范围的项目——例如需要将网络图与时间序列、流式数据与静态快照，或不同图表类型间的协调视图结合使用。

安装

npm install semiotic

需要 React 18.1+ 或 React 19。

快速示例

协调式仪表板

悬停在一张图表上，即可通过共享选择在另一张图表中高亮相同数据：

import { LinkedCharts, Scatterplot, BarChart } from "semiotic"

<LinkedCharts>
  <Scatterplot
    data={data} xAccessor="age" yAccessor="income" colorBy="region"
    linkedHover={{ name: "hl", fields: ["region"] }}
    selection={{ name: "hl" }}
  />
  <BarChart
    data={summary} categoryAccessor="region" valueAccessor="total"
    selection={{ name: "hl" }}
  />
</LinkedCharts>

带衰减的流式指标

实时数据会淡化旧数据点、闪现新数据点，并标记过期的数据源：

import { RealtimeLineChart } from "semiotic"

const chartRef = useRef()
chartRef.current.push({ time: Date.now(), value: cpuLoad })

<RealtimeLineChart
  ref={chartRef}
  timeAccessor="time"
  valueAccessor="value"
  decay={{ type: "exponential", halfLife: 100 }}
  staleness={{ threshold: 5000, showBadge: true }}
/>

网络图

力导向图和桑基图——使用与 LineChart 相同的 API：

import { ForceDirectedGraph, SankeyDiagram } from "semiotic"

<ForceDirectedGraph
  nodes={people} edges={friendships}
  colorBy="team" nodeSize={8} showLabels
/>

<SankeyDiagram
  edges={budgetFlows}
  sourceAccessor="from" targetAccessor="to" valueAccessor="amount"
/>

地理可视化

分级统计地图、流向图和距离变形地图，支持 Canvas 渲染、 缩放/平移、瓦片底图和动态粒子：

import { ChoroplethMap, FlowMap, DistanceCartogram } from "semiotic/geo"

<ChoroplethMap
  areas={geoJsonFeatures} valueAccessor="gdp"
  colorScheme="viridis" projection="equalEarth" zoomable tooltip
/>

<FlowMap
  nodes={airports} flows={routes} valueAccessor="passengers"
  showParticles particleStyle={{ color: "source", speedMultiplier: 1.5 }}
/>

<DistanceCartogram
  points={cities} center="rome" costAccessor="travelDays"
  showRings costLabel="days" lines={routes}
/>

流式系统监控器

实时服务拓扑，支持阈值告警和点击检查：

import { StreamNetworkFrame, ChartContainer, DetailsPanel, LinkedCharts } from "semiotic"

const chartRef = useRef()
chartRef.current.push({ source: "API", target: "Orders", value: 15 })

<LinkedCharts>
  <ChartContainer title="System Monitor" status="live"
    detailsPanel={
      <DetailsPanel position="right" trigger="click">
        {(datum) => <div>{datum.id}: {datum.value} req/s</div>}
      </DetailsPanel>
    }>
    <StreamNetworkFrame ref={chartRef} chartType="sankey"
      showParticles particleStyle={{ proportionalSpeed: true }}
      thresholds={{ metric: n => n.value, warning: 100, critical: 250 }}
    />
  </ChartContainer>
</LinkedCharts>

标准图表

折线图、条形图、散点图和面积图共用同一套基于访问器的 API：

import { LineChart, BarChart } from "semiotic"

<LineChart
  data={salesData}
  xAccessor="month" yAccessor="revenue"
  curve="monotoneX" showPoints
/>

<BarChart
  data={categoryData}
  categoryAccessor="department" valueAccessor="sales"
  orientation="horizontal" colorBy="region"
/>

所有图表组件

类别	组件
XY	LineChart AreaChart DifferenceChart StackedAreaChart Scatterplot ConnectedScatterplot BubbleChart Heatmap QuadrantChart MultiAxisLineChart MinimapChart CandlestickChart ScatterplotMatrix
分类	BarChart StackedBarChart GroupedBarChart LikertChart SwimlaneChart FunnelChart SwarmPlot BoxPlot Histogram ViolinPlot RidgelinePlot DotPlot PieChart DonutChart GaugeChart
网络	ForceDirectedGraph ChordDiagram SankeyDiagram ProcessSankey TreeDiagram Treemap CirclePack OrbitDiagram
地理	ChoroplethMap ProportionalSymbolMap FlowMap DistanceCartogram
实时	RealtimeLineChart RealtimeHistogram RealtimeSwarmChart RealtimeWaterfallChart RealtimeHeatmap
协同	LinkedCharts
布局	ChartGrid ContextLayout CategoryColorProvider
帧	StreamXYFrame StreamOrdinalFrame StreamNetworkFrame StreamGeoFrame

Vega-Lite 转换

粘贴 Vega-Lite 规范，即可生成 Semiotic 图表：

import { fromVegaLite } from "semiotic/data"
import { configToJSX, fromConfig } from "semiotic"

const config = fromVegaLite({
  mark: "bar",
  data: { values: [{ a: "A", b: 28 }, { a: "B", b: 55 }] },
  encoding: {
    x: { field: "a", type: "nominal" },
    y: { field: "b", type: "quantitative" },
  },
})

// Render directly
const { componentName, props } = fromConfig(config)
// → componentName: "BarChart", props: { data, categoryAccessor: "a", valueAccessor: "b" }

// Or generate JSX code
configToJSX(config)
// → <BarChart data={[...]} categoryAccessor="a" valueAccessor="b" />

支持条形图、折线图、面积图、点、矩形、弧和刻度标记，并可转换颜色、大小、聚合和分箱编码。

对话轨迹遥测

捕获并重放 AI 辅助图表会话的操作路径：

import {
  createLocalStorageConversationArcSink,
  enableConversationArc,
  getConversationArcStore,
  loadConversationArc,
  registerConversationArcSink,
} from "semiotic/ai"

const sink = createLocalStorageConversationArcSink({ key: "my-app:arc" })
registerConversationArcSink(sink)
enableConversationArc({ sessionId: "session-abc" })

getConversationArcStore().record({ type: "chart-rendered", component: "LineChart" })
loadConversationArc(sink.load(), { enabled: false })

包体积

Semiotic 提供 41 个稳定的 JavaScript 入口点（40 个子路径加根路径）。除非需要全部功能，否则不要从 "semiotic" 导入——请使用与图表或工具相匹配的最小子路径。

自定义网络布局可以通过 semiotic/network/zoom 使用虚拟缩放/平移视口。它导出 ZoomableNetworkCustomChart 和投影尺寸/LOD 钩子；普通图表导入不会包含其手势和 LOD 运行时。

以下数字表示第一方产物成本：Semiotic 各子路径自身代码的 gzip 大小。它们不包含 React 和其他运行时依赖项；每行会统计该入口可访问的所有代码块，包括仅按需加载的代码，因此不能用来预测应用冷启动时的包体积。不要通过相加各产物行来估算应用体积：依赖解析和跨导入去重由使用方的打包器处理，并在下方单独测量。

入口点	gzip	包含内容
semiotic/atlas	322 KB	Motif Braid、Dependency Forest 和 Flow Circuit 读取器
semiotic/atlas/core	15 KB	Network Atlas 准备、投影和证据查询
semiotic/access	31 KB	Chart Access Contract 工厂和第一波基线契约
semiotic/evidence	47 KB	Chart Evidence Envelope、确定性哈希和发布门控
semiotic/artifact	125 KB	与渲染器无关的契约、声明、时间、策略、依据和传输审计
semiotic/artifact/react	4 KB	为制品契约和策略评估提供无障碍渐进式信息披露
semiotic/line	145 KB	仅包含 LineChart——单图微型边界
semiotic/xy	183 KB	LineChart、AreaChart、Scatterplot、Heatmap，以及另外 8 种 XY 图表
semiotic/ordinal	134 KB	BarChart、PieChart、BoxPlot、Histogram，以及另外 11 种分类图表
semiotic/network	180 KB	ForceDirectedGraph、SankeyDiagram、ProcessSankey、Treemap，以及另外 4 种图表
semiotic/network/zoom	190 KB	可选的虚拟网络视口、摄像机控件和由使用方管理的 LOD
semiotic/network/perspective	2 KB	等距图标和无障碍透视切换控件（该属性随 ./network 提供）
semiotic/network/perspective/core	3 KB	投影尺寸、分辨率和 SVG 放置辅助工具
semiotic/vite	1 KB	用于清理未使用 Semiotic worker 资源的构建插件
semiotic/geo	111 KB	ChoroplethMap、FlowMap、DistanceCartogram、ProportionalSymbolMap
semiotic/realtime	216 KB	RealtimeLineChart、RealtimeHistogram，以及另外 4 种流式图表
semiotic/realtime/core	214 KB	流式图表类型、高阶组件和缓冲区辅助工具
semiotic/realtime/react	2 KB	流状态和同步推送钩子
semiotic/server	278 KB	renderChart、renderDashboard、renderToImage、renderToAnimatedGif
semiotic/server/node	278 KB	renderChart、renderDashboard、renderToImage、renderToAnimatedGif
semiotic/server/edge	284 KB	renderChart、renderChartWithEvidence、renderToStaticSVG、renderDashboard
semiotic/utils	112 KB	ThemeProvider、数值/无障碍审计、序列化——不包含图表组件
semiotic/utils/core	102 KB	纯主题辅助工具、数值/无障碍审计和序列化
semiotic/utils/react	10 KB	ThemeProvider、useTheme、useReducedMotion、useHighContrast、useStreamStatus
semiotic/recipes	118 KB	纯布局函数（waffle、marimekko、flextree、dagre，……）
semiotic/recipes/core	115 KB	纯布局函数（waffle、marimekko、flextree、dagre，……）
semiotic/recipes/react	3 KB	Glyph 和 React 布局选择辅助工具
semiotic/themes	13 KB	仅包含主题预设（tufte、carbon 等）
semiotic/themes/core	13 KB	主题预设和令牌辅助工具
semiotic/themes/react	9 KB	ThemeProvider/useTheme 和钩子
semiotic/data	5 KB	bin、rollup、groupBy、pivot、fromVegaLite
semiotic/value	6 KB	BigNumber——焦点值 KPI/记分卡（SingleValueFrame POC）
semiotic/physics	188 KB	GaltonBoardChart、EventDropChart、UnitPileChart、CollisionSwarmChart、PacketFlowChart、PhysicsCustomChart
semiotic/physics/matter	1 KB	Matter.js 迁移辅助工具 + 可选的对等依赖守卫（不包含图表组件）
semiotic/physics/rapier	1 KB	Rapier 对等依赖守卫 + 适配器决策元数据（不包含图表组件）
semiotic/ai	668 KB	所有由架构支持的图表 + 验证——针对 LLM 代码生成进行优化
semiotic/ai/core	143 KB	suggestCharts、auditData、describeChart、repairChartConfig、工具适配器——不包含图表组件
semiotic/controls	19 KB	DirectManipulationControl、CircularBrush、LinearBrush、MobileStandardControls、auditVisualizationControls——不包含框架渲染器
semiotic/rough	3 KB	可选的确定性 Rough.js 绘制后端——Semiotic 的精确几何仍为权威依据
semiotic/text	2 KB	可选的 Pretext 注释钩子——排除对等依赖包
semiotic	429 KB	完整的图表 API 和共享工具

冷启动消费者的命名导入

上表衡量的是一方产物的体积，而不是应用程序包。下面生成的表格衡量的是另一项内容：一个全新的消费者通过公共导出路径，从打包后的 semiotic tarball 导入一个保留的命名导入，并像应用构建那样进行代码拆分。初始加载指图表渲染前页面下载的内容；按需加载指仅在功能需要时才获取的代码。表格包含 Semiotic 及其解析后的运行时依赖，但会将 React/React DOM 和宿主应用拥有的可选适配器对等依赖设为外部依赖。每一行都从冷启动开始，因此请用它比较单个公共导入选项，而不要将应用各行的体积相加。已检验的机器可读基线为 benchmarks/setup/cold-consumer-imports.json；生产构建后，可使用 npm run docs:cold-consumer 刷新。

方法：新建 npm pack --ignore-scripts tarball → 临时消费者 → 经压缩/摇树优化的 Rolldown（Vite 的打包器）ESM 构建，启用代码拆分并使用生产环境的 NODE_ENV → 对每个文件执行 gzip -9。初始加载统计入口及其静态导入的代码块；按需加载统计仅在功能需要时才获取的代码块（刷选、边缘图形、动画过渡、基础框架内置布局）。React/React DOM 和可选适配器对等依赖设为外部依赖；Semiotic 及其解析后的运行时依赖则包含在内。

Public named import	Runtime	gzip initial load	gzip on demand
import { semioticVite } from "semiotic/vite"	node	0.6 KiB	—
import { getNetworkPerspectiveSize } from "semiotic/network/perspective/core"	browser	1.1 KiB	—
import { MotifBraidChart } from "semiotic/atlas"	browser	109.8 KiB	29.3 KiB
import { prepareNetworkAtlas } from "semiotic/atlas/core"	browser	7.1 KiB	—
import { LineChart } from "semiotic"	browser	122.5 KiB	44.2 KiB
import { LineChart } from "semiotic/xy"	browser	122.1 KiB	32.2 KiB
import { LineChart } from "semiotic/line"	browser	122.3 KiB	32.2 KiB
import { BarChart } from "semiotic/ordinal"	browser	103.6 KiB	14.7 KiB
import { SankeyDiagram } from "semiotic/network"	browser	133.4 KiB	6.6 KiB
import { ZoomableNetworkCustomChart } from "semiotic/network/zoom"	browser	113.0 KiB	29.3 KiB
import { isometricGlyphs } from "semiotic/network/perspective"	browser	1.4 KiB	—
import { RealtimeLineChart } from "semiotic/realtime"	browser	119.5 KiB	42.0 KiB
import { RingBuffer } from "semiotic/realtime/core"	browser	0.7 KiB	13.6 KiB
import { useStreamStatus } from "semiotic/realtime/react"	browser	0.6 KiB	—
import { GaltonBoardChart } from "semiotic/physics"	browser	94.4 KiB	2.7 KiB
import { MATTER_PHYSICS_CAPABILITIES } from "semiotic/physics/matter"	browser	0.1 KiB	—
import { RAPIER_PHYSICS_CAPABILITIES } from "semiotic/physics/rapier"	browser	0.2 KiB	—
import { renderChart } from "semiotic/server"	node	298.0 KiB	—
import { generateFrameSVGs } from "semiotic/server/edge"	node	127.3 KiB	—
import { renderToImage } from "semiotic/server/node"	node	298.4 KiB	0.6 KiB
import { suggestCharts } from "semiotic/ai"	browser	37.9 KiB	13.6 KiB
import { suggestCharts } from "semiotic/ai/core"	browser	32.0 KiB	—
import { buildArtifactContract } from "semiotic/artifact"	browser	4.5 KiB	—
import { ArtifactInspector } from "semiotic/artifact/react"	browser	3.7 KiB	—
import { createChartAccessContract } from "semiotic/access"	browser	27.9 KiB	—
import { toEvidenceEnvelope } from "semiotic/evidence"	browser	43.5 KiB	—
import { bin } from "semiotic/data"	browser	0.9 KiB	—
import { ChoroplethMap } from "semiotic/geo"	browser	107.0 KiB	1.7 KiB
import { usePretextAnnotations } from "semiotic/text"	browser	1.5 KiB	—
import { createRoughRenderMode } from "semiotic/rough"	browser	3.2 KiB	—
import { resolveThemePreset } from "semiotic/themes"	browser	2.6 KiB	—
import { resolveThemePreset } from "semiotic/themes/core"	browser	2.6 KiB	—
import { ThemeProvider } from "semiotic/themes/react"	browser	6.2 KiB	—
import { validateProps } from "semiotic/utils"	browser	10.0 KiB	—
import { smartTickFormat } from "semiotic/utils/core"	browser	1.1 KiB	—
import { useReducedMotion } from "semiotic/utils/react"	browser	0.3 KiB	—
import { waffleLayout } from "semiotic/recipes"	browser	1.6 KiB	—
import { waffleLayout } from "semiotic/recipes/core"	browser	1.6 KiB	—
import { Glyph } from "semiotic/recipes/react"	browser	0.8 KiB	—
import { BigNumber } from "semiotic/value"	browser	5.8 KiB	—
import { DirectManipulationControl } from "semiotic/controls"	browser	1.5 KiB	—

**Line 边界说明：**保留命名导入 semiotic/line 的原始大小为 364.8 KiB，与 semiotic/xy 的 364.8 KiB 相同；gzip 大小相差 0.1 KiB（0.1%）。Tree-shaking 会让两条路径汇聚到相同的 LineChart 实现依赖图。请将 semiotic/line 视为更窄的 API／直接 ESM 产物边界，而非应用包体积优化。只有当某个图表的打包后命名导入相比所属系列路径同时节省 10 KiB gzip 和 7% 时，才应新增单图表入口。

**d3 打包模型：**Semiotic 将其导入的 12 个 d3 模块设为外部依赖，并将它们声明为常规运行时依赖。使用者无需手动安装 d3 包；其打包器会解析、去重并 tree-shake 该依赖图。对四个代表性图表系列的打包版 webpack 对比中，这种模型有三项表现更优；Next 16 的 webpack 路由也比完全打包的替代方案小 22.7 KiB gzip。唯一胜出的打包方案是 Sankey，但仅小 0.4 KiB gzip。此选择保留了由 22 个包组成、解压后大小为 1.9 MB 的 d3 安装依赖闭包，以换取更小的常见应用依赖图和常规依赖契约。已检查的策略为 npm run check:d3-packaging；可在 benchmarks/setup/d3-packaging.json 中查看可复现的证据，并在该隔离工具链目录中安装 webpack 和 Next 后，使用 npm run measure:d3-packaging -- --toolchain-root <dir> 重新生成。

// Import from the sub-path, not from "semiotic"
import { LineChart } from "semiotic/xy"
import { BarChart } from "semiotic/ordinal"
import { SankeyDiagram } from "semiotic/network"
import { ChoroplethMap } from "semiotic/geo"

Tree-shaking 与多子路径导入：系列入口（semiotic/xy、semiotic/network、semiotic/ai 等）构建为一个带有共享代码块的 ESM 依赖图。流帧、渲染器和其他通用代码只会打包一次，并由需要它们的每个入口导入——因此组合使用 semiotic/ai、semiotic/xy 和 semiotic/network，并不意味着要为运行时支付三份完整副本的成本。该包标记为 "sideEffects": false，因此现代打包器只会保留你所保留的命名导出（例如 LineChart + suggestCharts）。为清晰起见，建议使用系列子路径；如果不需要图表目录，请从 semiotic/ai 或更轻量的 semiotic/ai/core 导入 AI 辅助工具。

何时使用 "semiotic"：如果你想用一次导入来混用不同系列，可以使用它。共享代码块可避免不同系列子路径重复包含运行时代码；对于单个命名导入，上方的冷启动使用者表更具参考价值。

CommonJS 兼容性说明：require("semiotic/xy") 会加载共享的 CommonJS 客户端包（压缩前约 2.1 MB），以确保 React 上下文在不同系列导入中保持 单例。若关注包体积，浏览器构建中优先使用 ESM 导入；在缺少上下文标识 契约的情况下拆分此 CJS 客户端并不安全。

TypeScript

使用 strict: true 构建。包中附带完整类型定义。 支持泛型的类型安全访问器：

interface Sale { month: number; revenue: number }

<LineChart<Sale>
  data={sales}
  xAccessor="month"    // TS validates this is keyof Sale
  yAccessor="revenue"
/>

服务器端渲染

所有图表组件在服务器环境中都会自动渲染为 SVG——无需特殊导入或配置。非流式图表 HOC 可直接从 Next.js Server Component 导入并渲染：Semiotic 的 "use client" 指令定义了包边界，因此导入页面无需自行添加包装器或指令。跨越 该边界的 Props 必须保持可序列化；只有在引入钩子、回调属性、浏览器状态或由推送驱动的流式图表时，才需要添加由应用负责的客户端包装器。

// app/dashboard/page.tsx — a Next.js Server Component
import { LineChart } from "semiotic/xy"

// Server: renders <svg> with path/circle/rect elements
// Client: renders <canvas> with SVG overlay for axes
export default async function DashboardPage() {
  const data = await fetchMetrics()
  return <LineChart data={data} xAccessor="date" yAccessor="value" />
}

如需生成独立的 SVG／PNG／GIF（用于邮件、OG 图片、PDF、Slack），请使用服务器入口点：

import { renderChart, renderToImage, renderToAnimatedGif } from "semiotic/server"

// SVG — sync, no dependencies
const svg = renderChart("LineChart", {
  data, xAccessor: "date", yAccessor: "value",
  theme: "tufte", title: "Revenue Trend",
})

// PNG — async, requires sharp
const png = await renderToImage("BarChart", { data, ... }, { format: "png", scale: 2 })

// Animated GIF — async, requires sharp + gifenc
const gif = await renderToAnimatedGif("line", data, { ... }, { fps: 12 })

MCP 服务

mcp-name: io.github.nteract/semiotic

Semiotic 随附一个 MCP 服务，可让 AI 编码助手通过工具调用来渲染图表、诊断配置问题、发现架构、读取打包的 AI 指南并获取图表建议。

设置

添加到 MCP 客户端配置中（例如 Claude Desktop 的 claude_desktop_config.json）：

{
  "mcpServers": {
    "semiotic": {
      "command": "npx",
      "args": ["-y", "-p", "semiotic", "semiotic-mcp"]
    }
  }
}

本地 stdio 无需 API 密钥或身份验证。HTTP 模式也可用于检查器、Web 客户端和 ChatGPT Apps SDK 实验：npx -y -p semiotic semiotic-mcp --http --port 3001。默认绑定到 127.0.0.1，且仅接受其绑定主机名（以及用于回环的 localhost）。浏览器请求需要明确的来源允许列表，例如 MCP_ALLOWED_ORIGINS=http://localhost:5173；否则，任何携带 Origin 的请求都会被拒绝并返回 403。省略 Origin 的原生 MCP 客户端仍可正常工作。从 3.7.2 开始，HTTP 模式为无状态模式：每个请求都会创建一个全新的只读 MCP 服务和传输，因此可在无服务器主机上自动扩缩，无需粘性会话。

对于 ChatGPT 开发者模式，请通过隧道将 HTTP 端点暴露为 HTTPS，将 MCP_ALLOWED_HOSTS 设置为隧道主机名，并创建一个指向 https://<your-tunnel>/mcp 的连接器。对于公共接口，请明确使用 --host 0.0.0.0 或 MCP_HOST=0.0.0.0，并将 MCP_ALLOWED_HOSTS 配置为实际提供服务的主机名。配置完成前，即使绑定到所有网络接口，也仍只允许回环 Host 值。两个允许列表均以逗号分隔，并在预检、运行状况或 MCP 处理前进行检查。CORS 只会回显明确允许的来源；不支持通配符来源。当传输请求需要携带 bearer 令牌时，设置 MCP_AUTH_TOKEN。实验性的 Apps SDK 接口为 renderInteractiveChart，它会返回一个 text/html;profile=mcp-app 小组件模板，以及一个由 MCP 服务上的 Semiotic 渲染的隐藏 SVG 载荷。

有关托管部署，请参阅 deploy/cloud-run。该包装器会运行已发布的 semiotic-mcp 二进制文件，提供 /mcp 和运行状况端点，并支持使用 MCP_ALLOWED_HOSTS 配置生产环境的 Host 请求头允许列表。对于 ChatGPT Apps 域名验证，请设置 OPENAI_APPS_CHALLENGE_TOKEN，使 HTTP 模式从 /.well-known/openai-apps-challenge 提供原始令牌。

使用 --profile=public 启用包含五个工具的公共接口；也支持分开指定选项和值。 显式无效的配置文件或格式错误的选项会导致启动中止。默认情况下，两种配置文件和传输方式 都会通过 MCP_MAX_TOOL_OUTPUT_BYTES 将完整工具响应限制在 2 MiB，并对超大结果返回明确错误。

工具

工具	描述
renderChart	将 Semiotic 图表渲染为静态 SVG。支持 getSchema 返回且标记为 [renderable] 的组件。传入 { component: "LineChart", props: { data: [...], xAccessor: "x", yAccessor: "y" } }。返回 SVG 字符串，以及一个“渲染证据” JSON 块（按场景类型统计的标记数量、解析后的坐标轴域、空状态标记、注释数量、无障碍名称），供 Agent 验证图表是否绘制了数据标记；若有验证错误，则返回错误及修复建议。
renderInteractiveChart	将静态数据图表渲染为 ChatGPT Apps 小组件。使用与 renderChart 相同的 Semiotic 服务端渲染路径，然后为 iframe UI 加载交互功能，包括适配、缩放、数据、悬停和渲染证据控件。
getSchema	返回指定组件的属性架构。传入 { component: "LineChart" } 可获取该组件的属性；省略 component 则列出完整的、以架构为依据的目录。标记为 [renderable] 的组件可通过 renderChart 使用；实时图表需要浏览器或实时环境。
suggestChart	基于样例行的推荐工具。传入 { data: [{...}, ...] }，其中包含 1–5 个样例对象，以及可选的宽泛意图或能力筛选条件。
suggestCharts	面向有界行数据的能力型推荐工具。返回按得分排序的图表建议，包含理由、注意事项、导入路径和可直接使用的属性。
suggestStreamCharts	根据架构（形状、键、吞吐量）推荐流式图表。返回 { suggestions, excluded, stretchSuggestions }。
suggestStreamDashboard	根据流架构和受众布局策略，组合多面板仪表板。
suggestDashboard	构建涵盖不同分析意图的多面板仪表板建议。
suggestStretchCharts	根据 AudienceProfile 推荐拓展受众数据素养的图表。
repairChartConfig	检查请求的图表是否适用于数据集；若不适用，则返回按排名排序的替代方案。
interrogateChart	返回统计摘要和了解图表上下文的信息，以便回答自然语言问题，并可选择添加注释。
diagnoseConfig	检查图表配置中的常见问题——数据为空、尺寸不正确、缺少访问器、数据形状错误等。返回易读的诊断报告和可执行的修复方案。
reportIssue	为 Bug 报告或功能请求生成预填的 GitHub issue URL。传入 { title: "...", body: "...", labels: ["bug"] }。返回用户可打开并提交问题的 URL。
applyTheme	列出命名主题预设，或返回指定预设（例如 { name: "tufte" }）的 ThemeProvider/CSS/令牌用法。
auditArtifact	根据命名策略评估明确的制品契约，不推断缺失的来源、审核或时间信息。
recommendRepresentation	根据提供的数据、主张、证据、时间状态和策略要求，比较图表与非图表的呈现方式。
repairArtifact	提出契约修复方案，并可选择补全缺失的身份字段；已有的不匹配项需要修订并重新评估主张。
explainRefusal	说明哪些明确的策略义务阻止了发布或操作，并指出安全的后续工作。

制品工具是可选的诊断工具，不代表获得发布授权。 conditional 结果（包括 CLI 退出代码 0）表示仍有未完成的工作。常规的 renderChart 调用不会强制执行制品策略；受管控的宿主必须自行执行 发布边界。解决手动检查项以及与修订版本绑定的发布审批，仍属于单独的宿主工作流任务。

资源

资源	描述
semiotic://artifact-contract-schema	独立的 JSON Schema，用于定义可移植的用途、声明、证据、时间、审核和转移元数据。
semiotic://schema	完整的机器可读组件 Schema JSON。
semiotic://schema-index	精简的发现索引，包含类别、可渲染性、导入路径，以及每个组件的 Schema 资源 URI。
semiotic://schema/{component}	单个组件的 Schema、元数据、无障碍指南和行为契约（例如 semiotic://schema/LineChart）。
semiotic://components	向后兼容的组件索引，显示可渲染／仅限浏览器的状态及 MCP 类别。
semiotic://surface-manifest	当前 AI Schema、导出、可渲染性、工具、资源和提示词的生成式清单。
semiotic://behavior-contracts	Agent 可见的语义规则，涵盖颜色优先级、必需的 prop 组合、push ref 和可渲染性。
semiotic://system-prompt	精简的 AI 指令，包含导入规则、图表 props、SSR 指南和注意事项。
semiotic://examples	按数据形状分类的可复制粘贴图表示例。
ui://semiotic/chart-widget.html	renderInteractiveChart 使用的 ChatGPT Apps / MCP Apps 微件模板。

提示词

提示词	描述
build-semiotic-chart	可复用工作流，用于选择图表、读取 Schema、诊断 props 并渲染预览。
debug-semiotic-chart	可复用工作流，用于调试无效 props、渲染失败和问题报告。

示例：获取组件的 Schema

Tool: getSchema
Args: { "component": "LineChart" }
→ Returns: { "name": "LineChart", "description": "...", "parameters": { "properties": { "data": ..., "xAccessor": ..., ... } } }

示例：为你的数据推荐图表

Tool: suggestChart
Args: {
  "data": [
    { "month": "Jan", "revenue": 120, "region": "East" },
    { "month": "Feb", "revenue": 180, "region": "West" }
  ]
}
→ Returns:
  1. BarChart (high confidence) — categorical field (region) with values (revenue)
  2. StackedBarChart (medium confidence) — two categorical fields (month, region)
  3. DonutChart (medium confidence) — 2 categories — proportional composition

示例：渲染图表

Tool: renderChart
Args: {
  "component": "BarChart",
  "props": {
    "data": [
      { "category": "Q1", "revenue": 120 },
      { "category": "Q2", "revenue": 180 },
      { "category": "Q3", "revenue": 150 }
    ],
    "categoryAccessor": "category",
    "valueAccessor": "revenue"
  }
}
→ Returns: <svg>...</svg>

示例：渲染 ChatGPT Apps 微件

Tool: renderInteractiveChart
Args: {
  "component": "BarChart",
  "props": {
    "title": "Revenue by Quarter",
    "data": [
      { "quarter": "Q1", "revenue": 120 },
      { "quarter": "Q2", "revenue": 180 }
    ],
    "categoryAccessor": "quarter",
    "valueAccessor": "revenue"
  }
}
→ Returns: structured chart summary for the model + hidden SVG/widget metadata for ChatGPT.

微件 SVG 在嵌入前，会根据元素、属性、CSS 和 URL 许可列表重新构建。 支持本地片段引用和内嵌的 base64 PNG/JPEG/GIF/WebP 图像；外部资源、SVG 数据 URL、脚本、外来 HTML、 动画、CSS 导入和字体面规则都会被移除。允许的样式会限定在图表范围内，同时保留自动暗色调色板和注释 展开功能。主题变量使用受支持的颜色、长度、字体和其他令牌语法。SVG 格式错误时会返回明确的工具错误， 而不是显示空白的成功预览。微件宿主的 CSP 还提供了额外的安全边界。

示例：诊断有问题的配置

Tool: diagnoseConfig
Args: { "component": "LineChart", "props": { "data": [] } }
→ Returns: ✗ [EMPTY_DATA] data is an empty array — Fix: provide at least one data point

示例：报告问题

Tool: reportIssue
Args: {
  "title": "Bug: BarChart tooltip shows undefined for custom accessor",
  "body": "When using valueAccessor='amount', tooltip displays 'undefined'.\n\ndiagnoseConfig output: ✓ no issues detected.",
  "labels": ["bug"]
}
→ Returns: Open this URL to submit the issue: https://github.com/nteract/semiotic/issues/new?...

命令行替代方案

如需在没有 MCP 客户端的情况下快速验证：

npx -p semiotic semiotic-ai --list         # list components with import paths and renderability
npx -p semiotic semiotic-ai --list --json  # machine-readable component index
npx -p semiotic semiotic-ai --schema GaugeChart
npx -p semiotic semiotic-ai --suggest '{"data":[{"category":"A","value":10}],"intent":"comparison"}'
npx -p semiotic semiotic-ai --doctor       # validate component + props JSON
npx -p semiotic semiotic-ai --schema       # dump all chart schemas
npx -p semiotic semiotic-ai --compact      # compact schema (fewer tokens)

当 dist 可用时，--doctor 会运行完整的 diagnoseConfig 检查；在干净的源码检出环境中，则会回退到仅基于 Schema 的验证。

在哪里为 AI 助手查找 Semiotic

Semiotic 已被 AI 编码 Agent 文档工具收录，因此你的助手（Claude Code、Cursor、Cline、Copilot 等）可以获取最新文档和工具，无需复制粘贴：

• Context7 — context7.com/nteract/semiotic（通过 context7.json 配置）
• DeepWiki — deepwiki.com/nteract/semiotic
• GitMCP — gitmcp.io/nteract/semiotic（直接将仓库作为 MCP 端点公开）
• 官方 MCP Registry — 在 registry.modelcontextprotocol.io 搜索“semiotic”

官方 MCP Registry 是 MCP 目录中的规范记录；它与被任何助手供应商纳入其精选连接器目录是两回事。次级目录的更新状态和版本发布归属记录在 MCP_DISTRIBUTION.md 中。

面向 Agent 的 API：

• AGENTS.md 是简明的仓库开发约定，CLAUDE.md 会导入它以供 Claude Code 使用。这些文件保留在仓库本地，不会将无关的贡献者说明随包分发给使用者。
• ai/reference.md、ai/schema.json、ai/surface-manifest.json、ai/behaviorContracts.cjs 和 agent-skill/semiotic-charts/SKILL.md 都会打包到 npm 压缩包中（参见 package.json#files）。参考文档是通过 npx -p semiotic semiotic-ai 按需输出的产品指南；schema、清单、契约和可移植技能则提供结构化生成和验证指导。
• semiotic.nteract.io/llms.txt + /llms-full.txt — 根据 llms.txt 标准部署在文档网站上。Agent 通过 HTTP 获取导航地图（llms.txt）或完整内联文档（llms-full.txt）；它们不属于 npm 包本身。

文档

交互式文档和示例

• 快速入门
• 图表 — 含实时示例的图表类型
• Frame — 完整的 Frame API 参考
• 功能 — 坐标轴、工具提示、交互、响应式行为和组合
• 注释 — 一流的注释类型、设计指导、来源信息和生命周期
• 实用指南 — 高级模式和实用方案
• 交互式演练场 — 交互式探索属性

升级

• 迁移指南 — 从 v1.x 或 v2.x 升级
• 更新日志 — 完整的版本发布历史

贡献

请参阅 CONTRIBUTING.md。我们的社区遵循 nteract 行为准则。

致谢

本库的开发在很大程度上得益于 Susie Lu、Jason Reid、James Womack、 Matt Herman、Shelby Sturgis 和 Tristan Reid。

Sankey 布局引擎基于 Tom Shanley 编写的 sankey-plus，该项目在他早期的 d3-sankey-circular 基础上进行了改进，提供了更好的环路检测、分层弧形堆叠 和动态范围调整。

Semiotic 图标基于 Andre Schauer 创作的图标。

许可证

Apache 2.0