名称： 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. 读取现有配置：
   • 加载 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）；否则保留默认值。
   • 搜索范围 → 设置 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。
   • API UI 访问 → 仅当用户明确希望在不同源上使用 UI 时设置 CORS_ORIGINS。
   • 默认情况下不要询问：时区、质量与成本、超时设置、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. 报告结果：
   • 总结运行统计信息（seen、kept、时间窗口）。
   • 如果结果稀疏，建议增加 WINDOW_HOURS、ARXIV_MAX_RESULTS 或拓宽主题范围。

获取良好结果的建议

• 保持主题聚焦且互斥，以便分类器能选择正确的 ID。
• 如果质量很重要，为摘要使用比相关性判断更强的模型。
• 当结果稀疏时，增加 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。