weflow-cli 1.7.0 → 1.8.0

package/scripts/biz_daily.py

@@ -22,12 +22,18 @@ import re
 import time
 import urllib.request
 import base64
+from concurrent.futures import ThreadPoolExecutor, as_completed
 from datetime import datetime, timezone, timedelta
 from pathlib import Path
 
 # 公共工具
 sys.path.insert(0, os.path.dirname(os.path.abspath(__file__)))
-from _utils import call_deepseek, load_config, decrypt_lock, get_api_key, write_with_frontmatter, format_wikilinks
+from _utils import (call_deepseek, load_config, decrypt_lock, get_api_key,
+                    write_with_frontmatter, format_wikilinks,
+                    TOPICS, TOPIC_CRITERIA, DEFAULT_TOPIC,
+                    RELEVANCE_NAMES, DEFAULT_RELEVANCE,
+                    excluded_topics, record_source_topics, load_source_topics,
+                    source_prior_candidates, source_topics_path)
 
 try:
     from sqlcipher3 import dbapi2 as sqlcipher
@@ -47,16 +53,20 @@ except ImportError:
 # ====== Config ======
 
 SCRIPT_DIR = os.path.dirname(os.path.dirname(os.path.abspath(__file__)))
-CONFIG_PATH = os.path.join(os.path.expanduser('~'), '.weflow-cli', 'config.json')
+# 配置一律走 _utils.load_config()（它自己解析路径）。这里原先还有一份 CONFIG_PATH，
+# 定义了但没人用过。
 DB_PATH = None  # auto-detect from config
 OUTPUT_ROOT = os.path.join(SCRIPT_DIR, 'output', 'biz-daily')
-MAX_ARTICLES = 50  # 最多抓取篇数
+# 这里曾有一个 MAX_ARTICLES = 50，注释写着"最多抓取篇数"——**它从来没有被读过**。
+# 真正生效的是 --limit（默认 0 = 不限），所以一天 150–270 篇是常态。一个写着上限
+# 却不生效的常量，比没有它更误导人。
 FETCH_TIMEOUT = 15
 DEEPSEEK_TIMEOUT = 60
 FETCH_DELAY_MIN = 8   # 最小抓取间隔 (秒)
 FETCH_DELAY_MAX = 12  # 最大抓取间隔 (秒)
 
-TOPICS = ['AI', '学术', '新闻', '文学', '投资', '政治']
+# TOPICS 现在从 _utils 导入（见文件头的 import）——分类法只有一份定义，
+# 因为"散文写的枚举"已经漂过一次：这里曾硬编码五类，而 TOPICS 是六类。
 
 
 def load_source_categories(config: dict) -> dict[str, str]:
@@ -114,18 +124,289 @@ def _guess_topic(article: dict) -> str:
     return '新闻'
 
 
+def _tags_for_write(article, topic):
+    """两个写入者共用的 tags 取值。
+
+    md 与 json 原本各写各的默认：md 是 `a.get('tags', [topic])`，json 是
+    `article.get('tags', [])`。**键不存在时**（`--no-ai`、或没配 API key，
+    Phase 2 整段不跑，就不会有任何分类路径去设 `tags`）同一篇文章于是变成
+    md `tags: [学术]`、json `tags: []`。2026-09-04 的 177 篇就是这个样子。
+
+    回落成 `[主题]` 而不是 `[]`，是沿用本仓库既有的约定：分类路径自己就是
+    `a['tags'] = [a['topic']]`（三处）。这里只是让 json 那个写入者跟上。
+
+    注意用的是 `.get(k, 默认)` 而不是 `... or [topic]`：键**存在但为空表**
+    （模型一个标签都没抽出来）是另一种情况，两条路都保留空表，不要在这里合流。
+    """
+    return article.get('tags', [topic])
+
+
+def _serializable_article(article, date_str):
+    """一篇文章 -> `.articles.json` 里的那条记录。
+
+    **判断的原始概率必须一起写进去。** 报告优先读这个文件，只把概率写进 md 的
+    frontmatter 的话，它们在报告那条主路径上等于不存在——真的发生过：日报末尾的
+    "我拿不准的"永远只输出一句"没有概率字段"，而 frontmatter 里明明有。
+    """
+    entry = {
+        'title': article.get('title', ''),
+        'source': article.get('account_name', ''),
+        'date': date_str,
+        'time': article.get('time', ''),
+        # 默认值与分组/md 那条路**必须是同一个**。这里曾经是 `''`，而分组那边是
+        # `'学术'`，于是同一次运行里 md 写 `topic: 学术`、json 写 `topic: ""`。
+        'topic': article.get('topic') or DEFAULT_TOPIC,
+        'relevance': article.get('relevance', DEFAULT_RELEVANCE),
+        'tags': _tags_for_write(article, article.get('topic') or DEFAULT_TOPIC),
+        'summary': article.get('summary', article.get('digest', '')),
+        'url': article.get('url', ''),
+    }
+    for key in ('relevanceScore', 'topicConfidence', 'includeScore'):
+        if article.get(key) is not None:
+            entry[key] = round(float(article[key]), 3)
+    return entry
+
+
+def _normalize_topics(articles):
+    """把每篇的主题定稿到 `TOPICS` 之内，**就地**改，返回兜底的篇数。
+
+    在写入之前只跑这一次，分组、md frontmatter、json 三条路都读它的结果。
+
+    以前没有这一步，主题在写入路径上有三个来源，而且都不报错：
+
+    * 分组键：`a.get('topic','学术')`，越界再折成 `'学术'` —— md 写的是它
+    * json：`a.get('topic','')` —— 空字符串
+    * 原始字段：可能是空的，也可能不在分类法里
+
+    2026-09-04 的产出就是这么分叉的：178 篇全落在 `学术/`、frontmatter 写
+    `topic: 学术`（其中两篇是「OpenAI 深夜发布 GPT-6」「专为高管准备的 AI 助手」），
+    而同一批的 json 全是 `topic: ""` —— 报告读 json，整批被静默排除。
+
+    返回值不为 0 就是"这一批有文章没拿到主题"的信号，调用方要把它说出来：
+    整批兜底（`--no-ai` 就是）不该看起来像一次正常分类。
+    """
+    fallbacks = 0
+    for a in articles:
+        if a.get('topic') not in TOPICS:
+            a['topic'] = DEFAULT_TOPIC
+            fallbacks += 1
+    return fallbacks
+
+
+def _group_by_topic(articles):
+    """归一化主题并按主题分桶，返回 `(分组, 兜底篇数)`。
+
+    **分组键就是 md 写进 frontmatter 的那个主题**（见 Phase 3 的 `fm['topic']`），
+    所以这张表和 `.articles.json` 里的 `topic` 必须指的是同一个值——md 与 json
+    对同一篇文章给出不同主题，就是从这里分叉出去的。
+
+    归一化放在函数内部而不是让调用方分两步做：两步就能被写颠倒（先分组再归一化，
+    键就落在归一化之前的旧值上），而这类颠倒不会报错。合成一个入口之后，
+    "分组用的主题"和"落盘用的主题"在结构上不可能不是同一个。
+    """
+    fallbacks = _normalize_topics(articles)
+    groups = {t: [] for t in TOPICS}
+    for a in articles:
+        # 直取不兜底：归一化刚保证过成员资格，这里再兜一次就等于又有第二个默认值。
+        groups[a['topic']].append(a)
+    return groups, fallbacks
+
+
+def _classify_with_jev(client, title, body, topics):
+    """让 Jev 判断这一篇；**问不出来就返回 None**，由调用方逐篇退回老路。
+
+    这里刻意吞掉异常（包括 `JevError` 之外的意外），因为"分类这一篇失败"
+    不该让整天的日报挂掉。但异常类型会打出来——一个真的写错了的行号不该
+    在日志里长得跟"网络抖了一下"一样。
+    """
+    if client is None:
+        return None
+    try:
+        return client.decide_article(title, body, topics)
+    except Exception as error:
+        print(f'    [WARN] Jev 分类失败（{type(error).__name__}），本篇退回 LLM 解析：{error}')
+        return None
+
+
+# 分类是纯网络等待（实测 0.97s/篇），而且对摘要没有任何依赖，所以没有理由
+# 把它排在那条串行的 LLM 循环里一篇一篇等。并发数克制一些：服务 2026-09-15 才上线，
+# 打满了会返回 529（已实测遇到过），并发拉高只会换来一堆重试。
+JEV_WORKERS = 6
+# 图片并发。取的是 qpic.cn（微信 CDN），浏览器本来就并发取图；串行只是实现选择。
+# 实测每张 0.37s、135 KB、一篇 14–31 张，串行下来 190 篇约 18 分钟。
+IMAGE_WORKERS = 6
+
+
+def classifier_plan(no_ai, classifier, deepseek_key, engine, needs_llm=True):
+    """这次日报用哪条判断路径。返回 `'skip' | 'jev' | 'llm'`。
+
+    这是 D-031 那句"`--classifier` 是一条命令回滚"的**全部实现**——三条分支此前
+    没有任何测试，而回滚承诺就压在它们上面：
+
+    * `'llm'` 必须**不碰 Jev**（一键回退，也是"同一天两条路各跑一遍"的做法）；
+    * `'jev'` 只是**意图**，不是结果——没有 key、或 key 解不开时，建客户端会失败，
+      由调用方按 `classifier == 'jev'` 决定要不要告警，然后安静退回老路（`auto` 的语义）；
+    * `'skip'` 让**整块 Phase 2 都不执行**：`--no-ai`，或 `dailyAiEnabled=false`
+      （那个配置项在更早处被折进 `no_ai`）。
+
+    `needs_llm=False`（`--no-summary`：只要判断、不要生成）时，**不再要求 LLM key**——
+    那一层的 key 校验是为了调 LLM 生成摘要，而这条路上根本不生成。少了这一句，
+    "没有 DeepSeek key 也能只用 Jev 分类"这个诉求会静默变成"整段不跑"。
+
+    单独成函数是为了能**离线枚举**这几种组合——它们决定"有没有数据出境"，
+    不该只靠读代码确认。
+    """
+    if no_ai:
+        return 'skip'
+    if needs_llm and not (deepseek_key or engine != 'deepseek'):
+        return 'skip'
+    return 'jev' if classifier in ('auto', 'jev') else 'llm'
+
+
+def _classify_articles_parallel(articles, client, topics, workers=JEV_WORKERS):
+    """把能分类的篇目一次性并发问完，返回 {下标: decision}。
+
+    分类对摘要没有任何依赖，两者串在一起只是历史顺序。单独跑这一步之后，
+    串行的摘要循环里就只剩它真正必须串行的那部分。
+
+    eligibility 与主循环保持一致（正文存在且够长）——不一致的话，某些文章会在这
+    一步被跳过、然后在循环里又被问一次，等于白花一次调用。
+    """
+    if client is None:
+        return {}
+    todo = []
+    for index, article in enumerate(articles):
+        content = article.get('fetched_md') or article.get('local_text', '')
+        if content and len(content.strip()) > 50:
+            todo.append((index, article.get('title', ''), content))
+    if not todo:
+        return {}
+
+    started = time.time()
+    decisions = {}
+    with ThreadPoolExecutor(max_workers=max(1, workers)) as pool:
+        futures = {
+            pool.submit(_classify_with_jev, client, title, body, topics): index
+            for index, title, body in todo
+        }
+        for future in as_completed(futures):
+            decisions[futures[future]] = future.result()
+
+    ok = sum(1 for value in decisions.values() if value)
+    # 先报个数：并发之后逐篇日志没有意义了，但这三件事必须看得见。
+    print(f'  分类完成 {ok}/{len(todo)} 篇，耗时 {time.time() - started:.1f}s'
+          f'（{workers} 并发；串行约需 {len(todo) * 0.97:.0f}s）')
+    return decisions
+
+
+def _apply_decision(article, decision, set_topic=True):
+    """把 Jev 的判断写进 article。`set_topic=False` 用于主题已被人工配置钉住的场景。"""
+    if not decision:
+        return False
+    if set_topic:
+        article['topic'] = decision['topic']
+    article['relevance'] = decision['relevance']
+    # 原始分与置信度一起落盘：相关度那三档的切点是暂定的，留着原始值，
+    # 将来校准不用重跑整天的日报。
+    article['relevanceScore'] = decision.get('relevanceScore')
+    if decision.get('topicConfidence') is not None:
+        article['topicConfidence'] = decision['topicConfidence']
+    # 收录判断与 relatedness 不是一回事，单独存一个原始概率给日报那道门用。
+    if decision.get('includeScore') is not None:
+        article['includeScore'] = decision['includeScore']
+    return True
+
+
+SUMMARY_WORKERS = 6
+# 单篇摘要的实测耗时（3 篇串行 2.27/2.92/2.45s，含网络）。只用来报「串行约需多少秒」。
+SUMMARY_SECONDS_PER_ARTICLE = 2.5
+
+
+def summary_prompt_for(article, category_hint, judged=False):
+    """这一篇要发的提示词与 `max_tokens`。
+
+    三条分支：
+    * 配了类别的来源 → 短提示词（只要摘要，`max_tokens=1000`）；
+    * `judged=True`（Jev 已经判过这一篇）→ `SUMMARY_ONLY_PROMPT`，不再要它写主题/相关度；
+    * 其余（`--classifier llm`，或单篇 Jev 失败退回来的）→ 完整的 `TOPIC_PROMPT`，
+      **与旧行为逐字节一致**，回退路径不能换标准。
+
+    抽出来是为了让"取摘要"能并发：搬动的是**调用位置**，不是内容。
+    """
+    content = article.get('fetched_md') or article.get('local_text', '')
+    if category_hint:
+        return (f'''请只为下面这篇公众号文章生成一段 50-300 字的中文摘要。
+来源类别已经确定为「{category_hint}」，不要重新判断或改写文章分类，不要输出主题、标签、相关度或概念字段。
+
+标题：{article["title"]}
+来源：{article["account_name"]}
+
+正文：
+{content[:4000]}''', 1000)
+    base = SUMMARY_ONLY_PROMPT if judged else TOPIC_PROMPT
+    prompt = base + f'\n\n标题：{article["title"]}\n来源：{article["account_name"]}'
+    prompt += f'\n\n内容：\n{content[:4000]}'
+    return prompt, 2000
+
+
+def _summarise_articles_parallel(articles, engine, api_key, workers=SUMMARY_WORKERS,
+                                 decisions=None):
+    """把每篇的 LLM 调用先并发跑完，返回与 `articles` 等长的 `(response, error)`。
+
+    **只有网络等待是并发的**：调用方仍按原顺序串行地解析与落字段，所以每篇的写入
+    顺序、以及失败时走哪条兜底分支，都与串行版本一致。这一层不碰 article dict。
+
+    资格判断必须与调用方**逐字一致**（`content and len(content.strip()) > 50`），
+    否则会出现"并发跑了、主循环却不认为该跑"的错位——那正是 `_classify_articles_parallel`
+    里用下标对齐要防的东西，这里同样按**原下标**回填。
+
+    实测（12 篇）：串行约 12s → 6 路约 3s。串行时每篇后睡 0.3s 的节奏挪到了
+    worker 里（每个请求照样睡一次），所以对上游的请求速率没有变密。
+    """
+    results = [(None, None)] * len(articles)
+    jobs = [i for i, a in enumerate(articles)
+            if (a.get('fetched_md') or a.get('local_text', ''))
+            and len((a.get('fetched_md') or a.get('local_text', '')).strip()) > 50]
+    if not jobs:
+        return results
+
+    from _utils import call_ai
+
+    def one(index):
+        article = articles[index]
+        # 逐篇判断，不是整批一刀切：Jev 判过的那篇用精简提示词，判失败的仍用完整提示词
+        # （它要靠 LLM 的【主题】/【相关度】兜底）。
+        judged = bool((decisions or {}).get(index))
+        prompt, max_tokens = summary_prompt_for(article, article.get('source_category', ''),
+                                               judged=judged)
+        try:
+            return index, call_ai(prompt, engine, api_key, max_tokens=max_tokens), None
+        except Exception as exc:            # 交给调用方那条原有的 except 分支
+            return index, None, exc
+        finally:
+            time.sleep(0.3)
+
+    started = time.time()
+    with ThreadPoolExecutor(max_workers=max(1, workers)) as pool:
+        for index, response, error in pool.map(one, jobs):
+            results[index] = (response, error)
+
+    ok = sum(1 for response, _error in results if response is not None)
+    # 与分类那段同一个形状：并发之后逐篇日志不再说明什么，但三件事必须看得见——
+    # 成了几篇、实际耗时、串行本来要多久。
+    print(f'  摘要完成 {ok}/{len(jobs)} 篇，耗时 {time.time() - started:.1f}s'
+          f'（{workers} 并发；串行约需 {len(jobs) * SUMMARY_SECONDS_PER_ARTICLE:.0f}s）')
+    return results
+
+
 TOPIC_PROMPT = f"""对文章分类、深度摘要、打标签，并评估与读者的相关度。
 
 【读者定位】环境科学研究生，研究方向是计算机与环境的交叉领域（环境模型、大气污染模拟、遥感反演、环境大数据分析、LCA等），关注AI工具如何提升科研效率。
 
 【主题】必须且只能是：{' / '.join(TOPICS)} 中的一个词。
 
-判断规则：
-- AI：AI大模型/Agent/编程/开源/科技产品/工具教程
-- 投资：股票基金/融资/经济分析/商业市场
-- 新闻：时事政策/社会热点/娱乐/招聘促销/会议通知
-- 文学：散文小说/美食旅游/生活随笔/历史文化
-- 学术：科研论文/期刊文章/实验室成果/学术会议/高校研究（环境/气候/地理/海洋/生态/化学/材料/生物医学等）
+判断规则（每一类都必须落到其中一条）：
+{chr(10).join('- %s：%s' % (name, desc) for name, desc in TOPIC_CRITERIA.items())}
 
 【相关度】对上述读者的实用价值：
 - 高：可直接用于科研（新工具/新方法/数据源/代码库）
@@ -133,7 +414,7 @@ TOPIC_PROMPT = f"""对文章分类、深度摘要、打标签，并评估与读
 - 低：信息性阅读（纯新闻/娱乐/文学）
 
 **分类关键**：
-- 【主题】只写一个词（AI/学术/新闻/文学/投资），不要写其他文字
+- 【主题】只写一个词（{'/'.join(TOPICS)}），不要写其他文字
 - 【相关度】只写一个词（高/中/低）
 - 科研论文、期刊文章优先归学术；AI技术/工具/产品归AI
 
@@ -149,6 +430,29 @@ TOPIC_PROMPT = f"""对文章分类、深度摘要、打标签，并评估与读
 【摘要】【核心观点】一句话。【关键细节】1. 要点一；2. 要点二；3. 要点三
 【概念】概念名|一句话说明, 概念名|一句话说明"""
 
+# Jev 已经判过主题与相关度时，给 LLM 的提示词改成这一份：**不再要它输出那两个字段**。
+#
+# 原来无论谁判，提示词都把【主题】【相关度】连"六类判据 + 三档定义"一起塞进去，
+# 而 Jev 那条路上这两个答案是白写的——每篇约 20 个输出 token，加上那几段判据约
+# 300 个输入 token，一天 400 篇就是十来万 token 的纯浪费。
+#
+# **摘要要求那一段与 `TOPIC_PROMPT` 逐字相同**（有测试钉住）——只动分类那几段，
+# 生成的摘要/标签/概念不受影响。`--classifier llm`、以及单篇 Jev 失败退回来的那些，
+# 仍然用完整的 `TOPIC_PROMPT`，回退路径与旧行为逐字节一致（D-031 的约束）。
+SUMMARY_ONLY_PROMPT = f"""为文章写深度摘要、打标签，并抽取概念。
+
+【读者定位】环境科学研究生，研究方向是计算机与环境的交叉领域（环境模型、大气污染模拟、遥感反演、环境大数据分析、LCA等），关注AI工具如何提升科研效率。
+
+**摘要要求**：
+- 【摘要】写一段完整的深度摘要（150-300字），不要只写一两句
+- 格式：【核心观点】一句话概括中心思想。【关键细节】列出3-5个具体要点（工具/方法/数据/结论/人物/事件等），每个要点一句话
+- 摘要不需要包含分类/相关度/标签信息，那些由上面的字段处理
+
+返回格式（严格）：
+【标签】tag1, tag2, tag3
+【摘要】【核心观点】一句话。【关键细节】1. 要点一；2. 要点二；3. 要点三
+【概念】概念名|一句话说明, 概念名|一句话说明"""
+
 # ====== Helpers ======
 
 
@@ -214,6 +518,37 @@ WECHAT_UA = (
     'MicroMessenger/8.0.38(0x18002633) NetType/WIFI Language/zh_CN'
 )
 
+def _decode_body(raw: bytes, content_encoding: str) -> str:
+    """按 `Content-Encoding` 解压响应体。认不出来就原样解码。
+
+    **只认我们主动要求的两种**（`gzip`/`deflate`）——请求里声明的就是这两种，
+    服务器不该回别的；真回了不认识的，退回原样解码而不是抛错：那就会走
+    `fetch_article` 的重试与回退，把一次"少传了字节"的优化变成"抓不到文章"。
+    """
+    enc = (content_encoding or '').strip().lower()
+    if enc == 'gzip':
+        import gzip
+        raw = gzip.decompress(raw)
+    elif enc == 'deflate':
+        import zlib
+        # 裸 deflate（无 zlib 头）是这里的常见形态，先按裸的试，再退回带头的。
+        try:
+            raw = zlib.decompress(raw, -zlib.MAX_WBITS)
+        except zlib.error:
+            raw = zlib.decompress(raw)
+    return raw.decode('utf-8', errors='ignore')
+
+
+def summary_section(summary):
+    """md 正文里的摘要段。**空就不写这一段**（`--no-summary` 就是这种情况）。
+
+    为什么要单独一条规则：没有摘要时，把标题写上去会看起来像"摘要生成失败"，而用
+    本地 digest 顶上又会看起来像 AI 写的摘要——两者都是把不存在的东西说成存在。
+    判据用"去空白后非空"，顺带挡住空串与纯空白。
+    """
+    return f'## AI 摘要\n\n{summary}\n\n' if str(summary or '').strip() else ''
+
+
 def fetch_article(url: str, max_retries: int = 3) -> str | None:
     """Fetch WeChat article with WeChat browser UA to bypass WAF.
     Retries up to max_retries times if content is too short."""
@@ -227,9 +562,16 @@ def fetch_article(url: str, max_retries: int = 3) -> str | None:
                 'Origin': 'https://mp.weixin.qq.com',
                 'Accept': 'text/html,application/xhtml+xml',
                 'Accept-Language': 'zh-CN,zh;q=0.9',
+                # **`urllib` 默认不发这个头**，于是服务器只好把整页未压缩地传过来。
+                # 微信文章页是 3–4 MB（大量内联 JS/CSS），实测同一篇：不发头 33–40s，
+                # 发了 gzip 后 0.7–0.8 MB / 6–10s——正文一模一样（解压后同尺寸，
+                # `js_content` 与 `rich_media_content` 都在）。传的字节更少，
+                # 上游压力是**变小**的，与"按篇节流"同一个方向。
+                'Accept-Encoding': 'gzip, deflate',
             })
             with urllib.request.urlopen(req, timeout=FETCH_TIMEOUT) as resp:
-                html = resp.read().decode('utf-8', errors='ignore')
+                raw = resp.read()
+                html = _decode_body(raw, resp.headers.get('Content-Encoding', ''))
 
             # Validate: article content must include js_content div
             if 'js_content' not in html and 'rich_media_content' not in html:
@@ -297,31 +639,85 @@ def fetch_article(url: str, max_retries: int = 3) -> str | None:
     return None
 
 
-def download_images_to_local(markdown: str, images_dir: Path) -> tuple[str, dict]:
-    """Download mmbiz images to local directory. Returns (markdown, url_mapping)."""
+FETCH_CACHE_DIR = os.path.join(SCRIPT_DIR, 'output', '.cache', 'fetch')
+
+
+def fetch_article_cached(url: str, use_cache: bool = True) -> tuple[str | None, bool]:
+    """抓正文，带本地缓存。返回 `(markdown 或 None, 是否命中缓存)`。
+
+    **为什么需要它**：日报是**全有全无**的——要把当天的文章**全部抓完**才进 Phase 3
+    写盘，抓取结果只存在内存里。一天 400 篇光是抓取（10s/篇 + 8–12s 节流）就一个多
+    小时，任何中断（被收走、网络断、手滑）都会把前面的抓取全部作废。2026-09-22 那天
+    实测停在 105/403，什么都没写出来。
+    按 URL 缓存正文之后：**重跑只抓缺的那些**，也顺带让"改代码 / 换分类器 /
+    `--no-summary` 与正常模式之间切换"重跑同一天几乎免费。
+
+    **只缓存成功**：失败的下次照旧重试（`None` 不落盘）。
+    """
+    path = os.path.join(FETCH_CACHE_DIR, hashlib.md5(url.encode()).hexdigest() + '.md')
+    if use_cache and os.path.isfile(path) and os.path.getsize(path) > 0:
+        try:
+            with open(path, encoding='utf-8') as fh:
+                body = fh.read()
+            if body.strip():
+                return body, True
+        except OSError:
+            pass                      # 读不了就当没缓存，走网络
+    body = fetch_article(url)
+    if body and body.strip():
+        try:
+            os.makedirs(FETCH_CACHE_DIR, exist_ok=True)
+            with open(path, 'w', encoding='utf-8') as fh:
+                fh.write(body)
+        except OSError:
+            pass                      # 缓存写不进去不该让这一天的日报失败
+    return body, False
+
+
+def _download_one_image(url: str, local_path: Path) -> bool:
+    """取一张图。成功返回 True；失败**不抛**——一张图挂了不该影响这一篇的其它图。"""
+    try:
+        req = urllib.request.Request(url, headers={
+            'User-Agent': 'Mozilla/5.0 (Windows NT 10.0; Win64; x64) AppleWebKit/537.36',
+            'Referer': 'https://mp.weixin.qq.com/',
+        })
+        with urllib.request.urlopen(req, timeout=10) as resp:
+            data = resp.read(10 * 1024 * 1024)  # max 10MB
+        if data:
+            local_path.write_bytes(data)
+            return True
+    except Exception:
+        pass
+    return False
+
+
+def download_images_to_local(markdown: str, images_dir: Path,
+                             workers: int = IMAGE_WORKERS) -> tuple[str, dict]:
+    """Download mmbiz images to local directory. Returns (markdown, url_mapping).
+
+    **并发取图**（`IMAGE_WORKERS`）：串行只是实现选择，实测 190 篇约 18 分钟。
+
+    只登记**真的在本地存在**的文件。原先每张图在下载前就写进映射，于是下载失败的
+    也留一条——而映射会被注入阅读器（`window._IMG_MAP`，见 `generate_html.py`），
+    让页面去找一个不存在的文件。保留远程链接才是对的：阅读器按远程取照样能看。
+    """
     url_mapping = {}  # remote_url -> local_rel_path
 
     if not markdown:
         return markdown, url_mapping
 
-    # Create images directory
     images_dir.mkdir(parents=True, exist_ok=True)
 
-    # Find all image URLs in markdown
-    img_pattern = re.compile(r'!\[(.*?)\]\((https?://[^)]+)\)')
-    img_matches = img_pattern.findall(markdown)
-
+    img_matches = re.compile(r'!\[(.*?)\]\((https?://[^)]+)\)').findall(markdown)
     if not img_matches:
         return markdown, url_mapping
 
-    downloaded_count = 0
-    for alt, url in img_matches:
+    targets, seen = [], set()
+    for _alt, url in img_matches:
         # Process any qpic.cn (mmbiz/mmecoa) images
-        if '.qpic.cn' not in url:
+        if '.qpic.cn' not in url or url in seen:
             continue
-
-        # Generate filename from URL hash
-        url_hash = hashlib.md5(url.encode()).hexdigest()[:12]
+        seen.add(url)                     # 同一张图在页面上可能出现多次，只取一次
         ext = '.jpg'  # default
         if '.png' in url or 'wx_fmt=png' in url:
             ext = '.png'
@@ -329,33 +725,28 @@ def download_images_to_local(markdown: str, images_dir: Path) -> tuple[str, dict
             ext = '.gif'
         elif '.webp' in url or 'wx_fmt=webp' in url:
             ext = '.webp'
+        local_filename = f'{hashlib.md5(url.encode()).hexdigest()[:12]}{ext}'
+        targets.append((url, images_dir / local_filename, f'images/{local_filename}'))
 
-        local_filename = f'{url_hash}{ext}'
-        local_path = images_dir / local_filename
-        rel_path = f'images/{local_filename}'
-
-        # Store mapping
-        url_mapping[url] = rel_path
-
-        # Skip if already downloaded
+    downloaded_count = 0
+    todo = []
+    for url, local_path, rel_path in targets:
+        # Skip if already downloaded——重跑同一天时这一步就把它们全跳过了
         if local_path.exists() and local_path.stat().st_size > 0:
+            url_mapping[url] = rel_path
             downloaded_count += 1
-            continue
-
-        # Download image
-        try:
-            req = urllib.request.Request(url, headers={
-                'User-Agent': 'Mozilla/5.0 (Windows NT 10.0; Win64; x64) AppleWebKit/537.36',
-                'Referer': 'https://mp.weixin.qq.com/',
-            })
-            with urllib.request.urlopen(req, timeout=10) as resp:
-                data = resp.read(10 * 1024 * 1024)  # max 10MB
-                if len(data) > 0:
-                    local_path.write_bytes(data)
+        else:
+            todo.append((url, local_path, rel_path))
+
+    if todo:
+        with ThreadPoolExecutor(max_workers=max(1, workers)) as pool:
+            futures = {pool.submit(_download_one_image, url, path): (url, rel_path)
+                       for url, path, rel_path in todo}
+            for future in as_completed(futures):
+                url, rel_path = futures[future]
+                if future.result():
+                    url_mapping[url] = rel_path
                     downloaded_count += 1
-        except Exception as e:
-            # Keep original URL if download fails
-            pass
 
     if downloaded_count > 0:
         print(f'  图片下载: {downloaded_count}张')
@@ -461,6 +852,14 @@ def main():
     parser.add_argument('--api-key', help='AI API key (或设环境变量 DEEPSEEK_API_KEY)')
     parser.add_argument('--engine', default='deepseek', help='AI 引擎: local/deepseek/claude/ollama')
     parser.add_argument('--no-ai', action='store_true', help='关闭摘要、分类和日报简报的 AI 调用')
+    parser.add_argument('--no-fetch-cache', action='store_true',
+                        help='忽略正文抓取缓存，强制重新抓取（默认命中缓存，用于续跑与重跑）')
+    parser.add_argument('--no-summary', action='store_true',
+                        help='只要判断、不要生成：完全跳过 LLM 调用（摘要/标签/概念/简报），'
+                             '主题与相关度仍由 Jev 判断；因此**不需要 DeepSeek key**')
+    parser.add_argument('--classifier', choices=['auto', 'llm', 'jev'], default='auto',
+                        help='主题/相关度由谁判断：auto=配了 TypeSafe key 就用 Jev（默认），'
+                             'llm=沿用 LLM 解析路径，jev=强制 Jev')
     parser.add_argument('--source', action='append', default=[], metavar='NAME',
                         help='仅处理指定公众号，可重复或用逗号分隔；默认读取配置 dailySources')
     args = parser.parse_args()
@@ -486,7 +885,9 @@ def main():
     # API key — only required for cloud engines
     engine = args.engine or 'deepseek'
     api_key = args.api_key or os.environ.get('DEEPSEEK_API_KEY', '') or get_api_key(config)
-    if not args.dry_run and engine in ('deepseek', 'claude') and not api_key:
+    # `--no-summary` 下不生成任何文字，也就不需要 LLM key——这条校验是"要调 LLM"的前提，
+    # 不是"要跑 Phase 2"的前提。不改这一句，"没有 DeepSeek 也能只用 Jev 分类"会被它挡死。
+    if not args.dry_run and not args.no_summary and engine in ('deepseek', 'claude') and not api_key:
         print(f'[ERROR] --engine {engine} 需要 API key。请通过 --api-key、环境变量或配置文件提供')
         sys.exit(1)
     # Auto-detect local engine if no api_key and engine is deepseek
@@ -612,53 +1013,106 @@ def main():
 
     # ====== Phase 1: Fetch all articles ======
     print(f'=== Phase 1: 抓取 {len(articles)} 篇文章 ===\n')
+    cache_hits = 0
     for i, a in enumerate(articles):
         t, n, ti = a['time'], a['account_name'], a['title']
         print(f'[{i+1}/{len(articles)}] [{t}] {n} - {ti[:50]}')
 
         if a['url']:
             delay = FETCH_DELAY_MIN + random.random() * (FETCH_DELAY_MAX - FETCH_DELAY_MIN)
-            md = fetch_article(a['url'])
+            md, cached = fetch_article_cached(a['url'], use_cache=not args.no_fetch_cache)
             if md:
                 a['fetched_md'] = md
-                print(f'  OK ({len(md)}字, {delay:.1f}s)')
+                if cached:
+                    cache_hits += 1
+                    print(f'  OK ({len(md)}字, 缓存)')
+                else:
+                    print(f'  OK ({len(md)}字, {delay:.1f}s)')
             else:
                 print(f'  FAIL, 回退本地缓存')
-            time.sleep(delay)
+            # **命中缓存就不睡**：节流是为了少打扰上游，而缓存命中根本没有请求。
+            # 这也正是"重跑快"的来源——续跑那部分几乎是瞬时的，且与节流同向。
+            if not cached:
+                time.sleep(delay)
         elif a.get('local_text'):
             print(f'  无URL, 使用本地缓存')
 
+    if cache_hits:
+        print(f'  抓取完成：{len(articles) - cache_hits} 篇走网络，'
+              f'{cache_hits} 篇命中本地缓存（少发 {cache_hits} 次请求）')
+
     # ====== Phase 2: AI summary + topic classification ======
-    if not args.no_ai and (api_key or engine != 'deepseek'):
-        print(f'\n=== Phase 2: AI 摘要 + 主题分类 (engine={engine}) ===\n')
+    # **实际服务我们的判断模型**（如 `jev-1.13.0`），不是请求的别名（`jev-latest`）。
+    # 别名会漂：今天跑的和测过的可能不是同一个东西，而结果看起来一切正常。落盘它，
+    # 是为了让这件事**可见**。（没走 Jev 时保持 None，如实表示"没用判断模型"。）
+    decision_model = None
+    plan = classifier_plan(args.no_ai, args.classifier, api_key, engine,
+                           needs_llm=not args.no_summary)
+    if plan != 'skip':
+        stage = '只分类（--no-summary）' if args.no_summary else 'AI 摘要 + 主题分类'
+        print(f'\n=== Phase 2: {stage} (engine={engine}) ===\n')
         from _utils import call_ai
-        for i, a in enumerate(articles):
+        from jev_client import create_client
+        # 判断交给 Jev，生成留给 LLM。没配 key 就整条走老路（auto 的语义）。
+        jev_client = create_client(config=config) if plan == 'jev' else None
+        if jev_client is not None:
+            tail = '本次不生成摘要' if args.no_summary else f'生成摘要仍用 {engine}'
+            print(f'  分类：Jev（model={jev_client.model}，{tail}）')
+        elif args.classifier == 'jev':
+            print('  [WARN] --classifier jev 但没找到 TypeSafe key，本次退回 LLM 解析路径')
+        # 先把分类并发跑完，再进串行的摘要循环。分类对摘要没有任何依赖，
+        # 串行做就是把 N 次网络等待排在 N 次 LLM 调用后面。
+        decisions = _classify_articles_parallel(articles, jev_client, TOPICS)
+        if jev_client is not None:
+            decision_model = jev_client.last_model
+        if args.no_summary:
+            # **只要判断、不要生成**：不调 LLM，也不留摘要。`prefetched = None` 让下面
+            # 那个串行循环整段跳过——它是围绕 LLM 响应写的，没有响应就没有它的事。
+            judged = 0
+            for i, a in enumerate(articles):
+                if _apply_decision(a, decisions.get(i)):
+                    judged += 1
+                # **明确写空**而不是留着不写：md 那条路的缺省是本地 digest、json 那条路
+                # 另有缺省，写空才能让两边都如实表示"没有摘要"，而不是拿平台摘要冒充。
+                a['summary'] = ''
+            print(f'  判出 {judged}/{len(articles)} 篇；未生成：摘要、标签、概念')
+            if jev_client is None:
+                print('  [WARN] 没有 TypeSafe key，本次**没有任何判断**——只抓取与归档，'
+                      '主题与相关度保持默认值')
+            prefetched = None
+        else:
+            # 先把每篇的 LLM 调用并发跑完，再进下面这个串行循环做解析与落字段。
+            # 解析是纯本地操作，并发的价值全在网络等待上；这样循环体本身不用重写，
+            # 每条兜底分支的行为也就与串行版本一致。
+            prefetched = _summarise_articles_parallel(articles, engine, api_key,
+                                                      decisions=decisions)
+        # `--no-summary` 时 prefetched 是 None，这个循环整段不跑（循环体是围绕 LLM
+        # 响应写的）。用变量而不是把循环体缩进进 if，是为了让 diff 只碰这一行。
+        pending = list(enumerate(articles)) if prefetched is not None else []
+        for i, a in pending:
             t, n, ti = a['time'], a['account_name'], a['title']
             content = a.get('fetched_md') or a.get('local_text', '')
             if content and len(content.strip()) > 50:
                 try:
                     category_hint = a.get('source_category', '')
+                    response, call_error = prefetched[i]
+                    if call_error is not None:
+                        # 调用是并发阶段做的，异常在那里被捕获了。这里重新抛出，
+                        # 让下面原有的 `except` 接管——兜底行为与串行版本一致。
+                        raise call_error
                     if category_hint:
-                        summary_prompt = f'''请只为下面这篇公众号文章生成一段 50-300 字的中文摘要。
-来源类别已经确定为「{category_hint}」，不要重新判断或改写文章分类，不要输出主题、标签、相关度或概念字段。
-
-标题：{a["title"]}
-来源：{a["account_name"]}
-
-正文：
-{content[:4000]}'''
-                        response = call_ai(summary_prompt, engine, api_key, max_tokens=1000)
                         a['topic'] = category_hint
                         a['tags'] = [category_hint]
                         a['summary'] = response.strip()[:1000]
-                        a['relevance'] = '中'
+                        # 主题是人工配的强约束，不动；但相关度以前是硬编码的「中」，
+                        # 而那正是"全库 relevance 都是中"的成因之一，交给 Jev。
+                        _apply_decision(a, decisions.get(i), set_topic=False)
                         a['concepts'] = []
                         print(f'[{i+1}/{len(articles)}] [{t}] {n} - [{category_hint}] 固定来源类别，仅生成摘要')
-                        time.sleep(0.3)
                         continue
-                    prompt = TOPIC_PROMPT + f'\n\n标题：{a["title"]}\n来源：{a["account_name"]}'
-                    prompt += f'\n\n内容：\n{content[:4000]}'
-                    response = call_ai(prompt, engine, api_key, max_tokens=2000)
+                    # （提示词与调用已移到 `_summarise_articles_parallel`，响应在上面取。）
+                    # 判断来自开头那轮并发分类；没拿到才回落到下面的解析。
+                    decision = decisions.get(i)
 
                     # Parse response: 【主题】xxx 【相关度】xxx 【标签】xxx 【摘要】xxx 【概念】xxx
                     topic_match = re.search(r'【主题】\s*(.+)', response)
@@ -668,8 +1122,8 @@ def main():
                     summary_match = re.search(r'【摘要】\s*(.+?)(?=\n【(?:主题|相关度|标签|概念)】|$)', response, re.DOTALL)
                     concepts_match = re.search(r'【概念】\s*(.+)', response, re.DOTALL)
 
-                    if category_hint:
-                        a['topic'] = category_hint
+                    if decision:
+                        _apply_decision(a, decision)
                     elif topic_match:
                         raw_topic = topic_match.group(1).strip()
                         if raw_topic in TOPICS:
@@ -688,9 +1142,11 @@ def main():
                         a['topic'] = _guess_topic(a)
 
                     # Parse relevance: 高/中/低
-                    if relevance_match:
+                    if decision:
+                        pass  # 已由 _apply_decision 写入
+                    elif relevance_match:
                         raw_rel = relevance_match.group(1).strip()
-                        if raw_rel in ['高', '中', '低']:
+                        if raw_rel in RELEVANCE_NAMES:
                             a['relevance'] = raw_rel
                         elif '高' in raw_rel:
                             a['relevance'] = '高'
@@ -699,9 +1155,9 @@ def main():
                         elif '低' in raw_rel:
                             a['relevance'] = '低'
                         else:
-                            a['relevance'] = '中'
+                            a['relevance'] = DEFAULT_RELEVANCE
                     else:
-                        a['relevance'] = '中'
+                        a['relevance'] = DEFAULT_RELEVANCE
 
                     # Parse tags: comma-separated, clean up
                     if category_hint:
@@ -731,23 +1187,27 @@ def main():
                         a['summary'] = response[:300]
 
                     print(f'[{i+1}/{len(articles)}] [{t}] {n} - [{a.get("topic","?")}] tags={a.get("tags",[])} ({len(a.get("summary",""))}字)')
-                    time.sleep(0.3)
                 except Exception as e:
                     a['summary'] = a.get('digest', '') or content[:300]
-                    a['topic'] = a.get('source_category') or '学术'
+                    a['topic'] = a.get('source_category') or DEFAULT_TOPIC
                     a['tags'] = [a['topic']]
                     a['concepts'] = []
+                    # 这三条兜底路径以前完全不设 relevance，靠落盘时的默认值兜成「中」。
+                    # 显式写出来，并保留 Jev 已经给出的那一份（setdefault 而不是赋值）。
+                    a.setdefault('relevance', DEFAULT_RELEVANCE)
                     print(f'[{i+1}/{len(articles)}] [{t}] {n} - ERR: {e}')
             elif content:
                 a['summary'] = content[:400]
-                a['topic'] = a.get('source_category') or '学术'
+                a['topic'] = a.get('source_category') or DEFAULT_TOPIC
+                a.setdefault('relevance', DEFAULT_RELEVANCE)
             else:
                 a['summary'] = a.get('digest', '(无内容)')
-                a['topic'] = a.get('source_category') or '学术'
+                a['topic'] = a.get('source_category') or DEFAULT_TOPIC
+                a.setdefault('relevance', DEFAULT_RELEVANCE)
 
         # Print topic distribution
         from collections import Counter
-        topic_counts = Counter(a.get('topic', '学术') for a in articles)
+        topic_counts = Counter(a.get('topic') or DEFAULT_TOPIC for a in articles)
         print(f'\n  主题分布: {dict(topic_counts)}')
 
     # ====== Phase 3: Write files (by topic folders) ======
@@ -757,29 +1217,16 @@ def main():
     for topic in TOPICS:
         (out_dir / topic).mkdir(parents=True, exist_ok=True)
 
-    # Group articles by topic
-    topic_groups = {t: [] for t in TOPICS}
-    for a in articles:
-        t = a.get('topic', '学术')
-        if t not in topic_groups:
-            t = '学术'
-        topic_groups[t].append(a)
+    # --- 主题在这里定稿：**分组、md frontmatter、json 三条路都只读这一次的结果** ---
+    topic_groups, fallback_count = _group_by_topic(articles)
+    if fallback_count:
+        # 说出来，别让它看起来像一次正常分类：`--no-ai`、没配 key、或者来源配置里
+        # 写了个不在分类法里的词，都会整批落到兜底类。
+        print(f'  [WARN] {fallback_count}/{len(articles)} 篇没有可用主题，'
+              f'已归入兜底类「{DEFAULT_TOPIC}」（不是判断结果）')
 
     # --- 写入结构化 JSON：一次提取，多次复用（供 AI 报告等下游使用） ---
-    serializable = []
-    for a in articles:
-        entry = {
-            'title': a.get('title', ''),
-            'source': a.get('account_name', ''),
-            'date': date_str,
-            'time': a.get('time', ''),
-            'topic': a.get('topic', ''),
-            'relevance': a.get('relevance', '中'),
-            'tags': a.get('tags', []),
-            'summary': a.get('summary', a.get('digest', '')),
-            'url': a.get('url', ''),
-        }
-        serializable.append(entry)
+    serializable = [_serializable_article(a, date_str) for a in articles]
 
     json_path = out_dir / '.articles.json'
     try:
@@ -787,6 +1234,8 @@ def main():
             json.dump({
                 'generated_at': datetime.now(timezone(timedelta(hours=8))).strftime('%Y-%m-%d %H:%M:%S'),
                 'date': date_str,
+                # 只增字段：老读者不认识它会忽略；但"这次是谁判的"从此有据可查。
+                'decisionModel': decision_model,
                 'articles': serializable,
             }, f, ensure_ascii=False, indent=2)
         print(f'  ✓ 结构化数据: {json_path} ({len(serializable)} 篇)')
@@ -815,7 +1264,7 @@ def main():
                     print(f'  [SKIP] 内容过短 ({len(body_text)}字): {a["title"]}')
                     continue
             summary = a.get('summary', a.get('digest', ''))
-            tags = a.get('tags', [topic])
+            tags = _tags_for_write(a, topic)
             concepts = a.get('concepts', [])
 
             fm = {
@@ -823,10 +1272,18 @@ def main():
                 'source': f'"{a["account_name"]}"',
                 'date': date_str,
                 'topic': topic,
-                'relevance': a.get('relevance', '中'),
+                'relevance': a.get('relevance', DEFAULT_RELEVANCE),
                 'tags': tags,
                 'created': date_str,
             }
+            # 只增字段：下游只做 fm.get('relevance') 的字面量比较，不认识的键会被忽略。
+            # 不留这两个值，Jev 带来的概率信息就在落盘这一步丢掉了。
+            if a.get('relevanceScore') is not None:
+                fm['relevanceScore'] = round(float(a['relevanceScore']), 3)
+            if a.get('topicConfidence') is not None:
+                fm['topicConfidence'] = round(float(a['topicConfidence']), 3)
+            if a.get('includeScore') is not None:
+                fm['includeScore'] = round(float(a['includeScore']), 3)
             if a['url']:
                 fm['url'] = f'"{a["url"]}"'
 
@@ -836,7 +1293,7 @@ def main():
             if a['url']:
                 body_parts.append(f'> 原文：[阅读原文]({a["url"]})\n')
             body_parts.append('\n---\n\n')
-            body_parts.append(f'## AI 摘要\n\n{summary}\n\n')
+            body_parts.append(summary_section(summary))
 
             if concepts:
                 body_parts.append(format_wikilinks(concepts))
@@ -944,7 +1401,9 @@ def main():
                 break
 
         highlight_text = '\n'.join(highlights[:25])
-        if highlight_text and not args.no_ai:
+        # `--no-summary` 同样跳过简报的 LLM 调用（它是"生成"）：落到下面那条由标题拼的
+        # 确定性兜底上。兜底路径本来就在（AI 失败时走它），所以这里不新增一种产物形状。
+        if highlight_text and not args.no_ai and not args.no_summary:
             try:
                 briefing_prompt = f"""你是公众号日报助手。基于今天 {len(all_articles)} 篇文章（{topic_summary}），生成一段200字以内的今日简报。
 
@@ -1050,6 +1509,32 @@ def main():
     with open(state_file, 'w', encoding='utf-8') as f:
         json.dump(processed, f, ensure_ascii=False, indent=2)
 
+    # === 来源级先验：把今天**真正归档了的**判断累加进本地表 ===
+    #
+    # 记"盘上真有的"（按 written_urls 对回来）而不是"抓过的"：这样这张表和 output/
+    # 里的语料一一对应，哪天想重算也重算得出来。
+    #
+    # 它**只记账，不跳过任何东西**。跳过是不可逆的，而这张表还在长；等某个来源
+    # 攒够了样本（见 _utils.SOURCE_PRIOR_MIN_SAMPLES），再决定要不要拿它做拉取前的筛。
+    pairs = [(a.get('account_name', ''), a.get('topic', '')) for a in articles
+             if a.get('url') and a['url'] in written_urls]
+    if pairs:
+        summary = record_source_topics(pairs)
+        if summary['error']:
+            # 说清楚"没写进去"：静默失败会让人以为表在长，实际一直没动。
+            print(f'  [WARN] 来源先验没写进去（{summary["error"]}）—— 不影响今天的日报')
+        else:
+            print(f'  来源先验: 今天记了 {summary["added"]} 篇，表里共 {summary["sources"]} 个来源'
+                  f'（{source_topics_path()}）')
+        exclude = excluded_topics(config)
+        rows = source_prior_candidates(load_source_topics(), exclude)
+        if rows:
+            print('  来源先验: 这些来源已经稳到能判，且正落在你配的排除主题里'
+                  '（只报数，不跳过）:')
+            for source, topic, ratio, total in rows[:5]:
+                print(f'    {source} → {topic}（{total} 篇里 {round(ratio * total)} 篇'
+                      f' = {ratio:.0%}）')
+
 
 if __name__ == '__main__':
     main()