# Twitter Monitor MVP

日期：2026-05-16
状态：completed

## 背景

用户要求在 Steam MVP 已完成的基础上，新增 X.com/Twitter 玩家反馈采集与处理功能，目标源为 `https://x.com/Tohotopia`，采集范围为所有帖子以及所有回复，首轮全量，增量按时间，继续复用 `RawItem -> raw_items -> OpenRouter -> analysis_results -> work_items -> dashboard` 流程。

## 需求确认

- 做什么：接入 X.com/Twitter 账号 `Tohotopia` 的账号帖子和每帖回复采集，归一为 `RawItem` 并进入现有同步、分析、dashboard 流程。
- 不做什么：不改 dashboard 的核心数据结构；不把 Twitter 私有字段提升为 dashboard 查询字段；不在未登录时伪造空结果。
- 成功标准：本机登录态可用时，CLI/同步能采集 Twitter 帖子与回复并入库去重，新增内容可进入 OpenRouter 分析和 dashboard 展示。
- 关键约束：X.com 当前页面/API/登录态属于动态事实，先以本机 smoke test 验证；采集失败不得删除旧数据。

## 文档/代码预读

- Project AGENTS：新渠道单独封装采集、解析、限流、登录态和失败处理；运营判断必须可追溯到平台、原始链接、采集时间或批次。
- Relevant docs：`README.md` 和 `任务/方案/后续社区平台接入指南.md` 明确新平台采集器输出 `app.models.RawItem`，复用三层数据模型。
- Relevant code：`app/sync.py` 当前只采 Steam；`app/models.py` 的 `RawItem` 可容纳 Twitter 数据；`app/db.py` 已有 `raw_json` 和 `(source, source_item_id)` 唯一键。
- 已确认事实：已有 `social-media-scraper` skill 支持 X.com 用户时间线和单帖回复，通过已登录 Chrome/CDP profile 拦截 API 输出 JSON/CSV。
- 冲突 / 歧义：用户不确定是否需要登录态；本机 smoke test 已验证当前 profile 检测到 X.com 登录提示。

## 术语与冲突

- Resolved terms：Twitter/X 平台标识在代码中使用 `twitter` 作为配置前缀；来源类型使用 `twitter_posts` 和 `twitter_replies`。
- Conflicts：无。
- Follow-up CONTEXT / glossary updates：暂无项目级 `CONTEXT.md`，本次术语记录在任务文档。

## 当前计划

- [x] T1 预读文档与现有 Steam 流程代码。
- [x] T2 验证 X.com 目标页与可用采集工具前提。
- [x] T3 制定 Twitter 接入方案和数据映射。
- [x] T4 实现采集器与同步流程接入。
- [x] T5 补充 CLI/配置/文档与任务记录。
- [x] T6 运行 smoke test 验证入库、分析与 dashboard。

## 关键判断与证据

| 判断 | 类型（稳定原理/当前事实/推断） | 证据 | 验证时间 | 未验证项 | 决策影响 |
|------|--------------------------------|------|----------|----------|----------|
| 新平台应输出 `RawItem` 后复用同步链路 | 稳定原理 | README、后续社区平台接入指南、`app/models.py` | 2026-05-16 | 无 | 避免 dashboard 直接依赖 Twitter 私有字段 |
| X.com 当前采集需要登录态 | 当前事实 | `social-media-scraper` 未登录提示；登录后小样本抓到 18 条 | 2026-05-16 | 全量回复数量和耗时 | 实现必须显式处理未登录失败并给出前置条件 |
| 复用已有 CDP 采集脚本比重写 X.com API 更稳妥 | 推断 | 已有 skill 支持 UserTweets/TweetDetail；登录后项目同步入口成功入库并分析 | 2026-05-16 | 全量耗时 | 新增项目内适配层读取 JSON 并转 RawItem |

## 执行记录

- 14:00：读取 `AGENTS.md`、`README.md`、`.codex/tasks/steam-monitor-mvp.md`、`任务/方案/后续社区平台接入指南.md`，确认新平台接入规则。
- 14:05：读取 `social-media-scraper` skill，确认 X.com 用户时间线和单帖回复已支持，输出位置可指定。
- 14:10：运行 `python C:\Users\jiajiankun\.codex\skills\social-media-scraper\scraper.py https://x.com/Tohotopia --max-no-new 1 --output-dir 任务/验证/twitter-smoke`，结果为当前 Chrome profile 未登录 X.com。
- 14:25：新增 `app/twitter.py`，将 `social-media-scraper` 输出的 timeline/thread JSON 转为 `RawItem`，内容类型为 `twitter_post` / `twitter_reply`，来源为 `twitter_posts` / `twitter_replies`。
- 14:35：扩展 `app/config.py`、`app/sync.py`、`app/cli.py`、`app/main.py`，支持 `TWITTER_ENABLED`、平台级同步、Twitter 单平台 CLI、dashboard 类型筛选。
- 14:42：更新 `.env.example`、`README.md`、`requirements.txt`，补充 Twitter 登录前提、配置和依赖。
- 14:50：修正 Twitter 增量高水位，从“最近同步完成时间”改为“已入库 Twitter 内容的最大发布/采集时间”，避免漏掉发布时间早于同步结束时间的内容。
- 14:55：验证 `python -m compileall app` 通过；默认配置 `python -m app.cli sync --platform twitter` 返回 `twitter_skipped=1`；临时启用 Twitter 后返回 `twitter_errors=1` 且 `sync_runs.status=partial`，未插入空 Twitter 数据。
- 19:17：用户在 CDP Chrome profile 登录 X.com 后，运行 `social-media-scraper` 小样本验证，抓到 18 条 `Tohotopia` 时间线内容。
- 19:21：运行项目同步小范围验证：`TWITTER_ENABLED=true`、`TWITTER_INCREMENTAL_MAX_NO_NEW=1`、`TWITTER_THREAD_MAX_NO_NEW=1`、`TWITTER_INCREMENTAL_REPLY_PARENT_LIMIT=2`、`python -m app.cli sync --platform twitter`。结果：`twitter_fetched=26`、新增 22、分析 22、已见 4。
- 19:25：数据库确认 Twitter 已入库 18 条 `twitter_posts` 和 4 条 `twitter_replies`；最近同步 `id=12` 状态为 `success`。
- 19:24-19:51：用户设置 `TWITTER_ENABLED=true` 后启动 `python -m app.cli sync --platform twitter --full`。命令被用户中断后仍有进程存活但 30 秒内无文件增长、CPU 几乎不变，判断为不再推进。
- 19:53：停止残留全量进程 `pid=81152`，将 `sync_runs id=13` 从 `running` 标记为 `partial`，保留已入库数据。最终 Twitter 数据为 34 条主帖、139 条回复，共 173 条，分析状态全部 `done`。

## 当前状态

- 已完成：文档/代码预读；X.com 登录态前提验证；Twitter 采集适配层、配置、同步、CLI、dashboard 文案和文档更新；编译、未登录失败路径、登录后小范围端到端验证。
- 阻塞：无。
- 下一步：如需执行“所有帖子及所有回复”的首轮全量，启用 `.env` 的 `TWITTER_ENABLED=true` 后运行 `python -m app.cli sync --platform twitter --full`。

## 五层变更候选

- 无。

## 恢复入口

下次继续时先读：

- 关键文件：`app/twitter.py`、`app/sync.py`、`app/config.py`、`app/cli.py`、`app/main.py`。
- 当前目标：把 `https://x.com/Tohotopia` 的帖子和回复接入现有 RawItem 流程。
- 当前状态：实现已完成；X.com 登录态已写入 CDP profile；小范围同步成功；一次全量同步被中断后已清理残留进程并保留 173 条已分析数据。
- 最近完成：清理全量残留进程，将 `sync_runs id=13` 标记为 partial。
- 下一步：如需继续全量，可再次运行 `python -m app.cli sync --platform twitter --full`，现有去重会跳过已入库内容。
- 不要做：不要把未登录导致的失败当作“无数据”；不要改 dashboard 数据模型。
- 已改文件：`.codex/tasks/twitter-monitor-mvp.md`、`app/twitter.py`、`app/config.py`、`app/sync.py`、`app/cli.py`、`app/main.py`、`.env.example`、`README.md`、`requirements.txt`。
- 验证结果：`python -m compileall app` 通过；默认 Twitter 未启用会跳过；未登录会 partial；登录后项目同步成功；当前 Twitter 共 34 条主帖和 139 条回复，173 条全部 `done`。
- 当前阻塞：无。