kenaz 0.0.0-stage → 0.3.2

package/core/.system/cli-tools/README.md

@@ -0,0 +1,724 @@
+# CLI Tools - Development Scripts Reference
+
+本文檔涵蓋所有位於 `dev/scripts/` 的 CLI 工具，包含初始化、排程、維護三大類，並提供 PowerShell 與 Bash 雙平台對照表。
+
+---
+
+## 目錄
+
+- [工具分類](#工具分類)
+- [初始化類工具](#初始化類工具)
+  - [INIT_PROJECT](#init_project)
+  - [INIT_GIT](#init_git)
+  - [SETUP_RAG](#setup_rag)
+  - [SETUP_MCP](#setup_mcp)
+  - [SETUP_GIT_HOOKS](#setup_git_hooks)
+- [排程類工具](#排程類工具)
+  - [START_DEV_AGENT](#start_dev_agent)
+  - [START_MULTI_AGENT](#start_multi_agent)
+  - [RUN_ONCE](#run_once)
+- [維護類工具](#維護類工具)
+  - [CLEAN_TASK_QUEUE](#clean_task_queue)
+  - [ARCHIVE_TASKS](#archive_tasks)
+  - [SYNC_TASKS](#sync_tasks)
+- [參數對照表](#參數對照表)
+- [平台兼容性](#平台兼容性)
+
+---
+
+## 工具分類
+
+| 類別 | 工具 | 用途 |
+|------|------|------|
+| **初始化** | INIT_PROJECT | 初始化新專案（清理 Pipeline、重置狀態） |
+| | INIT_GIT | 初始化 Git 倉庫（.gitignore、.gitattributes、aliases） |
+| | SETUP_RAG | 設置 RAG 引擎（安裝 kenaz-cortex、配置 Git hooks） |
+| | SETUP_MCP | 設置 MCP Server（讓 Claude Code 自動使用 RAG） |
+| | SETUP_GIT_HOOKS | 配置 Git hooks（RAG 自動索引） |
+| **排程** | START_DEV_AGENT | 單 Agent 開發（自我增強迭代模式） |
+| | START_MULTI_AGENT | 多 Agent 並行開發（路徑鎖定防衝突） |
+| | RUN_ONCE | 單次執行 /dev（不含自我增強循環） |
+| **維護** | CLEAN_TASK_QUEUE | 清理 TASK_QUEUE.json 中的已完成任務 |
+| | ARCHIVE_TASKS | 封存已完成任務到 .memory/ |
+| | SYNC_TASKS | 同步 markdown 任務文件到 TASK_QUEUE.json |
+
+---
+
+## 初始化類工具
+
+### INIT_PROJECT
+
+**用途**：初始化新專案，清理舊狀態並重置 Pipeline。
+
+#### 基本使用
+
+```powershell
+# Windows（批處理腳本）
+.\dev\scripts\INIT_PROJECT.bat
+
+# PowerShell 直接調用
+.\dev\scripts\init_project.ps1
+```
+
+#### PowerShell 參數
+
+| 參數 | 類型 | 預設值 | 說明 |
+|------|------|--------|------|
+| `-SkipRAG` | switch | false | 跳過 RAG 環境設置 |
+| `-SkipCleanup` | switch | false | 跳過清理舊任務 |
+| `-AutoStart` | switch | false | 自動啟動 /產品 流程 |
+| `-Quiet` | switch | false | 靜默模式（無互動確認） |
+| `-WorkingDirectory` | string | - | 指定工作目錄 |
+| `-nopause` | switch | false | 跳過暫停（從 Tauri 調用時使用） |
+
+#### 範例
+
+```powershell
+# 跳過 RAG 設置並靜默執行
+.\dev\scripts\init_project.ps1 -SkipRAG -Quiet
+
+# 指定工作目錄
+.\dev\scripts\init_project.ps1 -WorkingDirectory "C:\Projects\MyApp"
+
+# 完整初始化並自動啟動產品流程
+.\dev\scripts\init_project.ps1 -AutoStart
+```
+
+#### 執行內容
+
+1. **清理舊 Pipeline 狀態**
+   - 清空 `dev/pipeline/tasks/`
+   - 備份並清空 `dev/pipeline/completed/`
+   - 刪除 `SELF_ENHANCEMENT_STATUS.json`
+   - 重置 `PROGRESS.md`
+
+2. **建立必要目錄**
+   - `dev/pipeline/tasks/`
+   - `dev/pipeline/completed/`
+   - `dev/pipeline/logs/`
+   - `dev/pipeline/archive/`
+
+3. **初始化狀態文件**
+   - `TASK_QUEUE.json`（空佇列）
+   - `AGENT_STATE.json`（scheduler status: stopped）
+   - `LOCK_STATE.json`（空鎖定）
+   - `PIPELINE_CONFIG.json`（預設配置）
+
+4. **複製 Claude Code 配置**（如果來源可用）
+   - `.claude/`（commands、skills、hooks）
+   - `.agents/`（外部 skills）
+   - `.githooks/`（Git hooks）
+   - `CLAUDE.md`（專案指令）
+
+5. **檢查 PRODUCT_SPEC**
+   - 保留現有 spec 或建立新模板
+
+---
+
+### INIT_GIT
+
+**用途**：初始化 Git 倉庫並配置標準化設定。
+
+#### 基本使用
+
+```powershell
+# Windows（批處理腳本）
+.\dev\scripts\INIT_GIT.bat
+
+# PowerShell 直接調用
+.\dev\scripts\init_git.ps1
+```
+
+#### PowerShell 參數
+
+| 參數 | 類型 | 預設值 | 說明 |
+|------|------|--------|------|
+| `-RemoteUrl` | string | "" | 遠端倉庫 URL |
+| `-SkipInitialCommit` | switch | false | 跳過初始 commit |
+| `-Force` | switch | false | 強制重新初始化（刪除現有 .git） |
+| `-Quiet` | switch | false | 靜默模式 |
+| `-WorkingDirectory` | string | - | 工作目錄 |
+| `-nopause` | switch | false | 跳過暫停 |
+
+#### 範例
+
+```powershell
+# 初始化並設置遠端倉庫
+.\dev\scripts\init_git.ps1 -RemoteUrl "https://github.com/user/repo.git"
+
+# 強制重新初始化
+.\dev\scripts\init_git.ps1 -Force
+
+# 靜默模式，跳過初始 commit
+.\dev\scripts\init_git.ps1 -Quiet -SkipInitialCommit
+```
+
+#### 自動配置內容
+
+1. **`.gitignore`**
+   - Python（`__pycache__/`, `*.pyc`, `venv/`, `.env`）
+   - Node.js（`node_modules/`, `dist/`, `build/`）
+   - IDE（`.vscode/`, `.idea/`, `*.swp`）
+   - Kenaz AI 特定（`.cortex/db/`, `dev/pipeline/logs/`）
+
+2. **`.gitattributes`**
+   - 跨平台換行符標準化
+   - 二進制文件處理
+
+3. **Git aliases**
+   - `st` = status
+   - `co` = checkout
+   - `br` = branch
+   - `ci` = commit
+   - `lg` = log --graph --oneline
+
+---
+
+### SETUP_RAG
+
+**用途**：設置 RAG 引擎（kenaz-cortex），啟用語義代碼搜索。
+
+#### 基本使用
+
+```powershell
+# Windows（批處理腳本）
+.\dev\scripts\SETUP_RAG.bat
+
+# PowerShell 直接調用
+.\dev\scripts\setup_rag.ps1
+```
+
+#### PowerShell 參數
+
+| 參數 | 類型 | 預設值 | 說明 |
+|------|------|--------|------|
+| `-SkipInstall` | switch | false | 跳過 pip install |
+| `-SkipHooks` | switch | false | 跳過 Git hooks 配置 |
+| `-SkipIndex` | switch | false | 跳過初始索引 |
+| `-Reindex` | switch | false | 強制重新索引 |
+| `-Quiet` | switch | false | 靜默模式 |
+| `-WorkingDirectory` | string | - | 工作目錄 |
+| `-nopause` | switch | false | 跳過暫停 |
+
+#### 範例
+
+```powershell
+# 完整設置 RAG 引擎
+.\dev\scripts\setup_rag.ps1
+
+# 只安裝套件，跳過索引
+.\dev\scripts\setup_rag.ps1 -SkipIndex
+
+# 強制重新索引
+.\dev\scripts\setup_rag.ps1 -Reindex
+
+# 靜默模式完整設置
+.\dev\scripts\setup_rag.ps1 -Quiet
+```
+
+#### 執行內容
+
+1. **檢查 Python 環境**（Python 3.10+）
+2. **安裝 kenaz-cortex**（`pip install -e kenaz-cortex/`）
+3. **配置 Git Hooks**（`git config core.hooksPath .githooks`）
+4. **初始化向量索引**（索引代碼庫到 ChromaDB）
+
+---
+
+### SETUP_MCP
+
+**用途**：設置 MCP Server，讓 Claude Code 自動使用 RAG。
+
+#### 基本使用
+
+```powershell
+# Windows（批處理腳本）
+.\dev\scripts\SETUP_MCP.bat
+
+# PowerShell 直接調用
+.\dev\scripts\setup_mcp.ps1
+```
+
+#### PowerShell 參數
+
+| 參數 | 類型 | 預設值 | 說明 |
+|------|------|--------|------|
+| `-WorkingDirectory` | string | - | 工作目錄 |
+| `-nopause` | switch | false | 跳過暫停 |
+
+#### MCP 工具功能
+
+設置後，Claude Code 會自動使用以下 MCP 工具：
+
+| 工具 | 用途 |
+|------|------|
+| `cortex_search` | 語義代碼搜索 |
+| `cortex_context` | 專案結構 Context（自動切換全量/RAG） |
+| `cortex_file_chunks` | 文件切片查詢 |
+| `cortex_status` | RAG 引擎狀態 |
+
+#### 自動切換策略
+
+- **小型專案**（<40k tokens, <20 files）→ 全量 Context
+- **大型專案**（>40k tokens 或 >20 files）→ RAG 模式
+
+---
+
+### SETUP_GIT_HOOKS
+
+**用途**：配置 Git hooks，實現 RAG 自動索引（post-commit 時更新向量資料庫）。
+
+#### 基本使用
+
+```powershell
+# Windows（批處理腳本）
+.\dev\scripts\SETUP_GIT_HOOKS.bat
+
+# PowerShell 直接調用
+.\dev\scripts\setup_git_hooks.ps1
+```
+
+#### 執行內容
+
+- 設置 `git config core.hooksPath .githooks`
+- 啟用 `.githooks/post-commit`（自動更新 RAG 索引）
+
+---
+
+## 排程類工具
+
+### START_DEV_AGENT
+
+**用途**：啟動單 Agent 開發排程器（自我增強迭代模式）。
+
+#### 基本使用
+
+```powershell
+# Windows（批處理腳本）
+.\dev\scripts\START_DEV_AGENT.bat
+
+# PowerShell 直接調用
+.\dev\scripts\dev_agent_scheduler.ps1
+```
+
+#### PowerShell 參數
+
+| 參數 | 類型 | 預設值 | 說明 |
+|------|------|--------|------|
+| `-InitialDelaySeconds` | int | 30 | 首次執行前等待秒數 |
+| `-IntervalMinutes` | int | 20 | 任務間隔分鐘數 |
+| `-EarlyFinishDelaySeconds` | int | 30 | 提早完成時等待秒數 |
+| `-TotalRuns` | int | 16 | 最大開發執行次數 |
+| `-MaxEnhancementCycles` | int | 3 | 最大自我增強循環次數 |
+| `-WorkingDirectory` | string | - | 工作目錄 |
+| `-nopause` | switch | false | 跳過暫停 |
+
+#### 範例
+
+```powershell
+# 自訂配置：首次等待 60 秒，間隔 30 分鐘，最多 20 次
+.\dev\scripts\dev_agent_scheduler.ps1 `
+  -InitialDelaySeconds 60 `
+  -IntervalMinutes 30 `
+  -TotalRuns 20
+
+# 最多執行 5 輪自我增強循環
+.\dev\scripts\dev_agent_scheduler.ps1 -MaxEnhancementCycles 5
+
+# 快速測試模式（間隔 5 分鐘）
+.\dev\scripts\dev_agent_scheduler.ps1 `
+  -InitialDelaySeconds 10 `
+  -IntervalMinutes 5 `
+  -TotalRuns 3
+```
+
+#### 自我增強流程
+
+```
+[執行 /dev 開發任務] → [任務完成?]
+                           ↓ 是
+                    [/product-review 分析 PRODUCT_SPEC]
+                           ↓
+                    ┌──────┴──────┐
+             [需要新功能/測試]  [專案已完成]
+                    ↓              ↓
+             [建立任務,繼續]   [結束排程]
+```
+
+#### 關鍵限制
+
+- **緊貼 PRODUCT_SPEC**：不可天馬行空開發，只能實現規格中定義的功能
+- **最大循環次數**：預設 3 次，防止無限迭代
+- **狀態文件**：`dev/pipeline/SELF_ENHANCEMENT_STATUS.json`
+
+---
+
+### START_MULTI_AGENT
+
+**用途**：啟動多 Agent 並行開發（路徑鎖定防衝突）。
+
+#### 基本使用
+
+```powershell
+# Windows（批處理腳本）
+.\dev\scripts\START_MULTI_AGENT.bat
+
+# PowerShell 直接調用
+.\dev\scripts\multi_agent_scheduler.ps1
+```
+
+#### PowerShell 參數
+
+| 參數 | 類型 | 預設值 | 說明 |
+|------|------|--------|------|
+| `-MaxAgents` | int | 3 | 最大並行 Agent 數量 |
+| `-PollIntervalSeconds` | int | 30 | 輪詢間隔 |
+| `-TaskTimeoutMinutes` | int | 60 | 單任務超時 |
+| `-DryRun` | switch | false | 模擬運行（不實際啟動） |
+| `-SingleRun` | switch | false | 單次運行（不循環） |
+| `-WorkingDirectory` | string | - | 工作目錄 |
+| `-nopause` | switch | false | 跳過暫停 |
+| `-Standalone` | switch | false | 獨立模式（忽略 Dashboard heartbeat） |
+
+#### 範例
+
+```powershell
+# 最多 5 個並行 Agent，每 60 秒輪詢一次
+.\dev\scripts\multi_agent_scheduler.ps1 `
+  -MaxAgents 5 `
+  -PollIntervalSeconds 60
+
+# 模擬運行（檢查任務分配邏輯）
+.\dev\scripts\multi_agent_scheduler.ps1 -DryRun
+
+# 單次運行，不循環
+.\dev\scripts\multi_agent_scheduler.ps1 -SingleRun
+
+# 獨立模式（不需要 Dashboard）
+.\dev\scripts\multi_agent_scheduler.ps1 -Standalone
+```
+
+#### 多 Agent 運作原理
+
+```
+[Task Queue] → [Scheduler 分配無衝突任務]
+                    ↓
+    ┌───────────────┼───────────────┐
+    ↓               ↓               ↓
+[Agent 1]       [Agent 2]       [Agent 3]
+ Branch A        Branch B        Branch C
+ Scope: src/api  Scope: src/ui   Scope: tests/
+    ↓               ↓               ↓
+[路徑鎖定防止衝突，完成後自動釋放]
+```
+
+#### 路徑衝突檢測規則
+
+- 路徑包含或被包含 = 衝突
+- 範例：`dev/pipeline/` 與 `dev/pipeline/tasks/` 衝突
+- 無衝突任務可並行執行
+
+---
+
+### RUN_ONCE
+
+**用途**：單次執行 /dev（不含自我增強循環）。
+
+#### 基本使用
+
+```powershell
+# Windows（批處理腳本）
+.\dev\scripts\RUN_ONCE.bat
+```
+
+#### 適用場景
+
+- 測試 /dev 指令
+- 手動觸發單次開發循環
+- 不需要自我增強的快速開發
+
+---
+
+## 維護類工具
+
+### CLEAN_TASK_QUEUE
+
+**用途**：清理 `TASK_QUEUE.json` 中的已完成任務。
+
+#### 基本使用
+
+```powershell
+# Windows（批處理腳本）
+.\dev\scripts\CLEAN_TASK_QUEUE.bat
+
+# PowerShell 直接調用
+.\dev\scripts\clean_task_queue.ps1
+```
+
+#### PowerShell 參數
+
+| 參數 | 類型 | 預設值 | 說明 |
+|------|------|--------|------|
+| `-DryRun` | switch | false | 模擬運行（不修改文件） |
+| `-Verbose` | switch | false | 顯示詳細資訊 |
+| `-SkipBackup` | switch | false | 跳過備份 |
+
+#### 範例
+
+```powershell
+# 模擬運行，查看將清理哪些任務
+.\dev\scripts\clean_task_queue.ps1 -DryRun
+
+# 清理並顯示詳細過程
+.\dev\scripts\clean_task_queue.ps1 -Verbose
+
+# 不備份直接清理（謹慎使用）
+.\dev\scripts\clean_task_queue.ps1 -SkipBackup
+```
+
+#### 執行內容
+
+1. 備份 `TASK_QUEUE.json` 到 `dev/pipeline/backups/`
+2. 移除 status = "completed" 的任務
+3. 驗證 JSON 格式
+
+---
+
+### ARCHIVE_TASKS
+
+**用途**：封存已完成任務到 `.memory/COMPLETED_TASKS.json`。
+
+#### 基本使用
+
+```powershell
+# Windows（批處理腳本）
+.\dev\scripts\ARCHIVE_TASKS.bat
+
+# PowerShell 直接調用
+.\dev\scripts\archive_completed_tasks.ps1
+```
+
+#### PowerShell 參數
+
+| 參數 | 類型 | 預設值 | 說明 |
+|------|------|--------|------|
+| `-DryRun` | switch | false | 模擬運行（不實際封存） |
+| `-Quiet` | switch | false | 靜默模式（不顯示任務列表） |
+
+#### 範例
+
+```powershell
+# 模擬運行，查看將封存哪些任務
+.\dev\scripts\archive_completed_tasks.ps1 -DryRun
+
+# 靜默封存
+.\dev\scripts\archive_completed_tasks.ps1 -Quiet
+```
+
+#### 執行內容
+
+1. 讀取 `TASK_QUEUE.json` 中的 completed 任務
+2. 追加到 `.memory/COMPLETED_TASKS.json`
+3. 從 `TASK_QUEUE.json` 移除這些任務
+
+---
+
+### SYNC_TASKS
+
+**用途**：同步 markdown 任務文件到 `TASK_QUEUE.json`。
+
+#### 基本使用
+
+```powershell
+# Windows（批處理腳本）
+.\dev\scripts\SYNC_TASKS.bat
+
+# PowerShell 直接調用
+.\dev\scripts\sync_task_queue.ps1
+```
+
+#### PowerShell 參數
+
+| 參數 | 類型 | 預設值 | 說明 |
+|------|------|--------|------|
+| `-WorkingDirectory` | string | - | 工作目錄 |
+| `-nopause` | switch | false | 跳過暫停 |
+
+#### 執行內容
+
+- 掃描 `dev/pipeline/tasks/` 的 markdown 文件
+- 解析任務 metadata（frontmatter）
+- 更新 `TASK_QUEUE.json`
+
+---
+
+## 參數對照表
+
+### 通用參數（所有腳本都支援）
+
+| 參數 | 說明 | 腳本覆蓋範圍 |
+|------|------|-------------|
+| `-WorkingDirectory` | 指定工作目錄 | 所有 Tauri 可調用的腳本 |
+| `-nopause` | 跳過暫停（非互動模式） | 所有批處理腳本 |
+| `-Quiet` | 靜默模式（無確認提示） | 初始化類、維護類 |
+
+### 初始化參數對照
+
+| 功能 | INIT_PROJECT | INIT_GIT | SETUP_RAG |
+|------|--------------|----------|-----------|
+| 跳過步驟 | `-SkipRAG`, `-SkipCleanup` | `-SkipInitialCommit` | `-SkipInstall`, `-SkipHooks`, `-SkipIndex` |
+| 強制執行 | - | `-Force` | `-Reindex` |
+| 自動啟動 | `-AutoStart` | - | - |
+| 遠端 URL | - | `-RemoteUrl` | - |
+
+### 排程參數對照
+
+| 功能 | START_DEV_AGENT | START_MULTI_AGENT |
+|------|-----------------|-------------------|
+| 執行頻率 | `-InitialDelaySeconds`, `-IntervalMinutes` | `-PollIntervalSeconds` |
+| 執行次數 | `-TotalRuns`, `-MaxEnhancementCycles` | `-SingleRun` |
+| 並行控制 | - | `-MaxAgents`, `-TaskTimeoutMinutes` |
+| 測試模式 | - | `-DryRun`, `-Standalone` |
+
+### 維護參數對照
+
+| 功能 | CLEAN_TASK_QUEUE | ARCHIVE_TASKS |
+|------|------------------|---------------|
+| 模擬運行 | `-DryRun` | `-DryRun` |
+| 顯示控制 | `-Verbose` | `-Quiet` |
+| 備份控制 | `-SkipBackup` | - |
+
+---
+
+## 平台兼容性
+
+### Windows
+
+所有腳本提供 `.bat` 批處理包裝器：
+
+```powershell
+# 批處理腳本（推薦）
+.\dev\scripts\INIT_PROJECT.bat
+.\dev\scripts\START_DEV_AGENT.bat
+
+# 直接調用 PowerShell 腳本（進階用法）
+powershell -ExecutionPolicy Bypass -File "dev\scripts\init_project.ps1" -Quiet
+```
+
+### Linux / macOS
+
+直接調用 PowerShell 腳本（需安裝 PowerShell Core）：
+
+```bash
+# 安裝 PowerShell（Ubuntu）
+sudo apt-get install -y powershell
+
+# 安裝 PowerShell（macOS）
+brew install --cask powershell
+
+# 執行腳本
+pwsh dev/scripts/init_project.ps1 -Quiet
+```
+
+### Git Bash（Windows）
+
+可使用批處理腳本或 PowerShell：
+
+```bash
+# 批處理腳本（推薦）
+./dev/scripts/INIT_PROJECT.bat
+
+# PowerShell 腳本
+powershell -ExecutionPolicy Bypass -File "dev/scripts/init_project.ps1"
+```
+
+---
+
+## 快速參考
+
+### 新專案初始化流程
+
+```powershell
+# 1. 初始化 Git 倉庫
+.\dev\scripts\INIT_GIT.bat
+
+# 2. 初始化專案
+.\dev\scripts\INIT_PROJECT.bat
+
+# 3. 設置 RAG 引擎（可選）
+.\dev\scripts\SETUP_RAG.bat
+
+# 4. 設置 MCP Server（可選）
+.\dev\scripts\SETUP_MCP.bat
+```
+
+### 開發排程流程
+
+```powershell
+# 單 Agent 開發（自我增強模式）
+.\dev\scripts\START_DEV_AGENT.bat
+
+# 多 Agent 並行開發
+.\dev\scripts\START_MULTI_AGENT.bat
+```
+
+### 維護流程
+
+```powershell
+# 清理 TASK_QUEUE.json
+.\dev\scripts\CLEAN_TASK_QUEUE.bat
+
+# 封存已完成任務
+.\dev\scripts\ARCHIVE_TASKS.bat
+
+# 同步任務文件
+.\dev\scripts\SYNC_TASKS.bat
+```
+
+---
+
+## 故障排除
+
+### PowerShell 執行策略錯誤
+
+```powershell
+# 臨時解除限制
+Set-ExecutionPolicy -Scope Process -ExecutionPolicy Bypass
+
+# 或使用批處理腳本（自動繞過）
+.\dev\scripts\INIT_PROJECT.bat
+```
+
+### Tauri 調用失敗
+
+檢查以下項目：
+
+1. 確保使用 `-nopause` 參數（避免腳本等待輸入）
+2. 確保 `KENAZ_PROJECT_PATH` 環境變數正確設置
+3. 檢查 `multi_agent_batch.log` 或 `multi_agent_startup.log`
+
+### Git Hooks 不生效
+
+```powershell
+# 重新配置 Git hooks
+.\dev\scripts\SETUP_GIT_HOOKS.bat
+
+# 驗證配置
+git config --get core.hooksPath
+# 應該輸出：.githooks
+```
+
+---
+
+## 相關文檔
+
+- **初始化指南**：`CLAUDE.md#CLI 工具`
+- **排程系統**：`CLAUDE.md#排程腳本（自我增強模式）`
+- **多 Agent 開發**：`CLAUDE.md#多 Agent 並行開發`
+- **RAG 系統**：`.system/rag/README.md`（待建立）
+- **Pipeline 系統**：`.system/pipeline/README.md`
+
+---
+
+**最後更新**：2026-02-19
+**維護者**：Kenaz AI Team