任務狀態流轉指南 (Task Status Transition Guide)

本文檔說明了 GIIP 系統中 AI 代理執行的任務各狀態的含義、流轉過程以及記錄位置。

1. 概述

任務狀態管理是分布式 AI 代理協作的核心機制。所有狀態變化均基於文件（而非資料庫）實現，透過特定的 PowerShell 腳本讀取並修改這些文件來完成狀態流轉。

2. 狀態流轉流程 (Transition Flow)

stateDiagram-v2
    [*] --> Pending : [發生] Orchestrator 創建文件
    Pending --> In Progress : [開始] 執行 launch_subsession.ps1
    In Progress --> Completed : [完成] 代理工作及驗證完成
    Completed --> [*] : [結束] 反映至 MASTER_ISSUE_LIST.md

狀態	含義	流轉條件
Pending	等待中。任務已分配但尚未開始	Orchestrator 在 giipdb/dispatch/ 中創建文件
In Progress	進行中。代理已佔用該任務並正在處理	狀態被 launch_subsession.ps1 或 launch_role.ps1 替換
Completed	已完成。工作已結束且代理已完成自我驗證	代理手動修改文件中的 Status
Archived	已歸檔。完成的工作在反映到主列表後進行清理	文件被管理工具移動或標記

3. 技術實現機制 (Technical Mechanics)

3.1 狀態識別 (check_status.ps1)

• 掃描：掃描 giipdb/dispatch/ 資料夾下的 TASK_*.md 文件。
• 解析：利用正規表示式查找文件頂部的 **Status**: 模式，提取當前狀態。

3.2 狀態更新 (launch_subsession.ps1)

• 自動化：發現 Pending 狀態的任務時，讀取文件內容並使用 -replace 強制替換為 **Status:** In Progress。
• 注意：由於涉及文件的物理修改，若發生編碼錯誤或正規匹配失敗，可能導致文件內容損壞。

3.3 腳本差異

• launch_subsession.ps1：立即執行後台代理並直接修改文件。
• launch_role.ps1：為進行用戶交互而修改文件，並在剪貼板生成提示詞。

4. 記錄與同步點

當任務狀態發生變化時，代理必須在以下兩個位置留下痕跡：

1. 單個任務文件：giipdb/dispatch/TASK_*.md (Source of Truth)
2. 主問題列表：giipdb/docs/00_Master/MASTER_ISSUE_LIST.md (控制面板)

5. 常見問題排查 (Troubleshooting)

• 狀態未改變：請檢查文件頂部的 **Status:** 格式是否正確（注意錯別字或空格）。
• 內容丟失：若文件編碼不是 UTF-8 BOM，腳本處理過程中可能會出現亂碼。請務必確認編碼格式。

---

最後更新日期：2026年3月20日