kenaz 0.3.22 → 0.3.24

package/core/dev/pipeline/docs/overview.md

@@ -1,406 +0,0 @@
----
-type: guide
-title: Pipeline System 系統概覽
-description: Kenaz AI 任務管理與工作流程編排系統完整介紹
-tags: [pipeline, task-management, workflow, orchestration, multi-agent]
-audience: all
----
-
-# Pipeline System 系統概覽
-
-## 簡介
-
-Pipeline System 是 Kenaz AI 的核心任務管理和工作流程編排系統，負責：
-- 任務生命週期管理（建立、分派、執行、完成）
-- 多 Agent 並行協作調度
-- 依賴關係解析與衝突檢測
-- 進度追蹤與報告生成
-- 路徑鎖定與資源管理
-
-## 系統架構
-
-```
-Pipeline System
-├── 任務管理
-│   ├── TASK_QUEUE.json         # 任務佇列（活躍任務）
-│   ├── tasks/                  # 待處理任務定義
-│   └── completed/              # 已完成任務
-│
-├── 狀態追蹤
-│   ├── PROGRESS.md             # 人類可讀的進度報告
-│   ├── AGENT_STATE.json        # Agent 執行狀態
-│   ├── LOCK_STATE.json         # 路徑鎖定狀態
-│   └── DASHBOARD_HEARTBEAT.json # Dashboard 心跳
-│
-├── 配置
-│   ├── PIPELINE_CONFIG.json    # Pipeline 配置
-│   └── SELF_ENHANCEMENT_STATUS.json # 自我增強狀態
-│
-├── 歷史記錄
-│   ├── logs/                   # 執行日誌
-│   ├── backups/                # 備份文件
-│   └── archive/                # 封存任務
-│
-└── 編排引擎
-    ├── orchestrator/           # Python 編排模組
-    │   ├── task_queue.py       # 任務佇列管理
-    │   ├── lock_manager.py     # 路徑鎖定
-    │   ├── dependency_resolver.py # 依賴解析
-    │   ├── agent_assigner.py   # Agent 分派
-    │   └── feature_agent_manager.py # Feature Agent 管理
-    └── self_enhancement/       # 自我增強模組
-```
-
-## 核心概念
-
-### 1. 任務 (Task)
-
-每個任務是一個 YAML 文件，定義：
-- **ID**: 唯一標識符（如 `TASK_001`）
-- **標題**: 簡短描述
-- **描述**: 詳細說明
-- **類型**: feature, bugfix, refactor, docs, test
-- **優先級**: P0 (最高), P1, P2, P3 (最低)
-- **狀態**: pending, in_progress, completed, blocked, cancelled
-- **Scope**: 影響的檔案路徑範圍
-- **依賴**: 前置任務
-- **驗收標準**: 完成條件
-
-**範例**：
-```yaml
-id: TASK_123
-title: "建立用戶認證 API"
-description: |
-  實現 JWT 認證機制，包含登入、註冊、Token 刷新功能
-type: feature
-priority: P1
-status: pending
-scope:
-  - src/api/auth/
-  - src/models/user.py
-dependencies:
-  - TASK_120  # 資料庫 Schema
-acceptance_criteria:
-  - AC-123-1: 登入 API 回傳 JWT token
-  - AC-123-2: Token 驗證中介軟體正常運作
-  - AC-123-3: 通過安全性測試
-```
-
-### 2. Agent 分派
-
-**單 Agent 模式** (Dev Agent):
-```
-用戶 → /dev → Dev Agent 執行任務
-```
-
-**多 Agent 模式** (Feature Agent):
-```
-Scheduler → 分析 TASK_QUEUE → 分派無衝突任務
-    ↓
-┌───────────────┼───────────────┐
-↓               ↓               ↓
-Agent 1        Agent 2        Agent 3
-Branch A       Branch B       Branch C
-TASK_101       TASK_102       TASK_103
-Scope: api/    Scope: ui/     Scope: tests/
-```
-
-### 3. 路徑鎖定 (Path Locking)
-
-防止多個 Agent 同時修改同一文件：
-```json
-{
-  "src/api/auth/": {
-    "locked_by": "agent_001",
-    "task_id": "TASK_123",
-    "locked_at": "2026-02-09T10:30:00Z",
-    "mode": "exclusive"
-  }
-}
-```
-
-**鎖定模式**：
-- **Exclusive**: 排他性鎖定（寫入）
-- **Shared**: 共享鎖定（只讀）
-
-### 4. 依賴解析
-
-任務之間的依賴關係：
-```
-TASK_120 (資料庫 Schema)
-    ↓ 依賴
-TASK_123 (認證 API)
-    ↓ 依賴
-TASK_125 (前端登入頁面)
-```
-
-Dependency Resolver 確保：
-- 前置任務完成後才執行
-- 循環依賴檢測
-- 依賴鏈可視化
-
-### 5. 自我增強 (Self-Enhancement)
-
-Dev Agent 可以自動：
-1. 執行開發任務
-2. 分析 PRODUCT_SPEC
-3. 發現缺失功能或測試
-4. 建立新任務
-5. 繼續迭代
-
-**限制**：
-- 最大循環次數（預設 3 次）
-- 緊貼 PRODUCT_SPEC（不可天馬行空）
-
-## 工作流程
-
-### 1. 任務建立流程
-
-```
-產品需求 → /產品 → PM Agent 分析
-    ↓
-建立 PRD (PRODUCT_SPEC.md)
-    ↓
-拆解成任務 (TASK_XXX.yaml)
-    ↓
-添加到 TASK_QUEUE.json
-```
-
-### 2. 任務執行流程
-
-```
-TASK_QUEUE.json
-    ↓
-Scheduler 選擇任務 (優先級、依賴、無衝突)
-    ↓
-分派給 Agent (Dev Agent 或 Feature Agent)
-    ↓
-Agent 執行 (在隔離的 Git Branch)
-    ↓
-建立 Git Commit (包含 Task ID)
-    ↓
-更新狀態 (completed)
-    ↓
-封存任務 (移到 completed/)
-    ↓
-更新 PROGRESS.md
-```
-
-### 3. 並行執行流程
-
-```
-Scheduler 掃描 TASK_QUEUE
-    ↓
-找出無衝突的任務組 (Scope 不重疊)
-    ↓
-並行啟動多個 Feature Agent
-    ↓
-Agent 1: TASK_101 (api/)
-Agent 2: TASK_102 (ui/)
-Agent 3: TASK_103 (tests/)
-    ↓
-各自完成後合併到 main
-```
-
-## 關鍵文件說明
-
-### TASK_QUEUE.json
-
-活躍任務佇列，包含：
-- **pending**: 等待執行
-- **in_progress**: 正在執行
-- **blocked**: 被阻塞（等待依賴）
-
-**範例**：
-```json
-{
-  "tasks": [
-    {
-      "id": "TASK_123",
-      "status": "in_progress",
-      "assigned_to": "agent_001",
-      "started_at": "2026-02-09T10:30:00Z"
-    }
-  ],
-  "stats": {
-    "total_tasks": 10,
-    "completed": 7,
-    "in_progress": 2,
-    "pending": 1
-  }
-}
-```
-
-### PROGRESS.md
-
-人類可讀的進度報告，自動生成，包含：
-- 專案概況
-- 階段進度
-- 最近完成的任務
-- 待辦任務列表
-- 當前阻塞問題
-
-### LOCK_STATE.json
-
-路徑鎖定狀態，追蹤：
-- 哪些路徑被鎖定
-- 誰鎖定的
-- 什麼時候鎖定的
-- 鎖定模式
-
-### AGENT_STATE.json
-
-Agent 執行狀態，記錄：
-- 當前活躍的 Agent
-- 正在執行的任務
-- Agent 類型和 ID
-- 開始時間
-
-## 集成點
-
-### 與 Team System 的關係
-
-```
-Pipeline System     ←→     Team System
-任務分派              協作執行
-單一 Agent            Leader + Team
-任務定義              工作流程
-進度追蹤              團隊狀態
-```
-
-**使用場景**：
-- 簡單任務 → Dev Agent (Pipeline)
-- 複雜任務 → Backend Team (Team System)
-
-### 與 Dashboard 的整合
-
-Dashboard 透過以下文件監控 Pipeline：
-- `TASK_QUEUE.json` - 任務狀態
-- `PROGRESS.md` - 進度報告
-- `AGENT_STATE.json` - Agent 狀態
-- `DASHBOARD_HEARTBEAT.json` - 系統健康
-
-### 與 RAG 的整合
-
-Pipeline 系統的文檔可以被索引到 RAG 引擎，讓 Agent 能夠：
-- 查詢任務管理最佳實踐
-- 了解工作流程規範
-- 學習多 Agent 協作模式
-
-## 使用指南
-
-### CLI 命令
-
-```bash
-# 執行單一任務
-/dev
-
-# 啟動多 Agent 並行開發
-.\dev\scripts\START_MULTI_AGENT.bat
-
-# 查看進度
-/進度
-# 或
-cat dev/pipeline/PROGRESS.md
-
-# 查看任務佇列
-cat dev/pipeline/TASK_QUEUE.json
-
-# 查看 Agent 狀態
-cat dev/pipeline/AGENT_STATE.json
-```
-
-### Python API
-
-```python
-from dev.pipeline.orchestrator.task_queue import TaskQueue
-from dev.pipeline.orchestrator.lock_manager import LockManager
-
-# 載入任務佇列
-queue = TaskQueue()
-pending_tasks = queue.get_pending_tasks()
-
-# 檢查路徑鎖定
-lock_mgr = LockManager()
-can_lock = lock_mgr.acquire_lock("src/api/", "agent_001", "TASK_123")
-```
-
-## 最佳實踐
-
-### ✅ 推薦
-
-1. **明確的 Scope** - 任務的 scope 應該清楚定義
-2. **合理的優先級** - P0 只給關鍵任務
-3. **完整的驗收標準** - 每個任務至少 2-3 個 AC
-4. **及時更新狀態** - 任務完成後立即更新
-5. **定期檢視進度** - 使用 PROGRESS.md 追蹤
-
-### ❌ 避免
-
-1. **Scope 重疊** - 會導致路徑鎖定衝突
-2. **循環依賴** - 會造成任務無法執行
-3. **過度拆分** - 任務太小會增加管理負擔
-4. **忽略依賴** - 會導致執行順序錯誤
-
-## 監控與除錯
-
-### 健康檢查
-
-```bash
-# 檢查任務佇列一致性
-python dev/scripts/validate_pipeline.py
-
-# 檢查路徑鎖定狀態
-cat dev/pipeline/LOCK_STATE.json
-
-# 檢查 Agent 狀態
-cat dev/pipeline/AGENT_STATE.json
-```
-
-### 常見問題
-
-**任務卡住？**
-- 檢查依賴是否完成
-- 檢查路徑是否被鎖定
-- 查看 Agent 狀態
-
-**路徑衝突？**
-- 調整任務 scope
-- 等待衝突任務完成
-- 使用順序執行代替並行
-
-**進度不更新？**
-- 檢查 PROGRESS.md 權限
-- 確認 auto_update_progress 開啟
-- 手動觸發進度更新
-
-## 效能指標
-
-| 指標 | 單 Agent | 多 Agent (3 並行) |
-|------|---------|------------------|
-| 任務完成時間 | 15 分鐘 | 5-7 分鐘 |
-| 吞吐量 | 4 任務/小時 | 10-12 任務/小時 |
-| 資源使用 | 低 | 中 |
-
-## 相關文件
-
-- [Task Management Guide](./task-management.md)
-- [Multi-Agent Coordination](./multi-agent-coordination.md)
-- [Workflows Reference](./workflows.md)
-- [PROGRESS.md Template](../PROGRESS_template.md)
-
-## 未來規劃
-
-- [ ] Task 視覺化看板
-- [ ] 自動化測試集成
-- [ ] 任務時間預估
-- [ ] Agent 效能分析
-- [ ] 衝突自動解決
-- [ ] 智慧任務推薦
-
----
-
-**建立日期**: 2026-02-09
-**最後更新**: 2026-02-09
-**系統版本**: 1.0.0
-**維護者**: Developer Team