笔记多平台发布工具 · 当前版本 v1.3.0
飞书多维表格驱动的自动发布项目：
- 小红书支持两种渠道：
- 蚁小二（API 云发布 / 本机发布）
- 比特浏览器（Playwright 模拟真人操作）
- 抖音固定走蚁小二
- 安装依赖：
npm install- 启动服务：
npm start- 首次启动时，程序会在当前系统用户目录自动生成空白配置模板
- 打开 http://localhost:3210，进入“飞书接入”页填写配置
config.example.json仅作为字段结构参考，不再要求复制到项目根目录
如需启动桌面壳（Electron）：
npm run desktop桌面版会自动拉起内置本地服务并加载同一套管理界面。
如需本地生成 Windows 安装包：
npm run dist:win如需本地生成 macOS 分发包：
npm run dist:mac当前分发方式：
- Windows：
知发 Portable.exe，免安装，可直接运行 - macOS：
知发 macOS.zip，解压后直接打开.app
两者都会继续把配置和运行数据放在系统用户目录，因此删掉程序文件本体后，本机配置默认仍会保留。
仓库内已提供 GitHub Actions 工作流，会在推送后自动构建 Windows 与 macOS 两套产物并上传为构建产物。
程序实际读写的本机数据不再放在项目根目录，而是放在当前系统用户目录：
- Windows 配置目录：
%AppData%/Zhifa/config.json - Windows 数据目录：
%LocalAppData%/Zhifa/ - macOS 配置目录：
~/Library/Application Support/Zhifa/config.json - macOS 数据目录：
~/Library/Caches/Zhifa/
其中：
- 配置文件：
config.json - 发布账本：
publish-ledger.json - 临时素材：
tmp/ - 运行缓存：
cache/
如果用户目录里还没有配置文件，程序会自动创建空白模板。
如果检测到旧版项目根目录下已有 config.json 或 publish-ledger.json，会在首次启动时自动迁移到新位置。
管理页“飞书接入”中还提供：
- 导出配置备份 / 导入配置备份：只迁移配置
- 导出完整数据 / 导入完整数据：迁移配置 + 发布账本
完整数据备份不会包含缓存目录和临时素材。
实际生效的 config.json 位于系统用户目录中。完整结构可参考 config.example.json。
| 字段 | 必填 | 说明 |
|---|---|---|
appId |
✅ | 飞书应用的 App ID |
appSecret |
✅ | 飞书应用的 App Secret |
appToken |
✅ | 多维表格的 App Token（URL 中 /base/ 后的部分） |
tableId |
✅ | 数据表的 Table ID（在多维表格设置中查看） |
wikiUrl |
— | 仅用于文档说明，程序不读取 |
| 字段 | 必填 | 说明 |
|---|---|---|
apiKey |
✅ | 蚁小二官方开放 API Key |
teamId |
✅ | 蚁小二团队 ID |
clientId |
— | 本机发布客户端 ID；填写后走本机发布，不填走云发布 |
username / password |
— | 历史遗留字段，当前版本不使用 |
| 字段 | 必填 | 说明 |
|---|---|---|
apiBaseUrl |
— | 比特浏览器本地 API 地址，默认 http://127.0.0.1:54345 |
publishUrl |
— | 小红书发布页地址，默认 https://creator.xiaohongshu.com/publish/publish |
xiaohongshu |
✅ | 小红书账号名 → browserId 的映射对象（见下方示例） |
bitbrowser.xiaohongshu 示例：
"xiaohongshu": {
"我的账号A": { "browserId": "比特浏览器中的 profile ID" },
"我的账号B": { "browserId": "另一个 profile ID" }
}账号名需与飞书表格"小红书账号"字段的选项值完全一致。
视频笔记走比特浏览器时：
- 会自动进入小红书视频发布页
- 上传
素材字段中的视频文件 - 再用
视频封面字段中的图片设置视频封面
飞书账号名 → 蚁小二平台账号 ID 的映射。账号 ID 在蚁小二后台"账号管理"中查看。
"accountMapping": {
"xiaohongshu": {
"我的账号A": "蚁小二平台账号ID"
},
"douyin": {
"我的抖音账号": "蚁小二平台账号ID"
}
}配置每天自动检查的时间窗口，支持多个时间段：
"schedule": {
"periods": [
{ "startTime": "06:00", "endTime": "08:00", "intervalMinutes": 30 },
{ "startTime": "19:00", "endTime": "21:00", "intervalMinutes": 60 }
]
}| 字段 | 说明 |
|---|---|
startTime / endTime |
时间段范围，格式 HH:MM |
intervalMinutes |
该时间段内每隔多少分钟检查一次，范围 5–480 |
"defaultMusic": {
"id": "蚁小二音乐ID",
"text": "歌曲名称（用于搜索验证）"
}不填则程序自动回退到热门纯音乐。也可在管理界面"配乐设置"中配置。
| 字段 | 默认值 | 说明 |
|---|---|---|
douyinMaxTags |
5 | 抖音最多携带标签数 |
titleMaxLength |
— | 保留字段，当前未生效；小红书/抖音标题固定截断为 20 字 |
内容表需要以下字段（字段名必须完全一致）：
| 字段名 | 类型 | 说明 |
|---|---|---|
标题 |
文本 | 笔记/视频标题 |
正文 |
文本 | 正文内容 |
标签 |
多选或文本 | 发布标签，自动去重、过滤 # 前缀 |
内容类型 |
单选 | 图文 或 视频 |
素材 |
附件 | 图片或视频文件（按文件名数字顺序排列） |
视频封面 |
附件 | 视频封面图（仅内容类型为视频时使用） |
小红书账号 |
单选 | 发布到哪个小红书账号（需与 config 账号名一致） |
小红书发布渠道 |
单选 | 蚁小二 或 比特浏览器 |
抖音账号 |
单选 | 发布到哪个抖音账号 |
发布时间 |
日期 | 定时发布；空或过去时间表示立即发布 |
发布状态 |
单选 | 已发布 时跳过该条；程序自动写入 |
小红书发布状态 |
单选 | 程序自动写入；常见值为 待发布 / 发布中 / 已发布 / 发布失败 |
抖音发布状态 |
单选 | 同上 |
配乐关键词 |
文本 | 抖音配乐搜索关键词（优先级低于"指定歌曲名"） |
指定歌曲名 |
文本 | 抖音精确匹配歌曲名 |
备注 |
文本 | 程序自动写入发布记录和错误信息，勿手动编辑 |
- 标题截断：小红书、抖音标题超过 20 字自动截断，截断情况会写入"备注"字段
- 标签数量：小红书最多取 10 个标签，抖音最多取 5 个；标签按与标题的相关度排序选取
- 自动定时发布：自动调度和顶部“立即补发”只会处理已经到发布时间，且平台状态为
待发布的记录；未来时间的记录不会被提前发出 - 云发布状态：通过蚁小二云发布时，任务提交成功后会先写成
发布中，等最终成功后再写成已发布 - 重发控制：自动调度、顶部“立即补发”、单条“立即发布”全部只会处理平台状态精确等于
待发布的记录；发布失败不会被直接重试，如需重发，必须先在飞书把对应平台状态改回待发布 - 停止行为：点击“停止”后，当前正在发布的记录会收尾，但未开始的定时任务会暂停；重新点击“启动”后会立即补扫并继续处理未完成任务
- 发布时间：若"发布时间"字段晚于当前时间，该条记录会跳过直到时间到达
- 比特浏览器：素材先下载到本地临时目录，再由 Playwright 模拟真人上传到小红书发布页
- 素材顺序：只有文件名“数字开头”的素材会按数字排序（如
0.png / 1.png / 2.png）；其余文件保持飞书原顺序，避免封面_11.png这类名字抢到第一页 - 视频封面：小红书视频封面走真实页面流程“修改封面 → 上传图片 → 确定”，不是直接替换默认封面字段
启动后提示未完成飞书接入配置
- 确认已执行
npm install - 打开管理页“飞书接入”，补全 App ID / App Secret / App Token / Table ID
- 如需手动编辑配置，路径见上方《配置与数据目录》
蚁小二连接失败
- 检查
yixiaoer.apiKey和yixiaoer.teamId是否正确 - 在蚁小二后台确认 API Key 未过期、团队 ID 与账号匹配
比特浏览器发布报错"账号未登录"
- 手动打开对应
browserId的 profile，在小红书创作者页面完成登录 - 确认
bitbrowser.apiBaseUrl与比特浏览器本地服务端口一致（默认 54345）
比特浏览器发布报错"未找到上传入口"或"未找到标题输入框"
- 小红书发布页 UI 可能已更新，需检查并更新
bitbrowser-xhs.js中对应步骤的选择器 - 可先手动在对应 profile 浏览器中打开发布页确认页面是否正常加载
飞书获取记录失败
- 检查
feishu.appId/appSecret是否正确，飞书应用是否已开通多维表格读写权限 - 确认
appToken和tableId对应的表格已向该应用授权
发布任务提交成功但平台显示失败
- 蚁小二云发布为异步任务，提交成功 ≠ 平台审核通过；请在蚁小二后台查看任务详情
- 比特浏览器发布成功后状态为最终结果
项目已接入 GitHub：https://github.com/xiwenran/bjfb
更新代码或蚁小二插件前，建议先打本地备份 tag：
npm run backup:tag
git push origin --tags执行后会创建类似 backup-20260323-183000 的 tag，可用于快速回滚：
git checkout backup-20260323-183000如果你希望在本地一条命令完成 add / commit / push，可以直接使用：
npm run git:sync -- "feat: 更新说明"这个脚本会：
- 自动
git add . - 使用你传入的提交信息执行
git commit - 推送到当前分支对应的
origin/<branch>
如果不传提交信息，会自动生成一个带时间戳的默认说明。
如果 GitHub Actions 生成的 macOS 包和你的本机架构不匹配，也可以先在本地打包，再把本地产物上传到 GitHub Release：
npm run dist:mac
npm run release:mac-local默认会上传 dist/知发 macOS.zip，并自动创建一个带时间戳的 Release。你也可以手动指定文件路径和 tag：
npm run release:mac-local -- "dist/知发 macOS.zip" "local-mac-manual-20260327"这种方式上传的是发布附件，不会把安装包提交进代码仓库。
如果你更习惯直接双击文件，也可以在项目根目录双击：
-
打包并上传Mac.command -
仅打包Mac.command -
打包并上传Mac.command：本地打包后上传到 GitHub Release -
仅打包Mac.command：只在本地生成 mac 安装包，不上传 GitHub
AI 写作模块
- 新增设置页"AI 写作"子页面，支持配置 OpenAI 兼容接口、Anthropic Claude 官方 API、Google Gemini 官方 API
- 定时扫描时自动检测飞书"笔记主题"字段：有值且 24 小时内修改过、内容与上次不同，则调用 AI 生成标题/正文/标签并回写飞书
- 发布页右栏新增"AI 生成"按钮，可手动为单条记录立即生成内容
- 生成缓存存储在本机
ai-writing-cache.json，相同主题不重复调用，修改后自动重新生成
账号映射修复 + 内容过滤
- 修复账号重新授权后持续显示"未映射"：蚁小二账号重新授权后 ID 会变更，旧映射的 ID 失效但代码直接跳过已有映射不再重建，导致始终显示"未映射"。现在刷新时先清除指向已失效 ID 的陈旧映射，再自动重新匹配。
- 跳过标题或素材为空的记录：标题为空或素材附件为空的记录不再加入精准任务队列，日志输出
⚠️ 跳过...：标题或素材为空，避免无效任务积压。
公式字段兼容性修复
- 修复标题/正文为空：飞书公式字段（引用 AI 生成输出结果）在 API 中有时以
{value: "内容"}或{value: [{text:...}]}格式包装返回，原来的getText没有处理这种格式，导致读取结果为空。现在兼容所有已知包装格式。 - 修复标签乱码：
getTagValues遇到{value: [...]}对象时，原来的String(field.value)会输出[object Object]，现在正确展开数组后再拆分标签。
稳定性修复
- 修复图片上传 EPIPE 弹窗：PUT 到 OSS 时服务端关闭连接，会触发 Node ReadStream EPIPE 错误，此前会弹 Electron 错误对话框并干扰上传结果（图片没传成功但任务仍被提交，蚁小二后台显示"图片上传失败"）。现在错误正确传播，飞书里会显示"发布失败"，不再有静默漏发。
- 修复 saveLedger 非原子写：本地 publish-ledger.json 改为 tmp+rename 原子写，与 publish-history.json 保持一致。避免进程被强杀时 ledger 写成残缺 JSON，导致下次启动服务失败。
- 修复飞书附件同名覆盖：同一条记录里两个附件名称相同时，本地文件不再互相覆盖，自动追加
_2/_3后缀区分。 - 视频封面子目录隔离：videoCover 下载到独立的
tmpDir/cover/子目录，避免封面文件名与正文图片同名时互相污染。
重大事故修复（上版本未来得及写入）
- 修复蚁小二上传 fileKey 跨记录覆盖：2026-04-09 事故根因——上传接口曾将客户端文件名作为 OSS 全局 key，导致 5 条不同记录的同名图片（1.png/封面.png）互相覆盖，发出去的 5 篇笔记图片全是同一篇内容。已回滚为由服务端生成唯一 key，并在客户端文件名加随机前缀作双重兜底。
- 修复待发布计数：平台状态为空时不再算作待发布
- 附件排序支持小数点（
1.1 < 1.2）和括号（1(1) < 1(2)）命名风格 - 左侧导航栏布局调整：数据移至顶部，设置独立在底部，版本号显示在最底部
- 红线防护架构加固（C1 预查重 + R6 写入顺序 + 跨账号血统账本）
- 初始发布
- 支持小红书（蚁小二云/本机发布、比特浏览器）、抖音（蚁小二）
- 飞书多维表格驱动，定时自动发布
- Electron 桌面版