微信公众号内容工厂
把「写完之后」那些折磨人的手工活自动化：排版、配图、合规、交付。
写作本身交给模型，本 skill 负责让一篇稿子真正能发出去、发得好看、不踩雷。
能力范围
| 层级 | 能力 | 说明 | 依赖 |
|---|---|---|---|
| L0 素材级 | ingest.py 素材摄入 | PDF/docx/pptx/网页/长文 → 可引用的结构化素材 | pypdf、python-docx、python-pptx |
| L1 粘贴级 | md2wx.py Markdown → 内联样式 HTML | 4 套主题，输出可直接粘贴进编辑器 | 纯标准库 |
| L2 成稿级 | cover.py 封面图、lint.py 写作闸门、check.py 合规体检、preview.py 排版确认 | 900×383 / 1080×1080 / 200×200；写作环节可校验 | Pillow、Chrome |
| L3 直发级 | 草稿箱 API 直发 | 未实现，接口契约见 references/api.md | AppID + AppSecret + 认证账号 |
完整创作默认按 L1 + L2 交付；局部任务按请求范围交付，不强制生成整套产物。L3 需要账号已认证并拿到 AppSecret——未认证的订阅号没有开发者接口，拿不到就只能停在 L2（手动粘贴），这一点先跟用户确认，不要假设有。
快速开始
顺序很重要：先出预览、再体检、最后生成工作台。工作台是快照，提前生成会在改稿后变成旧版本。
完整创作按本 skill 的三档封面标准验收。 明确要求发布就绪的排版也需检查封面；
lint --out out --publish将缺失或尺寸不符判为必须修。普通「仅排版」「仅体检」「纯预览」 不强制补齐封面。三档尺寸是本项目交付规格，不代替微信后台当前要求或实际图片检查。
# 0. 有素材文件时，先摄入（PDF/docx/pptx/网页）
python3 scripts/ingest.py 素材.pdf -o out/ingest
# 1. 完整创作按项目规格生成封面：900×383 头条 + 1080×1080 方形 + 200×200 次条
python3 scripts/cover.py --md article.md --all -o out/cover
# 2. 先出预览页（这一步不生成工作台）；输出目录不存在会自动创建
python3 scripts/md2wx.py article.md -o out/article.html
# 3. 排版确认（浏览器不可用时如实说明）
python3 scripts/preview.py out/article.html -o out/preview.png --height 4000
# 4. 双重体检（先跑一轮；发现问题先改稿，改完重来）
python3 scripts/lint.py article.md --cards out/素材卡.md --outline out/大纲.md --strict
python3 scripts/check.py article.md --html out/article.body.html --strict
# 5. 全部通过后，最后生成工作台并打快照（构建指纹写进产物与 build.json）
python3 scripts/md2wx.py article.md --sheet --snapshot -o out/article.html
# 6. 交付前终检：产物必须等于当前源稿，且封面齐全（--publish）
python3 scripts/lint.py article.md --out out --publish --strict
python3 scripts/check.py article.md --html out/article.body.html --strict
所有命令在 skill 根目录下执行。python3 需为 3.9+；cover.py 需要 Pillow。按步骤执行并检查退出码，不忽略失败继续后续步骤；批量执行先启用 set -e。没有素材卡或大纲时省略对应参数，并记录未核验范围；明确传入但解析失败不能当成未提供而放行。完整快照要求本地图片已放在输出目录内；仅排版不强制快照或封面。
写文章前：先把 frontmatter 写好
标题、摘要、作者、主题这些元信息只写一次，放在 Markdown 文件开头，三个脚本共用：
---
title: 我写废了 150 份周报才明白：领导要的不是「你做了什么」
title_short: 周报别再写成流水账了
summary: 周报要经过三层转述，每过一手都在丢信息。如果领导不能从里面抄走一句话，你这周的产出就等于零。
author: 云光迷途
tag: 职场进阶
theme: growth
---
# 正文标题
正文从这里开始……
| 字段 | 必填 | 说明 |
|---|---|---|
title | 是 | 长标题，≤64 字；后台填的就是它 |
title_short | 是 | 短标题，≤20 字；只用来检查信息流显示，后台不填 |
summary | 是 | 摘要，≤120 字 |
author | 否 | 后台作者字段 + 封面署名；不写则默认「云光迷途」 |
tag | 建议 | 封面左上角标签，2~4 字 |
theme | 建议 | tech / growth / minimal / elegant |
cover_title | 否 | 想在封面上另写一句时用；省略则用 title |
写好后，后面的渲染、封面、体检都不需要再传参数。
署名规则：默认「云光迷途」，用户指定就按指定的走。
| 场景 | 怎么做 |
|---|---|
| 用户没说署名 | 什么都不用写，自动用默认「云光迷途」，工作台会标注「来自默认署名」 |
| 用户指定了署名 | 写进 frontmatter 的 author——工作台、封面、后台作者字段都读它 |
| 只想临时试封面文字 | 用 md2wx.py --author / cover.py --author 覆盖，不落盘 |
优先级：--author 命令行 > frontmatter 的 author > 默认「云光迷途」。
不要只给 cover.py --author 而不改 frontmatter——那会让封面署名和工作台里的作者字段不一致。
工作流
先选任务分支，再执行对应步骤。 只有「完整创作」需要顺序走完整链路，局部任务不套用全部创作提问。
| 任务 | 典型请求 | 只需确认 | 执行路线 |
|---|---|---|---|
| 完整创作 | 写一篇文章；把素材改成文章 | 垂类、读者、素材、主题 | Step 0 → 0.5（有素材时）→ 1~7 |
| 仅排版 | 已定稿，只排版；转成公众号 HTML | 定稿源文件、主题或现有 frontmatter；拟发布时才补缺失元信息 | Step 4 → Step 6.2（检查提示，不自行改稿）→ Step 7（局部交付） |
| 仅封面 | 只做公众号封面 | 封面文字、主题/样式、所需尺寸、可选标签与署名 | Step 5 → 人工复核封面文字 → Step 7（局部交付） |
| 仅体检 | 只查合规、排版或引用 | 待检文件；有 HTML、素材卡、大纲时才使用对应参数 | Step 6 的相关检查 → Step 7（只交付报告） |
判断不了分支时（例如「帮我处理一下这篇」「看看这个能不能发」）：先按完整创作走 Step 0，但只问一个最关键的问题，不要一口气抛出四问。宁可多问一句，也不要猜错分支硬走七步。
局部任务只补当前任务必要信息，已有信息直接沿用；不得重写已定稿正文或已有标题，不重新确认读者、选题、大纲，也不强制再给五个标题候选。用户明确要求改稿时，才另行进入对应创作步骤。
- 仅排版不调用
cover.py，除非用户同时要求封面。已有主题优先沿用；没有偏好时用tech并说明，不因此阻塞。 - 仅封面不要求补摘要、正文、素材卡或大纲，也不为了运行整篇检查而伪造文章；按
references/compliance.md只复核实际封面文字，并说明复核范围。 - 仅体检不修改被检文件。只有 Markdown 时不传
--html；只有 HTML 且无 Markdown 源稿时只做 HTML 兼容人工检查并说明范围，不凑假正文。缺素材卡时说明引用与数字无法完整核验。 - Pillow 或浏览器缺失时不自行安装、不冒充该步骤已完成；交付已完成部分并列明缺失项。局部完成不等于整篇可以发布。
Step 0 · 确认输入（仅完整创作）
完整创作先确认四件事，已有答案直接沿用；必要信息缺失时再提问，不自行编造：
- 垂类：技术/产品，还是职场/成长（决定主题与文风）
- 读者：他们是谁、卡在哪、读完能做什么
- 素材：有没有真实案例、数据、代码、截图
- 主题偏好：默认按垂类选（见「主题选择」）
同时判断这次的起点是哪一种，后面走不同的路：
| 起点 | 典型说法 | 走哪条路 |
|---|---|---|
| 给素材 | 「把这个 PDF / 周报 / 网页改成公众号文章」 | Step 0.5 → Step 1 |
| 给话题 | 「写一篇关于 X 的文章」 | 跳过 0.5，直接 Step 1 |
| 两者都有 | 「按这份报告，写一篇讲 Y 的」 | Step 0.5 → Step 1 |
Step 0.5 · 摄入素材（用户给了文件或链接才走这一步）
读 references/ingest.md，按它执行。不要跳过这一步直接开始写——直接读原文会跳读、漏结论、把数字记错。
python3 scripts/ingest.py 素材.pdf 会议纪要.docx -o out/ingest
产出三层文件（清洗正文 / 结构骨架 / 候选可引用句），然后按 ingest.md §2 抽素材卡：
| 前缀 | 类型 |
|---|---|
F | 事实（客观陈述） |
D | 数据（数字 + 单位 + 口径） |
O | 观点（原作者主张，不是事实） |
? | 存疑（矛盾 / 无出处 / 需核实） |
这一步的交付物是素材卡表格 + 缺口清单，先给用户确认，再往下走。
三条红线（ingest.md §3）：不改数字、不改口径、不把推测写成事实。
发现同一指标多个数值时，进 ? 卡去问，不许默默择一。
Step 1 · 话题扩展与大纲
- 用户给了素材：从素材卡反推能写什么角度（
references/topic-expand.md§3） - 用户只给话题：走
topic-expand.md§1–§3，把一句话扩成论点树
再结合 references/writing-playbook.md 的 §1（垂类基线）和 §4（5 套结构模板）选定骨架，
产出带字数配比的大纲给用户确认。
大纲里每个论点必须挂上素材卡编号（[F1] [D2]），挂不上的论点直接删，
不许为了结构完整硬凑（topic-expand.md §4）。
Step 2 · 写标题与摘要
读 references/writing-playbook.md §2 与 §6：
- 出 长标题（≤64 字，用于后台字段）+ 短标题（≤20 字，用于信息流展示）
- 一次给 5 个候选，标注各自用了哪种公式，让用户挑
- 摘要 ≤120 字，给 1~2 个版本
Step 3 · 写正文
按大纲写 Markdown，注意：
- 开头按 §3 的钩子写法，前 3 行就要抓住人
- 每段一件事，单段 ≤5 行（约 260 字）
- 收尾按 §5，用「提问收尾 / 系列预告 / 价值总结」，不要写诱导分享
- 写完用 §7 的 24 条清单过一遍「AI 味」，删掉所有删了不影响理解的过渡词
Step 4 · 排版渲染
沿用 frontmatter 的 theme 或用户明确指定的主题渲染；没有偏好时按垂类选，局部排版默认 tech：
python3 scripts/md2wx.py article.md -o out/article.html
输出父目录会自动创建，产出两个文件：
out/article.html— 预览页（带白底容器，像手机阅读页）→ 用来看out/article.body.html— 纯正文片段 → 备用粘贴方案
本步不生成工作台；最终 out/sheet.html 在 Step 7 生成，避免在封面和定稿完成前保存过早的文件快照。
渲染后用 preview.py 截图，自己先看一眼再交给用户（标题是否换行难看、表格是否过宽、代码块是否被截断）。浏览器不可用时打开 HTML 人工检查并如实说明未截图，不因此要求重写文章。
Step 5 · 生成封面（发布必做）
公众号没有封面就发不出去，这一步在「完整创作」和「要发布的排版」里不是可选项。
python3 scripts/cover.py --md article.md --all -o out/cover
三档一次出：cover.png 900×383（头条 2.35:1）、cover-square.png 1080×1080（方形）、
cover-thumb.png 200×200（次条）。尺寸不对会被平台裁切，lint --publish 会校验。
参数默认从 frontmatter 读（标题、标签、作者、主题），一般不用再传：
--style：gradient（默认，深色底）/minimal（白底，观点文）/band（色带，品牌稿）--all出三档：头条 900×383、方形 1080×1080、次条 200×200- 封面标题默认用
title（长标题钩子更足）；想换文字就在 frontmatter 加cover_title
Step 6 · 双重体检（两个闸门，各管一段）
完整创作执行两个闸门；仅排版、仅体检按入口表选择对应检查，不强制补造缺失材料，也不自行改动原稿。缺少元信息、素材卡或截图时记录限制，局部交付不标为整篇可发布验收。
6.1 写作闸门 —— 查「观点有没有依据、数字从哪来」
python3 scripts/lint.py article.md --cards out/素材卡.md --outline out/大纲.md
这一步是硬闸门，不是在写建议：
| 检查 | 规则 | 不过会怎样 |
|---|---|---|
| 空引用 | 正文 [F1] 必须在素材卡里存在 | 报「必须修」 |
| 存疑卡 | [?N] 不得出现在正文 | 报「必须修」——核实或删 |
| 数字无出处 | 正文每个「数字+单位」必须能在 F/D 卡找到 | 报「必须修」 |
| 论点无支撑 | 大纲每条支撑必须挂 ≥1 个 [F]/[D] | 报「必须修」 |
| 主论点质量 | 不能是短语（「缓存很重要」这类） | 报「必须修」 |
| 观点卡 | [O] 被引用时提示不得当主论据 | 「应确认」 |
| 缺口清单 | 大纲必须有 P0/P1/P2 缺口 | 「提示」 |
没有素材卡时自动降级：只提示「数字无法校验」，并列出所有带单位的数字供人工过目。
产物版本校验：加 --out <产物目录> 后，还会比对交付物里的构建指纹与当前源稿算出的指纹。
python3 scripts/lint.py article.md --out out --publish --strict
--publish 表示按发布就绪范围验收，必须配合 --out 指定产物目录；缺少目录参数会报错。它按本项目三档规格检查文件存在与 PNG 头中的宽高，不完整解码图片，也不验证封面文字、上传或微信后台要求。
| 情况 | 判定 |
|---|---|
| 产物指纹 == 当前源稿指纹 | 通过 |
| 改过稿但没重新渲染 | 「必须修」：预览页/工作台是旧版本 |
build.json 记录的源稿摘要对不上 | 「必须修」：源稿在生成后被改过 |
article.body.html 被替换或手工编辑 | 「必须修」：靠 build.json 的正文摘要旁路校验 |
| 产物没有指纹 | 「应确认」：旧脚本生成或被手工改过 |
缺封面 / 尺寸不对（--publish） | 「必须修」：未达到本项目的发布就绪封面规格 |
这一步是防「改完稿忘了重跑，把上一版发出去」的唯一机械保障，交付前必跑。
6.2 发布体检 —— 查「能不能发」
python3 scripts/check.py article.md --html out/article.body.html --strict
标题长度、摘要长度自动从 frontmatter 取，不用重复传。
硬性通过标准：
| 指标 | 要求 |
|---|---|
| lint「必须修」 | 必须为 0 |
| 高风险项 | 0 个未解决高风险，人工确认误报需留下证据与复核记录 |
| 元信息 | title、title_short、summary 必填且非空；只支持 key: value 单行字段 |
| 标题字数 | 长标题 ≤64，短标题 ≤20；实际发布标题的关键开头信息仍需人工检查 |
| 摘要字数 | ≤120 |
| 外域图片 | 发布前上传或替换为微信可用图片，并在编辑器预览确认 |
| 专业或涉密内容 | 必须人工/法务终审，删关键词、改写或脱敏不能替代审核和授权 |
两个 --strict 都可以进 CI：有「必须修」或高风险时退出码为 1。check.py 会将缺失/超长元信息、不支持的多行字段值、显式指定但不存在的 HTML 作为高风险；未加 --strict 仍报告问题，但退出码为 0。
发布体检逐字段扫描 title、title_short、summary、cover_title、author、tag 与正文；正文代码仍屏蔽，元信息中的反引号不能绕过检查。JSON finding 的 field 标明来源，正文 line 仍相对正文。标题/摘要的命令行覆盖值是最终检查对象。
扫描通过不等于允许发布。高风险按 references/compliance.md §0 记录「待复核 / 确认误报 / 完成修订 / 拒绝发布」；脚本不能读取或代替人工复核记录，确认误报不使 --strict 自动通过。专业、授权与保密问题未解决时暂停，不交付为可发布稿。中低风险保留项、人工确认项及依据一并说明。
素材使用权限或出处不明时先补授权/来源或排除；不改成量级，也不把外部观点改成作者亲历。素材摄入后单独保留 许可与限制.md，记录来源、署名、使用范围、适用边界及授权状态。
Step 7 · 交付
需要 HTML/工作台的任务，交付前统一重新生成最终工作台。 确认定稿、元信息、主题及请求的封面已经完成，再使用同一份源稿与相同主题/输出参数运行：
python3 scripts/md2wx.py article.md --sheet -o out/article.html
这会同步更新预览页、正文片段和 sheet.html，工作台从同目录读取最终 cover.png、cover-square.png、cover-thumb.png。它是静态文件快照，刷新浏览器不会重新生成工作台。若之后又修改正文、元信息、主题或图片，重新生成相关产物并复查对应检查与预览；不得交付旧快照。
构建指纹与回退：
- 指纹包含渲染代码、源稿、合并后的主题、实际标题/署名/主题覆盖及输出选项、本地图片和封面内容；元信息和本地资产变化都会使旧构建失效。
build.json使用 schema 2，声明实际请求的文件，并逐项记录完整 SHA256；检查器按实际渲染参数校验，因此显式-t覆盖主题不应误报。文件丢失、内容替换或结构损坏会阻断。article.body.html保持纯净、不带任何标记；它与预览/工作台分别靠清单摘要校验，不只信任 HTML 中的指纹标签。旧清单无法完整验证时提示重新渲染。- 完整创作在最后一次渲染加
--snapshot，保存源稿、请求的 HTML、本地图片和封面到out/.builds/<指纹>/。同一指纹的快照不可覆盖；缺少本地图片不能冒充完整快照。图片须为输出目录内相对路径，快照不获取远程图片。 md2wx.py --list-builds --out-dir out查看历史；md2wx.py --rollback <指纹> --out-dir out会恢复源稿原路径、产物、本地图片和封面，并清理上一版清单声明而本版不需要的输出。操作前先确认回退意图，因为它会覆盖当前源稿和已声明资产；仅使用可信的本地快照。- 回退先验证全部文件及摘要，损坏或危险路径不会先恢复一半。快照不恢复渲染脚本或全局主题配置；这些变更后仍须重新渲染和复查。stdin 快照的源稿恢复为输出目录的
article.md。 - 仅排版沿用上面的不带
--snapshot命令；完整创作使用：
python3 scripts/md2wx.py article.md --sheet --snapshot -o out/article.html
交付前自检清单（逐条确认，不要用「命令跑过了」代替「文件看过了」）：
- 完整创作运行
lint.py article.md --out out --publish --strict通过——产物就是当前源稿且封面满足项目规格 -
check.py article.md --html out/article.body.html --strict通过——没有高风险项 - 亲眼看过
article.html或preview.png（标题换行、表格宽度、代码块截断） -
sheet.html里的标题/短标题/摘要/作者与要填进后台的一致 - 三档封面存在且头部尺寸正确（
--publish已检查）；另行打开图片确认可解码、文字没被截断 - 正文里的本地图片已列明「需要手动上传」
- 交付说明写清：保留了哪些中低风险项、哪些没做完
逐项检查实际输出文件，封面或截图缺失项要列明，不能以执行过命令代替文件确认；需要完整成稿时缺失项未解决不标为完整交付。源 Markdown 按实际路径一并提供，不要求移动或覆盖用户原稿。
按任务范围自检（自检项跟着请求走，不要一律按完整创作验收）：
- 完整创作：全部清单逐项过
- 仅排版：源稿、HTML、正文片段、工作台可用即可，仅排版不要求三档封面
- 仅封面：只复核封面文字与尺寸，不要求正文与体检
- 仅体检：只交报告，不要求改稿
局部任务只交付请求的产物：仅排版交付源稿、HTML、正文片段和工作台；仅封面交付请求尺寸的图片及文字复核结论；仅体检交付检查报告。不要求补齐封面、素材卡或大纲，不能把局部检查当成完整发布验收。
下列清单仅适用于完整创作，源稿文件的位置以实际路径为准：
out/
├── article.md 定稿 Markdown（源文件，含 frontmatter）
├── article.html 预览页（给人看）
├── article.body.html 纯正文片段（备用）
├── sheet.html 发布工作台（用来发）
├── cover.png 头条封面 900×383
├── cover-square.png 方形 1080×1080
├── cover-thumb.png 次条 200×200
└── preview.png 排版截图
完整创作同时给出：长标题 / 短标题 / 摘要 / 体检结论（保留了哪些中低风险项）。局部任务只列已有元信息、所请求产物、实际检查范围及未完成项，不为了补齐清单另写标题、摘要或正文。
发布到公众号（关键步骤）
打开 out/sheet.html，一个页面搞定所有复制操作：
- ① 标题 → 点「复制」→ 粘进后台标题框
- ③ 摘要 → 点「复制」→ 粘进后台摘要框
- ④ 作者 → 点「复制」→ 粘进作者框
- 正文 → 点右上角「复制正文」→ 粘进编辑区
- 正文图片 → 左侧「正文图片」卡片里逐张处理（见下）
- 封面图 → 上传
cover.png - 照「发布前清单」逐项勾选
为什么图片会丢
微信编辑器的粘贴只接收文字和样式，不会帮你上传本地图片。 正文里的
<img src="fig.png"> 是本地相对路径，粘进编辑器后图片位置是空的——这不是排版没做好，
是宿主环境的限制：图片必须先进入微信服务器（mmbiz.qpic.cn）才能显示。
没有 API 权限时，这一步只能手动。工作台把它压缩成两条路径：
| 方式 | 操作 |
|---|---|
| 复制图片 | 点「复制图片」→ 到编辑器对应位置 Cmd+V，微信会自动上传 |
| 右键复制 | 「复制图片」失败时点「打开原图」→ 右键「复制图片」→ 编辑器粘贴 |
| 兜底 | 右键「图片另存为」→ 编辑器「图片」按钮上传 |
顺序按正文出现次序（第 1 张、第 2 张……），粘贴时对照正文找位置。
不要复制
.md源文：md 是纯文本，切过去只剩一堆#和**，图片和排版都不会有。 必须复制工作台的富文本，或article.body.html的渲染结果。
检查是否漏图：发布前在手机预览里从头划一遍，看每张图是否都在位。
备用方案：浏览器打开 article.body.html → Cmd+A → 复制 → 粘贴。
（不要用 article.html，那是预览页，会带进外层容器。）
主题选择
| 主题 | 适用 | 视觉 |
|---|---|---|
tech 科技蓝 | 技术拆解、产品分析、工程实践 | 蓝色强调、H2 竖条、深色代码块 |
growth 成长橙 | 职场经验、成长复盘、方法论 | 暖橙强调、H2 色块、行距更松 |
minimal 极简黑白 | 观点评论、深度思考 | 黑白、H2 下划线 |
elegant 商务藏青 | 品牌稿、正式发布、行业分析 | 衬线字体、藏青强调、H1 居中 |
原则：内容越硬，主题越素。拿不准就用 tech。
新增主题只需在 scripts/themes/ 加一个 JSON，字段说明见 references/layout-spec.md §13。
命令速查
| 命令 | 作用 | 关键参数 |
|---|---|---|
ingest.py <文件...> | 素材 → 结构化文本 + 候选可引用句 | -o 输出目录、--json |
md2wx.py <md> | Markdown → 公众号 HTML | --sheet 出工作台、--snapshot 打快照、-t 主题、-o 输出、--no-body、--check |
md2wx.py --list-builds | 查看历史构建 | --out-dir |
md2wx.py --rollback <指纹> | 恢复某版产物 | --out-dir |
cover.py | 封面图 | --md 自动读 frontmatter、--style、--all；--title/--tag/--author/--theme 可覆盖 |
lint.py <md> | 写作闸门 + 产物版本校验 | --cards、--outline、--out、--json、--strict |
check.py <md> | 发布前体检 | --html、--json、--strict；--title/--summary 可覆盖 frontmatter |
preview.py <html> | 截图确认排版 | -o、--width、--height |
标题、摘要、作者、主题默认都从 frontmatter 读；命令行参数只用于临时覆盖。
--strict 用于 CI/自动化：存在高风险时退出码为 1。
常见坑（必须知道）
| 坑 | 现象 | 处理 |
|---|---|---|
| 外链不可点 | 正文里的 https://... 点了没反应 | 改成文字描述，或放「阅读原文」 |
| 图片空白 | 外域图片显示为占位/灰块 | 手动在编辑器上传，或走 L3 素材接口 |
| 空行不稳定 | 用空行做段落间距，客户端表现不一致 | 用 margin 做间距，md2wx.py 已处理 |
| 代码折行 | 长代码被自动折行，不能读 | 单块 ≤30 行，超长拆片段 |
| 表格撑爆 | 5 列以上表格横向滚动 | 列数 ≤4，超了就拆成两张 |
| 标题被截断 | 信息流只显示约 20 字 | 必须有短标题版本 |
| 没封面发不出去 | 后台头条封面是必填项，跳过封面等于交不了稿 | 完整创作必跑 cover.py --all，交付前用 lint --out --publish 验 |
| 交付了旧版本 | 改了稿但没重新渲染，发出去是上一版 | 交付前跑 lint --out out --strict，指纹不一致会拦住 |
参考文档（按需加载，不要一次性全读）
| 文档 | 什么时候读 |
|---|---|
references/ingest.md | Step 0.5：素材摄入、抽素材卡、保真规则、口径冲突、缺口清单 |
references/topic-expand.md | Step 1：话题扩展、论点树、防注水纪律 |
references/writing-playbook.md | Step 2~3：标题公式、开头钩子、结构模板、去 AI 味 |
references/compliance.md | Step 6：合规词表、违规类型、替代表述 |
references/layout-spec.md | 需要调排版、加主题、判断视觉问题时 |
references/api.md | 用户要做 L3 自动发布时 |
依赖
| 依赖 | 用于 | 缺失时 |
|---|---|---|
| Python 3.9+ | 全部脚本 | 必须 |
| Pillow | cover.py | 封面图这一步会失败，其余可用 |
| pypdf | ingest.py 解析 PDF | 已 vendored 到 scripts/vendor，无需另装 |
| python-docx | ingest.py 解析 DOCX | 已 vendored 到 scripts/vendor，无需另装 |
| python-pptx | ingest.py 解析 PPTX | 已 vendored 到 scripts/vendor，无需另装 |
| Playwright/Chrome | preview.py 截图 | 截图步骤跳过，改用人工检查 HTML |
调试
如果某个步骤不工作，先检查 exit code：echo $?。非 0 时看错误输出，不要忽略报错继续往下走。
md2wx.py 支持 --check 模式：只校验 frontmatter 字段完整性，不生成 HTML。
python3 scripts/md2wx.py article.md --check
lint.py 和 check.py 都支持 --json，输出结构化结果便于调试。
Pillow 版本问题在 Ubuntu 上常见：
# 如果 cover.py 报 font 相关错误
python3 -c "from PIL import ImageFont; print(ImageFont)"
# 没问题就跳过，报错则检查 Pillow 版本：
pip install "Pillow>=10.0.0"
规则
- 需要用户确认的信息，先问再执行，不自行编造。用户说「按上次的来」或「和之前一样」时要追问到底指的是什么。
- 需要用户选择的选项（如主题、风格），给简短的推荐理由让用户选，不自己做主。
- 用户拒绝回答时记录缺口项范围，按已有信息交付，并说明限制范围。不强制填满全部字段才能交付。
- 每一步出问题（脚本报错、依赖缺失、参数错误）如实告知用户原因和目前能做哪一步，不隐瞒失败继续执行。
- 产出交付物后先自己检查再给用户（例如：预览图看看有没有异常、封面图打没打开、体检报告有没有高风险）。要求用户确认时告知风险或注意点，不「默默交付」
- 只有完整创作要求全套产物（封面、体检、工作台等齐全）；局部任务只交付请求的产物。用户不主动要求全套时不能自行升级为完整创作。
- 本 skill 只管交付准备，不管实际点击公众号后台的「保存为草稿」「群发」按钮。需要直发时走 L3（前提是用户具备条件）。
- 完整创作无法产生全套产物时（如依赖缺失、信息不全），先交付已完成部分，列明未完成项与原因。
- 不逆向工程
scripts/目录下的实现细节，也不需要向用户解释实现原理。按本文档约定的接口和流程操作即可。 ingest.py只在用户明确提供了文件或链接时运行，不主动要求用户找素材。- 用户改稿后，对已改部分相关的素材卡、大纲、缺口清单同样更新，不保留旧版引用。
preview.py截图需要浏览器，不可用时如实告知。cover.py缺 Pillow 时失败；不可在无图片处理能力时假装生成封面。- 用户用非 "article.md" 文件名时，所有脚本对应调整文件路径参数。