universal-dev-standards 5.15.1 → 5.16.0

package/bundled/locales/zh-CN/skills/observability-assistant/guide.md

@@ -0,0 +1,188 @@
+---
+source: ../../../../skills/observability-assistant/guide.md
+source_version: 1.0.0
+translation_version: 1.0.0
+last_synced: 2026-06-02
+source_hash: 760e3ec43846
+status: current
+scope: universal
+description: |
+  指导跨三大支柱（Logs、Metrics、Traces）实施可观测性。
+  使用场景：搭建监控、选择指标类型、实施追踪、评估成熟度。
+  关键词：observability、metrics、traces、logs、golden signals、OpenTelemetry、可观测性、监控。
+---
+
+# Observability Assistant
+
+> **语言**：English | [繁体中文](../../locales/zh-TW/skills/observability-assistant/SKILL.md)
+
+**版本**：1.0.0
+**最后更新**：2026-04-01
+**适用范围**：Claude Code Skills
+
+---
+
+## 目的
+
+本技能通过提供三大支柱（Logs、Metrics、Traces）、指标类型选择、Golden Signals 监控以及成熟度自评等方面的指导，帮助团队构建可观测的系统。
+
+---
+
+## 快速参考（YAML 压缩版）
+
+```yaml
+# === THREE PILLARS 三大支柱 ===
+three_pillars:
+  logs:
+    captures: "Discrete events with context / 帶上下文的離散事件"
+    use_for: "Debugging, audit trails, error details"
+    granularity: "High (per-event)"
+  metrics:
+    captures: "Numerical measurements over time / 隨時間變化的數值量測"
+    use_for: "Dashboards, alerting, capacity planning"
+    granularity: "Low (aggregated)"
+  traces:
+    captures: "Request flow across services / 跨服務的請求流"
+    use_for: "Latency analysis, dependency mapping"
+    granularity: "Medium (per-request)"
+
+correlation:
+  metric_to_trace: "Use Exemplars to link anomalous metric → specific trace"
+  trace_to_logs: "Use trace_id + span_id embedded in logs"
+  logs_to_metric: "Aggregate log patterns into metrics (e.g., error rate)"
+  key_fields: ["trace_id", "service.name"]
+
+# === METRIC TYPES 指標類型 ===
+metric_types:
+  counter:
+    behavior: "Monotonically increasing (resets on restart) / 只增不減"
+    examples: ["request count", "error count", "bytes sent"]
+  gauge:
+    behavior: "Point-in-time value, can go up or down / 當前值，可升可降"
+    examples: ["temperature", "queue depth", "active connections"]
+  histogram:
+    behavior: "Distribution across buckets / 跨桶分布"
+    examples: ["request duration", "response size"]
+  summary:
+    behavior: "Client-computed percentiles / 客戶端計算百分位"
+    examples: ["legacy systems needing client-side quantiles"]
+
+metric_type_decision:
+  only_goes_up: "→ Counter"
+  need_distribution: "→ Histogram"
+  current_state_value: "→ Gauge"
+  legacy_client_percentiles: "→ Summary"
+
+naming: "<domain>.<entity>.<action>.<unit>"
+# e.g., http.server.request.duration.seconds
+
+# === GOLDEN SIGNALS 黃金信號 ===
+golden_signals:
+  latency:
+    what: "Request duration P50/P95/P99 / 請求延遲"
+    metric: "http.server.request.duration.seconds"
+    alert: "P99 > threshold sustained 5 min"
+  traffic:
+    what: "Requests per second (RPS) / 每秒請求數"
+    metric: "http.server.request.total (Counter, rate)"
+    alert: "Sudden drop >50% or spike >200%"
+  errors:
+    what: "Error rate = 5xx / total / 錯誤率"
+    metric: "http.server.request.total{status=~'5..'}"
+    alert: "Error rate > X% sustained 5 min"
+  saturation:
+    what: "Resource utilization / 資源飽和度"
+    metrics: ["system.cpu.utilization", "system.memory.utilization", "db.client.connection.pool.usage"]
+    alert: "Resource > 80% sustained 10 min"
+
+# === MATURITY MODEL 成熟度模型 ===
+maturity:
+  L0_no_observability:
+    characteristics: "No structured logs; debugging via SSH + tail -f / 無結構化日誌"
+    upgrade: "Implement structured logging; centralize collection"
+  L1_basic_logging:
+    characteristics: "Structured JSON logs; centralized; basic search / 結構化日誌+集中收集"
+    upgrade: "Add business metrics; create first dashboard"
+  L2_metrics_driven:
+    characteristics: "Logs + Metrics; dashboards; basic alerting / 日誌+指標+儀表板"
+    upgrade: "Enable distributed tracing; SLO-based alerting"
+  L3_full_observability:
+    characteristics: "All three pillars; correlation; SLO alerts; Golden Signals / 三支柱完整"
+    upgrade: "Add anomaly detection; auto-remediation"
+  L4_intelligent:
+    characteristics: "AIOps; predictive alerting; automatic remediation / 智慧化可觀測"
+    upgrade: "Maintain, optimize, share learnings"
+
+self_assessment:
+  - "Can you find logs for a specific request across all services? (L1+)"
+  - "Can you view dashboards showing error rate and latency? (L2+)"
+  - "Can you trace a request from ingress to database and back? (L3+)"
+  - "Does your system auto-detect anomalies before users report? (L4)"
+
+# === INSTRUMENTATION CHECKLIST 儀器化清單 ===
+pre_production_checklist:
+  - "Structured logging enabled (JSON + trace_id)"
+  - "HTTP/gRPC entry metrics (count, duration histogram, error rate)"
+  - "Critical business operation custom metrics"
+  - "Distributed tracing enabled (sampling rate set, W3C headers)"
+  - "Health check endpoints (liveness + readiness)"
+  - "Dashboard covering Golden Signals"
+  - "Alert rules defined (SLO burn rate)"
+  - "Log retention configured"
+  - "Sensitive data excluded from logs/traces"
+```
+
+---
+
+## 与相关技能整合 / Integration with Related Skills
+
+| 技能 | 整合点 | 说明 |
+|-------|-------------------|-------------|
+| `/slo` | 基于 SLO 的告警 | 将 metrics 作为 SLI 数据源；burn rate 告警引用 Golden Signals |
+| `/incident` | 事件诊断 | 三大支柱提供诊断数据；关联分析加快 MTTD/MTTR |
+| `/observability --alerting` | 告警设计 | Golden Signals 为告警规则创建提供依据 |
+
+---
+
+## 配置检测
+
+### 检测顺序
+
+1. 检查 `CONTRIBUTING.md` 中是否有 "Disabled Skills" 区块
+2. 检查 `CONTRIBUTING.md` 中是否有 "Observability Standards" 区块
+3. 若未找到，**默认采用标准的可观测性实践**
+
+---
+
+## 详细指引
+
+完整标准请参阅：
+- [Observability Standards](../../core/observability-standards.md)
+- [Logging Standards](../../core/logging-standards.md)
+
+---
+
+## 相关标准
+
+- [Observability Standards](../../core/observability-standards.md) - 核心标准
+- [SLO Standards](../../core/slo-standards.md) - SLI/SLO/错误预算
+- [Alerting Standards](../../core/alerting-standards.md) - 告警设计
+- [Performance Standards](../../core/performance-standards.md) - 性能目标
+- [SLO Assistant](../slo-assistant/SKILL.md) - SLO 工作流程
+- [Runbook Assistant](../runbook-assistant/SKILL.md) - 运维操作流程
+
+---
+
+## 版本历史
+
+| 版本 | 日期 | 变更 |
+|---------|------|---------|
+| 1.0.0 | 2026-04-01 | 首次发布 |
+
+---
+
+## 许可证
+
+本技能依据 [CC BY 4.0](https://creativecommons.org/licenses/by/4.0/) 发布。
+
+**来源**：[universal-dev-standards](https://github.com/AsiaOstrich/universal-dev-standards)

package/bundled/locales/zh-CN/skills/orchestrate/SKILL.md

@@ -0,0 +1,173 @@
+---
+name: orchestrate
+source: ../../../../skills/orchestrate/SKILL.md
+source_version: 2.0.0
+translation_version: 2.0.0
+last_synced: 2026-06-02
+source_hash: 40e97479c7da
+scope: universal
+description: |
+  [UDS] 以 Claude 原生 Agent tool 编排多任务执行计划（DAG-based，无外部引擎）。
+  Use when: executing a plan.json file with parallel/sequential task dependencies.
+  Keywords: orchestrate, plan, execute, DAG, task plan, 编排, 执行计划, 并行.
+argument-hint: "<plan.json> [--dry-run]"
+---
+
+# /orchestrate — 任务计划编排 Skill
+
+> **语言**: [English](../../../../skills/orchestrate/SKILL.md) | 简体中文
+
+## 用法
+
+```
+/orchestrate <plan.json>           # 执行计划
+/orchestrate <plan.json> --dry-run # 仅验证，不执行
+```
+
+---
+
+## 执行流程
+
+### Step 1：读取与解析计划（Claude-native）
+
+使用 Read tool 读取 plan.json，直接由 Claude 解析：
+
+1. 读取 JSON 文件，解析为任务清单
+2. 验证结构：`tasks` 非空、每个 task 含 `id`、`title`、`spec`
+3. 安全扫描：检查 `task.spec` 是否含危险指令（`rm -rf /`、`DROP DATABASE`、`git push --force`）
+   - 若发现安全问题，列出所有问题并**询问用户是否继续**
+4. 拓扑排序：依 `depends_on` 字段将 tasks 分组为执行层（layers）
+   - Layer 0：没有依赖的 tasks（可并行）
+   - Layer N：依赖全部在 Layer 0..N-1 中的 tasks
+
+若 `validation.valid` 为 false，输出错误信息并停止。
+
+---
+
+### Step 2：呈现执行计划
+
+向用户显示解析结果：
+
+```
+计划：<project>  品质：<quality>
+──────────────────────────────────
+Layer 0 (并行)：T-001, T-002
+Layer 1 (序列)：T-003 (依赖 T-001)
+Layer 2 (序列)：T-004 (依赖 T-002, T-003)
+──────────────────────────────────
+共 4 个任务，3 个执行层
+```
+
+若使用 `--dry-run`：显示以上摘要后**立即停止**，不启动任何 Agent。
+
+---
+
+### Step 3：逐层执行
+
+对 `layers` 数组中的每一层：
+
+1. **同层并行**：同一层的 tasks 在同一消息中启动多个 Agent tool
+2. **Agent tool 参数**：
+   - `prompt`：task.spec + acceptance_criteria + user_intent 组合而成的执行提示
+   - `isolation: "worktree"`：每个 task 在独立 git worktree 执行
+   - `description`：`"Task {task.id}: {task.title}"`
+3. **等待完成**：所有同层 agents 完成后，才进入下一层
+
+**Agent 提示模板**：
+```
+Task: {task.title}
+
+Spec:
+{task.spec}
+
+Acceptance Criteria:
+{task.acceptance_criteria 逐条列出}
+
+User Intent:
+{task.user_intent}
+
+After completing the task, run: {task.verify_command}
+```
+
+---
+
+### Step 4：依赖失败处理
+
+如果某个 task 的 agent 回报失败：
+- 标记该 task 为 `failed`
+- 后续层中 `depends_on` 包含该 task ID 的所有 tasks 标记为 `skipped`
+- 继续执行不受影响的 tasks
+- 最终报告中标示失败原因
+
+---
+
+### Step 5：Quality Gate
+
+每个 task 完成后，若 task 定义了 `verify_command`：
+
+1. 使用 Bash tool 执行 `verify_command`
+2. **成功**：记录 `status: "success"`
+3. **失败**：
+   - 若 `quality` 为 `"strict"` 或 `"standard"`：启动 Fix Loop
+   - Fix Loop：将错误输出回传给 agent，重新执行（最多 3 次）
+   - 超过重试上限：标记为 `failed`
+
+---
+
+### Step 6：Judge 审查（可选）
+
+如果 task 定义了 `judge: true`：
+- 启动一个额外的 Agent tool 进行审查
+- 提示：`审查 task {id} 的 git diff，依照 code-review 标准检查`
+- Judge 结果附加到最终报告
+
+---
+
+### Step 7：产出报告
+
+汇整所有 task 结果，输出执行报告：
+
+```json
+{
+  "summary": {
+    "total_tasks": 4,
+    "succeeded": 3,
+    "failed": 1,
+    "skipped": 0,
+    "total_duration_ms": 120000
+  },
+  "tasks": [
+    { "task_id": "T-001", "status": "success", "duration_ms": 30000 },
+    { "task_id": "T-002", "status": "failed",  "error": "..." },
+    { "task_id": "T-003", "status": "skipped", "reason": "依赖任务失败" }
+  ]
+}
+```
+
+---
+
+## 品质配置档
+
+| Profile | 行为 |
+|---------|------|
+| `strict` | 全部检查 + Fix Loop 最多 5 次 |
+| `standard` | lint + test + Fix Loop 最多 3 次（默认） |
+| `minimal` | 仅跑 verify_command，不 Fix Loop |
+| `none` | 不执行任何验证 |
+
+---
+
+## 重要注意事项
+
+- 每个 Agent tool 的 `isolation: "worktree"` 会自动创建 git worktree
+- `depends_on: []` 的 tasks 在同一层内全部并行
+- 使用简体中文回复用户
+
+---
+
+## 版本历程
+
+| 版本 | 日期 | 变更 |
+|------|------|------|
+| 2.0.0 | 2026-04-28 | 升格为 UDS 正式 Skill；Step 1 改为 Claude-native 解析（移除 plan-resolver-cli.js 依赖）；新增 Quality Gate / Fix Loop 章节（XSPEC-097 Phase 3） |
+| 1.0.0 | 2026-04-09 | 初始发布（从上游迁移） |

package/bundled/locales/zh-CN/skills/plan/SKILL.md

@@ -0,0 +1,240 @@
+---
+name: plan
+source: ../../../../skills/plan/SKILL.md
+source_version: 2.0.0
+translation_version: 2.0.0
+last_synced: 2026-06-02
+source_hash: 6fbb1a1b8040
+scope: universal
+description: |
+  [UDS] 从 Spec 文档、OpenSpec 变更或自由文本需求生成 plan.json。
+  Use when: converting specifications into executable task plans for /orchestrate.
+  Keywords: plan, spec, task plan, 计划, 规格, 任务, plan.json, DAG.
+argument-hint: "[spec-file.md | openspec-dir/ | \"需求描述文本\" | (交互模式)]"
+---
+
+# /plan — 从 Spec 自动生成 plan.json
+
+> **语言**: [English](../../../../skills/plan/SKILL.md) | 简体中文
+
+## 用法
+
+```
+/plan <spec-file.md>              # Spec 模式（自有格式 / SpecKit）
+/plan <openspec-change-dir/>      # OpenSpec 模式
+/plan "需求描述文本"               # 需求模式
+/plan                             # 交互模式（自动检测）
+```
+
+---
+
+## 执行流程
+
+### Step 1：输入识别与格式检测
+
+根据参数类型判断使用模式：
+
+**参数是 .md 文件：**
+1. 读取文件内容
+2. 检测格式：
+   - 含 `## Requirements` **且** `## Technical Design` → **自有格式**（SPEC-NNN-*.md）
+   - 含 `## Summary` **且** `## Detailed Design` → **SpecKit 格式**
+   - 其他 .md → 尝试解析为通用 Spec（按自有格式处理，缺少的字段由 AI 补充）
+
+**参数是目录：**
+1. 检查是否含 `proposal.md` + `tasks.md` → **OpenSpec 格式**
+2. 否则报错：「此目录不符合 OpenSpec 结构」
+
+**参数是字符串描述（非文件路径）：**
+→ **需求模式**
+
+**无参数：**
+→ **交互模式**
+1. 检测 `openspec/` 目录存在？ → 列出 changes 让用户选择
+2. 检测 `specs/*.md` 存在？ → 列出可用 Spec 让用户选择
+3. 都没有 → 进入需求模式问答
+
+---
+
+### Step 2：项目 Context 收集
+
+读取目标项目的关键信息：
+
+1. **CLAUDE.md / AGENTS.md** — 语言、框架、测试工具、开发规范
+2. **package.json / pyproject.toml** — 可用 scripts（build, test, lint）
+
+从 Context 推断：
+- 主要语言（TypeScript / Python / 其他）
+- 默认 verify_command（如 `pnpm build && pnpm test`、`pytest -x`）
+- 默认 lint_command（如 `pnpm lint`、`ruff check .`）
+
+---
+
+### Step 3：Spec 解析
+
+依检测到的格式，解析 Spec 内容：
+
+#### 自有格式（SPEC-NNN-*.md）
+
+提取以下区段：
+- **Summary / Motivation** → 理解背景与需求动机
+- **Requirements (REQ-NNN)** → 功能需求列表
+- **Acceptance Criteria (AC-N)** → Given/When/Then 验收条件
+- **Technical Design** → Phase 分层、每个 Phase 的实现项目
+- **Test Plan** → 测试清单
+- **Risks** → 风险评估
+
+#### OpenSpec（change 目录）
+
+读取以下文件：
+- `proposal.md` → Why（动机）、What Changes（变更项目）、Impact
+- `tasks.md` → `- [ ]` checklist 项目
+- `design.md`（若存在）→ 技术决策
+- `specs/*/spec.md`（若存在）→ Requirements（SHALL / MUST 语句）、Scenarios
+
+#### SpecKit（SPEC-ID.md）
+
+提取以下区段：
+- **Summary / Motivation** → 背景
+- **Detailed Design** → 技术实现步骤
+- **Acceptance Criteria** → checkbox 验收条件
+- **Dependencies** → 外部依赖
+- **Risks** → 风险
+
+---
+
+### Step 4：Task 切分
+
+依格式套用不同映射规则：
+
+#### 自有格式映射规则
+
+| Spec 区段 | plan.json 字段 | 映射规则 |
+|-----------|---------------|----------|
+| Technical Design > Phase | 一组 tasks | 每个 Phase 的每个实现项目 = 1 个 task |
+| Phase 实现项目描述 | `task.spec` | 合并：项目描述 + 相关 REQ + 技术细节 |
+| Acceptance Criteria (AC-N) | `task.acceptance_criteria` | 分配到最相关的 task |
+| Summary / Motivation | `task.user_intent` | 提取与 task 最相关的意图 |
+| Test Plan | `task.verify_command` | 推断测试命令 |
+
+#### OpenSpec 映射规则
+
+| OpenSpec 文件 | plan.json 字段 | 映射规则 |
+|--------------|---------------|----------|
+| `tasks.md` 的 checklist 项目 | tasks | 每个 `- [ ]` 项目 = 1 个 task |
+| `proposal.md` > Why | `task.user_intent` | 所有 tasks 共用 |
+| `proposal.md` > What Changes | 融入 `task.spec` | 提供变更上下文 |
+| `design.md` 技术细节 | 融入 `task.spec` | 补充实现指引 |
+| `specs/*/spec.md` > Scenarios | `task.acceptance_criteria` | 每个 Scenario 映射为一条 criteria |
+| `specs/*/spec.md` > Requirements | 融入 `task.spec` | SHALL / MUST 语句转为具体实现指引 |
+
+---
+
+### Step 5：依赖推断
+
+为 tasks 建立 `depends_on` 关系：
+
+1. **Phase / Stage 顺序**：后面的 Phase 的第一个 task depends_on 前面 Phase 的最后一个 task
+2. **同 Phase 内顺序**：类型定义 → 实现 → 集成 → 测试
+3. **文件依赖**：A 创建的文件被 B import → B depends_on A
+4. **无依赖的 tasks**：`depends_on: []`（可并行）
+
+---
+
+### Step 6：verify_command 推断
+
+依以下优先顺序推断：
+
+1. **Test Plan / Scenarios 有明确测试项** → 对应测试命令
+2. **TypeScript 项目** → `pnpm build && pnpm test`
+3. **Python 项目** → `pytest -x`
+4. **其他** → 使用 Step 2 收集的项目 scripts
+5. **无法推断** → 不设（后续质量警告会提醒）
+
+---
+
+### Step 7：质量设置
+
+- 默认 `quality: "standard"`
+- 用户可在交互确认时调整
+
+---
+
+### Step 8：组装 plan.json
+
+```json
+{
+  "project": "<项目名称>",
+  "quality": "standard",
+  "defaults": {
+    "max_turns": 30,
+    "max_budget_usd": 2.0,
+    "verify_command": "<推断的默认验证命令>"
+  },
+  "tasks": [
+    {
+      "id": "T-001",
+      "title": "<task 标题>",
+      "spec": "<详细的 task 规格说明>",
+      "depends_on": [],
+      "verify_command": "<task 层级验证命令（可选）>",
+      "acceptance_criteria": ["<验收条件 1>"],
+      "user_intent": "<用户意图>"
+    }
+  ]
+}
+```
+
+**注意事项：**
+- Task ID 格式：`T-NNN`（如 T-001, T-002）
+- `spec` 字段应详尽——它是 agent 执行任务的唯一规格输入
+- `acceptance_criteria` 每条都必须是可观察、可验证的
+
+---
+
+### Step 9：验证（Claude-native）
+
+Claude 对 plan.json 执行以下验证（无需外部引擎）：
+
+1. **结构验证**：`tasks` 数组存在且非空、每个 task 含必填字段（id, title, spec）
+2. **DAG 合法性**：`depends_on` 中的所有 ID 均存在、无循环依赖
+3. **安全扫描**：task.spec 不含危险命令（`rm -rf /`、`DROP DATABASE`、`git push --force`）
+4. **质量警告**：task 缺少 verify_command、spec 过短（< 20 字）等
+
+若发现问题，在呈现前先自动修正（若可修正）或标示警告。
+
+---
+
+### Step 10：呈现与确认
+
+向用户呈现生成结果：
+
+1. **摘要表格**：
+   ```
+   | Task ID | 标题 | 依赖 | 验证命令 |
+   |---------|------|------|----------|
+   | T-001   | ...  | -    | ...      |
+   | T-002   | ...  | T-001| ...      |
+   ```
+
+2. **DAG 拓扑**：
+   ```
+   Layer 0: T-001, T-002（并行）
+   Layer 1: T-003（依赖 T-001）
+   Layer 2: T-004（依赖 T-002, T-003）
+   ```
+
+3. **质量设置**：`quality: standard`
+
+4. **质量警告**（若有）
+
+5. **询问用户**：确认或修改？确认后写入文件（默认路径：`plans/<spec-name>.plan.json`）
+
+---
+
+## 版本历程
+
+| 版本 | 日期 | 变更 |
+|------|------|------|
+| 2.0.0 | 2026-04-28 | 升格为 UDS 正式 Skill；移除 [DEVAP] 标记；Step 9 改为 Claude-native 验证（XSPEC-097 Phase 3） |
+| 1.0.0 | 2026-04-09 | 初始发布（从上游迁移） |