OpenCode v2 会话可靠性实战：Snapshots、Compaction、Instructions 与 Formatters

这是《OpenCode v2 实战：从零搭建企业级 AI 编程助手》专题的第 20 篇。上一篇解决了 Proxy、私有 CA、CORS、日志与 Heap Snapshot 的企业网络排障问题；这一篇回到长时间开发最容易失控的现场：改错文件后怎样安全撤回，超长会话怎样继续，团队规则怎样持续生效，Agent 写完代码后怎样稳定格式化。

OpenCode v2 分别提供了 Snapshots、Compaction、Instructions 与 Formatters。它们看起来分属恢复、上下文、规则和代码风格，实际共同决定一条 Agent 会话能否"跑得久、退得回、接得上、验得过"。

只启用其中一个能力并不能解决可靠性问题。Snapshot 不能回滚数据库和 Git Commit；Compaction 会有损压缩细节；Instructions 不会自动消解冲突；Formatter 也不等于测试或静态检查。生产化需要把四者放进同一个变更闭环，并明确每一步的边界、证据和失败策略。

本文依据 2026 年 10 月 29 日可见的 OpenCode v2 官方文档整理。示例中的仓库、会话 ID、路径和指标均为演示数据，不包含真实凭据。

一、为什么长会话最容易失去工程控制

1. 四类失控会互相放大

一条持续数小时的会话，通常同时面临四类风险：

风险	表面现象	根因	需要的控制
变更失控	改错文件、误删内容	缺少可恢复边界	Snapshots + Git
上下文失控	忘记早期约束、重复调查	接近模型上下文上限	Compaction
规则失控	子目录规范未加载、规则冲突	指令作用域不清	Instructions
质量失控	格式漂移、无关 diff 增多	写后处理不稳定	Formatters + 检查

最危险的不是某一步失败，而是团队把一个能力误当成另一个能力。例如把 /undo 当作数据库事务，把摘要当作完整审计日志，或者把自动格式化当作测试通过。

2. 建立一条完整闭环

text 复制代码

加载项目规则
  → 记录工作区基线
  → Agent 读写文件
  → 匹配并运行 Formatter
  → 执行测试与静态检查
  → 记录 diff、日志和业务结果
  → 需要时通过 Snapshot 暂存回滚
  → 长会话通过 Compaction 续接
  → 重要里程碑进入 Git Commit 或备份

这条链路中，每个机制只承担自己能证明的那一段。恢复文件、保留语义、加载规范和统一格式是不同责任，不能混成一个"Agent 会自动处理"的黑箱。

3. 先定义成功，而不是先开功能

团队可以先约定四个可观测目标：

yaml 复制代码

recovery:
  important_change_has_git_checkpoint: true
context:
  next_move_present_after_compaction: true
instructions:
  verification_command_is_explicit: true
quality:
  formatter_and_tests_have_exit_codes: true

只有当回滚范围、摘要质量、规则来源和验证结果都能被复核，长会话才算可靠。

二、Snapshots 的真实语义

1. `/undo` 是暂存回滚，不是立即销毁

在希望修改上一轮请求时，可以运行：

text 复制代码

/undo

OpenCode 会暂存这次回滚，恢复相关文件，并把被移除的提示放回输入区供编辑。提交修改后的提示，才会确认这次暂存回滚。若反悔，可以在提交前运行：

text 复制代码

/redo

/redo 会取消暂存回滚，恢复 /undo 之前的对话和文件状态。终端默认快捷键分别是 <leader>u 与 <leader>r。

2. Snapshot 以模型步骤为边界

对于每个模型步骤，OpenCode 会尽力在模型调用前创建 Snapshot，并在步骤记录为成功或失败时再创建一个。助手消息会记录两次快照之间哪些路径发生变化：

text 复制代码

模型步骤开始前 ── Snapshot A
Agent 修改 src/order.ts
步骤结束       ── Snapshot B
差异记录       ── changed: src/order.ts

这里的关键词是"尽力"。Snapshot 捕获失败不会中止对话，因此某一步能够继续执行，不代表它一定拥有可恢复的文件状态。

3. 恢复以助手步骤归属的路径为准

回滚不会把整个仓库粗暴还原到某个时间点，而是恢复所选对话边界之后、归属于助手步骤的路径。被创建的新文件如果在边界时不存在，会在回滚后删除；受影响文件会回到第一个被撤销步骤之前的版本。

text 复制代码

边界时：src/api.ts = A，src/new.ts 不存在
后续：  src/api.ts = B，创建 src/new.ts
回滚后：src/api.ts = A，src/new.ts 被移除

没有归属于这些步骤的路径会保留，但当前对受影响路径的人工编辑可能被覆盖。因此继续前必须检查：

bash 复制代码

git diff --stat
git diff

三、Snapshot 能捕获什么，不能捕获什么

1. 作用域由活动目录和 Git Worktree 决定

文件系统 Snapshot 需要 Git 仓库。会话在 packages/web 启动时，只捕获该活动目录下符合条件的文件，而不是整个仓库。

内容	是否捕获	说明
活动目录内已跟踪文件	是	记录文件内容变化
未忽略且单文件不超过 2 MiB	是	可包含未跟踪文件
Git 忽略文件	否	如构建产物和本地缓存
大于 2 MiB 的未跟踪文件	否	如大型调试日志
活动目录外文件	否	即使属于同一仓库
Git 元数据与外部副作用	否	Commit、分支、进程、数据库等

仓库外使用 /undo 时，对话历史仍可回滚，但无法恢复相关文件。

2. Snapshot 不是外部系统事务

下面这些动作不会因 /undo 自动逆转：

text 复制代码

启动或停止进程
写入数据库
调用支付、消息、发布接口
创建 Git Commit 或切换分支
修改活动目录外文件
生成被 .gitignore 忽略的制品

因此外部副作用必须使用各自的幂等键、业务对账和补偿流程。网络超时后先查业务状态，不能因为文件已回滚就盲目重放请求。

3. Snapshot 也不是安全擦除

快照对象存放在 OpenCode 数据目录中的独立内部 Git 对象数据库里，可能包含完整文件内容。禁用未来捕获不会删除已经保存的 Snapshot；提交回滚也只是从活动对话视图移除消息，不代表持久历史和快照对象被安全擦除。

json 复制代码

{
  "$schema": "https://opencode.ai/config.json",
  "snapshots": false
}

如果仓库包含敏感材料，OpenCode 数据目录也必须纳入终端加密、访问控制、备份和保留策略。

四、把 `/undo` 变成可控恢复流程

1. 回滚前先冻结现场

推荐的恢复顺序是：

text 复制代码

停止继续写入
  → 记录 git status --short
  → 保存重要未跟踪文件
  → 确认回滚边界
  → 执行 /undo
  → 检查恢复摘要与 git diff
  → 决定提交新提示还是 /redo

不要在外部编辑器仍在自动保存时执行回滚，也不要让另一个 Agent 同时修改相同路径。

2. 重要工作仍然使用 Git 里程碑

Snapshot 适合调整最近对话，Git Commit 适合长期追溯、协作与审查。可以按风险设置检查点：

bash 复制代码

git status --short
git diff --check
git add src tests
git commit -m "checkpoint: validate order callback"

是否提交、推送或合并仍应遵循团队授权规则。快照的便利不能替代规范的分支、Review 和备份。

3. 为恢复演练准备验收项

已知活动目录与 Snapshot 覆盖范围；
已确认未跟踪大文件和忽略文件不会恢复；
回滚前保存了人工修改；
/undo 后核对了 git diff；
外部副作用拥有独立对账方式；
重要节点已经进入 Git 或备份；
数据目录按敏感资产治理。

五、Compaction 为什么必不可少

1. 它用摘要替换旧对话

当会话接近模型上下文上限时，OpenCode 会总结当前对话，并在摘要旁保留最近一段对话。默认大约保留 15,000 Token：

text 复制代码

压缩前：[系统提示][很长的旧对话][最近 15k][待办]
压缩后：[系统提示][结构化摘要][最近 15k][待办]

后续再次压缩时，会基于已有摘要和新对话更新检查点。完整会话会用于摘要请求，使支持的 Provider 可以复用正常请求的提示缓存。

2. Compaction 是有损的

摘要会保留目标、约束、决定、完成项、进行中工作、阻塞、下一步和相关文件，但不会逐字保留所有历史。长工具输出会被缩短，附件数据会替换为简短描述。

因此这些内容不要只依赖聊天记忆：

text 复制代码

精确 API 契约 → 写入代码或文档
关键决策     → 写入 ADR
发布步骤     → 写入 Runbook
验收结果     → 写入 CI 或测试报告
敏感授权     → 由业务系统保存

3. 默认配置与调优

自动压缩默认开启：

json 复制代码

{
  "$schema": "https://opencode.ai/config.json",
  "compaction": {
    "auto": true,
    "keep": { "tokens": 15000 }
  }
}

keep.tokens 越大，精确近期细节越多，但留给新工作的空间越少。buffer 用于在模型上限前预留空间；默认是上下文上限的 15%，且至少 16k Token。过大的 Buffer 会更早触发压缩。

六、手动压缩与幂等控制

1. 在安全点主动请求

无需等到上下文即将耗尽，可以通过 API 主动请求：

bash 复制代码

opencode api post /api/session/ses_example/compact --data '{}'

API 响应只代表请求已被接受，并不代表摘要已经完成。应继续观察 session.compaction.* 事件。请求会在下一个安全点执行，排在仍等待的 Prompt 之前；压缩待处理时重复请求会合并。

2. 精确重试使用请求 ID

bash 复制代码

opencode api post /api/session/ses_example/compact \
  --data '{"id":"msg_compact_once"}'

相同 ID 的精确重试具备幂等性；把同一个 ID 用于不同请求会返回冲突。这比网络超时后生成新请求更容易判断结果。

3. 关闭自动压缩不影响手动请求

json 复制代码

{
  "$schema": "https://opencode.ai/config.json",
  "compaction": {
    "auto": false,
    "keep": { "tokens": 24000 },
    "buffer": 16000
  }
}

即使 auto 为 false，手动 Compaction 仍然可用。适合必须在代码 Review、阶段验收或交接点主动压缩的受控工作流。

七、摘要模型与 Provider 原生压缩

1. 为摘要指定独立模型

默认由当前会话模型生成摘要，也可以指定：

json 复制代码

{
  "$schema": "https://opencode.ai/config.json",
  "agents": {
    "compaction": {
      "model": "anthropic/claude-sonnet-5-5"
    }
  }
}

如果指定模型无法解析，OpenCode 会回退到会话模型。团队应监控摘要模型的可用性、成本和信息保真度，而不是只看配置是否存在。

2. Provider 原生压缩的边界

部分 Provider 或模型支持原生 Compaction：

json 复制代码

{
  "$schema": "https://opencode.ai/config.json",
  "providers": {
    "openai": {
      "settings": { "compaction": { "type": "native" } },
      "models": {
        "gpt-6.1-sol": {
          "settings": { "compaction": { "type": "summary" } }
        }
      }
    }
  }
}

模型设置覆盖 Provider 设置。native 使用 Provider 的压缩端点，返回代表旧对话的不透明加密检查点；summary 使用 OpenCode 摘要。

3. 原生检查点不具备通用可移植性

原生加密检查点只适用于相同 Provider 和模型。切换模型时，会话从原始对话继续，而不是把该检查点迁移过去。Provider 拒绝过长的原生压缩请求时，OpenCode 会缩小请求重试，但不会自动改成摘要模式。

八、后台 Compaction 的收益与风险

1. 提前生成，达到阈值再切换

实验性后台压缩会在阈值约 85% 时提前生成摘要，会话继续运行；达到阈值时再把摘要切换进来：

json 复制代码

{
  "$schema": "https://opencode.ai/config.json",
  "experimental": {
    "background_compaction": true
  }
}

它减少了达到阈值后的等待，但未被使用的摘要仍会产生 Token 成本。

2. 哪些情况会回退或跳过

如果摘要生成后又出现太多新对话，或者模型、指令、会话开头发生变化，OpenCode 会回退到普通压缩。原生 Compaction、约 64k Token 以下的会话、刚切换模型或 Provider 已拒绝请求过长时，也可能跳过后台模式。

3. 生产启用要看指标

yaml 复制代码

metrics:
  compaction_latency_p95: 4.2s
  summary_reuse_rate: 0.78
  unused_summary_cost: 0.03
  post_compaction_rework_rate: 0.06

后台摘要保存在内存中，重启会丢失。启用前应同时衡量等待时间、浪费成本、摘要采用率和压缩后返工率。

九、Instructions 如何成为持续规则

1. 用 `AGENTS.md` 保存项目指导

markdown 复制代码

# Project instructions

- 修改 TypeScript 后运行 `bun typecheck`。
- 数据库查询只放在 `src/database`。
- 不要直接编辑生成文件。

适合写入构建命令、架构边界、代码约定和验证要求。项目文件应提交到仓库，让每个协作者获得相同规则。

2. 规则按作用域组合，不会自动解决冲突

OpenCode 会先加载全局文件，再加载从当前工作区向上到主目录或项目根的每个 AGENTS.md。更具体的规则应放在更靠近代码的位置。

text 复制代码

~/.config/opencode/AGENTS.md
repo/AGENTS.md
repo/packages/AGENTS.md
repo/packages/web/AGENTS.md  ← 当前工作区

这些内容会被组合，而不是互相覆盖或自动判定优先级。规则冲突必须由团队消除。V2 只识别 AGENTS.md，不会把 CLAUDE.md 当作后备文件。

3. 嵌套规则按探索过程发现

工作区下方的指令文件不会全部在启动时塞入上下文。当 Agent 读取文件或列出目录时，目标与工作区之间的 AGENTS.md 会被加载，且按最近目录优先、在当前模型可见历史中去重。

text 复制代码

repo/AGENTS.md              启动时加载
repo/packages/web/AGENTS.md 读取 web/src/app.ts 时加载
repo/packages/web/src/app.ts

这能控制上下文体积，但也意味着任务尚未探索某个目录时，它可能还不知道该目录的专属规则。

十、指令更新、压缩与回滚的联动

1. 运行中修改上层规则会注入更新

全局或向上发现的 AGENTS.md 在会话运行时发生变化，OpenCode 会在下一次模型请求前加入指令更新。临时读取失败会保留最后已知规则，而不是误判为删除。

text 复制代码

AGENTS.md 变化
  → instruction update
  → 下一次 Prompt

嵌套文件加载后再被编辑，不会自动检测；需要新文本立即生效时，启动新会话更可靠。

2. Compaction 后规则基线会变化

Compaction 完成后，当前版本的指令文件会成为会话的新基线。提交一次 Session Revert 会清除指令状态，并在下一次 Prompt 前重新加载。

这意味着规则变更、压缩和回滚不是互不相关的三个功能。关键任务应在变更规则时记录版本或 Commit，并在压缩后核对摘要中的约束是否与当前规则一致。

3. 通过配置加载补充指令

json 复制代码

{
  "$schema": "https://opencode.ai/config.json",
  "instructions": [
    "CONTRIBUTING.md",
    "docs/guidelines/*.md",
    "~/rules/opencode.md",
    "https://example.com/instructions.md"
  ]
}

相对路径或 Glob 会在工作区到项目根之间解析，~/ 从主目录解析，绝对路径按原样使用，HTTP(S) URL 在加载配置时获取且超时为 5 秒。远程规则应使用受控域名、版本化内容和完整性校验，避免把可变网页当成不可审查的最高权限指令。

十一、编写高质量 `AGENTS.md`

1. 写可执行约束，不写愿望

低质量规则：

text 复制代码

代码要优雅。
注意安全。
测试充分。

高质量规则：

markdown 复制代码

- 修改 `src/api/**` 后运行 `bun test api`。
- 禁止把令牌、Cookie 和客户数据写入日志。
- 数据库迁移只允许新增文件，不修改已上线迁移。
- 完成时报告变更路径、测试命令和退出码。

规则应包含触发条件、允许或禁止的动作、验证命令和完成证据。

2. 控制作用域和长度

text 复制代码

全局：通用安全与沟通规范
仓库根：架构、构建、全局验证
模块目录：局部约束与测试命令
任务输入：本次目标与验收标准

固定指令过大时，Compaction 也无法创造空间。例如 128k 上下文中，若固定指令与工具 Schema 已占 120k，压缩 8k 对话几乎没有价值。

3. 建立规则测试

可以用代表性任务验证规则是否被加载：

yaml 复制代码

cases:
  - task: "修改 web 订单页面"
    must_mention: "bun test web"
  - task: "增加数据库字段"
    must_not: "改写已有迁移"
  - task: "输出诊断日志"
    must_mention: "脱敏"

把规则测试纳入升级验证，能提前发现指令发现顺序或模型行为变化。

十二、Formatters 的定位：写后规范化

1. 默认关闭，需要显式启用

json 复制代码

{
  "$schema": "https://opencode.ai/config.json",
  "formatter": true
}

Formatter 会在 write、edit 或 patch 工具修改文件后运行。true 启用内置定义，但只有命令和项目要求满足时才会实际执行。

2. 内置 Formatter 覆盖多种语言

官方内置定义包括 gofmt、mix、oxfmt、prettier、biome、zig、clang-format、ktlint、ruff、uv、rubocop、dart、terraform、rustfmt、shfmt 等。

不同定义拥有不同发现条件。例如 Prettier 需要项目 package.json 中的依赖，Biome 需要配置文件和已安装二进制，clang-format 需要命令与 .clang-format，Ruff 需要配置或依赖声明。

3. 自动格式化不等于质量门禁

Formatter 只能证明某个格式化命令对匹配文件成功。它不能证明：

text 复制代码

代码可以编译
类型检查通过
单元测试通过
API 行为兼容
安全策略满足
业务结果正确

因此格式化之后仍要运行 Lint、Typecheck、Test 和业务验收。

十三、自定义 Formatter 的正确方式

1. 命令是参数数组，不是 Shell 字符串

json 复制代码

{
  "$schema": "https://opencode.ai/config.json",
  "formatter": {
    "deno-markdown": {
      "command": ["deno", "fmt", "$FILE"],
      "extensions": [".md"]
    }
  }
}

OpenCode 会把 $FILE 替换为文件绝对路径，并从活动项目目录执行命令。数组形式避免依赖 Shell 拼接，也更容易审计每个参数。

2. 可以覆盖环境变量和扩展名

json 复制代码

{
  "$schema": "https://opencode.ai/config.json",
  "formatter": {
    "prettier": {
      "environment": {
        "NODE_ENV": "development"
      },
      "extensions": [".js", ".ts"]
    }
  }
}

environment 会在保留父进程环境的基础上追加变量；extensions 会替换内置扩展列表。扩展名需要包含点号，并且匹配区分大小写。

3. 多个匹配项按顺序尝试

json 复制代码

{
  "formatter": {
    "preferred": {
      "command": ["preferred-fmt", "$FILE"],
      "extensions": [".foo"]
    },
    "fallback": {
      "command": ["fallback-fmt", "$FILE"],
      "extensions": [".foo"]
    }
  }
}

多个 Formatter 匹配时，OpenCode 按注册顺序执行，并在第一个成功命令后停止。某个命令失败会记录日志并尝试下一个匹配项。内置项保留内置顺序，自定义项按对象顺序追加。

十四、Formatter 的配置陷阱

1. 复合扩展名不会按预期匹配

匹配使用文件最终扩展名，.part.md 不会匹配 notes.part.md，因为最终扩展名是 .md。需要使用：

json 复制代码

{
  "formatter": {
    "markdown": {
      "command": ["deno", "fmt", "$FILE"],
      "extensions": [".md"]
    }
  }
}

2. 空对象、`true` 与 `false` 语义不同

json 复制代码

{
  "formatter": {}
}

对象会启用内置项，并允许继承、覆盖或添加；空对象保留继承的 Formatter 设置，true 则重置为内置定义。若低优先级配置已启用格式化，可用 false 明确关闭：

json 复制代码

{
  "formatter": false
}

3. 只禁用一个内置项

json 复制代码

{
  "formatter": {
    "prettier": {
      "disabled": true
    }
  }
}

新建自定义项时必须同时提供 command 和 extensions；内置项则可以只覆盖部分字段，未提供字段会继承。

十五、四种能力如何协同

1. 一次安全修改的推荐时序

text 复制代码

读取根目录 AGENTS.md
  → 探索目标目录并加载嵌套规则
  → git status 记录基线
  → 修改文件
  → Formatter 自动处理
  → 查看 diff，运行类型检查和测试
  → 失败时判断修复还是 /undo
  → 里程碑进入 Git Commit
  → 阶段交接前主动 Compaction
  → 检查摘要中的目标、约束与 Next Move

回滚只处理最近文件与对话，压缩只处理模型可见上下文，Instructions 只提供约束，Formatter 只处理格式。明确边界后，失败才容易定位。

2. 把完成证据写成结构化报告

json 复制代码

{
  "objective": "为订单回调增加签名校验",
  "changed": ["src/order/callback.ts", "tests/order/callback.test.ts"],
  "formatter": { "name": "prettier", "exitCode": 0 },
  "checks": [
    { "command": "bun typecheck", "exitCode": 0 },
    { "command": "bun test order", "exitCode": 0 }
  ],
  "checkpoint": "commit-or-backup-id",
  "nextMove": "在预发布环境验证旧签名兼容性"
}

这类报告既能帮助人工 Review，也能为下一次 Compaction 提供高质量输入。

3. 失败矩阵

故障	不应直接做什么	正确动作
Snapshot 缺失	假设 `/undo` 会恢复全部文件	先检查 Git 与备份
压缩后遗漏细节	继续凭记忆修改	回读代码、ADR 与测试
指令冲突	让模型自行猜优先级	合并或重写冲突规则
Formatter 失败	忽略并继续发布	读取日志、固定版本、人工验证
外部请求超时	回滚文件后重发	查询业务状态并对账

十六、团队落地配置示例

1. 基础配置

json 复制代码

{
  "$schema": "https://opencode.ai/config.json",
  "snapshots": true,
  "compaction": {
    "auto": true,
    "keep": { "tokens": 18000 },
    "buffer": 20000
  },
  "formatter": {
    "prettier": {
      "extensions": [".js", ".jsx", ".ts", ".tsx", ".json", ".md"]
    },
    "shfmt": {
      "extensions": [".sh", ".bash"]
    }
  },
  "instructions": [
    "CONTRIBUTING.md",
    "docs/engineering/*.md"
  ]
}

Token 数值应结合实际模型上限、任务长度和工具 Schema 占用压测，不要把示例值直接当成通用最优值。

2. 仓库根规则示例

markdown 复制代码

# Repository rules

- 开始前运行 `git status --short`，不得覆盖用户现有修改。
- 修改 TypeScript 后运行 `bun typecheck`。
- 修改业务逻辑后运行对应测试，不得只报告 Formatter 成功。
- 发布、推送、部署、删除和外部消息必须有明确授权。
- 完成时报告文件、命令、退出码和未解决风险。

3. 模块规则示例

markdown 复制代码

# Order service rules

- 公共回调保持向后兼容。
- 日志不得记录签名原文、Cookie 或客户数据。
- 修改回调后运行 `bun test order-callback`。
- 数据库迁移只新增文件，不改写已执行迁移。

十七、观测与审计指标

1. 恢复指标

yaml 复制代码

snapshot_capture_success_rate: 0.997
rollback_attempts: 12
rollback_overwrite_incidents: 0
external_side_effect_replay_incidents: 0

只统计 /undo 次数没有意义，还要观察捕获成功率、人工编辑覆盖和副作用误重放。

2. 上下文指标

yaml 复制代码

compaction_count: 38
compaction_latency_p95: 5.1s
post_compaction_clarification_rate: 0.08
post_compaction_rework_rate: 0.04

摘要质量应通过压缩后澄清率、返工率和任务续接成功率衡量。

3. 规则与质量指标

yaml 复制代码

instruction_conflict_count: 2
formatter_success_rate: 0.985
format_only_diff_ratio: 0.11
required_check_pass_rate: 0.96

Formatter 成功率高但必需检查通过率低，说明团队把格式化误当成了完整验证。

十八、上线检查清单与总结

1. 上线前检查

已明确 Snapshot 的活动目录、文件大小和忽略规则；
重要变更有 Git Commit 或独立备份；
/undo 前会冻结外部编辑和并发 Agent；
外部副作用使用幂等键、状态查询和补偿流程；
OpenCode 数据目录按敏感数据治理；
Compaction 的 keep.tokens 与 buffer 经过压测；
摘要包含目标、约束、决定、阻塞与 Next Move；
原生检查点的 Provider 与模型可移植性已评估；
实验性后台压缩有成本与回退监控；
AGENTS.md 分层清晰且没有冲突；
关键规则写成可执行命令和验收证据；
远程 Instructions 来源受控并可版本化；
Formatter 命令、版本和项目依赖可复现；
格式化后仍执行 Lint、Typecheck、Test 与业务验收；
发布、推送、部署和删除继续保留独立授权。

2. 总结

OpenCode v2 的会话可靠性，不来自某一个"自动恢复"开关，而来自四层互补控制：Snapshots 为最近的对话与文件改动提供可撤回边界；Compaction 让长会话在上下文上限前保留任务语义；Instructions 把团队规则带入正确作用域；Formatters 在写后统一机器可执行的代码风格。

成熟闭环应当是：

text 复制代码

规则有来源、有作用域、有验证
  → 变更有基线、有格式化、有测试
  → 最近错误可用 Snapshot 谨慎撤回
  → 重要里程碑用 Git 或备份长期保存
  → 长会话用 Compaction 结构化续接
  → 外部副作用独立授权、对账与补偿
  → 最终用 diff、退出码、ID 和业务状态证明完成

当团队不再把对话历史当数据库、不把 Snapshot 当事务、不把 Formatter 当测试，也不把规则冲突交给模型猜测时，Agent 才能从一次性代码生成器升级为可持续协作的工程执行者。

3. 参考资料

本文依据 2026 年 10 月 29 日可见的 OpenCode v2 官方 Snapshots、Compaction、Instructions、Formatters、Config 与 API 文档整理。实验性后台压缩、Provider 原生压缩、内置 Formatter 列表和配置语义可能继续变化；生产环境应固定实际版本，并以当前官方文档、安装版本和运行结果为准。

OpenCode v2 会话可靠性实战：Snapshots、Compaction、Instructions 与 Formatters