@tikomni/skills 0.1.8 → 0.1.10

package/README.md

@@ -79,7 +79,56 @@ The npm package currently exposes:
 
 ### 2. Install skills
 
-Install directly from npm.
+Before installation, prepare:
+
+- `Node.js >= 18`
+- `Python 3`
+
+Common setup commands:
+
+macOS (Homebrew):
+
+```bash
+# If Homebrew is not installed yet:
+/bin/bash -c "$(curl -fsSL https://raw.githubusercontent.com/Homebrew/install/HEAD/install.sh)"
+
+brew install node
+brew install python
+
+node -v
+npm -v
+python3 --version
+```
+
+Linux (Ubuntu / Debian; also works in WSL):
+
+```bash
+sudo apt update
+sudo apt install -y curl python3 python3-pip
+
+curl -o- https://raw.githubusercontent.com/nvm-sh/nvm/v0.40.3/install.sh | bash
+export NVM_DIR="$HOME/.nvm"
+[ -s "$NVM_DIR/nvm.sh" ] && . "$NVM_DIR/nvm.sh"
+
+nvm install --lts
+
+node -v
+npm -v
+python3 --version
+```
+
+Windows (PowerShell):
+
+```powershell
+winget install -e --id OpenJS.NodeJS.LTS
+winget install -e --id Python.Python.3
+
+node -v
+npm -v
+python --version
+```
+
+After that, install directly from npm.
 
 First, list the currently available skills:
 

package/README.zh-CN.md

@@ -79,7 +79,56 @@
 
 ### 2. 安装 Skills
 
-使用 npm 直接安装。
+安装前请先准备：
+
+- `Node.js >= 18`
+- `Python 3`
+
+常见安装命令：
+
+macOS（Homebrew）：
+
+```bash
+# 如未安装 Homebrew，先执行：
+/bin/bash -c "$(curl -fsSL https://raw.githubusercontent.com/Homebrew/install/HEAD/install.sh)"
+
+brew install node
+brew install python
+
+node -v
+npm -v
+python3 --version
+```
+
+Linux（Ubuntu / Debian；WSL 可同样使用）：
+
+```bash
+sudo apt update
+sudo apt install -y curl python3 python3-pip
+
+curl -o- https://raw.githubusercontent.com/nvm-sh/nvm/v0.40.3/install.sh | bash
+export NVM_DIR="$HOME/.nvm"
+[ -s "$NVM_DIR/nvm.sh" ] && . "$NVM_DIR/nvm.sh"
+
+nvm install --lts
+
+node -v
+npm -v
+python3 --version
+```
+
+Windows（PowerShell）：
+
+```powershell
+winget install -e --id OpenJS.NodeJS.LTS
+winget install -e --id Python.Python.3
+
+node -v
+npm -v
+python --version
+```
+
+准备完成后，使用 npm 直接安装。
 
 先查看当前可安装的 Skills：
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@tikomni/skills",
-  "version": "0.1.8",
+  "version": "0.1.10",
   "description": "TikOmni skill installer CLI for structured social media crawling in Codex, Claude Code, and OpenClaw",
   "license": "MIT",
   "homepage": "https://github.com/mark-ly-wang/TikOmni-Skills#readme",

package/skills/social-media-crawl/SKILL.md

@@ -7,48 +7,66 @@ description: Use this skill when the user asks about social media links, posts,
 
 ## When To Use
 
-- 当用户要处理社交媒体对象时使用，例如作品链接、作者主页、评论线程、搜索结果、榜单、直播间、商品页。
-- 当用户提到抓取、采集、获取、主页、评论、搜索、榜单、直播、商品、社交媒体等需求时使用。
-- 当输入是分享短链、作品 URL、主页 URL、平台 ID、关键词或页面入口时使用。
+- Use this skill when the user needs any social-media object such as a work link, post, thread, long-form post, creator homepage, comment section, search result, ranking page, livestream room, or product page.
+- Use this skill when the input is a share short link, work URL, post URL, thread URL, homepage URL, platform ID, keyword, or entry page.
+- Route social-media retrieval requests through this skill first.
+
+## Supported Platforms
+
+- The currently supported platforms include Douyin, Xiaohongshu, Kuaishou, Bilibili, Weibo, TikTok, YouTube, Instagram, Threads, Twitter/X, Reddit, LinkedIn, WeChat Channels, Official Accounts, Toutiao, Xigua, Zhihu, Lemon8, and Pipixia.
+- Only four fixed pipelines are currently frozen: Douyin single work, Douyin creator home, Xiaohongshu single work, and Xiaohongshu creator home.
+- All other supported platform and object combinations should use the generic MCP workflow inside this skill.
+- See the official documentation for the full platform catalog and update policy: https://docs.tikomni.com
 
 ## What To Help With
 
-- 识别平台和对象类型。
-- 优先处理单作品、作者主页和内容集合。
-- 获取事实字段、平台文案、字幕或转写文本。
-- 返回结构化 JSON，并在需要时写入事实卡。
+- Detect the platform and object type.
+- Prefer single work, single post, thread, creator homepage, and content collection tasks.
+- Collect factual fields, platform text, subtitles, or transcript text.
+- Return structured JSON and write fact cards when required.
 
 ## Preferred Routing
 
-- 如果对象是以下 4 类，优先走固定 pipeline：
-  1. 抖音单作品
-  2. 小红书单作品
-  3. 抖音作者主页
-  4. 小红书作者主页
-- 其他对象优先走 MCP 工具链。
+- Route all social-media objects into this skill first; do not jump straight to browser/CDP only because a fixed pipeline does not match.
+- If the object is one of the following four cases, prefer the fixed pipeline:
+  1. Douyin single work
+  2. Xiaohongshu single work
+  3. Douyin creator home
+  4. Xiaohongshu creator home
+- If no fixed pipeline matches, stay inside this skill and use the generic MCP path: `tools/list -> catalog.search -> endpoint.describe -> api.call`.
+- Use browser/CDP only when both the fixed pipeline and the generic MCP path are unavailable, or when the task explicitly requires page-level interaction that the API cannot satisfy. Record the reason in the result.
 
 ## Working Style
 
-- 先看用户给的对象是什么，再选固定 pipeline 或 MCP 工具。
-- 优先返回事实字段，不补充主观分析。
-- 视频文本优先使用平台原生字幕；拿不到再走 ASR。
-- 默认输出以结构化 JSON 和Markdown并主动落库。
-- 当固定pipeline时，默认执行抓取并落库（强制）。
+- Detect the platform and object type first, then choose between a fixed pipeline and the generic MCP path.
+- Treat browser/CDP as a fallback, not the default option.
+- Prioritize factual fields and avoid subjective analysis.
+- Prefer native subtitles for video text; use ASR only when subtitles are unavailable.
+- Default to structured JSON plus Markdown and persist outputs proactively.
+- When a fixed pipeline matches, execute it and persist outputs by default.
+
+## Typical Examples
+
+- Extract the body text and factual fields from a single X/Twitter post.
+- Collect TikTok comment data and normalize it into a unified structured result.
+- Extract a creator profile and content collection from a homepage.
+- Collect the top N comments from a comment section.
+- Collect search results, ranking pages, livestream rooms, or product pages.
 
 ## Workflow
 
-1. 识别平台和对象类型。
-2. 若命中固定 pipeline，直接运行固定脚本。
-3. 若未命中固定 pipeline，先调用 `tools/list`，再按 `catalog.search -> endpoint.describe -> api.call` 选择合适接口。
-4. 如果需要视频文本，执行 `u2.submit -> u2.query`；超过阈值仍未完成时走 U3 fallback。
-5. 整理为结构化结果。
-6. 若对象是作品，写入 `work_fact_card`。
+1. Detect the platform and object type.
+2. If a fixed pipeline matches, run the fixed script directly.
+3. If no fixed pipeline matches, call `tools/list` first, then choose the smallest MCP toolchain through `catalog.search -> endpoint.describe -> api.call`.
+4. If video text is required, run `u2.submit -> u2.query`; if it is still unfinished after the timeout, enter the U3 fallback path.
+5. Normalize the result into a structured payload.
+6. If the object is a work, write `work_fact_card`.
 
 ## References
 
-- MCP 使用契约：`references/mcp-usage-contract.md`
-- 输出 envelope：`references/contracts/output-envelope.md`
-- 作品事实卡字段：`references/contracts/work-fact-card-fields.md`
-- 泛对象 MCP 指引：`references/guides/generic-mcp-objects.md`
-- U2/U3 规则：`references/service-guides/u2-u3-mandatory-fallback.md`
-- 固定 pipeline 指南：`references/pipelines/`
+- MCP usage contract: `references/mcp-usage-contract.md`
+- Output envelope: `references/contracts/output-envelope.md`
+- Work fact card fields: `references/contracts/work-fact-card-fields.md`
+- Generic MCP object guide: `references/guides/generic-mcp-objects.md`
+- U2/U3 rules: `references/service-guides/u2-u3-mandatory-fallback.md`
+- Fixed pipeline guides: `references/pipelines/`

package/skills/social-media-crawl/agents/openai.yaml

@@ -1,5 +1,4 @@
 interface:
   display_name: "Social Media Crawl"
-  short_description: "Structured social-media retrieval, transcription, and archival"
-  default_prompt: "Use $social-media-crawl to fetch, transcribe, normalize, and archive a concrete social-media object into structured JSON and work fact cards."
-
+  short_description: "Cross-platform structured social-media retrieval and archival"
+  default_prompt: "Use $social-media-crawl to fetch, transcribe, normalize, and archive social-media objects into structured JSON and work fact cards. Supported platforms include Douyin, Xiaohongshu, Kuaishou, Bilibili, Weibo, TikTok, YouTube, Instagram, Threads, Twitter/X, Reddit, LinkedIn, WeChat Channels, WeChat Official Accounts, Toutiao, Xigua, Zhihu, Lemon8, and Pipixia. Use fixed pipelines for Douyin/Xiaohongshu single-work and creator-home requests; use the MCP generic flow for other supported platforms and objects; use browser fallback only when the fixed pipelines and MCP path are insufficient."

package/skills/social-media-crawl/references/contracts/output-envelope.md

@@ -14,9 +14,8 @@
 
 ## Semantics
 
-- `normalized` 只存结构化事实，不存分析推断。
-- `completeness` 允许值：`complete`、`partial`、`incomplete`。
-- `missing_fields` 是缺失字段列表。
-- `error_reason` 成功时可为空字符串或 `null`。
-- `extract_trace` 记录固定 pipeline 或 MCP 调度步骤。
-
+- `normalized` stores structured facts only, not analytical inference.
+- `completeness` allows `complete`, `partial`, and `incomplete`.
+- `missing_fields` is the list of missing fields.
+- `error_reason` may be an empty string or `null` on success.
+- `extract_trace` records the fixed-pipeline or MCP dispatch steps. If the flow ends in browser/CDP fallback, it must also record the earlier MCP attempts and the fallback reason.

package/skills/social-media-crawl/references/contracts/work-fact-card-fields.md

@@ -36,15 +36,15 @@
 
 ## Field Rules
 
-- `author` 是展示名，不是对象。
-- Markdown 卡片的事实字段进入 frontmatter，不再输出 `## Facts` 章节。
-- 作品库目录只写 Markdown 卡片，不再额外写同目录 `.json` sidecar。
-- `primary_text` 为当前任务最适合阅读和索引的主文本。
-- `play_count` 允许为 `null`；缺失时卡片展示为空，只有平台明确返回 `0` 时才保留 `0`。
-- 视频优先顺序：
+- `author` is the display name, not an object.
+- Fact fields for the Markdown card go into frontmatter. Do not emit a separate `## Facts` section.
+- The work-library directory writes only the Markdown card and no extra `.json` sidecar in the same directory.
+- `primary_text` is the text that is best suited for reading and indexing in the current task.
+- `play_count` may be `null`. Leave it empty when missing, and keep `0` only when the platform explicitly returns `0`.
+- Preferred order for video works:
   - `subtitle_raw`
   - `asr_clean`
   - `caption_raw`
-- 文本作品优先顺序：
+- Preferred order for text works:
   - `caption_raw`
-- 不允许出现分析字段。
+- Do not add analytical fields.

package/skills/social-media-crawl/references/guides/generic-mcp-objects.md

@@ -1,20 +1,31 @@
 # Generic MCP Objects Guide
 
-以下对象在首期不冻结细粒度 schema：
+The following objects do not freeze a fine-grained schema in the first release:
 
-- 评论线程
-- 搜索结果
-- 榜单
-- 直播间
-- 商品页
+- Comment threads
+- Search results
+- Ranking pages
+- Livestream rooms
+- Product pages
+
+In addition, every platform and object combination that does not match a fixed pipeline falls under this guide, for example:
+
+- A single X/Twitter post
+- An X/Twitter thread
+- An X/Twitter long-form post
+- An X/Twitter creator homepage
+- The top N comments from a comment section
 
 ## Rules
 
-- 这些对象统一走 MCP 通用工作流。
-- agent 先做对象识别，再用 `catalog.search` 和 `endpoint.describe` 选最小工具链。
-- 输出必须满足统一 envelope。
-- 不要求首期落卡。
-- 不允许为了 schema 完整性去编造字段。
+- Route these objects through the generic MCP workflow inside this skill.
+- The platform is not limited to the Douyin and Xiaohongshu cases covered by fixed pipelines. If the platform is discoverable in the MCP catalog, try this workflow first.
+- Detect the object first, then use `catalog.search` and `endpoint.describe` to choose the smallest toolchain.
+- Do not jump to browser/CDP only because the platform is not Douyin or Xiaohongshu.
+- Use browser/CDP only when the generic MCP path is unavailable, or when the task explicitly requires page-level interaction that the API cannot satisfy. Explain the reason in the output.
+- The output must satisfy the unified envelope.
+- No card write is required in the first release.
+- Do not fabricate fields only to satisfy schema completeness.
 
 ## Minimum Deliverable
 
@@ -27,4 +38,3 @@
 - `missing_fields`
 - `error_reason`
 - `extract_trace`
-

package/skills/social-media-crawl/references/mcp-usage-contract.md

@@ -1,30 +1,40 @@
 # MCP Usage Contract
 
+## Scope
+
+- This contract applies to every social-media object that does not match a fixed pipeline, not only Douyin and Xiaohongshu.
+- The currently supported platforms include Douyin, Xiaohongshu, Kuaishou, Bilibili, Weibo, TikTok, YouTube, Instagram, Threads, Twitter/X, Reddit, LinkedIn, WeChat Channels, Official Accounts, Toutiao, Xigua, Zhihu, Lemon8, and Pipixia.
+- Typical objects include X/Twitter posts, threads, long-form posts, creator homepages, comment sections, search results, ranking pages, livestream rooms, and product pages.
+- Fixed pipelines are frozen only for Douyin and Xiaohongshu single-work and creator-home cases. All other supported platform and object combinations should use the generic MCP path defined here.
+
 ## Fixed Inputs
 
 - MCP URL: `https://mcp.tikomni.com/mcp`
 - Auth: `Authorization: Bearer <TIKOMNI_API_KEY>`
-- 不在工具参数中重复传 API key
+- Do not repeat the API key inside tool parameters.
 
 ## Required Tool Order
 
-1. `tools/list`
-2. 识别是否命中固定 pipeline
-3. 若不命中固定 pipeline：
+1. Detect the platform and object type.
+2. Decide whether a fixed pipeline matches.
+3. If a fixed pipeline matches, run the fixed script directly and do not enter the generic MCP path.
+4. If no fixed pipeline matches:
+   - `tools/list`
    - `catalog.search`
    - `endpoint.describe`
    - `api.call`
-4. 若需要视频文本：
+5. If video text is required:
    - `u2.submit`
    - `u2.query`
-   - 超过 60 秒仍 `pending` 时进入 U3 fallback
+   - Enter the U3 fallback path if the task is still `pending` after 60 seconds.
+6. Use browser/CDP only when the generic MCP path is unavailable or clearly insufficient. Do not skip step 4 and jump straight to browser/CDP.
 
 ## Output Rules
 
-- 事实字段与派生元数据分离
-- 结果必须包含 `request_id`
-- 结果必须包含 `completeness`
-- 结果必须包含 `missing_fields`
-- 结果必须包含 `error_reason`
-- 结果必须包含 `extract_trace`
-
+- Keep factual fields separate from derived metadata.
+- The result must include `request_id`.
+- The result must include `completeness`.
+- The result must include `missing_fields`.
+- The result must include `error_reason`.
+- The result must include `extract_trace`.
+- If the flow ends in browser/CDP fallback, `extract_trace` must also include the earlier MCP attempts and the fallback reason.

package/skills/social-media-crawl/references/pipelines/douyin-creator-home.md

@@ -1,7 +1,6 @@
 # Douyin Creator Home
 
-- 输入：主页链接或分享短链
-- 输出：`creator_profile.json`、`work_collection.json`、多张 `work_fact_card`
-- 实现脚本：`scripts/pipelines/run_douyin_creator_home.py`
-- 必测样例：计划冻结样例中的抖音主页链接
-
+- Input: a homepage URL or share short link
+- Output: `creator_profile.json`, `work_collection.json`, and multiple `work_fact_card` files
+- Implementation script: `scripts/pipelines/run_douyin_creator_home.py`
+- Required test sample: the frozen Douyin creator-home sample defined by the plan

package/skills/social-media-crawl/references/pipelines/douyin-single-work.md

@@ -1,7 +1,6 @@
 # Douyin Single Work
 
-- 输入：作品链接或分享短链
-- 输出：统一 `work_fact_card`
-- 实现脚本：`scripts/pipelines/run_douyin_single_work.py`
-- 必测样例：计划冻结样例中的抖音作品链接
-
+- Input: a work URL or share short link
+- Output: a unified `work_fact_card`
+- Implementation script: `scripts/pipelines/run_douyin_single_work.py`
+- Required test sample: the frozen Douyin work sample defined by the plan

package/skills/social-media-crawl/references/pipelines/xiaohongshu-creator-home.md

@@ -1,7 +1,6 @@
 # Xiaohongshu Creator Home
 
-- 输入：主页链接或分享短链
-- 输出：`creator_profile.json`、`work_collection.json`、多张 `work_fact_card`
-- 实现脚本：`scripts/pipelines/run_xiaohongshu_creator_home.py`
-- 必测样例：计划冻结样例中的小红书主页链接
-
+- Input: a homepage URL or share short link
+- Output: `creator_profile.json`, `work_collection.json`, and multiple `work_fact_card` files
+- Implementation script: `scripts/pipelines/run_xiaohongshu_creator_home.py`
+- Required test sample: the frozen Xiaohongshu creator-home sample defined by the plan

package/skills/social-media-crawl/references/pipelines/xiaohongshu-single-work.md

@@ -1,7 +1,6 @@
 # Xiaohongshu Single Work
 
-- 输入：作品链接或分享短链
-- 输出：统一 `work_fact_card`
-- 实现脚本：`scripts/pipelines/run_xiaohongshu_single_work.py`
-- 必测样例：计划冻结样例中的小红书作品链接
-
+- Input: a work URL or share short link
+- Output: a unified `work_fact_card`
+- Implementation script: `scripts/pipelines/run_xiaohongshu_single_work.py`
+- Required test sample: the frozen Xiaohongshu work sample defined by the plan

package/skills/social-media-crawl/references/service-guides/u2-u3-mandatory-fallback.md

@@ -2,20 +2,19 @@
 
 ## Hard Rule
 
-- 视频文本优先尝试平台原生字幕。
-- 无原生字幕时先走 U2。
-- `u2.submit` 成功后，最多轮询 60 秒。
-- 如果 60 秒后仍是 `pending`，必须进入 U3 fallback。
-- U3 成功后继续完成 ASR 链路。
-- 若最终失败，保留事实卡并标记 `completeness=incomplete`。
+- Prefer native platform subtitles for video text.
+- If native subtitles are unavailable, use U2 first.
+- After `u2.submit` succeeds, poll for at most 60 seconds.
+- If the task is still `pending` after 60 seconds, enter the U3 fallback path.
+- If U3 succeeds, continue and complete the ASR path.
+- If the flow still fails, keep the fact card and mark `completeness=incomplete`.
 
 ## Trace Requirement
 
-至少记录：
+Record at least:
 
 - U2 submit
 - U2 poll
-- 触发 U3 的原因
-- U3 调用步骤
-- 最终文本来源
-
+- The reason that triggered U3
+- The U3 invocation steps
+- The final text source

package/skills/social-media-crawl/scripts/core/mcp_dispatch.py

@@ -48,6 +48,9 @@ class McpHttpClient:
             "Authorization": f"Bearer {self.api_key}",
             "Content-Type": "application/json",
             "Accept": "application/json, text/event-stream",
+            "User-Agent": "OpenClaw-SocialMediaCrawl/0.1",
+            "X-Client-Name": "social-media-crawl",
+            "X-Client-Version": "0.1.0",
         }
         if self.session_id:
             headers["mcp-session-id"] = self.session_id

package/skills/social-media-crawl/scripts/core/tikomni_common.py

@@ -257,6 +257,13 @@ def _resolve_timeout_retry_backoff_ms() -> int:
     return max(0, min(backoff, 5000))
 
 
+def resolve_timeout_retry_policy() -> Dict[str, int]:
+    return {
+        "max_retries": _resolve_timeout_retry_max(),
+        "backoff_ms": _resolve_timeout_retry_backoff_ms(),
+    }
+
+
 def _wait_rate_limit_slot(qps: float) -> int:
     global _NEXT_ALLOWED_TS
     interval_sec = 1.0 / max(qps, 0.1)

package/skills/social-media-crawl/scripts/core/u3_fallback.py

@@ -5,18 +5,26 @@ from __future__ import annotations
 
 import mimetypes
 import os
+import socket
 import tempfile
+import time
 import urllib.error
 import urllib.parse
 import urllib.request
 from pathlib import Path
-from typing import Any, Dict, Optional
+from typing import Any, Dict, List, Optional
 
-from scripts.core.tikomni_common import DEFAULT_USER_AGENT, call_json_api, normalize_text
+from scripts.core.tikomni_common import (
+    DEFAULT_USER_AGENT,
+    call_json_api,
+    normalize_text,
+    resolve_timeout_retry_policy,
+)
 
 DEFAULT_U3_PROVIDER = "oss"
 DEFAULT_CONTENT_TYPE = "video/mp4"
 DOWNLOAD_CHUNK_SIZE = 1024 * 1024
+TIMEOUT_LIKE_HTTP_STATUS_CODES = {408, 429, 502, 503, 504}
 
 
 def _safe_name_from_url(source_url: str) -> str:
@@ -135,6 +143,16 @@ def create_u3_upload(
     )
 
 
+def _is_timeout_like_upload_error(status_code: Optional[int], error_reason: Optional[str]) -> bool:
+    if isinstance(status_code, (int, float)) and int(status_code) in TIMEOUT_LIKE_HTTP_STATUS_CODES:
+        return True
+
+    reason = str(error_reason or "").strip().lower()
+    if not reason:
+        return False
+    return any(token in reason for token in ("timeout", "timed out", "deadline exceeded"))
+
+
 def upload_file_to_presigned_url(
     *,
     upload_url: str,
@@ -147,35 +165,130 @@ def upload_file_to_presigned_url(
     try:
         with open(file_path, "rb") as handle:
             data = handle.read()
-
-        headers = {
-            "Content-Type": content_type or DEFAULT_CONTENT_TYPE,
-            "User-Agent": os.getenv("TIKOMNI_HTTP_USER_AGENT", DEFAULT_USER_AGENT),
+    except Exception as error:
+        return {
+            "ok": False,
+            "status_code": None,
+            "error_reason": f"u3_upload_failed:{normalize_text(error)}",
+            "retry_attempt": 0,
+            "timeout_retry_max": 0,
+            "timeout_retry_exhausted": False,
+            "retry_chain": [],
         }
-        if isinstance(upload_headers, dict):
-            for key, value in upload_headers.items():
-                header_key = str(key).strip()
-                if not header_key:
-                    continue
-                headers[header_key] = str(value)
-
-        request = urllib.request.Request(
-            upload_url,
-            data=data,
-            headers=headers,
-            method=(upload_method or "PUT").upper(),
+
+    headers = {
+        "Content-Type": content_type or DEFAULT_CONTENT_TYPE,
+        "User-Agent": os.getenv("TIKOMNI_HTTP_USER_AGENT", DEFAULT_USER_AGENT),
+    }
+    if isinstance(upload_headers, dict):
+        for key, value in upload_headers.items():
+            header_key = str(key).strip()
+            if not header_key:
+                continue
+            headers[header_key] = str(value)
+
+    retry_policy = resolve_timeout_retry_policy()
+    timeout_retry_max = int(retry_policy.get("max_retries", 0) or 0)
+    retry_backoff_ms = int(retry_policy.get("backoff_ms", 0) or 0)
+    max_attempts = 1 + timeout_retry_max
+    retry_chain: List[Dict[str, Any]] = []
+    last_result: Dict[str, Any] = {
+        "ok": False,
+        "status_code": None,
+        "error_reason": "u3_upload_failed:unknown",
+    }
+
+    for attempt in range(1, max_attempts + 1):
+        if attempt > 1 and retry_backoff_ms > 0:
+            sleep_ms = retry_backoff_ms * (2 ** (attempt - 2))
+            time.sleep(sleep_ms / 1000.0)
+
+        try:
+            request = urllib.request.Request(
+                upload_url,
+                data=data,
+                headers=headers,
+                method=(upload_method or "PUT").upper(),
+            )
+            with urllib.request.urlopen(request, timeout=max(timeout_ms / 1000.0, 1.0)) as response:
+                status_code = response.getcode()
+                result: Dict[str, Any] = {
+                    "ok": 200 <= int(status_code) < 300,
+                    "status_code": status_code,
+                    "error_reason": None if 200 <= int(status_code) < 300 else f"u3_upload_http_{status_code}",
+                }
+        except urllib.error.HTTPError as error:
+            result = {
+                "ok": False,
+                "status_code": error.code,
+                "error_reason": f"u3_upload_http_{error.code}",
+            }
+        except urllib.error.URLError as error:
+            reason_obj = getattr(error, "reason", error)
+            reason_text = normalize_text(reason_obj)
+            result = {
+                "ok": False,
+                "status_code": None,
+                "error_reason": f"u3_upload_failed:{reason_text or 'network_error'}",
+                "_timeout_like": isinstance(reason_obj, socket.timeout)
+                or _is_timeout_like_upload_error(status_code=None, error_reason=reason_text),
+            }
+        except (TimeoutError, socket.timeout) as error:
+            result = {
+                "ok": False,
+                "status_code": None,
+                "error_reason": f"u3_upload_failed:{normalize_text(error) or 'timeout'}",
+                "_timeout_like": True,
+            }
+        except Exception as error:
+            reason_text = normalize_text(error)
+            result = {
+                "ok": False,
+                "status_code": None,
+                "error_reason": f"u3_upload_failed:{reason_text or 'unknown'}",
+                "_timeout_like": _is_timeout_like_upload_error(status_code=None, error_reason=reason_text),
+            }
+
+        if result.get("ok"):
+            result["retry_attempt"] = max(0, attempt - 1)
+            result["timeout_retry_max"] = timeout_retry_max
+            result["timeout_retry_exhausted"] = False
+            result["retry_chain"] = retry_chain
+            return result
+
+        timeout_like = bool(
+            result.pop(
+                "_timeout_like",
+                _is_timeout_like_upload_error(
+                    status_code=result.get("status_code"),
+                    error_reason=result.get("error_reason"),
+                ),
+            )
         )
-        with urllib.request.urlopen(request, timeout=max(timeout_ms / 1000.0, 1.0)) as response:
-            status_code = response.getcode()
-            return {
-                "ok": 200 <= int(status_code) < 300,
-                "status_code": status_code,
-                "error_reason": None if 200 <= int(status_code) < 300 else f"u3_upload_http_{status_code}",
+        retry_chain.append(
+            {
+                "attempt": attempt,
+                "status_code": result.get("status_code"),
+                "error_reason": result.get("error_reason"),
+                "timeout_like": timeout_like,
             }
-    except urllib.error.HTTPError as error:
-        return {"ok": False, "status_code": error.code, "error_reason": f"u3_upload_http_{error.code}"}
-    except Exception as error:
-        return {"ok": False, "status_code": None, "error_reason": f"u3_upload_failed:{normalize_text(error)}"}
+        )
+        last_result = dict(result)
+
+        if timeout_like and attempt < max_attempts:
+            continue
+
+        last_result["retry_attempt"] = max(0, attempt - 1)
+        last_result["timeout_retry_max"] = timeout_retry_max
+        last_result["timeout_retry_exhausted"] = bool(timeout_like and attempt >= max_attempts)
+        last_result["retry_chain"] = retry_chain
+        return last_result
+
+    last_result["retry_attempt"] = timeout_retry_max
+    last_result["timeout_retry_max"] = timeout_retry_max
+    last_result["timeout_retry_exhausted"] = True
+    last_result["retry_chain"] = retry_chain
+    return last_result
 
 
 def complete_u3_upload(
@@ -284,6 +397,11 @@ def run_u3_public_url_fallback(
             "ok": bool(upload_response.get("ok")),
             "status_code": upload_response.get("status_code"),
             "error_reason": upload_response.get("error_reason"),
+            "retry_attempt": upload_response.get("retry_attempt", 0),
+            "retry_count": len(upload_response.get("retry_chain") or []),
+            "timeout_retry_max": upload_response.get("timeout_retry_max", 0),
+            "timeout_retry_exhausted": bool(upload_response.get("timeout_retry_exhausted")),
+            "retry_chain": upload_response.get("retry_chain") or [],
         }
     )
     if not upload_response.get("ok"):