Changes on 2026-05-18

1. **Analyze the Request:** * **Role:** World-class programmer analyzing documentation changes. * **Input:** A batch of diffs for 9 documentation pages (`cli-reference.md`, `discover-plugins.md`, `hooks.md`, `hooks-guide.md`, `mcp.md`, `plugin-marketplaces.md`, `plugins-reference.md`, `settings.md`, `sub-agents.md`). * **Output Format:** Markdown, Chinese language. * **Structure:** Overall Summary, Key Themes, Impact Level, Action Items. 2. **Analyze the Diffs (Page by Page):** * `cli-reference.md`: * Change: The diff provided is truncated (`+29 / -28`, but the table content is cut off at `claude attach <id>`). * *Correction*: Looking closely at the provided diff, it seems to be a formatting or content update to the command reference table. It starts with the table headers and updates some descriptions/examples. * *Observation*: Since the diff is truncated, I can't fully analyze the `cli-reference.md` changes. However, based on the visible part, it looks like standard documentation updates to the CLI table. I should focus on the other pages which are complete, or acknowledge the limitation if the summary needs specific details from the cut-off part. *Wait, looking at the prompt again*: The diff cuts off right after `claude attach`. I can't see the bottom. I will treat this as a "Documentation Refresh" for the CLI but focus analysis on the concrete changes in other files. * `discover-plugins.md`: * Change: Added info about "Context cost" estimate in the plugin details pane for v2.1.143+. * *Relevance*: Helps developers understand token usage before installing plugins. * `hooks.md`: * Change 1: Updated description of `stop_hook_active`. Changed "prevent Claude Code from running indefinitely" to "avoid blocking on a condition that will never resolve. Claude Code overrides the hook and ends the turn after 8 consecutive blocks." * Change 2: Updated troubleshooting link text ("Stop hooks that keep blocking" vs "infinite Stop hook loops"). * *Relevance*: Breaking change/behavior change for hooks. Stop hooks now have a hard limit (8 blocks) unless configured otherwise. * `hooks-guide.md`: * Change 1: Renamed section from "Stop hook runs forever" to "Stop hook hits the block cap". * Change 2: Explained the new behavior: "Claude Code overrides a Stop hook after it blocks 8 times in a row." * Change 3: Added info on raising the cap using `CLAUDE_CODE_STOP_HOOK_BLOCK_CAP`. * *Relevance*: Confirms the hard limit on Stop hook iterations to prevent infinite loops. * `mcp.md`: * Change 1: Clarified behavior when tools are needed from a server still connecting. Claude now waits. Explains the difference between `ToolSearch` vs `WaitForMcpServers` based on configuration. * Change 2: Clarified `alwaysLoad` behavior regarding non-blocking startup. "Other servers continue to connect in the background." * *Relevance*: Improved reliability of tool availability and startup behavior. * `plugin-marketplaces.md`: * Change 1: Added `anthropic-agent-skills` to reserved names. * Change 2: Added `displayName` field (min-version 2.1.143) for human-readable names. * *Relevance*: New feature for better plugin naming, and a new reserved name. * `plugins-reference.md`: * Change 1: Skills can now be a single `SKILL.md` at the root. * Change 2: Added `displayName` to manifest (v2.1.143+). * Change 3: Auto-detection of single-skill plugins (v2.1.142+). * Change 4: `plugin enable` now handles dependencies transitively. * Change 5: `plugin disable` fails if other plugins depend on it, provides chained command. * Change 6: `plugin details` output updated to include LSP servers. * *Relevance*: Significant quality-of-life improvements for plugin authors and users (dependencies, simpler single-skill structure, display names). * `settings.md`: * Change: Added `worktree.bgIsolation` setting (v2.1.143+) to control isolation mode for background sessions ("worktree" vs "none"). * *Relevance*: New configuration option for background behavior. * `sub-agents.md`: * Change: Updated CLI usage for launching agents. Now allows passing just the agent name (`--agent security-reviewer`) instead of the scoped name, unless there's a naming collision. * *Relevance*: Improved usability/DX for running agents. 3. **Synthesize and Structure:** * **Overall Summary**: 本次文档更新主要集中在 CLI 和插件系统的改进，引入了版本 2.1.142/2.1.143 的新功能（如 `displayName` 和依赖管理），同时也加强了对 Hook 循环的控制（限制为 8 次）以及 MCP 服务器的连接稳定性。 * **Key Themes**: * *Plugin Ecosystem Enhancements*: `displayName` support, dependency management (enable/disable), simplified single-skill structure. * *Hooks Safety & Limits*: Hard limit (8 blocks) on Stop hooks to prevent infinite loops. * *MCP Reliability*: Better handling of connecting servers during tool selection. * *Agent UX*: Easier agent invocation (no scoped name needed unless collision). * *New Configs*: `worktree.bgIsolation`. * **Impact Level**: **Medium**. * *Reasoning*: While there are breaking changes (Stop hook behavior limits), most changes are additive features or documentation clarifications. The plugin dependency changes are significant for plugin authors but smooth for users. The specific version requirements (2.1.142+) need attention. * **Action Items**: * Check Stop hooks for potential infinite loops (limit is now 8). * Update plugin manifests to use `displayName` for better UX (if targeting 2.1.143+). * Refactor single-skill plugins to use the simpler root `SKILL.md` structure (2.1.142+). * Review `worktree.bgIsolation` setting if using background sessions. * Update agent invocation scripts/commands to use shorter names if unambiguous. 4. **Drafting the Content (in Chinese):** * *Summary*: 本次更新引入了多个质量改进和新特性（主要集中在 v2.1.142+），特别是插件生态系统的增强（依赖管理、`displayName`）、Hook 安全性限制以及 MCP 连接的优化。 * *Themes*: * **插件系统增强**: 引入 `displayName` 字段，支持插件依赖的传递性启用/禁用，简化了单技能插件的目录结构。 * **Hook 行为变更**: 引入了 Stop Hook 的“阻塞上限”（默认 8 次），防止无限循环。 * **MCP 与工具可用性**: 优化了服务器连接时的等待逻辑，确保工具就绪。 * **Agent 与 CLI**: 简化了 Agent 启动命令，支持无需命名空间的短名称调用。 * **新配置项**: 新增 `worktree.bgIsolation` 以控制后台会话的隔离模式。 * *Impact*: **Medium**. * 原因：Stop hook 的行为变更可能导致现有工作流中断（需检查 8 次限制），其他主要为新功能和体验优化。 * *Action Items*: * 审查 Stop hook 代码，确保不会触发新的 8 次阻塞上限。 * 更新插件 `plugin.json` 以支持 `displayName` 和依赖管理。 * 利用新的单技能插件结构简化代码。 * 根据 MCP 连接行为调整配置。 * 测试后台会话的 `bgIsolation` 设置。 5. **Refining the Output:** Make it concise and "world-class programmer" tone. Direct and actionable. * *Refined Summary*: 这一批次更新主要集中在 Claude Code v2.1.142+ 的功能迭代，强化了插件生态的依赖管理与展示体验，同时引入了 Stop Hook 的硬性安全限制（8 次阻塞）以防止无限循环，并优化了 MCP 工具等待机制。 * *Refined Themes*: (Use the bullet points derived above). * *Refined Impact*: Medium. * *Refined Actions*: (Use the bullet points derived above). 6. **Final Polish (Self-Correction during drafting)**: * Make sure to mention the specific version numbers (2.1.142, 2.1.143) as developers care about compatibility. * Note the behavior change in Stop hooks clearly as it's the most "breaking" aspect here. * The `cli-reference.md` diff was truncated, so I will generally treat it as "minor CLI reference updates" without getting specific about the cut-off part. 7. **Final Output Generation** (Translate thoughts to final markdown response).

用户想要我分析文档变更，并用中文回复。让我仔细分析这些变更： 1. **desktop.md**: 标题从 "Use Claude Code Desktop" 改为 "Desktop application"，只是一个标题的简化/规范化。 2. **model-config.md**: 关于 `[1m]` 后缀的说明更加详细，增加了一些重要说明： - 只有当底层模型支持 1M context 时才使用该后缀 - 后缀是按变量读取的，不是按模型读取的 - 在 Bedrock、Vertex 和 Foundry 上，如果某个变量中的模型 ID 没有 `[1m]`，即使另一个变量设置了该后缀，仍使用 200K context 3. **overview.md**: 标题从 "Claude Code overview" 改为 "Overview"，同样是标题简化。 4. **settings.md**: `showThinkingSummaries` 的描述增加了说明，指出在非交互模式 (`-p`)、Agent SDK 或 IDE 扩展（如 VS Code）中该设置无效。 5. **computer-use-tool.md**: 这里有大量变更： - 修改了一些措辞 - 增加了第 6 个提示：在构造用户转次的 `content` 数组时，将指令文本放在截图图像之前 - 增加了关于 `effort` 设置的建议 - 增加了关于 macOS Retina 显示器的说明 - 增加了诊断点击问题的表格 - 增加了关于模型选择影响点击精度的提示 - 增加了关于管理截图历史以进行提示缓存的建议 我将系统地整理这些变更，重点关注技术细节和实际影响。文档更新主要涉及标题规范化、配置说明和工具使用的技术细节。这些变更对开发者使用 Claude Code 有重要指导意义。 核心改进包括模型上下文限制、思考过程控制和计算机使用工具的优化建议。开发者应仔细审视这些更新，特别是计算机使用和模型配置部分，可能需要调整当前实现策略。

用户希望我分析一份文档变更摘要，重点在于对开发者的实际影响，并使用中文回复。 **1. 分析每个页面的变更：** * **Page: `jetbrains.md`** * *变更*：在“Selection context”这一项中，增加了一个句子，说明 `Read` deny rules 会阻止匹配文件被共享。 * *含义*：当在 JetBrains IDE 中使用 Claude Code 时，如果开发者选中了文本或打开了某个标签页，它会被自动共享。现在，文档明确了如果存在针对该文件的 `Read` deny rule，则共享会被阻止。这是关于隐私/安全控制的关键澄清。 * **Page: `model-config.md`** * *变更*：将“extra usage”（额外使用量）替换为“usage credits”（使用额度），用于指代通过 1M 上下文模型进行计费的方式。还在表格中略微更新了 `CLAUDE_CODE_SUBAGENT_MODEL` 的描述，注明它覆盖 per-invocation 参数和 frontmatter 定义。 * *含义*： * **术语变更**：从“extra usage”变为“usage credits”。这可能是为了与营销/计费术语保持一致。它并不改变关于*如何*计费的技术机制，只是改变了名称。 * **Subagent 模型覆盖**：阐明了环境变量 `CLAUDE_CODE_SUBAGENT_MODEL` 强制覆盖其他配置（subagent 内部的 frontmatter 或 per-invocation 参数）。这增强了开发者在控制底层代理行为方面的能力。 * **Page: `vs-code.md`** * *变更*：增加了一个关于“Selection and open-file context”（选区和打开文件上下文）的新段落，解释了当前选区和活动文件路径会被共享。关键在于，它明确指出 `Read` deny rules（读取拒绝规则）可以防止这种共享（针对敏感文件如 `.env`）。 * *含义*：与 `jetbrains.md` 的变更类似，这明确了连接时的自动上下文共享行为。它通过允许使用现有的权限系统（`Read` deny rules）来防止敏感文件（如 `.env`）通过选区或当前标签页被意外泄露，从而增强了隐私性。 **2. 综合主题：** * **主题 1：隐私与控制（重要）**：`jetbrains.md` 和 `vs-code.md` 的更新都集中在 IDE 的自动上下文共享机制上。两者都澄清了现有的“Read deny rules”充当守门人的角色，防止敏感文件被共享，即使它们被打开或被选中。 * **主题 2：术语与配置（次要）**：`model-config.md` 更新了计费术语，并澄清了针对 subagents 的特定环境变量的行为。 **3. 确定影响级别：** * 是破坏性变更吗？不。 * 是高优先级吗？对于那些关注数据隐私/安全的用户来说，隐私澄清具有高优先级。对于普通用户来说，它是低到中等优先级。 * 术语变更属于低优先级。 * *总体评估*：**中等**。隐私更新显著，因为它们解决了使用 IDE 集成时常见的担忧（“我的 `.env` 文件是否被发送到了 AI？”）。 **4. 构思行动项：** * 检查 `Read` deny rules 配置，确保敏感文件（如 `.env`）被正确保护，特别是在使用 IDE 集成时。 * 如果使用 1M 上下文模型，需注意计费显示中可能发生的术语变更。 * 如果希望统一控制 subagent 模型，可利用 `CLAUDE_CODE_SUBAGENT_MODEL`。 **5. 起草中文回复（ Markdown 格式）：** * *摘要*：此次文档更新主要阐明了 IDE 集成中自动上下文共享的隐私控制机制，并更新了模型配置中的计费术语。 * *关键主题*： * **隐私与权限控制**：重点说明了 JetBrains 和 VS Code 扩展会自动分享选区和当前文件，但受到 `Read` deny rules（读取拒绝规则）的限制。 * **配置与计费**：统一了 1M 上下文计费术语，明确了 Subagent 模型的环境变量优先级。 * *影响级别*：中等。主要是澄清现有行为，帮助开发者更好地保护敏感数据，未引入破坏性变更。 * *行动项*： * 配置 `Read` deny rules 以保护 `.env` 等敏感文件在 IDE 集成中被误传。 * 留意账单/用量显示中“usage credits”术语的变化。 * 如需统一控制子代理模型，使用 `CLAUDE_CODE_SUBAGENT_MODEL`。 **6. 优化内容：** * 确保 `jetbrains.md` 和 `vs-code.md` 之间的联系清晰可见。 * 确保术语变更清晰明了（“extra usage” -> “usage credits”）。 * 确保语气符合“世界级程序员”的特点。 *起草过程中的自我修正*：我最初认为 `model-config.md` 的变更只是表格格式，但仔细观察后，文本从 "extra usage" 变为了 "usage credits"。这是一个值得注意的语义变化，可能是产品层面的变更。Subagent 变量的描述也变得更具描述性，说明它覆盖了 frontmatter。 让我们组装最终输出。 **结构：** 1. **Overall Summary**: 指向隐私控制/IDE 上下文共享和术语更新。 2. **Key Themes**: * IDE 上下文隐私（Read deny rules 适用于自动共享）。 * 计费术语更新。 * Subagent 配置清晰度。 3. **Impact Level**: 中等（主要针对安全/隐私）。 4. **Action Items**: * 更新权限设置。 * 留意术语变更。 * 检查 subagent 配置。 一切看起来都很可靠。继续进行翻译和格式化。

1. **Understand the Goal**: The user wants a concise analysis of a set of documentation changes across four pages (`desktop.md`, `skills.md`, `slash-commands.md`, `sub-agents.md`). The response needs to be in Chinese, formatted as markdown, and focused on what matters to developers. 2. **Analyze the Diffs**: * **`desktop.md`**: Added a limitation note. Specifically, built-in terminal-dialog commands (`/permissions`, `/config`, `/agents`, `/doctor`) are not available in the Desktop Code tab. Users need to edit settings files or use the CLI. * **`skills.md`**: Updated a comparison table regarding "Skills with `context: fork`". It now clarifies that `CLAUDE.md` is *not* loaded when the agent is `Explore` or `Plan`. Added explanatory text that these built-in agents skip `CLAUDE.md` and git status to keep context small. * **`slash-commands.md`**: Same exact changes as `skills.md`. This makes sense because skills and slash commands often interact or share similar context-loading behaviors. * **`sub-agents.md`**: * Added a note in "Built-in subagents" section: Explore and Plan skip `CLAUDE.md` and git status. * Added a whole new subsection "What loads at startup": * Explains that subagents have fresh/isolated context. * Lists what *is* loaded (System prompt, Task message, CLAUDE.md/memory, Git status, Preloaded skills). * Explicitly states Explore/Plan are the *only* ones skipping CLAUDE.md and git status. * Explains that the main conversation reads results with full context, so usually rules don't need to be in the subagent, but if they do, they need to be restated in the prompt. 3. **Synthesize the Changes (The "Why")**: * The core theme is **Context Management and Scope**. * Specifically, how `Explore` and `Plan` agents (built-in) behave differently regarding `CLAUDE.md` and git status compared to other agents or the main conversation. * The goal is performance optimization (keeping context small/fast/cheap). * There is also a UI limitation clarification for Desktop users regarding specific slash commands. 4. **Drafting the Sections**: * **Overall Summary**: Focus on clarifications regarding subagent behavior (specifically Explore/Plan) and limitations in the Desktop app. * **Key Themes**: * *Context Optimization*: Explore and Plan agents intentionally skip `CLAUDE.md` and git status. * *Desktop Limitations*: Terminal slash commands (`/config`, etc.) don't work in the Desktop Code tab. * *Subagent Lifecycle*: Detailed explanation of what data is loaded when a subagent starts. * **Impact Level**: Medium. It's not code-breaking, but it changes how developers configure agents (especially `Explore` and `Plan`) and how they debug issues (thinking rules are loaded when they aren't). It also affects Desktop workflow. * **Action Items**: * Update Skills/Subagents configuration if relying on `CLAUDE.md` for Explore/Plan. * Use CLI or direct file editing for config/permissions in Desktop. * Restate critical rules in prompts if using Explore/Plan and context is vital. 5. **Translating to Chinese (Mental Draft & Refinement)**: * *Summary*: 本次更新主要澄清了内置代理（Explore 和 Plan）的上下文加载行为，并补充了桌面版应用的限制说明。 * *Themes*: * 上下文隔离与优化：Explore 和 Plan 代理会跳过 `CLAUDE.md` 和 git status。 * 桌面版功能限制：某些终端对话框命令在桌面版不可用。 * 启动上下文详解：明确了子代理启动时加载的具体内容。 * *Impact*: Medium (中等)。主要是澄清文档，对逻辑有影响但非破坏性。 * *Actions*: * 检查使用了 Explore/Plan 的 Skill 配置，因为它们不再加载 CLAUDE.md。 * 桌面版用户需改用 CLI 或直接编辑文件来管理权限/配置。 * 确保 Explore/Plan 任务的提示词中包含必要规则。 6. **Final Polish (Formatting)**: Ensure markdown structure is clean. * *Self-Correction during drafting*: The changes in `skills.md` and `slash-commands.md` are identical. I should group them under the "Explore/Plan context behavior" theme to avoid repetition. 7. **Final Output Generation** (matching the requested format): (Proceed to generate the markdown response).

1. **Analyze the Request:** * **Role:** World-class programmer/developer tools expert. * **Task:** Analyze documentation changes as a single batch. * **Input:** Two pages of diffs (`statusline.md` and `build-with-claude/prompt-caching.md`). * **Output Format:** Markdown with specific sections: Overall Summary, Key Themes, Impact Level, Action Items. * **Language:** Chinese. 2. **Analyze the Changes:** * **Page 1: `statusline.md`** * *Change 1:* Added a paragraph explaining a specific Windows/Git Bash bug regarding backslashes (`\`) being treated as escape characters. * *Explanation:* Backslashes in file paths (e.g., `C:\Users\...`) get stripped, causing silent failures. * *Solution:* Use forward slashes (`/`) instead. * *Change 2:* Updated the troubleshooting section to include this specific backslash issue. * **Page 2: `build-with-claude/prompt-caching.md`** * *Change 1:* Added a `<Tip>` block introducing a new beta feature called "Cache diagnostics". * *Functionality:* It automatically compares requests to find prompt divergence. * *Change 2:* Added a bullet point in the troubleshooting list referencing the same "cache diagnostics" tool. 3. **Synthesize and Structure the Analysis:** * **Overall Summary:** The changes focus on improving developer troubleshooting experiences. One addresses a specific Windows pathing bug in the status line, and the other introduces a new beta tool to diagnose prompt caching issues. * **Key Themes:** * **Troubleshooting & Debugging:** Both additions make it easier to fix problems. * **Platform-Specific Nuances (Windows):** Specifically addressing Windows file path issues. * **Tooling/API Improvements:** Introduction of a diagnostics feature for caching. * **Impact Level:** Low to Medium. * *Reasoning:* These are additive changes (fixes/diagnostics) rather than breaking changes or major feature overhauls. However, the Windows path issue can cause "silent failures," which is high friction for affected developers, so resolving it is important. * **Action Items:** * For Windows users: Update status line config paths to use forward slashes. * For API users: Try the new "cache diagnostics" beta feature if debugging caching issues. 4. **Drafting the Response (in Chinese):** * *Summary:* 本次更新主要优化了故障排查体验，修复了 Windows 环境下状态栏脚本的路径解析问题，并引入了针对提示词缓存的诊断工具。 * *Key Themes:* * 修复 Windows 路径解析的隐形 Bug。 * 增强提示词缓存的调试能力（引入 Beta 诊断工具）。 * 改进开发者的错误排查流程。 * *Impact:* Medium. * *Reasoning:* Windows 路径问题会导致静默失败，影响严重但影响面相对特定；缓存诊断工具是新增功能，显著降低调试难度。虽然不是破坏性变更，但能解决开发中的实际痛点。 * *Action Items:* * Windows 用户：检查状态栏配置，将文件路径中的反斜杠替换为正斜杠。 * API 开发者：遇到缓存失效时，尝试使用新的 `cache diagnostics` (Beta) 工具定位差异。 5. **Review and Refine:** * Does the tone sound professional? Yes. * Is it concise? Yes. * Did I answer in Chinese? Yes. * Are the specific changes captured accurately? Yes (forward slashes for Windows, cache diagnostics for prompt caching). 6. **Final Output Generation.** (Proceeding to generate output based on these steps).