gsi-protocol-installer 1.0.8

Installer for GSI-Protocol workflow commands (Claude Code & Codex)

GSI-Protocol（中文）

Gherkin → 架構 → 實作

一個語言無關的工作流程，使用 AI 代理和 BDD 原則建立可驗證的軟體功能。

🎯 什麼是 GSI-Protocol?

GSI-Protocol 是一個 AI 驅動的工作流程插件，實作了規格驅動開發（SDD）。它透過嚴格的四階段流程，將模糊的需求轉化為經過驗證、可用於生產環境的程式碼。

支援平台：

• ✅ Claude Code
• ✅ Codex (OpenAI)
• ✅ GitHub Copilot

核心理念

"規格 → 架構 → 實作 → 驗證"

將業務邏輯、技術架構、程式撰寫和品質保證分離到不同階段，以最小化 AI 幻覺並最大化精確度。

主要特性

• 🌍 語言無關：支援 Python、TypeScript、Go、Java、Rust、C# 等等
• 🎯 框架獨立：不綁定任何特定函式庫或框架
• 📝 基於 BDD：使用 Gherkin 撰寫清晰、可測試的規格
• 🏗️ 專案感知：自動掃描並遵循既有專案架構
• ✅ 可驗證：自動根據規格進行驗證
• 🔄 模組化：可獨立執行各階段或完整工作流程

---

📦 快速開始

安裝

選項 1：使用 uvx（最推薦，無需安裝）

uvx --from gsi-protocol-installer gsi-install

選項 2：使用 pipx

pipx run gsi-protocol-installer

選項 3：直接執行 Python

# 下載並執行
wget https://raw.githubusercontent.com/CodeMachine0121/GSI-Protocol/main/gsi_installer.py
python3 gsi_installer.py

# 或使用 curl
curl -O https://raw.githubusercontent.com/CodeMachine0121/GSI-Protocol/main/gsi_installer.py
python3 gsi_installer.py

安裝程式會引導您：

1. 選擇 AI 平台（Claude Code、Codex 或兩者）
2. 選擇安裝位置（全域或當前專案）
3. 自動完成安裝

選項 4：手動全域安裝

Claude Code:

mkdir -p ~/.claude/commands
cd ~/.claude/commands
curl -sSL https://raw.githubusercontent.com/CodeMachine0121/GSI-Protocol/main/.claude/commands/sdd-auto.md -o sdd-auto.md
curl -sSL https://raw.githubusercontent.com/CodeMachine0121/GSI-Protocol/main/.claude/commands/sdd-spec.md -o sdd-spec.md
curl -sSL https://raw.githubusercontent.com/CodeMachine0121/GSI-Protocol/main/.claude/commands/sdd-arch.md -o sdd-arch.md
curl -sSL https://raw.githubusercontent.com/CodeMachine0121/GSI-Protocol/main/.claude/commands/sdd-integration-test.md -o sdd-integration-test.md
curl -sSL https://raw.githubusercontent.com/CodeMachine0121/GSI-Protocol/main/.claude/commands/sdd-impl.md -o sdd-impl.md
curl -sSL https://raw.githubusercontent.com/CodeMachine0121/GSI-Protocol/main/.claude/commands/sdd-verify.md -o sdd-verify.md

Codex (OpenAI):

mkdir -p ~/.codex/prompts
cd ~/.codex/prompts
curl -sSL https://raw.githubusercontent.com/CodeMachine0121/GSI-Protocol/main/.codex/prompts/sdd-auto.md -o sdd-auto.md
curl -sSL https://raw.githubusercontent.com/CodeMachine0121/GSI-Protocol/main/.codex/prompts/sdd-spec.md -o sdd-spec.md
curl -sSL https://raw.githubusercontent.com/CodeMachine0121/GSI-Protocol/main/.codex/prompts/sdd-arch.md -o sdd-arch.md
curl -sSL https://raw.githubusercontent.com/CodeMachine0121/GSI-Protocol/main/.codex/prompts/sdd-integration-test.md -o sdd-integration-test.md
curl -sSL https://raw.githubusercontent.com/CodeMachine0121/GSI-Protocol/main/.codex/prompts/sdd-impl.md -o sdd-impl.md
curl -sSL https://raw.githubusercontent.com/CodeMachine0121/GSI-Protocol/main/.codex/prompts/sdd-verify.md -o sdd-verify.md

GitHub Copilot:

mkdir -p ~/.copilot/commands
cd ~/.copilot/commands
curl -sSL https://raw.githubusercontent.com/CodeMachine0121/GSI-Protocol/main/.copilot/commands/sdd-auto.md -o sdd-auto.md
curl -sSL https://raw.githubusercontent.com/CodeMachine0121/GSI-Protocol/main/.copilot/commands/sdd-spec.md -o sdd-spec.md
curl -sSL https://raw.githubusercontent.com/CodeMachine0121/GSI-Protocol/main/.copilot/commands/sdd-arch.md -o sdd-arch.md
curl -sSL https://raw.githubusercontent.com/CodeMachine0121/GSI-Protocol/main/.copilot/commands/sdd-integration-test.md -o sdd-integration-test.md
curl -sSL https://raw.githubusercontent.com/CodeMachine0121/GSI-Protocol/main/.copilot/commands/sdd-impl.md -o sdd-impl.md
curl -sSL https://raw.githubusercontent.com/CodeMachine0121/GSI-Protocol/main/.copilot/commands/sdd-verify.md -o sdd-verify.md

完成後，可在任何專案中使用 /sdd-auto、/sdd-spec 等全域指令（Claude/Codex）或 @workspace /sdd-auto、@workspace /sdd-spec（Copilot）。

📖 查看 安裝指南 了解詳細說明

第一次使用（2 分鐘）

# 使用 uvx 安裝
uvx gsi-protocol-installer

# 選擇平台和安裝位置後，進入您的專案
cd your-project

# 自動模式 - 生成所有內容
/sdd-auto Create a shopping cart in TypeScript with add, remove, checkout functions
# 或使用 Copilot
@workspace /sdd-auto Create a shopping cart in TypeScript with add, remove, checkout functions

# 手動模式 - 逐步執行
/sdd-spec Create a shopping cart with add, remove, checkout
/sdd-arch features/shopping_cart.feature
/sdd-impl features/shopping_cart.feature
/sdd-verify features/shopping_cart.feature
# 或使用 Copilot
@workspace /sdd-spec Create a shopping cart with add, remove, checkout
@workspace /sdd-arch features/shopping_cart.feature
@workspace /sdd-impl features/shopping_cart.feature
@workspace /sdd-verify features/shopping_cart.feature

---

📚 文件

文件	說明
快速入門指南	5 分鐘教學
安裝指南	詳細安裝說明
Python 安裝器	uvx 安裝方式（推薦）
平台支援	Claude Code vs Codex 比較
指令參考	完整指令文件
語言指南	多語言支援指南
工作流程定義	詳細方法論
貢獻指南	如何貢獻

---

🔄 工作流程概覽

核心四階段（必需）

Phase 1：規格（PM）
    ↓
    Gherkin .feature 檔案
    ↓
Phase 2：架構（架構師）
    ↓
    架構設計文件（繁中 Markdown）
    ↓
Phase 3：實作（工程師）
    ↓
    可運行的程式碼（依專案架構）
    ↓
Phase 4：驗證（QA）
    ↓
    ✅ 驗證結論報告

選用階段：Integration Tests

Phase 2.5：整合測試（選用）
    ↓
    在實作前生成 Integration Tests
    ↓
    測試先行開發（紅燈 → 綠燈）

何時使用 /sdd-integration-test？

• ✅ 團隊實踐 BDD 測試先行
• ✅ 需要完整的整合測試覆蓋
• ✅ 複雜的業務邏輯需要驗證
• ❌ 簡單的 CRUD 功能
• ❌ 原型開發階段
• ❌ 時程緊迫的專案

指令

指令	用途	何時使用	是否必需
/sdd-auto	自動執行全部 4 個階段	快速原型、簡單功能	-
/sdd-spec	生成 Gherkin 規格	定義需求	✅ 必需
/sdd-arch	設計資料模型與介面	審查結構	✅ 必需
/sdd-integration-test	生成 Integration Tests（紅燈）	BDD 測試先行開發	🔷 選用
/sdd-impl	實作邏輯	撰寫程式碼	✅ 必需
/sdd-verify	根據規格驗證	測試實作	✅ 必需

---

💡 範例

輸入

/sdd-auto Implement a VIP discount system in Python where VIP users get 20% off purchases over $100

輸出

階段 1：規格 (features/vip_discount.feature)

Feature: VIP Discount
  Scenario: Apply discount to VIP user
    Given user is VIP
    When user makes a purchase of 1000 USD
    Then final price should be 800 USD

Phase 2：架構 (docs/features/vip_discount/architecture.md)

# VIP 折扣系統 - 架構設計

## 1. 專案上下文

- 程式語言：Python
- 架構模式：Service Layer

## 3. 資料模型

- UserType（列舉）：VIP, NORMAL
- DiscountResult（實體）：final_price, discount

## 4. 服務介面

- calculate_discount(amount, user_type) → DiscountResult

Phase 3：實作 （依 architecture.md 指定位置）

# src/services/discount_service.py
def calculate_discount(amount: float, user_type: UserType) -> DiscountResult:
    if user_type == UserType.VIP and amount >= 100:
        discount = amount * 0.2
        return DiscountResult(amount - discount, discount)
    return DiscountResult(amount, 0)

Phase 4：驗證結論 (docs/features/vip_discount/conclusion.md)

## 3. 摘要

- 架構：2/2 通過
- 情境：2/2 通過
- **狀態：** ✅ 完成

---

🌐 多語言支援

相同的工作流程，不同的語言：

Python

from dataclasses import dataclass
from abc import ABC, abstractmethod

@dataclass
class User:
    id: str
    type: UserType

class IUserService(ABC):
    @abstractmethod
    def authenticate(self, credentials: Credentials) -> User:
        pass

TypeScript

interface User {
  id: string;
  type: UserType;
}

interface IUserService {
  authenticate(credentials: Credentials): User;
}

Go

type User struct {
    ID   string
    Type UserType
}

type UserService interface {
    Authenticate(credentials Credentials) (User, error)
}

更多語言請參閱 語言指南，包含 Rust、Java、C# 等。

---

🎓 使用案例

1. API 開發

/sdd-spec Design a RESTful API for blog posts (CRUD operations)
/sdd-arch features/blog_api.feature
# 獲得清晰的 API 契約和資料結構

2. 功能實作

/sdd-auto Implement user authentication with JWT tokens in TypeScript
# 幾分鐘內獲得可運行、已測試的程式碼

3. 遺留程式碼重構

/sdd-spec The payment module should support credit card, PayPal, and crypto
# 在重構前定義清晰的需求

4. 團隊協作

# PM：定義需求
/sdd-spec User registration with email verification

# 架構師：審查並設計
/sdd-arch features/user_registration.feature

# 工程師：實作
/sdd-impl features/user_registration.feature

# QA：驗證
/sdd-verify features/user_registration.feature

---

📁 專案結構

執行 SDD 工作流程後的輸出：

your-project/
├── features/                    # Phase 1: Gherkin 規格
│   └── {feature}.feature
├── docs/
│   └── features/
│       └── {feature}/
│           ├── architecture.md  # Phase 2: 架構設計（繁中）
│           └── conclusion.md    # Phase 4: 驗證結論
└── src/                         # Phase 3: 實作程式碼
    ├── models/                  # 依專案既有架構
    │   └── {Feature}Model.{ext}
    └── services/
        └── {Feature}Service.{ext}

GSI-Protocol 儲存庫結構：

GSI-Protocol/
├── README.md                    # 本檔案
├── CONTRIBUTING.md              # 貢獻指南
├── LICENSE                      # MIT 授權
├── gsi_installer.py             # Python 安裝器
├── pyproject.toml               # Python 專案配置
├── .claude/
│   └── commands/                # Claude Code slash 指令
│       ├── sdd-auto.md         # 自動工作流程
│       ├── sdd-spec.md         # Phase 1
│       ├── sdd-arch.md         # Phase 2
│       ├── sdd-integration-test.md  # BDD Integration Tests
│       ├── sdd-impl.md         # Phase 3
│       └── sdd-verify.md       # Phase 4
├── .codex/
│   └── prompts/                 # Codex (OpenAI) prompts
│       ├── sdd-auto.md         # 自動工作流程
│       ├── sdd-spec.md         # Phase 1
│       ├── sdd-arch.md         # Phase 2
│       ├── sdd-integration-test.md  # BDD Integration Tests
│       ├── sdd-impl.md         # Phase 3
│       └── sdd-verify.md       # Phase 4
├── .copilot/
│   └── commands/                # GitHub Copilot 指令
│       ├── sdd-auto.md         # 自動工作流程
│       ├── sdd-spec.md         # Phase 1
│       ├── sdd-arch.md         # Phase 2
│       ├── sdd-integration-test.md  # BDD Integration Tests
│       ├── sdd-impl.md         # Phase 3
│       └── sdd-verify.md       # Phase 4
├── docs/                        # 文件
│   ├── QUICKSTART.md           # 快速入門指南
│   ├── INSTALL.md              # 安裝指南
│   ├── PYTHON_INSTALLER.md     # Python 安裝器說明
│   ├── PLATFORM_SUPPORT.md     # 平台支援說明
│   ├── COMMANDS.md             # 指令參考
│   ├── LANGUAGE_GUIDE.md       # 語言支援
│   └── expected_workflow.md    # 工作流程細節
└── prompts/                     # 代理提示（參考）
    ├── pm_agent.md
    ├── architect_agent.md
    ├── engineer_agent.md
    └── qa_agent.md

---

🚀 優勢

對開發者

• ✅ 更快開發：自動生成樣板程式碼和結構
• ✅ 更高品質：系統化方法減少 bug
• ✅ 清晰需求：Gherkin 規格消除歧義

對團隊

• ✅ 共同語言：所有人都能理解的 BDD 規格
• ✅ 更好溝通：PM、架構師、工程師、QA 各有明確階段
• ✅ 可維護程式碼：每一行都可追溯到需求

對專案

• ✅ 語言彈性：切換語言不需改變方法論
• ✅ 框架無關：使用任何函式庫或框架
• ✅ 可擴展：適用於簡單功能到複雜系統

---

🔧 需求

• AI 平台（擇一或多個）：
  • Claude Code CLI，或
  • Codex (OpenAI)，或
  • GitHub Copilot
• 安裝工具：
  • Python 3.10+
  • uvx/pipx（推薦）或 pip
• Git
• 目標語言執行環境（Python 3.8+、Node.js 16+、Go 1.19+ 等）

---

📖 了解更多

• 📝 快速入門（5 分鐘）
• 📚 完整文件
• 🌍 語言支援
• 💬 GitHub 討論

---

🤝 貢獻

我們歡迎貢獻！請參閱 CONTRIBUTING.md 了解指南。

貢獻方式

• 🐛 回報 bug
• 💡 建議功能
• 📝 改善文件
• 🌍 新增語言範例
• 🔧 提交 pull request

---

📄 授權

MIT 授權 - 詳見 LICENSE 檔案。

---

🙏 致謝

使用以下工具建置：

• Claude Code - AI 驅動開發
• Codex (OpenAI) - AI 程式碼生成
• GitHub Copilot - AI 程式輔助
• Gherkin - BDD 規格語言
• 靈感來自測試驅動開發和行為驅動開發原則

---

📞 支援

• 📖 文件
• 💬 GitHub Issues
• 💡 討論

---

⬆ 回到頂端

由開發者打造，為開發者服務 ❤️