universal-dev-standards 4.2.0 → 5.0.0-beta.10

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

@@ -422,7 +422,7 @@ and this project adheres to [Semantic Versioning](https://semver.org/).
 
 ## 排除規則
 
-> **另見**：完整的排除規則，請參閱 [versioning.md](versioning.md#exclusion-rules--排除規則)。
+> **另見**：完整的排除規則，請參閱 [versioning.md](versioning.md#排除規則)。
 
 ### 核心原則
 

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

@@ -1,5 +1,5 @@
 ---
-source: core/checkin-standards.md
+source: ../../../core/checkin-standards.md
 source_version: 1.4.0
 translation_version: 1.4.0
 last_synced: 2026-01-16
@@ -67,10 +67,12 @@ pip install -r requirements.txt && python -m py_compile src/**/*.py
 
 ### 2. 測試驗證
 
-- [ ] **所有現有測試通過**
-  - Unit tests: 100% pass rate
-  - Integration tests: 100% pass rate
-  - End-to-end tests (if applicable): 100% pass rate
+- [ ] **所有相關測試通過**
+  - 單元測試：已修改模組的所有測試通過
+  - 整合測試：與已變更元件相關的所有測試通過
+  - 端對端測試（如適用）：所有關鍵路徑測試通過
+
+  > **注意**：「相關測試」指直接執行已變更程式碼的測試，以及可能受變更影響的測試。如有可用的測試影響分析工具，請使用。
 
 - [ ] **新程式碼已測試**
   - New features have corresponding tests
@@ -227,6 +229,17 @@ def authenticate(username: str, password: str) -> Optional[str]:
     """
 ```
 
+#### 適用性判斷標準
+
+使用此表格判斷選用項目何時適用：
+
+| 項目 | 何時適用 | 何時不適用 |
+|------|---------|-----------|
+| **README 更新** | 新增功能、設定變更、API 行為變更 | 內部重構、僅測試變更、依賴更新 |
+| **CHANGELOG 條目** | 使用者可見的變更、影響使用者的錯誤修復、重大變更 | 內部重構、僅測試變更、僅文件變更、開發依賴更新 |
+| **端對端測試** | 使用者流程變更、關鍵路徑受影響、整合點修改 | 純後端變更且無 UI 影響、獨立的工具函式 |
+| **API 文件** | 公開 API 變更、新增端點、參數含義變更 | 私有方法、內部工具、測試程式碼 |
+
 ---
 
 ### 5. 工作流程合規

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

@@ -1,5 +1,5 @@
 ---
-source: core/code-review-checklist.md
+source: ../../../core/code-review-checklist.md
 source_version: 1.3.0
 translation_version: 1.3.0
 last_synced: 2026-01-12

package/bundled/locales/zh-TW/core/commit-message-guide.md

@@ -1,5 +1,5 @@
 ---
-source: core/commit-message-guide.md
+source: ../../../core/commit-message-guide.md
 source_version: 1.2.3
 translation_version: 1.2.3
 last_synced: 2025-12-25

package/bundled/locales/zh-TW/core/developer-memory.md

@@ -0,0 +1,576 @@
+---
+source: ../../../core/developer-memory.md
+source_version: 1.0.0
+translation_version: 1.0.0
+last_synced: 2026-02-07
+status: current
+---
+
+# 開發者持久記憶標準
+
+> [English](../../../core/developer-memory.md) | **繁體中文**
+
+**版本**: 1.0.0
+**最後更新**: 2026-02-07
+**適用範圍**: 所有使用 AI 助手的軟體專案
+**範圍**: 通用 (Universal)
+**產業標準**: 無 (UDS 原創)
+
+---
+
+## 目的
+
+本標準定義了一套結構化系統，用於跨對話和跨專案捕獲、檢索和浮現開發者經驗洞察（陷阱、模式、反模式、心智模型等）。它使 AI 助手能夠主動利用累積的知識，減少重複錯誤並加速問題解決。
+
+---
+
+## 快速參考
+
+### 記憶條目 Schema（必填欄位）
+
+| 欄位 | 類型 | 說明 |
+|------|------|------|
+| `id` | string | 唯一識別碼（格式：`MEM-YYYY-NNNN`） |
+| `insight` | string | 一句話核心洞察 |
+| `category` | enum | 9 種分類之一（見 §2） |
+| `confidence` | float | 0.0–1.0，根據回饋動態調整 |
+| `created_at` | date | ISO 8601 日期 (YYYY-MM-DD) |
+
+### 記憶條目 Schema（選填欄位）
+
+| 欄位 | 類型 | 說明 |
+|------|------|------|
+| `context` | string | 適用的情境或環境 |
+| `anti_pattern` | string | 不應該做的事（錯誤做法） |
+| `resolution` | string | 如何修復或避免問題 |
+| `example` | object | `{bad: string, good: string}` — 程式碼或方法範例 |
+| `tags` | list | 自由搜尋標籤（如 `["async", "race-condition"]`） |
+| `applicability` | object | 語言/框架範圍（見 §6） |
+| `triggers` | list | 應觸發浮現此記憶的模式 |
+| `related` | list | 相關記憶條目的 ID |
+| `validity` | object | 生命週期中繼資料（見 §7） |
+
+### 統計欄位（自動管理）
+
+| 欄位 | 類型 | 說明 |
+|------|------|------|
+| `stats.times_surfaced` | int | 此記憶被顯示的次數 |
+| `stats.times_useful` | int | 正面回饋次數 |
+| `stats.times_not_useful` | int | 負面回饋次數 |
+| `stats.last_surfaced` | date | 最近一次推送時間 |
+
+### 回饋紀錄
+
+| 欄位 | 類型 | 說明 |
+|------|------|------|
+| `feedback[]` | list | 回饋條目陣列 |
+| `feedback[].date` | date | 回饋時間 |
+| `feedback[].result` | enum | `valid` / `invalid` / `needs-revision` |
+| `feedback[].note` | string | 可選的開發者備註 |
+
+---
+
+## 1. 記憶 Schema
+
+### 1.1 完整 Schema 定義
+
+```yaml
+# 記憶條目 - 完整 Schema
+id: "MEM-2026-0001"              # 必填：唯一 ID
+insight: "..."                    # 必填：一句話核心洞察
+category: pitfall                 # 必填：9 種類型之一
+confidence: 0.85                  # 必填：0.0–1.0
+created_at: "2026-02-07"         # 必填：ISO 日期
+
+# 選填欄位
+context: "在 Node.js 串流中使用 async iterators 時..."
+anti_pattern: "在未 await 前一個結果的情況下呼叫 next()"
+resolution: "始終 await 每個 next() 呼叫，或使用 for-await-of"
+example:
+  bad: "iterator.next(); iterator.next();"
+  good: "for await (const chunk of iterator) { ... }"
+tags: ["async", "streams", "node"]
+applicability:
+  languages: ["javascript", "typescript"]
+  frameworks: []
+  universal: false
+  exclusions: []
+triggers:
+  - "async iterator"
+  - "stream processing"
+  - "next() called multiple times"
+related: ["MEM-2026-0005"]
+validity:
+  type: versioned            # evergreen | versioned | temporal
+  version_bound: "node >= 18"
+  expires_at: null
+
+# 自動管理
+stats:
+  times_surfaced: 12
+  times_useful: 9
+  times_not_useful: 1
+  last_surfaced: "2026-02-01"
+feedback:
+  - date: "2026-01-15"
+    result: valid
+    note: "省了我 30 分鐘的除錯時間"
+```
+
+### 1.2 ID 格式
+
+| 組成 | 格式 | 範例 |
+|------|------|------|
+| 前綴 | `MEM` | `MEM` |
+| 年份 | `YYYY` | `2026` |
+| 序號 | `NNNN` | `0001` |
+| 完整 | `MEM-YYYY-NNNN` | `MEM-2026-0001` |
+
+ID 全域唯一。序號每年重置。
+
+---
+
+## 2. 記憶分類
+
+| 分類 | 說明 | 範例 |
+|------|------|------|
+| `pitfall` | 常見錯誤或陷阱 | 「以 0 為基礎的 API 分頁中的差一錯誤」 |
+| `pattern` | 已驗證的解決方案或最佳實踐 | 「使用 Builder 模式建構複雜物件」 |
+| `anti-pattern` | 已知的不良實踐 | 「處理所有業務邏輯的上帝物件」 |
+| `mental-model` | 理解概念的框架 | 「將 React state 視為快照，而非變數」 |
+| `workaround` | 已知問題的臨時修復 | 「為 npm 7+ 的 peer 衝突添加 `--legacy-peer-deps`」 |
+| `performance` | 效能洞察或優化 | 「頻繁查詢時使用 `Map` 取代 `Object`」 |
+| `debugging-strategy` | 診斷問題的方法 | 「使用 `git bisect` 二分搜尋 git 歷史」 |
+| `tool-usage` | 工具/函式庫技巧 | 「使用 `npx tsc --noEmit` 進行類型檢查而不建構」 |
+| `decision-rationale` | 做出特定決策的原因 | 「因交易支援而選擇 PostgreSQL 而非 MongoDB」 |
+
+---
+
+## 3. 四項操作
+
+### 3.1 記錄 (Record)
+
+#### 輸入流程
+
+1. 開發者以自然語言描述洞察
+2. AI 將其結構化為記憶 schema
+3. 開發者確認或編輯結構化條目
+4. 條目儲存至記憶庫
+
+#### 30 秒規則
+
+每個記憶條目必須回答三個問題：
+
+| 問題 | 對應欄位 |
+|------|---------|
+| 具體問題是什麼？ | `insight` |
+| 為什麼會發生？ | `context` + `anti_pattern` |
+| 如何修復/避免？ | `resolution` |
+
+#### 記錄層級
+
+| 層級 | 欄位 | 使用時機 |
+|------|------|---------|
+| 層級 1：快速 | `insight`, `category`, `tags` | 快速筆記，稍後完善 |
+| 層級 2：情境 | 層級 1 + `context`, `anti_pattern`, `resolution` | 標準記錄 |
+| 層級 3：完善 | 層級 2 + `example`, `triggers`, `applicability` | 重要且頻繁使用的洞察 |
+
+#### 去識別化
+
+儲存前，移除專案特定細節：
+
+| 移除 | 保留 |
+|------|------|
+| API 金鑰、密鑰 | 技術模式 |
+| 專案名稱、內部 URL | 框架/函式庫名稱 |
+| 團隊成員名稱 | 語言/版本資訊 |
+| 專有業務邏輯 | 通用業務邏輯模式 |
+
+### 3.2 查詢 (Query)
+
+#### 搜尋方法
+
+| 方法 | 說明 | 範例 |
+|------|------|------|
+| 關鍵字 | 跨 `insight`、`context`、`tags` 的自由文字搜尋 | `"async race condition"` |
+| 標籤 | `tags` 欄位的精確匹配 | `tags: ["react", "hooks"]` |
+| 分類 | 依分類類型篩選 | `category: pitfall` |
+| 語言 | 依 `applicability.languages` 篩選 | `languages: ["python"]` |
+| 信心度 | 依信心度閾值篩選 | `confidence >= 0.7` |
+| 組合 | 多重篩選組合 | `category: pitfall AND tags: ["react"]` |
+
+#### 查詢結果排序
+
+| 優先順序 | 標準 |
+|---------|------|
+| 1 | 與目前情境的相關性 |
+| 2 | 信心度分數（最高優先） |
+| 3 | 命中率 (`times_useful / times_surfaced`) |
+| 4 | 近期性 (`created_at` 最新優先) |
+
+### 3.3 回饋 (Feedback)
+
+#### 回饋動作
+
+| 動作 | 對 `confidence` 的影響 | 對 `stats` 的影響 |
+|------|----------------------|------------------|
+| `valid` | +0.05（上限 1.0） | `times_useful += 1` |
+| `invalid` | -0.15（下限 0.0） | `times_not_useful += 1` |
+| `needs-revision` | -0.05（下限 0.0） | 無變更 |
+
+#### 信心度調整規則
+
+| 條件 | 動作 |
+|------|------|
+| 連續 3 次 `valid` | 額外 +0.05 |
+| 連續 3 次 `invalid` | 標記待審查 |
+| `confidence < 0.2` | 標記待退役 |
+| `confidence > 0.9` 且使用 10+ 次 | 標記為「已驗證」 |
+
+### 3.4 審查 (Review)
+
+AI 掃描記憶庫並產生審查報告，涵蓋：
+
+#### 合併建議
+
+| 觸發條件 | 動作 |
+|---------|------|
+| 兩個條目語意相似度 >80% | 建議合併 |
+| 相同 `tags` + 相同 `category` + 相似 `insight` | 建議合併 |
+| 合併後繼承最高 `confidence` | 保留兩者回饋紀錄 |
+
+#### 退役建議
+
+| 觸發條件 | 動作 |
+|---------|------|
+| `confidence < 0.2` | 建議退役 |
+| 超過 180 天未浮現且 `confidence < 0.5` | 建議退役 |
+| 5+ 筆 `invalid` 回饋 | 建議退役 |
+
+#### 過時偵測
+
+| 觸發條件 | 動作 |
+|---------|------|
+| `validity.type == "versioned"` 且版本已過時 | 標記為過時 |
+| `validity.type == "temporal"` 且 `expires_at` 已過 | 標記為已過期 |
+| `validity.type == "evergreen"` | 跳過版本檢查 |
+
+#### 修訂建議
+
+| 觸發條件 | 動作 |
+|---------|------|
+| 2+ 筆 `needs-revision` 回饋 | 建議修訂 |
+| 高 `times_surfaced` 但低 `times_useful` 比率 | 建議修訂 |
+
+---
+
+## 4. 主動行為協議
+
+### 4.1 記憶浮現（主動浮現）
+
+#### 何時浮現
+
+| 時機 | 行為 |
+|------|------|
+| 對話開始 | 掃描記憶庫，顯示與所述任務最相關的前 3 個 |
+| 開發過程中 | 偵測程式碼模式、錯誤訊息或技術決策是否匹配 `triggers` |
+| 提交前 | 浮現與已變更檔案/模式相關的陷阱 |
+
+#### 浮現規則
+
+| 規則 | 值 | 理由 |
+|------|---|------|
+| 相關性閾值 | > 0.7 | 避免鬆散相關記憶的雜訊 |
+| 冷卻期 | 每條目 7 天 | 防止重複建議 |
+| 每次觸發上限 | 3–5 條 | 防止資訊過載 |
+| 溢出處理 | AI 歸納為分組洞察 | 當 > 5 個匹配時 |
+
+#### 浮現格式
+
+```
+💡 記憶匹配 [MEM-2026-0042]（信心度：0.85）
+分類：pitfall | 標籤：async, promise
+洞察：Promise.all 在第一個失敗時就會拒絕 — 使用 Promise.allSettled 取得部分結果
+情境：處理批次 API 呼叫且可接受部分成功時
+```
+
+### 4.2 記憶萃取（主動萃取）
+
+#### 觸發信號
+
+AI 應偵測這些開發者信號並建議記錄：
+
+| 信號 | 範例 |
+|------|------|
+| 重複修改 | 同一程式碼區塊被編輯 3+ 次 |
+| 還原 | `git revert` 或手動復原 |
+| 洞察語言 | 「喔！」、「我懂了」、「原來」、「終於」、「the trick is...」 |
+| 長時間除錯 | 同一錯誤超過 10 分鐘 |
+| 掙扎後的解決方案 | 錯誤 → 多次嘗試 → 解決 |
+
+#### 萃取流程
+
+```
+1. AI 偵測信號
+2. AI 提議：「看起來你發現了某些東西。要記錄這個洞察嗎？」
+3. AI 根據對話情境預先結構化條目
+4. 開發者確認/編輯/跳過
+5. 若確認 → 儲存至記憶庫
+```
+
+### 4.3 記憶聚合（主動聚合）
+
+#### 聚合觸發
+
+| 觸發條件 | 動作 |
+|---------|------|
+| 3+ 個相關的 `pitfall` 條目 | 建議歸納為 `mental-model` |
+| 5+ 個相同標籤的條目 | 建議建立主題摘要 |
+| 關於同一概念的分散片段 | 建議整合 |
+
+#### 升級路徑
+
+```
+多個陷阱 → 模式 → 心智模型
+（片段）    （解決方案）  （理解）
+```
+
+---
+
+## 5. 雜訊控制
+
+### 推送層級
+
+| 層級 | 名稱 | 行為 |
+|------|------|------|
+| 0 | 靜默 | 從不推送；僅回應查詢 |
+| 1 | 摘要 | 顯示計數：「找到 3 個相關記憶。要查看嗎？」 |
+| 2 | 主動（預設） | 顯示前 3 個及一行摘要 |
+| 3 | 詳細 | 顯示完整條目，含情境和範例 |
+
+### 雜訊降低規則
+
+| 規則 | 說明 |
+|------|------|
+| 回饋驅動 | 若使用者標記 3+ 個浮現記憶為 `invalid`，降至層級 1 |
+| 會話尊重 | 使用者說「現在不要」後，當前會話切換至層級 0 |
+| 信心度篩選 | 僅浮現 `confidence >= 0.5` 的條目 |
+| 已驗證偏好 | 優先顯示「已驗證」狀態的條目（confidence > 0.9，10+ 次使用） |
+
+---
+
+## 6. 跨語言適用性
+
+### 適用性 Schema
+
+```yaml
+applicability:
+  languages: ["javascript", "typescript"]  # 適用語言（空 = 通用）
+  frameworks: ["react", "next.js"]          # 適用框架（空 = 任何）
+  universal: false                           # true = 適用所有語言
+  exclusions: ["rust"]                       # 明確不適用的語言
+```
+
+### 適用性規則
+
+| 情境 | `universal` | `languages` | `exclusions` |
+|------|-------------|-------------|--------------|
+| 適用所有語言 | `true` | `[]` | `[]` |
+| 特定語言 | `false` | `["python", "ruby"]` | `[]` |
+| 除部分語言外全部適用 | `true` | `[]` | `["c", "assembly"]` |
+| 特定框架 | `false` | `["javascript"]` | `[]` |
+
+---
+
+## 7. 知識生命週期
+
+### 有效性類型
+
+| 類型 | 說明 | 過時檢查 |
+|------|------|---------|
+| `evergreen` | 始終適用（如演算法洞察） | 無 |
+| `versioned` | 綁定特定版本（如 API 行為） | 檢查 `version_bound` |
+| `temporal` | 有時效（如 bug 的暫時修復） | 檢查 `expires_at` |
+
+### 有效性 Schema
+
+```yaml
+validity:
+  type: versioned          # evergreen | versioned | temporal
+  version_bound: "react >= 18"  # 用於 versioned 類型
+  expires_at: "2026-12-31"      # 用於 temporal 類型
+```
+
+### 信心度生命週期
+
+```
+新條目：confidence = 0.5（預設）
+    ↓ valid 回饋
+成長中：0.5 → 0.7 → 0.85
+    ↓ 持續正面使用
+已驗證：0.9+（經過 10+ 次浮現）
+    ↓ invalid 回饋 / 過時
+下降中：0.85 → 0.6 → 0.3
+    ↓ 退役閾值
+已退役：confidence < 0.2
+```
+
+### 退役條件
+
+條目在以下任何條件下被標記為退役：
+
+- `confidence < 0.2`
+- 超過 180 天未浮現且 `confidence < 0.5`
+- 5+ 筆 `invalid` 回饋
+- `validity.type == "temporal"` 且 `expires_at` 已過
+- `validity.type == "versioned"` 且版本不再使用
+
+已退役條目被封存（非刪除）以供歷史參考。
+
+---
+
+## 8. 指標
+
+### 關鍵指標
+
+| 指標 | 公式 | 健康範圍 |
+|------|------|---------|
+| 命中率 | `times_useful / times_surfaced` | > 0.6 |
+| 回饋率 | `(valid + invalid) / times_surfaced` | > 0.3 |
+| 庫增長 | 每月新增條目 | 5–20 |
+| 退役率 | 每月退役條目 | < 新增的 20% |
+| 覆蓋率 | 有 5+ 條目的分類數 | 9 種分類中 6+ |
+
+### 健康指標
+
+| 指標 | 良好 | 警告 | 需要處理 |
+|------|------|------|---------|
+| 平均信心度 | > 0.6 | 0.4–0.6 | < 0.4 |
+| 命中率 | > 0.6 | 0.3–0.6 | < 0.3 |
+| 過時條目 | < 10% | 10–25% | > 25% |
+| 孤立條目（從未浮現） | < 15% | 15–30% | > 30% |
+
+---
+
+## 9. 儲存格式
+
+### 推薦：依分類 YAML
+
+```
+.memory/
+├── pitfall.yaml
+├── pattern.yaml
+├── anti-pattern.yaml
+├── mental-model.yaml
+├── workaround.yaml
+├── performance.yaml
+├── debugging-strategy.yaml
+├── tool-usage.yaml
+├── decision-rationale.yaml
+└── _index.yaml          # ID 登錄與交叉參考
+```
+
+#### 檔案大小建議
+
+| 每檔條目數 | 建議 |
+|-----------|------|
+| < 100 | 每分類一個 YAML 檔 |
+| 100–500 | 依分類內子主題分割 |
+| > 500 | 考慮 JSONL 格式 |
+
+### 替代方案：JSONL
+
+大型記憶庫可使用每分類一個 JSONL 檔：
+
+```
+.memory/
+├── pitfall.jsonl
+├── pattern.jsonl
+└── ...
+```
+
+每行是一個代表一個記憶條目的完整 JSON 物件。
+
+### 索引檔 (`_index.yaml`)
+
+```yaml
+# 記憶索引
+last_id: "MEM-2026-0042"
+total_entries: 42
+by_category:
+  pitfall: 12
+  pattern: 8
+  anti-pattern: 5
+  mental-model: 3
+  workaround: 4
+  performance: 3
+  debugging-strategy: 2
+  tool-usage: 3
+  decision-rationale: 2
+```
+
+---
+
+## 相關標準
+
+- [反幻覺標準](anti-hallucination.md) — 證據導向分析適用於記憶來源
+- [AI 指令標準](ai-instruction-standards.md) — Token 效率優化的記憶系統指令格式
+- [AI 友善架構](ai-friendly-architecture.md) — 支援記憶整合的專案結構
+- [文件撰寫標準](documentation-writing-standards.md) — 記憶條目的撰寫品質
+
+---
+
+## 10. 架構決策：Always-On Protocol
+
+### 分類
+
+開發者持久記憶被分類為 **Always-On Protocol**，而非使用者觸發的工作流。
+
+| 模式 | 特性 | 範例 | 需要 Skill？ |
+|------|------|------|------------|
+| **使用者觸發** | 使用者明確調用、多步驟引導式工作流 | `/commit`、`/review`、`/sdd` | 是 |
+| **Always-On Protocol** | AI 載入 ai.yaml 後持續遵循規則 | 反幻覺、開發者記憶 | 否 |
+
+### 理由：不需要 CLI / Skill / 斜線命令
+
+| 元件 | 決策 | 理由 |
+|------|------|------|
+| CLI 命令 (`uds memory ...`) | **不需要** | 核心操作（語意匹配、洞察萃取、信心度調整）需要 LLM 智能；CLI 只能做字串匹配 |
+| Skill (`skills/developer-memory/`) | **不需要** | `developer-memory.ai.yaml` 已自足，包含完整 schema + 規則 + 主動協議 |
+| `/memory add`、`/memory search` | **不需要** | 與「主動行為」設計理念矛盾 — AI 應自動萃取和浮現 |
+| `/memory review` | **延後** | 唯一可能有用的命令；延後至使用者回饋表明需要時 |
+
+### 無需額外工具即可運作
+
+```
+AI 載入 developer-memory.ai.yaml
+    ↓
+規則自動啟動：
+  - proactive-surfacing：在情境匹配時浮現相關記憶
+  - proactive-extraction：偵測洞察時刻，提議記錄
+  - proactive-aggregation：建議合併相關條目
+  - noise-control：尊重推送層級和冷卻期
+    ↓
+不需要明確的使用者觸發
+```
+
+### 未來考量
+
+如果使用者回饋揭示：
+- **發現性不足**：考慮輕量級 Skill（配置偵測 + 發現性）
+- **明確的審查需求**：考慮 `/memory review` 斜線命令
+- **永遠不需要**：`uds memory add/search` CLI 命令 — 這些操作本質上需要 LLM
+
+---
+
+## 版本歷史
+
+| 版本 | 日期 | 變更 |
+|------|------|------|
+| 1.0.0 | 2026-02-07 | 初始標準：schema、4 項操作、主動協議、雜訊控制、架構決策（Always-On Protocol） |
+
+---
+
+## 授權
+
+本標準依 [CC BY 4.0](https://creativecommons.org/licenses/by/4.0/) 發布。