kenaz 0.3.18 → 0.3.19

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

@@ -1,724 +0,0 @@
-# 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