audio-paper-digest

分类: 开发与编程 | 上传者: nanless | 下载: 0 | 版本: v1.0（最新）

语音/音乐/音频论文速递自动化技能。抓取 arXiv + HuggingFace Papers，使用环境变量配置的 LLM 做筛选与深度分析，输出结构化 JSON，并可发布到 GitHub Pages 博客、微信公众号草稿与小红书文案。适用场景：论文速递、论文摘要、每日追踪、重分析、博客发布、微信发布与小红书发布。 --- **[English](SKILL.en.md)** | 中文 # Paper Digest Skill（以当前代码为准） ## 1. 文档定位 - `SKILL.md`：给 Agent 的执行规则与安全约束 - `README.md`：给人的运行手册（命令、配置、排错） - `prompts/filter.md`：筛选阶段 LLM prompt - `prompts/deep-analysis.md`：深度分析阶段 LLM prompt（输出格式、标签体系、评分标准）当文档与代码冲突时，**以 `scripts/*` 当前实现为准，并同步更新文档**。 --- ## 2. 当前真实流程主入口：`./run-full-fetch.sh`（或 `node scripts/full-fetch.js` / `npm run fetch`） 1. **自动归档**：检查 `data/current/deep-analysis-result.json` / `filtered-papers.json` / `analyzed.json`，若时间戳早于今天（北京时间）且 `data/archive/<日期>/` 下不存在，则复制后删除原文件。**`papers.json` 不归档。** 2. **arXiv 抓取**：7 个分类，每类最多 100 篇（可通过 `PD_ARXIV_MAX_RESULTS` 调整），遇连续 20 篇已有 ID 提前停止 3. **HuggingFace 抓取**：`daily_papers` 分页（最多 20 页）+ `papers` API 补充，默认近 7 天 4. **合并去重**：arXiv 优先，HF 补充 7 个特有字段，标记 `sources` 5. **LLM 筛选**：按 `PAPER_ANALYZER_*` 配置逐篇判断语音/音乐/音频相关，`batchSize=5`（可通过 `PD_FILTER_BATCH_SIZE` 调整），单篇超时 60 秒，重试 3 次 6. **保存筛选结果**：`data/current/filtered-papers.json` 7. **深度分析**：`deep-analyzer.js`，全文+图片，并发 3 篇（可通过 `PD_ANALYSIS_CONCURRENCY` 调整），每篇最多重试 2 次（可通过 `PD_ANALYSIS_MAX_RETRIES` 调整） 8. **增量保存**：每批分析后立即保存到 `data/current/deep-analysis-result.json`，自带失败结果保护（已有成功 analysis 的论文不会被无 analysis 的失败结果覆盖） 9. **更新去重库**：追加新论文 ID 到 `data/current/papers.json`，自动备份 papers.json（保留最近 7 天） 10. **收尾合并**：去重合并历史结果，自动备份 bak 文件（保留最近 10 个） `full-fetch.js` **不会自动发布博客/微信**，发布需单独运行 Python 脚本。 --- ## 3. 数据路径规范 ### 3.1 优先路径（当前） | 文件 | 用途 | 归档行为 | |------|------|---------| | `data/current/papers.json` | 论文去重数据库 | **不归档**，持续累积 | | `data/current/filtered-papers.json` | 筛选后的论文元数据 | 每日归档移走后重新生成 | | `data/current/deep-analysis-result.json` | 核心分析结果（含 analysis / parsed / imageUrls） | 每日归档移走后重新生成 | | `data/current/analyzed.json` | 旧版已分析记录（兼容） | 每日归档移走后重新生成 | ### 3.2 兼容行为部分脚本在读取时兼容 `data/*.json` 旧路径，但新产物应写入 `data/current/`。 ### 3.3 归档目录 `data/archive/<YYYY-MM-DD>/` 按日期子目录存放当日归档文件。`deep-analysis-resul

更新日志: Source: GitHub https://github.com/nanless/audio-paper-digest

目录结构

当前层级: tree/main/

📁 .github/
- 📁 workflows/
  - 📄 ci.yml 773 B
📁 docs/
- 📁 en/
  - 📄 data-format.md 4.3 KB
  - 📄 maintenance.md 7.0 KB
  - 📄 scripts.md 22.0 KB
  - 📄 setup.md 9.7 KB
  - 📄 troubleshooting.md 4.3 KB
  - 📄 workflow.md 13.1 KB
- 📄 data-format.md 4.1 KB
- 📄 maintenance.md 5.8 KB
- 📄 scripts.md 20.1 KB
- 📄 setup.md 8.8 KB
- 📄 troubleshooting.md 3.8 KB
- 📄 workflow.md 11.4 KB
📁 prompts/
- 📁 en/
  - 📄 deep-analysis.md 29.0 KB
  - 📄 filter.md 4.2 KB
  - 📄 gap-fill.md 7.7 KB
  - 📄 index.md 1.4 KB
  - 📄 opensource-scan.md 2.0 KB
- 📄 deep-analysis.md 24.8 KB
- 📄 filter.md 3.5 KB
- 📄 gap-fill.md 6.3 KB
- 📄 index.md 1.2 KB
- 📄 opensource-scan.md 1.7 KB
📁 scripts/
- 📄 analysis-engine.js 12.8 KB
- 📄 analyze-single-paper.js 3.2 KB
- 📄 backfill_papers.py 10.4 KB
- 📄 backup-data.sh 2.1 KB
- 📄 batch-analyze.js 4.0 KB
- 📄 config.js 7.3 KB
- 📄 deep-analysis-only.js 4.4 KB
- 📄 deep-analyzer.js 37.1 KB
- 📄 fetch-huggingface-papers.js 11.6 KB
- 📄 fetch-papers.js 19.1 KB
- 📄 full-fetch.js 19.0 KB
- 📄 log-setup.js 3.0 KB
- 📄 log_setup.py 2.0 KB
- 📄 publish-to-blog.py 43.1 KB
- 📄 publish-to-feishu.py 11.5 KB
- 📄 publish-wechat-full.py 13.2 KB
- 📄 publish-xiaohongshu.py 10.4 KB
- 📄 publish_common.py 6.7 KB
- 📄 quick-test.js 2.9 KB
- 📄 reanalyze-selected.js 3.5 KB
- 📄 reanalyze.js 6.4 KB
- 📄 test-api-key.js 3.4 KB
- 📄 utils.js 33.7 KB
- 📄 utils.py 21.3 KB
- 📄 xiaohongshu-publisher.py 31.0 KB
📁 tests/
- 📄 config.test.js 3.8 KB
- 📄 utils.test.js 8.1 KB
📄 .gitignore 398 B
📄 LICENSE 1.0 KB
📄 package-lock.json 18.0 KB
📄 package.json 1.4 KB
📄 README.en.md 6.5 KB
📄 README.md 5.9 KB
📄 run-full-fetch.sh 326 B
📄 SKILL.en.md 32.8 KB
📄 SKILL.md 29.5 KB

SKILL.md

---
name: audio-paper-digest
description: >
  语音/音乐/音频论文速递自动化技能。抓取 arXiv + HuggingFace Papers，使用环境变量配置的 LLM 做筛选与深度分析，
  输出结构化 JSON，并可发布到 GitHub Pages 博客、微信公众号草稿与小红书文案。
  适用场景：论文速递、论文摘要、每日追踪、重分析、博客发布、微信发布与小红书发布。
---

**[English](SKILL.en.md)** | 中文

# Paper Digest Skill（以当前代码为准）

## 1. 文档定位

- `SKILL.md`：给 Agent 的执行规则与安全约束
- `README.md`：给人的运行手册（命令、配置、排错）
- `prompts/filter.md`：筛选阶段 LLM prompt
- `prompts/deep-analysis.md`：深度分析阶段 LLM prompt（输出格式、标签体系、评分标准）

当文档与代码冲突时，**以 `scripts/*` 当前实现为准，并同步更新文档**。

---

## 2. 当前真实流程

主入口：`./run-full-fetch.sh`（或 `node scripts/full-fetch.js` / `npm run fetch`）

1. **自动归档**：检查 `data/current/deep-analysis-result.json` / `filtered-papers.json` / `analyzed.json`，若时间戳早于今天（北京时间）且 `data/archive/<日期>/` 下不存在，则复制后删除原文件。**`papers.json` 不归档。**
2. **arXiv 抓取**：7 个分类，每类最多 100 篇（可通过 `PD_ARXIV_MAX_RESULTS` 调整），遇连续 20 篇已有 ID 提前停止
3. **HuggingFace 抓取**：`daily_papers` 分页（最多 20 页）+ `papers` API 补充，默认近 7 天
4. **合并去重**：arXiv 优先，HF 补充 7 个特有字段，标记 `sources`
5. **LLM 筛选**：按 `PAPER_ANALYZER_*` 配置逐篇判断语音/音乐/音频相关，`batchSize=5`（可通过 `PD_FILTER_BATCH_SIZE` 调整），单篇超时 60 秒，重试 3 次
6. **保存筛选结果**：`data/current/filtered-papers.json`
7. **深度分析**：`deep-analyzer.js`，全文+图片，并发 3 篇（可通过 `PD_ANALYSIS_CONCURRENCY` 调整），每篇最多重试 2 次（可通过 `PD_ANALYSIS_MAX_RETRIES` 调整）
8. **增量保存**：每批分析后立即保存到 `data/current/deep-analysis-result.json`，自带失败结果保护（已有成功 analysis 的论文不会被无 analysis 的失败结果覆盖）
9. **更新去重库**：追加新论文 ID 到 `data/current/papers.json`，自动备份 papers.json（保留最近 7 天）
10. **收尾合并**：去重合并历史结果，自动备份 bak 文件（保留最近 10 个）

`full-fetch.js` **不会自动发布博客/微信**，发布需单独运行 Python 脚本。

---

## 3. 数据路径规范

### 3.1 优先路径（当前）

| 文件 | 用途 | 归档行为 |
|------|------|---------|
| `data/current/papers.json` | 论文去重数据库 | **不归档**，持续累积 |
| `data/current/filtered-papers.json` | 筛选后的论文元数据 | 每日归档移走后重新生成 |
| `data/current/deep-analysis-result.json` | 核心分析结果（含 analysis / parsed / imageUrls） | 每日归档移走后重新生成 |
| `data/current/analyzed.json` | 旧版已分析记录（兼容） | 每日归档移走后重新生成 |

### 3.2 兼容行为

部分脚本在读取时兼容 `data/*.json` 旧路径，但新产物应写入 `data/current/`。

### 3.3 归档目录

`data/archive/<YYYY-MM-DD>/` 按日期子目录存放当日归档文件。`deep-analysis-result-<时间戳>.bak.json` 备份文件也存放在此目录下，自动清理保留最近 10 个。

---

## 4. 模型与环境变量

### 4.1 统一存放位置

**所有环境变量统一放在 `~/.hermes/.env`。** `.zshrc` 已配置：
```zsh
set -a; source ~/.hermes/.env 2>/dev/null; set +a
```

这意味着：
- shell 启动时自动注入所有变量
- Python 脚本直接通过 `os.environ` 读取
- Node 脚本通过 `loadEnvFile()` 二次兜底（仅补未设置的变量）

### 4.2 筛选阶段（`fetch-papers.js`）

筛选统一调用 `PAPER_ANALYZER_*` 指定的 LLM：

- endpoint: `PAPER_ANALYZER_ENDPOINT`（必填）
- key: `PAPER_ANALYZER_API_KEY`（必填）
- model: `PAPER_ANALYZER_MODEL`（必填）
- **API 协议自动路由**：`scripts/utils.js` 中的 `detectApiType()` 会根据端点和模型名自动判断使用 OpenAI 还是 Anthropic 协议
  - **MiMo/Kimi Token Plan / Coding Plan**（端点含 `token-plan` 或 `coding`，模型含 `mimo`/`kimi`）→ 自动切换为 **Anthropic 协议**，伪装成 Claude Code 调用
    - **MiMo**: `https://token-plan-cn.xiaomimimo.com/v1` → `https://token-plan-cn.xiaomimimo.com/anthropic/v1/messages`（替换 `/v1` 为 `/anthropic`）
    - **Kimi**: `https://api.kimi.com/coding/v1` → `https://api.kimi.com/coding/v1/messages`（直接加 `/messages`，无需 `/anthropic` 中间路径）
    - Headers: `x-api-key` + `anthropic-version: 2023-06-01` + `User-Agent: claude-cli/<version> (external, cli)`（版本号动态获取自本地 `claude --version`，失败回退到 `2.1.108`）
    - system message 自动提取为请求体顶级字段（Anthropic 要求）
  - **其他情况**（包括 MiMo 按量付费、通用 OpenAI 兼容端点）→ 使用标准 **OpenAI 协议**
    - URL: `/v1/chat/completions`
    - Headers: `Authorization: Bearer {key}`
- **agent: `false`** — LLM API 请求明确禁用连接复用，避免全局 agent 连接池被代理污染导致 MiMo 403（详见 9.2）
- 超时 60 秒，重试 3 次，每次重试独立创建 AbortController
- 指数退避：抓取 4s/8s/16s（`2^attempt * 2s`，上限 60s），限流 10s/20s/40s（`2^attempt * 5s`，上限 60s）
- prompt 来源：`prompts/filter.md`，运行时通过 `loadPrompt()` 读取并替换 `{title}`、`{abstract}`、`{categories}` 占位符
- 判定口径：多模态模型只要明确涉及语音/音乐/音频（输入、输出、训练目标、评测任务或核心能力之一）即判定为相关
- 冲突处理：若同时满足"多模态涉及语音/音乐/音频"和"其他领域"描述，优先判定为"是"

### 4.3 深度分析阶段（`deep-analyzer.js`）

深度分析统一使用 `PAPER_ANALYZER_*` 指定的 LLM，**与筛选阶段共用同一套 API 协议自动路由逻辑**：

- endpoint: `PAPER_ANALYZER_ENDPOINT`（必填）
- key: `PAPER_ANALYZER_API_KEY`（必填）
- model: `PAPER_ANALYZER_MODEL`（必填）
- `detectApiType()` 自动判断协议类型，行为与 4.2 节一致
  - **MiMo**: `/v1` → `/anthropic/v1/messages`
  - **Kimi**: `/coding/v1` → `/coding/v1/messages`

API 调用特性：
- 整体超时 20 分钟（AbortController）
- max_tokens=64000，temperature=0.7
- **双层重试**：analysis-engine.js 层面每篇最多重试 2 次（总共最多 3 次尝试）；deep-analyzer.js 内部每次 API 调用再重试最多 3 次（指数退避：第一次 10 秒，之后翻倍，`2^attempt * 5s`）
- **LLM API 请求明确设置 `agent: false`，强制直连以绕过本地代理（避免 MiMo 403）；arXiv/HuggingFace 等外部抓取仍使用代理自动检测**
- arXiv HTML 解析使用 **cheerio** 结构化选择器，移除 script/style/nav/header/footer 等噪音元素
- 图片下载 **并行化（并发 3）**，下载论文全部图片（无数量限制）；单张 base64 上限约 20M 字符（config.js 中 `imageMaxBase64Chars`）；超时后自动降级为纯文本重试
- 全文上限约 500K 字符（config.js 中 `fullTextMaxChars`）
- 所有分析配置集中管理于 `scripts/config.js`，支持环境变量覆写

输出约束：
- prompt 来源：`prompts/deep-analysis.md`，运行时通过 `loadPrompt()` 读取并替换 `{hasFullText}`、`{title}`、`{authors}`、`{categories}`、`{arxivId}`、`{textForAnalysis}` 占位符
- 固定一级标题：`## 评分`、`## 机器摘要`、`## 标签`、`## 作者与机构`、`## 毒舌点评`、`## 核心摘要`、`## 方法概述和架构`、`## 核心创新点`、`## 实验结果`、`## 细节详述`、`## 评分理由`、`## 局限与问题`、`## 开源详情`
- `## 评分` 下先输出总分（X.X/10）
- **代码后处理**：`parseAnalysis`/`parse_analysis` 会从 `## 评分理由` 中提取七个分项（创新性/3、技术严谨性/1.5、实验充分性/1.5、清晰度/1、影响力/2、开源/1.5、可复现性/0.5）重新计算总分，四舍五入到 0.1，覆盖 LLM 原始总分
- `## 机器摘要` 包含 `rank_bucket`（带顶会映射）、`quality_score`（综合学术质量 0-7）、`value_score`（影响力 0-2）、`reproducibility_bonus`（可复现性综合 0-2）、`confidence`、`primary_task_tag`、`primary_method_tag` 等固定键
- 评分采用七维审稿人体系：创新性（0-3）+ 技术严谨性（0-1.5）+ 实验充分性（0-1.5）+ 清晰度（0-1）+ 影响力（0-2）+ 开源（0-1.5）+ 可复现性（0-0.5）
- **代码后处理**：`parseAnalysis`/`parse_analysis` 始终从 `## 评分理由` 提取分项重新计算总分，覆盖 LLM 原始输出，避免 LLM 算错总分
- 标签输出必须同时包含最终标签串、`主任务标签`、`主方法标签`、`补充标签`
- 缺失信息必须写"未说明/未提供/未提及"，禁止猜测作者机构、实验数字、开源状态或外部信息
- 修改 `prompts/deep-analysis.md` 或 `prompts/filter.md` 时，需同步检查 `scripts/utils.js` 与 `scripts/utils.py` 的解析逻辑是否仍能匹配新输出格式

### 4.4 微信公众号（`publish-wechat-full.py`）

- `WECHAT_APP_ID` 和 `WECHAT_APP_SECRET` 从 `os.environ` 读取
- `WECHAT_THUMB_MEDIA_ID`（可选）：封面图永久素材 ID，未设置时使用内置默认素材
- 图片上传：下载 arXiv 图片 → 上传到微信 CDN → 替换为微信 URL。缓存保存在系统临时目录下的 `wechat-image-cache.json`
- 该脚本会访问真实微信接口；除非用户明确要求生成或上传公众号草稿，否则不要执行
- **注意**：所有发布脚本统一从环境变量读取凭证，禁止硬编码

### 4.5 完整环境变量清单

```bash
# LLM API（筛选 + 深度分析，下面是 4 种常见配置方案，只能选一种启用）

# 方案 1: MiMo Token Plan（推荐，伪装 Claude Code 自动切换 Anthropic 协议）
PAPER_ANALYZER_API_KEY=tp-your-token-plan-key
PAPER_ANALYZER_MODEL=mimo-v2.5
PAPER_ANALYZER_ENDPOINT=https://token-plan-cn.xiaomimimo.com/v1

# 方案 2: MiMo 按量付费（通用 OpenAI 协议）
# PAPER_ANALYZER_API_KEY=sk-your-pay-as-you-go-key
# PAPER_ANALYZER_MODEL=mimo-v2.5
# PAPER_ANALYZER_ENDPOINT=https://api.xiaomimimo.com/v1

# 方案 3: Kimi Coding Plan（伪装 Claude Code 自动切换 Anthropic 协议）
# PAPER_ANALYZER_API_KEY=sk-your-kimi-key
# PAPER_ANALYZER_MODEL=kimi-for-coding
# PAPER_ANALYZER_ENDPOINT=https://api.kimi.com/coding/v1

# 方案 4: 通用 OpenAI 兼容端点
# PAPER_ANALYZER_API_KEY=sk-your-openai-key
# PAPER_ANALYZER_MODEL=gpt-4o
# PAPER_ANALYZER_ENDPOINT=https://api.openai.com/v1

# 微信公众号
WECHAT_APP_ID=your-app-id
WECHAT_APP_SECRET=your-app-secret
# WECHAT_THUMB_MEDIA_ID=your-thumb-media-id  # 封面图永久素材 ID（可选，未设置时使用默认素材）

# 飞书文档
FEISHU_APP_ID=your-feishu-app-id
FEISHU_APP_SECRET=your-feishu-app-secret

# 博客发布
# PAPER_DIGEST_BLOG_REPO=~/code/github_repos/audio-paper-digest-blog
# PAPER_DIGEST_BLOG_BASE_PATH=/audio-paper-digest-blog
# PAPER_DIGEST_BLOG_URL=https://nanless.github.io/audio-paper-digest-blog/posts
# PAPER_DIGEST_GITHUB_REMOTE=origin

# 微信公众号作者（可选）
# PAPER_DIGEST_AUTHOR=your-name

# 配置覆写（可选）
# PD_ANALYSIS_CONCURRENCY=3       # 深度分析并发度
# PD_ANALYSIS_MAX_RETRIES=2       # 深度分析重试次数
# PD_REANALYZE_CONCURRENCY=3      # 重分析并发度（默认与 ANALYSIS_CONFIG.concurrency 一致）
# PD_FILTER_BATCH_SIZE=5          # LLM 筛选每批篇数
# PD_ARXIV_MAX_RESULTS=100        # arXiv 每类抓取数量

# 代理（可选，但建议为 MiMo Token Plan 关闭或绕过代理）
# https_proxy=http://127.0.0.1:7897
# http_proxy=http://127.0.0.1:7897
# all_proxy=socks5://127.0.0.1:7897
```

**API 协议自动路由概览**：

| 端点特征 | 模型特征 | 自动路由 | Anthropic URL 转换 |
|----------|----------|----------|-------------------|
| 含 `token-plan` | 含 `mimo` | Anthropic | `/v1` → `/anthropic/v1/messages` |
| 含 `coding` | 含 `kimi` | Anthropic | `/coding/v1` → `/coding/v1/messages` |
| 任意其他 | 任意其他 | OpenAI | `/v1/chat/completions` |

端点配置格式统一为 `协议://域名/v1`，不管后续用哪种协议，配置方式一致。

---

## 5. 常用命令（当前可用）

```bash
cd ~/.hermes/skills/openclaw-imports/audio-paper-digest

# 全流程（抓取 + 筛选 + 深度分析）
npm run fetch
# 或 ./run-full-fetch.sh

# 仅深度分析续跑（跳过已有 analysis）
npm run deep

# 全量重分析（默认读取 data/current/deep-analysis-result.json）
npm run reanalyze

# 指定并发度重分析
node scripts/reanalyze.js --concurrency 3 data/current/deep-analysis-result.json

# 运行单元测试
npm test

# 快速抓取测试（仅抓+筛选，不分析，输出 data/quick-test-result.json）
node scripts/quick-test.js

# 批量分析未分析论文（基于 deep-analysis-result.json）
npm run batch

# 单独分析一篇论文（命令行参数）
node scripts/analyze-single-paper.js 2604.16044

# 补录历史 paper ID（不做深度分析）
npm run backfill

# 发布博客（建议显式指定日期）
npm run publish -- --date YYYY-MM-DD

# 只生成 markdown，不推送
npm run publish -- --skip-push --date YYYY-MM-DD

# 使用自定义数据文件发布
npm run publish -- --date YYYY-MM-DD data/current/deep-analysis-result.json

# 生成微信公众号草稿（默认读 data/current/deep-analysis-result.json）
npm run wechat

# 生成小红书文案（默认 TOP 5 精选版）
npm run xiaohongshu
npm run xiaohongshu -- --top 7     # 指定 TOP N
npm run xiaohongshu -- --all       # 完整汇总版
npm run xiaohongshu -- --date 2026-04-22
```

**小红书发布经验：**

- 小红书单帖正文限制约 1000 字，TOP 3 模式默认约 800-950 字符，适合单帖直接发布
- **每篇论文的一句话介绍调用 MiMo LLM API 生成**（anthropic 协议，绕过代理），LLM 失败时回退到本地 `extract_one_liner()`（优先取 innovation 第一条，其次 summary 中含"提出了/解决了/旨在"的句子，最后 roast）
- 脚本会自动清理 Markdown 格式（`**加粗**`、`` 代码 ``）和学术化前缀（"这篇论文旨在"、"本文针对"等），避免平台渲染异常
- 文案自动附带 emoji 热度标识：🔥≥8 分、✅≥6 分、📝<6 分（与博客、微信统一）
- 末尾固定附博客链接和开源仓库链接，不输出标签和 `---` 分隔线
- `--all` 模式输出更长，适合分篇发或自选精华发布

---

## 6. 发布行为与日期安全

发布脚本：`scripts/publish-to-blog.py`

### 核心原则：博客日期 = 爬取分析日期，≠ arXiv 上传日期

- `published` 字段是论文在 arXiv 上的原始发布日期，可能早于今天
- **博客的 `YYYY-MM-DD` 日期代表「今天爬取并分析」的批次**，不是论文原始发布日期
- `deep-analysis-result.json` 已经是「今天抓取 → 和 `papers.json` 去重 → LLM 筛选」后的结果，其中所有论文都应发布在 today's blog 下

当前行为：

- 默认读 `data/current/deep-analysis-result.json`
- **按 `fetchedAt` 日期过滤**：只发布 `fetchedAt` 匹配 `--date` 指定日期的论文（默认今天），避免历史数据被重复发布
- 在 `~/code/github_repos/audio-paper-digest-blog/content/posts` 生成：
  - 汇总页：`YYYY-MM-DD.md`
  - 单篇页：`YYYY-MM-DD-<slug>.md`
- 默认会执行 `git add -A`、`git commit`、`git push origin main`
- 若需发布全部论文（不过滤），可手动修改脚本或使用自定义数据文件

Agent 执行约束：

- 默认仅允许使用 `--skip-push` 模式验证博客生成结果
- 只有用户明确要求"正式发布 / 推送博客"时，才允许去掉 `--skip-push`
- 若只是检查格式、验证新字段或预览产物，禁止触发真实 `git push`

发布前保障：

- `full-fetch.js` 每天运行时会自动归档移走昨天的 `deep-analysis-result.json`、`filtered-papers.json` 和 `analyzed.json`，确保 `data/current/` 下只有当天新抓取的论文
- 若意外混入非当日论文，它们也会被发布在今天的博客下，所以必须确保每天运行前 `data/current/` 已清空

### 重跑/修复当天的正确姿势

若当天结果需要清空重跑：

1. 删除 `data/current/filtered-papers.json`、`data/current/deep-analysis-result.json`
2. **恢复 `papers.json` 到昨天状态**（推荐，比个删 ID 更可靠）：
   ```bash
   # 用昨天备份替换去重库（backupPapersJson 生成，格式为 papers-YYYY-MM-DD.json）
   cp data/archive/papers-2026-04-21.json data/current/papers.json
   ```
3. 删除博客仓库中当天的所有 `content/posts/YYYY-MM-DD-*.md` 文件
4. 重新运行 `npm run fetch`

**特殊场景——筛选阶段 API 全面失败（如 34→0 篇）：**
- 即使筛选为 0 篇，`papers.json` 也已被污染（新增 ID 已写入），必须按步骤 1-2 清理后重跑。
- 若修复后立即重跑，可用 `npm run batch` 续跑深度分析（无需重新抓取）。

**关键教训——恢复 `papers.json` 前必须检查 `lastUpdated`：**

第一次运行中断后，不要盲目恢复任何备份！必须先确认 `papers.json` 的状态：

```bash
# 检查 papers.json 最后更新时间
ls -la data/current/papers.json
# 或读取 lastUpdated 字段
cat data/current/papers.json | python3 -c "import json,sys; d=json.load(sys.stdin); print(d.get('lastUpdated'))"
```

判断规则：
| `papers.json` 的 `lastUpdated` | 正确操作 |
|-------------------------------|---------|
| **今天**（如 `2026-04-23T03:09:03`）| **不要恢复！** 它已经是最新状态，直接删除 `filtered-papers.json` 后重新运行即可 |
| **昨天或更早** | 可以恢复备份：`cp data/archive/papers-YYYY-MM-DD.json data/current/papers.json` |

推荐检查命令（可选）：

```bash
python3 - <<'PY'
import json
from collections import Counter
with open('data/current/deep-analysis-result.json') as f:
    d = json.load(f)
papers = d.get('papers', [])
dates = [p.get('published', '')[:10] for p in papers if p.get('published')]
print('总论文:', len(papers))
print('日期分布:', Counter(dates))
PY
```

---

## 7. 日志与运行特性

- Node 脚本统一通过 `scripts/log-setup.js` 输出日志到 `logs/<script>-YYYYMMDD-HHMMSS.log`
- Python 脚本统一通过 `scripts/log_setup.py` 输出日志到 `logs/<script>-YYYYMMDD-HHMMSS.log`
- **自动清理**：每次启动时清理旧日志，保留最近 50 个
- `backfill_papers.py` 额外写独立日志到 `logs/backfill.log`
- 主要 Node 脚本已处理后台 stdout 缓冲（`setBlocking`），便于实时查看进度
- `full-fetch.js` / `deep-analysis-only.js` / `batch-analyze.js` 采用重试与增量保存，降低中断丢数风险
- `reanalyze.js` 每 5 篇保存一次中间结果（并发模式下自动调整保存间隔）
- `full-fetch.js` 自动备份 bak 文件到 `data/archive/`，保留最近 10 个
- `full-fetch.js` 自动备份 `papers.json` 到 `data/archive/papers-<日期>.json`，保留最近 7 天

---

## 8. Agent 执行规则（强约束）

1. **先查再改**：先读取相关脚本确认当前行为，再更新文档或执行命令。
2. **发布需确认日期**：未明确日期时，先问用户；默认不要依赖"今天"。
3. **禁止危险操作**：未获明确授权，禁止 `git reset --hard`、`git push -f`、批量删除历史文章。
4. **不自动扩展流程**：运行 `full-fetch.js` 后，不要擅自追加博客/微信发布，除非用户明确要求。
5. **改动留痕**：流程、参数、路径变化后，同步更新 `SKILL.md` 和 `README.md`。
6. **禁止硬编码密钥**：不要在任何脚本或文档中写入真实 API key；所有凭证（LLM、微信公众号、飞书）统一从环境变量读取，LLM 配置放在 `~/.hermes/.env`（由脚本自动 `source`），微信/飞书凭据也写入 `~/.hermes/.env`。
7. **修改脚本时防止安全机制破坏**：本环境会静默替换 `API_KEY` 等敏感字符为 `***`。修改含有这类字符的脚本时，修改后必须重新读取文件验证关键行未被破坏。同时定期检查 `data/`、`logs/` 目录是否残留含密钥的备份文件或日志快照，发现立即清理。
8. **环境变量统一管理**：新增脚本需要读取 LLM 配置时，统一使用 `PAPER_ANALYZER_API_KEY`、`PAPER_ANALYZER_MODEL`、`PAPER_ANALYZER_ENDPOINT`，禁止引入别名回退链、硬编码或 base64 编码变量名 hack。
9. **新增可配置参数放入 config.js**：新增脚本涉及可调整参数（并发度、超时、批次大小等）时，统一放入 `scripts/config.js` 并添加对应的环境变量覆写支持。
10. **新增分析脚本复用 analysis-engine.js**：新增论文分析相关脚本时，优先复用 `analysis-engine.js` 的 `analyzeBatch()` / `analyzePaperWithRetry()`，避免重复实现重试、解析、保存逻辑。
11. **博客验证默认不推送**：未获用户明确授权时，运行 `publish-to-blog.py` 必须带 `--skip-push`。
12. **输出契约改动要同步 parser**：若修改 `prompts/deep-analysis.md` 中的 `## 机器摘要` 键名、章节顺序或标签输出格式，必须同步检查 `scripts/utils.js` 与 `scripts/utils.py` 的解析逻辑。
13. **变更后必须做产物级验证**：至少抽样检查一份 `data/current/deep-analysis-result.json`，确认存在 `rank_bucket`、`primary_task_tag`、`primary_method_tag` 等字段，再运行博客/社媒脚本验证最终产物。
14. **变更后验证 prompt 加载**：修改 `prompts/` 目录下的 markdown 文件后，运行一次快速测试（`node scripts/quick-test.js` 或单篇分析）确认 `loadPrompt()` 能正确读取并替换占位符，无 `{变量名}` 残留。
15. **变更后运行单元测试**：修改 `scripts/utils.js`、`scripts/config.js` 或分析引擎核心逻辑后，必须运行 `npm test` 确保测试通过。
16. **MiMo API 请求必须禁用代理连接复用**：`fetch-papers.js` 和 `deep-analyzer.js` 中调用 LLM API 时，`options.agent` 必须为 `false`（不是 `undefined`）。任何重构或修改 HTTP 请求逻辑时，禁止将 `agent: false` 改回 `agent: proxyAgent` 或 `agent: undefined`，否则 MiMo Token Plan 会在有系统代理的环境中返回 403。
17. **新增 LLM 端点必须接入 API 协议自动路由**：任何新增脚本调用 LLM 时，统一使用 `scripts/utils.js` 中的 `detectApiType()`、`buildApiUrl()`、`buildHeaders()`、`buildRequestBody()`、`parseResponseText()`，禁止硬编码特定协议的 URL/Header/Body。
18. **修改 API 协议路由逻辑时同步全链路**：修改 `detectApiType()` 的判定规则或 `buildApiUrl()`/`buildHeaders()` 等函数时，必须同步检查 `fetch-papers.js`、`deep-analyzer.js` 以及所有使用 `analysis-engine.js` 的脚本（`full-fetch.js`、`reanalyze.js`、`batch-analyze.js`、`deep-analysis-only.js`、`analyze-single-paper.js`），确保全链路行为一致。
19. **禁止将敏感文件提交到版本控制**：`data/`、`logs/`、`*.env`、`*.backup*`、缓存文件、含密钥的日志归档等严禁进入 git；提交前必须确认 `.gitignore` 已正确配置，且仓库中不存在历史遗留的敏感文件。

---

## 9. 最小排错手册

### 9.1 模型调用失败 / API 返回 401 / 403 / timeout

**检查步骤**：

1. **检查 key/endpoint/model 三元组是否匹配**
   | 套餐类型 | 端点 | Key 前缀 | 协议 |
   |---------|------|----------|-------|
   | MiMo Token Plan | `token-plan-cn.xiaomimimo.com/v1` | `tp-` | Anthropic（自动切换） |
   | MiMo 按量付费 | `api.xiaomimimo.com/v1` | `sk-` | OpenAI |
   | Kimi Coding Plan | `api.kimi.com/coding/v1` | `sk-kimi-...` | Anthropic（自动切换） |
   | 通用 OpenAI | 自定义端点 | `sk-...` | OpenAI |

   - MiMo Token Plan key 前缀为 `tp-`，必须配合 Token Plan 端点，两者混用必返回 401
   - 确保 `.env` 已正确配置，且 `.zshrc` 已 source

2. **检查是否走对了协议**（日志中查找 `[filter] API 类型: xxx` 或 `[api] → model | xxx` 行）
   - 若使用 MiMo/Kimi Token Plan 却显示 `openai`，检查端点是否含 `token-plan` 或 `coding`，模型是否含 `mimo` 或 `kimi`
   - 若日志显示 `anthropic`但仍失败，检查是否走的是 `/anthropic/v1/messages` 路径（不是 `/v1/chat/completions`）

3. **Anthropic 协议专项检查**（日志显示 `anthropic` 时）
   - 请求头是否为 `x-api-key`（非 `Authorization: Bearer`）
   - 是否带 `anthropic-version: 2023-06-01`
   - 是否带 `User-Agent: claude-cli/<version> (external, cli)`（日志不会直接显示，可用代理工具验证）

4. **OpenAI 协议专项检查**（日志显示 `openai` 时）
   - 确认使用 `Authorization: Bearer {key}`
   - 确认 URL 路径是 `/v1/chat/completions`

5. **检查代理**（见 9.2 节）
   - MiMo Token Plan 在有系统代理时可能被屏蔽
   - 尝试用 `curl --noproxy "xiaomimimo.com"` 绕过代理测试

6. **查看日志**：`logs/full-fetch-*.log`、`logs/deep-analyzer-*.log`

### 9.2 MiMo API 返回 403 Illegal access / timeout / socket hang up

**根因**：Node.js `https.request` 的 `agent: undefined` 仍会复用全局默认 agent 的连接池。当系统配置了代理（`https_proxy` 等环境变量）时，全局 agent 的连接可能被代理污染，导致 MiMo Token Plan 服务端拒绝请求。

**修复**：`fetch-papers.js` 和 `deep-analyzer.js` 中 LLM API 请求的 `options.agent` 必须设为 `false`（不是 `undefined`），彻底禁用连接复用，强制每个请求建立新连接：

```javascript
const options = {
    hostname: url.hostname,
    path: url.pathname,
    method: 'POST',
    headers: headers,
    agent: false,  // ← 必须是 false，undefined 无效
    signal: controller.signal
};
```

**验证**：直接用 `curl --noproxy "xiaomimimo.com"` 测试，若绕过代理成功而脚本失败，即为此问题。

### 9.3 深度分析慢或频繁失败

- 查看日志：`logs/deep-analyzer-*.log`、`logs/full-fetch-*.log`
- 检查 key/endpoint/model 三元组是否匹配（见 9.1 节）
- 若超时，脚本会自动降级为纯文本重试；若仍失败，检查代理或减小并发
- 可用 `node scripts/deep-analysis-only.js` 安全续跑

### 9.4 发布后无变更可推送

在博客仓库检查：
```bash
cd ~/code/github_repos/audio-paper-digest-blog
git status --short
ls -lt content/posts | head -20
```

### 9.5 路径混淆

优先使用 `data/current/deep-analysis-result.json`，仅在兼容场景下读取旧路径。

### 9.6 重分析启动报 key 未设置

- 在 `~/.hermes/.env` 中配置 `PAPER_ANALYZER_API_KEY`
- 重新 source：`source ~/.zshrc`

### 9.7 微信公众号发布失败

- 检查 `WECHAT_APP_ID` / `WECHAT_APP_SECRET` 环境变量是否已设置（在 `~/.hermes/.env`）
- 检查 `APP_SECRET` 是否过期
- 检查图片是否过大或被 arXiv 限制
- 微信图片上传有频率限制，大量图片可能需要分批执行

### 9.8 HuggingFace 抓取为空

- 检查网络连接（`curl https://huggingface.co/api/daily_papers?limit=10`）
- 检查是否被限流或需要代理
- `fetch-huggingface-papers.js` 使用 `curl` 命令，确保系统 `curl` 可用

### 9.9 验证 API 路由变更

当修改 `detectApiType()` 或 `buildApiUrl()` 后，必须用以下测试脚本验证两个端点都正常：

```bash
# 纯文本测试
node -e "
const u = require('./scripts/utils.js');
const cases = [
  ['MiMo', 'https://token-plan-cn.xiaomimimo.com/v1', 'mimo-v2.5'],
  ['Kimi', 'https://api.kimi.com/coding/v1', 'kimi-for-coding'],
  ['OpenAI', 'https://api.openai.com/v1', 'gpt-4o']
];
for (const [name, ep, model] of cases) {
  const t = u.detectApiType(ep, model);
  const url = u.buildApiUrl(t, ep);
  console.log(name + ': ' + t + ' -> ' + url);
}
"
```

确保输出符合预期：
- MiMo → `anthropic` → `.../anthropic/v1/messages`
- Kimi → `anthropic` → `.../coding/v1/messages`（无 `/anthropic` 中间路径）
- OpenAI → `openai` → `.../v1/chat/completions`

**重要经验**：Kimi 和 MiMo 的 Anthropic URL 结构不同，修改 `buildApiUrl()` 时必须分支处理。

### 9.10 后台运行 full-fetch 被 SIGTERM 中断 (exit code 143)

**根因**：npm 脚本在后台模式下尝试访问 TTY 交互，导致 bash 报错并终止进程。

**修复**：后台运行时使用直接 Node 命令，绕过 npm：
```bash
# ❌ 后台模式避免使用
npm run fetch

# ✅ 后台运行推荐方式
node scripts/full-fetch.js
```

如果已在筛选阶段中断，需要按第 6 节"重跑/修复当天的正确姿势"处理：
1. 检查 `papers.json` 的 `lastUpdated` 是否为今天（见 6 节判断矩阵）
2. 如果是今天，不要恢复 papers.json，直接删除 `filtered-papers.json` 后重跑
3. 如果是昨天或更早，恢复 `papers.json` 备份后重跑

---

## 10. 相关子技能

### 轻量论文速递

#### arXiv Trending (`references/arxiv-digest.md`)
Daily AI/ML trending papers from HuggingFace Papers with accessible interpretations. Fetches trending papers, ranks by combined score (position + upvotes + freshness), generates plain-language summaries. Supports automated daily delivery via cron.
- Script: `scripts/fetch_papers.py`
- Output: JSON or Markdown
- Deduplication: history tracking

#### Daily Paper Digest (`references/daily-paper-digest.md`)
Aggregates latest AI papers from arXiv and HuggingFace, formats output for chat apps (Feishu, Slack, Discord). Configurable sources and keyword filters via `config/sources.json`.
- Scripts: `main.py`, `arxiv_fetcher.py`, `huggingface_fetcher.py`
- Triggers: `论文速递`, `今日论文`, `最新论文`, `/papers`, `/digest`

登录后下载/点赞/收藏 ❤ 31 | ★ 0

audio-paper-digest

目录结构

SKILL.md

举报内容

提示