名称： agentic-paper-digest-skill
描述： 使用 Agentic Paper Digest 获取并总结近期的 arXiv 和 Hugging Face 论文。当用户需要论文摘要、近期论文的 JSON 订阅源，或运行 arXiv/HF 处理流程时使用。
主页： https://github.com/matanle51/agentic_paper_digest
compatibility: 需要 Python 3、网络访问权限，以及用于引导的 git 或 curl/wget。通过 OPENAI_API_KEY 或 LITELLM_API_KEY（OpenAI 兼容）访问 LLM。
元数据： {"clawdbot":{"requires":{"anyBins":["python3","python"]}}}

Agentic Paper Digest

何时使用

• 从 arXiv 和 Hugging Face 获取近期论文摘要。
• 为下游智能体生成 JSON 输出。
• 当需要轮询工作流时，运行本地 API 服务器。

先决条件

• Python 3 和网络访问权限。
• 通过 OPENAI_API_KEY 或通过 LITELLM_API_BASE + LITELLM_API_KEY 使用 OpenAI 兼容的提供商来访问 LLM。
• git 用于引导是可选的；否则使用 curl/wget（或 Python）下载仓库。

获取代码并安装

• 推荐方式：运行引导辅助脚本。如果可用则使用 git，否则回退到 zip 下载。

bash "{baseDir}/scripts/bootstrap.sh"

• 通过设置 PROJECT_DIR 来覆盖克隆位置。

PROJECT_DIR="$HOME/agentic_paper_digest" bash "{baseDir}/scripts/bootstrap.sh"

运行（推荐 CLI）

bash "{baseDir}/scripts/run_cli.sh"

• 根据需要传递 CLI 参数。

bash "{baseDir}/scripts/run_cli.sh" --window-hours 24 --sources arxiv,hf

运行（可选 API）

bash "{baseDir}/scripts/run_api.sh"

• 触发运行并读取结果。

curl -X POST http://127.0.0.1:8000/api/run
curl http://127.0.0.1:8000/api/status
curl http://127.0.0.1:8000/api/papers

• 如果需要，停止 API 服务器。

bash "{baseDir}/scripts/stop_api.sh"

输出

• CLI --json 选项输出 run_id、seen、kept、window_start 和 window_end。
• 数据存储：data/papers.sqlite3（位于 PROJECT_DIR 下）。
• API 端点：POST /api/run、GET /api/status、GET /api/papers、GET/POST /api/topics、GET/POST /api/settings。

配置

配置文件位于 PROJECT_DIR/config。环境变量可以在 shell 中设置或通过 .env 文件设置。此处的包装脚本会自动从 PROJECT_DIR 加载 .env（可通过 ENV_FILE=/path/to/.env 覆盖）。

环境变量（.env 文件或导出的变量）
- OPENAI_API_KEY：使用 OpenAI 模型时必需（litellm 会读取此变量）。
- LITELLM_API_BASE、LITELLM_API_KEY：使用 OpenAI 兼容的代理/提供商。
- LITELLM_MODEL_RELEVANCE、LITELLM_MODEL_SUMMARY：用于相关性判断和摘要生成的模型（如果未设置摘要模型，则默认使用相关性模型）。
- LITELLM_TEMPERATURE_RELEVANCE、LITELLM_TEMPERATURE_SUMMARY：数值越低，输出越确定。
- LITELLM_MAX_RETRIES：LLM 调用的重试次数。
- LITELLM_DROP_PARAMS=1：丢弃不支持的参数以避免提供商错误。
- WINDOW_HOURS、APP_TZ：时间窗口和时区。
- ARXIV_CATEGORIES：逗号分隔的 arXiv 类别（默认包括 cs.CL,cs.AI,cs.LG,stat.ML,cs.CR）。
- ARXIV_API_BASE、HF_API_BASE：如有需要，可覆盖源端点。
- ARXIV_MAX_RESULTS、ARXIV_PAGE_SIZE：arXiv 分页限制。
- MAX_CANDIDATES_PER_SOURCE：在 LLM 筛选前，每个源的候选论文上限。
- FETCH_TIMEOUT_S、REQUEST_TIMEOUT_S：源获取和单次请求的超时时间。
- ENABLE_PDF_TEXT=1：在摘要中包含 PDF 第一页文本；需要安装 PyMuPDF（pip install pymupdf）。
- DATA_DIR：papers.sqlite3 文件的存储位置。
- CORS_ORIGINS：API 服务器允许的跨域来源（逗号分隔，用于 UI）。
- 路径覆盖：TOPICS_PATH、SETTINGS_PATH、AFFILIATION_BOOSTS_PATH。

配置文件
- config/topics.json：主题列表，包含 id、label、description、max_per_topic 和 keywords。相关性分类器必须输出此处定义的主题 ID。当 apply_topic_caps=1 时，max_per_topic 也会限制 GET /api/papers 的结果数量。
- config/settings.json：覆盖获取限制（arxiv_max_results、arxiv_page_size、fetch_timeout_s、max_candidates_per_source）。可通过 POST /api/settings 更新。
- config/affiliations.json：{pattern, weight} 提升列表，通过子字符串匹配机构名称应用。权重累加并上限为 1.0。无效的 JSON 会禁用提升，因此请保持文件为严格的 JSON 格式（无尾随逗号）。

强制工作流程（请逐步遵循）

1. 首先，你必须打开并阅读从 GitHub 仓库下载的配置：
   • 加载 config/topics.json、config/settings.json 和 config/affiliations.json（如果存在）。
   • 在请求用户更改之前，注意当前的主题 ID、数量上限和获取限制。
2. 向用户询问以下偏好（帮助用户）：
   • 感兴趣的主题 → 更新 config/topics.json（topics[].id/label/description/keywords、max_per_topic）。
     显示当前默认值，并询问是保留还是更改它们。
   • 时间窗口（小时） → 设置 WINDOW_HOURS（或向 CLI 传递 --window-hours）仅在用户关心时；否则保持默认值 24 小时。
   • 请用户填写以下参数（向用户解释其意图）：ARXIV_CATEGORIES、ARXIV_MAX_RESULTS、ARXIV_PAGE_SIZE、MAX_CANDIDATES_PER_SOURCE。
     询问是否保留默认值并显示当前值。
   • 模型/提供商 → 设置 OPENAI_API_KEY 或 LITELLM_API_KEY（+ LITELLM_API_BASE 如果使用代理），并设置 LITELLM_MODEL_RELEVANCE/LITELLM_MODEL_SUMMARY。
   • 默认情况下不要询问：时区、质量与成本、超时设置、PDF 文本、机构偏向、源列表。除非用户要求更改，否则使用默认值。
3. 确认工作空间路径：询问克隆/运行的位置。如果用户不关心，默认为 PROJECT_DIR="$HOME/agentic_paper_digest"。切勿硬编码 /Users/... 等路径。
4. 引导仓库：运行引导脚本（除非仓库已存在且用户要求跳过）。
5. 创建或验证 .env 文件：
   • 如果缺少 .env，请从仓库中的 .env.example 创建，然后请用户填写密钥和任何请求的偏好。
   • 在运行之前，确保至少设置了 OPENAI_API_KEY 或 LITELLM_API_KEY 中的一个。
6. 应用配置更改：
   • 直接编辑 JSON 文件（如果运行 API，也可使用 POST /api/topics 和 POST /api/settings）。
7. 运行处理流程：
   • 对于一次性 JSON 输出，优先使用 scripts/run_cli.sh。
   • 仅当用户明确要求 UI/API 访问或轮询时，才使用 scripts/run_api.sh。
8. 报告结果：
   • 如果结果稀疏，建议增加 WINDOW_HOURS、ARXIV_MAX_RESULTS 或拓宽主题范围。

获取良好结果

• 帮助用户定义并保持主题聚焦且互斥，以便分类器能选择正确的 ID。
• 如果质量很重要，为摘要使用比相关性判断更强的模型。
• 如果使用 OpenAI 的模型，默认使用 gpt-5-mini 以获得良好的性价比。
• 当结果稀疏时，增加 WINDOW_HOURS 或 ARXIV_MAX_RESULTS；如果结果噪声过多，则降低它们。
• 根据研究领域调整 ARXIV_CATEGORIES。
• 当摘要信息过少时，启用 PDF 文本（ENABLE_PDF_TEXT=1）。
• 使用适度的机构权重来偏置排名，而不会淹没相关性。
• 积极主动，帮助用户调整此技能以获得良好结果！

故障排除

• 端口 8000 被占用：运行 bash "{baseDir}/scripts/stop_api.sh" 或向 API 命令传递 --port 参数。
• 结果为空：增加 WINDOW_HOURS 或验证 .env 中的 API 密钥。
• 缺少 API 密钥错误：在运行前在 shell 中导出 OPENAI_API_KEY 或 LITELLM_API_KEY。