메뉴
语音/音乐/音频论文速递自动化技能。抓取 arXiv + HuggingFace Papers，使用环境变量配置的 LLM 做筛选与深度分析， 输出结构化 JSON，并可发布到 GitHub Pages 博客、微信公众号草稿与小红书文案。 适用场景：论文速递、论文摘要、每日追踪、重分析、博客发布、微信发布与小红书发布。
Codex 또는 Claude로 설치 이 Prompt를 복사해 Codex, Claude 또는 다른 어시스턴트에 붙여 넣으면 Skill 페이지를 검토하고 설치를 진행할 수 있습니다.
SOC 직업 분류 기준
| name | audio-paper-digest |
| description | 语音/音乐/音频论文速递自动化技能。抓取 arXiv + HuggingFace Papers，使用环境变量配置的 LLM 做筛选与深度分析， 输出结构化 JSON，并可发布到 GitHub Pages 博客、微信公众号草稿与小红书文案。 适用场景：论文速递、论文摘要、每日追踪、重分析、博客发布、微信发布与小红书发布。 |
English | 中文
SKILL.md：给 Agent 的执行规则与安全约束README.md：给人的运行手册（命令、配置、排错）prompts/filter.md：筛选阶段 LLM promptprompts/deep-analysis.md：深度分析阶段 LLM prompt（纯文本，输出格式、标签体系、评分标准）prompts/image-supplement.md：图像筛选与补充 prompt（双模型模式，最终文本修复后副模型看图选图并补充正文）prompts/opensource-scan.md：开源链接扫描 prompt（Round 2）prompts/structure-repair.md：审校结果缺少必要章节时的主模型局部结构修复 promptprompts/scoring-audit.md：正文修复完成后的类型感知评分审计 prompt（主模型只输出 JSON 评分修订）当文档与代码冲突时，以 scripts/* 当前实现为准，并同步更新文档。
主入口：./run-full-fetch.sh（或 node scripts/full-fetch.js / npm run fetch）
data/current/deep-analysis-result.json / filtered-papers.json / analyzed.json，若时间戳早于今天（北京时间）且 data/archive/<日期>/ 下不存在，则复制后删除原文件。papers.json 不归档。data/current/papers.json 已有 ID；扫描 Hugo 博客仓库（PAPER_DIGEST_BLOG_REPO）中已发布论文的 arXiv ID，两者合并为统一去重集合PD_ARXIV_MAX_RESULTS 调整），每个分类完成后原子写入 fetch-checkpoint.json；中断后只补抓未完成分类，任一分页或摘要请求失败均不能标记该分类健康daily_papers 分页（最多 20 页）+ papers API 补充，默认近 7 天；来源完成后独立 checkpoint，必需请求、分页覆盖或日期截断不完整时整体失败并等待下次续跑sources；过滤掉博客已发布论文PAPER_ANALYZER_* 配置逐篇判断相关性，每批写入 filter-decisions.json。fetch-checkpoint、raw、decisions、filtered 共同绑定来源配置、历史去重集合和博客已发布集合的指纹；健康 raw 即使尚无 decisions 也能从空集合续跑，模型/prompt 变化只重筛该批候选，不重复抓取；只有明确决定完整覆盖候选全集时才可完成data/current/raw-candidates.json 保存筛选输入，data/current/filtered-papers.json 保存筛选/归档去重后的输出data/current/papers.json（不仅筛选通过的，提前保存防止后续中断丢失）deep-analyzer.js 完成全部论文的文本分析与评分审计；该阶段不建立或等待视觉任务。data/current/deep-analysis-result.json，自带失败结果保护（已有成功 analysis 的论文不会被无 analysis 的失败结果覆盖）；同时通过 scripts/digest-status.js 回写 papers.json.digestStatus。分析结果和论文库写入使用跨进程锁与 generation 校验，部分失败状态为 partial_failed 并返回非零退出码main OID 验证成功后，push-blog.py 自动建立最终评分 TOP 10 论文长图和一张批次汇总图任务。图片不进入或阻断本轮博客发布。Codex 使用内置 image_gen 处理 pending/failed 项，项目脚本只管理规划、验证、复制和 checkpoint，禁止调用图像 API。论文长图使用约 220–360 个中文字符，不得退化为口号式概念海报；若深度分析已选中并完整缓存论文关键图，任务按“方法总览/架构/流程优先，关键实验其次”绑定最多两张参考图、caption、MIME、缓存路径和 SHA。内置生图直接完成英文标题、中文说明、结构图、实验数据和纸张拼贴艺术的一体化最终构图，禁止再经过旧的确定性文字卡片合成器；登记前逐项目检标题、文字、箭头关系、指标方向和数值，不可读或存在实质错误必须重生成。两类图片统一采用暖白底与低饱和色的清新纸张编辑风，通过细微纸纹、纸片叠层、局部毛边、少量胶带和柔和投影建立层次；禁止脏旧复古、拥挤手账、深蓝霓虹、赛博 HUD、金属边框和仪表盘风格。full-fetch.js 不会自动发布博客/微信，发布需单独运行 Python 脚本。
| 文件 | 用途 | 归档行为 |
|---|---|---|
data/current/papers.json | 论文去重数据库（含 digestStatus 分析状态） | 不归档，持续累积；pending_analysis / analysis_failed 不参与强去重，便于中断后重跑；所有分析入口通过 scripts/digest-status.js 同步状态；旧成功分析保留时用 latestAttemptStatus 记录最新失败尝试 |
data/current/fetch-checkpoint.json | 逐来源抓取 checkpoint，绑定候选指纹、论文数量和稳定内容 SHA-256 | 同日原子更新；篡改或截短只重抓对应来源 |
data/current/raw-candidates.json | 当日合并与博客去重后的筛选候选，含 sourceHealth | 每次全流程重写，用于排查筛选输入 |
data/current/filter-decisions.json | 当日逐篇 LLM 筛选决策缓存，含 reason/rawResponse | 每批增量写入，模型或 prompt hash 变化后自动失效 |
data/current/filtered-papers.json | 筛选后的论文元数据 | 每日归档移走后重新生成 |
data/current/deep-analysis-result.json | 核心分析结果（含逐阶段 checkpoint、指纹、analysis / parsed / 图片与来源状态） | 每篇完成或失败后立即锁内保存；下次从首个未完成或指纹失效阶段续跑 |
data/current/visual-summary-manifests/YYYY-MM-DD.json | 全部博客发布后评分 TOP 10 的纵向长图状态，绑定排名、分析/prompt SHA 和资产 SHA | 仅失败、缺失或指纹变化的长图回到 pending |
data/current/digest-cover-manifests/YYYY-MM-DD.json | 全部博客发布后的批次汇总图状态 | 绑定论文集合、热门方向、排行榜和 prompt SHA |
data/current/xiaohongshu-oneliners-YYYY-MM-DD.json | 小红书逐篇一句话文案缓存，绑定分析、prompt、模型配置和清洗契约 | 每篇成功后原子保存；仅失败或输入变化的论文重跑 |
data/current/analyzed.json | 旧版已分析记录（兼容） | 每日归档移走后重新生成 |
部分脚本在读取时兼容 data/*.json 旧路径，但新产物应写入 data/current/。Python 发布入口通过 path_config.resolve_deep_analysis_result_path() 保持 current 优先、legacy 兜底。
data/archive/<YYYY-MM-DD>/ 按日期子目录存放当日归档文件。发布后生成的 TOP 10 论文长图按最终排行榜编号保存到 visual-summaries/01-<paper>/infographic.png 至 10-<paper>/infographic.png，汇总封面保存到 digest-cover/cover.png，不滞留在 data/current/。旧版 current 图片在下一次视觉 plan 时校验 SHA 后原子迁移。deep-analysis-result-<时间戳>.bak.json 备份文件也存放在归档目录，自动清理保留最近 10 个。
所有项目配置统一放在 项目根目录的 .env 文件。
这意味着：
scripts/env-loader.js / loadEnvFile() 读取项目根 .envscripts/project_env.py 读取项目根 .env.env；禁止外层环境变量与当前项目配置混用fetch-papers.js）筛选统一调用 PAPER_ANALYZER_* 指定的 LLM：
PAPER_ANALYZER_ENDPOINT（必填）PAPER_ANALYZER_API_KEY（必填）PAPER_ANALYZER_MODEL（必填）scripts/utils.js 中的 detectApiType() 会根据端点和模型名自动判断使用 OpenAI 还是 Anthropic 协议；完整优先级见第 4.2 节，DeepSeek 强制 OpenAI，token-plan+mimo / coding+kimi / 非 DeepSeek 的 /anthropic 走 Anthropic
token-plan 或 coding，模型含 mimo/kimi）→ 自动切换为 Anthropic 协议，伪装成 Claude Code 调用
https://token-plan-cn.xiaomimimo.com/v1 → https://token-plan-cn.xiaomimimo.com/anthropic/v1/messages（替换 /v1 为 /anthropic）https://api.kimi.com/coding/v1 → https://api.kimi.com/coding/v1/messages（直接加 /messages，无需 /anthropic 中间路径）x-api-key + anthropic-version: 2023-06-01 + User-Agent: claude-cli/<version> (external, cli)（版本号动态获取自本地 claude --version，失败回退到 2.1.108）/anthropic 端点 → 使用 Anthropic 协议并拼接 /messages/v1/chat/completionsAuthorization: Bearer {key}false — LLM API 请求明确禁用连接复用，避免全局 agent 连接池被代理污染导致 MiMo 403（详见 9.2）2^attempt * 1s（2s/4s/8s/16s/32s）；arXiv 页面抓取 429 限流时 60s * 2^(attempt-1)，其他错误线性 5s * attemptprompts/filter.md，运行时通过 loadPrompt() 读取并替换 {title}、{abstract}、{categories} 占位符deep-analyzer.js）深度分析统一使用 PAPER_ANALYZER_* 指定的 LLM，与筛选阶段共用同一套 API 协议自动路由逻辑：
PAPER_ANALYZER_ENDPOINT（必填）PAPER_ANALYZER_API_KEY（必填）PAPER_ANALYZER_MODEL（必填）detectApiType() 自动判断协议类型，行为与 4.2 节一致
/v1 → /anthropic/v1/messages/coding/v1 → /coding/v1/messagesAPI 调用特性：
2^attempt * 5s）agent: false 直连，不得注入代理 agent/dispatcher；arXiv/HuggingFace 抓取缺少项目 .env 代理必须失败，禁止直接回退。Node arXiv 仅使用 HTTPS_PROXY / HTTP_PROXY 的 HTTP CONNECT 地址，HuggingFace curl 可额外使用 SOCKS ALL_PROXY；访问本机代理的网络命令必须在沙箱外运行。imageCandidateMax=20）；HTML 正文与图注在同一次响应中解析并复用，预提供 URL 会按完整 URL或唯一文件名补全 caption。只有配置副模型的双模型模式才串行下载最多 imageMaxCount=20 张候选图片并送入副模型；成功内容写入 data/current/image-cache/，恢复时校验 MIME/文件头后复用。仅 408/425/429/5xx 和网络异常重试，404、非法 MIME、超限与安全拒绝立即终止imageManifest，记录图片发现数、候选评分、逐 URL 下载结果、缓存命中、插图计划哈希、拒绝原因和最终选图，便于复盘图像筛选analysisManifest；失败尝试保留 analysisCheckpoint 和独立的 analysisRecoveryImageManifest。失败合并会独立按完整契约重解析旧正文，不受最新失败 manifest 影响，连续多次失败也不能覆盖旧成功正文。arXiv HTML/图片发现默认单次 60 秒，PDF fallback 默认 180 秒；Demo 页面最多跟随 3 次重定向并逐跳重验公网 DNS/IP。只有严格的 {"insertions":[]} 才是有效空插图计划，缺字段、错误类型或非法 JSON 都保持为可重试失败fullTextMaxChars）scripts/config.js，支持在项目根 .env 中覆写输出约束：
prompts/deep-analysis.md，运行时通过 loadPrompt() 读取并替换 {hasFullText}、{title}、{authors}、{categories}、{arxivId}、{textForAnalysis} 占位符analysisSource、sourceId、原始/实际输入/全文字符数、truncated、sourceSha256、HTML 可用性和告警。稳定 400/403/404 不重复请求；版本化 ID 只读取指定版本；PDF 有 50MB 默认上限并校验 MIME、文件头与提取长度。全文不可用时优先使用完整摘要，不允许短错误页覆盖摘要## 评分、## 机器摘要、## 标签、## 作者与机构、## 毒舌点评、## 核心摘要、## 方法概述和架构、## 核心创新点、## 实验结果、## 细节详述、## 评分理由、## 局限与问题、## 开源详情## 评分 下先输出总分（X.X/10）parseAnalysis/parse_analysis 仅在 ## 评分理由 的八个分项完整、唯一、分母正确、数值有限且位于各自范围时重新计算总分；合计上限为 10，四舍五入到 0.1，覆盖 LLM 原始总分。缺失、重复、错误分母、负数、越界或非有限值会产生契约错误并阻断保存/发布，不存在最低 1 分保底## 机器摘要 包含 document_type、rank_bucket（带顶会映射）、innovation（创新性 0-2）、technical_rigor（技术严谨性 0-1.5）、experimental_sufficiency（实验充分性 0-1.5）、clarity（清晰度 0-1）、impact（影响力 0-1.5）、open_source（开源 0-1.5）、reproducibility（可复现性 0-0.5）、engineering_score（工程/实践价值 0-1.5）、confidence、primary_task_tag、primary_method_tag 等固定键type-aware-v1：document_type 只能取方法研究、系统技术报告、模型报告、数据集与基准、综述、理论研究、应用研究。类型只决定适用证据，不改变八维权重，也不提供固定加分、保底或豁免confidenceprompts/structure-repair.md 只修复当前论文结构，避免外层整篇重跑prompts/scoring-audit.md 做最终 JSON 评分审计；送审前由代码移除旧“评分理由”段，避免模型照抄待纠正的跨维度扣分，正文与原文证据账本保持不变；校验失败会把精确错误及违规分句反馈给下一次局部审计。无核心产物时，代码按“肯定语境承诺开放 0.5 / 明确 URL 或肯定结构化 Demo 0.2 / 否定或未提及 0”确定性归一化开源分和理由；理论研究按公开证明、推导和附录判断核心产物，不因代码/模型/数据标记为空而强制归零。代码只替换评分相关字段，副模型不参与评分selectedImageUrls 按最终正文顺序归一化。发布 review 必须保留 Markdown 表格中前导分组列为空的合法续行PD_IMAGE_INSERTION_MAX 可覆写），每张必须从代码生成的段落目录中选择稳定 paragraph_id；非法 ID、定位失败和超限图片由代码拒绝，不回退到章节末尾。旧自由文本 anchor 仅兼容历史响应。[secondary] 日志记录模型/协议/endpoint 与 key 来源、候选和下载数量、caption、缓存、段落 ID、JSON 解析状态、拒绝原因和最终选图；禁止打印 API key 内容主任务标签、主方法标签、补充标签prompts/deep-analysis.md 或 prompts/filter.md 时，需同步检查 scripts/utils.js 与 scripts/utils.py 的解析逻辑是否仍能匹配新输出格式配置 PAPER_ANALYZER_SECONDARY_MODEL 时启用双模型模式：
PAPER_ANALYZER_*）：纯文本深度分析，使用 prompts/deep-analysis.md（Round 1a）PAPER_ANALYZER_SECONDARY_*）：多模态图像筛选与插图计划，使用 prompts/image-supplement.md（最终文本修复后执行），需要支持图片输入的多模态模型（如 mimo-v2.5、gpt-4o 等）endpoint / key 不设置时分别回退到主模型的对应值paragraph_id、图前 lead、图后 explanation）。代码拒绝非法段落 ID 和超限计划，并忽略旧 replacement / rewrite 字段；副模型不得替换主模型任何原句，也不得输出完整分析报告或参与评分。publish-wechat-full.py）WECHAT_APP_ID 和 WECHAT_APP_SECRET 从 os.environ 读取WECHAT_THUMB_MEDIA_ID（可选）：封面图永久素材 ID，未设置时使用内置默认素材wechat-image-cache.json# 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
# 方案 5: 双模型模式（主模型纯文本 + 副模型多模态图像筛选与插图计划）
# 主模型配置同上（选方案 1-4 之一）
# 副模型（可选，不设置则退回单模型纯文本模式）
# PAPER_ANALYZER_SECONDARY_MODEL=mimo-v2.5
# PAPER_ANALYZER_SECONDARY_ENDPOINT=https://token-plan-cn.xiaomimimo.com/v1
# PAPER_ANALYZER_SECONDARY_API_KEY=tp-your-token-plan-key
# 注：副模型 endpoint/key 不设置时默认复用主模型的对应值
# 微信公众号
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 每类抓取数量
# PD_ARXIV_PDF_MAX_BYTES=52428800 # PDF fallback 最大字节数
# PD_SCORING_AUDIT_TEMPERATURE=0.1
# PD_IMAGE_PLAN_TEMPERATURE=0.2
# 抓取代理（必需）：arXiv 的 Node 请求必须使用 HTTP CONNECT 地址
# HTTPS_PROXY=http://127.0.0.1:7897
# HTTP_PROXY=http://127.0.0.1:7897
# HuggingFace 的 curl 可额外使用 SOCKS；LLM 请求固定 agent:false 直连
# ALL_PROXY=socks5h://127.0.0.1:7897
API 协议自动路由概览：
| 端点特征 | 模型特征 | 自动路由 | URL 转换 |
|---|---|---|---|
含 deepseek.com 或模型含 deepseek | — | OpenAI | /anthropic → /v1/chat/completions（优先级最高） |
含 token-plan | 含 mimo | Anthropic | /v1 → /anthropic/v1/messages |
含 coding | 含 kimi | Anthropic | /coding/v1 → /coding/v1/messages |
含 /anthropic | — | Anthropic | {base}/messages |
| 其他 | 其他 | OpenAI | /v1/chat/completions |
端点配置格式统一为 协议://域名/v1，不管后续用哪种协议，配置方式一致。
cd /path/to/audio-paper-digest
# 全流程（抓取 + 筛选 + 深度分析）
npm run fetch
# 或 ./run-full-fetch.sh
# 仅深度分析续跑（跳过已有 analysis；若尚无分析结果，会从 filtered-papers.json 初始化）
npm run deep
# 全量重分析（默认读取 data/current/deep-analysis-result.json）
npm run reanalyze
# 指定并发度重分析
node scripts/reanalyze.js --concurrency 3 data/current/deep-analysis-result.json
# 按日期重新筛选 + 重新分析
node scripts/refilter-reanalyze-by-date.js 2026-07-01
# 运行单元测试
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 --force
# 补录历史 paper ID（不做深度分析）
npm run backfill
# 博客必须分三阶段执行
npm run blog:generate -- --date YYYY-MM-DD
npm run blog:generate -- --date YYYY-MM-DD --exclude-id 2607.12345 # 明确排除单篇，可重复传入
npm run blog:review -- --date YYYY-MM-DD
npm run blog:push -- --date YYYY-MM-DD
# push 验证远端 main OID 后会自动建立发布后视觉任务；可幂等重跑
npm run visual:post-publish -- --date YYYY-MM-DD
npm run visual:status -- --date YYYY-MM-DD
npm run cover:status -- --date YYYY-MM-DD
# 使用自定义数据文件发布
npm run blog:generate -- --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
小红书发布经验：
--top 3 调整），正文约 800-950 字符，适合单帖直接发布publish_common.py 的协议路由并绕过代理），LLM 失败时回退到本地 extract_one_liner()（优先取 innovation 第一条，其次 summary 中含"提出了/解决了/旨在"的句子，最后 roast）.env 的 PD_XIAOHONGSHU_ONELINER_CONCURRENCY 调整为 1–5；完成顺序不会改变最终排名顺序，单篇异常只回退该篇--date 严格校验为 YYYY-MM-DD。本流程只生成文案，不触发自动发布parsed.summary、parsed.results、parsed.limitations、parsed.opensource 与主标签，再回退摘要，避免只复述标题**加粗**、代码）和学术化前缀（"这篇论文旨在"、"本文针对"等），避免平台渲染异常--- 分隔线--all 模式输出完整汇总文案，适合手动拆分或自选精华发布博客入口：scripts/generate-blog.py → scripts/review-blog.py → scripts/push-blog.py；scripts/publish-to-blog.py 只作生成兼容入口和共用实现。
published 字段是论文在 arXiv 上的原始发布日期，可能早于今天YYYY-MM-DD 日期代表「今天爬取并分析」的批次，不是论文原始发布日期deep-analysis-result.json 可能包含当日新增分析和合并保留的既有结果；博客、微信、飞书默认按 fetchedAt == --date 过滤，只有匹配批次日期的论文会发布到当天内容下当前行为：
data/current/deep-analysis-result.jsonfetchedAt 日期过滤：只发布 fetchedAt 匹配 --date 指定日期的论文（默认今天），避免历史数据被重复发布--exclude-id <arXiv ID>，只从本次 generation 权威快照排除明确命中的论文；ID 未命中会阻断，分析数据本身不变fetchedAt 日期过滤；如需发布输入文件全部论文，显式传 --all~/code/github_repos/audio-paper-digest-blog/content/posts 生成：
YYYY-MM-DD.mdYYYY-MM-DD-<slug>.mdgenerate-blog.py 在日期级跨进程锁内逐页生成、安装并写 journal；崩溃后可收养已完成的同 SHA 页面，全部论文完成后才生成汇总页和严格 generation manifest，禁止 review/commit/pushreview-blog.py 在同一日期锁内逐文件审查，checkpoint 绑定 worker 实际读取的 SHA；内容失败修复后只复审失败页，瞬时 LLM/网络错误保持待重试，任何已通过文件变化、应存在页面消失、清单/基线变化或 Hugo 前后 SHA 变化都会阻断凭证；禁止 commit/pushpush-blog.py 验证审查凭证和当前文件哈希，精确 stage 后及 commit 前再逐项校验 index blob SHA/删除状态，随后提交、推送并核对远端 OID；禁止重新生成或 reviewpublish-to-blog.py 必须在沙箱外运行：入口检测到可靠沙箱标志 CODEX_SANDBOX 会立即拒绝执行；沙箱外权限包装会保留网络禁用环境标志，不能据此误拒绝。原因是 review 会直连 LLM、下载图片并运行 Hugo，push 需要真实 Git 网络；不得在沙箱内跳过 review、伪造凭证或改用无网络降级路径。--allAgent 执行约束：
push-blog.pygit push发布前保障：
full-fetch.js 每天运行时会自动归档移走昨天的 deep-analysis-result.json、filtered-papers.json 和 analyzed.json，确保 data/current/ 下只有当天新抓取的论文fetchedAt == --date 过滤；仍需保持 data/current/ 干净，避免 review、校验和显式 --all 发布时混入不同批次若当天结果需要清空重跑：
data/current/filtered-papers.json 是今天且 status: complete，并且筛选指纹与当前配置一致：不要删筛选结果，直接运行 node scripts/full-fetch.js，主流程会跳过抓取/筛选并续跑深度分析；若仅筛选模型/prompt/协议参数变化且健康 raw 候选仍匹配，只重新筛选，不重复抓取。data/current/raw-candidates.json / filter-decisions.json 是今天、来源健康且模型/prompt hash 一致：直接运行 node scripts/full-fetch.js，主流程跳过抓取，只重试未决论文；不能删除这两个 checkpoint。data/current/fetch-checkpoint.json、data/current/raw-candidates.json、data/current/filter-decisions.json、data/current/filtered-papers.json、data/current/deep-analysis-result.jsonpapers.json 到昨天状态（推荐，比个删 ID 更可靠）：
# 用昨天备份替换去重库（backupPapersJson 生成，格式为 papers-YYYY-MM-DD.json）
cp data/archive/papers-2026-04-21.json data/current/papers.json
content/posts/YYYY-MM-DD-*.md 文件node scripts/full-fetch.js特殊场景——抓取或筛选 API 全面失败：
sourceHealth 的异常，禁止生成完整空批次。retryable，不会写入正式决定缓存，也不能把筛选产物标记为 complete；若同日候选来源健康，重跑主流程只复用候选和明确决定、重试未决项，禁止为此重新抓取全部来源。关键教训——恢复 papers.json 前必须检查 lastUpdated：
第一次运行中断后，不要盲目恢复任何备份！必须先确认 papers.json 的状态：
# 检查 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 / filter-decisions.json 续跑 |
| 昨天或更早 | 可以恢复备份：cp data/archive/papers-YYYY-MM-DD.json data/current/papers.json |
推荐检查命令（可选）：
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('fetchedAt', '')[:10] for p in papers if p.get('fetchedAt')]
print('总论文:', len(papers))
print('fetchedAt 批次日期分布:', Counter(dates))
PY
logs/<script>-YYYYMMDD-HHMMSS-<pid>-<seq>.log；backup-data.sh 同样默认生成文件日志并在退出时为每一行补写北京时间戳PD_ENABLE_FILE_LOGS=1 / PAPER_DIGEST_ENABLE_FILE_LOGS=1 继续兼容，但不再是生成日志的必要条件PAPER_DIGEST_DISABLE_FILE_LOGS=1 或 PD_DISABLE_FILE_LOGS=1 可强制禁用文件日志backfill_papers.py 复用统一的每次运行日志，不再额外追加 logs/backfill.log0600 权限；每个非空物理日志行均以毫秒级北京时间戳（[YYYY-MM-DD HH:mm:ss.SSS+08:00]）开头。日志层统一脱敏 Authorization、x-api-key、Cookie、token、secret、password、任意已配置密钥实际值和 URL userinfo，并同步落盘，避免 process.exit() 丢失尾部日志full-fetch.js / deep-analysis-only.js / batch-analyze.js 采用重试、逐阶段锁内 checkpoint、跨进程锁和 generation 校验；损坏的 current JSON 会阻断写入，不会回退 legacy 后覆盖。长时间单篇锁使用 heartbeat 续租，远程主机遗留锁只在租约超龄后回收full-fetch.js 另有覆盖归档、清理、筛选和最终合并的单实例运行锁，内部论文分析仍保持配置的并发度；锁 owner 使用随机 token，旧 owner 不能释放后来者的同路径新锁reanalyze.js 每 5 篇保存一次中间结果（并发模式下自动调整保存间隔）npm run validate:data 只读校验当前 papers.json、raw-candidates.json、filter-decisions.json、filtered-papers.json、deep-analysis-result.json 的结构、候选统计、筛选计数一致性，以及完整筛选决策对候选全集的覆盖；该命令不修复数据，发现问题会非零退出full-fetch.js 自动备份 bak 文件到 data/archive/，保留最近 10 个full-fetch.js 自动备份 papers.json 到 data/archive/papers-<日期>.json，保留最近 7 天git reset --hard、git push -f、批量删除历史文章。full-fetch.js 后，不要擅自追加博客/微信发布，除非用户明确要求。SKILL.md、README.md、AGENTS.md 和相关 docs/ 文档。项目根目录的 .env 文件，由脚本通过项目 env loader 加载。API_KEY 等敏感字符为 ***。修改含有这类字符的脚本时，修改后必须重新读取文件验证关键行未被破坏。同时定期检查 data/、logs/ 目录是否残留含密钥的备份文件或日志快照，发现立即清理。.env 中的 PAPER_ANALYZER_API_KEY、PAPER_ANALYZER_MODEL、PAPER_ANALYZER_ENDPOINT，并复用 Node scripts/env-loader.js 或 Python scripts/project_env.py；禁止引入别名回退链、硬编码、base64 编码变量名 hack，或读取外层 shell/Codex/Trae 继承变量作为项目配置。
8.1 所有脚本必须沙箱外执行：直接运行任意 scripts/*.js、scripts/*.py、run-full-fetch.sh 或 scripts/*.sh 时，必须使用沙箱外权限。Node/Python 公共环境加载器和两个 shell 入口会在检测到 CODEX_SANDBOX 后、任何业务逻辑/日志/网络/写入之前失败退出；不得在沙箱内换命令、手动取消检查或伪造结果。单元测试导入模块不会触发该守卫。data/current/*.json 运行数据文件时，统一放入/复用 scripts/config.js（运行数据路径使用 Config.FILES），参数项按需添加项目 .env 覆写支持；新增 Python 发布/维护脚本涉及共享路径时，复用 scripts/path_config.py，禁止再次手写 data/current/*.json 默认路径。analysis-engine.js 的 analyzeBatch() / analyzePaperWithRetry()，避免重复实现重试、解析、保存逻辑；保存结果后必须通过 scripts/digest-status.js 同步 papers.json.digestStatus。generate-blog.py 只生成并写 generation manifest；review-blog.py 只执行严格 LLM/图片 review 和 Hugo gate，通过后写入逐文件 SHA-256 凭证；push-blog.py 只验证凭证后 commit/push，禁止调用生成或 review。未获用户明确授权时禁止运行 push 阶段。
11.1 博客发布必须沙箱外执行：运行 generate-blog.py、review-blog.py、push-blog.py 或兼容 publish-to-blog.py 时，Agent 必须使用沙箱外权限。脚本检测到 Codex 沙箱标志会失败退出；该失败不是内容问题，不得在沙箱内重复执行或绕过 LLM/图片/Hugo/Git 检查。prompts/deep-analysis.md 中的 ## 机器摘要 键名、章节顺序或标签输出格式，必须同步检查 scripts/utils.js 与 scripts/utils.py 的解析逻辑。data/current/deep-analysis-result.json，确认 analysis 文本的机器摘要包含 document_type、rank_bucket、primary_task_tag、primary_method_tag，且 parsed 缓存包含 documentType、scoringRubricVersion、rankBucket、primaryTaskTag、primaryMethodTag 等字段，再运行博客/社媒脚本验证最终产物。prompts/ 目录下的 markdown 文件后，运行一次快速测试（node scripts/quick-test.js 或单篇分析）确认 loadPrompt() 能正确读取并替换占位符，无 {变量名} 残留。scripts/utils.js、scripts/config.js 或分析引擎核心逻辑后，必须运行 npm test 确保测试通过。test-api-key.js）的 options.agent 必须为 false（不是 undefined）。任何重构或修改 HTTP 请求逻辑时，禁止将 agent: false 改回 agent: proxyAgent 或 agent: undefined，否则 MiMo Token Plan 会在有系统代理的环境中返回 403。scripts/utils.js 中的 detectApiType()、buildApiUrl()、buildHeaders()、buildRequestBody()、parseResponseText()；Python 发布阶段 LLM 调用必须复用 publish_common.py 的 call_publish_llm_api()，禁止硬编码特定协议的 URL/Header/Body。
17.1 视觉资产由 Codex 内置图像工具在发布后生成：绝不在项目脚本中调用图像 API，也不读取或要求 OPENAI_API_KEY。全部博客页通过 review、push 且远端 OID 验证后，发布凭证才写入 remoteVerifiedOid；视觉 CLI 必须校验该凭证。Agent 读取已审计分析和 prompts/visual-summary.md，仅对最终评分 TOP 10 各调用一次内置 image_gen；再按 prompts/digest-cover.md 生成一张标题、热门方向与 TOP 10 排行榜汇总图。登记前必须目视核对英文标题逐字一致、正文为简体中文、论文数字和排行榜没有虚构或错位。两类任务用 token 登记并独立续跑；长图按 manifest 的最终 rank 保存到 data/archive/<date>/visual-summaries/01-<paper>/ 至 10-<paper>/，禁止按生成完成顺序编号；封面保存到 data/archive/<date>/digest-cover/，旧版 current 资产校验后迁移。图片不回写本轮博客，不参与博客 generation/review/push 清单。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），确保全链路行为一致。data/、logs/、*.env、*.backup*、缓存文件、含密钥的日志归档等严禁进入 git；提交前必须确认 .gitignore 已正确配置，且仓库中不存在历史遗留的敏感文件。npm test、npm run validate:data、find scripts tests -name '*.js'、find scripts -name '*.py'、python3 -m unittest discover -s tests/python 和全仓库 .sh 语法检查覆盖新增 JS/Python/shell 文件；新增特殊文件类型时再更新 .github/workflows/ci.yml。timestamp / lastUpdated / fetchedAt 时使用 getBeijingISOString()；Python 发布侧使用北京时间 helper（如 get_today_bj()），避免 UTC 日期造成跨天归档或发布筛选错误。检查步骤：
检查 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 |
tp-，必须配合 Token Plan 端点，两者混用必返回 401.env 中的 key/endpoint/model 三元组来自同一供应商，不依赖 .zshrc 或外层 shell 变量检查是否走对了协议（终端输出或 logs/*.log 中查找 [filter] API 类型: xxx 或 [api] → model | xxx 行）
openai，检查端点是否含 token-plan 或 coding，模型是否含 mimo 或 kimianthropic 但仍失败，检查 URL 是否正确：MiMo 是 /anthropic/v1/messages，Kimi 是 /coding/v1/messages，都不是 /v1/chat/completionsAnthropic 协议专项检查（输出显示 anthropic 时）
x-api-key（非 Authorization: Bearer）anthropic-version: 2023-06-01User-Agent: claude-cli/<version> (external, cli)（日志不会直接显示，可用代理工具验证）OpenAI 协议专项检查（输出显示 openai 时）
Authorization: Bearer {key}/v1/chat/completions检查代理（见 9.2 节）
curl --noproxy "xiaomimimo.com" 绕过代理测试查看输出：优先查看 logs/full-fetch-*.log、logs/deep-analyzer-*.log，同时保留终端完整输出
根因：Node.js https.request 的 agent: undefined 仍会复用全局默认 agent 的连接池。当系统配置了代理（https_proxy 等环境变量）时，全局 agent 的连接可能被代理污染，导致 MiMo Token Plan 服务端拒绝请求。
修复：所有 Node LLM 请求（包括 test-api-key.js）的 options.agent 必须设为 false（不是 undefined），彻底禁用连接复用，强制每个请求建立新连接：
const options = {
hostname: url.hostname,
path: url.pathname + url.search,
method: 'POST',
headers: headers,
agent: false, // ← 必须是 false，undefined 无效
signal: controller.signal
};
验证：直接用 curl --noproxy "xiaomimimo.com" 测试，若绕过代理成功而脚本失败，即为此问题。
logs/deep-analyzer-*.log、logs/full-fetch-*.log，同时保留终端完整输出node scripts/deep-analysis-only.js 安全续跑在博客仓库检查：
cd ~/code/github_repos/audio-paper-digest-blog
git status --short
ls -lt content/posts | head -20
优先使用 data/current/deep-analysis-result.json，仅在兼容场景下读取旧路径。
项目根目录的 .env 文件 中配置 PAPER_ANALYZER_API_KEY、PAPER_ANALYZER_MODEL、PAPER_ANALYZER_ENDPOINT.zshrc / Trae / Codex 外层环境变量补齐项目配置WECHAT_APP_ID / WECHAT_APP_SECRET 是否已写入 项目根目录的 .env 文件APP_SECRET 是否过期curl https://huggingface.co/api/daily_papers?limit=10）fetch-huggingface-papers.js 使用 curl 命令，确保系统 curl 可用当修改 detectApiType() 或 buildApiUrl() 后，必须用以下测试脚本验证两个端点都正常：
# 纯文本测试
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);
}
"
确保输出符合预期：
anthropic → .../anthropic/v1/messagesanthropic → .../coding/v1/messages（无 /anthropic 中间路径）openai → .../v1/chat/completions重要经验：Kimi 和 MiMo 的 Anthropic URL 结构不同，修改 buildApiUrl() 时必须分支处理。
根因：npm 脚本在后台模式下尝试访问 TTY 交互，导致 bash 报错并终止进程。
修复：后台运行时使用直接 Node 命令，绕过 npm：
# ❌ 后台模式避免使用
npm run fetch
# ✅ 后台运行推荐方式
node scripts/full-fetch.js
如果已在筛选阶段中断，需要按第 6 节"重跑/修复当天的正确姿势"处理：
papers.json 的 lastUpdated 是否为今天（见 6 节判断矩阵）status: complete 且筛选模型/hash 匹配的 filtered-papers.json 续跑，只有需要强制重筛时才删除 filtered-papers.json 后重跑papers.json 备份后重跑当前仓库没有独立 references/ 子技能目录，也没有 scripts/fetch_papers.py / main.py 等旧入口。维护和执行时以本文第 3 节列出的 Node/Python 脚本为准；新增会议或专题流程应在对应分支和文档中显式登记。