Craft 中 `/compact` 命令的端到端设计:基于 opencode summarize 的按需上下文压缩实现指南

原创2026-09-09 09:57:261,678 阅读
文章标签:人工智能AI 应用RAGAI Agent深度研究MCP 服务知识库搜索引擎企业应用后端前端数据集成

Craft 中 /compact 命令的端到端设计:基于 opencode summarize 的按需上下文压缩实现指南

本文以 compact-command.md 设计文档为骨架,结合 danswer(Onyx)仓库中 Craft 构建会话(Build Session)的真实源码,完整梳理 /compact 斜杠命令从"为什么需要"、opencode 协议契约、前后端实现策略、UX 到测试验证的完整链路。读者将掌握:Craft 会话中上下文窗口压缩的现有机制(CompactionPacket → CompactionMarker)如何复用,kind="compact" 交互式 turn 如何在既有 executor/streaming 管道中落地,以及如何把一条纯 POST 的 summarize 请求改造成可流式、可持久化的真实命令。

一、背景:为什么需要手动触发压缩

Craft 会话的上下文窗口由 opencode 负责管理,其默认策略是自动压缩:当上下文接近限制(本文档环境下 Opus 4.8 约为 1M token)时,opencode 会自动生成摘要并压缩历史。这套自动压缩的能力在 danswer 中已经通过"上下文窗口压缩功能"完整接入——即输入栏上方的 context ring 指示器 + CompactionPacket → CompactionMarker 的渲染链路。

但自动压缩存在明显的体验缺口:用户无法决定压缩时机。当用户希望在执行大任务之前、或者 ring 已经变为琥珀色(接近上限)时主动回收上下文,没有任何入口可用。/compact 命令正是为此而生——它是一个面向用户的斜杠命令,按需调用 opencode 的 summarize 端点,并把压缩结果作为转录(transcript)中已有的压缩标记(compaction marker)呈现出来。

关键设计定位:这是手动触发,而非新造一套压缩渲染管线。渲染路径已经建好且无需改动——本工作只负责"按需触发压缩 + 把它做成一级 picker 命令"。

二、opencode 压缩协议契约(v1.15.7 已验证)

2.1 端点与请求体

/compact 底层调用的 opencode 端点为:

POST /session/{sessionID}/summarize

请求体为:

{
  "providerID": "…",
  "modelID": "…",
  "auto": false
}

其中 auto: false 明确表示这是一次手动压缩请求,区别于 opencode 内部自动触发的压缩。

2.2 事件流与状态机

调用 summarize 之后,opencode 会:

  1. 生成一条 assistant 消息,其 info.summary === true 标记该消息为摘要消息;
  2. 发布 session.compacted {sessionID} 事件;
  3. 进入空闲状态(go idle)。

danswer 的翻译器(translator)已经对这套事件做好了处理:

  • 收到 session.compacted 时发出 CompactionPacket;
  • 抑制 summary:true 消息的可见文本(摘要正文不会作为普通消息渲染出来);
  • 通过 REST 把摘要文本附加到 CompactionPacket 上;
  • session.idle 通过 _emit_terminator 终止流,与普通 turn 完全一致。

因此 consume → translate → persist(消费事件 → 翻译 → 持久化)整条路径可以原样复用,零改动。

2.3 核心细节:只调用 summarize 不会显示任何东西

这是整个设计中最重要的一个 subtlety:单独发一个 POST /summarize 是"fire-and-forget",界面上什么都不会出现。压缩标记(marker)只有在 session.compacted / summary:true 事件流经 translate_opencode_event → CompactionPacket → 持久化/流式推送之后才会渲染。

所以 /compact 必须作为一个真正的流式 turn 运行,而不是一条丢弃结果的 POST。这直接决定了后端要以 kind="compact" 的完整交互式 turn 来实现,复用 cache-turn + 后台 runner + attach/resume 机制,获得与 send-message 相同的可靠性:marker 实时流式呈现,刷新后依然持久可见。

三、已锁定的产品决策

文档记录了几个与用户确认过的决策,实现时必须遵守:

决策项 结论
命令名 /compact(无前导点号)
后端运行方式 完整交互式 turn(kind="compact"),复用 cache-turn + 后台 runner + attach/resume 机制
Picker 分组 专属 Commands 分组,显示在 Skills / Apps 之上
定位 真实用户可见命令,而非测试钩子(同时它也是端到端演练压缩能力的按需入口)

3.1 Turn 的形状

一个 compact turn 有以下特殊之处:

  • 没有用户 prompt;
  • 不创建任何用户消息行(user message row);
  • 只产出压缩标记(compaction marker);
  • 附带一个间接效果:摘要消息的 token 统计会产生一个更新的 ContextUsagePacket,从而把 ring 刷新为压缩后的数值。

3.2 模型解析

summarize 需要 providerID / modelID。方案是直接使用会话上存储的 agent_provider / agent_model——这两个字段已经贯穿到 _streaming.yield_sandbox_events 中。如果两者都为 null(遗留行数据),则命令不可用,而不是去猜测模型。

四、前端实现:Picker 命令与触发链路

4.1 现状:Picker 模型与匹配逻辑

前端 picker 的模型与匹配逻辑集中在 web/src/lib/skills/picker.ts,目前已定义:

  • PickerSkill(kind: "skill")、PickerApp(kind: "app")、PickerMcpServer(kind: "mcp")三种条目;
  • PickerEntry 联合类型;
  • PickerSections 结构(skills / apps / mcpServers 三个数组);
  • toPickerSections(从 SkillsList、external apps、MCP servers 构造分组,并做过滤与排序);
  • 匹配与扁平化工具函数:filterPickerSections、flattenSections、detectSlashTrigger、matchesQuery。

4.2 新增 PickerCommand 条目

按设计文档,需要在 picker 中新增第四种条目:

interface PickerCommand {
  kind: "command";
  slug: string;
  name: string;
  description: string;
}

具体步骤:

  1. 扩展联合类型:把 PickerCommand 加入 PickerEntry 联合;
  2. 扩展分组:给 PickerSections 增加 commands 数组;
  3. 过滤:在 filterPickerSections 中纳入 commands(复用现有 matchesQuery);
  4. 排序:把 commands 放在 flattenSections 的最前面——这样才能保证键盘导航的索引与渲染顺序一致;
  5. 种子数据:内置一个静态的 compact 命令,无需服务端拉取。

4.3 渲染 Commands 分组

在 EntryPickerPopover 中把 "Commands" 分组渲染在 Skills / Apps 之上,并使用与 marker 相同的 SvgFold 图标(见 web/src/app/craft/components/CompactionMarker.tsx 第 30 行 SvgFold 的使用),让它在视觉上读起来是一个"动作"而非"技能"。

4.4 选择即动作:路由到 onCompact

在 web/src/app/craft/components/CraftInputBar.tsx 中,picker 的 onSelect 需要按条目类型分支:

  • 普通技能/应用:走现有 addEntry,生成 chip;
  • entry.kind === "command" && entry.slug === "compact":不插入任何文本,直接调用从 ChatPanel 传入的新 prop onCompact。

同样需要分支的路径包括:粘贴路径(paste path),以及(可选)+ 菜单中的 buildEntryMenuItems。当前的接线点包括 useSlashPicker({ onSelect: addEntry })、activeEntries chips、handleSubmit 的前缀逻辑。

4.5 可用性 gating

命令在以下情况下不可用(隐藏或禁用并带 tooltip):

  • 尚无 opencode_session_id(首轮 turn 之前);
  • 已有 turn 正在运行(isRunning);
  • 模型未知。

这样保证命令永远不会产生令人困惑的空操作(no-op)。

4.6 触发与附加:复用 useBuildStreaming

ChatPanel.onCompact 的流程设计为:

onCompact
  → POST /build/sessions/{id}/compact        # 返回与 send-message 相同的 turn 形状
  → 注册 active turn
  → 通过既有 useBuildStreaming 附加到 GET .../turns/{turn_id}/events
  → marker 实时流式呈现并持久化

前端不需要任何新的流式代码——web/src/app/craft/hooks/useBuildStreaming.ts 与 web/src/app/craft/hooks/useBuildSessionStore.ts 负责 active-turn 注册、appendStreamItem 与 CompactionMarker 渲染,这些全部复用。

运行期间展示一个瞬态的 "Compacting context…" 提示(复用 running/interrupt 的既有 affordance),在 terminator 到来时清除。

五、后端实现:kind="compact" 的交互式 turn

5.1 现状:交互式 turn 的基础设施

后端交互式 turn 的核心设施已经存在,均位于 backend/onyx/server/features/build 下:

  • Turn 状态:interactive_turns/state.py 定义了 InteractiveTurn dataclass(turn_id、session_id、user_id、prompt、status、turn_index、attachments 等)、InteractiveTurnStatus 枚举(QUEUED / RUNNING / SUCCEEDED / FAILED / CANCELLED)、create_interactive_turn、acquire_active_turn_lock(Redis 锁,lease 60 秒)等;
  • 后台执行器:interactive_turns/executor.py 提供 start_interactive_turn_runner 与 _drive_interactive_turn,让 turn 脱离浏览器响应流运行(刷新/重连不中断);
  • 事件附加:interactive_turns/api.py 提供 GET .../turns/{turn_id}/events;
  • 创建路由:session/messages.py 的 POST /build/sessions/{id}/send-message,内部依次执行 acquire_active_turn_lock → create_interactive_turn → start_interactive_turn_runner;
  • 驱动链路:session/streaming.py 的 BuildStreamingState 与 yield_sandbox_events,其中已导入并使用 CompactionPacket、ContextUsagePacket 等 packet 类型。

5.2 步骤 1:Turn 模型增加 kind 字段

在 InteractiveTurn(state.py)与 create_interactive_turn 中新增:

kind: Literal["prompt", "compact"] = "prompt"

并同步到 _save_turn / _load_turn 的序列化逻辑,保证 turn 在 cache 中往返后 kind 不丢失。

5.3 步骤 2:新增 compact 路由

在 session/messages.py 中新增 POST /build/sessions/{id}/compact,镜像 send-message 的创建路径,但:

  • kind="compact";
  • 空 prompt;
  • 使用下一个 turn_index(count_user_messages 的结果,与 send-message 一致);
  • 返回与 send-message 相同的响应形状(InteractiveTurnResponse),前端可以无缝复用 attach 逻辑;
  • 复用 active-turn 锁 + runner 启动;
  • 当 opencode_session_id 或模型缺失时直接拒绝。

5.4 步骤 3:驱动链路穿透 kind

把 kind 从 executor._drive_interactive_turn 穿透到 SessionManager.yield_sandbox_events(session/manager.py)再到 _streaming.yield_sandbox_events(session/streaming.py)。

当 kind == "compact" 时:

  • 调用新的 serve_client.compact() 而非 send_message;
  • 跳过用户消息持久化(不写 user message row)。

5.5 步骤 4:serve_client.compact() 生成器

在 backend/onyx/server/features/build/sandbox/opencode/serve_client.py 中新增 compact() 生成器,镜像现有 send_message(第 1329 行起)的结构:

  1. 订阅 pod 事件总线(self._event_bus.subscribe(...));
  2. 等待 /event 流就绪(_wait_for_event_stream_ready,避免 POST 后错过首屏事件);
  3. POST /session/{id}/summarize,body 为 {providerID, modelID, auto: false}——通过新增的 _post_summarize(作为 _post_prompt_async 的兄弟函数)发送;
  4. 通过 _consume_from_bus 消费事件,经 translate_opencode_event 翻译,直到 terminator。

无需改动 translator:session.compacted → CompactionPacket、summary:true 文本抑制、session.idle 终止这三件事已经工作正常。参考 send_message 的实现,compact() 也应正确处理浏览器断连(GeneratorExit → POST /abort)与超时逻辑,以获得与普通 turn 一致的生命周期语义。

5.6 明确无需改动的部分

以下模块已构建完成,且对自动/手动压缩的事件处理完全一致,不需要任何修改:

  • translate_opencode_event(事件翻译)
  • CompactionPacket(压缩数据包)
  • CompactionMarker(前端压缩标记渲染,含 "View summary" 折叠披露)
  • 持久化与重载(convertMessagesToStreamItems)

六、用户体验设计

/compact 的交互体验定义如下:

  • 在斜杠弹层顶部出现专属 Commands 分组,SvgFold 图标,标签 "Compact context",描述 "Summarize earlier context to free up space";输入 /comp… 即可匹配;
  • 选中后立即执行(不产生 chip、不插入文本),短暂显示 "Compacting context…" 状态,然后转录中会出现低调的压缩分隔线(带 "View summary" 披露控件),ring 指示器降至压缩后的数值;
  • 首轮 turn 之前、turn 运行中、模型未知时命令不可用——保证它永远不会变成令人困惑的空操作。

七、测试策略

7.1 后端测试

  • serve_client.compact():验证其向 /session/{id}/summarize 发送正确的 {providerID, modelID, auto} 请求体,并在构造的 session.compacted 事件上产出翻译后的 CompactionPacket——扩展现有 test_translate_opencode_event 的 fixtures(压缩/抑制翻译已有覆盖);
  • 路由测试:验证 kind="compact" 在 _streaming.yield_sandbox_events 中驱动 compact() 而非 send_message。

7.2 前端单元测试

  • web/src/lib/skills/picker.ts:命令出现在 sections 中、按 /comp 过滤、在 flattenSections 中排首位;
  • CraftInputBar:command 选择路由到 onCompact 而非 addEntry;
  • 可用性 gating 逻辑。

7.3 Playwright 端到端

可选(仅当 FE↔backend 的 attach 需要端到端覆盖时才加):打开 / → Commands 分组显示 Compact → 选中 → 断言 compact turn 启动且压缩标记渲染。否则以上单测已足够。

八、源码索引速查

关注点 仓库路径
本文档 docs/craft/features/compact-command.md
Picker 模型与匹配 web/src/lib/skills/picker.ts
输入栏接线 web/src/app/craft/components/CraftInputBar.tsx
压缩标记渲染 web/src/app/craft/components/CompactionMarker.tsx
前端流式附加 web/src/app/craft/hooks/useBuildStreaming.ts、web/src/app/craft/hooks/useBuildSessionStore.ts
Turn 状态模型 backend/onyx/server/features/build/interactive_turns/state.py
后台执行器 backend/onyx/server/features/build/interactive_turns/executor.py
创建/附加路由 backend/onyx/server/features/build/session/messages.py、backend/onyx/server/features/build/interactive_turns/api.py
流式驱动管线 backend/onyx/server/features/build/session/streaming.py
opencode serve 客户端 backend/onyx/server/features/build/sandbox/opencode/serve_client.py

九、小结

/compact 是一个"以小博大"的功能:渲染、翻译、持久化等核心链路全部复用既有上下文压缩机制,新增的工作集中在触发一侧——前端新增一个 PickerCommand 条目并路由到 onCompact,后端新增一个 kind="compact" 的交互式 turn 与 POST /build/sessions/{id}/compact 路由,以及 serve_client.compact() 这一镜像 send_message 的生成器。整条链路的关键约束是"必须以流式 turn 运行而非 fire-and-forget POST",否则 marker 永远不会渲染。这一设计同时让 /compact 成为端到端演练压缩能力的按需入口,兼具功能价值与可测试性。

登录后查看全文
danswer