准入限制与恢复¶

如何添加一个由 REA 所有的准入上限、预算或截止时间，以及在触及这些限制时调用方该怎么做。这是一条设计规则，而不是一份清单。应成为设置的各项上限被跟踪在 #6176 中。限制错误命名的诚实性问题见 #5910。

先定义默认值，再在运维人员需要更多余量时提供设置项¶

将数字放入带单位的命名常量中。不要将其作为魔法数字留在调用点。

当工作负载可能需要更多空间时，添加一个设置项，其未设置时的值即为该常量。src/config/ 下的一个模块负责默认值、任何下限、最大值、schema、解析器和恢复文本。将该 schema 注册到 environment.ts 中的 environmentSchema 上。parseConfig 会调用 parseEnvironment。Doctor 通过 nativeAnalysisConfigurationError 使用同一个解析器，因此启动和 rea doctor 接受相同的值。将名称加入 SELECTED_REGISTRATION_SETTINGS，以便 rea setup 将其复制到客户端注册中。未设置时保持当前行为。无效值属于 ConfigurationError，并表现为 configuration_invalid。不要回退到默认值。

REA_REGEX_MATCHING_DEADLINE_MS（#6267）是参考实现。默认 5000 ms，下限 1 ms，最大值 2147483647 ms，因为 Node 会将更长的 setTimeout 延迟调度为 1 ms。Setup 命令会复制该设置。当命中限制时，提示内容为：

有效的 REA_REGEX_MATCHING_DEADLINE_MS 值为 5000 ms（来源 default；默认值 5000 ms，下限 1 ms，最大值 2147483647 ms）。请在启动 REA 的环境中，将 REA_REGEX_MATCHING_DEADLINE_MS 设置为 1 到 2147483647 之间的正整数十进制整数，然后重启 REA。工作进程的老年代堆不会提高此截止时间。

REA_MCP_MAX_RESPONSE_BYTES 是字节预算的形态：一个十进制安全整数，下限为 10 MiB（MINIMUM_RESPONSE_BYTES），使用相同的共享 schema，并且没有静默回退。该值变更需要重启 REA，并需要匹配的客户端接收缓冲区。它不会提高 REA 的保留字符串限制或 Node 的字符串上限。setup 允许列表不会复制此设置。新的余量设置应遵循 regex 截止时间的做法。

每次调用的预算不是环境设置。JavaScript max_heap_mb（CLI --max-heap-mb）是一个从 128 到 16384 MiB 的整数，默认值为 1024。它在下一次分析开始时生效（分析会启动新的工作进程），且不需要重启 REA。它不会提高父级结果预算、传输上限或固定的解析器限制。

宿主内存和 NODE_OPTIONS 不会提高 REA 的准入限制，除非该限制的恢复文本明确说明可以。JavaScript 父级结果预算就是一个会提高的例外：其恢复文本要求，在启动 REA 的进程上设置 NODE_OPTIONS（例如 --max-old-space-size=<MiB>），然后重启该进程。max_heap_mb 不会提高它。

如实说明固定上限¶

如果上限必须保持固定，请在失败信息中如实说明。指出该限制名称和有效值，说明此版本没有运行时覆盖项，并指出不会提高该限制的设置。不要凭空发明一个设置项。

JSON 值在 jsonValue.ts 中受 MAX_JSON_DEPTH（1000）限制：“JSON 值超过最大嵌套深度 1000。此版本没有运行时覆盖项。”

恢复文本¶

调用方看到的字符串包括：

• 限制或设置项名称
• 有效值和单位
• 来源（default 或 setting）
• 默认值、最大值和下限（如果该设置项有下限）
• 下一步操作，包括在哪里设置（“启动 REA 的环境中”）
• 是否需要重启
• 该变更不会提高哪些限制

无效的设置永远不会走这条路径。它们属于 configuration_invalid。Doctor 报告 runtime-configuration:<setting>，并说明应在 shell 或 MCP 注册中修正它，然后重新运行。

Agent 的做法¶

遵循 remediation.action。仅当该文本建议更改请求字段或 REA_* 设置时，才进行更改。仅当文本说明该值是在启动时读取时，才重启。某个控件不会提高该限制的表述，并不是要求更改它。

• MCP 连接断开：仅在可以安全重试或已知尚未开始的情况下，重试一次该调用。如果它可能已经更改了目标，或再次失败，请告知用户并要求其重启 MCP 客户端。不要从 rea doctor 开始（#6353）。
• REA 无法启动其连接：重试一次。如果再次失败，请告知用户并要求其重启 MCP 客户端，然后运行 rea doctor。不要重试返回相同且未改变结果的启动：请告知用户 REA 无法启动，让用户重启 MCP 客户端，然后运行 rea doctor。
• 意外的进程命令失败：不要重复该命令。告知用户检查输入文件，然后运行 rea doctor。
• cleanup_incomplete：该操作不可重试。请重试 details.resources 中命名的那个确切清理所有者，并等待其确认释放后，再在这些资源上接受新工作（#6357）。
• resource_constraint（容量相关），当 retryable 为 true 时：等待当前准入过程完成，然后在报告的限制内重试。不要重启 REA 来释放槽位。
• configuration_invalid：在启动 REA 的环境中修正指定的设置，然后再次启动 REA。运行 rea doctor 进行 runtime-configuration: 检查。当该设置位于注册允许列表时，为该客户端重新运行 rea setup，然后重新连接，以便新进程看到它。
• invalid_request：根据当前 schema 或 CLI 帮助修正所报告的字段。不要重复未更改的调用。

环境设置和仍运行先前注册的客户端需要重启。这不是瞬时 MCP 断连、容量等待或保留清理时的第一步。

测试¶

通过 parseEnvironment 和 parseConfig 锁定未设置的默认值、一个可接受的覆盖、被拒绝的下限、最大值、语法以及恢复语句。 regexMatchingDeadline.test.ts 是范式。构造失败场景：对无效值断言 configuration_invalid，对命中断言恢复措辞。