@huicai/cli 2026.814.0 → 2026.1019.0

package/skills/docx-author/scripts/zh_prose.py

@@ -0,0 +1,639 @@
+# 中文技术文档的文字质量体检：错别字、标点、术语一致、表述质量、**AI 味**。
+#
+# 与排版体检（docx_check 的几何部分）的分工：那边管「看得见的事故」（溢出、超宽、变形），
+# 这边管「读得出的毛病」（写错字、标点混用、满篇套话）。两边都在 docx_check 里汇总成一份报告。
+#
+# 本模块**只吃纯文本**，不依赖 python-docx——所以 Markdown 草稿、纯文本、
+# docx 抽出来的段落都能用同一套判据。`python zh_prose.py 草稿.md` 可直接跑。
+#
+# ── 一条纪律：误报比漏报更伤 ──────────────────────────────────────────────
+# 一个天天喊狼来了的检查器，用两次就没人看了。所以：
+#   · 黑白分明的（「己经」「按装」）才报 error；
+#   · 一词两用、要看语境的（「制定/制订」「截止/截至」）只报 warn 并写明区别，由人定夺；
+#   · AI 味**一律按密度报，不按单次出现报**——「综上所述」在结论里出现一次是正常写作，
+#     出现七次才是模板。单次命中就报，等于逼人把正常的话也删掉。
+
+import math
+import re
+import sys
+from collections import Counter, defaultdict
+
+# ── 一、错别字与易混词 ─────────────────────────────────────────────────────
+# 明确写错的（error）：右边是唯一正确写法，替换不需要看语境。
+TYPOS = {
+    '己经': '已经', '既使': '即使', '按装': '安装', '安照': '按照', '布署': '部署',
+    '峻工': '竣工', '蓝领': None, '篮图': '蓝图', '题纲': '提纲', '编致': '编制',
+    '曼延': '蔓延', '讫今': '迄今', '座落': '坐落', '渡过难关': None, '决对': '绝对',
+    '既然如此': None, '至至': None, '在所不昔': '在所不惜', '迫不急待': '迫不及待',
+    '有条不絮': '有条不紊', '一如继往': '一如既往', '一诺千斤': '一诺千金',
+    '按步就班': '按部就班', '不落于俗套': None, '弱不经风': '弱不禁风',
+    '穿流不息': '川流不息', '重蹈复辙': '重蹈覆辙', '一愁莫展': '一筹莫展',
+    '各行其事': '各行其是', '再接再励': '再接再厉', '悬梁刺骨': '悬梁刺股',
+    '甘败下风': '甘拜下风', '好高鹜远': '好高骛远', '如愿以尝': '如愿以偿',
+    '和霭': '和蔼', '缘故': None, '寒喧': '寒暄', '慧眼识金': None,
+    '通宵达但': '通宵达旦', '相辅相承': '相辅相成', '迫在没睫': '迫在眉睫',
+    '不径而走': '不胫而走', '声名雀起': '声名鹊起', '沤心沥血': '呕心沥血',
+    '走头无路': '走投无路', '不加思索': '不假思索', '融汇贯通': '融会贯通',
+    '严具以待': '严阵以待', '摩拳擦掌': None, '肆无忌单': '肆无忌惮',
+    '开门缉盗': '开门揖盗', '功亏一匮': '功亏一篑', '侯选': '候选', '气慨': '气概',
+    '爆发户': '暴发户', '奇葩异草': '奇花异草', '直接了当': '直截了当',
+    '毛骨耸然': '毛骨悚然', '不落窠桕': '不落窠臼', '循私舞弊': '徇私舞弊',
+    '连锁反映': '连锁反应', '暗然失色': '黯然失色', '记忆尤新': '记忆犹新',
+}
+TYPOS = {k: v for k, v in TYPOS.items() if v}
+
+# 需要看语境的（warn）：写法都存在，但含义不同，用错了读者会误解。
+CONFUSABLES = [
+    ('截止目前', '截至目前', '「截止」是停止（截止日期），「截至」是到某时间为止'),
+    ('截止到', '截至', '同上：表示「到……为止」用「截至」'),
+    ('制定计划', None, '「制定」多用于方针政策等宏观件，「制订」多用于具体方案，可推敲'),
+    ('起动', '启动', '机械装置用「起动」，系统/程序/项目一律用「启动」'),
+    ('帐号', '账号', '与钱、账目相关一律用「账」，「帐」只用于布幔'),
+    ('帐户', '账户', '同上'),
+    ('帐单', '账单', '同上'),
+    ('其它', '其他', '现代汉语规范推荐「其他」，指物指人皆可'),
+    ('部份', '部分', '「部份」为港台写法，大陆规范为「部分」'),
+    ('作出贡献', None, '「作出」与「做出」皆通行，全文统一即可'),
+    ('反应情况', '反映情况', '「反映」是如实告知，「反应」是物理化学或应激'),
+    ('权利机关', '权力机关', '「权力」是支配力，「权利」是法律赋予的资格'),
+    ('必需品', None, '「必需」作定语指必不可少之物，「必须」作状语修饰动词，勿互换'),
+    ('以致于', '以至于', '「以致」接不好的结果，「以至」表程度延伸'),
+    ('进行了优化', None, '「进行+双音节动词」是典型冗余，可直接说「优化了」'),
+]
+
+# ── 重复（打字/粘贴事故）─────────────────────────────────────────────────
+# **不能按「虚词叠字」判**。中文里这些叠字几乎全有合法用法：
+#   目的的重要性 / 为了了解 / 和和平发展 / 在在线账户 / 的的确确 / 把把手 / 对对方 / 从从容容
+# 早先那条 `ch*2 in s` 的规则在真实语料上命中 20 处，**全是误报**，还是必修级——
+# 这种检查比没有更糟。改成两条黑白分明的：
+#   ① 同一字符连续出现三次以上（的的的、我我我）——正常中文不会这样；
+#   ② 三字以上的词组紧邻重复（本项目本项目）——这是复制粘贴事故的真实指纹。
+#      限定三字起：两字重叠是合法构词（看看、渐渐、一步一步、认认真真）。
+DUP_RUN_RE = re.compile(r'([一-鿿])\1{2,}')
+DUP_PHRASE_RE = re.compile(r'([一-鿿]{3,8})\1')
+
+# ── 二、标点 ───────────────────────────────────────────────────────────────
+CJK = r'一-鿿㐀-䶿'
+PUNCT_RULES = [
+    ('half-comma', re.compile(rf'[{CJK}],(?![\d])'), 'error', '中文语境用了半角逗号 ","', '，'),
+    ('half-period', re.compile(rf'[{CJK}]\.(?![\d\w])'), 'error', '中文语境用了半角句号 "."', '。'),
+    ('half-semi', re.compile(rf'[{CJK}];'), 'error', '中文语境用了半角分号 ";"', '；'),
+    ('half-colon', re.compile(rf'[{CJK}]:(?![\d/\\])'), 'error', '中文语境用了半角冒号 ":"', '：'),
+    ('half-question', re.compile(rf'[{CJK}]\?'), 'error', '中文语境用了半角问号 "?"', '？'),
+    ('half-paren', re.compile(rf'\([^)]*[{CJK}][^)]*\)'), 'warn', '中文内容用了半角括号 "()"', '（）'),
+    ('bad-ellipsis', re.compile(r'\.{3,}|。{3,}|·{3,}'), 'warn', '省略号写法不规范', '……'),
+    # 破折号只在「前后都贴着字」时才算破折号用法。
+    # 单独一个「—」占满整格，是中文表格里「不适用/无」的标准占位写法——
+    # 把它判成破折号错误，等于逼人把规范写法改坏。
+    ('bad-dash', re.compile(rf'(?<![-—])--(?!-)|(?<=[{CJK}\w])—(?=[{CJK}\w])'), 'warn',
+     '破折号应为两个全角「——」', '——'),
+    ('dup-punct', re.compile(r'([，。；：！？、])\1+'), 'error', '连续重复标点', None),
+    ('space-before-punct', re.compile(r'\s+[，。；：！？、）】」』]'), 'warn', '标点前多了空格', None),
+    ('num-range-hyphen', re.compile(r'\d+\s*-\s*\d+\s*(?:年|月|日|万元|元|人|个|台|套|%)'), 'info',
+     '数值区间建议用「～」或「—」而非半角连字符', None),
+]
+PAIRS = [('（', '）'), ('「', '」'), ('『', '』'), ('【', '】'), ('《', '》'), ('“', '”'), ('‘', '’')]
+
+# ── 三、AI 味 ──────────────────────────────────────────────────────────────
+# 词表分三类，各有各的阈值。**全部按密度判定**，单次出现一律不报。
+AI_CLICHE = [                      # 套话骨架：出现三次以上就是模板在说话
+    '值得注意的是', '需要指出的是', '需要强调的是', '综上所述', '总而言之', '总的来说',
+    '总体而言', '不难看出', '由此可见', '换句话说', '毫无疑问', '显而易见',
+    '在当今', '随着.{0,8}的不断发展', '随着.{0,8}的日益', '显得尤为重要',
+    '具有重要的现实意义', '具有重要意义', '奠定了坚实的基础', '提供了有力支撑',
+    '发挥了重要作用', '取得了显著成效', '积累了宝贵经验', '为.{0,10}提供了新思路',
+]
+AI_BUZZ = [                        # 互联网黑话/空转动词：技术文档里几乎总能换成具体动作
+    '赋能', '抓手', '闭环', '打法', '心智', '颗粒度', '生态位', '组合拳', '护城河',
+    '对齐颗粒度', '拉通', '沉淀', '复用性', '强化认知', '深度融合', '全方位',
+    '多维度', '立体化', '一体化推进', '持续深化', '不断优化', '有效提升', '显著改善',
+    '大力推进', '积极探索', '切实加强', '进一步完善', '深入推进', '扎实开展',
+    '助力', '致力于', '旨在打造', '构建了一套', '形成了.{0,6}体系',
+]
+AI_EMPTY = ['进一步', '有效', '积极', '大力', '不断', '切实', '充分', '全面', '深入', '持续', '高度']
+AI_CONNECT = ['首先', '其次', '再次', '最后', '另一方面', '与此同时', '在此基础上']
+
+SPECIFIC_RE = re.compile(r'\d')        # 具体性锚点：数字、日期、比例、金额
+DATE_RE = re.compile(r'\d{4}\s*年|\d{1,2}\s*月|\bQ[1-4]\b')
+
+# ── 四、表述质量阈值 ───────────────────────────────────────────────────────
+LONG_RUN = 45           # 连续 >45 字不出现停顿标点：读者要憋着读完，必须断开
+LONG_SENT = 110         # 整句 >110 字：即便有逗号也太长，该拆成两句
+LONG_PARA = 600         # 一段 >600 字：该拆
+DE_PER_SENT = 4         # 一句里 4 个以上「的」：定语套娃
+
+SENT_SPLIT = re.compile(r'(?<=[。！？；\n])')
+
+
+def _issue(level, group, kind, loc, msg, quote='', suggest=''):
+    return {'level': level, 'group': group, 'kind': kind, 'loc': loc,
+            'msg': msg, 'quote': quote[:60], 'suggest': suggest}
+
+
+# 「读起来有多长」：书名号、引号里的名称、括注，读者当一个整体读，不会在中间换气；
+# 一个英文词、一个数字（含版本号、百分比）也是一个单位；「［待补：…］」占位不算字数。
+# 按字符硬数会把「艾瑞咨询《……洞察报告》（2026 年 8 月发布）指出」「Spring Cloud 2023.0.1 与 …」报成不喘气——
+# 可研、方案这类报告通篇是引用、文号、版本、公式，这种误报会逼着把写对的东西改坏。
+_QUOTED = re.compile(r'《[^》]{0,80}》|「[^」]{0,80}」|“[^”]{0,80}”|（[^）]{0,80}）|\([^)]{0,80}\)|〔[^〕]{0,20}〕')
+_PLACEHOLDER = re.compile(r'［[^］]{0,60}］')
+_LATIN_WORD = re.compile(r'[A-Za-z0-9][A-Za-z0-9.\-_/%]*')
+# 除逗号顿号分号冒号外，箭头与公式运算符也是停顿（「A → B → C」「净现金流量 = 收入 + 节约 − 成本」）
+RUN_SPLIT = re.compile(r'[，、；：,→←⇒⇐=＝+＋−×÷|｜]')
+
+
+def _reading_len(text):
+    t = _PLACEHOLDER.sub('', str(text or ''))
+    t = _QUOTED.sub('□', t)
+    t = _LATIN_WORD.sub('x', t)
+    return len(re.sub(r'\s+', '', t))
+
+
+def _sentences(text):
+    return [s.strip() for s in SENT_SPLIT.split(str(text or '')) if s.strip()]
+
+
+def _cjk_len(s):
+    return sum(1 for ch in s if '一' <= ch <= '鿿')
+
+
+# ── 段级检查 ───────────────────────────────────────────────────────────────
+def check_paragraph(text, loc='', kind='body', strict=False):
+    """单段文字体检。kind: body 正文 / heading 标题 / caption 题注 / cell 单元格。"""
+    out = []
+    s = str(text or '')
+    if not s.strip():
+        return out
+
+    for wrong, right in TYPOS.items():
+        if wrong in s:
+            out.append(_issue('error', 'text', 'typo', loc, f'错别字「{wrong}」应为「{right}」',
+                              _around(s, wrong), right))
+    for wrong, right, note in CONFUSABLES:
+        if wrong in s:
+            sug = f'建议改为「{right}」' if right else '请人工确认'
+            out.append(_issue('warn', 'text', 'confusable', loc,
+                              f'易混写法「{wrong}」：{note}', _around(s, wrong), sug))
+    m = DUP_RUN_RE.search(s)
+    if m:
+        out.append(_issue('warn', 'text', 'dup-char', loc,
+                          f'同一字符连续出现 {len(m.group(0))} 次：「{m.group(0)}」',
+                          _around(s, m.group(0)), m.group(1)))
+    m = DUP_PHRASE_RE.search(s)
+    if m:
+        out.append(_issue('warn', 'text', 'dup-phrase', loc,
+                          f'词组紧邻重复：「{m.group(1)}」出现了两遍',
+                          _around(s, m.group(0)), m.group(1)))
+
+    for name, pat, level, msg, sug in PUNCT_RULES:
+        if name == 'num-range-hyphen' and not strict:
+            level = 'info'
+        m = pat.search(s)
+        if m:
+            n = len(pat.findall(s))
+            out.append(_issue(level, 'punct', name, loc,
+                              msg + (f'（本段 {n} 处）' if n > 1 else ''),
+                              _around(s, m.group(0)), sug or ''))
+    for lft, rgt in PAIRS:
+        if lft == rgt:
+            continue
+        if s.count(lft) != s.count(rgt):
+            out.append(_issue('error', 'punct', 'unpaired', loc,
+                              f'{lft}{rgt} 不配对（{s.count(lft)} 开 / {s.count(rgt)} 闭）', s[:60], ''))
+    if s.count('"') % 2 or s.count("'") % 2:
+        out.append(_issue('warn', 'punct', 'straight-quote', loc,
+                          '出现半角直引号且数量为奇数，中文正文应使用“”', s[:60], '“”'))
+
+    if kind == 'heading':
+        if s.rstrip().endswith(('。', '．', '.')):
+            out.append(_issue('warn', 'punct', 'heading-period', loc, '标题末尾不应加句号', s[:40], ''))
+        if len(s) > 40:
+            out.append(_issue('warn', 'text', 'heading-long', loc,
+                              f'标题过长（{len(s)} 字），标题应是名词短语不是句子', s[:40], ''))
+        return out
+
+    if kind == 'body':
+        n = len(s)
+        if n > LONG_PARA:
+            out.append(_issue('warn', 'text', 'para-long', loc,
+                              f'段落过长（{n} 字），建议拆成 2–3 段或改列项', s[:40], ''))
+        for sent in _sentences(s):
+            # 「长」有两种：一种是整句太长，一种是句子里某一截不喘气。
+            # 早先只按「去掉逗号后的字数」判，会把带三个逗号的句子说成「无停顿」——
+            # 判据与文案不符的检查最伤信任，所以两件事分开量、分开说。
+            chunks = RUN_SPLIT.split(sent)
+            longest = max((_reading_len(c) for c in chunks), default=0)
+            sent_len = len(_PLACEHOLDER.sub('', sent))
+            if longest > LONG_RUN:
+                out.append(_issue('warn', 'text', 'sent-run', loc,
+                                  f'连续 {longest} 字没有停顿标点，读者要憋着读完',
+                                  max(chunks, key=_reading_len)[:50], '在语义停顿处补逗号或断句'))
+            elif sent_len > LONG_SENT:
+                out.append(_issue('warn', 'text', 'sent-long', loc,
+                                  f'整句 {sent_len} 字过长，建议拆成两句', sent[:50], ''))
+            if sent.count('的') >= DE_PER_SENT:
+                out.append(_issue('info', 'text', 'de-stack', loc,
+                                  f'一句里 {sent.count("的")} 个「的」，定语套娃', sent[:50], ''))
+        if s.strip() and s.strip()[-1] not in '。！？；：”）】》…—':
+            out.append(_issue('warn', 'punct', 'no-end-punct', loc, '段落结尾缺标点', s[-30:], '。'))
+    return out
+
+
+def _around(s, needle, span=12):
+    i = s.find(needle)
+    if i < 0:
+        return s[:40]
+    return s[max(0, i - span):i + len(needle) + span]
+
+
+# ── 文档级：术语一致 ───────────────────────────────────────────────────────
+# 术语一致性分两路，都刻意做得「无争议」——宁可少报，不报有争议的：
+#   ① 拉丁词大小写不一致（API/Api/api）：同一个词的不同拼法，客观是错，靠通用扫描发现，
+#      不需要维护词表，也不会误伤（大小写不同就是不一致，没有第二种解释）；
+#   ② 中文角色词的多种叫法（甲方/建设单位/委托方）：同一份文件里混着叫，读者要自己对应。
+# 早先把「用户/客户」「系统/平台」也列进来是错的——那是两个不同概念，不是两种写法。
+# 连字符、下划线、点号、斜杠、@ 连着的是标识符或专名的一部分（one-api、Vue.js、/v1/api、user@host），不是独立术语：
+# 「one-api」里的 api 和正文里的 API 不是同一个词的两种拼法（实测可研里被报成「api×2、API×2」）
+LATIN_TOKEN = re.compile(r'(?<![A-Za-z0-9\-_./@])([A-Za-z][A-Za-z0-9]{1,15})(?![A-Za-z0-9\-_./@])')
+CASE_WHITELIST = {'a', 'i', 'the', 'of', 'and', 'to', 'in', 'is', 'v', 'vs'}
+ROLE_SYNONYMS = [
+    (['甲方', '建设单位', '委托方', '需求方'], '委托方'),
+    (['乙方', '承建单位', '承研单位', '受托方', '开发方'], '承担方'),
+    (['本系统', '本平台', '该系统', '该平台'], '本系统'),
+    (['项目组', '课题组', '研制组', '开发组'], '项目组'),
+    (['验收组', '专家组', '评审组'], '专家组'),
+]
+
+NUM_UNIT_RE = re.compile(r'(\d[\d,.]*)\s*(万元|亿元|元|万|人|人月|个月|天|台|套|%|％)')
+
+# 数量口径：「从七个维度识别」与「按五个维度识别」出现在同一份文件里，是评审最容易抓的硬伤，
+# 而人工通读几乎发现不了（两处隔了几页，各自读都通顺）。只查「结构性名词」的数量（模块/维度/阶段…），
+# 且只在**同一名词 + 同一后续两字**（如「维度识别」「微服务组成」）或两处都带「共/总计」这类总括词时才比——
+# 「网关包含五个模块」与「平台共十二个模块」是局部与整体，不是矛盾，不能报。
+_CN_DIGIT = {'一': 1, '二': 2, '两': 2, '三': 3, '四': 4, '五': 5, '六': 6, '七': 7, '八': 8, '九': 9}
+COUNT_NOUNS = ('维度|子系统|微服务|模块|服务|层次|阶段|环节|步骤|方面|能力|场景|板块|中心|引擎|组件|大类|类别|'
+               '原则|目标|子课题|课题|任务|里程碑|措施|指标|创新点|关键技术|技术难点|痛点|方向|领域|终端|入口|角色|'
+               '智能体|专家团|工作流|数据源')
+COUNT_RE = re.compile(
+    r'(?<![\d一二两三四五六七八九十百千第前后每近约逾超几数多余若至到~～\-－.．])'
+    r'(?P<n>\d{1,3}|[一二两三四五六七八九十]{1,3})\s*(?P<u>个|项|类|大|层|种|条|套|款|支|组)?\s*'
+    r'(?P<noun>' + COUNT_NOUNS + r')(?P<tail>[\u4e00-\u9fff]{0,2})')
+COUNT_TOTAL = re.compile(r'(共|总计|合计|一共|总共|全部|整体|总体上|共计|累计)\s*$')
+
+
+def _cn_int(s):
+    if s.isdigit():
+        return int(s)
+    if s == '十':
+        return 10
+    if s.startswith('十'):
+        return 10 + _CN_DIGIT.get(s[1:], 0)
+    if '十' in s:
+        a, _, b = s.partition('十')
+        return _CN_DIGIT.get(a, 0) * 10 + (_CN_DIGIT.get(b, 0) if b else 0)
+    return _CN_DIGIT.get(s, 0)
+
+
+def count_conflicts(paras):
+    """同一对象前后数量不一致。返回 issue 列表（建议级：数量可能各有语境，交人核对）。"""
+    strong, total = defaultdict(list), defaultdict(list)
+    for p in paras:
+        t = str(p.get('text', ''))
+        for m in COUNT_RE.finditer(t):
+            n = _cn_int(m.group('n'))
+            if n < 2:                                   # 「一个平台」是冠词用法，不是数量主张
+                continue
+            after = t[m.end():m.end() + 3]
+            if re.match(r'\s*(以上|以下|左右|多|余|来)', after):
+                continue
+            noun, tail = m.group('noun'), m.group('tail')
+            snippet = t[max(0, m.start() - 8):m.end() + 4].replace('\n', ' ')
+            rec = (n, m.group(0), snippet, p.get('loc', ''))
+            if len(tail) == 2:
+                strong[(noun, tail)].append(rec)
+            if COUNT_TOTAL.search(t[max(0, m.start() - 6):m.start()]):
+                total[noun].append(rec)
+    out, seen = [], set()
+    for key, recs in list(strong.items()) + [((k, '*'), v) for k, v in total.items()]:
+        vals = sorted({r[0] for r in recs})
+        if len(vals) < 2:
+            continue
+        sig = (key[0], tuple(vals))
+        if sig in seen:
+            continue
+        seen.add(sig)
+        forms = Counter(r[1] for r in recs)
+        detail = '、'.join(f'「{f}」×{c}' for f, c in forms.most_common(4))
+        where = '；'.join(f'{r[3]}：…{r[2]}…' for r in recs[:3] if r[3])
+        out.append(_issue('warn', 'consistency', 'count-conflict', '全文',
+                          f'同一对象的数量前后不一致：{detail}', where,
+                          '核对后全文统一（数量写错是评审最容易抓的硬伤；若确是不同对象，改写成能区分的叫法）'))
+    return out
+
+
+def check_document(paras, strict=False):
+    """文档级检查：术语一致、数字矛盾、AI 味、结构均匀度。paras = [{'text','kind','loc'}]。"""
+    out = []
+    bodies = [p for p in paras if p.get('kind') in (None, 'body')]
+    heads = [p for p in paras if p.get('kind') == 'heading']
+    full = '\n'.join(str(p.get('text', '')) for p in paras)
+    if not full.strip():
+        return out
+
+    # ① 拉丁词大小写不一致
+    byline = defaultdict(Counter)
+    for m in LATIN_TOKEN.finditer(full):
+        tok = m.group(1)
+        if tok.lower() in CASE_WHITELIST:
+            continue
+        byline[tok.lower()][tok] += 1
+    for low, forms in byline.items():
+        if len(forms) < 2 or sum(forms.values()) < 3:
+            continue
+        # 每种拼法都出现两次以上 = 确实在混用（建议级）；只出现一次的少数拼法更像手误（提示级）。
+        # 不按「每种都 ≥2」一刀切：真实文档里最常见的正是「用了三次 API、漏打一次 api」。
+        lvl = 'warn' if all(v >= 2 for v in forms.values()) else 'info'
+        detail = '、'.join(f'{k}×{v}' for k, v in sorted(forms.items(), key=lambda x: -x[1]))
+        out.append(_issue(lvl, 'consistency', 'term-variant', '全文',
+                          f'同一术语多种拼法：{detail}', '',
+                          f'择一并全文统一（通常取出现最多的「{max(forms, key=forms.get)}」）'))
+    # ② 中文角色词多种叫法
+    for group, prefer in ROLE_SYNONYMS:
+        forms = {w: full.count(w) for w in group}
+        forms = {k: v for k, v in forms.items() if v >= 2}
+        if len(forms) >= 2:
+            detail = '、'.join(f'{k}×{v}' for k, v in sorted(forms.items(), key=lambda x: -x[1]))
+            out.append(_issue('info', 'consistency', 'term-role', '全文',
+                              f'同一角色多种叫法：{detail}', '',
+                              f'全文统一（合同类文件通常用「{prefer}」或首次出现处的写法）'))
+
+    # 数字一致：同一「单位+量级」的关键数字在全文出现多个不同值时提请核对
+    by_unit = defaultdict(Counter)
+    for m in NUM_UNIT_RE.finditer(full):
+        by_unit[m.group(2)][m.group(1)] += 1
+    for unit in ('万元', '亿元', '人月'):
+        vals = by_unit.get(unit)
+        if vals and len(vals) >= 3:
+            top = '、'.join(f'{v}{unit}' for v, _ in vals.most_common(5))
+            out.append(_issue('info', 'consistency', 'number-scan', '全文',
+                              f'全文出现 {len(vals)} 个不同的「{unit}」数值：{top} …'
+                              f'——总投资/总工期这类数字必须处处相同，请专项核对', '', ''))
+
+    out.extend(count_conflicts(paras))
+
+    # 标题重复
+    dup = [t for t, n in Counter(str(p.get('text', '')).strip() for p in heads).items() if t and n > 1]
+    for t in dup[:5]:
+        out.append(_issue('warn', 'structure', 'dup-heading', '全文', f'标题重复出现：{t}', '', ''))
+
+    out.extend(ai_flavor(bodies, heads, strict=strict))
+    return out
+
+
+# ── 文档级：AI 味 ──────────────────────────────────────────────────────────
+def ai_flavor(bodies, heads=(), strict=False):
+    """AI 味体检。三层：词汇层（套话/黑话密度）、句式层（连接词/破折号/排比）、结构层（均匀度/具体性）。
+
+    结构层才是真指纹：人写的东西是不均匀的——有的节写得长，有的节两句话带过；
+    模型写的每节都恰好三段、每段都恰好四句、每条列项都恰好一行。
+    """
+    out = []
+    texts = [str(p.get('text', '')) for p in bodies]
+    full = '\n'.join(texts)
+    total = _cjk_len(full)
+    if total < 400:                       # 太短的文本统计量没有意义，不硬判
+        return out
+    k = total / 1000.0                    # 按每千字密度衡量
+
+    def _label(w):
+        """词表里的条目是正则，报告要给人看：把 `.{0,8}` 这类量词还原成「…」，
+        否则会打出「随着0,8的不断发展」这种没人看得懂的东西。"""
+        return re.sub(r'\.\{\d+,\d+\}', '…', re.sub(r'[\\[\]()*+?|]', '', w))
+
+    def hits(words):
+        c = Counter()
+        for w in words:
+            n = len(re.findall(w, full))
+            if n:
+                c[_label(w)] = n
+        return c
+
+    cl = hits(AI_CLICHE)
+    if sum(cl.values()) / k >= 2.0 and sum(cl.values()) >= 3:
+        top = '、'.join(f'{w}×{n}' for w, n in cl.most_common(6))
+        out.append(_issue('warn', 'ai', 'cliche', '全文',
+                          f'套话密度偏高（每千字 {sum(cl.values())/k:.1f} 处）：{top}',
+                          '', '删掉承接性套话，直接说结论；「综上所述」全文留一处足矣'))
+    bz = hits(AI_BUZZ)
+    if sum(bz.values()) / k >= 2.0 and sum(bz.values()) >= 3:
+        top = '、'.join(f'{w}×{n}' for w, n in bz.most_common(6))
+        out.append(_issue('warn', 'ai', 'buzzword', '全文',
+                          f'空转动词/黑话密度偏高（每千字 {sum(bz.values())/k:.1f} 处）：{top}',
+                          '', '换成具体动作：「赋能业务」→「把审批从 3 天缩到 4 小时」'))
+    em = hits(AI_EMPTY)
+    if sum(em.values()) / k >= 6.0:
+        top = '、'.join(f'{w}×{n}' for w, n in em.most_common(6))
+        out.append(_issue('info', 'ai', 'empty-adv', '全文',
+                          f'空洞副词密度高（每千字 {sum(em.values())/k:.1f} 处）：{top}',
+                          '', '「有效提升」→给提升了多少；给不出数字就删掉副词'))
+
+    cn = hits(AI_CONNECT)
+    if sum(cn.values()) >= 8 and sum(cn.values()) / k >= 3.0:
+        out.append(_issue('info', 'ai', 'connector', '全文',
+                          f'「首先/其次/再次」类连接词 {sum(cn.values())} 处，通篇同一套承接骨架',
+                          '', '改用小标题或直接分条，别用连接词假装有逻辑'))
+
+    dash = full.count('——')
+    if dash / k >= 3.0 and dash >= 5:
+        out.append(_issue('info', 'ai', 'dash-overuse', '全文',
+                          f'破折号 {dash} 处（每千字 {dash/k:.1f}），是模型口癖的显著特征',
+                          '', '大部分破折号可换成句号另起一句，或换成冒号'))
+
+    # 句式层：段首雷同
+    starts = Counter(t.strip()[:4] for t in texts if len(t.strip()) >= 8)
+    for pre, n in starts.most_common(3):
+        if n >= 4 and n / max(len(texts), 1) >= 0.25:
+            out.append(_issue('warn', 'ai', 'same-opening', '全文',
+                              f'{n} 个段落以「{pre}…」同样的方式开头（占 {n/len(texts)*100:.0f}%）',
+                              '', '把其中一半改成直接给结论或直接给数字'))
+            break
+
+    # 结构层一：段落长度过于均匀（人写的东西是参差的）
+    lens = [_cjk_len(t) for t in texts if _cjk_len(t) >= 20]
+    if len(lens) >= 6:
+        mu = sum(lens) / len(lens)
+        sd = math.sqrt(sum((x - mu) ** 2 for x in lens) / len(lens))
+        cv = sd / mu if mu else 1.0
+        if cv < 0.22:
+            out.append(_issue('warn', 'ai', 'uniform-para', '全文',
+                              f'{len(lens)} 个段落长度异常均匀（均值 {mu:.0f} 字，离散度 {cv:.2f}，'
+                              f'人写作通常 >0.35）——这是模板化生成最明显的指纹',
+                              '', '该长的写长、该一句带过的就一句：把最重要的一节扩到两倍，删掉凑数的段'))
+
+    # 结构层二：具体性锚点缺失
+    with_num = sum(1 for t in texts if SPECIFIC_RE.search(t))
+    if texts and with_num / len(texts) < 0.25 and len(texts) >= 8:
+        out.append(_issue('warn', 'ai', 'no-anchor', '全文',
+                          f'仅 {with_num}/{len(texts)} 个段落含数字（<25%），通篇在讲原则不讲事实',
+                          '', '每段至少落一个可核对的锚点：数量、日期、金额、比例、责任人'))
+    if not DATE_RE.search(full):
+        out.append(_issue('info', 'ai', 'no-date', '全文',
+                          '全文没有出现任何具体年月，进度与里程碑无法核对', '', '补上时间点'))
+
+    # 结构层三：每节字数过于均匀（比段落更强的指纹）
+    if heads:
+        out.extend(_section_evenness(heads, bodies))
+    return out
+
+
+def _section_evenness(heads, bodies):
+    """按标题切节，看各节篇幅是否被均匀摊平。切不出节就静默返回——宁可不报也不瞎报。"""
+    order = sorted(bodies + list(heads), key=lambda p: p.get('index', 0))
+    secs, cur = [], None
+    for p in order:
+        if p.get('kind') == 'heading':
+            if cur:
+                secs.append(cur)
+            cur = 0
+        elif cur is not None:
+            cur += _cjk_len(str(p.get('text', '')))
+    if cur is not None:
+        secs.append(cur)
+    secs = [s for s in secs if s >= 50]
+    if len(secs) < 5:
+        return []
+    mu = sum(secs) / len(secs)
+    sd = math.sqrt(sum((x - mu) ** 2 for x in secs) / len(secs))
+    cv = sd / mu if mu else 1.0
+    if cv < 0.25:
+        return [_issue('warn', 'ai', 'uniform-section', '全文',
+                       f'{len(secs)} 个章节篇幅异常均匀（均值 {mu:.0f} 字，离散度 {cv:.2f}）——'
+                       f'每节都写得一样长，说明是在填格子而不是在说事',
+                       '', '按重要性重新分配篇幅：核心章节写透，次要章节敢于只写三行')]
+    return []
+
+
+# ── 汇总入口 ───────────────────────────────────────────────────────────────
+def check(paras, strict=False):
+    """整篇体检：逐段 + 文档级。paras = [{'text','kind','loc','index'}]。"""
+    out = []
+    for p in paras:
+        out.extend(check_paragraph(p.get('text', ''), p.get('loc', ''), p.get('kind', 'body'), strict))
+    out.extend(check_document(paras, strict))
+    return out
+
+
+def from_markdown(path_or_text, is_path=True):
+    """Markdown/纯文本 → paras（供 CLI 与草稿预检用；表格行按 cell 处理）。"""
+    text = (open(path_or_text, encoding='utf-8-sig').read() if is_path
+            else str(path_or_text)).lstrip('\ufeff')
+    paras, buf = [], []
+    for i, raw in enumerate(text.splitlines() + ['']):
+        line = raw.rstrip()
+        m = re.match(r'^(#{1,6})\s+(.*)', line)
+        if m or not line.strip() or line.lstrip().startswith('|'):
+            if buf:
+                paras.append({'text': ' '.join(buf), 'kind': 'body',
+                              'loc': f'第 {i - len(buf) + 1} 行', 'index': len(paras)})
+                buf = []
+        if m:
+            paras.append({'text': m.group(2).strip(), 'kind': 'heading',
+                          'loc': f'第 {i+1} 行', 'index': len(paras)})
+        elif line.lstrip().startswith('|'):
+            paras.append({'text': line.strip().strip('|'), 'kind': 'cell',
+                          'loc': f'第 {i+1} 行', 'index': len(paras)})
+        elif line.strip():
+            buf.append(re.sub(r'^\s*(?:[-*+]|\d+[.、])\s*', '', line.strip()))
+    return paras
+
+
+LEVEL_ORDER = {'error': 0, 'warn': 1, 'info': 2}
+LEVEL_LABEL = {'error': '必修', 'warn': '建议', 'info': '提示'}
+GROUP_LABEL = {'text': '文字', 'punct': '标点', 'ai': 'AI 味',
+               'consistency': '一致性', 'structure': '结构'}
+
+
+def report(issues, limit_per_kind=4):
+    """把 issues 排成人读的报告（同类问题折叠，只列前几条 + 计数）。"""
+    if not issues:
+        return '文字体检：未发现问题。'
+    lines, counts = [], Counter(i['level'] for i in issues)
+    lines.append(f"文字体检：必修 {counts.get('error',0)} · 建议 {counts.get('warn',0)} · 提示 {counts.get('info',0)}")
+    grouped = defaultdict(list)
+    for it in issues:
+        grouped[(it['level'], it['group'], it['kind'])].append(it)
+    for key in sorted(grouped, key=lambda k: (LEVEL_ORDER[k[0]], k[1], k[2])):
+        lvl, grp, _ = key
+        items = grouped[key]
+        head = f"  [{LEVEL_LABEL[lvl]}·{GROUP_LABEL.get(grp, grp)}] {items[0]['msg']}"
+        if len(items) > 1:
+            head += f'（共 {len(items)} 处）'
+        lines.append(head)
+        for it in items[:limit_per_kind]:
+            where = f"{it['loc']} " if it['loc'] and it['loc'] != '全文' else ''
+            q = f"「{it['quote']}」" if it['quote'] else ''
+            sug = f" → {it['suggest']}" if it['suggest'] else ''
+            if where or q or sug:
+                lines.append(f'      · {where}{q}{sug}')
+        if len(items) > limit_per_kind:
+            lines.append(f'      · …另有 {len(items)-limit_per_kind} 处')
+    return '\n'.join(lines)
+
+
+def self_test():
+    bad = '本项目己经按装完成，采用了先进的技术,并且部署了系统;取得了显著成效。'
+    # 判据自检：带逗号的长句只该报 sent-run（且报的是最长那一截），不该报「整句过长」
+    _run = check_paragraph('研制一套面向 5000 节点规模的智能运维平台系统软件与配套工具链并完成部署，' * 1
+                           + '把时间压到 8 分钟。', 'R')
+    assert not any(i['kind'] == 'sent-long' for i in _run), _run
+    iss = check_paragraph(bad, 'T1')
+    kinds = {i['kind'] for i in iss}
+    assert 'typo' in kinds, kinds
+    # 这些是**合法中文**，一条都不许报重复
+    for ok_txt in ('明确项目目的的重要性。', '这和和平发展有关。', '为了了解情况。',
+                   '在在线账户权益领域，风险突出。', '项目的的确确完成了。',
+                   '把把手换掉。', '从从容容推进。', '认认真真核对一遍。'):
+        bad = [i for i in check_paragraph(ok_txt, 'F') if i['kind'] in ('dup-char', 'dup-phrase')]
+        assert not bad, (ok_txt, bad)
+    # 这些是真事故，必须报
+    assert any(i['kind'] == 'dup-char' for i in check_paragraph('这的的的确不对。', 'D'))
+    assert any(i['kind'] == 'dup-phrase' for i in check_paragraph('本项目本项目已完成。', 'P'))
+    assert {'half-comma', 'half-semi'} & kinds, kinds
+    assert check_paragraph('一、项目背景。', 'H', 'heading')[0]['kind'] == 'heading-period'
+    assert not check_paragraph('本季度交付 12 个模块，缺陷密度 0.8 个/千行。', 'OK')
+    assert not check_paragraph('—', 'CELL', 'cell'), '表格里当「无」用的占位符不该判成破折号错误'
+    assert any(i['kind'] == 'bad-dash' for i in check_paragraph('这里—用错了破折号。', 'D')), '真破折号误用要报'
+
+    # AI 味：同一批话堆到 1000 字以上才该报
+    ai = ('值得注意的是，本系统通过深度赋能业务闭环，有效提升了整体效能。'
+          '综上所述，该方案具有重要的现实意义，为后续工作奠定了坚实的基础。') * 20
+    paras = [{'text': ai[i:i+120], 'kind': 'body', 'index': i} for i in range(0, len(ai), 120)]
+    ks = {i['kind'] for i in check_document(paras)}
+    assert 'cliche' in ks and 'buzzword' in ks, ks
+    assert 'uniform-para' in ks or 'no-anchor' in ks, ks
+    # 反向：真实写作不应被判成 AI（长短参差 + 处处有数字）
+    real = [
+        {'text': '一期上线 3 个模块，比计划晚了 11 天，原因是甲方 4 月才给出接口口径。', 'kind': 'body', 'index': 0},
+        {'text': '延期没有影响验收：合同里的里程碑是 6 月 30 日，我们 6 月 18 日封版。', 'kind': 'body', 'index': 1},
+        {'text': '缺陷密度 0.62 个/千行。', 'kind': 'body', 'index': 2},
+        {'text': '压测在 800 并发下 P95 响应 340ms，未达 300ms 目标，二期做连接池改造。'
+                 '这是本期唯一没有兑现的指标，已写进遗留问题清单，责任人为张工，计划 9 月 15 日前关闭。', 'kind': 'body', 'index': 3},
+        {'text': '成本超了 8.4 万元，主要是压测环境多租了两个月机器。', 'kind': 'body', 'index': 4},
+        {'text': '2026 年 7 月 3 日通过内部评审。', 'kind': 'body', 'index': 5},
+    ] * 3
+    ks2 = {i['kind'] for i in check_document(real)}
+    assert 'cliche' not in ks2 and 'buzzword' not in ks2, ks2
+    assert 'no-anchor' not in ks2, ks2
+    assert 'term-variant' not in ks2, ks2          # 正常文字不该被判术语不一致
+    tv = [{'text': '本系统提供 API 接口。Api 需鉴权，api 限流 100 QPS，API 版本 v2。',
+           'kind': 'body', 'index': 0}]
+    assert any(i['kind'] == 'term-variant' for i in check_document(tv * 2)), '大小写不一致漏报'
+    print('[zh_prose] self-test OK ·', f'规则 {len(TYPOS)} 错别字 / {len(CONFUSABLES)} 易混 / '
+          f'{len(PUNCT_RULES)} 标点 / {len(AI_CLICHE)+len(AI_BUZZ)} AI 词条')
+
+
+if __name__ == '__main__':
+    args = [a for a in sys.argv[1:] if not a.startswith('-')]
+    if not args:
+        self_test()
+    else:
+        print(report(check(from_markdown(args[0]), strict='--strict' in sys.argv)))