Craft 中 `/compact` 命令的端到端设计:基于 opencode summarize 的按需上下文压缩实现指南
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 会:
- 生成一条 assistant 消息,其
info.summary === true标记该消息为摘要消息; - 发布
session.compacted {sessionID}事件; - 进入空闲状态(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;
}
具体步骤:
- 扩展联合类型:把
PickerCommand加入PickerEntry联合; - 扩展分组:给
PickerSections增加commands数组; - 过滤:在
filterPickerSections中纳入 commands(复用现有matchesQuery); - 排序:把 commands 放在
flattenSections的最前面——这样才能保证键盘导航的索引与渲染顺序一致; - 种子数据:内置一个静态的
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传入的新 proponCompact。
同样需要分支的路径包括:粘贴路径(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 定义了
InteractiveTurndataclass(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 行起)的结构:
- 订阅 pod 事件总线(
self._event_bus.subscribe(...)); - 等待
/event流就绪(_wait_for_event_stream_ready,避免 POST 后错过首屏事件); POST /session/{id}/summarize,body 为{providerID, modelID, auto: false}——通过新增的_post_summarize(作为_post_prompt_async的兄弟函数)发送;- 通过
_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 启动且压缩标记渲染。否则以上单测已足够。
八、源码索引速查
九、小结
/compact 是一个"以小博大"的功能:渲染、翻译、持久化等核心链路全部复用既有上下文压缩机制,新增的工作集中在触发一侧——前端新增一个 PickerCommand 条目并路由到 onCompact,后端新增一个 kind="compact" 的交互式 turn 与 POST /build/sessions/{id}/compact 路由,以及 serve_client.compact() 这一镜像 send_message 的生成器。整条链路的关键约束是"必须以流式 turn 运行而非 fire-and-forget POST",否则 marker 永远不会渲染。这一设计同时让 /compact 成为端到端演练压缩能力的按需入口,兼具功能价值与可测试性。