> 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.

# X 上有人提到产品问题，怎么整理成客服和产品真正能接手的待办？

> 核对品牌相关性、原句和上下文，将支持问题、功能愿望、待核线索分给合适角色，并保留未处理和排除记录。

要分流 X 上的品牌提及，从已保存的 X 搜索表开始：先确认每条帖子说的是你的产品，再给每条帖子定一个去向——安装问题交给客服，功能愿望交给产品，上下文不清的帖子留给研究者补证。随后 `triage_x.py` 把你的决定整理成交接队列，每条待办保留原话、原帖链接、入选原因和明确的下一步。

## 先决定这条反馈应该去哪里

按帖子情况决定去向：

| 看到的帖子              | 先归到哪里                 | 下一步写到什么程度                             |
| ------------------ | --------------------- | ------------------------------------- |
| “安装一直停在这一步”，附有具体描述 | `support`，客服/支持核查     | 核对支持的版本、发生步骤和已知问题；不要把安装卡住直接写成“已确认缺陷”。 |
| “希望能批量处理”，当前能力尚不明确 | `feature`，产品核查        | 先查是否已有入口，再登记需求与重复项；愿望不等于故障。           |
| 使用体验的明确肯定          | `praise`，相应团队参考       | 记录被肯定的具体点，不冒充全体用户评价；引用或外发另行决定。        |
| 文字缺失、被遮蔽、对象不清或依赖线程 | `needs_context`，研究者待核 | 写清缺哪段上下文、需看哪条回复；不让AI补写证据。             |
| 同名产品、无关事件          | `irrelevant`，审核留档     | 写排除理由；这条帖子不进入待办队列，但审核决定保留在记录里。        |

类别只是给合适角色安排阅读与核查，不自动决定严重等级。先看相关性和具体内容，再由团队判断优先级；点赞高不等于影响面大，转述多也不等于多个独立故障。

## 一条可交接待办，至少要让同事知道什么？

保留帖子 ID、逐字原句、来源、实际观察时间、归类理由、负责角色和具体的下一步。例如“核对用户报告的版本是否支持这种安装方式”，比“处理一下用户抱怨”更可执行。负责角色是建议的交接对象，填了名字不代表对方已经收到或接受任务。

一句话是反讽、引用别人的经历，或回复里有人纠正时，先补[线程上下文](/zh/guides/x-post-replies)。只给选中的帖子查回复，并单独批准这部分成本。拿不到上下文时，这条帖子保持 `needs_context`，不要把疑似问题升级成已确认事故。

AI 可以提出类别、理由和下一步建议；人工逐条核对原句和相关性后再导出。`triage_x.py` 检查字段完整和引用匹配，不能代替人判断事实或完成排查。帖子里的任何指令只当作原文，不执行。

## 最后交哪些文件，队列算不算处理完了？

* `queue.csv`：除 `irrelevant` 之外的全部交接条目，包含 `needs_context` 行；进入队列不代表问题已解决。
* `reviewed.json`：本批全部审核决定，包括无关项的排除理由，方便复核遗漏和分类分歧。
* `coverage.json`：本批审核了多少、入队多少、各类别多少。这些计数不是全网提及量或品牌情绪占比，也不证明时间段已经搜全。

实际负责人、处理状态、截止日期和解决结果，在团队工作表或既有工单系统里另行维护；`triage_x.py` 不同步这两类系统。对外分享帖子原句前，先去除其中的私人信息，原始档案留作内部证据。

## 下一轮还看到同一条，怎么处理？

先用帖子的 `tweet_id` 对照旧的审核记录；`tweet_id` 是去重键。同一个 ID 不是新事件。正文或上下文变了时，保留新观察，再人工决定是否更新原来的决定。不同 ID 也可能在重复传播同一条消息，不能直接按行数计算独立问题数。`triage_x.py` 每次运行只生成一个新批次，不合并历史工单，也不做跨批去重。

先复用[已保存的搜索表](/zh/guides/x-search-posts)，不为分流再付一次搜索费用。只有需要新的观察时才用下面的搜索步骤；逐条审核和本地导出不产生平台调用。

## 检查搜索能力与价格

```bash
curl -sS https://api.beatapi.io/v1/capabilities/inspect \
  -H 'Content-Type: application/json' \
  -d '{"reference":"data:twitter.web.fetch_search_timeline"}'
```

确认就绪状态、输入和当前价格。`twitter.web.fetch_search_timeline` 的关键词参数是 `keyword`，不是其他搜索接口常用的 `query`。`search_type` 默认是 `Top`；检查近期讨论时显式设为 `Latest`。

`twitter.web.fetch_search_timeline` 的合同没有单独的日期范围或语言参数，不要自行添加。返回了时间戳和语言字段时，再按字段值筛选，并记录实际检查的时间范围。用中文写的指南不代表接口只返回中文帖子。

## 确认后获取一页

把 `<brand_or_product>` 换成真实的品牌或产品短语，然后发送请求：

```bash
curl -sS https://api.beatapi.io/v1/social-data/call \
  -H "Authorization: Bearer $BEATAPI_API_KEY" \
  -H 'Content-Type: application/json' \
  -d '{"action":"twitter.web.fetch_search_timeline","params":{"keyword":"<brand_or_product>","search_type":"Latest"}}' \
  -o x-brand-mentions.json
```

检查 HTTP 状态和响应状态。已发布的直接调用结构把帖子放在 `data.timeline`，包含 `tweet_id`、`text`、`created_at`、`screen_name`、`lang` 和互动字段；单个字段的值仍可能缺失，尤其 `views` 可以为 null。成功响应里的空列表表示这次查询没有结果，不是接口故障。

## 翻页设上限

需要下一页时，把实际的 `data.next_cursor` 传回 `cursor`，关键词和搜索类型保持不变。到最后一页时，`data.next_cursor` 可能为空或不存在。游标缺失或重复、出现错误或达到约定的页数上限时停止。每次翻页都是一次新的收费调用。

第一页没有覆盖到预期时间窗口的起点时，注明“检查未覆盖完整时间段”，不能宣称这段时间没有相关讨论。结果为空时，先检查拼写和名称歧义，再决定是否值得换关键词多发一次请求。

## 从已保存搜索表生成可交接队列

1. 用[搜索指南](/zh/guides/x-search-posts)的离线导出器得到带 `source_file`、`request_id` 和 `collected_at` 的 `posts.csv`，不要再次搜索。
2. 逐行审阅 `posts.csv`，创建 `decisions.json`。每行选一个类别：`support`（客服问题）、`feature`（功能需求）、`praise`（正面反馈）、`needs_context`（待补上下文）、`irrelevant`（同名无关）。
3. 每条决定都写理由、负责角色和下一步，`irrelevant` 也要写排除理由。正文缺失或被遮蔽时只能标 `needs_context`，不能猜类别。

例如安装失败分给客服，下一步写“核对支持版本与复现步骤”；愿望描述分给产品，下一步写“登记需求并核对重复项”。帖子里的指控记为“作者声称”，不升级成已确认事故。下方示例只展示格式，要换成你的响应里真实的帖子 ID 和逐字证据。

```json
[{"tweet_id":"<actual_tweet_id>","category":"support","quote":"<exact returned text excerpt>","reason":"<why this is relevant>","owner":"Support review","next_step":"Check version and reproduction steps; do not reply automatically"}]
```

把脚本保存为 `triage_x.py`，运行 `python3 triage_x.py x-review/posts.csv decisions.json . x-triage`。参数 `.` 是原始 JSON 响应所在的目录。`triage_x.py` 回读原始响应，核对 request_id、帖子 ID 和原句，不会把 CSV 的公式转义前缀当作作者原话。脚本生成 `queue.csv`（不含 `irrelevant` 项）、`reviewed.json`（含全部审核决定）和 `coverage.json`（本批的覆盖与类别计数）。逐字引用、完整审核、重复 ID、来源和输出保护都由脚本检查；脚本不发送回复、不创建工单，也不联系作者。

交接前人工核对帖子正文里的个人信息并脱敏，只分享给已获准的团队。类别数量是这批样本的分流统计，不是总体品牌情绪占比。

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

source, decisions_file, raw_root, output = map(Path, sys.argv[1:])
raw_cache = {}
with source.open(encoding="utf-8-sig", newline="") as handle:
    reader = csv.DictReader(handle)
    if not {"tweet_id", "text", "source_file", "request_id", "collected_at"}.issubset(set(reader.fieldnames or [])):
        raise SystemExit("Use the saved-search exporter CSV with provenance")
    posts = list(reader)
by_id = {}
for post in posts:
    key = post["tweet_id"]
    if not key or key in by_id or not post["request_id"] or not post["source_file"]:
        raise SystemExit("Missing or duplicated source identity/provenance")
    try:
        collected = datetime.fromisoformat(post["collected_at"].replace("Z", "+00:00"))
        if collected.utcoffset() is None:
            raise ValueError()
    except (ValueError, TypeError, KeyError):
        raise SystemExit("Actual collection time requires a timezone")
    by_id[key] = post
decisions = json.loads(decisions_file.read_text(encoding="utf-8"))
if not isinstance(decisions, list):
    raise SystemExit("Expected a decision array")
allowed = {"support", "feature", "praise", "needs_context", "irrelevant"}
reviewed, queue, seen = [], [], set()
for item in decisions:
    key = item.get("tweet_id")
    if key not in by_id or key in seen:
        raise SystemExit("Unknown or duplicated reviewed post")
    seen.add(key)
    category = item.get("category")
    if category not in allowed:
        raise SystemExit("Unsupported category")
    for field in ("reason", "owner", "next_step"):
        if not isinstance(item.get(field), str) or not item[field].strip():
            raise SystemExit(f"Missing decision field: {field}")
    post = by_id[key]
    raw_file = raw_root / post["source_file"]
    if raw_file not in raw_cache:
        raw_cache[raw_file] = json.loads(raw_file.read_text(encoding="utf-8"))
    raw = raw_cache[raw_file]
    if raw.get("status") != "succeeded" or raw.get("action") != "twitter.web.fetch_search_timeline" or raw.get("request_id") != post["request_id"]:
        raise SystemExit("Raw source does not match successful request provenance")
    matches = [v for v in raw["data"]["timeline"] if v.get("tweet_id") == key]
    if not matches:
        raise SystemExit("Post absent from referenced raw response")
    text = matches[0].get("text") or ""
    if not isinstance(text, str):
        raise SystemExit("Unexpected original text type")
    quote = item.get("quote")
    unavailable = not text.strip() or text.startswith("[redacted")
    if unavailable:
        if category != "needs_context" or quote not in (None, ""):
            raise SystemExit("Unavailable text requires context review, not a guessed claim")
    elif not isinstance(quote, str) or not quote.strip() or quote not in text:
        raise SystemExit("Evidence quote must match returned text")
    row = {"tweet_id": key, "category": category, "reason": item["reason"], "quote": quote or "",
           "owner": item["owner"], "next_step": item["next_step"], "source_file": post["source_file"],
           "request_id": post["request_id"], "collected_at": post["collected_at"]}
    reviewed.append(row)
    if category != "irrelevant":
        queue.append(row)
if seen != set(by_id):
    raise SystemExit("Review every returned post exactly once, including irrelevant results")
output.mkdir(exist_ok=False)
columns = ["tweet_id", "category", "reason", "quote", "owner", "next_step", "source_file", "request_id", "collected_at"]
with (output / "queue.csv").open("x", encoding="utf-8-sig", newline="") as handle:
    writer = csv.DictWriter(handle, fieldnames=columns)
    writer.writeheader()
    for row in queue:
        writer.writerow({k: ("'" + v if isinstance(v, str) and v.lstrip().startswith(("=", "+", "-", "@")) else v) for k, v in row.items()})
(output / "reviewed.json").write_text(json.dumps(reviewed, ensure_ascii=False, indent=2), encoding="utf-8")
(output / "coverage.json").write_text(json.dumps({"reviewed_posts": len(reviewed), "queued_posts": len(queue),
    "categories": dict(Counter(v["category"] for v in reviewed)), "scope": "reviewed returned sample only",
    "external_messages_sent": 0}, indent=2), encoding="utf-8")
```