--- phase: 01-foundation plan: 03 subsystem: infra tags: [errors, config, retry, pydantic-settings, tenacity, tdd] # Dependency graph requires: - phase: 01-foundation-02 provides: Core schemas (StepStatus, StepInput, StepOutput) provides: - Structured error types (KBError, NetworkError, ValidationError, SystemError, AuthError) - Configuration management with pydantic-settings - Automatic retry mechanism for network errors - Error serialization via to_dict() affects: [processing-skills, platform-skills] # Tech tracking tech-stack: added: [pydantic-settings, tenacity, python-dotenv] patterns: [structured errors with context, singleton config via lru_cache, decorator-based retry] key-files: created: - kb_pipeline/errors.py - kb_pipeline/config.py - kb_pipeline/retry.py - tests/test_pipeline/test_errors.py - tests/test_pipeline/test_config.py - tests/test_pipeline/test_retry.py modified: - kb_pipeline/__init__.py key-decisions: - "使用 pydantic-settings 从 ~/.kb_env 加载配置" - "使用 tenacity 实现重试机制,3次重试+指数退避" - "SystemError 虽然与 Python 内置同名,但在 kb_pipeline 命名空间下安全" patterns-established: - "Pattern 1: 错误类包含 step_name, input_summary, suggestion 用于调试" - "Pattern 2: 配置使用 SecretStr 保护敏感信息" - "Pattern 3: 装饰器模式用于横切关注点(重试)" requirements-completed: [REL-02, MNT-02, MNT-03] # Metrics duration: 8min completed: 2026-03-13 --- # Phase 1 Plan 3: Error Handler & Config Manager Summary **结构化错误处理、统一配置管理(pydantic-settings)和网络重试机制(tenacity),为工作流提供可靠的错误恢复和配置验证能力** ## Performance - **Duration:** 8 min - **Started:** 2026-03-13T09:12:23Z - **Completed:** 2026-03-13T09:20:34Z - **Tasks:** 5 - **Files modified:** 7 ## Accomplishments - 结构化错误类型(KBError 及其子类)包含丰富上下文便于调试 - 配置从 ~/.kb_env 加载,支持 SecretStr 保护敏感信息 - 网络错误自动重试 3 次,指数退避(2s, 4s, max 10s) - 所有公共 API 可从包根导入 ## Task Commits Each task was committed atomically: 1. **Task 1: Write failing tests for error handling** - `8405590` (test) 2. **Task 2: Implement error handling** - `d8cfee3` (feat) 3. **Task 3: Write and implement configuration management** - `e789d81` (test) + `44b5d18` (feat) 4. **Task 4: Write and implement retry mechanism** - `c87dd8b` (test) + `74adaf3` (feat) 5. **Task 5: Update package exports** - `c69515e` (feat) **Plan metadata:** TBD (docs: complete plan) _Note: TDD tasks may have multiple commits (test -> feat -> refactor)_ ## Files Created/Modified - `kb_pipeline/errors.py` - 结构化错误类型(ErrorType, KBError, NetworkError, ValidationError, SystemError, AuthError) - `kb_pipeline/config.py` - 配置管理(KBSettings, get_settings) - `kb_pipeline/retry.py` - 重试装饰器(retry_on_network_error) - `tests/test_pipeline/test_errors.py` - 错误处理测试(22 个测试用例) - `tests/test_pipeline/test_config.py` - 配置管理测试(14 个测试用例) - `tests/test_pipeline/test_retry.py` - 重试机制测试(7 个测试用例) - `kb_pipeline/__init__.py` - 更新导出 ## Decisions Made - 使用 pydantic-settings 从 ~/.kb_env 加载配置,env_prefix="KB_" - 使用 tenacity 实现重试,配置 reraise=True 重新抛出原始异常 - 测试中使用 `_env_file=None` 参数隔离环境变量 ## Deviations from Plan ### Auto-fixed Issues **1. [Rule 3 - Blocking] 安装 pydantic-settings 依赖** - **Found during:** Task 3 (配置管理实现) - **Issue:** pydantic-settings 包未安装 - **Fix:** 运行 `pip install pydantic-settings` - **Files modified:** .venv (虚拟环境) - **Verification:** 导入成功,测试通过 - **Committed in:** 44b5d18 (Task 3 commit) **2. [Rule 3 - Blocking] 安装 tenacity 依赖** - **Found during:** Task 4 (重试机制实现) - **Issue:** tenacity 包未安装 - **Fix:** 运行 `pip install tenacity` - **Files modified:** .venv (虚拟环境) - **Verification:** 导入成功,测试通过 - **Committed in:** 74adaf3 (Task 4 commit) **3. [Rule 1 - Bug] tenacity reraise 导入错误** - **Found during:** Task 4 (重试机制实现) - **Issue:** `from tenacity import reraise` 失败,新版本 tenacity 将 reraise 作为参数而非导出 - **Fix:** 直接在 retry() 调用中使用 `reraise=True` 参数 - **Files modified:** kb_pipeline/retry.py - **Verification:** 测试通过 - **Committed in:** 74adaf3 (Task 4 commit) **4. [Rule 1 - Bug] 配置测试环境隔离问题** - **Found during:** Task 3 (配置管理测试) - **Issue:** 测试失败因为环境变量从 ~/.kb_env 读取,影响测试隔离 - **Fix:** 修改测试使用 `_env_file=None` 参数和 `patch.dict(os.environ, {}, clear=True)` - **Files modified:** tests/test_pipeline/test_config.py - **Verification:** 所有 14 个测试通过 - **Committed in:** 44b5d18 (Task 3 commit) --- **Total deviations:** 4 auto-fixed (2 blocking, 2 bug) **Impact on plan:** 所有修复都是必要的依赖安装和环境适配,无范围蔓延 ## Issues Encountered None - 所有依赖和测试问题都通过 deviation rules 自动处理 ## User Setup Required None - 无外部服务配置要求 ## Next Phase Readiness - 错误处理、配置管理、重试机制已就绪 - 所有 100 个测试通过 - 公共 API 可从 kb_pipeline 包根导入 --- *Phase: 01-foundation* *Completed: 2026-03-13*