# DeepCast AI Coding Instructions

You are an expert AI agent working on **DeepCast**, an automated podcast generation engine based on the [HelloAgents](https://github.com/datawhalechina/Hello-Agents) framework.

## 🏗 Architecture Overview

### Backend (Python 3.10+ / FastAPI)
- **Entry Point**: [backend/src/main.py](backend/src/main.py) — FastAPI server at `localhost:8000`
- **Core Orchestrator**: [backend/src/agent.py](backend/src/agent.py) — `DeepResearchAgent` coordinates the entire workflow
- **Workflow Pipeline**: `Planning → Research (parallel threads) → Summarization → Reporting → Script → TTS → Audio Synthesis`
- **Service Layer**: [backend/src/services/](backend/src/services/) — decoupled business logic:
  - `planner.py` / `summarizer.py` / `reporter.py` — research phases
  - `script_generator.py` — converts report to dialogue
  - `audio_generator.py` — TTS per dialogue turn
  - `audio_synthesizer.py` — FFmpeg stitching
  - `search.py` — hybrid search via `hello_agents.tools.SearchTool`

### Frontend (Vue 3 / Vite / TypeScript)
- **SSE Streaming**: [frontend/src/services/api.ts](frontend/src/services/api.ts) connects to `/research/stream` via `fetch` + `ReadableStream`
- **Event Types**: `status`, `todo_list`, `task_status`, `search_result`, `summary`, `report`, `script`, `audio_progress`, `done`, `error`, `cancelled`

### Data Flow
```
User Topic → PlanningService (smart_llm) → TodoItems[]
           → [Parallel Workers] SearchTool → SummarizationService (fast_llm)
           → ReportingService (smart_llm) → ScriptGenerationService → AudioGenerationService → PodcastSynthesisService
           → Output: report.md + podcast.mp3
```

## 🛠 Developer Workflows

```bash
# Backend (requires .env configured from env.example)
cd backend && python src/main.py

# Frontend
cd frontend && npm install && npm run dev

# Verification scripts (run from project root)
python backend/scripts/verify_ecnu_llm.py   # Test LLM
python backend/scripts/verify_ecnu_tts.py   # Test TTS
python backend/scripts/verify_ffmpeg.py     # Check FFmpeg
python backend/scripts/verify_search.py     # Test search APIs
```

## 💡 Key Patterns

### LLM Model Selection
- **`smart_llm` (`ecnu-reasoner`)**: For complex reasoning — planning (`todo_agent`), reporting (`report_agent`)
- **`fast_llm` (`ecnu-max`)**: For high-volume tasks — task summarization, script generation
- Configured in [backend/src/config.py](backend/src/config.py) via `SMART_LLM_MODEL` / `FAST_LLM_MODEL`

### Agent Definition Pattern
Agents are created in `DeepResearchAgent.__init__` using `ToolAwareSimpleAgent`:
```python
self.todo_agent = self._create_tool_aware_agent(
    name="研究规划专家",
    system_prompt=todo_planner_system_prompt,  # from prompts.py
    llm=self.smart_llm,
)
```

### Structured Output
- **Models**: [backend/src/models.py](backend/src/models.py) — `SummaryState`, `TodoItem`, `SummaryStateOutput`
- **Prompts**: [backend/src/prompts.py](backend/src/prompts.py) — JSON output instructions embedded in system prompts
- When adding new agent outputs, define Pydantic model + update corresponding prompt's `<输出格式>` section

### Podcast Voices (TTS)
| Role | Voice ID | Character |
|------|----------|-----------|
| Host (夏雨) | `xiayu` | Curious, humorous, audience proxy |
| Guest (李娃) | `liwa` | Knowledgeable expert |

Voice mapping in [backend/src/services/audio_generator.py](backend/src/services/audio_generator.py) `_get_voice_for_role()`

### Streaming Events
The `run_stream()` method in `DeepResearchAgent` uses a multi-threaded worker pattern:
- Each `TodoItem` gets its own thread
- Events are pushed to a `Queue` and yielded to the SSE endpoint
- Supports cancellation via `cancel()` / `is_cancelled()` / `CancelledException`

## ⚠️ Common Pitfalls

| Issue | Solution |
|-------|----------|
| FFmpeg errors in synthesis | Set `FFMPEG_PATH` in `.env` (Windows: `C:\ffmpeg\bin\ffmpeg.exe`) |
| Empty search results | Ensure `TAVILY_API_KEY` or `SERP_API_KEY` is configured |
| LLM timeout | Increase `LLM_TIMEOUT` (default 60s) for complex topics |
| Notes not persisting | Check `NOTES_WORKSPACE` path exists and is writable |
| CORS issues | Frontend proxy in `vite.config.ts`; backend allows all origins by default |

## 📁 Output Artifacts
- **Notes**: `backend/output/notes/` — `note_*.md` + `notes_index.json`
- **Audio**: `backend/output/audio/` — individual MP3s + final `podcast_*.mp3`
- Served statically at `/output/...` via FastAPI `StaticFiles`