# Collection Tools

这些脚本用于把 JD、论文和行业资料从 Markdown 笔记变成可检索、可检查、可视化的数据。

## Scripts

### `new_item.py`

生成一个带 frontmatter 的新条目草稿。

```bash
python3 tools/collection/new_item.py jobs "baidu aidu agent algorithm engineer beijing" \
  --title "Baidu AIDU Agent Algorithm Engineer" \
  --url "https://talent.baidu.com/jobs/list?projectType=3&recruitType=GRADUATE"
```

支持的 collection:

- `jobs`
- `papers`
- `industry`

### `build_index.py`

扫描 `jobs/items/`、`papers/items/`、`industry/items/` 的 frontmatter，生成结构化索引。

```bash
python3 tools/collection/build_index.py
```

输出：

- `data/index.json`
- `data/summary.json`

### `check_urls.py`

检查条目中的 `url`、`source_url`、`code_url` 是否可访问。

```bash
python3 tools/collection/check_urls.py
```

可加 `--json` 输出机器可读结果。

### `collect_arxiv.py`

用 arXiv API 批量收集最近一年 Agent 相关论文，生成 `papers/items/` 条目、`data/arxiv-agent-papers-*.json` 入库清单和 `data/arxiv-agent-candidates-*.json` 全量候选清单。

```bash
python3 tools/collection/collect_arxiv.py \
  --from-date 2025-07-08 \
  --to-date 2026-07-08 \
  --max-items 180 \
  --sleep 1.0
```

默认策略：

- 多组关键词召回：LLM agent、language agent、tool use、memory、evaluation、coding agent、web/GUI agent、multi-agent、safety、RAG 等。
- 自动去重：按 arXiv ID 去重。
- 自动打标签：根据标题和摘要推断 topics。
- 自动分层：生成 `queued` 条目，后续人工精读后再升级状态。
- API 退避：遇到 arXiv 429 或临时网络错误时按 `--retries` 和 `--retry-sleep` 重试。

当 `export.arxiv.org` API 不可用时，可以使用 arXiv 官方搜索页面后端：

```bash
python3 tools/collection/collect_arxiv.py \
  --backend search-html \
  --from-date 2026-07-09 \
  --to-date 2026-07-27 \
  --per-query 300 \
  --page-size 100 \
  --request-timeout 120 \
  --dry-run
```

`--dry-run` 不写 `papers/items/`，但会保存候选和选择 manifest。之后使用
`promote_arxiv_manifest.py` 按本地阈值入库。API 和 HTML 后端使用相同的分类、去重和
manifest schema。

## Method

1. 搜索或导入资料。
2. 用 `new_item.py` 生成草稿。
3. 人工整理摘要、标签、判断和关联。
4. 运行 `build_index.py` 更新结构化数据。
5. 运行 `check_urls.py` 检查来源可达性。
6. 更新对应 insight 文件。

大规模论文扩展时，先运行 `collect_arxiv.py`，再运行 `build_index.py`。

### `promote_arxiv_manifest.py`

从 `collect_arxiv.py` 生成的候选池里，把达到阈值的记录批量提升为 `papers/items/` 条目。适合在 arXiv API 限流后继续本地调阈值。

```bash
python3 tools/collection/promote_arxiv_manifest.py \
  data/arxiv-agent-candidates-2025-07-08-to-2026-07-08.json \
  --min-score 13 \
  --relevance high \
  --output-manifest data/arxiv-agent-papers-2025-07-08-to-2026-07-08.json
```

默认用途：

- `score >= 13` 且 `relevance=high` 的论文进入主阅读队列。
- 低分候选仍留在 candidate manifest，后续可以人工抽查或降低阈值再提升。