nsforge-mcp copilot-instructions.md

Copilot 自定義指令

此文件為 VS Code GitHub Copilot 的 Agent Mode 提供專案上下文。

---

開發哲學 💡

「想要寫文件的時候，就更新 Memory Bank 吧！」

「想要零散測試的時候，就寫測試檔案進 tests/ 資料夾吧！」

---

法規遵循

你必須遵守以下法規層級：

1. 憲法：CONSTITUTION.md - 最高原則，不可違反
2. 子法：.github/bylaws/*.md - 細則規範
3. 技能：.claude/skills/*/SKILL.md - 操作程序

---

架構原則

• 採用 DDD (Domain-Driven Design)
• DAL (Data Access Layer) 必須獨立
• 依賴方向：Presentation → Application → Domain ← Infrastructure

詳見：.github/bylaws/ddd-architecture.md

---

Python 環境（uv 優先）

• 優先使用 uv 管理套件和虛擬環境
• 新專案必須建立 pyproject.toml + uv.lock
• 禁止全域安裝套件

# 初始化環境
uv venv
uv sync --all-extras

# 安裝依賴
uv add package-name
uv add --dev pytest ruff

詳見：.github/bylaws/python-environment.md

---

Memory Bank 同步

每次重要操作必須更新 Memory Bank：

操作	更新文件
完成任務	progress.md (Done)
開始任務	progress.md (Doing), activeContext.md
重大決策	decisionLog.md
架構變更	architect.md

詳見：.github/bylaws/memory-bank.md

---

Git 工作流

提交前必須執行檢查清單：

1. ✅ Memory Bank 同步（必要）
2. 📖 README 更新（如需要）
3. 📋 CHANGELOG 更新（如需要）
4. 🗺️ ROADMAP 標記（如需要）
5. ✅ uv run python scripts/check.py（12 gates，含 mcp contract gate）

詳見：.github/bylaws/git-workflow.md

---

可用 Skills

位於 .claude/skills/ 目錄：

🔥 NSForge 專用 Skills（MCP 工具組合）

Skill	說明	觸發詞
nsforge-derivation-workflow	完整推導工作流	推導, derive, 組合公式
nsforge-formula-management	公式庫管理	找公式, 列出, 更新公式
nsforge-formula-search	外部公式搜尋	Wikidata, BioModels, 物理常數, PK模型
nsforge-verification-suite	驗證工具組合	驗證, 維度, check
nsforge-code-generation	程式碼/報告生成	生成程式碼, LaTeX, 報告
nsforge-quick-calculate	快速計算（無需會話）	計算, 簡化, 求解
nsforge-usolver-collab	🆕 USolver 協作	優化, 最佳化, 劑量優化

詳細說明見 docs/nsforge-skills-guide.md

MCP 2.1 協議規則（NSForge 0.3.0）

• Runtime 使用 MCPServer、MCP Python SDK 2.1.1、protocol revision 2026-07-28。
• Catalog 共 91 tools；預設 82，music 9 個需 NSFORGE_ENABLE_MUSIC=1。
• 既有工具名稱、input／output schema 與 response payload 是相容性契約；不可為了 MCP 2 metadata 改壞它們。
• 每個工具必須保有 explicit structured output、title、icon、標準 annotations 與 namespaced org.nsforge/* _meta。application error 要保留既有 JSON body 並設 protocol isError。
• Discovery 可讀 nsforge://manifest、nsforge://health、nsforge://north-star、nsforge://derivations/{result_id}，以及 forge_verified_derivation prompt。
• task_run／task_explore 會透過 MCP Context 回報開始與完成進度；不要把 progress 誤寫成 MCP Tasks extension。
• stdio 為預設；Streamable HTTP 只在明確 opt-in 時啟用。非 loopback 需 allow flag 與真正的外部 authentication／TLS；allow flag 本身不是安全邊界。
• MCP 2 sync handlers 可在 worker threads 執行；session／repository 的共享可變狀態與檔案寫入必須維持 thread-safe／atomic。