任务状态：把运行进度表示清楚

1. 状态描述任务现在在哪里

状态是程序保存的阶段标记，例如准备、运行、等待人工、完成。状态迁移是从一个阶段进入另一个阶段。读者看到运行会继续等待，看到等待人工会核对操作，因此状态同时服务于程序和界面。

物流包裹的“已揽收→运输中→已签收”就是熟悉的例子：当前标记告诉你走到哪里，运输记录告诉你怎么走来的。

状态和结果可以分别保存：状态写 completed，结果写答复和来源；失败附错误类别；人工状态附待批准操作。界面先根据状态选展示方式，再根据结果填内容。

2. 记录一次暂停与恢复

先在 PowerShell 创建并进入学习目录：

mkdir "F:\学习\l3-state" -Force
cd "F:\学习\l3-state"

保存下面的文件后，在这个终端运行 dir 核对文件名，再执行本节给出的运行命令。

在新文件夹创建 state.py，写入完整代码：

先在 PowerShell 创建并进入学习目录：

mkdir "F:\学习\l3-state" -Force
cd "F:\学习\l3-state"

保存下面的文件后，在这个终端运行 dir 核对文件名，再执行本节给出的运行命令。

"""用允许的状态迁移表记录任务的进度。"""
import json

ALLOWED = {
    "ready": {"running", "cancelled"},
    "running": {"completed", "failed", "waiting_human"},
    "waiting_human": {"running", "cancelled"},
    "completed": set(), "failed": set(), "cancelled": set(),
}

def move(task, target):
    current = task["status"]
    # 每条记录同时保存起点和终点，方便追查哪次操作改变了任务。
    if target not in ALLOWED[current]:
        raise ValueError(f"无法从 {current} 切换到 {target}")
    task["events"].append(f"{current} -> {target}")
    task["status"] = target

if __name__ == "__main__":
    task = {"status": "ready", "events": []}
    for target in ("running", "waiting_human", "running", "completed"):
        move(task, target)
    print(json.dumps(task, ensure_ascii=False))

ls
python state.py

输出：

{"status": "completed", "events": ["ready -> running", "running -> waiting_human", "waiting_human -> running", "running -> completed"]}

ALLOWED 是迁移表，键为当前状态，集合为允许到达的状态。ready 可进入运行或取消；等待人工可恢复或取消；终点的集合为空。

move 先读取当前状态，查表，通过后追加事件并改变状态。events 保存过程，status 保存当前位置。人工批准所针对的提案则需要另行保存，在恢复前校验。

3. 改迁移顺序，观察结果

把序列改为 ("running", "failed")，输出失败状态和两条事件。改为 ("completed",)，会出现“无法从ready切换到completed”，表明流程跳过了运行阶段。

若业务允许准备后直接答复，可以明确增加这条边，并为直接答复入口添加完成条件。再把序列设为 ("running", "waiting_human", "cancelled")，保存后运行 python state.py，最终状态是取消，暂停前的记录仍保留。恢复第2节的四项序列再重跑，任务重新完成。

4. 保留检查用例

同一目录创建 test_state.py：

下面的测试检查合法与非法的状态迁移，以及等待人工后重新进入运行状态的过程。

"""检查state示例的正常路径和边界结果。"""
import unittest
from state import move
class Tests(unittest.TestCase):
    def test_flow(self):
        s={"status":"ready","events":[]}
        move(s,"running");move(s,"completed")
        self.assertEqual(s["events"],["ready -> running","running -> completed"])
    def test_invalid(self):
        with self.assertRaises(ValueError): move({"status":"ready","events":[]},"completed")

if __name__ == "__main__":
    unittest.main()

python -m unittest test_state -v

测试同时检查正常路径和改变条件后的结果。遇到导入错误时，先核对两个文件是否在同一目录；遇到断言失败时，比较预期值和实际值，再回到相应分支。

5. 区分任务进度与一次工具结果

工具查询成功可能只是局部进展：查到订单以后还要查政策和计算，所以整体任务继续运行。一个备用来源失败，另一来源已提供完整证据，整体任务也可能完成。整体状态应根据目标和现有结果共同判断。

内存字典随程序退出消失，长任务可将状态和事件写入数据库。恢复时从最近确认的结果继续。多个执行器推进同一任务时，可增加版本字段：更新要求版本与读取时一致，成功后增加版本，避免互相覆盖。

状态太多会让界面与分支复杂，太少则把等待、失败和未知混在一起。先按读者的下一步操作划分：继续等、补资料、批准、重试、查看结果，常能得到实用的集合。

LangGraph 持久化说明介绍检查点和恢复。先画清自己的状态与迁移，再对照框架保存位置，阅读会更容易。

用一次退款查询串起状态与数据

状态迁移与业务数据一起保存，恢复时才能知道批准的是哪个操作。只恢复waiting_human这个词，还缺金额、对象和版本。事件列表可以保存必要字段，任务对象保留当前快照，二者共同帮助恢复。

若用户修改金额，提案版本应增加，等待状态展示新提案。若用户取消，保存取消记录；正在执行的工具还要处理取消请求的时机，已经完成的外部写入需要回查结果。

同一个任务有多个工具时，工具返回ok可以记录在子动作里，整体状态仍为running。达到目标且结果核对通过后，再更新任务为completed。这样页面上的完成含义和实际产物一致。

回顾与下一步

状态描述位置，迁移表安排下一步，结果保存产物，事件解释过程。继续读 错误分类。