# Papers.cool Topic Workflow（MVP + V2）

本文档说明当前实现的主题检索工作流：围绕 `ICL压缩 / ICL隐式偏置 / KV Cache加速`，支持单次多主题检索、汇总、日报输出、定时执行与 UI 操作。

## 1. 端到端流程

```text
Input Queries
   -> Query Normalize
   -> Source Injection (papers_cool by default)
   -> Branch Search (arxiv + venue)
   -> Parse & Normalize Records
   -> Merge / Dedup / Score
   -> Query Summary + Global Summary
   -> (Optional) LLM Enrichment (summary/trends/insight/relevance)
   -> (Optional) LLM-as-Judge (5-dim scoring + recommendation)
   -> (Optional) DailyPaper Markdown/JSON
   -> (Optional) Scheduler Cron + Feed Events
```

### 关键步骤

1. **查询规范化**
   - 内置中文映射：
     - `ICL压缩` -> `icl compression`
     - `ICL隐式偏置` -> `icl implicit bias`
     - `KV Cache加速` -> `kv cache acceleration`
   - 同义输入去重，避免重复请求。

2. **单源检索 + 分支策略**
   - Source：`papers_cool`
   - Branch：`arxiv` / `venue`
   - URL：`/{branch}/search?query=...&highlight=1&show=...`

3. **聚合**
   - 先按 URL 去重，后按归一化标题兜底去重。
   - 输出 `matched_keywords / matched_queries / score`。

4. **LLM 增强（可选）**
   - 统一入口 `LLMService`，按 task_type 走 ModelRouter。
   - 支持 `summary/trends/insight/relevance` 四类增强。
   - 默认关闭，不影响原有纯检索模式。

5. **LLM-as-Judge（可选）**
   - 对每个 query 的 top papers 做 5 维评分：relevance/novelty/rigor/impact/clarity。
   - 产出 `overall` 与 `recommendation`（must_read/worth_reading/skim/skip）。
   - 可配置重复打分次数（中位数校准）。

6. **日报输出（DailyPaper）**
   - 支持 `markdown/json/both`。
   - 支持直接写盘。
   - Markdown 会自动附加 LLM Insights 区块（若启用）。

7. **调度与信息流**
   - ARQ job 定时生成日报。
   - 将日报高亮项桥接到 feed 的 recommendation 事件。
   - 支持 `PAPERBOT_DAILYPAPER_ENABLE_LLM` 与特性开关。

## 2. 代码位置

- Source 注入层：`src/paperbot/application/workflows/topic_search_sources.py`
- 工作流编排：`src/paperbot/application/workflows/paperscool_topic_search.py`
- LLM 统一服务：`src/paperbot/application/services/llm_service.py`
- Prompt 模板：`src/paperbot/application/prompts/registry.py`
- DailyPaper 报告：`src/paperbot/application/workflows/dailypaper.py`
- API 路由：`src/paperbot/api/routes/paperscool.py`
- CLI 命令：`src/paperbot/presentation/cli/main.py`
- Scheduler/ARQ：`src/paperbot/infrastructure/queue/arq_worker.py`
- Feed 桥接：`src/paperbot/workflows/feed.py`
- Web 页面：`web/src/app/workflows/page.tsx`

## 3. API 使用

### Topic Search

`POST /api/research/paperscool/search`

```json
{
  "queries": ["ICL压缩", "ICL隐式偏置", "KV Cache加速"],
  "sources": ["papers_cool"],
  "branches": ["arxiv", "venue"],
  "top_k_per_query": 5,
  "show_per_branch": 25
}
```

### DailyPaper

`POST /api/research/paperscool/daily`

```json
{
  "queries": ["ICL压缩", "ICL隐式偏置", "KV Cache加速"],
  "sources": ["papers_cool"],
  "branches": ["arxiv", "venue"],
  "top_k_per_query": 5,
  "show_per_branch": 25,
  "top_n": 10,
  "formats": ["both"],
  "save": true,
  "output_dir": "./reports/dailypaper",
  "enable_llm_analysis": true,
  "llm_features": ["summary", "trends", "insight"],
  "enable_judge": true,
  "judge_runs": 2,
  "judge_max_items_per_query": 5
}
```

## 4. CLI 使用

```bash
# 主题检索
python -m paperbot.presentation.cli.main topic-search \
  -q "ICL压缩" -q "ICL隐式偏置" -q "KV Cache加速" \
  --source papers_cool --branch arxiv --branch venue --json

# 生成日报（含 LLM 增强）
python -m paperbot.presentation.cli.main daily-paper \
  -q "ICL压缩" -q "ICL隐式偏置" -q "KV Cache加速" \
  --source papers_cool --format both --save --output-dir ./reports/dailypaper \
  --with-llm --llm-feature summary --llm-feature trends --llm-feature insight \
  --with-judge --judge-runs 2 --judge-max-items 5
```

## 5. 新源注入（扩展）

新增数据源时，实现 `TopicSearchSource` 协议并注册到 `TopicSearchSourceRegistry`：

```python
class MySource:
    name = "my_source"

    def search(self, *, query: str, branches: Sequence[str], show_per_branch: int):
        return [TopicSearchRecord(...)]

registry.register("my_source", MySource)
```

然后请求中传入：`"sources": ["my_source"]`。

## 6. 架构图

- 系统架构图（可编辑）：[Excalidraw](../asset/architecture.excalidraw) · [drawio](../asset/architecture.drawio)

## 7. Scheduler 配置（DailyPaper）

- `PAPERBOT_DAILYPAPER_ENABLED`：是否启用 daily cron（true/false）
- `PAPERBOT_DAILYPAPER_CRON_HOUR` / `PAPERBOT_DAILYPAPER_CRON_MINUTE`
- `PAPERBOT_DAILYPAPER_RUN_AT_STARTUP`
- `PAPERBOT_DAILYPAPER_QUERIES`（逗号分隔）
- `PAPERBOT_DAILYPAPER_SOURCES`（逗号分隔）
- `PAPERBOT_DAILYPAPER_BRANCHES`（逗号分隔）
- `PAPERBOT_DAILYPAPER_TOP_K` / `PAPERBOT_DAILYPAPER_SHOW` / `PAPERBOT_DAILYPAPER_TOP_N`
- `PAPERBOT_DAILYPAPER_TITLE`
- `PAPERBOT_DAILYPAPER_OUTPUT_DIR`
- `PAPERBOT_DAILYPAPER_ENABLE_LLM`
- `PAPERBOT_DAILYPAPER_LLM_FEATURES`（逗号分隔：summary,trends,insight,relevance）
- `PAPERBOT_DAILYPAPER_ENABLE_JUDGE`
- `PAPERBOT_DAILYPAPER_JUDGE_RUNS`
- `PAPERBOT_DAILYPAPER_JUDGE_MAX_ITEMS`
- `PAPERBOT_DAILYPAPER_JUDGE_TOKEN_BUDGET`
- `PAPERBOT_DAILYPAPER_NOTIFY_ENABLED`（是否在 daily cron 后推送通知）
- `PAPERBOT_DAILYPAPER_NOTIFY_CHANNELS`（逗号分隔：email,slack,dingding）

通用通知配置（由 `DailyPushService` 读取）：

- `PAPERBOT_NOTIFY_ENABLED`
- `PAPERBOT_NOTIFY_CHANNELS`（逗号分隔：email,slack,dingding）
- `PAPERBOT_NOTIFY_SUBJECT_PREFIX`
- `PAPERBOT_NOTIFY_TIMEOUT_SECONDS`
- `PAPERBOT_NOTIFY_SMTP_HOST` / `PAPERBOT_NOTIFY_SMTP_PORT`
- `PAPERBOT_NOTIFY_SMTP_USERNAME` / `PAPERBOT_NOTIFY_SMTP_PASSWORD`
- `PAPERBOT_NOTIFY_SMTP_USE_TLS` / `PAPERBOT_NOTIFY_SMTP_USE_SSL`
- `PAPERBOT_NOTIFY_EMAIL_FROM` / `PAPERBOT_NOTIFY_EMAIL_TO`
- `PAPERBOT_NOTIFY_SLACK_WEBHOOK_URL`
- `PAPERBOT_NOTIFY_DINGTALK_WEBHOOK_URL`
- `PAPERBOT_NOTIFY_DINGTALK_SECRET`（可选，机器人开启签名时使用）

说明：

- `daily-paper` API 新增 `notify` 与 `notify_channels` 参数，可手动触发一次推送。
- ARQ 定时任务 `daily_papers_job` 在 `notify=true` 时会自动推送日报摘要。

## 8. UI 设计说明

当前采用 **参数化面板 + XYFlow 只读 DAG**（`/workflows`）而非 n8n/coze 式自由拖拽，原因：

- MVP 目标是“先可用 + 可验证 + 可运维”。
- 当前流程节点固定（Source -> Search -> Rank -> DailyPaper -> Schedule），参数面板已经覆盖主要操作。
- 后续如需拖拽，建议在现有节点模型基础上演进（保留当前 API 合约不变）。