xhs-kit 0.1.0__tar.gz

xhs_kit-0.1.0/.claude/skills/xhs-kit/SKILL.md

@@ -0,0 +1,350 @@
+---
+name: post-to-xhs
+description: 小红书内容发布与管理助手。当用户要求登录、发小红书、搜索小红书、评论点赞收藏等任何小红书相关操作时使用。
+metadata: {"openclaw": {"emoji": "📕", "requires": {"bins": ["convert"]}}}
+---
+
+# xhs-kit 使用方式
+
+## 安装
+
+首次使用需要确认环境中有 Python 解释器。
+
+```bash
+# 使用 pip 安装
+pip install -U xhs-kit
+
+# 安装 Playwright 浏览器（必需）
+playwright install chromium
+```
+
+## ⚠️ 重要：所有操作必须先登录
+
+**小红书所有功能（发布、搜索、点赞、评论等）都需要先登录。**
+
+### 1. 检查登录状态
+
+执行任何操作前，先检查是否已登录：
+
+```bash
+xhs-kit status
+```
+
+- 输出 `✅ 已登录`：表示检测到 cookies 文件（quick 模式），通常可以继续操作
+- 输出 `❌ 未登录`：表示未检测到 cookies 文件，必须先执行登录步骤
+
+如果出现发布或者评论无结果等错误，说明 cookies 可能已过期或不可用，此时使用 verify 模式做真实校验：
+
+```bash
+xhs-kit status --verify
+```
+
+- 输出 `✅ 已登录（verify）`：cookies 仍可用，失败原因更可能是内容不可见或参数问题
+- 输出 `❌ 未登录（verify）`：cookies 可能过期或被风控，需要重新登录
+
+### 2. 登录方式（带 fallback 逻辑）
+
+**推荐按以下顺序尝试登录：**
+
+**方式一：终端二维码（Claude Code / Open Code 推荐）**
+```bash
+xhs-kit login-qrcode --terminal
+```
+- ⚠️ 需要安装 zbar 库才能解析二维码：
+  - macOS: `brew install zbar`
+  - Ubuntu: `apt install libzbar0`
+- 如果未安装 zbar，会自动保存二维码图片并提示路径
+- 用户扫码后按回车完成登录
+- 如果终端显示失败，fallback 到方式二
+
+**方式二：浏览器扫码登录（有图形界面的环境）**
+```bash
+xhs-kit login-browser
+```
+- 会弹出浏览器窗口供用户扫码
+- 如果无法弹出浏览器（如远程服务器无图形界面），会提示使用二维码方式
+
+**方式三：保存二维码图片（OpenClaw 推荐）**
+```bash
+xhs-kit login-qrcode --save /tmp/qrcode.png
+```
+- 将二维码图片发送给用户扫码
+- 用户扫码后按回车完成登录
+
+**如果以上方式都失败：**
+- 提醒用户需要安装浏览器环境（Playwright + Chromium）
+- 或需要图形界面环境
+
+### 3. 登录参数说明
+
+`login-qrcode` 参数：
+
+| 参数 | 类型 | 必需 | 说明 |
+|------|------|------|------|
+| `-s/--save` | string | ❌ | 保存二维码图片到指定路径 |
+| `--terminal/--no-terminal` | flag | ❌ | 是否在终端显示二维码（默认 terminal） |
+
+登录成功后，cookies 会保存到本地文件，后续操作自动复用（有效期约 7-30 天）。
+
+## ⚠️ Agent 运行建议（Claude Code / OpenClaw / MCP）
+
+- **不要在每次调用前都执行 `status --verify`**，这会频繁打开页面，增加开销和风控风险。
+- 默认使用 `xhs-kit status`（quick）即可。
+- **仅当出现如下错误时**再执行 `xhs-kit status --verify`：
+  - `未找到笔记详情（可能 xsec_token 失效、未登录或触发风控）`
+  - 发布/点赞/评论失败且多次重试无效
+- 如果 `status --verify` 判定未登录，再让用户执行 `xhs-kit login-browser`（需要人工扫码）。
+
+## 发布操作
+
+### 发布图文内容
+
+命令：`xhs-kit publish`
+
+**参数：**（`-i/--image`、`--tag` 可多次指定）
+
+| 参数 | 类型 | 必需 | 说明 |
+|------|------|------|------|
+| `-t/--title` | string | ✅ | 文字标题 |
+| `-c/--content` | string | ✅ | 文字正文内容 |
+| `-i/--image` | string | ✅ | 图片路径（可多次指定） |
+| `--tag` | string | ❌ | 话题标签（可多次指定） |
+| `--headless/--no-headless` | flag | ❌ | 是否无头模式（默认 headless） |
+
+示例：
+
+```bash
+xhs-kit publish -t "标题" -c "正文" -i /abs/1.jpg -i /abs/2.jpg --tag 旅行 --tag 美食
+```
+
+### 发布视频内容
+
+命令：`xhs-kit publish-video`
+
+**参数：**
+
+| 参数 | 类型 | 必需 | 说明 |
+|------|------|------|------|
+| `-t/--title` | string | ✅ | 文字标题 |
+| `-c/--content` | string | ✅ | 文字正文内容 |
+| `-v/--video` | string | ✅ | 视频路径 |
+| `--tag` | string | ❌ | 话题标签（可多次指定） |
+| `--headless/--no-headless` | flag | ❌ | 是否无头模式（默认 headless） |
+
+示例：
+
+```bash
+xhs-kit publish-video -t "标题" -c "正文" -v /abs/video.mp4
+```
+
+### 发布文字配图（文字卡片）
+
+命令：`xhs-kit publish-text-card`
+
+**参数：**（`-p/--page`、`--tag` 可多次指定）
+
+| 参数 | 类型 | 必需 | 说明 |
+|------|------|------|------|
+| `-c/--cover` | string | ✅ | 封面文字 |
+| `-p/--page` | string | ❌ | 正文页文字（可多次指定，最多17页） |
+| `-s/--style` | string | ❌ | 卡片样式：基础\|边框\|备忘\|手写\|便签\|涂写\|简约\|光影\|几何 |
+| `-t/--title` | string | ❌ | 文字标题 |
+| `--content` | string | ❌ | 文字正文内容 |
+| `--tag` | string | ❌ | 话题标签（可多次指定） |
+| `--headless/--no-headless` | flag | ❌ | 是否无头模式（默认 headless） |
+
+示例：
+
+```bash
+xhs-kit publish-text-card -c "封面" -p "第一页" -p "第二页" -s "基础" -t "笔记标题"
+```
+
+## 浏览/搜索
+
+### 搜索内容
+
+命令：`xhs-kit search`
+
+**参数：**
+
+| 参数 | 类型 | 必需 | 说明 |
+|------|------|------|------|
+| `-k/--keyword` | string | ✅ | 搜索关键词 |
+| `--headless/--no-headless` | flag | ❌ | 是否无头模式（默认 headless） |
+
+**输出：**
+
+命令会打印搜索到的笔记列表。每条结果会包含：
+
+- `ID`：对应后续命令里的 `--feed-id`
+- `xsec_token`：对应后续命令里的 `--xsec-token`
+
+示例（截断）：
+
+```text
+1. 标题...
+   作者: xxx | 点赞: 123
+   ID: 1234567890abcdef
+   xsec_token: xsec_xxx
+```
+
+### 获取首页推荐列表
+
+命令：`xhs-kit list-feeds`
+
+**参数：**
+
+| 参数 | 类型 | 必需 | 说明 |
+|------|------|------|------|
+| `--headless/--no-headless` | flag | ❌ | 是否无头模式（默认 headless） |
+
+**输出：** JSON 格式的推荐笔记列表
+
+示例：
+
+```bash
+xhs-kit list-feeds
+```
+
+### 获取笔记详情
+
+命令：`xhs-kit detail`
+
+**参数：**
+
+| 参数 | 类型 | 必需 | 说明 |
+|------|------|------|------|
+| `--feed-id` | string | ✅ | 笔记 ID |
+| `--xsec-token` | string | ✅ | 访问令牌 |
+| `--load-comments` | flag | ❌ | 是否加载评论（默认 false） |
+| `--headless/--no-headless` | flag | ❌ | 是否无头模式（默认 headless） |
+
+**输出：** JSON 格式的笔记详情（包括标题、内容、图片、互动数据等）
+
+示例：
+
+```bash
+xhs-kit detail --feed-id FEED_ID --xsec-token XSEC_TOKEN
+xhs-kit detail --feed-id FEED_ID --xsec-token XSEC_TOKEN --load-comments
+```
+
+### 获取用户主页
+
+命令：`xhs-kit user-profile`
+
+**参数：**
+
+| 参数 | 类型 | 必需 | 说明 |
+|------|------|------|------|
+| `--user-id` | string | ✅ | 用户 ID |
+| `--xsec-token` | string | ✅ | 访问令牌 |
+| `--headless/--no-headless` | flag | ❌ | 是否无头模式（默认 headless） |
+
+**输出：** JSON 格式的用户主页信息
+
+示例：
+
+```bash
+xhs-kit user-profile --user-id USER_ID --xsec-token XSEC_TOKEN
+```
+
+## 互动（点赞/收藏/评论）
+
+以下命令需要你先从搜索结果或笔记链接中拿到 `feed_id` 和 `xsec_token`。
+
+### 点赞/取消点赞
+
+命令：`xhs-kit like`
+
+**参数：**
+
+| 参数 | 类型 | 必需 | 说明 |
+|------|------|------|------|
+| `--feed-id` | string | ✅ | 笔记 ID |
+| `--xsec-token` | string | ✅ | 访问令牌 |
+| `--unlike` | flag | ❌ | 取消点赞（默认 false 为点赞） |
+| `--headless/--no-headless` | flag | ❌ | 是否无头模式（默认 headless） |
+
+示例：
+
+```bash
+xhs-kit like --feed-id FEED_ID --xsec-token XSEC_TOKEN
+xhs-kit like --feed-id FEED_ID --xsec-token XSEC_TOKEN --unlike
+```
+
+### 收藏/取消收藏
+
+命令：`xhs-kit favorite`
+
+**参数：**
+
+| 参数 | 类型 | 必需 | 说明 |
+|------|------|------|------|
+| `--feed-id` | string | ✅ | 笔记 ID |
+| `--xsec-token` | string | ✅ | 访问令牌 |
+| `--unfavorite` | flag | ❌ | 取消收藏（默认 false 为收藏） |
+| `--headless/--no-headless` | flag | ❌ | 是否无头模式（默认 headless） |
+
+示例：
+
+```bash
+xhs-kit favorite --feed-id FEED_ID --xsec-token XSEC_TOKEN
+xhs-kit favorite --feed-id FEED_ID --xsec-token XSEC_TOKEN --unfavorite
+```
+
+### 发表评论
+
+命令：`xhs-kit comment`
+
+**参数：**
+
+| 参数 | 类型 | 必需 | 说明 |
+|------|------|------|------|
+| `--feed-id` | string | ✅ | 笔记 ID |
+| `--xsec-token` | string | ✅ | 访问令牌 |
+| `-c/--content` | string | ✅ | 评论内容 |
+| `--headless/--no-headless` | flag | ❌ | 是否无头模式（默认 headless） |
+
+示例：
+
+```bash
+xhs-kit comment --feed-id FEED_ID --xsec-token XSEC_TOKEN -c "评论内容"
+```
+
+### 回复评论
+
+命令：`xhs-kit reply-comment`
+
+**参数：**
+
+| 参数 | 类型 | 必需 | 说明 |
+|------|------|------|------|
+| `--feed-id` | string | ✅ | 笔记 ID |
+| `--xsec-token` | string | ✅ | 访问令牌 |
+| `-c/--content` | string | ✅ | 回复内容 |
+| `--comment-id` | string | ❌ | 目标评论 ID |
+| `--user-id` | string | ❌ | 目标用户 ID |
+| `--headless/--no-headless` | flag | ❌ | 是否无头模式（默认 headless） |
+
+`--comment-id` 和 `--user-id` 至少需要提供一个。
+
+示例：
+
+```bash
+xhs-kit reply-comment --feed-id FEED_ID --xsec-token XSEC_TOKEN -c "回复内容" --comment-id COMMENT_ID
+```
+
+
+## 退出登录
+
+命令：`xhs-kit logout`
+
+会删除本地 cookies。
+
+## （可选）MCP 模式
+
+如果你的运行环境支持 MCP（例如 Claude Desktop / Cursor），可以启动 MCP：
+
+```bash
+xhs-kit serve
+```

xhs_kit-0.1.0/.github/workflows/publish.yml

@@ -0,0 +1,55 @@
+name: Publish to PyPI
+
+on:
+  push:
+    tags:
+      - 'v*'
+  workflow_dispatch:
+
+jobs:
+  build:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+
+      - name: Set up Python
+        uses: actions/setup-python@v5
+        with:
+          python-version: "3.11"
+
+      - name: Install build dependencies
+        run: |
+          python -m pip install --upgrade pip
+          pip install build
+
+      - name: Build package
+        run: python -m build
+
+      - name: Upload artifacts
+        uses: actions/upload-artifact@v4
+        with:
+          name: dist
+          path: dist/
+
+  publish:
+    needs: build
+    runs-on: ubuntu-latest
+    environment: pypi
+    permissions:
+      id-token: write
+      contents: write
+    steps:
+      - name: Download artifacts
+        uses: actions/download-artifact@v4
+        with:
+          name: dist
+          path: dist/
+
+      - name: Publish to PyPI
+        uses: pypa/gh-action-pypi-publish@release/v1
+
+      - name: Create GitHub Release
+        uses: softprops/action-gh-release@v1
+        with:
+          generate_release_notes: true
+          files: dist/*

xhs_kit-0.1.0/.github/workflows/test.yml

@@ -0,0 +1,34 @@
+name: Test
+
+on:
+  push:
+    branches: [main]
+  pull_request:
+    branches: [main]
+
+jobs:
+  test:
+    runs-on: ubuntu-latest
+
+    steps:
+      - uses: actions/checkout@v4
+
+      - name: Set up Python 3.12
+        uses: actions/setup-python@v5
+        with:
+          python-version: "3.12"
+
+      - name: Install dependencies
+        run: |
+          python -m pip install --upgrade pip
+          pip install -e ".[dev]"
+          pip install pytest-asyncio
+          playwright install chromium
+
+      - name: Run unit tests
+        run: |
+          pytest tests/test_cookies.py tests/test_cli.py tests/test_mcp_server.py -v
+
+      - name: Run login tests (without browser)
+        run: |
+          pytest tests/test_login.py -v --ignore-glob="*browser*" || true

xhs_kit-0.1.0/.gitignore

@@ -0,0 +1,38 @@
+# Byte-compiled / optimized / DLL files
+__pycache__/
+*.py[cod]
+*$py.class
+
+# Distribution / packaging
+build/
+dist/
+*.egg-info/
+*.egg
+
+# Virtual environments
+venv/
+.venv/
+env/
+
+# IDE
+.idea/
+.vscode/
+*.swp
+*.swo
+
+# Testing
+.pytest_cache/
+.coverage
+htmlcov/
+
+# Logs
+*.log
+
+# Local config
+.env
+cookies.json
+settings.local.json
+
+# OS
+.DS_Store
+Thumbs.db

xhs_kit-0.1.0/CLAUDE.md

@@ -0,0 +1,139 @@
+# xhs-kit 项目说明
+
+## 项目概述
+
+xhs-kit 是一个小红书自动化工具，基于 Playwright 浏览器自动化框架实现，支持通过 MCP 协议与 AI 助手集成。
+
+**核心功能：**
+- 扫码登录（浏览器/二维码两种模式）
+- 发布图文、视频、文字配卡笔记
+- 搜索内容、获取推荐流
+- 点赞、收藏、评论、回复
+- 获取笔记详情、用户主页
+---
+
+## 实现思路
+
+### 1. 浏览器自动化核心
+
+基于 **Playwright** 模拟真实浏览器行为：
+
+- 创建持久化浏览器上下文（Persistent Context）
+- 复用用户数据目录和 cookies，避免重复登录
+- 模拟真实用户操作（点击、输入、滚动等）
+- 拦截和分析网络请求，获取 API 数据
+
+核心文件：`src/xhs_kit.po/browser.py`
+
+### 2. 登录机制
+
+小红书需要登录才能使用，实现了两种登录方式：
+
+**浏览器扫码登录：**
+- 弹出浏览器窗口访问小红书登录页
+- 用户扫码后自动保存 cookies
+
+**二维码登录（CLI 模式）：**
+- 通过截取登录页的二维码获取登录二维码
+- 支持终端显示二维码（需安装 zbar）
+- 支持保存二维码图片
+- 轮询检测登录状态
+
+核心文件：`src/xhs_kit.po/login.py`、`src/xhs_kit.po/cookies.py`
+
+### 3. 内容发布
+
+**图文发布：**
+- 访问创作者发布页面
+- 上传图片、填写标题和正文
+- 支持添加话题标签
+- 支持定时发布
+
+**文字配卡发布：**
+- 使用小红书自带的文字生图将文字渲染为卡片
+- 支持多页、多种样式（基础、边框、手写等）
+
+核心文件：`src/xhs_kit.po/publish.py`、`src/xhs_kit.po/text_card.py`
+
+### 4. 数据获取
+
+**搜索与推荐：**
+- 访问搜索页面，模拟用户输入关键词
+- 监听网络请求拦截搜索结果 API 响应
+- 解析返回的 JSON 数据
+
+**笔记详情、用户主页：**
+- 直接访问笔记/用户页面 URL
+- 监听 API 响应获取结构化数据
+
+核心文件：`src/xhs_kit.po/search.py`、`src/xhs_kit.po/feeds.py`、`src/xhs_kit.po/feed_detail.py`
+
+### 5. MCP 协议集成
+
+将上述功能封装为 MCP 工具：
+
+```
+MCP Server (stdio 模式)
+  ├── login_with_browser
+  ├── check_login_status
+  ├── get_login_qrcode
+  ├── publish_content
+  ├── publish_text_card
+  ├── publish_with_video
+  ├── search_feeds
+  ├── list_feeds
+  ├── get_feed_detail
+  ├── get_user_profile
+  ├── like_feed / favorite_feed
+  └── post_comment / reply_comment
+```
+
+核心文件：`src/xhs_kit.po/mcp_server.py`
+
+### 6. CLI 封装
+
+提供命令行接口 `xhs-kit`，支持所有 MCP 工具的对应命令：
+
+核心文件：`src/xhs_kit.po/cli.py`
+
+---
+
+## 开发规范
+
+### 不修改已有功能
+
+**本项目遵循「只修 bug，不改功能」原则：**
+
+- ✅ 可以修复现有 bug
+- ✅ 可以优化错误提示和日志
+- ✅ 可以改进代码结构和注释
+- ❌ 不要修改现有功能的业务逻辑
+- ❌ 不要添加未经讨论的新功能
+- ❌ 不要删除或重命名现有接口
+
+### 添加新功能的流程
+
+如果需要添加新功能：
+
+1. 先与项目维护者讨论需求和设计
+2. 确认后再进行实现
+3. 新功能应通过 MCP 工具和 CLI 双暴露
+
+### 代码结构
+
+```
+src/xhs_kit.po/
+├── browser.py        # Playwright 浏览器封装
+├── cookies.py        # Cookies 管理
+├── login.py          # 登录逻辑（浏览器/二维码）
+├── publish.py        # 发布图文/视频
+├── text_card.py      # 文字生图生成
+├── search.py         # 搜索功能
+├── feeds.py          # 推荐流获取
+├── feed_detail.py    # 笔记详情
+├── user_profile.py   # 用户主页
+├── interact.py       # 点赞/收藏/评论
+├── models.py         # Pydantic 数据模型
+├── mcp_server.py     # MCP 服务入口
+└── cli.py            # 命令行入口
+```

xhs_kit-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2024
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.