Copilot instructions

1# Copilot 自定義指令
2 
3此文件為 VS Code GitHub Copilot 的 Agent Mode 提供專案上下文。
4 
5---
6 
7## 開發哲學 💡
8 
9> **「想要寫文件的時候，就更新 Memory Bank 吧！」**
10> 
11> **「想要零散測試的時候，就寫測試檔案進 tests/ 資料夾吧！」**
12 
13---
14 
15## 法規遵循
16 
17你必須遵守以下法規層級：
18 
191. **憲法**：`CONSTITUTION.md` - 最高原則，不可違反
202. **子法**：`.github/bylaws/*.md` - 細則規範
213. **技能**：`.claude/skills/*/SKILL.md` - 操作程序
22 
23---
24 
25## 架構原則
26 
27- 採用 **DDD (Domain-Driven Design)**
28- **DAL (Data Access Layer) 必須獨立**
29- 依賴方向：`Presentation → Application → Domain ← Infrastructure`
30 
31詳見：`.github/bylaws/ddd-architecture.md`
32 
33---
34 
35## Python 環境（uv 優先）
36 
37- **優先使用 uv** 管理套件和虛擬環境
38- 新專案必須建立 `pyproject.toml` + `uv.lock`
39- 禁止全域安裝套件
40 
41```bash
42# 初始化環境
43uv venv
44uv sync --all-extras
45 
46# 安裝依賴
47uv add package-name
48uv add --dev pytest ruff
49```
50 
51詳見：`.github/bylaws/python-environment.md`
52 
53---
54 
55## Memory Bank 同步
56 
57每次重要操作必須更新 Memory Bank：
58 
59| 操作 | 更新文件 |
60|------|----------|
61| 完成任務 | `progress.md` (Done) |
62| 開始任務 | `progress.md` (Doing), `activeContext.md` |
63| 重大決策 | `decisionLog.md` |
64| 架構變更 | `architect.md` |
65 
66詳見：`.github/bylaws/memory-bank.md`
67 
68---
69 
70## Git 工作流
71 
72提交前必須執行檢查清單：
73 
741. ✅ Memory Bank 同步（必要）
752. 📖 README 更新（如需要）
763. 📋 CHANGELOG 更新（如需要）
774. 🗺️ ROADMAP 標記（如需要）
78 
79詳見：`.github/bylaws/git-workflow.md`
80 
81---
82 
83## 可用 Skills
84 
85位於 `.claude/skills/` 目錄：
86 
87### 🔥 NSForge 專用 Skills（MCP 工具組合）
88 
89| Skill | 說明 | 觸發詞 |
90|-------|------|--------|
91| **nsforge-derivation-workflow** | 完整推導工作流 | 推導, derive, 組合公式 |
92| **nsforge-formula-management** | 公式庫管理 | 找公式, 列出, 更新公式 |
93| **nsforge-formula-search** | 外部公式搜尋 | Wikidata, BioModels, 物理常數, PK模型 |
94| **nsforge-verification-suite** | 驗證工具組合 | 驗證, 維度, check |
95| **nsforge-code-generation** | 程式碼/報告生成 | 生成程式碼, LaTeX, 報告 |
96| **nsforge-quick-calculate** | 快速計算（無需會話） | 計算, 簡化, 求解 |
97| **nsforge-usolver-collab** | 🆕 USolver 協作 | 優化, 最佳化, 劑量優化 |
98 
99> 詳細說明見 `docs/nsforge-skills-guide.md`
100 
101### ⚠️ 數學計算黃金法則
102 
103> **「先用 SymPy-MCP 計算驗證，再用 NSForge 存檔管理！」**
104>
105> **「每步計算都要用 `print_latex_expression` 或 `derivation_show()` 顯示給用戶確認！」**
106>
107> **「人類的推導是一步一步的，每步都可加入新元素！」**
108 
109#### 📊 108 工具快速選擇指南（v0.2.4）
110 
111| 我想要... | 用哪個？ | 工具 |
112|-----------|---------|------|
113| 簡化/展開/分解 | SymPy-MCP | `simplify_expression`, `expand_expression`, `factor_expression` |
114| 微分/積分 | SymPy-MCP | `differentiate_expression`, `integrate_expression` |
115| 解方程 | SymPy-MCP | `solve_algebraically`, `solve_linear_system` |
116| ODE/PDE | SymPy-MCP | `dsolve_ode`, `pdsolve_pde` |
117| 矩陣 | SymPy-MCP | `matrix_*` 系列 |
118| 單位換算 | SymPy-MCP | `convert_to_units` |
119| **展開/因式分解** | **NSForge** | `expand_expression`, `factor_expression`, `collect_expression` |
120| **三角/冪次化簡** | **NSForge** | `trigsimp_expression`, `powsimp_expression`, `radsimp_expression` |
121| **部分分式** | **NSForge** | `apart_expression` 🔥 反 Laplace 必備 |
122| **約分/合併** | **NSForge** | `cancel_expression`, `together_expression` |
123| **Laplace 變換** | **NSForge** | `laplace_transform_expression`, `inverse_laplace_transform_expression` 🔥 |
124| **Fourier 變換** | **NSForge** | `fourier_transform_expression`, `inverse_fourier_transform_expression` |
125| **極限** | **NSForge** | `calculate_limit` |
126| **級數展開** | **NSForge** | `calculate_series` |
127| **求和 Σ** | **NSForge** | `calculate_summation` |
128| **不等式** | **NSForge** | `solve_inequality`, `solve_inequality_system` |
129| **機率分佈** | **NSForge** | `define_distribution`, `distribution_stats`, `distribution_probability` |
130| **假設查詢** | **NSForge** | `query_assumptions`, `refine_expression` |
131| 數值計算 | NSForge | `evaluate_numeric` |
132| 等價檢查 | NSForge | `symbolic_equal` |
133| 推導追蹤 | NSForge | `derivation_*` 系列 (31 工具) |
134| 公式存取 | NSForge | `formula_*` 系列 |
135| 驗證 | NSForge | `verify_*`, `check_dimensions` |
136| 程式碼生成 | NSForge | `generate_python_function`, `generate_*` |
137| **優化求解** | **USolver** | 與 `derivation_prepare_for_optimization` 協作 |
138 
139> 💡 **76 NSForge + 32 SymPy-MCP = 108 工具！** 詳見各 Skill 文檔。
140 
141#### 🔥 步進式推導工作流（核心）
142 
143```
144┌─────────────────────────────────────────────────────────────┐
145│  Phase 1: NSForge 開始會話                                  │
146│     derivation_start(name="...", description="...")         │
147├─────────────────────────────────────────────────────────────┤
148│  Phase 2: 循環 - 每一步都可加入人類知識！                    │
149│  ┌────────────────────────────────────────────────────────┐ │
150│  │ 2a. SymPy-MCP: 執行計算                                │ │
151│  │     intro_many([...])                                  │ │
152│  │     introduce_expression(...)                          │ │
153│  │     substitute_expression(...)                         │ │
154│  │     print_latex_expression(...)  # ⚠️ 顯示給用戶！     │ │
155│  ├────────────────────────────────────────────────────────┤ │
156│  │ 2b. NSForge: 記錄這一步                                │ │
157│  │     derivation_record_step(      # 🆕 橋接工具         │ │
158│  │       expression="...",          # SymPy 結果          │ │
159│  │       description="代入 Arrhenius",                    │ │
160│  │       notes="酵素在高溫會變性..."  # ⚡ 人類知識！      │ │
161│  │     )                                                  │ │
162│  ├────────────────────────────────────────────────────────┤ │
163│  │ 2c. NSForge: 加入說明（可選）                          │ │
164│  │     derivation_add_note(         # 🆕 橋接工具         │ │
165│  │       note="建議加入校正因子",                         │ │
166│  │       note_type="correction"     # ⚡ 修正建議         │ │
167│  │     )                                                  │ │
168│  ├────────────────────────────────────────────────────────┤ │
169│  │ 2d. NSForge: 顯示當前狀態（必須！）                    │ │
170│  │     derivation_show()            # 🆕 顯示給用戶！     │ │
171│  └────────────────────────────────────────────────────────┘ │
172│  → 重複 2a-2d，每步都可加入新洞見 → 演化成新公式！          │
173├─────────────────────────────────────────────────────────────┤
174│  Phase 3: NSForge 完成存檔                                  │
175│     derivation_complete(...)        # 存檔 + 元資料        │
176│     derivation_show()               # 🆕 顯示最終結果！    │
177└─────────────────────────────────────────────────────────────┘
178```
179 
180#### 分工原則
181 
182| 任務 | 工具 | 原因 |
183|------|------|------|
184| **計算求解** | SymPy-MCP | 功能完整（ODE、矩陣、單位） |
185| **公式顯示** | `print_latex_expression` 或 `derivation_show()` | 讓用戶確認結果 |
186| **知識存檔** | NSForge | 有溯源、分類、搜尋 |
187| **簡單驗證** | NSForge | `check_dimensions` 等 |
188 
189#### ❌ 禁止行為
190 
191- 不要直接用 `generate_python_function` 生成未經驗證的程式碼
192- **不要跳過顯示步驟**，用 `print_latex_expression` 或 `derivation_show()` 讓用戶看到公式
193- 不要把 SymPy-MCP 的計算結果存成 YAML 檔案（應存為 Markdown）
194 
195#### 🔄 Handoff 機制：無法計算時怎麼辦？
196 
197**當 NSForge 無法處理時（ODE、PDE、複雜矩陣運算），使用 Handoff 工具：**
198 
199> ⚠️ **v0.2.1 後，極限/級數/求和已可用 NSForge 直接計算！**
200> Handoff 主要用於 ODE、PDE、聯立方程組等。
201 
202```
203NSForge 遇到無法處理的操作
204        ↓
205derivation_export_for_sympy()
206        ↓
207→ 返回 intro_many_command, current_expression
208        ↓
209[SymPy-MCP] intro_many([...])
210[SymPy-MCP] introduce_expression("...")
211[SymPy-MCP] dsolve_ode(...) / solve_linear_system(...) / etc.
212[SymPy-MCP] print_latex_expression(...)
213        ↓
214derivation_import_from_sympy(
215    expression="...",
216    operation_performed="Solved ODE",
217    sympy_tool_used="dsolve_ode",
218    notes="...",
219    assumptions_used=[...],
220    limitations=[...]
221)
222        ↓
223繼續 NSForge 步進式推導！
224```
225 
226**Handoff 工具三件套：**
227- `derivation_export_for_sympy()` - 導出當前狀態給 SymPy-MCP
228- `derivation_import_from_sympy()` - 從 SymPy-MCP 導入結果回來
229- `derivation_handoff_status()` - 查看能力邊界和工作流程
230 
231**使用時機：**
232- NSForge 工具返回錯誤
233- 需要解 ODE/PDE
234- 需要複雜矩陣運算
235 
236### 通用開發 Skills
237 
238| Skill | 說明 |
239|-------|------|
240| **git-precommit** | Git 提交前編排器 |
241| **ddd-architect** | DDD 架構輔助與檢查 |
242| **code-refactor** | 主動重構與模組化 |
243| **memory-updater** | Memory Bank 同步 |
244| **memory-checkpoint** | 記憶檢查點（Summarize 前外部化） |
245| **readme-updater** | README 智能更新 |
246| **changelog-updater** | CHANGELOG 自動更新 |
247| **roadmap-updater** | ROADMAP 狀態追蹤 |
248| **code-reviewer** | 程式碼審查 |
249| **test-generator** | 測試生成（Unit/Integration/E2E） |
250| **project-init** | 專案初始化 |
251 
252---
253 
254## 💾 Memory Checkpoint 規則
255 
256為避免對話被 Summarize 壓縮時遺失重要上下文：
257 
258### 主動觸發時機
2591. 對話超過 **10 輪**
2602. 累積修改超過 **5 個檔案**
2613. 完成一個 **重要功能/修復**
2624. 使用者說要 **離開/等等**
263 
264### 執行指令
265- 「記憶檢查點」「checkpoint」「存檔」
266- 「保存記憶」「sync memory」
267 
268### 必須記錄
269- 當前工作焦點
270- 變更的檔案列表（完整路徑）
271- 待解決事項
272- 下一步計畫
273 
274---
275 
276## 回應風格
277 
278- 使用**繁體中文**
279- 提供清晰的步驟說明
280- 引用相關法規條文
281- 執行操作後更新 Memory Bank
282