live-artifact

实时产物技能

创建一个 OpenDesign 实时产物：一个项目范围内可预览的 HTML 产物，其数据之后可以刷新，而无需重新设计展示形式。

资源映射

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

当前状态

请将此目录中的参考资料作为实时产物文件规范的准确信息来源。注册或更新实时产物时，优先使用守护进程封装命令，而非原始 HTTP。

何时使用此技能

当用户需要数据驱动的视图，并且希望它在首次渲染后仍然有用时，请使用此技能，例如实时仪表板、可刷新的报告、同步状态页面、可审计的数据视图，或之后可从本地／项目数据或连接器刷新数据的产物。

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

• 如果用户提到刷新、同步、定期更新、连接器支持的数据、来源／出处追踪、仪表板、报告或可复用的数据驱动视图，请使用实时产物。
• 如果用户只需要一次性的 HTML／模型图／图像／文件，且不需要刷新、来源元数据或数据／出处面板，请使用普通静态产物。
• 如果意图不明确，请简短询问一个问题：“您希望它可刷新／实时更新，还是只需要静态产物？”

工作流

1. 确定范围和数据源，但不要因连接器未连接而停滞

   • 明确预览目标、受众、数据时效预期，以及之后是否需要支持刷新。
   • 如果用户明确指出了某个连接器／来源，例如 Notion、GitHub、Slack 或 Google Drive，在检查守护进程连接器工具之前，不要询问“数据应该来自哪里？”
   • 如有可用的本地／项目来源或守护进程连接器工具，请优先使用。
   • 如果存在守护进程连接器／封装器，不要直接调用提供方 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 数据源在哪里？”

2. 编写源文件

   • 将 template.html 编写为人工设计的 HTML 模板。守护进程会根据 html_template_v1 绑定契约，使用 data.json 为模板填充数据——必须遵守该契约，否则填充会失败，原始模板会直接发布，显示可见的 {{…}} 标记：
     • 标量：{{data.path.to.value}}。路径以 data 开头，并以点分隔；允许使用数字数组索引（{{data.kpis.0.value}}）。每个绑定都必须解析为单个字符串或数字，不能是对象或数组。
     • 列表：使用 data-od-repeat="item in data.items" 重复一个元素，然后在其中绑定循环作用域字段，例如 {{item.label}}（标量数组则使用 {{item}}）。只支持一层；在重复元素内仍可使用 data.* 访问全局数据。
     • 不要在 <script> 中手动循环（预览时脚本会被移除），也不要在没有匹配的 data-od-repeat 作用域时引用不带前缀的循环变量，例如 {{metric.value}}——这种绑定无法解析。不支持嵌套重复、条件、过滤器、辅助函数和原始／三重花括号插值。
   • 将 data.json 编写为这些绑定使用的规范预览数据——使用真实值，而非占位符。
   • 编写 artifact.json，其中包含实时产物元数据、预览声明、文档声明和安全的源描述符。
   • 编写 provenance.json，其中包含简洁的来源说明、时间戳、非敏感的连接器引用和转换说明。
   • 不要将 index.html 作为源文件编写。守护进程会根据 template.html 和 data.json 生成 index.html。

3. 保持数据精简并以预览为导向

   • 仅存储预览所需的规范化值。
   • 将大型列表、提供方响应或日志摘要后，再写入 data.json。
   • 遵守 references/artifact-schema.md 中有界 JSON 的规则。

4. 注册前应用安全规则

   • 不要在 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 插值。

5. 通过守护进程包装命令注册或更新

   • 使用 OpenDesign 守护进程包装命令 "$OD_NODE_BIN" "$OD_BIN"，而不是原始 curl、裸 node 或裸 od：

     "$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；守护进程会根据令牌推导项目／运行作用域。

   • 仅在明确要求时，才将原始 HTTP 用于守护进程开发／调试。

6. 使用连接器包装命令获取连接器数据

   • 发现可用的连接器和工具：

     "$OD_NODE_BIN" "$OD_BIN" tools connectors list --format compact
     

   • 使用 JSON 对象输入文件执行只读连接器工具：

     "$OD_NODE_BIN" "$OD_BIN" tools connectors execute --connector "$CONNECTOR_ID" --tool "$TOOL_NAME" --input input.json
     

   • 仅持久化预览所需的精简规范化字段，以及非敏感的连接器引用（connectorId、toolName、accountLabel）。切勿持久化连接器凭据、传输元数据或提供方的原始输出。

   • 不要询问连接器密钥或重复设置。如果 status 为 connected，请使用列出的工具；如果未连接，请告知用户在 UI 中连接。

   • 有关列表/执行和凭据边界，请参阅 references/connector-policy.md；有关只读刷新源元数据，请参阅 references/refresh-contract.md。

7. 简洁地报告结果

   • 成功时，返回产物 ID/标题，并说明 index.html 是由守护进程派生生成的。
   • 验证失败时，修复源文件并通过包装器重试。不要绕过验证。

必需文件

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

• template.html — 声明的技能输出，也是预览的源模板。
• data.json — 精简、规范的预览数据。
• artifact.json — 用于守护进程验证的创建/更新输入。
• provenance.json — 安全的来源和转换摘要。

index.html 是在 frontmatter 中声明的主要预览入口，但它是由守护进程派生生成的输出，而非由 Agent 编写的源文件。