# TVU Design System — 同事 Onboarding

## 前置
- Claude Code 已装（最新版，[下载](https://claude.com/download)）
- 在公司内网或 VPN 内（访问内部 Gitea）
- macOS 或 Windows（两个平台命令并列在下面）

## 选你的 setup（二选一）

| 你的情况 | 看哪段 | 时长 |
|---|---|---|
| 不打算改 TVU 设计系统，只用 AI 工作流 | **A · 纯消费者** | 30 秒 |
| 想贡献 / 改进 TVU 设计系统（多数同事推荐） | **B · 贡献者** | 2 分钟 |

---

## A · 纯消费者安装

打开终端：

- **macOS**：`Cmd + 空格` → 输入 `Terminal` → 回车
- **Windows**：开始菜单 → 输入 `PowerShell` → 回车

复制粘贴（macOS / Windows 通用）：

```bash
claude plugin marketplace add http://product-demo.tvustream.com:3001/ux-team/tvu-design-system.git
claude plugin install tvu
```

完成 ✅ — 在 Claude Code 任意 cwd 说 `@TVU mockup` / `@TVU code` 即可触发。唤醒词通过 `tvu:` namespace 全局可用。

### A 故障排查：报 auth 错

如果上面命令报 `HTTPS authentication failed` 或 `terminal prompts disabled`：

```bash
# 1. 用普通 git 命令 prime 凭证缓存，弹 prompt 时输 Gitea 用户名 + 密码/token
git ls-remote http://product-demo.tvustream.com:3001/ux-team/tvu-design-system.git

# 2. 清掉上次失败残留
claude plugin marketplace remove tvu-design-system 2>/dev/null

# 3. 重跑安装
claude plugin marketplace add http://product-demo.tvustream.com:3001/ux-team/tvu-design-system.git
claude plugin install tvu
```

> ⚠️ **网页登录 Gitea 不能替代**——必须用终端跑 git 命令才能把凭证写进 macOS Keychain / Windows Credential Manager。

---

## B · 贡献者安装

分 2 步：**Step 1 一次性 clone + 初始化**，**Step 2 每个消费产品接入一次**。

### Step 1 · 一次性 clone + 初始化（终端跑一次）

#### ▼ macOS Terminal

```bash
mkdir -p ~/code && cd ~/code
git clone http://product-demo.tvustream.com:3001/ux-team/tvu-design-system.git
cd tvu-design-system && pnpm install
mkdir -p ~/.claude/skills
ln -sfn ~/code/tvu-design-system/skills/setup-tvu-consumer ~/.claude/skills/setup-tvu-consumer
```

#### ▼ Windows Git Bash

⚠️ **先开 Developer Mode**：设置 → 隐私和安全性 → 开发者选项 → 打开 **"开发人员模式"**（用于让 `ln -s` 能创建 symlink 而无需管理员权限）

打开 **Git Bash**（不是 PowerShell——symlink 创建用 Git Bash 最稳）：

```bash
mkdir -p ~/code && cd ~/code
git clone http://product-demo.tvustream.com:3001/ux-team/tvu-design-system.git
cd tvu-design-system && pnpm install
mkdir -p ~/.claude/skills
ln -sfn ~/code/tvu-design-system/skills/setup-tvu-consumer ~/.claude/skills/setup-tvu-consumer
```

> Step 1 末尾这条 `ln -sfn setup-tvu-consumer` 是关键——把 setup 入口 skill 挂到 user 级，让 Step 2 的"文字唤醒"方法可用。

### Step 2 · 把 TVU 接入每个消费产品（任选其一）

#### ▼ 方法 a · 文字唤醒（推荐，零终端）

在你的消费产品 cwd 打开 Claude Code，chat 里说：

```
在当前项目中使用 TVU 设计系统
```

AI 自动触发 `setup-tvu-consumer` skill → 跑项目级 setup 脚本 → 完成 ✅

唤醒词的其它说法（任一可用）：

- "scaffold TVU consumer product"
- "初始化 TVU 消费产品"
- "把这个项目接入 TVU"

#### ▼ 方法 b · 终端命令

```bash
cd ~/code/<你的消费产品>
bash ~/code/tvu-design-system/scripts/setup-consumer.sh
```

完成 ✅ — 在该消费产品 cwd 内说 `@TVU mockup` / `@TVU code` / `@UX` / `@翻译` 即可触发。

### B 项目级 scope 说明

唤醒词**仅在该消费产品 cwd 内有效**，离开 cwd 不触发。其它消费产品需各自跑一次 Step 2（方法 a 或 b 任选）。

### B 的好处

- **dev clone 是单一真源**：改 `~/code/tvu-design-system/skills/...` AI 立即看到，不需要 commit/push/update
- **改完顺手 PR 回流**：发现 TVU 设计系统问题 → 进 dev clone 走 4 步 PR（见 [`CONTRIBUTING.md`](../CONTRIBUTING.md)）
- **拿团队最新**：`cd ~/code/tvu-design-system && git pull` 即可

### B 简化：加 alias（可选）

#### macOS（`~/.zshrc`）

```bash
alias tvu-setup="bash ~/code/tvu-design-system/scripts/setup-consumer.sh"
```

#### Windows Git Bash（`~/.bashrc`）

```bash
alias tvu-setup="bash ~/code/tvu-design-system/scripts/setup-consumer.sh"
```

加完后 `source ~/.zshrc`（macOS）或 `source ~/.bashrc`（Windows Git Bash）生效。之后任何新消费产品接入 TVU：

```bash
cd ~/code/<新消费产品> && tvu-setup
```

---

## 验证（A 或 B 都适用）

跟 Claude 说 `@TVU code` 或 `@TVU mockup` → 应触发对应 skill。

> 如果触发不了：
> - Setup A：跑 `claude plugin list | grep tvu` 看是否 enabled
> - Setup B：在该消费产品 cwd 跑 `ls .claude/skills/` 看 symlink 是否就位

---

## 可用 skill 列表

**设计 / 代码 / 消费产品**

- `tvu-design-mockup` — 在 Figma 画 mockup（含 UI 文案时自动协调 role-ux + 词库）
- `tvu-design-code` — 在产品 repo 写代码消费 library
- `design-discovery` — pre-design 用户研究
- `design-walkthrough` — F1 设计走查
- `design-qa-loop` — Design QA 两阶段
- `persona-simulation` — F2 persona 模拟
- `consumer-product-conventions` — 消费产品通用规则
- `setup-tvu-consumer` — 初始化新消费产品 scaffold（含 vite singlefile / docs 骨架 / postinstall 联调检查）

**团队共享角色 + 词库**

- `role-ux` — UX 设计师角色（唤醒词 `Hi，UX` / `@UX`）
- `role-translator` — 智能翻译助手（唤醒词 `Hi，翻译` / `@翻译`）
- `shared-vocab-rules` — 团队词库规则 + `vocabulary.md`（不单独触发，由 role-ux / role-translator / mockup Bridge step 引用）

> Setup A 用户使用全限定 `tvu:<skill-name>` 形式（如 `/tvu:design-walkthrough`）可消歧——当你自己也有同名 skill 时用。

---

## 装 npm 包（消费 library 本身）

如果你要在产品里 import TVU library 组件（如 `<Button>` / `<Input>` 等），见 [`GETTING_STARTED.md`](../GETTING_STARTED.md)（含 `.npmrc` + GitHub PAT 配置）。

---

## 更新到最新版

| Setup | 命令 |
|---|---|
| A · 纯消费者 | `claude plugin update tvu` |
| B · 贡献者 | `cd ~/code/tvu-design-system && git pull` |

---

## 故障排查

| 症状 | 检查 |
|---|---|
| `claude` 命令找不到 | 没装 Claude Code，先去 [claude.com/download](https://claude.com/download) |
| `Failed to add marketplace: HTTPS authentication failed` 或 `terminal prompts disabled` | Gitea 凭证未缓存。跑 §A 故障排查段的 `git ls-remote` 输用户名密码 |
| marketplace add 报 "cannot fetch" | 检查 VPN / 内网连通性 + Gitea 仓库 read 权限 |
| `@TVU` 触发不了（Setup A） | `claude plugin list` 看 enabled；未 enabled 则 `claude plugin enable tvu` |
| `@TVU` 触发不了（Setup B） | 检查当前 cwd 是否含 `.claude/skills/tvu-design-mockup` symlink；不在则重跑 setup（方法 a 或 b） |
| 文字唤醒"在当前项目中使用 TVU 设计系统"无反应（Setup B） | 检查 Step 1 末尾的 `ln -sfn setup-tvu-consumer` 是否跑过；`ls ~/.claude/skills/setup-tvu-consumer` 应是 symlink |
| Setup B symlink broken | TVU clone 路径变了 / 重新 clone 过 → 重跑 setup（方法 a 或 b） |
| Setup B Windows symlink 创建失败 | Developer Mode 未开。设置 → 隐私和安全性 → 开发者选项 → 打开"开发人员模式" |
| 自己有同名 `design-walkthrough` skill | Setup A 用全限定 `/tvu:design-walkthrough`；Setup B 项目级 scope 自然隔离 |

---

## 给完全不熟终端的同事

如果 Step 1 那段命令看起来很陌生，可以：

1. **先选 Setup A**——只用 AI 工作流，无需 clone、无需理解项目级 setup
2. **未来想贡献时再升级到 Setup B**——到时找熟悉终端的同事或 Nancy 协助 Step 1

Setup A 装上后能用所有 AI 工作流（mockup / code / UX / 翻译），跟 Setup B 体验上唯一差别是：Setup B 改了 TVU 文件 AI 立即看到（无需 git pull），Setup A 需要 `claude plugin update tvu` 才拿到新版。