「公号编辑器·熊少」用户使用手册

1 安装与启用面向零基础 · 3 分钟跑通

本章解决「把扩展装到 Chrome 并出现在公众号编辑页右侧抽屉里」的问题。适合刚下载安装包、或第一次接触 Chrome 扩展的用户。整体过程约 3 分钟。

1.1 系统要求

• Chrome / Edge / Brave 等 Chromium 内核浏览器，版本 ≥ 116（依赖 chrome.sidePanel 原生 API，老版本不可用）；
• 已注册的 微信公众号（订阅号 / 服务号 / 个人号均可），并已登录 mp.weixin.qq.com；
• 至少 1 个大模型 API Key（推荐先开 DeepSeek 作为主线，详见 第 4 章）；
• （可选）腾讯云 COS 4 项凭据 —— 用于图片自动上传、二维码、AI 排版后自动外链化，详见 第 5 章。

1.2 从 Chrome 应用商店安装（推荐）

[截图占位] Chrome 应用商店「公号编辑器·熊少」详情页 + 「添加至 Chrome」按钮

1.3 从源码 / dist 包加载（开发者 / 离线分发）

未上架商店，或 Comdr 给你发了一个 .zip 离线包，用这种方式。

1. 下载并解压 extension-vXXX.zip，里面有一个 dist/ 目录；
2. 地址栏输入 chrome://extensions 进入扩展管理页；
3. 右上角打开「开发者模式」开关；
4. 左上角点「加载已解压的扩展程序」，选中刚解压的 dist/ 文件夹；
5. 扩展列表里应出现 公号编辑器·熊少，确保「已启用」拨片是绿色。

[截图占位] chrome://extensions 开发者模式 + 加载已解压扩展程序

1.4 打开侧边栏（Sidebar）

本扩展通过 Chrome 原生 sidePanel 在公众号编辑页右侧展开一个 350px 的工作区。共 3 种打开方式：

1. 方式 A · 扩展图标：登录 mp.weixin.qq.com 进入「图文消息」编辑页（URL 含 /cgi-bin/appmsg?action=edit），点工具栏的 扩展图标，Chrome 会原生唤起 sidePanel。再点一次会关闭。
2. 方式 B · 浮按钮：编辑页左下角注入了一个 🌿 浮按钮（v23-r3 增加 sidePanel toggle 切换能力），点它也会开关 sidePanel。
3. 方式 C · 选项页入口：选项页右上角点「打开抽屉」（实验入口，需当前已有 mp 编辑页打开）。

1.5 验证是否启用成功

• 工具栏 扩展图标变彩色（灰色 = 不在公众号编辑页白名单上）；
• 编辑页右侧出现 350px 抽屉，顶部标题「🌿 公号编辑器·熊少 智能排版助手」；
• 抽屉顶部右上角「？」点击有使用提示弹窗；
• chrome://extensions → 公号编辑器·熊少 → 详情页 Service Worker 状态显示「活动」。

2 5 分钟快速上手3 步排版你的第一篇

本章解决「从一段粗稿，到公众号编辑器里出现一篇排版好的文章」的最短路径。适合已完成第 1 章安装并配好 DeepSeek Key 的新用户。

整个流程只有 3 步，全程 ≤ 5 分钟。每步都对应抽屉里一个明显的按钮。

3 侧边栏布局速览v23-r22/r23 全局 UI 精修后

本章解决「侧边栏每一块到底是干什么的」。适合刚装上、但抽屉里按钮太多看不过来的用户。建议对照下面的「抽屉地图」逐块认一遍。

3.1 抽屉 7 大功能区（从上到下）

1. Header（顶栏）：左 logo + 「🌿 公号编辑器·熊少」标题，右「？」帮助 + 「⚙」设置入口；
2. Tab 切换：「✏️ Compose」（撰写）与「🎨 模板库」两个主 Tab；
3. 抽屉输入框（Compose Tab）：大文本域，粘贴 / 输入原稿；
4. 实时预览区：自动渲染下方 AI 排版结果，配 iPhone 16 Pro 真机预览（详见 第 14 章）；
5. 处理范围 + 同步开关：3 选项 segmented「抽屉输入 / 全文 / 选区」+ 「同步原编辑器」toggle（详见 第 10 章）；
6. 应用行：「📤 应用到正文」/「📌 插入到光标」/「📋 复制并切 mp 粘贴」3 按钮；
7. 更多配置抽屉：底部「⚙ 更多」展开「高级布局」/「启用滚动条」/「AI 排版后自动 COS 上传」3 个 toggle + 「AI 风格」/「AI 模型」下拉。

[截图占位] 抽屉 7 大功能区编号示意图

3.2 5 个 AI 操作按钮

Compose Tab 顶部一行 5 个按钮，对应 5 个 AI 任务（详见 第 7 章）：

3.3 AI 风格抽屉（v23-r19/r21 改造）

顶部「风格」下拉点开 → 弹出 右侧全屏 320px 抽屉（React Portal 渲染到 document.body，v23-r21 修复了之前「只显示一半」的真根因），列出 20 套预设 + 你自定义的风格。每张卡片：

• 左 迷你色块预览（demoSnippet）：每套独一无二的小段排版示例（v23-r25/r26 升级，含 25 张 Unsplash 真图，杂志级排版）；
• 右上 名称 + 品类标签；
• 右下「📱 预览」按钮 → 弹 iPhone 16 Pro 真机预览（详见 第 14 章）。

3.4 模板库 Tab

顶部 Tab 切到「🎨 模板库」→ 顶部搜索框 + 分类 chip（默认 / 内容 / 行业 / 兴趣 / 风格 / 极简 / 业界）+ 36 套模板卡片网格。每张卡片：

• 缩略色块（primary / accent / bg 三色）；
• 模板名 + 一句话描述；
• 「📱 预览」（iPhone 真机） + 「🎨 套用」两按钮。

3.5 状态指示

• AI 流式进度条：顶部 2px 绿色条，从左到右匀速增长，到 100% 渐隐；
• 中央 loading 浮罩：「✨ AI 正在排版…」+ token 计数 + 已用时；
• 底部 toast：成功 ✅ / 失败 ❌ / 信息 ℹ︎，3 秒自动消失。

[截图占位] 顶部进度条 + 中央 loading + 底部 toast 三种状态示意

4 BYOK API Key 配置7 厂商 · 零服务器 · AES-GCM-256

本章解决「把你自己在大模型厂商账户下生成的 API Key 填到扩展里」的问题。适合所有用户 —— BYOK 是本扩展的核心定位，必须先做这一步才能用 AI 排版。

入口：浏览器工具栏 扩展图标右键 → 「选项」；或 chrome://extensions → 公号编辑器·熊少 → 「扩展程序选项」。

必填：DeepSeek（主线，所有 AI 功能默认走它）。选填：Anthropic / OpenAI / Qwen / GLM / Kimi / 自定义 OpenAI 兼容。

[截图占位] 选项页 BYOK 7 厂商卡片整体

4.1 DeepSeek（主线必填）

4.2 OpenAI GPT（选填）

4.3 Anthropic Claude（选填）

4.4 Qwen 通义千问（选填）

4.5 GLM 智谱（选填）

4.6 Kimi（Moonshot，选填）

4.7 自定义 OpenAI 兼容（选填）

4.8 通用：保存 / 测试 / 拉取 model / 清除

• 保存：填完一个或多个 Key，点页面底部「💾 保存全部」。AES-GCM-256 加密后写入 chrome.storage.local。
• 测试连接：每个卡片右侧「⚡ 测试连接」单独发 5-token 探测请求（不消耗有效配额）。绿点 = OK、灰点 = 未配置、红点 = 失败。
• 拉取可用 models：填好 Key 后点「📋 拉取可用 models」，自动调用厂商 /v1/models 接口列出你账户能用的全部 model，下拉选择即可。v21-A 起 Custom 也支持。
• 清除：每个卡片右侧「🗑 清除」按钮单独删除该厂商 Key（其它厂商不受影响）。

4.9 当前 AI 厂商切换

抽屉「⚙ 更多」展开 → 「AI 模型」下拉，可在已配置的厂商间切换。建议保留多个 Key 作为「主备」—— 主厂商 429 限速时一键切换。

5 腾讯云 COS 配置图片自动上传 · 二维码 · 防盗链解决方案

本章解决「把扩展里的图片（粘贴、AI 生成、二维码）上传到你自己的腾讯云 COS 公网 Bucket」的问题。适合需要外链图床 / 担心 mp 素材库挂掉 / 跨账号共享图床的用户。

本章是可选配置。不配 COS 也能用智能排版、AI 风格、模板套版等所有核心功能；不配 = 签名档图片字段被禁用 + 「AI 排版后自动 COS 上传」（v23-r27）开关无效。

5.1 4 项必填凭据

5.2 创建 COS Bucket 步骤

[截图占位] 选项页 COS 4 项配置卡片 + 测试连接成功状态

5.3 「优先用 COS 上传图片」开关

选项页 COS 卡片下方 toggle，默认开。粘贴 base64 图时优先走 COS（速度更快、Bucket 可控），关闭则只走 mp 素材库通道。

5.4 应用场景（3 类）

1. 粘贴单张图自动上传：用户在 mp 编辑器 / 抽屉输入 粘贴含 data:image/...;base64, 的内容，扩展 content script 检测到 → 调用 SW 上传 COS → 返回 https://xxx.myqcloud.com/yyy.png URL 替换 src；
2. AI 排版后批量上传（v23-r27）：详见 第 13 章。需要先在抽屉「⚙ 更多」开启「AI 排版后自动 COS 上传」toggle，AI 输出含的所有外链图（mmbiz / 第三方）会被批量重传到你的 COS Bucket，防御对方域名挂掉 / 防盗链；
3. 二维码 / Logo 上传：签名档配置必经路径，详见 第 6 章。

5.5 防盗链原理（v23-r30 真根因）

mp 域名 mmbiz.qpic.cn 服务端检查 Referer header —— 浏览器跨域请求 default Referer 是当前页（非 mp 域）→ 403。v23-r30 修复方案：

• 所有 mmbiz 图 fetch 改走 SW → SW 的 declarativeNetRequest 规则把 Referer 改为 https://mp.weixin.qq.com/ → 服务端通过；
• SW 拿到 blob → 重新上传 COS → 返回 COS URL；
• v23-r16 同步修复长图导出场景下的 mmbiz CORS（fetch 改 content-script 同源） → 详见 第 15 章。

6 签名档与图文素材作者名 · 二维码 · Logo · CTA

本章解决「每篇文章末尾固定追加作者署名 / 公众号二维码 / Logo / CTA 横幅」的问题。适合个人 IP 号 / 公众号矩阵 / 需要固定引流话术的运营者。

签名档全部默认空，不填 = 不显示任何内容（不会有意外的 PandaAI 字样）。需要主动到选项页填写才生效。

6.1 6 个字段

6.2 配置入口

选项页 → 「签名档」分组 → 填 4 个文本字段 + 上传 2 张图片 → 「💾 保存」。

• 文本走 chrome.storage.sync —— 跨设备自动同步（你在 PC 设置，公司另一台 Chrome 登同账号也同步）；
• 图片先上传到腾讯云 COS（需先配 COS，见 第 5 章），存的是 https://...myqcloud.com/xxx.png 公网 URL。

6.3 二维码 / Logo 上传步骤

[截图占位] 签名档配置区 + 二维码上传后的预览态

6.4 签名档何时渲染

• 智能排版 / 重写：末尾自动追加（如果 6 字段全空则跳过整段，不输出任何 PandaAI 硬编码）；
• 套版：根据模板设计追加（v23-r2 #7 修复了套版后图片占满宽度的 bug —— 现在 HTML 属性 + inline style 双保险）；
• 不想某次追加：临时清空 signature 文本即可；或在「📱 预览」编辑区手动删除尾部 <footer class="pa-sig-footer">...</footer>。

6.5 图片占位规范

• 二维码：120×120 px，PNG 透明背景最佳，圆角 8px 自动应用；
• Logo / 头像：48×48 px，自动裁圆，建议 1:1 正方形原图；
• 文件大小：≤ 5MB（COS 单次上传限制）。

7 智能排版 / 重写 / 扩写 / 精简 / 标题5 个 AI 任务 · 商用专业级 prompt · AI 续写

本章解决「每个 AI 按钮到底干什么、什么时候用」。适合所有用户。这 5 个按钮在 Compose Tab 顶部一字排开，是本扩展的核心生产力。

7.1 5 个任务总览

7.2 ✨ 智能排版（smart）

核心任务。AI 接收你的粗稿 + 当前 AI 风格 + 处理范围 → 输出带语义结构 + 内联样式的 HTML。

• 语义结构：自动判断段落是 h1（标题）/ h2（小节标题）/ p（正文）/ blockquote（引用）/ figure+img（图文混排，需开高级布局）；
• 内联样式：按 AI 风格的 primary / accent / 字号 / 行距注入 style="..."，确保 mp 编辑器不会剥离样式；
• 不重复内容：v23-r17 商用 prompt 起，AI 严格保留原始措辞，只调结构 + 排版，不改变事实信息。

建议：原稿 200-2000 字效果最稳。< 200 字 AI 容易"自由发挥"，建议改用「扩写」；> 2000 字会触发 AI 续写机制（见 7.7）。

7.3 🔄 重写（rewrite）

同语义、不同表达。适用场景：

• 觉得原稿不够好，想看 AI 帮你换种说法；
• 智能排版后，对其中某段表达不满意 → 把那段粘到抽屉输入 → 点重写；
• 同一份原稿，重写多次取最优。

7.4 📖 扩写（expand）

50-200 字 → 200-500 字。AI 会补充：

• 具体例子（行业数据 / 知名公司案例 / 历史事件）；
• 因果链（为什么 / 如何 / 影响）；
• 佐证引用（引用专家观点 / 权威研究）。

7.5 ✂️ 精简（compress）

长稿 → 摘要。压缩到约 50% 长度，保留核心信息 + 关键数字 + 主要结论。适合：

• 把别人的长文压成「精读笔记」转载；
• 把自己的初稿砍掉冗余；
• 为「微信视频号 / 朋友圈」配文。

7.6 🏷 起标题（title）

AI 读取你的正文 → 生成 5 个候选标题，每个：

• 8-15 字（公众号头条最优字数）；
• 带评分（吸引力 0-10）；
• 带风格标签（如「悬念」/「数字」/「反问」/「金句」/「Listicle」）；
• 点任一即复制到剪贴板，可粘到公众号顶部标题栏。

7.7 AI 续写机制（v23-r17）

大模型每次输出有 token 上限（典型 4096-8192 token）。原始稿太长时，AI 会被截断 → 输出末尾出现「未完成」状态。v23-r17 起每个任务自动检测：

1. 每轮 streaming end 时检查 finish_reason；
2. 若 === 'length'（被 token 限制截断）→ 自动发起续写请求，prompt 包含「截断前最后 N token + 继续写」；
3. 最多续写 5 次（防御无限循环 / 烧 token）；
4. 用户无感 —— 抽屉里看到的是连贯的完整文章，但底部 token 计数会持续增长。

7.8 商用专业级 prompt（v23-r17）

每个任务的 promptHint 从「单句概括」升级为「5 项结构化指令」：

1. 写作节奏：短句 / 长句 / 停顿设计；
2. 词汇风格：具体名词 / 行业术语 / 口语 / 中英混排；
3. 段落结构：观点-论据-小结 / 故事场景 / 步骤编号；
4. 标点偏好：句号多 / 感叹号少 / 引号 / 破折号；
5. 禁忌：流行语 / AI 套话 / 行业话术。

业界依据：结构化 prompt 错误率降 76%（promptbuilder.cc/blog/2026）。

8 AI 排版风格 · 20 套预设v23-r18 起 8→16→20 · v23-r25/r26 demoSnippet

本章解决「到底选哪个 AI 风格才符合我的公众号品类」。适合所有用户。建议先把 20 套都点开「📱 预览」看一遍 iPhone 真机效果，找到 2-3 个常用的钉住。

8.1 20 套完整列表

8.2 demoSnippet · 每套独一无二的迷你预览（v23-r25/r26）

v23-r19 起 AI 风格做成右侧抽屉化，v23-r25 起每张卡片左侧加 demoSnippet 迷你预览：

• 每套都有专属的小段排版示例（标题 + 一行正文 + 一个引用 / 列表 / 图文混排）；
• v23-r26 升级为杂志级排版：含 25 张 Unsplash 真图，验证图文混排能力；
• 点卡片右下「📱 预览」→ 弹 iPhone 16 Pro 真机预览（详见 第 14 章）。

[截图占位] AI 风格抽屉 + 20 套 demoSnippet 列表

8.3 选择建议（按品类）

8.4 自定义风格

AI 风格抽屉底部「➕ 新建自定义」→ 弹 7 字段表单：

• 名称：你的风格名，如「我的品牌风」；
• 主色 / 副色：颜色选择器；
• 字号：14 / 15 / 16 / 17 / 18 px；
• 行距：1.6 / 1.75 / 1.85 / 2.0；
• 字间距：0 / 0.05em / 0.1em；
• promptHint：5 项结构化指令（参考 7.8）。

编辑后存 chrome.storage.local，仅本机生效（不跨设备同步）。可在抽屉里「✏️ 编辑」/「🗑 删除」。

8.5 公众号阅读体验铁律：白底优先（v23-r18）

v23-r18 起，除 midnight 外 19 套全部统一 #FFFFFF 白底。原因（Comdr 真机反馈）：

• 公众号读者期待是白底（默认主题）；
• 之前 life=#FAF3E0 黄米底用户看到「黄米底 + 薄荷绿边」，名实不符；
• 色调通过 primary / accent 表达即可，背景不需要带色。

仅 midnight 例外（明确标注「个性深色」#0F172A），仅限特殊场景（科技夜读 / Web3）。

9 模板套版 · 36 套美工级v23-r18 精修 · 4 doocs + 32 native

本章解决「整篇文章从骨架到装饰全部由模板决定，AI 只填正文」的场景。适合需要强视觉冲击 / 品牌一致性 / 节日营销 / 报告类的运营者。

v23 #12 联网调研 3 源交叉验证后，模板库从 22 套扩到 34 套；v23-r18 进一步精修补完 + 加入 2 套 v21 二次补充，目前共 36 套（4 doocs + 32 native）。

9.1 入口与界面

抽屉顶部 Tab 切到「🎨 模板库」→ 顶部搜索框 + 分类 chip + 36 套卡片网格。每张卡片：

• 缩略色块：primary / accent / bg 三色预览；
• 模板名 + 一句话描述；
• 📱 预览：弹 iPhone 16 Pro 真机预览（详见 第 14 章）；
• 🎨 套用：把当前抽屉输入 / mp 正文 / 选区按模板填入。

[截图占位] 模板库 Tab 36 套卡片网格

9.2 doocs 系（4 套，WTFPL 开源）

基于 doocs/md 上游 commit c32fbd68，WTFPL 授权开源。

9.3 Native v20 原版（8 套）

9.4 Native v21 扩充（12 套）

9.5 Native v23 新增（12 套，联网调研 3 源交叉验证）

v23 #12 调研依据：docs/research/v23-templates-expansion-2026-05-19.md。

9.6 套用步骤

9.7 自定义主色

选中任一模板后，预览区上方有主色色板：可临时改 primary 色（不修改模板源），改完即时刷新预览。常用场景：「我喜欢这套模板的骨架，但要把蓝改成我品牌的紫」。

10 处理范围与同步开关v23-r29 互斥逻辑反转重写

本章解决「我点 ✨ 智能排版，AI 到底拿哪段文字作为输入」的根本问题。适合所有用户 —— 错选会导致 AI 排错对象。

10.1 3 个处理范围（segmented）

10.2 「同步原编辑器」开关

处理范围下方独立 toggle。打开后：

• 抽屉输入框双向同步到 mp 编辑器 —— 你在抽屉里粘东西，mp 里也立刻出现；
• 反之，你在 mp 里改，抽屉也会刷新；
• 典型场景：希望抽屉作为"草稿区"，但同时也想在 mp 里看到正稿。

10.3 三者互斥逻辑（v23-r29 重写）

v23-r27/r28 之间有一轮「互斥灰化」的反复迭代，最终 v23-r29 修正为下表逻辑：

具体表现：「抽屉输入框」会出现灰化 + 顶部小字「当前由 mp 编辑器同步，禁止粘贴」。

10.4 何时用哪个？

• 从外部粘原稿（飞书 / Notion / 微信公众号草稿箱）→ 选「抽屉输入」+ 同步关；
• 已在 mp 编辑器里草草打了一稿，希望 AI 整篇重排 → 选「全文」+ 同步关；
• 整篇已基本满意，只想润色其中某段 → 选「选区」+ 同步关 + 在 mp 里高亮那段；
• 边粘边看 mp 实时同步（< 50KB 短文）→ 抽屉输入 + 同步开。

10.5 选区识别细节

mp 编辑器是 iframe ProseMirror，选区通过跨上下文消息桥读取：

1. 用户在 mp iframe 内 mousedown + drag 选中文字；
2. content script 监听 selection change，把 Selection.toString() + 选区 ProseMirror node 范围发回扩展；
3. 抽屉「处理范围」选「选区」时，AI 拿到的就是这段文本（不含周围段落）。

11 应用到正文 / 插入到光标 / 复制并切 mp 粘贴

AI 排版完成后，3 种方式把内容写回 mp 编辑器。默认走 JSAPI 直写，遇高级布局或失败时自动降级。

11.1 应用到正文（默认主路径）

抽屉底部主按钮「📤 应用到正文」一键写入 mp 编辑器全文。

• 调用 mp 原生 __MP_Editor_JSAPI__.invoke('mp_editor_set_content', html) 接口；
• 保留所有 inline style（颜色 / 字号 / 字体 / 行距）；
• 同 doocs/md 主流公众号工具走同一接口，兼容性最佳；
• 成功 toast「✅ 已写入编辑器」，失败自动降级到剪贴板路径并提示。

![待补充] 截图：「应用到正文」点击后 toast 提示

11.2 插入到光标（局部追加）

抽屉底部副按钮「📍 插入到光标」在 mp 编辑器当前光标位置插入排版后内容，不替换其他段落。

11.3 复制并切 mp 粘贴（剪贴板路径）

启用「高级布局」（第 12 章）后，主按钮文字变为「📋 复制并切 mp 粘贴（高级布局）」。

11.4 失败降级链路

1. JSAPI 写入失败（mp 编辑器未就绪 / JSAPI 未注入）→ 自动 fallback 到剪贴板；
2. 剪贴板也失败（浏览器拒绝权限）→ toast 提示「请手动复制下方框内文本」+ 展示纯文本框；
3. 用户可重新触发主按钮，扩展会重试整条链路。

12 高级布局（图文混排 / 滚动容器）

「更多配置」区下的可选开关。开启后 AI 排版会自动生成 figure 图文卡 / 左图右文 / 长引文滚动容器，写回 mp 走剪贴板路径完整保留高级样式。

12.1 启用条件

• 抽屉「更多配置」展开 → 勾选「启用高级布局」（v23-r27 起 默认勾选）；
• 主按钮文案自动变成「📋 复制并切 mp 粘贴（高级布局）」；
• 持久化到 chrome.storage.local，下次打开 sidebar 保留偏好。

12.2 自动生成的高级元素

• figure 图文卡：img + figcaption，标题灰色小字居中，自动 16px padding；
• 左图右文 / 右图左文：display:flex; gap:16px，移动端 ≤ 480px 自动垂直堆叠；
• 横向滚动卡片：长 ≥ 120 字的 blockquote 自动加 overflow-x:auto（公众号 H5 阅读特色）；
• 抽屉内并排图：pa-image-row 容器，单行 2-3 张图等宽分布。

![待补充] 截图：高级布局开启前后 AI 输出对比

12.3 与「应用到正文」的对比

13 AI 排版后自动 COS 上传图片（v23-r27）

AI 排版完成后，自动把外链图（mmbiz 防盗链图 / Unsplash 配图 / 用户原图）上传到你的腾讯云 COS，替换 src 为 COS URL。解决 mmbiz 防盗链失效 + 长图导出图片丢失 + 长期 CDN 稳定三大问题。

13.1 工作流

AI 排版完成
    ↓
扫 HTML 中所有 <img> 标签
    ↓ 跳过 data: / blob: / chrome-extension: / 已经是 myqcloud.com
SW fetch (Referer: https://mp.weixin.qq.com/, credentials: omit)
    ↓ 绕过 mmbiz / 各平台防盗链
blob → uploadToCos(SecretId + SecretKey + Bucket + Region)
    ↓ 拿到 https COS URL
img.setAttribute('src', cosUrl)  ← 替换
    ↓
最终 HTML 写入 mp 编辑器

13.2 启用条件

1. 已配置腾讯云 COS（第 5 章 4 项凭据）；
2. 抽屉「更多配置」→ 「✓ AI 排版后自动上传图片到 COS」勾选（默认勾选）；
3. 未配置 COS 时 checkbox 自动 disabled + 灰底 + tooltip 引导到选项页。

![待补充] 截图：未配置 COS 时 checkbox 灰化

13.3 进度反馈

AI 排版完成后，扫到外链图时 sidebar 显示「上传中 done/total」实时进度条。完成后底部 toast 提示「图片已自动上传到 COS：N 张成功 / M 张跳过 / X 张失败」。

13.4 跳过规则

• data:image/...;base64,...（已是同源）；
• blob: / chrome-extension:// / file://（本地资源）；
• https://*.myqcloud.com/...（已是 COS URL，避免循环）；
• 大小超过 20 MB 的远程图（避免长尾卡顿）。

13.5 失败回退

单张图失败（防盗链 403 / 超时 15s / SW fetch BLOCKED_BY_CHROME / COS SecretId 错误）不影响整体：

• 该 img 保留原 src 不动；
• errors 计数 +1，errorMessages 保留前 20 条；
• 其他图继续上传，整体 HTML 仍写入 mp 编辑器。

13.6 何时关闭

• 没配 COS：自动 disabled，不用管；
• 测试小稿：想跑得快可临时关闭，AI 排版后图片仍是 mmbiz / Unsplash 外链（预览能看，长图导出靠 v23-r2 SW fetch base64 兜底）；
• COS 流量敏感：临时关掉，仅在最终发布前打开做一次上传。

14 iPhone 16 Pro 真机预览（v23-r20+r24）

所见即所发：在排版风格 / 模板卡上点「📱 预览」→ 弹出 iPhone 16 Pro 玫瑰金真机模拟器，渲染该风格的杂志级 demo 内容，让你在应用前看到「公众号读者实际看到的样子」。

14.1 视觉设计

• iPhone 16 Pro 玫瑰金边框：155deg 三段渐变 #F4D6D7 → #E8B4B8 → #C9A0A0，4 层 box-shadow（外环高光 + 内陷玫瑰高光 + 内陷暖阴影 + 桌面双层投影）；
• 尺寸：280×606 屏 + 12px 边框 padding（19.5:9 比例，与真机一致）；
• Dynamic Island：96×27 居中顶部 17px，纯黑（屏幕一部分）；
• Home Indicator：底部 16px 处 108×4 横条，rgba(0,0,0,0.65) 与玫瑰金底协调；
• 屏幕：白底 + 32px 圆角，iframe srcdoc 隔离渲染。

![待补充] 截图：iPhone 16 Pro 玫瑰金预览

14.2 字号阶梯（公众号 iOS 阅读规范）

iframe 内 :where() 选择器把所有未指定字号的元素降到 0 specificity 基线，模板/AI 风格 inline style 仍能覆盖：

• h1 22px / h2 19px / h3 17px / p 16px / blockquote 14px / small 12px；
• zoom: 0.72 等比缩内容（模拟 iPhone 真机视觉密度）；
• line-height 1.7（web.dev《Mobile readability》base ≥ 16 + lh 1.5-1.75 黄金区间）；
• letter-spacing 标题 -0.018em（紧凑），正文 0（默认）。

14.3 两种触发方式

从模板抽屉

模板卡 hover 出现「📱 预览」按钮 → iPhone modal 渲染该模板的 mock 文本（含 H1 + 段 + figure + blockquote + 列表）。

从 AI 风格抽屉

AI 风格卡的 📱 按钮 → iPhone modal 渲染该风格的 定制 demoSnippet（v23-r25/r26，每套独一无二的杂志级图文）。

14.4 v23-r24 Portal 修复

14.5 应用按钮

iPhone modal 底部「✨ 应用此风格 / 应用此模板」按钮一键关闭 modal + 切回 Compose Tab + 自动选中该风格 ID。

15 📸 长图导出

把整篇排版好的文章导出为一张 PNG / JPG 长图，用于分享朋友圈 / 微博 / 小红书 / 群聊。基于 html2canvas + 分段拼接防 OOM + SW 远程图预处理。

15.1 触发方式

• 抽屉「📸 生成长图」按钮（智能排版完成后可见）；
• 点击后底部进度条「正在渲染…N%」，3-10 秒（视长度）；
• 完成后下载弹窗 + 预览。

![待补充] 截图：长图导出进度条 + 下载弹窗

15.2 防 OOM 分段拼接（v14）

长文章一次性 html2canvas 渲染会爆内存（> 8000px 高度）。本扩展用分段策略：

1. 单段 ≤ 1500px 高度，避免单 canvas 过大；
2. 每段独立 html2canvas → 拿到 canvas A / B / C ...；
3. 新建最终 canvas，drawImage 把 A / B / C ... 串联竖直拼接；
4. 最终 canvas toDataURL('image/png') 输出。

15.3 远程图预处理（v23-r2 #3 / r16）

真根因：mp 图床（mmbiz.qpic.cn）不返 ACAO header + 校验 Referer 防盗链 双重坑。直接 html2canvas 会让 canvas 标 tainted（污染），toDataURL 抛 SecurityError。

修复链路（每个 https img 都走）：

1. html2canvas 之前，扫容器内所有 <img>；
2. 把外链 src 发给 SW（FETCH_IMAGE_AS_BASE64 handler）；
3. SW fetch（Referer: mp.weixin.qq.com / credentials: omit / 10s 超时）→ ArrayBuffer → base64；
4. 替换 <img src> 为 data:image/...;base64,...（同源资源，html2canvas 完美渲染）；
5. 失败 retry 3 次（指数退避 100/300/900ms），还失败用占位 SVG。

15.4 manifest host_permissions（v23-r16 真根因）

SW fetch 不仅要正确发请求，还需要 manifest 声明权限。本扩展 host_permissions 已包含：

• https://mmbiz.qpic.cn/*
• https://*.qpic.cn/*（mp 图床所有子域）
• https://*.qlogo.cn/*（mp 头像 CDN）
• https://images.unsplash.com/*（AI 风格 demo 图源）

15.5 暗色 / 浅色背景切换

导出前可切换：

• 白底：适合微信群 / 公众号截图分享；
• 暗底（夜读）：#1c1c1e，配合 AI 风格 midnight 个性深色。

15.6 配 COS 上传更稳

v23-r27 「AI 排版后自动 COS 上传」开启时，导出长图就更稳：

• 所有图已是 COS URL（CDN 直读，无防盗链）；
• SW 也走 base64 路径，但已是同源 COS 直链，几乎零失败；
• 长图导出耗时下降 30-50%。

16 多平台分发（一稿多发）

排好的稿不仅限于公众号。本扩展支持一键导出适配 知乎 / 头条 / 简书 / 飞书 / 微博 / 小红书 等主流平台的格式。

16.1 平台 picker 入口

抽屉底部「📤 多平台分发」按钮（高级模式）→ 弹平台选择 modal。

![待补充] 截图：平台 picker modal

16.2 各平台适配规则

17 长文卡死防护（v23-r14/r15/r31/r32）

从 mp 编辑器同步过来的长文（≥ 50KB），或粘贴正文区粘贴的复杂网页（≥ 50KB），可能导致 sidebar 卡死。本扩展用 4 层防护 解决：state 全量保留 + chunking + content-visibility:auto + iframe modal 隔离。

17.1 真根因（v23-r14）

旧实现：editorLiveHtml / pastedPreview 状态变化时，整篇 HTML 通过 dangerouslySetInnerHTML 一次性进 React tree → 浏览器 layout / paint 风暴。200KB HTML 引发 3-10 秒主线程阻塞 → sidebar 看起来「卡死」。

17.2 修复策略（4 层）

17.3 v23-r32 进一步优化

r31 之上深度排查发现 5 个真瓶颈，每键 50-200ms → 瞬时：

1. detect useMemo 改用 pastedDebounced（不再每键扫描）；
2. detectFormat 内只扫前 8000 字（HTML/SVG/MD 标记都在文首）；
3. readability 改用 debounced + >100KB 跳过分析；
4. rawToHtml ≥150KB 直接返回空（UI 走 iframe modal）；
5. PREVIEW_DEBOUNCE_MS 300 → 500ms。

17.4 content-visibility:auto 业界依据

17.5 iframe 隔离窗口

• 触发：内容 ≥ 150KB 时预览区显示「📄 超长内容 X KB · Y 字」+ 「在隔离窗口查看」按钮；
• 点击 → 90vw × 85vh modal，iframe srcdoc 渲染全量 HTML；
• iframe 是独立 document，主 React tree 完全不参与 layout，无论多大都不卡死；
• v23-r32：iframe 内 lazy 算一次 HTML，不走 purify（sandbox 已隔离）省 200ms+。

18 常见问题与故障排查（FAQ）

Q1：扩展图标灰色，点不开 sidebar

原因：当前不在 mp.weixin.qq.com 编辑页。本扩展只在 /cgi-bin/appmsg?action=edit 路径下激活。请先进入「图文消息」编辑器。

Q2：智能排版按钮全灰，提示「请先配置 API Key」

解决：选项页（Options）填写至少一个厂商的 API Key（推荐 DeepSeek）。详见第 4 章。

Q3：AI 排版后没图片 / 图片显示破图 / 图片是占位灰块

原因：mmbiz 防盗链 或 Unsplash 网络问题。解决：

1. 配 COS（第 5 章）+ 开「自动上传到 COS」（第 13 章）；
2. SW DevTools 看 [sw v23-r30 COS_UPLOAD_FROM_URL] 日志定位失败原因；
3. 若是 HTTP 403：mmbiz 防盗链生效，COS 上传可绕过；
4. 若是 BLOCKED_BY_CHROME：manifest host_permissions 缺该域（已含主流，新增请提 issue）。

Q4：粘贴大段内容时 sidebar 卡死 / 输入很慢

已修复（v23-r14/15/31/32）。请确认扩展是最新版本：chrome://extensions → 「公号编辑器·熊少」→ 详情 → 版本号 ≥ v23.r32。

Q5：「全文」「仅选区」按钮灰化划掉点不动

设计如此（v23-r29 互斥逻辑）：

• 勾选「同步原编辑器」→ scope 锁定「全文」，抽屉输入 / 仅选区灰化；
• 未勾选 → 抽屉输入 / 仅选区可用，「全文」灰化（因没同步拿不到 mp 全文）。

详见第 10 章 处理范围与同步开关。

Q6：长图导出后图片全是灰色占位

原因：旧版本 manifest 缺 mmbiz 权限。已在 v23-r16 修复。请更新到最新版本。

Q7：iPhone 预览只显示半屏 / 被 AI 抽屉遮挡

已修复（v23-r24）：iPhone modal 改用 React Portal + z-index 10001。请更新版本。

Q8：AI 续写半截就停了，没接上

v23-r17 加了续写机制（finish_reason=length 自动接龙最多 5 次）。如仍停顿请：

1. 检查厂商对应 model 的最大输出 token 是否够大（DeepSeek V3 推荐 8K / Claude 4K）；
2. 降低输入长度（< 4000 字最佳）；
3. SW DevTools 看「[sw continuation] round=N」日志确认是否触发续写。

Q9：用了「应用到正文」后内容没出现在 mp 编辑器

排查：

1. SW DevTools console 看 「[sidebar] mp_editor_set_content」日志；
2. 看 mp 标签页 console 看 「[main-world JSAPI]」日志；
3. 常见原因：mp 编辑器未完全加载 / 切换到其他 tab 时 JSAPI 失效 / mp 编辑器灰背景显示「点这里写正文」未触发 contenteditable；
4. 降级方案：开「高级布局」走剪贴板路径（第 12 章）。

Q10：BYOK Key 提示「无效」

各厂商 Key 格式不同，确认：

• DeepSeek：以 sk- 开头，长度 ≥ 48；
• Anthropic：以 sk-ant- 开头，长度 ≥ 80；
• OpenAI：以 sk- 开头，长度 ≥ 50；
• 填完点「测试连接」按钮验证。

Q11：COS 测试连接失败「校验失败 401」

SecretId / SecretKey 配错或权限不足。检查腾讯云 IAM 给该 Key 配了「cos:PutObject」权限到目标 Bucket。

Q12：COS 上传成功但 URL 无法访问

Bucket 权限设错（默认私有）。腾讯云 COS 控制台 → Bucket → 权限 → 「公有读私有写」即可。

Q13：扩展更新后状态丢了 / 设置回到默认

本扩展把所有用户偏好持久化到 chrome.storage（local + sync 双轨）。如真丢失：

• 用 Chrome 主登录账号同步（自动跨设备）；
• Chrome 扩展更新通常保留 storage（除非主版本号跳跃且 onInstalled 触发数据迁移失败）；
• 请提 issue 附 SW console 错误日志。

Q14：能否离线使用？

套版（v20 themes / templates-25）走本地纯渲染，离线可用。智能排版 / 重写 / 续写 需联网调 AI API，必须联网。

Q15：扩展会上传我的稿件到 Anthropic / 你的服务器吗？

不会。BYOK 模式下，你的稿件直接发送到 你选定的厂商 API（如 DeepSeek），扩展自己没有服务器。详见第 19 章 隐私。

Q16：能否多账号切换？

Chrome 多账户即可。每个 Chrome user 独立的 storage，互不影响。

Q17：能否自定义模板？

当前 36 套模板内置不可改，可在「AI 风格」里点「新建风格」自定义主色 / 字号 / promptHint（详见第 8 章）。完整模板编辑器在 Roadmap。

Q18：iPhone modal 显示空白

iframe 加载延迟（150KB 长 demo 时较明显）。等 0.5-2 秒。或缩短输入长度。

Q19：长图导出超时

原因：图片多 + mmbiz 防盗链慢。解决：

• 配 COS + 开自动上传（图变同源 CDN，速度 +50%）；
• SW 单图 10s 超时，超时图用占位灰块继续渲染长图；
• 若仍频繁超时，看 SW DevTools 定位哪几张图慢。

Q20：ribbon 注入按钮没出现在 mp 工具栏

v23-r30 修了 log 格式。如确实没注入，可能 mp 工具栏 DOM 变了。临时方案：用浏览器工具栏的扩展图标打开 sidebar。

19 隐私与数据安全

核心承诺：扩展本身零服务器，不收集任何用户数据。所有 API Key 仅本地存储，所有稿件仅在你设备 ↔ 你选的厂商 API 之间传输。

19.1 数据流向

用户稿件（mp 编辑器 / 抽屉粘贴）
    ↓ 本地 sidebar
    ↓
直连 DeepSeek / Anthropic / OpenAI / Qwen / GLM / Kimi / 自定义 API
    ↓
AI 输出 HTML
    ↓ 本地 sidebar
    ↓
（可选）COS 上传：用户的腾讯云 Bucket
    ↓
写回 mp 编辑器 / 长图导出 / 多平台分发

扩展开发者无任何中转服务器。

19.2 API Key 加密

• 所有 BYOK Key 用 AES-GCM-256 加密落 chrome.storage.local；
• 加密 key 用 Chrome 扩展 ID + 设备随机 salt 派生（SubtleCrypto PBKDF2）；
• 即使别人拷贝你的 chrome.storage 文件，没有你设备的 salt 也解不开；
• 选项页显示「Key 已配置（masked）」，明文不外露。

19.3 COS 凭据保护

SecretId / SecretKey 同样 AES-GCM 加密。仅 SW 上下文持有解密结果，panel 上下文（sidebar / options）拿不到 SecretKey 明文。所有 COS 调用走 SW 代理（COS_UPLOAD_DATAURL / COS_UPLOAD_FROM_URL message）。

19.4 storage 持久化范围

19.5 不收集的数据

• 稿件内容（不上传到扩展开发者）；
• 用户操作日志（不发遥测）；
• Chrome 用户身份（不读 chrome.identity）；
• 剪贴板（仅在用户主动「复制」时写入，从不主动读）。

19.6 厂商责任声明

稿件发到 DeepSeek / Anthropic 等厂商后，受该厂商隐私政策约束。详见各家官方文档：

• DeepSeek: deepseek.com/privacy
• Anthropic: anthropic.com/legal/privacy
• OpenAI: openai.com/privacy

20 v23 更新日志（r1 → r32）

本扩展从 v23-r1（2026-05-17）至 v23-r32（2026-05-21）共 32 轮迭代。下表为关键里程碑。

20.1 下一步 Roadmap（v24 计划）

• WASM 关键算法保护（防逆向第二层）；
• 自定义模板编辑器（用户自己设计 36 套之外的模板）；
• 多平台 OpenAPI 集成（一键发文到知乎 / 头条 / 简书）；
• AI 模型自动选择（智能切换最便宜的可用厂商）；
• 历史稿件全文搜索（基于嵌入向量）。