@topmindspace/topmind-skills 4.13.0

package/topmind-wechat/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/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/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/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/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/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 不是「可以忽略」，而是「已知风险，需确认是否可接受」。

package/topmind-wechat/references/known-pits.md

@@ -0,0 +1,86 @@
+# 已知坑（实测踩过，写入质检与操作纪律）
+
+## 1. `--embed-images` 不加 = 粘贴丢图
+
+链路：HTML `src="images/xx.png"` → 浏览器复制序列化成 `file://` → 公众号后台取不到 → **整张 `<img>` 消失**（不是裂图）。
+
+**修法**：`md2wechat.py --embed-images`（base64 内嵌）。`images/` 仍导出作占位符兜底。
+
+自检：
+
+```bash
+grep -c 'src="images/' <包>/*-公众号版.html     # 期望 0
+grep -c 'src="data:image/' <包>/*-公众号版.html  # 期望 = 正文图数
+```
+
+## 2. 图片 basename 撞名 → 链式全挂
+
+`resolve_image()` 按 **basename** 复制到 `images/`。`images/bare/01.png` 与 `images/01.png` 同名 → 产出 `01-1.png` → 删副本 = HTML 图全挂。
+
+**铁律**：
+
+- 正文只引用 `images/XX.png`，包内只放正文那一套  
+- 多套用不同前缀（`full-` / `bare-`），不要靠子目录区分  
+- `-1` 副本不是垃圾，是 HTML 正在引用的文件  
+
+自检：
+
+```bash
+find <包> -name "*-1.*"    # 不应有任何结果
+```
+
+## 3. 同一文件并行 Edit 只落盘一部分
+
+同一条消息多个 Edit：工具可能都回 Successfully，**只有部分落盘**。
+
+**纪律**：改完必须 `grep` 关键词复核；多处改动合成一个脚本一次写完，或串行分轮。
+
+## 4. `::: stat` 非管道行被静默丢弃
+
+容器内每行必须 `数值 | 说明`。不带 `|` 的行整块消失且无报错。生成 HTML 后抽查容器内容。
+
+## 5. 表格单元格 `|` 要转义
+
+生成 markdown 表时 `.replace(/\|/g, '\\|')`。JS 模板字符串里写 `\\\\|` 才得到 `\\|`。
+
+## 6. 代码块长行被 `break-all` 词中切断
+
+JSON 示例行宽压到 ~55 字符；真实节选注明「节选」，字段值不得改写。
+
+## 7. 图文两套同名 + 清理 `bare/` 
+
+完整版与纯图形版共处包内必撞名。完整版放研究层；交付包只留正文用的一套。
+
+## 8. 外部工具改稿的数字漂移
+
+「比值对但绝对值错」= 从别的口径倒推。先脚本回溯 `results/*.json`，再改文字。
+
+## 9. 表格手抄必漂移
+
+从数据源生成（脚本直出）。同一文档两份拷贝时 `md5` 比对；派生汇总字段也是数据，要回填。
+
+## 10. qu-aiwei 误报别改坏
+
+- 「排比三段式」可能误报数据变化（从 A 到 B）→ **保留**  
+- 专有名词「复盘」→ 不改；动词套话 → 改  
+
+## 11. 满分仍「太 AI」
+
+词面 100 分只证明无套话。再查四症状：段末金句癖 / 节奏过分整齐 / 没有「我」与场景 / 报告体标注。
+
+## 12. 加「人味」用力过猛
+
+社交垫词（「先说个好消息」「说白了」）不是人味。判据：删掉后读者少知道了什么？
+
+## 13. 长文零容器 = 视觉窒息
+
+每 1500–2500 字至少一个 `::: stat` 或 `::: pull`。8000 字纯段落反面教材。
+
+## 14. 复制依赖 `execCommand`
+
+Safari 可能失败 → 手动全选复制。Desktop/移动端提供按钮 + 失败提示。
+
+## 15. 合规自检误报
+
+- 正文 `<h2>` 是有意设计（不用 h1）  
+- `pre` 会命中英文单词；只在 `<article>` 内按标签形式匹配  

package/topmind-wechat/references/theme-map.md

@@ -0,0 +1,139 @@
+# 题材 → 主题映射
+
+「按题材分主题」的规约。主题文件在 `assets/themes/*.json`，
+命令行 `--theme` 选主题，`--list-themes` 看全部，`genre:题材` 按题材自动选。
+
+## 已注册主题
+
+| 主题 | 标识 | 主色 | 标题样式 | 圆角 | 适用题材 |
+|---|---|---|---|---|---|
+| 极简黑白灰 | `minimal-ink` | `#A6524A` 砖红 | number | 4px | **默认**、观点、深度分析、随笔 |
+| 科技蓝 | `tech-blue` | `#185FA5` 蓝 | number | 6px | 教程、实操、工具测评、建站 |
+| 石墨灰阶 | `graphite` | `#52525B` 石墨 | underline | 0px | 技术说明、专业评论、方法、原理 |
+| 报纸纸感 | `newsprint` | `#8C5A3C` 棕（衬线） | center | 0px | 复盘、特稿、行业观察、长文 |
+| 琥珀评测 | `amber-review` | `#B45309` 琥珀 | number | 6px | 评测、模型评测、数据对比、榜单、速览 |
+
+```bash
+# 看清单
+python3 scripts/md2wechat.py --list-themes
+
+# 指定主题（三种写法都可以）
+--theme amber-review        # 标识
+--theme 琥珀评测            # 中文名
+--theme genre:评测          # 按题材自动选
+```
+
+## 选题材的原则
+
+**一句话**：主题跟着**题材**走，不跟着心情走。同一个题材永远用同一套主题，
+读者才能形成视觉记忆。换题材时才换主题。
+
+| 判断依据 | 走哪个主题 |
+|---|---|
+| 有大量数据对比、榜单、多维评分 | 琥珀评测 |
+| 有步骤、命令、可复现的操作过程 | 科技蓝 |
+| 讲原理、讲机制、专业观点输出，需要克制 | 石墨灰阶 |
+| 讲一个完整案例的来龙去脉、时间跨度长 | 报纸纸感 |
+| 观点表达、行业观察、随笔，没有明显题材特征 | 极简黑白灰（默认） |
+
+**题材交叉时**（如"带步骤的模型评测"）：看**读者来干什么**。
+来抄操作步骤的 → 科技蓝；来看结论和数据的 → 琥珀评测。
+
+## 主题之间必须一致的东西
+
+换主题**只换色彩与标题形态**，以下参数在所有主题间保持一致，不要随手改：
+
+| 参数 | 统一值 | 理由 |
+|---|---|---|
+| 正文字号 | 16px | 公众号长文阅读舒适区 |
+| 行高 | 1.75（报纸纸感 1.8） | 低于 1.7 会挤 |
+| 段间距 | 22px（报纸纸感 24px） | 与行高成比例 |
+| 对齐 | `left` | 中文 `justify` 会产生「河流」并触发格式告警 |
+| 章节编号 | 全部由排版层生成 | 见 `element-spec.md`「章节编号」；末章收束类用 `∞` |
+| 视觉层级规则 | 锚点层 ≤5 / 标记层每段 1–3 | 与主题无关，是阅读规律 |
+
+**这些是阅读规律，不是审美偏好**，任何主题都不该改。
+
+## 每套主题必须提供的字段
+
+新增主题时字段缺一个，就会继承默认主题的值——**这正是历史 bug 的成因**：
+`tech-blue` 当年只写了 14 个字段，`mark_bg` 落到默认主题的砖红浅底 `#FAF0EE`，
+一套蓝色主题里冒出砖红高亮，于是从来没人敢用它。现在 `load_theme()` 会按各自主色
+自动派生 `accent_light` / `accent_soft`，但**其余字段仍需显式写全**。
+
+```jsonc
+{
+  "id": "标识（英文，命令行用）",
+  "name": "中文名",
+  "genre": ["题材1", "题材2"],        // `--theme genre:题材` 按此匹配，也用于 --list-themes 展示
+
+  // 主色三件套：派生色可不写（自动按 accent 算），写了则以文件为准
+  "accent": "#______",               // 唯一强调色
+  "accent_light": "#______",         // 关键词下划线（标记层）
+  "accent_soft": "#______",          // 高亮底 / 徽章底
+
+  // 文字四级
+  "text": "#______",                 // 正文
+  "text_strong": "#______",          // 加粗、标题
+  "text_muted": "#______",           // 斜体、脚注
+  "text_light": "#______",           // 图注、数值说明、导读截断提示
+
+  // 面与线
+  "surface": "#______",              // 卡片底（stat/引用/签名/导读共用）
+  "border": "#______",               // 表格线、金句上下框线
+  "img_border": "#______",           // 图片描边
+
+  // 代码块：色板按 accent 自动生成，配色方案二选一
+  "code_bg": "#______",
+  "code_text": "#______",
+  "code_scheme": "mono",             // mono（推荐，只用主色+明暗）| palenight（不推荐）
+
+  // 四种语义色（容器左边框）
+  "c_note": "#______", "c_tip": "#______",
+  "c_warn": "#______", "c_danger": "#______",
+
+  // 形态
+  "radius": "0px | 4px | 6px",       // 全主题统一圆角；直角最保守
+  "h2_style": "number | bar | underline | center | plain",
+  "line_height": "1.75",
+  "para_gap": "22px",
+  "align": "left",
+  "font_size": "16px",
+
+  // 结构组件
+  "toc": true, "toc_max": 5, "toc_min_h2": 4, "toc_min_chars": 2000,
+  "table_max_cols": 3,               // 超过就转卡片化
+
+  "font_stack": "...", "mono_stack": "..."
+}
+```
+
+## 加一套新主题的步骤
+
+1. 在 `assets/themes/` 写 `{id}.json`，字段按上表写全
+2. 跑 `python3 scripts/md2wechat.py --list-themes` 确认能被列出
+3. 用一篇真实稿跑一遍，确认 `合规自检` 为 0 ERROR：
+   `python3 scripts/md2wechat.py --input 稿.md --out-dir /tmp/t --slug t --theme {id}`
+4. 在本文件的主题表里登记一行
+5. 目视核对：**下划线色、高亮底、代码块关键字色是否都跟本主题主色同源**
+   （不同源 = 又出现了色彩外溢）
+
+## 主题与视觉层级的配合
+
+三层标记手段在所有主题下的表现：
+
+| 层 | 手段 | 主题相关性 |
+|---|---|---|
+| 锚点层 | 主色加粗 / 深色底白字引用 | 用 `text_strong`，**不用 accent**——浅色主题下 accent 加粗不够重 |
+| 标记层 | 下划线 `accent_light` | 浅色主题用浅色调（砖红→`#E3BAB3`）；深色主题用主色本身（石墨→`#52525B`） |
+| 容器层 | 底色 `surface` + 左边框 `accent` | 全主题统一结构，只换色 |
+
+石墨灰阶的下划线特意用主色本身而不是浅色调：灰色主题里浅灰下划线几乎看不见，
+起不到标记作用。**下划线色的选择标准是「能不能看见」，不是「够不够淡」。**
+
+### `h2_style` 会连带影响导读
+
+导读（前言看点）的标记跟随 `h2_style`：带编号的主题（`minimal-ink`/`tech-blue`/`amber-review`）
+导读也编号，末章收束类同为 `∞`；不带编号的主题（`graphite` 下划线 / `newsprint` 上下框线）
+导读只能用中性圆点。**换主题时导读会自动跟着变，不用手改**——但如果发现"导读有 01、正文没编号"，
+那是渲染器 bug，不是主题配置问题。

package/topmind-wechat/references/typography-rules.md

@@ -0,0 +1,62 @@
+# 公众号改稿规则（Stage 1 执行标准）
+
+从技术博客 Markdown 到公众号稿，改的是**阅读节奏**，不是技术事实。事实、数据、链接一律不动。
+
+## 必须做
+
+1. **开头 150 字内给钩子**：结论、反差或悬念，不要背景铺垫。原文首段若是长背景，压缩或后移。
+2. **段落切分**：单段 ≤ 110 字（约 4 行手机屏）。长段按语义断点拆开，不要机械等分。
+3. **小标题序号化**：二级标题统一「一、二、三」或「01 / 02」，读者能感知进度。
+4. **列表项 ≤ 70 字**：超长列表项改成「加粗小标题 + 短说明」的段落组。
+5. **重点加粗**：只加粗结论句和关键数据，全篇加粗密度控制在每 20 字不超过 1 处。
+6. **长句拆短**：单句 > 45 字且有逗号堆叠时，拆成两句。
+7. **图注统一**：`*▲ 图 N：说明*`，图注要说出「看什么」，不要只重复图片名。
+8. **外链处理**：保留可点性无意义，改为「来源：XXX（URL）」的灰色小字或直接写机构名。
+9. **结尾三段式**：一句总结结论 → 一句抛出问题/邀请讨论 → 引导关注语。
+
+## 不要做
+
+- 不改技术事实、不改数据、不改评测结论
+- 不删代码块（公众号读者需要可复制的配置/命令）
+- 不把「我」改成「笔者」「作者」等腔调词，第一人称是这类文章的信任来源
+- 不加「随着...的发展」「在当今时代」这类 AI 腔 / 八股开场
+- 不加 emoji 堆砌的小标题
+- 不为了凑字数注水，公众号长文 3000-6000 字是合理区间
+- 中英文/数字之间忘了空格没关系（lint --fix 会补），但**别手动在代码和链接里加**
+
+## 容器语法使用时机（v2）
+
+| 时机 | 用法 |
+|---|---|
+| 一句话核心观点、想让它从版面上跳出来 | `::: pull` 金句容器（大字居中，前后留白） |
+| 关键数据对比（如「62.7% vs 99.9%」） | `::: stat` 数据卡（大数字 + 注释） |
+| 补充但不打断主线的信息 | `::: note` 灰色提示框 |
+| 操作建议、经验窍门 | `::: tip` 绿色提示框 |
+| 容易踩的坑、官方风险提示 | `::: warn` 橙色 / `::: danger` 红色 |
+| 观点交锋、问答式段落（A: B:） | `::: dialogue` 对话容器 |
+| 版本号、状态标签、关键词打标 | `[!新特性]` 行内徽章 |
+| 全文最重要的 1-3 句 | `==高亮==`（节制使用） |
+
+原则：**每 800 字最多 1 个容器**，容器是调味料不是主菜；连续两种容器相邻会显得杂乱。
+
+## 去 AI 腔检查点
+
+- 排比三连句（"不是 A，不是 B，而是 C"）出现超过 2 次 → 改写
+- 「值得注意的是」「综上所述」「不难看出」→ 删
+- 每段都以「首先/其次/最后」开头 → 打散
+- 形容词堆叠（"极其轻巧稳定的架构"）→ 留一个
+
+## 排版参数基线（调研印证的通用规范）
+
+- 正文 16px、行距 1.75、字间距 0、左对齐（不用 justify，会被格式检测判为非标准值）
+- 段间距 22px 代替首行缩进（手机端惯例）
+- 正文色 #333（纯黑 #000 在白底上过刺眼），辅助文字 #888
+- 代码块深底浅字（浅灰底代码块在部分安卓机型上对比度不足）
+
+## 交付前自检
+
+```bash
+python3 scripts/lint-wechat.py --input 公众号稿.md --fix
+```
+
+错误项（长段 > 200 字 / 图片缺失/过大）必须清零；警告项逐条判断是否接受。