starmen1265/kb-skills
Archived
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

docs(01-03): complete error handler & config manager plan

Browse Source 
- 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:
starmen1265
2026-03-13 17:22:58 +08:00
parent 770225439b
commit b7db451d9d
3 changed files with 167 additions and 12 deletions
Download Patch File Download Diff File Expand all files Collapse all files
.planning/REQUIREMENTS.md
+6 -6
View File
@@ -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 |
.planning/STATE.md
+10 -6
View File
@@ -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
.planning/phases/01-foundation/01-03-SUMMARY.md
+151
View File
@@ -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*