weflow-cli 1.9.0 → 1.11.0

package/scripts/biz_daily.py

@@ -212,19 +212,29 @@ def _group_by_topic(articles):
     return groups, fallbacks
 
 
-def _classify_with_jev(client, title, body, topics):
+def _classify_with_jev(client, title, body, topics, noise=None):
     """让 Jev 判断这一篇；**问不出来就返回 None**，由调用方逐篇退回老路。
 
     这里刻意吞掉异常（包括 `JevError` 之外的意外），因为"分类这一篇失败"
     不该让整天的日报挂掉。但异常类型会打出来——一个真的写错了的行号不该
     在日志里长得跟"网络抖了一下"一样。
+
+    `noise` 可选（见 `_classify_articles_parallel`）：把**同一条**失败折叠成一次输出。
+    一天上百篇全因同一个原因失败时（实测：判断层按地区不可用，HTTP 451），打上百行
+    等于没说；而**没见过的异常类型或没见过的消息仍然每次照打**——折叠的是重复，不是未知。
     """
     if client is None:
         return None
     try:
         return client.decide_article(title, body, topics)
     except Exception as error:
-        print(f'    [WARN] Jev 分类失败（{type(error).__name__}），本篇退回 LLM 解析：{error}')
+        signature = (type(error).__name__, str(error)[:200])
+        if noise is not None and signature in noise['seen']:
+            noise['repeat'] += 1
+        else:
+            if noise is not None:
+                noise['seen'].add(signature)
+            print(f'    [WARN] Jev 分类失败（{type(error).__name__}），本篇退回 LLM 解析：{error}')
         return None
 
 
@@ -284,9 +294,12 @@ def _classify_articles_parallel(articles, client, topics, workers=JEV_WORKERS):
 
     started = time.time()
     decisions = {}
+    # 同一条失败折叠成一次输出（见 `_classify_with_jev`）：一天上百篇同一个原因失败时，
+    # 逐篇刷同一行等于没说；但没见过的异常/消息仍然照打。
+    noise = {'seen': set(), 'repeat': 0}
     with ThreadPoolExecutor(max_workers=max(1, workers)) as pool:
         futures = {
-            pool.submit(_classify_with_jev, client, title, body, topics): index
+            pool.submit(_classify_with_jev, client, title, body, topics, noise): index
             for index, title, body in todo
         }
         for future in as_completed(futures):
@@ -296,6 +309,8 @@ def _classify_articles_parallel(articles, client, topics, workers=JEV_WORKERS):
     # 先报个数：并发之后逐篇日志没有意义了，但这三件事必须看得见。
     print(f'  分类完成 {ok}/{len(todo)} 篇，耗时 {time.time() - started:.1f}s'
           f'（{workers} 并发；串行约需 {len(todo) * 0.97:.0f}s）')
+    if noise['repeat']:
+        print(f'  [WARN] 另有 {noise["repeat"]} 篇因**同一条**失败被折叠（原因已在上面打过一次）')
     return decisions
 
 
@@ -473,13 +488,13 @@ def get_db_keys(config):
     contact_salt = config.get('contactSalt', '')
     contact_key = decrypt_lock(contact_key_enc) if contact_key_enc else ''
 
-    # biz_message_0.db（订阅号库）：钥匙派生统一在 `_utils.biz_message_db()`。
-    # 这块原来自己算了两遍（先按 bizKey/bizSalt，又被下面按 passphrase 派生的一遍覆盖），
-    # 两遍并存就是分叉留下的痕迹 —— 见那个函数的注释。
-    from _utils import biz_message_db
-    try:
-        biz_db, biz_key, biz_salt = biz_message_db(config)
-    except RuntimeError as exc:
+    # biz_message_0.db（订阅号库）：钥匙派生统一在 `_utils.biz_message_db()`。
+    # 这块原来自己算了两遍（先按 bizKey/bizSalt，又被下面按 passphrase 派生的一遍覆盖），
+    # 两遍并存就是分叉留下的痕迹 —— 见那个函数的注释。
+    from _utils import biz_message_db
+    try:
+        biz_db, biz_key, biz_salt = biz_message_db(config)
+    except RuntimeError as exc:
         raise SystemExit(str(exc))
 
     return {

package/scripts/chat_notes.py

@@ -42,8 +42,8 @@ from datetime import datetime, timedelta, timezone
 from pathlib import Path
 
 sys.path.insert(0, os.path.dirname(os.path.abspath(__file__)))
-from _utils import (CHAT_CARD_PREFIX, SEPARATOR, call_deepseek, decrypt_lock,  # noqa: E402
-                    get_api_key, load_config,
+from _utils import (CHAT_CARD_PREFIX, LinkNamer, SEPARATOR,  # noqa: E402
+                    call_deepseek, decrypt_lock, get_api_key, line_concepts_path, load_config,
                     note_path as _shared_note_path, plain, write_with_frontmatter)
 from reply_debt import collect_conversations, format_line  # noqa: E402
 
@@ -179,12 +179,15 @@ def parse_note(raw):
     }
 
 
-def render_note(note, name, days, updated, messages):
+def render_note(note, name, days, updated, messages, namer=None):
     """卡片 → (frontmatter, body)。
 
     frontmatter 的键是**消费者定的**：`compile_wiki.scan_articles` 读 `title`/`source`/`topic`/`tags`。
     body 的 `## AI 摘要` 标题也是它定的（`_extract_summary` 就找这一段）。
     """
+    # `namer` 由调用方按**库根**建好（`LinkNamer.for_out_dir(<库>/Chat/Concepts)`）：
+    # 这个脚本只管卡片，而"另一条线有哪些名字"要问库 —— 不传就按裸名字渲染（老行为）。
+    namer = namer or (lambda x: x)
     frontmatter = {
         'title': f'{name}',
         'type': 'chat-card',
@@ -212,7 +215,9 @@ def render_note(note, name, days, updated, messages):
                 continue
             parts.append('### %s\n' % label)
             for item in note[key]:
-                parts.append('- [[%s]] %s %s' % (item['name'], SEPARATOR, item['desc']))
+                # 跨线同名要带路径（`namer`，见 `_utils.LinkNamer`）：卡片里这个链接指的是
+                # **聊天线**那张概念页，而两条线同名时裸 `[[名字]]` 在 Obsidian 里是二义的。
+                parts.append('- [[%s]] %s %s' % (namer(item['name']), SEPARATOR, item['desc']))
             parts.append('')
     if note['owed']:
         parts.append('## 欠着什么\n')
@@ -501,6 +506,10 @@ def main():
         return 1
 
     updated = datetime.now(TZ).strftime('%Y-%m-%d %H:%M')
+    # 卡片里指向概念的链接要跨线消歧（两条线同名时带路径）。按**库根**建一次：
+    # 认不出线（自定义 `--vault-root`）时它回一个恒等函数 ⇒ 渲染成裸名字（老行为）。
+    chat_concepts = line_concepts_path('chat') or 'Chat/Concepts'
+    namer = LinkNamer.for_out_dir(Path(args.vault_root).joinpath(*chat_concepts.split('/')))
     written, failed = [], []
     for card in cards:
         prompt = build_note_prompt(card['name'], card['lines'], args.days)
@@ -521,7 +530,8 @@ def main():
             continue
         path = note_path(args.out, card['name'])
         path.parent.mkdir(parents=True, exist_ok=True)
-        frontmatter, body = render_note(note, card['name'], args.days, updated, card['messages'])
+        frontmatter, body = render_note(note, card['name'], args.days, updated, card['messages'],
+                                        namer=namer)
         write_with_frontmatter(str(path), frontmatter, body)
         written.append({'name': card['name'], 'file': str(path),
                         'topics': len(note['topics']), 'people': len(note['people'])})

package/scripts/check_readme_commands.py

@@ -0,0 +1,426 @@
+#!/usr/bin/env python3
+# -*- coding: utf-8 -*-
+"""**手写的命令面**必须在 CLI 里真实存在：README 的代码块 + `capabilities --json` 里的 `cli:` 串。
+
+`capabilities --json` 也在这一支里，因为它是**学这个项目的入口**（比 600 KB 的文档好读），而它的
+`cli:` 字段是**手写**的 —— 同一个输出里的 MCP 那半从真实注册表派生（`safety.mcpSurface.derivedFrom`），
+手写的那半同样会漂移。2026-10-11 量过：21 条 `cli:` 串、0 处对不上（准的），但准不等于有人盯着。
+
+
+为什么要有它：`1.5.0` 与主线之间曾拉开 128 个提交、两个多月，用户照着 README 敲
+`init --path` 得到 `unknown option` —— **文档漂移是用户先发现的那一类故障**，而仓库里
+原本没有任何东西盯着它（`test/pack-contents.test.ts` 管的是 npm 包里**有什么文件**，
+不是**命令面**）。
+
+判据取自真实 CLI，不复刻命令表：逐级问 `--help`，用输出里的 `Usage:` 行判断 commander
+实际解析到了哪一级。**不能看退出码** —— `--help` 会短路，`wiki <不存在的子命令> --help`
+照样打印 wiki 的帮助并 exit 0。第一版就是这么错的：`bad_path` 永远是 0，看着"全绿"，
+其实是那条判据从来没机会执行（同 `AGENTS.md` 的"负结论要配正对照"）。
+
+只扫**围栏代码块**里以 `weflow-cli` 开头的行。散文与表格里的提及不扫 —— 英文 README 里
+「Manage with `weflow-cli scene`, or bind…」的 `or` 会被当成子命令，那是假阳性。
+
+第三类**手写的命令面**：文档代码块里的 `python|py scripts/x.py --flag`。判据**不跑脚本**，
+用 AST 取 `add_argument('--x')` 当声明表 —— 仓库对 Python 脚本的既定纪律就是不 import 也不运行
+（`test/script_stdout_encoding_test.py` 头部写着原因：CI 的 python job 只装两个依赖，import 会假失败）。
+2026-10-11 量过：24 处文档调用、脚本全在、旗标全认。
+
+跑法：
+
+    npm run build                      # cli.cjs 依赖 dist/
+    python scripts/check_readme_commands.py
+    python scripts/check_readme_commands.py --self-test    # 正对照：证明判据是活的
+"""
+import argparse
+import ast
+import glob
+import json
+import os
+import re
+import shlex
+import subprocess
+import sys
+
+# 输出里会有中文与命令原文；手跑/重定向时 stdout 走本机编码（GBK）会 UnicodeEncodeError。
+# 这是 `test/script_stdout_encoding_test.py` 盯着的规矩，见 `docs/EXTENDING.md` Recipe E。
+sys.stdout.reconfigure(encoding='utf-8', errors='replace')
+
+ROOT = os.path.dirname(os.path.dirname(os.path.abspath(__file__)))
+FENCE = '`' * 3
+TOKEN_OK = re.compile(r'^[a-z][a-z0-9-]*$')
+FLAG = re.compile(r'^--?[A-Za-z][A-Za-z0-9-]*$')
+# 文档里的 Python 调用（`py -3 scripts/x.py --flag` 这种也认）。
+# 脚本名里**允许连字符**：第一版写成 `[\w.]+\.py`，于是 `scripts/no-such-script.py` 整条被静默跳过 ——
+# 变异检查里夹具写了 3 条、提取到 2 条才发现（"负结论要先排除假阴性"）。`--` 前缀的自由参数也认。
+PY_CALL = re.compile(r'\b(?:python|py)\s+(?:--?[\w-]+\s+)*scripts/([\w.-]+\.py)(.*)$')
+PY_FLAG = re.compile(r'(?<!\S)(--?[A-Za-z][A-Za-z0-9-]*)')
+
+
+def usage_path(help_text):
+    """这条帮助属于哪个命令 —— 从 `Usage:` 行取，直到第一个选项/占位符。"""
+    if not help_text:
+        return None
+    m = re.search(r'^Usage: weflow-cli\s*([^\n]*)', help_text, re.M)
+    if not m:
+        return None
+    out = []
+    for tok in m.group(1).split():
+        if tok.startswith(('-', '<', '[')):
+            break
+        out.append(tok)
+    return out
+
+
+def has_subcommands(help_text):
+    return bool(help_text) and bool(re.search(r'^\s*Commands:', help_text, re.M))
+
+
+def fenced_lines(text):
+    """围栏代码块里的每一行（围栏标记本身不算）：(行号, 行内容)。"""
+    out = []
+    fence = False
+    for lineno, line in enumerate(text.splitlines(), 1):
+        stripped = line.strip()
+        if stripped.startswith(FENCE):
+            fence = not fence
+            continue
+        if fence:
+            out.append((lineno, stripped))
+    return out
+
+
+def _body(stripped):
+    """去掉 `$ ` 提示符与行尾注释。"""
+    body = stripped[2:].strip() if stripped.startswith('$ ') else stripped
+    return re.split(r'\s+#', body)[0].strip()
+
+
+def command_lines(text):
+    """围栏代码块里的 `weflow-cli` 命令：(行号, 正文)。"""
+    return [(lineno, body) for lineno, stripped in fenced_lines(text)
+            if (body := _body(stripped)).startswith('weflow-cli ')]
+
+
+CLI_WRAPPER = re.compile(r'\b(?:npx\s+tsx|node)\s+\S*[\\/]?(?:cli\.cjs|weflow-cli\.ts)\s+(.*)$')
+
+
+def cli_wrapped_lines(text):
+    """**换了个写法的 CLI 调用**：`node cli.cjs capabilities --json` → [(行号, 'weflow-cli …')]。
+
+    文档里这种写法有几处（`docs/DEEPSEEK_V4_FLASH施工文档.md`、`docs/RELEASING.md`），它们的命令与
+    旗标和 `weflow-cli …` 是同一套东西，所以用同一个判据（CLI 自己的 `--help`）来验 —— 此前它们
+    **一条都没被扫到**（只认行首的 `weflow-cli `）。要求文件名是 `cli.cjs`/`weflow-cli.ts`：
+    `node scripts/graph3d_check.mjs --flag` 那种是**别的脚本自己的旗标**，不该拿 CLI 的表去比。
+    """
+    out = []
+    for lineno, stripped in fenced_lines(text):
+        m = CLI_WRAPPER.search(_body(stripped))
+        if m and m.group(1).strip():
+            out.append((lineno, 'weflow-cli ' + m.group(1).strip()))
+    return out
+
+
+def python_invocations(text):
+    """围栏代码块里的 Python 调用：(行号, 脚本名, 剩余参数)。"""
+    out = []
+    for lineno, stripped in fenced_lines(text):
+        m = PY_CALL.search(_body(stripped))
+        if m:
+            out.append((lineno, m.group(1), m.group(2).strip()))
+    return out
+
+
+def declared_flags(source):
+    """一个脚本用 `add_argument` 声明过的旗标 —— **纯 AST：不 import、不运行**。
+
+    仓库对 Python 脚本的既定纪律就是不在检查里跑它们（`test/script_stdout_encoding_test.py`
+    头部写了原因：CI 的 python job 只装两个依赖，import 会假失败），所以这里也只读源码。
+    """
+    flags = set()
+    for node in ast.walk(ast.parse(source)):
+        if isinstance(node, ast.Call) and getattr(node.func, 'attr', None) == 'add_argument':
+            for arg in node.args:
+                if isinstance(arg, ast.Constant) and isinstance(arg.value, str) \
+                        and arg.value.startswith('-'):
+                    flags.add(arg.value)
+    return flags
+
+
+def audit_line(body, help_of):
+    """→ (命令路径, [问题])。问题里 kind 是 'unknown-command' 或 'unknown-flag'。"""
+    tokens = shlex.split(body, posix=False)[1:]      # posix=False：Windows 路径里的 \ 不被吃掉
+    path, problems = [], []
+    for tok in tokens:
+        clean = tok.strip('`,')
+        if not TOKEN_OK.match(clean):
+            break                                    # 参数/占位符，路径到此为止
+        if usage_path(help_of(path + [clean])) == path + [clean]:
+            path.append(clean)
+        else:
+            # 走不动了。父命令**有子命令**，说明这个裸词是想当子命令用的 ⇒ 它不存在。
+            if has_subcommands(help_of(path)):
+                problems.append(('unknown-command', ' '.join(path + [clean])))
+            break
+    help_text = help_of(path)
+    for tok in tokens:
+        clean = tok.strip('`,')
+        if FLAG.match(clean) and clean not in (help_text or ''):
+            problems.append(('unknown-flag', '%s %s' % (' '.join(path), clean)))
+    return path, problems
+
+
+# ---------------------------------------------------------------- 真实 CLI / 正对照
+
+def cli_help(path, cli=None):
+    """问真实 CLI。取不到就返回 None —— 由调用方报错，不许当成"没问题"。"""
+    cli = cli or os.path.join(ROOT, 'cli.cjs')
+    if not os.path.exists(cli):
+        raise SystemExit('找不到 %s —— 先跑 `npm run build`（cli.cjs 依赖 dist/）' % cli)
+    proc = subprocess.run(['node', cli, *path, '--help'], capture_output=True, cwd=ROOT)
+    return (proc.stdout + proc.stderr).decode('utf-8', 'replace')
+
+
+def default_files():
+    """默认扫的**用户文档**。
+
+    排除两份按性质记录过去的：`CHANGELOG.md`（发布日志）与 `docs/DECISIONS.md`（决策日志）——
+    它们会成段引用**当时**的命令，拿今天的 CLI 去校验必然假阳性。其余 `docs/*.md` 都扫：
+    2026-10-11 就是这份集合里的 `OPERATIONS.md` 抓到了"文档教用户敲一个 CLI 没有的旗标"
+    （`search --no-rerank`），而只扫两份 README 时它一条也扫不到。
+    """
+    out = ['README.md', 'README.en.md', 'OPERATIONS.md', 'ARCHITECTURE.md',
+           'CONTRIBUTING.md', 'SECURITY.md']
+    out += ['docs/' + os.path.basename(p)
+            for p in sorted(glob.glob(os.path.join(ROOT, 'docs', '*.md')))
+            if os.path.basename(p) != 'DECISIONS.md']
+    return out
+
+
+def check_python_call(doc, lineno, script, rest):
+    """文档里的一条 `py scripts/x.py …` → [问题]。"""
+    path = os.path.join(ROOT, 'scripts', script)
+    if not os.path.exists(path):
+        return [{'file': doc, 'line': lineno, 'command': 'scripts/' + script,
+                 'kind': 'missing-script', 'detail': 'scripts/%s 不存在' % script}]
+    try:
+        with open(path, encoding='utf-8') as fh:
+            have = declared_flags(fh.read())
+    except (OSError, SyntaxError) as exc:
+        # 读不出来就说读不出来（这一面**没有被检查**），不当成通过
+        return [{'file': doc, 'line': lineno, 'command': 'scripts/' + script,
+                 'kind': 'unreadable-script', 'detail': '读不出这个脚本的声明：%s' % exc}]
+    out = []
+    for flag in PY_FLAG.findall(rest):
+        # argparse 允许前缀缩写，所以 `--dry` 也算认；文档里写全名最清楚，这里按前缀判
+        long_ok = flag.startswith('--') and any(h.startswith(flag) for h in have if h.startswith('--'))
+        if flag not in have and not long_ok:
+            out.append({'file': doc, 'line': lineno, 'command': 'scripts/%s %s' % (script, flag),
+                        'kind': 'unknown-script-flag', 'detail': '%s 没声明 %s' % (script, flag)})
+    return out
+
+
+ANGLE = re.compile(r'<[^<>]*>')
+ELLIPSIS = re.compile(r'\.\.\.|…')
+
+
+def command_forms(text):
+    """把 `capabilities` 里一条命令串拆成**可校验的形式**（这个输出的记法不是 shell 语法）。
+
+    · `<a|b|c>` —— 尖括号里的"或"，取第一项（`export <talker> <json|txt|html|excel>` 是**一条**命令）
+    · `a | b` —— 尖括号**之外**的 `|` 是"两种写法"（`decide --request … | decide --over …`），逐条验
+    · `...` / `…` —— 省略号之后截掉（那部分本来就没写全，验不了）
+
+    2026-10-11 踩过：不知道这三种记法时直接按 `|` 切，8 条串报出 11 个"问题"，**全是噪声**
+    （`<add|remove|enable|…>` 被切成了命令）。
+    """
+    # 取第一项时**去掉尖括号**（按第一项替换）。这一条踩过：先写成"保留尖括号"，于是
+    # `<whitelist|blacklist> <add|rm> <target> --dry-run --json` 这类串在**第一个占位符**处就断了
+    # ——而那个占位符**本身就是命令名**（`whitelist add`）⇒ 旗标被拿去跟**父命令**的 help 比，
+    # 一次报出 6 处"没有这个旗标"，全是假的（换回不带括号后 6 处全消，且与独立探针的结果一致）。
+    # 反方向的代价很小：参数位上的占位符变成普通小写词，路径在那里停下即可（父命令没有子命令时不会误报）。
+    text = ANGLE.sub(lambda m: m.group(0)[1:-1].split('|')[0].strip(), text)
+    text = ELLIPSIS.split(text)[0]
+    return [part.strip() for part in text.split('|') if part.strip()]
+
+
+def capability_commands(cli=None):
+    """`capabilities --json` 里**手写**的命令串 → [(字段路径, 命令行)]。
+
+    收 `cli` **与 `preview`** 两个字段：`preview` 是"两阶段安全路径"里先跑的那一条（用户与 agent
+    都按它来），所以它和 `cli` 一样会被手写漂移。这个对象的其余部分要么是布尔/契约名，要么
+    （`safety.mcpSurface`）是从真实注册表派生的 —— 派生那半不用这儿管。
+    """
+    cli = cli or os.path.join(ROOT, 'cli.cjs')
+    if not os.path.exists(cli):
+        raise SystemExit('找不到 %s —— 先跑 `npm run build`' % cli)
+    proc = subprocess.run(['node', cli, 'capabilities', '--json'], capture_output=True, cwd=ROOT)
+    text = (proc.stdout or b'').decode('utf-8', 'replace')
+    try:
+        data = json.loads(text)
+    except ValueError:
+        raise SystemExit('`capabilities --json` 没给出可解析的 JSON：%s' % text[:200])
+    out = []
+
+    def walk(node, where):
+        if isinstance(node, dict):
+            for key, value in node.items():
+                if key in ('cli', 'preview') and isinstance(value, str):
+                    out.append((where + '.' + key, value))
+                else:
+                    walk(value, where + '.' + key)
+        elif isinstance(node, list):
+            for i, item in enumerate(node):
+                walk(item, '%s[%d]' % (where, i))
+
+    walk(data, 'capabilities')
+    return out
+
+
+CANNED = {
+    (): ('Usage: weflow-cli [options] [command]\n\nOptions:\n  -V, --version\n\n'
+         'Commands:\n  sessions [options]  会话列表\n  wiki [options]      概念图谱管理\n'),
+    ('sessions',): 'Usage: weflow-cli sessions [options]\n\nOptions:\n  -n, --limit <n>\n',
+    ('wiki',): ('Usage: weflow-cli wiki [options] [command]\n\nOptions:\n  -h, --help\n\n'
+                'Commands:\n  graph [options]\n  lint [options]\n'),
+    ('wiki', 'graph'): 'Usage: weflow-cli wiki graph [options]\n\nOptions:\n  --flat\n  --open\n',
+}
+
+# (说明, 命令行, 期望报出的问题数)
+CONTROLS = [
+    ('该过的过：存在的命令 + 存在的旗标', 'weflow-cli sessions -n 5', 0),
+    ('该报的报：不存在的旗标', 'weflow-cli sessions --bogus', 1),
+    ('该报的报：不存在的子命令', 'weflow-cli wiki bogus', 1),
+    ('该报的报：不存在的顶层命令', 'weflow-cli bogus', 1),
+    ('不该报的不报：参数里的裸词（父命令没有子命令）', 'weflow-cli sessions 张三', 0),
+]
+
+
+def self_test():
+    """判据本身的正对照。扫描器失灵时它会安静地全绿，所以先证明它活着。"""
+    bad = []
+    for label, line, expect in CONTROLS:
+        _, problems = audit_line(line, lambda p: CANNED.get(tuple(p)))
+        if len(problems) != expect:
+            bad.append('%s\n    %s\n    期望 %d 个问题，实得 %d：%s'
+                       % (label, line, expect, len(problems), problems))
+    # 反"空扫"：一条命令都没解析出来，说明扫描器坏了，那时的"没问题"不作数
+    sample = FENCE + 'powershell\ndir\nweflow-cli sessions -n 5\n' + FENCE + '\n'
+    if len(command_lines(sample)) != 1:
+        bad.append('反空扫失败：围栏代码块里的命令没被识别出来')
+    # Python 那一半：**围栏里**的调用要认得出，**散文里**的提及不许认（那正是假阳性来源）
+    fenced = FENCE + 'powershell\npy scripts/health_check.py --json\n' + FENCE + '\n'
+    if len(python_invocations(fenced)) != 1:
+        bad.append('反空扫失败：围栏里的 `py scripts/x.py` 没被识别出来')
+    if python_invocations('跑 `py scripts/health_check.py --json` 就行（散文里的一句）\n'):
+        bad.append('散文里的调用被当成命令了 —— 那会造出假阳性')
+    flags = declared_flags('import argparse\np = argparse.ArgumentParser()\n'
+                           "p.add_argument('--dry-run')\np.add_argument('-n', '--limit')\n")
+    if flags != {'--dry-run', '-n', '--limit'}:
+        bad.append('AST 取声明旗标取错了：%s' % sorted(flags))
+    # 脚本名里的连字符：第一版的正则漏了它，整条调用被静默跳过（夹具 3 条只提取到 2 条才发现）。
+    # 注意围栏**必须单独一行** —— 第一版把命令写在 ``` 同一行上，那行被当成围栏标记，内容根本不产出
+    # （控制项自己错了，却报成"连字符没被认出来"）。
+    hyphen = FENCE + '\npy scripts/some-hyphenated-script.py --flag\n' + FENCE + '\n'
+    if len(python_invocations(hyphen)) != 1:
+        bad.append('脚本名里的连字符没被认出来 —— 那会让整条调用静默漏检')
+    # `capabilities` 命令串的三种记法：尖括号里的"或"取第一项、括号外的 `|` 拆成两种写法、`…` 截断
+    forms = command_forms('export <talker> <json|txt|html|excel>')
+    if forms != ['export talker json']:
+        bad.append('尖括号里的"或"没取第一项：%s' % forms)
+    forms = command_forms('<whitelist|blacklist> <add|rm> <target> --dry-run --json')
+    if forms != ['whitelist add target --dry-run --json']:
+        bad.append('命令名上的占位符没被替换成第一项（那会让路径断在这里）：%s' % forms)
+    forms = command_forms('decide --a --yes | decide --b --yes')
+    if forms != ['decide --a --yes', 'decide --b --yes']:
+        bad.append('括号外的 `|` 没拆成两种写法：%s' % forms)
+    forms = command_forms('scene <add|remove> … --dry-run')
+    if forms != ['scene add']:
+        bad.append('省略号没截断 / 或"或"没取第一项：%s' % forms)
+    # 换了写法的 CLI 调用：那两种写法都认得出，**不**把别的脚本当成 CLI
+    wrapped = FENCE + '\nnode cli.cjs capabilities --json\nnode node_modules\\weflow-cli\\cli.cjs --version\n' + FENCE + '\n'
+    if len(cli_wrapped_lines(wrapped)) != 2:
+        bad.append('`node …/cli.cjs <命令>` 这种写法没被认出来：%s' % cli_wrapped_lines(wrapped))
+    if cli_wrapped_lines(FENCE + '\nnode scripts/graph3d_check.mjs --flag\n' + FENCE + '\n'):
+        bad.append('把别的脚本的调用当成 CLI 了（那会拿 CLI 的表去比它的旗标）')
+    controls = len(CONTROLS) + 10
+    print('正对照：%d 条，通过 %d 条' % (controls, controls - len(bad)))
+    for item in bad:
+        print('  ✗ ' + item)
+    return 1 if bad else 0
+
+
+def main():
+    parser = argparse.ArgumentParser(description='校验文档与 capabilities 里的命令在 CLI 里存在')
+    parser.add_argument('--files', nargs='*', default=None,
+                        help='要扫的 markdown（缺省：README + 仓库根那几份 + docs/*.md，'
+                             '排除按性质记录过去的 CHANGELOG 与 DECISIONS）')
+    parser.add_argument('--json', action='store_true')
+    parser.add_argument('--self-test', action='store_true', help='只跑判据的正对照')
+    args = parser.parse_args()
+
+    if args.self_test:
+        raise SystemExit(self_test())
+
+    checked, findings, doc_checked = 0, [], 0
+    for name in (args.files if args.files else default_files()):
+        path = os.path.join(ROOT, name)
+        if not os.path.exists(path):
+            raise SystemExit('找不到 %s' % path)
+        with open(path, encoding='utf-8') as fh:
+            text = fh.read()
+        for lineno, body in command_lines(text) + cli_wrapped_lines(text):
+            checked += 1
+            doc_checked += 1
+            _, problems = audit_line(body, cli_help)
+            findings += [{'file': name, 'line': lineno, 'command': body,
+                          'kind': kind, 'detail': detail} for kind, detail in problems]
+        # 同一批文档里的第三类手写面：`py scripts/x.py --flag`
+        for lineno, script, rest in python_invocations(text):
+            checked += 1
+            findings += check_python_call(name, lineno, script, rest)
+
+    # 第二个手写面：`capabilities --json` 的 `cli:` 与 `preview:` 串（学这个项目的入口，也是手写的）。
+    caps = capability_commands()
+    cap_forms = 0
+    for where, command in caps:
+        for form in command_forms(command):
+            cap_forms += 1
+            checked += 1
+            _, problems = audit_line('weflow-cli ' + form, cli_help)
+            findings += [{'file': 'capabilities --json', 'line': 0, 'command': form, 'where': where,
+                          'kind': kind, 'detail': detail} for kind, detail in problems]
+    script_checked = checked - doc_checked - cap_forms
+
+    if args.json:
+        print(json.dumps({'checked': checked, 'docChecked': doc_checked,
+                          'scriptChecked': script_checked, 'capabilityFormsChecked': cap_forms,
+                          'capabilityStringsChecked': len(caps), 'findings': findings},
+                         ensure_ascii=False, indent=2))
+    else:
+        for f in findings:
+            source = ('%s（%s）' % (f['file'], f['where'])) if f.get('where') else ('%s:%d' % (f['file'], f['line']))
+            where_it_lives = ('文档里写了它' if f['kind'] == 'unknown-script-flag' else '写的地方有它')
+            missing_side = ('那个脚本没声明' if f['kind'] == 'unknown-script-flag' else 'CLI 里没有')
+            print('[FAIL] %s  %s\n       %s —— %s%s' % (source, f['command'], f['detail'], where_it_lives, missing_side))
+        if findings:
+            print('\n%d 处对不上（共检查 %d 条：文档命令 %d + 脚本调用 %d + capabilities %d 种写法）。'
+                  % (len(findings), checked, doc_checked, script_checked, cap_forms))
+        else:
+            print('命令面与实现一致：文档命令 %d 条 + `py scripts/…` 调用 %d 条 + capabilities 的 %d 种写法'
+                  '（来自 %d 条 `cli:`/`preview:` 串），0 处对不上。'
+                  % (doc_checked, script_checked, cap_forms, len(caps)))
+    # 反空扫只对**缺省语料**生效：那批文档里一定有命令，扫到 0 条说明判据/提取器坏了，不该报通过。
+    # 显式 `--files <夹具>` 时不算失败 —— 夹具本来就可能只含某一类。
+    # （"提取器本身还活着"另由 `--self-test` 的三条对照负责；脚本那一面**不做** entry 级反空扫：
+    #  文档里一条 `py scripts/…` 都没有是可能发生的。）
+    if not args.files and doc_checked == 0:
+        print('反空扫失败：缺省文档里一条命令都没扫到，这次"通过"不作数。')
+        return 2
+    if not caps:
+        print('反空扫失败：`capabilities --json` 里一条 `cli:` 串都没读到，这一半没有被检查。')
+        return 2
+    return 1 if findings else 0
+
+
+if __name__ == '__main__':
+    raise SystemExit(main())