weflow-cli 1.8.1 → 1.9.0

package/resources/panel/renderer.js

@@ -84,6 +84,40 @@ function addTurn(who, text) {
   return div
 }
 
+/**
+ * 把这一轮的**轨迹**折叠着挂在回答下面（服务端 `/api/ask` 一并给回来）。
+ *
+ * **默认折叠**是有意的：轨迹多数时候是"我查了什么"，摊开会把每次回答都变成一屏日志，
+ * 而不想看的人还得滚过它。想核对"它到底查没查、查的是什么"的人点一下展开。
+ * 内容与微信里发「轨迹」看到的是同一份（同一个格式函数），所以两处不会各说各话。
+ *
+ * 全用 `textContent`（不用 innerHTML）：轨迹里有工具参数，是**用户数据**。
+ */
+function addThinking(turn, trace) {
+  const lines = trace && Array.isArray(trace.lines)
+    ? trace.lines.filter((line) => typeof line === 'string' && line.trim()) : []
+  const reasoning = trace && typeof trace.reasoning === 'string' ? trace.reasoning.trim() : ''
+  if (!lines.length && !reasoning) return      // 没有轨迹就什么都不挂（不是显示一个空壳）
+  const details = document.createElement('details')
+  details.className = 'thinking'
+  const summary = document.createElement('summary')
+  summary.textContent = '思考过程'
+  details.appendChild(summary)
+  for (const line of lines) {
+    const row = document.createElement('div')
+    row.className = 'thinking-line'
+    row.textContent = line
+    details.appendChild(row)
+  }
+  if (reasoning) {
+    const row = document.createElement('div')
+    row.className = 'thinking-line thinking-reasoning'
+    row.textContent = reasoning
+    details.appendChild(row)
+  }
+  turn.appendChild(details)
+}
+
 /**
  * 还没聊过时的开头。**空白是这里最糟的状态**：第一次打开的人看到一整片黑，
  * 既不知道它能干什么，也看不出它是活的（下面没有正在输入之类的动静）。
@@ -127,10 +161,11 @@ function renderEmptyState() {
 }
 
 /**
- * 球的背景跟着状态走（CSS 里 `body.busy/.offline/.quota #ball .glow`）。
+ * 球的**脸**跟着状态走（CSS 里 `body.busy/.offline/.quota #ball .face`）——
+ * 2026-09-29 之前还有一层会变色/呼吸的光晕，按用户要求整层去掉了（见 panel.css 那段注释）。
  *
  * 集中在一个函数里改：之前这些类名散在 ask()/refreshStatus() 各处的话，
- * 迟早有一条分支忘了摘掉 `busy`，球就一直亮着——那种"看起来在忙其实没在忙"比不显示更糟。
+ * 迟早有一条分支忘了摘掉 `busy`，球就一直挂着那张脸——那种"看起来在忙其实没在忙"比不显示更糟。
  * 传进来的每一项都**整体替换**，不做增量。
  */
 function setBallState(state) {
@@ -243,7 +278,8 @@ async function ask(text, display = null) {
     pending.remove()
 
     if (res.ok && body.ok) {
-      addTurn('it', body.reply)
+      const turn = addTurn('it', body.reply)
+      addThinking(turn, body.trace)
       // 配额用尽时服务端回的是一句**回答**（不是错误），所以上面照常显示；
       // 这里只是把状态条上的数字刷新一下
       void refreshStatus()
@@ -307,9 +343,101 @@ function prefersReducedMotion() {
     && window.matchMedia('(prefers-reduced-motion: reduce)').matches
 }
 
+// ------------------------------------------------------- 眼珠跟着鼠标（2026-09-30）
+
+/**
+ * 鼠标位置来自**主进程**（`onCursor`），不是页面的 `mousemove`：球只有 96×96，鼠标绝大多数
+ * 时间在窗口**外面**，渲染进程一个事件都收不到。
+ *
+ * 位移上限是**从美术上量出来的**，不是拍的（量法见提交信息里的脚本）：
+ *   - 虹膜到左边那道深色描边只剩约 2.6px（球上），再往左就裂开一条白缝；
+ *   - **向上几乎没有余量**（上面就是眼皮），向下宽一些；
+ *   - 所以夹的是一个**椭圆**，不是一个圆 —— 横向 2.6、向上 0.8、向下 2.6。
+ *
+ * 常量按**球的 96px** 写；球尺寸将来变了，下面按实测宽度等比缩放，不用回来改这些数。
+ */
+const IRIS_MAX_X = 2.6
+const IRIS_MAX_UP = 0.8
+const IRIS_MAX_DOWN = 2.6
+const IRIS_EASE = 0.18      // 每帧逼近目标的比例（一阶低通）
+const IRIS_FAR = 260        // 鼠标远过这个距离就当"看向最边上"，不再加分
+const IRIS_EPS = 0.02       // 到位判定（球上像素）
+
+let cursorTarget = null     // 鼠标的屏幕坐标；null = 还不知道它在哪
+let irisX = 0
+let irisY = 0
+let irisRaf = null
+
+/** 球心在屏幕上的位置。载荷是 DIP、`getBoundingClientRect` 也是 DIP，所以可以直接相减。 */
+function ballCenterOnScreen() {
+  const rect = ball.getBoundingClientRect()
+  return {
+    x: window.screenX + rect.left + rect.width / 2,
+    y: window.screenY + rect.top + rect.height / 2,
+  }
+}
+
+/** 往目标挪一帧。返回"还在动吗"——不动了外层就把 rAF 停掉。 */
+function stepIris() {
+  const size = ball.offsetWidth || 96
+  const k = size / 96
+  let tx = 0
+  let ty = 0
+  if (cursorTarget && !prefersReducedMotion()) {
+    const center = ballCenterOnScreen()
+    const dx = cursorTarget.x - center.x
+    const dy = cursorTarget.y - center.y
+    const dist = Math.hypot(dx, dy) || 1
+    const strength = Math.min(1, dist / (IRIS_FAR * k))   // 远处饱和：屏幕另一头也是"看那边"
+    const ux = (dx / dist) * strength
+    const uy = (dy / dist) * strength
+    tx = ux * IRIS_MAX_X * k
+    ty = uy * (uy < 0 ? IRIS_MAX_UP : IRIS_MAX_DOWN) * k
+  }
+  irisX += (tx - irisX) * IRIS_EASE
+  irisY += (ty - irisY) * IRIS_EASE
+  const done = Math.abs(irisX - tx) < IRIS_EPS && Math.abs(irisY - ty) < IRIS_EPS
+  if (done) {
+    irisX = tx
+    irisY = ty
+  }
+  const iris = ball.querySelector('.iris')
+  if (iris) iris.style.transform = `translate(${irisX.toFixed(2)}px, ${irisY.toFixed(2)}px)`
+  return !done
+}
+
+/**
+ * **静止就停 rAF**。一直跑 60fps 写 transform 会让合成器一直忙——那是为装饰付的电，
+ * 不值得（这个窗口是常驻的）。所以：鼠标动了才起循环，到位就停，下一次推送再起。
+ */
+function pumpIris() {
+  if (irisRaf !== null) return
+  if (typeof requestAnimationFrame !== 'function') return
+  irisRaf = requestAnimationFrame(() => {
+    irisRaf = null
+    if (stepIris()) pumpIris()
+  })
+}
+
+if (hasShell && window.weflowPanel && typeof window.weflowPanel.onCursor === 'function') {
+  window.weflowPanel.onCursor((point) => {
+    cursorTarget = point
+    pumpIris()
+  })
+}
+
 /** 气泡方位相关的类，每次切形态先全摘掉再按主进程说的挂上 */
 const LAYOUT_CLASSES = ['bubble-left', 'bubble-right', 'anchor-top']
 
+/**
+ * 半隐相关的类：`ball-peek` 换成探头那张脸（并去掉球的圆角，好让那条直切边落在屏幕边上），
+ * `ball-peek-right` 再把图水平镜像一次给右边用。
+ *
+ * 贴哪条边只有主进程知道（它才管窗口位置），所以这一组**和形态一样是主进程说了算**，
+ * 页面只照着挂。同样先整体摘掉再按说的挂——散着写迟早有一条分支忘了摘。
+ */
+const PEEK_CLASSES = ['ball-peek', 'ball-peek-right']
+
 /**
  * 按主进程说的形态切 class。**这里是唯一改形态的地方**。
  *
@@ -322,15 +450,28 @@ const LAYOUT_CLASSES = ['bubble-left', 'bubble-right', 'anchor-top']
 function applyMode(payload) {
   const mode = payload && payload.mode === 'ball' ? 'ball' : 'chat'
   const side = payload && payload.side === 'right' ? 'right' : 'left'
-  document.body.classList.remove('mode-ball', 'mode-chat', 'closing', ...LAYOUT_CLASSES)
-  document.body.classList.add(mode === 'chat' ? 'mode-chat' : 'mode-ball')
+  // **只摆锚、不切形态**（`anchorOnly`）：展开分两步走，见 `main.cjs` 里"先摆锚、等页面
+  // 画完、再改窗口尺寸"那段。切形态会连带把气泡显出来，而那会儿窗口还是 96px ——
+  // 气泡恰好盖住球。所以第一步只动 `LAYOUT_CLASSES`。
+  const anchorOnly = !!(payload && payload.anchorOnly)
+  document.body.classList.remove(
+    ...(anchorOnly ? LAYOUT_CLASSES : ['mode-ball', 'mode-chat', 'closing', ...LAYOUT_CLASSES]))
+  // 半隐与"锚"无关，所以 `anchorOnly` 那一步（展开的两个阶段）不许把它摘掉
+  if (!anchorOnly) {
+    document.body.classList.remove(...PEEK_CLASSES)
+    if (mode === 'ball' && payload && payload.peek) {
+      document.body.classList.add('ball-peek')
+      if (payload.peek === 'right') document.body.classList.add('ball-peek-right')
+    }
+  }
+  if (!anchorOnly) document.body.classList.add(mode === 'chat' ? 'mode-chat' : 'mode-ball')
   if (mode === 'chat') {
     document.body.classList.add(side === 'right' ? 'bubble-right' : 'bubble-left')
     if (payload && payload.anchorY === 'top') document.body.classList.add('anchor-top')
     const height = Number(payload && payload.bubbleHeight)
     document.body.style.setProperty('--bubble-height',
       `${Number.isFinite(height) && height > 0 ? Math.round(height) : 560}px`)
-    input.focus()
+    if (!anchorOnly) input.focus()
   }
 }
 
@@ -354,6 +495,21 @@ function toggleMode() {
 if (hasShell) {
   // `shell` 这个类决定球在不在场（见 panel.css）：浏览器降级那条路永远不该看见球
   document.body.classList.add('shell', 'mode-ball')
+  // **四张脸先取回来。**（2026-09-29 加的，用户报"点一下会闪一下"）
+  //
+  // 这些脸是 CSS 背景图，**什么时候用什么时候才去取**；而实测从守护进程取一张要
+  // **~15 毫秒**（60Hz 一帧是 16.7ms，正好一帧）。所以按下球的那一刻才开始取，第一帧
+  // 就是空的——看起来就是"闪一下"。仓库里那句老注释写过同一个症状
+  // （"球在按下的一瞬间会闪成一张空图"），当时的结论是静态白名单一张都不能漏；
+  // 现在白名单是对的，但**第一次用到仍然要等那一趟网络**。预取把它挪到页面刚加载时，
+  // 那时没人盯着球看。
+  //
+  // 放在 `hasShell` 里面：浏览器降级那条路根本不显示球，没必要替它取。
+  for (const face of ['mascot.png', 'mascot-happy.png', 'mascot-thinking.png',
+                      'mascot-sorry.png', 'mascot-tired.png']) {
+    const img = new Image()
+    img.src = '/panel/' + face
+  }
   ball.hidden = false
   collapse.hidden = false
 
@@ -431,10 +587,11 @@ if (hasShell) {
       }
     })()
   })
-  document.addEventListener('click', () => closeQuickMenu())
-  document.addEventListener('keydown', (event) => {
-    if (event.key === 'Escape') closeQuickMenu()
-  })
+  // 这里原来挂着两条 `closeQuickMenu()`（点了别处关菜单、Esc 关菜单）——**那是页内菜单时代的
+  // 旧址**：菜单现在是**原生**的（`openQuickMenu` 由主进程弹，画在窗口外面），没有"页内菜单"
+  // 可关，而 `closeQuickMenu` 这个函数**在文件里根本没有定义**。
+  // 后果是：点面板里任何地方、或按 Esc，都会抛一次未捕获的 ReferenceError（不致命，
+  // 但测试里 jsdom 会把它报出来，控制台也一直脏）。按"没有页内菜单"这个事实删掉。
 
   collapse.addEventListener('click', () => { requestMode('ball') })
 

package/scripts/_utils.py

@@ -601,6 +601,38 @@ def get_db_config(config=None):
     }
 
 
+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:
@@ -676,6 +708,20 @@ def write_with_frontmatter(filepath: str, frontmatter: dict, body: str):
         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('---'):
@@ -695,7 +741,7 @@ def parse_frontmatter(content: str) -> tuple[dict, str]:
         val = val.strip()
         if val.startswith('[') and val.endswith(']'):
             inner = val[1:-1]
-            items = [v.strip().strip('"\'') for v in inner.split(',')] if inner.strip() else []
+            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]

package/scripts/backfill_articles.py

@@ -4,6 +4,7 @@
 用法:
   python scripts/backfill_articles.py --since 2026-03-01 --until 2026-08-31 --dry-run --json
   python scripts/backfill_articles.py --since 2026-03-01 --until 2026-08-31 --workers 12 --yes
+  python scripts/backfill_articles.py --since 2025-09-05 --until 2026-03-02 --topic AI --yes
 
 ## 为什么不是直接跑 `pipeline run --date`
 
@@ -26,6 +27,17 @@
 **图片型文章抓不到正文。** 实测 3/4、7/4 两天：27/40、44/60 有正文，其余是图文消息
 （内容全在图片里），清洗掉图片与链接后不足 100 字，与 `biz_daily` 一样被跳过。这不是
 抓取失败，是那类文章本来就没有文字。所以"2 万篇"这个量级是有正文的部分，不是总量。
+
+## `--topic`：只回填一部分主题（先筛后抓）
+
+`--topic AI` 用的就是本脚本自己判主题的那套 `_guess_topic`（只看标题与号名、**不看正文**），
+所以它筛出来的 AI 集合，与全量跑完之后落在 `AI/` 目录里的那批**逐个相同** —— 不是另立一套
+口径，只是省掉了其余主题的抓取（实测 2025-09-05~2026-03-02 那段：全量 10,880 篇里 AI 占
+1,759 篇，抓取量约 1/6）。
+
+**代价必须写出来：那一天就不再是完整的一天。** 所以 `.articles.json` 里会多一个 `topicFilter`
+（README 里也写明），`day_done` 据此在之后跑**全量**时**不会**跳过这一天。少了这一步，那天
+其余五个主题的文章会被永久漏掉、而且不报错 —— 文件在、json 在、"已回填"看起来处处成立。
 """
 import argparse
 import hashlib
@@ -121,6 +133,32 @@ def apply_topics(articles):
     return articles
 
 
+def parse_topics(values):
+    """把 `--topic` 的取值展开成一个列表：**可重复，也可逗号分隔**。
+
+    两种都收的理由是仓库里另一条命令（`article_notes.py`）的 `--topic` 就是 `action='append'`
+    且写明"可重复或逗号分隔"。只认一种的话，照另一边习惯写就会**静默只做一个主题**。
+
+    `values` 传字符串也当单个处理：`for chunk in 'AI'` 会**逐字符**迭代，而每个字符都不在分类法里
+    —— 于是"整批被拒"看起来跟"参数拼错"一模一样，很难查。这里把它挡住。
+    """
+    if isinstance(values, str) or values is None:
+        values = [values or '']
+    return [t.strip() for chunk in values for t in str(chunk).split(',') if t.strip()]
+
+
+def select_topics(articles, topics):
+    """只留下选中主题的文章；`topics` 为空/None 表示全要（原样返回）。
+
+    必须在 `apply_topics` **之后**调：主题是那个函数的输出。顺序对"选中哪些"没有影响
+    （`_guess_topic` 逐篇独立、只看标题与号名），所以筛出来的集合与全量跑完落在对应主题
+    目录里的那批逐个相同。
+    """
+    if not topics:
+        return articles
+    return [a for a in articles if a.get('topic') in topics]
+
+
 def fetch_bodies(articles, workers: int, log=None):
     """并发把这批文章的正文抓回来，写进 `fetched_md`。
 
@@ -151,13 +189,66 @@ def fetch_bodies(articles, workers: int, log=None):
     return {'attempted': len(todo), 'ok': ok}
 
 
-def write_day(articles, day, out_root):
+def _read_index(day_dir) -> dict:
+    """读这一天已有的 `.articles.json`（没有就空表）。
+
+    **读不了的时候不是安静地返回空表**：那等于把已有条目从索引里抹掉，而这件事不会报错
+    —— 正是这一整段要防的事。所以把原文件改名留成 `.json.bad` 再继续，至少还能人工救。
+    """
+    path = Path(day_dir) / '.articles.json'
+    if not path.exists():
+        return {}
+    try:
+        payload = json.loads(path.read_text(encoding='utf-8'))
+        return payload if isinstance(payload, dict) else {}
+    except Exception as exc:
+        try:
+            path.rename(path.with_name('.articles.json.bad'))
+        except OSError:
+            pass
+        print('    警告：%s 读不了（%s），已留成 .articles.json.bad，旧索引未参与合并'
+              % (path.name, exc))
+        return {}
+
+
+def _merge_articles(kept, fresh):
+    """合并两组 `.articles.json` 条目，按「来源-标题」去重（那是它在盘上的文件名）。
+
+    顺序按 `time` 再 `title` 排，是为了让同一天的索引**稳定**：分两次回填的那天，
+    第二次不该把先前的条目挤到别处去，否则每次跑都产生一份看着像"改了"的索引。
+    没有 `time` 的老条目（理论上不会有）排在前面，不参与排序。
+    """
+    merged = {}
+    for entry in list(kept) + list(fresh):
+        if not isinstance(entry, dict):
+            continue
+        merged[(str(entry.get('source', '')), str(entry.get('title', '')))] = entry
+    return sorted(merged.values(), key=lambda e: (str(e.get('time', '')), str(e.get('title', ''))))
+
+
+def write_day(articles, day, out_root, topic_filter=None, truncated=False):
     """落盘：`<日期>/<主题>/<来源>-<标题>.md` + `.articles.json` + README。
 
     格式与 `biz_daily` 一致——`create_reading_notes` 与 `compile_wiki` 都按那个形状读。
     正文那段写 `## AI 摘要`（内容用文章自带的 digest）：**本脚本不调模型**，所以这里
     放的只能是原文已有的东西，不能假装是生成的摘要。
+
+    传了 `topic_filter`（`--topic`）时，这里会**再筛一次**并在元数据里留下 `topicFilter`：
+
+    - 筛在**这里**做，是为了让标记不可能撒谎。如果筛只发生在调用方（`main`），那么有人
+      漏调那一步时，`write_day` 会把六个主题全写出去、同时盖上"只回填了 AI"的章 ——
+      一个自称只回填了一半、实际写满了的目录，比不写标记更坏。
+    - README 里也写明这一天是哪几个主题。**这两处不是装饰**：一天只回填了一半却看起来像
+      完整的一天，是这份产出唯一会"静默变少"的方式（见 `day_done`）。
+    - 传了 `truncated`（`--limit-per-day` 截过）时同理，多一个 `truncated` 标记。
+    - **索引是与这一天已有的内容合并的，不是覆盖**：先 `--topic AI` 再来 `--topic 学术`，
+      先前那个主题的条目必须留着。覆盖会让**索引比盘上少几条**而 md 还在 —— 不报错，
+      而"索引与盘不一致"正是这一支反复吃的那个形状（见 `_merge_articles`、`_read_index`）。
+      `topicFilter` 取并集；只要这次是全量、或这天本来就是完整的，标记就**消失**。
+
+    `truncated` 只影响元数据（它记录的是"调用方截过"，不宜在这里重算——截在调用方发生）。
     """
+    articles = select_topics(articles, topic_filter)
     groups, fallbacks = _group_by_topic(articles)
     out_dir = Path(out_root) / day
     written, skipped = [], []
@@ -201,13 +292,50 @@ def write_day(articles, day, out_root):
             written.append(article)
     out_dir.mkdir(parents=True, exist_ok=True)
     serializable = [_serializable_article(a, day) for a in written]
+    # **索引描述的是这一天盘上全部的文章，不是这一轮写的那批。** 分两次、用不同主题回填同一天
+    # 时（`--topic AI` 之后再来 `--topic 学术`），只写本轮的话，先前那个主题的条目会从索引里
+    # 消失而 md 还留在盘上——索引少一条、盘上多一篇，不报错。所以先把不属于本轮的旧条目接过来。
+    prior = _read_index(out_dir)
+    kept = [e for e in prior.get('articles', [])
+            if e.get('topic') not in set(topic_filter or ())]
+    stored_filter = prior.get('topicFilter')
+    # 「**没有**旧索引」与「旧索引是**完整**的一天」是两件事，第一版把它们混成了一个 `None`：
+    # 于是第一次做过滤回填时标记根本没写，那天看起来像完整的一天 —— 正是要防的那件事。
+    # 区分它们的是"旧索引里有没有东西"，不是"有没有那个键"。
+    if topic_filter is None:
+        scope_filter = None                       # 全量跑过 → 这天完整
+    elif not prior.get('articles'):
+        scope_filter = sorted(topic_filter)       # 第一次写这天，且只写了一部分
+    elif stored_filter is None:
+        scope_filter = None                       # 本来就完整，这次只是重做其中一部分
+    else:
+        scope_filter = sorted(set(stored_filter) | set(topic_filter))
+    if scope_filter and set(scope_filter) >= set(TOPICS):
+        # 六个主题都做过一遍了 —— 这一天"能做的都做了"，与全量跑过没有区别。
+        # 不撤标记的话它**永远**被当成没做完：以后随便跑一次全量都会把整个窗口重抓一遍。
+        scope_filter = None
+    payload = {'date': day, 'generated_at': datetime.now(TZ).strftime('%Y-%m-%d %H:%M:%S'),
+               'backfilled': True, 'articles': _merge_articles(kept, serializable)}
+    # 只在**确实是一部分**的时候才加这两个键：全量回填写出来的文件与以前逐字节相同，
+    # 而 `day_done` 把"没有 topicFilter"读作"完整的一天"。缺了它就等于把半天的产出
+    # 冒充成整天——这正是这条路径唯一能静默丢东西的地方。
+    if scope_filter:
+        payload['topicFilter'] = scope_filter
+    if truncated or prior.get('truncated'):
+        # `truncated` 一旦记上就不撤销：这一次没截，不代表上一次截掉的那些补回来了。
+        payload['truncated'] = True
     (out_dir / '.articles.json').write_text(
-        json.dumps({'date': day, 'generated_at': datetime.now(TZ).strftime('%Y-%m-%d %H:%M:%S'),
-                    'backfilled': True, 'articles': serializable},
-                   ensure_ascii=False, indent=2), encoding='utf-8')
+        json.dumps(payload, ensure_ascii=False, indent=2), encoding='utf-8')
+    if scope_filter:
+        scope = ('**只回填了 %s 主题** —— 这一天并非全部文章，其余主题还没拉。\n'
+                 % '、'.join(scope_filter))
+    else:
+        scope = ''
+    # README 说的是**这一天**有几篇（合并后的），不是这一轮写了几篇 —— 分两次回填的那天，
+    # 前者才是读它的人想要的数。
     (out_dir / 'README.md').write_text(
         '# 公众号文章 — %s（历史回填）\n\n共 %d 篇。正文由 `backfill_articles.py` 抓取，'
-        '**未下载图片、未调用模型**。\n' % (day, len(written)), encoding='utf-8')
+        '**未下载图片、未调用模型**。\n%s' % (day, len(payload['articles']), scope), encoding='utf-8')
     return {'written': len(written), 'skipped': len(skipped),
             'fallbackTopics': fallbacks, 'skipSample': skipped[:3]}
 
@@ -277,15 +405,40 @@ def days_with_articles(out_root) -> list:
     return days
 
 
-def day_done(out_root, day) -> bool:
-    """这一天已经回填过了吗（增量：免得重跑把同样的文章再抓一遍）。"""
+def day_done(out_root, day, topics=None) -> bool:
+    """这一天**我们要的那些主题**已经回填过了吗（增量：免得重跑把同样的文章再抓一遍）。
+
+    `topics=None` 表示"全量"。**判据不只是"写过"**，还要看写的是不是完整的一天：
+
+    - 只回填过 AI 的一天，`.articles.json` 里带着 `topicFilter`。此后跑**全量**时必须
+      **不能**被跳过 —— 否则那天其余五个主题的文章会被永久漏掉，而且不报错：文件在、
+      `.articles.json` 在、"已回填"看起来成立。这就是 `days_with_articles` 那条注释里
+      记的同一类事故（拿一个不完整的判据当"做完了"）。
+    - 反向：`--topic AI` 之后又跑 `--topic AI,学术`，存过的是子集，也要重做；
+      而存过的**覆盖**了这次要的（或那天本来就完整），才算做完。
+    - 被 `--limit-per-day` 截过的一天**从来不算做完**：截掉的那些既没抓、也看不出来。
+    """
     path = Path(out_root) / day / '.articles.json'
     if not path.exists():
         return False
     try:
-        return bool(json.loads(path.read_text(encoding='utf-8')).get('articles'))
+        payload = json.loads(path.read_text(encoding='utf-8'))
     except Exception:
         return False
+    if not payload.get('articles'):
+        return False
+    if payload.get('truncated'):
+        return False
+    stored = payload.get('topicFilter')
+    if stored is None:
+        return True            # 完整的一天，所有主题都在
+    if set(stored) >= set(TOPICS):
+        # 六个主题在标记里都在 = 这天完整（`write_day` 现在会直接把标记撤掉，但**旧代码写的**
+        # 天数带着这个形态留在盘上 —— 读的判据也认它，免得那几天永远"没做完"）。
+        return True
+    if topics is None:
+        return False           # 只要过一部分，全量的活还没干
+    return set(stored) >= set(topics)
 
 
 def main():
@@ -300,7 +453,13 @@ def main():
     parser.add_argument('--vault-sync', action='store_true',
                         help='只做这件事：把已回填的天补拷进 Vault 的 Sources（本地，不抓取、不调模型）')
     parser.add_argument('--workers', type=int, default=8, help='抓正文的并发数（默认 8）')
-    parser.add_argument('--limit-per-day', type=int, default=0, help='每天最多抓几篇（0=不限）')
+    parser.add_argument('--limit-per-day', type=int, default=0,
+                        help='每天最多抓几篇（0=不限）。设了就不是完整的一天：'
+                             '截掉的那些既没抓也看不出来，所以增量判断会重做这天')
+    parser.add_argument('--topic', action='append', default=[], metavar='T',
+                        help='只回填这些主题（可重复或逗号分隔，合法值 %s），不写=全部。'
+                             '只回填过一部分主题的一天，之后跑全量时不会被跳过。'
+                             % '/'.join(TOPICS))
     parser.add_argument('--refresh', action='store_true', help='已回填过的天也重做（默认跳过）')
     parser.add_argument('--max-days', type=int, default=0, help='最多处理几天（0=不限，用于试跑）')
     parser.add_argument('--dry-run', action='store_true', help='只报到要抓多少，不抓不写')
@@ -319,6 +478,17 @@ def main():
         print('--until 不能早于 --since'); return 1
     if args.workers < 1:
         print('--workers 要 ≥ 1'); return 1
+    picked = parse_topics(args.topic)
+    unknown = [t for t in picked if t not in TOPICS]
+    if unknown:
+        # 拼错一个词（比如 `--topic ai` 小写）会静默筛出 0 篇、然后报一句"没有要处理的"——
+        # 看着像"这天本来就没文章"。所以这里当场报错并列出合法值，放在碰库之前。
+        message = ('--topic 里有不在分类法里的主题：%s\n合法值：%s'
+                   % ('、'.join(unknown), '、'.join(TOPICS)))
+        print(json.dumps({'success': False, 'error': message}, ensure_ascii=False)
+              if args.json else message)
+        return 1
+    topics = sorted(set(picked)) or None
 
     if args.vault_sync:
         # **补拷模式**：不抓取、不调模型，只把已经躺在 biz-daily 的那几天补进 Vault。
@@ -328,6 +498,8 @@ def main():
         # 重复跑是**安全**的：`copy_to_vault` 逐 md 覆盖、不删别的东西，而它现在还会洗残留，
         # 所以"再补一次"同时也是"把库里那一层重新洗一遍"（2026-09-28 就是这么把 1,755 篇
         # 漏网的补上的 —— 那天被 `backfilled` 标记挡在门外的 12 天）。
+        if topics:
+            print('提示：--vault-sync 只把**已回填的** md 补拷进 Vault，--topic 对这一步不起作用。')
         days = days_with_articles(args.out)
         if args.max_days:
             days = days[:args.max_days]
@@ -374,28 +546,35 @@ def main():
 
     todo = []
     for day in days:
-        if not args.refresh and day_done(args.out, day):
+        if not args.refresh and day_done(args.out, day, topics):
             continue
         articles = collect_articles(cursor, users, name_map, day)
+        # 筛选在 `collect_articles` **之后**：主题是它内部 `apply_topics` 的输出，
+        # 先筛就无从筛起（理由与等价性写在 `select_topics` 上）。
+        articles = select_topics(articles, topics)
+        # 截断要在**筛完之后**判断：`--limit-per-day 5 --topic AI` 该解作"每天 5 篇 AI"。
+        truncated = bool(args.limit_per_day) and len(articles) > args.limit_per_day
         if args.limit_per_day:
             articles = articles[:args.limit_per_day]
         if articles:
-            todo.append((day, articles))
+            todo.append((day, articles, truncated))
 
     if args.dry_run:
-        total = sum(len(items) for _, items in todo)
-        need = sum(1 for _, items in todo for a in items
+        total = sum(len(items) for _, items, _ in todo)
+        need = sum(1 for _, items, _ in todo for a in items
                    if len(body_without_media(a.get('local_text'))) < MIN_BODY_CHARS and a.get('url'))
         payload = {
             'success': True, 'dryRun': True, 'action': 'backfill-articles',
+            'topics': topics or '全部',
             'days': len(todo), 'articles': total, 'needFetch': need,
             'workers': args.workers, 'invokesAI': False, 'downloadsImages': False,
             'readsLocalData': True,
             'note': '只抓正文，不下图片、不调用模型；抓完还要跑 vault notes 与 article-notes',
         }
         print(json.dumps(payload, ensure_ascii=False, indent=2) if args.json
-              else '%d 天、%d 篇（其中 %d 篇要联网抓正文），并发 %d'
-                   % (len(todo), total, need, args.workers))
+              else '%d 天、%d 篇（其中 %d 篇要联网抓正文），并发 %d，主题 %s'
+                   % (len(todo), total, need, args.workers,
+                      '全部' if not topics else '、'.join(topics)))
         conn.close()
         return 0
 
@@ -404,23 +583,25 @@ def main():
         conn.close()
         return 0
     if not args.yes:
-        print('会抓 %d 天、%d 篇的正文（不调模型）。加 --yes 确认。'
-              % (len(todo), sum(len(i) for _, i in todo)))
+        print('会抓 %d 天、%d 篇的正文（不调模型，主题 %s）。加 --yes 确认。'
+              % (len(todo), sum(len(i) for _, i, _ in todo),
+                 '全部' if not topics else '、'.join(topics)))
         conn.close()
         return 1
 
     report = []
-    for index, (day, articles) in enumerate(todo, 1):
-        print('\n[%d/%d] %s — 库里 %d 篇' % (index, len(todo), day, len(articles)))
+    for index, (day, articles, truncated) in enumerate(todo, 1):
+        print('\n[%d/%d] %s — 选中 %d 篇' % (index, len(todo), day, len(articles)))
         fetch = fetch_bodies(articles, args.workers, log=print)
-        result = write_day(articles, day, args.out)
+        result = write_day(articles, day, args.out, topic_filter=topics, truncated=truncated)
         print('    写入 %d 篇，跳过 %d 篇（正文太短），主题兜底 %d 篇'
               % (result['written'], result['skipped'], result['fallbackTopics']))
         if args.vault_copy:
             sync = copy_to_vault(day, args.out, args.vault_root)
             print('    入 Vault 的 Sources: %d 个 md' % sync['copied'])
         report.append({'date': day, 'inDb': len(articles), 'fetched': fetch['ok'],
-                       'written': result['written'], 'skippedThin': result['skipped']})
+                       'written': result['written'], 'skippedThin': result['skipped'],
+                       'truncated': truncated})
     conn.close()
 
     total_written = sum(r['written'] for r in report)