admin
5afeb6b78a
一、④段整套同步（用户选候选 A）
- 新增 `references/stage-proto-doc/assets/产品文档模板.html`（16 KB／247 行，从备份拷、转 LF）。
- ④段 SKILL.md 换成备份 15:28 那版，并按模板口径改齐：
· 「产品文档框架」从「四块＋一附录」改成**六节** —— 页面结构／功能清单／使用场景／操作流程／
跨页与界面状态／待确认与偏离；与模板同构，⛔ 不从空白页重写结构。
· 编号从 R/S/F 改成 **P 页面／S 场景／F 功能／J 二级功能**，各自唯一、按展示顺序通排。
· 保留旧版有价值的要求：每项功能补齐 做什么／入口在哪／输入边界／异常与恢复；重点功能三处标红；
横向流程图每步写清页面／功能／操作／完成判据。
· 完成标准「七节」→「六节」，自查清单同步换掉「需求」那批条目，补模板与配图两条。
· 路径 `designs/<项目>/` → `docs/pm/<项目>/ui/`（2 处）。
· 补回本机那条「每份产出文档开头都要有一张图」的引用（指向主 skill，段内不复述）。
- 主 skill 同步：四段结构表④行、④段沿革、画图小节（④段画页面结构图 ＋ 用户路径）。
二、open-design 移到技能根（用户选候选 A）
- `git mv product-planning/references/stage-delivery/assets/open-design → open-design/`（4178 文件）。
- `.gitignore` 白名单加 `!/open-design/` —— 否则移出去就不再纳入版本控制。
- 引用改 11 处：路径形态 `assets/open-design/...` → `<技能根>/open-design/...`；
「随段携带的自带件」改称「同根技能」；「路径怎么找」那条改成自带件（段内相对路径）与
同根技能（`<技能根>/<技能名>/`）两类分开写。
- open-design 自己的 ATTRIBUTION.md 两处同步（它现在与 oil-ui-pro 同层）。
- 副作用（有益）：命名闸门读数由 2063 降到 225 —— 此前它把 open-design 里 919 个第三方 md
当成规则一起扫了；现在只扫本包 23 个 md。已确认④段的 H1 与 4a/4b/4c 子步仍在检查范围内。
三、验收
- check_naming.py --ws E:/ProgramData/AIProject/contentm_agent ＝ 通过 225 / 失败 0 / 提示 27。
- 活文件里 `assets/open-design` 残留 0；工作区 CRLF 文件 0。
140 lines
8.7 KiB
Markdown
140 lines
8.7 KiB
Markdown
---
|
|
name: live-artifact
|
|
description: |
|
|
Create refreshable, auditable OpenDesign artifacts backed by connector or local data.
|
|
Trigger when the user asks for live dashboards, refreshable reports, synced views, or reusable data-backed artifacts.
|
|
triggers:
|
|
- "live artifact"
|
|
- "live dashboard"
|
|
- "refreshable dashboard"
|
|
- "live report"
|
|
- "refreshable report"
|
|
- "synced view"
|
|
- "可刷新"
|
|
- "实时看板"
|
|
od:
|
|
mode: prototype
|
|
scenario: live
|
|
preview:
|
|
type: html
|
|
entry: index.html
|
|
reload: debounce-100
|
|
design_system:
|
|
requires: true
|
|
outputs:
|
|
primary: index.html
|
|
secondary:
|
|
- template.html
|
|
- artifact.json
|
|
- data.json
|
|
- provenance.json
|
|
capabilities_required:
|
|
- shell
|
|
- file_write
|
|
---
|
|
|
|
# Live Artifact Skill
|
|
|
|
Create an OpenDesign live artifact: a project-scoped, previewable HTML artifact whose data can later be refreshed without redesigning the presentation.
|
|
|
|
## 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
|
|
```
|
|
|
|
## 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.
|
|
|
|
## 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?”
|
|
|
|
## Workflow
|
|
|
|
1. **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?”
|
|
|
|
2. **Author the source files**
|
|
- Write `template.html` as the human-designed HTML template. The daemon hydrates it with `data.json` using the `html_template_v1` binding contract — stay inside it or hydration fails and the raw template ships with visible `{{…}}` tokens:
|
|
- Scalars: `{{data.path.to.value}}`. Paths start with `data`, dot-separated; numeric array indexes are allowed (`{{data.kpis.0.value}}`). Every binding must resolve to a single string/number, not an object or array.
|
|
- Lists: repeat one element with `data-od-repeat="item in data.items"`, then bind loop-scoped fields inside it as `{{item.label}}` (or `{{item}}` for a scalar array). One level only; `data.*` still works inside the repeat for globals.
|
|
- Do NOT hand-loop in a `<script>` (scripts are stripped from previews), and do NOT reference a bare loop variable like `{{metric.value}}` without a matching `data-od-repeat` scope — that binding is unresolvable. Nested repeats, conditionals, filters, helpers, and raw/triple-brace interpolation are unsupported.
|
|
- Write `data.json` as the canonical preview data used by those bindings — real values, not placeholders.
|
|
- 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`.
|
|
|
|
3. **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`.
|
|
|
|
4. **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.
|
|
|
|
5. **Register or update through daemon wrappers**
|
|
- Use the OpenDesign 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.
|
|
|
|
6. **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.
|
|
|
|
7. **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.
|
|
|
|
## 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.
|