docs(01-03): complete error handler & config manager plan
- Structured error types with rich context (KBError, NetworkError, etc.) - Configuration management via pydantic-settings from ~/.kb_env - Automatic retry mechanism with tenacity (3 attempts, exponential backoff) - All 100 tests passing - Requirements REL-02, MNT-02, MNT-03 completed Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
This commit is contained in:
@@ -0,0 +1,151 @@
|
||||
---
|
||||
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*
|
||||
Reference in New Issue
Block a user