Changes on 2026-05-29

1. **Analyze the Request:** * **Role:** World-class programmer analyzing documentation changes. * **Task:** Analyze a specific batch of 6 documentation pages (`desktop.md`, `hooks.md`, `skills.md`, `slash-commands.md`, `statusline.md`, `CHANGELOG.md.md`). * **Output Format:** Markdown, concise, insightful, Chinese language. * **Specific Sections:** Overall Summary, Key Themes, Impact Level (with reasoning), Action Items (max 5). 2. **Analyze the Input Data (Page by Page):** * **Page: `desktop.md`** * *Change 1:* Added a link `[dynamic workflows](/en/workflows)` to the description of background tasks. * *Change 2:* Updated the "Agent teams" bullet point in the limitations section. * *Insight:* Clarifies that "Agent teams" (parallel sessions messaging each other) are CLI-only, but multi-agent work *inside* one session is possible in Desktop via "dynamic workflows". * *Key takeaway:* Desktop supports multi-agent functionality via workflows, but not parallel session orchestration. * **Page: `hooks.md`** * *Change:* Updated the table for Hook event fields. Specifically the `effort` field description. * *Insight:* The text mentions `ultra` is stored as `ultra` but reported as `xhigh` to the model, but the main visible change is the wrapping of the table text (diff shows formatting changes). Wait, looking closely at the diff provided: * *Correction:* The diff shows `| Field | ... |` formatting changed (width adjustment). The content text for `effort` mentions `ultra` is stored value. The prompt implies I should focus on semantic changes, but this looks mostly like a table reformatting or width adjustment in the markdown source, *unless* there's a hidden content change. * *Re-reading the diff:* The diff for `hooks.md` shows lines being replaced. The old line ends `... field. The object matches the [status line](/en/statusline#available-data) ...`. The new line is truncated in the diff view provided in the prompt (ends at `... | :-------...`). * *Wait, let me look at `skills.md` and `slash-commands.md` to see the pattern.* They explicitly say "Ultracode is not a distinct level and reports as `xhigh`". * *Hypothesis:* The `hooks.md` diff provided in the prompt is actually just formatting (columns). However, checking `skills.md` and `slash-commands.md` is crucial for the "Effort" theme. * **Page: `skills.md`** * *Change:* Updated the `${CLAUDE_EFFORT}` description. * *Old:* `ultra` value is stored value for ultracode. * *New:* `ultra` is not a distinct level and reports as `xhigh`. * *Insight:* A breaking change in how "Ultracode" effort level is reported to scripts/skills. It is now normalized to `xhigh`. * **Page: `slash-commands.md`** * *Change:* Same as `skills.md`. Updated `${CLAUDE_EFFORT}` description. * *New:* `ultra` is not a distinct level and reports as `xhigh`. * *Insight:* Consistent with `skills.md`. * **Page: `statusline.md`** * *Change:* Updated the JSON fields documentation sent to scripts. * *Old:* `effort.level` includes `ultra`. * *New:* (Implied from the partial diff, but let's infer from the other pages). The diff shows `effort.level` description ending with `ultra` in the old version. The new version in the diff cuts off, but based on `skills.md` and `slash-commands.md`, the change is likely removing `ultra` as a distinct reported value or standardizing it to `xhigh`. * *Refinement:* The prompt diff is cut off (`...`), but the pattern is clear. The "Effort" system is changing regarding the `ultra` label. * **Page: `CHANGELOG.md.md`** * *Version:* `2.1.157` * *Relevant changes:* * Plugins auto-loaded from `.claude/skills`. * `claude plugin init`. * `claude agents` improvements. * "Ultracode" changes? Not explicitly listed in the text provided in the diff, but the doc changes align with a new release. * Bug fixes and minor features. * *Note:* The doc changes in `skills.md` etc. regarding `ultra` correspond to `2.1.157` likely, or a specific model behavior change. 3. **Synthesize Key Themes:** * **Theme 1: Effort Level Normalization (`ultra` -> `xhigh`).** * Across `skills.md`, `slash-commands.md`, `statusline.md`, and `hooks.md`. * The system no longer reports `ultra` as a distinct value in environment variables or hooks. It reports `xhigh`. * **Theme 2: Desktop vs. CLI Feature Clarity.** * `desktop.md`: Clarifies that multi-agent *within* a session (workflows) works in Desktop, but parallel session orchestration ("Agent teams") is CLI-only. * **Theme 3: Plugin System Enhancements.** * `CHANGELOG.md.md`: Auto-loading plugins, init command. 4. **Drafting the Analysis (in Chinese):** * **Overall Summary:** This batch updates documentation primarily to reflect a change in how the `ultra` effort level is reported (now mapping to `xhigh`) and clarifies multi-agent capabilities in the Desktop app. It also introduces new plugin management features in version 2.1.157. (本次更新主要调整了 `ultra` 努力级别的报告方式（现映射为 `xhigh`），并澄清了桌面版中的多智能体能力。同时引入了版本 2.1.157 中的插件管理新功能。) * **Key Themes:** * **Effort Level Standardization:** Removed `ultra` as a distinct reporting level. It is now reported as `xhigh` in environment variables (`${CLAUDE_EFFORT}`), hooks (`effort.level`), and statusline scripts. Developers checking for "ultra" need to update their logic. * **Desktop Capabilities Clarification:** Updated `desktop.md` to distinguish between "Agent teams" (parallel sessions, CLI only) and "dynamic workflows" (multi-agent within session, available in Desktop). Added cross-linking to workflows. * **Plugin System Evolution (v2.1.157):** Introduction of automatic plugin loading from `.claude/skills` and a new `init` command, simplifying local plugin development. * **Impact Level:** * **Medium.** While mostly documentation alignment, the change in `${CLAUDE_EFFORT}` value (removing `ultra`) is a behavior change that will break conditional logic in custom Skills or Slash Commands expecting a string value of "ultra". * **Action Items:** * **Update Skill/Script Logic:** If your custom Skills or Slash Commands check for `${CLAUDE_EFFORT} == "ultra"`, update them to check for `"xhigh"` instead. * **Review Hook Scripts:** Ensure any scripts consuming `effort.level` or the `$CLAUDE_EFFORT` environment variable handle the removal of the `ultra` value. * **Explore Local Plugins:** Try the new `claude plugin init <name>` to scaffold plugins directly in `.claude/skills` without needing a marketplace. * **Check Desktop Multi-Agent Use Cases:** If using Desktop, utilize dynamic workflows for intra-session multi-agent tasks instead of looking for the "Agent teams" feature. 5. **Refining the Output:** * Translate insights into clear, professional Chinese. * Ensure the "Impact" reasoning highlights the specific breaking change regarding the `ultra` string. * Keep action items actionable. 6. **Final Polish (Self-Correction during drafting):** * *Check:* Did I miss anything in `desktop.md`? The link to workflows is helpful for navigation. * *Check:* `CHANGELOG.md` has many small bug fixes, but the "Plugin" and "Effort" things are the most "developer" facing structural changes to docs. The specific `ultra` change isn't explicitly detailed in the *visible* changelog text provided (it lists bug fixes), but the doc updates confirm it's the behavioral change. * *Formatting:* Use the requested markdown structure. 7. **Final Output Generation** (Proceeding to generate response based on these steps).

1. **Analyze the Request**: * **Role**: World-class programmer analyzing documentation changes. * **Output**: Concise, insightful analysis in markdown format. * **Focus**: What matters to developers. * **Language**: Chinese (requested in the prompt: "请用中文回复"). * **Input**: 3 pages of diffs (`mcp.md`, `plugin-marketplaces.md`, `about-claude/models/migration-guide.md`). 2. **Analyze the Diffs**: * **Page 1: `mcp.md` (MCP Server Configuration)** * *Change 1*: Updated the introduction sentence from "three different ways" to "several ways". (Minor wording). * *Change 2*: Added "Option 4: Add a remote WebSocket server". * Details: WebSocket servers allow persistent bidirectional connections (push events). * Comparison with HTTP: HTTP is for request-response, supports OAuth and `--transport` flag. WebSocket does *not* support OAuth or `--transport` flag. * Configuration: Use `.mcp.json` or `claude mcp add-json`. * JSON structure: `type: "ws"`. Supports `url`, `headers`, `headersHelper`, `timeout`, `alwaysLoad`. * Auth: Header-only (static token or `headersHelper`). * *Change 3*: Updated "Plugin MCP servers" section list of transports. Added "WebSocket" to the list of supported transports (stdio, SSE, HTTP, WebSocket). * **Page 2: `plugin-marketplaces.md` (Marketplace Configuration)** * *Change*: Modified the description of the `name` field in the `marketplace.json` schema. * Added constraint: "Each user can register only one marketplace per name: adding a second marketplace with the same name replaces the first." * Added instruction: To publish multiple plugins, list them in a *single* `marketplace.json`. This implies a one-to-one mapping between marketplace name and the JSON file for a user. * Note: The "Reserved names" list seems mostly unchanged (scrolling check), but the context implies stricter definition. * **Page 3: `about-claude/models/migration-guide.md` (Model Migration)** * *Change 1*: Moved the "Automate your migration with the Claude API skill" tip *up* to the top of the page (near the intro), moving it from the "Migrating from Claude Opus 4.7" section. * *Change 2*: Updated the example command in the moved tip to be more generic/forward-looking (e.g., `/claude-api migrate this project to claude-opus-4-8`) instead of specific to Opus 4.7. * *Change 3*: Removed the duplicate/lower tip from the Opus 4.7 section. * *Logic*: This makes the migration tip more prominent and general for *any* model migration covered on the page, rather than burying it in a specific section. 3. **Synthesize the Analysis**: * **Overall Summary**: The documentation updates introduce WebSocket support for MCP servers and clarify marketplace registration rules, while also promoting automated migration tools more prominently. * **Key Themes**: * *Protocol Expansion*: MCP now supports WebSocket for persistent connections (event pushing). * *Configuration Constraints*: stricter rules on how users register plugin marketplaces (one name = one file). * *Developer Experience (DX)*: Highlighting automated migration tools to reduce friction when upgrading models. * **Impact Level**: Medium. * *Reasoning*: WebSocket is a new feature (feature addition), marketplace naming rules are a specific constraint that could confuse existing authors if misunderstood, and the migration guide change is purely organizational (better DX). No breaking changes to existing APIs are explicitly shown, but the marketplace "one name replaces another" rule is critical data for developers. * **Action Items**: * Evaluate if WebSocket fits MCP use cases (need for push events). * Review marketplace packaging strategy (single JSON file per name). * Use the `/claude-api migrate` command for model updates. * Note limitations of WebSocket transport (no OAuth, no CLI transport flag). 4. **Drafting the Response (in Chinese)**: * *Overall Summary*: 本次文档更新引入了 WebSocket 支持以实现持久化 MCP 连接，明确了插件市场的注册规则（每个名称只能注册一个市场），并将自动化模型迁移工具的提示提升到了更显眼的位置。 * *Key Themes*: * **MCP 协议扩展**: 新增 `Option 4`，支持通过 WebSocket 配置远程 MCP 服务器，适用于需要主动推送事件的场景。 * **配置约束**: 插件市场配置更加严格，明确了 `name` 字段的唯一性规则（重复注册会覆盖旧配置）。 * **开发者体验**: 将模型迁移的自动化工具提示移至文档顶部，突出了通用性，方便开发者快速迁移到新模型。 * *Impact Level*: Medium. * *Reasoning*: 新增 WebSocket 传输方式提供了重要的双向通信能力，但存在不支持 OAuth 等**限制**。插件市场的命名规则对市场维护者有直接影响。模型迁移指南的调整属于优化，对功能无实质影响，但对操作流程有正面引导。 * *Action Items*: * 如果您的 MCP 服务器需要向 Claude **主动推送事件**，请考虑使用新的 `ws` 类型配置，并注意其不支持 OAuth 和 `claude mcp add --transport` 标志。 * 插件市场维护者应检查 `marketplace.json` 结构，确保将所有插件列在**单个文件**中，以避免因重复名称导致配置被覆盖。 * 在进行模型迁移时，优先使用文档顶部的 `/claude-api migrate` 命令来自动处理参数调整。 5. **Refining the Response**: * Ensure the "Why it matters" aspect is clear. * Keep it concise. 6. **Final Polish (Self-Correction during drafting)**: * Make sure to mention the "HTTP vs WebSocket" trade-off, as that's crucial for developers choosing the right tool. * Emphasize the "replacement" aspect of the marketplace name rule. 7. **Final Output Generation** (similar to the drafted text in step 4).

1. **Understand the Goal:** The user wants an analysis of documentation changes for two pages (`api/overview.md` and `build-with-claude/extended-thinking.md`). The response needs to be in Chinese, concise, markdown-formatted, and focused on what matters to developers. 2. **Analyze Page 1: `api/overview.md`** * *Change:* "container" $\to$ "sandbox" in two places. * "managed cloud containers" $\to$ "managed cloud sandboxes" * "container templates" $\to$ "sandbox templates" * *Context:* This refers to the Sessions API and Environments API. * *Meaning:* Terminology update. The underlying technology or function likely hasn't changed (same endpoints), but the marketing/technical name has shifted from "containers" to "sandboxes". This aligns with industry trends where "sandbox" implies a safer, isolated environment for AI agents. 3. **Analyze Page 2: `build-with-claude/extended-thinking.md`** * *Change:* Addition of a section explaining `usage.output_tokens_details.thinking_tokens`. * *Context:* Extended thinking (Claude thinking). The previous warning said billed output tokens $\neq$ visible tokens. The new content explains *how* to see the billed internal reasoning tokens specifically. * *New Feature/Info:* * New field: `usage.output_tokens_details.thinking_tokens`. * Shows raw reasoning tokens generated (not the summary). * Formula: `output_tokens` (total) - `thinking_tokens` $\approx$ non-reasoning output. * JSON example provided. * Billing: `output_tokens` is still the total for billing. `output_tokens_details` is read-only. * Streaming note: This breakdown appears in the final `message_delta` event. * Update to "Token usage tracking" best practice bullet to reference the new field. 4. **Synthesize Key Themes:** * **Terminology Precision:** "Containers" is out, "Sandboxes" is in for managed agents. * **Observability/Transparency:** Better visibility into token usage breakdown for Extended Thinking. 5. **Determine Impact Level:** * *Terminology:* Low impact. Just a name change. * *Token Usage Field:* Medium impact. Developers caring about cost optimization for Extended Thinking *need* this field to understand where the money goes. It's not breaking (no API parameter changes), but it's significant for monitoring. * *Overall:* Medium. It's a mix of documentation polish and a new feature addition for billing transparency. 6. **Draft Action Items:** * Update internal docs/comments to use "sandbox" instead of "container". * Update code consuming the API response to look for `output_tokens_details.thinking_tokens` to track Extended Thinking costs. * When streaming, look for this field in the `message_delta` event. 7. **Draft Response in Chinese (Iterative refinement):** * *Overall Summary:* 本次更新主要修正了 API 概览中的术语（将“容器”改为“沙箱”），并增强了 Extended Thinking 功能中关于 Token 计费和监控的透明度（新增 `thinking_tokens` 字段）。 * *Key Themes:* * **术语标准化**: Agent 运行环境从 "container" 更名为 "sandbox"。 * **计费透明度**: 新增字段用于区分内部推理消耗的 Token，帮助开发者更精准地监控成本。 * *Impact Level:* Medium. * *Reasoning:* 术语变更无功能影响，但新增加的 Token 详情字段为成本敏感型应用提供了重要的可观测性数据。 * *Action Items:* * 更新代码或文档中关于 Managed Agents 环境的描述，使用“沙箱”替代“容器”。 * 如果正在使用 Extended Thinking，请更新日志/监控逻辑以读取 `usage.output_tokens_details.thinking_tokens` 字段。 * 注意在流式响应中，该字段仅在最终的 `message_delta` 事件中提供。 8. **Final Polish:** Check against constraints. * Markdown format? Yes. * Concise? Yes. * Chinese? Yes. * Developer focused? Yes. *Self-Correction during drafting:* Ensure I mention that `output_tokens` is still the billing authority, as the docs emphasize that. Don't confuse developers into thinking `thinking_tokens` is a separate bill. 9. **Final Output Generation.** (Matches the logic above).