Skip to content

会话恢复、交接与本地记忆 ​

文档导航

原始会话、交接和长期记忆承担不同职责。Pi 保存原始会话树;Wenext-Pi 保存任务绑定、恢复点和带来源的本地记忆。交接或摘要中的“完成”不代替任务、授权或质量证据。

适用范围 ​

运行基座维护会话绑定、checkpoint、派生交接、本地记忆及上下文投影;不包含 Web、服务端、游戏领域规则。Pi SessionManager 继续维护原始会话树、分支及压缩。默认工作流要求智能体在工作片段结束前显式保存有用的交接,而非自动摘录全部对话。

checkpoint 是工作中保存的恢复点,不是结束工作片段的许可。已批准实施应继续到验证;用户确认的是最终归档与知识沉淀,不能用等待归档解释实施中止。

task.json、计划文件和冻结质量证据是权威状态。handoff、memory、Pi compaction 和近期会话片段均为派生上下文:completed 只是作者陈述,不能替代批准、检查证据或完成状态。

工具与接口 ​

入口输入/输出
wenext_continue可选 taskId;跨会话返回 switching,当前工具结果保存后自动恢复任务的原始主会话并继续;当前已在目标会话时返回任务阶段和派生上下文;多个候选返回列表
wenext_handoffaction=save/show;save 需要 notes;可选 evidence 为任务相对路径或需导入的绝对文件路径;show 可传 version 读取历史版本
wenext_handoff.stop可选 {reason: "blocked" | "user_requested", detail: string};仅在缺少外部输入或用户明确暂停时填写
notesgoal、constraints[]、decisions[]、completed[]、nextSteps[]
wenext_memoryaction=search/read/save/update/invalidate/delete,scope=task/project/user;read 使用 scope/id 读取核验后的来源
memory 写入content、sourcePath、可选 sourceTaskId、sourceExcerpt 和未来 expiresAt;update/invalidate/delete 需要 id 和 expectedVersion
memory 检索query 为不区分大小写的所有词包含匹配,含中文短语子串;offset/limit 分页,返回 total/nextOffset;includeInactive=true 可维护失效记录

存储与检索服务位于 runtime/session/ 和 runtime/memory/,不依赖 Pi SDK。Pi 工具、UI 确认和事件接入集中于 adapters/pi/continuity.ts。这些是单包内部模块,尚非独立的稳定客户端 SDK。

行为约定 ​

路径及来源 ​

<project-state> 默认为 $WENEXT_PI_HOME/projects/<name>--<path-hash>。

内容路径
当前任务权威状态<project-state>/tasks/<task>/task.json
原始主会话<task>/sessions/<time>_<native-session-id>.jsonl;保留 Pi 的树、消息、压缩和工具结果
主恢复指针task.json.latestSession={sessionId,relativePath,leafEntryId,generation,updatedAt},relativePath 相对任务目录
子会话<task>/agents/<agent-id>/sessions/;全局 runtime/agents 保留队列和运行记录,子会话不写 latestSession
旧共享来源<task>/sessions/legacy/<range-hash>.jsonl;仅归属可证明的任务片段,原共享文件不移动、不删除
损坏尾部备份<task>/continuity/recovery/<file>.<uuid>.original;只修复尾部,中间损坏明确报错
交接<task>/continuity/handoff.json
交接历史<task>/continuity/handoffs/<version>.json;更新时保留,show/version 可读取
记忆整理提示游标<task>/continuity/maintenance.json;相同阶段和批准版本不重复提示
checkpoint<task>/continuity/sessions/<session-id-sha256>.json,每个会话保留最新状态
会话分段绑定<task>/continuity/ranges/<file-and-start-sha256>.json
任务记忆<task>/memory/<uuid>.json,来源相对当前任务目录
项目记忆<project-state>/runtime/memory/project/<uuid>.json,来源相对项目根
用户偏好$WENEXT_PI_HOME/memory/user/<uuid>.json,来源为真实 UI 确认事件与会话 id
外置历史上下文已绑定任务:<task>/artifacts/context/<hash>.<ext>;未绑定普通对话:runtime/cache/context

兼容旧本地 layout 时,project-state 为 .wenext-spec,runtime 为 .runtime,用户记忆也留在该 runtime 内,不擅自写真实用户目录。已有外置状态布局无需新迁移;业务仓库无需脚本或配置。

交接保存任务身份、权威状态摘要、计划文件摘要、版本、时间、会话范围及证据 SHA-256。任务的普通更新时间和会话游标变化不使交接失效;任务阶段/批准/计划等权威内容变化会失效。

记忆保存 scope、owner、版本、时间、可选到期时间、状态和来源。task/project 必须指向当前范围内的普通文件;提供 sourceTaskId 时按稳定任务 id 在当前项目的活动/归档目录中唯一解析。sourceExcerpt 指定文件内的原文片段,只校验该片段仍存在,文件中无关改动不使记录失效;未提供片段时校验全文件摘要。片段存在只说明来源可核验,不证明旧决定仍然适用;新决定冲突时仍须 update/invalidate。read 返回核验后的来源,最多 16,000 字符并显式标记 truncated。相同内容和来源的重复 save 尽量复用既有有效记录。user 写入/更新/失效/删除必须通过真实 UI 确认,工具参数不能伪造确认。删除会删除记录,不保留隐藏内容副本;此前会话中已见到的内容不被倒改。

交互界面的 /resume ​

选择器同时读取入口会话和当前项目 tasks/<task>/sessions 中的有效主会话。任务项显示任务标题和状态;已由任务主会话接管的入口占位会话不再重复出现。恢复的是原始 JSONL 会话树,保留多轮用户对话与工具结果,不用 handoff 或最后一条消息重建历史。原有压缩和模型上下文预算仍适用。

已归档任务显示“已归档 · 只读”,选择后打开本地历史查看器。使用方向键、PgUp/PgDn、Home/End 浏览,Esc 或 q 返回;不调用模型、不追加原始会话、不重新开放任务。文本和工具调用可读,图片等附件显示类型提示,不在终端重绘。

适配只在 CLI 运行期间包装锁定 SDK 的公开 SessionManager.list/listAll,退出或失败后恢复原方法。只发现当前项目的主会话,不混入子智能体会话;无效的任务会话不进入列表。SDK 升级必须复测选择器发现与实际主会话恢复。

恢复和投影 ​

宿主固定适配 Pi 1.1.0 的公开生命周期方法。withPiRuntimeOwner(owner, operation) 在 native main 启动期间挂接公开 AgentSessionRuntime.setRebindSession,不重写 TUI/登录/模式启动、不缓存旧 command context。Agent.finishTurn 在创建/继续工具结果落盘后结束旧轮次;agent_settled 调度带一次性 nonce 的内部命令,switchSession(...,{withSession}) 使用新上下文继续原请求。用户主动取消不触发自动续跑。

运行时构造失败前暂缓旧 AgentSession.dispose;失败时重绑仍存活的旧会话,成功时在新会话工作前释放旧会话。这个适配依赖锁定 SDK 的公开调用顺序,升级 SDK 必须重跑真实运行时和 CLI 集成测试;它不是任意版本通用的事务保证。

任务主写租约使用既有进程存活检测锁。同任务另一活进程不能打开第二个写者;不会因超时抢占活进程。每次 native append 返回后先 fsync JSONL,再原子发布 latestSession;在 task.json 发布前 SIGKILL 可从任务内有效 lineage 恢复。lineage 声明 taskId/role/main/generation/native sessionId。仅准备而未应用的文件标记 prepared,不参与恢复;/new 的空文件不提升指针。原生历史会话被显式重新打开时分配新的 generation;迟到旧 generation 不能覆盖。压缩与 tree 选择保存真实叶子,不把物理最后一个兄弟分支当目标。

finish 仍须原有用户归档授权与质量检查。宿主先记录 completed、收据和 archivePending,保留目录接收工具结果及最终回复;安全边界切到未绑定会话后再移动目录。未归档的已授权完成任务在下次启动回收死写者后完成归档。归档后的原始会话仅作证据,不允许原生 resume 在归档内继续写入。任务复制/迁移按当前项目 cwd 打开;生成的附件引用可根据 lineage 原目录映射至新任务目录,旧缓存引用按需复制到 artifacts/imported;缺失旧附件不会伪造。

  1. 当前有效、未完成的会话指针优先;否则只允许自动选择唯一未完成任务。旧 Codex/Claude 会话提示不能从多个候选中自动挑选。
  2. 跨会话先读取旧范围,再绑定新范围;新文件不继承旧 entry id。同一会话 A/B 切换保留独立分段,恢复时排除切换边界所属的前一个任务。
  3. 按 Pi parentId 还原目标叶子的祖先链,排除兄弟分支。截断文本时仍保留 role、toolCallId、isError、stopReason,compaction 文本标为派生内容。
  4. 交接 missing/corrupt 时继续使用任务文件与 Pi 片段。stale 保留历史正文并标记 task_changed/evidence_changed,不把旧阶段摘要当作当前事实。记忆过期、来源变化或 owner 不匹配时不进入正常检索。
  5. before_agent_start 注入有界派生上下文,空查询仅自动带入本任务记忆和用户偏好;跨任务的项目记忆由智能体按需显式 search。工具 show/search 可以按需检索完整有界记录;系统提示明确权威状态及当前用户指令优先。阶段/批准版本变化后的 turn_end 附加一次隐藏整理提示,不额外请求模型、不新增批准或完成门禁;摘要和语义决定仍由智能体显式保存,不能保证模型一定执行整理。
  6. context 投影保留最新 user 消息。历史图片按模型 input 能力和预算保存为可重载引用;大的工具输出保存 JSON 原件,保留工具结果的错误标志和调用配对。写盘失败保留原内容。
  7. 使用模型 contextWindow 的 60% 作为投影预算(最少 256);文本按字符/2 保守估计,非实际 token 统计。未处理的对话长度、系统提示和大输入由 Pi 原生压缩/模型限制处理,不承诺每次请求必定适配预算。
  8. 不支持图片的模型不会被假装成视觉模型。当前图片仍保留,交互模式提示切换模型;非交互客户端可读取 unsupportedCurrentImages 事件。Pi SDK 会捕获 context handler 异常,因此不通过抛异常假装能阻止 provider 请求。

本地限制 ​

  • 单条 memory 内容和证据片段最多 4,000 字符;搜索扫描有效记录后排序并分页,不按随机 UUID 截去历史。默认最多 10 条、6,000 个序列化字符;显式工具检索最多 16,000 字符。nextOffset 基于本次排序,期间新增/修改可能使分页位置变化;预算无法容纳下一条时返回相同 offset,调用方可提高预算或缩小查询。
  • goal 最多 2,000 字符,每组 notes 最多 20 条、每条 1,000 字符;证据最多 30 个。单个本地 JSON 状态最多 128 KiB,文件原子替换并使用 0600 权限。
  • 会话按 64 KiB 块解码并逐行解析,不再把大于 64 MiB 的文件当作空历史。近期投影保留分支元数据与有界内容,内存随记录数和最大单行增长,不保留全部大工具正文。分段边界不再截取前 100 个,避免遗漏其它任务的隔离边界;不删除 Pi 原会话。单个外置上下文原件最多 16 MiB,超过或持久化失败时保留原消息。
  • expectedVersion 检查和变更位于同一作用域的本机跨进程锁;冲突明确拒绝,不能覆盖另一进程的新版本。协调与死锁持有者回收见 并行运行契约。没有向量库、云同步、自动过期文件清理或独立记忆 UI。

结果与错误处理 ​

场景行为
当前指针合法 / 唯一候选恢复对应任务
多候选或旧平台提示返回候选,不写新绑定
指针 taskId 与目录中的 task 不一致不采用错误任务
新会话无 entry清空 task/pointer 的旧 entry id,不从无范围文件抓取其他任务正文
任务阶段或证据变化handoff=stale,权威状态继续有效
摘要 JSON 损坏 / 缺失corrupt/missing;不改任务真相
memory 来源变化 / 到期 / 失效正常检索不返回;includeInactive 可检查
memory 版本冲突拒绝更新或删除,要求重新检索
user scope 无 UI、拒绝确认、调用已取消或确认期间取消拒绝保存/更新/失效/删除;向 UI 传递 AbortSignal,迟到的确认不能写入偏好;其他 scope 不冒充用户偏好
来源或状态路径经 symlink 越界拒绝写入/检索该记录
当前图片 + text-only model保留原图并提示能力不支持
历史输出超过预算引用本地原件,不把失败改写成通过

观测边界 ​

事件为 session_recovery、session_interrupted、session_compaction_started/completed/failed、checkpoint_failed、handoff_saved、memory_changed、context_projected;payload 只含原因、状态、计数、布尔值等,不含摘要、记忆正文、代码或原始错误内容。图片事件去掉文件路径,仅保留数量/字节数。provider 未报告 usage 时仍为 unknown;budgetMethod=estimate 不转换为 usage。

导入交接证据 ​

wenext_handoff save 的 evidence 接受任务相对路径或显式绝对文件路径。绝对路径(包括 /tmp/check.log)复制为 <task>/continuity/evidence/<sha256>-<basename>,handoff 保存相对路径与摘要;临时源删除不影响恢复。普通文件限制 16 MiB,目录、越界相对路径和损坏引用仍拒绝。导入内容只是来源证据,不生成质量 receipt,不改变批准或 check 状态。

正确:保留失败日志并在交接中说明失败。错误:为了保存交接删除证据引用,或把复制成功当作测试通过。

当前读图与交接增量 ​

图像模型最新一批工具结果在 8 MiB 图片总预算内保留像素,不因历史上下文预算立即裁剪。更大的图片保存后提示缩放或裁剪副本;文本模型提示切换能力。图片按字节摘要命名,相同内容复用附件;后续请求可裁剪历史图片,原始会话仍保留。

恢复提示从当前会话分支提取交接之后最多 12 条消息索引,每条最多 500 字符,保留工具错误标记。索引不能充当验证收据;完整会话、当前任务和真实检查结果优先于旧 nextSteps。