From 2ed555ccc2d53626eaaabc6465be814a04e0c027 Mon Sep 17 00:00:00 2001 From: starmen1265 Date: Fri, 13 Mar 2026 16:06:47 +0800 Subject: [PATCH] docs: create roadmap (4 phases) --- .planning/REQUIREMENTS.md | 6 +-- .planning/ROADMAP.md | 103 ++++++++++++++++++++++++++++++++++++++ .planning/STATE.md | 66 ++++++++++++++++++++++++ 3 files changed, 172 insertions(+), 3 deletions(-) create mode 100644 .planning/ROADMAP.md create mode 100644 .planning/STATE.md diff --git a/.planning/REQUIREMENTS.md b/.planning/REQUIREMENTS.md index aac952f..28b9e9f 100644 --- a/.planning/REQUIREMENTS.md +++ b/.planning/REQUIREMENTS.md @@ -81,13 +81,13 @@ Which phases cover which requirements. Updated during roadmap creation. | PLAT-01 | Phase 2 | Pending | | PLAT-02 | Phase 2 | Pending | | PLAT-03 | Phase 2 | Pending | -| MNT-01 | Phase 5 | Pending | +| MNT-01 | Phase 4 | Pending | **Coverage:** - v1 requirements: 12 total - Mapped to phases: 12 -- Unmapped: 0 ✓ +- Unmapped: 0 --- *Requirements defined: 2026-03-13* -*Last updated: 2026-03-13 after initial definition* +*Last updated: 2026-03-13 after roadmap creation* diff --git a/.planning/ROADMAP.md b/.planning/ROADMAP.md new file mode 100644 index 0000000..08c43c0 --- /dev/null +++ b/.planning/ROADMAP.md @@ -0,0 +1,103 @@ +# Roadmap: kb-skills 工作流重构 + +## Overview + +将现有分散的技能模块重构为统一的管道处理系统。从基础设施（状态管理、Schema验证）开始，逐步集成平台技能（B站/知乎）、处理技能（ASR/OCR），最终形成完整的端到端工作流。每个阶段都交付可独立验证的能力，确保长时任务可恢复、可追溯。 + +## Phases + +**Phase Numbering:** +- Integer phases (1, 2, 3): Planned milestone work +- Decimal phases (2.1, 2.2): Urgent insertions (marked with INSERTED) + +Decimal phases appear between their surrounding integers in numeric order. + +- [ ] **Phase 1: Foundation** - 状态管理、Schema验证、错误处理、统一配置 +- [ ] **Phase 2: Platform Skills** - B站/知乎链接解析、元数据提取、内容下载 +- [ ] **Phase 3: Processing Skills** - ASR/OCR集成、多模态内容处理 +- [ ] **Phase 4: Analysis & Orchestration** - 深度分析集成、完整管道编排、端到端验证 + +## Phase Details + +### Phase 1: Foundation +**Goal**: 建立可靠的基础设施，支持步骤级状态持久化、Schema验证和结构化错误处理 +**Depends on**: Nothing (first phase) +**Requirements**: PIPE-01, PIPE-02, PIPE-03, REL-01, REL-02, REL-03, VAL-01, MNT-02, MNT-03 +**Success Criteria** (what must be TRUE): + 1. 执行任意步骤后，workflow_state.json 正确记录该步骤的完成状态 + 2. 中断后重新执行，已完成的步骤被跳过，从中断点继续 + 3. 每个步骤输出通过 Pydantic Schema 验证，格式错误阻止进入下一步 + 4. 所有环境变量集中在 ~/.kb_env，启动时验证必需变量 + 5. 错误信息包含步骤名、输入摘要、失败原因、可操作建议 +**Plans**: TBD + +Plans: +- [ ] 01-01: State Manager - workflow_state.json 管理 +- [ ] 01-02: Schema Registry - 统一输入输出格式定义 +- [ ] 01-03: Error Handler & Config - 结构化错误处理和统一配置 + +### Phase 2: Platform Skills +**Goal**: 集成B站和知乎平台的内容获取能力，形成从链接到原始内容的完整流程 +**Depends on**: Phase 1 +**Requirements**: PLAT-01, PLAT-02, PLAT-03 +**Success Criteria** (what must be TRUE): + 1. 输入B站视频链接，自动提取元数据（标题、作者、时长等）并保存为结构化JSON + 2. 输入B站专栏链接，自动提取文章内容并保存为Markdown + 3. 输入知乎问答/专栏链接，自动提取内容和元数据 + 4. 重复执行同一链接，不产生重复文件（幂等） + 5. 403/超时错误触发降级策略，记录失败原因到状态文件 +**Plans**: TBD + +Plans: +- [ ] 02-01: Link Parser & B站 Metadata 集成 +- [ ] 02-02: B站 Content (视频/专栏) 集成 +- [ ] 02-03: 知乎 Metadata & Content 集成 + +### Phase 3: Processing Skills +**Goal**: 集成ASR和OCR处理能力，支持视频和图片的多模态内容提取 +**Depends on**: Phase 2 +**Requirements**: None (平台支持已在Phase 2覆盖) +**Success Criteria** (what must be TRUE): + 1. B站视频自动下载字幕（优先官方字幕），无字幕时调用语音识别 + 2. Whisper识别完成后，转录结果保存为结构化JSON（含时间戳） + 3. 视频帧自动提取并OCR识别，文字结果与时间戳关联 + 4. 处理结果自动关联到对应的内容目录 + 5. HF_TOKEN配置时自动启用带说话者分离的Whisper +**Plans**: TBD + +Plans: +- [ ] 03-01: B站字幕下载 & Whisper/FunASR 集成 +- [ ] 03-02: OCR 处理集成 + +### Phase 4: Analysis & Orchestration +**Goal**: 集成深度分析能力，完成端到端工作流编排，实现从链接到分析报告的全自动处理 +**Depends on**: Phase 3 +**Requirements**: MNT-01 +**Success Criteria** (what must be TRUE): + 1. 输入任意支持的平台链接，自动完成解析→下载→识别→分析全流程 + 2. 深度分析报告保存到对应内容目录，包含结构化的核心观点和洞察 + 3. 整个工作流可通过单个命令触发，无需手动干预 + 4. 新人能通过清晰的模块结构和文档理解代码，在30分钟内定位并修改任意步骤 + 5. 所有步骤的状态可通过 workflow_state.json 查询 +**Plans**: TBD + +Plans: +- [ ] 04-01: Deep Analyzer 集成 +- [ ] 04-02: Pipeline Engine 完整编排 +- [ ] 04-03: 代码结构整理与文档 + +## Progress + +**Execution Order:** +Phases execute in numeric order: 1 → 2 → 3 → 4 + +| Phase | Plans Complete | Status | Completed | +|-------|----------------|--------|-----------| +| 1. Foundation | 0/3 | Not started | - | +| 2. Platform Skills | 0/3 | Not started | - | +| 3. Processing Skills | 0/2 | Not started | - | +| 4. Analysis & Orchestration | 0/3 | Not started | - | + +--- +*Roadmap created: 2026-03-13* +*Granularity: coarse (4 phases)* diff --git a/.planning/STATE.md b/.planning/STATE.md new file mode 100644 index 0000000..1f48f6f --- /dev/null +++ b/.planning/STATE.md @@ -0,0 +1,66 @@ +# Project State + +## Project Reference + +See: .planning/PROJECT.md (updated 2026-03-13) + +**Core value:** 可靠、可维护的处理管道 - 每个步骤独立、可验证、可恢复 +**Current focus:** Phase 1 - Foundation + +## Current Position + +Phase: 1 of 4 (Foundation) +Plan: 0 of 3 in current phase +Status: Ready to plan +Last activity: 2026-03-13 — Roadmap created, phases defined + +Progress: [░░░░░░░░░░] 0% + +## Performance Metrics + +**Velocity:** +- Total plans completed: 0 +- Average duration: - min +- Total execution time: 0.0 hours + +**By Phase:** + +| Phase | Plans | Total | Avg/Plan | +|-------|-------|-------|----------| +| 1. Foundation | 0 | - | - | +| 2. Platform Skills | 0 | - | - | +| 3. Processing Skills | 0 | - | - | +| 4. Analysis & Orchestration | 0 | - | - | + +**Recent Trend:** +- Last 5 plans: - +- Trend: - + +*Updated after each plan completion* + +## Accumulated Context + +### Decisions + +Decisions are logged in PROJECT.md Key Decisions table. +Recent decisions affecting current work: + +- [Roadmap]: 采用4阶段结构（coarse粒度），合并Processing和Analysis相关需求 + +### Pending Todos + +[From .planning/todos/pending/ — ideas captured during sessions] + +None yet. + +### Blockers/Concerns + +[Issues that affect future work] + +None yet. + +## Session Continuity + +Last session: 2026-03-13 +Stopped at: Roadmap creation complete, ready for Phase 1 planning +Resume file: None