wechat-styler

WeChat Styler - 公众号排版工具

将 Markdown 文章转换为优雅的公众号 HTML，支持多主题切换、结构化组件和 SVG 开场动画。

使用方式

# 默认模式（纯净排版，无组件无动画）
/wechat-styler path/to/article.md
/wechat-styler path/to/article.md --theme kami

# 组件模式（Agent 智能改写 + 开场动画 + 8 种结构化表达）
/wechat-styler path/to/article.md --components

# 丰富组件模式（仅在用户明确要求“激进一点 / 多用组件”时启用）
/wechat-styler path/to/article.md --components --component-density rich

# 批量转换
/wechat-styler "articles/*.md" --theme kami

# 输出到指定路径
/wechat-styler path/to/article.md --output path/to/output.html

两种模式：

• 默认模式：直接转换，克制排版，无组件无动画。90% 场景用这个。
• 组件模式（--components）：Agent 分析文章结构，智能改写 Markdown，自动加开场动画。生成前向用户确认。

组件密度由 Agent 改写层控制，不传时保持 standard：

密度	触发方式	结构组件预算
restrained	用户说“克制、少组件、轻排版”	2-4 个
standard	默认	3-6 个
rich	用户说“激进一点、丰富一点、多用组件”	7-12 个；超过 8000 字可到 14 个

普通图片、正文引用和行内高亮不计入结构组件预算。密度只改变组件候选数量，不放宽防重复、卡片短文本和微信兼容规则。

可用主题

主题	命令	风格	适用场景
zhijian（默认）	--theme zhijian	暖纸感 × 顾问可信度	智见AI 品牌内容
kami	--theme kami	纸感编辑排版	深度文章、商业分析
magazine-ink	--theme magazine-ink	墨水经典杂志	通用杂志内页
magazine-indigo	--theme magazine-indigo	靛蓝研究风	技术研究、深度调研
magazine-forest	--theme magazine-forest	森林田野笔记	非虚构、自然叙事
elegant	--theme elegant	优雅复古	商业案例、知识分享
modern	--theme modern	现代简约	科技产品、教程
minimal	--theme minimal	极简主义	哲学思考、个人随笔

主题详情、YAML 参数、扩展指南见 references/theme-guide.md。

工作流程

默认模式

用户只给文件路径和主题，Agent 直接调用 convert.mjs 转换，不做 Markdown 改写。

组件模式（--components）

Agent 不直接调用 convert，先执行 5 步智能改写流程：

写作层前置硬门：先检查段落密度

WeChat Styler 不负责把拥挤长段自动切开。段落边界属于写作语义，渲染器按标点拆段会破坏作者节奏。组件改写前先运行：

npm run qa:density -- /absolute/path/to/article.md --strict

如果失败，停止排版，回到上游 Markdown 按事实、判断、机制、例子、边界和行动的切换点拆段。不要用缩小字号、放大行高或增加组件掩盖正文阅读墙。

第 1 步：分析文章结构

读完整篇 Markdown，识别适合用组件呈现的内容（表格→对比卡片、流程→步骤块、金句→金句块等）。只改写确实适合的内容，并按 component-density 执行预算；未指定时使用 standard 的 3-6 个。详见 references/component-guide.md。

⛔ 防重复硬规则：金句块/提示块/警告块的核心原则是替换原文，不是追加。如果原文已经把同样的意思说清楚了，不要在原文后面追加组件重复一遍。正确做法是删掉原文的概括句，只保留视觉权重更高的组件；或者原文已完整表达时不加组件。生成前必须全文扫描确认无重复。

⛔ 围栏格式硬规则：:::compare / :::flow / :::timeline 必须独占一行，前后留空行。紧跟正文的 :::compare 不会被解析，会以原始 markdown 显示。

第 2 步：提取开场动画参数

从文章内容推断标题（frontmatter.title）、副标题（核心观点一句话）、标签（3个以内关键词），并选择模板（见下）。

第 3 步：向用户确认

组件改写计划:
  • 开场动画(typewriter): 标题「初识 WorkBuddy」/ 副标题「...」/ 标签: ...
  • 「专家对比表」→ 对比卡片
  • 「Ask/Plan/Craft」→ 对比卡片
  • 「用好 WorkBuddy 的核心」→ 金句块
确认后开始生成?

第 4 步：生成前检查（必做）

调用 convert 之前，必须对改写后的 Markdown 逐条检查 references/component-guide.md 的「生成前检查清单」：

• 图片插入位置是否在完整段落之后（不在句子中间）
• 金句块/提示块/警告块是否与原文重复
• :::compare / :::flow 围栏是否独占一行
• 矩阵对比是否被误转成 compare
• 开场动画标题长度是否超出 viewBox
• 结构组件数量是否落在选定密度预算内
• 段落密度硬门是否通过；记录中位数、P90、百字长段占比和最长连续长段

第 5 步：生成

在内存中改写 Markdown（不改原文件），然后调用 convert：

node scripts/convert.mjs /tmp/rewritten.md --theme zhijian --components \
  --strict-density \
  --cover --cover-template typewriter \
  --cover-title "..." --cover-subtitle "..." --cover-tags "..."

--components 启用时自动包含 --cover（开场动画）。

生成 HTML 后，zhijian 主题必须执行移动端视觉检查：

npm run qa:mobile -- /absolute/path/to/article.html \
  --expect-zhijian --strict-image-uniqueness \
  --screenshot /tmp/article-mobile.png

检查项包括 390px 视口横向溢出、坏图、图片 URL 异常重复、引用符号与首行同段对齐、引用是否误用左侧竖线、H2 暖陶色层级。失败时先修排版，再注入公众号。

convert.mjs 默认会打印段落密度软门报告；正式发布候选必须传 --strict-density。该门自动阻止明显的阅读墙；连续超短段只提醒人工检查，不能仅凭数量判失败。渲染器不自动修改正文。

SVG 开场动画

--components 模式自动包含开场动画。SVG SMIL 动画只在首次加载时播放，因此只做开场，其他位置用静态组件。

5 个模板

模板	参数值	气质	适配
墨韵开篇	ink-wash (默认)	仪式感·墨点晕染	方法论、品牌、课程
打字机流	typewriter	极客感·逐字打字·光标跟随	技术教程、工具介绍
画卷展开	scroll-painting	叙事感·双横线·渐入佳境	案例、复盘、故事
聚焦聚光灯	spotlight	判断感·聚光·标题缩放	观点、评测、趋势
极简白描	minimal-sketch	克制·留白·呼吸圆点	随笔、思考、感悟

Agent 模板选择逻辑

• 「教程/工具/技术/CLI/Agent/开发」→ typewriter
• 「案例/复盘/故事/落地/实战记录」→ scroll-painting
• 「判断/观点/趋势/评测/分析」→ spotlight
• 「随笔/思考/感悟/月度/年度」→ minimal-sketch
• 默认/品牌课程/方法论 → ink-wash

Agent 选定模板后，在确认环节明确告知用户："我选了 X 模板，因为文章有 Y 特征，你可以换。" 不确定时默认 ink-wash。

模板设计原则和踩坑清单见 references/svg-animation-design.md。

WeChat エディターへの注入

WeChat エディターの貼り付けフィルターは <animate> タグを除去します。現在、安定している方法は OpenCLI で DOM を直接操作することです。

export OPENCLI_PROFILE="<your-opencli-profile>"
export WX_EDITOR_URL="https://mp.weixin.qq.com/..."
node scripts/inject-to-wechat.mjs article_wechat.html

公開バックエンドの選択ルール： Codex 内蔵の Chrome は、公式アカウント編集ページで DOM の読み書きが許可されている場合に限り、注入バックエンドとして使用できる可能性があります。現在の Chrome Browser セキュリティポリシーでは、mp.weixin.qq.com/cgi-bin/appmsg へのページアクセスが拒否され、CDP による回避も明確に禁止されているため、SVG アニメーションの注入や検証には使用できません。このポリシーによってブロックされた場合は、そのまま OpenCLI を使用してください。CDP、ほかのブラウザー自動化、間接的なスクリプトによる回避に切り替えてはいけません。今後、同じ編集ページで「読み取り専用の調査 → 本文への書き込み → <animate> の読み戻し → 下書きの保存」の4項目を実測できた場合に限り、デフォルトのバックエンドを変更できます。

安定した公開モード：

node scripts/inject-to-wechat.mjs article_wechat.html \
  --reuse-current \
  --title "公众号标题" \
  --summary "转发摘要" \
  --sync-cover-from-body \
  --cover-file /path/to/local-cover.jpg \
  --save-draft \
  --report /tmp/wechat-publish-report.json

--cover-file は、明示的に指定できる推奨のカバー画像オプションです。カバー画像が既にある場合は指定したファイルに置き換え、ない場合は画像ライブラリを自動で開いて、ローカルのカバー画像をアップロードして素材を選択し、「次へ」とトリミングの確認を順に完了します。--sync-cover-from-body のみを使用してファイルを渡さない場合に限り、既存のカバー画像を優先して使用するか、本文から最初の画像を選択します。ローカルのカバー画像は 2.35:1 を推奨します。180KB を超える場合、macOS ではページへの注入に適した JPEG に自動で圧縮されます。

インジェクターは本文編集領域の特定をポーリングし、タイトル用の ProseMirror を避けます。タイトルと概要を同期し、2MB を超えるリモート画像を自動で圧縮し、WeChat による画像の転送完了を待ちます。また、mmbiz.qlogo.cn、mmbiz.qpic.cn、wx.qlogo.cn をすべて WeChat が管理している画像として扱います。保存後は「新しい appmsgid の出現」または「既存の appmsgid と今回の保存通知／履歴の変更」によって下書きを確認し、SVG、アニメーション、画像、本文の先頭と末尾を検証します。history などのページフィールドが欠落している場合は空の配列に正規化し、スクリプトエラーが発生しないようにします。

公開コマンドには必ず --report を付けてください。成功レポートには cover.strategy、画像の状態、保存の証拠が含まれます。どの段階で失敗した場合も、mode: "failed"、phase、機密情報を除去したエラー、読み取り専用の状況、すぐに実行できる復旧手順が書き込まれます。--verify-only --reuse-current を使用すると、既に開いている下書きを読み取り専用で確認できます。

詳しい手順は references/opencli-injection.md を参照してください。

コンポーネント拡張レイヤー

--components モードでは、8種類の構造化表現が有効になります。デフォルトモードでは、コンポーネント構文は通常の Markdown に自然にフォールバックします。

コンポーネント	構文	適用場面
名言ブロック	> **核心观点**	記事の中心的な論点
軽量マーカー	==关键词==	本文内のキーワード強調（下部に細線）
注記ブロック	> [!NOTE] 内容	補足説明、技術的な注記
警告ブロック	> [!WARNING] 内容	注意事項、つまずきやすい点
手順番号	1. [step] 动作	操作手順、アクション一覧
フローカード	:::flow フェンス	段階的なフロー
比較カード	:::compare フェンス	案A vs B vs C
タイムライン	:::timeline フェンス	変遷の経緯、プロジェクトの振り返り

構文の完全な例と設計原則は references/component-guide.md を参照してください。

設計原則： 装飾よりも控えめな表現を優先 · 色はテーマから取得 · 横並びカードは flex:1 による均等割りを優先し、あふれた場合に備えて overflow でフォールバック · マトリックス比較には table を維持 · カードの内容は簡潔に · デフォルトでは表示しない

パラメーターの説明

パラメーター	説明	デフォルト値
--theme	テーマ名	zhijian
--font-size	本文のフォントサイズ（px）	テーマのデフォルト
--line-height	行の高さ	テーマのデフォルト
--accent-color	アクセントカラー	テーマのデフォルト
--background-color	背景色（solid hex）	テーマのデフォルト
--max-width	コンテンツの最大幅（px）	640
--output	出力ファイルのパス	<input>_wechat.html
--components	コンポーネントモードを有効化（インテリジェントな書き換え＋アニメーション＋コンポーネント）	false
--component-density	Agent の書き換えレイヤーにおけるコンポーネント密度：restrained / standard / rich。convert.mjs には渡されません	standard
--strict-density	段落密度の検査に失敗した場合、生成を停止します。正式公開の候補では必須です	false
--cover	オープニングアニメーションを生成（--components に自動で含まれます）	false
--cover-template	オープニングアニメーションのテンプレート	ink-wash
--cover-title	オープニングアニメーションのメインタイトル	frontmatter.title から取得
--cover-subtitle	オープニングアニメーションのサブタイトル	frontmatter.summary から取得
--cover-tags	オープニングアニメーションのタグ（カンマ区切り）	なし

フォントサイズの推奨

zhijian の現在のビジュアル基準は editorial-weighted-2026-07 です。H2/H3 では仓耳今楷を優先するフォントスタックを使用し、本文では思源宋体 VF 15px / 450 / 1.68、キャプションとメタ情報では思源黑体 13px を使用します。大鹏は、15px のほうがスマートフォンで読みやすいことを確認しています。ウェイト 450 により、紙面で読むときの安定感が戻ります。フォントサイズは表示サイズのみを調整するもので、コンテンツレイヤーでの段落修正の代わりにはなりません。推奨設定：

• 公式アカウントの長文／情報密度の高い記事：デフォルトの 15px を維持し、まず段落密度のハードゲートを通します
• 物語調の記事、年配の読者向け、またはゆったりとした見た目にしたい場合：17px を使用できます
• 16px ゆったりモード：読者の年齢層が高い場合や、本文に専門用語が多い場合は明示的に使用できます
• ミニマルテーマ minimal：デフォルトでやや小さいため、通常は調整不要です

プレースホルダーの仕組み

画像ホスティングの準備ができていない状態で執筆していますか？Markdown にプレースホルダーを記述すると、convert によって中央揃えの破線のグレー枠としてレンダリングされます。

【插入:文章开头的视频截图】

独立した行に記述する 【插入:xxx】（全角の角括弧）のみをサポートします。

出力ルール

• 入力：path/to/article.md → 出力：path/to/article_wechat.html
• 完全な HTML で、スタイルはインラインです。公式アカウントのエディターにそのままコピーできます
• convert の実行後、validate.mjs によるソフトゲート検証が自動で実行されます（処理はブロックされず、レポートが出力されます）

互換性のハードルールの詳細は references/wechat-compatibility.md を参照してください。

参考資料

ファイル	内容
references/theme-guide.md	8テーマの完全な設定、Renderer Presets、拡張ガイド、技術的な実装
references/component-guide.md	8種類の構造化表現の構文例、設計原則、インテリジェントな書き換えルール
references/svg-animation-design.md	5種類のテンプレートの設計原則、技術的制約、11項目のつまずきやすい点
references/wechat-compatibility.md	公式アカウントの互換性に関するハードルール（ERROR/WARN の詳細）
references/opencli-injection.md	OpenCLI の注入手順、ブラウザーの機能範囲、前提条件、障害復旧
references/zhijian-theme-baseline.md	Zhijian テーマのバージョン比較、スタイルロック、モバイル向けビジュアル基準

---

バージョン： 1.9.0 · 作者： 大鹏