weflow-cli 1.7.0 → 1.8.0

package/scripts/generate_ai_report.py

@@ -23,7 +23,8 @@ from pathlib import Path
 from collections import Counter
 
 sys.path.insert(0, os.path.dirname(os.path.abspath(__file__)))
-from _utils import create_engine, parse_frontmatter
+from _utils import (create_engine, parse_frontmatter, TOPICS, TOPIC_CRITERIA,
+                    load_config, excluded_topics)
 
 SCRIPTS_DIR = os.path.dirname(os.path.abspath(__file__))
 ROOT_DIR = os.path.dirname(SCRIPTS_DIR)
@@ -31,7 +32,7 @@ SOURCE_ROOT = os.path.join(ROOT_DIR, 'output', 'biz-daily')
 OUTPUT_DIR = os.path.join(ROOT_DIR, 'output', 'ai-reports')
 
 TZ = timezone(timedelta(hours=8))
-TOPICS = ['AI', '学术', '新闻', '文学', '投资', '政治']
+
 FOCUS_TOPIC = 'AI'
 
 
@@ -89,7 +90,168 @@ REPORT_PROMPT = """你是一位为忙碌研究生写作的「深度阅读策展
 # DATA LOADING
 # ======================================================================
 
-def load_articles_from_date(date_str: str) -> list[dict]:
+# 「该不该进今天的日报」的切点。**暂定且未经校准**：Jev 问的是
+# `worth_including`（含可直接用上的具体内容吗），返回 0~1 的概率，
+# 原始值存在 frontmatter 的 `includeScore` 里，改这个数不用重跑日报。
+INCLUDE_THRESHOLD = 0.5
+
+
+# 「拿不太准」的区间。收录分落在中间，意味着这次收还是不收都说得过去——
+# 报告不该把这种条目当成确定的事报出去。
+UNCERTAIN_BAND = (0.35, 0.65)
+TOPIC_CONFIDENT = 0.7
+UNCERTAIN_LIST_LIMIT = 8
+
+
+def _num(value):
+    """把 includeScore 之类的概率读成 float；读不出返回 None。
+
+    要认字符串：`.articles.json` 里是数字，md 兜底路径读出来是 YAML 标量文本。
+    """
+    if value is None:
+        return None
+    try:
+        return float(value)
+    except (TypeError, ValueError):
+        return None
+
+
+def _score(article):
+    """读 includeScore。`.articles.json` 里是数字，md 兜底路径读出来是字符串。"""
+    value = article.get('includeScore')
+    if value is None:
+        return None
+    try:
+        return float(value)
+    except (TypeError, ValueError):
+        return None
+
+
+def build_uncertainty_section(included, everything, include_all=False, exclude=()) -> str:
+    """报告末尾那一段「我拿不准的」。**本地算，不经 LLM** —— 让模型去描述自己的不确定，
+    等于又要它生成一段可能被编圆的散文。
+
+    两种不确定分开说，因为处理方式不同：
+      * 收录卡在阈值上 —— 收与不收都说得过去，你看到的是这次掷硬币的结果；
+      * 主题置信度低 —— 它可能被分到了错误的那一栏，位置都可能是错的。
+
+    **没有概率字段时不能沉默。** 早期生成的文章没有 includeScore，那一段的缺席会被
+    读成"这份报告哪里都很确定"，而事实是"它没告诉你"。所以那种情况要明说。
+    """
+    scored = [a for a in everything if _score(a) is not None]
+    if not scored:
+        return (chr(10) + '---' + chr(10) + chr(10) + '## 我拿不准的' + chr(10) + chr(10)
+                + '本期文章没有概率字段（生成早于该字段引入），所以**这份报告无法告诉你'
+                  '它哪里不确定**——不能把上面的结论读成"都已经过确认"。' + chr(10))
+
+    low, high = UNCERTAIN_BAND
+    in_ids = {id(a) for a in included}
+
+    def band(article):
+        value = _score(article)
+        return value is not None and low <= value <= high
+
+    # 这一段三份清单都不提被排除的主题：否则"不想看新闻"的同一份报告，
+    # 会在这一栏把新闻的标题和分数原样列出来。
+    borderline_in = [a for a in included
+                     if band(a) and not is_excluded_topic(a, exclude)]
+    # 注意：这一栏装的是**没收**的文章，被排除的天然满足"没收"——
+    # 把 exclude 交给 admits 反而会让它们更容易被列进来（我第一版就是这么错的）。
+    # 这里要的是"因为分数而没收"，所以按排除集滤掉。
+    borderline_out = [] if include_all else [a for a in everything
+                                            if not admits(a, include_all) and band(a)
+                                            and not is_excluded_topic(a, exclude)]
+    low_confidence = [a for a in included
+                      if isinstance(a.get('topicConfidence'), (int, float))
+                      and a['topicConfidence'] < TOPIC_CONFIDENT
+                      and not is_excluded_topic(a, exclude)]
+
+    lines = [chr(10) + '---' + chr(10), '## 我拿不准的' + chr(10),
+             '这两处不是漏掉，是**判断本身不确定**。列出来，免得被当成定论。' + chr(10)]
+
+    total_borderline = len(borderline_in) + len(borderline_out)
+    if total_borderline:
+        if include_all:
+            # 收录判据没启用，"收与不收"这个区分根本不存在——照抄阈值两侧的措辞
+            # 会让人以为这里做过一次筛选。
+            lines.append('**收录分落在边界上的 %d 篇**（本次未启用收录判据，全部收录）'
+                         '——这些分数本来就说不准：%s' % (total_borderline, chr(10)))
+        else:
+            lines.append('**收录卡在阈值上的 %d 篇**（收了 %d 篇、没收 %d 篇）——'
+                         '收与不收都说得过去：%s'
+                         % (total_borderline, len(borderline_in),
+                            len(borderline_out), chr(10)))
+        listed = borderline_in + borderline_out
+        for article in listed[:UNCERTAIN_LIST_LIMIT]:
+            kept = '' if include_all else (' · 收' if id(article) in in_ids else ' · 没收')
+            lines.append('- %s（收录分 %.2f%s · 主题 %s）'
+                         % (article.get('title', '(无标题)'), _score(article), kept,
+                            article.get('topic', '?')))
+        if total_borderline > UNCERTAIN_LIST_LIMIT:
+            lines.append('- 另有 %d 篇同样卡在边界，未列。' % (total_borderline - UNCERTAIN_LIST_LIMIT))
+        lines.append('')
+
+    if low_confidence:
+        lines.append('**主题可能归错的 %d 篇**（主题置信度低于 %.1f，分栏位置可能不对）：%s'
+                     % (len(low_confidence), TOPIC_CONFIDENT, chr(10)))
+        for article in low_confidence[:UNCERTAIN_LIST_LIMIT]:
+            lines.append('- %s（标为 %s · 置信 %.2f）'
+                         % (article.get('title', '(无标题)'), article.get('topic', '?'),
+                            article['topicConfidence']))
+        if len(low_confidence) > UNCERTAIN_LIST_LIMIT:
+            lines.append('- 另有 %d 篇同样置信偏低，未列。' % (len(low_confidence) - UNCERTAIN_LIST_LIMIT))
+        lines.append('')
+
+    if not total_borderline and not low_confidence:
+        lines.append('本期没有落在边界上的条目——收录分与主题置信度都不在含糊区间。' + chr(10))
+
+    lines.append('> 这些数字来自决策模型，**没有金标准校准过**；概率在阈值附近还会抖'
+                 '（同一批数据两次跑会有出入），别细究 0.48 与 0.52 的区别。')
+    lines.append('')
+    return chr(10).join(lines)
+
+
+def is_excluded_topic(article: dict, exclude=()) -> bool:
+    """用户是不是明说了不要这个主题。
+
+    单独抽出来是因为它有**两个方向相反**的用处：
+    `admits` 靠它判"不要"，而「我拿不准的」那一栏靠它判"别列出来"——
+    那一栏装的恰好是**没收**的文章，被排除的天然满足"没收"。
+    两处各写一遍早晚会写反，事实上第一版就写反了。
+    """
+    return (article.get('topic') or '') in (exclude or ())
+
+
+def admits(article: dict, include_all: bool = False, exclude=()) -> bool:
+    """这篇文章该不该收录。
+
+    焦点主题永远收。其余看 `includeScore`——那是**专门为这个问题**问出来的概率，
+    比拿 `relevance != '高'` 顶替准：相关度量的是"对读者的实用价值"，回答不了
+    "今天该不该收它"，阈值怎么调都是在调一个问错了的题。
+
+    没有 `includeScore` 的是这个字段出现之前的产物，退回旧规则，行为不变。
+
+    这里要认字符串：`.articles.json` 里的值是数字，但 md 兜底路径读出来的是
+    YAML 标量文本（`'0.8'`）。只认 `int/float` 的话，那条路径上这个新字段
+    就会被静默忽略——测出来正是如此。
+    """
+    # 排除是**正交**的一维，所以放在 include_all 前面：用户明说不要的主题，
+    # 连 --include-all 都不该让它冒出来。
+    if is_excluded_topic(article, exclude):
+        return False
+    if include_all or article.get('topic') == FOCUS_TOPIC:
+        return True
+    score = article.get('includeScore')
+    if score is not None:
+        try:
+            return float(score) >= INCLUDE_THRESHOLD
+        except (TypeError, ValueError):
+            # 值不是数字（乱改过的产物）。退回旧规则，别让报告生成在这里炸掉。
+            pass
+    return article.get('relevance') == '高'
+
+def load_articles_from_date(date_str: str, include_all: bool = False,
+                            exclude=()) -> list[dict]:
     json_path = Path(SOURCE_ROOT) / date_str / '.articles.json'
     if json_path.exists():
         try:
@@ -98,7 +260,26 @@ def load_articles_from_date(date_str: str) -> list[dict]:
             arts = data.get('articles', data) if isinstance(data, dict) else data
             for a in arts:
                 a.setdefault('date', date_str)
-            return arts
+            # 这里原先直接 return，不筛。于是「非焦点主题只收相关度高的文章」
+            # 这条规则**只在下面的 MD 兜底路径里存在**，而 .articles.json 才是
+            # 正常走的那条路 —— 规则因此从未真正生效过。
+            kept = [a for a in arts if admits(a, include_all, exclude)]
+            if len(kept) != len(arts):
+                # 说清**实际**用的是哪条规则：有收录分的按概率筛，早于该字段的产物
+                # 退回旧规则。无脑写"阈值 includeScore >= x"，在后一种情况下是撒谎。
+                parsed = [_num(a.get('includeScore')) for a in arts]
+                scored = sum(1 for v in parsed if v is not None)
+                if scored == 0:
+                    print(f'  收录筛选: {len(arts)} 篇 -> {len(kept)} 篇'
+                          f'（这些产物没有收录分，退回旧的 relevance == 高 规则）')
+                elif scored < len(arts):
+                    print(f'  收录筛选: {len(arts)} 篇 -> {len(kept)} 篇'
+                          f'（{scored} 篇按 includeScore >= {INCLUDE_THRESHOLD}，'
+                          f'其余 {len(arts) - scored} 篇按旧规则）')
+                else:
+                    print(f'  收录筛选: {len(arts)} 篇 -> {len(kept)} 篇'
+                          f'（阈值 includeScore >= {INCLUDE_THRESHOLD}）')
+            return kept
         except Exception:
             pass
     # 回退：扫描 MD 文件
@@ -119,8 +300,7 @@ def load_articles_from_date(date_str: str) -> list[dict]:
             if not fm:
                 continue
             relevance = fm.get('relevance', '中')
-            # 非 AI 主题只收录相关度"高"的文章
-            if topic != FOCUS_TOPIC and relevance != '高':
+            if not admits({**fm, 'topic': topic}, include_all, exclude):
                 continue
             # AI 主题读取完整正文（最多 5000 字），其他主题读取摘要
             if topic == FOCUS_TOPIC:
@@ -148,11 +328,13 @@ def load_articles_from_date(date_str: str) -> list[dict]:
     return articles
 
 
-def load_articles_range(from_date: date, to_date: date) -> list[dict]:
+def load_articles_range(from_date: date, to_date: date, include_all: bool = False,
+                        exclude=()) -> list[dict]:
     all_articles = []
     cur = from_date
     while cur <= to_date:
-        all_articles.extend(load_articles_from_date(cur.strftime('%Y-%m-%d')))
+        all_articles.extend(load_articles_from_date(cur.strftime('%Y-%m-%d'), include_all,
+                                                   exclude))
         cur += timedelta(days=1)
     return all_articles
 
@@ -290,6 +472,11 @@ def main():
     parser.add_argument('--to', dest='to_date', help='结束日期 YYYY-MM-DD，默认今天')
     parser.add_argument('--output', help='输出文件路径（默认 output/ai-reports/）')
     parser.add_argument('--dry-run', action='store_true', help='不调用 AI，仅输出统计骨架')
+    parser.add_argument('--exclude-topics', default='',
+                        help='不在报告里出现的主题，逗号分隔（如 新闻,投资）；'
+                             '展示层开关：不重抓、不改产物，只影响这份报告收谁')
+    parser.add_argument('--include-all', action='store_true',
+                        help='不筛选，收录当天全部文章（回退到引入收录判据之前的行为）')
     args = parser.parse_args()
 
     # 日期解析
@@ -314,7 +501,11 @@ def main():
     print(f'🔧 引擎: {args.engine}' + (' (dry-run)' if args.dry_run else ''))
 
     # 加载文章
-    articles = load_articles_range(from_date, to_date)
+    exclude = excluded_topics(load_config(), args.exclude_topics,
+                                  protected=(FOCUS_TOPIC,))
+    if exclude:
+        print('🚫 已排除主题: ' + '/'.join(t for t in TOPICS if t in exclude))
+    articles = load_articles_range(from_date, to_date, args.include_all, exclude)
     if not articles:
         print(f'\n❌ 未找到 {date_label} 的文章。请先运行：')
         print(f'   python scripts/biz_daily.py')
@@ -353,6 +544,20 @@ def main():
     # 生成报告
     t0 = time.time()
     report = generate_report(articles, engine, date_label, dry_run=args.dry_run)
+    # 不确定那一段在本地算：它必须与"模型有没有写、写得漂不漂亮"无关。
+    # 另外单独加载一次全集——被收录判据筛掉的边界条目也要能看见，
+    # 否则"我拿不准"只报告了收进来的那一半。
+    try:
+        everything = load_articles_range(from_date, to_date, include_all=True,
+                                         exclude=exclude)
+    except Exception:
+        everything = articles
+    section = build_uncertainty_section(articles, everything, include_all=args.include_all,
+                                        exclude=exclude)
+    report += section
+    uncertain_count = section.count(chr(10) + '- ')
+    if uncertain_count:
+        print(f'   不确定条目: {uncertain_count} 条已列入报告末尾')
     elapsed = time.time() - t0
 
     with open(out_path, 'w', encoding='utf-8') as f:

package/scripts/generate_html.py

@@ -14,6 +14,9 @@ SCRIPTS_DIR = os.path.dirname(os.path.abspath(__file__))
 PROJECT_ROOT = os.path.dirname(SCRIPTS_DIR)
 SOURCE_ROOT = os.path.join(PROJECT_ROOT, 'output', 'biz-daily')
 
+sys.path.insert(0, SCRIPTS_DIR)
+from _utils import load_config, excluded_topics  # noqa: E402
+
 
 def _inline_marked_js(html_path: str):
     """Replace CDN marked.js with local inline copy to eliminate network dependency."""
@@ -84,10 +87,16 @@ def get_body_preview(text: str, max_chars=200) -> str:
     return preview
 
 
-def collect_articles(date_dir: str) -> dict:
-    """收集所有文章，按主题分组。"""
+def collect_articles(date_dir: str, exclude=()) -> dict:
+    """收集所有文章，按主题分组。
+
+    `exclude` 里的主题**整个目录都不扫**（不是扫完再滤）：读者页和 AI 报告共用同一份
+    排除集，两边才不会一个说排掉了、另一个还在列。展示层开关，md 产物不动。
+    """
     topics = {}
     for topic in TOPIC_ORDER:
+        if topic in exclude:
+            continue
         topic_dir = Path(date_dir) / topic
         if not topic_dir.is_dir():
             continue
@@ -1597,6 +1606,8 @@ def main():
     parser = argparse.ArgumentParser(description='生成公众号日报 HTML 页面')
     parser.add_argument('--date', help='日期 YYYY-MM-DD, 默认今天')
     parser.add_argument('--output', help='输出路径（默认在日报目录下的 index.html）')
+    parser.add_argument('--exclude-topics', default='',
+                        help='不展示的主题，逗号分隔（如 新闻,投资）；只影响这一页，不改产物')
     args = parser.parse_args()
 
     if args.date:
@@ -1612,7 +1623,11 @@ def main():
         print(f'[ERROR] 目录不存在: {date_dir}')
         sys.exit(1)
 
-    topics = collect_articles(date_dir)
+    exclude = excluded_topics(load_config(), args.exclude_topics,
+                              protected=(TOPIC_ORDER[0],))  # 第一项=这份日报的主体
+    if exclude:
+        print('🚫 已排除主题: ' + '/'.join(t for t in TOPIC_ORDER if t in exclude))
+    topics = collect_articles(date_dir, exclude)
     if not topics:
         print(f'[ERROR] 未找到任何文章')
         sys.exit(1)

package/scripts/generate_review.py

@@ -9,7 +9,7 @@ import sys, os, json, re, time, subprocess
 from pathlib import Path
 
 sys.path.insert(0, os.path.dirname(os.path.abspath(__file__)))
-from _utils import create_engine, parse_frontmatter
+from _utils import create_engine, parse_frontmatter, DEFAULT_TOPIC
 
 DAILY_PROMPT = """你是知识管理助手，基于今日文章内容生成学习日报。
 
@@ -67,7 +67,7 @@ def scan_today_articles(target_date: str, source='output/biz-daily') -> list[dic
         articles.append({
             'title': fm.get('title', md_file.stem),
             'source': fm.get('source', ''),
-            'topic': fm.get('topic', '学术'),
+            'topic': fm.get('topic') or DEFAULT_TOPIC,
             'tags': fm.get('tags', []),
             'summary': summary,
         })

package/scripts/jev_client.py

@@ -0,0 +1,294 @@
+#!/usr/bin/env python3
+"""Jev（TypeSafe System One）决策客户端 —— **只做判断，不生成文本**。
+
+日报现在把"主题 + 相关度"塞在同一个散文 prompt 里让 LLM 顺手答，再用两条正则抠回来。
+实测（60 篇真实中文文章）结果是：`relevance` 全库 2199/2201 都是默认值「中」，
+`tags` 全库都是 `[主题名]`，`topic` 靠关键词兜底猜。这个模块把**判断**换成类型化的
+决策调用：输入 state，返回带概率的 choice/score/noul，没有自由文本需要解析。
+
+契约不是转述的，来自服务自己的 OpenAPI（`GET https://api.typesafe.ai/openapi.json`）
+加上实测：
+
+    POST https://api.typesafe.ai/v1/systemone      Authorization: Bearer <key>
+    request  {model, state, questions}
+    response {model, answers, usage}
+
+    choice: criteria 是**对象** {选项名: 何时选它}，答案 {type, choice, confidence, probabilities}
+    score : criteria 是**有序数组**，位置即分值（零索引），答案多一个 score + legend
+    noul  : 不需要 criteria，答案 {type, noul} —— **没有 confidence**
+
+失败取向：**本模块一律抛 `JevError`**（fail-loud），由调用方决定退到哪条老路
+（fail-soft）。分类被问不出来，不该让整天的日报崩掉；但客户端自己不许把失败
+伪装成一个看起来正常的答案。
+"""
+import json
+import os
+import time
+import urllib.error
+import urllib.request
+
+ENDPOINT = 'https://api.typesafe.ai/v1/systemone'
+MODELS_ENDPOINT = 'https://api.typesafe.ai/v1/models'
+DEFAULT_MODEL = 'jev-latest'
+# 瞬时故障：官方参考实现（AI SDK 的 evaluate）默认对它们重试 2 次，这里同样。
+# 实测遇到过 529 `system_overloaded`——服务 2026-09-15 才发布，被打满是常态。
+RETRY_STATUS = frozenset({429, 500, 502, 503, 504, 529})
+INPUT_USD_PER_TOKEN = 0.042 / 1_000_000  # 输出 token 目前不计费
+
+# 分类法（列表 + 每类的判据）只有一份，在 `_utils` 里。这里直接引用它，
+# 所以提示词那条路和决策模型这条路**判的是同一套定义**——回退时不会换标准。
+from _utils import TOPIC_CRITERIA, RELEVANCE_NAMES  # noqa: E402  (scripts/ 在 sys.path 上)
+
+# **顺序即语义**：score.criteria 零索引，第一个元素是 0 分。
+# 两件事必须分开：判据文本是**给模型看**的（照抄 TOPIC_PROMPT 里对高/中/低的定义，
+# 少了这段说明模型就没有判档依据），而落盘的值必须是**裸的三个字**——下游
+# generate_ai_report.py:123、enrich_backlinks.py:75,87、generate_html.py:817-820
+# 都在做字面量比较。名字表在 `_utils`（词表与 TOPICS 同处），下面这份判据文本
+# 按下标与它一一对应（有测试钉住），所以两者都不能重排。
+RELEVANCE_LEVELS = [
+    '低：信息性阅读（纯新闻/娱乐/文学）',
+    '中：有启发性（思路/趋势/跨领域技术）',
+    '高：可直接用于科研（新工具/新方法/数据源/代码库）',
+]
+
+
+class JevError(RuntimeError):
+    """调用或契约出问题。消息面向人，**不含 API key**。"""
+
+
+def _check_choice(key, question, answer):
+    """对 `choice` 答案做硬校验：不合法就抛 `JevError`，**不放行**。
+
+    四条断言（概率的键集 == criteria 的键集、取值都在 [0,1]、和 ≈ 1、`choice`
+    就是 argmax）来自 browser-use × TypeSafe 官方示范仓库的 `validate_choice`；
+    我按它挑的这四条原样实现，并把**实测**过的真实响应作为基准（`jev-1.13.0`：
+    `{"看电影":0.0,"散步":1.0,"睡觉":0.0}` + `choice="散步"`，四条全过）。
+
+    为什么值得在客户端做：契约漂移的失效方式不是报错，而是**选错了但看起来正常**。
+    `argmax` 那条尤其关键——我们此前踩过一个同型的坑：把 `noul`（概率浮点）当布尔
+    读，每个问题都读成"否"，而输出还把责任推给了模型。
+    """
+    if question.get('type') != 'choice':
+        # noul / score 没有"criteria ↔ probabilities"这层对应关系，不该被这套检查误伤。
+        # `decide` 已经按类型过滤，这里再挡一次是为了让这个函数单独调用也安全。
+        return
+    criteria = question.get('criteria') or {}
+    probs = answer.get('probabilities')
+    if not isinstance(probs, dict):
+        raise JevError('%s：choice 答案里没有 probabilities：%s'
+                       % (key, json.dumps(answer, ensure_ascii=False)[:200]))
+    if criteria:
+        missing = sorted(set(criteria) - set(probs))
+        extra = sorted(set(probs) - set(criteria))
+        if missing or extra:
+            raise JevError('%s：probabilities 的键与 criteria 不一致（缺 %s，多 %s）'
+                           % (key, missing, extra))
+    out_of_range = {k: v for k, v in probs.items()
+                    if not isinstance(v, (int, float)) or isinstance(v, bool)
+                    or not 0.0 <= float(v) <= 1.0}
+    if out_of_range:
+        raise JevError('%s：概率不在 [0,1]：%s' % (key, out_of_range))
+    total = sum(float(v) for v in probs.values())
+    if probs and abs(total - 1.0) > 0.02:
+        raise JevError('%s：概率和是 %.3f，不是 1（差得太多说明契约变了）' % (key, total))
+    picked = answer.get('choice')
+    if criteria and picked not in criteria:
+        raise JevError('%s：choice=%r 不在 criteria 里' % (key, picked))
+    if probs:
+        top = max(probs, key=lambda k: probs[k])
+        if picked != top:
+            raise JevError('%s：choice=%r 不是概率的 argmax（%r 才是）——'
+                           '这种情况最危险，它看起来是个正常答案'
+                           % (key, picked, top))
+
+
+def resolve_key(explicit='', config=None):
+    """key 的取值顺序：显式传入 → `TYPESAFE_API_KEY` → 配置里（自动解密）。
+
+    不落盘、不打印。配置那条走 `_utils.decrypt_lock`，所以 `config set` 写的
+    机器绑定密文能直接用。
+    """
+    key = (explicit or os.environ.get('TYPESAFE_API_KEY') or '').strip()
+    if key:
+        return key
+    try:
+        import _utils
+        return (getattr(_utils, 'get_typesafe_key')(config) or '').strip()
+    except Exception:
+        # 配置读不到、密文解不开（比如 config.json 是从别的机器拷来的）——
+        # 回空串让调用方走老路，而不是把日报打挂。
+        return ''
+
+
+def score_to_relevance(score):
+    """把 `score` 期望值映射回「低/中/高」。
+
+    criteria 是零索引的有序量表，所以 `score` 落在 [0, len-1] 区间里。
+    用 `int(score + 0.5)` 取最近档而不是 `round()`：Python 的 round 是银行家舍入，
+    `round(0.5)` 得 0、`round(1.5)` 得 2，边界会跳档。
+
+    阈值是**暂定**的（没有金标准可校准），所以原始分要一起落盘（`relevanceScore`），
+    将来重新校准不用重跑整天的日报。
+    """
+    if score is None:
+        raise JevError('score 答案缺少 score 字段')
+    index = int(float(score) + 0.5)
+    index = max(0, min(len(RELEVANCE_NAMES) - 1, index))
+    return RELEVANCE_NAMES[index]
+
+
+def build_questions(topics, criteria=None):
+    """与 `TOPIC_PROMPT` 等价的类型化版本：一个 choice + 一个 score + 一个 noul。
+
+    `worth_including` 是**回答一个以前没人问过的问题**。日报原来拿 `relevance != '高'`
+    当收录门，而那是在用"对读者的实用价值"回答"该不该进今天的日报"——两件事不一样，
+    阈值怎么调都调不准，因为问题本身错了。多问一个问题的边际成本近零（实测 2 个问题
+    0.84s，12 个问题 0.91s，`state` 才是开销大头），所以这个判断基本是白送的。
+
+    这里刻意不放"探测型"问题（比如"是不是科研论文"）：问完没人读，就是
+    `COVER_STATE` 那种"算了就扔"，不如不加。
+    """
+    table = criteria or TOPIC_CRITERIA
+    # 判据必须覆盖传入的每个主题：choice 的 criteria 就是选项集合本身，
+    # 少一个选项，模型就永远选不到它。
+    choice_criteria = {topic: table.get(topic, topic) for topic in topics}
+    return {
+        'topic': {'type': 'choice',
+                  'instructions': '这篇文章属于哪个主题？',
+                  'criteria': choice_criteria},
+        'relevance': {'type': 'score',
+                      'instructions': '对「环境科学研究生，做计算机与环境交叉」的实用价值有多高？',
+                      'criteria': list(RELEVANCE_LEVELS)},
+        'worth_including': {
+            'type': 'noul',
+            'instructions': '这篇文章含有读者今天就能用上的具体内容'
+                            '（新工具/新方法/数据源/代码库/可复现的结论），'
+                            '而不是仅有信息性的新闻、观点或生活随笔？'},
+    }
+
+
+class JevClient:
+    """一次请求问多个问题，共享同一份 state。"""
+
+    def __init__(self, api_key, model=DEFAULT_MODEL, timeout=120):
+        if not api_key:
+            raise JevError('缺少 TypeSafe API key')
+        self.api_key = api_key
+        self.model = model
+        self.timeout = timeout
+        # 最近一次响应里**实际服务的模型**（如 `jev-1.13.0`），不是请求的别名。
+        self.last_model = None
+
+    def _post(self, url, payload=None, attempts=3, backoff=0.8):
+        """带重试的请求。
+
+        退避故意很短（最坏约 2.4s）：调用方是**逐篇**分类日报的，服务整体过载时
+        长退避只会把一整天的日报拖成几十分钟，而那时调用方本来就该退回老路。
+        """
+        last_error = None
+        for attempt in range(attempts):
+            try:
+                return self._post_once(url, payload)
+            except JevError as error:
+                if attempt == attempts - 1 or not getattr(error, 'retryable', False):
+                    raise
+                last_error = error
+                time.sleep(backoff * (2 ** attempt))
+        raise last_error  # pragma: no cover - 循环内已覆盖所有出口
+
+    def _post_once(self, url, payload=None):
+        data = None if payload is None else json.dumps(payload, ensure_ascii=False).encode('utf-8')
+        request = urllib.request.Request(
+            url, data=data, method='POST' if data else 'GET',
+            headers={'Content-Type': 'application/json',
+                     'Authorization': f'Bearer {self.api_key}'})
+        try:
+            with urllib.request.urlopen(request, timeout=self.timeout) as response:
+                return json.loads(response.read())
+        except urllib.error.HTTPError as error:
+            detail = ''
+            try:
+                # 截断：别把整个响应体（可能很长）带进日志。
+                detail = error.read().decode('utf-8', 'replace')[:400]
+            except Exception:
+                pass
+            if error.code in (401, 403):
+                raise JevError(f'鉴权被拒（HTTP {error.code}）。key 可能不对或已过期：{detail}')
+            if error.code == 422:
+                # 422 说明我理解的契约和服务端不一致，是最值得看的一种失败。
+                raise JevError(f'请求被拒（HTTP 422），契约与预期不符：{detail}')
+            failure = JevError(f'HTTP {error.code}: {detail}')
+            failure.retryable = error.code in RETRY_STATUS
+            raise failure
+        except urllib.error.URLError as error:
+            failure = JevError(f'连不上 {url}: {error.reason}')
+            failure.retryable = True   # 连接层失败通常是瞬时的
+            raise failure
+
+    def models(self):
+        """可用别名。用它可以确认 `--model` 没写错。"""
+        return self._post(MODELS_ENDPOINT).get('models', [])
+
+    def decide(self, state, questions):
+        """返回 (answers, usage)。state 可以是字符串、JSON 对象或数组。
+
+        `usage` 里除了 token 数还带 `model`——那是**实际服务的模型**（实测
+        `jev-1.13.0`），不是你请求的别名（`jev-latest`）。落盘它，是为了让
+        "线上跑的和我测过的不是同一个东西"这件事**可见**，而不是等到结果不对
+        才去猜。
+
+        **每个 choice 答案都过一遍 `_check_choice`**：键集、取值域、概率和、
+        argmax 全对不上就抛 `JevError`。契约漂移应当当场炸——漂移的失效方式是
+        "看起来正常但选错了"，那正是最难发现的。
+        """
+        body = self._post(ENDPOINT, {'model': self.model,
+                                     'state': state, 'questions': questions})
+        answers = body.get('answers')
+        if not isinstance(answers, dict):
+            raise JevError(f'响应里没有 answers：{json.dumps(body, ensure_ascii=False)[:300]}')
+        for key, question in (questions or {}).items():
+            if isinstance(question, dict) and question.get('type') == 'choice':
+                _check_choice(key, question, answers.get(key) or {})
+        usage = dict(body.get('usage') or {})
+        if body.get('model'):
+            usage['model'] = body['model']
+            self.last_model = body['model']
+        return answers, usage
+
+    def decide_article(self, title, body, topics, criteria=None, max_chars=4000):
+        """给一篇文章定主题与相关度。**问不出来就抛 `JevError`。**
+
+        state 只放生产环境真会给模型的东西（标题 + 正文），不放日期、来源、
+        也不放 frontmatter 里的 topic/relevance —— 那些是答案的味道。
+        """
+        state = f'标题：{title}\n\n正文：\n{(body or "")[:max_chars]}'
+        answers, usage = self.decide(state, build_questions(topics, criteria))
+
+        topic_answer = answers.get('topic') or {}
+        relevance_answer = answers.get('relevance') or {}
+        picked = topic_answer.get('choice')
+        if picked not in topics:
+            # criteria 就是 topics，正常不该发生。真发生了说明契约变了，
+            # 与其把一个陌生主题写进 frontmatter 污染下游，不如报错让调用方回退。
+            raise JevError(f'返回的主题不在候选里：{picked!r}')
+
+        score = relevance_answer.get('score')
+        return {
+            'topic': picked,
+            'topicConfidence': topic_answer.get('confidence'),
+            'topicProbabilities': topic_answer.get('probabilities'),
+            'relevance': score_to_relevance(score),
+            'relevanceScore': score,
+            # 「该不该收录」的原始概率。落盘而不是在这儿切成布尔：切点是暂定的，
+            # 留着原始值，改阈值不用重跑。
+            'includeScore': (answers.get('worth_including') or {}).get('noul'),
+            'usage': usage,
+        }
+
+
+def create_client(api_key='', model=DEFAULT_MODEL, timeout=120, config=None):
+    """拿到 key 就返回客户端，没有就返回 None（调用方据此走老路）。"""
+    key = resolve_key(api_key, config)
+    if not key:
+        return None
+    return JevClient(key, model=model, timeout=timeout)