universal-dev-standards 5.16.0 → 6.0.0

package/bundled/locales/zh-TW/core/cd-deployment-strategies.md

@@ -0,0 +1,135 @@
+---
+source: ../../../core/cd-deployment-strategies.md
+source_version: 1.0.0
+translation_version: 1.0.0
+last_synced: 2026-06-10
+source_hash: 0eeb697c2f07
+status: current
+---
+
+# CD Deployment Strategies（CD 部署策略）
+
+> **Language**: [English](../../../core/cd-deployment-strategies.md) | 繁體中文
+
+## 概述
+
+本標準定義四種主要部署策略的選用矩陣：Blue-Green、Canary、Rolling、Recreate。幫助團隊根據流量規模、風險容忍度和基礎設施成本，做出一致且有據可查的策略選擇。
+
+---
+
+## 核心原則
+
+- **三維決策**：根據流量規模 × 風險容忍度 × 基礎設施成本選擇策略
+- **禁止直接推產**：任何變更都必須先通過 staging 環境驗證
+- **零停機目標**：除非為內部工具或開發環境，否則應追求零停機部署
+
+---
+
+## 策略選用矩陣
+
+| 策略 | 流量規模 | 風險容忍度 | 基礎設施成本 | 停機時間 | 回滾時間 |
+|------|---------|----------|------------|---------|---------|
+| Blue-Green | 高 | 低 | 高 | 零 | < 30 秒 |
+| Canary | 中至高 | 中 | 中 | 零 | < 2 分鐘 |
+| Rolling | 任意 | 中 | 低 | 極少 | 數分鐘 |
+| Recreate | 低 | 高 | 極低 | 數秒至數分鐘 | 數分鐘 |
+
+---
+
+## 各策略詳細說明
+
+### Blue-Green
+
+**適用場景**：有狀態服務、資料庫相容性變更、高 SLA API
+
+**運作方式**：
+- 維護兩個完全相同的環境（Blue = 現有線上版，Green = 新版本）
+- 完整部署並驗證 Green 環境後，切換 Load Balancer 流量
+- 問題發生時立即切回 Blue
+
+**前置條件**：雙環境基礎設施、Load Balancer、健康檢查
+
+---
+
+### Canary
+
+**適用場景**：功能驗證、A/B 測試、高風險變更
+
+**流量漸進比例**：1% → 5% → 25% → 50% → 100%
+
+**運作方式**：
+- 先將少量流量導向新版本
+- 監控指標，符合自動晉升規則則繼續擴大
+- 發現問題立即縮回 0%
+
+**前置條件**：流量切分機制、可觀測性、自動晉升規則
+
+---
+
+### Rolling
+
+**適用場景**：無狀態服務、標準更新、批次工作者
+
+**運作方式**：
+- 依序更新每個實例，更新前進行健康檢查
+- 允許新舊版本短暫共存
+- 資源效率最佳，但回滾需時較長
+
+**前置條件**：多個服務實例、健康檢查
+
+---
+
+### Recreate
+
+**適用場景**：開發/測試環境、內部工具、單一實例服務
+
+**運作方式**：
+- 停止所有現有實例，部署新版本，重新啟動
+- 最簡單，但有停機時間
+
+**前置條件**：無（最低門檻）
+
+---
+
+## 決策樹
+
+```
+Q1: 需要零停機時間？
+  → 否 → Recreate
+  → 是 → Q2
+
+Q2: 流量 > 10k req/min？
+  → 是 → Q3（Blue-Green 或 Canary）
+  → 否 → Rolling
+
+Q3: 變更屬於高風險？
+  → 是 → Canary
+  → 否 → Q4
+
+Q4: 基礎設施預算有限？
+  → 是 → Rolling
+  → 否 → Blue-Green
+```
+
+---
+
+## 無 CI/CD 環境的替代做法
+
+| 策略 | 替代方案 |
+|------|---------|
+| Blue-Green | 參見 no-cicd-deployment.ai.yaml 的 Shell Script 實作 |
+| Canary | 使用 Nginx `split_clients` 或 HAProxy 做流量切分 |
+| Rolling | 使用順序式 rsync + 健康檢查迴圈 |
+| Recreate | 最簡單 — 停止、部署、啟動 |
+
+---
+
+## 相關標準
+
+- [deployment-standards.md](../../../core/deployment-standards.md) — 部署基礎原則
+- [rollback-standards.md](../../../core/rollback-standards.md) — 回滾觸發條件矩陣
+- [no-cicd-deployment.md](../../../core/no-cicd-deployment.md) — 無 CI/CD 部署策略
+- AI 格式：[../../../ai/standards/cd-deployment-strategies.ai.yaml](../../../ai/standards/cd-deployment-strategies.ai.yaml)
+
+
+**Scope**: universal

package/bundled/locales/zh-TW/core/chaos-injection-tests.md

@@ -0,0 +1,130 @@
+---
+source: ../../../core/chaos-injection-tests.md
+source_version: 1.0.0
+translation_version: 1.0.0
+last_synced: 2026-06-10
+source_hash: 4aaf84b1c84c
+status: current
+---
+
+# 混沌注入測試
+
+> **語言**: [English](../../../core/chaos-injection-tests.md) | 繁體中文 | [简体中文](../../zh-CN/core/chaos-injection-tests.md)
+
+## 概述
+
+混沌注入測試使失敗情境可機器驗證。`chaos-engineering-standards` 描述實驗方法論，而本標準定義 AI Agent 系統所需的具體測試——LLM 逾時、資料庫斷線、策略引擎失效，以及爆炸半徑控制。
+
+## 為什麼 AI Agent 系統需要專屬的混沌測試
+
+傳統軟體只有少數外部依賴。AI Agent 系統使這一情況更加複雜：
+
+- **LLM API**：高延遲、速率限制、非確定性失敗
+- **策略引擎**（OPA/Rego）：安全關鍵——必須在失敗時關閉
+- **向量儲存 / 知識庫**：檢索失敗影響輸出品質
+- **資料庫**：操作中途斷線可能損壞多步驟的 Agent 狀態
+- **對等 Agent**：在多 Agent 管線中，一個 Agent 崩潰不得串聯影響其他 Agent
+
+上述每種失敗模式都需要專屬測試，而不僅僅是操作手冊中的一句說明。
+
+## 需求摘要
+
+| ID | 規則 | 依據 |
+|----|------|-----------|
+| REQ-CIT-001 | 每個外部依賴需要一個失敗隔離測試 | 單一依賴失敗不得串聯 |
+| REQ-CIT-002 | LLM 客戶端必須處理逾時和速率限制 | LLM 是最高風險依賴 |
+| REQ-CIT-003 | 策略引擎不可用時必須預設為 DENY | 開放式失敗是安全漏洞 |
+| REQ-CIT-004 | 操作中途資料庫斷線必須乾淨回滾 | 部分寫入會造成資料損毀 |
+| REQ-CIT-005 | Agent 崩潰不得傳播至不相關的 Agent | Agent 間爆炸半徑必須有界 |
+
+## 注入模式
+
+### LLM 逾時
+
+```typescript
+it('surfaces TimeoutError when LLM does not respond in time', async () => {
+  const slowLlm = { complete: () => new Promise(() => {}) } // never resolves
+  const agent = new PlannerAgent({ llm: slowLlm, timeoutMs: 100 })
+  await expect(agent.run(input)).rejects.toThrow('TimeoutError')
+})
+```
+
+### LLM 速率限制（429）
+
+```typescript
+it('retries with backoff on 429 and eventually surfaces RateLimitError', async () => {
+  const rateLimitedLlm = mockLlm({ status: 429, retryAfter: 1 })
+  const agent = new PlannerAgent({ llm: rateLimitedLlm })
+  await expect(agent.run(input)).rejects.toThrow('RateLimitError')
+  expect(rateLimitedLlm.callCount).toBeLessThanOrEqual(3) // respects retry policy
+})
+```
+
+### 策略引擎停機（失敗關閉）
+
+```typescript
+it('returns DENY when OPA sidecar is unavailable', async () => {
+  const downOpa = { query: () => Promise.reject(new Error('ECONNREFUSED')) }
+  const guardian = new GuardianAgent({ opa: downOpa })
+  const result = await guardian.review(reviewable)
+  expect(result.decision).toBe('DENY')
+  expect(result.reason).toMatch(/policy engine unavailable/)
+})
+```
+
+### 資料庫斷線
+
+```typescript
+it('rolls back transaction on mid-operation DB disconnect', async () => {
+  const db = createTestDb()
+  await seedRows(db, [{ id: 1, name: 'alice' }])
+  
+  // Force disconnect after first write in the transaction
+  let writeCount = 0
+  const hookedDb = hookAfterWrite(db, () => {
+    if (++writeCount === 1) db.close()
+  })
+  
+  await expect(runner.executeWithDb(hookedDb, plan)).rejects.toThrow()
+  
+  const freshDb = createTestDb()
+  const rows = freshDb.prepare('SELECT * FROM records').all()
+  expect(rows).toHaveLength(1) // original row preserved, partial write rolled back
+})
+```
+
+### Agent 崩潰控制
+
+```typescript
+it('pipeline continues when one agent throws', async () => {
+  const crashingAgent = { run: () => { throw new Error('agent crash') } }
+  const pipeline = new Pipeline({ agents: { planner: crashingAgent, builder: realBuilder } })
+  
+  const result = await pipeline.run(input, { skipFailedAgents: true })
+  expect(result.completedAgents).toContain('builder')
+  expect(result.failedAgents).toContain('planner')
+})
+```
+
+## 安全規則
+
+1. 絕對不要對生產環境或共享的測試資料庫執行混沌測試
+2. 在 `afterEach` 或 `finally` 區塊中始終清理注入的故障
+3. 為混沌測試加上標籤（`@chaos`），以在開發工作流程的快速單元測試執行中排除
+4. 混沌測試可在 CI 的專屬工作中執行，不納入標準單元測試矩陣
+
+## 反模式
+
+- **在主處理器中捕獲並忽略所有錯誤** — 這會對斷言隱藏混沌失敗
+- **斷線後不驗證資料庫狀態** — 僅斷言錯誤被拋出是不夠的；必須斷言沒有寫入部分資料
+- **開放式策略引擎處理** — 策略路徑中的任何模糊情況都必須解析為 DENY，而非 ALLOW
+
+## 另請參閱
+
+- `chaos-engineering-standards.ai.yaml` — 實驗方法論與 SLO 整合
+- `testing.ai.yaml` — 通用測試結構
+- `secure-op.ai.yaml` — AI Agent 的失敗關閉原則
+- `security-standards.ai.yaml` — 安全不變量
+
+
+**Scope**: universal

package/bundled/locales/zh-TW/core/checkin-standards.md

@@ -3,7 +3,7 @@ source: ../../../core/checkin-standards.md
 source_version: 1.6.0
 translation_version: 1.6.0
 last_synced: 2026-04-20
-status: current
+status: stale
 ---
 
 # 程式碼簽入檢查點標準

package/bundled/locales/zh-TW/core/code-review-checklist.md

@@ -3,7 +3,7 @@ source: ../../../core/code-review-checklist.md
 source_version: 1.3.0
 translation_version: 1.3.0
 last_synced: 2026-01-12
-status: current
+status: stale
 ---
 
 # 程式碼審查檢查清單

package/bundled/locales/zh-TW/core/container-image-standards.md

@@ -0,0 +1,93 @@
+---
+source: ../../../core/container-image-standards.md
+source_version: 1.0.0
+translation_version: 1.0.0
+last_synced: 2026-06-17
+source_hash: ac8280a5b7cf
+status: current
+---
+
+# 容器映像建構與安全標準
+
+> **Language**: [English](../../../core/container-image-standards.md) | 繁體中文
+
+> **版本**: 1.0.0 | **狀態**: Active | **更新日期**: 2026-06-17
+> **AI 最佳化版本**: `ai/standards/container-image-standards.ai.yaml`
+> **規格**: XSPEC-065（cross-project/specs/XSPEC-065-uds-infrastructure-pack.md）
+
+## 概觀
+
+本標準定義容器映像建構管線的安全與合規要求。涵蓋五項 Dockerfile 撰寫原則（多階段
+建構、非 root 執行、最小基底映像、無秘密的 build args、SBOM metadata）、使用 `syft`
+或 `trivy` 進行 SBOM 生成與嵌入，以及封鎖 Critical／High CVE 的映像掃描政策。
+
+本標準屬於 **IaC 標準包**（XSPEC-065），並透過聚焦於供應鏈安全與合規認證
+（attestation）來補足既有的 `containerization-standards`（layer 排序與標記）。
+
+> **範圍**：本標準定義生產映像必須保證的事項（rootless、最小化、已掃描、SBOM
+> 認證）以及 CVE 的*嚴重度政策*。具體的 SBOM 工具（`syft`／`trivy`）、掃描器與
+> registry 屬採用者的選擇，不在本標準範圍內。
+
+## 需求
+
+| ID | 規則 | 等級 |
+|----|------|------|
+| REQ-001 | Dockerfile 五原則（多階段、非 root、最小基底、無秘密、SBOM label） | MUST |
+| REQ-002 | SBOM 嵌入（於 CI 生成、嵌入或認證、保留 ≥12 個月） | MUST |
+| REQ-003 | 映像掃描（Critical／High 封鎖；Medium 開單；自動基底更新） | MUST |
+
+### REQ-001 — Dockerfile 五原則
+
+每個生產 Dockerfile MUST 遵循五項原則：(1) **多階段建構**——分離 builder 與 runtime
+階段，以最小化最終映像大小與攻擊面；(2) **非 root 最終使用者**——runtime 階段 MUST
+設定非 root `USER`（UID ≥ 1000）；生產容器中以 root 執行為禁止；(3) **Distroless 或
+Alpine 基底**——最終階段使用 distroless（`gcr.io/distroless`）或 Alpine 基底映像以
+最小化 CVE 曝險；除非有正當理由並文件化，否則避免完整 Debian／Ubuntu；(4) **無硬
+編碼秘密**——build ARGs 與 ENV 變數 MUST NOT 含秘密；秘密於執行期透過 volume mount
+或 secret manager 注入（見 `secret-management-standards`）；(5) **SBOM metadata
+label**——最終映像 MUST 包含 OCI label `org.opencontainers.image.source` 及含 git
+commit SHA 的建構期 label `org.opencontainers.image.revision`。
+
+### REQ-002 — SBOM 嵌入
+
+每個生產容器映像 MUST 在 CI 建構步驟生成軟體物料清單（SBOM），使用 `syft` 或
+`trivy` 以 CycloneDX 或 SPDX 格式產出。SBOM MUST 為以下其一：(a) 嵌入為 OCI 映像
+annotation（OCI 相容 registry 的首選），或 (b) 以 `cosign` attestation 附加於映像
+digest。SBOM 產物 MUST 與映像一同儲存於容器 registry，並至少保留 12 個月供合規稽核。
+
+### REQ-003 — 映像掃描
+
+所有容器映像在推送至生產 registry 前 MUST 掃描已知 CVE，使用整合於 CI 管線的
+`trivy`、`grype` 或同等工具。嚴重度政策：**Critical 與 High** CVE MUST 封鎖建構並
+阻止晉升至生產；**Medium** CVE MUST 產生警告並建立追蹤工單；**Low 與 Negligible**
+CVE 僅供參考。當上游映像收到 CVE 修補時，基底映像更新 MUST 自動觸發（例如以
+Dependabot 或 Renovate 處理 Dockerfile 基底映像 pin）。
+
+## 反模式
+
+- 在生產 Dockerfile 對基底映像使用 `latest` 標籤（不可重現建構）。
+- 在最終 runtime 階段以 root（UID 0）執行容器程序。
+- 將秘密嵌入會殘留於映像 layer 的 Docker build ARGs 或 ENV 變數。
+- 為節省 CI 時間而略過 SBOM 生成，喪失供應鏈可追溯性。
+- 未經 CVE 掃描結果即推送映像至生產。
+
+## 與既有標準的整合
+
+- **`containerization-standards`**——涵蓋 layer 排序與標記；本標準在其上加上供應鏈
+  安全與認證層。
+- **`secret-management-standards`**——執行期秘密注入取代任何 ARGs／ENV 中的建構期
+  秘密（REQ-001 原則 4）。
+- **`supply-chain-security-standards`**——此處的 SBOM 與 CVE 掃描政策是更廣供應鏈
+  態勢的容器映像面向。
+- **`iac-design-principles`**——映像建構／晉升本身即是版本化、可重現的基礎設施。
+
+## 相關規格
+
+- XSPEC-065 — UDS 基礎設施（IaC）標準包（本標準來源）
+- DEC-043 — UDS 覆蓋完整性路線圖（Wave 4 範圍）
+
+## 變更紀錄
+
+| 版本 | 日期 | 變更 |
+|------|------|------|
+| v1.0.0 | 2026-06-17 | 初版——REQ-001~003：Dockerfile 五原則、SBOM 嵌入、映像掃描（XSPEC-065） |