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

package/bundled/locales/zh-CN/core/capability-declaration.md

@@ -0,0 +1,123 @@
+---
+source: ../../../core/capability-declaration.md
+source_version: 1.0.0
+translation_version: 1.0.0
+last_synced: 2026-04-20
+status: current
+---
+
+# Fail-Closed 能力声明标准
+
+> **语言**: [English](../../../core/capability-declaration.md) | 简体中文
+
+**版本**: 1.0.0
+**最后更新**: 2026-04-17
+**状态**: Trial（到期 2026-10-17）
+**适用范围**: universal
+**来源**: XSPEC-068（DEC-043 Wave 1 可靠性套件）
+
+---
+
+## 目的
+
+Fail-Closed 能力声明：工具 / Adapter 默认不安全，必须明确声明才视为安全。
+
+各工具和 Adapter 的并发安全性、只读性等能力未明确声明，导致 Agent 编排时无法判断是否可并发调用。本标准要求所有工具和 Adapter 必须在接口中明确声明其能力属性，未声明的属性默认为 false（Fail-Closed）。
+
+---
+
+## 核心规范
+
+- 所有工具（Tool）和 Adapter 必须声明能力接口（`CapabilityDeclaration`）
+- `isConcurrencySafe` 默认 `false`（未声明 = 不可并发）
+- `isReadOnly` 默认 `false`（未声明 = 可能修改状态）
+- `supportsPartialFailure` 默认 `false`
+- Agent 编排器在并发调用前必须检查 `isConcurrencySafe`
+
+---
+
+## CapabilityDeclaration 接口
+
+```typescript
+interface CapabilityDeclaration {
+  toolId: string;
+
+  // 并发安全性：未声明默认 false
+  isConcurrencySafe: boolean;
+
+  // 只读性：未声明默认 false（可能有副作用）
+  isReadOnly: boolean;
+
+  // 是否支持部分失败（单个操作失败不影响其他）
+  supportsPartialFailure: boolean;
+
+  // 最大并发数（isConcurrencySafe=true 时有效）
+  maxConcurrency?: number;
+
+  // 能力声明版本
+  declarationVersion: string;
+}
+```
+
+---
+
+## Fail-Closed 规则
+
+| 属性 | 默认值 | 含义 |
+|------|--------|------|
+| `isConcurrencySafe` | `false` | 未声明则禁止并发调用 |
+| `isReadOnly` | `false` | 未声明则假设有副作用，需额外谨慎 |
+| `supportsPartialFailure` | `false` | 未声明则任意失败视为全部失败 |
+
+---
+
+## 编排器检查流程
+
+```
+调用工具前：
+1. 读取工具的 CapabilityDeclaration
+2. 若需要并发调用且 isConcurrencySafe=false → 拒绝并发，改为串行
+3. 若工具未提供 CapabilityDeclaration → 视为 isConcurrencySafe=false
+4. 记录 capability_check_result 遥测事件
+```
+
+---
+
+## 遥测事件
+
+**`capability_check_result`**（每次能力检查时上报）
+
+| 字段 | 类型 |
+|------|------|
+| `toolId` | `string` |
+| `checkType` | `concurrency\|readonly\|partial_failure` |
+| `declared` | `boolean` |
+| `decision` | `allowed\|denied` |
+| `timestamp` | `string` |
+
+---
+
+## 情境示例
+
+**情境 1：并发安全检查**
+- 条件：Agent 编排器需要并发调用 `file-writer` 工具
+- `file-writer` 的 `isConcurrencySafe=false`
+- 结果：编排器改为串行调用，记录 `capability_check_result`（decision=denied）
+
+**情境 2：未声明能力（Fail-Closed）**
+- 条件：旧版工具未提供 `CapabilityDeclaration`
+- 结果：视为 `isConcurrencySafe=false, isReadOnly=false`，采用最保守策略
+
+**情境 3：只读工具并发**
+- 条件：`search-tool` 声明 `isReadOnly=true, isConcurrencySafe=true, maxConcurrency=5`
+- 结果：允许最多 5 个并发调用
+
+---
+
+## 错误码
+
+| 代码 | 说明 |
+|------|------|
+| `CAP-001` | `MISSING_CAPABILITY_DECLARATION` — 工具未提供能力声明，采用 Fail-Closed |
+| `CAP-002` | `CONCURRENCY_DENIED` — isConcurrencySafe=false 但请求并发调用 |
+| `CAP-003` | `MAX_CONCURRENCY_EXCEEDED` — 并发数超过 maxConcurrency 限制 |

package/bundled/locales/zh-CN/core/circuit-breaker.md

@@ -0,0 +1,106 @@
+---
+source: ../../../core/circuit-breaker.md
+source_version: 1.0.0
+translation_version: 1.0.0
+last_synced: 2026-04-20
+status: current
+---
+
+# 断路器标准
+
+> **语言**: [English](../../../core/circuit-breaker.md) | 简体中文
+
+**版本**: 1.0.0
+**最后更新**: 2026-04-17
+**状态**: Trial（到期 2026-10-17）
+**适用范围**: universal
+**来源**: XSPEC-068（DEC-043 Wave 1 可靠性套件）
+
+---
+
+## 目的
+
+通用断路器标准：三态状态机（CLOSED/HALF_OPEN/OPEN）、阈值配置、与遥测整合。
+
+各模块各自实现断路器导致行为不一致（阈值不同、HALF_OPEN 探针逻辑各异、遥测事件命名混乱）。本标准提供统一的状态机定义、配置键名，以及必须上报的遥测事件，确保 DevAP/VibeOps/telemetry 三端可互相理解断路器状态。
+
+---
+
+## 核心规范
+
+- 断路器必须实现三态：CLOSED / HALF_OPEN / OPEN
+- `failureThreshold`、`successThreshold`、`cooldownMs` 必须可配置，有默认值
+- 触发转换时必须上报 `circuit_state_change` 遥测事件
+- HALF_OPEN 状态下只允许单次探针请求（不允许并发探针）
+- 所有断路器实例必须可通过 `circuitId` 唯一标识
+
+---
+
+## 状态机
+
+| 状态 | 说明 |
+|------|------|
+| **CLOSED** | 正常状态，放行所有请求；连续失败计数 |
+| **HALF_OPEN** | 冷却后的探针状态；放行单次探针请求 |
+| **OPEN** | 开路状态，拒绝所有请求；等待冷却期 |
+
+### 状态转换规则
+
+```
+CLOSED → OPEN       : 连续失败 >= failureThreshold
+OPEN → HALF_OPEN    : 冷却期（cooldownMs）到期
+HALF_OPEN → CLOSED  : 探针成功 >= successThreshold
+HALF_OPEN → OPEN    : 探针失败（立即重新开路）
+```
+
+---
+
+## 配置参数
+
+| 参数 | 默认值 | 说明 |
+|------|--------|------|
+| `failureThreshold` | `3` | 触发 OPEN 的连续失败次数 |
+| `successThreshold` | `1` | 从 HALF_OPEN 恢复到 CLOSED 所需的成功次数 |
+| `cooldownMs` | `30000` | OPEN 状态冷却时间（毫秒）|
+| `circuitId` | 必填 | 断路器唯一标识符 |
+
+---
+
+## 遥测事件
+
+**`circuit_state_change`**（每次状态转换时上报）
+
+| 字段 | 类型 |
+|------|------|
+| `circuitId` | `string` |
+| `fromState` | `CLOSED\|HALF_OPEN\|OPEN` |
+| `toState` | `CLOSED\|HALF_OPEN\|OPEN` |
+| `reason` | `string` |
+| `failureCount` | `number` |
+| `timestamp` | `string` |
+
+---
+
+## 情境示例
+
+**情境 1：CLOSED → OPEN**
+- 条件：连续 3 次调用下游 API 失败（failureThreshold=3）
+- 结果：断路器转 OPEN，后续请求立即回传 `CircuitOpenError`
+
+**情境 2：OPEN → HALF_OPEN → CLOSED**
+- 条件：冷却 30s 后放行探针请求，探针成功
+- 结果：断路器恢复 CLOSED，失败计数重置
+
+**情境 3：HALF_OPEN → OPEN（探针失败）**
+- 条件：探针请求失败
+- 结果：立即重新开路，重新进入冷却期
+
+---
+
+## 错误码
+
+| 代码 | 说明 |
+|------|------|
+| `CB-001` | `CIRCUIT_OPEN` — 断路器为 OPEN 状态，请求被拒绝 |
+| `CB-002` | `PROBE_REJECTED` — HALF_OPEN 状态下拒绝并发探针 |
+| `CB-003` | `CONFIG_INVALID` — 断路器配置参数无效 |

package/bundled/locales/zh-CN/core/dual-phase-output.md

@@ -0,0 +1,103 @@
+---
+source: ../../../core/dual-phase-output.md
+source_version: 1.0.0
+translation_version: 1.0.0
+last_synced: 2026-04-20
+status: current
+---
+
+# 双阶段输出标准
+
+> **语言**: [English](../../../core/dual-phase-output.md) | 简体中文
+
+**版本**: 1.0.0
+**最后更新**: 2026-04-17
+**状态**: Trial（到期 2026-10-17）
+**适用范围**: universal
+**来源**: XSPEC-068（DEC-043 Wave 1 可靠性套件）
+
+---
+
+## 目的
+
+双阶段 LLM 输出标准：`<analysis>` 丢弃 + `<summary>` 保留，统一 Agent 的输出过滤行为。
+
+Agent 的推理过程（chain-of-thought）不应直接暴露给下游消费者：它消耗 token、包含中间假设、对机器不友好。本标准要求所有 Agent 输出分为两个阶段，`<analysis>` 标签内容在传递给下游前丢弃，只保留 `<summary>` 内容。
+
+---
+
+## 核心规范
+
+- 所有 Agent 必须在输出中明确区分 `<analysis>` 与 `<summary>` 两个阶段
+- `<analysis>` 内容为推理过程，不得传递给下游消费者（丢弃）
+- `<summary>` 内容为最终结论，必须保留并传递
+- 若 Agent 输出缺少 `<summary>` 标签，视为格式错误（DUAL-001）
+- 下游模块在消费 Agent 输出前必须执行过滤步骤
+
+---
+
+## 输出格式
+
+```xml
+<analysis>
+[Agent 的推理过程、假设检验、中间步骤]
+[此区段会被丢弃，不传递给下游]
+</analysis>
+
+<summary>
+[最终结论、可执行的建议、结构化数据]
+[此区段会被保留并传递给下游消费者]
+</summary>
+```
+
+---
+
+## 过滤规则
+
+| 规则 | 说明 |
+|------|------|
+| 规则 1 | 解析输出时，提取 `<summary>...</summary>` 内容 |
+| 规则 2 | 丢弃 `<analysis>...</analysis>` 及其内容 |
+| 规则 3 | 若两个标签都缺失，回传错误 `DUAL-001` |
+| 规则 4 | 若只有 `<analysis>` 无 `<summary>`，回传错误 `DUAL-001` |
+| 规则 5 | 允许 `<summary>` 内嵌套结构化数据（JSON、YAML、代码块）|
+
+---
+
+## 遥测事件
+
+**`dual_phase_filter_applied`**（每次执行过滤时上报）
+
+| 字段 | 类型 |
+|------|------|
+| `agentId` | `string` |
+| `analysisTokens` | `number` |
+| `summaryTokens` | `number` |
+| `filterSuccess` | `boolean` |
+| `timestamp` | `string` |
+
+---
+
+## 情境示例
+
+**情境 1：正常双阶段输出**
+- Agent 输出包含 `<analysis>` 和 `<summary>` 标签
+- 过滤后只保留 `<summary>` 内容传递给下游
+
+**情境 2：缺少 `<summary>` 标签**
+- Agent 输出只有 `<analysis>` 内容
+- 回传 `DUAL-001` 错误，不传递任何内容给下游
+
+**情境 3：`<summary>` 内嵌套 JSON**
+- `<summary>` 内包含结构化 JSON 数据
+- 过滤后完整保留 JSON，可被下游直接解析
+
+---
+
+## 错误码
+
+| 代码 | 说明 |
+|------|------|
+| `DUAL-001` | `MISSING_SUMMARY_TAG` — 输出缺少 `<summary>` 标签 |
+| `DUAL-002` | `EMPTY_SUMMARY` — `<summary>` 标签内容为空 |
+| `DUAL-003` | `MALFORMED_OUTPUT` — 输出格式无法解析 |

package/bundled/locales/zh-CN/core/failure-source-taxonomy.md

@@ -0,0 +1,99 @@
+---
+source: ../../../core/failure-source-taxonomy.md
+source_version: 1.0.0
+translation_version: 1.0.0
+last_synced: 2026-04-20
+status: current
+---
+
+# 失败来源分类法
+
+> **语言**: [English](../../../core/failure-source-taxonomy.md) | 简体中文
+
+**版本**: 1.0.0
+**最后更新**: 2026-04-17
+**状态**: Trial（到期 2026-10-17）
+**适用范围**: universal
+**来源**: XSPEC-045（DEC-035 Recovery Recipe Registry）
+
+---
+
+## 目的
+
+失败来源分类法：8 类 `failureSource`，补充 `TaskStatus` 的 why 维度。
+
+`TaskStatus`（succeeded/failed/partial）只描述「是什么」，不描述「为什么失败」。本分类法定义 8 类失败来源，让 Recovery Recipe Registry（XSPEC-046）可以根据 `failureSource` 精准选择恢复策略，而不是对所有失败套用同一个回退逻辑。
+
+---
+
+## 核心规范
+
+- 所有失败事件必须附带 `failureSource`（8 类之一）
+- `failureSource` 决定是否可重试（见下表）
+- Recovery Recipe 以 `failureSource` 为匹配键
+- 无法分类的失败标记为 `unknown`，触发人工检查点
+- 单次失败事件只能有一个 `failureSource`（不可多选）
+
+---
+
+## 8 类失败来源
+
+| failureSource | 可重试 | 说明 |
+|---------------|--------|------|
+| `transient_network` | ✅ | 短暂网络抖动，如 TCP 超时、DNS 解析失败 |
+| `rate_limit` | ✅ | 速率限制，如 429 Too Many Requests |
+| `upstream_unavailable` | ✅ | 上游服务不可达，断路器可处理 |
+| `tool_failure` | ✅ | 工具层失败，如 CLI 工具崩溃 |
+| `prompt_delivery` | ✅ | 提示词传递失败，可切换模型重试 |
+| `authentication` | ❌ | 凭证错误，重试不会变对 |
+| `validation` | ❌ | 输入验证失败，重试结果不变 |
+| `policy_violation` | ❌ | 安全策略拒绝，禁止绕过 |
+| `quota_exhausted` | ❌ | 配额耗尽，等待刷新 |
+| `model_degradation` | ✅ | 模型质量降级，可切换备用模型 |
+| `resource_exhaustion` | ❌ | 资源耗尽（内存/磁盘），需人工介入 |
+| `branch_divergence` | ✅ | 分支漂移，可 rebase 重试 |
+| `compilation` | ✅ | 编译错误，Fix Loop 可处理 |
+| `test_failure` | ✅ | 测试失败，Fix Loop 可处理 |
+| `unknown` | ❌ | 未能分类，触发人工检查点 |
+
+---
+
+## 与 Recovery Recipe 的对应
+
+| failureSource | 推荐 Recovery Strategy |
+|---------------|----------------------|
+| `compilation` | `fix_loop` |
+| `test_failure` | `fix_loop` |
+| `model_degradation` | `model_switch` |
+| `branch_divergence` | `rebase_and_retry` |
+| `resource_exhaustion` | `degraded_mode` |
+| `policy_violation` | `human_checkpoint` |
+| `authentication` | `human_checkpoint` |
+| `transient_network` | `circuit_breaker` + retry |
+| `tool_failure` | `circuit_breaker` |
+| `prompt_delivery` | `model_switch` |
+| `unknown` | `human_checkpoint` |
+
+---
+
+## 遥测事件
+
+**`failure_classified`**（每次失败分类时上报）
+
+| 字段 | 类型 |
+|------|------|
+| `taskId` | `string` |
+| `failureSource` | `FailureSource` |
+| `isRetryable` | `boolean` |
+| `originalError` | `string` |
+| `timestamp` | `string` |
+
+---
+
+## 错误码
+
+| 代码 | 说明 |
+|------|------|
+| `FST-001` | `UNCLASSIFIED_FAILURE` — 失败来源无法分类，标记为 unknown |
+| `FST-002` | `INVALID_FAILURE_SOURCE` — failureSource 不在 8 类定义内 |
+| `FST-003` | `MULTIPLE_SOURCES` — 单次失败标记了多个 failureSource（违规）|