From 7f0228e5e51b3392f5b6da8c56947291322d2d04 Mon Sep 17 00:00:00 2001 From: wenshao Date: Mon, 30 Mar 2026 07:53:58 +0800 Subject: [PATCH 1/2] Add access dates to all 24 undated source attributions across 14 files MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit All "来源：[...]" annotations now include dates per project conventions: - Live docs (no publish date): "(2026-03 访问)" format - Changelogs with known dates: "(2026-03)" format - Blog posts with known dates: "(2025)" or "(2026-03)" format Files: slash-commands-deep-dive (6), hook-plugin-extension (2), model-routing (2), loop-schedule (2), qwen-code (3), codex-cli (1), claude-code (1), mcp-integration (1), sandbox-security (1), terminal-ui (1), review-command (2), benchmarks (1) Verified: grep "来源：\[" | grep -v "202[0-9]" returns 0 results Co-Authored-By: Claude Opus 4.6 (1M context) --- docs/benchmarks/overview.md | 2 +- docs/comparison/hook-plugin-extension-deep-dive.md | 4 ++-- docs/comparison/loop-schedule.md | 4 ++-- docs/comparison/mcp-integration-deep-dive.md | 2 +- docs/comparison/model-routing.md | 4 ++-- docs/comparison/review-command.md | 4 ++-- docs/comparison/sandbox-security-deep-dive.md | 2 +- docs/comparison/slash-commands-deep-dive.md | 14 +++++++------- docs/comparison/terminal-ui-deep-dive.md | 2 +- docs/tools/claude-code/06-settings.md | 2 +- docs/tools/codex-cli/02-commands.md | 2 +- docs/tools/qwen-code/02-commands.md | 2 +- docs/tools/qwen-code/05-settings.md | 2 +- docs/tools/qwen-code/06-extensions.md | 2 +- 14 files changed, 24 insertions(+), 24 deletions(-) diff --git a/docs/benchmarks/overview.md b/docs/benchmarks/overview.md index fc180382..4ce28650 100644 --- a/docs/benchmarks/overview.md +++ b/docs/benchmarks/overview.md @@ -57,7 +57,7 @@ Aider Code Editing Benchmark 是由 Aider 项目维护的代码编辑基准测 | DeepSeek V3 | ~70% | whole | ~$0.01 | | GPT-4o-mini | ~62% | whole | ~$0.005 | -*注：成绩取决于 Aider 使用的编辑格式（diff 或 whole），不同格式对不同模型的效果可能不同。数据来源：[Aider 排行榜](https://aider.chat/docs/leaderboards/)。* +*注：成绩取决于 Aider 使用的编辑格式（diff 或 whole），不同格式对不同模型的效果可能不同。数据来源：[Aider 排行榜](https://aider.chat/docs/leaderboards/)（2026-03 访问）。* ### Terminal-Bench diff --git a/docs/comparison/hook-plugin-extension-deep-dive.md b/docs/comparison/hook-plugin-extension-deep-dive.md index 6ee45ea6..34f9e62a 100644 --- a/docs/comparison/hook-plugin-extension-deep-dive.md +++ b/docs/comparison/hook-plugin-extension-deep-dive.md @@ -131,7 +131,7 @@ v1.0.10 修复了 `.github/hooks/` 在 `-p`（prompt）模式下不触发的问 ### Codex CLI：Plugins 一等公民（v0.117.0） -> 来源：[Codex CLI v0.117.0 Changelog](https://developers.openai.com/codex/changelog) +> 来源：[Codex CLI v0.117.0 Changelog](https://developers.openai.com/codex/changelog)（2026-03） v0.117.0 将 Plugins 提升为一等公民： - 启动时自动同步 product-scoped plugins @@ -141,7 +141,7 @@ v0.117.0 将 Plugins 提升为一等公民： ### Copilot CLI：Hook 模板变量（v1.0.12） -> 来源：[Copilot CLI v1.0.12 Changelog](https://github.com/github/copilot-cli/blob/main/changelog.md) +> 来源：[Copilot CLI v1.0.12 Changelog](https://github.com/github/copilot-cli/blob/main/changelog.md)（2026-03） v1.0.12 为 Plugin hooks 引入环境变量和模板变量： - 环境变量：`CLAUDE_PROJECT_DIR`、`CLAUDE_PLUGIN_DATA`（**注**：沿用 Claude Code 生态的变量命名，确保跨工具 Plugin hooks 兼容——Copilot CLI 读取 `.claude/settings.json` 和 Claude Code 插件） diff --git a/docs/comparison/loop-schedule.md b/docs/comparison/loop-schedule.md index e1219234..532528bc 100644 --- a/docs/comparison/loop-schedule.md +++ b/docs/comparison/loop-schedule.md @@ -206,7 +206,7 @@ codex cloud diff # 查看 diff ## Goose `goose schedule`（本地 cron 调度） -> 来源：[Goose CLI Commands](https://block.github.io/goose/docs/guides/goose-cli-commands/)，[GitHub Discussions #4389](https://github.com/block/goose/discussions/4389) +> 来源：[Goose CLI Commands](https://block.github.io/goose/docs/guides/goose-cli-commands/)（2026-03 访问），[GitHub Discussions #4389](https://github.com/block/goose/discussions/4389) ### 与 Claude Code `/schedule` 的对比 @@ -248,7 +248,7 @@ Goose 的调度只能执行 Recipe（YAML/JSON 定义的可复用任务模板） ## Aider `--watch-files`（文件监视 + AI 注释触发） -> 来源：[Aider Watch Docs](https://aider.chat/docs/usage/watch.html) +> 来源：[Aider Watch Docs](https://aider.chat/docs/usage/watch.html)（2026-03 访问） Aider 的 `--watch-files` 不是循环命令，而是**基于文件变更的 AI 触发机制**： diff --git a/docs/comparison/mcp-integration-deep-dive.md b/docs/comparison/mcp-integration-deep-dive.md index 8695c26b..7762d711 100644 --- a/docs/comparison/mcp-integration-deep-dive.md +++ b/docs/comparison/mcp-integration-deep-dive.md @@ -22,7 +22,7 @@ ## 一、Goose：MCP 原生架构（全工具 MCP 驱动） -> 来源：[Goose MCP 文档](https://block.github.io/goose/docs/)，`rmcp` Rust SDK +> 来源：[Goose MCP 文档](https://block.github.io/goose/docs/)（2026-03 访问），`rmcp` Rust SDK **所有工具都通过 MCP 协议实现**，没有"内置工具"概念： diff --git a/docs/comparison/model-routing.md b/docs/comparison/model-routing.md index 96c3911f..ead7eb34 100644 --- a/docs/comparison/model-routing.md +++ b/docs/comparison/model-routing.md @@ -217,7 +217,7 @@ Claude Code 的 Skill 系统有隐式模型选择： ### 配额倍率系统 -> 来源：[GitHub Copilot 官方文档](https://docs.github.com/en/copilot)，倍率因版本/计划而异。 +> 来源：[GitHub Copilot 官方文档](https://docs.github.com/en/copilot)（2026-03 访问），倍率因版本/计划而异。 | 模型 | 配额倍率 | 说明 | |------|---------|------| @@ -293,7 +293,7 @@ codex --oss --model qwen3:32b ## 八、Goose：注册表驱动 + 快速 Fallback -> 来源：[Goose 文档](https://block.github.io/goose/docs/)、开源代码 +> 来源：[Goose 文档](https://block.github.io/goose/docs/)（2026-03 访问）、开源代码 ```yaml # ~/.config/goose/config.yaml diff --git a/docs/comparison/review-command.md b/docs/comparison/review-command.md index 1fcdc7fe..0cd73a42 100644 --- a/docs/comparison/review-command.md +++ b/docs/comparison/review-command.md @@ -485,7 +485,7 @@ Qoder CLI 是唯一将代码审查和 PR 审查**分为两个独立命令**的 ### 从 prompt 到 agentic：Copilot 审查架构演进（来源：[GitHub Blog](https://github.blog/changelog/2026-03-05-copilot-code-review-now-runs-on-an-agentic-architecture/)，2026-03-05） -Copilot 代码审查从基于 prompt 的架构重构为**agentic tool-calling 架构**——Agent 主动收集仓库上下文（代码、目录结构、引用）来理解变更如何融入整体架构。升级后正面反馈增加 **8.1%**（来源：[60 Million Copilot Code Reviews](https://github.blog/ai-and-ml/github-copilot/60-million-copilot-code-reviews-and-counting/)）。 +Copilot 代码审查从基于 prompt 的架构重构为**agentic tool-calling 架构**——Agent 主动收集仓库上下文（代码、目录结构、引用）来理解变更如何融入整体架构。升级后正面反馈增加 **8.1%**（来源：[60 Million Copilot Code Reviews](https://github.blog/ai-and-ml/github-copilot/60-million-copilot-code-reviews-and-counting/)，2026-03）。 ### 学术研究：LLM 审查的可靠性边界 @@ -495,7 +495,7 @@ Copilot 代码审查从基于 prompt 的架构重构为**agentic tool-calling | [Rethinking Code Review with LLM](https://arxiv.org/html/2505.16339v1)（WirelessCar，2025） | 开发者反馈："If they're not good enough, you stop reading them...you miss the real issues because you start ignoring the feedback."——**低质量 AI 反馈反而降低审查质量** | | [CORE: Resolving Code Quality Issues](https://dl.acm.org/doi/10.1145/3643762)（ACM） | 二阶段 proposer+ranker 模式减少 **25.8%** 假阳性——与 Claude Code 的多代理验证异曲同工 | -### 行业共识：五层信任架构（来源：[Latent Space](https://www.latent.space/p/reviews-dead)） +### 行业共识：五层信任架构（来源：[Latent Space](https://www.latent.space/p/reviews-dead)，2025） 核心主张：确定性质量关卡应该是测试套件而非代码审查——将人类监督从下游代码阅读移到上游规格编写。 diff --git a/docs/comparison/sandbox-security-deep-dive.md b/docs/comparison/sandbox-security-deep-dive.md index 11be9b86..295f7a28 100644 --- a/docs/comparison/sandbox-security-deep-dive.md +++ b/docs/comparison/sandbox-security-deep-dive.md @@ -232,7 +232,7 @@ priority = 70 - **严格 macOS Seatbelt**：基于白名单的 Seatbelt 策略（~200+ 条 syscall 规则）（v0.34） - **safeFetch + IP 验证**：防止 SSRF 和内部网络访问（v0.34） - **子代理特定 TOML 策略**：每个子代理可有独立安全策略（v0.34） -- **统一 SandboxManager**：v0.35 引入统一沙箱管理器，集成 Linux 原生 bubblewrap + seccomp 隔离工具执行（150 变更含 2 安全修复）（来源：[v0.35 Release Notes](https://geminicli.com/docs/changelogs/latest/)） +- **统一 SandboxManager**：v0.35 引入统一沙箱管理器，集成 Linux 原生 bubblewrap + seccomp 隔离工具执行（150 变更含 2 安全修复）（来源：[v0.35 Release Notes](https://geminicli.com/docs/changelogs/latest/)，2026-03） ### macOS Seatbelt diff --git a/docs/comparison/slash-commands-deep-dive.md b/docs/comparison/slash-commands-deep-dive.md index 510130f7..2c83713f 100644 --- a/docs/comparison/slash-commands-deep-dive.md +++ b/docs/comparison/slash-commands-deep-dive.md @@ -78,7 +78,7 @@ gh pr edit --add-reviewer @copilot ### Codex CLI 代码审查 -> 来源：[OpenAI Developers](https://developers.openai.com/codex/cli/features) +> 来源：[OpenAI Developers](https://developers.openai.com/codex/cli/features)（2026-03 访问） ```bash # PR 评论触发审查 @@ -91,7 +91,7 @@ gh pr edit --add-reviewer @copilot ### Gemini CLI `/code-review`（官方扩展） -> 来源：[gemini-cli-extensions/code-review](https://github.com/gemini-cli-extensions/code-review) +> 来源：[gemini-cli-extensions/code-review](https://github.com/gemini-cli-extensions/code-review)（2026-03 访问） ```bash # 安装扩展（需要 Gemini CLI v0.4.0+） @@ -122,7 +122,7 @@ gemini extensions install https://github.com/gemini-cli-extensions/code-review ### Claude Code 三层压缩（源码：API `compact-2026-01-12`） -> 来源：[Claude API Compaction 文档](https://platform.claude.com/docs/en/build-with-claude/compaction) +> 来源：[Claude API Compaction 文档](https://platform.claude.com/docs/en/build-with-claude/compaction)（2026-03 访问） ```bash # 手动压缩 @@ -610,7 +610,7 @@ Wire 协议的 JSONL 格式使会话可在不同环境间迁移。 ### Goose 的 MCP 原生架构（独有） -> 来源：[Goose MCP 深度分析](https://dev.to/lymah/deep-dive-into-gooses-extension-system-and-model-context-protocol-mcp-3ehl)，Goose 已捐赠给 Linux 基金会 [Agentic AI Foundation (AAIF)](https://www.linuxfoundation.org/press/linux-foundation-announces-the-formation-of-the-agentic-ai-foundation) +> 来源：[Goose MCP 深度分析](https://dev.to/lymah/deep-dive-into-gooses-extension-system-and-model-context-protocol-mcp-3ehl)（2025），Goose 已捐赠给 Linux 基金会 [Agentic AI Foundation (AAIF)](https://www.linuxfoundation.org/press/linux-foundation-announces-the-formation-of-the-agentic-ai-foundation) 所有工具都通过 MCP 协议实现，没有"内置工具"概念： - Host → Goose（管理多个 MCP 客户端） @@ -757,7 +757,7 @@ approval_mode = "auto" ### Gemini CLI TOML 策略引擎详解 -> 来源：[Policy Engine 文档](https://geminicli.com/docs/reference/policy-engine/) +> 来源：[Policy Engine 文档](https://geminicli.com/docs/reference/policy-engine/)（2026-03 访问） **5 层优先级**（最终优先级 = `tier_base + toml_priority / 1000`）： @@ -775,7 +775,7 @@ Admin 目录强制严格所有权检查，防止权限提升。 ### Codex CLI 三平台 OS 级沙箱（源码：`codex-rs/`） -> 来源：[OpenAI 安全文档](https://developers.openai.com/codex/agent-approvals-security)、[DeepWiki 沙箱分析](https://deepwiki.com/openai/codex/5.6-sandboxing-implementation) +> 来源：[OpenAI 安全文档](https://developers.openai.com/codex/agent-approvals-security)、[DeepWiki 沙箱分析](https://deepwiki.com/openai/codex/5.6-sandboxing-implementation)（2026-03 访问） **最硬核的安全实现——OS 原生隔离，三个平台各有专用方案：** @@ -803,7 +803,7 @@ Admin 目录强制严格所有权检查，防止权限提升。 ### Goose 权限系统 -> 来源：[Goose 工具权限文档](https://block.github.io/goose/docs/guides/managing-tools/tool-permissions/) +> 来源：[Goose 工具权限文档](https://block.github.io/goose/docs/guides/managing-tools/tool-permissions/)（2026-03 访问） 三级工具权限 × 四种操作模式： diff --git a/docs/comparison/terminal-ui-deep-dive.md b/docs/comparison/terminal-ui-deep-dive.md index a2dc99db..bd1dae07 100644 --- a/docs/comparison/terminal-ui-deep-dive.md +++ b/docs/comparison/terminal-ui-deep-dive.md @@ -101,7 +101,7 @@ Rust 原生 CLI / Metal(macOS) + Vulkan(Linux/Win) GPU 渲染 | Shift+Tab | 循环切换审批模式（DEFAULT → AUTO_EDIT → PLAN → YOLO） | | Esc Esc | 触发 `/rewind`（RewindViewer 组件） | -**v0.35 新增：自定义快捷键 + Vim 增强**（来源：[v0.35 Release Notes](https://geminicli.com/docs/changelogs/latest/)） +**v0.35 新增：自定义快捷键 + Vim 增强**（来源：[v0.35 Release Notes](https://geminicli.com/docs/changelogs/latest/)，2026-03） - **自定义键绑定**：支持自定义 keybindings、字面字符绑定、扩展终端协议键 - **Vim 模式增强**：新增 `X`、`~`、`r`、`f/F/t/T` 动作 + yank/paste 支持 diff --git a/docs/tools/claude-code/06-settings.md b/docs/tools/claude-code/06-settings.md index 1716ffa8..e883b6bf 100644 --- a/docs/tools/claude-code/06-settings.md +++ b/docs/tools/claude-code/06-settings.md @@ -81,7 +81,7 @@ Claude Code 的 Hook 系统是其最独特的能力之一。与传统脚本 Hook | `CwdChanged` | 工作目录变更时 | v2.1.83 二进制确认 | | `FileChanged` | 文件变更检测时 | v2.1.83 二进制确认 | -> 来源：[官方 Hooks 文档](https://code.claude.com/docs/en/hooks)，全部 24 个事件在 v2.1.83 二进制中确认存在。 +> 来源：[官方 Hooks 文档](https://code.claude.com/docs/en/hooks)（2026-03 访问），全部 24 个事件在 v2.1.83 二进制中确认存在。 ### Hook 配置示例 diff --git a/docs/tools/codex-cli/02-commands.md b/docs/tools/codex-cli/02-commands.md index fbfebf0b..2f96a842 100644 --- a/docs/tools/codex-cli/02-commands.md +++ b/docs/tools/codex-cli/02-commands.md @@ -204,7 +204,7 @@ codex --dangerously-bypass-... → 绕过一切（仅限测试环境） ## TUI 斜杠命令（28 个，官方文档验证） -> 来源：[官方斜杠命令文档](https://developers.openai.com/codex/cli/slash-commands)，28 个命令。 +> 来源：[官方斜杠命令文档](https://developers.openai.com/codex/cli/slash-commands)（2026-03 访问），28 个命令。 > 注：Rust 编译的二进制中命令名以 enum 形式存储，无法通过 `strings` 直接提取，以官方文档为权威来源。 ### 会话控制 diff --git a/docs/tools/qwen-code/02-commands.md b/docs/tools/qwen-code/02-commands.md index 13486e56..ec350556 100644 --- a/docs/tools/qwen-code/02-commands.md +++ b/docs/tools/qwen-code/02-commands.md @@ -126,7 +126,7 @@ Qwen Code 提供 41 个内置斜杠命令，加上从 MCP prompts、bundled skil ## 其他命令类型 -> 来源：[官方文档](https://qwenlm.github.io/qwen-code-docs/zh/users/features/commands/) +> 来源：[官方文档](https://qwenlm.github.io/qwen-code-docs/zh/users/features/commands/)（2026-03 访问） 除斜杠命令外，Qwen Code 还支持 3 种命令类型： diff --git a/docs/tools/qwen-code/05-settings.md b/docs/tools/qwen-code/05-settings.md index afb4ad6b..eebc3bcd 100644 --- a/docs/tools/qwen-code/05-settings.md +++ b/docs/tools/qwen-code/05-settings.md @@ -1,6 +1,6 @@ # 5. Qwen Code 配置系统 -> 来源：[官方文档](https://qwenlm.github.io/qwen-code-docs/zh/users/configuration/settings/)，v0.3.0+ 嵌套结构格式 +> 来源：[官方文档](https://qwenlm.github.io/qwen-code-docs/zh/users/configuration/settings/)（2026-03 访问），v0.3.0+ 嵌套结构格式 ## 配置层级（7 层优先级） diff --git a/docs/tools/qwen-code/06-extensions.md b/docs/tools/qwen-code/06-extensions.md index 0af4f62c..1a62d676 100644 --- a/docs/tools/qwen-code/06-extensions.md +++ b/docs/tools/qwen-code/06-extensions.md @@ -1,6 +1,6 @@ # 6. Qwen Code 扩展系统 -> 来源：[官方文档](https://qwenlm.github.io/qwen-code-docs/zh/users/extension/introduction/) +> 来源：[官方文档](https://qwenlm.github.io/qwen-code-docs/zh/users/extension/introduction/)（2026-03 访问） ## 概述 From 44a4badd42ae40adde8539c7ee7c5f0c506ee475 Mon Sep 17 00:00:00 2001 From: wenshao Date: Wed, 1 Apr 2026 09:39:58 +0800 Subject: [PATCH 2/2] Add Claude Code Prompt Suggestions deep-dive from source code analysis (+287 lines) Document the complete Prompt Suggestions (tengu_chomp_inflection) feature based on source code analysis, covering architecture flow, suggestion prompt template, 12-rule filtering, Tab/Enter/Arrow acceptance, three-layer suppression guards, Speculation pre-execution with CoW overlay, pipeline mechanism, telemetry events, and 8-file source index. Co-Authored-By: Claude Opus 4.6 (1M context) --- docs/tools/claude-code/07-session.md | 281 +++++++++++++++++++++++++++ 1 file changed, 281 insertions(+) diff --git a/docs/tools/claude-code/07-session.md b/docs/tools/claude-code/07-session.md index 2aac121d..f0a1ab01 100644 --- a/docs/tools/claude-code/07-session.md +++ b/docs/tools/claude-code/07-session.md @@ -34,6 +34,287 @@ claude --worktree ``` Git worktree 隔离允许多个 Claude Code 实例在不同分支上并行工作，互不干扰。EnterWorktree/ExitWorktree 工具支持在会话内动态切换 worktree。 +### Prompt Suggestions（下一步提示预测） + +Claude Code 在每轮对话结束后，自动预测用户下一步可能输入的内容，以蓝紫色提示文本显示在输入框中。该功能内部代号为 **tengu_chomp_inflection**。 + +#### 架构概览 + +``` +┌─────────────────────────────────────────────────────────────────┐ +│ stopHooks.ts │ +│ query/stopHooks.ts#L139 │ +│ 每轮 assistant 回复完成后触发 │ +│ void executePromptSuggestion(stopHookContext) │ +└────────────────────┬────────────────────────────────────────────┘ + │ + ▼ +┌─────────────────────────────────────────────────────────────────┐ +│ executePromptSuggestion() │ +│ services/PromptSuggestion/promptSuggestion.ts#L184 │ +│ 仅处理 querySource === 'repl_main_thread' 的主线程请求 │ +│ │ +│ 1. tryGenerateSuggestion() — 守卫检查 + 生成 + 过滤 │ +│ 2. 写入 AppState.promptSuggestion │ +│ 3. 如果 Speculation 启用 → startSpeculation() │ +└────────────────────┬────────────────────────────────────────────┘ + │ + ┌──────┴──────┐ + ▼ ▼ +┌──────────────────┐ ┌──────────────────────────────────────────┐ +│ usePromptSuggestion│ │ startSpeculation() │ +│ hooks/ │ │ services/PromptSuggestion/speculation.ts │ +│ usePromptSuggestion│ │ 以 suggestion 为假设输入预执行 agent │ +│ .ts │ │ (仅限 Anthropic 内部用户启用) │ +│ │ └──────────────────────────────────────────┘ +│ 管理 UI 显示 │ +│ Tab/Enter 接受 │ +│ 遥测日志 │ +└──────────────────┘ +``` + +#### 工作原理 + +1. **触发时机**：每轮 assistant 回复完成后，在 stop hooks 阶段以 fire-and-forget 方式异步发起（源码: `query/stopHooks.ts#L139`） +2. **生成方式**：调用 `runForkedAgent()` 复用主对话的缓存参数（`cacheSafeParams`），将专用 prompt 作为 user message 追加到对话历史，请求模型预测用户下一条消息（源码: `services/PromptSuggestion/promptSuggestion.ts#L294-352`） +3. **独立请求**：suggestion 请求标记为 `querySource: "prompt_suggestion"`、`forkLabel: "prompt_suggestion"`，不写入对话 transcript，也不写入缓存（`skipTranscript: true, skipCacheWrite: true`） +4. **禁止工具**：suggestion 请求中所有工具调用均通过 `canUseTool` 回调拒绝（`behavior: "deny"`），模型只能返回纯文本 +5. **缓存复用**：刻意不覆盖任何 API 参数（不设 `effortValue`、`maxOutputTokens` 等），以确保命中主对话的 prompt cache。历史教训：PR #18143 尝试设置 `effort:'low'` 导致 cache 命中率从 92.7% 暴跌至 61%（源码注释: `promptSuggestion.ts#L308-318`） + +#### 专用 Prompt + +suggestion 生成使用常量 `SUGGESTION_PROMPT`（源码: `services/PromptSuggestion/promptSuggestion.ts#L258-287`）： + +``` +[SUGGESTION MODE: Suggest what the user might naturally type next into Claude Code.] + +FIRST: Look at the user's recent messages and original request. + +Your job is to predict what THEY would type - not what you think they should do. + +THE TEST: Would they think "I was just about to type that"? + +EXAMPLES: +User asked "fix the bug and run tests", bug is fixed → "run the tests" +After code written → "try it out" +Claude offers options → suggest the one the user would likely pick, based on conversation +Claude asks to continue → "yes" or "go ahead" +Task complete, obvious follow-up → "commit this" or "push it" +After error or misunderstanding → silence (let them assess/correct) + +Be specific: "run the tests" beats "continue". + +NEVER SUGGEST: +- Evaluative ("looks good", "thanks") +- Questions ("what about...?") +- Claude-voice ("Let me...", "I'll...", "Here's...") +- New ideas they didn't ask about +- Multiple sentences + +Stay silent if the next step isn't obvious from what the user said. + +Format: 2-12 words, match the user's style. Or nothing. + +Reply with ONLY the suggestion, no quotes or explanation. +``` + +Prompt 通过 `PromptVariant` 类型索引（源码: `promptSuggestion.ts#L31-35`），当前仅有 `'user_intent'` 和 `'stated_intent'` 两个变体，均映射到同一 prompt 模板。 + +#### 过滤机制 + +生成的 suggestion 经过 12 条过滤规则严格筛选（源码: `services/PromptSuggestion/promptSuggestion.ts#L354-456`，函数 `shouldFilterSuggestion`），不满足条件的被静默丢弃： + +| 过滤规则 | 说明 | 匹配示例 | +|----------|------|----------| +| `done` | 内容恰好为 "done" | `done` | +| `meta_text` | 模型输出元描述而非真实预测 | "nothing to suggest"、"silence"、"nothing found" | +| `meta_wrapped` | 被括号包裹的元推理 | `(silence — ...)`、`[no suggestion]` | +| `error_message` | API 错误信息泄漏 | "api error: ..."、"prompt is too long"、"image was too large" | +| `prefixed_label` | 带 `word: ` 标签前缀 | "Next step: run tests" | +| `too_few_words` | 少于 2 个单词（允许斜杠命令和特定单词） | 单个普通单词（非 yes/ok/push/commit 等） | +| `too_many_words` | 超过 12 个单词 | 过长的句子 | +| `too_long` | ≥100 个字符 | — | +| `multiple_sentences` | 包含多个句子（`/[.!?]\s+[A-Z]/`） | "Do this. Then that." | +| `has_formatting` | 包含换行符或 Markdown 格式 | 含 `\n`、`*`、`**` | +| `evaluative` | 评价性/感谢语句 | "looks good"、"thanks"、"perfect"、"awesome" | +| `claude_voice` | 模型自身语气开头 | "Let me..."、"I'll..."、"Here's..."、"You should..." | + +**允许的单词白名单**（即使只有 1 个单词也不过滤）： + +| 类别 | 单词 | +|------|------| +| 肯定词 | yes, yeah, yep, yea, yup, sure, ok, okay | +| 动作词 | push, commit, deploy, stop, continue, check, exit, quit | +| 否定词 | no | + +#### 交互方式 + +| 操作 | 效果 | 遥测 `acceptMethod` | +|------|------|---------------------| +| **Tab** | 接受 suggestion 填入输入框（可继续编辑后再提交） | `tab` | +| **Enter**（输入框为空时） | 接受 suggestion 并直接提交 | `enter` | +| **→**（右箭头） | 接受 suggestion 填入输入框 | — | +| 开始输入其他内容 | suggestion 自动消失，Speculation 被中止 | — | +| 忽略（直接输入新内容提交） | suggestion 在下一轮对话后被新预测替换 | `ignored` | + +接受判定逻辑（源码: `hooks/usePromptSuggestion.ts#L116-117`）： +- Tab 按下：`acceptedAt > shownAt` +- 或：用户最终提交内容 === suggestion 文本（空 Enter 场景） + +#### 状态数据结构 + +```typescript +// 源码: state/AppStateStore.ts#L385-391 +promptSuggestion: { + text: string | null // suggestion 文本内容 + promptId: 'user_intent' | 'stated_intent' | null // prompt 变体标识 + shownAt: number // 首次渲染时间戳（用于计算 timeToAcceptMs） + acceptedAt: number // Tab 接受时间戳 + generationRequestId: string | null // 关联的 API 请求 ID（用于 RL 数据集关联） +} +``` + +#### 抑制条件 + +suggestion 生成分为两层守卫——**初始化守卫**和**运行时守卫**： + +**初始化守卫**（源码: `promptSuggestion.ts#L37-94`，函数 `shouldEnablePromptSuggestion`）： + +| 检查顺序 | 条件 | 结果 | +|----------|------|------| +| 1 | 环境变量 `CLAUDE_CODE_ENABLE_PROMPT_SUGGESTION` 为 falsy | 禁用 | +| 2 | 环境变量 `CLAUDE_CODE_ENABLE_PROMPT_SUGGESTION` 为 truthy | 启用 | +| 3 | GrowthBook flag `tengu_chomp_inflection` 为 false | 禁用 | +| 4 | 非交互模式（`-p`、管道输入、SDK） | 禁用 | +| 5 | Swarm teammate（非 leader） | 禁用 | +| 6 | `settings.promptSuggestionEnabled !== false` | 按设置值 | + +**运行时守卫**（源码: `promptSuggestion.ts#L107-119`，函数 `getSuggestionSuppressReason`）： + +| 条件 | 抑制原因 | +|------|----------| +| `promptSuggestionEnabled === false` | `disabled` | +| 存在待审批的 Worker/Sandbox 权限请求 | `pending_permission` | +| MCP elicitation 队列非空 | `elicitation_active` | +| Plan mode 激活 | `plan_mode` | +| 外部用户且速率限制触发 | `rate_limit` | + +**生成前守卫**（源码: `promptSuggestion.ts#L125-182`，函数 `tryGenerateSuggestion`）： + +| 条件 | 抑制原因 | +|------|----------| +| AbortController 已中止 | `aborted` | +| assistant 回复不足 2 轮 | `early_conversation` | +| 上一条回复是 API 错误 | `last_response_error` | +| 上一条回复未缓存 token 数 > 10,000 | `cache_cold` | + +#### 配置方式 + +| 方式 | 说明 | +|------|------| +| `/config` → "Prompt suggestions" | 交互式配置菜单中切换开关 | +| `settings.json` 中设置 `"promptSuggestionEnabled": false` | 持久化关闭 | +| 环境变量 `CLAUDE_CODE_ENABLE_PROMPT_SUGGESTION=0` | 强制关闭（优先级最高） | +| 环境变量 `CLAUDE_CODE_ENABLE_PROMPT_SUGGESTION=1` | 强制开启（优先级最高） | +| GrowthBook feature flag `tengu_chomp_inflection` | 服务端灰度发布控制 | + +#### UI 样式 + +suggestion 文本使用主题中的 `suggestion` 颜色渲染： + +| 主题 | 颜色 | +|------|------| +| Light | `rgb(87, 105, 247)`（蓝紫色） | +| Dark | `rgb(177, 185, 249)`（浅蓝紫色） | +| ANSI Light | `ansi:blue` | +| ANSI Dark | `ansi:blueBright` | + +#### 遥测事件 + +**初始化事件** `tengu_prompt_suggestion_init`（源码: `promptSuggestion.ts#L41-92`）： + +| 字段 | 说明 | +|------|------| +| `enabled` | 是否启用 | +| `source` | 决策来源：`env` / `growthbook` / `non_interactive` / `swarm_teammate` / `setting` | + +**结果事件** `tengu_prompt_suggestion`（源码: `hooks/usePromptSuggestion.ts#L120-157`、`promptSuggestion.ts#L462-523`）： + +| 字段 | 说明 | +|------|------| +| `source` | `cli`（TUI）或 `sdk`（API 消费方） | +| `outcome` | `accepted` / `ignored` / `suppressed` | +| `prompt_id` | `user_intent` / `stated_intent` | +| `reason` | 抑制原因（仅 suppressed 时） | +| `acceptMethod` | `tab` / `enter`（仅 CLI 且 accepted 时） | +| `timeToAcceptMs` | 从显示到接受的毫秒数 | +| `timeToIgnoreMs` | 从显示到忽略的毫秒数 | +| `timeToFirstKeystrokeMs` | 从显示到首次按键的毫秒数 | +| `wasFocusedWhenShown` | suggestion 出现时终端是否有焦点 | +| `similarity` | `finalInput.length / suggestion.length`（相似度） | + +> Anthropic 内部用户（`USER_TYPE === 'ant'`）额外记录 `suggestion` 和 `userInput` 原文，用于 RL 数据集训练。 + +#### Speculation（推测执行） + +Prompt Suggestions 是更深层 **Speculation** 系统的触发器。当 suggestion 生成后，系统立即使用该 suggestion 作为假设的用户输入，预执行一轮 agent 响应。 + +**核心参数**（源码: `services/PromptSuggestion/speculation.ts#L58-70`）： + +```typescript +const MAX_SPECULATION_TURNS = 20 // 最大推测轮数 +const MAX_SPECULATION_MESSAGES = 100 // 最大消息数 + +// 允许在推测中执行的工具 +const WRITE_TOOLS = new Set(['Edit', 'Write', 'NotebookEdit']) +const SAFE_READ_ONLY_TOOLS = new Set([ + 'Read', 'Glob', 'Grep', 'ToolSearch', 'LSP', 'TaskGet', 'TaskList' +]) +``` + +**文件隔离机制**（Copy-on-Write Overlay）： +- 推测执行在独立目录中进行：`$CLAUDE_TEMP_DIR/speculation/{pid}/{id}/` +- 写操作使用 Copy-on-Write：首次写入时将原文件复制到 overlay 目录，后续读写均重定向到 overlay +- CWD 外的写操作被拒绝 +- 接受时：overlay 文件复制回主目录；中止时：overlay 直接删除 + +**边界检测**（`CompletionBoundary` 类型，源码: `state/AppStateStore.ts#L41-50`）： + +| 边界类型 | 触发条件 | 行为 | +|----------|----------|------| +| `complete` | agent 自然完成 | 记录 outputTokens | +| `bash` | 非只读 Bash 命令 | 中止推测 | +| `edit` | 文件编辑但权限不足 | 中止推测 | +| `denied_tool` | 不在允许列表中的工具 | 中止推测 | + +**Pipeline 机制**：推测执行完成后，如果用户尚未做出响应，会立即生成下一轮 suggestion（`generatePipelinedSuggestion`，源码: `speculation.ts#L345-400`）。当用户接受当前 suggestion 时，pipelined suggestion 被提升为新的 suggestion 显示，形成连续的预测-预执行链。 + +**启用条件**（源码: `speculation.ts#L337-343`）： + +```typescript +export function isSpeculationEnabled(): boolean { + const enabled = + process.env.USER_TYPE === 'ant' && + (getGlobalConfig().speculationEnabled ?? true) + return enabled +} +``` + +> **注意**：Speculation 仅对 Anthropic 内部用户启用（`USER_TYPE === 'ant'`），外部用户仅使用 Prompt Suggestions 文本预测功能。 + +#### 源码文件索引 + +| 文件 | 职责 | +|------|------| +| `services/PromptSuggestion/promptSuggestion.ts` | 核心服务：启用检查、生成、过滤、遥测（524 行） | +| `services/PromptSuggestion/speculation.ts` | 推测执行：overlay 隔离、边界检测、pipeline（992 行） | +| `hooks/usePromptSuggestion.ts` | React Hook：UI 状态管理、接受/显示/遥测（178 行） | +| `components/PromptInput/PromptInput.tsx` | 输入框组件：集成 suggestion 显示与 Enter 接受 | +| `components/PromptInput/useTypeahead.tsx` | Tab/→ 键接受与 ghost text 渲染 | +| `state/AppStateStore.ts#L385-393` | 状态定义：`promptSuggestion` + `speculation` + `speculationSessionTimeSavedMs` | +| `query/stopHooks.ts#L139` | 入口：在 stop hooks 中 fire-and-forget 调用 | +| `components/Settings/Config.tsx` | `/config` 菜单中的开关切换 | + ## 内存系统 Claude Code 的记忆系统通过 CLAUDE.md 文件跨会话保存项目知识和用户偏好：