weflow-cli 1.17.0 → 1.19.0

package/scripts/_utils.py

@@ -1,1338 +1,1338 @@
-"""
-weflow-cli 公共工具函数 — 供 biz_daily / classify_daily / chat_report 等共用。
-"""
-import os, json, re, base64, socket, urllib.request, hashlib
-from functools import wraps
-
-
-# ======================================================================
-# 工具库（静态知识，供报告「行动指南」自动匹配）
-# 按关键词 → GitHub 项目/工具，匹配越靠前优先级越高
-# ======================================================================
-
-TOOL_LIBRARY = [
-    # --- AI 编程 / Agent ---
-    {'keywords': ['cursor', 'agent', 'ide', '编程助手', '代码生成'],
-     'name': 'Cursor', 'url': 'https://github.com/getcursor/cursor',
-     'desc': 'AI 原生 IDE，支持多文件编辑与 Agent 模式'},
-    {'keywords': ['windsurf', 'agent', 'ide'],
-     'name': 'Windsurf', 'url': 'https://codeium.com/windsurf',
-     'desc': 'AI 原生 IDE，类 Cursor，支持任务级自动编程'},
-    {'keywords': ['continue', 'agent', 'ide', 'vscode'],
-     'name': 'Continue', 'url': 'https://github.com/continuedev/continue',
-     'desc': '开源 VS Code 插件，接入本地/云端大模型'},
-
-    # --- 大模型 / 推理 ---
-    {'keywords': ['deepseek', 'r1', '开源模型'],
-     'name': 'DeepSeek R1', 'url': 'https://github.com/deepseek-ai/DeepSeek-R1',
-     'desc': 'DeepSeek 开源推理模型，中文表现强'},
-    {'keywords': ['llama', 'meta', '开源模型'],
-     'name': 'Llama 3', 'url': 'https://github.com/meta-llama/llama3',
-     'desc': 'Meta 开源大模型，社区生态最成熟'},
-    {'keywords': ['ollama', '本地部署', '本地推理'],
-     'name': 'Ollama', 'url': 'https://github.com/ollama/ollama',
-     'desc': '一行命令运行本地大模型（macOS/Linux/Windows）'},
-    {'keywords': ['lmstudio', '本地部署', '本地推理'],
-     'name': 'LM Studio', 'url': 'https://lmstudio.ai',
-     'desc': '桌面端本地大模型运行器，有 GUI'},
-
-    # --- 信息聚合 / 日报 / RAG ---
-    {'keywords': ['rag', '检索增强', '知识库', '论文'],
-     'name': 'AnythingLLM', 'url': 'https://github.com/Mintplex-Labs/anything-llm',
-     'desc': '开箱即用的 RAG 知识库 + 聊天桌面应用'},
-    {'keywords': ['rss', '信息源', '订阅'],
-     'name': 'Fluent Reader', 'url': 'https://github.com/yang991178/fluent-reader',
-     'desc': '现代化 RSS 阅读器，聚合公众号/博客/新闻'},
-
-    # --- 环境科学 / 交叉方向 ---
-    {'keywords': ['遥感', '卫星', '反演', 'landsat', 'sentinel'],
-     'name': 'Google Earth Engine', 'url': 'https://earthengine.google.com',
-     'desc': '大规模遥感影像在线分析平台'},
-    {'keywords': ['遥感', '卫星', 'python'],
-     'name': 'xarray', 'url': 'https://github.com/pydata/xarray',
-     'desc': 'N 维数组处理，气象/遥感数据标配'},
-    {'keywords': ['大气', '排放清单', '排放'],
-     'name': 'MEIC', 'url': 'https://meicmodel.org',
-     'desc': '中国多尺度排放清单模型'},
-    {'keywords': ['lca', '生命周期', '生命周期评估'],
-     'name': 'brightway', 'url': 'https://github.com/brightway-lca/brightway2',
-     'desc': '开源生命周期评估（LCA）框架'},
-    {'keywords': ['数值模拟', '大气', '模型', '模拟'],
-     'name': 'WRF', 'url': 'https://github.com/wrf-model/WRF',
-     'desc': '中尺度数值天气预报模型'},
-
-    # --- 效率工具 ---
-    {'keywords': ['obsidian', '笔记', '知识管理'],
-     'name': 'Obsidian', 'url': 'https://obsidian.md',
-     'desc': '本地优先的 Markdown 笔记，双链/图谱'},
-    {'keywords': ['anki', '记忆', '复习'],
-     'name': 'Anki', 'url': 'https://apps.ankiweb.net',
-     'desc': '基于间隔重复的闪卡记忆工具'},
-
-    # --- 一般关键词兜底 ---
-    {'keywords': ['投资', '财报', '股价', '股票'],
-     'name': 'Tushare', 'url': 'https://tushare.pro',
-     'desc': '免费金融数据接口（Python）'},
-]
-
-
-def match_tools(articles: list[dict], top_n: int = 8) -> list[dict]:
-    """从文章的标题/摘要/标签中抽取关键词，匹配 TOOL_LIBRARY。"""
-    collected_text = ''
-    for a in articles:
-        tags = a.get('tags') or []
-        text_parts = [
-            a.get('title', ''),
-            a.get('summary', ''),
-            ' '.join(tags) if isinstance(tags, list) else str(tags),
-        ]
-        collected_text += ' ' + ' '.join(text_parts)
-    collected_text = collected_text.lower()
-
-    ranked = []
-    for tool in TOOL_LIBRARY:
-        score = sum(1 for kw in tool['keywords'] if kw.lower() in collected_text)
-        if score > 0:
-            ranked.append((score, tool))
-    ranked.sort(key=lambda x: x[0], reverse=True)
-    return [t for _, t in ranked[:top_n]]
-
-
-# ======================================================================
-# Config
-# ======================================================================
-
-CONFIG_PATH = os.path.join(os.path.expanduser('~'), '.weflow-cli', 'config.json')
-
-
-# ======================================================================
-# AI Engine 抽象
-# ======================================================================
-
-class AIEngine:
-    """OpenAI-compatible API 引擎基类。"""
-    def __init__(self, api_key: str, base_url: str, model: str, timeout=60):
-        self.api_key = api_key
-        self.base_url = base_url.rstrip('/')
-        self.model = model
-        self.timeout = timeout
-
-    def chat(self, prompt: str, max_tokens=2000) -> str:
-        payload = json.dumps({
-            'model': self.model,
-            'messages': [{'role': 'user', 'content': prompt}],
-            'max_tokens': max_tokens,
-            'temperature': 0.2,
-        }).encode('utf-8')
-        req = urllib.request.Request(
-            f'{self.base_url}/chat/completions',
-            data=payload,
-            headers={
-                'Content-Type': 'application/json',
-                'Authorization': f'Bearer {self.api_key}',
-            },
-            method='POST',
-        )
-        with urllib.request.urlopen(req, timeout=self.timeout) as resp:
-            data = json.loads(resp.read())
-        return data['choices'][0]['message']['content']
-
-
-class AnthropicEngine(AIEngine):
-    """Anthropic Messages API 引擎（/v1/messages）。"""
-    def __init__(self, api_key: str, base_url: str, model: str, timeout=120):
-        super().__init__(api_key, base_url, model, timeout=timeout)
-
-    def chat(self, prompt: str, max_tokens=2000) -> str:
-        payload = json.dumps({
-            'model': self.model,
-            'messages': [{'role': 'user', 'content': prompt}],
-            'max_tokens': max_tokens,
-        }).encode('utf-8')
-        req = urllib.request.Request(
-            f'{self.base_url}/messages',
-            data=payload,
-            headers={
-                'Content-Type': 'application/json',
-                'x-api-key': self.api_key,
-                'anthropic-version': '2023-06-01',
-                'Authorization': f'Bearer {self.api_key}',
-            },
-            method='POST',
-        )
-        with urllib.request.urlopen(req, timeout=self.timeout) as resp:
-            data = json.loads(resp.read())
-        return data['content'][0]['text']
-
-
-class DeepSeekEngine(AIEngine):
-    def __init__(self, api_key: str, model='deepseek-chat', timeout=180):
-        super().__init__(api_key, 'https://api.deepseek.com/v1', model, timeout=timeout)
-
-
-class ClaudeEngine(AIEngine):
-    def __init__(self, api_key: str, model='claude-sonnet-4-6', timeout=90):
-        super().__init__(api_key, 'https://api.anthropic.com/v1', model, timeout=timeout)
-
-
-class OllamaEngine(AIEngine):
-    def __init__(self, model='llama3', timeout=120):
-        super().__init__('ollama', 'http://localhost:11434/v1', model, timeout=timeout)
-
-
-# ======================================================================
-# 本地引擎自动检测
-# ======================================================================
-
-_LOCAL_ENDPOINTS = [
-    # (name, base_url, api_style)
-    ('ollama',    'http://localhost:11434',  'openai'),
-    ('lmstudio',  'http://localhost:1234', 'openai'),
-    ('claude',    'http://localhost:8080',  'anthropic'),
-    ('lmstudio',  'http://localhost:8000', 'openai'),
-    ('lmstudio',  'http://localhost:3000', 'openai'),
-]
-
-
-def _try_local_endpoint(name: str, base_url: str, api_style: str,
-                       timeout: int = 5) -> tuple[bool, str, str, str]:
-    health_path = f'{base_url}/v1/models'
-    try:
-        req = urllib.request.Request(health_path, headers={'Accept': 'application/json'})
-        with urllib.request.urlopen(req, timeout=timeout) as resp:
-            data = json.loads(resp.read())
-        models = data.get('data', data.get('models', []))
-        if not models:
-            return True, name, base_url, 'local'
-        first = models[0]
-        model_name = first.get('id', first.get('model', 'local'))
-        return True, name, base_url, model_name
-    except Exception as e:
-        return False, name, base_url, str(e)
-
-
-def detect_local_engine(timeout: int = 5) -> tuple[bool, AIEngine, str]:
-    """自动检测本地推理服务。返回 (detected, engine, description)。"""
-    checked = set()
-    for name, base_url, api_style in _LOCAL_ENDPOINTS:
-        key = (name, base_url)
-        if key in checked:
-            continue
-        checked.add(key)
-        ok, dname, durl, model = _try_local_endpoint(name, base_url, api_style, timeout)
-        if not ok:
-            continue
-        if api_style == 'anthropic':
-            engine = AnthropicEngine('local', durl, model, timeout=180)
-        else:
-            engine = OllamaEngine(model=model, timeout=180)
-            engine.base_url = durl.rstrip('/') + '/v1'
-        desc = f'{dname} ({model}@{durl})'
-        return True, engine, desc
-    return False, None, '无可用本地推理服务'
-
-
-def create_engine(engine_type: str, api_key: str = '') -> AIEngine:
-    """工厂函数：根据类型创建 AI 引擎。
-
-    引擎类型: local(自动检测) / deepseek / claude / ollama
-    配置 aiBaseUrl 时, deepseek 引擎走自定义 OpenAI 兼容端点 (中转站)。
-    """
-    t = engine_type.lower()
-    if t == 'local':
-        ok, engine, desc = detect_local_engine(timeout=8)
-        if not ok:
-            raise RuntimeError(
-                '未检测到本地推理服务。请启动以下任一服务后重试：\n'
-                '  • Ollama:     ollama serve          (11434)\n'
-                '  • LM Studio:  lmstudio server start (1234)\n'
-                '  • Claude Code 本地服务 (8080)\n'
-                '或使用 --engine deepseek/claude 指定云端引擎。'
-            )
-        return engine
-    elif t == 'deepseek':
-        base_url, model = _custom_endpoint()
-        if base_url:
-            return AIEngine(api_key, base_url, model)
-        return DeepSeekEngine(api_key)
-    elif t == 'claude':
-        return ClaudeEngine(api_key)
-    elif t == 'ollama':
-        return OllamaEngine()
-    raise ValueError(
-        f'未知引擎: {engine_type}，可选: local / deepseek / claude / ollama'
-    )
-
-
-def _custom_endpoint():
-    """读取 config.json 的 aiBaseUrl/aiModel; 未配置返回 (None, None)。"""
-    try:
-        with open(CONFIG_PATH, encoding='utf-8') as f:
-            cfg = json.load(f)
-        base_url = (cfg.get('aiBaseUrl') or '').strip().rstrip('/')
-        model = (cfg.get('aiModel') or '').strip() or 'deepseek-chat'
-        return (base_url or None), (model if base_url else None)
-    except Exception:
-        return None, None
-
-
-def call_deepseek(prompt: str, api_key: str, max_tokens=2000, timeout=60) -> str:
-    """向后兼容：调用 DeepSeek API。"""
-    return DeepSeekEngine(api_key, timeout=timeout).chat(prompt, max_tokens=max_tokens)
-
-
-def call_ai(prompt: str, engine_type: str = 'local', api_key: str = '', max_tokens=2000) -> str:
-    """通用 AI 调用：支持 local/deepseek/claude/ollama 引擎。"""
-    engine = create_engine(engine_type, api_key)
-    return engine.chat(prompt, max_tokens=max_tokens)
-
-
-# ======================================================================
-# 缓存机制 — 避免重跑 pipeline 时重复调用 API
-# ======================================================================
-
-_CACHE_DIR = os.path.join(os.path.dirname(os.path.dirname(os.path.abspath(__file__))),
-                          'output', '.cache')
-
-
-def _cache_key(*args, **kwargs) -> str:
-    """根据参数生成 MD5 缓存 key。"""
-    raw = json.dumps({'args': args, 'kwargs': kwargs}, sort_keys=True, ensure_ascii=False)
-    return hashlib.md5(raw.encode('utf-8')).hexdigest()
-
-
-def cached_call(func, *args, cache_subdir: str = '', **kwargs):
-    """带缓存的函数调用。命中缓存则直接返回，否则调用 func 并存储结果。
-
-    Args:
-        func: 要调用的函数（需返回可 JSON 序列化的结果）
-        cache_subdir: 缓存子目录名（如 'classify'、'wiki'）
-    """
-    cache_dir = os.path.join(_CACHE_DIR, cache_subdir) if cache_subdir else _CACHE_DIR
-    os.makedirs(cache_dir, exist_ok=True)
-    key = _cache_key(func.__name__, *args, **kwargs)
-    cache_file = os.path.join(cache_dir, f'{key}.json')
-
-    if os.path.exists(cache_file):
-        try:
-            with open(cache_file, 'r', encoding='utf-8') as f:
-                return json.load(f)
-        except (json.JSONDecodeError, OSError):
-            pass  # 缓存损坏，重新调用
-
-    result = func(*args, **kwargs)
-    try:
-        with open(cache_file, 'w', encoding='utf-8') as f:
-            json.dump(result, f, ensure_ascii=False)
-    except (TypeError, OSError):
-        pass  # 结果不可序列化或写入失败，跳过缓存
-
-    return result
-
-
-def clear_cache(cache_subdir: str = ''):
-    """清空指定子目录的缓存，或全部缓存。"""
-    target = os.path.join(_CACHE_DIR, cache_subdir) if cache_subdir else _CACHE_DIR
-    if not os.path.isdir(target):
-        return
-    for fname in os.listdir(target):
-        fpath = os.path.join(target, fname)
-        if os.path.isfile(fpath):
-            os.unlink(fpath)
-# ======================================================================
-# Config Decrypt
-# ======================================================================
-
-# ======================================================================
-# 主题分类法 —— **唯一一处定义**
-#
-# 列表与定义都收在这里，因为「散文写的枚举会漂」在这个仓库里已经真的发生过：
-# `biz_daily.TOPIC_PROMPT` 的第一行按 TOPICS 生成了六类，但同一段提示词后面两处
-# 提醒是硬编码的五类（少了政治），判断规则里也没有政治那一栏——而政治在语料里占 26%。
-# 两条路径（LLM 提示词 / 决策模型的判据）现在读同一张表，所以它们不可能再对不上。
-#
-# **顺序有意义**：`generate_ai_report` 按这个顺序给报告分栏。
-TOPICS = ['AI', '学术', '新闻', '文学', '投资', '政治']
-
-# 聊天卡拷进 Vault `Sources/Chat/` 时的文件名前缀。**必须共享**：`chat_notes` 用它写文件、
-# `compile_wiki` 用它把概念页的"来源"链接指过去——两处各写一份就是"同一条信息写两处"，
-# 而这个仓库已经因为这类分叉吃过亏。
-# 为什么要有这个前缀：聊天卡的名字**就是会话名**（`白马非马`、`老表亲戚群`），而概念页
-# 也可能叫同一个名字；两个文件同名时 `[[白马非马]]` 在 Obsidian 里是二义的。
-CHAT_CARD_PREFIX = '会话-'
-
-# 知识页住在哪几个目录（**Vault 相对路径**）。**分成两个是有意的**：用户明确要求
-# 聊天知识库与公众号文章知识库分开（2026-09-27），所以是"一条线一个目录"而不是混在一起。
-# 顺序即展示顺序：文章在前。
-#
-# 读的一方（`wiki_lint` / `vault_search` / `vault_rag` / 助手的 `search_knowledge`）
-# 都要把**两个都读**，否则新分出去的那一半会静默地搜不到——而这个仓库已经因为
-# "同一个事实写在两处"栽过好几次，所以 TS 那边有一份平行的列表，有测试钉住两者一致。
-#
-# 这一层是 2026-10-10 立的：用户要求两条线**各自一棵树**（不只是同根下的两个子目录），
-# 而"一串 Vault 相对路径"这个形状把"共用一个根"写死了 ⇒ 改值不够、得先改形状。
-# 现在两条线的根**仍然相同**（物理迁移还没做），所以下面这层只是把形状立起来；
-# 迁移时只改 `root` 的值，不再动形状。**唯一源头**：`CONCEPT_DIRS` 由它派生，
-# 图谱那两处曾经的硬编码也改读它。
-KNOWLEDGE_LINES = (
-    # (线 id, 根, 线内的概念目录)
-    ('wiki', 'output/wechat-vault', 'Wiki/Concepts'),
-    ('chat', 'output/wechat-vault', 'Chat/Concepts'),
-)
-
-
-def concept_dirs():
-    """所有线的概念目录（Vault 相对路径），顺序即展示顺序：文章在前。"""
-    return tuple(concepts for _line, _root, concepts in KNOWLEDGE_LINES)
-
-
-CONCEPT_DIRS = concept_dirs()
-
-
-def line_for_concept_dir(path):
-    """给一个概念目录（任意写法）→ 线 id；认不出就返回 None（**不猜**）。
-
-    认不出是正常情形（`wiki compile --output` 可以指到库外的任意目录），
-    调用方要按"没有线"处理，而不是当成某条线。
-    """
-    try:
-        target = os.path.normcase(os.path.abspath(str(path)))
-    except Exception:
-        return None
-    for line_id, root, concepts in KNOWLEDGE_LINES:
-        if target == os.path.normcase(os.path.abspath(os.path.join(root, concepts))):
-            return line_id
-    return None
-
-
-# 线的展示名。**只此一份**：图谱的提示、体检的报告、助手的输出都取它，各写一句
-# "文章线/聊天线"的后果是改词那天只改到一半，而没有任何东西会红。
-LINE_LABELS = {'wiki': '文章线', 'chat': '聊天线'}
-
-# 主键的分隔符。选 `:` 是因为**概念页的文件名里不可能有它**（Windows 禁止，
-# `compile_wiki` 也会把它换成 `_`）—— 主键要能被原样切回 (线, 名字)，
-# 这个判据就必须没有二义。改成 `-` 或 `_` 都会把 `AI-Agent` 这类名字切错，
-# 而症状是"图谱里两个节点凭一个错名字连上了"，不报错。
-LINE_SEP = ':'
-
-
-def line_for_relative_concepts(relative):
-    """给一个**库内相对**概念目录（`Wiki/Concepts`）→ 线 id；认不出返回 None（**不猜**）。
-
-    与 `line_for_concept_dir` 的分工：那个比的是**绝对路径**（适合已经知道库根的调用方）；
-    这个只比对清单里那串相对路径 —— 测试里的临时库、或 `--vault` 指到别处时库根对不上，
-    但"`Chat/Concepts` 属于聊天线"这一层仍然成立。
-    """
-    def norm(p):
-        return os.path.normcase(str(p).replace('/', os.sep).replace('\\', os.sep))
-    for line_id, _root, concepts in KNOWLEDGE_LINES:
-        if norm(concepts) == norm(relative):
-            return line_id
-    return None
-
-
-def line_concepts_path(line_id):
-    """线 id → 它的概念目录（**库内相对路径**，`Wiki/Concepts`）；认不出返回 None。"""
-    for lid, _root, concepts in KNOWLEDGE_LINES:
-        if lid == line_id:
-            return concepts
-    return None
-
-
-def concept_link_target(line_id, name, other_line_names=()):
-    """渲染一个概念链接该写成什么目标。
-
-    **只在"另一条线也有这个名字"时才带路径**（`Chat/Concepts/DeepSeek|DeepSeek`）：
-    两条线同名时裸 `[[DeepSeek]]` 在 Obsidian 里是二义的（官方判据：会 deterministic
-    解析，但不保证命中你想要的那张），所以给目标带上路径、用 `|` 保住显示文本。
-    只属于一条线的名字**一个字节都不动** —— 否则 4.9 万张页里绝大多数链接都要白重写
-    一遍，而那样改出来的 diff 没人看得完。
-    """
-    if name in other_line_names:
-        concepts = line_concepts_path(line_id)
-        if concepts:
-            return '%s/%s|%s' % (concepts, name, name)
-    return name
-
-
-def link_target_name(raw):
-    """`[[…]]` 里抓到的那一串 → 概念名。**解析只此一份。**
-
-    `[[Chat/Concepts/DeepSeek|DeepSeek]]` → `DeepSeek`。各处自己写 `split('|')` 的话，
-    漏掉一处那处的边就整条丢掉，而图里少一条边不报错。
-
-    **改动面越小越好**：只切掉 `|显示文本`，并且**只对带线路径的那些**再去掉前缀。
-    其余一律原样返回 —— 这个函数的上游既有"概念名"也有"卡片名"，随手多切一刀就会
-    改掉既有行为：
-
-    - 别切 `#`：这个库里的概念名**真的带 `#`**（`#GPT6`、`Erdős#1026`）。切了它们会被
-      当成别的名字，指向它们的边整条消失（2026-10-10 实测少了 4 条边，而图里少边不报错）。
-    - 别切 `.md`：`## 来源` 的卡片链接就写成 `[[名字.md]]`，`wiki_lint.resolve` 靠这个
-      后缀把它分流到卡片目录。切了它，那一支就再也不走了。
-    """
-    name = str(raw or '').strip()
-    if '|' in name:
-        name = name.split('|', 1)[0].strip()      # `[[目标|显示文本]]` → 目标
-    norm = name.replace('\\', '/')
-    for _lid, _root, concepts in KNOWLEDGE_LINES:
-        prefix = concepts + '/'
-        if norm.startswith(prefix):
-            norm = norm[len(prefix):]
-            if norm.lower().endswith('.md'):      # 带路径的写法里才去后缀（我们自己写的那种）
-                norm = norm[:-3]
-            break
-    return norm.strip()
-
-
-def is_line_qualified(raw):
-    """这条链接是不是**带了线的路径前缀**（`Wiki/Concepts/…` / `Chat/Concepts/…`）。
-
-    体检用它区分"已经消歧过的链接"和"还是裸的二义链接"。
-    """
-    name = str(raw or '').strip()
-    if '|' in name:
-        name = name.split('|', 1)[0].strip()
-    norm = name.replace('\\', '/')
-    for _lid, _root, concepts in KNOWLEDGE_LINES:
-        if norm == concepts or norm.startswith(concepts + '/'):
-            return True
-    return False
-
-
-def sibling_concepts_dir(concept_dir):
-    """同一个库里**另一条线**的概念目录；认不出线、或它不存在 → None。
-
-    **两级**：两条线都是 `<库>/<线>/Concepts`，库根是 `concept_dir.parent.parent`。
-    写成一级的话候选恒不存在（`<库>/Chat/Wiki/Concepts`）—— 于是"另一条线没有这个名字"
-    永远成立，链接不会带路径，而 Obsidian 里那条裸链接就**悄悄**变成二义的。
-    2026-09-27 那段同样的两级路径就是这么栽过一次（写在已删掉的那个函数的注释里）。
-
-    认线用**路径尾两段**而不是绝对路径（`line_for_relative_concepts`）：测试里的临时库、
-    或者用户把库根换了地方，尾两段仍然是 `Chat/Concepts` ⇒ 认得出；用绝对路径的话
-    只有仓库里那两个真实根才认得出，别的地方会安静地退化成"没有另一条线"。
-    """
-    norm = str(concept_dir).replace('\\', '/').rstrip('/')
-    parts = [p for p in norm.split('/') if p]
-    if len(parts) < 2:
-        return None
-    my_line = line_for_relative_concepts('/'.join(parts[-2:]))
-    if not my_line:
-        return None                       # 库外的目录：那里没有"另一条线"
-    root = os.path.dirname(os.path.dirname(norm))
-    for line_id, _r, concepts in KNOWLEDGE_LINES:
-        if line_id == my_line:
-            continue
-        candidate = os.path.join(root, *concepts.split('/'))
-        if os.path.isdir(candidate):
-            return candidate
-    return None
-
-
-def concept_names(concept_dir):
-    """那个目录里的概念名（文件名去掉 `.md`）。读不出来就返回空集（不猜）。"""
-    try:
-        return {f[:-3] for f in os.listdir(str(concept_dir)) if f.endswith('.md')}
-    except OSError:
-        return set()
-
-
-class LinkNamer:
-    """把概念名渲染成链接目标 —— **跨线同名时才带路径**，其余原样。
-
-    为什么要一个对象而不是每处写一句：**渲染点有三处**（模型建页、零模型建页、索引表），
-    各写一份的话漏一处就会在库里留下一批裸的二义链接，而它只在有人跑 `wiki lint` 时
-    才看得见。判断"要不要带路径"只需要另一条线的**文件名集合**，所以构造一次就够。
-    """
-
-    def __init__(self, line_id, other_names=()):
-        self.line_id = line_id or ''
-        self.other_names = set(other_names)
-
-    @classmethod
-    def for_out_dir(cls, out_dir):
-        """按输出目录定线，并顺手把另一条线的名字读出来（一次 listdir）。
-
-        认线用**路径尾两段**（`Chat/Concepts`），所以测试里的临时库、或库根换了地方都认得出。
-        认不出线（`--output` 指到库外的任意目录）时 **`line_id` 为空 → 一律渲染成裸名字**：
-        那是"库外目录"的既有行为，而不是按猜出来的线写一堆带路径的链接。
-        """
-        parts = [p for p in str(out_dir).replace('\\', '/').rstrip('/').split('/') if p]
-        line_id = line_for_relative_concepts('/'.join(parts[-2:])) if len(parts) >= 2 else None
-        if not line_id:
-            return cls('', ())
-        sibling = sibling_concepts_dir(out_dir)
-        return cls(line_id, concept_names(sibling) if sibling else ())
-
-    def __call__(self, name):
-        if not self.line_id:
-            return name
-        return concept_link_target(self.line_id, name, self.other_names)
-
-
-def concept_key(line_id, name):
-    """线 id + 概念名 → 跨线唯一的主键。
-
-    **为什么需要**：两条线各有一张同名页是设计使然（用户 2026-10-10 要求两个概念
-    命名空间分开），而图谱的主键原来就是文件 stem ⇒ 两棵目录里的 `DeepSeek` 是
-    **同一个键**。2026-10-10 实测：合并图里 49,956 个节点里有 36 组撞键，前端
-    `new Map(NODES.map(n => [n.id, n]))` 会静默只留一个 —— 节点数看着对，少掉的那个
-    却点不到。同名的两页靠这个键分开。
-    """
-    return '%s%s%s' % (line_id, LINE_SEP, name)
-
-
-def split_concept_key(key):
-    """主键 → (线 id, 名字)；**认不出线就返回 `(None, 原样)`，不猜**。
-
-    兼容没有线前缀的旧主键（认不出线的情形），调用方按"没有线"处理。
-    """
-    line_id, sep, name = str(key).partition(LINE_SEP)
-    if not sep or line_id not in LINE_LABELS:
-        return None, str(key)
-    return line_id, name
-
-
-def line_label(line_id):
-    """线 id → 展示名；认不出返回 None（调用方自己决定"无线"怎么写）。"""
-    return LINE_LABELS.get(line_id)
-
-# 一篇文章**没能被分类**时落到哪一类。
-#
-# 收成一处是因为它曾经在写入路径上有两个不同的答案、相隔七行：
-# `.articles.json` 那条路默认 `''`（空主题），而分组/落 md 那条路默认 `'学术'`。
-# 于是一篇文章在 md 里写 `topic: 学术`、在 json 里写 `topic: ""`——
-# **同一次运行、同一篇文章，两个产物给出不同的主题**，而且都不报错。
-#
-# 真实后果（2026-09-04 的产出，178 篇）：md 全落在 `学术/` 目录、frontmatter 写
-# `topic: 学术`（其中两篇是「OpenAI 深夜发布 GPT-6」「专为高管准备的 AI 助手」，
-# 明显不该是学术），而 json 里同一批全是 `""` —— 报告那条路读 json，
-# 判据 `topic != FOCUS_TOPIC and relevance != '高'` 就把它们整批静默排除了。
-#
-# 什么情况下会走到这里：`daily --no-ai`、或者没配 API key 时，Phase 2（分类）整段
-# 不跑，文章 dict 里**根本没有 `topic` 键**，而 Phase 3 照常写文件。
-#
-# 这个值是**兜底不是判断**：落到这里的文章其实是"未分类"。之所以不新造一个
-# `未分类` 类别，是因为它要额外维护一个目录、一处 HTML 分栏、以及下游对
-# 主题字面量的比较；改用 `未分类` 属于改既有契约，得单独决策。
-DEFAULT_TOPIC = '学术'
-
-# 每一类的判据。既生成提示词里的判断规则，也直接作为 Jev 的 choice criteria。
-TOPIC_CRITERIA = {
-    'AI': 'AI大模型/Agent/编程/开源/科技产品/工具教程',
-    '投资': '股票基金/融资/经济分析/商业市场',
-    '新闻': '时事政策/社会热点/娱乐/招聘促销/会议通知',
-    '文学': '散文小说/美食旅游/生活随笔/历史文化',
-    '学术': '科研论文/期刊文章/实验室成果/学术会议/高校研究',
-    '政治': '党政理论/政策解读/领导人讲话/官方评论',
-}
-
-# 相关度的三个档位。与 `TOPICS` 一样是**下游按字面量比较**的封闭词表：
-# `generate_ai_report.py`、`enrich_backlinks.py`、`generate_html.py` 都在比
-# `'高'`/`'中'`/`'低'` 这三个字。定义收在这里，`jev_client` 与 `biz_daily`
-# 都从这里取——原先 `jev_client` 一份、`biz_daily` 的成员校验里再写一份。
-#
-# **顺序即语义**：`jev_client.RELEVANCE_LEVELS` 是给模型看的判据文本，按下标与
-# 这个列表一一对应（有测试钉住），所以不要重排。
-RELEVANCE_NAMES = ['低', '中', '高']
-
-# 一篇文章**没能被判相关度**时落到哪一档。和 `DEFAULT_TOPIC` 是同一类东西：
-# 兜底不是判断。之所以要具名，是因为"全库 2199/2201 篇都是「中」"这件事的答案
-# 就在这里——分类失败的每条路径最终都落到这个值，而 `'中'` 读起来是
-# 「有启发性」（正面评价），不是「没判断」。值不变更（改档位会动到下游的
-# 收录判据），只是把它写在一处，好让它可被搜索、可被讨论。
-DEFAULT_RELEVANCE = '中'
-
-
-def load_config():
-    with open(CONFIG_PATH, 'r', encoding='utf-8') as f:
-        return json.load(f)
-
-
-# ---- 「不说话地失败」的最小护栏 ---------------------------------------------
-# 这个文件里有一批函数**故意不抛**（跨机器拷配置时，解不开的密文该表现为"没配"，
-# 而不是让整条命令崩）。但"不抛"不等于"不说"：`except: return ''` 会让调用方
-# 与用户都以为"本来就没有"，而真实原因是**解密失败/配置坏了**。
-# 所以这里只做一件事：同一条原因**说一次**，然后照旧返回空值。
-# 只说一次是必须的——这些函数每次请求/每次重排都会被调用，刷屏等于没警告。
-_WARNED_ONCE = set()
-
-
-def warn_once(tag, message):
-    """同一条原因只往 stderr 说一次（tag 相同即视为同一条）。"""
-    if tag in _WARNED_ONCE:
-        return
-    _WARNED_ONCE.add(tag)
-    import sys as _sys
-    print('[WARN] ' + message, file=_sys.stderr)
-    _sys.stderr.flush()
-
-
-def reset_warn_once():
-    """测试用：清空去重表。"""
-    _WARNED_ONCE.clear()
-
-
-# 配置里"不想在日报里看到的主题"的键名。值形如 `新闻,投资,学术`。
-EXCLUDED_TOPICS_KEY = 'dailyExcludeTopics'
-
-
-def excluded_topics(config=None, explicit='', protected=()):
-    """用户不想在日报里看到的主题集合。`explicit`（命令行）覆盖配置。
-
-    **这是展示层的开关，不是抓取层的**：正文照常抓取、照常归档，只是不出现在
-    日报里。理由是实测：拉之前只有来源+标题+摘要，按它判类型**不可靠**（与来源级
-    比对一致率仅 60%、误伤 48/217），而**排除是不可逆的**——没抓取就没归档。
-    放在展示层还换来一件事：改主意不用重抓，改个配置重新生成报告即可。
-
-    写错的主题名会被忽略并**打一行 WARN**（静默忽略会让人以为过滤生效了）。
-
-    `protected` 是不许被排除的主题（呼叫方传自己的「焦点主题」）。它比「未知主题名」
-    更值得拦一下：把焦点主题排掉，报告要么没有主体、要么直接报「未找到文章」
-    **指错方向**（那句话说去跑 biz_daily，可文章其实在）。同样 WARN 后忽略。
-    """
-    raw = explicit or (config or {}).get(EXCLUDED_TOPICS_KEY, '') or ''
-    names = [t.strip() for t in str(raw).replace('，', ',').split(',') if t.strip()]
-    out = set()
-    for name in names:
-        if name in TOPICS:
-            if name in protected:
-                print('[WARN] %s 里的「%s」是这份报告的主体，不能排除，已忽略'
-                      % (EXCLUDED_TOPICS_KEY, name))
-                continue
-            out.add(name)
-        else:
-            print('[WARN] %s 里的「%s」不是已知主题，已忽略（可选：%s）'
-                  % (EXCLUDED_TOPICS_KEY, name, '/'.join(TOPICS)))
-    return out
-
-
-# === 来源级先验："哪个号稳定发哪一类"从真实判断里长出来 ===
-#
-# 为什么不写死一张表：拉取之前只有来源+标题+摘要，按它判类型实测只有 60% 一致率、
-# 误伤 48/217（见 excluded_topics 的说明）。但**抓回来之后**每次都有 Jev 按正文判的
-# 主题，日积月累就看得出某个号一贯发什么。这张表因此是长出来的，不是我编的。
-#
-# 它现在只用来**报数**，不用来跳过任何东西：跳过是不可逆的。
-SOURCE_TOPICS_FILE = 'source_topics.json'
-SOURCE_PRIOR_MIN_SAMPLES = 8   # 少于这么多篇不下结论
-SOURCE_PRIOR_SHARE = 0.8       # 某一类占比到这个数才算"稳定地只发这一路"
-
-
-def source_topics_path(path=None):
-    """先验表的落盘位置。默认与 config.json 同目录（家目录）。"""
-    return path or os.path.join(os.path.dirname(CONFIG_PATH), SOURCE_TOPICS_FILE)
-
-
-def load_source_topics(path=None):
-    """读先验表：`{来源: {主题: 次数}}`。
-
-    读不出、坏掉、不是字典——一律返回 `{}`。这是**辅助**数据，坏了不该让日报挂掉。
-    """
-    try:
-        with open(source_topics_path(path), encoding='utf-8') as f:
-            data = json.load(f)
-    except (OSError, ValueError):
-        return {}
-    if not isinstance(data, dict):
-        return {}
-    out = {}
-    for source, counts in data.items():
-        if isinstance(source, str) and source.strip() and isinstance(counts, dict):
-            out[source] = counts
-    return out
-
-
-def record_source_topics(pairs, path=None):
-    """把这一批 `(来源, 主题)` 累加进先验表，返回摘要 dict。
-
-    **只增不减**（与 frontmatter 的 only-increase 同一个纪律）：累计次数是你事后判断
-    "这个号到底稳不稳"的唯一依据，抹掉就回不来了。
-    来源为空、主题不在 TOPICS 里的都不计——计了会污染分母，让占比算错。
-    """
-    import tempfile as _tmp   # 模块顶没导入它：本文件里它是函数内导入的
-    store = load_source_topics(path)
-    added = skipped = 0
-    for source, topic in pairs:
-        source = (source or '').strip()
-        topic = (topic or '').strip()
-        if not source or topic not in TOPICS:
-            skipped += 1
-            continue
-        bucket = store.setdefault(source, {})
-        try:
-            bucket[topic] = int(bucket.get(topic, 0)) + 1
-        except (TypeError, ValueError):
-            bucket[topic] = 1      # 值被改坏了，从 1 重新数，别让它把整个文件废掉
-        added += 1
-    target = source_topics_path(path)
-    try:
-        os.makedirs(os.path.dirname(target) or '.', exist_ok=True)
-        fd, tmp_path = _tmp.mkstemp(suffix='.json', dir=os.path.dirname(target) or '.')
-        try:
-            with os.fdopen(fd, 'w', encoding='utf-8') as f:
-                json.dump(store, f, ensure_ascii=False, indent=1, sort_keys=True)
-            os.replace(tmp_path, target)
-        except Exception:
-            if os.path.exists(tmp_path):
-                os.unlink(tmp_path)
-            raise
-    except OSError as exc:
-        # 写不进去（权限、磁盘）不能让日报失败——它只是记个账。
-        return {'sources': len(store), 'added': added, 'skipped': skipped,
-                'error': str(exc)}
-    return {'sources': len(store), 'added': added, 'skipped': skipped, 'error': ''}
-
-
-def stable_source_topic(counts, min_samples=SOURCE_PRIOR_MIN_SAMPLES,
-                        share=SOURCE_PRIOR_SHARE):
-    """某个来源是不是已经**稳定地只发某一类**。
-
-    返回 `(主题, 占比, 样本数)`；还判不了返回 `None`。
-    **`None` 是"还不知道"，不是"没有主题"**——调用方必须把这两种情况分开，
-    别把 `None` 当成某个默认主题用（那正好是"来源判不准"最坏的那种错）。
-    """
-    clean = {}
-    for topic, count in (counts or {}).items():
-        try:
-            value = int(count)
-        except (TypeError, ValueError):
-            continue
-        if value > 0:
-            clean[topic] = value
-    total = sum(clean.values())
-    if total < min_samples:
-        return None
-    topic, top = max(clean.items(), key=lambda kv: kv[1])
-    ratio = top / total
-    if ratio < share:
-        return None
-    return (topic, ratio, total)
-
-
-def source_prior_candidates(store, exclude, **kwargs):
-    """先验里"已经稳到能判"且落在排除集里的来源，按样本数从多到少。
-
-    只报出来给人看，**不据此跳过任何东西**：跳过是不可逆的，而这张表还在长。"""
-    rows = []
-    for source, counts in (store or {}).items():
-        stable = stable_source_topic(counts, **kwargs)
-        if stable and stable[0] in (exclude or ()):
-            rows.append((source, stable[0], stable[1], stable[2]))
-    return sorted(rows, key=lambda row: (-row[3], row[0]))
-
-def decrypt_lock(locked_str: str) -> str:
-    if not locked_str or not locked_str.startswith('lock:'):
-        return locked_str
-    from cryptography.hazmat.primitives.ciphers.aead import AESGCM
-    from cryptography.hazmat.primitives import hashes
-    from cryptography.hazmat.primitives.kdf.pbkdf2 import PBKDF2HMAC
-    from cryptography.hazmat.backends import default_backend
-
-    raw = base64.b64decode(locked_str[5:])
-    salt, iv, auth_tag, ciphertext = raw[:16], raw[16:28], raw[28:44], raw[44:]
-    machine_id = f'{socket.gethostname()}-{os.environ.get("USERNAME", "")}-weflow-cli'
-    kdf = PBKDF2HMAC(algorithm=hashes.SHA256(), length=32, salt=salt, iterations=100000,
-                     backend=default_backend())
-    key = kdf.derive(machine_id.encode('utf-8'))
-    aesgcm = AESGCM(key)
-    return aesgcm.decrypt(iv, ciphertext + auth_tag, None).decode()
-
-
-def get_db_config(config=None):
-    if config is None:
-        config = load_config()
-    return {
-        'nt_db': config.get('ntDbPath', ''),
-        'nt_key': decrypt_lock(config.get('ntKey', '')),
-        'nt_salt': config.get('ntSalt', ''),
-        'contact_db': config.get('contactDbPath', ''),
-        'contact_key': decrypt_lock(config.get('contactKey', '')),
-        'contact_salt': config.get('contactSalt', ''),
-    }
-
-
-def biz_message_db(config=None):
-    """订阅号（公众号）消息库 `biz_message_0.db` 的路径与钥匙，返回 `(db, key_hex, salt_hex)`。
-
-    **微信 4.x：钥匙由全库 passphrase 派生**（PBKDF2-HMAC-SHA512，256000 轮，32 字节），
-    盐取**库文件头 16 字节**。`favPassphrase` 优先，退而用 `decryptKey`；
-    更早的 `bizKey`/`bizSalt`（配了就直用）只作兼容保留——那两个键在本机早就不存在了。
-
-    抽成一个函数，是因为这把钥匙原来有**三份实现**：`biz_daily` 那份是 passphrase 派生（可用），
-    `chat_stats` 与 `mcp_bridge` 那两份只认 `bizKey`（在本机必然报『缺少密钥』，而照它们的提示去
-    `config set bizKey` 还会撞上『该键不在 CLI 可写白名单里』——越修越远）。
-    """
-    import hashlib
-    if config is None:
-        config = load_config()
-    nt_db = str(config.get('ntDbPath', ''))
-    msg_dir = os.path.dirname(nt_db.replace('\\', '/'))
-    db = os.path.join(msg_dir, 'biz_message_0.db')
-    key_enc = config.get('bizKey', '')
-    salt = config.get('bizSalt', '')
-    if key_enc and salt:
-        return db, decrypt_lock(key_enc), salt
-    pass_enc = config.get('favPassphrase', '') or config.get('decryptKey', '')
-    if not pass_enc or not os.path.exists(db):
-        raise RuntimeError(
-            '缺少订阅号数据库密钥: 请运行 weflow-cli fav set-key --passphrase <64位hex> '
-            '配置全库 passphrase (自动派生各库密钥)')
-    with open(db, 'rb') as fh:
-        salt = fh.read(16).hex()
-    key = hashlib.pbkdf2_hmac('sha512', bytes.fromhex(decrypt_lock(pass_enc)),
-                              bytes.fromhex(salt), 256000, dklen=32).hex()
-    return db, key, salt
-
-def get_api_key(config=None) -> str:
-    """读取 AI API key (自动解密 lock: 前缀)。"""
-    if config is None:
-        config = load_config()
-    return decrypt_lock(config.get('deepseekApiKey', ''))
-
-
-def get_dashscope_key(config=None) -> str:
-    """读取阿里云百炼（DashScope）的 embedding key，自动解密 lock: 前缀。
-
-    和 `get_api_key` / `get_typesafe_key` 同一形状：**不要直接 config.get**——
-    这个键进了 `ENCRYPTED_KEYS`，磁盘上是密文。解密失败回空串而不是抛，
-    理由同 get_typesafe_key（跨机器拷配置时它该表现为"没配"，不是崩）。
-    """
-    if config is None:
-        try:
-            config = load_config()
-        except Exception as exc:
-            warn_once('load_config', '读不到配置文件 %s（%s: %s）—— 本次当作空配置，需要配置的功能会退化成默认行为'
-                      % (CONFIG_PATH, type(exc).__name__, exc))
-            return ''
-    try:
-        return decrypt_lock(config.get('dashscopeApiKey', ''))
-    except Exception as exc:
-        warn_once('dashscopeApiKey', '配置项 dashscopeApiKey 解不开（%s: %s）—— 当作"没配"，语义检索会退成关键词'
-                  % (type(exc).__name__, exc))
-        return ''
-
-
-def get_typesafe_key(config=None) -> str:
-    """读取 TypeSafe (Jev) 决策模型的 key，自动解密 lock: 前缀。
-
-    解密失败**回空串而不是抛**：TS 侧 lockDecrypt() 失败就是静默回 ''，而
-    decrypt_lock() 是抛的。两份 config.json 一跨机器拷贝，同一份密文在
-    TS 侧表现为"没配 key"、在这里表现为崩——那会让日报整个挂掉，而它本该
-    只是退回到 LLM 解析路径。
-    """
-    if config is None:
-        try:
-            config = load_config()
-        except Exception as exc:
-            warn_once('load_config', '读不到配置文件 %s（%s: %s）—— 本次当作空配置，需要配置的功能会退化成默认行为'
-                      % (CONFIG_PATH, type(exc).__name__, exc))
-            return ''
-    try:
-        return decrypt_lock(config.get('typesafeApiKey', ''))
-    except Exception as exc:
-        warn_once('typesafeApiKey', '配置项 typesafeApiKey 解不开（%s: %s）—— 当作"没配"，决策模型退回 LLM 解析'
-                  % (type(exc).__name__, exc))
-        return ''
-
-
-def get_openrouter_key(config=None) -> str:
-    """读取 OpenRouter 的 key（决策模型的第二条通路，D-120），自动解密 lock: 前缀。
-
-    与 `get_typesafe_key` 逐字同一条规矩：**跨机器拷配置时表现为"没配"，不是崩**。
-    解密失败回空串之后，`create_client()` 会返回 None，调用方按老路退回 ——
-    这是"这条路没配好"的**安全**失效方向。
-    """
-    if config is None:
-        try:
-            config = load_config()
-        except Exception as exc:
-            warn_once('load_config', '读不到配置文件 %s（%s: %s）—— 本次当作空配置，需要配置的功能会退化成默认行为'
-                      % (CONFIG_PATH, type(exc).__name__, exc))
-            return ''
-    try:
-        return decrypt_lock(config.get('openrouterApiKey', ''))
-    except Exception as exc:
-        warn_once('openrouterApiKey', '配置项 openrouterApiKey 解不开（%s: %s）—— 当作"没配"，OpenRouter 那条路会停用'
-                  % (type(exc).__name__, exc))
-        return ''
-
-
-def get_judge_provider(config=None) -> str:
-    """决策模型走哪条通路：`native`（默认）、`chat`、`openrouter` 或 `local`（本机决策模型）。
-
-    **默认必须是 native**：这个开关存在的意义是"本机原生被地区封锁时换条路"，
-    而不是替所有用户改行为。取值不认识时也回 native —— 打错的配置项不该把判断整层关掉。
-    """
-    if config is None:
-        try:
-            config = load_config()
-        except Exception:
-            return 'native'
-    value = str((config or {}).get('judgeProvider') or '').strip().lower()
-    return value if value in ('native', 'chat', 'openrouter', 'local') else 'native'
-
-
-# 本地决策模型服务的默认地址：`python decide.py serve --port 8090` 起的那个（D-127）。
-DEFAULT_JUDGE_LOCAL_URL = 'http://127.0.0.1:8090'
-
-
-def get_judge_local_url(config=None) -> str:
-    """`judgeProvider=local` 时往哪发：配置项 `judgeLocalUrl`，没配就用默认地址。
-
-    与 `get_chat_endpoint` 同一态度：配置读不出来就当没配，返回默认值而不是抛 ——
-    这里抛会让"本机能跑但配置少一个键"变成整条判断链不可用。
-    """
-    if config is None:
-        try:
-            config = load_config()
-        except Exception:
-            return DEFAULT_JUDGE_LOCAL_URL
-    value = str((config or {}).get('judgeLocalUrl') or '').strip()
-    return value.rstrip('/') or DEFAULT_JUDGE_LOCAL_URL
-
-
-def get_chat_endpoint(config=None):
-    """`judgeProvider=chat` 时该往哪个 (base_url, model) 发 —— 与"中转站"同一条口径。
-
-    故意只做一件事：**委托 `_custom_endpoint()`**。那个函数是 `aiBaseUrl`/`aiModel` 的权威读法
-    （base 与 model 成对出现），判断器另写一份就会在"只配了 base 没配 model"这类组合上分叉，
-    而分叉的表现是"发去了错的端点"——不报错、只是判断质量变了。没配 `aiBaseUrl` 时返回 (None, None)。
-    """
-    try:
-        return _custom_endpoint()
-    except Exception:
-        return None, None
-
-
-def get_ai_engine(config=None) -> str:
-    """配置里选的对话引擎：`local` / `deepseek`（默认）/ `claude` / `ollama`。
-
-    **决策模型的 `chat` 通路必须读它**：`judgeProvider=chat` 的语义是"用**配置里的**对话模型"，
-    而"配置里的"到底指谁只有 `aiEngine` 说得清。2026-10-18 之前那条路无条件用 `deepseekApiKey`，
-    于是 `aiEngine=local` 的用户一开 `judgeProvider=chat` 就会把文章正文发去 DeepSeek ——
-    这不是"多花点钱"，是**用户明确选了不出境之后又被送出境**。
-    """
-    if config is None:
-        try:
-            config = load_config()
-        except Exception as exc:
-            warn_once('load_config', '读不到配置文件 %s（%s: %s）—— 本次当作空配置，需要配置的功能会退化成默认行为'
-                      % (CONFIG_PATH, type(exc).__name__, exc))
-            return 'deepseek'
-    return str((config or {}).get('aiEngine') or 'deepseek').strip().lower()
-
-
-def get_openrouter_model(config=None) -> str:
-    """OpenRouter 上用的模型 id（默认 `typesafe/jev-router`，即 TypeSafe 发布的决策模型）。
-
-    ⚠️ **地区限制是逐模型的**（实测 2026-10-17）：`typesafe/jev-router` 与 `:free` 模型能通，
-    付费通用模型（`openai/gpt-4o-mini`）在本地区返回 403。换模型必须重测，见 D-120。
-    """
-    if config is None:
-        try:
-            config = load_config()
-        except Exception as exc:
-            warn_once('load_config', '读不到配置文件 %s（%s: %s）—— 本次当作空配置，需要配置的功能会退化成默认行为'
-                      % (CONFIG_PATH, type(exc).__name__, exc))
-            return ''
-    return str((config or {}).get('openrouterJudgeModel') or '').strip()
-
-
-# ======================================================================
-# Markdown / Frontmatter
-# ======================================================================
-
-def write_with_frontmatter(filepath: str, frontmatter: dict, body: str):
-    import tempfile as _tmp
-    fm_lines = ['---']
-    for k, v in frontmatter.items():
-        if isinstance(v, list):
-            fm_lines.append(f'{k}: [{", ".join(v)}]')
-        elif isinstance(v, str) and ('"' in v or ':' in v or '#' in v):
-            vs = v.strip()
-            fm_lines.append(f'{k}: "{vs}"' if not (vs.startswith('"') and vs.endswith('"'))
-                            else f'{k}: {v}')
-        else:
-            fm_lines.append(f'{k}: {v}')
-    fm_lines.append('---')
-    fm_block = '\n'.join(fm_lines) + '\n\n'
-    dir_name = os.path.dirname(filepath) or '.'
-    fd, tmp_path = _tmp.mkstemp(suffix='.md', dir=dir_name)
-    try:
-        with os.fdopen(fd, 'w', encoding='utf-8') as f:
-            f.write(fm_block)
-            f.write(body)
-        os.replace(tmp_path, filepath)
-    except Exception:
-        if os.path.exists(tmp_path):
-            os.unlink(tmp_path)
-        raise
-
-
-def _unquote(item: str) -> str:
-    """拆掉**成对的**外层引号；不成对就一个字都不动。
-
-    原来这里写的是 `item.strip().strip('"\\'')` —— `.strip()` 的语义是"剥掉首尾**所有**这些
-    字符"，于是项**内部**末尾的引号也被吃掉：`AI 长出"手脚"` 读回来变成 `AI 长出"手脚`。
-    一个字符之差、不报错，下游只表现为"这个名字对不上"（2026-10-01：一张概念页的别名因此
-    永远匹配不上卡片里的链接，那页被报成孤儿）。成对判断把它修好，同时保住"外层引号是语法"。
-    """
-    item = item.strip()
-    if len(item) >= 2 and item[0] == item[-1] and item[0] in '"\'':
-        return item[1:-1]
-    return item
-
-
-def parse_frontmatter(content: str) -> tuple[dict, str]:
-    """解析 Markdown 文件中的 YAML frontmatter。"""
-    if not content.startswith('---'):
-        return {}, content
-    end = content.find('---', 3)
-    if end == -1:
-        return {}, content
-    fm_text = content[3:end].strip()
-    body = content[end + 3:].lstrip('\n')
-    result = {}
-    for line in fm_text.split('\n'):
-        line = line.strip()
-        if not line or ':' not in line:
-            continue
-        key, _, val = line.partition(':')
-        key = key.strip()
-        val = val.strip()
-        if val.startswith('[') and val.endswith(']'):
-            inner = val[1:-1]
-            items = [_unquote(v) for v in inner.split(',')] if inner.strip() else []
-            result[key] = items
-        elif val.startswith('"') and val.endswith('"'):
-            result[key] = val[1:-1]
-        elif val.startswith("'") and val.endswith("'"):
-            result[key] = val[1:-1]
-        else:
-            result[key] = val
-    return result, body
-
-
-NORM_STRIP_RE = re.compile(r'[\s\-_·、，.。:：/\\（）()\[\]【】"\’]+')
-
-
-def normalize_concept_name(name: str) -> str:
-    """判「这两个名字是不是同一个概念」用的规范形。
-
-    去空格、连字符、下划线、标点，转小写，再去掉英文复数尾 —— 实测这样能把
-    `GPT 5.6`/`GPT-5.6`/`GPT5.6`、`AI 工具`/`AI工具`、`AI skill`/`AI skills` 收到一起。
-
-    **它也会把 `news`/`new` 收到一起**，所以它只用来**提议**合并；真正的裁决是
-    "留来源最多的那张页"，而且删之前还有 `--dry-run` 可以看名单。
-
-    住在这里（而不是 `compile_wiki`）是因为**两个读者必须用同一个口径**：`compile_wiki
-    --merge-duplicates` 拿它决定合并谁，`wiki_lint` 拿它报告"还有哪些是同一个节点的两种写法"。
-    两边各写一份的话，体检报出来的名单就会有一半是合并工具不会动的 —— 2026-09-28 之前正是
-    如此：lint 用的是另一套（把所有非字母数字都去掉），于是 `DeepSeek++` 在它眼里等于
-    `DeepSeek`，而合并工具并不这么认为。
-    """
-    stripped = NORM_STRIP_RE.sub('', name.casefold().strip())
-    return re.sub(r'(?<=[a-z])s$', '', stripped)
-
-
-def format_wikilinks(concepts: list[tuple[str, str]]) -> str:
-    lines = ['## 相关概念', '']
-    for name, desc in concepts:
-        if desc:
-            lines.append(f'- [[{name}]] — {desc}')
-        else:
-            lines.append(f'- [[{name}]]')
-    return '\n'.join(lines) + '\n'
-
-
-# ======================================================================
-# 用户定位 & 行动建议（向后兼容）
-# ======================================================================
-
-DEFAULT_USER_PROFILE = (
-    '你是一名对AI感兴趣的环境科学研究生，研究方向是计算机与环境的交叉领域'
-    '（如环境模型、大气污染模拟、遥感反演、环境大数据分析、LCA生命周期评估等）。'
-    '你关注AI工具如何提升科研效率、环境数据处理新技术、以及交叉领域的学术机会。'
-)
-
-ACTION_PROMPT = """基于以下文章，为读者生成可落地的行动建议。
-
-【读者定位】
-{profile}
-
-【文章信息】
-标题：{title}
-来源：{source}
-主题：{topic}
-摘要：{summary}
-
-【正文节选】
-{content}
-
-【输出格式】
-### 相关度
-（高/中/低 + 一句话解释）
-
-### 行动建议
-- **立即可做**：1-2个今天就能执行的具体动作
-- **本周计划**：1个本周可以推进的中期动作
-- **长期关注**：1个值得持续跟踪的方向（相关度为低时省略）"""
-
-
-def generate_action_suggestion(title: str, source: str, topic: str,
-                                summary: str, content: str,
-                                api_key: str, profile: str = '',
-                                engine_type: str = 'deepseek',
-                                max_tokens: int = 1500) -> str:
-    if not profile:
-        profile = DEFAULT_USER_PROFILE
-    prompt = ACTION_PROMPT.format(
-        profile=profile, title=title, source=source, topic=topic,
-        summary=summary[:500], content=content[:3000],
-    )
-    engine = create_engine(engine_type, api_key)
-    return engine.chat(prompt, max_tokens=max_tokens)
-
-# ---------------------------------------------------------------- 知识卡片的公共件
-#
-# `chat_notes.py`（对话线）与 `article_notes.py`（文章线）产出的是**同一种卡片**：
-# 带 frontmatter + `## AI 摘要` + `[[概念]] — 说明` 的 markdown，都喂给 `compile_wiki`。
-# 所以这几样放在这里，一份实现两边用——两处各写一份，早晚有一处会漏。
-
-SEPARATOR = '—'   # 与 `compile_wiki` 认的破折号一致（那条描述要能被它读回描述）
-
-# 文件名里不许出现的字符（Windows 一套 + 控制字符）
-_ILLEGAL_IN_NAME = set('\\/:*?"<>|') | {chr(code) for code in range(0, 32)}
-
-
-def plain(text) -> str:
-    """自由文本里的 `[[…]]` 一律拆掉。
-
-    纪律是「wikilink 只由我们的代码渲染，不由模型写」：`compile_wiki.scan_articles` 收正文里
-    **所有** wikilink，它不会问这是谁写的——模型在摘要里随手一个 `[[X]]`，就会凭空长出一个概念。
-    """
-    out, index = [], 0
-    source = str(text or '')
-    while True:
-        start = source.find('[[', index)
-        if start < 0:
-            out.append(source[index:])
-            break
-        end = source.find(']]', start)
-        if end < 0:
-            out.append(source[index:])
-            break
-        out.append(source[index:start])
-        out.append(source[start + 2:end])
-        index = end + 2
-    return ''.join(out).replace('[[', '').replace(']]', '')
-
-
-def note_path(out_root, name: str, fallback: str = '未命名'):
-    """一张卡一个文件。名字要过文件名安全：会话/文章名里有 `/` 会写到别的目录去。"""
-    from pathlib import Path as _Path
-    cleaned = ''.join('_' if ch in _ILLEGAL_IN_NAME else ch for ch in str(name))
-    cleaned = ' '.join(cleaned.split())[:80].strip().strip('.')
-    return _Path(out_root) / ('%s.md' % (cleaned or fallback))
-
-
-# ---------------------------------------------------------------- 微信正文里的界面残留
-
-# 微信文章正文会带**阅读器自己的界面文字**（"在小说阅读器读本章"那一串），以及文末的
-# 原创标记与公众号名重复。实测：库里 1633 篇笔记，**1484 篇（91%）**的摘要里混着它
-# （先按"整份文件里出现某条短语"数是 330，那是数漏了——短语有好几种写法，按摘要层数才对）。
-# 这份清理在真库上跑过：1484 篇 → 清理后 **0 篇**仍带残留。
-#
-# `classify_daily.py` 里本来有一份 `AD_PATTERNS`，但它只用在日报那条路上，
-# **写笔记那条路（`create_reading_notes.py`）一次都没清洗**——而且对着真串比对，
-# 那份表还漏了一条：真串是「在**公众号**小说中沉浸阅读」，表里写的是
-# 「在小说阅读器**中**沉浸阅读」。所以这里一次列全，各处共用。
-_AD_PHRASES = (
-    '在小说阅读器读本章',
-    '在小说阅读器中沉浸阅读',
-    '在公众号小说中沉浸阅读',
-    '去阅读',
-    'Scan to Follow',
-    '轻触阅读原文',
-    '预览时标签不可点',
-    '继续滑动看下一个',
-)
-
-_UNDERSCORE_RUN = None      # 惰性编译，避免在 import 期做什么重活
-_JS_LINK = None
-
-
-def strip_wx_ads(text: str) -> str:
-    """去掉微信正文里那几样界面残留。
-
-    处理顺序有讲究：先删短语，再删下划线长串，最后收拾"原创 + 公众号名重复 N 遍"。
-    只动**已知的**几样——这是给摘要与提示词做清洁，不是改写正文；
-    拿不准的一律留着（宁可留一点噪音，也不要把用户的话删掉）。
-    """
-    import re as _re
-    global _UNDERSCORE_RUN
-    if _UNDERSCORE_RUN is None:
-        _UNDERSCORE_RUN = _re.compile(r'_{4,}')
-    out = str(text or '')
-    for phrase in _AD_PHRASES:
-        out = out.replace(phrase, ' ')
-    out = _UNDERSCORE_RUN.sub(' ', out)
-    global _JS_LINK
-    if _JS_LINK is None:
-        _JS_LINK = _re.compile(r'\[.*?\]\(javascript:void\(0\);?\)')
-    out = _JS_LINK.sub(' ', out)
-    # 「原创 开源星探 开源星探 开源星探」：公众号名在文末被重复粘了几遍，压成一个
-    out = _re.sub(r'原创\s+(\S{2,12})(?:\s+\1\b){1,}\s*', ' ', out)
-    out = _re.sub(r'原创\s+[一-龥A-Za-z0-9]{2,12}\s*$', '', out)
-    out = _re.sub(r'\b(\S{2,12})(?:\s+\1\b)+', r'\1', out)
-    out = _re.sub(r'[ \t]{2,}', ' ', out)
-    out = _re.sub(r'\n{3,}', '\n\n', out)
-    # 短语被删掉之后可能留下孤零零的空白或行首标点
-    out = _re.sub(r'[ \t]+([，。、；：！？])', r'\1', out)
-    return out.strip()
-
-
-_FENCED_BLOCK = None
-
-
-def strip_wx_ads_document(text: str) -> str:
-    """整篇原文用的清洗：**frontmatter 与围栏代码块一个字不动**，其余同 `strip_wx_ads`。
-
-    删短语的规则**完全复用** `strip_wx_ads`，不另写一套 —— 两处各写一份，迟早会对
-    "什么算残留"给出不同答案（本仓库因为这类分叉吃过亏）。
-
-    两处防护各有实测理由：
-
-    - **frontmatter**：`去阅读` 是**短词**，完全可能出现在标题里（"如何去阅读一本书"）。
-      标题被改就等于改文件名对齐关系 —— 笔记靠 `日期-标题` 找原文，改了就对不上了。
-      实测当前 35,060 篇里 0 篇的 frontmatter 含短语，所以这一条是**防未来**，不是修现在。
-    - **围栏代码块**：`strip_wx_ads` 末尾那几条空白规整（`[ \\t]{2,}` → ' '、`\\n{3,}` → `\\n\\n`）
-      对摘要是无损的，对**原文**却会吃掉代码缩进 —— 实测 20 篇带围栏、其中 10 篇围栏内容会变
-      （HTML/JS 示例）。原文是素材，缩进就是内容。
-    """
-    if text.startswith('---'):
-        end = text.find('\n---', 3)
-        front, body = (text[:end + 4], text[end + 4:]) if end != -1 else ('', text)
-    else:
-        front, body = '', text
-    # `strip_wx_ads` 末尾带 `.strip()`，会把正文首尾空白吃掉。frontmatter 与正文之间那两行
-    # 空行是正文的一部分，所以这里把首尾空白单独摘出来、洗完再放回去。
-    lead = body[:len(body) - len(body.lstrip())]
-    tail = body[len(body.rstrip()):]
-    core = body.strip()
-    global _FENCED_BLOCK
-    if _FENCED_BLOCK is None:
-        import re as _re
-        _FENCED_BLOCK = _re.compile(r'^```.*?^```', _re.S | _re.M)
-    # 占位符用 chr(0) 拼，不写字面反斜杠：本仓有"JSON 层吃掉转义"的前科，能避开就避开。
-    mark = chr(0) + 'FENCE' + chr(0)
-    blocks = []
-
-    def stash(match):
-        blocks.append(match.group(0))
-        return mark + str(len(blocks) - 1) + mark
-
-    cleaned = strip_wx_ads(_FENCED_BLOCK.sub(stash, core))
-    for index, block in enumerate(blocks):
-        cleaned = cleaned.replace(mark + str(index) + mark, block)
-    return front + lead + cleaned + tail
+"""
+weflow-cli 公共工具函数 — 供 biz_daily / classify_daily / chat_report 等共用。
+"""
+import os, json, re, base64, socket, urllib.request, hashlib
+from functools import wraps
+
+
+# ======================================================================
+# 工具库（静态知识，供报告「行动指南」自动匹配）
+# 按关键词 → GitHub 项目/工具，匹配越靠前优先级越高
+# ======================================================================
+
+TOOL_LIBRARY = [
+    # --- AI 编程 / Agent ---
+    {'keywords': ['cursor', 'agent', 'ide', '编程助手', '代码生成'],
+     'name': 'Cursor', 'url': 'https://github.com/getcursor/cursor',
+     'desc': 'AI 原生 IDE，支持多文件编辑与 Agent 模式'},
+    {'keywords': ['windsurf', 'agent', 'ide'],
+     'name': 'Windsurf', 'url': 'https://codeium.com/windsurf',
+     'desc': 'AI 原生 IDE，类 Cursor，支持任务级自动编程'},
+    {'keywords': ['continue', 'agent', 'ide', 'vscode'],
+     'name': 'Continue', 'url': 'https://github.com/continuedev/continue',
+     'desc': '开源 VS Code 插件，接入本地/云端大模型'},
+
+    # --- 大模型 / 推理 ---
+    {'keywords': ['deepseek', 'r1', '开源模型'],
+     'name': 'DeepSeek R1', 'url': 'https://github.com/deepseek-ai/DeepSeek-R1',
+     'desc': 'DeepSeek 开源推理模型，中文表现强'},
+    {'keywords': ['llama', 'meta', '开源模型'],
+     'name': 'Llama 3', 'url': 'https://github.com/meta-llama/llama3',
+     'desc': 'Meta 开源大模型，社区生态最成熟'},
+    {'keywords': ['ollama', '本地部署', '本地推理'],
+     'name': 'Ollama', 'url': 'https://github.com/ollama/ollama',
+     'desc': '一行命令运行本地大模型（macOS/Linux/Windows）'},
+    {'keywords': ['lmstudio', '本地部署', '本地推理'],
+     'name': 'LM Studio', 'url': 'https://lmstudio.ai',
+     'desc': '桌面端本地大模型运行器，有 GUI'},
+
+    # --- 信息聚合 / 日报 / RAG ---
+    {'keywords': ['rag', '检索增强', '知识库', '论文'],
+     'name': 'AnythingLLM', 'url': 'https://github.com/Mintplex-Labs/anything-llm',
+     'desc': '开箱即用的 RAG 知识库 + 聊天桌面应用'},
+    {'keywords': ['rss', '信息源', '订阅'],
+     'name': 'Fluent Reader', 'url': 'https://github.com/yang991178/fluent-reader',
+     'desc': '现代化 RSS 阅读器，聚合公众号/博客/新闻'},
+
+    # --- 环境科学 / 交叉方向 ---
+    {'keywords': ['遥感', '卫星', '反演', 'landsat', 'sentinel'],
+     'name': 'Google Earth Engine', 'url': 'https://earthengine.google.com',
+     'desc': '大规模遥感影像在线分析平台'},
+    {'keywords': ['遥感', '卫星', 'python'],
+     'name': 'xarray', 'url': 'https://github.com/pydata/xarray',
+     'desc': 'N 维数组处理，气象/遥感数据标配'},
+    {'keywords': ['大气', '排放清单', '排放'],
+     'name': 'MEIC', 'url': 'https://meicmodel.org',
+     'desc': '中国多尺度排放清单模型'},
+    {'keywords': ['lca', '生命周期', '生命周期评估'],
+     'name': 'brightway', 'url': 'https://github.com/brightway-lca/brightway2',
+     'desc': '开源生命周期评估（LCA）框架'},
+    {'keywords': ['数值模拟', '大气', '模型', '模拟'],
+     'name': 'WRF', 'url': 'https://github.com/wrf-model/WRF',
+     'desc': '中尺度数值天气预报模型'},
+
+    # --- 效率工具 ---
+    {'keywords': ['obsidian', '笔记', '知识管理'],
+     'name': 'Obsidian', 'url': 'https://obsidian.md',
+     'desc': '本地优先的 Markdown 笔记，双链/图谱'},
+    {'keywords': ['anki', '记忆', '复习'],
+     'name': 'Anki', 'url': 'https://apps.ankiweb.net',
+     'desc': '基于间隔重复的闪卡记忆工具'},
+
+    # --- 一般关键词兜底 ---
+    {'keywords': ['投资', '财报', '股价', '股票'],
+     'name': 'Tushare', 'url': 'https://tushare.pro',
+     'desc': '免费金融数据接口（Python）'},
+]
+
+
+def match_tools(articles: list[dict], top_n: int = 8) -> list[dict]:
+    """从文章的标题/摘要/标签中抽取关键词，匹配 TOOL_LIBRARY。"""
+    collected_text = ''
+    for a in articles:
+        tags = a.get('tags') or []
+        text_parts = [
+            a.get('title', ''),
+            a.get('summary', ''),
+            ' '.join(tags) if isinstance(tags, list) else str(tags),
+        ]
+        collected_text += ' ' + ' '.join(text_parts)
+    collected_text = collected_text.lower()
+
+    ranked = []
+    for tool in TOOL_LIBRARY:
+        score = sum(1 for kw in tool['keywords'] if kw.lower() in collected_text)
+        if score > 0:
+            ranked.append((score, tool))
+    ranked.sort(key=lambda x: x[0], reverse=True)
+    return [t for _, t in ranked[:top_n]]
+
+
+# ======================================================================
+# Config
+# ======================================================================
+
+CONFIG_PATH = os.path.join(os.path.expanduser('~'), '.weflow-cli', 'config.json')
+
+
+# ======================================================================
+# AI Engine 抽象
+# ======================================================================
+
+class AIEngine:
+    """OpenAI-compatible API 引擎基类。"""
+    def __init__(self, api_key: str, base_url: str, model: str, timeout=60):
+        self.api_key = api_key
+        self.base_url = base_url.rstrip('/')
+        self.model = model
+        self.timeout = timeout
+
+    def chat(self, prompt: str, max_tokens=2000) -> str:
+        payload = json.dumps({
+            'model': self.model,
+            'messages': [{'role': 'user', 'content': prompt}],
+            'max_tokens': max_tokens,
+            'temperature': 0.2,
+        }).encode('utf-8')
+        req = urllib.request.Request(
+            f'{self.base_url}/chat/completions',
+            data=payload,
+            headers={
+                'Content-Type': 'application/json',
+                'Authorization': f'Bearer {self.api_key}',
+            },
+            method='POST',
+        )
+        with urllib.request.urlopen(req, timeout=self.timeout) as resp:
+            data = json.loads(resp.read())
+        return data['choices'][0]['message']['content']
+
+
+class AnthropicEngine(AIEngine):
+    """Anthropic Messages API 引擎（/v1/messages）。"""
+    def __init__(self, api_key: str, base_url: str, model: str, timeout=120):
+        super().__init__(api_key, base_url, model, timeout=timeout)
+
+    def chat(self, prompt: str, max_tokens=2000) -> str:
+        payload = json.dumps({
+            'model': self.model,
+            'messages': [{'role': 'user', 'content': prompt}],
+            'max_tokens': max_tokens,
+        }).encode('utf-8')
+        req = urllib.request.Request(
+            f'{self.base_url}/messages',
+            data=payload,
+            headers={
+                'Content-Type': 'application/json',
+                'x-api-key': self.api_key,
+                'anthropic-version': '2023-06-01',
+                'Authorization': f'Bearer {self.api_key}',
+            },
+            method='POST',
+        )
+        with urllib.request.urlopen(req, timeout=self.timeout) as resp:
+            data = json.loads(resp.read())
+        return data['content'][0]['text']
+
+
+class DeepSeekEngine(AIEngine):
+    def __init__(self, api_key: str, model='deepseek-chat', timeout=180):
+        super().__init__(api_key, 'https://api.deepseek.com/v1', model, timeout=timeout)
+
+
+class ClaudeEngine(AIEngine):
+    def __init__(self, api_key: str, model='claude-sonnet-4-6', timeout=90):
+        super().__init__(api_key, 'https://api.anthropic.com/v1', model, timeout=timeout)
+
+
+class OllamaEngine(AIEngine):
+    def __init__(self, model='llama3', timeout=120):
+        super().__init__('ollama', 'http://localhost:11434/v1', model, timeout=timeout)
+
+
+# ======================================================================
+# 本地引擎自动检测
+# ======================================================================
+
+_LOCAL_ENDPOINTS = [
+    # (name, base_url, api_style)
+    ('ollama',    'http://localhost:11434',  'openai'),
+    ('lmstudio',  'http://localhost:1234', 'openai'),
+    ('claude',    'http://localhost:8080',  'anthropic'),
+    ('lmstudio',  'http://localhost:8000', 'openai'),
+    ('lmstudio',  'http://localhost:3000', 'openai'),
+]
+
+
+def _try_local_endpoint(name: str, base_url: str, api_style: str,
+                       timeout: int = 5) -> tuple[bool, str, str, str]:
+    health_path = f'{base_url}/v1/models'
+    try:
+        req = urllib.request.Request(health_path, headers={'Accept': 'application/json'})
+        with urllib.request.urlopen(req, timeout=timeout) as resp:
+            data = json.loads(resp.read())
+        models = data.get('data', data.get('models', []))
+        if not models:
+            return True, name, base_url, 'local'
+        first = models[0]
+        model_name = first.get('id', first.get('model', 'local'))
+        return True, name, base_url, model_name
+    except Exception as e:
+        return False, name, base_url, str(e)
+
+
+def detect_local_engine(timeout: int = 5) -> tuple[bool, AIEngine, str]:
+    """自动检测本地推理服务。返回 (detected, engine, description)。"""
+    checked = set()
+    for name, base_url, api_style in _LOCAL_ENDPOINTS:
+        key = (name, base_url)
+        if key in checked:
+            continue
+        checked.add(key)
+        ok, dname, durl, model = _try_local_endpoint(name, base_url, api_style, timeout)
+        if not ok:
+            continue
+        if api_style == 'anthropic':
+            engine = AnthropicEngine('local', durl, model, timeout=180)
+        else:
+            engine = OllamaEngine(model=model, timeout=180)
+            engine.base_url = durl.rstrip('/') + '/v1'
+        desc = f'{dname} ({model}@{durl})'
+        return True, engine, desc
+    return False, None, '无可用本地推理服务'
+
+
+def create_engine(engine_type: str, api_key: str = '') -> AIEngine:
+    """工厂函数：根据类型创建 AI 引擎。
+
+    引擎类型: local(自动检测) / deepseek / claude / ollama
+    配置 aiBaseUrl 时, deepseek 引擎走自定义 OpenAI 兼容端点 (中转站)。
+    """
+    t = engine_type.lower()
+    if t == 'local':
+        ok, engine, desc = detect_local_engine(timeout=8)
+        if not ok:
+            raise RuntimeError(
+                '未检测到本地推理服务。请启动以下任一服务后重试：\n'
+                '  • Ollama:     ollama serve          (11434)\n'
+                '  • LM Studio:  lmstudio server start (1234)\n'
+                '  • Claude Code 本地服务 (8080)\n'
+                '或使用 --engine deepseek/claude 指定云端引擎。'
+            )
+        return engine
+    elif t == 'deepseek':
+        base_url, model = _custom_endpoint()
+        if base_url:
+            return AIEngine(api_key, base_url, model)
+        return DeepSeekEngine(api_key)
+    elif t == 'claude':
+        return ClaudeEngine(api_key)
+    elif t == 'ollama':
+        return OllamaEngine()
+    raise ValueError(
+        f'未知引擎: {engine_type}，可选: local / deepseek / claude / ollama'
+    )
+
+
+def _custom_endpoint():
+    """读取 config.json 的 aiBaseUrl/aiModel; 未配置返回 (None, None)。"""
+    try:
+        with open(CONFIG_PATH, encoding='utf-8') as f:
+            cfg = json.load(f)
+        base_url = (cfg.get('aiBaseUrl') or '').strip().rstrip('/')
+        model = (cfg.get('aiModel') or '').strip() or 'deepseek-chat'
+        return (base_url or None), (model if base_url else None)
+    except Exception:
+        return None, None
+
+
+def call_deepseek(prompt: str, api_key: str, max_tokens=2000, timeout=60) -> str:
+    """向后兼容：调用 DeepSeek API。"""
+    return DeepSeekEngine(api_key, timeout=timeout).chat(prompt, max_tokens=max_tokens)
+
+
+def call_ai(prompt: str, engine_type: str = 'local', api_key: str = '', max_tokens=2000) -> str:
+    """通用 AI 调用：支持 local/deepseek/claude/ollama 引擎。"""
+    engine = create_engine(engine_type, api_key)
+    return engine.chat(prompt, max_tokens=max_tokens)
+
+
+# ======================================================================
+# 缓存机制 — 避免重跑 pipeline 时重复调用 API
+# ======================================================================
+
+_CACHE_DIR = os.path.join(os.path.dirname(os.path.dirname(os.path.abspath(__file__))),
+                          'output', '.cache')
+
+
+def _cache_key(*args, **kwargs) -> str:
+    """根据参数生成 MD5 缓存 key。"""
+    raw = json.dumps({'args': args, 'kwargs': kwargs}, sort_keys=True, ensure_ascii=False)
+    return hashlib.md5(raw.encode('utf-8')).hexdigest()
+
+
+def cached_call(func, *args, cache_subdir: str = '', **kwargs):
+    """带缓存的函数调用。命中缓存则直接返回，否则调用 func 并存储结果。
+
+    Args:
+        func: 要调用的函数（需返回可 JSON 序列化的结果）
+        cache_subdir: 缓存子目录名（如 'classify'、'wiki'）
+    """
+    cache_dir = os.path.join(_CACHE_DIR, cache_subdir) if cache_subdir else _CACHE_DIR
+    os.makedirs(cache_dir, exist_ok=True)
+    key = _cache_key(func.__name__, *args, **kwargs)
+    cache_file = os.path.join(cache_dir, f'{key}.json')
+
+    if os.path.exists(cache_file):
+        try:
+            with open(cache_file, 'r', encoding='utf-8') as f:
+                return json.load(f)
+        except (json.JSONDecodeError, OSError):
+            pass  # 缓存损坏，重新调用
+
+    result = func(*args, **kwargs)
+    try:
+        with open(cache_file, 'w', encoding='utf-8') as f:
+            json.dump(result, f, ensure_ascii=False)
+    except (TypeError, OSError):
+        pass  # 结果不可序列化或写入失败，跳过缓存
+
+    return result
+
+
+def clear_cache(cache_subdir: str = ''):
+    """清空指定子目录的缓存，或全部缓存。"""
+    target = os.path.join(_CACHE_DIR, cache_subdir) if cache_subdir else _CACHE_DIR
+    if not os.path.isdir(target):
+        return
+    for fname in os.listdir(target):
+        fpath = os.path.join(target, fname)
+        if os.path.isfile(fpath):
+            os.unlink(fpath)
+# ======================================================================
+# Config Decrypt
+# ======================================================================
+
+# ======================================================================
+# 主题分类法 —— **唯一一处定义**
+#
+# 列表与定义都收在这里，因为「散文写的枚举会漂」在这个仓库里已经真的发生过：
+# `biz_daily.TOPIC_PROMPT` 的第一行按 TOPICS 生成了六类，但同一段提示词后面两处
+# 提醒是硬编码的五类（少了政治），判断规则里也没有政治那一栏——而政治在语料里占 26%。
+# 两条路径（LLM 提示词 / 决策模型的判据）现在读同一张表，所以它们不可能再对不上。
+#
+# **顺序有意义**：`generate_ai_report` 按这个顺序给报告分栏。
+TOPICS = ['AI', '学术', '新闻', '文学', '投资', '政治']
+
+# 聊天卡拷进 Vault `Sources/Chat/` 时的文件名前缀。**必须共享**：`chat_notes` 用它写文件、
+# `compile_wiki` 用它把概念页的"来源"链接指过去——两处各写一份就是"同一条信息写两处"，
+# 而这个仓库已经因为这类分叉吃过亏。
+# 为什么要有这个前缀：聊天卡的名字**就是会话名**（`白马非马`、`老表亲戚群`），而概念页
+# 也可能叫同一个名字；两个文件同名时 `[[白马非马]]` 在 Obsidian 里是二义的。
+CHAT_CARD_PREFIX = '会话-'
+
+# 知识页住在哪几个目录（**Vault 相对路径**）。**分成两个是有意的**：用户明确要求
+# 聊天知识库与公众号文章知识库分开（2026-09-27），所以是"一条线一个目录"而不是混在一起。
+# 顺序即展示顺序：文章在前。
+#
+# 读的一方（`wiki_lint` / `vault_search` / `vault_rag` / 助手的 `search_knowledge`）
+# 都要把**两个都读**，否则新分出去的那一半会静默地搜不到——而这个仓库已经因为
+# "同一个事实写在两处"栽过好几次，所以 TS 那边有一份平行的列表，有测试钉住两者一致。
+#
+# 这一层是 2026-10-10 立的：用户要求两条线**各自一棵树**（不只是同根下的两个子目录），
+# 而"一串 Vault 相对路径"这个形状把"共用一个根"写死了 ⇒ 改值不够、得先改形状。
+# 现在两条线的根**仍然相同**（物理迁移还没做），所以下面这层只是把形状立起来；
+# 迁移时只改 `root` 的值，不再动形状。**唯一源头**：`CONCEPT_DIRS` 由它派生，
+# 图谱那两处曾经的硬编码也改读它。
+KNOWLEDGE_LINES = (
+    # (线 id, 根, 线内的概念目录)
+    ('wiki', 'output/wechat-vault', 'Wiki/Concepts'),
+    ('chat', 'output/wechat-vault', 'Chat/Concepts'),
+)
+
+
+def concept_dirs():
+    """所有线的概念目录（Vault 相对路径），顺序即展示顺序：文章在前。"""
+    return tuple(concepts for _line, _root, concepts in KNOWLEDGE_LINES)
+
+
+CONCEPT_DIRS = concept_dirs()
+
+
+def line_for_concept_dir(path):
+    """给一个概念目录（任意写法）→ 线 id；认不出就返回 None（**不猜**）。
+
+    认不出是正常情形（`wiki compile --output` 可以指到库外的任意目录），
+    调用方要按"没有线"处理，而不是当成某条线。
+    """
+    try:
+        target = os.path.normcase(os.path.abspath(str(path)))
+    except Exception:
+        return None
+    for line_id, root, concepts in KNOWLEDGE_LINES:
+        if target == os.path.normcase(os.path.abspath(os.path.join(root, concepts))):
+            return line_id
+    return None
+
+
+# 线的展示名。**只此一份**：图谱的提示、体检的报告、助手的输出都取它，各写一句
+# "文章线/聊天线"的后果是改词那天只改到一半，而没有任何东西会红。
+LINE_LABELS = {'wiki': '文章线', 'chat': '聊天线'}
+
+# 主键的分隔符。选 `:` 是因为**概念页的文件名里不可能有它**（Windows 禁止，
+# `compile_wiki` 也会把它换成 `_`）—— 主键要能被原样切回 (线, 名字)，
+# 这个判据就必须没有二义。改成 `-` 或 `_` 都会把 `AI-Agent` 这类名字切错，
+# 而症状是"图谱里两个节点凭一个错名字连上了"，不报错。
+LINE_SEP = ':'
+
+
+def line_for_relative_concepts(relative):
+    """给一个**库内相对**概念目录（`Wiki/Concepts`）→ 线 id；认不出返回 None（**不猜**）。
+
+    与 `line_for_concept_dir` 的分工：那个比的是**绝对路径**（适合已经知道库根的调用方）；
+    这个只比对清单里那串相对路径 —— 测试里的临时库、或 `--vault` 指到别处时库根对不上，
+    但"`Chat/Concepts` 属于聊天线"这一层仍然成立。
+    """
+    def norm(p):
+        return os.path.normcase(str(p).replace('/', os.sep).replace('\\', os.sep))
+    for line_id, _root, concepts in KNOWLEDGE_LINES:
+        if norm(concepts) == norm(relative):
+            return line_id
+    return None
+
+
+def line_concepts_path(line_id):
+    """线 id → 它的概念目录（**库内相对路径**，`Wiki/Concepts`）；认不出返回 None。"""
+    for lid, _root, concepts in KNOWLEDGE_LINES:
+        if lid == line_id:
+            return concepts
+    return None
+
+
+def concept_link_target(line_id, name, other_line_names=()):
+    """渲染一个概念链接该写成什么目标。
+
+    **只在"另一条线也有这个名字"时才带路径**（`Chat/Concepts/DeepSeek|DeepSeek`）：
+    两条线同名时裸 `[[DeepSeek]]` 在 Obsidian 里是二义的（官方判据：会 deterministic
+    解析，但不保证命中你想要的那张），所以给目标带上路径、用 `|` 保住显示文本。
+    只属于一条线的名字**一个字节都不动** —— 否则 4.9 万张页里绝大多数链接都要白重写
+    一遍，而那样改出来的 diff 没人看得完。
+    """
+    if name in other_line_names:
+        concepts = line_concepts_path(line_id)
+        if concepts:
+            return '%s/%s|%s' % (concepts, name, name)
+    return name
+
+
+def link_target_name(raw):
+    """`[[…]]` 里抓到的那一串 → 概念名。**解析只此一份。**
+
+    `[[Chat/Concepts/DeepSeek|DeepSeek]]` → `DeepSeek`。各处自己写 `split('|')` 的话，
+    漏掉一处那处的边就整条丢掉，而图里少一条边不报错。
+
+    **改动面越小越好**：只切掉 `|显示文本`，并且**只对带线路径的那些**再去掉前缀。
+    其余一律原样返回 —— 这个函数的上游既有"概念名"也有"卡片名"，随手多切一刀就会
+    改掉既有行为：
+
+    - 别切 `#`：这个库里的概念名**真的带 `#`**（`#GPT6`、`Erdős#1026`）。切了它们会被
+      当成别的名字，指向它们的边整条消失（2026-10-10 实测少了 4 条边，而图里少边不报错）。
+    - 别切 `.md`：`## 来源` 的卡片链接就写成 `[[名字.md]]`，`wiki_lint.resolve` 靠这个
+      后缀把它分流到卡片目录。切了它，那一支就再也不走了。
+    """
+    name = str(raw or '').strip()
+    if '|' in name:
+        name = name.split('|', 1)[0].strip()      # `[[目标|显示文本]]` → 目标
+    norm = name.replace('\\', '/')
+    for _lid, _root, concepts in KNOWLEDGE_LINES:
+        prefix = concepts + '/'
+        if norm.startswith(prefix):
+            norm = norm[len(prefix):]
+            if norm.lower().endswith('.md'):      # 带路径的写法里才去后缀（我们自己写的那种）
+                norm = norm[:-3]
+            break
+    return norm.strip()
+
+
+def is_line_qualified(raw):
+    """这条链接是不是**带了线的路径前缀**（`Wiki/Concepts/…` / `Chat/Concepts/…`）。
+
+    体检用它区分"已经消歧过的链接"和"还是裸的二义链接"。
+    """
+    name = str(raw or '').strip()
+    if '|' in name:
+        name = name.split('|', 1)[0].strip()
+    norm = name.replace('\\', '/')
+    for _lid, _root, concepts in KNOWLEDGE_LINES:
+        if norm == concepts or norm.startswith(concepts + '/'):
+            return True
+    return False
+
+
+def sibling_concepts_dir(concept_dir):
+    """同一个库里**另一条线**的概念目录；认不出线、或它不存在 → None。
+
+    **两级**：两条线都是 `<库>/<线>/Concepts`，库根是 `concept_dir.parent.parent`。
+    写成一级的话候选恒不存在（`<库>/Chat/Wiki/Concepts`）—— 于是"另一条线没有这个名字"
+    永远成立，链接不会带路径，而 Obsidian 里那条裸链接就**悄悄**变成二义的。
+    2026-09-27 那段同样的两级路径就是这么栽过一次（写在已删掉的那个函数的注释里）。
+
+    认线用**路径尾两段**而不是绝对路径（`line_for_relative_concepts`）：测试里的临时库、
+    或者用户把库根换了地方，尾两段仍然是 `Chat/Concepts` ⇒ 认得出；用绝对路径的话
+    只有仓库里那两个真实根才认得出，别的地方会安静地退化成"没有另一条线"。
+    """
+    norm = str(concept_dir).replace('\\', '/').rstrip('/')
+    parts = [p for p in norm.split('/') if p]
+    if len(parts) < 2:
+        return None
+    my_line = line_for_relative_concepts('/'.join(parts[-2:]))
+    if not my_line:
+        return None                       # 库外的目录：那里没有"另一条线"
+    root = os.path.dirname(os.path.dirname(norm))
+    for line_id, _r, concepts in KNOWLEDGE_LINES:
+        if line_id == my_line:
+            continue
+        candidate = os.path.join(root, *concepts.split('/'))
+        if os.path.isdir(candidate):
+            return candidate
+    return None
+
+
+def concept_names(concept_dir):
+    """那个目录里的概念名（文件名去掉 `.md`）。读不出来就返回空集（不猜）。"""
+    try:
+        return {f[:-3] for f in os.listdir(str(concept_dir)) if f.endswith('.md')}
+    except OSError:
+        return set()
+
+
+class LinkNamer:
+    """把概念名渲染成链接目标 —— **跨线同名时才带路径**，其余原样。
+
+    为什么要一个对象而不是每处写一句：**渲染点有三处**（模型建页、零模型建页、索引表），
+    各写一份的话漏一处就会在库里留下一批裸的二义链接，而它只在有人跑 `wiki lint` 时
+    才看得见。判断"要不要带路径"只需要另一条线的**文件名集合**，所以构造一次就够。
+    """
+
+    def __init__(self, line_id, other_names=()):
+        self.line_id = line_id or ''
+        self.other_names = set(other_names)
+
+    @classmethod
+    def for_out_dir(cls, out_dir):
+        """按输出目录定线，并顺手把另一条线的名字读出来（一次 listdir）。
+
+        认线用**路径尾两段**（`Chat/Concepts`），所以测试里的临时库、或库根换了地方都认得出。
+        认不出线（`--output` 指到库外的任意目录）时 **`line_id` 为空 → 一律渲染成裸名字**：
+        那是"库外目录"的既有行为，而不是按猜出来的线写一堆带路径的链接。
+        """
+        parts = [p for p in str(out_dir).replace('\\', '/').rstrip('/').split('/') if p]
+        line_id = line_for_relative_concepts('/'.join(parts[-2:])) if len(parts) >= 2 else None
+        if not line_id:
+            return cls('', ())
+        sibling = sibling_concepts_dir(out_dir)
+        return cls(line_id, concept_names(sibling) if sibling else ())
+
+    def __call__(self, name):
+        if not self.line_id:
+            return name
+        return concept_link_target(self.line_id, name, self.other_names)
+
+
+def concept_key(line_id, name):
+    """线 id + 概念名 → 跨线唯一的主键。
+
+    **为什么需要**：两条线各有一张同名页是设计使然（用户 2026-10-10 要求两个概念
+    命名空间分开），而图谱的主键原来就是文件 stem ⇒ 两棵目录里的 `DeepSeek` 是
+    **同一个键**。2026-10-10 实测：合并图里 49,956 个节点里有 36 组撞键，前端
+    `new Map(NODES.map(n => [n.id, n]))` 会静默只留一个 —— 节点数看着对，少掉的那个
+    却点不到。同名的两页靠这个键分开。
+    """
+    return '%s%s%s' % (line_id, LINE_SEP, name)
+
+
+def split_concept_key(key):
+    """主键 → (线 id, 名字)；**认不出线就返回 `(None, 原样)`，不猜**。
+
+    兼容没有线前缀的旧主键（认不出线的情形），调用方按"没有线"处理。
+    """
+    line_id, sep, name = str(key).partition(LINE_SEP)
+    if not sep or line_id not in LINE_LABELS:
+        return None, str(key)
+    return line_id, name
+
+
+def line_label(line_id):
+    """线 id → 展示名；认不出返回 None（调用方自己决定"无线"怎么写）。"""
+    return LINE_LABELS.get(line_id)
+
+# 一篇文章**没能被分类**时落到哪一类。
+#
+# 收成一处是因为它曾经在写入路径上有两个不同的答案、相隔七行：
+# `.articles.json` 那条路默认 `''`（空主题），而分组/落 md 那条路默认 `'学术'`。
+# 于是一篇文章在 md 里写 `topic: 学术`、在 json 里写 `topic: ""`——
+# **同一次运行、同一篇文章，两个产物给出不同的主题**，而且都不报错。
+#
+# 真实后果（2026-09-04 的产出，178 篇）：md 全落在 `学术/` 目录、frontmatter 写
+# `topic: 学术`（其中两篇是「OpenAI 深夜发布 GPT-6」「专为高管准备的 AI 助手」，
+# 明显不该是学术），而 json 里同一批全是 `""` —— 报告那条路读 json，
+# 判据 `topic != FOCUS_TOPIC and relevance != '高'` 就把它们整批静默排除了。
+#
+# 什么情况下会走到这里：`daily --no-ai`、或者没配 API key 时，Phase 2（分类）整段
+# 不跑，文章 dict 里**根本没有 `topic` 键**，而 Phase 3 照常写文件。
+#
+# 这个值是**兜底不是判断**：落到这里的文章其实是"未分类"。之所以不新造一个
+# `未分类` 类别，是因为它要额外维护一个目录、一处 HTML 分栏、以及下游对
+# 主题字面量的比较；改用 `未分类` 属于改既有契约，得单独决策。
+DEFAULT_TOPIC = '学术'
+
+# 每一类的判据。既生成提示词里的判断规则，也直接作为 Jev 的 choice criteria。
+TOPIC_CRITERIA = {
+    'AI': 'AI大模型/Agent/编程/开源/科技产品/工具教程',
+    '投资': '股票基金/融资/经济分析/商业市场',
+    '新闻': '时事政策/社会热点/娱乐/招聘促销/会议通知',
+    '文学': '散文小说/美食旅游/生活随笔/历史文化',
+    '学术': '科研论文/期刊文章/实验室成果/学术会议/高校研究',
+    '政治': '党政理论/政策解读/领导人讲话/官方评论',
+}
+
+# 相关度的三个档位。与 `TOPICS` 一样是**下游按字面量比较**的封闭词表：
+# `generate_ai_report.py`、`enrich_backlinks.py`、`generate_html.py` 都在比
+# `'高'`/`'中'`/`'低'` 这三个字。定义收在这里，`jev_client` 与 `biz_daily`
+# 都从这里取——原先 `jev_client` 一份、`biz_daily` 的成员校验里再写一份。
+#
+# **顺序即语义**：`jev_client.RELEVANCE_LEVELS` 是给模型看的判据文本，按下标与
+# 这个列表一一对应（有测试钉住），所以不要重排。
+RELEVANCE_NAMES = ['低', '中', '高']
+
+# 一篇文章**没能被判相关度**时落到哪一档。和 `DEFAULT_TOPIC` 是同一类东西：
+# 兜底不是判断。之所以要具名，是因为"全库 2199/2201 篇都是「中」"这件事的答案
+# 就在这里——分类失败的每条路径最终都落到这个值，而 `'中'` 读起来是
+# 「有启发性」（正面评价），不是「没判断」。值不变更（改档位会动到下游的
+# 收录判据），只是把它写在一处，好让它可被搜索、可被讨论。
+DEFAULT_RELEVANCE = '中'
+
+
+def load_config():
+    with open(CONFIG_PATH, 'r', encoding='utf-8') as f:
+        return json.load(f)
+
+
+# ---- 「不说话地失败」的最小护栏 ---------------------------------------------
+# 这个文件里有一批函数**故意不抛**（跨机器拷配置时，解不开的密文该表现为"没配"，
+# 而不是让整条命令崩）。但"不抛"不等于"不说"：`except: return ''` 会让调用方
+# 与用户都以为"本来就没有"，而真实原因是**解密失败/配置坏了**。
+# 所以这里只做一件事：同一条原因**说一次**，然后照旧返回空值。
+# 只说一次是必须的——这些函数每次请求/每次重排都会被调用，刷屏等于没警告。
+_WARNED_ONCE = set()
+
+
+def warn_once(tag, message):
+    """同一条原因只往 stderr 说一次（tag 相同即视为同一条）。"""
+    if tag in _WARNED_ONCE:
+        return
+    _WARNED_ONCE.add(tag)
+    import sys as _sys
+    print('[WARN] ' + message, file=_sys.stderr)
+    _sys.stderr.flush()
+
+
+def reset_warn_once():
+    """测试用：清空去重表。"""
+    _WARNED_ONCE.clear()
+
+
+# 配置里"不想在日报里看到的主题"的键名。值形如 `新闻,投资,学术`。
+EXCLUDED_TOPICS_KEY = 'dailyExcludeTopics'
+
+
+def excluded_topics(config=None, explicit='', protected=()):
+    """用户不想在日报里看到的主题集合。`explicit`（命令行）覆盖配置。
+
+    **这是展示层的开关，不是抓取层的**：正文照常抓取、照常归档，只是不出现在
+    日报里。理由是实测：拉之前只有来源+标题+摘要，按它判类型**不可靠**（与来源级
+    比对一致率仅 60%、误伤 48/217），而**排除是不可逆的**——没抓取就没归档。
+    放在展示层还换来一件事：改主意不用重抓，改个配置重新生成报告即可。
+
+    写错的主题名会被忽略并**打一行 WARN**（静默忽略会让人以为过滤生效了）。
+
+    `protected` 是不许被排除的主题（呼叫方传自己的「焦点主题」）。它比「未知主题名」
+    更值得拦一下：把焦点主题排掉，报告要么没有主体、要么直接报「未找到文章」
+    **指错方向**（那句话说去跑 biz_daily，可文章其实在）。同样 WARN 后忽略。
+    """
+    raw = explicit or (config or {}).get(EXCLUDED_TOPICS_KEY, '') or ''
+    names = [t.strip() for t in str(raw).replace('，', ',').split(',') if t.strip()]
+    out = set()
+    for name in names:
+        if name in TOPICS:
+            if name in protected:
+                print('[WARN] %s 里的「%s」是这份报告的主体，不能排除，已忽略'
+                      % (EXCLUDED_TOPICS_KEY, name))
+                continue
+            out.add(name)
+        else:
+            print('[WARN] %s 里的「%s」不是已知主题，已忽略（可选：%s）'
+                  % (EXCLUDED_TOPICS_KEY, name, '/'.join(TOPICS)))
+    return out
+
+
+# === 来源级先验："哪个号稳定发哪一类"从真实判断里长出来 ===
+#
+# 为什么不写死一张表：拉取之前只有来源+标题+摘要，按它判类型实测只有 60% 一致率、
+# 误伤 48/217（见 excluded_topics 的说明）。但**抓回来之后**每次都有 Jev 按正文判的
+# 主题，日积月累就看得出某个号一贯发什么。这张表因此是长出来的，不是我编的。
+#
+# 它现在只用来**报数**，不用来跳过任何东西：跳过是不可逆的。
+SOURCE_TOPICS_FILE = 'source_topics.json'
+SOURCE_PRIOR_MIN_SAMPLES = 8   # 少于这么多篇不下结论
+SOURCE_PRIOR_SHARE = 0.8       # 某一类占比到这个数才算"稳定地只发这一路"
+
+
+def source_topics_path(path=None):
+    """先验表的落盘位置。默认与 config.json 同目录（家目录）。"""
+    return path or os.path.join(os.path.dirname(CONFIG_PATH), SOURCE_TOPICS_FILE)
+
+
+def load_source_topics(path=None):
+    """读先验表：`{来源: {主题: 次数}}`。
+
+    读不出、坏掉、不是字典——一律返回 `{}`。这是**辅助**数据，坏了不该让日报挂掉。
+    """
+    try:
+        with open(source_topics_path(path), encoding='utf-8') as f:
+            data = json.load(f)
+    except (OSError, ValueError):
+        return {}
+    if not isinstance(data, dict):
+        return {}
+    out = {}
+    for source, counts in data.items():
+        if isinstance(source, str) and source.strip() and isinstance(counts, dict):
+            out[source] = counts
+    return out
+
+
+def record_source_topics(pairs, path=None):
+    """把这一批 `(来源, 主题)` 累加进先验表，返回摘要 dict。
+
+    **只增不减**（与 frontmatter 的 only-increase 同一个纪律）：累计次数是你事后判断
+    "这个号到底稳不稳"的唯一依据，抹掉就回不来了。
+    来源为空、主题不在 TOPICS 里的都不计——计了会污染分母，让占比算错。
+    """
+    import tempfile as _tmp   # 模块顶没导入它：本文件里它是函数内导入的
+    store = load_source_topics(path)
+    added = skipped = 0
+    for source, topic in pairs:
+        source = (source or '').strip()
+        topic = (topic or '').strip()
+        if not source or topic not in TOPICS:
+            skipped += 1
+            continue
+        bucket = store.setdefault(source, {})
+        try:
+            bucket[topic] = int(bucket.get(topic, 0)) + 1
+        except (TypeError, ValueError):
+            bucket[topic] = 1      # 值被改坏了，从 1 重新数，别让它把整个文件废掉
+        added += 1
+    target = source_topics_path(path)
+    try:
+        os.makedirs(os.path.dirname(target) or '.', exist_ok=True)
+        fd, tmp_path = _tmp.mkstemp(suffix='.json', dir=os.path.dirname(target) or '.')
+        try:
+            with os.fdopen(fd, 'w', encoding='utf-8') as f:
+                json.dump(store, f, ensure_ascii=False, indent=1, sort_keys=True)
+            os.replace(tmp_path, target)
+        except Exception:
+            if os.path.exists(tmp_path):
+                os.unlink(tmp_path)
+            raise
+    except OSError as exc:
+        # 写不进去（权限、磁盘）不能让日报失败——它只是记个账。
+        return {'sources': len(store), 'added': added, 'skipped': skipped,
+                'error': str(exc)}
+    return {'sources': len(store), 'added': added, 'skipped': skipped, 'error': ''}
+
+
+def stable_source_topic(counts, min_samples=SOURCE_PRIOR_MIN_SAMPLES,
+                        share=SOURCE_PRIOR_SHARE):
+    """某个来源是不是已经**稳定地只发某一类**。
+
+    返回 `(主题, 占比, 样本数)`；还判不了返回 `None`。
+    **`None` 是"还不知道"，不是"没有主题"**——调用方必须把这两种情况分开，
+    别把 `None` 当成某个默认主题用（那正好是"来源判不准"最坏的那种错）。
+    """
+    clean = {}
+    for topic, count in (counts or {}).items():
+        try:
+            value = int(count)
+        except (TypeError, ValueError):
+            continue
+        if value > 0:
+            clean[topic] = value
+    total = sum(clean.values())
+    if total < min_samples:
+        return None
+    topic, top = max(clean.items(), key=lambda kv: kv[1])
+    ratio = top / total
+    if ratio < share:
+        return None
+    return (topic, ratio, total)
+
+
+def source_prior_candidates(store, exclude, **kwargs):
+    """先验里"已经稳到能判"且落在排除集里的来源，按样本数从多到少。
+
+    只报出来给人看，**不据此跳过任何东西**：跳过是不可逆的，而这张表还在长。"""
+    rows = []
+    for source, counts in (store or {}).items():
+        stable = stable_source_topic(counts, **kwargs)
+        if stable and stable[0] in (exclude or ()):
+            rows.append((source, stable[0], stable[1], stable[2]))
+    return sorted(rows, key=lambda row: (-row[3], row[0]))
+
+def decrypt_lock(locked_str: str) -> str:
+    if not locked_str or not locked_str.startswith('lock:'):
+        return locked_str
+    from cryptography.hazmat.primitives.ciphers.aead import AESGCM
+    from cryptography.hazmat.primitives import hashes
+    from cryptography.hazmat.primitives.kdf.pbkdf2 import PBKDF2HMAC
+    from cryptography.hazmat.backends import default_backend
+
+    raw = base64.b64decode(locked_str[5:])
+    salt, iv, auth_tag, ciphertext = raw[:16], raw[16:28], raw[28:44], raw[44:]
+    machine_id = f'{socket.gethostname()}-{os.environ.get("USERNAME", "")}-weflow-cli'
+    kdf = PBKDF2HMAC(algorithm=hashes.SHA256(), length=32, salt=salt, iterations=100000,
+                     backend=default_backend())
+    key = kdf.derive(machine_id.encode('utf-8'))
+    aesgcm = AESGCM(key)
+    return aesgcm.decrypt(iv, ciphertext + auth_tag, None).decode()
+
+
+def get_db_config(config=None):
+    if config is None:
+        config = load_config()
+    return {
+        'nt_db': config.get('ntDbPath', ''),
+        'nt_key': decrypt_lock(config.get('ntKey', '')),
+        'nt_salt': config.get('ntSalt', ''),
+        'contact_db': config.get('contactDbPath', ''),
+        'contact_key': decrypt_lock(config.get('contactKey', '')),
+        'contact_salt': config.get('contactSalt', ''),
+    }
+
+
+def biz_message_db(config=None):
+    """订阅号（公众号）消息库 `biz_message_0.db` 的路径与钥匙，返回 `(db, key_hex, salt_hex)`。
+
+    **微信 4.x：钥匙由全库 passphrase 派生**（PBKDF2-HMAC-SHA512，256000 轮，32 字节），
+    盐取**库文件头 16 字节**。`favPassphrase` 优先，退而用 `decryptKey`；
+    更早的 `bizKey`/`bizSalt`（配了就直用）只作兼容保留——那两个键在本机早就不存在了。
+
+    抽成一个函数，是因为这把钥匙原来有**三份实现**：`biz_daily` 那份是 passphrase 派生（可用），
+    `chat_stats` 与 `mcp_bridge` 那两份只认 `bizKey`（在本机必然报『缺少密钥』，而照它们的提示去
+    `config set bizKey` 还会撞上『该键不在 CLI 可写白名单里』——越修越远）。
+    """
+    import hashlib
+    if config is None:
+        config = load_config()
+    nt_db = str(config.get('ntDbPath', ''))
+    msg_dir = os.path.dirname(nt_db.replace('\\', '/'))
+    db = os.path.join(msg_dir, 'biz_message_0.db')
+    key_enc = config.get('bizKey', '')
+    salt = config.get('bizSalt', '')
+    if key_enc and salt:
+        return db, decrypt_lock(key_enc), salt
+    pass_enc = config.get('favPassphrase', '') or config.get('decryptKey', '')
+    if not pass_enc or not os.path.exists(db):
+        raise RuntimeError(
+            '缺少订阅号数据库密钥: 请运行 weflow-cli fav set-key --passphrase <64位hex> '
+            '配置全库 passphrase (自动派生各库密钥)')
+    with open(db, 'rb') as fh:
+        salt = fh.read(16).hex()
+    key = hashlib.pbkdf2_hmac('sha512', bytes.fromhex(decrypt_lock(pass_enc)),
+                              bytes.fromhex(salt), 256000, dklen=32).hex()
+    return db, key, salt
+
+def get_api_key(config=None) -> str:
+    """读取 AI API key (自动解密 lock: 前缀)。"""
+    if config is None:
+        config = load_config()
+    return decrypt_lock(config.get('deepseekApiKey', ''))
+
+
+def get_dashscope_key(config=None) -> str:
+    """读取阿里云百炼（DashScope）的 embedding key，自动解密 lock: 前缀。
+
+    和 `get_api_key` / `get_typesafe_key` 同一形状：**不要直接 config.get**——
+    这个键进了 `ENCRYPTED_KEYS`，磁盘上是密文。解密失败回空串而不是抛，
+    理由同 get_typesafe_key（跨机器拷配置时它该表现为"没配"，不是崩）。
+    """
+    if config is None:
+        try:
+            config = load_config()
+        except Exception as exc:
+            warn_once('load_config', '读不到配置文件 %s（%s: %s）—— 本次当作空配置，需要配置的功能会退化成默认行为'
+                      % (CONFIG_PATH, type(exc).__name__, exc))
+            return ''
+    try:
+        return decrypt_lock(config.get('dashscopeApiKey', ''))
+    except Exception as exc:
+        warn_once('dashscopeApiKey', '配置项 dashscopeApiKey 解不开（%s: %s）—— 当作"没配"，语义检索会退成关键词'
+                  % (type(exc).__name__, exc))
+        return ''
+
+
+def get_typesafe_key(config=None) -> str:
+    """读取 TypeSafe (Jev) 决策模型的 key，自动解密 lock: 前缀。
+
+    解密失败**回空串而不是抛**：TS 侧 lockDecrypt() 失败就是静默回 ''，而
+    decrypt_lock() 是抛的。两份 config.json 一跨机器拷贝，同一份密文在
+    TS 侧表现为"没配 key"、在这里表现为崩——那会让日报整个挂掉，而它本该
+    只是退回到 LLM 解析路径。
+    """
+    if config is None:
+        try:
+            config = load_config()
+        except Exception as exc:
+            warn_once('load_config', '读不到配置文件 %s（%s: %s）—— 本次当作空配置，需要配置的功能会退化成默认行为'
+                      % (CONFIG_PATH, type(exc).__name__, exc))
+            return ''
+    try:
+        return decrypt_lock(config.get('typesafeApiKey', ''))
+    except Exception as exc:
+        warn_once('typesafeApiKey', '配置项 typesafeApiKey 解不开（%s: %s）—— 当作"没配"，决策模型退回 LLM 解析'
+                  % (type(exc).__name__, exc))
+        return ''
+
+
+def get_openrouter_key(config=None) -> str:
+    """读取 OpenRouter 的 key（决策模型的第二条通路，D-120），自动解密 lock: 前缀。
+
+    与 `get_typesafe_key` 逐字同一条规矩：**跨机器拷配置时表现为"没配"，不是崩**。
+    解密失败回空串之后，`create_client()` 会返回 None，调用方按老路退回 ——
+    这是"这条路没配好"的**安全**失效方向。
+    """
+    if config is None:
+        try:
+            config = load_config()
+        except Exception as exc:
+            warn_once('load_config', '读不到配置文件 %s（%s: %s）—— 本次当作空配置，需要配置的功能会退化成默认行为'
+                      % (CONFIG_PATH, type(exc).__name__, exc))
+            return ''
+    try:
+        return decrypt_lock(config.get('openrouterApiKey', ''))
+    except Exception as exc:
+        warn_once('openrouterApiKey', '配置项 openrouterApiKey 解不开（%s: %s）—— 当作"没配"，OpenRouter 那条路会停用'
+                  % (type(exc).__name__, exc))
+        return ''
+
+
+def get_judge_provider(config=None) -> str:
+    """决策模型走哪条通路：`native`（默认）、`chat`、`openrouter` 或 `local`（本机决策模型）。
+
+    **默认必须是 native**：这个开关存在的意义是"本机原生被地区封锁时换条路"，
+    而不是替所有用户改行为。取值不认识时也回 native —— 打错的配置项不该把判断整层关掉。
+    """
+    if config is None:
+        try:
+            config = load_config()
+        except Exception:
+            return 'native'
+    value = str((config or {}).get('judgeProvider') or '').strip().lower()
+    return value if value in ('native', 'chat', 'openrouter', 'local') else 'native'
+
+
+# 本地决策模型服务的默认地址：`python decide.py serve --port 8090` 起的那个（D-127）。
+DEFAULT_JUDGE_LOCAL_URL = 'http://127.0.0.1:8090'
+
+
+def get_judge_local_url(config=None) -> str:
+    """`judgeProvider=local` 时往哪发：配置项 `judgeLocalUrl`，没配就用默认地址。
+
+    与 `get_chat_endpoint` 同一态度：配置读不出来就当没配，返回默认值而不是抛 ——
+    这里抛会让"本机能跑但配置少一个键"变成整条判断链不可用。
+    """
+    if config is None:
+        try:
+            config = load_config()
+        except Exception:
+            return DEFAULT_JUDGE_LOCAL_URL
+    value = str((config or {}).get('judgeLocalUrl') or '').strip()
+    return value.rstrip('/') or DEFAULT_JUDGE_LOCAL_URL
+
+
+def get_chat_endpoint(config=None):
+    """`judgeProvider=chat` 时该往哪个 (base_url, model) 发 —— 与"中转站"同一条口径。
+
+    故意只做一件事：**委托 `_custom_endpoint()`**。那个函数是 `aiBaseUrl`/`aiModel` 的权威读法
+    （base 与 model 成对出现），判断器另写一份就会在"只配了 base 没配 model"这类组合上分叉，
+    而分叉的表现是"发去了错的端点"——不报错、只是判断质量变了。没配 `aiBaseUrl` 时返回 (None, None)。
+    """
+    try:
+        return _custom_endpoint()
+    except Exception:
+        return None, None
+
+
+def get_ai_engine(config=None) -> str:
+    """配置里选的对话引擎：`local` / `deepseek`（默认）/ `claude` / `ollama`。
+
+    **决策模型的 `chat` 通路必须读它**：`judgeProvider=chat` 的语义是"用**配置里的**对话模型"，
+    而"配置里的"到底指谁只有 `aiEngine` 说得清。2026-10-18 之前那条路无条件用 `deepseekApiKey`，
+    于是 `aiEngine=local` 的用户一开 `judgeProvider=chat` 就会把文章正文发去 DeepSeek ——
+    这不是"多花点钱"，是**用户明确选了不出境之后又被送出境**。
+    """
+    if config is None:
+        try:
+            config = load_config()
+        except Exception as exc:
+            warn_once('load_config', '读不到配置文件 %s（%s: %s）—— 本次当作空配置，需要配置的功能会退化成默认行为'
+                      % (CONFIG_PATH, type(exc).__name__, exc))
+            return 'deepseek'
+    return str((config or {}).get('aiEngine') or 'deepseek').strip().lower()
+
+
+def get_openrouter_model(config=None) -> str:
+    """OpenRouter 上用的模型 id（默认 `typesafe/jev-router`，即 TypeSafe 发布的决策模型）。
+
+    ⚠️ **地区限制是逐模型的**（实测 2026-10-17）：`typesafe/jev-router` 与 `:free` 模型能通，
+    付费通用模型（`openai/gpt-4o-mini`）在本地区返回 403。换模型必须重测，见 D-120。
+    """
+    if config is None:
+        try:
+            config = load_config()
+        except Exception as exc:
+            warn_once('load_config', '读不到配置文件 %s（%s: %s）—— 本次当作空配置，需要配置的功能会退化成默认行为'
+                      % (CONFIG_PATH, type(exc).__name__, exc))
+            return ''
+    return str((config or {}).get('openrouterJudgeModel') or '').strip()
+
+
+# ======================================================================
+# Markdown / Frontmatter
+# ======================================================================
+
+def write_with_frontmatter(filepath: str, frontmatter: dict, body: str):
+    import tempfile as _tmp
+    fm_lines = ['---']
+    for k, v in frontmatter.items():
+        if isinstance(v, list):
+            fm_lines.append(f'{k}: [{", ".join(v)}]')
+        elif isinstance(v, str) and ('"' in v or ':' in v or '#' in v):
+            vs = v.strip()
+            fm_lines.append(f'{k}: "{vs}"' if not (vs.startswith('"') and vs.endswith('"'))
+                            else f'{k}: {v}')
+        else:
+            fm_lines.append(f'{k}: {v}')
+    fm_lines.append('---')
+    fm_block = '\n'.join(fm_lines) + '\n\n'
+    dir_name = os.path.dirname(filepath) or '.'
+    fd, tmp_path = _tmp.mkstemp(suffix='.md', dir=dir_name)
+    try:
+        with os.fdopen(fd, 'w', encoding='utf-8') as f:
+            f.write(fm_block)
+            f.write(body)
+        os.replace(tmp_path, filepath)
+    except Exception:
+        if os.path.exists(tmp_path):
+            os.unlink(tmp_path)
+        raise
+
+
+def _unquote(item: str) -> str:
+    """拆掉**成对的**外层引号；不成对就一个字都不动。
+
+    原来这里写的是 `item.strip().strip('"\\'')` —— `.strip()` 的语义是"剥掉首尾**所有**这些
+    字符"，于是项**内部**末尾的引号也被吃掉：`AI 长出"手脚"` 读回来变成 `AI 长出"手脚`。
+    一个字符之差、不报错，下游只表现为"这个名字对不上"（2026-10-01：一张概念页的别名因此
+    永远匹配不上卡片里的链接，那页被报成孤儿）。成对判断把它修好，同时保住"外层引号是语法"。
+    """
+    item = item.strip()
+    if len(item) >= 2 and item[0] == item[-1] and item[0] in '"\'':
+        return item[1:-1]
+    return item
+
+
+def parse_frontmatter(content: str) -> tuple[dict, str]:
+    """解析 Markdown 文件中的 YAML frontmatter。"""
+    if not content.startswith('---'):
+        return {}, content
+    end = content.find('---', 3)
+    if end == -1:
+        return {}, content
+    fm_text = content[3:end].strip()
+    body = content[end + 3:].lstrip('\n')
+    result = {}
+    for line in fm_text.split('\n'):
+        line = line.strip()
+        if not line or ':' not in line:
+            continue
+        key, _, val = line.partition(':')
+        key = key.strip()
+        val = val.strip()
+        if val.startswith('[') and val.endswith(']'):
+            inner = val[1:-1]
+            items = [_unquote(v) for v in inner.split(',')] if inner.strip() else []
+            result[key] = items
+        elif val.startswith('"') and val.endswith('"'):
+            result[key] = val[1:-1]
+        elif val.startswith("'") and val.endswith("'"):
+            result[key] = val[1:-1]
+        else:
+            result[key] = val
+    return result, body
+
+
+NORM_STRIP_RE = re.compile(r'[\s\-_·、，.。:：/\\（）()\[\]【】"\’]+')
+
+
+def normalize_concept_name(name: str) -> str:
+    """判「这两个名字是不是同一个概念」用的规范形。
+
+    去空格、连字符、下划线、标点，转小写，再去掉英文复数尾 —— 实测这样能把
+    `GPT 5.6`/`GPT-5.6`/`GPT5.6`、`AI 工具`/`AI工具`、`AI skill`/`AI skills` 收到一起。
+
+    **它也会把 `news`/`new` 收到一起**，所以它只用来**提议**合并；真正的裁决是
+    "留来源最多的那张页"，而且删之前还有 `--dry-run` 可以看名单。
+
+    住在这里（而不是 `compile_wiki`）是因为**两个读者必须用同一个口径**：`compile_wiki
+    --merge-duplicates` 拿它决定合并谁，`wiki_lint` 拿它报告"还有哪些是同一个节点的两种写法"。
+    两边各写一份的话，体检报出来的名单就会有一半是合并工具不会动的 —— 2026-09-28 之前正是
+    如此：lint 用的是另一套（把所有非字母数字都去掉），于是 `DeepSeek++` 在它眼里等于
+    `DeepSeek`，而合并工具并不这么认为。
+    """
+    stripped = NORM_STRIP_RE.sub('', name.casefold().strip())
+    return re.sub(r'(?<=[a-z])s$', '', stripped)
+
+
+def format_wikilinks(concepts: list[tuple[str, str]]) -> str:
+    lines = ['## 相关概念', '']
+    for name, desc in concepts:
+        if desc:
+            lines.append(f'- [[{name}]] — {desc}')
+        else:
+            lines.append(f'- [[{name}]]')
+    return '\n'.join(lines) + '\n'
+
+
+# ======================================================================
+# 用户定位 & 行动建议（向后兼容）
+# ======================================================================
+
+DEFAULT_USER_PROFILE = (
+    '你是一名对AI感兴趣的环境科学研究生，研究方向是计算机与环境的交叉领域'
+    '（如环境模型、大气污染模拟、遥感反演、环境大数据分析、LCA生命周期评估等）。'
+    '你关注AI工具如何提升科研效率、环境数据处理新技术、以及交叉领域的学术机会。'
+)
+
+ACTION_PROMPT = """基于以下文章，为读者生成可落地的行动建议。
+
+【读者定位】
+{profile}
+
+【文章信息】
+标题：{title}
+来源：{source}
+主题：{topic}
+摘要：{summary}
+
+【正文节选】
+{content}
+
+【输出格式】
+### 相关度
+（高/中/低 + 一句话解释）
+
+### 行动建议
+- **立即可做**：1-2个今天就能执行的具体动作
+- **本周计划**：1个本周可以推进的中期动作
+- **长期关注**：1个值得持续跟踪的方向（相关度为低时省略）"""
+
+
+def generate_action_suggestion(title: str, source: str, topic: str,
+                                summary: str, content: str,
+                                api_key: str, profile: str = '',
+                                engine_type: str = 'deepseek',
+                                max_tokens: int = 1500) -> str:
+    if not profile:
+        profile = DEFAULT_USER_PROFILE
+    prompt = ACTION_PROMPT.format(
+        profile=profile, title=title, source=source, topic=topic,
+        summary=summary[:500], content=content[:3000],
+    )
+    engine = create_engine(engine_type, api_key)
+    return engine.chat(prompt, max_tokens=max_tokens)
+
+# ---------------------------------------------------------------- 知识卡片的公共件
+#
+# `chat_notes.py`（对话线）与 `article_notes.py`（文章线）产出的是**同一种卡片**：
+# 带 frontmatter + `## AI 摘要` + `[[概念]] — 说明` 的 markdown，都喂给 `compile_wiki`。
+# 所以这几样放在这里，一份实现两边用——两处各写一份，早晚有一处会漏。
+
+SEPARATOR = '—'   # 与 `compile_wiki` 认的破折号一致（那条描述要能被它读回描述）
+
+# 文件名里不许出现的字符（Windows 一套 + 控制字符）
+_ILLEGAL_IN_NAME = set('\\/:*?"<>|') | {chr(code) for code in range(0, 32)}
+
+
+def plain(text) -> str:
+    """自由文本里的 `[[…]]` 一律拆掉。
+
+    纪律是「wikilink 只由我们的代码渲染，不由模型写」：`compile_wiki.scan_articles` 收正文里
+    **所有** wikilink，它不会问这是谁写的——模型在摘要里随手一个 `[[X]]`，就会凭空长出一个概念。
+    """
+    out, index = [], 0
+    source = str(text or '')
+    while True:
+        start = source.find('[[', index)
+        if start < 0:
+            out.append(source[index:])
+            break
+        end = source.find(']]', start)
+        if end < 0:
+            out.append(source[index:])
+            break
+        out.append(source[index:start])
+        out.append(source[start + 2:end])
+        index = end + 2
+    return ''.join(out).replace('[[', '').replace(']]', '')
+
+
+def note_path(out_root, name: str, fallback: str = '未命名'):
+    """一张卡一个文件。名字要过文件名安全：会话/文章名里有 `/` 会写到别的目录去。"""
+    from pathlib import Path as _Path
+    cleaned = ''.join('_' if ch in _ILLEGAL_IN_NAME else ch for ch in str(name))
+    cleaned = ' '.join(cleaned.split())[:80].strip().strip('.')
+    return _Path(out_root) / ('%s.md' % (cleaned or fallback))
+
+
+# ---------------------------------------------------------------- 微信正文里的界面残留
+
+# 微信文章正文会带**阅读器自己的界面文字**（"在小说阅读器读本章"那一串），以及文末的
+# 原创标记与公众号名重复。实测：库里 1633 篇笔记，**1484 篇（91%）**的摘要里混着它
+# （先按"整份文件里出现某条短语"数是 330，那是数漏了——短语有好几种写法，按摘要层数才对）。
+# 这份清理在真库上跑过：1484 篇 → 清理后 **0 篇**仍带残留。
+#
+# `classify_daily.py` 里本来有一份 `AD_PATTERNS`，但它只用在日报那条路上，
+# **写笔记那条路（`create_reading_notes.py`）一次都没清洗**——而且对着真串比对，
+# 那份表还漏了一条：真串是「在**公众号**小说中沉浸阅读」，表里写的是
+# 「在小说阅读器**中**沉浸阅读」。所以这里一次列全，各处共用。
+_AD_PHRASES = (
+    '在小说阅读器读本章',
+    '在小说阅读器中沉浸阅读',
+    '在公众号小说中沉浸阅读',
+    '去阅读',
+    'Scan to Follow',
+    '轻触阅读原文',
+    '预览时标签不可点',
+    '继续滑动看下一个',
+)
+
+_UNDERSCORE_RUN = None      # 惰性编译，避免在 import 期做什么重活
+_JS_LINK = None
+
+
+def strip_wx_ads(text: str) -> str:
+    """去掉微信正文里那几样界面残留。
+
+    处理顺序有讲究：先删短语，再删下划线长串，最后收拾"原创 + 公众号名重复 N 遍"。
+    只动**已知的**几样——这是给摘要与提示词做清洁，不是改写正文；
+    拿不准的一律留着（宁可留一点噪音，也不要把用户的话删掉）。
+    """
+    import re as _re
+    global _UNDERSCORE_RUN
+    if _UNDERSCORE_RUN is None:
+        _UNDERSCORE_RUN = _re.compile(r'_{4,}')
+    out = str(text or '')
+    for phrase in _AD_PHRASES:
+        out = out.replace(phrase, ' ')
+    out = _UNDERSCORE_RUN.sub(' ', out)
+    global _JS_LINK
+    if _JS_LINK is None:
+        _JS_LINK = _re.compile(r'\[.*?\]\(javascript:void\(0\);?\)')
+    out = _JS_LINK.sub(' ', out)
+    # 「原创 开源星探 开源星探 开源星探」：公众号名在文末被重复粘了几遍，压成一个
+    out = _re.sub(r'原创\s+(\S{2,12})(?:\s+\1\b){1,}\s*', ' ', out)
+    out = _re.sub(r'原创\s+[一-龥A-Za-z0-9]{2,12}\s*$', '', out)
+    out = _re.sub(r'\b(\S{2,12})(?:\s+\1\b)+', r'\1', out)
+    out = _re.sub(r'[ \t]{2,}', ' ', out)
+    out = _re.sub(r'\n{3,}', '\n\n', out)
+    # 短语被删掉之后可能留下孤零零的空白或行首标点
+    out = _re.sub(r'[ \t]+([，。、；：！？])', r'\1', out)
+    return out.strip()
+
+
+_FENCED_BLOCK = None
+
+
+def strip_wx_ads_document(text: str) -> str:
+    """整篇原文用的清洗：**frontmatter 与围栏代码块一个字不动**，其余同 `strip_wx_ads`。
+
+    删短语的规则**完全复用** `strip_wx_ads`，不另写一套 —— 两处各写一份，迟早会对
+    "什么算残留"给出不同答案（本仓库因为这类分叉吃过亏）。
+
+    两处防护各有实测理由：
+
+    - **frontmatter**：`去阅读` 是**短词**，完全可能出现在标题里（"如何去阅读一本书"）。
+      标题被改就等于改文件名对齐关系 —— 笔记靠 `日期-标题` 找原文，改了就对不上了。
+      实测当前 35,060 篇里 0 篇的 frontmatter 含短语，所以这一条是**防未来**，不是修现在。
+    - **围栏代码块**：`strip_wx_ads` 末尾那几条空白规整（`[ \\t]{2,}` → ' '、`\\n{3,}` → `\\n\\n`）
+      对摘要是无损的，对**原文**却会吃掉代码缩进 —— 实测 20 篇带围栏、其中 10 篇围栏内容会变
+      （HTML/JS 示例）。原文是素材，缩进就是内容。
+    """
+    if text.startswith('---'):
+        end = text.find('\n---', 3)
+        front, body = (text[:end + 4], text[end + 4:]) if end != -1 else ('', text)
+    else:
+        front, body = '', text
+    # `strip_wx_ads` 末尾带 `.strip()`，会把正文首尾空白吃掉。frontmatter 与正文之间那两行
+    # 空行是正文的一部分，所以这里把首尾空白单独摘出来、洗完再放回去。
+    lead = body[:len(body) - len(body.lstrip())]
+    tail = body[len(body.rstrip()):]
+    core = body.strip()
+    global _FENCED_BLOCK
+    if _FENCED_BLOCK is None:
+        import re as _re
+        _FENCED_BLOCK = _re.compile(r'^```.*?^```', _re.S | _re.M)
+    # 占位符用 chr(0) 拼，不写字面反斜杠：本仓有"JSON 层吃掉转义"的前科，能避开就避开。
+    mark = chr(0) + 'FENCE' + chr(0)
+    blocks = []
+
+    def stash(match):
+        blocks.append(match.group(0))
+        return mark + str(len(blocks) - 1) + mark
+
+    cleaned = strip_wx_ads(_FENCED_BLOCK.sub(stash, core))
+    for index, block in enumerate(blocks):
+        cleaned = cleaned.replace(mark + str(index) + mark, block)
+    return front + lead + cleaned + tail