docs: api §7 补 LLM_NETWORK_ERROR 行（对齐异常树错误码）

2026-08-09 13:51:21 +08:00
parent aa9c63df73
commit 857bc789ed
2 changed files with 2 additions and 0 deletions
@@ -55,3 +55,4 @@
 | 2026-08-09 11:45 | Agent 实现 | LLM 错误码对齐 Task1：异常树 error_code 类属性（LLMError 基类 None + four 子类 four 码，对齐 api-design §7），沿用现有中文 docstring 未改动。TDD RED（AttributeError: type object 'LLMError' has no attribute 'error_code'）→ GREEN（聚焦 4 passed，exceptions.py 100%）；聚焦单文件运行触发全库 fail-under=99 coverage exit 1 为基线行为（总覆盖 9.95%），与本次改动无关；加入 _AI_USAGE_LOG.md 提交 | src/genesis/inference/exceptions.py, tests/test_inference_errors.py, _AI_USAGE_LOG.md | deepseek-v4-flash-free |
 | 2026-08-09 13:42 | Agent 实现 | LLM 错误码对齐 Task2：ChatResult/StructuredResult 增加 error_code 字段（默认 None 向后兼容）。TDD RED（AttributeError: 'ChatResult' object has no attribute 'error_code'）→ GREEN（聚焦 8 passed，types.py 100%）；pytest 全量 123 passed 覆盖 100.00%（799 stmts/188 br），fail_under=99 达标；提交见 git log | src/genesis/inference/types.py, tests/test_inference_types.py, _AI_USAGE_LOG.md | deepseek-v4-flash-free |
 | 2026-08-09 14:02 | Agent 实现 | LLM 错误码对齐 Task3：engine 失败/parse_error 路径透传 error_code（与 error 同源取最后一次异常）。chat() 循环记 last_error_code=exc.error_code，失败返回 error_code=last_error_code；chat_structured() 三路径：JSONDecodeError 分支置 last_error_code="LLM_PARSE_ERROR"（解析耗尽→parse_error）、LLMError 分支 early return 带 error_code=exc.error_code、循环后 parse_error 用 last_error_code。TDD RED（5 failed，error_code=None）→ GREEN（聚焦 22 passed）；pytest 全量 128 passed 覆盖 100.00%（803 stmts/188 br），fail_under=99 达标；提交见 git log | src/genesis/inference/engine.py, tests/test_inference_engine.py, _AI_USAGE_LOG.md | deepseek-v4-flash-free |
+| 2026-08-09 13:51 | Agent 实现 | LLM 错误码对齐 Task4：api-design §7 补 LLM_NETWORK_ERROR 行（对齐异常树 error_code）。在 docs/api-design.md §7 错误码表 LLM_TIMEOUT 行后插入新行 `| LLM_NETWORK_ERROR | 502 | 网络失败/5xx 重试耗尽 | retry / skip / abort | exceptions.LLMNetworkError |`，保留 LLM_NOT_CONFIGURED/LLM_PARSE_ERROR 与 INTERNAL_ERROR 兜底行不动；纯文档改动，全量回归 128 passed 覆盖 100.00%（803 stmts/188 br），fail_under=99 达标 | docs/api-design.md, _AI_USAGE_LOG.md | deepseek-v4-flash-free |
@@ -309,6 +309,7 @@ docker-compose.yml（扩展）:
 | `FILE_TOO_LARGE` | 400 | 超过 100MB 限制 | 压缩/分割 | — |
 | `STATE_TRANSITION_INVALID` | 409 | 非法状态转移（如 uploading 直接 generate）| 提示正确流程 | — |
 | `LLM_TIMEOUT` | 502 | LLM 调用超时 | retry / skip / abort | exceptions.LLMTimeoutError |
+| `LLM_NETWORK_ERROR` | 502 | 网络失败/5xx 重试耗尽 | retry / skip / abort | exceptions.LLMNetworkError |
 | `LLM_NOT_CONFIGURED` | 503 | LLM Key 未配置 | 配置 Key | exceptions.LLMNotConfiguredError |
 | `LLM_PARSE_ERROR` | 502 | 结构化输出解析失败 | retry | exceptions.LLMResponseError |
 | `EMBEDDING_FAILED` | 503 | Embedding 服务故障（降级为 BM25）| 继续（降级提示）| — |