# Copilot 自定義指令 - Zotero Keeper

## 專案概述
這是一個整合 PubMed 文獻搜尋與 Zotero 書目管理的 AI 輔助研究工具組。

## 開發哲學 💡
> **「想要寫文件的時候，就更新 Memory Bank 吧！」**
>
> **「想要零散測試的時候，就寫測試檔案進 tests/ 資料夾吧！」**

## 法規遵循
你必須遵守以下法規層級：
1. **憲法**：`CONSTITUTION.md` - 最高原則
2. **子法**：`.github/bylaws/*.md` - 細則規範
3. **技能**：`.claude/skills/*/SKILL.md` - 操作程序

## 架構原則
- 採用 DDD (Domain-Driven Design)
- DAL (Data Access Layer) 必須獨立
- 參見子法：`.github/bylaws/ddd-architecture.md`

## Python 環境（uv 唯一）
- **所有專案必須使用 uv 管理套件**（禁止使用 pip）
- 必須建立虛擬環境（禁止全域安裝）
- 文件、程式碼、CI 中一律使用 uv 指令
- 參見子法：`.github/bylaws/python-environment.md`

## Memory Bank 同步
每次重要操作必須更新 Memory Bank：
- 參見子法：`.github/bylaws/memory-bank.md`
- 目錄：`memory-bank/`

## Git 工作流
提交前必須執行檢查清單：
- 參見子法：`.github/bylaws/git-workflow.md`

## MCP Server 開發
- pubmed-search-mcp: `external/pubmed-search-mcp/`
- zotero-keeper: `mcp-server/`
- 使用 FastMCP 框架

## VS Code Extension 開發
- 位置: `vscode-extension/`
- 使用 TypeScript
- 發布到 VS Code Marketplace

### 發布流程

#### 1. 版本更新檢查清單
發布前必須同步更新以下檔案的版本號：
- `vscode-extension/package.json` - `version` 欄位
- `vscode-extension/src/statusBar.ts` - `private version` 欄位（fallback 用）
- `vscode-extension/CHANGELOG.md` - 新增版本區塊

#### 2. 編譯驗證
```bash
cd vscode-extension
npm run compile  # 確保無 TypeScript 錯誤
```

#### 3. 提交與發布
```bash
# 提交變更
git add -A && git commit -m "release: vX.Y.Z - 簡短描述"

# 建立 tag 並推送（觸發 CI 自動發布）
git tag -a vX.Y.Z-ext -m "Release vX.Y.Z"
git push && git push origin vX.Y.Z-ext
```

**重要**：tag 格式必須為 `vX.Y.Z-ext`，CI workflow 才會觸發發布

#### 4. 驗證發布成功

**GitHub Actions（最即時）**
```bash
# 檢查 workflow 狀態（推薦用 Python 解析）
curl -s "https://api.github.com/repos/u9401066/zotero-keeper/actions/runs?per_page=10" | \
  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]]))"
```
- `Publish VS Code Extension | v0.5.x-ext | success` 表示成功

**VS Marketplace（5-10 分鐘後更新）**
- URL: https://marketplace.visualstudio.com/items?itemName=u9401066.vscode-zotero-mcp
```bash
# curl 方式（推薦，不會卡住）
curl -s "https://marketplace.visualstudio.com/items?itemName=u9401066.vscode-zotero-mcp" | \
  grep -o '"version":"[^"]*"' | head -1

# npx 方式（可能會卡住，需要下載套件）
# npx @vscode/vsce show u9401066.vscode-zotero-mcp --json | grep version
```



#### 5. 常見問題排除

| 問題 | 原因 | 解決方案 |
|------|------|----------|
| "version already exists" | Marketplace 已有此版本 | 升級版本號重新發布 |
| CI 未觸發 | tag 格式錯誤 | 確保使用 `vX.Y.Z-ext` 格式 |

#### 6. Secrets 設定（Repository Settings）
- `VSCE_PAT` - VS Code Marketplace Personal Access Token

### 平台支援
擴充功能支援以下平台：
- `win32-x64`, `win32-ia32` (Windows)
- `linux-x64`, `linux-arm64` (Linux)
- `darwin-x64`, `darwin-arm64` (macOS)

## 回應風格
- 使用繁體中文
- 提供清晰的步驟說明
- 引用相關法規條文