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

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

@@ -0,0 +1,224 @@
+---
+source: ../../../core/packaging-standards.md
+source_version: 1.0.0
+translation_version: 1.0.0
+last_synced: 2026-04-20
+status: current
+---
+
+# 打包标准
+
+> **语言**: [English](../../../core/packaging-standards.md) | 简体中文
+
+**版本**: 1.0.0
+**最后更新**: 2026-04-15
+**适用性**: 使用 UDS/DevAP 工具链的项目
+**范围**: 通用 (Universal)
+
+---
+
+## 目的
+
+本标准定义一套基于 Recipe 的打包框架，让用户项目可在 `.devap/packaging.yaml` 中声明打包目标（target）。UDS 负责提供 Recipe 定义与内置 Recipe 库；DevAP 则在 pipeline 中执行编排。
+
+框架的关注点分离如下：
+- **用户项目**：声明「打包什么」（targets + 配置覆盖）
+- **UDS**：定义「如何打包」（Recipe 结构 + 内置 Recipes）
+- **DevAP**：执行「何时打包」（在 Review 与 Deploy 之间的 pipeline 阶段）
+
+---
+
+## 核心原则
+
+| 原则 | 说明 |
+|------|------|
+| **Recipe-based** | 每个打包目标都参照一个具名 Recipe；不在 pipeline YAML 中编写临时脚本 |
+| **声明式 targets** | 项目在 `.devap/packaging.yaml` 中声明 targets；DevAP 负责解析与执行 |
+| **可定制** | 四个定制层允许配置覆盖、Hook 注入、自定义 Recipe 及 Escape Hatch |
+| **整合至 Pipeline** | 打包作为独立阶段运行于 VibeOps pipeline 的 Review 与 Deploy 之间 |
+
+---
+
+## Recipe 结构
+
+Recipe 是定义如何打包项目的 YAML 文件，字段定义如下：
+
+```yaml
+# Recipe: <name>.yaml
+name: <string>            # 必填 — 唯一标识符（kebab-case）
+description: <string>     # 选填 — 人类可读描述
+requires:                 # 选填 — 执行前必须存在的文件
+  - <file-path>
+steps:                    # 必填 — 有序的构建/打包步骤清单
+  - run: <shell-command>
+    description: <string> # 选填 — 步骤描述
+config:                   # 选填 — 默认配置值（可被用户项目覆盖）
+  <key>: <value>
+hooks:                    # 选填 — 生命周期 hooks（~ 表示不执行）
+  preBuild: ~
+  postBuild: ~
+  prePublish: ~
+  postPublish: ~
+```
+
+### 必填与选填字段
+
+| 字段 | 必填 | 说明 |
+|------|------|------|
+| `name` | 是 | 唯一标识符，kebab-case 格式 |
+| `steps` | 是 | 至少需要一个步骤 |
+| `description` | 否 | 人类可读描述 |
+| `requires` | 否 | 前置条件文件检查 |
+| `config` | 否 | 默认配置值；所有 key 均可被用户项目覆盖 |
+| `hooks` | 否 | 生命周期 hook 插入点；`~` 表示不执行 |
+
+### 步骤变量
+
+配置值与运行时上下文可在 `run` 命令中使用 `{variable}` 占位符：
+
+| 变量 | 来源 | 示例 |
+|------|------|------|
+| `{registry}` | `config.registry` | `ghcr.io` |
+| `{name}` | `package.json#name` 或 `config.name` | `my-app` |
+| `{version}` | `package.json#version` 或 `config.version` | `1.2.3` |
+| `{platforms}` | `config.platforms` | `linux/amd64,linux/arm64` |
+| `{output_dir}` | `config.output_dir` | `dist/installers` |
+
+---
+
+## 内置 Recipes
+
+UDS 随附四个内置 Recipe，位于 `recipes/` 目录：
+
+| Recipe | 文件 | 使用场景 |
+|--------|------|----------|
+| `npm-library` | `recipes/npm-library.yaml` | 不含执行入口的 npm 包 |
+| `npm-cli` | `recipes/npm-cli.yaml` | 含 `bin` 字段的 npm 包（CLI 工具） |
+| `docker-service` | `recipes/docker-service.yaml` | Docker 容器镜像构建与推送 |
+| `windows-installer` | `recipes/windows-installer.yaml` | Windows 安装包（.msi / .exe）通过用户脚本 |
+
+### 选择 Recipe 的决策流程
+
+```
+产出物是 npm 包吗？
+├── 是 → package.json 是否含有 "bin" 字段？
+│         ├── 是 → npm-cli
+│         └── 否 → npm-library
+└── 否 → 产出物是容器镜像吗？
+          ├── 是 → docker-service
+          └── 否 → 产出物是 Windows 安装包吗？
+                    ├── 是 → windows-installer
+                    └── 否 → 编写自定义 Recipe（参见定制层）
+```
+
+---
+
+## 定制层
+
+需要偏离内置 Recipe 默认值的项目，应使用最低适用层：
+
+| 层级 | 机制 | 使用时机 |
+|------|------|----------|
+| **L1 — 配置覆盖** | `.devap/packaging.yaml` 中的 `config:` 块 | 更改默认值（registry URL、tag、输出目录）|
+| **L2 — Hook 注入** | `.devap/packaging.yaml` 中的 `hooks:` 块 | 在构建或发布前后执行额外命令 |
+| **L3 — 自定义 Recipe** | 项目 `.devap/recipes/` 中的新 `.yaml` 文件 | 完全不同的构建流程；内置 Recipe 不适用 |
+| **L4 — Escape Hatch** | target 定义中以 `script:` 替代 `recipe:` | 原始 shell 脚本，无合适的 Recipe 抽象 |
+
+### L1 示例 — 配置覆盖
+
+```yaml
+# .devap/packaging.yaml
+targets:
+  - name: publish-npm
+    recipe: npm-library
+    config:
+      registry: https://npm.pkg.github.com
+      access: restricted
+      tag: beta
+```
+
+### L2 示例 — Hook 注入
+
+```yaml
+# .devap/packaging.yaml
+targets:
+  - name: docker-push
+    recipe: docker-service
+    hooks:
+      postPush: |
+        curl -X POST https://hooks.example.com/deploy-notify \
+          -d "{\"version\": \"{version}\"}"
+```
+
+### L3 示例 — 自定义 Recipe
+
+```yaml
+# .devap/recipes/electron-app.yaml
+name: electron-app
+description: 构建 Electron 桌面应用程序
+requires:
+  - package.json
+  - electron-builder.yml
+steps:
+  - run: npm run build
+  - run: npx electron-builder --publish never
+config:
+  output_dir: dist
+```
+
+### L4 示例 — Escape Hatch
+
+```yaml
+# .devap/packaging.yaml
+targets:
+  - name: legacy-bundle
+    script: |
+      ./scripts/legacy-bundle.sh
+      mv output/ dist/bundle/
+```
+
+---
+
+## 打包验收标准
+
+当以下**所有**条件均满足时，打包执行视为**成功**：
+
+| 标准 | 阈值 | 备注 |
+|------|------|------|
+| 所有 `requires` 文件存在 | 100% | 在任何步骤执行前检查 |
+| 所有步骤以 exit code 0 结束 | 100% | 任何非零 exit 使执行失败 |
+| `postBuild` 产出物存在 | 存在于预期路径 | 构建步骤后由 DevAP 验证 |
+| Hook 命令以 exit code 0 结束 | 100% | Hook 失败会传播为步骤失败 |
+| 已发布产出物可被取回 | HTTP 200 / registry 查询成功 | 由 DevAP 在发布后进行 smoke check |
+
+### 失败处理
+
+| 失败类型 | 行动 | 可重试？ |
+|----------|------|----------|
+| `requires` 文件缺失 | 立即失败，报告缺失路径 | 否 |
+| 步骤非零 exit | 立即失败，若已定义则执行 `postBuild` hook | 可配置（默认：否）|
+| Hook 非零 exit | 立即失败 | 否 |
+| 发布无法连接 | 以指数退避重试最多 3 次 | 是（3×）|
+
+---
+
+## 相关标准
+
+- [部署标准](deployment-standards.md) — 打包后的部署阶段
+- [Pipeline 整合标准](pipeline-integration-standards.md) — CI/CD pipeline 配置
+- [Check-in 标准](checkin-standards.md) — 打包前的质量关卡
+- [版本控制标准](versioning.md) — 包产出物使用的版本号
+
+---
+
+## 版本历史
+
+| 版本 | 日期 | 变更 |
+|------|------|------|
+| 1.0.0 | 2026-04-15 | 初始发行 — XSPEC-034 Phase 1 |
+
+---
+
+## 许可证
+
+本标准以 [CC BY 4.0](https://creativecommons.org/licenses/by/4.0/) 许可发布。

package/bundled/locales/zh-CN/core/recovery-recipe-registry.md

@@ -0,0 +1,146 @@
+---
+source: ../../../core/recovery-recipe-registry.md
+source_version: 1.0.0
+translation_version: 1.0.0
+last_synced: 2026-04-20
+status: current
+---
+
+# 恢复配方注册表标准
+
+> **语言**: [English](../../../core/recovery-recipe-registry.md) | 简体中文
+
+**版本**: 1.0.0
+**最后更新**: 2026-04-16
+**适用范围**: 所有 Agent 执行恢复逻辑
+**Scope**: universal
+**来源**: XSPEC-046（claw-code ROADMAP Phase 3 Recovery Recipes，DEC-035）
+**依赖**: failure-source-taxonomy（XSPEC-045）
+
+---
+
+## 目的
+
+恢复配方注册表：将分散的恢复逻辑统一为 YAML 可配置的 Recipe，以 `failureSource` 为匹配键。
+
+各模块（Fix Loop、Circuit Breaker、Guardian 自动修复、Staging 重试）的恢复逻辑统一为可外部化的 Recovery Recipe 格式。每个 Recipe 通过 `failureSource`（XSPEC-045）匹配触发条件，选择对应的恢复策略，并定义升级路径（escalation）。无匹配 Recipe 时 fallback 到现有行为（向后兼容）。
+
+---
+
+## 核心规范
+
+- 每个 Recovery Recipe 必须有唯一 ID（`RR-NNN` 格式）
+- `match.failure_source` 必须是 failure-source-taxonomy 中定义的 8 类之一
+- `escalation.on_exhaust` 必须定义，不得无限循环（如 escalation 指向自身）
+- 无匹配 Recipe 时，系统必须 fallback 到现有默认行为（不得抛出错误）
+- 用户自定义 Recipe 优先于内置 Recipe（同 `failureSource` 时，用户配置的先匹配）
+- Recipe config 格式错误时 fallback 到策略默认值（不中断执行）
+
+---
+
+## 6 个内置恢复策略
+
+### `fix_loop`
+
+- **描述**：注入结构化错误反馈，重试任务（现有 Fix Loop）
+- **默认 config**：`max_attempts: 3`, `budget_usd: 0.50`
+- **最适合**：`compilation`, `test_failure`
+
+### `circuit_breaker`
+
+- **描述**：三态断路器保护（XSPEC-036），连续失败后开路避免雪崩
+- **默认 config**：`failure_threshold: 3`, `cooldown_ms: 30000`
+- **最适合**：`tool_failure`, `prompt_delivery`
+
+### `rebase_and_retry`
+
+- **描述**：先执行 git rebase 同步基准分支，再重试任务 / 迭代
+- **默认 config**：`max_attempts: 1`, `base_branch: "main"`
+- **最适合**：`branch_divergence`
+- **依赖**：XSPEC-047 Branch Drift Detection
+
+### `model_switch`
+
+- **描述**：切换至备用模型后重试
+- **默认 config**：`fallback_models: [...]`, `max_attempts: 2`
+- **最适合**：`model_degradation`, `prompt_delivery`
+
+### `degraded_mode`
+
+- **描述**：以降级模式继续执行（如：跳过质量验证、以部分结果继续）
+- **结果状态**：`done_with_concerns`
+- **最适合**：`resource_exhaustion`, `model_degradation`
+
+### `human_checkpoint`
+
+- **描述**：暂停执行，等待人工介入（提供失败细节供判断）
+- **最适合**：`policy_violation`, `branch_divergence`
+- **备注**：所有其他策略的最终升级路径
+
+---
+
+## Recipe YAML 格式
+
+```yaml
+id: RR-NNN          # 必填，唯一标识符
+name: string        # 必填，可读名称
+match:              # 必填
+  failure_source: <FailureSource>   # 必填
+  severity: [critical, high, ...]   # 选填；省略表示匹配所有 severity
+strategy: <RecoveryStrategy>        # 必填
+config: {}                          # 选填；覆盖策略默认值
+escalation:         # 必填
+  on_exhaust: <RecoveryStrategy>    # 必填；不得指向自身
+  message: string   # 选填；升级时的通知消息
+```
+
+---
+
+## 5 个默认 Recipe
+
+| ID | 名称 | 匹配条件 | 策略 | 升级路径 |
+|----|------|----------|------|---------|
+| `RR-001` | Fix Loop for Compilation Errors | `compilation` | `fix_loop`（3次, $0.50） | `human_checkpoint` |
+| `RR-002` | Fix Loop for Test Failures | `test_failure` | `fix_loop`（3次, $0.50） | `human_checkpoint` |
+| `RR-003` | Model Switch for Degradation | `model_degradation` | `model_switch`（2次） | `degraded_mode` |
+| `RR-004` | Rebase for Branch Divergence | `branch_divergence` | `rebase_and_retry`（1次） | `human_checkpoint`（需人工解决冲突） |
+| `RR-005` | Degraded Mode for Resource Exhaustion | `resource_exhaustion` | `degraded_mode` | `human_checkpoint` |
+
+---
+
+## 类型定义
+
+### RecoveryStrategy
+
+```
+fix_loop | circuit_breaker | rebase_and_retry | model_switch | degraded_mode | human_checkpoint
+```
+
+### RecoveryRecipe
+
+| 字段 | 类型 | 必填 |
+|------|------|------|
+| `id` | `string`（RR-NNN 格式） | 是 |
+| `name` | `string` | 是 |
+| `match.failure_source` | `FailureSource` | 是 |
+| `match.severity` | `string[]`（可选） | 否 |
+| `strategy` | `RecoveryStrategy` | 是 |
+| `config` | `object`（可选） | 否 |
+| `escalation.on_exhaust` | `RecoveryStrategy` | 是 |
+| `escalation.message` | `string`（可选） | 否 |
+
+---
+
+## 集成点
+
+### DevAP
+
+- `packages/core/src/types.ts` — `RecoveryRecipe` / `RecoveryStrategy` type
+- `packages/core/src/recovery-registry.ts` — Registry 实现与默认 recipe
+- `packages/core/src/orchestrator.ts` — fix loop 前查询 Registry
+
+### VibeOps
+
+- `src/types/index.ts` — 独立定义 `RecoveryRecipe`（AGPL 隔离）
+- `src/runner/recovery-registry.ts` — 独立实现
+- `recovery-recipes.yaml` — 默认 recipe 配置

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

@@ -0,0 +1,131 @@
+---
+source: ../../../core/retry-standards.md
+source_version: 1.0.0
+translation_version: 1.0.0
+last_synced: 2026-04-20
+status: current
+---
+
+# 重试策略标准
+
+> **语言**: [English](../../../core/retry-standards.md) | 简体中文
+
+**版本**: 1.0.0
+**最后更新**: 2026-04-17
+**状态**: Trial（到期 2026-10-17）
+**适用范围**: universal
+**来源**: XSPEC-067（DEC-043 Wave 1 可靠性套件）
+
+---
+
+## 目的
+
+重试策略标准：指数退避加抖动、重试上限、依 failure-source 分类的重试规则。
+
+延伸既有 circuit-breaker 与 failure-source-taxonomy，补齐 retry 层的标准化规则。避免各组件各自实现重试造成行为不一致（无上限重试、无 jitter 导致 thundering herd）。
+
+---
+
+## 核心规范
+
+- 所有重试逻辑必须使用 exponential + jitter，禁止固定间隔或无 jitter 的纯指数
+- 重试必须有明确上限（`max_attempts`），禁止无限重试
+- 重试决策必须先参考 failure-source-taxonomy 分类，fail-fast 类别不得重试
+- 重试必须与 circuit-breaker 整合：OPEN 状态下不得重试，直接 fail-fast
+- 每次重试都应通过遥测事件上报（`retry_attempted` / `retry_exhausted`）
+
+---
+
+## 退避公式
+
+**Exponential with full jitter**：
+
+```
+wait_ms = min(cap_ms, base_ms * 2^attempt) * (0.5 + random() * 0.5)
+```
+
+| 参数 | 默认值 | 说明 |
+|------|--------|------|
+| `base_ms` | `100` | 基础等待时间 |
+| `cap_ms` | `30000` | 等待时间上限 |
+| `max_attempts` | `5` | 最大重试次数 |
+| `jitter_ratio` | `0.5` | ±50% 抖动 |
+
+**理由**：
+- Exponential 随重试次数指数退避，避免短时间大量请求
+- Jitter ±50% 避免 thundering herd（所有 client 同时重试）
+- cap_ms=30s 避免超长等待，与典型 request timeout 对齐
+
+---
+
+## 依 failure-source 的重试规则
+
+| 失败来源 | 可重试 | max_attempts | base_ms | 备注 |
+|---------|--------|-------------|---------|------|
+| `transient_network` | ✅ | 5 | 100 | 短暂网络抖动，指数退避通常可恢复 |
+| `rate_limit` | ✅ | 3 | 1000 | 底数加大预留额度恢复时间；优先采用 Retry-After header |
+| `upstream_unavailable` | ✅ | 3 | 500 | 重试前先查 circuit-breaker |
+| `tool_failure` | ✅ | 2 | 200 | 工具层失败通常非 transient，仅给 2 次机会 |
+| `prompt_delivery` | ✅ | 2 | 100 | 超过 2 次改走 model_switch |
+| `authentication` | ❌ | — | — | fail-fast；凭证错误重试不会变对 |
+| `validation` | ❌ | — | — | fail-fast；input 错误重试结果不变 |
+| `policy_violation` | ❌ | — | — | fail-fast；安全决策禁止绕过 |
+| `quota_exhausted` | ❌ | — | — | fail-fast；等 budget reset 或升级 tier |
+
+---
+
+## 与 circuit-breaker 整合
+
+| 规则 | 说明 |
+|------|------|
+| Rule 1 | 每次重试前检查对应 breaker 的 state；若为 OPEN 立即回传 `CircuitOpenError`，不消耗 `max_attempts` |
+| Rule 2 | 重试全部耗尽（`retry_exhausted`）计入 breaker 的 failure count |
+| Rule 3 | HALF_OPEN 状态下仅允许 1 次探针重试，不套用 `max_attempts` |
+
+---
+
+## 遥测事件
+
+**`retry_attempted`**（每次重试前上传，第 0 次原始调用不算）
+
+| 字段 | 类型 |
+|------|------|
+| `operation` | `string` |
+| `attempt` | `number` |
+| `max_attempts` | `number` |
+| `failure_source` | `FailureSource \| null` |
+| `wait_ms` | `number` |
+
+**`retry_exhausted`**（达到 max_attempts 仍失败时上传）
+
+| 字段 | 类型 |
+|------|------|
+| `operation` | `string` |
+| `attempts` | `number` |
+| `final_failure_source` | `FailureSource` |
+
+---
+
+## 情境示例
+
+**情境 1：指数退避计算**
+- 条件：调用下游 API 失败，failure_source=transient_network，已重试 2 次
+- 第 3 次重试等待时间：`min(30000, 100 * 2^3) * [0.5..1.0] = 400~800ms`
+
+**情境 2：authentication fail-fast**
+- 条件：API 回传 401，failure_source=authentication
+- 结果：立即 fail-fast，不进入退避，不计入 circuit-breaker failure count
+
+**情境 3：circuit OPEN 跳过重试**
+- 条件：对应 breaker 为 OPEN，cooldown 剩 15s
+- 结果：立即回传 CircuitOpenError，不消耗 max_attempts
+
+---
+
+## 错误码
+
+| 代码 | 说明 |
+|------|------|
+| `RETRY-001` | `RETRY_EXHAUSTED` — 达到 max_attempts 仍失败 |
+| `RETRY-002` | `RETRY_SKIPPED_NON_RETRYABLE` — failure_source 属 fail-fast 类别 |
+| `RETRY-003` | `RETRY_SKIPPED_CIRCUIT_OPEN` — breaker OPEN 状态下跳过重试 |

package/bundled/locales/zh-CN/core/security-decision.md

@@ -0,0 +1,104 @@
+---
+source: ../../../core/security-decision.md
+source_version: 1.0.0
+translation_version: 1.0.0
+last_synced: 2026-04-20
+status: current
+---
+
+# 安全决策标准
+
+> **语言**: [English](../../../core/security-decision.md) | 简体中文
+
+**版本**: 1.0.0
+**最后更新**: 2026-04-17
+**状态**: Trial（到期 2026-10-17）
+**适用范围**: universal
+**来源**: XSPEC-068（DEC-043 Wave 1 可靠性套件）
+
+---
+
+## 目的
+
+安全决策铁律：deny > ask > allow 优先级仲裁，确保所有安全相关决策不被绕过。
+
+当多个规则对同一操作产生冲突的安全决策时（一个规则说 allow，另一个说 deny），必须有明确的优先级仲裁机制。本标准定义三态优先级（deny > ask > allow），并禁止任何代码路径绕过 deny 决策。
+
+---
+
+## 核心规范
+
+- 安全决策优先级：`deny` > `ask` > `allow`
+- 任何 `deny` 决策均不可被 `allow` 或 `ask` 覆盖
+- `policy_violation` 类失败必须触发 `deny`，不得重试
+- 安全决策必须记录遥测事件（`security_decision_made`）
+- 禁止在安全决策路径上使用 try/catch 静默吞掉异常
+
+---
+
+## 三态优先级
+
+| 优先级 | 决策 | 说明 |
+|--------|------|------|
+| 最高 | `deny` | 明确拒绝，不可被覆盖；记录原因 |
+| 中间 | `ask` | 需要用户确认后才可执行 |
+| 最低 | `allow` | 默认放行，前提是无 deny/ask 规则匹配 |
+
+### 仲裁逻辑
+
+```
+if (任何规则产生 deny) → deny（终止，不继续检查）
+else if (任何规则产生 ask) → ask（等待用户确认）
+else → allow
+```
+
+---
+
+## 禁止的模式
+
+| 禁止 | 原因 |
+|------|------|
+| 捕获 `DenyError` 并继续执行 | 绕过安全决策 |
+| 在 `deny` 后重试操作 | `policy_violation` 不可重试 |
+| 在 `ask` 阶段超时后自动 allow | 应超时后自动 deny |
+| 忽略安全决策遥测日志 | 无审计追踪 |
+
+---
+
+## 遥测事件
+
+**`security_decision_made`**（每次安全决策时上报）
+
+| 字段 | 类型 |
+|------|------|
+| `operation` | `string` |
+| `decision` | `deny\|ask\|allow` |
+| `matchedRule` | `string` |
+| `reason` | `string` |
+| `timestamp` | `string` |
+
+---
+
+## 情境示例
+
+**情境 1：deny 优先于 allow**
+- 条件：规则 A 产生 allow，规则 B 产生 deny
+- 结果：最终决策为 deny，操作被拒绝，记录原因
+
+**情境 2：ask 超时**
+- 条件：操作需要用户确认（ask），用户 30 秒内未响应
+- 结果：超时后自动转为 deny（不允许自动 allow）
+
+**情境 3：policy_violation 不重试**
+- 条件：操作触发 `policy_violation`，决策为 deny
+- 结果：立即终止，不进入重试逻辑，记录 `security_decision_made`
+
+---
+
+## 错误码
+
+| 代码 | 说明 |
+|------|------|
+| `SEC-001` | `OPERATION_DENIED` — 安全决策为 deny，操作被拒绝 |
+| `SEC-002` | `ASK_TIMEOUT` — 用户确认超时，自动转为 deny |
+| `SEC-003` | `SECURITY_BYPASS_DETECTED` — 检测到绕过安全决策的代码路径 |