# flow-xhs

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

## 适用对象

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

## 项目结构

```text
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

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

pipx install --python python3.12 flow-xhs
```

### Linux

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

pipx install --python python3.12 flow-xhs
```

### Windows PowerShell

```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 解释器绝对路径。

## 升级与卸载

### 升级

```bash
pipx upgrade --python python3.12 flow-xhs
```

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

### 重建

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

```bash
pipx reinstall --python python3.12 flow-xhs
```

### 卸载

```bash
pipx uninstall flow-xhs
```

## 首次使用

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

```bash
flow-xhs doctor run --format json
```

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

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

## 快速开始

```bash
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
```

## 常用命令

```bash
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 调用模板：

```bash
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. 若是平台风控、登录或验证码问题，先确认账号状态再重试

## 开发与测试

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

```bash
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
```

打包校验：

```bash
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](../README.md)
- 用户说明： [docs/users/README.md](../docs/users/README.md)
- 开发说明： [docs/development/README.md](../docs/development/README.md)
- 发布说明： [docs/release/README.md](../docs/release/README.md)
