qwen-code Session 存储生命周期修复损坏、孤儿与 Active/Archive 冲突的确定性维护方案【免费下载链接】qwen-codeAn open-source AI coding agent that lives in your terminal.项目地址: https://gitcode.com/GitHub_Trending/qw/qwen-code导读本文讲解 qwen-code 项目中「会话存储生命周期修复」Session storage lifecycle repair的设计与实现在会话 transcript 为空、头部撕裂损坏或属于父级已不存在的遗留子会话legacy orphan时依然能够对物理文件执行确定性的 delete、archive、unarchive 操作并为 active/archive 目录同时存在同名会话文件的冲突场景提供显式的resolveConflicts修复选项。读完本文你将掌握该仓库生命周期分类器的判定规则、写入者锁与 generation 防护机制以及 REST/ACP/SDK 三层 API 的兼容性演进方式。问题背景生命周期操作不应依赖「可加载的 transcript」在 2026-08-22-session-storage-lifecycle-repair.md 描述的问题中会话生命周期操作删除、归档、取消归档此前依赖「将 transcript 加载为可用会话」这一前置条件。这对于 delete、archive、unarchive 而言约束过强transcript 文件为空empty文件头部撕裂或格式损坏torn / malformed head属于遗留子会话legacy child其父会话已不存在。上述文件虽然无法被加载为对话但只要「选定的工作区workspace」与「归档状态」是明确的物理文件仍然需要维护。否则这些物理文件会被遗留在磁盘上stranded既无法加载也无法通过正常生命周期操作清理。该变更的目标是让 delete、archive、unarchive 直接作用于「所选工作区拥有的、拼写精确匹配的常规 transcript 文件」并为 active/archive 冲突新增显式修复选项同时不改变 transcript 加载、列举、导出、组织、Live 会话身份以及通用的大小写不敏感查找逻辑正常生成的会话 UUID 仍保持规范的小写形式。存储分类生命周期分类器的判定规则分类器lifecycle classifier会同时检查请求 UUID 文件在 active 与 archived 两个目录中的存在情况其判定语义如下判定条件结果路径不存在不贡献任何状态常规的空文件或损坏文件贡献「物理状态」physical state可读的首条记录必须标识出请求的会话与所选工作区首条记录标识了其他工作区视为未找到not found符号链接、目录或其他非常规条目失败关闭fails closedactive 与 archived 同时存在构成冲突conflict分类器会捕获文件的身份信息file identity用于纯物理维护。在 unlink 或 rename 之前Core 会再次验证「同一个常规文件仍占据相同路径」。在源码层面该逻辑位于 sessionService.ts 的resolveMaintainableSessionSnapshot对active、archived两种状态逐一调用readMaintainableSessionIdentitysessionService.ts打开文件时使用O_RDONLY在非 Windows 平台额外叠加O_NOFOLLOW与O_NONBLOCK从而对符号链接、目录等非常规条目失败关闭捕获ELOOP时抛出SessionStorageEntryError(sessionId, non_regular)首条可读记录若sessionId或cwd不是字符串、sessionId大小写不匹配、或cwd不属于当前项目则分别抛出unknown_project/foreign_project错误sessionService.ts任一状态出现 foreign 且无任何有效身份时抛出foreign_project出现 foreign 但同时存在其他身份时抛出ambiguous_project拒绝歧义所有权最终根据 active/archived 身份的有无归约为conflict、active、archived或undefined未找到四种位置。SessionStorageEntryError定义在 sessionService.ts归档/取消归档循环中捕获reason foreign_project并归入notFound而不是返回错误。路由规则工作区限定与无工作区路由路由层面分为两类工作区限定路由workspace-qualified只变更所选受信任运行时的存储无工作区普通路由workspace-less保留既有主工作区行为。Internal Conversations 运行时仅当请求批次具有唯一无歧义的所有者时才会被选中。关键约束是运行时选择在持有生命周期协调器锁lifecycle coordinator lock期间重复执行如果 generation 已变化或不可用返回既有的可重试运行时错误而不是变更陈旧的存储stale storage。Provenance来源信息对加载与列举仍是权威依据但不再阻止对「归本工作区所有的常规 transcript」的维护——这就允许清理遗留孤儿子会话同时不使其变为可加载。从代码看resolveMaintainableSessionSnapshot的可读首条记录只要求 sessionId 与 cwd 归属当前项目而非要求记录结构完整可重建对话正是「物理所有权」与「可加载性」解耦的体现。冲突修复默认非破坏显式 resolveConflicts默认行为非破坏性的冲突错误archive 与 unarchive 保持默认的非破坏行为active/archive 冲突以「按会话错误」per-session error返回两个持久化副本都不会被移动、删除或覆盖。两个细节值得注意archive 仍会先严格关闭活动会话再分类冲突这样队列中待写入的记录有机会 flush 到 active transcript避免分类在脏数据上进行批量生命周期路由含工作区限定路由以200响应返回该结果取代此前工作区限定的409 session_conflict错误封套——冲突不再以整个请求失败的形式呈现而是体现在批量结果中的 per-sessionerrors数组里。显式修复resolveConflicts: true调用方可以发送resolveConflicts: true来显式修复冲突操作修复语义archive resolveConflicts: true保留 archived transcript移除 active transcriptunarchive resolveConflicts: true保留 active transcript移除 archived transcript响应新增resolvedConflicts数组包含被该请求修复的会话 ID。delete 保持既有兼容行为无需任何选项即移除两份副本。在 sessionService.ts 的archiveSessions实现中冲突分支location conflict在resolveConflicts缺失时直接抛出Session archive conflict: ${sessionId}开启后则先执行assertStorageUnchanged与assertCanMutate校验调用assertMaintainableSessionUnchangedsessionService.ts逐状态比对快照身份任何不一致抛出SessionTranscriptChangedError移除 active 文件并把 PR sidecar、worktree 路径、prompt ledger 等副产物一并迁移或清理将 sessionId 同时计入archived与resolvedConflicts。unarchiveSessionssessionService.ts对称处理保留 active、移除 archived并额外通过retitleIfCollidesWithActive避免归档会话的存储标题与活动会话撞名。写入者与 generation 安全维护操作在 per-session 生命周期协调器与写入者锁writer lock下运行损坏 transcript 使用同一把写入者锁但携带维护哨兵maintenance sentinel因为常规写入者证明writer proof会刻意拒绝撕裂的 JSONL哨兵不会绕过认证交接certified handoff如果写入者封存锁之后 transcript 字节发生变化接管仍以SessionTranscriptChangedError失败关闭需要操作者介入Core 在提交变更前仍会对实际 transcript 路径做快照与验证。Generation 防护共三层检查获取协调器之后、文件系统提交之前、操作完成之后各检查一次所选运行时 generation。因此即使运行时被替换也不可能把进行中的变更静默重定向到另一个运行时。测试侧SessionTranscriptChangedError与 generation fencing 的覆盖见 sessionService.corruption.test.ts 以及 sessionService.test.ts后者的resolveConflicts/resolvedConflicts用例覆盖了显式修复与替换检测。API 兼容性REST、ACP 与 SDK请求体与能力声明REST 与 ACP 的 archive/unarchive 请求体接受可选的布尔字段resolveConflicts省略该字段保留非变更的冲突行为工作区限定的 REST 传输层按上文所述在批量结果中报告冲突非布尔值属于无效请求invalid request。服务端通过session_storage_conflict_repair能力位capability通告对选项与响应字段的支持声明位于 capabilities.tssince: v1。响应字段与 SDKarchive 与 unarchive 响应新增resolvedConflictsSDK 结果类型将该字段保持为可选resolvedConflicts?: string[]使旧客户端对旧 daemon 保持兼容而新 daemon 始终返回数组——见 types.ts既有 SDK client-ID 调用形式保持有效选项通过额外的重载位置传入见 DaemonClient.ts。REST 行为验证server.test.ts 中的集成测试精确验证了契约resolveConflicts: yes字符串返回400code为invalid_request——证明非布尔值被拒绝resolveConflicts: true归档冲突会话返回200响应体为{ archived: [sid], resolvedConflicts: [sid], errors: [] }且 active 文件被移除、archived 文件保留unarchive 方向对称验证。能力位session_storage_conflict_repair也在该文件的 capability 清单server.test.ts中被断言。验证矩阵回归测试的覆盖维度回归矩阵覆盖 delete、archive、unarchive 在以下三类 transcript 上的行为empty空文件damaged损坏文件如撕裂的 JSON 头部legacy-orphan遗留孤儿其记录的 cwd 属于当前项目但父会话已不存在。测试分别运行在 Core 层、工作区限定内部路由、以及无工作区的唯一所有者路由unqualified unique-owner routing。每个成功用例都会断言最终的 active/archive 文件状态且移动操作保留原始字节。在 sessionService.corruption.test.ts 中可以看到具体形态unreadableShapes数组定义了{ name: empty, content: }与{ name: damaged, content: {uuid:torn-head }两种不可读形态对每种形态测试断言delete 后 active 文件不存在archive 后 active 消失、archived 文件内容与写入时逐字节一致fs.readFileSync(paths.archived, utf8)等于原 content证明「不重写、原样移动」冲突修复测试sessionService.corruption.test.ts分别以resolveConflicts: true验证 archive 保留 archived 内容{uuid:torn-archived、unarchive 保留 active 内容{uuid:torn-active并断言resolvedConflicts数组。兼容性测试则保留默认 archive/unarchive 冲突行为与 delete-both 行为并补充覆盖双向显式修复、外来/歧义所有权拒绝foreign_project/ambiguous_project、无效选项类型、SDK 请求体、generation fencing 与替换检测。总结设计要点一览关注点设计决策可维护性判定以「物理所有权」替代「可加载性」空/损坏/孤儿文件仍可维护所有权校验首条记录必须匹配会话 ID 且 cwd 属于当前工作区外来/歧义一律拒绝非常规条目符号链接、目录等 fail closednon_regular冲突默认行为非破坏per-session 错误两份副本均不动批量路由返回200显式修复resolveConflicts: truearchive 留归档删活动unarchive 留活动删归档写入安全维护哨兵 writer lock认证交接仍 fail closed变更前快照验证路径身份并发防护generation 在协调器获取后、提交前、完成后三处校验API 演进resolvedConflicts可选字段保持旧客户端兼容新 daemon 恒返回数组capability 通告通过「物理状态分类 显式冲突修复 写入者/ generation 双重防护」的组合该设计让会话存储的维护从「依赖完整对话」变为「依赖确定的物理所有权」为损坏与遗留数据提供了一条可安全执行的清理路径值得在同类 AI 编码代理的会话存储层中借鉴。【免费下载链接】qwen-codeAn open-source AI coding agent that lives in your terminal.项目地址: https://gitcode.com/GitHub_Trending/qw/qwen-code创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考
