3.5 KiB
3.5 KiB
Phase 1: Foundation - Context
Gathered: 2026-03-13 Status: Ready for planning
## Phase Boundary建立可靠的基础设施层，支持步骤级状态持久化、Schema 验证、结构化错误处理和统一配置管理。这些是后续所有平台技能和处理技能的基础。
此阶段不涉及具体平台集成（B站/知乎），只构建管道模型的核心机制。
## Implementation Decisions状态管理
- 状态粒度: 步骤级状态 — 符合现有子技能映射 (metadata→content→whisper→analyzer)
- 状态关联: 按内容ID关联 — 如 BV123xxx，重复链接自动识别
- 幂等执行: 自动跳过已完成步骤 — 重新执行同一链接时从中断点继续
- 备份机制: 需要备份 — 原子写入 + .bak 轮转，崩溃后可恢复
- 存储位置: 状态文件存放在内容目录下 — 方便关联查看
- 历史记录: 只保留最新状态 — 不追加历史执行记录
Schema 验证
- 验证时机: 立即验证 — 步骤完成后立即验证，失败则阻止进入下一步
- Schema 定义位置: 集中定义 — 所有步骤的 Schema 集中在一个模块
- 验证范围: 验证输入和输出 — 步骤执行前验证输入，执行后验证输出
- Schema 格式: Pydantic 模型 — 自带验证和序列化，类型安全
错误处理
- 错误分类: 支持四种错误类型
- 网络错误 (403/404/500/超时)
- 验证错误 (Schema 验证失败)
- 系统错误 (文件系统/内存/依赖缺失)
- 认证/配额错误 (API配额/Cookie过期/Token失效)
- 重试策略: 自动重试 — 网络错误自动重试3次，指数退避
- 错误信息: 完整上下文 — 步骤名、输入摘要、错误类型、失败原因、可操作建议
- 降级策略: 定义降级链 — 如官方字幕失败后尝试语音识别
配置管理
- 配置文件位置: ~/.kb_env — 延续现有习惯
- 验证时机: 启动时验证 — 缺失必需变量则报错退出
- 敏感信息处理: 环境变量存敏感 — Cookie/Token 用环境变量，配置文件只存非敏感配置
- 配置库: pydantic-settings — 自动验证和类型转换
<code_context>
Existing Code Insights
Reusable Assets
gsd-openclaw/src/gsd_openclaw/state_manager.py: 完整的原子状态保存、备份轮转、Schema 验证模式 — 可作为 State Manager 实现参考kb-workflow/kb_workflow.py: 目录管理、查重、归档工具函数 — 可复用
Established Patterns
- 现有子技能映射:
METADATA_AGENTS = {"bilibili": "kb-bilibili-metadata", "zhihu": "kb-zhihu-metadata"} - 内容类型分类:
VIDEO_CONTENT_TYPES,TEXT_CONTENT_TYPES,IMAGE_CONTENT_TYPES - 环境变量分散在 ~/.kb_env, HF_TOKEN, ZHIHU_COOKIE 等
Integration Points
- State Manager 需要与现有 kb_workflow.py 集成
- Schema Registry 需要定义所有子技能的输入输出格式
- Error Handler 需要被所有子技能调用
- Config Manager 需要统一现有分散的环境变量
</code_context>
## Specific Ideas- 状态文件名建议:
workflow_state.json，存放在每个内容目录下 - 降级链示例: 官方字幕 → Whisper → FunASR
- 错误信息格式应包含
step_name,input_summary,error_type,message,suggestion字段
None — discussion stayed within phase scope
Phase: 01-foundation Context gathered: 2026-03-13