LinuxPythonWorkshop 公众号排版标准流程

把一段 Linux 实操录屏沉淀成可发布的公众号图文。本技能是 video-content-ocr（取内容）与 wechat-draft-article（推草稿）之间的"排版标准层"——规定内容怎么写、截图怎么放、品牌怎么脱敏、推送怎么不误删。

何时用

• 用户给一段 Linux 实操录屏（Ansible/Ollama/OpenWebUI/...），要写成公众号文章
• 用户提到「公众号排版 / 公众号草稿 / 排版模板 / LinuxPythonWorkshop 排版 / 视频转公众号 / 推到公众号草稿箱」
• 任何需要把实验视频/截图沉淀成"跟着敲一遍"风格图文的场景

配套文件（v1.2.0 起，优先取用）

> 三者的关系：video-to-article-sop.md 是执行清单（勾选）、templates.md 是填空模板（取用）、本 SKILL.md 是规则详解（查原因）。

总流程（7 步）

1. 视频全片 OCR 取内容（不要只看开头）
2. 套用品牌/脱敏替换规则
3. 按标准章节结构写稿
4. 内联真实终端截图（铁律：代码块外）
5. 生成自包含本地预览
6. 用户确认后推送草稿箱（安全去重）
7. 推送前扫描清理（禁用词/来源修饰词/视频源词/截图品牌）+ 推送后 API 拉回复核（双保险，确认无问题再交付）

协作模式：边测边嵌图（推荐直播式写法）

27 期实战验证的高效流程：用户按 AI 给的命令在真实环境逐步实测、每步贴终端截图 → AI 把每张图存进 article_shots_xxx/ 并立刻嵌入 md 对应章节 → 全部章节跑通后再做去视频化 / 结构校验 → 用户终审通过才推送。

• 优点：截图 100% 真实、与代码逐节对应；真实故障即案例（死锁 / 满盘 / 站错机器直接写进报错排查节）。
• 关键：每收到一张截图先存盘再嵌入，避免漏存（曾因漏存 shot13 致加载失败，需从剪贴板历史补）；推送前用脚本校验图片文件全部存在且与 md 引用一一对应。

步骤 1：视频全片 OCR 取真实内容

本环境 Read 读图被系统过滤（"current model does not support images"），绝不能靠 Read 抽帧来"看"。改用 OCR 抓画面文字：

• 环境：已装 av / rapidocr-onnxruntime 的 Python 虚拟环境（venv），用当前项目实际在用的解释器即可，路径不固定。
• 验证：python -c "import av, rapidocr_onnxruntime; print('ok')"
• 先 probe 真实时长（av.open(path).streams.video[0]，用 vs.duration*vs.time_base 或解码计数），避免只扫前 8 分钟漏掉压轴内容。
• 全片均匀抽帧 + 逐帧 OCR（约 80 帧覆盖整段），run_in_background 后台跑（40 分钟视频约 9 分钟）。
• 按时间排序识别章节：理论 → 模块实战 → Playbook → 报错排查。
• 标题必须覆盖视频后段压轴内容（如 Nginx Playbook），不能只写开头模块。
• 细节见 video-content-ocr 技能。
• 知识点遗漏核查（交付前 / 用户质疑时）：当用户问"视频里是不是漏了 X（如颜色修改、某模块）"，用脚本在 OCR 全文 grep -i 关键词确认，不要凭印象答。
• 例：查颜色 → 搜 颜色|colors?|\[colors\]|nocolor|green|red|blue。若 [colors] 段 0 次、仅命中 nocolor = 0（且 md 已写该参数）→ 判定未遗漏，向用户说明；若用户能定位具体时间点，重新抽该帧核对。
• 内部溯源时间戳可用于定位，但不得写进正文。

步骤 2：品牌 / 脱敏替换规则（硬性，逐条必做）

写稿时对所有命令、截图文字、输出做以下替换（这些规则是 LinuxPythonWorkshop 跨项目个人惯例，也记在 MEMORY.md）：

源品牌词表（开工必做）：先从素材（视频画面 / OCR 文本 / 终端输出）中识别出第三方源品牌，构建其四种形态的词表——全称、简称、域名前缀、官网地址；下文所有替换与扫描一律以该词表为准。本技能不预设任何具体品牌名。

> 截图若含未替换的品牌/真实 IP，需用替换后的重截图表替换，不能直接留原图。

步骤 2.5：去除"来源修饰词"（去视频化的第二道关，硬性）

步骤 2 解决了"第三方品牌字样"，但正文里还有一类暗示文章来自某视频/旧教程的修饰词，同样会让读者产生"这是某期视频附属稿"的框架感，违反公众号图文本体定位。必须在推送前清零：

必须删除/改写的高频短语（命中即改）：

扫描模式（推送前脚本必跑，0 命中才算过）：
手册原视频|视频演示|部分旧教程|旧教程|教程里|有些资料|资料里|文档里|部分旧|某些|一些教程|网传|网上|官方文档|原视频|里写|里用|里提|里给|视频|演示|抽帧|录屏|字幕

> 注意：某些 这类词只在特指"某些教程/资料"时违规；若是技术泛指（如"某些 sudo 的 requiretty 配置"）属正常语境，保留。扫描命中后需逐条人工判断是否真为"来源修饰词"再删。任何一次推送前都必须把上面这套扫描跑完整、确认 0 命中，才允许推送草稿箱——即"先梳理一遍，没问题再推送"。

步骤 2.6：控制"引用块 / 代码块"长度（避免微信原创校验警告）

微信公众号原创校验会把文章里的长引用块（Markdown > 生成的 <blockquote>）和超长代码块（<pre><code>）判定为"引用他人内容"。单段字数超过约 300 字就会弹 "引用字数：309/300（单次引用不得超过 300 字，避免不合理引用）"，阻塞发布。

推送前处理原则：

1. 长引用块（>）一律改成普通正文：把多行 > 提示/讲解/排查步骤改为普通段落 + 粗体小标题（如 📌 **排查提示**： / 💡 **小知识**： / 📷 **上图说明**：）。保留少数极短（≤80 字）的单行提示可继续用 >。
2. 超长代码块拆段：如果一段 ```bash 代码块（尤其是 cat <<'EOF' 大段 heredoc）超过约 300 字，拆成 2~3 段，中间加一句原创讲解。例如 Tomcat Playbook 拆成"第一段写头部和变量"、"第二段追加 task 和 handlers"。
3. 扫描脚本（推送前必跑）：
   - 对生成的 HTML 抽所有 <blockquote> 和 <pre> 块；
   - 计算每块去除空白后的字符数；
   - 任一 blockquote/pre > 300 字 → 阻止推送，回 md 拆分/改写成普通段落后再推。

> 28 期真实案例：Tomcat 一键部署节的 cat > ~/ansible/tomcat.yml <<'EOF' 单段 heredoc 超过 600 字，且旁边的 💡 下载失败怎么办？ 长引用块超过 390 字，共同触发了"引用字数"警告。解决后把长引用块改普通段落、heredoc 拆成两段，警告消失。

步骤 3：标准章节结构（"跟着敲一遍"风格）

固定骨架，顺序不要乱：

• 00 导语：钩子——"今晚就能上手""跟着敲一遍就懂"，点出文章价值。导语末尾、分隔线 --- 前，加一个 📋 今日主要内容概要 编号清单框（1~6 节一句话概括），方便粉丝打开即定位想看的章节（27 期实证有效）。
• 01 环境准备：软件版本（ansible --version）+ /etc/ansible/hosts 主机清单（管理端/客户端）
• 02 模块热身 / 基础操作：每个动作配真实终端截图（见步骤 4）
• 03 进阶：Playbook 理论 / YAML 组件（Target/Variable/Task/Handler）
• 04 实战：主 hands-on——写剧本截图 → 执行结果多张截图 → 验证截图
• 报错排查：真实报错文本 + 根因 + 修正写法（并警示"错误写法"长什么样）
• 05 小结：对比表格（如 Ad-hoc vs Playbook）。若文章是"多版演进"结构（v1→v2→v3），小结不能只给一张 3×3 表，必须补三层：
  1. 演进路线：说明每一版解决了上一版的什么痛点；
  2. 选型建议：告诉读者什么场景用哪一版；
  3. 核心思想：把知识点升华成可迁移的方法论。
  同时注意：小结里的描述必须和各版代码块真实行为一致，不能凭记忆写"v1 无幂等"而实际 v1 已实现幂等。
• 进阶内容分层（实测 vs 代码赏析）：视频常含需专门环境（多机/负载均衡/Docker/JDK）的进阶 Playbook（如 Keepalived/Docker/Tomcat/LVS）。处理原则：
• 已实测章节（如 01~04）：真实跑通、实拍截图内联，作主 hands-on。
• 未实测进阶章节：整理为「进阶 Playbook 代码赏析」，明确标注「需对应环境，本文不强制你动手」。代码骨架必须来自视频 OCR（内部溯源可记时间戳如 881s/908s，正文不得出现），不得自行编造。
• 用户问"这实验我能做吗"→ 先给可行性结论（系统源是否匹配 openEuler / 磁盘空间 / 网络 / 是否已装），再建议靶机，不要默认照抄就跑通。
• "赏析→实测"升级留到下一版：除非用户明确要求，不把未实测章节强行标成已动手。
• 互动福利：找茬送宝典 / 打卡领福利，引导小程序 + 知识库创作学习
• 06 练习题 + 摘要（文末固定追加，教辅/引流必备）：
• 5 道选择题：每题 4 个选项，答案分布按用户指定（如"1-B/2-A/3-D/4-B/5-C"），不可自行改答案；每题附【答案提示】点出考哪个知识点
• 禁止出"考品牌替换规则"的题：如「源素材里的内网 IP 按品牌规则应改为？」这类只考文案加工规则（IP/前缀替换）的机械选择题，对读者无实战价值、纯属凑数，必须避免。选择题应聚焦本文核心知识点（幂等/vars/handlers/模块作用等）或"动手验证"类题型。
• "动手验证"题必须确保真实环境下可复现：出题前先想清楚读者照做会输出什么。若题目依赖"原始 v1"但实际 v1 已被优化、或环境已安装好，会出现"两次都是 changed=0 看不出区别"的翻车。若无法保证真实复现，就改成知识点选择题或代码结构分析题，不要硬凑"动手验证"。
• 2 道填空题：基于本文内容出题（版本号 / 端口 / 安装前缀 / 关键参数等），每题附【答案提示】
• 100 字内公众号摘要：钩子（今晚就上手 / 跟着敲一遍）+ 实机截图数量 + 动手引导，纯中文 ≤100 字，快速吸引粉丝实践
• 关键词 / 话题标签：文末或摘要后建议给出 3-5 个 # 关键词；必须与本文技术主题强相关，禁止残留其它文章标签（如 Nginx 文不能带 #Ollama #DeepSeek）。注意：公众号后台的「话题标签」无法通过 draft API 修改，需在后台草稿编辑器手动设置；若想随文章一起可控，可把关键词作为正文段落写进 Markdown 一并推送。

标题打磨：戳中粉丝"点进来 + 跟着敲"的欲望

标题决定打开率与动手意愿。27 期迭代 6 版验证：以下写法有效、以下写法无效（字节均按 UTF-8、≤64，见常见坑 45003）。

❌ 教材味/说教词（降点击、无情绪钩子）：
- 配置与基础实战、实战重点讲透、吃透 cfg 参数（含坑） —— 像课本目录；括号堆砌 （照敲就通含坑） 显拥挤别扭。

✅ 情绪钩子（公众号爆款逻辑，5 类任选）：
1. 痛点共鸣：「Ansible 卡在 cfg？这份配置照抄就跑通」——专治"会不会跑不起来"的恐惧；
2. 成果爽感：「配好 ansible.cfg，3 台机器一句话管完」——点出 Ansible 核心价值；
3. 动手乐趣：「别被参数吓退，Ansible 照敲一遍就上瘾」——最不像教材、情绪最轻；
4. 制造好奇：「Ansible 最难是第一步，我拆成照抄清单」——用"最难"勾起想看；
5. 快速上手+爽感（27 期定稿）：「Ansible 快速上手，cfg 照敲就停不下来」——点名核心文件 cfg + 透出跟着敲的爽感。

铁则：保留系列号 跟着敲一遍㉙：；可点名本文核心文件/成果（如 cfg、管 3 台），但避免堆砌说教词；全程禁用"视频/本期/这期"（见文案风格铁律）。给用户 3~4 个备选让其拍板，不要自作主张定稿。

标题打分（v1.2.0 起必做）：候选标题写好后跑评分器，一次可传多个自动排序：

python scripts/score_title.py "候选A" "候选B" "候选C"

六维度：字节长度 20 / 说教词 20 / 期数框架词 15 / 情绪钩子 20 / 系列号 10 / 成果点名 15。
<70 分不许定稿，按脚本给的改写建议调完再测；退出码 0 表示有候选过线。五级钩子备选池见 references/templates.md T8。

文案风格铁律：禁用"期数 / 视频"框架字样

文章是图文本体，不是某期视频的附属说明，全文不得出现以下字样（读者不应有"这是某一期视频"的框架感）：

• 禁用：本期视频、这期、本期、下期、本期实战、视频带你... 等期数/视频指代词。
• 导语改用：本文、这次实战、跟着练一遍、这套流程 等中性表述。
• 小结/展望改用：这次实战串起...、后续我们继续...、掌握...你就具备... 等，不写"下期"。
• 推送前用脚本扫一遍正文，命中上述字样即视为未通过（见步骤 7 验证清单）。
• 除了"期数/视频"指代词，任何暗示文章来自某视频/旧教程的来源修饰词也要清零（见步骤 2.5）：如 手册原视频里、视频演示里、部分旧教程里写的、有些资料里、本文命令均来自真实终端演示 等。这些词既含"视频"字样、又让读者产生"这是某一期视频附属稿"的框架感，必须改写为中性直接陈述。

教学深度：初学者讲解（知其所以然）

面向初学者粉丝，技术要点不能只给「是什么 / 怎么写」，还要讲清「为什么要这样写」，让其知其所以然、更快上手掌握：

• 在关键进阶代码块（如 notify+handlers 幂等守卫、YAML vars 变量化、幂等、脱敏规则等）下方，紧跟一段「📖 初学者讲解：为什么要 X？」白话段。放置顺序建议「代码块 → 讲解段 → 真实截图」，形成"代码→原理→实机"对照。
• 讲解写法三要素：
  1. 先抛痛点：不这样写会怎样（如 v1 每次重编译白费时间、硬编码换版本要改多处易漏改）。
  2. 生活类比 + 一句话口诀：如「notify 是变了才喊人、handlers 是被喊了才动 = 只做一次」；「vars 像配方顶部的主料清单，换主料不用重写步骤」。
  3. 对比演示：用「第一次跑 changed 触发 / 第二次跑 ok 跳过」讲幂等；并附「小提醒」指出入门写法的局限与真实项目推荐写法（如单 task notify 多个 handler 仅作演示，真实项目推荐每步自己 notify）。
• 注意：讲解段是普通 Markdown 段落 / 引用块，不要写进代码围栏；保持文章整体代码围栏成对、0 图在块内。

粉丝提问口吻（降低距离感，像社群答疑直播）

技术澄清类内容，优先用「第三方粉丝提问 → 答」的问答体，比作者直接说教更亲切：

• 结构：💬 【粉丝提问】：<粉丝口吻的困惑，可口语、可带笔误> 紧跟 📖 答：<原讲解内容>。
• 示例（ed25519 算法 vs passphrase 混淆）：粉丝问「教程写 ssh-keygen -t ed25519，ed25519 是干嘛的？那 lpw0803 又是什么？」→ 答里讲清 -t 是算法类型、lpw0803 是 passphrase（密码短语）、二者不是一回事，并可附 rsa/ed25519 对比表。
• 粉丝原话有笔误（如把 lpw0803 打成 1pwe803）→ 文中以正确值为准，备注说明即可，保持全文一致。
• 问答体仍是普通 Markdown，不进代码围栏；围栏成对、0 图在块内。

步骤 4：截图嵌入铁律（最常出 bug，务必遵守）

• 截图相对路径引用：必须用标准 Markdown 图片语法 ![alt](./article_shots_xxx/<file>.png)。
• 严禁用 HTML 注释 <!-- 配图: 描述 路径 --> 占位——VS Code / 普通 Markdown 预览器不会渲染，推送脚本转换后也识别不到 <img>，导致本地预览和公众号草稿箱都丢图（Docker ① 期踩坑）。
• 图片必须放在代码围栏 ``` 之外。误放进代码块内，Markdown 会把它当纯文本显示成 ![...](...) 原始字符（之前 user/cron/synchronize/shell 四张图误入代码块，渲染失败）。
• 标准范式——一张图配一段命令，逐个对照：

`textbash
[root@LinuxPythonWorkshop ~]# ansible 192.168.149.129 -m user \
-a "name=lpwstudio1 shell=/sbin/nologin"
```

````

• 截图从本机 clipboard-images/ 复制（cp，勿 mv 删源）到项目 article_shots_xxx/。
• 特例（视频帧全黑读不出时）：若 OCR 引擎（RapidOCR/EasyOCR）在本环境（Python 3.13 + numpy 2.5）跑不通、视频帧全黑提取不到可读文字，但作者直接提供了源文件（如 install_nginx_v1/v2/v3.yaml），可跳过 OCR 步骤，直接用源文件全文作为"可照抄代码块"替代终端截图——比假截图更准、更实用，且无需走 uploadimg 图床。此时文章内的 YAML 代码块即等同"真实终端截图（代码块外）"，仍满足步骤 4 铁律。
• 推送前用脚本校验：① 代码围栏成对闭合；② 0 张图在代码块内（见步骤 7 验证清单）。

步骤 5：本地自包含预览

• 生成 base64 内嵌的原图尺寸 PNG 预览 HTML（不要用 480px + JPEG q18 压缩，会糊）。
• 便于用户在本地 Markdown 查看器直接看到全部配图，无需先推草稿箱。
• ⚠️ 本地预览可用 base64；但推送到公众号草稿箱时，正文图片必须走 uploadimg 上传到 mmbiz.qpic.cn 再用 URL 引用——直接 base64 内嵌会触发 errcode 45002 content size out of limit。

步骤 6：推送草稿箱（安全！）

• 调用 wechat-draft-article 技能完成 md→图文转换与推送（图片走微信图床 mmbiz.qpic.cn，代码块表格注入内联 style）。
• 铁律：绝不删除用户其它草稿。 去重只用"自有 media_id 列表"：
• 维护项目目录下的 our_draft_ids.txt，记录每次本技能推送的 media_id。
• 推送前 draft/batchget（返回键是 item，不是 draft_list；count 最大 20，草稿多要 offset 分页拉全），凡是 media_id 在该列表里且仍存在的旧副本才删。
• 与标题乱码/隐藏字符完全无关，绝不靠"模糊标题/关键词"匹配删（会误删用户资料）。
• 推送后打印草稿箱全量清单（media_id + UTF-8 标题）让用户核对其它资料都在。
• 重推更新版（替换模式）：用户要求"把带 XX 的版本重新推送 / 刷新草稿"时，用 --replace 运行推送脚本。该模式在推送成功后，仅删除「media_id 在本技能 own 列表（our_draft_ids.txt）内 且 标题与本次推送完全相同」的草稿——即本文章上一版；绝不靠模糊标题匹配，也绝不碰 own 列表外的任何资料（如 LVS、用户手动建的"跟着敲一遍㉕"等标题不同的草稿）。删除后把 own 列表里对应的旧 id 替换为新 id。注意：替换模式不要对已成功推送的版本重复运行——旧版删完、列表里只剩当前版，重跑只会再建一份重复草稿。
• 未获用户明确确认前不推送。
• 图床策略（避免 45002）：
• 正文图片：先调 POST https://api.weixin.qq.com/cgi-bin/media/uploadimg?access_token=TOKEN 上传每一张图，获取 url（mmbiz.qpic.cn），再把 <img src="url"> 写进 content。
• 封面图：用 material/add_material?type=image 上传，得到 thumb_media_id。
• content 构建后控制在 <200KB，13 张图实测约 28KB，远低于 1MB 上限。

步骤 7：推送后 / 交付前验证清单

• [ ] 代码围栏成对闭合（grep -c '```' 为偶数）
• [ ] 0 张图在代码块内（脚本扫：代码块内不应出现 ](./article_shots_）
• [ ] 标题 ≤64 字；digest 写明"实机截图+踩坑"
• [ ] 全部替换规则已应用（源品牌词表已清零、提示符统一、源域名前缀→lpwstudio、101.→149.）
• [ ] 文案无"本期视频/这期/本期/下期/本期实战/视频带你"等期数框架字样（已用脚本扫正文确认 0 命中）
• [ ] 章节编号与目录一致、无遗漏截图、无虚构章节
• [ ] 本地预览：<img> 全部带 src；代码块/表格有内联 style
• [ ] content 大小 <200KB（mmbiz URL 引用，非 base64 内嵌）
• [ ] 文末含 06 练习题：5 选择（4 选项/题，答案分布按用户指定）+ 2 填空（基于本文）+ 答案提示
• [ ] 100 字内公众号摘要已写（纯中文 ≤100 字，钩子+实机截图+动手引导）
• [ ] 关键进阶概念（notify/handlers、vars 变量化、幂等、脱敏等）已配「📖 初学者讲解」段，讲清"为什么这样写"，面向初学者知其所以然
• [ ] 关键词/话题标签与本文内容一致，无其它文章遗留标签（如 Nginx 文不应出现 Ollama/DeepSeek）；后台话题标签 API 不可改，需在公众号后台手动核对
• [ ] 草稿箱仅剩目标草稿 + 用户其它资料（旧副本已清，零误删）
• [ ] 00 导语含 📋 今日主要内容概要 编号清单框（粉丝快速定位章节）
• [ ] 进阶章节已标注"实测"或"代码赏析（需对应环境，不强制动手）"，未实测内容未谎称已动手
• [ ] 标题用情绪钩子、无说教词（讲透/吃透/含坑），且已给用户 3~4 个备选拍板
• [ ] 标题已过 scripts/score_title.py ≥70 分（六维度全绿或已按建议改写）
• [ ] 写稿时已按 references/templates.md T1~T8 取用模板（导语概要框 / 小结三层 / 练习题组 / 初学者讲解段）
• [ ] 技术澄清类内容优先用「💬 粉丝提问 → 📖 答」问答体（降低距离感）
• [ ] 推送前图片文件全部存在且与 md 引用一一对应（含 local-file:/// 前缀已 strip，待上传数非 0）
• [ ] 禁用词机器扫描：对全正文（含标题）扫源品牌词表（全称|简称|域名前缀|官网地址四种形态），必须 0 命中（不只肉眼看）
• [ ] 来源修饰词/视频源词机器扫描：扫 视频|演示|抽帧|录屏|字幕|部分旧教程|旧教程|有些资料|教程里|资料里|文档里|部分旧|某些|网传|原视频|里写|里用，必须 0 命中
• [ ] 被引用的每张截图已逐张扫描：终端标题栏/提示符无源品牌（全称/简称/域名前缀）及任何真实品牌字样（发布稿里的图片也会带文字，不能只看正文）
• [ ] 未被引用的旧视频抽帧图（如 shot001~150）已统一挪到 unused_old_shots/ 备份，避免手滑引用发布出去

步骤 7.5：推送后 API 拉回复核（强制，每次推送必做）

推送成功 ≠ 内容干净。必须用 draft/get 把刚推的草稿拉回来，对返回的 content 做机器复核，确认无问题才算交付：

1. 拉回：用 media_id（取自 our_draft_ids.txt 末行）调 draft/get?access_token=TOKEN，POST body {"media_id": MID}，ensure_ascii=False。
2. 禁用词扫描：对 content 全文（含 title）扫源品牌词表（全称|简称|域名前缀|官网地址），必须 0 命中。
3. 来源修饰词 / 视频源词扫描：扫 视频|演示|抽帧|录屏|字幕|部分旧教程|旧教程|有些资料|教程里|资料里|文档里|部分旧|某些|网传|原视频|里写|里用，必须 0 命中。
4. 视频元素扫描：正则 <video[^>]*>|\.mp4|\.avi|\.mov|webm（不区分大小写），必须 0 命中。
5. 图片域名扫描：正则提取所有 <img src>，必须全部包含 mmbiz.qpic.cn；若出现 local-file:/// 或非 mmbiz 域名 → 推送脚本 strip/上传逻辑有 bug，需修复重推。
6. 引用块 / 代码块长度扫描：对拉回的 content 抽所有 <blockquote> 和 <pre> 块，计算去除空白后的字符数。任一 blockquote/pre 块 > 300 字 → 说明 md 里还有长引用块或超长 heredoc 没拆分，必须回改 md 后再重推。
7. 把拉回的 content 存成 xxx_draft_pulled.html 供人工二次核对。

> 复核脚本建议写成独立 .py（如 review_draft.py），复用 draft/get + 正则扫描；避免用 python -c 传中文正则（GBK 解码坑，见常见坑）。

常见坑速查

• 只扫视频前 8 分钟 → 漏掉压轴内容（如 Nginx Playbook），必须全片 OCR
• 截图误入代码块 → 渲染成 ![...] 文本（最常见排版 bug）
• 配图用 HTML 注释 <!-- 配图: ... --> 占位 → VS Code / 公众号草稿箱都看不到图（Docker ① 期踩坑）→ 必须用标准 ![alt](./article_shots_xxx/xxx.png)
• 推送用模糊关键词删草稿 → 误删用户资料（致命）→ 必须用 own media_id 列表
• base64 预览用 f-string 拼 CSS 大括号会被冲掉 → 用字符串拼接 / .format
• 导语/小结写"本期视频/这期/下期" → 读者有期数框架感，与图文本体定位不符 → 统一改用"本文/这次实战/后续"
• 推送时把图片 base64 内嵌进 content → errcode 45002 content size out of limit → 必须改用 uploadimg 上传到 mmbiz.qpic.cn，再用 URL 引用
• 文末练习题答案分布被"脑补" → 答案顺序（如 1-B/2-A/3-D/4-B/5-C）以用户指定为准，不得自行改；填空题须基于本文真实内容（版本号/端口/前缀/参数）
• 重推更新版用 --replace：删除判据必须是「own 列表内 + 精确标题一致」，不要只靠标题匹配（会误删用户同名不同文草稿）；且不要对已经成功推送的版本再跑一次——旧版已删、列表只剩当前版，重跑只会新增重复草稿
• 关键词/话题标签与本文主题不符 → 检查文末关键词段落；同时登录公众号后台核对「话题标签」无其它文章残留（如 Nginx 文不应带 #Ollama #DeepSeek）。后台话题标签无法通过 draft API 修改。
• 公众号摘要超 100 字 → 精简为"钩子+实机截图数量+动手引导"三段，纯中文 ≤100 字
• 视频帧全黑、OCR 引擎（RapidOCR/EasyOCR）在 Python 3.13+numpy 2.5 跑不通 → 若作者直接提供源文件（如 install_nginx_v1/v2/v3.yaml），用源文件全文作为可照抄代码块替代截图，比假截图更准
• 作者字段 author 超长 → errcode 45110 author size out of limit → author 须 ≤16 字节英文（或 8 汉字），如 LinuxPythonWorkshop(18 字符) 会超限，改用 LinuxPy 等缩写
• draft/add 中文乱码 → json.dumps() 默认 ensure_ascii=True 会把标题/正文里的中文全转义成 \uXXXX，微信不自动解码即显示乱码。必须写 json.dumps(data, ensure_ascii=False).encode("utf-8")，所有向微信发 JSON 的请求（draft/add、draft/delete、draft/batchget、素材接口等）都要带 ensure_ascii=False 并以 UTF-8 编码。
• 标题超长 → errcode 45003 title size out of limit：公众号草稿标题是字节上限（实测约 76~80 字节，不是字数也不是"单位"）。实测 76 字节标题能通过、88 字节被拒。常见陷阱：想"模仿"长标题模板（如 【云计算精品课程】跟着敲一遍㉕：Ansible Playbook 一键部署 Nginx（含报错排查） ≈101 字节）必然超限。取舍原则：前缀【云计算精品课程】占 30 字节 + "跟着敲一遍㉙：" 占 21 字节，主题只剩 ~25 字节空间；若用户要保留"三版演进"等核心词，就得砍掉前缀（如 跟着敲一遍㉖：Ansible 三版演进 Nginx（报错） ≈59 字节）。推送前先数 UTF-8 字节，控制在 ≤70 字节留余量。
• --replace 删旧版失效：draft/batchget 必须传 no_content: 0（拉标题），若传 no_content: 1 返回项不含 news_item，标题匹配永远为空、旧稿删不掉变成重复草稿。删旧版逻辑应仅按 OLD_TITLE 精确匹配删除（去掉 mid in own_ids 依赖），否则 own 列表缺失时旧稿删不掉变重复。
• Windows 下 python -c 中文参数被 GBK 解码：在 Git Bash/cmd 用 python -c "..." 传中文（标题匹配、中文 in title 条件）会被按本地代码页 cp936/GBK 解码，而微信返回是 UTF-8，导致匹配永远 False、删除逻辑不执行（表现就是"零删除"实则是没命中）。规避：① 改脚本按 OLD_TITLE 精确匹配删除、不依赖中文参数；② 临时命令一律用 media_id（纯 ASCII）定位删除，绝不靠中文标题字面量。
• 编辑器 local-file:/// 绝对路径协议 → md 经某些编辑器插入的图片写成 ![](local-file:///D:/.../shot01.png)，推送脚本若只认相对路径会全部漏传、微信报 errcode 40007 invalid media_id（封面也空）。规避：推送脚本必须显式 strip 该前缀（local-file:/// → 空）再 os.path.normpath 拼基准目录；推送前先打印"待上传图片数"确认非 0，封面 thumb_media_id 已拿到再 draft/add。
• OCR 时间戳残留 视频 881s / 908s → 写稿时若把"来源时间戳"当笔记留进正文（如 5.1 Keepalived：视频 881s），既含禁用词"视频"、又脱离上下文。内部溯源可用时间戳，不得进正文；交付前扫 视频 必须 0 命中（见文案风格铁律）。
• 标题说教味过重 → 读者无点击/动手欲（27 期：配置与基础实战/实战重点讲透/吃透 cfg 参数 均被否）。改用情绪钩子（痛点共鸣/成果爽感/动手乐趣/制造好奇），保留系列号 ㉙ 与核心文件点名，见「标题打磨」小节。
• 来源修饰词 / 视频源词残留导致发布翻车 → 28 期曾因正文含 手册原视频里/视频演示里/部分旧教程里写的/有些资料里/本文命令均来自真实终端演示 被用户抓出"视频来源"字样，重推才解决。除了品牌替换，推送前必须用脚本跑三套扫描（禁用词 + 来源修饰词 + 视频源词）、逐张扫被引用截图、把未引用旧抽帧图挪到 unused_old_shots/，并且推送后必须用 draft/get 拉回正文复核（见步骤 2.5、步骤 7.5）。任一扫描非 0 命中都不许推送。
• 长引用块 / 超长 heredoc 触发微信"引用字数"警告 → 微信公众号把 <blockquote>（Markdown >）和长 <pre><code> 代码块都计入"引用"，单段超过约 300 字就会弹"引用字数：309/300（单次引用不得超过 300 字，避免不合理引用）"。28 期 Tomcat 节的 💡 下载失败怎么办？ 长提示块和 cat > tomcat.yml <<'EOF' 大段 heredoc 同时触发。规避：推送前用脚本扫 HTML 中所有 blockquote/pre 块长度，>300 字必须拆分成普通段落或短代码块（见步骤 2.6、步骤 7.5）。

反馈与评分

如果本技能帮你节省了时间、解决了问题，欢迎到 SkillHub 为它打分（搜索对应 slug 即可）。你的评分是我持续迭代、补充场景的动力。

```