This repository has been archived on 2026-08-07. You can view files and clone it. You cannot open issues or pull requests or push a commit.
Files
kb-skills/.planning/phases/14-robustness-cost/14-02-SUMMARY.md
T

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
llm
error-handling
retry
fallback
pydantic
json-parsing
phase provides
13-llm UnifiedSegmentationStrategy, SemanticSegmentationEngine, VideoSegment
Parse error retry logic with JSONDecodeError/ValueError recovery
ValidationError immediate fallback (data structure errors)
Detailed error logging with LLM output fragments
14-03
14-04
14-05
added patterns
Error type differentiation (recoverable vs non-recoverable)
Retry loop with attempt tracking
Detailed logging for parse failures
created modified
kb_workflow/srt/semantic_engine.py
tests/test_semantic_robustness.py
ValidationError checked before ValueError (ValidationError inherits from ValueError)
JSON parse errors (JSONDecodeError, ValueError) are recoverable - retry 1 time
Pydantic validation errors (ValidationError) are non-recoverable - immediate fallback
Parse failures log LLM output fragment (first 500 chars) for diagnosis
Error type hierarchy: ValidationError → ValueError → Exception
Recoverable error detection: network, timeout, rate limit, JSON parse errors
Non-recoverable errors: 4xx HTTP, ValidationError, other exceptions
Logging levels: INFO for retry, WARNING for fallback, DEBUG for success
ROBUST-02
ROBUST-04
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:

  1. 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

  1. ValidationError 继承自 ValueError

    • Problem: 初始实现中,isinstance(error, ValueError) 匹配了 ValidationError,导致验证错误被误判为可恢复错误
    • Solution: 在 _is_recoverable_error() 中先检查 ValidationError,再检查 ValueError
    • Verification: 测试 test_validation_error_no_retry 验证 ValidationError 只调用 1 次 LLM(不重试)
  2. 日志级别不一致

    • 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