python-library-ff14-news 0.0.0__tar.gz

python_library_ff14_news-0.0.0/.cursor/skills/ff14_news-package-changelog/SKILL.md

@@ -0,0 +1,17 @@
+---
+name: ff14-news-package-changelog
+description: ff14_news 包：要求与决议；最新在上。
+---
+
+# ff14_news · Changelog
+
+（规则见 `~/.cursor/skills/agent-project-changelog/SKILL.md`。）
+
+## 2026-06-04
+
+- **决议**：默认抓取改为**列表级**（头图、标题、摘要、链接）；`fetch_articles` / `fetch_articles_by_ids` 的 **`blocks` 为空**；正文用 **`fetch_article_detail`**（`fetch_article` 别名）。国服按 ID 仍调详情 JSON 但只取 Title/Summary/HomeImagePath；日文列表解析 `news__list--banner` 摘要；微博默认不拉 statuses/show。新增 **`common/list_feed.py`**；example 仅导出头图。
+- **决议**：新增渠道 **`cn_weibo`**（FF14 官方微博 `@cnff14`）；`channels/cn_weibo/` 独立实现；m.weibo.cn 时间线 + statuses/show；文章 `id` 为 mblog id 字符串。
+- **决议**：新增渠道 **`jp_official`**（日文 Lodestone）；`channels/jp_official/` 独立实现；`article.id` 改为 `str`；`category_code` 可选。
+- **决议**：多渠道架构：`channels/<id>/` 分目录；门面 `FF14News.cn_official`；`NewsFeed` / `NewsArticle` 增加 `channel_id`；example 按渠道分子目录输出。
+- **决议**：实现国服渠道 `cn_official`（cqnews `CategoryCode=5310`），详情转有序 `NewsContentBlock`。
+- **决议**：在 monorepo 初始化空包 **ff14_news**，并建立包级三件套（预加载、设计笔记、changelog）。

python_library_ff14_news-0.0.0/.cursor/skills/ff14_news-package-design/SKILL.md

@@ -0,0 +1,33 @@
+---
+name: ff14-news-package-design
+description: >-
+  ff14_news 包：当前有效的设计意图；变更见 ff14_news-package-changelog。
+---
+
+# ff14_news · 设计笔记
+
+> 变更见 `.cursor/skills/ff14_news-package-changelog/SKILL.md`；矛盾以 changelog 最新为准。
+
+## 设计意图
+
+- **多渠道**：各渠道在 **`ff14_news/channels/<channel_id>/`** 独立实现，逻辑不混写；共享模型在包根 `models.py`。
+- **门面 `FF14News`**：以属性暴露渠道（如 **`cn_official`**），`channel(id)` 按标识取用。
+- **默认抓取粒度**：与旧 Selenium 列表一致——头图、标题、摘要、详情页链接；**`fetch_articles` / `fetch_articles_by_ids` 的 `blocks` 为空**。
+- **正文**：各渠道 **`fetch_article_detail`**（`fetch_article` 别名）；国服 `html_content`、日文 `detail_parser`、微博 `mblog_parser` 保留，仅默认路径不调用。
+- **列表转文章**：`ff14_news/common/list_feed.py` 的 **`article_from_list_item`**。
+- **渠道 `cn_official`**：列表 `newsList`；按 ID 补全用详情 JSON 的 Title/Summary/HomeImagePath，不 `html_to_blocks`。
+- **渠道 `cn_weibo`**：时间线 `mblog_to_list_item`；按 ID 先扫时间线，否则 statuses/show 仅取列表级字段。
+- **渠道 `jp_official`**：列表含 `news__list--banner` 摘要（纯文本 ≤200）；按 ID 先扫列表，否则 `parse_detail_metadata`。
+- 结构化输出：**`NewsFeed` / `NewsArticle` / `NewsContentBlock`**（Pydantic v2），均带 **`channel_id`**。
+
+## 硬性要求
+
+- 包目录名 **`ff14_news`**（snake_case）；PyPI 名 **`python-library-ff14-news`**。
+- 新渠道须新建子目录 + 门面属性，禁止把多站逻辑堆在同一文件。
+- 正文块保持 DOM 阅读顺序；去掉 `style`/`script` 与常见分享/版权噪音（仅 **`fetch_article_detail`** 路径）。
+- 中文禁用词见 `~/.cursor/skills/forbidden-doc-comment-vocabulary/SKILL.md`。
+
+## 备忘与待定
+
+- 第二渠道及以后：在 `channels/` 下追加子包并在 `FF14News` 注册。
+- 调度、缓存由外层任务包组合各渠道的 `fetch_articles`。

python_library_ff14_news-0.0.0/.cursor/skills/ff14_news-package-preload/SKILL.md

@@ -0,0 +1,25 @@
+---
+name: ff14-news-package-preload
+description: ff14_news 包：会话预加载；改本包源码前 Read。
+---
+
+# ff14_news · 会话预加载
+
+## 初始化加载（Session preload）
+
+在 **`packages/ff14_news/`** 下改源码、测试或 `pyproject.toml` 时，按序 **Read**：
+
+1. `~/.cursor/skills/project-skill-manifest-policy/SKILL.md`
+2. `~/.cursor/skills/forbidden-doc-comment-vocabulary/SKILL.md`
+3. `~/.cursor/skills/markdown-authoring-zh/SKILL.md`
+4. `~/.cursor/skills/python-project-ai/SKILL.md`
+5. `~/.cursor/skills/python-doc-comments/SKILL.md`
+6. `~/.cursor/skills/agent-codegen-self-review/SKILL.md`
+7. `.cursor/skills/ff14_news-package-design/SKILL.md`
+8. `.cursor/skills/ff14_news-package-changelog/SKILL.md`
+
+整库约定见仓库根 `.cursor/skills/python-library-session-manifest/SKILL.md`。
+
+## 用过的 skill（追加记录）
+
+（初始为空。）

python_library_ff14_news-0.0.0/.gitignore

@@ -0,0 +1,17 @@
+.venv/
+__pycache__/
+*.py[cod]
+*$py.class
+.pytest_cache/
+.mypy_cache/
+.ruff_cache/
+*.egg-info/
+dist/
+build/
+
+# example 抓取产物（含下载图片）
+example/output/
+
+# 微博登录 Cookie / Playwright 会话（本地私密）
+example/weibo_cookie.txt
+example/.weibo_browser_state.json

python_library_ff14_news-0.0.0/PKG-INFO

@@ -0,0 +1,8 @@
+Metadata-Version: 2.4
+Name: python-library-ff14-news
+Version: 0.0.0
+Requires-Python: >=3.10
+Requires-Dist: crawl4weibo>=0.1.0
+Requires-Dist: pydantic>=2.0
+Provides-Extra: dev
+Requires-Dist: pytest>=8.0; extra == 'dev'

python_library_ff14_news-0.0.0/README.md

@@ -0,0 +1,110 @@
+# python-library-ff14-news
+
+多渠道 FF14 新闻抓取；各渠道代码分目录实现，输出统一的 `NewsFeed` / `NewsArticle`。
+
+## 设计特性
+
+### 渠道
+
+| 标识 | 目录 | 说明 |
+| --- | --- | --- |
+| `cn_official` | `ff14_news/channels/cn_official/` | [国服官网](https://ff.web.sdo.com/web8/index.html#/newstab/newslist)，cqnews JSON（与 SPA 同源，非 Selenium） |
+| `cn_weibo` | `ff14_news/channels/cn_weibo/` | [FF14 官方微博](https://weibo.com/cnff14)，m.weibo.cn 时间线 |
+| `jp_official` | `ff14_news/channels/jp_official/` | [日文 Lodestone トピックス](https://jp.finalfantasyxiv.com/lodestone/topics/)，列表 `news__list--*` |
+
+新渠道在 `ff14_news/channels/<id>/` 下单独实现，并在门面 `FF14News` 上挂同名属性。
+
+### 返回结构
+
+- `NewsFeed`：`channel_id`、列表 URL、`articles`（顺序与对应站点列表一致）。
+- `NewsArticle`：列表级字段（`channel_id`、标题、摘要、头图、`source_page_url`）；默认 `blocks` 为空。
+- 正文块：调用各渠道 `fetch_article_detail`（`fetch_article` 为别名）后 `blocks` 才有内容。
+
+### 国服官网（cn_official）
+
+- 列表栏目 `CategoryCode=5310`；详情页链接 `newscont/{id}`。
+- `fetch_articles` / `fetch_articles_by_ids`：列表或详情 JSON 的标题、摘要、头图，不解析 HTML 正文。
+- `fetch_article_detail`：详情 `Content` 转有序 `NewsContentBlock`。
+
+### 日文官网（jp_official）
+
+- 列表：`news__list--header`（标题/时间）、`news__list--banner`（摘要，纯文本最多 200 字）、`news__list--img`。
+- `fetch_articles`：仅列表；`fetch_articles_by_ids`：先扫列表，未命中再拉详情元数据（无 blocks）。
+- `fetch_article_detail`：详情页 `news__detail__wrapper` 全文块。
+- 文章 `id` 为 Lodestone 十六进制串（非数字）。
+
+### 官方微博（cn_weibo）
+
+- 账号 `@cnff14`（uid `1784473157`）；列表自 m.weibo.cn 用户微博 tab。
+- 反爬：依赖 [crawl4weibo](https://pypi.org/project/crawl4weibo/) + **Playwright Chromium**（`example.bat` 默认经代理 `127.0.0.1:7897` 安装内核并取 Cookie）。
+- 默认无 Cookie 时由 Playwright 打开移动端页获取会话；API 经 `add_proxy` 走同一代理。也可手动配置 `cn_weibo_cookie` 或 `example/weibo_cookie.txt`。
+- `fetch_articles`：时间线列表级字段，不拉长文展开。
+- `fetch_articles_by_ids`：时间线查找或单条元数据，无 blocks。
+- `fetch_article_detail`：完整正文（含长文展开）。
+- 文章 `id` 为微博 mblog id 字符串。
+
+## 配置
+
+| 项 | 说明 |
+| --- | --- |
+| `FF14News().cn_official.category_code` | 列表栏目，默认 `5310` |
+| `FF14News(cn_official_timeout_seconds=…)` | 国服渠道 HTTP 超时 |
+| `FF14News(cn_weibo_timeout_seconds=…)` | 微博渠道 HTTP 超时（默认 60s） |
+| `FF14News(cn_weibo_cookie=…)` | 微博 Cookie 整串（跳过 Playwright 取 Cookie） |
+| `FF14News(cn_weibo_cookie_storage_path=…)` | Playwright 会话缓存路径 |
+| `FF14News(cn_weibo_browser_headless=…)` | 自动取 Cookie 时是否无头浏览器（默认 True） |
+| `FF14News(cn_weibo_proxy_url=…)` | 微博 HTTP 代理，如 `127.0.0.1:7897` |
+| `FF14News(jp_official_timeout_seconds=…)` | 日文渠道 HTTP 超时（默认 120s） |
+
+## 使用
+
+```python
+from ff14_news import FF14News
+
+news = FF14News()
+
+# 列表级（blocks 为空）
+feed = news.cn_official.fetch_articles(limit=2)
+feed_wb = news.cn_weibo.fetch_articles(limit=2)
+feed_jp = news.jp_official.fetch_articles(limit=2)
+feed = news.channel("cn_official").fetch_articles_by_ids(["387965"])
+
+# 单篇正文
+article = news.cn_official.fetch_article_detail("387965")
+
+print(feed.model_dump_json(indent=2, ensure_ascii=False))
+```
+
+## 示例
+
+`example.bat` 默认抓取**全部渠道、每渠道 2 条**，按渠道分子目录，仅下载头图：
+
+```
+example/output/
+  cn_official/
+  cn_weibo/
+  jp_official/
+    feed.json
+    {id}/article.json
+    {id}/article.md
+    {id}/images/cover.*
+```
+
+```bat
+example.bat
+example.bat --proxy 127.0.0.1:7897
+example.bat -c cn_official -n 5
+example.bat --proxy ""
+```
+
+首次运行会经代理下载 Chromium（约 180MB）。代理默认 `127.0.0.1:7897`，与本地 Clash 等一致时可不改。若仍失败，可改用手动 Cookie：`example/weibo_cookie.txt`。
+
+## 测试
+
+```bat
+pip install -e ".[dev]"
+pytest
+
+set FF14_NEWS_INTEGRATION=1
+pytest tests/test_integration.py
+```

python_library_ff14_news-0.0.0/_debug_jp_list.py

@@ -0,0 +1,11 @@
+import re
+
+from ff14_news.channels.jp_official.http_client import fetch_html
+from ff14_news.channels.jp_official.list_parser import topics_list_url
+
+html = fetch_html(topics_list_url(0), timeout_seconds=120)
+print("topics count", html.count("news__list--topics"))
+pat = r'<li class="news__list--topics[^"]*">'
+print("split", len(re.split(pat, html)))
+idx = html.find("news__list--topics")
+print("sample", repr(html[idx : idx + 100]))

python_library_ff14_news-0.0.0/_debug_jp_list2.py

@@ -0,0 +1,17 @@
+import re
+
+from ff14_news.channels.jp_official.http_client import fetch_html
+from ff14_news.channels.jp_official.list_parser import (
+    _parse_item_fragment,
+    topics_list_url,
+)
+
+html = fetch_html(topics_list_url(0), timeout_seconds=120)
+pat = re.compile(r'<li class="news__list--topics[^"]*">')
+frags = pat.split(html)
+print("frags", len(frags))
+frag = frags[1]
+print("frag len", len(frag))
+print("id re", bool(re.search(r"/lodestone/topics/detail/([a-f0-9]+)/", frag)))
+row = _parse_item_fragment(frag)
+print("row", row)

python_library_ff14_news-0.0.0/_debug_jp_list3.py

@@ -0,0 +1,13 @@
+import re
+
+from ff14_news.channels.jp_official.http_client import fetch_html
+from ff14_news.channels.jp_official.list_parser import topics_list_url
+
+html = fetch_html(topics_list_url(0), timeout_seconds=120)
+pat = re.compile(r'<li class="news__list--topics[^"]*">')
+frag = pat.split(html)[1]
+links = re.findall(r"/lodestone/topics/detail/[^\"']+", frag)
+print("links", links[:3])
+# maybe uppercase
+links2 = re.findall(r"/lodestone/topics/detail/([A-Fa-f0-9]+)", frag)
+print("ids", links2[:3])