nsforge-mcp: Instructions file for GitHub Copilot

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（14 gates，含 security、mcp、package）

詳見：.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.4.0）

• Runtime 使用 MCPServer、精確 pin MCP Python SDK 2.1.1、protocol revision 2026-07-28。
• Catalog 共 91 tools；固定啟動 profiles 為 legacy 82（預設）、workflow 17、 scientific 35、interactive 35、full 91。Legacy 仍支援 music opt-in。
• 既有工具名稱、input／output schema 與 response payload 是相容性契約；不可為了 MCP 2 metadata 改壞它們。
• 每個工具必須保有 explicit structured output、title、icon、標準 annotations 與 namespaced org.nsforge/* _meta。application error 要保留既有 JSON body 並設 protocol isError。
• Compact profiles 必須拒絕 unknown fields 並實作 ToolSpec 宣告的 enum／range constraints；descriptions 精簡，教學移到 docs／prompt。
• Discovery 可讀 nsforge://manifest、nsforge://health、nsforge://north-star、 nsforge://derivations/{result_id}、nsforge://runs/{run_id}、.../events、 nsforge://sessions/{session_id}、nsforge://artifacts/{sha256}，以及 forge_verified_derivation prompt。
• Strict task results 以 ResourceLink 連到 immutable run／artifact；phase event 同時驅動 provenance、progress、SQLite persistence 與 OTel correlation。
• SDK 2.1.1 尚未實作 MCP Tasks；task_run 是 NSForge tool，不可宣稱為 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。
• Caller expression 只能走中央 allowlisted no-eval parser；不得直接用 parse_expr／sympify；保留 exponent／combinatorial literal complexity budgets。 Repository／artifact／music paths 必須通過 root containment，music root 在註冊時凍結。
• Strict workflow 以 tenant-scoped SQLite UoW 為權威；legacy JSON／YAML 與 process globals 只是相容層。沒有 IdP 時，一個 instance 就是一個 tenant boundary； 不宣稱 cross-replica shared state。