使用文档

pupu 是一款多平台内容发布浏览器扩展：一次编辑，轻松将内容同步发布到多个社交平台。当前版本为 0.3.0。

安装

pupu 提供已经打包好的扩展压缩包，无需自己编译即可安装使用。

  1. 下载并解压

    在 Releases 页面下载 pupu-v<version>.zip，解压到任意目录。解压后目录中应当直接能看到 manifest.json。

  2. 打开扩展管理页并开启开发者模式

    Chrome 输入 chrome://extensions，Edge 输入 edge://extensions，打开右上角「开发者模式」。

  3. 加载已解压的扩展程序

    点击左上角「加载已解压的扩展程序」，选中第 1 步解压出的目录。

为什么不能直接装 .crx？ 自签名 CRX 无法通过拖拽或普通安装流程安装：Chromium 会校验 CRX 内的 proof 是否由 Chrome 应用商店的私钥签名，否则报 CRX_REQUIRED_PROOF_MISSING（依据见 Chromium 的 crx_verifier.cc：off-store 的 CRX 会按 CRX3_WITH_PUBLISHER_PROOF 校验）。这与怎么打包无关， 加 manifest 的 key 字段或 update_url 都不解决；唯一可用的 CRX 路径是机器级强制企业策略 （ExtensionInstallAllowlist + ExtensionInstallSources，注意必须是 MANDATORY，recommended 会被忽略）。 因此本项目不再提供 .crx，想彻底摆脱「开发者模式」，唯一途径是上架应用商店。
扩展 ID 为 nffpajdealkjpdmjjboneelajanbboig（由签名密钥决定，各版本固定不变）。Edge 与 Chrome 同为 Chromium，共用同一份 .zip。
安装后点击工具栏的 pupu 图标会自动打开扩展主界面（选项页），侧边栏用于平台选择与账号管理。

Linux 桌面 Agent 实验版

main 开发版新增单窗口多平台工作台，尚未发布安装包： 源码运行 pnpm desktop:dev，可使用插件的动态、视频、Markdown 文章编辑器及图片/PPTX/PDF 导入。 平台收纳为窗口内标签，批量执行不弹窗或抢焦点；需要登录时点击「登录 / 查看」或顶部平台标签。 普通适配器自动模式显示「待确认」，不是发布成功；可能已提交或仍执行的任务禁止重载重发。 此路径不需要模型，原 Agent 入口为 pnpm desktop:agent。 下列下载和操作步骤针对已发布的 v0.3.0 小红书试点；开发版未逐一验收所有真实平台。
  1. 从 Releases 下载 pupu-desktop-v0.3.0-linux-x64.tar.gz，解压并保留完整目录，运行 pupu-linux-x64/pupu。不需要 Node.js 或加载扩展。仅提供 Linux x64 归档。
  2. 单独安装 Ollama。连接本机服务，或在高级设置选择 Ollama 可执行文件，再点击「下载 Qwen3 4B」。模型约 2.5 GB，不包含在应用归档中。
  3. 输入标题、正文并添加图片，打开平台窗口登录并确认当前账号。点击「让 Agent 自动发布」，确认本次任务后自动执行。

先想了解流程，可在高级设置运行本地模拟发布，不会向互联网发布。正式任务中的正文和图片会上传到小红书；本地模型只读取字段标签。

目前仅试点小红书图文。已实测真实平台上传、填写、回读、图文导航，未实测真实提交及成功回执。登录、验证码或歧义会暂停，提交不确定时不要直接重发，请在内容管理核对。停止不能撤销已提交内容。

草稿文字和登录状态可保留，图片选择重启后需要重新添加。缺少内容/图片或模型时点击发布按钮会显示原因；不需要自己操作「观察字段」。Windows/macOS 和手机应用尚未发布。

pnpm desktop:dev
pnpm desktop:smoke     # 不需要模型的 Chromium/IPC 冒烟
pnpm desktop:verify    # 真实本地 Qwen3 + 模拟发布
pnpm desktop:package

发布流程

CI 同时检查扩展和桌面类型、测试、扩展归档及无模型桌面冒烟。Release 在 Linux runner 打包并验证完整桌面目录，所有产物成功后发布扩展 ZIP、桌面 tar.gz 和 SHA256SUMS，再部署 Pages。Pages 静态版本读取已发布 Release，而非尚未发布的标签。

使用

发布类型

  • 动态：只填内容即可。支持添加图片、导入 PPT / PDF 并自动逐页转图片随动态发布。
  • 视频：上传视频并发布到支持视频的平台。
  • 文章：导入本地 Markdown，可视化编辑 / 预览渲染，图片随正文一起发布。

自动 / 手动发布

底部开关可一键切换发布模式：自动发布在内容填充完成后直接提交；手动发布只把内容填充到各平台页面，由你确认后再发布。首次使用建议先用手动发布确认各平台填充效果。

内容工具栏

  • 用 # 包裹文字即可添加话题，例如 #今日好物#；选中文字可一键包裹为 #话题#。
  • 输入框内的话题会实时蓝色高亮预览。
  • emoji 分类面板共 9 类，包含颜文字。
  • 发布到小红书时会自动把 #话题# 转换为小红书格式 #话题[话题]#；标题超过 20 字会自动跳过标题。

平台与分组

动态 / 视频 / 文章各自的首选平台会单独列出，其余平台统一归入「其它」分组。

发布类型 首选平台
动态 微博、小红书、知乎、X、脸书
视频 抖音、快手、微信视频号、bilibili、微博、小红书、Youtube
文章 微信公众号、知乎、CSDN、51CTO

其它平台包括掘金、简书、思否、少数派、豆瓣、雪球、即刻、今日头条、百家号、网易号、搜狐号、企鹅号、大鱼号、一点号、东方财富、得物、小黑盒、脉脉、知识星球、阿里云、腾讯云、WordPress、Medium、Instagram、TikTok、LinkedIn、Reddit、Pinterest、Threads、BlueSky、V2EX、Webhook 等，完整列表可在扩展内的平台选择面板查看。

各平台图标内置在扩展本地、离线可用，国内平台按流量池排序置前。部分平台（如即刻、Webhook、知识星球、WordPress）需要先配置圈子 / 地址 / 星球等附加信息。

账号与侧边栏

  • 侧边栏显示当前编辑类型的平台列表，切换 Tab 时实时跟随；切到「关于」页会自动关闭侧边栏。
  • 顶栏账户头像按当前月份显示 12 生肖，悬停同时显示生肖与星座。点击头像可一键展开侧边栏。
  • 账号不会在打开侧边栏时自动刷新，只有点击「刷新账号」才会真正抓取各平台账号；已登录的平台排在最前，常用平台其次，其余平台折叠收纳。
  • 「清空账号缓存」需二次确认，清空后会自动重新刷新一次账号。

本地开发与构建

需要 Node.js 与 pnpm。

pnpm install
pnpm dev        # 启动 Plasmo 开发模式（热更新）

构建产物的命令：

pnpm build      # 本地构建：只产出可「加载已解压」的目录（不出 zip / crx）
pnpm build:ci   # 构建并打包 zip（CI 使用）
pnpm package    # 只把已构建的产物打包成 zip
pnpm crx        # 只打包 CRX（自托管/企业策略场景用，需签名密钥；不能拖拽安装）
pnpm verify:crx # 校验 CRX3 签名与包内内容

本地构建刻意不产出 zip / crx（那些由 CI 生成并附加到 Release），只输出 build/chrome-mv3-prod/，在扩展管理页「加载已解压的扩展程序」中直接导入即可。

注意：构建后会自动执行 scripts/copy-pdf-worker.mjs，把 PDF worker、PDF 图像解码器 WASM 与离线平台图标复制进产物。若直接使用 npx plasmo build，需要手动补跑该脚本，否则 PDF 转图片与平台图标会缺失。
签名密钥：扩展 ID 由签名密钥决定，若将来要做企业策略自托管或上架商店，必须沿用同一密钥。 本地密钥放在 keys/pupu.pem（已被 .gitignore 忽略），CI 从仓库 Secret CRX_PRIVATE_KEY 读取（Release 已不再需要它）。没有密钥时 pnpm crx 会跳过而不会自动生成新密钥 —— 新密钥会产生新的扩展 ID，已安装用户将收不到更新。

代码检查与测试

pnpm lint       # 代码检查（Biome）
pnpm lint:fix   # 自动修复
pnpm format     # 格式化
pnpm typecheck  # 类型检查（tsc --noEmit）
pnpm test       # 单元测试（vitest）

CI / CD 与发布

仓库内置三条 GitHub Actions 工作流：

工作流 触发条件 作用
CI push 到 main、PR、手动 安装依赖 → pnpm lint → pnpm typecheck → pnpm test → 桌面类型检查与无模型 Chromium 冒烟 → pnpm build:ci，校验产物；再用临时密钥打包 CRX 做冒烟测试（仅验证打包路径可用），最后上传 zip 与解压目录为构建产物
Release 推送 v* 标签、手动 校验标签与 package.json 版本一致 → lint + typecheck + test → 扩展构建 + Linux 桌面打包/冒烟 → 创建 Release，附上扩展 ZIP、桌面 tar.gz 与 SHA256SUMS（不附 CRX）
Deploy Pages push 到 main 且改动 docs/**、手动 把 docs/ 目录部署到 GitHub Pages（本站在此发布）

发布一个版本

先改版本号并提交，再打标签（顺序不能反，否则发布流程会因一致性校验失败而中止）：

pnpm pkg set version=0.3.0
# 同步更新 docs/releases/v0.3.0.md 并提交相关变更
git commit -am "chore(release): 0.3.0"
git push origin main
git tag v0.3.0 && git push origin v0.3.0

推送标签后，Release 工作流会校验标签与 package.json 版本一致、跑完 lint / 类型检查 / 单元测试、 构建扩展 ZIP 与 Linux 桌面归档（校验 manifest 版本与标签一致），然后发布到 Releases 页面， 并触发一次站点重部署以同步站点上的版本号。也可以在 Actions 页面手动运行 Release 工作流并填写版本号， 输入必须与源码版本一致，且必须提供对应更新说明；它会自动创建对应标签。

为什么必须先改版本号：扩展内「关于」页显示的是构建时 manifest 的版本，而 manifest 版本来自 package.json。标签与 package.json 不一致时发布流程会直接失败并给出修复命令， 避免仓库版本与已发布版本悄悄漂移。
站点版本号是自动的：部署时查询已发布 Release，并由 scripts/inject-site-version.mjs 注入静态页面，页面再用 GitHub API 获取最新 release；发布流程结束时会自动触发一次站点重部署。README 徽章同样由 shields 动态读取，都无需手工维护。

常见问题

安装 .crx 时提示「包无效：CRX_REQUIRED_PROOF_MISSING」？

这是 Chromium 对非商店来源 CRX 的限制，不是打包方式的问题：它会校验 CRX 内的 proof 是否由 Chrome 应用商店的私钥签名，自签名的一律被拒（拖拽、双击都一样），因此本项目已不再提供 .crx。请改用 .zip + 「加载已解压的扩展程序」。若确实需要 CRX 部署，只能走机器级强制企业策略 （ExtensionInstallAllowlist + ExtensionInstallSources）；要彻底摆脱「开发者模式」，唯一途径是上架 Chrome Web Store / Edge 加载项商店，且上架与后续更新都要沿用同一把签名密钥以保持扩展 ID 不变。

安装后扩展被浏览器停用 / 提示来自非应用商店？

这是不经过应用商店安装的浏览器限制，与扩展本身无关：需保持扩展管理页右上角的「开发者模式」开启， 否则这类扩展可能被浏览器自动停用。

有 Safari 版本吗？

暂时没有。Safari 扩展不能像 .crx 那样单独分发，必须由 Xcode 打包成宿主 App 并通过 App Store 分发；另外本扩展依赖的 sidePanel（侧边栏选平台）与 tabGroups 在 Safari 上并不存在，即使转换出来核心流程也无法工作。

扩展里的 PDF / 平台图标显示不出来？

通常是没有执行复制脚本导致的。重新运行 pnpm build:ci（或 pnpm dev）即可，产物中应当存在 pdf.worker.min.mjs、wasm/ 与 assets/platforms/。

为什么标题没有发布出去？

部分平台（如小红书）标题有长度限制，超过 20 字时会自动跳过标题，只发布正文内容。

为什么打开侧边栏没有显示我的账号？

账号只在点击「刷新账号」时抓取，不会自动刷新。请先在各平台登录，再点击「刷新账号」；若仍未显示，可尝试「清空账号缓存」后重新刷新。

遇到问题或想新增平台？

欢迎到 GitHub Issues 反馈，或在扩展内点击「提交反馈」/「发送邮件」。

权限说明

扩展申请的权限与用途如下（见 package.json 中的 manifest 字段）：

权限 用途
host_permissions 访问 https://*/* 与本地地址，用于在目标平台页面填充 / 发布内容
cookies 读取各平台的登录状态，用于判断账号是否已登录
tabs / tabGroups 为每个同步任务打开管理标签页，并在侧边栏中管理这些标签
scripting 向目标页面注入内容填充与抓取脚本
activeTab 在当前活动标签页上执行用户主动触发的操作
sidePanel 提供平台选择与账号管理的侧边栏界面
background 在后台协调各平台标签页与同步任务

扩展会把内容发布到你自己已经登录的平台；除此之外，扩展会请求项目自身的同步服务 https://pupu.app（开发模式下为 http://localhost:3000）用于账号数据同步。设置页的「可信域名」 用于授权特定网站调用扩展的发布能力，请只添加你信任的域名。

本项目为个人学习 / 交流项目，请遵守各平台的使用规范与当地法律法规。