xhs-image-note-release

• Version: 1.5.2
• License: MIT
• Author: Evan Song · github.com/Songhonglei
• Repository: https://github.com/Songhonglei/better-office-work-flow

xhs-image-note-release

通过 ego-browser 自动化发布小红书图文笔记。覆盖从打开创作平台到发布成功的完整流程，包含图片批量上传、标题/正文填写、话题标签、一键发布等。附带 28 种多样式风格卡片生成器（含 3 种照片背景氛围主题），卡片参数可自由配置。

Dependencies

本技能依赖以下外部工具/技能，必须在使用前安装并配置：

特别提示（仅 WorkBuddy 环境）：较新版本的 WorkBuddy 需先关闭沙箱功能（设置 → 关闭沙箱），否则运行 ego-browser 会被中断。这不是本技能的依赖——在终端或其他 Agent 中直接运行本技能无需任何沙箱相关操作。

ego-browser API：本技能代码中使用的 useOrCreateTaskSpace、openOrReuseTab、snapshotText、click、fillInput、typeText、pressKey、cdp、js、pageInfo、completeTaskSpace、captureScreenshot、wait、waitForNetworkIdle、cliLog 均为 ego-browser 提供的 API，需先 Skill("ego-browser") 加载后使用。

前置条件

1. ego-lite 已安装且运行中 — ego-browser CLI 依赖 ego-lite app 提供的浏览器环境
2. 小红书已登录 — ego-browser 继承用户登录态，需在 ego-lite 中手动登录小红书一次
3. 已加载 ego-browser 技能 — 先 Skill("ego-browser") 加载浏览器操作技能

特别提示（仅 WorkBuddy 环境）：较新版本的 WorkBuddy 需先关闭沙箱功能（设置 → 关闭沙箱），否则运行 ego-browser 会被中断。这不是本技能的依赖，在终端或其他 Agent 中直接运行无需此操作。

核心流程（9 步）

创建 task space → 打开创作平台 → 等待 SPA 渲染(15s) → 进入图文发布页(自动兼容 tab/下拉)
→ 上传图片(CDP 批量) → 填标题 → 填正文 → 逐个话题从下拉列表选择
→ 调用 _onPublish() 发布 → 等待跳转确认 → 清理 task space

1. 创建 task space 并打开创作平台

ego-browser nodejs <<'EOF'
const task = await useOrCreateTaskSpace('publish xhs note')
await openOrReuseTab('https://creator.xiaohongshu.com/publish/publish', { wait: true, timeout: 25 })
// Vue SPA，必须等待 15 秒渲染
await wait(15)
EOF

关键点：小红书创作平台是 Vue SPA，`` 初始为空，waitForNetworkIdle 不够，必须 await wait(15)。

2. 进入图文发布页

创作平台支持两种入口进入图文编辑页，脚本会自动兼容两种 UI：

• 方式 A（顶部 tab）：页面顶部有「上传视频 / 上传图文 / 写长文」tab 导航，点击「上传图文」
• 方式 B（下拉菜单）：页面有「发布笔记」下拉按钮，点击展开后选「上传图文」

脚本逻辑：先试方式 A（按文本遍历点击），检查是否出现 input.upload-input；如果没有，回退到方式 B（snapshotText 匹配 ref 点击）。

// 方式 A：点击顶部「上传图文」tab
const tabClicked = await js(`(() => {
  const walker = document.createTreeWalker(document.body, NodeFilter.SHOW_TEXT, null, false)
  let node
  while (node = walker.nextNode()) {
    if (node.textContent.trim() === '上传图文') {
      let element = node.parentElement
      for (let i = 0; i < 4; i++) {
        if (!element) break
        element.click()
        element.dispatchEvent(new MouseEvent('click', { bubbles: true, cancelable: true, view: window }))
        element = element.parentElement
      }
      return true
    }
  }
  return false
})()`)
await wait(3)

// 检查是否已进入图文编辑页
if (!await js(`!!document.querySelector('input.upload-input')`)) {
  // 方式 B：回退到「发布笔记」下拉菜单
  const pageText = await snapshotText()
  const matchPublish = pageText.match(/发布笔记.*?\[ref=(\d+)/)
  if (matchPublish) {
    await click('@' + matchPublish[1])
    await wait(2)
    const text2 = await snapshotText()
    const matchUpload = text2.match(/上传图文.*?\[ref=(\d+)/)
    if (matchUpload) {
      await click('@' + matchUpload[1])
      await waitForNetworkIdle(5)
      await wait(3)
    }
  }
}

注意：两种 UI 可能同时存在或随版本切换，脚本以 input.upload-input 是否出现为判断标准，自动选择可用入口。

3. 上传图片（CDP 批量）

不能用 uploadFile() 传逗号分隔多文件路径（不生效）。必须用 CDP：

const doc = await cdp('DOM.getDocument', {})
const inputNode = await cdp('DOM.querySelector', {
  nodeId: doc.root.nodeId,
  selector: 'input.upload-input'
})
await cdp('DOM.setFileInputFiles', {
  files: ['/abs/path/img1.png', '/abs/path/img2.png', ...],
  nodeId: inputNode.nodeId
})
await wait(8)  // 等待图片处理

• 图片推荐尺寸：1080x1440（3:4 竖屏）
• 最多 18 张

4. 填写标题

await fillInput('css:input[placeholder="填写标题会有更多赞哦"]', '标题内容')

5. 填写正文与话题标签

正文区域是 contenteditable="true" 的富文本编辑器：

// 先 focus 编辑器并输入正文（不带 #话题）
await js(`document.querySelector('[contenteditable="true"]').focus()`)
await typeText('正文内容...')
await wait(1)

// 逐个话题从下拉列表选择，确保生成真正可点击的话题标签
const topics = ['话题1', '话题2']
for (const topic of topics) {
  await typeText('#' + topic, { label: 'type topic' })
  await wait(4)  // 等待下拉列表返回

  await js(`((topic) => {
    const container = document.getElementById('creator-editor-topic-container')
    if (!container) return
    const items = [...container.querySelectorAll('.item')]
    let item = items.find(el => {
      const nameEl = el.querySelector('.name')
      return nameEl && (nameEl.innerText === '#' + topic || nameEl.innerText.includes(topic))
    })
    if (!item && items.length) item = items[0]
    item && item.click()
  })('${topic}')`)

  await wait(1.5)
  await pressKey('Escape')
  await typeText(' ')
}

注意：直接粘贴 #话题1 #话题2 只会生成纯文本，不会真正挂载到话题词条。必须从 # 触发下拉列表后点击选中。

6. 触发发布

小红书的「发布」按钮封装为自定义 Web Component（``），常规选择器或坐标点击无法命中，需直接调用其暴露的发布方法：

const host = document.querySelector('xhs-publish-btn')
// 检查状态
const disabled = host.getAttribute('submit-disabled')  // 'false' = 可点
const loading = host.getAttribute('submit-loading')     // 'false' = 未加载
// 触发发布
host._onPublish()

若需了解完整的失败方案对比与排查细节，参见 references/publish-method.md。

7. 等待发布完成

调用 _onPublish() 后按钮进入 loading，约 5-10 秒后页面会重置并出现 published=true URL 参数。验证：

const info = await pageInfo()
if (info.url.includes('published=true') || info.url.includes('note-manage')) {
  cliLog('SUCCESS: 发布成功！')
}

8. 清理

await completeTaskSpace(task.id, { keep: false })

快速复用

发布已有图片

修改 scripts/publish_note.sh 中的 4 个参数后直接运行：

IMAGE_DIR="/path/to/images"
IMAGES="img1.png,img2.png,img3.png"
TITLE="标题"
BODY='正文内容'
TOPICS="话题1,话题2,话题3"

bash ~/.workbuddy/skills/xhs-image-note-release/scripts/publish_note.sh

先用本技能生成卡片，再发布

本技能附带统一风格卡片生成器，位于 references/card-generator/card_generator.py。

python3 ~/.workbuddy/skills/xhs-image-note-release/references/card-generator/card_generator.py \
  --theme warm \
  --tag "人生随笔" \
  --lines "周五了\\n你还活着吗\\n去外面走走" \
  --subtitle "关于活着" \
  --page-number 1 \
  --total-pages 6 \
  --account "@雨夜心灯" \
  -o ./card.png

# 图文卡片：顶部简笔画 + 窄列居中文字 + 底部署名
python3 ~/.workbuddy/skills/xhs-image-note-release/references/card-generator/card_generator.py \
  --layout image-text \
  --illustration ./door.svg \
  --theme warm_illust \
  --lines "周五了。\\n把工牌摘下来，" \
  --account "@雨夜心灯" \
  -o ./illust-card.png

28 种内置主题（纯文字布局全部共用同一套布局；图文布局额外支持 warm_illust）：

小红书风有两个模式：xhs = 简洁正式（白底 + 45° 极淡斜纹，呼吸感强，适合知识笔记）；xhs_rich = 丰富活泼（淡粉渐变底 + 手账圆点纹 + 毛玻璃光晕 + 三段波浪线，适合生活攻略）。

用 --list-themes 可随时打印完整清单。

自定义参数：

图文布局（--layout image-text）说明：

• 顶部居中展示插画，下方是窄列居中文字，再下方是短横线 + 账号署名。
• 文案宽度默认为卡片宽度的 65%，适合短句分行，营造留白和呼吸感。
• 不显示 tag、subtitle、页码，保持画面极简。
• 推荐主题：warm_illust（米白底、黑线稿、琥珀色点缀，与截图示例一致）。
• SVG 插画：建议插画本身以原点为中心、无多余留白；生成器会自动提取第一个 `` 元素并居中放置。
• PNG/JPG 插画：建议使用已裁切好的插画图（去除背景文字），生成器会按最大 55% 宽度 / 32% 高度等比缩放。

生成后配合 publish_note.sh 发布即可。

照片背景卡片（v1.5.0 新增）

适用场景：用户要求「书籍实拍氛围」「暗色文字底图」「照片背景卡片」等需要满幅照片作为底图、文字压在图片上的效果。

工作原理

照片背景功能在现有 HTML 渲染管线（SVG → HTML → Chrome headless → PNG）基础上，新增一层照片图层栈：

SVG 底层
  └─  纯色兜底（防止边缘透出）
  └─ 
      ├─ #photoFx   — 可选：模糊 + 降饱和滤镜
      ├─ #scrimGrad — 暗色渐变遮罩（上下两端更重，保护标签/页脚可读）
      ├─ #txtShadow — 文字投影（保证任意画面上文字清晰）
      └─ #grainFx   — 可选：胶片颗粒噪点
  └─         — 背景照片（base64 内嵌，center-crop 铺满）
  └─    — 暗色遮罩层
  └─    — 颗粒层（可选）
  └─ 
      └─ 标签 / 文案 / 页脚（全部带投影）

关键设计决策：

• 不内置素材：背景图由 Agent 通过 ImageGen 生成或用户提供，技能只负责合成
• 自动亮色反转：非照片主题传入 --background 时，文字/辅助色自动反转为亮色，无需手动切换主题
• base64 内嵌：避免 Chrome headless 的 file:// CSP 限制（与插画加载逻辑一致）

三种照片氛围主题

CLI 用法

⚠️ 以下命令统一使用生成器的完整路径。若已 cd 到 references/card-generator/，可简写为 python3 card_generator.py。 不要在续行符 \ 后面加行内注释——\ 会转义空格而非换行，# 之后整条命令被截断，下一行参数会被当作命令执行。

CG=~/.workbuddy/skills/xhs-image-note-release/references/card-generator/card_generator.py

# 基础用法：指定背景图 + 照片主题
python3 "$CG" \
  --theme cinematic \
  --background ./bg_photo.png \
  --lines "说得着，一句顶一万句；\n说不着，万句皆是多余。" \
  --account "@雨夜心灯" \
  -o card_photo.png

# 高级用法：自定义遮罩、模糊、降饱和
# --scrim 0.6    更重的暗色遮罩（默认取主题预设）
# --blur 3       背景高斯模糊半径（默认 0 = 不模糊）
# --desaturate   降饱和到 70%（不带值时取 0.65）
# --grain 0.08   手动覆盖颗粒强度
python3 "$CG" \
  --theme cinematic \
  --background ./bg_photo.png \
  --scrim 0.6 \
  --blur 3 \
  --desaturate 0.7 \
  --grain 0.08 \
  --lines "文案内容" \
  --account "@雨夜心灯" \
  -o card_custom.png

# 自动反转：用非照片主题（如浅色的 warm）+ --background，文字自动变亮色
python3 "$CG" \
  --theme warm \
  --background ./bg.png \
  --lines "文案" \
  -o card_auto.png

# 图文布局 + 照片背景：插画浮于照片之上，仅文字带投影
python3 "$CG" \
  --layout image-text \
  --illustration ./door.svg \
  --theme warm_illust \
  --background ./bg_photo.png \
  --lines "文案" \
  --account "@雨夜心灯" \
  -o card_illust_photo.png

新增参数一览

Agent 工作流（完整示例）

当用户要求「书籍实拍氛围金句卡片」时，Agent 执行以下步骤：

CG=~/.workbuddy/skills/xhs-image-note-release/references/card-generator/card_generator.py

# Step 1: ImageGen 生成背景图（5 张，每张对应一条文案的情绪）
# ImageGen 是 agent 侧工具，不在本脚本内调用；产物存为 ./bg_1.png … ./bg_5.png

# Step 2: 用 card_generator 合成文字 + 背景
QUOTES=(
  "说得着，一句顶一万句；\n说不着，万句皆是多余。"
  "我常感到内心深处\n难以名状的孤独。"
  "此刻才读懂，\n《一句顶一万句》\n到底有多动人。"
  "世上人潮汹涌，\n说得着的人千里难寻。"
  "我们所有的奔赴与寻找，\n本质都是对抗\n无法言说的孤独。"
)

for i in 1 2 3 4 5; do
  python3 "$CG" \
    --theme cinematic \
    --background "./bg_${i}.png" \
    --lines "${QUOTES[$((i-1))]}" \
    --hide-tag --hide-subtitle \
    --account "@雨夜心灯" \
    --page-number "$i" --total-pages 5 \
    -o "card_${i}.png"
done

# Step 3: 用 ego-browser 发布（见上文「核心流程」章节）

注意事项

1. 沙箱（仅 WorkBuddy 环境）：若在 WorkBuddy 中运行报错 from the default agent sandbox，请在设置中关闭沙箱后重试（见上文「特别提示」）
2. SPA 渲染：首次加载等 15 秒，不要用 waitForNetworkIdle 代替
3. 话题标签：TOPICS 中的每个话题都会先输入 # 触发建议下拉列表，再点击匹配项完成挂载；不要手动在 BODY 里写 #话题
4. 发布频率：严禁短时间连续发多篇，可能触发风控；建议每次发布间隔至少 5 分钟
5. 权限设置：发布前如需设置权限（公开/仅自己可见），在填正文后、点发布前操作
6. 标题特殊字符：脚本中 TITLE 变量会插入 JS 单引号字符串，严禁包含单引号，否则会中断脚本
7. 正文特殊字符：脚本中 BODY 变量会插入 JS 模板字符串，严禁包含反引号（`）和 ${，否则会中断脚本

Resources

scripts/

• scripts/publish_note.sh — 一键发布脚本，修改 4 个参数即可复用

references/

• references/publish-method.md — 完整方法文档，含失败方案对比表和技术原理详解。按需加载：当需要了解发布按钮各失败方案的完整对比、或需要排查发布相关问题时阅读此文件；正常发布流程无需提前加载