任务状态流转指南 (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日