feat(article): parse, render and translate X articles on a reader page

.agents/skills/anon-tweet/SKILL.md

@@ -4,16 +4,17 @@ description: >-
   匿名浏览 Twitter/X 推文与 Instagram 帖子的 API 使用指南（BFF 聚合接口，读取无需 API Key）。
   用 /api/tweet/search 按关键词或 X 高级语法搜索推文、/api/tweet/get/{id} 与
   /api/tweet/replies/{id} 读取单条推文及回复、/api/user/get/{username} 查询用户资料、
-  /api/ig/get/{id} 拉取 IG 帖子（caption/媒体），另有 AI 翻译与图片代理接口。
-  当需要搜索/抓取推文、查看 X 用户资料或 IG 帖子内容时使用。
+  /api/ig/get/{id} 拉取 IG 帖子（caption/媒体），长文推文还会带 X Article（标题 + 块文档正文），
+  另有 AI 翻译（推文 / IG / 长文按块）与图片代理接口。
+  当需要搜索/抓取推文、读取 X 长文、查看 X 用户资料或 IG 帖子内容时使用。
 license: MIT
 compatibility: 需要 PowerShell 7+（pwsh）与网络访问部署实例；纯 PowerShell 封装，不依赖 curl/python3
 metadata:
   author: Chilfish
-  version: "1.2.0"
+  version: "1.3.0"
   base-url: https://anon-tweet.chilfish.top
   repository: https://github.com/Chilfish/anonTweet
-  updated: "2026-09-12"
+  updated: "2026-09-27"
 ---
 
 # Anon Tweet API
@@ -29,6 +30,7 @@ metadata:
 
 - 搜索推文（关键词 / hashtag / 用户 / 高级语法过滤）
 - 读取单条推文、其回复列表或 List 时间线
+- 读取 X 长文（Article）：`/api/tweet/get/{id}` 对文章推文返回 `article`（标题 + 块文档正文）
 - 查询 X 用户资料
 - 拉取 Instagram 帖子（caption / 媒体 / 标签）或翻译 caption
 - 在页面上展示 IG 图片时走图片代理绕过 CDN CORS
@@ -54,15 +56,15 @@ pwsh -NoProfile -File $A help
 | 方法 | 路径 | 用途 |
 | --- | --- | --- |
 | GET | `/api/tweet/search?q=...` | 推文搜索（核心，支持 X 高级语法） |
-| GET | `/api/tweet/get/{id}` | 单条推文（三层缓存 → Twitter 原文；返回 EnrichedTweet 数组，可能为空） |
+| GET | `/api/tweet/get/{id}` | 单条推文（三层缓存 → Twitter 原文；文章推文另含 `article` 块文档） |
 | GET | `/api/tweet/replies/{id}?cursor=...` | 推文回复（cursor 分页） |
 | GET | `/api/tweet/list/{id}` | List 时间线（EnrichedTweet 数组） |
 | GET | `/api/user/get/{username}` | 用户资料（DB 缓存，无记录返回 null） |
 | GET | `/api/user/timeline/{username}` | 用户时间线（EnrichedTweet 数组） |
 | GET | `/api/ig/get/{id}` | IG 帖子（id 为 shortcode；未配 INS_COOKIES 返回空数组） |
 | POST | `/api/ig/translate/{id}` | IG caption 翻译（manualTranslation 传入则跳过 AI） |
 | GET | `/api/proxy/image?url=...` | 图片代理（url 白名单校验，返回二进制） |
-| POST | `/api/ai-translation` | 通用 AI 翻译（type + tweet/igPost） |
+| POST | `/api/ai-translation` | 通用 AI 翻译（`type`: twitter / ins / article） |
 | POST | `/api/ai-vision` | 图片/视频 AI 描述 |
 | POST | `/api/bili-post` | B 站动态抓取 |
 
@@ -116,7 +118,9 @@ Invoke-RestMethod "https://anon-tweet.chilfish.top/api/ig/translate/DWlrun0AVbE"
 
 ## 数据结构要点
 
-- **EnrichedTweet**: `id_str`、`text`、`url`、`lang`（如 en/ja/zxx）、`created_at`（ISO 8601）、`user`（TweetUser）、`entities`（Entity[]），可选 `quoted_tweet_id` / `card` / `mediaDetails` / `visionInfo`
+- **EnrichedTweet**: `id_str`、`text`、`url`、`lang`（如 en/ja/zxx）、`created_at`（ISO 8601）、`user`（TweetUser）、`entities`（Entity[]），可选 `quoted_tweet_id` / `card` / `mediaDetails` / `visionInfo` / `article`
+- **TweetArticle**（文章推文才有）: `id`、`url`、`title`、`previewText`、`plainText`、`format`（`rich` 带 `blocks`，`plain` 仅纯文本）、`coverImage`、`publishedAt`（epoch ms）、`blocks`（ArticleBlock[]）
+- **ArticleBlock**: `type` ∈ paragraph / heading / list-item / quote / markdown / divider / image / embed-tweet / link / unknown；`key` 为稳定块 ID；段落类带 `runs`（文本/链接/mention/hashtag）；`text`（markdown）、`media`（image）、`tweetId`（embed-tweet）
 - **TweetUser**: `id_str`、`name`、`screen_name`、`profile_image_url_https`、`verified`、`is_blue_verified`、`verified_type`（Business/Government）、`profile_image_shape`（Circle/Square/Hexagon）
 - **Entity**: `type` ∈ text / hashtag / mention / url / media / symbol / media_alt / separator；`index` 为文本偏移；hashtag/mention/url/media/symbol 带 `href`；`aiTranslation` / `translation` 存翻译
 - **SearchResponse / RepliesResponse**: `{ tweets: EnrichedTweet[], nextCursor: string | null }`

.agents/skills/anon-tweet/references/anon-tweet-openapi.json

@@ -401,7 +401,7 @@
           "Tweet"
         ],
         "operationId": "tweetSet",
-        "summary": "保存推文实体编辑",
+        "summary": "保存推文实体编辑或文章按块译文",
         "requestBody": {
           "required": true,
           "content": {
@@ -415,16 +415,18 @@
                 "properties": {
                   "intent": {
                     "type": "string",
-                    "const": "updateEntities"
+                    "enum": [
+                      "updateEntities",
+                      "updateArticleTranslations"
+                    ]
                   },
                   "data": {
                     "type": "array",
-                    "description": "每项包含 tweetId 与 entities（TranslationEntity[]）",
+                    "description": "updateEntities：每项 { tweetId, entities }；updateArticleTranslations：每项 { tweetId, translation }",
                     "items": {
                       "type": "object",
                       "required": [
-                        "tweetId",
-                        "entities"
+                        "tweetId"
                       ],
                       "properties": {
                         "tweetId": {
@@ -434,7 +436,12 @@
                           "type": "array",
                           "items": {
                             "$ref": "#/components/schemas/TranslationEntity"
-                          }
+                          },
+                          "description": "intent=updateEntities 时必填"
+                        },
+                        "translation": {
+                          "$ref": "#/components/schemas/ArticleTranslation",
+                          "description": "intent=updateArticleTranslations 时必填"
                         }
                       }
                     }
@@ -952,7 +959,7 @@
         ],
         "operationId": "aiTranslation",
         "summary": "统一 AI 翻译端点",
-        "description": "type=twitter（默认）翻译推文实体；type=ins 翻译 IG caption。baseUrl 走 ENABLE_AI_BASE_URL_WHITELIST 可选白名单（AC-SEC-001）。",
+        "description": "type=twitter（默认）翻译推文实体；type=ins 翻译 IG caption；type=article 按块翻译 X 长文。baseUrl 走 ENABLE_AI_BASE_URL_WHITELIST 可选白名单（AC-SEC-001）。",
         "requestBody": {
           "required": true,
           "content": {
@@ -964,7 +971,8 @@
                     "type": "string",
                     "enum": [
                       "twitter",
-                      "ins"
+                      "ins",
+                      "article"
                     ],
                     "default": "twitter"
                   },
@@ -976,6 +984,10 @@
                     "$ref": "#/components/schemas/IGPost",
                     "description": "type=ins 时必填"
                   },
+                  "article": {
+                    "$ref": "#/components/schemas/TweetArticle",
+                    "description": "type=article 时必填"
+                  },
                   "enableAITranslation": {
                     "type": "boolean",
                     "description": "twitter 分支守卫"
@@ -1049,6 +1061,14 @@
                         "captionTranslation": {
                           "type": "string",
                           "description": "ins 分支"
+                        },
+                        "articleId": {
+                          "type": "string",
+                          "description": "article 分支"
+                        },
+                        "translation": {
+                          "$ref": "#/components/schemas/ArticleTranslation",
+                          "description": "article 分支：按块 key 的译文"
                         }
                       }
                     }
@@ -1068,7 +1088,7 @@
             }
           },
           "404": {
-            "description": "tweet/igPost 缺失",
+            "description": "tweet / igPost / article 缺失",
             "content": {
               "application/json": {
                 "schema": {
@@ -1696,6 +1716,10 @@
             "type": "object",
             "description": "X Space 卡片（SpaceDetails，见 app/types/space.ts；仅 Space 推文有）"
           },
+          "article": {
+            "$ref": "#/components/schemas/TweetArticle",
+            "description": "X 长文卡片与块文档（app/types/article.ts；仅文章推文有）"
+          },
           "comments": {
             "type": "array",
             "items": {
@@ -1719,6 +1743,206 @@
         },
         "additionalProperties": true
       },
+      "TweetArticle": {
+        "type": "object",
+        "description": "X 长文（Article）数据（app/types/article.ts TweetArticle），挂在 EnrichedTweet.article",
+        "required": [
+          "id",
+          "url",
+          "title",
+          "format"
+        ],
+        "properties": {
+          "id": {
+            "type": "string",
+            "description": "文章 rest_id（与推文 id 不同）"
+          },
+          "url": {
+            "type": "string",
+            "format": "uri",
+            "description": "文章永久链接"
+          },
+          "title": {
+            "type": "string"
+          },
+          "previewText": {
+            "type": "string",
+            "description": "摘要"
+          },
+          "plainText": {
+            "type": "string",
+            "description": "纯文本全文（content_state 缺失时的兜底）"
+          },
+          "format": {
+            "type": "string",
+            "enum": [
+              "rich",
+              "plain"
+            ],
+            "description": "rich 表示 blocks 可用；plain 仅纯文本"
+          },
+          "coverImage": {
+            "$ref": "#/components/schemas/ArticleMedia"
+          },
+          "publishedAt": {
+            "type": "integer",
+            "description": "首次发布时间（epoch ms）"
+          },
+          "blocks": {
+            "type": "array",
+            "items": {
+              "$ref": "#/components/schemas/ArticleBlock"
+            },
+            "description": "块文档（format=rich 时存在）"
+          }
+        },
+        "additionalProperties": true
+      },
+      "ArticleMedia": {
+        "type": "object",
+        "description": "文章内嵌媒体（图片）",
+        "required": [
+          "id",
+          "url"
+        ],
+        "properties": {
+          "id": {
+            "type": "string"
+          },
+          "url": {
+            "type": "string",
+            "format": "uri"
+          },
+          "width": {
+            "type": "integer"
+          },
+          "height": {
+            "type": "integer"
+          },
+          "alt": {
+            "type": "string"
+          }
+        }
+      },
+      "ArticleBlock": {
+        "type": "object",
+        "description": "文章块（Draft.js block 语义化，app/types/article.ts ArticleBlock）。type 判别：段落类带 runs；markdown 带 text；image 带 media；embed-tweet 带 tweetId。",
+        "required": [
+          "key",
+          "type"
+        ],
+        "properties": {
+          "key": {
+            "type": "string",
+            "description": "稳定块 ID（按块翻译与渲染对齐用）"
+          },
+          "type": {
+            "type": "string",
+            "enum": [
+              "paragraph",
+              "heading",
+              "list-item",
+              "quote",
+              "markdown",
+              "divider",
+              "image",
+              "embed-tweet",
+              "link",
+              "unknown"
+            ]
+          },
+          "runs": {
+            "type": "array",
+            "description": "段落的行内片段（文本 / link / mention / hashtag，带样式）",
+            "items": {
+              "type": "object",
+              "properties": {
+                "type": {
+                  "type": "string",
+                  "enum": [
+                    "text",
+                    "link",
+                    "mention",
+                    "hashtag"
+                  ]
+                },
+                "text": {
+                  "type": "string"
+                },
+                "url": {
+                  "type": "string",
+                  "description": "type=link"
+                },
+                "href": {
+                  "type": "string",
+                  "description": "type=mention / hashtag"
+                },
+                "styles": {
+                  "type": "array",
+                  "items": {
+                    "type": "string",
+                    "enum": [
+                      "bold",
+                      "italic",
+                      "strikethrough"
+                    ]
+                  }
+                }
+              }
+            }
+          },
+          "level": {
+            "type": "integer",
+            "enum": [
+              1,
+              2,
+              3
+            ],
+            "description": "heading 级别"
+          },
+          "ordered": {
+            "type": "boolean",
+            "description": "list-item 是否有序"
+          },
+          "text": {
+            "type": "string",
+            "description": "markdown 块的原始 GFM"
+          },
+          "media": {
+            "$ref": "#/components/schemas/ArticleMedia",
+            "description": "image 块"
+          },
+          "caption": {
+            "type": "string",
+            "description": "image 块说明"
+          },
+          "tweetId": {
+            "type": "string",
+            "description": "embed-tweet 块的推文 id"
+          },
+          "url": {
+            "type": "string",
+            "description": "link 块 URL"
+          }
+        },
+        "additionalProperties": true
+      },
+      "ArticleTranslation": {
+        "type": "object",
+        "description": "文章按块译文（app/lib/article/translate.ts ArticleTranslation）：title + 块 key → 译文",
+        "properties": {
+          "title": {
+            "type": "string"
+          },
+          "blocks": {
+            "type": "object",
+            "additionalProperties": {
+              "type": "string"
+            },
+            "description": "块 key → 译文（link / mention / hashtag 以 <<__LINK_n__>> 占位符锚定）"
+          }
+        }
+      },
       "IGAudio": {
         "type": "object",
         "description": "IG 帖子附带音频/音乐信息（app/types/ins.ts IGAudio）",
@@ -2042,4 +2266,4 @@
       }
     }
   }
-}
+}