xhs-note-extractor 0.1.dev2__py3-none-any.whl

xhs_note_extractor/__init__.py

@@ -0,0 +1,50 @@
+"""
+小红书笔记提取器包
+
+这是一个用于从小红书URL中提取笔记信息的Python包。
+支持URL解析、设备连接、页面跳转和笔记内容提取。
+
+主要功能：
+- URL解析和转换（支持标准格式和xhsdiscover协议格式）
+- 设备连接和自动化操作
+- 笔记内容提取（正文、图片、点赞数等）
+- 结构化数据返回
+
+示例:
+    >>> from xhs_note_extractor import XHSNoteExtractor
+    >>> extractor = XHSNoteExtractor()
+    >>> data = extractor.extract_note_data(url="https://www.xiaohongshu.com/explore/...")
+    >>> print(data['content'])
+"""
+
+__version__ = "1.0.0"
+__author__ = "JoyCode Agent"
+__email__ = "agent@joycode.com"
+
+from .extractor import XHSNoteExtractor
+from .utils import (
+    DeviceManager,
+    ElementFinder,
+    DataFormatter,
+    NetworkUtils,
+    FileManager,
+    XHSUtils,
+    connect_device,
+    format_like_count,
+    extract_image_urls_from_html,
+    fetch_html
+)
+
+__all__ = [
+    "XHSNoteExtractor",
+    "DeviceManager",
+    "ElementFinder",
+    "DataFormatter",
+    "NetworkUtils",
+    "FileManager",
+    "XHSUtils",
+    "connect_device",
+    "format_like_count",
+    "extract_image_urls_from_html",
+    "fetch_html",
+]

xhs_note_extractor/_version.py

@@ -0,0 +1,34 @@
+# file generated by setuptools-scm
+# don't change, don't track in version control
+
+__all__ = [
+    "__version__",
+    "__version_tuple__",
+    "version",
+    "version_tuple",
+    "__commit_id__",
+    "commit_id",
+]
+
+TYPE_CHECKING = False
+if TYPE_CHECKING:
+    from typing import Tuple
+    from typing import Union
+
+    VERSION_TUPLE = Tuple[Union[int, str], ...]
+    COMMIT_ID = Union[str, None]
+else:
+    VERSION_TUPLE = object
+    COMMIT_ID = object
+
+version: str
+__version__: str
+__version_tuple__: VERSION_TUPLE
+version_tuple: VERSION_TUPLE
+commit_id: COMMIT_ID
+__commit_id__: COMMIT_ID
+
+__version__ = version = '0.1.dev2'
+__version_tuple__ = version_tuple = (0, 1, 'dev2')
+
+__commit_id__ = commit_id = 'g1aa72014c'

xhs_note_extractor/cli.py

@@ -0,0 +1,98 @@
+#!/usr/bin/env python3
+"""
+Command Line Interface for XHS Note Extractor
+"""
+
+import argparse
+import sys
+from pathlib import Path
+
+from .extractor import XHSNoteExtractor
+from .utils import NetworkUtils
+
+
+def main():
+    """Main entry point for the CLI application."""
+    parser = argparse.ArgumentParser(
+        description="Extract Xiaohongshu (Little Red Book) note data from URLs"
+    )
+    parser.add_argument(
+        "url",
+        help="Xiaohongshu note URL to extract data from"
+    )
+    parser.add_argument(
+        "-o", "--output",
+        help="Output file path (default: stdout)"
+    )
+    parser.add_argument(
+        "-f", "--format",
+        choices=["json", "csv"],
+        default="json",
+        help="Output format (default: json)"
+    )
+    parser.add_argument(
+        "-v", "--verbose",
+        action="store_true",
+        help="Enable verbose output"
+    )
+    
+    args = parser.parse_args()
+    
+    # Validate URL
+    if not NetworkUtils.is_valid_xhs_url(args.url):
+        print(f"Error: Invalid Xiaohongshu URL: {args.url}", file=sys.stderr)
+        sys.exit(1)
+    
+    try:
+        if args.verbose:
+            print(f"Extracting data from: {args.url}")
+        
+        # Initialize extractor
+        extractor = XHSNoteExtractor()
+        
+        # Extract note data
+        note_data = extractor.extract_note(args.url)
+        
+        if not note_data:
+            print("Error: Failed to extract note data", file=sys.stderr)
+            sys.exit(1)
+        
+        # Format output
+        if args.format == "json":
+            import json
+            output = json.dumps(note_data, ensure_ascii=False, indent=2)
+        else:  # csv
+            import csv
+            from io import StringIO
+            
+            # Convert to CSV format (simplified)
+            output_buffer = StringIO()
+            writer = csv.writer(output_buffer)
+            
+            # Write headers
+            writer.writerow(["Field", "Value"])
+            
+            # Write data rows
+            for key, value in note_data.items():
+                if isinstance(value, (list, dict)):
+                    value = str(value)
+                writer.writerow([key, value])
+            
+            output = output_buffer.getvalue()
+        
+        # Output result
+        if args.output:
+            output_path = Path(args.output)
+            output_path.write_text(output, encoding='utf-8')
+            if args.verbose:
+                print(f"Output saved to: {output_path}")
+        else:
+            print(output)
+            
+    except Exception as e:
+        print(f"Error: {e}", file=sys.stderr)
+        sys.exit(1)
+
+
+if __name__ == "__main__":
+    main()

xhs_note_extractor/extractor.py

@@ -0,0 +1,412 @@
+"""
+小红书笔记提取器模块
+
+该模块提供了从小红书URL中提取笔记信息的功能，包括：
+- URL解析和转换
+- 设备连接和页面跳转
+- 笔记内容提取（正文、图片、点赞数等）
+- 结构化数据返回
+
+作者: JoyCode Agent
+版本: 1.0.0
+"""
+
+import uiautomator2 as u2
+import time
+import re
+import requests
+import logging
+from typing import Dict, List, Optional, Union
+from urllib.parse import urlparse, parse_qs
+
+# 配置日志
+logging.basicConfig(
+    level=logging.INFO,
+    format='%(asctime)s - %(name)s - %(levelname)s - %(message)s'
+)
+logger = logging.getLogger(__name__)
+
+
+class XHSNoteExtractor:
+    """
+    小红书笔记提取器类
+    
+    提供了从小红书URL中提取笔记信息的完整功能，
+    包括URL解析、设备连接、页面跳转和笔记内容提取。
+    """
+    
+    def __init__(self, device_serial: Optional[str] = None):
+        """
+        初始化小红书笔记提取器
+        
+        Args:
+            device_serial (str, optional): 设备序列号，如果为None则自动连接可用设备
+            
+        Raises:
+            RuntimeError: 当没有可用设备时抛出异常
+        """
+        self.device = None
+        self.device_serial = device_serial
+        if not self.connect_device():
+            raise RuntimeError("未找到可用的Android设备，请连接设备后再试")
+    
+    def connect_device(self) -> bool:
+        """
+        连接设备
+        
+        Returns:
+            bool: 是否成功连接设备
+        """
+        try:
+            if self.device_serial:
+                self.device = u2.connect(self.device_serial)
+            else:
+                self.device = u2.connect()
+            logger.info(f"✓ 已连接设备: {self.device.serial}")
+            return True
+        except Exception as e:
+            logger.error(f"✗ 设备连接失败: {e}")
+            return False
+    
+    @staticmethod
+    def parse_xhs_url(url: str) -> Dict[str, str]:
+        """
+        解析小红书URL，提取note_id和xsec_token
+        
+        Args:
+            url (str): 小红书URL，支持标准格式或xhsdiscover协议格式
+            
+        Returns:
+            Dict[str, str]: 包含note_id和xsec_token的字典
+            
+        Raises:
+            ValueError: 当URL格式不正确时抛出异常
+        """
+        # 处理xhsdiscover协议格式
+        if url.startswith("xhsdiscover://"):
+            # 提取note_id
+            note_id_match = re.search(r'item/([^?]+)', url)
+            if not note_id_match:
+                raise ValueError("无法从xhsdiscover URL中提取note_id")
+            
+            note_id = note_id_match.group(1)
+            
+            # 尝试从open_url参数中提取原始URL
+            open_url_match = re.search(r'open_url=([^&]+)', url)
+            xsec_token = ""
+            if open_url_match:
+                open_url = open_url_match.group(1)
+                # 解码URL
+                import urllib.parse
+                decoded_url = urllib.parse.unquote(open_url)
+                # 从原始URL中提取xsec_token
+                token_match = re.search(r'xsec_token=([^&]+)', decoded_url)
+                if token_match:
+                    xsec_token = token_match.group(1)
+            
+            return {
+                "note_id": note_id,
+                "xsec_token": xsec_token,
+                "original_url": url
+            }
+        
+        # 处理标准URL格式
+        elif "xiaohongshu.com" in url:
+            parsed_url = urlparse(url)
+            path_parts = parsed_url.path.strip('/').split('/')
+            
+            # 查找explore部分和note_id
+            if 'explore' in path_parts:
+                explore_index = path_parts.index('explore')
+                if explore_index + 1 < len(path_parts):
+                    note_id = path_parts[explore_index + 1]
+                else:
+                    raise ValueError("URL中缺少note_id")
+            else:
+                raise ValueError("URL格式不正确，缺少/explore/路径")
+            
+            # 提取查询参数中的xsec_token
+            query_params = parse_qs(parsed_url.query)
+            xsec_token = query_params.get('xsec_token', [''])[0]
+            
+            return {
+                "note_id": note_id,
+                "xsec_token": xsec_token,
+                "original_url": url
+            }
+        
+        else:
+            raise ValueError("不支持的URL格式")
+    
+    @staticmethod
+    def validate_url(url: str) -> bool:
+        """
+        验证URL是否是有效的小红书URL
+        
+        Args:
+            url (str): 要验证的URL
+            
+        Returns:
+            bool: URL是否有效
+        """
+        try:
+            XHSNoteExtractor.parse_xhs_url(url)
+            return True
+        except ValueError:
+            return False
+    
+    @staticmethod
+    def convert_to_xhsdiscover_format(note_id: str, xsec_token: str = "") -> str:
+        """
+        将note_id和xsec_token转换为xhsdiscover协议格式
+        
+        Args:
+            note_id (str): 笔记ID
+            xsec_token (str): xsec_token参数
+            
+        Returns:
+            str: xhsdiscover协议格式的URL
+        """
+        if xsec_token:
+            original_url = f"http://www.xiaohongshu.com/explore/{note_id}?xsec_token={xsec_token}&xsec_source=pc_feed"
+            encoded_url = requests.utils.quote(original_url)
+            return f"xhsdiscover://item/{note_id}?open_url={encoded_url}"
+        else:
+            return f"xhsdiscover://item/{note_id}"
+    
+    def extract_note_data(self, url: Optional[str] = None, note_id: Optional[str] = None, 
+                         xsec_token: Optional[str] = None) -> Dict[str, Union[str, List[str]]]:
+        """
+        从小红书笔记中提取数据
+        
+        Args:
+            url (str, optional): 小红书URL，如果提供则会解析其中的note_id和xsec_token
+            note_id (str, optional): 笔记ID，如果提供则直接使用
+            xsec_token (str, optional): xsec_token参数
+            
+        Returns:
+            Dict[str, Union[str, List[str]]]: 包含笔记数据的字典，格式与xhs_utils.get_detail_data()一致
+            
+        Raises:
+            RuntimeError: 当设备未连接时抛出异常
+            Exception: 当提取过程中出现错误时抛出异常
+        """
+        # 如果提供了URL，则先解析它（验证URL有效性）
+        if url:
+            parsed_data = self.parse_xhs_url(url)
+            note_id = parsed_data["note_id"]
+            xsec_token = parsed_data["xsec_token"]
+            
+        # 检查设备是否连接
+        if self.device is None:
+            raise RuntimeError("设备未连接，请先连接设备")
+        
+        # 构建跳转URL
+        jump_url = self.convert_to_xhsdiscover_format(note_id, xsec_token)
+        
+        logger.info(f"正在尝试跳转至笔记: {note_id}")
+        
+        try:
+            # 发起跳转
+            self.device.open_url(jump_url)
+            logger.info("✓ 已发送跳转指令，等待页面加载...")
+            
+            # 使用现有的xhs_utils功能提取数据
+            data = self._get_detail_data()
+            
+            logger.info(f"✓ 成功提取笔记数据，点赞数: {data['likes']}, 图片数: {len(data['image_urls'])}")
+            
+            return data
+            
+        except Exception as e:
+            logger.error(f"✗ 提取笔记数据失败: {e}")
+            raise
+    
+    def _get_detail_data(self) -> Dict[str, Union[str, List[str]]]:
+        """
+        从当前已经打开的小红书详情页提取完整正文、图片和点赞数。
+        这是xhs_utils.get_detail_data的封装版本，保持相同功能。
+        
+        Returns:
+            Dict[str, Union[str, List[str]]]: 包含笔记数据的字典
+        """
+        logger.info("🔍 进入深度提取模式...")
+        
+        # 1. 验证是否进入详情页 (增加重试和多关键词检测)
+        detail_loaded = False
+        detail_keywords = ["说点什么", "写评论", "写点什么", "收藏", "点赞", "评论", "分享", "发弹幕"]
+        for i in range(8):
+            if any(self.device(textContains=kw).exists or self.device(descriptionContains=kw).exists for kw in detail_keywords):
+                detail_loaded = True
+                break
+            if i == 4:
+                # 可能是视频，点击屏幕中心尝试激活 UI
+                self.device.click(540, 900)
+            time.sleep(1)
+        
+        if not detail_loaded:
+            logger.warning("⚠ 警告：详情页特征未发现，提取可能不完整")
+
+        # 2. 处理"展开"按钮以获取完整长文
+        for btn_text in ["展开", "查看全部", "全文"]:
+            btn = self.device(text=btn_text)
+            if btn.exists:
+                logger.info(f"[Action] 点击'{btn_text}'")
+                btn.click()
+                time.sleep(1)
+
+        # 3. 提取正文 (多策略拼接)
+        content = ""
+        # 策略 A: 尝试常见 ID
+        desc_el = self.device(resourceIdMatches=".*desc.*|.*content.*")
+        if desc_el.exists:
+            content = desc_el.get_text()
+        
+        # 策略 B: 文本容器遍历 (更稳健)
+        if not content or len(content) < 20:
+            texts = []
+            for el in self.device(className="android.widget.TextView"):
+                try:
+                    t = el.get_text()
+                    if not t or len(t) < 3: continue
+                    # 过滤坐标：只取屏幕中间内容区
+                    b = el.info.get('bounds', {})
+                    if 200 < b.get('top', 0) < 2100:
+                        if not any(k in t for k in ['收藏', '点赞', '评论', '分享', '发布于', '说点什么', '条评论']):
+                            texts.append(t)
+                except: continue
+            content = "\n".join(texts)
+
+        # 4. 提取图片 (通过分享链接解析高清图)
+        image_urls = []
+        try:
+            share_btn = self.device(description="分享")
+            if share_btn.exists:
+                share_btn.click()
+                time.sleep(1.5)
+                copy_link_btn = self.device(text="复制链接")
+                if copy_link_btn.exists:
+                    copy_link_btn.click()
+                    time.sleep(0.5)
+                    share_link = self.device.clipboard
+                    if "http" in str(share_link):
+                        image_urls = self._fetch_web_images(share_link)
+                else:
+                    self.device.press("back")
+        except Exception as e:
+            logger.warning(f"⚠ 图片提取异常: {e}")
+
+        # 5. 提取点赞数
+        likes = "0"
+        try:
+            for el in self.device(className="android.widget.TextView"):
+                txt = el.get_text() or ""
+                if any(c.isdigit() for c in txt):
+                    b = el.info.get('bounds', {})
+                    if b.get('top', 0) > 2000 and b.get('left', 0) > 500:
+                        likes = ''.join(c for c in txt if c.isdigit() or c in ['.', 'w', 'W'])
+                        if likes: break
+        except: pass
+
+        return {
+            "content": content,
+            "image_urls": image_urls,
+            "likes": likes
+        }
+    
+    def _fetch_web_images(self, url: str) -> List[str]:
+        """
+        从分享链接中解析图片地址
+        
+        Args:
+            url (str): 分享链接URL
+            
+        Returns:
+            List[str]: 图片URL列表
+        """
+        try:
+            headers = {"User-Agent": "Mozilla/5.0 (iPhone; CPU iPhone OS 14_8 like Mac OS X) AppleWebKit/605.1.15 (KHTML, like Gecko) Version/14.1.2 Mobile/15E148 Safari/604.1"}
+            res = requests.get(url, headers=headers, timeout=10)
+            html = res.text
+            img_patterns = [
+                r'property="og:image" content="(https://[^"]+)"',
+                r'"url":"(https://sns-img-[^"]+)"',
+                r'"url":"(https://sns-img-qc\.xhscdn\.com/[^"]+)"'
+            ]
+            found = []
+            for pattern in img_patterns:
+                matches = re.findall(pattern, html)
+                for m in matches:
+                    clean_url = m.replace('\\u002F', '/')
+                    if clean_url not in found: found.append(clean_url)
+            return found
+        except:
+            return []
+    
+    def save_note_data(self, data: Dict[str, Union[str, List[str]]], 
+                      filename: str = "last_extracted_note.txt", 
+                      note_url: str = "") -> None:
+        """
+        保存笔记数据到文件
+        
+        Args:
+            data (Dict[str, Union[str, List[str]]]): 笔记数据
+            filename (str): 保存文件名
+            note_url (str): 笔记URL
+        """
+        try:
+            with open(filename, "w", encoding="utf-8") as f:
+                f.write("=" * 50 + "\n")
+                f.write("【小红书笔记提取结果】\n")
+                f.write("=" * 50 + "\n")
+                if note_url:
+                    f.write(f"笔记URL: {note_url}\n")
+                    f.write("=" * 50 + "\n")
+                f.write(f"点赞数: {data['likes']}\n")
+                f.write(f"图片数: {len(data['image_urls'])}\n")
+                f.write("=" * 50 + "\n")
+                f.write("【正文内容】\n")
+                f.write(data['content'])
+                f.write("\n" + "=" * 50 + "\n")
+                if data['image_urls']:
+                    f.write("【图片URL】\n")
+                    for i, url in enumerate(data['image_urls'], 1):
+                        f.write(f"{i}. {url}\n")
+                    f.write("=" * 50 + "\n")
+            
+            logger.info(f"✓ 笔记数据已保存到: {filename}")
+        except Exception as e:
+            logger.error(f"✗ 保存笔记数据失败: {e}")
+            raise
+
+
+def extract_note_from_url(url: str, device_serial: Optional[str] = None) -> Dict[str, Union[str, List[str]]]:
+    """
+    便捷函数：直接从URL提取笔记数据
+    
+    Args:
+        url (str): 小红书笔记URL
+        device_serial (str, optional): 设备序列号
+        
+    Returns:
+        Dict[str, Union[str, List[str]]]: 笔记数据
+    """
+    extractor = XHSNoteExtractor(device_serial=device_serial)
+    return extractor.extract_note_data(url=url)
+
+
+def convert_url_format(url: str) -> str:
+    """
+    便捷函数：转换URL格式
+    
+    Args:
+        url (str): 输入URL
+        
+    Returns:
+        str: 转换后的xhsdiscover协议格式URL
+    """
+    parsed_data = XHSNoteExtractor.parse_xhs_url(url)
+    return XHSNoteExtractor.convert_to_xhsdiscover_format(
+        parsed_data["note_id"], 
+        parsed_data["xsec_token"]
+    )

xhs_note_extractor/utils.py

@@ -0,0 +1,493 @@
+"""
+小红书工具模块
+
+该模块提供了小红书相关的辅助功能，包括：
+- 设备管理和连接
+- 页面操作和元素查找
+- 数据格式化和验证
+- 错误处理和日志记录
+
+作者: JoyCode Agent
+版本: 1.0.0
+"""
+
+import uiautomator2 as u2
+import time
+import re
+import requests
+import logging
+from typing import Dict, List, Optional, Union, Any
+from functools import wraps
+
+# 配置日志
+logging.basicConfig(
+    level=logging.INFO,
+    format='%(asctime)s - %(name)s - %(levelname)s - %(message)s'
+)
+logger = logging.getLogger(__name__)
+
+
+def retry(max_attempts: int = 3, delay: float = 1.0, backoff: float = 2.0):
+    """
+    重试装饰器
+    
+    Args:
+        max_attempts (int): 最大重试次数
+        delay (float): 初始延迟时间(秒)
+        backoff (float): 延迟时间倍增因子
+    """
+    def decorator(func):
+        @wraps(func)
+        def wrapper(*args, **kwargs):
+            attempt = 0
+            current_delay = delay
+            
+            while attempt < max_attempts:
+                try:
+                    return func(*args, **kwargs)
+                except Exception as e:
+                    attempt += 1
+                    if attempt >= max_attempts:
+                        logger.error(f"函数 {func.__name__} 在 {max_attempts} 次尝试后仍然失败: {e}")
+                        raise
+                    
+                    logger.warning(f"函数 {func.__name__} 第 {attempt} 次尝试失败: {e}，{current_delay}秒后重试...")
+                    time.sleep(current_delay)
+                    current_delay *= backoff
+            
+            return None
+        return wrapper
+    return decorator
+
+
+class DeviceManager:
+    """设备管理类"""
+    
+    @staticmethod
+    def connect_device(device_serial: Optional[str] = None) -> u2.Device:
+        """
+        连接设备
+        
+        Args:
+            device_serial (str, optional): 设备序列号
+            
+        Returns:
+            u2.Device: 设备对象
+        """
+        try:
+            if device_serial:
+                device = u2.connect(device_serial)
+                logger.info(f"✓ 已连接指定设备: {device.serial}")
+            else:
+                device = u2.connect()
+                logger.info(f"✓ 已连接设备: {device.serial}")
+            return device
+        except Exception as e:
+            logger.error(f"✗ 设备连接失败: {e}")
+            raise
+    
+    @staticmethod
+    def check_device_status(device: u2.Device) -> Dict[str, Any]:
+        """
+        检查设备状态
+        
+        Args:
+            device (u2.Device): 设备对象
+            
+        Returns:
+            Dict[str, Any]: 设备状态信息
+        """
+        try:
+            info = device.info
+            return {
+                "serial": device.serial,
+                "status": "connected",
+                "sdk_version": info.get('sdkInt', 'unknown'),
+                "screen_size": f"{info.get('displayWidth', 0)}x{info.get('displayHeight', 0)}",
+                "battery": info.get('battery', {})
+            }
+        except Exception as e:
+            logger.error(f"✗ 获取设备状态失败: {e}")
+            return {"status": "error", "error": str(e)}
+
+
+class ElementFinder:
+    """元素查找器类"""
+    
+    def __init__(self, device: u2.Device):
+        """
+        初始化元素查找器
+        
+        Args:
+            device (u2.Device): 设备对象
+        """
+        self.device = device
+    
+    @retry(max_attempts=3, delay=0.5)
+    def find_element_by_text(self, text: str, timeout: float = 5.0) -> Optional[u2.UiObject]:
+        """
+        通过文本查找元素
+        
+        Args:
+            text (str): 要查找的文本
+            timeout (float): 超时时间(秒)
+            
+        Returns:
+            Optional[u2.UiObject]: 找到的元素对象，未找到返回None
+        """
+        element = self.device(text=text)
+        if element.wait(timeout=timeout):
+            return element
+        return None
+    
+    @retry(max_attempts=3, delay=0.5)
+    def find_element_by_description(self, description: str, timeout: float = 5.0) -> Optional[u2.UiObject]:
+        """
+        通过描述查找元素
+        
+        Args:
+            description (str): 要查找的描述
+            timeout (float): 超时时间(秒)
+            
+        Returns:
+            Optional[u2.UiObject]: 找到的元素对象，未找到返回None
+        """
+        element = self.device(description=description)
+        if element.wait(timeout=timeout):
+            return element
+        return None
+    
+    @retry(max_attempts=3, delay=0.5)
+    def find_element_by_resource_id(self, resource_id: str, timeout: float = 5.0) -> Optional[u2.UiObject]:
+        """
+        通过资源ID查找元素
+        
+        Args:
+            resource_id (str): 资源ID
+            timeout (float): 超时时间(秒)
+            
+        Returns:
+            Optional[u2.UiObject]: 找到的元素对象，未找到返回None
+        """
+        element = self.device(resourceId=resource_id)
+        if element.wait(timeout=timeout):
+            return element
+        return None
+    
+    def wait_for_element(self, condition_func, timeout: float = 10.0, check_interval: float = 0.5) -> bool:
+        """
+        等待元素出现
+        
+        Args:
+            condition_func: 条件函数，返回True表示找到元素
+            timeout (float): 超时时间(秒)
+            check_interval (float): 检查间隔(秒)
+            
+        Returns:
+            bool: 是否找到元素
+        """
+        start_time = time.time()
+        while time.time() - start_time < timeout:
+            if condition_func():
+                return True
+            time.sleep(check_interval)
+        return False
+
+
+class DataFormatter:
+    """数据格式化类"""
+    
+    @staticmethod
+    def format_like_count(like_text: str) -> str:
+        """
+        格式化点赞数字符串
+        
+        Args:
+            like_text (str): 原始点赞数字符串
+            
+        Returns:
+            str: 格式化后的点赞数
+        """
+        if not like_text:
+            return "0"
+        
+        # 提取数字和可能的单位
+        match = re.search(r'([\d.]+)\s*([wW万]?)\s*', str(like_text))
+        if match:
+            number = match.group(1)
+            unit = match.group(2).lower()
+            
+            # 处理单位转换
+            if unit in ['w', '万']:
+                try:
+                    num = float(number)
+                    return str(int(num * 10000))
+                except ValueError:
+                    return number
+            else:
+                return number
+        
+        # 如果没有匹配到模式，返回原始文本中的数字
+        digits = ''.join(c for c in str(like_text) if c.isdigit())
+        return digits if digits else "0"
+    
+    @staticmethod
+    def extract_image_urls_from_html(html: str) -> List[str]:
+        """
+        从HTML中提取图片URL
+        
+        Args:
+            html (str): HTML内容
+            
+        Returns:
+            List[str]: 图片URL列表
+        """
+        img_patterns = [
+            r'property="og:image" content="(https://[^"]+)"',
+            r'"url":"(https://sns-img-[^"]+)"',
+            r'"url":"(https://sns-img-qc\.xhscdn\.com/[^"]+)"',
+            r'data-src="(https://[^"]+)"',
+            r'src="(https://[^"]+\.(?:jpg|jpeg|png|gif))"'
+        ]
+        
+        found_urls = []
+        for pattern in img_patterns:
+            matches = re.findall(pattern, html)
+            for match in matches:
+                clean_url = match.replace('\\u002F', '/').replace('\\/', '/')
+                if clean_url not in found_urls:
+                    found_urls.append(clean_url)
+        
+        return found_urls
+    
+    @staticmethod
+    def clean_text_content(text: str) -> str:
+        """
+        清理文本内容
+        
+        Args:
+            text (str): 原始文本
+            
+        Returns:
+            str: 清理后的文本
+        """
+        if not text:
+            return ""
+        
+        # 移除多余的空白字符
+        text = re.sub(r'\s+', ' ', text)
+        # 移除特殊字符
+        text = re.sub(r'[^\w\s\u4e00-\u9fff，。！？；：""''（）【】]', '', text)
+        # 移除前后空格
+        text = text.strip()
+        
+        return text
+
+
+class NetworkUtils:
+    """网络工具类"""
+    
+    @staticmethod
+    @retry(max_attempts=3, delay=1.0)
+    def fetch_html(url: str, headers: Optional[Dict[str, str]] = None, timeout: int = 10) -> str:
+        """
+        获取网页HTML内容
+        
+        Args:
+            url (str): 目标URL
+            headers (dict, optional): 请求头
+            timeout (int): 超时时间(秒)
+            
+        Returns:
+            str: HTML内容
+            
+        Raises:
+            requests.RequestException: 请求失败时抛出异常
+        """
+        default_headers = {
+            "User-Agent": "Mozilla/5.0 (iPhone; CPU iPhone OS 14_8 like Mac OS X) AppleWebKit/605.1.15 (KHTML, like Gecko) Version/14.1.2 Mobile/15E148 Safari/604.1"
+        }
+        
+        if headers:
+            default_headers.update(headers)
+        
+        response = requests.get(url, headers=default_headers, timeout=timeout)
+        response.raise_for_status()
+        
+        return response.text
+    
+    @staticmethod
+    def is_valid_url(url: str) -> bool:
+        """
+        验证URL是否有效
+        
+        Args:
+            url (str): 要验证的URL
+            
+        Returns:
+            bool: URL是否有效
+        """
+        try:
+            from urllib.parse import urlparse
+            result = urlparse(url)
+            return all([result.scheme, result.netloc])
+        except Exception:
+            return False
+    
+    @staticmethod
+    def is_valid_xhs_url(url: str) -> bool:
+        """
+        验证小红书URL是否有效
+        
+        Args:
+            url (str): 要验证的小红书笔记URL
+            
+        Returns:
+            bool: URL是否有效的小红书笔记URL
+        """
+        try:
+            from urllib.parse import urlparse
+            result = urlparse(url)
+            
+            # 检查是否为有效的URL
+            if not all([result.scheme, result.netloc]):
+                return False
+            
+            # 检查是否为小红书域名
+            valid_domains = ['xiaohongshu.com', 'www.xiaohongshu.com', 'm.xiaohongshu.com']
+            if result.netloc not in valid_domains:
+                return False
+            
+            # 检查是否为笔记详情页URL
+            if '/explore/' not in url and '/discovery/item/' not in url:
+                return False
+            
+            return True
+        except Exception:
+            return False
+
+
+class FileManager:
+    """文件管理类"""
+    
+    @staticmethod
+    def save_data_to_file(data: str, filename: str, encoding: str = "utf-8") -> bool:
+        """
+        将数据保存到文件
+        
+        Args:
+            data (str): 要保存的数据
+            filename (str): 文件名
+            encoding (str): 文件编码
+            
+        Returns:
+            bool: 是否保存成功
+        """
+        try:
+            with open(filename, "w", encoding=encoding) as f:
+                f.write(data)
+            logger.info(f"✓ 数据已保存到: {filename}")
+            return True
+        except Exception as e:
+            logger.error(f"✗ 保存数据失败: {e}")
+            return False
+    
+    @staticmethod
+    def load_data_from_file(filename: str, encoding: str = "utf-8") -> Optional[str]:
+        """
+        从文件加载数据
+        
+        Args:
+            filename (str): 文件名
+            encoding (str): 文件编码
+            
+        Returns:
+            Optional[str]: 文件内容，失败返回None
+        """
+        try:
+            with open(filename, "r", encoding=encoding) as f:
+                return f.read()
+        except Exception as e:
+            logger.error(f"✗ 加载数据失败: {e}")
+            return None
+
+
+class XHSUtils:
+    """小红书工具类 - 兼容原有接口"""
+    
+    @staticmethod
+    def get_detail_data(device: u2.Device) -> Dict[str, Union[str, List[str]]]:
+        """
+        从当前已经打开的小红书详情页提取完整正文、图片和点赞数。
+        这是为了向后兼容而保留的方法，实际功能已迁移到extractor.py中。
+        
+        Args:
+            device (u2.Device): 设备对象
+            
+        Returns:
+            Dict[str, Union[str, List[str]]]: 包含笔记数据的字典
+        """
+        # 导入extractor模块中的方法
+        from .extractor import XHSNoteExtractor
+        
+        # 创建临时提取器实例
+        extractor = XHSNoteExtractor.__new__(XHSNoteExtractor)
+        extractor.device = device
+        
+        # 调用提取方法
+        return extractor._get_detail_data()
+
+
+# 便捷函数
+def connect_device(device_serial: Optional[str] = None) -> u2.Device:
+    """
+    便捷函数：连接设备
+    
+    Args:
+        device_serial (str, optional): 设备序列号
+        
+    Returns:
+        u2.Device: 设备对象
+    """
+    return DeviceManager.connect_device(device_serial)
+
+
+def format_like_count(like_text: str) -> str:
+    """
+    便捷函数：格式化点赞数
+    
+    Args:
+        like_text (str): 原始点赞数字符串
+        
+    Returns:
+        str: 格式化后的点赞数
+    """
+    return DataFormatter.format_like_count(like_text)
+
+
+def extract_image_urls_from_html(html: str) -> List[str]:
+    """
+    便捷函数：从HTML中提取图片URL
+    
+    Args:
+        html (str): HTML内容
+        
+    Returns:
+        List[str]: 图片URL列表
+    """
+    return DataFormatter.extract_image_urls_from_html(html)
+
+
+def fetch_html(url: str, headers: Optional[Dict[str, str]] = None, timeout: int = 10) -> str:
+    """
+    便捷函数：获取网页HTML内容
+    
+    Args:
+        url (str): 目标URL
+        headers (dict, optional): 请求头
+        timeout (int): 超时时间(秒)
+        
+    Returns:
+        str: HTML内容
+    """
+    return NetworkUtils.fetch_html(url, headers, timeout)

xhs_note_extractor-0.1.dev2.dist-info/METADATA

@@ -0,0 +1,234 @@
+Metadata-Version: 2.4
+Name: xhs-note-extractor
+Version: 0.1.dev2
+Summary: A Python package for extracting Xiaohongshu (Little Red Book) note data from URLs
+Author-email: JoyCode Agent <agent@joycode.com>
+License: MIT
+Project-URL: Homepage, https://github.com/yehao20/xhs-note-extractor
+Project-URL: Repository, https://github.com/yehao20/xhs-note-extractor
+Project-URL: Documentation, https://github.com/yehao20/xhs-note-extractor/blob/main/README.md
+Project-URL: Issues, https://github.com/yehao20/xhs-note-extractor/issues
+Keywords: xiaohongshu,little-red-book,web-scraping,automation,uiautomator
+Classifier: Development Status :: 4 - Beta
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.8
+Classifier: Programming Language :: Python :: 3.9
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Topic :: Software Development :: Libraries :: Python Modules
+Classifier: Topic :: Internet :: WWW/HTTP
+Classifier: Topic :: Utilities
+Requires-Python: >=3.8
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: uiautomator2>=2.16.17
+Requires-Dist: requests>=2.25.0
+Provides-Extra: dev
+Requires-Dist: pytest>=6.0; extra == "dev"
+Requires-Dist: pytest-cov>=2.0; extra == "dev"
+Requires-Dist: black>=21.0; extra == "dev"
+Requires-Dist: flake8>=3.8; extra == "dev"
+Dynamic: license-file
+
+# 小红书笔记提取器 (Xiaohongshu Note Extractor)
+
+一个用于从小红书提取笔记数据的Python工具，支持命令行界面和编程接口。
+
+## 功能特性
+
+- 🔍 从小红书笔记URL提取详细数据
+- 📊 支持JSON和CSV输出格式
+- 🖥️ 命令行界面支持
+- 🔧 可配置的设备连接选项
+- 📱 Android设备集成（通过uiautomator2）
+- 🛡️ 优雅的错误处理和设备状态检查
+
+## 安装
+
+### 从源码安装
+
+```bash
+# 克隆仓库
+git clone <repository-url>
+cd xhs-note-extractor
+
+# 安装依赖
+pip install -r requirements.txt
+
+# 安装包（开发模式）
+pip install -e .
+```
+
+### 依赖要求
+
+- Python 3.7+
+- Android设备（用于完整功能）
+- ADB工具
+
+## 使用方法
+
+### 命令行界面（CLI）
+
+安装完成后，可以直接使用 `xhs-extract` 命令：
+
+```bash
+# 提取笔记并输出到控制台（JSON格式）
+xhs-extract https://www.xiaohongshu.com/explore/note_id
+
+# 保存到文件
+xhs-extract https://www.xiaohongshu.com/explore/note_id -o note_data.json
+
+# 输出CSV格式
+xhs-extract https://www.xiaohongshu.com/explore/note_id -f csv -o note_data.csv
+
+# 启用详细输出模式
+xhs-extract https://www.xiaohongshu.com/explore/note_id -v
+
+# 查看帮助
+xhs-extract --help
+```
+
+### 编程接口
+
+```python
+from xhs_note_extractor import XHSNoteExtractor
+import json
+
+# 创建提取器实例
+extractor = XHSNoteExtractor()
+
+# 检查设备连接状态
+if extractor.is_device_connected():
+    # 提取笔记数据
+    note_data = extractor.extract_note_data("https://www.xiaohongshu.com/explore/note_id")
+    print(json.dumps(note_data, ensure_ascii=False, indent=2))
+else:
+    print("请连接Android设备并启用USB调试")
+```
+
+## 输出数据结构
+
+提取的数据包含以下字段：
+
+```json
+{
+  "title": "笔记标题",
+  "content": "笔记完整内容",
+  "author": {
+    "nickname": "作者昵称",
+    "user_id": "用户ID"
+  },
+  "likes": 100,
+  "collects": 50,
+  "comments": 25,
+  "shares": 10,
+  "image_urls": [
+    "图片URL1",
+    "图片URL2"
+  ],
+  "video_url": "视频URL（如果有）",
+  "tags": ["标签1", "标签2"],
+  "publish_time": "发布时间",
+  "note_id": "笔记ID"
+}
+```
+
+## 设备连接
+
+### 连接Android设备
+
+1. 在Android设备上启用**开发者选项**和**USB调试**
+2. 通过USB连接设备到电脑
+3. 授权USB调试权限（设备上会弹出提示）
+
+### 检查设备状态
+
+```bash
+# 使用ADB检查设备
+adb devices
+
+# 使用CLI工具检查
+xhs-extract --help  # 会显示设备连接状态
+```
+
+## 故障排除
+
+### 设备连接问题
+
+如果CLI工具提示设备未连接：
+
+1. 检查USB连接是否正常
+2. 确认已在设备上启用USB调试
+3. 确认已授权USB调试权限
+4. 尝试重新插拔USB线缆
+5. 重启ADB服务：
+   ```bash
+   adb kill-server
+   adb start-server
+   ```
+
+### 权限问题
+
+在Linux/Mac上，可能需要为ADB添加权限：
+
+```bash
+sudo adb kill-server
+sudo adb start-server
+```
+
+## 示例
+
+查看 `examples/basic_usage.py` 文件获取更多使用示例：
+
+```bash
+# 运行示例
+python examples/basic_usage.py
+```
+
+## 开发
+
+### 项目结构
+
+```
+xhs-note-extractor/
+├── xhs_note_extractor/
+│   ├── __init__.py
+│   ├── cli.py          # 命令行界面
+│   ├── extractor.py    # 核心提取器
+│   └── utils.py        # 工具函数
+├── examples/
+│   └── basic_usage.py  # 使用示例
+├── tests/
+├── requirements.txt
+├── setup.py
+└── README.md
+```
+
+### 运行测试
+
+```bash
+# 运行示例
+python examples/basic_usage.py
+
+# 使用CLI工具
+xhs-extract --help
+```
+
+## 注意事项
+
+- 本工具仅供学习和研究使用
+- 请遵守小红书的使用条款和API限制
+- 过度频繁的请求可能导致IP被封禁
+- 建议在合理范围内使用，避免对平台造成负担
+
+## 许可证
+
+MIT License
+
+## 贡献
+
+欢迎提交Issue和Pull Request！

xhs_note_extractor-0.1.dev2.dist-info/RECORD

@@ -0,0 +1,11 @@
+xhs_note_extractor/__init__.py,sha256=CjHdqO4W5sj6zbeE7xYkR0_WRfc99G56nR6k2Kmji44,1207
+xhs_note_extractor/_version.py,sha256=59jjKBtTUi_9u6FVZcIpQEDYjyAaqdxzqXyuRuFYKPE,720
+xhs_note_extractor/cli.py,sha256=F5phl4HqnzEe_vTS8vpio_KcZNx4cxmXJnYcQ1FgMbA,2693
+xhs_note_extractor/extractor.py,sha256=Afl-VzMmuRSk82BbAROpIAB6g1BSpC3yRbDJTrO0NCM,14964
+xhs_note_extractor/utils.py,sha256=mOVoLknlflzv7aCjXdmeNniQ7P6WNUcjSKjCm8uwFNk,14364
+xhs_note_extractor-0.1.dev2.dist-info/licenses/LICENSE,sha256=VFtWajKKKkgOoX3cMb2upEjsQmDpU85ymhom2bYY_oI,1069
+xhs_note_extractor-0.1.dev2.dist-info/METADATA,sha256=ohcbdSTJ-ms66W5xBEqXIhczNN_7lpk4mqsvpL1fF0g,5525
+xhs_note_extractor-0.1.dev2.dist-info/WHEEL,sha256=_zCd3N1l69ArxyTb8rzEoP9TpbYXkqRFSNOD5OuxnTs,91
+xhs_note_extractor-0.1.dev2.dist-info/entry_points.txt,sha256=1IG34snKfX2pzpLSeDXHqlSVSH8p7bf3eaKQfcwGDk4,60
+xhs_note_extractor-0.1.dev2.dist-info/top_level.txt,sha256=at3SqTdQr3DWMFCL5KM0Ofo_LE88WqADjh8MeFLwwO0,19
+xhs_note_extractor-0.1.dev2.dist-info/RECORD,,

xhs_note_extractor-0.1.dev2.dist-info/WHEEL

@@ -0,0 +1,5 @@
+Wheel-Version: 1.0
+Generator: setuptools (80.9.0)
+Root-Is-Purelib: true
+Tag: py3-none-any
+

xhs_note_extractor-0.1.dev2.dist-info/entry_points.txt

@@ -0,0 +1,2 @@
+[console_scripts]
+xhs-extract = xhs_note_extractor.cli:main

xhs_note_extractor-0.1.dev2.dist-info/licenses/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 JoyCode Agent
+
+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.

xhs_note_extractor-0.1.dev2.dist-info/top_level.txt

@@ -0,0 +1 @@
+xhs_note_extractor