{"type":"system","subtype":"hook_started","hook_id":"66766bc9-51b0-4fd5-83ea-44677172f205","hook_name":"SessionStart:startup","hook_event":"SessionStart","uuid":"97c4cd8b-9243-4e72-8183-a56f438e9cbf","session_id":"ccca31c3-4a85-4094-9f46-4533df53f8ce"} {"type":"system","subtype":"hook_started","hook_id":"193b2bc2-511d-415c-a160-2be00a5ec43e","hook_name":"SessionStart:startup","hook_event":"SessionStart","uuid":"7c8772f1-58ef-4887-a844-ef256bd078d4","session_id":"ccca31c3-4a85-4094-9f46-4533df53f8ce"} {"type":"system","subtype":"hook_response","hook_id":"66766bc9-51b0-4fd5-83ea-44677172f205","hook_name":"SessionStart:startup","hook_event":"SessionStart","output":"{\"hookSpecificOutput\": {\"hookEventName\": \"SessionStart\", \"additionalContext\": \"⛔ MANDATORY ONBOARDING(两层;链路 SoT = docs/STATUS.md §起手必读链路)— 第一个**项目相关**回答 / 推荐 / 任务前必须完成。机制:用 TodoWrite 为 L-core 每项 + 命中的 L-ref 项各建 1 个 todo, 逐项 Read 完才能回答。\\n\\n【L-core — 全文必读, 禁 grep/跳读/摘要替代】\\n1. Read docs/FIGMA_AS_SOURCE_OF_TRUTH.md (⭐ 最高优先级 — Figma 真源原则)\\n2. Read docs/STATUS.md (项目状态 SoT + 链路 SoT — 含 L-ref 完整触发表)\\n3. Read docs/PROJECT_GOAL.md (项目目标 + 5 个能力 + 受众 + 约束)\\n4. Read docs/internal/_plans/next-session-pickup-2026-07-08-full-lifecycle-optimization.md (当前 sprint 操作手册)\\n\\n【L-ref — 最小集必读, 命中触发再深读(完整触发表在 STATUS §L-ref)】\\n- AGENTS.md §硬规则表 + §Onboarding Gate(每 session 最小集)\\n- 接手 sprint task → backlog.md 对应 entry **全文 Read 不是 grep**\\n- 排期/版本决策 → tracker 全读(最小集 = §排期原则)\\n- 写 prompt/设计机制 → meta-rules.md 反模式清单\\n- Mockup 任务 → AGENTS §Mockup Write Gate + §必读链路 7-10 整链 mandatory\\n\\n【⛔ 两条「绝对不能违反、但没有任何入口会主动告诉你」的规则 —— 它们不在 AGENTS §硬规则表里, 所以上面那条最小集覆盖不到】\\n1. **changeset 纪律**:本次改动若碰到 package.json 的 files[] 白名单内的资产 (src/** · src/tokens/** · 导出 index.ts · eslint-plugin/** · templates/** · 白名单内那批 scripts/), 必须在**同一个 commit** 里写 changeset (跑 pnpm changeset)。判据是「该文件在不在 files[] 里」, files[] 是唯一真源 (npm pack --dry-run 可查); 纯 docs/ tests/ playground/ react-pilot/ 不写。真源 = AGENTS.md §直 commit master 时:写 changeset(版本日志)。⚠️ CONTRIBUTING.md 此前反向教过「手改 CHANGELOG + 手改版本号」, 别照那个做。\\n2. **VISUAL_COMMIT_APPROVED**:docs 站视觉改动的 pre-commit 视觉门要这个环境变量才放行, 而 **AI 不得自设** —— 它的含义是「owner 看过实际效果并说出口了」, 自设等于伪造签核。合批只减少问几次, 不改变必须由 owner 说出口。真源 = AGENTS.md §docs 站内部 demo / 页面样式改动的快车道 条 2。\\n(这两条的发现路径此前只有「撞上 pre-commit 才知道」; 2026-08-17 [[INFRA-F125]] ① 把它们提到 SessionStart 注入面 —— 选 hook 而不是新建 skill, 因为 skill 靠唤醒词概率命中 = 要求使用者先懂流程, 而 hook 是 cwd 一进来就注入、零条件。)\\n\\n违反信号 (命中任一立即停下重读):\\n- L-core 没读完就回答 ('我已经知道大概了'/'跳一步') → 错\\n- L-core 或 backlog entry 用 grep/摘要替代全文 Read → 错\\n- 命中 L-ref 触发却只读标题/最小集 → 错\\n- 'memory 兜底替代 SoT' → 错 (memory 是 AI 缓存, 项目契约真源在仓库)\\n\\n例外1 (跳过): 用户首条 query 明显非项目相关 (如 '今天日期' / 闲聊 / 角色唤醒词)。\\n例外2 (减档 = 微改档, owner 2026-08-13 裁定): 改动是**单文件 + 纯文案/措辞 + 不换组件不改 token 不加删元素 + 非 mockup 写操作**时, L-core 减为 **#1 (FIGMA_AS_SOURCE_OF_TRUTH 全文) + AGENTS §硬规则表**, 省下 STATUS / PROJECT_GOAL / pickup 三份。⛔ 判据不确定就是不满足; 一旦发现要换组件 / 改 token / 加删元素 / 动第二个文件 / 触组件选型或 Figma 真源判断 → **当场停下补读完整 L-core 再继续**。判据与升级条件的唯一 SoT = docs/STATUS.md §微改档, 别照本行推测边界。\\n\\n两个例外的完整定义详见 docs/STATUS.md §起手必读链路 + AGENTS.md §Onboarding Gate。\\n\\n历史实证: 2026-05-13 session 10 跳过 PROJECT_GOAL + AGENTS → 首轮推荐缺 4 项硬约束 → 用户返工纠偏。\\n\\n⚠️ **⚠️ **探测失败**(CLAUDE_PROJECT_DIR 未设或不指向 git 仓库)—— 按 fail-closed 照发本段:**当作有并行 session****(owner 2026-08-13 裁定)。\\n- ⛔ **本 session 若要写任何仓库文件,起手就开 worktree**(走 `superpowers:using-git-worktrees`),别靠事后 pathspec 补救 —— 判据是「并行线在写代码吗」,**不是「我只出 .md 吗」**:纯 .md 一样会被别人的裸 commit 卷走。\\n- 那些 dirty/untracked 文件**先假设是别 session 进行中**,不主动消化、不替它们 commit。\\n- 若确实不开 worktree(只读任务 / owner 明示不开):commit 必须 `git commit -F -- <显式路径>`,且**提交后紧跟 `git reset -- <同样路径>`** 清幻影 staged。\\n- worktree 三坑:无 node_modules(symlink 主仓那份)· 无 dist-wc(`pnpm build:wc`)· husky 跑主仓 hooks。\"}}\n","stdout":"{\"hookSpecificOutput\": {\"hookEventName\": \"SessionStart\", \"additionalContext\": \"⛔ MANDATORY ONBOARDING(两层;链路 SoT = docs/STATUS.md §起手必读链路)— 第一个**项目相关**回答 / 推荐 / 任务前必须完成。机制:用 TodoWrite 为 L-core 每项 + 命中的 L-ref 项各建 1 个 todo, 逐项 Read 完才能回答。\\n\\n【L-core — 全文必读, 禁 grep/跳读/摘要替代】\\n1. Read docs/FIGMA_AS_SOURCE_OF_TRUTH.md (⭐ 最高优先级 — Figma 真源原则)\\n2. Read docs/STATUS.md (项目状态 SoT + 链路 SoT — 含 L-ref 完整触发表)\\n3. Read docs/PROJECT_GOAL.md (项目目标 + 5 个能力 + 受众 + 约束)\\n4. Read docs/internal/_plans/next-session-pickup-2026-07-08-full-lifecycle-optimization.md (当前 sprint 操作手册)\\n\\n【L-ref — 最小集必读, 命中触发再深读(完整触发表在 STATUS §L-ref)】\\n- AGENTS.md §硬规则表 + §Onboarding Gate(每 session 最小集)\\n- 接手 sprint task → backlog.md 对应 entry **全文 Read 不是 grep**\\n- 排期/版本决策 → tracker 全读(最小集 = §排期原则)\\n- 写 prompt/设计机制 → meta-rules.md 反模式清单\\n- Mockup 任务 → AGENTS §Mockup Write Gate + §必读链路 7-10 整链 mandatory\\n\\n【⛔ 两条「绝对不能违反、但没有任何入口会主动告诉你」的规则 —— 它们不在 AGENTS §硬规则表里, 所以上面那条最小集覆盖不到】\\n1. **changeset 纪律**:本次改动若碰到 package.json 的 files[] 白名单内的资产 (src/** · src/tokens/** · 导出 index.ts · eslint-plugin/** · templates/** · 白名单内那批 scripts/), 必须在**同一个 commit** 里写 changeset (跑 pnpm changeset)。判据是「该文件在不在 files[] 里」, files[] 是唯一真源 (npm pack --dry-run 可查); 纯 docs/ tests/ playground/ react-pilot/ 不写。真源 = AGENTS.md §直 commit master 时:写 changeset(版本日志)。⚠️ CONTRIBUTING.md 此前反向教过「手改 CHANGELOG + 手改版本号」, 别照那个做。\\n2. **VISUAL_COMMIT_APPROVED**:docs 站视觉改动的 pre-commit 视觉门要这个环境变量才放行, 而 **AI 不得自设** —— 它的含义是「owner 看过实际效果并说出口了」, 自设等于伪造签核。合批只减少问几次, 不改变必须由 owner 说出口。真源 = AGENTS.md §docs 站内部 demo / 页面样式改动的快车道 条 2。\\n(这两条的发现路径此前只有「撞上 pre-commit 才知道」; 2026-08-17 [[INFRA-F125]] ① 把它们提到 SessionStart 注入面 —— 选 hook 而不是新建 skill, 因为 skill 靠唤醒词概率命中 = 要求使用者先懂流程, 而 hook 是 cwd 一进来就注入、零条件。)\\n\\n违反信号 (命中任一立即停下重读):\\n- L-core 没读完就回答 ('我已经知道大概了'/'跳一步') → 错\\n- L-core 或 backlog entry 用 grep/摘要替代全文 Read → 错\\n- 命中 L-ref 触发却只读标题/最小集 → 错\\n- 'memory 兜底替代 SoT' → 错 (memory 是 AI 缓存, 项目契约真源在仓库)\\n\\n例外1 (跳过): 用户首条 query 明显非项目相关 (如 '今天日期' / 闲聊 / 角色唤醒词)。\\n例外2 (减档 = 微改档, owner 2026-08-13 裁定): 改动是**单文件 + 纯文案/措辞 + 不换组件不改 token 不加删元素 + 非 mockup 写操作**时, L-core 减为 **#1 (FIGMA_AS_SOURCE_OF_TRUTH 全文) + AGENTS §硬规则表**, 省下 STATUS / PROJECT_GOAL / pickup 三份。⛔ 判据不确定就是不满足; 一旦发现要换组件 / 改 token / 加删元素 / 动第二个文件 / 触组件选型或 Figma 真源判断 → **当场停下补读完整 L-core 再继续**。判据与升级条件的唯一 SoT = docs/STATUS.md §微改档, 别照本行推测边界。\\n\\n两个例外的完整定义详见 docs/STATUS.md §起手必读链路 + AGENTS.md §Onboarding Gate。\\n\\n历史实证: 2026-05-13 session 10 跳过 PROJECT_GOAL + AGENTS → 首轮推荐缺 4 项硬约束 → 用户返工纠偏。\\n\\n⚠️ **⚠️ **探测失败**(CLAUDE_PROJECT_DIR 未设或不指向 git 仓库)—— 按 fail-closed 照发本段:**当作有并行 session****(owner 2026-08-13 裁定)。\\n- ⛔ **本 session 若要写任何仓库文件,起手就开 worktree**(走 `superpowers:using-git-worktrees`),别靠事后 pathspec 补救 —— 判据是「并行线在写代码吗」,**不是「我只出 .md 吗」**:纯 .md 一样会被别人的裸 commit 卷走。\\n- 那些 dirty/untracked 文件**先假设是别 session 进行中**,不主动消化、不替它们 commit。\\n- 若确实不开 worktree(只读任务 / owner 明示不开):commit 必须 `git commit -F -- <显式路径>`,且**提交后紧跟 `git reset -- <同样路径>`** 清幻影 staged。\\n- worktree 三坑:无 node_modules(symlink 主仓那份)· 无 dist-wc(`pnpm build:wc`)· husky 跑主仓 hooks。\"}}\n","stderr":"","exit_code":0,"outcome":"success","uuid":"b443558e-adb1-4e80-89d5-d302d9c3dfe1","session_id":"ccca31c3-4a85-4094-9f46-4533df53f8ce"} {"type":"system","subtype":"hook_response","hook_id":"193b2bc2-511d-415c-a160-2be00a5ec43e","hook_name":"SessionStart:startup","hook_event":"SessionStart","output":"{\n \"hookSpecificOutput\": {\n \"hookEventName\": \"SessionStart\",\n \"additionalContext\": \"\\nYou have superpowers.\\n\\n**Below is the full content of your 'superpowers:using-superpowers' skill - your introduction to using skills. For all other skills, use the 'Skill' tool:**\\n\\n---\\nname: using-superpowers\\ndescription: Use when starting any conversation - establishes how to find and use skills, requiring skill invocation before ANY response including clarifying questions\\n---\\n\\n\\nIf you were dispatched as a subagent to execute a specific task, ignore this skill.\\n\\n\\n\\nIf you think there is even a 1% chance a skill might apply to what you are doing, you ABSOLUTELY MUST invoke the skill.\\n\\nIF A SKILL APPLIES TO YOUR TASK, YOU DO NOT HAVE A CHOICE. YOU MUST USE IT.\\n\\nThis is not negotiable. You cannot rationalize your way out of this.\\n\\n\\n## The Rule\\n\\n**Invoke relevant or requested skills BEFORE any response or action** — including clarifying questions, exploring the codebase, or checking files. If it turns out wrong for the situation, you don't have to use it.\\n\\n**Before entering plan mode:** if you haven't already brainstormed, invoke the brainstorming skill first.\\n\\nThen announce \\\"Using [skill] to [purpose]\\\" and follow the skill exactly. If it has a checklist, create a todo per item.\\n\\n## Skill Priority\\n\\nWhen multiple skills apply, process skills come first — they set the approach, then implementation skills (frontend-design, etc.) carry it out. Brainstorming and systematic-debugging are Superpowers' most common process skills, but the rule holds for any of them.\\n\\n- \\\"Let's build X\\\" → superpowers:brainstorming first, then implementation skills.\\n- \\\"Fix this bug\\\" → superpowers:systematic-debugging first, then domain skills.\\n\\n## Red Flags\\n\\nThese thoughts mean STOP—you're rationalizing:\\n\\n| Thought | Reality |\\n|---------|---------|\\n| \\\"This is just a simple question\\\" | Questions are tasks. Check for skills. |\\n| \\\"I need more context first\\\" | Skill check comes BEFORE clarifying questions. |\\n| \\\"Let me explore the codebase first\\\" | Skills tell you HOW to explore. Check first. |\\n| \\\"I can check git/files quickly\\\" | Files lack conversation context. Check for skills. |\\n| \\\"Let me gather information first\\\" | Skills tell you HOW to gather information. |\\n| \\\"This doesn't need a formal skill\\\" | If a skill exists, use it. |\\n| \\\"I remember this skill\\\" | Skills evolve. Read current version. |\\n| \\\"This doesn't count as a task\\\" | Action = task. Check for skills. |\\n| \\\"The skill is overkill\\\" | Simple things become complex. Use it. |\\n| \\\"I'll just do this one thing first\\\" | Check BEFORE doing anything. |\\n| \\\"This feels productive\\\" | Undisciplined action wastes time. Skills prevent this. |\\n| \\\"I know what that means\\\" | Knowing the concept ≠ using the skill. Invoke it. |\\n\\n## Platform Adaptation\\n\\nIf your harness appears here, read its reference file for special instructions:\\n\\n- Codex: `references/codex-tools.md`\\n- Pi: `references/pi-tools.md`\\n- Antigravity: `references/antigravity-tools.md`\\n- Hermes Agent: `references/hermes-tools.md`\\n\\n## User Instructions\\n\\nUser instructions (CLAUDE.md, AGENTS.md, GEMINI.md, etc, direct requests) take precedence over skills, which in turn override default behavior. Only skip skill workflows or instructions when your human partner has explicitly told you to.\\n\"\n }\n}\n","stdout":"{\n \"hookSpecificOutput\": {\n \"hookEventName\": \"SessionStart\",\n \"additionalContext\": \"\\nYou have superpowers.\\n\\n**Below is the full content of your 'superpowers:using-superpowers' skill - your introduction to using skills. For all other skills, use the 'Skill' tool:**\\n\\n---\\nname: using-superpowers\\ndescription: Use when starting any conversation - establishes how to find and use skills, requiring skill invocation before ANY response including clarifying questions\\n---\\n\\n\\nIf you were dispatched as a subagent to execute a specific task, ignore this skill.\\n\\n\\n\\nIf you think there is even a 1% chance a skill might apply to what you are doing, you ABSOLUTELY MUST invoke the skill.\\n\\nIF A SKILL APPLIES TO YOUR TASK, YOU DO NOT HAVE A CHOICE. YOU MUST USE IT.\\n\\nThis is not negotiable. You cannot rationalize your way out of this.\\n\\n\\n## The Rule\\n\\n**Invoke relevant or requested skills BEFORE any response or action** — including clarifying questions, exploring the codebase, or checking files. If it turns out wrong for the situation, you don't have to use it.\\n\\n**Before entering plan mode:** if you haven't already brainstormed, invoke the brainstorming skill first.\\n\\nThen announce \\\"Using [skill] to [purpose]\\\" and follow the skill exactly. If it has a checklist, create a todo per item.\\n\\n## Skill Priority\\n\\nWhen multiple skills apply, process skills come first — they set the approach, then implementation skills (frontend-design, etc.) carry it out. Brainstorming and systematic-debugging are Superpowers' most common process skills, but the rule holds for any of them.\\n\\n- \\\"Let's build X\\\" → superpowers:brainstorming first, then implementation skills.\\n- \\\"Fix this bug\\\" → superpowers:systematic-debugging first, then domain skills.\\n\\n## Red Flags\\n\\nThese thoughts mean STOP—you're rationalizing:\\n\\n| Thought | Reality |\\n|---------|---------|\\n| \\\"This is just a simple question\\\" | Questions are tasks. Check for skills. |\\n| \\\"I need more context first\\\" | Skill check comes BEFORE clarifying questions. |\\n| \\\"Let me explore the codebase first\\\" | Skills tell you HOW to explore. Check first. |\\n| \\\"I can check git/files quickly\\\" | Files lack conversation context. Check for skills. |\\n| \\\"Let me gather information first\\\" | Skills tell you HOW to gather information. |\\n| \\\"This doesn't need a formal skill\\\" | If a skill exists, use it. |\\n| \\\"I remember this skill\\\" | Skills evolve. Read current version. |\\n| \\\"This doesn't count as a task\\\" | Action = task. Check for skills. |\\n| \\\"The skill is overkill\\\" | Simple things become complex. Use it. |\\n| \\\"I'll just do this one thing first\\\" | Check BEFORE doing anything. |\\n| \\\"This feels productive\\\" | Undisciplined action wastes time. Skills prevent this. |\\n| \\\"I know what that means\\\" | Knowing the concept ≠ using the skill. Invoke it. |\\n\\n## Platform Adaptation\\n\\nIf your harness appears here, read its reference file for special instructions:\\n\\n- Codex: `references/codex-tools.md`\\n- Pi: `references/pi-tools.md`\\n- Antigravity: `references/antigravity-tools.md`\\n- Hermes Agent: `references/hermes-tools.md`\\n\\n## User Instructions\\n\\nUser instructions (CLAUDE.md, AGENTS.md, GEMINI.md, etc, direct requests) take precedence over skills, which in turn override default behavior. Only skip skill workflows or instructions when your human partner has explicitly told you to.\\n\"\n }\n}\n","stderr":"","exit_code":0,"outcome":"success","uuid":"872a1fd7-54dc-4498-97aa-4329ac018715","session_id":"ccca31c3-4a85-4094-9f46-4533df53f8ce"} {"type":"system","subtype":"init","cwd":"/Users/nancy/.ai-ds-lab/pins/tvu-ds-4a68e02d","session_id":"ccca31c3-4a85-4094-9f46-4533df53f8ce","tools":["Task","Artifact","CronCreate","CronDelete","CronList","DesignSync","EnterWorktree","ExitWorktree","Glob","Grep","ListAgents","Monitor","PushNotification","Read","RemoteTrigger","ReportFindings","ScheduleWakeup","SendMessage","ShareOnboardingGuide","Skill","TaskOutput","TaskStop","ToolSearch","WebFetch","WebSearch","Workflow"],"mcp_servers":[],"model":"claude-opus-5","permissionMode":"acceptEdits","slash_commands":["daily-report","monthly-summary","role-english-teacher","role-translator","role-ux","setup-tvu-consumer","shared-vocab-rules","deep-research","frontend-design:frontend-design","figma:figma-code-connect","figma:figma-create-new-file","figma:figma-design-to-code","figma:figma-generate-design","figma:figma-generate-diagram","figma:figma-generate-library","figma:figma-implement-motion","figma:figma-swiftui","figma:figma-use","figma:figma-use-figjam","figma:figma-use-motion","figma:figma-use-slides","superpowers:brainstorming","superpowers:dispatching-parallel-agents","superpowers:executing-plans","superpowers:finishing-a-development-branch","superpowers:receiving-code-review","superpowers:requesting-code-review","superpowers:subagent-driven-development","superpowers:systematic-debugging","superpowers:test-driven-development","superpowers:using-git-worktrees","superpowers:using-superpowers","superpowers:verification-before-completion","superpowers:writing-plans","superpowers:writing-skills","design","design-sync","dataviz","artifact-design","artifact-diagramming","artifact-capabilities","update-config","verify","debug","code-review","simplify","batch","fewer-permission-prompts","doctor","loop","schedule","claude-api","run","run-skill-generator","agents","auto-mode-setup","autocompact","clear","color","compact","config","context","effort","fast","heapdump","init","mcp","import","model","__remote-workflow","workflow-launch-exec","reload-skills","rename","security-review","usage-credits","extra-usage","usage","insights","recap","goal","design-consent","design-revoke","list-agents","team-onboarding"],"terminal_slash_commands":["doctor","color"],"apiKeySource":"none","claude_code_version":"2.1.241","output_style":"default","agents":["affordance-search","claude","claude-code-guide","design-review","Explore","general-purpose","Plan","statusline-setup"],"skills":["daily-report","monthly-summary","role-english-teacher","role-translator","role-ux","setup-tvu-consumer","shared-vocab-rules","deep-research","frontend-design:frontend-design","figma:figma-code-connect","figma:figma-create-new-file","figma:figma-design-to-code","figma:figma-generate-design","figma:figma-generate-diagram","figma:figma-generate-library","figma:figma-implement-motion","figma:figma-swiftui","figma:figma-use","figma:figma-use-figjam","figma:figma-use-motion","figma:figma-use-slides","superpowers:brainstorming","superpowers:dispatching-parallel-agents","superpowers:executing-plans","superpowers:finishing-a-development-branch","superpowers:receiving-code-review","superpowers:requesting-code-review","superpowers:subagent-driven-development","superpowers:systematic-debugging","superpowers:test-driven-development","superpowers:using-git-worktrees","superpowers:using-superpowers","superpowers:verification-before-completion","superpowers:writing-plans","superpowers:writing-skills","design","design-sync","dataviz","artifact-design","artifact-diagramming","artifact-capabilities","update-config","verify","debug","code-review","simplify","batch","fewer-permission-prompts","doctor","loop","schedule","claude-api","run","run-skill-generator"],"plugins":[{"name":"frontend-design","path":"/Users/nancy/.claude/plugins/cache/claude-plugins-official/frontend-design/unknown","source":"frontend-design@claude-plugins-official"},{"name":"figma","path":"/Users/nancy/.claude/plugins/cache/claude-plugins-official/figma/2.2.96","source":"figma@claude-plugins-official","version":"2.2.96"},{"name":"superpowers","path":"/Users/nancy/.claude/plugins/cache/claude-plugins-official/superpowers/6.3.0","source":"superpowers@claude-plugins-official","version":"6.3.0"},{"name":"superpowers","path":"/Users/nancy/.claude/plugins/cache/superpowers-marketplace/superpowers/6.0.3","source":"superpowers@superpowers-marketplace","version":"6.0.3"}],"capabilities":["interrupt_receipt_v1","interrupt_cancel_queued_v1","msg_lifecycle_v1"],"analytics_disabled":false,"product_feedback_disabled":false,"uuid":"ea8824ac-9482-413c-862f-8932fa2a09dd","memory_paths":{"auto":"/Users/nancy/.claude/projects/-Users-nancy-Documents-AICoding-VS-Code-tvu-design-system/memory/"},"messaging_socket_path":"/tmp/cc-socks/13752.sock","fast_mode_state":"off"} {"type":"system","subtype":"thinking_tokens","estimated_tokens":50,"estimated_tokens_delta":50,"uuid":"67a68fab-db63-4287-952c-47c755bf34f9","session_id":"ccca31c3-4a85-4094-9f46-4533df53f8ce"} {"type":"system","subtype":"thinking_tokens","estimated_tokens":150,"estimated_tokens_delta":100,"uuid":"75729d16-3dd1-437e-b7d9-b5c41a9b0fa0","session_id":"ccca31c3-4a85-4094-9f46-4533df53f8ce"} {"type":"system","subtype":"thinking_tokens","estimated_tokens":250,"estimated_tokens_delta":100,"uuid":"730220df-69d5-4bf3-83d5-2b187a4351e8","session_id":"ccca31c3-4a85-4094-9f46-4533df53f8ce"} {"type":"system","subtype":"thinking_tokens","estimated_tokens":450,"estimated_tokens_delta":200,"uuid":"2d735413-9a18-4a37-9f18-0652c03fa07b","session_id":"ccca31c3-4a85-4094-9f46-4533df53f8ce"} {"type":"system","subtype":"thinking_tokens","estimated_tokens":600,"estimated_tokens_delta":150,"uuid":"c7c3d036-12c0-40fb-b5a6-78d7112f0d98","session_id":"ccca31c3-4a85-4094-9f46-4533df53f8ce"} {"type":"system","subtype":"thinking_tokens","estimated_tokens":700,"estimated_tokens_delta":100,"uuid":"70673f54-2691-4f57-8e75-4ce4a2b18d1e","session_id":"ccca31c3-4a85-4094-9f46-4533df53f8ce"} {"type":"system","subtype":"thinking_tokens","estimated_tokens":800,"estimated_tokens_delta":100,"uuid":"d88cd45c-baf4-4c67-acff-18c4bd54aebe","session_id":"ccca31c3-4a85-4094-9f46-4533df53f8ce"} {"type":"system","subtype":"thinking_tokens","estimated_tokens":900,"estimated_tokens_delta":100,"uuid":"904ae10d-8a08-4e22-9314-d09bf953f776","session_id":"ccca31c3-4a85-4094-9f46-4533df53f8ce"} {"type":"system","subtype":"thinking_tokens","estimated_tokens":1000,"estimated_tokens_delta":100,"uuid":"20674811-939b-4548-badb-5e3da4010e9f","session_id":"ccca31c3-4a85-4094-9f46-4533df53f8ce"} {"type":"assistant","message":{"model":"claude-opus-5","id":"msg_011CePDjh9nSri5YdKAs8Yff","type":"message","role":"assistant","content":[{"type":"thinking","thinking":"","signature":"CAIS4xYKpgEIERgCKkBpOlDbPfoW34oERJ937f6Cb3KIrRBvd+5Ot7iLAMktGQqVVhO2wEWMdcWEO6RjPo1RQPCjXNtTyQHRzTo+N+atMg1jbGF1ZGUtb3B1cy01OAFCCHRoaW5raW5nWiRjODEyM2U4YS04YWI1LTRjMTAtOTI0NS03NzE5NWYwMDFmNWNyEBfgeyIqdf44HDNid5nifo2IAQGoAY29tdQGsAECEgyDUCc1PT1ioX+euL0aDNMpx/88IDWzAkQWnCIwvqyH31yibcy8sHGninl7A9iriT8np9OgIbnV6QPWwSACEz0p19GO8ayScto09INIKukUamTvANmnKhmld1yxsiCApDZIYOyGFv/qKG3R71OFyFgdyDSd575a+jdVM/ndYvuOPTX2uokEEBhbGAgcID7e5xbPGwTesJ09DV/MCk8p42w8iQGzDT31188LRHpTPonKSihGOSl2w0HoFLwxcycbQHwIP2Q8W1hW8f8pGhZ3rDzbYALQZmIhxXHDvTHj01his1bnIY1IQBCFUwBmjDD9QJB+3TStghQXgq8bLoLDFYxitUqtApZrOUihUy6daFBJVk5spVUkVyQi7D9Oz0yp04I7PSeCO2El7fgMTy4cUsUgl1yLysKEx1jx4MKN05adonzBqmAkkDkdrTCo0+T91X2HiBK+k/4A5fEQdkL4cMy4F92tkUM9zeVhjD8NajDJheaRG1hUJVyNOWj8qZt14Zp3Zh6RlHyTTJQ4EkBhFsMvl9a4LEcvI8oq8r7d2/PVevNPwDZKxDtAFV1nPMahe6c06vczDhQh77b3cv9m7JA5XU7vjAksqHMNABoNCchm7QSw+FuBPNfRlCuxE0RopXiJyB9RgzoSAFSJXhbiQs6Iw9/m4VVZ5Kkus8FEXaK0TsjphgVJMFHvy/CFTFgc+fh6ANLl36shtyhVLkeGgGbBymXGTDNCMM4ED0fbfCprMp0xlBpTXMKLhXnCpeJbaWYD7aRomy+sjk9WhD2uV5krIBAlmt7ZbwUDxLKDdqzzqMvMsyQpb5wPJW6jX+OMB9T0QRFheBRBUfKfrmIl5f6VTEpJw2XJHDegwWpY983mLDL3pjC/8vRuZzdDa0ofkYgGfVHn9UjyvY3VlR7QGlcO7f/Lj38CLFqavM8c3tvhQ2/Dy1uT+FHgihSEb+7LxIFvwNeAJOqCDp/J9kotbCzxY6j4VmNdblTLCVb74T2tWmi2ZElfrvoq4D6kVgEVjn6v00VpDovdE17Hrz/Dq+pp8pPe0PA2nBmZtypun+rEkOr0cl5Y1d68J0apCM3JM7R7dw1gKlZggdvecpLQp41CMxZPhPU+eRp/u3q84Ji45qvd8GNUyjKSA3sAeb0ZETYYWd2jbgYcpENz3Y90mNQ4h4B9FLWQSDA6Z7/2QeNK9tqNVJUjGxtwYQFBC8lgc3Tl1ZlOT+Z968hjwz9y8Vq8NTU9qw6IL51bN93edjv73vaWczR7ptxV4fXhPXUdqG7xjeb2dKpRq+tikzoGNHtoWhIN74ZBqnc6S6guQ3BWqjGG/O4jgAKCUNE2eT0S5O5DN5zmHns3tnNq6VpL4tf8os5dKt1+sFXTjmTTN3rO/baP7CEYhveLlKHJ8AKdytWj28D+YX7vEIXP6JhGasjWFjipfx2MfSPaR64hT4jY01IW5lbppT8qk3ilhIou9yj0EniXAQf3nmZI2hBTG2wP4X+mXPdf2tLTWUql2z2fxvCVaP4q12uUjE38lx2cv4ebcOEAuWGuDdNK5Lh9XvfsnKS7ufPDAASU8JmyIhoMWXzUGdeflacu5BTZ9f1M32iMRDpvQ8jTnWDdZuoAmTdYv86r0AmXiYhCSxXODOsYCAuWiAg3ALkgi3lNetUdi/lDYJWXySrTRJi6HURzzyHQsmjr/XZ6V2MOh/dU7UwVQGbLhIZ9byMjIpnumnNe/L+Umtft+HMx0S8Jn4lshCtULEpZZVDck7ZY/k7KedVRxhDIRnwllbUNLi1I2ilKGwwtWgWfGwMD4gPaN74j2p2l5/9Euov28ut/lhhB3283o1YKuQHWtvBbKcA/6ehlTQlsBI6uGweOld7PcSukUfhfi6cjiq8DHB7RiSAL7Uc9M/2tep4res6Fraq6F0/dy1tQykllxAtQLCvq7qPi3mypqoQy/DQ9wHGMDk2HvwHzluMzWyAud1rlZPhUVca3iwxIvUeakkHfKEhPFW670PO9Sn0I6H+0wGO4WWktXoRXBhFtuPoDwfZ6fZ2DycHSQ3CZxmHwxsVXX5McXQL1C/ebiX0ZeP5+aAbBqrOcMb+K1mLwcevmV+lQV3SBGMUur74TlWwqJsrR+Dv65GLgFFIDPMk9I0XUpq/yS5oUDqVXoco8XL+TjGv3qLMpqhMdlR3M+kqMppaMb5w4/8hReSbKQa5XAPoy57gsbKVAVIXOAit9FvIVhISUg/SECeL+4woGcgsh6rIKGM8B3MgE9E3zKp1OJ4hmS1UJMH4nhPeri1KYVJWf+emVs20P2mYClErDATzKaOopJlqXE4HdWEGucYFuennQhDlSC+v0sur0exzI+GZX5l1lwnD+F4NxhKHRgcDArZP273zm8HMCBvKqhtqH6hFVg0rRrOcuzk/Osg/jIpY6PQJdXkKX4qFf0OeP3h7SfUxEazUMLSTzPxjfeEPf9n4k/gkdNK2jTaFX7lJFM0PHLvjYJ0A7M02zJYnUNQwiYWOk2ZvpFFOBri7IfSis/WveHwVjVc3e0qEDM+pElkrDlvLX7PBLwtyeT420AAiIvL96L7RGrAP+iGwsXzSnxj7V7+IU6a1MY3NZCWoaLLIvMFCQIOIVEKzZGahoVOI44YZ4CjoB4gOBBboP6MuqjsXWyq8V+Xd+iZmI9RCA9uh4T8FIbsJ7Oty11aWelzh1fdeqldqEchMq77DQIHbg38PsyqsXi/FIEZSnQS/KYoGnmNCaTVCaK5Rba+x1K5rq2zp1weEVMvS4ypw8bU6p/+rCpwl6mJ+2nSUW8WqVRnfu9hsC8iWQ7xfZpIRTa9c3a5H+QMswIF2yS2FgaKOa9t8ERPMjKb1+njyEs20U01IbB6Wo29JhETHwhhaB6fqwPIsMAX569+aZrDX7TmYFzyGyhsafH5GeQt43z6eh5beQxhCI0oNGNkzZXgpp8cWSQ8M3PbaoGP3VfipbuorGZoNcCejFhSrpKpfxVgwOTEiHNhcrs1BLvijWcbsU37tK8OmGLvLFFNQnCOaRvV+4OG2sCeq5zqvi6prWEChQ78//CPl3SYIghKtoq8ap/87PYqNYEQWNUeKy49lnDBWxtuJn2QpEFAn5Yth++AURz8t2OJCLl01Udn9hMzmpnIuYQascK8+4vg/7CDchn6WvjMAHWWmPPhvq97XIyDnVJEpK9/aKutz0BSHeRxLtjDr+yG6y/PwsqJnLjc7ITAdFEl7ENcqsLHS7i2TyCgvO2dunudDQH5gmEyceYLv0HDQURjOkxSFdwhqbK3m89Ydn+pAwga3RN+hlRGn/gzdT8YjHoaL91TrOyUK69qf5LJzBKyNUA8DCSSjbomaivdrDB3Gv/jGe9BMSmVJxOvDggX0CNiNCoCzglUtPhnnq+NQgu3/oIURZSI1KeSxHtJOjTf5KNxYpKT2j62iPSwc8xFX+6sETBgYUEUPgVYszSCwl2HmlHGO/UerTdWkdz6zPiDxMVUQF79x61UZtZhDgRKPuPAbBSPSNXLrZ0QuLmqoLtYrio+UagZzMKGeSQKeddmRPDqesKeRedBtUBkML+5fAW9wCvLyn47hgAjYWdvi251xXDB2ZK5auT37bpRyAy+JoOAXr63SUI5O5FTGPo9qbAxeHg8J12coaiO6C1oWdooZtZRgB"}],"stop_reason":null,"stop_sequence":null,"stop_details":null,"usage":{"input_tokens":2,"cache_creation_input_tokens":59449,"cache_read_input_tokens":0,"cache_creation":{"ephemeral_5m_input_tokens":0,"ephemeral_1h_input_tokens":59449},"output_tokens":2,"service_tier":"standard","inference_geo":"not_available"},"diagnostics":null,"context_management":null},"parent_tool_use_id":null,"session_id":"ccca31c3-4a85-4094-9f46-4533df53f8ce","uuid":"8e46e622-04d0-4642-a84b-0f6af53ef448","timestamp":"2026-08-25T09:21:17.596Z","request_id":"req_011CePDje4VeFgvgyXui7jmj"} {"type":"assistant","message":{"model":"claude-opus-5","id":"msg_011CePDjh9nSri5YdKAs8Yff","type":"message","role":"assistant","content":[{"type":"text","text":"我先走完项目的强制 onboarding 链路(本 session 只读,Read 可用)。"}],"stop_reason":null,"stop_sequence":null,"stop_details":null,"usage":{"input_tokens":2,"cache_creation_input_tokens":59449,"cache_read_input_tokens":0,"cache_creation":{"ephemeral_5m_input_tokens":0,"ephemeral_1h_input_tokens":59449},"output_tokens":2,"service_tier":"standard","inference_geo":"not_available"},"diagnostics":null,"context_management":null},"parent_tool_use_id":null,"session_id":"ccca31c3-4a85-4094-9f46-4533df53f8ce","uuid":"92190039-ea74-49de-97c8-2e25d0b57bfe","timestamp":"2026-08-25T09:21:18.484Z","request_id":"req_011CePDje4VeFgvgyXui7jmj"} {"type":"assistant","message":{"model":"claude-opus-5","id":"msg_011CePDjh9nSri5YdKAs8Yff","type":"message","role":"assistant","content":[{"type":"tool_use","id":"toolu_01N8nHG1PP3hwecyk45DXeGV","name":"Read","input":{"file_path":"/Users/nancy/.ai-ds-lab/pins/tvu-ds-4a68e02d/docs/FIGMA_AS_SOURCE_OF_TRUTH.md"},"caller":{"type":"direct"}}],"stop_reason":null,"stop_sequence":null,"stop_details":null,"usage":{"input_tokens":2,"cache_creation_input_tokens":59449,"cache_read_input_tokens":0,"cache_creation":{"ephemeral_5m_input_tokens":0,"ephemeral_1h_input_tokens":59449},"output_tokens":2,"service_tier":"standard","inference_geo":"not_available"},"diagnostics":null,"context_management":null},"parent_tool_use_id":null,"session_id":"ccca31c3-4a85-4094-9f46-4533df53f8ce","uuid":"a1d1255d-4cbe-4390-be7b-0c139c402638","timestamp":"2026-08-25T09:21:19.731Z","request_id":"req_011CePDje4VeFgvgyXui7jmj"} {"type":"user","message":{"role":"user","content":[{"tool_use_id":"toolu_01N8nHG1PP3hwecyk45DXeGV","type":"tool_result","content":"1\t# Figma 是真源(Figma as Source of Truth)\n2\t\n3\t> **适用对象**:任何在本仓库工作的 AI 工具(Claude Code / Codex / Cursor / 其他)/ 开发 / 设计师。\n4\t> **优先级**:**高于** working-principles 任何条款;高于本文件之外的所有规则。\n5\t> **触发时机**:起手必读链路**第 0 步**——比 [`PROJECT_GOAL.md`](./PROJECT_GOAL.md) 还要先读。\n6\t> **历史背景**:2026-05-20 session 实证:纯静态 audit + 启发式 selector 匹配在一连串 finding 分类 / fix prompt 上产生 5 次错估错分,迫使本文件诞生。\n7\t\n8\t---\n9\t\n10\t## 唯一原则\n11\t\n12\t**Figma 设计系统库是真源。Code 组件必须 1:1 还原 Figma 组件的所有视觉属性(Color / Padding / Size / Radius / Opacity / Gap / Border / etc.)。**\n13\t\n14\t唯一允许的\"差异\"是**值形态映射**:Figma 端有些属性写的是 raw hex / px 字面量没走 Variable token;代码层用 token 变量去引用这些值,这是合法的映射层——**视觉等价**,命名形态不同。\n15\t\n16\t例:\n17\t- Figma 节点 fill 写 `#F0F0F0`(raw hex)↔ code `var(--color-grey-3)`(token 引用)—— **合法映射**,视觉等价\n18\t- Figma 节点 fill 绑 `UX/Grey/grey-3` (Variable) ↔ code `var(--color-grey-3)` —— **完美一致**\n19\t- Figma 节点 padding 写 `12px`(raw num)↔ code `padding: var(--sp-sm)` 其中 `--sp-sm: 12px` —— **合法映射**\n20\t\n21\t非例:\n22\t- Figma fill `#F0F0F0` ↔ code `var(--bg-layer4)`(其值是 `#dbdbdb`)—— **❌ 非法**,视觉不等价(这是 2026-05-19 select-chip 案例)\n23\t\n24\t---\n25\t\n26\t## 不允许的差异(违反 = code bug,不是 design choice)\n27\t\n28\t| ❌ 反模式 | 历史案例 |\n29\t|---|---|\n30\t| Code 用 Figma 没绑的 token | `.select-chip background: var(--bg-layer4)` 但 Figma 绑 `--color-grey-3` |\n31\t| Code 用 CSS 技巧替代 Figma 具体设计 | `.tvu-input:disabled { opacity: 0.4 }` 但 Figma 用 token desaturation (`--text-disabled` / `--control-disabled-*`) |\n32\t| Padding / gap / size / radius / opacity 跟 Figma variant 数值不一致 | `.select-chip gap: 4px` 但 Figma 8px;`.dropdown-select width: 240` 但 Figma L variant 300 |\n33\t| Code 自创 status / variant axis 不在 Figma 库里 | 已删除的 `notification.status=\"success\"` / `notification.type` / `badge.type` 形状轴 |\n34\t| Code 用 status-aspirational selector 但 Figma 实际绑别的 | `.select-wrap--error` 强行用 `--red`,但 Figma 在 error variant 实际绑 grey —— **fix code 跟 Figma,不是要求 Figma 改** |\n35\t\n36\t---\n37\t\n38\t## 合法的\"差异\"边界(**允许**,且必须显式登记到 [`src/design-system/translation/divergences-decisions.json`](../src/design-system/translation/divergences-decisions.json))\n39\t\n40\t| ✅ 合法 | 性质 | 例子 |\n41\t|---|---|---|\n42\t| 值形态映射 | 视觉等价,命名形态不同 | Figma raw `#F0F0F0` ↔ code `var(--color-grey-3)` |\n43\t| 拓扑合成 | code 提供合成层包多个 Figma 单元 | button 8-set → 一个 canonical + 8 axis prop(`button-eight-sets-single-component`)|\n44\t| Figma 设计态 vs 运行态 | Figma axis 是设计预览开关不是 runtime prop | `dark theme=on/off` / `enable` / `UX` 等已登记的 design-state axes |\n45\t| Figma SLOT ↔ Vue slot | API 形态技术不可达 1:1 | `figma-content-slot-vue-slot` |\n46\t| Figma export 工具限制 | Figma API 自身限制 | `icon-variable-resolved-to-hex` (SVG export 把 Variable 解析为 hex) |\n47\t| 用户显式 code-first 拍板 | 项目方向变化,code 走在 Figma 前面 | `chart-color-palette-2026-05-13` / `pill-component-family-2026-05-19` —— **必须**含 \"user approved code-first YYYY-MM-DD\" 注释 |\n48\t\n49\t任何不属于上面 6 条的\"差异\"想登记 divergence ——**stop,重新分析,默认结论是 code bug 按 Figma fix**。\n50\t\n51\t---\n52\t\n53\t## 验证方法(**不允许启发式**)\n54\t\n55\t任何 Figma↔code 验证必须 **deterministic**:\n56\t\n57\t### 推荐机制(manifest-based render verification)\n58\t\n59\t1. 显式 manifest:`figma-data/render-verification-manifest.json`,每条 entry 是 (Figma nodeId, codeComponent, codeProps) 的 1:1 映射\n60\t2. Render harness:docs site 内 `/internal/render-harness/*` 路由按 manifest 渲染每个 variant 孤立实例\n61\t3. Playwright 跑 manifest:逐项 `getComputedStyle()` vs Figma extract 数值精确比较\n62\t4. 输出 per-variant PASS / FAIL(actual vs expected 数值)\n63\t\n64\t### 禁止做法\n65\t\n66\t| ❌ 禁止 | 理由 |\n67\t|---|---|\n68\t| 静态 selector-to-variant BEM 启发式匹配 | 实证假阳率 ≥40%(2026-05-20 session)|\n69\t| 凭 selector 名字字面 (`--error` / `--checked` / `--disabled`) 推 variant 含义 | selector 名字是 code 意图,不是 Figma 真源 |\n70\t| 把 audit finding \"Figma 端不对\" 默认结论为 designer漏标 | 默认是 code 错;designer 漂移需要 designer **明确 ack** |\n71\t| 把\"实现策略差异\"(如 CSS opacity vs token desaturation)登记为 divergence | 实现策略差 = code 偷懒;按 Figma 改 |\n72\t\n73\t---\n74\t\n75\t## AI 工具自检清单(起手必读第 0 步)\n76\t\n77\t在写任何 audit / fix prompt 前,AI 必须确认:\n78\t\n79\t- [ ] 我的 finding 是 deterministic 来源(manifest-based),还是启发式推断?\n80\t- [ ] 我是否在\"猜\" selector 跟哪个 variant 对应?如果是 → **STOP**,重写为 manifest 查表\n81\t- [ ] 我提议的 fix 方向是 code → 跟 Figma,还是 Figma → 跟 code?如果是后者 → 需要设计师 ack,否则默认 code fix\n82\t- [ ] 我登记的 divergence 是否落在上面 6 条合法边界内?如果不是 → 不要登记,按 Figma fix code\n83\t- [ ] 我对\"X-axis cleavage\"/\"100% same binding\"等批量结论是不是验证过**全数据**?还是只看了一部分子集就外推?\n84\t\n85\t任一项打 No → **STOP,重新设计**。\n86\t\n87\t---\n88\t\n89\t## 设计师自检清单(review Figma 真源时)\n90\t\n91\t设计师/用户在 Figma 端发现 binding 看起来不符合直觉(如 error 边框绑 grey 不是 red)时:\n92\t\n93\t- [ ] **默认假设**:Figma 当前 binding 就是设计意图(code 应该 follow)\n94\t- [ ] 如果要\"改 Figma\"(认为 Figma 漂移了),明确 ack:在 git commit message / divergence-decisions entry 写 `designer-acknowledged-figma-fix-needed-YYYY-MM-DD`\n95\t- [ ] 改完 Figma 后跑 `pnpm sync:figma-library` 让 figma-data 同步,audit 自动消化\n96\t- [ ] 不做 ack 直接让 code 端逆向用 status token (如 `--red`/`--brand`) —— ❌ 违反原则\n97\t\n98\t---\n99\t\n100\t## 历史教训(避免再犯,session 2026-05-19/20 实证)\n101\t\n102\t| # | 错误 | 根因 |\n103\t|---|---|---|\n104\t| 1 | 误判 170 case A rebind(实际 38)| axis cleavage 分析只看了 12/126 数据子集就外推 |\n105\t| 2 | 误判 126 dropdown-disabled 同 binding(实际 11)| 同上 |\n106\t| 3 | P3 §Fix 3 改错方向(把对的 200 改成 240)| 读 triage `\"240 -> 200px\"` 文本箭头方向歧义 |\n107\t| 4 | 误把 56 条 figma-drift 归到\"设计师漏标\"| audit selector-to-variant 启发式把 `enable=off` disabled variant 套到 `.select-wrap--error` selector |\n108\t| 5 | 推荐用 divergence 登记 opacity strategy | 没核实 disabled token 已存在;CSS opacity 是 code 偷懒不是必要妥协 |\n109\t\n110\t**共同根因**:缺 deterministic manifest。机制不修,AI(任何工具任何模型)还会重复错。\n111\t\n112\t---\n113\t\n114\t## 文档关系\n115\t\n116\t| 文档 | 用途 |\n117\t|---|---|\n118\t| **本文件**(`FIGMA_AS_SOURCE_OF_TRUTH.md`) | 第 0 步原则——优先级最高 |\n119\t| [`AGENTS.md`](../AGENTS.md) | AI 协作硬规则(含起手必读链路索引)|\n120\t| [`docs/PROJECT_GOAL.md`](./PROJECT_GOAL.md) | 项目目标 / 受众 / 路线图 |\n121\t| [`docs/working-principles.md`](./working-principles.md) | 9 条工作原则(次于本文件) |\n122\t| [`src/design-system/translation/divergences-decisions.json`](../src/design-system/translation/divergences-decisions.json) | 合法 divergence 显式登记表 |\n123\t| [`figma-data/render-verification-manifest.json`](../figma-data/render-verification-manifest.json) | ✅ **已建**(INFRA-F41)deterministic 验证 manifest(936 entries,每条 = Figma nodeId ↔ codeComponent ↔ codeProps + expectedNodes);由 `pnpm test:render-verification` 跑、`pnpm audit:render-drift-gate` 闸 |\n124\t"}]},"parent_tool_use_id":null,"session_id":"ccca31c3-4a85-4094-9f46-4533df53f8ce","uuid":"63568402-3d0b-4b68-b8b3-6404eb0da1c8","timestamp":"2026-08-25T09:21:19.750Z","tool_use_result":{"type":"text","file":{"filePath":"/Users/nancy/.ai-ds-lab/pins/tvu-ds-4a68e02d/docs/FIGMA_AS_SOURCE_OF_TRUTH.md","content":"# Figma 是真源(Figma as Source of Truth)\n\n> **适用对象**:任何在本仓库工作的 AI 工具(Claude Code / Codex / Cursor / 其他)/ 开发 / 设计师。\n> **优先级**:**高于** working-principles 任何条款;高于本文件之外的所有规则。\n> **触发时机**:起手必读链路**第 0 步**——比 [`PROJECT_GOAL.md`](./PROJECT_GOAL.md) 还要先读。\n> **历史背景**:2026-05-20 session 实证:纯静态 audit + 启发式 selector 匹配在一连串 finding 分类 / fix prompt 上产生 5 次错估错分,迫使本文件诞生。\n\n---\n\n## 唯一原则\n\n**Figma 设计系统库是真源。Code 组件必须 1:1 还原 Figma 组件的所有视觉属性(Color / Padding / Size / Radius / Opacity / Gap / Border / etc.)。**\n\n唯一允许的\"差异\"是**值形态映射**:Figma 端有些属性写的是 raw hex / px 字面量没走 Variable token;代码层用 token 变量去引用这些值,这是合法的映射层——**视觉等价**,命名形态不同。\n\n例:\n- Figma 节点 fill 写 `#F0F0F0`(raw hex)↔ code `var(--color-grey-3)`(token 引用)—— **合法映射**,视觉等价\n- Figma 节点 fill 绑 `UX/Grey/grey-3` (Variable) ↔ code `var(--color-grey-3)` —— **完美一致**\n- Figma 节点 padding 写 `12px`(raw num)↔ code `padding: var(--sp-sm)` 其中 `--sp-sm: 12px` —— **合法映射**\n\n非例:\n- Figma fill `#F0F0F0` ↔ code `var(--bg-layer4)`(其值是 `#dbdbdb`)—— **❌ 非法**,视觉不等价(这是 2026-05-19 select-chip 案例)\n\n---\n\n## 不允许的差异(违反 = code bug,不是 design choice)\n\n| ❌ 反模式 | 历史案例 |\n|---|---|\n| Code 用 Figma 没绑的 token | `.select-chip background: var(--bg-layer4)` 但 Figma 绑 `--color-grey-3` |\n| Code 用 CSS 技巧替代 Figma 具体设计 | `.tvu-input:disabled { opacity: 0.4 }` 但 Figma 用 token desaturation (`--text-disabled` / `--control-disabled-*`) |\n| Padding / gap / size / radius / opacity 跟 Figma variant 数值不一致 | `.select-chip gap: 4px` 但 Figma 8px;`.dropdown-select width: 240` 但 Figma L variant 300 |\n| Code 自创 status / variant axis 不在 Figma 库里 | 已删除的 `notification.status=\"success\"` / `notification.type` / `badge.type` 形状轴 |\n| Code 用 status-aspirational selector 但 Figma 实际绑别的 | `.select-wrap--error` 强行用 `--red`,但 Figma 在 error variant 实际绑 grey —— **fix code 跟 Figma,不是要求 Figma 改** |\n\n---\n\n## 合法的\"差异\"边界(**允许**,且必须显式登记到 [`src/design-system/translation/divergences-decisions.json`](../src/design-system/translation/divergences-decisions.json))\n\n| ✅ 合法 | 性质 | 例子 |\n|---|---|---|\n| 值形态映射 | 视觉等价,命名形态不同 | Figma raw `#F0F0F0` ↔ code `var(--color-grey-3)` |\n| 拓扑合成 | code 提供合成层包多个 Figma 单元 | button 8-set → 一个 canonical + 8 axis prop(`button-eight-sets-single-component`)|\n| Figma 设计态 vs 运行态 | Figma axis 是设计预览开关不是 runtime prop | `dark theme=on/off` / `enable` / `UX` 等已登记的 design-state axes |\n| Figma SLOT ↔ Vue slot | API 形态技术不可达 1:1 | `figma-content-slot-vue-slot` |\n| Figma export 工具限制 | Figma API 自身限制 | `icon-variable-resolved-to-hex` (SVG export 把 Variable 解析为 hex) |\n| 用户显式 code-first 拍板 | 项目方向变化,code 走在 Figma 前面 | `chart-color-palette-2026-05-13` / `pill-component-family-2026-05-19` —— **必须**含 \"user approved code-first YYYY-MM-DD\" 注释 |\n\n任何不属于上面 6 条的\"差异\"想登记 divergence ——**stop,重新分析,默认结论是 code bug 按 Figma fix**。\n\n---\n\n## 验证方法(**不允许启发式**)\n\n任何 Figma↔code 验证必须 **deterministic**:\n\n### 推荐机制(manifest-based render verification)\n\n1. 显式 manifest:`figma-data/render-verification-manifest.json`,每条 entry 是 (Figma nodeId, codeComponent, codeProps) 的 1:1 映射\n2. Render harness:docs site 内 `/internal/render-harness/*` 路由按 manifest 渲染每个 variant 孤立实例\n3. Playwright 跑 manifest:逐项 `getComputedStyle()` vs Figma extract 数值精确比较\n4. 输出 per-variant PASS / FAIL(actual vs expected 数值)\n\n### 禁止做法\n\n| ❌ 禁止 | 理由 |\n|---|---|\n| 静态 selector-to-variant BEM 启发式匹配 | 实证假阳率 ≥40%(2026-05-20 session)|\n| 凭 selector 名字字面 (`--error` / `--checked` / `--disabled`) 推 variant 含义 | selector 名字是 code 意图,不是 Figma 真源 |\n| 把 audit finding \"Figma 端不对\" 默认结论为 designer漏标 | 默认是 code 错;designer 漂移需要 designer **明确 ack** |\n| 把\"实现策略差异\"(如 CSS opacity vs token desaturation)登记为 divergence | 实现策略差 = code 偷懒;按 Figma 改 |\n\n---\n\n## AI 工具自检清单(起手必读第 0 步)\n\n在写任何 audit / fix prompt 前,AI 必须确认:\n\n- [ ] 我的 finding 是 deterministic 来源(manifest-based),还是启发式推断?\n- [ ] 我是否在\"猜\" selector 跟哪个 variant 对应?如果是 → **STOP**,重写为 manifest 查表\n- [ ] 我提议的 fix 方向是 code → 跟 Figma,还是 Figma → 跟 code?如果是后者 → 需要设计师 ack,否则默认 code fix\n- [ ] 我登记的 divergence 是否落在上面 6 条合法边界内?如果不是 → 不要登记,按 Figma fix code\n- [ ] 我对\"X-axis cleavage\"/\"100% same binding\"等批量结论是不是验证过**全数据**?还是只看了一部分子集就外推?\n\n任一项打 No → **STOP,重新设计**。\n\n---\n\n## 设计师自检清单(review Figma 真源时)\n\n设计师/用户在 Figma 端发现 binding 看起来不符合直觉(如 error 边框绑 grey 不是 red)时:\n\n- [ ] **默认假设**:Figma 当前 binding 就是设计意图(code 应该 follow)\n- [ ] 如果要\"改 Figma\"(认为 Figma 漂移了),明确 ack:在 git commit message / divergence-decisions entry 写 `designer-acknowledged-figma-fix-needed-YYYY-MM-DD`\n- [ ] 改完 Figma 后跑 `pnpm sync:figma-library` 让 figma-data 同步,audit 自动消化\n- [ ] 不做 ack 直接让 code 端逆向用 status token (如 `--red`/`--brand`) —— ❌ 违反原则\n\n---\n\n## 历史教训(避免再犯,session 2026-05-19/20 实证)\n\n| # | 错误 | 根因 |\n|---|---|---|\n| 1 | 误判 170 case A rebind(实际 38)| axis cleavage 分析只看了 12/126 数据子集就外推 |\n| 2 | 误判 126 dropdown-disabled 同 binding(实际 11)| 同上 |\n| 3 | P3 §Fix 3 改错方向(把对的 200 改成 240)| 读 triage `\"240 -> 200px\"` 文本箭头方向歧义 |\n| 4 | 误把 56 条 figma-drift 归到\"设计师漏标\"| audit selector-to-variant 启发式把 `enable=off` disabled variant 套到 `.select-wrap--error` selector |\n| 5 | 推荐用 divergence 登记 opacity strategy | 没核实 disabled token 已存在;CSS opacity 是 code 偷懒不是必要妥协 |\n\n**共同根因**:缺 deterministic manifest。机制不修,AI(任何工具任何模型)还会重复错。\n\n---\n\n## 文档关系\n\n| 文档 | 用途 |\n|---|---|\n| **本文件**(`FIGMA_AS_SOURCE_OF_TRUTH.md`) | 第 0 步原则——优先级最高 |\n| [`AGENTS.md`](../AGENTS.md) | AI 协作硬规则(含起手必读链路索引)|\n| [`docs/PROJECT_GOAL.md`](./PROJECT_GOAL.md) | 项目目标 / 受众 / 路线图 |\n| [`docs/working-principles.md`](./working-principles.md) | 9 条工作原则(次于本文件) |\n| [`src/design-system/translation/divergences-decisions.json`](../src/design-system/translation/divergences-decisions.json) | 合法 divergence 显式登记表 |\n| [`figma-data/render-verification-manifest.json`](../figma-data/render-verification-manifest.json) | ✅ **已建**(INFRA-F41)deterministic 验证 manifest(936 entries,每条 = Figma nodeId ↔ codeComponent ↔ codeProps + expectedNodes);由 `pnpm test:render-verification` 跑、`pnpm audit:render-drift-gate` 闸 |\n","numLines":124,"startLine":1,"totalLines":124}}} {"type":"assistant","message":{"model":"claude-opus-5","id":"msg_011CePDjh9nSri5YdKAs8Yff","type":"message","role":"assistant","content":[{"type":"tool_use","id":"toolu_01GZ59NtY1Dwqg7XLGV8CEyY","name":"Read","input":{"file_path":"/Users/nancy/.ai-ds-lab/pins/tvu-ds-4a68e02d/docs/STATUS.md"},"caller":{"type":"direct"}}],"stop_reason":null,"stop_sequence":null,"stop_details":null,"usage":{"input_tokens":2,"cache_creation_input_tokens":59449,"cache_read_input_tokens":0,"cache_creation":{"ephemeral_5m_input_tokens":0,"ephemeral_1h_input_tokens":59449},"output_tokens":2,"service_tier":"standard","inference_geo":"not_available"},"diagnostics":null,"context_management":null},"parent_tool_use_id":null,"session_id":"ccca31c3-4a85-4094-9f46-4533df53f8ce","uuid":"3ae35da5-9af1-42fa-944d-da8e04d90dd3","timestamp":"2026-08-25T09:21:20.558Z","request_id":"req_011CePDje4VeFgvgyXui7jmj"} {"type":"assistant","message":{"model":"claude-opus-5","id":"msg_011CePDjh9nSri5YdKAs8Yff","type":"message","role":"assistant","content":[{"type":"tool_use","id":"toolu_019RTpCbS1GipD9p3nK1xXKG","name":"Read","input":{"file_path":"/Users/nancy/.ai-ds-lab/pins/tvu-ds-4a68e02d/docs/PROJECT_GOAL.md"},"caller":{"type":"direct"}}],"stop_reason":null,"stop_sequence":null,"stop_details":null,"usage":{"input_tokens":2,"cache_creation_input_tokens":59449,"cache_read_input_tokens":0,"cache_creation":{"ephemeral_5m_input_tokens":0,"ephemeral_1h_input_tokens":59449},"output_tokens":2,"service_tier":"standard","inference_geo":"not_available"},"diagnostics":null,"context_management":null},"parent_tool_use_id":null,"session_id":"ccca31c3-4a85-4094-9f46-4533df53f8ce","uuid":"8d6ccf9f-5e3c-4783-98d5-f56e12bac581","timestamp":"2026-08-25T09:21:21.240Z","request_id":"req_011CePDje4VeFgvgyXui7jmj"} {"type":"user","message":{"role":"user","content":[{"tool_use_id":"toolu_019RTpCbS1GipD9p3nK1xXKG","type":"tool_result","content":"1\t# TVU 设计系统 项目目标\n2\t\n3\t> 本文档是项目的最高指导原则。任何 AI 工具(Claude / Codex 等)在新 session 中接手任务时,**第一份必读文档**。\n4\t> 与之配合的还有:[`docs/PROJECT_MAP.md`](./PROJECT_MAP.md)(数据来源 / 组成 / 生成链 / 跨 AI 分工)、[`docs/working-principles.md`](./working-principles.md)(实现原则)、[`src/design-system/translation/`](../src/design-system/translation/)(翻译层 SoT)、[`docs/internal/retrospection/`](./internal/retrospection/)(决策复盘)。\n5\t\n6\t---\n7\t\n8\t## 一句话目标\n9\t\n10\t把 **Figma 已发布的 Library**(组件、Token、图标、Styles)做成 **AI 与开发可消费的双向 Figma↔Code 桥**:\n11\t\n12\t- 开发通过 **Element Plus 风格文档站 + npm install** 即可用(Vue 组件 / 设计 token / 图标 registry / 样式)\n13\t- AI 拿 **Figma URL** → 定位代码并 1:1 还原\n14\t- AI 拿 **代码页面** → 生成 / 还原 Figma 效果图\n15\t > 现状(能力 3 code→Figma,按边界如实分层):**DS 生成的代码 _可_ 还原回 Figma**——经 `figma-data/render-verification-manifest.json`(936 条 Figma nodeId ↔ code 组件 ↔ props 确定性映射)+ canonical `data-figma-*` 溯源属性,回指**有且只有一个**设计库真源(`figmaFileKey = YbsPRUVmNdsbN40NNwh1Gn`,全 manifest distinct fileKey 实测唯一)。**真正缺的不是\"还原能力\",而是自动 publish 链路的三块**:① Code Connect `.figma.ts` publish(Figma Professional plan,任何 Code Connect API 调用 401,需 Org/Ent seat;已实证)② 非 DS 代码(库外自绘组件)的反查 ③ Figma MCP 本地未配置。所以标 **DEFERRED(bypass equivalent)** 指的是\"全自动 code→Figma publish\",**不是**\"code→Figma 不可为\"。详见 `docs/CAPABILITY_3_BYPASS.md` + STATUS §Deferred。\n16\t- AI 拿 **文字 / 链接 / 截图 / 代码任一组合** → 生成符合本规范的:\n17\t - **UX 效果图**(Figma 设计稿 / 截图)\n18\t - **可运行代码网页**(Vue 组件 + 部署)\n19\t > 现状:能力 4 当前实现为**合规守门(gate)+ AI 辅助合成**,非全自动生成器。\n20\t- 每个 Code 组件可追溯到 **Figma 来源**(哪个组件 / 哪个属性)\n21\t\n22\t---\n23\t\n24\t## 操作模型(谁用 / 怎么把关 / 质量如何保证)\n25\t\n26\t> 本节是项目北极星,后续任何流程优化都须遵守。目标架构(自触发脊梁 + 四支柱 + 元层)与差距登记见 `docs/internal/full-lifecycle-assessment-2026-07-08.md`(backlog INFRA-F55),演进中、不冻结进本文件。\n27\t\n28\t- **性质**:企业级设计系统,供多人使用。\n29\t- **角色**:一个 owner 把关质量;设计同事拉分支维护 + 使用;dev / PM 直接用现成系统做产品设计。\n30\t- **工具面(目标 / 现状分列)**:**目标** = Claude Code / Codex / 其它 AI / claude.ai·Design 类工具都要能产出高质量产品设计;**当前** = 仅 Claude Code(hooks + skills 全套)就位,Codex 半套、claude.ai/其它工具适配未齐——补齐是 backlog INFRA-F55 支柱③ 工作(现状诊断见 assessment §2 工具耦合)。\n31\t- **三条核心要求(目标,建设中)**:① **质量与\"用哪个工具\"解耦**(不绑单一工具)② 使用者**不必懂流程**,系统**自行触发**对应流程 ③ 团队成员**一看就知道如何使用**。\n32\t- **质量把关模型**:**非 owner 贡献者的改动走 PR,由 owner review**(目标:自动化 gate 做重活、人只点 merge);**owner 本人改动直推 master**(fast-lane,见 `AGENTS.md` 硬规则 #7)。**gate 平权原则**:凡拦贡献者 PR 的 gate 同样挂 `push:master`,owner 直推路径不少过任何一关(真源 = [`.gitea/workflows/pr-checks.yml`](../.gitea/workflows/pr-checks.yml) 文件头 —— ⚠️ **2026-08-14 订正**:此处原写「见 backlog **INFRA-F56**」,而该号早已并入 `INFRA-F61`、backlog 全文零命中,是个悬挂指针)。\n33\t- **派生最高目标**:任何人 × 任何工具 → 被系统自动导进正确流程、产出高质量产品设计(code + mockup)。\n34\t\n35\t## Token 架构(Figma 变量 = 原子级真源)\n36\t\n37\t- **Figma Variable = 原子真源,sync-bound + gated**:54 个 Figma 变量含**两层**——原始色板(`--color-grey-*` / `--brand` / `--red` / …)+ **语义颜色层**(Figma `Color Type/*` → `--text-*` / `--icon-*` / `--bg-*` / `--line-*`)。全部由 `pnpm generate` 按名同步、`audit:token-contract` L5 gate 卡;**不可手改代码值,改设计改 Figma**。语义颜色 token 不是摆设,是原子依据。\n38\t- **非颜色 token = 当前值对齐、非变量绑定(保真缺口)**:间距 `--sp-*`、控件尺寸、Effect / Text Style、组件变体 token 不在 Figma Variable 里(Effect / Text 在 Figma 是 Style,间距代码手写),靠人工对齐值、无 gate。是否变量化见 backlog INFRA-F57。\n39\t- **分发形态**:CSS 变量(`dist/style.css`)+ **TS / JSON token 出口已发**(`./tokens` = DTCG `dist/tokens/tokens.json` · `./tokens/js` = resolved TS `dist/tokens/tokens.js`+`.d.ts`,INFRA-F55 支柱①,2026-07-10 起),非 web 工具已可消费。注:token 分发已解决;剩余缺口是**非色 token(spacing/size/effect)仍代码手写、未 Figma-Variable-绑定**(INFRA-F57),以及 DTCG 输出未标 `$extensions.tvu.source` 区分 figma-variable vs code-authored(见 assessment 2026-07-16 §支柱B)。\n40\t\n41\t---\n42\t\n43\t## 各能力的前置约束(写 T3 / T4 prompt 时必读)\n44\t\n45\t下面这些约束是为了让\"双向 + 多模态消费\"能力**不在后期返工**——而不是要现在实现。T3 / T4 prompt 设计时必须前置考虑。\n46\t\n47\t### T3 — EP 分类 + Figma origin 元数据\n48\t\n49\t- metadata schema 必须支持**双向查询**:\n50\t - (a) Figma node ID → code 路径(已规划)\n51\t - (b) **code 路径 → Figma node ID**(反向)\n52\t- 多 code 实体共享 Figma origin 时(如 SelectBoxLine + SelectBoxFilled 共享 `Select.feature=date`)必须支持 **N:1 映射**\n53\t\n54\t### T4a — Code Connect `.figma.ts`\n55\t\n56\t- 不只声明 props 映射,要预留 `reverseGenerationHints`(或类似字段)——后期反向生成器(Code → Figma)读这个字段重建 Figma node 结构\n57\t- 所有映射查 `axis-implementation-map.json` 真源(meta-rules 反模式 #1:不在 `.figma.ts` 自创映射)\n58\t\n59\t### T4b — AI manifest\n60\t\n61\tmanifest 顶层必须含:\n62\t\n63\t- `directions: ['figma-to-code', 'code-to-figma']` — 明示支持的方向\n64\t- `compositionSupport` — 不只描述单组件,还含组件组合规则(如 FormItem 包 Input、Table 包 Pagination)+ 布局/间距规范,让 AI 能合成 **页面级** 输出(不只单组件)。(前瞻约束、非现状:组合契约当前仅内部 `component-affordances.json`、不随包发;随包发是支柱① 工作)\n65\t- 各方向所需的额外锚点(如 code-to-figma 需要 baseline 截图引用、page-level 合成需要布局 token)\n66\t\n67\t### T5 — 视觉回归 baseline\n68\t\n69\tbaseline 截图除了用于回归检测,还作为:\n70\t\n71\t- code-to-figma 反向生成的视觉锚点(生成后跟 baseline diff 验证)\n72\t- 多模态合成(截图输入)的训练 / 校验语料\n73\t\n74\t---\n75\t\n76\t## 受众与他们的关注点\n77\t\n78\t| 角色 | 优先级 | 关注点 |\n79\t|---|---|---|\n80\t| **开发** | P0 主要使用者 | npm 安装、import 用法、props/events/slots、可复制代码示例、TypeScript 类型 |\n81\t| **设计** | P1 查看者 | 与 Figma 对应关系、变体网格、设计 spec、版本变更 |\n82\t| **产品** | P1 查看者 | 业务场景示例、组件能做什么、什么时候用哪个 |\n83\t| **QA** | P1 查看者 | 状态矩阵(hover/disabled/error/empty 等)、可交互测试、边界条件 |\n84\t\n85\t---\n86\t\n87\t## 关键产出物\n88\t\n89\t1. **Code 库**\n90\t - Vue 组件(`src/components/`)\n91\t - 设计 token(`tokens/`)——CSS 变量经 `./style.css` 分发 + **TS/JSON token 出口已发**(`./tokens` DTCG + `./tokens/js` resolved TS,见「Token 架构」节)\n92\t - 图标 registry(`src/icons/` + `icons/index.ts`)\n93\t - Styles(CSS 变量 + 主题)\n94\t\n95\t2. **npm 包发布机制**\n96\t - `package.json` 配置(entry、exports、types)\n97\t - 版本管理(semver)\n98\t - changelog 规范\n99\t - 公司其他项目 `npm install @ux-team/tvu-design-system` 即可使用\n100\t\n101\t3. **文档站(Element Plus 风格)**\n102\t - 参考站:https://element-plus.org/en-US/component/overview\n103\t - 必有结构:标题 + intro / 多段示例(preview + show source)/ API 表(Attributes / Slots / Events / Exposes)/ 右侧 TOC\n104\t - **多角色补充**(不止开发视角):\n105\t - \"Design Spec\" tab / 段落:Figma 变体网格 + 设计稿对照\n106\t - \"Status Matrix\" tab / 段落:QA 视角的状态测试\n107\t > **scope 显式化(2026-06-10 system-review P2-08)**:Status Matrix 当前只建模 **Figma 导出的变体状态**(设计真源有的轴);**runtime 态(empty / loading / error / 0 数据 / 超长文本)不在矩阵建模范围**——数据类组件(Table / Select)的 runtime 态 demo 是已知缺口,按需求触发补,不随组件页自动复制(StatusMatrix.vue 头注释同此声明;mockup 侧超长文本由 M43 管)。三视图覆盖与 pending 债务由 `audit:docs-site` + `site-review-manifest.json` views 字段跟踪\n108\t - \"Use Cases\" 段落:产品视角的业务示例\n109\t > 现状:当前落地 = 开发 + QA 双视图;**产品 Use Cases / 设计 Spec 视图为已知缺口**,按需补,不在此写版本 roadmap。⛔ **条数别在这里手抄** —— 真源是 `pnpm audit:docs-site` 自印的 `threeViewPending`(它不只信 manifest 自报,还拿页面源码正则交叉核)+ `site-review-manifest.json` 各 page 的 `views` 字段。此前这里写死的 `0/34 · 1/34` **分母当天就是错的**:34 取自 2026-07-08 的 manifest **总页数**(含 6 overview + 5 foundation),而带 `views` 的只有 component 页 —— 那天与今天都是 **25**(2026-08-07 复核:36 页 = 6+5+25,useCases present 0 / designSpec present 1)。\n110\t\n111\t4. **长期维护机制**\n112\t - **边界翻译层**(`src/design-system/translation/`):显式管理 Figma↔Code 的命名/结构差异\n113\t - **Figma↔Code 锁定(防 drift)**:`figma connect publish`(Code Connect `*.figma.ts`)当前**不可达**(Figma Professional plan,任何 Code Connect API 调用返回 401,需 Org/Ent Developer seat;已实证)。**当前实际采用的等价同步机制**:硬规则 #6(AI 从 Figma URL 生成必用 `src/canonical/*` 作 SoT)+ 边界翻译层(`src/design-system/translation/`)+ `pnpm sync:figma-library` 14-step audit pipeline + `figma-data/render-verification-manifest.json`(936 entries,Figma nodeId ↔ code 组件 ↔ props 的确定性数值验证)。Code Connect 待 Figma plan 升级后纳入。\n114\t - **视觉层确定性脚本**(`scripts/visual-audit.ts`):不依赖 AI 的对 diff,CI 可跑\n115\t\n116\t---\n117\t\n118\t## 不要做\n119\t\n120\t- ❌ **不修改 Figma**——Figma 是设计师的真源,代码出现差异时由翻译层登记\n121\t- ❌ **不让 AI 自由发挥**——Codex / Claude 必须读翻译层 + working-principles,不准按\"行业惯例\"补全\n122\t- ❌ **不让单组件深修阻塞 release 节奏**——但这 ≠「永不深修」。**Code 是否 1:1 还原 Figma 的保真度修正,是 post-launch 迭代的持续主线**:非破坏性修正(颜色 / 间距 / a11y / composition 复用)由 [`figma-vs-code-fidelity-audit-2026-05-29.md`](./_archive/_reports/figma-vs-code-fidelity-audit-2026-05-29.md) 驱动、**按 tier 排期(版本归属见 [`STATUS.md`](./STATUS.md) + tracker)**;破坏性 API 改造(如**已完成**的 Button canonical 迁移)走 0.x.0 minor。要点:fidelity 修正不阻塞交付节奏,也不被无限期搁置——**是持续进行的主线,不因某版本收尾而停**\n123\t- ❌ **不混合多语义到一个 prop**——发现同名异义(如 Badge.type = 颜色 vs Figma Type = 形状)必须拆\n124\t\n125\t---\n126\t\n127\t## 当前进度\n128\t\n129\t> ⚠️ **逐版本进度真源 = [`docs/STATUS.md`](./STATUS.md)**(当前版本 + 版本线分组 + Active 余量)**+ [`design-spec-canonical-alignment-tracker.md`](./internal/retrospection/design-spec-canonical-alignment-tracker.md)**(排期 SoT + 逐版本 retrospect)。本文件不再镜像版本路线——此处曾冻结在 v0.6.0 规划态多个版本(2026-06-10 system-review P2-07 de-mirror,同 AGENTS.md \"当前阶段定位\" 段范式)。\n130\t>\n131\t> 已完成的架构里程碑(稳定史实,不随版本滚动):0-3 架构层(边界翻译层 / working-principles / 翻译层登记)→ 4-5 模式聚类 + B1-B10 决策 → 6.x 翻译层批量登记 + token 替换 → npm 包化 + Element Plus 风格文档站 → 0.x 逐版本 release(v0.2.0 起见 tracker §Release 排期)。\n132\t\n133\t> **排期原则**(不可违背):项目目标对齐 > 依赖解锁 > 自动化标准化 > 短 cycle 顺路;**不按耗时 / 复杂度 / 成本最低排**。详见 tracker.md §排期原则。\n134\t\n135\t---\n136\t\n137\t## AI 协作规范(Codex / Claude / 其他)\n138\t\n139\t### 必读入口(按优先级)\n140\t1. **本文档**(PROJECT_GOAL.md)—— 知道在做什么\n141\t2. [`docs/PROJECT_MAP.md`](./PROJECT_MAP.md) —— 知道数据来源、项目组成、生成链和跨 AI 分工\n142\t3. [`docs/working-principles.md`](./working-principles.md) —— 知道怎么做\n143\t4. [`src/design-system/translation/`](../src/design-system/translation/) —— 知道已有决策\n144\t5. [`docs/internal/retrospection/`](./internal/retrospection/) —— 知道怎么走到这里的\n145\t\n146\t### Prompt 模板(验证有效)\n147\t位置:[`docs/internal/_prompts/`](./internal/_prompts/)\n148\t- 所有 Codex prompt 都以文件形式版本化\n149\t- 用户通过 `请读取并执行 docs/internal/_prompts/.prompt.md 中的指令` 触发\n150\t- 绕过 VS Code Codex 扩展的剪贴板编码 bug\n151\t\n152\t### Gate 机制(防 AI 漂移)\n153\t- 每个 prompt 末尾必带 \"完成后 STOP,等我决定下一步\"\n154\t- 关键参数(如 variant 枚举值、token 值)必须先返回给用户确认\n155\t- 双向 diff(code 侧 + Figma 侧)后只审 ⚠️ 行\n156\t- 视觉层硬错误(hex / 未定义 token)走脚本,不走 AI\n157\t\n158\t---\n159\t\n160\t## Quick Reference\n161\t\n162\t| 我想知道 | 看哪里 |\n163\t|---|---|\n164\t| 项目目标 | 本文档 |\n165\t| 数据来源 / 项目组成 / 生成链 / 清理规则 | [`docs/PROJECT_MAP.md`](./PROJECT_MAP.md) |\n166\t| 实现原则 | [`docs/working-principles.md`](./working-principles.md) |\n167\t| 当前进度 | [`docs/internal/retrospection/`](./internal/retrospection/)(最新日期) |\n168\t| 已做的决策 | [`src/design-system/translation/`](../src/design-system/translation/) + working-principles 末尾\"决策 Log\" |\n169\t| 下一步要跑的 prompt | [`docs/internal/_prompts/`](./internal/_prompts/) |\n170\t| API diff 状态 | [`docs/internal/api-diff.md`](./internal/api-diff.md) + [`api-diff-patterns.md`](./internal/api-diff-patterns.md) |\n171\t| 资产清单 | [`docs/internal/asset-inventory.md`](./internal/asset-inventory.md) |\n172\t| 组件级映射扫描 | [`docs/internal/component-mapping-scan.md`](./internal/component-mapping-scan.md) |\n173\t| 待补运行时能力 | [`docs/internal/runtime-additions.md`](./internal/runtime-additions.md) |\n174\t"}]},"parent_tool_use_id":null,"session_id":"ccca31c3-4a85-4094-9f46-4533df53f8ce","uuid":"a09d8104-c088-4bda-b6e5-3ccfb25ede49","timestamp":"2026-08-25T09:21:21.251Z","tool_use_result":{"type":"text","file":{"filePath":"/Users/nancy/.ai-ds-lab/pins/tvu-ds-4a68e02d/docs/PROJECT_GOAL.md","content":"# TVU 设计系统 项目目标\n\n> 本文档是项目的最高指导原则。任何 AI 工具(Claude / Codex 等)在新 session 中接手任务时,**第一份必读文档**。\n> 与之配合的还有:[`docs/PROJECT_MAP.md`](./PROJECT_MAP.md)(数据来源 / 组成 / 生成链 / 跨 AI 分工)、[`docs/working-principles.md`](./working-principles.md)(实现原则)、[`src/design-system/translation/`](../src/design-system/translation/)(翻译层 SoT)、[`docs/internal/retrospection/`](./internal/retrospection/)(决策复盘)。\n\n---\n\n## 一句话目标\n\n把 **Figma 已发布的 Library**(组件、Token、图标、Styles)做成 **AI 与开发可消费的双向 Figma↔Code 桥**:\n\n- 开发通过 **Element Plus 风格文档站 + npm install** 即可用(Vue 组件 / 设计 token / 图标 registry / 样式)\n- AI 拿 **Figma URL** → 定位代码并 1:1 还原\n- AI 拿 **代码页面** → 生成 / 还原 Figma 效果图\n > 现状(能力 3 code→Figma,按边界如实分层):**DS 生成的代码 _可_ 还原回 Figma**——经 `figma-data/render-verification-manifest.json`(936 条 Figma nodeId ↔ code 组件 ↔ props 确定性映射)+ canonical `data-figma-*` 溯源属性,回指**有且只有一个**设计库真源(`figmaFileKey = YbsPRUVmNdsbN40NNwh1Gn`,全 manifest distinct fileKey 实测唯一)。**真正缺的不是\"还原能力\",而是自动 publish 链路的三块**:① Code Connect `.figma.ts` publish(Figma Professional plan,任何 Code Connect API 调用 401,需 Org/Ent seat;已实证)② 非 DS 代码(库外自绘组件)的反查 ③ Figma MCP 本地未配置。所以标 **DEFERRED(bypass equivalent)** 指的是\"全自动 code→Figma publish\",**不是**\"code→Figma 不可为\"。详见 `docs/CAPABILITY_3_BYPASS.md` + STATUS §Deferred。\n- AI 拿 **文字 / 链接 / 截图 / 代码任一组合** → 生成符合本规范的:\n - **UX 效果图**(Figma 设计稿 / 截图)\n - **可运行代码网页**(Vue 组件 + 部署)\n > 现状:能力 4 当前实现为**合规守门(gate)+ AI 辅助合成**,非全自动生成器。\n- 每个 Code 组件可追溯到 **Figma 来源**(哪个组件 / 哪个属性)\n\n---\n\n## 操作模型(谁用 / 怎么把关 / 质量如何保证)\n\n> 本节是项目北极星,后续任何流程优化都须遵守。目标架构(自触发脊梁 + 四支柱 + 元层)与差距登记见 `docs/internal/full-lifecycle-assessment-2026-07-08.md`(backlog INFRA-F55),演进中、不冻结进本文件。\n\n- **性质**:企业级设计系统,供多人使用。\n- **角色**:一个 owner 把关质量;设计同事拉分支维护 + 使用;dev / PM 直接用现成系统做产品设计。\n- **工具面(目标 / 现状分列)**:**目标** = Claude Code / Codex / 其它 AI / claude.ai·Design 类工具都要能产出高质量产品设计;**当前** = 仅 Claude Code(hooks + skills 全套)就位,Codex 半套、claude.ai/其它工具适配未齐——补齐是 backlog INFRA-F55 支柱③ 工作(现状诊断见 assessment §2 工具耦合)。\n- **三条核心要求(目标,建设中)**:① **质量与\"用哪个工具\"解耦**(不绑单一工具)② 使用者**不必懂流程**,系统**自行触发**对应流程 ③ 团队成员**一看就知道如何使用**。\n- **质量把关模型**:**非 owner 贡献者的改动走 PR,由 owner review**(目标:自动化 gate 做重活、人只点 merge);**owner 本人改动直推 master**(fast-lane,见 `AGENTS.md` 硬规则 #7)。**gate 平权原则**:凡拦贡献者 PR 的 gate 同样挂 `push:master`,owner 直推路径不少过任何一关(真源 = [`.gitea/workflows/pr-checks.yml`](../.gitea/workflows/pr-checks.yml) 文件头 —— ⚠️ **2026-08-14 订正**:此处原写「见 backlog **INFRA-F56**」,而该号早已并入 `INFRA-F61`、backlog 全文零命中,是个悬挂指针)。\n- **派生最高目标**:任何人 × 任何工具 → 被系统自动导进正确流程、产出高质量产品设计(code + mockup)。\n\n## Token 架构(Figma 变量 = 原子级真源)\n\n- **Figma Variable = 原子真源,sync-bound + gated**:54 个 Figma 变量含**两层**——原始色板(`--color-grey-*` / `--brand` / `--red` / …)+ **语义颜色层**(Figma `Color Type/*` → `--text-*` / `--icon-*` / `--bg-*` / `--line-*`)。全部由 `pnpm generate` 按名同步、`audit:token-contract` L5 gate 卡;**不可手改代码值,改设计改 Figma**。语义颜色 token 不是摆设,是原子依据。\n- **非颜色 token = 当前值对齐、非变量绑定(保真缺口)**:间距 `--sp-*`、控件尺寸、Effect / Text Style、组件变体 token 不在 Figma Variable 里(Effect / Text 在 Figma 是 Style,间距代码手写),靠人工对齐值、无 gate。是否变量化见 backlog INFRA-F57。\n- **分发形态**:CSS 变量(`dist/style.css`)+ **TS / JSON token 出口已发**(`./tokens` = DTCG `dist/tokens/tokens.json` · `./tokens/js` = resolved TS `dist/tokens/tokens.js`+`.d.ts`,INFRA-F55 支柱①,2026-07-10 起),非 web 工具已可消费。注:token 分发已解决;剩余缺口是**非色 token(spacing/size/effect)仍代码手写、未 Figma-Variable-绑定**(INFRA-F57),以及 DTCG 输出未标 `$extensions.tvu.source` 区分 figma-variable vs code-authored(见 assessment 2026-07-16 §支柱B)。\n\n---\n\n## 各能力的前置约束(写 T3 / T4 prompt 时必读)\n\n下面这些约束是为了让\"双向 + 多模态消费\"能力**不在后期返工**——而不是要现在实现。T3 / T4 prompt 设计时必须前置考虑。\n\n### T3 — EP 分类 + Figma origin 元数据\n\n- metadata schema 必须支持**双向查询**:\n - (a) Figma node ID → code 路径(已规划)\n - (b) **code 路径 → Figma node ID**(反向)\n- 多 code 实体共享 Figma origin 时(如 SelectBoxLine + SelectBoxFilled 共享 `Select.feature=date`)必须支持 **N:1 映射**\n\n### T4a — Code Connect `.figma.ts`\n\n- 不只声明 props 映射,要预留 `reverseGenerationHints`(或类似字段)——后期反向生成器(Code → Figma)读这个字段重建 Figma node 结构\n- 所有映射查 `axis-implementation-map.json` 真源(meta-rules 反模式 #1:不在 `.figma.ts` 自创映射)\n\n### T4b — AI manifest\n\nmanifest 顶层必须含:\n\n- `directions: ['figma-to-code', 'code-to-figma']` — 明示支持的方向\n- `compositionSupport` — 不只描述单组件,还含组件组合规则(如 FormItem 包 Input、Table 包 Pagination)+ 布局/间距规范,让 AI 能合成 **页面级** 输出(不只单组件)。(前瞻约束、非现状:组合契约当前仅内部 `component-affordances.json`、不随包发;随包发是支柱① 工作)\n- 各方向所需的额外锚点(如 code-to-figma 需要 baseline 截图引用、page-level 合成需要布局 token)\n\n### T5 — 视觉回归 baseline\n\nbaseline 截图除了用于回归检测,还作为:\n\n- code-to-figma 反向生成的视觉锚点(生成后跟 baseline diff 验证)\n- 多模态合成(截图输入)的训练 / 校验语料\n\n---\n\n## 受众与他们的关注点\n\n| 角色 | 优先级 | 关注点 |\n|---|---|---|\n| **开发** | P0 主要使用者 | npm 安装、import 用法、props/events/slots、可复制代码示例、TypeScript 类型 |\n| **设计** | P1 查看者 | 与 Figma 对应关系、变体网格、设计 spec、版本变更 |\n| **产品** | P1 查看者 | 业务场景示例、组件能做什么、什么时候用哪个 |\n| **QA** | P1 查看者 | 状态矩阵(hover/disabled/error/empty 等)、可交互测试、边界条件 |\n\n---\n\n## 关键产出物\n\n1. **Code 库**\n - Vue 组件(`src/components/`)\n - 设计 token(`tokens/`)——CSS 变量经 `./style.css` 分发 + **TS/JSON token 出口已发**(`./tokens` DTCG + `./tokens/js` resolved TS,见「Token 架构」节)\n - 图标 registry(`src/icons/` + `icons/index.ts`)\n - Styles(CSS 变量 + 主题)\n\n2. **npm 包发布机制**\n - `package.json` 配置(entry、exports、types)\n - 版本管理(semver)\n - changelog 规范\n - 公司其他项目 `npm install @ux-team/tvu-design-system` 即可使用\n\n3. **文档站(Element Plus 风格)**\n - 参考站:https://element-plus.org/en-US/component/overview\n - 必有结构:标题 + intro / 多段示例(preview + show source)/ API 表(Attributes / Slots / Events / Exposes)/ 右侧 TOC\n - **多角色补充**(不止开发视角):\n - \"Design Spec\" tab / 段落:Figma 变体网格 + 设计稿对照\n - \"Status Matrix\" tab / 段落:QA 视角的状态测试\n > **scope 显式化(2026-06-10 system-review P2-08)**:Status Matrix 当前只建模 **Figma 导出的变体状态**(设计真源有的轴);**runtime 态(empty / loading / error / 0 数据 / 超长文本)不在矩阵建模范围**——数据类组件(Table / Select)的 runtime 态 demo 是已知缺口,按需求触发补,不随组件页自动复制(StatusMatrix.vue 头注释同此声明;mockup 侧超长文本由 M43 管)。三视图覆盖与 pending 债务由 `audit:docs-site` + `site-review-manifest.json` views 字段跟踪\n - \"Use Cases\" 段落:产品视角的业务示例\n > 现状:当前落地 = 开发 + QA 双视图;**产品 Use Cases / 设计 Spec 视图为已知缺口**,按需补,不在此写版本 roadmap。⛔ **条数别在这里手抄** —— 真源是 `pnpm audit:docs-site` 自印的 `threeViewPending`(它不只信 manifest 自报,还拿页面源码正则交叉核)+ `site-review-manifest.json` 各 page 的 `views` 字段。此前这里写死的 `0/34 · 1/34` **分母当天就是错的**:34 取自 2026-07-08 的 manifest **总页数**(含 6 overview + 5 foundation),而带 `views` 的只有 component 页 —— 那天与今天都是 **25**(2026-08-07 复核:36 页 = 6+5+25,useCases present 0 / designSpec present 1)。\n\n4. **长期维护机制**\n - **边界翻译层**(`src/design-system/translation/`):显式管理 Figma↔Code 的命名/结构差异\n - **Figma↔Code 锁定(防 drift)**:`figma connect publish`(Code Connect `*.figma.ts`)当前**不可达**(Figma Professional plan,任何 Code Connect API 调用返回 401,需 Org/Ent Developer seat;已实证)。**当前实际采用的等价同步机制**:硬规则 #6(AI 从 Figma URL 生成必用 `src/canonical/*` 作 SoT)+ 边界翻译层(`src/design-system/translation/`)+ `pnpm sync:figma-library` 14-step audit pipeline + `figma-data/render-verification-manifest.json`(936 entries,Figma nodeId ↔ code 组件 ↔ props 的确定性数值验证)。Code Connect 待 Figma plan 升级后纳入。\n - **视觉层确定性脚本**(`scripts/visual-audit.ts`):不依赖 AI 的对 diff,CI 可跑\n\n---\n\n## 不要做\n\n- ❌ **不修改 Figma**——Figma 是设计师的真源,代码出现差异时由翻译层登记\n- ❌ **不让 AI 自由发挥**——Codex / Claude 必须读翻译层 + working-principles,不准按\"行业惯例\"补全\n- ❌ **不让单组件深修阻塞 release 节奏**——但这 ≠「永不深修」。**Code 是否 1:1 还原 Figma 的保真度修正,是 post-launch 迭代的持续主线**:非破坏性修正(颜色 / 间距 / a11y / composition 复用)由 [`figma-vs-code-fidelity-audit-2026-05-29.md`](./_archive/_reports/figma-vs-code-fidelity-audit-2026-05-29.md) 驱动、**按 tier 排期(版本归属见 [`STATUS.md`](./STATUS.md) + tracker)**;破坏性 API 改造(如**已完成**的 Button canonical 迁移)走 0.x.0 minor。要点:fidelity 修正不阻塞交付节奏,也不被无限期搁置——**是持续进行的主线,不因某版本收尾而停**\n- ❌ **不混合多语义到一个 prop**——发现同名异义(如 Badge.type = 颜色 vs Figma Type = 形状)必须拆\n\n---\n\n## 当前进度\n\n> ⚠️ **逐版本进度真源 = [`docs/STATUS.md`](./STATUS.md)**(当前版本 + 版本线分组 + Active 余量)**+ [`design-spec-canonical-alignment-tracker.md`](./internal/retrospection/design-spec-canonical-alignment-tracker.md)**(排期 SoT + 逐版本 retrospect)。本文件不再镜像版本路线——此处曾冻结在 v0.6.0 规划态多个版本(2026-06-10 system-review P2-07 de-mirror,同 AGENTS.md \"当前阶段定位\" 段范式)。\n>\n> 已完成的架构里程碑(稳定史实,不随版本滚动):0-3 架构层(边界翻译层 / working-principles / 翻译层登记)→ 4-5 模式聚类 + B1-B10 决策 → 6.x 翻译层批量登记 + token 替换 → npm 包化 + Element Plus 风格文档站 → 0.x 逐版本 release(v0.2.0 起见 tracker §Release 排期)。\n\n> **排期原则**(不可违背):项目目标对齐 > 依赖解锁 > 自动化标准化 > 短 cycle 顺路;**不按耗时 / 复杂度 / 成本最低排**。详见 tracker.md §排期原则。\n\n---\n\n## AI 协作规范(Codex / Claude / 其他)\n\n### 必读入口(按优先级)\n1. **本文档**(PROJECT_GOAL.md)—— 知道在做什么\n2. [`docs/PROJECT_MAP.md`](./PROJECT_MAP.md) —— 知道数据来源、项目组成、生成链和跨 AI 分工\n3. [`docs/working-principles.md`](./working-principles.md) —— 知道怎么做\n4. [`src/design-system/translation/`](../src/design-system/translation/) —— 知道已有决策\n5. [`docs/internal/retrospection/`](./internal/retrospection/) —— 知道怎么走到这里的\n\n### Prompt 模板(验证有效)\n位置:[`docs/internal/_prompts/`](./internal/_prompts/)\n- 所有 Codex prompt 都以文件形式版本化\n- 用户通过 `请读取并执行 docs/internal/_prompts/.prompt.md 中的指令` 触发\n- 绕过 VS Code Codex 扩展的剪贴板编码 bug\n\n### Gate 机制(防 AI 漂移)\n- 每个 prompt 末尾必带 \"完成后 STOP,等我决定下一步\"\n- 关键参数(如 variant 枚举值、token 值)必须先返回给用户确认\n- 双向 diff(code 侧 + Figma 侧)后只审 ⚠️ 行\n- 视觉层硬错误(hex / 未定义 token)走脚本,不走 AI\n\n---\n\n## Quick Reference\n\n| 我想知道 | 看哪里 |\n|---|---|\n| 项目目标 | 本文档 |\n| 数据来源 / 项目组成 / 生成链 / 清理规则 | [`docs/PROJECT_MAP.md`](./PROJECT_MAP.md) |\n| 实现原则 | [`docs/working-principles.md`](./working-principles.md) |\n| 当前进度 | [`docs/internal/retrospection/`](./internal/retrospection/)(最新日期) |\n| 已做的决策 | [`src/design-system/translation/`](../src/design-system/translation/) + working-principles 末尾\"决策 Log\" |\n| 下一步要跑的 prompt | [`docs/internal/_prompts/`](./internal/_prompts/) |\n| API diff 状态 | [`docs/internal/api-diff.md`](./internal/api-diff.md) + [`api-diff-patterns.md`](./internal/api-diff-patterns.md) |\n| 资产清单 | [`docs/internal/asset-inventory.md`](./internal/asset-inventory.md) |\n| 组件级映射扫描 | [`docs/internal/component-mapping-scan.md`](./internal/component-mapping-scan.md) |\n| 待补运行时能力 | [`docs/internal/runtime-additions.md`](./internal/runtime-additions.md) |\n","numLines":174,"startLine":1,"totalLines":174}}} {"type":"assistant","message":{"model":"claude-opus-5","id":"msg_011CePDjh9nSri5YdKAs8Yff","type":"message","role":"assistant","content":[{"type":"tool_use","id":"toolu_018HwonZPBvnMaqWomtqFuB6","name":"Read","input":{"file_path":"/Users/nancy/.ai-ds-lab/pins/tvu-ds-4a68e02d/AGENTS.md"},"caller":{"type":"direct"}}],"stop_reason":null,"stop_sequence":null,"stop_details":null,"usage":{"input_tokens":2,"cache_creation_input_tokens":59449,"cache_read_input_tokens":0,"cache_creation":{"ephemeral_5m_input_tokens":0,"ephemeral_1h_input_tokens":59449},"output_tokens":2,"service_tier":"standard","inference_geo":"not_available"},"diagnostics":null,"context_management":null},"parent_tool_use_id":null,"session_id":"ccca31c3-4a85-4094-9f46-4533df53f8ce","uuid":"7394f2ff-1b99-49c2-8d1a-782e20cd3589","timestamp":"2026-08-25T09:21:21.253Z","request_id":"req_011CePDje4VeFgvgyXui7jmj"} {"type":"rate_limit_event","rate_limit_info":{"status":"allowed","resetsAt":1787658600,"rateLimitType":"five_hour","overageStatus":"rejected","overageDisabledReason":"out_of_credits","isUsingOverage":false},"uuid":"fdcb0d69-d5bb-4db1-975b-cb1ca78579c9","session_id":"ccca31c3-4a85-4094-9f46-4533df53f8ce"} {"type":"user","message":{"role":"user","content":[{"tool_use_id":"toolu_01GZ59NtY1Dwqg7XLGV8CEyY","type":"tool_result","content":"1\t# TVU Design System — Status\n2\t\n3\t> **Last updated**: 2026-08-25 —— **落地线第三十轮:mockup conformance 合成单进程引擎 + 给闸的 stdout 定输出契约**(**Active 32 → 32**:新增 [[INFRA-F139]]、删档 INFRA-F132)。执行外部 lab 的两份处方(第 7 / 7b 步),⛔ 不是自选题。
🔴 **本轮最值钱的一条:给 11 条在链闸补一个「分母」字段,当场照出一条 L5 闸的绿三个月来不可解读。** `audit:figma-conformance` 的扫描面 `src/canonical/generated/*.vue` 实测 **0 个文件** ⇒ 每次发版都绿、绿无信息量。修法是 owner 裁定(退役 vs 改指向,两条都改发布链判据强度)⇒ [[INFRA-F139]] + 收割器里具名 shrink-only 豁免(照样每次打印)。**这不是契约引入的缺陷,是契约让一个一直存在的空分母第一次可见。**
**引擎实测**:进程 10 → **1** · 请求 12 → **3** / 大 payload 8 → **1**(请求计数器自证,⛔ 不用耗时代理)· 同一 fileKey 整文件 140s → **27.0s**(且在多跑一条规则的前提下)· 规则 9 → **10**。**规则清单真源从「代码位置」改成「一条命令」**(`--list-rules`)—— 指代码位置本身就是 stale 源。
**契约实测**:11 条在链 `figma-sync` 闸全部上契约,收割器 **11/11 解析出契约块、11/11 读出 findings 计数**(上契约前 10 条在吐 JSON、只有 **4** 条读得出)。选择面**钉 npm key**、⛔ 不钉文件特征。
**B1 = 这一族闸历史上第一个自动执行点**:`.claude/hooks/post-figma-write.sh` 每次 `use_figma` 写后自动后台跑引擎,fileKey **从 prompt 里的 Figma URL 捕获**(不是写死常量)。⚠️ L4,绕过面如实登记。
⚠️ **三条注入证明非空过**,其中一条打的是**接线**(摘掉 `failed` 表达式里一项 → 1 红),纯 import 单测覆盖不到那一半。
⛔ **数别抄,跑**:`pnpm report:gate-output-harvest` · `pnpm audit:mockup-conformance --list-rules`。验收逐条实测 / 两个既有缺陷前后对照 / KNOWN_SILENT 增删行 / 刻意偏离处方的理由 / 处方自身两处数字偏差,全在 [STATUS-CHANGELOG](./internal/STATUS-CHANGELOG.md) 顶条,⛔ 别在本行找。\n4\t> ——\n5\t> **更早各轮(session I–X)摘要已逐字归档**在 [STATUS-CHANGELOG](./internal/STATUS-CHANGELOG.md);仍需接手人知道的**状态性事实**已各归其唯一真源 —— 主机拓扑 [`DEPLOY.md`](./DEPLOY.md) · docs 站发布口径 [`RELEASING.md`](./RELEASING.md) Step 4 · build 顺序 `scripts/check-dist-wc-freshness.mjs` 头注释 · 各闸的覆盖面与豁免语义在各自脚本头注释且**每次运行自印** · 其余在 [backlog](./internal/backlog.md) 各 entry。⛔ 别再往本段回写完成叙述,闸会拦。\n6\t>\n7\t> ### 一 · 等 owner 拍板(本仓库)\n8\t> 0a. **docs 站 644 张图标预览线上仍坏 —— 源码已修,等一次 docs 站 build + 发布**(`designAssetData.ts` 曾把 dev-server 专用的 `/@fs<绝对路径>` 前缀逐字带进产物)。⛔ 这不是代码待办,是**发布决策**:口径真源 [`RELEASING.md`](./RELEASING.md) §Step 4(= owner 决定,不是 REQUIRED);测量口 `pnpm check:docs-site-version`(三态,`2` 当 `0` 用就是假绿)。修复经过在 [STATUS-CHANGELOG](./internal/STATUS-CHANGELOG.md) 第二轮那条。**本条 2026-08-18 从顶部摘要区搬来 —— 它是 open 的 owner 项,此前混在「已归档各轮」里容易被读成历史。**\n9\t> 0b. **loading 矩阵免横滚 —— ✅ owner 2026-08-13 已裁定走 ②(把每格 variant 文字 / nodeId 收起),⏳ 待落地**(docs 站视觉改动,走快车道)。裁定理由:② 消除根因(那些文字才是要求 180px 的原因),① 会**失去矩阵对齐** = 牺牲这个页面存在的意义(横向对比 variant);nodeId 属查证时才用的次要信息,收进 hover / 点击展开即可。⚠️ 落地后仍需 owner 看一眼实际效果。原始两条路:① 把 ≤980 的卡片流降级上提到 ≤1100 / ≤1280(**已否决**)② 见上。背景:2026-08-12 已 ship 的是「够得着」(横滚 + ③ 删掉 ≤1280 反向加宽的列宽覆盖,所需 1260→1040、1280 档横滚量 682→462px)。⛔ 两条**已排除**:拖拽列宽不创造宽度(1280 档 6 列每列只 106px)· 让宽 demo 横跨右侧 CONTENTS 栏不可行(CONTENTS 是 shell 三栏 grid 里的 sticky item,横跨只能负 margin 画到它底下 = F67 (b) 专抓的「被盖住」)。\n10\t> 1. **DG-1 layout 原语 —— token 层 2026-07-31 已 ship,剩下两件事要 owner/designer 的视觉裁定**(owner 当日裁定「根据实际信息来显示即可 + 要有唯一值」→ 不等新表,值取实测现值做成单一定义;八个值逐字取自改动前在用的值、纯命名化零渲染变化,`audit:layout-tokens` L4+L5 上闸):① ~~3 个存量一次性断点~~ → **✅ 2026-08-12 全部拍完,本子项关闭**:`docs.css` 720 **消除**(owner 拍「拆开归并」并当日 ship)· `progress-demo.css` 900 与 `button-demo.css` 980 **维持豁免不归并**(owner 08-11 / 08-12 分别拍定;判据 = 二者都是 React demo 内部栅格,改它对 DS 消费者零影响,而归并是净损失)。**三条的重开条件已各自写进 [`audit-layout-tokens.mjs`](../scripts/audit-layout-tokens.mjs) 的豁免表**,别在这里找。⚠️ 留一条教训:720 的裁定材料一度**过期**(08-11 那个数字当天就被抽屉导航作废,照它裁 = 按不存在的效果裁)——**「等 owner」条目的实测数字有保质期,隔了一次 ship 要重测再送审**。② ~~容器宽未收口~~ → **✅ owner 2026-08-11 拍定:维持 report-only,不收口**(那批 `max/min-width ≥600px` 是 demo/页面**内容宽**,硬塞进容器档位就是把偶然值当契约。⚠️ **处数别写死,读闸每次运行的自印** —— 这里 2026-08-12 我先把「19 处」改成「22」,**那是错的、当天已订正回来**:22 是闸自己数错的,`extractWidthLiterals`(S5)**不剥 CSS 注释**,把 08-11 抽屉导航那批注释里提到的 3 次 `max-width: 1100px` 当成了真声明。同文件的 `extractMediaWidths`(S3)08-11 修过这个病、S5 那边漏了。已补上同样的注释中和 + 3 条单测(含阴性对照:注释旁的真声明照收),修后实测 **19**,与 07-31 一致 —— **处数从来没漂过,漂的是闸的读数**)。闸的 S5 继续自印剩余处数,**别读成待办**。⚠️ 别读成「布局已收口」;终点仍是 A(Figma 变量),迁移只换真源方向、不改 token 名。详见 [spec §6c](./superpowers/specs/2026-07-30-dg1-layout-primitives-design.md)(§6b「等一张表」那行已就地标注被推翻)。\n11\t> 3. **Gitea registry TLS 化的 owner 残余**(原 INFRA-F74,**2026-08-14 该 entry 已删档 —— 仓库侧全部做完,剩下的只有下面这两件 owner 动作,本行现在是它们的家;⛔ 别再去 backlog 找 F74**)—— ① 人眼看一次新入口 `https://product-demo.tvustream.com/gitea/ux-team/-/packages`(硬纪律,API 绿不免除)· ② 建议轮换主机 `.env`(600) 里那份 `git ls-remote` 仍有效的 `GIT_AUTH`(签发需 owner UI,AI 无此权限)。⛔ **别把 `:3001` 写回 consumer 面 registry 配置** —— 它不是并列的备用入口,是 443 链路上的**中间一跳**,入口拓扑与那次修复的完整真源 = [`GITEA_ENTRYPOINTS.md`](./GITEA_ENTRYPOINTS.md)(⛔ 原先这里指的 `[[INFRA-F89]]` 已删档)。③ 主机上三个 `*.pre-f74*` 回退备份 **暂缓删除**(拿到 SSH 才用得上的唯一回滚源,保留成本为零)—— 三条精确路径已搬进 [`infra/README.md`](../infra/README.md) §主机侧回滚源。\n12\t> 4. **候选回流规则维持候选**(owner 07-29 答「先等等」)—— V4-1827 那批(PRD 措辞锚定产品现状基线 / 交付集与 mockup 同交付区 / 反馈态用文案+状态色、动效交 dev / 删缩元素前先列「谁靠它定位」)+ V4-2333 轮二三条(走查 scope / 偏差要写后果 / wrap-up 步骤有条件)。\n13\t> 5. **[[INFRA-F58]] 残余② 规则三层化 —— 处置待拍(建议整条搁置并重定义)**:2026-08-03 算完三个测量,**器械与目的不匹配** —— 宣称用途是 assessment 支柱① 的「让 claude.ai / Codex 能当 Project Instructions 直接吃」,但那五份文件(`AGENTS.md` + `meta-rules` + `design-process` + `code-conventions` + `mockup-conventions`)**一天涨 54 行、十一天涨 401 行**(08-03 = 7327 → 08-13 = 7674 → **08-14 实测 7728**),而最好可省 150-300 行 —— **可省量追不上分母的增长,比例还在往下走**。⛔ **别读这里的数,自己跑** `wc -l AGENTS.md docs/meta-rules.md docs/internal/{design-process,code-conventions,mockup-conventions}.md`(此处三轮都在漂,本行因此改为只留结论 + 取数命令)。另:原写的 `ds-bundle/reference/` 那组「近逐字搬运」数字(2885→2867 / 1488→1470)**在本仓不可复验** —— `ds-bundle/` 在 `.gitignore` 里、不入库,属外部事实。四块逐块判定 + 六处数字订正 + 两条执行前置见 [backlog F58 entry](./internal/backlog.md)(`e8120010`)。**建议改标「已 scoping、器械与目的不匹配、按需触发」而非留在待做**。⚠️ 若 owner 要真闭合那条 P1 缺口,需要的是**派生式精简产物**(从散文生成紧凑契约、生成而非手维护)—— 那是独立提案、有自己的设计问题(谁是真源 / 怎么防漂),**未立项**。另:任一动它的方案开工前须 owner 显式划清与 2026-06-12 被 reframe 掉的 [`rule-registry`](./internal/rule-registry-design-2026-06-12.md) wholesale reorg 的边界。\n14\t> 6. **DS 系统性评估的两件待办**(评估本身七轴已跑完、finding 已全部立成 [[INFRA-F114]]–[[INFRA-F128]],叙述见上方摘要与 [评估报告](./internal/_reports/2026-08-13-ds-assessment-axes-abcd.md)):① **6 份计划仍待起工** —— [闸扩面](./superpowers/plans/2026-08-12-rule-inventory-mirror-gate-extension.md) · [归档](./superpowers/plans/2026-08-12-live-tree-derivative-archive.md) · [场景路由](./superpowers/plans/2026-08-12-scenario-routing-single-source.md) · [PathA增量](./superpowers/plans/2026-08-12-path-a-legacy-host-increment-rule.md) · [判定表](./superpowers/plans/2026-08-12-element-decision-trace-product.md) · [UX场景](./superpowers/plans/2026-08-12-ux-scenario-coverage-expansion.md) ② ~~`AGENTS.md` 快车道「闸的判据」四字等 owner 确认原意~~ → **✅ 2026-08-13 已裁定并落地**(`46234b9f`):原意 = **`tests/`**,⛔ 不含 `scripts/` 下的闸脚本 ⇒ **改 `scripts/` 的闸脚本不走快车道**。⚠️ **2026-08-13 晚订正本行后半句**(登记为 [[INFRA-F124]] ④):此前这里与 AGENTS 那段 ⚠️ 注都写「⇒ 照常写 changeset」,而那是**依据 F117 落地前的 §「何时写」**推出来的 —— 同日 F117 已把判据收窄成 `files[]` 白名单。⇒ 正确表述 = **changeset 仍按 §「何时写」的 `files[]` 判据判,不在白名单里的内部 `audit-*.mjs` 属「不写」**。owner 的裁定实质未变,变的只是这半句转述。~~⚠️ 一个联动项:`§228` 把 `scripts/` 整个列为 consumer-facing 必写,F117 落地后要同步改~~ → **✅ 2026-08-13 已随 F117 一并落地(`5844130b`)**:`§228` 改为「`files[]` 白名单内那 20 个 `scripts/`」,并显式声明 **`files[]` 是唯一真源**、不在 AGENTS 里维护第二份会漂的清单。\n15\t>\n16\t> 7. **[[INFRA-F115]] 撤销旧 Figma PAT —— owner 2026-08-13 已同意,⏳ 待 owner 在 Figma UI 执行一步**(Settings → Personal access tokens 撤销那个旧 token)。**AI 侧结构上不可为**(⛔ 禁调 Figma API / 禁重签,见 §三 10),所以「它现在是否仍有效」只能由 owner 在该页确认。**影响面已核(2026-08-13,只看元数据未读任何凭据值)**:本仓所有读 Figma 凭据的脚本都走全仓唯一 parser `scripts/lib/figma-env.mjs` 读 `.env`(当前 PAT)· 旧 PAT 在本机的唯一驻留点就是 `.env.bak.1785390298`(`.env.local` 只有 `GITEA_HOST`、`~/.config/tvu/gitea-token` 是 Gitea 的)· **Gitea 与 GitHub workflow 里零处引用 Figma secret** ⇒ **本仓 / 本机 / CI 三面零影响,新 PAT 完全取代**。⚠️ **唯一核不到的**:`scripts/consumer-postinstall.mjs` 教 consumer 仓库设 GH secret `FIGMA_TOKEN`,MicroApps / NOC 那边那份值是新是旧**看不见**(别的仓库的 secrets)—— 撤销后若某 consumer 的 mockup conformance 报 403,就是它,重配即可。**⚠️ 2026-08-14 影响面重核(零 Figma API 调用、零凭据内容读取,只读元数据)**:那份明文副本当时**仍在**,`find` 全树(含 6 个 worktree)**精确 1 个命中** ⇒「本机唯一驻留点」有判据不只是断言 —— **该副本已于同日删除**(零引用已核、⛔ 未读其内容),但**删本地副本 ≠ 远端失效**,撤销仍只能 owner 在 Figma UI 做;读 Figma 凭据的文件现取 **12 个**(原 11,新增 `scripts/ds-health-scan-mockups.mjs`)、**12/12 全部走唯一 parser**;两 host 5 个 workflow 扫 `FIGMA` **零命中**(配阳性对照 `secrets\\.` 命中 3 行 ⇒ 非空过)。⇒ **三面零影响的结论未变。** 顺带查出一处不属本条的真缺陷(`consumer-postinstall.mjs` 教人配一个所给模板永远不读的 GH secret),已挂 [[INFRA-F115]] entry。\n17\t>\n18\t\n19\t> ### 二 · 等 designer(Figma 侧动手)\n20\t> ⭐ **2026-08-14 新增可交付**:⭐「拿错设计库」的清理清单已机械生成 —— [`_generated/foreign-library-cleanup.md`](./internal/_generated/foreign-library-cleanup.md),逐个换成当前 DS 库组件。**污染源只有两个 file**(`TVU UX Library` 六文件全中 · `Nancy's Design Assets` 三文件),⛔ 别引用清单里的数(契约 G4:重跑 `pnpm health:mockups` 现算)。它由 `ds-health-scan-mockups.mjs` 全量成功时重写,⛔ **别手改**。\n21\t> 9. **design-review-queue 4 条** —— #4 Notification pop confirm 问句标点不一致(owner 定如实提取、由 designer 在 Figma 统一)+ 3 条 designer-action(off-scale px / multi-select padding outlier / 缺 disabled 变体),全 live 2026-06-11 验证过。详见 [design-review-queue.md](./internal/design-review-queue.md)。**⚠️ 2026-08-03:#3「缺 disabled 变体」多了第 4 个成员 `Tab/Item`**(**条数不变** —— 既有条目长出一个成员,不是新条目)。它把这条从「三个零散控件」变成**需要一次统一裁定**:同族 `select box/filled` / `input box/filled` / `switch` / `radio` **都有** `enable` 轴,缺的这四个不是族惯例、是漏。~~裁定要连数值一起给(0.4 / 0.45 / 第三条路 三选一 + 一个数)~~ → **✅ owner 2026-08-13 已裁定:走 `token desaturation`,且「定一个数」这一问作废**(`--control-disabled-*` / `--text-disabled` / `--icon-disabled` 是 **per-theme 具体色值不是透明度** ⇒ 四分叉 0.4 / 0.45 / ≈0.5 / 0.6 全部作废;依据 = `FIGMA_AS_SOURCE_OF_TRUTH.md:71` 逐字禁止把 opacity-vs-token 当实现策略差 + 实测 token 路线已是多数派 **12 : 8**)。**designer 侧仍待动手** = 在 Figma 给这 4 个成员补 disabled 变体、按 token desaturation 表达 —— ⚠️ **2026-08-14 owner 裁定后它不再是 code 的前置**(Figma 无变体时 code 直接绑既有语义 disabled token 即可,不算发明数值;规则真源 `code-conventions.md` §R9 disabled 行,参照实现 `TabItem.vue`),补变体的目的是补齐设计真源。**code 侧待办** = [[INFRA-F120]](⚠️ 原并列的 `CANONICAL-F92` 已于 2026-08-14 删档 —— `Tab/Item` 的 code 侧四项实测早在立项前就已 shipped,结论搬进 `design-review-queue.md` §3 那条 🔑,那里另记了一条**待 owner 拍的一致性问题**:Tab 在 Figma 无变体的前提下已绑 token,与 F120 对 `Rating`/`Slider`/`Select` 的「无变体 ⇒ 等 designer」口径互斥)(⚠️ **2026-08-13 订正**:原写「改四个 + `Switch`/`InputNumber` 只需删多余 opacity 行」**已被实测推翻** —— 实为「三改 + 两个转为改 + 一个不动」,且三个改项在 Figma 无 disabled 变体、值仍等本条 designer 产出;观感会变,**必须过 owner 视觉签核**。逐条与证据在 [[INFRA-F120]] entry,另见 §一 7 那条待拍的例外)。\n22\t>\n23\t> ### 三 · 技术项未闭合(详情在 [backlog](./internal/backlog.md) §Active,此处只留最容易被漏的几条;条数别写死 —— 以 `pnpm run audit:status-consistency` 为准)\n24\t> 10. **变量层 ack 2026-10-28 到期即红**(原 INFRA-F79,**2026-08-13 已删档**:⛔ 禁止复现清单已搬进 `audit:variables-freshness` 的 PASS 自印输出 + `variables-staleness-ack.json` 的 `reviewQuestions` 两处真源,别再回写 backlog)。缺口按 **Figma plan = Professional** 的事实已闭合;出路只有 plan 升级(采购)或 Figma plugin 侧导出(未调研);MCP `get_variable_defs` **只能点验、不能替代 sync**。\n25\t> 11. **[[INFRA-F66]] 残余** —— `tvu-drop-down-list-select` 的 `:host` 尺寸未判定(docs React demo 零渲染实例,且它是 light-DOM CE、`:host` 语义不同不能照搬)。🔴 **2026-08-14 订正触发条件**:原写「触发 = 给它补 React demo 时一并判」并以为硬规则 #8 的闸会推动它 —— **实测那个闸的 in-scope 根本不含它**(无 slot、零 boolean prop),闸绿是空过;React 侧不渲染还是 `Select.tsx` 里一条显式裁定(`F45 OUT`)。⇒ **真触发 = owner 主动把它提为一级 demo 组件**,别等闸。(原 INFRA-F67 已于 2026-08-14 闭合删档 —— 三件残余全部实测已闭;(c-3) 那段「够格独立成 entry」的内容也已全部完成,给已完成的工作立新 entry 违反「完成即删档」。)\n26\t> 12. **尚无人接:只剩 [[INFRA-F75]],且它的体量 2026-08-14 被推翻** —— 它**不是**「NOC 迁 registry」:实测那份 `upstream-gate` 副本**从来没有** registry/token 配置,与本仓 `templates/upstream-gate-workflow.yml` 逐行比**只差 2 行包名**,且它当前连 `package.json` 都没有、在任何 runner 上都跑不起来。⚠️ 原记的「被 GitHub Actions 额度软阻塞」引的是**7 月**的月度额度,跨月后多半已失效(未实测,待 NOC 侧确认)。致病机制(DS 改 template 包名 → consumer 已复制出去的副本不会跟着改,且无人发现)已搬进 [`MIGRATION_TO_V1.md`](./MIGRATION_TO_V1.md) §3 并把扫描面从 `src` 扩到 `.github/workflows`。(~~INFRA-F90 docs 站 URL 无 section anchor~~ —— **✅ 2026-08-03 已 ship 并从 backlog 删档**,形态 = 路由后多一个尾段 `#/component//`,沿用 `#/changelog/` 的既有先例;**hash 路由只有一个 `#`,不存在第二个 fragment**,所以不可能做成 `#…#anchor`。⚠️ **两条如实登记的边界**:① slug 由标题文本派生 → **跨 locale 不解析**(中文站复制的链接在英文站只停在页面顶部 = 修复前行为,良性降级)② `/changelog` 与 `/`(overview)**不支持**段锚点 —— 前者尾段已被版本号占用。段落 slug 的**唯一定义** = `playground/docs/navigation.ts` 的 `slugifySectionTitle`,与 F88 视觉闸内联那份必须逐字一致,由 `tests/docs-section-anchor.test.ts` 的漂移闸钉住。**已发到真站并端到端验过**,签核可直接贴形如 `…/playground-dist/#/component/button/button-api` 的链接。)\n27\t>\n28\t> **第四条线(design-sync:Sync A 补齐 + runtime 刷新 + TopBar/MenuList 对齐 Figma,08-13 起 / 08-14 全部收口)**:叙述见 [CHANGELOG](./internal/STATUS-CHANGELOG.md) 顶条,判据 / 取证 / 通道归属 / 验证边界的真源在 [`.design-sync/NOTES.md`](../.design-sync/NOTES.md)。**本线在 STATUS 已无待办**。\n29\t>\n30\t> **本文档是项目状态 SoT**,也是 onboarding 链路的唯一 SoT。在 L-core 里它是 **#1**——**第 0 份是 [`FIGMA_AS_SOURCE_OF_TRUTH.md`](./FIGMA_AS_SOURCE_OF_TRUTH.md)**(见下方 §起手必读链路 的 L-core 表,那张表是次序真源)。本文件早于 PROJECT_GOAL.md 读,因为它直接告诉你\"在哪\"。\n31\t\n32\t> 任何 session wrap up 时**必须更新本文档**(见末尾\"Wrap-up 协议\")。\n33\t>\n34\t> ⚠️ **排期 SoT 在 [`retrospection/design-spec-canonical-alignment-tracker.md`](./internal/retrospection/design-spec-canonical-alignment-tracker.md)**——本文件 Version Roadmap 段只是镜像。任何 \"v0.X 包含哪些 / 先做哪个\" 决策前先读 tracker 的 \"排期原则\" 自检清单。\n35\t\n36\t---\n37\t\n38\t## 一句话目标\n39\t\n40\t把 Figma 已发布 Library 做成 **AI 与开发可消费的双向 Figma↔Code 桥**(详见 [`PROJECT_GOAL.md`](./PROJECT_GOAL.md))。\n41\t\n42\t---\n43\t\n44\t## Claude Code Plugin\n45\t\n46\tUX 团队 AI workflow skill 的独立分发轨道(与 npm 包版本独立)。详见 [`docs/PLUGIN.md`](./PLUGIN.md)。\n47\t\n48\t---\n49\t\n50\t## 当前版本:v1.2.0(✅ **published & verified 2026-07-31** —— 四步核验俱全(tag→CI 历史首跑 + registry API 两路 + 真取回 tarball 逐字核 sha1 + owner 人眼核 Packages 页)。**完整取证实录 2026-08-13 已逐字下沉** [STATUS-CHANGELOG](./internal/STATUS-CHANGELOG.md) §「v1.2.0 发布核验实录」——⛔ 别在本行找 run 号 / sha1 / 解包抽验清单。**核验协议真源 = [`RELEASING.md`](./RELEASING.md)**(registry API 两路 + 真取回 tarball + Packages 页人眼亲验;硬纪律,API 绿不免除 —— v0.1.0/v0.1.1 曾 silent fail 1-2 周)。)\n51\t\n52\t| 项 | 值 |\n53\t|---|---|\n54\t| v1.2.0 内容 | **4 minor + 3 patch**(全 additive,无组件 API 移除/改名):`./web-components` 出口(React / 原生 CE 第一次有 npm 消费路径;⚠️ tarball 2.84 → 4.74 MB,+67%)· Select 触发器补 combobox ARIA · `peerDependencies` 改 `vue: ^3.5.0`([[INFRA-F85]])· 浮层层级 token 化(`--z-dropdown` / `--z-tooltip` / `--z-modal` / `--z-select-portal`)·(patch)I18N-01 可见文案 key 真被组件消费 + 防回归闸 · registry 改走 HTTPS 标准端口(原 INFRA-F74,已删档)· UserMenu 面板对齐 Figma `DtZcMkhNy6qh6jbQQnhreQ` node `6423:85`。逐条详情见 [`CHANGELOG.md`](../CHANGELOG.md) |\n55\t| 本次 publish | ⏳ **走 tag→CI**(`.gitea/workflows/publish.yml`,tag `v1.2.0`)。**这条链此前从未执行过一次**(Gitea 1.22.6 没有 `workflow_dispatch`,因此本 host 无干跑能力;恢复干跑的前置 = 升 Gitea ≥1.23)。三个必须逐段读的观察点:① pre-flight 凭据闸(A 读 / B **真写一次 probe** / C 删除并重读列表核实)② changesets-consumed guard ③ `pnpm publish` 本体。401/403 的读码方式写在 workflow 注释与 `RELEASING.md` §Troubleshooting |\n56\t| 包名 | `@ux-team/tvu-design-system`(团队 Gitea registry)。GitHub Packages 上旧包名 `@nancyzeng0210/tvu-design-system` 的 15 个版本(≤1.1.0)**刻意保留不删**(rollback 退路;⚠️ **2026-08-14 订正**:括号里原写的第二条理由「MicroApps/vue-app 仍钉 `^0.6.1`」**已为假** —— 该仓 `111c408`(2026-08-07)已迁到 `^1.2.0`,两个 consumer 都在新 registry 上了。**「别清旧包」这条禁止动作本身仍成立**,靠的是 rollback 退路那条),此后不再有新版本发到那里 |\n57\t| 上一版本 | v1.1.1 —— ✅ published & verified 2026-07-30T02:39:15Z(Gitea registry,**本机 `scripts/publish-to-gitea.sh` 发**,因为 tag→CI 的 secret 当天才修好;三路核验 + owner 人眼确认俱全,叙述归档在 [STATUS-CHANGELOG](./internal/STATUS-CHANGELOG.md))|\n58\t| 安装 | `pnpm add @ux-team/tvu-design-system` + Gitea `.npmrc`(**HTTPS 标准端口**:`https://product-demo.tvustream.com/gitea/api/packages/ux-team/npm/`)+ **Gitea** token(`read:package`;GitHub PAT 不行,Gitea 在 `authGroup.Verify` 就拒)。步骤见 [`RELEASING.md`](./RELEASING.md) §External consumer setup |\n59\t| Release 流程 | changesets + **tag-triggered 自托管 Gitea CI** + strict audit 链(**条数别写死 —— `prepublishOnly` 是链的 SoT,要数就读它**;此处曾写「32 条」而 2026-08-05 实测 37 步 = 35 条 `audit:*` + `lint-skills` + `lint:ds`)+ Node 20/22 matrix(vitest 仅 Node 22 —— 3 个 audit 脚本靠 Node≥22 原生 TS 类型剥离)+ changesets-consumed guard + **render-gate 前移到切 tag 时在本机强制**(不在 CI:Gitea runner 非特权装不了 chromium 系统库)。GitHub 侧 `gates.yml` = dispatch-only、无发布能力,⚠️ 别给它恢复 tag trigger |\n60\t| 破坏性 (1.2.0) | **无 API 破坏** —— 组件 API / 样式 / token 均无变化。但有一条 consumer 侧硬门槛:**peer 下界升到 `vue ^3.5.0`**,钉 `3.4.x` 的 consumer 装不上。那条「支持 3.4」事实上早已不存在(shipped 代码在用 Vue 3.5 才有的 `useId()`,3.4 上渲染 Tooltip/Select 当场报 `useId is not a function`)——本版删掉的是一句假声明,不是砍掉能用的支持 |\n61\t| 版本详情 | [`CHANGELOG.md`](../CHANGELOG.md) |\n62\t| 注 | ⚠️ 生态:`vue@3.5.36`(曾是 npm latest)官方发布产物损坏(`workspace:*` 未替换),consumer fresh install 需钉 `3.5.35` 或本仓库在用的 `3.5.32`;与本包发布无关 |\n63\t\n64\t---\n65\t\n66\t## 能力 × 成熟度(单一真源表 · INFRA-F58)\n67\t\n68\t> 5 能力定义真源 = [`PROJECT_GOAL.md`](./PROJECT_GOAL.md) §一句话目标;本表只登记**当前成熟度 + 该能力状态的单一真源**,避免\"读了 PROJECT_GOAL 承诺信以为真\"(assessment §5 承诺-vs-实现)。成熟度变化改本表。\n69\t\n70\t| # | 能力 | 成熟度 | 状态单一真源 |\n71\t|---|---|---|---|\n72\t| 1 | 开发 npm install 即用(Vue 组件 / token / 图标 / 样式) | 🟡 **partial** — Vue 全通;**token = CSS 变量 + DTCG JSON + TS 出口**(`./tokens` DTCG · `./tokens/js` resolved TS,INFRA-F55 支柱①);**React 无 published npm 路径**(经 CE + `react-pilot` 内部 bindings,非 `./react` 导出) | `package.json` exports + PROJECT_GOAL §Token 架构 + assessment §5 |\n73\t| 2 | AI 拿 Figma URL → 定位代码 1:1 还原 | ✅ **done** — manifest 确定性验证 | `figma-data/render-verification-manifest.json`(936)+ FIGMA_AS_SOURCE_OF_TRUTH.md |\n74\t| 3 | AI 拿 代码 → 生成 / 还原 Figma | ⚠️ **DEFERRED(bypass equivalent)** — DS 代码 _可_ 经 manifest + 唯一库 `YbsPRUVmNdsbN40NNwh1Gn` 还原;缺的仅\"全自动 Code Connect publish\"(Pro plan 401)+ 非 DS 反查 + MCP config | PROJECT_GOAL 能力3 + `CAPABILITY_3_BYPASS.md` |\n75\t| 4 | AI 拿 文字/链接/截图/代码 → UX 效果图 + 可运行代码 | 🟡 **gate + AI 辅助合成**(非全自动生成器);mockup 确定性后验强制化 = F55 缺口 A | PROJECT_GOAL 能力4 + assessment §4 支柱② 设计网 |\n76\t| 5 | 每个 Code 组件可追溯 Figma 来源 | ✅ **done** — canonical `data-figma-*` + manifest N:1 | canonical 组件 `data-figma-*` 属性 + manifest |\n77\t\n78\t---\n79\t\n80\t## Version Roadmap(剩余按版本线分组)\n81\t\n82\t> 本段只留 **open / blocked** 项——已 shipped 版本(v0.2.0–v0.7.0)逐版本 retrospect + 历史完成项在 [`design-spec-canonical-alignment-tracker.md`](./internal/retrospection/design-spec-canonical-alignment-tracker.md) §轨道 A 已完成 / §Release 排期(完成叙述不在 STATUS 累积 — status-keep-only-unfinished)。\n83\t\n84\t### ✅ v1.0.0(稳定承诺 — API 锁定 · **已发布 2026-07-20**)\n85\t\n86\t> **published & verified**:GitHub Packages `1.0.0` created 2026-07-20T10:33:19Z · CI run [29735085984](https://github.com/NancyZeng0210/TVU-Design-System/actions/runs/29735085984)。首个稳定版,公开 API 锁定([`API_STABILITY.md`](./API_STABILITY.md));scope = 组件保真镜像层(36 组件 + token + 图标 + 双向 Figma↔code 桥),产品构建层(Table/Form/layout/pattern)列 v1.x/v2。\n87\t> **触发条件回顾**(全满足):5 能力交付(能力 3 旁路 ack)· L5 口径 A(tooling ships + MicroApps adopts)· color-contrast owner-accept 收口 · burn-in waived · RC soak(MicroApps Console ≥1 周 0 critical,owner 2026-07-20 sign-off go)。\n88\t\n89\t### 🔵 v1.3.0(**规划中** — 排期层 2026-08-13 重建)\n90\t\n91\t> **排期 SoT 在 [tracker `### v1.3.0`](./internal/retrospection/design-spec-canonical-alignment-tracker.md),本段只是指针,别在这里找批次内容。**\n92\t> 缘起:原排期图终点是 v1.0.0,2026-07-20 **达成**后没有人画第二张图 ⇒ 排期层空了 4 周,\n93\t> 期间 backlog 涨到 57 条且**无一条有版本归属**(表现 = 一堆 High/Medium 谁也说不上先做哪个)。\n94\t> owner 2026-08-13 拍「先补规划层,别急着往下做条目」。\n95\t> **分拣的主要产出是认定大多数 entry 不该排队**(17 条是「下次碰 X 时」的触发式)。\n96\t> ⚠️ **「57」这个数尚未经核对** —— 当日抽样两次命中 stale([[INFRA-F119]] 可关一半 · 原 INFRA-F122 存量 2→6(该 entry 2026-08-14 已落地删档)),别把它当工作量。\n97\t\n98\t| 后续 | 版本线 |\n99\t|---|---|\n100\t| ~~批次 A — consumer 面发布正确性~~ → **✅ 2026-08-13 全部 ship(`5844130b`)**:F114 / F117 已删档、F105 只剩 ①③④;顺带闭合 F102。终态判据与留下的已知缺口(`./web-components` 仍无 types)全在 [tracker `### v1.3.0`](./internal/retrospection/design-spec-canonical-alignment-tracker.md),⛔ 别在这里找 | v1.3.0 |\n101\t| 批次 B 凭据卫生 · 批次 C 让已有的闸真的守住 · 批次 D 大件(Tier 1-C ESLint plugin / F62 / F60,**起不起由 owner 拍**)| v1.3.0 / 待拍 |\n102\t| 产品构建层剩余(layout 原语 / pattern 层)—— APID-02 Form 校验引擎 + APID-01 Table 状态层均已随 **v1.1.0** 发布 | v1.x / v2(backlog INFRA-F68 Batch D/E/G)|\n103\t\n104\t### ⚪ Deferred / Out of scope\n105\t\n106\t| 项 | 状态 | 理由 |\n107\t|---|---|---|\n108\t| **能力 3 (AI code→Figma)** | DEFERRED bypass shipped | Figma Pro plan 限制;[`CAPABILITY_3_BYPASS.md`](./CAPABILITY_3_BYPASS.md) 提供等价方案 |\n109\t| **T1c Extract Pipeline** | PAUSED | plan owner \"元层疑问\"未解 |\n110\t| **Phase 8** 视觉脚本 + Code Connect | DEFERRED | 需 Figma Org plan 升级 |\n111\t\n112\t---\n113\t\n114\t## Active 后续工作\n115\t\n116\t```\n117\tBacklog (active) (32): INFRA- F58·F60·F61·F62·F63·F66·F68·F69·F75·F81·F86·F91·F101·F105·F106·F107·F115·F120·F123·F129·F131·F133·F134·F137·F138·F139 · CANONICAL- F92–F94(打包入口·现只含 F93+F94)·F93·F94·F95·F104 · META-DSYNC-01 —— 计数镜像;状态/待办/⛔ 全在 backlog.md ## Active 各自 entry(C4 机械核)。⛔ 这串别手抄,从活源生成:`grep '^### ' docs/internal/backlog.md`\n118\tdesign-review-queue (4): 设计侧待 designer 动手(off-scale px / multi-select padding outlier / 缺 disabled 变体 / Notification pop confirm 标点)—— 计数镜像,与 §二 9 同口径。⛔ 各条 live 复核日期**别在此抄**(三条不同日),见 design-review-queue.md 各条自带实测行。✅ 2026-08-21 起有闸:`audit:status-consistency` C6(判据 = 真源 `designer-action: yes` 条数,核三处镜像)\n119\tCode-leads divergences (3): msg-bg-tinted-dark / chart-color-palette / pill-component-family — 见 translation/divergences-decisions.json\n120\tDeferred (3): 能力3 bypass · T1c · Phase 8\n121\t```\n122\t\n123\t**真正 next 可推进的**(2026-08-05 复核,**此前三处指路句已 stale 并就地删除**:f73 plan 的「轨道 A 发 1.1.0,卡 owner 建 Gitea PAT」—— 1.1.1/1.2.0 都已发完;`1.1.2` 那条载荷路线 07-31 已作废;`2026-07-30-v1x-next-batch` 的 **10 个 Task 已全部执行完**,Task 10 = 发 v1.2.0):[[INFRA-F104]](render-gate 降级判据字段化)**已于 2026-08-07 ship 并从本段删档**(数字/闸细节见上方 Last updated 摘要)——⚠️ **本段已被排期层取代 —— 「下一个做什么」的答案现在在 [tracker `### v1.3.0`](./internal/retrospection/design-spec-canonical-alignment-tracker.md),别在本段挑**(本段历来是\"零散指路句\",而 2026-08-13 的分拣证明零散指路正是排期层空缺的症状:57 条 entry 无一条有版本归属)。~~**建议最先** = v1.3.0 批次 A 三条 consumer 面发布正确性~~ → **✅ 2026-08-13 已 ship(`5844130b`)并删档**(F114 / F117 / 顺带 F102;F105 只剩 ①③④)。**不等 owner、不等 designer 的**(~~F98~~ 2026-08-06 已 ship 删档 · ~~F119~~ **2026-08-13 已完全闭合并删档**:步骤①亲验发现 2026-07-31 就已存在于 `release.mjs` step 1c、步骤② 76 张基线已 ship `3cb3e36b`)= ~~[[INFRA-F100]]~~ → **✅ 2026-08-17 整条落地并删档**(三条结构缺口 + 最后那条「37 行豁免按 CE 语义逐行复核」)。**封路理由与诚实边界已全部搬进 `scripts/audit-render-drift-gate-react.mjs` 头注释**(闸每次运行自印),⛔ 别再来 backlog 找这个号 · **Tier 1-C** `@ux-team/eslint-plugin-tvu-design-system`(能力 1 加固,tracker 估 ~2-3 周,自 v0.6.0 挂到现在 —— 「大所以推后」逐字命中 tracker §排期原则反模式表,要继续推后需要一个**不是\"大\"的**新理由,起不起由 owner 拍)。另有 RTL-01 / F68 FID-04 M1 role-map 全量铺开,各自成批。design-review-queue 4 条待设计师(⚠️ 此处 2026-08-21 前一直写 **3**,是本文件里第三处 stale 的同一个量 —— F136 立项时只发现两处;现由 `audit:status-consistency` C6c 吃**所有**出现处)。\n124\t\n125\t**排期决策必读**:[`retrospection/design-spec-canonical-alignment-tracker.md`](./internal/retrospection/design-spec-canonical-alignment-tracker.md) §排期原则 — **不按耗时 / 复杂度 / 成本最低排,按项目目标对齐 + 依赖解锁 + 自动化标准化排**。\n126\t\n127\t---\n128\t\n129\t## 起手必读链路\n130\t\n131\t> **本节是 onboarding 链路的唯一 SoT**(AGENTS.md §必读链路 只登记任务触发表,不再维护并行清单 — 2026-06-10 system-review P1-07/P1-08 重构为两层,消除双链路 drift + 与仓库 lazy-load 原则对齐)。\n132\t>\n133\t> **⛔ Mandatory Gate**:任何 AI session 在第一个项目相关回答 / 推荐 / 任务前,**必须全文读完 L-core 四份**,并读完命中触发条件的 L-ref 最小集。机械执行:用 TodoWrite / TaskList 为 L-core 每项 + 命中的 L-ref 项各建 1 个 todo,逐个 Read 完才能回答。基于 partial L-core 给推荐 = **协议违反**。**唯一的减档 = 下方 [§微改档](#微改档单文件纯文案的减档)**(owner 2026-08-13 裁定新增),判据不满足即回落本档、无第二个例外。\n134\t>\n135\t> **体量口径 —— 本行是唯一真源**(`AGENTS.md` §Onboarding Gate 只指回这里,刻意不复述数字):**2026-08-04 `wc -c` 实测 65.2 KB** = 三份固定文件 59.8 KB(FIGMA_AS_SOURCE_OF_TRUTH 8.1 + 本文件 37.0 + PROJECT_GOAL 14.7)+ 当前 pickup(本轮那份 5.4)。⚠️ **引用前先自己重跑** `wc -c` 那四份 —— 它们每工作日都在涨,本行也会漂。此前这里与 AGENTS 两处都写着「~40KB ≈ 10-15min」,而 2026-08-03 实测已是 **90.5 KB**、失真 **2.2×**(原 INFRA-F95 已付代价 4 —— **该 entry 三项待做全部闭合、2026-08-13 已删档**;本轮清理让本文件从 63.7 → 37.0 KB,L-core 因此回落到 65.2)。⚠️ **2026-08-13 实测 L-core 四份已回涨到 ~74 KB**(本文件 ~45 KB)—— 正是本行自己说的「本行也会漂」,**别引用这两个数,自己跑 `wc -c`**。**别再写死耗时** —— 那正是下方「历史实证」里 gate 被默读架空的机械成因。\n136\t\n137\t### 微改档(单文件 · 纯文案的减档)\n138\t\n139\t> **owner 2026-08-13 裁定新增。这是本链路唯一的减档,本节是它的唯一 SoT**(`AGENTS.md` §Onboarding Gate 只留一行指针,刻意不复述判据 —— 复述一份就是第二处会漂的副本,[[INFRA-F121]] 已付过这个代价)。\n140\t> 缘起:此前唯一豁免是「用户首条 query 明显非项目相关」,于是「把这句 UI 文案从 A 改成 B」也要先吃 65 KB。gate 设严的原因是 2026-05-13 跳读致首轮推荐漏 4 项硬约束,所以减档不是取消 gate,而是**把省下的风险交给下方升级条件接住**。\n141\t\n142\t**适用判据(四条全中才算,任一不中 → 回落完整 L-core)**:\n143\t\n144\t1. 改动落在**单个文件**内;\n145\t2. 性质是**纯文案 / 措辞**(UI 可见文本、注释、文档行文、错误提示字串);\n146\t3. **不换组件、不改 token、不加删元素、不动布局**,也不涉及组件选型判断;\n147\t4. 不是 mockup 写操作,也不是推荐 / 排期 / 裁定 / 发版类回答。\n148\t\n149\t**微改档要读的(省下 STATUS 本文件 + PROJECT_GOAL + 当前 pickup 三份)**:\n150\t\n151\t| # | 文件 | 为什么它不能省 |\n152\t|---|---|---|\n153\t| 0 | ⭐ [`FIGMA_AS_SOURCE_OF_TRUTH.md`](./FIGMA_AS_SOURCE_OF_TRUTH.md) 全文 | 文案也可能踩「code 反向要求改 Figma」;本文件是唯一能拦住它的 |\n154\t| — | [`AGENTS.md`](../AGENTS.md) §硬规则表 | 硬规则里的写边界 / commit 纪律与改动大小无关 |\n155\t\n156\t**⛔ 自动升级条件(硬 —— 命中任一即当场停下补读完整 L-core 再继续,不许「就差一点,先改完」)**:\n157\t\n158\t- 发现要动的不只是文案:要**换组件**、要**改 / 新增 token 或写字面量**、要**加删元素或改布局**;\n159\t- 要动**第二个文件**(含\"顺手把生成产物也重跑一下\");\n160\t- 触到**组件选型**(该用 A 还是 B)、**Figma 真源判断**、**divergence 登记**;\n161\t- 用户在同一 session 里追加了任何非微改任务,或要求推荐 / 排期 / 裁定;\n162\t- 自己不确定判据 1-4 是否满足 —— **不确定就是不满足**。\n163\t\n164\t**⛔ 本档不放宽的**:mockup 写操作仍走 `AGENTS.md` §Mockup Write Gate 4 步前置 + §必读链路 7-11 整链(不受本档影响);任何写 Figma 的动作照旧要显式授权。\n165\t\n166\t### L-core — 每 session 全文必读(禁 grep / 跳读 / 摘要替代)\n167\t\n168\t| # | 文件 | 作用 |\n169\t|---|---|---|\n170\t| **0** | ⭐ [`FIGMA_AS_SOURCE_OF_TRUTH.md`](./FIGMA_AS_SOURCE_OF_TRUTH.md) | **最高优先级原则** — Figma 真源 + 唯一合法 divergence + 禁止启发式验证 |\n171\t| 1 | **本文件 STATUS.md** | 知道在哪(状态镜像 + 本链路 SoT) |\n172\t| 2 | [`PROJECT_GOAL.md`](./PROJECT_GOAL.md) | 知道目标(5 个能力 + 受众 + 约束) |\n173\t| 3 | [`_plans/next-session-pickup-*.md`](./internal/_plans/) 最新一份
**⚡ 当前活跃优化程序(固定指针 · 不靠 mtime · 并行 session 再写新 pickup 也不漂移)**:[全生命周期优化](./internal/_plans/next-session-pickup-2026-07-08-full-lifecycle-optimization.md) → 存档 SoT [`full-lifecycle-assessment-2026-07-08`](./internal/full-lifecycle-assessment-2026-07-08.md)(tracked = backlog **INFRA-F55**) | 当前 sprint 操作手册 |\n174\t\n175\t### L-ref — 最小集必读 + 命中触发再深读(各文件顶部有「🤖 AI 读取指引」)\n176\t\n177\t| 文件 | 每 session 最小集 | 升级为全读 / 深读的触发 |\n178\t|---|---|---|\n179\t| [`AGENTS.md`](../AGENTS.md) | §硬规则表(含 Enforcement 层级列)+ §Onboarding Gate | 写 prompt / 审 executor → §工作流 + task-type 矩阵;commit 前 → §Git 工作流;**mockup 任务 → §Mockup Write Gate + §必读链路 7-11 整链升 mandatory** |\n180\t| [`tracker`](./internal/retrospection/design-spec-canonical-alignment-tracker.md) | §排期原则 | 任何\"v0.X 包含哪些 / 先做哪个 / 该不该上 Tier N\"决策 → 全读 |\n181\t| [`backlog.md`](./internal/backlog.md) | — | 当前 sprint task 对应 entry → **全文 Read(不是 grep)**;新增 entry → 先 grep 全部已用 ID |\n182\t| [`meta-rules.md`](./meta-rules.md) | 触发器目录(标题扫一遍) | 写 prompt / 设计机制 / 推荐方案前 → 反模式清单全读 |\n183\t| [`code-conventions.md`](./internal/code-conventions.md) | — | **写 UI 代码的任何任务**(Vue / React / HTML — 含 `playground/docs/*`、`src/components/*`、下游产品 demo 与 PoC)→ 顶部 **§🤖 AI 读取指引 的「起手必读段」**(§R0 Phase 0 元素→组件映射 + §R7 四场景判断 + Task Entry Modes 的唯一活源),单条 R-rule 按该表触发条件 jump。⛔ 禁全量吞(近 90 KB);⛔ 跳过起手必读段直接进 R-rule = 协议违反。**注**:机械路径 `detect-figma-task.sh` 只在 prompt 含 `figma.com/(design\\|file)/` URL 时触发,**没有 Figma URL 的 code 任务全靠本行**([[INFRA-F121]] ①) |\n184\t| [`working-principles.md`](./working-principles.md) | 原则 0-8 标题 | 实现决策(命名 / token / API 形态)命中 → 对应原则全读 |\n185\t| [`translation/`](../src/design-system/translation/) 4 文件 | — | Figma↔Code 命名 / divergence / alias 决策时查对应文件 |\n186\t| mockup 链(AGENTS §7-11 + [`figma-component-catalog.md`](./internal/figma-component-catalog.md)) | — | **mockup 任务整链升 mandatory**(Mockup Write Gate 的 4 步前置不变,仍是硬规则) |\n187\t\n188\t> **违反信号(分层版,命中任一 → 停下重读)**:\n189\t> - L-core 没读完就给项目相关回答 / 推荐 → 错(\"我已经知道大概了 / 状态简单跳一步\" 同罪)\n190\t> - L-core 或 backlog 当前 task entry 用 grep / 摘要替代全文 Read → 错\n191\t> - 命中 L-ref 触发条件却只读了标题 / 最小集 → 错(如排期决策没全读 tracker、mockup 任务没读 §7-11)\n192\t> - \"memory 兜底替代 SoT\" → 错(memory 是 AI 缓存,项目契约真源在仓库)\n193\t>\n194\t> **历史实证**:2026-05-13 session 10 跳过 PROJECT_GOAL + AGENTS → 首轮推荐缺 4 项硬约束(canonical SoT / plan owner 边界 / working-principles / meta-rules)→ 用户返工纠偏。2026-06-10 system-review P1-08:旧版\"全量读 ~225KB(mockup +270KB)标 30min\"失真 → gate 被默读架空;两层化让严格性落在读得完的集合上。\n195\t\n196\t---\n197\t\n198\t## Wrap-up 协议\n199\t\n200\t> **session 收尾时读** [`docs/WRAP-UP.md`](./WRAP-UP.md)(每-session STATUS 必改项 + Release wrap-up + Retrospection 触发判断)。\n201\t> 核心一条:顶部 \"Last updated\" 改到今天 + 当日摘要(旧摘要 prepend 进 STATUS-CHANGELOG.md);SessionEnd hook 自动核验日期。\n202\t\n203\t---\n204\t\n205\t## 文件关系(防混淆)\n206\t\n207\t| 文档 | 用途 | 更新节奏 |\n208\t|---|---|---|\n209\t| **STATUS.md**(本文件) | 全局状态镜像 + 版本线分组 + Active 余量 | **每 session** |\n210\t| `PROJECT_GOAL.md` | 项目目标 + 5 个能力 + 受众 + 约束 | 大方向变才改(罕见) |\n211\t| `_plans/next-session-pickup-*.md` | 当前 sprint 操作手册(prompts / 任务顺序 / dirty 协议) | **每 sprint** |\n212\t| `CHANGELOG.md` | Release-facing(外部 consumer 看)| 每 release |\n213\t| `backlog.md` | 全量 entry 详情(Active only,完成直接删) | 每发现 / 每完成 |\n214\t| `retrospection/design-spec-canonical-alignment-tracker.md` | 设计规范完整计划 + 进度时间线(living doc)| **每 session wrap-up 前同步** |\n215\t| `retrospection/*.md` | 阶段复盘(决策 / 反模式 / 教训) | 每阶段完成 |\n216\t| `internal/STATUS-CHANGELOG.md` | 历史 session changelog 归档(从本文件拆出) | 每 session wrap-up |\n217\t| `WRAP-UP.md` | session 收尾协议(STATUS 必改项 / Release / retrospect 触发) | 罕见 |\n218\t| `PLUGIN.md` | Claude Code plugin 独立分发轨道 | 每 plugin release |\n219\t\n220\t**真源关系**:STATUS.md 是各 SoT 的**镜像/导航**,不是 SoT 本身。具体决策仍在 PROJECT_GOAL / pickup / backlog / CHANGELOG。\n221\t\n222\t### SoT 归属表(哪类事实以谁为准 · INFRA-F58)\n223\t\n224\t> AI 读多份文档遇到冲突时,**以本表指定的真源为准**,其余处一律视为镜像/指针(镜像 stale 时以真源修镜像,不反向)。\n225\t\n226\t| 事实类型 | 唯一真源 | 说明 |\n227\t|---|---|---|\n228\t| **npm 包当前版本号** | STATUS §当前版本(字面版本号只此一处)| README/PLUGIN/GETTING_STARTED/AGENTS 一律\"见 STATUS\",不写字面版本(de-mirror 闸 `no-version` mode 强制)|\n229\t| **docs 站要不要跟着发版发布** | [`RELEASING.md`](./RELEASING.md) §Step 4 | = **owner 决定,不是 REQUIRED**(owner 裁定 2026-07-31,此前 Step 4 写 REQUIRED / [[INFRA-F84]] 残余① 写 owner 决定,两处各说一套)。测量口 = `pnpm check:docs-site-version`(三态 `0`/`1`/`2`,`2` 当 `0` 用就是假绿),别处只指回 Step 4 |\n230\t| **layout 断点 / 容器宽的数值** | `src/tokens/variables.css` §`── Layout breakpoints ──` + §`── Layout containers ──` | code-first(owner 拍 2026-07-31,登记在 `divergences-decisions.json`);CSS `@media` 吃不了 `var()` → 引用的可校验形式 = 字面量 ∈ token 值集合,`audit:layout-tokens` 机械核;非 CSS 消费方走 `./tokens` DTCG + `./tokens/js`(同一份文件派生,不存第二份)|\n231\t| **plugin 版本号** | `PLUGIN.md` §版本表 | 与 npm 版本独立;de-mirror 闸 `no-npm-version` mode 放行本文件自身 plugin 版本 |\n232\t| **发版历史 / changelog** | `CHANGELOG.md`(外部)+ `STATUS-CHANGELOG.md`(内部)| — |\n233\t| **排期 / 版本包含哪些** | `retrospection/design-spec-canonical-alignment-tracker.md` §排期原则 | STATUS Version Roadmap 段是镜像 |\n234\t| **Active backlog 全量** | `backlog.md` §Active | STATUS \"Active 后续工作\" 是计数镜像(C4 gate 核)|\n235\t| **5 能力定义** | `PROJECT_GOAL.md` §一句话目标 | 能力**成熟度/状态** → STATUS §能力×成熟度表 |\n236\t| **Figma↔Code 真源原则 + 合法 divergence** | `FIGMA_AS_SOURCE_OF_TRUTH.md` + `translation/divergences-decisions.json` | — |\n237\t| **组件公开 API(props/values)** | 组件 SFC `defineProps`(如 `ButtonBridge.vue`)+ 文档站组件页 | 文档示例必须与 SFC 一致;F58 实证 GETTING_STARTED/README 曾漂移 |\n238\t| **AI 协作硬规则 / 起手链路** | `AGENTS.md` §硬规则 + STATUS §起手必读链路 | 链路 SoT 在 STATUS,AGENTS 只登记任务触发表 |\n239\t| **文档间\"改 X 复查 Y\"依赖** | `docs/internal/doc-sync-map.json` | audit:doc-sync 校 |\n240\t"}]},"parent_tool_use_id":null,"session_id":"ccca31c3-4a85-4094-9f46-4533df53f8ce","uuid":"92acc26d-a99e-4768-a0e7-a8399f0f90e7","timestamp":"2026-08-25T09:21:22.054Z","tool_use_result":{"type":"text","file":{"filePath":"/Users/nancy/.ai-ds-lab/pins/tvu-ds-4a68e02d/docs/STATUS.md","content":"# TVU Design System — Status\n\n> **Last updated**: 2026-08-25 —— **落地线第三十轮:mockup conformance 合成单进程引擎 + 给闸的 stdout 定输出契约**(**Active 32 → 32**:新增 [[INFRA-F139]]、删档 INFRA-F132)。执行外部 lab 的两份处方(第 7 / 7b 步),⛔ 不是自选题。
🔴 **本轮最值钱的一条:给 11 条在链闸补一个「分母」字段,当场照出一条 L5 闸的绿三个月来不可解读。** `audit:figma-conformance` 的扫描面 `src/canonical/generated/*.vue` 实测 **0 个文件** ⇒ 每次发版都绿、绿无信息量。修法是 owner 裁定(退役 vs 改指向,两条都改发布链判据强度)⇒ [[INFRA-F139]] + 收割器里具名 shrink-only 豁免(照样每次打印)。**这不是契约引入的缺陷,是契约让一个一直存在的空分母第一次可见。**
**引擎实测**:进程 10 → **1** · 请求 12 → **3** / 大 payload 8 → **1**(请求计数器自证,⛔ 不用耗时代理)· 同一 fileKey 整文件 140s → **27.0s**(且在多跑一条规则的前提下)· 规则 9 → **10**。**规则清单真源从「代码位置」改成「一条命令」**(`--list-rules`)—— 指代码位置本身就是 stale 源。
**契约实测**:11 条在链 `figma-sync` 闸全部上契约,收割器 **11/11 解析出契约块、11/11 读出 findings 计数**(上契约前 10 条在吐 JSON、只有 **4** 条读得出)。选择面**钉 npm key**、⛔ 不钉文件特征。
**B1 = 这一族闸历史上第一个自动执行点**:`.claude/hooks/post-figma-write.sh` 每次 `use_figma` 写后自动后台跑引擎,fileKey **从 prompt 里的 Figma URL 捕获**(不是写死常量)。⚠️ L4,绕过面如实登记。
⚠️ **三条注入证明非空过**,其中一条打的是**接线**(摘掉 `failed` 表达式里一项 → 1 红),纯 import 单测覆盖不到那一半。
⛔ **数别抄,跑**:`pnpm report:gate-output-harvest` · `pnpm audit:mockup-conformance --list-rules`。验收逐条实测 / 两个既有缺陷前后对照 / KNOWN_SILENT 增删行 / 刻意偏离处方的理由 / 处方自身两处数字偏差,全在 [STATUS-CHANGELOG](./internal/STATUS-CHANGELOG.md) 顶条,⛔ 别在本行找。\n> ——\n> **更早各轮(session I–X)摘要已逐字归档**在 [STATUS-CHANGELOG](./internal/STATUS-CHANGELOG.md);仍需接手人知道的**状态性事实**已各归其唯一真源 —— 主机拓扑 [`DEPLOY.md`](./DEPLOY.md) · docs 站发布口径 [`RELEASING.md`](./RELEASING.md) Step 4 · build 顺序 `scripts/check-dist-wc-freshness.mjs` 头注释 · 各闸的覆盖面与豁免语义在各自脚本头注释且**每次运行自印** · 其余在 [backlog](./internal/backlog.md) 各 entry。⛔ 别再往本段回写完成叙述,闸会拦。\n>\n> ### 一 · 等 owner 拍板(本仓库)\n> 0a. **docs 站 644 张图标预览线上仍坏 —— 源码已修,等一次 docs 站 build + 发布**(`designAssetData.ts` 曾把 dev-server 专用的 `/@fs<绝对路径>` 前缀逐字带进产物)。⛔ 这不是代码待办,是**发布决策**:口径真源 [`RELEASING.md`](./RELEASING.md) §Step 4(= owner 决定,不是 REQUIRED);测量口 `pnpm check:docs-site-version`(三态,`2` 当 `0` 用就是假绿)。修复经过在 [STATUS-CHANGELOG](./internal/STATUS-CHANGELOG.md) 第二轮那条。**本条 2026-08-18 从顶部摘要区搬来 —— 它是 open 的 owner 项,此前混在「已归档各轮」里容易被读成历史。**\n> 0b. **loading 矩阵免横滚 —— ✅ owner 2026-08-13 已裁定走 ②(把每格 variant 文字 / nodeId 收起),⏳ 待落地**(docs 站视觉改动,走快车道)。裁定理由:② 消除根因(那些文字才是要求 180px 的原因),① 会**失去矩阵对齐** = 牺牲这个页面存在的意义(横向对比 variant);nodeId 属查证时才用的次要信息,收进 hover / 点击展开即可。⚠️ 落地后仍需 owner 看一眼实际效果。原始两条路:① 把 ≤980 的卡片流降级上提到 ≤1100 / ≤1280(**已否决**)② 见上。背景:2026-08-12 已 ship 的是「够得着」(横滚 + ③ 删掉 ≤1280 反向加宽的列宽覆盖,所需 1260→1040、1280 档横滚量 682→462px)。⛔ 两条**已排除**:拖拽列宽不创造宽度(1280 档 6 列每列只 106px)· 让宽 demo 横跨右侧 CONTENTS 栏不可行(CONTENTS 是 shell 三栏 grid 里的 sticky item,横跨只能负 margin 画到它底下 = F67 (b) 专抓的「被盖住」)。\n> 1. **DG-1 layout 原语 —— token 层 2026-07-31 已 ship,剩下两件事要 owner/designer 的视觉裁定**(owner 当日裁定「根据实际信息来显示即可 + 要有唯一值」→ 不等新表,值取实测现值做成单一定义;八个值逐字取自改动前在用的值、纯命名化零渲染变化,`audit:layout-tokens` L4+L5 上闸):① ~~3 个存量一次性断点~~ → **✅ 2026-08-12 全部拍完,本子项关闭**:`docs.css` 720 **消除**(owner 拍「拆开归并」并当日 ship)· `progress-demo.css` 900 与 `button-demo.css` 980 **维持豁免不归并**(owner 08-11 / 08-12 分别拍定;判据 = 二者都是 React demo 内部栅格,改它对 DS 消费者零影响,而归并是净损失)。**三条的重开条件已各自写进 [`audit-layout-tokens.mjs`](../scripts/audit-layout-tokens.mjs) 的豁免表**,别在这里找。⚠️ 留一条教训:720 的裁定材料一度**过期**(08-11 那个数字当天就被抽屉导航作废,照它裁 = 按不存在的效果裁)——**「等 owner」条目的实测数字有保质期,隔了一次 ship 要重测再送审**。② ~~容器宽未收口~~ → **✅ owner 2026-08-11 拍定:维持 report-only,不收口**(那批 `max/min-width ≥600px` 是 demo/页面**内容宽**,硬塞进容器档位就是把偶然值当契约。⚠️ **处数别写死,读闸每次运行的自印** —— 这里 2026-08-12 我先把「19 处」改成「22」,**那是错的、当天已订正回来**:22 是闸自己数错的,`extractWidthLiterals`(S5)**不剥 CSS 注释**,把 08-11 抽屉导航那批注释里提到的 3 次 `max-width: 1100px` 当成了真声明。同文件的 `extractMediaWidths`(S3)08-11 修过这个病、S5 那边漏了。已补上同样的注释中和 + 3 条单测(含阴性对照:注释旁的真声明照收),修后实测 **19**,与 07-31 一致 —— **处数从来没漂过,漂的是闸的读数**)。闸的 S5 继续自印剩余处数,**别读成待办**。⚠️ 别读成「布局已收口」;终点仍是 A(Figma 变量),迁移只换真源方向、不改 token 名。详见 [spec §6c](./superpowers/specs/2026-07-30-dg1-layout-primitives-design.md)(§6b「等一张表」那行已就地标注被推翻)。\n> 3. **Gitea registry TLS 化的 owner 残余**(原 INFRA-F74,**2026-08-14 该 entry 已删档 —— 仓库侧全部做完,剩下的只有下面这两件 owner 动作,本行现在是它们的家;⛔ 别再去 backlog 找 F74**)—— ① 人眼看一次新入口 `https://product-demo.tvustream.com/gitea/ux-team/-/packages`(硬纪律,API 绿不免除)· ② 建议轮换主机 `.env`(600) 里那份 `git ls-remote` 仍有效的 `GIT_AUTH`(签发需 owner UI,AI 无此权限)。⛔ **别把 `:3001` 写回 consumer 面 registry 配置** —— 它不是并列的备用入口,是 443 链路上的**中间一跳**,入口拓扑与那次修复的完整真源 = [`GITEA_ENTRYPOINTS.md`](./GITEA_ENTRYPOINTS.md)(⛔ 原先这里指的 `[[INFRA-F89]]` 已删档)。③ 主机上三个 `*.pre-f74*` 回退备份 **暂缓删除**(拿到 SSH 才用得上的唯一回滚源,保留成本为零)—— 三条精确路径已搬进 [`infra/README.md`](../infra/README.md) §主机侧回滚源。\n> 4. **候选回流规则维持候选**(owner 07-29 答「先等等」)—— V4-1827 那批(PRD 措辞锚定产品现状基线 / 交付集与 mockup 同交付区 / 反馈态用文案+状态色、动效交 dev / 删缩元素前先列「谁靠它定位」)+ V4-2333 轮二三条(走查 scope / 偏差要写后果 / wrap-up 步骤有条件)。\n> 5. **[[INFRA-F58]] 残余② 规则三层化 —— 处置待拍(建议整条搁置并重定义)**:2026-08-03 算完三个测量,**器械与目的不匹配** —— 宣称用途是 assessment 支柱① 的「让 claude.ai / Codex 能当 Project Instructions 直接吃」,但那五份文件(`AGENTS.md` + `meta-rules` + `design-process` + `code-conventions` + `mockup-conventions`)**一天涨 54 行、十一天涨 401 行**(08-03 = 7327 → 08-13 = 7674 → **08-14 实测 7728**),而最好可省 150-300 行 —— **可省量追不上分母的增长,比例还在往下走**。⛔ **别读这里的数,自己跑** `wc -l AGENTS.md docs/meta-rules.md docs/internal/{design-process,code-conventions,mockup-conventions}.md`(此处三轮都在漂,本行因此改为只留结论 + 取数命令)。另:原写的 `ds-bundle/reference/` 那组「近逐字搬运」数字(2885→2867 / 1488→1470)**在本仓不可复验** —— `ds-bundle/` 在 `.gitignore` 里、不入库,属外部事实。四块逐块判定 + 六处数字订正 + 两条执行前置见 [backlog F58 entry](./internal/backlog.md)(`e8120010`)。**建议改标「已 scoping、器械与目的不匹配、按需触发」而非留在待做**。⚠️ 若 owner 要真闭合那条 P1 缺口,需要的是**派生式精简产物**(从散文生成紧凑契约、生成而非手维护)—— 那是独立提案、有自己的设计问题(谁是真源 / 怎么防漂),**未立项**。另:任一动它的方案开工前须 owner 显式划清与 2026-06-12 被 reframe 掉的 [`rule-registry`](./internal/rule-registry-design-2026-06-12.md) wholesale reorg 的边界。\n> 6. **DS 系统性评估的两件待办**(评估本身七轴已跑完、finding 已全部立成 [[INFRA-F114]]–[[INFRA-F128]],叙述见上方摘要与 [评估报告](./internal/_reports/2026-08-13-ds-assessment-axes-abcd.md)):① **6 份计划仍待起工** —— [闸扩面](./superpowers/plans/2026-08-12-rule-inventory-mirror-gate-extension.md) · [归档](./superpowers/plans/2026-08-12-live-tree-derivative-archive.md) · [场景路由](./superpowers/plans/2026-08-12-scenario-routing-single-source.md) · [PathA增量](./superpowers/plans/2026-08-12-path-a-legacy-host-increment-rule.md) · [判定表](./superpowers/plans/2026-08-12-element-decision-trace-product.md) · [UX场景](./superpowers/plans/2026-08-12-ux-scenario-coverage-expansion.md) ② ~~`AGENTS.md` 快车道「闸的判据」四字等 owner 确认原意~~ → **✅ 2026-08-13 已裁定并落地**(`46234b9f`):原意 = **`tests/`**,⛔ 不含 `scripts/` 下的闸脚本 ⇒ **改 `scripts/` 的闸脚本不走快车道**。⚠️ **2026-08-13 晚订正本行后半句**(登记为 [[INFRA-F124]] ④):此前这里与 AGENTS 那段 ⚠️ 注都写「⇒ 照常写 changeset」,而那是**依据 F117 落地前的 §「何时写」**推出来的 —— 同日 F117 已把判据收窄成 `files[]` 白名单。⇒ 正确表述 = **changeset 仍按 §「何时写」的 `files[]` 判据判,不在白名单里的内部 `audit-*.mjs` 属「不写」**。owner 的裁定实质未变,变的只是这半句转述。~~⚠️ 一个联动项:`§228` 把 `scripts/` 整个列为 consumer-facing 必写,F117 落地后要同步改~~ → **✅ 2026-08-13 已随 F117 一并落地(`5844130b`)**:`§228` 改为「`files[]` 白名单内那 20 个 `scripts/`」,并显式声明 **`files[]` 是唯一真源**、不在 AGENTS 里维护第二份会漂的清单。\n>\n> 7. **[[INFRA-F115]] 撤销旧 Figma PAT —— owner 2026-08-13 已同意,⏳ 待 owner 在 Figma UI 执行一步**(Settings → Personal access tokens 撤销那个旧 token)。**AI 侧结构上不可为**(⛔ 禁调 Figma API / 禁重签,见 §三 10),所以「它现在是否仍有效」只能由 owner 在该页确认。**影响面已核(2026-08-13,只看元数据未读任何凭据值)**:本仓所有读 Figma 凭据的脚本都走全仓唯一 parser `scripts/lib/figma-env.mjs` 读 `.env`(当前 PAT)· 旧 PAT 在本机的唯一驻留点就是 `.env.bak.1785390298`(`.env.local` 只有 `GITEA_HOST`、`~/.config/tvu/gitea-token` 是 Gitea 的)· **Gitea 与 GitHub workflow 里零处引用 Figma secret** ⇒ **本仓 / 本机 / CI 三面零影响,新 PAT 完全取代**。⚠️ **唯一核不到的**:`scripts/consumer-postinstall.mjs` 教 consumer 仓库设 GH secret `FIGMA_TOKEN`,MicroApps / NOC 那边那份值是新是旧**看不见**(别的仓库的 secrets)—— 撤销后若某 consumer 的 mockup conformance 报 403,就是它,重配即可。**⚠️ 2026-08-14 影响面重核(零 Figma API 调用、零凭据内容读取,只读元数据)**:那份明文副本当时**仍在**,`find` 全树(含 6 个 worktree)**精确 1 个命中** ⇒「本机唯一驻留点」有判据不只是断言 —— **该副本已于同日删除**(零引用已核、⛔ 未读其内容),但**删本地副本 ≠ 远端失效**,撤销仍只能 owner 在 Figma UI 做;读 Figma 凭据的文件现取 **12 个**(原 11,新增 `scripts/ds-health-scan-mockups.mjs`)、**12/12 全部走唯一 parser**;两 host 5 个 workflow 扫 `FIGMA` **零命中**(配阳性对照 `secrets\\.` 命中 3 行 ⇒ 非空过)。⇒ **三面零影响的结论未变。** 顺带查出一处不属本条的真缺陷(`consumer-postinstall.mjs` 教人配一个所给模板永远不读的 GH secret),已挂 [[INFRA-F115]] entry。\n>\n\n> ### 二 · 等 designer(Figma 侧动手)\n> ⭐ **2026-08-14 新增可交付**:⭐「拿错设计库」的清理清单已机械生成 —— [`_generated/foreign-library-cleanup.md`](./internal/_generated/foreign-library-cleanup.md),逐个换成当前 DS 库组件。**污染源只有两个 file**(`TVU UX Library` 六文件全中 · `Nancy's Design Assets` 三文件),⛔ 别引用清单里的数(契约 G4:重跑 `pnpm health:mockups` 现算)。它由 `ds-health-scan-mockups.mjs` 全量成功时重写,⛔ **别手改**。\n> 9. **design-review-queue 4 条** —— #4 Notification pop confirm 问句标点不一致(owner 定如实提取、由 designer 在 Figma 统一)+ 3 条 designer-action(off-scale px / multi-select padding outlier / 缺 disabled 变体),全 live 2026-06-11 验证过。详见 [design-review-queue.md](./internal/design-review-queue.md)。**⚠️ 2026-08-03:#3「缺 disabled 变体」多了第 4 个成员 `Tab/Item`**(**条数不变** —— 既有条目长出一个成员,不是新条目)。它把这条从「三个零散控件」变成**需要一次统一裁定**:同族 `select box/filled` / `input box/filled` / `switch` / `radio` **都有** `enable` 轴,缺的这四个不是族惯例、是漏。~~裁定要连数值一起给(0.4 / 0.45 / 第三条路 三选一 + 一个数)~~ → **✅ owner 2026-08-13 已裁定:走 `token desaturation`,且「定一个数」这一问作废**(`--control-disabled-*` / `--text-disabled` / `--icon-disabled` 是 **per-theme 具体色值不是透明度** ⇒ 四分叉 0.4 / 0.45 / ≈0.5 / 0.6 全部作废;依据 = `FIGMA_AS_SOURCE_OF_TRUTH.md:71` 逐字禁止把 opacity-vs-token 当实现策略差 + 实测 token 路线已是多数派 **12 : 8**)。**designer 侧仍待动手** = 在 Figma 给这 4 个成员补 disabled 变体、按 token desaturation 表达 —— ⚠️ **2026-08-14 owner 裁定后它不再是 code 的前置**(Figma 无变体时 code 直接绑既有语义 disabled token 即可,不算发明数值;规则真源 `code-conventions.md` §R9 disabled 行,参照实现 `TabItem.vue`),补变体的目的是补齐设计真源。**code 侧待办** = [[INFRA-F120]](⚠️ 原并列的 `CANONICAL-F92` 已于 2026-08-14 删档 —— `Tab/Item` 的 code 侧四项实测早在立项前就已 shipped,结论搬进 `design-review-queue.md` §3 那条 🔑,那里另记了一条**待 owner 拍的一致性问题**:Tab 在 Figma 无变体的前提下已绑 token,与 F120 对 `Rating`/`Slider`/`Select` 的「无变体 ⇒ 等 designer」口径互斥)(⚠️ **2026-08-13 订正**:原写「改四个 + `Switch`/`InputNumber` 只需删多余 opacity 行」**已被实测推翻** —— 实为「三改 + 两个转为改 + 一个不动」,且三个改项在 Figma 无 disabled 变体、值仍等本条 designer 产出;观感会变,**必须过 owner 视觉签核**。逐条与证据在 [[INFRA-F120]] entry,另见 §一 7 那条待拍的例外)。\n>\n> ### 三 · 技术项未闭合(详情在 [backlog](./internal/backlog.md) §Active,此处只留最容易被漏的几条;条数别写死 —— 以 `pnpm run audit:status-consistency` 为准)\n> 10. **变量层 ack 2026-10-28 到期即红**(原 INFRA-F79,**2026-08-13 已删档**:⛔ 禁止复现清单已搬进 `audit:variables-freshness` 的 PASS 自印输出 + `variables-staleness-ack.json` 的 `reviewQuestions` 两处真源,别再回写 backlog)。缺口按 **Figma plan = Professional** 的事实已闭合;出路只有 plan 升级(采购)或 Figma plugin 侧导出(未调研);MCP `get_variable_defs` **只能点验、不能替代 sync**。\n> 11. **[[INFRA-F66]] 残余** —— `tvu-drop-down-list-select` 的 `:host` 尺寸未判定(docs React demo 零渲染实例,且它是 light-DOM CE、`:host` 语义不同不能照搬)。🔴 **2026-08-14 订正触发条件**:原写「触发 = 给它补 React demo 时一并判」并以为硬规则 #8 的闸会推动它 —— **实测那个闸的 in-scope 根本不含它**(无 slot、零 boolean prop),闸绿是空过;React 侧不渲染还是 `Select.tsx` 里一条显式裁定(`F45 OUT`)。⇒ **真触发 = owner 主动把它提为一级 demo 组件**,别等闸。(原 INFRA-F67 已于 2026-08-14 闭合删档 —— 三件残余全部实测已闭;(c-3) 那段「够格独立成 entry」的内容也已全部完成,给已完成的工作立新 entry 违反「完成即删档」。)\n> 12. **尚无人接:只剩 [[INFRA-F75]],且它的体量 2026-08-14 被推翻** —— 它**不是**「NOC 迁 registry」:实测那份 `upstream-gate` 副本**从来没有** registry/token 配置,与本仓 `templates/upstream-gate-workflow.yml` 逐行比**只差 2 行包名**,且它当前连 `package.json` 都没有、在任何 runner 上都跑不起来。⚠️ 原记的「被 GitHub Actions 额度软阻塞」引的是**7 月**的月度额度,跨月后多半已失效(未实测,待 NOC 侧确认)。致病机制(DS 改 template 包名 → consumer 已复制出去的副本不会跟着改,且无人发现)已搬进 [`MIGRATION_TO_V1.md`](./MIGRATION_TO_V1.md) §3 并把扫描面从 `src` 扩到 `.github/workflows`。(~~INFRA-F90 docs 站 URL 无 section anchor~~ —— **✅ 2026-08-03 已 ship 并从 backlog 删档**,形态 = 路由后多一个尾段 `#/component//`,沿用 `#/changelog/` 的既有先例;**hash 路由只有一个 `#`,不存在第二个 fragment**,所以不可能做成 `#…#anchor`。⚠️ **两条如实登记的边界**:① slug 由标题文本派生 → **跨 locale 不解析**(中文站复制的链接在英文站只停在页面顶部 = 修复前行为,良性降级)② `/changelog` 与 `/`(overview)**不支持**段锚点 —— 前者尾段已被版本号占用。段落 slug 的**唯一定义** = `playground/docs/navigation.ts` 的 `slugifySectionTitle`,与 F88 视觉闸内联那份必须逐字一致,由 `tests/docs-section-anchor.test.ts` 的漂移闸钉住。**已发到真站并端到端验过**,签核可直接贴形如 `…/playground-dist/#/component/button/button-api` 的链接。)\n>\n> **第四条线(design-sync:Sync A 补齐 + runtime 刷新 + TopBar/MenuList 对齐 Figma,08-13 起 / 08-14 全部收口)**:叙述见 [CHANGELOG](./internal/STATUS-CHANGELOG.md) 顶条,判据 / 取证 / 通道归属 / 验证边界的真源在 [`.design-sync/NOTES.md`](../.design-sync/NOTES.md)。**本线在 STATUS 已无待办**。\n>\n> **本文档是项目状态 SoT**,也是 onboarding 链路的唯一 SoT。在 L-core 里它是 **#1**——**第 0 份是 [`FIGMA_AS_SOURCE_OF_TRUTH.md`](./FIGMA_AS_SOURCE_OF_TRUTH.md)**(见下方 §起手必读链路 的 L-core 表,那张表是次序真源)。本文件早于 PROJECT_GOAL.md 读,因为它直接告诉你\"在哪\"。\n\n> 任何 session wrap up 时**必须更新本文档**(见末尾\"Wrap-up 协议\")。\n>\n> ⚠️ **排期 SoT 在 [`retrospection/design-spec-canonical-alignment-tracker.md`](./internal/retrospection/design-spec-canonical-alignment-tracker.md)**——本文件 Version Roadmap 段只是镜像。任何 \"v0.X 包含哪些 / 先做哪个\" 决策前先读 tracker 的 \"排期原则\" 自检清单。\n\n---\n\n## 一句话目标\n\n把 Figma 已发布 Library 做成 **AI 与开发可消费的双向 Figma↔Code 桥**(详见 [`PROJECT_GOAL.md`](./PROJECT_GOAL.md))。\n\n---\n\n## Claude Code Plugin\n\nUX 团队 AI workflow skill 的独立分发轨道(与 npm 包版本独立)。详见 [`docs/PLUGIN.md`](./PLUGIN.md)。\n\n---\n\n## 当前版本:v1.2.0(✅ **published & verified 2026-07-31** —— 四步核验俱全(tag→CI 历史首跑 + registry API 两路 + 真取回 tarball 逐字核 sha1 + owner 人眼核 Packages 页)。**完整取证实录 2026-08-13 已逐字下沉** [STATUS-CHANGELOG](./internal/STATUS-CHANGELOG.md) §「v1.2.0 发布核验实录」——⛔ 别在本行找 run 号 / sha1 / 解包抽验清单。**核验协议真源 = [`RELEASING.md`](./RELEASING.md)**(registry API 两路 + 真取回 tarball + Packages 页人眼亲验;硬纪律,API 绿不免除 —— v0.1.0/v0.1.1 曾 silent fail 1-2 周)。)\n\n| 项 | 值 |\n|---|---|\n| v1.2.0 内容 | **4 minor + 3 patch**(全 additive,无组件 API 移除/改名):`./web-components` 出口(React / 原生 CE 第一次有 npm 消费路径;⚠️ tarball 2.84 → 4.74 MB,+67%)· Select 触发器补 combobox ARIA · `peerDependencies` 改 `vue: ^3.5.0`([[INFRA-F85]])· 浮层层级 token 化(`--z-dropdown` / `--z-tooltip` / `--z-modal` / `--z-select-portal`)·(patch)I18N-01 可见文案 key 真被组件消费 + 防回归闸 · registry 改走 HTTPS 标准端口(原 INFRA-F74,已删档)· UserMenu 面板对齐 Figma `DtZcMkhNy6qh6jbQQnhreQ` node `6423:85`。逐条详情见 [`CHANGELOG.md`](../CHANGELOG.md) |\n| 本次 publish | ⏳ **走 tag→CI**(`.gitea/workflows/publish.yml`,tag `v1.2.0`)。**这条链此前从未执行过一次**(Gitea 1.22.6 没有 `workflow_dispatch`,因此本 host 无干跑能力;恢复干跑的前置 = 升 Gitea ≥1.23)。三个必须逐段读的观察点:① pre-flight 凭据闸(A 读 / B **真写一次 probe** / C 删除并重读列表核实)② changesets-consumed guard ③ `pnpm publish` 本体。401/403 的读码方式写在 workflow 注释与 `RELEASING.md` §Troubleshooting |\n| 包名 | `@ux-team/tvu-design-system`(团队 Gitea registry)。GitHub Packages 上旧包名 `@nancyzeng0210/tvu-design-system` 的 15 个版本(≤1.1.0)**刻意保留不删**(rollback 退路;⚠️ **2026-08-14 订正**:括号里原写的第二条理由「MicroApps/vue-app 仍钉 `^0.6.1`」**已为假** —— 该仓 `111c408`(2026-08-07)已迁到 `^1.2.0`,两个 consumer 都在新 registry 上了。**「别清旧包」这条禁止动作本身仍成立**,靠的是 rollback 退路那条),此后不再有新版本发到那里 |\n| 上一版本 | v1.1.1 —— ✅ published & verified 2026-07-30T02:39:15Z(Gitea registry,**本机 `scripts/publish-to-gitea.sh` 发**,因为 tag→CI 的 secret 当天才修好;三路核验 + owner 人眼确认俱全,叙述归档在 [STATUS-CHANGELOG](./internal/STATUS-CHANGELOG.md))|\n| 安装 | `pnpm add @ux-team/tvu-design-system` + Gitea `.npmrc`(**HTTPS 标准端口**:`https://product-demo.tvustream.com/gitea/api/packages/ux-team/npm/`)+ **Gitea** token(`read:package`;GitHub PAT 不行,Gitea 在 `authGroup.Verify` 就拒)。步骤见 [`RELEASING.md`](./RELEASING.md) §External consumer setup |\n| Release 流程 | changesets + **tag-triggered 自托管 Gitea CI** + strict audit 链(**条数别写死 —— `prepublishOnly` 是链的 SoT,要数就读它**;此处曾写「32 条」而 2026-08-05 实测 37 步 = 35 条 `audit:*` + `lint-skills` + `lint:ds`)+ Node 20/22 matrix(vitest 仅 Node 22 —— 3 个 audit 脚本靠 Node≥22 原生 TS 类型剥离)+ changesets-consumed guard + **render-gate 前移到切 tag 时在本机强制**(不在 CI:Gitea runner 非特权装不了 chromium 系统库)。GitHub 侧 `gates.yml` = dispatch-only、无发布能力,⚠️ 别给它恢复 tag trigger |\n| 破坏性 (1.2.0) | **无 API 破坏** —— 组件 API / 样式 / token 均无变化。但有一条 consumer 侧硬门槛:**peer 下界升到 `vue ^3.5.0`**,钉 `3.4.x` 的 consumer 装不上。那条「支持 3.4」事实上早已不存在(shipped 代码在用 Vue 3.5 才有的 `useId()`,3.4 上渲染 Tooltip/Select 当场报 `useId is not a function`)——本版删掉的是一句假声明,不是砍掉能用的支持 |\n| 版本详情 | [`CHANGELOG.md`](../CHANGELOG.md) |\n| 注 | ⚠️ 生态:`vue@3.5.36`(曾是 npm latest)官方发布产物损坏(`workspace:*` 未替换),consumer fresh install 需钉 `3.5.35` 或本仓库在用的 `3.5.32`;与本包发布无关 |\n\n---\n\n## 能力 × 成熟度(单一真源表 · INFRA-F58)\n\n> 5 能力定义真源 = [`PROJECT_GOAL.md`](./PROJECT_GOAL.md) §一句话目标;本表只登记**当前成熟度 + 该能力状态的单一真源**,避免\"读了 PROJECT_GOAL 承诺信以为真\"(assessment §5 承诺-vs-实现)。成熟度变化改本表。\n\n| # | 能力 | 成熟度 | 状态单一真源 |\n|---|---|---|---|\n| 1 | 开发 npm install 即用(Vue 组件 / token / 图标 / 样式) | 🟡 **partial** — Vue 全通;**token = CSS 变量 + DTCG JSON + TS 出口**(`./tokens` DTCG · `./tokens/js` resolved TS,INFRA-F55 支柱①);**React 无 published npm 路径**(经 CE + `react-pilot` 内部 bindings,非 `./react` 导出) | `package.json` exports + PROJECT_GOAL §Token 架构 + assessment §5 |\n| 2 | AI 拿 Figma URL → 定位代码 1:1 还原 | ✅ **done** — manifest 确定性验证 | `figma-data/render-verification-manifest.json`(936)+ FIGMA_AS_SOURCE_OF_TRUTH.md |\n| 3 | AI 拿 代码 → 生成 / 还原 Figma | ⚠️ **DEFERRED(bypass equivalent)** — DS 代码 _可_ 经 manifest + 唯一库 `YbsPRUVmNdsbN40NNwh1Gn` 还原;缺的仅\"全自动 Code Connect publish\"(Pro plan 401)+ 非 DS 反查 + MCP config | PROJECT_GOAL 能力3 + `CAPABILITY_3_BYPASS.md` |\n| 4 | AI 拿 文字/链接/截图/代码 → UX 效果图 + 可运行代码 | 🟡 **gate + AI 辅助合成**(非全自动生成器);mockup 确定性后验强制化 = F55 缺口 A | PROJECT_GOAL 能力4 + assessment §4 支柱② 设计网 |\n| 5 | 每个 Code 组件可追溯 Figma 来源 | ✅ **done** — canonical `data-figma-*` + manifest N:1 | canonical 组件 `data-figma-*` 属性 + manifest |\n\n---\n\n## Version Roadmap(剩余按版本线分组)\n\n> 本段只留 **open / blocked** 项——已 shipped 版本(v0.2.0–v0.7.0)逐版本 retrospect + 历史完成项在 [`design-spec-canonical-alignment-tracker.md`](./internal/retrospection/design-spec-canonical-alignment-tracker.md) §轨道 A 已完成 / §Release 排期(完成叙述不在 STATUS 累积 — status-keep-only-unfinished)。\n\n### ✅ v1.0.0(稳定承诺 — API 锁定 · **已发布 2026-07-20**)\n\n> **published & verified**:GitHub Packages `1.0.0` created 2026-07-20T10:33:19Z · CI run [29735085984](https://github.com/NancyZeng0210/TVU-Design-System/actions/runs/29735085984)。首个稳定版,公开 API 锁定([`API_STABILITY.md`](./API_STABILITY.md));scope = 组件保真镜像层(36 组件 + token + 图标 + 双向 Figma↔code 桥),产品构建层(Table/Form/layout/pattern)列 v1.x/v2。\n> **触发条件回顾**(全满足):5 能力交付(能力 3 旁路 ack)· L5 口径 A(tooling ships + MicroApps adopts)· color-contrast owner-accept 收口 · burn-in waived · RC soak(MicroApps Console ≥1 周 0 critical,owner 2026-07-20 sign-off go)。\n\n### 🔵 v1.3.0(**规划中** — 排期层 2026-08-13 重建)\n\n> **排期 SoT 在 [tracker `### v1.3.0`](./internal/retrospection/design-spec-canonical-alignment-tracker.md),本段只是指针,别在这里找批次内容。**\n> 缘起:原排期图终点是 v1.0.0,2026-07-20 **达成**后没有人画第二张图 ⇒ 排期层空了 4 周,\n> 期间 backlog 涨到 57 条且**无一条有版本归属**(表现 = 一堆 High/Medium 谁也说不上先做哪个)。\n> owner 2026-08-13 拍「先补规划层,别急着往下做条目」。\n> **分拣的主要产出是认定大多数 entry 不该排队**(17 条是「下次碰 X 时」的触发式)。\n> ⚠️ **「57」这个数尚未经核对** —— 当日抽样两次命中 stale([[INFRA-F119]] 可关一半 · 原 INFRA-F122 存量 2→6(该 entry 2026-08-14 已落地删档)),别把它当工作量。\n\n| 后续 | 版本线 |\n|---|---|\n| ~~批次 A — consumer 面发布正确性~~ → **✅ 2026-08-13 全部 ship(`5844130b`)**:F114 / F117 已删档、F105 只剩 ①③④;顺带闭合 F102。终态判据与留下的已知缺口(`./web-components` 仍无 types)全在 [tracker `### v1.3.0`](./internal/retrospection/design-spec-canonical-alignment-tracker.md),⛔ 别在这里找 | v1.3.0 |\n| 批次 B 凭据卫生 · 批次 C 让已有的闸真的守住 · 批次 D 大件(Tier 1-C ESLint plugin / F62 / F60,**起不起由 owner 拍**)| v1.3.0 / 待拍 |\n| 产品构建层剩余(layout 原语 / pattern 层)—— APID-02 Form 校验引擎 + APID-01 Table 状态层均已随 **v1.1.0** 发布 | v1.x / v2(backlog INFRA-F68 Batch D/E/G)|\n\n### ⚪ Deferred / Out of scope\n\n| 项 | 状态 | 理由 |\n|---|---|---|\n| **能力 3 (AI code→Figma)** | DEFERRED bypass shipped | Figma Pro plan 限制;[`CAPABILITY_3_BYPASS.md`](./CAPABILITY_3_BYPASS.md) 提供等价方案 |\n| **T1c Extract Pipeline** | PAUSED | plan owner \"元层疑问\"未解 |\n| **Phase 8** 视觉脚本 + Code Connect | DEFERRED | 需 Figma Org plan 升级 |\n\n---\n\n## Active 后续工作\n\n```\nBacklog (active) (32): INFRA- F58·F60·F61·F62·F63·F66·F68·F69·F75·F81·F86·F91·F101·F105·F106·F107·F115·F120·F123·F129·F131·F133·F134·F137·F138·F139 · CANONICAL- F92–F94(打包入口·现只含 F93+F94)·F93·F94·F95·F104 · META-DSYNC-01 —— 计数镜像;状态/待办/⛔ 全在 backlog.md ## Active 各自 entry(C4 机械核)。⛔ 这串别手抄,从活源生成:`grep '^### ' docs/internal/backlog.md`\ndesign-review-queue (4): 设计侧待 designer 动手(off-scale px / multi-select padding outlier / 缺 disabled 变体 / Notification pop confirm 标点)—— 计数镜像,与 §二 9 同口径。⛔ 各条 live 复核日期**别在此抄**(三条不同日),见 design-review-queue.md 各条自带实测行。✅ 2026-08-21 起有闸:`audit:status-consistency` C6(判据 = 真源 `designer-action: yes` 条数,核三处镜像)\nCode-leads divergences (3): msg-bg-tinted-dark / chart-color-palette / pill-component-family — 见 translation/divergences-decisions.json\nDeferred (3): 能力3 bypass · T1c · Phase 8\n```\n\n**真正 next 可推进的**(2026-08-05 复核,**此前三处指路句已 stale 并就地删除**:f73 plan 的「轨道 A 发 1.1.0,卡 owner 建 Gitea PAT」—— 1.1.1/1.2.0 都已发完;`1.1.2` 那条载荷路线 07-31 已作废;`2026-07-30-v1x-next-batch` 的 **10 个 Task 已全部执行完**,Task 10 = 发 v1.2.0):[[INFRA-F104]](render-gate 降级判据字段化)**已于 2026-08-07 ship 并从本段删档**(数字/闸细节见上方 Last updated 摘要)——⚠️ **本段已被排期层取代 —— 「下一个做什么」的答案现在在 [tracker `### v1.3.0`](./internal/retrospection/design-spec-canonical-alignment-tracker.md),别在本段挑**(本段历来是\"零散指路句\",而 2026-08-13 的分拣证明零散指路正是排期层空缺的症状:57 条 entry 无一条有版本归属)。~~**建议最先** = v1.3.0 批次 A 三条 consumer 面发布正确性~~ → **✅ 2026-08-13 已 ship(`5844130b`)并删档**(F114 / F117 / 顺带 F102;F105 只剩 ①③④)。**不等 owner、不等 designer 的**(~~F98~~ 2026-08-06 已 ship 删档 · ~~F119~~ **2026-08-13 已完全闭合并删档**:步骤①亲验发现 2026-07-31 就已存在于 `release.mjs` step 1c、步骤② 76 张基线已 ship `3cb3e36b`)= ~~[[INFRA-F100]]~~ → **✅ 2026-08-17 整条落地并删档**(三条结构缺口 + 最后那条「37 行豁免按 CE 语义逐行复核」)。**封路理由与诚实边界已全部搬进 `scripts/audit-render-drift-gate-react.mjs` 头注释**(闸每次运行自印),⛔ 别再来 backlog 找这个号 · **Tier 1-C** `@ux-team/eslint-plugin-tvu-design-system`(能力 1 加固,tracker 估 ~2-3 周,自 v0.6.0 挂到现在 —— 「大所以推后」逐字命中 tracker §排期原则反模式表,要继续推后需要一个**不是\"大\"的**新理由,起不起由 owner 拍)。另有 RTL-01 / F68 FID-04 M1 role-map 全量铺开,各自成批。design-review-queue 4 条待设计师(⚠️ 此处 2026-08-21 前一直写 **3**,是本文件里第三处 stale 的同一个量 —— F136 立项时只发现两处;现由 `audit:status-consistency` C6c 吃**所有**出现处)。\n\n**排期决策必读**:[`retrospection/design-spec-canonical-alignment-tracker.md`](./internal/retrospection/design-spec-canonical-alignment-tracker.md) §排期原则 — **不按耗时 / 复杂度 / 成本最低排,按项目目标对齐 + 依赖解锁 + 自动化标准化排**。\n\n---\n\n## 起手必读链路\n\n> **本节是 onboarding 链路的唯一 SoT**(AGENTS.md §必读链路 只登记任务触发表,不再维护并行清单 — 2026-06-10 system-review P1-07/P1-08 重构为两层,消除双链路 drift + 与仓库 lazy-load 原则对齐)。\n>\n> **⛔ Mandatory Gate**:任何 AI session 在第一个项目相关回答 / 推荐 / 任务前,**必须全文读完 L-core 四份**,并读完命中触发条件的 L-ref 最小集。机械执行:用 TodoWrite / TaskList 为 L-core 每项 + 命中的 L-ref 项各建 1 个 todo,逐个 Read 完才能回答。基于 partial L-core 给推荐 = **协议违反**。**唯一的减档 = 下方 [§微改档](#微改档单文件纯文案的减档)**(owner 2026-08-13 裁定新增),判据不满足即回落本档、无第二个例外。\n>\n> **体量口径 —— 本行是唯一真源**(`AGENTS.md` §Onboarding Gate 只指回这里,刻意不复述数字):**2026-08-04 `wc -c` 实测 65.2 KB** = 三份固定文件 59.8 KB(FIGMA_AS_SOURCE_OF_TRUTH 8.1 + 本文件 37.0 + PROJECT_GOAL 14.7)+ 当前 pickup(本轮那份 5.4)。⚠️ **引用前先自己重跑** `wc -c` 那四份 —— 它们每工作日都在涨,本行也会漂。此前这里与 AGENTS 两处都写着「~40KB ≈ 10-15min」,而 2026-08-03 实测已是 **90.5 KB**、失真 **2.2×**(原 INFRA-F95 已付代价 4 —— **该 entry 三项待做全部闭合、2026-08-13 已删档**;本轮清理让本文件从 63.7 → 37.0 KB,L-core 因此回落到 65.2)。⚠️ **2026-08-13 实测 L-core 四份已回涨到 ~74 KB**(本文件 ~45 KB)—— 正是本行自己说的「本行也会漂」,**别引用这两个数,自己跑 `wc -c`**。**别再写死耗时** —— 那正是下方「历史实证」里 gate 被默读架空的机械成因。\n\n### 微改档(单文件 · 纯文案的减档)\n\n> **owner 2026-08-13 裁定新增。这是本链路唯一的减档,本节是它的唯一 SoT**(`AGENTS.md` §Onboarding Gate 只留一行指针,刻意不复述判据 —— 复述一份就是第二处会漂的副本,[[INFRA-F121]] 已付过这个代价)。\n> 缘起:此前唯一豁免是「用户首条 query 明显非项目相关」,于是「把这句 UI 文案从 A 改成 B」也要先吃 65 KB。gate 设严的原因是 2026-05-13 跳读致首轮推荐漏 4 项硬约束,所以减档不是取消 gate,而是**把省下的风险交给下方升级条件接住**。\n\n**适用判据(四条全中才算,任一不中 → 回落完整 L-core)**:\n\n1. 改动落在**单个文件**内;\n2. 性质是**纯文案 / 措辞**(UI 可见文本、注释、文档行文、错误提示字串);\n3. **不换组件、不改 token、不加删元素、不动布局**,也不涉及组件选型判断;\n4. 不是 mockup 写操作,也不是推荐 / 排期 / 裁定 / 发版类回答。\n\n**微改档要读的(省下 STATUS 本文件 + PROJECT_GOAL + 当前 pickup 三份)**:\n\n| # | 文件 | 为什么它不能省 |\n|---|---|---|\n| 0 | ⭐ [`FIGMA_AS_SOURCE_OF_TRUTH.md`](./FIGMA_AS_SOURCE_OF_TRUTH.md) 全文 | 文案也可能踩「code 反向要求改 Figma」;本文件是唯一能拦住它的 |\n| — | [`AGENTS.md`](../AGENTS.md) §硬规则表 | 硬规则里的写边界 / commit 纪律与改动大小无关 |\n\n**⛔ 自动升级条件(硬 —— 命中任一即当场停下补读完整 L-core 再继续,不许「就差一点,先改完」)**:\n\n- 发现要动的不只是文案:要**换组件**、要**改 / 新增 token 或写字面量**、要**加删元素或改布局**;\n- 要动**第二个文件**(含\"顺手把生成产物也重跑一下\");\n- 触到**组件选型**(该用 A 还是 B)、**Figma 真源判断**、**divergence 登记**;\n- 用户在同一 session 里追加了任何非微改任务,或要求推荐 / 排期 / 裁定;\n- 自己不确定判据 1-4 是否满足 —— **不确定就是不满足**。\n\n**⛔ 本档不放宽的**:mockup 写操作仍走 `AGENTS.md` §Mockup Write Gate 4 步前置 + §必读链路 7-11 整链(不受本档影响);任何写 Figma 的动作照旧要显式授权。\n\n### L-core — 每 session 全文必读(禁 grep / 跳读 / 摘要替代)\n\n| # | 文件 | 作用 |\n|---|---|---|\n| **0** | ⭐ [`FIGMA_AS_SOURCE_OF_TRUTH.md`](./FIGMA_AS_SOURCE_OF_TRUTH.md) | **最高优先级原则** — Figma 真源 + 唯一合法 divergence + 禁止启发式验证 |\n| 1 | **本文件 STATUS.md** | 知道在哪(状态镜像 + 本链路 SoT) |\n| 2 | [`PROJECT_GOAL.md`](./PROJECT_GOAL.md) | 知道目标(5 个能力 + 受众 + 约束) |\n| 3 | [`_plans/next-session-pickup-*.md`](./internal/_plans/) 最新一份
**⚡ 当前活跃优化程序(固定指针 · 不靠 mtime · 并行 session 再写新 pickup 也不漂移)**:[全生命周期优化](./internal/_plans/next-session-pickup-2026-07-08-full-lifecycle-optimization.md) → 存档 SoT [`full-lifecycle-assessment-2026-07-08`](./internal/full-lifecycle-assessment-2026-07-08.md)(tracked = backlog **INFRA-F55**) | 当前 sprint 操作手册 |\n\n### L-ref — 最小集必读 + 命中触发再深读(各文件顶部有「🤖 AI 读取指引」)\n\n| 文件 | 每 session 最小集 | 升级为全读 / 深读的触发 |\n|---|---|---|\n| [`AGENTS.md`](../AGENTS.md) | §硬规则表(含 Enforcement 层级列)+ §Onboarding Gate | 写 prompt / 审 executor → §工作流 + task-type 矩阵;commit 前 → §Git 工作流;**mockup 任务 → §Mockup Write Gate + §必读链路 7-11 整链升 mandatory** |\n| [`tracker`](./internal/retrospection/design-spec-canonical-alignment-tracker.md) | §排期原则 | 任何\"v0.X 包含哪些 / 先做哪个 / 该不该上 Tier N\"决策 → 全读 |\n| [`backlog.md`](./internal/backlog.md) | — | 当前 sprint task 对应 entry → **全文 Read(不是 grep)**;新增 entry → 先 grep 全部已用 ID |\n| [`meta-rules.md`](./meta-rules.md) | 触发器目录(标题扫一遍) | 写 prompt / 设计机制 / 推荐方案前 → 反模式清单全读 |\n| [`code-conventions.md`](./internal/code-conventions.md) | — | **写 UI 代码的任何任务**(Vue / React / HTML — 含 `playground/docs/*`、`src/components/*`、下游产品 demo 与 PoC)→ 顶部 **§🤖 AI 读取指引 的「起手必读段」**(§R0 Phase 0 元素→组件映射 + §R7 四场景判断 + Task Entry Modes 的唯一活源),单条 R-rule 按该表触发条件 jump。⛔ 禁全量吞(近 90 KB);⛔ 跳过起手必读段直接进 R-rule = 协议违反。**注**:机械路径 `detect-figma-task.sh` 只在 prompt 含 `figma.com/(design\\|file)/` URL 时触发,**没有 Figma URL 的 code 任务全靠本行**([[INFRA-F121]] ①) |\n| [`working-principles.md`](./working-principles.md) | 原则 0-8 标题 | 实现决策(命名 / token / API 形态)命中 → 对应原则全读 |\n| [`translation/`](../src/design-system/translation/) 4 文件 | — | Figma↔Code 命名 / divergence / alias 决策时查对应文件 |\n| mockup 链(AGENTS §7-11 + [`figma-component-catalog.md`](./internal/figma-component-catalog.md)) | — | **mockup 任务整链升 mandatory**(Mockup Write Gate 的 4 步前置不变,仍是硬规则) |\n\n> **违反信号(分层版,命中任一 → 停下重读)**:\n> - L-core 没读完就给项目相关回答 / 推荐 → 错(\"我已经知道大概了 / 状态简单跳一步\" 同罪)\n> - L-core 或 backlog 当前 task entry 用 grep / 摘要替代全文 Read → 错\n> - 命中 L-ref 触发条件却只读了标题 / 最小集 → 错(如排期决策没全读 tracker、mockup 任务没读 §7-11)\n> - \"memory 兜底替代 SoT\" → 错(memory 是 AI 缓存,项目契约真源在仓库)\n>\n> **历史实证**:2026-05-13 session 10 跳过 PROJECT_GOAL + AGENTS → 首轮推荐缺 4 项硬约束(canonical SoT / plan owner 边界 / working-principles / meta-rules)→ 用户返工纠偏。2026-06-10 system-review P1-08:旧版\"全量读 ~225KB(mockup +270KB)标 30min\"失真 → gate 被默读架空;两层化让严格性落在读得完的集合上。\n\n---\n\n## Wrap-up 协议\n\n> **session 收尾时读** [`docs/WRAP-UP.md`](./WRAP-UP.md)(每-session STATUS 必改项 + Release wrap-up + Retrospection 触发判断)。\n> 核心一条:顶部 \"Last updated\" 改到今天 + 当日摘要(旧摘要 prepend 进 STATUS-CHANGELOG.md);SessionEnd hook 自动核验日期。\n\n---\n\n## 文件关系(防混淆)\n\n| 文档 | 用途 | 更新节奏 |\n|---|---|---|\n| **STATUS.md**(本文件) | 全局状态镜像 + 版本线分组 + Active 余量 | **每 session** |\n| `PROJECT_GOAL.md` | 项目目标 + 5 个能力 + 受众 + 约束 | 大方向变才改(罕见) |\n| `_plans/next-session-pickup-*.md` | 当前 sprint 操作手册(prompts / 任务顺序 / dirty 协议) | **每 sprint** |\n| `CHANGELOG.md` | Release-facing(外部 consumer 看)| 每 release |\n| `backlog.md` | 全量 entry 详情(Active only,完成直接删) | 每发现 / 每完成 |\n| `retrospection/design-spec-canonical-alignment-tracker.md` | 设计规范完整计划 + 进度时间线(living doc)| **每 session wrap-up 前同步** |\n| `retrospection/*.md` | 阶段复盘(决策 / 反模式 / 教训) | 每阶段完成 |\n| `internal/STATUS-CHANGELOG.md` | 历史 session changelog 归档(从本文件拆出) | 每 session wrap-up |\n| `WRAP-UP.md` | session 收尾协议(STATUS 必改项 / Release / retrospect 触发) | 罕见 |\n| `PLUGIN.md` | Claude Code plugin 独立分发轨道 | 每 plugin release |\n\n**真源关系**:STATUS.md 是各 SoT 的**镜像/导航**,不是 SoT 本身。具体决策仍在 PROJECT_GOAL / pickup / backlog / CHANGELOG。\n\n### SoT 归属表(哪类事实以谁为准 · INFRA-F58)\n\n> AI 读多份文档遇到冲突时,**以本表指定的真源为准**,其余处一律视为镜像/指针(镜像 stale 时以真源修镜像,不反向)。\n\n| 事实类型 | 唯一真源 | 说明 |\n|---|---|---|\n| **npm 包当前版本号** | STATUS §当前版本(字面版本号只此一处)| README/PLUGIN/GETTING_STARTED/AGENTS 一律\"见 STATUS\",不写字面版本(de-mirror 闸 `no-version` mode 强制)|\n| **docs 站要不要跟着发版发布** | [`RELEASING.md`](./RELEASING.md) §Step 4 | = **owner 决定,不是 REQUIRED**(owner 裁定 2026-07-31,此前 Step 4 写 REQUIRED / [[INFRA-F84]] 残余① 写 owner 决定,两处各说一套)。测量口 = `pnpm check:docs-site-version`(三态 `0`/`1`/`2`,`2` 当 `0` 用就是假绿),别处只指回 Step 4 |\n| **layout 断点 / 容器宽的数值** | `src/tokens/variables.css` §`── Layout breakpoints ──` + §`── Layout containers ──` | code-first(owner 拍 2026-07-31,登记在 `divergences-decisions.json`);CSS `@media` 吃不了 `var()` → 引用的可校验形式 = 字面量 ∈ token 值集合,`audit:layout-tokens` 机械核;非 CSS 消费方走 `./tokens` DTCG + `./tokens/js`(同一份文件派生,不存第二份)|\n| **plugin 版本号** | `PLUGIN.md` §版本表 | 与 npm 版本独立;de-mirror 闸 `no-npm-version` mode 放行本文件自身 plugin 版本 |\n| **发版历史 / changelog** | `CHANGELOG.md`(外部)+ `STATUS-CHANGELOG.md`(内部)| — |\n| **排期 / 版本包含哪些** | `retrospection/design-spec-canonical-alignment-tracker.md` §排期原则 | STATUS Version Roadmap 段是镜像 |\n| **Active backlog 全量** | `backlog.md` §Active | STATUS \"Active 后续工作\" 是计数镜像(C4 gate 核)|\n| **5 能力定义** | `PROJECT_GOAL.md` §一句话目标 | 能力**成熟度/状态** → STATUS §能力×成熟度表 |\n| **Figma↔Code 真源原则 + 合法 divergence** | `FIGMA_AS_SOURCE_OF_TRUTH.md` + `translation/divergences-decisions.json` | — |\n| **组件公开 API(props/values)** | 组件 SFC `defineProps`(如 `ButtonBridge.vue`)+ 文档站组件页 | 文档示例必须与 SFC 一致;F58 实证 GETTING_STARTED/README 曾漂移 |\n| **AI 协作硬规则 / 起手链路** | `AGENTS.md` §硬规则 + STATUS §起手必读链路 | 链路 SoT 在 STATUS,AGENTS 只登记任务触发表 |\n| **文档间\"改 X 复查 Y\"依赖** | `docs/internal/doc-sync-map.json` | audit:doc-sync 校 |\n","numLines":240,"startLine":1,"totalLines":240}}} {"type":"user","message":{"role":"user","content":[{"tool_use_id":"toolu_018HwonZPBvnMaqWomtqFuB6","type":"tool_result","content":"1\t# AI Agents 必读(跨 AI 工具通用)\n2\t\n3\t> 本文件适用于:Codex / Claude Code / Cursor / Cline / GitHub Copilot / 任何在本仓库工作的 AI 工具。\n4\t\n5\t---\n6\t\n7\t## 仓库身份(Owner / 默认作者)\n8\t\n9\t- **Owner**:Nancy ``\n10\t- **默认 UX 交付说明作者**:Nancy(任何 M23 规则卡 / annotation footer 的 \"Author / 作者\" 字段默认填 Nancy,不要写通用 \"UX\" 角色名)\n11\t- **AI 工作时的身份约定**:AI 是 Nancy 的 plan-owner / executor 代理,**不是独立角色**。所有 AI 写出的 commit / PR / annotation 都视为 Nancy 的署名工作\n12\t\n13\t任何 AI 在生成 attribution(commit author / annotation author / handoff doc 作者行 / Jira reporter 等)时**默认填 Nancy**,除非用户在当前 session 明确指定其他人。\n14\t\n15\t---\n16\t\n17\t## ⛔ Mockup Write Gate(TVU 产品 Figma 写操作 mandatory)— 2026-05-27 新增\n18\t\n19\t任何 AI 工具(不限 Claude Code)在对 **TVU 产品 Figma 文件** 做写操作前——包括但不限于:加 mockup / 改 mockup / 加 UX 交付说明 / 加 jira 组件 / 加注释 / 加 page / 加 tooltip / 调样式——**必须**先完成 4 步:\n20\t\n21\t1. **Read [`docs/internal/mockup-conventions.md`](./docs/internal/mockup-conventions.md) — 按文件顶 §🤖 AI 读取指引 scoped 读**(起手必读段 + 触发 jump,禁全量吞;**读哪几条由该文件顶部的 §🤖 AI 读取指引 jump 表按你的任务派**,⛔ 这里不再抄一份「重点规则」清单 —— 抄一份就是一处会漂的副本,2026-08-14 扩 `audit:rule-inventory` 分母时实测这里抄的那份里,有一个 id **活源根本不存在**)\n22\t2. **Read [`docs/internal/design-process.md`](./docs/internal/design-process.md) § Pre-Phase 0(含 § No Open Questions in Deliverables)+ § Stage 0.5 + § Scope Handling + § Delivery Cleanup Gate**(Stage 0.5 含字段长度分布声明,M43 UX-side 镜像;§No Open Questions = 触发器 P 落地:起手扫齐 open questions + 交付物零未决项,禁止贴 Figma)\n23\t3. **Read [`docs/internal/figma-component-catalog.md`](./docs/internal/figma-component-catalog.md) 标题列表**(lazy reference,具体 entry 按需 grep)\n24\t4. **从 [`docs/site-review-manifest.json`](./docs/site-review-manifest.json) 拿 library fileKey**(不要靠扫产品文件 instance 反推)\n25\t\n26\t**⛔ 写操作全程走 §M-LIFECYCLE 三时点闸**([`mockup-conventions.md` §M-LIFECYCLE](./docs/internal/mockup-conventions.md))——任何 create / update / delete:\n27\t- **操作前**:create/move 先 probe 目标区防叠加(§I6) · update 先 live 重读做最小 delta(§I5) · delete 先确认目标 + 处理指向它的 connector(§I5/§M23.6)\n28\t- **操作后(每批次,不拖到末尾)**:跑 `pnpm audit:mockup-conformance --file --node <一个 nodeId>`(规则清单 + 条数真源 = **跑一次 `pnpm audit:mockup-conformance --list-rules`**,⛔ 别在这写死条数、也别指某个会搬家的代码位置 —— 2026-08-24 合并后它已从 `AUDITS` 数组挪进 `scripts/mockup-rules/index.mjs`)+ `use_figma` connector centerline probe;违例当场修\n29\t- **走查时**:design-walkthrough 三轴全跑、机械维度贴机检 pass/fail、机检覆盖面 = 全 session 触碰节点 —— ⚠️ **`--node` 只吃一个 id**,覆盖多节点 = 逐节点跑或整文件跑(**用法真源 = [`scripts/audit-mockup-conformance.mjs`](./scripts/audit-mockup-conformance.mjs) 头注释**,本文件不复述)\n30\t\n31\t**触发判定(命中任一即触发)**:\n32\t- 用户给了 Figma URL + 任一动词:\"加 / 改 / 调 / 更新 / 同步 / 推 / 画 / 设计\"\n33\t- 用户说\"加 UX 交付说明 / UX notes / 加 jira 组件 / 走查 / 角色测试 / persona / journey map\"\n34\t- 用户说\"基于昨天的页面修改\" / \"在上一期 mockup 上加 X\" / \"clone 这个 page 改 Y\" → 额外触发 M46 (Library Instance Iteration Discipline)\n35\t- fileKey 命中 TVU 产品文件(典型如 TPC-20220519 `xu7H3ppLyQfa3fOmU8M7iO` / Micro-Apps-20250923 等;非 library 文件均按 TVU 产品文件处理)\n36\t\n37\t**严禁**:\n38\t- 用 claude.ai 通用 `figma-use` / `figma-generate-design` skill 替代 TVU 专属硬规则(M23 等会被整段跳过)\n39\t- 用 memory cache 替代 mockup-conventions.md 真源(memory 是工具私有缓存,规则演化 memory 会过期)\n40\t- \"起手只读 STATUS.md,mockup 规则现场拍\" → mockup 写操作硬规则前置,不允许现场拍\n41\t- 起手用 createFrame 自画 overlay 覆盖既有库 instance → 违 M46 (Library Instance Iteration Discipline);正路是先 probe instance 可改性\n42\t- M23 UX 交付卡里塞 regex / pseudocode / 长代码块 → 违 M23.10 (Audience-Aware Language)\n43\t- 把 Persona / out-of-scope 声明 / 未来 roadmap 这类 tangential 内容塞进 UX 卡 → 违 M23.11 (Scope Discipline)\n44\t- \"本期不动 R list\" 误读成 \"hide R list\" → 违 design-process.md § Scope Handling\n45\t- Session 收尾前不走 cleanup → 留下被 supersede 的临时 spec / overlay / code 卡 → 违 design-process.md § Delivery Cleanup Gate\n46\t- 调列宽 / 改 cell 内容后只截整表缩略图自检 → 违 M43.2 (Column Width Self-Audit),必须 zoom-in 每列\n47\t\n48\t**违反信号 → 上一段输出不合格,重做**:\n49\t- UX 交付说明卡用了 cream / 浅底 / 单语 / 非 navy `#2B2D42` → M23 违例\n50\t- 表格新增字段没在 mockup 里给 3 状态(正常 / 截断 / hover tooltip) → M43 违例\n51\t- 自画 RECTANGLE+TEXT 拼 tooltip / button / 注释卡 → M32 Library-First 违例\n52\t- 装饰元素 / NEW badge 浮在 page 层不在 mockup frame 内 → M-INTEGRITY §I4 违例\n53\t- 改了 text 节点 fontName 但没保留 textStyleId → M47 违例(cell 渲染会变灰 / 错位)\n54\t\n55\t**实证**:\n56\t- 2026-05-27 FB-9398(TPC-Service 消费端):AI 起手只加载 claude.ai 通用 `figma-use` skill,跳过 mockup-conventions.md → UX 交付说明卡用 cream 浅底自由设计 + 单语 → 用户连续两次抓\"没用 TVU 设计系统已有规则\"\n57\t- 2026-05-28 TPC-628(TPC-Service 消费端):AI 起手 clone FB-9398 后误判 instance 不可改 → 跳到自画 overlay;又把 NEW badge 放 page 层;font fallback 时丢 textStyleId 让 cell 变灰;列宽 rebudget 砍了 Operation 列但没 zoom-in 验证 Edit/Delete/Status 三按钮溢出;收尾时留下 spec 帧 / Display Logic 代码卡 / Persona 卡等冗余 → 用户连续抓 7 次。本次回流加 M46 / M47 / M-INTEGRITY §I4 / M23.10 / M23.11 / M43.2 / Scope Handling / Delivery Cleanup Gate 等规则。\n58\t\n59\t---\n60\t\n61\t## ⛔ Onboarding Gate(第一个项目相关回答前 mandatory)\n62\t\n63\t**任何 AI 在第一个项目相关任务 / 推荐 / 回答前,必须先完成 [`docs/STATUS.md` §起手必读链路](./docs/STATUS.md#起手必读链路) 的两层 onboarding**(该节是链路唯一 SoT,本文件不重复维护清单 — 2026-06-10 P1-07/P1-08 重构):\n64\t\n65\t- **L-core 全文必读(4 份,禁 grep / 跳读)**:FIGMA_AS_SOURCE_OF_TRUTH → STATUS → PROJECT_GOAL → 当前 pickup。⚠️ **体量 / 耗时预算的唯一真源 = STATUS §起手必读链路**,本文件刻意不复述那个数字 —— 那四份自己每工作日都在涨,复述一份就是又一处会漂的副本(原 INFRA-F95 已付代价 4:两处都写「~40KB」而实测 2.2× —— **该 entry 2026-08-13 已闭合删档**,这条实证的留痕在 `STATUS-CHANGELOG` 与 `audit-doc-shape.mjs` 头注释)\n66\t- **L-ref 最小集必读 + 命中触发深读**:本文件 §硬规则表 + §Onboarding Gate 是每 session 最小集;tracker §排期原则 / backlog 当前 entry 全文 / meta-rules / working-principles / translation/ 按触发表升级 —— 触发表见 STATUS §L-ref\n67\t- **Mockup 任务**:§Mockup Write Gate 4 步前置 + §必读链路 7-11 整链升 mandatory(不受分层影响,仍是硬规则)\n68\t- **唯一减档 = 微改档**(单文件 · 纯文案 · 不换组件不改 token):判据 / 必读集 / 自动升级条件的**唯一 SoT = [`STATUS.md` §微改档](./docs/STATUS.md#微改档单文件纯文案的减档)**,本文件刻意不复述(owner 2026-08-13 裁定新增;复述一份就是第二处会漂的副本 — [[INFRA-F121]] 已付过这个代价)。⚠️ 上一条 L-core「4 份」在微改档下减为 **#0 + 本文件 §硬规则表**;mockup 写操作**不适用**本减档\n69\t\n70\t**机械执行**:用 TodoWrite / TaskList / 等价机制为 L-core 每项 + 命中的 L-ref 项各建 1 个 todo,逐个 Read 完才能开始回答。**基于 partial L-core 给推荐 = 协议违反**。\n71\t\n72\t**违反信号(分层版)+ 历史实证**:见 [`STATUS.md` §起手必读链路](./docs/STATUS.md#起手必读链路)(该节是链路唯一 SoT,含完整违反信号分层 + 2026-05-13/2026-06-10 P1-08 实证)——本节不再内联镜像,避免两处各改一处忘的 drift(DUP-01;此前 AGENTS 版已漏掉 STATUS 版的 P1-08 教训)。\n73\t\n74\t---\n75\t\n76\t## AI 响应格式规则(决策点 / 推荐型回答 mandatory)\n77\t\n78\tAI 在面对决策点 / 给用户多选项 / 推荐方案时,响应**必须包含 4 块**(缺一不合格):\n79\t\n80\t1. **总计划 / 总数字**:当前剩余多少问题 / 总任务清单(含已完成 + 待办)\n81\t2. **本次范围**:本轮做了什么 / 影响多少数字\n82\t3. **明确推荐**:选哪个,不要\"A 或 B 都可以\"模糊话;候选 ≥ 2 个时必须排序 + 标默认\n83\t4. **推荐理由**:3 条以内核心理由\n84\t\n85\t**违反信号**(命中任一 → 上一条响应不合格,重写):\n86\t- 用户问\"推荐哪个\" / \"还剩多少\" / \"总计划呢\" → 重写\n87\t- 用户说\"我自己决定\" / \"你决定\" → 默认仍要给推荐;\"我没意见\"不算合规\n88\t- 列了多选项但没排序 / 没标默认 → 重写\n89\t\n90\t**历史实证**:2026-05-20 session 用户多次因为这 4 块缺失追问 / 重发问题(典型:\"你没告诉我剩下还有多少问题?你推荐解决哪个?为什么\")。\n91\t\n92\t**规则分层(DUP-05 — 出推荐时三条协同、非重复)**:本节 = **输出契约**(响应长什么样)。配套两条在 [`meta-rules.md`](./docs/meta-rules.md):**触发器 F**(出推荐**前**的推荐自审 4 问:理由经得起反驳吗 / 有没有把最省事项包装成 #1 / 有没有更稳健选项被压脚注 / 该我拍还是 owner 拍);**触发器 E**(决策疲劳态下\"只给一个推荐拍 Yes/No\"的 mode override——与本节\"候选 ≥2 排序标默认\"不冲突:E 管疲劳态、本节管常态多选)。三者 = 自审→输出→疲劳降级 的分层,不是三份重复规则。\n93\t\n94\t---\n95\t\n96\t## 项目一句话\n97\t\n98\t把 **Figma 已发布 Library**(组件 / Token / 图标 / Styles)做成 **AI 与开发可消费的双向 Figma↔Code 桥**。\n99\t\n100\t> **5 个能力的完整定义 + 各能力前置约束(T3/T4 schema 设计要点)+ 能力 3 的边界分层,真源 =\n101\t> [`docs/PROJECT_GOAL.md`](./docs/PROJECT_GOAL.md) §一句话目标**。能力**成熟度 / 当前状态** →\n102\t> [`docs/STATUS.md`](./docs/STATUS.md) §能力 × 成熟度表。\n103\t>\n104\t> 2026-08-03 本节从全量镜像收成一句 + 指针([[INFRA-F58]] D1)。原先这里复述了 5 条能力**并夹带\n105\t> 会变的数字与 key**(`render-verification-manifest 936 条` / `YbsPRUVmNdsbN40NNwh1Gn` / \"待 Pro plan\"),\n106\t> 那是三份现状真源的第四份副本 —— manifest 条数与 plan 状态都在别处随时会动。\n107\t\n108\t---\n109\t\n110\t## 必读链路\n111\t\n112\t> **Onboarding 链路唯一 SoT = [`docs/STATUS.md` §起手必读链路](./docs/STATUS.md#起手必读链路)**(L-core 全读 + L-ref 按触发深读)。本节不再维护并行清单(2026-06-10 P1-07 双链路 drift 治理),只登记 **L-ref 的任务触发表** —— 命中触发即把对应真源升为该任务的 mandatory 深读:\n113\t\n114\t| 触发(做什么) | 深读真源 |\n115\t|---|---|\n116\t| 排期 / 版本决策(\"v0.X 含哪些 / 先做哪个 / 该不该上 Tier N\") | [`tracker`](./docs/internal/retrospection/design-spec-canonical-alignment-tracker.md) 全读(最小集 = §排期原则) |\n117\t| 写 prompt / 设计机制 / 给推荐方案 | [`docs/meta-rules.md`](./docs/meta-rules.md) 反模式清单 |\n118\t| **写 UI 代码**(Vue / React / HTML — 含本仓库 `playground/docs/*`、`src/components/*`、下游产品 demo 与 PoC) | [`docs/internal/code-conventions.md`](./docs/internal/code-conventions.md) 顶部 **§🤖 AI 读取指引 的「起手必读段」**(含 §R0 Phase 0 元素→组件映射 + §R7 四场景判断 + Task Entry Modes;具体 R-rule 按该表触发条件 jump)。⛔ 按 scoped 读,**禁全量吞**(该文件近 90 KB);⛔ 跳过起手必读段直接进单条 R-rule = 协议违反(该文件自记「漏 R0 Phase 0 是历史最高频回归源」) |\n119\t| 实现决策:命名 / token / API 形态 / 图标 alias | [`docs/working-principles.md`](./docs/working-principles.md) 9 条原则(0-8)对应条 + [`src/design-system/translation/`](./src/design-system/translation/) 4 文件(`prop-aliases` / `divergences` / `icon-aliases.ts` / `token-aliases.ts`) |\n120\t| 数据来源 / 生成链 / 清理规则 | [`docs/PROJECT_MAP.md`](./docs/PROJECT_MAP.md) |\n121\t| 历史决策回溯 / \"怎么走到这里的\" | [`docs/internal/retrospection/`](./docs/internal/retrospection/)(最新日期) |\n122\t| 接手 sprint task / 立新 entry | [`docs/internal/backlog.md`](./docs/internal/backlog.md)(当前 entry 全文;新 ID 先 grep 全部已用) |\n123\t\n124\t### Mockup 任务额外必读\n125\t\n126\t> 任何 AI 工具收到\"在 TVU 产品 Figma 文件画 UX mockup / 改 mockup / 抽组件入库\"类任务时,**除 L-core + 上表命中项外,下列 7-11 整链升 mandatory —— 各文件按其顶部 §🤖 AI 读取指引 scoped 读**(§Mockup Write Gate 的 4 步前置照旧):\n127\t>\n128\t> ⚠️ **第 11 项不是「读一份文件」而是「跑一条命令」**(2026-08-14 加入)—— 因此上面那句「按 §🤖 AI 读取指引 scoped 读」对它不适用,它的执行方式与输出怎么读,见该项自己那段。\n129\t>\n130\t> ⚠️ **\"mandatory\" 修饰的是「这条链一份都不能跳」,不是「逐字全量吞」**([[INFRA-F121]] ② 2026-08-13 统一)。此前本行写「整链升 mandatory **全读**」,与上方 §Mockup Write Gate 第 1 步逐字要求的「按文件顶 §🤖 AI 读取指引 scoped 读(…禁全量吞)」互斥,而两条指的是同一份 `mockup-conventions.md`、又都标 mandatory —— 实测两种读法差 **2.5 倍字节**。⇒ 以 scoped 读为准;某文件没有 §🤖 AI 读取指引块的,才全读。\n131\t>\n132\t> (**此 7-11 链 SoT = 本节**,是 mockup 任务的 scoped 强化清单,有意内联——**不属于 §必读链路开头所指的\"并行清单 drift\"**,无需归并到 STATUS。)\n133\t\n134\t7. **[`docs/internal/design-process.md`](./docs/internal/design-process.md)** — 通用 process 规则(**完整清单见该文件头 `rule-inventory` 块 = 唯一真源**,此处不再枚举)\n135\t8. **[`docs/internal/domain-tvu.md`](./docs/internal/domain-tvu.md)** — TVU 业务规则(**完整清单见该文件头 `rule-inventory` 块**)\n136\t9. **[`docs/internal/mockup-conventions.md`](./docs/internal/mockup-conventions.md)** — Path A 专属(Figma 真源 / 组件取数优先级 / 库归属验证 / M0 / M1 / M10)\n137\t + **[`docs/internal/figma-technical-reference.md`](./docs/internal/figma-technical-reference.md)**(Figma API quirks,实现时查)\n138\t10. **[`docs/internal/figma-component-catalog.md`](./docs/internal/figma-component-catalog.md)** — TVU 已发布库组件目录快速查(mockup 任务起手第一查,避免凭印象造组件)\n139\t11. **跑一次 `pnpm pattern:lookup <本次的 figma URL>`** — 查**本产品自己**已经做过哪些模块(owner 2026-08-14 拍定,走[提案](./docs/superpowers/specs/2026-08-13-product-pattern-index-proposal.md) §7 的 Q2 候选 (a))\n140\t\n141\t> **第 10 与第 11 是两个不同的问题,⛔ 别合并**:第 10 问「**DS 库**有没有这个原子」(Button / Input / Table,跨产品);\n142\t> 第 11 问「**这个产品自己**有没有做过这个模块」(设备状态卡 / 告警行 / 参数面板,产品专有、DS 不该收)。\n143\t> owner 的痛点逐字是「用了设计库组件、**没用当前产品已有的组件**」—— 那是第 11 条治的,第 10 条结构上看不见。\n144\t>\n145\t> **⛔⛔ 这一条最容易被用错的方式:把「查不到」读成「没有」。** 工具输出四态,**只有 `✅ covered` 那一态**\n146\t> 能得出「本产品已有 X」;`⬜`(还没采过)的正确结论是「**我查不到**」,⛔ **不是**「没有先例可复用」。\n147\t>\n148\t> **⇒ 命中 ⬜ 的正确动作是「当场采一次再查」,不是「跳过这一步继续画」**:\n149\t> `cd <主工作树> && node scripts/ds-health-scan-mockups.mjs --only `(一步,⛔ 不需要预先登记、\n150\t> 不需要审批;worktree 没有 `.env` ⇒ 必须从主工作树 cwd 跑)。采完重跑第 11 项即可。\n151\t> **⛔ 这里没有、也不该有「先申请纳入采集面」这类白名单** —— 原来的 `patternIndex: true` opt-in\n152\t> 已于 2026-08-14 拆除(owner 逐字:「为什么要把消费级产品一个个拉进来?我要做的是规则,不是实测」)。\n153\t> 任何产品文件都能就地采;已登记为 DIM-U12 测量目标的,全量跑 `pnpm health:mockups` 时顺带就刷新了。\n154\t> ⚠️ 唯一的例外是**采集实在跑不了时**(无 Figma 凭据 / 网络不通):那时才「照常按本链其余步骤走」,\n155\t> 并在交付里如实写明「本产品 pattern 索引未采到」,⛔ 别写成「无先例可复用」。\n156\t>\n157\t> **为什么这一条是「跑命令」不是「读文档」**:提案 §7 逐字写着,能否定掉整个索引的唯一理由是\n158\t> 「没有任何机制保证有人在画之前查它」。只写一句必读,等于把成败押在每个人每次都记得上 ——\n159\t> 那正是本仓「规则别继续往 L1 prose 加」要治的病。**判据/数据真源与五态语义在\n160\t> [`scripts/pattern-index-lookup.mjs`](./scripts/pattern-index-lookup.mjs) 头注释,⛔ 别在本文件维护第二份。**\n161\t> ⚠️ 它是**查询不是闸**(always exit 0,不拦任何东西)—— 本条的 Enforcement 层级是 **L1**:\n162\t> **没有任何机制能发现「有人跳过了这一步」**。这是如实登记的事实,⛔ 不是待补的 TODO。\n163\t> **「为什么停在 L1 + 什么条件下才该升」的唯一真源** = [`scripts/pattern-index-lookup.mjs`](./scripts/pattern-index-lookup.mjs)\n164\t> 头注释里那个 📌 段(owner 2026-08-14 拍定)。⛔ **别顺手给它加个闸** —— 先读完那三条为什么;\n165\t> 尤其别走「新建组件与已有 pattern 相似度」那条,它是启发式,直接撞 `FIGMA_AS_SOURCE_OF_TRUTH.md` §验证方法。\n166\t\n167\t---\n168\t\n169\t## 硬规则(不可违背)\n170\t\n171\t| # | 规则 | Enforcement 层级 | 违反后果 |\n172\t|---|---|---|---|\n173\t| 1 | **不修改 Figma**——Figma 是设计师真源 | L4-partial:pre-commit 拦 figma-data/ sync-output 镜像写入;**Figma 端写操作本身无机制可拦(L1)** | 任何 Figma 写操作都是 bug |\n174\t| 2 | **不让 AI 按\"行业惯例\"自由发挥** | L1(AI 自律;登记缺失由 #5 的间接链兜底) | 必须读 translation/ 已登记决策;新决策必须先得到用户确认 |\n175\t| 3 | **不创建未登记的 prop / variant / 状态** | L2 间接:无 commit 时拦截,render-verification + published-vs-code 事后抓 drift | 例:Notification 的 `success` 曾是 code 自创 drift;2026-06-12 owner 在 Figma 正式补 `dialog`×`success` 并随发布登记 → 由 drift 转为合法(先 Figma 后 code,符 §\"Figma 库 master 变更→code 原子同步契约\") |\n176\t| 4 | **颜色硬编码 = bug** | L5:`audit:no-hardcoded-design-tokens`(prepublishOnly + master-push CI) | 必须用 token;token 缺失就新建,不能写 hex |\n177\t| 5 | **任何 Figma↔Code 不一致必须先在 translation/ 登记** | L2 间接:`audit:translation-completeness`(L5)只验**已登记**条目;未登记漂移靠 render-drift-gate 事后抓 | 不登记的不一致 = 漂移 |\n178\t| 6 | **AI 工具从 Figma URL 生成代码必须用 `src/canonical/*` 作为 SoT,不用 `src/components/*`** | L1(DS 仓内);consumer 侧 L4-partial(eslint `no-base-component-import`) | `src/components/*` 是实现/base 层,`src/canonical/*` 是 Figma-aligned 桥层(npm 经 `src/index.ts` 导出 canonical)。落 base/legacy → 输出 API 错位。详见 [`src/design-system/translation/divergences.md`](./src/design-system/translation/divergences.md) \"Code 端双源\" 段 |\n179\t| 7 | **代码改动必须走 feature 分支 + PR (non-Owner 约束);Owner 任何改动均可直 commit master**(2026-05-28 broader Owner override 落地,原 docs-only 例外被升级)| L3 平台:Gitea 分支保护(non-Owner)+ Owner override 政策条款 | 见下方「Git 工作流(强制)」段。Owner 例外见 §\"Owner 直 commit master 权限(broader 2026-05-28)\" |\n180\t| 8 | **组件 demo 必演示 Slot + Boolean 属性(Vue playground + React pilot 双框架)**(owner 2026-07-03 拍板)| **L4**:pre-commit 条件 gate + blocking `audit:demo-slot-boolean`(INFRA-F45 shipped 2026-07-06;`scripts/audit-demo-slot-boolean-coverage.mjs` 从 `components.config.ts` 派生 in-scope=28,静态断言双侧 slot 投影 + boolean live 绑定;staged 命中 demo surface/config/audit 时触发)| 凡有 default/named slot 或 boolean prop 的组件,其 docs demo 必须在 **Vue 与 React 两侧**各演示(a)slot 投影真实内容、(b)至少一个 boolean prop 的 live 切换。理由:slot 投影与 boolean 属性是双框架 CE 最易 silent 破的两条链(实证 INFRA-F43 light-DOM slot 不投影恒空 body 数版本未被发现)。首个 exemplar = PopupBox;全量回填后每个 in-scope 组件双侧达标,audit gate 防回归。|\n181\t| 9 | **AI 不得编造 / 虚构工具输出**——随机标识符(commit hash / SHA / 时间戳 / exit code / 测试 passed 数)只能从工具原始输出逐字复制,不准生成 | L1(无机制可拦 AI 幻觉,唯靠纪律 + 用户终端核对) | ① commit hash / SHA / 时间戳 / exit code / passed 数 = 从原始 stdout 逐字复制,绝不自己生成;② 不可逆 / 外部可见操作(commit / push / publish / 删除)的结果以**原始工具输出**或用户终端核对为准,**不得用\"已成功 / 已一致 / 已通过\"概括代替原文**;③ 工具输出超时 / 被省略 / 截断 / 前后矛盾 / 可疑时 → **STOP 交用户在终端核**,不自行接管编造。**归因要准**:病根是 AI 编造,**不是**\"工具不返回\"——多数情况工具正常返回真实数据(2026-07-15 本 session 实证工具输出全真实可核)。真源 memory `no-fabrication-on-uncertain-tool-output` + `local-env-tool-quirks`。实证:上个 session(D2 Task 9 首次尝试)AI 伪造过不存在的 commit hash / push 成功 / 测试通过 / SHA 一致,逼用户起新 session 从真实基线重做 |\n182\t| 10 | **结论必须对\"活源\"验证,不凭摘要 / 镜像 / 记忆下判断**——判断仓库或远端的**当前状态**(某文件是否存在 / 内容为何 / prop-token 名 / 组件是否已同步 / 远端卡片长什么样)前,**必须直接读活源**:本地 `Read` / `grep` 实际文件;远端 DesignSync `get_file` 实际内容。**不得**拿派生镜像 / 摘要 / 记忆缓存 / 面板 UI 当依据下结论。 | L1(无机制可拦,唯靠纪律;由 #9 事后核对间接兜底) ⚠️ 2026-08-20 新增一个此前未登记的形态:**计划文件里的具体值(prop / 导出名)未对活源核** —— 已上机械闸 `pnpm audit:claim-vs-livesource`(pre-commit 条件触发 + pr-checks;INFRA-F133)。⚠️ **该闸对这个形态是 report-only(每次跑、每次印、不阻断)**:落地当天校准实测假阳性率 **86.7%(13/15,35 份指令型文档)**,按 spec §9 退档条件退档;阻断档只保留三条 fail-closed 基础设施判据(活源分母 / 扫描面 / 豁免表 shrink-only)。⚠️ **闸只覆盖这个形态的 prop 名那一半**:barrel 导出名虽然解析了,但只喂活源分母与覆盖面自印,**没有任何判据比对导出名断言**(词法上「导出名断言」与闸选宿主用的形态重合,全比一遍必然是噪声 —— 理由见闸脚本头注释,缺口登记在 backlog `INFRA-F133`)。⛔ 判据、档位与结构化区域定义的真源是[闸脚本头注释](./scripts/audit-claim-vs-livesource.mjs),**别在本表维护第二份**。⇒ 仍靠纪律的是:**结构化区域里的断言(S2 只印不红)**、散文里的断言(S5 只印不红)、**导出名断言(不在覆盖面)**、对话里的口头结论、以及**文档断言 × 另一份文档的当前版本**(本闸只核代码活源)。 | 二手源会 drift,信了就\"读错\":① 导出 bundle 的 `01–14` ≠ repo 真源——**改规则去 `docs/` / `docs/internal/`,别去 bundle 找**([`PROJECT_MAP.md` §9](./docs/PROJECT_MAP.md));② 现有远端卡的 prop ≠ canonical——**照抄现有卡 = 复制 drift**,prop 名一律以 `src/canonical/*.vue` 为准;③ DesignSync 面板 `updatedAt` / 卡片对**非视觉写入不刷新**——别拿 UI 当同步凭据,写完逐文件 `get_file` 亲验(memory `designsync-nonvisual-writes-no-ui-bump`);④ memory / handoff / 摘要文档是工具私有缓存或时点快照,规则演化后会过期,**只作导航,不作真源**(形态 ①④ 2026-08-20 已评估:无可靠词法解 —— 实测 71 处引用中 48 处报红且多数假阳性,\"当依据\"与\"当对象\"是语义区分 ⇒ 维持 L1,不上闸)。**病根 = \"AI 读错\":信了会漂移的二手源。** 实证:Sync A 6 卡审计中 5 卡有 prop drift(Badge/Button 的 `tag`/`variant` → 应 `fill`、UserMenu `items[]` → 应 `actions[]` 等),正是历史上照抄现有卡、未回 `canonical` 活源验证的结果。
⚠️ **2026-08-11 补一个被漏掉的形态(PR #9 实证):多分支协作下,你自己的本地工作树也是一种会过期的镜像。** 那次撞号的一方读的是**本地实际文件**(不是摘要、不是 memory、不是面板 UI —— 完全符合本条),只是那份文件已经 62 天没同步,于是把 master 上早已占用的规则编号又用了一遍。⇒ 判断**全局命名空间的当前状态**(规则编号 / backlog entry ID / token 名 / 已用过的 key)时,活源是 **`origin/master`**(先 `git fetch`),不是本地文件。已上机械闸:`pnpm audit:rule-number-collision`(pre-commit 条件触发 + `pr-checks.yml` 带 `--require-remote`)+ 分配器 `pnpm rule:next <系列>` / `pnpm new-backlog <前缀>`。⚠️ **2026-08-20 订正**:此处原写「该闸只覆盖三份规则真源的编号,**看不到 backlog entry ID**,那一条仍靠本纪律」—— 原 [[INFRA-F109]] 已落地,`docs/internal/backlog.md` 的 **entry ID 现已在覆盖面内**(含 `####` 层级、无 `F` 中缀、带连字符前缀、umbrella 范围标题四种形态;⛔ 覆盖面与仍看不到的三样,真源是[闸脚本头注释](./scripts/audit-rule-number-collision.mjs),**别在本表维护第二份**)。⇒ 本条仍需靠纪律的只剩「**已删档号被重新占用**」(完成即删档 ⇒ 被删 ID 在 master 文本里已不存在,闸看不见)—— 取号一律走 `pnpm new-backlog`,它扫三份 SoT 全文、含历史提及 |\n183\t\n184\t> **Enforcement 层级图例**(对齐 [`meta-rules.md`](./docs/meta-rules.md) 触发器 K 的 L1→L5 谱系;列加于 2026-06-10 system-review P2-04):**L1** = 文本规则靠 AI/人自律 · **L2** = 无直接拦截但有事后 audit 可抓 · **L3** = 平台/流程机制 · **L4** = 本地 pre-commit hook(可 `--no-verify` 绕过)· **L5** = prepublishOnly / CI strict gate。**各条规则强度本不相同**——没有这列时\"同等强\"是错觉;声称\"有 gate 兜底\"前先对照此列。\n185\t\n186\t---\n187\t\n188\t## Git 工作流(强制)\n189\t\n190\t`master` 受分支保护,**non-Owner 的任何代码改动必须走 PR**。AI 在本仓库工作时遵循以下决策树:\n191\t\n192\t> **⚠️ Owner 例外**:默认操作者 Owner(Nancy)**可直 commit master、不建分支**——见下方 §\"Owner 直 commit master 权限(broader 2026-05-28)\"(硬规则 #7 已编码)。本节决策树主要约束 non-Owner,及 Owner 在当前 session 明示\"走 PR / 建分支\"的情形。\n193\t\n194\t### 分支决策(non-Owner 贡献者适用)\n195\t\n196\t> **本仓实际默认 = Owner(Nancy)直 commit master、不建分支**(硬规则 #7,见下方 §Owner override)。下面仅约束 non-Owner 贡献者,或 Owner 在当前 session 明示\"走 PR / 建分支\"时。\n197\t\n198\t1. **在 master 起手** → `git checkout -b /`(type ∈ feat/fix/docs/chore/refactor/test)。\n199\t2. **已在 feature 分支** → **强默认复用同一分支**。边界按**主题**(非文件/组件):同会话持续指令、无\"切任务\"信号 = 同主题,累积 commit 最后一个 PR。拆多分支/多 PR = 反模式(增 review 摩擦、破坏语义聚合)。\n200\t3. **只在三种情况换分支**:用户明说\"另一个任务/新分支\"、当前 PR 已合并(master 已含该分支)、主题完全跨域(最后一种先问 owner)。**不主动问\"是否换分支\"**。\n201\t\n202\t### Commit + Push\n203\t\n204\t- Commit message 用 Conventional Commits:`type(scope): description`(如 `feat(button): add loading state`)\n205\t- 一个分支可以多个 commit,PR 合并时会汇总\n206\t- Push 后把 Gitea 自动返回的 PR 创建链接给用户:\n207\t ```\n208\t https://product-demo.tvustream.com/gitea/ux-team/tvu-design-system/compare/master...<分支名>\n209\t ```\n210\t\n211\t### 并行 session 下的 git 纪律(本仓库常态:多 session 同时写)\n212\t\n213\t**本节是这两条纪律的唯一真源**(2026-08-04 从 `docs/STATUS.md` 顶部搬来——它们是规则不是状态)。\n214\t\n215\t1. **接手前先 `git status`;遇到 dirty / untracked 先判「隔夜遗留」还是「别人正在写」** —— 这两种情况的正确动作**相反**,而判据**不是**「dirty 就是别人的」,是 **mtime + `git log` 有无同任务 commit**。两次实证都在 2026-07-30/31 的多 session 并行里:起手时靠它判出 `UserMenu.vue` 正被并行写(mtime 与本 session 起手同分钟)从而没去碰;收尾时又靠它把一批「看着像隔夜残留」的 untracked 判成**正在进行**(mtime 在当下几分钟内),几分钟后那条线自己提交了。\n216\t2. **`git commit` 必须带内联显式路径**:`git commit -F -- …`(`-F` 在 `--` 之前),**且提交后紧跟 `git reset -- `**。不带 pathspec 会把别人 staged 的文件卷进自己的 commit;不 reset 则留下幻影 staged 状态、会被别人下一次裸 commit 提交掉。⚠️ 并行写同一仓库时 `.git/index.lock` 会让 commit 直接 `exit 128` —— **那不是故障、是对方正在提交**,等一下重来即可(改动完好留在工作树)。\n217\t\n218\t### 建 PR 时如何填模板(PR body)\n219\t\n220\t建 PR 时按 [`.gitea/PULL_REQUEST_TEMPLATE.md`](./.gitea/PULL_REQUEST_TEMPLATE.md) 逐段填正文,分两类纪律:\n221\t\n222\t**必须自动填好**(从 diff / 对话可推导,不让 Owner 自己猜):\n223\t- **改动内容**:读本次 diff,逐条列出实际改了什么文件、什么行为\n224\t- **改动原因**:从对话上下文 / 关联需求写清楚,关联 Issue 写 `#编号`\n225\t- **改动类型**:按改动性质勾选(可多选)\n226\t- **备注**:reviewer 需知的点、后续 TODO、未执行项说明\n227\t\n228\t**禁止假填**(只能反映真实结果,否则误导 Owner review):\n229\t- **测试情况 checkbox**:只勾**本次真实跑过并通过**的命令;没跑的留空,并在「备注」写明\"未执行:xxx\"。绝不能凭\"应该会过\"就打勾——Owner 见勾即视为已验证。\n230\t- **截图 / 录屏**:仅 UI 改动且**真实跑过 app / playground 截取**才贴;纯 docs / 逻辑改动写\"不涉及 UI\"。不得生成或捏造截图。\n231\t- **检查清单**:只勾确实核对过的项。\n232\t\n233\t**Why**:模板的价值是让 Owner 一眼判断该不该合。勾选若不可信 → 比留空更糟(制造虚假安全感)。AI 应把\"哪些已验证 / 哪些没验证\"如实写出,判断权留给 Owner。\n234\t\n235\t### 直 commit master 时:commit message 写结构化 body\n236\t\n237\t直 commit master 没有 PR 描述兜记录,**commit message 的 body 就是\"改了什么 + 测了什么\"的唯一载体**——按 [PR 模板](./.gitea/PULL_REQUEST_TEMPLATE.md) 字段精简对齐,让 `git log` / Gitea 提交页一眼可读,与同事走 PR 看到的信息一致、互不冲突。\n238\t\n239\t格式:\n240\t\n241\t```\n242\t(): <一句话 subject> # subject 仍遵循 Conventional Commits\n243\t\n244\t改动内容:\n245\t- <逐条列出实际改了什么文件 / 行为,从 diff 来>\n246\t改动类型:feat / fix / docs / refactor / chore …(可多类)\n247\t测试:<只写本次真实跑过的,如 pnpm test ✅ 219 passed;没跑的写\"未跑:lint/typecheck\">\n248\t```\n249\t\n250\t**纪律(与 PR 模板同源)**:\n251\t- 改动内容 / 类型从 diff 与对话自动填好,别让 Owner 自己猜。\n252\t- 测试只写**真实执行**的结果;没跑的如实标\"未跑:xxx\",绝不能凭\"应该会过\"写 ✅——Owner 看 commit 即视为已验证。\n253\t- UI 改动有截图就把路径 / 链接放进 body;纯逻辑改动注明\"不涉及 UI\"。\n254\t\n255\t**Why**:同事 PR 的\"改动 + 测试\"在 PR 描述里,Owner 直 commit 的在 commit body 里,两条路径记录同一套字段、各自独立——Owner 在 PR 列表和 git log 里都能一眼看出改了什么、测没测,统一可见且不冲突。\n256\t\n257\t### 直 commit master 时:写 changeset(版本日志)\n258\t\n259\t走 PR 有 PR 模板兜结构化记录;**直 commit master(Owner override)没有 PR**,靠 changeset 留每个版本的改动记录。仓库已配 [Changesets](./.changeset/config.json)(`baseBranch: master`),`CHANGELOG.md` 由它按版本自动生成——这就是\"按版本知道改了什么\"的真源。\n260\t\n261\t**何时写**:本次 commit **影响 npm 发布产物 / consumer 行为**时——`src/**` 组件、API/props、`src/tokens/**`、导出(`index.ts`)、`eslint-plugin/**`、`templates/**`,以及 **`files[]` 白名单内那 20 个 `scripts/`**(不是整个 `scripts/`)等 consumer-facing 资产。\n262\t\n263\t> ⚠️ **本行 2026-08-13 随 [[INFRA-F117]] 落地订正**:原文写的是裸 `scripts/`,而当时 `files[]` 也确实是裸 `\"scripts\"`(107 个内部脚本全进包)。F117 把它收窄成具名白名单后,**`scripts/` 不再整体是 consumer-facing** —— 判据改为「该文件在不在 `package.json` 的 `files[]` 里」,`files[]` 是唯一真源,别在这里维护第二份清单(要看当前白名单跑 `npm pack --dry-run`)。改一个只在本仓库跑的 `scripts/audit-*.mjs` 属**不写** changeset 的内部改动。\n264\t\n265\t\n266\t\n267\t**何时不写**(写了反而污染版本日志):纯 `docs/**`、`tests/**`、`playground/**`、`react-pilot/**`(owner 2026-08-12 明确补入 —— 它的 `src/demos/*.css` 是 docs 站两侧共用的 demo 样式,不进 `dist`)、`figma-sync/**`、CI / 内部重构等不改变发布产物的改动。\n268\t\n269\t**怎么写**:和实质改动放在**同一个 commit** 里,新增 `.changeset/.md`:\n270\t\n271\t```md\n272\t---\n273\t\"@ux-team/tvu-design-system\": patch\n274\t---\n275\t\n276\t<面向 consumer 的一句话:改了什么 + 影响。Breaking 要写迁移说明。>\n277\t```\n278\t\n279\t**bump 级别(= 改动类型)**:\n280\t- `major` — 破坏性改动(API / prop 重命名或删除、行为不兼容)\n281\t- `minor` — 新功能 / 新组件 / 新 prop(向后兼容)\n282\t- `patch` — bug 修复 / 视觉对齐 / 小调整\n283\t\n284\t**纪律**:bump 级别和描述据实写,不夸大不缩小——`changeset version` 据此 bump 版本号并汇总进 CHANGELOG,Owner 与 consumer 都按它判断升级影响。发布时 `pnpm changeset:version` 汇总、`pnpm changeset:status` 查待发布项。\n285\t\n286\t### docs 站内部 demo / 页面样式改动的快车道(owner 2026-08-12 裁定)\n287\t\n288\t**适用面(严格 AND)**:本次改动集 ⊆ `playground/**` + `react-pilot/**` + `docs/**` + `tests/**`,**且不碰 `src/**`** ⇒ 不进 npm 产物、consumer 不可见。典型 = docs 站 demo CSS、页面布局、响应式断点、**闸的判据(指 `tests/**` 里的断言,⛔ 不含 `scripts/` 下的闸脚本本身)**。\n289\t\n290\t> ⚠️ **「闸的判据」四字的限定是 owner 2026-08-13 补的**([[INFRA-F128]] 系列评估发现互斥):原文只写「闸的判据」,而闸脚本住在 `scripts/`,于是它把 `scripts/` 隐含划进了快车道面 —— 但同段的「严格 AND」谓词**根本不含 `scripts/`**(只有 `playground`/`react-pilot`/`docs`/`tests`)。owner 确认原意是 **`tests/`**(2026-08-12 那批快车道改动实际动的就是 `tests/docs-overflow/*.spec.ts` 的 `VIEWPORTS` 与判据,且它满足谓词)。⇒ **改 `scripts/` 下的闸脚本不走快车道**(谓词不含它);**changeset 则仍按上一节 §「何时写」的 `files[]` 判据判 —— 不在 `files[]` 白名单里的内部 `audit-*.mjs` 属「不写」。**\n291\t>\n292\t> > 🔴 **2026-08-13 晚就地订正本段自己的一处 stale 转述(登记为原 INFRA-F124 ④ —— **该 entry 2026-08-14 四个子项全部落地后已删档**,判据留痕在 tracker §待核可关)**:上面原写「上一节 §「何时写」又把 `scripts/` 列为 consumer-facing **必写**,三方互斥」并据此推出「⇒ …**照常写 changeset**」—— **那句描述的是 [[INFRA-F117]] 落地前的措辞**。同一天的 §「何时写」(见上一节)已把判据订正为「该文件在不在 `package.json` 的 `files[]` 里,**`files[]` 是唯一真源**」,并逐字点名「改一个只在本仓库跑的 `scripts/audit-*.mjs` 属**不写** changeset 的内部改动」。⇒ 这**不是两条对等规则打架**,是本段的前提 stale ⇒ 它推出的那半句结论失效(互斥也从「三方」降为「两方」,第三方已自行消失)。**owner 的裁定实质一个字没动** —— 快车道谓词仍不含 `scripts/`;变的只是 changeset 那一半,从「照常写」改为回指 `files[]` 判据。⚠️ 这条留痕本身是「**同一份文件内部**的规则真源冲突」的实例,与 原 INFRA-F124 的三项(跨文件冲突)同类不同形态。\n293\t\n294\t**立规缘由**:这类改动的产品体量很小(常是几行 CSS),但此前按满配纪律走 —— 逐文件问视觉批准 + 为每条缺陷配新闸 + 故障注入证明 + STATUS/CHANGELOG/backlog/tracker 四处同步 —— 仪式成本是改动本身的数倍。owner 2026-08-12 拍板给三条豁免:\n295\t\n296\t1. **免 changeset** —— 见上一节「何时不写」(本裁定把 `react-pilot/**` 补进那张清单)。\n297\t2. **视觉批准合批** —— `VISUAL_COMMIT_APPROVED` 一次批准覆盖**同一批**(同 session 内连续、owner 已看过效果的那一组)视觉改动,不必逐文件 / 逐 commit 各问一次。⚠️ **AI 仍然不自设这个变量**:合批只减少「问几次」,不改变「必须由 owner 说出口」。\n298\t3. **免为它新建闸 / 免故障注入证明 / 免四处文档同步** —— 只更新 backlog 对应 entry(真源)+ STATUS 一行;不写复盘文档、不为单条缺陷新建 audit 脚本。\n299\t\n300\t⚠️ **「免机械闸」我按最窄读法执行,owner 可推翻**:读成「免**新建**闸」,**现成的 `audit:docs-overflow` / `audit:layout-tokens` / `vue-tsc` / `pnpm test` 仍然跑**。三条理由:① 前两条恰好是自动发现「内容被裁且够不着」的唯一手段,而 [[INFRA-F112]] 正是从 `docs-overflow` 的判据漏洞逃掉的 —— 关掉它等于把发现同类缺陷的能力一起关掉 ② 成本不在这里:四条合计 ~7min 且无人值守,同一条修复里真正吃时间的是重写判据、故障注入、四处文档 ③ 它们是**已存在**的闸,跑一次的边际成本近零。**重开条件**:owner 明说「连现成的也别跑」,或实测这几条闸的耗时占到一次 docs 修复总时长的 1/3 以上。\n301\t\n302\t### 禁止 AI 做的事\n303\t\n304\t- ❌ 不要自己点合并(PR 必须由人审批后合并)\n305\t- ❌ **non-Owner** 不要试图 push 到 master(会被分支保护拒绝);**Owner 直 commit master 是默认**,见 §\"Owner 直 commit master 权限(broader 2026-05-28)\"\n306\t- ❌ 不要为同一个逻辑改动拆多个分支\n307\t- ❌ 不要在没确认主题完成的情况下擅自切回 master\n308\t\n309\t### Owner 直 commit master 权限(broader 2026-05-28)\n310\t\n311\t**2026-05-28 Owner override 升级**:原 docs-only 例外扩到 **任何改动**(含 code / config / schema / scripts / SoT 等)。Owner Nancy 默认 commit 到 master,**不建 feature 分支**,除非用户在当前 session 明示\"开分支\"。\n312\t\n313\t**触发条件(严格 AND)**:\n314\t1. 当前 session 操作者 = Owner (默认 Nancy;见 §\"仓库身份\")\n315\t2. Owner 未在当前 session 明示\"建分支\" / \"走 PR\" / \"feature branch\" 等措辞\n316\t\n317\t**AI 决策树**(在仓库 cwd 改任何文件时):\n318\t\n319\t```\n320\t当前 session 是 Owner 操作?\n321\t └─ YES → Owner 明示要建分支 / PR?\n322\t └─ YES → 走 §\"Git 工作流(强制)\" feature branch\n323\t └─ NO → 当前在 master:直 commit;当前在 feature:问 Owner \"本次并入当前分支还是切 master 直 commit?\"\n324\t └─ NO → 走常规 feature branch + PR 流程\n325\t```\n326\t\n327\t**Why**:\n328\t- 单人 owner 项目 + AI plan-owner/executor 代理模式下,feature branch 仅是仪式 (no second reviewer except Owner themselves)\n329\t- Owner 已对每个 commit 实质 review (plan owner 审 executor diff + Owner ack)\n330\t- 分支保护可为 Owner 设豁免规则 (Gitea 支持);未设豁免时 Owner 用管理员权限绕过\n331\t- 减少 branch / PR / merge 切换 cycle 摩擦\n332\t\n333\t**反例(仍走 feature branch)**:\n334\t- 非 Owner 用户改任何文件 → 常规流程保留 review trail\n335\t- Owner 明示\"这个开分支跑\" / \"走 PR\" → 按 Owner 指令开分支\n336\t- AI 在 Owner 没明示授权直 commit 时... 实际不存在此 case(Owner override 是 default,AI 不需要明示授权也直 commit)\n337\t\n338\t**实证**:2026-05-28 BRIDGE-MOCKUP-008 Phase C session — Codex 按旧 docs-only 例外建 `chore/bridge-mockup-008-phase-c-merge` 分支,Owner 反问 \"为什么它会弄到分支里面?没道理不知道提交到 master\"。本条款升级。\n339\t\n340\t### Docs-only 改动:见上方 broader Owner override(legacy 2026-05-26,已被涵盖)\n341\t\n342\t**本节原 docs-only 例外(2026-05-26 立)已被上方 §\"Owner 直 commit master 权限(broader 2026-05-28)\" 完全涵盖**——docs-only 只是\"任何改动\"的子集,规则一律以 §276 broader override 为准,本节不再单独维护触发条件 / 决策树(避免两处改一处忘的 drift)。\n343\t\n344\t**实证(保留)**:2026-05-26 TPC bulk import session,Owner 改 mockup-conventions.md M23 stroke 3→4px 时被 AI 建议走 feature 分支,多绕一层;催生原 docs-only 例外,2026-05-28 被 broader override 吸收。\n345\t\n346\t---\n347\t\n348\t## 元规则:真源单一 + 双层导入(不绑工具 / 不绑模型)\n349\t\n350\t> 本元规则适用于**任何 AI 工具**(Claude Code / Codex / Cursor / Cline / Copilot / 其它)、**任何角色**(plan owner / executor / reviewer)。\n351\t> 角色与工具的绑定可变化——当前 Claude Code = plan owner、Codex = executor,但可互换或被替代——**本规则不变**。\n352\t\n353\t详细规则、反模式清单、角色互换条款、Audit/数据产出类 prompt 子规则,统一登记在:\n354\t\n355\t→ **[`docs/meta-rules.md`](./docs/meta-rules.md)**(元规则真源)\n356\t\n357\t任何角色在写 prompt / 设计机制 / 推荐方案前,**必须先过 meta-rules.md 的反模式清单**。命中任一条 → 停下重新设计。\n358\t\n359\t---\n360\t\n361\t## 工作流(约定)\n362\t\n363\t> **角色驱动,工具可换。** 本段使用角色名(`plan owner` / `executor`)而非工具名。\n364\t> **本仓实际默认(2026-07-17 对齐实际)**:solo DS 工作 = **Claude Code 同时任 plan owner + executor(直做 + 自动 subagent/Workflow 并行)**——不走 file-based 往返委派。下面的\"标准闭环 / executor STOP / file-based prompt\"是**委派协议**,仅在 **① 多工具协作(另一 AI 当 executor)或 ② 同事委派 / 大型可并行任务** 时启用。(owner 2026-07-16 确立\"默认自主 + 自动多 Agent 并行\"实践,详见 §标准闭环 头注。)\n365\t> **委派时的默认绑定**:`plan owner = Claude Code`、`executor = Codex`。\n366\t> **切换方式**:用户在对话里说\"把 `<角色>` 换成 ``\",新工具读 `AGENTS.md` + `docs/meta-rules.md` 即可承担该角色。\n367\t> **切换不需要改本文件 / `meta-rules.md` / 任何 prompt 模板**——它们都是角色无关的。如果发现哪条规则绑了具体工具名,应该改成角色名(违反 meta-rules 反模式 #1)。\n368\t\n369\t### 角色定义\n370\t\n371\t| 角色 | 职责 |\n372\t|---|---|\n373\t| **plan owner** | 写 plan / 设计 prompt / 审 executor 的 diff / 复审是否进入下一阶段 |\n374\t| **executor** | 按 plan owner 写的 prompt 严格执行任务 / 跑脚本 / 报告改动与未解决项 |\n375\t| **reviewer** | 用户最终拍板(部分情况下 plan owner 兼任审计) |\n376\t\n377\t> 上表是默认骨架。**具体职责按下面 task-type 矩阵微调**——不是 one-size-fits-all。\n378\t\n379\t### Task-type 分工矩阵(mandatory,prompt §Mode 头段必声明)\n380\t\n381\t> 实证来源:P15.1 / P15.2 / P15.2-extend / P16 discovery 四次实跑。Plan owner 凭记忆喂 baseline 数字 = bug 源(P15 §0 算错 38 → reroute / pickup §3 \"~48\" 歧义被 Codex 抓出);executor 在 apply 阶段额外 verify spec = 冗余 round trip。\n382\t>\n383\t> **每个 prompt 必须在 §Mode 段明示 task type**(如 `Mode: Discovery only` / `Mode: Apply deterministic spec` / `Mode: Design options + STOP`)。executor 按对应行执行,plan owner 按对应行 review。\n384\t\n385\t| 任务类型 | Baseline 数字 | 决策 / 分类 | 设计选项 | 代码改动 | 典型实证 |\n386\t|---|---|---|---|---|---|\n387\t| **Discovery / 调研** | Executor grep 实证 | Executor 按 plan owner 写的机械规则分类 | Executor 列偏差 + STOP | ❌ 不动 | P15.1 / P16 discovery |\n388\t| **Apply / 实施**(spec 已定) | Plan owner 写死 | Plan owner 已拍板 | ❌ 不发挥 | Executor 按 spec 改 | P15.2 / P15.2-extend |\n389\t| **Design / 设计选项**(多解) | Plan owner 给约束 | — | Executor 列 2-3 选项 + 推荐默认 + STOP | ❌ 不动 | P16b verifier topology |\n390\t| **Refactor / API 改造** | Plan owner 实证(写死)| Plan owner 拍板 API 形态 | Plan owner 拍板 | Executor 按 API spec 改 + 跑 vitest | Phase 6.6 dual-form / Phase 6.8 Button canonical |\n391\t| **Infrastructure / 工具**(小 CLI / hook)| — | Plan owner 拍板 spec | Plan owner | **Plan owner 可 direct**(path B)| Tier 2-D/E/F / new-backlog.mjs |\n392\t| **Audit / 数据扫描产出** | Executor grep | Executor 按 plan owner schema 输出 | — | ❌ 不动 | future audit-mockup-conformance discovery |\n393\t\n394\t### 跨 task-type 不变约束(所有类型都必须遵守)\n395\t\n396\t1. **Executor 永不 commit / push** — prompt 不得含 commit/push 指令,executor verify 后只报 diff + stdout,由 plan owner + 用户 ack 后才 commit\n397\t2. **Plan owner 必独立 verify executor 报告**——按 task type 差异化(见下):\n398\t - Discovery 类:sample 1-2 cluster 重 grep 验分类;不能只 verify 数字加总\n399\t - Apply 类:diff 全审 + git status / git diff --stat 独立 check\n400\t - Design 类:每个 option 独立查可行性,不 rubber-stamp executor 推荐\n401\t3. **Plan owner 不直接动 source code / tokens / JSON 数据 / component**——例外仅 Infrastructure 类小工具 + 协作文档 + prompt 文件 + 审计报告 + 复盘文档\n402\t4. **决定哪类 task type** 由 plan owner 在 prompt §Mode 段明示;executor 起手第一步是 confirm task type,与 prompt §Mode 不符必 STOP 反馈\n403\t\n404\t### 标准闭环(委派协议 — plan owner ≠ executor 时按顺序)\n405\t\n406\t> **适用范围**:下面 7 步是 **plan owner 与 executor 分属不同工具/人** 时的委派协议。**本仓 solo DS 工作(Claude 直做)默认不走此环**——坍缩为:`Claude 实现(+subagent/Workflow 并行)→ 自 verify 拿真实 gate stdout → owner ack → commit`(不可逆操作前的 owner ack 与自 verify 是保留的核心闸,见跨 task-type 不变约束 #1/#2)。\n407\t\n408\t1. plan owner 读项目规则 + audit\n409\t2. plan owner 生成 `docs/internal/_prompts/.prompt.md`\n410\t3. 用户把 prompt 交给 executor\n411\t4. executor 按 prompt 改代码 / 产出文件\n412\t5. executor STOP,列出改动和未验证项\n413\t6. plan owner 复审 executor diff\n414\t7. 用户决定是否进入下一阶段\n415\t\n416\t### 单一决策源模式(当前默认)\n417\t\n418\t为避免 plan owner 与 executor 在对话中互相\"补充框架\"、反复扩展路线,后续协作默认采用以下边界:\n419\t\n420\t- **plan owner 负责产出一版路线图 / prompt**,并把结构性决策固化到仓库文档\n421\t- **executor 不做\"加料式评论\"**:不在 plan owner 路线图基础上继续发明新轨道、新阶段或新框架\n422\t- **executor 只做三件事**:\n423\t 1. 检查 prompt 是否有明显 blocker(会误删 / 误 commit / 改 Figma / 范围不可验证 / 与仓库规则冲突)\n424\t 2. 执行 prompt 指定任务\n425\t 3. 报告改动、验证结果、未解决项\n426\t- 如果 executor 不同意 prompt,只指出**会导致失败的 blocker**,不扩展替代路线\n427\t- 一旦 `docs/internal/long-term-plan-v2-*.md` 或同等路线图落仓库并经用户确认,本阶段以该文档为准;不要在对话里反复发明新框架\n428\t\n429\t### executor 角色行为约束\n430\t\n431\t- 用户通过 file-based prompt 触发任务:`请按 docs/internal/_prompts/.prompt.md 执行`\n432\t- **起手第一步:confirm prompt §Mode 段声明的 task type**,按 task-type 矩阵对应行执行;prompt 缺 §Mode 段 → STOP 反馈让 plan owner 补\n433\t- 每个 prompt 末尾会有 \"完成后 STOP,等用户审\"——**严格遵守 STOP**,不要自行进入下一步\n434\t- 关键参数(如 token 值、变体枚举)**先列出来给用户确认**,不要自行决定\n435\t- 在单一决策源模式下,执行前只做 blocker 检查;无 blocker 就执行,不再提出额外路线规划\n436\t- **不\"加料式评论\"、不发明新轨道 / 阶段 / 框架**——只做三件事:① 检查 prompt 有无明显 blocker ② 执行 prompt 任务 ③ 报告改动、验证结果、未解决项\n437\t- **永不自行 commit / push**(见跨 task-type 不变约束 #1)\n438\t\n439\t### plan owner 角色行为约束\n440\t\n441\t- 直接读项目文件审 executor 产出\n442\t- 设计 prompt 前**强制过 `docs/meta-rules.md` 反模式清单**——命中任一条 → 重新设计,不 fire\n443\t- **每个 prompt §Mode 段必明示 task type**(Discovery / Apply / Design / Refactor / Infrastructure / Audit)——见 task-type 矩阵\n444\t- **Discovery / Audit 类 prompt 不写死 baseline 数字**——让 executor grep 实证;plan owner 凭记忆喂数字 = bug 源(P15 §0 算错 38 实证)\n445\t- **Apply 类 prompt 必写死 spec**(token 名 / CSS 行 / API 形态)——不让 executor 重复 verify\n446\t- 任何重大决策(破坏性 API 改造、跨阶段路径选择)必须 propose 给用户拍板\n447\t- 默认**不直接修改代码 / 脚本 / tokens / JSON 数据 / 组件文件**——涉及这些改动时,应先生成 executor prompt,除非用户明确授权(Infrastructure 类小工具 path B 例外)\n448\t- 可以直接修改协作规则文档、prompt 文件、审计报告和复盘文档;完成后必须 STOP,等用户确认\n449\t- **审 executor 产出必独立 verify**——Discovery 类 sample 1-2 重 grep 验分类(不只 verify 数字加总);Apply 类全 diff 审 + git status 实证;Design 类每 option 独立查可行性\n450\t\n451\t### 共同规则\n452\t\n453\t- 决策必须固化到文档(不能只在对话里口头提)\n454\t- 阶段完成后追加复盘到 `docs/internal/retrospection/{date}.md`"}]},"parent_tool_use_id":null,"session_id":"ccca31c3-4a85-4094-9f46-4533df53f8ce","uuid":"8df42bab-c844-4c05-8b25-be22af05bec8","timestamp":"2026-08-25T09:21:22.953Z","tool_use_result":{"type":"text","file":{"filePath":"/Users/nancy/.ai-ds-lab/pins/tvu-ds-4a68e02d/AGENTS.md","content":"# AI Agents 必读(跨 AI 工具通用)\n\n> 本文件适用于:Codex / Claude Code / Cursor / Cline / GitHub Copilot / 任何在本仓库工作的 AI 工具。\n\n---\n\n## 仓库身份(Owner / 默认作者)\n\n- **Owner**:Nancy ``\n- **默认 UX 交付说明作者**:Nancy(任何 M23 规则卡 / annotation footer 的 \"Author / 作者\" 字段默认填 Nancy,不要写通用 \"UX\" 角色名)\n- **AI 工作时的身份约定**:AI 是 Nancy 的 plan-owner / executor 代理,**不是独立角色**。所有 AI 写出的 commit / PR / annotation 都视为 Nancy 的署名工作\n\n任何 AI 在生成 attribution(commit author / annotation author / handoff doc 作者行 / Jira reporter 等)时**默认填 Nancy**,除非用户在当前 session 明确指定其他人。\n\n---\n\n## ⛔ Mockup Write Gate(TVU 产品 Figma 写操作 mandatory)— 2026-05-27 新增\n\n任何 AI 工具(不限 Claude Code)在对 **TVU 产品 Figma 文件** 做写操作前——包括但不限于:加 mockup / 改 mockup / 加 UX 交付说明 / 加 jira 组件 / 加注释 / 加 page / 加 tooltip / 调样式——**必须**先完成 4 步:\n\n1. **Read [`docs/internal/mockup-conventions.md`](./docs/internal/mockup-conventions.md) — 按文件顶 §🤖 AI 读取指引 scoped 读**(起手必读段 + 触发 jump,禁全量吞;**读哪几条由该文件顶部的 §🤖 AI 读取指引 jump 表按你的任务派**,⛔ 这里不再抄一份「重点规则」清单 —— 抄一份就是一处会漂的副本,2026-08-14 扩 `audit:rule-inventory` 分母时实测这里抄的那份里,有一个 id **活源根本不存在**)\n2. **Read [`docs/internal/design-process.md`](./docs/internal/design-process.md) § Pre-Phase 0(含 § No Open Questions in Deliverables)+ § Stage 0.5 + § Scope Handling + § Delivery Cleanup Gate**(Stage 0.5 含字段长度分布声明,M43 UX-side 镜像;§No Open Questions = 触发器 P 落地:起手扫齐 open questions + 交付物零未决项,禁止贴 Figma)\n3. **Read [`docs/internal/figma-component-catalog.md`](./docs/internal/figma-component-catalog.md) 标题列表**(lazy reference,具体 entry 按需 grep)\n4. **从 [`docs/site-review-manifest.json`](./docs/site-review-manifest.json) 拿 library fileKey**(不要靠扫产品文件 instance 反推)\n\n**⛔ 写操作全程走 §M-LIFECYCLE 三时点闸**([`mockup-conventions.md` §M-LIFECYCLE](./docs/internal/mockup-conventions.md))——任何 create / update / delete:\n- **操作前**:create/move 先 probe 目标区防叠加(§I6) · update 先 live 重读做最小 delta(§I5) · delete 先确认目标 + 处理指向它的 connector(§I5/§M23.6)\n- **操作后(每批次,不拖到末尾)**:跑 `pnpm audit:mockup-conformance --file --node <一个 nodeId>`(规则清单 + 条数真源 = **跑一次 `pnpm audit:mockup-conformance --list-rules`**,⛔ 别在这写死条数、也别指某个会搬家的代码位置 —— 2026-08-24 合并后它已从 `AUDITS` 数组挪进 `scripts/mockup-rules/index.mjs`)+ `use_figma` connector centerline probe;违例当场修\n- **走查时**:design-walkthrough 三轴全跑、机械维度贴机检 pass/fail、机检覆盖面 = 全 session 触碰节点 —— ⚠️ **`--node` 只吃一个 id**,覆盖多节点 = 逐节点跑或整文件跑(**用法真源 = [`scripts/audit-mockup-conformance.mjs`](./scripts/audit-mockup-conformance.mjs) 头注释**,本文件不复述)\n\n**触发判定(命中任一即触发)**:\n- 用户给了 Figma URL + 任一动词:\"加 / 改 / 调 / 更新 / 同步 / 推 / 画 / 设计\"\n- 用户说\"加 UX 交付说明 / UX notes / 加 jira 组件 / 走查 / 角色测试 / persona / journey map\"\n- 用户说\"基于昨天的页面修改\" / \"在上一期 mockup 上加 X\" / \"clone 这个 page 改 Y\" → 额外触发 M46 (Library Instance Iteration Discipline)\n- fileKey 命中 TVU 产品文件(典型如 TPC-20220519 `xu7H3ppLyQfa3fOmU8M7iO` / Micro-Apps-20250923 等;非 library 文件均按 TVU 产品文件处理)\n\n**严禁**:\n- 用 claude.ai 通用 `figma-use` / `figma-generate-design` skill 替代 TVU 专属硬规则(M23 等会被整段跳过)\n- 用 memory cache 替代 mockup-conventions.md 真源(memory 是工具私有缓存,规则演化 memory 会过期)\n- \"起手只读 STATUS.md,mockup 规则现场拍\" → mockup 写操作硬规则前置,不允许现场拍\n- 起手用 createFrame 自画 overlay 覆盖既有库 instance → 违 M46 (Library Instance Iteration Discipline);正路是先 probe instance 可改性\n- M23 UX 交付卡里塞 regex / pseudocode / 长代码块 → 违 M23.10 (Audience-Aware Language)\n- 把 Persona / out-of-scope 声明 / 未来 roadmap 这类 tangential 内容塞进 UX 卡 → 违 M23.11 (Scope Discipline)\n- \"本期不动 R list\" 误读成 \"hide R list\" → 违 design-process.md § Scope Handling\n- Session 收尾前不走 cleanup → 留下被 supersede 的临时 spec / overlay / code 卡 → 违 design-process.md § Delivery Cleanup Gate\n- 调列宽 / 改 cell 内容后只截整表缩略图自检 → 违 M43.2 (Column Width Self-Audit),必须 zoom-in 每列\n\n**违反信号 → 上一段输出不合格,重做**:\n- UX 交付说明卡用了 cream / 浅底 / 单语 / 非 navy `#2B2D42` → M23 违例\n- 表格新增字段没在 mockup 里给 3 状态(正常 / 截断 / hover tooltip) → M43 违例\n- 自画 RECTANGLE+TEXT 拼 tooltip / button / 注释卡 → M32 Library-First 违例\n- 装饰元素 / NEW badge 浮在 page 层不在 mockup frame 内 → M-INTEGRITY §I4 违例\n- 改了 text 节点 fontName 但没保留 textStyleId → M47 违例(cell 渲染会变灰 / 错位)\n\n**实证**:\n- 2026-05-27 FB-9398(TPC-Service 消费端):AI 起手只加载 claude.ai 通用 `figma-use` skill,跳过 mockup-conventions.md → UX 交付说明卡用 cream 浅底自由设计 + 单语 → 用户连续两次抓\"没用 TVU 设计系统已有规则\"\n- 2026-05-28 TPC-628(TPC-Service 消费端):AI 起手 clone FB-9398 后误判 instance 不可改 → 跳到自画 overlay;又把 NEW badge 放 page 层;font fallback 时丢 textStyleId 让 cell 变灰;列宽 rebudget 砍了 Operation 列但没 zoom-in 验证 Edit/Delete/Status 三按钮溢出;收尾时留下 spec 帧 / Display Logic 代码卡 / Persona 卡等冗余 → 用户连续抓 7 次。本次回流加 M46 / M47 / M-INTEGRITY §I4 / M23.10 / M23.11 / M43.2 / Scope Handling / Delivery Cleanup Gate 等规则。\n\n---\n\n## ⛔ Onboarding Gate(第一个项目相关回答前 mandatory)\n\n**任何 AI 在第一个项目相关任务 / 推荐 / 回答前,必须先完成 [`docs/STATUS.md` §起手必读链路](./docs/STATUS.md#起手必读链路) 的两层 onboarding**(该节是链路唯一 SoT,本文件不重复维护清单 — 2026-06-10 P1-07/P1-08 重构):\n\n- **L-core 全文必读(4 份,禁 grep / 跳读)**:FIGMA_AS_SOURCE_OF_TRUTH → STATUS → PROJECT_GOAL → 当前 pickup。⚠️ **体量 / 耗时预算的唯一真源 = STATUS §起手必读链路**,本文件刻意不复述那个数字 —— 那四份自己每工作日都在涨,复述一份就是又一处会漂的副本(原 INFRA-F95 已付代价 4:两处都写「~40KB」而实测 2.2× —— **该 entry 2026-08-13 已闭合删档**,这条实证的留痕在 `STATUS-CHANGELOG` 与 `audit-doc-shape.mjs` 头注释)\n- **L-ref 最小集必读 + 命中触发深读**:本文件 §硬规则表 + §Onboarding Gate 是每 session 最小集;tracker §排期原则 / backlog 当前 entry 全文 / meta-rules / working-principles / translation/ 按触发表升级 —— 触发表见 STATUS §L-ref\n- **Mockup 任务**:§Mockup Write Gate 4 步前置 + §必读链路 7-11 整链升 mandatory(不受分层影响,仍是硬规则)\n- **唯一减档 = 微改档**(单文件 · 纯文案 · 不换组件不改 token):判据 / 必读集 / 自动升级条件的**唯一 SoT = [`STATUS.md` §微改档](./docs/STATUS.md#微改档单文件纯文案的减档)**,本文件刻意不复述(owner 2026-08-13 裁定新增;复述一份就是第二处会漂的副本 — [[INFRA-F121]] 已付过这个代价)。⚠️ 上一条 L-core「4 份」在微改档下减为 **#0 + 本文件 §硬规则表**;mockup 写操作**不适用**本减档\n\n**机械执行**:用 TodoWrite / TaskList / 等价机制为 L-core 每项 + 命中的 L-ref 项各建 1 个 todo,逐个 Read 完才能开始回答。**基于 partial L-core 给推荐 = 协议违反**。\n\n**违反信号(分层版)+ 历史实证**:见 [`STATUS.md` §起手必读链路](./docs/STATUS.md#起手必读链路)(该节是链路唯一 SoT,含完整违反信号分层 + 2026-05-13/2026-06-10 P1-08 实证)——本节不再内联镜像,避免两处各改一处忘的 drift(DUP-01;此前 AGENTS 版已漏掉 STATUS 版的 P1-08 教训)。\n\n---\n\n## AI 响应格式规则(决策点 / 推荐型回答 mandatory)\n\nAI 在面对决策点 / 给用户多选项 / 推荐方案时,响应**必须包含 4 块**(缺一不合格):\n\n1. **总计划 / 总数字**:当前剩余多少问题 / 总任务清单(含已完成 + 待办)\n2. **本次范围**:本轮做了什么 / 影响多少数字\n3. **明确推荐**:选哪个,不要\"A 或 B 都可以\"模糊话;候选 ≥ 2 个时必须排序 + 标默认\n4. **推荐理由**:3 条以内核心理由\n\n**违反信号**(命中任一 → 上一条响应不合格,重写):\n- 用户问\"推荐哪个\" / \"还剩多少\" / \"总计划呢\" → 重写\n- 用户说\"我自己决定\" / \"你决定\" → 默认仍要给推荐;\"我没意见\"不算合规\n- 列了多选项但没排序 / 没标默认 → 重写\n\n**历史实证**:2026-05-20 session 用户多次因为这 4 块缺失追问 / 重发问题(典型:\"你没告诉我剩下还有多少问题?你推荐解决哪个?为什么\")。\n\n**规则分层(DUP-05 — 出推荐时三条协同、非重复)**:本节 = **输出契约**(响应长什么样)。配套两条在 [`meta-rules.md`](./docs/meta-rules.md):**触发器 F**(出推荐**前**的推荐自审 4 问:理由经得起反驳吗 / 有没有把最省事项包装成 #1 / 有没有更稳健选项被压脚注 / 该我拍还是 owner 拍);**触发器 E**(决策疲劳态下\"只给一个推荐拍 Yes/No\"的 mode override——与本节\"候选 ≥2 排序标默认\"不冲突:E 管疲劳态、本节管常态多选)。三者 = 自审→输出→疲劳降级 的分层,不是三份重复规则。\n\n---\n\n## 项目一句话\n\n把 **Figma 已发布 Library**(组件 / Token / 图标 / Styles)做成 **AI 与开发可消费的双向 Figma↔Code 桥**。\n\n> **5 个能力的完整定义 + 各能力前置约束(T3/T4 schema 设计要点)+ 能力 3 的边界分层,真源 =\n> [`docs/PROJECT_GOAL.md`](./docs/PROJECT_GOAL.md) §一句话目标**。能力**成熟度 / 当前状态** →\n> [`docs/STATUS.md`](./docs/STATUS.md) §能力 × 成熟度表。\n>\n> 2026-08-03 本节从全量镜像收成一句 + 指针([[INFRA-F58]] D1)。原先这里复述了 5 条能力**并夹带\n> 会变的数字与 key**(`render-verification-manifest 936 条` / `YbsPRUVmNdsbN40NNwh1Gn` / \"待 Pro plan\"),\n> 那是三份现状真源的第四份副本 —— manifest 条数与 plan 状态都在别处随时会动。\n\n---\n\n## 必读链路\n\n> **Onboarding 链路唯一 SoT = [`docs/STATUS.md` §起手必读链路](./docs/STATUS.md#起手必读链路)**(L-core 全读 + L-ref 按触发深读)。本节不再维护并行清单(2026-06-10 P1-07 双链路 drift 治理),只登记 **L-ref 的任务触发表** —— 命中触发即把对应真源升为该任务的 mandatory 深读:\n\n| 触发(做什么) | 深读真源 |\n|---|---|\n| 排期 / 版本决策(\"v0.X 含哪些 / 先做哪个 / 该不该上 Tier N\") | [`tracker`](./docs/internal/retrospection/design-spec-canonical-alignment-tracker.md) 全读(最小集 = §排期原则) |\n| 写 prompt / 设计机制 / 给推荐方案 | [`docs/meta-rules.md`](./docs/meta-rules.md) 反模式清单 |\n| **写 UI 代码**(Vue / React / HTML — 含本仓库 `playground/docs/*`、`src/components/*`、下游产品 demo 与 PoC) | [`docs/internal/code-conventions.md`](./docs/internal/code-conventions.md) 顶部 **§🤖 AI 读取指引 的「起手必读段」**(含 §R0 Phase 0 元素→组件映射 + §R7 四场景判断 + Task Entry Modes;具体 R-rule 按该表触发条件 jump)。⛔ 按 scoped 读,**禁全量吞**(该文件近 90 KB);⛔ 跳过起手必读段直接进单条 R-rule = 协议违反(该文件自记「漏 R0 Phase 0 是历史最高频回归源」) |\n| 实现决策:命名 / token / API 形态 / 图标 alias | [`docs/working-principles.md`](./docs/working-principles.md) 9 条原则(0-8)对应条 + [`src/design-system/translation/`](./src/design-system/translation/) 4 文件(`prop-aliases` / `divergences` / `icon-aliases.ts` / `token-aliases.ts`) |\n| 数据来源 / 生成链 / 清理规则 | [`docs/PROJECT_MAP.md`](./docs/PROJECT_MAP.md) |\n| 历史决策回溯 / \"怎么走到这里的\" | [`docs/internal/retrospection/`](./docs/internal/retrospection/)(最新日期) |\n| 接手 sprint task / 立新 entry | [`docs/internal/backlog.md`](./docs/internal/backlog.md)(当前 entry 全文;新 ID 先 grep 全部已用) |\n\n### Mockup 任务额外必读\n\n> 任何 AI 工具收到\"在 TVU 产品 Figma 文件画 UX mockup / 改 mockup / 抽组件入库\"类任务时,**除 L-core + 上表命中项外,下列 7-11 整链升 mandatory —— 各文件按其顶部 §🤖 AI 读取指引 scoped 读**(§Mockup Write Gate 的 4 步前置照旧):\n>\n> ⚠️ **第 11 项不是「读一份文件」而是「跑一条命令」**(2026-08-14 加入)—— 因此上面那句「按 §🤖 AI 读取指引 scoped 读」对它不适用,它的执行方式与输出怎么读,见该项自己那段。\n>\n> ⚠️ **\"mandatory\" 修饰的是「这条链一份都不能跳」,不是「逐字全量吞」**([[INFRA-F121]] ② 2026-08-13 统一)。此前本行写「整链升 mandatory **全读**」,与上方 §Mockup Write Gate 第 1 步逐字要求的「按文件顶 §🤖 AI 读取指引 scoped 读(…禁全量吞)」互斥,而两条指的是同一份 `mockup-conventions.md`、又都标 mandatory —— 实测两种读法差 **2.5 倍字节**。⇒ 以 scoped 读为准;某文件没有 §🤖 AI 读取指引块的,才全读。\n>\n> (**此 7-11 链 SoT = 本节**,是 mockup 任务的 scoped 强化清单,有意内联——**不属于 §必读链路开头所指的\"并行清单 drift\"**,无需归并到 STATUS。)\n\n7. **[`docs/internal/design-process.md`](./docs/internal/design-process.md)** — 通用 process 规则(**完整清单见该文件头 `rule-inventory` 块 = 唯一真源**,此处不再枚举)\n8. **[`docs/internal/domain-tvu.md`](./docs/internal/domain-tvu.md)** — TVU 业务规则(**完整清单见该文件头 `rule-inventory` 块**)\n9. **[`docs/internal/mockup-conventions.md`](./docs/internal/mockup-conventions.md)** — Path A 专属(Figma 真源 / 组件取数优先级 / 库归属验证 / M0 / M1 / M10)\n + **[`docs/internal/figma-technical-reference.md`](./docs/internal/figma-technical-reference.md)**(Figma API quirks,实现时查)\n10. **[`docs/internal/figma-component-catalog.md`](./docs/internal/figma-component-catalog.md)** — TVU 已发布库组件目录快速查(mockup 任务起手第一查,避免凭印象造组件)\n11. **跑一次 `pnpm pattern:lookup <本次的 figma URL>`** — 查**本产品自己**已经做过哪些模块(owner 2026-08-14 拍定,走[提案](./docs/superpowers/specs/2026-08-13-product-pattern-index-proposal.md) §7 的 Q2 候选 (a))\n\n> **第 10 与第 11 是两个不同的问题,⛔ 别合并**:第 10 问「**DS 库**有没有这个原子」(Button / Input / Table,跨产品);\n> 第 11 问「**这个产品自己**有没有做过这个模块」(设备状态卡 / 告警行 / 参数面板,产品专有、DS 不该收)。\n> owner 的痛点逐字是「用了设计库组件、**没用当前产品已有的组件**」—— 那是第 11 条治的,第 10 条结构上看不见。\n>\n> **⛔⛔ 这一条最容易被用错的方式:把「查不到」读成「没有」。** 工具输出四态,**只有 `✅ covered` 那一态**\n> 能得出「本产品已有 X」;`⬜`(还没采过)的正确结论是「**我查不到**」,⛔ **不是**「没有先例可复用」。\n>\n> **⇒ 命中 ⬜ 的正确动作是「当场采一次再查」,不是「跳过这一步继续画」**:\n> `cd <主工作树> && node scripts/ds-health-scan-mockups.mjs --only `(一步,⛔ 不需要预先登记、\n> 不需要审批;worktree 没有 `.env` ⇒ 必须从主工作树 cwd 跑)。采完重跑第 11 项即可。\n> **⛔ 这里没有、也不该有「先申请纳入采集面」这类白名单** —— 原来的 `patternIndex: true` opt-in\n> 已于 2026-08-14 拆除(owner 逐字:「为什么要把消费级产品一个个拉进来?我要做的是规则,不是实测」)。\n> 任何产品文件都能就地采;已登记为 DIM-U12 测量目标的,全量跑 `pnpm health:mockups` 时顺带就刷新了。\n> ⚠️ 唯一的例外是**采集实在跑不了时**(无 Figma 凭据 / 网络不通):那时才「照常按本链其余步骤走」,\n> 并在交付里如实写明「本产品 pattern 索引未采到」,⛔ 别写成「无先例可复用」。\n>\n> **为什么这一条是「跑命令」不是「读文档」**:提案 §7 逐字写着,能否定掉整个索引的唯一理由是\n> 「没有任何机制保证有人在画之前查它」。只写一句必读,等于把成败押在每个人每次都记得上 ——\n> 那正是本仓「规则别继续往 L1 prose 加」要治的病。**判据/数据真源与五态语义在\n> [`scripts/pattern-index-lookup.mjs`](./scripts/pattern-index-lookup.mjs) 头注释,⛔ 别在本文件维护第二份。**\n> ⚠️ 它是**查询不是闸**(always exit 0,不拦任何东西)—— 本条的 Enforcement 层级是 **L1**:\n> **没有任何机制能发现「有人跳过了这一步」**。这是如实登记的事实,⛔ 不是待补的 TODO。\n> **「为什么停在 L1 + 什么条件下才该升」的唯一真源** = [`scripts/pattern-index-lookup.mjs`](./scripts/pattern-index-lookup.mjs)\n> 头注释里那个 📌 段(owner 2026-08-14 拍定)。⛔ **别顺手给它加个闸** —— 先读完那三条为什么;\n> 尤其别走「新建组件与已有 pattern 相似度」那条,它是启发式,直接撞 `FIGMA_AS_SOURCE_OF_TRUTH.md` §验证方法。\n\n---\n\n## 硬规则(不可违背)\n\n| # | 规则 | Enforcement 层级 | 违反后果 |\n|---|---|---|---|\n| 1 | **不修改 Figma**——Figma 是设计师真源 | L4-partial:pre-commit 拦 figma-data/ sync-output 镜像写入;**Figma 端写操作本身无机制可拦(L1)** | 任何 Figma 写操作都是 bug |\n| 2 | **不让 AI 按\"行业惯例\"自由发挥** | L1(AI 自律;登记缺失由 #5 的间接链兜底) | 必须读 translation/ 已登记决策;新决策必须先得到用户确认 |\n| 3 | **不创建未登记的 prop / variant / 状态** | L2 间接:无 commit 时拦截,render-verification + published-vs-code 事后抓 drift | 例:Notification 的 `success` 曾是 code 自创 drift;2026-06-12 owner 在 Figma 正式补 `dialog`×`success` 并随发布登记 → 由 drift 转为合法(先 Figma 后 code,符 §\"Figma 库 master 变更→code 原子同步契约\") |\n| 4 | **颜色硬编码 = bug** | L5:`audit:no-hardcoded-design-tokens`(prepublishOnly + master-push CI) | 必须用 token;token 缺失就新建,不能写 hex |\n| 5 | **任何 Figma↔Code 不一致必须先在 translation/ 登记** | L2 间接:`audit:translation-completeness`(L5)只验**已登记**条目;未登记漂移靠 render-drift-gate 事后抓 | 不登记的不一致 = 漂移 |\n| 6 | **AI 工具从 Figma URL 生成代码必须用 `src/canonical/*` 作为 SoT,不用 `src/components/*`** | L1(DS 仓内);consumer 侧 L4-partial(eslint `no-base-component-import`) | `src/components/*` 是实现/base 层,`src/canonical/*` 是 Figma-aligned 桥层(npm 经 `src/index.ts` 导出 canonical)。落 base/legacy → 输出 API 错位。详见 [`src/design-system/translation/divergences.md`](./src/design-system/translation/divergences.md) \"Code 端双源\" 段 |\n| 7 | **代码改动必须走 feature 分支 + PR (non-Owner 约束);Owner 任何改动均可直 commit master**(2026-05-28 broader Owner override 落地,原 docs-only 例外被升级)| L3 平台:Gitea 分支保护(non-Owner)+ Owner override 政策条款 | 见下方「Git 工作流(强制)」段。Owner 例外见 §\"Owner 直 commit master 权限(broader 2026-05-28)\" |\n| 8 | **组件 demo 必演示 Slot + Boolean 属性(Vue playground + React pilot 双框架)**(owner 2026-07-03 拍板)| **L4**:pre-commit 条件 gate + blocking `audit:demo-slot-boolean`(INFRA-F45 shipped 2026-07-06;`scripts/audit-demo-slot-boolean-coverage.mjs` 从 `components.config.ts` 派生 in-scope=28,静态断言双侧 slot 投影 + boolean live 绑定;staged 命中 demo surface/config/audit 时触发)| 凡有 default/named slot 或 boolean prop 的组件,其 docs demo 必须在 **Vue 与 React 两侧**各演示(a)slot 投影真实内容、(b)至少一个 boolean prop 的 live 切换。理由:slot 投影与 boolean 属性是双框架 CE 最易 silent 破的两条链(实证 INFRA-F43 light-DOM slot 不投影恒空 body 数版本未被发现)。首个 exemplar = PopupBox;全量回填后每个 in-scope 组件双侧达标,audit gate 防回归。|\n| 9 | **AI 不得编造 / 虚构工具输出**——随机标识符(commit hash / SHA / 时间戳 / exit code / 测试 passed 数)只能从工具原始输出逐字复制,不准生成 | L1(无机制可拦 AI 幻觉,唯靠纪律 + 用户终端核对) | ① commit hash / SHA / 时间戳 / exit code / passed 数 = 从原始 stdout 逐字复制,绝不自己生成;② 不可逆 / 外部可见操作(commit / push / publish / 删除)的结果以**原始工具输出**或用户终端核对为准,**不得用\"已成功 / 已一致 / 已通过\"概括代替原文**;③ 工具输出超时 / 被省略 / 截断 / 前后矛盾 / 可疑时 → **STOP 交用户在终端核**,不自行接管编造。**归因要准**:病根是 AI 编造,**不是**\"工具不返回\"——多数情况工具正常返回真实数据(2026-07-15 本 session 实证工具输出全真实可核)。真源 memory `no-fabrication-on-uncertain-tool-output` + `local-env-tool-quirks`。实证:上个 session(D2 Task 9 首次尝试)AI 伪造过不存在的 commit hash / push 成功 / 测试通过 / SHA 一致,逼用户起新 session 从真实基线重做 |\n| 10 | **结论必须对\"活源\"验证,不凭摘要 / 镜像 / 记忆下判断**——判断仓库或远端的**当前状态**(某文件是否存在 / 内容为何 / prop-token 名 / 组件是否已同步 / 远端卡片长什么样)前,**必须直接读活源**:本地 `Read` / `grep` 实际文件;远端 DesignSync `get_file` 实际内容。**不得**拿派生镜像 / 摘要 / 记忆缓存 / 面板 UI 当依据下结论。 | L1(无机制可拦,唯靠纪律;由 #9 事后核对间接兜底) ⚠️ 2026-08-20 新增一个此前未登记的形态:**计划文件里的具体值(prop / 导出名)未对活源核** —— 已上机械闸 `pnpm audit:claim-vs-livesource`(pre-commit 条件触发 + pr-checks;INFRA-F133)。⚠️ **该闸对这个形态是 report-only(每次跑、每次印、不阻断)**:落地当天校准实测假阳性率 **86.7%(13/15,35 份指令型文档)**,按 spec §9 退档条件退档;阻断档只保留三条 fail-closed 基础设施判据(活源分母 / 扫描面 / 豁免表 shrink-only)。⚠️ **闸只覆盖这个形态的 prop 名那一半**:barrel 导出名虽然解析了,但只喂活源分母与覆盖面自印,**没有任何判据比对导出名断言**(词法上「导出名断言」与闸选宿主用的形态重合,全比一遍必然是噪声 —— 理由见闸脚本头注释,缺口登记在 backlog `INFRA-F133`)。⛔ 判据、档位与结构化区域定义的真源是[闸脚本头注释](./scripts/audit-claim-vs-livesource.mjs),**别在本表维护第二份**。⇒ 仍靠纪律的是:**结构化区域里的断言(S2 只印不红)**、散文里的断言(S5 只印不红)、**导出名断言(不在覆盖面)**、对话里的口头结论、以及**文档断言 × 另一份文档的当前版本**(本闸只核代码活源)。 | 二手源会 drift,信了就\"读错\":① 导出 bundle 的 `01–14` ≠ repo 真源——**改规则去 `docs/` / `docs/internal/`,别去 bundle 找**([`PROJECT_MAP.md` §9](./docs/PROJECT_MAP.md));② 现有远端卡的 prop ≠ canonical——**照抄现有卡 = 复制 drift**,prop 名一律以 `src/canonical/*.vue` 为准;③ DesignSync 面板 `updatedAt` / 卡片对**非视觉写入不刷新**——别拿 UI 当同步凭据,写完逐文件 `get_file` 亲验(memory `designsync-nonvisual-writes-no-ui-bump`);④ memory / handoff / 摘要文档是工具私有缓存或时点快照,规则演化后会过期,**只作导航,不作真源**(形态 ①④ 2026-08-20 已评估:无可靠词法解 —— 实测 71 处引用中 48 处报红且多数假阳性,\"当依据\"与\"当对象\"是语义区分 ⇒ 维持 L1,不上闸)。**病根 = \"AI 读错\":信了会漂移的二手源。** 实证:Sync A 6 卡审计中 5 卡有 prop drift(Badge/Button 的 `tag`/`variant` → 应 `fill`、UserMenu `items[]` → 应 `actions[]` 等),正是历史上照抄现有卡、未回 `canonical` 活源验证的结果。
⚠️ **2026-08-11 补一个被漏掉的形态(PR #9 实证):多分支协作下,你自己的本地工作树也是一种会过期的镜像。** 那次撞号的一方读的是**本地实际文件**(不是摘要、不是 memory、不是面板 UI —— 完全符合本条),只是那份文件已经 62 天没同步,于是把 master 上早已占用的规则编号又用了一遍。⇒ 判断**全局命名空间的当前状态**(规则编号 / backlog entry ID / token 名 / 已用过的 key)时,活源是 **`origin/master`**(先 `git fetch`),不是本地文件。已上机械闸:`pnpm audit:rule-number-collision`(pre-commit 条件触发 + `pr-checks.yml` 带 `--require-remote`)+ 分配器 `pnpm rule:next <系列>` / `pnpm new-backlog <前缀>`。⚠️ **2026-08-20 订正**:此处原写「该闸只覆盖三份规则真源的编号,**看不到 backlog entry ID**,那一条仍靠本纪律」—— 原 [[INFRA-F109]] 已落地,`docs/internal/backlog.md` 的 **entry ID 现已在覆盖面内**(含 `####` 层级、无 `F` 中缀、带连字符前缀、umbrella 范围标题四种形态;⛔ 覆盖面与仍看不到的三样,真源是[闸脚本头注释](./scripts/audit-rule-number-collision.mjs),**别在本表维护第二份**)。⇒ 本条仍需靠纪律的只剩「**已删档号被重新占用**」(完成即删档 ⇒ 被删 ID 在 master 文本里已不存在,闸看不见)—— 取号一律走 `pnpm new-backlog`,它扫三份 SoT 全文、含历史提及 |\n\n> **Enforcement 层级图例**(对齐 [`meta-rules.md`](./docs/meta-rules.md) 触发器 K 的 L1→L5 谱系;列加于 2026-06-10 system-review P2-04):**L1** = 文本规则靠 AI/人自律 · **L2** = 无直接拦截但有事后 audit 可抓 · **L3** = 平台/流程机制 · **L4** = 本地 pre-commit hook(可 `--no-verify` 绕过)· **L5** = prepublishOnly / CI strict gate。**各条规则强度本不相同**——没有这列时\"同等强\"是错觉;声称\"有 gate 兜底\"前先对照此列。\n\n---\n\n## Git 工作流(强制)\n\n`master` 受分支保护,**non-Owner 的任何代码改动必须走 PR**。AI 在本仓库工作时遵循以下决策树:\n\n> **⚠️ Owner 例外**:默认操作者 Owner(Nancy)**可直 commit master、不建分支**——见下方 §\"Owner 直 commit master 权限(broader 2026-05-28)\"(硬规则 #7 已编码)。本节决策树主要约束 non-Owner,及 Owner 在当前 session 明示\"走 PR / 建分支\"的情形。\n\n### 分支决策(non-Owner 贡献者适用)\n\n> **本仓实际默认 = Owner(Nancy)直 commit master、不建分支**(硬规则 #7,见下方 §Owner override)。下面仅约束 non-Owner 贡献者,或 Owner 在当前 session 明示\"走 PR / 建分支\"时。\n\n1. **在 master 起手** → `git checkout -b /`(type ∈ feat/fix/docs/chore/refactor/test)。\n2. **已在 feature 分支** → **强默认复用同一分支**。边界按**主题**(非文件/组件):同会话持续指令、无\"切任务\"信号 = 同主题,累积 commit 最后一个 PR。拆多分支/多 PR = 反模式(增 review 摩擦、破坏语义聚合)。\n3. **只在三种情况换分支**:用户明说\"另一个任务/新分支\"、当前 PR 已合并(master 已含该分支)、主题完全跨域(最后一种先问 owner)。**不主动问\"是否换分支\"**。\n\n### Commit + Push\n\n- Commit message 用 Conventional Commits:`type(scope): description`(如 `feat(button): add loading state`)\n- 一个分支可以多个 commit,PR 合并时会汇总\n- Push 后把 Gitea 自动返回的 PR 创建链接给用户:\n ```\n https://product-demo.tvustream.com/gitea/ux-team/tvu-design-system/compare/master...<分支名>\n ```\n\n### 并行 session 下的 git 纪律(本仓库常态:多 session 同时写)\n\n**本节是这两条纪律的唯一真源**(2026-08-04 从 `docs/STATUS.md` 顶部搬来——它们是规则不是状态)。\n\n1. **接手前先 `git status`;遇到 dirty / untracked 先判「隔夜遗留」还是「别人正在写」** —— 这两种情况的正确动作**相反**,而判据**不是**「dirty 就是别人的」,是 **mtime + `git log` 有无同任务 commit**。两次实证都在 2026-07-30/31 的多 session 并行里:起手时靠它判出 `UserMenu.vue` 正被并行写(mtime 与本 session 起手同分钟)从而没去碰;收尾时又靠它把一批「看着像隔夜残留」的 untracked 判成**正在进行**(mtime 在当下几分钟内),几分钟后那条线自己提交了。\n2. **`git commit` 必须带内联显式路径**:`git commit -F -- …`(`-F` 在 `--` 之前),**且提交后紧跟 `git reset -- `**。不带 pathspec 会把别人 staged 的文件卷进自己的 commit;不 reset 则留下幻影 staged 状态、会被别人下一次裸 commit 提交掉。⚠️ 并行写同一仓库时 `.git/index.lock` 会让 commit 直接 `exit 128` —— **那不是故障、是对方正在提交**,等一下重来即可(改动完好留在工作树)。\n\n### 建 PR 时如何填模板(PR body)\n\n建 PR 时按 [`.gitea/PULL_REQUEST_TEMPLATE.md`](./.gitea/PULL_REQUEST_TEMPLATE.md) 逐段填正文,分两类纪律:\n\n**必须自动填好**(从 diff / 对话可推导,不让 Owner 自己猜):\n- **改动内容**:读本次 diff,逐条列出实际改了什么文件、什么行为\n- **改动原因**:从对话上下文 / 关联需求写清楚,关联 Issue 写 `#编号`\n- **改动类型**:按改动性质勾选(可多选)\n- **备注**:reviewer 需知的点、后续 TODO、未执行项说明\n\n**禁止假填**(只能反映真实结果,否则误导 Owner review):\n- **测试情况 checkbox**:只勾**本次真实跑过并通过**的命令;没跑的留空,并在「备注」写明\"未执行:xxx\"。绝不能凭\"应该会过\"就打勾——Owner 见勾即视为已验证。\n- **截图 / 录屏**:仅 UI 改动且**真实跑过 app / playground 截取**才贴;纯 docs / 逻辑改动写\"不涉及 UI\"。不得生成或捏造截图。\n- **检查清单**:只勾确实核对过的项。\n\n**Why**:模板的价值是让 Owner 一眼判断该不该合。勾选若不可信 → 比留空更糟(制造虚假安全感)。AI 应把\"哪些已验证 / 哪些没验证\"如实写出,判断权留给 Owner。\n\n### 直 commit master 时:commit message 写结构化 body\n\n直 commit master 没有 PR 描述兜记录,**commit message 的 body 就是\"改了什么 + 测了什么\"的唯一载体**——按 [PR 模板](./.gitea/PULL_REQUEST_TEMPLATE.md) 字段精简对齐,让 `git log` / Gitea 提交页一眼可读,与同事走 PR 看到的信息一致、互不冲突。\n\n格式:\n\n```\n(): <一句话 subject> # subject 仍遵循 Conventional Commits\n\n改动内容:\n- <逐条列出实际改了什么文件 / 行为,从 diff 来>\n改动类型:feat / fix / docs / refactor / chore …(可多类)\n测试:<只写本次真实跑过的,如 pnpm test ✅ 219 passed;没跑的写\"未跑:lint/typecheck\">\n```\n\n**纪律(与 PR 模板同源)**:\n- 改动内容 / 类型从 diff 与对话自动填好,别让 Owner 自己猜。\n- 测试只写**真实执行**的结果;没跑的如实标\"未跑:xxx\",绝不能凭\"应该会过\"写 ✅——Owner 看 commit 即视为已验证。\n- UI 改动有截图就把路径 / 链接放进 body;纯逻辑改动注明\"不涉及 UI\"。\n\n**Why**:同事 PR 的\"改动 + 测试\"在 PR 描述里,Owner 直 commit 的在 commit body 里,两条路径记录同一套字段、各自独立——Owner 在 PR 列表和 git log 里都能一眼看出改了什么、测没测,统一可见且不冲突。\n\n### 直 commit master 时:写 changeset(版本日志)\n\n走 PR 有 PR 模板兜结构化记录;**直 commit master(Owner override)没有 PR**,靠 changeset 留每个版本的改动记录。仓库已配 [Changesets](./.changeset/config.json)(`baseBranch: master`),`CHANGELOG.md` 由它按版本自动生成——这就是\"按版本知道改了什么\"的真源。\n\n**何时写**:本次 commit **影响 npm 发布产物 / consumer 行为**时——`src/**` 组件、API/props、`src/tokens/**`、导出(`index.ts`)、`eslint-plugin/**`、`templates/**`,以及 **`files[]` 白名单内那 20 个 `scripts/`**(不是整个 `scripts/`)等 consumer-facing 资产。\n\n> ⚠️ **本行 2026-08-13 随 [[INFRA-F117]] 落地订正**:原文写的是裸 `scripts/`,而当时 `files[]` 也确实是裸 `\"scripts\"`(107 个内部脚本全进包)。F117 把它收窄成具名白名单后,**`scripts/` 不再整体是 consumer-facing** —— 判据改为「该文件在不在 `package.json` 的 `files[]` 里」,`files[]` 是唯一真源,别在这里维护第二份清单(要看当前白名单跑 `npm pack --dry-run`)。改一个只在本仓库跑的 `scripts/audit-*.mjs` 属**不写** changeset 的内部改动。\n\n\n\n**何时不写**(写了反而污染版本日志):纯 `docs/**`、`tests/**`、`playground/**`、`react-pilot/**`(owner 2026-08-12 明确补入 —— 它的 `src/demos/*.css` 是 docs 站两侧共用的 demo 样式,不进 `dist`)、`figma-sync/**`、CI / 内部重构等不改变发布产物的改动。\n\n**怎么写**:和实质改动放在**同一个 commit** 里,新增 `.changeset/.md`:\n\n```md\n---\n\"@ux-team/tvu-design-system\": patch\n---\n\n<面向 consumer 的一句话:改了什么 + 影响。Breaking 要写迁移说明。>\n```\n\n**bump 级别(= 改动类型)**:\n- `major` — 破坏性改动(API / prop 重命名或删除、行为不兼容)\n- `minor` — 新功能 / 新组件 / 新 prop(向后兼容)\n- `patch` — bug 修复 / 视觉对齐 / 小调整\n\n**纪律**:bump 级别和描述据实写,不夸大不缩小——`changeset version` 据此 bump 版本号并汇总进 CHANGELOG,Owner 与 consumer 都按它判断升级影响。发布时 `pnpm changeset:version` 汇总、`pnpm changeset:status` 查待发布项。\n\n### docs 站内部 demo / 页面样式改动的快车道(owner 2026-08-12 裁定)\n\n**适用面(严格 AND)**:本次改动集 ⊆ `playground/**` + `react-pilot/**` + `docs/**` + `tests/**`,**且不碰 `src/**`** ⇒ 不进 npm 产物、consumer 不可见。典型 = docs 站 demo CSS、页面布局、响应式断点、**闸的判据(指 `tests/**` 里的断言,⛔ 不含 `scripts/` 下的闸脚本本身)**。\n\n> ⚠️ **「闸的判据」四字的限定是 owner 2026-08-13 补的**([[INFRA-F128]] 系列评估发现互斥):原文只写「闸的判据」,而闸脚本住在 `scripts/`,于是它把 `scripts/` 隐含划进了快车道面 —— 但同段的「严格 AND」谓词**根本不含 `scripts/`**(只有 `playground`/`react-pilot`/`docs`/`tests`)。owner 确认原意是 **`tests/`**(2026-08-12 那批快车道改动实际动的就是 `tests/docs-overflow/*.spec.ts` 的 `VIEWPORTS` 与判据,且它满足谓词)。⇒ **改 `scripts/` 下的闸脚本不走快车道**(谓词不含它);**changeset 则仍按上一节 §「何时写」的 `files[]` 判据判 —— 不在 `files[]` 白名单里的内部 `audit-*.mjs` 属「不写」。**\n>\n> > 🔴 **2026-08-13 晚就地订正本段自己的一处 stale 转述(登记为原 INFRA-F124 ④ —— **该 entry 2026-08-14 四个子项全部落地后已删档**,判据留痕在 tracker §待核可关)**:上面原写「上一节 §「何时写」又把 `scripts/` 列为 consumer-facing **必写**,三方互斥」并据此推出「⇒ …**照常写 changeset**」—— **那句描述的是 [[INFRA-F117]] 落地前的措辞**。同一天的 §「何时写」(见上一节)已把判据订正为「该文件在不在 `package.json` 的 `files[]` 里,**`files[]` 是唯一真源**」,并逐字点名「改一个只在本仓库跑的 `scripts/audit-*.mjs` 属**不写** changeset 的内部改动」。⇒ 这**不是两条对等规则打架**,是本段的前提 stale ⇒ 它推出的那半句结论失效(互斥也从「三方」降为「两方」,第三方已自行消失)。**owner 的裁定实质一个字没动** —— 快车道谓词仍不含 `scripts/`;变的只是 changeset 那一半,从「照常写」改为回指 `files[]` 判据。⚠️ 这条留痕本身是「**同一份文件内部**的规则真源冲突」的实例,与 原 INFRA-F124 的三项(跨文件冲突)同类不同形态。\n\n**立规缘由**:这类改动的产品体量很小(常是几行 CSS),但此前按满配纪律走 —— 逐文件问视觉批准 + 为每条缺陷配新闸 + 故障注入证明 + STATUS/CHANGELOG/backlog/tracker 四处同步 —— 仪式成本是改动本身的数倍。owner 2026-08-12 拍板给三条豁免:\n\n1. **免 changeset** —— 见上一节「何时不写」(本裁定把 `react-pilot/**` 补进那张清单)。\n2. **视觉批准合批** —— `VISUAL_COMMIT_APPROVED` 一次批准覆盖**同一批**(同 session 内连续、owner 已看过效果的那一组)视觉改动,不必逐文件 / 逐 commit 各问一次。⚠️ **AI 仍然不自设这个变量**:合批只减少「问几次」,不改变「必须由 owner 说出口」。\n3. **免为它新建闸 / 免故障注入证明 / 免四处文档同步** —— 只更新 backlog 对应 entry(真源)+ STATUS 一行;不写复盘文档、不为单条缺陷新建 audit 脚本。\n\n⚠️ **「免机械闸」我按最窄读法执行,owner 可推翻**:读成「免**新建**闸」,**现成的 `audit:docs-overflow` / `audit:layout-tokens` / `vue-tsc` / `pnpm test` 仍然跑**。三条理由:① 前两条恰好是自动发现「内容被裁且够不着」的唯一手段,而 [[INFRA-F112]] 正是从 `docs-overflow` 的判据漏洞逃掉的 —— 关掉它等于把发现同类缺陷的能力一起关掉 ② 成本不在这里:四条合计 ~7min 且无人值守,同一条修复里真正吃时间的是重写判据、故障注入、四处文档 ③ 它们是**已存在**的闸,跑一次的边际成本近零。**重开条件**:owner 明说「连现成的也别跑」,或实测这几条闸的耗时占到一次 docs 修复总时长的 1/3 以上。\n\n### 禁止 AI 做的事\n\n- ❌ 不要自己点合并(PR 必须由人审批后合并)\n- ❌ **non-Owner** 不要试图 push 到 master(会被分支保护拒绝);**Owner 直 commit master 是默认**,见 §\"Owner 直 commit master 权限(broader 2026-05-28)\"\n- ❌ 不要为同一个逻辑改动拆多个分支\n- ❌ 不要在没确认主题完成的情况下擅自切回 master\n\n### Owner 直 commit master 权限(broader 2026-05-28)\n\n**2026-05-28 Owner override 升级**:原 docs-only 例外扩到 **任何改动**(含 code / config / schema / scripts / SoT 等)。Owner Nancy 默认 commit 到 master,**不建 feature 分支**,除非用户在当前 session 明示\"开分支\"。\n\n**触发条件(严格 AND)**:\n1. 当前 session 操作者 = Owner (默认 Nancy;见 §\"仓库身份\")\n2. Owner 未在当前 session 明示\"建分支\" / \"走 PR\" / \"feature branch\" 等措辞\n\n**AI 决策树**(在仓库 cwd 改任何文件时):\n\n```\n当前 session 是 Owner 操作?\n └─ YES → Owner 明示要建分支 / PR?\n └─ YES → 走 §\"Git 工作流(强制)\" feature branch\n └─ NO → 当前在 master:直 commit;当前在 feature:问 Owner \"本次并入当前分支还是切 master 直 commit?\"\n └─ NO → 走常规 feature branch + PR 流程\n```\n\n**Why**:\n- 单人 owner 项目 + AI plan-owner/executor 代理模式下,feature branch 仅是仪式 (no second reviewer except Owner themselves)\n- Owner 已对每个 commit 实质 review (plan owner 审 executor diff + Owner ack)\n- 分支保护可为 Owner 设豁免规则 (Gitea 支持);未设豁免时 Owner 用管理员权限绕过\n- 减少 branch / PR / merge 切换 cycle 摩擦\n\n**反例(仍走 feature branch)**:\n- 非 Owner 用户改任何文件 → 常规流程保留 review trail\n- Owner 明示\"这个开分支跑\" / \"走 PR\" → 按 Owner 指令开分支\n- AI 在 Owner 没明示授权直 commit 时... 实际不存在此 case(Owner override 是 default,AI 不需要明示授权也直 commit)\n\n**实证**:2026-05-28 BRIDGE-MOCKUP-008 Phase C session — Codex 按旧 docs-only 例外建 `chore/bridge-mockup-008-phase-c-merge` 分支,Owner 反问 \"为什么它会弄到分支里面?没道理不知道提交到 master\"。本条款升级。\n\n### Docs-only 改动:见上方 broader Owner override(legacy 2026-05-26,已被涵盖)\n\n**本节原 docs-only 例外(2026-05-26 立)已被上方 §\"Owner 直 commit master 权限(broader 2026-05-28)\" 完全涵盖**——docs-only 只是\"任何改动\"的子集,规则一律以 §276 broader override 为准,本节不再单独维护触发条件 / 决策树(避免两处改一处忘的 drift)。\n\n**实证(保留)**:2026-05-26 TPC bulk import session,Owner 改 mockup-conventions.md M23 stroke 3→4px 时被 AI 建议走 feature 分支,多绕一层;催生原 docs-only 例外,2026-05-28 被 broader override 吸收。\n\n---\n\n## 元规则:真源单一 + 双层导入(不绑工具 / 不绑模型)\n\n> 本元规则适用于**任何 AI 工具**(Claude Code / Codex / Cursor / Cline / Copilot / 其它)、**任何角色**(plan owner / executor / reviewer)。\n> 角色与工具的绑定可变化——当前 Claude Code = plan owner、Codex = executor,但可互换或被替代——**本规则不变**。\n\n详细规则、反模式清单、角色互换条款、Audit/数据产出类 prompt 子规则,统一登记在:\n\n→ **[`docs/meta-rules.md`](./docs/meta-rules.md)**(元规则真源)\n\n任何角色在写 prompt / 设计机制 / 推荐方案前,**必须先过 meta-rules.md 的反模式清单**。命中任一条 → 停下重新设计。\n\n---\n\n## 工作流(约定)\n\n> **角色驱动,工具可换。** 本段使用角色名(`plan owner` / `executor`)而非工具名。\n> **本仓实际默认(2026-07-17 对齐实际)**:solo DS 工作 = **Claude Code 同时任 plan owner + executor(直做 + 自动 subagent/Workflow 并行)**——不走 file-based 往返委派。下面的\"标准闭环 / executor STOP / file-based prompt\"是**委派协议**,仅在 **① 多工具协作(另一 AI 当 executor)或 ② 同事委派 / 大型可并行任务** 时启用。(owner 2026-07-16 确立\"默认自主 + 自动多 Agent 并行\"实践,详见 §标准闭环 头注。)\n> **委派时的默认绑定**:`plan owner = Claude Code`、`executor = Codex`。\n> **切换方式**:用户在对话里说\"把 `<角色>` 换成 ``\",新工具读 `AGENTS.md` + `docs/meta-rules.md` 即可承担该角色。\n> **切换不需要改本文件 / `meta-rules.md` / 任何 prompt 模板**——它们都是角色无关的。如果发现哪条规则绑了具体工具名,应该改成角色名(违反 meta-rules 反模式 #1)。\n\n### 角色定义\n\n| 角色 | 职责 |\n|---|---|\n| **plan owner** | 写 plan / 设计 prompt / 审 executor 的 diff / 复审是否进入下一阶段 |\n| **executor** | 按 plan owner 写的 prompt 严格执行任务 / 跑脚本 / 报告改动与未解决项 |\n| **reviewer** | 用户最终拍板(部分情况下 plan owner 兼任审计) |\n\n> 上表是默认骨架。**具体职责按下面 task-type 矩阵微调**——不是 one-size-fits-all。\n\n### Task-type 分工矩阵(mandatory,prompt §Mode 头段必声明)\n\n> 实证来源:P15.1 / P15.2 / P15.2-extend / P16 discovery 四次实跑。Plan owner 凭记忆喂 baseline 数字 = bug 源(P15 §0 算错 38 → reroute / pickup §3 \"~48\" 歧义被 Codex 抓出);executor 在 apply 阶段额外 verify spec = 冗余 round trip。\n>\n> **每个 prompt 必须在 §Mode 段明示 task type**(如 `Mode: Discovery only` / `Mode: Apply deterministic spec` / `Mode: Design options + STOP`)。executor 按对应行执行,plan owner 按对应行 review。\n\n| 任务类型 | Baseline 数字 | 决策 / 分类 | 设计选项 | 代码改动 | 典型实证 |\n|---|---|---|---|---|---|\n| **Discovery / 调研** | Executor grep 实证 | Executor 按 plan owner 写的机械规则分类 | Executor 列偏差 + STOP | ❌ 不动 | P15.1 / P16 discovery |\n| **Apply / 实施**(spec 已定) | Plan owner 写死 | Plan owner 已拍板 | ❌ 不发挥 | Executor 按 spec 改 | P15.2 / P15.2-extend |\n| **Design / 设计选项**(多解) | Plan owner 给约束 | — | Executor 列 2-3 选项 + 推荐默认 + STOP | ❌ 不动 | P16b verifier topology |\n| **Refactor / API 改造** | Plan owner 实证(写死)| Plan owner 拍板 API 形态 | Plan owner 拍板 | Executor 按 API spec 改 + 跑 vitest | Phase 6.6 dual-form / Phase 6.8 Button canonical |\n| **Infrastructure / 工具**(小 CLI / hook)| — | Plan owner 拍板 spec | Plan owner | **Plan owner 可 direct**(path B)| Tier 2-D/E/F / new-backlog.mjs |\n| **Audit / 数据扫描产出** | Executor grep | Executor 按 plan owner schema 输出 | — | ❌ 不动 | future audit-mockup-conformance discovery |\n\n### 跨 task-type 不变约束(所有类型都必须遵守)\n\n1. **Executor 永不 commit / push** — prompt 不得含 commit/push 指令,executor verify 后只报 diff + stdout,由 plan owner + 用户 ack 后才 commit\n2. **Plan owner 必独立 verify executor 报告**——按 task type 差异化(见下):\n - Discovery 类:sample 1-2 cluster 重 grep 验分类;不能只 verify 数字加总\n - Apply 类:diff 全审 + git status / git diff --stat 独立 check\n - Design 类:每个 option 独立查可行性,不 rubber-stamp executor 推荐\n3. **Plan owner 不直接动 source code / tokens / JSON 数据 / component**——例外仅 Infrastructure 类小工具 + 协作文档 + prompt 文件 + 审计报告 + 复盘文档\n4. **决定哪类 task type** 由 plan owner 在 prompt §Mode 段明示;executor 起手第一步是 confirm task type,与 prompt §Mode 不符必 STOP 反馈\n\n### 标准闭环(委派协议 — plan owner ≠ executor 时按顺序)\n\n> **适用范围**:下面 7 步是 **plan owner 与 executor 分属不同工具/人** 时的委派协议。**本仓 solo DS 工作(Claude 直做)默认不走此环**——坍缩为:`Claude 实现(+subagent/Workflow 并行)→ 自 verify 拿真实 gate stdout → owner ack → commit`(不可逆操作前的 owner ack 与自 verify 是保留的核心闸,见跨 task-type 不变约束 #1/#2)。\n\n1. plan owner 读项目规则 + audit\n2. plan owner 生成 `docs/internal/_prompts/.prompt.md`\n3. 用户把 prompt 交给 executor\n4. executor 按 prompt 改代码 / 产出文件\n5. executor STOP,列出改动和未验证项\n6. plan owner 复审 executor diff\n7. 用户决定是否进入下一阶段\n\n### 单一决策源模式(当前默认)\n\n为避免 plan owner 与 executor 在对话中互相\"补充框架\"、反复扩展路线,后续协作默认采用以下边界:\n\n- **plan owner 负责产出一版路线图 / prompt**,并把结构性决策固化到仓库文档\n- **executor 不做\"加料式评论\"**:不在 plan owner 路线图基础上继续发明新轨道、新阶段或新框架\n- **executor 只做三件事**:\n 1. 检查 prompt 是否有明显 blocker(会误删 / 误 commit / 改 Figma / 范围不可验证 / 与仓库规则冲突)\n 2. 执行 prompt 指定任务\n 3. 报告改动、验证结果、未解决项\n- 如果 executor 不同意 prompt,只指出**会导致失败的 blocker**,不扩展替代路线\n- 一旦 `docs/internal/long-term-plan-v2-*.md` 或同等路线图落仓库并经用户确认,本阶段以该文档为准;不要在对话里反复发明新框架\n\n### executor 角色行为约束\n\n- 用户通过 file-based prompt 触发任务:`请按 docs/internal/_prompts/.prompt.md 执行`\n- **起手第一步:confirm prompt §Mode 段声明的 task type**,按 task-type 矩阵对应行执行;prompt 缺 §Mode 段 → STOP 反馈让 plan owner 补\n- 每个 prompt 末尾会有 \"完成后 STOP,等用户审\"——**严格遵守 STOP**,不要自行进入下一步\n- 关键参数(如 token 值、变体枚举)**先列出来给用户确认**,不要自行决定\n- 在单一决策源模式下,执行前只做 blocker 检查;无 blocker 就执行,不再提出额外路线规划\n- **不\"加料式评论\"、不发明新轨道 / 阶段 / 框架**——只做三件事:① 检查 prompt 有无明显 blocker ② 执行 prompt 任务 ③ 报告改动、验证结果、未解决项\n- **永不自行 commit / push**(见跨 task-type 不变约束 #1)\n\n### plan owner 角色行为约束\n\n- 直接读项目文件审 executor 产出\n- 设计 prompt 前**强制过 `docs/meta-rules.md` 反模式清单**——命中任一条 → 重新设计,不 fire\n- **每个 prompt §Mode 段必明示 task type**(Discovery / Apply / Design / Refactor / Infrastructure / Audit)——见 task-type 矩阵\n- **Discovery / Audit 类 prompt 不写死 baseline 数字**——让 executor grep 实证;plan owner 凭记忆喂数字 = bug 源(P15 §0 算错 38 实证)\n- **Apply 类 prompt 必写死 spec**(token 名 / CSS 行 / API 形态)——不让 executor 重复 verify\n- 任何重大决策(破坏性 API 改造、跨阶段路径选择)必须 propose 给用户拍板\n- 默认**不直接修改代码 / 脚本 / tokens / JSON 数据 / 组件文件**——涉及这些改动时,应先生成 executor prompt,除非用户明确授权(Infrastructure 类小工具 path B 例外)\n- 可以直接修改协作规则文档、prompt 文件、审计报告和复盘文档;完成后必须 STOP,等用户确认\n- **审 executor 产出必独立 verify**——Discovery 类 sample 1-2 重 grep 验分类(不只 verify 数字加总);Apply 类全 diff 审 + git status 实证;Design 类每 option 独立查可行性\n\n### 共同规则\n\n- 决策必须固化到文档(不能只在对话里口头提)\n- 阶段完成后追加复盘到 `docs/internal/retrospection/{date}.md`","numLines":454,"startLine":1,"totalLines":781,"truncatedByTokenCap":true}}} {"type":"system","subtype":"thinking_tokens","estimated_tokens":50,"estimated_tokens_delta":50,"uuid":"b3ce2a55-538f-4ddd-a3ab-5c5c413d5465","session_id":"ccca31c3-4a85-4094-9f46-4533df53f8ce"} {"type":"system","subtype":"thinking_tokens","estimated_tokens":150,"estimated_tokens_delta":100,"uuid":"2e5c9cf3-605e-4a94-8ab8-7882745bf875","session_id":"ccca31c3-4a85-4094-9f46-4533df53f8ce"} {"type":"system","subtype":"thinking_tokens","estimated_tokens":250,"estimated_tokens_delta":100,"uuid":"99465d25-473b-47d0-834e-74722541e291","session_id":"ccca31c3-4a85-4094-9f46-4533df53f8ce"} {"type":"system","subtype":"thinking_tokens","estimated_tokens":400,"estimated_tokens_delta":150,"uuid":"f740cd7d-9a79-4145-803e-c999ecfa2bc9","session_id":"ccca31c3-4a85-4094-9f46-4533df53f8ce"} {"type":"assistant","message":{"model":"claude-opus-5","id":"msg_011CePDmK3p6j6G26PLhhYQz","type":"message","role":"assistant","content":[{"type":"thinking","thinking":"","signature":"CAIS4QoKpgEIERgCKkBfI/iJ1Xi85C4Qf27RT3tPH5knVc+EjPXeCbd6g9n8vd71eG6epcO2IZqirSrbw3VcfOYa58CF2fuOu3PnZfwzMg1jbGF1ZGUtb3B1cy01OAFCCHRoaW5raW5nWiRjODEyM2U4YS04YWI1LTRjMTAtOTI0NS03NzE5NWYwMDFmNWNyEBfgeyIqdf44HDNid5nifo2IAQGoAZ29tdQGsAECEgz/zIEc0bV+ssuc5fYaDBafyQ927uS5I9vnDCIweTWLoJiaxAyOxoOiLEL2VtMGHlSemgspNWjrMpQuAHY9IQx0z4brEeo/Q0enJGDNKucIx3nZIeKL5lf7Kl7z1WJaQbndU66dmM76jh/Sv6MZedrsfTcxwfDX9JTmsz3qDqj4Oe/tH4fALRmaE2eWnxpV7Z2d5h6YtfC+skp09VWvRHtJG2L8VNf/Kb8xM4WZoW6q8+6eqn4Ce8C7bjmfvbXFY1V4vNn1BRNxyu9Z/oplRCZTWzzXXQdIrUkE0FJ7sVxsch2BhBl9LQ+dQS14Z4vugNsBPjnBKN0VSySKj1hsMhoBYWnmWRaxQEdQPduqXlEM2P8ZYwR2fTiuYWhNKwU2I/WmY6Lq/nqAJLog2W1FRLY7tvPvGs7f7ZRgi+0iWEHbGJbhUYYw7O6UG8D12kIbHBM0T3KbetYDbc8/rlDc/3icsJyy4rX8W9xo/CoHxSo+QqUEZ5FNFbCOYwmlpFNM9Ya9emGVU1Z7v/ssNGCXO1ReQXuESPeneYCRjSLrMHOCHGCerHrd76xVfKjw1UxK1nh165Fh9BKh9+9sBFWjj33/UA78bHOrvPr3tgCQ34LMpVNtQCfJ5zGIhTR5k6vg/nIr3gqHB4+SVjnR2TRoa/5fj5jmDSgOJQtMbD9UlvImpBkDVO9tXK45jq2a+TobG7aULvqylYW6lG4GZh++a0kRsl8N40uq1Ts3QERbSLyC8G2WW2QNdlbOMtBJEAdhRtnT/Cx9ZA8re9wbQgNpK8+YcDTB11B04CSkgg2tecI0dy4LYiIcaJn7f9qwBBX0MG+jzE0s+tY5eWo4tv+nOHcgvVgcVmhQrVxP4Zs57UtMzOwGFvG1fr93XEan/dkd/QNVTHlgo8GRxVkNw1+f9RsoZ6b3jZdaRyuYvF0GXGhMty2enefef1/aUaPh5OM9ecKROyTHKJKC/DtQPP44vBmm3ySA55aWhYegwK903yIinEqBlPmfoyOdJPqo6LJDMApj4lC9tSdzTTEASeEvqDKYH6/RI92zQtwbwV+RA1LZSRGrNzkmdzu3D3Ymxvgc1Ii2GNIuFaoNJvoO9EfT/y9lm4nLWcIaEqdVv20VFPcuDAKsiBxWZHjQoF+m53sF83GLazrLpemJ6rrjvnLgqd74eF3kLmehlxval6MdZqjT5bLYfNh2G/Xu2DEzvPpZeVSuzBY7uv5QUOJZ7yW30gJzioasihWv2hNLjL59nl30YuVGhvcf0VIxBrzgtnCp/MSp7poNg3dmIPkukztS45of3pJ88Dsk9IM7UQXWM3+IW5UmsjqUe75YCPKQU8eAsmSykGj8lxDvA0CQpwbr3ZSvivIF4rEPNnQMTMuirzPvxsZT6ldQnl1AUe8rqjjzSjfXJZtR2Dg/xFFdEaqvS+yp7cv2ODDhjh3sXNm+jjy5NeRBXzoBGnwD2dfcbJRGsH9kOlBQ2sCNNM8STvEik5GNIi8yhSxlp54GQV5O7B2YeGodYFPIkReE3BzZIG58DR/q8FD+gmrqQsImZD5ZRqzVYjncEokU75VuwaTgaH+QUlM9nWbWmZdzfJacd0NsLU5WvN+nuIQYAQ=="}],"stop_reason":null,"stop_sequence":null,"stop_details":null,"usage":{"input_tokens":2,"cache_creation_input_tokens":59604,"cache_read_input_tokens":59449,"cache_creation":{"ephemeral_5m_input_tokens":0,"ephemeral_1h_input_tokens":59604},"output_tokens":3,"service_tier":"standard","inference_geo":"not_available"},"diagnostics":null,"context_management":null},"parent_tool_use_id":null,"session_id":"ccca31c3-4a85-4094-9f46-4533df53f8ce","uuid":"9c21fea6-64fb-4ab1-8d27-9be2c392da7f","timestamp":"2026-08-25T09:21:33.338Z","request_id":"req_011CePDmDecWL1kmnYqfk1vw"} {"type":"assistant","message":{"model":"claude-opus-5","id":"msg_011CePDmK3p6j6G26PLhhYQz","type":"message","role":"assistant","content":[{"type":"tool_use","id":"toolu_01XvttNysQ9vdbVRk4rPJnhq","name":"Read","input":{"file_path":"/Users/nancy/.ai-ds-lab/pins/tvu-ds-4a68e02d/AGENTS.md","offset":455,"limit":330},"caller":{"type":"direct"}}],"stop_reason":null,"stop_sequence":null,"stop_details":null,"usage":{"input_tokens":2,"cache_creation_input_tokens":59604,"cache_read_input_tokens":59449,"cache_creation":{"ephemeral_5m_input_tokens":0,"ephemeral_1h_input_tokens":59604},"output_tokens":3,"service_tier":"standard","inference_geo":"not_available"},"diagnostics":null,"context_management":null},"parent_tool_use_id":null,"session_id":"ccca31c3-4a85-4094-9f46-4533df53f8ce","uuid":"050b4151-c932-481e-b2a3-40b07f69cdcc","timestamp":"2026-08-25T09:21:34.764Z","request_id":"req_011CePDmDecWL1kmnYqfk1vw"} {"type":"user","message":{"role":"user","content":[{"tool_use_id":"toolu_01XvttNysQ9vdbVRk4rPJnhq","type":"tool_result","content":"455\t- 所有 prompt 版本化保存在 `docs/internal/_prompts/`\n456\t\n457\t### Sprint 收尾 Self-Audit 协议(mandatory)\n458\t\n459\t> **元规则归属**:本协议是 [`docs/meta-rules.md` §触发器 O](./docs/meta-rules.md) \"Onboarding 知识 ≠ 实际产品状态(实测优先)\" 的具体子规则落地 — sprint shipped 后用实测重审 spec / 实现 / doc,拒绝 \"按 spec ship 完即 done\" 心智模型。\n460\t\n461\t> **2026-05-27 INFRA-F35 实证立规**:9 项 spec 全 ship 后我自报 \"complete\",user 追问 \"再 audit\" 才暴露 5 个真问题(cleanup --apply 无 extract 不安全 / AGENTS.md stale / Step 10/11 silent failure / sample 5 太小 / backlog 缺 shipped 标识)。凭\"按 spec ship 完即 done\"心态根本抓不到这些。\n462\t\n463\t**任何 sprint commit/push 完成后,在 user 询问\"完成了吗\"之前主动跑 3 类扫描**。每个 finding 按 P0/P1/P2 分级 + 估时 explicit 输出,user 拍板要不要修。\n464\t\n465\t| 扫类 | 检查项 | 工具 |\n466\t|---|---|---|\n467\t| **A. Spec gap** | sprint spec 是否覆盖所有 user 给过的实例 case?(**实测拉一遍**,不凭印象)
边界条件 / 默认值是否拍板正确?(\"default ON\" 在哪些 mode 下不安全?)
参数(sample size / timeout / threshold)是否拍脑袋而非论证过? | 重新对照 user 原始 case 列表跑一遍 |\n468\t| **B. 实现 bug** | 看自己写的每段代码:为了\"快速过关\"硬编码 `code: 0` / `return true` / `catch {}` 吞 error?
新加的字段引用是否 exist?(例: `c.filename` vs `c.source` 这种 schema 误读)
silent failure path 是否暴露? | code review + unit-level test |\n469\t| **C. Doc lag** | grep 该 sprint 涉及的 noun / flag / 命令 across 全 repo doc
新引入概念在 AGENTS.md / STATUS.md / working-principles.md 登记?
backlog entry 是否标 ✅ shipped? | `grep -rn '' AGENTS.md docs/` |\n470\t| **D. Canonical compliance** (INFRA-F37 Phase 2 落地)| canonical/ 内有 inline `__check / __radio / __dot` 等 affordance?native `