上下文压缩 — 设计规范

上下文压缩 — 设计规范概述为 opencode-goal 插件增加自动和手动的对话压缩功能。压缩通过 opencode 服务端对对话历史进行摘要实现在降低 Token 用量的同时保留关键上下文目标状态、进度。已有的compact_after_tokens选项将被激活新增一个compact_after_turns选项。配置// opencode.json { plugin: [[./opencode-goal/dist/server.js, { compact_after_tokens: 8000, // Token 8000 时压缩0 禁用 compact_after_turns: 10 // 每 10 个自动继续轮次压缩一次0 禁用 }]] }组件1. 选项 — server.ts选项类型默认值描述compact_after_tokensnumber0当tokens_used 该值时自动压缩。0 表示禁用。代码中已预留。compact_after_turnsnumber0每 N 个自动继续轮次自动压缩一次。0 表示禁用。新增选项。compact_timeout_secondsnumber300压缩 HTTP 请求的超时时间。0 表示无超时。默认 3005 分钟。2. 压缩工具 — server.ts暴露一个compact工具让 AI 可以触发压缩tool: { compact: tool({ description: 压缩/总结对话以降低 Token 用量, args: {}, async execute(_args, context) { // 通过 V1 客户端的内部 HTTP 调用 POST /api/session/{sessionID}/compact } }) }该工具也是/goal compact的工作方式 —— 当参数为 “compact” 时命令模板会指示 AI 调用compact工具。3. run_auto_continue 中的自动触发 — server.ts读取目标状态之后、发送继续提示之前run_auto_continue(session_id): goal await get_goal(session_id) // 检查自动压缩触发器 if compact_after_turns 0 AND goal.auto_turns % compact_after_turns 0: 触发压缩 if compact_after_tokens 0 AND goal.tokens_used compact_after_tokens: 触发压缩仅一次通过标志位防止重复触发 // 继续正常流程 ...设计决策压缩在继续提示之前触发这样压缩后的上下文可用于下一个 AI 轮次。使用运行时跟踪映射compacted_at_tokens防止在同一 Token 级别重复压缩每次跨越阈值时仅压缩一次而不是每次空闲事件都压缩。4. 命令模板更新 — prompts.ts在目标命令处理指令中增加 “compact”compact → compact 工具压缩对话历史5. 压缩 API 调用opencode 服务端暴露POST /api/session/{sessionID}/compactV2 SDK 中的Session3.compact()。插件通过 V1 客户端内部的 HTTP 客户端client.session._client使用原始 POST 调用 —— 与client.session.prompt()所使用的类型转换模式保持一致。6. 压缩钩子已有 — 无更改server.ts中已有的experimental.session.compacting钩子会通过compaction_context()在压缩提示中注入目标状态。无需改动。测试手动测试 —/goal compact用户/goal compact → AI 收到命令模板 → AI 调用 compact 工具 → 压缩 APIPOST /api/session/{id}/compact → 压缩钩子触发注入目标状态 → AI 回复对话已压缩。自动压缩验证在 opencode.json 中设置compact_after_turns: 3使用/goal test启动一个目标在 3 次自动继续轮次后验证压缩是否自动触发检查日志[opencode_goal_auto] 自动压缩已触发轮次安全性与边界情况幂等性compacted_at_token_level映射防止在相同阈值重复压缩。仅在 Token 用量增加后重新检查 Token 阈值。空会话对没有目标的会话执行压缩 → 服务端压缩仍然运行API 端点独立于插件的目标状态。任何成功的 POST 请求该工具都返回{compacted: true}。压缩失败API 调用失败会记录日志自动继续流程会继续执行而不压缩非致命错误。竞态条件busy_sessions守卫已防止并发的自动继续从而保护压缩触发逻辑。