Inkwell（墨池）

AI 辅助创作 + 人工发布工作流:工具做机械劳动(选题研究、文案生成、配图、填表、上传、话题选取),发布由你亲手点击。这是一个 TypeScript CLI 工具,支持三种内容生成模式、五种配图策略,以及基于 Playwright 的浏览器自动化——但「发布」按钮永远由人点击。

合规声明

小红书 2026 年 3 月《关于打击AI托管运营账号的治理公告》明确:工具托管、自动化批量发布属重度违规(封号档);AI 辅助创作的内容须声明「AI辅助创作」并经人工审阅修改。本工具按此公告设计:

• 本工具永不点击「发布」:程序完成导航、上传图片、填写标题正文、添加话题、尽力勾选「AI辅助创作」声明等机械劳动后,保持有头浏览器打开并提示,由你亲自点击「发布」。程序只被动检测发布结果(URL 跳转/成功文案),绝不代点。
• AI 声明勾选尽力而为 + 人工兜底:草稿 aiAssisted 默认为 true,准备阶段会自动尝试勾选声明控件;若未能勾上,工具截图并提示,由你在浏览器中手动勾选后再点击发布。
• 人工编辑留痕:预览页可直接修改标题、正文、标签,「确认内容并准备」仅确认内容并把编辑存回草稿文件(≠ 发布),审阅修改有迹可循。
• 频控/相似度防同质化:policy.dailyLimit 篇/日、间隔不少于 policy.minIntervalMinutes 分钟、与近 historyLookbackDays 天历史/草稿相似度达 similarityBlock 即拒绝进入准备——从源头降低"批量同质内容"的账号风险。
• 超时不算失败:等待人工点击有超时上限(默认 10 分钟),超时后浏览器关闭、笔记未发布,以退出码 2 结束并记为 missed;草稿文件仍在,可安全重新运行 publish(重跑会重新填表并再次等待)。

明确不做:我们不做反检测手段(随机延迟、鼠标轨迹模拟等)。那是规避,不是合规——本工具完全暴露自动化痕迹,只把最后的发布动作留给真人。

功能特性

• 三种笔记类型:图文、长文、视频,各有独立的生成、预览、发布准备流程
• 三种生成模式:keyword(AI 自主研究主题)、material(素材改写)、template(YAML 模板填充)
• 五种配图策略:ai-gen(AI 绘图)、local-pool(本地图库)、screenshot(网页截图)、text-card(文字卡片)、passthrough(直接使用)
• 可编辑浏览器预览:编辑体验内嵌于运营台外壳(一次性预览实例,只挂编辑器所需接口,发布类路由一律不挂载),标题/正文/标签可直接修改,确认后存回草稿
• 本地 Web 控制台:inkwell ui 五视图运营台——生成、草稿、日程、历史、系统状态一站齐;依旧只做准备,人工发布
• 人工确认式发布:准备完毕后保持浏览器打开,轮询检测结果,由你亲手点击「发布」
• 定时发布:node-cron 队列 + 时间窗口调度,开窗后准备笔记并等待人工点击(无人值守时到期关窗则记 missed,不强行发布)
• 一键流程:create 命令串联 生成 → 可编辑预览 → 准备 → 人工点击发布(绝不自动发布)
• 内容抓取:Playwright 抓取小红书搜索结果、笔记正文与评论,归档到本地

安装

# 安装依赖
npm install

# 可选:全局链接,获得 inkwell 命令
npm link

text-card 经 Playwright chromium 渲染（无 GTK/Cairo 原生编译依赖）；本机未装浏览器时该策略不可用，运行 npx playwright install chromium 安装，不影响其他功能。

快速开始

# 1. 配置 API 密钥
cp .env.example .env   # 填入 ANTHROPIC_API_KEY / OPENAI_API_KEY

# 2. 首次登录(扫码)
inkwell login

# 3. 生成图文草稿
inkwell generate keyword "Python装饰器" --style tutorial

# 4. 可编辑预览:修改标题/正文/标签,点「确认内容并准备」(编辑存回草稿,不发布)
inkwell preview --draft drafts/draft_xxx.json

# 5. 填表上传并等待——浏览器弹出后,请你亲自点击「发布」
inkwell publish --draft drafts/draft_xxx.json

命令总览

| 命令 | 说明 | |------|------| | inkwell login | 扫码登录小红书 | | inkwell generate keyword <关键词> | AI 研究主题生成文案(--style 风格) | | inkwell generate material <素材...> | 素材改写为小红书风格(--instruction 额外指令) | | inkwell generate template <模板名> | 使用 YAML 模板填充(--params 传 JSON 参数) | | inkwell image ai-gen <提示词> | AI 绘图(--count 指定数量) | | inkwell image local-pool | 从本地图库选图(--tags 过滤) | | inkwell image pool-add <目录> | 将目录图片加入本地图库 | | inkwell preview --draft <路径> | 可编辑预览:页面内改标题/正文/标签,点「确认内容并准备」后编辑存回草稿文件(确认 ≠ 发布),随后需另行运行 publish | | inkwell ui [--port <端口>] | 启动本地 Web 运维控制台(默认 3456,仅监听 127.0.0.1),详见「Web 控制台」章 | | inkwell publish --draft <路径> [--note-type <type>] [--dry-run] | 准备 + 等待人工点击:填表、上传、尽力勾选 AI 声明后保持浏览器打开,等你亲手点「发布」,程序自动检测成功;--dry-run 只准备不进入人工等待;人工超时退出码 2,重跑安全 | | inkwell draft list/show/delete | 草稿管理(列出/查看/删除,delete 支持 --force) | | inkwell history [--limit <n>] | 查看发布记录(含 done/failed/missed) | | inkwell create keyword <关键词> / create material <素材...> | 一站式:生成 → 可编辑预览 → 准备 → 人工点击发布(绝不自动发布) | | inkwell schedule add --draft <路径> --time <窗口> | 加入定时队列,窗口语法见下 | | inkwell schedule list | 查看队列中未完成任务(状态含 preparing/awaiting/missed) | | inkwell schedule retry <id> [--time <窗口>] | 重置 failed/missed 任务为待发布;missed 任务必须提供新窗口 | | inkwell schedule run | 启动调度器(每分钟检查一次队列) | | inkwell search <词> [--type keyword\|tag] [--limit <n>] [--interactive] [--with-body] [--with-comments] [--output <dir>] | 搜索/抓取小红书内容并归档到本地 | | inkwell status | 查看登录与待发布状态 |

generate / create / publish 均支持 --note-type image|article|video 选择笔记类型(publish 时为覆盖草稿中的类型)。

定时发布的时间窗口

schedule add / schedule retry 的 --time 接受一个发布窗口,而非单一时刻:

• 19:00-20:30 — 裸时间区间,日期取今天
• 明天20:00~21:30、18:00至19:00 — 分隔符 ~ / ～ / 至 均可;右半只写 HH:mm 时继承左半的日期
• 单一时间(30分钟后、周五 18:00、ISO 8601 等)⇒ 自动取「起点 + 60 分钟」为窗口
• 终点不晚于起点 ⇒ 视为跨午夜,终点顺延 24 小时

调度器每分钟检查队列:窗口开启后合规闸门(频控/相似度)通过即开始准备(状态 preparing),随后进入 awaiting 等待你在浏览器中点击「发布」;点击成功记 done,窗口关闭仍未发布记 missed(可用 schedule retry <id> --time <新窗口> 重来)。

Web 控制台

inkwell ui                 # 默认 3456 端口
inkwell ui --port 4000     # 端口被占用时换端口

启动后打开 http://localhost:3456。控制台只做读取与准备:所有终态动作(点击「发布」)永远由你在弹出的浏览器里人工完成,界面顶部横幅会提示当前哪篇稿子在等你。

五视图导览

截图位:docs/screenshots/console-<视图名>.png(待补)

1. 仪表盘 #/dashboard — 登录态/调度器/今日额度三盏灯、实时事件流、系统快照([截图位])
2. 内容生成 #/studio — 三种模式生成 + 配图策略选择,编辑器改题后三出口:「存为草稿」/「送调度」/「准备并等待发布」([截图位])
3. 草稿箱 #/drafts — 草稿网格,单篇可编辑/删除/「准备发布」/「加入调度」([截图位])
4. 定时队列 #/schedule — 加窗(chips + 自定义区间)、窗口状态徽章(待办/准备中/等你发布/已过窗…),过窗任务重试必填新窗([截图位])
5. 历史归档 #/history — published.jsonl 只读回看(done/failed/missed)([截图位])

齿轮「设置」抽屉直接读写 policy.* / publisher.* 配置;密钥只读显示是否配置,值绝不下发。

与 schedule run 二选一

定时调度同一时刻只能有一个驱动方:控制台里的「调度器开/关」与 CLI 的 inkwell schedule run 通过 data/scheduler.lock 互斥——文件内容是持锁进程 PID,谁先启动谁持锁,另一方显示 locked-external(并给出持锁 PID,方便你定位)。注意关台不停班:在控制台里开启的调度器跑在 inkwell ui 进程内,关掉浏览器标签页不会停它,只有结束 inkwell ui 进程(Ctrl-C)才停。

端口占用与安全

• 端口被占用时 inkwell ui 会明确报错并提示用 --port 换端口(常见占用者:另一个控制台实例或旧的 inkwell preview 进程)。
• 仅监听 127.0.0.1:控制台能读写草稿、配置并驱动浏览器做准备,请切勿将其端口暴露到局域网/公网(不要做端口转发),不用时 Ctrl-C 关闭。

测试

npx playwright test --project=console           # 冒烟:五视图渲染/awaiting 横幅/全站无代发布按钮(webServer 自动起 :3567)
npx playwright test --project=selectors -g "静态" # 静态守卫:publisher + console 层无发布点击语义(不启动任何服务)

配置

• .env:API 密钥(ANTHROPIC_API_KEY、OPENAI_API_KEY,可选 ANTHROPIC_BASE_URL 指向自定义代理)
• config/inkwell.json:运行配置,主要分组:
  • browser.* — 浏览器(headless 默认 false;人工确认发布需要有头模式,即使配置 headless=true 也会强制有头启动)
  • generator.* — 默认模型与 maxTokens
  • publisher.* — manualTimeoutMinutes(默认 10):准备完毕后等待你人工点击「发布」的上限分钟数;pollIntervalSeconds(默认 2):检测发布结果的轮询间隔;retryTimes、publishUrl
  • policy.* — 合规闸门五字段:dailyLimit(默认 2,当日成功发布数上限)、minIntervalMinutes(默认 30,两次发布最小间隔)、similarityWarn(默认 0.55,达到则警告)、similarityBlock(默认 0.75,达到则拒绝进入准备)、historyLookbackDays(默认 7,相似度回看天数)。相似度按标题/正文的字符二元组 Jaccard 计算,短正文天然偏雷同,若你常发短文/文字卡片,可适当调高 similarityBlock(如 0.85),否则会被误伤拦截
  • scraper.* — 抓取输出目录、默认条数、翻页间隔、超时与正文/评论默认抽取开关
• config/templates/*.yaml:template 生成模式使用的文案模板

开发

npm run dev -- <command>   # 直接运行源码(tsx)
npm test                   # 单元测试(vitest)
npm run test:e2e           # Playwright e2e 测试(含「永不点击发布」回归)
npm run build              # 编译到 dist/
npx tsc --noEmit           # 类型检查

文档

• 使用指南 docs/user-guide/USAGE.md — 完整使用流程与命令示例
• 工程化指南 docs/user-guide/BUILD.md — 编译、构建、调试方法
• 路线图 docs/product/ROADMAP.md — P0-P3 功能规划与分阶段落地计划
• Beav 借鉴分析 docs/product/LEARNINGS.md — 对标 Beav 的借鉴方向与反借鉴清单
• 版本发布记录 — 各版本功能变更与提交记录
• 交接文档 — 项目当前状态、环境、命令速查与安全红线（历史快照在 docs/handover/archive/）
• 测试策略 — 测试方法论、门禁规则与分层策略

目录结构

├── config/           # 运行配置 + YAML 模板 + 本地图片库
├── src/              # 源码(cli/config/generator/image/drafts/preview/policy/publisher/scheduler/scraper/console/video/utils)
├── tests/e2e/        # Playwright e2e 测试
├── docs/             # 文档
├── drafts/           # 生成的草稿与调度队列(运行时)
├── published/        # 发布记录(运行时)
└── data/browser/     # Playwright 登录态(cookie,运行时)

许可证

MIT © 2026 xuqi