weflow-cli 1.14.1 → 1.15.0

package/docs/PROJECT_STATE.md

@@ -514,6 +514,41 @@ because nobody built it" look identical to a reader.
 - **`tags` is the configured category for any source that has one, by design.** The prompt for a categorised source is summary-only and explicitly says *不要输出主题、标签、相关度或概念字段*, and the code sets `tags = [category]` itself. Measured over the 1584 articles of the 11 stored days: 1396 carry exactly `[topic]`, 182 carry none, and only **6** carry real extracted tags - and those 6 are the corpus built without configured categories. The checkable signature is that **on every one of those days each source maps to exactly one topic** (36/40/15/43/41/27/35/36/3/36/6 sources, no exceptions), which is what topic-from-config produces and per-article classification does not. A live call through the production prompt returns real tags (`AI与数学, 人类数学家, 数学共同体, 人机关系, 学术人文`), so extraction itself is not broken - it is simply not asked for on that path. Practical consequence: to get meaningful tags for a source, leave its category unconfigured (and accept that its topic then comes from classification rather than from you).
 - **No real artifact on disk carries `includeScore`.** The six files in the 2026-09-05 output directory were written before that field existed, so the field has never been produced in a real run - which is why calibration has to re-score articles rather than read stored values.
 - The report's admission threshold (`INCLUDE_THRESHOLD = 0.5` on `includeScore`) is provisional in the same way and, unlike the old rule, it is actually applied: both loaders call one predicate. Turning it on **reduced** what the report collects, because the primary loader previously collected everything unfiltered. On a 6-article trial the scores straddled the cut point (0.48 and 0.63 on two engineering posts), so the cut point is doing real work rather than being decorative.
+- **Four read-only "questions WeChat cannot answer" commands ship as CLI, not just scripts.**
+  `today` (cross-year same-day recap), `network` (shared groups / introduction paths from `contact.db`),
+  `promises` (what I said I would do, with the follow-up evidence), `timeline` (one account's articles
+  over time). All four are `--json`-capable and read only; none sends or calls the assistant layer.
+  Two shared traps were fixed while wiring them: **contact names live in `contact.db`, never in the
+  message shards** (looking for a `contact` table there silently yields ids, so every name printed as
+  `47966561144@chatroom`), and **the configured `wxid` may carry a suffix the `Name2Id` table does not**
+  (`wxid_账号A_后缀` vs `wxid_账号A`), which made "messages I sent" match nothing until the comparison
+  became prefix-tolerant.
+- **Voice transcription works once four decode settings are on - measured 2026-10-22.** Default
+  `model.transcribe(...)` returned verbatim repetition (`我做的事情都没有做过` x3) on dialect-heavy clips,
+  which is Whisper's self-conditioning failure mode rather than an audio problem: the decode side was
+  verified good (15878-byte SILK → 8.4 s of 16 kHz mono, peak 27613, 46% loud samples, and decoding at
+  8000 vs 16000 Hz yields the same 8.38 s so PILK resamples rather than shifting pitch). The fix is the
+  combination in `transcribe_wav`: `condition_on_previous_text=False` (breaks the repetition chain),
+  `vad_filter=True` (silence is what invites hallucination), `compression_ratio_threshold=2.0` with a
+  `temperature` ladder (so a repeating output really escalates instead of stalling), and
+  `repetition_penalty=1.15`. Measured after the change: **4 of 5 clips readable**
+  (`你填一下交通补贴20元 兄弟`), where before it was 0 of 5. Residual errors remain on heavy dialect and
+  are reported as-is; there is no claim of accuracy here.
+- **Voice enters the *phrase* index, not the semantic one.** `build_phrase_index` appends
+  `output/.voice_index/voices.jsonl` as `type='voice'`, so `search --phrase` finds what was said out
+  loud - the one content class WeChat cannot search at all. It is deliberately kept out of the semantic
+  index (a second embedding bill for a dialect-approximate transcript is a bad trade) and out of the
+  `wiki`/`chat` line filters (those two are user-chosen scopes; voice is a third kind of evidence).
+  `voice_transcribe.py` owns decode + cache + resume, and the cache is content-addressed so a re-run
+  after ids shift still hits.
+- **Message shards are split by *time*, not by account or by size - measured 2026-10-22.** The four
+  `message_*.db` files on this machine each cover a consecutive span, oldest to newest:
+  `message_2.db` 2024-03-29 ~ 2024-08-28 (1 conversation table), `message_1.db` 2024-08-30 ~ 2025-08-28 (2),
+  `message_0.db` 2025-08-31 ~ 2026-08-30 (122), `message_3.db` 2026-08-30 ~ 2026-10-22 (84). Two consequences
+  worth knowing before reading anything into "missing" history: the **earliest record is 2024-03-29** (that is
+  where this account's data starts, not a reading failure), and a *year* can look empty while the shard holding
+  it holds almost nothing - the whole of 2024 lives in 3 conversation tables across two shards. `discover_message_shards`
+  reads all of them, so `on_this_day.py` correctly reports "no chat that day" rather than failing to look.
 - Message reads select only the columns the reader consumes, resolved per shard from what that shard actually has. `nt_decrypt` reads six (`local_id`, `server_id`, `local_type`, `real_sender_id`, `create_time`, `message_content`) and a WeChat version that renames or drops any other column of the message table therefore cannot make a shard unreadable. What is lost is reported, not swallowed: a shard lacking one of those six is read anyway and named in `missingColumns`, while a shard where none of them is present is reported as `SCHEMA_MISMATCH` and makes `coverage` partial. `export_chat_html` reads rows positionally, so there a missing column keeps its slot as `NULL` instead of shifting the fields after it. Both are verified against synthetic shards only - no future WeChat schema has been tested.
 
 - **Topic exclusion is a display-layer switch, and that is a measurement result rather than a preference.** `dailyExcludeTopics` (or `--exclude-topics`) removes a topic from the daily report and the reader page; the article is still fetched, judged and archived. Filtering *before* the fetch was the original ask and was rejected on evidence: from a source name plus a title and the platform digest - everything that exists pre-fetch - the type judgement agreed with the source-level configuration on only **60%** of 217 articles, with 48 false positives, and there is no gold standard either way. A dropped fetch is irreversible (nothing is archived, and the page is not the same weeks later) while an unwanted article costs only attention, so the decision is deliberately placed where it can be undone by regenerating. The exclusion is orthogonal to `--include-all` and to the inclusion score, and **all three lists in 我拿不准的 are filtered** - passing the exclusion set to `admits()` in the "not admitted" list had the opposite effect and surfaced the excluded articles (that list is populated by exactly the articles being excluded). One predicate (`is_excluded_topic`) now serves both directions. Excluding the focus topic is refused with a WARN, because the result is not an empty report but a misleading one: it exits with "未找到文章，请先运行 biz_daily.py". The key is registered in all four `configService` literals plus `bin`'s `configurableKeys`, which `test/config-keys.test.ts` now enforces - a key missing from defaults or `clear()` survives `config set` and then quietly disappears.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "weflow-cli",
-  "version": "1.14.1",
+  "version": "1.15.0",
   "description": "让 AI 读懂你的微信 — 公众号日报·聊天导出·知识库搜索·MCP Server",
   "type": "module",
   "bin": {

package/scripts/bonds.py

@@ -58,7 +58,7 @@ OTHER_CHANNEL = ('打电话', '手机号', '电话号', '邮箱', '邮件', '短
 
 # 名字里带这些的，**只标出来、不自动排除**。
 #
-# 为什么只标不排：实测有个「普华口腔门诊部」的 id 是 `wxid_v5q0oc8eb04712`、`local_type=1`、
+# 为什么只标不排：实测有个「普华口腔门诊部」的 id 是 `wxid_示例号`、`local_type=1`、
 # 还有自定义微信号 —— 它**和真人长得一模一样**，结构上没有任何标记能区分（`@openim` 那种是另一类）。
 # 所以"谁算人"这一手，工具摆出可疑的、由人决定；名单在 `output/bonds-skip.txt` 或 `--skip` 里。
 SERVICE_NAME_HINTS = ('门诊', '口腔', '医院', '客服', '小助手', '福利', '旗舰店', '专营店',

package/scripts/network.py

@@ -0,0 +1,206 @@
+"""人脉图谱：谁和你在同一个群、谁适合做引荐人。
+
+数据全在 `contact.db`（联系人 + 群 + 群成员），不碰消息库，也就没有"读聊天内容"这件事：
+     contact(id, username, nick_name, remark)      4192 人
+     chat_room(id, username, owner)                80 个群
+     chatroom_member(room_id, member_id)           4305 条关系（member_id 是 contact.id）
+
+用法：
+    python scripts/network.py --groups              群概览（成员数，按大小排）
+    python scripts/network.py --with 张三           我和他共同在哪些群
+    python scripts/network.py --intro 张三           谁最适合把我介绍给他
+    python scripts/network.py --intro 张三 --json
+"""
+from __future__ import annotations
+
+import argparse
+import json
+import pathlib
+import sys
+from collections import defaultdict
+
+SCRIPT_DIR = pathlib.Path(__file__).resolve().parent
+sys.path.insert(0, str(SCRIPT_DIR))
+
+from _utils import load_config, decrypt_lock  # noqa: E402
+from nt_common import derive_database_key  # noqa: E402
+from export_chat_html import connect  # noqa: E402
+
+
+def _open_contact(cfg):
+    path = cfg.get('contactDbPath') or ''
+    if not path:
+        raise SystemExit('配置里没有 contactDbPath，先跑 weflow-cli init')
+    key = decrypt_lock(cfg.get('contactKey', '') or cfg.get('ntKey', '') or '')
+    salt = decrypt_lock(cfg.get('contactSalt', '') or cfg.get('ntSalt', '') or '')
+    pw = decrypt_lock(cfg.get('favPassphrase', '') or cfg.get('decryptKey', '') or '')
+    k, s = derive_database_key(path, key, salt, pw)
+    return connect(path, k, s)
+
+
+def load_graph(cfg):
+    """(people, rooms, members) —— people: id->名字; rooms: id->群名; members: room->{id}"""
+    conn, cur = _open_contact(cfg)
+    try:
+        people = {}
+        for pid, username, nick, remark in cur.execute(
+                'SELECT id, username, COALESCE(nick_name,""), COALESCE(remark,"") FROM contact'):
+            name = remark or nick or username
+            people[int(pid)] = {'name': name, 'username': username, 'nick': nick, 'remark': remark}
+
+        rooms = {}
+        # 群昵称在 `contact` 里（`@chatroom` 那条的 remark/nick_name），`chat_room.username`
+        # 只是 id —— 不查这一步，输出里 80 个群全叫 `47966561144@chatroom`。
+        by_username = {p['username']: p for p in people.values()}
+        for rid, username, owner in cur.execute('SELECT id, username, COALESCE(owner,"") FROM chat_room'):
+            info = by_username.get(username) or {}
+            name = info.get('remark') or info.get('nick') or username
+            rooms[int(rid)] = {'name': name, 'username': username, 'owner': owner}
+
+        members = defaultdict(set)
+        for rid, mid in cur.execute('SELECT room_id, member_id FROM chatroom_member'):
+            members[int(rid)].add(int(mid))
+        return people, rooms, members
+    finally:
+        conn.close()
+
+
+def resolve(people, needle):
+    """按 wxid / 昵称 / 备注找一个人；返回 (id, 记录) 或 None。
+
+    **排除群**：`contact` 表里 `@chatroom` 也在，用 `--with 老表` 会先命中「老表亲戚群」
+    这个群而不是人（第一版就这么错），所以匹配人时跳过它们。
+    """
+    needle = (needle or '').strip()
+    if not needle:
+        return None
+    exact, fuzzy = [], []
+    for pid, p in people.items():
+        if p['username'].endswith('@chatroom'):
+            continue
+        fields = (p['name'], p['username'], p['nick'], p['remark'])
+        if needle == p['username']:
+            return pid, p
+        if any(needle == f for f in fields if f):
+            exact.append((pid, p))
+        elif any(needle in f for f in fields if f):
+            fuzzy.append((pid, p))
+    pool = exact or fuzzy
+    return pool[0] if pool else None
+
+
+def find_me(people, members, cfg):
+    """自己的 contact.id。
+
+    先按配置里的 wxid 找；**找不到就用"出现在最多群里的人"** —— 你在自己所有群里，
+    而 `contact` 表不一定收录自己（实测这里就没有），少了这个兜底，
+    「共同群」这类功能会直接退化成一列群名。
+    """
+    wxid = cfg.get('wxid') or ''
+    if wxid:
+        for pid, p in people.items():
+            if p['username'] == wxid:
+                return pid
+    counts = defaultdict(int)
+    for ids in members.values():
+        for pid in ids:
+            counts[pid] += 1
+    if counts:
+        pid, n = max(counts.items(), key=lambda kv: kv[1])
+        if n >= 3:
+            return pid
+    return None
+
+
+def rooms_of(members, pid):
+    return {rid for rid, ids in members.items() if pid in ids}
+
+
+def cmd_groups(people, rooms, members):
+    rows = []
+    for rid, info in rooms.items():
+        ids = members.get(rid, set())
+        rows.append({'room': info['name'], 'members': len(ids)})
+    rows.sort(key=lambda r: -r['members'])
+    print(f'共 {len(rows)} 个群\n')
+    for r in rows[:30]:
+        print(f"  {r['members']:>4} 人  {r['room']}")
+    if len(rows) > 30:
+        print(f'  …还有 {len(rows)-30} 个')
+
+
+def cmd_with(people, rooms, members, needle, cfg):
+    me_id = find_me(people, members, cfg)
+    me = (me_id, people.get(me_id, {})) if me_id else None
+    target = resolve(people, needle)
+    if not target:
+        raise SystemExit(f'没找到「{needle}」')
+    tid, tinfo = target
+    t_rooms = rooms_of(members, tid)
+    print(f"目标：{tinfo['name']}（{tinfo['username']}）在 {len(t_rooms)} 个群")
+    if not me:
+        print('（配置里没有自己的 wxid，跳过共同群计算）')
+        for rid in sorted(t_rooms):
+            print(f"  · {rooms[rid]['name']}")
+        return
+    my_rooms = rooms_of(members, me[0])
+    common = t_rooms & my_rooms
+    print(f"你们共同在 {len(common)} 个群：")
+    for rid in sorted(common):
+        print(f"  · {rooms[rid]['name']}（{len(members.get(rid, []))} 人）")
+    if not common:
+        print('  （没有共同群）')
+
+
+def cmd_intro(people, rooms, members, needle, cfg, top=8):
+    me_id = find_me(people, members, cfg)
+    me = (me_id, people.get(me_id, {})) if me_id else None
+    target = resolve(people, needle)
+    if not target:
+        raise SystemExit(f'没找到「{needle}」')
+    tid, tinfo = target
+    if not me:
+        raise SystemExit('配置里没有自己的 wxid，算不了引荐路径')
+    my_rooms = rooms_of(members, me[0])
+    t_rooms = rooms_of(members, tid)
+
+    # 候选人 = 同时在我和目标的群里的人；分数 = 交集群数，其次是他和目标最近的共同群大小
+    scores = defaultdict(lambda: {'rooms': set()})
+    for rid in my_rooms & t_rooms:
+        for pid in members.get(rid, set()):
+            if pid in (me[0], tid):
+                continue
+            scores[pid]['rooms'].add(rid)
+    if not scores:
+        print(f'你和「{tinfo["name"]}」不在同一个群，也没有共同的联系人可引荐')
+        return
+    ranked = sorted(scores.items(), key=lambda kv: -len(kv[1]['rooms']))
+    print(f"想认识「{tinfo['name']}」，这些人同时和你们在一个群：\n")
+    for pid, info in ranked[:top]:
+        p = people.get(pid, {})
+        shared = '、'.join(rooms[r]['name'] for r in list(info['rooms'])[:3])
+        print(f"  {p.get('name') or p.get('username')}  共同群 {len(info['rooms'])} 个：{shared}")
+
+
+def main():
+    ap = argparse.ArgumentParser(description='人脉图谱：共同群与引荐路径')
+    ap.add_argument('--groups', action='store_true', help='群概览')
+    ap.add_argument('--with', dest='with_who', default='', help='我和他共同在哪些群')
+    ap.add_argument('--intro', default='', help='谁能把我介绍给他')
+    ap.add_argument('--json', action='store_true')
+    args = ap.parse_args()
+
+    cfg = load_config()
+    people, rooms, members = load_graph(cfg)
+    if args.groups:
+        cmd_groups(people, rooms, members)
+    elif args.with_who:
+        cmd_with(people, rooms, members, args.with_who, cfg)
+    elif args.intro:
+        cmd_intro(people, rooms, members, args.intro, cfg)
+    else:
+        ap.print_help()
+
+
+if __name__ == '__main__':
+    main()

package/scripts/on_this_day.py

@@ -0,0 +1,178 @@
+"""「那年今日」：把几年前的今天你在聊什么捞出来。
+
+为什么只有本地全量数据能做到：微信的搜索只覆盖当前会话、而且历史一长就翻不动；
+这里直接按 `create_time` 扫所有分片里的每一张会话表，所以"五年前的今天"是能查的。
+
+用法：
+    python scripts/on_this_day.py                     # 1 / 3 / 5 年前的今天
+    python scripts/on_this_day.py --years 2,4,6
+    python scripts/on_this_day.py --talker 老表亲戚群   # 只看某个会话
+    python scripts/on_this_day.py --json
+"""
+from __future__ import annotations
+
+import argparse
+import re
+import json
+import pathlib
+import sys
+import time
+from collections import Counter, defaultdict
+from datetime import datetime, timezone, timedelta
+
+SCRIPT_DIR = pathlib.Path(__file__).resolve().parent
+sys.path.insert(0, str(SCRIPT_DIR))
+
+from _utils import load_config, decrypt_lock  # noqa: E402
+import nt_decrypt as nd  # noqa: E402
+
+TZ = timezone(timedelta(hours=8))
+DEFAULT_YEARS = (1, 3, 5)
+
+
+def _keys(cfg):
+    key = decrypt_lock(cfg.get('ntKey', '') or '')
+    salt = decrypt_lock(cfg.get('ntSalt', '') or '')
+    pw = decrypt_lock(cfg.get('favPassphrase', '') or cfg.get('decryptKey', '') or '')
+    return key, salt, pw
+
+
+def _text_of(content, local_type=0):
+    """消息正文 → 一行字。
+
+    **不能只看 `message_content` 是不是以 `<` 开头**：appmsg 那一族（链接/文件/小程序）
+    的内容是 zstd 压缩的二进制，原样打出来就是 `(/`$` 这种碎片（第一版就是这么翻车的）。
+    这里直接复用 `nt_decrypt` 里那套已经处理过压缩、类型标签与引用消息的显示层。
+    """
+    lt = int(local_type or 0)
+    base = lt & 0xFFFFFFFF
+    if base == 1:                      # 纯文本
+        text = nd._decode_content(content)
+        text = ' '.join(str(text).split())[:120]
+        # 群消息的 `message_content` 自带 `wxid_xxx: ` 前缀，而发言人已经在左边显示了一次
+        return re.sub(r'^[A-Za-z0-9_\-]+@?(chatroom|openim)?\s*:\s*', '', text)[:120]
+    try:
+        out = nd.non_text_display(lt, content)[:120]
+        return re.sub(r'^[A-Za-z0-9_\-]+:\s*', '', out)[:120]
+    except Exception:
+        return ''
+
+
+def day_bounds(dt):
+    start = datetime(dt.year, dt.month, dt.day, tzinfo=TZ)
+    return int(start.timestamp()), int((start + timedelta(days=1)).timestamp())
+
+
+def collect_for_day(conns, name_map, target_day, talker_filter=''):
+    """{talker: [(ts, sender, text), ...]} for one calendar day."""
+    start, end = day_bounds(target_day)
+    out = defaultdict(list)
+    for conn in conns:
+        c = conn.cursor()
+        try:
+            c.execute('SELECT user_name FROM Name2Id WHERE is_session = 1')
+            sessions = [r[0] for r in c.fetchall() if r[0]]
+        except Exception:
+            continue
+        # `real_sender_id` 是 **Name2Id 的 rowid**，不是 wxid —— 少这一步映射，
+        # 输出里发言人就全是 `65`、`4`、`8` 这样的数字（第一版就是这样）。
+        try:
+            c.execute('SELECT rowid, user_name FROM Name2Id')
+            sender_map = {r[0]: r[1] for r in c.fetchall()}
+        except Exception:
+            sender_map = {}
+        for talker in sessions:
+            if talker_filter and talker_filter not in (talker, name_map.get(talker, talker)):
+                continue
+            tbl = f'Msg_{__import__("hashlib").md5(talker.encode()).hexdigest()}'
+            try:
+                c.execute('SELECT COUNT(*) FROM sqlite_master WHERE name=?', (tbl,))
+                if c.fetchone()[0] == 0:
+                    continue
+                c.execute(f'SELECT create_time, real_sender_id, local_type, message_content '
+                          'FROM "{0}" WHERE create_time >= ? AND create_time < ? ORDER BY create_time'.format(tbl),
+                          (start, end))
+                for ts, sender, ltype, content in c.fetchall():
+                    text = _text_of(content, ltype)
+                    if text:
+                        who = sender_map.get(sender, '')
+                        out[name_map.get(talker, talker)].append(
+                            (int(ts), name_map.get(who, who), text))
+            except Exception:
+                continue
+    return out
+
+
+def main():
+    ap = argparse.ArgumentParser(description='那几年的今天你在聊什么')
+    ap.add_argument('--years', default=','.join(str(y) for y in DEFAULT_YEARS),
+                    help='往前看几年，逗号分隔（默认 1,3,5）')
+    ap.add_argument('--talker', default='', help='只看某个会话（wxid 或昵称）')
+    ap.add_argument('--limit', type=int, default=6, help='每天最多列几条（默认 6）')
+    ap.add_argument('--json', action='store_true')
+    args = ap.parse_args()
+
+    cfg = load_config()
+    db = cfg.get('ntDbPath') or ''
+    if not db:
+        raise SystemExit('配置里没有 ntDbPath，先跑 weflow-cli init')
+    key, salt, pw = _keys(cfg)
+    conns = nd.connect_message_shards(db, key, salt, pw)
+    if not conns:
+        raise SystemExit('打不开任何消息分片')
+
+    try:
+        # 联系人在 **contact.db**，不在消息库里 —— 从消息库找 `contact` 表一定落空，
+        # 输出里就只剩 `47966561144@chatroom` 和 `wxid_xxx`（第一版就是这样）。
+        name_map = {}
+        try:
+            from network import load_graph
+            people, _rooms, _members = load_graph(cfg)
+            name_map = {p['username']: (p['remark'] or p['nick'] or p['username'])
+                        for p in people.values()}
+        except Exception as exc:
+            print(f'[WARN] 读联系人失败（{type(exc).__name__}: {exc}），下面显示 id',
+                  file=sys.stderr)
+
+        today = datetime.now(TZ)
+        years = [int(y) for y in args.years.split(',') if y.strip().isdigit()]
+        result = []
+        for y in years:
+            try:
+                day = today.replace(year=today.year - y)
+            except ValueError:      # 2 月 29 日
+                day = today.replace(year=today.year - y, day=28)
+            by_talker = collect_for_day(conns, name_map, day, args.talker)
+            total = sum(len(v) for v in by_talker.values())
+            top = Counter({k: len(v) for k, v in by_talker.items()}).most_common(3)
+            picks = []
+            for talker, msgs in sorted(by_talker.items(), key=lambda kv: -len(kv[1]))[:3]:
+                for ts, sender, text in msgs[:max(1, args.limit // 3)]:
+                    picks.append({'talker': talker, 'time': datetime.fromtimestamp(ts, tz=TZ).strftime('%H:%M'),
+                                  'sender': sender, 'text': text})
+            result.append({'date': day.strftime('%Y-%m-%d'), 'yearsAgo': y,
+                           'total': total, 'threads': top, 'samples': picks[:args.limit]})
+    finally:
+        for conn in conns:
+            try:
+                conn.close()
+            except Exception:
+                pass
+
+    if args.json:
+        print(json.dumps({'success': True, 'days': result}, ensure_ascii=False, indent=2))
+        return
+
+    for item in result:
+        head = f"{item['date']}（{item['yearsAgo']} 年前的今天）"
+        if not item['total']:
+            print(f'\n{head}\n  那天没有聊天记录')
+            continue
+        threads = '、'.join(f'{n}({c})' for n, c in item['threads'])
+        print(f"\n{head}  {item['total']} 条  {threads}")
+        for s in item['samples']:
+            print(f"  {s['time']}  {s['talker']} · {s['sender'] or '?'}：{s['text']}")
+
+
+if __name__ == '__main__':
+    main()

package/scripts/opinion_timeline.py

@@ -0,0 +1,138 @@
+"""某个号的观点时间线：它这一年都说过什么，什么时候开始变了。
+
+日报每天把文章存成 `output/biz-daily/<date>/<topic>/*.md`（frontmatter 带 `source`、
+`date`，正文有 `## AI 摘要`），所以"这个号的观点怎么变"是可以按时间排出来的 ——
+而微信里你只能一篇篇点开、还没有横轴。
+
+用法：
+    python scripts/opinion_timeline.py --list                  # 哪些号存了多少篇
+    python scripts/opinion_timeline.py --source 某号      # 时间线
+    python scripts/opinion_timeline.py --source 某号 --months 3
+    python scripts/opinion_timeline.py --source 某号 --ai       # 让模型总结观点变化
+"""
+from __future__ import annotations
+
+import argparse
+import json
+import pathlib
+import re
+import sys
+from collections import defaultdict
+
+SCRIPT_DIR = pathlib.Path(__file__).resolve().parent
+sys.path.insert(0, str(SCRIPT_DIR))
+
+# 摘要复用日报那套清洗：原始文本是「【核心观点】…【关键细节】1.…」，直接打出来是噪音。
+from daily_mail import clean_summary as _clean  # noqa: E402
+
+ROOT = SCRIPT_DIR.parent
+DAILY_DIR = ROOT / 'output' / 'biz-daily'
+
+
+def parse_md(path):
+    """frontmatter + `## AI 摘要` 那一段。解析不出来就跳过，不让一篇坏文件毁掉整条时间线。"""
+    try:
+        text = path.read_text(encoding='utf-8')
+    except Exception:
+        return None
+    meta = {}
+    body = text
+    if text.startswith('---'):
+        end = text.find('\n---', 3)
+        if end > 0:
+            for line in text[3:end].splitlines():
+                if ':' in line:
+                    k, v = line.split(':', 1)
+                    meta[k.strip()] = v.strip().strip('"')
+            body = text[end + 4:]
+    summary = ''
+    m = re.search(r'##\s*AI 摘要\s*\n+(.+?)(?:\n#|\n---|$)', body, re.S)
+    if m:
+        summary = ' '.join(m.group(1).split())[:200]
+    return {
+        'title': meta.get('title', ''),
+        'source': meta.get('source', ''),
+        'date': meta.get('date', ''),
+        'relevance': meta.get('relevance', ''),
+        'topic': meta.get('topic', ''),
+        'url': meta.get('url', ''),
+        'summary': summary,
+    }
+
+
+def load_all():
+    """所有日期目录里的文章。"""
+    items = []
+    if not DAILY_DIR.is_dir():
+        return items
+    for day in sorted(DAILY_DIR.iterdir()):
+        if not day.is_dir():
+            continue
+        for md in day.rglob('*.md'):
+            rec = parse_md(md)
+            if rec and rec['source']:
+                items.append(rec)
+    return items
+
+
+def main():
+    ap = argparse.ArgumentParser(description='某个号的观点时间线')
+    ap.add_argument('--source', default='', help='公众号名（子串匹配）')
+    ap.add_argument('--months', type=int, default=0, help='只看最近 N 个月（0 = 全部）')
+    ap.add_argument('--limit', type=int, default=30, help='最多列几篇（默认 30，最近的在前）')
+    ap.add_argument('--list', action='store_true', help='列出存了哪些号、各多少篇')
+    ap.add_argument('--ai', action='store_true', help='让模型总结观点变化（要 API key）')
+    ap.add_argument('--json', action='store_true')
+    args = ap.parse_args()
+
+    items = load_all()
+    if not items:
+        raise SystemExit(f'{DAILY_DIR} 下没有可解析的文章')
+
+    if args.list:
+        counter = defaultdict(int)
+        for it in items:
+            counter[it['source']] += 1
+        rows = sorted(counter.items(), key=lambda kv: -kv[1])
+        print(f'共 {len(rows)} 个号，{len(items)} 篇\n')
+        for name, n in rows[:40]:
+            print(f'  {n:>4} 篇  {name}')
+        return
+
+    if not args.source:
+        ap.print_help()
+        return
+
+    picked = [it for it in items if args.source in it['source']]
+    if not picked:
+        raise SystemExit(f'没有匹配「{args.source}」的文章；用 --list 看有哪些号')
+    picked.sort(key=lambda x: x['date'], reverse=True)
+    if args.limit and args.limit > 0:
+        picked = picked[:args.limit]
+
+    dates = sorted({it['date'] for it in picked})
+    print(f"{picked[0]['source']}：{len(picked)} 篇，{dates[0]} ~ {dates[-1]}\n")
+    for it in picked:
+        rel = f"（{it['relevance']}）" if it['relevance'] else ''
+        print(f"{it['date']}  {it['title'][:60]}{rel}")
+        if it['summary']:
+            print(f"    {_clean(it['summary'], 160)}")
+
+    if args.ai:
+        from _utils import load_config, get_api_key, call_ai
+        api_key = get_api_key(load_config())
+        if not api_key:
+            print('\n[WARN] 没有可用的 API key，跳过观点总结', file=sys.stderr)
+            return
+        lines = [f"{it['date']} {it['title']}：{it['summary']}" for it in picked][-40:]
+        prompt = (
+            f"下面是同一个公众号「{picked[0]['source']}」按时间排列的文章与要点。\n"
+            '请用中文回答：它的关注点或立场有没有随时间变化？如果有，指出从什么变成什么，'
+            '并给出对应的日期作为证据；如果没有明显变化，就说明它一直关注什么。'
+            '不要罗列所有篇目，不要空话。\n\n' + '\n'.join(lines))
+        print('\n--- 观点变化（AI 总结）---')
+        print(call_ai(prompt, 'deepseek', api_key, max_tokens=800))
+
+
+if __name__ == '__main__':
+    main()