From b7db451d9d884f9c1f5cc2014021ee941bac4340 Mon Sep 17 00:00:00 2001 From: starmen1265 Date: Fri, 13 Mar 2026 17:22:58 +0800 Subject: [PATCH] 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 --- .planning/REQUIREMENTS.md | 12 +- .planning/STATE.md | 16 +- .../phases/01-foundation/01-03-SUMMARY.md | 151 ++++++++++++++++++ 3 files changed, 167 insertions(+), 12 deletions(-) create mode 100644 .planning/phases/01-foundation/01-03-SUMMARY.md diff --git a/.planning/REQUIREMENTS.md b/.planning/REQUIREMENTS.md index 0785f40..ec278db 100644 --- a/.planning/REQUIREMENTS.md +++ b/.planning/REQUIREMENTS.md @@ -16,7 +16,7 @@ Requirements for initial release. Each maps to roadmap phases. ### Reliability (可靠性) - [x] **REL-01**: 幂等执行保证 - 重复执行同一链接不会产生重复文件或重复处理 -- [ ] **REL-02**: 错误恢复策略 - 403/超时/网络错误有明确的降级策略和重试机制 +- [x] **REL-02**: 错误恢复策略 - 403/超时/网络错误有明确的降级策略和重试机制 - [x] **REL-03**: 清晰的流程定义 - 每个步骤的前置条件、输出格式、成功标准明确 ### Validation (验证) @@ -26,8 +26,8 @@ Requirements for initial release. Each maps to roadmap phases. ### Maintainability (可维护性) - [ ] **MNT-01**: 代码结构清晰化 - 模块化设计，新人能快速理解和修改 -- [ ] **MNT-02**: 统一配置管理 - 环境变量集中在 ~/.kb_env，使用 pydantic-settings 管理 -- [ ] **MNT-03**: 结构化错误处理 - 错误包含上下文信息，便于调试和日志追踪 +- [x] **MNT-02**: 统一配置管理 - 环境变量集中在 ~/.kb_env，使用 pydantic-settings 管理 +- [x] **MNT-03**: 结构化错误处理 - 错误包含上下文信息，便于调试和日志追踪 ### Platform Support (平台支持) @@ -73,11 +73,11 @@ Which phases cover which requirements. Updated during roadmap creation. | PIPE-02 | Phase 1 | Complete | | PIPE-03 | Phase 1 | Complete | | REL-01 | Phase 1 | Complete | -| REL-02 | Phase 1 | Pending | +| REL-02 | Phase 1 | Complete | | REL-03 | Phase 1 | Complete | | VAL-01 | Phase 1 | Complete | -| MNT-02 | Phase 1 | Pending | -| MNT-03 | Phase 1 | Pending | +| MNT-02 | Phase 1 | Complete | +| MNT-03 | Phase 1 | Complete | | PLAT-01 | Phase 2 | Pending | | PLAT-02 | Phase 2 | Pending | | PLAT-03 | Phase 2 | Pending | diff --git a/.planning/STATE.md b/.planning/STATE.md index 2e32274..8f11e98 100644 --- a/.planning/STATE.md +++ b/.planning/STATE.md @@ -4,14 +4,14 @@ milestone: v1.0 milestone_name: milestone current_plan: 3 status: executing -stopped_at: Completed 01-01 WorkflowStateManager -last_updated: "2026-03-13T09:19:17.560Z" +stopped_at: Completed 01-03-PLAN.md (Error Handler & Config Manager) +last_updated: "2026-03-13T09:22:34.916Z" last_activity: 2026-03-13 progress: total_phases: 4 - completed_phases: 0 + completed_phases: 1 total_plans: 3 - completed_plans: 2 + completed_plans: 3 percent: 8 --- @@ -56,6 +56,7 @@ Progress: [█░░░░░░░░░] 8% *Updated after each plan completion* | Phase 01-foundation P01 | 5 | 3 tasks | 3 files | +| Phase 01-foundation P03 | 8 | 5 tasks | 7 files | ## Accumulated Context @@ -70,6 +71,9 @@ Recent decisions affecting current work: - [01-02]: 创建 pytest.ini 配置 pythonpath - [Phase 01-01]: Follow gsd-openclaw atomic write pattern for crash-safe state persistence - [Phase 01-01]: Return None instead of raising exception when no state file exists +- [Phase 01-foundation]: 使用 pydantic-settings 从 ~/.kb_env 加载配置，env_prefix=KB_ +- [Phase 01-foundation]: 使用 tenacity 实现重试机制，3次重试+指数退避 +- [Phase 01-foundation]: 错误类包含 step_name, input_summary, suggestion 用于调试 ### Pending Todos @@ -85,6 +89,6 @@ None yet. ## Session Continuity -Last session: 2026-03-13T09:19:17.559Z -Stopped at: Completed 01-01 WorkflowStateManager +Last session: 2026-03-13T09:22:34.914Z +Stopped at: Completed 01-03-PLAN.md (Error Handler & Config Manager) Resume file: None diff --git a/.planning/phases/01-foundation/01-03-SUMMARY.md b/.planning/phases/01-foundation/01-03-SUMMARY.md new file mode 100644 index 0000000..83bcf6b --- /dev/null +++ b/.planning/phases/01-foundation/01-03-SUMMARY.md @@ -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*