学习笔记 · Obsidian
Threads：状态、Checkpoint 与生命周期
Thread 是一组 stateful Runs 的持久容器，保存累计 state、interrupts 与 checkpoint 历史。Assistant 描述“运行什么”，Thread 描述“这段会话执行到哪里”。
资源与查询端点
| 能力 | 方法与路径 | 说明 |
|---|---|---|
| 创建 | POST /threads | 200；自定义 ID 冲突 409；根文档与 create 页同操作 |
| 读取/删除 | GET、DELETE /threads/{thread_id} | 不存在 404 |
| Patch | PATCH /threads/{thread_id} | 更新 metadata 与 TTL |
| Copy | POST /threads/{thread_id}/copy | 复制 Thread，目标冲突 409 |
| 搜索/计数 | POST /threads/search、POST /threads/count | 按 ID、metadata、state values、status 过滤 |
| 批量 prune | POST /threads/prune | 对 thread IDs 应用 delete 或 keep_latest |
| Join thread stream | GET /threads/{thread_id}/stream | 加入 Thread 级事件流 |
Thread 状态枚举是 idle、busy、interrupted、error。返回还包含创建/更新时间、state 更新时间、metadata、config、values、interrupts；只有请求包含相应信息时才返回 TTL/extracted 等扩展字段。
创建、幂等与 TTL
ThreadCreate 可传 thread_id、metadata、TTL 和预置 supersteps。if_exists 为 raise（默认）或 do_nothing。supersteps 由一组 update 组成，可携带 values/command 和 as_node，属于状态导入能力，不能接受未校验的客户端任意节点名。
TTL 使用分钟数与策略：
delete：到期删除 Thread；keep_latest：清理历史但保留最新状态。
Patch 可调整 metadata/TTL；prune 可对多个 Thread 立即应用相同策略。TTL 不是数据治理的完整替代：还要定义备份、审计、用户删除、legal hold 与 Store 中跨 Thread 数据的生命周期。
State 与 checkpoint 端点
| 能力 | 方法与路径 | 差异 |
|---|---|---|
| 当前 state | GET /threads/{id}/state | 返回当前 values、next、tasks、checkpoint、interrupts |
| 按 checkpoint ID | GET /threads/{id}/state/{checkpoint_id} | URL 中直接指定 ID |
| 按 checkpoint config | POST /threads/{id}/state/checkpoint | body 带 thread/checkpoint namespace/ID/map，可请求 subgraphs |
| 历史简表 | GET /threads/{id}/history | 直接获取历史 |
| 历史查询 | POST /threads/{id}/history | limit、before、metadata、checkpoint 过滤 |
| 更新 state | POST /threads/{id}/state | values、目标 checkpoint、as_node |
ThreadState 的核心字段是 values、下一节点列表 next、tasks、checkpoint config、metadata、created_at、parent checkpoint 与 interrupts。checkpoint config 由 thread_id、checkpoint_ns、可选 checkpoint ID/map 组成。
update state 会“仿佛某个节点刚执行完”写入更新，服务端返回新 checkpoint。它不是普通 CRUD：reducer、下一节点与 time travel 都可能改变。生产后台必须限制可写字段和 as_node，并在写前记录旧 checkpoint，避免越权改写会话或跳过审批节点。
Search 与投影
搜索支持 status、metadata、state values、IDs，分页默认 10；排序字段含 thread/status/created/updated/state_updated 时间。select 可裁剪返回字段。extract 最多定义 10 个 alias→JSONB path，路径必须从 values、metadata、config 或 interrupts 开始，例如抽取最后消息；它适合列表投影，不替代 schema 校验。
一致性与安全
- 一个 Thread 同时只有一种明确的多任务策略；不要让多个调用方绕过 Run 的并发控制直接更新 state。
- copy/time travel 产生分支后保存源 Thread、源 checkpoint 与新 Thread ID，防止审计链断裂。
- 恢复 interrupt 要从 checkpoint 继续，不要用新 HumanMessage 覆盖未完成 tool call。
- metadata/values 的过滤必须自动叠加租户/owner 条件，不能相信客户端传入 owner。
- 删除、prune、TTL 和 state mutation 均是高风险操作，应提供 dry-run/确认、审计和可恢复窗口。