# TVU 设计系统 · 全生命周期评估（SoT）

> **日期**：2026-07-08
> **性质**：诊断存档（只读结论，不改任何规范文件）——所有建议等 owner 逐条 ack 后才动。
> **方法**：多 subagent 并行盘点（生命周期 / 横切质量 / 前瞻三轴）+ 主线一手 `Bash`/`Read` 交叉验证关键事实。
> **定位**：本文是后续所有"设计系统全流程优化"的 SoT + 排期依据。真源仍在 AGENTS.md / meta-rules / design-process / conventions；本文是**跨这些真源合成的差距视图**，不替代它们。

---

## 0. 读前声明（方法 + 已更正的误判）

本评估经历多轮，期间**更正过三处误判**，写在最前面防止后续 session 沿用错误结论：

1. **「单测不进 CI」是错的（已撤）** — 该判断只看了 GitHub `ci.yml`。团队真源在 **Gitea**，`.gitea/workflows/pr-checks.yml` 触发在 `pull_request:[master]` + `push:[master]`，**合并前就在 PR 上跑 `vue-tsc` + `pnpm test`(vitest) + `prepublishOnly`**。单测在 CI，且 PR 自动化 gate 的基础已存在。
2. **「设计走查缺失」是错的（已更正）** — 走查有正式 gate：`skills/design-walkthrough/SKILL.md` + `docs/internal/design-process.md`(1407 行) + `pnpm design:kickoff`。
3. **「单 owner → 过滤多人团队项」是错的（已更正）** — 实际是**多人拉分支协作的企业级设计系统**，多团队项重新在 scope 内。

**证据分级**：文中标 `[验]` = 主线一手 Read/Bash 验证；`[报]` = subagent 报告、附了 file:line 但主线未逐条复核（实现前需复核，尤其代码类）。

---

## 1. 操作模型（北极星 · 来自 owner 明确定义）

| 维度 | 定义 |
|---|---|
| 性质 | 企业级设计系统，供多人使用 |
| 角色 | 一个负责人**审 PR**（把关质量，最好自动化、人只点 merge）；设计同事**拉分支维护+使用**；dev/PM **直接用**现成系统做产品设计 |
| 工具面 | Claude Code / Codex / 其他 AI / **claude.ai·Design 类设计工具** 都要能产出高质量产品设计 |
| 核心要求 | ① **质量与"用哪个工具"解耦**（不是绑 Claude Code）② 使用者**不必懂具体流程**，系统**自行触发**对应流程 ③ 设计团队成员**一看就知道如何使用** |

**派生的最高目标**：任何人 × 任何工具，都能被系统自动导进正确流程、产出高质量产品设计（code + mockup），owner 通过（尽量自动化的）PR review 把关。

---

## 2. 统一根因（三轮诊断对齐到一条）

**系统的可靠性是"双模态"的，且病根一致：**

- **有确定性机械 gate 的轴（代码保真）近乎完美**：render-verification manifest ~930 entries、双框架 29/29 `A_TRUE_DRIFT=0`、icon audits、changesets。错误假设被 gate 否决而非人工发现。
- **只有 prose / AI-skill / hook 的轴（mockup、上游分析、API 一致性、流程触发）掉到低可靠**：`rule-execution-discipline-gap` 实测 8 步流程默认命中率 **37.5%**；53 份 retrospection **≥28 份**沉淀了执行失败（已读未遵守 / 反复试 / 靠人工矫正 / declared≠consumed / 链路漏步 …）。`[报]`

**三条互相叠加的病因：**
1. **机制不对称**：流程/质量约束大多是 L1 prose（AI 必须记得+主动遵守），不是 L2 机械闸。mockup/设计侧 prose:机械闸 ≈ **73:1**，且唯一那道 mockup 闸是"查文本 `I1=pass`"的假闸。`[报]`
2. **工具耦合**：流程触发+引导全在 `.claude/`（hooks + skills）里，**Claude Code 独有**。Codex 半套、claude.ai/其他工具几乎零约束 → **质量绑工具、不绑系统**。`[验]`
3. **承诺 vs 实现落差**：PROJECT_GOAL 承诺的多项能力实现只兑现一半，AI 读了文档信以为真 → 按错误前提行动（详见 §5）。

---

## 3. 目标架构

```
              ┌──────────────────────────────────────────────┐
              │  自触发脊梁（工具无关 · 面向人和 AI）          │
              │  git hook(post-checkout/pre-push) + `ds start` │
              │  + PR/CI + README「START HERE」                │
              └──────────────────────────────────────────────┘
                                   │ 触发
   ┌──────────────┬───────────────┼───────────────┬──────────────────┐
   ▼              ▼               ▼               ▼                  ▼
 支柱①          支柱④           支柱②           支柱③              元层
 工具无关       上游理解-        双质量网         每工具            学习闭环 /
 机器可读       分析 gate       (代码 CI/PR      薄适配器          审核分诊 /
 契约          (接真源+确认+     + 设计提交       (指向同一          可观测
              强制自触发)       校验)           契约)
                                   │
                          PR review = owner 统一验收关卡（尽量自动、人只 merge）
```

- **支柱① =** 设计系统知识做成任何工具都能 ingest 的产物（npm 内机器可读组件契约：API + 组合规则 + 成熟度 status；精简可移植规则文件；Figma 库；claude-design-bundle）——不再锁在 skill/6916 行 prose 里。
- **支柱② =** 两张工具无关质量网：**代码网**（PR/CI，谁产的代码都过）+ **设计网**（Figma/托管产出的提交即校验）。
- **支柱③ =** 薄适配器：Claude Code→hooks/skills、Codex→file-based prompt、claude.ai→bundle+Project Instructions，全指向支柱①同一契约。
- **支柱④ =** 产出 code/mockup **之前**的强制上游 gate：需求复述+理解确认 → 读真源（产品 roadmap/PRD/既有 design-record/product-context）→ 竞品/persona/IA 分析（**竞品接实时检索**）→ 数据可行性 → MVP scope → user 校验。
- **元层 =** 让上面长期不烂、规模不塌、可证明：学习闭环 / 审核分诊 / 流程可观测。

---

## 4. 现状 × 差距登记（按支柱 · 修复模式 机=机制 覆=覆盖 文=文档）

### 支柱① 工具无关机器可读契约

| 缺口 | 现状/证据 | 修复 | 优先级 |
|---|---|---|---|
| API 跨组件命名散乱 + 无横向一致性 gate | size 四套大小写（Button`XS\|S\|M\|L`/Slider`M\|S`/Input`s\|m\|l\|xl`/Badge`m\|s`）；外观变体 5 个 prop 名（variant/canonicalStyle/type/property1）；`type` 语义过载；canonical 贴 Figma 反更乱 `[报]` | 机+文 | **P0** |
| 组合契约不随 npm 发布 | `component-affordances.json` 是 internal、不在 `files[]`；T4b `compositionSupport` 未落 → 外部 AI 页面级合成靠猜 `[报]` | 覆 | P1 |
| Token 分发 web-only | 只有 CSS 变量（`src/tokens/variables.css`）；exports 仅 `./style.css`、**无 TS/JSON token**；`figma-data/raw/design-tokens.tokens.json` 是输入不 publish；无 style-dictionary `[验]` | 机 | P1 |
| 精简可移植规则契约缺失 | 规则散在 6916 行（AGENTS 745 + meta-rules 807 + design-process 1407 + mockup-conv 2560 + code-conv 1397）`[验]`；claude.ai/Codex 无法当 Project Instructions 直接吃 | 覆 | P1 |

### 支柱② 双质量网（含 PR gate 现状——已更正）

| 项 | 现状/证据 | 缺口 | 优先级 |
|---|---|---|---|
| **代码网 PR gate（基础已在 Gitea）** | `.gitea/workflows/pr-checks.yml` on `pull_request`+`push[master]`：`vue-tsc`+`vitest`+`prepublishOnly`(20 audits) `[验]` | 见下 4 条 | — |
| render-drift/视觉/React 验证不在 PR | Gitea runner 无 root 装不了 chromium → 只在 release(GitHub `publish.yml`)跑 `[验]`；`tests/visual` 62 baseline 零 CI `[验]` | 视觉/fidelity 回归溜到发布才发现 | P1 |
| **consumer/集成/blast-radius 检测缺失** | CI/PR 完全不测消费方；无 E2E、无自动 consumer 集成、组件组合无 integration 测 `[验]` | DS 自测绿却把消费产品搞挂——最典型"合并后爆" | **P1** |
| API breaking 检测缺失 | 无 api-surface diff `[验]` | 破坏性变更悄悄合并、consumer 升级才爆 | P1 |
| 分支保护"必需+强制" | Gitea 仓库设置，文件里看不到——**需 owner 在 Gitea 确认/开启**"required check 全绿 + 禁直推 master 才能 merge" | 否则 gate 跑了也不拦，"绿了才 merge"没被强制 | **P1** |
| 风险分诊 | 无 `[验]` | 单人审核，需 docs-only→轻检 / src→全检 / API改→必人工 的自动分级 | P1 |
| **设计网（mockup 确定性后验）缺失** | `audit:mockup-conformance` auto-run：pre-commit=0 / ci=0 / prepublish=0；只在 `post-figma-write.sh` hook 提醒；唯一 repo 闸 `audit-mockup-handoff-evidence` 是**查文本存在性**（贴 `I1=pass` 就过）`[验/报]` | 设计产出无等价 render-verification 的确定性后验 | **P0** |
| 合并后 canary | 无 | post-merge 消费方 canary build 兜底（owner 原述"检测合并后会不会有问题"） | P2 |

### 支柱③ 每工具薄适配器

| 项 | 现状 | 缺口 | 优先级 |
|---|---|---|---|
| Claude Code | hooks(3)+skills 全套 `[验]` | —（最完整） | — |
| Codex | file-based prompt + 仓库文件，无 hooks/skills | 上游/走查/conformance 触发靠 prompt 自带 | P1 |
| claude.ai/Figma Make | `export:claude-design-bundle`（雏形，手动触发）+ npm 包 `[验]` | bundle 覆盖度未知、需补全+保鲜 | P1 |

### 支柱④ 上游理解-分析 gate

| 项 | 现状/证据 | 缺口 | 优先级 |
|---|---|---|---|
| 上游 discovery 存在 | `skills/design-discovery`：6 deliverable（含 **Market/Competitive analysis 3+**、IA、data feasibility）+ Stage 0/0.5 + M50 kickoff `[验]` | —（骨架在） | — |
| 分析不接真源、当场脑补 | 竞品/persona 照空模板 AI 编；仓库 roadmap 是 DS 自己的、非消费产品的；product-context 在 consumer 仓且未强制"先读再析" | **接真源**（产品 roadmap/PRD/design-record/product-context）+ 竞品接**实时检索**（见 §6） | **P0** |
| 触发靠 AI 自判、可跳过 | skill §1 AI 自问"要 discovery 吗"、§5 允许跳 `[验]` | 强制、工具无关自触发 | P1 |
| 缺"理解确认"关卡 | 有 No-Open-Questions 闸(触发器 P) 但那是交付物层 | 动手前**复述需求+对着真源跟 user 确认理解** | **P0** |
| 依赖：消费产品缺活的 roadmap/product-context | product-context 在 consumer 仓、roadmap 基本没有 | 每消费产品维护轻量 roadmap+product-context 供 gate 读 | P1 |

### 元层（让四支柱长期不烂）

| 项 | 现状 | 缺口 | 优先级 |
|---|---|---|---|
| 学习闭环 | retrospection→规则回流是真资产，但绑 AI/owner `[验]` | 工具无关、任何人可触发的"这里不对/新模式"回流入口，喂回契约 | P1 |
| 审核分诊 | 无 | 保护单一 PR 审核人（同支柱②分诊） | P1 |
| 流程可观测 | 无 | gate 通过率/返工率/按工具·按人分布——否则无法判断"跨工具都高质量"是否达成 | P1 |
| 跨产品方案级一致 | REQUEST-INDEX 是每产品的 | 产品设计层先例/pattern 索引 | P2 |
| 契约治理 / 逃生舱 | 图标有 LIBRARY GAP 流程 | 规则契约变更治理 + 更广的"超出 DS 时正规路径" | P2 |

### 横切质量属性 & 韧性（多团队/企业级 scope 内）

| 缺口 | 现状/证据 | 修复 | 优先级 |
|---|---|---|---|
| Bundle 性能 | vite `external` 配错（列非依赖 chart.js/vue-chartjs、漏真依赖 echarts）→ 2.1MB 主包；无 sideEffects；`cssCodeSplit:false`→96K CSS；无 size gate `[报-实现前复核]` | 机 | P1 |
| i18n 缺 + 组件硬编码英文 | Pagination `of`/`Go to`、UserMenu `Sign Out` 不可本地化；无 runtime locale 机制；RTL≈0 `[报]` | 机 | P1 |
| Motion 无体系 | 无 `--duration/--ease` token；12 组件硬编码 transition(0.12–0.3s 散乱)`[报]` | 机+覆 | P1/P2 |
| 微文案中央层无 | 有词库；无中央 microcopy/i18n、无 voice/tone·大小写·标点规范 `[报]` | 文+机 | P2 |
| 主题多品牌/白标 | dark/light 三层 token 完整；仅两套、无扩展点、无 `useTheme` `[报]` | 机 | P2 |
| 图标规模化 | 644 图标、命名规范+audit+tree-shakable ESM 强；`audit:icon-canonical-names` 未进 prepublish、worklist 非自动 `[报]` | 机 | P2 |
| 依赖/供应链 | 无漏洞扫描/dependabot/license/SBOM `[报]` | 机 | P2 |
| 发布产物完整性 | 无 publint/attw/pack 内容 gate（v0.6.0 漏 scripts 修了个例未立 gate）`[报]` | 机 | P2 |
| 回滚/hotfix/事故 runbook | RELEASING.md 无"发坏了怎么办" `[报]` | 文 | P2 |
| 响应式 scope 未声明 | 0 `@media` in src，硬编码固定尺寸；未写死 desktop-first `[报]` | 文 | P2 |
| docs 站单版本 · RC 通道未启用 · 采用度量/blast-radius 索引无 · 组件成熟度分级无 · CODEOWNERS/SUPPORT/ACCESSIBILITY 文档无 · issue 模板无(`.github/ISSUE_TEMPLATE` 缺) | 多团队 scope 内，但排在脊梁/契约/网之后 `[验/报]` | 覆/文 | P2 |

---

## 5. 承诺 vs 实现 落差清单（"看起来有其实没有"，最坑 AI）

| PROJECT_GOAL 承诺 | 实现真相 `[验]` |
|---|---|
| npm 装了可用 **TS Token** | 只有 CSS 变量，无 TS token 出口 |
| **双框架 Vue+React** | React 未进 npm `files[]`（仅 dist=Vue）、仅 `react-pilot/` + docs 演示 + INFRA-F43 slot 投影 bug 未修 → "已成"是演示层非产物层 |
| AI 多模态输入→**生成** UX 效果图+代码（能力4） | 实为合规**守门**（gate），非生成器；靠 AI 人肉合成 |
| 四角色文档站（含产品 Use Cases） | Use Cases **0/34**、Design Spec **1/34**、Status Matrix 9/34 → 实为开发+QA 双角色站 |
| 组件可合成**页面级**输出（T4b） | 组合契约锁在 internal，不随包发 |
| 能力 3 code→Figma | bypass（Figma Pro plan 限制），手工维护 translation 映射 |

> 处理原则：这些**要么补实现、要么改 PROJECT_GOAL 措辞对齐**，别让 AI 继续按错误承诺行动。

---

## 6. 竞品分析接入方式（已验证可实时检索）

- **主线可实时联网检索**（WebSearch / `deep-research` skill），**不需人给竞品名**，给种子只加速。
- 已实测：TVU 同类真实竞品 = **LiveU / Dejero / Grabyo / Teradek / QuickLink / Cingularity**（来源：tvunetworks.com/alternatives、cbinsights、tracxn）。
- 落地：支柱④竞品步 = **实时+引用来源**（非脑补表格）；缓存成每产品一份 `competitive-intel.md` 定期刷新，避免每需求全网重跑；深度 UX 拆解单产品可能仍需产品访问权限。

---

## 7. 待 owner 决策的架构分叉

1. **设计产出入口在哪** → 决定"设计网"形态：主要在仓库/命令行 → git+CLI 路由够；主要在 Figma → 脊梁要延伸到 Figma 侧（插件/文件内 checklist），另一量级工作。
2. **owner-direct-master vs PR-for-all** → 要"人只 merge"，需把实质改动都走 PR + 分支保护；与现有 owner-direct-master 默认冲突，owner 定夺（建议：实质改动走 PR、trivial 保留 fast-lane）。
3. **Gitea runner 无 root（装不了 chromium）** → 视觉/render-drift 上 PR 的方案：给 runner 装依赖 / GitHub 镜像仓 PR 跑 / 接受 release-time。

---

## 8. 建议排期（最高杠杆先 · 均等 owner ack）

1. **支柱④ 上游理解-分析 gate + 支柱① 契约补全**（最高杠杆）：治"没理解需求就返工" + 让任何工具产出前有可预测契约。含：需求确认关卡、竞品接实时检索、API 一致性 + 横向 gate、组合契约/TS token 随包发。
2. **支柱② 代码网补全**：扩 `.gitea/pr-checks.yml`（+consumer 冒烟 +API-diff）、Gitea 开分支保护、视觉/render 上 PR、风险分诊。→ 实现"自动审 PR、人只 merge、合并前就知道会不会出问题"。
3. **支柱② 设计网（缺口 A）**：mockup conformance 从"hook 提醒"升为"产出后强制自动跑 + 报告防伪"，堵 `I1=pass` 粘贴洞。
4. **支柱③ 适配器 + 元层**：补全 claude-design-bundle、Codex 协议对齐；学习闭环/可观测埋点。
5. **横切/韧性 P1**：bundle external bug、i18n 硬编码英文、consumer 集成测。

---

## 附录 A：一手验证事实清单（供后续 session 免重复考据）

- Gitea `pr-checks.yml`：`on: pull_request:[master] + push:[master]`；跑 vue-tsc + vitest + prepublishOnly `[验]`
- GitHub `ci.yml`(push:master paths) / `publish.yml`(tags, render-gate+a11y) / `stale-anchors.yml`；**无 pull_request** `[验]`
- `prepublishOnly` = 20 个 audit，**不含 vitest** `[验]`；`.husky/pre-commit` 跑 vitest+audits（可 `--no-verify` 绕）`[验]`
- `.claude/hooks/`：onboarding-checklist / detect-figma-task / post-figma-write（Claude Code 专属，注入文本不拦截）`[验]`
- token：`src/tokens/variables.css` CSS 变量；exports 仅 `./style.css`；无 TS/JSON token `[验]`
- 文档站三视图：Use Cases 0/34、Design Spec 1/34、Status Matrix 9/34 `[验]`
- `skills/design-discovery`(竞品/IA/data audit)、`skills/design-walkthrough`、`design-process.md`(1407 行) `[验]`
- `CONTRIBUTING.md`(78) / `.gitea/PULL_REQUEST_TEMPLATE.md` 存在；`.github/ISSUE_TEMPLATE`/CODEOWNERS/SUPPORT/ACCESSIBILITY/adoption 缺 `[验]`
- 待实现前复核（subagent 报告的代码类）：vite external echarts bug、API 命名 file:line、motion 硬编码、bundle 2.1MB、73:1 比例、≥28/53 复发数

## 附录 B：规模校准

本项目 = **单 owner 审 PR + 多人拉分支协作**的企业级 DS。多团队协作项在 scope 内，但**排在"自触发脊梁 + 契约 + 质量网 + 上游 gate"之后**——不因"企业级"就把公开库的全套卫生项（SBOM/docs 多版本/多品牌主题/RTL）提前，按真实使用循环 ROI 排。
</content>
</invoke>