xueqiu-collector — 雪球采集与同步流程 Skill
一体化技能（v2.0 合并版），包含两条主线能力：
A. 帖子采集与分析（原 xueqiu-collector 1.x）
B. 自动化同步流程（原 xueqiu-pipeline 1.x：采集 → 导出 → IMA 上传 → 校验）
功能概述
A. 采集与分析
- 全量/增量采集 — 自动判断采集模式（首次全量，后续增量）
- 完整正文提取 — 含 Markdown 格式化、blockquote 评论识别
- 图片处理 — 下载帖子图片并 OCR 识别内容（winocr/tesseract）
- V4 规则分析 — 零 token 消耗，采集即分析：
- 帖子类型（原创/评论/错误/空内容）
- 投资相关性（high/medium/low/none）
- 情感分析（看多/看空/中性）
- 操作意图（买入/卖出/持有/观察）
- 主题标签（估值分析/财务分析/操作记录…）
- 质量评分（1-5分） - 数据导出 — SQLite 数据库 + JSON + Markdown（全量及按分类）
B. 自动化同步流程
- 采集 — 复用内置
collect.py（本包自包含 V4 引擎，无外部技能依赖） - 智能同步 — 对比采集前后数据，自动处理最新月份（增量/跨月全量）
- 增量上传 — 跳过已上传月份，只上传新历史月份到 IMA 知识库
- 一致性校验 — 对比本地数据库 / MD 文件 / 上传状态 / 云端 IMA 四方面
前置依赖
| 依赖项 | 说明 |
|---|---|
playwright-cli (npx) |
浏览器自动化，用于页面采集 |
| Edge 浏览器 + 真实 Profile | 挂载登录态，避免触发验证码 |
| Python 3.10+ | 运行采集/流程脚本 |
winocr（可选） |
Windows 内置 OCR，识别帖子图片文字 |
| SQLite | 数据持久化（内置） |
| IMA API 凭证（仅同步流程需要） | ~/.config/ima/client_id 与 api_key |
快速开始
# 0. 环境检测（首次使用必跑！）
python scripts/check_env.py
# ── A. 纯采集 ──────────────────────────────────
# 首次运行（不传参数，自动进入配置向导）
python scripts/collect.py
# 增量采集（推荐）
python scripts/collect.py --author "用户昵称" --url "https://xueqiu.com/u/7712999844"
# 强制扫描列表找新帖 / 强制重采正文 / 只采最新 N 条
python scripts/collect.py --author "昵称" --url "URL" --refresh-list
python scripts/collect.py --author "昵称" --url "URL" --force-collect
python scripts/collect.py --author "昵称" --url "URL" --force-collect --latest --limit 10
# 批量 V4 规则分析（补分析未分析的帖子）
python scripts/analyze.py --db "db/stock_analysis.db" --missing
# ── B. 自动化流程 ──────────────────────────────
# 完整流程：采集 → 同步 → 上传 → 校验
python scripts/pipeline.py --author "随缘的人生体验" --url "https://xueqiu.com/u/7712999844"
# 完整流程 + GUI 窗口（WorkBuddy Git Bash 环境推荐）
python scripts/pipeline.py --author "随缘的人生体验" --url "https://xueqiu.com/u/7712999844" --gui
# 只执行其中一步：采集 / 同步 / 上传 / 校验
python scripts/pipeline.py --author "昵称" --url "URL" --collect
python scripts/pipeline.py --author "昵称" --url "URL" --sync
python scripts/pipeline.py --author "昵称" --url "URL" --upload
python scripts/pipeline.py --author "昵称" --url "URL" --verify
# 强制覆盖上传指定月份
python scripts/upload.py --author "昵称" --month 2026-04 --force
SOP（标准操作流程）
场景一：首次采集某用户全部帖子
用户说："帮我采集 @随缘的人生体验 的全部雪球帖子"
- 确认昵称与主页 URL（
https://xueqiu.com/u/{UID}） - 运行
python scripts/collect.py --author "昵称" --url "URL" --db "db/stock_analysis.db" --out-dir "data/xueqiu" - 等待完成，报告统计（采集前后帖子数、新增数）
场景二：增量更新（常规日常）
用户说："同步一下雪球数据" / "雪球有新帖，更新一下"
- 从已知配置读取 author + url
- 运行
python scripts/collect.py --author "昵称" --url "URL" --refresh-list - 报告新增数量
场景三：完整自动化流程（采集 → IMA）
用户说："执行雪球自动化流程" / "同步雪球帖子到IMA"
- 确认昵称、URL、IMA 配置（
config/ima_config.json或环境变量） - 运行
python scripts/pipeline.py --author "昵称" --url "URL" - 脚本自动执行 precheck → 采集 → 智能同步 → 增量上传 → 四方面一致性校验
- 汇报每步结果
场景四：只同步最新月份 / 增量上传历史月份
用户说："雪球有新帖，重新上传一下最新月份" / "上传还没传的历史月份"
- 运行
python scripts/pipeline.py --author "昵称" --url "URL" --sync（重导最新月份并覆盖上传） - 或
--upload（依据upload_status_v2.json只传缺失月份）
场景五：一致性校验
用户说："检查一下雪球数据是否一致"
- 运行
python scripts/pipeline.py --author "昵称" --url "URL" --verify - 对比：本地 DB / MD 文件 / 上传状态 / 云端 IMA，输出差异报告
场景六：对历史帖子补 V4 分析
用户说："帮我分析一下数据库里的帖子"
python scripts/analyze.py --db "db/stock_analysis.db" --missing（只分析未分析的）- 或
--batch全量重分析
参数说明
collect.py
| 参数 | 说明 | 示例 |
|---|---|---|
--author |
用户昵称 | 随缘的人生体验 |
--url |
雪球主页 URL | https://xueqiu.com/u/7712999844 |
--db |
SQLite 路径（默认 <技能目录>/../data/xueqiu.db） |
db/stock_analysis.db |
--out-dir |
数据输出根目录 | data/xueqiu |
--refresh-list / --force-collect / --latest / --limit N |
采集模式控制 | - |
pipeline.py
| 参数 | 说明 |
|---|---|
--author / --url / --db / --out-dir |
同 collect.py |
--collect / --sync / --upload / --verify |
只执行单步 |
--gui |
弹出 GUI 窗口运行（自动继承 Python PATH） |
--skip-precheck |
跳过前置检测 |
输出结构
data/xueqiu/{昵称}/
├── posts_full.json 全量 JSON（时间倒序）
├── posts_full.md 全量 Markdown
├── classified/ 按分类 JSON（腾讯控股.json / 操作日记.json …）
├── md/ 按分类 Markdown
├── md_by_month/ 按月 MD（posts_2022-11.md …，流程上传用）
├── upload_status_v2.json 上传状态记录（增量上传依据）
└── images/ 帖子图片
数据库（xueqiu_posts）要点
字段覆盖：post_id/author/author_id/title/content/full_content/category/published_at/url
互动计数（like_count/comment_count/repost_count/read_count）、image_ocr_text，
V4 分析列（post_type/own_text/quote_text/reply_to_post_id/investment_relevance/sentiment/
trade_intent/content_type/quality_score/summary/topics/tags/word_count）。
IMA 配置（同步上传需要）
- 编辑
config/ima_config.json：填入knowledge_base_id、folder_id；多作者可扩展shared_config.py的AUTHOR_FOLDER_MAP - 或环境变量：
IMA_KB_ID、IMA_FOLDER_ID - 凭证文件：
~/.config/ima/client_id、~/.config/ima/api_key
一致性校验内容
- 本地数据库 —
xueqiu_posts该作者帖子 - 本地 MD 文件 —
md_by_month/月份文件 - 上传状态文件 —
upload_status_v2.json - 云端 IMA — API 查询知识库文件列表
报告：各月数量对比、缺失 MD、幽灵上传记录、最新月份一致性。
注意事项
- 浏览器登录态：采集需 Edge 已登录雪球，首次会自动启动并导航
- 采集限速：随机延迟 2-5 秒，每 20 条休息 8-12 秒，429 自动退避
- IMA 频率限制：上传间隔约 3 秒；
--force覆盖会先查云端列表删除旧文件再传 - 跨月处理：智能同步自动检测跨月，新月份按全量处理
- 日志：采集
logs/xueqiu_collect.log；流程logs/pipeline.log - OCR：
pip install winocr pillow（可选） - 分类关键词：
references/category_keywords.json可自定义主题规则
踩坑经验
- IMA 不支持同名覆盖，文件名必须带时间戳；覆盖前先查云端 media_id
- 跨月全量需以 before_count=0 触发
playwright-cli eval仅支持单行 JS- 雪球列表页时间格式多变（昨天/前天/X小时前/MM-DD/YYYY-MM-DD），已全部处理
- Edge Profile 路径含空格必须用 subprocess 列表传参；中文路径用 PowerShell + UTF-8 启动
--gui模式需 PATH 注入（继承 Python 路径到新 CMD），否则报找不到 python
