@pcircle/claude-code-buddy-mcp 2.5.2 → 2.6.0

package/README.zh-TW.md

@@ -1,266 +1,131 @@
-# Claude Code Buddy (CCB)
-
-🌐 **網站:** [ccb.pcircle.ai](https://ccb.pcircle.ai) | **語言版本:** [English](README.md) | 繁體中文
-
----
-
-> **讓 Claude Code 記住你的專案、從你的回饋中學習，並提供專家級的回應,無需專家級的提示。**
-
-Claude Code Buddy 是一個 Claude Code Plugin，為 Claude Code 增加智能、記憶和任務路由功能 - 將它從強大的助手轉變為具備專案意識的 AI 團隊成員。
+<div align="center">
 
----
+# 🧠 Claude Code Buddy (CCB)
 
-## 問題所在
+### **唯一會記住一切的 MCP Server**
 
-你使用 Claude Code 來建構專案，但不斷遇到相同的挫折：
+**讓 Claude Code 記住所有事情。開發更快。Vibe 更爽。**
 
-- **「我們不是討論過這個嗎？」** - Claude 在不同 session 之間會忘記上下文
-- **「為什麼我要再解釋一次？」** - 每次對話都從零開始
-- **「這個答案太泛化了」** - 無論你是在除錯、審查程式碼還是設計 UI，回應都一樣
-- **「讓我再寫一次這 50 行提示...」** - 常見任務需要重複的指令
+[![GitHub Stars](https://img.shields.io/github/stars/PCIRCLE-AI/claude-code-buddy?style=social)](https://github.com/PCIRCLE-AI/claude-code-buddy)
+[![npm version](https://img.shields.io/npm/v/@pcircle/claude-code-buddy-mcp)](https://www.npmjs.com/package/@pcircle/claude-code-buddy-mcp)
+[![License](https://img.shields.io/badge/license-AGPL--3.0-blue.svg)](LICENSE)
+[![MCP](https://img.shields.io/badge/MCP-1.25.3-purple.svg)](https://modelcontextprotocol.io)
 
-**結果你成了 Claude 的記憶和專案經理，而不是專注於建構。**
+[🚀 快速開始](#-2-分鐘快速開始) • [📖 文檔](docs/) • [🌐 官網](https://ccb.pcircle.ai) • [💬 討論區](https://github.com/PCIRCLE-AI/claude-code-buddy/discussions)
 
 ---
 
-## 解決方案
-
-Claude Code Buddy 位於你和 Claude Code 之間，增加三項超能力：
-
-### 1. 🧠 **專案記憶**
-
-CCB 記住你的架構決策、編碼模式和過去的解決方案。問「為什麼我們選擇 PostgreSQL？」，你會得到實際的決策理由 - 而不是泛泛的比較。
-
-### 2. 🎯 **智能任務路由**
-
-你的請求會被分析並路由到正確的「專家模式」 - 程式碼審查任務獲得程式碼審查專業知識，除錯獲得系統化除錯方法，前端獲得 UI/UX 最佳實踐。
-
-### 3. 🎯 **能力導向引導**
-
-CCB 會依任務類型與專案情境調整提示詞，讓審查、除錯、設計等工作都有適切的結構與防護欄。
-
-**結果：** 專家級回應無需專家級提示。持續的上下文。聚焦且可執行的引導。
-
-### CCB 所謂的「隨你的專案演化」究竟是什麼意思？
-
-CCB 不會重訓模型或修改 Claude 本身。
-
-相反地，演化來自於 Claude Code Plugin 內部的 **持久化系統層**：
-
-• **專案記憶累積**
-架構決策、慣例和已解決的討論都被儲存為結構化的上下文。
-
-• **模式強化**
-重複的批准、重構和偏好的解決方案逐漸塑造未來提示詞的建構方式。
-
-• **任務類型區分**
-審查、除錯、重構和設計任務使用不同的內部提示策略處理。
-
-• **上下文重用，而非重複**
-選擇性地注入相關記憶，避免提示詞過其臃腫，同時保持連續性。
-
-隨著時間推移，Claude Code 的回應變得：
-• 更符合你的慣例
-• 跨會話更一致
-• 較少依賴冗長的提示詞
-
-這是一種 *透過系統記憶和路由的行為演化*，而非模型微調。
+</div>
 
 ---
 
-## 實際運作
+## 🤔 問題所在
 
-**沒有 CCB：**
+你一定經歷過這種痛苦：
 
 ```
-你：「優化這個資料庫查詢」
-Claude：[關於索引和查詢結構的泛化建議]
+Session 1: "讓我解釋一下我們的架構..."
+Session 2: "就像我之前說的，我們的架構..."
+Session 3: "我剛剛提到過，我們的架構..."
+Session 4: 😤
 ```
 
-**有了 CCB：**
-
-```
-你：「優化這個資料庫查詢」
-
-CCB 分析：資料庫優化任務
-CCB 路由到：資料庫優化能力
-CCB 用以下內容增強提示：資料庫最佳實踐、索引策略、性能分析技術
-
-Claude：[針對你的資料庫設定的具體優化建議，包含實際查詢範例
-         和基於你的 schema 的性能基準測試]
-```
-
-**差異：** CCB 了解你的技術堆疊，記住你的 schema，並提供目標性的專業知識。
+**每。一。次。都。要。重複。**
 
 ---
 
-## 如何使用 CCB
+## ✨ 解決方案
 
-安裝完成後，CCB 有 **兩種使用方式**：
+<table>
+<tr>
+<td width="50%" valign="top">
 
-### 🔄 自動模式（正常對話即可）
+### ❌ **使用 CCB 之前**
 
-CCB 在背景自動增強你的請求，不需要特別的指令：
-
-```
-你：「檢查這段程式碼的安全性問題」
-     ↓
-CCB 自動執行：
-  • 偵測任務類型 → 程式碼審查
-  • 路由到 → 程式碼審查能力
-  • 增強提示詞 → 安全檢查清單、最佳實踐
-     ↓
-Claude 回應專業的安全審查結果
-```
+- 每次 session 都要重新解釋架構
+- 重複回答相同問題
+- 隔天就忘記設計決策
+- 一直寫類似的提示詞
+- Claude 有失憶症 🤕
 
-**像平常一樣使用 Claude Code** - CCB 在背景默默提升回應品質。
+</td>
+<td width="50%" valign="top">
 
-### 🎮 Buddy 指令（明確控制）
+### ✅ **使用 CCB 之後**
 
-當你需要特定 CCB 功能時，使用這些指令：
+- **記住**專案架構
+- **瞬間回想**過去決策
+- **自動整理**知識
+- **智能路由**任務
+- Claude 成為你的 AI 隊友 🤝
 
-| 指令 | 功能 | 範例 |
-|------|------|------|
-| `buddy-do` | 智能路由執行任務 | `buddy-do "建立使用者認證系統"` |
-| `buddy-remember` | 搜尋專案記憶 | `buddy-remember "為什麼選擇 PostgreSQL"` |
-| `buddy-help` | 取得指令說明 | `buddy-help remember` |
-
-### 💾 專案記憶
-
-專案記憶會自動記錄。使用 `buddy-remember` 召回關鍵決策與近期進度。
-
-### 📋 快速參考卡
-
-```
-┌─────────────────────────────────────────────────────────────┐
-│  CCB 快速參考                                                │
-├─────────────────────────────────────────────────────────────┤
-│  🔄 自動模式（正常對話即可）                                   │
-│     • 「審查這段程式碼」→ 路由到程式碼審查能力                 │
-│     • 「幫我除錯這個錯誤」→ 路由到除錯能力                     │
-│     • 「設計一個元件」→ 路由到介面設計能力                     │
-├─────────────────────────────────────────────────────────────┤
-│  🎮 BUDDY 指令                                               │
-│     buddy-do "任務"         智能路由執行                      │
-│     buddy-remember "查詢"   搜尋專案記憶                      │
-│     buddy-help [指令]       取得說明                          │
-├─────────────────────────────────────────────────────────────┤
-│  🧭 工作流程                                                  │
-│     get-session-health     檢查上下文健康度                   │
-│     get-workflow-guidance  取得下一步建議                     │
-│     generate-smart-plan    產生實作計畫                       │
-└─────────────────────────────────────────────────────────────┘
-```
+</td>
+</tr>
+</table>
 
 ---
 
-## 核心功能
+## 🎯 核心功能
 
-### ✨ 自動專業知識路由
+### 1. 🧠 **真正有用的專案記憶**
 
-CCB 會依照能力訊號自動路由至內部專家。你只要描述需求即可。
-
-**涵蓋能力範圍：**
-- 程式碼審查、安全稽核與最佳實踐
-- 除錯與根因分析
-- 重構與技術債處理
-- API 設計、後端架構、資料庫優化
-- 測試策略與測試產生
-- 效能分析與最佳化
-- UI/UX 設計與技術文件
-- 研究、產品與規劃支援
-
-### 💾 記憶系統
-
-**知識圖譜**
-
-```
-你：「為什麼我們選擇這個架構？」
-CCB：[回憶決策、考慮過的替代方案和權衡]
-```
-
-**專案上下文**
+```bash
+# Session 1（上週）
+你: "我們選擇 PostgreSQL 是因為 JSONB 支援"
 
+# Session 42（今天）
+你: buddy-remember "為什麼選 PostgreSQL？"
+CCB: "根據你在 2024-01-15 的決策：選擇 PostgreSQL 是因為
+      JSONB 支援和進階查詢能力..."
 ```
-CCB 記住：
-- 你的編碼標準
-- 命名慣例
-- 專案特定模式
-- 你已經建構的內容
-```
-
-### 🎯 能力導向引導與回應聚焦
 
-CCB 依任務複雜度與類型，路由到適合的能力配置，調整提示詞結構與檢查重點。
+**Claude 記住了。永遠。**
 
-**運作方式**：TaskAnalyzer 檢查你的請求 → 評估複雜度（1-10）→ 路由到最佳能力配置 → 回應更聚焦、更可執行。
-
-**實際範例**：「修正這個錯字」走最短流程，「設計認證系統」走架構設計與風險檢視流程，「審查這個 PR」走安全與品質清單。
-
-### 🤝 使用者友善的命令
+### 2. 🎯 **智能任務路由（自動駕駛模式）**
 
 ```bash
-# 自然語言命令，就是這麼簡單
-buddy-do "setup authentication"
-buddy-do "optimize this database query"
-buddy-remember "how we implemented login"
-buddy-help
+你: "Review 這段程式碼"
+CCB: *偵測任務類型*
+     *啟動程式碼審查模式*
+     *套用最佳實踐*
+     *提供結構化審查*
 ```
 
-### 🔄 智能工作流程引導
+**不用再問「我該怎麼做？」直接開始做。**
 
-**CCB 知道下一步是什麼。** 你寫完程式碼後，它建議執行測試。測試通過後，它建議程式碼審查。不需要手動思考。
+### 3. 💬 **超簡單命令**
 
-```
-你寫程式碼 → CCB：「程式碼看起來不錯！下一步執行測試？」
-測試通過 → CCB：「測試通過！準備好進行程式碼審查？」
-審查完成 → CCB：「審查完成！提交並推送？」
+```bash
+buddy-do "設定身份驗證"          # 執行任何開發任務
+buddy-remember "API 設計"        # 查詢專案記憶
+buddy-help                       # 需要幫助時
 ```
 
-**工作流程工具：**
+**三個命令。無限可能。**
 
-- `get-workflow-guidance` - 獲得下一步建議
-- `get-session-health` - 檢查 session 健康狀態
+---
 
-**優勢：** 永不疑惑「我接下來該做什麼？」- CCB 引導你完成整個開發流程。
+## 🚀 2 分鐘快速開始
 
-### 📋 智能實作規劃
+### 步驟 1：安裝（選擇你的 IDE）
 
-**將複雜功能分解為小型任務。** CCB 生成 TDD 結構化計畫，具備能力感知的任務分解。
+<details>
+<summary><strong>🎯 Cursor 使用者</strong>（點擊展開）</summary>
 
+只需點擊這個魔法連結：
 ```
-你：「規劃使用者身份驗證的實作」
-CCB：[生成逐步計畫，包含：
-  - 測試優先方法
-  - 2-5 分鐘的任務
-  - 每個任務的正確能力
-  - 明確的成功標準]
+cursor://anysphere.cursor-deeplink/mcp/install?name=@pcircle/claude-code-buddy-mcp&config=eyJjb21tYW5kIjoibnB4IiwiYXJncyI6WyIteSIsIkBwY2lyY2xlL2NsYXVkZS1jb2RlLWJ1ZGR5LW1jcCJdfQ==
 ```
 
-**規劃工具：**
-
-- `generate-smart-plan` - 創建智能實作計畫
-
----
+**完成。**重啟 Cursor 就好了。
 
-## 快速開始（2 分鐘）
+</details>
 
-### 🚀 一鍵安裝
-
-#### Cursor 用戶
-
-<a href="cursor://anysphere.cursor-deeplink/mcp/install?name=@pcircle/claude-code-buddy-mcp&config=eyJjb21tYW5kIjoibnB4IiwiYXJncyI6WyIteSIsIkBwY2lyY2xlL2NsYXVkZS1jb2RlLWJ1ZGR5LW1jcCJdfQ==">
-  <img src="https://cursor.com/deeplink/mcp-install-dark.png" alt="安裝到 Cursor" />
-</a>
-
-**點擊上方按鈕或在瀏覽器貼上此連結：**
-```
-cursor://anysphere.cursor-deeplink/mcp/install?name=@pcircle/claude-code-buddy-mcp&config=eyJjb21tYW5kIjoibnB4IiwiYXJncyI6WyIteSIsIkBwY2lyY2xlL2NsYXVkZS1jb2RlLWJ1ZGR5LW1jcCJdfQ==
-```
+<details>
+<summary><strong>⚡ Claude Code 使用者</strong>（點擊展開）</summary>
 
-#### VS Code / Claude Code 用戶
+將這段加到 `~/.claude/mcp_settings.json`：
 
-**快速 MCP 配置**（加入到 `~/.claude/mcp_settings.json`）：
 ```json
 {
   "mcpServers": {
@@ -272,308 +137,265 @@ cursor://anysphere.cursor-deeplink/mcp/install?name=@pcircle/claude-code-buddy-m
 }
 ```
 
-然後重啟 Claude Code 即可開始使用 CCB！
+**重啟 Claude Code** 就搞定了。
 
-**📖 詳細安裝指南**：參見 [QUICK_INSTALL.md](docs/QUICK_INSTALL.md)
+</details>
 
----
-
-### 前置需求
-
-- Node.js 20+ ([下載](https://nodejs.org/))
-- Claude Code 已安裝 ([在這裡取得](https://claude.com/claude-code)) 或 Cursor IDE
-
-### 手動安裝（替代方案）
+### 步驟 2：測試
 
 ```bash
-# 1. 複製儲存庫
-git clone https://github.com/PCIRCLE-AI/claude-code-buddy.git
-cd claude-code-buddy
+# 在 Claude Code/Cursor 中輸入：
+buddy-help
 
-# 2. 執行互動式安裝程式（它會處理所有事情）
-./scripts/install.sh
-```
+# 你應該會看到 CCB 的命令列表
+# 現在試試：
+buddy-do "解釋 CCB 功能"
 
-安裝程式會引導你完成 **9 個互動式步驟**：
+# 見證魔法 ✨
+```
 
-**核心設定（步驟 1-7）**：
+**🎉 就這樣！開始 vibe 吧。**
 
-- ✓ 檢查前置需求（Node.js 20+、npm；git 可選）
-- ✓ 安裝相依性
-- ✓ 建構專案
-- ✓ 檢查系統資源
-- ✓ 設定環境
-- ✓ 設定 Claude Code MCP 整合
-- ✓ 測試安裝
+📖 **需要幫助？**[詳細安裝指南](docs/QUICK_INSTALL.md) | [疑難排解](docs/TROUBLESHOOTING.md)
 
-**互動式展示（步驟 8-9）**：
+---
 
-- 📚 **步驟 8：基本使用展示** - 了解 CCB 的智能路由、範例提示與記憶功能
-- ✅ **步驟 9：MCP 驗證** - 確認 MCP 伺服器可連線
+## 💡 實際使用場景
 
-**在 MCP 伺服器模式下不需要 API 金鑰** - 使用你現有的 Claude Code 訂閱。
+### 場景 1：**開發新功能**
 
-**可選設定**（只有在需要調整預設值時才需要）：
 ```bash
-cp .env.example .env
-# 若要以獨立 orchestrator 模式執行：
-# MCP_SERVER_MODE=false
-# ANTHROPIC_API_KEY=your_key_here
+你: buddy-do "建立 WebSocket 即時聊天"
+
+CCB 會：
+✅ 記住你的技術棧（React, Node.js 等）
+✅ 套用你過去的程式碼模式
+✅ 生成符合你風格的程式碼
+✅ 自動記錄這次設計決策供未來使用
 ```
 
-### 開始使用
+### 場景 2：**「等等，我們為什麼這樣做？」**
 
-重新啟動 Claude Code，然後嘗試：
+```bash
+你: buddy-remember "身份驗證方式"
 
+CCB 立即回想：
+📚 3 週前的 JWT vs Session 討論
+💻 你寫的實作程式碼
+🔧 你決定的錯誤處理模式
 ```
-「分析我的程式碼庫架構」
-「為 auth.ts 生成測試」
-「審查這段程式碼是否有安全問題」
-「優化這個資料庫查詢」
-```
-
-CCB 會自動將任務路由到正確的能力，並用相關上下文增強提示。
-
----
 
-## 運作原理
+### 場景 3：**持續開發流程**
 
 ```
-你的請求
-    ↓
-CCB 分析任務
-    ↓
-路由到最佳能力類型（例如程式碼審查、除錯）
-    ↓
-用專業上下文增強提示
-    ↓
-Claude Code 用你的訂閱執行
-    ↓
-系統從你的選擇中學習（當你覆蓋建議時）
+第 1 天：「實作使用者登入」
+        ↓ CCB 記住所有事情
+第 5 天：「新增密碼重設」
+        ↓ CCB 回想第 1 天的架構
+第 10 天：「新增 OAuth 支援」
+        ↓ CCB 知道前兩次的設計
 ```
 
-**幕後：**
+**再也不用重複解釋 context。**
 
-- **內部專家體系**：以能力訊號驅動路由與提示增強
-- **智能路由**分析任務複雜度並選擇最佳能力配置
-- **演化系統**從你的選擇中學習並持續改進建議
+---
 
-**技術深入探討：** 參見 [docs/README.md](docs/README.md)
+## 📊 CCB vs 其他工具
 
-**API 文檔：** 參見 [docs/api/API_REFERENCE.md](docs/api/API_REFERENCE.md)
+| 功能 | 純 Claude Code | 其他 MCP 工具 | CCB |
+|------|---------------|--------------|-----|
+| **持久化記憶** | ❌ | ⚠️ 基本功能 | ✅ **完整知識圖譜** |
+| **智能路由** | ❌ | ❌ | ✅ **自動偵測任務類型** |
+| **Vibe Coding 優化** | ⚠️ | ❌ | ✅ **專為此打造** |
+| **零設定** | ✅ | ⚠️ 複雜 | ✅ **2 分鐘** |
+| **免費開源** | ✅ | ⚠️ 不一定 | ✅ **AGPL-3.0** |
 
 ---
 
-## CCB 擅長什麼 ✅
+## 🛠️ 進階功能
 
-- **使 Claude Code 具備專案意識**針對你的特定專案
-- **減少重複提示**透過智能任務路由
-- **在不同 session 之間記憶**使用持久記憶系統（知識圖譜 + 專案上下文）
-- **提供專業知識**無需你撰寫專家級提示
-- **保持回應聚焦**透過路由到適合的能力配置
-- **從你的選擇中學習**當你覆蓋建議時
-- **引導你的工作流程**透過智能下一步建議
-- **協調複雜工作流程**跨越多個步驟
-- **跨平台支援**無縫支援 Windows、macOS 和 Linux
-- **生產就緒**具備全面測試、安全性強化和資源保護
+<details>
+<summary><strong>自動記憶系統</strong></summary>
 
-## 誠實的限制 ⚠️
+當你使用 `buddy-do` 時，CCB 會自動記錄：
+- ✅ 任務目標和結果
+- ✅ 技術決策和理由
+- ✅ 遇到的錯誤和解決方案
+- ✅ 開發里程碑
 
-- **不是魔法** - 仍然需要你提供明確的需求
-- **不是學習的替代品** - 你應該了解你在建構什麼
-- **增強 Claude Code，不是取代它** - 與你現有的設定一起運作
-- **需要設定** - 2 分鐘安裝，不是一鍵完成（還沒有）
-- **早期階段（v2.2）** - 預期會有粗糙的地方，但正在積極改進
-- **受 Claude 能力限制** - 無法讓 Claude 做不可能的事
+**你不用想記憶的事。CCB 會處理。**
 
-**理念：** 我們對什麼有效、什麼無效保持誠實。如果某些東西對你不起作用，請告訴我們 - 這個回饋會讓所有人都受益。
+</details>
 
----
+<details>
+<summary><strong>多專案支援</strong></summary>
 
-## 使用案例
+每個專案都有獨立的記憶空間。
 
-### 程式碼審查
+```bash
+cd ~/project-A
+buddy-remember "auth"  # 回傳 project-A 的 auth 決策
 
-```
-「審查這個 PR 是否有安全漏洞和程式碼品質問題」
-→ 路由到程式碼審查能力
-→ 獲得安全檢查清單 + 品質標準
-→ 返回詳細審查，包含具體建議
+cd ~/project-B
+buddy-remember "auth"  # 回傳 project-B 的 auth 決策
 ```
 
-### 除錯
+**絕不會混淆。**
 
-```
-「這個函式在 undefined 時崩潰，幫助除錯」
-→ 路由到除錯能力
-→ 獲得系統化除錯方法
-→ 逐步進行根本原因分析
-```
+</details>
 
-### 前端設計
+<details>
+<summary><strong>17 個 MCP 標準工具</strong></summary>
 
-```
-「設計一個具有深色模式的響應式儀表板」
-→ 路由到介面設計能力
-→ 獲得 UI/UX 模式 + 無障礙性指南
-→ 返回完整設計，包含響應式斷點
-```
+完整整合 Model Context Protocol。
 
-### 資料庫優化
+查看完整列表：[ToolDefinitions.ts](src/mcp/ToolDefinitions.ts)
 
-```
-「這個 Prisma 查詢需要 2 秒，優化它」
-→ 路由到資料庫優化能力
-→ 獲得查詢優化模式 + 索引策略
-→ 返回優化的查詢，包含性能基準測試
-```
+</details>
 
 ---
 
-## 進階功能
+## 🧪 技術細節
 
-- **自訂技能** - 用 TypeScript 撰寫你自己的路由行為
-- **多步驟規劃** - 將複雜任務分解為可執行的計劃
-- **工作流程協調** - 自動檢查點檢測和下一步建議
-- **儀表板** - 即時指標、session 健康監控、性能追蹤
+<table>
+<tr>
+<td width="50%">
 
-**探索：** 參見 [docs/](docs/) 了解每個功能的詳細指南。
+### 需求
+- Node.js 20+
+- Claude Code 或 Cursor IDE
+- 5 分鐘時間
 
----
+</td>
+<td width="50%">
 
-## 技術規格
+### 平台支援
+- ✅ **Claude 4.5**（Haiku/Sonnet/Opus）
+- ✅ **MCP SDK 1.25.3**
+- ✅ Windows、macOS、Linux
 
-### Claude 4.5 模型支援
+</td>
+</tr>
+</table>
 
-CCB 完整支援最新的 Claude 4.5 模型家族：
+### 🔒 安全優先
 
-- **Claude Haiku 4.5** (claude-haiku-4-5-20251015) - 簡單任務的快速回應
-  - 價格：$1.00 input / $5.00 output per MTok
-  - 使用場景：快速查詢、簡單重構、程式碼格式化
+- ✅ **100% 本地處理** - 資料永不離開你的機器
+- ✅ **零外部 API 呼叫** - 使用你的 Claude Code 訂閱
+- ✅ **npm audit：0 個漏洞**
+- ✅ **開源** - 自己審查程式碼
 
-- **Claude Sonnet 4.5** (claude-sonnet-4-5-20250929) - 日常開發的平衡效能
-  - 使用場景：程式碼生成、測試、中等複雜度任務
+---
 
-- **Claude Opus 4.5** (claude-opus-4-5-20251101) - 複雜挑戰的深度推理
-  - 使用場景：架構設計、複雜除錯、創意問題解決
+## 🤝 貢獻
 
-**智慧模型選擇：** CCB 根據任務複雜度自動選擇適當的模型，兼顧品質與成本效益。
+我們很樂意你的幫助讓 CCB 變得更好！
 
-### MCP 規範符合性
+- 🐛 **發現 bug？**[開啟 issue](https://github.com/PCIRCLE-AI/claude-code-buddy/issues/new)
+- 💡 **有想法？**[開始討論](https://github.com/PCIRCLE-AI/claude-code-buddy/discussions)
+- 🛠️ **想寫程式？**查看 [Good First Issues](https://github.com/PCIRCLE-AI/claude-code-buddy/labels/good%20first%20issue)
 
-✅ **完全符合 MCP Specification 2025-11-25**
+**貢獻指南**：[CONTRIBUTING.md](docs/CONTRIBUTING.md)
 
-所有 MCP 工具都包含：
-- **工具註解**：`readOnlyHint`、`destructiveHint`、`idempotentHint`、`openWorldHint`
-- **輸出 Schema**：具類型安全的結構化 JSON schemas
-- **執行時驗證**：自動驗證工具輸入與輸出
+---
 
-**7 個 MCP 工具可用：**
-1. `buddy-do` - 具備能力路由的智慧任務執行
-2. `buddy-remember` - 專案記憶回溯
-3. `buddy-help` - 命令文件
-4. `get-session-health` - Session 監控與診斷
-5. `get-workflow-guidance` - 智慧工作流程建議
-6. `generate-smart-plan` - 實作計劃生成
-7. `hook-tool-use` - 工具使用事件追蹤
+## 📚 文檔
 
-完整工具規格請參見 [src/mcp/ToolDefinitions.ts](src/mcp/ToolDefinitions.ts)。
+- 📖 [完整文檔](docs/)
+- 🚀 [快速安裝指南](docs/QUICK_INSTALL.md)
+- 📘 [使用者指南](docs/USER_GUIDE.md)
+- 🛠️ [API 參考](docs/api/API_REFERENCE.md)
+- ❓ [疑難排解](docs/TROUBLESHOOTING.md)
 
 ---
 
-## 社群與支援
+## ❓ 常見問題
 
-- **文件**：[docs/](docs/) 資料夾 + 這個 README
-- **問題**：[GitHub Issues](https://github.com/PCIRCLE-AI/claude-code-buddy/issues)
-- **討論**：[GitHub Discussions](https://github.com/PCIRCLE-AI/claude-code-buddy/discussions)
-- **貢獻**：[CONTRIBUTING.md](docs/CONTRIBUTING.md)
+<details>
+<summary><strong>Q：需要付費嗎？</strong></summary>
 
-**有問題？** 開啟一個 issue 或開始討論 - 我們在這裡提供協助。
+**A：** 不用。100% 免費開源（AGPL-3.0）。使用你現有的 Claude Code 訂閱。
 
----
+</details>
 
-## 開發
+<details>
+<summary><strong>Q：我的資料安全嗎？</strong></summary>
 
-```bash
-# 執行測試（292 個測試檔案涵蓋核心功能）
-npm test
+**A：** 是的。所有資料都在本地處理。零外部 API 呼叫。零資料上傳。
 
-# 開發模式，自動重載
-npm run dev
+</details>
 
-# 為生產環境建構
-npm run build
+<details>
+<summary><strong>Q：和純 Claude Code 有什麼不同？</strong></summary>
 
-# 查看性能儀表板
-npm run dashboard
-```
+**A：** CCB 加入兩大超能力：
+1. **持久化記憶** - Claude 能跨 session 記住你的專案
+2. **智能路由** - 自動偵測和處理不同任務類型
 
-**貢獻：** 我們歡迎貢獻！參見 [CONTRIBUTING.md](docs/CONTRIBUTING.md) 了解指南。
+可以想成：Claude Code + 超強記憶 + 自動駕駛模式。
 
-**完整文檔：**
+</details>
 
-- 📚 [文件索引](docs/README.md) - 文件總覽與導航
-- 🔧 [組件指南](docs/COMPONENT_GUIDE.md) - 詳細組件參考與 API 文檔
-- 🔄 [數據流程](docs/DATA_FLOW.md) - 請求生命週期、事務模式、錯誤傳播
-- 🚀 [部署指南](docs/DEPLOYMENT.md) - 安裝、配置、監控、故障排除
-- 🤝 [貢獻指南](docs/CONTRIBUTING.md) - 開發設置、代碼標準、PR 流程
+<details>
+<summary><strong>Q：可以客製化嗎？</strong></summary>
 
----
+**A：** 當然。提示詞模板在 `src/core/PromptEnhancer.ts`。
+
+想更深度客製化？Fork 它、改它、變成你的。這就是開源精神。
 
-## 常見問題
+</details>
 
-**問：我需要是開發者才能使用嗎？**
-答：如果你能使用 Claude Code，你就能使用 CCB。它是為了讓 Claude 更容易使用，而不是更難。
+<details>
+<summary><strong>Q：支援 Cursor 嗎？</strong></summary>
 
-**問：這會在 Claude Code 之外產生額外費用嗎？**
-答：不會 - CCB 使用你現有的 Claude Code 訂閱。它協助保持提示與回應聚焦，不會增加額外 API 成本。
+**A：** 支援！Cursor 原生支援 MCP。一鍵安裝。
 
-**問：這與單純使用 Claude Code 有什麼不同？**
-答：Claude Code 對所有任務一視同仁。CCB 增加了任務特定的專業知識、記憶和學習。
+</details>
 
-**問：我的程式碼是私有的嗎？**
-答：是的。所有內容都透過你的 Claude Code 訂閱在本地執行，不需要外部 AI 服務。
+---
 
-**問：如果我不喜歡怎麼辦？**
-答：從你的 MCP 設定中移除它。沒有鎖定，沒有供應商依賴。
+## 🙏 致謝
 
-**問：這要多少錢？**
-答：CCB 是免費且開源的（AGPL-3.0）。與你現有的 Claude Code 訂閱一起使用。
+站在巨人的肩膀上：
 
-**問：我可以自訂路由行為嗎？**
-答：當然！提示範本在 `src/core/PromptEnhancer.ts`。演化設定在 `src/evolution/AgentEvolutionConfig.ts`。
+- [Model Context Protocol (MCP)](https://github.com/anthropics/mcp) - 基礎
+- [Claude Code](https://claude.com/claude-code) - 平台
+- 所有我們出色的[貢獻者](https://github.com/PCIRCLE-AI/claude-code-buddy/graphs/contributors)和早期測試者
 
 ---
 
-## 授權條款
+## 📄 授權
 
-**AGPL-3.0 授權條款** - 詳見 [LICENSE](LICENSE) 檔案。
+**AGPL-3.0** - 查看 [LICENSE](LICENSE)
 
-這是免費且開源的軟體。如果你修改並將其部署為網路服務，你必須向使用者提供原始碼。
+*這代表：使用它、修改它、分享它。但保持開源。*
 
 ---
 
-## 致謝
+## 🌟 Star 歷史
 
-- 使用 [Model Context Protocol (MCP)](https://github.com/anthropics/mcp) 建構
-- 與 [Claude Code](https://claude.com/claude-code) 配合使用
-- 受 Claude Code 社群啟發
-- 感謝所有貢獻者和早期測試者
-
-**免責聲明：** 本專案為獨立開發的開源專案，與 Anthropic PBC 或其產品（包括 Claude 和 Claude Code）無任何官方關聯或附屬關係。Claude Code Buddy 是設計用於與 Claude Code 整合的第三方工具。
+[![Star History Chart](https://api.star-history.com/svg?repos=PCIRCLE-AI/claude-code-buddy&type=Date)](https://star-history.com/#PCIRCLE-AI/claude-code-buddy&Date)
 
 ---
 
 <div align="center">
 
-**由開發者為開發者用心打造 ❤️**
+### **開發者打造，為開發者服務**
+
+**別再重複自己。開始 vibe 吧。**
+
+[🚀 開始使用](#-2-分鐘快速開始) • [📖 閱讀文檔](docs/) • [💬 加入討論](https://github.com/PCIRCLE-AI/claude-code-buddy/discussions)
 
-**讓 Claude Code 更聰明，而非更繁雜。**
+---
+
+### ⭐ **如果 CCB 今天幫你省時間，給它一個 star！**
 
-[開始使用](#快速開始2-分鐘) • [文件](docs/) • [回報問題](https://github.com/PCIRCLE-AI/claude-code-buddy/issues) • [加入討論](https://github.com/PCIRCLE-AI/claude-code-buddy/discussions)
+這能幫助其他人發現這個工具。
 
 ---
 
-⭐ **如果 CCB 讓你的開發生活更輕鬆，請為這個儲存庫加星！**
+**與 Anthropic PBC 無關** • 獨立開源專案
+
+**語言：**[English](README.md) • [繁體中文](README.zh-TW.md)
 
 </div>