评论透镜 chiknc9-maker/bilibili-comment_lens

评论透镜（Comment Lens）— B站评论区思辨分析工具

项目定位：针对 B站争议视频的评论区，生成中立的三层分析——争论各方在争什么、每一方最有力的论证是什么、被当作「垃圾」的评论垃圾在论证的哪一环（以及其中有没有被误杀的观点内核）。

免责声明：本项目仅用于个人学习与研究，请遵守 B站用户协议与当地法律法规。报告只分析论证与讨论结构，不评判立场、不评价个人；公开分享报告请使用脱敏版本（去逐字引用与定位编号，只留结构性结论），见伦理红线。

当前进度：

| 里程碑 | 状态 | 产物 |
| M0 抓取 | ✅ | fetch_comments.py：BV 号 → 含楼中楼（最深六级）的评论 JSON |
| M1 分析管线 | ✅ v2 内核 | run_analysis.py + analyze/：评论 JSON → 九段式思辨报告（md + json） |
| M2 网页服务 | ✅ 可用（2026-10-27 端到端验收通过） | web/app.py + web/static/index.html：粘贴链接 → 轮询进度 → 页面渲染报告 |
| M3 真实争议视频评测 | 🟡 进行中 | 6 支视频数据全部跑出 v2 九段式报告；4 份 v1 归档。v1/v2 横向对比见 M3_评测_v1_v2对比.md |

⚠️ reports/ 里 2026-09-06 的 4 份报告是 v1 内核产物：只有「最佳论证 / 可疑事实 / 认知观察」三块，没有命题还原、观点地图、论辩关系、论证诊断，字段结构也与 v2 不同构，已整体归档到 reports/v1_kernel/。除非做历史对比，否则只看 reports/ 下的 v2 报告。

✅ 曾经的阻断缺陷已修（2026-09-22）：命题提取在 max_tokens=8000 边界被截断会导致整跑失败（实测约 50% 视频中招）。现在改为三级降档 + 截断抢救，机制见「踩过的坑」第 9 条；当时的评测记录见 M3_评测_v1_v2对比.md 第六节。

目录结构

comment-lens/
├── fetch_comments.py # M0：BV号 → 评论 JSON（含楼中楼，最深六级） ├── run_analysis.py # M1：评论 JSON → 八段式报告（CLI） ├── analyze/ │ ├── llm.py # DeepSeek 客户端（httpx 直连 + JSON mode + 重试） │ ├── preprocess.py # 清洗/截断/脱敏 + 语料拼装（Thread 数据类） │ ├── nodes.py # 各分析节点的提示词与调用（产品价值观写在提示词里） │ └── pipeline.py # LangGraph 编排 + 报告渲染 ├── web/ │ ├── app.py # M2：FastAPI 服务（后台线程抓取 + 分析） │ └── static/index.html # 单页前端（轮询进度 + marked 渲染报告） ├── data/ # 抓取结果（已在 .gitignore） ├── reports/ # 报告与结构化结果（已在 .gitignore） ├── requirements.txt ├── .env.example # 复制为 .env 填凭据 └── README.md

快速开始

0) 克隆并建虚拟环境（首次）
git clone https://github.com/chiknc9-maker/bilibili-comment_lens.git comment-lens
cd comment-lens
python -m venv .venv # Windows 之后用 .venv\Scripts\python.exe；macOS/Linux 用 .venv/bin/python

1) 依赖 .venv\Scripts\python.exe -m pip install -r requirements.txt

2) 凭据：复制 .env.example 为 .env DEEPSEEK_API_KEY 分析必需（platform.deepseek.com 注册并充值，单视频约 ¥0.2~0.6）； SESSDATA/BUVID3 可留空（匿名也能抓，填了更稳）

3) 三步走通 .venv\Scripts\python.exe fetch_comments.py BV1iUXNBzEVh # M0 → data/ .venv\Scripts\python.exe run_analysis.py data/BV1iUXNBzEVh_comments.json # M1 → reports/ .venv\Scripts\python.exe -m uvicorn web.app:app --port 8000 # M2 → http://127.0.0.1:8000/

免安装打包版（Windows）

不懂命令行？从 GitHub Releases 下载 comment-lens.zip，解压后双击 comment-lens.exe：浏览器会自动打开本地页面，粘贴 B站链接即可，数据与报告写在 exe 旁边（data/、reports/），关闭黑窗口即停止服务。

两个前提：① 需要你自己的 API key——DeepSeek 或任何 OpenAI 兼容服务（通义/Kimi/GLM/ SiliconFlow/Ollama）都行，在页面「高级设置」里粘贴一次就会被浏览器记住（只存在你自己的浏览器里）； ② 个别杀毒软件会误报 PyInstaller 打包的程序，添加信任即可。

M0 抓取：BV 号 → 评论 JSON

.venv\Scripts\python.exe fetch_comments.py BV1RhtV6iEt3
.venv\Scripts\python.exe fetch_comments.py "https://www.bilibili.com/video/BV1RhtV6iEt3/"

| 参数 | 默认 | 说明 |
| --main-total | 100 | 抓多少条主评论（热评排序，每页 20；0=不限） |
| --no-subs | — | 不抓楼中楼（更快） |
| --sub-limit | 20 | 每条主评论的楼中楼条数上限 |
| --depth3-limit | 5 | 深树下钻时每个节点最多保留多少条直接回复（0=不下钻）；树深度由接口返回决定，实测可达六级 |
| --depth3-floor | 10 | 主楼楼中楼≥此值才下钻（控制请求量） |
| --delay | 0.4 | 请求间隔（秒），遇到风控就加大 |
| --proxy | 直连 | 走代理时显式指定，如 http://127.0.0.1:7892 |

抓 100 条主评论约需 1~2 分钟（含深树下钻 1~5 分钟），结果写入 data/<BV号>_comments.json。

M1 分析：评论 JSON → 思辨报告

.venv\Scripts\python.exe run_analysis.py data/BV1roE9zUEF5_comments.json
.venv\Scripts\python.exe run_analysis.py data/BV1roE9zUEF5_comments.json --dry-run # 只算语料规模与预算，不调模型 .venv\Scripts\python.exe run_analysis.py data/BV1roE9zUEF5_comments.json --out reports

换模型：分析走 OpenAI 兼容协议，改 .env 里 DEEPSEEK_BASE_URL / DEEPSEEK_MODEL 两个值即可换成通义、Kimi、GLM、SiliconFlow、Ollama（本地模型）等；网页版在「高级设置」里直接填。
个别服务不支持 JSON 输出模式时，客户端会自动去掉该参数重试。

输出两个文件到 reports/（文件名取自视频 BV 号）：

- BVxxxx_report.md —— 人读的九段式报告
- BVxxxx_structure.json —— 机读结构化结果：claims / position_map / debate_relations / picks / diagnosis / best_args / suspect_facts / insights

实测规模（100 条主评论的输入）：

| 指标 | 实测值 |
| 参与分析的语料 | 0.7 万 ~ 3.4 万字（每节点最多留 5 条回复、单条截断 300 字、树深上限 8 层） |
| 模型调用 | 9 次分析调用 + 1 次连通性测试（ping） |
| 耗时 | 77 ~ 261 秒（六次实跑）。波动主要来自服务端延迟（论辩关系节点平时 8s、最慢一次 138s）；新增的非论证解剖只占约 5s |
| 成本 | 每次实跑的真实 token 与估算成本落盘在 reports/_run_log.jsonl（价格快照：输入 ¥2/百万、输出 ¥8/百万）；--dry-run 是事前估算 |
| 本地缓存 | data/llm_cache/：同 prompt 同参数直接复用结果，重复分析同一数据文件几乎零成本（日志里的 cache_hits 可见命中数）。强制重调模型加 --no-cache，清缓存删目录 |

分析管线（LangGraph，全串行单链）

| 顺序 | 节点 | 做什么 |
| 0 | prepare | 脱敏成 {like, text, replies} 树，只留引用所需的最小字段 |
| 1 | extract_claims | 命题还原：把评论还原为「实际提出了什么」（最多 50 条，被截断时自动降档 50→30→20）；玩梗/提问/纯情绪只登记 thread_id + kind 索引，交给第 6 步专门解剖 |
| 2 | position_map | 观点地图：按命题簇聚类（不是支持/反对二分），标出伪对立与共享前提 |
| 3 | debate_relations | 论辩关系：谁真的回应了谁的命题，谁在各说各话、误解、转移话题 |
| 4 | pick_diagnosis | 挑 5 处「高传播但论证有典型问题」的评论作为诊断对象 |
| 5 | argument_diagnosis | 论证诊断：先说「论证在哪一环断了」，逻辑学术语只作条件式补充；必答「其中值得认真对待的问题」 |
| 6 | nonargument_autopsy | 非论证表达解剖：把玩梗/反讽/情绪/提问聚类，说清它们在争论里实际起了什么作用、其中有没有被埋掉的真问题；允许也必须能判「没有内核」 |
| 7 | best_args | 值得学习的论证：挑论证质量高的范本并覆盖不同观点簇；已诊断的整楼会从输入语料里物理删除，模型不可能再选它 |
| 8 | suspect_facts | 可疑事实清单：最多 10 条、合并重复、只标「待核实」不下对错结论 |
| 9 | cognitive_insights | 认知与社会观察：只分析表达模式与讨论结构，不分析单个评论者心理 |
| 10 | compose | 渲染九段式报告 |

M2 网页：粘贴链接 → 报告

.venv\Scripts\python.exe -m uvicorn web.app:app --port 8000
浏览器打开 http://127.0.0.1:8000/

流程：粘贴视频链接或 BV 号 → 后台线程抓取（main_total=100, delay=0.35）→ 分析 → 前端每 2 秒轮询进度 → 完成后渲染 Markdown。整个流程约 2~6 分钟。

接口：POST /api/analyze、GET /api/tasks/{id}、GET /api/tasks/{id}/report。

MVP 限制（单机自用够用）：

- 任务状态在内存里，重启服务即清空历史任务（报告本身已落盘到 reports/）
- 无队列、无取消：同时提交多个任务会各自抓取，容易一起撞 B站风控
- CORS 全开、API 地址写死 http://127.0.0.1:8000，只为兼容「双击 index.html 以 file:// 打开」；不要暴露到公网
- 前端 marked.js 走 CDN，离线时自动降级为纯文本展示
- 分析发生降级（命题提取超限自动降档/抢救）时，网页端会显示警示横幅并建议重跑
- 任务失败自动重试（最多 3 次）：抓取失败（风控/网络）等 90s/180s，分析失败等 15s/30s；缺 key、鉴权失败等确定性错误不重试

报告怎么读

九段结构：一、讨论概览｜二、命题还原｜三、观点地图｜四、论辩关系｜五、论证诊断｜六、非论证表达解剖｜七、值得学习的论证｜八、可疑事实清单｜九、认知与社会观察。

第六节怎么读：它把玩梗/反讽/情绪/提问按模式聚成不超过 6 个簇，每簇说明「字面在说什么」和「在争论里起了什么作用」，再判有没有值得认真对待的内核。argument_kernel 写"无"是常见且正常的结论（不是漏找）——梗刷屏的视频常常整节都是"无"，有实质争论的视频才会挖出真问题。该节还会披露解剖素材条数：素材明显少于登记条数时，说明大量候选没有正文可分析，结论的支撑面就窄。

引用定位：编号按抓取时刻的 B站「按热度」排序生成——[T0] = 热度第 1 条主评论，[T12] = 从上往下第 13 条；T12_回复3 = 点开 T12 后楼中楼第 3 条（热度序）。脚本不做任何重排（不按点赞数排序），所以编号能和你在评论区里数出来的位置对上。每条引用附「抓取时 N 赞」，热度变化重排后按原文和赞数对照查找。

匿名化：报告里只有 [T序号]，不出现用户名；引用正文里嵌的"回复 @某人："前缀在预处理阶段已剥离。

定位的前提：报告头部的链接行是唯一可靠的入口——B站搜索可能因视频被降权/搜索屏蔽而找不到原视频（实测发生过），直接点报告里的链接即可；视频被删后引用无法回溯，报告只对抓取时刻的快照负责。

匿名化的边界：红线是"回复 @用户名："式的点名。若评论内容本身提到角色名/公众人物名，而该名字恰好与某个用户名重合（如《P5》角色"雨宫莲"与同名粉丝），引用中出现该词属于内容引用，不是身份泄露。

踩过的坑（重要，务必阅读）

抓取侧

1. 代理：B站是国内站，且会对境外 IP 出口（Clash 等代理节点）直接风控（412）。
脚本默认直连（忽略系统代理）。确实需要代理时用 --proxy http://127.0.0.1:7892。
2. 请求头一致性：无 cookie 的匿名请求不要带 Referer（实测触发 412）；只有填了 cookie 脚本才会带 Referer + Cookie。脚本已自动处理，不要手动改。
3. 请求节奏：默认每请求间隔 0.4s，抓 100 条主评论约需 1~2 分钟。
连续高频请求会触发风控，风控后等几分钟再试。
4. reply 接口与多级对话树：
- root=主评论rpid → 该主楼的全部直接回复（每项含 rpid/parent/root）
- root=<任意回复rpid> → 以该回复为根的多层展开对话树（扁平列表，含其自身与各代后代，实测单次请求可含至第六级），rcount 字段恒为 0 （B站已废弃该信号）。
- 抓取时本地重组装：从目标回复出发，把 parent 落在已收集集合内的项挂为对应父节点的子级（parent 指向集合外的其他分支丢弃），逐层按点赞截断，得到完整嵌套树（最深可达接口返回极限）。

分析侧

5. LangGraph 多入边节点会重复执行：实测本版本 LangGraph（1.2.x）里，一个节点有多个直接前驱时会把该节点跑两遍（模型调用直接翻倍）。
所以管线是全串行单链，每个节点只有一个前驱——串行化后总耗时只多约 15 秒（命题提取是绝对瓶颈，其他节点都很短）。改图时不要随手加并行入边。
6. 语料顺序不能重排：T 编号 = 抓取时的 B站热度序，一旦按点赞数重排，报告里的编号就再也对不回评论区的实际位置（这是报告可用性的命门）。
7. 中文互联网语境：评论里大量反讽、圈子梗、亚文化黑话，字面意思 ≠ 真实意图。
提示词里有专门的"语境铁律"：语气夸张/逻辑反常的先怀疑是玩梗，按上下文解读；拿不准的标注"疑似圈子梗/反讽，含义未确认"，不许自信地给字面解读。
8. v1/v2 报告不同构：v1 只有三段（最佳论证/可疑事实/认知观察），v2 是八段。
做横向评测前先把旧视频用 v2 重跑，否则指标不可比。
9. 生成的 JSON 会顶到 max_tokens 上限，而原样重试几乎没用：命题提取要模型吐 50 条命题（含隐含前提），实测输出 6.7k~8k tokens，正好卡在 8000 上限上——同 payload 重试等于再抛一次硬币。现在的处理：① 命题上限三级降档 50→30→20；② 仍被截断就从残缺 JSON 里抢救已完整的条目（llm.salvage_partial_json），保证不整跑失败；③ 非论证内容从命题提取里挪走（只留索引），从源头给输出瘦身。
降档或抢救会打印提示、结构数据里带 degraded: true——此时报告覆盖偏窄，应当重跑。

遇风控怎么办（code=-412 / HTTP 412）

1. 等 5~10 分钟再试，或加大 --delay 1.0
2. 在 .env 中填入自己的 SESSDATA（复制 .env.example 改名 .env），登录态下风控阈值高得多，还能看更多评论

JSON 数据格式

{
"meta": { // 视频信息与抓取配置
"bvid", "aid", "title", "owner", "stat", "fetched_at", "config"
},
"threads": [ // 主评论（热评排序）
{
"rpid": 316116547328, // 评论ID "uname": "...", // 用户名（分析展示阶段将匿名化） "like": 5132, // 点赞数 "ctime": "ISO时间", "rcount": 57, // 楼中楼总回复数（>实际抓到的数量=还有更深层争论） "text": "评论内容",
"replies": [ // 直接回复（按热度最多20条）
{ "rpid", "uname", "like", "ctime", "rcount", "text",
"replies": [ // 该回复的回复（可递归至六级，每节点上限5条）json
{ ..., "replies": [...] }
]
}
]
}
]
}

伦理红线（产品原则）

抓取只用于本地分析。展示与分析阶段，所有评论一律匿名化，报告只评「论证」，不评「人」。不做评分榜，不做公开排行。

公开分享报告时，请使用脱敏版本：

- 报告里的逐字引用是可搜索追溯的——匿名化只隐藏用户名，藏不住人。
公开版应去掉所有引文（改写为摘要）与 [T序号] 定位，只保留结构性结论。
- 建议附注：「分析基于抓取时刻的快照，不构成对任何个人或观点的评价。」

路线图

已完成

- M0：抓取脚本（BV → 楼中楼 JSON，最深六级）
- M1：LangGraph 分析管线（v2 内核：命题还原 / 观点地图 / 论辩关系 / 论证诊断 / 非论证解剖 / 最佳论证 / 可疑事实 / 认知观察 → 九段式报告）
- M2：FastAPI + 网页（粘贴链接 → 报告）
- 工程硬化：截断降档 + 抢救、运行日志（reports/_run_log.jsonl）、本地 LLM 缓存、失败自动重试、降级警示
- v1/v2 横向对比评测（结论见 M3_评测_v1_v2对比.md）：引用错位 38/63 → 0/106、用户名残留 5 → 0

进行中 / 可选增强

- M3 人工评测：报告判断是否站得住、引用定位好不好用（需真人对照原评论区逐条检验）
- 任务队列与取消（当前定位是单机自用；多任务同时提交容易一起撞 B站风控）
- 公开版报告模式：一键脱敏（去逐字引用与定位编号，只留结构性结论）

技术栈

- Python 3.10+（本机 .venv 为 3.14）
- 抓取：httpx 直连 B站公开接口（api.bilibili.com/x/v2/reply/main|reply，hot 排序），未用第三方封装库（实测 bilibili-api-python 新版封装有坑，直连接口更可控）
- 分析：LangGraph 1.2（全串行单链）+ httpx 直连 DeepSeek（JSON mode 结构化输出，零框架依赖）
- 网页：FastAPI + uvicorn + 单页 HTML（marked.js 渲染 Markdown）