@haoshu/cli（号薯 CLI）

通过本机 Agent Bridge 查询与维护号薯（小红书）数据：账号、稿件、存稿任务、发表任务、分组、标签、代理 IP、稿件分类、员工（主账号），并支持 Cookie 导入加号、账号元数据写、代理写、统计刷新、稿件导入 / 设封面 / 插配图、存稿与发表任务写。

供各类 AI Agent 调用（Cursor、Claude Code、Codex、WorkBuddy、QoderWork、QClaw、OpenClaw、Trae 等；凡能执行终端命令即可）。

前置： 必须安装并运行 号薯桌面端，在设置中启用 Agent Bridge 并生成 API Key。CLI 不能单独访问云端数据。稿件路径导入、设封面、插配图须本机绝对路径，号薯与 Agent 同机可读。

当前版本：1.7.0

安装

需要 Node.js 18+。

npm install -g @haoshu/[email protected]

安装后全局命令为 haoshu。

快速开始

1. 打开号薯 → 设置 → Agent Bridge → 启用 → 生成并复制 API Key（主账号与子账号均可；Key 本机共用）
2. 配置 CLI：

haoshu auth set-key
haoshu auth status --json

3. 查询示例：

haoshu accounts list --json
haoshu manuscripts list --assigned unassigned --json
haoshu draft-tasks list --status completed --completed today --json
haoshu publish-tasks list --status pending --json
haoshu groups list --json
haoshu tags list --json
haoshu ip-proxies list --status healthy --json
haoshu categories list --json
haoshu employees list --json   # 仅主账号

能力边界

支持（读）： 账号、稿件、存稿任务、发表任务、分组、标签、代理 IP、稿件分类、员工（仅主账号）、异步 Job、notify summary、存稿运行聚合态。accounts list|get 不含 cookie；统计字段须 --include stats；未读字段须 --include unread。

支持（写）： Cookie 导入加号、导出 Cookie（须 cookieExport 权限）、账号号主/备注、移组、设标签（含批量）、分组与标签 CRUD、代理库 CRUD / 绑定 / 检测 / Excel 导入、统计/未读刷新、账号 detect、稿件路径导入 / 改删 / 批量分类 / 清标题、稿件分类 CRUD、设封面 / 插配图、存稿任务 create·start·cancel·delete、发表任务 from-draft·start·start-batch·start-all-pending·cancel·delete。

不支持： 扫码登录、删账号、员工增删改、链接导入稿件、飞书。

导出账号 Cookie

accounts list|get 不返回 cookie；需要时用独立命令 accounts cookie，且当前登录用户须有 cookieExport 权限（员工账号看主账号的权限）。导出的是主页（www.xiaohongshu.com） 那份 Cookie —— 消息、私信等能力都依赖主页 token，创作中心那份可由它换票自动登录。无权限返回 403 FORBIDDEN；账号未登录主页、取不到 CK 时返回 503 ACCOUNT_NOT_READY。

haoshu accounts cookie <id> --json
# → { "accountId": "...", "wxid": "...", "name": "...", "cookie": "web_session=...; ..." }

Cookie 属敏感凭证，取到后请勿写入日志、仓库或转发给第三方。

Cookie 导入添加账号

与桌面端「添加账号 → Cookie 导入」同一条链路：注入 Cookie → 校验登录态 → 从平台拉回 wxid / 名称 / 类型 → 入库并接管登录态延续。wxid、名称、类型无须传入。

# 直连
haoshu accounts import-cookie --cookie-file ./ck.txt --json

# 指定分组 + 代理库节点
haoshu accounts import-cookie --cookie-file ./ck.txt \
  --group <groupId> --mode managed --ip-proxy-id <ipProxyId> --json

# 自定义代理（不入代理库，直接嵌到账号上），--payload-file 内容形如
# { "host": "1.2.3.4", "port": 1080, "type": "SOCKS5", "username": "u", "password": "p" }
haoshu accounts import-cookie --cookie-file ./ck.txt --mode custom --payload-file ./proxy.json --json

| 参数 | 说明 | |------|------| | --cookie-file / --cookie | 二选一。支持标准 Cookie 头、JSON、Netscape 等格式，自动识别。长 Cookie 建议用文件 | | --group | 分组 ID；省略或 ungrouped 表示未分组。员工账号通常必须指定 | | --owner | 号主，可选 | | --mode | direct（默认，本地直连）/ managed（配 --ip-proxy-id）/ custom（配 --payload-file） |

失败返回：账号数超限或未开通会员 403 FORBIDDEN；号薯内正在添加账号（添加账号窗口开着 / 扫码未结束）或已有导入在跑 409 CONFLICT；Cookie 失效 401 REMOTE_UNAUTHORIZED。

一次只能导入一个账号，无批量接口；多账号请串行调用，遇 409 稍后重试。

账号元数据写操作

# 修改号主/备注
haoshu accounts patch <id> --owner 张三 --json

# 移组
haoshu accounts move-group <id> --group <groupId|ungrouped> --json

# 设标签（全量替换）
haoshu accounts set-tags <id> --tags t1,t2 --json

# 分组/标签 CRUD（删除须 --confirm）
haoshu groups create --name 新分组 --json
haoshu groups delete <id> --confirm --json
haoshu tags create --name 新标签 --json
haoshu tags delete <id> --confirm --json

移组、分组 CRUD 仅主账号；员工可改可见账号的号主/备注与标签（须会员额度）。详见包内 Skill 权限表。

代理写操作

# 代理 CRUD（删除须 --confirm）
haoshu ip-proxies create --host 1.2.3.4 --port 1080 --type socks5 --json
haoshu ip-proxies test <id> --json
haoshu ip-proxies delete <id> --confirm --json

# Excel 导入（异步，返回 jobId）
haoshu ip-proxies import --file ./proxies.xlsx --json
haoshu jobs get <jobId> --json

# 账号绑定 / 代理检测
haoshu accounts bind-proxy --accounts a1 --mode managed --ip-proxy-id <id> --json
haoshu accounts proxy-detect <accountId> --json
haoshu accounts proxy-detect-batch --accounts a1,a2 --poll --json

# 无库连通性 test / 查出口 IP
haoshu proxy test --host 1.2.3.4 --port 1080 --type socks5 --json
haoshu proxy lookup-exit-ip --host 1.2.3.4 --port 1080 --type socks5 --json

Excel 导入与批量代理检测为异步 Job（内存存储，号薯重启后丢失；完成后约 1h TTL）。--poll 自动轮询 Job 至 completed/failed。

统计：读与刷新

统计字段（粉丝数、近 7 / 30 日曝光观看点赞涨粉等）默认不返回——近百个标量挂在列表每一行太重。需要时加 --include stats：

haoshu accounts list --include stats --json
haoshu accounts get <id> --include stats --json

返回形如：

{
  "id": "a1",
  "name": "测试号",
  "stats": {
    "updatedAt": 1756000000,
    "refreshing": false,
    "fansCount": 1024,
    "seven": { "impl_count": 8800, "view_count": 5200, "like_count": 42, "net_rise_fans_count": 13, "...": null },
    "thirty": { "impl_count": 30000, "...": null }
  }
}

seven / thirty 的 key 为平台原始字段名（snake_case），与「数据统计」页同源；从未刷新过的列为 null（不是 0）。

账号统计刷新（refresh-metrics）≠ 代理检测（proxy-detect）。单账号刷新直接回带 stats，无须再查一次：

haoshu accounts refresh-metrics <id> [--no-force] --json
haoshu accounts refresh-metrics-batch [--accounts a1,a2] [--poll] --json

批量省略 --accounts 时处理全部可见可刷新账号；返回 jobId，用 haoshu jobs get 轮询，完成后再 accounts list --include stats 取数。默认 force: true；--no-force 仅刷新符合自动策略的账号。

稿件导入

路径须为本机绝对路径（支持 zip）；号薯与 Agent 同机。同步返回 { imported, errors }。

haoshu manuscripts import-paths --paths /abs/a.docx,/abs/b.zip [--category <id>] [--strip-duplicate-title] --json

单篇稿件设封面

--file / --url / --clear 互斥；本机路径须绝对路径、同机可读（与 import-paths 相同约束）。

haoshu manuscripts set-cover <id> --file /abs/cover.jpg --json
haoshu manuscripts set-cover <id> --url https://example.com/cover.png --json
haoshu manuscripts set-cover <id> --clear --json

单篇稿件插入配图

--position：article_start / article_end / before_paragraph / after_paragraph。--files / --urls / --payload-file 三选一；本机路径须绝对路径且同机可读。

haoshu manuscripts insert-images <id> --position article_start --files /abs/a.jpg,/abs/b.png --json
haoshu manuscripts insert-images <id> --position before_paragraph --urls https://example.com/a.jpg --json
haoshu manuscripts insert-images <id> --payload-file ./insert-images.json --json

存稿 / 发表写操作

start 后 fire-and-forget（不返回 Job），须轮询 draft-tasks get / publish-tasks get 查看进度。发表任务由已完成的存稿任务派生（from-draft），不支持定时发布。

# 默认 --content-mode article（图文）；贴图用 note（亦接受 sticker）
haoshu draft-tasks create --account <id> --manuscripts m1,m2 [--content-mode article|note] [--payload-file ./draft.json] [--start] --json
haoshu draft-tasks start|cancel <id> --json
haoshu draft-tasks delete <id> --confirm --json

haoshu publish-tasks from-draft --draft-task <存稿任务ID> [--start] --json
haoshu publish-tasks start <id> --json
haoshu publish-tasks start-batch --ids p1,p2 --json
haoshu publish-tasks start-all-pending --json
haoshu publish-tasks cancel <id> --json
haoshu publish-tasks delete <id> --confirm --json

--payload-file 为 JSON 对象，可覆盖同名 CLI flag，允许字段：accountId、manuscriptIds、contentMode、imageDedupEnabled、noteEmptyTitleEnabled、autoClearAfterSave。

配置写入 ~/.haoshu/config.json（baseUrl 默认 http://127.0.0.1:19323，apiKey）。

列表过滤

• 过滤参数使用英文稳定码，与号薯 UI 对齐
• 多选 ID 用逗号分隔（如 --group id1,id2；哨兵 ungrouped / untagged / uncategorized）
• 详见 haoshu --help 或包内 Skill

--quick-filter 可选值：all / mainOnline / mainOffline / creatorOnline / creatorOffline / needsAttention / withIp / direct。主页与创作中心各自独立登录，在线离线因此分成两组；旧值 online / offline 仍按主页那组解释。

haoshu accounts list --quick-filter mainOnline --group g1,g2 --json
haoshu manuscripts list --cover unset --json
haoshu ip-proxies list --group ungrouped --json

员工列表：仅主账号可访问；员工子账号返回 403。

Agent Skill

包内附带 skills/haoshu-agent/SKILL.md。安装 CLI 后复制到 Agent 的 skills 目录即可：

mkdir -p ~/.claude/skills/haoshu-agent
cp "$(npm root -g)/@haoshu/cli/skills/haoshu-agent/SKILL.md" ~/.claude/skills/haoshu-agent/

仓库内开发时用 node scripts/sync-agent-skill.mjs 保持 docs/agent 与包内副本一致。

发布（维护者）

npm 账号 montisan，组织 haoshu（scope @haoshu）：

npm whoami                    # montisan
npm org ls haoshu              # 确认自己在组织内且有 publish 权限
cd packages/haoshu-cli
npm publish --access public