@topmindspace/tms-skills 0.1.18 → 0.2.0

package/topmind-wechat-post/SKILL.md

@@ -0,0 +1,208 @@
+---
+name: topmind-wechat-post
+description: "公众号文章全生命周期技能：交付包、审校改写、质量三关（事实/逻辑/去AI味）、状态同步、微信内联排版与发布清单。Use when 写公众号、公众号排版、定稿、发公众号。Do NOT use for 只改错别字、小红书/知乎、纯网页发布。"
+triggers:
+  - 公众号
+  - 微信排版
+  - 公众号排版
+  - 公众号稿
+  - 排版这篇文章
+  - 定稿
+  - 发公众号
+  - 公众号交付
+  - wechat
+  - mp format
+tags: [wechat, typography, formatting, publishing, markdown, write]
+author: TopMindSpace
+license: MIT
+homepage: https://github.com/topmindspace/tms-skills
+updated: 2026-09-29
+---
+
+# topmind-wechat-post · 公众号创作技能
+
+**公众号专用写作技能**。管一篇公众号文章从选题/底稿到发布清单的完整生命周期。
+
+```
+选题/底稿 → 创作 → 质量三关 → 定稿(状态+目录) → 排版 → 发布清单 →（可选）回推 notes
+```
+
+> 用户明确说公众号 / 微信排版时进本技能；通用长文写作不在本技能范围内。
+
+## 脚本（真源）
+
+| 脚本 | 用途 |
+|------|------|
+| `scripts/new-article.py` | 建交付包（骨架稿 + frontmatter + images/diagrams） |
+| `scripts/sync-status.py` | 状态 ⇄ 目录名 ⇄ 字数（草稿 / 定稿 / 已发布） |
+| `scripts/sync-mapping.py` | 映射一致性（frontmatter + 目录 + 可选 notes + topic 总表） |
+| `scripts/push-to-topstream.py` | 可选回推：公众号稿降级为纯 Markdown notes |
+| `scripts/lint-wechat.py` | 排版体检 + 自动修复（中英文间距、段长、AI 腔…） |
+| `scripts/md2wechat.py` | Markdown → 全内联 HTML；**必加 `--embed-images`** |
+| `scripts/scan_ai_flavor.py` | 中文去 AI 味扫描（与 `qu-aiwei-zh` 同源） |
+
+```bash
+# 路径解析：CLI --base/--workspace → env TOPMIND_WECHAT_BASE / TOPMIND_WORKSPACE / TOPSTREAM_ROOT → 惯例
+export TOPMIND_WORKSPACE=/path/to/workspace   # 推荐
+python3 scripts/new-article.py --slug demo --title "标题" --direction reverse
+python3 scripts/lint-wechat.py --input <包>/公众号稿.md --fix
+python3 scripts/scan_ai_flavor.py <包>/公众号稿.md          # 目标 ≥85
+python3 scripts/md2wechat.py --input <包>/公众号稿.md --out-dir <包> --slug demo \
+  --asset-root <素材根> --embed-images
+python3 scripts/sync-status.py --set 定稿 <包> --apply
+```
+
+细节见 [`references/workflow.md`](references/workflow.md) · [`references/known-pits.md`](references/known-pits.md)。
+
+## 路径默认
+
+| 用途 | 解析 |
+|------|------|
+| 交付包根 | `--base` → `TOPMIND_WECHAT_BASE` → `{ws}/40-创作/2026-公众号` 或 `{ws}/20-专题/2026-公众号` |
+| 工作区 | `TOPMIND_WORKSPACE` |
+| 底稿/回推 | `--topstream` → `TOPSTREAM_ROOT` → 可选；不存在则跳过 notes 校验 |
+| 终稿交付 | 可 `save-output` 拷贝到 role:delivery（`88-交付/`），包仍留在创作类专题 |
+
+## 三条路径
+
+### forward（底稿 → 公众号）
+
+```
+底稿 notes/*.md → 审校改写 → 质量三关 → 定稿 → 排版 → 发布
+```
+
+`new-article.py --direction forward --source-file notes/xxx.md`
+
+### reverse（选题原创）
+
+```
+选题包 → 调研素材 → 多轮改稿 → 三关 → 定稿 → 排版 → 发布 →（可选）push-to-topstream
+```
+
+`new-article.py --direction reverse`（`target_file: pending`）
+
+### 站外拉取（转载整合 / 在线精选站）
+
+源不在本工作区、也不在 topstream `notes/` 时，**仍落 `reverse` + `target_file: pending`**。  
+**不要用 `forward`**：它要求 `source_file` 以 `notes/` 开头且文件真实存在，站外源必然过不了 `sync-mapping.py`。
+
+```bash
+python3 scripts/new-article.py --slug <中文短名> --title "<标题>" --direction reverse
+```
+
+取源坑（Next.js 站点）：正文在 RSC 载荷里，优先 `GET /api/notes/<id>`；图片在 `/api/uploads/<hash>`，记 hash→本地名映射；同图双 hash 用 `md5` 去重。差异与口径写进包内 `README.md`。
+
+**回推纪律**：notes 保持纯 Markdown。`::: 容器` / 徽章 / `==高亮==` 只进公众号稿。回推**务必带 `--assets`**（否则 GitHub 上 `images/` 死链）：
+
+```bash
+python3 scripts/push-to-topstream.py <包> --target notes/xxx.md --assets          # dry-run
+python3 scripts/push-to-topstream.py <包> --target notes/xxx.md --assets --apply \
+  --asset-names "00-封面.jpg=01-cover.jpg,…"
+```
+
+## 交付包与状态
+
+```text
+YYYY-MM-DD-<中文短名>            # 草稿
+YYYY-MM-DD-<中文短名>-released   # 定稿 / 已发布
+├── 公众号稿.md                  # 唯一改稿入口
+├── <slug>-公众号版.html         # 浏览器打开 → 复制正文 → 粘贴后台
+├── 图片上传清单.md
+├── images/  diagrams/
+└── README.md                    # 包说明（可选）
+```
+
+**frontmatter（映射真源）**
+
+```yaml
+status: 草稿            # 草稿 | 定稿 | 已发布
+direction: reverse      # forward | reverse
+source_file: ""         # forward 填 notes/xxx.md
+target_file: pending    # reverse：pending | notes/xxx.md
+word_count: 0           # 纯中文字数，sync-status 维护
+```
+
+状态与目录名**不要手改**：
+
+```bash
+python3 scripts/sync-status.py --set 定稿 <包> --apply
+```
+
+## 质量三关（定稿前必过）
+
+### 关 1 · 事实
+
+- 承重数字回**一手来源**；厂商口径 / 据报道 分开写  
+- 查不到一手来源的传闻**删**  
+- 改稿续写：正文已有数字**回源重核**（上一轮文本最不可信）  
+- 多口径（主轮/复跑）显式拆开；表格从数据源生成，禁止手抄  
+- 外部工具改过的稿：**先核数字再动文字**；「比值对但绝对值错」= 全段重核  
+
+### 关 2 · 逻辑
+
+- 单边结论旁配反方证据  
+- 结构前后一致；同一事实多处同值  
+
+### 关 3 · 文字（去 AI 味）
+
+```bash
+python3 scripts/scan_ai_flavor.py <包>/公众号稿.md   # ≥85（人话）
+```
+
+- 删套话/黑话/工程圈行话；降调段末加粗金句  
+- **满分 ≠ 有人味**：再查「段末金句癖 / 节奏过分整齐 / 没有场景与我 / 报告体标注」  
+- **口语化 ≠ 有人味**：删社交垫词（元叙述、空转过渡、姿态句）  
+- 判据：**这句话删掉之后，读者少知道了什么？**  
+
+详见 [`references/writing-quality.md`](references/writing-quality.md)。
+
+## 排版要点（写稿时）
+
+- 开头 150 字内钩子；单段 ≤110 字；列表项 ≤70 字  
+- 二级标题序号化；容器：`::: stat|pull|note|tip|warn|danger|dialogue`  
+- **`::: stat` 内必须是 `数值 | 说明` 管道行**，否则静默丢弃  
+- 评测稿：**图承担数据，正文只解读**；健康密度 **300–450 字/图**  
+- 个股用词红线：禁用 买入/推荐/目标价…；文末投资声明  
+
+更多：[`references/typography-rules.md`](references/typography-rules.md) · [`references/wechat-constraints.md`](references/wechat-constraints.md)。
+
+## 排版与导出（必读）
+
+```bash
+python3 scripts/md2wechat.py \
+  --input <包>/公众号稿.md --out-dir <包> --slug <slug> \
+  --asset-root <素材根> --embed-images \
+  [--theme assets/themes/minimal-ink.json]
+```
+
+1. **永远 `--embed-images`**，否则粘贴丢图（相对路径被序列化成 file://）  
+2. **图片 basename 铁律**：正文引用名 = `images/` 目标名；禁止两套同名图共处  
+3. 合规自检出现 `✗` 改生成器，不要手改 HTML  
+
+坑清单：[`references/known-pits.md`](references/known-pits.md)。
+
+## 主题
+
+| 文件 | 风格 | 适用 |
+|------|------|------|
+| `assets/themes/minimal-ink.json`（默认） | 黑白灰 + 砖红 | 深度研析 / 观点 / 随笔 |
+| `assets/themes/tech-blue.json` | 科技蓝 | AI/技术 |
+| `assets/themes/newsprint.json` | 报纸衬线 | 人文评论 |
+| `assets/themes/graphite.json` | 石墨克制 | 严肃报告 |
+| `assets/themes/amber-review.json` | 琥珀评测 | 产品评测 |
+
+`md2wechat.py --list-themes` 看全部；`--theme genre:评测` 可按题材自动选。  
+渲染规格见 [`references/element-spec.md`](references/element-spec.md) · 主题映射见 [`references/theme-map.md`](references/theme-map.md)。
+
+**平台红线速查**（详见 [`references/wechat-constraints.md`](references/wechat-constraints.md)）：禁 `div`/`pre`/`h1`/`figure`/`thead`/flex/float/gradient/shadow；表格 `table-layout` 不写 fixed；列数 ≥4 转卡片。
+
+## 与 Desktop「公众号创作」
+
+可视化工作流伴面（若有）：包列表 → 改稿 → 三关 → 预览 → 导出。脚本语义以本技能为准。
+
+## When NOT to use
+
+- 只想改几个句子 → 直接编辑  
+- 小红书 / 知乎 / 掘金 → 平台约束不同  
+- 通用长文交付 → 不在本技能范围
+- 只去 AI 味不排版 → 中文走 `humanizer-zh`（先立保真边界）+ `qu-aiwei-zh`（再扫描定位）；英文走 `humanizer`

package/topmind-wechat-post/assets/themes/amber-review.json

@@ -0,0 +1,35 @@
+{
+  "id": "amber-review",
+  "name": "琥珀评测",
+  "genre": ["评测", "模型评测", "数据对比", "榜单", "速览"],
+  "accent": "#B45309",
+  "accent_light": "#E8C79A",
+  "accent_soft": "#FBF2E4",
+  "text": "#3A3226",
+  "text_strong": "#231A0E",
+  "text_muted": "#8A7A62",
+  "text_light": "#A3927A",
+  "surface": "#FAF6EF",
+  "border": "#EADFCB",
+  "code_bg": "#2B2620",
+  "code_text": "#EFE7DA",
+  "code_scheme": "mono",
+  "c_note": "#C7B9A2",
+  "c_tip": "#4F8763",
+  "c_warn": "#C98A2B",
+  "c_danger": "#BC4F3E",
+  "radius": "6px",
+  "font_size": "16px",
+  "line_height": "1.75",
+  "para_gap": "22px",
+  "align": "left",
+  "h2_style": "number",
+  "toc": true,
+  "toc_max": 5,
+  "toc_min_h2": 4,
+  "toc_min_chars": 2000,
+  "table_max_cols": 3,
+  "img_border": "#EDE2D0",
+  "font_stack": "-apple-system,BlinkMacSystemFont,'Helvetica Neue','PingFang SC','Hiragino Sans GB','Microsoft YaHei',sans-serif",
+  "mono_stack": "Menlo,Monaco,Consolas,'Courier New',monospace"
+}

package/topmind-wechat-post/assets/themes/graphite.json

@@ -0,0 +1,35 @@
+{
+  "id": "graphite",
+  "name": "石墨灰阶",
+  "genre": ["技术说明", "专业评论", "方法", "原理"],
+  "accent": "#52525B",
+  "accent_light": "#52525B",
+  "accent_soft": "#EFEFF1",
+  "text": "#3A3A3A",
+  "text_strong": "#1C1C1C",
+  "text_muted": "#7A7A7A",
+  "text_light": "#9E9E9E",
+  "surface": "#F4F4F4",
+  "border": "#E2E2E2",
+  "code_bg": "#262626",
+  "code_text": "#E4E4E4",
+  "code_scheme": "mono",
+  "c_note": "#BDBDBD",
+  "c_tip": "#6E7F6E",
+  "c_warn": "#A08B5E",
+  "c_danger": "#9C5B52",
+  "radius": "0px",
+  "font_size": "16px",
+  "line_height": "1.75",
+  "para_gap": "22px",
+  "align": "left",
+  "h2_style": "underline",
+  "toc": true,
+  "toc_max": 5,
+  "toc_min_h2": 4,
+  "toc_min_chars": 2000,
+  "table_max_cols": 3,
+  "img_border": "#EAEAEA",
+  "font_stack": "-apple-system,BlinkMacSystemFont,'Helvetica Neue','PingFang SC','Hiragino Sans GB','Microsoft YaHei',sans-serif",
+  "mono_stack": "'SF Mono',Menlo,Consolas,'Courier New',monospace"
+}

package/topmind-wechat-post/assets/themes/minimal-ink.json

@@ -0,0 +1,35 @@
+{
+  "id": "minimal-ink",
+  "name": "极简黑白灰",
+  "genre": ["默认", "观点", "深度分析", "随笔"],
+  "accent": "#A6524A",
+  "accent_light": "#E3BAB3",
+  "accent_soft": "#FAF0EE",
+  "text": "#333333",
+  "text_strong": "#1A1A1A",
+  "text_muted": "#888888",
+  "text_light": "#999999",
+  "surface": "#F7F7F7",
+  "border": "#E8E8E8",
+  "code_bg": "#2C2C2C",
+  "code_text": "#E8E8E8",
+  "code_scheme": "mono",
+  "c_note": "#C9C9C9",
+  "c_tip": "#5B8C5A",
+  "c_warn": "#C08A3E",
+  "c_danger": "#B5544C",
+  "radius": "4px",
+  "font_size": "16px",
+  "line_height": "1.75",
+  "para_gap": "22px",
+  "align": "left",
+  "h2_style": "number",
+  "toc": true,
+  "toc_max": 5,
+  "toc_min_h2": 4,
+  "toc_min_chars": 2000,
+  "table_max_cols": 3,
+  "img_border": "#F0F0F0",
+  "font_stack": "-apple-system,BlinkMacSystemFont,'Helvetica Neue','PingFang SC','Hiragino Sans GB','Microsoft YaHei',sans-serif",
+  "mono_stack": "Menlo,Monaco,Consolas,'Courier New',monospace"
+}

package/topmind-wechat-post/assets/themes/newsprint.json

@@ -0,0 +1,35 @@
+{
+  "id": "newsprint",
+  "name": "报纸纸感",
+  "genre": ["复盘", "特稿", "行业观察", "长文"],
+  "accent": "#8C5A3C",
+  "accent_light": "#D8C0A8",
+  "accent_soft": "#F3E9DE",
+  "text": "#2B2B2B",
+  "text_strong": "#14110E",
+  "text_muted": "#7A7268",
+  "text_light": "#9C938A",
+  "surface": "#F5F3EE",
+  "border": "#E2DDD2",
+  "code_bg": "#2E2B27",
+  "code_text": "#EDE8DF",
+  "code_scheme": "mono",
+  "c_note": "#B4AEA2",
+  "c_tip": "#5F7A55",
+  "c_warn": "#B07C33",
+  "c_danger": "#A24B3C",
+  "radius": "0px",
+  "font_size": "16px",
+  "line_height": "1.8",
+  "para_gap": "24px",
+  "align": "left",
+  "h2_style": "center",
+  "toc": true,
+  "toc_max": 5,
+  "toc_min_h2": 4,
+  "toc_min_chars": 2000,
+  "table_max_cols": 3,
+  "img_border": "#E5E1D8",
+  "font_stack": "'Songti SC','Noto Serif CJK SC','Source Han Serif SC',Georgia,'Times New Roman',serif",
+  "mono_stack": "'SF Mono',Menlo,Consolas,'Courier New',monospace"
+}

package/topmind-wechat-post/assets/themes/tech-blue.json

@@ -0,0 +1,35 @@
+{
+  "id": "tech-blue",
+  "name": "科技蓝",
+  "genre": ["教程", "实操", "工具测评", "建站"],
+  "accent": "#185FA5",
+  "accent_light": "#A9C9E8",
+  "accent_soft": "#EAF2FA",
+  "text": "#333333",
+  "text_strong": "#12233A",
+  "text_muted": "#6B7C93",
+  "text_light": "#96A3B4",
+  "surface": "#F2F6FB",
+  "border": "#DCE6F2",
+  "code_bg": "#1B2733",
+  "code_text": "#DCE6F2",
+  "code_scheme": "mono",
+  "c_note": "#A8B8C8",
+  "c_tip": "#3F8F6A",
+  "c_warn": "#C08A3E",
+  "c_danger": "#C0554A",
+  "radius": "6px",
+  "font_size": "16px",
+  "line_height": "1.75",
+  "para_gap": "22px",
+  "align": "left",
+  "h2_style": "number",
+  "toc": true,
+  "toc_max": 5,
+  "toc_min_h2": 4,
+  "toc_min_chars": 2000,
+  "table_max_cols": 3,
+  "img_border": "#E4EDF7",
+  "font_stack": "-apple-system,BlinkMacSystemFont,'Helvetica Neue','PingFang SC','Hiragino Sans GB','Microsoft YaHei',sans-serif",
+  "mono_stack": "Menlo,Monaco,Consolas,'Courier New',monospace"
+}

package/topmind-wechat-post/package-lock.json

@@ -0,0 +1,16 @@
+{
+  "name": "topmind-wechat-post",
+  "version": "0.1.0",
+  "lockfileVersion": 3,
+  "requires": true,
+  "packages": {
+    "": {
+      "name": "topmind-wechat-post",
+      "version": "0.1.0",
+      "license": "MIT",
+      "engines": {
+        "node": ">=18"
+      }
+    }
+  }
+}

package/topmind-wechat-post/package.json

@@ -0,0 +1,16 @@
+{
+  "name": "topmind-wechat-post",
+  "version": "0.1.0",
+  "private": true,
+  "description": "公众号文章全生命周期：交付包、审校改写、质量三关、状态同步、微信内联排版与发布清单。",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/topmindspace/tms-skills.git",
+    "directory": "topmind-wechat-post"
+  },
+  "type": "commonjs",
+  "engines": {
+    "node": ">=18"
+  }
+}

package/topmind-wechat-post/references/design.md

@@ -0,0 +1,50 @@
+# topmind-wechat-post · 技能侧设计摘要
+
+> 技能边界以本文件、`SKILL.md` 和 `references/` 为准。不要另做一份用浏览器本地存储的公众号编辑器。
+
+## 定位
+
+- write 族**子技能**（`action_category: write` · `entrypoint: false` · pack `optional: true`）
+- 触发意图：公众号 / 微信排版 / 定稿 / 发公众号
+- 能力真源：`scripts/*.py`（stdlib）+ `references/*` + `assets/themes/*`（5 套，含 `amber-review`）
+
+## 路径解析
+
+`--base` → `TOPMIND_WECHAT_BASE` → `{TOPMIND_WORKSPACE}/40-创作|20-专题/{year}-公众号`；topstream 可选（`TOPSTREAM_ROOT`）。
+**禁止**把个人绝对路径写进脚本默认值；兜底惯例路径必须经环境变量可覆盖。
+
+## 三条路径
+
+- **forward**：`notes/*.md` → 公众号稿（`source_file`）
+- **reverse**：选题原创 → 公众号稿 → 可选回推（`target_file: pending`；回推**必须** `--assets`）
+- **站外拉取**：在线精选站/转载整合 → 仍用 `reverse` + `pending`（站外源不进 notes）
+
+## 质量三关 + 排版关
+
+事实 / 逻辑 / 文字（scan_ai_flavor ≥85 + 报告腔四症状）→ lint 0 error → md2wechat `--embed-images`。
+
+Desktop / 移动伴面只实现**约束子集**；完整语义以本目录 Python 为准。
+
+## references 索引
+
+| 文件 | 管什么 |
+|------|--------|
+| `workflow.md` | 流程/状态机/路径/站外拉取 |
+| `known-pits.md` | 实操坑 |
+| `element-spec.md` | 元素 → HTML 渲染规格 |
+| `theme-map.md` | 主题键 ↔ 题材映射 |
+| `wechat-constraints.md` | 平台硬约束（转换产物） |
+| `typography-rules.md` | 阅读节奏/段长 |
+| `writing-quality.md` | 质量三关 |
+
+## 已知分叉与对拍要求
+
+| 项 | 真源 | Desktop 子集 | 要求 |
+|----|------|--------------|------|
+| max-item | lint-wechat.py **70** | `WECHAT_MAX_ITEM` | 必须同值 |
+| AI 结构扣分 | scan_ai_flavor.structural | `structuralDeduction()` | 同规则 |
+| stat 管道行 | md2wechat 非 `\|` 丢弃 | wechat-format 同 | 同语义 |
+| embed-images | `--embed-images` | `WechatService.exportViaScript` **优先**；否则 `embedLocalImagesWithChecklist` | 同效果 + 上传清单 |
+| 导出真源 | `md2wechat.py` | 有 Python + 脚本时走 `wechat.exportViaScript` | 内置为回退 |
+
+改动任一侧规则时，**同一次改动**更新另一侧并跑 `tests/plugin-wechat-ui.test.mjs` 对拍断言。

package/topmind-wechat-post/references/element-spec.md

@@ -0,0 +1,162 @@
+# 元素渲染规范
+
+`md2wechat.py` 把 Markdown 转成公众号内联样式 HTML 的**唯一依据**。
+改渲染逻辑或新增语法时，先改本文件再改代码；`audit_inline()` 是本文件的自动校验版本。
+
+合规分级（贯穿全篇）：
+
+| 级别 | 含义 | 处理原则 |
+|---|---|---|
+| **S** 安全 | 内联纯色/边框/字号，不会静默失效 | 可以放心依赖 |
+| **D** 降级 | 可能被丢弃，但丢了不破坏结构与可读性 | 可用，但**不得作为唯一区分手段** |
+| **X** 禁用 | 会静默失效或整段被吞 | 一律不用；`audit_inline` 判 ERROR |
+
+---
+
+## 一、块级元素
+
+| Markdown | 产物 | 级 | 说明 |
+|---|---|---|---|
+| `# 标题` | `<p style="20px/700/center">` | S | 不用 `<h1>`（微信按标题语义覆盖字号） |
+| `## 标题` | `<h2 style="18px/700;color:text_strong">` + 自动编号 | S | 见下方「章节编号」 |
+| `### 标题` | `<h3 style="16px/600">` | S | |
+| `#### 标题` | `<h4 style="15px/600">` | S | |
+| 段落 | `<p style="margin:0 0 {para_gap};line-height:{line_height};letter-spacing:0.5px;text-align:left;word-break:break-word">` | S | `text-align` 只允许 left/center/right |
+| `---` | `<p style="center"><span style="display:inline-block;width:12%;height:2px;background:accent">` | D | 短横线依赖 `inline-block`；丢了会退化成一条不可见的行内元素 |
+| `> 引用` | `<section>` + `background:surface` + `border-left:3px solid accent` | S | **不用 `<blockquote>`**：微信有原生引用样式会覆盖我们的配色 |
+| `- 项` / `1. 项` | `<ul>`/`<ol>` + `<li>`，支持嵌套 | S | 圆点颜色取 accent |
+| ```` ```lang ```` | `<section background:code_bg>` → 语言标签 `<section>` → 代码体 `<section style="white-space:pre-wrap;word-break:break-all">` | S | **不用 `<pre>`**；详见「代码块」 |
+| 表格（≤3 列） | `<table style="width:100%">`，表头行是首个 `<tr>` | S | **不写 `table-layout:fixed`**，**不用 `thead/tbody/colgroup`** |
+| 表格（≥4 列） | 自动转卡片：每行一张 `<section>`，首列作标题、其余「列名 + 值」成对 | S | 公众号列数 >4 必然横向溢出，卡片化是唯一稳的解法 |
+| `![说明](src)` | `<section>` → `<p center>` → `<img style="max-width:100%;height:auto;display:block;margin:0 auto">` | S | **不用 `width:100%`**（小图被拉满变糊）；**不用 `<figure>`** |
+| `*图注*`（紧随图片） | `<p style="13px;color:text_light;center">` | S | 独立 `<p>`，不嵌在图片块里 |
+
+---
+
+## 二、行内元素
+
+| Markdown | 产物 | 级 | 视觉层级 |
+|---|---|---|---|
+| `**文字**` | `<strong style="font-weight:600;color:text_strong">` | S | **锚点层**，全文 ≤5 处 |
+| `*文字*` | `<em style="font-style:normal;color:text_muted">` | S | 弱化 |
+| `` `代码` `` | `<code style="background:surface;color:accent;font-family:mono">` | S | |
+| `==文字==` | `<strong>` + `background:accent_soft` | S | 容器层（高亮） |
+| `++文字++` 或 `<u>文字</u>` | `<span style="border-bottom:2px solid accent_light;font-weight:600;color:text_strong">` | S | **标记层**，每段 1–3 个 |
+| `~~文字~~` | `<span style="background:accent_soft;font-weight:600">` | S | 半高亮 |
+| `[!文字]` | `<span style="11px;color:accent;background:accent_soft;padding:1px 6px">` | S | 徽章；不用 `inline-block` |
+| `[文字](url)` | 正文 `文字` + 上标 `[n]`，文末「参考链接」块 | S | 公众号正文不支持可点外链 |
+
+### 视觉层级（三层，写稿时的标记纪律）
+
+| 层 | 手段 | 频率 | 用错会怎样 |
+|---|---|---|---|
+| **锚点层** | `**加粗**` | 全文 **≤5 处** | 到处加粗 = 没有重点 |
+| **标记层** | `++下划线++` | **覆盖 ≥60% 的正文段落**，每段 1–3 个 4–15 字短语 | 缺失 = 正文变成一堵灰墙，读者无处落脚 |
+| **容器层** | `==高亮==`、`::: 容器`、引用块 | 按需 | 堆太多会显得花 |
+
+标记层是**出现频率最高**的一层，也是最容易被漏掉的一层。
+
+`lint-wechat.py` 分两层判：**标记覆盖率 ≥60%**（带标记的正文段落数 ÷ 正文段落数，低于就报「跳读时没有落点」）+ **锚点加粗 ≤5 处**（超出就报「把标记当锚点用」）。
+
+**不用「强调占比」这个口径**——它把两层合成一个数，会同时掩盖两种病：锚点爆表（加粗 123 处）和标记归零（下划线 0 处）能算出相近的占比，但修法完全不同。占比还容易凑：35 段里只标 5 段、每段标 20 字也能到 10%，而整段划线等于没标。覆盖率对应的是「还有几段没标」这个可执行动作。
+
+---
+
+## 三、容器
+
+`:::` 是自研中间标记（公众号不认 Markdown，由 `md2wechat.py` 转成内联样式 HTML）。
+
+| 写法 | 产物 | 用在哪 |
+|---|---|---|
+| `::: note` | 灰边说明块 | 补充说明 |
+| `::: tip` | 绿边提示块 | 实操建议 |
+| `::: warn` | 琥珀边注意块 | 风险提醒 |
+| `::: danger` | 红边警告块 | 严重风险 |
+| `::: pull` | 上下框线 + 居中金句 | 全文点睛，1–2 处 |
+| `::: stat` | 浅底卡片 + 大号 accent 数字 | 关键数据（`数值 \| 说明` 每行一条） |
+| `::: dialogue` | 说话人 + 气泡 | 访谈、问答 |
+| `::: toc` | 前言导读卡 | 一般不用手写，见「自动导读」 |
+| `::: sign` | 尾部签名区 | 一般不用手写，见「自动签名」 |
+
+容器名拼错会**静默降级成 note**——`lint-wechat.py` 会报未知容器。
+别名（`info`/`memo`→note，`success`/`ok`→tip，`quote`/`golden`→pull，`data`/`metric`→stat，
+`chat`/`talk`→dialogue）等价。
+
+---
+
+## 四、三段自动行为
+
+### 章节编号
+
+- 标题里**手写的序号会被剥离**：`## 一、官方总表` → `01 官方总表`
+- 剥离规则：中文序号（`一、`/`第一、`）、阿拉伯序号（`1.`/`01 `）
+- 带负向断言保护：`## 3.4× 成本` **不会**被误剥成 `4× 成本`
+- 编号由 `h2_style` 决定：`number`（01 + 左竖条，默认）/ `bar`（仅左竖条）/
+  `underline`（下划线）/ `center`（上下框线）/ `plain`（无装饰）
+- **末章若为收束类用 `∞` 而不是顺延数字**：标题匹配
+  总结/结语/小结/尾声/后记/写在最后/写在后面/收尾/结尾/余论 时，编号取 `∞`
+  （`number` 样式下生效）。理由：数字编号暗示"还有下一节"，与收束章的定位打架。
+  实测 `## 六、总结` → `∞ 总结`，其余仍为 `01`…`05`。
+- **写稿时不要手写序号**：手写后序号变成不可编程的字符串，
+  换编号样式、加引用、做导航都得手改一遍
+
+### 前言导读
+
+- 触发条件（满足任一，且 `toc` 未被 `--no-toc` 关闭）：
+  - 章节数 ≥ `toc_min_h2`（默认 4）
+  - 章节数 ≥ 3 且正文 ≥ `toc_min_chars`（默认 2000 中文字）
+- 位置：**首个正文段落之后**（不是标题与封面图之间）
+- 内容：最多 `toc_max`（默认 5）条，超出时附注「……共 N 节」
+  ——**不假装全文只有这几节**
+- **导读的标记必须与正文标题一致**：
+  - 标题带编号（`number`）→ 导读也编号，末章收束类同为 `∞`
+  - 标题不带编号（`center`/`underline`/`plain`）→ 导读用中性圆点 `·`，
+    **不能凭空造出 01/02**（否则读者在正文里找不到对应的编号）
+- 显式 `::: toc` 优先于自动插入
+
+### 尾部签名
+
+`--signature` 三态：
+
+| 值 | 行为 |
+|---|---|
+| `auto`（默认） | 稿件末尾**已自带**签名/CTA 则不再追加，避免出现两处签名区 |
+| `on` | 无条件追加 |
+| `off` | 只在显式写了 `::: sign` 时渲染 |
+
+- 署名用占位 `{{作者名}}`，**不替用户编造人名**；`--author` / `--author-bio` 可填
+- 判定「已自带」的口径：正文末尾 8 个非空段落内出现
+  `点赞 / 在看 / 三连 / 点个关注 / 欢迎关注 / 关注「 / 扫码 / 分享给 / 我是…，`
+
+---
+
+## 五、代码块
+
+- **不用 `<pre>`**：公众号端不自动换行，窄屏横向溢出，且格式检测会标风险项
+- 用 `<section>` + `white-space:pre-wrap` + `word-break:break-all`
+- 缩进与换行由代码自身提供：**HTML 源码里不在 pre-wrap 容器内插入任何格式化换行**
+  （插了就会渲染出伪空行和大左缩进）
+- **色板跟随主题**（`code_scheme`）：
+  - `mono`（默认）：只用「主色 + 明暗层级」。注释最暗、字符串次之、
+    关键字取主色的提亮版、其余用 `code_text`
+  - `palenight`：Material Palenight 的 16 色，**已不推荐**——
+    天蓝/翠绿/橙红与砖红、琥珀等主色毫无关系，一篇文章里会出现两套色彩语言
+- 语言标签显示在代码体上方，字号 11px，颜色取 accent
+
+---
+
+## 六、`audit_inline()` 检查清单
+
+每次生成 HTML 后自动跑，`ERROR` 必须清零。检查项已按本文件分级：
+
+**ERROR**：`<div>` `<figure>` `<figcaption>` `<pre>` `<thead>` `<tbody>` `<colgroup>`
+`<h1>` `<iframe>` `<video>` `<script>` `<style>`；`text-align` 非标准值；
+px 固定宽度；`white-space:pre/nowrap`；`position/float/transform/opacity`；
+`display:flex/grid`；`-webkit-*`；`linear-gradient`；`box-shadow`；`rgba()/hsla()`；
+`var(--)`；`@media/@keyframes`；`class` 属性；Markdown 标记残留（`==`、`**`）
+
+**WARN**：`table-layout:fixed`（列宽均分）、`display:inline-block`（非常规 display 值）、
+`border-radius`（可能被丢，属优雅降级）、图片 `width:100%`、`id` 属性、
+`<img width="...">` 属性
+
+WARN 不是「可以忽略」，而是「已知风险，需确认是否可接受」。