live-artifact

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

Live Artifact Skill

Live Artifact 技能

Create an Open Design live artifact: a project-scoped, previewable HTML artifact whose data can later be refreshed without redesigning the presentation.

创建一个Open Design实时工件：一种项目范围的、可预览的HTML工件，其数据无需重新设计展示即可在后续刷新。

Resource map

资源目录

live-artifact/
├── SKILL.md
└── references/
    ├── artifact-schema.md      ← `references/artifact-schema.md`: artifact files, DTO shape, template binding rules
    ├── connector-policy.md     ← `references/connector-policy.md`: connector safety, redaction, credential boundaries
    └── refresh-contract.md     ← `references/refresh-contract.md`: source metadata, refresh execution, snapshots

live-artifact/
├── SKILL.md
└── references/
    ├── artifact-schema.md      ← `references/artifact-schema.md`：工件文件、DTO结构、模板绑定规则
    ├── connector-policy.md     ← `references/connector-policy.md`：连接器安全性、脱敏处理、凭证边界
    └── refresh-contract.md     ← `references/refresh-contract.md`：源元数据、刷新执行、快照

Current status

当前状态

Use the references in this directory as the source of truth for the live artifact file contract. Prefer daemon wrapper commands over raw HTTP when registering or updating live artifacts.

请将此目录中的参考文档作为实时工件文件约定的权威来源。注册或更新实时工件时，优先使用daemon包装命令而非原始HTTP请求。

When to use this skill

何时使用此技能

Use this skill when the user asks for a data-backed view that should remain useful after the first render, for example a live dashboard, refreshable report, synced status page, auditable data view, or artifact that can later be refreshed from local/project data or connectors.

Before creating files, decide whether the user actually wants a live artifact or a normal static artifact:

Use a live artifact when the user mentions refresh, sync, recurring updates, connector-backed data, source/provenance tracking, dashboards, reports, or reusable data-backed views.
Use a normal static artifact when the user only wants a one-off HTML/mockup/image/file and does not need refresh, source metadata, or data/provenance panels.
If the intent is ambiguous, ask one short question: “Should this be refreshable/live, or just a static artifact?”

当用户请求数据驱动的视图且该视图在首次渲染后仍需保持可用性时，可使用此技能，例如实时仪表板、可刷新报告、同步状态页面、可审计数据视图，或可后续从本地/项目数据或连接器刷新的工件。

在创建文件前，需判断用户实际需要的是实时工件还是普通静态工件：

当用户提及刷新、同步、定期更新、连接器支持的数据、来源/溯源跟踪、仪表板、报告或可复用的数据驱动视图时，使用实时工件。
当用户仅需要一次性HTML/原型图/图像/文件，且不需要刷新、源元数据或数据/溯源面板时，使用普通静态工件。
如果意图不明确，可提出一个简短问题：“此工件需要可刷新/实时功能，还是仅为静态工件？”

Workflow

工作流程

Resolve scope and data source without blocking on connected connectors
- Identify the preview goal, audience, data freshness expectations, and whether refresh should be possible later.
- If the user explicitly names a connector/source such as Notion, GitHub, Slack, or Google Drive, do not ask “where should the data come from?” before checking daemon connector tools.
- Prefer local/project sources or daemon connector tools when available.
- Do not call provider APIs directly when a daemon connector/wrapper exists.
- If connector data is needed, first list connectors with
```
"$OD_NODE_BIN" "$OD_BIN" tools connectors list --format compact
```
  . If the named connector is present with
```
status: "connected"
```
  , choose an appropriate read-only
```
auto
```
  tool from its catalog and execute it through the connector wrapper.
- For Notion specifically, a connected
```
notion
```
  connector plus a user brief that names Notion is enough to start with
```
notion.notion_search
```
  using a query derived from the requested artifact/topic. Use
```
notion.notion_fetch_database
```
  only when the user supplied a database id or the search result clearly identifies one.
- Ask the user a data-source question only when no matching connected connector exists, multiple connected candidates fit equally well, or the requested artifact has no usable topic/query to search for. If you must ask, be specific: ask for the page/database/topic or permission to search broadly, not “where is the Notion data source?”
Author the source files
- Write
```
template.html
```
  as the human-designed HTML template.
- Write
```
data.json
```
  as the canonical preview data used by
```
{{data.path}}
```
  bindings.
- Write
```
artifact.json
```
  with the live artifact metadata, preview declaration, document declaration, and safe source descriptors.
- Write
```
provenance.json
```
  with concise source notes, timestamps, non-sensitive connector references, and transformation notes.
- Do not author
```
index.html
```
  as source. The daemon derives
```
index.html
```
  from
```
template.html
```
  and
```
data.json
```
  .
Keep data compact and preview-oriented
- Store only normalized values needed by the preview.
- Summarize large lists, provider responses, or logs before writing them into
```
data.json
```
  .
- Stay within the bounded JSON rules in
```
references/artifact-schema.md
```
  .
Apply safety rules before registration
- Never store credentials, OAuth tokens, API keys, cookies, auth headers, raw provider responses, HTTP envelopes, full payloads, or secret-like fields in
```
artifact.json
```
  ,
```
data.json
```
  ,
```
provenance.json
```
  , or source metadata.
- Avoid forbidden key names such as
```
raw
```
  ,
```
rawResponse
```
  ,
```
payload
```
  ,
```
body
```
  ,
```
headers
```
  ,
```
cookie
```
  ,
```
authorization
```
  ,
```
token
```
  ,
```
secret
```
  ,
```
credential
```
  , and
```
password
```
  anywhere in persisted JSON.
- Use escaped
```
html_template_v1
```
  interpolation only. Raw/unescaped HTML interpolation is not allowed.
Register or update through daemon wrappers
- Use the Open Design daemon wrapper commands via
```
"$OD_NODE_BIN" "$OD_BIN"
```
  instead of raw
```
curl
```
  , bare
```
node
```
  , or bare
```
od
```
  :
  bash
```
"$OD_NODE_BIN" "$OD_BIN" tools live-artifacts create --input artifact.json
"$OD_NODE_BIN" "$OD_BIN" tools live-artifacts list --format compact
"$OD_NODE_BIN" "$OD_BIN" tools live-artifacts update --artifact-id "$ARTIFACT_ID" --input artifact.json
```
- The wrapper reads injected
```
OD_NODE_BIN
```
  ,
```
OD_BIN
```
  ,
```
OD_DAEMON_URL
```
  , and
```
OD_TOOL_TOKEN
```
  ; do not print, persist, or override token values.
- Do not include or invent
```
projectId
```
  ; the daemon derives project/run scope from the token.
- Use raw HTTP only for daemon development/debugging when explicitly requested.
Use connector wrappers for connector data
- Discover available connectors and tools:
  bash
```
"$OD_NODE_BIN" "$OD_BIN" tools connectors list --format compact
```
- Execute a read-only connector tool with a JSON object input file:
  bash
```
"$OD_NODE_BIN" "$OD_BIN" tools connectors execute --connector "$CONNECTOR_ID" --tool "$TOOL_NAME" --input input.json
```
- Persist only the compact normalized fields needed by the preview plus non-sensitive connector references (
```
connectorId
```
  ,
```
toolName
```
  ,
```
accountLabel
```
  ). Never persist connector credentials, transport metadata, or raw provider output.
- Do not ask for connector secrets or duplicate setup. If
```
status
```
  is
```
connected
```
  , use the listed tools; if it is not connected, tell the user to connect it in the UI.
- See
```
references/connector-policy.md
```
  for listing/execution and credential boundaries, and
```
references/refresh-contract.md
```
  for read-only refresh source metadata.
Report concise results
- On success, return the artifact ID/title and note that
```
index.html
```
  is daemon-derived.
- On validation failure, fix the source files and retry through the wrapper. Do not bypass validation.

解析范围和数据源，无需等待已连接的连接器
- 明确预览目标、受众、数据新鲜度预期，以及后续是否需要刷新功能。
- 如果用户明确指定了某个连接器/数据源（如Notion、GitHub、Slack或Google Drive），在检查daemon连接器工具前，不要询问“数据来自哪里？”。
- 优先使用本地/项目源或daemon连接器工具（如果可用）。
- 当存在daemon连接器/包装器时，不要直接调用服务商API。
- 如果需要连接器数据，首先使用
```
"$OD_NODE_BIN" "$OD_BIN" tools connectors list --format compact
```
  列出连接器。如果指定的连接器状态为
```
status: "connected"
```
  ，从其目录中选择合适的只读
```
auto
```
  工具，并通过连接器包装器执行。
- 针对Notion，若已连接
```
notion
```
  连接器且用户需求中提及Notion，即可使用从请求的工件/主题衍生的查询，通过
```
notion.notion_search
```
  开始操作。仅当用户提供了数据库ID或搜索结果明确指向某个数据库时，才使用
```
notion.notion_fetch_database
```
  。
- 仅当不存在匹配的已连接连接器、多个已连接候选者适配程度相同，或请求的工件没有可用的主题/查询进行搜索时，才向用户询问数据源问题。若必须询问，请具体说明：请求页面/数据库/主题，或询问是否允许广泛搜索，而非笼统地问“Notion数据源在哪里？”
编写源文件
- 编写
```
template.html
```
  作为人工设计的HTML模板。
- 编写
```
data.json
```
  作为
```
{{data.path}}
```
  绑定使用的标准预览数据。
- 编写
```
artifact.json
```
  ，包含实时工件元数据、预览声明、文档声明和安全源描述符。
- 编写
```
provenance.json
```
  ，包含简洁的源说明、时间戳、非敏感连接器引用和转换说明。
- 不要编写
```
index.html
```
  作为源文件。daemon会从
```
template.html
```
  和
```
data.json
```
  生成
```
index.html
```
  。
保持数据紧凑且面向预览
- 仅存储预览所需的标准化值。
- 在写入
```
data.json
```
  之前，先汇总大型列表、服务商响应或日志。
- 遵守
```
references/artifact-schema.md
```
  中的受限JSON规则。
注册前应用安全规则
- 切勿在
```
artifact.json
```
  、
```
data.json
```
  、
```
provenance.json
```
  或源元数据中存储凭证、OAuth令牌、API密钥、Cookie、认证头、原始服务商响应、HTTP信封、完整负载或类似机密的字段。
- 在持久化JSON中避免使用禁用的键名，如
```
raw
```
  、
```
rawResponse
```
  、
```
payload
```
  、
```
body
```
  、
```
headers
```
  、
```
cookie
```
  、
```
authorization
```
  、
```
token
```
  、
```
secret
```
  、
```
credential
```
  和
```
password
```
  。
- 仅使用转义的
```
html_template_v1
```
  插值。不允许使用原始/未转义的HTML插值。

通过daemon包装器注册或更新

使用

"$OD_NODE_BIN" "$OD_BIN"

调用Open Design daemon包装命令，而非原始

curl

、裸

node

或裸

od

命令：

bash

"$OD_NODE_BIN" "$OD_BIN" tools live-artifacts create --input artifact.json
"$OD_NODE_BIN" "$OD_BIN" tools live-artifacts list --format compact
"$OD_NODE_BIN" "$OD_BIN" tools live-artifacts update --artifact-id "$ARTIFACT_ID" --input artifact.json

包装器会读取注入的
```
OD_NODE_BIN
```
、
```
OD_BIN
```
、
```
OD_DAEMON_URL
```
和
```
OD_TOOL_TOKEN
```
；请勿打印、持久化或覆盖令牌值。
不要包含或虚构
```
projectId
```
；daemon会从令牌中推导项目/运行范围。
仅在明确要求进行daemon开发/调试时使用原始HTTP请求。

使用连接器包装器获取连接器数据
- 发现可用的连接器和工具：
  bash
```
"$OD_NODE_BIN" "$OD_BIN" tools connectors list --format compact
```
- 使用JSON对象输入文件执行只读连接器工具：
  bash
```
"$OD_NODE_BIN" "$OD_BIN" tools connectors execute --connector "$CONNECTOR_ID" --tool "$TOOL_NAME" --input input.json
```
- 仅持久化预览所需的紧凑标准化字段以及非敏感连接器引用（
```
connectorId
```
  、
```
toolName
```
  、
```
accountLabel
```
  ）。切勿持久化连接器凭证、传输元数据或原始服务商输出。
- 不要询问连接器机密或重复设置。如果状态为
```
connected
```
  ，使用列出的工具；如果未连接，请告知用户在UI中进行连接。
- 有关列出/执行和凭证边界，请参阅
```
references/connector-policy.md
```
  ；有关只读刷新源元数据，请参阅
```
references/refresh-contract.md
```
  。
报告简洁结果
- 成功时，返回工件ID/标题，并说明
```
index.html
```
  由daemon生成。
- 验证失败时，修复源文件并通过包装器重试。请勿绕过验证。

Required files

必填文件

Every live artifact creation flow must produce these source files before registration:

```
template.html
```
— declared skill output and source template for the preview.
```
data.json
```
— compact, canonical preview data.
```
artifact.json
```
— create/update input for daemon validation.
```
provenance.json
```
— safe source and transformation summary.

index.html

is the primary preview entry declared in frontmatter, but it is derived daemon output rather than agent-authored source.

在注册前，每个实时工件创建流程必须生成以下源文件：

```
template.html
```
— 声明的技能输出和预览的源模板。
```
data.json
```
— 紧凑的标准预览数据。
```
artifact.json
```
— daemon验证的创建/更新输入。
```
provenance.json
```
— 安全的源和转换摘要。

index.html

是前端声明中指定的主要预览入口，但它是daemon生成的输出，而非Agent编写的源文件。