> For clean Markdown of any page, append .md to the page URL.
> For a complete documentation index, see https://docs.beatapi.io/llms.txt.
> For AI client integration (Claude Code, Cursor, etc.), connect to the MCP server at https://docs.beatapi.io/_mcp/server.

# 怎样把Reddit讨论整理成有原句支持的产品问题清单？

> 从选中的帖子读取评论，保留父子关系、去重观察，再审核原句并交付问题、适用条件与下一步。

要把 Reddit 讨论整理成产品问题，从选中的帖子链接取帖子 ID，加上 `t3_` 前缀，用 `reddit.app.fetch_post_comments` 读评论。把已保存的响应导出为 CSV，保留评论原句、父评论关系和出处。审核后，把值得处理的问题和每个问题的发生条件交给产品或内容同事。

例如一条评论说「手机端改完后电脑端没更新」，就记下两端设备和操作顺序。回复补充了版本或离线条件时，把回复和父评论一起存档，再安排复现。

## 一轮研究怎样推进？

1. **选准讨论。** 已有帖子永久链接时直接开始；还没选帖时，用[社区候选流程](/zh/guides/reddit-community-shortlist)选帖并保留选择理由。
2. **读一页评论。** 先看原帖和实际返回的回复，保存来源；再决定哪些问题需要补读回复或更多页。
3. **整理来源表。** 导出评论正文、标识、父子关系和可用计数；合并已存页面时，去重后的评论与同一评论的多次观察分开保存。
4. **审核原句。** 给每条入选评论填写主题、逐字引文和判断理由；在原始响应里核对到引文后，再放进问题清单。
5. **写下一步。** 把每个问题归入四类之一：原帖已有解答、需要补文档、需要复现、需要核实。

把审核交给已接入 BeatAPI 的助手时，可以这样布置：

> 阅读这条讨论的已取评论，整理与笔记同步有关的问题和体验。每项保留原句、帖子链接和父评论上下文，说明什么条件下发生、还需核实什么。不要只给情绪标签，给我能继续处理的问题清单。

## 哪些文件对应哪些结果？

| 文件                                  | 怎么读                                                      |
| ----------------------------------- | -------------------------------------------------------- |
| 每页评论CSV与原响应                         | 查看实际文本、父子关系与来源                                           |
| `comments.csv` / `observations.csv` | 区分去重评论与重复观察，回看后续变化                                       |
| `review-labels.json`                | 人工选择的主题、引文与审核理由                                          |
| `question-backlog.json`             | 已审核问题及原句来源，未审阅数量同时保留                                     |
| 人工行动副本                              | 添加 `proposed_action` 与 `verification_needed`，生成的来源记录继续保留 |

例如“哪种设置支持离线？”可以成为说明文档问题；“某台设备上同步失败”先作为待复现的自述。评论分数反映讨论热度，不能证明产品缺陷。

下面第 1–7 步依次完成取数、导出、合并和原句审核。本地步骤复用已存响应，不产生费用；新取评论或回复按[价格页](https://beatapi.io/zh/pricing)估算。

## 1. 确认输入与本次范围

从帖子链接 `/comments/` 后面取出 ID，加上 `t3_` 前缀。示例里的 `t3_abc123` 只是格式样例，换成你的真实 ID。第一次只取一页。先用免费的 `/v1/capabilities/inspect` 查看 `data:reddit.app.fetch_post_comments` 当前的参数和价格；每次平台调用按当前价格计费，本地转换不产生费用。

复制的是帖子或评论的永久链接时，用[本地请求准备器](/zh/faq/reddit-comment-pagination)提取帖子 ID；评论永久链接最后一段是评论 ID，不是帖子 ID。准备器只生成首页请求正文，不发送请求。

## 2. 保存一页原始响应

```bash
mkdir reddit-query-1 && \
curl --fail-with-body -sS https://api.beatapi.io/v1/social-data/call \
  -H "Authorization: Bearer $BEATAPI_API_KEY" \
  -H 'Content-Type: application/json' \
  -d '{"action":"reddit.app.fetch_post_comments","params":{"post_id":"t3_abc123","sort_type":"NEW","need_format":false,"after":""}}' \
  -D reddit-query-1/response.headers \
  -o reddit-query-1/reddit-comments.json
```

HTTP 请求失败时，保留错误信息，不运行导出。HTTP 成功后，`export_comments.py` 还会校验业务状态、动作和树结构。本例读取的是 `/v1/social-data/call` 的直接响应，不是 capabilities 执行包装。

## 3. 导出正文与父子关系

将下面的脚本保存为 `export_comments.py`，用 Python 3 运行。目标 CSV 必须还不存在：脚本先校验响应结构，再打开目标文件，已有导出文件不会被覆盖。缺失的分数留空，零分保持为零。以公式字符开头的文本前加单引号，降低表格软件把文本当公式执行的风险。

```python
import csv, json, pathlib, sys
source, target = map(pathlib.Path, sys.argv[1:3])
r = json.loads(source.read_text(encoding="utf-8"))
if not isinstance(r, dict) or r.get("error") is not None or r.get("status") != "succeeded" or r.get("action") != "reddit.app.fetch_post_comments":
    raise ValueError("Expected a successful Reddit comment response")
if not isinstance(r.get("request_id"), str) or not r["request_id"].strip():
    raise ValueError("Missing request ID")
forest = r["data"]["postInfoById"]["commentForest"]
trees = forest["trees"]
if not isinstance(trees, list):
    raise ValueError("commentForest.trees must be an array")
info = forest.get("pageInfo")
if not isinstance(info, dict) or type(info.get("hasNextPage")) is not bool:
    raise ValueError("Expected an explicit pagination boolean")
rows, seen = [], {}
duplicate_nodes = 0
def cell(value):
    if value is None: return ""
    text = str(value)
    return "'" + text if text.lstrip().startswith(("=", "+", "-", "@")) else text
for tree in trees:
    if not isinstance(tree, dict):
        raise ValueError("Each tree entry must be an object")
    node = tree.get("node")
    if node is None: continue  # pagination marker, not a comment
    if not isinstance(node, dict):
        raise ValueError("Unusable or redacted node; do not treat it as an empty page")
    key = node.get("id")
    if not isinstance(key, str) or not key or key.startswith("[redacted"):
        raise ValueError("Missing usable comment id")
    if type(tree.get("depth")) is not int or tree["depth"] < 0:
        raise ValueError("Expected nonnegative integer depth")
    for name in ("childCount",):
        if tree.get(name) is not None and (type(tree[name]) is not int or tree[name] < 0):
            raise ValueError("Expected nonnegative integer child count or missing")
    if node.get("score") is not None and (type(node["score"]) is not int or abs(node["score"]) > 9007199254740991):
        raise ValueError("Expected safe integer score, including negative values, or missing")
    if node.get("isRemoved") is not None and type(node["isRemoved"]) is not bool:
        raise ValueError("Removal status must be boolean or missing")
    content = node.get("content")
    if content is None: content = {}
    if not isinstance(content, dict) or (content.get("markdown") is not None and not isinstance(content["markdown"], str)):
        raise ValueError("Expected comment text or missing")
    if key in seen:
        if seen[key] != tree:
            raise ValueError("Conflicting duplicate comment within one page; preserve raw and review")
        duplicate_nodes += 1
        continue
    seen[key] = tree
    rows.append([key, tree.get("parentId"), tree.get("depth"), tree.get("childCount"),
                 content.get("markdown"), node.get("score"), node.get("createdAt"),
                 node.get("permalink"), node.get("isRemoved"), r.get("request_id")])
## Exclusive creation protects earlier exports; an empty valid page still gets a header.
with target.open("x", encoding="utf-8", newline="") as f:
    writer = csv.writer(f)
    writer.writerow(["id", "parent_id", "depth", "child_count", "markdown", "score",
                     "created_at", "permalink", "is_removed", "request_id"])
    writer.writerows([[cell(v) for v in row] for row in rows])
more = trees[-1].get("more") if trees else None
cursor = more.get("cursor") if isinstance(more, dict) else None
if not isinstance(cursor, str) or not cursor.strip():
    cursor = None
if not info["hasNextPage"]:
    cursor = None
stop_reason = "provider_end" if not info["hasNextPage"] else ("next_page_available" if cursor else "missing_usable_cursor")
print(json.dumps({"rows": len(rows), "has_next_page": info.get("hasNextPage"),
                  "after": cursor, "duplicate_nodes": duplicate_nodes,
                  "stop_reason": stop_reason, "all_comments_collected": False}, ensure_ascii=False))
```

## 4. 检查文件和继续翻页

```bash
python3 export_comments.py reddit-query-1/reddit-comments.json reddit-comments-page-1.csv
```

核对输出摘要里的 `rows` 与 CSV 行数一致，并检查重复 ID。有效的空页只输出表头。合并其他页时保留 `parent_id` 和 `depth`，按 `id` 去重。`permalink` 是相对链接，打开时在前面加 [https://www.reddit.com。\`score\`](https://www.reddit.com。`score`) 不是点赞数；缺失的正文保持缺失，不补写。

脚本打印 `has_next_page` 和 `after`。`has_next_page` 为 false 就结束。只有 `has_next_page` 为 true、`after` 是非空的新游标、且下一页在预先批准的页数内时，才继续请求，并用新的 JSON/CSV 文件名保存。游标缺失或重复、状态缺失或响应报错时，停止并检查响应。脚本从不自动重试收费查询。

## 5. 这份结果覆盖什么？

导出结果是返回评论节点的快照，不是全量历史备份。`child_count` 的数值不代表已收到这么多条回复。保留缺失父评论和删除标记；合并时不把孤立回复提升为一级评论。分页边界的细节见下方链接的 FAQ。

字段路径来自后端登记的四个历史生产响应结构和网关当前的渲染实现。示例按这份已登记结构编写，`t3_abc123` 是占位 ID。

[FAQ](/zh/faq/reddit-comment-pagination) · [Reddit](/zh/guides/reddit)

## 6. 合并已保存页面，保留重复观察与缺失父评论

不要把逐页 CSV 直接拼接后就当作去重结果。新建 `pages.json`，为每个 CSV 记录请求时的 `post_id` 和实际采集时间，格式如下：

```json
{"pages":[{"post_id":"t3_abc123","file":"reddit-comments-page-1.csv","collected_at":"2026-11-16T10:00:00Z"},{"post_id":"t3_abc123","file":"reddit-comments-page-2.csv","collected_at":"2026-11-16T10:01:00Z"}]}
```

将下面的脚本保存为 `merge_pages.py`，运行 `python3 merge_pages.py pages.json merged-comments`。脚本离线运行，拒绝已存在的输出目录，并生成三个文件：

* `comments.csv`：每个帖子 + 评论 ID 一行，取清单顺序里的首次观察。
* `observations.csv`：保留每一次观察，后续编辑和分数变化不会被悄悄覆盖。
* `coverage.json`：输入页数、唯一评论数、重复观察数和缺失父评论的回复数。

父评论缺失的回复仍是回复，有效的空页也计入页数。

```python
import csv
import json
import sys
from datetime import datetime
from pathlib import Path

manifest_path, output_path = map(Path, sys.argv[1:])
manifest = json.loads(manifest_path.read_text(encoding="utf-8"))
pages = manifest.get("pages")
if not isinstance(pages, list) or not pages:
    raise SystemExit("Expected at least one saved-page entry")
required = {"id", "parent_id", "depth", "child_count", "markdown", "score", "created_at", "permalink", "is_removed", "request_id"}
observations, chosen, seen_files = [], {}, set()
for page in pages:
    post = page.get("post_id")
    if not isinstance(post, str) or not post.startswith("t3_") or len(post) <= 3:
        raise SystemExit("Expected the request's t3_ post ID")
    file = manifest_path.parent / page["file"]
    if file.resolve() in seen_files:
        raise SystemExit("Duplicate page file")
    seen_files.add(file.resolve())
    try:
        stamp = datetime.fromisoformat(page["collected_at"].replace("Z", "+00:00"))
        if stamp.utcoffset() is None:
            raise ValueError()
    except (ValueError, KeyError, TypeError):
        raise SystemExit("Collection time requires a timezone")
    with file.open(encoding="utf-8-sig", newline="") as handle:
        reader = csv.DictReader(handle)
        if set(reader.fieldnames or []) != required:
            raise SystemExit("Use CSVs from the exporter above")
        for row in reader:
            if not row["id"] or not row["depth"].isdigit():
                raise SystemExit("Missing ID or invalid depth")
            observation = {"post_id": post, **row, "source_csv": page["file"], "collected_at": page["collected_at"]}
            observations.append(observation)
            key = (post, row["id"])
            if key not in chosen:
                chosen[key] = observation
rows = []
for (post, key), first in chosen.items():
    row = dict(first)
    row["parent_in_sample"] = "not_applicable_root" if int(row["depth"]) == 0 else str((post, row["parent_id"]) in chosen).lower()
    row["observations"] = sum(v["post_id"] == post and v["id"] == key for v in observations)
    rows.append(row)
summary = {"pages": len(pages), "observations": len(observations), "unique_comments": len(rows),
           "duplicate_observations": len(observations) - len(rows),
           "replies_with_missing_parent": sum(v["parent_in_sample"] == "false" for v in rows),
           "policy": "first observation in manifest order; all observations retained separately",
           "scope": "saved returned nodes only, not a complete thread"}
output_path.mkdir(parents=False, exist_ok=False)
def write(name, values, columns):
    with (output_path / name).open("x", encoding="utf-8-sig", newline="") as handle:
        writer = csv.DictWriter(handle, fieldnames=columns)
        writer.writeheader()
        for row in values:
            writer.writerow({k: ("'" + v if isinstance(v, str) and v.lstrip().startswith(("=", "+", "-", "@")) else v) for k, v in row.items()})
base_columns = ["post_id", "id", "parent_id", "depth", "child_count", "markdown", "score", "created_at", "permalink", "is_removed", "request_id", "source_csv", "collected_at"]
write("comments.csv", rows, base_columns + ["parent_in_sample", "observations"])
write("observations.csv", observations, base_columns)
(output_path / "coverage.json").write_text(json.dumps(summary, indent=2), encoding="utf-8")
```

## 7. 从已保存讨论形成带证据的待回答问题清单

读取评论和解读称赞、抱怨、问题是两个步骤。Reddit 还要保留回复上下文：回复另一位读者的评论不自动构成独立的产品抱怨。直接用第 6 步的合并结果，不重复购买已存页面。

交给产品团队的是一份短清单，包含三类条目，每条都附精确证据：需要回答的问题、值得排查的阻碍、应当保留的优点。读完上下文后，每条入选评论只归一个主主题。AI 模型可以建议标签，每个标签都由审核人核对。广告、跑题和证据不足的解读标为排除，并写明理由。已删除或删除状态未知的评论不作为支撑。

用真实的帖子 ID、评论 ID 和原始响应 `markdown` 里的原句建立 `review-labels.json`。把下面模板里的占位值换掉：

```json
[{"post_id":"t3_abc123","comment_id":"REPLACE_WITH_REAL_COMMENT_ID","decision":"include","kind":"question","topic":"Setup prerequisites","quote":"REPLACE_WITH_VERBATIM_EXCERPT"}]
```

入选评论的 `kind` 填 `question`、`complaint` 或 `praise`。排除评论时，`decision` 填 `exclude`，并写非空的 `reason`。将下方脚本保存为 `reddit_review.py`。脚本核对每条审核评论都在合并样本里、每句引文都逐字出现在原始文本里、评论明确未被删除。脚本保留父评论和深度信息，并报告未审阅的评论数，部分审核不会显得像全部审完。脚本不判断用户说法是否属实，也不发布任何内容。

运行脚本前建立 `raw-pages.json`，把合并表里每个 `source_csv` 对应到原始响应和请求的帖子。CSV 的公式转义可能加上原文没有的单引号，所以 `reddit_review.py` 回读原始 JSON 核对引文，不删除单引号。

```json
[{"post_id":"t3_abc123","csv_file":"reddit-comments-page-1.csv","raw_file":"reddit-query-1/reddit-comments.json"}]
```

```python
import csv,hashlib,json,pathlib,sys
source,raw_manifest,review,target=map(pathlib.Path,sys.argv[1:5])
with source.open(encoding="utf-8-sig",newline="") as f:records=list(csv.DictReader(f))
comments={}
for row in records:
    key=(row.get("post_id"),row.get("id"))
    if not all(isinstance(value,str) and value.strip() for value in key) or key in comments:raise ValueError("Use deduplicated merged comments")
    comments[key]=row
raw_entries=json.loads(raw_manifest.read_text(encoding="utf-8"))
if not isinstance(raw_entries,list):raise ValueError("Raw-page manifest required")
originals={};csv_pages=set()
for page in raw_entries:
    csv_file=page["csv_file"];post=page["post_id"]
    if csv_file in csv_pages:raise ValueError("Ambiguous CSV to raw-page mapping")
    csv_pages.add(csv_file)
    path=pathlib.Path(page["raw_file"])
    if not path.is_absolute():path=raw_manifest.parent/path
    raw=path.read_bytes();response=json.loads(raw)
    if not isinstance(response,dict) or response.get("error") is not None or response.get("status")!="succeeded" or response.get("action")!="reddit.app.fetch_post_comments":raise ValueError("Wrong raw response")
    if not isinstance(response.get("request_id"),str) or not response["request_id"].strip():raise ValueError("Missing raw request ID")
    trees=response["data"]["postInfoById"]["commentForest"]["trees"]
    if not isinstance(trees,list):raise ValueError("Raw tree required")
    for tree in trees:
        if not isinstance(tree,dict):raise ValueError("Invalid raw tree entry")
        node=tree.get("node")
        if node is None:continue
        if not isinstance(node,dict):raise ValueError("Unusable raw comment object")
        ident=node.get("id")
        if not isinstance(ident,str) or not ident.strip() or ident.startswith("[redacted"):raise ValueError("Missing raw comment ID")
        key=(post,ident,csv_file)
        if key in originals:
            if originals[key]["tree"]!=tree:raise ValueError("Conflicting raw duplicate; do not select a favorable version")
            continue
        originals[key]={"node":node,"tree":tree,"request_id":response["request_id"],"raw_file":str(path),"sha256":hashlib.sha256(raw).hexdigest()}
labels=json.loads(review.read_text(encoding="utf-8"))
if not isinstance(labels,list):raise ValueError("Review array required")
seen=set();topics={};excluded=[]
for item in labels:
    key=(item["post_id"],item["comment_id"])
    if key not in comments or key in seen:raise ValueError("Review each actual comment at most once")
    seen.add(key);row=comments[key]
    if item.get("decision")=="exclude":
        reason=item.get("reason")
        if not isinstance(reason,str) or not reason.strip():raise ValueError("Exclusion reason required")
        excluded.append({"post_id":key[0],"comment_id":key[1],"reason":reason});continue
    if item.get("decision")!="include":raise ValueError("Decision must be include or exclude")
    original=originals.get((key[0],key[1],row.get("source_csv")))
    if original is None or original["request_id"]!=row.get("request_id"):raise ValueError("Raw source does not match merged observation")
    node=original["node"];tree=original["tree"]
    if node.get("isRemoved") is not False:raise ValueError("Only explicitly non-removed raw comments may support a theme")
    topic=item.get("topic");kind=item.get("kind");quote=item.get("quote");content=node.get("content") or {}
    if not isinstance(content,dict) or not isinstance(content.get("markdown"),str):raise ValueError("Raw markdown required")
    text=content["markdown"]
    if not isinstance(topic,str) or not topic.strip() or kind not in ("question","complaint","praise"):raise ValueError("Topic and supported kind required")
    if text.strip().lower() in ("[removed]","[deleted]"):raise ValueError("Removal placeholders are not theme evidence")
    if not isinstance(quote,str) or not quote.strip() or quote not in text:raise ValueError("Quote must occur verbatim in original raw comment text")
    if not node.get("permalink") or not row.get("request_id"):raise ValueError("Evidence source and request_id required")
    depth=row.get("depth","")
    if not depth.isdigit() or int(depth)!=tree.get("depth"):raise ValueError("Comment depth differs from raw evidence")
    if row.get("parent_id")!=str(tree.get("parentId") or ""):raise ValueError("Parent differs from raw evidence")
    bucket=topics.setdefault((kind,topic),[])
    bucket.append({"post_id":key[0],"comment_id":key[1],"quote":quote,"permalink":node["permalink"],"raw_file":original["raw_file"],"raw_sha256":original["sha256"],
                   "request_id":row["request_id"],"collected_at":row.get("collected_at"),"depth":int(depth),
                   "parent_id":row.get("parent_id"),"parent_in_sample":row.get("parent_in_sample"),"source_csv":row.get("source_csv")})
output=[]
for (kind,topic),evidence in sorted(topics.items()):
    output.append({"kind":kind,"topic":topic,"supporting_comments":len(evidence),"distinct_posts":len({v["post_id"] for v in evidence}),
                   "root_comments":sum(v["depth"]==0 for v in evidence),"replies":sum(v["depth"]>0 for v in evidence),
                   "evidence":evidence,"proposed_action":"","verification_needed":""})
report={"unique_exported_comments":len(comments),"reviewed_comments":len(seen),"unreviewed_comments":len(comments)-len(seen),
        "included_comments":sum(len(v) for v in topics.values()),"excluded_comments":len(excluded),"excluded":excluded,
        "topics":output,"scope":"Reviewed saved comments only; counts are comments, not people or population prevalence",
        "review_policy":"One primary topic per included comment. Semantic labels are human-reviewed, not machine-verified truth."}
with target.open("x",encoding="utf-8") as f:json.dump(report,f,ensure_ascii=False,indent=2)
print(str(target))
```

运行 `python3 reddit_review.py merged-comments/comments.csv raw-pages.json review-labels.json question-backlog.json`。逐条结合上下文回看证据原句，再在副本里填写 `proposed_action` 和 `verification_needed`。例如未解答的安装问题对应一份文档草稿，投诉对应一份复现清单，而不是直接对外指控。每条建议动作都是你的编辑决定，不是 API 返回的事实。

`question-backlog.json` 里的统计是支撑评论数和不同帖子数，不是不同人数、客户普遍比例或独立问卷样本。一级评论和回复分开计数，缺失父评论仍然可见，排除数和未审阅数留在覆盖记录里。输出不带作者名，但原句仍可能含个人信息：发给审核团队以外的人之前，先在副本里脱敏。

## 坏行要拒绝，但缺游标不应抹掉已经拿到的评论

`export_comments.py` 在创建 CSV 之前，要求有请求号、明确的 `hasNextPage` 布尔值，以及合法的评论深度、回复数和分数类型。Reddit 负分有效；布尔值或小数分数不能当作计数。同一页里完全相同的重复节点合并成一行并计数。同一页里同一 ID 出现两个不同版本时导出停止，有利的原句无法被悄悄选中；保留原始响应排查。不同已存页面之间的变化由合并步骤保留。

页面有有效评论但没有可用的下一页游标时，导出脚本仍导出已返回的评论，并报告 `missing_usable_cursor`：页面有评论，帖子也没有读全。`provider_end` 只表示当前分页结束。导出脚本始终把 `all_comments_collected` 设为 false，因为未展开的回复分支、删除内容和后续新评论都不在已存页面里。`next_page_available` 只表示有游标，是否花钱读下一页由你决定。继续时必须在既定预算内，并且游标是新的。

## 分享前，怎样验收这份问题清单？

逐个主题核对保留的原句在对话上下文里是否支持标签。问题指向待核查的文档缺口，抱怨指向复现任务，称赞指向值得保留的体验。建议的下一步是编辑判断，不是对所有客户的已证实结论。在审核副本里填写 `proposed_action` 和 `verification_needed`，生成的原文件保持不变。

以下文件一起交付：选帖名单与理由、原始页面字节、各页 CSV、`pages.json` 与 `raw-pages.json`、合并评论与全部观察、审核标签、生成的问题清单、人工行动副本。写明还有多少条未审阅，不把部分标注的文件说成全部审完。对外分享的副本先去掉原句里的个人信息。脚本不会联系 Reddit 用户、发布结论、创建提醒，也不替你取得对外分享的授权。

有多页时，人工核对每份已存请求都使用了上一页返回的新 `after` 游标；`merge_pages.py` 不校验游标链。`raw-pages.json` 里的每个 `csv_file` 必须与合并表的某个 `source_csv` 完全一致。

`reddit_review.py` 还会拒绝同一原始页内相互矛盾的重复 ID、非空但不可用的节点和错误包装，审核不会挑选有利版本。评论分数必须是安全的 JSON 整数，负分仍然有效。异常值留作排查，不从不安全的数值推算精确分数。

[还没有帖子链接时，从选定社区首页挑讨论](/zh/guides/reddit-community-shortlist)。