From d7f8450123eefee33cee0417b4ecd767e9a3ddcf Mon Sep 17 00:00:00 2001
From: admin <jk_work@126.com>
Date: Sat, 30 May 2026 23:27:56 +0800
Subject: [PATCH] =?UTF-8?q?=E4=B8=8A=E4=BC=A0=E6=96=87=E4=BB=B6=E8=87=B3?=
 =?UTF-8?q?=20/?=
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

---
 README.md | 116 ++++++++++++++++++++++++++++++++++++++++++++++++++++++
 1 file changed, 116 insertions(+)
 create mode 100644 README.md

diff --git a/README.md b/README.md
new file mode 100644
index 0000000..8848a72
--- /dev/null
+++ b/README.md
@@ -0,0 +1,116 @@
+# 帝国幻想乡~TOHOTOPIA 社区监控 MVP
+
+本项目第一阶段接入 Steam 评测与 Steam 讨论区，定时抓取社区内容，使用 OpenRouter 模型分类，并在本地 dashboard 中展示处理状态。
+
+## 当前状态
+
+- 产品：《帝国幻想乡~TOHOTOPIA》
+- Steam AppID：`3774440`
+- 当前已接入：Steam 评测、Steam 讨论区主题、Steam 讨论区回复
+- 已实现待登录验证：Twitter/X 账号帖子与帖子回复采集
+- 当前模型：OpenRouter `deepseek/deepseek-v4-pro`
+- 当前数据库：SQLite，默认 `data/tohotopia_monitor.sqlite3`
+- 当前服务：FastAPI + 内联 dashboard
+- 当前刷新：后台每 30 分钟增量同步
+- 当前排序：建议回复优先；同组内按发布时间新到旧
+- 当前局域网服务：监听 `0.0.0.0:8000`
+
+已验证数据状态：
+
+- 本机 smoke test 已抓取 384 条 Steam 内容。
+- 2026-05-01 之后的 209 条内容已全部完成 AI 分析。
+- Steam 讨论区中文时间文本已解析并回填，支持新到旧排序。
+
+## 本机运行
+
+```powershell
+python -m venv .venv
+.\.venv\Scripts\pip install -r requirements.txt
+Copy-Item .env.example .env
+# 编辑 .env，填入 OPENROUTER_API_KEY
+.\.venv\Scripts\python -m app.cli sync --full
+.\.venv\Scripts\uvicorn app.main:app --host 0.0.0.0 --port 8000
+```
+
+打开：
+
+```text
+http://127.0.0.1:8000
+```
+
+局域网其他设备访问：
+
+```text
+http://本机局域网IP:8000
+```
+
+当前 MVP 没有登录认证。开放到局域网后，同一局域网内能访问该地址的人都可以查看 dashboard、触发同步和修改处理状态。
+
+## 关键配置
+
+- `OPENROUTER_API_KEY`：OpenRouter Key。
+- `APP_ID`：Steam AppID，默认 `3774440`。
+- `SYNC_INTERVAL_MINUTES`：自动刷新间隔，默认 30 分钟。
+- `TWITTER_ENABLED`：是否启用 Twitter/X 采集，默认 `false`，需要先登录 X.com。
+- `TWITTER_USERNAME`：目标账号，默认 `Tohotopia`。
+- `TWITTER_BROWSER_PROVIDER`：社媒采集浏览器来源，默认 `existing`，复用 `social-media-scraper` 的 CDP Chrome profile。
+- `TWITTER_FULL_MAX_NO_NEW` / `TWITTER_INCREMENTAL_MAX_NO_NEW`：账号时间线滚动停止阈值。
+- `TWITTER_THREAD_MAX_NO_NEW`：单帖回复滚动停止阈值。
+- `TWITTER_FULL_REPLY_POST_LIMIT`：全量同步时抓取回复的帖子数上限，`0` 表示不限制。
+- `TWITTER_INCREMENTAL_REPLY_PARENT_LIMIT`：增量同步时回查最近多少条已入库 Twitter 主帖的回复。
+- `DISCUSSION_FULL_SCAN_MAX_PAGES`：首轮讨论区全量安全页数上限。
+- `DISCUSSION_INCREMENTAL_MAX_PAGES`：增量刷新最多扫描页数。
+
+## 分析补跑
+
+Dashboard 里的“补跑分析”会在后台启动，每批最多处理 20 条，点击后页面会立即返回。刷新页面查看“已分析 / 待补跑”计数变化；如果仍有待补跑，可以继续点击。
+
+如果启动服务后才修改 `.env`，需要重启 uvicorn 才能让后台自动同步线程读取新配置。页面按钮会在每次请求时重新读取 `.env`。
+
+也可以用 CLI 定向补跑，例如只补 2026-05-01 之后的内容：
+
+```powershell
+python -m app.cli analyze-pending --since 2026-05-01 --limit 20
+```
+
+## Twitter/X 采集前提
+
+Twitter/X 采集复用本机已有 `social-media-scraper` skill，通过 CDP Chrome profile 拦截结构化接口。首次使用需要先登录：
+
+```powershell
+python "$env:USERPROFILE\.codex\skills\social-media-scraper\scraper.py" --keep-browser-open https://x.com
+```
+
+在弹出的 Chrome 窗口登录 X.com 后，启用 `.env` 中的 `TWITTER_ENABLED=true`，再运行：
+
+```powershell
+python -m app.cli sync --platform twitter --full
+```
+
+如果未登录，系统会把本轮同步记为 partial 并在最近同步里显示错误，不会删除旧数据。
+
+## 新社区平台扩展入口
+
+后续接入其它社区平台时，优先复用现有三层数据模型：
+
+- `raw_items`：原始内容和来源追溯信息
+- `analysis_results`：OpenRouter 模型分析结果
+- `work_items`：制作人/处理人状态、备注和处理记录
+
+每个新平台建议单独实现采集器，输出与 `app.models.RawItem` 兼容的数据，不要让 dashboard 直接依赖平台私有字段。
+
+新增平台最少需要明确：
+
+- 来源平台和内容类型
+- 稳定去重主键
+- 原始链接生成方式
+- 作者标识和发布时间解析
+- 首轮全量与后续增量策略
+- 是否需要登录态、cookie、API key 或浏览器自动化
+- 失败重试和限流策略
+
+当前 Steam 采集器参考：
+
+- `app/steam.py`
+- `app/sync.py`
+- `app/openrouter.py`