carrielabs reddit-intel
Reddit 舆情情报 Skill
⚠️ Reddit API 限制说明（永久生效，必须在 Phase 1 告知用户）
这是 Reddit 的平台政策，不是工具的 bug。
Reddit 官方 API 限制（2023年收紧后）：
① 单次请求：最多返回 100 条帖子
② 搜索总量：同一关键词+排序，分页后约 250-500 条上限
（Reddit 故意截断，防止大规模数据抓取）
③ 评论获取：需要对每条帖子单独发请求（不含在搜索结果里）
④ 限流：请求过快会被封 IP，需每次间隔 2 秒
我们的策略（4种排序 × 多个版块 × 去重）：
→ 可将单关键词可获取量扩展至 600-1500 条
→ 指定日期范围 = 按周分段请求，不突破单次上限，但总量可叠加
注意：Reddit 有数百万条相关帖子，API 只给你很小的窗口。
这是平台限制，无法绕过。PullPush.io（第三方历史数据）可选接入，
但该服务不稳定，随时可能关闭，不作为默认方案。
永久约束（任何阶段均有效）
① 禁止捏造数据。字段无法判断时，用兜底规则（见 CLASSIFY_RULES.md），
不允许输出"无法判断"作为最终结果。
② 批处理强制执行。Phase 3 每批严格处理 10 条，禁止一次性处理全部。
③ 竞品只提取明确出现的品牌名。帖子原文没有的，一律不写。
④ 置信度诚实标注。文本不足以可靠判断时，强制标"低"。
⑤ 行动点必须具体，"值得关注""建议持续观察"直接删除重写。
⑥ 热评精华基于真实评论内容，无内容时留空。
⑦ 概览 Tab（Sheet 2）的统计数字由 Python 计算，不允许 Claude 估算。
架构说明
文件加载时序：
Phase 1：READ ${CLAUDE_SKILL_DIR}/SUBREDDIT_MAP.md（行业版块推荐）
Phase 3：READ ${CLAUDE_SKILL_DIR}/CLASSIFY_RULES.md
READ ${CLAUDE_SKILL_DIR}/TRANSLATE_RULES.md
Phase 4：READ ${CLAUDE_SKILL_DIR}/OUTPUT_SCHEMA.md
Phase 1：参数确认
加载：
READ "${CLAUDE_SKILL_DIR}/SUBREDDIT_MAP.md"
向用户一次性问清以下参数：
① 关键词是什么？
支持逻辑运算：
- AND："Binance AND scam"（同时含两个词）
- OR： "ChatGPT, Claude, Gemini"（逗号分隔 = OR）
- NOT："cryptocurrency NOT Bitcoin"（排除词）
② 分析目的是什么？
A. 品牌/产品研究
（关键词是产品或公司名，如：Notion / Binance / ChatGPT）
→ 使用产品研究框架（P1-P5）
B. 行业舆情监控
（关键词是行业词或话题词，如：加密货币 / AI写作 / 电商退款）
→ 自动匹配行业框架，Claude 根据关键词推断
C. 自定义分类
→ 追问：你想分哪几类？（3-6个为宜）
③ 时间范围？
- 近 7 天（默认）
- 近 30 天
- 近 3 个月
- 近一年
- 自定义：[起始日期] 至 [结束日期]
④ 抓取数量？（默认 100，最多 500；超过 200 条耗时较长）
⑤ 评论模式？
- 快速模式（默认）：只抓帖子正文，3-5 分钟出结果
- 深度模式：抓帖子 + 每条热评（耗时 10-15 分钟，数据更丰富）
⑥ 限定版块？（可跳过，跳过则全站搜索；不熟悉版块可说行业，我来推荐）
用户说不知道版块时： → 根据关键词和 SUBREDDIT_MAP.md 推荐 3-5 个版块，让用户确认或调整
完成后告知 API 限制：
"本次配置预计可获取约 X 条帖子。
说明：Reddit API 对单关键词每种排序方式约返回 250-500 条，
多排序合并去重后实际可用量约 [估算范围]。
这是 Reddit 平台限制，与工具无关。"
参数记录（工作记忆）：
QUERY: [处理后的搜索字符串]
LOGIC: [AND / OR / NOT]
LIMIT: [数字]
TIMEFRAME: [week / month / 3month / year / custom:起止日期]
MODE: [fast / deep]
SUBREDDITS: [版块列表，空则全站]
FRAMEWORK: [A=产品研究 / B=行业舆情+行业名 / C=自定义类别列表]
Phase 2：数据抓取
执行脚本：
python3 "${CLAUDE_SKILL_DIR}/scripts/fetch_reddit.py" \
--query "QUERY" \
--limit LIMIT \
--time TIMEFRAME \
--mode MODE \
--subreddits "版块1,版块2" \
--output posts_raw.json
等待脚本完成后：
- 读取
posts_raw.json - 向用户报告：
抓取完成：共 X 条帖子 来源版块：N 个（列举前5个） 时间跨度：[最早日期] 至 [最新日期] 内容类型预判：图片帖/自动播报/营销推广 共约 X 条（可能影响分类质量） - 如果 posts_raw.json 为空 → 告知用户并提示调整关键词或去掉版块限制
- 进入 Phase 3
Phase 3：批量认知处理
加载：
READ "${CLAUDE_SKILL_DIR}/CLASSIFY_RULES.md"
READ "${CLAUDE_SKILL_DIR}/TRANSLATE_RULES.md"
批处理规则：
- 每次取 10 条，处理完追加到结果列表，向用户展示进度
- 全部完成后写入
posts_processed.json - 如果中途中断，记录已处理到第几条，告知用户可恢复
每条帖子必须先做内容质量预判（见 CLASSIFY_RULES.md 第一节），再做分类
处理后每条帖子的 JSON 格式：
{
"id": "帖子ID",
"content_type": "内容类型（图片帖/自动播报/营销推广/有效文字）",
"title_original": "原始标题",
"title_zh": "中文标题",
"summary_zh": "中文摘要（≤500字）",
"core_intent": "核心意图",
"main_category": "主分类",
"sub_tags": ["子标签1", "子标签2"],
"sentiment": "情绪",
"competitors_mentioned": ["品牌名"],
"use_case": "使用场景",
"top_comments_summary": "热评精华",
"action_item": "行动点",
"confidence": "置信度",
"upvotes": 0,
"num_comments": 0,
"subreddit": "r/xxx",
"created_date": "YYYY-MM-DD",
"url": "https://reddit.com/..."
}
⚠️ 营销推广预警： 处理完全部帖子后，统计 content_type="营销推广" 的比例。 如果超过 40%，在进入 Phase 4 之前主动提示：
"⚠️ 本次结果中 X%（N条）为营销推广内容，有效数据偏少。
建议：在关键词后加 NOT "referral" 或指定更垂直的版块后重试。"
Phase 4：生成 Excel
加载：
READ "${CLAUDE_SKILL_DIR}/OUTPUT_SCHEMA.md"
执行脚本（Python 负责统计，Claude 负责写综合 Action Items）：
第一步：让 Claude 基于 posts_processed.json 写出 3-5 条综合行动点， 存入变量 SUMMARY_ACTIONS（供脚本写入 Sheet 2）
第二步：执行导出：
python3 "${CLAUDE_SKILL_DIR}/scripts/export_excel.py" \
--input posts_processed.json \
--keyword "关键词" \
--actions "综合行动点文字（换行分隔）"
完成后向用户报告：
✅ 完成
文件：reddit_intel_[关键词]_[日期].xlsx
Sheet 1「舆情数据」：X 条帖子，17 列
Sheet 2「概览」：情绪分布 / Top分类 / 高赞帖子 / 综合建议
置信度分布：高 X 条 / 中 Y 条 / 低 Z 条
（低置信度条目建议人工复核，主要来自图片帖和内容过短的帖子）
错误处理
| 错误情况 | 处理方式 |
|---|---|
| fetch 返回 0 条 | 提示关键词过冷门或版块限制过严，建议扩展关键词 |
| API 429 限流 | 脚本自动等待 30 秒重试（最多 3 次），超出则保存已有数据 |
| Phase 3 中途中断 | 记录中断位置，告知用户可从中断点恢复，不删除已有结果 |
| export 失败 | 检查 openpyxl 是否安装（pip install -r requirements.txt） |
| 营销推广占比 >40% | 提示用户调整关键词，询问是否继续或重新配置 |