| name | design-lab |
| description | 個人化品牌設計系統 skill — multi-client cases + Astro local dashboard + authenticated sidecar HTTP bridge for Open Design integration. v0.3 auto-auth 架構：`/design` 自動 ensure sidecar、cold spawn 旋轉 local API token、`/api/context` 提供 retrieval-scoped payload 給 Open Design 注入 prompt。Memory 在 ~/Documents/CC Cli/design-library/。 |
| version | 0.3.0 |
design-lab v0.3 — sidecar auto-auth 架構
個人化品牌設計系統。三大組件：
- Multi-client vault：v0.2 schema_version=2，每個 client 獨立
cases/ + anti-library/，retrieval scope 自動 union（type:self clients 跨 client 共享）。
- Sidecar daemon（Express + SQLite + chokidar，
localhost:5174）：watch vault → SQLite cache → 5 個 API + dashboard SSR mount；v0.3 起有 host allowlist + write-route token auth。
- Local dashboard（Astro 5 SSR + Tailwind 4，從 sidecar 同 port serve）：4 page UI（overview / clients CRUD / case grid / style-guide editor），SSR 注入 API token 給 CSR fetch。
Memory 庫位置：~/Documents/CC Cli/design-library/（Obsidian vault 內）。
啟動 hook
每個 slash command 第一個動作都跑 schema check；v0.3 起 /design 在 schema check 後會自動 ensure sidecar，讓 Open Design bridge skill 在 generation pre-flight 可抓 context：
bash $SKILL_DIR/scripts/check-schema.sh "$HOME/Documents/CC Cli/design-library"
退出碼 2 = 提示用戶跑 migration；退出碼 1 = 致命錯誤；退出碼 0 = 繼續。
如 vault 不存在：先跑 bash $SKILL_DIR/scripts/init-library.sh "$HOME/Documents/CC Cli/design-library" 初始化（v0.2 結構：clients/_personal/、scenario-overrides/、personal-style-guide.md）。
如 vault 是 v1 結構（root cases/ + anti-library/，無 clients/）：check-schema 會提示跑 bash $SKILL_DIR/scripts/migrate-v1-to-v2.sh "$HOME/Documents/CC Cli/design-library"，自動把 root cases 搬到 clients/_personal/cases/，sibling 備份原 vault。
/design 專用 auto-spawn：
bash $SKILL_DIR/scripts/ensure-sidecar.sh
spawn 失敗時 design.sh fail soft，只提示 bridge 將 fallback 到 no-memory generation，不阻塞本次 design。
Slash commands（v0.3 只保留 2 個）
/design <task description> — 主入口
做什麼：根據任務描述，組 brand.yaml token > personal-style-guide > taste-overrides > taste-skill baseline 的 design context，從個案庫抽相似 case，產出 design。
執行：
bash $SKILL_DIR/scripts/design.sh "<task description>"
design.sh 行為：
- 跑 schema check（exit 2 提示 migration / exit 1 致命）
- v0.3: 開頭自動
ensure-sidecar.sh（fail soft），給 bridge skill 抓 context；cold spawn 會產生 token 並啟 sidecar
- 印 task description
- 印
composed-design-context：brand.yaml tokens、personal-style-guide、taste-overrides、section-filtered taste-skill baseline
- 透過
node --import tsx 載入 lib/case-loader.ts，輸出 cases/ frontmatter summary（含 client / slug / scenario / quotes / tags / palette）
- 印 case_count（用
find clients/*/cases/*.md）+ fallback flag
- 印 INSTRUCTIONS：Claude 從 summary 挑 top 5 → 載 scenario-override → 產出 design → 跑 lint
Claude 接著做：
/design-dashboard — 啟動 local dashboard
做什麼：啟 authenticated sidecar daemon (port 5174) + dashboard，瀏覽器開 http://localhost:5174/。v0.3 起 sidecar-start.sh 內部委派 ensure-sidecar.sh，保留舊入口向後相容。
執行：
bash $SKILL_DIR/scripts/sidecar-start.sh
Script 行為：
- vault 不存在 → 提示先跑 init-library.sh，exit 1
- 委派
ensure-sidecar.sh
- 已 running（PID file +
/api/health 偵測）→ 直接印 URL
- dashboard dist 不存在 → 自動
cd dashboard && npm install && npm run build
- cold spawn 時產生 API token，寫
~/.claude/state/design-lab/api-token（0600），並 export 給 sidecar process
- spawn
node --import tsx sidecar/server.ts（背景）
- 寫 PID 到
~/.claude/state/design-lab/sidecar.pid
- poll
http://127.0.0.1:5174/api/health 最多 10s 等 ready
- 印 PID + URL + log path
Auth 行為：
GET /api/health 不需 auth。- API host 必須符合 allowlist（default 包含
127.0.0.1:5174、localhost:5174、localhost:4322，case-insensitive）。
POST / PUT / DELETE write route 必須帶 X-Design-Lab-Token。- Dashboard SSR 會把
DESIGN_LAB_API_TOKEN 注入 <meta name="design-lab-token">，CSR fetch 自動帶 token；401 時 reload 一次後清旗標。
4 個 dashboard page：
/ — overview（totals / byClient / scenarios / recent cases / ClientSwitcher）/clients — client CRUD（new / edit / archive）/clients/[slug] — case grid + scenario/sentiment filter/style-guide — personal-style-guide.md editor（hash conflict 偵測）
停止：
bash $SKILL_DIR/scripts/sidecar-stop.sh
Stale PID 會自動 self-heal（清 PID file 後可重啟）。
Training layers（MCP canonical）
Training side uses a layered write model:
- Capture：Hermes / local agents call MCP
add_feedback with signal, user_quote, verdict, client, case_slug, dimension, derived_rule. This is the canonical capture path into sidecar + feedback-log.jsonl.
- Distill：scheduled/script distill is machine-only training. It deterministically regenerates
design-library/taste-overrides.md from feedback-log.jsonl.
- Style-guide edits：
personal-style-guide.md is human-curated. The only write path is MCP cluster/review → user approval → MCP edit_style_guide with expectedHash.
Distill must not write, mutate, append to, or frontmatter-bump personal-style-guide.md.
v0.1 commands（已收斂進 dashboard）
| v0.1 command | v0.2 替代 |
|---|
/design-collect | dashboard /clients/[slug] 右上 + 按鈕（呼叫 POST /api/cases），或 bash $SKILL_DIR/scripts/collect.sh <image> 仍可用（v0.2 互動加問 client，預設 _personal） |
/design-feedback | MCP add_feedback 是 canonical capture；舊 dashboard / script feedback 入口僅視為相容層 |
/design-stats | dashboard 首頁 overview（含 byClient + byScenario + totals），或 bash $SKILL_DIR/scripts/stats.sh 仍可用 |
/design-distill | scheduled/script distill 只重生 taste-overrides.md；不寫 personal-style-guide.md |
v0.2 vault 結構
~/Documents/CC Cli/design-library/
├── personal-style-guide.md # DO / NEVER / SOMETIMES（含 NEVER regex rules）
├── scenario-overrides/
│ ├── landing.md
│ ├── saas-ui.md
│ ├── brand.md
│ └── content.md
├── clients/
│ ├── _personal/ # type: self（個人案例）
│ │ ├── meta.yaml # schema_version: 2 + slug + name + type + theme_color
│ │ ├── cases/ # positive cases
│ │ │ └── <slug>.md # frontmatter: client / slug / scenario / sentiment / tokens / tags
│ │ └── anti-library/ # negative cases (NEVER signals)
│ ├── aicycle/ # type: client（外部品牌）
│ │ ├── meta.yaml
│ │ ├── cases/
│ │ └── anti-library/
│ └── .archived/ # archiveClient 搬到這（不真刪）
├── feedback-log.jsonl # JSONL，canonical write path is MCP add_feedback
├── taste-overrides.md # machine layer regenerated by distill; never human approval source
└── .index/
└── library.db # SQLite cache (sidecar 寫，schema 4 表)
Retrieval scope union 規則（/api/context + loadCaseSummaries）：
- 沒指定 client → 全 client union
- 指定 type:client → target + 所有 type:self union
- 指定 type:self → 全 type:self union（不含其他 type:client）
- 未知 client slug → unknown + 全 type:self union
Bridge to Open Design
架構更新（2026-06）：日常設計迴圈改走 ace hermes 本機端，經一個包 sidecar 的 MCP server 讀 context + 寫 capture（見 docs/adr/0002）。open-design 退為選用重型生成 studio，本段 bridge 仍有效但非日常主路徑；兩 repo 不合併（見 docs/adr/0001）。設計域術語見根目錄 CONTEXT.md，完整 v0.4 願景見 docs/superpowers/specs/2026-06-02-design-lab-v0.4-hermes-capture.md。
Sidecar 提供 /api/context?client=X&scenario=Y 讓 open-design fork 內 design-memory-bridge skill 在 generation pre-flight 抓 context：
TOKEN="$(cat "$HOME/.claude/state/design-lab/api-token")"
curl -s "http://127.0.0.1:5174/api/context?client=$CLIENT&scenario=$SCENARIO" \
-H "X-Design-Lab-Token: $TOKEN"
Response shape：
{
"client": ClientMeta | null,
"styleGuide": "...full markdown...",
"scenarioOverride": "...landing.md content or empty...",
"cases": [...top 5 positive in scope...],
"antiCases": [...all negative in scope...],
"neverRules": [{ "id", "pattern", "target" }, ...],
"retrievedFrom": ["aicycle", "_personal", "zhenheco"]
}
Bridge contract（理想注入）：把 styleGuide + scenarioOverride 注入 system prompt、cases 當參考、antiCases 提示 NEVER。現況：open-design fork 內 design-memory-bridge skill（commit 101f2d3）目前把整包 /api/context JSON 直接 JSON.stringify 進 prompt（盲轉，未做上述語意框定），保真度提升列 backlog。任一 bridge consumer 必須按 v0.3 spec §3.4 bridge contract + §4.1 design-memory-bridge SKILL.md template：
- 從
$HOME/.claude/state/design-lab/api-token 讀 token。
GET /api/context 帶 X-Design-Lab-Token。- 401 時重新讀 token 並 retry 一次。
- 不要詢問、印出、寫入或旋轉 token；token lifecycle 由 design-lab
ensure-sidecar.sh 管。
Sidecar 不可用時 bridge 應 fallback 到無記憶 generation 而非 fail hard。
DELETE route 也是 write route；bridge skill 或 fork helper 若未來要呼叫 DELETE，必須先讀 token 並帶 X-Design-Lab-Token。
Auth & Auto-spawn (v0.3+)
Token lifecycle：
- 每次 cold spawn 由
ensure-sidecar.sh 產生新的 32-byte hex token。
- token 寫到
$HOME/.claude/state/design-lab/api-token，umask 077 + chmod 600。
- token 透過
DESIGN_LAB_API_TOKEN export 給 sidecar process；dashboard SSR 從同 env 注入 meta token。
- 已健康運行的 sidecar 不重生、不旋轉 token；PID stale 或 sidecar dead 時清 PID 後 cold spawn 旋轉。
Host allowlist：
- default allowlist：
127.0.0.1:5174、localhost:5174、localhost:4322。
- compare case-insensitive；可用
DESIGN_LAB_HOST_ALLOWLIST 覆寫。
Failure mode：
/design 的 auto-spawn 失敗 → design.sh fail soft，bridge fallback 到 no-memory generation，CLI design 繼續。- Dashboard CSR fetch 遇 401 → reload once，讓 SSR 讀新 token 後重試；成功 200 後清 reload flag。
- Fork bridge skill sidecar down、token 讀不到、non-2xx 或 retry 後仍 401 → fallback no-memory，不 fail hard。
環境變數
DESIGN_LAB_VAULT_PATH：default $HOME/Documents/CC Cli/design-libraryDESIGN_LAB_STATE_PATH：default $HOME/.claude/state/design-lab/（PID file + last-artifact.txt 等 transient state）DESIGN_LAB_API_TOKEN：sidecar write-route auth token；由 ensure-sidecar.sh cold spawn 自動生成並 export，不需 user 手動設定DESIGN_LAB_HOST_ALLOWLIST：optional override，覆寫 sidecar API Host allowlist（逗號分隔）
開發 / 測試
npm test
npx tsc --noEmit
cd skill/dashboard
npm run build
npm run dev
bash skill/scripts/sidecar-start.sh
cd skill/dashboard
npx playwright install chromium
npx playwright test
v0.3 已知限制 / v0.4 backlog
- E2E specs 部分 selector 待修（不擋 phase tag）
- bridge skill 已寫於 open-design fork（commit
101f2d3）；現為盲轉 JSON、語意注入保真度待提升。日常主消費者改為 ace hermes 經 MCP server（見 docs/adr/0002）
- v0.4：Global Search FTS5、Feedback log UI、自動 distill、LLM NEVER detector、URL 截圖
- v0.4+：SaaS 化（multi-tenant、auth、cloud sidecar）
