universal-dev-standards 5.1.0-beta.7 → 5.1.0

package/bundled/locales/zh-CN/core/frontend-design-standards.md

@@ -0,0 +1,289 @@
+---
+source: ../../../core/frontend-design-standards.md
+source_version: 1.0.0
+translation_version: 1.0.0
+last_synced: 2026-04-20
+status: current
+---
+
+# 前端设计标准
+
+> **语言**: [English](../../../core/frontend-design-standards.md) | 简体中文
+
+**版本**: 1.0.0
+**最后更新**: 2026-04-13
+**状态**: Active
+**适用范围**: 所有具备前端用户界面的项目
+**参考**: DEC-029（awesome-design-md, MIT）、DEC-030（OpenAI Frontend Guide）
+
+---
+
+## 目的
+
+本标准定义一套机器可读的前端设计规格格式（DESIGN.md），用于 AI 辅助开发。建立 9 段式 DESIGN.md 结构、强制设计 token 词汇、UI 硬性约束，以及反模式拒绝规则。
+
+目标是通过结构化设计约束（而非自由形式的风格描述）确保 AI Agent 在不同执行情境下产生一致、高质量的 UI。
+
+**核心原则**：
+- DESIGN.md 是设计规格的唯一真实来源
+- 语义化 token 命名（框架无关）
+- 约束式提示：自由度越少 = UI 质量越高
+- 与源代码同步进行版本控制
+
+---
+
+## DESIGN.md 结构
+
+DESIGN.md 是放在项目根目录的 Markdown 文件，作为机器可读的设计规格书。使用结构化 Markdown，人类与 AI Agent 皆可读取。
+
+```
+传统方式：Figma 设计稿 → 人类开发者 → 代码
+新方式：DESIGN.md → AI Agent → 代码
+
+DESIGN.md = 给 AI 读的设计规格书
+  - 人类可读（Markdown 格式）
+  - AI 可消费（结构化纯文本）
+  - 版本控制友好（放在 repo 根目录）
+  - 与代码同步演进
+```
+
+### 必填段落
+
+完整的 DESIGN.md 必须依序包含全部 9 个段落：
+
+| # | 段落键值 | 必填 | 说明 |
+|---|---------|------|------|
+| 1 | `visual-theme` | 是 | 整体风格与氛围定义 |
+| 2 | `color-palette` | 是 | 语义色彩 token 与 hex 值 |
+| 3 | `typography` | 是 | 字体家族与字体层级角色 |
+| 4 | `component-styling` | 是 | UI 组件的视觉规则 |
+| 5 | `layout-spacing` | 是 | 间距尺度与网格定义 |
+| 6 | `depth-shadow` | 是 | 层次感与阴影系统 |
+| 7 | `design-guidelines` | 是 | 设计规则与反模式清单 |
+| 8 | `responsive` | 是 | 断点与响应式规则 |
+| 9 | `agent-prompt-refs` | 是 | AI 可消费的设计意图摘要 |
+
+---
+
+## 第 1 段：视觉主题与氛围
+
+**目的**：定义产品的整体美学意图。AI Agent 在生成 UI 时以此作为高层次约束。
+
+**必填字段**：
+- `theme`: 单行风格描述（如「极简、专业、数据密集」）
+- `mood`: 情感品质（如「沉稳、专注、可信赖」）
+- `inspiration`: 参考产品或设计流派（如「Linear、Stripe dashboard」）
+- `dark-mode`: 深色模式是 primary / secondary / 不支持
+
+---
+
+## 第 2 段：色彩系统
+
+**目的**：定义完整的语义色彩系统。所有颜色以语义 token 表示，不直接在代码中使用原始 hex 值。
+
+**必填**：全部 5 个语义 token（见[语义色彩 Token](#语义色彩-token)）
+
+**选填**：状态扩展 token（error、warning、success、info）、border、overlay。
+
+---
+
+## 第 3 段：字体系统
+
+**目的**：定义字体家族与字体层级角色。约束 AI 最多使用 2 个字体家族。
+
+**必填**：全部 4 个字体角色定义（见[字体角色](#字体角色)）
+
+**约束**：最多 2 个字体家族（display + body）。使用 3 个以上属反模式。
+
+---
+
+## 第 4 段：组件样式
+
+**目的**：定义常见 UI 组件（按钮、卡片、输入框、徽章）的视觉规则。
+
+**必填字段**：
+- 圆角尺度
+- 按钮变体（primary、secondary、ghost）
+- 输入框样式
+- 卡片 / surface 样式
+
+---
+
+## 第 5 段：版面与间距
+
+**目的**：定义间距尺度与网格系统。以 8px 基础网格，定义 7 个间距步骤。
+
+**必填**：标准尺度的全部 7 个间距步骤（见[间距尺度](#间距尺度)）
+
+---
+
+## 第 6 段：层次感与阴影系统
+
+**目的**：以阴影定义高度层次感，不依赖颜色建立视觉层级。
+
+**必填**：至少 3 个高度层级。
+
+---
+
+## 第 7 段：设计准则与反模式
+
+**目的**：对 AI Agent 明确列出规则和禁止的 UI 模式。此段落是约束式提示的主要机制。
+
+**必填子段落**：
+1. UI 硬性约束（≥4 条规则）
+2. 反模式清单（≥5 个禁止模式）
+
+---
+
+## 第 8 段：响应式行为
+
+**目的**：定义断点与响应式规则。必须采用 Mobile-first 做法。
+
+**必填**：至少 3 个断点（mobile、tablet、desktop）。
+
+---
+
+## 第 9 段：Agent 提示参考
+
+**目的**：设计意图的精简 AI 最优化摘要。AI Agent 应先读此段作快速定向，再查阅其他段落。
+
+**必填字段**：
+- `style-summary`: 1–2 句设计意图
+- `key-constraints`: 最关键规则的列表
+- `tone`: 设计带给用户的「感受」
+
+---
+
+## 语义色彩 Token
+
+每个 DESIGN.md **必须**定义以下 5 个语义色彩 token。它们与框架无关，必须使用这些精确名称。
+
+| Token | 角色 | 对应示例 |
+|-------|------|---------|
+| `background` | 页面 / App 背景 | `#0A0A0A`（深色）/ `#FFFFFF`（浅色）|
+| `surface` | 卡片、面板、Modal | `#1A1A1A`（深色）/ `#F9FAFB`（浅色）|
+| `primary-text` | 主要正文 | `#F5F5F5`（深色）/ `#111827`（浅色）|
+| `muted-text` | 次要文字、placeholder | `#888888`（深色）/ `#6B7280`（浅色）|
+| `accent` | CTA 按钮、链接、强调 | `#6366F1`（靛蓝示例）|
+
+**规则**：
+- Token 名称为 kebab-case，必须完全相符
+- 每个 token 必须定义 hex 值
+- `accent` 必须是单一颜色，禁止多个强调色
+- 扩展 token（error、warning、success）为选填，但必须遵循相同命名模式
+
+---
+
+## 字体角色
+
+每个 DESIGN.md **必须**定义以下 4 个字体角色：
+
+| 角色 | 大小 | 字重 | 行高 | 用途 |
+|------|------|------|------|------|
+| `display` | 48px+ | 700 | 1.1 | 英雄标题、展示文字 |
+| `headline` | 24–32px | 600 | 1.3 | 段落标题、卡片标题 |
+| `body` | 16px | 400 | 1.6 | 段落、主要内文 |
+| `caption` | 12–14px | 400 | 1.4 | 标签、Metadata、辅助文字 |
+
+**规则**：
+- 角色名称为小写，必须完全相符
+- 4 个角色最多使用 2 个字体家族
+- 字体大小为最小值，响应式缩放可接受
+
+---
+
+## 间距尺度
+
+标准间距尺度以 8px 基础网格，定义 7 个命名步骤：
+
+| Token | 值 | 用途 |
+|-------|-----|------|
+| `space-1` | 4px | 图标内距、紧凑元素 |
+| `space-2` | 8px | 默认元素内距 |
+| `space-3` | 16px | 组件内部间距 |
+| `space-4` | 24px | 段落内距、Gutter |
+| `space-5` | 32px | 组件之间 |
+| `space-6` | 48px | 主要段落之间 |
+| `space-8` | 64px | 页面级别分隔 |
+
+**规则**：
+- 所有代码中的间距必须使用这些步骤 token，不得使用任意 px 值
+- `space-7` 刻意跳过（直接跳到 space-8=64px 维持视觉节奏）
+
+---
+
+## UI 硬性约束
+
+| 约束 | 规则 | 理由 |
+|------|------|------|
+| H1 数量 | 每页最多 1 个 H1 | 清晰内容层级 |
+| 段落数量 | 每页最多 6 个段落 | 防止认知过载 |
+| 字体家族 | 最多 2 个字体家族 | 视觉一致性 |
+| 强调色 | 最多 1 个强调色 | 防止视觉噪音 |
+| 嵌套深度 | 最多 3 层视觉嵌套 | 可读性 |
+| 信息层级 | Hero → Support → Detail → CTA | 叙事结构 |
+| 触控目标 | 移动端最小 44×44px | 无障碍设计 |
+
+---
+
+## 反模式
+
+以下 UI 模式为**禁止**。AI Agent 在生成前端代码或设计规格时必须拒绝这些模式。
+
+| 反模式 | 说明 | 建议替代方案 |
+|--------|------|------------|
+| `floating-badge` | 与内容脱离的浮动徽章 | 行内标签或状态指示器 |
+| `generic-card-layout` | 以完全相同的卡片堆叠作为主要内容 | 有清晰层级的多元内容结构 |
+| `dashboard-grid-as-homepage` | 营销首页看起来像数据 dashboard | Hero → Support → CTA 叙事首页 |
+| `competing-ctas` | 同一画面出现视觉权重相同的多个 CTA | 一个 primary CTA，零或一个 secondary CTA |
+| `color-only-differentiation` | 仅用颜色传达状态或类别 | 搭配图标、图案或文字标签 |
+| `decorative-overload` | 不传递信息的插图或动画 | 移除装饰性元素；偏好功能性视觉 |
+| `triple-nesting` | 视觉层级超过 3 层 | 扁平化结构；以留白作分隔 |
+| `rainbow-accents` | 多个强调/高亮色 | 单一强调色系统 |
+
+每个 DESIGN.md 的第 7 段必须明确列出至少 5 个反模式。
+
+---
+
+## DESIGN.md 文件位置
+
+DESIGN.md 必须放在**项目根目录**，与 README.md 同层。
+
+**规则**：
+- 文件名：`DESIGN.md`（大小写必须完全相符）
+- 位置：仅在项目根目录（不在 `docs/`、`src/` 或子目录）
+- 格式：使用 `##` 级别段落标题的 Markdown
+- 版本：文档标题包含版本字段
+- 更新策略：设计 token 变更时 DESIGN.md 必须同步更新；视为代码，而非文档
+
+---
+
+## 验证清单
+
+### 结构
+- [ ] 全部 9 个段落依序存在
+- [ ] 文件位于项目根目录（与 README.md 同层）
+- [ ] 文件名精确为 `DESIGN.md`
+
+### 色彩系统（第 2 段）
+- [ ] 定义了全部 5 个语义 token：`background`、`surface`、`primary-text`、`muted-text`、`accent`
+- [ ] 所有 token 都有 hex 值
+- [ ] 只定义了 1 个强调色
+
+### 字体系统（第 3 段）
+- [ ] 定义了全部 4 个角色：`display`、`headline`、`body`、`caption`
+- [ ] 最多使用 2 个字体家族
+
+### 间距（第 5 段）
+- [ ] 定义了全部 7 个间距步骤：space-1 到 space-8（无 space-7）
+- [ ] 值符合 8px 基础尺度
+
+### 设计准则（第 7 段）
+- [ ] 列出至少 4 条 UI 硬性约束
+- [ ] 列出至少 5 个反模式
+- [ ] 明确禁止 `floating-badge`、`generic-card-layout`、`dashboard-grid-as-homepage`
+
+### Agent 提示参考（第 9 段）
+- [ ] 风格摘要存在（1–2 句）
+- [ ] 关键约束列表存在
+- [ ] 氛围（tone）已定义

package/bundled/locales/zh-CN/core/health-check-standards.md

@@ -0,0 +1,144 @@
+---
+source: ../../../core/health-check-standards.md
+source_version: 1.0.0
+translation_version: 1.0.0
+last_synced: 2026-04-20
+status: current
+---
+
+# 健康检查标准
+
+> **语言**: [English](../../../core/health-check-standards.md) | 简体中文
+
+**版本**: 1.0.0
+**最后更新**: 2026-04-17
+**状态**: Trial（到期 2026-10-17）
+**适用范围**: universal
+**来源**: XSPEC-067（DEC-043 Wave 1 可靠性套件）
+
+---
+
+## 目的
+
+健康检查标准：liveness / readiness / startup 三种 probe、深度 health check、结构化 JSON 响应。
+
+业界常见错误：把 liveness 和 readiness 混用（健康检查检查外部依赖导致连锁重启）。本标准明确三种 probe 语义分离，定义深度 health check 的检查范围（仅关键依赖），并规范结构化 JSON 响应以便下游自动化处理。
+
+---
+
+## 核心规范
+
+- Liveness probe 不得检查外部依赖（DB、下游 API），否则会造成连锁重启
+- Readiness probe 可检查关键外部依赖，但仅关键（非全部依赖）
+- 慢启动服务应使用 startup probe，启动完成后交棒给 liveness
+- Health check 端点必须回传结构化 JSON，包含 status / dependencies / timestamp
+- Health check 结果应作为 observability 的 Error signal 之一，连续 fail 触发 incident
+
+---
+
+## 三种 Probe 类型
+
+### Liveness Probe
+
+- **目的**：服务是否还存活（process 是否卡死）
+- **建议端点**：`GET /health/live`
+- **允许检查**：process 是否能响应 HTTP、内部 event loop 是否可用
+- **禁止检查**：DB 连接、下游 API、消息队列（会造成连锁重启）
+- **失败行为**：重启 pod / process
+- **参数**：failureThreshold=3，periodSeconds=10
+
+### Readiness Probe
+
+- **目的**：是否可接收流量
+- **建议端点**：`GET /health/ready`
+- **允许检查**：自身 API 可用、DB 连接（若服务必须依赖 DB）、关键下游依赖、必要配置已加载
+- **禁止检查**：非关键依赖（避免非关键故障造成服务被移出负载均衡）
+- **失败行为**：移出负载均衡，不重启
+- **参数**：failureThreshold=3，periodSeconds=5
+
+### Startup Probe
+
+- **目的**：启动期专用，替代慢启动服务的 liveness
+- **建议端点**：`GET /health/startup`
+- **检查项目**：启动过程所需资源（如缓存预热、index 加载）已完成
+- **失败行为**：重启 pod（启动超时）
+- **完成后**：停用，改由 liveness 接手
+- **参数**：failureThreshold=30，periodSeconds=10
+
+---
+
+## 深度规则
+
+| 层级 | 使用时机 | 检查范围 |
+|------|---------|---------|
+| Shallow | Liveness | process 是否可响应，不碰任何外部依赖 |
+| Deep | Readiness | 自身 API 路由、DB ping（若必须）、关键下游 API ping |
+
+**关键依赖的定义**：没有它服务就完全无法提供核心功能。
+
+---
+
+## 响应格式
+
+**Content-Type**：`application/json`
+
+| HTTP 状态码 | 含义 |
+|------------|------|
+| `200` | healthy — 所有关键依赖正常 |
+| `503` | unhealthy — 至少一个关键依赖失败 |
+
+**JSON Schema**：
+
+```json
+{
+  "status": "healthy | degraded | unhealthy",
+  "timestamp": "<ISO-8601>",
+  "uptime_seconds": 12345,
+  "version": "1.0.0",
+  "dependencies": {
+    "database": {
+      "status": "healthy | unhealthy",
+      "latency_ms": 5,
+      "last_check": "<ISO-8601>"
+    },
+    "upstream_api": {
+      "status": "healthy | unhealthy",
+      "latency_ms": 20
+    }
+  }
+}
+```
+
+---
+
+## 与 Observability 整合
+
+- Health check 结果应作为 RED metric 的 Error 来源之一（Rate / Errors / Duration）
+- 连续 N 次 health check failed 应触发 incident（对齐 incident-response）
+- probe 延迟本身应被监控（异常缓慢可能是 resource_exhaustion 征兆）
+
+---
+
+## 情境示例
+
+**情境 1：liveness 不检查 DB**
+- 条件：DB 暂时无法连接
+- Liveness 回传 200 healthy（不检查 DB），避免连锁重启
+
+**情境 2：readiness 因关键依赖失败**
+- 条件：关键下游 API 不可达
+- Readiness 回传 503，pod 移出负载均衡但不重启
+
+**情境 3：startup 后交棒 liveness**
+- 条件：服务需 60s 预热缓存
+- 前 60s startup probe 持续回 503，预热完成后交棒 liveness
+
+---
+
+## 错误码
+
+| 代码 | 说明 |
+|------|------|
+| `HC-001` | `HEALTH_CHECK_FAILED` — 关键依赖失败 |
+| `HC-002` | `HEALTH_CHECK_TIMEOUT` — probe 本身超时 |
+| `HC-003` | `INVALID_DEPENDENCY_SET` — readiness 检查了非关键依赖（设计违规）|

package/bundled/locales/zh-CN/core/immutability-first.md

@@ -0,0 +1,96 @@
+---
+source: ../../../core/immutability-first.md
+source_version: 1.0.0
+translation_version: 1.0.0
+last_synced: 2026-04-20
+status: current
+---
+
+# 不可变性优先原则
+
+> **语言**: [English](../../../core/immutability-first.md) | 简体中文
+
+**版本**: 1.0.0
+**最后更新**: 2026-04-17
+**状态**: Trial（到期 2026-10-17）
+**适用范围**: universal
+**来源**: XSPEC-068（DEC-043 Wave 1 可靠性套件）
+
+---
+
+## 目的
+
+不可变性优先原则：DTO 字段 readonly，防止并发 Agent 竞态条件。
+
+多个 Agent 并发执行时，共享状态的可变对象容易产生竞态条件（race condition）。本标准要求所有跨 Agent 边界传递的数据对象（DTO）默认使用 readonly 字段，并提供安全修改的替代模式（返回新实例而非原地修改）。
+
+---
+
+## 核心规范
+
+- 所有 DTO（Data Transfer Object）字段默认必须声明为 `readonly`
+- 跨 Agent 边界传递的对象必须是不可变的（immutable）
+- 需要修改时，必须返回新实例（而非原地修改）
+- 深层嵌套对象的所有层级都必须是 readonly
+- 集合（数组/Map）使用 `ReadonlyArray` / `ReadonlyMap`
+
+---
+
+## IMM 规则
+
+| 规则 | 说明 |
+|------|------|
+| `IMM-001` | DTO 所有字段声明为 `readonly` |
+| `IMM-002` | 嵌套对象使用 `Readonly<T>` 递归包装 |
+| `IMM-003` | 数组使用 `ReadonlyArray<T>` 而非 `T[]` |
+| `IMM-004` | 禁止对跨 Agent 边界的对象使用原地修改（`push`、`splice`、直接赋值）|
+| `IMM-005` | 需要修改时，使用展开运算符（spread）返回新实例 |
+
+---
+
+## TypeScript 示例
+
+```typescript
+// 正确：不可变 DTO
+interface TaskResult {
+  readonly taskId: string;
+  readonly status: 'succeeded' | 'failed';
+  readonly outputs: ReadonlyArray<string>;
+  readonly metadata: Readonly<Record<string, unknown>>;
+}
+
+// 正确：通过展开运算符创建新实例
+function updateStatus(result: TaskResult, newStatus: TaskResult['status']): TaskResult {
+  return { ...result, status: newStatus };
+}
+
+// 错误：原地修改（违反 IMM-004）
+// result.status = 'succeeded'; // TypeScript 会报错
+```
+
+---
+
+## 情境示例
+
+**情境 1：并发 Agent 读取同一 DTO**
+- 条件：两个 Agent 并发读取 `TaskResult` 对象
+- 结果：因为字段是 readonly，无需加锁，不存在竞态条件
+
+**情境 2：需要更新状态**
+- 条件：Agent A 需要将 `TaskResult.status` 从 `failed` 改为 `succeeded`
+- 结果：通过 `{ ...result, status: 'succeeded' }` 返回新对象，不修改原始对象
+
+**情境 3：集合操作**
+- 条件：需要向 `outputs` 数组添加新元素
+- 结果：`{ ...result, outputs: [...result.outputs, newOutput] }`
+
+---
+
+## 错误码
+
+| 代码 | 说明 |
+|------|------|
+| `IMM-001` | `MUTABLE_DTO_FIELD` — DTO 字段缺少 readonly 声明 |
+| `IMM-002` | `MUTABLE_NESTED_OBJECT` — 嵌套对象未使用 Readonly 包装 |
+| `IMM-003` | `MUTABLE_ARRAY` — 使用可变数组而非 ReadonlyArray |
+| `IMM-004` | `IN_PLACE_MUTATION` — 对跨 Agent 边界对象执行原地修改 |