feat: add 17 items from PR #2866 + web articles + UX analysis (70→87)

docs/comparison/qwen-code-improvement-report-p0-p1.md

@@ -503,3 +503,27 @@
 **意义**：GitLab 在企业用户中占比显著——仅支持 GitHub 覆盖面不够。
 **缺失后果**：GitLab 用户无法在 CI 中集成 Agent。
 **改进收益**：覆盖 GitLab 用户群——企业级 CI 集成。
+
+---
+
+<a id="item-75"></a>
+
+### 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 `<Text dimColor>`）；新建 `utils/suggestions/` 目录实现命令/路径/历史三层补全。
+
+**意义**：命令补全是 CLI 工具最基础的 UX 期待——无补全等于每次都手打全名。
+**缺失后果**：用户需完整输入 `/compress`、文件路径等——效率低且易出错。
+**改进收益**：输入 `/com` 即显示 `/compress` 灰字，Tab 接受——打字量减半。

docs/comparison/qwen-code-improvement-report-p2.md

@@ -799,3 +799,333 @@
 **意义**：MCP 工具是 Agent 扩展能力的核心——连接中断会导致 Agent 丧失关键工具能力。
 **缺失后果**：MCP 服务器短暂不可用 → Agent 整个 session 的 MCP 工具失效——需手动重启。
 **改进收益**：瞬态故障自动恢复——用户无感知，Agent 持续使用 MCP 工具。
+
+---
+
+<a id="item-71"></a>
+
+### 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 完整文件，不浪费上下文。
+
+---
+
+<a id="item-72"></a>
+
+### 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% 需要重试，总体延迟降低。
+
+---
+
+<a id="item-73"></a>
+
+### 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 自动单线程重试——资源受限环境下仍能完成搜索。
+
+---
+
+<a id="item-74"></a>
+
+### 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 改代码后自动更新相关文档。
+
+---
+
+---
+
+<a id="item-76"></a>
+
+### 76. 目录/文件路径补全（P2）
+
+**思路**：输入含 `/` 或 `./` 时触发文件路径补全——扫描目录 + LRU 缓存避免重复 I/O。结合 `.gitignore` 过滤不相关文件。
+
+**Claude Code 源码索引**：
+
+| 文件 | 关键函数/常量 |
+|------|-------------|
+| `utils/suggestions/directoryCompletion.ts` | 路径扫描 + LRU 缓存 |
+
+**Qwen Code 修改方向**：`InputPrompt.tsx` 检测输入中的路径模式；新建 `utils/suggestions/directoryCompletion.ts` 扫描并缓存结果。
+
+**意义**：文件路径是 Agent 交互中最常输入的内容——补全直接提升效率。
+**缺失后果**：用户需完整输入文件路径——深层目录路径打字量大。
+**改进收益**：Tab 补全路径——减少打字量，避免路径拼写错误。
+
+---
+
+<a id="item-77"></a>
+
+### 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"。
+
+---
+
+<a id="item-78"></a>
+
+### 78. 权限对话框文件预览（P2）
+
+**思路**：权限审批对话框中显示将被操作的文件内容预览 + 语法高亮——用户看到具体变更内容再决定是否批准。
+
+**Claude Code 源码索引**：
+
+| 文件 | 关键函数/常量 |
+|------|-------------|
+| `components/permissions/` | 文件预览 + 语法高亮 + 上下文说明 |
+
+**Qwen Code 修改方向**：`PermissionsDialog.tsx` 的 tool confirmation 中增加文件内容预览区域。
+
+**意义**：盲目批准权限是安全隐患——用户需看到变更内容才能做出知情决策。
+**缺失后果**：用户只看到"Edit file.ts?"无法判断变更是否安全——倾向于全部批准。
+**改进收益**：预览 diff 后再批准——安全审批变得有意义。
+
+---
+
+<a id="item-79"></a>
+
+### 79. Token 使用实时警告（P2）
+
+**思路**：在 UI 中实时显示 token 使用量、压缩进度、错误计数。不是在 `/stats` 命令中查看，而是在操作过程中自动浮现警告。
+
+**Claude Code 源码索引**：
+
+| 文件 | 关键函数/常量 |
+|------|-------------|
+| `components/TokenWarning.tsx` | 实时 token 警告 + 压缩状态 |
+
+**Qwen Code 修改方向**：在 `Footer.tsx` 的 `ContextUsageDisplay` 中增加警告阈值——超过 80% 时高亮显示。
+
+**意义**：用户不应该被上下文溢出"突袭"——应提前可视化预警。
+**缺失后果**：用户无感知地用完上下文 → 突然报错中断工作流。
+**改进收益**：80% 时黄色警告 → 90% 红色警告——用户提前 /compress。
+
+---
+
+<a id="item-80"></a>
+
+### 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 可以展开——功能可发现性差。
+**改进收益**：操作旁边即显示快捷键——"边用边学"。
+
+---
+
+<a id="item-81"></a>
+
+### 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 完成后用户不知道——浪费等待时间。
+**改进收益**：终端标签显示 ✓ 或弹出通知——无需切回即知完成。
+
+---
+
+<a id="item-82"></a>
+
+### 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"——知道在做什么、花了多久。
+
+---
+
+<a id="item-83"></a>
+
+### 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 步的部分有用工作。
+**改进收益**：选择检查点精确回退——保留有用变更，撤销错误变更。
+
+---
+
+<a id="item-84"></a>
+
+### 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 环境无障碍。
+
+---
+
+<a id="item-85"></a>
+
+### 85. 首次运行引导向导（P2）
+
+**思路**：首次运行显示多步引导——主题选择 → 认证（OAuth/API Key）→ 安全设置 → 终端优化建议。每步有分析追踪确保完成率。
+
+**Claude Code 源码索引**：
+
+| 文件 | 关键函数/常量 |
+|------|-------------|
+| `components/Onboarding.tsx` | 多步引导 UI |
+| `utils/config.ts` | `checkHasTrustDialogAccepted()` |
+
+**Qwen Code 修改方向**：`gemini.tsx` 首次运行检测 → 新建 `Onboarding.tsx` 多步向导组件。
+
+**意义**：第一印象决定工具留存率——无引导的首次体验让新用户迷茫。
+**缺失后果**：新用户不知道如何认证、不知道有 QWEN.md、不知道权限模式——流失。
+**改进收益**：3 分钟引导完成所有设置——新用户即刻高效使用。
+
+---
+
+<a id="item-86"></a>
+
+### 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 秒列出所有问题 + 修复建议——自助排障。
+
+---
+
+<a id="item-87"></a>
+
+### 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——变更一目了然，审查效率提升。