企业官网建设流程全解析

本教程带你用约 10 分钟完成TaskStateGuard的安装与首次重启对账（restart reconciliation）预览。TaskStateGuard 是一个面向 AI 智能体和后台 worker 的嵌入式 SQLite 状态对账工具：服务重启后，那些一直卡在running的任务和pending的投递记录，可以先用--dry-run只读预览会改动多少条记录，确认无误后再真正收敛，全程绝不把"未知结果"猜成成功。

1️⃣ TaskStateGuard 解决什么问题？

想象这样一个场景：你的 AI 智能体服务半夜重启，界面上 20 个任务还显示running，但你已经无法确认它们是否真的还在工作。人工逐条排查既慢又危险——猜错了可能把失败的任务标记成成功。

TaskStateGuard 的做法是把"任务终态"和"投递终态"拆成两套独立状态机：

状态流转如下（完整说明见 README.md）：

任务：queued ──> running ──> succeeded | failed | timed_out | cancelled 投递：pending ──> delivered | failed | not_applicable

任务终态回答"工作以什么结果结束"，投递状态回答"结果是否真实送达"。两者分开，就不会把"任务完成"误判成"用户已收到"。

2️⃣ 一键安装 TaskStateGuard（Linux / macOS / Windows）

前置要求：CPython 3.11–3.14。运行时代码只依赖 Python 标准库，无网络请求、无遥测。

Linux 或 macOS：

python3 -m venv .venv . .venv/bin/activate python -m pip install task-state-guard

Windows PowerShell：

py -3 -m venv .venv .\.venv\Scripts\python.exe -m pip install task-state-guard

💡 如果你想从源码审阅未发布的版本，先 clone 仓库，在仓库根目录创建虚拟环境后，把安装命令换成python -m pip install .：

git clone https://gitcode.com/gh_mirrors/ta/task-state-guard cd task-state-guard python3 -m venv .venv && . .venv/bin/activate python -m pip install .

3️⃣ 运行首次重启对账演示：3 步跑通完整流程

随仓库提供的演示脚本 examples/restart_reconciliation_demo.py 会在系统临时目录创建一个 SQLite 库，写入 4 条固定的合成样例任务，然后调用真实 CLI 依次执行preview → apply → 幂等复查 → doctor，结束后自动删除临时数据库。它不读取本机任务数据，是体验对账流程最安全的方式。

Linux 或 macOS（在仓库根目录执行）：

PYTHONDONTWRITEBYTECODE=1 PYTHONPATH=src python3 examples/restart_reconciliation_demo.py

Windows PowerShell：

$env:PYTHONDONTWRITEBYTECODE = "1" $env:PYTHONPATH = "src" py -3 .\examples\restart_reconciliation_demo.py --allow-external-acl

你会看到三段关键输出，前两段的核心字段解读如下：

对账规则本身（截止时间、活跃宽限期、投递宽限期）定义在 src/task_state_guard/reconcile.py，reconcile子命令的参数在 src/task_state_guard/cli.py。

4️⃣ 对自己的数据库：先预览，再执行，最后体检

演示跑通后，对你自己的账本按"预览 → 应用 → 体检"三步操作即可（假设数据库在./private-state/tasks.sqlite）：

# 第 1 步：只读预览（不修改任何任务、事件或数据库） task-state-guard --db ./private-state/tasks.sqlite reconcile \ --active-grace-seconds 600 --delivery-grace-seconds 600 --dry-run # 第 2 步：确认计数符合预期后，正式执行 task-state-guard --db ./private-state/tasks.sqlite reconcile \ --active-grace-seconds 600 --delivery-grace-seconds 600 # 第 3 步：健康检查，输出只含聚合计数 task-state-guard --db ./private-state/tasks.sqlite doctor

几个值得记住的细节：

• --dry-run不是锁。预览只代表"预览那一刻"的判断结果；执行前请核对返回的dry_run和applied字段，因为时间和并发状态可能已经变化。
• doctor的退出码：0表示账本健康；1表示真实存在结构、状态、时间戳或事件链不一致。
• Windows 用户：需先把数据库目录配置为仅服务账户可访问的私有 DACL，并将--allow-external-acl放在子命令之前（该参数只是"确认边界已建立"，不会替你创建或验证 DACL）。

5️⃣ 快速参考：核心命令速查表

6️⃣ 常见问题

TaskStateGuard 能续跑中断的智能体任务吗？不能。它保存并收敛任务生命周期元数据，但不保存计算检查点。超过截止时间的running任务会转为timed_out，是否新建重试任务由你的运行时决定。

预览结果能保证与稍后执行完全相同吗？只有同一时刻且期间无并发状态变化时才相同。--dry-run不写数据库、不锁定未来执行，它用于审阅当前判断，不是对后续执行的预约。

它会保存提示词或消息正文吗？不会。数据库中没有提示词、消息正文、任务正文或自由文本字段，reconcile和doctor输出也只含聚合计数，不返回任务 ID——这让诊断输出天然适合纳入工作流可观测性（workflow observability）体系。

它是什么，不是什么？它是本地 SQLite 状态账本护栏，不是队列、调度器、worker 或工作流引擎，也不承诺恰好一次执行/投递。完整边界说明见 THREAT_MODEL.md。

7️⃣ 延伸阅读

• 完整文档与双语 FAQ：README.md
• 状态模型与原因码定义：src/task_state_guard/model.py
• 账本存储与权限边界：src/task_state_guard/store.py
• 合成测试套件（覆盖超时、重启宽限、幂等闭合等场景）：tests/test_task_state_guard.py
• 版本与发布说明：CHANGELOG.md、RELEASE_NOTES_v0.1.0.md

跑通本教程后，你已经掌握了 TaskStateGuard 的完整闭环：安装 → 演示 → 预览 → 执行 → 体检。把它放到你的智能体运行时或 worker 池旁边，重启后的状态收敛从此有数可依，不再靠猜。🎉