测试是持久性：这在三个月后的CI重跑中是否有用？如果是，仓库。如果否，遥测。

JSON Schema是契约。没有它，每个Agent发明新字段，每个审查者学习新形状，每个CI脚本必须特殊处理过去版本。有了它，坏写入是被拒绝的写入。

Schema覆盖：必需键、允许的 status 值、禁止值（例如数组的 null）、模式约束（任务id匹配 T-\d{3,}）、版本字段用于迁移。

状态写入需要存活部分失败：写入临时文件，fsync，重命名覆盖目标。状态文件是真相来源；半写入的文件比没有文件更糟。

当Schema变更时，在Schema升级旁边发布迁移脚本。状态文件携带 schema_version 字段；管理器拒绝加载它无法迁移的版本文件。

原子临时-重命名不是可选的。 2026年3月Hive项目bug报告清楚地记录了失败模式：state.json 通过 write_text() 写入，异常被捕获并静默。部分写入导致会话针对损坏状态恢复，没有信号。修复始终是：tempfile.mkstemp 在目标同一目录，写入，fsync，os.replace。
每个非幂等工具调用的幂等键。 如果Agent在调用工具后但在检查点结果之前崩溃，恢复重试工具调用。读取安全；邮件、数据库插入、文件上传危险。模式：在执行前将每个工具调用ID记录到 pending_calls.jsonl。重试时，检查ID；如果存在，跳过调用并使用缓存结果。
将大型工件与状态分开。 不要在 agent_state.json 中存储CSV、长记录或生成文件。将工件保存为单独文件（或上传到对象存储），仅在状态中保留路径。
审计用事件溯源，恢复用快照。 每次变更追加到事件日志（state.events.jsonl）；定期快照到 state.json。恢复读取快照，然后重放快照时间戳之后的任何事件。

实践

code/main.py实现：agent_state.schema.json 和 task_board.schema.json、标准库验证器、带原子临时-重命名写入的 StateManager，以及跨两轮变更、持久化、重新加载和证明往返的演示。

交付

outputs/skill-state-schema.md生成项目特定的JSON Schema对（状态+板）、连接到原子写入的Python StateManager，以及迁移脚手架。