diff --git a/.planning/PROJECT.md b/.planning/PROJECT.md
new file mode 100644
index 0000000..e4c378a
--- /dev/null
+++ b/.planning/PROJECT.md
@@ -0,0 +1,83 @@
+# kb-skills 工作流重构
+
+## What This Is
+
+一个基于管道模型的知识库内容处理技能体系。将外部链接（B站视频/专栏、知乎问答/专栏）转换为结构化的深度分析报告，支持幂等执行和断点续传。
+
+## Core Value
+
+**可靠、可维护的处理管道** - 每个步骤独立、可验证、可恢复。无论何时失败，都能从断点继续，不会丢失已完成的进度。
+
+## Requirements
+
+### Validated
+
+- ✓ B站视频元数据提取 — bilibili_metadata.py
+- ✓ B站视频/专栏内容下载 — bilibili_content.py
+- ✓ B站字幕下载（官方字幕） — bilibili_content.py --type subtitle-download
+- ✓ 知乎元数据提取 — zhihu_metadata.py
+- ✓ 知乎文章/问答内容提取 — zhihu_content.py
+- ✓ Whisper 语音识别 — whisper.py
+- ✓ 说话者分离 — whisper_diarization.py
+- ✓ FunASR 中文语音识别 — funasr_runner.py
+- ✓ OCR 文字识别 — ocr_processor.py
+- ✓ AI 深度分析 — deep_analyzer.py
+- ✓ 目录管理和归档 — kb_workflow.py
+
+### Active
+
+- [ ] **PIPE-01**: 统一的管道模型 - 每个步骤是独立管道，输入→处理→输出
+- [ ] **PIPE-02**: 步骤级状态管理 - 每个主要步骤完成后记录状态到 workflow_state.json
+- [ ] **PIPE-03**: 统一 JSON Schema - 所有子技能遵守统一的输入输出格式规范
+- [ ] **PIPE-04**: 幂等执行保证 - 重复执行同一链接不会产生重复文件
+- [ ] **PIPE-05**: 错误恢复策略 - 403/超时等错误有明确的降级策略
+- [ ] **PIPE-06**: 清晰的流程定义 - 每个步骤的前置条件、输出格式、成功标准明确
+- [ ] **PIPE-07**: Schema 验证机制 - 每个步骤输出通过 Schema 验证
+- [ ] **PIPE-08**: 代码结构清晰化 - 模块化设计，新人能快速理解和修改
+
+### Out of Scope
+
+- 实时/流式处理 — 批量处理即可，不需要实时
+- 并发限制 — 不需要限制并发数量
+- 用户界面 — 命令行运行，不需要 Web/UI
+- 多语言支持 — 中文即可，不需要国际化
+- 微信公众号/小红书 — 当前只支持 B站和知乎
+
+## Context
+
+### 现有架构
+- 技能集合：13 个技能模块（kb-* 系列 + gsd-openclaw）
+- 主工作流：kb-workflow 协调多个子技能的执行
+- 平台支持：B站（视频/专栏）、知乎（问答/专栏/视频）
+- 处理类型：视频需要字幕/语音识别，文章直接提取文字
+
+### 已知问题（来自审查报告）
+1. **流程不清晰**：执行主体不明确（主代理 vs 子代理），步骤边界模糊
+2. **完成要求不明确**：缺少成功标准，失败处理不一致
+3. **缺少示例**：没有端到端成功案例，错误处理案例缺失
+4. **无状态管理**：没有 workflow_state.json，无法断点续传
+5. **格式不明确**：JSON Schema 缺失，字段名不统一，命名规范模糊
+
+### 技术债务
+- 环境变量配置分散（~/.kb_env, HF_TOKEN 在子章节, ZHIHU_COOKIE 在子技能）
+- 超时和重试机制不明确
+- 子技能文档质量参差不齐
+
+## Constraints
+
+- **Tech Stack**: Python 3.12+, 现有依赖库保持不变
+- **Compatibility**: 可破坏性更新，不需要向后兼容
+- **Scope**: 只支持 B站和知乎两个平台
+- **State Granularity**: 步骤级状态管理（不是任务级）
+
+## Key Decisions
+
+| Decision | Rationale | Outcome |
+|----------|-----------|---------|
+| 管道模型 | 每个步骤独立，输入→处理→输出，串联执行 | — Pending |
+| 步骤级状态 | 记录主要步骤状态（解析→下载→识别→分析），支持断点续传 | — Pending |
+| Schema 验证 | 只验证 JSON Schema，内容正确性由步骤保证 | — Pending |
+| 全量重构 | 主流程 + 所有子技能一起重构，避免接口不兼容 | — Pending |
+
+---
+*Last updated: 2026-03-13 after initialization*