Changes on 2026-09-03

1. **Understand the Goal**: The user wants a concise, insightful analysis of documentation changes for a developer tool (specifically Claude Code). The analysis should be in markdown, in Chinese, focusing on what matters to developers. There are 11 changed pages provided. 2. **Analyze the Inputs**: * `cli-reference.md`: Added `--permission-prompts` flag. Allows setting `none` to deny prompts in print mode/hostless environments. Requires v2.1.259. * `headless.md`: New section "Turn off permission prompts in unattended runs". Explains usage of `--permission-prompts none`. Explains behavior (denial instead of waiting), removal of user-facing tools (like `AskUserQuestion`), and behavior with hooks/MCP. * `hooks.md`: Clarified `PermissionRequest` hooks. The `permission_suggestions` array isn't an exact 1:1 with UI options. Removed text suggesting echoing suggestions is equivalent to UI selection (simplified/clarified). * `monitoring-usage.md`: Minor text cleanup regarding managed settings and retention sweeps. "When `managed-settings.json` itself can't be read or parsed" -> "When `managed-settings.json` itself can't be read". * `network-config.md`: Clarified watchdog behavior for stalled streams. Added context about subagents and non-interactive sessions regarding "incomplete-response notices". * `sandboxing.md`: Clarified behavior in "Auto-allow mode" and "Escape hatch". Removed mentions of auto-mode classifier fallback in specific edge cases, focusing on explicit permission flows. Added note about `permissions.blockReadsOutsideWorkingDirectories`. * `security.md`: Removed mention of auto-mode reading paths outside the working directory boundary without asking. Now implies consistent behavior (prompting) or refers to sandbox rules. This suggests a security tightening or clarification of behavior change. * `settings.md`: Updated error handling for managed settings. Added specific error reference for "Managed settings document could not be parsed". * `sub-agents.md`: Clarified subagent recovery from mid-stream cutoffs. Clarified behavior when stopping subagents manually vs. programmatically. * `api/overview.md`: Updated authentication headers. `Authorization` is now preferred/primary. `x-api-key` is legacy. Benefits list updated. * `CHANGELOG.md.md`: Huge list of changes for version 2.1.260. Includes fixes for permissions, sandboxing, managed settings, subagents, UI improvements, Fable 5.1 support, etc. Reverted a specific permission change regarding `Read()` deny rules. 3. **Synthesize Key Themes**: * **Permissions & Security**: New flag `--permission-prompts` for unattended runs. Sandbox and permission flow clarifications (tightening behavior or clarifying auto-mode vs manual-mode differences). The CHANGELOG mentions reverting a permission change and fixing path matching bugs. * **Subagents & Resilience**: Improvements in how subagents handle errors, cutoffs, and resumption. * **API & Auth**: Shift from `x-api-key` to `Authorization` header (Bearer token). * **Minor Doc/Text Updates**: Cleanup of descriptions for settings, errors, and network timeouts. 4. **Determine Impact Level**: * **High**: The introduction of `--permission-prompts none` is a significant feature for CI/CD and unattended automation. The API auth header change is structural. The permission/sandboxing clarifications might imply behavior changes developers need to be aware of (e.g., the CHANGELOG mentions reverting a specific 2.1.259 change, and docs removed auto-mode silent reads outside working directory). * *Decision*: Medium to High. The feature addition is high value for automation, but the churn in permission/sandbox docs suggests stability in how permissions work. Let's settle on **Medium/High** depending on the audience. For developers using the CLI/SDK, it's High. For casual users, it's Low. Given the prompt asks for developer focus, **High** is appropriate due to the new flag and auth changes. Actually, let's look at the CHANGELOG again. Reverting a permission change is significant. The Auth change is significant. Let's stick to **High**. 5. **Draft the Analysis (Internal Monologue/Rough Draft)**: * *Summary*: Added `--permission-prompts` flag for headless runs, updated API auth preferences, and clarified subagent and permission behaviors. * *Themes*: Automation permissions (unattended runs), API authentication shifts, Subagent error handling improvements, Sandbox/Security refinements. * *Impact*: High. New flag enables better CI/CD. Auth header change matters for API users. Changelog shows significant bug fixes. * *Action Items*: Use `--permission-prompts none` for CI. Update API clients to use `Authorization` header. Review sandbox/permission rules if using complex regex. Update to 2.1.260 for permission fixes. 6. **Refine and Translate to Chinese**: * *Summary*: 本次更新主要引入了非交互式运行的新权限控制标志，更新了 API 认证头的优先级，并优化了子代理和沙盒行为的相关文档。 * *Themes*: * **非交互式自动化**: 引入 `--permission-prompts` 标志以在无人值守运行中完全禁用权限提示，防止任务挂起。 * **API 认证变更**: 明确 `Authorization` 头为首选认证方式，`x-api-key` 降级为遗留方案。 * **权限与沙盒细化**: 文档移除了关于自动模式下“静默读取”某些路径的描述，暗示安全行为更严格或一致性提升；CHANGELOG 中显示回滚了上一个版本的特定权限规则。 * **子代理与错误处理**: 明确了子代理在响应被截断时的恢复逻辑以及手动停止后的自动恢复行为。 * *Impact*: **High**. * Reason: `--permission-prompts none` 关键解决了 CI/CD 场景下的阻塞问题。API 认证方式调整影响直接调用 API 的开发者。权限逻辑的微调涉及核心安全行为。 * *Action Items*: * 在 CI/CD 脚本中使用 `--permission-prompts none` 以避免权限等待。 * 更新 API 客户端代码，优先使用 `Authorization: Bearer <token>` 头。 * 升级至 v2.1.260 以修复路径匹配中的正则表达式 Bug 及沙盒权限问题。 7. **Final Polish**: Ensure markdown formatting is clean and concise. * *Self-Correction on Themes*: The CHANGELOG shows `Reverted the 2.1.259 change applying Read() deny rules to Bash arguments`. This is crucial because the docs also changed around permission logic. I should mention stability/fixes. * *Self-Correction on Action Items*: Keep it to max 5. 8. **Final Output Generation** (matches the thought process).

1. **理解目标**：用户希望以一名世界级程序员的身份，用中文分析文档的变更。我需要总结*发生了什么变化*以及*为何这对开发者重要*。分析需以 Markdown 格式呈现，包含四个特定部分：总体摘要、关键主题、影响级别和行动事项。背景是对 `build-with-claude/batch-processing.md` 文档的一次单独变更。 2. **分析变更**： * **文件**：`build-with-claude/batch-processing.md` * **变更**： * 从描述“哪些可以被批处理”的表格中移除了几行。 * 移除的内容： * `store` / `previous_thread_event_id`（Threads）：移除原因？也许这些功能现在*支持*批处理，或者不再相关/被废弃了。看 diff，原文称它们“不被支持”。现在它们从“不支持”列表中消失了。这暗示了它们现在可能*被支持*，或者列表仅关注剩余的关键不兼容项。 * `cache_hint` / `context_hint`：移除原因？同样，原文称它们适用于同步请求调度。现在它们消失了。 * `research_preview_2026_02: "active"`：移除原因？原文称其在批处理路径上不可用。现在消失了。 * 修改了 FAQ 部分：“我可以将 Message Batches API 与其他 API 功能一起使用吗？” * 更新了不被支持的参数列表。它从明确列出的不兼容参数中移除了 `store`、`previous_thread_event_id`、`cache_hint`、`context_hint` 和 `research_preview_2026_02`。 * 剩余的不兼容项：`stream`、`speed`、`max_tokens: 0`。 3. **解读“原因”（开发者的意义）**： * 文档之前列出了多个不兼容的参数。 * 现在它删除了其中的许多，仅留下了核心的不兼容项（`stream`、`speed`、`max_tokens: 0`）。 * *关键推断*：如果某项从“不被支持”列表中移除，通常意味着它**现在被支持了**。 * 因此，Claude 的 Message Batches API 现在可能支持： * Threads（状态管理）。 * 路由提示（`cache_hint`、`context_hint`）。 * 研究预览功能。 * 或者，文档得到了简化，因为（Threads 等的）架构已经成熟，这些功能是可用的，或者明确指出它们受限是不再必要的，但通常在 API 文档中，将某项从“限制”列表中移除是功能开启的信号。 * *对“store”的优化*：`store` 通常与自动评估或缓存有关。如果已移除，也许批处理现在支持自动存储/评估。 * *对“Threads”的优化*：批处理是无状态的（单条消息）。但在批处理上下文中支持 `previous_thread_event_id` 暗示了上下文传递或某种形式的状态回溯能力，或者批处理工具现在能更好地处理 Threads API 工作流。等等，看下旧的文本：“Threads are stateful; batch requests are not.”（Threads 是有状态的；批处理请求不是。）如果该行移除了，这表明 Message Batches API 可能已发展为处理 Threads，或者该限制被澄清/移除了。鉴于 `store` 也被移除，这感觉像是一个功能扩展更新，其中受限的功能已集成到批处理路径中。 4. **起草分析（中文）**： * **总体摘要**：文档更新了 Message Batches API 的兼容性列表。它移除了 Threads（`store`、`previous_thread_event_id`）、路由提示（`cache_hint`、`context_hint`）和研究预览功能不被支持的限制。这表明这些功能现在可用于批处理。 * **关键主题**： * **功能扩展**：Message Batches API 可能现在支持状态管理和高级路由。 * **简化/清晰化**：文档重点转移到仅剩的核心限制（流式传输、速度、token 限制）。 * **Threads 集成**：关于 Threads 不可用的限制已移除。 * **影响级别**：**Medium**（中等）。这不是破坏性变更，但它为批处理工作流显著解锁了新能力（特别是 Threads 和路由提示）。开发者现在可以构建更复杂的批处理流水线。 * **行动事项**： * 更新批处理代码以尝试使用 `store` 或 Threads 相关参数。 * 如果使用自定义路由，利用 `cache_hint` / `context_hint` 进行批处理。 * 如适用，在新批处理中测试研究预览功能。 5. **优化语言（中文）**： * *摘要*：文档更新了 Message Batches API 的功能兼容性列表，移除了关于 Threads、路由提示和研究预览功能的限制说明。这暗示这些功能现在可能已支持批处理。 * *主题*：功能兼容性扩展, 限制条件简化, Threads 集成. * *影响*：Medium. 虽然不是破坏性变更，但解锁了新的批处理能力，特别是对状态管理和路由优化的支持。 * *行动*：审查现有的批处理代码，探索在批处理中使用 `store` 参数或 Threads 功能。利用 `cache_hint`/`context_hint` 优化批处理调度。测试研究预览功能在批处理中的表现。 6. **最终润色**：确保语气专业且对开发者有帮助。 * *自我修正*：说它们*已支持*是否安全？从限制列表中移除是列出功能*现在可用*或之前完全受限的某些功能的*限制已移除*的最合逻辑的推断。我将表述为“暗示支持”或“移除限制”，这在技术上更加安全，但在功能上对开发者意味着同样的事情。 * 让我们检查删除的具体行： * `store` / `previous_thread_event_id` (Threads) * `cache_hint` / `context_hint` * `research_preview_2026_02: "active"` 这些原本在表格的“限制”部分。从那里移除强烈暗示 API 现在支持它们。 让我们构建最终输出。 **结构**： ### 1. Overall Summary ### 2. Key Themes ### 3. Impact Level ### 4. Action Items （按要求翻译成中文）。

用户希望我对文档更改进行批次分析。总共有6个页面发生了更改。让我逐个查看： 1. **interactive-mode.md (+10 / -6)** - 删除了关于 PR 状态刷新频率的详细说明（90秒/60秒）和一小时无输入后停止刷新的规则 - 增加了对 `CLAUDE_CODE_DISABLE_NONESSENTIAL_TRAFFIC` 环境变量的说明，当设置该变量时，不会检查 PR 或 MR 状态 - 更新了 GitHub PR 状态检测的说明，明确了如何根据不同的 GitHub 主机找到 token，以及缺少 token 时显示的提示信息 - 简化了 GitLab MR 状态刷新的说明 2. **model-config.md (+7 / -7)** - 修改了表格中 `CLAUDE_CODE_SUBAGENT_MODEL` 的描述链接，从 `#choose-a-model` 改为 `#run-every-subagent-on-one-model` 3. **plugins-reference.md (+18 / -0)** - 新增了 `plugin validate` 命令的文档 - 可以检查插件或市场的语法和架构错误 - 支持 `--strict` 选项（将警告视为错误） - 支持 `--json` 选项（输出 JSON 格式的验证报告） - 在交互式会话中可以使用 `/plugin validate <path>` 4. **sub-agents.md (+16 / -5)** - 更新了关于 subagent 模型选择的说明，将关于 `CLAUDE_CODE_SUBAGENT_MODEL_FORCE` 的详细说明移到了一个新的章节 "Run every subagent on one model" - 在多个地方更新了对这个功能的引用链接 - 新增了详细的章节解释如何强制所有 subagent 使用同一个模型 5. **build-with-claude/files.md (+1 / -1)** - 在 Content Credentials 的说明中增加了音频文件 6. **agents-and-tools/tool-use/code-execution-tool.md (+1 / -1)** - 在 Content Credentials 的说明中增加了音频文件，并列出了支持的音频格式 现在让我总结一下关键主题： 1. **PR/MR 状态检测的优化和简化** - 移除了复杂的刷新频率说明，增加了非必要流量控制选项 2. **Subagent 模型控制的重构** - 将强制模型设置的功能移到了专门的章节 3. **插件验证工具的增强** - 新增了验证命令，支持严格模式和 JSON 输出 4. **Content Credentials 的扩展** - 增加了对音频文件的支持 影响级别：Low-Medium。这些主要是文档改进和新功能文档，没有破坏性更改。 行动项： - 开发者可以使用新的 `CLAUDE_CODE_DISABLE_NONESSENTIAL_TRAFFIC` 来控制 PR 状态检查 - 开发者可以使用新的 `plugin validate` 命令来验证插件 - 开发者可以更好地理解如何使用 `CLAUDE_CODE_SUBAGENT_MODEL_FORCE` 来控制所有 subagent 的模型