flow-xhs 0.1.0

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 doctor run --format json

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

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

快速开始

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

常用命令

flow-xhs search note --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>] [--account <user_id>] [--input <file|->]

flow-xhs note --note-id <id> [--xsec-token t] [--xsec-source src] [--comment-size N] [--sub-comment-size N] [--account <user_id>] [--input <file|->]
  # 如上游已拿到 xsec_token，默认优先携带；发现页里的笔记=pc_feed，搜索页里的笔记=pc_search，达人收藏页里的笔记=pc_collect，达人点赞页里的笔记=pc_like，达人笔记页里的笔记=pc_user

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

flow-xhs user --user-id <id> [--xsec-token t] [--xsec-source src] [--account <user_id>] [--input <file|->]
  # 如上游已拿到 xsec_token，默认优先携带；发现页里的达人=pc_feed，搜索页里的达人=pc_search，达人收藏页里的达人=pc_collect，达人点赞页里的达人=pc_like，笔记页里的达人=pc_note

flow-xhs user self --account <user_id>

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

JSON 输入模式（--input）

参数优先级固定：

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

支持 --input 的命令：

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

note 的 --input 里如果带 xsec_source，它表示笔记来源：

• 发现页笔记=pc_feed
• 搜索页笔记=pc_search
• 达人收藏页笔记=pc_collect
• 达人点赞页笔记=pc_like
• 达人笔记页笔记=pc_user

user 的 --input 里如果带 xsec_source，它表示达人来源：

• 发现页达人=pc_feed
• 搜索页达人=pc_search
• 达人收藏页达人=pc_collect
• 达人点赞页达人=pc_like
• 笔记页达人=pc_note

不支持 --input 的命令：

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

推荐 Agent 调用模板：

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

输出与退出码

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

故障排查

常见排查顺序：

1. 先运行 flow-xhs doctor run --format json
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.0
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