flow-xhs 0.1.2

Flow XHS command line interface

flow-xhs

flow-xhs 是面向小红书平台的命令行工具，提供账号管理、内容检索、详情读取和内容发布能力。它既服务终端用户，也服务自动化系统和上层 Agent 编排。

适用对象

• 个人或团队运营者：需要稳定的命令行工具完成小红书账号操作
• 自动化系统开发者：需要 JSON 协议、稳定退出码和可脚本化调用方式
• 仓库开发者：需要在 monorepo 内持续开发和发布 flow-xhs

项目结构

xhs/
├── pyproject.toml
├── README.md
├── schemas/
├── src/
│   └── flow_xhs/
│       ├── cli/
│       ├── contracts/
│       ├── services/
│       ├── runtime/
│       ├── platform/
│       ├── errors.py
│       └── exit_codes.py
└── tests/

目录职责：

• cli/：Typer 入口、命令注册、输出协议
• contracts/：输入输出模型
• services/：业务编排
• runtime/：浏览器、数据库、账号、发布运行时
• platform/：小红书平台特有实现
• tests/：本项目测试

功能范围

当前已支持：

• 运行时初始化与环境自检
• 账号登录、状态检查、列表、切换、删除
• 笔记搜索与达人搜索
• 笔记详情、达人详情、自身信息查询
• 图文与视频发布
• 面向自动化的 JSON 输入输出

当前不承诺：

• 通用型多平台 CLI
• 独立 GUI
• 完整的跨平台浏览器打包能力

系统要求

• Python 3.12.x
• pipx
• Google Chrome（推荐）

安装包会随 pipx install 自动拉取 Python 运行依赖。浏览器运行时按当前实现优先使用系统已安装的 Google Chrome；如果未找到系统 Chrome，则回退到当前环境中可用的 Playwright Chromium。

安装

macOS

brew update
brew install python@3.12 pipx
pipx ensurepath
exec zsh

pipx install --python python3.12 flow-xhs

Linux

python3.12 -m pip install --user pipx
python3.12 -m pipx ensurepath

pipx install --python python3.12 flow-xhs

Windows PowerShell

py -3.12 -m pip install --user pipx
py -3.12 -m pipx ensurepath

$python = py -3.12 -c "import sys; print(sys.executable)"
pipx install --python $python flow-xhs

如果上述方式在本机环境不可用，也可以直接把 $python 替换为 Python 解释器绝对路径。

升级与卸载

升级

pipx upgrade --python python3.12 flow-xhs

Windows 可将 python3.12 替换为对应 Python 路径或 py -3.12 解析出的解释器。

重建

如果历史环境用了其他 Python 版本，建议重建：

pipx reinstall --python python3.12 flow-xhs

卸载

pipx uninstall flow-xhs

首次使用

建议安装后先跑一遍环境自检：

flow-xhs --format json doctor

然后初始化运行目录并登录账号：

flow-xhs init
flow-xhs account login
flow-xhs --format json account status

快速开始

flow-xhs init
flow-xhs account login
flow-xhs --format json account status
flow-xhs --format json note search --keyword 旅行 --size 20 --sort-by latest --note-type image_text
flow-xhs --format json user search --keyword 摄影 --size 20

说明：--format、--out、--quiet、--trace-id 等全局参数必须位于子命令前，例如 flow-xhs --format json doctor。

常用命令

flow-xhs note search --keyword <kw> [--size N] [--sort-by <comprehensive|latest|most_liked|most_commented|most_favorited>] [--note-type <all|video|image_text>] [--publish-time <all|day|week|half_year>] [--search-scope <all|viewed|unviewed|following>] [--location <all|local|nearby>] [--input <file|->]

flow-xhs note get --note-url <url> [--comment-size N] [--sub-comment-size N] [--input <file|->]
  # 推荐直接传入完整笔记链接，自动解析 note_id / xsec_token / xsec_source

flow-xhs user search --keyword <kw> [--size N] [--input <file|->]

flow-xhs user get --user-url <url> [--input <file|->]
  # 推荐直接传入完整用户链接，自动解析 user_id / xsec_token / xsec_source

flow-xhs user self

flow-xhs note publish --target image --image-list csv --title <title> --content <content> [--tags csv] [--schedule-at rfc3339] [--input <file|->]
flow-xhs note publish --target video --video <path-or-url> --title <title> --content <content> [--tags csv] [--schedule-at rfc3339] [--input <file|->]

JSON 输入模式（--input）

参数优先级固定：

• 显式 CLI 参数
• --input JSON
• 默认值

支持 --input 的命令：

• note search
• user search
• note get
• user get
• note publish

note 的 --input 推荐传 note_url，例如：

• https://www.xiaohongshu.com/explore/69a831c6000000001b01556a?xsec_token=token&xsec_source=pc_search

user 的 --input 推荐传 user_url，例如：

• https://www.xiaohongshu.com/user/profile/6235c2f50000000010009b58?xsec_token=token&xsec_source=pc_note

不支持 --input 的命令：

• init
• doctor
• account login|status|list|activate|delete
• user self

推荐 Agent 调用模板：

flow-xhs --format json --trace-id req-001 note search --input payload.json
cat payload.json | flow-xhs --format json --trace-id req-002 note publish --input -

输出与退出码

• 自动化调用建议统一使用 --format json + --trace-id
• 退出码：0 成功，2 参数错误，3 认证错误，4 风控或限流，5 内部错误，6 超时，7 依赖缺失或未实现

故障排查

常见排查顺序：

1. 先运行 flow-xhs --format json doctor
2. 检查当前 Python 是否为 3.12.x
3. 检查系统 Chrome 是否可用
4. 若是 pipx 环境异常，优先尝试 pipx reinstall
5. 若是平台风控、登录或验证码问题，先确认账号状态再重试

开发与测试

本项目在仓库内开发时，统一从仓库根执行：

uv sync --locked --all-packages --group ci
uv run --locked --package flow-xhs python xhs/tests/runner.py --suite unit
uv run --locked --package flow-xhs python xhs/tests/runner.py --suite contract
uv run --locked --package flow-xhs python xhs/tests/runner.py --suite integration

打包校验：

uv run --locked --group ci python .github/scripts/workspace_release.py metadata --tag flow-xhs-v0.1.1
uv run --locked --group ci python .github/scripts/workspace_release.py build flow-xhs --clean
uv run --locked --group ci python -m twine check xhs/dist/*.tar.gz xhs/dist/*.whl

说明：

• schema 文件位于 schemas/
• 构建产物输出到 xhs/dist/
• CI 从仓库根触发，但目标包目录始终是 xhs/
• 开发、测试、CI 统一使用 uv
• 终端用户安装、升级、卸载继续使用 pipx

相关文档

• 仓库总览： README.md
• 用户说明： docs/users/README.md
• 开发说明： docs/development/README.md
• 发布说明： docs/release/README.md