@remixmate/cli 0.9.26 → 0.9.27

package/README.md

@@ -6,7 +6,7 @@ English | [简体中文](./README.zh-CN.md)
 
 AI media generation skills for Claude Code / Codex.
 
-11 skills covering the full short-video production pipeline: image / video / voice / digital-human asset generation, web page capture, script planning, template binding, Remotion rendering, Jianying (CapCut) draft export, and video deconstruction.
+13 skills covering the full short-video production pipeline: image / video / voice / digital-human asset generation, web page capture and text extraction, script planning, template binding, Remotion rendering, Jianying (CapCut) draft export, and video deconstruction.
 
 ## Install
 
@@ -159,11 +159,11 @@ cp .env.example .env
 source .env
 ```
 
-Python skills (8 of 12) require `python3 >= 3.10`. `web-screenshot` / `web-record` require Playwright (auto-installs chromium on first run). `ffmpeg` is only needed for `video-parser`'s optional local tool (`deconstruct_video.py`); the default `video-parser` entry runs server-side via ab-render and needs no local ffmpeg.
+Python skills (9 of 13) require `python3 >= 3.10`. `web-screenshot` / `web-record` / `web-read` require Playwright (auto-installs chromium on first run). `ffmpeg` is only needed for `video-parser`'s optional local tool (`deconstruct_video.py`); the default `video-parser` entry runs server-side via ab-render and needs no local ffmpeg.
 
 ## Skills
 
-This project contains 11 AI media generation skills covering the full pipeline from asset generation, script orchestration, template binding, and video rendering to Jianying export.
+This project contains 13 AI media generation skills covering the full pipeline from asset generation, script orchestration, template binding, and video rendering to Jianying export.
 
 ### Skill layers
 
@@ -186,6 +186,7 @@ This project contains 11 AI media generation skills covering the full pipeline f
 │  video-parser      Video deconstruction (audio / ASR / kf)  │
 │  web-screenshot    Web page screenshot (png / jpg)          │
 │  web-record        Web page recording / storyboard video    │
+│  web-read          Web page text extraction (markdown/json) │
 └─────────────────────────────────────────────────────────────┘
 ```
 
@@ -207,7 +208,8 @@ This project contains 11 AI media generation skills covering the full pipeline f
 │   ├── export-jianying/        # orchestration: export Jianying draft ZIP
 │   ├── video-parser/           # tool: video deconstruction & analysis
 │   ├── web-screenshot/         # tool: headless-browser screenshot (also hosts record.py)
-│   └── web-record/             # tool: headless-browser recording (entry -> web-screenshot/scripts/record.py)
+│   ├── web-record/             # tool: headless-browser recording (entry -> web-screenshot/scripts/record.py)
+│   └── web-read/               # tool: headless-browser text extraction (entry -> web-screenshot/scripts/read_page.py)
 └── README.md
 ```
 
@@ -227,6 +229,7 @@ This project contains 11 AI media generation skills covering the full pipeline f
 | video-parser | tool | Video → audio + ASR + keyframes + scene segmentation | python `scripts/parse_via_render.py` |
 | web-screenshot | tool | Web page screenshot (png / jpg) | python `scripts/screenshot.py` |
 | web-record | tool | Web page recording / scroll-through / storyboard video (webm -> mp4 -> VOD) | python `../web-screenshot/scripts/record.py` |
+| web-read | tool | Web page → main text (markdown / plain text / structured JSON) | python `../web-screenshot/scripts/read_page.py` |
 
 ### Core workflows
 

package/README.zh-CN.md

@@ -6,7 +6,7 @@
 
 面向 Claude Code / Codex 的 AI 媒体生成技能集。
 
-包含 11 个技能，覆盖完整的短视频生产链路：图片 / 视频 / 语音 / 数字人素材生成、网页捕获、脚本编排、模板绑定、Remotion 渲染、剪映（CapCut）草稿导出，以及视频解构。
+包含 13 个技能，覆盖完整的短视频生产链路：图片 / 视频 / 语音 / 数字人素材生成、网页捕获与正文抽取、脚本编排、模板绑定、Remotion 渲染、剪映（CapCut）草稿导出，以及视频解构。
 
 ## 安装
 
@@ -113,11 +113,11 @@ cp .env.example .env
 source .env
 ```
 
-Python 技能（12 个中的 8 个）需要 `python3 >= 3.10`。`web-screenshot` / `web-record` 需要 Playwright（首次运行自动安装 chromium）。`ffmpeg` 仅 `video-parser` 的可选本地工具（`deconstruct_video.py`）需要；`video-parser` 默认入口走 ab-render 服务端解构，无需本地 ffmpeg。
+Python 技能（13 个中的 9 个）需要 `python3 >= 3.10`。`web-screenshot` / `web-record` / `web-read` 需要 Playwright（首次运行自动安装 chromium）。`ffmpeg` 仅 `video-parser` 的可选本地工具（`deconstruct_video.py`）需要；`video-parser` 默认入口走 ab-render 服务端解构，无需本地 ffmpeg。
 
 ## 技能
 
-本项目包含 12 个 AI 媒体生成技能，覆盖从素材生成、脚本编排、模板绑定、视频渲染到剪映导出的完整视频内容生产链路。
+本项目包含 13 个 AI 媒体生成技能，覆盖从素材生成、脚本编排、模板绑定、视频渲染到剪映导出的完整视频内容生产链路。
 
 ### 技能分层
 
@@ -140,6 +140,7 @@ Python 技能（12 个中的 8 个）需要 `python3 >= 3.10`。`web-screenshot`
 │  video-parser      视频解构（音频提取 / ASR / 关键帧）       │
 │  web-screenshot    网页截图（png / jpg）                     │
 │  web-record        网页录屏 / 滚动录屏 / 分镜视频            │
+│  web-read          网页正文抽取（markdown / 纯文本 / JSON）  │
 └─────────────────────────────────────────────────────────────┘
 ```
 
@@ -161,7 +162,8 @@ Python 技能（12 个中的 8 个）需要 `python3 >= 3.10`。`web-screenshot`
 │   ├── export-jianying/        # 编排: 导出剪映草稿 ZIP
 │   ├── video-parser/           # 工具: 视频解构与分析
 │   ├── web-screenshot/         # 工具: 无头浏览器截图（record.py 也放在这里）
-│   └── web-record/             # 工具: 无头浏览器录屏（入口指向 web-screenshot/scripts/record.py）
+│   ├── web-record/             # 工具: 无头浏览器录屏（入口指向 web-screenshot/scripts/record.py）
+│   └── web-read/               # 工具: 无头浏览器正文抽取（入口指向 web-screenshot/scripts/read_page.py）
 └── README.md
 ```
 
@@ -181,6 +183,7 @@ Python 技能（12 个中的 8 个）需要 `python3 >= 3.10`。`web-screenshot`
 | video-parser | 工具 | 视频 → 音频 + ASR + 关键帧 + 场景分段 | python `scripts/parse_via_render.py` |
 | web-screenshot | 工具 | 网页截图（png / jpg） | python `scripts/screenshot.py` |
 | web-record | 工具 | 网页录屏 / 滚动录屏 / 分镜视频（webm → mp4 → VOD） | python `../web-screenshot/scripts/record.py` |
+| web-read | 工具 | 网页正文抽取（markdown / 纯文本 / 结构化 JSON） | python `../web-screenshot/scripts/read_page.py` |
 
 ### 核心链路
 
@@ -218,6 +221,7 @@ remixmate export-jianying --help
 remixmate video-parser --help
 remixmate web-screenshot --help
 remixmate web-record --help
+remixmate web-read --help
 remixmate template-registry --help
 
 # http 技能（gen-image、gen-video、gen-voice、gen-digital-human）没有

package/dist/handlers/gen-voice.d.ts

@@ -4,9 +4,19 @@
  * Operations:
  *   --list-voices true                 → GET available voice IDs from /voice/page (live)
  *   --list-voices true --local true    → print the built-in language-tagged
- *                                        fallback catalog (offline, no API call)
+ *                                        fallback catalog (offline, no API call).
+ *                                        **CLI-only escape hatch for offline dev.**
  *   default                            → synthesize text into an MP3 URL
  *
+ * `local` is deliberately absent from `skills/gen-voice/skill.json`'s
+ * `parameters`, which is what ab-agent turns into the model-facing tool schema.
+ * A model asked to check a voice id would reach for `local: true`, get a
+ * two-entry hardcoded list back, and conclude that a perfectly valid voice does
+ * not exist — which is exactly what happened on the hosted web agent
+ * ("本地回退列表中没有该音色"). The remote catalog is the only authority on
+ * which voices exist; the local list is a developer convenience for working
+ * without a token, and it is only reachable by typing the flag yourself.
+ *
  * The previous Python script also offered `--download` to write the MP3 to
  * disk. That's intentionally dropped here: the agent flow never used it (the
  * audio URL is persisted in cloud) and removing local file I/O keeps the

package/dist/handlers/gen-voice.js

@@ -4,9 +4,19 @@
  * Operations:
  *   --list-voices true                 → GET available voice IDs from /voice/page (live)
  *   --list-voices true --local true    → print the built-in language-tagged
- *                                        fallback catalog (offline, no API call)
+ *                                        fallback catalog (offline, no API call).
+ *                                        **CLI-only escape hatch for offline dev.**
  *   default                            → synthesize text into an MP3 URL
  *
+ * `local` is deliberately absent from `skills/gen-voice/skill.json`'s
+ * `parameters`, which is what ab-agent turns into the model-facing tool schema.
+ * A model asked to check a voice id would reach for `local: true`, get a
+ * two-entry hardcoded list back, and conclude that a perfectly valid voice does
+ * not exist — which is exactly what happened on the hosted web agent
+ * ("本地回退列表中没有该音色"). The remote catalog is the only authority on
+ * which voices exist; the local list is a developer convenience for working
+ * without a token, and it is only reachable by typing the flag yourself.
+ *
  * The previous Python script also offered `--download` to write the MP3 to
  * disk. That's intentionally dropped here: the agent flow never used it (the
  * audio URL is persisted in cloud) and removing local file I/O keeps the
@@ -21,6 +31,10 @@ import { isTrue, toNumber } from './shared.js';
  * Mirrors the language-keyed defaults that gen_script.py uses, kept in sync
  * by hand because the two callers live on different runtimes.
  *
+ * This is **not** a list of available voices — it is the two ids the resolver
+ * falls back to when nothing else is specified, and one of them is still a
+ * placeholder. Never treat it as evidence about what the service offers.
+ *
  * Promote to a JSON config once this grows beyond a handful of entries.
  */
 const LOCAL_VOICE_CATALOG = [
@@ -44,6 +58,8 @@ async function listVoicesRemote(ctx) {
     process.stdout.write(`💡 Use --voice-id <id> to select a voice for synthesis\n`);
 }
 function listVoicesLocal() {
+    process.stderr.write('⚠️  --local prints a hardcoded 2-entry fallback list, NOT the available voices. ' +
+        'Drop --local to query the live catalog.\n');
     for (const v of LOCAL_VOICE_CATALOG) {
         process.stdout.write(`${v.id}\t${v.language}\t${v.name}\n`);
     }

package/dist/manifest.json

@@ -1,7 +1,7 @@
 {
   "schemaVersion": 1,
-  "version": "0.9.26",
-  "generatedAt": "2026-09-13T00:51:13.551Z",
+  "version": "0.9.27",
+  "generatedAt": "2026-09-13T09:11:30.410Z",
   "skills": [
     {
       "id": "export-jianying",
@@ -636,7 +636,7 @@
           },
           "voice_id": {
             "type": "string",
-            "description": "Voice id. Default 'Chinese (Mandarin)_Male_Announcer'. When unsure, call with list_voices=true first to see what's available — do not invent ids."
+            "description": "Voice id. Default 'Chinese (Mandarin)_Male_Announcer'. When unsure, call with list_voices=true first to see what's available — do not invent ids, and do not declare a voice unavailable unless it is missing from that list."
           },
           "speed": {
             "type": "number",
@@ -644,11 +644,7 @@
           },
           "list_voices": {
             "type": "boolean",
-            "description": "List available voices and exit"
-          },
-          "local": {
-            "type": "boolean",
-            "description": "Used together with list_voices=true: print the voice-resolver fallback catalog with language tags (no remote /voice/page call). Output is one '<id>\\t<lang>\\t<name>' line per voice."
+            "description": "List the available voices and exit. This queries the live voice service and is the authoritative catalog — one call is enough, and its absence from this list is the only evidence that a voice id is invalid."
           },
           "json_output": {
             "type": "boolean",
@@ -667,8 +663,7 @@
         ],
         "hidden": [
           "json_output",
-          "list_voices",
-          "local"
+          "list_voices"
         ]
       }
     },
@@ -965,6 +960,162 @@
         ]
       }
     },
+    {
+      "id": "web-read",
+      "toolName": "web_read",
+      "tier": "tool",
+      "category": "consuming",
+      "title": "Web Page Reader",
+      "summary": "Open any URL in a headless browser (Playwright Python) and return the page's MAIN TEXT — title, headings, paragraphs, lists, code blocks and tables — as Markdown, plain text, or structured JSON. Boilerplate (nav / sidebar / comments / ads / footer) is stripped by a Readability-style pass, and JS-rendered pages work because a real browser runs the page. This is the tool to use whenever you need to KNOW WHAT A PAGE SAYS: summarizing an article, pulling source material for a script, reading a README or docs page, checking what a link contains. It returns text, not pictures — for a screenshot (png/jpg) use web_screenshot, for a recording (mp4/webm) use web_record. Output is capped by max_chars (default 20000) and truncated on a block boundary; pass an `output` path to keep the full text on disk.",
+      "triggers": [
+        "Read this link / what does this page say / summarize this article",
+        "Fetch page content, extract article text, get the text of a URL",
+        "Use a web page as source material for a script or video",
+        "Read a README / docs page / changelog / blog post",
+        "Pull code samples or tables out of a page"
+      ],
+      "entry": {
+        "type": "python",
+        "scriptPath": "../web-screenshot/scripts/read_page.py"
+      },
+      "runtime": "python",
+      "envVars": [
+        "WEB_CAPTURE_BROWSER",
+        "WEB_CAPTURE_ALLOW_PRIVATE_HOSTS",
+        "PLAYWRIGHT_BROWSERS_PATH"
+      ],
+      "parameters": {
+        "type": "object",
+        "properties": {
+          "url": {
+            "type": "string",
+            "description": "Target page URL (http/https). Private / loopback / link-local addresses are refused unless WEB_CAPTURE_ALLOW_PRIVATE_HOSTS=1."
+          },
+          "format": {
+            "type": "string",
+            "enum": [
+              "markdown",
+              "text",
+              "json"
+            ],
+            "description": "markdown (default: keeps headings, lists, code fences, tables) | text (plain) | json (structured blocks + metadata, not truncated)"
+          },
+          "max_chars": {
+            "type": "number",
+            "description": "Cap on the printed text, cut at a block boundary with an explicit [truncated] notice (default 20000, 0 = unlimited). Raise it when you need the whole document; a very long page will otherwise fill your context."
+          },
+          "selector": {
+            "type": "string",
+            "description": "Read only inside this CSS selector. Leave empty to auto-detect the article container — only reach for this when the auto-detected container was wrong."
+          },
+          "include_links": {
+            "type": "boolean",
+            "description": "Keep hyperlinks as [text](url) instead of plain text. Useful when you need to follow links from the page."
+          },
+          "include_images": {
+            "type": "boolean",
+            "description": "Keep images as ![alt](src). Useful for harvesting illustration URLs out of an article."
+          },
+          "output": {
+            "type": "string",
+            "description": "Also write the FULL (untruncated) text to this local path. stdout still respects max_chars — use this when a long page must be kept for later steps."
+          },
+          "settle_ms": {
+            "type": "number",
+            "description": "Extra wait before extracting, in ms. Raise for pages that render content late."
+          },
+          "wait_for_selector": {
+            "type": "string",
+            "description": "Wait for this CSS selector before extracting (the reliable fix for JS-rendered content)"
+          },
+          "wait_for_timeout": {
+            "type": "number",
+            "description": "Fixed wait before extracting, in ms"
+          },
+          "device": {
+            "type": "string",
+            "description": "Device emulation name, e.g. 'iPhone 15 Pro' — some sites serve a leaner page to mobile"
+          },
+          "viewport": {
+            "type": "string",
+            "description": "Viewport as 'width,height', e.g. '1280,800'"
+          },
+          "color_scheme": {
+            "type": "string",
+            "enum": [
+              "light",
+              "dark",
+              "no-preference"
+            ],
+            "description": "Emulate prefers-color-scheme"
+          },
+          "user_agent": {
+            "type": "string",
+            "description": "Override the User-Agent (try this when a site blocks headless browsers)"
+          },
+          "timeout": {
+            "type": "number",
+            "description": "Global Playwright action timeout in ms"
+          },
+          "ignore_https_errors": {
+            "type": "boolean",
+            "description": "Ignore HTTPS certificate errors"
+          },
+          "storage_state": {
+            "type": "string",
+            "description": "Path to a Playwright storageState JSON file (logged-in session)"
+          },
+          "cookies": {
+            "type": "string",
+            "description": "Playwright cookies as a JSON string or a path to a JSON file (top level is an array)"
+          },
+          "browser": {
+            "type": "string",
+            "enum": [
+              "chromium",
+              "firefox",
+              "webkit"
+            ],
+            "description": "Browser engine (default chromium)"
+          },
+          "quiet": {
+            "type": "boolean",
+            "description": "Suppress the extraction diagnostics on stderr"
+          }
+        },
+        "required": [
+          "url"
+        ]
+      },
+      "ui": {
+        "primary": [
+          "url",
+          "format",
+          "max_chars"
+        ],
+        "advanced": [
+          "selector",
+          "include_links",
+          "include_images",
+          "wait_for_selector",
+          "settle_ms",
+          "device",
+          "viewport",
+          "color_scheme",
+          "timeout"
+        ],
+        "hidden": [
+          "output",
+          "quiet",
+          "user_agent",
+          "ignore_https_errors",
+          "storage_state",
+          "cookies",
+          "browser",
+          "wait_for_timeout"
+        ]
+      }
+    },
     {
       "id": "web-record",
       "toolName": "web_record",

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@remixmate/cli",
-  "version": "0.9.26",
+  "version": "0.9.27",
   "description": "AI media generation skills for Claude Code / Codex — 12 skills covering image, video, voice, digital human, web screenshot, web recording, script, template registry, rendering, Jianying export, and video deconstruction.",
   "type": "module",
   "main": "dist/index.js",
@@ -21,6 +21,7 @@
     "smoke": "node scripts/smoke.mjs",
     "test:cli": "npm run build && node --test test/*.test.mjs",
     "test:validators": "PYTHONDONTWRITEBYTECODE=1 python3 scripts/test-validators.py",
+    "test:web-read": "PYTHONDONTWRITEBYTECODE=1 python3 scripts/test-web-read.py",
     "test:template-pipeline": "PYTHONDONTWRITEBYTECODE=1 node dist/cli.js exec -- python3 scripts/test-template-pipeline.py",
     "test:props-contract": "PYTHONDONTWRITEBYTECODE=1 python3 scripts/test-props-contract.py",
     "test:narration-speed": "PYTHONDONTWRITEBYTECODE=1 python3 scripts/test-narration-speed.py",

package/skills/gen-script/scripts/gen_script.py

@@ -1442,7 +1442,7 @@ Examples:
     parser.add_argument("--ratio", default=None, choices=VALID_RATIOS, help="Aspect ratio. When omitted: if --template-id is set, use the template's supportedAspectRatios[0]; otherwise default 16:9.")
     parser.add_argument("--resolution", default="1080p", help="Resolution (default: 1080p)")
     parser.add_argument("--scenes", type=int, default=None, help="Scene count (default: auto-planned)")
-    parser.add_argument("--voice-id", default=None, help="Narration voice id. When omitted, the resolver picks template.defaultVoiceId, then the language-keyed fallback (zh→Chinese (Mandarin)_Male_Announcer, en→TBD English voice). gen_voice --list-voices --local prints the language-tagged catalog.")
+    parser.add_argument("--voice-id", default=None, help="Narration voice id. When omitted, the resolver picks template.defaultVoiceId, then the language-keyed fallback (zh→Chinese (Mandarin)_Male_Announcer, en→TBD English voice). gen_voice --list-voices prints the live catalog.")
     parser.add_argument(
         "--speed",
         type=float,

package/skills/gen-voice/SKILL.md

@@ -46,13 +46,15 @@ There is no skill-local env file — the executing process inherits the system e
 remixmate gen-voice --list-voices
 ```
 
-To inspect the local language-tagged fallback catalog used by the voice resolver (no remote API call), add `--local`:
+The list above is the **authoritative** catalog — a voice id is invalid only if it is missing from it.
+
+For offline development (no token / no network) there is a `--local` escape hatch. It prints the resolver's two hardcoded fallback ids, **not** the available voices, so never use it to decide whether a voice exists:
 
 ```bash
 remixmate gen-voice --list-voices --local
 ```
 
-The local catalog prints one voice per line as `<voice-id>\t<lang>\t<display-name>`.
+It prints one line per entry as `<voice-id>\t<lang>\t<display-name>`.
 
 ### Default synthesis (URL output)
 
@@ -83,7 +85,7 @@ remixmate gen-voice --text "<text-to-synthesize>" --json-output
 | `--voice-id` | Voice id (use `--list-voices` to discover) | `Chinese (Mandarin)_Male_Announcer` |
 | `--speed` | Speech rate, 0.5–2.0 | `1.0` |
 | `--list-voices` | List available voices and exit | — |
-| `--local` | Used with `--list-voices`: print the local fallback catalog (offline) | off |
+| `--local` | CLI-only. With `--list-voices`: print the 2-entry hardcoded fallback list instead of querying the service (offline dev). Not exposed to the agent — see the handler comment. | off |
 | `--json-output` | Emit JSON (url, audio_length_ms, subtitles) | off |
 | `--priv-token` | Override token | env var |
 

package/skills/gen-voice/skill.json

@@ -25,7 +25,7 @@
       },
       "voice_id": {
         "type": "string",
-        "description": "Voice id. Default 'Chinese (Mandarin)_Male_Announcer'. When unsure, call with list_voices=true first to see what's available — do not invent ids."
+        "description": "Voice id. Default 'Chinese (Mandarin)_Male_Announcer'. When unsure, call with list_voices=true first to see what's available — do not invent ids, and do not declare a voice unavailable unless it is missing from that list."
       },
       "speed": {
         "type": "number",
@@ -33,11 +33,7 @@
       },
       "list_voices": {
         "type": "boolean",
-        "description": "List available voices and exit"
-      },
-      "local": {
-        "type": "boolean",
-        "description": "Used together with list_voices=true: print the voice-resolver fallback catalog with language tags (no remote /voice/page call). Output is one '<id>\\t<lang>\\t<name>' line per voice."
+        "description": "List the available voices and exit. This queries the live voice service and is the authoritative catalog — one call is enough, and its absence from this list is the only evidence that a voice id is invalid."
       },
       "json_output": {
         "type": "boolean",
@@ -56,8 +52,7 @@
     ],
     "hidden": [
       "json_output",
-      "list_voices",
-      "local"
+      "list_voices"
     ]
   }
 }

package/skills/web-read/SKILL.md

@@ -0,0 +1,146 @@
+---
+name: web-read
+description: |
+  Web-page reading skill — open a URL in a headless browser (Playwright Python) and get back the page's **main text**: title, headings, paragraphs, lists, code blocks and tables, as Markdown / plain text / structured JSON.
+  Boilerplate (nav, sidebar, comments, ads, footer) is stripped by a Readability-style pass, and JS-rendered pages work because a real browser runs the page first.
+
+  Text only. For a still screenshot (`.png` / `.jpg`) use web-screenshot / `web_screenshot`; for a recording (`.mp4` / `.webm`) use web-record / `web_record`.
+
+  Use this skill immediately whenever the user asks for any of:
+  - Read this link / what does this page say / summarize this article
+  - Fetch page content, extract the article text, get the text of a URL
+  - Use a web page as source material for a script, outline, or video
+  - Read a README / docs page / changelog / blog post
+  - Pull the code samples or the table out of a page
+  - Check what is behind a link before acting on it
+
+  Even when the user does not say "read", any request that needs the *content* of a URL (rather than a picture of it) should route here.
+triggers:
+  - Read this link / what does this page say / summarize this article
+  - Fetch page content, extract article text, get the text of a URL
+  - Use a web page as source material for a script or video
+  - Read a README / docs page / changelog / blog post
+  - Pull code samples or tables out of a page
+---
+
+# Web Read Skill (`web_read`)
+
+Turns a URL into text. Entry script **`read_page.py`**, pure Python, prints to **stdout**.
+
+> **Text only.** A screenshot is `web_screenshot`, a recording is `web_record`. Those two produce *files*; this one produces *content you can reason about*.
+
+**Script location**: this skill has no `scripts/` of its own — it reuses `read_page.py` and the `_media_screenshot/` package from the web-screenshot directory (`skill.json`'s `entry.scriptPath` points relatively at `../web-screenshot/scripts/read_page.py`). Everywhere the commands below say **`<ReadScript>`**, substitute:
+
+```
+<SkillDir>/../web-screenshot/scripts/read_page.py
+```
+
+> Path convention: read the system-injected `Base directory for this skill: <path>` as `<SkillDir>`. Never hardcode an absolute path.
+
+## Prerequisites
+
+- **Python 3.9+**
+- **The `playwright` pip package + the chromium engine**: the first run **bootstraps automatically** (`pip install playwright` + `playwright install chromium`).
+
+## Basic usage
+
+```bash
+python3 <ReadScript> --url "https://example.com/article/123"
+```
+
+Prints a Markdown document: an `# title` line, a `site · author · date · url` line, then the body. A one-line extraction diagnostic (`blocks / chars / container`) goes to **stderr**, so piping stdout gives you clean text.
+
+## Output formats
+
+```bash
+# Markdown (default) — headings, lists, ``` code fences, | tables |
+python3 <ReadScript> --url "https://docs.python.org/3/tutorial/introduction.html"
+
+# Plain text — no markup, for TTS or keyword work
+python3 <ReadScript> --url "https://example.com/post" --format text
+
+# JSON — typed blocks + metadata, for programmatic consumption
+python3 <ReadScript> --url "https://example.com/post" --format json
+```
+
+The JSON shape is `{url, status, metadata{title,byline,siteName,publishedTime,description,lang}, container, charCount, blocks[]}`, where each block is one of `heading` / `paragraph` / `quote` / `code` / `list` / `table` / `image` / `rule`. JSON is **never truncated** (half a JSON document is not a JSON document) — cap it with `--selector` instead.
+
+## Length control (read this before pointing it at a long page)
+
+`--max-chars` defaults to **20000** and cuts on a block boundary, appending an explicit `[truncated] 已显示 N / M 字符` notice. Nothing is silently dropped.
+
+```bash
+# Keep the whole document on disk, read a bounded slice now
+python3 <ReadScript> \
+  --url "https://example.com/very-long-guide" \
+  --max-chars 8000 \
+  --output "./guide.md"
+
+# No cap at all
+python3 <ReadScript> --url "https://example.com/post" --max-chars 0
+```
+
+## When the automatic extraction misses
+
+The container is picked by paragraph-density scoring, which is right on ordinary article/docs/blog pages and can miss on unusual layouts. In order of what to try:
+
+```bash
+# 1. Content renders late (SPA): wait for the real element
+python3 <ReadScript> --url "https://app.example.com/doc/1" --wait-for-selector "article.body"
+
+# 2. Still short: give it a fixed settle window
+python3 <ReadScript> --url "https://example.com/x" --settle-ms 3000
+
+# 3. Wrong part of the page: name the container yourself
+python3 <ReadScript> --url "https://example.com/x" --selector "#main-content"
+
+# 4. Behind a login
+python3 <ReadScript> --url "https://example.com/x" --storage-state "./auth.json"
+python3 <ReadScript> --url "https://example.com/x" --cookies '[{"name":"sid","value":"…","domain":"example.com","path":"/"}]'
+
+# 5. Site serves headless browsers a stub page
+python3 <ReadScript> --url "https://example.com/x" --user-agent "Mozilla/5.0 (Macintosh; Intel Mac OS X 10_15_7) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/124.0 Safari/537.36"
+```
+
+The stderr diagnostics tell you which case you are in: `⚠️ 整页有 N 字符，却只抽到 M` means the wrong container was chosen (→ `--selector`), while `⚠️ 这个页面几乎没有文本` means the page itself never rendered text (→ waiting, cookies, or user-agent).
+
+## Links and images
+
+Both are dropped by default, because they are noise for a summarize/rewrite task and they inflate the character budget.
+
+```bash
+# Keep links as [text](url) — when you need to follow them
+python3 <ReadScript> --url "https://example.com/index" --include-links
+
+# Keep images as ![alt](src) — when harvesting illustration URLs
+python3 <ReadScript> --url "https://example.com/post" --include-images
+```
+
+## Private addresses are refused
+
+`web_read` hands page text to a model, so by default it refuses URLs that resolve to private / loopback / link-local addresses (`localhost`, `10.*`, `169.254.169.254`, …). Reading an intranet page or a local dev server on purpose:
+
+```bash
+WEB_CAPTURE_ALLOW_PRIVATE_HOSTS=1 python3 <ReadScript> --url "http://localhost:5173/"
+```
+
+## Full flag list
+
+| Flag | Meaning |
+|---|---|
+| `-u, --url` | Target URL (required, http/https) |
+| `--format` | `markdown` (default) / `text` / `json` |
+| `--max-chars` | stdout cap, block-aligned (default 20000, `0` = unlimited) |
+| `--selector` | Extract only inside this CSS selector |
+| `--include-links` / `--include-images` | Keep `[text](url)` / `![alt](src)` |
+| `-o, --output` | Write the **full** text to a file (stdout stays capped) |
+| `--settle-ms` | Extra wait before extracting |
+| `--quiet` | Suppress the stderr diagnostic line |
+| `-b, --browser` | `chromium` (default) / `firefox` / `webkit` |
+| `--device`, `--viewport`, `--color-scheme`, `--user-agent` | Emulation |
+| `--wait-for-selector`, `--wait-for-timeout`, `--timeout` | Waiting |
+| `--storage-state`, `--cookies`, `--ignore-https-errors` | Session |
+
+## Exit codes
+
+`0` on success — including a page that legitimately has little text. Non-zero only for a refused URL, an unresolvable selector, or a navigation failure; each prints a single actionable line rather than a Python traceback.