nsforge-mcp

# 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`
- 禁止全域安裝套件

```bash
# 初始化環境
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。

### ⚠️ 數學計算黃金法則

> **「先用 SymPy-MCP 計算驗證，再用 NSForge 存檔管理！」**
>
> **「每步計算都要用 `print_latex_expression` 或 `derivation_show()` 顯示給用戶確認！」**
>
> **「人類的推導是一步一步的，每步都可加入新元素！」**

#### 📊 工具快速選擇指南（NSForge v0.4.0）

| 我想要... | 用哪個？ | 工具 |
|-----------|---------|------|
| 簡化/展開/分解 | SymPy-MCP | `simplify_expression`, `expand_expression`, `factor_expression` |
| 微分/積分 | SymPy-MCP | `differentiate_expression`, `integrate_expression` |
| 解方程 | SymPy-MCP | `solve_algebraically`, `solve_linear_system` |
| ODE/PDE | SymPy-MCP | `dsolve_ode`, `pdsolve_pde` |
| 矩陣 | SymPy-MCP | `matrix_*` 系列 |
| 單位換算 | SymPy-MCP | `convert_to_units` |
| **展開/因式分解** | **NSForge** | `expand_expression`, `factor_expression`, `collect_expression` |
| **三角/冪次化簡** | **NSForge** | `trigsimp_expression`, `powsimp_expression`, `radsimp_expression` |
| **部分分式** | **NSForge** | `apart_expression` 🔥 反 Laplace 必備 |
| **約分/合併** | **NSForge** | `cancel_expression`, `together_expression` |
| **Laplace 變換** | **NSForge** | `laplace_transform_expression`, `inverse_laplace_transform_expression` 🔥 |
| **Fourier 變換** | **NSForge** | `fourier_transform_expression`, `inverse_fourier_transform_expression` |
| **極限** | **NSForge** | `calculate_limit` |
| **級數展開** | **NSForge** | `calculate_series` |
| **求和 Σ** | **NSForge** | `calculate_summation` |
| **不等式** | **NSForge** | `solve_inequality`, `solve_inequality_system` |
| **機率分佈** | **NSForge** | `define_distribution`, `distribution_stats`, `distribution_probability` |
| **假設查詢** | **NSForge** | `query_assumptions`, `refine_expression` |
| 數值計算 | NSForge | `evaluate_numeric` |
| 等價檢查 | NSForge | `symbolic_equal` |
| 推導追蹤 | NSForge | `derivation_*` 系列 (31 工具) |
| 公式存取 | NSForge | `formula_*` 系列 |
| 驗證 | NSForge | `verify_*`, `check_dimensions` |
| 程式碼生成 | NSForge | `generate_python_function`, `generate_*` |
| **優化求解** | **USolver** | 與 `derivation_prepare_for_optimization` 協作 |

> 💡 **NSForge catalog 91：legacy 82／workflow 17／scientific 35／interactive 35／full 91。**
> Agent 新工作流建議用 `workflow`；舊 client 預設仍是 `legacy`。

#### 🔥 步進式推導工作流（核心）

```
┌─────────────────────────────────────────────────────────────┐
│  Phase 1: NSForge 開始會話                                  │
│     derivation_start(name="...", description="...")         │
├─────────────────────────────────────────────────────────────┤
│  Phase 2: 循環 - 每一步都可加入人類知識！                    │
│  ┌────────────────────────────────────────────────────────┐ │
│  │ 2a. SymPy-MCP: 執行計算                                │ │
│  │     intro_many([...])                                  │ │
│  │     introduce_expression(...)                          │ │
│  │     substitute_expression(...)                         │ │
│  │     print_latex_expression(...)  # ⚠️ 顯示給用戶！     │ │
│  ├────────────────────────────────────────────────────────┤ │
│  │ 2b. NSForge: 記錄這一步                                │ │
│  │     derivation_record_step(      # 🆕 橋接工具         │ │
│  │       expression="...",          # SymPy 結果          │ │
│  │       description="代入 Arrhenius",                    │ │
│  │       notes="酵素在高溫會變性..."  # ⚡ 人類知識！      │ │
│  │     )                                                  │ │
│  ├────────────────────────────────────────────────────────┤ │
│  │ 2c. NSForge: 加入說明（可選）                          │ │
│  │     derivation_add_note(         # 🆕 橋接工具         │ │
│  │       note="建議加入校正因子",                         │ │
│  │       note_type="correction"     # ⚡ 修正建議         │ │
│  │     )                                                  │ │
│  ├────────────────────────────────────────────────────────┤ │
│  │ 2d. NSForge: 顯示當前狀態（必須！）                    │ │
│  │     derivation_show()            # 🆕 顯示給用戶！     │ │
│  └────────────────────────────────────────────────────────┘ │
│  → 重複 2a-2d，每步都可加入新洞見 → 演化成新公式！          │
├─────────────────────────────────────────────────────────────┤
│  Phase 3: NSForge 完成存檔                                  │
│     derivation_complete(...)        # 存檔 + 元資料        │
│     derivation_show()               # 🆕 顯示最終結果！    │
└─────────────────────────────────────────────────────────────┘
```

#### 分工原則

| 任務 | 工具 | 原因 |
|------|------|------|
| **計算求解** | SymPy-MCP | 功能完整（ODE、矩陣、單位） |
| **公式顯示** | `print_latex_expression` 或 `derivation_show()` | 讓用戶確認結果 |
| **知識存檔** | NSForge | 有溯源、分類、搜尋 |
| **簡單驗證** | NSForge | `check_dimensions` 等 |

#### ❌ 禁止行為

- 不要直接用 `generate_python_function` 生成未經驗證的程式碼
- **不要跳過顯示步驟**，用 `print_latex_expression` 或 `derivation_show()` 讓用戶看到公式
- 不要手動寫入 repository YAML；用 `derivation_complete` 保存，需人類文件時再產 Markdown report

#### 🔄 Handoff 機制：無法計算時怎麼辦？

**當 NSForge 無法處理時（ODE、PDE、複雜矩陣運算），使用 Handoff 工具：**

> ⚠️ **v0.2.1 後，極限/級數/求和已可用 NSForge 直接計算！**
> Handoff 主要用於 ODE、PDE、聯立方程組等。

```
NSForge 遇到無法處理的操作
        ↓
derivation_export_for_sympy()
        ↓
→ 返回 intro_many_command, current_expression
        ↓
[SymPy-MCP] intro_many([...])
[SymPy-MCP] introduce_expression("...")
[SymPy-MCP] dsolve_ode(...) / solve_linear_system(...) / etc.
[SymPy-MCP] print_latex_expression(...)
        ↓
derivation_import_from_sympy(
    expression="...",
    operation_performed="Solved ODE",
    sympy_tool_used="dsolve_ode",
    notes="...",
    assumptions_used=[...],
    limitations=[...]
)
        ↓
繼續 NSForge 步進式推導！
```

**Handoff 工具三件套：**
- `derivation_export_for_sympy()` - 導出當前狀態給 SymPy-MCP
- `derivation_import_from_sympy()` - 從 SymPy-MCP 導入結果回來
- `derivation_handoff_status()` - 查看能力邊界和工作流程

**使用時機：**
- NSForge 工具返回錯誤
- 需要解 ODE/PDE
- 需要複雜矩陣運算

### 通用開發 Skills

| Skill | 說明 |
|-------|------|
| **git-precommit** | Git 提交前編排器 |
| **ddd-architect** | DDD 架構輔助與檢查 |
| **code-refactor** | 主動重構與模組化 |
| **memory-updater** | Memory Bank 同步 |
| **memory-checkpoint** | 記憶檢查點（Summarize 前外部化） |
| **readme-updater** | README 智能更新 |
| **changelog-updater** | CHANGELOG 自動更新 |
| **roadmap-updater** | ROADMAP 狀態追蹤 |
| **code-reviewer** | 程式碼審查 |
| **test-generator** | 測試生成（Unit/Integration/E2E） |
| **project-init** | 專案初始化 |

---

## 💾 Memory Checkpoint 規則

為避免對話被 Summarize 壓縮時遺失重要上下文：

### 主動觸發時機
1. 對話超過 **10 輪**
2. 累積修改超過 **5 個檔案**
3. 完成一個 **重要功能/修復**
4. 使用者說要 **離開/等等**

### 執行指令
- 「記憶檢查點」「checkpoint」「存檔」
- 「保存記憶」「sync memory」

### 必須記錄
- 當前工作焦點
- 變更的檔案列表（完整路徑）
- 待解決事項
- 下一步計畫

---

## 回應風格

- 使用**繁體中文**
- 提供清晰的步驟說明
- 引用相關法規條文
- 執行操作後更新 Memory Bank