Pain Miner
输入：一句目标用户描述。
最终输出：九节、来源可追溯的研究报告；不是旧式 Step A/B/C 交付。
默认路径免登录。Reddit、HN、V2EX 的可用性取决于网络环境，工具会把失败和样本边界写入结果。
标准工作流
python3 scripts/pain_miner.py diagnose --out /tmp/pain-diagnose.json
python3 scripts/pain_miner.py run \
--target "独立 SaaS 创业者" \
--hours 336 --min-score 10 --min-comments 5 \
--profile-communities --fetch-comments --analyze \
--out /tmp/pain-run.json
python3 scripts/pain_miner.py render-report \
--input /tmp/pain-run.json --out /tmp/pain-report.md
先读 /tmp/pain-report.md，再在其中已有证据范围内补充写作；不要手工将 JSON 重组为流程型标题。
run --analyze 在主证据不足时仍会写 JSON，但返回码为 2，并将 analysis.evidence_verdict.status 置为 INSUFFICIENT_EVIDENCE。这不是“没有痛点”的结论，而是当前采样不能支持机会判断。
运行前：目标与社区计划
python3 scripts/pain_miner.py plan-communities \
--target "独立 SaaS 创业者" --profile-communities \
--out /tmp/pain-plan.json
- 检查
reddit_subs、hn_queries、v2ex_nodes与confidence。 - 中文目标出现
SaaS、indie、独立开发等线索时必须保持languages: [zh, en]；不得因中文输入而把英文社区和 HN 排除。 - SaaS/独立开发默认优先
SaaS、indiehackers、SideProject、EntrepreneurRideAlong与 V2EXcreate/share；career只能是显式补充，不得作为主证据。 - 推断不对时用
--subs、--hn-query、--v2ex-node覆盖，并在报告范围中说明。
数据源健康与降级
先运行 diagnose，检查 source_health：
| 状态 | 动作 |
|---|---|
ok | 正常收集；仍需按相关性和证据类型过滤。 |
degraded | 记录原因，扩大窗口或调整阈值，不把 0 hit 解读为无需求。 |
unavailable / reddit_edge_block | 不重复请求同一 Reddit 路径；转 HN-first，并把故障写入报告。 |
rate_limited | 停止重试该源，遵守退避与间隔。 |
empty | 区分“源为空”与“请求失败”；检查计划与时间窗。 |
当 Reddit 合格帖少于 3 且 HN 可用时，run 会一次性扩展已有的目标相关 HN 查询。不要用泛化的 Show HN、MRR 单词替代目标词；优先 indie hacker、micro saas、solo founder first customers 等模板。
浏览器/Jina 若返回 whoa there, pardner、network policy 或 Blocked，会标为失败而非成功正文。不得从拦截页提取证据。
证据与质量门禁
每条帖子均保留：
platform、community、url、data_source、抓取快照；post_intent、commercial_signals、evidence_type、risk_flags；target_relevance: high | low | unknown。
默认规则：
target_relevance=low帖子进入step_b.noise_posts与analysis.posts审计，不进入痛点簇和 OpportunityCard。promotion/commercially_contaminated、纯行业观点和单条反证不能独立支撑产品方向。- 少于
--min-primary-evidence（默认 5）条目标相关primary_evidence时，机会卡必须为空；报告在第 1 节和第 9 节说明不足与后续动作。 - 不得把热度、回复数或规则分类压成不透明的“机会总分”。
最终报告契约
只允许以下九个顶级标题：
- 研究范围
- 社区地图
- 高价值证据
- 痛点结构
- 跨社区共识与分歧
- 商业信号
- 候选产品方向
- 推荐验证方案
- 证据附录
第 9 节必须含数据限制和 source_health；证据不足时还要含可执行的下一步。完整字段映射见 references/output-templates.md。
分命令调试
python3 scripts/pain_miner.py discover --subs SaaS,indiehackers --hours 336
python3 scripts/pain_miner.py extract --subs SaaS,SideProject --hours 336 --min-score 10 --min-comments 5
python3 scripts/pain_miner.py hn-search --query "indie hacker" --hours 336 --min-score 10 --min-comments 5
python3 scripts/pain_miner.py v2ex-hot --node create --min-comments 5
python3 scripts/pain_miner.py compare-communities --input /tmp/pain-run.json --topic "customer feedback"
analyze-research 可以离线补齐分析；render-report 是唯一的完整 Markdown 输出器。
交付前自检
- 已执行
diagnose或在报告中说明未探测的源。 - 已运行
render-report，最终标题没有Step A、Step B、Step C。 - 每个结论都能回链到目标相关的来源帖。
- 已区分支持证据、反证、推广污染和低相关噪声。
-
INSUFFICIENT_EVIDENCE时没有产品机会、定价或营销钩子。 - 单一社区观察没有外推为普遍结论。