better-dsh 0.2.4 → 0.2.5

package/docs/80_upstream-docs-and-skills/hermes-dev-skill/src/i18n/zh-Hans/user-guide/skills/bundled/productivity/productivity-powerpoint.md

@@ -0,0 +1,257 @@
+---
+title: "Powerpoint — 创建、读取、编辑"
+sidebar_label: "Powerpoint"
+description: "创建、读取、编辑"
+---
+
+{/* This page is auto-generated from the skill's SKILL.md by website/scripts/generate-skill-docs.py. Edit the source SKILL.md, not this page. */}
+
+# Powerpoint
+
+创建、读取、编辑 .pptx 幻灯片、备注、模板。
+
+## Skill 元数据
+
+| | |
+|---|---|
+| 来源 | 内置（默认安装） |
+| 路径 | `skills/productivity/powerpoint` |
+| 许可证 | 专有。完整条款见 LICENSE.txt |
+| 平台 | linux, macos, windows |
+
+## 参考：完整 SKILL.md
+
+:::info
+以下是 Hermes 在触发该 skill 时加载的完整 skill 定义。这是 agent 在 skill 激活时所看到的指令内容。
+:::
+
+# Powerpoint Skill
+
+## 使用时机
+
+只要涉及 .pptx 文件——无论作为输入、输出还是两者兼有——均使用此 skill。包括：创建幻灯片、演示文稿或 pitch deck；读取、解析或提取任意 .pptx 文件中的文本（即使提取的内容将用于其他地方，如邮件或摘要）；编辑、修改或更新现有演示文稿；合并或拆分幻灯片文件；处理模板、布局、演讲者备注或注释。只要用户提到"deck"、"slides"、"presentation"或引用了 .pptx 文件名，无论之后计划如何使用内容，均触发此 skill。如果需要打开、创建或操作 .pptx 文件，请使用此 skill。
+
+## 快速参考
+
+| 任务 | 指南 |
+|------|-------|
+| 读取/分析内容 | `python -m markitdown presentation.pptx` |
+| 基于模板编辑或创建 | 阅读 [editing.md](https://github.com/NousResearch/hermes-agent/blob/main/skills/productivity/powerpoint/editing.md) |
+| 从零创建 | 阅读 [pptxgenjs.md](https://github.com/NousResearch/hermes-agent/blob/main/skills/productivity/powerpoint/pptxgenjs.md) |
+
+---
+
+## 读取内容
+
+```bash
+# 文本提取
+python -m markitdown presentation.pptx
+
+# 可视化概览
+python scripts/thumbnail.py presentation.pptx
+
+# 原始 XML
+python scripts/office/unpack.py presentation.pptx unpacked/
+```
+
+---
+
+## 编辑工作流
+
+**完整细节请阅读 [editing.md](https://github.com/NousResearch/hermes-agent/blob/main/skills/productivity/powerpoint/editing.md)。**
+
+1. 使用 `thumbnail.py` 分析模板
+2. 解包 → 操作幻灯片 → 编辑内容 → 清理 → 打包
+
+---
+
+## 从零创建
+
+**完整细节请阅读 [pptxgenjs.md](https://github.com/NousResearch/hermes-agent/blob/main/skills/productivity/powerpoint/pptxgenjs.md)。**
+
+在没有模板或参考演示文稿时使用。
+
+---
+
+## 设计建议
+
+**不要创建无聊的幻灯片。** 白底纯文字列表不会给任何人留下深刻印象。请针对每张幻灯片参考以下建议。
+
+### 开始之前
+
+- **选择大胆、契合内容的配色方案**：配色应专为该主题而设计。如果把你的配色套用到完全不同的演示文稿中仍然"可用"，说明选择还不够具体。
+- **主次分明，而非平均分配**：一种颜色应占主导地位（60-70% 视觉比重），搭配 1-2 种辅助色和一种鲜明的强调色。切勿让所有颜色平分秋色。
+- **深浅对比**：标题页和结尾页用深色背景，内容页用浅色（"三明治"结构）。或全程使用深色背景以营造高端感。
+- **坚持一种视觉母题**：选择一种独特元素并贯穿始终——圆角图片框、彩色圆圈内的图标、单侧粗边框。在每张幻灯片上保持一致。
+
+### 配色方案
+
+根据主题选择配色，不要默认使用通用蓝色。以下配色方案仅供参考：
+
+| 主题 | 主色 | 辅助色 | 强调色 |
+|-------|---------|-----------|--------|
+| **午夜商务** | `1E2761`（深海蓝） | `CADCFC`（冰蓝） | `FFFFFF`（白） |
+| **森林苔藓** | `2C5F2D`（森林绿） | `97BC62`（苔绿） | `F5F5F5`（米白） |
+| **珊瑚活力** | `F96167`（珊瑚红） | `F9E795`（金黄） | `2F3C7E`（深蓝） |
+| **暖陶土** | `B85042`（陶土红） | `E7E8D1`（沙色） | `A7BEAE`（鼠尾草绿） |
+| **海洋渐变** | `065A82`（深蓝） | `1C7293`（青蓝） | `21295C`（午夜蓝） |
+| **炭灰极简** | `36454F`（炭灰） | `F2F2F2`（近白） | `212121`（黑） |
+| **青蓝信任** | `028090`（青蓝） | `00A896`（海泡绿） | `02C39A`（薄荷绿） |
+| **浆果奶油** | `6D2E46`（浆果紫） | `A26769`（玫瑰灰） | `ECE2D0`（奶油） |
+| **鼠尾草静谧** | `84B59F`（鼠尾草绿） | `69A297`（桉叶绿） | `50808E`（石板蓝） |
+| **樱桃醒目** | `990011`（樱桃红） | `FCF6F5`（近白） | `2F3C7E`（深蓝） |
+
+### 每张幻灯片
+
+**每张幻灯片都需要视觉元素**——图片、图表、图标或形状。纯文字幻灯片令人印象全无。
+
+**布局选项：**
+- 双栏（左文字，右插图）
+- 图标 + 文字行（彩色圆圈内图标，粗体标题，下方描述）
+- 2x2 或 2x3 网格（一侧图片，另一侧内容块网格）
+- 半出血图片（左侧或右侧全满）配内容叠加
+
+**数据展示：**
+- 大数字标注（60-72pt 大号数字，下方小标签）
+- 对比列（前后对比、优缺点、并排选项）
+- 时间线或流程图（编号步骤、箭头）
+
+**视觉精修：**
+- 章节标题旁的小彩色圆圈内放图标
+- 关键数据或标语使用斜体强调文字
+
+### 字体排版
+
+**选择有趣的字体搭配**——不要默认使用 Arial。选择一种有个性的标题字体，搭配简洁的正文字体。
+
+| 标题字体 | 正文字体 |
+|-------------|-----------|
+| Georgia | Calibri |
+| Arial Black | Arial |
+| Calibri | Calibri Light |
+| Cambria | Calibri |
+| Trebuchet MS | Calibri |
+| Impact | Arial |
+| Palatino | Garamond |
+| Consolas | Calibri |
+
+| 元素 | 字号 |
+|---------|------|
+| 幻灯片标题 | 36-44pt 粗体 |
+| 章节标题 | 20-24pt 粗体 |
+| 正文 | 14-16pt |
+| 说明文字 | 10-12pt 弱化色 |
+
+### 间距
+
+- 最小 0.5" 边距
+- 内容块之间 0.3-0.5"
+- 留有呼吸空间——不要填满每一寸
+
+### 避免（常见错误）
+
+- **不要重复相同布局**——在幻灯片间变换列、卡片和标注
+- **不要居中对齐正文**——段落和列表左对齐；仅标题居中
+- **不要忽视字号对比**——标题需 36pt 以上才能从 14-16pt 正文中突出
+- **不要默认使用蓝色**——选择能反映具体主题的颜色
+- **不要随意混用间距**——选定 0.3" 或 0.5" 的间隔后保持一致
+- **不要只精心设计一张幻灯片而其余保持简陋**——要么全力投入，要么全程保持简洁
+- **不要创建纯文字幻灯片**——添加图片、图标、图表或视觉元素；避免纯标题 + 列表
+- **不要忘记文本框内边距**——将线条或形状与文字边缘对齐时，将文本框的 `margin` 设为 `0`，或偏移形状以补偿内边距
+- **不要使用低对比度元素**——图标和文字都需要与背景形成强烈对比；避免浅色背景上的浅色文字或深色背景上的深色文字
+- **绝对不要在标题下方使用装饰线**——这是 AI 生成幻灯片的典型特征；改用留白或背景色
+
+---
+
+## QA（必须执行）
+
+**假设存在问题。你的任务是找出它们。**
+
+第一次渲染几乎从不正确。将 QA 视为查找 bug，而非确认步骤。如果第一次检查没有发现任何问题，说明你看得还不够仔细。
+
+### 内容 QA
+
+```bash
+python -m markitdown output.pptx
+```
+
+检查缺失内容、错别字、顺序错误。
+
+**使用模板时，检查是否残留占位符文本：**
+
+```bash
+python -m markitdown output.pptx | grep -iE "xxxx|lorem|ipsum|this.*(page|slide).*layout"
+```
+
+如果 grep 返回结果，在宣告完成前先修复。
+
+### 视觉 QA
+
+**⚠️ 使用子 agent**——即使只有 2-3 张幻灯片。你一直盯着代码，会看到你期望看到的，而非实际存在的。子 agent 有全新的视角。
+
+将幻灯片转换为图片（见[转换为图片](#converting-to-images)），然后使用以下 prompt（提示词）：
+
+```
+Visually inspect these slides. Assume there are issues — find them.
+
+Look for:
+- Overlapping elements (text through shapes, lines through words, stacked elements)
+- Text overflow or cut off at edges/box boundaries
+- Decorative lines positioned for single-line text but title wrapped to two lines
+- Source citations or footers colliding with content above
+- Elements too close (< 0.3" gaps) or cards/sections nearly touching
+- Uneven gaps (large empty area in one place, cramped in another)
+- Insufficient margin from slide edges (< 0.5")
+- Columns or similar elements not aligned consistently
+- Low-contrast text (e.g., light gray text on cream-colored background)
+- Low-contrast icons (e.g., dark icons on dark backgrounds without a contrasting circle)
+- Text boxes too narrow causing excessive wrapping
+- Leftover placeholder content
+
+For each slide, list issues or areas of concern, even if minor.
+
+Read and analyze these images:
+1. /path/to/slide-01.jpg (Expected: [brief description])
+2. /path/to/slide-02.jpg (Expected: [brief description])
+
+Report ALL issues found, including minor ones.
+```
+
+### 验证循环
+
+1. 生成幻灯片 → 转换为图片 → 检查
+2. **列出发现的问题**（如果未发现任何问题，请更严格地再看一遍）
+3. 修复问题
+4. **重新验证受影响的幻灯片**——一处修复往往会引发另一个问题
+5. 重复，直到完整检查一遍后不再出现新问题
+
+**在完成至少一次修复并验证的循环之前，不得宣告成功。**
+
+---
+
+## 转换为图片
+
+将演示文稿转换为单张幻灯片图片以供视觉检查：
+
+```bash
+python scripts/office/soffice.py --headless --convert-to pdf output.pptx
+pdftoppm -jpeg -r 150 output.pdf slide
+```
+
+这将生成 `slide-01.jpg`、`slide-02.jpg` 等文件。
+
+修复后重新渲染特定幻灯片：
+
+```bash
+pdftoppm -jpeg -r 150 -f N -l N output.pdf slide-fixed
+```
+
+---
+
+## 依赖项
+
+- `pip install "markitdown[pptx]"` - 文本提取
+- `pip install Pillow` - 缩略图网格
+- `npm install -g pptxgenjs` - 从零创建
+- LibreOffice（`soffice`）- PDF 转换（通过 `scripts/office/soffice.py` 为沙箱环境自动配置）
+- Poppler（`pdftoppm`）- PDF 转图片

package/docs/80_upstream-docs-and-skills/hermes-dev-skill/src/i18n/zh-Hans/user-guide/skills/bundled/productivity/productivity-teams-meeting-pipeline.md

@@ -0,0 +1,127 @@
+---
+title: "Teams Meeting Pipeline"
+sidebar_label: "Teams Meeting Pipeline"
+description: "通过 Hermes CLI 操作 Teams 会议摘要流水线 — 总结会议、检查流水线状态、重放任务、管理 Microsoft Graph 订阅"
+---
+
+{/* This page is auto-generated from the skill's SKILL.md by website/scripts/generate-skill-docs.py. Edit the source SKILL.md, not this page. */}
+
+# Teams Meeting Pipeline
+
+通过 Hermes CLI 操作 Teams 会议摘要流水线 — 总结会议、检查流水线状态、重放任务、管理 Microsoft Graph 订阅。
+
+## Skill 元数据
+
+| | |
+|---|---|
+| 来源 | 内置（默认安装） |
+| 路径 | `skills/productivity/teams-meeting-pipeline` |
+| 版本 | `1.1.0` |
+| 作者 | Hermes Agent + Teknium |
+| 许可证 | MIT |
+| 标签 | `Teams`, `Microsoft Graph`, `Meetings`, `Productivity`, `Operations` |
+
+## 参考：完整 SKILL.md
+
+:::info
+以下是 Hermes 在触发该 skill 时加载的完整 skill 定义。这是 agent 在 skill 激活时所看到的指令内容。
+:::
+
+# Teams Meeting Pipeline
+
+当用户询问 Microsoft Teams 会议摘要、转录文本、录制内容、行动项、Graph 订阅，或任何与 Teams 会议流水线相关的运维问题时，使用此 skill。支持任意语言 — 以下触发示例并非完整列表。
+
+所有面向运维人员的操作均通过终端工具执行 `hermes teams-pipeline` 子命令完成。此流水线没有新的模型工具 — CLI 是唯一操作界面。
+
+## 使用场景
+
+用户希望：
+- 总结 Teams 会议 / 提取行动项 / 获取会议记录
+- 检查流水线状态、查看已存储的会议任务，或查看近期会议
+- 重放 / 重新运行失败或需要重新生成摘要的已存储任务
+- 在更改环境变量或配置后验证 Microsoft Graph 设置
+- 排查"会议摘要未送达"或"新会议未被采集"等问题
+- 管理 Graph webhook 订阅（创建、续期、删除、查看）
+- 设置自动订阅续期（参见下方注意事项）
+
+多语言触发示例（非完整列表）：
+- 英语："summarize the Teams meeting"、"pipeline status"、"replay job X"
+- 土耳其语："Teams meeting özetle"、"action item çıkar"、"toplantı notu"、"pipeline durumu"、"replay job"
+
+## 前置条件
+
+使用流水线前，请确认以下变量已在 `~/.hermes/.env` 中设置：
+
+```bash
+MSGRAPH_TENANT_ID=...
+MSGRAPH_CLIENT_ID=...
+MSGRAPH_CLIENT_SECRET=...
+```
+
+如有缺失，请将用户引导至 `/docs/guides/microsoft-graph-app-registration` 的 Azure 应用注册指南 — 流水线正常运行需要一个已获得管理员授权的 Azure AD 应用注册，并配置相应的 Graph 应用权限。
+
+## 命令参考
+
+### 状态与检查（从这里开始）
+
+```bash
+hermes teams-pipeline validate              # 配置快照 — 每次变更后首先运行
+hermes teams-pipeline token-health          # Graph token 状态
+hermes teams-pipeline token-health --force-refresh   # 强制重新获取 token
+hermes teams-pipeline list                  # 近期会议任务
+hermes teams-pipeline list --status failed  # 仅显示失败任务
+hermes teams-pipeline show <job-id>         # 查看某个任务的完整详情
+hermes teams-pipeline subscriptions         # 当前 Graph webhook 订阅
+```
+
+### 重新运行 / 调试
+
+```bash
+hermes teams-pipeline run <job-id>          # 重放已存储任务（重新生成摘要并重新投递）
+hermes teams-pipeline fetch --meeting-id <id>   # 试运行：解析会议及转录文本，不持久化
+hermes teams-pipeline fetch --join-web-url "<url>"   # 通过加入链接进行试运行
+```
+
+### 订阅管理
+
+```bash
+hermes teams-pipeline subscribe \
+  --resource communications/onlineMeetings/getAllTranscripts \
+  --notification-url https://<your-public-host>/msgraph/webhook \
+  --client-state "$MSGRAPH_WEBHOOK_CLIENT_STATE"
+
+hermes teams-pipeline renew-subscription <sub-id> --expiration <iso-8601>
+hermes teams-pipeline delete-subscription <sub-id>
+hermes teams-pipeline maintain-subscriptions            # 续期即将到期的订阅
+hermes teams-pipeline maintain-subscriptions --dry-run  # 显示将被续期的内容
+```
+
+## 常见问题决策树
+
+- 用户问"为什么今天的会议没有收到摘要？" → 先执行 `list --status failed`，再对相关行执行 `show <job-id>`。如果任务根本不存在，检查 `subscriptions` — webhook 可能已过期（参见下方注意事项）。
+- 用户问"设置是否正常？" → 依次执行 `validate`、`token-health`、`subscriptions`。三项均通过后，发起一次测试会议，并检查 `list` 是否出现新行。
+- 用户问"重新运行会议 X 的摘要" → 执行 `list` 找到任务 ID，执行 `run <job-id>` 进行重放。若再次失败，执行 `show <job-id>` 查看错误，并用 `fetch --meeting-id` 对制品解析进行试运行。
+- 用户问"将会议 X 加入流水线" → 通常无需手动操作 — 流水线由订阅驱动，而非按单次会议触发。如果用户希望对某个历史会议生成摘要，使用 `fetch` 拉取转录文本，并在任务创建后执行 `run`。
+
+## 关键注意事项：Graph 订阅 72 小时后过期
+
+Microsoft Graph 将 webhook 订阅上限设为 72 小时，且**不会自动续期**。如果未调度 `maintain-subscriptions`，手动创建订阅 3 天后会议通知将静默停止。
+
+当用户反馈"昨天流水线还正常，今天没有任何内容进来"时：
+1. 执行 `hermes teams-pipeline subscriptions` — 如果结果为空，或所有条目的 `expirationDateTime` 均已过期，即为原因所在。
+2. 按上方示例使用 `subscribe` 重新创建订阅。
+3. **立即设置自动续期**，可通过 `hermes cron add`、systemd timer 或普通 crontab 实现。运维手册 `/docs/guides/operate-teams-meeting-pipeline#automating-subscription-renewal-required-for-production` 提供了三种方案的完整说明。12 小时间隔是安全的（相对 72 小时上限有 6 倍余量）。
+
+## 其他注意事项
+
+- **转录文本尚未就绪。** Teams 在会议结束后需要一段时间才能生成转录制品。对刚结束的会议执行 `fetch --meeting-id` 可能返回空结果。等待 2-5 分钟后重试，或让 Graph webhook 自然驱动采集。
+- **投递模式不匹配。** 如果摘要已生成（`list` 显示成功）但 Teams 中未收到任何内容，检查 `platforms.teams.extra.delivery_mode` 及对应的目标配置（`incoming_webhook_url` 或 `chat_id` 或 `team_id`+`channel_id`）。写入器从 config.yaml 或 `TEAMS_*` 环境变量中读取这些配置。
+- **Graph 应用权限。** token 获取正常（`token-health` 通过），但 Graph API 调用返回 401/403，原因是权限已添加但未重新授予管理员同意。请用户重新进入 Azure 门户中的应用注册页面，再次点击"授予管理员同意"。
+
+## 相关文档
+
+当用户需要比本 skill 更深入的内容时，请将其引导至以下资源：
+- Azure 应用注册操作指南：`/docs/guides/microsoft-graph-app-registration`
+- 完整流水线设置：`/docs/user-guide/messaging/teams-meetings`
+- 运维手册（续期自动化、故障排查、上线检查清单）：`/docs/guides/operate-teams-meeting-pipeline`
+- Webhook 监听器设置：`/docs/user-guide/messaging/msgraph-webhook`

package/docs/80_upstream-docs-and-skills/hermes-dev-skill/src/i18n/zh-Hans/user-guide/skills/bundled/research/research-arxiv.md

@@ -0,0 +1,300 @@
+---
+title: "Arxiv — 通过关键词、作者、分类或 ID 搜索 arXiv 论文"
+sidebar_label: "Arxiv"
+description: "通过关键词、作者、分类或 ID 搜索 arXiv 论文"
+---
+
+{/* This page is auto-generated from the skill's SKILL.md by website/scripts/generate-skill-docs.py. Edit the source SKILL.md, not this page. */}
+
+# Arxiv
+
+通过关键词、作者、分类或 ID 搜索 arXiv 论文。
+
+## Skill 元数据
+
+| | |
+|---|---|
+| 来源 | 内置（默认安装） |
+| 路径 | `skills/research/arxiv` |
+| 版本 | `1.0.0` |
+| 作者 | Hermes Agent |
+| 许可证 | MIT |
+| 平台 | linux, macos, windows |
+| 标签 | `Research`, `Arxiv`, `Papers`, `Academic`, `Science`, `API` |
+| 相关 skill | [`ocr-and-documents`](/user-guide/skills/bundled/productivity/productivity-ocr-and-documents) |
+
+## 参考：完整 SKILL.md
+
+:::info
+以下是 Hermes 在触发此 skill 时加载的完整 skill 定义。这是 agent 在 skill 激活时所看到的指令内容。
+:::
+
+# arXiv 学术研究
+
+通过 arXiv 免费 REST API 搜索并获取学术论文。无需 API key，无需额外依赖——仅使用 curl。
+
+## 快速参考
+
+| 操作 | 命令 |
+|--------|---------|
+| 搜索论文 | `curl "https://export.arxiv.org/api/query?search_query=all:QUERY&max_results=5"` |
+| 获取指定论文 | `curl "https://export.arxiv.org/api/query?id_list=2402.03300"` |
+| 阅读摘要（网页） | `web_extract(urls=["https://arxiv.org/abs/2402.03300"])` |
+| 阅读完整论文（PDF） | `web_extract(urls=["https://arxiv.org/pdf/2402.03300"])` |
+
+## 搜索论文
+
+API 返回 Atom XML 格式数据。可使用 `grep`/`sed` 解析，或通过管道传给 `python3` 获得整洁输出。
+
+### 基本搜索
+
+```bash
+curl -s "https://export.arxiv.org/api/query?search_query=all:GRPO+reinforcement+learning&max_results=5"
+```
+
+### 整洁输出（将 XML 解析为可读格式）
+
+```bash
+curl -s "https://export.arxiv.org/api/query?search_query=all:GRPO+reinforcement+learning&max_results=5&sortBy=submittedDate&sortOrder=descending" | python3 -c "
+import sys, xml.etree.ElementTree as ET
+ns = {'a': 'http://www.w3.org/2005/Atom'}
+root = ET.parse(sys.stdin).getroot()
+for i, entry in enumerate(root.findall('a:entry', ns)):
+    title = entry.find('a:title', ns).text.strip().replace('\n', ' ')
+    arxiv_id = entry.find('a:id', ns).text.strip().split('/abs/')[-1]
+    published = entry.find('a:published', ns).text[:10]
+    authors = ', '.join(a.find('a:name', ns).text for a in entry.findall('a:author', ns))
+    summary = entry.find('a:summary', ns).text.strip()[:200]
+    cats = ', '.join(c.get('term') for c in entry.findall('a:category', ns))
+    print(f'{i+1}. [{arxiv_id}] {title}')
+    print(f'   Authors: {authors}')
+    print(f'   Published: {published} | Categories: {cats}')
+    print(f'   Abstract: {summary}...')
+    print(f'   PDF: https://arxiv.org/pdf/{arxiv_id}')
+    print()
+"
+```
+
+## 搜索查询语法
+
+| 前缀 | 搜索范围 | 示例 |
+|--------|----------|---------|
+| `all:` | 所有字段 | `all:transformer+attention` |
+| `ti:` | 标题 | `ti:large+language+models` |
+| `au:` | 作者 | `au:vaswani` |
+| `abs:` | 摘要 | `abs:reinforcement+learning` |
+| `cat:` | 分类 | `cat:cs.AI` |
+| `co:` | 备注 | `co:accepted+NeurIPS` |
+
+### 布尔运算符
+
+```
+# AND（使用 + 时的默认行为）
+search_query=all:transformer+attention
+
+# OR
+search_query=all:GPT+OR+all:BERT
+
+# AND NOT
+search_query=all:language+model+ANDNOT+all:vision
+
+# 精确短语
+search_query=ti:"chain+of+thought"
+
+# 组合使用
+search_query=au:hinton+AND+cat:cs.LG
+```
+
+## 排序与分页
+
+| 参数 | 选项 |
+|-----------|---------|
+| `sortBy` | `relevance`, `lastUpdatedDate`, `submittedDate` |
+| `sortOrder` | `ascending`, `descending` |
+| `start` | 结果偏移量（从 0 开始） |
+| `max_results` | 结果数量（默认 10，最大 30000） |
+
+```bash
+# cs.AI 分类下最新的 10 篇论文
+curl -s "https://export.arxiv.org/api/query?search_query=cat:cs.AI&sortBy=submittedDate&sortOrder=descending&max_results=10"
+```
+
+## 获取指定论文
+
+```bash
+# 通过 arXiv ID
+curl -s "https://export.arxiv.org/api/query?id_list=2402.03300"
+
+# 多篇论文
+curl -s "https://export.arxiv.org/api/query?id_list=2402.03300,2401.12345,2403.00001"
+```
+
+## 生成 BibTeX
+
+获取论文元数据后，生成 BibTeX 条目：
+
+{% raw %}
+```bash
+curl -s "https://export.arxiv.org/api/query?id_list=1706.03762" | python3 -c "
+import sys, xml.etree.ElementTree as ET
+ns = {'a': 'http://www.w3.org/2005/Atom', 'arxiv': 'http://arxiv.org/schemas/atom'}
+root = ET.parse(sys.stdin).getroot()
+entry = root.find('a:entry', ns)
+if entry is None: sys.exit('Paper not found')
+title = entry.find('a:title', ns).text.strip().replace('\n', ' ')
+authors = ' and '.join(a.find('a:name', ns).text for a in entry.findall('a:author', ns))
+year = entry.find('a:published', ns).text[:4]
+raw_id = entry.find('a:id', ns).text.strip().split('/abs/')[-1]
+cat = entry.find('arxiv:primary_category', ns)
+primary = cat.get('term') if cat is not None else 'cs.LG'
+last_name = entry.find('a:author', ns).find('a:name', ns).text.split()[-1]
+print(f'@article{{{last_name}{year}_{raw_id.replace(\".\", \"\")},')
+print(f'  title     = {{{title}}},')
+print(f'  author    = {{{authors}}},')
+print(f'  year      = {{{year}}},')
+print(f'  eprint    = {{{raw_id}}},')
+print(f'  archivePrefix = {{arXiv}},')
+print(f'  primaryClass  = {{{primary}}},')
+print(f'  url       = {{https://arxiv.org/abs/{raw_id}}}')
+print('}')
+"
+```
+{% endraw %}
+
+## 阅读论文内容
+
+找到论文后，按以下方式阅读：
+
+```
+# 摘要页（速度快，包含元数据和摘要）
+web_extract(urls=["https://arxiv.org/abs/2402.03300"])
+
+# 完整论文（PDF → 通过 Firecrawl 转为 markdown）
+web_extract(urls=["https://arxiv.org/pdf/2402.03300"])
+```
+
+本地 PDF 处理请参阅 `ocr-and-documents` skill。
+
+## 常用分类
+
+| 分类 | 领域 |
+|----------|-------|
+| `cs.AI` | 人工智能 |
+| `cs.CL` | 计算与语言（NLP） |
+| `cs.CV` | 计算机视觉 |
+| `cs.LG` | 机器学习 |
+| `cs.CR` | 密码学与安全 |
+| `stat.ML` | 机器学习（统计） |
+| `math.OC` | 优化与控制 |
+| `physics.comp-ph` | 计算物理 |
+
+完整列表：https://arxiv.org/category_taxonomy
+
+## 辅助脚本
+
+`scripts/search_arxiv.py` 脚本负责处理 XML 解析并提供整洁输出：
+
+```bash
+python scripts/search_arxiv.py "GRPO reinforcement learning"
+python scripts/search_arxiv.py "transformer attention" --max 10 --sort date
+python scripts/search_arxiv.py --author "Yann LeCun" --max 5
+python scripts/search_arxiv.py --category cs.AI --sort date
+python scripts/search_arxiv.py --id 2402.03300
+python scripts/search_arxiv.py --id 2402.03300,2401.12345
+```
+
+无需额外依赖——仅使用 Python 标准库。
+
+---
+
+## Semantic Scholar（引用、相关论文、作者主页）
+
+arXiv 不提供引用数据或推荐功能。请使用 **Semantic Scholar API**——免费，基本使用无需 API key（1 次请求/秒），返回 JSON 格式。
+
+### 获取论文详情及引用信息
+
+```bash
+# 通过 arXiv ID
+curl -s "https://api.semanticscholar.org/graph/v1/paper/arXiv:2402.03300?fields=title,authors,citationCount,referenceCount,influentialCitationCount,year,abstract" | python3 -m json.tool
+
+# 通过 Semantic Scholar 论文 ID 或 DOI
+curl -s "https://api.semanticscholar.org/graph/v1/paper/DOI:10.1234/example?fields=title,citationCount"
+```
+
+### 获取引用该论文的文献（被引情况）
+
+```bash
+curl -s "https://api.semanticscholar.org/graph/v1/paper/arXiv:2402.03300/citations?fields=title,authors,year,citationCount&limit=10" | python3 -m json.tool
+```
+
+### 获取该论文的参考文献（引用情况）
+
+```bash
+curl -s "https://api.semanticscholar.org/graph/v1/paper/arXiv:2402.03300/references?fields=title,authors,year,citationCount&limit=10" | python3 -m json.tool
+```
+
+### 搜索论文（arXiv 搜索的替代方案，返回 JSON）
+
+```bash
+curl -s "https://api.semanticscholar.org/graph/v1/paper/search?query=GRPO+reinforcement+learning&limit=5&fields=title,authors,year,citationCount,externalIds" | python3 -m json.tool
+```
+
+### 获取论文推荐
+
+```bash
+curl -s -X POST "https://api.semanticscholar.org/recommendations/v1/papers/" \
+  -H "Content-Type: application/json" \
+  -d '{"positivePaperIds": ["arXiv:2402.03300"], "negativePaperIds": []}' | python3 -m json.tool
+```
+
+### 作者主页
+
+```bash
+curl -s "https://api.semanticscholar.org/graph/v1/author/search?query=Yann+LeCun&fields=name,hIndex,citationCount,paperCount" | python3 -m json.tool
+```
+
+### 常用 Semantic Scholar 字段
+
+`title`、`authors`、`year`、`abstract`、`citationCount`、`referenceCount`、`influentialCitationCount`、`isOpenAccess`、`openAccessPdf`、`fieldsOfStudy`、`publicationVenue`、`externalIds`（包含 arXiv ID、DOI 等）
+
+---
+
+## 完整研究工作流
+
+1. **发现论文**：`python scripts/search_arxiv.py "your topic" --sort date --max 10`
+2. **评估影响力**：`curl -s "https://api.semanticscholar.org/graph/v1/paper/arXiv:ID?fields=citationCount,influentialCitationCount"`
+3. **阅读摘要**：`web_extract(urls=["https://arxiv.org/abs/ID"])`
+4. **阅读完整论文**：`web_extract(urls=["https://arxiv.org/pdf/ID"])`
+5. **查找相关工作**：`curl -s "https://api.semanticscholar.org/graph/v1/paper/arXiv:ID/references?fields=title,citationCount&limit=20"`
+6. **获取推荐**：向 Semantic Scholar 推荐接口发送 POST 请求
+7. **追踪作者**：`curl -s "https://api.semanticscholar.org/graph/v1/author/search?query=NAME"`
+
+## 速率限制
+
+| API | 速率 | 认证 |
+|-----|------|------|
+| arXiv | 约 1 次请求 / 3 秒 | 无需认证 |
+| Semantic Scholar | 1 次请求 / 秒 | 无需认证（有 API key 可达 100 次/秒） |
+
+## 注意事项
+
+- arXiv 返回 Atom XML——使用辅助脚本或解析代码片段获得整洁输出
+- Semantic Scholar 返回 JSON——通过管道传给 `python3 -m json.tool` 提升可读性
+- arXiv ID 格式：旧格式（`hep-th/0601001`）与新格式（`2402.03300`）
+- PDF：`https://arxiv.org/pdf/{id}` — 摘要：`https://arxiv.org/abs/{id}`
+- HTML（如有）：`https://arxiv.org/html/{id}`
+- 本地 PDF 处理请参阅 `ocr-and-documents` skill
+
+## ID 版本控制
+
+- `arxiv.org/abs/1706.03762` 始终解析为**最新**版本
+- `arxiv.org/abs/1706.03762v1` 指向某个**特定**不可变版本
+- 生成引用时，请保留你实际阅读的版本后缀，以防引用漂移（后续版本可能对内容有重大修改）
+- API 的 `<id>` 字段返回带版本号的 URL（例如 `http://arxiv.org/abs/1706.03762v7`）
+
+## 已撤回论文
+
+论文提交后可能被撤回。发生这种情况时：
+- `<summary>` 字段会包含撤回声明（注意查找 "withdrawn" 或 "retracted" 字样）
+- 元数据字段可能不完整
+- 在将某条结果视为有效论文之前，请务必检查摘要内容