docs(01): capture phase 1 context

.planning/phases/01-foundation/01-CONTEXT.md

@@ -0,0 +1,89 @@
+# 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*