amm10090/fanqie-publisher-skill

核心能力

面向已经准备好章节文件的作者，以及协助作者操作后台的 AI Agent。项目通过 Playwright 将本地 Markdown 章节填入番茄小说作者后台，核对后再发布，入口统一为 scripts/publish_fanqie.js。

• 先看解析，再操作后台：从 Markdown 提取章节号、标题和正文，支持本地预览。
• 分阶段核对：可以只填编辑器，也可以推进到最终发布弹窗；真实提交需要 --confirm-publish 和用户当轮明确授权。
• 检查正文输入是否一致：填充后回读正文，逐字符比对中文、Emoji 和换行；不一致时中止当前章节。
• 单章起步，再批量或定时：支持目录选章、分卷选择，以及番茄后台原生定时发布。
• 保留本地操作记录：保存登录态、阶段截图和章节记录；可显式开启本地记录去重。

快速安装

git clone https://github.com/amm10090/fanqie-publisher-skill.git
cd fanqie-publisher-skill
npm install

运行前需要自行准备：

• Node.js 与 npm；脚本使用 Node.js 内置的 fetch。
• Python 3，用于解析章节。
• 可通过 CDP 连接的 Chromium / Chrome 浏览器。
• 能访问目标作品后台的番茄小说作者账号；需要登录时由本人扫码。

下文命令均在仓库根目录执行。npm install 安装项目依赖，不会替你启动浏览器、开启调试端口或完成登录。

快速开始

先完成单章预览和填充，再决定是否发布。示例中的 /path/to/chapters 请替换为自己的绝对路径。

1. 准备章节并预览

一份 .md 文件对应一章，使用 UTF-8、无 BOM 编码。文件名建议统一补零，例如 第001章_启程.md，内容如下：

# 第001章 启程

天亮时，他推开了门。

街道尽头，第一班车正在等候。

python3 scripts/prepare_chapters.py \
  --dir "/path/to/chapters" \
  --preview

对上述示例，预览会列出 第001章 启程，正文字符数为 26。解析器优先使用文件第一行的一级标题；没有该标题时从文件名推导。填入后台时，章节号为 1，显示标题为 启程，首行标题不进入正文。

目录只读取当前层的 Markdown 文件，并按文件名排序，不递归子目录。正文按纯文本处理，不负责将 Markdown 标记转换为富文本样式。预览中的“字数”按正文字符数计算，包含正文中的空白和换行，不等同于后台计数。

2. 配置目标作品，再连接浏览器

当前版本的目标作品写在源码中。 首次连接前，检查 scripts/publish_fanqie.js 顶部的 BOOK_ID 和 BOOK_NAME，改为自己的作品；DRAFT_URL 与 CHAPTER_MANAGE_URL 由它们生成。当前没有 --book-id 或 --book-name 命令参数。

启动自己的 Chromium / Chrome，并准备可访问的 CDP 地址。以下示例使用 http://127.0.0.1:9222；如果使用其他地址，应在登录和发布命令中保持一致。调试端口只向可信本机环境开放。

node scripts/login_fanqie.js --cdp http://127.0.0.1:9222

脚本连接浏览器；需要登录时切换到二维码流程，等待人工扫码。登录态保存在 state/fanqie-storage-state.json，二维码截图保存在 state/login-qr.png。若当前会话已登录，则刷新保存登录态。

3. 只填充一章，不提交发布

node scripts/publish_fanqie.js \
  --cdp http://127.0.0.1:9222 \
  --file "/path/to/chapters/第001章_启程.md" \
  --mode immediate \
  --fill-only

--fill-only 会实际填写章节号、标题和正文，但不点击“下一步”或“确认发布”。请在浏览器中核对目标作品、章节号、标题、完整正文、分卷和页面状态；需要指定分卷时，在这一步就加入 --volume "目标分卷名"。

填充会改写编辑器内容，应使用专门的新草稿。批量操作前，先目视检查这一章；仅查看终端输出不能替代页面核对。

从最终弹窗到正式发布

先核对最终发布设置

将上一条命令中的 --fill-only 替换为 --to-final-modal：

node scripts/publish_fanqie.js \
  --cdp http://127.0.0.1:9222 \
  --file "/path/to/chapters/第001章_启程.md" \
  --mode immediate \
  --to-final-modal

该模式会推进“下一步”及中间弹窗，尝试将“是否使用AI”设为“否”，成功后停在最终发布弹窗，不点击“确认发布”。核对分卷、章节标题和 AI 选项。

对于定时模式，这个停止点位于定时控件填写之前：到达弹窗不代表定时时间已经设置。

获得当轮授权后再提交

用户明确确认本轮的章节、作品、分卷和发布方式后，保留已核对的参数，移除停止标志，加入 --confirm-publish：

node scripts/publish_fanqie.js \
  --cdp http://127.0.0.1:9222 \
  --file "/path/to/chapters/第001章_启程.md" \
  --mode immediate \
  --confirm-publish

不要将 --confirm-publish 与 --fill-only 或 --to-final-modal 混用。每次执行命令都会重新进入处理流程，并非接着上一次停留的弹窗继续。

以章节管理页作为发布核验依据

“确认发布”点击后，回到章节管理并刷新，确认目标章节行存在，且状态为“审核中”或“已发布”。“审核中”表示已提交待审，不代表审核通过或已对读者可见。

当前汇总有一项限制： BATCH_SUMMARY 中的 publishedVerified 按“找到目标章节行”计数，代码未强制检查该行状态是否属于上述两种。因此，不能单凭 ok: true、计数增加或本地记录判定发布成功，仍需核对管理页实际状态。

批量与定时发布

批量即时发布

先预览整个目录，核对顺序和起始章节；完成单章页面核对并获得本轮批量授权后，再执行：

node scripts/publish_fanqie.js \
  --cdp http://127.0.0.1:9222 \
  --dir "/path/to/chapters" \
  --start-from "第014章" \
  --limit 3 \
  --mode immediate \
  --skip-published \
  --confirm-publish

--start-from 在文件名或标题中做子串匹配；找不到时不会报错，而会从目录开头处理。执行前必须从预览确认起点存在。首次批量建议保留较小的 --limit。

使用番茄后台原生定时发布

以下命令中的时间仅展示输入格式；执行前替换为用户确认的未来时间，并核对后台显示的日期和时间：

node scripts/publish_fanqie.js \
  --cdp http://127.0.0.1:9222 \
  --file "/path/to/chapters/第018章_启程.md" \
  --mode scheduled \
  --schedule-at "2026-11-01 21:00" \
  --confirm-publish

正确参数是 --mode scheduled 与 --schedule-at。脚本通过后台定时控件提交，不依赖外部 cron。输入不含时区，脚本按运行环境本地时间解析；它不会自动转换到作者后台的时区。

批量定时可将 --file 替换为 --dir，加入起点、数量和 --schedule-step-minutes 30，让后续章节依次间隔 30 分钟。每章都需核对管理页中的排程信息；排入队列不等于已经到时发布。

常用参数

停止模式和正式发布标志见上文。完整命令与流程说明见 SKILL.md，实际参数行为以发布脚本为准。

如何报告执行结果

以下名称用于区分操作阶段，不是脚本统一返回的状态枚举：

安全边界与本地记录

• 授权按轮次确认。 预览、填充或到达弹窗，都不构成真实发布授权；正式发布必须得到当前用户当轮明确确认。
• 字符上限是操作保护。 50,000 字符/日来自项目操作经验，不是官方配额；当前保护只应用于 immediate 模式，也不会自动读取账号今天已发的字数。
• 定时修改要留出余量。 项目记录过后台提示“请在发布时间前30分钟提交修改内容，否则无法完成修改”。遇到该提示，应将该章节视为已进入不可安全修改的窗口。
• 选择器随后台变化。 页面结构变化时先检查真实页面，再更新共享选择器和脚本，重新进行单章填充核对。

运行时文件都保存在本地 state/ 下，该目录已加入 .gitignore：

不要提交或公开登录态、二维码、用户章节及后台截图。本地去重以文件路径为依据，移动文件或换用另一份状态记录后，应重新核对后台已有章节。

接入 AI Agent

仓库提供以下指导入口，共享同一套章节解析、登录和发布脚本：

将所用 Agent 指向对应入口，并让它先读取共享工作流和安全规则。接入指导文件后，依赖、浏览器连接、人工扫码和发布确认仍需分别完成。

遇到问题时

连接失败或缺少登录态：先确认 CDP 地址和浏览器调试端口可访问，再运行 node scripts/login_fanqie.js --cdp http://127.0.0.1:9222。登录脚本默认连接该地址，并不自动启动浏览器。

出现 Unicode 一致性校验失败：查看原文编码和回读差异，结合编辑器截图检查中文、Emoji、空行和段落；修正后重新填充，不能将失败降格为成功。

分卷或弹窗不符合预期：暂停当前流程，核对作品配置和当前页面，查看分卷与发布工作流及选择器说明。需要指定分卷时，通过 --volume 走“章节管理 → 选分卷 → 新建章节”路径。

提交后未找到章节：先去管理页查询，不要直接重跑。脚本对部分页面状态错误会自动重试一次；缺少核验结果时，仍有重复提交风险。

按任务查阅文档

许可证

本项目采用 MIT 许可证。