@pcircle/claude-code-buddy-mcp 2.3.1

package/README.zh-TW.md

@@ -0,0 +1,577 @@
+# 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 團隊成員。
+
+---
+
+## 問題所在
+
+你使用 Claude Code 來建構專案，但不斷遇到相同的挫折：
+
+- **「我們不是討論過這個嗎？」** - Claude 在不同 session 之間會忘記上下文
+- **「為什麼我要再解釋一次？」** - 每次對話都從零開始
+- **「這個答案太泛化了」** - 無論你是在除錯、審查程式碼還是設計 UI，回應都一樣
+- **「讓我再寫一次這 50 行提示...」** - 常見任務需要重複的指令
+
+**結果你成了 Claude 的記憶和專案經理，而不是專注於建構。**
+
+---
+
+## 解決方案
+
+Claude Code Buddy 位於你和 Claude Code 之間，增加三項超能力：
+
+### 1. 🧠 **專案記憶**
+
+CCB 記住你的架構決策、編碼模式和過去的解決方案。問「為什麼我們選擇 PostgreSQL？」，你會得到實際的決策理由 - 而不是泛泛的比較。
+
+### 2. 🎯 **智能任務路由**
+
+你的請求會被分析並路由到正確的「專家模式」 - 程式碼審查任務獲得程式碼審查專業知識，除錯獲得系統化除錯方法，前端獲得 UI/UX 最佳實踐。
+
+### 3. 🎯 **能力導向引導**
+
+CCB 會依任務類型與專案情境調整提示詞，讓審查、除錯、設計等工作都有適切的結構與防護欄。
+
+**結果：** 專家級回應無需專家級提示。持續的上下文。聚焦且可執行的引導。
+
+### CCB 所謂的「隨你的專案演化」究竟是什麼意思？
+
+CCB 不會重訓模型或修改 Claude 本身。
+
+相反地，演化來自於 Claude Code Plugin 內部的 **持久化系統層**：
+
+• **專案記憶累積**
+架構決策、慣例和已解決的討論都被儲存為結構化的上下文。
+
+• **模式強化**
+重複的批准、重構和偏好的解決方案逐漸塑造未來提示詞的建構方式。
+
+• **任務類型區分**
+審查、除錯、重構和設計任務使用不同的內部提示策略處理。
+
+• **上下文重用，而非重複**
+選擇性地注入相關記憶，避免提示詞過其臃腫，同時保持連續性。
+
+隨著時間推移，Claude Code 的回應變得：
+• 更符合你的慣例
+• 跨會話更一致
+• 較少依賴冗長的提示詞
+
+這是一種 *透過系統記憶和路由的行為演化*，而非模型微調。
+
+---
+
+## 實際運作
+
+**沒有 CCB：**
+
+```
+你：「優化這個資料庫查詢」
+Claude：[關於索引和查詢結構的泛化建議]
+```
+
+**有了 CCB：**
+
+```
+你：「優化這個資料庫查詢」
+
+CCB 分析：資料庫優化任務
+CCB 路由到：資料庫優化能力
+CCB 用以下內容增強提示：資料庫最佳實踐、索引策略、性能分析技術
+
+Claude：[針對你的資料庫設定的具體優化建議，包含實際查詢範例
+         和基於你的 schema 的性能基準測試]
+```
+
+**差異：** CCB 了解你的技術堆疊，記住你的 schema，並提供目標性的專業知識。
+
+---
+
+## 如何使用 CCB
+
+安裝完成後，CCB 有 **兩種使用方式**：
+
+### 🔄 自動模式（正常對話即可）
+
+CCB 在背景自動增強你的請求，不需要特別的指令：
+
+```
+你：「檢查這段程式碼的安全性問題」
+     ↓
+CCB 自動執行：
+  • 偵測任務類型 → 程式碼審查
+  • 路由到 → 程式碼審查能力
+  • 增強提示詞 → 安全檢查清單、最佳實踐
+     ↓
+Claude 回應專業的安全審查結果
+```
+
+**像平常一樣使用 Claude Code** - CCB 在背景默默提升回應品質。
+
+### 🎮 Buddy 指令（明確控制）
+
+當你需要特定 CCB 功能時，使用這些指令：
+
+| 指令 | 功能 | 範例 |
+|------|------|------|
+| `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    產生實作計畫                       │
+└─────────────────────────────────────────────────────────────┘
+```
+
+---
+
+## 核心功能
+
+### ✨ 自動專業知識路由
+
+CCB 會依照能力訊號自動路由至內部專家。你只要描述需求即可。
+
+**涵蓋能力範圍：**
+- 程式碼審查、安全稽核與最佳實踐
+- 除錯與根因分析
+- 重構與技術債處理
+- API 設計、後端架構、資料庫優化
+- 測試策略與測試產生
+- 效能分析與最佳化
+- UI/UX 設計與技術文件
+- 研究、產品與規劃支援
+
+### 💾 記憶系統
+
+**知識圖譜**
+
+```
+你：「為什麼我們選擇這個架構？」
+CCB：[回憶決策、考慮過的替代方案和權衡]
+```
+
+**專案上下文**
+
+```
+CCB 記住：
+- 你的編碼標準
+- 命名慣例
+- 專案特定模式
+- 你已經建構的內容
+```
+
+### 🎯 能力導向引導與回應聚焦
+
+CCB 依任務複雜度與類型，路由到適合的能力配置，調整提示詞結構與檢查重點。
+
+**運作方式**：TaskAnalyzer 檢查你的請求 → 評估複雜度（1-10）→ 路由到最佳能力配置 → 回應更聚焦、更可執行。
+
+**實際範例**：「修正這個錯字」走最短流程，「設計認證系統」走架構設計與風險檢視流程，「審查這個 PR」走安全與品質清單。
+
+### 🤝 使用者友善的命令
+
+```bash
+# 自然語言命令，就是這麼簡單
+buddy-do "setup authentication"
+buddy-do "optimize this database query"
+buddy-remember "how we implemented login"
+buddy-help
+```
+
+### 🔄 智能工作流程引導
+
+**CCB 知道下一步是什麼。** 你寫完程式碼後，它建議執行測試。測試通過後，它建議程式碼審查。不需要手動思考。
+
+```
+你寫程式碼 → CCB：「程式碼看起來不錯！下一步執行測試？」
+測試通過 → CCB：「測試通過！準備好進行程式碼審查？」
+審查完成 → CCB：「審查完成！提交並推送？」
+```
+
+**工作流程工具：**
+
+- `get-workflow-guidance` - 獲得下一步建議
+- `get-session-health` - 檢查 session 健康狀態
+
+**優勢：** 永不疑惑「我接下來該做什麼？」- CCB 引導你完成整個開發流程。
+
+### 📋 智能實作規劃
+
+**將複雜功能分解為小型任務。** CCB 生成 TDD 結構化計畫，具備能力感知的任務分解。
+
+```
+你：「規劃使用者身份驗證的實作」
+CCB：[生成逐步計畫，包含：
+  - 測試優先方法
+  - 2-5 分鐘的任務
+  - 每個任務的正確能力
+  - 明確的成功標準]
+```
+
+**規劃工具：**
+
+- `generate-smart-plan` - 創建智能實作計畫
+
+---
+
+## 快速開始（2 分鐘）
+
+### 🚀 一鍵安裝
+
+#### Cursor 用戶
+
+[![安裝到 Cursor](https://img.shields.io/badge/安裝到-Cursor-blue?style=for-the-badge&logo=cursor)](cursor://anysphere.cursor-deeplink/mcp/install?name=claude-code-buddy&config=eyJjb21tYW5kIjoibnB4IiwiYXJncyI6WyIteSIsImNsYXVkZS1jb2RlLWJ1ZGR5Il19)
+
+**點擊上方按鈕或在瀏覽器貼上此連結：**
+```
+cursor://anysphere.cursor-deeplink/mcp/install?name=claude-code-buddy&config=eyJjb21tYW5kIjoibnB4IiwiYXJncyI6WyIteSIsImNsYXVkZS1jb2RlLWJ1ZGR5Il19
+```
+
+#### VS Code / Claude Code 用戶
+
+**快速 MCP 配置**（加入到 `~/.claude/mcp_settings.json`）：
+```json
+{
+  "mcpServers": {
+    "claude-code-buddy": {
+      "command": "npx",
+      "args": ["-y", "claude-code-buddy"]
+    }
+  }
+}
+```
+
+然後重啟 Claude Code 即可開始使用 CCB！
+
+**📖 詳細安裝指南**：參見 [QUICK_INSTALL.md](docs/QUICK_INSTALL.md)
+
+---
+
+### 前置需求
+
+- Node.js 20+ ([下載](https://nodejs.org/))
+- Claude Code 已安裝 ([在這裡取得](https://claude.com/claude-code)) 或 Cursor IDE
+
+### 手動安裝（替代方案）
+
+```bash
+# 1. 複製儲存庫
+git clone https://github.com/PCIRCLE-AI/claude-code-buddy.git
+cd claude-code-buddy
+
+# 2. 執行互動式安裝程式（它會處理所有事情）
+./scripts/install.sh
+```
+
+安裝程式會引導你完成 **9 個互動式步驟**：
+
+**核心設定（步驟 1-7）**：
+
+- ✓ 檢查前置需求（Node.js 20+、npm；git 可選）
+- ✓ 安裝相依性
+- ✓ 建構專案
+- ✓ 檢查系統資源
+- ✓ 設定環境
+- ✓ 設定 Claude Code MCP 整合
+- ✓ 測試安裝
+
+**互動式展示（步驟 8-9）**：
+
+- 📚 **步驟 8：基本使用展示** - 了解 CCB 的智能路由、範例提示與記憶功能
+- ✅ **步驟 9：MCP 驗證** - 確認 MCP 伺服器可連線
+
+**在 MCP 伺服器模式下不需要 API 金鑰** - 使用你現有的 Claude Code 訂閱。
+
+**可選設定**（只有在需要調整預設值時才需要）：
+```bash
+cp .env.example .env
+# 若要以獨立 orchestrator 模式執行：
+# MCP_SERVER_MODE=false
+# ANTHROPIC_API_KEY=your_key_here
+```
+
+### 開始使用
+
+重新啟動 Claude Code，然後嘗試：
+
+```
+「分析我的程式碼庫架構」
+「為 auth.ts 生成測試」
+「審查這段程式碼是否有安全問題」
+「優化這個資料庫查詢」
+```
+
+CCB 會自動將任務路由到正確的能力，並用相關上下文增強提示。
+
+---
+
+## 運作原理
+
+```
+你的請求
+    ↓
+CCB 分析任務
+    ↓
+路由到最佳能力類型（例如程式碼審查、除錯）
+    ↓
+用專業上下文增強提示
+    ↓
+Claude Code 用你的訂閱執行
+    ↓
+系統從你的選擇中學習（當你覆蓋建議時）
+```
+
+**幕後：**
+
+- **內部專家體系**：以能力訊號驅動路由與提示增強
+- **智能路由**分析任務複雜度並選擇最佳能力配置
+- **演化系統**從你的選擇中學習並持續改進建議
+
+**技術深入探討：** 參見 [docs/README.md](docs/README.md)
+
+**API 文檔：** 參見 [docs/api/API_REFERENCE.md](docs/api/API_REFERENCE.md)
+
+---
+
+## CCB 擅長什麼 ✅
+
+- **使 Claude Code 具備專案意識**針對你的特定專案
+- **減少重複提示**透過智能任務路由
+- **在不同 session 之間記憶**使用持久記憶系統（知識圖譜 + 專案上下文）
+- **提供專業知識**無需你撰寫專家級提示
+- **保持回應聚焦**透過路由到適合的能力配置
+- **從你的選擇中學習**當你覆蓋建議時
+- **引導你的工作流程**透過智能下一步建議
+- **協調複雜工作流程**跨越多個步驟
+- **跨平台支援**無縫支援 Windows、macOS 和 Linux
+- **生產就緒**具備全面測試、安全性強化和資源保護
+
+## 誠實的限制 ⚠️
+
+- **不是魔法** - 仍然需要你提供明確的需求
+- **不是學習的替代品** - 你應該了解你在建構什麼
+- **增強 Claude Code，不是取代它** - 與你現有的設定一起運作
+- **需要設定** - 2 分鐘安裝，不是一鍵完成（還沒有）
+- **早期階段（v2.2）** - 預期會有粗糙的地方，但正在積極改進
+- **受 Claude 能力限制** - 無法讓 Claude 做不可能的事
+
+**理念：** 我們對什麼有效、什麼無效保持誠實。如果某些東西對你不起作用，請告訴我們 - 這個回饋會讓所有人都受益。
+
+---
+
+## 使用案例
+
+### 程式碼審查
+
+```
+「審查這個 PR 是否有安全漏洞和程式碼品質問題」
+→ 路由到程式碼審查能力
+→ 獲得安全檢查清單 + 品質標準
+→ 返回詳細審查，包含具體建議
+```
+
+### 除錯
+
+```
+「這個函式在 undefined 時崩潰，幫助除錯」
+→ 路由到除錯能力
+→ 獲得系統化除錯方法
+→ 逐步進行根本原因分析
+```
+
+### 前端設計
+
+```
+「設計一個具有深色模式的響應式儀表板」
+→ 路由到介面設計能力
+→ 獲得 UI/UX 模式 + 無障礙性指南
+→ 返回完整設計，包含響應式斷點
+```
+
+### 資料庫優化
+
+```
+「這個 Prisma 查詢需要 2 秒，優化它」
+→ 路由到資料庫優化能力
+→ 獲得查詢優化模式 + 索引策略
+→ 返回優化的查詢，包含性能基準測試
+```
+
+---
+
+## 進階功能
+
+- **自訂技能** - 用 TypeScript 撰寫你自己的路由行為
+- **多步驟規劃** - 將複雜任務分解為可執行的計劃
+- **工作流程協調** - 自動檢查點檢測和下一步建議
+- **儀表板** - 即時指標、session 健康監控、性能追蹤
+
+**探索：** 參見 [docs/](docs/) 了解每個功能的詳細指南。
+
+---
+
+## 技術規格
+
+### Claude 4.5 模型支援
+
+CCB 完整支援最新的 Claude 4.5 模型家族：
+
+- **Claude Haiku 4.5** (claude-haiku-4-5-20251015) - 簡單任務的快速回應
+  - 價格：$1.00 input / $5.00 output per MTok
+  - 使用場景：快速查詢、簡單重構、程式碼格式化
+
+- **Claude Sonnet 4.5** (claude-sonnet-4-5-20250929) - 日常開發的平衡效能
+  - 使用場景：程式碼生成、測試、中等複雜度任務
+
+- **Claude Opus 4.5** (claude-opus-4-5-20251101) - 複雜挑戰的深度推理
+  - 使用場景：架構設計、複雜除錯、創意問題解決
+
+**智慧模型選擇：** CCB 根據任務複雜度自動選擇適當的模型，兼顧品質與成本效益。
+
+### MCP 規範符合性
+
+✅ **完全符合 MCP Specification 2025-11-25**
+
+所有 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/) 資料夾 + 這個 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)
+
+**有問題？** 開啟一個 issue 或開始討論 - 我們在這裡提供協助。
+
+---
+
+## 開發
+
+```bash
+# 執行測試（292 個測試檔案涵蓋核心功能）
+npm test
+
+# 開發模式，自動重載
+npm run dev
+
+# 為生產環境建構
+npm run build
+
+# 查看性能儀表板
+npm run dashboard
+```
+
+**貢獻：** 我們歡迎貢獻！參見 [CONTRIBUTING.md](docs/CONTRIBUTING.md) 了解指南。
+
+**完整文檔：**
+
+- 📚 [文件索引](docs/README.md) - 文件總覽與導航
+- 🔧 [組件指南](docs/COMPONENT_GUIDE.md) - 詳細組件參考與 API 文檔
+- 🔄 [數據流程](docs/DATA_FLOW.md) - 請求生命週期、事務模式、錯誤傳播
+- 🚀 [部署指南](docs/DEPLOYMENT.md) - 安裝、配置、監控、故障排除
+- 🤝 [貢獻指南](docs/CONTRIBUTING.md) - 開發設置、代碼標準、PR 流程
+
+---
+
+## 常見問題
+
+**問：我需要是開發者才能使用嗎？**
+答：如果你能使用 Claude Code，你就能使用 CCB。它是為了讓 Claude 更容易使用，而不是更難。
+
+**問：這會在 Claude Code 之外產生額外費用嗎？**
+答：不會 - CCB 使用你現有的 Claude Code 訂閱。它協助保持提示與回應聚焦，不會增加額外 API 成本。
+
+**問：這與單純使用 Claude Code 有什麼不同？**
+答：Claude Code 對所有任務一視同仁。CCB 增加了任務特定的專業知識、記憶和學習。
+
+**問：我的程式碼是私有的嗎？**
+答：是的。所有內容都透過你的 Claude Code 訂閱在本地執行，不需要外部 AI 服務。
+
+**問：如果我不喜歡怎麼辦？**
+答：從你的 MCP 設定中移除它。沒有鎖定，沒有供應商依賴。
+
+**問：這要多少錢？**
+答：CCB 是免費且開源的（AGPL-3.0）。與你現有的 Claude Code 訂閱一起使用。
+
+**問：我可以自訂路由行為嗎？**
+答：當然！提示範本在 `src/core/PromptEnhancer.ts`。演化設定在 `src/evolution/AgentEvolutionConfig.ts`。
+
+---
+
+## 授權條款
+
+**AGPL-3.0 授權條款** - 詳見 [LICENSE](LICENSE) 檔案。
+
+這是免費且開源的軟體。如果你修改並將其部署為網路服務，你必須向使用者提供原始碼。
+
+---
+
+## 致謝
+
+- 使用 [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 整合的第三方工具。
+
+---
+
+<div align="center">
+
+**由開發者為開發者用心打造 ❤️**
+
+**讓 Claude Code 更聰明，而非更繁雜。**
+
+[開始使用](#快速開始2-分鐘) • [文件](docs/) • [回報問題](https://github.com/PCIRCLE-AI/claude-code-buddy/issues) • [加入討論](https://github.com/PCIRCLE-AI/claude-code-buddy/discussions)
+
+---
+
+⭐ **如果 CCB 讓你的開發生活更輕鬆，請為這個儲存庫加星！**
+
+</div>

package/dist/__benchmarks__/performance-fixes.bench.d.ts

@@ -0,0 +1,8 @@
+declare function benchmarkGetStats(): Promise<void>;
+declare function benchmarkGetConnectedEntities(): Promise<void>;
+declare function benchmarkAnalyzePatterns(): Promise<void>;
+declare function benchmarkCPUCache(): Promise<void>;
+declare function benchmarkResourceMonitorMemory(): Promise<void>;
+declare function runAllBenchmarks(): Promise<void>;
+export { benchmarkGetStats, benchmarkGetConnectedEntities, benchmarkAnalyzePatterns, benchmarkCPUCache, benchmarkResourceMonitorMemory, runAllBenchmarks, };
+//# sourceMappingURL=performance-fixes.bench.d.ts.map

package/dist/__benchmarks__/performance-fixes.bench.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"performance-fixes.bench.d.ts","sourceRoot":"","sources":["../../src/__benchmarks__/performance-fixes.bench.ts"],"names":[],"mappings":"AA+BA,iBAAe,iBAAiB,kBA8C/B;AAGD,iBAAe,6BAA6B,kBA8C3C;AAGD,iBAAe,wBAAwB,kBAmDtC;AAGD,iBAAe,iBAAiB,kBA4C/B;AAGD,iBAAe,8BAA8B,kBAgE5C;AAGD,iBAAe,gBAAgB,kBAqB9B;AAOD,OAAO,EACL,iBAAiB,EACjB,6BAA6B,EAC7B,wBAAwB,EACxB,iBAAiB,EACjB,8BAA8B,EAC9B,gBAAgB,GACjB,CAAC"}