🤖 York (The AI Project Brain)
York 是一個專為 AI Agent 設計的「專案知識管理大腦」。它透過 Model Context Protocol (MCP) 為 Claude 等 AI 提供深度專案認知能力，包含語意搜尋、結構感知與長期記憶管理。
✨ 核心特色
- 🧠 雙腦協作架構 (Cognitive Architecture)
* 結構認知 (Structure): 自動偵測專案框架 (Laravel, FuelPHP, React...) 並理解目錄意義。 * 知識記憶 (Knowledge): 儲存業務邏輯、開發規範與決策紀錄。
- 🔍 混合檢索系統 (Hybrid Search)
* 結合 關鍵字搜尋 (BM25) 與 語意搜尋 (Vector Embedding)。 * 使用 RRF (Reciprocal Rank Fusion) 演算法優化排序。
- ⚡ 高效能 Python 核心
* 基於 FastMCP 與 uv 套件管理。 * 內建 LanceDB 向量資料庫（無須額外安裝 Service）。 * 支援 SentenceTransformers 本機 Embedding 模型。
🚀 快速開始 (Docker 部署)
1. 建置 Docker Image
./build-image.sh2. 設定 Claude Code / Claude Desktop
macOS/Linux — Claude Code
在 ~/.claude/mcp.json 加入（不存在則新建）：
{
"mcpServers": {
"york": {
"command": "/你的/絕對路徑/york/start.sh"
}
}
}macOS/Linux — Claude Desktop
設定檔位置: ~/Library/Application Support/Claude/claude_desktop_config.json
{
"mcpServers": {
"york": {
"command": "/你的/絕對路徑/york/start.sh"
}
}
}Windows — Claude Desktop / Antigravity
{
"mcpServers": {
"york": {
"command": "powershell.exe",
"args": ["-NoProfile", "-ExecutionPolicy", "Bypass", "-File", "C:\\你的路徑\\york\\start.ps1"]
}
}
}3. 重啟 Claude
重啟後應在 🛠️ 圖示中看到 York 的工具。
⚙️ 環境設定
所有資料預設存放在專案內的 .data/ 目錄（已加入 .gitignore）：
york/.data/
├── lancedb/ ← 向量資料庫
└── {project_name}/ ← 知識 Markdown 檔案
└── *.md如需自訂路徑，複製 .env.example 為 .env 並設定：
cp .env.example .env| 環境變數 | 預設值 | 說明 |
|---|---|---|
PROJECTS_DIR | 必填 | 本機專案根目錄 |
YORK_KNOWLEDGE_ROOT | ./data | 知識庫 md 檔存放路徑 |
YORK_VECTOR_DB_PATH | ./data/lancedb | LanceDB 向量資料庫路徑 |
ALLOWED_PROJECTS | 空（允許全部） | 逗號分隔的允許專案名稱 |
🛠️ 可用工具 (MCP Tools)
York 提供 12 個工具，分為三大類：
📚 知識管理 (Knowledge)
| 工具名稱 | 描述 |
|---|---|
save_knowledge_tool | 儲存文件到知識庫，並自動同步向量索引 |
read_knowledge_tool | 讀取特定知識文件的內容與 metadata |
list_knowledge_tool | 列出專案中的所有知識文件 |
delete_knowledge_tool | 刪除知識文件與對應的向量數據 |
get_project_knowledge_tool | 取得專案的完整知識彙整 (project-knowledge.md) |
🔍 搜尋與檢索 (Retrieval)
| 工具名稱 | 描述 |
|---|---|
search_knowledge_tool | 混合搜尋 (關鍵字+語意)，支援 RRF 排序與結構化過濾 |
reindex_knowledge_tool | 手動觸發特定專案的索引重建 |
get_vector_db_stats_tool | 查看向量資料庫狀態 (統計、快取命中率) |
🏗️ 結構認知 (Structure)
| 工具名稱 | 描述 |
|---|---|
detect_project_structure_tool | 自動偵測專案框架並生成 project.structure.yml 建議 |
get_project_structure_tool | 讀取目前的專案結構配置 |
save_project_structure_tool | 儲存結構配置並觸發結構索引更新 |
list_projects_tool | 列出此工作區管理的所有專案 |
🔗 可用資源 (Resources - 支援 @ 引用)
| URI 模式 | 用途 |
|---|---|
project://{name}/structure | 讀取專案目前的目錄結構與架構說明 |
project://{name}/knowledge/{file} | 讀取特定的知識文件 |
📂 專案結構
york/
├── src/
│ ├── agent_server/ # MCP Server 定義與入口
│ ├── knowledge/ # 知識管理核心 (CRUD, Sync, Search)
│ ├── services/ # 基礎服務 (VectorStore: Singleton + LRU)
│ ├── structure/ # 結構認知核心 (Detector, YAML Handler)
│ ├── models/ # Pydantic 資料模型定義
│ └── utils/ # 通用工具 (Logger, Project Helper)
├── scripts/ # 功能演示腳本
├── tests/ # Pytest 測試套件
├── .data/ # 本機資料 (gitignored)
│ ├── lancedb/ # 向量資料庫
│ └── {project}/ # 知識 md 檔
├── Dockerfile
├── start.sh # 容器啟動腳本 (macOS/Linux)
├── start.ps1 # 容器啟動腳本 (Windows)
└── build-image.sh # Docker Image 建置🔧 維運工具
| 工具 | macOS/Linux | Windows | 用途 | ||
|---|---|---|---|---|---|
| 知識庫儀表板 | ./dashboard.sh | .\dashboard.ps1 | 視覺化瀏覽知識庫（http://localhost:8501） | ||
| 資料庫檢查 | ./inspect_db.sh | .\inspect_db.ps1 | 查看向量資料庫詳細內容 | ||
| 重建索引 | ./migrate_knowledge.sh | .\migrate_knowledge.ps1 | 強制重建所有專案的向量索引 | ||
| 資料庫管理 | `./ops_db.sh [backup\ | reset]` | `.\ops_db.ps1 [backup\ | reset]` | 備份或重置 LanceDB |
| 測試 | ./test.sh | .\test.ps1 | 執行完整測試套件 |
📝 開發者指南
若您想在本機直接開發（不使用 Docker）：
# 安裝 uv
curl -LsSf https://astral.sh/uv/install.sh | sh
# 安裝依賴
uv sync --all-extras
# 執行測試
uv run pytest
# 啟動 Server
uv run python -m src