Copilot instructions

1# Copilot 自定義指令 - Zotero Keeper
2 
3## 專案概述
4這是一個整合 PubMed 文獻搜尋與 Zotero 書目管理的 AI 輔助研究工具組。
5 
6## 開發哲學 💡
7> **「想要寫文件的時候，就更新 Memory Bank 吧！」**
8>
9> **「想要零散測試的時候，就寫測試檔案進 tests/ 資料夾吧！」**
10 
11## 法規遵循
12你必須遵守以下法規層級：
131. **憲法**：`CONSTITUTION.md` - 最高原則
142. **子法**：`.github/bylaws/*.md` - 細則規範
153. **技能**：`.claude/skills/*/SKILL.md` - 操作程序
16 
17## 架構原則
18- 採用 DDD (Domain-Driven Design)
19- DAL (Data Access Layer) 必須獨立
20- 參見子法：`.github/bylaws/ddd-architecture.md`
21 
22## Python 環境（uv 唯一）
23- **所有專案必須使用 uv 管理套件**（禁止使用 pip）
24- 必須建立虛擬環境（禁止全域安裝）
25- 文件、程式碼、CI 中一律使用 uv 指令
26- 參見子法：`.github/bylaws/python-environment.md`
27 
28## Memory Bank 同步
29每次重要操作必須更新 Memory Bank：
30- 參見子法：`.github/bylaws/memory-bank.md`
31- 目錄：`memory-bank/`
32 
33## Git 工作流
34提交前必須執行檢查清單：
35- 參見子法：`.github/bylaws/git-workflow.md`
36 
37## MCP Server 開發
38- pubmed-search-mcp: `external/pubmed-search-mcp/`
39- zotero-keeper: `mcp-server/`
40- 使用 FastMCP 框架
41 
42## VS Code Extension 開發
43- 位置: `vscode-extension/`
44- 使用 TypeScript
45- 發布到 VS Code Marketplace
46 
47### 發布流程
48 
49#### 1. 版本更新檢查清單
50發布前必須同步更新以下檔案的版本號：
51- `vscode-extension/package.json` - `version` 欄位
52- `vscode-extension/src/statusBar.ts` - `private version` 欄位（fallback 用）
53- `vscode-extension/CHANGELOG.md` - 新增版本區塊
54 
55#### 2. 編譯驗證
56```bash
57cd vscode-extension
58npm run compile  # 確保無 TypeScript 錯誤
59```
60 
61#### 3. 提交與發布
62```bash
63# 提交變更
64git add -A && git commit -m "release: vX.Y.Z - 簡短描述"
65 
66# 建立 tag 並推送（觸發 CI 自動發布）
67git tag -a vX.Y.Z-ext -m "Release vX.Y.Z"
68git push && git push origin vX.Y.Z-ext
69```
70 
71**重要**：tag 格式必須為 `vX.Y.Z-ext`，CI workflow 才會觸發發布
72 
73#### 4. 驗證發布成功
74 
75**GitHub Actions（最即時）**
76```bash
77# 檢查 workflow 狀態（推薦用 Python 解析）
78curl -s "https://api.github.com/repos/u9401066/zotero-keeper/actions/runs?per_page=10" | \
79  python3 -c "import sys,json; d=json.load(sys.stdin); print('\n'.join([f\"{r['name']:30} | {r['head_branch']:15} | {r['conclusion']}\" for r in d['workflow_runs'][:8]]))"
80```
81- `Publish VS Code Extension | v0.5.x-ext | success` 表示成功
82 
83**VS Marketplace（5-10 分鐘後更新）**
84- URL: https://marketplace.visualstudio.com/items?itemName=u9401066.vscode-zotero-mcp
85```bash
86# curl 方式（推薦，不會卡住）
87curl -s "https://marketplace.visualstudio.com/items?itemName=u9401066.vscode-zotero-mcp" | \
88  grep -o '"version":"[^"]*"' | head -1
89 
90# npx 方式（可能會卡住，需要下載套件）
91# npx @vscode/vsce show u9401066.vscode-zotero-mcp --json | grep version
92```
93 
94 
95 
96#### 5. 常見問題排除
97 
98| 問題 | 原因 | 解決方案 |
99|------|------|----------|
100| "version already exists" | Marketplace 已有此版本 | 升級版本號重新發布 |
101| CI 未觸發 | tag 格式錯誤 | 確保使用 `vX.Y.Z-ext` 格式 |
102 
103#### 6. Secrets 設定（Repository Settings）
104- `VSCE_PAT` - VS Code Marketplace Personal Access Token
105 
106### 平台支援
107擴充功能支援以下平台：
108- `win32-x64`, `win32-ia32` (Windows)
109- `linux-x64`, `linux-arm64` (Linux)
110- `darwin-x64`, `darwin-arm64` (macOS)
111 
112## 回應風格
113- 使用繁體中文
114- 提供清晰的步驟說明
115- 引用相關法規條文
116