CLI tool to sync Kiro documentation files from remote Git repositories
npm install kiro-doc-sync一個跨平台的 CLI 工具,用於將遠端 Git 倉庫中的 Kiro 文件同步到本地專案的 .kiro/steering/ 目錄。
- ✓ 跨平台支援(Windows、macOS、Linux)
- ✓ 稀疏檢出(Sparse Checkout)以提高同步效率
- ✓ 基於模式的文件選擇
- ✓ 互動模式用於文件衝突解決
- ✓ 可配置的文件覆蓋行為
- ✓ 自動建立目錄
- ✓ 完整的錯誤處理
- ✓ 臨時文件自動清理
``bash`
npm install
npm run build
1. 在專案根目錄建立 kiro-doc-sync.cfg.json 配置文件:
`json`
{
"general": {
"files": {
"sync_override": true
}
},
"docs": [
{
"git": "https://github.com/user/repo.git",
"steering": [
"api/*.global.md",
"php/di.md"
]
}
]
}
2. 執行同步:
`bash`
npm start
`bash`
kiro-doc-sync
根據當前目錄中的預設 kiro-doc-sync.cfg.json 同步文件。
`bash`
kiro-doc-sync [options]
| 選項 | 簡寫 | 說明 |
|------|------|------|
| --config | -c | 配置文件路徑(預設:kiro-doc-sync.cfg.json) |--project
| | -p | 專案根目錄(預設:當前目錄) |--interactive
| | -i | 當文件已存在時詢問確認 |--help
| | -h | 顯示幫助信息 |--version
| | -v | 顯示版本 |
`bash使用預設配置
kiro-doc-sync
配置
$3
在專案根目錄建立
kiro-doc-sync.cfg.json:`json
{
"general": {
"files": {
"sync_override": boolean
}
},
"docs": [
{
"git": "string (Git 倉庫 URL)",
"steering": [
"string (相對於倉庫根目錄的文件模式)"
]
}
]
}
`$3
####
general.files.sync_override- 型別:
boolean
- 預設值: true
- 說明: 控制文件覆蓋行為
- true: 總是覆蓋已存在的文件
- false: 跳過已存在的文件(除非使用 --interactive 模式)####
docs[].git- 型別:
string
- 必需: 是
- 說明: 要同步的 Git 倉庫 URL####
docs[].steering- 型別:
string[]
- 必需: 是
- 說明: 要同步的文件模式陣列(相對於倉庫根目錄)
- 支援三種模式:
- 精確檔案: "php/di.md" - 同步單個檔案
- Glob 模式: "java/springboot/steering/*.global.md" - 同步所有匹配的檔案
- 目錄: "java/springboot/steering/" - 遞迴同步目錄中的所有檔案####
docs[].branch- 型別:
string
- 必需: 否
- 說明: 要同步的 Git 分支(預設:預設分支)####
docs[].tag- 型別:
string
- 必需: 否
- 說明: 要同步的 Git 標籤(優先於分支)$3
簡單的單一倉庫配置:
`json
{
"general": {
"files": {
"sync_override": true
}
},
"docs": [
{
"git": "https://github.com/myorg/docs.git",
"steering": [
"api/reference.md",
"guides/*.md",
"patterns/"
]
}
]
}
`多個倉庫配置:
`json
{
"general": {
"files": {
"sync_override": false
}
},
"docs": [
{
"git": "https://github.com/myorg/api-docs.git",
"steering": ["api/*.md"],
"branch": "develop"
},
{
"git": "https://github.com/myorg/guides.git",
"steering": [
"php/di.md",
"patterns/*.md",
"standards/"
],
"tag": "v1.0.0"
}
]
}
`工作原理
1. 解析配置: 讀取並驗證
kiro-doc-sync.cfg.json 設定
2. 建立目錄: 如果不存在則建立 .kiro/steering/ 目錄
3. 稀疏檢出: 對於每個 Git 倉庫:
- 使用 --depth 1 進行淺層克隆
- 使用 Git 稀疏檢出只下載指定的文件
- 將文件複製到 .kiro/steering/
4. 處理衝突:
- 若 sync_override: true,覆蓋已存在的文件
- 若 sync_override: false:
- 非互動模式:跳過已存在的文件
- 互動模式(-i):逐個詢問使用者
5. 清理: 刪除臨時克隆的倉庫輸出範例
工具在執行過程中提供清晰的反饋:
`
Project root: /path/to/project
Config file: kiro-doc-sync.cfg.json
Found 2 doc source(s)Loading configuration...
Cloning https://github.com/user/repo.git with sparse-checkout...
✓ Synced: api/reference.md
⊘ Skipped (exists): guides/intro.md
==================================================
Sync completed. 1 files synced, 1 errors
Synced files:
• api/reference.md
Errors:
• File not found in repo: docs/missing.md
==================================================
`系統需求
- Node.js 14+
- Git 已安裝且在 PATH 中可用
- 對指定 Git 倉庫的讀取權限
- HTTPS:使用者名稱/密碼或個人存取令牌
- SSH:SSH 金鑰已配置且 SSH agent 正在運行
$3
如果使用 SSH URLs(例如
git@github.com:user/repo.git):macOS/Linux:
`bash
生成 SSH 金鑰(如果不存在)
ssh-keygen -t ed25519 -C "your-email@example.com"將金鑰添加到 SSH agent
ssh-add ~/.ssh/id_ed25519將公鑰添加到 GitHub/GitLab
cat ~/.ssh/id_ed25519.pub
`Windows:
`bash
生成 SSH 金鑰
ssh-keygen -t ed25519 -C "your-email@example.com"啟動 SSH agent
Get-Service ssh-agent | Set-Service -StartupType Automatic
Start-Service ssh-agent將金鑰添加到 SSH agent
ssh-add $env:USERPROFILE\.ssh\id_ed25519將公鑰添加到 GitHub/GitLab
type $env:USERPROFILE\.ssh\id_ed25519.pub
`開發
`bash
安裝依賴
npm install編譯 TypeScript
npm run build開發模式執行
npm run dev執行編譯後的版本
npm start
`故障排除
$3
確保 Git 已安裝且在系統 PATH 中可用。
$3
檢查是否有讀取指定 Git 倉庫的權限。對於私有倉庫,確保 Git 認證已正確配置。
對於 SSH 倉庫,驗證:
- SSH 金鑰已生成並添加到 SSH agent
- 公鑰已添加到你的 Git 託管服務(GitHub、GitLab 等)
- SSH agent 正在運行
$3
驗證
steering` 陣列中的文件模式是否與倉庫中的實際文件路徑相符(相對於倉庫根目錄)。確保對專案目錄有寫入權限。
MIT