ThesisAgent

# ThesisAgents [](https://github.com/Integration-Automation/ThesisAgents/actions/workflows/ci.yml) [](https://github.com/Integration-Automation/ThesisAgents/actions/workflows/release.yml) [](https://pypi.org/project/thesisagents/) [](https://pypi.org/project/thesisagents/) [](https://github.com/Integration-Automation/ThesisAgents/blob/main/LICENSE) [](https://thesisagents.readthedocs.io/en/latest/) > **语言**: [繁體中文](readmes/README.zh-TW.md) · [简体中文](readmes/README.zh-CN.md) · [日本語](readmes/README.ja.md) · [Español](readmes/README.es.md) · [Français](readmes/README.fr.md) · [Deutsch](readmes/README.de.md) · [한국어](readmes/README.ko.md) · [Português](readmes/README.pt.md) · [Русский](readmes/README.ru.md) · [Italiano](readmes/README.it.md) · [Tiếng Việt](readmes/README.vi.md) · [हिन्दी](readmes/README.hi.md) · [Bahasa Indonesia](readmes/README.id.md) > **文档**: [thesisagents.readthedocs.io](https://thesisagents.readthedocs.io/en/latest/) 一款基于关键词驱动的论文搜索助手，从 arXiv、Semantic Scholar、OpenAlex、PubMed、ACM（通过 Crossref）、IEEE Xplore、DBLP、generic Crossref、OpenAIRE、Springer Nature、Europe PMC、DOAJ、HAL、CORE 和 Google Scholar 等来源获取结果，对结果进行标准化，并导出为**毕业论文样式的 PowerPoint 演示文稿**、**Excel 工作簿**和 **BibTeX 文件** —— 所有这些都可以通过一次 CLI 调用或一次 MCP 工具调用完成。或者，通过读取论文的 PDF 并生成结构化的每篇论文摘要来丰富每篇论文，摘要格式可以是上下文（LLM-as-agent 流程）或通过 Anthropic API（Python 管道流程）。 ## 适用于驱动该项目的 AI 代理 **如果您是阅读本 README 以确定操作流程的 LLM（Claude Code、Cursor、Aider、Codex CLI 等）—— 请从这里开始。** 以下所有内容也都固定在 [`AGENTS.md`](AGENTS.md) （跨代理镜像）和 [`CLAUDE.md`](CLAUDE.md) （规范参考）中；请在进行非琐碎更改之前阅读它们。 ### 用户实际想要的 默认交付成果是**每篇论文的毕业论文样式的富 `.pptx`**，而不是 CLI 默认生成的轻量级仅摘要的演示文稿。轻量级生成是中间产物 —— 您的任务是升级它。 ### 决策树 1. 环境中是否设置了 `ANTHROPIC_API_KEY`？ → 直接运行 CLI；它通过 Anthropic API 自动丰富。您完成了。 2. 没有密钥，但您（一个 LLM）正在驱动会话 → **您自己生成富摘要**。阅读每篇论文的 PDF，手工编写一个包含富字段的 `PaperSummary`（`pain_points`、`research_question`、`contributions_detailed`、`headline_metrics`、`technique_table`、`method_sections`、`evaluation_sections`、`system_flow`、`research_questions`、`rq_results`、`core_observation`、`limitations`、`future_work`），然后运行一个 `scripts/regen_<query>.py` 脚本。**不要告诉用户设置 API 密钥** —— 您是会编写摘要的 LLM。 3. 没有 LLM 参与（CI / cron / 无人值守）→ 轻量级是可接受的。 ### 6 步 MCP 工作流程 ``` 1. （可选）list_sources() # 查看哪些插件已启用 2. search(keywords, sources, top_tier_only=true, ...) 3. （可选）download_pdfs(papers, out_dir="./exports/...") 4. fetch_pdf_text(pdf_url=paper.pdf_url) # 每篇论文 5. （您阅读每篇论文的 PDF 并生成结构化的摘要字典） 6. export(papers=[{...paper, "summary": {...}}], language="zh-tw", ...) ``` 所有十三個 MCP 工具（包括 `list_sources`、`list_exports`、`download_pdfs`、`pptx_inspect` / `pptx_review` / `pptx_update_slide` / `pptx_add_slide` 等等）都在 [`docs/mcp.md`](docs/mcp.md) 中有文档。 ### 必需：发货前验证 URL / DOI 发布者 URL 路径**不能被猜测** —— AAAI 使用数字 ID（`v40i5.37389`），IEEE 使用不透明的 `arnumber`，ACM 使用不透明的 DOI。当您手工编写一篇 `Paper`时，**请逐字复制 `url` / `doi` / `arxiv_id` 从生成此运行的搜索 xlsx 中** —— 永远不要从记忆中，永远不要从标题中构造。 xlsx 被写入 `exports/<run>/<slug>-<timestamp>.xlsx`，列 7 = DOI，列 8 = URL。在您完成时，请审核您的再生脚本： ```python from openpyxl import load_workbook from scripts.regen_<run> import ALL_PAPERS real = {sh.cell(row=r, column=2).value: sh.cell(row=r, column=8).value for sh in [load_workbook("exports/<run>/<slug>-<ts>.xlsx")["Papers"]] for r in range(2, sh.max_row + 1)} for p in ALL_PAPERS: actual = next((u for t, u in real.items() if p.title[:30] in (t or "")), None) if actual and not (p.url == actual or p.url.split("v")[0] == actual.split("v")[0]): print(f"! {p.bibtex_key()} authored {p.url} vs real {actual}") ``` 这种方式捕获了两个生产中的伪造：错误的 AAAI 卷（`v39i23.34521` vs 真实 `v39i22.34537`）和构造的作者-slug 路径（`view/fang2026` 而不是 `v40i5.37389`）。 ### 必需：在发货前修剪无关下载 搜索关键词匹配是基于关键词的，因此非主题论文会混入：一个“Claude 代码”查询返回了一篇 Viterbi 解码器论文，因为两者都包含“代码”；“LLM 代码审查”匹配了一篇目标检测文献综述。一旦您阅读摘要并将论文分类为非主题，请修剪运行目录： ```python from pathlib import Path run = Path("exports/<run>") irrelevant_keys = ("key-of-off-topic-paper-1", "key-of-off-topic-paper-2") for key in irrelevant_keys: for path in (run / "pdfs" / f"{key}.pdf", run / f"{key}.pptx"): if path.exists(): path.unlink() ``` 删除 `exports/<run>/pdfs/<key>.pdf` + `exports/<run>/<key>.pptx`。**保留**聚合的 `<slug>-<timestamp>.xlsx` / `.bib` —— 它们是搜索返回内容的诚实记录。边缘情况会得到丰富的摘要；最好包含比沉默丢弃可能的匹配项。 ### 工作示例 [`scripts/regen_llm_security_batch.py`](scripts/regen_llm_security_batch.py) 提供了 8 个手工编写的丰富摘要，这些摘要正是这样生成的。将它用作任何多论文搜索的模板。zh-tw 配套脚本位于 [`scripts/regen_llm_security_batch_zh_tw.py`](scripts/regen_llm_security_batch_zh_tw.py)。 ### 禁止事项 - **不要** 在多论文搜索结束时告诉用户“设置 `ANTHROPIC_API_KEY` 以获取丰富的演示文稿” —— 您是能编写摘要的 LLM。 - **不要** 将每篇论文的轻量级 `.pptx` 当作交付成果。 - **不要** 在 `download_pdfs` 报告 N 个 PDF 保存后停止 —— 这是丰富创作阶段的开始，而不是结束。 - **不要** 编造论文中没有的数字、研究问题、贡献或局限性。 - **不要** 伪造 URL / DOI / arXiv ID —— 请参阅上面的规则。 - **不要** 在运行目录中留下无关下载。关键词搜索匹配可以包括非主题论文（一个“Claude 代码”查询拉入了一篇 Viterbi 解码器论文；“LLM 代码审查”拉入了一篇目标检测文献综述）。在分类论文为非主题后，请删除它们的 `pdfs/<key>.pdf` 和轻量级 `<key>.pptx`；保留聚合的 xlsx / bib 作为搜索返回内容的诚实记录。 - **不要** 在提交消息、PR 描述、代码注释或文档中提及“Claude”、“Claude Code”、“AI-generated”、“GPT”、“Copilot”或任何 AI 工具/模型名称。 ## 功能 - **十五个可插拔的源**：`arxiv`、`semantic_scholar`、`openalex`、`pubmed`、`acm`（Crossref 范围内）、`dblp`、`crossref`（无范围）、`openaire`、`springer`（需要 API 密钥）、`europepmc`（开放，无密钥 —— 生命科学 + 预印本 + 农业）、`doaj`（开放，无密钥 —— 开放获取期刊，通常具有直接的 PDF 链接）、`hal`（开放，无密钥 —— 法国的 CS / 数学 / 物理档案，具有全文 PDF）、`core`（需要免费 API 密钥 —— 最大开放获取聚合器，250M+ 篇作品）、`ieee`（通过可见的 Chrome 默认启用；API 密钥添加官方 Xplore API）、`scholar`（通过可见的 Chrome 默认启用）。每个都位于 `sources/<name>/` 后面，并带有 `Fetcher` 适配器。顶级会议/期刊白名单默认过滤结果为旗舰 CS 会议/期刊以及 Nature/Science/PNAS；传递 `--all-venues` 以禁用。 - **单论文模式**：粘贴 arXiv ID、arXiv URL、DOI、PMID 或 IEEE 文档 URL —— ThesisAgents 通过正确的源解析它并发出相同的导出包。适用于论文阅读笔记和毕业论文答辩准备。 - **本地 PDF 模式**（`--pdf <path>`）：传递一个 PDF 或一个目录。启发式提取器直接从每个 PDF 的前几页中提取**标题、作者、年份、arXiv ID、DOI 和实际摘要**（锚定在明确的 `Abstract` / `ABSTRACT` / `摘要` 标题上，而不是盲目前缀）。 `--title` / `--authors` / `--year` / `--venue` / `--doi` / `--arxiv-id` 在单个 PDF 调用上重写；在目录上，每个文件的提取优先，因此每篇论文都获得以其 BibTeX 键命名的自己的演示文稿。 - **八个导出器**： - `.pptx` —— 16:9 宽屏，分页，三个渲染层级（轻量级仅摘要 · 丰富扁平 · **毕业论文样式**，带有痛点象限、KPI 调用、技术比较表、每个 RQ 结果表、贡献摘要、核心观察、局限性和未来工作、问答、参考文献）。所有模板字符串都已国际化，支持 **14 种语言**：英语、繁體中文、简体中文、日語、西班牙语、法语、德语、韩语、葡萄牙语、俄语、意大利语、越南语、印地语、印度尼西亚语。 - **设计后的视觉识别**（不是默认的 Calibri-on-white 外观）：每种语言的排版（拉丁语使用 Inter，CJK + 印地语使用 Microsoft JhengHei UI / YaHei UI / Yu Gothic UI / Malgun Gothic / Nirmala UI）、程序化强调几何（每张幻灯片顶部强调条 + 封面左侧条带）、学术风格的表格格式（默认网格剥离、深蓝色标题规则、软行间分隔符、交替行条纹、垂直居中、粗体行标签），以及五色调色板学科（深蓝色 / 青色 / 灰色 / 浅色 / 白色），红色 **禁止**用于文本（改为使用粗体 + 青色 `#0E7490` 进行强调）。 - **暗色模式是默认渲染路径**。在浅色调色板上构建运行，然后在构建后将文本 + 填充 + 单元格边框 RGB 值交换为暗色调色板（幻灯片背景 `#12151B`，正文文本 `#E5E7EB`，强调青色交换为更亮的 `#2DD4BF`）。OLED 投影仪和低光照场地无需作者思考即可获得暗色调色板；传递 `--light-mode`（CLI），取消选中 **Light mode**（GUI 选项卡 Deck），或 `ExportOptions(dark_mode=False)`（编程）以选择退出适用于光线充足的投影仪或印刷讲义。 - `.xlsx` —— 论文表格 + 查询来源表格，超链接 URL / PDF，冻结标题，自动列宽。列 5（**来源**）显示实际的出版场地（例如“IEEE Access”）；列 6（**索引通过**）显示哪个获取者返回了元数据（例如“openalex”），因此这两个信息永远不会冲突。 - `.md` —— 完整的源 / 标题 / 摘要列表。 - `.bib` —— 无冲突的引用键，LaTeX 转义字段。 - `.json` —— 下游工具的原始有效载体。 - `.ris` —— RIS 交换导入到 Zotero / Mendeley / EndNote / RefWorks（非 LaTeX 参考管理器的 BibTeX 兄弟）。 - `.csv` —— 用于电子表格 / 快速 grep 分类（RFC-4180 引用，因此标题中的逗号永远不会改变列）的扁平每论文表格。 - `.csl.json` —— CSL-JSON 用于 Pandoc / citeproc；以任何 CSL 样式（APA、IEEE、Nature、……）渲染书目。`.csl.json` 扩展名使其与纯 `.json` 转储区分开来。 - **PPT 编辑工具包**：`thesisagents.exporters.pptx_edit`（检查 / 更新幻灯片 / 删除幻灯片 / 重新排序幻灯片 / 添加幻灯片）适用于任何导出器生成的演示文稿，以及等效的 `pptx_*` MCP 工具，以便 LLM 代理可以迭代生成的演示文稿。 - **MCP 服务器**：12 个工具 —— `list_sources` + `list_exports`（发现），`search`，`fetch_paper`，`fetch_pdf_text`，`download_pdfs`，`export`，以及五个 `pptx_*` 编辑工具。让任何 MCP 感知的 LLM（Claude Code、Claude Desktop、Cursor、……）驱动整个工作流程。 - **两种丰富路径**，用于超越摘要进入真正的毕业论文样式的演示文稿： - **LLM-as-agent（无 API 密钥）** —— 调用 LLM 读取 PDF 正文文本，通过 `fetch_pdf_text`，在上下文中编写结构化摘要，并将其传递给 `export`。 - **Python 管道（`--enrich`）** —— CLI 调用 Anthropic 的 API 本身；默认模型 `claude-opus-4-7`。 - **可见 Chrome 发布流程**：学者 SERP、IEEE `/rest/search` 和每个付费 PDF 下载（ieeexplore / dl.acm / link.springer / sciencedirect / wiley / oup / nature / science / …）都在一个真正的可见 Chrome 会话中通过 `selenium` 运行。用户在实时窗口中解决验证码 / 完成 SSO；`THESISAGENTS_CHROME_PROFILE_DIR` 在运行之间持久化 cookie。 - **LLM-as-agent 流程**（`scripts/llm_*.py`）：当编辑器中的 LLM 驱动浏览器本身（而不是让 `asyncio.gather` 执行）时，`scripts/llm_driven_search.py` 在学者和 IEEE 上打开 Chrome，`scripts/llm_download_pdfs.py` 遍历一个 xlsx 并下载每个论文在一个 Chrome 会话中（IEEE / ACM / Springer / arXiv / ACL Anthology / NeurIPS / OpenReview），而 `scripts/regen_*.py` 显示了为每篇论文手工编写富 `PaperSummary` 的工作模式。 - **OA PDF 解析器**：在重复数据删除后，每篇没有 `pdf_url` 的论文都会通过 Unpaywall → S2 `openAccessPdf` → arXiv 标题搜索 → CORE.ac.uk（当设置密钥时）。在 IEEE / ACM / Springer / 其它重度查询中，典型的提升为 40-70 个百分点。 - **默认安全**：仅 HTTPS 的 HTTP 传输，每个源的速率限制（令牌桶），任何 XML 有效载体的 `defusedxml`，导出路径的安全防护路径遍历，不对用户输入使用 `eval` / `exec` / `pickle`。 - **zh-tw / zh-cn 词汇保护**：`tests/test_i18n.py::test_zh_tw_files_use_traditional_chinese_vocabulary` 中的 ~244 个正则表达式模式捕获了简体中文词汇，这些词汇被错误地用繁体字渲染（例如 `內存` → `記憶體`，`魯棒性` → `穩健性`，`軟件` → `軟體`，`緩存` → `快取`）。相同的保护措施在 zh-cn 本地字符串中反向运行。完整的规则 + 正则表达式目录位于 `.claude/agents/rules/language-vocabulary-check.md`。 ## 快速开始 ```powershell git clone <repo-url> cd ThesisAgents python -m venv .venv .venv\Scripts\Activate.ps1 # Windows PowerShell # source .venv/bin/activate # Linux / macOS # 安装开发依赖项（也包括 MCP SDK 和智能依赖项） pip install -e .[dev] ``` 搜索 arXiv 并导出演示文稿 + 工作簿 + BibTeX（默认 `--query`）： ```powershell py -m thesisagents --query "diffusion models" --source arxiv --max 10 ` --out .\exports\ ``` 从 URL 获取单个论文 —— 默认导出 `.pptx + .bib`（对于一行来说，`.xlsx` 意义不大）： ```powershell py -m thesisagents --paper "https://arxiv.org/abs/1706.03762" ` --filename-stem attention ` --out .\exports\ ``` 以繁體中文渲染演示文稿： ```powershell py -m thesisagents --paper "https://arxiv.org/abs/1706.03762" ` --lang zh-tw --out .\exports\ ``` LLM 管道丰富（Python 调用 Anthropic 本身 —— 需要 API 密钥）： ```powershell $env:ANTHROPIC_API_KEY = "sk-ant-..." py -m thesisagents --paper "https://arxiv.org/abs/1706.03762" ` --enrich --lang zh-tw --out .\exports\ ``` ## CLI 标志 | 标志 | 用途 | |---|---| | `--query` / `-q` | 关键词（必需，除非 `--paper`）。 | | `--paper` / `-p` | arXiv ID / URL，DOI，PMID 或 IEEE 文档 URL。 与 `--query` 互斥。 | | `--source` / `-s` | 以逗号分隔的源列表。 默认 `arxiv`。 | | `--max` / `-n` | 每个源的最大结果数（1..200）。 默认 25。 | | `--year-from` / `--year-to` | 包含年份筛选。 | | `--export` / `-e` | 格式：`pptx`、`xlsx`、`md`、`bib`、`json`、`ris`、`csv`、`csl` 任意之一。 默认值取决于模式（见下文）。 | | `--out` / `-o` | 输出目录。 默认 `./exports`。 | | `--filename-stem` | 覆盖生成的 filename stem。 | | `--no-abstract` | 从导出中省略摘要内容。 | | `--lang` / `-l` | 幻灯片语言：14 种语言之一 - `zh-tw`、`zh-cn`、`ja`、`es`、`fr`、`de`、`ko`、`pt`、`ru`、`it`、`vi`、`hi`、`id`。 默认 `en`。 | | `--enrich` | 自动丰富功能的强制变体。 需要 `ANTHROPIC_API_KEY` 和 `[intelligence]` 额外功能。 （当设置密钥时，自动丰富是默认的。） | | `--lightweight` | 跳过丰富 + 强制仅摘要幻灯片。 仅用于快速/无人值守运行； **当 LLM 代理驱动时，请优先使用 LLM-as-agent 流** 以下。 | | `--llm-model` | 覆盖用于丰富的默认 `claude-opus-4-7`。 | | `--no-pdf` | 跳过自动 PDF 下载。 还禁用每篇论文的 PPT 门（无 PDF → 无完整内容）。 | | `--no-oa-resolve` | 跳过后重复 OA PDF 解析器（Unpaywall + S2 + arXiv + CORE.ac.uk）。 | | `--top-tier-only` | 将结果限制在 arXiv +精选的 CS 旗舰期刊名单（S&P、CCS、NDSS、USENIX Security、NeurIPS、ICML、ICSE 等）。 默认关闭。 | | `--paywall-threshold` | 触发确认提示的付费结果分数。 默认 0.30。 | | `--yes` | 跳过付费墙提示并继续。 | | `--max-slides` | 每篇论文的幻灯片上限（默认 25；传递 0 为无限制）。 | | `--light-mode` | 渲染 pptx 时使用白色背景 + 海军蓝文本。 默认暗模式（暗背景 + 近白色文本）- 传递此参数适用于在光线充足的房间中使用投影仪或打印时。 | | `--quiet` | 禁止每篇论文的打印输出。 | ### 环境变量 | 变量 | 使用方 | 用途 | |---|---|---| | `ANTHROPIC_API_KEY` | `--enrich` | LLM 认证。 不适用于通过 MCP 的 LLM-as-agent 路径。 | | `THESISAGENTS_LLM_MODEL` | `--enrich` | 覆盖默认的 `claude-opus-4-7`。 | | `THESISAGENTS_S2_API_KEY` | Semantic Scholar + OA 解析器 | 更高的速率限制；也用于 OA 解析器的 S2 `openAccessPdf` 步骤。 在 <https://www.semanticscholar.org/product/api> 获取免费密钥。 | | `THESISAGENTS_NCBI_API_KEY` | PubMed | 将 NCBI 的匿名限制（3/s）提高到 10/s。 可选。 | | `THESISAGENTS_CONTACT_EMAIL` | PubMed、ACM、Crossref、OpenAlex、**Unpaywall** | 礼貌池标签 + 启用 OA 解析器的 Unpaywall 步骤（IEEE / ACM / Springer / Elsevier 付费论文的最大 PDF 覆盖增益；典型提升 40-70 pp）。 | | `THESISAGENTS_IEEE_API_KEY` | IEEE（API 路径） | 官方 IEEE Xplore API；为范围内论文提供 `pdf_url`。 | | `THESISAGENTS_DISABLE_IEEE_SCRAPING` | IEEE | **IEEE 默认通过可见 Chrome 启用**。 设置 `=1` 以选择退出（例如，无 Chrome 的 CI）。 httpx 爬虫分支仅在 WebRunner 不可用时作为回退运行。 | | `THESISAGENTS_CROSSREF_PLUS_TOKEN` | ACM、Crossref | Crossref Plus 订阅令牌（Bearer 头）。 可选。 | | `THESISAGENTS_SPRINGER_API_KEY` | Springer | 需要；从 <https://dev.springernature.com/> 获取免费密钥。 插件在没有该密钥时引发 `ConfigError`。 | | `THESISAGENTS_DISABLE_SCHOLAR_SCRAPING` | Google Scholar | **Scholar 默认通过可见 Chrome 启用**。 设置 `=1` 以选择退出（Google 的服务条款禁止自动访问 - 默认启用以确保覆盖范围，退出以避免验证码/IP 阻止风险）。 | | `THESISAGENTS_CHROME_PROFILE_DIR` | Scholar + IEEE + 付费 PDF 下载 | 持久的 Chrome `--user-data-dir`。 设置此项并完成 VPN / SSO / Google 登录一次；后续运行继承 cookie，以便 IEEE 返回付费元数据，Scholar 提供不限速的 SERP。 | | `THESISAGENTS_DISABLE_WEBRUNNER` | Scholar + IEEE + 付费 PDF 下载 | `=1` 强制使用 httpx 路径而不是驱动真实 Chrome。 适用于无 Chrome 二进制文件的 CI / Docker；否则请保持未设置。 | | `THESISAGENTS_CORE_API_KEY` | OA 解析器 + `core` 搜索源 | 在 <https://core.ac.uk/services/api> 获取免费密钥。 启用 CORE.ac.uk OA 查找步骤（200M+ 机构/区域 OA 项目） **和** `core` 搜索源。 如果没有它，`core` 源将被静默跳过，其他 OA 策略（Unpaywall、S2、arXiv）仍会运行。 | | `THESISAGENTS_PDF_COOKIES_FILE` | PDF 下载器 | Netscape `cookies.txt`。 默认关闭。 仅与您具有机构权限的出版商一起使用。 | | `THESISAGENTS_LOG_LEVEL` | 记录器 | 默认 `INFO`；`DEBUG` 用于详细跟踪。 | 默认值：`--query` → `pptx`、`xlsx`、`bib`。 `--paper` → `pptx`、`bib`。 始终可通过显式 `--export` 覆盖。 ## LLM-as-agent 流 当编辑器中的 LLM（Claude Code、Cursor、Aider、Codex CLI 等）想要驱动发布商浏览器本身时 - 选择 URL，检查返回的 DOM，决定要深入研究的论文 - `scripts/` 下的五个脚本涵盖了规范路径： | 脚本 | 功能 | |---|---| | `scripts/llm_driven_search.py "<query>"` | 启动可见的 Chrome，导航到 Scholar SERP 以查询，JS 获取 IEEE `/rest/search`，从内部的 IEEE 源，倾倒 SERP HTML + IEEE JSON 到 `exports/_llm_scratch/`。 | | `scripts/llm_parse_results.py` | 读取倾倒的产物，运行项目的解析器，重复数据删除 + 排名 + 导出 `.xlsx` + `.md` 供 LLM 检查。 | | `scripts/llm_download_pdfs.py <xlsx>` | 遍历 `.xlsx`，将每行分派到正确的发布商下载器（IEEE / ACM / Springer / arXiv / ACL Anthology / NeurIPS / OpenReview）到一个 Chrome 会话中。 幂等：如果磁盘上已经有有效的 `<id>.pdf`，则立即跳过。 | | `scripts/llm_download_{ieee,acm,springer}_pdf.py <id>` | 单论文变体，用于迭代选择器/调试一个条目。 | | `scripts/regen_*.py` | 论文总结的示例用法 → 富集 `.pptx`。 查看 `scripts/regen_speculative_decoding_zh_tw.py` 以获取规范形状。 | 完整的端到端运行手册（搜索 → 丰富的 deck）位于 `.claude/agents/tasks/paper-summary-author.md` - 在启动新查询之前打开它，以便 LLM 可以在不暂停用户输入的情况下运行流程。 ## MCP 服务器 使用 Claude Code 注册： ```powershell claude mcp add thesisagents -- ".venv\Scripts\python.exe" -m thesisagents.mcp ``` 或写入您的设置文件： ```json { "mcpServers": { "thesisagents": { "command": ".venv\\Scripts\\python.exe", "args": ["-m", "thesisagents.mcp"] } } } ``` 工具： | 工具 | 用途 | |---|---| | `list_sources` | 列出每个插件并报告当前环境中是否启用。 在 `search` 之前调用此工具。 | | `search` | 关键词 → 论文列表。 接受 `top_tier_only`、`min_citations`；默认为完整的无需 API 密钥的源混合。 | | `fetch_paper` | arXiv / DOI / PMID / IEEE 标识符 → 单篇论文。 | | `fetch_pdf_text` | 下载一篇论文，返回提取的正文。 **MCP 路径到"I read the paper"。** | | `download_pdfs` | 将论文列表的 PDFs 批量下载到 `{out_dir}/pdfs/`。 返回按 BibTeX 键控的每篇论文结果。 | | `export` | 论文列表 + 格式 → 编写 `.pptx/.xlsx/.md/.bib/.json/.ris/.csv/.csl.json`。 接受每篇论文的 `summary` 字段用于丰富的论文样式模式，`max_slides_per_paper`（默认 25）和 `dark_mode`（默认 `false` - 项目默认为浅色海军带状图，传递 `true` 用于暗色 OLED / 低光后通道）。 | | `pptx_inspect` | 读取现有幻灯片的幻灯片/形状结构。 | | `pptx_review` | 审核一个幻灯片 - 溢出 + 颜色合同 + `paper_rule` 部分完整性。 自动检测幻灯片语言；也是 CLI `python -m thesisagents review <deck.pptx>`。 | | `pptx_update_slide` | 替换 `title` / `body` / `meta`（按形状名称）或任意索引形状。 | | `pptx_delete_slide` | 删除一个幻灯片及其部分关系。 | | `pptx_reorder_slides` | 通过 `sldIdLst` 排列幻灯片。 | | `pptx_add_slide` | 追加或插入新的 `title` / `body` / `meta` 幻灯片。 | LLM-as-agent 流（无需 `ANTHROPIC_API_KEY` - LLM 是代理）： ``` 1. （可选）list_sources（） # 发现启用的插件 2. search（keywords = ...，sources = [...]，top_tier_only = true） 3. （可选）download_pdfs（papers，out_dir = "./exports/..."）# 持久化 PDFs 4. fetch_pdf_text（pdf_url = paper.pdf_url）# 每篇论文 5. （LLM 读取正文，生成结构化的 `summary` 字典） 6. export（papers = [{...paper, "summary": {pain_points: [...]，rq_results: [...]}}]， language = "zh-tw"，formats = ["pptx","bib"]，dark_mode = true，...） ``` 完整的参考资料见 [`docs/mcp.md`](docs/mcp.md)。 ## 项目布局 ``` ThesisAgents/ ├── thesisagents/ # 主包 │ ├── core/ # Paper / PaperSummary / RqResult / 重复数据删除 / 排名 / 管道 │ ├── fetchers/ # 仅 HTTPS 的异步客户端，令牌桶速率限制 │ ├── exporters/ # pptx（论文样式）· xlsx · bib · md · json · ris · csv · csl · pptx_edit · i18n │ ├── intelligence/ # PDF 获取 + Anthropic 总结器（[intelligence] 额外） │ ├── mcp/ # FastMCP 服务器（12 个工具） │ ├── utils/ # 日志记录，路径安全 │ ├── cli.py # argparse CLI │ └── __main__.py ├── sources/ # 插件文件夹：arxiv，semantic_scholar， │ # openalex，pubmed，acm，ieee，scholar， │ # dblp，crossref，openaire，springer， │ # europepmc，doaj，hal，core ├── tests/ # pytest 套件 + 记录的 fixtures（无实时 HTTP） ├── docs/ # Sphinx（14 个语言树） ├── scripts/ # 一次性再生脚本 └── pyproject.toml # ruff，bandit，构建，可选额外功能 ``` ## 完成定义 ```powershell .venv\Scripts\python.exe -m pytest tests/ .venv\Scripts\python.exe -m ruff check . .venv\Scripts\python.exe -m bandit -c pyproject.toml -r thesisagents/ sources/ ``` -bandit 上的 `-c` 标志是必需的 - 没有它，bandit 会忽略项目跳过配置。 在触摸 pptx 导出器时，还要运行溢出检查（参见 `CLAUDE.md` 中的“幻灯片规则”）。 ## 桌面 GUI（PySide6） 使用 `[gui]` 额外功能提供原生桌面界面： ```powershell pip install thesisagents[gui] thesisagents-gui # 或：thesisagents gui ``` 窗口有四个选项卡 - **搜索**，**设置**（通过 QSettings 保留 API 密钥），**丰富**（驱动 LLM-as-agent / Python-pipeline 丰富 `collection_ready` 信号），和 **Deck**（浅色模式切换 + 幻灯片上限 + 最大图形控件流到 `ExportOptions`）。Windows 发布版 zip 提供了 Nuitka 编译的 bundle，附带 PySide6，因此 `thesisagents.exe gui` 无需单独的 Python 安装即可运行。 **UI 支持所有 14 种语言**（英文，繁体中文，简体中文，日本语，西班牙语，法语，德语，韩语，葡萄牙语，俄语，意大利语，越南语，印地语，印尼语）- 首次运行从您的 OS 区域设置中选取语言，然后 **设置 → 接口语言** 允许您更改。幻灯片输出语言是一个单独的下拉菜单，因此您可以运行 UI 使用一种语言，发出幻灯片使用另一种语言。布局是自适应的：每个表单都位于 `QScrollArea` 中，窗口调整大小到 900×600（仍然适合 720p），默认启用 HiDPI 缩放。 完整的参考资料： [`docs/gui.md`](docs/gui.md)。 ## 打包为独立可执行文件 提供了两个打包器来提供一个不需要安装 Python 的单个二进制文件： - **[`docs/packaging-pyinstaller.md`](docs/packaging-pyinstaller.md)` - 快速构建（不到 1 分钟），200–300 MB 输出，2–4 秒启动。 - 最适合您迭代构建脚本时使用。 - **[`docs/packaging-nuitka.md`](docs/packaging-nuitka.md)** - 慢构建（5–15 分钟），80–150 MB 输出，亚秒级启动， 一些字节码保护。 最适合终端用户运行二进制文件很多次时使用。 两个文档涵盖项目特定的陷阱 - `sources/<name>/` 下的动态源插件 - 并提供 CLI 和 MCP 服务器入口点的已验证命令。 ## 持续集成 & 发布 两个 GitHub Actions 工作流位于 `.github/workflows/` 下： - **`ci.yml`** 在每次推送和 `main` 的 PR 上运行。 矩阵是 Ubuntu + Windows × Python 3.12 / 3.13 / 3.14（6 个作业）。 每个作业运行 `ruff check`、`bandit -c pyproject.toml` 和 `pytest`。 - **`release.yml`** 等待 `ci.yml` 在 `main` 上完成（`workflow_run` 触发器）。 它仅在 CI 成功后运行。 **每次 CI 成功推送到 `main` 就是一个发布** - 工作流自动在 `pyproject.toml` 中增加版本号，提交更改回 `main` 为 `chore: bump version to X.Y.Z`，并管道： 1. **`bump-version`** - 从 `pyproject.toml` 读取当前 `X.Y.Z`，增量到 `X.Y.(Z+1)`，提交 + 推回 `main` 使用工作流的 `GITHUB_TOKEN`。 该推送 **不会** 重新触发 CI（按照 GitHub 的规则，使用 `GITHUB_TOKEN` 驱动的推送不能启动新的工作流运行），所以循环自然终止。 2. **`publish-pypi`** - 构建 sdist + 轮， `twine check`， 3. **`create-draft-release`** - 在标签 `v<version>` 处打开一个 *草稿* GitHub 发布，附带自动生成的注释。 4. **`build-nuitka`** - 编译一个 Nuitka 独立包，在 Windows 运行器上（入口点：`python -m thesisagents` 通过 `--python-flag=-m`），冒烟测试它，将生成的 `thesisagents.dist/` 文件夹压缩，附加 zip 和 `.sha256` 校验和到草稿发布。独立（非 onefile）设计。Windows 独家也是因为 Linux / macOS 用户从 PyPI 安装。构建缓存以 `pyproject.toml` 为键，暖构建从 ~70 分钟冷启动到 ~5–10 分钟。 5. **`publish-release`** - 一旦 Nuitka 资产上传完毕，取消草稿标记，发布即可，用户永远不会看到半成品发布。 **跳过发布** 在提交消息中包含 `[skip release]` 即可跳过版本号增加和后续作业 - 对文档/错字/重构等提交使用此功能，这些提交不应消耗版本号。 启用 PyPI 发布 + 可执行文件发布： 1. 在 <https://pypi.org/manage/account/token/> 处生成一个项目范围的 API 令牌。 2. 在 GitHub 仓库中：`设置 → 动作 → 常规 → 工作流权限 → 读取和写入权限`。允许 GitHub Actions 将更改推送到 `main`。版本号增加由工作流的 `GITHUB_TOKEN` 推送。 3. 切割发布时，请将 PR 合并到 `main`。管道需要 ~3–5 分钟发布到 PyPI，~50–70 分钟更多（冷）或 ~5–10 分钟（暖 Nuitka 缓存）才能将 Windows zip 附加。 `publish-pypi` 作业故意 **不** 附加 GitHub 环境，因此每次运行都显示为发布条目（附带 Nuitka `.exe`），而不是作为“部署”侧边栏小工具显示在仓库首页 - 发布有自己的专用页面，部署条目在顶部冗余噪音。 ## 许可 请参阅 `LICENSE`。arXiv API 在其使用条款 (<https://info.arxiv.org/help/api/tou.html>) 的基础上使用 - 观察每 3 秒的软限制；捆绑的获取器已经通过其令牌桶强制执行此限制。