Guiro — 可共享的可视化快照

Guiro（https://guiro.io）是一种临时性的“呈现层即服务”（Presentation Layer as a Service）。您向其提供一个结构化的 JSON 数据包，用以描述一组可视化组件的布局，它将返回一个短期有效、公开可访问的分享链接（例如：https://guiro.io/s/{slug}）。渲染出的页面是一个经过精心设计、只读的可视化界面——可以是仪表盘、报表、图表、日历或状态页。查看该页面无需登录或注册账号。

每当您生成结构化结果时（如指标数据、表格、时间线、财务信息、活动日程、进度追踪等），并希望将其转换为用户可在浏览器中打开、发送给同事或导出为 PDF 的可共享可视化成果时，请使用本技能。

您可以构建的内容类型

API 工作流程

1. 获取能力清单 — 查询所支持的协议版本与组件目录。
2. 构建请求载荷（Payload） — 组装符合当前运行合约值（live contract values）的 A2UI JSON 数据包。
3. 校验 — 在创建前确认载荷格式正确无误。
4. 创建 — 发布该数据包，并获取对应的分享链接。

端点（Endpoints）

基础 URL：https://api.guiro.io

认证方式

所有请求均需通过 X-API-Key 请求头提供 API 密钥。密钥从环境变量 GUIRO_API_KEY 中读取。若密钥缺失，请提示用户提供。

命令行操作

# 1 – 获取能力清单（结果保存至 .guiro/runtime-capabilities.json）
bash "{baseDir}/scripts/fetch-capabilities.sh"

# 2 – 编写示例载荷（可选类型：dashboard | calendar | chart | donut）
bash "{baseDir}/scripts/write-sample-payload.sh" ./payload.json dashboard

# 3 – 校验并创建 guiro
bash "{baseDir}/scripts/create-guiro.sh" --payload ./payload.json --idempotency-key run-001

示例载荷仅为起点。请将其中占位符内容替换为与用户请求直接相关的真实数据。

载荷（Payload）结构

一个合法的 A2UI 数据包应具备如下结构：

{
  "storage_version": "1",
  "a2ui_version": "0.9",
  "catalog_id": "guiro.shadcn.detached.v1",
  "theme": {
    "primary": "#0f766e",
    "secondary": "#0f172a"
  },
  "messages": [
    {
      "version": "v0.9",
      "createSurface": {
        "surfaceId": "share-main",
        "catalogId": "guiro.shadcn.detached.v1"
      }
    },
    {
      "version": "v0.9",
      "updateComponents": {
        "surfaceId": "share-main",
        "components": [ ... ]
      }
    }
  ]
}

• storage_version、a2ui_version、catalog_id — 应使用 capabilities 接口响应中返回的值。
• messages 数组必须包含且仅包含一条 createSurface 消息和一条 updateComponents 消息。
• 必须且仅能面向一个 surface（表面）进行操作。

组件参考

components 数组是一个扁平化的组件对象列表。每个组件需具有唯一字符串 ID（id）及明确的 component 类型。父级组件通过子组件的 id 引用其子项。整个组件树中必须包含一个 id: "root" 的组件。

布局类组件

内容类组件

组件树示例

[
  { "id": "root", "component": "Card", "child": "page" },
  { "id": "page", "component": "Column", "gap": "lg", "children": ["heading", "metrics"] },
  { "id": "heading", "component": "Text", "text": "Monthly Report", "variant": "h1" },
  { "id": "metrics", "component": "Row", "gap": "md", "children": ["badge1", "progress1"] },
  { "id": "badge1", "component": "Badge", "label": "Active: 42", "variant": "outline" },
  { "id": "progress1", "component": "ProgressIndicator", "value": 75, "max": 100 }
]

主题（Theme）

颜色支持十六进制（#0f766e）或 OKLCH（oklch(0.527 0.154 150.069)）格式：

{ "primary": "#0f766e", "secondary": "#0f172a" }

请根据内容特性选择合适的主题色，并确保 primary 与 secondary 具有足够对比度。

规范与约束

• 始终优先调用 capabilities 接口，并严格使用其返回值填充 storage_version、a2ui_version 和 catalog_id。
• 创建前必须执行 validate 校验。
• 数据包必须且仅能指向一个 surface。
• updateComponents 所含组件中必须存在 id: "root" 的组件。
• 将校验错误视为权威依据——修正载荷后重新校验，直至通过为止。
• 可将示例载荷作为结构模板使用，但须将所有占位内容替换为用户请求中的真实数据。
• 在提升内容可扫描性（scanability）的前提下，优先选用 Icon 组件增强章节标题、强调区块（callout）及状态提示效果。

输出结果

成功创建后返回：

{
  "slug": "abc123",
  "url": "https://guiro.io/s/abc123",
  "expires_at": "2025-07-15T12:00:00Z"
}

请将 url 分享给用户。Guiro 为临时性资源：一旦超过 expires_at 时间，该链接将跳转至标准化的“此 Guiro 已过期”页面。