diff --git a/docs/comparison/computer-use-deep-dive.md b/docs/comparison/computer-use-deep-dive.md new file mode 100644 index 00000000..a0a89f7d --- /dev/null +++ b/docs/comparison/computer-use-deep-dive.md @@ -0,0 +1,131 @@ +# Computer Use 桌面自动化 Deep-Dive + +> AI Agent 能否操作桌面应用——截图、点击、打字、读剪贴板？本文基于 Claude Code（v2.1.89 源码分析）的源码分析，介绍其 Computer Use 桌面自动化架构。Qwen Code 目前无此功能。 + +--- + +## 1. 架构总览 + +``` +Claude Code CLI + ↓ MCP 协议 +Computer Use MCP Server（进程内 stdio 传输） + ↓ NAPI +┌─────────────────────────────────┐ +│ @ant/computer-use-swift │ ← 截图（SCContentFilter） +│ @ant/computer-use-input (Rust) │ ← 鼠标/键盘（enigo） +└─────────────────────────────────┘ + ↓ macOS API +NSWorkspace / TCC / IOKit +``` + +| 维度 | 详情 | +|------|------| +| **集成方式** | MCP Server（进程内，stdio 传输） | +| **截图** | `SCContentFilter`（macOS ScreenCaptureKit） | +| **输入控制** | Rust `enigo` NAPI 绑定 | +| **权限** | TCC Accessibility + Screen Recording | +| **门控** | GrowthBook `tengu_malort_pedway` + Max/Pro 订阅 | +| **工具名** | `mcp__computer-use__*` | + +--- + +## 2. 截图捕获 + +```typescript +// 源码: utils/computerUse/swiftLoader.ts +// 通过 NAPI 加载 @ant/computer-use-swift +// 方法: captureExcluding(), captureRegion(), screenshot +// JPEG 质量: 0.75 +// 坐标缩放: 逻辑坐标 → 物理像素 → API 目标尺寸 +``` + +**终端豁免**：截图时自动隐藏终端窗口（避免截到 Agent 自身 UI）。通过 `getTerminalBundleId()` 检测当前终端：iTerm、Terminal.app、Ghostty、Kitty、Warp、VS Code。 + +--- + +## 3. 鼠标/键盘控制 + +| 操作 | 实现 | 参数 | +|------|------|------| +| `moveMouse()` | 瞬移 + 50ms 稳定延迟 | x, y | +| `click()` | 支持修饰键（press/release 括号化） | button, modifiers | +| `drag()` | ease-out-cubic 动画，60fps，2000px/s，最大 0.5s | start, end | +| `scroll()` | 垂直优先 | dx, dy | +| `key()` / `keys()` | 通过 DispatchQueue.main 分发 | key name, modifiers | +| `holdKey()` | press/release 追踪防止修饰键卡住 | key, action | +| `type()` | 剪贴板粘贴（含回读验证）或直接 typeText() | text | + +**Run Loop 排空**：`drainRunLoop()` 确保 main-queue dispatch 事件到达——30s 超时上限，orphan 标志防护。 + +> 源码: `utils/computerUse/executor.ts` + +--- + +## 4. TCC 权限 + +```typescript +// 源码: utils/computerUse/hostAdapter.ts#L47-L54 +// 启动时检查: +checkAccessibility() // 辅助功能权限（鼠标/键盘控制） +checkScreenRecording() // 屏幕录制权限（截图捕获） +// 两项均需批准才能使用 Computer Use +``` + +--- + +## 5. MCP 集成 + +```typescript +// 源码: utils/computerUse/setup.ts#L23-L53 +// Server 配置: +{ + type: 'stdio', // 进程内传输 + command: process.execPath, // 自身二进制 + args: ['--computer-use-mcp'], // MCP 入口 + scope: 'dynamic', // 按需启动 +} +// 工具名: mcp__computer-use__screenshot, mcp__computer-use__click, ... +// 权限: buildComputerUseTools() 自动添加 allowed tools（绕过权限提示） +``` + +**CallTool 覆盖**（源码: `utils/computerUse/wrapper.tsx`）：拦截 MCP callTool，注入权限对话框、状态管理、锁获取和截图持久化。 + +--- + +## 6. 门控与限制 + +| 门控 | 条件 | +|------|------| +| GrowthBook | `tengu_malort_pedway` 特性开关 | +| 订阅 | Max / Pro 订阅（Ant 用户绕过） | +| 平台 | 仅 macOS（SCContentFilter 依赖） | +| 并发 | 文件锁（`computerUseLock.ts`）防止并发 CU 会话 | +| 中止 | Cmd+Escape 热键（`escHotkey.ts` 通过 event-tap 注册） | + +**子门控**（GrowthBook 动态配置）： +- `pixelValidation` — 像素级操作验证 +- `clipboardPasteMultiline` — 多行剪贴板粘贴 +- `mouseAnimation` — 鼠标拖拽动画 +- `hideBeforeAction` — 操作前隐藏终端 +- `autoTargetDisplay` — 自动选择目标显示器 +- `clipboardGuard` — 剪贴板保护 + +--- + +## 7. 关键源码文件 + +| 文件 | 职责 | +|------|------| +| `utils/computerUse/mcpServer.ts` | MCP Server 入口 | +| `utils/computerUse/executor.ts` | 鼠标/键盘/截图执行 | +| `utils/computerUse/hostAdapter.ts` | TCC 权限检查 | +| `utils/computerUse/swiftLoader.ts` | SCContentFilter NAPI | +| `utils/computerUse/inputLoader.ts` | enigo/keyboard NAPI | +| `utils/computerUse/gates.ts` | GrowthBook 门控 | +| `utils/computerUse/setup.ts` | MCP 配置 | +| `utils/computerUse/wrapper.tsx` | CallTool 覆盖 | +| `utils/computerUse/computerUseLock.ts` | 并发文件锁 | +| `utils/computerUse/escHotkey.ts` | Cmd+Escape 中止热键 | + +> **免责声明**: 以上分析基于 2026 年 Q1 源码，后续版本可能已变更。Computer Use 仅限 macOS，需 Max/Pro 订阅。 diff --git a/docs/comparison/cost-fastmode-deep-dive.md b/docs/comparison/cost-fastmode-deep-dive.md new file mode 100644 index 00000000..0647fa7f --- /dev/null +++ b/docs/comparison/cost-fastmode-deep-dive.md @@ -0,0 +1,166 @@ +# 成本追踪与 Fast Mode Deep-Dive + +> 用户如何了解 AI Agent 的实际花费？能否在速度和成本之间灵活切换？本文基于 Claude Code（v2.1.89 源码分析）和 Qwen Code（v0.15.0 开源）的源码分析，对比两者在成本追踪、Fast Mode 速度分级和并发会话管理方面的差异。 + +--- + +## 1. 架构总览 + +| 维度 | Claude Code | Qwen Code | +|------|------------|-----------| +| **成本显示** | USD 金额 + 按模型分项 + cache 效率 | Token 计数 + 请求数 + cache 效率百分比 | +| **成本持久化** | 按 session ID 存储在项目配置中 | 无持久化 | +| **Fast Mode** | ✅ Opus 4.6 标准/快速切换（$5→$30/Mtok） | ❌（仅 `--fast` 指定备用模型） | +| **并发 Session** | ✅ PID 文件追踪 + 后台 Agent 脱附 | 无跨终端追踪 | + +--- + +## 2. Claude Code：USD 成本追踪 + +### 2.1 成本累计 + +```typescript +// 源码: cost-tracker.ts +// 每次 API 响应后调用: +addToTotalSessionCost(model, usage) + → calculateUSDCost(model, usage) // 按定价表计算 USD + → addToTotalModelUsage(model, usage) // 按模型分项累计 + → getCostCounter().add(cost) // OpenTelemetry 指标 +``` + +### 2.2 /cost 命令输出 + +``` +Total cost: $1.25 +Total duration (API): 2m 45s +Total duration (wall): 5m 30s +Total code changes: 25 lines added, 8 lines removed + +Usage by model: + Opus 4.6: 100,000 input, 45,000 output, 5,000 cache read, 2,500 cache write ($0.95) + Sonnet 4.6: 50,000 input, 12,000 output ($0.30) +``` + +**关键信息**： +- USD 金额精确到分 +- Cache read / write tokens 分开显示——用户可判断 prompt cache 效率 +- 按模型分项——用户可识别哪个模型消耗最多 +- API 时间 vs 总时间——区分网络延迟和工具执行时间 + +### 2.3 会话成本持久化 + +```typescript +// 源码: cost-tracker.ts +// 保存到项目配置: +saveCurrentSessionCosts() → config.projects[projectPath] = { + lastSessionId, lastCost, lastAPIDuration, lastModelUsage, lastLinesChanged +} +// --resume 恢复时: +restoreCostStateForSession() → 检查 sessionId 匹配后恢复累积成本 +``` + +### 2.4 Fast Mode + +```typescript +// 源码: utils/fastMode.ts +// 切换: /fast 命令 或 设置 fastMode: true +// 定价: Opus 4.6 Standard $5/$25 → Fast $30/$150 per Mtok + +// 冷却机制: +type FastModeState = + | { status: 'active' } + | { status: 'cooldown'; resetAt: number; reason: 'rate_limit' | 'overloaded' } + +// 429 错误 → triggerFastModeCooldown(resetTimestamp, reason) +// 冷却结束 → 自动恢复 active +``` + +**与重试集成**（源码: `services/api/withRetry.ts`）： +- 短 `retry-after`（<20s）：保持 Fast Mode 重试（保留 cache） +- 长 `retry-after`：进入冷却，回退到 Standard +- Overage rejection：永久禁用 Fast Mode + +### 2.5 并发 Session 管理 + +```typescript +// 源码: utils/concurrentSessions.ts +// PID 文件: ~/.claude/sessions/{pid}.json +{ + pid: 12345, + sessionId: "abc-123", + cwd: "/path/to/project", + kind: "interactive" | "bg" | "daemon" | "daemon-worker", + name: "background-session-name", + startedAt: 1704067200000 +} +// countConcurrentSessions() — 扫描 PID 文件，过滤已退出进程 +// 自动清理: registerCleanup() 在退出时删除 PID 文件 +``` + +--- + +## 3. Qwen Code：Token 统计 + +### 3.1 /stats 命令 + +```typescript +// 源码: qwen-code/packages/cli/src/ui/components/StatsDisplay.tsx +// 显示内容: +// - Session ID、工具调用（成功/失败）、成功率 +// - Wall time、Agent 活跃时间、API 时间占比 +// - 按模型分项: 模型名、请求数、输入/输出 tokens +// - Cache 效率: "{cacheEfficiency.toFixed(1)}% of input from cache" +``` + +### 3.2 无 USD 成本计算 + +Qwen Code 的 `/stats` 显示 token 数量和 cache 效率百分比，但**不计算 USD 金额**——因为支持多 Provider（Google/Qwen/Anthropic/OpenAI），定价差异大，难以统一计算。 + +### 3.3 /model --fast + +```typescript +// 源码: qwen-code/packages/cli/src/ui/commands/modelCommand.ts +// /model --fast → 设置后台任务的备用快速模型 +// 与 Claude Code 的 Fast Mode 不同： +// - Claude: 同一模型的不同推理速度（相同 Opus 4.6，不同 QPS/价格） +// - Qwen: 指定另一个更快的模型（如用 Haiku 替代 Opus） +``` + +--- + +## 4. 对比 + +| 维度 | Claude Code | Qwen Code | +|------|------------|-----------| +| 成本单位 | **USD 金额** | Token 数量 | +| 按模型分项 | ✅ 含 cache read/write 分项 | ✅ 含 cache 效率百分比 | +| 成本持久化 | ✅ 跨 `--resume` 累加 | ❌ | +| Fast Mode | ✅ 同模型速度切换 + 冷却 + 重试集成 | ⚠️ `--fast` 指定备用模型（非速度分级） | +| 并发追踪 | ✅ PID 文件 + 后台脱附 | ❌ | +| 代码变更统计 | ✅ lines added/removed | ❌ | + +--- + +## 5. 关键源码文件 + +### Claude Code + +| 文件 | 职责 | +|------|------| +| `cost-tracker.ts` | 成本累计、持久化、/cost 格式化 | +| `utils/modelCost.ts` | 定价表（7 个价格档） | +| `utils/fastMode.ts` | Fast Mode 状态机 + 冷却 | +| `commands/fast/fast.tsx` | /fast 命令 UI | +| `commands/cost/cost.ts` | /cost 命令 | +| `utils/concurrentSessions.ts` | PID 追踪 + 并发计数 | + +### Qwen Code + +| 文件 | 职责 | +|------|------| +| `packages/cli/src/ui/components/StatsDisplay.tsx` | 统计 UI | +| `packages/cli/src/ui/commands/statsCommand.ts` | /stats 命令 | +| `packages/cli/src/ui/commands/modelCommand.ts` | /model --fast | +| `packages/core/src/telemetry/metrics.ts` | OpenTelemetry 指标 | + +> **免责声明**: 以上分析基于 2026 年 Q1 源码，后续版本可能已变更。 diff --git a/docs/comparison/deep-link-protocol-deep-dive.md b/docs/comparison/deep-link-protocol-deep-dive.md new file mode 100644 index 00000000..2c479da6 --- /dev/null +++ b/docs/comparison/deep-link-protocol-deep-dive.md @@ -0,0 +1,156 @@ +# Deep Link 协议 Deep-Dive + +> 如何从浏览器、IDE 或 Slack 一键启动 AI Agent 并预填充 prompt？本文基于 Claude Code（v2.1.89 源码分析）的源码分析，介绍其 `claude-cli://` URI scheme 的完整架构：协议解析、终端自动检测、GitHub 仓库解析和安全模型。Qwen Code 目前无此功能。 + +--- + +## 1. 架构总览 + +``` +浏览器/IDE/Slack → claude-cli://open?q=...&cwd=...&repo=... + ↓ OS Protocol Handler +URL Handler App（macOS .app / Linux .desktop / Windows Registry） + ↓ --handle-uri +Claude Code CLI → parseDeepLink() → 解析参数 + ↓ +terminalLauncher → 检测/启动终端 + ↓ 终端内启动 +Claude Code REPL（预填充 prompt + 工作目录） +``` + +--- + +## 2. URI Scheme + +**协议**：`claude-cli://` + +**格式**：`claude-cli://open?q=&cwd=&repo=` + +| 参数 | 类型 | 说明 | 限制 | +|------|------|------|------| +| `q` | string | 预填充 prompt | ≤5,000 字符，无控制字符 | +| `cwd` | string | 工作目录 | 绝对路径，≤4,096 字符 | +| `repo` | string | GitHub 仓库 slug | `owner/repo` 格式 | + +**安全**：所有参数 URL-decoded + Unicode 清理 + 控制字符拒绝 + shell-quoted。 + +> 源码: `utils/deepLink/parseDeepLink.ts` + +--- + +## 3. 终端自动检测与启动 + +### 3.1 macOS（优先级从高到低） + +| 终端 | 启动方式 | CWD 方法 | +|------|----------|----------| +| **iTerm** | AppleScript `create window` + `write text` | AppleScript 内置 | +| **Ghostty** | `open -na --args` | `--working-directory=` | +| **Kitty** | `open -na --args` | `--directory ` | +| **Alacritty** | `open -na --args` | `--working-directory ` | +| **WezTerm** | `open -na --args` | `start --cwd ` | +| **Terminal.app** | AppleScript `do script` | AppleScript 内置 | + +**检测顺序**： +1. 用户保存的偏好（`deepLinkTerminal` 配置） +2. `TERM_PROGRAM` 环境变量 +3. Spotlight `mdfind` 查找 bundle ID +4. `/Applications/` 目录回退 +5. Terminal.app（始终可用） + +### 3.2 Linux + +| 终端 | CWD 方法 | +|------|----------| +| ghostty, kitty, alacritty, wezterm | `--working-directory` / `--directory` / `--cwd` | +| gnome-terminal, konsole | `--working-directory` | +| xfce4-terminal, mate-terminal, tilix | `--working-directory` | +| xterm | `spawn({cwd})` | + +**检测**：`$TERMINAL` → `x-terminal-emulator` → 优先级列表 `which()` 遍历 + +### 3.3 Windows + +| 终端 | 启动方式 | +|------|----------| +| Windows Terminal (`wt.exe`) | `-d -- cmd args` | +| PowerShell 7+ (`pwsh.exe`) | `-NoExit -Command "Set-Location; &"` | +| PowerShell 5.1 | 同上 | +| cmd.exe | `/k "cd /d '' && "` | + +> 源码: `utils/deepLink/terminalLauncher.ts` + +--- + +## 4. GitHub 仓库解析 + +```typescript +// 源码: utils/deepLink/protocolHandler.ts#L36-L75 +// 优先级: 显式 cwd > repo 查找 > home 目录 + +// repo 查找: +getKnownPathsForRepo('owner/repo') + → 扫描已知克隆路径（githubRepoPathMapping.ts） + → filterExistingPaths() + → 返回 MRU（最近使用）的克隆目录 +``` + +**新鲜度检查**（源码: `utils/deepLink/banner.ts#L88-L102`）： +- 读取 `FETCH_HEAD` mtime +- 超过 7 天显示过期警告 + +--- + +## 5. 安全模型 + +### 5.1 来源警告 Banner + +``` +⚠ External deep link +Working directory: /path/to/project +Repo: owner/repo (last fetched 3 days ago) + +Review the prompt below, then press Enter to submit. +``` + +- 用户必须按 Enter 确认——不自动执行 +- Prompt 超过 1,000 字符时提示"scroll down to review" + +### 5.2 协议注册 + +| 平台 | 注册方式 | 位置 | +|------|----------|------| +| macOS | `.app` bundle + LaunchServices | `~/Applications/Claude Code URL Handler.app/` | +| Linux | `.desktop` 文件 + xdg-mime | `$XDG_DATA_HOME/applications/` | +| Windows | Registry HKCU | `HKCU\Software\Classes\claude-cli` | + +**自动注册**：后台 housekeeping 中 fire-and-forget，GrowthBook `tengu_lodestone_enabled` 门控，失败 24h 退避。 + +> 源码: `utils/deepLink/registerProtocol.ts` + +--- + +## 6. CLI 参数 + +| 参数 | 用途 | +|------|------| +| `--handle-uri ` | OS 协议分发入口 | +| `--deep-link-origin` | 标记从 deep link 启动 | +| `--deep-link-repo ` | 已解析的 GitHub slug | +| `--deep-link-last-fetch ` | FETCH_HEAD mtime（显示新鲜度） | +| `--prefill ` | 预填充 prompt | + +--- + +## 7. 关键源码文件 + +| 文件 | 职责 | +|------|------| +| `utils/deepLink/parseDeepLink.ts` | URI 解析 + 参数验证 | +| `utils/deepLink/protocolHandler.ts` | URI 分发 + repo 解析 | +| `utils/deepLink/terminalLauncher.ts` | 终端检测 + 跨平台启动 | +| `utils/deepLink/registerProtocol.ts` | 协议注册（macOS/Linux/Windows） | +| `utils/deepLink/terminalPreference.ts` | 终端偏好存储 | +| `utils/deepLink/banner.ts` | 来源安全警告 | + +> **免责声明**: 以上分析基于 2026 年 Q1 源码，后续版本可能已变更。 diff --git a/docs/comparison/git-workflow-session-deep-dive.md b/docs/comparison/git-workflow-session-deep-dive.md new file mode 100644 index 00000000..957b2a51 --- /dev/null +++ b/docs/comparison/git-workflow-session-deep-dive.md @@ -0,0 +1,215 @@ +# Git 工作流与会话管理 Deep-Dive + +> AI Agent 如何追踪代码归属、管理文件历史、支持对话分支？本文基于 Claude Code（v2.1.89 源码分析）和 Qwen Code（v0.15.0 开源）的源码分析，对比两者在 commit attribution、文件历史快照、会话分支和输出模式方面的差异。 + +--- + +## 1. 架构总览 + +| 维度 | Claude Code | Qwen Code | +|------|------------|-----------| +| **Commit Attribution** | ✅ Co-Authored-By + 按文件字符归因 + git notes | ❌ | +| **Git Diff 统计** | ✅ numstat + hunks 解析（50 文件 / 1MB 上限） | 依赖 simple-git npm | +| **文件历史** | ✅ per-file SHA256 快照（100 个/session） | Git worktree checkpoint | +| **会话分支** | ✅ /branch（transcript 完整 fork + forkedFrom 溯源） | ❌ | +| **Output Styles** | ✅ Learning（教学模式）+ Explanatory（解释模式） | ❌ | + +--- + +## 2. Commit Attribution（代码归因） + +### 2.1 Claude Code + +**Co-Authored-By 注入**（源码: `utils/commitAttribution.ts`）： + +``` +git commit 消息末尾自动追加: +Co-Authored-By: Claude +``` + +**按文件字符归因**： +- 跟踪每个文件的 `claudeChars`（AI 贡献字符数）vs `humanChars`（人类贡献字符数） +- 通过 diff 前缀/后缀匹配计算贡献比例 +- SHA256 哈希标识文件版本 + +**Attribution 元数据**（存储在 git notes 中）： + +```json +{ + "version": 1, + "summary": { "claudeChars": 1500, "humanChars": 200 }, + "files": [ + { "path": "src/main.ts", "claudeChars": 800, "humanChars": 50, "hash": "abc123" } + ], + "surface": "cli/opus-4-6", + "sessionId": "session-uuid" +} +``` + +**模型名清理**：内部模型名（`opus-4-6-fast`）在外部仓库自动清理为公开名（`claude-opus-4-6`），避免泄露内部代号。 + +### 2.2 Qwen Code + +无 commit attribution 机制——commit 消息中不标注 AI 贡献，无法区分 AI vs 人类代码。 + +**影响**：开源项目中 AI 生成代码的透明度缺失；审计场景无法追溯。 + +--- + +## 3. Git Diff 统计 + +### 3.1 Claude Code + +**结构化 diff 解析**（源码: `utils/gitDiff.ts`）： + +```typescript +// 两阶段 diff: +// 1. git diff HEAD --numstat → O(1) 内存快速探测（文件数 + 行数） +// 2. git diff HEAD → 完整 hunks（仅在文件数不超限时） + +// 限制: +MAX_FILES = 50 // 超过 50 文件跳过详情 +MAX_DIFF_SIZE_BYTES = 1_000_000 // 单文件 >1MB 跳过 +MAX_LINES_PER_FILE = 400 // GitHub auto-load 限制 +MAX_FILES_FOR_DETAILS = 500 // 超过 500 文件仅显示 numstat + +// 特殊处理: +// - merge/rebase/cherry-pick/revert 期间跳过 diff +// - 未跟踪文件: git ls-files --others（仅文件名） +// - 单文件 diff: 与默认分支 merge-base 比较（PR 风格视图） +``` + +**统计信息**： +- `filesCount`、`linesAdded`、`linesRemoved` +- 按文件：`added`、`removed`、`isBinary`、`isUntracked` +- 结构化 hunks：`oldStart`、`oldLines`、`newStart`、`newLines`、`lines[]` + +### 3.2 Qwen Code + +使用 `simple-git` npm 包调用 git 命令，无专门的 diff 解析器。无 numstat 快速探测、无文件数限制、无结构化 hunks 输出。 + +--- + +## 4. 文件历史快照 + +### 4.1 Claude Code + +**Per-file SHA256 快照**（源码: `utils/fileHistory.ts`）： + +``` +编辑前 → fileHistoryTrackEdit() → 备份原始文件 + ├── 计算 SHA256 内容哈希 + ├── 检查 mtime 避免重复备份 + └── 存储: {hash}@v{version} + +消息完成后 → fileHistoryMakeSnapshot() → 创建快照 + ├── 记录所有已跟踪文件的当前版本 + ├── 删除的文件标记 backupFileName: null + └── 快照上限: 100 个/session +``` + +**恢复**：按消息 ID 回滚到特定快照——比 git-level checkpoint 更细粒度。 + +### 4.2 Qwen Code + +**Git Worktree Checkpoint**（源码: `packages/core/src/services/gitWorktreeService.ts`）： + +``` +setupWorktrees() → git worktree add（创建独立工作副本） + → git stash create（捕获脏状态） + → 复制未跟踪文件 + → 创建 baseline commit + +// Diff 从 baseline 开始——仅捕获 agent 变更，排除预先存在的编辑 +``` + +**区别**：Git-level（整体快照）vs file-level（按文件版本），Qwen 的粒度更粗但与 git 生态天然兼容。 + +--- + +## 5. 会话分支（/branch） + +### 5.1 Claude Code + +```typescript +// 源码: commands/branch/branch.ts +// /branch [名称] → fork 当前 transcript 为新 session + +// 保留的元数据: +// - 完整消息历史（时间戳、gitBranch、parentUuid、isSidechain） +// - content-replacement 条目（prompt cache 预览） +// - forkedFrom: { sessionId, messageUuid }（溯源） + +// 命名: "对话标题 (Branch)" → "(Branch 2)" → "(Branch 3)" +// 分支自动成为活跃 session；原始 session 可通过 --resume 恢复 +``` + +**用例**： +- 探索替代实现方案而不丢失当前进度 +- A/B 对比不同架构决策 +- 从某个关键节点创建多个实验分支 + +### 5.2 Qwen Code + +无会话分支功能。`forkedQuery.ts` 用于 speculation/followup 的 cache-aware 二次查询，不是对话分叉。 + +--- + +## 6. Output Styles（输出模式） + +### 6.1 Claude Code + +**两种内置模式**（源码: `constants/outputStyles.ts`）： + +| 模式 | 行为 | +|------|------| +| **Explanatory** | 在代码变更后添加 "Insight" 块：解释实现选择和代码库模式——"提供教育性洞察" | +| **Learning** | 暂停执行，要求用户编写代码——"通过动手实践学习" | + +**Learning 模式详情**： +- 对 20+ 行的函数，请求用户贡献 2-10 行设计决策/业务逻辑/算法 +- 格式：Context → Your Task → Guidance +- 代码中插入 `TODO(human)` 占位符 +- 等待人类实现后继续 +- 适用场景：教学、代码审查培训、新人上手 + +**加载优先级**：built-in → plugin → user settings → project settings + +### 6.2 Qwen Code + +无内置 output style 模式。`settingsSchema.ts` 有通用设置框架，但未定义 Learning/Explanatory 等具体模式。 + +--- + +## 7. 对比总结 + +| 维度 | Claude Code | Qwen Code | 差距 | +|------|------------|-----------|------| +| Commit Attribution | 按文件字符归因 + git notes | 无 | 缺失 | +| Diff 统计 | 原生解析（numstat + hunks + 限制） | simple-git 库 | 中等 | +| 文件快照 | per-file SHA256（100 个/session） | Git worktree（整体） | 粒度差异 | +| 会话分支 | /branch + forkedFrom 溯源 | 无 | 缺失 | +| Output Styles | Learning + Explanatory | 无 | 缺失 | + +--- + +## 8. 关键源码文件 + +### Claude Code + +| 文件 | 职责 | +|------|------| +| `utils/commitAttribution.ts` | Co-Authored-By + 按文件字符归因 | +| `utils/gitDiff.ts` | 结构化 diff 解析（numstat + hunks + 限制） | +| `utils/fileHistory.ts` | Per-file SHA256 快照 + 按消息恢复 | +| `commands/branch/branch.ts` | /branch 会话分叉 | +| `constants/outputStyles.ts` | Learning / Explanatory 输出模式 | + +### Qwen Code + +| 文件 | 职责 | +|------|------| +| `packages/core/src/services/gitWorktreeService.ts` | Git worktree checkpoint | +| `packages/core/src/followup/forkedQuery.ts` | Cache-aware 二次查询（非对话分叉） | + +> **免责声明**: 以上分析基于 2026 年 Q1 源码，后续版本可能已变更。 diff --git a/docs/comparison/qwen-code-improvement-report-p0-p1.md b/docs/comparison/qwen-code-improvement-report-p0-p1.md new file mode 100644 index 00000000..05016df5 --- /dev/null +++ b/docs/comparison/qwen-code-improvement-report-p0-p1.md @@ -0,0 +1,505 @@ +# Qwen Code 改进建议 — P0/P1 详细说明 + +> 最高优先级改进项。每项包含：思路概述、Claude Code 源码索引（方便查找参考）、Qwen Code 修改方向。 +> +> 返回 [改进建议总览](./qwen-code-improvement-report.md) + +--- + + + +### 1. 多层上下文压缩（P0） + +**思路**：不做一次性全量摘要，而是分层递进——先清旧工具结果（MicroCompact），再自动触发全量摘要（~93% 阈值），最后记忆感知压缩。大多数场景 MicroCompact 就够。 + +**Claude Code 源码索引**： + +| 文件 | 关键函数/常量 | +|------|-------------| +| `services/compact/microCompact.ts` (531行) | `COMPACTABLE_TOOLS` Set（8 种可清除工具）、`consumePendingCacheEdits()` | +| `services/compact/autoCompact.ts` | `AUTOCOMPACT_BUFFER_TOKENS = 13_000`（~93% 触发） | +| `services/compact/compact.ts` (1705行) | `compactConversation()`、`POST_COMPACT_MAX_FILES_TO_RESTORE = 5` | +| `services/compact/prompt.ts` | 9 章节摘要 Prompt 模板 | + +**Qwen Code 修改方向**：在 `chatCompressionService.ts` 新增 `microCompact()` 方法，在 `agent-core.ts` 的 `processFunctionCalls()` 后调用；`tryCompressChat()` 改为 93% 自动触发。 + +**相关文章**：[上下文压缩深度对比](./context-compression-deep-dive.md) + +**意义**：长会话是 AI Agent 的核心使用场景，压缩质量直接决定长会话的可用性。 +**缺失后果**：用户需手动 /compress，压缩后模型'失忆'需重新描述上下文。 +**改进收益**：长会话无限延续无需干预，压缩后自动恢复最近文件和记忆。 + +--- + + + +### 2. Fork 子代理（P0） + +**思路**：省略 `subagent_type` 时自动 fork——子代理继承完整对话历史 + 系统提示 + 工具集。所有 fork 使用相同占位 tool_result 文本，确保 API 请求前缀字节一致 → prompt cache 共享（5 个子代理省 80%+ token）。 + +**Claude Code 源码索引**： + +| 文件 | 关键函数/常量 | +|------|-------------| +| `tools/AgentTool/forkSubagent.ts` (210行) | `isForkSubagentEnabled()`、`FORK_AGENT` 定义、`buildForkedMessages()`、`buildChildMessage()`（10 条铁律） | +| `tools/AgentTool/AgentTool.tsx` (1397行) | fork vs 常规决策树（L318-L356）、`override.systemPrompt` 传递 | +| `tools/AgentTool/runAgent.ts` (973行) | `useExactTools: true`（跳过工具过滤）、thinking config 继承 | +| `utils/forkedAgent.ts` (689行) | `CacheSafeParams` 类型、`saveCacheSafeParams()` | + +**Qwen Code 修改方向**：`agent.ts` 中将 `subagent_type` 改为可选；新增 `forkSubagent.ts` 实现消息构建（克隆 assistant message + 统一占位 tool_result + 指令注入）。 + +**相关文章**：[Fork 子代理 Deep-Dive](./fork-subagent-deep-dive.md) + +**意义**：大型任务需拆分给多个子代理并行处理，上下文传递效率决定成本和准确率。 +**缺失后果**：每个子代理独立上下文 = N× 完整 prompt 费用，且需重复描述背景。 +**改进收益**：N 个子代理共享一份 cache（省 80%+ token），继承完整对话零丢失。 + +--- + + + +### 3. Speculation 默认启用（P1） + +**思路**：Qwen Code v0.15.0 已实现完整 speculation 系统，但 `enableSpeculation` 默认关闭。核心工作是评估安全性后默认开启，并扩大 `speculationToolGate` 的 safe 工具覆盖。 + +**Claude Code 源码索引**： + +| 文件 | 关键函数/常量 | +|------|-------------| +| `services/PromptSuggestion/speculation.ts` (991行) | `startSpeculation()`、`acceptSpeculation()`、overlay 文件系统 | +| `services/PromptSuggestion/promptSuggestion.ts` | `shouldFilterSuggestion()`（12 条过滤规则） | + +**Qwen Code 修改方向**：`settingsSchema.ts` 中 `enableSpeculation` 默认值 `false` → `true`；`speculationToolGate.ts` 扩大 safe 工具列表。 + +**相关文章**：[Prompt Suggestions](../tools/claude-code/10-prompt-suggestions.md)、[输入队列](./input-queue-deep-dive.md) + +**意义**：用户接受建议后的等待时间是交互体验的关键瓶颈。 +**缺失后果**：每次 Tab 接受后等 2-10 秒完整 API + 工具执行。 +**改进收益**：Tab 接受零延迟——建议展示时预执行已完成，支持连续 Tab-Tab-Tab。 + +--- + + + +### 4. 会话记忆 SessionMemory（P1） + +**思路**：session 结束时自动提取关键决策/文件结构/技术栈信息，持久化到 `.qwen/memory/`。新 session 启动时检索相关记忆并注入系统提示。与 compact 协同——压缩时保留已提取记忆。 + +**Claude Code 源码索引**： + +| 文件 | 关键函数/常量 | +|------|-------------| +| `services/SessionMemory/sessionMemory.ts` | 会话记忆提取 + 存储 | +| `services/SessionMemory/prompts.ts` | 记忆提取 Prompt | +| `memdir/findRelevantMemories.ts` | 相关性检索 | +| `memdir/memdir.ts` | `loadMemoryPrompt()`（200 行 / 25KB 截断） | + +**Qwen Code 修改方向**：新建 `services/sessionMemoryService.ts`；在 session 结束的 hook 中调用提取逻辑；`prompts.ts` 的 `getCustomSystemPrompt()` 注入检索结果。 + +**相关文章**：[记忆系统深度对比](./memory-system-deep-dive.md) + +**意义**：开发者在同一项目上反复使用 Agent，跨 session 知识断层导致效率低下。 +**缺失后果**：每次新 session 从零开始——反复告知项目背景、编码规范、已知坑点。 +**改进收益**：新 session 自动注入相关记忆——Agent'记住'项目上下文，无需反复说明。 + +--- + + + +### 5. Auto Dream 自动记忆整理（P1） + +**思路**：双门控（24h + 5 session）满足时，后台 fork 只读 agent 整理记忆——合并重复、删除过时、解决矛盾。文件锁防止多进程并发。 + +**Claude Code 源码索引**： + +| 文件 | 关键函数/常量 | +|------|-------------| +| `services/autoDream/autoDream.ts` (324行) | 门控逻辑、forked agent 调度 | +| `services/autoDream/consolidationPrompt.ts` | 整理 Prompt 模板 | +| `services/autoDream/consolidationLock.ts` | 文件锁防并发 | + +**Qwen Code 修改方向**：新建 `services/autoDream/`；在 `SessionStart` hook 中检查门控条件；满足时 fork 后台 agent 执行整理。 + +**相关文章**：[记忆系统深度对比](./memory-system-deep-dive.md) + +**意义**：记忆文件随使用膨胀，陈旧/矛盾记忆导致模型行为异常。 +**缺失后果**：记忆无限增长占满 token 预算，旧决策与新决策矛盾共存。 +**改进收益**：后台自动整理——合并重复、删除过时、解决矛盾，记忆始终精简。 + +--- + + + +### 6. Mid-Turn Queue Drain（P0） + +**思路**：在推理循环中每个工具批次执行完后、下一次 API 调用前，检查命令队列并将用户输入注入 toolResults——模型在当前 turn 的下一个 step 即可看到新指令，无需等整轮结束。 + +**Claude Code 源码索引**： + +| 文件 | 关键函数/常量 | +|------|-------------| +| `query.ts` (L1550-L1643) | `getCommandsByMaxPriority()`、`getAttachmentMessages()`、`removeFromQueue()` | +| `utils/messageQueueManager.ts` | 优先级队列（`now`/`next`/`later`）、`dequeue()` 带 filter | + +**Qwen Code 修改方向**：在 `agent-core.ts` 的 `processFunctionCalls()` 返回后、下一轮 `while` 迭代前，调用 `queue.dequeue()` 并将消息注入到下一次 API 调用的 history 中。 + +**相关文章**：[输入队列与中断机制](./input-queue-deep-dive.md) | **进展**：[PR#2854](https://github.com/QwenLM/qwen-code/pull/2854) + +**意义**：用户在 Agent 执行多步操作时发现方向错误，无法及时纠正。 +**缺失后果**：必须等所有步骤完成后才能发送新指令——已完成的错误工作需撤销。 +**改进收益**：用户输入在当前 turn 的下一个 step 即被模型看到——避免无用工作。 + +--- + + + +### 7. 智能工具并行（P1） + +**思路**：每个工具实现 `isConcurrencySafe(input)` 方法。连续的并发安全工具合并为一个并行批次（上限 10），遇到写工具则独立串行。并行时上下文修改队列化，批次结束后串行应用。 + +**Claude Code 源码索引**： + +| 文件 | 关键函数/常量 | +|------|-------------| +| `services/tools/toolOrchestration.ts` (188行) | `partitionToolCalls()`、`runToolsConcurrently()`、`runToolsSerially()` | +| `services/tools/StreamingToolExecutor.ts` (530行) | `canExecuteTool()`、Bash 错误级联（`siblingAbortController`） | +| `Tool.ts` (L402) | `isConcurrencySafe()` 接口 | + +**Qwen Code 修改方向**：`coreToolScheduler.ts` 中将 `otherCalls` 的顺序执行改为按 `kind` 分批并行；在 `tools.ts` 基类新增 `isConcurrencySafe` 属性（read 工具默认 true）。 + +**相关文章**：[工具并行执行](./tool-parallelism-deep-dive.md) | **进展**：[PR#2864](https://github.com/QwenLM/qwen-code/pull/2864) + +**意义**：代码探索场景（多个 Read + Grep + Glob）是最常见的 Agent 操作之一。 +**缺失后果**：7 个只读工具串行执行 = 7× 延迟。 +**改进收益**：只读工具并行 = 1× 延迟，I/O 密集任务快 5-10×。 + +--- + + + +### 8. 启动优化（P1） + +**思路**：两个独立优化——① API Preconnect：启动时 fire-and-forget HEAD 请求预热 TCP+TLS（省 100-200ms）；② Early Input：REPL 未就绪时 raw mode 捕获键盘输入，就绪后预填充。 + +**Claude Code 源码索引**： + +| 文件 | 关键函数/常量 | +|------|-------------| +| `utils/apiPreconnect.ts` (71行) | `preconnectAnthropicApi()`（fire-and-forget HEAD） | +| `utils/earlyInput.ts` (191行) | `startCapturingEarlyInput()`、`consumeEarlyInput()`、`processChunk()` | + +**Qwen Code 修改方向**：`gemini.tsx` 入口最早处调用 preconnect（DashScope/Gemini 端点）；新增 `earlyInput.ts` 在 `process.stdin.setRawMode(true)` 下捕获，`AppContainer` mount 时 consume。 + +**相关文章**：[启动阶段优化](./startup-optimization-deep-dive.md) + +**意义**：启动体验是用户对工具的第一印象。 +**缺失后果**：首次 API 需完整 TCP+TLS 握手（+100-200ms），启动打字丢失。 +**改进收益**：预连接省 150ms + 启动打字不丢失——感知启动更快。 + +--- + + + +### 9. 指令条件规则（P1） + +**思路**：`.qwen/rules/*.md` 支持 YAML frontmatter `paths:` glob 模式——有 `paths:` 的规则仅在操作匹配文件时惰加载，其余急加载。支持 HTML 注释剥离（作者注释不进 token 预算）。 + +**Claude Code 源码索引**： + +| 文件 | 关键函数/常量 | +|------|-------------| +| `utils/claudemd.ts` (1479行) | `processMdRules()`、`@include` 指令解析、HTML 注释剥离 | +| `utils/frontmatterParser.ts` | `paths:` glob 解析（`ignore` 库 picomatch） | + +**Qwen Code 修改方向**：`memoryImportProcessor.ts` 新增 frontmatter 解析；`memoryDiscovery.ts` 区分急/惰加载；文件操作时触发条件规则检查。 + +**相关文章**：[指令文件加载](./instruction-loading-deep-dive.md) + +**意义**：大型项目不同目录有不同编码规范（TS/Python/Docs），全部加载浪费 token。 +**缺失后果**：所有规则塞在一个 QWEN.md 中——系统提示膨胀，规则互相干扰。 +**改进收益**：按文件路径匹配加载规则——操作 TS 文件时只注入 TS 规范，精准且省 token。 + +--- + + + +### 10. Team Memory 组织级记忆（P2→Top20） + +**思路**：per-repo 级别团队记忆同步——API pull/push（ETag + SHA256 per-key 校验和）、Delta 上传（仅变更 key）、fs.watch 2s debounce 实时推送。上传前 29 条 gitleaks 规则密钥扫描。 + +**Claude Code 源码索引**： + +| 文件 | 关键函数/常量 | +|------|-------------| +| `services/teamMemorySync/index.ts` | delta sync 编排、`MAX_PUT_BODY_BYTES = 200KB` 批次 | +| `services/teamMemorySync/secretScanner.ts` | 29 条 gitleaks 规则 | +| `services/teamMemorySync/watcher.ts` | fs.watch + 2s debounce | +| `memdir/teamMemPrompts.ts` | private + team 双目录提示构建 | + +**Qwen Code 修改方向**：新建 `services/teamMemorySync/`；API 端点对接阿里云/自建后端；`memoryTool.ts` 扩展为 private/team 双目录。 + +**相关文章**：[Team Memory 深度对比](./team-memory-deep-dive.md) + +**意义**：团队协作项目中，个人发现的项目知识无法共享是效率瓶颈。 +**缺失后果**：团队成员各自维护独立记忆——项目知识孤岛，新成员从零积累。 +**改进收益**：一人学到的知识自动同步全团队 + 29 条规则防止密钥泄露。 + +--- + + + +### 11. 工具动态发现 ToolSearchTool（P1） + +**思路**：系统提示仅注入核心工具（~10 个），其余标记为 deferred。模型需要时调用 ToolSearch（keyword 或 `select:` 模式）按需加载——省 50%+ 系统提示 token。MCP 工具始终 deferred。 + +**Claude Code 源码索引**： + +| 文件 | 关键函数/常量 | +|------|-------------| +| `tools/ToolSearchTool/ToolSearchTool.ts` (472行) | keyword 评分（MCP 12/6分, 普通 10/5分）、`select:` 直接选择 | +| `tools/ToolSearchTool/prompt.ts` | `isDeferredTool()` 分类逻辑、`alwaysLoad` 豁免 | + +**Qwen Code 修改方向**：工具注册表新增 `deferred: boolean` 属性；新建 `tools/toolSearch.ts`；`coreToolScheduler.ts` 在工具 schema 注入时过滤 deferred 工具。 + +**相关文章**：[工具搜索与延迟加载](./tool-search-deep-dive.md) + +**意义**：39+ 工具 schema 全部注入系统提示占用大量 token——尤其 MCP 工具。 +**缺失后果**：系统提示 ~15K+ tokens 被工具 schema 占满，留给用户内容的空间减少。 +**改进收益**：仅加载核心工具（~10 个），其余按需搜索——系统提示 token 减少 50%+。 + +--- + + + +### 12. Commit Attribution（P1） + +**思路**：跟踪每个文件的 AI vs 人类字符贡献比例（diff 前缀/后缀匹配），commit 消息自动追加 `Co-Authored-By`，attribution 元数据存 git notes。内部模型名在外部仓库自动清理为公开名。 + +**Claude Code 源码索引**： + +| 文件 | 关键函数/常量 | +|------|-------------| +| `utils/commitAttribution.ts` (961行) | 按文件字符归因、`INTERNAL_MODEL_REPOS` 清理 | +| `utils/attributionTrailer.ts` | Co-Authored-By 注入 | + +**Qwen Code 修改方向**：新建 `utils/commitAttribution.ts`；在 `shell.ts` 检测到 `git commit` 时注入 trailer。 + +**相关文章**：[Git 工作流与会话管理](./git-workflow-session-deep-dive.md) + +**意义**：AI 生成代码的透明度和可追溯性是开源社区和企业合规的核心关注。 +**缺失后果**：git 历史无法区分 AI 和人类代码——合规审计困难。 +**改进收益**：commit 自动标注 AI 贡献比例——满足开源 AI 披露和企业审计要求。 + +--- + + + +### 13. 会话分支 /branch（P1） + +**思路**：fork 当前 transcript JSONL 为新 session——保留完整历史 + `forkedFrom: { sessionId, messageUuid }` 溯源。自动命名 "(Branch)"，分支成为活跃 session，原始可 `--resume`。 + +**Claude Code 源码索引**： + +| 文件 | 关键函数/常量 | +|------|-------------| +| `commands/branch/branch.ts` (296行) | `getUniqueForkName()`、transcript 复制 + `forkedFrom` 元数据 | + +**Qwen Code 修改方向**：新建 `/branch` 命令；`sessionService.ts` 新增 `forkSession()` 方法（复制 JSONL + 写入 forkedFrom）。 + +**相关文章**：[Git 工作流与会话管理](./git-workflow-session-deep-dive.md) + +**意义**：探索替代方案是软件开发的常见需求——A/B 对比架构决策。 +**缺失后果**：探索替代方案必须丢弃当前进度，或手动复制上下文。 +**改进收益**：从任意节点创建分支——原始 session 保留，分支独立探索。 + +--- + + + + +### 14. GitHub Actions CI（P1） + +**思路**：官方 GitHub Action 封装 `claude -p` headless 模式——PR 创建时自动触发 review、issue 创建时自动分类。支持 `--allowedTools` 白名单和 `--permission-mode dontAsk`。 + +**Claude Code 源码索引**： + +| 文件 | 关键函数/常量 | +|------|-------------| +| 外部: `anthropics/claude-code-action` | GitHub Action YAML + headless 调用 | +| `cli/print.ts` (5594行) | `runHeadless()` — headless 执行入口 | + +**Qwen Code 修改方向**：创建 `qwenlm/qwen-code-action` GitHub Action；核心是调用 `qwen-code -p --allowedTools "Read,Bash" --output-format json`。 + +**意义**：CI 自动化是开发工作流的核心——每个 PR 都应被审查。 +**缺失后果**：PR 审查需手动触发 Agent——无法自动化。 +**改进收益**：PR 创建自动触发 Agent 审查——减少人工审查负担。 + +--- + + + +### 15. GitHub Code Review 多代理审查（P1） + +**思路**：多 Agent 并行审查 PR 不同文件——每个 Agent 检查一类问题（逻辑错误/安全漏洞/边界情况），验证步骤过滤误报，结果去重排序后发 inline 评论。可配合 `REVIEW.md` 定制审查规则。 + +**Claude Code 源码索引**： + +| 文件 | 关键函数/常量 | +|------|-------------| +| 托管服务（非本地源码） | 多 Agent 并行 + 验证 + 去重 | +| `code-review.md` 官方文档 | severity: 🔴 Important / 🟡 Nit / 🟣 Pre-existing | + +**Qwen Code 修改方向**：基于已有 `/review` Skill 扩展——fork 多个 Agent 各审查一组文件；`gh api` 发 inline 评论；新增 `REVIEW.md` 支持。 + +**意义**：大 PR 单 Agent 逐文件审查慢——多代理并行可大幅提速。 +**缺失后果**：单 Agent 审查大 PR 需 N 分钟。 +**改进收益**：多 Agent 并行审查——大 PR 审查时间缩短到 ~1 分钟。 + +--- + + + +### 16. HTTP Hooks（P1） + +**思路**：Hook 除了 `type: "command"`（shell）外，支持 `type: "http"` —— POST JSON 到 URL 并接收 JSON 响应。适合与 CI、审批系统、消息平台直接集成，无需 shell 中转。 + +**Claude Code 源码索引**： + +| 文件 | 关键函数/常量 | +|------|-------------| +| `utils/hooks/hookRunner.ts` | HTTP hook 执行（fetch POST + JSON parse） | +| `types/hooks.ts` | `HookConfig.type` 支持 `'command'` 和 `'http'` | + +**Qwen Code 修改方向**：`hookRunner.ts` 新增 HTTP 分支——`type === 'http'` 时 fetch POST body（hook input JSON），解析 response JSON 作为 hook output。 + +**意义**：与外部服务（CI/审批/消息平台）集成需要 HTTP 而非 shell。 +**缺失后果**：通过 shell curl 间接集成——脆弱且难以处理 JSON 响应。 +**改进收益**：Hook 原生 HTTP——直接与 API 交互，响应结构化解析。 + +--- + + + +### 17. Structured Output --json-schema（P1） + +**思路**：headless 模式 `--json-schema` 参数注入 SyntheticOutputTool——强制模型调用该工具输出结构化数据，Ajv 运行时验证 schema。不通过则重试。 + +**Claude Code 源码索引**： + +| 文件 | 关键函数/常量 | +|------|-------------| +| `tools/SyntheticOutputTool/SyntheticOutputTool.ts` | Ajv 验证 + WeakMap schema 缓存 | +| `main.tsx` | `--json-schema` CLI 参数解析 + `--output-format json` | + +**Qwen Code 修改方向**：新建 `tools/structuredOutput.ts`；`nonInteractiveCli.ts` 新增 `--json-schema` 参数；headless 模式注入该工具到工具列表。 + +**意义**：CI 脚本需要结构化输出——解析纯文本不可靠。 +**缺失后果**：CI 脚本自行 parse 纯文本——脆弱且不可靠。 +**改进收益**：--json-schema 保证输出符合 schema——CI 集成可靠。 + +--- + + + +### 18. Agent SDK Python（P1） + +**思路**：Qwen Code 已有 TypeScript SDK（`@qwen-code/sdk`），缺 Python SDK。Claude Code 提供 Python + TS 双语言 SDK，支持流式回调和工具审批回调。 + +**Claude Code 源码索引**： + +| 文件 | 关键函数/常量 | +|------|-------------| +| `entrypoints/sdk/` | SDK 类型定义、消息映射 | +| 外部: `anthropics/claude-code-sdk-python` | Python 包 | + +**Qwen Code 修改方向**：新建 `packages/sdk-python/`；封装 subprocess 调用 `qwen-code -p --output-format stream-json`；提供 `QwenCodeAgent` class + async generator API。 + +**意义**：Python 生态开发者（数据科学、后端）需要原生 SDK。 +**缺失后果**：Python 开发者需通过 shell 调用 CLI——不优雅。 +**改进收益**：Python SDK `from qwen_code import Agent`——原生集成。 + +--- + + + +### 19. Bare Mode --bare（P1） + +**思路**：`--bare` 跳过所有自动发现（hooks/LSP/plugins/auto-memory/CLAUDE.md/OAuth/keychain），仅通过 CLI 显式参数传入上下文。CI 确定性执行——每台机器同样结果。 + +**Claude Code 源码索引**： + +| 文件 | 关键函数/常量 | +|------|-------------| +| `entrypoints/cli.tsx` (L283) | `CLAUDE_CODE_SIMPLE=1` 设置 | +| `main.tsx` (L394) | 跳过所有 prefetch | + +**Qwen Code 修改方向**：`gemini.tsx` 新增 `--bare` flag；设置 `QWEN_CODE_SIMPLE=1` 环境变量；各模块在 `SIMPLE` 模式下跳过自动发现。 + +**意义**：CI 环境需要确定性执行——不同机器的 hooks/plugins 不应影响结果。 +**缺失后果**：CI 启动慢 + 加载不需要的 hooks/plugins + 结果不可复现。 +**改进收益**：--bare 确定性执行——跳过所有自动发现，每台机器同样结果。 + +--- + + + +### 20. Remote Control Bridge（P1） + +**思路**：终端 Agent 注册到服务端（WebSocket），用户通过 Web/手机驱动本地 session。Outbound-only 模式——终端主动推事件，不接受入站连接。支持权限审批远程转发。 + +**Claude Code 源码索引**： + +| 文件 | 关键函数/常量 | +|------|-------------| +| `bridge/bridgeMain.ts` | WebSocket 连接 + 事件转发 | +| `bridge/bridgeApi.ts` | API 端点交互 | +| `bridge/bridgeConfig.ts` | 配置 + 环境注册 | + +**Qwen Code 修改方向**：新建 `packages/core/src/bridge/`；对接阿里云/自建 WebSocket 服务；`/remote-control` 命令启动桥接。 + +**意义**：离开电脑后 Agent 需要人类审批权限——当前无法远程操作。 +**缺失后果**：需要人在电脑前审批——离开后 Agent 暂停。 +**改进收益**：手机/浏览器远程驱动——外出时继续审批和补充上下文。 + +--- + + + +### 21. /teleport 跨平台迁移（P1） + +**思路**：Web session 完成后 `/teleport` 到终端——fetch 远程分支 + checkout + 加载完整会话历史。前提：同 repo、clean git state、同账号。 + +**Claude Code 源码索引**： + +| 文件 | 关键函数/常量 | +|------|-------------| +| `utils/teleport.tsx` | 交互式 session picker | +| `utils/teleport/api.ts` | 远程 session 列表 API | +| `utils/teleport/gitBundle.ts` | git fetch + checkout | + +**Qwen Code 修改方向**：需先有 Web 版本；新增 `/teleport` 命令；调用 API 获取 session 列表 → fetch branch → 加载历史。 + +**意义**：Web 上启动的长任务完成后需要在终端继续调试。 +**缺失后果**：Web 和终端是独立的——无法衔接。 +**改进收益**：/teleport 拉取 Web session 到终端——跨平台无缝切换。 + +--- + + + +### 22. GitLab CI/CD 集成（P1） + +**思路**：官方 GitLab pipeline 集成——MR 创建时自动触发 review。核心是在 `.gitlab-ci.yml` 中调用 `qwen-code -p` headless 模式 + `glab` CLI 发评论。 + +**Claude Code 源码索引**： + +| 文件 | 关键函数/常量 | +|------|-------------| +| 外部: 官方文档 `gitlab-ci-cd.md` | pipeline YAML 配置示例 | +| `cli/print.ts` | headless 执行入口 | + +**Qwen Code 修改方向**：创建 `qwenlm/qwen-code-gitlab` CI 模板；核心调用 `qwen-code -p --output-format json` + `glab mr note`。 + +**意义**：GitLab 在企业用户中占比显著——仅支持 GitHub 覆盖面不够。 +**缺失后果**：GitLab 用户无法在 CI 中集成 Agent。 +**改进收益**：覆盖 GitLab 用户群——企业级 CI 集成。 diff --git a/docs/comparison/qwen-code-improvement-report-p2.md b/docs/comparison/qwen-code-improvement-report-p2.md new file mode 100644 index 00000000..3470f7d7 --- /dev/null +++ b/docs/comparison/qwen-code-improvement-report-p2.md @@ -0,0 +1,770 @@ +# Qwen Code 改进建议 — P2 详细说明 + +> 中等优先级改进项。每项包含：思路概述、Claude Code 源码索引、Qwen Code 修改方向。 +> +> 返回 [改进建议总览](./qwen-code-improvement-report.md) + +--- + + + +### 23. Shell 安全增强（P2） + +**思路**：在 AST 读写分类基础上，补充专项检查——IFS 注入、Unicode 空白、Zsh 危险命令、花括号展开等。AST 是主路径（精确），专项检查是补充（覆盖面）。 + +**Claude Code 源码索引**： + +| 文件 | 关键函数/常量 | +|------|-------------| +| `tools/BashTool/bashSecurity.ts` (2592行) | 25+ validators 管线、`COMMAND_SUBSTITUTION_PATTERNS`（12 种）、`ZSH_DANGEROUS_COMMANDS`（18 个） | +| `utils/bash/treeSitterAnalysis.ts` (506行) | AST 辅助消除 `find -exec \;` 误报 | + +**Qwen Code 修改方向**：`shellAstParser.ts` 保持 AST 主路径不变；新增 `shellSecurityChecks.ts` 补充 IFS/Unicode/Zsh 检查，AST 判定 read-only 后仍过一遍专项检查。 + +**相关文章**：[Shell 安全模型](./shell-security-deep-dive.md) + +**意义**：Shell 命令是 Agent 最危险的工具——注入攻击可能造成系统损害。 +**缺失后果**：AST-only 不覆盖 IFS 注入、Unicode 空白、Zsh 命令等边缘攻击。 +**改进收益**：AST 主路径 + 专项检查补充——覆盖面与精确度兼得。 + +--- + + + +### 24. MDM 企业策略（P2） + +**思路**：通过 OS-native 方式读取企业策略——macOS plist、Windows Registry、Linux 文件。5 级 First-Source-Wins 优先级（Remote > HKLM > file > drop-in > HKCU）。启动时子进程并行读取避免阻塞。 + +**Claude Code 源码索引**： + +| 文件 | 关键函数/常量 | +|------|-------------| +| `utils/settings/mdm/constants.ts` | `com.anthropic.claudecode` domain、Registry keys | +| `utils/settings/mdm/rawRead.ts` | 子进程 plutil/reg query（5s 超时） | +| `utils/settings/mdm/settings.ts` | First-Source-Wins 合并逻辑 | + +**Qwen Code 修改方向**：新建 `utils/settings/mdm/`；在 `config.ts` 初始化时并行读取 plist/Registry；settings 合并时 MDM 优先级最高。 + +**相关文章**：[MDM 企业配置管理](./mdm-enterprise-deep-dive.md) + +**意义**：企业 IT 需集中管控 AI Agent 配置——禁用危险模式、限制模型、强制遥测。 +**缺失后果**：用户可自行覆盖所有配置——无管理员锁定能力。 +**改进收益**：通过 MDM 策略锁定关键配置——满足 SOC 2 / HIPAA 合规。 + +--- + + + +### 25. API 实时 Token 计数（P2） + +**思路**：3 层回退——API `countTokens()` → Haiku 小模型回退 → 粗估（4 bytes/token）。每次 API 调用前精确计数，比静态模式匹配更准确。 + +**Claude Code 源码索引**： + +| 文件 | 关键函数/常量 | +|------|-------------| +| `services/tokenEstimation.ts` (495行) | `countTokensWithAPI()`、`roughTokenCountEstimation()`、`TOKEN_COUNT_THINKING_BUDGET = 1024` | +| `services/vcr.ts` | `withTokenCountVCR()`（SHA1 hash 缓存） | + +**Qwen Code 修改方向**：调用 DashScope/Gemini 的 token 计数 API 替代 `tokenLimits.ts` 的静态模式匹配；加缓存层避免重复计数。 + +**相关文章**：[Token 估算与 Thinking](./token-estimation-deep-dive.md) + +**意义**：上下文窗口占用率是触发压缩和防溢出的关键指标——估算不准会导致过早或过晚压缩。 +**缺失后果**：静态模式匹配估算不精确——可能触发不必要压缩或溢出。 +**改进收益**：API 实时计数——压缩触发更准确，避免浪费和溢出。 + +--- + + + +### 26. Output Styles（P2） + +**思路**：内置 Learning（暂停要求用户写代码，插入 `TODO(human)` 占位符）和 Explanatory（添加 "Insight" 教育块）两种模式。通过 settings 或 plugin 可扩展自定义 style。 + +**Claude Code 源码索引**： + +| 文件 | 关键函数/常量 | +|------|-------------| +| `constants/outputStyles.ts` (216行) | `Explanatory`、`Learning`（20+ 行函数触发、2-10 行贡献请求） | +| `utils/outputStyles.ts` | `getAllOutputStyles()`（built-in + plugin + settings 合并） | + +**Qwen Code 修改方向**：新建 `core/outputStyles.ts`；系统提示中根据 `settings.outputStyle` 注入 style 指令。 + +**相关文章**：[Git 工作流与会话管理](./git-workflow-session-deep-dive.md) + +**意义**：教学和培训场景需要 Agent 引导用户动手实践，而非直接给出答案。 +**缺失后果**：Agent 只有一种输出风格——无法适应教学需求。 +**改进收益**：Learning 模式让 Agent 变教练——暂停、出题、等用户实现后继续。 + +--- + + + +### 27. Fast Mode（P2） + +**思路**：同一模型（如 Opus 4.6）的标准/快速推理切换。快速模式 $30/$150/Mtok（标准 $5/$25）。含冷却机制——429 后自动回退到标准，冷却结束恢复。 + +**Claude Code 源码索引**： + +| 文件 | 关键函数/常量 | +|------|-------------| +| `utils/fastMode.ts` (532行) | `isFastModeAvailable()`、`triggerFastModeCooldown()`、`FastModeState` | +| `commands/fast/fast.tsx` | /fast 命令 UI + 定价显示 | + +**Qwen Code 修改方向**：需后端支持速度分级；`modelCommand.ts` 新增 `--fast` toggle（非指定备用模型）；UI 显示当前速度档位。 + +**相关文章**：[成本追踪与 Fast Mode](./cost-fastmode-deep-dive.md) + +**意义**：时间敏感任务（紧急 bug 修复）需要更快推理，日常任务需要更低成本。 +**缺失后果**：用户无法灵活平衡速度和成本——始终使用同一速度。 +**改进收益**：一键切换推理速度——紧急用 Fast，日常用 Standard，同一模型同一上下文。 + +--- + + + +### 28. Computer Use 桌面自动化（P2） + +**思路**：通过 MCP Server 桥接原生模块——截图（SCContentFilter）、鼠标/键盘（Rust enigo NAPI）、剪贴板操作。TCC 权限门控 + GrowthBook 特性开关 + 订阅检查。 + +**Claude Code 源码索引**： + +| 文件 | 关键函数/常量 | +|------|-------------| +| `utils/computerUse/executor.ts` | `moveMouse()`、`click()`、`type()`、截图 JPEG 0.75 | +| `utils/computerUse/mcpServer.ts` | 进程内 MCP Server（stdio） | +| `utils/computerUse/gates.ts` | GrowthBook `tengu_malort_pedway` | + +**Qwen Code 修改方向**：新建 `packages/computer-use/` 原生模块；注册为 MCP Server；`settingsSchema.ts` 新增门控。 + +**相关文章**：[Computer Use 桌面自动化](./computer-use-deep-dive.md) + +**意义**：前端调试和跨应用自动化需要 Agent '看到' 桌面——截图、点击、打字。 +**缺失后果**：Agent 只能操作文件和终端——无法操作浏览器/IDE/桌面应用。 +**改进收益**：解锁跨应用工作流——自动验证 UI、提取设计稿、操作数据库 GUI。 + +--- + + + +### 29. Denial Tracking（P2） + +**思路**：记录权限分类器的连续拒绝/成功次数（`maxConsecutive: 3`, `maxTotal: 20`）。超限时自动回退到 prompting 模式，避免分类器陷入"全拒绝"死循环。 + +**Claude Code 源码索引**： + +| 文件 | 关键函数/常量 | +|------|-------------| +| `utils/permissions/denialTracking.ts` (45行) | `DENIAL_LIMITS`、`recordDenial()`、`shouldFallbackToPrompting()` | + +**Qwen Code 修改方向**：`permission-manager.ts` 新增 `DenialTrackingState`；auto-edit/yolo 模式拒绝时累计；超限回退到 default 模式。 + +**意义**：权限分类器可能陷入连续拒绝的死循环——用户完全无感知。 +**缺失后果**：分类器可能永久阻塞合法操作——'静默失败'。 +**改进收益**：连续拒绝自动检测 → 回退到手动确认——用户看到被拒操作并可批准。 + +--- + + + +### 30. 并发 Session 管理（P2） + +**思路**：PID 文件（`~/.claude/sessions/{pid}.json`）追踪多终端会话——记录 kind（interactive/bg/daemon）、cwd、startedAt。`countConcurrentSessions()` 扫描并过滤已退出进程。 + +**Claude Code 源码索引**： + +| 文件 | 关键函数/常量 | +|------|-------------| +| `utils/concurrentSessions.ts` (204行) | `registerSession()`、`countConcurrentSessions()`、退出时 `registerCleanup()` | + +**Qwen Code 修改方向**：新建 `utils/concurrentSessions.ts`；`gemini.tsx` 启动时注册 PID 文件；退出时自动清理。 + +**相关文章**：[成本追踪与 Fast Mode](./cost-fastmode-deep-dive.md) + +**意义**：开发者常在多终端运行多个 Agent 实例——需要追踪和管理。 +**缺失后果**：无法了解其他终端的 Agent 状态——可能重复执行相同任务。 +**改进收益**：PID 追踪 + 后台脱附——多终端并行工作不冲突。 + +--- + + + +### 31. Git Diff 统计（P2） + +**思路**：两阶段 diff——`git diff --numstat` 快速探测（文件数 + 行数），再 `git diff` 完整 hunks。限制：50 文件、1MB/文件、400 行/文件。merge/rebase 期间跳过。 + +**Claude Code 源码索引**： + +| 文件 | 关键函数/常量 | +|------|-------------| +| `utils/gitDiff.ts` (532行) | `MAX_FILES = 50`、`MAX_DIFF_SIZE_BYTES = 1_000_000`、hunks 解析 | + +**Qwen Code 修改方向**：`gitWorktreeService.ts` 的 simple-git 调用替换为原生 `git diff --numstat` 解析；添加文件数/大小限制。 + +**相关文章**：[Git 工作流与会话管理](./git-workflow-session-deep-dive.md) + +**意义**：编辑后的 diff 统计帮助用户在 commit 前了解变更影响范围。 +**缺失后果**：无 git-aware diff——用户需手动 git diff 检查变更。 +**改进收益**：编辑后自动展示按文件统计的 diff——变更一目了然。 + +--- + + + +### 32. 文件历史快照（P2） + +**思路**：编辑前自动备份（SHA256 + mtime），按消息粒度创建快照（上限 100 个/session）。支持回滚到任意消息时刻——比 git checkpoint 更细粒度。 + +**Claude Code 源码索引**： + +| 文件 | 关键函数/常量 | +|------|-------------| +| `utils/fileHistory.ts` (1115行) | `fileHistoryTrackEdit()`、`fileHistoryMakeSnapshot()`、`MAX_SNAPSHOTS = 100` | + +**Qwen Code 修改方向**：`edit.ts` 和 `write-file.ts` 编辑前调用 snapshot；新建 `fileHistory.ts` 管理备份目录。 + +**相关文章**：[Git 工作流与会话管理](./git-workflow-session-deep-dive.md) + +**意义**：细粒度文件恢复比 git checkout 更灵活——可回滚到任意消息时刻。 +**缺失后果**：恢复粒度粗（git 级）——只能回到 checkpoint，不能回到特定消息。 +**改进收益**：按消息粒度恢复——Agent 第 3 步改错了可直接回到第 2 步。 + +--- + + + +### 33. Deep Link 协议（P2） + +**思路**：`claude-cli://open?q=&cwd=&repo=` URI scheme——OS 协议注册（macOS .app / Linux .desktop / Windows Registry）→ 终端自动检测（10+ 终端优先级链）→ 预填充 prompt。安全：来源 banner + 手动 Enter 确认。 + +**Claude Code 源码索引**： + +| 文件 | 关键函数/常量 | +|------|-------------| +| `utils/deepLink/parseDeepLink.ts` | URI 解析 + 参数验证（≤5000 字符） | +| `utils/deepLink/terminalLauncher.ts` | 10+ 终端检测（iTerm/Ghostty/Kitty/...） | +| `utils/deepLink/registerProtocol.ts` | macOS/Linux/Windows 协议注册 | + +**Qwen Code 修改方向**：新建 `utils/deepLink/`；注册 `qwen-code://` scheme；`gemini.tsx` 新增 `--handle-uri` 参数。 + +**相关文章**：[Deep Link 协议](./deep-link-protocol-deep-dive.md) + +**意义**：从浏览器/IDE/Slack 一键启动 Agent 减少上下文切换成本。 +**缺失后果**：每次都需打开终端 + cd 到项目目录 + 输入命令——切换成本高。 +**改进收益**：点击链接即启动——预填充 prompt + 自动定位项目目录。 + +--- + + + +### 34. Plan 模式 Interview（P2） + +**思路**：`EnterPlanMode` 支持 interview 阶段——先通过提问收集需求信息，再制定实施计划。分离"探索"和"执行"，减少返工。 + +**Claude Code 源码索引**： + +| 文件 | 关键函数/常量 | +|------|-------------| +| `tools/EnterPlanModeTool/EnterPlanModeTool.ts` | interview 阶段状态管理 | +| `tools/ExitPlanModeTool/ExitPlanModeV2Tool.ts` | 计划确认 + 执行过渡 | + +**Qwen Code 修改方向**：已有 `exitPlanMode` 工具；新增 `enterPlanMode` 工具支持 interview 阶段的附件系统。 + +**意义**：复杂任务先收集需求再动手——减少因理解不全导致的返工。 +**缺失后果**：Agent 直接开始执行——可能方向偏差后大量返工。 +**改进收益**：先 interview 收集完整需求 → 再制定计划 → 用户确认后执行。 + +--- + + + +### 35. BriefTool（P2） + +**思路**：Agent 向用户发送异步状态消息（含附件），不中断工具执行。用于 proactive status 更新——"已完成 3/5 个文件修改"。 + +**Claude Code 源码索引**： + +| 文件 | 关键函数/常量 | +|------|-------------| +| `tools/BriefTool/BriefTool.ts` | 异步消息发送 + 附件支持 | + +**Qwen Code 修改方向**：新建 `tools/brief.ts`；通过事件系统（`AgentEventEmitter`）向 UI 推送进度消息。 + +**意义**：长时间后台任务中用户需要了解进度——否则只能盲等。 +**缺失后果**：用户不知道 Agent 在做什么——只能等最终结果。 +**改进收益**：Agent 可异步推送进度消息——'已完成 3/5 个文件修改'。 + +--- + + + +### 36. SendMessageTool（P2） + +**思路**：多代理间消息传递——单播（name）、广播（`*`）、UDS Socket、Remote Control bridge。支持结构化消息（shutdown_request、plan_approval）。 + +**Claude Code 源码索引**： + +| 文件 | 关键函数/常量 | +|------|-------------| +| `tools/SendMessageTool/SendMessageTool.ts` (917行) | 路由逻辑（name → agentNameRegistry → tasks → mailbox）、broadcast | +| `utils/teammateMailbox.ts` (1183行) | 文件邮箱 + proper-lockfile | + +**Qwen Code 修改方向**：Arena 模式下新增消息传递工具；基于文件或 IPC 实现 agent 间通信。 + +**相关文章**：[多代理系统](./multi-agent-deep-dive.md) + +**意义**：多代理协作需要代理间通信——分配任务、报告进度、协调行动。 +**缺失后果**：Arena 模式下代理间无法通信——只能各自独立执行。 +**改进收益**：Leader 分配任务后 Worker 通过消息报告进度——真正的团队协作。 + +--- + + + +### 37. FileIndex（P2） + +**思路**：fzf 风格模糊文件搜索——异步增量索引 + nucleo 风格匹配。不需精确文件名即可定位。 + +**Claude Code 源码索引**： + +| 文件 | 关键函数/常量 | +|------|-------------| +| `native-ts/file-index/` | 原生 TS 文件索引器 | + +**Qwen Code 修改方向**：新建 `tools/fileIndex.ts`；基于 `glob` + 模糊匹配库（如 fzf-for-js）实现。 + +**意义**：大型仓库中精确文件名难以记住——模糊搜索是刚需。 +**缺失后果**：需要精确文件名才能定位——'那个 auth 相关的文件叫什么来着？' +**改进收益**：fzf 风格模糊搜索——输入部分关键词即可定位。 + +--- + + + +### 38. Notebook Edit（P2） + +**思路**：Jupyter `.ipynb` 文件的 cell 级编辑——插入/修改 code/markdown cell，自动追踪 cell ID，集成文件历史快照。 + +**Claude Code 源码索引**： + +| 文件 | 关键函数/常量 | +|------|-------------| +| `tools/NotebookEditTool/NotebookEditTool.ts` | cell 编辑 + ID 追踪 | + +**Qwen Code 修改方向**：新建 `tools/notebookEdit.ts`；解析 ipynb JSON → 定位 cell → 修改 → 写回。 + +**意义**：数据科学工作流大量使用 Jupyter notebook——原生支持是差异化能力。 +**缺失后果**：Agent 无法直接操作 .ipynb 文件——数据科学家需手动编辑。 +**改进收益**：原生 cell 级编辑——Agent 可直接修改 notebook 代码和 markdown。 + +--- + + + +### 39. 自定义快捷键（P2） + +**思路**：支持 multi-chord 组合键（如 `Ctrl+K Ctrl+S`）+ 跨平台适配（Windows VT mode 检测）+ `~/.claude/keybindings.json` 自定义。Reserved keys（Ctrl+C/D）不可重绑。 + +**Claude Code 源码索引**： + +| 文件 | 关键函数/常量 | +|------|-------------| +| `keybindings/` | `defaultBindings.ts`、multi-chord 状态机 | + +**Qwen Code 修改方向**：`KeypressContext.tsx` 扩展支持 chord 序列；新增 `~/.qwen/keybindings.json` 配置加载。 + +**意义**：高级用户对快捷键有强烈自定义需求——尤其 Vim 用户。 +**缺失后果**：固定快捷键无法满足不同用户习惯。 +**改进收益**：multi-chord + 自定义 keybindings.json——每个用户定制最顺手的操作方式。 + +--- + + + +### 40. Session Ingress Auth（P2） + +**思路**：远程会话 bearer token 认证——通过文件描述符或 well-known 文件传递 token。支持企业多用户环境下的安全 Agent 访问。 + +**Claude Code 源码索引**： + +| 文件 | 关键函数/常量 | +|------|-------------| +| `utils/sessionIngressAuth.ts` | bearer token 验证 | + +**Qwen Code 修改方向**：新建 `utils/sessionIngressAuth.ts`；headless 模式下验证 `--ingress-token` 参数。 + +**意义**：企业多用户环境需要安全的远程 Agent 访问控制。 +**缺失后果**：无认证机制——任何能访问端口的人都能操控 Agent。 +**改进收益**：bearer token 认证——仅授权用户可远程访问。 + +--- + + + +### 41. 企业代理支持（P2） + +**思路**：CONNECT-to-WebSocket relay 处理企业代理环境——CA cert 链注入、NO_PROXY 白名单（RFC1918 + API + GitHub + 包注册表）。失败时 fail-open 不阻断。 + +**Claude Code 源码索引**： + +| 文件 | 关键函数/常量 | +|------|-------------| +| `upstreamproxy/upstreamproxy.ts` | CONNECT relay + CA cert 注入 | +| `utils/proxy.ts` | `configureGlobalAgents()`、`getProxyFetchOptions()` | + +**Qwen Code 修改方向**：`config.ts` 扩展代理配置；Node.js `https.Agent` 注入自定义 CA cert。 + +**意义**：企业网络（代理/VPN/防火墙）是 Agent 部署的常见环境。 +**缺失后果**：企业代理环境下 API 调用失败——Agent 不可用。 +**改进收益**：CONNECT relay + CA cert 注入——企业网络环境下正常工作。 + +--- + + + +### 42. ConfigTool（P2） + +**思路**：模型通过工具 get/set 设置（主题、模型、权限等），带 schema 验证。模型可根据任务自动调整配置。 + +**Claude Code 源码索引**： + +| 文件 | 关键函数/常量 | +|------|-------------| +| `tools/ConfigTool/ConfigTool.ts` | get/set 操作 + schema 验证 | + +**Qwen Code 修改方向**：新建 `tools/config.ts`；通过 `config.ts` API 读写设置并验证。 + +**意义**：模型根据任务自动调整配置——如切换到更适合当前任务的模型。 +**缺失后果**：模型无法程序化修改设置——用户需手动 /settings。 +**改进收益**：Agent 可自主切换模型/主题/权限——根据任务需求自适应。 + +--- + + + +### 43. 终端主题检测（P2） + +**思路**：通过 OSC 11 查询终端背景色 + `$COLORFGBG` 环境变量回退——解析 `auto` 主题为具体 dark/light。 + +**Claude Code 源码索引**： + +| 文件 | 关键函数/常量 | +|------|-------------| +| `utils/systemTheme.ts` | `resolveThemeSetting()`（OSC 11 + COLORFGBG） | + +**Qwen Code 修改方向**：`semantic-colors.ts` 新增 `detectTheme()` 函数；启动时探测并设置默认主题。 + +**意义**：终端 dark/light 模式不一致会导致代码高亮和 UI 不可读。 +**缺失后果**：硬编码主题可能在浅色终端上不可见。 +**改进收益**：自动检测终端背景色——UI 始终可读。 + +--- + + + +### 44. 自动后台化 Agent（P2） + +**思路**：超过阈值（GrowthBook 配置的 ms 数）的 Agent 自动转后台——不阻塞用户交互。 + +**Claude Code 源码索引**： + +| 文件 | 关键函数/常量 | +|------|-------------| +| `tools/AgentTool/AgentTool.tsx` | `getAutoBackgroundMs()` | + +**Qwen Code 修改方向**：`agent.ts` 执行时启动 timer；超时将任务标记为 background 并释放前台。 + +**意义**：长时间 Agent 任务阻塞用户交互——用户只能等待。 +**缺失后果**：用户等 Agent 执行完才能继续输入——浪费时间。 +**改进收益**：超时自动转后台——用户继续交互，Agent 后台完成。 + +--- + + + +### 45. 队列输入编辑（P2） + +**思路**：排队中的命令在 prompt 下方可见。按 Escape 可将可编辑命令弹出到输入框重新编辑（过滤 task-notification、isMeta 等不可编辑项）。 + +**Claude Code 源码索引**： + +| 文件 | 关键函数/常量 | +|------|-------------| +| `utils/messageQueueManager.ts` | `popAllEditable()`、`isQueuedCommandEditable()` | + +**Qwen Code 修改方向**：`AsyncMessageQueue` 新增 `popEditable()` 方法；`InputPrompt.tsx` 渲染队列内容并处理 Escape。 + +**相关文章**：[输入队列与中断机制](./input-queue-deep-dive.md) + +**意义**：发现排队输入有误需要修改——但已入队无法撤回。 +**缺失后果**：错误输入已排队 → Agent 处理错误指令 → 需要额外一轮纠正。 +**改进收益**：Escape 弹出排队命令到输入框——修改后重新提交。 + +--- + + + +### 46. 状态栏紧凑布局（P2） + +**思路**：状态栏固定高度不随内容伸缩——"height so the footer never grows/shrinks and shifts scroll content"。最大化终端内容区域。 + +**Claude Code 源码索引**： + +| 文件 | 关键函数/常量 | +|------|-------------| +| `components/PromptInput/PromptInputFooterLeftSide.tsx` | 固定高度约束 | +| `components/StatusLine.tsx` | 条件显示（`statusLineShouldDisplay`） | + +**Qwen Code 修改方向**：`Footer.tsx` 添加 `height: 1`（或 Ink ``）固定行高；条件显示非关键信息。 + +**意义**：终端空间有限（笔记本 + 分屏），Footer 挤压内容区域。 +**缺失后果**：Footer 占用偏高——Agent 输出和用户输入可见行数减少。 +**改进收益**：固定高度 Footer——最大化内容区域，小终端也舒适。 + +--- + + + +### 47. Conditional Hooks（P2） + +**思路**：Hook 支持 `if` 字段——使用权限规则语法过滤何时执行（如 `Bash(git:*)` 仅在 git 命令时触发）。 + +**Claude Code 源码索引**： + +| 文件 | 关键函数/常量 | +|------|-------------| +| `utils/hooks/hookRunner.ts` | `if` 字段匹配逻辑 | +| `types/hooks.ts` | `HookConfig.if` 字段定义 | + +**Qwen Code 修改方向**：`hookRunner.ts` 执行前检查 `hook.if` 条件；复用权限规则匹配器（`permission-manager.ts`）。 + +**意义**：Hook 需要按场景过滤——不是所有工具调用都应触发所有 hook。 +**缺失后果**：所有匹配事件都触发——无法精细控制。 +**改进收益**：if 条件过滤——'仅在 git 命令时运行 pre-commit 检查'。 + +--- + + + +### 48. Transcript Search（P2） + +**思路**：transcript 模式下按 `/` 进入搜索，输入关键词后 `n`/`N` 在匹配项间导航。 + +**Claude Code 源码索引**： + +| 文件 | 关键函数/常量 | +|------|-------------| +| `components/Messages/` | transcript 搜索 UI + 高亮 | + +**Qwen Code 修改方向**：`HistoryItemDisplay.tsx` 新增搜索状态；`KeypressContext` 拦截 `/` 键进入搜索模式。 + +**意义**：长会话中回忆之前的讨论是常见需求。 +**缺失后果**：需手动滚动查找——'刚才说的那个 API 是什么？' +**改进收益**：/ 搜索 + n/N 导航——快速定位历史讨论。 + +--- + + + +### 49. Bash File Watcher（P2） + +**思路**：检测 formatter/linter 在 Agent 读取文件后修改了该文件——Agent 基于旧内容编辑会冲突。发出警告并建议重新 Read。 + +**Claude Code 源码索引**： + +| 文件 | 关键函数/常量 | +|------|-------------| +| `tools/BashTool/` | 文件 mtime 比对逻辑 | +| `utils/fileStateCache.ts` | 已读文件状态缓存 | + +**Qwen Code 修改方向**：`edit.ts` 编辑前比对文件 mtime 与上次 read 时的 mtime；不一致时警告并建议 re-read。 + +**意义**：formatter/linter 在 Agent 读取文件后可能自动修改——导致编辑冲突。 +**缺失后果**：Agent 基于旧内容编辑 → 覆盖 formatter 的修改 → 格式丢失。 +**改进收益**：自动检测文件被外部修改 → 提醒 re-read——避免 stale-edit。 + +--- + + + +### 50. /batch 并行操作（P2） + +**思路**：编排大规模并行变更——将任务拆分为多个子任务，fork 多个 Agent 并行执行，汇总结果。 + +**Claude Code 源码索引**： + +| 文件 | 关键函数/常量 | +|------|-------------| +| `skills/bundled/batch.ts` | /batch bundled skill | + +**Qwen Code 修改方向**：新建 `skills/bundled/batch/SKILL.md`；核心逻辑是解析用户输入 → 拆分 → fork 多个 Agent → 汇总。 + +**意义**：大规模重构（如'所有 class 组件迁移到 hooks'）需要并行处理多文件。 +**缺失后果**：只能逐文件处理——大规模重构耗时长。 +**改进收益**：并行拆分执行——多文件同时处理，速度倍增。 + +--- + + + +### 51. Chrome Extension 浏览器调试（P2） + +**思路**：Chrome 扩展通过 MCP 协议桥接——提供 `read_page`（DOM）、`read_console_messages`（Console）、`read_network_requests`（Network）、`navigate`、`switch_browser` 工具。通过 `/web-setup` 配置。 + +**Claude Code 源码索引**： + +| 文件 | 关键函数/常量 | +|------|-------------| +| `utils/claudeInChrome/mcpServer.ts` | Chrome MCP Server | +| `utils/claudeInChrome/chromeNativeHost.ts` | Native Messaging Host | + +**Qwen Code 修改方向**：开发 Chrome 扩展 + Native Messaging Host；注册为 MCP Server（tools: read_page/read_console/navigate）。 + +**意义**：前端调试需要 Agent 看到浏览器渲染结果和错误日志。 +**缺失后果**：Agent 无法'看到'浏览器——前端 bug 只能靠描述。 +**改进收益**：直接读取 DOM/Console/Network——前端调试效率大幅提升。 + +--- + + + +### 52. /effort 命令（P2） + +**思路**：动态设置模型 effort 级别（低 ○ / 中 ◐ / 高 ●）——影响推理深度和 token 消耗。显示在 prompt bar 和 spinner 上。 + +**Claude Code 源码索引**： + +| 文件 | 关键函数/常量 | +|------|-------------| +| `commands/effort/effort.tsx` | /effort 命令 UI | +| `utils/effort.ts` | `parseEffortValue()`、`getInitialEffortSetting()` | + +**Qwen Code 修改方向**：`settingsSchema.ts` 新增 `effort` 设置；新建 `/effort` 命令；`contentGenerator.ts` 按 effort 调整 `reasoning` 参数。 + +**意义**：不同任务需要不同推理深度——简单任务浪费 token，复杂任务推理不够。 +**缺失后果**：固定推理深度——无法灵活调整。 +**改进收益**：动态 effort 级别——简单任务省 token，复杂任务深度思考。 + +--- + + + +### 53. Status Line 自定义（P2） + +**思路**：用户配置 shell 脚本在状态栏展示自定义信息（如 rate limit 用量、git branch、构建状态）。脚本定期执行，输出显示在 footer。 + +**Claude Code 源码索引**： + +| 文件 | 关键函数/常量 | +|------|-------------| +| `components/StatusLine.tsx` | shell 脚本执行 + 输出渲染 | +| settings: `statusLine` | 配置项 | + +**Qwen Code 修改方向**：`settingsSchema.ts` 新增 `statusLine` 配置（shell 命令字符串）；`Footer.tsx` 定期执行并显示输出。 + +**意义**：状态栏是实时信息展示的最佳位置——rate limit、git branch 等。 +**缺失后果**：状态栏内容固定——无法展示用户关心的自定义信息。 +**改进收益**：shell 脚本自定义——展示 rate limit 用量、构建状态等。 + +--- + + + +### 54. Fullscreen Rendering（P2） + +**思路**：Alt-screen 渲染 + 虚拟滚动缓冲区——完全消除终端闪烁。通过 `CLAUDE_CODE_NO_FLICKER=1` 启用。 + +**Claude Code 源码索引**： + +| 文件 | 关键函数/常量 | +|------|-------------| +| `utils/fullscreen.ts` | alt-screen 切换 + 虚拟化 | + +**Qwen Code 修改方向**：`AppContainer.tsx` 新增 fullscreen 模式；通过 ANSI alt-screen sequences 切换；Ink `` 虚拟化长内容。 + +**意义**：终端闪烁是低性能终端上的常见 UX 问题。 +**缺失后果**：长输出时终端闪烁——视觉体验差。 +**改进收益**：alt-screen 无闪烁渲染——视觉稳定。 + +--- + + + +### 55. Image [Image #N] Chips（P2） + +**思路**：粘贴图片后在输入框生成 `[Image #1]`、`[Image #2]` 位置标记——用户可在 prompt 中引用特定图片（"修复 [Image #1] 中的 bug"）。 + +**Claude Code 源码索引**： + +| 文件 | 关键函数/常量 | +|------|-------------| +| `components/PromptInput/PromptInput.tsx` (L581) | `parseReferences()` + `[Image` filter | + +**Qwen Code 修改方向**：`InputPrompt.tsx` 粘贴图片时插入 `[Image #N]` 文本标记；发送时将标记替换为实际图片引用。 + +**意义**：多图场景需要精确引用特定图片。 +**缺失后果**：粘贴多张图片后无法区分——'哪张图的 bug？' +**改进收益**：[Image #1] 标记——'修复 [Image #1] 中的 bug'精确引用。 + +--- + + + +### 56. --max-turns 限制（P2） + +**思路**：headless 模式 `--max-turns N` 限制最大 agentic turn 数——防止无限循环，CI 精确控制执行范围。 + +**Claude Code 源码索引**： + +| 文件 | 关键函数/常量 | +|------|-------------| +| `main.tsx` | `--max-turns` CLI 参数 | +| `query.ts` | turn 计数 + 超限退出 | + +**Qwen Code 修改方向**：`nonInteractiveCli.ts` 新增 `--max-turns` 参数；`agent-core.ts` 的 `runReasoningLoop` 中按 turn 计数退出。 + +**意义**：headless 模式需要防止无限循环——CI 不应无限运行。 +**缺失后果**：Agent 可能陷入循环无限重试——CI 超时才会停。 +**改进收益**：--max-turns N 精确控制——最多 N 轮后自动停止。 + +--- + + + +### 57. --max-budget-usd 花费上限（P2） + +**思路**：headless 模式 `--max-budget-usd N` 限制 USD 花费——累计超过阈值自动停止。防止意外高消耗。 + +**Claude Code 源码索引**： + +| 文件 | 关键函数/常量 | +|------|-------------| +| `main.tsx` | `--max-budget-usd` CLI 参数 | +| `cost-tracker.ts` | 累计成本检查 | + +**Qwen Code 修改方向**：`nonInteractiveCli.ts` 新增 `--max-budget` 参数；每次 API 响应后检查累计 token 成本。 + +**意义**：headless 模式需要花费上限——防止意外高消耗。 +**缺失后果**：无花费保护——一次运行可能消耗大量 token。 +**改进收益**：--max-budget-usd 5 限制——超过自动停止。 + +--- + + + +### 58. Connectors 托管式 MCP（P2） + +**思路**：托管式 MCP 连接——OAuth 认证的 GitHub/Slack/Linear/Google Drive 等连接器。处理 token 刷新、401 重试、连接器去重（本地优先）。 + +**Claude Code 源码索引**： + +| 文件 | 关键函数/常量 | +|------|-------------| +| `services/mcp/client.ts` | OAuth token 管理 + 401 重试 + 连接器去重 | + +**Qwen Code 修改方向**：`mcp-client.ts` 扩展 OAuth 连接管理；新增托管连接器配置 UI（类似 `/mcp` 对话框）。 + +**意义**：与外部服务（GitHub/Slack/Linear）的集成需要 OAuth 管理。 +**缺失后果**：手动配置 token + 手动刷新——容易过期。 +**改进收益**：托管式 OAuth——一键连接，自动刷新，401 自动重试。 diff --git a/docs/comparison/qwen-code-improvement-report-p3.md b/docs/comparison/qwen-code-improvement-report-p3.md new file mode 100644 index 00000000..c7303f9d --- /dev/null +++ b/docs/comparison/qwen-code-improvement-report-p3.md @@ -0,0 +1,214 @@ +# Qwen Code 改进建议 — P3 详细说明 + +> 低优先级改进项。每项包含：思路概述、Claude Code 源码索引、Qwen Code 修改方向。 +> +> 返回 [改进建议总览](./qwen-code-improvement-report.md) + +--- + + + +### 59. 动态状态栏（P3） + +**思路**：`AppState.statusLineText` 允许模型/工具实时更新状态文本（如"正在分析 5 个文件..."），提供执行进度可见性。 + +**Claude Code 源码索引**： + +| 文件 | 关键函数/常量 | +|------|-------------| +| `state/AppStateStore.ts` | `statusLineText: string` | +| `components/StatusLine.tsx` | 条件渲染 | + +**Qwen Code 修改方向**：`UIStateContext` 新增 `statusText` 状态；工具执行时通过 `setUIState()` 更新；`Footer.tsx` 渲染。 + +**意义**：用户不知道 Agent 当前在做什么——长时间执行时焦虑等待。 +**缺失后果**：仅有 spinner 无具体信息——'还要等多久？在做什么？' +**改进收益**：动态状态文本——'正在分析 5 个文件...'——减少等待焦虑。 + +--- + + + +### 60. 上下文折叠 History Snip（P3） + +**思路**：`feature('HISTORY_SNIP')` 门控。**Claude Code 自身仅 scaffolding**——SnipTool 有 lazy require 占位无完整实现。已有 `collapseReadSearch.ts` 的 UI 级消息折叠（连续 read/search 合并显示）。 + +**Claude Code 源码索引**： + +| 文件 | 关键函数/常量 | +|------|-------------| +| `utils/collapseReadSearch.ts` | UI 级连续 read/search 折叠 | + +**Qwen Code 修改方向**：参考方向——连续工具调用的 UI 折叠显示（不改变 API 发送内容）。 + +**意义**：早期对话占满上下文但内容已过时——比全量压缩更精细的方案。 +**缺失后果**：注意：Claude Code 自身仅 scaffolding，无完整实现。参考方向。 +**改进收益**：UI 级折叠——连续 read/search 合并显示，减少视觉噪音。 + +--- + + + +### 61. 内存诊断（P3） + +**思路**：1.5GB 阈值触发 V8 heap snapshot + Linux smaps_rollup 解析 + 内存增长率分析 → leak 建议。 + +**Claude Code 源码索引**： + +| 文件 | 关键函数/常量 | +|------|-------------| +| `utils/heapDumpService.ts` | 阈值触发 + heap snapshot | + +**Qwen Code 修改方向**：`process.memoryUsage()` 定期检查；超限时 `v8.writeHeapSnapshot()`。 + +**意义**：长会话可能内存泄漏——Agent 进程 OOM 导致 session 丢失。 +**缺失后果**：无内存监控——OOM 时直接崩溃，无诊断信息。 +**改进收益**：1.5GB 阈值预警 + heap snapshot——提前发现并诊断泄漏。 + +--- + + + +### 62. Feature Gates（P3） + +**思路**：GrowthBook 远程特性开关——A/B 测试 + 按事件动态采样。渐进式灰度发布。 + +**Claude Code 源码索引**： + +| 文件 | 关键函数/常量 | +|------|-------------| +| `services/analytics/growthbook.ts` | `initializeGrowthBook()`、`getFeatureValue_CACHED_MAY_BE_STALE()` | + +**Qwen Code 修改方向**：集成 GrowthBook SDK 或自建 feature flag 服务。 + +**意义**：新功能灰度发布降低全量上线风险——A/B 测试数据驱动决策。 +**缺失后果**：新功能只能全量发布——出问题影响所有用户。 +**改进收益**：渐进式灰度——先 1% 用户验证，确认无问题后全量。 + +--- + + + +### 63. DXT/MCPB 插件包（P3） + +**思路**：`.dxt`/`.mcpb` 单文件打包 MCP 服务器 + 依赖。zip bomb 防护（512MB/文件、1GB 总量、50:1 压缩比）。 + +**Qwen Code 修改方向**：定义包格式（zip + manifest.json）；安装时验证大小/压缩比。 + +**意义**：MCP 插件分发需要打包依赖——避免安装环境不一致。 +**缺失后果**：松散文件分发——依赖缺失导致安装失败。 +**改进收益**：单文件安装 + zip bomb 防护——安全可靠的插件分发。 + +--- + + + +### 64. /security-review（P3） + +**思路**：基于 git diff 的安全审查命令，聚焦 OWASP Top 10 漏洞检测。 + +**Qwen Code 修改方向**：新建 `skills/bundled/security-review/SKILL.md`，prompt 模板聚焦安全。 + +**意义**：代码提交前的安全扫描是 DevSecOps 的基本要求。 +**缺失后果**：无内置安全审查——安全漏洞可能被合并到代码库。 +**改进收益**：基于 diff 的安全审查——聚焦新增代码的 OWASP Top 10。 + +--- + + + +### 65. Ultraplan 远程计划探索（P3） + +**思路**：启动远程 CCR 会话，用更强模型深度规划后回传结果。需云端执行基础设施。 + +**Qwen Code 修改方向**：需先有 Web 版本；`--remote` flag 创建云端 session。 + +**意义**：复杂项目规划需要更强模型的深度推理——本地模型可能不够。 +**缺失后果**：规划仅能用当前模型——深度思考能力受限。 +**改进收益**：远程调用更强模型规划——结果回传到本地执行。 + +--- + + + +### 66. Advisor 顾问模型（P3） + +**思路**：`/advisor` 配置副模型（如更强模型）审查主模型输出。`server_tool_use` 方式自动调用。 + +**Claude Code 源码索引**： + +| 文件 | 关键函数/常量 | +|------|-------------| +| `utils/advisor.ts` | `isAdvisorEnabled()`、GrowthBook `tengu_sage_compass` | + +**Qwen Code 修改方向**：需多模型同时调用能力；response 后追加审查模型调用。 + +**意义**：主模型输出质量不稳定——副模型审查可提升可靠性。 +**缺失后果**：无审查机制——错误输出可能被直接执行。 +**改进收益**：副模型自动审查——发现主模型遗漏的问题。 + +--- + + + +### 67. Vim 完整实现（P3） + +**思路**：完整 modal editing——motions + operators + text objects + transitions。4 文件结构。 + +**Claude Code 源码索引**： + +| 文件 | 关键函数/常量 | +|------|-------------| +| `keybindings/motions.ts` | hjkl/w/b/e/0/$ | +| `keybindings/operators.ts` | d/c/y | +| `keybindings/textObjects.ts` | iw/aw/i"/a" | + +**Qwen Code 修改方向**：扩展现有 `vim.ts`——补充 text objects 和 operators。 + +**意义**：Vim 用户群体庞大——完整 modal editing 是差异化竞争力。 +**缺失后果**：基础 vim 模式缺少 text objects 和 operators——Vim 用户体验不完整。 +**改进收益**：完整 Vim 体验——motions + operators + text objects 全覆盖。 + +--- + + + +### 68. 语音模式（P3） + +**思路**：push-to-talk 语音输入 + 流式 STT 转录。快捷键可通过 `keybindings.json` 重绑。 + +**Claude Code 源码索引**： + +| 文件 | 关键函数/常量 | +|------|-------------| +| `commands/voice/` | push-to-talk + STT | +| keybindings: `voice:pushToTalk` | 绑定配置 | + +**Qwen Code 修改方向**：需音频捕获 NAPI + STT API（如阿里云 ASR）。 + +**意义**：语音输入解放双手——适合代码审查讨论、快速口述需求。 +**缺失后果**：只能键盘输入——手不方便时无法使用。 +**改进收益**：push-to-talk 语音输入——说完自动转文字。 + +--- + + + +### 69. 插件市场（P3） + +**思路**：官方 marketplace 安装插件（hooks/commands/agents/MCP），安装状态追踪，自动更新。 + +**Claude Code 源码索引**： + +| 文件 | 关键函数/常量 | +|------|-------------| +| `utils/plugins/pluginLoader.ts` | 加载 + marketplace 同步 | +| `utils/plugins/pluginInstaller.ts` | 安装 + 版本管理 | + +**Qwen Code 修改方向**：已有 extension 系统；新增 marketplace 发现 + git-based 安装。 + +**意义**：插件生态是工具平台化的关键——用户和社区可扩展功能。 +**缺失后果**：功能扩展依赖官方开发——社区无法贡献。 +**改进收益**：插件市场——社区可发布和发现插件，生态自增长。 + +**相关文章**：[Hook 与插件扩展](./hook-plugin-extension-deep-dive.md) diff --git a/docs/comparison/qwen-code-improvement-report.md b/docs/comparison/qwen-code-improvement-report.md index de643d22..8b3fdb98 100644 --- a/docs/comparison/qwen-code-improvement-report.md +++ b/docs/comparison/qwen-code-improvement-report.md @@ -37,251 +37,97 @@ | 优先级 | 改进点 | Qwen Code 现状 | 难度 | 进展 | |:------:|--------|----------------|:----:|------| -| **P0** | [Mid-Turn Queue Drain](./input-queue-deep-dive.md)（工具批次间注入用户输入） | 推理循环内无队列检查 | 中 | PR [#2854](https://github.com/QwenLM/qwen-code/pull/2854) open | -| **P0** | [多层上下文压缩](./context-compression-deep-dive.md)（4 层 vs 单一 70% 阈值） | 仅 ChatCompressionService | 中 | — | -| **P0** | [Fork 子代理](./fork-subagent-deep-dive.md)（隐式 fork + 上下文继承 + prompt cache 共享） | 仅预定义 subagent_type | 中 | — | -| **P1** | [Speculation](../tools/claude-code/10-prompt-suggestions.md) 默认启用 | v0.15.0 已实现，默认关闭 | 小 | PR [#2525](https://github.com/QwenLM/qwen-code/pull/2525) merged | -| **P1** | [会话记忆](./memory-system-deep-dive.md)（SessionMemory + memdir 跨 session 检索） | 仅简单笔记工具 | 大 | — | -| **P1** | Auto Dream（自动记忆整理，24h + 5 session 门控） | 缺失 | 中 | — | -| **P1** | 上下文折叠（History Snip，span 级摘要） | 缺失 | 大 | — | -| **P1** | 工具动态发现（ToolSearchTool，延迟加载 + 搜索） | 缺失 | 小 | — | -| **P1** | [智能工具并行](./tool-parallelism-deep-dive.md)（Kind-based Batching，默认 10 并发） | Agent 并发 / 其他顺序 | 小 | PR [#2864](https://github.com/QwenLM/qwen-code/pull/2864) open | -| **P1** | [启动优化](./startup-optimization-deep-dive.md)（API Preconnect + Early Input Capture） | 完全缺失 | 小 | — | -| **P1** | [指令条件规则](./instruction-loading-deep-dive.md)（frontmatter `paths:` + 惰加载） | 无 frontmatter / 条件加载 | 中 | — | -| **P2** | [Shell 安全增强](./shell-security-deep-dive.md)（25+ 检查 vs AST-only 读写分类） | 不覆盖 IFS/Unicode/Zsh | 中 | — | -| **P2** | [MDM 企业策略](./mdm-enterprise-deep-dive.md)（plist + Registry + 远程 API） | 无 OS 级策略 | 大 | — | -| **P2** | [API 实时 Token 计数](./token-estimation-deep-dive.md)（vs 静态 82 模式匹配） | 静态模式匹配 | 中 | — | -| **P2** | Plan 模式 Interview Phase | 无 interview 阶段 | 中 | — | -| **P2** | BriefTool（异步消息 + 附件） | 缺失 | 中 | — | -| **P2** | [SendMessageTool](./multi-agent-deep-dive.md)（多代理通信） | 缺失 | 中 | — | -| **P2** | FileIndex（fzf 风格模糊搜索） | 依赖 rg/glob | 中 | — | -| **P2** | ConfigTool（工具化设置读写） | 仅 /settings 命令 | 小 | — | -| **P2** | 自动后台化 Agent（超时转后台） | 需显式指定 | 小 | — | -| **P3** | /security-review 安全审查命令 | 缺失 | 小 | — | -| **P3** | Ultraplan 远程计划探索 | 缺失 | 大 | — | -| **P3** | Advisor 顾问模型 | 缺失 | 中 | — | -| **P3** | Vim 完整实现（motions/operators/textObjects） | 基础 vim.ts | 中 | — | -| **P3** | 语音模式 | 缺失 | 大 | — | -| **P3** | [插件市场](./hook-plugin-extension-deep-dive.md) | 缺失 | 大 | — | - -> 详细的 Claude Code 实现机制和建议方案见下文 Top 5 详细说明及各 [Deep-Dive 文章](#五相关-deep-dive-文章)。 - -## 三、Top 5 改进点详细说明 - -### 1. 多层上下文压缩 (Context Compression) 策略（P0） - -**Claude Code 实现**： -- `services/compact/microCompact.ts` — turn 级微压缩，移除冗余工具结果 -- `services/compact/autoCompact.ts` — 基于 token 阈值的自动压缩 -- `services/compact/apiMicrocompact.ts` — API 原生上下文管理（`clear_tool_uses` / `clear_thinking`） -- `services/compact/sessionMemoryCompact.ts` — 基于会话记忆 (Memory) 的压缩，保留关键上下文 -- `services/compact/postCompactCleanup.ts` — 压缩后清理 -- `services/compact/grouping.ts` — 消息分组优化 - -**源码引用**： -- 源码: `services/compact/autoCompact.ts` -- 源码: `services/compact/sessionMemoryCompact.ts` -- 源码: `services/compact/compact.ts`（1705 行） - -**Qwen Code 现状**： -- 源码: `packages/core/src/services/chatCompressionService.ts`（369 行），基于固定 token 阈值（70%）的单一压缩策略 -- 无 micro-compact、无 memory-aware compact、无 API 原生上下文管理 - -**缺失后果**： -- 长会话中工具结果（大文件内容、长命令输出）持续累积，用户必须手动执行 `/compress`，否则上下文溢出报错 -- 压缩时一次性丢弃所有历史，丢失已提取的会话记忆——压缩后模型"失忆"，需重新描述上下文 -- 无 `cache_edits` API 支持——每次压缩重建整个 prompt cache，浪费 cache write tokens - -**改进收益**： -- **MicroCompact**：自动在 turn 间裁剪旧工具结果，长会话可无限延续而无需手动干预 -- **Session-Memory Compact**：压缩时保留关键记忆 + 最近 5 个文件重注入——压缩后模型仍能"接着干" -- **多级阈值**：~93% 自动触发（Claude Code 默认）vs 70% 手动触发——用户感知不到压缩发生 - -**相关文章**： -- [上下文压缩深度对比](./context-compression-deep-dive.md) - -**建议方案**： -1. 实现 micro-compact：在每个 turn 结束后，自动裁剪冗余的工具结果（如大文件读取的截断部分） -2. 实现 session-memory compact：压缩时保留已提取的会话记忆 (Memory)，而非简单丢弃 -3. 引入多级压缩阈值（而非单一 70%），根据模型 token 限制动态调整 - ---- - -### 2. Fork 子代理 (Subagent)（P0） - -**Claude Code 实现**： -- `tools/AgentTool/forkSubagent.ts` — fork 机制核心 -- 当 `subagent_type` 未指定时，自动 fork 当前会话上下文 -- 子代理继承父代理的完整对话历史、系统 prompt、工具池 -- 使用 `FORK_BOILERPLATE_TAG` 防止递归 fork -- prompt cache 优化：所有 fork 子代理产生字节一致的 API 请求前缀 - -**源码引用**： -- 源码: `tools/AgentTool/forkSubagent.ts`（210 行） -- 源码: `tools/AgentTool/AgentTool.tsx`（1397 行） -- 源码: `tools/AgentTool/runAgent.ts`（973 行） - -**Qwen Code 现状**： -- 源码: `packages/core/src/tools/agent.ts` — Agent 工具存在，但必须显式指定 `subagent_type` -- 源码: `packages/core/src/subagents/` — 子代理管理器，但仅支持预定义类型 -- 无法 fork 当前会话上下文，无法继承对话历史 - -**缺失后果**： -- 子代理无法获得父代理的对话上下文——每次委派任务都需要在 prompt 中重复描述背景，增加 token 消耗和信息丢失风险 -- 每个子代理的 API 请求前缀完全不同——无法共享 prompt cache，5 个子代理 = 5× 完整 prompt 费用（100K context 下约 500K tokens vs fork 模式 ~105K） -- 用户必须显式指定 `subagent_type`——模型无法自然地"分叉去做"，降低了自主性 - -**改进收益**： -- **上下文零成本传递**：子代理继承完整对话历史，无需重复描述——任务理解准确率提升 -- **Prompt Cache 共享**：N 个 fork 子代理共享一份缓存，成本从 N× 降为 ~1×——典型场景节省 80%+ token 费用 -- **隐式调用**：省略 `subagent_type` 即 fork——降低模型认知负担，让委派更自然 - -**相关文章**： -- [Fork 子代理 Deep-Dive](./fork-subagent-deep-dive.md) -- [Claude Code 多代理系统](../tools/claude-code/09-multi-agent.md) - -**建议方案**： -1. 在 Agent 工具 schema 中将 `subagent_type` 改为可选 -2. 实现 fork 消息构建逻辑：从当前对话历史构建子代理上下文 -3. 实现递归 fork 防护（检测 fork boilerplate tag） -4. 优化 prompt cache：确保 fork 前缀的字节一致性 - ---- - -### 3. 投机执行 (Speculation) 系统完善（P1） - -**Claude Code 实现**： -- `services/PromptSuggestion/speculation.ts` — 991 行完整投机执行 (Speculation) 引擎 -- 使用 overlay-fs 实现 copy-on-write 文件隔离 -- 写操作写入 overlay 目录，用户确认后 copy-overlay-to-main -- 自动检测 write tools（Edit/Write/NotebookEdit）并拒绝投机 -- 与 PromptSuggestion 深度集成：suggestion 展示时自动启动投机 - -**源码引用**： -- 源码: `services/PromptSuggestion/speculation.ts`（991 行） -- 源码: `services/PromptSuggestion/promptSuggestion.ts` - -**Qwen Code 现状**： -- 源码: `packages/core/src/followup/speculation.ts`（563 行）— v0.15.0 已实现完整系统 -- 源码: `packages/core/src/followup/overlayFs.ts`（140 行）— Copy-on-Write overlay 文件系统 -- 源码: `packages/core/src/followup/speculationToolGate.ts`（146 行）— 工具安全分类（safe/write/boundary/unknown） -- 源码: `packages/core/src/followup/suggestionGenerator.ts`（367 行）— 建议生成 + 12 条过滤规则 -- 已实现 `acceptSpeculation()` + `generatePipelinedSuggestion()` + 边界检测 -- **当前限制**：`enableSpeculation` 默认关闭，需用户手动开启 - -**缺失后果（默认关闭）**： -- 用户每次按 Tab 接受建议后，仍需等待完整的 API 调用 + 工具执行——典型等待 2-10 秒 -- 无法实现"Tab-Tab-Tab"连续操作模式——每次接受后都有延迟中断 - -**改进收益（默认开启后）**： -- **零感知延迟**：建议展示时 speculation 已在后台预执行，Tab 接受后结果立即呈现 -- **Pipelined Suggestion**：speculation 完成后自动预生成下一个建议——用户可连续 Tab 操作 -- 预计首次交互延迟改善 2-5 秒（取决于工具执行时间） - -**相关文章**： -- [Claude Code 提示建议](../tools/claude-code/10-prompt-suggestions.md) -- [启动阶段优化深度对比](./startup-optimization-deep-dive.md) -- [输入队列深度对比](./input-queue-deep-dive.md) - -**建议方案**： -1. 将 `enableSpeculation` 默认值改为 `true`（当前为 `false`） -2. 扩大 speculationToolGate 的 safe 工具列表覆盖度 -3. 增加 speculation 完成率的遥测追踪，评估 boundary 命中频率 -4. 优化 `MAX_SPECULATION_TURNS`（当前 20）的动态调节策略 - ---- - -### 4. 会话记忆 (Session Memory) 系统（P1） - -**Claude Code 实现**： -- `services/SessionMemory/sessionMemory.ts` — 会话记忆 (Memory) 管理 -- `services/SessionMemory/sessionMemoryUtils.ts` — 记忆 (Memory) 提取和检索 -- `services/SessionMemory/prompts.ts` — 记忆 (Memory) 提取 prompt -- `memdir/` 目录（8 文件）— 记忆 (Memory) 目录和检索系统 -- `memdir/findRelevantMemories.ts` — 基于相关性的记忆 (Memory) 检索 -- 跨 session 持久化：记忆 (Memory) 在 session 结束后自动提取并存储 - -**源码引用**： -- 源码: `services/SessionMemory/sessionMemory.ts` -- 源码: `memdir/findRelevantMemories.ts` -- 源码: `memdir/memdir.ts` - -**Qwen Code 现状**： -- 源码: `packages/core/src/tools/memoryTool.ts` — 仅支持简单的笔记读写 -- 无跨 session 记忆 (Memory) -- 无记忆 (Memory) 提取/检索机制 -- 无记忆 (Memory) 生命周期管理 - -**缺失后果**： -- 每次新 session 从零开始——用户需反复告知项目背景、编码规范、已踩过的坑 -- 复杂项目中同一问题被多次排查——前次 session 的发现未持久化 -- 与 `/compact` 冲突——压缩后丢失的上下文无法从记忆中恢复 - -**改进收益**： -- **跨 session 连续性**：关键决策、文件结构、技术栈信息自动提取并持久化——新 session 自动注入相关记忆 -- **压缩后恢复**：记忆在 compact 时被保留（session-memory compact），模型不会因压缩而"失忆" -- **项目级知识积累**：多人/多 session 的发现汇聚为项目知识库——团队共享学习曲线 - -**相关文章**： -- [记忆系统深度对比](./memory-system-deep-dive.md) - -**建议方案**： -1. 实现 SessionMemoryService：管理会话记忆 (Memory) 的提取、存储和检索 -2. 实现记忆 (Memory) 提取 hook：在 compact 或 session 结束时自动提取关键信息 -3. 实现记忆 (Memory) 检索工具：在新 session 开始时检索相关记忆 (Memory) -4. 记忆 (Memory) 持久化到 `.qwen/` 目录，支持项目级和用户级记忆 (Memory) - ---- - -### 5. Auto Dream 自动记忆 (Memory) 整理（P1） - -**Claude Code 实现**： -- `services/autoDream/autoDream.ts` — 自动记忆 (Memory) 整理引擎（325 行） -- 双门控触发：时间门控（默认 24h）+ session 数量门控（默认 5 个 session） -- 使用 forked agent 在后台执行记忆 (Memory) 整理 -- `services/autoDream/consolidationPrompt.ts` — 整理 prompt -- `services/autoDream/consolidationLock.ts` — 防止多进程并发整理 - -**源码引用**： -- 源码: `services/autoDream/autoDream.ts`（324 行） -- 源码: `services/autoDream/consolidationPrompt.ts` -- 源码: `services/autoDream/consolidationLock.ts` - -**相关文章**： -- [记忆系统深度对比](./memory-system-deep-dive.md) -- [上下文压缩深度对比](./context-compression-deep-dive.md) - -**Qwen Code 现状**： -- 完全缺失此功能 - -**缺失后果**： -- 记忆文件（QWEN.md / MEMORY.md）随使用增长无限膨胀——token 预算被陈旧记忆占满 -- 相互矛盾的记忆（旧决策 vs 新决策）共存——模型收到冲突指令 -- 用户需手动清理过时记忆——违背"AI 代理应自治"原则 - -**改进收益**： -- **自动整合**：后台 agent 定期合并、去重、删除过时记忆——记忆始终精简且一致 -- **门控保护**：仅在 24h + 5 session 门控同时满足时触发——避免频繁整理干扰正常使用 -- **并发安全**：文件锁防止多进程同时整理——适合多终端/CI 场景 - -**建议方案**： -1. 实现 DreamConfig：定义时间门控和 session 数量门控参数 -2. 实现 DreamScheduler：在 post-sampling hook 中检查门控条件 -3. 当门控触发时，fork 一个只读 agent 执行记忆整理 -4. 实现 ConsolidationLock：使用文件锁防止并发整理 -5. 整理结果写入 `.qwen/dream/` 目录，供后续 session 检索 - ---- +| **P0** | [Mid-Turn Queue Drain](./input-queue-deep-dive.md) — Agent 执行中途注入用户输入，无需等整轮结束 [↓](./qwen-code-improvement-report-p0-p1.md#item-6) | 推理循环内无队列检查 | 中 | [PR#2854](https://github.com/QwenLM/qwen-code/pull/2854) | +| **P0** | [多层上下文压缩](./context-compression-deep-dive.md) — 自动裁剪旧工具结果 + 摘要，用户无需手动 /compress [↓](./qwen-code-improvement-report-p0-p1.md#item-1) | 仅单一 70% 手动压缩 | 中 | — | +| **P0** | [Fork 子代理](./fork-subagent-deep-dive.md) — 子代理继承完整对话上下文，共享 prompt cache 省 80%+ 费用 [↓](./qwen-code-improvement-report-p0-p1.md#item-2) | 子代理必须从零开始 | 中 | — | +| **P1** | [Speculation](../tools/claude-code/10-prompt-suggestions.md) — 预测用户下一步并提前执行，Tab 接受零延迟 [↓](./qwen-code-improvement-report-p0-p1.md#item-3) | 已实现但默认关闭 | 小 | [PR#2525](https://github.com/QwenLM/qwen-code/pull/2525) ✓ | +| **P1** | [会话记忆](./memory-system-deep-dive.md) — 关键决策/文件结构自动提取，新 session 自动注入 [↓](./qwen-code-improvement-report-p0-p1.md#item-4) | 仅简单笔记工具 | 大 | — | +| **P1** | [Auto Dream](./memory-system-deep-dive.md) — 后台 agent 自动合并去重过时记忆 [↓](./qwen-code-improvement-report-p0-p1.md#item-5) | 缺失 | 中 | — | +| **P1** | [工具动态发现](./tool-search-deep-dive.md) — 仅加载核心工具，其余按需搜索，省 50%+ token [↓](./qwen-code-improvement-report-p0-p1.md#item-11) | 全部工具始终加载 | 小 | — | +| **P1** | [智能工具并行](./tool-parallelism-deep-dive.md) — 连续只读工具并行执行，代码探索快 5-10× [↓](./qwen-code-improvement-report-p0-p1.md#item-7) | 除 Agent 外全部顺序 | 小 | [PR#2864](https://github.com/QwenLM/qwen-code/pull/2864) | +| **P1** | [启动优化](./startup-optimization-deep-dive.md) — TCP 预连接 + 启动期间键盘捕获不丢失 [↓](./qwen-code-improvement-report-p0-p1.md#item-8) | 完全缺失 | 小 | — | +| **P1** | [指令条件规则](./instruction-loading-deep-dive.md) — 按文件路径匹配加载不同编码规范 [↓](./qwen-code-improvement-report-p0-p1.md#item-9) | 所有指令始终加载 | 中 | — | +| **P1** | [Commit Attribution](./git-workflow-session-deep-dive.md) — git commit 中标注 AI vs 人类代码贡献比例 [↓](./qwen-code-improvement-report-p0-p1.md#item-12) | 缺失 | 小 | — | +| **P1** | [会话分支](./git-workflow-session-deep-dive.md) — /branch 从任意节点 fork 对话，探索替代方案 [↓](./qwen-code-improvement-report-p0-p1.md#item-13) | 缺失 | 中 | — | +| **P2** | [Shell 安全增强](./shell-security-deep-dive.md) — IFS 注入/Unicode 空白/Zsh 命令等 25+ 专项检查 [↓](./qwen-code-improvement-report-p2.md#item-23) | AST-only 读写分类 | 中 | — | +| **P2** | [MDM 企业策略](./mdm-enterprise-deep-dive.md) — macOS plist + Windows Registry + 远程 API 集中管控 [↓](./qwen-code-improvement-report-p2.md#item-24) | 无 OS 级策略 | 大 | — | +| **P2** | [API 实时 Token 计数](./token-estimation-deep-dive.md) — 每次 API 调用前精确计数，3 层回退 [↓](./qwen-code-improvement-report-p2.md#item-25) | 静态 82 种模式匹配 | 中 | — | +| **P2** | [Output Styles](./git-workflow-session-deep-dive.md) — Learning 模式暂停让用户写代码，Explanatory 添加教育洞察 [↓](./qwen-code-improvement-report-p2.md#item-26) | 缺失 | 中 | — | +| **P2** | [Fast Mode](./cost-fastmode-deep-dive.md) — 同一模型标准/快速推理切换（$5→$30/Mtok），含冷却机制 [↓](./qwen-code-improvement-report-p2.md#item-27) | 仅指定备用模型 | 小 | — | +| **P2** | [并发 Session](./cost-fastmode-deep-dive.md) — 多终端 PID 追踪 + 后台 Agent 脱附/重附 [↓](./qwen-code-improvement-report-p2.md#item-30) | 缺失 | 中 | — | +| **P2** | [Git Diff 统计](./git-workflow-session-deep-dive.md) — 编辑后 numstat + hunks 结构化 diff（50 文件/1MB 上限） [↓](./qwen-code-improvement-report-p2.md#item-31) | 无 git-aware diff | 小 | — | +| **P2** | [文件历史快照](./git-workflow-session-deep-dive.md) — per-file SHA256 备份，按消息粒度恢复（100 个/session） [↓](./qwen-code-improvement-report-p2.md#item-32) | git-level checkpoint | 中 | — | +| **P2** | [Computer Use](./computer-use-deep-dive.md) — macOS 截图 + 鼠标/键盘 + 剪贴板，通过 MCP 桥接 [↓](./qwen-code-improvement-report-p2.md#item-28) | 缺失 | 大 | — | +| **P2** | [Deep Link](./deep-link-protocol-deep-dive.md) — `claude-cli://` 一键从浏览器/IDE 启动 Agent + 预填充 prompt [↓](./qwen-code-improvement-report-p2.md#item-33) | 缺失 | 中 | — | +| **P2** | [Team Memory](./team-memory-deep-dive.md) — 团队共享项目知识 + 29 条 gitleaks 密钥扫描 + ETag 同步 [↓](./qwen-code-improvement-report-p0-p1.md#item-10) | 缺失 | 大 | — | +| **P2** | Plan 模式 Interview — 先收集信息再制定计划，分离探索和规划阶段 [↓](./qwen-code-improvement-report-p2.md#item-34) | 无 interview 阶段 | 中 | — | +| **P2** | BriefTool — Agent 向用户发送异步消息（含附件），不中断工具执行 [↓](./qwen-code-improvement-report-p2.md#item-35) | 缺失 | 中 | — | +| **P2** | [SendMessageTool](./multi-agent-deep-dive.md) — 多代理间消息传递、shutdown 请求、plan 审批 [↓](./qwen-code-improvement-report-p2.md#item-36) | 缺失 | 中 | — | +| **P2** | FileIndex — fzf 风格模糊文件搜索 + 异步增量索引 [↓](./qwen-code-improvement-report-p2.md#item-37) | 依赖 rg/glob | 中 | — | +| **P2** | Notebook Edit — Jupyter cell 编辑 + 自动 cell ID 追踪 + 文件历史快照 [↓](./qwen-code-improvement-report-p2.md#item-38) | 缺失 | 中 | — | +| **P2** | 自定义快捷键 — multi-chord 组合键 + 跨平台适配 + `keybindings.json` 自定义 [↓](./qwen-code-improvement-report-p2.md#item-39) | 缺失 | 中 | — | +| **P2** | Session Ingress Auth — 远程会话 bearer token 认证（企业多用户环境） [↓](./qwen-code-improvement-report-p2.md#item-40) | 缺失 | 中 | — | +| **P2** | 企业代理 — CONNECT relay + CA cert 注入 + NO_PROXY 白名单（容器环境） [↓](./qwen-code-improvement-report-p2.md#item-41) | 缺失 | 大 | — | +| **P2** | ConfigTool — 模型通过工具读写设置（主题/模型/权限等），带 schema 验证 [↓](./qwen-code-improvement-report-p2.md#item-42) | 仅 /settings 命令 | 小 | — | +| **P2** | 终端主题检测 — OSC 11 查询 dark/light + COLORFGBG 环境变量回退 [↓](./qwen-code-improvement-report-p2.md#item-43) | 缺失 | 小 | — | +| **P2** | 自动后台化 Agent — 超过阈值自动转后台执行，不阻塞用户交互 [↓](./qwen-code-improvement-report-p2.md#item-44) | 需显式指定 | 小 | — | +| **P2** | Denial Tracking — 连续权限拒绝自动回退到手动确认模式，防止静默阻塞 [↓](./qwen-code-improvement-report-p2.md#item-29) | 缺失 | 小 | — | +| **P2** | [队列输入编辑](./input-queue-deep-dive.md) — 排队中的指令可通过方向键弹出到输入框重新编辑 [↓](./qwen-code-improvement-report-p2.md#item-45) | 缺失 | 小 | — | +| **P2** | 状态栏紧凑布局 — 固定高度不伸缩，最大化终端内容区域 [↓](./qwen-code-improvement-report-p2.md#item-46) | Footer 占用偏高 | 小 | — | +| **P1** | GitHub Actions CI — 自动 PR 审查/issue 分类 action [↓](./qwen-code-improvement-report-p0-p1.md#item-14) | 缺失 | 中 | — | +| **P1** | GitHub Code Review — 多代理自动 PR review + inline 评论 [↓](./qwen-code-improvement-report-p0-p1.md#item-15) | 缺失 | 大 | — | +| **P1** | HTTP Hooks — Hook 可 POST JSON 到 URL 并接收响应（不仅 shell 命令）[↓](./qwen-code-improvement-report-p0-p1.md#item-16) | 仅 shell 命令 | 小 | — | +| **P2** | Conditional Hooks — Hook `if` 字段用权限规则语法按工具/路径过滤 [↓](./qwen-code-improvement-report-p2.md#item-47) | 缺失 | 小 | — | +| **P2** | Transcript Search — 按 `/` 搜索会话记录，`n`/`N` 导航匹配项 [↓](./qwen-code-improvement-report-p2.md#item-48) | 缺失 | 小 | — | +| **P2** | Bash File Watcher — 检测 formatter/linter 修改已读文件，防止 stale-edit [↓](./qwen-code-improvement-report-p2.md#item-49) | 缺失 | 小 | — | +| **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) | 缺失 | 中 | — | +| **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) | 缺失 | 小 | — | +| **P1** | Remote Control Bridge — 从手机/浏览器驱动本地终端 session [↓](./qwen-code-improvement-report-p0-p1.md#item-20) | 缺失 | 大 | — | +| **P1** | /teleport — Web session → 终端 session 双向迁移 [↓](./qwen-code-improvement-report-p0-p1.md#item-21) | 缺失 | 大 | — | +| **P1** | GitLab CI/CD — 官方 GitLab pipeline 集成 [↓](./qwen-code-improvement-report-p0-p1.md#item-22) | 缺失 | 中 | — | +| **P2** | /effort — 设置模型 effort 级别（○ 低 / ◐ 中 / ● 高）[↓](./qwen-code-improvement-report-p2.md#item-52) | 缺失 | 小 | — | +| **P2** | Status Line 自定义 — shell 脚本在状态栏展示自定义信息 [↓](./qwen-code-improvement-report-p2.md#item-53) | 缺失 | 小 | — | +| **P2** | Fullscreen Rendering — alt-screen 无闪烁渲染 + 虚拟滚动缓冲 [↓](./qwen-code-improvement-report-p2.md#item-54) | 缺失 | 中 | — | +| **P2** | Image [Image #N] Chips — 粘贴图片后生成位置引用标记 [↓](./qwen-code-improvement-report-p2.md#item-55) | 缺失 | 小 | — | +| **P2** | --max-turns — headless 模式最大 turn 数限制 [↓](./qwen-code-improvement-report-p2.md#item-56) | 缺失 | 小 | — | +| **P2** | --max-budget-usd — headless 模式 USD 花费上限 [↓](./qwen-code-improvement-report-p2.md#item-57) | 缺失 | 小 | — | +| **P2** | Connectors — 托管式 MCP 连接（GitHub/Slack/Linear/Google Drive OAuth）[↓](./qwen-code-improvement-report-p2.md#item-58) | 缺失 | 大 | — | +| **P3** | 动态状态栏 — 模型/工具可实时更新状态文本 [↓](./qwen-code-improvement-report-p3.md#item-59) | 仅静态 Footer | 小 | — | +| **P3** | [上下文折叠](./context-compression-deep-dive.md) — History Snip（Claude Code 自身仅 scaffolding，未完整实现） [↓](./qwen-code-improvement-report-p3.md#item-60) | 缺失 | 大 | — | +| **P3** | 内存诊断 — V8 heap dump + 1.5GB 阈值触发 + leak 建议 + smaps 分析 [↓](./qwen-code-improvement-report-p3.md#item-61) | 缺失 | 中 | — | +| **P3** | Feature Gates — GrowthBook 远程特性开关 + A/B 测试 + 按事件动态采样 [↓](./qwen-code-improvement-report-p3.md#item-62) | 缺失 | 中 | — | +| **P3** | DXT/MCPB 插件包 — zip bomb 防护（512MB/文件，1GB 总量，50:1 压缩比限制） [↓](./qwen-code-improvement-report-p3.md#item-63) | 缺失 | 中 | — | +| **P3** | /security-review — 基于 git diff 的安全审查命令，聚焦漏洞检测 [↓](./qwen-code-improvement-report-p3.md#item-64) | 缺失 | 小 | — | +| **P3** | Ultraplan — 启动远程 CCR 会话，用更强模型深度规划后回传结果 [↓](./qwen-code-improvement-report-p3.md#item-65) | 缺失 | 大 | — | +| **P3** | Advisor 顾问模型 — /advisor 配置副模型审查主模型输出，多模型协作 [↓](./qwen-code-improvement-report-p3.md#item-66) | 缺失 | 中 | — | +| **P3** | Vim 完整实现 — motions + operators + textObjects + transitions 完整体系 [↓](./qwen-code-improvement-report-p3.md#item-67) | 基础 vim.ts | 中 | — | +| **P3** | 语音模式 — push-to-talk 语音输入 + 流式 STT 转录 + 可重绑快捷键 [↓](./qwen-code-improvement-report-p3.md#item-68) | 缺失 | 大 | — | +| **P3** | [插件市场](./hook-plugin-extension-deep-dive.md) — 插件发现、安装、版本管理 + 前端 UI [↓](./qwen-code-improvement-report-p3.md#item-69) | 缺失 | 大 | — | + +> 点击改进点名称可跳转到 Deep-Dive 文章；每项的详细说明（缺失后果 + 改进收益 + 建议方案）见 [§三](#三全部改进点详细说明)。 + +## 三、全部改进点详细说明 + +按优先级分文件，点击查看每项的 Claude Code 实现机制、缺失后果、改进收益和建议方案： + +| 文件 | 内容 | 项数 | +|------|------|:----:| +| [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 | +| [P3 详细说明](./qwen-code-improvement-report-p3.md) | 低优先级（Feature Gates、Vim、语音、插件市场等） | 11 | ## 四、架构差异总结 | 维度 | Claude Code | Qwen Code | 差距评估 | 进展 | |------|-------------|-----------|----------|------| -| **Mid-Turn Queue Drain** | `query.ts` 工具批次间 drain | 无 | 显著落后 | PR [#2854](https://github.com/QwenLM/qwen-code/pull/2854) open | +| **Mid-Turn Queue Drain** | `query.ts` 工具批次间 drain | 无 | 显著落后 | [PR#2854](https://github.com/QwenLM/qwen-code/pull/2854) | | 压缩 (Compression) 策略 | 4 层分层压缩 | 单一阈值压缩 | 显著落后 | — | | 子代理 (Subagent) | 支持 fork + 上下文继承 | 仅预定义类型 | 显著落后 | — | -| **智能工具并行** | Kind-based batching（默认 10 并发） | Agent 并发 / 其他顺序 | 中等差距 | PR [#2864](https://github.com/QwenLM/qwen-code/pull/2864) open | -| 投机执行 (Speculation) | 完整 overlay-fs + cow（991 行） | v0.15.0 已完整实现（563 行），默认关闭 | 小差距 | PR [#2525](https://github.com/QwenLM/qwen-code/pull/2525) merged | +| **智能工具并行** | Kind-based batching（默认 10 并发） | Agent 并发 / 其他顺序 | 中等差距 | [PR#2864](https://github.com/QwenLM/qwen-code/pull/2864) | +| 投机执行 (Speculation) | 完整 overlay-fs + cow（991 行） | v0.15.0 已完整实现（563 行），默认关闭 | 小差距 | [PR#2525](https://github.com/QwenLM/qwen-code/pull/2525) ✓ | | 启动优化 | API Preconnect + Early Input | 无 | 缺失 | — | | CLAUDE.md 条件规则 | frontmatter `paths:` + 惰加载 | 无 | 中等差距 | — | | 会话记忆 (Session Memory) | SessionMemory + memdir | 简单笔记工具 | 显著落后 | — | @@ -293,6 +139,22 @@ | 工具发现 | ToolSearchTool | 无 | 缺失 | — | | 多代理通信 | SendMessageTool | 无 | 缺失 | — | | 文件索引 | FileIndex（fzf 风格） | 依赖 rg/glob | 中等差距 | — | +| Commit Attribution | Co-Authored-By 追踪 | 无 | 缺失 | — | +| 会话分支 | /branch 对话分叉 | 无 | 缺失 | — | +| Output Styles | Learning / Explanatory 模式 | 无 | 缺失 | — | +| Fast Mode | 速度/成本分级推理 | 无 | 缺失 | — | +| 并发 Session | 多终端 PID 追踪 + 后台脱附 | 无 | 缺失 | — | +| Git Diff 统计 | 结构化 diff + 按文件统计 | 无 git-aware stats | 中等差距 | — | +| 文件历史快照 | per-file SHA256 + 按消息恢复 | checkpoint（git 级） | 小差距 | — | +| Session Ingress Auth | bearer token 远程认证 | 无 | 缺失 | — | +| Computer Use | macOS 桌面自动化 | 无 | 缺失 | — | +| Deep Link | `claude-cli://` URI scheme | 无 | 缺失 | — | +| Notebook Edit | Jupyter cell 编辑 | 无 | 缺失 | — | +| Team Memory | 组织级记忆同步 | 无 | 缺失 | — | +| 自定义快捷键 | multi-chord + keybindings.json | 无 | 缺失 | — | +| 企业代理 | CONNECT relay + CA cert 注入 | 无 | 缺失 | — | +| 终端主题 | OSC 11 dark/light 检测 | 无 | 缺失 | — | +| Denial Tracking | 权限拒绝学习 + 自动回退 | 无 | 缺失 | — | ## 五、相关 Deep-Dive 文章 @@ -314,6 +176,12 @@ | 多代理通信 | [多代理系统](./multi-agent-deep-dive.md) | | 插件/Hook 扩展 | [Hook 与插件扩展](./hook-plugin-extension-deep-dive.md) | | MCP 集成 | [MCP 集成](./mcp-integration-deep-dive.md) | +| 成本与 Fast Mode | [成本追踪与 Fast Mode](./cost-fastmode-deep-dive.md) | +| Git 工作流与会话 | [Git 工作流与会话管理](./git-workflow-session-deep-dive.md) | +| 工具动态发现 | [工具搜索与延迟加载](./tool-search-deep-dive.md) | +| Team Memory | [组织级记忆同步](./team-memory-deep-dive.md) | +| Computer Use | [桌面自动化](./computer-use-deep-dive.md) | +| Deep Link | [协议处理与终端启动](./deep-link-protocol-deep-dive.md) | | 功能矩阵 | [功能对比矩阵](./features.md) | ### Claude Code 源码文档 diff --git a/docs/comparison/team-memory-deep-dive.md b/docs/comparison/team-memory-deep-dive.md new file mode 100644 index 00000000..42222be8 --- /dev/null +++ b/docs/comparison/team-memory-deep-dive.md @@ -0,0 +1,180 @@ +# Team Memory 组织级记忆同步 Deep-Dive + +> 团队成员如何共享 AI Agent 学到的项目知识？本文基于 Claude Code（v2.1.89 源码分析）的源码分析，介绍其 Team Memory 组织级记忆同步架构：API 同步、Delta 上传、gitleaks 密钥扫描和冲突解决。Qwen Code 目前无此功能。 + +--- + +## 1. 架构总览 + +``` +用户 A 编辑 team/MEMORY.md + ↓ fs.watch（2s debounce） +本地 SHA256 哈希 → 与 serverChecksums 对比 → Delta 上传 + ↓ PUT /api/claude_code/team_memory +Anthropic Server（per-repo 存储） + ↓ GET（ETag 条件请求） +用户 B 启动新 session → Pull → 注入系统提示 +``` + +| 维度 | Team Memory | Auto Memory | +|------|-----------|------------| +| **作用域** | 组织级（同 repo 所有成员共享） | 用户私有 | +| **同步** | API pull/push（startup + fs.watch） | 无（仅本地） | +| **存储路径** | `~/.claude/projects/.../memory/team/` | `~/.claude/projects/.../memory/` | +| **认证** | First-party OAuth（必须） | 无 | +| **密钥扫描** | ✅ 29 条 gitleaks 规则 | 无 | +| **冲突处理** | 412 → refresh checksums → retry | N/A | +| **大小限制** | 250KB/entry，总数由服务端控制 | 无限制 | +| **特性门控** | `feature('TEAMMEM')` + GrowthBook `tengu_herring_clock` | `CLAUDE_CODE_DISABLE_AUTO_MEMORY` | + +--- + +## 2. API 同步协议 + +**端点**：`/api/claude_code/team_memory?repo={owner/repo}` + +| 方法 | 用途 | 说明 | +|------|------|------| +| **GET** | 拉取全量记忆 + 每 key SHA256 校验和 | ETag 条件请求（304 = 未变化） | +| **GET ?view=hashes** | 仅拉取校验和元数据 | 冲突恢复时轻量探测 | +| **PUT** | Delta 上传变更条目 | 仅上传哈希不同的 key | + +**状态码**： + +| 码 | 含义 | +|:--:|------| +| 200 | 成功 | +| 304 | 未变化（ETag 匹配，跳过 pull） | +| 404 | 新 repo，无数据 | +| 412 | ETag 不匹配（冲突） | +| 413 | 条目数超限（返回 `max_entries`） | + +> 源码: `services/teamMemorySync/types.ts` + +--- + +## 3. Delta 同步算法 + +``` +1. 读取本地 team/ 目录所有文件 +2. 计算每个文件 SHA256 哈希 +3. 与 serverChecksums Map 对比 +4. 仅上传哈希不同的 key（delta） +5. 分批: MAX_PUT_BODY_BYTES = 200KB（贪心装箱） +6. 每批独立 PUT，部分失败不影响已提交批次 +``` + +**冲突解决（412）**： + +``` +PUT → 412 (ETag mismatch) + → GET ?view=hashes（刷新 serverChecksums） + → 重新计算 delta + → 重试 PUT（新 ETag） + → 最多 2 次重试 +``` + +**状态追踪**（`SyncState`）： + +```typescript +// 源码: services/teamMemorySync/index.ts +{ + lastKnownChecksum: string | null, // ETag + serverChecksums: Map, // per-key sha256 + serverMaxEntries: number | null, // 从 413 学习 +} +``` + +--- + +## 4. 文件监视与推送 + +```typescript +// 源码: services/teamMemorySync/watcher.ts +// fs.watch 监视 team/ 目录 +// 2 秒 debounce（避免编辑中频繁推送） +// 变更触发: 重新计算 delta → PUT +``` + +--- + +## 5. Gitleaks 密钥扫描 + +**扫描时机**：**上传前**——密钥不会离开本地机器。 + +**29 条规则覆盖**（源码: `services/teamMemorySync/secretScanner.ts`）： + +| 类别 | 规则 | +|------|------| +| 云平台 | AWS Access Key、GCP API Key、Azure | +| AI 平台 | OpenAI API Key、Anthropic API Key、HuggingFace Token | +| 代码托管 | GitHub PAT（regular/fine-grained/app/refresh）、GitLab Token | +| 通信 | Slack Token、Twilio API Key、SendGrid | +| 包管理 | NPM Token、PyPI Token | +| 基础设施 | Databricks、Hashicorp Vault、Pulumi | +| 支付 | Stripe API Key、Shopify Token | +| 密钥 | RSA/DSA/EC Private Key | + +**命中行为**： +- 整个文件跳过（不上传） +- 收集到 `skippedSecrets` 数组（含规则 ID + 人类可读标签） +- 密钥值**永不**记录或显示 + +--- + +## 6. 系统提示注入 + +```typescript +// 源码: memdir/teamMemPrompts.ts +// 启用 Team Memory 时，系统提示包含: + +"You have a persistent, file-based memory system with two directories: + - private: ~/.claude/projects/.../memory/ (user-scoped) + - team: ~/.claude/projects/.../memory/team/ (org-scoped, synced) + +Memory scope: + - private: persistent per-user, unshared + - team: shared with all authenticated org members, synced on session start" +``` + +**MEMORY.md 索引**：private 和 team 各有独立的 `MEMORY.md`，均注入系统提示（200 行 / 25KB 截断）。 + +--- + +## 7. 路径安全 + +```typescript +// 源码: memdir/teamMemPaths.ts +// Symlink 安全（PSR M22186）： +// - 解析 symlink 目标 +// - 验证目标在 team/ 目录内 +// - 防止 symlink 越狱读取系统文件 +``` + +--- + +## 8. Qwen Code 对比 + +| 维度 | Claude Code | Qwen Code | +|------|------------|-----------| +| 团队记忆 | ✅ API 同步（per-repo） | ❌ | +| 密钥扫描 | ✅ 29 条 gitleaks 规则 | ❌ | +| 文件监视 | ✅ fs.watch + 2s debounce | ❌ | +| 冲突处理 | ✅ ETag + 412 重试 | ❌ | +| 记忆类型 | 4 种（user/feedback/project/reference），可选 private/team 作用域 | 仅简单笔记 | + +--- + +## 9. 关键源码文件 + +| 文件 | 职责 | +|------|------| +| `services/teamMemorySync/index.ts` | 同步编排、Delta 上传、批处理 | +| `services/teamMemorySync/types.ts` | API Schema（Zod）、状态类型 | +| `services/teamMemorySync/watcher.ts` | 文件监视 + 2s debounce 推送 | +| `services/teamMemorySync/secretScanner.ts` | 29 条 gitleaks 规则密钥扫描 | +| `memdir/teamMemPaths.ts` | 路径验证 + symlink 安全 | +| `memdir/teamMemPrompts.ts` | 系统提示构建（private + team） | +| `memdir/memdir.ts` | Feature gating + 记忆加载 | + +> **免责声明**: 以上分析基于 2026 年 Q1 源码，后续版本可能已变更。Team Memory 需 First-party OAuth 认证。 diff --git a/docs/comparison/tool-search-deep-dive.md b/docs/comparison/tool-search-deep-dive.md new file mode 100644 index 00000000..b054449e --- /dev/null +++ b/docs/comparison/tool-search-deep-dive.md @@ -0,0 +1,131 @@ +# 工具动态发现与延迟加载 Deep-Dive + +> 39+ 个工具的 schema 全部注入系统提示会浪费大量 token。本文基于 Claude Code（v2.1.89 源码分析）的源码分析，介绍其 ToolSearchTool 延迟加载机制——仅加载核心工具，其余按需搜索。Qwen Code 目前无此功能。 + +--- + +## 1. 问题与方案 + +| 方案 | 系统提示 Token | 工具可用性 | +|------|:---:|:---:| +| **全量加载** | ~15,000+（39 工具 schema） | 全部可用 | +| **延迟加载**（Claude Code） | ~5,000（~10 核心工具） | 核心始终可用，其余按需 | + +Claude Code 通过 `ToolSearchTool` 实现第二种方案——核心工具始终在系统提示中，其余工具的 schema 仅在模型调用 ToolSearch 时注入。 + +--- + +## 2. 延迟加载分类 + +```typescript +// 源码: tools/ToolSearchTool/prompt.ts#L62-L108 +// 分类逻辑: +``` + +| 类别 | 条件 | 示例 | +|------|------|------| +| **始终加载** | `alwaysLoad: true` 或特殊角色 | ToolSearch 自身、Agent（FORK_SUBAGENT 启用时）、BriefTool、SendUserFileTool | +| **延迟加载** | `shouldDefer: true` 或 MCP 工具 | WebFetch、WebSearch、NotebookEdit、CronCreate、TaskCreate 等 | +| **MCP 工具** | 始终延迟 | 所有 `mcp__*` 前缀工具 | + +--- + +## 3. 搜索模式 + +### 3.1 Select 模式（直接选择） + +``` +ToolSearch(query: "select:WebFetch,NotebookEdit") +→ 精确匹配工具名（大小写不敏感） +→ 返回匹配工具的完整 schema +→ 已加载工具也会返回（无害的 no-op） +``` + +> 源码: `tools/ToolSearchTool/ToolSearchTool.ts#L363-L405` + +### 3.2 Keyword 模式（模糊搜索） + +``` +ToolSearch(query: "notebook jupyter") +ToolSearch(query: "+slack send") ← + 前缀 = 必须匹配 +``` + +**评分算法**（源码: `ToolSearchTool.ts#L186-L302`）： + +| 匹配类型 | MCP 工具 | 普通工具 | +|----------|:--------:|:--------:| +| 工具名精确部分匹配 | 12 分 | 10 分 | +| 工具名部分匹配 | 6 分 | 5 分 | +| `searchHint` 匹配 | 4 分 | 4 分 | +| 描述匹配（词边界） | 2 分 | 2 分 | +| 全名回退 | 3 分 | 3 分 | + +**MCP 工具评分略高**——因为 MCP 工具始终延迟，搜索是唯一发现路径。 + +### 3.3 Schema + +```typescript +// 输入: +{ query: string, max_results?: number } // max_results 默认 5 + +// 输出: +{ + matches: [{ name, description, schema }], + query: string, + total_deferred_tools: number, + pending_mcp_servers?: string[] // 仍在连接中的 MCP 服务器 +} +``` + +--- + +## 4. 缓存策略 + +```typescript +// 源码: ToolSearchTool.ts#L66-L100 +// 工具描述缓存: +getToolDescriptionMemoized(toolName) + → 首次调用: 生成描述 + schema + → 后续调用: 返回缓存 + → 延迟工具集变化时: maybeInvalidateCache() 清除 + +// Schema 延迟加载: +lazySchema() → 仅在 ToolSearch 被调用时加载 schema +``` + +--- + +## 5. 系统提示中的呈现 + +当 ToolSearch 启用时，系统提示中不列出延迟工具的完整 schema，而是一段引导文本： + +``` +The following deferred tools are available via ToolSearch: +AskUserQuestion, CronCreate, CronDelete, CronList, ... +``` + +模型看到这段文本后，知道可以通过 `ToolSearch(query: "select:AskUserQuestion")` 获取完整 schema。 + +--- + +## 6. Qwen Code 对比 + +| 维度 | Claude Code | Qwen Code | +|------|------------|-----------| +| 工具加载 | 核心始终 + 其余延迟 | 全部始终加载 | +| 搜索工具 | ToolSearchTool（keyword + select） | 无 | +| MCP 工具 | 始终延迟 | 始终加载 | +| 系统提示 Token | ~5,000（核心） | ~15,000+（全部） | +| 缓存 | 描述缓存 + 变更失效 | N/A | + +--- + +## 7. 关键源码文件 + +| 文件 | 行数 | 职责 | +|------|------|------| +| `tools/ToolSearchTool/ToolSearchTool.ts` | 472 | 搜索引擎（keyword/select/评分/缓存） | +| `tools/ToolSearchTool/prompt.ts` | 122 | 延迟分类逻辑 + 系统提示文本 | +| `tools/ToolSearchTool/constants.ts` | 1 | 常量 | + +> **免责声明**: 以上分析基于 2026 年 Q1 源码，后续版本可能已变更。