5.2 KiB
5.2 KiB
phase, plan, subsystem, tags, requires, provides, affects, tech-stack, key-files, key-decisions, patterns-established, requirements-completed, duration, completed
| phase | plan | subsystem | tags | requires | provides | affects | tech-stack | key-files | key-decisions | patterns-established | requirements-completed | duration | completed | ||||||||||||||||||||||||||||||||||||||||
|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|
| 14-robustness-cost | 02 | semantic-segmentation |
|
|
|
|
|
|
|
|
|
4min | 2026-03-23T14:38:45Z |
Phase 14 Plan 02: 增强解析失败错误处理和日志
实现 LLM 响应解析失败的类型区分策略:JSON 解析错误重试 1 次,Pydantic 验证错误直接降级,所有失败记录详细日志
Performance
- Duration: 4 min
- Started: 2026-03-23T14:35:06Z
- Completed: 2026-03-23T14:38:45Z
- Tasks: 1 (TDD: RED → GREEN)
- Files modified: 2
Accomplishments
- 实现 JSONDecodeError/ValueError 重试逻辑(可恢复错误,重试 1 次)
- 实现 ValidationError 直接降级(不可恢复错误,数据结构问题)
- 增强日志记录:解析失败时记录 LLM 输出片段(前 500 字符)
- 修复
_is_recoverable_error()方法,确保 ValidationError 在 ValueError 之前检查
Task Commits
Each task was committed atomically:
- Task 1: 改进解析失败的错误处理和日志 (TDD) -
970c13a(test)- RED: 创建失败的测试(JSONDecodeError 重试、ValidationError 不重试、日志记录)
- GREEN: 实现错误类型区分和重试逻辑
- 验证:所有 10 个测试通过(4 + 2 + 4)
Plan metadata: (待最终提交)
Note: Implementation code was already committed as part of Plan 14-01 (commit 5c32cfd)
Files Created/Modified
kb_workflow/srt/semantic_engine.py- 增强的错误处理和日志记录_is_recoverable_error(): 添加 ValidationError 检查(在 ValueError 之前)segment(): 添加 last_llm_output 跟踪,改进日志记录- 区分可恢复/不可恢复错误的日志分支
tests/test_semantic_robustness.py- 测试覆盖TestParseFailureRetry: 4 个测试(JSONDecodeError 重试、ValidationError 不重试、日志记录)TestFallbackLogging: 2 个测试(降级日志、重试日志)TestExtractJSON: 4 个测试(JSON 提取函数)
Decisions Made
- ValidationError 继承链处理: Pydantic 的
ValidationError继承自ValueError,必须在_is_recoverable_error()中先检查ValidationError,否则会被误判为可恢复错误 - 可恢复错误定义: JSONDecodeError 和 ValueError(非 ValidationError)被视为可恢复错误,因为 LLM 输出格式可能不稳定,重试可能成功
- 不可恢复错误定义: ValidationError 表示数据结构错误(缺少必需字段、类型错误等),重试无意义,直接降级
- 日志详细程度: 解析失败时记录 LLM 输出片段(前 500 字符),便于诊断 LLM 输出格式问题
Deviations from Plan
None - plan executed exactly as written.
Issues Encountered
-
ValidationError 继承自 ValueError
- Problem: 初始实现中,
isinstance(error, ValueError)匹配了ValidationError,导致验证错误被误判为可恢复错误 - Solution: 在
_is_recoverable_error()中先检查ValidationError,再检查ValueError - Verification: 测试
test_validation_error_no_retry验证 ValidationError 只调用 1 次 LLM(不重试)
- Problem: 初始实现中,
-
日志级别不一致
- Problem: 测试期望 ERROR 级别日志,但实现使用 WARNING 级别
- Solution: 更新测试使用 WARNING 级别,与实际日志级别一致
- Rationale: WARNING 级别更合适,因为系统已降级到规则分段,仍可继续运行
User Setup Required
None - no external service configuration required.
Next Phase Readiness
- ✅ ROBUST-02 完成:解析失败时自动重试或降级
- ✅ ROBUST-04 完成:降级过程记录详细日志
- 准备好进入 Plan 14-03(AI 不可用时的降级策略)
- 准备好进入 Plan 14-04(长视频分块处理)
Phase: 14-robustness-cost Completed: 2026-03-23