Skip to content

topmindspace/topmind-writing-skills / topmind-wechat-post

topmind-wechat-post

Verified

创作、整理和排版公众号文章;支持工具/插件推荐结构、产品实测评测、深度解读与叙事随笔,从选题或底稿到 Markdown,按需导出内联 HTML、预览与上传清单。公众号短文用 topmind-briefs,独立改稿用 topmind-revise。

FileKindSize
.gitignoreother31 B
README.en.mdmarkdown2.0 KB
README.mdmarkdown2.2 KB
SKILL.mdskill md5.5 KB
assets/themes/amber-review.jsonconfig979 B
assets/themes/graphite.jsonconfig971 B
assets/themes/md3-business-blue.jsonconfig895 B
assets/themes/minimal-ink.jsonconfig965 B
assets/themes/newsprint.jsonconfig936 B
assets/themes/tech-blue.jsonconfig957 B
examples/01-公众号-整理书架.mdmarkdown1.7 KB
examples/02-公众号-第一次养绿植.mdmarkdown1.8 KB
examples/README.mdmarkdown667 B
knowledge/README.mdmarkdown9.4 KB
knowledge/cards/atlas-local-fix.mdmarkdown781 B
knowledge/cards/brief-news-to-post.mdmarkdown3.0 KB
knowledge/cards/brief-news.mdmarkdown916 B
knowledge/cards/brief-paper.mdmarkdown760 B
knowledge/cards/brief-tools.mdmarkdown617 B
knowledge/cards/brief-value-first.mdmarkdown3.1 KB
knowledge/cards/cover-abstract.mdmarkdown1.3 KB
knowledge/cards/cover-brief.mdmarkdown1.3 KB
knowledge/cards/cover-collage.mdmarkdown1.3 KB
knowledge/cards/cover-color.mdmarkdown1.2 KB
knowledge/cards/cover-culture.mdmarkdown1013 B
knowledge/cards/cover-editorial.mdmarkdown1.2 KB
knowledge/cards/cover-material.mdmarkdown1.3 KB
knowledge/cards/cover-photo.mdmarkdown1.1 KB
knowledge/cards/cover-playful.mdmarkdown1.0 KB
knowledge/cards/cover-scene.mdmarkdown962 B
knowledge/cards/cover-series.mdmarkdown1017 B
knowledge/cards/cover-typography.mdmarkdown1.3 KB
knowledge/cards/creative-choice.mdmarkdown807 B
knowledge/cards/crop-independent.mdmarkdown719 B
knowledge/cards/de-ai-mechanisms.mdmarkdown3.6 KB
knowledge/cards/experience-loop.mdmarkdown801 B
knowledge/cards/format-fidelity.mdmarkdown501 B
knowledge/cards/format-layouts.mdmarkdown502 B
knowledge/cards/poster-paging.mdmarkdown726 B
knowledge/cards/poster-structure.mdmarkdown646 B
knowledge/cards/poster-voices.mdmarkdown530 B
knowledge/cards/reference-reading.mdmarkdown857 B
knowledge/cards/revise-depth.mdmarkdown677 B
knowledge/cards/revise-feedback.mdmarkdown609 B
knowledge/cards/revise-learn-from-edits.mdmarkdown3.1 KB
knowledge/cards/revise-preserve.mdmarkdown788 B
knowledge/cards/viral-mechanisms.mdmarkdown535 B
knowledge/cards/viral-observation.mdmarkdown544 B
knowledge/cards/viral-play-dumb.mdmarkdown2.8 KB
knowledge/cards/viral-replies.mdmarkdown722 B
knowledge/cards/visual-density-and-evidence.mdmarkdown2.8 KB
knowledge/cards/voice-peer-stance.mdmarkdown2.7 KB
knowledge/cards/wechat-decide.mdmarkdown746 B
knowledge/cards/wechat-explain.mdmarkdown820 B
knowledge/cards/wechat-plugin-and-review.mdmarkdown2.5 KB
knowledge/cards/wechat-story.mdmarkdown798 B
knowledge/cards/x-adapt.mdmarkdown643 B
knowledge/cards/x-argument.mdmarkdown770 B
knowledge/cards/x-evidence.mdmarkdown608 B
knowledge/index.jsonconfig39.9 KB
package.jsonmanifest464 B
references/case-notes.mdmarkdown1.9 KB
references/core-voice.mdmarkdown9.9 KB
references/creative-practice.mdmarkdown5.0 KB
references/de-ai-rules.mdmarkdown17.9 KB
references/element-spec.mdmarkdown9.7 KB
references/image-sourcing.mdmarkdown2.7 KB
references/information-design.mdmarkdown5.0 KB
references/knowledge-library.mdmarkdown5.5 KB
references/known-pits.mdmarkdown3.9 KB
references/platform-cover-specs.mdmarkdown7.4 KB
references/platform-operations.mdmarkdown12.2 KB
references/research-mode.mdmarkdown1.6 KB
references/revision-workflow.mdmarkdown5.9 KB
references/social-writing-principles.mdmarkdown7.7 KB
references/theme-map.mdmarkdown6.6 KB
references/typography-rules.mdmarkdown1.6 KB
references/wechat-constraints.mdmarkdown7.2 KB
references/workflow.mdmarkdown6.5 KB
references/workspace.mdmarkdown2.3 KB
references/writing-quality.mdmarkdown2.0 KB
references/x-delivery-contract.mdmarkdown3.6 KB
references/x-post-format.mdmarkdown2.5 KB
scripts/article_scaffold.pyscript5.6 KB
scripts/audit-provenance.pyscript14.9 KB
scripts/audit_css.pyscript1.1 KB
scripts/audit_docs.pyscript3.1 KB
scripts/audit_skill.pyscript3.1 KB
scripts/audit_styles.pyscript1.6 KB
scripts/check_article.pyscript13.9 KB
scripts/count_words.pyscript3.0 KB
scripts/de_ai_lint.pyscript41.5 KB
scripts/info_design_hints.pyscript14.2 KB
scripts/knowledge.pyscript11.8 KB
scripts/lint-wechat.pyscript18.5 KB
scripts/lint_x_post.pyscript20.0 KB
scripts/md2wechat.pyscript83.6 KB
scripts/negative_tests.pyscript24.9 KB
scripts/new-article.pyscript10.3 KB
scripts/package_skill.pyscript6.6 KB
scripts/push-to-topstream.pyscript9.7 KB
scripts/revise_check.pyscript15.2 KB
scripts/scan_ai_flavor.pyscript2.6 KB
scripts/scan_ai_flavor_builtin.pyscript6.5 KB
scripts/sync-mapping.pyscript8.4 KB
scripts/sync-status.pyscript6.9 KB
scripts/wechat_paths.pyscript4.7 KB

scripts/md2wechat.py

View on GitHub
#!/usr/bin/env python3
# -*- coding: utf-8 -*-
"""md2wechat v2 — Markdown -> WeChat MP inline-style HTML.

Zero dependency (stdlib only). WeChat's rich text editor strips <style> blocks
and class attributes, so every style in the output is inlined.

Supported beyond CommonMark:
  - code syntax highlighting (inline span colors, no <style>)
  - ::: container blocks (note/tip/warn/danger/pull/dialogue/stat) — legacy packages only;
    new single-source drafts use plain Markdown
  - [!badge] inline tags, ==highlight== (legacy, still rendered)
  - HTML comments (<!-- writing notes -->, may span lines) are dropped; code keeps them
  - footnote link mode (external links -> end-of-article index)
  - CJK "pangu" spacing between Han and Latin/digits
  - four heading-2 style variants

Usage:
    python3 md2wechat.py --input <文章名>/<文章名>.md --embed-images
        # 文章文件夹结构:--out-dir 缺省 <文章名>/out,--slug 缺省文件名,
        # --asset-root 缺省文章文件夹
    python3 md2wechat.py --input 稿.md --out-dir 交付包 --slug foo \
        --asset-root /path/to/repo [--theme theme.json] [--link-mode footnote] \
        [--embed-images] [--auto-number]

Headings: 二级标题写了「一、」「1.」这类手写序号就原样保留,不再自动编号;
都没写时按主题样式自动编号。--auto-number 恢复旧行为(剥离手写序号后统一编号)。
Images: 图片后紧跟(或隔一个空行)的「来源:……」行渲染成图注样式。

Outputs:
    <out-dir>/<slug>-公众号版.html   full page, copy body section into WeChat
    <out-dir>/images/*               local image assets
    <out-dir>/diagrams/*             extracted mermaid sources (+ png if rendered)
    <out-dir>/图片上传清单.md         manual upload checklist

--embed-images: 把正文 <img> 的本地路径换成 base64 data URI。
公众号后台拿到相对路径或本地/内网地址时无法取图,粘贴过去图片会整段消失;
base64 内嵌后图片字节随剪贴板一起过去,粘贴即带图。images/ 仍照常导出,
作为「后台显示占位符时手动补传」的兜底。
"""

import argparse
import base64
import html
import json
import os
import re
import shutil
import subprocess
import sys

# ---------------------------------------------------------------- theme

DEFAULT_THEME = {
    "id": "md3-business-blue",
    "name": "MD3 商务蓝",
    "genre": ["通用", "商务", "AI/技术", "教程", "评测"],
    "accent": "#0B57D0",
    # accent 的浅化与淡化变体:下划线与浅底高亮都必须与主色同源,
    # 否则主题一换就会露出上一套主题的色(历史 bug:tech-blue 继承砖红 mark_bg)。
    "accent_light": "#7CACF8",
    "accent_soft": "#E8F0FE",
    "accent_container": "#D3E3FD",
    "text": "#1F1F1F",
    "text_strong": "#0B1F3A",
    "text_muted": "#5F6368",
    "text_light": "#80868B",
    "surface": "#F8FAFD",
    "surface_container": "#EDF2FA",
    "border": "#C4C7C5",
    "code_bg": "#1A1C1E",
    "code_text": "#E3E2E6",
    "c_note": "#7CACF8",
    "c_tip": "#146C2E",
    "c_warn": "#B06000",
    "c_danger": "#B3261E",
    "mark_bg": "#E8F0FE",
    "radius": "16px",
    "radius_small": "8px",
    "font_size": "16px",
    "line_height": "1.75",
    "para_gap": "24px",
    # 公众号只认 left / center / right,justify 会被判为非标准值
    "align": "left",
    "h2_style": "number",
    "toc": True,
    "toc_max": 5,
    "toc_min_h2": 4,
    "toc_min_chars": 2000,
    "table_max_cols": 3,
    "code_scheme": "mono",
    "img_border": "#E8F0FE",
    "font_stack": (
        "-apple-system,BlinkMacSystemFont,'Helvetica Neue',"
        "'PingFang SC','Hiragino Sans GB','Microsoft YaHei',sans-serif"
    ),
    "mono_stack": "Menlo,Monaco,Consolas,'Courier New',monospace",
}

# Material Palenight derived, desaturated to survive on #2C2C2C
HIGHLIGHT = {
    "comment": "#6B7A8F",
    "string": "#C3E88D",
    "number": "#F78C6C",
    "keyword": "#C792EA",
    "builtin": "#FFCB6B",
    "func": "#82AAFF",
    "variable": "#FFCB6B",
    "op": "#89DDFF",
    "key": "#82AAFF",
    "punct": "#89DDFF",
    "flag": "#FFCB6B",
    "tag": "#F07178",
    "attr": "#FFCB6B",
    "add": "#C3E88D",
    "del": "#E58B7F",
    "meta": "#6B7A8F",
}

# ordered rules: earlier patterns win
LANG_RULES = {
    "python": [
        ("comment", r"#[^\n]*"),
        ("string", r'"""[\s\S]*?"""|\'\'\'[\s\S]*?\'\'\'|"(?:\\.|[^"\\\n])*"|\'(?:\\.|[^\'\\\n])*\''),
        ("keyword", r"\b(?:def|class|if|elif|else|for|while|return|import|from|as|try|except|finally|with|lambda|yield|pass|break|continue|in|is|not|and|or|None|True|False|self|async|await|raise|assert|global|del|match|case)\b"),
        ("builtin", r"\b(?:print|len|range|int|str|float|list|dict|set|tuple|open|enumerate|zip|map|filter|sum|min|max|abs|sorted|type|isinstance|super|getattr|setattr|hasattr)\b"),
        ("func", r"\b[A-Za-z_]\w*(?=\s*\()"),
        ("number", r"\b\d+\.?\d*\b"),
        ("op", r"[=+\-*/%<>!&|^~]+"),
    ],
    "js": [
        ("comment", r"//[^\n]*|/\*[\s\S]*?\*/"),
        ("string", r"`(?:\\.|[^`\\])*`|\"(?:\\.|[^\"\\\n])*\"|'(?:\\.|[^'\\\n])*'"),
        ("keyword", r"\b(?:const|let|var|function|return|if|else|for|while|class|extends|new|await|async|import|export|from|default|try|catch|finally|throw|typeof|instanceof|this|super|null|undefined|true|false|switch|case|break|continue|delete|in|of|yield|static|get|set)\b"),
        ("builtin", r"\b(?:console|JSON|Math|Object|Array|String|Number|Boolean|Promise|window|document|require|module|exports|process)\b"),
        ("func", r"\b[A-Za-z_$]\w*(?=\s*\()"),
        ("number", r"\b\d+\.?\d*\b"),
        ("op", r"[=+\-*/%<>!&|^~?:]+"),
    ],
    "json": [
        ("key", r'"(?:\\.|[^"\\])*"(?=\s*:)'),
        ("string", r'"(?:\\.|[^"\\])*"'),
        ("keyword", r"\b(?:true|false|null)\b"),
        ("number", r"-?\b\d+\.?\d*(?:[eE][+-]?\d+)?\b"),
        ("punct", r"[{}\[\],:]"),
    ],
    "bash": [
        ("comment", r"#[^\n]*"),
        ("string", r'"(?:\\.|[^"\\])*"|\'(?:\\.|[^\'\\])*\''),
        ("variable", r"\$\w+|\$\{[^}]*\}"),
        ("keyword", r"\b(?:if|then|else|fi|for|in|do|done|while|case|esac|function|return|export|local|source)\b"),
        ("builtin", r"\b(?:npm|npx|node|python3?|pip3?|git|docker|curl|wget|vercel|mmdc|openssl|mkdir|cp|mv|rm|ls|cat|grep|sed|awk|trash|open|echo|cd|sudo|chmod|kill|ps|top)\b"),
        ("flag", r"(?<=\s)-{1,2}[\w-]+"),
        ("op", r"[|&;<>]+"),
    ],
    "yaml": [
        ("comment", r"#[^\n]*"),
        ("key", r"^\s*[\w.\-/]+(?=\s*:)"),
        ("string", r'"(?:\\.|[^"\\])*"|\'(?:\\.|[^\'\\])*\''),
        ("keyword", r"\b(?:true|false|null|yes|no|on|off)\b"),
        ("number", r"\b\d+\.?\d*\b"),
        ("punct", r"[-:]"),
    ],
    "sql": [
        ("comment", r"--[^\n]*"),
        ("string", r"'(?:\\.|[^'\\])*'"),
        ("keyword", r"\b(?:SELECT|FROM|WHERE|INSERT|INTO|VALUES|UPDATE|SET|DELETE|CREATE|TABLE|ALTER|DROP|JOIN|LEFT|RIGHT|INNER|OUTER|ON|GROUP|BY|ORDER|LIMIT|OFFSET|AS|AND|OR|NOT|NULL|IS|IN|LIKE|COUNT|SUM|AVG|MAX|MIN|DISTINCT|INDEX|PRIMARY|KEY|DEFAULT|CASCADE|WITH|UNION|HAVING)\b"),
        ("number", r"\b\d+\.?\d*\b"),
        ("op", r"[=<>!*/+\-]+"),
    ],
    "diff": [
        ("meta", r"^@@[^\n]*|^---[^\n]*|^\+\+\+[^\n]*"),
        ("add", r"^\+[^\n]*"),
        ("del", r"^-[^\n]*"),
    ],
    "html": [
        ("comment", r"<!--[\s\S]*?-->"),
        ("string", r'"(?:\\.|[^"\\])*"|\'(?:\\.|[^\'\\])*\''),
        ("tag", r"</?[A-Za-z][\w:.-]*|/?>"),
        ("attr", r"[\w:.-]+(?=\s*=)"),
        ("punct", r"[=]"),
    ],
    "css": [
        ("comment", r"/\*[\s\S]*?\*/"),
        ("keyword", r"@[\w-]+"),
        ("string", r'"(?:\\.|[^"\\])*"|\'(?:\\.|[^\'\\])*\''),
        ("key", r"[\w-]+(?=\s*:)"),
        ("number", r"-?\b\d+\.?\d*(?:px|em|rem|%|vh|vw|s|ms)?\b|#[0-9a-fA-F]{3,8}"),
        ("punct", r"[{}\[\],;:]"),
    ],
}

LANG_ALIASES = {
    "javascript": "js", "jsx": "js", "typescript": "js", "ts": "js", "tsx": "js",
    "py": "python", "sh": "bash", "shell": "bash", "zsh": "bash", "console": "bash",
    "yml": "yaml", "xml": "html", "vue": "html", "scss": "css", "less": "css",
    "http": "json", "diff": "diff", "patch": "diff",
}


def build_code_scheme(theme):
    """按主题生成代码高亮色板。

    默认 mono:只用「主色 + 明暗层级」,不引入第二套色彩语言。
    历史问题:代码块固定用 Material Palenight 的 16 色(天蓝/蓝/绿/橙/紫),
    与砖红主题毫无关系,一篇文章里出现两套色板,读者会觉得是另一个号。
    """
    if theme.get("code_scheme") == "palenight":
        return dict(HIGHLIGHT)
    base = theme.get("code_text", "#E8E8E8")
    bg = theme.get("code_bg", "#2C2C2C")
    acc = mix_hex(theme.get("accent", "#A6524A"), "#FFFFFF", 0.34)
    dim = mix_hex(base, bg, 0.46)
    mid = mix_hex(base, bg, 0.20)
    return {
        "comment": dim, "meta": dim,
        "string": mid, "number": mid,
        "keyword": acc, "tag": acc, "del": acc,
        "builtin": base, "func": base, "variable": base,
        "op": mid, "key": mid, "punct": mid, "flag": mid,
        "attr": mid, "add": mid,
    }


def highlight(code, lang, scheme=None):
    """Inline-span syntax highlighting (no <style>, no class)."""
    key = LANG_ALIASES.get(lang, lang)
    rules = LANG_RULES.get(key)
    if not rules:
        return html.escape(code, quote=False)
    palette = scheme or CTX.get("hl_scheme") or HIGHLIGHT
    pattern = _HL_PATTERN_CACHE.get(key)
    if pattern is None:
        # (?m) 不能写进单个分支:拼成 alternation 后它就不在表达式开头了,
        # Python 会报 "global flags not at the start"(历史 crash:```yaml / ```diff
        # 代码块直接 Traceback)。MULTILINE 在编译期统一加,分支里只留 ^。
        pattern = re.compile("|".join("(?P<%s>%s)" % (name, pat) for name, pat in rules), re.S | re.M)
        _HL_PATTERN_CACHE[key] = pattern
    out = []
    pos = 0
    for m in pattern.finditer(code):
        if m.start() > pos:
            out.append(html.escape(code[pos:m.start()], quote=False))
        color = palette.get(m.lastgroup)
        text = html.escape(m.group(), quote=False)
        out.append('<span style="color:%s;">%s</span>' % (color, text) if color else text)
        pos = m.end()
    out.append(html.escape(code[pos:], quote=False))
    return "".join(out)


THEME_DIR = os.path.normpath(os.path.join(
    os.path.dirname(os.path.abspath(__file__)), "..", "assets", "themes"))


def list_themes():
    """列出 assets/themes/ 下所有可用主题(按题材分主题的清单来源)。"""
    out = []
    if not os.path.isdir(THEME_DIR):
        return out
    for fn in sorted(os.listdir(THEME_DIR)):
        if not fn.endswith(".json"):
            continue
        path = os.path.join(THEME_DIR, fn)
        try:
            with open(path, encoding="utf-8") as fh:
                d = json.load(fh)
        except Exception:
            continue
        out.append({
            "file": path, "stem": fn[:-5],
            "id": d.get("id", fn[:-5]), "name": d.get("name", fn[:-5]),
            "genre": d.get("genre", []), "accent": d.get("accent", ""),
            "h2_style": d.get("h2_style", ""),
        })
    return out


def resolve_theme(spec):
    """把 --theme 的值解析成主题文件路径。

    支持三种写法,降低「按题材换主题」的使用门槛:
      1. 空串            -> 用 DEFAULT_THEME(不读文件)
      2. 主题名 / 标识   -> 在 assets/themes/ 里按 id、文件名、中文名匹配
      3. 文件路径        -> 直接读
    另有 "genre:题材" 语法按题材自动选主题(方案 B 的入口)。
    """
    if not spec:
        return None
    if os.path.exists(spec):
        return spec
    themes = list_themes()
    if spec.startswith("genre:"):
        want = spec.split(":", 1)[1].strip()
        for t in themes:
            if want in t["genre"]:
                return t["file"]
        raise SystemExit("没有主题声明题材「%s」。各主题题材见 references/theme-map.md" % want)
    low = spec.strip().lower()
    for t in themes:
        if low in (t["id"].lower(), t["stem"].lower(), t["name"].lower()):
            return t["file"]
    raise SystemExit("未知主题:%s\n可用主题:%s" % (
        spec, "、".join("%s(%s)" % (t["name"], t["id"]) for t in themes) or "(无)"))


def load_theme(spec):
    base = dict(DEFAULT_THEME)
    path = resolve_theme(spec)
    if not path:
        return base
    try:
        with open(path, encoding="utf-8") as fh:
            data = json.load(fh)
    except (OSError, ValueError) as e:
        # ValueError 覆盖 json.JSONDecodeError:坏掉的主题文件给干净报错,不抛 Traceback
        sys.exit("错误:主题文件无法解析 %s(%s)" % (path, e))
    accent = data.get("accent", base["accent"])
    # 主色派生字段必须按「本主题」的主色重算,不能继承默认主题的值:
    # 默认主题的 accent_light / mark_bg 是砖红系,继承过来会让蓝色或灰色主题里
    # 冒出砖红下划线和砖红高亮底——这正是 tech-blue 等主题当年从没被启用的原因。
    data.setdefault("accent_light", mix_hex(accent, "#FFFFFF", 0.62))
    data.setdefault("accent_soft", mix_hex(accent, "#FFFFFF", 0.92))
    data.setdefault("mark_bg", data["accent_soft"])
    theme = dict(base)
    theme.update(data)
    theme.setdefault("id", os.path.basename(path)[:-5])
    return theme


def mix_hex(a, b, ratio):
    """把 a 往 b 混 ratio 比例(0=全 a,1=全 b)。主题色派生用,避免手填出错。"""
    a = a.lstrip("#")
    b = b.lstrip("#")
    if len(a) != 6 or len(b) != 6:
        return "#" + a
    out = []
    for i in (0, 2, 4):
        va, vb = int(a[i:i + 2], 16), int(b[i:i + 2], 16)
        out.append("%02X" % int(round(va + (vb - va) * ratio)))
    return "#" + "".join(out)


# ---------------------------------------------------------------- inline

# shared render state, set once per convert() run
CTX = {
    "theme": DEFAULT_THEME,
    "link_mode": "footnote",
    "footnotes": [],
    "use_pangu": True,
}

CODE_TOKEN = "\x00C%d\x00"
HAN = r"\u4e00-\u9fff\u3400-\u4dbf"
HAN_RE = re.compile("[%s]" % HAN)
PANGU_A = re.compile(r"([%s])([A-Za-z0-9])" % HAN)
PANGU_B = re.compile(r"([A-Za-z0-9])([%s])" % HAN)

# render_inline() 的行内模式:预编译在模块级,避免每行重复走 re 缓存查找
# (666k 行级调用 × 10 个模式时,re.sub 的字符串模式查找是可观开销)。
INLINE_CODE_RE = re.compile(r"`([^`]+)`")


def _parse_paren(s, j):
    """s[j] == '(' 时找与之匹配的 ')'(括号可嵌套:URL 里允许出现平衡括号,如维基链接)。

    返回 (括号内文本, 右括号之后的位置);括号不平衡返回 None。
    """
    depth = 0
    k, n = j, len(s)
    while k < n:
        c = s[k]
        if c == "(":
            depth += 1
        elif c == ")":
            depth -= 1
            if depth == 0:
                return s[j + 1:k], k + 1
        k += 1
    return None


# `(url)` / `(url "title")` / `(url 'title')` / `(url (title))` → url(title 丢弃)。
_URL_TITLE_RE = re.compile(r'^(\S+?)(?:\s+(?:"[^"]*"|\'[^\']*\'|\([^()]*\)))?\s*$')


def _split_url_title(inner):
    """把链接/图片括号内的 `url "title"` 拆出 url(title 丢弃)。

    裸 url 不得含空白:含裸空白时返回 ""(调用方保留原文,
    与旧正则 `[^)\\s]+` 的行为一致,不静默吞掉)。
    """
    m = _URL_TITLE_RE.match(inner.strip())
    return m.group(1) if m else ""


def _scan_md_links(text, img, repl):
    """扫描替换行内图片/链接,url 括号支持嵌套、可带 "title"。

    img=True 扫 ![alt](src),False 扫 [label](url);repl(文本, url) -> 替换串。
    括号不平衡、url 为空、url 含裸空白时保留原文(旧正则同样认不出这些写法,
    保留原文比截断 URL 更安全——历史 bug:`![a](img(1).png)` 被截成 `img(1`,
    文件明明存在却被记成缺失;`[维基](…/猫_(动物))` 的 URL 被截断、正文多个 `)`)。
    """
    open_tok = "![" if img else "["
    skip = len(open_tok)
    res = []
    i, n = 0, len(text)
    while i < n:
        if text.startswith(open_tok, i):
            k = text.find("]", i + skip)
            if k != -1 and k + 1 < n and text[k + 1] == "(":
                parsed = _parse_paren(text, k + 1)
                if parsed:
                    url = _split_url_title(parsed[0])
                    if url:
                        res.append(repl(text[i + skip:k], url))
                        i = parsed[1]
                        continue
        res.append(text[i])
        i += 1
    return "".join(res)
INLINE_BADGE_RE = re.compile(r"\[!([^\]]+)\]")
INLINE_HL_RE = re.compile(r"==([^=]+)==")
INLINE_UNDER_RE = re.compile(r"\+\+([^+]+)\+\+")
INLINE_U_RE = re.compile(r"&lt;u&gt;(.+?)&lt;/u&gt;")
INLINE_MARK_RE = re.compile(r"~~([^~]+)~~")
INLINE_STRONG_RE = re.compile(r"\*\*([^*]+)\*\*")
INLINE_EM_RE = re.compile(r"(?<![*\w])\*([^*\n]+)\*(?!\*)")

# highlight() 的语言联合模式缓存:同一语言的多段代码块只编译一次
_HL_PATTERN_CACHE = {}


def pangu(text):
    text = PANGU_A.sub(r"\1 \2", text)
    text = PANGU_B.sub(r"\1 \2", text)
    return text


def esc(text):
    return html.escape(text, quote=False)


def render_inline(raw):
    """Escape + markdown inline -> HTML with inline styles.

    Reads shared state from CTX so links/footnotes resolve across all
    block types (paragraphs, tables, lists, containers) uniformly.
    """
    theme = CTX["theme"]
    link_mode = CTX["link_mode"]
    footnotes = CTX["footnotes"]
    use_pangu = CTX["use_pangu"]
    spans = []

    def stash(code):
        spans.append(code)
        return CODE_TOKEN % (len(spans) - 1)

    text = esc(raw)
    text = INLINE_CODE_RE.sub(lambda m: stash(m.group(1)), text)

    if use_pangu:
        text = pangu(text)

    strong = 'font-weight:600;color:%s;' % theme["text_strong"]
    em = 'font-style:normal;color:%s;' % theme["text_muted"]

    # images(行内图与独立成行图共用同一括号语义)
    def img_repl(alt, src):
        # 行内图片同样走图片管线:本地文件解析 → 复制到 images/ → 登记清单,
        # 否则 --embed-images 找不到文件、清单漏项、计数为 0(历史 bug:
        # 段落里的 ![alt](x.png) 被原样保留相对路径,粘贴到公众号后整图消失)。
        resolver = CTX.get("img_resolve")
        if resolver and not re.match(r"^(https?:|data:|//)", src):
            src = resolver(html.unescape(src))
        caption = ' alt="%s"' % alt if alt else ""
        return ('<img src="%s"%s style="max-width:100%%;height:auto;'
                'border-radius:3px;vertical-align:middle;">') % (src, caption)

    text = _scan_md_links(text, True, img_repl)

    # links
    def link_repl(label, url):
        # 入口处已 esc():先还原,插入点与脚注登记处再按需转义。
        # 否则脚注列表里 URL 的 & 会被 esc 两次、显示成 &amp;(历史 bug)。
        label, url = html.unescape(label), html.unescape(url)
        if link_mode == "footnote" and footnotes is not None:
            # url→序号字典:原写法每次链接都扫全表两次(O(n²)),长文链接多时明显变慢
            fidx = CTX.get("footnote_idx")
            if fidx is not None and url in fidx:
                idx = fidx[url]
            elif fidx is not None:
                footnotes.append({"url": url, "label": label})
                idx = len(footnotes)
                fidx[url] = idx
            else:  # 外部直接调 render_inline 且未初始化索引时,走原来的线性查找
                if url not in [f["url"] for f in footnotes]:
                    footnotes.append({"url": url, "label": label})
                idx = [f["url"] for f in footnotes].index(url) + 1
            return ('%s<sup style="font-size:11px;color:%s;'
                    'padding-left:1px;">[%d]</sup>'
                    % (esc(label), theme["accent"], idx))
        if link_mode == "inline":
            return ('%s<span style="font-size:13px;color:%s;">(%s)</span>'
                    % (esc(label), theme["text_light"], esc(url)))
        return ('<span style="font-size:13px;color:%s;word-break:break-all;">'
                '%s(%s)</span>' % (theme["text_light"], esc(label), esc(url)))

    text = _scan_md_links(text, False, link_repl)

    # badges: [!文本]
    # 不用 display:inline-block:公众号对非常规 display 值支持不稳定,
    # 徽章是纯行内元素,padding 足够撑开视觉。
    text = INLINE_BADGE_RE.sub(
        r'<span style="font-size:11px;line-height:1.6;'
        r'color:' + theme["accent"] + r';background:' + theme["accent_soft"] + r';'
        r'padding:1px 6px;border-radius:2px;margin:0 2px;'
        r'font-weight:600;">\1</span>',
        text,
    )

    # ==高亮== before bold so inner markup still works
    text = INLINE_HL_RE.sub(
        r'<strong style="font-weight:600;color:' + theme["text_strong"] + r';'
        r'background:' + theme["accent_soft"] + r';padding:1px 3px;'
        r'border-radius:2px;">\1</strong>',
        text,
    )

    # ++下划线++ / <u>下划线</u>:兼容读取旧稿的扩展标记,照常渲染;
    # 新稿是单源纯 Markdown,不再建议写。esc() 已把 <u> 转义,故这里匹配实体。
    underline = ('<span style="border-bottom:2px solid %s;font-weight:600;'
                 'color:%s;">\\1</span>'
                 % (theme["accent_light"], theme["text_strong"]))
    text = INLINE_UNDER_RE.sub(underline, text)
    text = INLINE_U_RE.sub(underline, text)

    # ~~荧光笔~~:半高亮。用纯色浅底,不用 linear-gradient
    # (渐变在公众号会被静默丢弃,退化成无底)。
    text = INLINE_MARK_RE.sub(
        r'<span style="background:%s;font-weight:600;color:%s;">\1</span>'
        % (theme["accent_soft"], theme["text_strong"]),
        text,
    )

    text = INLINE_STRONG_RE.sub(r'<strong style="%s">\1</strong>' % strong, text)
    text = INLINE_EM_RE.sub(r'<em style="%s">\1</em>' % em, text)

    for idx, code in enumerate(spans):
        text = text.replace(
            CODE_TOKEN % idx,
            '<code style="background:%s;color:%s;padding:2px 5px;'
            'border-radius:3px;font-size:14px;font-family:%s;word-break:break-all;">%s</code>'
            % (theme["surface"], theme["accent"], theme["mono_stack"], code),
        )
    return text


# ---------------------------------------------------------------- blocks

HEADING_RE = re.compile(r"^(#{1,6})\s+(.*)$")
# 围栏反引号数 >= 3:```` 开栏只能由 >= 4 反引号闭合(CommonMark),
# 否则 markdown 示例代码里的内层 ``` 会把外层栏提前"闭合",造成静默错排。
FENCE_RE = re.compile(r"^(`{3,})(\w*)\s*$")
HR_RE = re.compile(r"^(-{3,}|\*{3,}|_{3,})\s*$")


def match_img_only(line):
    """独立成行图片:![alt](src) 独占一行(src 括号可嵌套、可带 title)。

    返回 (alt, src),不是独立成行图片返回 None。
    与行内图片共用同一括号语义(_parse_paren + _split_url_title)。
    """
    if not line.startswith("!["):
        return None
    k = line.find("]", 2)
    if k == -1:
        return None
    j = k + 1
    if j >= len(line) or line[j] != "(":
        return None
    parsed = _parse_paren(line, j)
    if not parsed:
        return None
    src = _split_url_title(parsed[0])
    if not src or line[parsed[1]:].strip():
        return None
    return line[2:k], src
CAPTION_RE = re.compile(r"^\*(.+)\*\s*$")
# 图片后紧跟的「来源:」行渲染成图注(core-voice V14);中间最多隔一个空行
SOURCE_RE = re.compile(r"^(来源[::].+)$")
TABLE_SEP_RE = re.compile(r"^\|?[\s:|-]+\|[\s:|-]*$")
CONTAINER_RE = re.compile(r"^:::+\s*(\w+)?\s*(.*)$")

CN_NUM = "一二三四五六七八九十壹贰叁肆伍陆柒捌玖拾"

# 标题里手写的中文/阿拉伯序号。默认:稿子里的二级标题带手写序号(「一、」「1.」)就原样保留,
# 排版层不再自动编号;二级标题都没写序号时才按主题样式自动编号。--auto-number 恢复旧行为:
# 一律剥离手写序号后由排版层重新编号。
# 注意:\d{1,2}[、..](?!\d) 带负向断言,避免把「3.4× 成本」这类
# 以数字开头的标题误剥成「4× 成本」。
HAND_NUM_RE = re.compile(
    r"^(?:第\s*[" + CN_NUM + r"]{1,3}\s*[、..]?\s*"
    r"|[" + CN_NUM + r"]{1,3}\s*[、..]\s*"
    r"|\d{1,2}\s*[、..](?!\d)\s*"
    r"|0\d\s+)"
)

# 末章若是收束类(总结/结语/小结…),编号改用 ∞ 而不是顺延的数字——
# 数字编号暗示「还有下一节」,收束章用数字会和读者预期打架。
# 只在 h2_style 含 number 时生效(其它样式本来就不输出编号)。
SUMMARY_H2_RE = re.compile(
    r"^(?:总结|结语|小结|尾声|后记|写在最后|写在后面|收尾|结尾|余论|结语与展望)"
)


def split_row(line):
    return [c.strip() for c in line.strip().strip("|").split("|")]


def is_list_item(line):
    return bool(re.match(r"^\s*([-*+]|\d+[.)])\s+", line))


def list_meta(line):
    m = re.match(r"^(\s*)([-*+]|\d+[.)])\s+(.*)$", line)
    indent = len(m.group(1).replace("\t", "    ")) // 2
    return indent, m.group(2), m.group(3)


def para_style(theme):
    return ("margin:0 0 %s;line-height:%s;letter-spacing:0.5px;"
            "text-align:%s;word-break:break-word;"
            % (theme["para_gap"], theme["line_height"], theme["align"]))


def keep_hand_num(theme):
    return bool(theme.get("_keep_hand_num"))


def detect_hand_numbers(lines):
    """二级标题里有没有手写序号(「一、」「1.」「第一章」)。"""
    return any(HAND_NUM_RE.match(l.strip()[3:].strip())
               for l in lines if l.strip().startswith("## "))


def render_heading(level, text, theme, index=None):
    accent = theme["accent"]
    if level == 1:
        # 正文大标题不用 <h1>:微信对 h1 有「标题」语义映射,粘贴后字号/样式易被
        # 后台覆盖。改用 <p> + 内联样式,等价且稳(20px/700/居中)。
        return ('<p style="font-size:20px;font-weight:700;color:%s;'
                'text-align:center;margin:0 0 18px;line-height:1.5;'
                'letter-spacing:0.5px;">%s</p>'
                % (theme["text_strong"], render_inline(text.strip() if keep_hand_num(theme)
                                                       else (HAND_NUM_RE.sub("", text).strip() or text))))

    if level == 2:
        style = theme.get("h2_style", "number")
        if keep_hand_num(theme):
            # 保留手写序号:标题原样输出,不再补排版层编号
            plain = text.strip()
            index = None
        else:
            # 先剥离手写序号,再按主题样式决定是否由排版层补编号
            plain = HAND_NUM_RE.sub("", text).strip() or text.strip()
        t = render_inline(plain)
        num = ""
        if "number" in style and index:
            # index 既可以是序号(int,渲染成 01/02),也可以是 ∞ 这类标记(str)
            label = ("%02d" % index) if isinstance(index, int) else str(index)
            num = ('<span style="color:%s;font-weight:700;margin-right:8px;'
                   'font-family:%s;">%s</span>'
                   % (accent, theme["mono_stack"], label))

        if style == "center":
            return ('<h2 style="font-size:18px;font-weight:700;color:%s;'
                    'text-align:center;margin:36px 0 18px;padding:12px 0;'
                    'line-height:1.5;border-top:1px solid %s;'
                    'border-bottom:1px solid %s;letter-spacing:1px;">%s%s</h2>'
                    % (theme["text_strong"], theme["border"], theme["border"],
                       num, t))
        if style == "underline":
            return ('<h2 style="font-size:18px;font-weight:700;color:%s;'
                    'margin:34px 0 16px;line-height:1.5;display:inline-block;'
                    'border-bottom:2px solid %s;padding-bottom:4px;">%s%s</h2>'
                    % (theme["text_strong"], accent, num, t))
        if style == "plain":
            return ('<h2 style="font-size:18px;font-weight:700;color:%s;'
                    'margin:34px 0 16px;line-height:1.5;'
                    'letter-spacing:0.5px;">%s%s</h2>'
                    % (theme["text_strong"], num, t))
        # number / bar:都走左竖条;number 额外带 01/02 编号
        return ('<h2 style="font-size:18px;font-weight:700;color:%s;'
                'margin:34px 0 16px;padding-left:11px;line-height:1.5;'
                'border-bottom:2px solid %s;padding-bottom:8px;">%s%s</h2>'
                % (theme["text_strong"], accent, num, t))

    if level == 3:
        t = render_inline(text.strip() if keep_hand_num(theme)
                          else (HAND_NUM_RE.sub("", text).strip() or text))
        return ('<h3 style="font-size:16px;font-weight:600;color:%s;'
                'margin:26px 0 12px;line-height:1.5;">%s</h3>'
                % (theme["text_strong"], t))
    t = render_inline(text)
    return ('<h4 style="font-size:15px;font-weight:600;color:%s;'
            'margin:22px 0 10px;line-height:1.5;">%s</h4>' % (theme["text"], t))


def render_code(code, lang, theme):
    body = highlight(code.rstrip("\n"), (lang or "").lower())
    # 语言标签用 <section> 不用 <div>:公众号新版编辑器底层是 ProseMirror,
    # 白名单里没有 div,div 包裹的块连同背景/内边距会被整段吞掉。
    label = ('<section style="font-size:11px;color:%s;padding:0 0 8px;'
             'letter-spacing:1px;font-weight:600;font-family:%s;">%s</section>'
             % (theme["accent"], theme["mono_stack"], esc(lang.upper()))
             if lang else "")
    # 不用 <pre>:公众号端 pre 不自动换行,窄屏会横向溢出。
    # 改用 section + pre-wrap + break-all,长行自动折行;缩进与换行由代码自身
    # 提供,HTML 源码里不在该 section 内插入任何格式化换行。
    return ('<section style="margin:0 0 %s;background:%s;border-radius:%s;'
            'padding:16px;">%s<section style="margin:0;'
            'white-space:pre-wrap;word-break:break-all;color:%s;font-size:13.5px;'
            'line-height:1.65;font-family:%s;">%s</section></section>'
            % (theme["para_gap"], theme["code_bg"], theme["radius"], label,
               theme["code_text"], theme["mono_stack"], body))


def render_quote(lines, theme):
    texts = []
    buf = []
    for line in lines:
        if not line.strip():
            if buf:
                texts.append(render_inline(" ".join(buf)))
                buf = []
            continue
        buf.append(line.strip())
    if buf:
        texts.append(render_inline(" ".join(buf)))
    parts = []
    for k, x in enumerate(texts):
        gap = "0" if k == len(texts) - 1 else "10px"
        parts.append('<p style="margin:0 0 %s;line-height:1.75;text-align:%s;'
                     'word-break:break-word;">%s</p>'
                     % (gap, theme["align"] or "left", x))
    # 用 <section> 而非 <blockquote>:公众号对 blockquote 有原生「引用」样式,
    # 可能覆盖我们设置的颜色与边框。section 样式完全自控。
    # MD3:无衬条(无 border-left/border-top),纯背景色调 + 大圆角区分层级。
    return ('<section style="margin:0 0 %s;padding:14px 16px;'
            'background:%s;border-radius:%s;'
            'color:%s;font-size:15px;">%s</section>'
            % (theme["para_gap"], theme["surface"],
               theme["radius"], theme["text"], "".join(parts)))


def render_paragraph(text, theme, tight=False, align=None):
    style = para_style(theme)
    if tight:
        style = style.replace("margin:0 0 %s;" % theme["para_gap"], "margin:0 0 10px;")
    if align:
        style += "text-align:%s;" % align
    return '<p style="%s">%s</p>' % (style, render_inline(text))


def render_list(items, theme, ordered, depth=0):
    tag = "ol" if ordered else "ul"
    style = ("margin:0 0 20px;padding-left:%dpx;line-height:%s;"
             % (26 if depth == 0 else 22, theme["line_height"]))
    if ordered:
        style += "list-style-type:decimal;"
    else:
        style += "list-style-type:disc;color:%s;" % theme["accent"]
    out = ["<%s style=\"%s\">" % (tag, style)]
    for item in items:
        line = '<li style="margin-bottom:9px;color:%s;">' % theme["text"]
        line += '<span style="color:%s;">%s</span>' % (theme["text"], item["text"])
        if item["children"]:
            line += render_list(item["children"], theme,
                                bool(item["children_ordered"]), depth + 1)
        line += "</li>"
        out.append(line)
    out.append("</%s>" % tag)
    return "".join(out)


def build_list(lines, theme, start=0):
    items = []
    root = {"indent": -1, "children": items, "ordered": False, "children_ordered": None}
    stack = [root]
    i = start
    while i < len(lines):
        line = lines[i]
        if not line.strip():
            if i + 1 < len(lines) and is_list_item(lines[i + 1]):
                i += 1
                continue
            break
        if not is_list_item(line):
            if line.startswith("    ") or line.startswith("\t"):
                if items:
                    items[-1]["text"] += " " + line.strip()
                i += 1
                continue
            break
        indent, marker, content = list_meta(line)
        node = {
            "text": render_inline(content),
            "children": [],
            "children_ordered": None,
            "indent": indent,
            "ordered": not marker.startswith(("-", "*", "+")),
        }
        while stack and stack[-1]["indent"] >= indent:
            stack.pop()
        if not stack:
            stack = [root]
        parent = stack[-1]
        if parent["children_ordered"] is None:
            parent["children_ordered"] = node["ordered"]
        parent["children"].append(node)
        stack.append(node)
        i += 1

    ordered = bool(re.match(r"^\s*(\d+[.)])\s+", lines[start]))
    return render_list(items, theme, ordered), i


def render_table(rows, theme):
    """表格分流渲染。

    列数 <= table_max_cols:保留 <table>,但不加 table-layout:fixed,
    让列宽按内容自适应(fixed 会把各列均分,5 列在 677px 正文宽里每列仅 135px,
    中文被压成竖条)。
    列数更多:转卡片化,每行一张卡(首列作标题,其余「列名 + 值」成对),
    彻底摆脱横向溢出。公众号端列数 > 4 必然溢出,这是唯一稳的解法。

    另外:<thead>/<tbody>/<colgroup> 在公众号里不被支持,一律不输出。
    """
    cols = max(len(r) for r in rows)
    if cols > int(theme.get("table_max_cols", 3)):
        return render_table_cards(rows[0], rows[1:], theme)

    head = rows[0]
    # MD3 浅色表:表头浅蓝底 + 蓝色文字,无网格线;
    # 表头用一条蓝色底部分隔线强调,行与行之间用浅色底部分隔线。
    hcells = "".join(
        '<th style="background:%s;border-bottom:2px solid %s;padding:10px 12px;'
        'text-align:left;font-weight:600;color:%s;font-size:14px;'
        'line-height:1.55;word-break:break-word;">%s</th>'
        % (theme["accent_soft"], theme["accent"], theme["accent"],
           render_inline(c))
        for c in head
    )
    body_rows = "".join(
        "<tr>%s</tr>" % "".join(
            '<td style="border-bottom:1px solid %s;padding:10px 12px;color:%s;'
            'font-size:14px;line-height:1.6;word-break:break-word;">%s</td>'
            % (theme["border"], theme["text"], render_inline(c))
            for c in row
        )
        for row in rows[1:]
    )
    return ('<section style="margin:0 0 %s;">'
            '<table style="border-collapse:collapse;width:100%%;font-size:14px;">'
            '<tr>%s</tr>%s</table></section>'
            % (theme["para_gap"], hcells, body_rows))


def render_table_cards(head, body, theme):
    cards = []
    for row in body:
        if not row:
            continue
        title = render_inline(row[0]) if row else ""
        metas = []
        for k in range(1, len(row)):
            name = head[k] if k < len(head) else ""
            metas.append(
                '<p style="margin:0 0 6px;line-height:1.6;">'
                '<span style="font-size:12.5px;color:%s;">%s</span>'
                '<span style="font-size:14px;font-weight:600;color:%s;'
                'margin-left:8px;">%s</span></p>'
                % (theme["text_light"], render_inline(name),
                   theme["text_strong"], render_inline(row[k])))
        cards.append(
            '<section style="margin:0 0 12px;padding:13px 15px;background:%s;'
            'border-radius:%s;">'
            '<p style="margin:0 0 9px;font-size:15px;font-weight:600;color:%s;'
            'line-height:1.5;word-break:break-word;">%s</p>%s</section>'
            % (theme["surface"], theme["radius"],
               theme["accent"], title, "".join(metas)))
    return ('<section style="margin:0 0 %s;">%s</section>'
            % (theme["para_gap"], "".join(cards)))


def render_hr(theme):
    # 宽度用百分比:公众号端 px 固定值在不同屏宽下表现不一致。
    # 不用 display:inline-block:audit_inline 会把它判为 WARN,而这是生成器
    # 自己的输出、用户无从修正——自检永远带一条洗不掉的 WARN 等于没有自检。
    # 块级 section + margin:0 auto 居中,视觉与原来完全一致。
    return ('<section style="margin:32px 0;">'
            '<section style="width:12%%;height:2px;background:%s;'
            'margin:0 auto;"></section></section>' % theme["accent"])


def render_figure(src, caption, theme, alt="", source=None):
    cap = ""
    if caption:
        cap = ('<p style="font-size:13px;color:%s;text-align:center;'
               'margin:9px 0 %s;line-height:1.6;">%s</p>'
               % (theme["text_light"], "4px" if source else theme["para_gap"], render_inline(caption)))
    if source:
        cap += ('<p style="font-size:12px;color:%s;text-align:center;'
                'margin:%s 0 %s;line-height:1.6;">%s</p>'
                % (theme["text_light"], "0" if caption else "9px", theme["para_gap"],
                   render_inline(source)))
        caption = caption or source
    border = ""  # MD3 优雅:图片无边框,只保留圆角
    altattr = ' alt="%s"' % esc(alt) if alt else ""
    # 图片一律 max-width:100%,绝不用 width:100%:正文容器约 677px,
    # width:100% 会把 400px 的小截图强行拉满变糊,竖图更糟。
    # max-width 让大图缩到容器宽、小图保持原尺寸并居中。
    # 不用 <figure>:微信粘贴时可能剥离包裹导致图注错位,改 section + p。
    return ('<section style="margin:0 0 %s;">'
            '<p style="margin:0;text-align:center;">'
            '<img src="%s"%s style="max-width:100%%;height:auto;display:block;'
            '%sborder-radius:%s;margin:0 auto;"></p>%s</section>'
            % ("9px" if caption else theme["para_gap"], src, altattr, border,
               theme["radius"], cap))


# ---------------------------------------------------------------- containers

CONTAINER_KINDS = {
    "note": "note", "info": "note", "memo": "note",
    "tip": "tip", "success": "tip", "ok": "tip",
    "warn": "warn", "warning": "warn",
    "danger": "danger", "error": "danger",
    "pull": "pull", "quote": "pull", "golden": "pull",
    "dialogue": "dialogue", "chat": "dialogue", "talk": "dialogue",
    "stat": "stat", "data": "stat", "metric": "stat",
}

DEFAULT_LABELS = {
    "note": "说明", "tip": "提示", "warn": "注意", "danger": "警告",
}


def render_container(kind, label, inner_lines, theme):
    kind = CONTAINER_KINDS.get(kind, "note")
    text = "\n".join(inner_lines)

    if kind == "pull":
        # 金句块用 <section> 不用 <div>(div 会被公众号整段吞掉)。
        # MD3:无上下衬线,tonal 卡片(surface_container 比正文卡片深一阶)承载。
        return ('<section style="margin:28px 0;padding:20px 18px;'
                'background:%s;border-radius:%s;">'
                '<p style="margin:0;font-size:17px;line-height:1.85;color:%s;'
                'text-align:center;font-weight:600;letter-spacing:0.5px;'
                'word-break:break-word;">%s</p></section>'
                % (theme.get("surface_container", theme["surface"]),
                   theme["radius"],
                   theme["text_strong"], render_inline(text.strip())))

    if kind == "dialogue":
        rows = []
        for line in inner_lines:
            if not line.strip():
                continue
            m = re.match(r"^\s*(.{1,12}?)\s*[::]\s*(.+)$", line)
            if m:
                name, say = m.group(1), m.group(2)
                rows.append(
                    '<p style="margin:0 0 6px;font-size:13px;color:%s;">%s</p>'
                    '<p style="margin:0 0 14px;padding:11px 14px;background:%s;'
                    'border-radius:%s;font-size:15px;line-height:1.72;'
                    'color:%s;">%s</p>'
                    % (theme["text_light"], render_inline(name),
                       theme["surface"], theme["radius"], theme["text"],
                       render_inline(say)))
            else:
                rows.append('<p style="margin:0 0 14px;padding:11px 14px;'
                            'background:%s;border-radius:%s;font-size:15px;'
                            'line-height:1.72;color:%s;">%s</p>'
                            % (theme["surface"], theme["radius"], theme["text"],
                               render_inline(line.strip())))
        return '<section style="margin:0 0 %s;">%s</section>' % (
            theme["para_gap"], "".join(rows))

    if kind == "stat":
        rows = []
        for line in inner_lines:
            if not line.strip() or "|" not in line:
                continue
            value, desc = line.split("|", 1)
            rows.append(
                '<p style="margin:0 0 14px;line-height:1.3;">'
                '<span style="font-size:26px;font-weight:700;color:%s;'
                'margin-right:10px;">%s</span>'
                '<span style="font-size:13px;color:%s;">%s</span></p>'
                % (theme["accent"], esc(value.strip()),
                   theme["text_light"], esc(desc.strip())))
        return '<section style="margin:0 0 %s;padding:16px 18px;' \
               'background:%s;border-radius:%s;">%s</section>' % (
                   theme["para_gap"], theme["surface"], theme["radius"],
                   "".join(rows))

    color = {"note": theme["c_note"], "tip": theme["c_tip"],
             "warn": theme["c_warn"], "danger": theme["c_danger"]}[kind]
    label_html = ""
    if label:
        # 标签用 <section> 不用 <div>
        label_html = ('<section style="font-size:12px;font-weight:600;color:%s;'
                      'letter-spacing:1px;margin-bottom:6px;">%s</section>'
                      % (color, esc(label)))
    body = []
    buf = []
    for line in inner_lines:
        if not line.strip():
            if buf:
                body.append(render_paragraph(" ".join(buf), theme, tight=True))
                buf = []
            continue
        buf.append(line.strip())
    if buf:
        body.append(render_paragraph(" ".join(buf), theme, tight=True))
    # MD3  tonal 卡片:无衬条,靠背景色调 + 大圆角区分层级;
    # 种类用标签文字颜色区分(note 蓝 / tip 绿 / warn 橙 / danger 红)。
    return ('<section style="margin:0 0 %s;padding:14px 16px;background:%s;'
            'border-radius:%s;">%s%s</section>'
            % (theme["para_gap"], theme["surface"], theme["radius"],
               label_html, "".join(body)))


# ---------------------------------------------------------------- images

def resolve_image(src, md_path, out_dir, assets, asset_root):
    if re.match(r"^https?://", src):
        assets.append({"src": src, "local": None, "remote": True})
        return src
    abs_path = os.path.normpath(os.path.join(os.path.dirname(md_path), src))
    if not os.path.exists(abs_path) and asset_root:
        rel = re.sub(r"^(\.\./)+", "", src)
        candidate = os.path.normpath(os.path.join(asset_root, rel))
        if os.path.exists(candidate):
            abs_path = candidate
    if not os.path.exists(abs_path):
        # 本地文件缺失:登记缺失记录再返回原 src(HTML 保留占位 <img>,
        # embed 会跳过并提示"未内嵌",上传清单与计数也不会漏掉这一项)
        assets.append({"src": src, "local": None, "remote": False,
                       "missing": True})
        return src
    img_dir = os.path.join(out_dir, "images")
    try:
        os.makedirs(img_dir, exist_ok=True)
    except OSError as e:
        sys.exit("错误:无法创建图片目录 %s(%s)" % (img_dir, e))
    base = os.path.basename(abs_path)
    target = os.path.join(img_dir, base)
    n = 1
    while os.path.exists(target) and not os.path.samefile(abs_path, target):
        stem, ext = os.path.splitext(base)
        target = os.path.join(img_dir, "%s-%d%s" % (stem, n, ext))
        n += 1
    if not os.path.exists(target):
        try:
            shutil.copy2(abs_path, target)
        except OSError as e:
            sys.exit("错误:复制图片失败 %s → %s(%s)" % (abs_path, target, e))
    rel = os.path.relpath(target, out_dir)
    assets.append({"src": src, "local": rel, "remote": False,
                   "basename": os.path.basename(target),
                   "size": os.path.getsize(abs_path)})
    return rel


def handle_mermaid(code, out_dir, diagrams, theme, render):
    os.makedirs(os.path.join(out_dir, "diagrams"), exist_ok=True)
    idx = len(diagrams) + 1
    mmd = os.path.join(out_dir, "diagrams", "diagram-%02d.mmd" % idx)
    with open(mmd, "w", encoding="utf-8") as fh:
        fh.write(code)
    png = os.path.join(out_dir, "diagrams", "diagram-%02d.png" % idx)
    rel_png = os.path.relpath(png, out_dir)
    ok = False
    if render and shutil.which("mmdc"):
        try:
            subprocess.run(
                ["mmdc", "-i", mmd, "-o", png, "-b", "white", "-w", "1080"],
                check=True, capture_output=True, timeout=180,
            )
            ok = os.path.exists(png)
        except Exception:
            ok = False
    diagrams.append({"index": idx, "mmd": os.path.relpath(mmd, out_dir),
                     "png": rel_png if ok else None})
    if ok:
        return render_figure(rel_png, None, theme)
    note = ("[此处为流程图 %02d,公众号不支持 mermaid。请渲染 diagrams/%s 为图片后手动插入]"
            % (idx, os.path.basename(mmd)))
    return ('<section style="margin:0 0 %s;padding:14px 16px;'
            'background:%s;color:%s;'
            'font-size:14px;line-height:1.7;border-radius:%s;">%s</section>'
            % (theme["para_gap"], theme["surface"],
               theme["text_muted"], theme["radius"], esc(note)))


# ---------------------------------------------------------------- parser

_FENCE_OPEN_RE = re.compile(r"^\s{0,3}(`{3,}|~{3,})")


def strip_html_comments(text):
    """去掉正文里的 HTML 注释(<!-- … -->,可跨行):写作提示、骨架备注不进渲染产物。
    围栏代码块和行内代码里的 <!-- 原样保留;整行只有注释的行直接删掉。"""
    out, fence, in_c = [], None, False
    for line in text.split("\n"):
        if not in_c:
            m = _FENCE_OPEN_RE.match(line)
            if fence is None and m:
                fence = m.group(1)
                out.append(line)
                continue
            if fence is not None:
                if m and m.group(1)[0] == fence[0] and len(m.group(1)) >= len(fence) \
                        and not line.strip()[len(m.group(1)):].strip():
                    fence = None
                out.append(line)
                continue
        res, rest = "", line
        while rest:
            if in_c:
                j = rest.find("-->")
                if j < 0:
                    rest = ""
                    break
                rest, in_c = rest[j + 3:], False
                if res.endswith(" ") and rest.startswith(" "):
                    rest = rest.lstrip(" ")
            else:
                j = rest.find("<!--")
                if j < 0:
                    res += rest
                    break
                if (res + rest[:j]).count("`") % 2 == 1:  # 行内代码里的 <!-- 不算注释
                    res, rest = res + rest[:j + 4], rest[j + 4:]
                    continue
                res, rest, in_c = res + rest[:j], rest[j + 4:], True
        if res == line:
            out.append(line)
        elif res.strip():
            out.append(res.rstrip())
    return "\n".join(out)


def strip_frontmatter(lines):
    if lines and lines[0].strip() == "---":
        for idx in range(1, len(lines)):
            if lines[idx].strip() == "---":
                return lines[idx + 1:]
    return lines


def convert_blocks(lines, md_path, out_dir, theme, ctx):
    out = []
    i = 0
    n = len(lines)
    h2_index = 0
    h2_titles = []
    toc_at = None  # 导读落点:首个正文段落之后

    # 预扫描:末章是否为收束类,决定它的编号用数字还是 ∞
    keep = keep_hand_num(theme)
    h2_texts = [(l.strip()[3:].strip() if keep else
                 (HAND_NUM_RE.sub("", l.strip()[3:]).strip() or l.strip()[3:].strip()))
                for l in lines if l.strip().startswith("## ")]
    h2_total = len(h2_texts)
    last_is_summary = bool(h2_total) and bool(SUMMARY_H2_RE.match(h2_texts[-1]))

    while i < n:
        line = lines[i]
        stripped = line.strip()

        if not stripped:
            i += 1
            continue

        m = FENCE_RE.match(stripped)
        if m:
            open_len = len(m.group(1))
            lang = m.group(2)
            i += 1
            buf = []
            while i < n:
                s2 = lines[i].strip()
                k = 0
                while k < len(s2) and s2[k] == "`":
                    k += 1
                # 闭合栏:反引号数 >= 开栏数且后面无其它字符(闭合栏可比开栏长)。
                # 带信息串的 ```python 不是闭合栏,是栏内代码——旧写法按
                # startswith("```") 判闭合,会把栏提前关掉。
                if k >= open_len and not s2[k:].strip():
                    break
                buf.append(lines[i])
                i += 1
            i += 1
            code = "\n".join(buf)
            if lang.lower() == "mermaid":
                out.append(handle_mermaid(code, out_dir, ctx["diagrams"], theme,
                                          ctx["render_mermaid"]))
            else:
                out.append(render_code(code, lang, theme))
            continue

        if HR_RE.match(stripped) and not is_list_item(line):
            out.append(render_hr(theme))
            i += 1
            continue

        m = HEADING_RE.match(stripped)
        if m:
            level = len(m.group(1))
            marker = h2_index
            if level == 2:
                h2_index += 1
                h2_titles.append(m.group(2).strip() if keep else
                                 (HAND_NUM_RE.sub("", m.group(2)).strip() or m.group(2).strip()))
                marker = ("∞" if (last_is_summary and h2_index == h2_total)
                          else h2_index)
            out.append(render_heading(level, m.group(2).strip(), theme, marker))
            i += 1
            continue

        m = CONTAINER_RE.match(stripped)
        if m:
            kind = (m.group(1) or "note").lower()
            label = m.group(2).strip()
            i += 1
            buf = []
            while i < n and not lines[i].strip().startswith(":::"):
                buf.append(lines[i])
                i += 1
            if kind in ("toc", "目录", "导读"):
                out.append(TOC_TOKEN)
                i += 1
                continue
            if kind in ("sign", "signature", "签名"):
                out.append(SIGN_TOKEN)
                i += 1
                continue
            i += 1
            out.append(render_container(kind, label or DEFAULT_LABELS.get(
                CONTAINER_KINDS.get(kind, "note"), ""), buf, theme))
            continue

        if stripped.startswith("|") and i + 1 < n and TABLE_SEP_RE.match(lines[i + 1].strip()):
            rows = [split_row(stripped)]
            i += 2
            while i < n and lines[i].strip().startswith("|"):
                rows.append(split_row(lines[i].strip()))
                i += 1
            out.append(render_table(rows, theme))
            continue

        if stripped.startswith(">"):
            buf = []
            while i < n and lines[i].strip().startswith(">"):
                buf.append(lines[i].strip().lstrip(">").strip())
                i += 1
            out.append(render_quote(buf, theme))
            continue

        if is_list_item(line):
            block_html, i = build_list(lines, theme, i)
            out.append(block_html)
            continue

        m = match_img_only(stripped)
        if m:
            caption = None
            source = None
            if i + 1 < n:
                cm = CAPTION_RE.match(lines[i + 1].strip())
                if cm:
                    caption = cm.group(1)
                    i += 1
            # 「来源:」行(紧跟或隔一个空行)→ 图注样式
            j = i + 1
            if j < n and not lines[j].strip() and j + 1 < n:
                j += 1
            if j < n:
                sm = SOURCE_RE.match(lines[j].strip())
                if sm:
                    source = sm.group(1)
                    i = j
            src = resolve_image(m[1], md_path, out_dir,
                                ctx["assets"], ctx["asset_root"])
            out.append(render_figure(src, caption, theme, alt=m[0], source=source))
            i += 1
            continue

        buf = [stripped]
        i += 1
        dot_item = stripped.startswith("·")
        while i < n:
            cur = lines[i].strip()
            # 「·」开头的行是纯文本列表项:每行单独成段,不和上下行并成一段
            if dot_item or cur.startswith("·"):
                break
            if (not cur or HEADING_RE.match(cur) or HR_RE.match(cur)
                    or CONTAINER_RE.match(cur) or cur.startswith(">")
                    or cur.startswith("|") or is_list_item(lines[i])
                    or match_img_only(cur) or FENCE_RE.match(cur)):
                break
            buf.append(cur)
            i += 1
        nxt_dot = i < n and lines[i].strip().startswith("·")
        out.append(render_paragraph(" ".join(buf), theme, tight=dot_item and nxt_dot))
        if toc_at is None:
            toc_at = len(out)

    # 自动导读:显式 ::: toc 优先。触发条件是「章节够多」或「正文够长」任一成立——
    # 只按字数会漏掉「1152 字 / 6 节」这类章节密集的短稿,只按章节数会漏掉
    # 「3 节 / 3000 字」这类长段落稿。
    if not any(x == TOC_TOKEN for x in out) and ctx.get("toc"):
        n_h2 = len(h2_titles)
        n_han = ctx.get("han_chars", 0)
        by_h2 = n_h2 >= int(theme.get("toc_min_h2", 4))
        by_len = n_h2 >= 3 and n_han >= int(theme.get("toc_min_chars", 2000))
        if by_h2 or by_len:
            out.insert(toc_at if toc_at is not None else 0, TOC_TOKEN)

    html = "".join(out)
    html = html.replace(TOC_TOKEN, render_toc(h2_titles, theme))
    return html


def convert(md_text, md_path, out_dir, theme, link_mode="footnote",
            render_mermaid=False, asset_root=None, use_pangu=True,
            toc=True, sign_mode="auto", author="", author_bio="", auto_number=False):
    lines = strip_frontmatter(strip_html_comments(md_text).split("\n"))
    theme = dict(theme)
    theme["_keep_hand_num"] = (not auto_number) and detect_hand_numbers(lines)
    han_chars = sum(len(HAN_RE.findall(l)) for l in lines)
    ctx = {"assets": [], "diagrams": [], "footnotes": [],
           "render_mermaid": render_mermaid, "asset_root": asset_root,
           "toc": bool(toc), "han_chars": han_chars,
           "sign_mode": sign_mode, "author": author, "author_bio": author_bio}
    CTX["theme"] = theme
    CTX["link_mode"] = link_mode
    CTX["footnotes"] = ctx["footnotes"]
    CTX["footnote_idx"] = {}
    CTX["use_pangu"] = use_pangu
    CTX["hl_scheme"] = build_code_scheme(theme)
    # 行内图片解析器:render_inline 里的 ![alt](src) 通过它走 resolve_image,
    # 与独立成行的图片共享「复制到 images/ + 登记清单」管线。
    abs_md = os.path.abspath(md_path)
    CTX["img_resolve"] = lambda s: resolve_image(
        s, abs_md, out_dir, ctx["assets"], ctx.get("asset_root"))

    body = convert_blocks(lines, md_path, out_dir, theme, ctx)

    # 尾部签名区。auto:稿件末尾已自带签名/CTA 就不重复生成(避免出现两处签名)。
    sign_html = render_signature(theme, author, author_bio)
    if SIGN_TOKEN in body:
        body = body.replace(SIGN_TOKEN, sign_html)
    elif sign_mode == "on":
        body += sign_html
    elif sign_mode == "auto" and not md_tail_has_signature(lines):
        body += sign_html

    if link_mode == "footnote" and ctx["footnotes"]:
        body += render_footnotes(ctx["footnotes"], theme)
    return body, ctx["assets"], ctx["diagrams"], ctx["footnotes"]


def render_footnotes(footnotes, theme):
    items = "".join(
        '<p style="margin:0 0 8px;font-size:13px;line-height:1.7;color:%s;'
        'word-break:break-all;">[%d] %s — %s</p>'
        % (theme["text_muted"], idx, esc(f["label"]), esc(f["url"]))
        for idx, f in enumerate(footnotes, 1)
    )
    # 标题用 <section> 不用 <div>
    return ('<section style="margin:34px 0 %s;padding:16px 18px;'
            'background:%s;border-radius:%s;">'
            '<section style="font-size:13px;font-weight:600;color:%s;'
            'letter-spacing:1px;margin-bottom:10px;">参考链接</section>%s</section>'
            % (theme["para_gap"], theme["surface"], theme["radius"],
               theme["text_strong"], items))


# ---------------------------------------------------------------- toc / signature

SIGN_RE = re.compile(
    r"点赞|在看|三连|点个关注|欢迎关注|关注「|扫码|分享给|我是[^。,,]{0,20}[,,]")

# 流式解析时还不知道全文有哪些 H2,先用占位符标记落点,收尾时统一替换
TOC_TOKEN = "\x01TOC\x01"
SIGN_TOKEN = "\x01SIGN\x01"


def md_tail_has_signature(lines, window=8):
    """稿件末尾是否已自带签名/CTA。自带则不再追加,避免出现两处签名区。"""
    tail = [l.strip() for l in lines if l.strip()][-window:]
    return any(SIGN_RE.search(l) for l in tail)


def render_toc(titles, theme):
    """前言导读。展示精选看点而非全量目录:超出 toc_max 时截断并注明总节数,
    不假装全文只有这几节。"""
    if not titles:
        return ""
    cap = int(theme.get("toc_max", 5))
    shown = titles[:cap]
    # 导读的标记必须跟正文标题一致:
    #  - 标题带编号(h2_style 含 number)→ 导读也用编号;末章收束类用 ∞,避免「导读 04 / 正文 ∞」
    #  - 标题不带编号(center/underline/plain)→ 导读只用中性圆点,不要凭空造出 01/02
    numbered = "number" in theme.get("h2_style", "number") and not keep_hand_num(theme)
    last_summary = bool(titles) and bool(SUMMARY_H2_RE.match(titles[-1]))

    def label(k):
        if not numbered:
            return "·"
        return "∞" if (last_summary and k == len(titles)) else "%02d" % k

    rows = "".join(
        '<p style="margin:0 0 7px;font-size:14px;line-height:1.6;color:%s;'
        'word-break:break-word;">'
        '<span style="color:%s;font-weight:700;margin-right:8px;'
        'font-family:%s;">%s</span>%s</p>'
        % (theme["text"], theme["accent"], theme["mono_stack"], label(k),
           render_inline(t))
        for k, t in enumerate(shown, 1))
    more = ""
    if len(titles) > len(shown):
        more = ('<p style="margin:9px 0 0;font-size:12.5px;color:%s;">'
                '……共 %d 节</p>' % (theme["text_light"], len(titles)))
    return ('<section style="margin:0 0 26px;padding:15px 17px;background:%s;'
            'border-radius:%s;">'
            '<p style="margin:0 0 10px;font-size:12.5px;font-weight:600;'
            'color:%s;letter-spacing:1px;">本文看点</p>%s%s</section>'
            % (theme["surface"], theme["radius"],
               theme["accent"], rows, more))


def render_signature(theme, author="", bio=""):
    """尾部签名区。2026-10-01 起默认不再渲染"自我介绍"行(我是{{作者名}},{{一句话简介}});
    只保留三连 CTA。author/bio 参数保留仅为兼容旧调用,不再使用。"""
    return ('<section style="margin:34px 0 0;padding:16px 18px;background:%s;'
            'border-radius:%s;">'
            '<p style="margin:0;font-size:14px;line-height:1.75;color:%s;'
            'word-break:break-word;">如果你觉得今天这篇有收获,欢迎'
            '<span style="font-weight:600;color:%s;">点赞、在看、转发</span>'
            '三连,我们下篇见。</p></section>'
            % (theme["surface"], theme["radius"],
               theme["text"], theme["accent"]))


# ---------------------------------------------------------------- embed

MIME_BY_EXT = {
    ".png": "image/png",
    ".jpg": "image/jpeg",
    ".jpeg": "image/jpeg",
    ".gif": "image/gif",
    ".webp": "image/webp",
    ".svg": "image/svg+xml",
}


def embed_images_inline(body, out_dir):
    """把正文里指向本地文件的 <img src> 换成 base64 data URI。

    公众号后台会丢相对路径与本地地址:粘贴过去的 <img> 没有可抓取的 URL,
    整张图直接消失(连占位符都没有)。内嵌成 data URI 后,图片字节跟着
    剪贴板一起过去。远程 http(s) 图与已经是 data: 的图不动。
    返回 (新正文, 统计)。
    """
    stats = {"count": 0, "bytes": 0, "skipped": []}

    def repl(m):
        src = m.group(1)
        if re.match(r"^(https?:|data:|//)", src):
            return m.group(0)
        path = os.path.normpath(os.path.join(out_dir, src))
        mime = MIME_BY_EXT.get(os.path.splitext(path)[1].lower())
        if not mime or not os.path.exists(path):
            stats["skipped"].append(src)
            return m.group(0)
        with open(path, "rb") as fh:
            raw = fh.read()
        stats["count"] += 1
        stats["bytes"] += len(raw)
        return 'src="data:%s;base64,%s"' % (
            mime, base64.b64encode(raw).decode("ascii"))

    return re.sub(r'src="([^"]+)"', repl, body), stats


# ---------------------------------------------------------------- page

PAGE_TPL = """<!DOCTYPE html>
<html lang="zh-CN">
<head>
<meta charset="utf-8">
<meta name="viewport" content="width=device-width,initial-scale=1">
<title>{title}</title>
<style>
/* 仅本地预览用:公众号会剥离 style 标签,正文内联样式保持百分比宽度 */
body>div,body>article{{max-width:677px!important;margin-left:auto!important;
margin-right:auto!important;box-sizing:border-box;}}
</style>
</head>
<body style="margin:0;padding:24px 12px 64px;background:#EDEDED;font-family:{font_stack};">

<div style="max-width:100%;margin:0 auto 18px;padding:13px 18px;background:#FFF8E6;
border:1px solid #F0D9A8;border-radius:8px;font-size:13px;line-height:1.7;color:#7A5C1E;">
{notice}
</div>

<div style="max-width:100%;margin:0 auto 14px;display:flex;align-items:center;gap:10px;
flex-wrap:wrap;">
<button onclick="copyBody()" style="padding:9px 20px;font-size:14px;color:#fff;
background:{accent};border:none;border-radius:6px;cursor:pointer;">复制正文</button>
<span id="wx-tip" style="font-size:13px;color:#4A7A3A;"></span>
<span style="margin-left:auto;font-size:12px;color:#888;">{title}</span>
</div>

<div style="max-width:100%;margin:0 auto;padding:0 0 8px;font-size:12px;
color:#999;text-align:center;">↓ 正文开始 ↓</div>

<article id="wx-body" style="max-width:100%;margin:0 auto;padding:26px 20px 32px;
background:#FFFFFF;border:1px dashed #C9C9C9;border-radius:8px;
font-size:{font_size};color:{text};line-height:{line_height};
font-family:{font_stack};">
{body}
</article>

<script>
function copyBody() {{
  var node = document.getElementById('wx-body');
  var sel = window.getSelection();
  var range = document.createRange();
  range.selectNodeContents(node);
  sel.removeAllRanges();
  sel.addRange(range);
  try {{
    document.execCommand('copy');
    document.getElementById('wx-tip').textContent = '已复制,去公众号后台粘贴';
  }} catch (e) {{
    document.getElementById('wx-tip').textContent = '复制失败,请手动全选';
  }}
  sel.removeAllRanges();
}}
</script>
</body>
</html>
"""


def build_notice(embedded, n_images):
    """页顶「发布前须知」文案。内嵌模式与手动上传模式的说明不同。"""
    code = ('<code style="background:#F5F5F5;padding:1px 4px;border-radius:3px;">%s</code>')
    head = ("<strong>发布前须知</strong>:上方为操作提示,<strong>不要一起复制</strong>。"
            "请点「复制正文」或全选下方虚线框内容,粘贴到公众号后台编辑器。")
    if embedded:
        tail = ("<br>本页 %d 张图已 base64 内嵌,粘贴时会跟着一起过去,正常情况下"
                "无需再手动插图。若后台某张图显示为占位符,按 %s 的顺序,"
                "从 %s 手动补传这一张。"
                % (n_images, code % "图片上传清单.md", code % "images/"))
    else:
        tail = ("<br>图片需手动上传:本页图片仅供本地预览 —— 按 %s 的顺序"
                "逐张插入素材库。" % (code % "图片上传清单.md"))
    return head + tail


# audit_inline 的值级检查:原来是 8 次全正文 re.search(re.I 下每次都扫完整 MB 级
# body,大正文里 audit_inline 能占近一半耗时)。合并为一次单遍扫描:命中哪个分支
# 报哪条,收集命中的分支序号后按原列表顺序输出——与原来逐条 search 的结果完全一致。
_AUDIT_VALUE_PATTERNS = [
    ("linear-gradient", "ERROR", "linear-gradient(渐变被静默丢弃,退化成无背景。改纯色)"),
    ("box-shadow", "ERROR", "box-shadow(阴影被丢弃)"),
    ("rgba\\(|hsla\\(", "ERROR", "rgba()/hsla() 颜色(透明度不被支持,改纯色十六进制)"),
    ("var\\(--", "ERROR", "CSS 变量(不支持,值必须写死)"),
    ("@media|@keyframes", "ERROR", "@media/@keyframes(媒体查询与动画不被支持)"),
    ("\\sclass=", "ERROR", "class 属性(公众号会剥离,样式必须内联)"),
    ("\\sid=", "WARN", "id 属性(正文里无意义,可能被剥离)"),
    ("<img[^>]*width=\"", "WARN", "<img> 上的 width 属性(公众号不保证保留,宽度用内联 style)"),
]
_AUDIT_VALUE_RE = re.compile(
    "|".join("(?P<g%d>%s)" % (i, pat)
             for i, (pat, _lv, _msg) in enumerate(_AUDIT_VALUE_PATTERNS)),
    re.I,
)


def audit_inline(body):
    """正文的平台合规自检,返回 [(级别, 说明)],空列表即通过。

    级别含义:
      ERROR —— 公众号会静默丢弃该样式或整段吞掉该标签,产物必然与预览不一致
      WARN  —— 转换后仍可读,但存在降级风险或移动端体验问题

    硬约束依据见 references/wechat-constraints.md,本函数是该文档的可执行版本。
    """
    issues = []

    def add(level, msg):
        issues.append((level, msg))

    # ---- 标签级:会被剥离或不被支持
    TAGS = [
        ("<div", "ERROR", "<div> 标签(新版编辑器白名单无 div,包裹的块连同背景/内边距会被整段吞掉,是「粘贴后样式全丢」的头号元凶。改 <section>)"),
        ("<figure", "ERROR", "<figure> 标签(粘贴时可能剥离包裹导致图注错位。用 <section>+<p>)"),
        ("<figcaption", "ERROR", "<figcaption> 标签(同上,图注改用独立 <p>)"),
        ("<pre", "ERROR", "<pre> 标签(公众号端不自动换行,窄屏横向溢出。用 <section>+pre-wrap)"),
        ("<thead", "ERROR", "<thead> 不被支持(去掉分组标签,表头行直接作为首个 <tr>)"),
        ("<tbody", "ERROR", "<tbody> 不被支持(同上)"),
        ("<colgroup", "ERROR", "<colgroup> 不被支持"),
        ("<h1", "ERROR", "<h1> 标签(微信按标题语义覆盖字号,正文大标题用 <p> + 内联样式)"),
        ("<iframe", "ERROR", "<iframe> 会被剥离(视频只能用公众号自带组件)"),
        ("<video", "ERROR", "<video> 会被剥离"),
        ("<script", "ERROR", "<script> 会被剥离"),
        ("<style", "ERROR", "<style> 会被剥离,样式必须内联"),
    ]
    for tag, lv, msg in TAGS:
        if tag in body:
            add(lv, msg)

    # ---- 属性/值级
    for m in re.finditer(r'style="([^"]*)"', body):
        decls = [d.strip() for d in m.group(1).split(";") if d.strip()]
        for decl in decls:
            prop, _, val = decl.partition(":")
            prop, val = prop.strip().lower(), val.strip()
            low = val.lower()
            if prop == "text-align" and val not in ("left", "center", "right"):
                add("ERROR", "text-align:%s 非标准值(只允许 left/center/right)" % val)
            elif prop in ("width", "max-width", "min-width") and "px" in low:
                add("ERROR", "%s:%s 固定像素宽度(不同屏宽下表现不一致,改百分比)" % (prop, val))
            elif prop == "white-space" and low in ("pre", "nowrap"):
                add("ERROR", "white-space:%s 不换行(窄屏溢出;折行用 pre-wrap)" % val)
            elif prop in ("position", "float", "transform", "opacity"):
                add("ERROR", "%s:%s 定位/透明属性(公众号会吞掉,元素错位)" % (prop, val))
            elif prop == "display" and low in ("flex", "grid"):
                add("ERROR", "display:%s(布局属性被吞,内容堆叠。用 <section>+padding 模拟)" % val)
            elif prop.startswith("-"):
                add("ERROR", "%s 私有属性(公众号不支持)" % prop)
            elif prop == "table-layout" and low == "fixed":
                add("WARN", "table-layout:fixed(各列宽度均分,小屏下中文被压成竖条;除非逐列显式设宽,否则去掉)")
            elif prop == "display" and low == "inline-block":
                add("WARN", "display:inline-block(非常规 display 值,公众号支持不稳定)")
            elif prop == "border-radius":
                add("WARN", "border-radius(圆角可能被丢弃,降级为直角;属可接受的优雅降级,勿依赖圆角做视觉区分)")

    hit = set()
    for m in _AUDIT_VALUE_RE.finditer(body):
        for i in range(len(_AUDIT_VALUE_PATTERNS)):
            if m.group("g%d" % i) is not None:
                hit.add(i)
                break
    for i in sorted(hit):
        _pat, lv, msg = _AUDIT_VALUE_PATTERNS[i]
        add(lv, msg)

    # ---- 图片宽度:小图被拉伸是高频问题
    for m in re.finditer(r'<img[^>]*style="([^"]*)"', body):
        st = m.group(1)
        if re.search(r"(?<!max-)(?<!min-)\bwidth:\s*100%", st) and "max-width" not in st:
            add("WARN", "图片用 width:100%(小图会被强行拉满变糊,改 max-width:100%;height:auto)")
            break

    # 去重(保留首次出现的级别)
    seen, out = {}, []
    for lv, msg in issues:
        if msg not in seen:
            seen[msg] = lv
            out.append((lv, msg))
    # ERROR 在前
    out.sort(key=lambda x: 0 if x[0] == "ERROR" else 1)
    return out


def atomic_write(path, text):
    """原子写文件:先写临时文件再 rename,写一半失败(磁盘满/断电)时
    不会留下半截产物——要么是旧文件,要么是没有文件,绝不残缺。"""
    tmp = path + ".tmp"
    try:
        with open(tmp, "w", encoding="utf-8") as fh:
            fh.write(text)
        os.replace(tmp, path)
    except BaseException:
        try:
            os.unlink(tmp)
        except OSError:
            pass
        raise


def write_manifest(out_dir, slug, title, assets, diagrams, theme, footnotes,
                   embedded=False, subtitle=""):
    lines = ["# 图片上传清单 · %s" % title, ""]
    if subtitle:
        lines += ["## 摘要(frontmatter subtitle)", "", subtitle, "",
                  "> 公众号后台「摘要」栏可以直接用(120 字以内);正文里不重复。", ""]
    if embedded:
        lines.append("> 本页图片已 base64 内嵌,正常情况下粘贴到后台即带图。"
                     "若有图显示为占位符,再按此顺序逐张上传到素材库替换。")
    else:
        lines.append("> 公众号不会抓取本地图片,请在后台编辑器按此顺序逐张上传到素材库并插入正文。")
    lines.append("")
    if assets:
        lines.append("## 正文图片(按出现顺序)")
        lines.append("")
        lines.append("| 序号 | 文件名 | 体积 | 原 Markdown 引用 |")
        lines.append("|---|---|---|---|")
        for idx, a in enumerate(assets, 1):
            size = ""
            if a.get("size"):
                kb = a["size"] / 1024
                size = "%.0f KB" % kb if kb < 1024 else "%.1f MB" % (kb / 1024)
            if a.get("remote"):
                lines.append("| %d | %s(远程) | %s | `%s` |" % (idx, a["src"], size, a["src"]))
            elif a.get("missing"):
                lines.append("| %d | ⚠ 本地文件缺失:`%s` | — | `%s` |"
                             % (idx, a["src"], a["src"]))
            else:
                lines.append("| %d | `%s` | %s | `%s` |"
                             % (idx, a.get("basename") or "", size, a["src"]))
        lines.append("")
        lines.append("图片目录:`images/`(公众号单图建议 < 2 MB,宽度 1080 px 左右)")
        lines.append("")
    else:
        lines.append("## 正文图片")
        lines.append("")
        lines.append("_无_")
        lines.append("")
    lines.append("## 图表(mermaid)")
    lines.append("")
    if diagrams:
        lines.append("| 序号 | 源文件 | 已渲染 PNG |")
        lines.append("|---|---|---|")
        for d in diagrams:
            lines.append("| %d | `%s` | %s |" % (d["index"], d["mmd"],
                                                 ("`%s`" % d["png"]) if d["png"] else "未渲染"))
        lines.append("")
        lines.append("渲染:`mmdc -i diagrams/xx.mmd -o diagrams/xx.png -b white -w 1080`")
    else:
        lines.append("_无_")
    if footnotes:
        lines.append("")
        lines.append("## 参考链接(正文上标序号对应)")
        lines.append("")
        for idx, f in enumerate(footnotes, 1):
            lines.append("%d. %s — %s" % (idx, f["label"], f["url"]))
    lines.append("")
    lines.append("---")
    lines.append("")
    lines.append("主题:%s · 点缀色 `%s` · 标题样式 `%s` · 代码色板 `%s`"
                 % (theme["name"], theme["accent"],
                    theme.get("h2_style", "number"),
                    theme.get("code_scheme", "mono")))
    path = os.path.join(out_dir, "图片上传清单.md")
    atomic_write(path, "\n".join(lines))
    return path


# ---------------------------------------------------------------- main


def preview_png(html_path, png_path, width=430):
    """无头 Chrome 把页面截成长图(手机宽度),有 Pillow 时裁掉底部空白。成功返回路径,否则 None。"""
    chrome = os.environ.get("CHROME_PATH") if os.path.isfile(os.environ.get("CHROME_PATH", "")) else None
    for c in ("/Applications/Google Chrome.app/Contents/MacOS/Google Chrome",
              "/Applications/Chromium.app/Contents/MacOS/Chromium"):
        if not chrome and os.path.isfile(c):
            chrome = c
    for name in ("google-chrome", "chromium", "chromium-browser", "msedge"):
        if not chrome:
            chrome = shutil.which(name)
    if not chrome:
        return None
    cmd = [chrome, "--headless=new", "--no-sandbox", "--disable-gpu", "--hide-scrollbars",
           "--force-device-scale-factor=2", "--window-size=%d,16000" % width,
           "--screenshot=%s" % png_path, "file://" + os.path.abspath(html_path)]
    try:
        subprocess.run(cmd, capture_output=True, text=True, timeout=180)
    except (OSError, subprocess.TimeoutExpired):
        return None
    if not os.path.isfile(png_path):
        return None
    try:
        from PIL import Image, ImageChops
        im = Image.open(png_path).convert("RGB")
        bg = Image.new("RGB", im.size, im.getpixel((im.size[0] - 2, im.size[1] - 2)))
        box = ImageChops.difference(im, bg).getbbox()
        if box:
            im.crop((0, 0, im.size[0], min(im.size[1], box[3] + 40))).save(png_path)
    except Exception:
        pass
    return png_path

def main():
    ap = argparse.ArgumentParser()
    # 不设 required=True:--list-themes 需要能在不带输入文件时单独运行。
    # 必填校验放在下面手动做。
    ap.add_argument("--input", default="")
    ap.add_argument("--out-dir", default="")
    ap.add_argument("--slug", default="")
    ap.add_argument("--title", default="")
    ap.add_argument("--theme", default="",
                    help="主题:可传标识(tech-blue)、中文名(科技蓝)、JSON 路径,"
                         "或 genre:题材 按题材自动选(如 genre:评测)。留空用默认主题")
    ap.add_argument("--list-themes", action="store_true", help="列出所有可用主题后退出")
    ap.add_argument("--link-mode", default="footnote",
                    choices=["footnote", "note", "inline"])
    ap.add_argument("--asset-root", default="",
                    help="源仓库根目录,用于解析稿中 ../assets/ 形式的图片路径")
    ap.add_argument("--no-pangu", action="store_true", help="关闭中英文自动加空格")
    ap.add_argument("--render-mermaid", action="store_true")
    ap.add_argument("--embed-images", action="store_true",
                    help="把正文图片转成 base64 内嵌,粘贴到公众号时带图(推荐)")
    ap.add_argument("--no-toc", action="store_true",
                    help="不自动插入前言导读(默认 H2 >=4 个,或 H2 >=3 且正文 >=2000 中文字时插入)")
    ap.add_argument("--signature", default="auto", choices=["auto", "on", "off"],
                    help="尾部签名区:auto=稿件末尾已有签名则不重复生成(默认)")
    ap.add_argument("--author", default="",
                    help="签名区署名;留空则不输出署名行(不再写 {{作者名}} 占位)")
    ap.add_argument("--author-bio", default="", help="签名区一句话简介")
    ap.add_argument("--auto-number", action="store_true",
                    help="二级标题一律剥离手写序号、由排版层重新编号(旧行为);"
                         "默认:稿里写了「一、」这类序号就原样保留")
    ap.add_argument("--preview", action="store_true",
                    help="图文预览:用无头 Chrome 把生成的页面截成 <out-dir>/预览.png(手机宽度),交付前先看一遍")
    args = ap.parse_args()

    if args.list_themes:
        for t in list_themes():
            print("%-14s %-10s %-9s %s" % (t["id"], t["name"], t["accent"],
                                           "、".join(t["genre"]) or "(未声明题材)"))
        return

    if not args.input:
        sys.exit("缺少必填参数:--input")
    # 文章文件夹结构(<文章名>/<文章名>.md):--out-dir 缺省 <文章文件夹>/out,
    # --slug 缺省为文件名,--asset-root 缺省为文章文件夹
    in_dir = os.path.dirname(os.path.abspath(args.input))
    if not args.out_dir:
        args.out_dir = os.path.join(in_dir, "out")
    if not args.slug:
        args.slug = os.path.splitext(os.path.basename(args.input))[0]
    if not args.asset_root:
        args.asset_root = in_dir

    if os.path.isdir(args.input):
        sys.exit("错误:输入是目录不是文件 %s" % args.input)
    if not os.path.isfile(args.input):
        sys.exit("错误:找不到输入文件 %s" % args.input)

    theme = load_theme(args.theme)
    try:
        with open(args.input, encoding="utf-8") as fh:
            md_text = fh.read()
    except UnicodeDecodeError:
        sys.exit("错误:输入文件不是有效的 UTF-8 编码 %s" % args.input)
    except OSError as e:
        sys.exit("错误:无法读取输入文件 %s(%s)" % (args.input, e))

    try:
        os.makedirs(args.out_dir, exist_ok=True)
    except OSError as e:
        sys.exit("错误:无法创建输出目录 %s(%s)" % (args.out_dir, e))
    body, assets, diagrams, footnotes = convert(
        md_text, os.path.abspath(args.input), args.out_dir, theme,
        args.link_mode, args.render_mermaid, args.asset_root or None,
        not args.no_pangu,
        toc=not args.no_toc, sign_mode=args.signature,
        author=args.author, author_bio=args.author_bio,
        auto_number=args.auto_number,
    )

    title = args.title
    if not title and md_text.startswith("---"):
        end = md_text.find("\n---", 3)
        fm = md_text[3:end] if end > 0 else ""
        m = re.search(r"^title:\s*(.+)$", fm, re.M)
        if m:
            title = m.group(1).strip().strip("\"'")
    subtitle = ""
    if md_text.startswith("---"):
        end = md_text.find("\n---", 3)
        m = re.search(r"^subtitle:[ \t]*(\S.*?)[ \t]*$", md_text[3:end] if end > 0 else "", re.M)
        if m:
            subtitle = m.group(1).strip().strip("\"'")
    if not title:
        for line in md_text.split("\n"):
            if line.startswith("# "):
                title = line[2:].strip()
                break
    title = title or args.slug

    embed_stats = None
    if args.embed_images:
        body, embed_stats = embed_images_inline(body, args.out_dir)

    page = PAGE_TPL.format(
        title=esc(title), body=body, accent=theme["accent"],
        text=theme["text"], font_size=theme["font_size"],
        line_height=theme["line_height"], font_stack=theme["font_stack"],
        notice=build_notice(embed_stats is not None,
                            embed_stats["count"] if embed_stats else len(assets)),
    )
    html_path = os.path.join(args.out_dir, "%s-公众号版.html" % args.slug)
    atomic_write(html_path, page)

    manifest = write_manifest(args.out_dir, args.slug, title, assets, diagrams,
                              theme, footnotes, embed_stats is not None, subtitle)

    plain = re.sub(r"<[^>]+>", "", body)
    print("HTML     : %s" % html_path)
    audit = audit_inline(body)
    errors = [m for lv, m in audit if lv == "ERROR"]
    warns = [m for lv, m in audit if lv == "WARN"]
    if errors or warns:
        print("合规自检 : %s(ERROR %d / WARN %d)"
              % ("✗ 未通过" if errors else "△ 通过但有提示", len(errors), len(warns)))
        for m in errors:
            print("   [ERROR] %s" % m)
        for m in warns[:8]:
            print("   [WARN ] %s" % m)
        if len(warns) > 8:
            print("   …… 另有 %d 条 WARN" % (len(warns) - 8))
    else:
        print("合规自检 : ✓ 无告警(标签/属性/宽度/对齐 全部通过)")
    print("清单     : %s" % manifest)
    if args.preview:
        shot = preview_png(html_path, os.path.join(args.out_dir, "预览.png"))
        print("图文预览 : %s" % (shot or "未生成(没找到 Chrome / Chromium,可设 CHROME_PATH)"))
    if embed_stats:
        print("图片内嵌 : ✓ %d 张 / %.0f KB(base64 后约 %.1f MB)"
              % (embed_stats["count"], embed_stats["bytes"] / 1024,
                 embed_stats["bytes"] * 4 / 3 / 1024 / 1024))
        if embed_stats["skipped"]:
            print("           未内嵌:%s" % "、".join(embed_stats["skipped"]))
    print("主题     : %s(%s) / 标题样式 %s / 代码色板 %s"
          % (theme["name"], theme.get("id", "-"), theme.get("h2_style", "number"),
             theme.get("code_scheme", "mono")))
    print("图片     : %d 张(%d 远程)" % (len(assets), sum(1 for a in assets if a.get("remote"))))
    print("图表     : %d 个 mermaid" % len(diagrams))
    print("脚注     : %d 条" % len(footnotes))
    print("正文字数 : %d" % len(plain))


if __name__ == "__main__":
    sys.exit(main())
slack-gif-creatoranthropics/skillsKnowledge and utilities for creating animated GIFs optimized for Slack. Provides constraints, validation tools, and animation concepts. Use when users request animated GIFs for Slack like "make me a GIF of X doing Y for Slack."Stars: 198kUpdated Claude CodeCodexVerifiedInstall
ponytailDietrichGebert/ponytailLazy senior dev mode for any coding task: the smallest change that fully solves it, and a reply a busy human understands in one read.Stars: 194kUpdated Claude CodeCodexVerifiedInstall
ponytail-debtDietrichGebert/ponytailHarvest every shortcut: comment into one debt ledger, so deferrals get tracked instead of forgotten. One-shot report.Stars: 194kUpdated Claude CodeCodexVerifiedInstall
ponytail-debtDietrichGebert/ponytailList every `shortcut:` comment (and older `ponytail:` ones) as a debt ledger. One-shot report, changes nothing. Use for "ponytail debt", "what did ponytail defer", "list the shortcuts", /ponytail-debt.Stars: 194kUpdated Claude CodeCodexVerifiedInstall