90 lines
3.5 KiB
Markdown
90 lines
3.5 KiB
Markdown
# Phase 1: Foundation - Context
|
|
|
|
**Gathered:** 2026-03-13
|
|
**Status:** Ready for planning
|
|
|
|
<domain>
|
|
## Phase Boundary
|
|
|
|
建立可靠的基础设施层，支持步骤级状态持久化、Schema 验证、结构化错误处理和统一配置管理。这些是后续所有平台技能和处理技能的基础。
|
|
|
|
此阶段不涉及具体平台集成（B站/知乎），只构建管道模型的核心机制。
|
|
|
|
</domain>
|
|
|
|
<decisions>
|
|
## 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 — 自动验证和类型转换
|
|
|
|
</decisions>
|
|
|
|
<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>
|
|
|
|
<specifics>
|
|
## Specific Ideas
|
|
|
|
- 状态文件名建议: `workflow_state.json`，存放在每个内容目录下
|
|
- 降级链示例: 官方字幕 → Whisper → FunASR
|
|
- 错误信息格式应包含 `step_name`, `input_summary`, `error_type`, `message`, `suggestion` 字段
|
|
|
|
</specifics>
|
|
|
|
<deferred>
|
|
## Deferred Ideas
|
|
|
|
None — discussion stayed within phase scope
|
|
|
|
</deferred>
|
|
|
|
---
|
|
|
|
*Phase: 01-foundation*
|
|
*Context gathered: 2026-03-13*
|