From e23418c8ba235b23a6b78a4c1c75465f511abf1a Mon Sep 17 00:00:00 2001 From: wenshao Date: Fri, 3 Apr 2026 21:43:01 +0800 Subject: [PATCH] fix: apply post-merge audit fixes to input-queue-deep-dive.md MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Includes 5 rounds of fixes that were pushed to feat/input-queue-deep-dive after PR #29 squash-merged (only initial commit was included): 1. Audit fixes: drain() semantics, Qwen Code 3-layer cancel, line counts, Escape→cancelCurrentRound (queue preserved), other-agent table precision 2. Replace 排水→drain/queue drain terminology 3. Add Mid-Turn Queue Drain as core architectural difference (query.ts#L1550) 4. Align document with mid-turn drain thesis (architecture diagram, priority table, practical impact scenarios, agent comparison table, design insights) 5. Update for Qwen Code v0.15.0: follow-up suggestions + speculation (PR #2525) Co-Authored-By: Claude Opus 4.6 (1M context) --- docs/comparison/input-queue-deep-dive.md | 48 ++++++++++++++++++------ 1 file changed, 36 insertions(+), 12 deletions(-) diff --git a/docs/comparison/input-queue-deep-dive.md b/docs/comparison/input-queue-deep-dive.md index 79a30f0b..f69ca36b 100644 --- a/docs/comparison/input-queue-deep-dive.md +++ b/docs/comparison/input-queue-deep-dive.md @@ -1,6 +1,6 @@ # 输入队列与中断机制 Deep-Dive -> 当 AI Agent 正在执行工具调用时，用户能否继续输入？输入会被丢弃、阻塞，还是排队等待下一轮？本文基于 Claude Code（v2.1.89 反编译）和 Qwen Code（Gemini CLI fork，开源）的源码分析，深度对比两者在输入队列、中断机制和交互流畅性方面的设计差异。 +> 当 AI Agent 正在执行工具调用时，用户能否继续输入？输入会被丢弃、阻塞，还是排队等待下一轮？本文基于 Claude Code（v2.1.89 反编译）和 Qwen Code（v0.15.0，Gemini CLI fork，开源）的源码分析，深度对比两者在输入队列、中断机制和交互流畅性方面的设计差异。 --- @@ -430,12 +430,19 @@ abort(): void { // 3. 立即终止 ### 4.6 预测与预执行 -| 能力 | Claude Code | Qwen Code | +| 能力 | Claude Code | Qwen Code（v0.15.0+） | |------|------------|-----------| -| Prompt Suggestion | ✅ 预测下一步输入 | ❌ | -| Speculation | ✅ 预执行预测结果 | ❌ | -| Early Input | ✅ 启动阶段捕获键入 | ❌ | -| Tab 接受 | ✅ 预执行结果直接注入 | — | +| Prompt Suggestion | ✅ 默认开启 | ✅ 默认开启（`followupSuggestionsEnabled`） | +| Speculation | ✅（ant-only，`USER_TYPE === 'ant'`） | ✅ opt-in（`enableSpeculation: false` 默认关闭） | +| Overlay FS 隔离 | ✅ Copy-on-Write | ✅ Copy-on-Write（`/tmp/qwen-speculation/{pid}/`） | +| Tab 接受 → 结果注入 | ✅ 直接注入对话 | ✅ `acceptSpeculation()` → `addHistory()` | +| 工具安全分类 | ✅ `interruptBehavior` | ✅ `speculationToolGate.ts`（safe/write/boundary/unknown 4 类） | +| Pipelined Suggestion | ✅ speculation 完成后预生成下一个 | ✅ `generatePipelinedSuggestion()` | +| Early Input | ✅ 启动阶段 stdin 捕获 | ❌ | + +> **重要变化**：Qwen Code v0.15.0（2026-04-03 合入 `#2525`）新增了完整的 follow-up suggestions + speculation 系统，架构与 Claude Code 高度相似。但 speculation 默认关闭，需手动启用。 +> +> 源码: `qwen-code/packages/core/src/followup/`（6 个文件，~1,900 行）、`qwen-code/packages/cli/src/config/settingsSchema.ts#L520-L544` --- @@ -581,9 +588,22 @@ Claude Code 中断后队列**始终保留**（`messageQueueManager` 无 drain > 源码: Qwen Code `AgentComposer.tsx#L88`（Escape → `cancelCurrentRound()`） -### 6.3 Speculation 零等待 +### 6.3 Speculation 预执行 -Claude Code 的 Speculation 系统在用户还未输入时就预测并预执行下一步。当用户按 Tab 接受建议时，结果已经准备好——体感上是**零延迟**。Qwen Code 无此机制。 +两者现在都支持 Speculation 预执行，但启用状态不同： + +| 维度 | Claude Code | Qwen Code | +|------|------------|-----------| +| 默认状态 | ant-only 自动启用 | **默认关闭**（`enableSpeculation: false`） | +| 启用方式 | `USER_TYPE === 'ant'` | 用户手动在 settings 中开启 | +| Overlay FS | 内存级覆盖层 | `/tmp/qwen-speculation/{pid}/{uuid}/` | +| 工具限制 | `interruptBehavior` 区分 | `speculationToolGate` 分 4 类（safe/write/boundary/unknown） | +| 最大 turn 数 | 无硬编码上限 | `MAX_SPECULATION_TURNS = 20` | +| Tab 接受路径 | 注入对话历史 | `acceptSpeculation()` → `addHistory()` 绕过队列 | +| Cache 共享 | prompt cache breakpoint 机制 | `saveCacheSafeParams()` 捕获 cache 参数 | + +> Qwen Code 的 speculation 实现于 2026-04-03 合入（PR #2525），与 Claude Code 架构高度相似。 +> 源码: `qwen-code/packages/core/src/followup/speculation.ts`（563 行） --- @@ -592,7 +612,7 @@ Claude Code 的 Speculation 系统在用户还未输入时就预测并预执行 | Agent | 队列模型 | 执行中可输入 | Mid-Turn Drain | 优先级 | 中断粒度 | 预测/预执行 | |-------|----------|:-----------:|:--------------:|:------:|----------|:----------:| | **Claude Code** | 优先级队列 | ✅ | ✅ | 3 级 | 工具级 | ✅ | -| **Qwen Code** | FIFO 队列 | ✅ | ❌ | 无 | Round 级 | ❌ | +| **Qwen Code** | FIFO 队列 | ✅ | ❌ | 无 | Round 级 | ✅ opt-in | | **Gemini CLI** | FIFO 队列 | ✅ | ❌ | 无 | Round 级 | ❌ | | **Copilot CLI** | 无队列 | ⚠️ 无排队 | ❌ | — | 全局级 | ❌ | | **Aider** | 无队列 | ⚠️ 无排队 | ❌ | — | 全局级 | ❌ | @@ -626,6 +646,10 @@ Claude Code 的 Speculation 系统在用户还未输入时就预测并预执行 | `packages/core/src/utils/asyncMessageQueue.ts` | 54 | 通用 FIFO 队列 | | `packages/core/src/agents/runtime/agent-core.ts` | ~540 | 推理循环（`runReasoningLoop`，无 mid-turn drain） | | `packages/core/src/agents/runtime/agent-interactive.ts` | 512 | 交互代理（消息循环 + 三层取消） | +| `packages/core/src/followup/speculation.ts` | 563 | Speculation 引擎（v0.15.0 新增） | +| `packages/core/src/followup/suggestionGenerator.ts` | 367 | 建议生成 + 12 条过滤规则 | +| `packages/core/src/followup/overlayFs.ts` | 140 | Copy-on-Write overlay 文件系统 | +| `packages/core/src/followup/speculationToolGate.ts` | 146 | 工具安全分类（safe/write/boundary） | | `packages/cli/src/ui/contexts/KeypressContext.tsx` | ~170 | Ink 键盘输入捕获 | --- @@ -643,7 +667,7 @@ Claude Code 的 Speculation 系统在用户还未输入时就预测并预执行 ### 对用户 - Claude Code 用户可以在 Agent 执行时**放心输入**——输入不会丢失，会自动成为下一轮 -- Qwen Code 用户同样可以输入，但 `abort()` 后队列会被清空——避免在取消后依赖已排队的输入 -- Speculation 是 Claude Code 独有的"零等待"体验——但仅限 Anthropic 内部用户（`USER_TYPE === 'ant'`） +- Qwen Code 用户同样可以输入，但 `abort()` 后已排队输入被放弃（`drain()` 阻止新入队 + abort 信号使循环退出）——Escape 取消当前轮则队列保留 +- Speculation 预执行：Claude Code 仅限 Anthropic 内部用户（`USER_TYPE === 'ant'`）；Qwen Code v0.15.0 支持但默认关闭（需在 settings 中开启 `enableSpeculation`） -> **免责声明**: 以上分析基于 2026 年 Q1 源码，后续版本可能已变更。Qwen Code 为 Gemini CLI fork，其队列模型继承自 Gemini CLI。 +> **免责声明**: 以上分析基于 2026 年 Q1 源码（Claude Code v2.1.89、Qwen Code v0.15.0 commit `3bce84d`），后续版本可能已变更。Qwen Code 为 Gemini CLI fork，其队列模型继承自 Gemini CLI，follow-up suggestions + speculation 为 Qwen Code 独立实现。