docs(designs): apply Codex review fixes to Spec-1/2/3

2026-07-11 07:54:48 -04:00
parent a5666b4f16
commit ef402c46a2
3 changed files with 48 additions and 7 deletions
@@ -33,19 +33,20 @@
 |------|-----|------|
 | 重试次数 | 2 | 第 3 次失败才整题终止（stop_reason=error 不变） |
 | 退避 | 20s / 40s | 用户指定 |
-| 异常范围 | 全部 Exception | 这一层防的是穿透 GovernedLLMClient 内部重试栈的异常（SSL 等），统一兜底不分型 |
+| 可重试异常 | 显式类型元组：`ssl.SSLError`、`TimeoutError`、`ConnectionError`、`OSError`、openai SDK 传输类异常（`APIConnectionError`/`APITimeoutError`） | 遵循 CLAUDE.md P5（不做全 Exception 兜底）；`asyncio.CancelledError` 绝不吞；其余未知异常 fail-fast 整题终止（现状行为） |
 | 上下文 | 原样保留 | messages 不回滚，重试即重发 |
-| 遥测 | 中间失败记入 error 字段 | 保持调用链可追溯 |
+| 遥测 | 失败尝试的 error 记录由 `GovernedLLMClient` 内部负责（已有）；AgentLoop 侧只以 loguru 记录步级重试事件（不注入 TelemetryRecorder） | AgentLoop 无遥测端口，不越层补写 |

 ### B 摘要附带实体原文

-`summarize_node` 输出末尾由**确定性代码**（非 LLM）追加节点 card 的字段原文：
+在 **dispatcher 侧**（`SearchToolDispatcher._handle_view_node`）由确定性代码（非 LLM）在摘要结果末尾追加节点 card 的字段原文：

 ```
 [实体] <entities + visible_entities 原文>
 [画面文字] <visible_text 原文>
 ```

+- **调用链改动**（Codex 审查修正）：`summarize_node` 只收 `raw_text: str`、无结构化 card 访问，且 `_node_full_text` 递归收值不保留字段名——因此在 `TreeEnvironment` 新增结构化字段提取方法（如 `node_entity_fields(node_id) -> dict[str, str]`），dispatcher 调用它并把区块拼接到 summarize_node 返回值之后；summarize_node 本体不改
 - 摘要后追加 → LLM 无法吞掉；字段为空则不加对应区块
 - 对 anchor / 非 anchor 两种模式一致生效