Algorithm-Practice-in-Industry Documentation

Technical Documentation: Doragd/Algorithm-Practice-in-Industry

ℹ️ Provenance: Multi-Tier Ingestion · CodeWiki Reference

Overview (README.md) Copy Section

Algorithm-Practice-in-Industry

仓库介绍 Copy Chapter

一开始这个仓库是做如下内容：

搜索、推荐、广告、用增等工业界实践文章收集（来源：知乎、Datafuntalk、技术公众号）

• 搜广推大厂实践文章

本文仅做资源收集，未引用具体内容，如有侵权，请联系删除。
源文件：source.xlsx，可以执行自定义排序

随后扩展了以下内容：

• 搜广推论文推送Bot

• 搜广推顶会论文列表

• 搜广推优质博主文章

• 搜广推算法系列串讲

当前仓库功能 Copy Chapter

当前仓库主线代码位于 paperBotV2/，主要维护搜广推方向的论文、顶会和工业实践内容：

• arXiv 每日论文：抓取 cs.IR 等方向新论文，使用大模型进行粗排、精排和摘要翻译，生成每日 JSON 与网页，并支持飞书群推送。
• 顶会论文汇总：维护 ACL、CIKM、ECIR、EMNLP、ICLR、ICML、KDD、NAACL、NIPS、RecSys、SIGIR、WSDM、WWW 等会议论文列表，生成按会议和年份组织的 Markdown 页面。
• 顶会论文日推：从 paperBotV2/conf_summary/data/results.json 中挑选推荐、搜索、广告相关论文，补全摘要、翻译摘要，并通过飞书机器人推送。
• 行业实践文章：维护大厂搜广推、广告、搜索、推荐、生成式等实践文章，支持 Issue 驱动更新 README、数据文件和网页版本。
• GitHub Actions 自动化：通过 workflow 定时或按 Issue 标签触发 arXiv 更新、飞书通知、顶会更新、会议日推和行业实践页面部署。

代码入口 Copy Chapter

• arXiv 主流程：python -m paperBotV2.arxiv_daily.arxiv
• arXiv 飞书通知：python paperBotV2/arxiv_daily/arxiv_feishu_msg.py
• 顶会 Issue 更新：python paperBotV2/conf_summary/update_from_issue.py
• 顶会日推：python paperBotV2/conf_summary/conf_daily.py
• 顶会 Markdown 生成：python paperBotV2/conf_summary/convert_to_md.py
• 顶会 README 更新：python paperBotV2/conf_summary/update_readme_papers.py
• 行业实践更新：python paperBotV2/industry_practice/maintain.py

旧版脚本和旧 arXiv workflow 已归档到 legacy/，仅用于历史回溯、兼容排查和必要时回滚；日常开发和自动化入口以 paperBotV2/ 为准。

贡献新文章 Copy Chapter

提交issue，利用github action自动更新readme和source.xlsx内容

已提供issue模板，具体内容参考issue：https://github.com/Doragd/Algorithm-Practice-in-Industry/issues/1

一起交流 Copy Chapter

• 关于我：2023届毕业，之前做NLP方向，毕业后转去搜广推方向，一枚努力适应的菜鸡。目前在做召回方向。
• 我的论文阅读笔记：https://github.com/doragd/paperreading
• 和我交流：

搜广推论文推送Bot 【✨Newest:网页版本🥹=>[点击查看](https://doragd.github.io/Algorithm-Practice-in-Industry/arxiv_daily)】 Copy Chapter

• Arxiv论文：利用github action + 大模型排序翻译 + 飞书机器人每天推送cs.IR等方向的新论文到飞书群组中。配置文件
• 顶会论文：利用github action + 彩云小译 + 飞书机器人每天推送搜广推顶会的论文到到飞书群组中。配置文件
• PS: 虽然论文没太大用，但是可以无聊时候刷刷，扩展下思路。
• 比如早上通勤的时候，可以刷刷推送，看看有没有有意思的论文，也不需要花太多时间，毕竟摘要都翻译好了~

顶会论文列表 Copy Chapter

大厂实践文章【✨Newest:网页版本🥹=>[点击查看](https://doragd.github.io/Algorithm-Practice-in-Industry/industry_practice/)】 Copy Chapter

Paperbotv2 Arxiv Daily Review (`docs/paperbotv2-arxiv-daily-review.md`) Copy Section

paperBotV2.arxiv_daily 逻辑 Review 报告

结论摘要 Copy Chapter

paperBotV2.arxiv_daily 已经是当前 arXiv 每日论文链路的主线实现，负责从 arXiv API 抓取论文、调用 DeepSeek 做粗排和精排、写入 JSON、生成 GitHub Pages 页面，并通过独立 workflow 发送飞书通知。整体链路可运行，工作流入口也已经从旧脚本迁移到 paperBotV2。

本次 review 未发现 P0 阻断问题，但发现 3 个 P1 和 2 个 P2 风险。最优先需要处理的是：跨日去重路径拼错、HTML 渲染未启用转义、generate_arxiv_html.py --output 参数必然报错。其次建议补强飞书失败观测和 arXiv 请求超时控制。

当前主线入口 Copy Chapter

arxiv.py 当前逻辑 Copy Chapter

文件：paperBotV2/arxiv_daily/arxiv.py

配置读取 Copy Section

arxiv.py 在模块加载阶段读取以下环境变量：

主处理流程 Copy Section

process_papers() 是主入口，执行顺序如下：

1. get_papers_from_all_categories()：遍历 TARGET_CATEGORYS，调用 arXiv API 获取论文，并初始化 is_filtered=False、is_fine_ranked=False。
2. perform_rough_ranking()：调用 rough_rank_papers()，基于标题使用 PRERANK_PROMPT 进行粗排，过滤低于 ROUGH_SCORE_THRESHOLD 的论文。
3. perform_fine_ranking()：调用 fine_rank_papers()，对粗排前 RETURN_PAPERS 篇论文使用标题和原始摘要做精排，写入 summary、translation、rerank_relevance_score、rerank_reasoning 等字段。
4. save_results_to_json()：将当天结果写入 paperBotV2/arxiv_daily/data/YYYYMMDD.json，并增量合并到 paperBotV2/arxiv_daily/data/results.json。

抓取逻辑 Copy Section

get_daily_arxiv_papers() 查询 http://export.arxiv.org/api/query，使用 cat:<category> AND submittedDate:[yesterday_utc TO now_utc] 作为搜索条件，按 submittedDate 降序排序。每篇论文会被转成以 arxiv_id 为 key 的字典，核心字段包括：

• title
• url
• arxiv_id
• authors
• categories
• pub_date
• ori_summary
• summary
• translation
• relevance_score
• reasoning
• rerank_relevance_score
• rerank_reasoning

LLM 调用逻辑 Copy Section

call_deepseek_api() 使用 OpenAI SDK 兼容 DeepSeek API，请求 deepseek-chat，并设置 response_format={'type': 'json_object'}。函数通过 tenacity 对 APIConnectionError、RateLimitError、APIStatusError 做最多 5 次指数退避重试。

当前行为特点：

• 没有 DEEPSEEK_API_KEY 时直接返回 None，不会发起 API 请求。
• LLM 返回非 JSON 或字段缺失时，函数会捕获异常并返回 None。
• 粗排或精排单篇失败时，该论文不会进入对应成功列表。

数据落盘逻辑 Copy Section

save_results_to_json() 只在 all_papers 非空时写文件。输出包括：

• 天级文件：paperBotV2/arxiv_daily/data/YYYYMMDD.json
• 全量文件：paperBotV2/arxiv_daily/data/results.json

全量文件只新增不存在的 arxiv_id，不会覆盖已有论文字段。这能降低历史数据被重写的风险，但也意味着 LLM prompt 或评分策略升级后，历史数据不会自动刷新。

generate_arxiv_html.py 当前逻辑 Copy Chapter

文件：paperBotV2/arxiv_daily/generate_arxiv_html.py

输入选择 Copy Section

main() 默认从 paperBotV2/arxiv_daily/data/ 中选择最新日期 JSON，排除 results.json。也支持：

• --date YYYYMMDD：指定某一天的 data/YYYYMMDD.json。
• --output path：指定 HTML 输出文件路径。

页面生成流程 Copy Section

generate_html() 的主要步骤：

1. 计算展示日期、论文总数、精选论文数量、平均分。
2. 准备 paperBotV2/arxiv_daily/output/ 与 output/static/templates/。
3. 复制 frontend 下的 styles.css、tailwind.config.js、app.js、index.html 和模板文件到 output/static/。
4. 调用 generate_papers_html() 渲染精选和普通论文卡片。
5. 将统计数据、日期选择器、论文 HTML 注入页面模板。
6. 注入折叠/展开逻辑、日历逻辑和 cache-busting 时间戳。
7. 写入 output/arxiv_YYYYMMDD.html 和 output/index.html。

卡片排序和展示逻辑 Copy Section

generate_papers_html() 会先按是否精选排序，再按 rerank_relevance_score 或 relevance_score 降序排序。精选论文使用 selected_paper_template.html，普通论文使用 normal_paper_template.html。

非精选论文会按分数折叠：

• 精选论文：默认完全展开。
• 普通论文且分数 > 1：默认只展示标题，详情折叠。
• 普通论文且分数 <= 1：默认隐藏在低分区域后。

arxiv_feishu_msg.py 当前逻辑 Copy Chapter

文件：paperBotV2/arxiv_daily/arxiv_feishu_msg.py

输入和跳过条件 Copy Section

main() 读取 paperBotV2/arxiv_daily/data/ 下最新日期 JSON，且要求文件名日期等于运行当天日期。若最新文件不是当天，会直接退出，避免手动或后置触发时重复发送历史论文。

飞书发送前还会检查：

• FEISHU_URL 是否为空。
• 是否加载到论文数据。
• 是否存在 is_fine_ranked=True 且包含 rerank_relevance_score 的论文。

消息选择和格式 Copy Section

脚本筛选精排论文后按 rerank_relevance_score 降序排序，最多发送 RETURN_PAPERS 篇。飞书卡片使用模板：

• template_id: AAqxH62u1uNko
• template_version_name: 1.0.8

模板变量包括：

• paper: Markdown 论文链接
• translation: 中文标题或翻译
• score: 星级和分数标签
• summary: 论文总结
• date: 当前日期

Workflow 当前逻辑 Copy Chapter

arxiv_daily_full.yml Copy Section

当前主流程如下：

1. actions/checkout@v3，已开启 lfs: true。
2. 设置 Python 3.8。
3. 安装 requirements.txt。
4. 执行 python -m paperBotV2.arxiv_daily.arxiv。
5. 进入 paperBotV2/arxiv_daily 执行 python generate_arxiv_html.py。
6. 检查 output/ 和 data/。
7. 如有 diff，提交并 push。
8. 使用 peaceiris/actions-gh-pages@v3 部署 paperBotV2/arxiv_daily/output 到 gh-pages 的 arxiv_daily 目录。

arxiv_feishu_msg.yml Copy Section

当前通知流程如下：

1. 在 arxiv_daily_full workflow 成功后自动触发，也支持手动触发。
2. actions/checkout@v3，已开启 lfs: true。
3. 设置 Python 3.8 并安装依赖。
4. 进入 paperBotV2/arxiv_daily 执行 python arxiv_feishu_msg.py。

问题清单 Copy Chapter

P1: 前一天数据路径拼错，跨日去重实际失效 Copy Section

• 位置：paperBotV2/arxiv_daily/arxiv.py 的 get_papers_from_all_categories()。
• 证据：current_dir 已经是 paperBotV2/arxiv_daily，但 yesterday_file 拼成了 current_dir/arxiv_daily/YYYYMMDD.json。
• 实际保存路径：paperBotV2/arxiv_daily/data/YYYYMMDD.json。
• 影响：前一天论文 ID 集合几乎永远为空，跨日重复论文不会被过滤。
• 风险：重复推送、重复 LLM 调用、成本增加、用户体验下降。
• 建议：改成 os.path.join(current_dir, "data", f"{yesterday:%Y%m%d}.json")，并补一个临时前一天 JSON 的去重测试。

P1: HTML 渲染未启用自动转义，存在页面注入风险 Copy Section

• 位置：paperBotV2/arxiv_daily/generate_arxiv_html.py 的 render_template() 和 generate_papers_html()。
• 证据：代码使用 Template(template_content)，Jinja2 默认 autoescape=False。
• 输入来源：arXiv feed 的标题、作者、摘要、分类，以及 DeepSeek 生成的 summary/reasoning/translation。
• 影响：如果上游文本含 HTML、事件属性或恶意 URL，可能被原样写入 GitHub Pages 页面。
• 验证：构造包含 `` 和 javascript:alert(1) 的论文样本时，渲染结果中 payload 未被转义。
• 建议：使用 jinja2.Environment(autoescape=select_autoescape(['html', 'xml']))；对手工拼接的 CATEGORY_TAGS 使用 html.escape；对 URL 做协议白名单校验，只允许 https://arxiv.org/、https://www.alphaxiv.org/ 等可信域名。

P1: `generate_arxiv_html.py --output` 会触发 `output_dir` 未定义 Copy Section

• 位置：paperBotV2/arxiv_daily/generate_arxiv_html.py 的 generate_html()。
• 证据：只有 output_file is None 时才定义 output_dir，但后续无条件执行 static_dir = os.path.join(output_dir, "static")。
• 影响：CLI 暴露了 --output 参数，但任何指定输出路径的调用都会触发 UnboundLocalError。
• 风险：手动生成指定路径页面、调试脚本或未来 workflow 使用该参数时失败。
• 建议：函数开头统一计算 output_dir：如果指定 output_file，使用 os.path.dirname(os.path.abspath(output_file))；否则使用默认 script_dir/output。

P2: 飞书 webhook 非 2xx 或业务失败不会让 workflow 失败 Copy Section

• 位置：paperBotV2/arxiv_daily/arxiv_feishu_msg.py 的 send_papers_to_feishu()。
• 证据：requests.post() 后只打印 status_code，没有 raise_for_status()，也没有解析飞书业务错误码。
• 影响：webhook 失效、限流、模板变量错误、权限错误时，workflow 仍可能显示成功，但用户收不到消息。
• 建议：对 HTTP 非 2xx 调用 raise_for_status()；记录响应体摘要；解析飞书返回的业务 code；汇总失败 webhook 数量，必要时以非 0 退出。

P2: arXiv HTTP 请求没有 timeout Copy Section

• 位置：paperBotV2/arxiv_daily/arxiv.py 的 get_daily_arxiv_papers()。
• 证据：requests.get(base_url, params=query_params) 未设置 timeout。
• 影响：arXiv API 网络半开或服务长时间无响应时，GitHub Actions 任务可能挂到默认超时，阻塞后续 HTML 部署和飞书通知。
• 建议：设置 timeout=(5, 30)，并配合有限重试；workflow 层增加 timeout-minutes 和 concurrency，避免定时任务堆积。

改进建议 Copy Chapter

必须优先修复 Copy Section

1. 修复前一天去重路径，避免重复论文跨日进入 LLM 和飞书链路。
2. 修复 HTML 转义和 URL 白名单，避免公开页面注入风险。
3. 修复 --output 参数，保证 CLI 行为与帮助说明一致。

建议尽快优化 Copy Section

1. 飞书发送失败应显式失败或至少汇总失败数，避免“workflow 成功但消息没发出”。
2. arXiv API 请求设置 timeout 和 retry，workflow 设置 timeout-minutes 与 concurrency。
3. 将 arxiv.py 内已废弃的 send_papers_to_feishu() 删除或迁移到公共通知模块，避免两个飞书模板版本并存。
4. 对 LLM 返回字段做 schema 校验，缺字段时保留原论文并标记失败原因，而不是静默丢失到成功列表之外。

可暂缓优化 Copy Section

1. save_results_to_json() 当前不会刷新历史全量结果，可后续增加手动 refresh 模式。
2. generate_arxiv_html.py 中大量内联 CSS/JS 可以后续拆回前端资源，降低维护成本。
3. get_latest_json_file() 仅按文件名排序，建议后续对 YYYYMMDD.json 做格式过滤，避免误选非日期 JSON。

验证记录 Copy Chapter

本次 review 使用无线上副作用方式验证，不使用真实 DEEPSEEK_API_KEY、不使用真实 FEISHU_URL、不触发真实飞书发送。

已执行验证 Copy Section

python3 - <<'PY'
import os, py_compile, tempfile
files = [
    'paperBotV2/arxiv_daily/__init__.py',
    'paperBotV2/arxiv_daily/prompts.py',
    'paperBotV2/arxiv_daily/arxiv.py',
    'paperBotV2/arxiv_daily/arxiv_feishu_msg.py',
    'paperBotV2/arxiv_daily/generate_arxiv_html.py',
]
with tempfile.TemporaryDirectory(prefix='arxiv_daily_pycompile_') as td:
    for path in files:
        cfile = os.path.join(td, path.replace('/', '__') + '.pyc')
        py_compile.compile(path, cfile=cfile, doraise=True)
        print(f'OK py_compile {path}')
PY

结果：5 个 arXiv daily Python 文件均可编译。

env -u FEISHU_URL -u DEEPSEEK_API_KEY RETURN_PAPERS=1 PYTHONPATH="$PWD" python3 - <<'PY'
from pathlib import Path
from paperBotV2.arxiv_daily import arxiv, arxiv_feishu_msg, generate_arxiv_html

post_calls = []
def fail_post(*args, **kwargs):
    post_calls.append((args, kwargs))
    raise AssertionError('requests.post should not be called in empty-key smoke')

arxiv.requests.post = fail_post
arxiv_feishu_msg.requests.post = fail_post
assert arxiv.call_deepseek_api('{"ping": true}', api_key='') is None
arxiv.send_papers_to_feishu([{'title':'T','url':'https://www.alphaxiv.org/abs/1','rerank_relevance_score':1,'summary':'S'}], feishu_urls=[])
arxiv_feishu_msg.send_papers_to_feishu([{'title':'T','url':'https://www.alphaxiv.org/abs/1','rerank_relevance_score':1,'summary':'S'}], feishu_urls=[])
arxiv_feishu_msg.main()
script_dir = Path('paperBotV2/arxiv_daily').resolve()
papers = generate_arxiv_html.load_paper_data(script_dir / 'data' / '20260526.json')[:1]
html = generate_arxiv_html.generate_papers_html(papers, str(script_dir / 'frontend'), str(script_dir / 'output' / 'static'))
assert html and '<script id="papers-data"' not in html
assert not post_calls, post_calls
print('OK empty-key smoke')
PY

结果：空 DeepSeek key 会短路；空飞书 URL 不发送；最新 JSON 非当天时飞书主流程退出；HTML 论文列表可只读渲染。

env -u FEISHU_URL -u DEEPSEEK_API_KEY PYTHONPATH="$PWD" python3 - <<'PY'
from pathlib import Path
from paperBotV2.arxiv_daily import generate_arxiv_html, arxiv_feishu_msg
root = Path('paperBotV2/arxiv_daily')
static_dir = root / 'output' / 'static'
malicious = '<img src=x onerror=alert(1)>'
paper = {
    'title': malicious,
    'translation': malicious,
    'summary': malicious,
    'ori_summary': malicious,
    'authors': malicious,
    'reasoning': malicious,
    'categories': ['cs.CL'],
    'url': 'javascript:alert(1)',
    'arxiv_id': '2501.00001',
    'rerank_relevance_score': 9,
    'is_fine_ranked': True,
}
html = generate_arxiv_html.generate_papers_html([paper], str(root / 'frontend'), str(static_dir))
print('HTML_UNESCAPED_PAYLOAD', malicious in html)
print('HTML_JAVASCRIPT_HREF', 'href="javascript:alert(1)"' in html)
PY

结果：HTML_UNESCAPED_PAYLOAD=True，HTML_JAVASCRIPT_HREF=True，确认 HTML 转义风险存在。

未执行验证 Copy Section

• 未运行真实 python -m paperBotV2.arxiv_daily.arxiv 全流程，因为会访问 arXiv、调用 DeepSeek 并写入当天 JSON。
• 未使用真实 FEISHU_URL，避免误发飞书。
• 未在 GitHub Actions Python 3.8 环境中复测，仅在本地 Python 环境完成静态和 smoke 验证。

修复记录 Copy Chapter

截至 2026-05-28，已按本报告的问题清单完成第一轮修复：

• 已修复跨日去重路径：arxiv.py 现在从 paperBotV2/arxiv_daily/data/YYYYMMDD.json 读取前一天数据。
• 已为 arXiv API 请求增加 timeout=(5, 30)，避免外部服务长时间无响应时拖垮 workflow。
• 已为 HTML 模板渲染启用 Jinja2 autoescape，并对分类标签做显式转义。
• 已增加论文 URL 白名单和 fallback；不可信 URL 会回退到 https://arxiv.org/abs/<arxiv_id>。
• 已修复 generate_arxiv_html.py --output ，指定输出目录时可正常生成页面、静态资源目录和 index.html。
• 已增强飞书 webhook 失败处理：HTTP 非 2xx、非 JSON 响应或飞书业务错误会汇总并抛出 RuntimeError。
• 已为 arxiv_daily_full.yml 和 arxiv_feishu_msg.yml 增加 workflow concurrency 与 job timeout-minutes。
• 已增强 arXiv 抓取完整性：抓取窗口改为最近 36 小时，按 ARXIV_PAGE_SIZE 分页抓取到空页或 ARXIV_MAX_PAGES，避免单页 max_results=100 漏论文。
• 已增强 arXiv 限流处理：请求增加 User-Agent，遇到 429/5xx 会按 Retry-After 或指数退避长时间重试；重试耗尽后会让流程失败，避免静默生成 0 篇结果。
• 已将内部 arXiv 重试策略调整为“少次数、长间隔”：单页请求最多 4 轮，默认等待约 10 分钟、20 分钟、40 分钟，最大等待 2400 秒，并增加 0-120 秒随机抖动，避免短时间重复请求无效消耗。
• 已进一步降低 arXiv 限流概率：分页间隔默认 60 秒，分类间隔默认 120 秒，并增加随机抖动，避免 GitHub Actions 固定节奏触发限流。
• 已增加分类级页数上限：cs.IR:5,cs.CL:8,cs.CV:20，低产分类减少不必要请求，高产 cs.CV 保留更大抓取深度。
• 已增加备用 API endpoint：主源 https://export.arxiv.org/api/query 失败时，同一轮会尝试 https://arxiv.org/api/query。
• 已将定时任务从北京时间 12:00 调整到 13:20，避开整点和常见自动任务高峰。
• 已增加同日缓存复用：手动重跑时若当天 JSON 已包含某分类结果，会复用缓存并跳过该分类 arXiv 请求。
• 已关闭额外分类级二次重试：单页请求内部已经使用长间隔退避，分类层不再重复放大等待时间；若某分类最终失败，workflow 会 fail，避免提交空结果。
• 已增加 workflow 外层重试：arxiv.py step 最多执行 3 次，失败后分别等待 30 分钟和 60 分钟再重试；最终失败会保留非 0 退出，阻止后续 HTML 生成、提交、部署和飞书成功触发。
• 已增加运行状态持久化：每次运行会写入 paperBotV2/arxiv_daily/status/YYYYMMDD.json 详细状态，并追加/更新 paperBotV2/arxiv_daily/status/arxiv_daily_runs.csv 汇总表，记录抓取、粗排、精排、平均分、输出和错误信息。
• 已增加晚间 recovery workflow：北京时间 18:05 检查当天状态，只有状态缺失、失败、抓取未成功、JSON 未写入或 HTML 未生成时才补跑；成功则直接跳过。
• 已扩展飞书触发条件：arxiv_feishu_msg.yml 同时监听 arxiv_daily_full 和 arxiv_daily_recovery，确保晚间补跑成功后也会发送当天 Top20 飞书消息。
• 已增加 PYTHONUNBUFFERED=1：GitHub Actions 长抓取阶段会实时输出日志，避免看起来像卡住。
• 已在 requirements.txt 约束 urllib3<2：避免 macOS 系统 Python + LibreSSL 环境出现 NotOpenSSLWarning。

修复验证采用无线上副作用方式完成：

• py_compile 通过：arxiv.py、generate_arxiv_html.py、arxiv_feishu_msg.py。
• YAML 和 shell 语法解析通过：arxiv_daily_full.yml、arxiv_daily_recovery.yml、arxiv_feishu_msg.yml。
• 静态检查通过：确认 requests.get(..., timeout=(5, 30)) 和 data/YYYYMMDD.json 去重路径存在。
• HTML 恶意样本验证通过：`` 被转义，javascript: URL 不会进入 href。
• --output 验证通过：临时目录中成功生成 arxiv_20260526.html、static/templates/ 和 index.html。
• 飞书 mock 验证通过：成功响应不抛错，HTTP 500 与业务错误码均会抛出 RuntimeError，空 URL 仍跳过发送。
• arXiv 抓取 mock 验证通过：429 会等待后重试，分页会继续抓取后续页面，并在空页停止。
• arXiv 慢抓策略验证通过：分类级页数、备用 endpoint、分页/分类间隔和随机抖动配置均可被代码和 workflow 读取。
• arXiv 缓存与分类重试 mock 验证通过：今日缓存存在时跳过请求，分类失败会单独等待后重试。
• 真实 arXiv 抓取层 smoke 验证通过：只请求 arXiv API，不进入 DeepSeek、不写 JSON/HTML、不发飞书。
• 状态持久化临时目录验证通过：JSON/CSV 写入、HTML 状态回写和 recovery 判断逻辑均符合预期。
• git diff --check 通过。

后续优化路线 Copy Chapter

首轮修复已覆盖本报告中的 5 个主要问题。后续可继续做以下增强：

1. 为去重路径、HTML 转义、URL 白名单、--output 和飞书失败处理补充正式单元测试。
2. 为 arXiv 请求增加分类级失败统计和抓取数量趋势监控。
3. 清理 arxiv.py 内废弃飞书函数，统一通知逻辑到 arxiv_feishu_msg.py 或公共模块。
4. 增加 DRY_RUN 或 --dry-run 参数，方便在 CI 和本地做无副作用验证。
5. 后续在 GitHub Actions Python 3.8 环境中手动触发一次 workflow，验证真实 secrets、Pages 部署和飞书模板兼容性。

Paperbotv2 Arxiv Html Ui Review (`docs/paperbotv2-arxiv-html-ui-review.md`) Copy Section

PaperBotV2 arXiv HTML UI Review

结论摘要 Copy Chapter

本次 review 聚焦 paperBotV2/arxiv_daily/generate_arxiv_html.py 及其生成的 arXiv 每日 HTML 页面。当前链路已经具备每日论文展示、精选优先、普通论文折叠、低分论文隐藏、摘要详情、统计卡片、日期日历和静态资源 fallback 等能力，且输出路径支持 --output，可以用临时目录做无副作用验证。

主要风险集中在前端状态与后端注入逻辑交错：日历会被过期 localStorage 影响，筛选和折叠逻辑分散在 app.js 与内联脚本中，低分论文分割线位置不符合文案语义，部分空值 fallback 与评分展示仍有体验问题。建议优先修正日历选中态和交互职责边界，再逐步补充搜索、筛选、历史浏览和阅读状态能力。

当前逻辑梳理 Copy Chapter

输入与数据转换 Copy Section

• main() 从 paperBotV2/arxiv_daily/data/ 读取指定 --date 的 YYYYMMDD.json，未指定时按文件名倒序选择最新 JSON。
• get_latest_json_file() 排除 results.json，直接按文件名排序选最新文件；get_json_file_by_date() 只接受 YYYYMMDD。
• load_paper_data() 将 JSON 字典转换为论文列表，并向每个 paper_info 原地写入 arxiv_id。
• generate_html() 统计总论文数、精选论文数和平均分；精选判断使用 is_fine_ranked，评分优先 rerank_relevance_score，否则 relevance_score。
• generate_papers_html() 先按精选优先排序，再按评分降序排序；精选论文使用 selected_paper_template.html，普通论文使用 normal_paper_template.html。

模板渲染与展示 Copy Section

• 模板渲染使用 Jinja2 Environment 和默认 autoescape，正文、标题、作者、摘要等文本会被转义。
• URL 只允许 http/https 且 host 属于 arXiv 白名单，路径必须以 /abs/、/pdf/ 或 /html/ 开头，异常 URL 回退到 https://arxiv.org/abs/{arxiv_id} 或 https://arxiv.org。
• 分类标签由 build_category_tags() 生成，分类文本逐项转义后以 Markup 注入模板。
• 作者超过 MAX_AUTHORS_DISPLAY_LENGTH 后截断，标题优先展示 translation，摘要优先 abstract，原始摘要优先 ori_summary。
• summary 非空时展示“核心总结”；推荐理由优先 rerank_reasoning，否则 reasoning，默认值为“无”。

静态资源与输出 Copy Section

• 默认输出为 paperBotV2/arxiv_daily/output/arxiv_YYYYMMDD.html，指定 --output 时会以输出文件所在目录作为临时 output_dir。
• 若 frontend/ 存在则复制其中 styles.css、tailwind.config.js、app.js、index.html 和模板；当前仓库主要使用 output/static/ 作为 fallback 来源。
• 输出页面中的 ../frontend/styles.css、../frontend/tailwind.config.js、../frontend/app.js 会被改写为 static/...。
• 每次生成具体日期 HTML 后，会在同一输出目录写入 index.html，通过 meta refresh 指向 arxiv_YYYYMMDD.html。

日历逻辑 Copy Section

• 后端扫描 script_dir/data/*.json，注入 availableDates 数组，过滤 results.json 和非 YYYYMMDD.json 文件。
• 前端从 #current-date 文本解析当前日期，初始化 displayYear 和 displayMonth。
• 日历按钮控制 #date-picker 的 hidden class，支持上月和下月切换。
• 有数据日期可点击，点击后写入 localStorage.selectedDate/selectedYear/selectedMonth，并跳转到 arxiv_YYYYMMDD.html。
• 无数据日期置灰不可点击；当天日期使用 bg-primary 高亮，选中日期使用边框和阴影高亮。

页面交互 Copy Section

• 精选论文默认完全展开，普通论文按评分分为 collapsed-level-1 和 collapsed-level-2。
• collapsed-level-1 只隐藏 .paper-details，标题仍可见；collapsed-level-2 整卡默认隐藏。
• 内联 collapse_js 会插入“展开/折叠全部非精选论文”按钮，给普通论文标题加眼睛图标，并处理“全部论文/仅显示精选”的实际过滤。
• app.js 也绑定了 show-all 和 show-selected，但只更新按钮样式；摘要详情主要依赖原生 ``。

问题清单 Copy Chapter

功能与体验改进 Copy Chapter

近期可做 Copy Section

中期增强 Copy Section

远期探索 Copy Section

验证记录 Copy Chapter

验证均使用本地命令和临时目录完成，不触发 DeepSeek、不发送飞书、不依赖生产 secrets、不覆盖线上 JSON/HTML 输出。

修复记录 Copy Chapter

本轮已按报告中的高优先级问题修复，并回溯重生成历史 HTML。

后续建议 Copy Chapter

1. 下一步建议将筛选、折叠和日历逻辑继续迁移到静态 app.js，后端只注入结构化 JSON 配置，减少 Python 拼接大段 JS。
2. 为 load_paper_data()、sanitize_url()、generate_html(--output)、availableDates 注入和模板 fallback 增加正式单元测试。
3. 近期产品增强优先做搜索、分类筛选、分数筛选和最近有数据日期列表，收益明确且不依赖线上服务。
4. 中期可评估阅读状态、收藏、导出 Markdown/BibTeX 和跨日 Top 论文入口。

Paperbotv2 Refactor Report (`docs/paperbotv2-refactor-report.md`) Copy Section

PaperBotV2 项目梳理与重构报告

结论摘要 Copy Chapter

本仓库从“搜广推工业实践文章收集”起步，随后扩展出 arXiv 每日论文推送、顶会论文汇总、行业实践网页和 GitHub Actions 自动化。当前代码同时保留顶层旧脚本和 paperBotV2/ 新结构，维护边界不清晰。

综合 README、脚本目录和工作流调用关系，当前主线应以 paperBotV2 为准：arXiv 每日处理、HTML 页面生成、飞书消息补发和行业实践页面更新均已迁入 paperBotV2；README 中顶会论文列表也指向 paperBotV2/conf_summary/data/papers/。但部分 GitHub Actions 仍会调用顶层旧脚本，说明旧代码尚未完全下线，后续重构需要分阶段迁移和验证，不能直接删除。

实施基础状态 Copy Chapter

Task 1 已从 main...origin/main 创建并切换到 refactor/paperbotv2-safe-migration 分支。创建前的 git status --short --branch 显示存在未跟踪的 .trae/ 与 docs/，本次只记录状态并保留这些现有改动，不执行清理、重置或覆盖操作。

本次安全迁移的计划修改范围限定为 GitHub Actions 入口、legacy/ 归档目录、实施报告和必要的最小验证记录。线上无损原则是：旧脚本只做目录级归档、不修改脚本内容，不删除历史数据，不改变已生效的 paperBotV2 输出目录，不触发真实线上 webhook，不让 README 顶会链接回退到顶层 papers/。

实施状态更新 Copy Section

截至 2026-05-28，Task 2 和 Task 3 已完成可安全迁移部分：旧 arXiv 手动工作流已归档到 legacy/workflows/，线上只保留 arxiv_daily_full.yml 与 arxiv_feishu_msg.yml；update_confs.yml 已迁移到 paperBotV2/conf_summary 链路；push_conf_daily.yml 因新版尚未完全替代旧飞书日推和私有 CONF_URL 摘要补全能力，暂时保留 legacy/conf.py 兼容调用，但已停止运行会把 README 链接回退到顶层 papers/ 的旧 legacy/render.py。

Task 4 已调整完成：顶层旧脚本不再通过修改源文件添加提示，而是以原始内容归档到 legacy/ 目录；README.md 已补充 legacy 入口说明，明确当前主线入口为 paperBotV2/arxiv_daily/、paperBotV2/conf_summary/ 和 paperBotV2/industry_practice/。本次未删除顶层历史数据文件或 papers/ 历史产物，保留回滚与复核能力。

仓库功能全景 Copy Chapter

主要功能 Copy Section

顶层目录与文件 Copy Section

顶层旧脚本 Copy Section

PaperBotV2 模块盘点 Copy Chapter

`paperBotV2/arxiv_daily` Copy Section

arxiv.py 是新版 arXiv 主处理入口。它从环境变量读取 TARGET_CATEGORYS、MAX_PAPERS、ROUGH_SCORE_THRESHOLD、RETURN_PAPERS、DEEPSEEK_API_KEY 和 FEISHU_URL，按分类查询 arXiv API，使用 DeepSeek 做粗排和精排，并将结果写入 paperBotV2/arxiv_daily/data/YYYYMMDD.json 与 paperBotV2/arxiv_daily/data/results.json。

generate_arxiv_html.py 读取 JSON 数据和静态模板，生成日级 HTML 与索引页面，输出到 paperBotV2/arxiv_daily/output/。输出目录含 static/、模板、样式与历史日级页面，是 GitHub Pages 发布源。

arxiv_feishu_msg.py 从 data/ 中选择最新日级 JSON，校验日期为当天后，根据精排分数选取论文并发送飞书消息。它将“数据处理/网页生成”和“消息发送”拆成两个自动化阶段，避免页面未部署时提前推送。

prompts.py 保存粗排和精排提示词，是新版筛选逻辑的核心配置文件。

`paperBotV2/conf_summary` Copy Section

crawler.py 从 DBLP 按会议和年份抓取论文列表，当前字段更贴近推荐展示：论文名、链接、作者、摘要、作者机构、标题翻译、推荐分和推荐理由。相比顶层 crawler.py，新版支持 nips/neurips 路径、重试、随机延迟和更丰富的会议范围。

get_free_abstract.py 面向 ACL/NAACL/EMNLP/ICLR 等开放页面补全摘要，支持按会议模式和数量限制筛选空摘要论文，是对旧 conf.py 中通过私有 CONF_URL 补摘要方式的替代方向。

convert_to_md.py 将 data/results.json 转成 data/papers/<conf>/<conf><year>.md，生成包含序号、标题、推荐理由、推荐度、摘要、作者、组织的 Markdown 表格，并对部分会议摘要做动态截断，控制文件大小。

update_readme_papers.py 扫描 data/papers/，重建 README 的顶会论文矩阵。README 当前顶会链接已经指向该目录，说明展示层已向 paperBotV2 靠拢。

`paperBotV2/industry_practice` Copy Section

maintain.py 是当前行业实践 Issue 入口。它解析 Issue 文章元数据，更新 data/article.json 和 data/article.csv，向 README 的行业实践表插入新文章，发送飞书通知，并调用 generate_industry_html.py 刷新网页。

generate_industry_html.py 读取 data/article.json，转换中英文键名，按日期倒序排序，生成公司和标签筛选数据，再基于 Jinja2 模板输出 paperBotV2/industry_practice/output/index.html。该输出目录被 update_content.yml 部署到 GitHub Pages 的 industry_practice/。

data/ 是结构化文章数据源，output/ 是网页产物。相比顶层 maintain.py 依赖 source.xlsx，新版更适合自动化和网页化。

GitHub Actions 调用关系 Copy Chapter

自动化证据表明：arXiv 日常计划任务、arXiv 飞书后置通知、行业实践 Pages 部署和顶会 Issue 更新已经是 paperBotV2 路径；旧 arXiv 手动工作流已归档到 legacy/workflows/，不再作为线上可触发 workflow。会议日推送 push_conf_daily.yml 仍保留 legacy/conf.py 兼容调用，是后续需要补齐新版飞书日推能力后再完全迁移的遗留入口。

新旧代码关系 Copy Chapter

arXiv 路径 Copy Section

旧 arxiv.py 以单分类查询、摘要翻译、飞书推送为中心，数据缓存写入顶层 arxiv.json。两个旧手动 workflow 已归档到 legacy/workflows/，不再位于 .github/workflows/ 线上触发目录；当前线上 arXiv 主入口保留 arxiv_daily_full.yml 和 arxiv_feishu_msg.yml。

新版 paperBotV2/arxiv_daily/arxiv.py 支持 cs.IR,cs.CL,cs.CV 等多分类，使用 DeepSeek 对论文做相关性粗排和摘要精排，输出日级 JSON 和全量 JSON，再由 generate_arxiv_html.py 发布页面，由 arxiv_feishu_msg.py 发送消息。它是当前自动日更和页面发布的实际生效路径。

结论：旧 arXiv 脚本属于兼容遗留代码，已以原始内容归档到 legacy/，README 标注当前主线。后续可在确认无人工依赖后删除归档副本。

会议论文路径 Copy Section

旧会议路径由 legacy/update.py、legacy/crawler.py、legacy/citer.py、legacy/conf.py、legacy/render.py 和顶层 results.json/papers/ 组成，侧重 DBLP 抓取、Crossref 引用数、私有摘要接口和 README 表格更新。Task 3 后，update_confs.yml 已迁入 paperBotV2/conf_summary；push_conf_daily.yml 暂保留 legacy/conf.py 用于旧飞书日推兼容，但不再调用会重写 README 的 legacy/render.py。

新版 paperBotV2/conf_summary 已具备 DBLP 抓取、开放摘要补全、Markdown 转换和 README 表格更新能力，README 顶会链接也已转向 paperBotV2/conf_summary/data/papers/。

结论：会议模块处于“Issue 更新和展示产物已迁入 paperBotV2，日推通知仍保留旧兼容脚本”的过渡态。下一步应补齐 paperBotV2/conf_summary 的飞书日推替代能力，再移除 push_conf_daily.yml 对 legacy/conf.py 的依赖。

行业实践路径 Copy Section

旧 legacy/maintain.py 依赖 source.xlsx，直接插入 README 表格并推送飞书。当前工作流没有调用该归档脚本。

新版 paperBotV2/industry_practice/maintain.py 以 article.json/article.csv 为结构化数据源，仍更新 README，同时生成 HTML 页面并部署 Pages。update_content.yml 已调用新版入口。

结论：行业实践模块已基本迁移完成，legacy/maintain.py 与 source.xlsx 可作为历史数据和回滚资产暂存，后续确认后删除归档副本或归档旧数据。

当前实际生效路径 Copy Chapter

当前应按以下路径理解仓库主线：

1. arXiv 日常任务：arxiv_daily_full.yml 调用 paperBotV2/arxiv_daily/arxiv.py 生成 JSON，再调用 paperBotV2/arxiv_daily/generate_arxiv_html.py 生成页面并部署。
2. arXiv 飞书通知：arxiv_feishu_msg.yml 在 arxiv_daily_full 成功后调用 paperBotV2/arxiv_daily/arxiv_feishu_msg.py。
3. 行业实践更新：update_content.yml 调用 paperBotV2/industry_practice/maintain.py，该脚本会更新数据、README、飞书消息和 HTML 页面。
4. 顶会展示：README 链接已指向 paperBotV2/conf_summary/data/papers/，说明展示产物以 paperBotV2 为准。
5. 顶会更新入口：update_confs.yml 已调用 paperBotV2/conf_summary/update_from_issue.py、convert_to_md.py 和 update_readme_papers.py；push_conf_daily.yml 暂时保留 legacy/conf.py 作为旧飞书日推兼容入口，但输出转换和 README 更新已使用 paperBotV2/conf_summary。

遗留风险 Copy Chapter

重构升级方案 Copy Chapter

代码分类 Copy Section

分阶段计划 Copy Section

第一阶段：文档与冻结。

将顶层旧脚本以原始内容移动到 legacy/，补充 README 或 docs/ 入口说明，明确 paperBotV2 是主线。禁止新功能继续写入顶层 arxiv.json、results.json 和 papers/。将旧手动工作流名称或描述改为 deprecated，避免误触发。

第二阶段：迁移会议自动化。

update_confs.yml 已迁移为 paperBotV2/conf_summary/update_from_issue.py、convert_to_md.py 和 update_readme_papers.py 链路，输出保持在 paperBotV2/conf_summary/data/。push_conf_daily.yml 暂时保留 legacy/conf.py 用于日推兼容，但已改用 paperBotV2/conf_summary 生成 Markdown 和 README，避免链接回退到顶层 papers/。

第三阶段：统一 arXiv 与行业实践入口。

push_arxiv_daily.yml、push_arxiv_daily_cl.yml 已移出 .github/workflows/ 并归档到 legacy/workflows/。线上 arXiv 入口仅保留 arxiv_daily_full.yml 和 arxiv_feishu_msg.yml；行业实践继续以 paperBotV2/industry_practice/maintain.py 为主入口。

第四阶段：数据归档与兼容窗口。

对顶层历史数据做一次只读归档，记录最新迁移日期、数据来源和是否仍被 README 引用。保留一个发布周期的回滚分支或 tag，确认 Pages、README 和飞书无异常后移除旧脚本。

第五阶段：清理依赖和质量提升。

统一 Python 包结构，补齐 paperBotV2 根包初始化，抽取通用飞书发送、日期处理、文件路径和 LLM 客户端。升级 GitHub Actions 的 checkout/setup-python 版本，替换废弃的 ::set-output。

验证清单 Copy Chapter

Task 5 最小化验证记录 Copy Section

验证日期：2026-05-28。本次只做本地静态检查、依赖安装后的导入/编译检查和空密钥分支验证，未使用真实 webhook 或生产密钥，未触发 GitHub Actions、Pages 发布、arXiv/DeepSeek 线上抓取或飞书真实发送。

残余风险：

• push_conf_daily.yml 仍保留对 legacy/conf.py 的兼容调用，虽然后续 Markdown/README 已转向 paperBotV2/conf_summary，但日推入口仍可能写入顶层会议中间数据。
• 本次未真实运行 GitHub Actions、Pages 发布、arXiv 抓取、DeepSeek 调用或飞书 webhook，仅覆盖静态和最小化本地分支。
• 本地为 Python 3.9，workflow 配置为 Python 3.8；依赖安装和导入在本机通过，但仍建议在 CI 的 Python 3.8 环境复核。
• 导入时出现 urllib3 关于 LibreSSL 的 NotOpenSSLWarning，未阻断验证，但线上运行环境如升级 urllib3/OpenSSL 仍需关注。
• paperBotV2/conf_summary/convert_to_md.py 含顶层文件读取/写入逻辑，本次仅做 py_compile，未在真实 data/results.json 输入上执行转换。

Legacy 目录归档调整记录 Copy Section

按“冻结旧脚本不用改动源文件，直接放进 legacy/ 文件夹”的要求，已撤销脚本头部 LEGACY NOTICE 方案，改为将 8 个旧脚本以 HEAD 中原始内容归档到 legacy/：arxiv.py、conf.py、crawler.py、citer.py、render.py、update.py、maintain.py、translate.py。顶层同名脚本已移除，push_conf_daily.yml 的兼容调用改为 python legacy/conf.py。

补充验证结果：missing_legacy=[]、still_top=[]、legacy_notice=[]；7 个 workflow YAML 均可解析；legacy/conf.py、legacy/translate.py、paperBotV2/conf_summary/update_from_issue.py 均通过 py_compile。

Legacy Workflow 归档调整记录 Copy Section

按“已有 arxiv_daily_full.yml，其他 arXiv workflow 也变成 legacy”的要求，已将 .github/workflows/push_arxiv_daily.yml 与 .github/workflows/push_arxiv_daily_cl.yml 移动到 legacy/workflows/。线上 .github/workflows/ 中当前仅保留两个 arXiv 相关 workflow：arxiv_daily_full.yml 和 arxiv_feishu_msg.yml。

补充验证结果：active_arxiv_workflows=['arxiv_daily_full.yml', 'arxiv_feishu_msg.yml']；legacy_workflows=['push_arxiv_daily.yml', 'push_arxiv_daily_cl.yml']；线上 5 个 workflow YAML 与 legacy 下 2 个归档 YAML 均可解析。

全量命令复测记录 Copy Section

按“所有改动都测试跑一次，包括之前老的 YAML 命令”的要求，已完成无线上副作用复测：

• 当前 .github/workflows/ 下 5 个 workflow 和 legacy/workflows/ 下 2 个归档 workflow 均通过 YAML 解析。
• 所有项目 Python 脚本均通过 py_compile，共 22 个脚本。
• python -m paperBotV2.arxiv_daily.arxiv 使用 MAX_PAPERS=0、空 DEEPSEEK_API_KEY、空 FEISHU_URL 完成 smoke test；未写入新 JSON。
• paperBotV2/arxiv_daily/generate_arxiv_html.py 可执行；测试生成的 HTML 时间戳副作用已恢复。
• paperBotV2/arxiv_daily/arxiv_feishu_msg.py 在无 webhook 且最新数据非当天时正确退出，未发送飞书。
• paperBotV2/conf_summary/conf_daily.py 使用临时 results JSON 和 DRY_RUN=true 通过，不请求 CONF_URL、不写生产数据、不发送飞书。
• paperBotV2/conf_summary/convert_to_md.py 使用临时有效 results JSON 通过，并生成测试 Markdown。
• paperBotV2/conf_summary/update_from_issue.py --help 通过。
• paperBotV2/industry_practice/maintain.py 的 issue parser 通过，generate_industry_html.py 可执行；测试生成的 HTML 时间戳副作用已恢复。
• git diff --check 通过，GetDiagnostics 无诊断问题。

本机环境没有 git-lfs，因此 paperBotV2/conf_summary/data/results.json 在本地仍是 LFS pointer，不能直接对真实大文件运行 convert_to_md.py。已在所有 active workflow 的 actions/checkout 中设置 lfs: true，确保 GitHub Actions 环境拉取真实 LFS 内容后再执行会议链路。

后续实施建议 Copy Chapter

后续优先处理 push_conf_daily.yml 对 legacy/conf.py 的兼容依赖，因为它仍可能写入顶层会议数据。旧 arXiv 手动 workflow 已归档，update_confs.yml 已转向 paperBotV2，下一阶段应补齐真实 CI 验证记录，再归档旧数据，避免在自动化入口尚未完全替换前破坏回滚能力。

每次迁移只改一个自动化入口，并在 PR 中附上运行日志、关键产物 diff 和 README 链接检查结果。若需要保留人工兼容入口，建议将旧脚本改成薄 wrapper，只打印迁移提示并转调 paperBotV2，而不是继续维护两套逻辑。

--- METRICS ---

• Files Extracted: 4
• Estimated Token Budget: ~48541 tokens
• Canonical Reference: https://codewiki.google/github.com/Doragd/Algorithm-Practice-in-Industry