Skip to content

Commit 7cbf2ac

Browse files
author
薛華慶, james.hsueh
committed
feat: add readme for script and rename it
1 parent 6f1882d commit 7cbf2ac

File tree

3 files changed

+162
-53
lines changed

3 files changed

+162
-53
lines changed

‎scripts/README.md‎

Lines changed: 48 additions & 44 deletions
Original file line numberDiff line numberDiff line change
@@ -1,88 +1,92 @@
1-
# GSI-Protocol 開發工作流程
1+
# GSI-Protocol Development Workflow
22

3-
## 問題
4-
修改 GSI command 內容時，需要同時維護三個位置：
3+
[中文版本](./README.zh-TW.md) | **English**
4+
5+
## Problem
6+
When modifying GSI command content, you need to maintain three locations:
57
- `.claude/commands/` (Claude Code)
68
- `.codex/prompts/` (Codex)
79
- `.github/prompts/` (GitHub Copilot)
810

9-
## 解決方案
10-
使用單一來源 + 自動同步腳本
11+
## Solution
12+
Single source + automatic sync script
1113

12-
## 目錄結構
14+
## Directory Structure
1315
```
1416
scripts/
15-
├── templates/ # 📝 唯一需要維護的模板來源
17+
├── templates/ # 📝 Single source of truth for templates
1618
│ ├── sdd-spec.md
1719
│ ├── sdd-arch.md
1820
│ ├── sdd-impl.md
1921
│ ├── sdd-verify.md
2022
│ ├── sdd-integration-test.md
2123
│ └── sdd-auto.md
22-
├── sync_commands.py # 🔄 同步腳本
23-
└── README.md # 📖 本文件
24+
├── dev_sync.py # 🔧 Local development testing tool (for developers only)
25+
└── README.md # 📖 This file
2426
```
2527

26-
## 開發工作流程
28+
## Development Workflow
2729

28-
### 1. 修改模板
29-
只需要修改 `scripts/templates/` 中的檔案，使用通用佔位符：
30+
### 1. Edit Templates
31+
Only need to modify files in `scripts/templates/`, using generic placeholders:
3032

3133
```markdown
32-
## 使用者需求
34+
## User Requirements
3335

3436
__PROMPT__
3537

36-
## 下一步
37-
- 使用指令：`__CMD_PREFIX__sdd-arch features/xxx.feature`
38+
## Next Steps
39+
- Use command: `__CMD_PREFIX__sdd-arch features/xxx.feature`
3840
```
3941

40-
**佔位符說明：**
41-
- `__PROMPT__` - 用戶輸入的參數
42-
- `__CMD_PREFIX__` - 命令前綴（會根據平台自動轉換）
42+
**Placeholder Explanation:**
43+
- `__PROMPT__` - User input parameter
44+
- `__CMD_PREFIX__` - Command prefix (automatically converted per platform)
4345

44-
### 2. 同步到三個平台
45-
運行同步腳本：
46+
### 2. Sync to Three Platforms
47+
Run the development sync tool:
4648

4749
```bash
48-
python3 scripts/sync_commands.py
50+
python3 scripts/dev_sync.py
4951
```
5052

51-
這會自動轉換佔位符並同步：
52-
- 轉換並同步到 `.claude/commands/`：`__PROMPT__` → `{{prompt}}`，`__CMD_PREFIX__` → `/`
53-
- 轉換並同步到 `.codex/prompts/`：`__PROMPT__` → `$1`，`__CMD_PREFIX__` → `/`
54-
- 轉換並同步到 `.github/prompts/`：`__PROMPT__` → `{{ARG}}`，`__CMD_PREFIX__` → `@workspace /`
53+
⚠️ **Note**: This tool is for development testing only, end users don't need it
54+
55+
This will automatically convert placeholders and sync:
56+
- Convert and sync to `.claude/commands/`: `__PROMPT__` → `{{prompt}}`, `__CMD_PREFIX__` → `/`
57+
- Convert and sync to `.codex/prompts/`: `__PROMPT__` → `$1`, `__CMD_PREFIX__` → `/`
58+
- Convert and sync to `.github/prompts/`: `__PROMPT__` → `{{ARG}}`, `__CMD_PREFIX__` → `@workspace /`
5559

56-
### 3. 測試
57-
在本地測試各平台的命令是否正常運作
60+
### 3. Test
61+
Test commands on each platform locally
5862

59-
### 4. 提交
60-
提交所有變更到 Git
63+
### 4. Commit
64+
Commit all changes to Git
6165

62-
## 用戶安裝流程
66+
## User Installation Flow
6367

64-
當用戶執行：
68+
When users run:
6569
```bash
6670
uvx --from gsi-protocol-installer gsi-install
6771
```
6872

69-
`gsi_installer.py` 會：
70-
1. 從 GitHub 下載 repo
71-
2. 讀取 `scripts/templates/` 中的模板
72-
3. 根據用戶選擇的平台自動轉換並安裝
73+
`gsi_installer.py` will:
74+
1. Download the repo from GitHub
75+
2. Read templates from `scripts/templates/`
76+
3. Automatically convert and install based on user's platform choice
7377

74-
## 佔位符轉換對照表
78+
## Placeholder Conversion Table
7579

76-
| 平台 | `__PROMPT__` 轉換為 | `__CMD_PREFIX__` 轉換為 | 檔案副檔名 |
77-
|------|-------------------|----------------------|-----------|
78-
| 模板 | `__PROMPT__` | `__CMD_PREFIX__` | `.md` |
80+
| Platform | `__PROMPT__` converts to | `__CMD_PREFIX__` converts to | File Extension |
81+
|----------|-------------------------|------------------------------|----------------|
82+
| Template | `__PROMPT__` | `__CMD_PREFIX__` | `.md` |
7983
| Claude Code | `{{prompt}}` | `/` | `.md` |
8084
| Codex | `$1` | `/` | `.md` |
8185
| GitHub Copilot | `{{ARG}}` | `@workspace /` | `.prompt.md` |
8286

83-
## 優點
87+
## Benefits
8488

85-
✅ 只需維護一個地方 (`scripts/templates/`)
86-
✅ 自動處理平台差異
87-
✅ 降低維護成本
88-
✅ 減少人為錯誤
89+
✅ Only maintain one location (`scripts/templates/`)
90+
✅ Automatically handle platform differences
91+
✅ Reduce maintenance cost
92+
✅ Minimize human errors

‎scripts/README.zh-TW.md‎

Lines changed: 92 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,92 @@
1+
# GSI-Protocol 開發工作流程
2+
3+
**中文版本** | [English](./README.md)
4+
5+
## 問題
6+
修改 GSI command 內容時，需要同時維護三個位置：
7+
- `.claude/commands/` (Claude Code)
8+
- `.codex/prompts/` (Codex)
9+
- `.github/prompts/` (GitHub Copilot)
10+
11+
## 解決方案
12+
使用單一來源 + 自動同步腳本
13+
14+
## 目錄結構
15+
```
16+
scripts/
17+
├── templates/ # 📝 唯一需要維護的模板來源
18+
│ ├── sdd-spec.md
19+
│ ├── sdd-arch.md
20+
│ ├── sdd-impl.md
21+
│ ├── sdd-verify.md
22+
│ ├── sdd-integration-test.md
23+
│ └── sdd-auto.md
24+
├── dev_sync.py # 🔧 本地開發測試工具（開發者專用）
25+
└── README.md # 📖 本文件
26+
```
27+
28+
## 開發工作流程
29+
30+
### 1. 修改模板
31+
只需要修改 `scripts/templates/` 中的檔案，使用通用佔位符：
32+
33+
```markdown
34+
## 使用者需求
35+
36+
__PROMPT__
37+
38+
## 下一步
39+
- 使用指令：`__CMD_PREFIX__sdd-arch features/xxx.feature`
40+
```
41+
42+
**佔位符說明：**
43+
- `__PROMPT__` - 用戶輸入的參數
44+
- `__CMD_PREFIX__` - 命令前綴（會根據平台自動轉換）
45+
46+
### 2. 同步到三個平台
47+
運行開發同步工具：
48+
49+
```bash
50+
python3 scripts/dev_sync.py
51+
```
52+
53+
⚠️ **注意**：此工具僅供開發測試，終端用戶不需要使用
54+
55+
這會自動轉換佔位符並同步：
56+
- 轉換並同步到 `.claude/commands/`：`__PROMPT__` → `{{prompt}}`，`__CMD_PREFIX__` → `/`
57+
- 轉換並同步到 `.codex/prompts/`：`__PROMPT__` → `$1`，`__CMD_PREFIX__` → `/`
58+
- 轉換並同步到 `.github/prompts/`：`__PROMPT__` → `{{ARG}}`，`__CMD_PREFIX__` → `@workspace /`
59+
60+
### 3. 測試
61+
在本地測試各平台的命令是否正常運作
62+
63+
### 4. 提交
64+
提交所有變更到 Git
65+
66+
## 用戶安裝流程
67+
68+
當用戶執行：
69+
```bash
70+
uvx --from gsi-protocol-installer gsi-install
71+
```
72+
73+
`gsi_installer.py` 會：
74+
1. 從 GitHub 下載 repo
75+
2. 讀取 `scripts/templates/` 中的模板
76+
3. 根據用戶選擇的平台自動轉換並安裝
77+
78+
## 佔位符轉換對照表
79+
80+
| 平台 | `__PROMPT__` 轉換為 | `__CMD_PREFIX__` 轉換為 | 檔案副檔名 |
81+
|------|-------------------|----------------------|-----------|
82+
| 模板 | `__PROMPT__` | `__CMD_PREFIX__` | `.md` |
83+
| Claude Code | `{{prompt}}` | `/` | `.md` |
84+
| Codex | `$1` | `/` | `.md` |
85+
| GitHub Copilot | `{{ARG}}` | `@workspace /` | `.prompt.md` |
86+
87+
## 優點
88+
89+
✅ 只需維護一個地方 (`scripts/templates/`)
90+
✅ 自動處理平台差異
91+
✅ 降低維護成本
92+
✅ 減少人為錯誤

scripts/sync_commands.py renamed to scripts/dev_sync.py

Lines changed: 22 additions & 9 deletions
Original file line numberDiff line numberDiff line change
@@ -1,7 +1,17 @@
11
#!/usr/bin/env python3
22
"""
3-
同步腳本 - 將 scripts/templates/ 中的模板同步到三個目標位置
4-
用法：python scripts/sync_commands.py
3+
🔧 開發測試工具 - 本地同步腳本
4+
5+
⚠️ 此腳本僅供 repo 維護者在本地開發測試使用
6+
⚠️ 終端用戶不需要使用此腳本，請使用官方安裝器
7+
8+
功能：將 scripts/templates/ 中的模板同步到三個目標位置
9+
用法：python3 scripts/dev_sync.py
10+
11+
使用場景：
12+
1. 修改模板後快速預覽轉換結果
13+
2. 本地測試各平台命令是否正常
14+
3. 提交前驗證佔位符轉換正確性
515
"""
616

717
import os
@@ -83,6 +93,8 @@ def sync_commands():
8393
}
8494
}
8595

96+
print("🔧 開發模式：本地同步工具")
97+
print("⚠️ 此工具僅供開發測試使用\n")
8698
print("🔄 開始同步命令模板...\n")
8799

88100
# 處理每個目標
@@ -121,13 +133,14 @@ def sync_commands():
121133

122134
print(f"✅ {name}: 已同步 {count} 個文件到 {target_dir}")
123135

124-
print("\n✨ 同步完成！")
125-
print("\n💡 提示：")
126-
print(" - 模板來源: scripts/templates/")
127-
print(" - 修改模板後運行此腳本即可同步到三個位置")
128-
print(" - Claude Code: .claude/commands/")
129-
print(" - Codex: .codex/prompts/")
130-
print(" - GitHub Copilot: .github/prompts/")
136+
print("\n✨ 本地同步完成！")
137+
print("\n💡 開發者提示：")
138+
print(" - 📝 模板來源: scripts/templates/")
139+
print(" - 🔄 修改模板後運行此腳本即可同步到三個位置")
140+
print(" - 🤖 Claude Code: .claude/commands/")
141+
print(" - 🔷 Codex: .codex/prompts/")
142+
print(" - 🐙 GitHub Copilot: .github/prompts/")
143+
print("\n⚠️ 注意：此腳本僅供本地開發測試，終端用戶請使用官方安裝器")
131144

132145

133146
if __name__ == "__main__":

0 commit comments

Comments
 (0)