---
name: setup-tvu-consumer
description: 在当前消费产品 cwd 跑一次性项目 scaffold。唤醒词：scaffold TVU consumer product / 初始化 TVU 消费产品 / 在当前项目中使用 TVU 设计系统 / 把这个项目接入 TVU。用于检查 vite singlefile、docs 骨架、postinstall TVU DS 联调等项目级配置；skill 安装由 tvu plugin 负责。
---

# 配置当前项目消费 TVU 设计系统

本 skill 是**meta / onboarding shim**——本身不做 TVU 业务工作（那些归 `tvu-design-mockup` / `tvu-design-code`），只在新产品 cwd 做一次性 setup。

**真源仓库**：`${CLAUDE_PLUGIN_ROOT}`（下称 `$TVU`）

**可执行 runbook**：`$TVU/templates/consumer-product/SETUP_GUIDE.md`（团队共享、跟 design system 版本一起演进）

路径解析：Markdown 中的 `${CLAUDE_PLUGIN_ROOT}` 表示当前 plugin root；若环境未展开该变量，按本 skill 下方 bash block 的 `TVU` fallback 解析到 plugin 根目录。

---

## 起手协议（按序，不可省略）

### 1. cwd 安全检查（任一命中 → STOP）

| 情况 | 处置 |
|---|---|
| cwd 在 `$TVU` 内部 | STOP — 这是 maintainer side，不是消费侧；告警"你在 tvu-design-system 自己内部，不需要 setup" |
| cwd 是 `/` 或 `$HOME` | STOP — 误触保护 |
| `$TVU` 路径不存在 | STOP — 告警"TVU 真源仓库不在预期路径，setup 前先确认仓库位置" |
| cwd 在 `/tmp/*` 或其他临时目录 | 警告 "这是临时目录，setup 会随目录清理失效" → 让用户确认 |

### 2. idempotency 检查

检查 `docs/`、`scripts/link-tvu-ds.mjs`、`.marprc.yml`、`.gitignore` 的 TVU scaffold marker：
- 若全部已就位 → 报告"项目 scaffold 已配置过"，列出现有文件，**STOP**，不重复 setup
- 若部分已就位 → 继续 step 3，但只补缺失项，不覆盖已有内容
- 若均未就位 → 继续 step 3

### 2.5. Variant Selection（mandatory · 不要默认）

**问用户**选哪种消费产品变体（详见 [`PROJECT_STRUCTURE.md` § 两种变体](../../templates/consumer-product/PROJECT_STRUCTURE.md#两种变体setup-时必选其一)）：

```
你要建哪种变体？
  A · Design + Code（默认）— 标准消费产品，含 vue-app / vite / postinstall sibling link
  B · Design-only（纯设计协作）— 只放 mockup spec / 需求 / 复盘 / Figma 链接，代码住别处
```

**判定启发**（辅助推测，仍要让用户确认）：
- cwd 已有 `package.json` / `vite.config.{js,ts}` / `src/` → 倾向 A
- cwd 完全空 OR 只有 `docs/` / 设计草稿 → 倾向 B
- 用户已说"不写代码"/"代码在别的仓"/"只放 UX 设计" → 锁定 B

把用户选择记到 `VARIANT` 变量传给 runbook（详见 `SETUP_GUIDE.md` Step 0）。Step 1 / 2 在变体 B 时整段跳过。

### 3. 项目级 skill symlink（clone-based 用户必跑；plugin 用户冗余但无害）

```bash
TVU="${CLAUDE_PLUGIN_ROOT:-$(cd "$(dirname "${BASH_SOURCE[0]:-$0}")/../.." && pwd)}"
bash "$TVU/scripts/setup-consumer.sh"
```

该脚本会在当前 cwd 建 `.claude/skills/` 项目级 symlink（11 个 skill + vocabulary.md），让用户在该 cwd 内 `@TVU mockup` / `@UX` 等唤醒词 work。

- Clone-based 用户（如维护者本机用 dev clone 但不装 plugin）：**必跑**——否则项目 cwd 无任何 TVU skill 可用
- Plugin 用户：可选——已通过 `tvu:` namespace 全局可用，再加项目级 symlink 冗余但不冲突

### 4. 读 + 执行项目 scaffold runbook

```bash
# 用 Read 工具读取并按顺序执行：
#   $TVU/templates/consumer-product/SETUP_GUIDE.md
# Steps 1 → 6 全在里头，按当前 cwd 跑。
```

Runbook 内含：
- Step 0：Variant Selection（变体 A · Design+Code / 变体 B · Design-only）
- Step 1：Vite singlefile 配置检查（**仅变体 A**；只报告不动手）
- Step 2：TVU DS 联调（**仅变体 A**；postinstall 软链 + vite alias 条件块，npm fallback）
- Step 2.6：TVU 规范强制接线（**仅变体 A**；按场景接 ESLint + lint-staged/pre-commit——场景3 全量严格 / 场景2 只 gate 改动文件 / 场景1 off）
- Step 2.7：mockup handoff conformance gate（**两变体共用**；零依赖 git hook，变体 B 用 `core.hooksPath`、变体 A 追加到 `.husky/pre-commit`，唯一硬依赖 node；INFRA-F62-b）
- Step 3：Docs 骨架 + 项目结构 scaffold（**两变体共用**，idempotent；变体 B 跳过主应用目录检查）
- Step 4：验证（变体 A 全套 / 变体 B 只验 docs 骨架）
- Step 5：报告 + 收尾（变体 B 简化报告）

---

## 不要做（反模式）

- ❌ 不要默认装到全局 `~/.claude/skills/`（plugin install 已替代 legacy symlink）
- ❌ 不要在已配置项目重复 scaffold（覆盖既有内容风险）
- ❌ 不要给 `$TVU` 自己跑（自指 symlink 污染源仓库）
- ❌ 不要顺手帮用户改 user-level `~/.claude/settings.json`（用户已明确选项目级 opt-in 模式）
- ❌ **不要自动改 `vite.config.js`**——配置文件常有项目自定义逻辑（alias、proxy、env 处理），覆写易出错。所有 vite 相关检查只报告不动手
- ❌ **不要覆盖已存在的 `docs/README.md` / `docs/retrospects/README.md`**——docs scaffold 完全 idempotent，已有内容是用户改过的，不动
- ❌ **不要自动改 `dependencies` 版本号**（含 `file:` / `link:` 反模式检测）——涉及构建语义，只报告建议
- ❌ **不要自动装 marp-cli**——全局工具，让用户自己决定（提示即可）
- ❌ **不要自动重整既有项目根目录结构**——PROJECT_STRUCTURE 检查只报告差异，不移动文件（影响面大，必须用户主导）

---

## 设计决策（why this shim exists）

- 用户 2026-05-14 session 明确拒绝"全局默认接入 TVU"路径，但希望有一个全局可触发的**setup 入口**——可控、显式、每次 opt-in
- 本 shim 跟 plugin install 不冲突：plugin 负责 skill 分发，本 shim 只负责消费产品项目级 scaffold
- **Runbook 内容**搬到 `$TVU/templates/consumer-product/SETUP_GUIDE.md`，跟 design system 一起 git 跟踪 + 团队共享 + 跟着版本演进；本 shim 只留 user-CLI-绑定的部分（唤醒词 + cwd 安全 + 反模式 + 设计决策）