# 2026-05-22 — Plugin 化 + 团队角色 / 词库共享（v0.1.0 → v0.2.0）

> Plugin migration + team-shared roles 一站式 session retrospect。
> 对应 prompt: [`_plans/_prompts/archived/plugin-migration-mvp.prompt.md`](../_prompts/archived/plugin-migration-mvp.prompt.md)
> 对应 commits: [67a44e79](https://github.com/NancyZeng0210/TVU-Design-System/commit/67a44e79) (v0.1.0) · [2f551f89](https://github.com/NancyZeng0210/TVU-Design-System/commit/2f551f89) (onboarding simplify) · [f9d90e3e](https://github.com/NancyZeng0210/TVU-Design-System/commit/f9d90e3e) (v0.2.0)

---

## 1. TL;DR

把 `.claude/skills/` 8 个 skill 打包成 Claude Code plugin `tvu`（v0.1.0），随后将 4 个用户级 role skill + 共享词库纳入同一 plugin（v0.2.0），落地团队同步机制。同事 onboarding 从"clone + ln -sfn"降级到**终端 2 行命令**。

> **核心 insight**：plugin 化的真实价值不是"少装东西"，而是把 namespace `tvu:` 物理隔离 + git 跟踪的版本契约一次性解决——同事自己写过同名 skill 也不会撞，更新机制变成 `claude plugin update` 一行。

| 指标 | 数 |
|---|---|
| 改动 commit | 3（plugin 化 + onboarding 简化 + v0.2.0 team roles） |
| 新增 / 修改文件 | 25 (`.claude-plugin/` × 2 / `skills/` 12 / docs × 4 / scripts × 1 / prompt × 1 等) |
| Plugin namespace skill 数 | 8 → 12 |
| `claude plugin validate` 校验 | ✅ pass（仅 marketplace description warning） |
| Pre-commit gates（vue-tsc + 137 测试 + figma-data 写检查 + 视觉 commit 闸） | ✅ 3 commit 全过 |

---

## 2. Session 概览

**起点**：用户问"同事从 Gitea 拉代码下来需要配置什么才能用 TVU 设计系统"

**最终落地**：
- 仓库根建 `.claude-plugin/{plugin,marketplace}.json`
- 12 个 skill 全部归 `tvu:` namespace（含 3 个 role + 1 个 vocab rule + vocab 文件）
- `docs/CONSUMER_ONBOARDING.md` — 终端 2 行命令为唯一推荐
- `tvu-design-mockup/SKILL.md` 加 Step 1.7 Bridge step（含 UI 文案时自动协调 role-ux + 词库）
- `scripts/lint-skills.mjs` 支持新旧 skill 路径双向兼容

**Process 产物**：
- Plan owner 写的 executor prompt：`docs/internal/_prompts/archived/plugin-migration-mvp.prompt.md`
- 1 份 engineering retrospect（本文件）

---

## 3. 关键决策时间线

| # | 用户原话 | AI 反应 | 决定 |
|---|---|---|---|
| 1 | "同事从 github 上拉代码下来需要配置什么才能使用吗" | 起手回答 npm install + .npmrc 配置 | 同事 onboarding 第一版 |
| 2 | "加了 tvu 也可能重命名，因为同事也在整理 tvu 的设计系统" | 启动 plugin namespace 调研 | **走 Plugin 路线**（决定性 pivot） |
| 3 | "走 Plugin" | 写 plan owner prompt → dispatch Codex | v0.1.0 落地 |
| 4 | "/plugin 命令在当前 VSCode 扩展环境下不可用" | 误判为同事桌面 App 也不可用 → 推 Projects pivot | **AI 误判**（见 Gap 1） |
| 5 | "我一直说同事用的是 Claude 桌面 App" | 确认是 Claude Code 而非聊天 App，看截图判定 | 撤回 Projects，回 plugin |
| 6 | "看起来 我也没有安装什么， 为什么还要用这两个文件" | 删 `.command` 双击安装器 | onboarding 简化（commit 2） |
| 7 | "UX 和 翻译这两个能否也加到里面去？...词库这个很重要" | 加 4 role + vocab 进 plugin | v0.2.0 落地（commit 3） |
| 8 | "Mockup 和 UX 有重叠了？能不能合并？" | 提 Bridge step 替代 full merge | mockup skill Step 1.7 加入 |

---

## 4. Process Gap

### Gap 1 · **产品名歧义未在第一时间澄清**

**实证**：
- 整个 session 中，用户说 "Claude Code App"，我默认理解为 Claude Code（CLI / VSCode 扩展）
- 当 `/plugin` 命令不可用时，我先后排查了 VSCode 扩展 bug / CC 版本太旧 / 命令名差异，**没问"你说的 Claude Code App 到底是哪个 icon"**
- 用户贴出版本号 `Claude 1.8555.0` 后我才警觉是聊天 App，错误推 Projects pivot
- 用户原话："我一直说同事用的是 Claude 桌面 App"

**返工成本**：~3 轮 round-trip + 1 个被撤回的 Projects 方案

**原因**：AI 把"Claude Code"和"Claude 桌面 App"（claude.ai download）当两个产品识别，但实际用户语境里"Claude 桌面 App 的 Code tab"是第三个产品入口——`Claude.app` 启动后切到 Code tab = Claude Code 服务，这条心智模型 AI 起手没建立。

**✅ 解决方案**：
- **当下修复**：本次 session 已通过看截图（Cowork / Routines / Opus 4.7 1M 等 CC 特征 UI）确认是 Claude Code 通过桌面 App Code tab 入口
- **长期防护**：AI 遇到 "App 版本 / 名字" 类问题，**起手先问"截图 / 启动台 icon / About 里写什么"**，不靠版本号格式猜测产品身份
- **真源落地**：⏳ 待回流到 [`docs/meta-rules.md`](../meta-rules.md) "AI 反模式清单"——新增一条 "产品识别先看截图 / icon，不靠名字 / 版本号"

### Gap 2 · **CONTRIBUTING.md scope creep 误判为 Codex 行为**

**实证**：
- 复审 Codex diff 时发现 `CONTRIBUTING.md` 新增 "团队仓库约定" 11 行
- 我标为 Codex scope creep，建议 revert
- 用户原话："这是另一个 Session 的 Claude Code 写的，先不用管"

**返工成本**：~1 轮 round-trip（用户澄清后我撤回判断）

**原因**：AI 复审 git status dirty 时默认"所有 dirty 都是当前 session 产物"，没核查 git log / 文件 mtime 区分跨 session

**✅ 解决方案**：
- **当下修复**：本 session 已遵循 memory `user_parallel-sessions`——后续所有 commit 都精确 stage（不混 CONTRIBUTING.md / 3 个 pre-existing dirty）
- **长期防护**：AI 复审 executor diff 时，**先 `git log <file>` 确认最近修改是不是当前 session 内**，再判定 scope creep
- **真源落地**：✅ 已在 memory `feedback_review-result-vs-rationale` 范畴内（已存在的规则），本 session 实证一次

### Gap 3 · **过度工程 `.command` 双击安装器**

**实证**：
- 用户提"少装"诉求 → AI 推 `.command` macOS 双击安装器（自带 Gatekeeper + 右键打开 + bash 兼容性）
- 用户当场反推："我也没有安装什么，为什么还要用这两个文件？是不是可以直接那 2 行命令就搞定了？"
- 改回 2 行终端命令为唯一推荐

**返工成本**：1 个 commit 撤回（commit 2: 简化 onboarding）

**原因**：AI 把"不习惯用终端"等同于"门槛极高需要包装"，没考虑到 Claude Code 用户都接触过类似工具，开终端 paste 2 行不是高门槛

**✅ 解决方案**：
- **当下修复**：删 `install-tvu.command`，CONSUMER_ONBOARDING.md 改成终端 2 行为主
- **长期防护**：AI 设计 onboarding flow 时，**优先最简路径（直接命令）**，再问"是否需要进一步降低门槛"，**不默认上 wrapper / installer**
- **真源落地**：⏳ 待回流到 [`docs/meta-rules.md`](../meta-rules.md) 反模式清单——"门槛降低不是 AI 一拍脑袋上 wrapper，先验证原始路径门槛是否真的存在"

---

## 5. 学到的新 Pattern

### 5.1 Plugin namespace 是 CC 跨同事 AI workflow 分发的 idiomatic 答案

| 维度 | symlink ~/.claude/skills/ | plugin namespace |
|---|---|---|
| 命名冲突 | 同名 skill 互相覆盖 / 优先级混乱 | `tvu:` 物理隔离，调用语法显式 |
| 更新机制 | 手动 git pull + symlink check | `claude plugin update tvu` 一行 |
| 团队同步 | 每人手动 maintain | git commit + push 一次，所有人 `claude plugin update` |
| 官方 schema | 无 | `claude plugin validate` 提供 |
| Resource location | `~/.claude/...` 绝对路径硬编码 | `${CLAUDE_PLUGIN_ROOT}` portable |

**结论**：任何"跨同事 / 跨机器分发 AI workflow"的项目，**默认走 plugin，不走 symlink hack**。

### 5.2 `${CLAUDE_PLUGIN_ROOT}` + skill self-resolve realpath = portable path 标准

```bash
# Plugin root resolution: env var preferred, realpath fallback
TVU="${CLAUDE_PLUGIN_ROOT:-$(cd "$(dirname "${BASH_SOURCE[0]:-$0}")/../.." && pwd)}"
```

Env var 是 plugin runtime 注入的 idiomatic；realpath fallback 兜底（dev mode / 工具未注入 env 时仍能解析）。**两条都配，不要二选一**。

### 5.3 Bridge step vs full skill merge

工作流层重叠（mockup 含 UI 文案 → 需要 role-ux 思考）**不必须靠合并 skill 解决**。在 mockup 起手协议加一条 "条件触发 load role-ux + vocab" 的 Bridge step，能达到"用户体验上合并"的效果但保留 skill 独立性：
- role-ux 仍能在不画 mockup 时独立用
- mockup skill 不爆炸成 2000 行
- 共享 vocab 自然成为桥梁

**类比**：Unix 管道哲学——小工具 + 显式 compose > 大单工具。

### 5.4 CLI 装的 plugin 被 Code tab 自动加载

`/plugin` slash command 在 Code tab UI 不可用，但 `claude plugin install tvu` 在终端跑后，Code tab 立刻识别 `tvu:` namespace skill。**install 与 use 跨 client 互通**——这条 invariant 让 `.command` 等 wrapper 没必要：终端跑一次，所有 client 都 work。

---

## 6. Post-deploy cleanup（用户侧）

```bash
# 等 Gitea 同步完成后跑：
claude plugin update tvu
claude plugin list  # 确认 0.2.0

# 备份本机用户级 role skill + vocab
cp -r ~/.claude/skills/role-{ux,translator,english-teacher} \
      ~/.claude/skills/shared-vocab-rules \
      ~/Desktop/claude-skills-backup-$(date +%Y%m%d) 2>/dev/null
cp ~/.claude/vocabulary.md ~/Desktop/vocabulary-backup-$(date +%Y%m%d).md 2>/dev/null

# 删用户级版本（避免 @UX 歧义）
rm -rf ~/.claude/skills/role-{ux,translator,english-teacher} \
       ~/.claude/skills/shared-vocab-rules
rm ~/.claude/vocabulary.md

# 重启 Claude Code App → @UX 应触发 tvu:role-ux（team 版）
```

---

## 7. 后续 backlog 候选（已识别，未排期）

| 候选项 | 优先级 | 触发条件 |
|---|---|---|
| 团队词库更新流程文档化（PR 审核 / 直接 commit / 频率） | Medium | 词库累积到 200+ 词条或团队提问 |
| Plugin 版本 changelog 机制（独立于 npm 包） | Medium | v0.3.0 时考虑 |
| `tvu-design-code` 也加 Bridge step（写 error message / 注释时 load role-ux） | Low | 用户实际遇到需求时 |
| `scripts/setup-consumer.ps1` PowerShell 等价 | Low | 同事 100% Windows + Git Bash 不可用时 |

---

## 8. 同日后续迭代（v0.2.1 + onboarding 完整版）

retrospect 主体写于 v0.2.0 发布后；同一日继续推进至 v0.2.1 + onboarding 文档完整化。补记关键学习：

### 8.1 v0.2.1：role-english-teacher 从 plugin 删除

**原因**：英语老师 skill 是个人艾宾浩斯学习用，团队场景无意义。归 user-level 真目录保留，plugin 仅留团队相关。
**实证**：commit [663ffe23](https://github.com/NancyZeng0210/TVU-Design-System/commit/663ffe23)。

### 8.2 Onboarding 双路径定型：Setup A vs Setup B

经过用户多轮诘问，明确**两种独立 setup**：

| Setup | 适用 | 同事工作流 |
|---|---|---|
| **A · 纯消费者** | 不打算改 TVU | `claude plugin install tvu` → 用工作流 |
| **B · 贡献者**（多数同事） | 想改进 TVU 设计系统 | clone 仓库 + 项目级 symlink → 即改即用 + PR 回流 |

**关键设计**：Setup B 不需要 plugin install——clone + symlink 已 100% 提供 AI 工作流，plugin install 反而是冗余副本（之前 doc 写错了）。

### 8.3 新 Pattern：Wake-word vs 终端命令双触发

同事是非 dev 多数 → 文字唤醒比终端友好。设计 Setup B Step 2 两种方式：

- **方法 a · 文字唤醒**：chat 说 "在当前项目中使用 TVU 设计系统" → 触发 `setup-tvu-consumer` skill → AI 跑脚本
- **方法 b · 终端**：直接 `bash setup-consumer.sh`

**前置桥**：Setup B Step 1 末尾加 `ln -sfn setup-tvu-consumer ~/.claude/skills/` —— 让 user 级唤醒入口存在，方法 a 才能 work。一次性 1 行命令换永久零终端 onboarding 新项目。

### 8.4 平台并列：macOS / Windows Git Bash

Windows 通过 Git Bash 跑同套 bash 命令（含 `ln -sfn`）；前提 Windows 10/11 开启 **Developer Mode**（symlink 创建权限）。doc 加 Windows 专属步骤 + Developer Mode 提醒。

### 8.5 Owner Exception（CONTRIBUTING.md）

Solo maintainer 阶段不强制 PR：commit message + git log 已是足够 audit trail。触发"团队 PR 模式"的条件简化为 **Owner 主动要求**。理由：单点维护时 PR 自审无 reviewer 价值。

### 8.6 Plugin git tag 入库

补打 3 个 plugin tag（`plugin-v0.1.0/0.2.0/0.2.1`）作为审计 history 锚点。Plugin version 主要由 `plugin.json` 字段驱动（`claude plugin update` 比较版本），tag 是辅助。

### 8.7 实战触发的 Process Gap 补记

#### Gap 4 · **凭证 prime 错误归因**（teammate Lora）

**实证**：teammate 报 `terminal prompts disabled` → AI 默认归因为 "Gitea 私有需 auth"，实际**Gitea 始终公有**，问题在 Lora 机器的 git credential helper（gh CLI / stale Keychain 等）拦截 HTTP URL 强制 auth。

**返工**：1 轮诊断纠偏（用户主动澄清"我的库一开始就是公有的"）+ doc 改 "Step 2 兜底" 分支结构。

**原因**：AI 跨度太快——看到"auth failed"立刻假设 "repo 需要 auth"，没先实测匿名 clone 是否 work。

**✅ 解决方案**：
- **当下修复**：实测 `GIT_TERMINAL_PROMPT=0 git clone` 验证服务器允许匿名 → 定位问题在 Lora 端 git 配置
- **长期防护**：诊断 auth 错误前**先实测匿名访问是否 work**——不要从错误信息直接跳到结论
- **真源落地**：⏳ 待回流到 [`docs/meta-rules.md`](../meta-rules.md) 反模式清单——"诊断网络/auth 错误前先二分实测"

---

## 9. 同日 commit 列表（按时序）

| Commit | 内容 |
|---|---|
| [67a44e79](https://github.com/NancyZeng0210/TVU-Design-System/commit/67a44e79) | **v0.1.0** plugin 化（tag `plugin-v0.1.0`） |
| [2f551f89](https://github.com/NancyZeng0210/TVU-Design-System/commit/2f551f89) | onboarding 简化（删 .command 文件） |
| [f9d90e3e](https://github.com/NancyZeng0210/TVU-Design-System/commit/f9d90e3e) | **v0.2.0** 团队角色 + 词库（tag `plugin-v0.2.0`） |
| [eba0b110](https://github.com/NancyZeng0210/TVU-Design-System/commit/eba0b110) | 本 retrospect 主体 + STATUS.md |
| [ce8733fc](https://github.com/NancyZeng0210/TVU-Design-System/commit/ce8733fc) | onboarding 加 prime 凭证 step（Lora bug fix） |
| [db816092](https://github.com/NancyZeng0210/TVU-Design-System/commit/db816092) | web login ≠ git CLI 凭证澄清 |
| [24682b84](https://github.com/NancyZeng0210/TVU-Design-System/commit/24682b84) | verify step 降级 |
| [663ffe23](https://github.com/NancyZeng0210/TVU-Design-System/commit/663ffe23) | **v0.2.1** 删 english-teacher（tag `plugin-v0.2.1`） |
| [5999bb22](https://github.com/NancyZeng0210/TVU-Design-System/commit/5999bb22) | `scripts/setup-consumer.sh` + skill 集成 |
| [306560ea](https://github.com/NancyZeng0210/TVU-Design-System/commit/306560ea) | onboarding 完整版（Setup A/B + macOS/Windows + wake-word + Owner Exception） |
| _本 commit_ | retrospect 8/9 段 + STATUS.md 同步 |