القائمة
整理 CHANGELOG（自上一版 tag 至 HEAD），產出雙語草稿供使用者 review。當使用者提到「整理 CHANGELOG」、「準備發版」、「draft changelog」、「發 v4.x.x」、「下一版要發了」、「整理 release notes」之類情境時使用。
التثبيت باستخدام Codex أو Claude انسخ هذا Prompt والصقه في Codex أو Claude أو مساعد آخر ليراجع صفحة Skill ويثبّتها لك.
استنادا إلى تصنيف SOC المهني
bee-library 新增框架快取物件的完整跨檔流程，分兩類——Define 定義快取（來源是定義檔，經 IDefineAccess）與 Database 資料庫相依快取（來源是 DB，經 ICacheDataSourceProvider 自載 + cache-notify 失效）。含 ObjectCache vs KeyObjectCache 決策樹、ICacheContainer + CacheContainerService 三處同步、兩個 CacheNotify 測試 stub（漏補必 CS0535）、DI 相依環的延遲解析與 cache-notify 失效鏈。當使用者要「新增快取物件」、「加一個 cache」、「快取某定義 / 資料庫資料」、「KeyObjectCache / ObjectCache」、「cache-notify 失效」、「判權限/查設定要零 DB」之類需求時使用。
為 bee-library 加一個新的 samples/ 專案，內含前端類型選擇（Console / Blazor Server / Avalonia / WinForms）、後端配對決策樹（QuickStart.Server / in-process Local）、auth 需求判斷、`Bee.Samples.slnx` 整合、README 樣板與 ProjectReference 預設值。當使用者要「新增一個 sample」、「加一個 demo」、「為某個 src 套件做 demo」之類需求時使用。
對 `samples/<Sample.Name>/` 的 demo 跑一輪端到端冒煙測試（透過 computer-use 點擊 UI 元素、驗證關鍵畫面），以宣告 demo 在本機跑得通。讀取 `samples/<Sample.Name>/.smoke.yaml` 設定檔。當使用者要「跑 demo」、「驗證 sample」、「demo 跑得通嗎」、「smoke test sample」之類需求時使用。
對 bee-library 框架做「全面體檢」的可重複方法論 —— 九面向(架構分層、相依分層與循環相依、安全性、維護性、散落/不必要類別、序列化一致性、公開 API 表面、測試品質與覆蓋、文件漂移)唯讀審查,以平行子代理分面向掃描(非抽樣),交叉去重後彙整成分級(P0~P4)重構計畫 + 每項 10 分制評分。內建各面向的具體檢查清單、已知雷區、與「應為乾淨」的基準項(供回歸偵測)。當使用者要「全面體檢」、「架構體檢」、「健康檢查/健康度」、「framework review」、「全面 review」、「架構審查」、「幫框架打分/評分」、「有沒有散落或不必要的類別」、「提重構計畫」之類需求時使用,即使沒明講「體檢」也要在這類全框架審查請求時主動觸發。**只負責唯讀審查、評分與產出重構計畫,不直接改 code**(修正另循一般流程)。
bee-library 新增對外公開的 BO 方法（FormBusinessObject / SystemBusinessObject）跨 contract / wire / BO / Repository / Client 共 7~8 個檔案的完整流程，含 3 條硬性規則、層別樣板、兩層 round-trip 測試與最終 checklist。當使用者要「新增 BO 方法」、「為 progId.action 加 API」、「FormBO/SystemBO 加方法」、「實作 GetList / Insert / Update / Delete」之類需求時使用。
在一個已接好的 Bee.NET app 上「加一張表單」的多檔流程與避雷 —— 一張可用的 CRUD 表單 = 4 處純定義修改（FormSchema + TableSchema + DbCategorySettings 註冊 + ProgramSettings 上選單），不寫 UI / CRUD 程式碼。涵蓋 4 檔 checklist（漏哪個會有什麼徵兆）、business 表用 company scope、TableSchema 資料夾必須 = CategoryId、FormSchema 慣例（lookup 的 RelationProgId+RelationFieldMappings+ref_* RelationField、master-detail 的 sys_master_rowid、DropDownEdit+ListItems、計算欄 FormField.ReadOnly、sys_name 可省）、何時才需要自訂 BO。當使用者要「加一張表單 / 主檔 / 單據」、「新增一個 ProgId / 畫面」、「為某張表做 CRUD」、「Bee 表單要怎麼定義 lookup / 明細 / 下拉 / 唯讀欄」之類需求時使用，即使沒明講「加表單」也要主動觸發。
| name | changelog-draft |
| description | 整理 CHANGELOG（自上一版 tag 至 HEAD），產出雙語草稿供使用者 review。當使用者提到「整理 CHANGELOG」、「準備發版」、「draft changelog」、「發 v4.x.x」、「下一版要發了」、「整理 release notes」之類情境時使用。 |
整理自上一版 tag 至 HEAD 的所有 commits，產出符合 Keep a Changelog 格式的雙語 CHANGELOG 條目（中／英），由使用者 review 後再走 ~/.claude/rules/releasing.md 流程發版。
CHANGELOG.md、繁中版 CHANGELOG.zh-TW.md，必須同步更新Directory.Build.props／打 tag —— 這些屬 releasing.md 流程，等使用者 review 完才動手docs/ 是現行框架對齊版（forward-looking）、docs/adr/ 是設計決策史、CHANGELOG.md 是版本差紀錄；三者互補，CHANGELOG 條目對應重大行為改動時應連結對應 ADR並行執行：
git tag --sort=-creatordate | head -3 # 取最近三個 tag，確認上版
git log <prev_tag>..HEAD --pretty=format:'%h %s' # 取 subject 概覽
git log <prev_tag>..HEAD --pretty=format:'%h%n%s%n%b%n---END---' # 取完整訊息（含 body）
git status # 確認沒有 uncommitted changes
若有 uncommitted changes，先告知使用者並停下來確認（避免漏掉未進版的變更）。
若 <prev_tag>..HEAD 為空（沒有新 commit），明確告訴使用者「無變更，不需發版」並結束。
依 commit subject 前綴判斷：
| 前綴 | 分類 | 是否進 user-facing CHANGELOG |
|---|---|---|
feat: / feat(scope): | 新增 | ✅ 必入 |
feat!: 或 commit body 含 BREAKING CHANGE: | 變更（breaking） | ✅ 必入，且需寫升級指引 |
fix: | 修正 | ✅ 必入 |
perf: | 變更（效能） | ✅ 必入 |
refactor: | 視情況 | ⚠️ 改到公開 API / 命名空間 / 預設行為才入；純內部重構 omit |
docs: / test: / chore: / build: / ci: / style: | 多半 omit | ⚠️ 除非影響使用者（如：發版前升級套件依賴版本、改變預設設定值） |
核心判斷原則：這個變更會讓使用者的 csproj / using / 程式碼 / XML 設定檔需要改嗎？
模糊情境的處理：
refactor 改了 internal 但有公開 API surface 變化 → 列入| Commits 內容 | 建議升版 |
|---|---|
| 任一 breaking change | major（e.g. 5.0.0） |
| 至少一個 feat（無 breaking） | minor（e.g. 4.4.0） |
| 僅 fix / perf / 內部變動 | patch（e.g. 4.3.1） |
Pre-stable 例外：本框架明文允許在 minor 中包含 API 搬遷（見 v4.3.0 changelog 開頭說明）。即使依嚴格 SemVer 為 major，pre-stable 政策下可建議 minor，附理由讓使用者拍板。
對重大行為改動（breaking / 新模組 / 架構搬遷），掃 docs/adr/ 目錄找對應條目：
ls /Users/jeff/Desktop/repos/bee-library/docs/adr/ | grep -i <關鍵字>
例如 v4.3.0 的 AddBeeFramework 搬至 Bee.Hosting → 對應 ADR-011 DI replaces service locator。
若找不到對應 ADR 但屬重大改動，標註「⚠️ 建議補 ADR」給使用者，不自動建立。
採「兩層：主檔精簡條目 + per-version 明細檔」結構（2026-06-24 確立）。每次發版同時產兩種輸出：
(A) 主 CHANGELOG（精簡，雙語兩檔） —— CHANGELOG.md / CHANGELOG.zh-TW.md：
## [4.x.0]
> 主題引言（1–3 句）＝這版的重點摘要。承載「為什麼這版重要」與整體脈絡，
> 是讀者掃讀時唯一需要看的敘事。pre-stable 期間若版本性質特殊（如嚴格 SemVer
> 屬 major、政策下以 minor 發佈）也在此一句帶過。
📄 詳細變更與設計脈絡：[docs/changelogs/4.x.0.md](docs/changelogs/4.x.0.md)
### 新增
- `<套件>`：<一行 WHAT，含關鍵 API／namespace>。
### 變更
- `<套件>`：<一行差異>。重大設計決策連結 ADR：[ADR-011](docs/adr/adr-011-di-replaces-service-locator.md)
### 修正
- `<套件>`：<一行 bug fix>。
### 升級指引（僅 breaking 才需要）
\`\`\`diff
+ using Bee.NewNs;
- using Bee.OldNs;
\`\`\`
(B) 明細檔（完整敘事，單語兩檔） —— 每版兩個檔，與主 CHANGELOG 的雙檔結構對稱：
docs/changelogs/<版號>.md（英文，如 docs/changelogs/4.11.0.md）
docs/changelogs/<版號>.zh-TW.md（繁中，如 docs/changelogs/4.11.0.zh-TW.md）
每檔頂部加標題 + 語言切換導覽列：[English](<版號>.md) ・ [繁體中文](<版號>.zh-TW.md) ・ [← CHANGELOG](../../CHANGELOG.md)（繁中檔的 ← CHANGELOG 指向 ../../CHANGELOG.zh-TW.md），再一句說明「本檔是 CHANGELOG [x.x.0] 條目的詳細版」
內容＝主檔精簡前的完整版：每條 bullet 保留多句 WHY／設計權衡／受影響範圍、升級指引含標題式情境說明
結構與主檔逐節對齊（破壞性變更／安全性／新增／變更／修正／升級指引），讓讀者能在主檔一行條目與明細檔展開版之間對照
參考既有範本：docs/changelogs/4.11.0.md + docs/changelogs/4.11.0.zh-TW.md
精簡原則（主檔，最重要，避免條目膨脹）：
> 主題引言；完整敘事 → 明細檔 docs/changelogs/<版號>.md（英）/ <版號>.zh-TW.md（繁中）；深層設計理由 → docs/adr/diff，散文說明進明細檔docs/changelogs/<版號>.md 明細，2026-06-24 一次補齊）；發新版時沿用此結構，不需再回頭改舊版雙語規則：
CHANGELOG.md）條目用動詞原形或 套件： 句首；繁中版（CHANGELOG.zh-TW.md）逐條對齊翻譯<版號>.md）與繁中檔（<版號>.zh-TW.md）逐節對應；CHANGELOG.md 連到 <版號>.md、CHANGELOG.zh-TW.md 連到 <版號>.zh-TW.md寫入位置：
docs/changelogs/<版號>.md + docs/changelogs/<版號>.zh-TW.md完成後給使用者一份簡短報告：
~/.claude/rules/releasing.md 走後續流程（更新 Directory.Build.props、commit、push tag）」src/Directory.Build.props 的 <Version> —— 屬 releasing.md 步驟releasing.md 步驟