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

package/bundled/locales/zh-CN/core/skill-standard-alignment-check.md

@@ -0,0 +1,112 @@
+---
+source: ../../../core/skill-standard-alignment-check.md
+source_version: 1.0.0
+translation_version: 1.0.0
+last_synced: 2026-04-20
+status: current
+---
+
+# Skill-Standard 对齐检查标准
+
+> **语言**: [English](../../../core/skill-standard-alignment-check.md) | 简体中文
+
+**版本**: 1.0.0
+**最后更新**: 2026-04-17
+**状态**: Trial（到期 2026-10-17）
+**适用范围**: universal
+**来源**: XSPEC-070（DEC-043 Wave 1 治理 Meta 套件）
+
+---
+
+## 目的
+
+Skill 必有 Standard 作为锚点，Standard 可无 Skill；定期识别孤儿 Skill。
+
+Skill 是 UX 糖衣，Standard 是 standards-of-truth。若 Skill 无锚定 Standard，其行为就没有明文依据，会随作者口味漂移。本标准规范 Skill 必须指明锚定哪个 Standard，并定期识别「孤儿 Skill」（无对应 Standard），触发补 Standard 的流程。反向允许 Standard 无 Skill（不强制每个 Standard 都造 Skill）。
+
+---
+
+## 核心规范
+
+- 所有 Skill 必须在 frontmatter 指明 `anchor_standard`（至少一个）
+- `anchor_standard` 必须指向 Trial / Active / Deprecated 状态的标准 id
+- Skill 无 `anchor_standard` 视为 orphan，必须在下一版补上或降级为 Proposed
+- Standard 无对应 Skill 是合法的（Standard 可独立存在，Skill 仅为 UX 加速）
+- 定期（建议季度）执行 alignment check，产出孤儿 Skill 清单
+
+---
+
+## 对齐规则
+
+### Skill 必须有 Standard
+
+- **规则**：Skill 的 frontmatter 必须包含 `anchor_standard` 字段
+- **格式**：`anchor_standard: <standard-id>` 或 `[<standard-id-1>, <standard-id-2>, ...]`
+- **强制执行**：CI / pre-release check，缺字段视为 fail
+- **例外**：纯 utility Skill（如 docs-generator）可标记 `anchor_standard: none` + 填 `utility_reason`
+
+### Standard 不必有 Skill
+
+- **规则**：Standard 是否有对应 Skill 不强制
+- **理由**：Standard 是 standards-of-truth，可被 QualityGate / Agent 直接消费；强制每 Standard 都造 Skill 会导致 Skill 库膨胀
+- **范例**：`immutability-first` 标准无对应 Skill — 合法
+
+### 孤儿 Skill 检测
+
+- 没有 `anchor_standard` 的 Skill 视为 orphan
+- **检测后行动**：
+  1. 列入季度报告
+  2. 建立对应 Standard 的 XSPEC（循 admission-criteria 流程）
+  3. 若无法建立 Standard，降 Skill 为 Proposed 直到有锚点
+
+---
+
+## 2026-04 已知孤儿 Skill 清单
+
+| Skill ID | 所需 Standard |
+|----------|--------------|
+| `slo-assistant` | slo-standards（XSPEC-063 规划中） |
+| `runbook-assistant` | runbook-standards（XSPEC-064 规划中） |
+| `incident-response-assistant` | incident-response-standards（XSPEC-063 规划中） |
+| `observability-assistant` | observability-standards（XSPEC-063 规划中） |
+| `metrics-dashboard-assistant` | metrics-dashboard-standards（XSPEC-063 规划中） |
+| `ci-cd-assistant` | ci-cd-standards（XSPEC-066 规划中） |
+
+清单将随 XSPEC-063~069 实现逐步清空。
+
+---
+
+## 对齐检查工作流程
+
+1. 扫描 `skills/**/*.md` 提取 frontmatter `anchor_standard`
+2. 扫描 `ai/standards/*.ai.yaml` 提取所有 `standard.id`
+3. 计算差集：Skill without anchor_standard → orphan 清单
+4. 计算反向差集：Standard without Skill → informational（非错误）
+5. 若 `anchor_standard` 指向不存在的 id 或已 Archived 的 id → 错误
+6. 输出 `alignment-report.json` / `alignment-report.md`（含孤儿清单、broken anchor 清单）
+
+---
+
+## 遥测事件
+
+**`alignment_check_run`**
+
+| 字段 | 类型 |
+|------|------|
+| `total_skills` | `number` |
+| `total_standards` | `number` |
+| `orphan_skills_count` | `number` |
+| `broken_anchors_count` | `number` |
+| `standalone_standards_count` | `number` |
+| `timestamp` | `string` |
+
+---
+
+## 错误码
+
+| 代码 | 说明 |
+|------|------|
+| `ALIGN-001` | `SKILL_MISSING_ANCHOR` — Skill frontmatter 缺 anchor_standard |
+| `ALIGN-002` | `BROKEN_ANCHOR` — anchor_standard 指向不存在的 standard id |
+| `ALIGN-003` | `ARCHIVED_ANCHOR` — anchor_standard 指向已 Archived 的标准 |
+| `ALIGN-004` | `UTILITY_MISSING_REASON` — utility Skill 标 anchor_standard=none 但缺 utility_reason |

package/bundled/locales/zh-CN/core/standard-admission-criteria.md

@@ -0,0 +1,104 @@
+---
+source: ../../../core/standard-admission-criteria.md
+source_version: 1.0.0
+translation_version: 1.0.0
+last_synced: 2026-04-20
+status: current
+---
+
+# 标准纳入条件
+
+> **语言**: [English](../../../core/standard-admission-criteria.md) | 简体中文
+
+**版本**: 1.0.0
+**最后更新**: 2026-04-17
+**状态**: Trial（到期 2026-10-17）
+**适用范围**: universal
+**来源**: XSPEC-070（DEC-043 Wave 1 治理 Meta 套件）
+
+---
+
+## 目的
+
+新标准纳入 UDS 的四项条件。在 DEC-043 提出 60+ 候选新标准的背景下，需要一个明文的纳入检查清单，避免标准库膨胀（重叠、未使用）与降低品质。本标准是 UDS 的治理层 meta 标准 — 用来「决定标准的标准」。每个候选新标准必须通过四项条件才能从 Proposed 进入 Trial。
+
+---
+
+## 核心规范
+
+- **四项硬性条件**：所有候选新标准必须同时通过 Evidence / Scope / Non-overlapping / AI-executable
+- **拒绝理由必须具体**：不得以「不合适」之类笼统用词结案，必须指出未通过的 criterion
+- **Admission ≠ Active**：通过 admission 仅代表可进 Trial，不代表直接 Active
+- **Self-applicability**：本标准也必须符合四项条件
+- **Backward compat**：既有 66 个 Active 标准不溯及既往
+
+---
+
+## 四项条件
+
+### 1. Evidence（具体场景）
+
+至少 2 个具体使用场景（非 hypothetical）：
+
+- 场景来自实际项目、Repo、论文或 DEC 记录
+- 描述具体（可举出文件 / 函数 / commit）
+- 至少 1 个来自 AsiaOstrich 内部痛点或外部产业佐证
+
+**拒绝示例**：「未来可能用到」— 无具体场景
+
+### 2. Scope（明确作用域）
+
+- `meta.scope` 标示 `universal` / `partial` / `uds-specific`
+- frontmatter 列出适用的活动类型（development / deployment / testing）
+- 若为 partial 或 uds-specific，说明不通用的原因
+
+**拒绝示例**：「所有场合都适用」— 过度泛化
+
+### 3. Non-overlapping（无重大重叠）
+
+与既有 UDS 标准内容重复 < 30%：
+
+- 列出最接近的 3 个既有标准，说明差异
+- 若有 ≥ 30% 重叠，应改为扩充既有标准
+- 明确定义 `integration_points`
+
+**拒绝示例**：与 `retry-standards` 80% 内容重复 — 应合并
+
+### 4. AI-executable（AI 可消费）
+
+至少一个 DevAP QualityGate / VibeOps Agent prompt / Skill 能消费：
+
+- 定义清楚的 guidelines（每条可验证）
+- 至少 2 个 Given-When-Then scenarios
+- 需类型时提供 interface / types 块
+- 明确的 `integration_points`
+
+**拒绝示例**：只有抽象原则，无任何 AI 可执行的规则
+
+---
+
+## 拒绝协议
+
+1. 拒绝理由必须指出未通过的 criterion（evidence / scope / non-overlapping / ai-executable）
+2. 拒绝记录写入 `cross-project/decisions/` 或 DEC 的 rejection log
+3. 候选者可依理由修正后重新申请（不永久封锁）
+4. 若拒绝理由涉及重叠，应建议改为扩充既有标准
+
+---
+
+## 情境示例
+
+- **情境 1 — 通过**：`retry-standards` 申请。Evidence（XSPEC-067 Scenario 1-1/1-2）、Scope（universal）、Non-overlapping（与 circuit-breaker 互补）、AI-executable（9 guidelines + 3 scenarios）全通过 → 进入 Trial
+- **情境 2 — 因重叠拒绝**：`advanced-retry-with-jitter` 申请。与 `retry-standards` 重叠 > 30% → 拒绝，建议改为 Phase 2 扩充
+- **情境 3 — 因证据不足拒绝**：`universal-best-practices` 申请。仅「未来可能用到」类描述 → 拒绝，要求至少 2 个已发生案例
+
+---
+
+## 错误码
+
+| 代码 | 说明 |
+|------|------|
+| `ADMISSION-001` | `MISSING_EVIDENCE` — 未提供至少 2 个具体使用场景 |
+| `ADMISSION-002` | `SCOPE_UNDEFINED` — 未定义 meta.scope 或适用活动类型 |
+| `ADMISSION-003` | `OVERLAP_EXCEEDED` — 与既有标准重叠 > 30% |
+| `ADMISSION-004` | `NOT_AI_EXECUTABLE` — 无任何 AI 可消费的规则或 scenarios |

package/bundled/locales/zh-CN/core/standard-lifecycle-management.md

@@ -0,0 +1,116 @@
+---
+source: ../../../core/standard-lifecycle-management.md
+source_version: 1.0.0
+translation_version: 1.0.0
+last_synced: 2026-04-20
+status: current
+---
+
+# 标准生命周期管理
+
+> **语言**: [English](../../../core/standard-lifecycle-management.md) | 简体中文
+
+**版本**: 1.0.0
+**最后更新**: 2026-04-17
+**状态**: Trial（到期 2026-10-17）
+**适用范围**: universal
+**来源**: XSPEC-070（DEC-043 Wave 1 治理 Meta 套件）
+
+---
+
+## 目的
+
+UDS 标准生命周期状态机。既有 66 个标准无明确状态管理：新增标准没有试验期、过时标准无弃用路径、废弃标准仍被引用。本标准建立五状态机（Proposed / Trial / Active / Deprecated / Archived）与合法转移规则，并规范所有 `.ai.yaml` 标准必须在 frontmatter 标示 `status` / `since` / `expires` / `supersedes`。
+
+---
+
+## 核心规范
+
+- **所有标准必有状态**：frontmatter 必须包含 `status` 和 `since`
+- **Trial 必有期限**：`expires` 默认 since + 6 months
+- **Deprecated 必有替代**：`supersedes` 指向替代标准 id 或迁移文档
+- **禁止反向转移**：Active → Proposed、Archived → Active 均无意义
+- **逾期自动 Archived**：Trial 到期未决则自动归档
+
+---
+
+## 状态说明
+
+| 状态 | 描述 | Skill 可引用？ |
+|------|------|--------------|
+| **Proposed** | 草案阶段，未通过 admission | 不可 |
+| **Trial** | 批准但试验中（默认 6 个月） | 可（标注 trial）|
+| **Active** | 全面采用，standard-of-truth | 可 |
+| **Deprecated** | 标记弃用，必须提供 `supersedes` | 可（Skill 应警示）|
+| **Archived** | 已移除，仅保留历史 | 不可 |
+
+---
+
+## 合法转移路径
+
+```
+Proposed ──(通过 admission)──→ Trial
+Trial    ──(验证通过)─────────→ Active
+Trial    ──(到期/拒绝)─────────→ Archived
+Active   ──(被取代)───────────→ Deprecated
+Deprecated ──(迁移完成)────────→ Archived
+```
+
+**禁止的转移**：
+
+- Active → Proposed（无意义）
+- Archived → Active（应重新申请 admission）
+- Deprecated → Active（应重新 Trial）
+- Proposed → Active（须先 Trial）
+
+---
+
+## Frontmatter 必填字段
+
+### 必填（所有状态）
+
+- `status`: proposed | trial | active | deprecated | archived
+- `since`: ISO-8601（进入当前状态的日期）
+- `version`: semver 字符串
+
+### 条件必填
+
+| 字段 | 适用时机 |
+|------|---------|
+| `expires` | `status = trial`（默认 since + 6 months）|
+| `supersedes` | `status = deprecated`（替代标准 id 或迁移文档路径）|
+| `migration_guide` | `status = deprecated`（相对路径，选填但强烈建议）|
+
+---
+
+## 情境示例
+
+- **情境 1 — Trial → Active**：`retry-standards` 处于 trial。2026-08-01 审视发现 DevAP Fix Loop 和 VibeOps Builder 均采用且无重大缺陷 → 转 Active，`since=2026-08-01`，移除 `expires`
+- **情境 2 — Trial 逾期自动 Archived**：某标准 trial 期限 2026-10-17 到期未通过验证 → 状态转 Archived，记录原因
+- **情境 3 — Deprecated 带迁移**：`legacy-retry-logic` 被 `retry-standards` 取代 → `status=deprecated, supersedes=retry-standards, migration_guide=docs/migrations/retry-v1-to-v2.md`；Skill 使用时显示警告
+
+---
+
+## 遥测事件
+
+**`standard_state_change`**
+
+| 字段 | 类型 |
+|------|------|
+| `standard_id` | `string` |
+| `from_state` | `proposed\|trial\|active\|deprecated\|archived` |
+| `to_state` | `proposed\|trial\|active\|deprecated\|archived` |
+| `reason` | `string` |
+| `timestamp` | `ISO-8601` |
+
+---
+
+## 错误码
+
+| 代码 | 说明 |
+|------|------|
+| `LIFECYCLE-001` | `MISSING_STATUS` — frontmatter 缺 status 字段 |
+| `LIFECYCLE-002` | `MISSING_EXPIRES` — trial 状态缺 expires 字段 |
+| `LIFECYCLE-003` | `MISSING_SUPERSEDES` — deprecated 状态缺 supersedes 字段 |
+| `LIFECYCLE-004` | `FORBIDDEN_TRANSITION` — 尝试执行禁止的状态转移 |
+| `LIFECYCLE-005` | `TRIAL_EXPIRED` — trial 到期未决策 |

package/bundled/locales/zh-CN/core/timeout-standards.md

@@ -0,0 +1,117 @@
+---
+source: ../../../core/timeout-standards.md
+source_version: 1.0.0
+translation_version: 1.0.0
+last_synced: 2026-04-20
+status: current
+---
+
+# Timeout 标准
+
+> **语言**: [English](../../../core/timeout-standards.md) | 简体中文
+
+**版本**: 1.0.0
+**最后更新**: 2026-04-17
+**状态**: Trial（到期 2026-10-17）
+**适用范围**: universal
+**来源**: XSPEC-067（DEC-043 Wave 1 可靠性套件）
+
+---
+
+## 目的
+
+Timeout 标准：层级预算（cascading 0.8×）、deadline propagation、与 circuit-breaker 整合。
+
+避免多层调用链中下层 timeout 大于上层（导致上层先 timeout 而下层仍在执行的资源浪费）。通过 cascading 预算规则（每层 ≤ 0.8× 上层）与 deadline propagation（传 absolute timestamp）让整条调用链都能精准 fail-fast。
+
+---
+
+## 核心规范
+
+- 多层调用的 timeout 必须逐层递减，每下一层 ≤ 0.8 × 上层（预留 20% buffer）
+- 跨服务调用必须传递 deadline（absolute timestamp），不得只传 relative duration
+- 收到请求后若 `now > deadline`，必须立即 fail-fast，禁止发起下游调用
+- Timeout 触发必须计入对应 circuit-breaker 的 failure count
+- 禁止下层 timeout 大于上层 timeout（违反 fail-fast，等同没设 timeout）
+
+---
+
+## Cascading 预算规则
+
+**规则**：每下一层 timeout ≤ 0.8 × 上层 timeout
+
+**示例**（Client timeout=10s，调用链 Client → Gateway → Service A → DB）：
+
+| 层级 | timeout |
+|------|---------|
+| Client | 10,000ms |
+| Gateway | 8,000ms（10000 × 0.8） |
+| Service A | 6,400ms（8000 × 0.8） |
+| DB | 5,120ms（6400 × 0.8） |
+
+**理由**：
+- 预留 20% buffer 给序列化、网络传输、重试等开销
+- 避免上层先 timeout 而下层仍在执行（资源浪费）
+- 0.8 是业界经验值（gRPC / Envoy 常用 0.7~0.85）
+
+---
+
+## Deadline Propagation
+
+| 字段 | 值 |
+|------|-----|
+| 格式 | absolute ISO-8601 timestamp（非 relative duration） |
+| Header 名称 | `X-Deadline` |
+
+**规则**：
+1. 发起调用前计算 `deadline = now + timeout`，写入 header
+2. 收到请求后立即检查 `now > deadline_header` → 若是则 fail-fast（回 `DEADLINE_EXCEEDED`）
+3. 向下游调用时 `timeout = min(cascading_budget, deadline - now)`，取两者较小
+
+**理由**：Relative duration（如 timeout=5s）无法在多层调用中累积扣除；absolute timestamp 让每一层都能精准计算剩余时间。
+
+---
+
+## Timeout 类型
+
+| 类型 | 默认值 | 说明 |
+|------|--------|------|
+| `connect_timeout` | 5,000ms | 建立 TCP / TLS 连接的时间上限 |
+| `request_timeout` | 30,000ms | 发送请求到收到完整响应的时间上限；受 cascading 预算约束 |
+| `idle_timeout` | 60,000ms | 连接闲置多久后关闭；server 端设置 |
+| `total_deadline` | 60,000ms | 含所有重试在内的整体上限；retry × attempt_timeout 总和不得超过此值 |
+
+---
+
+## 与 circuit-breaker 整合
+
+| 规则 | 说明 |
+|------|------|
+| Rule 1 | 每次 timeout 触发视为一次失败，计入 breaker 的 failure count |
+| Rule 2 | 连续 timeout 达 failureThreshold 时 breaker 进入 OPEN |
+| Rule 3 | OPEN 状态下的请求应套用极短 timeout（或直接 fail-fast） |
+
+---
+
+## 情境示例
+
+**情境 1：cascading 预算验证**
+- Client timeout=10s，各层依序 8s → 6.4s → 5.12s
+
+**情境 2：deadline 已过期 fail-fast**
+- 条件：请求抵达 Service A 时 X-Deadline 已过期
+- 结果：立即回 DEADLINE_EXCEEDED，不调用 DB
+
+**情境 3：timeout 触发 circuit breaker**
+- 条件：连续 3 次下游调用皆 timeout（failureThreshold=3）
+- 结果：circuit-breaker 进入 OPEN，第 4 次立即回 CircuitOpenError
+
+---
+
+## 错误码
+
+| 代码 | 说明 |
+|------|------|
+| `TIMEOUT-001` | `REQUEST_TIMEOUT` — 单次请求超时 |
+| `TIMEOUT-002` | `DEADLINE_EXCEEDED` — 整体 deadline 已过，拒绝发起/处理请求 |
+| `TIMEOUT-003` | `CASCADING_BUDGET_VIOLATION` — 下层 timeout > 上层 timeout（配置错误）|

package/bundled/locales/zh-CN/core/token-budget.md

@@ -0,0 +1,108 @@
+---
+source: ../../../core/token-budget.md
+source_version: 1.0.0
+translation_version: 1.0.0
+last_synced: 2026-04-20
+status: current
+---
+
+# Token 预算标准
+
+> **语言**: [English](../../../core/token-budget.md) | 简体中文
+
+**版本**: 1.0.0
+**最后更新**: 2026-04-17
+**状态**: Trial（到期 2026-10-17）
+**适用范围**: universal
+**来源**: XSPEC-068（DEC-043 Wave 1 可靠性套件）
+
+---
+
+## 目的
+
+Token 阈值四区模型（SAFE/WARNING/DANGER/BLOCKING），统一 DevAP/VibeOps 的 token 用量管控行为。
+
+各 Agent 对于「快用完 token 了」的处理方式各异（有的直接截断、有的无警告、有的在最后才通知）。本标准定义四个阈值区间，确保所有 Agent 在进入不同区间时采取一致的行为（警告、简化输出、阻塞）。
+
+---
+
+## 核心规范
+
+- 所有 Agent 必须实现四区 token 预算模型
+- 进入 WARNING 区必须产生结构化日志（非中断）
+- 进入 DANGER 区必须切换为简化输出模式
+- 进入 BLOCKING 区必须拒绝新任务，等待预算刷新
+- 阈值比例可配置，默认值如下
+
+---
+
+## 四区模型
+
+| 区间 | 范围（已用比例） | 行为 |
+|------|----------------|------|
+| **SAFE** | 0% – 60% | 正常执行，无特殊处理 |
+| **WARNING** | 60% – 80% | 产生 `token_budget_warning` 遥测事件；继续执行 |
+| **DANGER** | 80% – 95% | 切换简化输出模式；省略详细说明；继续执行 |
+| **BLOCKING** | 95% – 100% | 拒绝新任务；回传 `TOKEN_BUDGET_EXHAUSTED`；等待刷新 |
+
+---
+
+## 配置参数
+
+| 参数 | 默认值 | 说明 |
+|------|--------|------|
+| `warningThreshold` | `0.60` | 进入 WARNING 区的比例阈值 |
+| `dangerThreshold` | `0.80` | 进入 DANGER 区的比例阈值 |
+| `blockingThreshold` | `0.95` | 进入 BLOCKING 区的比例阈值 |
+| `totalBudget` | 由模型/配置决定 | Token 总预算上限 |
+
+---
+
+## 简化输出模式（DANGER 区）
+
+进入 DANGER 区后，Agent 必须：
+
+1. 省略详细的推理说明（只保留结论）
+2. 压缩示例代码（省略注释和空行）
+3. 不启动需要大量 token 的子任务
+4. 在输出开头标注 `[DANGER MODE]`
+
+---
+
+## 遥测事件
+
+**`token_budget_warning`**（进入 WARNING 或以上区间时上报）
+
+| 字段 | 类型 |
+|------|------|
+| `agentId` | `string` |
+| `zone` | `WARNING\|DANGER\|BLOCKING` |
+| `usedTokens` | `number` |
+| `totalBudget` | `number` |
+| `usedRatio` | `number` |
+| `timestamp` | `string` |
+
+---
+
+## 情境示例
+
+**情境 1：进入 WARNING 区**
+- 条件：已用 token 占比达 62%
+- 结果：上报 `token_budget_warning`（zone=WARNING），继续正常执行
+
+**情境 2：进入 DANGER 区**
+- 条件：已用 token 占比达 83%
+- 结果：切换简化输出模式，输出标注 `[DANGER MODE]`
+
+**情境 3：进入 BLOCKING 区**
+- 条件：已用 token 占比达 96%
+- 结果：拒绝新任务，回传 `TOKEN_BUDGET_EXHAUSTED`，等待下一个预算周期
+
+---
+
+## 错误码
+
+| 代码 | 说明 |
+|------|------|
+| `TOKEN-001` | `TOKEN_BUDGET_EXHAUSTED` — 已进入 BLOCKING 区，拒绝新任务 |
+| `TOKEN-002` | `TOKEN_BUDGET_CONFIG_INVALID` — 阈值配置无效（如 warningThreshold > dangerThreshold）|