④段整套同步(六节 + 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。
This commit is contained in:
admin committed 2026-10-15 21:17:28 +08:00
1 parent fa0a9026c8
commit 5afeb6b78a
4184 files changed
+326 -70

No files matched your search

@@ -0,0 +1,83 @@
# Pre-emit checklist (P0 must pass; do not write index.html until green)
Quote each P0 row in your reply with `[x]` or `[ ]`. Do not emit while
any P0 is unchecked.
## Visual integrity
- [ ] **P0 — Display face**. Page title uses a system / Notion-leaning
sans (SF Pro / system-ui) or an editorial serif from the active
DESIGN.md. **Never Inter Display, never SF Pro Display at body
size, never Helvetica condensed.**
- [ ] **P0 — Accent restraint**. The `--accent` token appears at most
twice in the body markup (one Refresh button + one sparkline
stroke is canonical). No accent on KPI numbers.
- [ ] **P0 — No purple/pink gradient header**. The Notion idiom is
flat. Backgrounds are `#fff` or `var(--bg-soft)`.
- [ ] **P0 — Body contrast**. Body text vs. background ≥ 4.5:1.
Secondary text ≥ 4.0:1.
- [ ] **P0 — No emoji icon strip across the top**. Page-emoji is one,
semantically meaningful (`📊` for ops, `📓` for docs, `🚀` for
launch — never an emoji decoration row).
## Honesty (the most-violated rule)
- [ ] **P0 — No invented metric**. Every number is either provided by
the user, by the connector, or labeled as `—` / `Sample`.
Forbidden: "10× faster", "join 50,000 founders", "99.99% uptime"
unless the user supplied the literal number.
- [ ] **P0 — Sample-data badge**. When `inputs.connector === mock`,
the page must display "Sample data" in the live-pill or callout
so a screenshot of this artifact is never mistaken for real ops.
- [ ] **P0 — Plausible KPI ranges**. `Total tasks` < 500 for a small
team. `Active members` ≤ team size. `Done this week` ≤ Total.
## Connector wiring (only when connector !== mock)
- [ ] **P0 — `connectors.json` exists** at the project root. See
`connectors.md` for the schema.
- [ ] **P0 — Endpoints documented**. Every `fetch()` call inside
`index.html` corresponds to one entry in `connectors.json`.
- [ ] **P0 — No hardcoded secrets**. No API tokens, integration secrets,
OAuth client IDs, or workspace IDs in the markup. The OD daemon
resolves these via `media-config.json`.
- [ ] **P0 — Stale fallback**. On `fetch` error or > 90s without a
successful poll, the pill swaps to amber and the previous values
remain on screen. The artifact never goes blank.
## Structural
- [ ] **P0 — Single file**. `index.html` self-contained. No external
CSS/JS imports beyond the system font stack and one OD custom
element. No CDN URLs.
- [ ] **P0 — Sidebar collapses on `< 980px`**. The dashboard is
mobile-readable; sidebar hides, KPI grid stacks 2-up, table
drops `due` and `priority` columns.
- [ ] **P0 — `prefers-reduced-motion`**. All tweens and pulses are
disabled when `(prefers-reduced-motion: reduce)`.
- [ ] **P0 — `tabular-nums` on KPI values**. Numeric values shouldn't
jitter horizontally during tween or auto-refresh.
## Polish (P1)
- [ ] P1 — Refresh button shows a spinning ↻ for the duration of the
poll, then settles back. No layout shift.
- [ ] P1 — Activity feed: newly-inserted row gets a left-edge accent
bullet (•) and a soft accent background for 2s, then fades.
- [ ] P1 — Database row that just changed flashes the row background
with a 1.4s ease-out.
- [ ] P1 — Live-pill states: green pulse (idle), blue solid
(syncing), amber solid (stale).
- [ ] P1 — Sparkline grid lines are dashed, line-color from `--line`,
stroke-dasharray `2 3`. Dots are filled `--accent` r=3.
- [ ] P1 — Toast bottom-center, dark `#1f1f1f`, 1800ms auto-dismiss.
## Content
- [ ] P1 — Person chips: 18px round avatar, two-letter initials,
stable per-name color. No initials > 2 chars.
- [ ] P1 — Status pill copy uses Notion canonical labels:
"Done", "In progress", "Blocked", "In review", "To do".
Case matters: "In progress" not "In-Progress".
- [ ] P1 — Footer attribution names the source platform and the
connector slug exactly: `composio.notion`, `composio.linear`, etc.
@@ -0,0 +1,212 @@
# Components
Copy these markup shapes verbatim. Re-skin via the active `DESIGN.md`
(color, typography, spacing tokens). Do not invent new component
shapes — that's where AI-slop sneaks in.
All snippets assume the CSS custom properties defined in
`assets/template.html` (`--ink`, `--ink-2`, `--bg-soft`, `--accent`,
`--line`, `--pill-*-bg/ink`, …).
---
## live-pill (top-right of the topbar)
```html
<div class="pill-live" id="livePill">
<span class="dot"></span>
<span id="liveText">Live · synced</span>
</div>
```
Three states:
| State | Class on `.pill-live` | Dot color | Text |
|--- |--- |--- |--- |
| Idle | (none) | green | `Live · synced` |
| Syncing | `.syncing` | accent | `Syncing…` |
| Stale | `.stale` | amber | `Stale · 2 min ago` |
The green dot animates a 1.8s `pulse` keyframe. Disable on
`prefers-reduced-motion`.
---
## kpi card (one cell of the KPI grid)
```html
<div class="kpi">
<div class="label">Total tasks</div>
<div class="value" id="kTotal">142</div>
<div class="delta up"><span class="arr">↑</span> 6 vs last week</div>
</div>
```
Rules:
- `.value` is `font-size: 32px; font-weight: 600; letter-spacing: -0.01em;
font-variant-numeric: tabular-nums`
- `.label` is `12px uppercase letter-spacing .03em` color `--ink-2`
- `.delta.up` → green; `.delta.down` → red; neutral `.delta` is grey
- On refresh, tween `value` between old and new with a 600ms cubic
ease-out, and add `.flash` for 700ms (turns the number `--accent-ink`
briefly).
- **Never** put a colored progress bar under the number.
- **Never** put a sparkline inside a KPI card — sparklines belong in
the two-column block.
---
## sparkline (SVG, hand-rolled)
```html
<svg class="spark" viewBox="0 0 600 140" preserveAspectRatio="none">
<g class="spark-grid">
<line x1="0" y1="35" x2="600" y2="35"/>
<line x1="0" y1="70" x2="600" y2="70"/>
<line x1="0" y1="105" x2="600" y2="105"/>
</g>
<path class="spark-fill" d=""></path>
<path class="spark-line" d=""></path>
<g id="sparkDots"></g>
<g id="sparkLabels" class="spark-axis"></g>
</svg>
```
CSS:
- `.spark-fill` is `fill: rgba(<accent-rgb>, 0.10)`
- `.spark-line` is `fill: none; stroke: var(--accent); stroke-width: 2`
- `.spark-grid line` is `stroke: var(--line); stroke-dasharray: 2 3`
- `.spark-dot` (circles, r=3) is `fill: var(--accent)`
Compute paths from a length-7 series with padding 24/16/10/24 (L/R/T/B)
inside the 600×140 viewBox. Today's bucket is at the right.
Do not use Chart.js / Recharts / D3 — single artifact, no external deps.
---
## activity-feed row
```html
<div class="feed-row">
<span class="av" style="background:#f1c40f">SC</span>
<div class="body">
<span class="who">Sarah Chen</span>
<span class="what"> moved</span>
<span class="target"> 🚀 Q3 Roadmap planning</span>
<span class="what"> to In progress</span>
</div>
<div class="time">3 min ago</div>
</div>
```
- Avatar: 26px round, two-letter initials, color stable per person.
- `.target` gets a 1px dotted underline and `cursor: pointer`.
- A "just inserted" row gets the `.new` class for 2s — applies a soft
`rgba(<accent>, .06)` background and a `•` bullet before the name.
- Re-render relative timestamps every 15s.
---
## status pills (Notion canonical five-color set)
```html
<span class="pill done">Done</span>
<span class="pill progress">In progress</span>
<span class="pill blocked">Blocked</span>
<span class="pill review">In review</span>
<span class="pill todo">To do</span>
```
| Class | Background | Foreground | Notion label |
|--- |--- |--- |--- |
| `done` | `#dbeddb` | `#2b593f` | Done |
| `progress` | `#fdecc8` | `#976d23` | In progress |
| `blocked` | `#ffe2dd` | `#b13b2c` | Blocked |
| `review` | `#d3e5ef` | `#1f5b78` | In review |
| `todo` | `#e9e5e3` | `#5a534f` | To do |
Do not introduce extra states. Map any project-specific state into one
of these five.
---
## linked-database row
```html
<div class="db-row">
<div class="db-cell">📐</div>
<div class="db-cell title"><span class="t">Design tokens v2 spec</span></div>
<div class="db-cell"><span class="pill review">In review</span></div>
<div class="db-cell"><span class="person">…avatar…<span>Lisa Zhao</span></span></div>
<div class="db-cell due">May 14</div>
<div class="db-cell priority">Med</div>
</div>
```
- 6-column grid: `32px 2.4fr 1fr 1fr 0.9fr 0.9fr`
- `.db-row.changed` triggers a 1.4s row-flash via the `rowflash`
keyframe.
- Hover: `background: var(--bg-soft)`. No transform / shadow.
---
## refresh button (page header, primary)
```html
<button class="btn primary" id="refreshBtn">
<span class="ico" id="refreshIco">↻</span>
<span>Refresh from Notion</span>
</button>
```
- Default: `background: var(--accent); color: #fff;`
- Hover: `background: var(--accent-ink)`
- During poll: add `.spin` to `.ico`, disable button taps via the
`busy` flag in JS (do **not** rely on `[disabled]` so visuals stay
identical).
- Label adapts to connector: "Refresh from Notion" / "Refresh from
Linear" / "Refresh from Stripe" — never just "Refresh" alone.
---
## auto-toggle (page header, ghost)
```html
<button class="btn ghost" id="autoBtn" title="Auto refresh every 30s">
<span>⏱</span><span id="autoLbl">Auto · on</span>
</button>
```
Toggles `setInterval(refresh, refresh_seconds * 1000)`. Persists to
`localStorage.live_dashboard_auto` so a reload restores the state.
---
## toast (bottom-center, transient)
```html
<div class="toast" id="toast">Synced — 3 changes from Notion</div>
```
`position: fixed; bottom: 20px; left: 50%; transform: translateX(-50%);`
1800ms auto-dismiss. Dark `#1f1f1f` background, white text. One toast
at a time; subsequent calls reset the timer.
---
## callout (Notion idiom)
```html
<div class="callout">
<div class="emj">💡</div>
<div>
<div><strong>This page is a Live Artifact.</strong> Numbers below are pulled from
your <strong>Acme Studio</strong> Notion workspace via the Composio connector.</div>
<small>Refreshes on demand or when the page opens. Last 7 days only.</small>
</div>
</div>
```
One short, declarative sentence + a smaller meta line. No marketing
copy, no "Powered by", no exclamation marks.
@@ -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.
@@ -0,0 +1,92 @@
# Layouts
Pick exactly **one** layout. State your choice in your reply before
emitting `index.html`.
All three share the same shell from `assets/template.html`:
`grid-template-columns: 240px 1fr` (sidebar + main), a 44px topbar, a
56px page top padding, and a max-width of 1100px on the page column.
---
## A · Classic dashboard (default)
Vertical stack inside the page column, in this order:
1. **Page header** (emoji + title + meta row)
2. **Live-Artifact callout**
3. **KPI grid** — 1 row × N (where N = `inputs.kpi_count`),
1px hairline grid
4. **Two-column block** — `1.1fr 1fr`:
- left: **Tasks created · last 7 days** sparkline card
- right: **Recent activity** feed card
5. **Linked database** — `Tasks · Active sprint`
6. **Footer**
Use this when:
- The user said "team dashboard" / "ops dashboard" without further qualifier.
- The user wants a generalist Notion-like landing page for a team
workspace.
This is what `example.html` ships.
---
## B · Kanban-flavored
Same shell, but replace the linked database (step 5) with a **3-column
kanban board**:
```
┌── To do ───────┐ ┌── In progress ─┐ ┌── In review ───┐
│ card │ │ card │ │ card │
│ card │ │ card (changed) │ │ card │
│ + add │ │ card │ │ card │
└────────────────┘ └────────────────┘ └────────────────┘
```
Cards are 1px-bordered, 12px padding, with: emoji row + title (medium
weight) + assignee chip + due date.
Use this when:
- The user explicitly said "kanban", "sprint board", "backlog view".
- `inputs.include_task_table` is true *and* the user mentioned drag /
swimlane / column.
The Live behavior stays the same: cards animate from one column to the
next on refresh (250ms ease-out translate, plus a 600ms accent
left-border on the moved card).
---
## C · KPI-only hero
Drop the database entirely. The page is **just**:
1. Page header
2. Callout (slightly taller — explain the data range)
3. **Hero KPI grid**: 2 × 2 with 32px → 56px font-size on the numbers
(use `display_scale` parameter)
4. The sparkline spans full width (no two-column split)
5. Activity feed becomes a single horizontal ticker (3 visible rows max,
auto-scrolls every 8s)
6. Footer
Use this when:
- `inputs.include_task_table === false`.
- The user said "exec summary", "morning standup", "weekly snapshot".
- The user wants something to throw on a TV in the office.
---
## Density & responsive notes (apply to all three)
- The `density` parameter controls the gap between blocks (callout →
KPIs → two-column → DB) — 8px low, 36px high. Default 18.
- Below 980px viewport, sidebar hides, the page padding drops to 20px,
KPI grid becomes 2-up, and the two-column block stacks.
- Below 640px, the linked database hides `due` and `priority` columns
and the kanban becomes a 1-column vertical scroll.
- Honor `prefers-reduced-motion: reduce` everywhere — disable tweens,
pulses, kanban-card translate, ticker auto-scroll, and the live-pill
pulse.