---
name: consumer-product-conventions
description: TVU 消费产品通用工作规则（跨 consumer 共享）。任何 consumer product 内操作时 AI 必须遵守：(1) 用户说收尾/wrap up/复盘 → commit + push gitea (2) 写任何 TVU 品牌色/视觉 hex 前先 grep variables.css 真源 (3) 复盘/分享物料署名默认用 git config user.name 不用 generic team name (4) Marp dist 导出按需触发, 默认不主动生成 (5) Marp 不导出 PDF, 只 HTML + PPTX (6) 任何 UI（mockup + code）开建第一步必须复用 DS canonical 组件 + 图标从 dist/icons/svg/ 取, 禁手搓组件/内联自画 SVG/PNG/emoji, DS 合规是开建硬约束非事后 QA (7) Meta: 写 feedback memory 前先问是不是通用规则, 通用就回流到 TVU 真源不进 memory. (8) 产品设计/mockup/code 任务起手读消费产品 docs/PRODUCT_INTRODUCTION.md（项目简介+团队 roster+产品设计规则+Figma 索引）, 缺失则提示按模板创建.
---

# TVU 消费产品通用工作规则

> **真源位置**：`tvu-design-system/skills/consumer-product-conventions/SKILL.md`
> **加载机制**：通过 `tvu` plugin 安装后在每个 consumer 项目中可用
> **适用范围**：任何 TVU 消费产品

本 skill 是**跨 consumer 共享的工作规则集**，AI 在任何 TVU consumer cwd 都必须遵守。

## Meta-Rule（最重要）

**写任何 feedback memory 前，先问自己**：

> 这条规则是**用户个人偏好**，还是**所有 TVU 消费产品都该遵守的通用规则**？

| 性质 | 归位 |
|---|---|
| 用户个人偏好（"Nancy 喜欢 X"） | 项目级 memory dir |
| 项目特定事实（"本项目用 gitea 端口 3001"） | 项目级 memory dir |
| TVU 消费产品**通用规则** | **本 skill** 或 TVU 真源其它 convention 文档 |
| TVU mockup / code 业务规则 | `mockup-conventions.md` / `code-conventions.md` |

**反模式**：每个 consumer 都写一份同样的"feedback memory"——污染各 consumer memory dir，TVU 改规则时要逐 consumer 同步。

**回流路径**：发现某条 feedback 写到了多个 consumer memory 里，立刻 promote 到本 skill。

---

## Rule 1 · 收尾 / Wrap-Up → 自动 commit + push gitea

**触发关键词**（在消费产品 cwd 中）：收尾 / wrap up / 复盘 / retrospect

**AI 默认动作**：
1. 写复盘 MD + 配套 `.slides.md`（默认放 `docs/retrospects/`）
2. `git add` 相关文件 + commit（含 `Co-Authored-By`）
3. `git push` 到 gitea origin
4. **不自动跑 Marp 导出**（详见 Rule 4）

**Why**: 消费产品用 gitea 做远端备份。收尾 = 工作产出固化 = 必须落远端，本地有丢失风险。

**例外**：
- `.env` / secrets / 大二进制混在 staged 改动里 → 停下确认
- 未关联到本 session 的他人正在改的文件 → 不要 stash / 不要顺手 add

**复盘格式 spec**：必读 `tvu-design-system/templates/consumer-product/docs/retrospects/RETROSPECT_FORMAT.md`
- 8 段格式（TL;DR / Session 概览 / 时间线 / Top N Gap / 高效对话建议 / 规则回流 / Model 选型 / Action Items）
- 长读版 `.md` + slides 版 `.slides.md` 配对
- 文件命名：`YYYY-MM-DD-{feature}-{type}.md`
- 标杆参考：已 ship 的 consumer video-sync + consumer-scaffold 两篇

---

## Rule 2 · 品牌色 / 视觉 hex 写前必 grep 真源

**强制前置步骤**（写任何涉及 TVU 品牌色 / 主题 / 视觉强调色的 hex 前）：

```bash
grep "brand" tvu-design-system/src/tokens/variables.css
```

**真源速查**：见 `tvu-design-system/BRANDING.md`（token 表 + logo 用法）

**Why**: 2026-05-21 实证 — AI 凭印象写 `#1f4e8c`（蓝）作为 TVU 品牌色，污染 6 文件。真值是 `#2fb54e`（dark mode brand token）。**记忆不可靠，颜色 token 演进时尤其会漂移**。

**适用场景**：
- Marp 主题 CSS
- mockup hex spec
- 文档 / 幻灯片配色示例
- PPTX 模板 / 分享物料

**例外**：仅 logo 文件保留 logo 色（`#56AF31 / #50B848`）；UI / 品牌强调一律走 `--brand` token。

**反模式**：
- ❌ "我记得 TVU 是 X 色"——记忆不可靠
- ❌ 不查 token 直接 hardcode
- ❌ 混淆 logo 色与 brand token

---

## Rule 3 · 署名默认用 git user.name

**复盘文档、幻灯片、分享物料的署名 / 作者 / footer / Thank You 页**默认用**对话者的真实姓名**（如 Nancy Zeng），不用 generic 的 "TVU UX team" / "UX team" / "Anonymous"。

**取值**：`git config user.name`

**Why**: Generic 团队名 = 没署名，分享时同事/领导不知道是谁做的；真实姓名才让贡献归属清晰。

**实现细节**：
- Marp slides 模板：footer 用 `{{AUTHOR}} × {{AI_MODEL}}`，Thank You 页用 `{{AUTHOR}} ({{TEAM}})`
- `setup-tvu-consumer` 复制模板时用 `git config user.name` 自动替换 `{{AUTHOR}}`
- 直接写复盘 MD / slides 时默认填用户名，不用 "TVU UX team" 占位

**例外**：真的代表整个团队立场（如团队达成的决策记录），可用 team name + 个人作者并列。

---

## Rule 4 · Dist 导出按需触发，默认不主动生成

**默认状态**：复盘 / mockup / 任何文档的 **dist 导出物料**（PPTX / HTML）**不生成**。AI 不要自作主张帮用户跑 marp/导出。

**不导出场景**：
- 用户说"收尾 / wrap up / 复盘" → 只 commit 源文件 (`.md` + `.slides.md`)
- 写完复盘 → 不跑 marp
- session 结束 → 不跑 marp
- demo / 验证 → 跑了之后告诉用户"已生成预览，按需保留"，不当成默认流程

**导出触发关键词**（用户显式说才跑）：
- "导出幻灯片" / "export slides"
- "分享" / "share"
- "出 PPT" / "出 HTML" / "出 PPTX"
- "生成 dist"

**Why**: 每份 PPTX 占 6-7MB + Chromium 启动 ~10s + 多产物维护混乱。`.md` 源 + gitea 浏览器渲染已覆盖"日常看复盘"场景。

**跑完报告**：产物路径 + 大小，让用户知道生成了多少东西。

**例外 · 远程访问 / 上传服务器 → force-add 入 git**

`dist/` 目录默认 gitignored，但当用户说以下关键词时：
- "远程访问 dist" / "需要远程访问"
- "上传服务器" / "share remotely"
- "把 dist 也提交" / "提交带上 dist"
- "通过 gitea / 远端拿 PPTX"

→ 用 `git add -f docs/retrospects/dist/<file>` **绕过 gitignore 单次提交**，commit message 注明"force-add for remote share"。

**Why**: gitea web UI 提供 download 链接，dist 提交后跨机器/同事/领导可直接通过浏览器拿 PPTX，比手动 scp / 邮件附件高效。

**注意**：
- 不修改 `.gitignore`——保持 default = 不入 git
- 每次新 dist 需要远程访问都要重新 `-f` 强制 add
- 用完后 dist 可以保留（gitea 占空间小）或下个 `git rm --cached` 清理

---

## Rule 5 · Marp 不导出 PDF

**只出 HTML + PPTX，不出 PDF**。

**Why**: Marp PDF 走 Chromium 的打印 CSS 管线（`@page` 规则 + 字体 hinting），跟 HTML 直接渲染 / PPTX 嵌入位图的产物排版**不一致**。多层 `radial-gradient` 被简化、`box-shadow` 经常丢失、长 list 行间距偏差导致溢出 slide。

**替代方案**：领导要 PDF → 跑 PPTX → 用 Keynote / PowerPoint 自带"另存为 PDF"，渲染走 PowerPoint 而非 Chromium，保真度更高。

**实施**：
- `marp` 命令不加 `--pdf`
- 用户明确要 Marp PDF → 先警告失真 + 建议改用 PPTX 另存为 PDF
- 模板 / README / SKILL.md 不要把 PDF 列进推荐组合

---

## Rule 6 · DS 组件 / 图标复用前置（常驻硬约束，开建即生效）

**强制前置步骤**（在 consumer cwd 里**开建任何 UI**——Figma mockup 或代码——的第一步，不是收尾 QA）：

1. **组件**：任何 UI 元素先查 DS 库再决定，**复用 canonical 组件**（代码 `src/canonical/*.vue` / Figma 取 TVU 设计系统库的对应组件），**禁手搓 frame / 裸 div 当组件**。
2. **图标**：起手 `ls tvu-design-system/dist/icons/svg/` 是 **mandatory**；图标一律从这里取，**禁内联自画 SVG / PNG base64 / emoji / 用文字 `+` `...` 凑**。
3. **颜色 / 字号 / 间距**：用 token（见 Rule 2），**禁裸 hex / 裸 fontSize**。

**Why**: 2026-06-17 BM-1047 V3 复盘实证 — DS 合规被当成事后 QA 而非开建硬约束，导致"裸 hex 色 + 手搓 frame 当组件 + 拿错库图标"，返工最重（按钮 13 个重建、checkbox 换 2 次、图标换 2 次）。**根因是组件/图标复用此前只活在 `tvu-design-mockup` / `tvu-design-code` 这两个 trigger-skill 里，没有常驻兜底**——走快捷入口或本地 prompt 跳过起手协议时就没人拦自造组件 / 内联 SVG。本条把它提升到 always-on 层，不依赖 mockup/code skill 是否被唤醒。

**真源**（本条只是常驻兜底，详则见真源）：
- 组件复用：`docs/internal/mockup-conventions.md` M2 / `docs/internal/code-conventions.md` R15
- 图标取 `dist/icons/svg/`：`docs/internal/code-conventions.md` R1

**适用场景**：Figma mockup（含 PRD→Figma）、HTML/Vue 代码、demo、分享物料里的 UI 片段。

**反模式**：
- ❌ 先手搓界面拼出来、DS 合规留到收尾补 —— 这就是"快捷路径"，最高返工
- ❌ 内联自画 SVG / PNG icon / emoji 凑图标
- ❌ 裸 hex / 裸 fontSize / 手搓组件
- ❌ "先出效果，组件后面再换" —— 换的成本远高于开建即用

---

## Rule 7 · 关联真源文档

本 skill 是规则**索引**。详细文档分布在 TVU 真源各处：

| 主题 | 真源 |
|---|---|
| 品牌色 token | `src/tokens/variables.css` + `BRANDING.md` |
| Marp 主题 / 导出 | `templates/consumer-product/marp-themes/README.md` |
| 项目目录结构 | `templates/consumer-product/PROJECT_STRUCTURE.md` |
| 复盘 8 段格式 | 消费产品 `docs/retrospects/` 下已 ship 的 internal-share retrospect（最新日期优先） |
| Mockup 业务规则 | `docs/internal/mockup-conventions.md` |
| Code 业务规则 | `docs/internal/code-conventions.md` |

---

## Rule 8 · 起手读消费产品的 `PRODUCT_INTRODUCTION.md`

**触发**：任何在消费产品 cwd 内的产品设计 / mockup / code 任务**起手**。

**AI 默认动作**：起手先读 `docs/PRODUCT_INTRODUCTION.md`——它承载该消费产品的**项目简介 + 团队 roster（含 Jira accountId）+ 产品设计规则（如 Figma 页面组织约定：新需求页归到哪个版本 / 状态分组）+ Figma 文件索引**。交付 @mention、「某模块找谁」、新页归位等都以它为准。

**缺失时**：提示用户该文件缺失，建议按模板 [`templates/consumer-product/docs/PRODUCT_INTRODUCTION.md`](../../templates/consumer-product/docs/PRODUCT_INTRODUCTION.md) 创建；**不要凭印象编项目信息**。（`setup-tvu-consumer` scaffold 已含此文件，新项目默认自带。）

**Why**：项目级信息（谁是 PM、@谁交付、新需求页归到哪个 Figma 分组）是**项目资料**——不进 memory（污染 / 跨 session 漂移），也不进跨项目 DS 真源（那里只放通用设计系统规范）。固化在消费产品这份文件里，跨 session / 跨人一致，起手必读避免每次重新问。**实证 2026-07-09**：roster + V4/V3 页面组织规则此前散落在 memory / 临时 `TEAM-ROSTER.md`，收敛进本文件。

**归属**：文件是消费产品项目资料（留消费产品侧）；本 skill 只规定"起手要读它"这个通用动作 + 由模板保证每个 consumer 都有。

---

## 演进策略

**改本 skill 的规则** → 改本文件 → plugin 更新后所有 consumer 下次 session 自动套新规则

**新增规则**：先确认是 consumer-wide 通用，不是某个 consumer 特殊情况；再加进来。

**删除规则**：先确认所有 consumer 都不再需要；migrating consumer 数据时给提示。

**反模式**：把项目特定规则塞进本 skill（污染通用规则集）。