SpecPilot MCP Server

🤖 AI 驅動的專案管理與規格文件智能生成系統

將自然語言轉換為結構化 PRD、Epic、Task，支援智能依賴分析與並行開發調度

✨ 核心特色

🗣️ 自然語言轉規格	🔍 智能依賴分析	⚡ 並行開發調度	🌿 Git Worktree
AI 驅動	循環檢測	多 Agent	隔離開發

🔗 GitHub 整合	🤖 多 AI 工具	🛠️ MCP 協議	📋 任務管理
自動同步	5 平台支援	9 核心工具	狀態追蹤

🏗️ 重構架構	❌ 統一錯誤處理	🔧 依賴注入	⚡ 非同步優化
模組化	AI 友善	可測試	高效能

🚀 快速開始

一鍵安裝

curl -fsSL https://raw.githubusercontent.com/sacahan/SpecPilot/main/install.sh -o install.sh
chmod +x install.sh && ./install.sh

驗證安裝

./verify-mcp-server.sh

📋 目錄

📥 完整安裝指南
🎯 使用指南
🛠️ 開發指南
🔧 故障排除

📥 完整安裝指南

📋 系統要求

項目	要求
作業系統	macOS, Linux (Ubuntu/Debian)
Node.js	>= 16.0.0
Git	任何版本
套件管理器	npm 或 pnpm (推薦)

🤖 AI 模型要求

⚠️ 重要: AI 模型需具備足夠推理能力才能有效生成高品質規格文件

類別	說明
推薦模型	Claude Sonnet 4、GPT-5、Gemini 2.5 Pro
最低要求	邏輯推理、結構化思考和上下文理解能力
文件品質警告	推理能力較弱的模型可能產生不完整或不準確的規格

🚀 安裝步驟

1. 下載並執行安裝腳本

curl -fsSL https://raw.githubusercontent.com/sacahan/SpecPilot/main/install.sh -o install.sh
chmod +x install.sh && ./install.sh

2. 驗證安裝

./verify-mcp-server.sh

3. 配置 Claude Code (可選)

claude mcp reset-project-choices

🎯 安裝功能概述

✅ 環境檢測 - 自動檢測系統環境和依賴
✅ MCP 配置 - 配置 5 種 AI 開發工具的 MCP 設定
✅ 專案結構 - 建立標準專案目錄結構和模板檔案
✅ 空間優化 - 移除 ~70% 不必要檔案，僅保留運行必需元件

🤖 支援的 AI 工具

工具	配置檔案	狀態
Claude Code	`~/.claude/claude.json`	✅
Codex CLI	`~/.codex/config.toml`	✅
Cursor IDE	`~/.cursor/mcp.json`	✅
Gemini CLI	`~/.gemini/settings.json`	✅
VS Code	`~/.vscode/mcp.json`	✅

🎯 使用指南

🔄 開發流程概覽

graph LR
    A[自然語言需求] --> B[PRD 生成]
    B --> C[TSD 技術規格]
    C --> D[Epic 實施階段]
    D --> E[Task 開發任務]

    B --> B1[prd-generate]
    C --> C1[tsd-generate]
    D --> D1[epic-generate]
    E --> E1[task-generate]

📋 開發階段對照表

階段	工具	輸入	輸出	目的
需求分析	`prd-generate`	自然語言描述	`specs/prd/prd-{name}.md`	產品需求文件
技術設計	`tsd-generate`	PRD 文件	`specs/tsd/tsd-{num}.md`	技術規格說明
實施規劃	`epic-generate`	TSD 文件	`specs/epics/epic-{num}.md`	開發階段劃分
任務分解	`task-generate`	Epic 文件	`specs/tasks/task-{num}.md`	具體開發任務

🔄 狀態管理系統

Task 狀態流程

stateDiagram-v2
    [*] --> new : task-generate
    new --> in_progress : start-task
    in_progress --> review : prepare-pr
    review --> done : close-task

    new --> blocked : 手動設定
    in_progress --> blocked : 遇到阻礙
    blocked --> in_progress : 繼續開發

    done --> [*]

Epic 狀態流程

stateDiagram-v2
    [*] --> draft : epic-generate
    draft --> assigned : task-generate
    assigned --> done : all tasks done
    done --> [*]

🏷️ 狀態管理參考

Task 狀態定義

狀態	說明	觸發條件
`new`	等待開發	任務生成完成
`in_progress`	開發中	執行 `start-task`
`review`	程式碼審查	提交 PR
`done`	已完成	合併 PR
`blocked`	被阻擋	手動設定

Epic 狀態定義

狀態	說明	觸發條件
`draft`	等待分拆任務	Epic 生成完成
`assigned`	任務已分拆	執行 `task-generate`
`done`	全部完成	所有任務為 `done`

3. Git Worktree 開發流程

sequenceDiagram
    participant M as Main Branch
    participant W as Worktree
    participant G as GitHub

    Note over M,G: 🚀 開始開發
    M->>W: start-task (建立隔離環境)
    W->>W: 開發 & 測試

    Note over M,G: 🔄 狀態同步 (雙重更新)
    W->>W: 更新 worktree 任務檔案
    W->>M: 同步狀態到主線
    M->>G: 同步到 GitHub Issue

    Note over M,G: 🎯 完成開發
    W->>G: prepare-pr (建立 PR)
    G->>G: 程式碼審查
    G->>M: close-task (合併 PR)
    M->>W: 清理 worktree

4. 依賴關係管理

graph TD
    A[task-001: 用戶註冊API] --> C[task-003: 登入功能]
    B[task-002: 資料庫模型] --> C
    B --> D[task-004: 個人資料管理]
    C --> E[task-005: 密碼重設]

    subgraph "並行群組 1"
        A
        B
    end

    subgraph "並行群組 2"
        C
        D
    end

    subgraph "並行群組 3"
        E
    end

依賴類型	檢查工具	說明	處理方式
線性依賴	`check-dependencies`	A 完成後才能開始 B	按順序執行
並行群組	`check-dependencies`	同群組任務可並行執行	多 Agent 協作
循環依賴	`check-dependencies`	A 依賴 B，B 又依賴 A	❌ 系統自動檢測並報錯
阻塞依賴	`next-action`	依賴任務被 blocked	🚫 暫停相關任務

🤖 next-action 建議邏輯

專案生命週期智能建議

next-action 工具會根據專案當前狀態，智能分析並提供下一步最佳行動建議：

🚀 階段 0: 空專案初始化

檔案狀態: 無任何規格文件建議:

🥇 Create your first PRD (prd-generate) - 建立產品需求文件

📋 階段 1: 需求分析完成

檔案狀態: 有 PRD，無 TSD 建議:

🥇 Generate TSD from PRD (tsd-generate) - 生成技術規格文件

🏗️ 階段 2: 技術架構完成

檔案狀態: 有 PRD + TSD，無 Epic 建議:

🥇 Break down TSD into Epics (epic-generate) - 分解為實施階段

📝 階段 3: 實施規劃完成

檔案狀態: 有 PRD + TSD + Epic，無 Task 建議:

🥇 Generate tasks from Epic (task-generate) - 從需要分拆的 Epic 生成開發任務
智能分析: 自動檢測哪些 Epic 處於 draft 狀態且無關聯任務
優先級選擇: 優先選擇最高優先級且需要分拆的 Epic

💻 階段 4: 開發執行階段

檔案狀態: 完整規格文件 + 開發任務 建議優先級:

Resumable Tasks (最高優先級)
- in_progress: 繼續開發 + 準備審查 (prepare-pr)
- review: 繼續開發 + 關閉任務 (close-task) ✅
Ready Tasks (中優先級)
- new (依賴已滿足): 開始開發 (start-task)
Blocked Analysis (低優先級)
- 依賴分析和解決建議 (check-dependencies)

🏁 階段 5: 專案完成階段

檔案狀態: 所有任務狀態為 done 建議:

🥇 Start next development cycle (prd-generate) - 創建新 PRD 開始下一個功能週期
智能版本管理: 自動生成下一版本號 (prd-002, prd-003...)
週期延續: 完成 → 新 PRD → TSD → Epic → Task → 完成...
上下文感知: 分析已完成功能，建議改進或新功能

Scope 參數說明

scope: "project": 執行完整生命週期分析
scope: "task": 專注於開發階段任務分析
scope: "development": 分析並行開發機會
scope: "resume": 專注於可恢復的任務

🛠️ 核心 MCP 工具 (9 個)

專案管理工具

工具	功能
`project-init`	初始化專案目錄結構
`project-status`	計算進度百分比、健康度
`next-action`	智能下一步行動建議

文件生成工具

工具	功能	輸出位置
`prd-generate`	PRD 規格文件生成	`specs/prd/`
`tsd-generate`	技術規格文檔生成	`specs/tsd/`
`epic-generate`	Epic 檔案生成	`specs/epics/`
`task-generate`	開發任務生成	`specs/tasks/`

分析工具

工具	功能
`check-dependencies`	檢查相依性循環、並行分組衝突
`analyze-project`	專案結構分析

🤖 AI 整合特色

🧠 智能 Agent 推薦 - 每個 Task 自動產生 AI 開發提示
🌿 Worktree 隔離開發 - 強制使用 Git Worktree 確保代碼穩定性
🔄 並行開發調度 - 智能分析並行開發機會
🔗 Multi-Agent 支援 - 支援專業 Agent (frontend-expert, python-dev-expert 等)

🎯 快速使用範例

基本開發流程

# 1. 初始化專案
使用 project-init 初始化專案結構

# 2. 建立 PRD (產品需求文件)
使用 prd-generate 建立電商平台 PRD

# 3. 生成技術設計 (TSD)
使用 tsd-generate 將 PRD 轉換為技術設計規格

# 4. 分解實施階段 (Epic)
使用 epic-generate 將 TSD 分解為開發階段

# 5. 生成開發任務 (Task)
使用 task-generate 分解為具體開發任務

# 6. 查看專案狀態
使用 project-status 查看進度和健康度

# 7. 獲取智能建議
使用 next-action 獲取下一步行動建議

MCP 工具 JSON 呼叫範例

點擊展開詳細範例

1. 初始化專案

{
    "tool": "project-init",
    "arguments": { "create_dirs": true, "create_default_policy": true }
}

2. 建立第一份 PRD

{
    "tool": "prd-generate",
    "arguments": {
        "kind": "PRD",
        "id": "prd-001",
        "dest": "specs/prd/prd-001.md",
        "text": "我要做一個 OAuth 登入功能，支援 Google 和 GitHub，並在首次登入後導向使用者設定頁。",
        "vars": { "owner": "alice" }
    }
}

3. 從 PRD 分析成技術設計規格TSD

{
    "tool": "tsd-generate",
    "arguments": {
        "source": "specs/prd/prd-001.md",
        "id": "tsd-001",
        "dest": "specs/tsd/tsd-001.md"
    }
}

4. 從 TSD 拆解成 Epics

{
    "tool": "epic-generate",
    "arguments": {
        "source": "specs/tsd/tsd-001.md",
        "id": "epic-001",
        "dest": "specs/epics/epic-001.md"
    }
}

5. 智能拆解 Epic 為 Tasks（含相依性分析）

{
    "tool": "task-generate",
    "arguments": {
        "source": "specs/epics/epic-001.md",
        "count": 6,
        "analyze_dependencies": true,
        "parallel_groups": 3
    }
}

5. 檢查狀態與並行建議

{ "tool": "project-status", "arguments": { "scope": "project" } }
{ "tool": "next-action", "arguments": { "scope": "spec", "target": "design-spec", "include_parallelization": true } }

6. 檢查相依性與可執行任務

{
    "tool": "check-dependencies",
    "arguments": {
        "validate_parallel": true
    }
}

📁 專案結構與檔案命名規範

安裝完成後，您的專案將擁有以下結構：

your-project/
├── specs/
│   ├── prd/          # Product Requirements Documents (prd-{project-name}.md)
│   ├── tsd/          # Technical Specification Documents (tsd-{number}.md)
│   ├── epics/        # Epic Implementation Phases (epic-{tsd-number}-{epic-number}.md)
│   └── tasks/        # Development Tasks (task-{tsd-number}-{epic-number}-{task-number}.md)
│
├── .specpilot/
├── .env              # 環境變數配置
└── .specpilot-install.log # 安裝日誌

🔧 驗證安裝

執行驗證腳本確保一切正常：

./verify-mcp-server.sh

驗證內容包括：

✅ 安裝目錄和檔案完整性
✅ Node.js 環境和版本檢查
✅ 套件依賴完整性
✅ MCP 服務器啟動測試
✅ MCP 工具註冊與功能驗證
✅ 個別工具回應測試
✅ AI 工具配置狀態

📊 驗證腳本修復說明

版本 0.5.1+ 重要改進：

修復誤報問題：改善 JSON 回應解析邏輯，解決在某些系統環境下的誤報
增強相容性：優化 timeout 命令處理，提升 macOS 系統相容性
智能檢測：新增備用檢測機制，確保 MCP Server 功能正常時不會誤報失敗
🧪 測試完善：達成 100% 測試通過率 (170/170)，全面提升代碼品質
🔧 腳本強化：改善 specpilot-workflow.sh 錯誤處理和日誌功能
📋 文檔更新：完善工作流程說明和 AI Agent 使用指引

預期結果：

📊 Verification Results Summary
==================================
Total tests: 15
Passed: 12-15    # 根據環境配置不同
Failed: 0-3      # 主要為非關鍵的配置檢查

🎉 All critical tests passed! SpecPilot MCP Server is fully operational. ✅

注意事項：

如果看到 "MCP tools not properly registered" 但工具實際可用，這通常是環境相容性問題，不影響實際功能
建議直接在 AI 工具中測試 SpecPilot 功能來確認運作狀態

🧪 完整測試覆蓋

168 個測試案例，涵蓋單元測試、整合測試與架構驗證測試
通過率: 100% (168/168 測試通過) ✅ 完全通過
Vitest 框架，支援 watch mode 和 UI 介面
多層測試架構，包含配置合併、清理功能、相依性檢查與錯誤處理測試
架構驗證測試，確保 AI 驅動分離式架構設計的正確性

🚨 測試狀態

✅ 全部通過: 所有 168 個測試案例都已通過
✅ 穩定架構: 核心功能、檔案掃描、MCP 工具整合、依賴檢查、架構驗證全部穩定
🎯 測試品質: 實現真正的功能測試，避免過度 mock，確保高品質測試覆蓋

🏗️ v0.5.1 重構成果

📊 重構統計

✅ 高優先級改進: 100% 完成 (4/4 項目)
🔧 新增架構組件: 3 個核心系統
📈 程式碼品質: 8.5/10 評分
🧪 測試穩定性: 維持 100% 通過率

🎯 主要改進項目

1. 🧪 測試覆蓋率提升

改善測試架構，遵循最佳實踐原則
整合測試和邊界案例優化
維持 100% 通過率，確保程式碼穩定性

2. ❌ 統一錯誤處理系統

新增: src/utils/error-handling.ts
SpecPilotError 類別：統一的錯誤格式
ErrorFactory：標準化錯誤生成
AI 友善錯誤：自動生成修復建議
MCP 協議整合：結構化錯誤回應

3. 🔧 依賴注入架構

新增: src/config/index.ts - 配置管理系統
新增: src/services/index.ts - 服務容器
ConfigManager：環境變數和配置管理
ServiceContainer：依賴注入容器
BaseService：服務基類，提升可測試性

4. ⚡ 非同步操作優化

修復同步操作：消除 fg.sync() 阻塞
提升效能：避免事件循環阻塞
改善響應性：全面採用非同步模式

📋 架構改善效果

錯誤處理：

// 統一錯誤處理範例
try {
    const result = await operation();
} catch (error) {
    return ErrorHandler.handleMCPToolError(error, "tool-name", { context });
}

依賴注入：

// 服務使用範例
export class MyService extends BaseService {
    async doWork() {
        const config = this.config;
        const logger = this.logger;
        const fileSystem = this.fileSystem;
    }
}

配置管理：

// 配置驅動開發
const config = getConfig();
const patterns = config.getFilePatterns();
const debugMode = config.get("debug").enabled;

🎉 重構價值

📋 更好的錯誤處理：統一、結構化、AI友善
🔧 更高的可測試性：依賴注入讓測試更容易
⚙️ 更好的配置管理：環境驅動的靈活系統
🚀 更好的效能：消除同步操作阻塞
📚 更好的可維護性：模組化設計和清晰邊界

📖 詳細重構報告：查看 REFACTORING_SUMMARY.md

統一測試指令

# 執行完整測試套件（安裝、清理、單元、整合測試）
./tests/test-runner.sh all

# 僅執行 Vitest 單元和整合測試
pnpm test:run

# 測試安裝腳本配置合併功能
./tests/test-runner.sh install

# 測試安裝後清理功能
./tests/test-runner.sh cleanup

# 測試 UI 介面
pnpm test:ui

# 測試覆蓋率
pnpm test:coverage

🚀 進階功能

空間優化安裝

安裝完成後，SpecPilot 會自動移除不必要的開發檔案：

保留必需元件: configs/, scripts/, .github/, .specpilot/
移除開發檔案: src/, tests/, .git/, .github/, 文檔檔案、建置配置等
Epic 狀態管理: 智能三狀態系統 (draft → assigned → done)
精準任務分拆: next-action 自動識別需要分拆任務的 Epic
個別 Epic 追蹤: 每個 Epic 獨立分析任務關聯狀態
空間節省: 移除約 70% 檔案（23+ 項目），大幅減少儲存空間佔用
功能完整: 保留 MCP 服務器運行所需的所有核心功能

Task YAML 結構範例

---
id: task-001
status: new
created: 2025-01-15T10:00:00Z
updated: 2025-01-15T10:00:00Z
epic: epic-001
priority: high
estimate: 16h

# 🤖 AI 開發提示
ai_hints:
    complexity: medium
    parallelizable: true
    sub_agent_suitable: true

# 依賴性管理
dependencies:
    depends_on: [task-002, task-003]
    parallel_group: 1
---
# 實作用戶註冊 API endpoint

建立支援 email/password 註冊的 REST API endpoint，包含完整的驗證機制。

🔄 Task Status System

SpecPilot 使用簡化的狀態系統來追蹤開發進度：

狀態流程: new → in_progress → review → done (+ blocked)

狀態	說明	觸發條件	next-action 行為
new	任務已建立，等待開發	任務生成時	依賴完成時建議開發
in_progress	開發進行中	執行 `start-task` 腳本	建議繼續開發
review	程式碼審查中	提交 PR 後	不建議修改
done	已完成並合併	PR 合併到主線後	跳過分析
blocked	被阻擋或等待中	手動設定	不建議開發

重要改進:

移除了 ready 狀態: next-action 動態計算可開發的任務
明確的轉換條件: 每個狀態變更都有明確的觸發點
與 Git 工作流整合: 狀態變更與 PR 生命週期同步

🐛 故障排除

常見問題快速修復

Node.js 版本問題：

# macOS
brew install node

# Linux
curl -fsSL https://deb.nodesource.com/setup_lts.x | sudo -E bash -
sudo apt-get install -y nodejs

NPX 快取問題（重要！）：

# 清理 NPX 快取（重複安裝時必須執行）
npm cache npx rm $(npm cache npx ls | grep $(pwd) | cut -d: -f1)

# 或者清理所有 NPX 快取
npm cache clean --force

驗證腳本問題：

# 如果驗證腳本顯示 FAIL 但功能正常，可以直接測試 MCP Server
echo '{"jsonrpc": "2.0", "id": 1, "method": "tools/list", "params": {}}' | npx specpilot-mcp-server

# 預期看到 JSON 回應包含工具列表，代表 MCP Server 正常運行

環境變數設定（建議）：

# 設定 SPECROOT 指向您的專案目錄
export SPECROOT=/absolute/path/to/your/project

# 永久設定（新增到 ~/.bashrc 或 ~/.zshrc）
echo 'export SPECROOT=/absolute/path/to/your/project' >> ~/.bashrc

更多詳細的故障排除指南請參考 INSTALLATION.md

🛠️ 開發指令

# 安裝依賴
pnpm i

# 開發模式（需要設定 SPECROOT）
export SPECROOT=/absolute/path/to/my-project
export SPECPILOT_DEBUG=true
pnpm dev

# 編譯專案
pnpm build

# 執行測試
pnpm test:run

# 測試 UI 介面
pnpm test:ui

# 測試覆蓋率
pnpm test:coverage

🤝 取得協助

遇到問題？我們提供多種協助管道：

快速診斷: 執行 ./scripts/verify-install.sh
GitHub Issues: 提交問題報告
完整文檔:
- 📖 腳本操作指南
- 🏗 DEBUG指南

🔄 GitHub 整合與自動化工作流

GitHub Integration 腳本系統

SpecPilot 提供完整的 GitHub 整合功能，通過 scripts/github/ 目錄實現：

智能同步: Epic 和 Task 與 GitHub Milestones 和 Issues 的雙向同步
自動化管理: 完整的項目管理工作流程自動化
狀態追蹤: 實時狀態同步和進度計算
標籤系統: 自動化標籤管理和分類

🚀 快速開始

安裝時自動執行 (推薦)：

GitHub 標籤在 install.sh 安裝過程中自動設定
當檢測到 GitHub CLI 認證和 repository 存取權限時自動執行

手動執行 (如需要)：

# 手動設定 GitHub 標籤系統 (如安裝時未執行)
./scripts/github/setup-labels.sh

# 同步所有 Epic 和 Task 到 GitHub
./scripts/github/github-manager.sh sync-all

# 查看專案狀態
./scripts/github/github-manager.sh project-status

Epic → GitHub Milestones 自動同步

當創建或更新 Epic 時，系統會：

自動創建對應的 GitHub Milestone
同步 Epic 狀態和描述
計算並更新完成進度百分比
關聯相關的 Task Issues
增強的錯誤處理和日誌記錄

Task → GitHub Issues 自動同步

當創建或更新 Task 時，系統會：

自動創建帶有標準化標題的 GitHub Issue
提取 YAML frontmatter 的所有元數據
自動分配適當的標籤 (狀態、優先級、複雜度、預估時間)
關聯到相應的 Epic Milestone
同步開發進度和狀態變更

🏷️ 智能標籤系統

自動創建和管理的標籤包括：

狀態標籤:

status:new, status:in-progress, status:review, status:done, status:blocked

優先級標籤:

priority:low, priority:medium, priority:high, priority:critical

類型標籤:

type:task, type:epic, type:bug, type:feature

複雜度標籤:

complexity:low, complexity:medium, complexity:high

預估時間標籤:

estimate:1h, estimate:2h, estimate:1d, estimate:1w 等

Agent 類型標籤:

agent:frontend, agent:backend, agent:fullstack, agent:testing

📋 開發週期整合

Epic 開發週期:

# 1. 創建 Epic 後自動同步到 GitHub Milestone
./scripts/github/github-manager.sh sync-epic epic-001

# 2. 開發過程中更新 Epic 狀態並同步
./scripts/github/github-manager.sh update-milestone epic-001

Task 開發週期 (雙重更新策略):

# 1. 創建 Task 後自動同步到 GitHub Issue
./scripts/github/github-manager.sh sync-task task-001

# 2. 開始開發時建立隔離環境
./scripts/specpilot-workflow.sh start-task task-001
cd ./workspaces/task-001

# 3. 開發過程中的狀態更新 (關鍵！)
# Step A: 更新 worktree 中的 task 文件
# 編輯 workspaces/task-001/specs/tasks/task-001.md

# Step B: 立即同步狀態到主線 (確保可見性)
cd ../../  # 回到專案根目錄
# 編輯 specs/tasks/task-001.md (僅更新狀態相關欄位)

# Step C: 同步到 GitHub Issue
./scripts/github/github-manager.sh sync-task task-001

# 4. 完成開發並創建 PR
cd ./workspaces/task-001
git push -u origin task-001-feature
cd ../../
./scripts/specpilot-workflow.sh prepare-pr task-001 "完成描述"

🔄 雙重更新策略說明:

Worktree 更新: 完整的開發記錄和 PR 內容
主線同步: 即時狀態可見性，確保 project-status 和 GitHub 整合正常運作
GitHub 同步: 外部專案管理和團隊協作可見性

批量同步操作:

# 同步整個專案到 GitHub
./scripts/github/github-manager.sh sync-all

# 查看專案與 GitHub 整合狀態
./scripts/github/github-manager.sh project-status

MANDATORY Git Worktree 隔離開發流程

🚨 重要: 所有任務開發都必須使用 Git Worktree 進行隔離開發！ 這是 SpecPilot 的標準開發流程，確保代碼穩定性和清晰的版本控制。

SpecPilot 內建完整的 Git worktree 自動化腳本，位於 scripts/ 目錄，提供從開發到部署的完整工作流程。

為什麼必須使用 Worktree？

🔒 代碼隔離: 每個任務在獨立環境中開發，避免主分支干擾
🛡️ 安全開發: 實驗性代碼不會影響主專案穩定性
📋 版本控制: 清晰的分支歷史和 PR 流程
🔄 接續開發: AI agent 中斷後，後續 agent 能準確接續開發位置
🧪 測試隔離: 每個任務有獨立的測試和構建環境

標準開發工作流程 (AI Agent 必須遵循)

# 🟢 步驟 1: 開始任務開發 (在主專案目錄)
./scripts/specpilot-workflow.sh start-task task-001

# 🟢 步驟 2: 切換到專用開發環境
cd ./workspaces/task-001

# 🟢 步驟 3: 進行開發工作 (所有開發都在此目錄)
# - 編寫代碼
# - 運行測試
# - 階段性提交
git add . && git commit -m "feat(task-001): 實作功能"

# 🟢 步驟 4: 完成開發並創建 PR
git push -u origin task-001-feature
cd ../SpecPilot
./scripts/specpilot-workflow.sh prepare-pr task-001 "任務完成標題"

# 🟢 步驟 5: 代碼審查通過後合併
./scripts/specpilot-workflow.sh close-task task-001 squash

中斷與接續開發指導

# 如果是接續其他 AI agent 的工作：
./scripts/specpilot-workflow.sh list-worktrees  # 檢查現有環境
cd ./workspaces/task-001  # 切換到工作環境
git status && git log --oneline -5  # 了解當前進度

# 如果需要中斷開發：
git add . && git commit -m "wip(task-001): 中斷點保存"
git push origin task-001-feature  # 保存到遠端

目錄結構

專案根目錄/
├── SpecPilot/                 # 主專案 (main 分支)
├── workspaces/
│   ├── task-001/              # Task-001 開發環境
│   ├── task-002/              # Task-002 開發環境
│   └── ...

📋 完整工作流程範例

🎯 範例場景：電商用戶認證系統

我們將建立一個電商平台的用戶認證系統，包含：

用戶註冊和登入
JWT Token 管理
密碼重設
個人資料管理

步驟 1: 建立 PRD

{
    "tool": "prd-generate",
    "arguments": {
        "kind": "PRD",
        "id": "prd-001",
        "dest": "specs/prd/prd-001.md",
        "text": "建立一個安全的電商用戶認證系統，支援註冊、登入、密碼重設和個人資料管理。需要支援 JWT Token 認證，並整合第三方 OAuth (Google, GitHub)。",
        "vars": { "owner": "development-team" }
    }
}

步驟 2: 生成技術設計規格TSD

{
    "tool": "tsd-generate",
    "arguments": {
        "source": "specs/prd/prd-001.md",
        "text": "Generate a technical design specification based on the provided PRD."
    }
}

步驟 3: 生成 Epic

{
    "tool": "epic-generate",
    "arguments": {
        "source": "specs/tsd/tsd-001.md",
        "count": 1
    }
}

步驟 4: 生成開發任務

{
    "tool": "task-generate",
    "arguments": {
        "source": "specs/epics/epic-001.md",
        "count": 4,
        "analyze_dependencies": true,
        "parallel_groups": 2
    }
}

步驟 5: 檢查專案狀態

{
    "tool": "project-status",
    "arguments": { "scope": "project" }
}

範例輸出:

📊 Project Status: E-commerce Platform (65% complete)

📈 Progress: 13/20 tasks completed (65%)
🏥 Health Score: 8.5/10

📋 Task Distribution:
  ✅ Done: 13 tasks
  🔍 Review: 3 tasks
  🚧 In Progress: 2 tasks
  ⏳ Ready: 1 task
  ❌ Blocked: 1 task

⚠️ Attention Required:
  - 2 tasks have been blocked for >3 days
  - 1 circular dependency detected in auth module

步驟 6: 獲取下一步建議

{
    "tool": "next-action",
    "arguments": {
        "scope": "spec",
        "target": "epic-001",
        "include_parallelization": true
    }
}

範例輸出:

🎯 Next Actions for: epic-001

🚀 Ready to Execute (2 tasks):
  1. task-001: Implement user registration API
     📍 No dependencies | ⏱️ 8h | 🤖 python-dev-expert

  2. task-003: Create user profile management UI
     📍 No dependencies | ⏱️ 6h | 🤖 frontend-expert

💡 Parallel Development Strategy:
  Group 1 (Backend): task-001, task-002
  Group 2 (Frontend): task-003, task-004

🤖 Sub-Agent Assignments:
  - python-dev-expert: Handle backend API development
  - frontend-expert: Handle React components and UI

步驟 7: GitHub 整合

自動同步到 GitHub

# 使用 GitHub Actions workflow
# 當推送 specs/ 變更時自動觸發
git add specs/
git commit -m "feat: Add user authentication system specs"
git push origin main

創建的 GitHub 資源

Milestone: "E-commerce Platform"

描述: Auto-synced from specs/prd/prd-001.md
狀態: Open

Issues (自動創建):

[task-001] 實作用戶註冊 API endpoint
- 標籤: task, new, high, estimate:8h
- 指派: 根據 recommended_agent 自動指派給後端團隊

步驟 8: 開發執行

AI Agent 工作流程建議

開始開發:

./scripts/specpilot-workflow.sh start-task task-001
cd ../workspaces/task-001

實作與測試: 根據任務的 development_guide 進行開發

提交審查:

git add . && git commit -m "feat: implement task-001"
git push -u origin task-001-feature
cd ../main-project
./scripts/specpilot-workflow.sh create-pr task-001

監控與完成:

./scripts/specpilot-workflow.sh check-pr task-001
./scripts/specpilot-workflow.sh close-task task-001

🛠️ 開發指南

開發環境設定

# 安裝依賴
pnpm install

# 設定環境變數
export SPECROOT=/absolute/path/to/your/project

# 開發模式
pnpm dev

# 編譯專案
pnpm build

測試

# 執行所有測試 (170 個測試案例)
pnpm test:run

# 測試覆蓋率
pnpm test:coverage

# 完整測試套件
./tests/test-runner.sh all

專案結構

your-project/
├── specs/
│   ├── prd/          # Product Requirements Documents
│   ├── tsd/          # Technical Specification Documents
│   ├── epics/        # Epic Implementation Phases
│   └── tasks/        # Development Tasks
├── .specpilot/       # SpecPilot 配置
└── .env              # 環境變數

🔧 故障排除

常見問題

Node.js 版本問題

# macOS
brew install node

# Linux
curl -fsSL https://deb.nodesource.com/setup_lts.x | sudo -E bash -
sudo apt-get install -y nodejs

NPX 快取問題

# 清理 NPX 快取
npm cache clean --force

環境變數設定

# 設定 SPECROOT
export SPECROOT=/absolute/path/to/your/project
echo 'export SPECROOT=/absolute/path/to/your/project' >> ~/.bashrc

驗證 MCP Server

# 手動測試 MCP Server
echo '{"jsonrpc": "2.0", "id": 1, "method": "tools/list", "params": {}}' | npx specpilot-mcp-server

取得協助

📊 快速診斷: 執行 ./verify-mcp-server.sh
🐛 問題回報: GitHub Issues
📖 完整文檔: 查看 INSTALLATION.md 和 DEBUG.md

📊 專案統計

測試狀態: ✅ 100% 通過率 (168/168 測試案例)
測試覆蓋率: 35.9% (v8 coverage)
MCP 工具: 9 個核心工具
支援平台: 5 種 AI 開發工具
版本: 0.5.1 (重構版本)
程式碼品質: 8.5/10 評分
重構成果: 統一錯誤處理 + 依賴注入 + 非同步優化

🚀 開始使用 SpecPilot，讓 AI 驅動您的專案管理！

安裝指南 • 使用說明 • 開發文檔

Name		Name	Last commit message	Last commit date
Latest commit History 108 Commits
.claude		.claude
.github		.github
configs		configs
scripts		scripts
src		src
tests		tests
.editorconfig		.editorconfig
.gitignore		.gitignore
CLAUDE.md		CLAUDE.md
DEBUG.md		DEBUG.md
README.md		README.md
cleanup-npx-cache.sh		cleanup-npx-cache.sh
install.sh		install.sh
package-lock.json		package-lock.json
package.json		package.json
pnpm-lock.yaml		pnpm-lock.yaml
pnpm-workspace.yaml		pnpm-workspace.yaml
test-implementation.md		test-implementation.md
tsconfig.json		tsconfig.json
verify-mcp-server.sh		verify-mcp-server.sh
vitest.config.ts		vitest.config.ts

sacahan/SpecPilot

Folders and files

Latest commit

History

Repository files navigation

SpecPilot MCP Server

✨ 核心特色

🚀 快速開始

一鍵安裝

驗證安裝

📋 目錄

📥 完整安裝指南

📋 系統要求

🤖 AI 模型要求

🚀 安裝步驟

1. 下載並執行安裝腳本

2. 驗證安裝

3. 配置 Claude Code (可選)

🎯 安裝功能概述

🤖 支援的 AI 工具

🎯 使用指南

🔄 開發流程概覽

📋 開發階段對照表

🔄 狀態管理系統

Task 狀態流程

Epic 狀態流程

🏷️ 狀態管理參考

Task 狀態定義

Epic 狀態定義

3. Git Worktree 開發流程

4. 依賴關係管理

🤖 next-action 建議邏輯

專案生命週期智能建議

🚀 階段 0: 空專案初始化

📋 階段 1: 需求分析完成

🏗️ 階段 2: 技術架構完成

📝 階段 3: 實施規劃完成

💻 階段 4: 開發執行階段

🏁 階段 5: 專案完成階段

Scope 參數說明

🛠️ 核心 MCP 工具 (9 個)

專案管理工具

文件生成工具

分析工具

🤖 AI 整合特色

🎯 快速使用範例

基本開發流程

MCP 工具 JSON 呼叫範例

1. 初始化專案

2. 建立第一份 PRD

3. 從 PRD 分析成技術設計規格TSD

4. 從 TSD 拆解成 Epics

5. 智能拆解 Epic 為 Tasks（含相依性分析）

5. 檢查狀態與並行建議

6. 檢查相依性與可執行任務

📁 專案結構與檔案命名規範

🔧 驗證安裝

📊 驗證腳本修復說明

🧪 完整測試覆蓋

🚨 測試狀態

🏗️ v0.5.1 重構成果

📊 重構統計

🎯 主要改進項目

1. 🧪 測試覆蓋率提升

2. ❌ 統一錯誤處理系統

3. 🔧 依賴注入架構

4. ⚡ 非同步操作優化

📋 架構改善效果

🎉 重構價值

統一測試指令

🚀 進階功能

空間優化安裝

Task YAML 結構範例

🔄 Task Status System

🐛 故障排除

常見問題快速修復

🛠️ 開發指令

🤝 取得協助

🔄 GitHub 整合與自動化工作流

GitHub Integration 腳本系統

Packages