{
  "markdown": "# Copilot Capability Manager\n\n> � **Neuro-Symbolic AI** 架構實現 - 結合符號推理與神經網路，讓 AI Agent 能力可組合、可解釋、可追蹤\n\n[![License](https://img.shields.io/badge/License-Apache_2.0-blue.svg)](https://opensource.org/licenses/Apache-2.0)\n[![Python](https://img.shields.io/badge/Python-3.9+-blue.svg)](https://www.python.org/)\n[![TypeScript](https://img.shields.io/badge/TypeScript-5.0+-blue.svg)](https://www.typescriptlang.org/)\n[![Status](https://img.shields.io/badge/Status-🚧_Under_Construction-yellow.svg)]()\n\n> ⚠️ **注意：此專案正在積極開發中，API 和功能可能會有重大變更。**\n\n🌐 [繁體中文](README.zh-TW.md) | 📖 [架構設計](ARCHITECTURE.md) | 🗺️ [Roadmap](ROADMAP.md)\n\n## 🧠 Neuro-Symbolic AI 架構\n\n本專案實現了 **Neuro-Symbolic AI** 模式，結合符號系統的可解釋性與神經網路的靈活性：\n\n```\n┌────────────────────────────────────────────────────────────────┐\n│  🔷 SYMBOLIC LAYER (符號層)                                    │\n│     Capability Graph, Contracts, Branch Logic                  │\n│     → 結構化、可驗證、確定性                                     │\n├────────────────────────────────────────────────────────────────┤\n│  🔶 SKILL BRIDGE (技能橋接層)                                   │\n│     LLM Agent + Abstract Node Resolver + Skill Executor        │\n│     → 神經網路決策 + 符號約束 = 可靠執行                          │\n├────────────────────────────────────────────────────────────────┤\n│  🔻 TOOL LAYER (工具層)                                        │\n│     MCP Tools, File System, External APIs                      │\n│     → 結構化 API、確定性操作                                     │\n└────────────────────────────────────────────────────────────────┘\n```\n\n### 為什麼是 Neuro-Symbolic？\n\n| 特性 | 純 Neural | 純 Symbolic | **Neuro-Symbolic** |\n|------|----------|-------------|-------------------|\n| 靈活性 | ✅ 高 | ❌ 低 | ✅ 高 |\n| 可解釋性 | ❌ 黑箱 | ✅ 透明 | ✅ 透明 |\n| 可靠性 | ⚠️ 不穩定 | ✅ 穩定 | ✅ 穩定 |\n| 適應性 | ✅ 強 | ❌ 弱 | ✅ 強 |\n\n## 🎯 願景\n\n將 AI 能力模組化、視覺化，讓使用者可以：\n\n1. **管理 Skills** - 透過 GUI 新增、編輯、設定 AI 技能（包含 MCP Tools）\n2. **組合 Capabilities** - 動態組合 Skills，支援迴圈與條件分支\n3. **追蹤長任務** - Checkpoint 機制實現跨對話狀態持久化\n4. **一鍵執行** - 透過 `/cp.xxx` 斜線指令觸發\n\n## 🏗️ 核心概念\n\n```\n┌─────────────────────────────────────────────────────────────┐\n│  Tool (工具)                                                │\n│  ├─ 最小單位，單一 API 調用                                  │\n│  └─ 例：fetch_webpage, read_file, mcp_pubmed_search        │\n├─────────────────────────────────────────────────────────────┤\n│  Skill (技能)                                               │\n│  ├─ 多個 Tools 的編排，完成一個明確的小任務                   │\n│  ├─ 定義於 .claude/skills/{skill-id}/SKILL.md              │\n│  └─ 例：search-literature (搜尋 + 篩選 + 摘要)              │\n├─────────────────────────────────────────────────────────────┤\n│  Capability (能力)                                          │\n│  ├─ 動態的 Skill 狀態機，可迴圈、條件分支                    │\n│  ├─ 需要狀態追蹤（長任務可能跨對話）                         │\n│  ├─ 定義於 .github/prompts/cp.{id}.prompt.md               │\n│  └─ 例：literature-review (多輪搜尋 + 多篇閱讀 + 綜合)       │\n└─────────────────────────────────────────────────────────────┘\n```\n\n### 為什麼不叫 Workflow？\n\n**Workflow** 暗示線性執行（A → B → C），但真實場景更複雜：\n\n```\n文獻評讀 Capability 範例：\n├── 輸入：一個資料夾（20 篇 PDF）\n├── search skill × N（可能要找更多文獻）\n├── 對每個 PDF：\n│   ├── read-pdf skill × M（長 PDF 要讀多次）\n│   └── write-note skill × M（每次讀完寫筆記）\n├── 發現需要補充 → 回到 search skill\n└── synthesis skill（最終綜合整理）\n```\n\n**Capability** 強調：\n- 🔄 **迴圈執行** - 同一 Skill 可重複調用\n- 🔀 **條件分支** - 根據結果決定下一步\n- 📊 **狀態追蹤** - 知道「處理到哪裡了」\n\n## 🎨 設計理念\n\n### 📐 圖論基礎的能力組合\n\n我們使用**有向圖（DAG）**來描述能力結構，而非傳統的線性工作流：\n\n```\n┌─────────────────────────────────────────────────────────────┐\n│                    Capability 圖結構                         │\n│                                                             │\n│  [START] ──► [detect] ──► [abstract:read] ──► [write] ──► [END]\n│                               │                             │\n│                    ┌──────────┼──────────┐                  │\n│                    ▼          ▼          ▼                  │\n│               [pdf-reader] [docx] [web-reader]              │\n│                    │                     │                  │\n│                    └──► [fallback] ◄─────┘                  │\n└─────────────────────────────────────────────────────────────┘\n```\n\n**圖的優勢：**\n- 📊 **複雜度量化** - McCabe 環路複雜度 + 迭代/互動權重\n- 🔄 **自然表達迴圈** - 回邊（back edge）清晰標示\n- 🔀 **分支即分叉** - 條件判斷是圖的自然結構\n\n### 🧩 抽象節點與動態解析\n\n**核心問題**：輸入不確定（可能是 PDF、DOCX、線上文檔）怎麼辦？\n\n**解決方案**：抽象節點 + Fallback 鏈\n\n```yaml\n# 定義「做什麼」而不是「怎麼做」\n- id: read_document\n  type: abstract\n  contract:\n    input: [source]\n    output: [content]\n  resolution:\n    strategy: auto_detect\n    implementations:\n      - condition: \"*.pdf\" → pdf-reader → [ocr-reader, ask-user]\n      - condition: \"*.docx\" → docx-reader\n      - condition: \"http*\" → web-reader\n```\n\n**設計原則：**\n- 🎯 **契約優先** - 定義輸入/輸出，不綁定實作\n- ⏱️ **延遲綁定** - 執行時才決定具體實現\n- 🛡️ **優雅降級** - 每個節點都有 Fallback 鏈\n\n> 📖 詳細設計：[ADAPTIVE-GRAPH-DESIGN.md](docs/ADAPTIVE-GRAPH-DESIGN.md)\n\n### 🔥 能力自動觸發\n\n不需要記住 `/cp.xxx` 指令，系統自動識別意圖：\n\n| 觸發條件 | 自動載入能力 |\n|----------|--------------|\n| 提到「報告」「PDF」「文獻」 | write-report |\n| 提到「commit」「提交」 | git-commit |\n| 提到「重構」「refactor」 | code-refactor |\n\n> 📖 詳細設計：[CAPABILITY-ARCHITECTURE.md](docs/CAPABILITY-ARCHITECTURE.md)\n\n## 💾 Checkpoint 機制（長任務支援）\n\nCopilot 有 context window 限制，長任務無法在單次對話完成。\n\n```\nmemory-bank/checkpoints/\n└── literature-review-20251221.json\n    {\n      \"capability\": \"literature-review\",\n      \"status\": \"in-progress\",\n      \"progress\": { \"total\": 20, \"completed\": 8 },\n      \"currentItem\": \"paper-09.pdf\",\n      \"completedItems\": [\"paper-01.pdf\", ...],\n      \"notes\": [...]\n    }\n```\n\n**執行流程：**\n1. 🚀 **啟動** → 建立 checkpoint\n2. ⚙️ **執行** → 每完成一項更新 checkpoint\n3. ⏸️ **中斷** → checkpoint 保留狀態\n4. ▶️ **繼續** → 讀取 checkpoint，從斷點繼續\n5. ✅ **完成** → 標記 completed\n\n## ✨ 功能特色\n\n### 🧩 Skill Manager（技能管理器）\n\n- 📋 **Skill 列表** - TreeView 瀏覽所有可用技能\n- ➕ **新增/複製 Skill** - GUI 表單建立新技能，支援複製\n- 🔧 **MCP Tool 推薦** - 根據 Skill 內容推薦相關 MCP 工具\n- 📝 **Prompt 編輯器** - Webview 編輯技能執行指令\n- 🏷️ **標籤分類** - 研究、文件、Git、維護、架構、品質\n\n### 🔗 Capability Builder（能力組合器）\n\n- 🎨 **步驟編輯器** - 拖動 Skills 排列順序\n- 🔄 **迴圈執行** - 支援固定次數、條件迴圈、遍歷\n- 🔀 **分支處理** - 條件判斷與步驟跳轉\n- ⚡ **並行執行** - 同時執行多個獨立 Steps\n- ✅ **驗證服務** - 檢查步驟 I/O 相容性、迴圈設定\n- 💾 **匯出 Prompt** - 自動生成 `.prompt.md` 檔案\n\n### ⚡ 執行引擎\n\n- `/cp.xxx` 斜線指令觸發\n- 保持 Agent Mode 完整工具權限\n- 依序執行 Skills\n- 自動同步 Memory Bank\n\n## 📁 專案結構\n\n```\ncopilot-capability-manager/\n├── src/                          # 🔧 VS Code 擴充套件原始碼\n│   ├── extension.ts              # 擴充套件入口\n│   ├── views/                    # Webview UI\n│   │   ├── SkillManager.ts       # Skill 管理頁面\n│   │   └── CapabilityBuilder.ts  # Capability 組合頁面\n│   ├── providers/                # 資料提供者\n│   │   ├── SkillProvider.ts\n│   │   └── CapabilityProvider.ts\n│   └── services/                 # 核心服務\n│       ├── SkillService.ts\n│       ├── McpService.ts\n│       └── PromptGenerator.ts\n├── webview-ui/                   # 🎨 前端 UI (React/Vue)\n├── .github/prompts/              # 📝 生成的 Prompt Files\n├── .claude/skills/               # 🧩 Skill 定義\n├── memory-bank/                  # 🧠 專案記憶\n└── package.json                  # 擴充套件配置\n```\n\n## 🚀 開發階段\n\n### Phase 1: 核心機制 ✅\n- [x] Prompt Files 機制\n- [x] Skill 模組架構\n- [x] `/cp.xxx` 斜線指令\n\n### Phase 2: VS Code Extension ✅\n- [x] 擴充套件基礎架構\n- [x] Skill Manager GUI\n- [x] Capability Builder GUI\n- [x] Skill TreeView + Editor Webview\n- [x] Capability TreeView + Builder Webview\n- [x] MCP Tools 推薦功能\n- [x] 非線性流程支援（分支/迴圈/並行）\n\n### Phase 3: MCP 整合 🚧\n- [x] MCP Tool 推薦器\n- [ ] Tool 參數設定 UI\n- [ ] 動態工具載入\n\n### Phase 4: 進階功能\n- [ ] Skill 市集（匯入/匯出）\n- [ ] 雲端同步\n- [ ] 團隊共享\n\n## 🛠️ 技術棧\n\n| 層級 | 技術 |\n|------|------|\n| **Python 核心** | DDD 架構, asyncio, dataclasses |\n| **MCP Server** | capability-engine (6 tools) |\n| **VS Code 擴充** | TypeScript, Extension API |\n| **UI 框架** | React / Vue (Webview) |\n| **資料格式** | YAML (Skills), Markdown (Prompts) |\n| **儲存** | 本地檔案 + VS Code Settings |\n\n## 🔌 Copilot 整合方式\n\n本專案提供三種方式與 VS Code Copilot 整合：\n\n### 1️⃣ MCP Server (推薦)\n\n```json\n// mcp.json\n{\n  \"servers\": {\n    \"capability-engine\": {\n      \"command\": \"python\",\n      \"args\": [\"-m\", \"src.capability_engine.infrastructure.mcp.server\"]\n    }\n  }\n}\n```\n\n**提供的 Tools:**\n- `execute_capability` - 執行能力圖\n- `resolve_abstract_node` - 解析抽象節點\n- `validate_graph` - 驗證圖結構\n- `get_complexity_metrics` - 計算複雜度\n- `list_capabilities` - 列出所有能力\n- `get_capability_status` - 取得執行狀態\n\n### 2️⃣ Prompt Injection\n\n動態生成 `.prompt.md` 檔案，透過 `/cp.xxx` 觸發。\n\n### 3️⃣ Chat Participant (進階)\n\n註冊 `@capability` 參與者，完整對話控制。\n\n## 📖 文檔\n\n- [架構設計](ARCHITECTURE.md) - 系統架構與組件設計\n- [**能力系統指南**](docs/CAPABILITY-GUIDE.md) - 📚 如何新增 Skill 與 Workflow\n- [擴充套件設計](docs/EXTENSION-DESIGN.md) - VS Code Extension 詳細設計\n- [Prompt Files 機制](docs/PROMPT-FILES-MECHANISM.md) - 當前運作原理\n- [Skill 改進分析](docs/SKILL-IMPROVEMENT-ANALYSIS.md) - Skill 觸發機制改進\n- [AGENTS.md](AGENTS.md) - Agent 指引\n- [Roadmap](ROADMAP.md) - 開發路線圖\n\n## 🤝 貢獻\n\n歡迎貢獻！請參閱 [CONTRIBUTING.md](CONTRIBUTING.md)。\n\n## 📄 License\n\n[Apache License 2.0](LICENSE)\n",
  "bytes": 8823,
  "sha": "0433789301beb13bdd57d4c67b43d0d6efece77ed0fd02468e8c335343f011b7",
  "repo_slug": "u9401066/copilot-capability-manager",
  "fonte": "repo",
  "truncated": false,
  "api": "https://api.agentalog.com/api/listings/skl_u9401066_copilot_capability_manager_repo_e62a6867/readme"
}