diff --git a/docs/comparison/qwen-code-improvement-report-p0-p1.md b/docs/comparison/qwen-code-improvement-report-p0-p1.md index 05016df5..af231c42 100644 --- a/docs/comparison/qwen-code-improvement-report-p0-p1.md +++ b/docs/comparison/qwen-code-improvement-report-p0-p1.md @@ -503,3 +503,27 @@ **意义**:GitLab 在企业用户中占比显著——仅支持 GitHub 覆盖面不够。 **缺失后果**:GitLab 用户无法在 CI 中集成 Agent。 **改进收益**:覆盖 GitLab 用户群——企业级 CI 集成。 + +--- + + + +### 75. Ghost Text 输入补全(P1) + +**思路**:用户输入时在光标后显示灰色建议文字(ghost text)——命令名、文件路径、shell history 三层。Tab/Right Arrow 接受。建议仅在光标位于正确插入点时显示。 + +**Claude Code 源码索引**: + +| 文件 | 关键函数/常量 | +|------|-------------| +| `types/textInputTypes.ts` | `InlineGhostText` 类型定义 | +| `hooks/useTextInput.ts` | ghost text 渲染 + `insertPosition === offset` 检查 | +| `utils/suggestions/commandSuggestions.ts` | 命令名模糊匹配 | +| `utils/suggestions/directoryCompletion.ts` | 路径补全 + LRU 缓存 | +| `utils/suggestions/shellHistoryCompletion.ts` | `~/.bash_history` 缓存 | + +**Qwen Code 修改方向**:`InputPrompt.tsx` 新增 ghost text 渲染层(Ink ``);新建 `utils/suggestions/` 目录实现命令/路径/历史三层补全。 + +**意义**:命令补全是 CLI 工具最基础的 UX 期待——无补全等于每次都手打全名。 +**缺失后果**:用户需完整输入 `/compress`、文件路径等——效率低且易出错。 +**改进收益**:输入 `/com` 即显示 `/compress` 灰字,Tab 接受——打字量减半。 diff --git a/docs/comparison/qwen-code-improvement-report-p2.md b/docs/comparison/qwen-code-improvement-report-p2.md index 5eef4f1b..bdd85265 100644 --- a/docs/comparison/qwen-code-improvement-report-p2.md +++ b/docs/comparison/qwen-code-improvement-report-p2.md @@ -799,3 +799,333 @@ **意义**:MCP 工具是 Agent 扩展能力的核心——连接中断会导致 Agent 丧失关键工具能力。 **缺失后果**:MCP 服务器短暂不可用 → Agent 整个 session 的 MCP 工具失效——需手动重启。 **改进收益**:瞬态故障自动恢复——用户无感知,Agent 持续使用 MCP 工具。 + +--- + + + +### 71. Tool Result 大小限制(P2) + +**思路**:每个工具定义 `maxResultSizeChars`(如 100K 字符)。超限结果持久化到磁盘文件,模型收到预览 + 文件路径而非完整内容——防止单个巨大工具结果占满上下文。 + +**Claude Code 源码索引**: + +| 文件 | 关键函数/常量 | +|------|-------------| +| `Tool.ts` | `maxResultSizeChars` 工具属性 | +| 各工具(TaskStopTool/NotebookEditTool/SkillTool 等) | `maxResultSizeChars: 100_000` | + +**Qwen Code 修改方向**:`BaseDeclarativeTool` 新增 `maxResultSizeChars` 属性;工具执行后检查结果字符数,超限时写入 temp 文件 + 返回预览。 + +**意义**:单个大文件 Read 或长命令输出可能超过 100K 字符——直接塞入上下文会溢出。 +**缺失后果**:大结果直接注入 → 上下文溢出或挤占其他内容空间。 +**改进收益**:大结果自动落盘 + 预览——模型需要时可 Read 完整文件,不浪费上下文。 + +--- + + + +### 72. Output Token 升级重试(P2) + +**思路**:首次请求用保守的 `max_output_tokens = 8_000`(BQ p99 仅 4911 tokens)。如果 `stop_reason === 'max_tokens'`,自动用 `64_000` 重试一次——避免默认预留过多槽位。 + +**Claude Code 源码索引**: + +| 文件 | 关键函数/常量 | +|------|-------------| +| `utils/context.ts` | `CAPPED_DEFAULT_MAX_TOKENS = 8_000`、`ESCALATED_MAX_TOKENS = 64_000` | +| `query.ts` (L1205) | `max_output_tokens_escalate` 重试逻辑 | + +**Qwen Code 修改方向**:`contentGenerator.ts` 首次请求用较小 `maxOutputTokens`;`agent-core.ts` 检测截断后自动升级重试。 + +**意义**:默认 32K/64K max_output_tokens 过度预留——浪费 API 槽位容量,增加延迟。 +**缺失后果**:每次请求都预留 32K+ 输出槽位——即使大多数响应 <5K tokens。 +**改进收益**:8K 首次 + 64K 重试——99% 请求用 8K 就够,<1% 需要重试,总体延迟降低。 + +--- + + + +### 73. Ripgrep 三级回退(P2) + +**思路**:Grep 工具解析 `rg` 二进制通过三级回退:系统安装 → Bun 内嵌 → 平台特定 vendored 二进制。EAGAIN 错误(资源不足)时自动用 `-j 1`(单线程)重试。 + +**Claude Code 源码索引**: + +| 文件 | 关键函数/常量 | +|------|-------------| +| `utils/ripgrep.ts` | `isEagainError()`(L83)、`-j 1` 单线程重试(L390-391) | + +**Qwen Code 修改方向**:`ripgrepUtils.ts` 新增 EAGAIN 检测 + `-j 1` 重试;增加 rg 二进制回退链。 + +**意义**:CI 容器和资源受限环境中 rg 可能 EAGAIN 失败——静默失败导致搜索不全。 +**缺失后果**:rg EAGAIN → 搜索失败 → Agent 误认为无匹配结果。 +**改进收益**:EAGAIN 自动单线程重试——资源受限环境下仍能完成搜索。 + +--- + + + +### 74. MAGIC DOC 自更新文档(P2) + +**思路**:标记 `# MAGIC DOC: [title]` 的 markdown 文件在 Agent 空闲时自动更新。后台 forked subagent 读取文件 + 项目上下文 → 更新内容。单文件范围限制防止越界。支持自定义 prompt(`~/.claude/magic-docs/prompt.md`)。 + +**Claude Code 源码索引**: + +| 文件 | 关键函数/常量 | +|------|-------------| +| `services/MagicDocs/prompts.ts` | 更新 Prompt 模板(保留 header、实质性变更才更新) | +| `services/MagicDocs/` | 触发逻辑 + forked agent 调度 | + +**Qwen Code 修改方向**:新建 `services/magicDocs/`;检测 `# MAGIC DOC:` header 的文件;空闲时 fork agent 执行更新。 + +**意义**:项目文档(API 参考、架构说明)容易过时——Agent 修改代码后文档不同步。 +**缺失后果**:代码改了但文档没更新——新成员读到过时文档。 +**改进收益**:标记的文档自动保持最新——Agent 改代码后自动更新相关文档。 + +--- + +--- + + + +### 76. 目录/文件路径补全(P2) + +**思路**:输入含 `/` 或 `./` 时触发文件路径补全——扫描目录 + LRU 缓存避免重复 I/O。结合 `.gitignore` 过滤不相关文件。 + +**Claude Code 源码索引**: + +| 文件 | 关键函数/常量 | +|------|-------------| +| `utils/suggestions/directoryCompletion.ts` | 路径扫描 + LRU 缓存 | + +**Qwen Code 修改方向**:`InputPrompt.tsx` 检测输入中的路径模式;新建 `utils/suggestions/directoryCompletion.ts` 扫描并缓存结果。 + +**意义**:文件路径是 Agent 交互中最常输入的内容——补全直接提升效率。 +**缺失后果**:用户需完整输入文件路径——深层目录路径打字量大。 +**改进收益**:Tab 补全路径——减少打字量,避免路径拼写错误。 + +--- + + + +### 77. 上下文 Tips 系统(P2) + +**思路**:基于当前配置、IDE 类型、插件状态、session 历史等条件动态显示提示(如"检测到 VS Code,推荐安装 Claude Code 扩展")。Tips 注册表管理所有提示及其触发条件。 + +**Claude Code 源码索引**: + +| 文件 | 关键函数/常量 | +|------|-------------| +| `services/tips/tipRegistry.ts` | `getActiveNotices()` + 条件过滤 | + +**Qwen Code 修改方向**:新建 `services/tips/`;定义 tips 数组(条件 + 消息);启动和 session 中检查条件并显示。 + +**意义**:新用户不知道可用功能——提示系统引导功能发现。 +**缺失后果**:用户不知道 `/compress`、`/review` 等功能存在——使用率低。 +**改进收益**:上下文提示引导——"你的上下文已用 80%,试试 /compress"。 + +--- + + + +### 78. 权限对话框文件预览(P2) + +**思路**:权限审批对话框中显示将被操作的文件内容预览 + 语法高亮——用户看到具体变更内容再决定是否批准。 + +**Claude Code 源码索引**: + +| 文件 | 关键函数/常量 | +|------|-------------| +| `components/permissions/` | 文件预览 + 语法高亮 + 上下文说明 | + +**Qwen Code 修改方向**:`PermissionsDialog.tsx` 的 tool confirmation 中增加文件内容预览区域。 + +**意义**:盲目批准权限是安全隐患——用户需看到变更内容才能做出知情决策。 +**缺失后果**:用户只看到"Edit file.ts?"无法判断变更是否安全——倾向于全部批准。 +**改进收益**:预览 diff 后再批准——安全审批变得有意义。 + +--- + + + +### 79. Token 使用实时警告(P2) + +**思路**:在 UI 中实时显示 token 使用量、压缩进度、错误计数。不是在 `/stats` 命令中查看,而是在操作过程中自动浮现警告。 + +**Claude Code 源码索引**: + +| 文件 | 关键函数/常量 | +|------|-------------| +| `components/TokenWarning.tsx` | 实时 token 警告 + 压缩状态 | + +**Qwen Code 修改方向**:在 `Footer.tsx` 的 `ContextUsageDisplay` 中增加警告阈值——超过 80% 时高亮显示。 + +**意义**:用户不应该被上下文溢出"突袭"——应提前可视化预警。 +**缺失后果**:用户无感知地用完上下文 → 突然报错中断工作流。 +**改进收益**:80% 时黄色警告 → 90% 红色警告——用户提前 /compress。 + +--- + + + +### 80. 快捷键提示组件(P2) + +**思路**:统一的 `KeyboardShortcutHint` 组件在 UI 各处显示当前操作的快捷方式(如 "(Ctrl+O to expand)"),且会根据用户自定义 keybindings 动态更新显示。 + +**Claude Code 源码索引**: + +| 文件 | 关键函数/常量 | +|------|-------------| +| `components/design-system/KeyboardShortcutHint.tsx` | 统一快捷键提示渲染 | +| `keybindings/useShortcutDisplay.ts` | `useShortcutDisplay()` 读取实际绑定 | + +**Qwen Code 修改方向**:新建 `KeyboardShortcutHint` 组件;各对话框/footer 使用统一提示;读取 keybindings 配置动态更新文本。 + +**意义**:用户记不住所有快捷键——UI 中随处可见的提示降低学习成本。 +**缺失后果**:用户不知道 Escape 可以取消、Ctrl+O 可以展开——功能可发现性差。 +**改进收益**:操作旁边即显示快捷键——"边用边学"。 + +--- + + + +### 81. 终端完成通知(P2) + +**思路**:后台任务完成时通过 OSC 转义序列通知终端——iTerm2 notification、Kitty notification、Ghostty notification 各有专用 OSC。同时上报进度百分比,终端标签可显示进度。 + +**Claude Code 源码索引**: + +| 文件 | 关键函数/常量 | +|------|-------------| +| `ink/useTerminalNotification.ts` | iTerm2/Kitty/Ghostty OSC 序列 + 进度状态 | + +**Qwen Code 修改方向**:`attentionNotification.ts` 从仅 bell 扩展为终端类型检测 + 对应 OSC 通知序列。 + +**意义**:用户切换到其他窗口后不知道 Agent 何时完成——需反复切回查看。 +**缺失后果**:Agent 完成后用户不知道——浪费等待时间。 +**改进收益**:终端标签显示 ✓ 或弹出通知——无需切回即知完成。 + +--- + + + +### 82. Spinner 工具名 + 计时(P2) + +**思路**:Spinner 不再只显示"Responding",而是显示当前执行的工具名 + 已用时间——如"Bash(npm test) · 15s"。工具名从 `spinnerVerbs.ts` 的动词表中选择友好显示。 + +**Claude Code 源码索引**: + +| 文件 | 关键函数/常量 | +|------|-------------| +| `constants/spinnerVerbs.ts` | 工具→动词映射("Accomplishing"/"Architecting"等) | +| `components/Spinner/SpinnerAnimationRow.tsx` | `elapsedTimeMs` 实时显示 | + +**Qwen Code 修改方向**:`SpinnerLabel.tsx` 从当前执行的工具调用中提取工具名;新增 `startTime` 计时并格式化显示。 + +**意义**:用户不知道 Agent 在做什么、要等多久——焦虑感强。 +**缺失后果**:只看到通用 spinner——"它卡了吗?还在跑吗?" +**改进收益**:看到"Bash(npm test) · 15s"——知道在做什么、花了多久。 + +--- + + + +### 83. /rewind 检查点回退(P2) + +**思路**:`/rewind` 命令恢复代码和对话到之前的检查点——结合 file history snapshots 和 git 状态。交互式检查点选择器展示每个点的变更摘要。 + +**Claude Code 源码索引**: + +| 文件 | 关键函数/常量 | +|------|-------------| +| `commands/rewind/index.ts` | /rewind(别名 checkpoint)命令 | +| `utils/fileHistory.ts` | snapshot 恢复逻辑 | + +**Qwen Code 修改方向**:新建 `/rewind` 命令;结合已有 checkpointing(git worktree)实现交互式回退。 + +**意义**:Agent 执行到第 5 步发现第 3 步就错了——需要精确回退。 +**缺失后果**:只能 git checkout 回退全部——无法保留第 4-5 步的部分有用工作。 +**改进收益**:选择检查点精确回退——保留有用变更,撤销错误变更。 + +--- + + + +### 84. /copy OSC 52 剪贴板(P2) + +**思路**:`/copy` 命令通过 OSC 52 转义序列将内容写入系统剪贴板——SSH 远程环境也能工作。终端不支持 OSC 52 时自动回退到 temp 文件 + 提示路径。 + +**Claude Code 源码索引**: + +| 文件 | 关键函数/常量 | +|------|-------------| +| `commands/copy/copy.tsx` | OSC 52 剪贴板 + temp 文件回退 | + +**Qwen Code 修改方向**:新建 `/copy` 命令;`process.stdout.write('\x1b]52;c;' + base64(content) + '\x07')` 实现 OSC 52。 + +**意义**:SSH 远程环境中无法 Ctrl+C 复制终端内容——/copy 是唯一途径。 +**缺失后果**:远程用户无法复制 Agent 输出——需手动选择文本。 +**改进收益**:`/copy` 一键复制到本地剪贴板——SSH 环境无障碍。 + +--- + + + +### 85. 首次运行引导向导(P2) + +**思路**:首次运行显示多步引导——主题选择 → 认证(OAuth/API Key)→ 安全设置 → 终端优化建议。每步有分析追踪确保完成率。 + +**Claude Code 源码索引**: + +| 文件 | 关键函数/常量 | +|------|-------------| +| `components/Onboarding.tsx` | 多步引导 UI | +| `utils/config.ts` | `checkHasTrustDialogAccepted()` | + +**Qwen Code 修改方向**:`gemini.tsx` 首次运行检测 → 新建 `Onboarding.tsx` 多步向导组件。 + +**意义**:第一印象决定工具留存率——无引导的首次体验让新用户迷茫。 +**缺失后果**:新用户不知道如何认证、不知道有 QWEN.md、不知道权限模式——流失。 +**改进收益**:3 分钟引导完成所有设置——新用户即刻高效使用。 + +--- + + + +### 86. /doctor 诊断工具(P2) + +**思路**:`/doctor` 检查系统环境健康——git 版本、Node.js/Bun 版本、shell 类型、权限配置、代理设置、MCP 服务器状态。输出可操作的修复建议。 + +**Claude Code 源码索引**: + +| 文件 | 关键函数/常量 | +|------|-------------| +| `utils/doctorDiagnostic.ts` | 环境检查 + 修复建议 | + +**Qwen Code 修改方向**:新建 `/doctor` 命令;检查 git/node/shell/rg 版本 + MCP 连接 + 权限配置。 + +**意义**:用户遇到问题时不知如何诊断——/doctor 一键定位。 +**缺失后果**:环境问题导致 Agent 异常——用户需手动逐项排查。 +**改进收益**:`/doctor` 5 秒列出所有问题 + 修复建议——自助排障。 + +--- + + + +### 87. 结构化 Diff 渲染(P2) + +**思路**:文件编辑后展示结构化 diff——Rust NAPI 快速着色 + 行号 gutter 列 + 语法高亮。比基础 inline diff 更易读。 + +**Claude Code 源码索引**: + +| 文件 | 关键函数/常量 | +|------|-------------| +| `components/StructuredDiff.tsx` | diff 渲染 UI | +| `native-ts/color-diff/` | Rust NAPI 着色 | + +**Qwen Code 修改方向**:`ToolMessage.tsx` 中编辑结果展示替换为结构化 diff 组件(可用 JS diff 库替代 Rust NAPI)。 + +**意义**:Diff 是用户审查 Agent 变更的核心界面——可读性直接影响审查质量。 +**缺失后果**:基础 inline diff 在大变更时难以阅读——用户可能遗漏关键修改。 +**改进收益**:行号 + 着色 + gutter——变更一目了然,审查效率提升。 diff --git a/docs/comparison/qwen-code-improvement-report.md b/docs/comparison/qwen-code-improvement-report.md index 2bc53fa7..c8ab0bba 100644 --- a/docs/comparison/qwen-code-improvement-report.md +++ b/docs/comparison/qwen-code-improvement-report.md @@ -83,6 +83,23 @@ | **P2** | /batch 并行操作 — 编排大规模并行变更(多文件/多任务)[↓](./qwen-code-improvement-report-p2.md#item-50) | 缺失 | 中 | — | | **P2** | Chrome Extension — 调试 live web 应用(读 DOM/Console/Network)[↓](./qwen-code-improvement-report-p2.md#item-51) | 缺失 | 中 | — | | **P2** | MCP Auto-Reconnect — 连续 3 次错误自动重连 + SSE 断线恢复 [↓](./qwen-code-improvement-report-p2.md#item-70) | 缺失 | 小 | — | +| **P2** | Tool Result 大小限制 — 超限结果持久化到磁盘,发文件路径给模型 [↓](./qwen-code-improvement-report-p2.md#item-71) | 缺失 | 小 | — | +| **P2** | Output Token 升级重试 — 首次 8K 截断后自动 64K 重试 [↓](./qwen-code-improvement-report-p2.md#item-72) | 缺失 | 小 | — | +| **P2** | Ripgrep 三级回退 — System→Embedded→Builtin + EAGAIN 单线程重试 [↓](./qwen-code-improvement-report-p2.md#item-73) | 缺失 | 小 | — | +| **P2** | MAGIC DOC 自更新文档 — 空闲时 Agent 自动更新标记文件的内容 [↓](./qwen-code-improvement-report-p2.md#item-74) | 缺失 | 中 | — | +| **P1** | Ghost Text 输入补全 — 输入时显示命令/路径建议灰字,Tab 接受 [↓](./qwen-code-improvement-report-p0-p1.md#item-75) | 缺失 | 中 | — | +| **P2** | 目录/文件路径补全 — 输入路径时 Tab 补全 + LRU 缓存 [↓](./qwen-code-improvement-report-p2.md#item-76) | 缺失 | 小 | — | +| **P2** | 上下文 Tips 系统 — 根据配置/IDE/插件状态显示上下文相关提示 [↓](./qwen-code-improvement-report-p2.md#item-77) | 缺失 | 小 | — | +| **P2** | 权限对话框文件预览 — 审批时展示文件内容 + 语法高亮 + 上下文说明 [↓](./qwen-code-improvement-report-p2.md#item-78) | 缺失 | 中 | — | +| **P2** | Token 使用实时警告 — 显示 token 用量 + 压缩进度 + 错误计数 [↓](./qwen-code-improvement-report-p2.md#item-79) | 仅基础显示 | 小 | — | +| **P2** | 快捷键提示组件 — UI 全局统一显示当前操作的键盘快捷方式 [↓](./qwen-code-improvement-report-p2.md#item-80) | 缺失 | 小 | — | +| **P2** | 终端完成通知 — 后台任务完成时 iTerm2/Kitty/Ghostty OSC 通知 + 进度百分比 [↓](./qwen-code-improvement-report-p2.md#item-81) | 仅 bell | 小 | — | +| **P2** | Spinner 工具名 + 计时 — 显示"正在执行 Bash(npm test) · 15s"而非通用 spinner [↓](./qwen-code-improvement-report-p2.md#item-82) | 通用 Responding | 小 | — | +| **P2** | /rewind 检查点回退 — 会话内代码 + 对话恢复到之前的检查点 [↓](./qwen-code-improvement-report-p2.md#item-83) | 缺失 | 中 | — | +| **P2** | /copy OSC 52 剪贴板 — 复制代码块到剪贴板,OSC 52 + temp 文件回退 [↓](./qwen-code-improvement-report-p2.md#item-84) | 缺失 | 小 | — | +| **P2** | 首次运行引导向导 — 主题/认证/API Key/安全/终端设置多步引导 [↓](./qwen-code-improvement-report-p2.md#item-85) | 缺失 | 中 | — | +| **P2** | /doctor 诊断工具 — 系统环境检查(git/node/shell/权限/代理)[↓](./qwen-code-improvement-report-p2.md#item-86) | 缺失 | 小 | — | +| **P2** | 结构化 Diff 渲染 — Rust NAPI 快速着色 + 行号 gutter + 语法高亮 [↓](./qwen-code-improvement-report-p2.md#item-87) | 基础 inline diff | 中 | — | | **P1** | Structured Output — `--json-schema` 强制 JSON Schema 验证输出 [↓](./qwen-code-improvement-report-p0-p1.md#item-17) | 缺失 | 小 | — | | **P1** | Agent SDK 增强 — Python SDK + 流式回调 + 工具审批回调(Qwen 仅 TS SDK)[↓](./qwen-code-improvement-report-p0-p1.md#item-18) | 仅 TypeScript SDK | 中 | — | | **P1** | Bare Mode — `--bare` 跳过所有自动发现,CI/脚本最快启动 [↓](./qwen-code-improvement-report-p0-p1.md#item-19) | 缺失 | 小 | — | @@ -116,8 +133,8 @@ | 文件 | 内容 | 项数 | |------|------|:----:| -| [P0/P1 详细说明](./qwen-code-improvement-report-p0-p1.md) | 最高优先级(Mid-Turn Drain、压缩、Fork、记忆、并行等) | 22 | -| [P2 详细说明](./qwen-code-improvement-report-p2.md) | 中等优先级(Shell 安全、MDM、Computer Use、Deep Link 等) | 37 | +| [P0/P1 详细说明](./qwen-code-improvement-report-p0-p1.md) | 最高优先级(Mid-Turn Drain、压缩、Fork、记忆、并行、Ghost Text 等) | 23 | +| [P2 详细说明](./qwen-code-improvement-report-p2.md) | 中等优先级(Shell 安全、MDM、Computer Use、终端渲染、/rewind 等) | 53 | | [P3 详细说明](./qwen-code-improvement-report-p3.md) | 低优先级(Feature Gates、Vim、语音、插件市场等) | 11 | ## 四、架构差异总结