OpenCode V2 模式变更日志深度解读事件溯源 Session 的持久化契约、分页语义与工具 Schema 演进【免费下载链接】opencodeThe open source coding agent.项目地址: https://gitcode.com/GitHub_Trending/openc/opencode本篇指南以 specs/v2/schema-changelog.md 为骨架完整梳理 OpenCode 项目实验性 V2 会话架构feat/opencode-embedded-api分支自 2026-06 以来每一次数据库表结构、持久化事件、HTTP 路由与生成 SDK 契约的变更。读完后你可以准确回答三类问题V2 Session 的事件溯源 投影模型到底如何存储与回放数据、GET /api/session/:sessionID/history等公开接口的分页与耗尽语义是什么、以及当 V2 事件 Schema 发生不兼容迭代时应如何重置实验数据而不影响 V1 规范数据。文档定位与适用范围原文档开篇即给出自身职责边界所有 V2 数据库、持久化事件、投影消息、HTTP 与生成 SDK 的 Schema 变更都必须记录在此处且每条记录要说明契约为何变化、消费者或已存数据是否需要兼容性处理。影响 Schema 的提交其 commit message 也应包含同样的摘要。理解本文档的前提有三点原文档明确声明后文所有条目都在此前提下解读分支前提文档覆盖的是feat/opencode-embedded-api分支自origin/dev分叉后引入的有意义的契约变更。纯文件移动和内部重构一律省略——除非它们改变了存储数据、回放行为、公开 HTTP/SDK 形态或模型侧工具契约。实验性前提V2 Session 数据在发布前始终被声明为可丢弃的实验状态disposable experimental state。当跨不兼容事件 Schema 迭代升级时正确的做法是重置实验性 V2 数据而不是做数据迁移。V1 不变前提每一次重置reset都明确声明保留规范的 V1session、message、part行。V2 与 V1 是双轨存储重置只作用于 V2 侧。从源码结构看这条双轨策略有明确落点V2 会话服务的核心接口定义在 packages/core/src/session.ts 中而 V2 的 HTTP 路由标注为 Experimental session routes.集中定义在 packages/protocol/src/groups/session.ts。近期关键变更2026-06-05 至 2026-06-261. Finite Session History有限历史分页读接口2026-06-26 的最新条目为 V2 会话新增了有限的finite历史分页读 API新增GET /api/session/:sessionID/history并生成 Promise、Effect 和 legacy JavaScript 三种客户端方法方法名分别为listHistory、listHistoryEffect、listHistoryLegacy见 packages/client/src/generated/client.ts。在**可选的排他聚合序列exclusive aggregate sequence**之后分页返回公开的持久化 Session 事件并带显式的hasMore耗尽信号。允许聚合序列出现间隙gaps、单页上限 100 个事件且原有的sessions.events()回放 尾随replay-and-tail流保持不变。无数据库迁移、无持久化事件版本变更——它只是对已有事件 manifest 的有限读接口。源码印证路由声明在 packages/protocol/src/groups/session.ts 中session.history端点响应结构为data: DurableEvent[]hasMore: booleanOpenAPI identifier 为v2.session.history与 SSE 流端点GET /api/session/:sessionID/eventv2.session.events并列。二者的定位差异正是 changelog 所述history 是一次性有限页新提交的事件会出现在后续页中而event端点是回放某序列之后的持久化事件然后持续尾随新事件。服务层接口定义在 packages/core/src/session.ts 的history方法入参after?: number 必填limit返回{ events, hasMore }与events方法返回Stream上两者并存、互不替代。hasMore的计算逻辑在 packages/core/src/event.tshasMore: rows.length input.limit——即取limit 1行探测是否还有后续超过上限即置位耗尽信号。设计含义消费端可以用after游标取本页最后一个事件的聚合序列 1做纯轮询式拉取历史无需维持长连接实时性要求高的场景则继续使用 SSE 流。两个接口共享同一份持久化事件日志语义上有限页 ⊂ 回放尾随流。2. Simplify Session Input Promotion2026-06-22围绕用户输入如何进入模型视野的事件模型做了简化保留session.next.prompt.admitted.1作为待处理 Session 输入的持久化、客户端可见记录已受理但未投给模型。用已有的session.next.prompted.1事件替换session.next.prompt.promoted.1当输入变为模型可见时只发prompted事件。保留 prompt 端点、受理回执admission receipt、幂等性、steer/queue投递顺序以及原子化的用户消息投影。配套重置实验性 V2 事件、投影、输入、Context Epoch 与同步工作区状态同时保留 V1 三张规范表。这与 06-04 的Event-Sourced Session Input Cutover呼应输入生命周期被拆成**受理admitted与晋升prompted**两个独立持久化操作steer语义在安全的 provider-turn 边界晋升queue语义按 FIFO 保持待处理直到回合自然结束。3. Reset Unpublished Compaction Event2026-06-22将未发布的session.next.compaction.ended.1事件的 payload 替换为当前 checkpoint payload并移除其遗留解码器随后重置实验性事件、序列、Session 输入、投影消息、Context Epoch、同步工作区行和 Session 工作区链接。V1 数据照常保留。这体现了 changelog 一贯的操作模式未发布unpublished事件的 payload 可以在不升版本的情况下直接改写但已发布事件只能追加式兼容。4. Make Session Interruption Process-Local2026-06-22把session.next.interrupt.requested.1从实验性持久化 Session 事件 union 和生成的 SDK 中整体移除——中断语义改为进程内process-local行为。理由在 packages/protocol/src/groups/session.ts 的session.interrupt路由描述中可以得到印证Interrupt active execution owned by this OpenCode process. Idle interruption is a no-op.。兼容性说明明确V1 数据无需迁移包含已退役事件的实验性 V2 历史直接可丢弃。5. Execute Automatic Session Compaction2026-06-05自动会话压缩从延期项变为已实现是 V2 上下文管理里信息量最大的一条触发时机在 provider turn 之前用完整估算请求 模型感知的绝对 headroom判断是否触发自动压缩。摘要契约保留既有结构化摘要契约新压缩的历史会更新此前的摘要摘要链式演进。存储方式token 有界的近期历史以纯序列化文本存进 checkpoint而不是回放 provider 原生消息。持久化边界压缩开始是持久化的、进度 delta 只是 live-only只有当持久化的完成摘要出现时才切换历史history cutover。完成事件携带当前 checkpoint payload包含稳定的消息身份、原因reason、摘要与近期上下文。续跑加载替换后的 Context Epoch在压缩完成后继续原本挂起的回合。不可失数据完整持久化历史永远保留压缩只改变活跃模型表示。明确延期provider 溢出恢复、显式手动压缩、确定性旧工具结果裁剪。对应实现位于 packages/core/src/session/compaction.ts 与 packages/core/src/session/context-epoch.ts。事件溯源输入切换2026-06-04 Event-Sourced Session Input Cutover这是 changelog 中篇幅最重的单条变更理解它是理解整个 V2 存储模型的关键受影响 Schemasession_input、session_message、event、event_sequence表以及可丢弃的工作区 beta 存储。新的同步事件session.next.prompt.admitted.1与后来被退役的session.next.prompt.promoted.1。实验性SessionV2.prompt(...)、HTTP 与生成 SDK 的受理回执。变更内容用事件溯源的 prompt 受理/晋升序列替换inbox 本地的受理序列。投影 Session 消息获得稳定的msg_*资源 ID与创建者事件 IDevt_*区分开。每一个创建投影 transcript 资源的事件都携带显式msg_*资源 IDassistant 步骤通过assistantMessageID在 assistant 拥有的各事件间传播同一身份。兼容性处理可操作要点重置保留 V1 的session、message、part行。已同步的工作区属于可丢弃 beta 状态由重置删除。启动新构建前先丢弃由未发布构建创建的、adapter 管理的外部工作区资源——因为 SQL 迁移无法通过运行时 adapter 删除外部资源且启动后重新发现残留资源可能回放不兼容的 beta 历史。精确的 prompt 重试在 Session、prompt 与投递模式三者一致时协调到同一个稳定的msg_*身份幂等。分支早期历史Earlier Branch History可回放 Session 事件精炼与游标流受影响 Schemapackages/core/src/session/event.ts中已有的session.next.*事件族、packages/core/src/session/message.ts中已有的 V2 投影消息 union、以及sessions.events({ sessionID, after? })返回的显式持久化事件 union 与内部回放游标。变更保留既有 Session 生命周期事件族与投影消息 union而非在本分支引入它们。停止同步文本 delta、推理 delta 与工具输入 delta——这些片段fragment被明确声明为 ephemeral。为回放安全的消费者新增显式持久化事件 union。新增由持久化 Session 事件序列支撑的回放 尾随聚合游标。在写入 JSON 存储前编码、回放时解码同步事件 payload使 Schema 转换显式地发生在持久化边界。动机嵌入式 Session 执行需要基于持久化日志的断线重连安全回放流外加按时间顺序的派生读模型片段流对在线渲染器有用但不得推进持久化游标也不得膨胀同步存储。兼容性session.next.*事件族早于本分支存在本分支只是精炼其 V2 持久化与回放契约持久化回放游标是每聚合的事件序列ephemeral delta 在重连后有意缺失。持久化 Step 结算归属Durable Step Settlement Ownershipsession.next.step.ended与session.next.step.failed的同步事件版本升到2step 结算绑定到显式的 assistant 消息 ID。原因provider 本地的 call 标识符可能在多个回合间重复。因为持久化 payload 变化同步事件必须升版本。持久化 Session 输入收件箱Durable Session Input Inbox新表session_input迁移20260603141458_session_input_inbox.tspending 索引由20260603160727_jittery_ezekiel_stane.ts更新新增SessionInput.AdmittedSchema 与Prompted.delivery字段。收件箱持久化字段自增 inbox 序列、唯一消息 ID、Session ID、编码后的 prompt、steer/queue投递模式、可选的晋升事件序列、创建时间索引按 Session、晋升状态、投递模式与受理序列组织。原因prompt 受理与模型可见晋升必须是两个独立的持久化操作steer 必须在安全 provider-turn 边界晋升queued prompt 按 FIFO 保持 pending。兼容性迁移创建 inbox 表并替换首个 pending 索引为感知投递模式的索引精确 prompt 重试幂等复用消息 ID 但输入不同会失败对应源码中的PromptConflictError定义见 packages/core/src/session.ts。持久化 Session 投影顺序Durable Session Projection Ordersession_message.seq来自20260603040000_session_message_projection_order.ts及一系列事件/消息索引。重置发布前的 Session 消息投影为新生成的同步事件加seq新增事件聚合序列、聚合类型序列索引以及消息序列、类型序列与兼容时间戳索引。原因投影历史、回放、压缩查找与分页必须跟随持久化聚合顺序而不是时间戳或调用方生成的 IDRunner 与 HTTP 读路径需要覆盖具体查询形态的 covering index。兼容性发布前的投影因可能在没有持久化创建者事件的情况下被写入而可丢弃迁移直接重置而不阻塞启动时间戳索引保留给遗留/过渡查询形态。结构化工具注册表与规范输出Structured Tool Registry And Canonical OutputCore 自有的类型化工具注册表契约、规范工具输出内容与结构化结算 Schemaopencode-ai/llm中标记化的工具文件源inline 数据 / 远程 URL / 托管文件 URI替代一个含义模糊的 URI 字符串。变更对模型输入按注册工具参数 Schema 校验对 handler 成功结果按 success Schema 校验后再做可选的纯模型输出降级从类型化 success Schema 生成可选的 output JSON Schema对运行中、完成与失败的工具都持久化规范结构化输出与内容。兼容性属追加式实验性 V2 运行时契约工具结果在 provider 续跑前必须持久化结算遗留文本/JSON/内联媒体结果仍可转换未解析的 URL 与文件源必须在 provider 降级前被物化或显式拒绝。托管工具输出文件Managed Tool-Output Files工具结果与完成的 Session 工具状态上新增可选outputPath/outputPaths普通read、grep输入接受绝对托管输出路径。超大模型侧工具文本被溢出spill到 OpenCode 共享工具输出目录下的全局唯一文件有界预览中包含该文件的绝对路径从而普通read、grep、bash都能检查完整内容。设计权衡模型上下文必须有界但不能丢完整输出文件系统的解析只接受托管目录中直接生成的tool_*文件权限白名单恰好覆盖该目录与 packages/core/src/tool-output-store.ts 的托管输出存储对应。托管输出按有界期限保留暴露为普通宿主文件系统路径。Location 作用域的只读与检索契约核心文件系统读、目录列举、根解析、命名引用输入LocationSearch.FilesInput、LocationSearch.GrepInput与有界结果 Schemaread、glob、grep工具参数与成功 payload。变更有界文件读、分页目录列举、有界 glob 结果、带行预览的有界 grep 匹配命名项目引用仅限只读操作遍历前解析并固定pin已批准的规范检索根宽泛 V2 glob/grep 发现默认排除隐藏路径段。兼容性属追加式 V2 工具契约隐藏文件发现有意比无条件的 ripgrep--hidden遍历更窄。Location 工作区身份Location Workspace IdentityLocation.Ref.workspaceID从无类型字符串变为WorkspaceV2.ID品牌类型V2 Location HTTP 中间件保持location[workspace]嵌套与 workspace header 两种路由输入但解码到同一品牌身份。兼容性满足 workspace ID Schema 的既有 workspace 字符串继续被接受生成的 OpenAPI 体现 workspace 前缀约束。结构化变更权限与文件叶子Structured Mutation Authority And File Leaves新增LocationMutation.ResolveInput、计划目标、外部目录授权与类型化路径错误新增write与精确edit工具 Schema 及内部文件变更提交服务。变更相对变更路径在活跃 Location 内解析内部绝对路径直接接受外部绝对路径必须显式external_directory批准后才能进入叶子批准命名引用只读、拒绝用于变更写机制执行前立即重验路径权限防 symlink/路径切换。动机变更工具需要显式的能力升级与符号链接/路径交换检查而不是假装路径 API 提供了系统调用级沙箱。兼容性追加式 V2 变更契约更丰富的 V1 模糊编辑行为有意延期。V2 权限请求与已保存规则V2 Permission Requests And Saved RulesPermissionV2.Request、AssertInput、ReplyInput、源元数据、标记错误与生命周期事件V2 权限列表/回复/已保存规则的 HTTP 路由与生成 SDK Schema。变更Location 作用域的挂起权限请求支持once、always、reject三种回复可附带来源工具消息与 call ID作者编写的有序规则与已保存批准作为评估的两个独立输入保留为read、glob、grep、edit、external_directory、bash、todowrite、webfetch建立动作与资源约定。原因嵌入式工具调用需要 Core 自有的授权边界能够经 HTTP 挂起与恢复。兼容性追加式实验契约策略作者应关注规范资源形态来源工具元数据在每个注册表调用都携带持久化 assistant 拥有者之前保持可选。初始 Core V2 内置工具 Schema、Bash 警告与后续工具内置工具集read、glob、grep、write、精确edit、bash、websearch——Core 自有的 Location 作用域内置工具带显式参数与 success Schemabash 输出与超时、搜索结果数与预览、读取大小、目录页、websearch 结果/上下文控制全部有界。apply_patch顺序提交、add-only 语义、预检后不可中断、skill{ name: string }选择返回 V1 形态的skill_content name...输出、todowriteSessionTodo.Info替换列表、question有序QuestionV2.Prompt 有序答案数组、webfetchtext/markdown/html显式格式、有界超时、可选托管输出元数据都是同样的追加式 Location 作用域 V2 内置工具模式且都不需要数据库迁移或公共 HTTP API 迁移。Bash Advisory Warningsbash 成功 payload 新增可选warnings——尽力而为的命令参数扫描发现外部绝对路径时返回建议性警告字符串但结构化的外部workdir批准仍然强制执行。理由很诚实shell 子进程拥有宿主用户的文件系统、进程与网络权限token 扫描无法诚实地提供隔离。消费端渲染 bash 成功时应容忍可选警告字符串。Bash 背景执行延期2026-06-03移除bash工具的可选background参数与进程内背景结算形态保留内部BackgroundJob原型。原因是模型没有注册的背景任务观察/取消工具进程内状态不构成充分的远程契约只有当持久化状态观察、完成投递与显式取消语义齐备时才重新引入。Bash Description 输入移除2026-06-18删除 V1 必填、V2 可选的description参数shell 展示从命令本身或通用 shell 标签派生。既有持久化 tool call 可能仍含description但新工具定义不再暴露或要求它执行行为不变。V2 Session HTTP 与生成 SDK 契约V2 Session 的 list、prompt、context、message-list、compact、wait 路由以及 V2 Location 查询路由字段与生成的 OpenAPI/JavaScript SDK。prompt 端点接受可选id幂等、deliverysteer/queue与resume持久受理但不立即执行字段消息游标保持不透明opaqueSDK 客户端同时保留遗留扁平location与嵌套location[...]查询参数两种路由形态。兼容性要点prompt 受理现在返回受理后的 user 形态消息一个消息 ID 被不同输入复用时返回冲突错误。分页与目录Catalog契约修正持久化 Session 消息分页2026-06-03内部SessionV2.messages()游标输入与GET /api/session/:sessionID/message返回的不透明游标 payload 中移除墙钟time游标内投影消息id解析到存储的session_message.seq分页边界与排序一律按每 Session 持久化seq而非time_created id。原因投影 V2 消息的时间顺序由同步 Session 事件顺序定义墙钟时间戳可能碰撞或回拨不是安全的分页边界list 端点必须与已经按持久化序列排序的回放和上下文加载保持一致。兼容性无需数据库迁移session_message.seq与会话作用域索引已存在HTTP 游标保持不透明既有游标仍可用它们本就携带投影消息id解码时忽略多余的time无需 OpenAPI 或生成 SDK 变更。公共 Provider 与模型目录 DTO2026-06-03GET /api/provider、GET /api/provider/:providerID、GET /api/model的响应替换为显式公共 DTO生成的ProviderV2PublicInfo与ModelV2PublicInfo。从公共响应中移除provider 请求头与请求体、API 设置、自定义启用数据、模型请求覆写、变体请求覆写。原因内部目录记录可能包含凭据或 provider 特定的请求材料不得跨越公共 HTTP 序列化边界。公共 V2 目录响应有意暴露更少字段内部 Schema 仍对运行时可用。回放元数据与投影所有权持久化推理与托管工具回放元数据2026-06-03持久化session.next.reasoning.started/ended事件新增可选providerMetadatasession.next.tool.success/failed事件新增可选持久化result并投影进结算工具消息状态。投影的 tool-call 元数据与可选结算结果元数据分开保存只在历史 assistant 模型与续跑所选模型一致时回放 provider 原生推理与工具元数据。原因provider 续跑需要后续回合携带签名/加密的推理元数据provider 执行的托管工具结果必须幸存投影使回放能把托管调用与结果内联保留在 assistant 内容中恢复结算不得抹掉重建有效续跑请求所需的 provider 原生 call 元数据。兼容性新增持久化事件字段均为可选先前记录的实验事件仍可解码OpenAI Responses 把重建的 provider 执行托管结果降级为存储项引用而非拒绝 assistant 历史Bedrock Converse 签名、GeminithoughtSignature、OpenAI 兼容 Chatreasoning_content现在都能经规范续跑 part 往返。投影 assistant 所有权与全值 Part2026-06-03投影 assistant 文本 part 保留稳定 ID持久化工具投影更新通过显式拥有者 assistant 消息 ID 路由而不是仅靠 provider 本地 call ID回放**全值full-value**的文本与工具输入终点 checkpoint片段 delta 仍为 ephemeral。原因provider 本地工具 call ID 可能跨回合重复持久化投影重建不能依赖重连后消失的 ephemeral 片段。兼容性早期无稳定文本 ID 的实验投影 assistant 行不假设回放兼容当前 V2 历史一律从持久化全值 checkpoint 重建。上下文纪元Context Epoch演进三部曲这三条是 V2 系统上下文管理的完整演进链建议按顺序阅读1. Add Durable Session Context Snapshots2026-06-04新表session_context_epoch每 Session 一个活跃不可变基线字符串、结构化 JSON 快照与基线序列。在首个安全 provider-turn 边界惰性初始化一个持久化 Context Epoch 快照纪元内每个 provider turn 通过LLMRequest.system下发其精确基线字符串重启或生产者变化后逐字复用存储基线而不是重新采样特权初始上下文后续观察与可覆写的编解码结构化快照而非渲染文本哈希比较受理的按时间顺序上下文作为一等systemSession 消息暴露。兼容性未发布的 Context Epoch Schema 合并进单个数据库迁移基线与结构化快照是运维状态而非同步事件历史。2. Admit Chronological Session Context Updates2026-06-04新同步事件session.next.context.updated.1携带持久化 System 消息 ID 与精确合并后的模型可见文本session_context_epoch.revision用于事务性结构化快照推进一等systemSession 消息投影。每个安全 provider-turn 边界用一个一致观察调和 Location 作用域 Context Source存储基线保持不可变变化源渲染作为按时间顺序的Message.system(...)历史受理结构化快照与渲染 System 消息事件原子推进源被移除时发出此前存储的模型意义移除渲染拒绝会把本地工具调用与其结果割裂到不同 provider 协议两侧的按时间顺序 system 更新Anthropic 原生 system 更新位置不受支持时使用包装 user 回退。兼容性同步事件日志只保留模型实际看到的文本不保留内部结构化快照。3. Replace Session Context Epochs Lazily2026-06-04→ Simplify Session Context Rebaselining2026-06-22惰性替换阶段模型切换或压缩完成后标记活跃 Context Epoch 为待替换session_context_epoch.replacement_seq可空持久化触发聚合序列使同目标回放不会重开已结算的替换新基线在下一个安全边界惰性渲染覆写组装活跃 provider 历史时排除旧纪元的按时间顺序 System 消息。2026-06-22 的简化是对其回滚式重构删除session_context_epoch.agent、replacement_seq、revision三列每个 provider turn 只采样一次有效 agent 与模型选择变化对下一 turn 生效压缩完成后直接重建基线而非维护挂起替换状态后压缩基线无法完整渲染时保留旧基线及其按时间顺序更新依赖进程内 Session 执行 lane而非 Context Epoch 写者间的乐观并发状态。兼容性既有 Context Epoch 行原地迁移丢弃废弃的选择与挂起替换列模型与 agent 切换不再通过强制新基线丢弃早前的按时间顺序 System 上下文更新。配套的 2026-06-05 两条补齐了生产侧Register Ambient System Context ProducersLocation 作用域的稳定键上下文生产者注册表替换 Session 专属加载器独立注册环境/日期与 ambient 指令生产者并按稳定贡献键顺序并发评估每个安全边界直接发现并读取全局与向上项目AGENTS.md任一上下文源不可用时阻塞首纪元初始化Session 移动时清空活跃纪元并在目标 Location 初始化完整基线以权威 Session Location 对纪元初始化做 fence防止并发的旧 Location runner 重建陈旧的特权上下文与Admit Selected-Agent Skill Guidancesession_context_epoch.agent记录基线所属有效 agent选定 agent 的技能指导经权限过滤后与 Location 级 System Context 组合再进纪元受理技能正文仍留在权限检查的skill工具后缺失技能错误不再枚举未过滤目录agent 切换后请求纪元替换并跨 agent 阻止在替换上下文不可用期间的 provider turn。其余契约条目速览Location 作用域 V2 Questions2026-06-03新增QuestionV2.*域 Schema、question.v2.asked/replied/rejected事件、GET /api/question/request与POST /api/session/:sessionID/question/request/:requestID/reply|reject路由。嵌入式 V2 工具执行需要 Location 拥有的挂起问题服务其挂起回复可经 HTTP 结算。无需数据库迁移——挂起问题有意是内存态 Location 状态。Core 自有 Todo 更新事件2026-06-03从 Core session-todo 所有权注册全局todo.updated事件向 Core V2 工具暴露既有 todo 项形态todo 表与公共事件形态不变无迁移。条件文件变更陈旧错误2026-06-03内部新增FileMutation.StaleContentError标记错误——已批准的精确编辑在提交时不再匹配字节时携带变更目标路径的类型化错误。V2 精确编辑必须失败而不是在权限批准后陈旧覆盖并发协作写入纯内部追加契约无数据库/HTTP/SDK 变更。Provider 流看门狗策略延期2026-06-03不施加通用的 provider 流不活跃或绝对超时移除内部超时错误与硬编码看门狗服务超时、重试、看门狗、持久化失败报告与 drain 链释放策略整体延期到可配置的设计切片。理由V1 本就没有通用处理器不活跃看门狗不同 provider 与自主负载的运行时特征不同硬编码默认值为时过早。键控合并持久化尾信号2026-06-03把进程全局无界聚合 ID PubSub 替换为每活跃尾 聚合一个滑动容量 1 的 dirty 信号历史 SQLite 回放前订阅注册、尾关闭时移除每次 dirty 边之后重查持久化行并只按持久化聚合序列推进。唤醒通知是建议性边而非持久化事件 payload慢消费者不应为一次 SQLite 查询就能恢复全部已提交行而保留无界冗余唤醒 ID。sessions.events({ sessionID, after? })语义不变。嵌入式本地工具恢复对齐2026-06-03Session 省略显式 agent 时权限按默认buildagent 评估与 provider-turn 执行一致组装 provider 请求前把上一个进程遗留、仍投影为running的本地工具用既有session.next.tool.failed形态与Tool execution interrupted消息持久化失败。原因无 agent 的嵌入式 Session 以前按build执行却用空权限规则集评估首个本地工具可能永远等待一个本地表面不存在的批准面进程在本地工具运行中丢失会留下悬空 tool call使后续 provider 续跑无效——恢复必须结算持久化投影而不重放被放弃的副作用。Pre-PR V2 安全评审2026-06-03对聚合 ID 与解码同步 payload 不一致的回放封套加 fence回放首次采纳无主聚合时持久化 owner 声明续跑前持久化结算被放弃的本地与 provider 执行工具apply_patch的 add hunk 采用 create-only 语义、预检后顺序提交不可中断、急切拒绝畸形 patch 语法skill内置物化前等待初始插件启动provider/model 公共 API URL 剥离凭据、query 与 fragmentV2 请求体在生成的 OpenAPI 与 SDK 类型中保持必填。兼容性要点pre-launch 的session.next.*数据库仍是可丢弃实验状态V1 把抓取图片作为附件返回而首个 Core V2 类型化结算是纯文本的因此 V2 继续拒绝抓取的图片等非文本文件直到附件结算被显式设计。阅读与实操建议消费 V2 历史数据轮询式用GET /api/session/:sessionID/historyafter排他序列 页上限 100 hasMore耗尽信号实时渲染用 SSE 的GET /api/session/:sessionID/event。两者读同一份持久化日志序列间隙是合法的。升级跨不兼容事件 Schema 迭代按 changelog 的一致性结论操作——重置实验性 V2 事件/投影/输入/纪元/同步工作区状态启动前清理 adapter 管理的外部工作区资源V1session/message/part行不动。写 V2 工具或权限策略以追加式、有界、Core 自有为基调——每个工具都有显式参数与 success Schema变更操作必须走external_directory显式授权与提交前重验bash 的宿主权限只能靠建议性警告提示而不可宣称隔离。提交影响 Schema 的变更在本 changelog 增加一条记录写清受影响 Schema、变更、原因与兼容性并在 commit message 中附同样摘要——这是该文件自身声明的维护纪律。【免费下载链接】opencodeThe open source coding agent.项目地址: https://gitcode.com/GitHub_Trending/openc/opencode创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考
OpenCode V2 模式变更日志深度解读事件溯源 Session 的持久化契约、分页语义与工具 Schema 演进【免费下载链接】opencodeThe open source coding agent.项目地址: https://gitcode.com/GitHub_Trending/openc/opencode本篇指南以 specs/v2/schema-changelog.md 为骨架完整梳理 OpenCode 项目实验性 V2 会话架构feat/opencode-embedded-api分支自 2026-06 以来每一次数据库表结构、持久化事件、HTTP 路由与生成 SDK 契约的变更。读完后你可以准确回答三类问题V2 Session 的事件溯源 投影模型到底如何存储与回放数据、GET /api/session/:sessionID/history等公开接口的分页与耗尽语义是什么、以及当 V2 事件 Schema 发生不兼容迭代时应如何重置实验数据而不影响 V1 规范数据。文档定位与适用范围原文档开篇即给出自身职责边界所有 V2 数据库、持久化事件、投影消息、HTTP 与生成 SDK 的 Schema 变更都必须记录在此处且每条记录要说明契约为何变化、消费者或已存数据是否需要兼容性处理。影响 Schema 的提交其 commit message 也应包含同样的摘要。理解本文档的前提有三点原文档明确声明后文所有条目都在此前提下解读分支前提文档覆盖的是feat/opencode-embedded-api分支自origin/dev分叉后引入的有意义的契约变更。纯文件移动和内部重构一律省略——除非它们改变了存储数据、回放行为、公开 HTTP/SDK 形态或模型侧工具契约。实验性前提V2 Session 数据在发布前始终被声明为可丢弃的实验状态disposable experimental state。当跨不兼容事件 Schema 迭代升级时正确的做法是重置实验性 V2 数据而不是做数据迁移。V1 不变前提每一次重置reset都明确声明保留规范的 V1session、message、part行。V2 与 V1 是双轨存储重置只作用于 V2 侧。从源码结构看这条双轨策略有明确落点V2 会话服务的核心接口定义在 packages/core/src/session.ts 中而 V2 的 HTTP 路由标注为 Experimental session routes.集中定义在 packages/protocol/src/groups/session.ts。近期关键变更2026-06-05 至 2026-06-261. Finite Session History有限历史分页读接口2026-06-26 的最新条目为 V2 会话新增了有限的finite历史分页读 API新增GET /api/session/:sessionID/history并生成 Promise、Effect 和 legacy JavaScript 三种客户端方法方法名分别为listHistory、listHistoryEffect、listHistoryLegacy见 packages/client/src/generated/client.ts。在**可选的排他聚合序列exclusive aggregate sequence**之后分页返回公开的持久化 Session 事件并带显式的hasMore耗尽信号。允许聚合序列出现间隙gaps、单页上限 100 个事件且原有的sessions.events()回放 尾随replay-and-tail流保持不变。无数据库迁移、无持久化事件版本变更——它只是对已有事件 manifest 的有限读接口。源码印证路由声明在 packages/protocol/src/groups/session.ts 中session.history端点响应结构为data: DurableEvent[]hasMore: booleanOpenAPI identifier 为v2.session.history与 SSE 流端点GET /api/session/:sessionID/eventv2.session.events并列。二者的定位差异正是 changelog 所述history 是一次性有限页新提交的事件会出现在后续页中而event端点是回放某序列之后的持久化事件然后持续尾随新事件。服务层接口定义在 packages/core/src/session.ts 的history方法入参after?: number 必填limit返回{ events, hasMore }与events方法返回Stream上两者并存、互不替代。hasMore的计算逻辑在 packages/core/src/event.tshasMore: rows.length input.limit——即取limit 1行探测是否还有后续超过上限即置位耗尽信号。设计含义消费端可以用after游标取本页最后一个事件的聚合序列 1做纯轮询式拉取历史无需维持长连接实时性要求高的场景则继续使用 SSE 流。两个接口共享同一份持久化事件日志语义上有限页 ⊂ 回放尾随流。2. Simplify Session Input Promotion2026-06-22围绕用户输入如何进入模型视野的事件模型做了简化保留session.next.prompt.admitted.1作为待处理 Session 输入的持久化、客户端可见记录已受理但未投给模型。用已有的session.next.prompted.1事件替换session.next.prompt.promoted.1当输入变为模型可见时只发prompted事件。保留 prompt 端点、受理回执admission receipt、幂等性、steer/queue投递顺序以及原子化的用户消息投影。配套重置实验性 V2 事件、投影、输入、Context Epoch 与同步工作区状态同时保留 V1 三张规范表。这与 06-04 的Event-Sourced Session Input Cutover呼应输入生命周期被拆成**受理admitted与晋升prompted**两个独立持久化操作steer语义在安全的 provider-turn 边界晋升queue语义按 FIFO 保持待处理直到回合自然结束。3. Reset Unpublished Compaction Event2026-06-22将未发布的session.next.compaction.ended.1事件的 payload 替换为当前 checkpoint payload并移除其遗留解码器随后重置实验性事件、序列、Session 输入、投影消息、Context Epoch、同步工作区行和 Session 工作区链接。V1 数据照常保留。这体现了 changelog 一贯的操作模式未发布unpublished事件的 payload 可以在不升版本的情况下直接改写但已发布事件只能追加式兼容。4. Make Session Interruption Process-Local2026-06-22把session.next.interrupt.requested.1从实验性持久化 Session 事件 union 和生成的 SDK 中整体移除——中断语义改为进程内process-local行为。理由在 packages/protocol/src/groups/session.ts 的session.interrupt路由描述中可以得到印证Interrupt active execution owned by this OpenCode process. Idle interruption is a no-op.。兼容性说明明确V1 数据无需迁移包含已退役事件的实验性 V2 历史直接可丢弃。5. Execute Automatic Session Compaction2026-06-05自动会话压缩从延期项变为已实现是 V2 上下文管理里信息量最大的一条触发时机在 provider turn 之前用完整估算请求 模型感知的绝对 headroom判断是否触发自动压缩。摘要契约保留既有结构化摘要契约新压缩的历史会更新此前的摘要摘要链式演进。存储方式token 有界的近期历史以纯序列化文本存进 checkpoint而不是回放 provider 原生消息。持久化边界压缩开始是持久化的、进度 delta 只是 live-only只有当持久化的完成摘要出现时才切换历史history cutover。完成事件携带当前 checkpoint payload包含稳定的消息身份、原因reason、摘要与近期上下文。续跑加载替换后的 Context Epoch在压缩完成后继续原本挂起的回合。不可失数据完整持久化历史永远保留压缩只改变活跃模型表示。明确延期provider 溢出恢复、显式手动压缩、确定性旧工具结果裁剪。对应实现位于 packages/core/src/session/compaction.ts 与 packages/core/src/session/context-epoch.ts。事件溯源输入切换2026-06-04 Event-Sourced Session Input Cutover这是 changelog 中篇幅最重的单条变更理解它是理解整个 V2 存储模型的关键受影响 Schemasession_input、session_message、event、event_sequence表以及可丢弃的工作区 beta 存储。新的同步事件session.next.prompt.admitted.1与后来被退役的session.next.prompt.promoted.1。实验性SessionV2.prompt(...)、HTTP 与生成 SDK 的受理回执。变更内容用事件溯源的 prompt 受理/晋升序列替换inbox 本地的受理序列。投影 Session 消息获得稳定的msg_*资源 ID与创建者事件 IDevt_*区分开。每一个创建投影 transcript 资源的事件都携带显式msg_*资源 IDassistant 步骤通过assistantMessageID在 assistant 拥有的各事件间传播同一身份。兼容性处理可操作要点重置保留 V1 的session、message、part行。已同步的工作区属于可丢弃 beta 状态由重置删除。启动新构建前先丢弃由未发布构建创建的、adapter 管理的外部工作区资源——因为 SQL 迁移无法通过运行时 adapter 删除外部资源且启动后重新发现残留资源可能回放不兼容的 beta 历史。精确的 prompt 重试在 Session、prompt 与投递模式三者一致时协调到同一个稳定的msg_*身份幂等。分支早期历史Earlier Branch History可回放 Session 事件精炼与游标流受影响 Schemapackages/core/src/session/event.ts中已有的session.next.*事件族、packages/core/src/session/message.ts中已有的 V2 投影消息 union、以及sessions.events({ sessionID, after? })返回的显式持久化事件 union 与内部回放游标。变更保留既有 Session 生命周期事件族与投影消息 union而非在本分支引入它们。停止同步文本 delta、推理 delta 与工具输入 delta——这些片段fragment被明确声明为 ephemeral。为回放安全的消费者新增显式持久化事件 union。新增由持久化 Session 事件序列支撑的回放 尾随聚合游标。在写入 JSON 存储前编码、回放时解码同步事件 payload使 Schema 转换显式地发生在持久化边界。动机嵌入式 Session 执行需要基于持久化日志的断线重连安全回放流外加按时间顺序的派生读模型片段流对在线渲染器有用但不得推进持久化游标也不得膨胀同步存储。兼容性session.next.*事件族早于本分支存在本分支只是精炼其 V2 持久化与回放契约持久化回放游标是每聚合的事件序列ephemeral delta 在重连后有意缺失。持久化 Step 结算归属Durable Step Settlement Ownershipsession.next.step.ended与session.next.step.failed的同步事件版本升到2step 结算绑定到显式的 assistant 消息 ID。原因provider 本地的 call 标识符可能在多个回合间重复。因为持久化 payload 变化同步事件必须升版本。持久化 Session 输入收件箱Durable Session Input Inbox新表session_input迁移20260603141458_session_input_inbox.tspending 索引由20260603160727_jittery_ezekiel_stane.ts更新新增SessionInput.AdmittedSchema 与Prompted.delivery字段。收件箱持久化字段自增 inbox 序列、唯一消息 ID、Session ID、编码后的 prompt、steer/queue投递模式、可选的晋升事件序列、创建时间索引按 Session、晋升状态、投递模式与受理序列组织。原因prompt 受理与模型可见晋升必须是两个独立的持久化操作steer 必须在安全 provider-turn 边界晋升queued prompt 按 FIFO 保持 pending。兼容性迁移创建 inbox 表并替换首个 pending 索引为感知投递模式的索引精确 prompt 重试幂等复用消息 ID 但输入不同会失败对应源码中的PromptConflictError定义见 packages/core/src/session.ts。持久化 Session 投影顺序Durable Session Projection Ordersession_message.seq来自20260603040000_session_message_projection_order.ts及一系列事件/消息索引。重置发布前的 Session 消息投影为新生成的同步事件加seq新增事件聚合序列、聚合类型序列索引以及消息序列、类型序列与兼容时间戳索引。原因投影历史、回放、压缩查找与分页必须跟随持久化聚合顺序而不是时间戳或调用方生成的 IDRunner 与 HTTP 读路径需要覆盖具体查询形态的 covering index。兼容性发布前的投影因可能在没有持久化创建者事件的情况下被写入而可丢弃迁移直接重置而不阻塞启动时间戳索引保留给遗留/过渡查询形态。结构化工具注册表与规范输出Structured Tool Registry And Canonical OutputCore 自有的类型化工具注册表契约、规范工具输出内容与结构化结算 Schemaopencode-ai/llm中标记化的工具文件源inline 数据 / 远程 URL / 托管文件 URI替代一个含义模糊的 URI 字符串。变更对模型输入按注册工具参数 Schema 校验对 handler 成功结果按 success Schema 校验后再做可选的纯模型输出降级从类型化 success Schema 生成可选的 output JSON Schema对运行中、完成与失败的工具都持久化规范结构化输出与内容。兼容性属追加式实验性 V2 运行时契约工具结果在 provider 续跑前必须持久化结算遗留文本/JSON/内联媒体结果仍可转换未解析的 URL 与文件源必须在 provider 降级前被物化或显式拒绝。托管工具输出文件Managed Tool-Output Files工具结果与完成的 Session 工具状态上新增可选outputPath/outputPaths普通read、grep输入接受绝对托管输出路径。超大模型侧工具文本被溢出spill到 OpenCode 共享工具输出目录下的全局唯一文件有界预览中包含该文件的绝对路径从而普通read、grep、bash都能检查完整内容。设计权衡模型上下文必须有界但不能丢完整输出文件系统的解析只接受托管目录中直接生成的tool_*文件权限白名单恰好覆盖该目录与 packages/core/src/tool-output-store.ts 的托管输出存储对应。托管输出按有界期限保留暴露为普通宿主文件系统路径。Location 作用域的只读与检索契约核心文件系统读、目录列举、根解析、命名引用输入LocationSearch.FilesInput、LocationSearch.GrepInput与有界结果 Schemaread、glob、grep工具参数与成功 payload。变更有界文件读、分页目录列举、有界 glob 结果、带行预览的有界 grep 匹配命名项目引用仅限只读操作遍历前解析并固定pin已批准的规范检索根宽泛 V2 glob/grep 发现默认排除隐藏路径段。兼容性属追加式 V2 工具契约隐藏文件发现有意比无条件的 ripgrep--hidden遍历更窄。Location 工作区身份Location Workspace IdentityLocation.Ref.workspaceID从无类型字符串变为WorkspaceV2.ID品牌类型V2 Location HTTP 中间件保持location[workspace]嵌套与 workspace header 两种路由输入但解码到同一品牌身份。兼容性满足 workspace ID Schema 的既有 workspace 字符串继续被接受生成的 OpenAPI 体现 workspace 前缀约束。结构化变更权限与文件叶子Structured Mutation Authority And File Leaves新增LocationMutation.ResolveInput、计划目标、外部目录授权与类型化路径错误新增write与精确edit工具 Schema 及内部文件变更提交服务。变更相对变更路径在活跃 Location 内解析内部绝对路径直接接受外部绝对路径必须显式external_directory批准后才能进入叶子批准命名引用只读、拒绝用于变更写机制执行前立即重验路径权限防 symlink/路径切换。动机变更工具需要显式的能力升级与符号链接/路径交换检查而不是假装路径 API 提供了系统调用级沙箱。兼容性追加式 V2 变更契约更丰富的 V1 模糊编辑行为有意延期。V2 权限请求与已保存规则V2 Permission Requests And Saved RulesPermissionV2.Request、AssertInput、ReplyInput、源元数据、标记错误与生命周期事件V2 权限列表/回复/已保存规则的 HTTP 路由与生成 SDK Schema。变更Location 作用域的挂起权限请求支持once、always、reject三种回复可附带来源工具消息与 call ID作者编写的有序规则与已保存批准作为评估的两个独立输入保留为read、glob、grep、edit、external_directory、bash、todowrite、webfetch建立动作与资源约定。原因嵌入式工具调用需要 Core 自有的授权边界能够经 HTTP 挂起与恢复。兼容性追加式实验契约策略作者应关注规范资源形态来源工具元数据在每个注册表调用都携带持久化 assistant 拥有者之前保持可选。初始 Core V2 内置工具 Schema、Bash 警告与后续工具内置工具集read、glob、grep、write、精确edit、bash、websearch——Core 自有的 Location 作用域内置工具带显式参数与 success Schemabash 输出与超时、搜索结果数与预览、读取大小、目录页、websearch 结果/上下文控制全部有界。apply_patch顺序提交、add-only 语义、预检后不可中断、skill{ name: string }选择返回 V1 形态的skill_content name...输出、todowriteSessionTodo.Info替换列表、question有序QuestionV2.Prompt 有序答案数组、webfetchtext/markdown/html显式格式、有界超时、可选托管输出元数据都是同样的追加式 Location 作用域 V2 内置工具模式且都不需要数据库迁移或公共 HTTP API 迁移。Bash Advisory Warningsbash 成功 payload 新增可选warnings——尽力而为的命令参数扫描发现外部绝对路径时返回建议性警告字符串但结构化的外部workdir批准仍然强制执行。理由很诚实shell 子进程拥有宿主用户的文件系统、进程与网络权限token 扫描无法诚实地提供隔离。消费端渲染 bash 成功时应容忍可选警告字符串。Bash 背景执行延期2026-06-03移除bash工具的可选background参数与进程内背景结算形态保留内部BackgroundJob原型。原因是模型没有注册的背景任务观察/取消工具进程内状态不构成充分的远程契约只有当持久化状态观察、完成投递与显式取消语义齐备时才重新引入。Bash Description 输入移除2026-06-18删除 V1 必填、V2 可选的description参数shell 展示从命令本身或通用 shell 标签派生。既有持久化 tool call 可能仍含description但新工具定义不再暴露或要求它执行行为不变。V2 Session HTTP 与生成 SDK 契约V2 Session 的 list、prompt、context、message-list、compact、wait 路由以及 V2 Location 查询路由字段与生成的 OpenAPI/JavaScript SDK。prompt 端点接受可选id幂等、deliverysteer/queue与resume持久受理但不立即执行字段消息游标保持不透明opaqueSDK 客户端同时保留遗留扁平location与嵌套location[...]查询参数两种路由形态。兼容性要点prompt 受理现在返回受理后的 user 形态消息一个消息 ID 被不同输入复用时返回冲突错误。分页与目录Catalog契约修正持久化 Session 消息分页2026-06-03内部SessionV2.messages()游标输入与GET /api/session/:sessionID/message返回的不透明游标 payload 中移除墙钟time游标内投影消息id解析到存储的session_message.seq分页边界与排序一律按每 Session 持久化seq而非time_created id。原因投影 V2 消息的时间顺序由同步 Session 事件顺序定义墙钟时间戳可能碰撞或回拨不是安全的分页边界list 端点必须与已经按持久化序列排序的回放和上下文加载保持一致。兼容性无需数据库迁移session_message.seq与会话作用域索引已存在HTTP 游标保持不透明既有游标仍可用它们本就携带投影消息id解码时忽略多余的time无需 OpenAPI 或生成 SDK 变更。公共 Provider 与模型目录 DTO2026-06-03GET /api/provider、GET /api/provider/:providerID、GET /api/model的响应替换为显式公共 DTO生成的ProviderV2PublicInfo与ModelV2PublicInfo。从公共响应中移除provider 请求头与请求体、API 设置、自定义启用数据、模型请求覆写、变体请求覆写。原因内部目录记录可能包含凭据或 provider 特定的请求材料不得跨越公共 HTTP 序列化边界。公共 V2 目录响应有意暴露更少字段内部 Schema 仍对运行时可用。回放元数据与投影所有权持久化推理与托管工具回放元数据2026-06-03持久化session.next.reasoning.started/ended事件新增可选providerMetadatasession.next.tool.success/failed事件新增可选持久化result并投影进结算工具消息状态。投影的 tool-call 元数据与可选结算结果元数据分开保存只在历史 assistant 模型与续跑所选模型一致时回放 provider 原生推理与工具元数据。原因provider 续跑需要后续回合携带签名/加密的推理元数据provider 执行的托管工具结果必须幸存投影使回放能把托管调用与结果内联保留在 assistant 内容中恢复结算不得抹掉重建有效续跑请求所需的 provider 原生 call 元数据。兼容性新增持久化事件字段均为可选先前记录的实验事件仍可解码OpenAI Responses 把重建的 provider 执行托管结果降级为存储项引用而非拒绝 assistant 历史Bedrock Converse 签名、GeminithoughtSignature、OpenAI 兼容 Chatreasoning_content现在都能经规范续跑 part 往返。投影 assistant 所有权与全值 Part2026-06-03投影 assistant 文本 part 保留稳定 ID持久化工具投影更新通过显式拥有者 assistant 消息 ID 路由而不是仅靠 provider 本地 call ID回放**全值full-value**的文本与工具输入终点 checkpoint片段 delta 仍为 ephemeral。原因provider 本地工具 call ID 可能跨回合重复持久化投影重建不能依赖重连后消失的 ephemeral 片段。兼容性早期无稳定文本 ID 的实验投影 assistant 行不假设回放兼容当前 V2 历史一律从持久化全值 checkpoint 重建。上下文纪元Context Epoch演进三部曲这三条是 V2 系统上下文管理的完整演进链建议按顺序阅读1. Add Durable Session Context Snapshots2026-06-04新表session_context_epoch每 Session 一个活跃不可变基线字符串、结构化 JSON 快照与基线序列。在首个安全 provider-turn 边界惰性初始化一个持久化 Context Epoch 快照纪元内每个 provider turn 通过LLMRequest.system下发其精确基线字符串重启或生产者变化后逐字复用存储基线而不是重新采样特权初始上下文后续观察与可覆写的编解码结构化快照而非渲染文本哈希比较受理的按时间顺序上下文作为一等systemSession 消息暴露。兼容性未发布的 Context Epoch Schema 合并进单个数据库迁移基线与结构化快照是运维状态而非同步事件历史。2. Admit Chronological Session Context Updates2026-06-04新同步事件session.next.context.updated.1携带持久化 System 消息 ID 与精确合并后的模型可见文本session_context_epoch.revision用于事务性结构化快照推进一等systemSession 消息投影。每个安全 provider-turn 边界用一个一致观察调和 Location 作用域 Context Source存储基线保持不可变变化源渲染作为按时间顺序的Message.system(...)历史受理结构化快照与渲染 System 消息事件原子推进源被移除时发出此前存储的模型意义移除渲染拒绝会把本地工具调用与其结果割裂到不同 provider 协议两侧的按时间顺序 system 更新Anthropic 原生 system 更新位置不受支持时使用包装 user 回退。兼容性同步事件日志只保留模型实际看到的文本不保留内部结构化快照。3. Replace Session Context Epochs Lazily2026-06-04→ Simplify Session Context Rebaselining2026-06-22惰性替换阶段模型切换或压缩完成后标记活跃 Context Epoch 为待替换session_context_epoch.replacement_seq可空持久化触发聚合序列使同目标回放不会重开已结算的替换新基线在下一个安全边界惰性渲染覆写组装活跃 provider 历史时排除旧纪元的按时间顺序 System 消息。2026-06-22 的简化是对其回滚式重构删除session_context_epoch.agent、replacement_seq、revision三列每个 provider turn 只采样一次有效 agent 与模型选择变化对下一 turn 生效压缩完成后直接重建基线而非维护挂起替换状态后压缩基线无法完整渲染时保留旧基线及其按时间顺序更新依赖进程内 Session 执行 lane而非 Context Epoch 写者间的乐观并发状态。兼容性既有 Context Epoch 行原地迁移丢弃废弃的选择与挂起替换列模型与 agent 切换不再通过强制新基线丢弃早前的按时间顺序 System 上下文更新。配套的 2026-06-05 两条补齐了生产侧Register Ambient System Context ProducersLocation 作用域的稳定键上下文生产者注册表替换 Session 专属加载器独立注册环境/日期与 ambient 指令生产者并按稳定贡献键顺序并发评估每个安全边界直接发现并读取全局与向上项目AGENTS.md任一上下文源不可用时阻塞首纪元初始化Session 移动时清空活跃纪元并在目标 Location 初始化完整基线以权威 Session Location 对纪元初始化做 fence防止并发的旧 Location runner 重建陈旧的特权上下文与Admit Selected-Agent Skill Guidancesession_context_epoch.agent记录基线所属有效 agent选定 agent 的技能指导经权限过滤后与 Location 级 System Context 组合再进纪元受理技能正文仍留在权限检查的skill工具后缺失技能错误不再枚举未过滤目录agent 切换后请求纪元替换并跨 agent 阻止在替换上下文不可用期间的 provider turn。其余契约条目速览Location 作用域 V2 Questions2026-06-03新增QuestionV2.*域 Schema、question.v2.asked/replied/rejected事件、GET /api/question/request与POST /api/session/:sessionID/question/request/:requestID/reply|reject路由。嵌入式 V2 工具执行需要 Location 拥有的挂起问题服务其挂起回复可经 HTTP 结算。无需数据库迁移——挂起问题有意是内存态 Location 状态。Core 自有 Todo 更新事件2026-06-03从 Core session-todo 所有权注册全局todo.updated事件向 Core V2 工具暴露既有 todo 项形态todo 表与公共事件形态不变无迁移。条件文件变更陈旧错误2026-06-03内部新增FileMutation.StaleContentError标记错误——已批准的精确编辑在提交时不再匹配字节时携带变更目标路径的类型化错误。V2 精确编辑必须失败而不是在权限批准后陈旧覆盖并发协作写入纯内部追加契约无数据库/HTTP/SDK 变更。Provider 流看门狗策略延期2026-06-03不施加通用的 provider 流不活跃或绝对超时移除内部超时错误与硬编码看门狗服务超时、重试、看门狗、持久化失败报告与 drain 链释放策略整体延期到可配置的设计切片。理由V1 本就没有通用处理器不活跃看门狗不同 provider 与自主负载的运行时特征不同硬编码默认值为时过早。键控合并持久化尾信号2026-06-03把进程全局无界聚合 ID PubSub 替换为每活跃尾 聚合一个滑动容量 1 的 dirty 信号历史 SQLite 回放前订阅注册、尾关闭时移除每次 dirty 边之后重查持久化行并只按持久化聚合序列推进。唤醒通知是建议性边而非持久化事件 payload慢消费者不应为一次 SQLite 查询就能恢复全部已提交行而保留无界冗余唤醒 ID。sessions.events({ sessionID, after? })语义不变。嵌入式本地工具恢复对齐2026-06-03Session 省略显式 agent 时权限按默认buildagent 评估与 provider-turn 执行一致组装 provider 请求前把上一个进程遗留、仍投影为running的本地工具用既有session.next.tool.failed形态与Tool execution interrupted消息持久化失败。原因无 agent 的嵌入式 Session 以前按build执行却用空权限规则集评估首个本地工具可能永远等待一个本地表面不存在的批准面进程在本地工具运行中丢失会留下悬空 tool call使后续 provider 续跑无效——恢复必须结算持久化投影而不重放被放弃的副作用。Pre-PR V2 安全评审2026-06-03对聚合 ID 与解码同步 payload 不一致的回放封套加 fence回放首次采纳无主聚合时持久化 owner 声明续跑前持久化结算被放弃的本地与 provider 执行工具apply_patch的 add hunk 采用 create-only 语义、预检后顺序提交不可中断、急切拒绝畸形 patch 语法skill内置物化前等待初始插件启动provider/model 公共 API URL 剥离凭据、query 与 fragmentV2 请求体在生成的 OpenAPI 与 SDK 类型中保持必填。兼容性要点pre-launch 的session.next.*数据库仍是可丢弃实验状态V1 把抓取图片作为附件返回而首个 Core V2 类型化结算是纯文本的因此 V2 继续拒绝抓取的图片等非文本文件直到附件结算被显式设计。阅读与实操建议消费 V2 历史数据轮询式用GET /api/session/:sessionID/historyafter排他序列 页上限 100 hasMore耗尽信号实时渲染用 SSE 的GET /api/session/:sessionID/event。两者读同一份持久化日志序列间隙是合法的。升级跨不兼容事件 Schema 迭代按 changelog 的一致性结论操作——重置实验性 V2 事件/投影/输入/纪元/同步工作区状态启动前清理 adapter 管理的外部工作区资源V1session/message/part行不动。写 V2 工具或权限策略以追加式、有界、Core 自有为基调——每个工具都有显式参数与 success Schema变更操作必须走external_directory显式授权与提交前重验bash 的宿主权限只能靠建议性警告提示而不可宣称隔离。提交影响 Schema 的变更在本 changelog 增加一条记录写清受影响 Schema、变更、原因与兼容性并在 commit message 中附同样摘要——这是该文件自身声明的维护纪律。【免费下载链接】opencodeThe open source coding agent.项目地址: https://gitcode.com/GitHub_Trending/openc/opencode创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考
