weflow-cli 1.6.0 → 1.6.2

package/docs/RELEASING.md

@@ -0,0 +1,177 @@
+# 发布清单
+
+npm 包与 GitHub 分开发布，中间隔多久都不奇怪——`1.5.0` 与主线之间曾拉开 128 个提交、
+两个多月，直接导致用户照着 README 敲 `init --path` 却报 `unknown option`。
+
+按下面顺序走，每一步都有对应的**失败长什么样**。
+
+## 1. 定版本号
+
+按语义化版本，不是按「改了多少行」：
+
+| 改动性质 | 升哪一位 | 例 |
+| --- | --- | --- |
+| 新功能、新命令、新参数 | **minor** | 1.5.0 → 1.6.0 |
+| 只修 bug、只改文档 | patch | 1.6.0 → 1.6.1 |
+| 破坏兼容 | major | 1.6.0 → 2.0.0 |
+
+已备好但**从未发布**的版本号可以并进下一个：`1.5.1` 准备过却没发，
+它的修复就直接并进了 `1.6.0`。
+
+## 2. 整理 CHANGELOG
+
+- 把 `## Unreleased` 改名为 `## <新版本号>`
+- 若上一版已写好但没发布，把它的条目并入，删掉那个空段
+- 通用说明（如「npm 与 GitHub 分开发布」）移到文件顶部，别留在版本段里
+
+## 3. 构建与测试
+
+```powershell
+npm run build
+npm test
+```
+
+## 4. 打包检查（**不能跳过**）
+
+```powershell
+npm pack --dry-run
+```
+
+本地常有 `output/`（几 GB 产出）、`models/`（几 GB 模型）、`_env.json`（含密钥）
+这类东西。`package.json` 的 `files` 是白名单，理论上挡住——但**白名单也可能写漏**，
+所以逐项确认：
+
+```powershell
+npm pack --dry-run 2>&1 | grep -E "npm notice [0-9]" > /tmp/list.txt
+grep -E "^output/|^models/|node_modules|\.env|\.db$|\.dat$|secret|credential" /tmp/list.txt
+```
+
+**这条命令必须没有输出。** 有输出就停下来查。
+
+同时确认新增文件确实**在**包里（白名单是按目录配的，容易漏）：
+
+```powershell
+grep -E "新文件名" /tmp/list.txt
+```
+
+## 5. 发布
+
+需要 npm 凭据。`ribiaosu` 账号开了 2FA，所以两条路：
+
+**凭据（推荐，一次配置长期可用）** — 用**带 `Bypass 2FA` 的 Granular Access Token**，
+在 https://www.npmjs.com/settings/ribiaosu/tokens 生成时**必须勾选那个框**。
+漏勾的 token 会在发布时报 `403 ... bypass 2fa enabled is required`。
+
+| 现象 | 原因 |
+| --- | --- |
+| `403 ... two-factor authentication ... required` | token 没勾 Bypass 2FA，或没用 OTP |
+| `ENEEAUTH` | 没登录 / 没配 token |
+
+**验证 token 是否可用**（`bypass_2fa` 必须是 `true`）：
+
+```powershell
+curl -s -H "Authorization: Bearer <token>" https://registry.npmjs.org/-/npm/v1/tokens
+```
+
+**一次性验证码**：
+
+```powershell
+npm publish --otp=<6位码>
+```
+
+## 6. 触发国内镜像同步（**新加的必要步骤**）
+
+国内用户大多用 `registry.npmmirror.com`（淘宝源），它对新版本有同步延迟。
+不同步的话，发布后几个小时内会有人来提「版本不存在」的 issue——
+`weflow-cli@1.6.0` 就这样被报过一次（Issue #8）。
+
+```powershell
+curl -X PUT https://registry.npmmirror.com/-/package/weflow-cli/syncs
+```
+
+返回 `{"ok":true,...,"state":"waiting"}` 即已受理。**约 5 分钟后**生效。
+
+## 7. 验证两个源都是新版本
+
+```powershell
+npm view weflow-cli version --registry=https://registry.npmjs.org
+npm view weflow-cli version --registry=https://registry.npmmirror.com
+```
+
+两个都要是新版本号才对外宣告。官方源发布后自身也有几分钟 CDN 传播延迟——
+期间 `npm view` 可能显示旧版本、tarball 可能 404，**这是在传播，不是失败**。
+用这个判断是否真的发出去了：
+
+```powershell
+npm publish    # 再发一次
+```
+
+报 `409 Conflict - Cannot publish over previously staged version` → **已经发布成功**。
+
+## 8. 兜底：告诉用户怎么绕开镜像
+
+```powershell
+npm config get registry                                            # 看用的哪个源
+npm view weflow-cli version --registry=https://registry.npmjs.org  # 用官方源查
+```
+
+两个源结果不一致 → 是镜像同步问题，不是包的问题：
+`npm install -g weflow-cli@<版本> --registry=https://registry.npmjs.org` 立刻可用。
+
+## 发布后
+
+- 回到相关 issue 回复「已发布 + 升级方式」
+- GitHub Release 与本清单解耦：源码、编译包、npm 三者版本差异要对用户可见
+
+### 回复用户的规矩
+
+报障的人多半不是开发者，也不看长文。**回复写给用户，不是写给同事：**
+
+- **先给出结论和做法**（已修复 / 升级到 x.y.z），技术细节不要写进回复
+- **三五句话说完**。根因分析、代码片段、执行顺序论证属于 commit message 和
+  本文档，不属于 issue 回复
+- 升级类回复直接给命令，别让人自己找
+- **发出前先给维护者过目**，确认后再发
+
+反面例子：一条回复里贴了 Python 代码片段和逐步的执行顺序分析，内容全对，
+但给用户的感受是「看不懂、太长」。
+
+### 新动态邮件提醒
+
+`scripts/watch_issues.py` 轮询本仓库的 issue 与回复，有非维护者发言时发邮件。
+由 Windows 计划任务 `WeFlow Issue Watch` 每 30 分钟调用一次，不依赖任何编辑器
+或 Claude 会话处于打开状态。
+
+邮件凭据放在仓库外，不进版本库：
+
+```json
+// ~/.weflow-issue-watch.json   （QQ 邮箱需用「授权码」，不是登录密码）
+{
+  "smtp_user": "1473517806@qq.com",
+  "smtp_auth": "<授权码>",
+  "mail_to":   "1473517806@qq.com",
+  "repo":      "zhuobichen/weflow-cli"
+}
+```
+
+- 首次运行只记录基线、不发信，避免把历史 issue 一次性全发出去
+- 发送失败不推进记录，下次自动重试
+- 手动跑一次：`py scripts/watch_issues.py`
+- 查看/改频率：`Get-ScheduledTask -TaskName 'WeFlow Issue Watch'`
+
+### 发布后自检
+
+```powershell
+npm view weflow-cli version --registry=https://registry.npmjs.org
+npm view weflow-cli version --registry=https://registry.npmmirror.com
+```
+
+两个源都是新版本，再对外说「已发布」。
+
+然后跑一遍体检，确认这次改动没有把读取路径或某个导出格式弄坏：
+
+```powershell
+py scripts/health_check.py
+```
+
+退出码 `0` 才算干净。检查项与各自的由来见 [HEALTH-CHECK.md](HEALTH-CHECK.md)。

package/package.json

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

package/scripts/biz_daily.py

@@ -194,9 +194,11 @@ def get_db_keys(config):
                 bytes.fromhex(biz_salt), 256000, dklen=32
             ).hex()
         if not biz_key:
+            # 只指向 passphrase 一条路: 早先还建议 `config set bizKey`, 但该键不在
+            # CLI 的可写白名单里, 照做必然报 INVALID_CONFIG_KEY。
             raise SystemExit(
                 '缺少公众号数据库密钥: 请运行 weflow-cli fav set-key --passphrase <64位hex> '
-                '配置全库 passphrase (自动派生各库密钥), 或 weflow-cli config set bizKey <raw key>'
+                '配置全库 passphrase (自动派生各库密钥)'
             )
 
     return {

package/scripts/export_chat_html.py

@@ -2121,6 +2121,8 @@ def main():
     parser.add_argument('--per-page', type=int, default=0,
                         help='Messages per file; overrides --parts. Keeps a long history snappy to open')
     parser.add_argument('--date', default=os.environ.get('WEFLOW_EXPORT_DATE', ''), help='Only export messages from local date YYYY-MM-DD')
+    parser.add_argument('--limit', type=int, default=int(os.environ.get('WEFLOW_EXPORT_LIMIT') or 0),
+                        help='Only export the most recent N messages (0 = all)')
     parser.add_argument('--emoticon-seed', default=os.environ.get('WEFLOW_EMOTICON_SEED', ''),
                         help='Account seed; decrypts custom stickers from the local cache')
     parser.add_argument('--passphrase', default=os.environ.get('WEFLOW_NT_PASSPHRASE', ''), help='Shared NT passphrase for deriving shard keys')
@@ -2220,6 +2222,13 @@ def main():
     _phase("before fetch")
     messages = fetch_messages_from_shards(args.db, args.key, args.salt, args.talker, args.date, args.passphrase)
 
+    # `--limit` means the most recent N, the same as `messages` and
+    # `export json`. Sliced here, before the media and sender maps are built,
+    # so neither does work for messages that are about to be dropped.
+    if args.limit and args.limit > 0 and len(messages) > args.limit:
+        print(f"Limiting to the most recent {args.limit} of {len(messages)} messages")
+        messages = messages[-args.limit:]
+
     if not messages:
         if args.date:
             file_prefix = sanitize_filename(args.name or args.talker)

package/scripts/health_check.py

@@ -0,0 +1,336 @@
+#!/usr/bin/env python3
+"""Periodic health check for weflow-cli.
+
+A pure script - no model, no tokens. Every check here exists because that exact
+thing has silently broken at least once, and the failure was invisible:
+
+  版本一致        1.6.0 自报 1.5.1, so "which build am I running" was unanswerable
+  读取路径一致    只读 message_0.db 时, export json 有 31 条而 export html 有 1145 条
+  会话新鲜度      同上, 会话列表停在 18 天前而命令仍然"成功"
+  导出格式         excel 全程从未成功过, 报错只有"导出失败"四个字
+  Python 依赖     缺 sqlcipher3 时命令报的是"数据库连接失败"
+  计划任务        提醒脚本静默停跑, 没人会发现
+
+Run it ad hoc, or schedule it and read the summary line:
+
+    py scripts/health_check.py
+    py scripts/health_check.py --json
+
+Exit code is 0 only when every check passes, so a scheduler can act on it.
+"""
+import argparse
+import datetime
+import json
+import os
+import shutil
+import subprocess
+import sys
+import tempfile
+import time
+from pathlib import Path
+
+ROOT = Path(__file__).resolve().parent.parent
+CLI = ROOT / 'cli.cjs'
+
+# Windows consoles default to a legacy codepage that cannot encode the report.
+for _stream in (sys.stdout, sys.stderr):
+    try:
+        _stream.reconfigure(encoding='utf-8', errors='replace')
+    except (AttributeError, ValueError):
+        pass
+
+# Each check shells out to the CLI, which takes seconds; keep the sample small.
+SAMPLE_LIMIT = 5
+TIMEOUT = 300
+
+# A session list that has not moved in this long means reads are stale. WeChat
+# is not chatty for everyone, so this is deliberately generous.
+STALE_SESSION_DAYS = 7
+
+
+def run(args, timeout=TIMEOUT):
+    """(returncode, stdout, stderr) with Node's experimental warning suppressed."""
+    env = {**os.environ, 'NODE_NO_WARNINGS': '1', 'PYTHONIOENCODING': 'utf-8'}
+    try:
+        proc = subprocess.run(
+            ['node', str(CLI), *args], capture_output=True, timeout=timeout,
+            encoding='utf-8', errors='replace', env=env, cwd=str(ROOT))
+    except (OSError, subprocess.SubprocessError) as error:
+        return 1, '', f'{type(error).__name__}: {error}'
+    return proc.returncode, proc.stdout or '', proc.stderr or ''
+
+
+def run_json(args):
+    """Parsed JSON payload, or None.
+
+    The CLI pretty-prints, so the payload spans many lines - parse from the
+    first brace rather than looking for a single-line blob.
+    """
+    code, out, _ = run([*args, '--json'])
+    start = out.find('{')
+    if start < 0:
+        return code, None
+    try:
+        return code, json.JSONDecoder().raw_decode(out[start:])[0]
+    except ValueError:
+        return code, None
+
+
+class Report:
+    def __init__(self):
+        self.rows = []
+
+    def add(self, name, ok, detail, hint=''):
+        self.rows.append({'name': name, 'ok': bool(ok), 'detail': detail, 'hint': hint})
+
+    @property
+    def failed(self):
+        return [r for r in self.rows if not r['ok']]
+
+    def render(self):
+        stamp = datetime.datetime.now().strftime('%Y-%m-%d %H:%M')
+        lines = [f'WeFlow 健康检查 · {stamp}', '']
+        width = max(len(r['name']) for r in self.rows) + 2
+        for row in self.rows:
+            mark = 'OK  ' if row['ok'] else 'FAIL'
+            lines.append(f'[{mark}] {row["name"]:<{width}}{row["detail"]}')
+            if not row['ok'] and row['hint']:
+                lines.append(f'{"":<7}{"":<{width}}↳ {row["hint"]}')
+        lines.append('')
+        if self.failed:
+            lines.append(f'{len(self.rows) - len(self.failed)} 项通过 / {len(self.failed)} 项失败')
+        else:
+            lines.append(f'全部通过（{len(self.rows)} 项）')
+        return '\n'.join(lines)
+
+
+def check_version(report):
+    """The CLI must report the version it actually is."""
+    try:
+        declared = json.loads((ROOT / 'package.json').read_text(encoding='utf-8'))['version']
+    except (OSError, ValueError, KeyError) as error:
+        report.add('版本一致', False, f'读不到 package.json ({type(error).__name__})')
+        return
+    code, out, _ = run(['--version'])
+    reported = out.strip().split('\n')[-1].strip() if out.strip() else ''
+    report.add('版本一致', code == 0 and reported == declared,
+               f'CLI {reported or "?"} / package {declared}',
+               '两者不一致说明 --version 又写死了，或 dist 未重新构建')
+
+
+def check_environment(report):
+    """Environment self-check: config present, Python deps importable."""
+    _, data = run_json(['check'])
+    if not data:
+        report.add('环境自检', False, 'check 未返回 JSON', '先跑 weflow-cli check 看原始输出')
+        return
+    config = data.get('configuration') or {}
+    deps = ((data.get('dependencies') or {}).get('required') or {})
+    missing = [name for name, status in deps.items() if not status]
+    ok = bool(config.get('initialized')) and bool(config.get('messageDatabase')) and not missing
+    detail = f'已初始化={config.get("initialized")} 消息库={config.get("messageDatabase")}'
+    if missing:
+        detail += f' 缺依赖={",".join(missing)}'
+    report.add('环境自检', ok, detail,
+               '缺依赖: pip install -r requirements.txt；未初始化: weflow-cli init')
+
+
+def pick_talkers(report):
+    """The most recently active sessions - the likeliest to span shards."""
+    _, data = run_json(['sessions', '--limit', str(SAMPLE_LIMIT)])
+    sessions = ((data or {}).get('sessions') or [])
+    if not sessions:
+        report.add('选择样本会话', False, '会话列表为空', '先确认微信已登录且 init 成功')
+        return []
+    ordered = sorted(sessions, key=lambda s: s.get('sortTimestamp') or 0, reverse=True)
+    return [s['username'] for s in ordered[:2] if s.get('username')]
+
+
+def check_read_paths(report, talker):
+    """`export json` and `export html` read the same chat by different code.
+
+    They disagreed by 1114 messages when the JSON path read only the first
+    shard, so comparing their newest message is the cheapest way to notice the
+    read paths drifting apart again.
+    """
+    with tempfile.TemporaryDirectory(prefix='wf-health-') as tmp:
+        out_json = Path(tmp) / 'json'
+        code_j, err_j = run(['export', talker, 'json', '--limit', '5',
+                             '--output', str(out_json), '--non-interactive'])[0::2]
+        newest_json = None
+        for path in out_json.glob('*.json'):
+            try:
+                rows = json.loads(path.read_text(encoding='utf-8'))
+            except (OSError, ValueError):
+                continue
+            times = [int(r.get('createTime') or 0) for r in rows]
+            if times:
+                newest_json = max(times)
+                break
+
+        out_html = Path(tmp) / 'html'
+        code_h, out_h, _ = run(['export', talker, 'html', '--limit', '5',
+                                '--output', str(out_html), '--non-interactive'])
+        total_html = None
+        for line in out_h.split('\n'):
+            line = line.strip()
+            if line.startswith('Total:') and 'messages' in line:
+                try:
+                    total_html = int(line.split()[1])
+                except (IndexError, ValueError):
+                    pass
+        # Read the pages while the temp directory still exists.
+        newest_html = html_newest_stamp(out_html)
+
+    label = f'读取路径一致 ({talker[:14]}…)'
+    if newest_json is None:
+        report.add(label, False, 'json 导出没有产出可比对的消息',
+                   'export json 失败时先单独跑一次看报错')
+        return
+    if total_html is None:
+        report.add(label, False, 'html 导出没有报告条数',
+                   'export html 失败时先单独跑一次看报错')
+        return
+
+    newest_txt = datetime.datetime.fromtimestamp(newest_json).strftime('%Y-%m-%d %H:%M')
+    if newest_html:
+        match = newest_html[:16] == newest_txt
+        report.add(label, match,
+                   f'json 最新 {newest_txt} / html 最新 {newest_html}',
+                   '两条路径读到不同的最新消息，通常又只剩一个分片被读了')
+    else:
+        # No timestamp in the page (empty chat); the count comparison still holds.
+        report.add(label, total_html > 0, f'json 最新 {newest_txt} / html 共 {total_html} 条')
+
+
+def html_newest_stamp(out_dir):
+    """Newest 'YYYY-MM-DD HH:MM:SS' stamp rendered into the exported pages."""
+    import re
+    newest = ''
+    try:
+        for page in sorted(Path(out_dir).glob('*.html')):
+            text = page.read_text(encoding='utf-8', errors='replace')
+            stamps = re.findall(r'\d{4}-\d{2}-\d{2} \d{2}:\d{2}:\d{2}', text)
+            if stamps and stamps[-1] > newest:
+                newest = stamps[-1]
+    except OSError:
+        pass
+    return newest
+
+
+def check_session_freshness(report):
+    """A read path that silently stops at an old shard shows up here first."""
+    _, data = run_json(['sessions', '--limit', '5'])
+    sessions = ((data or {}).get('sessions') or [])
+    stamps = [s.get('sortTimestamp') or 0 for s in sessions]
+    if not stamps or not max(stamps):
+        report.add('会话新鲜度', False, '会话列表没有时间戳', 'init 可能未完成')
+        return
+    newest = max(stamps)
+    age = (time.time() - newest) / 86400
+    when = datetime.datetime.fromtimestamp(newest).strftime('%Y-%m-%d %H:%M')
+    report.add('会话新鲜度', age <= STALE_SESSION_DAYS,
+               f'最新会话 {when}（{age:.1f} 天前）',
+               f'超过 {STALE_SESSION_DAYS} 天未更新，通常意味着读取只覆盖了部分分片')
+
+
+def check_export_formats(report, talker):
+    """json / txt / excel must each produce a file. html is covered above."""
+    with tempfile.TemporaryDirectory(prefix='wf-health-') as tmp:
+        for fmt, pattern in (('json', '*.json'), ('txt', '*.txt'), ('excel', '*.xlsx')):
+            out = Path(tmp) / fmt
+            code, stdout, stderr = run(['export', talker, fmt, '--limit', '3',
+                                        '--output', str(out), '--non-interactive'])
+            produced = list(out.glob(pattern)) if out.exists() else []
+            size = produced[0].stat().st_size if produced else 0
+            detail = f'{size} 字节' if produced else (stderr.strip().split('\n')[-1][:60] or f'exit {code}')
+            report.add(f'导出格式 {fmt}', code == 0 and size > 0, detail)
+
+
+def check_python_deps(report):
+    """The NT reader is a Python subprocess; a missing module looks like a DB error."""
+    required = {
+        'sqlcipher3': 'sqlcipher3',
+        'html2text': 'html2text',
+        'zstandard': 'zstandard',
+        'cryptography': 'cryptography',
+    }
+    missing = []
+    for module, package in required.items():
+        try:
+            __import__(module)
+        except ImportError:
+            missing.append(package)
+    report.add('Python 依赖', not missing,
+               '齐全' if not missing else f'缺 {", ".join(missing)}',
+               'pip install -r requirements.txt')
+
+
+def check_scheduled_tasks(report):
+    """The watcher tasks must exist and their last run must have succeeded."""
+    if os.name != 'nt':
+        report.add('计划任务', True, '非 Windows，跳过')
+        return
+    if not shutil.which('schtasks'):
+        report.add('计划任务', True, '找不到 schtasks，跳过')
+        return
+    names = ['WeFlow Issue Watch', 'WeFlow Mail Watch']
+    broken, absent = [], []
+    for name in names:
+        try:
+            proc = subprocess.run(['schtasks', '/query', '/tn', name, '/fo', 'LIST', '/v'],
+                                  capture_output=True, timeout=60, encoding='utf-8', errors='replace')
+        except (OSError, subprocess.SubprocessError):
+            absent.append(name)
+            continue
+        if proc.returncode != 0:
+            absent.append(name)
+            continue
+        text = proc.stdout or ''
+        for line in text.split('\n'):
+            if 'Last Result' in line or '上次运行结果' in line:
+                result = line.split(':', 1)[-1].strip()
+                if result not in ('0', '0x0'):
+                    broken.append(f'{name}={result}')
+    if broken:
+        report.add('计划任务', False, f'上次运行失败: {", ".join(broken)}',
+                   '脚本可能抛异常了，手动跑一次看输出')
+    elif absent:
+        report.add('计划任务', False, f'不存在: {", ".join(absent)}',
+                   '提醒不会触发；见 docs/HEALTH-CHECK.md 的注册命令')
+    else:
+        report.add('计划任务', True, '均在位且上次成功')
+
+
+def main():
+    parser = argparse.ArgumentParser(description='weflow-cli periodic health check')
+    parser.add_argument('--json', action='store_true', help='机器可读输出')
+    args = parser.parse_args()
+
+    if not CLI.exists():
+        print(f'找不到 {CLI}', file=sys.stderr)
+        return 2
+
+    report = Report()
+    check_version(report)
+    check_environment(report)
+    check_python_deps(report)
+    check_session_freshness(report)
+
+    talkers = pick_talkers(report)
+    if talkers:
+        check_read_paths(report, talkers[0])
+        check_export_formats(report, talkers[0])
+
+    check_scheduled_tasks(report)
+
+    if args.json:
+        print(json.dumps({'success': not report.failed, 'checks': report.rows},
+                         ensure_ascii=False, indent=2))
+    else:
+        print(report.render())
+    return 1 if report.failed else 0
+
+
+if __name__ == '__main__':
+    sys.exit(main())