# 上手页重写 —— 从「装什么，然后怎么用」改成「跟 Claude 怎么说」

> **状态**：**设计已 owner 逐段确认（2026-08-12），未开工**。
> **实现计划**：[2026-08-12-onboarding-page-rewrite.md](../plans/2026-08-12-onboarding-page-rewrite.md)
> （7 个 Task；§10 那两个「开工前必测」= Task 1，两页的 `.html` 提交集中在 Task 7 由 owner 视觉批准）。
> **交付面**：`playground/public/onboarding.html` → 站上 `…/playground-dist/onboarding.html`，免登录可读。
> **判据真源**：本文件。实现期任何与本文件冲突的既有页面内容，以本文件为准（页面是被改的那一方）。
> **owner 判定原文（2026-08-12）**：「onboarding.html 这个文档并不是小白即可用的跟 Claude 对话指南的文档」·
> 「只要跟 Claude 怎么说就行，这个文档主要是为技术小白用户准备的，一种是：维护设计系统的设计同事来使用；
> 另一种是 PM 或者其他不维护只引用设计系统来做产品设计的用户使用，从 0（下载或 Clone）开始，
> 最好简单易懂，Windows 和 MAC 都适用」。

---

## 1. 一句话问题

这一页当前的主线是**安装手册**（`h1` = 「装什么，然后怎么用」，20 段里 8 段在讲装），
而它被要求成为的东西是**给技术小白的「跟 Claude 怎么说」指南**。
两条最需要它的路径（不装东西的那两条）**一句可粘的话都没有**。

---

## 2. 本轮实测（2026-08-12，全部自跑，非引用）

### 2a. 可粘贴块的构成 —— 话术是少数

页面 20 个 `div.you` 块中，**只有 9 块是「对 Claude 说的话」**，另 11 块是要读者自己敲的
终端命令 / 代码（`.npmrc` / `npm view` / `main.ts` / `data-theme` / React 两段 / 段落锚点形态…）。
两类块**共用同一个样式**，读者无法分辨哪句该粘给 AI、哪句该进终端。

### 2b. 9 块话术全落在「要装东西」的三条路上

按 `data-aud` 机械核：

| 顶栏身份 | 可见段数 | 可见话术块 |
|---|---|---|
| 我只想看看 | 4 | **0** |
| 出稿但不用 Figma | 8 | **0** |
| 出 Figma 设计稿 | 13 | 6 |
| 写代码 | 12 | 4 |

唤醒词那一段（`#daily`）挂 `data-aud="figma code"` ⇒ 前两条身份看不见它。
**最小白的两条路，恰好没有对话指南** —— 这是 owner 判定的机械成因，不是文风问题。

### 2c. 自相矛盾：声称不用命令行，实际要求三处

副标题（L338）写「不用懂命令行」、装 npm 包段（L469）写「全程不用碰命令行」，而：

- L486 要读者自己在终端跑 `echo "//…:_authToken=你的令牌" >> .npmrc`
- L495 要读者自己跑一行 `npm view @ux-team/… --registry=…`
- L693–698 要读者自己开终端跑 clone 并输 Gitea 凭据

### 2d. 段体量（`</section>` 边界机械切分，共 1337 行）

`install-npm` **187 行**（11 个代码块）· `develop` 21 · `appendix` 48 ⇒ **写代码那条共 256 行**。
`browse` 81 · `design-figma` 61 · `design-browser` 45 · 其余各 ≤ 37。

### 2e. 与 `CONSUMER_ONBOARDING.md` 已经分叉

- 本页 L452–455：「出 Figma 设计稿」**必须先装源码**（*Windows 约 30 分钟*）
- [`CONSUMER_ONBOARDING.md`](../../CONSUMER_ONBOARDING.md) L12/L31：**Setup A 纯消费者 30 秒、不 clone**，
  装完 `@TVU mockup` / `@TVU code` 在任意 cwd 可用（`tvu:` namespace 全局）

两处对「画 mockup 要不要 clone」给出相反答案。⇒ 重写若照抄本页，会把错的前置固化。

### 2f. 用户级 symlink 那一步，本页从头到尾没有

全页仅 L734 提了一句 Junction；`setup-tvu-consumer` / `~/.claude/skills` / `ln -sfn` **零命中**。
而 [`CONSUMER_ONBOARDING.md` L83](../../CONSUMER_ONBOARDING.md) 把它标成「关键 —— 让 Step 2 的文字唤醒可用」，
其故障排查表 L209 正是这一条漏掉后的症状。⇒ 照本页装完的维护者，`在当前项目中使用 TVU 设计系统`
这句唤醒可能不触发。

### 2g. 旧链接会死，但有现成机制

页面 script 里有一张 `LEGACY` 旧 id → 现 id 映射表（L1318–1324，现有 9 条），
深链逻辑在 L1329–1334。重写后 `install-npm` / `browse` / `develop` / `daily` / `three` / `use`
等 id 消失，已转发出去的链接会失效 ⇒ 必须扩这张表（§9）。

### 2h. 文档站搜索：**2026-08-12 已可用**（本 spec 起草期间被并行线改掉）

起草时 [[INFRA-F111]] 的现状是「死控件」（无 `@click`、`Cmd+K` 与 `/` 均无反应），
本 spec 初稿据此写了「⛔ 不得写可以搜索」。**同日并行 session 把它修了并 ship**
（`4c10a788`，②a 方案），⇒ 那条约束**当场作废、已反转**（§11-6）。

现状（取自更新后的 F111 entry，非推断）：能用，**范围是名字过滤** ——
匹配 `id` + 两种语言的 `label`/`title`（中文界面输入 `button` 也命中「按钮」），
**刻意不匹配 `summary`**；点击 / `Cmd+K` / `Ctrl+K` / `/` 打开；不设结果条数上限。
仍开着的 ②b（连正文/段落标题一起搜）是另一件事、未立项。

⇒ **段 11 必须写它，且必须同时写明「搜的是名字，不是正文」**（否则读者搜一句正文里的话
搜不到，会判定搜索坏了）。这也正是 F111 entry 里那条「哪天接上了，回来把这段补上」的落点。

> 教训（值得留在本文件里）：本 spec 起草期间，一条被当作「现状」写进设计的事实
> 在**同一天**被并行线改掉。⇒ 实现开工前**逐条重验本文件引用的活源**，
> 尤其 §2 的实测和 §6/§7 里引用的页面行号。

---

## 3. 用途与读者（owner 2026-08-12 定，是本文件的约束而非推断）

**唯一用途**：给技术小白的「跟 Claude 怎么说」指南。不是安装手册、不是 API 参考。

| 读者 | 是谁 | 从 0 开始要走什么 |
|---|---|---|
| **A · 维护设计系统的设计同事** | 会改 DS 本身（新增组件 / 改样式 / 画 mockup / 同步 Figma 库） | 装 Claude Code → clone 源码 |
| **B · 只引用不维护的 PM 等** | 用 DS 做产品设计，不改 DS | 装 Claude Code → 两行 plugin 命令 **或/且** 浏览器里的 Claude Design |

**读者 B 的两条子路都要支持，且不互斥**（owner 原话「第一和第三都需要支持」「Claude Design 和
Claude Code 可同时支持」）。

### 3a. 产出形态 × 工具是两个独立维度（owner 2026-08-12 订正）

|  | Figma 设计稿 | 不碰 Figma 的稿（可运行网页 / 浏览器里的稿） |
|---|---|---|
| **Claude Code** | ✅ 只有它能做 | ✅ 也能做 |
| **Claude Design**（浏览器） | ❌ 出不了 Figma 文件 | ✅ |

**唯一硬约束：要 Figma 稿 → 只能走 Claude Code。** 其余情况两个工具都行、可以都用。
⛔ 不得把「不要 Figma」写成「那就用 Claude Design」—— 那是把两个维度压成一条链，
本设计过程中犯过一次并被 owner 当场纠正。

### 3b. 第二道过滤：有没有内网 Gitea 凭据

**装 plugin 这条路本身就要 Gitea 凭据**（`marketplace add` 走的是 Gitea git URL，
A 段故障排查逐字写着「弹 prompt 时输 Gitea 用户名 + 密码/token」）—— 这条不是本轮推断，
是先前 session 已查实并登记在 [STATUS-CHANGELOG](../../internal/STATUS-CHANGELOG.md) 的结论。

⇒ 对**没有 Gitea 权限**的读者（含其他公司的同事），三个起点里**只有 Claude Design 和
「只看文档站」是活的**。分诊表必须有这一行兜底，否则这批人在三条路里一条都对不上号
（现页面把这件事埋在一个 note 里）。

---

## 4. owner 已拍（别重开）

| # | 决定 | 备注 |
|---|---|---|
| 1 | 结构走**方案 ①**：三个起点只在「装」这一段分岔，之后合成一条共用的对话主线 | 方案 ②（按读者拆两页）已否：对话主线会两页重复、必然漂 |
| 2 | 「写代码 / 装 npm 包」那 **256 行移到第二个页面**，也发在站上、免登录 | 见 §8。不删（dev 侧会失去唯一免登录入口）、不留作附录（小白仍会滚到术语） |
| 3 | 文档站导览（`browse` 81 行）**留，但收短**成「想自己翻就看这里」一小节 | 段落锚点怎么拼那些细节删掉 |
| 4 | 顶栏筛选器 = **2 个读者**（+ 全部），**不按工具分** | 按工具分会把两个可并存的工具框成互斥 |
| 5 | `h1` 改成「跟 Claude 怎么说」 | ⚠️ 它同时是 `<title>`；上一轮刻意没动，这次因用途本身变了才改 |

---

## 5. 目标页结构（12 段）

```
0  这套系统怎么用（一句话：先问系统有什么，再动手）
1  你走哪条 —— 先问产出形态，再问有没有内网 Gitea，带兜底行
2  先装 Claude Code（下面两条都要；Mac/Win 各怎么开终端）
3  装 Claude Code 的两个版本
     3a 维护设计系统的：clone
     3b 只用不维护的：两行 plugin 命令
4  用浏览器 Claude Design（零安装，跟 3 不排斥，可以都用）
5  第一次开口说什么（按产出形态给三块 + 极简唤醒词表）
6  需求怎么说清楚（模板 + 一个填好的真例子）
7  它答偏了怎么纠
8  怎么验收它给你的东西
9  收工怎么说（分人）
10 卡住了照贴这句
11 附：想自己翻文档站（收短版）· 要写代码 → 另一页
```

`h1` = 「跟 Claude 怎么说」；副标题 = 「你不用懂命令行、不用记规则。这一页给的是可以直接粘给
Claude 的话；哪一步必须你自己动手，会单独标出来。」

**顶栏筛选器**：`全部` / `我维护设计系统` / `我只用它，不维护`。保留既有 `?view=` URL 同步机制
（筛选后的地址可转发，已 ship，别拆）。

**按读者隐藏的只有段 3a / 3b 两段**。段 4（Claude Design）**对两类读者都可见** ——
维护者同样可以用它出非 Figma 稿，按读者藏掉就是把 §3a 那张二维表又压成一条链。
段 0/1/2 与 5–11 一律全可见（对话主线三类人共用，这正是方案 ① 的理由）。

### 5a. 被吸收 / 删除的旧段

| 旧段 | 去处 |
|---|---|
| `use`（一次任务的顺序，五步表） | **吸收**进段 6–9（它本就是对话主线的骨架，留着等于讲两遍） |
| `three`（做界面记住三条） | **转成话术形态**进段 7（从"要你背的规则"变成"你可以直接说的话"） |
| `new-project`（要建产品项目时） | 并进段 3a |
| `combine`（这几条怎么配合） | 删（元讨论） |
| `appendix`（为什么是这种装法：submodule / pnpm workspace / `file:` 路径） | 移入第二页（§8） |
| `install-npm` / `develop` | 移入第二页（§8） |
| `browse` | 收短进段 11 |
| Claude Design 段里「早期发 zip 包」那条 | 删（读者拿到的是共享项目，不会碰 zip，对小白是纯噪声） |

---

## 6. 三段安装的内容契约

### 6a. 全页贯穿：两类可粘块必须视觉分开

```
💬 粘给 Claude          ⌨️ 这行你自己敲（Claude 代不了）
```

**`⌨️` 的判据不是「这是不是命令」，而是「Claude 能不能代做」。** 全页只有 3 处 Claude 代不了：
装 Claude Code（它还不在）· clone 时输 Gitea 凭据（凭据必须从键盘直接进钥匙串，不经过对话记录）·
plugin 报 auth 错时 prime 凭据（同理）。

⇒ **其余一律 `💬`，即使内容是命令** —— 两行 plugin 命令、`claude plugin list` 验收、
`dist 目录在吗` 验收，都以「让 Claude 代跑」的话术形态给。
（治 §2a 的病：现在两类块共用一个样式，读者分不清哪句该粘给 AI、哪句该进终端。）

### 6b. Windows 特例的分配原则

| 能不能交给 Claude | 怎么处理 |
|---|---|
| 能（改凭据助手 `wincred` / 装 pnpm 别用 corepack / `core.autocrlf false` / 构建用 Git Bash） | **写进 `💬` 话术里**，页面上不出现这些命令 |
| 不能（开开发者模式 / 自己开终端输凭据） | 页面上 `⌨️` 明写，Mac / Win 并列 |

好处：Mac 读者根本不用读 Windows 那些；Windows 读者也不必理解为什么要改 `wincred`。

### 6c. 段 2 · 先装 Claude Code

- 页面上**唯一非得自己动手**的一段（Claude 还不在）—— 明写这句话降焦虑
- `claude.com/download`
- `⌨️` 怎么开终端，Mac / Win 并列：`Cmd+空格` → `Terminal` ／ 开始菜单 → `PowerShell`
- 验收：终端输 `claude` 能起来
- 一句：**从这里往后命令都能让 Claude 代跑，你只管说话**

### 6d. 段 3a · clone 版（读者 A）

- `💬` 沿用现页面 L668–687 那块已验证的话，**补上 §2f 漏掉的那一步**：把 `setup-tvu-consumer`
  挂到用户级 skills 目录让文字唤醒可用；Windows 上 `ln -s` 失败改目录联接（Junction）
- `⌨️` 人必须自己做的两步：
  1. Windows 先开**开发者模式**（设置 → 隐私和安全性 → 开发者选项）
  2. clone 那步 Claude 把命令给你、你自己开终端跑，输 Gitea 用户名 + **令牌当密码**
     - 必写：**网页登录 Gitea 不算**，必须终端跑一次才写进钥匙串 / Windows 凭据管理器
     - 必写：输密码时屏幕不显示任何字符，正常现象
- `💬` 验收话 `dist 目录在吗？里面有多少文件？` + 为什么用这个判据：
  **Windows 上构建会静默跳过、退出码还是 0，看着像成功**
- 以后要在别的产品项目里用 → 一句话唤醒（原 `new-project`）

### 6e. 段 3b · plugin 版（读者 B，愿意用 Claude Code）

- 两行：`claude plugin marketplace add http://product-demo.tvustream.com:3001/ux-team/tvu-design-system.git`
  + `claude plugin install tvu`
- ⛔ **这个 `:3001` 是实测通的那个，不许"现代化"成 https** —— 迁 HTTPS 标准端口的是 npm registry
  那一面，两回事（[[INFRA-F74]]）
- `💬` 这两行也能让 Claude 代跑
- 报 auth 错 → `⌨️` 先 `git ls-remote <同上 URL>` 输一次凭据（同 6d：网页登录不算）
- 验收：`claude plugin list` 有 `tvu` 且 enabled，或直接说 `@TVU mockup` 看有没有反应
  （⚠️ 验收判据的强度见 §10-②）
- 更新：`claude plugin update tvu`

### 6f. 段 4 · 用浏览器 Claude Design（读者 B，零安装）

- 开头就写**跟段 3 不排斥，可以都用**
- 要什么：Claude **Pro / Max / Team** 账号 + 找 owner 共享名为 `TVU UX Design System` 的项目
- 保留 4 条 ⚠️：认项目所有者别只认名字 · 没有「间距」基础卡（`Corner Radius` 讲的是圆角
  `--r-xs…--r-xxl`）· 卡片命名跟仓库不一致、以卡片描述为准 · 内容是快照不实时，拿到先自己翻一遍
- 验收：项目里看得到 6 张基础卡 + 一批组件卡；看不到就找 owner 同步一次
- ⚠️ 卡片张数这类会动的数字，若写就必须带「实况日期」并注明是快照（沿用现页面做法）

---

## 7. 对话主线的内容契约（段 5–10）

> 段 6/7/8 是**全新内容**，现页面没有。它们不是搬来的，是从仓库既有结论派生：
> 「先查再说」方法论 · 硬规则 #9（不准拿「应该通过」代替真实输出）· 图标必须从库取那条。

### 7a. 段 5 · 第一次开口说什么（按产出形态，不按身份）

两条 Claude Code 路的唤醒词是同一套，所以这里**按你要产出什么**分三块：

⚠️ **要 Figma 稿这条多一个第 0 步**（实测见 §10-①）：Figma 通路是机器级 plugin，**不随装完
Claude Code / tvu plugin 自动就位**。先问 `💬 我现在有 Figma 的工具吗？` 或自己跑
`claude mcp list | grep -i figma`——没看到 `plugin:figma` 那一行就是没接，去装 Figma 的插件
（跟装 tvu plugin 是两件独立的事）。**接没接和有没有权限是两个问题**：下一步那句自检报错时，
`Looks like you don't have edit access to this file.` 既可能是「没权限」，也可能是「文件不存在」，
也可能是「根本没接 Figma」——分不清就先回头确认这第 0 步过了没有。

| 你要的 | `💬` 开场 |
|---|---|
| Figma 设计稿（先过第 0 步） | 自检通路：`读一下这个 Figma 文件有哪些页面：<链接>` → 通了再 `@TVU mockup` + 链接 + 要做什么 |
| 不要 Figma，要能在浏览器里看的稿 | `我要设计一个 <X> 页面。先看看设计系统里有哪些组件能用，然后给我一个能在浏览器里打开的稿。` |
| 用 Claude Design | 在共享项目里**直接提需求**，没有唤醒词 |

**极简唤醒词表只留 5 个**：`@TVU mockup`（画/改 Figma 稿）· `@UX`（聊思路、写 UI 文案）·
`design walkthrough`（走查）· `@TVU 设计全流程`（一条流程的所有状态一次做齐）· `收尾`（收工存档）。
其余（`design-discovery` / `design-qa-loop` / `persona-simulation` / `同步交付物` / `design done`
/ `@翻译` / `@TVU code`）**不列**，改成一句兜底 `💬 你这儿有哪些 TVU 的唤醒词？列一下。`
—— 用对话解决「清单会漂」，与本页「别去背数字」同一原则。

必写一句：**唤醒词只在 Claude Code 里有效**，Claude Design 里直接说需求。

⚠️ **唤醒词的仓库侧真源是 [`docs/WAKE-WORDS.md`](../../WAKE-WORDS.md)，但它在私有仓库、外部读者打不开**
⇒ 页面**不链过去**，用那句「问 Claude 列一遍」兜底。这也是为什么表只给 5 个最常用的、
不复制全表 —— 既有裁定：唤醒词表复述出第二份必漂移（`DESIGNING_WITH_TVU.md` 立文时刻意不复述，
见 [STATUS-CHANGELOG](../../internal/STATUS-CHANGELOG.md) 同条）。

### 7b. 段 6 · 需求怎么说清楚（整页最重要的一段）

现页面把「说清目标」列进五步表点了个名，**没给模板**，而这是读者唯一真正要做的事。

```
💬 我要做 <什么>。
   给谁用：<角色 / 场景>
   要覆盖这些情况：<正常 / 空 / 加载中 / 出错 / 数据很长>
   边界：<不要动什么、不要自己造什么>
   先别动手 —— 先告诉我设计系统里有哪些现成的能用，以及你打算怎么做。
```

最后一句是把「先查再说」压成一句可粘的话。配一句解释：**不列状态，AI 交回来的通常是
happy path 一张图**（该判断现页面已有，沿用）。再配**一个填好的真例子**（如「批量导出的空状态」）。

### 7c. 段 7 · 它答偏了怎么纠

同时把 `three` 那三条从「要你背的规则」转成「你可以直接说的话」：

| 它开始… | `💬` 你说 |
|---|---|
| 自己拼组件 | `这个是从设计系统里取的还是你自己拼的？把来源列出来；自拼的换成现成的。` |
| 手搓 SVG 图标 | `停。图标必须从设计系统的图标库取，先把可用的列出来给我挑。` |
| 写死颜色 | `有没有写死的 hex？有就换成 token。` |
| 跑成一整套 / 说完成了但看不出改了啥 | `范围收回来，只做 <X>。具体改了哪些文件、哪些帧？逐个列出来。` |

### 7d. 段 8 · 怎么验收它给你的东西

原则一句：**别看它说「完成了」，看它给的证据。**

- Figma 稿 → 让它列改了哪些 frame + 给截图，你自己在 Figma 里点开看
- 能跑的稿 → 让它给一个你能打开的地址，你自己在浏览器里点
- 装 / 配置 → 看具体判据（`dist` 里有没有文件 · `plugin list` 认不认）

再加一句：**它说「应该没问题」就等于没验** → `💬 你实际跑了吗？把输出原样贴给我。`
（= 仓库硬规则 #9 的小白版，值得出现在对外页上。）

### 7e. 段 9 · 收工怎么说（分人）

- **clone 那条**：说 `收尾` → 自动写工作记录、提交、推到 Gitea，**署名你的真实姓名**。
  ⚠️ 明写「它会真的推代码，知道了再说」
- **plugin / 浏览器那条**：没有仓库，`收尾` 不适用 →
  `💬 把今天做完的和没做完的列一下，我要贴到 Jira / 文档里。`

### 7f. 段 10 · 卡住了照贴这句

沿用现页面 L1077 那块兜底话，加一句：**把报错原样贴给它，别自己转述**（转述会丢关键行）。

### 7g. 段 11 · 附录两块

**① 想自己翻文档站**（`browse` 81 行的收短版）：

- 入口 URL（免登录）
- 进去先动的两个开关：**默认开出来是英文**（点右上角 `中文`）· `Vue` ↔ `React` **真换实现**
  （React 态底层换成 `<tvu-button>` 这类自定义元素，不是换段代码给你看）
- 左侧 7 组分组表（Foundation / Basic / Form / Data / Navigation / Overlays & Messaging / Others），
  并写明**这是分组不是清单**，组里有几个随版本动、以站上为准
- **搜索**：顶栏那个能用了，`Cmd+K` / `Ctrl+K` / `/` 也能开；⚠️ **搜的是页面和组件的名字，不是正文**
  （见 §2h）
- **删掉**：段落锚点怎么拼、跨语言不通用、哪些页不支持锚点 —— 小白用不上（这三条是 owner 拍的「收短」）

**② 要在产品里写代码** → 一句指向 `for-developers.html`（§8）。

---

## 8. 第二个页面：`playground/public/for-developers.html`

- 范围 = 现 `install-npm`（187 行）+ `develop`（21）+ `appendix`（48），**近逐字搬运**，
  只改跨页指路措辞。⛔ 不趁搬运改技术内容（那些数值/报错表是实测过的）
- 与本页的关系：本页段 11 一句指路；该页顶部一句回指本页
- 它同样随 `pnpm build:playground` 发布、免登录可读
- 读者是 dev，**不受本 spec「零术语」约束**

---

## 9. 连带改动（不做就会分叉）

1. **`docs/CONSUMER_ONBOARDING.md` 收成指针** —— 新页自包含（命令写在页面上），
   两处都写装法必然分叉（§2e 已经在分叉了）。做法沿用 `ONBOARDING_NEW_MACHINE.md` 的既有范式。
   ⚠️ 该文件的 §A 故障排查、Setup B 的 symlink 步骤、故障排查表在收缩前**必须先确认已被新页吸收**，
   逐条对照，不许「收缩」成丢内容。
   ⚠️ **它有 4 处入站引用要同步**（已 grep）：`ONBOARDING_NEW_MACHINE.md:42` ·
   `PLUGIN.md:34` · `DESIGNING_WITH_TVU.md:44` · `scripts/setup-consumer.sh:9`（注释）。
   收缩后「装法真源」= 站上的新页；仓库侧四处一律改成指过去。
2. **`LEGACY` 映射表扩条目**（L1318）：`install-npm` · `develop` · `appendix` · `browse` ·
   `daily` · `three` · `use` · `combine` · `new-project` · `install` · `install-source*` ·
   `triage` · `method` · `lookup` · `stuck` + 现有 9 条旧代号。
   ⚠️ 其中 `install-npm` / `develop` / `appendix` 的内容搬到了另一页 ⇒ 要**跨页跳转**
   （`location.replace('./for-developers.html#…')`），不是改 hash 就行。
3. **`docs/STATUS.md`** §一 第 0 条：那条「`#browse` 段等视觉批准」的在飞项**作废**，
   改成本重写的在飞状态（`#browse` 那批未提交改动的去向见 §11-③）。
4. **`docs/DESIGNING_WITH_TVU.md`** 已是指回本页的指针，确认其措辞在重写后仍成立。

---

## 10. 开工前必须先测的两件事（已测，2026-08-12，结论如下）

① **Figma 通路来自哪一层。** 已测（2026-08-12）：

```
$ claude mcp list 2>&1 | grep -iE 'figma'
plugin:figma:figma: https://mcp.figma.com/mcp (HTTP) - ✔ Connected
```

前缀 `plugin:` = **机器级 plugin**（随这台机器装的 Figma 插件而来，换台机器不会自动有）。
阴性对照——确认「账号级连接器」确实用另一种前缀，排除「前缀本身无意义」：

```
$ claude mcp list 2>&1 | grep -c '^claude.ai '
14
```

14 行都以 `claude.ai ` 开头（账号级连接器，登录即有），与 Figma 那行的 `plugin:` 前缀明显是两类。

**结论**：新机器装完 Claude Code + tvu plugin **不会自动有 Figma 通路**——Figma MCP 是单独装的机器级
plugin，不随账号登录自动就位。而现页面的 Figma 自检只区分「通」与「没权限」：一台根本没接 Figma 的机器
贴那句自检，只会看到 `Looks like you don't have edit access to this file.`，这条报错**不区分**
「没权限 / 文件不存在 / 根本没接 Figma」，会把「根本没接」误导成「我没权限」。
⇒ 段 5（§7a）Figma 那一行前必须加第 0 步，改法见 §7a。

② **plugin 装完，skills 能不能读到它们引用的规则文档。** 已测（2026-08-12），四个 skill 对照：

```
$ for s in tvu-design-mockup tvu-design-code role-ux consumer-product-conventions; do
    printf '%-32s CLAUDE_PLUGIN_ROOT=%s  裸docs/internal=%s\n' "$s" \
      "$(grep -c 'CLAUDE_PLUGIN_ROOT' skills/$s/SKILL.md)" \
      "$(grep -cE '(^|[^/${])docs/internal/' skills/$s/SKILL.md)"
  done
tvu-design-mockup                CLAUDE_PLUGIN_ROOT=7  裸docs/internal=2
tvu-design-code                  CLAUDE_PLUGIN_ROOT=5  裸docs/internal=1
role-ux                          CLAUDE_PLUGIN_ROOT=1  裸docs/internal=0
consumer-product-conventions     CLAUDE_PLUGIN_ROOT=0  裸docs/internal=4
```

`tvu-design-mockup` / `tvu-design-code` / `role-ux` 的硬规则真源（`mockup-conventions.md` /
`code-conventions.md` / `figma-component-catalog.md`）都走 `${CLAUDE_PLUGIN_ROOT}/…` 定位
（`tvu-design-code/SKILL.md:16` 还写了变量未展开时的 fallback）；`tvu-design-mockup` 那 2 处裸路径
落在「retrospect 写到哪」（输出路径，不是要读的规则），不影响判据。⇒ **plugin-only 环境能读到
mockup / code 规则文档**。

`consumer-product-conventions` 的 4 处裸路径逐条核对（Rule 6「真源（本条只是常驻兜底，详则见真源）」
列表 2 处 + Rule 7 规则索引表 2 处），全部落在「真源在哪」的说明位，不是「现在去读它」的指令位
——按判据不算缺陷，本轮不登记 backlog（详见 task-1-report.md）。

**结论**：段 3b（§6e）的验收判据可以写成强判据——「它能列出 mockup 规则」（而非只看
`plugin list` 认不认这条弱判据）。

---

## 11. 落地约束

1. **`.html` 命中 pre-commit 视觉闸** ⇒ 提交需 `VISUAL_COMMIT_APPROVED=1`，
   **AI 不自设**，owner 看过效果才给。两个页面各要一次。
2. **别手工往 `playground-dist/` 塞**（`emptyOutDir: true`）；改源后跑 `pnpm build:playground`。
   2026-08-12 已确认工作树干净、抽屉导航（`c98253a5`）已 ship ⇒ 可以干净重建，
   **不必再走 worktree**（08-11 那条结论已过期）。
3. **`#browse` 那批未提交改动（95 增 17 删）不单独提交** —— owner 已定它收短进段 11，
   约一半存活（两个开关 + 分组表 + 「默认英文」那条纠正），段落锚点细节丢弃。
   ⇒ 重写时从工作树那份取材，不要从 HEAD 取（HEAD 那版含一句**已证伪的说法**：
   「可以直接复制带段落锚点的链接」）。
4. **取渲染证据必须用送 `charset=utf-8` 的本地服务器** —— `python3 -m http.server` 不送，
   整页按 Latin-1 解码成乱码，毁掉 CJK 可断行性，会量出不存在的布局缺陷
   （2026-08-11 真踩过，那批数字全作废）。
5. **提交纪律**：`git diff --stat -- <路径…>` 先看，再 `git commit -F <msg> -- <路径…>`，
   紧跟 `git reset -- <路径…>`。本仓库常态多 session 并行，不带 pathspec 会卷进别人的改动。
6. **可以写「文档站能搜索」了，但必须写明范围是名字过滤**（[[INFRA-F111]] ②a 于 2026-08-12
   ship，`4c10a788`）。⛔ 别写成「全文检索」——搜正文搜不到是设计如此（②b 未立项）。
   ⛔ 也别再复述「搜索是死的」那个旧现状。
7. **`playground/public/onboarding.html` 在 de-mirror 闸的扫描面里，mode = `no-version`**
   （2026-08-11 扩面时加入，理由逐字写在 `scripts/audit-doc-de-mirror.mjs`：
   「上手页写死版本比内部文档更贵，读它的人拿不到仓库、无从核对」）
   ⇒ **重写后的页面不得出现任何 `vX.Y` 版本字面**，除非行内加 `<!-- de-mirror-ok: 理由 -->`。
8. **新页 `for-developers.html` 建议不加进那条闸的 `no-version` 扫描面** —— 它必须写 peer 版本
   下界（`vue ^3.5.0`，SoT 是 `package.json`，与 npm 包版本是两个事实）。
   若仍要加，那几行需带 `de-mirror-ok` 豁免。**但它同样不得写死本包的版本号**（那是 STATUS 的真源）。

---

## 12. 不做（YAGNI）

- **不做英文版**（owner 2026-08-11 已拍：先只出中文，等真有人要再说）
- **不给页面加搜索 / 目录折叠 / 进度条**等新交互 —— 现有 `?view=` 筛选 + 目录 + 回到顶部够用
- **不把规则正文内联**（间距 / 命名 / token / 组件 API 仍然只指路，owner 2026-08-11 内联边界）
- **不动 `playground/docs/` 文档站本体**（本 spec 只碰 `playground/public/` 两个静态页）
- **不修 [[INFRA-F111]] 那个死控件** —— 它是 owner 的产品判断（三条修法），不在本轮