④段整套同步（六节＋ P/S/F/J ＋模板）＋ open-design 移到技能根

一、④段整套同步（用户选候选 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。
2026-10-15 21:17:28 +08:00
1 parent fa0a9026c8
commit 5afeb6b78a
@@ -0,0 +1,169 @@
+# Connectors
+
+`live-dashboard` is a **Live Artifact**. The values it shows are not
+hard-coded — they are polled from a connector at runtime. The OD daemon
+(0.4.0+) ships a Composio connector catalog and a `connectors.json`
+contract that artifacts emit alongside `index.html`.
+
+When `inputs.connector === mock` (or the daemon cannot resolve the
+configured connector), the artifact falls back to seeded sample data.
+This keeps screenshots, the picker preview, and offline use working.
+
+> **Status — relationship to `design-templates/live-artifact/`.**
+>
+> The canonical, currently-shipping live-artifact contract lives in
+> [`design-templates/live-artifact/SKILL.md`](../../live-artifact/SKILL.md): it is
+> *file-shaped* (`artifact.json` + `template.html` + `data.json` +
+> `provenance.json`) and *CLI-shaped* on the agent side (the agent calls
+> `"$OD_NODE_BIN" "$OD_BIN" tools live-artifacts {create,update}` and
+> `tools connectors {list,execute}` rather than HTTP). The renderer is
+> scalar-only `html_template_v1` (`apps/daemon/src/live-artifacts/render.ts`).
+>
+> `live-dashboard` is a **complementary** browser-runtime variant: the
+> artifact is rendered as a single self-contained HTML page, and the
+> live behaviors (refresh-on-open, manual Refresh, auto-refresh, stale
+> pill) run in-page rather than at template-render time. Polling
+> therefore needs an HTTP shape, which is what the rest of this file
+> describes (`POST /api/od/connectors/poll`).
+>
+> Treat the HTTP shape below as a **forward-looking proposal** that
+> sits alongside the file/CLI contract: the daemon does not yet expose
+> `POST /api/od/connectors/poll` (`apps/daemon/src/server.ts` /
+> `apps/daemon/src/live-artifacts/`), so out-of-the-box the artifact
+> renders against the seeded sample data and the Refresh button only
+> tweens the fixture. When the daemon-team route lands, only
+> `seedNextChange()` in the template needs to be replaced with the
+> `poll()` helper documented here — the `connectors.json` shape is
+> already a usable declarative source-of-truth that downstream tooling
+> (the live-artifact CLI, MCP wrappers, audit logs) can read today.
+
+---
+
+## `connectors.json` schema
+
+Emit one `connectors.json` at the project root next to `index.html`:
+
+```json
+{
+  "schema": "od.connector/1",
+  "primary": "notion",
+  "freshness": {
+    "auto_refresh_seconds": 30,
+    "warn_after_seconds": 90,
+    "fail_after_seconds": 600
+  },
+  "bindings": {
+    "notion": {
+      "provider": "composio.notion",
+      "auth_ref": "media-config.json#notion.token",
+      "reads": [
+        {
+          "id": "tasks_active",
+          "endpoint": "databases.{id}.query",
+          "params": { "id": "${notion.tasks_db_id}",
+                      "filter": { "property": "Status", "status": { "does_not_equal": "Done" } },
+                      "sorts":  [{ "property": "Updated", "direction": "descending" }] },
+          "shape": "task[]"
+        },
+        {
+          "id": "kpi_total",
+          "endpoint": "databases.{id}.query",
+          "params": { "id": "${notion.tasks_db_id}", "page_size": 1 },
+          "extract": "$.metadata.total_count",
+          "shape": "integer"
+        },
+        {
+          "id": "activity_recent",
+          "endpoint": "search",
+          "params": { "filter": { "property": "object", "value": "page" },
+                      "sort":   { "direction": "descending", "timestamp": "last_edited_time" },
+                      "page_size": 8 },
+          "shape": "activity[]"
+        }
+      ],
+      "events": [
+        { "id": "task_changed", "type": "page.updated", "selector": "$.tasks_db_id" }
+      ]
+    }
+  }
+}
+```
+
+The shape is intentionally close to Notion's REST API — the daemon's
+connector adapter rewrites `endpoint` and `params` into the live
+provider call. Other connectors (Linear, Stripe, Posthog) follow the
+same shape with provider-specific `endpoint` strings.
+
+---
+
+## Resolution order (what the daemon does)
+
+1. Read `connectors.json` from the artifact dir.
+2. Look up `bindings[primary].provider` in the Composio catalog.
+3. Resolve `auth_ref` against the daemon-owned media configuration. The narrow
+   `OD_MEDIA_CONFIG_DIR` override applies to `media-config.json` only;
+   otherwise the daemon must derive the file from its already-resolved
+   `RUNTIME_DATA_DIR`. Do not infer a path from the project cwd or restate one
+   here. Before changing this lookup, read root `AGENTS.md` → **Daemon data
+   directory contract** and
+   [`apps/daemon/src/media/config.ts`](../../../apps/daemon/src/media/config.ts).
+
+   The artifact never opens any of these paths itself — it always goes
+   through the daemon poll endpoint, and the daemon enforces the
+   correct lookup order. **Never** read tokens from the artifact.
+4. For each `reads[].endpoint`, the daemon constructs the live HTTP
+   request with the resolved auth and substitutes `${...}` placeholders
+   from the resolved `media-config.json#<provider>.*` values.
+5. Cache responses for `freshness.auto_refresh_seconds`. The
+   `Refresh` button issues an explicit poll that bypasses the cache.
+
+---
+
+## Wiring inside `index.html`
+
+The artifact does **not** call Composio directly. It calls the OD
+daemon's local proxy:
+
+```js
+async function poll(readId) {
+  const res = await fetch(`/api/od/connectors/poll`, {
+    method: "POST",
+    headers: { "content-type": "application/json" },
+    body: JSON.stringify({ project: "<project_id>", read: readId })
+  });
+  if (!res.ok) throw new Error(`poll ${readId} failed: ${res.status}`);
+  return res.json();
+}
+```
+
+`<project_id>` is injected by the daemon at render time via a
+`<meta name="od:project" content="...">` tag. The artifact reads it
+once on mount.
+
+---
+
+## Fallback behavior
+
+- On `fetch` error: keep the previously-rendered values, swap the
+  live-pill to amber `Stale · <ago>`, write a small grey hint into the
+  footer (`Source: Notion · last good poll 4 min ago`).
+- On `inputs.connector === mock`: skip `poll()` entirely, use the
+  `seedMock()` function in `index.html`. The live-pill displays
+  `Sample data` in grey with no dot animation.
+- On 401/403: surface a one-time toast `Reconnect Notion in Settings →
+  Connectors` and stop further polls until the next manual Refresh.
+
+---
+
+## Provider-specific cheat sheet
+
+| Connector | `provider`         | Shape of one row             | Typical KPI                        |
+|---        |---                 |---                           |---                                 |
+| Notion    | `composio.notion`  | `task = {title, status, assignee, due, prio, updated}` | total tasks · done this week · members · review |
+| Linear    | `composio.linear`  | `issue = {title, state, assignee, priority, updated}`  | backlog · in progress · blocked · cycle progress |
+| Stripe    | `composio.stripe`  | `event = {type, amount, customer, created}`            | MRR · churn · new subs · refunds   |
+| Posthog   | `composio.posthog` | `event = {name, distinct_id, $current_url, ts}`        | DAU · signups · feature adoption · errors |
+
+Do not invent per-provider shapes. If the user wants something not in
+this table, fall back to `mock` and surface a footer hint asking the
+user to extend the connector catalog.