chore: release v1.113.0

* feat(baoyu-imagine): add DashScope Wan 2.7 image model support

Closes #139.

Adds the new `wan2.7-image-pro` and `wan2.7-image` model family to the
DashScope provider so users can call Wan 2.7 directly through the
official Aliyun (Bailian) API instead of going through Replicate.

- Register `wan2.7-image-pro` and `wan2.7-image` as a new `wan27` family
  in the DashScope provider with their own size resolution rules:
  pixel range `[768*768, 4096*4096]` for `wan2.7-image-pro` text-to-image,
  `[768*768, 2048*2048]` for `wan2.7-image-pro` with refs and for the
  base `wan2.7-image` model in any mode, with aspect ratios validated
  against the documented `[1:8, 8:1]` band.
- Allow up to 9 reference images per request (image editing /
  multi-image fusion). Local files are inlined as base64 data URLs;
  `http(s)://` paths are forwarded as-is. Other DashScope models still
  reject `--ref` with a hint to switch to a wan2.7 model or another
  provider.
- Drop `prompt_extend` from the request body for the Wan 2.7 family
  (not part of the Wan 2.7 API surface) and skip the Qwen-only negative
  prompt for this family.
- Allow `--provider dashscope --ref ...` in `detectProvider` so users
  can opt into Wan 2.7 reference workflows, while keeping Wan 2.7 out
  of the auto-detect ref priority list.
- Add provider, reference, and usage-example documentation, plus
  unit tests covering family routing, size derivation across the
  three pixel-budget modes, ratio rejection, explicit-size validation,
  and the new `--provider dashscope` ref opt-in path.

Made-with: Cursor

* fix(baoyu-imagine): force n=1 for DashScope wan2.7 to avoid silent multi-image billing

Cross-checked the implementation against the official Wan 2.7 image
generation & editing API reference and found that the API defaults
`parameters.n` to 4 in non-collage mode (1-4 range, billed per image).
baoyu-imagine has single-image save semantics — only the first image
in the response is kept — so without an explicit `n: 1` users would
silently pay for 3 discarded images per request.

- Always send `parameters.n: 1` in the wan2.7 request body
- Reject `--n > 1` for wan2.7 with a clear error pointing at the
  single-image save semantics
- Add tests asserting the request body shape (n=1, no prompt_extend,
  no negative_prompt) and the --n>1 rejection
- Document the defaults-vs-skill mismatch in the dashscope reference

Made-with: Cursor

* Fix DashScope Wan 2.7 review feedback

.claude-plugin/marketplace.json

@@ -6,46 +6,34 @@
   },
   "metadata": {
     "description": "Skills shared by Baoyu for improving daily work efficiency",
-    "version": "1.45.1"
+    "version": "1.113.0"
   },
   "plugins": [
     {
-      "name": "content-skills",
-      "description": "Content generation and publishing skills",
+      "name": "baoyu-skills",
+      "description": "Content generation, AI backends, and utility tools for daily work efficiency",
       "source": "./",
       "strict": false,
       "skills": [
-        "./skills/baoyu-xhs-images",
-        "./skills/baoyu-post-to-x",
-        "./skills/baoyu-post-to-wechat",
         "./skills/baoyu-article-illustrator",
-        "./skills/baoyu-cover-image",
-        "./skills/baoyu-slide-deck",
         "./skills/baoyu-comic",
-        "./skills/baoyu-infographic"
-      ]
-    },
-    {
-      "name": "ai-generation-skills",
-      "description": "AI-powered generation backends",
-      "source": "./",
-      "strict": false,
-      "skills": [
-        "./skills/baoyu-danger-gemini-web",
-        "./skills/baoyu-image-gen"
-      ]
-    },
-    {
-      "name": "utility-skills",
-      "description": "Utility tools for content processing",
-      "source": "./",
-      "strict": false,
-      "skills": [
-        "./skills/baoyu-danger-x-to-markdown",
         "./skills/baoyu-compress-image",
-        "./skills/baoyu-url-to-markdown",
+        "./skills/baoyu-cover-image",
+        "./skills/baoyu-danger-gemini-web",
+        "./skills/baoyu-danger-x-to-markdown",
+        "./skills/baoyu-diagram",
         "./skills/baoyu-format-markdown",
-        "./skills/baoyu-markdown-to-html"
+        "./skills/baoyu-imagine",
+        "./skills/baoyu-infographic",
+        "./skills/baoyu-markdown-to-html",
+        "./skills/baoyu-post-to-weibo",
+        "./skills/baoyu-post-to-wechat",
+        "./skills/baoyu-post-to-x",
+        "./skills/baoyu-slide-deck",
+        "./skills/baoyu-translate",
+        "./skills/baoyu-url-to-markdown",
+        "./skills/baoyu-image-cards",
+        "./skills/baoyu-youtube-transcript"
       ]
     }
   ]

.claude/skills/release-skills/SKILL.md

@@ -7,6 +7,16 @@ description: Universal release workflow. Auto-detects version files and changelo
 
 Universal release workflow supporting any project type with multi-language changelog.
 
+## User Input Tools
+
+When this skill prompts the user, follow this tool-selection rule (priority order):
+
+1. **Prefer built-in user-input tools** exposed by the current agent runtime — e.g., `AskUserQuestion`, `request_user_input`, `clarify`, `ask_user`, or any equivalent.
+2. **Fallback**: if no such tool exists, emit a numbered plain-text message and ask the user to reply with the chosen number/answer for each question.
+3. **Batching**: if the tool supports multiple questions per call, combine all applicable questions into a single call; if only single-question, ask them one at a time in priority order.
+
+Concrete `AskUserQuestion` references below are examples — substitute the local equivalent in other runtimes.
+
 ## Quick Start
 
 Just run `/release-skills` - auto-detects your project configuration.
@@ -35,6 +45,7 @@ Just run `/release-skills` - auto-detects your project configuration.
 ### Step 1: Detect Project Configuration
 
 1. Check for `.releaserc.yml` (optional config override)
+   - If present, inspect whether it defines release hooks
 2. Auto-detect version file by scanning (priority order):
    - `package.json` (Node.js)
    - `pyproject.toml` (Python)
@@ -48,18 +59,46 @@ Just run `/release-skills` - auto-detects your project configuration.
 4. Identify language of each changelog by filename suffix
 5. Display detected configuration
 
+**Project Hook Contract**:
+
+If `.releaserc.yml` defines `release.hooks`, keep the release workflow generic and delegate project-specific packaging/publishing to those hooks.
+
+Supported hooks:
+
+| Hook | Purpose | Expected Responsibility |
+|------|---------|-------------------------|
+| `prepare_artifact` | Make one target releasable | Validate the target is self-contained, sync/embed local dependencies, optionally stage extra files |
+| `publish_artifact` | Publish one releasable target | Upload the prepared target (or a staged directory if the project uses one), attach version/changelog/tags |
+
+Supported placeholders:
+
+| Placeholder | Meaning |
+|-------------|---------|
+| `{project_root}` | Absolute path to repository root |
+| `{target}` | Absolute path to the module/skill being released |
+| `{artifact_dir}` | Absolute path to a temporary staging directory for this target, when the project uses one |
+| `{version}` | Version selected by the release workflow |
+| `{dry_run}` | `true` or `false` |
+| `{release_notes_file}` | Absolute path to a UTF-8 file containing release notes/changelog text |
+
+Execution rules:
+- Keep the skill generic: do not hardcode registry/package-manager/project layout details into this SKILL.
+- If `prepare_artifact` exists, run it once per target before publish-related checks that need the final releasable target state.
+- Write release notes to a temp file and pass that file path to `publish_artifact`; do not inline multiline changelog text into shell commands.
+- If hooks are absent, fall back to the default project-agnostic release workflow.
+
 **Language Detection Rules**:
 
-| Filename Pattern | Language |
-|------------------|----------|
-| `CHANGELOG.md` (no suffix) | en (default) |
-| `CHANGELOG.zh.md` / `CHANGELOG_CN.md` / `CHANGELOG.zh-CN.md` | zh |
-| `CHANGELOG.ja.md` / `CHANGELOG_JP.md` | ja |
-| `CHANGELOG.ko.md` / `CHANGELOG_KR.md` | ko |
-| `CHANGELOG.de.md` / `CHANGELOG_DE.md` | de |
-| `CHANGELOG.fr.md` / `CHANGELOG_FR.md` | fr |
-| `CHANGELOG.es.md` / `CHANGELOG_ES.md` | es |
-| `CHANGELOG.{lang}.md` | Corresponding language code |
+Changelog files follow the pattern `CHANGELOG_{LANG}.md` or `CHANGELOG.{lang}.md`, where `{lang}` / `{LANG}` is a language or region code.
+
+| Pattern | Example | Language |
+|---------|---------|----------|
+| No suffix | `CHANGELOG.md` | en (default) |
+| `_{LANG}` (uppercase) | `CHANGELOG_CN.md`, `CHANGELOG_JP.md` | Corresponding language |
+| `.{lang}` (lowercase) | `CHANGELOG.zh.md`, `CHANGELOG.ja.md` | Corresponding language |
+| `.{lang-region}` | `CHANGELOG.zh-CN.md` | Corresponding region variant |
+
+Common language codes: `zh` (Chinese), `ja` (Japanese), `ko` (Korean), `de` (German), `fr` (French), `es` (Spanish).
 
 **Output Example**:
 ```

.githooks/pre-push

@@ -0,0 +1,7 @@
+#!/bin/sh
+set -eu
+
+REPO_ROOT=$(git rev-parse --show-toplevel)
+cd "$REPO_ROOT"
+
+node scripts/verify-shared-package-deps.mjs --repo-root "$REPO_ROOT"

.github/workflows/test.yml

@@ -0,0 +1,25 @@
+name: Test
+
+on:
+  push:
+  pull_request:
+  workflow_dispatch:
+
+jobs:
+  node-tests:
+    runs-on: ubuntu-latest
+    steps:
+      - name: Checkout
+        uses: actions/checkout@v4
+
+      - name: Setup Node.js
+        uses: actions/setup-node@v4
+        with:
+          node-version: 22
+          cache: npm
+
+      - name: Install dependencies
+        run: npm ci
+
+      - name: Run tests
+        run: npm test

.gitignore

@@ -83,6 +83,10 @@ out
 .nuxt
 dist
 
+# Shared package builds are published to npm.
+!packages/*/dist/
+!packages/*/dist/**
+
 # Gatsby files
 .cache/
 # Comment in the public line in if your project uses Gatsby and not Next.js
@@ -152,6 +156,9 @@ slide-deck/
 infographic/
 illustrations/
 comic/
+translate/
+posts/
+diagram/
 ### IntelliJ IDEA ###
 .idea
 *.iws
@@ -159,3 +166,10 @@ comic/
 *.ipr
 
 .claude/skills/baoyu-skill-evolution
+# ClawHub local state (current and legacy directory names from the official CLI)
+.clawhub/
+.clawdhub/
+.release-artifacts/
+.worktrees/
+youtube-transcript/
+.omx/

.releaserc.yml

@@ -0,0 +1,6 @@
+release:
+  target_globs:
+    - skills/*
+  hooks:
+    prepare_artifact: node scripts/verify-shared-package-deps.mjs --repo-root "{project_root}" --target "{target}"
+    publish_artifact: node scripts/publish-skill.mjs --skill-dir "{target}" --version "{version}" --changelog-file "{release_notes_file}" --dry-run "{dry_run}"

CHANGELOG.md

@@ -2,6 +2,719 @@
 
 English | [中文](./CHANGELOG.zh.md)
 
+## 1.113.0 - 2026-04-25
+
+### Features
+- `baoyu-imagine`: add DashScope Wan 2.7 image model support (`wan2.7-image-pro` and `wan2.7-image`) directly through the official Aliyun (Bailian) API. Supports text-to-image, image editing, and multi-image fusion with up to 9 reference images, with documented `[1:8, 8:1]` aspect ratio validation and per-mode pixel-budget rules. Forces `parameters.n: 1` to match baoyu-imagine's single-image save semantics and explicitly rejects `--n > 1` to prevent silent multi-image billing (the API defaults to `n=4` in non-collage mode). Allows `--provider dashscope --ref ...` opt-in for Wan 2.7 reference workflows.
+
+## 1.112.0 - 2026-04-24
+
+### Features
+- `baoyu-article-illustrator`: make `hand-drawn-edu` (infographic + sketch-notes + macaron) the universal fallback preset when content analysis surfaces no strong signal — warm cream paper, black hand-drawn lines, soft pastel section blocks. Elevate `sketch-notes` to primary style across infographic / flowchart / comparison / framework auto-selection; rewrite the sketch-notes style spec (macaron palette, canonical single-page layout, diagram-only rule); add matching prompt block and workflow defaults.
+- `baoyu-article-illustrator`: add `hand-drawn-edu-flow` (flowchart) and `hand-drawn-edu-compare` (comparison) presets for the same warm educational style.
+
+### Breaking Changes
+- `baoyu-article-illustrator`: `hand-drawn-edu` preset now maps to `infographic` instead of `flowchart`. Users relying on the previous flowchart behavior should switch to the new `hand-drawn-edu-flow` preset.
+
+### Fixes
+- `baoyu-post-to-x`: add entry point guard to `scripts/md-to-html.ts` so that importing `parseMarkdown` from `x-article.ts` no longer triggers the CLI entry point. Mirrors the same fix applied to `baoyu-post-to-weibo`.
+
+## 1.111.1 - 2026-04-21
+
+### Documentation
+- Add a top-level `## Confirmation Policy` section to every image-generating skill (`baoyu-infographic`, `baoyu-cover-image`, `baoyu-slide-deck`, `baoyu-image-cards`, `baoyu-xhs-images`, `baoyu-article-illustrator`) as a single source of truth: explicit skill invocation, keyword shortcuts, EXTEND.md defaults, and auto-recommendations are recommendation inputs only — they never authorize skipping the confirmation step. Opt-out requires an explicit current-request signal (`--no-confirm` / `--quick` / `--yes` / "直接生成" / equivalent).
+- `baoyu-infographic`: consolidate the scattered reminders (previously repeated across Step 5, Step 6, Default combination, Keyword Shortcuts, and the preferences docs) into a single policy section referenced from Step 4's hard gate.
+
+## 1.111.0 - 2026-04-21
+
+### Refactor
+- Unify image-backend resolution across all image-consuming skills (`baoyu-infographic`, `baoyu-comic`, `baoyu-cover-image`, `baoyu-image-cards`, `baoyu-article-illustrator`, `baoyu-slide-deck`, `baoyu-xhs-images`): add a single `preferred_image_backend` preference field (`auto | ask | <backend-id>`) and replace the stateless ask-once rule with a 4-step resolution (current-request override → saved preference → auto-select → ask). Runtime-native tools (Codex `imagegen`, Hermes `image_generate`) are preferred by default; existing `EXTEND.md` files without the field are treated as `auto` with no schema bump.
+- Add a top-level `## Changing Preferences` section to each image-consuming skill as a first-class surface for pinning the backend and editing common one-line preferences.
+
+## 1.110.0 - 2026-04-21
+
+### Features
+- `baoyu-imagine`: add `gpt-image-2` support for OpenAI image generation and edits, make it the default OpenAI model, and document the official size/quality mapping, custom-size constraints, and Azure deployment guidance
+
+## 1.109.0 - 2026-04-21
+
+### Features
+- `baoyu-url-to-markdown`: vendor the `baoyu-fetch` runtime into `scripts/lib` and run it through a local `scripts/baoyu-fetch` CLI so published skill installs are self-contained
+
+### Fixes
+- `baoyu-fetch`: extract playable X/Twitter video MP4 variants for single posts and X Articles, choosing the highest-bitrate MP4 and rendering article videos as `[video](...)`
+- `sync-clawhub`: publish from the shared release file list so extensionless CLI entrypoints, `bun.lock`, and vendored `scripts/lib` files are uploaded
+
+### Maintenance
+- Upgrade `defuddle` to 0.17.0 and `jsdom` to 29.0.2; override `@xmldom/xmldom` to 0.8.13 to keep the Defuddle dependency chain vulnerability-free
+
+## 1.108.0 - 2026-04-19
+
+### Refactor
+- Refactor skills into focused reference files for better maintainability
+- Use npm packages for shared skill code across skills
+
+## 1.107.0 - 2026-04-15
+
+### Features
+- `baoyu-diagram`: add SVG-to-PNG @2x conversion script — auto-converts generated SVG diagrams to @2x PNG using Sharp; consolidate reference files and add `{baseDir}` path resolution for portable skill loading
+
+### Fixes
+- `claude-plugin`: allow inline marketplace manifest (#130)
+
+## 1.106.0 - 2026-04-14
+
+### Features
+- `baoyu-diagram`: add architecture enrichment rules — automatically expand architecture diagrams with multiple client types, per-service tech stacks, database tiers, message buses, and color-coded categories; add full structural layout patterns, architecture-specific pitfalls, network topology templates, and layout math for complex diagrams
+
+## 1.105.0 - 2026-04-13
+
+### Features
+- `baoyu-diagram`: unify to analyze→confirm→generate workflow — remove single/multi mode split; skill now analyzes any input material, recommends diagram types and splitting strategy, confirms once, then generates all diagrams
+
+## 1.104.0 - 2026-04-13
+
+### Features
+- `baoyu-diagram`: add Mermaid sketch step (6d-0) before SVG generation — write a Mermaid code block as structural intent; add Mermaid–SVG consistency check in step 6f
+
+### Fixes
+- `baoyu-post-to-wechat`: verify editor focus before paste and type operations to prevent silent paste failures
+
+## 1.103.1 - 2026-04-13
+
+### Fixes
+- `baoyu-markdown-to-html`: decode HTML entities and strip tags from article summary
+- `baoyu-post-to-weibo`: decode HTML entities and strip tags from article summary
+
+## 1.103.0 - 2026-04-12
+
+### Features
+- `baoyu-diagram`: add multi-diagram mode — analyze article content and generate multiple diagrams at identified positions; new `--density` option (`minimal`, `balanced`, `per-section`, `rich`) and `--mode` option (`single`, `multi`, `auto`); auto-detects mode from input (file path → multi, short topic → single); inserts diagram image links into article; output structure `diagram/{article-slug}/NN-{type}-{slug}/`
+
+### Fixes
+- `baoyu-article-illustrator`: prevent color names and hex codes from appearing as visible text in generated images — add semantic constraint to all palette references and prompt construction rules
+- `baoyu-cover-image`: prevent color names and hex codes from appearing as visible text in generated images — add constraint to all palette references and prompt template
+- `baoyu-image-cards`: prevent color names from appearing as visible text in generated images
+- `baoyu-post-to-wechat`: decode HTML entities and strip HTML tags from article summary before using as WeChat article digest
+
+## 1.102.0 - 2026-04-12
+
+### Features
+- `baoyu-imagine`: add OpenAI-compatible image API dialect — new `--imageApiDialect` flag, `OPENAI_IMAGE_API_DIALECT` env var, and `default_image_api_dialect` config for gateways that expect aspect-ratio `size` plus `metadata.resolution` instead of pixel `size`
+
+## 1.101.0 - 2026-04-12
+
+### Features
+- `baoyu-imagine`: improve Replicate provider compatibility — route models through family-specific input builders and validators (nano-banana, Seedream 4.5, Seedream 5 Lite, Wan 2.7 Image); update default model to `google/nano-banana-2`; fix Seedream 4.5 custom size encoding to use width/height schema; fix aspect-ratio default inheritance for unsupported Replicate models; block multi-output requests before they reach the API (by @justnode)
+
+## 1.100.0 - 2026-04-12
+
+### Features
+- `baoyu-imagine`: add Z.AI GLM-Image provider — supports `glm-image` and `cogview-4-250304` models via the Z.AI sync image API; configure with `ZAI_API_KEY` (or `BIGMODEL_API_KEY` for backward compatibility)
+
+## 1.99.1 - 2026-04-11
+
+### Fixes
+- `baoyu-article-illustrator`: omit `model` field from batch tasks when `--model` is not specified, letting `baoyu-imagine` resolve the default from env/config
+
+## 1.99.0 - 2026-04-10
+
+### Features
+- `baoyu-diagram`: add new skill for generating publication-ready SVG diagrams — flowcharts, structural/architecture diagrams, and illustrative intuition diagrams. Claude writes real SVG code directly following a cohesive design system; output is a single self-contained `.svg` file with embedded styles and auto dark-mode, ready to embed in articles, WeChat posts, slides, and docs
+
+## 1.98.0 - 2026-04-10
+
+### Features
+- `baoyu-xhs-images`: Restore as active skill (remove deprecated warning)
+- `baoyu-xhs-images`: Add `sketch-notes` style — hand-drawn educational infographic with macaron pastels, wobble lines, and warm cream background
+- `baoyu-xhs-images`: Add palette system (`macaron`, `warm`, `neon`) as optional `--palette` color override dimension
+- `baoyu-xhs-images`: Add 3 new presets: `hand-drawn-edu`, `sketch-card`, `sketch-summary`
+
+## 1.97.1 - 2026-04-09
+
+### Fixes
+- `baoyu-image-cards`: rename palette color roles from "Zone N" to "Block Color" to prevent AI rendering labels as visible text in images
+
+## 1.97.0 - 2026-04-09
+
+### Features
+- `baoyu-image-cards`: add `sketch-notes` style, palette system (`macaron`, `warm`, `neon`), and 3 new presets (`hand-drawn-edu`, `sketch-card`, `sketch-summary`)
+
+### Fixes
+- `baoyu-xhs-images`: improve deprecated skill description for better routing
+
+## 1.96.0 - 2026-04-09
+
+### Features
+- `baoyu-image-cards`: add image card series skill migrated from `baoyu-xhs-images`, decoupled from Xiaohongshu platform
+- `baoyu-xhs-images`: deprecated, migrated to `baoyu-image-cards`
+
+## 1.95.1 - 2026-04-09
+
+### Fixes
+- `baoyu-slide-deck`: add `pptxgenjs` dependency and detect image format by magic bytes instead of file extension in PDF merge
+
+## 1.95.0 - 2026-04-08
+
+### Features
+- `baoyu-infographic`: add `hand-drawn-edu` style — macaron pastels, hand-drawn wobble, stick figures
+- `baoyu-slide-deck`: add `hand-drawn-edu` preset and `macaron` mood dimension with pastel color palette
+
+## 1.94.0 - 2026-04-08
+
+### Features
+- `baoyu-cover-image`: add macaron palette and hand-drawn-edu style preset
+
+## 1.93.0 - 2026-04-08
+
+### Features
+- `baoyu-article-illustrator`: add `hand-drawn-edu` preset — flowchart + sketch-notes + macaron combination for hand-drawn educational diagrams
+
+### Refactor
+- `baoyu-article-illustrator`: extract palette as independent third dimension in Type × Style × Palette system
+
+### Fixes
+- `baoyu-article-illustrator`: add explicit style file loading step in workflow
+
+## 1.92.0 - 2026-04-08
+
+### Features
+- `baoyu-article-illustrator`: add `macaron` style — soft macaron pastel color blocks (blue, mint, lavender, peach) on warm cream background with optional hand-drawn mode; add `edu-visual` preset
+
+## 1.90.1 - 2026-04-05
+
+### Fixes
+- `baoyu-post-to-wechat`: detect actual image format from buffer magic bytes to fix CDN content-type mismatches (e.g. WebP served for .png URLs); treat WebP as PNG-preferred for transparency handling
+
+## 1.89.1 - 2026-04-01
+
+### Features
+- `baoyu-chrome-cdp`: add `gracefulKillChrome` that waits for Chrome to exit and release its port; fix `killChrome` to use `exitCode`/`signalCode` instead of `.killed` for reliable process state detection
+- `baoyu-fetch`: auto-detect login state before extraction in interaction wait mode
+
+### Maintenance
+- Sync vendor baoyu-chrome-cdp across CDP skills
+- `baoyu-url-to-markdown`: sync vendor baoyu-fetch with login auto-detect
+
+## 1.89.0 - 2026-03-31
+
+### Features
+- `baoyu-fetch`: add X session cookie sidecar to persist login across runs, graceful Chrome shutdown via Browser.close, and stale profile lock auto-recovery
+- `baoyu-article-illustrator`: add warm palette variant for vector-illustration style with new `warm-knowledge` preset
+- `baoyu-post-to-x`: add X session persistence after login, Chrome lock recovery, and graceful shutdown
+
+### Documentation
+- `baoyu-post-to-weibo`: add post type auto-selection rules and safer CDP kill instructions
+
+### Refactor
+- `baoyu-danger-gemini-web`: use graceful Chrome shutdown instead of hard kill
+- `baoyu-danger-x-to-markdown`: use graceful Chrome shutdown instead of hard kill
+
+### Fixes
+- Sync npm lockfile and root node tests
+
+### Maintenance
+- `baoyu-url-to-markdown`: sync vendor baoyu-fetch with session and lifecycle changes
+- Update bun.lock files
+
+## 1.88.0 - 2026-03-27
+
+### Features
+- `baoyu-fetch`: new URL reader CLI package with Chrome CDP and site-specific adapters (X/Twitter, YouTube, Hacker News, generic)
+
+### Refactor
+- `baoyu-url-to-markdown`: replace custom CDP/converter pipeline with `baoyu-fetch` CLI
+- `shared-skill-packages`: add `package.json` `files` allowlist support and filter test files, changelogs, and `.changeset` dirs during vendor sync
+
+### Fixes
+- `baoyu-md`: rename test image paths from `images/` to `imgs/`
+
+## 1.87.2 - 2026-03-26
+
+### Refactor
+- `baoyu-translate`: simplify translation prompts from 15+ verbose principles to 7 concise ones, consolidate analysis and review steps in workflow references
+
+## 1.87.1 - 2026-03-26
+
+### Maintenance
+- Add deprecation notice to `baoyu-image-gen` SKILL.md redirecting users to `baoyu-imagine`
+- Document deprecated skills policy in CLAUDE.md
+
+## 1.87.0 - 2026-03-26
+
+### Maintenance
+- Remove deprecated `baoyu-image-gen` redirect skill and plugin manifest entry — migration to `baoyu-imagine` is complete
+
+## 1.86.0 - 2026-03-25
+
+### Features
+- `baoyu-translate`: enrich translation prompt with full analysis context — source voice assessment, structured figurative language mapping, comprehension challenge reasoning, structural/creative challenges, and chunk position context for subagents
+
+## 1.85.0 - 2026-03-25
+
+### Features
+- `baoyu-imagine`: auto-migrate legacy `baoyu-image-gen` EXTEND.md config path at runtime
+- Add `baoyu-image-gen` deprecation redirect skill to guide users to install `baoyu-imagine` and remove the old skill
+
+## 1.84.0 - 2026-03-25
+
+### Features
+- Rename `baoyu-image-gen` skill to `baoyu-imagine` — shorter command name, all references updated across docs, configs, and dependent skills
+
+## 1.83.0 - 2026-03-25
+
+### Features
+- `baoyu-image-gen`: add MiniMax provider (`image-01` / `image-01-live`) with subject_reference for character/portrait consistency, custom sizes, and aspect ratio support
+
+## 1.82.0 - 2026-03-24
+
+### Features
+- `baoyu-url-to-markdown`: add browser fallback strategy — headless first, automatic retry in visible Chrome on technical failure; new `--browser auto|headless|headed` flag with `--headless`/`--headed` shortcuts
+- `baoyu-url-to-markdown`: add content cleaner module for HTML preprocessing before extraction (remove ads, base64 images, scripts, styles)
+- `baoyu-url-to-markdown`: support base64 data URI images in media localizer alongside remote URLs
+- `baoyu-url-to-markdown`: capture final URL from browser to track redirects for output path generation
+- `baoyu-url-to-markdown`: add agent quality gate documentation for post-capture content validation
+
+### Dependencies
+- `baoyu-url-to-markdown`: upgrade defuddle ^0.12.0 → ^0.14.0
+
+### Tests
+- `baoyu-url-to-markdown`: add unit tests for content-cleaner, html-to-markdown, legacy-converter, media-localizer
+
+## 1.81.0 - 2026-03-24
+
+### Features
+- `baoyu-youtube-transcript`: add yt-dlp fallback when YouTube blocks direct InnerTube API, with alternate client identity retry and cookie support via `YOUTUBE_TRANSCRIPT_COOKIES_FROM_BROWSER` env var
+
+### Refactor
+- `baoyu-youtube-transcript`: split monolithic script into typed modules (youtube, transcript, storage, shared, types) and add unit tests
+
+## 1.80.1 - 2026-03-24
+
+### Fixes
+- `baoyu-image-gen`: use correct `prompt` field name for Jimeng API request
+
+## 1.80.0 - 2026-03-24
+
+### Features
+- `baoyu-image-gen`: add Azure OpenAI as independent image generation provider with flexible endpoint parsing, deployment-name resolution, quality mapping, and reference image validation
+
+## 1.79.2 - 2026-03-23
+
+### Fixes
+- `baoyu-cover-image`: simplify reference image handling — use `--ref` when model supports it, only create description files for models without reference image support
+- `baoyu-post-to-weibo`: add no-theme rule for article markdown-to-HTML conversion
+
+### Tests
+- Fix Node-compatible parser tests and add parser test dependencies
+
+## 1.79.1 - 2026-03-23
+
+### Fixes
+- Consolidate to single plugin to prevent duplicate skill registration (by @TyrealQ)
+- `baoyu-article-illustrator`: remove opacity parameter from watermark prompt
+- `baoyu-comic`: fix Doraemon naming spacing and remove opacity from watermark prompt
+- `baoyu-xhs-images`: remove opacity from watermark prompt and fix CJK spacing
+
+### Documentation
+- Update project documentation to reflect single-plugin architecture
+
+## 1.79.0 - 2026-03-22
+
+### Features
+- `baoyu-post-to-wechat`: improve credential loading with multi-source resolution, priority ordering, and diagnostics for skipped incomplete sources
+
+## 1.78.0 - 2026-03-22
+
+### Features
+- `baoyu-url-to-markdown`: add URL-specific parser layer for X/Twitter and archive.ph sites
+- `baoyu-url-to-markdown`: improved slug generation with stop words removal and subdirectory output structure
+
+### Fixes
+- `baoyu-url-to-markdown`: preserve anchor elements containing media in legacy converter
+- `baoyu-url-to-markdown`: smarter title deduplication to avoid redundant headings
+
+## 1.77.0 - 2026-03-22
+
+### Features
+- `baoyu-youtube-transcript`: add end times to chapter data (by @jzOcb)
+
+### Fixes
+- `sync-clawhub`: skip failed skills instead of aborting
+
+## 1.76.1 - 2026-03-21
+
+### Documentation
+- `baoyu-youtube-transcript`: fix zsh glob issue — always single-quote YouTube URLs when running the script
+
+## 1.76.0 - 2026-03-21
+
+### Features
+- `baoyu-youtube-transcript`: add title heading, description summary, and cover image to markdown output
+
+### Fixes
+- `baoyu-markdown-to-html`: use process.execPath and tsx import in test runner
+
+## 1.75.0 - 2026-03-21
+
+### Features
+- `baoyu-youtube-transcript`: new skill — download YouTube video transcripts/subtitles and cover images with multi-language, chapters, and speaker identification support
+
+## 1.74.1 - 2026-03-21
+
+### Fixes
+- `baoyu-image-gen`: align OpenRouter image generation with current API, harden image support, and narrow Gemini aspect ratios (by @cwandev)
+- `baoyu-image-gen`: broaden OpenRouter model detection and aspect ratio validation
+
+## 1.74.0 - 2026-03-20
+
+### Features
+- `baoyu-markdown-to-html`: CLI now supports all rendering options — color, font-family, font-size, code-theme, mac-code-block, line-number, count, legend
+
+### Fixes
+- `baoyu-markdown-to-html`: fix CSS custom property regex to handle quoted values; grace/simple themes now layer default CSS
+
+## 1.73.3 - 2026-03-20
+
+### Fixes
+- `baoyu-post-to-wechat`: fix placeholder replacement to avoid shorter placeholders matching longer numbered variants
+
+## 1.73.2 - 2026-03-20
+
+### Fixes
+- `baoyu-post-to-wechat`: fix body image upload to correctly use media/uploadimg API with format and size validation (by @AICreator-Wind)
+
+### Refactor
+- `baoyu-post-to-wechat`: extract image processor module for local format conversion (WebP/BMP/GIF → JPEG/PNG) instead of material API fallback
+
+## 1.73.1 - 2026-03-18
+
+### Refactor
+- `baoyu-danger-x-to-markdown`: migrate tests from bun:test to node:test
+
+## 1.73.0 - 2026-03-18
+
+### Features
+- `baoyu-danger-x-to-markdown`: add video media support for X articles with poster image and video link rendering
+
+## 1.72.0 - 2026-03-18
+
+### Features
+- `baoyu-danger-x-to-markdown`: add MARKDOWN entity support for rendering embedded markdown/code blocks in X articles
+
+## 1.71.0 - 2026-03-17
+
+### Features
+- `baoyu-image-gen`: add Seedream reference image support for 5.0/4.5/4.0 models with model-specific size validation
+
+## 1.70.0 - 2026-03-17
+
+### Features
+- `baoyu-format-markdown`: optimize title generation with formula-based recommendations and straightforward alternatives
+- `baoyu-format-markdown`: auto-generate dual summaries (`summary` + `description`) in frontmatter
+
+## 1.69.1 - 2026-03-16
+
+### Fixes
+- `baoyu-chrome-cdp`: tighten chrome auto-connect logic to reduce false positives
+
+## 1.69.0 - 2026-03-16
+
+### Features
+- `baoyu-chrome-cdp`: support connecting to existing Chrome session (by @bviews)
+
+### Fixes
+- `baoyu-chrome-cdp`: support Chrome 146 native remote debugging in approval mode (by @bviews)
+- `baoyu-chrome-cdp`: keep HTTP validation in findExistingChromeDebugPort (by @bviews)
+- `baoyu-danger-gemini-web`: reuse openPageSession and fix orphaned tab leak (by @bviews)
+- `baoyu-danger-gemini-web`: respect explicit profile config over auto-discovery (by @bviews)
+- `baoyu-danger-gemini-web`: respect BAOYU_CHROME_PROFILE_DIR in auto-discovery skip (by @bviews)
+- `baoyu-post-to-wechat`: improve browser publishing reliability (by @cfh-7598)
+
+### Documentation
+- `baoyu-cover-image`: clarify people reference image workflow and interactive confirmation
+
+## 1.68.0 - 2026-03-14
+
+### Features
+- `baoyu-article-illustrator`: add configurable output directory (`default_output_dir`) with 4 options — `imgs-subdir`, `same-dir`, `illustrations-subdir`, `independent`
+- `baoyu-cover-image`: add character preservation from reference images — use `usage: direct` to pass people references to model for stylized likeness
+
+## 1.67.0 - 2026-03-13
+
+### Features
+- `baoyu-image-gen`: add qwen-image-2.0-pro model support for DashScope provider with free-form sizes and text rendering (by @JianJang2017)
+
+## 1.66.1 - 2026-03-13
+
+### Tests
+- Migrate test files from centralized `tests/` directory to colocate with source code
+- Convert tests from `.mjs` to TypeScript (`.test.ts`) with `tsx` runner
+- Add npm workspaces configuration and npm cache to CI workflow
+
+## 1.66.0 - 2026-03-13
+
+### Features
+- `baoyu-image-gen`: add Jimeng (即梦) and Seedream (豆包) image generation providers (by @lindaifeng)
+
+### Fixes
+- `baoyu-image-gen`: tighten Jimeng provider behavior
+
+### Refactor
+- `baoyu-image-gen`: export functions for testability and add module entry guard
+
+### Documentation
+- `baoyu-image-gen`: add Jimeng and Seedream provider documentation to SKILL.md and READMEs
+
+### Tests
+- Add test infrastructure with CI workflow and image-gen unit tests
+
+## 1.65.1 - 2026-03-13
+
+### Refactor
+- `baoyu-translate`: replace remark/unified with markdown-it for chunk parsing, add main.ts CLI entry point
+
+## 1.65.0 - 2026-03-13
+
+### Features
+- `baoyu-post-to-wechat`: add placeholder image upload support with deduplication for markdown-embedded images
+
+### Fixes
+- `baoyu-post-to-wechat`: fix frontmatter parsing to allow leading whitespace and optional trailing newline
+
+### Refactor
+- `baoyu-post-to-wechat`: replace `renderMarkdownToHtml` with `renderMarkdownWithPlaceholders` for structured output
+
+## 1.64.0 - 2026-03-13
+
+### Features
+- `baoyu-image-gen`: add OpenRouter provider with support for image generation, reference images, and configurable models
+
+## 1.63.0 - 2026-03-13
+
+### Features
+- `baoyu-url-to-markdown`: add hosted `defuddle.md` API fallback when local browser capture fails
+- `baoyu-url-to-markdown`: extract YouTube transcript/caption text into markdown output
+- `baoyu-url-to-markdown`: materialize shadow DOM content for better web-component page conversion
+- `baoyu-url-to-markdown`: include language hint in markdown front matter when available
+
+### Refactor
+- `baoyu-url-to-markdown`: split monolithic converter into defuddle, legacy, and shared modules
+
+### Documentation
+- Fix Claude Code marketplace repo casing in READMEs
+
+## 1.62.0 - 2026-03-12
+
+### Features
+- `baoyu-infographic`: support flexible aspect ratios with custom W:H values (e.g., 3:4, 4:3, 2.35:1) in addition to named presets
+
+### Fixes
+- Set strict mode on plugins to prevent duplicated slash commands
+
+### Documentation
+- `baoyu-post-to-wechat`: replace credential-like placeholders
+
+## 1.61.0 - 2026-03-11
+
+### Features
+- `baoyu-post-to-wechat`: add multi-account support with `--account` CLI arg, EXTEND.md accounts block, isolated Chrome profiles, and credential resolution chain
+
+### Fixes
+- Exclude `out/dist/build` dirs and `bun.lockb` from skill release files
+- Use proper MIME types in skill publish to fix ClawhHub rejection
+
+## 1.60.0 - 2026-03-11
+
+### Features
+- `baoyu-url-to-markdown`: support reusing existing Chrome CDP instances and fix port detection order
+
+### Fixes
+- `baoyu-post-to-x`: add missing `fs` import in x-article
+
+### Refactor
+- Unify all CDP skills to use shared `baoyu-chrome-cdp` package with vendored copies
+- Simplify CLAUDE.md, move detailed documentation to `docs/` directory
+- Publish skills directly from synced vendor, removing separate artifact preparation step
+
+## 1.59.1 - 2026-03-11
+
+### Fixes
+- `baoyu-translate`: improve short text annotation density rule and add explicit style preset passing to 02-prompt.md
+- `baoyu-post-to-x`: remove `--disable-blink-features=AutomationControlled` Chrome flag
+
+### Refactor
+- `baoyu-post-to-weibo`: add entry point guard to md-to-html.ts for module import compatibility
+- Replace clawhub CLI with local sync-clawhub.mjs script
+
+### Documentation
+- Update CLAUDE.md to reflect v1.59.0 codebase state (by @jackL1020)
+
+## 1.59.0 - 2026-03-09
+
+### Features
+- `baoyu-image-gen`: add batch parallel image generation and provider-level throttling (by @SeamoonAO)
+
+### Fixes
+- `baoyu-image-gen`: restore Google as default provider when multiple keys available
+
+### Documentation
+- Improve skill documentation clarity (by @SeamoonAO)
+
+## 1.58.0 - 2026-03-08
+
+### Features
+- Add XDG config path support for EXTEND.md (by @liby)
+
+### Fixes
+- `baoyu-post-to-wechat`: surface agent-browser startup errors
+- `baoyu-post-to-wechat`: harden agent-browser command and eval handling (by @luojiyin1987)
+- `baoyu-image-gen`: use execFileSync for google curl requests (by @luojiyin1987)
+- `baoyu-format-markdown`: use spawnSync for autocorrect command (by @luojiyin1987)
+
+### Documentation
+- Fix CLAUDE dependency statement (by @luojiyin1987)
+- Add markdown-to-html to README utility skills (by @luojiyin1987)
+
+## 1.57.0 - 2026-03-08
+
+### Features
+- Add ClawHub/OpenClaw publishing support with sync script and README documentation
+
+### Refactor
+- Add openclaw metadata to all skill frontmatter for ClawHub registry compatibility
+- Rename `SKILL_DIR` to `baseDir` across all skills for consistency
+- `baoyu-danger-gemini-web`, `baoyu-danger-x-to-markdown`: dynamic script path in usage display
+- `baoyu-comic`, `baoyu-xhs-images`: use skill interface instead of direct script invocation for image generation
+
+## 1.56.1 - 2026-03-08
+
+### Fixes
+- `baoyu-post-to-weibo`: simplify article image insertion with Backspace-based placeholder deletion for ProseMirror compatibility
+
+## 1.56.0 - 2026-03-08
+
+### Features
+- `baoyu-article-illustrator`: preset-first selection flow with categorized style presets by content type
+- `baoyu-xhs-images`: streamline workflow from 6 to 4 steps with Smart Confirm (Quick/Customize/Detailed paths)
+
+### Fixes
+- `baoyu-post-to-wechat`: improve image upload reliability with file chooser interception and fallback
+
+## 1.55.0 - 2026-03-08
+
+### Features
+- `baoyu-article-illustrator`: add screen-print style and `--preset` flag for quick type + style selection
+- `baoyu-cover-image`: add screen-print rendering and duotone palette with 5 new style presets
+- `baoyu-xhs-images`: add screen-print style and `--preset` flag with 23 built-in presets
+
+### Documentation
+- Add credits section to both READMEs acknowledging open source inspirations
+
+## 1.54.1 - 2026-03-07
+
+### Fixes
+- `baoyu-post-to-x`: keep composed posts open in Chrome so users can review and publish manually
+
+### Documentation
+- `baoyu-post-to-x`: document default post type selection and manual publishing flow
+- `README`: add Star History charts to the English and Chinese READMEs
+
+## 1.54.0 - 2026-03-06
+
+### Features
+- `baoyu-format-markdown`: improve title and summary generation with style-differentiated candidates, prohibited patterns, and hook-first principles
+- `baoyu-markdown-to-html`: add `--cite` option to convert ordinary external links to numbered bottom citations
+- `baoyu-post-to-wechat`: enable bottom citations by default for markdown input, add `--no-cite` flag to disable
+- `baoyu-translate`: support external glossary files via `glossary_files` in EXTEND.md (markdown table or YAML)
+- `baoyu-translate`: add frontmatter transformation rules to rename source metadata fields with `source` prefix
+
+## 1.53.0 - 2026-03-06
+
+### Features
+- `baoyu-url-to-markdown`: save rendered HTML snapshot as `-captured.html` alongside markdown output
+- `baoyu-url-to-markdown`: Defuddle-first markdown conversion with automatic fallback to legacy Readability/selector extractor
+
+## 1.52.0 - 2026-03-06
+
+### Features
+- `baoyu-post-to-weibo`: add video upload support via `--video` flag (max 18 files total)
+- `baoyu-post-to-weibo`: switch from clipboard paste to `DOM.setFileInputFiles` for more reliable uploads
+
+### Fixes
+- `baoyu-post-to-weibo`: add Chrome health check with auto-restart for unresponsive instances
+- `baoyu-post-to-weibo`: add navigation check to ensure Weibo home page before posting
+
+## 1.51.2 - 2026-03-06
+
+### Fixes
+- `release-skills`: replace explicit language filename patterns (e.g. `CHANGELOG.de.md`) with generic pattern to avoid Gen Agent Trust Hub URL scanner false positive
+- `baoyu-infographic`: add credential/secret stripping instructions to address Snyk W007 insecure credential handling audit
+
+## 1.51.1 - 2026-03-06
+
+### Refactor
+- Unify Chrome CDP profile path — all skills now share `baoyu-skills/chrome-profile` instead of per-skill directories
+- Fix `baoyu-post-to-weibo` incorrectly reusing `x-browser-profile` path
+
+### Fixes
+- Remove `curl | bash` remote code execution pattern from all install instructions
+- Enforce HTTPS-only for remote image downloads in `md-to-html` scripts
+- Add redirect limit (max 5) to prevent infinite redirect loops
+- Add Security Guidelines section to CLAUDE.md
+
+## 1.51.0 - 2026-03-06
+
+### Features
+- `baoyu-post-to-weibo`: new skill for posting to Weibo — supports text posts with images and headline articles (头条文章) via Chrome CDP
+- `baoyu-format-markdown`: add title/summary multi-candidate selection — generates 3 candidates for user to pick, with `auto_select` EXTEND.md support
+
+## 1.50.0 - 2026-03-06
+
+### Features
+- `baoyu-translate`: expand translation style presets from 4 to 9 — add academic, business, humorous, conversational, and elegant styles
+- `baoyu-translate`: add `--style` CLI flag for per-invocation style override
+- `baoyu-translate`: integrate style instructions into subagent prompt template
+
+## 1.49.0 - 2026-03-06
+
+### Features
+- `baoyu-format-markdown`: add reader-perspective content analysis phase — analyzes highlights, structure, and formatting issues before applying formatting
+- `baoyu-format-markdown`: restructure workflow from 8 steps to 7 with explicit do/don't formatting principles and completion report
+- `baoyu-translate`: extract Step 2 workflow mechanics to separate reference file for cleaner SKILL.md
+- `baoyu-translate`: expand trigger keywords (改成中文, 快翻, 本地化, etc.) for better skill activation
+- `baoyu-translate`: add proactive warning for long content in quick mode
+- `baoyu-translate`: save frontmatter to `chunks/frontmatter.md` during chunking
+
+## 1.48.2 - 2026-03-06
+
+### Features
+- `baoyu-translate`: add figurative language & emotional fidelity review steps to refined workflow critique and revision stages
+- `baoyu-translate`: enhance quick mode to enforce meaning-first translation principles for figurative language
+
+## 1.48.1 - 2026-03-05
+
+### Features
+- `baoyu-translate`: add figurative language & metaphor mapping to analysis step — interprets metaphors, idioms, and implied meanings before translation instead of translating literally
+- `baoyu-translate`: add "meaning over words", "figurative language", and "emotional fidelity" translation principles to SKILL.md, refined workflow, and subagent prompt template
+
+## 1.48.0 - 2026-03-05
+
+### Features
+- `baoyu-translate`: add `--output-dir` option to chunk.ts — chunks now write to the translation output directory instead of the source file directory
+- `baoyu-translate`: improve refined workflow — split Review into Critical Review + Revision (5→6 steps), add Europeanized language diagnosis for CJK targets
+
+## 1.47.0 - 2026-03-05
+
+### Features
+- Add `baoyu-translate` skill — three-mode translation (quick/normal/refined) with custom glossaries, audience-aware translation, and parallel chunked translation for long documents
+- Add cross-platform PowerShell support for EXTEND.md preference checks across all skills
+
+## 1.46.0 - 2026-03-05
+
+### Features
+- Add `--output-dir` option to url-to-markdown for custom output directory with auto-generated filenames
+
 ## 1.45.1 - 2026-03-05
 
 ### Refactor

CHANGELOG.zh.md

@@ -2,6 +2,719 @@
 
 [English](./CHANGELOG.md) | 中文
 
+## 1.113.0 - 2026-04-25
+
+### 新功能
+- `baoyu-imagine`：新增 DashScope Wan 2.7 图像模型支持（`wan2.7-image-pro` 与 `wan2.7-image`），通过阿里云百炼官方 API 直接调用，无需经 Replicate 转发。支持文生图、图像编辑、多图融合（最多 9 张参考图），按官方文档校验 `[1:8, 8:1]` 宽高比范围，并按模式应用不同的像素预算规则。强制 `parameters.n: 1` 以匹配 baoyu-imagine 的单图保存语义，显式拒绝 `--n > 1`，避免在用户不知情的情况下产生多图计费（API 在非拼图模式下默认 `n=4`）。允许通过 `--provider dashscope --ref ...` 显式启用 Wan 2.7 参考图工作流。
+
+## 1.112.0 - 2026-04-24
+
+### 新功能
+- `baoyu-article-illustrator`：当内容分析未检测到明确信号时，将 `hand-drawn-edu`（infographic + sketch-notes + macaron）作为通用默认预设 —— 暖奶油色纸面背景、黑色手绘线条、柔和马卡龙色块。`sketch-notes` 升级为 infographic / flowchart / comparison / framework 自动选择的首选风格；重写 sketch-notes 风格规范（马卡龙调色板、标准单页布局、仅限示意图的规则）；新增对应的 prompt 模板块和默认工作流规则。
+- `baoyu-article-illustrator`：新增 `hand-drawn-edu-flow`（flowchart）和 `hand-drawn-edu-compare`（comparison）两个预设，保持相同的温暖教育风格。
+
+### 破坏性变更
+- `baoyu-article-illustrator`：`hand-drawn-edu` 预设的类型由 `flowchart` 改为 `infographic`。依赖原有流程图行为的用户请改用新增的 `hand-drawn-edu-flow` 预设。
+
+### 修复
+- `baoyu-post-to-x`：为 `scripts/md-to-html.ts` 添加入口守卫，确保 `x-article.ts` 导入 `parseMarkdown` 时不再触发 CLI 入口逻辑。与 `baoyu-post-to-weibo` 此前的修复保持一致。
+
+## 1.111.1 - 2026-04-21
+
+### 文档
+- 为每个图片生成类技能（`baoyu-infographic`、`baoyu-cover-image`、`baoyu-slide-deck`、`baoyu-image-cards`、`baoyu-xhs-images`、`baoyu-article-illustrator`）新增顶级 `## Confirmation Policy` 章节作为单一事实源：显式调用技能、关键词快捷方式、EXTEND.md 偏好、自动推荐都只是"推荐输入"，不授权跳过确认步骤。跳过确认必须由当前请求中的明确信号触发（`--no-confirm` / `--quick` / `--yes` / "直接生成" / 同义表达）。
+- `baoyu-infographic`：将原先散落在 Step 5、Step 6、Default combination、Keyword Shortcuts 及 preferences 文档中的重复提醒合并为单一策略章节，由 Step 4 的 hard gate 引用。
+
+## 1.111.0 - 2026-04-21
+
+### 重构
+- 统一所有图片生成类技能（`baoyu-infographic`、`baoyu-comic`、`baoyu-cover-image`、`baoyu-image-cards`、`baoyu-article-illustrator`、`baoyu-slide-deck`、`baoyu-xhs-images`）的后端选择规则：新增单一 `preferred_image_backend` 偏好字段（`auto | ask | <backend-id>`），用 4 步解析规则（当前请求覆盖 → 已保存偏好 → 自动选择 → 询问用户）替换原有的无状态询问规则。默认优先使用运行时原生工具（如 Codex `imagegen`、Hermes `image_generate`）；未设置该字段的现有 `EXTEND.md` 文件视为 `auto`，无需升级 schema 版本。
+- 在每个图片技能中新增顶级 `## Changing Preferences` 章节,作为固定后端和修改常用偏好的一级入口。
+
+## 1.110.0 - 2026-04-21
+
+### 新功能
+- `baoyu-imagine`：新增 `gpt-image-2` 支持，用于 OpenAI 图像生成与编辑；将其设为默认 OpenAI 模型，并补齐官方尺寸/质量映射、自定义尺寸约束与 Azure 部署说明
+
+## 1.109.0 - 2026-04-21
+
+### 新功能
+- `baoyu-url-to-markdown`：将 `baoyu-fetch` 运行时代码 vendored 到 `scripts/lib`，并通过本地 `scripts/baoyu-fetch` CLI 调用，使发布后的技能安装不再依赖 `baoyu-fetch` npm 包
+
+### 修复
+- `baoyu-fetch`：修复 X/Twitter 单条内容与 X Article 的视频解析，提取可播放的最高码率 MP4，并将文章视频渲染为 `[video](...)`
+- `sync-clawhub`：改用共享 release 文件清单发布，确保无扩展名 CLI 入口、`bun.lock` 和 vendored `scripts/lib` 文件都会被上传
+
+### 维护
+- 将 `defuddle` 升级到 0.17.0、`jsdom` 升级到 29.0.2，并通过 override 将 `@xmldom/xmldom` 固定到 0.8.13，清除 Defuddle 依赖链上的漏洞提示
+
+## 1.108.0 - 2026-04-19
+
+### 重构
+- 将技能文档拆分为聚焦的参考文件，提升可维护性
+- 将多技能共享代码迁移至 npm 包管理
+
+## 1.107.0 - 2026-04-15
+
+### 新功能
+- `baoyu-diagram`：新增 SVG 转 @2x PNG 转换脚本 —— 使用 Sharp 自动将生成的 SVG 图表转为 @2x PNG；精简合并参考文件，新增 `{baseDir}` 路径解析以支持可移植的技能加载
+
+### 修复
+- `claude-plugin`：支持内联 marketplace manifest (#130)
+
+## 1.106.0 - 2026-04-14
+
+### 新功能
+- `baoyu-diagram`：新增架构图丰富化规则 —— 自动扩展架构图，补充多客户端类型、各服务技术栈、数据库分层、消息总线和分色分类；新增完整结构布局模式、架构专用陷阱提示、网络拓扑模板和复杂图表布局计算
+
+## 1.105.0 - 2026-04-13
+
+### 新功能
+- `baoyu-diagram`：统一为分析→确认→生成工作流 —— 移除单图/多图模式区分；技能现在分析任意输入素材，推荐图表类型和拆分策略，一次确认后批量生成所有图表
+
+## 1.104.0 - 2026-04-13
+
+### 新功能
+- `baoyu-diagram`：新增 Mermaid 草图步骤（6d-0），在生成 SVG 前先写 Mermaid 代码块作为结构意图；在步骤 6f 新增 Mermaid–SVG 一致性检查
+
+### 修复
+- `baoyu-post-to-wechat`：在粘贴和输入操作前校验编辑器焦点，避免粘贴静默失败
+
+## 1.103.1 - 2026-04-13
+
+### 修复
+- `baoyu-markdown-to-html`：修复文章摘要中 HTML 实体未解码及 HTML 标签未剥离的问题
+- `baoyu-post-to-weibo`：修复文章摘要中 HTML 实体未解码及 HTML 标签未剥离的问题
+
+## 1.103.0 - 2026-04-12
+
+### 新功能
+- `baoyu-diagram`：新增多图模式 —— 分析文章内容，在识别出的位置批量生成图表；新增 `--density` 参数（`minimal`、`balanced`、`per-section`、`rich`）和 `--mode` 参数（`single`、`multi`、`auto`）；根据输入自动判断模式（文件路径→多图，短主题→单图）；自动在文章中插入图表链接；输出目录结构 `diagram/{article-slug}/NN-{type}-{slug}/`
+
+### 修复
+- `baoyu-article-illustrator`：修复生成图像中出现颜色名称和色值文字的问题 —— 在所有调色板参考文件和提示构建规则中添加语义约束
+- `baoyu-cover-image`：修复生成图像中出现颜色名称和色值文字的问题 —— 在所有调色板参考文件和提示模板中添加约束
+- `baoyu-image-cards`：修复生成图像中出现颜色名称文字的问题
+- `baoyu-post-to-wechat`：修复文章摘要中 HTML 实体未解码及 HTML 标签未剥离的问题，避免微信文章摘要显示乱码
+
+## 1.102.0 - 2026-04-12
+
+### 新功能
+- `baoyu-imagine`：新增 OpenAI 兼容图像 API 方言支持 —— 新增 `--imageApiDialect` 参数、`OPENAI_IMAGE_API_DIALECT` 环境变量及 `default_image_api_dialect` 配置项，用于对接期望宽高比格式 `size` 加 `metadata.resolution` 的兼容网关
+
+## 1.101.0 - 2026-04-12
+
+### 新功能
+- `baoyu-imagine`：改进 Replicate 服务商兼容性 —— 针对不同模型系列（nano-banana、Seedream 4.5、Seedream 5 Lite、Wan 2.7 Image）实现专属输入构建器和验证器；将默认模型更新为 `google/nano-banana-2`；修复 Seedream 4.5 自定义尺寸编码（改用 width/height schema）；修复不支持的 Replicate 模型的宽高比默认值继承问题；在请求到达 API 前拦截多图请求 (by @justnode)
+
+## 1.100.0 - 2026-04-12
+
+### 新功能
+- `baoyu-imagine`：新增 Z.AI GLM-Image 服务商支持，支持 `glm-image` 和 `cogview-4-250304` 模型，通过 Z.AI 同步图像 API 调用；配置 `ZAI_API_KEY`（或 `BIGMODEL_API_KEY` 向后兼容）
+
+## 1.99.1 - 2026-04-11
+
+### 修复
+- `baoyu-article-illustrator`：未指定 `--model` 时，批处理任务中不再写入 `model` 字段，改由 `baoyu-imagine` 从环境变量或配置中解析默认值
+
+## 1.99.0 - 2026-04-10
+
+### 新功能
+- `baoyu-diagram`：新增技能，用于生成可直接发布的 SVG 图表 —— 包括流程图、架构/结构图、示意图（直觉图解）。Claude 直接输出符合统一设计规范的真实 SVG 代码，产物是单个自包含的 `.svg` 文件，内嵌样式并自动支持深色模式，可直接嵌入文章、微信公众号、幻灯片和文档中
+
+## 1.98.0 - 2026-04-10
+
+### 新功能
+- `baoyu-xhs-images`：恢复为正式技能（移除废弃警告）
+- `baoyu-xhs-images`：新增 `sketch-notes` 风格 —— 手绘教育信息图，马卡龙配色，波动线条，暖奶油背景
+- `baoyu-xhs-images`：新增配色系统（`macaron`、`warm`、`neon`），支持 `--palette` 参数覆盖风格默认颜色
+- `baoyu-xhs-images`：新增 3 个预设：`hand-drawn-edu`、`sketch-card`、`sketch-summary`
+
+## 1.97.1 - 2026-04-09
+
+### 修复
+- `baoyu-image-cards`：将配色方案中 "Zone N" 角色名改为 "Block Color"，防止 AI 将标签文字渲染到图片中
+
+## 1.97.0 - 2026-04-09
+
+### 新功能
+- `baoyu-image-cards`：新增 `sketch-notes` 风格、配色系统（`macaron`、`warm`、`neon`）及 3 个新预设（`hand-drawn-edu`、`sketch-card`、`sketch-summary`）
+
+### 修复
+- `baoyu-xhs-images`：优化已弃用技能描述以改善路由匹配
+
+## 1.96.0 - 2026-04-09
+
+### 新功能
+- `baoyu-image-cards`：新增图片卡片系列技能，从 `baoyu-xhs-images` 迁移，解除小红书平台绑定
+- `baoyu-xhs-images`：已弃用，迁移至 `baoyu-image-cards`
+
+## 1.95.1 - 2026-04-09
+
+### 修复
+- `baoyu-slide-deck`：添加 `pptxgenjs` 依赖，PDF 合并时通过魔数字节检测图片格式替代文件扩展名判断
+
+## 1.95.0 - 2026-04-08
+
+### 新功能
+- `baoyu-infographic`：新增 `hand-drawn-edu` 风格 — 马卡龙柔和色块、手绘线条、火柴人角色
+- `baoyu-slide-deck`：新增 `hand-drawn-edu` 预设和 `macaron` 色调维度，含柔和马卡龙色板
+
+## 1.94.0 - 2026-04-08
+
+### 新功能
+- `baoyu-cover-image`：新增马卡龙色板和 hand-drawn-edu 风格预设
+
+## 1.93.0 - 2026-04-08
+
+### 新功能
+- `baoyu-article-illustrator`：新增 `hand-drawn-edu` 预设 — flowchart + sketch-notes + macaron 组合，用于手绘教育图解
+
+### 重构
+- `baoyu-article-illustrator`：将色板（Palette）提取为独立的第三维度，形成 Type × Style × Palette 三维系统
+
+### 修复
+- `baoyu-article-illustrator`：在工作流中添加显式的风格文件加载步骤
+
+## 1.92.0 - 2026-04-08
+
+### 新功能
+- `baoyu-article-illustrator`：新增 `macaron` 风格 — 马卡龙柔和色块（浅蓝、浅绿、浅紫、浅橙）配暖白底色，可选手绘模式；新增 `edu-visual` 预设
+
+## 1.90.1 - 2026-04-05
+
+### 修复
+- `baoyu-post-to-wechat`：通过 magic bytes 检测实际图片格式，修复 CDN 返回与 URL 扩展名不一致的 content-type 问题（如 .png URL 实际返回 WebP）；WebP 格式按 PNG 策略处理以保留透明度
+
+## 1.89.1 - 2026-04-01
+
+### 新功能
+- `baoyu-chrome-cdp`：新增 `gracefulKillChrome`，等待 Chrome 进程退出并释放端口；修复 `killChrome` 使用 `exitCode`/`signalCode` 替代 `.killed` 以更可靠地检测进程状态
+- `baoyu-fetch`：在交互等待模式下自动检测登录状态，未登录时提示用户先登录再提取内容
+
+### 维护
+- 同步 vendor baoyu-chrome-cdp 至所有 CDP 技能
+- `baoyu-url-to-markdown`：同步 vendor baoyu-fetch 的登录自动检测功能
+
+## 1.89.0 - 2026-03-31
+
+### 新功能
+- `baoyu-fetch`：新增 X 会话 Cookie 旁路文件，跨运行持久化登录状态；通过 Browser.close 优雅关闭 Chrome；自动检测并清理过期的 Chrome 配置锁文件
+- `baoyu-article-illustrator`：新增暖色调矢量插画配色方案，含 `warm-knowledge` 预设
+- `baoyu-post-to-x`：新增登录后 X 会话持久化、Chrome 锁文件恢复和优雅关闭
+
+### 文档
+- `baoyu-post-to-weibo`：新增发帖类型自动选择规则，优化 CDP Chrome 终止指令
+
+### 重构
+- `baoyu-danger-gemini-web`：使用优雅 Chrome 关闭替代强制终止
+- `baoyu-danger-x-to-markdown`：使用优雅 Chrome 关闭替代强制终止
+
+### 修复
+- 同步 npm lockfile 及修复根目录 Node 测试
+
+### 维护
+- `baoyu-url-to-markdown`：同步 vendor baoyu-fetch 的会话和生命周期改进
+- 更新 bun.lock 文件
+
+## 1.88.0 - 2026-03-27
+
+### 新功能
+- `baoyu-fetch`：新增 URL 阅读器 CLI 包，支持 Chrome CDP 和站点适配器（X/Twitter、YouTube、Hacker News、通用页面）
+
+### 重构
+- `baoyu-url-to-markdown`：用 `baoyu-fetch` CLI 替换自定义 CDP/转换管道
+- `shared-skill-packages`：支持 `package.json` 的 `files` 白名单，vendor 同步时过滤测试文件、CHANGELOG 和 `.changeset` 目录
+
+### 修复
+- `baoyu-md`：修正测试中图片路径 `images/` 为 `imgs/`
+
+## 1.87.2 - 2026-03-26
+
+### 重构
+- `baoyu-translate`：精简翻译提示词，将 15+ 条冗长原则压缩为 7 条，合并分析和审校步骤
+
+## 1.87.1 - 2026-03-26
+
+### 维护
+- 在 `baoyu-image-gen` SKILL.md 中添加废弃提示，引导用户使用 `baoyu-imagine`
+- 在 CLAUDE.md 中记录废弃技能策略
+
+## 1.87.0 - 2026-03-26
+
+### 维护
+- 移除已废弃的 `baoyu-image-gen` 重定向技能及插件清单条目 — 向 `baoyu-imagine` 的迁移已完成
+
+## 1.86.0 - 2026-03-25
+
+### 新功能
+- `baoyu-translate`：丰富翻译提示词的分析上下文 — 加入原文语气评估、结构化比喻映射表、理解难点推理、结构性/创造性翻译挑战，以及分块翻译的位置上下文
+
+## 1.85.0 - 2026-03-25
+
+### 新功能
+- `baoyu-imagine`：运行时自动迁移旧版 `baoyu-image-gen` 的 EXTEND.md 配置路径
+- 新增 `baoyu-image-gen` 废弃重定向技能，引导用户安装 `baoyu-imagine` 并移除旧技能
+
+## 1.84.0 - 2026-03-25
+
+### 新功能
+- 将 `baoyu-image-gen` 技能重命名为 `baoyu-imagine` — 更简短的命令名，所有文档、配置和依赖技能中的引用已同步更新
+
+## 1.83.0 - 2026-03-25
+
+### 新功能
+- `baoyu-image-gen`：新增 MiniMax 服务商（`image-01` / `image-01-live`），支持 subject_reference 角色/肖像一致性、自定义尺寸和宽高比
+
+## 1.82.0 - 2026-03-24
+
+### 新功能
+- `baoyu-url-to-markdown`：新增浏览器回退策略 — 默认无头模式优先，技术故障时自动重试有头 Chrome；新增 `--browser auto|headless|headed` 参数及 `--headless`/`--headed` 快捷方式
+- `baoyu-url-to-markdown`：新增内容清理模块，提取前预处理 HTML（移除广告、base64 图片、脚本、样式）
+- `baoyu-url-to-markdown`：媒体本地化支持 base64 data URI 图片
+- `baoyu-url-to-markdown`：从浏览器捕获最终 URL 以跟踪重定向，用于输出路径生成
+- `baoyu-url-to-markdown`：新增 Agent 质量门控文档，规范捕获后的内容验证流程
+
+### 依赖
+- `baoyu-url-to-markdown`：升级 defuddle ^0.12.0 → ^0.14.0
+
+### 测试
+- `baoyu-url-to-markdown`：新增 content-cleaner、html-to-markdown、legacy-converter、media-localizer 单元测试
+
+## 1.81.0 - 2026-03-24
+
+### 新功能
+- `baoyu-youtube-transcript`：YouTube 封锁直连 InnerTube API 时自动回退到 yt-dlp，支持备用客户端身份重试及通过 `YOUTUBE_TRANSCRIPT_COOKIES_FROM_BROWSER` 环境变量传递浏览器 Cookie
+
+### 重构
+- `baoyu-youtube-transcript`：将单体脚本拆分为类型化模块（youtube、transcript、storage、shared、types）并添加单元测试
+
+## 1.80.1 - 2026-03-24
+
+### 修复
+- `baoyu-image-gen`：修正即梦 API 请求中的 `prompt` 字段名
+
+## 1.80.0 - 2026-03-24
+
+### 新功能
+- `baoyu-image-gen`：新增 Azure OpenAI 作为独立图像生成服务商，支持灵活的端点解析、部署名称推断、质量映射及参考图片格式校验
+
+## 1.79.2 - 2026-03-23
+
+### 修复
+- `baoyu-cover-image`：简化参考图片处理流程 — 模型支持 `--ref` 时直接传递，仅在模型不支持参考图时创建描述文件
+- `baoyu-post-to-weibo`：文章 Markdown 转 HTML 时不传递 --theme 参数
+
+### 测试
+- 修复 Node 兼容的解析器测试，添加解析器测试依赖
+
+## 1.79.1 - 2026-03-23
+
+### 修复
+- 合并为单一插件，防止 skill 重复注册 (by @TyrealQ)
+- `baoyu-article-illustrator`：移除水印提示词中的不透明度参数
+- `baoyu-comic`：修正哆啦 A 梦命名间距，移除水印不透明度参数
+- `baoyu-xhs-images`：移除水印不透明度参数，修正中英文间距
+
+### 文档
+- 更新项目文档以反映单一插件架构
+
+## 1.79.0 - 2026-03-22
+
+### 新功能
+- `baoyu-post-to-wechat`：改进凭据加载机制，支持多来源优先级解析，并提供不完整凭据来源的诊断信息
+
+## 1.78.0 - 2026-03-22
+
+### 新功能
+- `baoyu-url-to-markdown`：新增 URL 专用解析层，支持 X/Twitter 和 archive.ph 站点的定制化 HTML 提取
+- `baoyu-url-to-markdown`：改进 slug 生成算法，去除停用词并采用子目录输出结构
+
+### 修复
+- `baoyu-url-to-markdown`：旧版转换器保留包含媒体元素的锚标签
+- `baoyu-url-to-markdown`：更智能的标题去重，避免重复添加标题
+
+## 1.77.0 - 2026-03-22
+
+### 新功能
+- `baoyu-youtube-transcript`：为章节数据添加结束时间 (by @jzOcb)
+
+### 修复
+- `sync-clawhub`：跳过失败的技能而不是中止同步
+
+## 1.76.1 - 2026-03-21
+
+### 文档
+- `baoyu-youtube-transcript`：修复 zsh glob 问题 — 运行脚本时始终对 YouTube URL 使用单引号
+
+## 1.76.0 - 2026-03-21
+
+### 新功能
+- `baoyu-youtube-transcript`：Markdown 输出中新增标题、描述摘要和封面图片
+
+### 修复
+- `baoyu-markdown-to-html`：测试运行器改用 process.execPath 和 tsx import
+
+## 1.75.0 - 2026-03-21
+
+### 新功能
+- `baoyu-youtube-transcript`：新技能 — 下载 YouTube 视频字幕/转录文本和封面图片，支持多语言、章节分段和说话人识别
+
+## 1.74.1 - 2026-03-21
+
+### 修复
+- `baoyu-image-gen`：对齐 OpenRouter 图像生成与当前 API，增强图像支持，收窄 Gemini 宽高比范围 (by @cwandev)
+- `baoyu-image-gen`：扩展 OpenRouter 模型检测和宽高比验证
+
+## 1.74.0 - 2026-03-20
+
+### 新功能
+- `baoyu-markdown-to-html`：CLI 支持全部渲染选项 — color、font-family、font-size、code-theme、mac-code-block、line-number、count、legend
+
+### 修复
+- `baoyu-markdown-to-html`：修复 CSS 自定义属性正则无法处理带引号值的问题；grace/simple 主题现在会叠加 default 主题 CSS
+
+## 1.73.3 - 2026-03-20
+
+### 修复
+- `baoyu-post-to-wechat`：修复占位符替换时短占位符错误匹配更长编号变体的问题
+
+## 1.73.2 - 2026-03-20
+
+### 修复
+- `baoyu-post-to-wechat`：修复正文图片上传，正确使用 media/uploadimg 接口并处理格式和大小限制 (by @AICreator-Wind)
+
+### 重构
+- `baoyu-post-to-wechat`：提取图片处理模块，本地转换不支持的格式（WebP/BMP/GIF → JPEG/PNG）而非回退到 material 接口
+
+## 1.73.1 - 2026-03-18
+
+### 重构
+- `baoyu-danger-x-to-markdown`：测试从 bun:test 迁移至 node:test
+
+## 1.73.0 - 2026-03-18
+
+### 新功能
+- `baoyu-danger-x-to-markdown`：支持 X 文章中的视频媒体，渲染封面图和视频链接
+
+## 1.72.0 - 2026-03-18
+
+### 新功能
+- `baoyu-danger-x-to-markdown`：支持渲染 X 文章中嵌入的 MARKDOWN 实体（代码块等）
+
+## 1.71.0 - 2026-03-17
+
+### 新功能
+- `baoyu-image-gen`：为 Seedream 5.0/4.5/4.0 模型添加参考图支持，并增加模型特定的尺寸校验
+
+## 1.70.0 - 2026-03-17
+
+### 新功能
+- `baoyu-format-markdown`：优化标题生成，基于公式智能推荐并提供平实风格备选
+- `baoyu-format-markdown`：自动生成双版本摘要（`summary` + `description`），写入 frontmatter
+
+## 1.69.1 - 2026-03-16
+
+### 修复
+- `baoyu-chrome-cdp`：收紧 Chrome 自动连接逻辑，减少误连接
+
+## 1.69.0 - 2026-03-16
+
+### 新功能
+- `baoyu-chrome-cdp`：支持连接到已有的 Chrome 会话 (by @bviews)
+
+### 修复
+- `baoyu-chrome-cdp`：支持 Chrome 146 原生远程调试（审批模式）(by @bviews)
+- `baoyu-chrome-cdp`：保留 findExistingChromeDebugPort 中的 HTTP 验证 (by @bviews)
+- `baoyu-danger-gemini-web`：复用 openPageSession 并修复孤立标签页泄漏 (by @bviews)
+- `baoyu-danger-gemini-web`：显式配置优先于自动发现 (by @bviews)
+- `baoyu-danger-gemini-web`：自动发现跳过时也遵循 BAOYU_CHROME_PROFILE_DIR (by @bviews)
+- `baoyu-post-to-wechat`：提升浏览器发布可靠性 (by @cfh-7598)
+
+### 文档
+- `baoyu-cover-image`：完善人物参考图片工作流和交互式确认说明
+
+## 1.68.0 - 2026-03-14
+
+### 新功能
+- `baoyu-article-illustrator`：新增可配置输出目录（`default_output_dir`），支持 4 种选项——`imgs-subdir`、`same-dir`、`illustrations-subdir`、`independent`
+- `baoyu-cover-image`：新增参考图片人物保留功能——当参考图包含人物时使用 `usage: direct` 传递给模型，风格化保留人物特征
+
+## 1.67.0 - 2026-03-13
+
+### 新功能
+- `baoyu-image-gen`：新增 DashScope qwen-image-2.0-pro 模型支持，支持自由尺寸和文字渲染 (by @JianJang2017)
+
+## 1.66.1 - 2026-03-13
+
+### 测试
+- 将测试文件从集中式 `tests/` 目录迁移至与源码同级
+- 将测试从 `.mjs` 转换为 TypeScript（`.test.ts`），使用 `tsx` 运行器
+- 新增 npm workspaces 配置，CI 工作流添加 npm 缓存
+
+## 1.66.0 - 2026-03-13
+
+### 新功能
+- `baoyu-image-gen`：新增即梦（Jimeng）和豆包（Seedream）图像生成服务商 (by @lindaifeng)
+
+### 修复
+- `baoyu-image-gen`：收紧即梦服务商行为
+
+### 重构
+- `baoyu-image-gen`：导出函数以支持测试，新增模块入口守卫
+
+### 文档
+- `baoyu-image-gen`：在 SKILL.md 和 README 中添加即梦和豆包服务商文档
+
+### 测试
+- 新增测试基础设施，包含 CI 工作流和 image-gen 单元测试
+
+## 1.65.1 - 2026-03-13
+
+### 重构
+- `baoyu-translate`：将 chunk 解析从 remark/unified 替换为 markdown-it，新增 main.ts CLI 入口
+
+## 1.65.0 - 2026-03-13
+
+### 新功能
+- `baoyu-post-to-wechat`：新增占位符图片上传支持，自动去重 Markdown 内嵌图片
+
+### 修复
+- `baoyu-post-to-wechat`：修复 frontmatter 解析，允许前导空白和可选的尾随换行
+
+### 重构
+- `baoyu-post-to-wechat`：将 `renderMarkdownToHtml` 重构为 `renderMarkdownWithPlaceholders`，输出结构化结果
+
+## 1.64.0 - 2026-03-13
+
+### 新功能
+- `baoyu-image-gen`：新增 OpenRouter 服务商，支持图像生成、参考图和可配置模型
+
+## 1.63.0 - 2026-03-13
+
+### 新功能
+- `baoyu-url-to-markdown`：本地浏览器抓取失败时自动回退到 `defuddle.md` 托管 API
+- `baoyu-url-to-markdown`：将 YouTube 字幕/文字记录提取到 Markdown 输出中
+- `baoyu-url-to-markdown`：转换前展开 Shadow DOM 内容，提升 Web Component 页面的转换质量
+- `baoyu-url-to-markdown`：Markdown front matter 中包含语言标识（如有）
+
+### 重构
+- `baoyu-url-to-markdown`：将单体转换器拆分为 defuddle、legacy 和 shared 三个模块
+
+### 文档
+- 修复 README 中 Claude Code marketplace 仓库名大小写
+
+## 1.62.0 - 2026-03-12
+
+### 新功能
+- `baoyu-infographic`：支持灵活宽高比，可使用自定义 W:H 值（如 3:4、4:3、2.35:1），同时保留预设名称
+
+### 修复
+- 设置插件严格模式，防止重复注册斜杠命令
+
+### 文档
+- `baoyu-post-to-wechat`：替换类似凭证的占位符
+
+## 1.61.0 - 2026-03-11
+
+### 新功能
+- `baoyu-post-to-wechat`：新增多账号支持，通过 `--account` 参数选择账号，EXTEND.md 支持 accounts 配置块，每个账号独立 Chrome 配置目录和凭证解析链
+
+### 修复
+- 排除 `out/dist/build` 目录和 `bun.lockb` 文件，避免打包到技能发布文件中
+- 修复技能发布时 MIME 类型不正确导致 ClawhHub 拒绝的问题
+
+## 1.60.0 - 2026-03-11
+
+### 新功能
+- `baoyu-url-to-markdown`：支持复用已有 Chrome CDP 实例，修复端口检测顺序问题
+
+### 修复
+- `baoyu-post-to-x`：补充 x-article 缺失的 `fs` 导入
+
+### 重构
+- 统一所有 CDP 技能使用共享 `baoyu-chrome-cdp` 包，各技能内置 vendor 副本
+- 精简 CLAUDE.md，将详细文档移至 `docs/` 目录
+- 从 synced vendor 直接发布技能，移除单独的 artifact 准备步骤
+
+## 1.59.1 - 2026-03-11
+
+### 修复
+- `baoyu-translate`：改进短文本注释密度规则，补充风格预设到 02-prompt.md 的显式传递
+- `baoyu-post-to-x`：移除 `--disable-blink-features=AutomationControlled` Chrome 启动参数
+
+### 重构
+- `baoyu-post-to-weibo`：为 md-to-html.ts 添加入口守卫，支持模块导入
+- 使用本地 sync-clawhub.mjs 脚本替代 clawhub CLI
+
+### 文档
+- 更新 CLAUDE.md 以反映 v1.59.0 代码库状态 (by @jackL1020)
+
+## 1.59.0 - 2026-03-09
+
+### 新功能
+- `baoyu-image-gen`：新增批量并行图片生成和提供商级别限流 (by @SeamoonAO)
+
+### 修复
+- `baoyu-image-gen`：修复多个 API key 可用时恢复 Google 为默认提供商
+
+### 文档
+- 改进技能文档清晰度 (by @SeamoonAO)
+
+## 1.58.0 - 2026-03-08
+
+### 新功能
+- 新增 EXTEND.md 的 XDG 配置路径支持 (by @liby)
+
+### 修复
+- `baoyu-post-to-wechat`：暴露 agent-browser 启动错误信息
+- `baoyu-post-to-wechat`：加固 agent-browser 命令和 eval 处理 (by @luojiyin1987)
+- `baoyu-image-gen`：使用 execFileSync 替代 shell 执行 Google curl 请求 (by @luojiyin1987)
+- `baoyu-format-markdown`：使用 spawnSync 替代 shell 执行 autocorrect 命令 (by @luojiyin1987)
+
+### 文档
+- 修正 CLAUDE 依赖说明 (by @luojiyin1987)
+- 将 markdown-to-html 添加到 README 工具技能列表 (by @luojiyin1987)
+
+## 1.57.0 - 2026-03-08
+
+### 新功能
+- 新增 ClawHub/OpenClaw 发布支持，包含同步脚本和 README 文档
+
+### 重构
+- 为所有 skill 前言添加 openclaw 元数据，兼容 ClawHub 注册表
+- 全部 skill 中将 `SKILL_DIR` 统一重命名为 `baseDir`
+- `baoyu-danger-gemini-web`、`baoyu-danger-x-to-markdown`：使用动态脚本路径显示用法
+- `baoyu-comic`、`baoyu-xhs-images`：通过 skill 接口调用图片生成，不再直接调用脚本
+
+## 1.56.1 - 2026-03-08
+
+### 修复
+- `baoyu-post-to-weibo`：简化头条文章图片插入逻辑，使用 Backspace 按键替代复杂的 deleteContents 方案，兼容 ProseMirror 编辑器
+
+## 1.56.0 - 2026-03-08
+
+### 新功能
+- `baoyu-article-illustrator`：预设优先选择流程，按内容类型分类的风格预设
+- `baoyu-xhs-images`：精简工作流从 6 步到 4 步，新增智能确认（快速/自定义/详细三种路径）
+
+### 修复
+- `baoyu-post-to-wechat`：通过文件选择器拦截改进图片上传可靠性
+
+## 1.55.0 - 2026-03-08
+
+### 新功能
+- `baoyu-article-illustrator`：新增 screen-print 风格和 `--preset` 快捷预设（如 tech-explainer、opinion-piece）
+- `baoyu-cover-image`：新增 screen-print 渲染风格和 duotone 调色板，包含 5 个新预设（poster-art、mondo 等）
+- `baoyu-xhs-images`：新增 screen-print 风格和 `--preset` 快捷预设，内置 23 个场景预设
+
+### 文档
+- 为中英文 README 新增致谢章节，致敬相关开源项目
+
+## 1.54.1 - 2026-03-07
+
+### 修复
+- `baoyu-post-to-x`：保持已填充的发帖窗口处于打开状态，方便用户手动检查并发布
+
+### 文档
+- `baoyu-post-to-x`：补充默认帖子类型选择规则和手动发布流程说明
+- `README`：为中英文 README 新增 Star History 图表
+
+## 1.54.0 - 2026-03-06
+
+### 新功能
+- `baoyu-format-markdown`：优化标题和摘要生成，支持多风格候选（颠覆型、方案型、悬念型、数字型），新增禁用模式和钩子优先原则
+- `baoyu-markdown-to-html`：新增 `--cite` 选项，将普通外链转换为底部编号引用
+- `baoyu-post-to-wechat`：Markdown 输入默认启用底部引用，新增 `--no-cite` 标志可关闭
+- `baoyu-translate`：EXTEND.md 支持 `glossary_files` 加载外部术语表文件（Markdown 表格或 YAML 格式）
+- `baoyu-translate`：新增 frontmatter 转换规则，翻译时将源文章元数据字段添加 `source` 前缀
+
+## 1.53.0 - 2026-03-06
+
+### 新功能
+- `baoyu-url-to-markdown`：将渲染后的 HTML 快照保存为 `-captured.html`，与 Markdown 文件并列输出
+- `baoyu-url-to-markdown`：优先使用 Defuddle 转换，失败时自动回退到旧版 Readability/选择器提取器
+
+## 1.52.0 - 2026-03-06
+
+### 新功能
+- `baoyu-post-to-weibo`：新增 `--video` 视频上传支持（图片+视频最多 18 个文件）
+- `baoyu-post-to-weibo`：上传方式从剪贴板粘贴改为 `DOM.setFileInputFiles`，提升上传可靠性
+
+### 修复
+- `baoyu-post-to-weibo`：新增 Chrome 健康检查，无响应时自动重启
+- `baoyu-post-to-weibo`：发布前检查页面是否在微博首页，避免在错误页面操作
+
+## 1.51.2 - 2026-03-06
+
+### 修复
+- `release-skills`：将显式语言文件名模式（如 `CHANGELOG.de.md`）替换为通用模式，避免 Gen Agent Trust Hub URL 扫描器误报
+- `baoyu-infographic`：新增凭证/密钥剥离指令，解决 Snyk W007 不安全凭证处理审计问题
+
+## 1.51.1 - 2026-03-06
+
+### 重构
+- 统一 Chrome CDP profile 路径——所有 skill 共享 `baoyu-skills/chrome-profile`，不再各自独立目录
+- 修复 `baoyu-post-to-weibo` 错误复用 `x-browser-profile` 路径的问题
+
+### 修复
+- 移除所有安装说明中的 `curl | bash` 远程代码执行模式
+- `md-to-html` 脚本强制仅允许 HTTPS 下载远程图片
+- 添加重定向次数限制（最多 5 次），防止无限重定向
+- 在 CLAUDE.md 中新增安全准则章节
+
+## 1.51.0 - 2026-03-06
+
+### 新功能
+- `baoyu-post-to-weibo`：新增微博发布技能——支持带图文本发布和头条文章，通过 Chrome CDP 自动化操作
+- `baoyu-format-markdown`：新增标题/摘要多候选项选择——生成 3 个候选供用户选择，支持 EXTEND.md 中的 `auto_select` 配置
+
+## 1.50.0 - 2026-03-06
+
+### 新功能
+- `baoyu-translate`：翻译风格预设从 4 种扩展到 9 种——新增学术、商务、幽默、口语化和优雅风格
+- `baoyu-translate`：新增 `--style` 命令行参数，支持按次指定翻译风格
+- `baoyu-translate`：将风格指令集成到子代理提示词模板
+
+## 1.49.0 - 2026-03-06
+
+### 新功能
+- `baoyu-format-markdown`：新增读者视角内容分析阶段——在应用格式之前先分析要点、结构和格式问题
+- `baoyu-format-markdown`：重构工作流从 8 步精简为 7 步，新增明确的格式化原则和完成报告模板
+- `baoyu-translate`：将步骤 2 的工作流机制提取到独立参考文件，精简 SKILL.md
+- `baoyu-translate`：扩展触发关键词（改成中文、快翻、本地化等），提升技能激活准确度
+- `baoyu-translate`：快速翻译模式下对长内容主动提示切换建议
+- `baoyu-translate`：分块时将 frontmatter 保存到 `chunks/frontmatter.md`
+
+## 1.48.2 - 2026-03-06
+
+### 新功能
+- `baoyu-translate`：在精翻工作流的审查和修订阶段新增比喻语言与情感忠实度检查
+- `baoyu-translate`：增强快速翻译模式，强制执行比喻语言的意义优先翻译原则
+
+## 1.48.1 - 2026-03-05
+
+### 新功能
+- `baoyu-translate`：在分析阶段新增比喻语言与隐喻映射——翻译前先解读隐喻、习语和隐含意义，避免字面直译
+- `baoyu-translate`：新增"意义优先于字面"、"比喻语言解读"、"情感忠实度"三项翻译原则，同步更新 SKILL.md、精翻工作流和子代理提示词模板
+
+## 1.48.0 - 2026-03-05
+
+### 新功能
+- `baoyu-translate`：为 chunk.ts 新增 `--output-dir` 选项——分块文件现在写入翻译输出目录而非源文件目录
+- `baoyu-translate`：优化精翻工作流——将审校拆分为批判性审查 + 修订（5→6 步），新增中日韩目标语言的欧化表达诊断
+
+## 1.47.0 - 2026-03-05
+
+### 新功能
+- 新增 `baoyu-translate` 翻译技能——支持快速/标准/精翻三种模式，自定义术语表、面向受众翻译、长文档自动分块并行翻译
+- 为所有技能的 EXTEND.md 偏好检测添加 PowerShell 跨平台支持
+
+## 1.46.0 - 2026-03-05
+
+### 新功能
+- 为 url-to-markdown 新增 `--output-dir` 选项，支持自定义输出目录并自动生成文件名
+
 ## 1.45.1 - 2026-03-05
 
 ### 重构

CLAUDE.md

@@ -1,455 +1,101 @@
 # CLAUDE.md
 
-This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.
-
-## Project Overview
-
-Claude Code marketplace plugin providing AI-powered content generation skills. Skills use Gemini Web API (reverse-engineered) for text/image generation and Chrome CDP for browser automation.
+Claude Code marketplace plugin providing AI-powered content generation skills. Version: **1.107.0**.
 
 ## Architecture
 
-Skills are organized into three plugin categories in `marketplace.json`:
+Skills are exposed through the single `baoyu-skills` plugin in `.claude-plugin/marketplace.json` (which defines plugin metadata, version, and skill paths). The repo docs still group them into three logical areas:
 
-```
-skills/
-├── [content-skills]           # Content generation and publishing
-│   ├── baoyu-xhs-images/          # Xiaohongshu infographic series (1-10 images)
-│   ├── baoyu-cover-image/         # Article cover images (2.35:1 aspect)
-│   ├── baoyu-slide-deck/          # Presentation slides with outlines
-│   ├── baoyu-article-illustrator/ # Smart illustration placement
-│   ├── baoyu-comic/               # Knowledge comics (Logicomix/Ohmsha style)
-│   ├── baoyu-post-to-x/           # X/Twitter posting automation
-│   └── baoyu-post-to-wechat/      # WeChat Official Account posting
-│
-├── [ai-generation-skills]     # AI-powered generation backends
-│   └── baoyu-danger-gemini-web/   # Gemini API wrapper (text + image gen)
-│
-└── [utility-skills]           # Utility tools for content processing
-    ├── baoyu-danger-x-to-markdown/ # X/Twitter content to markdown
-    └── baoyu-compress-image/      # Image compression
-```
+| Group | Description |
+|-------|-------------|
+| Content Skills | Generate or publish content (images, slides, comics, posts) |
+| AI Generation Skills | AI generation backends |
+| Utility Skills | Content processing (conversion, compression, translation) |
 
-**Plugin Categories**:
-| Category | Description |
-|----------|-------------|
-| `content-skills` | Skills that generate or publish content (images, slides, comics, posts) |
-| `ai-generation-skills` | Backend skills providing AI generation capabilities |
-| `utility-skills` | Helper tools for content processing (conversion, compression) |
+Each skill contains `SKILL.md` (YAML front matter + docs), optional `scripts/`, `references/`, `prompts/`.
 
-Each skill contains:
-- `SKILL.md` - YAML front matter (name, description) + documentation
-- `scripts/` - TypeScript implementations
-- `prompts/system.md` - AI generation guidelines (optional)
+Top-level `scripts/` contains repo maintenance utilities (sync, hooks, publish).
 
 ## Running Skills
 
-All scripts are TypeScript, executed via Bun runtime (no build step).
-
-### Runtime Detection (`${BUN_X}`)
-
-Before running any script, the agent MUST detect the runtime **once per session** and set `${BUN_X}`:
-
+TypeScript via Bun (no build step). Detect runtime once per session:
 ```bash
-# Detect runtime (run once, reuse result)
-if command -v bun &>/dev/null; then
-  BUN_X="bun"
-elif command -v npx &>/dev/null; then
-  BUN_X="npx -y bun"
-else
-  echo "Error: Neither bun nor npx found. Install bun: curl -fsSL https://bun.sh/install | bash"
-  exit 1
-fi
+if command -v bun &>/dev/null; then BUN_X="bun"
+elif command -v npx &>/dev/null; then BUN_X="npx -y bun"
+else echo "Error: install bun: brew install oven-sh/bun/bun or npm install -g bun"; exit 1; fi
 ```
 
-| Priority | Condition | `${BUN_X}` value | Notes |
-|----------|-----------|-------------------|-------|
-| 1 | `bun` installed | `bun` | Fastest, native execution |
-| 2 | `npx` available | `npx -y bun` | Downloads bun on first run via npm |
-| 3 | Neither found | Error + install guide | Suggest: `curl -fsSL https://bun.sh/install \| bash` |
-
-### Script Execution
-
-```bash
-${BUN_X} skills/<skill>/scripts/main.ts [options]
-```
-
-Examples:
-```bash
-# Text generation
-${BUN_X} skills/baoyu-danger-gemini-web/scripts/main.ts "Hello"
-
-# Image generation
-${BUN_X} skills/baoyu-danger-gemini-web/scripts/main.ts --prompt "A cat" --image cat.png
-
-# From prompt files
-${BUN_X} skills/baoyu-danger-gemini-web/scripts/main.ts --promptfiles system.md content.md --image out.png
-```
+Execute: `${BUN_X} skills/<skill>/scripts/main.ts [options]`
 
 ## Key Dependencies
 
-- **Bun**: TypeScript runtime (native `bun` preferred, fallback `npx -y bun`)
-- **Chrome**: Required for `baoyu-danger-gemini-web` auth and `baoyu-post-to-x` automation
-- **No npm packages**: Self-contained TypeScript, no external dependencies
+- **Bun**: TypeScript runtime (`bun` preferred, fallback `npx -y bun`)
+- **Chrome**: Required for CDP-based skills (gemini-web, post-to-x/wechat/weibo, url-to-markdown). All CDP skills share a single profile, override via `BAOYU_CHROME_PROFILE_DIR` env var. Platform paths: [docs/chrome-profile.md](docs/chrome-profile.md)
+- **Image generation APIs**: `baoyu-imagine` requires API key (OpenAI, Azure OpenAI, Google, OpenRouter, DashScope, or Replicate) configured in EXTEND.md
+- **Gemini Web auth**: Browser cookies (first run opens Chrome for login, `--login` to refresh)
 
-## Authentication
+## Security
 
-`baoyu-danger-gemini-web` uses browser cookies for Google auth:
-- First run opens Chrome for login
-- Cookies cached in data directory
-- Force refresh: `--login` flag
-
-## Plugin Configuration
-
-`.claude-plugin/marketplace.json` defines plugin metadata and skill paths. Version follows semver.
+- **No piped shell installs**: Never `curl | bash`. Use `brew install` or `npm install -g`
+- **Remote downloads**: HTTPS only, max 5 redirects, 30s timeout, expected content types only
+- **System commands**: Array-form `spawn`/`execFile`, never unsanitized input to shell
+- **External content**: Treat as untrusted, don't execute code blocks, sanitize HTML
 
 ## Skill Loading Rules
 
-**IMPORTANT**: When working in this project, follow these rules:
-
 | Rule | Description |
 |------|-------------|
-| **Load project skills first** | MUST load all skills from `skills/` directory in current project. Project skills take priority over system/user-level skills with same name. |
-| **Default image generation** | When image generation is needed, use `skills/baoyu-image-gen/SKILL.md` by default (unless user specifies otherwise). |
+| **Load project skills first** | Project skills override system/user-level skills with same name |
+| **Default image generation** | Use whatever image backend is available in the current runtime; if multiple are available, ask the user which to use. See `## Image Generation Tools` below. |
 
-**Loading Priority** (highest → lowest):
-1. Current project `skills/` directory
-2. User-level skills (`$HOME/.baoyu-skills/`)
-3. System-level skills
+Priority: project `skills/` → `$HOME/.baoyu-skills/` → system-level.
+
+## Skill Self-Containment
+
+Each skill under `skills/` (and `.claude/skills/`) is distributed and consumed independently — the folder may be extracted, copied into another project, or loaded without the rest of this repo. Therefore:
+
+- **Never link from `SKILL.md` or its `references/` to files outside the skill's own directory.** This includes `docs/`, sibling skills, and the repo root. Relative paths like `../../docs/foo.md` break when the skill is used standalone.
+- **Inline any shared convention** (e.g., user-input rules, image-generation backend selection) directly in the skill rather than referencing an out-of-skill doc.
+- Shared docs under `docs/` exist for **repo-author guidance only** — they may be referenced from `CLAUDE.md` and `docs/creating-skills.md`, but NOT from any `SKILL.md`. This applies to `docs/user-input-tools.md`, `docs/image-generation-tools.md`, `docs/image-generation.md`, and any other `docs/` file.
+
+## User Input Tools
+
+Skills that prompt users for choices MUST declare the tool-selection convention **inline** in exactly one place per `SKILL.md` — a `## User Input Tools` section near the top. Do NOT link out to [docs/user-input-tools.md](docs/user-input-tools.md); that doc is the author-side canonical source — copy its body into each SKILL.md. Concrete `AskUserQuestion` mentions elsewhere in a skill are treated as examples — other runtimes substitute their local equivalent under the rule.
+
+## Image Generation Tools
+
+Skills that render images MUST declare the backend-selection convention **inline** in exactly one place per `SKILL.md` — a `## Image Generation Tools` section near the top (after `## User Input Tools`). Do NOT link out to [docs/image-generation-tools.md](docs/image-generation-tools.md); that doc is the author-side canonical source — copy its body into each SKILL.md. Concrete tool names (`imagegen`, `image_generate`, `baoyu-imagine`) elsewhere in a skill are treated as examples — other runtimes substitute their local equivalent under the rule. The rule is stateless: use whatever backend is available; if multiple, ask the user once; if none, ask how to proceed. Every rendered image's full prompt must be written to a standalone `prompts/NN-*.md` file before any backend is invoked. Backend skills (`baoyu-imagine`, `baoyu-image-gen`, `baoyu-danger-gemini-web`) are exempt — they render directly rather than selecting a backend.
+
+## Deprecated Skills
+
+| Skill | Note |
+|-------|------|
+| `baoyu-image-gen` | Superseded by `baoyu-imagine`. Not in `.claude-plugin/marketplace.json`. Kept functional — sync any cross-cutting changes with `baoyu-imagine`. |
+| `baoyu-xhs-images` | Superseded by `baoyu-image-cards`. Not in `.claude-plugin/marketplace.json`. Kept functional — sync any cross-cutting changes with `baoyu-image-cards`. Do NOT update README for this skill. |
 
 ## Release Process
 
-**IMPORTANT**: When user requests release/发布/push, ALWAYS use `/release-skills` workflow.
-
-**Never skip**:
-1. `CHANGELOG.md` + `CHANGELOG.zh.md` - Both must be updated
+Use `/release-skills` workflow. Never skip:
+1. `CHANGELOG.md` + `CHANGELOG.zh.md`
 2. `marketplace.json` version bump
 3. `README.md` + `README.zh.md` if applicable
 4. All files committed together before tag
 
-## Adding New Skills
-
-**IMPORTANT**: All skills MUST use `baoyu-` prefix to avoid conflicts when users import this plugin.
-
-**REQUIRED READING**: Before creating a new skill, read the official [Skill authoring best practices](https://platform.claude.com/docs/en/agents-and-tools/agent-skills/best-practices).
-
-### Key Requirements from Official Best Practices
-
-| Requirement | Details |
-|-------------|---------|
-| **Concise is key** | Claude is smart—only add context it doesn't have. Challenge each token. |
-| **name field** | Max 64 chars, lowercase letters/numbers/hyphens only, no "anthropic"/"claude" |
-| **description field** | Max 1024 chars, non-empty, MUST be third person, include what + when to use |
-| **SKILL.md body** | Keep under 500 lines; use separate files for additional content |
-| **Naming convention** | Gerund form preferred (e.g., `processing-pdfs`), but `baoyu-` prefix required here |
-| **References** | Keep one level deep from SKILL.md; avoid nested references |
-| **No time-sensitive info** | Avoid dates/versions that become outdated |
-
-### Steps
-
-1. Create `skills/baoyu-<name>/SKILL.md` with YAML front matter
-   - Directory name: `baoyu-<name>`
-   - SKILL.md `name` field: `baoyu-<name>`
-2. Add TypeScript in `skills/baoyu-<name>/scripts/`
-3. Add prompt templates in `skills/baoyu-<name>/prompts/` if needed
-4. **Choose the appropriate category** and register in `marketplace.json`:
-   - `content-skills`: For content generation/publishing (images, slides, posts)
-   - `ai-generation-skills`: For AI backend capabilities
-   - `utility-skills`: For helper tools (conversion, compression)
-   - If none fit, create a new category with descriptive name
-5. **Add Script Directory section** to SKILL.md (see template below)
-
-### Choosing a Category
-
-| If your skill... | Use category |
-|------------------|--------------|
-| Generates visual content (images, slides, comics) | `content-skills` |
-| Publishes to platforms (X, WeChat, etc.) | `content-skills` |
-| Provides AI generation backend | `ai-generation-skills` |
-| Converts or processes content | `utility-skills` |
-| Compresses or optimizes files | `utility-skills` |
-
-**Creating a new category**: If the skill doesn't fit existing categories, add a new plugin object to `marketplace.json` with:
-- `name`: Descriptive kebab-case name (e.g., `analytics-skills`)
-- `description`: Brief description of the category
-- `skills`: Array with the skill path
-
-### Writing Effective Descriptions
-
-**MUST write in third person** (not "I can help you" or "You can use this"):
-
-```yaml
-# Good
-description: Generates Xiaohongshu infographic series from content. Use when user asks for "小红书图片", "XHS images", or "RedNote infographics".
-
-# Bad
-description: I can help you create Xiaohongshu images
-description: You can use this to generate XHS content
-```
-
-Include both **what** the skill does and **when** to use it (triggers/keywords).
-
-### Script Directory Template
-
-Every SKILL.md with scripts MUST include this section after Usage:
-
-```markdown
-## Script Directory
-
-**Important**: All scripts are located in the `scripts/` subdirectory of this skill.
-
-**Agent Execution Instructions**:
-1. Determine this SKILL.md file's directory path as `SKILL_DIR`
-2. Script path = `${SKILL_DIR}/scripts/<script-name>.ts`
-3. Resolve `${BUN_X}` runtime: if `bun` installed → `bun`; if `npx` available → `npx -y bun`; else suggest installing bun
-4. Replace all `${SKILL_DIR}` and `${BUN_X}` in this document with actual values
-
-**Script Reference**:
-| Script | Purpose |
-|--------|---------|
-| `scripts/main.ts` | Main entry point |
-| `scripts/other.ts` | Other functionality |
-```
-
-When referencing scripts in workflow sections, use `${BUN_X} ${SKILL_DIR}/scripts/<name>.ts` so agents can resolve the correct runtime and path.
-
-### Progressive Disclosure
-
-For skills with extensive content, use separate reference files:
-
-```
-skills/baoyu-example/
-├── SKILL.md              # Main instructions (<500 lines)
-├── references/
-│   ├── styles.md         # Style definitions (loaded as needed)
-│   └── examples.md       # Usage examples (loaded as needed)
-└── scripts/
-    └── main.ts           # Executable script
-```
-
-In SKILL.md, link to reference files (one level deep only):
-```markdown
-**Available styles**: See [references/styles.md](references/styles.md)
-**Examples**: See [references/examples.md](references/examples.md)
-```
-
 ## Code Style
 
-- TypeScript throughout, no comments
-- Async/await patterns
-- Short variable names
-- Type-safe interfaces
+TypeScript, no comments, async/await, short variable names, type-safe interfaces.
 
-## Image Generation Guidelines
+## Adding New Skills
 
-Skills that require image generation MUST delegate to available image generation skills rather than implementing their own.
+All skills MUST use `baoyu-` prefix. Details: [docs/creating-skills.md](docs/creating-skills.md)
 
-### Image Generation Skill Selection
+## Reference Docs
 
-**Default**: Use `skills/baoyu-image-gen/SKILL.md` (unless user specifies otherwise).
-
-1. Read `skills/baoyu-image-gen/SKILL.md` for parameters and capabilities
-2. If user explicitly requests a different skill, check `skills/` directory for alternatives
-3. Only ask user to choose when they haven't specified and multiple viable options exist
-
-### Generation Flow Template
-
-Use this template when implementing image generation in skills:
-
-```markdown
-### Step N: Generate Images
-
-**Skill Selection**:
-1. Check available image generation skills (e.g., `baoyu-danger-gemini-web`)
-2. Read selected skill's SKILL.md for parameter reference
-3. If multiple skills available, ask user to choose
-
-**Generation Flow**:
-1. Call selected image generation skill with:
-   - Prompt file path (or inline prompt)
-   - Output image path
-   - Any skill-specific parameters (refer to skill's SKILL.md)
-2. Generate images sequentially (one at a time)
-3. After each image, output progress: "Generated X/N"
-4. On failure, auto-retry once before reporting error
-```
-
-### Output Path Convention
-
-Each session creates an independent directory. Even the same source file generates a new directory per session.
-
-**Output Directory**:
-```
-<skill-suffix>/<topic-slug>/
-```
-- `<skill-suffix>`: Skill name suffix (e.g., `xhs-images`, `cover-image`, `slide-deck`, `comic`)
-- `<topic-slug>`: Generated from content topic (2-4 words, kebab-case)
-- Example: `xhs-images/ai-future-trends/`
-
-**Slug Generation**:
-1. Extract main topic from content (2-4 words, kebab-case)
-2. Example: "Introduction to Machine Learning" → `intro-machine-learning`
-
-**Conflict Resolution**:
-If `<skill-suffix>/<topic-slug>/` already exists:
-- Append timestamp: `<topic-slug>-YYYYMMDD-HHMMSS`
-- Example: `ai-future` exists → `ai-future-20260118-143052`
-
-**Source Files**:
-- Copy all sources to `<skill-suffix>/<topic-slug>/` with naming: `source-{slug}.{ext}`
-- Multiple sources supported: text, images, files from conversation
-- Examples:
-  - `source-article.md` (main text content)
-  - `source-reference.png` (image from conversation)
-  - `source-data.csv` (additional file)
-- Original source files remain unchanged
-
-### Image Naming Convention
-
-Image filenames MUST include meaningful slugs for readability:
-
-**Format**: `NN-{type}-[slug].png`
-- `NN`: Two-digit sequence number (01, 02, ...)
-- `{type}`: Image type (cover, content, page, slide, illustration, etc.)
-- `[slug]`: Descriptive kebab-case slug derived from content
-
-**Examples**:
-```
-01-cover-ai-future.png
-02-content-key-benefits.png
-03-page-enigma-machine.png
-04-slide-architecture-overview.png
-```
-
-**Slug Rules**:
-- Derived from image purpose or content (kebab-case)
-- Must be unique within the output directory
-- 2-5 words, concise but descriptive
-- When content changes significantly, update slug accordingly
-
-### Best Practices
-
-- Always read the image generation skill's SKILL.md before calling
-- Pass parameters exactly as documented in the skill
-- Handle failures gracefully with retry logic
-- Provide clear progress feedback to user
-
-## Style Maintenance (baoyu-comic)
-
-When adding, updating, or deleting styles for `baoyu-comic`, follow this workflow:
-
-### Adding a New Style
-
-1. **Create style definition**: `skills/baoyu-comic/references/styles/<style-name>.md`
-2. **Update SKILL.md**:
-   - Add style to `--style` options table
-   - Add auto-selection entry if applicable
-3. **Generate showcase image**:
-   ```bash
-   ${BUN_X} skills/baoyu-danger-gemini-web/scripts/main.ts \
-     --prompt "A single comic book page in <style-name> style showing [appropriate scene]. Features: [style characteristics from style definition]. 3:4 portrait aspect ratio comic page." \
-     --image screenshots/comic-styles/<style-name>.png
-   ```
-4. **Compress to WebP**:
-   ```bash
-   ${BUN_X} skills/baoyu-compress-image/scripts/main.ts screenshots/comic-styles/<style-name>.png
-   ```
-5. **Update both READMEs** (`README.md` and `README.zh.md`):
-   - Add style to `--style` options
-   - Add row to style description table
-   - Add image to style preview grid
-
-### Updating an Existing Style
-
-1. **Update style definition**: `skills/baoyu-comic/references/styles/<style-name>.md`
-2. **Regenerate showcase image** (if visual characteristics changed):
-   - Follow steps 3-4 from "Adding a New Style"
-3. **Update READMEs** if description changed
-
-### Deleting a Style
-
-1. **Delete style definition**: `skills/baoyu-comic/references/styles/<style-name>.md`
-2. **Delete showcase image**: `screenshots/comic-styles/<style-name>.webp`
-3. **Update SKILL.md**:
-   - Remove from `--style` options
-   - Remove auto-selection entry
-4. **Update both READMEs**:
-   - Remove from `--style` options
-   - Remove from style description table
-   - Remove from style preview grid
-
-### Style Preview Grid Format
-
-READMEs use 3-column tables for style previews:
-
-```markdown
-| | | |
-|:---:|:---:|:---:|
-| ![style1](./screenshots/comic-styles/style1.webp) | ![style2](./screenshots/comic-styles/style2.webp) | ![style3](./screenshots/comic-styles/style3.webp) |
-| style1 | style2 | style3 |
-```
-
-## Extension Support
-
-Every SKILL.md MUST include two parts for extension support:
-
-### 1. Load Preferences Section (in Step 1 or as "Preferences" section)
-
-For skills with workflows, add as Step 1.1. For utility skills, add as "Preferences (EXTEND.md)" section before Usage:
-
-```markdown
-**1.1 Load Preferences (EXTEND.md)**
-
-Use Bash to check EXTEND.md existence (priority order):
-
-\`\`\`bash
-# Check project-level first
-test -f .baoyu-skills/<skill-name>/EXTEND.md && echo "project"
-
-# Then user-level (cross-platform: $HOME works on macOS/Linux/WSL)
-test -f "$HOME/.baoyu-skills/<skill-name>/EXTEND.md" && echo "user"
-\`\`\`
-
-┌────────────────────────────────────────────┬───────────────────┐
-│                    Path                    │     Location      │
-├────────────────────────────────────────────┼───────────────────┤
-│ .baoyu-skills/<skill-name>/EXTEND.md       │ Project directory │
-├────────────────────────────────────────────┼───────────────────┤
-│ $HOME/.baoyu-skills/<skill-name>/EXTEND.md │ User home         │
-└────────────────────────────────────────────┴───────────────────┘
-
-┌───────────┬───────────────────────────────────────────────────────────────────────────┐
-│  Result   │                                  Action                                   │
-├───────────┼───────────────────────────────────────────────────────────────────────────┤
-│ Found     │ Read, parse, display summary                                              │
-├───────────┼───────────────────────────────────────────────────────────────────────────┤
-│ Not found │ Ask user with AskUserQuestion (see references/config/first-time-setup.md) │
-└───────────┴───────────────────────────────────────────────────────────────────────────┘
-
-**EXTEND.md Supports**: [List supported configuration options for this skill]
-
-Schema: `references/config/preferences-schema.md`
-```
-
-### 2. Extension Support Section (at the end)
-
-Simplified section that references the preferences section:
-
-```markdown
-## Extension Support
-
-Custom configurations via EXTEND.md. See **Step 1.1** for paths and supported options.
-```
-
-Or for utility skills without workflow steps:
-
-```markdown
-## Extension Support
-
-Custom configurations via EXTEND.md. See **Preferences** section for paths and supported options.
-```
-
-**Notes**:
-- Replace `<skill-name>` with actual skill name (e.g., `baoyu-cover-image`)
-- Use `$HOME` instead of `~` for cross-platform compatibility (macOS/Linux/WSL)
-- Use `test -f` Bash command for explicit file existence check
-- ASCII tables for clear visual formatting
+| Topic | File |
+|-------|------|
+| Image generation output guidelines | [docs/image-generation.md](docs/image-generation.md) |
+| Image generation backend selection | [docs/image-generation-tools.md](docs/image-generation-tools.md) |
+| User input tool convention | [docs/user-input-tools.md](docs/user-input-tools.md) |
+| Chrome profile platform paths | [docs/chrome-profile.md](docs/chrome-profile.md) |
+| Comic style maintenance | [docs/comic-style-maintenance.md](docs/comic-style-maintenance.md) |
+| ClawHub/OpenClaw publishing | [docs/publishing.md](docs/publishing.md) |

README.md

@@ -17,12 +17,33 @@ Skills shared by Baoyu for improving daily work efficiency with Claude Code.
 npx skills add jimliu/baoyu-skills
 ```
 
+### Publish to ClawHub / OpenClaw
+
+This repository now supports publishing each `skills/baoyu-*` directory as an individual ClawHub skill.
+
+```bash
+# Preview what would be published
+./scripts/sync-clawhub.sh --dry-run
+
+# Publish all changed skills from ./skills
+./scripts/sync-clawhub.sh --all
+```
+
+ClawHub installs skills individually, not as one marketplace bundle. After publishing, users can install specific skills such as:
+
+```bash
+clawhub install baoyu-imagine
+clawhub install baoyu-markdown-to-html
+```
+
+Publishing to ClawHub releases the published skill under `MIT-0`, per ClawHub's registry rules.
+
 ### Register as Plugin Marketplace
 
 Run the following command in Claude Code:
 
 ```bash
-/plugin marketplace add jimliu/baoyu-skills
+/plugin marketplace add JimLiu/baoyu-skills
 ```
 
 ### Install Skills
@@ -31,16 +52,14 @@ Run the following command in Claude Code:
 
 1. Select **Browse and install plugins**
 2. Select **baoyu-skills**
-3. Select the plugin(s) you want to install
+3. Select the **baoyu-skills** plugin
 4. Select **Install now**
 
 **Option 2: Direct Install**
 
 ```bash
-# Install specific plugin
-/plugin install content-skills@baoyu-skills
-/plugin install ai-generation-skills@baoyu-skills
-/plugin install utility-skills@baoyu-skills
+# Install the marketplace's single plugin
+/plugin install baoyu-skills@baoyu-skills
 ```
 
 **Option 3: Ask the Agent**
@@ -49,13 +68,13 @@ Simply tell Claude Code:
 
 > Please install Skills from github.com/JimLiu/baoyu-skills
 
-### Available Plugins
+### Available Plugin
 
-| Plugin | Description | Skills |
-|--------|-------------|--------|
-| **content-skills** | Content generation and publishing | [xhs-images](#baoyu-xhs-images), [infographic](#baoyu-infographic), [cover-image](#baoyu-cover-image), [slide-deck](#baoyu-slide-deck), [comic](#baoyu-comic), [article-illustrator](#baoyu-article-illustrator), [post-to-x](#baoyu-post-to-x), [post-to-wechat](#baoyu-post-to-wechat) |
-| **ai-generation-skills** | AI-powered generation backends | [image-gen](#baoyu-image-gen), [danger-gemini-web](#baoyu-danger-gemini-web) |
-| **utility-skills** | Utility tools for content processing | [url-to-markdown](#baoyu-url-to-markdown), [danger-x-to-markdown](#baoyu-danger-x-to-markdown), [compress-image](#baoyu-compress-image), [format-markdown](#baoyu-format-markdown) |
+The marketplace now exposes a single plugin so each skill is registered exactly once.
+
+| Plugin | Description | Includes |
+|--------|-------------|----------|
+| **baoyu-skills** | Content generation, AI backends, and utility tools for daily work efficiency | All skills in this repository, organized below as Content Skills, AI Generation Skills, and Utility Skills |
 
 ## Update Skills
 
@@ -80,7 +99,7 @@ Content generation and publishing skills.
 
 #### baoyu-xhs-images
 
-Xiaohongshu (RedNote) infographic series generator. Breaks down content into 1-10 cartoon-style infographics with **Style × Layout** two-dimensional system.
+Xiaohongshu image card series generator. Breaks down content into 1-10 cartoon-style image cards with **Style × Layout** system and optional palette override.
 
 ```bash
 # Auto-select style and layout
@@ -93,13 +112,22 @@ Xiaohongshu (RedNote) infographic series generator. Breaks down content into 1-1
 /baoyu-xhs-images posts/ai-future/article.md --layout dense
 
 # Combine style and layout
-/baoyu-xhs-images posts/ai-future/article.md --style tech --layout list
+/baoyu-xhs-images posts/ai-future/article.md --style notion --layout list
+
+# Override palette
+/baoyu-xhs-images posts/ai-future/article.md --style notion --palette macaron
 
 # Direct content input
 /baoyu-xhs-images 今日星座运势
+
+# Non-interactive (skip all confirmations, for scheduled tasks)
+/baoyu-xhs-images posts/ai-future/article.md --yes
+/baoyu-xhs-images posts/ai-future/article.md --yes --preset knowledge-card
 ```
 
-**Styles** (visual aesthetics): `cute` (default), `fresh`, `warm`, `bold`, `minimal`, `retro`, `pop`, `notion`, `chalkboard`
+**Styles** (visual aesthetics): `cute` (default), `fresh`, `warm`, `bold`, `minimal`, `retro`, `pop`, `notion`, `chalkboard`, `study-notes`, `screen-print`, `sketch-notes`
+
+**Palettes** (optional color override): `macaron`, `warm`, `neon`
 
 **Style Previews**:
 
@@ -133,7 +161,7 @@ Xiaohongshu (RedNote) infographic series generator. Breaks down content into 1-1
 
 #### baoyu-infographic
 
-Generate professional infographics with 20 layout types and 17 visual styles. Analyzes content, recommends layout×style combinations, and generates publication-ready infographics.
+Generate professional infographics with 21 layout types and 21 visual styles. Analyzes content, recommends layout×style combinations, and generates publication-ready infographics.
 
 ```bash
 # Auto-recommend combinations based on content
@@ -148,8 +176,9 @@ Generate professional infographics with 20 layout types and 17 visual styles. An
 # Specify both
 /baoyu-infographic path/to/content.md --layout funnel --style corporate-memphis
 
-# With aspect ratio
+# With aspect ratio (named preset or custom W:H)
 /baoyu-infographic path/to/content.md --aspect portrait
+/baoyu-infographic path/to/content.md --aspect 3:4
 ```
 
 **Options**:
@@ -157,7 +186,7 @@ Generate professional infographics with 20 layout types and 17 visual styles. An
 |--------|-------------|
 | `--layout <name>` | Information layout (20 options) |
 | `--style <name>` | Visual style (17 options, default: craft-handmade) |
-| `--aspect <ratio>` | landscape (16:9), portrait (9:16), square (1:1) |
+| `--aspect <ratio>` | Named: landscape (16:9), portrait (9:16), square (1:1). Custom: any W:H ratio (e.g., 3:4, 4:3, 2.35:1) |
 | `--lang <code>` | Output language (en, zh, ja, etc.) |
 
 **Layouts** (information structure):
@@ -243,9 +272,46 @@ Generate professional infographics with 20 layout types and 17 visual styles. An
 | ![knolling](./screenshots/infographic-styles/knolling.webp) | ![lego-brick](./screenshots/infographic-styles/lego-brick.webp) | |
 | knolling | lego-brick | |
 
+#### baoyu-diagram
+
+Generate publication-ready SVG diagrams from source material — flowcharts, sequence/protocol diagrams, structural/architecture diagrams, and illustrative intuition diagrams. Analyzes input material to recommend diagram type(s) and splitting strategy, confirms the plan once, then generates all diagrams. Claude writes real SVG code directly following a cohesive design system. Output is self-contained `.svg` files with embedded styles and auto dark-mode.
+
+```bash
+# Topic string — skill analyzes and proposes a plan
+/baoyu-diagram "how JWT authentication works"
+/baoyu-diagram "Kubernetes architecture" --type structural
+/baoyu-diagram "OAuth 2.0 flow"          --type sequence
+
+# File path — skill reads, analyzes, and proposes a plan
+/baoyu-diagram path/to/article.md
+
+# Language and output path
+/baoyu-diagram "微服务架构" --lang zh
+/baoyu-diagram "build pipeline" --out docs/build-pipeline.svg
+```
+
+**Options**:
+| Option | Description |
+|--------|-------------|
+| `--type <name>` | `flowchart`, `sequence`, `structural`, `illustrative`, `class`, `auto` (default). Skips type recommendation. |
+| `--lang <code>` | Output language (en, zh, ja, ...) |
+| `--out <path>` | Output file path. Generates exactly one diagram focused on the most important aspect. |
+
+**Diagram types**:
+
+| Type | Reader need | Verbs that trigger it |
+|------|-------------|------------------------|
+| `flowchart` | Walk me through the steps in order | walk through, steps, process, lifecycle, workflow, state machine |
+| `sequence` | Who talks to whom, in what order | protocol, handshake, auth flow, OAuth, TCP, request/response |
+| `structural` | Show me what's inside what, how it's organised | architecture, components, topology, layout, what's inside |
+| `illustrative` | Give me the intuition — draw the mechanism | how does X work, explain X, intuition for, why does X do Y |
+| `class` | What are the types and how are they related | class diagram, UML, inheritance, interface, schema |
+
+Not an image-generation skill — no LLM image model is called. Claude writes the SVG by hand with hand-computed layout math, so every diagram honors the design system. Embedded `<style>` block with `@media (prefers-color-scheme: dark)` means the same file renders correctly in both light and dark mode anywhere it's embedded.
+
 #### baoyu-cover-image
 
-Generate cover images for articles with 5 dimensions: Type × Palette × Rendering × Text × Mood. Combines 9 color palettes with 6 rendering styles for 54 unique combinations.
+Generate cover images for articles with 5 dimensions: Type × Palette × Rendering × Text × Mood. Combines 11 color palettes with 7 rendering styles for 77 unique combinations.
 
 ```bash
 # Auto-select all dimensions based on content
@@ -270,8 +336,8 @@ Generate cover images for articles with 5 dimensions: Type × Palette × Renderi
 
 **Five Dimensions**:
 - **Type**: `hero`, `conceptual`, `typography`, `metaphor`, `scene`, `minimal`
-- **Palette**: `warm`, `elegant`, `cool`, `dark`, `earth`, `vivid`, `pastel`, `mono`, `retro`
-- **Rendering**: `flat-vector`, `hand-drawn`, `painterly`, `digital`, `pixel`, `chalk`
+- **Palette**: `warm`, `elegant`, `cool`, `dark`, `earth`, `vivid`, `pastel`, `mono`, `retro`, `duotone`, `macaron`
+- **Rendering**: `flat-vector`, `hand-drawn`, `painterly`, `digital`, `pixel`, `chalk`, `screen-print`
 - **Text**: `none`, `title-only` (default), `title-subtitle`, `text-rich`
 - **Mood**: `subtle`, `balanced` (default), `bold`
 
@@ -449,20 +515,17 @@ Knowledge comic creator with flexible art style × tone combinations. Creates or
 
 #### baoyu-article-illustrator
 
-Smart article illustration skill with Type × Style two-dimension approach. Analyzes article structure, identifies positions requiring visual aids, and generates illustrations.
+Smart article illustration skill with Type × Style × Palette three-dimension approach. Analyzes article structure, identifies positions requiring visual aids, and generates illustrations.
 
 ```bash
 # Auto-select type and style based on content
 /baoyu-article-illustrator path/to/article.md
 
-# Specify type
-/baoyu-article-illustrator path/to/article.md --type infographic
-
-# Specify style
-/baoyu-article-illustrator path/to/article.md --style blueprint
-
-# Combine type and style
+# Specify type and style
 /baoyu-article-illustrator path/to/article.md --type flowchart --style notion
+
+# With palette override
+/baoyu-article-illustrator path/to/article.md --style vector-illustration --palette macaron
 ```
 
 **Types** (information structure):
@@ -476,7 +539,7 @@ Smart article illustration skill with Type × Style two-dimension approach. Anal
 | `framework` | Concept maps, relationship diagrams | Methodologies, architecture |
 | `timeline` | Chronological progression | History, project progress |
 
-**Styles** (visual aesthetics):
+**Styles** (rendering approach):
 
 | Style | Description | Best For |
 |-------|-------------|----------|
@@ -489,6 +552,14 @@ Smart article illustration skill with Type × Style two-dimension approach. Anal
 | `editorial` | Magazine-style infographic | Tech explainers, journalism |
 | `scientific` | Academic precise diagrams | Biology, chemistry, technical |
 
+**Palettes** (optional color override):
+
+| Palette | Description | Best For |
+|---------|-------------|----------|
+| `macaron` | Soft pastel blocks (blue, mint, lavender, peach) on warm cream | Educational, knowledge, tutorials |
+| `warm` | Warm earth tones on soft peach, no cool colors | Brand, product, lifestyle |
+| `neon` | Vibrant neon on dark purple | Gaming, retro, pop culture |
+
 **Style Previews**:
 
 | | | |
@@ -504,6 +575,8 @@ Smart article illustration skill with Type × Style two-dimension approach. Anal
 
 Post content and articles to X (Twitter). Supports regular posts with images and X Articles (long-form Markdown). Uses real Chrome with CDP to bypass anti-automation.
 
+Plain text input is treated as a regular post. Markdown files are treated as X Articles. Scripts fill content into the browser, and the user reviews and publishes manually.
+
 ```bash
 # Post with text
 /baoyu-post-to-x "Hello from Claude Code!"
@@ -558,32 +631,148 @@ To obtain credentials:
 
 **Browser Method** (no API setup needed): Requires Google Chrome. First run opens browser for QR code login (session preserved).
 
+**Multi-Account Support**: Manage multiple WeChat Official Accounts via `EXTEND.md`:
+
+```bash
+mkdir -p .baoyu-skills/baoyu-post-to-wechat
+```
+
+Create `.baoyu-skills/baoyu-post-to-wechat/EXTEND.md`:
+
+```yaml
+# Global settings (shared across all accounts)
+default_theme: default
+default_color: blue
+
+# Account list
+accounts:
+  - name: My Tech Blog
+    alias: tech-blog
+    default: false
+    default_publish_method: api
+    default_author: Author Name
+    need_open_comment: 1
+    only_fans_can_comment: 0
+    app_id: your_wechat_app_id
+    app_secret: your_wechat_app_secret
+  - name: AI Newsletter
+    alias: ai-news
+    default_publish_method: browser
+    default_author: AI Newsletter
+    need_open_comment: 1
+    only_fans_can_comment: 0
+```
+
+| Accounts configured | Behavior |
+|---------------------|----------|
+| No `accounts` block | Single-account mode (backward compatible) |
+| 1 account | Auto-select, no prompt |
+| 2+ accounts | Prompt to select, or use `--account <alias>` |
+| 1 account has `default: true` | Pre-selected as default |
+
+Each account gets an isolated Chrome profile for independent login sessions (browser method). API credentials can be set inline in EXTEND.md or via `.env` with alias-prefixed keys (e.g., `WECHAT_TECH_BLOG_APP_ID`).
+
+#### baoyu-post-to-weibo
+
+Post content to Weibo (微博). Supports regular posts with text, images, and videos, and headline articles (头条文章) with Markdown input. Uses real Chrome with CDP to bypass anti-automation.
+
+**Regular Posts** - Text + images/videos (max 18 files):
+
+```bash
+# Post with text
+/baoyu-post-to-weibo "Hello Weibo!"
+
+# Post with images
+/baoyu-post-to-weibo "Check this out" --image photo.png
+
+# Post with video
+/baoyu-post-to-weibo "Watch this" --video clip.mp4
+```
+
+**Headline Articles (头条文章)** - Long-form Markdown:
+
+```bash
+# Publish article
+/baoyu-post-to-weibo --article article.md
+
+# With cover image
+/baoyu-post-to-weibo --article article.md --cover cover.jpg
+```
+
+**Article Options**:
+| Option | Description |
+|--------|-------------|
+| `--cover <path>` | Cover image |
+| `--title <text>` | Override title (max 32 chars) |
+| `--summary <text>` | Override summary (max 44 chars) |
+
+**Note**: Scripts fill content into the browser. User reviews and publishes manually. First run requires manual Weibo login (session persists).
+
 ### AI Generation Skills
 
 AI-powered generation backends.
 
-#### baoyu-image-gen
+#### baoyu-imagine
 
-AI SDK-based image generation using official OpenAI, Google and DashScope (Aliyun Tongyi Wanxiang) APIs. Supports text-to-image, reference images, aspect ratios, and quality presets.
+AI SDK-based image generation using OpenAI GPT Image 2, Azure OpenAI, Google, OpenRouter, DashScope (Aliyun Tongyi Wanxiang), MiniMax, Jimeng (即梦), Seedream (豆包), and Replicate APIs. Supports text-to-image, reference images, aspect ratios, custom sizes, batch generation, and quality presets.
 
 ```bash
 # Basic generation (auto-detect provider)
-/baoyu-image-gen --prompt "A cute cat" --image cat.png
+/baoyu-imagine --prompt "A cute cat" --image cat.png
 
 # With aspect ratio
-/baoyu-image-gen --prompt "A landscape" --image landscape.png --ar 16:9
+/baoyu-imagine --prompt "A landscape" --image landscape.png --ar 16:9
 
 # High quality (2k)
-/baoyu-image-gen --prompt "A banner" --image banner.png --quality 2k
+/baoyu-imagine --prompt "A banner" --image banner.png --quality 2k
 
 # Specific provider
-/baoyu-image-gen --prompt "A cat" --image cat.png --provider openai
+/baoyu-imagine --prompt "A cat" --image cat.png --provider openai --model gpt-image-2
+
+# Azure OpenAI (model = deployment name)
+/baoyu-imagine --prompt "A cat" --image cat.png --provider azure --model gpt-image-2
+
+# OpenRouter
+/baoyu-imagine --prompt "A cat" --image cat.png --provider openrouter
+
+# OpenRouter with reference images
+/baoyu-imagine --prompt "Make it blue" --image out.png --provider openrouter --model google/gemini-3.1-flash-image-preview --ref source.png
 
 # DashScope (Aliyun Tongyi Wanxiang)
-/baoyu-image-gen --prompt "一只可爱的猫" --image cat.png --provider dashscope
+/baoyu-imagine --prompt "一只可爱的猫" --image cat.png --provider dashscope
 
-# With reference images (Google multimodal only)
-/baoyu-image-gen --prompt "Make it blue" --image out.png --ref source.png
+# DashScope with custom size
+/baoyu-imagine --prompt "为咖啡品牌设计一张 21:9 横幅海报，包含清晰中文标题" --image banner.png --provider dashscope --model qwen-image-2.0-pro --size 2048x872
+
+# Z.AI GLM-Image
+/baoyu-imagine --prompt "一张带清晰中文标题的科技海报" --image out.png --provider zai
+
+# MiniMax
+/baoyu-imagine --prompt "A fashion editorial portrait by a bright studio window" --image out.jpg --provider minimax
+
+# MiniMax with subject reference
+/baoyu-imagine --prompt "A girl stands by the library window, cinematic lighting" --image out.jpg --provider minimax --model image-01 --ref portrait.png --ar 16:9
+
+# Replicate (default: google/nano-banana-2)
+/baoyu-imagine --prompt "A cat" --image cat.png --provider replicate
+
+# Replicate Seedream 4.5
+/baoyu-imagine --prompt "A studio portrait" --image portrait.png --provider replicate --model bytedance/seedream-4.5 --ar 3:2
+
+# Replicate Wan 2.7 Image Pro
+/baoyu-imagine --prompt "A concept frame" --image frame.png --provider replicate --model wan-video/wan-2.7-image-pro --size 2048x1152
+
+# Jimeng (即梦)
+/baoyu-imagine --prompt "一只可爱的猫" --image cat.png --provider jimeng
+
+# Seedream (豆包)
+/baoyu-imagine --prompt "一只可爱的猫" --image cat.png --provider seedream
+
+# With reference images (Google, OpenAI, Azure OpenAI, OpenRouter, Replicate, MiniMax, or Seedream 5.0/4.5/4.0)
+/baoyu-imagine --prompt "Make it blue" --image out.png --ref source.png
+
+# Batch mode
+/baoyu-imagine --batchfile batch.json --jobs 4 --json
 ```
 
 **Options**:
@@ -592,30 +781,85 @@ AI SDK-based image generation using official OpenAI, Google and DashScope (Aliyu
 | `--prompt`, `-p` | Prompt text |
 | `--promptfiles` | Read prompt from files (concatenated) |
 | `--image` | Output image path (required) |
-| `--provider` | `google`, `openai` or `dashscope` (default: google) |
-| `--model`, `-m` | Model ID |
+| `--batchfile` | JSON batch file for multi-image generation |
+| `--jobs` | Worker count for batch mode |
+| `--provider` | `google`, `openai`, `azure`, `openrouter`, `dashscope`, `zai`, `minimax`, `jimeng`, `seedream`, or `replicate` |
+| `--model`, `-m` | Model ID or deployment name. Azure uses deployment name; OpenRouter uses full model IDs; Z.AI uses `glm-image`; MiniMax uses `image-01` / `image-01-live` |
 | `--ar` | Aspect ratio (e.g., `16:9`, `1:1`, `4:3`) |
-| `--size` | Size (e.g., `1024x1024`) |
-| `--quality` | `normal` or `2k` (default: normal) |
-| `--ref` | Reference images (Google multimodal only) |
+| `--size` | Size (e.g., `1024x1024`; `gpt-image-2` accepts valid custom sizes up to 3840px max edge) |
+| `--quality` | `normal` or `2k` (default: `2k`) |
+| `--imageSize` | `1K`, `2K`, or `4K` for Google/OpenRouter |
+| `--imageApiDialect` | `openai-native` or `ratio-metadata` for OpenAI-compatible gateways |
+| `--ref` | Reference images (Google, OpenAI, Azure OpenAI, OpenRouter, Replicate supported families, MiniMax, or Seedream 5.0/4.5/4.0) |
+| `--n` | Number of images per request (`replicate` currently requires `--n 1`) |
+| `--json` | JSON output |
 
 **Environment Variables** (see [Environment Configuration](#environment-configuration) for setup):
 | Variable | Description | Default |
 |----------|-------------|---------|
 | `OPENAI_API_KEY` | OpenAI API key | - |
+| `AZURE_OPENAI_API_KEY` | Azure OpenAI API key | - |
+| `OPENROUTER_API_KEY` | OpenRouter API key | - |
 | `GOOGLE_API_KEY` | Google API key | - |
+| `GEMINI_API_KEY` | Alias for `GOOGLE_API_KEY` | - |
 | `DASHSCOPE_API_KEY` | DashScope API key (Aliyun) | - |
-| `OPENAI_IMAGE_MODEL` | OpenAI model | `gpt-image-1.5` |
+| `ZAI_API_KEY` | Z.AI API key | - |
+| `BIGMODEL_API_KEY` | Backward-compatible alias for Z.AI API key | - |
+| `MINIMAX_API_KEY` | MiniMax API key | - |
+| `REPLICATE_API_TOKEN` | Replicate API token | - |
+| `JIMENG_ACCESS_KEY_ID` | Jimeng Volcengine access key | - |
+| `JIMENG_SECRET_ACCESS_KEY` | Jimeng Volcengine secret key | - |
+| `ARK_API_KEY` | Seedream Volcengine ARK API key | - |
+| `OPENAI_IMAGE_MODEL` | OpenAI model | `gpt-image-2` |
+| `AZURE_OPENAI_DEPLOYMENT` | Azure default deployment name | - |
+| `AZURE_OPENAI_IMAGE_MODEL` | Backward-compatible Azure deployment/model alias | `gpt-image-2` |
+| `OPENROUTER_IMAGE_MODEL` | OpenRouter model | `google/gemini-3.1-flash-image-preview` |
 | `GOOGLE_IMAGE_MODEL` | Google model | `gemini-3-pro-image-preview` |
-| `DASHSCOPE_IMAGE_MODEL` | DashScope model | `z-image-turbo` |
+| `DASHSCOPE_IMAGE_MODEL` | DashScope model | `qwen-image-2.0-pro` |
+| `ZAI_IMAGE_MODEL` | Z.AI model | `glm-image` |
+| `BIGMODEL_IMAGE_MODEL` | Backward-compatible alias for Z.AI model | `glm-image` |
+| `MINIMAX_IMAGE_MODEL` | MiniMax model | `image-01` |
+| `REPLICATE_IMAGE_MODEL` | Replicate model | `google/nano-banana-2` |
+| `JIMENG_IMAGE_MODEL` | Jimeng model | `jimeng_t2i_v40` |
+| `SEEDREAM_IMAGE_MODEL` | Seedream model | `doubao-seedream-5-0-260128` |
 | `OPENAI_BASE_URL` | Custom OpenAI endpoint | - |
+| `OPENAI_IMAGE_API_DIALECT` | OpenAI-compatible image API dialect (`openai-native` or `ratio-metadata`) | `openai-native` |
+| `OPENAI_IMAGE_USE_CHAT` | Use `/chat/completions` for OpenAI image generation | `false` |
+| `AZURE_OPENAI_BASE_URL` | Azure resource or deployment endpoint | - |
+| `AZURE_API_VERSION` | Azure image API version | `2025-04-01-preview` |
+| `OPENROUTER_BASE_URL` | Custom OpenRouter endpoint | `https://openrouter.ai/api/v1` |
+| `OPENROUTER_HTTP_REFERER` | Optional app/site URL for OpenRouter attribution | - |
+| `OPENROUTER_TITLE` | Optional app name for OpenRouter attribution | - |
 | `GOOGLE_BASE_URL` | Custom Google endpoint | - |
 | `DASHSCOPE_BASE_URL` | Custom DashScope endpoint | - |
+| `ZAI_BASE_URL` | Custom Z.AI endpoint | `https://api.z.ai/api/paas/v4` |
+| `BIGMODEL_BASE_URL` | Backward-compatible alias for Z.AI endpoint | - |
+| `MINIMAX_BASE_URL` | Custom MiniMax endpoint | `https://api.minimax.io` |
+| `REPLICATE_BASE_URL` | Custom Replicate endpoint | - |
+| `JIMENG_BASE_URL` | Custom Jimeng endpoint | `https://visual.volcengineapi.com` |
+| `JIMENG_REGION` | Jimeng region | `cn-north-1` |
+| `SEEDREAM_BASE_URL` | Custom Seedream endpoint | `https://ark.cn-beijing.volces.com/api/v3` |
+| `BAOYU_IMAGE_GEN_MAX_WORKERS` | Override batch worker cap | `10` |
+| `BAOYU_IMAGE_GEN_<PROVIDER>_CONCURRENCY` | Override provider concurrency | provider-specific |
+| `BAOYU_IMAGE_GEN_<PROVIDER>_START_INTERVAL_MS` | Override provider request start gap | provider-specific |
+
+**Provider Notes**:
+- Azure OpenAI: `--model` means Azure deployment name, not the underlying model family.
+- DashScope: `qwen-image-2.0-pro` is the recommended default for custom `--size`, `21:9`, and strong Chinese/English text rendering.
+- Z.AI: `glm-image` is recommended for posters, diagrams, and text-heavy Chinese/English images. Reference images are not supported.
+- MiniMax: `image-01` supports documented custom `width` / `height`; `image-01-live` is lower latency and works best with `--ar`.
+- MiniMax reference images are sent as `subject_reference`; the current API is specialized toward character / portrait consistency.
+- Jimeng does not support reference images.
+- Seedream reference images are supported by Seedream 5.0 / 4.5 / 4.0, not Seedream 3.0.
+- Replicate defaults to `google/nano-banana-2`. `baoyu-imagine` only enables Replicate advanced options for `google/nano-banana*`, `bytedance/seedream-4.5`, `bytedance/seedream-5-lite`, `wan-video/wan-2.7-image`, and `wan-video/wan-2.7-image-pro`.
+- Replicate currently saves exactly one output image per request. `--n > 1` is blocked locally instead of silently dropping extra results.
+- Replicate model behavior is family-specific: nano-banana uses `--quality` / `--ar`, Seedream uses validated `--size` / `--ar`, and Wan uses validated `--size` (with `--ar` converted locally to a concrete size).
 
 **Provider Auto-Selection**:
-1. If `--provider` specified → use it
-2. If only one API key available → use that provider
-3. If multiple available → default to Google
+1. If `--provider` is specified → use it
+2. If `--ref` is provided and no provider is specified → try Google, then OpenAI, Azure, OpenRouter, Replicate, Seedream, and finally MiniMax
+3. If only one API key is available → use that provider
+4. If multiple providers are available → default to Google, then OpenAI, Azure, OpenRouter, DashScope, Z.AI, MiniMax, Replicate, Jimeng, Seedream
 
 #### baoyu-danger-gemini-web
 
@@ -639,9 +883,43 @@ Interacts with Gemini Web to generate text and images.
 
 Utility tools for content processing.
 
+#### baoyu-youtube-transcript
+
+Download YouTube video transcripts/subtitles and cover images. Supports multiple languages, translation, chapters, and speaker identification. Caches raw data for fast re-formatting.
+
+```bash
+# Default: markdown with timestamps
+/baoyu-youtube-transcript https://www.youtube.com/watch?v=VIDEO_ID
+
+# Specify languages (priority order)
+/baoyu-youtube-transcript https://youtu.be/VIDEO_ID --languages zh,en,ja
+
+# With chapters and speaker identification
+/baoyu-youtube-transcript https://youtu.be/VIDEO_ID --chapters --speakers
+
+# SRT subtitle format
+/baoyu-youtube-transcript https://youtu.be/VIDEO_ID --format srt
+
+# List available transcripts
+/baoyu-youtube-transcript https://youtu.be/VIDEO_ID --list
+```
+
+**Options**:
+| Option | Description | Default |
+|--------|-------------|---------|
+| `<url-or-id>` | YouTube URL or video ID | Required |
+| `--languages <codes>` | Language codes, comma-separated | `en` |
+| `--format <fmt>` | Output format: `text`, `srt` | `text` |
+| `--translate <code>` | Translate to specified language | |
+| `--chapters` | Chapter segmentation from video description | |
+| `--speakers` | Speaker identification (requires AI post-processing) | |
+| `--no-timestamps` | Disable timestamps | |
+| `--list` | List available transcripts | |
+| `--refresh` | Force re-fetch, ignore cache | |
+
 #### baoyu-url-to-markdown
 
-Fetch any URL via Chrome CDP and convert to clean markdown. Supports two capture modes for different scenarios.
+Fetch any URL via Chrome CDP and convert to clean markdown. Saves rendered HTML snapshot alongside the markdown, and automatically falls back to a legacy extractor when Defuddle fails.
 
 ```bash
 # Auto mode (default) - capture when page loads
@@ -739,12 +1017,107 @@ Format plain text or markdown files with proper frontmatter, titles, summaries,
 | Code/commands | `` `inline` `` or ` ```block``` ` |
 | Quotes | `>` blockquote |
 
+#### baoyu-markdown-to-html
+
+Convert markdown files into styled HTML with WeChat-compatible themes, syntax highlighting, and optional bottom citations for external links.
+
+```bash
+# Basic conversion
+/baoyu-markdown-to-html article.md
+
+# Theme + color
+/baoyu-markdown-to-html article.md --theme grace --color red
+
+# Convert ordinary external links to bottom citations
+/baoyu-markdown-to-html article.md --cite
+```
+
+#### baoyu-translate
+
+Translate articles and documents between languages with three modes: quick (direct), normal (analysis-informed), and refined (full publication-quality workflow with review and polish).
+
+```bash
+# Normal mode (default) - analyze then translate
+/translate article.md --to zh-CN
+
+# Quick mode - direct translation
+/translate article.md --mode quick --to ja
+
+# Refined mode - full workflow with review and polish
+/translate article.md --mode refined --to zh-CN
+
+# Translate a URL
+/translate https://example.com/article --to zh-CN
+
+# Specify audience
+/translate article.md --to zh-CN --audience technical
+
+# Specify style
+/translate article.md --to zh-CN --style humorous
+
+# With additional glossary
+/translate article.md --to zh-CN --glossary my-terms.md
+```
+
+**Options**:
+| Option | Description |
+|--------|-------------|
+| `<source>` | File path, URL, or inline text |
+| `--mode <mode>` | `quick`, `normal` (default), `refined` |
+| `--from <lang>` | Source language (auto-detect if omitted) |
+| `--to <lang>` | Target language (default: `zh-CN`) |
+| `--audience <type>` | Target reader profile (default: `general`) |
+| `--style <style>` | Translation style (default: `storytelling`) |
+| `--glossary <file>` | Additional glossary file |
+
+**Modes**:
+| Mode | Steps | Use Case |
+|------|-------|----------|
+| Quick | Translate | Short texts, informal content |
+| Normal | Analyze → Translate | Articles, blog posts |
+| Refined | Analyze → Translate → Review → Polish | Publication-quality documents |
+
+After normal mode completes, you can reply "继续润色" or "refine" to continue with review and polish steps.
+
+**Audience Presets**:
+| Value | Description |
+|-------|-------------|
+| `general` | General readers (default) — plain language, more translator's notes |
+| `technical` | Developers / engineers — less annotation on common tech terms |
+| `academic` | Researchers / scholars — formal register, precise terminology |
+| `business` | Business professionals — business-friendly tone |
+
+Custom audience descriptions are also accepted, e.g., `--audience "AI-interested general readers"`.
+
+**Style Presets**:
+| Value | Description |
+|-------|-------------|
+| `storytelling` | Engaging narrative flow (default) — smooth transitions, vivid phrasing |
+| `formal` | Professional, structured — neutral tone, no colloquialisms |
+| `technical` | Precise, documentation-style — concise, terminology-heavy |
+| `literal` | Close to original structure — minimal restructuring |
+| `academic` | Scholarly, rigorous — formal register, complex clauses OK |
+| `business` | Concise, results-focused — action-oriented, executive-friendly |
+| `humorous` | Preserves and adapts humor — witty, recreates comedic effect |
+| `conversational` | Casual, spoken-like — friendly, as if explaining to a friend |
+| `elegant` | Literary, polished prose — aesthetically refined, carefully crafted |
+
+Custom style descriptions are also accepted, e.g., `--style "poetic and lyrical"`.
+
+**Features**:
+- Custom glossaries via EXTEND.md with built-in EN→ZH glossary
+- Audience-aware translation with adjustable annotation depth
+- Automatic chunking for long documents (4000+ words) with parallel subagent translation
+- Figurative language interpreted by meaning, not word-for-word
+- Translator's notes for cultural/domain-specific references
+- Output directory with all intermediate files preserved
+
 ## Environment Configuration
 
 Some skills require API keys or custom configuration. Environment variables can be set in `.env` files:
 
 **Load Priority** (higher priority overrides lower):
-1. CLI environment variables (e.g., `OPENAI_API_KEY=xxx /baoyu-image-gen ...`)
+1. CLI environment variables (e.g., `OPENAI_API_KEY=xxx /baoyu-imagine ...`)
 2. `process.env` (system environment)
 3. `<cwd>/.baoyu-skills/.env` (project-level)
 4. `~/.baoyu-skills/.env` (user-level)
@@ -759,8 +1132,22 @@ mkdir -p ~/.baoyu-skills
 cat > ~/.baoyu-skills/.env << 'EOF'
 # OpenAI
 OPENAI_API_KEY=sk-xxx
-OPENAI_IMAGE_MODEL=gpt-image-1.5
+OPENAI_IMAGE_MODEL=gpt-image-2
 # OPENAI_BASE_URL=https://api.openai.com/v1
+# OPENAI_IMAGE_USE_CHAT=false
+
+# Azure OpenAI
+AZURE_OPENAI_API_KEY=xxx
+AZURE_OPENAI_BASE_URL=https://your-resource.openai.azure.com
+AZURE_OPENAI_DEPLOYMENT=gpt-image-2
+# AZURE_API_VERSION=2025-04-01-preview
+
+# OpenRouter
+OPENROUTER_API_KEY=sk-or-xxx
+OPENROUTER_IMAGE_MODEL=google/gemini-3.1-flash-image-preview
+# OPENROUTER_BASE_URL=https://openrouter.ai/api/v1
+# OPENROUTER_HTTP_REFERER=https://your-app.example.com
+# OPENROUTER_TITLE=Your App Name
 
 # Google
 GOOGLE_API_KEY=xxx
@@ -769,8 +1156,35 @@ GOOGLE_IMAGE_MODEL=gemini-3-pro-image-preview
 
 # DashScope (Aliyun Tongyi Wanxiang)
 DASHSCOPE_API_KEY=sk-xxx
-DASHSCOPE_IMAGE_MODEL=z-image-turbo
+DASHSCOPE_IMAGE_MODEL=qwen-image-2.0-pro
 # DASHSCOPE_BASE_URL=https://dashscope.aliyuncs.com/api/v1
+
+# Z.AI
+ZAI_API_KEY=xxx
+ZAI_IMAGE_MODEL=glm-image
+# ZAI_BASE_URL=https://api.z.ai/api/paas/v4
+
+# MiniMax
+MINIMAX_API_KEY=xxx
+MINIMAX_IMAGE_MODEL=image-01
+# MINIMAX_BASE_URL=https://api.minimax.io
+
+# Replicate
+REPLICATE_API_TOKEN=r8_xxx
+REPLICATE_IMAGE_MODEL=google/nano-banana-2
+# REPLICATE_BASE_URL=https://api.replicate.com
+
+# Jimeng (即梦)
+JIMENG_ACCESS_KEY_ID=xxx
+JIMENG_SECRET_ACCESS_KEY=xxx
+JIMENG_IMAGE_MODEL=jimeng_t2i_v40
+# JIMENG_BASE_URL=https://visual.volcengineapi.com
+# JIMENG_REGION=cn-north-1
+
+# Seedream (豆包)
+ARK_API_KEY=xxx
+SEEDREAM_IMAGE_MODEL=doubao-seedream-5-0-260128
+# SEEDREAM_BASE_URL=https://ark.cn-beijing.volces.com/api/v3
 EOF
 ```
 
@@ -842,6 +1256,20 @@ This skill uses a reverse-engineered X (Twitter) API.
 - First use requires consent acknowledgment
 - Authentication via environment variables or Chrome login
 
+## Credits
+
+This project was inspired by and builds upon the following open source projects:
+
+- [x-article-publisher-skill](https://github.com/wshuyi/x-article-publisher-skill) by [@wshuyi](https://github.com/wshuyi) — Inspiration for the X article publishing skill
+- [doocs/md](https://github.com/doocs/md) by [@doocs](https://github.com/doocs) — Core implementation logic for Markdown to HTML conversion
+- [High-density Infographic Prompt](https://waytoagi.feishu.cn/wiki/YG0zwalijihRREkgmPzcWRInnUg) by AJ@WaytoAGI — Inspiration for the infographic skill
+- [qiaomu-mondo-poster-design](https://github.com/joeseesun/qiaomu-mondo-poster-design) by [@joeseesun](https://github.com/joeseesun)（乔木） — Inspiration for the Mondo style
+- [architecture-diagram-generator](https://github.com/Cocoon-AI/architecture-diagram-generator) by [@Cocoon-AI](https://github.com/Cocoon-AI) — Inspiration for the diagram skill's design system
+
 ## License
 
 MIT
+
+## Star History
+
+[![Star History Chart](https://api.star-history.com/svg?repos=JimLiu/baoyu-skills&type=Date)](https://www.star-history.com/#JimLiu/baoyu-skills&Date)

README.zh.md

@@ -17,12 +17,33 @@
 npx skills add jimliu/baoyu-skills
 ```
 
+### 发布到 ClawHub / OpenClaw
+
+现在这个仓库支持把每个 `skills/baoyu-*` 目录作为独立 ClawHub skill 发布。
+
+```bash
+# 预览将要发布的变更
+./scripts/sync-clawhub.sh --dry-run
+
+# 发布 ./skills 下所有已变更的 skill
+./scripts/sync-clawhub.sh --all
+```
+
+ClawHub 按“单个 skill”安装，不是把整个 marketplace 一次性装进去。发布后，用户可以按需安装：
+
+```bash
+clawhub install baoyu-imagine
+clawhub install baoyu-markdown-to-html
+```
+
+根据 ClawHub 的 registry 规则，发布到 ClawHub 的 skill 会以 `MIT-0` 许可分发。
+
 ### 注册插件市场
 
 在 Claude Code 中运行：
 
 ```bash
-/plugin marketplace add jimliu/baoyu-skills
+/plugin marketplace add JimLiu/baoyu-skills
 ```
 
 ### 安装技能
@@ -31,16 +52,14 @@ npx skills add jimliu/baoyu-skills
 
 1. 选择 **Browse and install plugins**
 2. 选择 **baoyu-skills**
-3. 选择要安装的插件
+3. 选择 **baoyu-skills** 插件
 4. 选择 **Install now**
 
 **方式二：直接安装**
 
 ```bash
-# 安装指定插件
-/plugin install content-skills@baoyu-skills
-/plugin install ai-generation-skills@baoyu-skills
-/plugin install utility-skills@baoyu-skills
+# 安装 marketplace 中唯一的插件
+/plugin install baoyu-skills@baoyu-skills
 ```
 
 **方式三：告诉 Agent**
@@ -51,11 +70,11 @@ npx skills add jimliu/baoyu-skills
 
 ### 可用插件
 
-| 插件 | 说明 | 包含技能 |
+现在 marketplace 只暴露一个插件，这样每个 skill 只会注册一次。
+
+| 插件 | 说明 | 包含内容 |
 |------|------|----------|
-| **content-skills** | 内容生成和发布 | [xhs-images](#baoyu-xhs-images), [infographic](#baoyu-infographic), [cover-image](#baoyu-cover-image), [slide-deck](#baoyu-slide-deck), [comic](#baoyu-comic), [article-illustrator](#baoyu-article-illustrator), [post-to-x](#baoyu-post-to-x), [post-to-wechat](#baoyu-post-to-wechat) |
-| **ai-generation-skills** | AI 生成后端 | [image-gen](#baoyu-image-gen), [danger-gemini-web](#baoyu-danger-gemini-web) |
-| **utility-skills** | 内容处理工具 | [url-to-markdown](#baoyu-url-to-markdown), [danger-x-to-markdown](#baoyu-danger-x-to-markdown), [compress-image](#baoyu-compress-image), [format-markdown](#baoyu-format-markdown) |
+| **baoyu-skills** | 提供内容生成、AI 后端和日常效率工具技能 | 仓库中的全部 skills，仍按下方的内容技能、AI 生成技能、工具技能三个分类展示 |
 
 ## 更新技能
 
@@ -80,7 +99,7 @@ npx skills add jimliu/baoyu-skills
 
 #### baoyu-xhs-images
 
-小红书信息图系列生成器。将内容拆解为 1-10 张卡通风格信息图，支持 **风格 × 布局** 二维系统。
+小红书图片卡片系列生成器。将内容拆解为 1-10 张卡通风格图片卡片，支持 **风格 × 布局** 系统和可选配色覆盖。
 
 ```bash
 # 自动选择风格和布局
@@ -93,13 +112,22 @@ npx skills add jimliu/baoyu-skills
 /baoyu-xhs-images posts/ai-future/article.md --layout dense
 
 # 组合风格和布局
-/baoyu-xhs-images posts/ai-future/article.md --style tech --layout list
+/baoyu-xhs-images posts/ai-future/article.md --style notion --layout list
+
+# 覆盖配色
+/baoyu-xhs-images posts/ai-future/article.md --style notion --palette macaron
 
 # 直接输入内容
 /baoyu-xhs-images 今日星座运势
+
+# 非交互模式（跳过所有确认，适用于定时任务）
+/baoyu-xhs-images posts/ai-future/article.md --yes
+/baoyu-xhs-images posts/ai-future/article.md --yes --preset knowledge-card
 ```
 
-**风格**（视觉美学）：`cute`（默认）、`fresh`、`warm`、`bold`、`minimal`、`retro`、`pop`、`notion`、`chalkboard`
+**风格**（视觉美学）：`cute`（默认）、`fresh`、`warm`、`bold`、`minimal`、`retro`、`pop`、`notion`、`chalkboard`、`study-notes`、`screen-print`、`sketch-notes`
+
+**配色**（可选颜色覆盖）：`macaron`、`warm`、`neon`
 
 **风格预览**：
 
@@ -133,7 +161,7 @@ npx skills add jimliu/baoyu-skills
 
 #### baoyu-infographic
 
-专业信息图生成器，支持 20 种布局和 17 种视觉风格。分析内容后推荐布局×风格组合，生成可发布的信息图。
+专业信息图生成器，支持 21 种布局和 21 种视觉风格。分析内容后推荐布局×风格组合，生成可发布的信息图。
 
 ```bash
 # 根据内容自动推荐组合
@@ -148,8 +176,9 @@ npx skills add jimliu/baoyu-skills
 # 同时指定布局和风格
 /baoyu-infographic path/to/content.md --layout funnel --style corporate-memphis
 
-# 指定比例
+# 指定比例（预设名称或自定义 W:H）
 /baoyu-infographic path/to/content.md --aspect portrait
+/baoyu-infographic path/to/content.md --aspect 3:4
 ```
 
 **选项**：
@@ -157,7 +186,7 @@ npx skills add jimliu/baoyu-skills
 |------|------|
 | `--layout <name>` | 信息布局（20 种选项） |
 | `--style <name>` | 视觉风格（17 种选项，默认：craft-handmade） |
-| `--aspect <ratio>` | landscape (16:9)、portrait (9:16)、square (1:1) |
+| `--aspect <ratio>` | 预设：landscape (16:9)、portrait (9:16)、square (1:1)。自定义：任意 W:H 比例（如 3:4、4:3、2.35:1） |
 | `--lang <code>` | 输出语言（en、zh、ja 等） |
 
 **布局**（信息结构）：
@@ -243,9 +272,46 @@ npx skills add jimliu/baoyu-skills
 | ![knolling](./screenshots/infographic-styles/knolling.webp) | ![lego-brick](./screenshots/infographic-styles/lego-brick.webp) | |
 | knolling | lego-brick | |
 
+#### baoyu-diagram
+
+从源素材生成可直接发布的 SVG 图表 —— 包括流程图、时序/协议图、架构/结构图、示意图（直觉图解）。分析输入素材，推荐图表类型和拆分策略，一次确认后批量生成。Claude 直接输出符合统一设计规范的真实 SVG 代码，产物是自包含的 `.svg` 文件，内嵌样式并自动支持深色模式。
+
+```bash
+# 主题描述 —— 技能分析并提出方案
+/baoyu-diagram "JWT 认证流程是怎么工作的"
+/baoyu-diagram "Kubernetes 架构" --type structural
+/baoyu-diagram "OAuth 2.0 流程"  --type sequence
+
+# 文件路径 —— 技能读取、分析并提出方案
+/baoyu-diagram path/to/article.md
+
+# 语言和输出路径
+/baoyu-diagram "微服务架构" --lang zh
+/baoyu-diagram "build pipeline" --out docs/build-pipeline.svg
+```
+
+**参数**：
+| 参数 | 说明 |
+|------|------|
+| `--type <name>` | `flowchart`、`sequence`、`structural`、`illustrative`、`class`、`auto`（默认）。跳过类型推荐直接生成。 |
+| `--lang <code>` | 输出语言（en、zh、ja 等） |
+| `--out <path>` | 输出文件路径。生成聚焦于最重要内容的单张图表。 |
+
+**五种图表类型**：
+
+| 类型 | 适用场景 | 触发动词 |
+|------|----------|----------|
+| `flowchart` | 按顺序走一遍流程 | 流程、步骤、工作流、生命周期、状态机 |
+| `sequence` | 谁和谁通信、按什么顺序 | 协议、握手、认证流程、OAuth、TCP、请求/响应 |
+| `structural` | 展示什么包含什么、如何组织 | 架构、组件、拓扑、布局、什么在什么里面 |
+| `illustrative` | 建立直觉 —— 画出机制本身 | 怎么工作、原理、为什么、直观解释 |
+| `class` | 类型是什么、它们如何关联 | 类图、UML、继承、接口、数据模型 |
+
+本技能不调用任何图像生成模型 —— Claude 通过手算坐标直接写 SVG 代码，确保每个图表都遵守设计规范。内嵌的 `<style>` 块包含 `@media (prefers-color-scheme: dark)`，同一个文件在浅色和深色模式下均正确渲染，可嵌入到任意支持 SVG 的宿主环境中。
+
 #### baoyu-cover-image
 
-为文章生成封面图，支持五维定制系统：类型 × 配色 × 渲染 × 文字 × 氛围。9 种配色方案与 6 种渲染风格组合，提供 54 种独特效果。
+为文章生成封面图，支持五维定制系统：类型 × 配色 × 渲染 × 文字 × 氛围。11 种配色方案与 7 种渲染风格组合，提供 77 种独特效果。
 
 ```bash
 # 根据内容自动选择所有维度
@@ -270,8 +336,8 @@ npx skills add jimliu/baoyu-skills
 
 **五个维度**：
 - **类型 (Type)**：`hero`、`conceptual`、`typography`、`metaphor`、`scene`、`minimal`
-- **配色 (Palette)**：`warm`、`elegant`、`cool`、`dark`、`earth`、`vivid`、`pastel`、`mono`、`retro`
-- **渲染 (Rendering)**：`flat-vector`、`hand-drawn`、`painterly`、`digital`、`pixel`、`chalk`
+- **配色 (Palette)**：`warm`、`elegant`、`cool`、`dark`、`earth`、`vivid`、`pastel`、`mono`、`retro`、`duotone`、`macaron`
+- **渲染 (Rendering)**：`flat-vector`、`hand-drawn`、`painterly`、`digital`、`pixel`、`chalk`、`screen-print`
 - **文字 (Text)**：`none`、`title-only`（默认）、`title-subtitle`、`text-rich`
 - **氛围 (Mood)**：`subtle`、`balanced`（默认）、`bold`
 
@@ -449,20 +515,17 @@ npx skills add jimliu/baoyu-skills
 
 #### baoyu-article-illustrator
 
-智能文章插图技能，采用类型 × 风格二维系统。分析文章结构，识别需要视觉辅助的位置，生成插图。
+智能文章插图技能，采用类型 × 风格 × 色板三维系统。分析文章结构，识别需要视觉辅助的位置，生成插图。
 
 ```bash
 # 根据内容自动选择类型和风格
 /baoyu-article-illustrator path/to/article.md
 
-# 指定类型
-/baoyu-article-illustrator path/to/article.md --type infographic
-
-# 指定风格
-/baoyu-article-illustrator path/to/article.md --style blueprint
-
 # 组合类型和风格
 /baoyu-article-illustrator path/to/article.md --type flowchart --style notion
+
+# 使用色板覆盖
+/baoyu-article-illustrator path/to/article.md --style vector-illustration --palette macaron
 ```
 
 **类型**（信息结构）：
@@ -476,7 +539,7 @@ npx skills add jimliu/baoyu-skills
 | `framework` | 概念图、关系图 | 方法论、架构 |
 | `timeline` | 时间线进展 | 历史、项目进度 |
 
-**风格**（视觉美学）：
+**风格**（渲染手法）：
 
 | 风格 | 描述 | 适用场景 |
 |------|------|----------|
@@ -489,6 +552,14 @@ npx skills add jimliu/baoyu-skills
 | `editorial` | 杂志风格信息图 | 科技解说、新闻 |
 | `scientific` | 学术精确图表 | 生物、化学、技术 |
 
+**色板**（可选配色覆盖）：
+
+| 色板 | 描述 | 适用场景 |
+|------|------|----------|
+| `macaron` | 马卡龙柔和色块（浅蓝、浅绿、浅紫、浅橙）暖白底 | 教育、知识分享、教程 |
+| `warm` | 暖色系（橙、赭石、金）无冷色 | 品牌、产品、生活方式 |
+| `neon` | 霓虹色（粉、青、黄）深色底 | 游戏、复古、潮流 |
+
 **风格预览**：
 
 | | | |
@@ -504,6 +575,8 @@ npx skills add jimliu/baoyu-skills
 
 发布内容和文章到 X (Twitter)。支持带图片的普通帖子和 X 文章（长篇 Markdown）。使用真实 Chrome + CDP 绕过反自动化检测。
 
+纯文本输入默认按普通帖子处理，Markdown 文件默认按 X 文章处理。脚本会将内容填入浏览器，用户需手动检查并发布。
+
 ```bash
 # 发布文字
 /baoyu-post-to-x "Hello from Claude Code!"
@@ -558,32 +631,148 @@ WECHAT_APP_SECRET=你的AppSecret
 
 **浏览器方式**（无需 API 配置）：需已安装 Google Chrome，首次运行需扫码登录（登录状态会保存）
 
+**多账号支持**：通过 `EXTEND.md` 管理多个微信公众号：
+
+```bash
+mkdir -p .baoyu-skills/baoyu-post-to-wechat
+```
+
+创建 `.baoyu-skills/baoyu-post-to-wechat/EXTEND.md`：
+
+```yaml
+# 全局设置（所有账号共享）
+default_theme: default
+default_color: blue
+
+# 账号列表
+accounts:
+  - name: 宝玉的技术分享
+    alias: baoyu
+    default: false
+    default_publish_method: api
+    default_author: 宝玉
+    need_open_comment: 1
+    only_fans_can_comment: 0
+    app_id: 你的微信AppID
+    app_secret: 你的微信AppSecret
+  - name: AI 工具集
+    alias: ai-tools
+    default_publish_method: browser
+    default_author: AI 工具集
+    need_open_comment: 1
+    only_fans_can_comment: 0
+```
+
+| 账号配置情况 | 行为 |
+|-------------|------|
+| 无 `accounts` 块 | 单账号模式（向后兼容） |
+| 1 个账号 | 自动选择，无需提示 |
+| 2+ 个账号 | 提示选择，或使用 `--account <别名>` |
+| 某账号设置 `default: true` | 预选为默认账号 |
+
+每个账号拥有独立的 Chrome 配置目录，保证浏览器方式下的登录会话互不干扰。API 凭证可在 EXTEND.md 中直接配置，也可通过 `.env` 文件使用别名前缀的环境变量（如 `WECHAT_BAOYU_APP_ID`）。
+
+#### baoyu-post-to-weibo
+
+发布内容到微博。支持文字、图片、视频发布和头条文章（长篇 Markdown）。使用真实 Chrome + CDP 绕过反自动化检测。
+
+**普通微博** - 文字 + 图片/视频（最多 18 个文件）：
+
+```bash
+# 发布文字
+/baoyu-post-to-weibo "Hello Weibo!"
+
+# 发布带图片
+/baoyu-post-to-weibo "看看这个" --image photo.png
+
+# 发布带视频
+/baoyu-post-to-weibo "看这个" --video clip.mp4
+```
+
+**头条文章** - 长篇 Markdown 文章：
+
+```bash
+# 发布文章
+/baoyu-post-to-weibo --article article.md
+
+# 带封面图
+/baoyu-post-to-weibo --article article.md --cover cover.jpg
+```
+
+**文章选项**：
+| 选项 | 说明 |
+|------|------|
+| `--cover <path>` | 封面图 |
+| `--title <text>` | 覆盖标题（最多 32 字） |
+| `--summary <text>` | 覆盖摘要（最多 44 字） |
+
+**说明**：脚本会将内容填入浏览器，用户需手动检查并发布。首次运行需手动登录微博（登录状态会保存）。
+
 ### AI 生成技能 (AI Generation Skills)
 
 AI 驱动的生成后端。
 
-#### baoyu-image-gen
+#### baoyu-imagine
 
-基于 AI SDK 的图像生成，使用官方 OpenAI、Google 和 DashScope（阿里通义万相）API。支持文生图、参考图、宽高比和质量预设。
+基于 AI SDK 的图像生成，支持 OpenAI GPT Image 2、Azure OpenAI、Google、OpenRouter、DashScope（阿里通义万相）、MiniMax、即梦（Jimeng）、豆包（Seedream）和 Replicate API。支持文生图、参考图、宽高比、自定义尺寸、批量生成和质量预设。
 
 ```bash
 # 基础生成（自动检测服务商）
-/baoyu-image-gen --prompt "一只可爱的猫" --image cat.png
+/baoyu-imagine --prompt "一只可爱的猫" --image cat.png
 
 # 指定宽高比
-/baoyu-image-gen --prompt "风景图" --image landscape.png --ar 16:9
+/baoyu-imagine --prompt "风景图" --image landscape.png --ar 16:9
 
 # 高质量（2k 分辨率）
-/baoyu-image-gen --prompt "横幅图" --image banner.png --quality 2k
+/baoyu-imagine --prompt "横幅图" --image banner.png --quality 2k
 
 # 指定服务商
-/baoyu-image-gen --prompt "一只猫" --image cat.png --provider openai
+/baoyu-imagine --prompt "一只猫" --image cat.png --provider openai --model gpt-image-2
+
+# Azure OpenAI（model 为部署名称）
+/baoyu-imagine --prompt "一只猫" --image cat.png --provider azure --model gpt-image-2
+
+# OpenRouter
+/baoyu-imagine --prompt "一只猫" --image cat.png --provider openrouter
+
+# OpenRouter + 参考图
+/baoyu-imagine --prompt "把它变成蓝色" --image out.png --provider openrouter --model google/gemini-3.1-flash-image-preview --ref source.png
 
 # DashScope（阿里通义万相）
-/baoyu-image-gen --prompt "一只可爱的猫" --image cat.png --provider dashscope
+/baoyu-imagine --prompt "一只可爱的猫" --image cat.png --provider dashscope
 
-# 带参考图（仅 Google 多模态支持）
-/baoyu-image-gen --prompt "把它变成蓝色" --image out.png --ref source.png
+# DashScope 自定义尺寸
+/baoyu-imagine --prompt "为咖啡品牌设计一张 21:9 横幅海报，包含清晰中文标题" --image banner.png --provider dashscope --model qwen-image-2.0-pro --size 2048x872
+
+# Z.AI GLM-Image
+/baoyu-imagine --prompt "一张带清晰中文标题的科技海报" --image out.png --provider zai
+
+# MiniMax
+/baoyu-imagine --prompt "A fashion editorial portrait by a bright studio window" --image out.jpg --provider minimax
+
+# MiniMax + 角色参考图
+/baoyu-imagine --prompt "A girl stands by the library window, cinematic lighting" --image out.jpg --provider minimax --model image-01 --ref portrait.png --ar 16:9
+
+# Replicate（默认：google/nano-banana-2）
+/baoyu-imagine --prompt "一只猫" --image cat.png --provider replicate
+
+# Replicate Seedream 4.5
+/baoyu-imagine --prompt "一张影棚人像" --image portrait.png --provider replicate --model bytedance/seedream-4.5 --ar 3:2
+
+# Replicate Wan 2.7 Image Pro
+/baoyu-imagine --prompt "一张概念分镜" --image frame.png --provider replicate --model wan-video/wan-2.7-image-pro --size 2048x1152
+
+# 即梦（Jimeng）
+/baoyu-imagine --prompt "一只可爱的猫" --image cat.png --provider jimeng
+
+# 豆包（Seedream）
+/baoyu-imagine --prompt "一只可爱的猫" --image cat.png --provider seedream
+
+# 带参考图（Google、OpenAI、Azure OpenAI、OpenRouter、Replicate、MiniMax 或 Seedream 5.0/4.5/4.0）
+/baoyu-imagine --prompt "把它变成蓝色" --image out.png --ref source.png
+
+# 批量模式
+/baoyu-imagine --batchfile batch.json --jobs 4 --json
 ```
 
 **选项**：
@@ -592,30 +781,85 @@ AI 驱动的生成后端。
 | `--prompt`, `-p` | 提示词文本 |
 | `--promptfiles` | 从文件读取提示词（多文件拼接） |
 | `--image` | 输出图片路径（必需） |
-| `--provider` | `google`、`openai` 或 `dashscope`（默认：google） |
-| `--model`, `-m` | 模型 ID |
+| `--batchfile` | 多图批量生成的 JSON 文件 |
+| `--jobs` | 批量模式的并发 worker 数 |
+| `--provider` | `google`、`openai`、`azure`、`openrouter`、`dashscope`、`zai`、`minimax`、`jimeng`、`seedream` 或 `replicate` |
+| `--model`, `-m` | 模型 ID 或部署名。Azure 使用部署名；OpenRouter 使用完整模型 ID；Z.AI 使用 `glm-image`；MiniMax 使用 `image-01` / `image-01-live` |
 | `--ar` | 宽高比（如 `16:9`、`1:1`、`4:3`） |
-| `--size` | 尺寸（如 `1024x1024`） |
-| `--quality` | `normal` 或 `2k`（默认：normal） |
-| `--ref` | 参考图片（仅 Google 多模态支持） |
+| `--size` | 尺寸（如 `1024x1024`；`gpt-image-2` 支持最长边不超过 3840px 的有效自定义尺寸） |
+| `--quality` | `normal` 或 `2k`（默认：`2k`） |
+| `--imageSize` | Google/OpenRouter 使用的 `1K`、`2K`、`4K` |
+| `--imageApiDialect` | OpenAI 兼容网关的图像 API 方言（`openai-native` 或 `ratio-metadata`） |
+| `--ref` | 参考图片（Google、OpenAI、Azure OpenAI、OpenRouter、Replicate 支持的模型家族、MiniMax 或 Seedream 5.0/4.5/4.0） |
+| `--n` | 单次请求生成图片数量（`replicate` 当前只支持 `--n 1`） |
+| `--json` | 输出 JSON 结果 |
 
 **环境变量**（配置方法见[环境配置](#环境配置)）：
 | 变量 | 说明 | 默认值 |
 |------|------|--------|
 | `OPENAI_API_KEY` | OpenAI API 密钥 | - |
+| `AZURE_OPENAI_API_KEY` | Azure OpenAI API 密钥 | - |
+| `OPENROUTER_API_KEY` | OpenRouter API 密钥 | - |
 | `GOOGLE_API_KEY` | Google API 密钥 | - |
+| `GEMINI_API_KEY` | `GOOGLE_API_KEY` 的别名 | - |
 | `DASHSCOPE_API_KEY` | DashScope API 密钥（阿里云） | - |
-| `OPENAI_IMAGE_MODEL` | OpenAI 模型 | `gpt-image-1.5` |
+| `ZAI_API_KEY` | Z.AI API 密钥 | - |
+| `BIGMODEL_API_KEY` | Z.AI API 密钥向后兼容别名 | - |
+| `MINIMAX_API_KEY` | MiniMax API 密钥 | - |
+| `REPLICATE_API_TOKEN` | Replicate API Token | - |
+| `JIMENG_ACCESS_KEY_ID` | 即梦火山引擎 Access Key | - |
+| `JIMENG_SECRET_ACCESS_KEY` | 即梦火山引擎 Secret Key | - |
+| `ARK_API_KEY` | 豆包火山引擎 ARK API 密钥 | - |
+| `OPENAI_IMAGE_MODEL` | OpenAI 模型 | `gpt-image-2` |
+| `AZURE_OPENAI_DEPLOYMENT` | Azure 默认部署名 | - |
+| `AZURE_OPENAI_IMAGE_MODEL` | 兼容旧配置的 Azure 部署/模型别名 | `gpt-image-2` |
+| `OPENROUTER_IMAGE_MODEL` | OpenRouter 模型 | `google/gemini-3.1-flash-image-preview` |
 | `GOOGLE_IMAGE_MODEL` | Google 模型 | `gemini-3-pro-image-preview` |
-| `DASHSCOPE_IMAGE_MODEL` | DashScope 模型 | `z-image-turbo` |
+| `DASHSCOPE_IMAGE_MODEL` | DashScope 模型 | `qwen-image-2.0-pro` |
+| `ZAI_IMAGE_MODEL` | Z.AI 模型 | `glm-image` |
+| `BIGMODEL_IMAGE_MODEL` | Z.AI 模型向后兼容别名 | `glm-image` |
+| `MINIMAX_IMAGE_MODEL` | MiniMax 模型 | `image-01` |
+| `REPLICATE_IMAGE_MODEL` | Replicate 模型 | `google/nano-banana-2` |
+| `JIMENG_IMAGE_MODEL` | 即梦模型 | `jimeng_t2i_v40` |
+| `SEEDREAM_IMAGE_MODEL` | 豆包模型 | `doubao-seedream-5-0-260128` |
 | `OPENAI_BASE_URL` | 自定义 OpenAI 端点 | - |
+| `OPENAI_IMAGE_API_DIALECT` | OpenAI 兼容图像 API 方言（`openai-native` 或 `ratio-metadata`） | `openai-native` |
+| `OPENAI_IMAGE_USE_CHAT` | OpenAI 改走 `/chat/completions` | `false` |
+| `AZURE_OPENAI_BASE_URL` | Azure 资源或部署端点 | - |
+| `AZURE_API_VERSION` | Azure 图像 API 版本 | `2025-04-01-preview` |
+| `OPENROUTER_BASE_URL` | 自定义 OpenRouter 端点 | `https://openrouter.ai/api/v1` |
+| `OPENROUTER_HTTP_REFERER` | OpenRouter 归因用站点 URL | - |
+| `OPENROUTER_TITLE` | OpenRouter 归因用应用名 | - |
 | `GOOGLE_BASE_URL` | 自定义 Google 端点 | - |
 | `DASHSCOPE_BASE_URL` | 自定义 DashScope 端点 | - |
+| `ZAI_BASE_URL` | 自定义 Z.AI 端点 | `https://api.z.ai/api/paas/v4` |
+| `BIGMODEL_BASE_URL` | Z.AI 端点向后兼容别名 | - |
+| `MINIMAX_BASE_URL` | 自定义 MiniMax 端点 | `https://api.minimax.io` |
+| `REPLICATE_BASE_URL` | 自定义 Replicate 端点 | - |
+| `JIMENG_BASE_URL` | 自定义即梦端点 | `https://visual.volcengineapi.com` |
+| `JIMENG_REGION` | 即梦区域 | `cn-north-1` |
+| `SEEDREAM_BASE_URL` | 自定义豆包端点 | `https://ark.cn-beijing.volces.com/api/v3` |
+| `BAOYU_IMAGE_GEN_MAX_WORKERS` | 批量模式最大 worker 数 | `10` |
+| `BAOYU_IMAGE_GEN_<PROVIDER>_CONCURRENCY` | 覆盖 provider 并发数 | provider 默认值 |
+| `BAOYU_IMAGE_GEN_<PROVIDER>_START_INTERVAL_MS` | 覆盖 provider 请求启动间隔 | provider 默认值 |
+
+**Provider 说明**：
+- Azure OpenAI：`--model` 表示 Azure deployment name，不是底层模型家族名。
+- DashScope：`qwen-image-2.0-pro` 是自定义 `--size`、`21:9` 和中英文排版的推荐默认模型。
+- Z.AI：`glm-image` 适合海报、图表和中英文排版密集的图片生成，暂不支持参考图。
+- MiniMax：`image-01` 支持官方文档里的自定义 `width` / `height`；`image-01-live` 更偏低延迟，适合配合 `--ar` 使用。
+- MiniMax 参考图会走 `subject_reference`，当前能力更偏角色 / 人像一致性。
+- 即梦不支持参考图。
+- 豆包参考图能力仅适用于 Seedream 5.0 / 4.5 / 4.0，不适用于 Seedream 3.0。
+- Replicate 默认模型改为 `google/nano-banana-2`。`baoyu-imagine` 目前只对 `google/nano-banana*`、`bytedance/seedream-4.5`、`bytedance/seedream-5-lite`、`wan-video/wan-2.7-image` 和 `wan-video/wan-2.7-image-pro` 开启本地能力识别与校验。
+- Replicate 当前只保存单张输出图，`--n > 1` 会在本地直接报错，避免多图结果被静默丢弃。
+- Replicate 的参数能力按模型家族区分：nano-banana 走 `--quality` / `--ar`，Seedream 走校验后的 `--size` / `--ar`，Wan 走校验后的 `--size`（`--ar` 会先在本地换算成具体尺寸）。
 
 **服务商自动选择**：
 1. 如果指定了 `--provider` → 使用指定的
-2. 如果只有一个 API 密钥 → 使用对应服务商
-3. 如果多个可用 → 默认使用 Google
+2. 如果传了 `--ref` 且未指定 provider → 依次尝试 Google、OpenAI、Azure、OpenRouter、Replicate、Seedream，最后是 MiniMax
+3. 如果只有一个 API 密钥 → 使用对应服务商
+4. 如果多个可用 → 默认使用 Google，然后依次为 OpenAI、Azure、OpenRouter、DashScope、Z.AI、MiniMax、Replicate、即梦、豆包
 
 #### baoyu-danger-gemini-web
 
@@ -639,9 +883,43 @@ AI 驱动的生成后端。
 
 内容处理工具。
 
+#### baoyu-youtube-transcript
+
+下载 YouTube 视频字幕/转录文本和封面图片。支持多语言、翻译、章节分段和说话人识别。缓存原始数据以便快速重新格式化。
+
+```bash
+# 默认：带时间戳的 Markdown
+/baoyu-youtube-transcript https://www.youtube.com/watch?v=VIDEO_ID
+
+# 指定语言（按优先级排列）
+/baoyu-youtube-transcript https://youtu.be/VIDEO_ID --languages zh,en,ja
+
+# 章节分段 + 说话人识别
+/baoyu-youtube-transcript https://youtu.be/VIDEO_ID --chapters --speakers
+
+# SRT 字幕格式
+/baoyu-youtube-transcript https://youtu.be/VIDEO_ID --format srt
+
+# 列出可用字幕
+/baoyu-youtube-transcript https://youtu.be/VIDEO_ID --list
+```
+
+**选项**：
+| 选项 | 说明 | 默认值 |
+|------|------|--------|
+| `<url-or-id>` | YouTube URL 或视频 ID | 必填 |
+| `--languages <codes>` | 语言代码，逗号分隔 | `en` |
+| `--format <fmt>` | 输出格式：`text`、`srt` | `text` |
+| `--translate <code>` | 翻译为指定语言 | |
+| `--chapters` | 根据视频描述进行章节分段 | |
+| `--speakers` | 说话人识别（需 AI 后处理） | |
+| `--no-timestamps` | 禁用时间戳 | |
+| `--list` | 列出可用字幕 | |
+| `--refresh` | 强制重新获取，忽略缓存 | |
+
 #### baoyu-url-to-markdown
 
-通过 Chrome CDP 抓取任意 URL 并转换为干净的 Markdown。支持两种抓取模式，适应不同场景。
+通过 Chrome CDP 抓取任意 URL 并转换为 Markdown。同时保存渲染后的 HTML 快照，Defuddle 失败时自动回退到旧版提取器。
 
 ```bash
 # 自动模式（默认）- 页面加载后立即抓取
@@ -739,12 +1017,107 @@ AI 驱动的生成后端。
 | 代码/命令 | `` `行内` `` 或 ` ```代码块``` ` |
 | 引用 | `>` 引用块 |
 
+#### baoyu-markdown-to-html
+
+将 Markdown 文件转换为样式化 HTML，支持微信公众号兼容主题、代码高亮，以及可选的外链底部引用。
+
+```bash
+# 基础转换
+/baoyu-markdown-to-html article.md
+
+# 主题 + 颜色
+/baoyu-markdown-to-html article.md --theme grace --color red
+
+# 将普通外链转换为文末引用
+/baoyu-markdown-to-html article.md --cite
+```
+
+#### baoyu-translate
+
+三模式翻译技能：快速（直接翻译）、标准（分析后翻译）、精翻（完整出版级工作流，含审校与润色）。
+
+```bash
+# 标准模式（默认）- 先分析再翻译
+/translate article.md --to zh-CN
+
+# 快速模式 - 直接翻译
+/translate article.md --mode quick --to ja
+
+# 精翻模式 - 完整工作流，含审校与润色
+/translate article.md --mode refined --to zh-CN
+
+# 翻译 URL
+/translate https://example.com/article --to zh-CN
+
+# 指定受众
+/translate article.md --to zh-CN --audience technical
+
+# 指定风格
+/translate article.md --to zh-CN --style humorous
+
+# 附加术语表
+/translate article.md --to zh-CN --glossary my-terms.md
+```
+
+**选项**：
+| 选项 | 说明 |
+|------|------|
+| `<source>` | 文件路径、URL 或行内文本 |
+| `--mode <mode>` | `quick`、`normal`（默认）、`refined` |
+| `--from <lang>` | 源语言（省略则自动检测） |
+| `--to <lang>` | 目标语言（默认：`zh-CN`） |
+| `--audience <type>` | 目标读者（默认：`general`） |
+| `--style <style>` | 翻译风格（默认：`storytelling`） |
+| `--glossary <file>` | 附加术语表文件 |
+
+**模式**：
+| 模式 | 步骤 | 适用场景 |
+|------|------|----------|
+| 快速 | 翻译 | 短文本、非正式内容 |
+| 标准 | 分析 → 翻译 | 文章、博客 |
+| 精翻 | 分析 → 翻译 → 审校 → 润色 | 出版级文档 |
+
+标准模式完成后，可回复「继续润色」或「refine」继续审校润色步骤。
+
+**受众预设**：
+| 值 | 说明 |
+|----|------|
+| `general` | 普通读者（默认）— 通俗语言，更多译注 |
+| `technical` | 开发者/工程师 — 常见技术术语少加注释 |
+| `academic` | 研究者/学者 — 正式语体，精确术语 |
+| `business` | 商务人士 — 商务友好语气 |
+
+也支持自定义受众描述，如 `--audience "对 AI 感兴趣的普通读者"`。
+
+**风格预设**：
+| 值 | 说明 |
+|----|------|
+| `storytelling` | 叙事流畅（默认）— 过渡自然，表达生动 |
+| `formal` | 正式、结构化 — 中性语气，无口语化表达 |
+| `technical` | 精确、文档风格 — 简洁，术语密集 |
+| `literal` | 贴近原文结构 — 最小化重构 |
+| `academic` | 学术、严谨 — 正式语体，复杂从句可接受 |
+| `business` | 简洁、结果导向 — 行动导向，高管友好 |
+| `humorous` | 保留幽默感 — 诙谐，在目标语言中重现喜剧效果 |
+| `conversational` | 口语化、亲切 — 友好，如同朋友间解释 |
+| `elegant` | 文学性、优雅 — 精心雕琢，注重韵律美感 |
+
+也支持自定义风格描述，如 `--style "诗意而抒情"`。
+
+**特性**：
+- 通过 EXTEND.md 自定义术语表，内置英中术语表
+- 面向受众的翻译，可调节注释深度
+- 长文档（4000+ 词）自动分块并行翻译
+- 比喻和修辞按意译而非逐字翻译
+- 为文化/专业术语添加译注
+- 输出目录保留所有中间文件
+
 ## 环境配置
 
 部分技能需要 API 密钥或自定义配置。环境变量可以在 `.env` 文件中设置：
 
 **加载优先级**（高优先级覆盖低优先级）：
-1. 命令行环境变量（如 `OPENAI_API_KEY=xxx /baoyu-image-gen ...`）
+1. 命令行环境变量（如 `OPENAI_API_KEY=xxx /baoyu-imagine ...`）
 2. `process.env`（系统环境变量）
 3. `<cwd>/.baoyu-skills/.env`（项目级）
 4. `~/.baoyu-skills/.env`（用户级）
@@ -759,8 +1132,22 @@ mkdir -p ~/.baoyu-skills
 cat > ~/.baoyu-skills/.env << 'EOF'
 # OpenAI
 OPENAI_API_KEY=sk-xxx
-OPENAI_IMAGE_MODEL=gpt-image-1.5
+OPENAI_IMAGE_MODEL=gpt-image-2
 # OPENAI_BASE_URL=https://api.openai.com/v1
+# OPENAI_IMAGE_USE_CHAT=false
+
+# Azure OpenAI
+AZURE_OPENAI_API_KEY=xxx
+AZURE_OPENAI_BASE_URL=https://your-resource.openai.azure.com
+AZURE_OPENAI_DEPLOYMENT=gpt-image-2
+# AZURE_API_VERSION=2025-04-01-preview
+
+# OpenRouter
+OPENROUTER_API_KEY=sk-or-xxx
+OPENROUTER_IMAGE_MODEL=google/gemini-3.1-flash-image-preview
+# OPENROUTER_BASE_URL=https://openrouter.ai/api/v1
+# OPENROUTER_HTTP_REFERER=https://your-app.example.com
+# OPENROUTER_TITLE=你的应用名
 
 # Google
 GOOGLE_API_KEY=xxx
@@ -769,8 +1156,35 @@ GOOGLE_IMAGE_MODEL=gemini-3-pro-image-preview
 
 # DashScope（阿里通义万相）
 DASHSCOPE_API_KEY=sk-xxx
-DASHSCOPE_IMAGE_MODEL=z-image-turbo
+DASHSCOPE_IMAGE_MODEL=qwen-image-2.0-pro
 # DASHSCOPE_BASE_URL=https://dashscope.aliyuncs.com/api/v1
+
+# Z.AI
+ZAI_API_KEY=xxx
+ZAI_IMAGE_MODEL=glm-image
+# ZAI_BASE_URL=https://api.z.ai/api/paas/v4
+
+# MiniMax
+MINIMAX_API_KEY=xxx
+MINIMAX_IMAGE_MODEL=image-01
+# MINIMAX_BASE_URL=https://api.minimax.io
+
+# Replicate
+REPLICATE_API_TOKEN=r8_xxx
+REPLICATE_IMAGE_MODEL=google/nano-banana-2
+# REPLICATE_BASE_URL=https://api.replicate.com
+
+# 即梦（Jimeng）
+JIMENG_ACCESS_KEY_ID=xxx
+JIMENG_SECRET_ACCESS_KEY=xxx
+JIMENG_IMAGE_MODEL=jimeng_t2i_v40
+# JIMENG_BASE_URL=https://visual.volcengineapi.com
+# JIMENG_REGION=cn-north-1
+
+# 豆包（Seedream）
+ARK_API_KEY=xxx
+SEEDREAM_IMAGE_MODEL=doubao-seedream-5-0-260128
+# SEEDREAM_BASE_URL=https://ark.cn-beijing.volces.com/api/v3
 EOF
 ```
 
@@ -842,6 +1256,20 @@ HTTP_PROXY=http://127.0.0.1:7890 HTTPS_PROXY=http://127.0.0.1:7890 /baoyu-danger
 - 首次使用需确认免责声明
 - 通过环境变量或 Chrome 登录进行身份验证
 
+## 致谢
+
+本项目受到以下开源项目的启发，感谢它们的作者：
+
+- [x-article-publisher-skill](https://github.com/wshuyi/x-article-publisher-skill) by [@wshuyi](https://github.com/wshuyi) — 发布 X 文章技能的灵感来源
+- [doocs/md](https://github.com/doocs/md) by [@doocs](https://github.com/doocs) — Markdown 转 HTML 的核心实现逻辑
+- [高密度信息图 Prompt](https://waytoagi.feishu.cn/wiki/YG0zwalijihRREkgmPzcWRInnUg) by AJ@WaytoAGI — 信息图技能的灵感来源
+- [qiaomu-mondo-poster-design](https://github.com/joeseesun/qiaomu-mondo-poster-design) by [@joeseesun](https://github.com/joeseesun)（乔木） — Mondo 风格的灵感来源
+- [architecture-diagram-generator](https://github.com/Cocoon-AI/architecture-diagram-generator) by [@Cocoon-AI](https://github.com/Cocoon-AI) — 图表技能设计体系的灵感来源
+
 ## 许可证
 
 MIT
+
+## Star History
+
+[![Star History Chart](https://api.star-history.com/svg?repos=JimLiu/baoyu-skills&type=Date)](https://www.star-history.com/#JimLiu/baoyu-skills&Date)

docs/chrome-profile.md

@@ -0,0 +1,27 @@
+# Chrome Profile
+
+All CDP skills share a single profile directory. Do NOT create per-skill profiles.
+
+Override: `BAOYU_CHROME_PROFILE_DIR` env var (takes priority over all defaults).
+
+| Platform | Default Path |
+|----------|-------------|
+| macOS | `~/Library/Application Support/baoyu-skills/chrome-profile` |
+| Linux | `$XDG_DATA_HOME/baoyu-skills/chrome-profile` (fallback `~/.local/share/`) |
+| Windows | `%APPDATA%/baoyu-skills/chrome-profile` |
+| WSL | Windows home `/.local/share/baoyu-skills/chrome-profile` |
+
+New skills: use `BAOYU_CHROME_PROFILE_DIR` only (not per-skill env vars like `X_BROWSER_PROFILE_DIR`).
+
+## Implementation Pattern
+
+```typescript
+function getDefaultProfileDir(): string {
+  const override = process.env.BAOYU_CHROME_PROFILE_DIR?.trim();
+  if (override) return path.resolve(override);
+  const base = process.platform === 'darwin'
+    ? path.join(os.homedir(), 'Library', 'Application Support')
+    : process.env.XDG_DATA_HOME || path.join(os.homedir(), '.local', 'share');
+  return path.join(base, 'baoyu-skills', 'chrome-profile');
+}
+```

docs/comic-style-maintenance.md

@@ -0,0 +1,35 @@
+# Style Maintenance (baoyu-comic)
+
+## Adding a New Style
+
+1. Create style definition: `skills/baoyu-comic/references/styles/<style-name>.md`
+2. Update SKILL.md: add to `--style` options table + auto-selection entry
+3. Generate showcase image:
+   ```bash
+   ${BUN_X} skills/baoyu-danger-gemini-web/scripts/main.ts \
+     --prompt "A single comic book page in <style-name> style showing [scene]. Features: [characteristics]. 3:4 portrait aspect ratio comic page." \
+     --image screenshots/comic-styles/<style-name>.png
+   ```
+4. Compress: `${BUN_X} skills/baoyu-compress-image/scripts/main.ts screenshots/comic-styles/<style-name>.png`
+5. Update both READMEs (`README.md` + `README.zh.md`): add style to options, description table, preview grid
+
+## Updating an Existing Style
+
+1. Update style definition in `references/styles/`
+2. Regenerate showcase image if visual characteristics changed (steps 3-4 above)
+3. Update READMEs if description changed
+
+## Deleting a Style
+
+1. Delete style definition + showcase image (`.webp`)
+2. Remove from SKILL.md `--style` options + auto-selection
+3. Remove from both READMEs (options, description table, preview grid)
+
+## Style Preview Grid Format
+
+```markdown
+| | | |
+|:---:|:---:|:---:|
+| ![style1](./screenshots/comic-styles/style1.webp) | ![style2](./screenshots/comic-styles/style2.webp) | ![style3](./screenshots/comic-styles/style3.webp) |
+| style1 | style2 | style3 |
+```

docs/creating-skills.md

@@ -0,0 +1,175 @@
+# Creating New Skills
+
+**REQUIRED READING**: [Skill authoring best practices](https://platform.claude.com/docs/en/agents-and-tools/agent-skills/best-practices)
+
+## Key Requirements
+
+| Requirement | Details |
+|-------------|---------|
+| **Prefix** | All skills MUST use `baoyu-` prefix |
+| **name field** | Max 64 chars, lowercase letters/numbers/hyphens only, no "anthropic"/"claude" |
+| **description** | Max 1024 chars, third person, include what + when to use |
+| **SKILL.md body** | Keep under 500 lines; use `references/` for additional content |
+| **References** | One level deep from SKILL.md; avoid nested references |
+
+## SKILL.md Frontmatter Template
+
+```yaml
+---
+name: baoyu-<name>
+description: <Third-person description. What it does + when to use it.>
+version: <semver matching marketplace.json>
+metadata:
+  openclaw:
+    homepage: https://github.com/JimLiu/baoyu-skills#baoyu-<name>
+    requires:          # include only if skill has scripts
+      anyBins:
+        - bun
+        - npx
+---
+```
+
+## Steps
+
+1. Create `skills/baoyu-<name>/SKILL.md` with YAML front matter
+2. Add TypeScript in `skills/baoyu-<name>/scripts/` (if applicable)
+3. Add prompt templates in `skills/baoyu-<name>/prompts/` if needed
+4. Register the skill in `.claude-plugin/marketplace.json` under the `baoyu-skills` plugin entry
+5. Add Script Directory section to SKILL.md if skill has scripts
+6. Add openclaw metadata to frontmatter
+
+## Skill Grouping
+
+All skills are registered under the single `baoyu-skills` plugin. Use these logical groups when deciding where the skill should appear in the docs:
+
+| If your skill... | Use group |
+|------------------|-----------|
+| Generates visual content (images, slides, comics) | Content Skills |
+| Publishes to platforms (X, WeChat, Weibo) | Content Skills |
+| Provides AI generation backend | AI Generation Skills |
+| Converts or processes content | Utility Skills |
+
+If you add a new logical group, update the docs that present grouped skills, but keep the skill registered under the single `baoyu-skills` plugin entry.
+
+## Writing Descriptions
+
+**MUST write in third person**:
+
+```yaml
+# Good
+description: Generates Xiaohongshu infographic series from content. Use when user asks for "小红书图片", "XHS images".
+
+# Bad
+description: I can help you create Xiaohongshu images
+```
+
+## Script Directory Template
+
+Every SKILL.md with scripts MUST include:
+
+```markdown
+## Script Directory
+
+**Important**: All scripts are located in the `scripts/` subdirectory of this skill.
+
+**Agent Execution Instructions**:
+1. Determine this SKILL.md file's directory path as `{baseDir}`
+2. Script path = `{baseDir}/scripts/<script-name>.ts`
+3. Resolve `${BUN_X}` runtime: if `bun` installed → `bun`; if `npx` available → `npx -y bun`; else suggest installing bun
+4. Replace all `{baseDir}` and `${BUN_X}` in this document with actual values
+
+**Script Reference**:
+| Script | Purpose |
+|--------|---------|
+| `scripts/main.ts` | Main entry point |
+```
+
+## Progressive Disclosure
+
+For skills with extensive content:
+
+```
+skills/baoyu-example/
+├── SKILL.md              # Main instructions (<500 lines)
+├── references/
+│   ├── styles.md         # Loaded as needed
+│   └── examples.md       # Loaded as needed
+└── scripts/
+    └── main.ts
+```
+
+Link from SKILL.md (one level deep only):
+```markdown
+**Available styles**: See [references/styles.md](references/styles.md)
+```
+
+## Extension Support (EXTEND.md)
+
+Every SKILL.md MUST include EXTEND.md loading. Add as Step 1.1 (workflow skills) or "Preferences" section (utility skills):
+
+```markdown
+**1.1 Load Preferences (EXTEND.md)**
+
+Check EXTEND.md existence (priority order):
+
+\`\`\`bash
+test -f .baoyu-skills/<skill-name>/EXTEND.md && echo "project"
+test -f "${XDG_CONFIG_HOME:-$HOME/.config}/baoyu-skills/<skill-name>/EXTEND.md" && echo "xdg"
+test -f "$HOME/.baoyu-skills/<skill-name>/EXTEND.md" && echo "user"
+\`\`\`
+
+| Path | Location |
+|------|----------|
+| `.baoyu-skills/<skill-name>/EXTEND.md` | Project directory |
+| `$XDG_CONFIG_HOME/baoyu-skills/<skill-name>/EXTEND.md` | XDG config (~/.config) |
+| `$HOME/.baoyu-skills/<skill-name>/EXTEND.md` | User home (legacy) |
+
+| Result | Action |
+|--------|--------|
+| Found | Read, parse, display summary |
+| Not found | Ask user via the runtime's user-input tool (see [user-input-tools.md](user-input-tools.md)) |
+```
+
+End of SKILL.md should include:
+```markdown
+## Extension Support
+Custom configurations via EXTEND.md. See **Step 1.1** for paths and supported options.
+```
+
+## User Input Tools Section (Required)
+
+Every SKILL.md that prompts the user for choices MUST include exactly one `## User Input Tools` section near the top (right after the intro, before the main workflow). The rule must be **inlined** — do NOT link to `docs/user-input-tools.md` (skills are self-contained; see [CLAUDE.md → Skill Self-Containment](../CLAUDE.md)). The author-side canonical reference lives at [user-input-tools.md](user-input-tools.md); copy its body into each new SKILL.md.
+
+Standard snippet (copy verbatim):
+
+```markdown
+## User Input Tools
+
+When this skill prompts the user, follow this tool-selection rule (priority order):
+
+1. **Prefer built-in user-input tools** exposed by the current agent runtime — e.g., `AskUserQuestion`, `request_user_input`, `clarify`, `ask_user`, or any equivalent.
+2. **Fallback**: if no such tool exists, emit a numbered plain-text message and ask the user to reply with the chosen number/answer for each question.
+3. **Batching**: if the tool supports multiple questions per call, combine all applicable questions into a single call; if only single-question, ask them one at a time in priority order.
+
+Concrete `AskUserQuestion` references below are examples — substitute the local equivalent in other runtimes.
+```
+
+## Image Generation Tools Section (Required for image-gen skills)
+
+Every SKILL.md that renders images — whether by calling an image-generation API directly or by delegating to another skill — MUST include exactly one `## Image Generation Tools` section near the top (after `## User Input Tools`, before the main workflow). The rule must be **inlined** — do NOT link to `docs/image-generation-tools.md` (skills are self-contained; see [CLAUDE.md → Skill Self-Containment](../CLAUDE.md)). The author-side canonical reference lives at [image-generation-tools.md](image-generation-tools.md); copy its body into each new SKILL.md.
+
+Standard snippet (copy verbatim):
+
+```markdown
+## Image Generation Tools
+
+When this skill needs to render an image:
+
+- **Use whatever image-generation tool or skill is available** in the current runtime — e.g., Codex `imagegen`, Hermes `image_generate`, `baoyu-imagine`, or any equivalent the user has installed.
+- **If multiple are available**, ask the user **once** at the start which to use (batch with any other initial questions).
+- **If none are available**, tell the user and ask how to proceed.
+
+**Prompt file requirement (hard)**: write each image's full, final prompt to a standalone file under `prompts/` (naming: `NN-{type}-[slug].md`) BEFORE invoking any backend. The backend receives the prompt file (or its content); the file is the reproducibility record and lets you switch backends without regenerating prompts.
+
+Concrete tool names (`imagegen`, `image_generate`, `baoyu-imagine`) above are examples — substitute the local equivalents under the same rule.
+```

docs/image-generation-tools.md

@@ -0,0 +1,45 @@
+# Image Generation Tools
+
+Skills in this repo are loaded by multiple agent runtimes (Claude Code, Codex, Hermes, other agents, bare CLI). Each runtime exposes a different image-generation capability — some have a runtime-native tool (Codex `imagegen`, Hermes `image_generate`), others rely on an installed skill (`baoyu-imagine`, or user-defined). This document defines the canonical **backend-selection rule** every skill that renders images follows so skills stay portable.
+
+## The Rule
+
+When a skill needs to render an image, resolve the backend in this order:
+
+1. **Current-request override** — if the user names a specific backend in the current message, use it.
+2. **Saved preference** — if the skill's `EXTEND.md` sets `preferred_image_backend` to a backend available right now, use it.
+3. **Auto-select** (when the preference is `auto`, unset, or the pinned backend isn't available):
+   - If the current runtime exposes a native image tool (e.g., Codex `imagegen`, Hermes `image_generate`), use it. Runtime-native tools are preferred by default — agents that know their own tool inventory should surface the native one here.
+   - Otherwise, if exactly one non-native backend is installed (e.g., `baoyu-imagine`), use it.
+   - Otherwise (multiple non-native backends with no runtime-native tool), ask the user once — batch with any other initial questions.
+4. **If none are available**, tell the user and ask how to proceed.
+
+Setting `preferred_image_backend: ask` forces the step-3 prompt every run regardless of available backends.
+
+## The Preference Field
+
+Each image-consuming skill's `EXTEND.md` carries a single `preferred_image_backend` field:
+
+| Value | Meaning |
+|---|---|
+| `auto` (default) | Apply the auto-select rule — runtime-native preferred, fall back to only installed backend, ask if multiple non-native. |
+| `ask` | Always confirm the backend on every run, even when a runtime-native tool exists. |
+| `<backend-id>` (e.g., `codex-imagegen`, `baoyu-imagine`, `image_generate`) | Pin this backend when available; fall back to `auto` if it isn't. |
+
+The field is **absent-equals-auto**: older `EXTEND.md` files without this field behave exactly as if `preferred_image_backend: auto` were set. No schema version bump is needed to introduce it.
+
+## Prompt File Requirement (hard)
+
+Regardless of which backend is chosen, every skill that renders images MUST write each image's full, final prompt to a standalone file under `prompts/` (naming: `NN-{type}-[slug].md`) BEFORE invoking any backend. The backend receives the prompt file (or its content); the file is the reproducibility record and allows switching backends without regenerating prompts.
+
+## How Skills Declare This
+
+Each `SKILL.md` that renders images includes **exactly one** `## Image Generation Tools` section (near the top, after `## User Input Tools` and before the main workflow) that **inlines** this rule. Skills are self-contained and cannot link to `docs/` — each skill folder must ship the rule inside its own `SKILL.md`. See [CLAUDE.md → Skill Self-Containment](../CLAUDE.md).
+
+Each skill's `references/config/preferences-schema.md` (and its `EXTEND.md` template in `first-time-setup.md`) lists `preferred_image_backend` alongside other preference fields. First-time setup does NOT ask the user about the backend — `auto` is set silently. Users who want to pin a specific backend edit `EXTEND.md` later, and each skill's `## Changing Preferences` section documents the common one-line edits.
+
+Concrete tool names (`imagegen`, `image_generate`, `baoyu-imagine`) in this document and in SKILL.md are **examples** — agents in other runtimes apply the rule above and substitute the local equivalent. Skill-specific parameters for these backends are illustrative; runtimes without those knobs can omit them.
+
+## Backend Skills Are Exempt
+
+Skills that **are themselves** image-generation backends — currently `baoyu-imagine`, `baoyu-image-gen` (deprecated), and `baoyu-danger-gemini-web` — do NOT include a `## Image Generation Tools` section. They render directly via their own provider integrations and have no need to "select a backend." The rule applies only to consumer skills that delegate rendering to whatever backend the runtime exposes.

docs/image-generation.md

@@ -0,0 +1,54 @@
+# Image Generation Guidelines
+
+Skills that require image generation MUST delegate to available image generation tools (runtime-native tools or installed skills).
+
+**Backend selection convention**: see [image-generation-tools.md](image-generation-tools.md) for the runtime-neutral rule. Short version: use whatever backend is available; if multiple, ask the user once; if none, ask how to proceed. This document covers output conventions (naming, paths) that apply regardless of which backend is selected.
+
+## Skill Selection
+
+1. Follow the rule in [image-generation-tools.md](image-generation-tools.md): use whatever backend is available; ask only on ambiguity.
+2. Read the chosen backend's documentation for parameters and capabilities.
+3. If user requests a specific backend, honor it.
+
+## Generation Flow Template
+
+```markdown
+### Step N: Generate Images
+
+**Backend Selection**:
+1. Detect available image-generation tools/skills (runtime-native + installed)
+2. If one available → use it. If multiple → ask user once. If none → ask how to proceed.
+3. Read the chosen backend's docs for parameters
+
+**Generation Flow**:
+1. Write the full prompt to `prompts/NN-{type}-[slug].md` BEFORE invoking the backend
+2. Call backend with the prompt (or prompt file), output path, and parameters
+3. Generate sequentially by default (batch parallel only when backend supports it and user has multiple prompts)
+4. Output progress: "Generated X/N"
+5. On failure, auto-retry once before reporting error
+```
+
+**Batch Parallel** (`baoyu-imagine` only): concurrent workers with per-provider throttling via `batch.max_workers` in EXTEND.md.
+
+## Output Path Convention
+
+**Output Directory**: `<skill-suffix>/<topic-slug>/`
+- `<skill-suffix>`: e.g., `xhs-images`, `cover-image`, `slide-deck`, `comic`
+- `<topic-slug>`: 2-4 words, kebab-case from content topic
+- Conflict: append timestamp `<topic-slug>-YYYYMMDD-HHMMSS`
+
+**Source Files**: Copy to output dir as `source-{slug}.{ext}`
+
+## Image Naming Convention
+
+**Format**: `NN-{type}-[slug].png`
+- `NN`: Two-digit sequence (01, 02, ...)
+- `{type}`: cover, content, page, slide, illustration, etc.
+- `[slug]`: 2-5 word kebab-case descriptor, unique within directory
+
+Examples:
+```
+01-cover-ai-future.png
+02-content-key-benefits.png
+03-slide-architecture-overview.png
+```

docs/publishing.md

@@ -0,0 +1,44 @@
+# ClawHub / OpenClaw Publishing
+
+## OpenClaw Metadata
+
+Skills include `metadata.openclaw` in YAML front matter:
+
+```yaml
+metadata:
+  openclaw:
+    homepage: https://github.com/JimLiu/baoyu-skills#<skill-name>
+    requires:          # only for skills with scripts
+      anyBins:
+        - bun
+        - npx
+```
+
+## Publishing Commands
+
+```bash
+bash scripts/sync-clawhub.sh           # sync all skills
+bash scripts/sync-clawhub.sh <skill>   # sync one skill
+```
+
+Release hooks are configured via `.releaserc.yml`. This repo does not stage a separate release directory: publish reads the skill directory directly and validates that local package references and CLI bin targets are self-contained.
+
+## Shared Workspace Packages
+
+`packages/` is the source of truth for shared runtime code. Most skills consume shared packages from npm with semver ranges. `baoyu-url-to-markdown` is the exception: it vendors the `baoyu-fetch` runtime into `skills/baoyu-url-to-markdown/scripts/lib/` so the published skill is self-contained and does not depend on the `baoyu-fetch` npm package.
+
+Current packages:
+- `baoyu-chrome-cdp` (Chrome CDP utilities), consumed by 5 skills (`baoyu-danger-gemini-web`, `baoyu-danger-x-to-markdown`, `baoyu-post-to-wechat`, `baoyu-post-to-weibo`, `baoyu-post-to-x`)
+- `baoyu-md` (shared Markdown rendering and placeholder pipeline), consumed by 3 skills (`baoyu-markdown-to-html`, `baoyu-post-to-wechat`, `baoyu-post-to-weibo`)
+- `baoyu-fetch` (URL-to-Markdown CLI), vendored into 1 skill (`baoyu-url-to-markdown`)
+
+**How it works**: npm packages are built from `packages/` and published to the public npm registry. Skills normally depend on those packages with `^<version>` specs. Release prep runs `node scripts/verify-shared-package-deps.mjs` so accidental `file:` dependencies cannot slip back in. For vendored skill runtimes, keep the copied code under the skill directory and run `node scripts/publish-skill.mjs --skill-dir <skill> --version <version> --dry-run` before publishing.
+
+**Update workflow**:
+1. Edit package under `packages/`
+2. Run the package build, e.g. `bun run --cwd packages/baoyu-md build`
+3. Publish the changed npm package with `npm publish --access public`
+4. Update consuming skill `package.json` semver ranges if the package version changed
+5. Run `node scripts/verify-shared-package-deps.mjs`
+
+**Git hook**: Run `node scripts/install-git-hooks.mjs` once to enable the `pre-push` hook. It blocks pushes when a skill uses a local `file:` dependency or a vendored workspace package.

docs/testing.md

@@ -0,0 +1,73 @@
+# Testing Strategy
+
+This repository has many scripts, but they do not share a single runtime or dependency graph. The lowest-risk testing strategy is to start from stable Node-based library code, then expand outward to CLI and skill-specific smoke tests.
+
+## Current Baseline
+
+- Root test runner: `node:test`
+- Entry point: `npm test`
+- Coverage command: `npm run test:coverage`
+- CI trigger: GitHub Actions on `push`, `pull_request`, and manual dispatch
+
+This avoids introducing Jest/Vitest across a repo that already mixes plain Node scripts, Bun-based skill packages, npm-published shared packages, and browser automation.
+
+## Rollout Plan
+
+### Phase 1: Stable library coverage
+
+Focus on pure functions under `scripts/lib/` first.
+
+- `scripts/lib/release-files.mjs`
+- `scripts/verify-shared-package-deps.mjs`
+
+Goals:
+
+- Validate file filtering and release packaging rules
+- Catch regressions that reintroduce local `file:` dependencies or vendored workspace packages
+- Keep tests deterministic and free of network, Bun, or browser requirements
+
+### Phase 2: Root CLI integration tests
+
+Add temp-directory integration tests for root CLIs that already support dry-run or local-only flows.
+
+- `scripts/verify-shared-package-deps.mjs`
+- `scripts/publish-skill.mjs --dry-run`
+- `scripts/sync-clawhub.mjs` argument handling and local skill discovery
+
+Goals:
+
+- Assert exit codes and stdout for common flows
+- Cover CLI argument parsing without hitting external services
+
+### Phase 3: Skill script smoke tests
+
+Add opt-in smoke tests for selected `skills/*/scripts/` packages, starting with those that:
+
+- accept local input files
+- have deterministic output
+- do not require authenticated browser sessions
+
+Examples:
+
+- markdown transforms
+- file conversion helpers
+- local content analyzers
+
+Keep browser automation, login flows, and live API publishing scripts outside the default CI path unless they are explicitly mocked.
+
+### Phase 4: Coverage gates
+
+After the stable Node path has enough breadth, add coverage thresholds in CI for the tested root modules.
+
+Recommended order:
+
+1. Start with reporting only
+2. Add line/function thresholds for `scripts/lib/**`
+3. Expand include patterns once skill-level smoke tests are reliable
+
+## Conventions For New Tests
+
+- Prefer temp directories over committed fixtures unless the fixture is reused heavily
+- Test exported functions before testing CLI wrappers
+- Avoid network, browser, and credential dependencies in default CI
+- Keep tests isolated so they can run with plain `node --test`

docs/user-input-tools.md

@@ -0,0 +1,17 @@
+# User Input Tools
+
+Skills in this repo are loaded by multiple agent runtimes (Claude Code, other agents, bare CLI). Each runtime exposes a different API for asking the user questions. This document defines the canonical **tool-selection rule** every skill follows so skills stay portable.
+
+## Tool Selection (priority order)
+
+1. **Prefer built-in user-input tools** if the current agent runtime exposes one — e.g., `AskUserQuestion`, `request_user_input`, `clarify`, `ask_user`, or any equivalent.
+2. **Fallback to plain text**: if no such tool exists, emit a numbered plain-text message and ask the user to reply with the chosen number/answer for each question.
+3. **Batching rule**:
+   - If the tool supports **multiple questions per call** (e.g., `AskUserQuestion`): **Combine all applicable questions into a single call. Do NOT split into separate calls.**
+   - If the tool supports **only one question per call** (e.g., single-prompt `clarify`): ask **one question per call, in priority order**.
+
+## How Skills Declare This
+
+Each `SKILL.md` that uses interactive user input includes **exactly one** `## User Input Tools` section (typically near the top, right after the intro) that **inlines** this rule. Do NOT link here from a SKILL.md — skills are self-contained (see [CLAUDE.md → Skill Self-Containment](../CLAUDE.md)). This document is the author-side canonical source; copy its body into each SKILL.md. The rule then governs every user-input interaction in that skill and its `references/` files.
+
+Specific mentions of a concrete tool (e.g., `AskUserQuestion`) elsewhere in a skill are **concrete examples** — agents in other runtimes apply the rule above and substitute the local equivalent. Tool-specific parameters (e.g., `header:`, `multiSelect:`) are illustrative; runtimes without those knobs can omit them.

package.json

@@ -0,0 +1,27 @@
+{
+  "name": "baoyu-skills",
+  "private": true,
+  "type": "module",
+  "workspaces": [
+    "packages/*"
+  ],
+  "scripts": {
+    "test": "node ./scripts/run-node-tests.mjs",
+    "test:coverage": "node ./scripts/run-node-tests.mjs --experimental-test-coverage"
+  },
+  "devDependencies": {
+    "@mozilla/readability": "^0.6.0",
+    "linkedom": "^0.18.12",
+    "turndown": "^7.2.2",
+    "turndown-plugin-gfm": "^1.0.2",
+    "tsx": "^4.20.5"
+  },
+  "dependencies": {
+    "pdf-lib": "^1.17.1",
+    "pptxgenjs": "^4.0.1",
+    "sharp": "^0.34.5"
+  },
+  "overrides": {
+    "@xmldom/xmldom": "0.8.13"
+  }
+}

packages/baoyu-chrome-cdp/dist/index.cjs

@@ -0,0 +1,479 @@
+var __create = Object.create;
+var __getProtoOf = Object.getPrototypeOf;
+var __defProp = Object.defineProperty;
+var __getOwnPropNames = Object.getOwnPropertyNames;
+var __getOwnPropDesc = Object.getOwnPropertyDescriptor;
+var __hasOwnProp = Object.prototype.hasOwnProperty;
+function __accessProp(key) {
+  return this[key];
+}
+var __toESMCache_node;
+var __toESMCache_esm;
+var __toESM = (mod, isNodeMode, target) => {
+  var canCache = mod != null && typeof mod === "object";
+  if (canCache) {
+    var cache = isNodeMode ? __toESMCache_node ??= new WeakMap : __toESMCache_esm ??= new WeakMap;
+    var cached = cache.get(mod);
+    if (cached)
+      return cached;
+  }
+  target = mod != null ? __create(__getProtoOf(mod)) : {};
+  const to = isNodeMode || !mod || !mod.__esModule ? __defProp(target, "default", { value: mod, enumerable: true }) : target;
+  for (let key of __getOwnPropNames(mod))
+    if (!__hasOwnProp.call(to, key))
+      __defProp(to, key, {
+        get: __accessProp.bind(mod, key),
+        enumerable: true
+      });
+  if (canCache)
+    cache.set(mod, to);
+  return to;
+};
+var __toCommonJS = (from) => {
+  var entry = (__moduleCache ??= new WeakMap).get(from), desc;
+  if (entry)
+    return entry;
+  entry = __defProp({}, "__esModule", { value: true });
+  if (from && typeof from === "object" || typeof from === "function") {
+    for (var key of __getOwnPropNames(from))
+      if (!__hasOwnProp.call(entry, key))
+        __defProp(entry, key, {
+          get: __accessProp.bind(from, key),
+          enumerable: !(desc = __getOwnPropDesc(from, key)) || desc.enumerable
+        });
+  }
+  __moduleCache.set(from, entry);
+  return entry;
+};
+var __moduleCache;
+var __returnValue = (v) => v;
+function __exportSetter(name, newValue) {
+  this[name] = __returnValue.bind(null, newValue);
+}
+var __export = (target, all) => {
+  for (var name in all)
+    __defProp(target, name, {
+      get: all[name],
+      enumerable: true,
+      configurable: true,
+      set: __exportSetter.bind(all, name)
+    });
+};
+
+// src/index.ts
+var exports_src = {};
+__export(exports_src, {
+  waitForChromeDebugPort: () => waitForChromeDebugPort,
+  sleep: () => sleep,
+  resolveSharedChromeProfileDir: () => resolveSharedChromeProfileDir,
+  openPageSession: () => openPageSession,
+  launchChrome: () => launchChrome,
+  killChrome: () => killChrome,
+  gracefulKillChrome: () => gracefulKillChrome,
+  getFreePort: () => getFreePort,
+  getDefaultChromeUserDataDirs: () => getDefaultChromeUserDataDirs,
+  findExistingChromeDebugPort: () => findExistingChromeDebugPort,
+  findChromeExecutable: () => findChromeExecutable,
+  discoverRunningChromeDebugPort: () => discoverRunningChromeDebugPort,
+  CdpConnection: () => CdpConnection
+});
+module.exports = __toCommonJS(exports_src);
+var import_node_child_process = require("node:child_process");
+var import_node_fs = __toESM(require("node:fs"));
+var import_node_net = __toESM(require("node:net"));
+var import_node_os = __toESM(require("node:os"));
+var import_node_path = __toESM(require("node:path"));
+var import_node_process = __toESM(require("node:process"));
+function sleep(ms) {
+  return new Promise((resolve) => setTimeout(resolve, ms));
+}
+async function getFreePort(fixedEnvName) {
+  const fixed = fixedEnvName ? Number.parseInt(import_node_process.default.env[fixedEnvName] ?? "", 10) : NaN;
+  if (Number.isInteger(fixed) && fixed > 0)
+    return fixed;
+  return await new Promise((resolve, reject) => {
+    const server = import_node_net.default.createServer();
+    server.unref();
+    server.on("error", reject);
+    server.listen(0, "127.0.0.1", () => {
+      const address = server.address();
+      if (!address || typeof address === "string") {
+        server.close(() => reject(new Error("Unable to allocate a free TCP port.")));
+        return;
+      }
+      const port = address.port;
+      server.close((err) => {
+        if (err)
+          reject(err);
+        else
+          resolve(port);
+      });
+    });
+  });
+}
+function findChromeExecutable(options) {
+  for (const envName of options.envNames ?? []) {
+    const override = import_node_process.default.env[envName]?.trim();
+    if (override && import_node_fs.default.existsSync(override))
+      return override;
+  }
+  const candidates = import_node_process.default.platform === "darwin" ? options.candidates.darwin ?? options.candidates.default : import_node_process.default.platform === "win32" ? options.candidates.win32 ?? options.candidates.default : options.candidates.default;
+  for (const candidate of candidates) {
+    if (import_node_fs.default.existsSync(candidate))
+      return candidate;
+  }
+  return;
+}
+function resolveSharedChromeProfileDir(options = {}) {
+  for (const envName of options.envNames ?? []) {
+    const override = import_node_process.default.env[envName]?.trim();
+    if (override)
+      return import_node_path.default.resolve(override);
+  }
+  const appDataDirName = options.appDataDirName ?? "baoyu-skills";
+  const profileDirName = options.profileDirName ?? "chrome-profile";
+  if (options.wslWindowsHome) {
+    return import_node_path.default.join(options.wslWindowsHome, ".local", "share", appDataDirName, profileDirName);
+  }
+  const base = import_node_process.default.platform === "darwin" ? import_node_path.default.join(import_node_os.default.homedir(), "Library", "Application Support") : import_node_process.default.platform === "win32" ? import_node_process.default.env.APPDATA ?? import_node_path.default.join(import_node_os.default.homedir(), "AppData", "Roaming") : import_node_process.default.env.XDG_DATA_HOME ?? import_node_path.default.join(import_node_os.default.homedir(), ".local", "share");
+  return import_node_path.default.join(base, appDataDirName, profileDirName);
+}
+async function fetchWithTimeout(url, timeoutMs) {
+  if (!timeoutMs || timeoutMs <= 0)
+    return await fetch(url, { redirect: "follow" });
+  const ctl = new AbortController;
+  const timer = setTimeout(() => ctl.abort(), timeoutMs);
+  try {
+    return await fetch(url, { redirect: "follow", signal: ctl.signal });
+  } finally {
+    clearTimeout(timer);
+  }
+}
+async function fetchJson(url, options = {}) {
+  const response = await fetchWithTimeout(url, options.timeoutMs);
+  if (!response.ok) {
+    throw new Error(`Request failed: ${response.status} ${response.statusText}`);
+  }
+  return await response.json();
+}
+async function isDebugPortReady(port, timeoutMs = 3000) {
+  try {
+    const version = await fetchJson(`http://127.0.0.1:${port}/json/version`, { timeoutMs });
+    return !!version.webSocketDebuggerUrl;
+  } catch {
+    return false;
+  }
+}
+function isPortListening(port, timeoutMs = 3000) {
+  return new Promise((resolve) => {
+    const socket = new import_node_net.default.Socket;
+    const timer = setTimeout(() => {
+      socket.destroy();
+      resolve(false);
+    }, timeoutMs);
+    socket.once("connect", () => {
+      clearTimeout(timer);
+      socket.destroy();
+      resolve(true);
+    });
+    socket.once("error", () => {
+      clearTimeout(timer);
+      resolve(false);
+    });
+    socket.connect(port, "127.0.0.1");
+  });
+}
+function parseDevToolsActivePort(filePath) {
+  try {
+    const content = import_node_fs.default.readFileSync(filePath, "utf-8");
+    const lines = content.split(/\r?\n/);
+    const port = Number.parseInt(lines[0]?.trim() ?? "", 10);
+    const wsPath = lines[1]?.trim();
+    if (port > 0 && wsPath)
+      return { port, wsPath };
+  } catch {}
+  return null;
+}
+async function findExistingChromeDebugPort(options) {
+  const timeoutMs = options.timeoutMs ?? 3000;
+  const parsed = parseDevToolsActivePort(import_node_path.default.join(options.profileDir, "DevToolsActivePort"));
+  if (parsed && parsed.port > 0 && await isDebugPortReady(parsed.port, timeoutMs))
+    return parsed.port;
+  if (import_node_process.default.platform === "win32")
+    return null;
+  try {
+    const result = import_node_child_process.spawnSync("ps", ["aux"], { encoding: "utf-8", timeout: 5000 });
+    if (result.status !== 0 || !result.stdout)
+      return null;
+    const lines = result.stdout.split(`
+`).filter((line) => line.includes(options.profileDir) && line.includes("--remote-debugging-port="));
+    for (const line of lines) {
+      const portMatch = line.match(/--remote-debugging-port=(\d+)/);
+      const port = Number.parseInt(portMatch?.[1] ?? "", 10);
+      if (port > 0 && await isDebugPortReady(port, timeoutMs))
+        return port;
+    }
+  } catch {}
+  return null;
+}
+function getDefaultChromeUserDataDirs(channels = ["stable"]) {
+  const home = import_node_os.default.homedir();
+  const dirs = [];
+  const channelDirs = {
+    stable: {
+      darwin: import_node_path.default.join(home, "Library", "Application Support", "Google", "Chrome"),
+      linux: import_node_path.default.join(home, ".config", "google-chrome"),
+      win32: import_node_path.default.join(import_node_process.default.env.LOCALAPPDATA ?? import_node_path.default.join(home, "AppData", "Local"), "Google", "Chrome", "User Data")
+    },
+    beta: {
+      darwin: import_node_path.default.join(home, "Library", "Application Support", "Google", "Chrome Beta"),
+      linux: import_node_path.default.join(home, ".config", "google-chrome-beta"),
+      win32: import_node_path.default.join(import_node_process.default.env.LOCALAPPDATA ?? import_node_path.default.join(home, "AppData", "Local"), "Google", "Chrome Beta", "User Data")
+    },
+    canary: {
+      darwin: import_node_path.default.join(home, "Library", "Application Support", "Google", "Chrome Canary"),
+      linux: import_node_path.default.join(home, ".config", "google-chrome-canary"),
+      win32: import_node_path.default.join(import_node_process.default.env.LOCALAPPDATA ?? import_node_path.default.join(home, "AppData", "Local"), "Google", "Chrome SxS", "User Data")
+    },
+    dev: {
+      darwin: import_node_path.default.join(home, "Library", "Application Support", "Google", "Chrome Dev"),
+      linux: import_node_path.default.join(home, ".config", "google-chrome-dev"),
+      win32: import_node_path.default.join(import_node_process.default.env.LOCALAPPDATA ?? import_node_path.default.join(home, "AppData", "Local"), "Google", "Chrome Dev", "User Data")
+    }
+  };
+  const platform = import_node_process.default.platform === "darwin" ? "darwin" : import_node_process.default.platform === "win32" ? "win32" : "linux";
+  for (const ch of channels) {
+    const entry = channelDirs[ch];
+    if (entry)
+      dirs.push(entry[platform]);
+  }
+  return dirs;
+}
+async function discoverRunningChromeDebugPort(options = {}) {
+  const channels = options.channels ?? ["stable", "beta", "canary", "dev"];
+  const timeoutMs = options.timeoutMs ?? 3000;
+  const userDataDirs = (options.userDataDirs ?? getDefaultChromeUserDataDirs(channels)).map((dir) => import_node_path.default.resolve(dir));
+  for (const dir of userDataDirs) {
+    const parsed = parseDevToolsActivePort(import_node_path.default.join(dir, "DevToolsActivePort"));
+    if (!parsed)
+      continue;
+    if (await isPortListening(parsed.port, timeoutMs)) {
+      return { port: parsed.port, wsUrl: `ws://127.0.0.1:${parsed.port}${parsed.wsPath}` };
+    }
+  }
+  if (import_node_process.default.platform !== "win32") {
+    try {
+      const result = import_node_child_process.spawnSync("ps", ["aux"], { encoding: "utf-8", timeout: 5000 });
+      if (result.status === 0 && result.stdout) {
+        const lines = result.stdout.split(`
+`).filter((line) => line.includes("--remote-debugging-port=") && userDataDirs.some((dir) => line.includes(dir)));
+        for (const line of lines) {
+          const portMatch = line.match(/--remote-debugging-port=(\d+)/);
+          const port = Number.parseInt(portMatch?.[1] ?? "", 10);
+          if (port > 0 && await isDebugPortReady(port, timeoutMs)) {
+            try {
+              const version = await fetchJson(`http://127.0.0.1:${port}/json/version`, { timeoutMs });
+              if (version.webSocketDebuggerUrl)
+                return { port, wsUrl: version.webSocketDebuggerUrl };
+            } catch {}
+          }
+        }
+      }
+    } catch {}
+  }
+  return null;
+}
+async function waitForChromeDebugPort(port, timeoutMs, options) {
+  const start = Date.now();
+  let lastError = null;
+  while (Date.now() - start < timeoutMs) {
+    try {
+      const version = await fetchJson(`http://127.0.0.1:${port}/json/version`, { timeoutMs: 5000 });
+      if (version.webSocketDebuggerUrl)
+        return version.webSocketDebuggerUrl;
+      lastError = new Error("Missing webSocketDebuggerUrl");
+    } catch (error) {
+      lastError = error;
+    }
+    await sleep(200);
+  }
+  if (options?.includeLastError && lastError) {
+    throw new Error(`Chrome debug port not ready: ${lastError instanceof Error ? lastError.message : String(lastError)}`);
+  }
+  throw new Error("Chrome debug port not ready");
+}
+
+class CdpConnection {
+  ws;
+  nextId = 0;
+  pending = new Map;
+  eventHandlers = new Map;
+  defaultTimeoutMs;
+  constructor(ws, defaultTimeoutMs = 15000) {
+    this.ws = ws;
+    this.defaultTimeoutMs = defaultTimeoutMs;
+    this.ws.addEventListener("message", (event) => {
+      try {
+        const data = typeof event.data === "string" ? event.data : new TextDecoder().decode(event.data);
+        const msg = JSON.parse(data);
+        if (msg.method) {
+          const handlers = this.eventHandlers.get(msg.method);
+          if (handlers) {
+            handlers.forEach((handler) => handler(msg.params));
+          }
+        }
+        if (msg.id) {
+          const pending = this.pending.get(msg.id);
+          if (pending) {
+            this.pending.delete(msg.id);
+            if (pending.timer)
+              clearTimeout(pending.timer);
+            if (msg.error?.message)
+              pending.reject(new Error(msg.error.message));
+            else
+              pending.resolve(msg.result);
+          }
+        }
+      } catch {}
+    });
+    this.ws.addEventListener("close", () => {
+      for (const [id, pending] of this.pending.entries()) {
+        this.pending.delete(id);
+        if (pending.timer)
+          clearTimeout(pending.timer);
+        pending.reject(new Error("CDP connection closed."));
+      }
+    });
+  }
+  static async connect(url, timeoutMs, options) {
+    const ws = new WebSocket(url);
+    await new Promise((resolve, reject) => {
+      const timer = setTimeout(() => reject(new Error("CDP connection timeout.")), timeoutMs);
+      ws.addEventListener("open", () => {
+        clearTimeout(timer);
+        resolve();
+      });
+      ws.addEventListener("error", () => {
+        clearTimeout(timer);
+        reject(new Error("CDP connection failed."));
+      });
+    });
+    return new CdpConnection(ws, options?.defaultTimeoutMs ?? 15000);
+  }
+  on(method, handler) {
+    if (!this.eventHandlers.has(method)) {
+      this.eventHandlers.set(method, new Set);
+    }
+    this.eventHandlers.get(method)?.add(handler);
+  }
+  off(method, handler) {
+    this.eventHandlers.get(method)?.delete(handler);
+  }
+  async send(method, params, options) {
+    const id = ++this.nextId;
+    const message = { id, method };
+    if (params)
+      message.params = params;
+    if (options?.sessionId)
+      message.sessionId = options.sessionId;
+    const timeoutMs = options?.timeoutMs ?? this.defaultTimeoutMs;
+    const result = await new Promise((resolve, reject) => {
+      const timer = timeoutMs > 0 ? setTimeout(() => {
+        this.pending.delete(id);
+        reject(new Error(`CDP timeout: ${method}`));
+      }, timeoutMs) : null;
+      this.pending.set(id, { resolve, reject, timer });
+      this.ws.send(JSON.stringify(message));
+    });
+    return result;
+  }
+  close() {
+    try {
+      this.ws.close();
+    } catch {}
+  }
+}
+async function launchChrome(options) {
+  await import_node_fs.default.promises.mkdir(options.profileDir, { recursive: true });
+  const args = [
+    `--remote-debugging-port=${options.port}`,
+    `--user-data-dir=${options.profileDir}`,
+    "--no-first-run",
+    "--no-default-browser-check",
+    ...options.extraArgs ?? []
+  ];
+  if (options.headless)
+    args.push("--headless=new");
+  if (options.url)
+    args.push(options.url);
+  return import_node_child_process.spawn(options.chromePath, args, { stdio: "ignore" });
+}
+function killChrome(chrome) {
+  try {
+    chrome.kill("SIGTERM");
+  } catch {}
+  setTimeout(() => {
+    if (chrome.exitCode === null && chrome.signalCode === null) {
+      try {
+        chrome.kill("SIGKILL");
+      } catch {}
+    }
+  }, 2000).unref?.();
+}
+async function gracefulKillChrome(chrome, port, timeoutMs = 6000) {
+  if (chrome.exitCode !== null || chrome.signalCode !== null)
+    return;
+  const exitPromise = new Promise((resolve) => {
+    chrome.once("exit", () => resolve());
+  });
+  killChrome(chrome);
+  const start = Date.now();
+  while (Date.now() - start < timeoutMs) {
+    if (chrome.exitCode !== null || chrome.signalCode !== null)
+      return;
+    if (port !== undefined && !await isPortListening(port, 250))
+      return;
+    const exited = await Promise.race([
+      exitPromise.then(() => true),
+      sleep(100).then(() => false)
+    ]);
+    if (exited)
+      return;
+  }
+  await Promise.race([
+    exitPromise,
+    sleep(250)
+  ]);
+}
+async function openPageSession(options) {
+  let targetId;
+  let createdTarget = false;
+  if (options.reusing) {
+    const created = await options.cdp.send("Target.createTarget", { url: options.url });
+    targetId = created.targetId;
+    createdTarget = true;
+  } else {
+    const targets = await options.cdp.send("Target.getTargets");
+    const existing = targets.targetInfos.find(options.matchTarget);
+    if (existing) {
+      targetId = existing.targetId;
+    } else {
+      const created = await options.cdp.send("Target.createTarget", { url: options.url });
+      targetId = created.targetId;
+      createdTarget = true;
+    }
+  }
+  const { sessionId } = await options.cdp.send("Target.attachToTarget", { targetId, flatten: true });
+  if (options.activateTarget ?? true) {
+    await options.cdp.send("Target.activateTarget", { targetId });
+  }
+  if (options.enablePage)
+    await options.cdp.send("Page.enable", {}, { sessionId });
+  if (options.enableRuntime)
+    await options.cdp.send("Runtime.enable", {}, { sessionId });
+  if (options.enableDom)
+    await options.cdp.send("DOM.enable", {}, { sessionId });
+  if (options.enableNetwork)
+    await options.cdp.send("Network.enable", {}, { sessionId });
+  return { sessionId, targetId, createdTarget };
+}

packages/baoyu-chrome-cdp/dist/index.js

@@ -0,0 +1,415 @@
+// src/index.ts
+import { spawn, spawnSync } from "node:child_process";
+import fs from "node:fs";
+import net from "node:net";
+import os from "node:os";
+import path from "node:path";
+import process from "node:process";
+function sleep(ms) {
+  return new Promise((resolve) => setTimeout(resolve, ms));
+}
+async function getFreePort(fixedEnvName) {
+  const fixed = fixedEnvName ? Number.parseInt(process.env[fixedEnvName] ?? "", 10) : NaN;
+  if (Number.isInteger(fixed) && fixed > 0)
+    return fixed;
+  return await new Promise((resolve, reject) => {
+    const server = net.createServer();
+    server.unref();
+    server.on("error", reject);
+    server.listen(0, "127.0.0.1", () => {
+      const address = server.address();
+      if (!address || typeof address === "string") {
+        server.close(() => reject(new Error("Unable to allocate a free TCP port.")));
+        return;
+      }
+      const port = address.port;
+      server.close((err) => {
+        if (err)
+          reject(err);
+        else
+          resolve(port);
+      });
+    });
+  });
+}
+function findChromeExecutable(options) {
+  for (const envName of options.envNames ?? []) {
+    const override = process.env[envName]?.trim();
+    if (override && fs.existsSync(override))
+      return override;
+  }
+  const candidates = process.platform === "darwin" ? options.candidates.darwin ?? options.candidates.default : process.platform === "win32" ? options.candidates.win32 ?? options.candidates.default : options.candidates.default;
+  for (const candidate of candidates) {
+    if (fs.existsSync(candidate))
+      return candidate;
+  }
+  return;
+}
+function resolveSharedChromeProfileDir(options = {}) {
+  for (const envName of options.envNames ?? []) {
+    const override = process.env[envName]?.trim();
+    if (override)
+      return path.resolve(override);
+  }
+  const appDataDirName = options.appDataDirName ?? "baoyu-skills";
+  const profileDirName = options.profileDirName ?? "chrome-profile";
+  if (options.wslWindowsHome) {
+    return path.join(options.wslWindowsHome, ".local", "share", appDataDirName, profileDirName);
+  }
+  const base = process.platform === "darwin" ? path.join(os.homedir(), "Library", "Application Support") : process.platform === "win32" ? process.env.APPDATA ?? path.join(os.homedir(), "AppData", "Roaming") : process.env.XDG_DATA_HOME ?? path.join(os.homedir(), ".local", "share");
+  return path.join(base, appDataDirName, profileDirName);
+}
+async function fetchWithTimeout(url, timeoutMs) {
+  if (!timeoutMs || timeoutMs <= 0)
+    return await fetch(url, { redirect: "follow" });
+  const ctl = new AbortController;
+  const timer = setTimeout(() => ctl.abort(), timeoutMs);
+  try {
+    return await fetch(url, { redirect: "follow", signal: ctl.signal });
+  } finally {
+    clearTimeout(timer);
+  }
+}
+async function fetchJson(url, options = {}) {
+  const response = await fetchWithTimeout(url, options.timeoutMs);
+  if (!response.ok) {
+    throw new Error(`Request failed: ${response.status} ${response.statusText}`);
+  }
+  return await response.json();
+}
+async function isDebugPortReady(port, timeoutMs = 3000) {
+  try {
+    const version = await fetchJson(`http://127.0.0.1:${port}/json/version`, { timeoutMs });
+    return !!version.webSocketDebuggerUrl;
+  } catch {
+    return false;
+  }
+}
+function isPortListening(port, timeoutMs = 3000) {
+  return new Promise((resolve) => {
+    const socket = new net.Socket;
+    const timer = setTimeout(() => {
+      socket.destroy();
+      resolve(false);
+    }, timeoutMs);
+    socket.once("connect", () => {
+      clearTimeout(timer);
+      socket.destroy();
+      resolve(true);
+    });
+    socket.once("error", () => {
+      clearTimeout(timer);
+      resolve(false);
+    });
+    socket.connect(port, "127.0.0.1");
+  });
+}
+function parseDevToolsActivePort(filePath) {
+  try {
+    const content = fs.readFileSync(filePath, "utf-8");
+    const lines = content.split(/\r?\n/);
+    const port = Number.parseInt(lines[0]?.trim() ?? "", 10);
+    const wsPath = lines[1]?.trim();
+    if (port > 0 && wsPath)
+      return { port, wsPath };
+  } catch {}
+  return null;
+}
+async function findExistingChromeDebugPort(options) {
+  const timeoutMs = options.timeoutMs ?? 3000;
+  const parsed = parseDevToolsActivePort(path.join(options.profileDir, "DevToolsActivePort"));
+  if (parsed && parsed.port > 0 && await isDebugPortReady(parsed.port, timeoutMs))
+    return parsed.port;
+  if (process.platform === "win32")
+    return null;
+  try {
+    const result = spawnSync("ps", ["aux"], { encoding: "utf-8", timeout: 5000 });
+    if (result.status !== 0 || !result.stdout)
+      return null;
+    const lines = result.stdout.split(`
+`).filter((line) => line.includes(options.profileDir) && line.includes("--remote-debugging-port="));
+    for (const line of lines) {
+      const portMatch = line.match(/--remote-debugging-port=(\d+)/);
+      const port = Number.parseInt(portMatch?.[1] ?? "", 10);
+      if (port > 0 && await isDebugPortReady(port, timeoutMs))
+        return port;
+    }
+  } catch {}
+  return null;
+}
+function getDefaultChromeUserDataDirs(channels = ["stable"]) {
+  const home = os.homedir();
+  const dirs = [];
+  const channelDirs = {
+    stable: {
+      darwin: path.join(home, "Library", "Application Support", "Google", "Chrome"),
+      linux: path.join(home, ".config", "google-chrome"),
+      win32: path.join(process.env.LOCALAPPDATA ?? path.join(home, "AppData", "Local"), "Google", "Chrome", "User Data")
+    },
+    beta: {
+      darwin: path.join(home, "Library", "Application Support", "Google", "Chrome Beta"),
+      linux: path.join(home, ".config", "google-chrome-beta"),
+      win32: path.join(process.env.LOCALAPPDATA ?? path.join(home, "AppData", "Local"), "Google", "Chrome Beta", "User Data")
+    },
+    canary: {
+      darwin: path.join(home, "Library", "Application Support", "Google", "Chrome Canary"),
+      linux: path.join(home, ".config", "google-chrome-canary"),
+      win32: path.join(process.env.LOCALAPPDATA ?? path.join(home, "AppData", "Local"), "Google", "Chrome SxS", "User Data")
+    },
+    dev: {
+      darwin: path.join(home, "Library", "Application Support", "Google", "Chrome Dev"),
+      linux: path.join(home, ".config", "google-chrome-dev"),
+      win32: path.join(process.env.LOCALAPPDATA ?? path.join(home, "AppData", "Local"), "Google", "Chrome Dev", "User Data")
+    }
+  };
+  const platform = process.platform === "darwin" ? "darwin" : process.platform === "win32" ? "win32" : "linux";
+  for (const ch of channels) {
+    const entry = channelDirs[ch];
+    if (entry)
+      dirs.push(entry[platform]);
+  }
+  return dirs;
+}
+async function discoverRunningChromeDebugPort(options = {}) {
+  const channels = options.channels ?? ["stable", "beta", "canary", "dev"];
+  const timeoutMs = options.timeoutMs ?? 3000;
+  const userDataDirs = (options.userDataDirs ?? getDefaultChromeUserDataDirs(channels)).map((dir) => path.resolve(dir));
+  for (const dir of userDataDirs) {
+    const parsed = parseDevToolsActivePort(path.join(dir, "DevToolsActivePort"));
+    if (!parsed)
+      continue;
+    if (await isPortListening(parsed.port, timeoutMs)) {
+      return { port: parsed.port, wsUrl: `ws://127.0.0.1:${parsed.port}${parsed.wsPath}` };
+    }
+  }
+  if (process.platform !== "win32") {
+    try {
+      const result = spawnSync("ps", ["aux"], { encoding: "utf-8", timeout: 5000 });
+      if (result.status === 0 && result.stdout) {
+        const lines = result.stdout.split(`
+`).filter((line) => line.includes("--remote-debugging-port=") && userDataDirs.some((dir) => line.includes(dir)));
+        for (const line of lines) {
+          const portMatch = line.match(/--remote-debugging-port=(\d+)/);
+          const port = Number.parseInt(portMatch?.[1] ?? "", 10);
+          if (port > 0 && await isDebugPortReady(port, timeoutMs)) {
+            try {
+              const version = await fetchJson(`http://127.0.0.1:${port}/json/version`, { timeoutMs });
+              if (version.webSocketDebuggerUrl)
+                return { port, wsUrl: version.webSocketDebuggerUrl };
+            } catch {}
+          }
+        }
+      }
+    } catch {}
+  }
+  return null;
+}
+async function waitForChromeDebugPort(port, timeoutMs, options) {
+  const start = Date.now();
+  let lastError = null;
+  while (Date.now() - start < timeoutMs) {
+    try {
+      const version = await fetchJson(`http://127.0.0.1:${port}/json/version`, { timeoutMs: 5000 });
+      if (version.webSocketDebuggerUrl)
+        return version.webSocketDebuggerUrl;
+      lastError = new Error("Missing webSocketDebuggerUrl");
+    } catch (error) {
+      lastError = error;
+    }
+    await sleep(200);
+  }
+  if (options?.includeLastError && lastError) {
+    throw new Error(`Chrome debug port not ready: ${lastError instanceof Error ? lastError.message : String(lastError)}`);
+  }
+  throw new Error("Chrome debug port not ready");
+}
+
+class CdpConnection {
+  ws;
+  nextId = 0;
+  pending = new Map;
+  eventHandlers = new Map;
+  defaultTimeoutMs;
+  constructor(ws, defaultTimeoutMs = 15000) {
+    this.ws = ws;
+    this.defaultTimeoutMs = defaultTimeoutMs;
+    this.ws.addEventListener("message", (event) => {
+      try {
+        const data = typeof event.data === "string" ? event.data : new TextDecoder().decode(event.data);
+        const msg = JSON.parse(data);
+        if (msg.method) {
+          const handlers = this.eventHandlers.get(msg.method);
+          if (handlers) {
+            handlers.forEach((handler) => handler(msg.params));
+          }
+        }
+        if (msg.id) {
+          const pending = this.pending.get(msg.id);
+          if (pending) {
+            this.pending.delete(msg.id);
+            if (pending.timer)
+              clearTimeout(pending.timer);
+            if (msg.error?.message)
+              pending.reject(new Error(msg.error.message));
+            else
+              pending.resolve(msg.result);
+          }
+        }
+      } catch {}
+    });
+    this.ws.addEventListener("close", () => {
+      for (const [id, pending] of this.pending.entries()) {
+        this.pending.delete(id);
+        if (pending.timer)
+          clearTimeout(pending.timer);
+        pending.reject(new Error("CDP connection closed."));
+      }
+    });
+  }
+  static async connect(url, timeoutMs, options) {
+    const ws = new WebSocket(url);
+    await new Promise((resolve, reject) => {
+      const timer = setTimeout(() => reject(new Error("CDP connection timeout.")), timeoutMs);
+      ws.addEventListener("open", () => {
+        clearTimeout(timer);
+        resolve();
+      });
+      ws.addEventListener("error", () => {
+        clearTimeout(timer);
+        reject(new Error("CDP connection failed."));
+      });
+    });
+    return new CdpConnection(ws, options?.defaultTimeoutMs ?? 15000);
+  }
+  on(method, handler) {
+    if (!this.eventHandlers.has(method)) {
+      this.eventHandlers.set(method, new Set);
+    }
+    this.eventHandlers.get(method)?.add(handler);
+  }
+  off(method, handler) {
+    this.eventHandlers.get(method)?.delete(handler);
+  }
+  async send(method, params, options) {
+    const id = ++this.nextId;
+    const message = { id, method };
+    if (params)
+      message.params = params;
+    if (options?.sessionId)
+      message.sessionId = options.sessionId;
+    const timeoutMs = options?.timeoutMs ?? this.defaultTimeoutMs;
+    const result = await new Promise((resolve, reject) => {
+      const timer = timeoutMs > 0 ? setTimeout(() => {
+        this.pending.delete(id);
+        reject(new Error(`CDP timeout: ${method}`));
+      }, timeoutMs) : null;
+      this.pending.set(id, { resolve, reject, timer });
+      this.ws.send(JSON.stringify(message));
+    });
+    return result;
+  }
+  close() {
+    try {
+      this.ws.close();
+    } catch {}
+  }
+}
+async function launchChrome(options) {
+  await fs.promises.mkdir(options.profileDir, { recursive: true });
+  const args = [
+    `--remote-debugging-port=${options.port}`,
+    `--user-data-dir=${options.profileDir}`,
+    "--no-first-run",
+    "--no-default-browser-check",
+    ...options.extraArgs ?? []
+  ];
+  if (options.headless)
+    args.push("--headless=new");
+  if (options.url)
+    args.push(options.url);
+  return spawn(options.chromePath, args, { stdio: "ignore" });
+}
+function killChrome(chrome) {
+  try {
+    chrome.kill("SIGTERM");
+  } catch {}
+  setTimeout(() => {
+    if (chrome.exitCode === null && chrome.signalCode === null) {
+      try {
+        chrome.kill("SIGKILL");
+      } catch {}
+    }
+  }, 2000).unref?.();
+}
+async function gracefulKillChrome(chrome, port, timeoutMs = 6000) {
+  if (chrome.exitCode !== null || chrome.signalCode !== null)
+    return;
+  const exitPromise = new Promise((resolve) => {
+    chrome.once("exit", () => resolve());
+  });
+  killChrome(chrome);
+  const start = Date.now();
+  while (Date.now() - start < timeoutMs) {
+    if (chrome.exitCode !== null || chrome.signalCode !== null)
+      return;
+    if (port !== undefined && !await isPortListening(port, 250))
+      return;
+    const exited = await Promise.race([
+      exitPromise.then(() => true),
+      sleep(100).then(() => false)
+    ]);
+    if (exited)
+      return;
+  }
+  await Promise.race([
+    exitPromise,
+    sleep(250)
+  ]);
+}
+async function openPageSession(options) {
+  let targetId;
+  let createdTarget = false;
+  if (options.reusing) {
+    const created = await options.cdp.send("Target.createTarget", { url: options.url });
+    targetId = created.targetId;
+    createdTarget = true;
+  } else {
+    const targets = await options.cdp.send("Target.getTargets");
+    const existing = targets.targetInfos.find(options.matchTarget);
+    if (existing) {
+      targetId = existing.targetId;
+    } else {
+      const created = await options.cdp.send("Target.createTarget", { url: options.url });
+      targetId = created.targetId;
+      createdTarget = true;
+    }
+  }
+  const { sessionId } = await options.cdp.send("Target.attachToTarget", { targetId, flatten: true });
+  if (options.activateTarget ?? true) {
+    await options.cdp.send("Target.activateTarget", { targetId });
+  }
+  if (options.enablePage)
+    await options.cdp.send("Page.enable", {}, { sessionId });
+  if (options.enableRuntime)
+    await options.cdp.send("Runtime.enable", {}, { sessionId });
+  if (options.enableDom)
+    await options.cdp.send("DOM.enable", {}, { sessionId });
+  if (options.enableNetwork)
+    await options.cdp.send("Network.enable", {}, { sessionId });
+  return { sessionId, targetId, createdTarget };
+}
+export {
+  waitForChromeDebugPort,
+  sleep,
+  resolveSharedChromeProfileDir,
+  openPageSession,
+  launchChrome,
+  killChrome,
+  gracefulKillChrome,
+  getFreePort,
+  getDefaultChromeUserDataDirs,
+  findExistingChromeDebugPort,
+  findChromeExecutable,
+  discoverRunningChromeDebugPort,
+  CdpConnection
+};

packages/baoyu-chrome-cdp/package.json

@@ -0,0 +1,42 @@
+{
+  "name": "baoyu-chrome-cdp",
+  "version": "0.1.0",
+  "type": "module",
+  "files": [
+    "dist",
+    "src/**/*.ts",
+    "!src/**/*.test.ts"
+  ],
+  "exports": {
+    ".": {
+      "types": "./src/index.ts",
+      "import": "./dist/index.js",
+      "require": "./dist/index.cjs",
+      "default": "./dist/index.js"
+    },
+    "./src/*": "./src/*"
+  },
+  "description": "Shared Chrome DevTools Protocol utilities for baoyu skills.",
+  "main": "./dist/index.cjs",
+  "module": "./dist/index.js",
+  "types": "./src/index.ts",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/JimLiu/baoyu-skills.git",
+    "directory": "packages/baoyu-chrome-cdp"
+  },
+  "bugs": {
+    "url": "https://github.com/JimLiu/baoyu-skills/issues"
+  },
+  "homepage": "https://github.com/JimLiu/baoyu-skills/tree/main/packages/baoyu-chrome-cdp#readme",
+  "publishConfig": {
+    "access": "public"
+  },
+  "scripts": {
+    "build": "node ../../scripts/build-shared-package.mjs",
+    "prepack": "bun run build"
+  },
+  "engines": {
+    "bun": ">=1.2.0"
+  }
+}

packages/baoyu-chrome-cdp/src/index.test.ts

@@ -0,0 +1,362 @@
+import assert from "node:assert/strict";
+import { spawn, type ChildProcess } from "node:child_process";
+import fs from "node:fs/promises";
+import http from "node:http";
+import os from "node:os";
+import path from "node:path";
+import process from "node:process";
+import test, { type TestContext } from "node:test";
+
+import {
+  discoverRunningChromeDebugPort,
+  findChromeExecutable,
+  findExistingChromeDebugPort,
+  gracefulKillChrome,
+  getFreePort,
+  openPageSession,
+  resolveSharedChromeProfileDir,
+  waitForChromeDebugPort,
+} from "./index.ts";
+
+function useEnv(
+  t: TestContext,
+  values: Record<string, string | null>,
+): void {
+  const previous = new Map<string, string | undefined>();
+  for (const [key, value] of Object.entries(values)) {
+    previous.set(key, process.env[key]);
+    if (value == null) {
+      delete process.env[key];
+    } else {
+      process.env[key] = value;
+    }
+  }
+
+  t.after(() => {
+    for (const [key, value] of previous.entries()) {
+      if (value == null) {
+        delete process.env[key];
+      } else {
+        process.env[key] = value;
+      }
+    }
+  });
+}
+
+async function makeTempDir(prefix: string): Promise<string> {
+  return fs.mkdtemp(path.join(os.tmpdir(), prefix));
+}
+
+async function startDebugServer(port: number): Promise<http.Server> {
+  const server = http.createServer((req, res) => {
+    if (req.url === "/json/version") {
+      res.writeHead(200, { "Content-Type": "application/json" });
+      res.end(JSON.stringify({
+        webSocketDebuggerUrl: `ws://127.0.0.1:${port}/devtools/browser/demo`,
+      }));
+      return;
+    }
+
+    res.writeHead(404);
+    res.end();
+  });
+
+  await new Promise<void>((resolve, reject) => {
+    server.once("error", reject);
+    server.listen(port, "127.0.0.1", () => resolve());
+  });
+
+  return server;
+}
+
+async function closeServer(server: http.Server): Promise<void> {
+  await new Promise<void>((resolve, reject) => {
+    server.close((error) => {
+      if (error) reject(error);
+      else resolve();
+    });
+  });
+}
+
+function shellPathForPlatform(): string | null {
+  if (process.platform === "win32") return null;
+  return "/bin/bash";
+}
+
+async function startFakeChromiumProcess(port: number): Promise<ChildProcess | null> {
+  const shell = shellPathForPlatform();
+  if (!shell) return null;
+
+  const child = spawn(
+    shell,
+    [
+      "-lc",
+      `exec -a chromium-mock ${JSON.stringify(process.execPath)} -e 'setInterval(() => {}, 1000)' -- --remote-debugging-port=${port}`,
+    ],
+    { stdio: "ignore" },
+  );
+
+  await new Promise((resolve) => setTimeout(resolve, 250));
+  return child;
+}
+
+async function stopProcess(child: ChildProcess | null): Promise<void> {
+  if (!child) return;
+  if (child.exitCode !== null || child.signalCode !== null) return;
+
+  child.kill("SIGTERM");
+  await new Promise((resolve) => setTimeout(resolve, 100));
+  if (child.exitCode === null && child.signalCode === null) child.kill("SIGKILL");
+  if (child.exitCode !== null || child.signalCode !== null) return;
+  await new Promise((resolve) => child.once("exit", resolve));
+}
+
+async function startPortHoldingProcess(port: number): Promise<ChildProcess> {
+  const child = spawn(
+    process.execPath,
+    [
+      "-e",
+      `
+        const http = require("node:http");
+        const port = Number(process.argv[1]);
+        const server = http.createServer((_req, res) => res.end("ok"));
+        server.listen(port, "127.0.0.1", () => process.stdout.write("ready\\n"));
+        setInterval(() => {}, 1000);
+      `,
+      String(port),
+    ],
+    {
+      stdio: ["ignore", "pipe", "ignore"],
+    },
+  );
+
+  await new Promise<void>((resolve, reject) => {
+    const timer = setTimeout(() => reject(new Error("Timed out waiting for child server to start.")), 3_000);
+    child.once("error", (error) => {
+      clearTimeout(timer);
+      reject(error);
+    });
+    child.stdout?.once("data", () => {
+      clearTimeout(timer);
+      resolve();
+    });
+    child.once("exit", () => {
+      clearTimeout(timer);
+      reject(new Error("Child server exited before becoming ready."));
+    });
+  });
+
+  return child;
+}
+
+test("getFreePort honors a fixed environment override and otherwise allocates a TCP port", async (t) => {
+  useEnv(t, { TEST_FIXED_PORT: "45678" });
+  assert.equal(await getFreePort("TEST_FIXED_PORT"), 45678);
+
+  const dynamicPort = await getFreePort();
+  assert.ok(Number.isInteger(dynamicPort));
+  assert.ok(dynamicPort > 0);
+});
+
+test("findChromeExecutable prefers env overrides and falls back to candidate paths", async (t) => {
+  const root = await makeTempDir("baoyu-chrome-bin-");
+  t.after(() => fs.rm(root, { recursive: true, force: true }));
+
+  const envChrome = path.join(root, "env-chrome");
+  const fallbackChrome = path.join(root, "fallback-chrome");
+  await fs.writeFile(envChrome, "");
+  await fs.writeFile(fallbackChrome, "");
+
+  useEnv(t, { BAOYU_CHROME_PATH: envChrome });
+  assert.equal(
+    findChromeExecutable({
+      envNames: ["BAOYU_CHROME_PATH"],
+      candidates: { default: [fallbackChrome] },
+    }),
+    envChrome,
+  );
+
+  useEnv(t, { BAOYU_CHROME_PATH: null });
+  assert.equal(
+    findChromeExecutable({
+      envNames: ["BAOYU_CHROME_PATH"],
+      candidates: { default: [fallbackChrome] },
+    }),
+    fallbackChrome,
+  );
+});
+
+test("resolveSharedChromeProfileDir supports env overrides, WSL paths, and default suffixes", (t) => {
+  useEnv(t, { BAOYU_SHARED_PROFILE: "/tmp/custom-profile" });
+  assert.equal(
+    resolveSharedChromeProfileDir({
+      envNames: ["BAOYU_SHARED_PROFILE"],
+      appDataDirName: "demo-app",
+      profileDirName: "demo-profile",
+    }),
+    path.resolve("/tmp/custom-profile"),
+  );
+
+  useEnv(t, { BAOYU_SHARED_PROFILE: null });
+  assert.equal(
+    resolveSharedChromeProfileDir({
+      wslWindowsHome: "/mnt/c/Users/demo",
+      appDataDirName: "demo-app",
+      profileDirName: "demo-profile",
+    }),
+    path.join("/mnt/c/Users/demo", ".local", "share", "demo-app", "demo-profile"),
+  );
+
+  const fallback = resolveSharedChromeProfileDir({
+    appDataDirName: "demo-app",
+    profileDirName: "demo-profile",
+  });
+  assert.match(fallback, /demo-app[\\/]demo-profile$/);
+});
+
+test("findExistingChromeDebugPort reads DevToolsActivePort and validates it against a live endpoint", async (t) => {
+  const root = await makeTempDir("baoyu-cdp-profile-");
+  t.after(() => fs.rm(root, { recursive: true, force: true }));
+
+  const port = await getFreePort();
+  const server = await startDebugServer(port);
+  t.after(() => closeServer(server));
+
+  await fs.writeFile(path.join(root, "DevToolsActivePort"), `${port}\n/devtools/browser/demo\n`);
+
+  const found = await findExistingChromeDebugPort({ profileDir: root, timeoutMs: 1000 });
+  assert.equal(found, port);
+});
+
+test("discoverRunningChromeDebugPort reads DevToolsActivePort from the provided user-data dir", async (t) => {
+  const root = await makeTempDir("baoyu-cdp-user-data-");
+  t.after(() => fs.rm(root, { recursive: true, force: true }));
+
+  const port = await getFreePort();
+  const server = await startDebugServer(port);
+  t.after(() => closeServer(server));
+
+  await fs.writeFile(path.join(root, "DevToolsActivePort"), `${port}\n/devtools/browser/demo\n`);
+
+  const found = await discoverRunningChromeDebugPort({
+    userDataDirs: [root],
+    timeoutMs: 1000,
+  });
+  assert.deepEqual(found, {
+    port,
+    wsUrl: `ws://127.0.0.1:${port}/devtools/browser/demo`,
+  });
+});
+
+test("discoverRunningChromeDebugPort ignores unrelated debugging processes", async (t) => {
+  if (process.platform === "win32") {
+    t.skip("Process discovery fallback is not used on Windows.");
+    return;
+  }
+
+  const root = await makeTempDir("baoyu-cdp-user-data-");
+  t.after(() => fs.rm(root, { recursive: true, force: true }));
+
+  const port = await getFreePort();
+  const server = await startDebugServer(port);
+  t.after(() => closeServer(server));
+
+  const fakeChromium = await startFakeChromiumProcess(port);
+  t.after(async () => { await stopProcess(fakeChromium); });
+
+  const found = await discoverRunningChromeDebugPort({
+    userDataDirs: [root],
+    timeoutMs: 1000,
+  });
+  assert.equal(found, null);
+});
+
+test("openPageSession reports whether it created a new target", async () => {
+  const calls: string[] = [];
+  const cdpExisting = {
+    send: async <T>(method: string): Promise<T> => {
+      calls.push(method);
+      if (method === "Target.getTargets") {
+        return {
+          targetInfos: [{ targetId: "existing-target", type: "page", url: "https://gemini.google.com/app" }],
+        } as T;
+      }
+      if (method === "Target.attachToTarget") return { sessionId: "session-existing" } as T;
+      throw new Error(`Unexpected method: ${method}`);
+    },
+  };
+
+  const existing = await openPageSession({
+    cdp: cdpExisting as never,
+    reusing: false,
+    url: "https://gemini.google.com/app",
+    matchTarget: (target) => target.url.includes("gemini.google.com"),
+    activateTarget: false,
+  });
+
+  assert.deepEqual(existing, {
+    sessionId: "session-existing",
+    targetId: "existing-target",
+    createdTarget: false,
+  });
+  assert.deepEqual(calls, ["Target.getTargets", "Target.attachToTarget"]);
+
+  const createCalls: string[] = [];
+  const cdpCreated = {
+    send: async <T>(method: string): Promise<T> => {
+      createCalls.push(method);
+      if (method === "Target.getTargets") return { targetInfos: [] } as T;
+      if (method === "Target.createTarget") return { targetId: "created-target" } as T;
+      if (method === "Target.attachToTarget") return { sessionId: "session-created" } as T;
+      throw new Error(`Unexpected method: ${method}`);
+    },
+  };
+
+  const created = await openPageSession({
+    cdp: cdpCreated as never,
+    reusing: false,
+    url: "https://gemini.google.com/app",
+    matchTarget: (target) => target.url.includes("gemini.google.com"),
+    activateTarget: false,
+  });
+
+  assert.deepEqual(created, {
+    sessionId: "session-created",
+    targetId: "created-target",
+    createdTarget: true,
+  });
+  assert.deepEqual(createCalls, ["Target.getTargets", "Target.createTarget", "Target.attachToTarget"]);
+});
+
+test("waitForChromeDebugPort retries until the debug endpoint becomes available", async (t) => {
+  const port = await getFreePort();
+
+  const serverPromise = (async () => {
+    await new Promise((resolve) => setTimeout(resolve, 200));
+    const server = await startDebugServer(port);
+    t.after(() => closeServer(server));
+  })();
+
+  const websocketUrl = await waitForChromeDebugPort(port, 4000, {
+    includeLastError: true,
+  });
+  await serverPromise;
+
+  assert.equal(websocketUrl, `ws://127.0.0.1:${port}/devtools/browser/demo`);
+});
+
+test("gracefulKillChrome waits for the Chrome process to exit and release its port", async (t) => {
+  const port = await getFreePort();
+  const child = await startPortHoldingProcess(port);
+  t.after(async () => { await stopProcess(child); });
+
+  assert.equal(await waitForChromeDebugPort(port, 1_000).catch(() => null), null);
+
+  await gracefulKillChrome(child, port, 4_000);
+
+  assert.ok(child.exitCode !== null || child.signalCode !== null);
+  assert.equal(
+    await fetch(`http://127.0.0.1:${port}`).then(() => true).catch(() => false),
+    false,
+  );
+});

packages/baoyu-chrome-cdp/src/index.ts

@@ -0,0 +1,554 @@
+import { spawn, spawnSync, type ChildProcess } from "node:child_process";
+import fs from "node:fs";
+import net from "node:net";
+import os from "node:os";
+import path from "node:path";
+import process from "node:process";
+
+export type PlatformCandidates = {
+  darwin?: string[];
+  win32?: string[];
+  default: string[];
+};
+
+type PendingRequest = {
+  resolve: (value: unknown) => void;
+  reject: (error: Error) => void;
+  timer: ReturnType<typeof setTimeout> | null;
+};
+
+type CdpSendOptions = {
+  sessionId?: string;
+  timeoutMs?: number;
+};
+
+type FetchJsonOptions = {
+  timeoutMs?: number;
+};
+
+type FindChromeExecutableOptions = {
+  candidates: PlatformCandidates;
+  envNames?: string[];
+};
+
+type ResolveSharedChromeProfileDirOptions = {
+  envNames?: string[];
+  appDataDirName?: string;
+  profileDirName?: string;
+  wslWindowsHome?: string | null;
+};
+
+type FindExistingChromeDebugPortOptions = {
+  profileDir: string;
+  timeoutMs?: number;
+};
+
+export type ChromeChannel = "stable" | "beta" | "canary" | "dev";
+
+export type DiscoveredChrome = {
+  port: number;
+  wsUrl: string;
+};
+
+type DiscoverRunningChromeOptions = {
+  channels?: ChromeChannel[];
+  userDataDirs?: string[];
+  timeoutMs?: number;
+};
+
+type LaunchChromeOptions = {
+  chromePath: string;
+  profileDir: string;
+  port: number;
+  url?: string;
+  headless?: boolean;
+  extraArgs?: string[];
+};
+
+type ChromeTargetInfo = {
+  targetId: string;
+  url: string;
+  type: string;
+};
+
+type OpenPageSessionOptions = {
+  cdp: CdpConnection;
+  reusing: boolean;
+  url: string;
+  matchTarget: (target: ChromeTargetInfo) => boolean;
+  enablePage?: boolean;
+  enableRuntime?: boolean;
+  enableDom?: boolean;
+  enableNetwork?: boolean;
+  activateTarget?: boolean;
+};
+
+export type PageSession = {
+  sessionId: string;
+  targetId: string;
+  createdTarget: boolean;
+};
+
+export function sleep(ms: number): Promise<void> {
+  return new Promise((resolve) => setTimeout(resolve, ms));
+}
+
+export async function getFreePort(fixedEnvName?: string): Promise<number> {
+  const fixed = fixedEnvName ? Number.parseInt(process.env[fixedEnvName] ?? "", 10) : NaN;
+  if (Number.isInteger(fixed) && fixed > 0) return fixed;
+
+  return await new Promise((resolve, reject) => {
+    const server = net.createServer();
+    server.unref();
+    server.on("error", reject);
+    server.listen(0, "127.0.0.1", () => {
+      const address = server.address();
+      if (!address || typeof address === "string") {
+        server.close(() => reject(new Error("Unable to allocate a free TCP port.")));
+        return;
+      }
+      const port = address.port;
+      server.close((err) => {
+        if (err) reject(err);
+        else resolve(port);
+      });
+    });
+  });
+}
+
+export function findChromeExecutable(options: FindChromeExecutableOptions): string | undefined {
+  for (const envName of options.envNames ?? []) {
+    const override = process.env[envName]?.trim();
+    if (override && fs.existsSync(override)) return override;
+  }
+
+  const candidates = process.platform === "darwin"
+    ? options.candidates.darwin ?? options.candidates.default
+    : process.platform === "win32"
+      ? options.candidates.win32 ?? options.candidates.default
+      : options.candidates.default;
+
+  for (const candidate of candidates) {
+    if (fs.existsSync(candidate)) return candidate;
+  }
+  return undefined;
+}
+
+export function resolveSharedChromeProfileDir(options: ResolveSharedChromeProfileDirOptions = {}): string {
+  for (const envName of options.envNames ?? []) {
+    const override = process.env[envName]?.trim();
+    if (override) return path.resolve(override);
+  }
+
+  const appDataDirName = options.appDataDirName ?? "baoyu-skills";
+  const profileDirName = options.profileDirName ?? "chrome-profile";
+
+  if (options.wslWindowsHome) {
+    return path.join(options.wslWindowsHome, ".local", "share", appDataDirName, profileDirName);
+  }
+
+  const base = process.platform === "darwin"
+    ? path.join(os.homedir(), "Library", "Application Support")
+    : process.platform === "win32"
+      ? (process.env.APPDATA ?? path.join(os.homedir(), "AppData", "Roaming"))
+      : (process.env.XDG_DATA_HOME ?? path.join(os.homedir(), ".local", "share"));
+  return path.join(base, appDataDirName, profileDirName);
+}
+
+async function fetchWithTimeout(url: string, timeoutMs?: number): Promise<Response> {
+  if (!timeoutMs || timeoutMs <= 0) return await fetch(url, { redirect: "follow" });
+
+  const ctl = new AbortController();
+  const timer = setTimeout(() => ctl.abort(), timeoutMs);
+  try {
+    return await fetch(url, { redirect: "follow", signal: ctl.signal });
+  } finally {
+    clearTimeout(timer);
+  }
+}
+
+async function fetchJson<T = unknown>(url: string, options: FetchJsonOptions = {}): Promise<T> {
+  const response = await fetchWithTimeout(url, options.timeoutMs);
+  if (!response.ok) {
+    throw new Error(`Request failed: ${response.status} ${response.statusText}`);
+  }
+  return await response.json() as T;
+}
+
+async function isDebugPortReady(port: number, timeoutMs = 3_000): Promise<boolean> {
+  try {
+    const version = await fetchJson<{ webSocketDebuggerUrl?: string }>(
+      `http://127.0.0.1:${port}/json/version`,
+      { timeoutMs }
+    );
+    return !!version.webSocketDebuggerUrl;
+  } catch {
+    return false;
+  }
+}
+
+function isPortListening(port: number, timeoutMs = 3_000): Promise<boolean> {
+  return new Promise((resolve) => {
+    const socket = new net.Socket();
+    const timer = setTimeout(() => { socket.destroy(); resolve(false); }, timeoutMs);
+    socket.once("connect", () => { clearTimeout(timer); socket.destroy(); resolve(true); });
+    socket.once("error", () => { clearTimeout(timer); resolve(false); });
+    socket.connect(port, "127.0.0.1");
+  });
+}
+
+function parseDevToolsActivePort(filePath: string): { port: number; wsPath: string } | null {
+  try {
+    const content = fs.readFileSync(filePath, "utf-8");
+    const lines = content.split(/\r?\n/);
+    const port = Number.parseInt(lines[0]?.trim() ?? "", 10);
+    const wsPath = lines[1]?.trim();
+    if (port > 0 && wsPath) return { port, wsPath };
+  } catch {}
+  return null;
+}
+
+export async function findExistingChromeDebugPort(options: FindExistingChromeDebugPortOptions): Promise<number | null> {
+  const timeoutMs = options.timeoutMs ?? 3_000;
+  const parsed = parseDevToolsActivePort(path.join(options.profileDir, "DevToolsActivePort"));
+
+  if (parsed && parsed.port > 0 && await isDebugPortReady(parsed.port, timeoutMs)) return parsed.port;
+
+  if (process.platform === "win32") return null;
+
+  try {
+    const result = spawnSync("ps", ["aux"], { encoding: "utf-8", timeout: 5_000 });
+    if (result.status !== 0 || !result.stdout) return null;
+
+    const lines = result.stdout
+      .split("\n")
+      .filter((line) => line.includes(options.profileDir) && line.includes("--remote-debugging-port="));
+
+    for (const line of lines) {
+      const portMatch = line.match(/--remote-debugging-port=(\d+)/);
+      const port = Number.parseInt(portMatch?.[1] ?? "", 10);
+      if (port > 0 && await isDebugPortReady(port, timeoutMs)) return port;
+    }
+  } catch {}
+
+  return null;
+}
+
+export function getDefaultChromeUserDataDirs(channels: ChromeChannel[] = ["stable"]): string[] {
+  const home = os.homedir();
+  const dirs: string[] = [];
+
+  const channelDirs: Record<string, { darwin: string; linux: string; win32: string }> = {
+    stable: {
+      darwin: path.join(home, "Library", "Application Support", "Google", "Chrome"),
+      linux: path.join(home, ".config", "google-chrome"),
+      win32: path.join(process.env.LOCALAPPDATA ?? path.join(home, "AppData", "Local"), "Google", "Chrome", "User Data"),
+    },
+    beta: {
+      darwin: path.join(home, "Library", "Application Support", "Google", "Chrome Beta"),
+      linux: path.join(home, ".config", "google-chrome-beta"),
+      win32: path.join(process.env.LOCALAPPDATA ?? path.join(home, "AppData", "Local"), "Google", "Chrome Beta", "User Data"),
+    },
+    canary: {
+      darwin: path.join(home, "Library", "Application Support", "Google", "Chrome Canary"),
+      linux: path.join(home, ".config", "google-chrome-canary"),
+      win32: path.join(process.env.LOCALAPPDATA ?? path.join(home, "AppData", "Local"), "Google", "Chrome SxS", "User Data"),
+    },
+    dev: {
+      darwin: path.join(home, "Library", "Application Support", "Google", "Chrome Dev"),
+      linux: path.join(home, ".config", "google-chrome-dev"),
+      win32: path.join(process.env.LOCALAPPDATA ?? path.join(home, "AppData", "Local"), "Google", "Chrome Dev", "User Data"),
+    },
+  };
+
+  const platform = process.platform === "darwin" ? "darwin" : process.platform === "win32" ? "win32" : "linux";
+
+  for (const ch of channels) {
+    const entry = channelDirs[ch];
+    if (entry) dirs.push(entry[platform]);
+  }
+
+  return dirs;
+}
+
+// Best-effort reuse of an already-running local CDP session discovered from
+// known Chrome user-data dirs. This is distinct from Chrome DevTools MCP's
+// prompt-based --autoConnect flow.
+export async function discoverRunningChromeDebugPort(options: DiscoverRunningChromeOptions = {}): Promise<DiscoveredChrome | null> {
+  const channels = options.channels ?? ["stable", "beta", "canary", "dev"];
+  const timeoutMs = options.timeoutMs ?? 3_000;
+
+  const userDataDirs = (options.userDataDirs ?? getDefaultChromeUserDataDirs(channels))
+    .map((dir) => path.resolve(dir));
+  for (const dir of userDataDirs) {
+    const parsed = parseDevToolsActivePort(path.join(dir, "DevToolsActivePort"));
+    if (!parsed) continue;
+    if (await isPortListening(parsed.port, timeoutMs)) {
+      return { port: parsed.port, wsUrl: `ws://127.0.0.1:${parsed.port}${parsed.wsPath}` };
+    }
+  }
+
+  if (process.platform !== "win32") {
+    try {
+      const result = spawnSync("ps", ["aux"], { encoding: "utf-8", timeout: 5_000 });
+      if (result.status === 0 && result.stdout) {
+        const lines = result.stdout
+          .split("\n")
+          .filter((line) =>
+            line.includes("--remote-debugging-port=") &&
+            userDataDirs.some((dir) => line.includes(dir))
+          );
+
+        for (const line of lines) {
+          const portMatch = line.match(/--remote-debugging-port=(\d+)/);
+          const port = Number.parseInt(portMatch?.[1] ?? "", 10);
+          if (port > 0 && await isDebugPortReady(port, timeoutMs)) {
+            try {
+              const version = await fetchJson<{ webSocketDebuggerUrl?: string }>(`http://127.0.0.1:${port}/json/version`, { timeoutMs });
+              if (version.webSocketDebuggerUrl) return { port, wsUrl: version.webSocketDebuggerUrl };
+            } catch {}
+          }
+        }
+      }
+    } catch {}
+  }
+
+  return null;
+}
+
+export async function waitForChromeDebugPort(
+  port: number,
+  timeoutMs: number,
+  options?: { includeLastError?: boolean }
+): Promise<string> {
+  const start = Date.now();
+  let lastError: unknown = null;
+
+  while (Date.now() - start < timeoutMs) {
+    try {
+      const version = await fetchJson<{ webSocketDebuggerUrl?: string }>(
+        `http://127.0.0.1:${port}/json/version`,
+        { timeoutMs: 5_000 }
+      );
+      if (version.webSocketDebuggerUrl) return version.webSocketDebuggerUrl;
+      lastError = new Error("Missing webSocketDebuggerUrl");
+    } catch (error) {
+      lastError = error;
+    }
+    await sleep(200);
+  }
+
+  if (options?.includeLastError && lastError) {
+    throw new Error(
+      `Chrome debug port not ready: ${lastError instanceof Error ? lastError.message : String(lastError)}`
+    );
+  }
+  throw new Error("Chrome debug port not ready");
+}
+
+export class CdpConnection {
+  private ws: WebSocket;
+  private nextId = 0;
+  private pending = new Map<number, PendingRequest>();
+  private eventHandlers = new Map<string, Set<(params: unknown) => void>>();
+  private defaultTimeoutMs: number;
+
+  private constructor(ws: WebSocket, defaultTimeoutMs = 15_000) {
+    this.ws = ws;
+    this.defaultTimeoutMs = defaultTimeoutMs;
+
+    this.ws.addEventListener("message", (event) => {
+      try {
+        const data = typeof event.data === "string"
+          ? event.data
+          : new TextDecoder().decode(event.data as ArrayBuffer);
+        const msg = JSON.parse(data) as {
+          id?: number;
+          method?: string;
+          params?: unknown;
+          result?: unknown;
+          error?: { message?: string };
+        };
+
+        if (msg.method) {
+          const handlers = this.eventHandlers.get(msg.method);
+          if (handlers) {
+            handlers.forEach((handler) => handler(msg.params));
+          }
+        }
+
+        if (msg.id) {
+          const pending = this.pending.get(msg.id);
+          if (pending) {
+            this.pending.delete(msg.id);
+            if (pending.timer) clearTimeout(pending.timer);
+            if (msg.error?.message) pending.reject(new Error(msg.error.message));
+            else pending.resolve(msg.result);
+          }
+        }
+      } catch {}
+    });
+
+    this.ws.addEventListener("close", () => {
+      for (const [id, pending] of this.pending.entries()) {
+        this.pending.delete(id);
+        if (pending.timer) clearTimeout(pending.timer);
+        pending.reject(new Error("CDP connection closed."));
+      }
+    });
+  }
+
+  static async connect(
+    url: string,
+    timeoutMs: number,
+    options?: { defaultTimeoutMs?: number }
+  ): Promise<CdpConnection> {
+    const ws = new WebSocket(url);
+    await new Promise<void>((resolve, reject) => {
+      const timer = setTimeout(() => reject(new Error("CDP connection timeout.")), timeoutMs);
+      ws.addEventListener("open", () => {
+        clearTimeout(timer);
+        resolve();
+      });
+      ws.addEventListener("error", () => {
+        clearTimeout(timer);
+        reject(new Error("CDP connection failed."));
+      });
+    });
+    return new CdpConnection(ws, options?.defaultTimeoutMs ?? 15_000);
+  }
+
+  on(method: string, handler: (params: unknown) => void): void {
+    if (!this.eventHandlers.has(method)) {
+      this.eventHandlers.set(method, new Set());
+    }
+    this.eventHandlers.get(method)?.add(handler);
+  }
+
+  off(method: string, handler: (params: unknown) => void): void {
+    this.eventHandlers.get(method)?.delete(handler);
+  }
+
+  async send<T = unknown>(method: string, params?: Record<string, unknown>, options?: CdpSendOptions): Promise<T> {
+    const id = ++this.nextId;
+    const message: Record<string, unknown> = { id, method };
+    if (params) message.params = params;
+    if (options?.sessionId) message.sessionId = options.sessionId;
+
+    const timeoutMs = options?.timeoutMs ?? this.defaultTimeoutMs;
+    const result = await new Promise<unknown>((resolve, reject) => {
+      const timer = timeoutMs > 0
+        ? setTimeout(() => {
+          this.pending.delete(id);
+          reject(new Error(`CDP timeout: ${method}`));
+        }, timeoutMs)
+        : null;
+      this.pending.set(id, { resolve, reject, timer });
+      this.ws.send(JSON.stringify(message));
+    });
+
+    return result as T;
+  }
+
+  close(): void {
+    try {
+      this.ws.close();
+    } catch {}
+  }
+}
+
+export async function launchChrome(options: LaunchChromeOptions): Promise<ChildProcess> {
+  await fs.promises.mkdir(options.profileDir, { recursive: true });
+
+  const args = [
+    `--remote-debugging-port=${options.port}`,
+    `--user-data-dir=${options.profileDir}`,
+    "--no-first-run",
+    "--no-default-browser-check",
+    ...(options.extraArgs ?? []),
+  ];
+  if (options.headless) args.push("--headless=new");
+  if (options.url) args.push(options.url);
+
+  return spawn(options.chromePath, args, { stdio: "ignore" });
+}
+
+export function killChrome(chrome: ChildProcess): void {
+  try {
+    chrome.kill("SIGTERM");
+  } catch {}
+  setTimeout(() => {
+    if (chrome.exitCode === null && chrome.signalCode === null) {
+      try {
+        chrome.kill("SIGKILL");
+      } catch {}
+    }
+  }, 2_000).unref?.();
+}
+
+export async function gracefulKillChrome(
+  chrome: ChildProcess,
+  port?: number,
+  timeoutMs = 6_000,
+): Promise<void> {
+  if (chrome.exitCode !== null || chrome.signalCode !== null) return;
+
+  const exitPromise = new Promise<void>((resolve) => {
+    chrome.once("exit", () => resolve());
+  });
+
+  killChrome(chrome);
+
+  const start = Date.now();
+  while (Date.now() - start < timeoutMs) {
+    if (chrome.exitCode !== null || chrome.signalCode !== null) return;
+    if (port !== undefined && !await isPortListening(port, 250)) return;
+
+    const exited = await Promise.race([
+      exitPromise.then(() => true),
+      sleep(100).then(() => false),
+    ]);
+    if (exited) return;
+  }
+
+  await Promise.race([
+    exitPromise,
+    sleep(250),
+  ]);
+}
+
+export async function openPageSession(options: OpenPageSessionOptions): Promise<PageSession> {
+  let targetId: string;
+  let createdTarget = false;
+
+  if (options.reusing) {
+    const created = await options.cdp.send<{ targetId: string }>("Target.createTarget", { url: options.url });
+    targetId = created.targetId;
+    createdTarget = true;
+  } else {
+    const targets = await options.cdp.send<{ targetInfos: ChromeTargetInfo[] }>("Target.getTargets");
+    const existing = targets.targetInfos.find(options.matchTarget);
+    if (existing) {
+      targetId = existing.targetId;
+    } else {
+      const created = await options.cdp.send<{ targetId: string }>("Target.createTarget", { url: options.url });
+      targetId = created.targetId;
+      createdTarget = true;
+    }
+  }
+
+  const { sessionId } = await options.cdp.send<{ sessionId: string }>(
+    "Target.attachToTarget",
+    { targetId, flatten: true }
+  );
+
+  if (options.activateTarget ?? true) {
+    await options.cdp.send("Target.activateTarget", { targetId });
+  }
+  if (options.enablePage) await options.cdp.send("Page.enable", {}, { sessionId });
+  if (options.enableRuntime) await options.cdp.send("Runtime.enable", {}, { sessionId });
+  if (options.enableDom) await options.cdp.send("DOM.enable", {}, { sessionId });
+  if (options.enableNetwork) await options.cdp.send("Network.enable", {}, { sessionId });
+
+  return { sessionId, targetId, createdTarget };
+}

packages/baoyu-fetch/.changeset/README.md

@@ -0,0 +1,11 @@
+# Changesets
+
+This folder stores release notes for version bumps managed by Changesets.
+
+Create a new changeset before merging a user-facing change:
+
+```bash
+bunx changeset
+```
+
+After the changeset lands on `main`, GitHub Actions will open or update the release PR automatically. Merging that release PR publishes the next npm version.

packages/baoyu-fetch/.changeset/config.json

@@ -0,0 +1,11 @@
+{
+  "$schema": "https://unpkg.com/@changesets/config@3.1.3/schema.json",
+  "changelog": "@changesets/cli/changelog",
+  "commit": false,
+  "fixed": [],
+  "linked": [],
+  "access": "public",
+  "baseBranch": "main",
+  "updateInternalDependencies": "patch",
+  "ignore": []
+}

packages/baoyu-fetch/.changeset/remote-defuddle-fallback.md

@@ -0,0 +1,5 @@
+---
+"baoyu-reader": patch
+---
+
+Add a `defuddle.md` markdown fallback for generic extraction when the CLI is asked to produce markdown output.

packages/baoyu-fetch/.github/workflows/release.yml

@@ -0,0 +1,58 @@
+name: Release
+
+on:
+  push:
+    branches:
+      - main
+  workflow_dispatch:
+
+concurrency: ${{ github.workflow }}-${{ github.ref }}
+
+permissions:
+  contents: write
+  pull-requests: write
+  id-token: write
+
+jobs:
+  release:
+    runs-on: ubuntu-latest
+
+    steps:
+      - name: Checkout repository
+        uses: actions/checkout@v5
+        with:
+          fetch-depth: 0
+
+      - name: Setup Bun
+        uses: oven-sh/setup-bun@v2
+        with:
+          bun-version: 1.2.23
+
+      - name: Setup Node.js
+        uses: actions/setup-node@v6
+        with:
+          node-version: 24
+          registry-url: https://registry.npmjs.org
+
+      - name: Install dependencies
+        run: bun install --frozen-lockfile
+
+      - name: Type check
+        run: bun run check
+
+      - name: Test
+        run: bun test
+
+      - name: Verify npm package contents
+        run: npm pack --dry-run
+
+      - name: Create release PR or publish to npm
+        id: changesets
+        uses: changesets/action@v1
+        with:
+          version: bun run version-packages
+          publish: bun run release
+          commit: "chore: release"
+          title: "chore: release"
+        env:
+          GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}

packages/baoyu-fetch/.gitignore

@@ -0,0 +1,6 @@
+node_modules
+dist
+.DS_Store
+.debug
+coverage
+

packages/baoyu-fetch/CHANGELOG.md

@@ -0,0 +1,65 @@
+# Changelog
+
+English | [简体中文](./CHANGELOG.zh-CN.md)
+
+The format is inspired by Keep a Changelog, and the project follows Semantic
+Versioning.
+
+## [0.1.2] - 2026-04-21
+
+#### Changed
+
+- Upgraded Defuddle to 0.17.0 and jsdom to 29.0.2 for generic extraction.
+- Added an `@xmldom/xmldom` override to keep the optional Defuddle MathML
+  dependency chain on a non-vulnerable release.
+
+#### Fixed
+
+- Fixed X/Twitter video extraction for single posts and X Articles by selecting
+  the highest-bitrate MP4 variant instead of the preview image URL.
+- Fixed X Article media rendering so video entities are emitted as
+  `[video](...)` links instead of image embeds.
+
+## [0.1.1] - 2026-03-27
+
+#### Added
+
+- Added the `hn` adapter for Hacker News stories and comment threads.
+- Added `--download-media` and `--media-dir` to download extracted media and
+  rewrite Markdown links.
+- Added Defuddle as the first generic extraction pass, with Readability +
+  HTML-to-Markdown as fallback.
+- Added interactive wait modes for login and verification flows, including
+  manual verification handoff and force-wait resume behavior.
+- Added `--format markdown|json` while keeping `--json` as a compatibility
+  alias.
+- Added Changesets-based release automation for npm publishing.
+
+#### Changed
+
+- Renamed the package and CLI from `baoyu-markdown` to `baoyu-fetch`.
+- Changed the published package to run `src/cli.ts` directly with Bun instead of
+  shipping a prebuilt `dist`.
+- Improved X extraction for threads, articles, note tweets, embeds, image URLs,
+  login state handling, and media metadata.
+- Improved YouTube transcript extraction and normalized Markdown image output.
+
+#### Fixed
+
+- Fixed X note tweet URL expansion.
+- Fixed media URL normalization before download, including Substack media links.
+- Fixed foreground behavior for interactive flows so manual steps are easier to
+  complete.
+
+## [0.1.0] - 2026-03-25
+
+#### Added
+
+- Initial public release as `baoyu-markdown`.
+- Added Chrome CDP session management, controlled tabs, and network journaling.
+- Added built-in adapters for `x`, `youtube`, and the generic fallback.
+- Added X article parsing, X single/tweet extraction, and YouTube transcript
+  extraction.
+- Added Markdown rendering, document metadata output, and CLI support for file
+  output, JSON output, debug exports, custom Chrome connection settings,
+  headless mode, and timeout control.

packages/baoyu-fetch/CHANGELOG.zh-CN.md

@@ -0,0 +1,55 @@
+# 更新日志
+
+[English](./CHANGELOG.md) | 简体中文
+
+格式参考 Keep a Changelog，版本号遵循 Semantic Versioning。
+
+## [0.1.2] - 2026-04-21
+
+### 变更
+
+- 将 Defuddle 升级到 0.17.0、jsdom 升级到 29.0.2，用于通用页面提取。
+- 新增 `@xmldom/xmldom` override，使 Defuddle 的可选 MathML 依赖链保持在无漏洞版本。
+
+### 修复
+
+- 修复 X/Twitter 单条内容和 X Article 的视频提取逻辑，改为选择最高码率 MP4 变体，而不是预览图 URL。
+- 修复 X Article 媒体渲染，视频实体现在输出为 `[video](...)` 链接，而不是图片嵌入。
+
+## [0.1.1] - 2026-03-27
+
+### 新增
+
+- 新增 `hn` adapter，可提取 Hacker News 帖子与评论串。
+- 新增 `--download-media` 和 `--media-dir`，可下载提取出的媒体文件并重写
+  Markdown 链接。
+- 通用提取链路新增 Defuddle 首选路径，并保留 Readability + HTML to Markdown
+  作为回退方案。
+- 新增登录/验证场景的交互等待模式，支持手动验证接管和 force wait 自动恢复。
+- 新增 `--format markdown|json`，同时保留 `--json` 作为兼容别名。
+- 新增基于 Changesets 的 npm 发版自动化流程。
+
+### 变更
+
+- 将包名和 CLI 名称从 `baoyu-markdown` 更名为 `baoyu-fetch`。
+- npm 发布物改为直接以 Bun 执行 `src/cli.ts`，不再附带预构建的 `dist`。
+- 强化 X 提取链路，覆盖 thread、article、note tweet、embed、图片 URL、
+  登录态判断与媒体元数据。
+- 增强 YouTube transcript 提取，并规范化 Markdown 图片输出。
+
+### 修复
+
+- 修复 X note tweet 的 URL 展开问题。
+- 修复媒体下载前的 URL 规范化问题，包括 Substack 媒体链接。
+- 修复交互模式的前台行为，使手动登录/验证流程更稳定。
+
+## [0.1.0] - 2026-03-25
+
+### 新增
+
+- `baoyu-markdown` 的首个公开版本。
+- 新增 Chrome CDP 会话管理、受控 tab 与网络日志采集能力。
+- 新增内置 `x`、`youtube` 与通用 fallback adapters。
+- 新增 X article 解析、X 单条内容提取，以及 YouTube transcript 提取。
+- 新增 Markdown 渲染与文档元数据输出，并提供文件输出、JSON 输出、调试导出、
+  自定义 Chrome 连接、headless 模式和超时控制等 CLI 能力。

packages/baoyu-fetch/README.md

@@ -0,0 +1,124 @@
+# baoyu-fetch
+
+English | [简体中文](./README.zh-CN.md) | [Changelog](./CHANGELOG.md) | [中文更新日志](./CHANGELOG.zh-CN.md)
+
+`baoyu-fetch` is a Bun CLI built on Chrome CDP. Give it a URL and it returns
+high-quality `markdown` or `json`. When a site adapter matches, it prefers API
+responses or structured page data; otherwise it falls back to generic HTML
+extraction.
+
+## Features
+
+- Capture rendered page content through Chrome CDP
+- Observe network requests and responses, and fetch bodies when needed
+- Adapter registry that auto-selects a handler from the URL
+- Built-in adapters for `x`, `youtube`, and `hn`
+- Generic fallback: Defuddle first, then Readability + HTML-to-Markdown; when `--format markdown` is requested, it can also fall back to `defuddle.md`
+- Print `markdown` / `json` to stdout or save with `--output`
+- Optionally download extracted images or videos and rewrite Markdown links
+- Optional wait modes for login and verification flows
+- Chrome profile defaults to `baoyu-skills/chrome-profile`
+
+## Installation
+
+```bash
+bun install
+```
+
+For package usage, the quickest option is:
+
+```bash
+bunx baoyu-fetch https://example.com
+```
+
+You can also install it globally:
+
+```bash
+npm install -g baoyu-fetch
+```
+
+The npm package ships TypeScript source entrypoints instead of a prebuilt
+`dist`, so Bun is required at runtime.
+
+## Usage
+
+```bash
+bun run src/cli.ts https://example.com
+bunx baoyu-fetch https://example.com
+baoyu-fetch https://example.com
+baoyu-fetch https://example.com --format markdown --output article.md
+baoyu-fetch https://example.com --format markdown --output article.md --download-media
+baoyu-fetch https://x.com/jack/status/20 --format json --output article.json
+baoyu-fetch https://x.com/jack/status/20 --json
+baoyu-fetch https://x.com/jack/status/20 --wait-for interaction
+baoyu-fetch https://x.com/jack/status/20 --wait-for force
+baoyu-fetch https://x.com/jack/status/20 --chrome-profile-dir ~/Library/Application\\ Support/baoyu-skills/chrome-profile
+```
+
+## Options
+
+```bash
+baoyu-fetch <url> [options]
+
+Options:
+  --output <file>       Save output to file
+  --format <type>       Output format: markdown | json
+  --json                Alias for --format json
+  --adapter <name>      Force an adapter (for example x / hn / generic)
+  --download-media      Download adapter-reported media into ./imgs and ./videos, then rewrite markdown links
+  --media-dir <dir>     Base directory for downloaded media. Defaults to the output directory
+  --debug-dir <dir>     Write debug artifacts (html, document.json, network.json)
+  --cdp-url <url>       Reuse an existing Chrome DevTools endpoint
+  --browser-path <path> Explicit Chrome binary path
+  --chrome-profile-dir <path>
+                        Chrome user data dir. Defaults to BAOYU_CHROME_PROFILE_DIR
+                        or baoyu-skills/chrome-profile
+  --headless            Launch a temporary headless Chrome if needed
+  --wait-for <mode>     Wait mode: interaction | force
+  --wait-for-interaction
+                        Alias for --wait-for interaction
+  --wait-for-login      Alias for --wait-for interaction
+  --interaction-timeout <ms>
+                        Manual interaction timeout. Default: 600000
+  --interaction-poll-interval <ms>
+                        Poll interval while waiting. Default: 1500
+  --login-timeout <ms>  Alias for --interaction-timeout
+  --login-poll-interval <ms>
+                        Alias for --interaction-poll-interval
+  --timeout <ms>        Page load timeout. Default: 30000
+  --help                Show help
+```
+
+## How It Works
+
+1. The CLI parses the target URL and options.
+2. It opens or connects to a Chrome CDP session and creates a controlled tab.
+3. `NetworkJournal` records requests and responses.
+4. The adapter registry resolves a site-specific adapter when possible.
+5. The adapter returns a structured `ExtractedDocument`.
+6. If nothing matches, generic HTML extraction runs instead.
+7. The result is rendered as Markdown, or returned as JSON with both
+   `document` and `markdown`.
+
+## Development
+
+```bash
+bun run check
+bun run test
+bun run build
+```
+
+## Release
+
+When you make a user-visible change, add a changeset first:
+
+```bash
+bunx changeset
+```
+
+After the generated `.changeset/*.md` file lands on `main`, GitHub Actions will
+open or update the release PR. Merging that release PR publishes the package to
+npm.
+
+The publish flow does not build `dist`; it publishes `src/*.ts` for Bun
+execution directly.

packages/baoyu-fetch/README.zh-CN.md

@@ -0,0 +1,122 @@
+# baoyu-fetch
+
+[English](./README.md) | 简体中文 | [更新日志](./CHANGELOG.zh-CN.md) | [English Changelog](./CHANGELOG.md)
+
+`baoyu-fetch` 是一个基于 Chrome CDP 的 Bun CLI。输入 URL，它会输出高质量
+`markdown` 或 `json`；命中站点 adapter 时优先消费 API 返回或页面内结构化
+数据，未命中时回退到通用 HTML 提取。
+
+## 当前能力
+
+- 通过 Chrome CDP 抓取渲染后的页面内容
+- 监听网络请求与响应，按需拉取响应体
+- adapter registry，支持按 URL 自动命中站点处理器
+- 内置 `x`、`youtube`、`hn` adapters
+- 通用 fallback：Defuddle 优先，Readability + HTML to Markdown 回退；`--format markdown` 时会再尝试 `defuddle.md` 兜底
+- `stdout` 或 `--output` 输出 `markdown` / `json`
+- 可选下载提取出的图片/视频并重写 Markdown 链接
+- 提供登录/验证场景下的交互等待模式
+- Chrome profile 默认对齐 `baoyu-skills/chrome-profile`
+
+## 安装
+
+```bash
+bun install
+```
+
+作为包使用时，推荐直接这样运行：
+
+```bash
+bunx baoyu-fetch https://example.com
+```
+
+也可以全局安装：
+
+```bash
+npm install -g baoyu-fetch
+```
+
+npm 包发布的是 TypeScript 源码入口，不包含预编译的 `dist`，所以运行时需要
+Bun。
+
+## 用法
+
+```bash
+bun run src/cli.ts https://example.com
+bunx baoyu-fetch https://example.com
+baoyu-fetch https://example.com
+baoyu-fetch https://example.com --format markdown --output article.md
+baoyu-fetch https://example.com --format markdown --output article.md --download-media
+baoyu-fetch https://x.com/jack/status/20 --format json --output article.json
+baoyu-fetch https://x.com/jack/status/20 --json
+baoyu-fetch https://x.com/jack/status/20 --wait-for interaction
+baoyu-fetch https://x.com/jack/status/20 --wait-for force
+baoyu-fetch https://x.com/jack/status/20 --chrome-profile-dir ~/Library/Application\\ Support/baoyu-skills/chrome-profile
+```
+
+## 主要参数
+
+```bash
+baoyu-fetch <url> [options]
+
+Options:
+  --output <file>       保存输出内容到文件
+  --format <type>       输出格式：markdown | json
+  --json                `--format json` 的兼容别名
+  --adapter <name>      强制使用指定 adapter（如 x / hn / generic）
+  --download-media      下载 adapter 返回的媒体到 ./imgs 和 ./videos，并重写 markdown 链接
+  --media-dir <dir>     指定媒体下载根目录；默认使用输出文件所在目录
+  --debug-dir <dir>     导出调试信息（html、document.json、network.json）
+  --cdp-url <url>       连接现有 Chrome 调试地址
+  --browser-path <path> 指定 Chrome 可执行文件
+  --chrome-profile-dir <path>
+                        指定 Chrome profile 目录。默认使用 BAOYU_CHROME_PROFILE_DIR，
+                        否则回退到 baoyu-skills/chrome-profile
+  --headless            启动临时 headless Chrome（未连现有实例时）
+  --wait-for <mode>     等待模式：interaction | force
+  --wait-for-interaction
+                        `--wait-for interaction` 的别名
+  --wait-for-login      `--wait-for interaction` 的别名
+  --interaction-timeout <ms>
+                        手动交互等待超时，默认 600000
+  --interaction-poll-interval <ms>
+                        等待期间的轮询间隔，默认 1500
+  --login-timeout <ms>  `--interaction-timeout` 的别名
+  --login-poll-interval <ms>
+                        `--interaction-poll-interval` 的别名
+  --timeout <ms>        页面加载超时，默认 30000
+  --help                显示帮助
+```
+
+## 设计
+
+核心链路：
+
+1. CLI 解析 URL 和选项
+2. 建立 CDP 会话并创建受控 tab
+3. 启动 `NetworkJournal` 收集所有请求/响应
+4. 由 adapter registry 匹配站点 adapter
+5. adapter 返回结构化 `ExtractedDocument`
+6. 没命中则走通用 HTML 提取
+7. 按请求输出 Markdown，或输出包含 `document` 和 `markdown` 的 JSON
+
+## 开发
+
+```bash
+bun run check
+bun run test
+bun run build
+```
+
+## 发版
+
+新增用户可见改动后，先添加一个 changeset：
+
+```bash
+bunx changeset
+```
+
+把生成的 `.changeset/*.md` 一起合并到 `main` 后，GitHub Actions 会自动创建或
+更新 release PR；合并 release PR 之后，会自动发布到 npm。
+
+发布流程不会编译 `dist`，而是直接把 `src/*.ts` 发布出去供 Bun 执行。

packages/baoyu-fetch/bun.lock

@@ -0,0 +1,530 @@
+{
+  "lockfileVersion": 1,
+  "configVersion": 0,
+  "workspaces": {
+    "": {
+      "name": "baoyu-fetch",
+      "dependencies": {
+        "@mozilla/readability": "^0.6.0",
+        "chrome-launcher": "^1.2.1",
+        "defuddle": "^0.17.0",
+        "jsdom": "^29.0.2",
+        "remark-gfm": "^4.0.1",
+        "remark-parse": "^11.0.0",
+        "turndown": "^7.2.0",
+        "turndown-plugin-gfm": "^1.0.2",
+        "unified": "^11.0.5",
+        "ws": "^8.18.3",
+      },
+      "devDependencies": {
+        "@changesets/cli": "^2.30.0",
+        "@types/bun": "^1.2.23",
+        "@types/jsdom": "^21.1.7",
+        "@types/ws": "^8.18.1",
+        "typescript": "^5.9.2",
+      },
+    },
+  },
+  "overrides": {
+    "@xmldom/xmldom": "0.8.13",
+  },
+  "packages": {
+    "@asamuzakjp/css-color": ["@asamuzakjp/css-color@5.1.11", "", { "dependencies": { "@asamuzakjp/generational-cache": "^1.0.1", "@csstools/css-calc": "^3.2.0", "@csstools/css-color-parser": "^4.1.0", "@csstools/css-parser-algorithms": "^4.0.0", "@csstools/css-tokenizer": "^4.0.0" } }, "sha512-KVw6qIiCTUQhByfTd78h2yD1/00waTmm9uy/R7Ck/ctUyAPj+AEDLkQIdJW0T8+qGgj3j5bpNKK7Q3G+LedJWg=="],
+
+    "@asamuzakjp/dom-selector": ["@asamuzakjp/dom-selector@7.1.1", "", { "dependencies": { "@asamuzakjp/generational-cache": "^1.0.1", "@asamuzakjp/nwsapi": "^2.3.9", "bidi-js": "^1.0.3", "css-tree": "^3.2.1", "is-potential-custom-element-name": "^1.0.1" } }, "sha512-67RZDnYRc8H/8MLDgQCDE//zoqVFwajkepHZgmXrbwybzXOEwOWGPYGmALYl9J2DOLfFPPs6kKCqmbzV895hTQ=="],
+
+    "@asamuzakjp/generational-cache": ["@asamuzakjp/generational-cache@1.0.1", "", {}, "sha512-wajfB8KqzMCN2KGNFdLkReeHncd0AslUSrvHVvvYWuU8ghncRJoA50kT3zP9MVL0+9g4/67H+cdvBskj9THPzg=="],
+
+    "@asamuzakjp/nwsapi": ["@asamuzakjp/nwsapi@2.3.9", "", {}, "sha512-n8GuYSrI9bF7FFZ/SjhwevlHc8xaVlb/7HmHelnc/PZXBD2ZR49NnN9sMMuDdEGPeeRQ5d0hqlSlEpgCX3Wl0Q=="],
+
+    "@babel/runtime": ["@babel/runtime@7.29.2", "", {}, "sha512-JiDShH45zKHWyGe4ZNVRrCjBz8Nh9TMmZG1kh4QTK8hCBTWBi8Da+i7s1fJw7/lYpM4ccepSNfqzZ/QvABBi5g=="],
+
+    "@bramus/specificity": ["@bramus/specificity@2.4.2", "", { "dependencies": { "css-tree": "^3.0.0" }, "bin": { "specificity": "bin/cli.js" } }, "sha512-ctxtJ/eA+t+6q2++vj5j7FYX3nRu311q1wfYH3xjlLOsczhlhxAg2FWNUXhpGvAw3BWo1xBcvOV6/YLc2r5FJw=="],
+
+    "@changesets/apply-release-plan": ["@changesets/apply-release-plan@7.1.0", "", { "dependencies": { "@changesets/config": "^3.1.3", "@changesets/get-version-range-type": "^0.4.0", "@changesets/git": "^3.0.4", "@changesets/should-skip-package": "^0.1.2", "@changesets/types": "^6.1.0", "@manypkg/get-packages": "^1.1.3", "detect-indent": "^6.0.0", "fs-extra": "^7.0.1", "lodash.startcase": "^4.4.0", "outdent": "^0.5.0", "prettier": "^2.7.1", "resolve-from": "^5.0.0", "semver": "^7.5.3" } }, "sha512-yq8ML3YS7koKQ/9bk1PqO0HMzApIFNwjlwCnwFEXMzNe8NpzeeYYKCmnhWJGkN8g7E51MnWaSbqRcTcdIxUgnQ=="],
+
+    "@changesets/assemble-release-plan": ["@changesets/assemble-release-plan@6.0.9", "", { "dependencies": { "@changesets/errors": "^0.2.0", "@changesets/get-dependents-graph": "^2.1.3", "@changesets/should-skip-package": "^0.1.2", "@changesets/types": "^6.1.0", "@manypkg/get-packages": "^1.1.3", "semver": "^7.5.3" } }, "sha512-tPgeeqCHIwNo8sypKlS3gOPmsS3wP0zHt67JDuL20P4QcXiw/O4Hl7oXiuLnP9yg+rXLQ2sScdV1Kkzde61iSQ=="],
+
+    "@changesets/changelog-git": ["@changesets/changelog-git@0.2.1", "", { "dependencies": { "@changesets/types": "^6.1.0" } }, "sha512-x/xEleCFLH28c3bQeQIyeZf8lFXyDFVn1SgcBiR2Tw/r4IAWlk1fzxCEZ6NxQAjF2Nwtczoen3OA2qR+UawQ8Q=="],
+
+    "@changesets/cli": ["@changesets/cli@2.30.0", "", { "dependencies": { "@changesets/apply-release-plan": "^7.1.0", "@changesets/assemble-release-plan": "^6.0.9", "@changesets/changelog-git": "^0.2.1", "@changesets/config": "^3.1.3", "@changesets/errors": "^0.2.0", "@changesets/get-dependents-graph": "^2.1.3", "@changesets/get-release-plan": "^4.0.15", "@changesets/git": "^3.0.4", "@changesets/logger": "^0.1.1", "@changesets/pre": "^2.0.2", "@changesets/read": "^0.6.7", "@changesets/should-skip-package": "^0.1.2", "@changesets/types": "^6.1.0", "@changesets/write": "^0.4.0", "@inquirer/external-editor": "^1.0.2", "@manypkg/get-packages": "^1.1.3", "ansi-colors": "^4.1.3", "enquirer": "^2.4.1", "fs-extra": "^7.0.1", "mri": "^1.2.0", "package-manager-detector": "^0.2.0", "picocolors": "^1.1.0", "resolve-from": "^5.0.0", "semver": "^7.5.3", "spawndamnit": "^3.0.1", "term-size": "^2.1.0" }, "bin": { "changeset": "bin.js" } }, "sha512-5D3Nk2JPqMI1wK25pEymeWRSlSMdo5QOGlyfrKg0AOufrUcjEE3RQgaCpHoBiM31CSNrtSgdJ0U6zL1rLDDfBA=="],
+
+    "@changesets/config": ["@changesets/config@3.1.3", "", { "dependencies": { "@changesets/errors": "^0.2.0", "@changesets/get-dependents-graph": "^2.1.3", "@changesets/logger": "^0.1.1", "@changesets/should-skip-package": "^0.1.2", "@changesets/types": "^6.1.0", "@manypkg/get-packages": "^1.1.3", "fs-extra": "^7.0.1", "micromatch": "^4.0.8" } }, "sha512-vnXjcey8YgBn2L1OPWd3ORs0bGC4LoYcK/ubpgvzNVr53JXV5GiTVj7fWdMRsoKUH7hhhMAQnsJUqLr21EncNw=="],
+
+    "@changesets/errors": ["@changesets/errors@0.2.0", "", { "dependencies": { "extendable-error": "^0.1.5" } }, "sha512-6BLOQUscTpZeGljvyQXlWOItQyU71kCdGz7Pi8H8zdw6BI0g3m43iL4xKUVPWtG+qrrL9DTjpdn8eYuCQSRpow=="],
+
+    "@changesets/get-dependents-graph": ["@changesets/get-dependents-graph@2.1.3", "", { "dependencies": { "@changesets/types": "^6.1.0", "@manypkg/get-packages": "^1.1.3", "picocolors": "^1.1.0", "semver": "^7.5.3" } }, "sha512-gphr+v0mv2I3Oxt19VdWRRUxq3sseyUpX9DaHpTUmLj92Y10AGy+XOtV+kbM6L/fDcpx7/ISDFK6T8A/P3lOdQ=="],
+
+    "@changesets/get-release-plan": ["@changesets/get-release-plan@4.0.15", "", { "dependencies": { "@changesets/assemble-release-plan": "^6.0.9", "@changesets/config": "^3.1.3", "@changesets/pre": "^2.0.2", "@changesets/read": "^0.6.7", "@changesets/types": "^6.1.0", "@manypkg/get-packages": "^1.1.3" } }, "sha512-Q04ZaRPuEVZtA+auOYgFaVQQSA98dXiVe/yFaZfY7hoSmQICHGvP0TF4u3EDNHWmmCS4ekA/XSpKlSM2PyTS2g=="],
+
+    "@changesets/get-version-range-type": ["@changesets/get-version-range-type@0.4.0", "", {}, "sha512-hwawtob9DryoGTpixy1D3ZXbGgJu1Rhr+ySH2PvTLHvkZuQ7sRT4oQwMh0hbqZH1weAooedEjRsbrWcGLCeyVQ=="],
+
+    "@changesets/git": ["@changesets/git@3.0.4", "", { "dependencies": { "@changesets/errors": "^0.2.0", "@manypkg/get-packages": "^1.1.3", "is-subdir": "^1.1.1", "micromatch": "^4.0.8", "spawndamnit": "^3.0.1" } }, "sha512-BXANzRFkX+XcC1q/d27NKvlJ1yf7PSAgi8JG6dt8EfbHFHi4neau7mufcSca5zRhwOL8j9s6EqsxmT+s+/E6Sw=="],
+
+    "@changesets/logger": ["@changesets/logger@0.1.1", "", { "dependencies": { "picocolors": "^1.1.0" } }, "sha512-OQtR36ZlnuTxKqoW4Sv6x5YIhOmClRd5pWsjZsddYxpWs517R0HkyiefQPIytCVh4ZcC5x9XaG8KTdd5iRQUfg=="],
+
+    "@changesets/parse": ["@changesets/parse@0.4.3", "", { "dependencies": { "@changesets/types": "^6.1.0", "js-yaml": "^4.1.1" } }, "sha512-ZDmNc53+dXdWEv7fqIUSgRQOLYoUom5Z40gmLgmATmYR9NbL6FJJHwakcCpzaeCy+1D0m0n7mT4jj2B/MQPl7A=="],
+
+    "@changesets/pre": ["@changesets/pre@2.0.2", "", { "dependencies": { "@changesets/errors": "^0.2.0", "@changesets/types": "^6.1.0", "@manypkg/get-packages": "^1.1.3", "fs-extra": "^7.0.1" } }, "sha512-HaL/gEyFVvkf9KFg6484wR9s0qjAXlZ8qWPDkTyKF6+zqjBe/I2mygg3MbpZ++hdi0ToqNUF8cjj7fBy0dg8Ug=="],
+
+    "@changesets/read": ["@changesets/read@0.6.7", "", { "dependencies": { "@changesets/git": "^3.0.4", "@changesets/logger": "^0.1.1", "@changesets/parse": "^0.4.3", "@changesets/types": "^6.1.0", "fs-extra": "^7.0.1", "p-filter": "^2.1.0", "picocolors": "^1.1.0" } }, "sha512-D1G4AUYGrBEk8vj8MGwf75k9GpN6XL3wg8i42P2jZZwFLXnlr2Pn7r9yuQNbaMCarP7ZQWNJbV6XLeysAIMhTA=="],
+
+    "@changesets/should-skip-package": ["@changesets/should-skip-package@0.1.2", "", { "dependencies": { "@changesets/types": "^6.1.0", "@manypkg/get-packages": "^1.1.3" } }, "sha512-qAK/WrqWLNCP22UDdBTMPH5f41elVDlsNyat180A33dWxuUDyNpg6fPi/FyTZwRriVjg0L8gnjJn2F9XAoF0qw=="],
+
+    "@changesets/types": ["@changesets/types@6.1.0", "", {}, "sha512-rKQcJ+o1nKNgeoYRHKOS07tAMNd3YSN0uHaJOZYjBAgxfV7TUE7JE+z4BzZdQwb5hKaYbayKN5KrYV7ODb2rAA=="],
+
+    "@changesets/write": ["@changesets/write@0.4.0", "", { "dependencies": { "@changesets/types": "^6.1.0", "fs-extra": "^7.0.1", "human-id": "^4.1.1", "prettier": "^2.7.1" } }, "sha512-CdTLvIOPiCNuH71pyDu3rA+Q0n65cmAbXnwWH84rKGiFumFzkmHNT8KHTMEchcxN+Kl8I54xGUhJ7l3E7X396Q=="],
+
+    "@csstools/color-helpers": ["@csstools/color-helpers@6.0.2", "", {}, "sha512-LMGQLS9EuADloEFkcTBR3BwV/CGHV7zyDxVRtVDTwdI2Ca4it0CCVTT9wCkxSgokjE5Ho41hEPgb8OEUwoXr6Q=="],
+
+    "@csstools/css-calc": ["@csstools/css-calc@3.2.0", "", { "peerDependencies": { "@csstools/css-parser-algorithms": "^4.0.0", "@csstools/css-tokenizer": "^4.0.0" } }, "sha512-bR9e6o2BDB12jzN/gIbjHa5wLJ4UjD1CB9pM7ehlc0ddk6EBz+yYS1EV2MF55/HUxrHcB/hehAyt5vhsA3hx7w=="],
+
+    "@csstools/css-color-parser": ["@csstools/css-color-parser@4.1.0", "", { "dependencies": { "@csstools/color-helpers": "^6.0.2", "@csstools/css-calc": "^3.2.0" }, "peerDependencies": { "@csstools/css-parser-algorithms": "^4.0.0", "@csstools/css-tokenizer": "^4.0.0" } }, "sha512-U0KhLYmy2GVj6q4T3WaAe6NPuFYCPQoE3b0dRGxejWDgcPp8TP7S5rVdM5ZrFaqu4N67X8YaPBw14dQSYx3IyQ=="],
+
+    "@csstools/css-parser-algorithms": ["@csstools/css-parser-algorithms@4.0.0", "", { "peerDependencies": { "@csstools/css-tokenizer": "^4.0.0" } }, "sha512-+B87qS7fIG3L5h3qwJ/IFbjoVoOe/bpOdh9hAjXbvx0o8ImEmUsGXN0inFOnk2ChCFgqkkGFQ+TpM5rbhkKe4w=="],
+
+    "@csstools/css-syntax-patches-for-csstree": ["@csstools/css-syntax-patches-for-csstree@1.1.3", "", { "peerDependencies": { "css-tree": "^3.2.1" }, "optionalPeers": ["css-tree"] }, "sha512-SH60bMfrRCJF3morcdk57WklujF4Jr/EsQUzqkarfHXEFcAR1gg7fS/chAE922Sehgzc1/+Tz5H3Ypa1HiEKrg=="],
+
+    "@csstools/css-tokenizer": ["@csstools/css-tokenizer@4.0.0", "", {}, "sha512-QxULHAm7cNu72w97JUNCBFODFaXpbDg+dP8b/oWFAZ2MTRppA3U00Y2L1HqaS4J6yBqxwa/Y3nMBaxVKbB/NsA=="],
+
+    "@exodus/bytes": ["@exodus/bytes@1.15.0", "", { "peerDependencies": { "@noble/hashes": "^1.8.0 || ^2.0.0" }, "optionalPeers": ["@noble/hashes"] }, "sha512-UY0nlA+feH81UGSHv92sLEPLCeZFjXOuHhrIo0HQydScuQc8s0A7kL/UdgwgDq8g8ilksmuoF35YVTNphV2aBQ=="],
+
+    "@inquirer/external-editor": ["@inquirer/external-editor@1.0.3", "", { "dependencies": { "chardet": "^2.1.1", "iconv-lite": "^0.7.0" }, "peerDependencies": { "@types/node": ">=18" }, "optionalPeers": ["@types/node"] }, "sha512-RWbSrDiYmO4LbejWY7ttpxczuwQyZLBUyygsA9Nsv95hpzUWwnNTVQmAq3xuh7vNwCp07UTmE5i11XAEExx4RA=="],
+
+    "@manypkg/find-root": ["@manypkg/find-root@1.1.0", "", { "dependencies": { "@babel/runtime": "^7.5.5", "@types/node": "^12.7.1", "find-up": "^4.1.0", "fs-extra": "^8.1.0" } }, "sha512-mki5uBvhHzO8kYYix/WRy2WX8S3B5wdVSc9D6KcU5lQNglP2yt58/VfLuAK49glRXChosY8ap2oJ1qgma3GUVA=="],
+
+    "@manypkg/get-packages": ["@manypkg/get-packages@1.1.3", "", { "dependencies": { "@babel/runtime": "^7.5.5", "@changesets/types": "^4.0.1", "@manypkg/find-root": "^1.1.0", "fs-extra": "^8.1.0", "globby": "^11.0.0", "read-yaml-file": "^1.1.0" } }, "sha512-fo+QhuU3qE/2TQMQmbVMqaQ6EWbMhi4ABWP+O4AM1NqPBuy0OrApV5LO6BrrgnhtAHS2NH6RrVk9OL181tTi8A=="],
+
+    "@mixmark-io/domino": ["@mixmark-io/domino@2.2.0", "", {}, "sha512-Y28PR25bHXUg88kCV7nivXrP2Nj2RueZ3/l/jdx6J9f8J4nsEGcgX0Qe6lt7Pa+J79+kPiJU3LguR6O/6zrLOw=="],
+
+    "@mozilla/readability": ["@mozilla/readability@0.6.0", "", {}, "sha512-juG5VWh4qAivzTAeMzvY9xs9HY5rAcr2E4I7tiSSCokRFi7XIZCAu92ZkSTsIj1OPceCifL3cpfteP3pDT9/QQ=="],
+
+    "@nodelib/fs.scandir": ["@nodelib/fs.scandir@2.1.5", "", { "dependencies": { "@nodelib/fs.stat": "2.0.5", "run-parallel": "^1.1.9" } }, "sha512-vq24Bq3ym5HEQm2NKCr3yXDwjc7vTsEThRDnkp2DK9p1uqLR+DHurm/NOTo0KG7HYHU7eppKZj3MyqYuMBf62g=="],
+
+    "@nodelib/fs.stat": ["@nodelib/fs.stat@2.0.5", "", {}, "sha512-RkhPPp2zrqDAQA/2jNhnztcPAlv64XdhIp7a7454A5ovI7Bukxgt7MX7udwAu3zg1DcpPU0rz3VV1SeaqvY4+A=="],
+
+    "@nodelib/fs.walk": ["@nodelib/fs.walk@1.2.8", "", { "dependencies": { "@nodelib/fs.scandir": "2.1.5", "fastq": "^1.6.0" } }, "sha512-oGB+UxlgWcgQkgwo8GcEGwemoTFt3FIO9ababBmaGwXIoBKZ+GTy0pP185beGg7Llih/NSHSV2XAs1lnznocSg=="],
+
+    "@types/bun": ["@types/bun@1.3.11", "", { "dependencies": { "bun-types": "1.3.11" } }, "sha512-5vPne5QvtpjGpsGYXiFyycfpDF2ECyPcTSsFBMa0fraoxiQyMJ3SmuQIGhzPg2WJuWxVBoxWJ2kClYTcw/4fAg=="],
+
+    "@types/debug": ["@types/debug@4.1.13", "", { "dependencies": { "@types/ms": "*" } }, "sha512-KSVgmQmzMwPlmtljOomayoR89W4FynCAi3E8PPs7vmDVPe84hT+vGPKkJfThkmXs0x0jAaa9U8uW8bbfyS2fWw=="],
+
+    "@types/jsdom": ["@types/jsdom@21.1.7", "", { "dependencies": { "@types/node": "*", "@types/tough-cookie": "*", "parse5": "^7.0.0" } }, "sha512-yOriVnggzrnQ3a9OKOCxaVuSug3w3/SbOj5i7VwXWZEyUNl3bLF9V3MfxGbZKuwqJOQyRfqXyROBB1CoZLFWzA=="],
+
+    "@types/mdast": ["@types/mdast@4.0.4", "", { "dependencies": { "@types/unist": "*" } }, "sha512-kGaNbPh1k7AFzgpud/gMdvIm5xuECykRR+JnWKQno9TAXVa6WIVCGTPvYGekIDL4uwCZQSYbUxNBSb1aUo79oA=="],
+
+    "@types/ms": ["@types/ms@2.1.0", "", {}, "sha512-GsCCIZDE/p3i96vtEqx+7dBUGXrc7zeSK3wwPHIaRThS+9OhWIXRqzs4d6k1SVU8g91DrNRWxWUGhp5KXQb2VA=="],
+
+    "@types/node": ["@types/node@25.5.0", "", { "dependencies": { "undici-types": "~7.18.0" } }, "sha512-jp2P3tQMSxWugkCUKLRPVUpGaL5MVFwF8RDuSRztfwgN1wmqJeMSbKlnEtQqU8UrhTmzEmZdu2I6v2dpp7XIxw=="],
+
+    "@types/tough-cookie": ["@types/tough-cookie@4.0.5", "", {}, "sha512-/Ad8+nIOV7Rl++6f1BdKxFSMgmoqEoYbHRpPcx3JEfv8VRsQe9Z4mCXeJBzxs7mbHY/XOZZuXlRNfhpVPbs6ZA=="],
+
+    "@types/unist": ["@types/unist@3.0.3", "", {}, "sha512-ko/gIFJRv177XgZsZcBwnqJN5x/Gien8qNOn0D5bQU/zAzVf9Zt3BlcUiLqhV9y4ARk0GbT3tnUiPNgnTXzc/Q=="],
+
+    "@types/ws": ["@types/ws@8.18.1", "", { "dependencies": { "@types/node": "*" } }, "sha512-ThVF6DCVhA8kUGy+aazFQ4kXQ7E1Ty7A3ypFOe0IcJV8O/M511G99AW24irKrW56Wt44yG9+ij8FaqoBGkuBXg=="],
+
+    "@xmldom/xmldom": ["@xmldom/xmldom@0.8.13", "", {}, "sha512-KRYzxepc14G/CEpEGc3Yn+JKaAeT63smlDr+vjB8jRfgTBBI9wRj/nkQEO+ucV8p8I9bfKLWp37uHgFrbntPvw=="],
+
+    "ansi-colors": ["ansi-colors@4.1.3", "", {}, "sha512-/6w/C21Pm1A7aZitlI5Ni/2J6FFQN8i1Cvz3kHABAAbw93v/NlvKdVOqz7CCWz/3iv/JplRSEEZ83XION15ovw=="],
+
+    "ansi-regex": ["ansi-regex@5.0.1", "", {}, "sha512-quJQXlTSUGL2LH9SUXo8VwsY4soanhgo6LNSm84E1LBcE8s3O0wpdiRzyR9z/ZZJMlMWv37qOOb9pdJlMUEKFQ=="],
+
+    "argparse": ["argparse@2.0.1", "", {}, "sha512-8+9WqebbFzpX9OR+Wa6O29asIogeRMzcGtAINdpMHHyAg10f05aSFVBbcEqGf/PXw1EjAZ+q2/bEBg3DvurK3Q=="],
+
+    "array-union": ["array-union@2.1.0", "", {}, "sha512-HGyxoOTYUyCM6stUe6EJgnd4EoewAI7zMdfqO+kGjnlZmBDz/cR5pf8r/cR4Wq60sL/p0IkcjUEEPwS3GFrIyw=="],
+
+    "bail": ["bail@2.0.2", "", {}, "sha512-0xO6mYd7JB2YesxDKplafRpsiOzPt9V02ddPCLbY1xYGPOX24NTyN50qnUxgCPcSoYMhKpAuBTjQoRZCAkUDRw=="],
+
+    "better-path-resolve": ["better-path-resolve@1.0.0", "", { "dependencies": { "is-windows": "^1.0.0" } }, "sha512-pbnl5XzGBdrFU/wT4jqmJVPn2B6UHPBOhzMQkY/SPUPB6QtUXtmBHBIwCbXJol93mOpGMnQyP/+BB19q04xj7g=="],
+
+    "bidi-js": ["bidi-js@1.0.3", "", { "dependencies": { "require-from-string": "^2.0.2" } }, "sha512-RKshQI1R3YQ+n9YJz2QQ147P66ELpa1FQEg20Dk8oW9t2KgLbpDLLp9aGZ7y8WHSshDknG0bknqGw5/tyCs5tw=="],
+
+    "boolbase": ["boolbase@1.0.0", "", {}, "sha512-JZOSA7Mo9sNGB8+UjSgzdLtokWAky1zbztM3WRLCbZ70/3cTANmQmOdR7y2g+J0e2WXywy1yS468tY+IruqEww=="],
+
+    "braces": ["braces@3.0.3", "", { "dependencies": { "fill-range": "^7.1.1" } }, "sha512-yQbXgO/OSZVD2IsiLlro+7Hf6Q18EJrKSEsdoMzKePKXct3gvD8oLcOQdIzGupr5Fj+EDe8gO/lxc1BzfMpxvA=="],
+
+    "bun-types": ["bun-types@1.3.11", "", { "dependencies": { "@types/node": "*" } }, "sha512-1KGPpoxQWl9f6wcZh57LvrPIInQMn2TQ7jsgxqpRzg+l0QPOFvJVH7HmvHo/AiPgwXy+/Thf6Ov3EdVn1vOabg=="],
+
+    "ccount": ["ccount@2.0.1", "", {}, "sha512-eyrF0jiFpY+3drT6383f1qhkbGsLSifNAjA61IUjZjmLCWjItY6LB9ft9YhoDgwfmclB2zhu51Lc7+95b8NRAg=="],
+
+    "character-entities": ["character-entities@2.0.2", "", {}, "sha512-shx7oQ0Awen/BRIdkjkvz54PnEEI/EjwXDSIZp86/KKdbafHh1Df/RYGBhn4hbe2+uKC9FnT5UCEdyPz3ai9hQ=="],
+
+    "chardet": ["chardet@2.1.1", "", {}, "sha512-PsezH1rqdV9VvyNhxxOW32/d75r01NY7TQCmOqomRo15ZSOKbpTFVsfjghxo6JloQUCGnH4k1LGu0R4yCLlWQQ=="],
+
+    "chrome-launcher": ["chrome-launcher@1.2.1", "", { "dependencies": { "@types/node": "*", "escape-string-regexp": "^4.0.0", "is-wsl": "^2.2.0", "lighthouse-logger": "^2.0.1" }, "bin": { "print-chrome-path": "bin/print-chrome-path.cjs" } }, "sha512-qmFR5PLMzHyuNJHwOloHPAHhbaNglkfeV/xDtt5b7xiFFyU1I+AZZX0PYseMuhenJSSirgxELYIbswcoc+5H4A=="],
+
+    "commander": ["commander@12.1.0", "", {}, "sha512-Vw8qHK3bZM9y/P10u3Vib8o/DdkvA2OtPtZvD871QKjy74Wj1WSKFILMPRPSdUSx5RFK1arlJzEtA4PkFgnbuA=="],
+
+    "cross-spawn": ["cross-spawn@7.0.6", "", { "dependencies": { "path-key": "^3.1.0", "shebang-command": "^2.0.0", "which": "^2.0.1" } }, "sha512-uV2QOWP2nWzsy2aMp8aRibhi9dlzF5Hgh5SHaB9OiTGEyDTiJJyx0uy51QXdyWbtAHNua4XJzUKca3OzKUd3vA=="],
+
+    "css-select": ["css-select@5.2.2", "", { "dependencies": { "boolbase": "^1.0.0", "css-what": "^6.1.0", "domhandler": "^5.0.2", "domutils": "^3.0.1", "nth-check": "^2.0.1" } }, "sha512-TizTzUddG/xYLA3NXodFM0fSbNizXjOKhqiQQwvhlspadZokn1KDy0NZFS0wuEubIYAV5/c1/lAr0TaaFXEXzw=="],
+
+    "css-tree": ["css-tree@3.2.1", "", { "dependencies": { "mdn-data": "2.27.1", "source-map-js": "^1.2.1" } }, "sha512-X7sjQzceUhu1u7Y/ylrRZFU2FS6LRiFVp6rKLPg23y3x3c3DOKAwuXGDp+PAGjh6CSnCjYeAul8pcT8bAl+lSA=="],
+
+    "css-what": ["css-what@6.2.2", "", {}, "sha512-u/O3vwbptzhMs3L1fQE82ZSLHQQfto5gyZzwteVIEyeaY5Fc7R4dapF/BvRoSYFeqfBk4m0V1Vafq5Pjv25wvA=="],
+
+    "cssom": ["cssom@0.5.0", "", {}, "sha512-iKuQcq+NdHqlAcwUY0o/HL69XQrUaQdMjmStJ8JFmUaiiQErlhrmuigkg/CU4E2J0IyUKUrMAgl36TvN67MqTw=="],
+
+    "data-urls": ["data-urls@7.0.0", "", { "dependencies": { "whatwg-mimetype": "^5.0.0", "whatwg-url": "^16.0.0" } }, "sha512-23XHcCF+coGYevirZceTVD7NdJOqVn+49IHyxgszm+JIiHLoB2TkmPtsYkNWT1pvRSGkc35L6NHs0yHkN2SumA=="],
+
+    "debug": ["debug@4.4.3", "", { "dependencies": { "ms": "^2.1.3" } }, "sha512-RGwwWnwQvkVfavKVt22FGLw+xYSdzARwm0ru6DhTVA3umU5hZc28V3kO4stgYryrTlLpuvgI9GiijltAjNbcqA=="],
+
+    "decimal.js": ["decimal.js@10.6.0", "", {}, "sha512-YpgQiITW3JXGntzdUmyUR1V812Hn8T1YVXhCu+wO3OpS4eU9l4YdD3qjyiKdV6mvV29zapkMeD390UVEf2lkUg=="],
+
+    "decode-named-character-reference": ["decode-named-character-reference@1.3.0", "", { "dependencies": { "character-entities": "^2.0.0" } }, "sha512-GtpQYB283KrPp6nRw50q3U9/VfOutZOe103qlN7BPP6Ad27xYnOIWv4lPzo8HCAL+mMZofJ9KEy30fq6MfaK6Q=="],
+
+    "defuddle": ["defuddle@0.17.0", "", { "dependencies": { "commander": "^12.1.0" }, "optionalDependencies": { "linkedom": "^0.18.12", "mathml-to-latex": "^1.5.0", "temml": "^0.13.1", "turndown": "^7.2.0" }, "bin": { "defuddle": "dist/cli.js" } }, "sha512-rjRb9kxgrJLFhFJjXTSAitbmmSyvjEqGCi5JiyM6ImOf4leC/O+f7TPVPAymk/gnENFTrn9j7T/LTfW9IVwiLw=="],
+
+    "dequal": ["dequal@2.0.3", "", {}, "sha512-0je+qPKHEMohvfRTCEo3CrPG6cAzAYgmzKyxRiYSSDkS6eGJdyVJm7WaYA5ECaAD9wLB2T4EEeymA5aFVcYXCA=="],
+
+    "detect-indent": ["detect-indent@6.1.0", "", {}, "sha512-reYkTUJAZb9gUuZ2RvVCNhVHdg62RHnJ7WJl8ftMi4diZ6NWlciOzQN88pUhSELEwflJht4oQDv0F0BMlwaYtA=="],
+
+    "devlop": ["devlop@1.1.0", "", { "dependencies": { "dequal": "^2.0.0" } }, "sha512-RWmIqhcFf1lRYBvNmr7qTNuyCt/7/ns2jbpp1+PalgE/rDQcBT0fioSMUpJ93irlUhC5hrg4cYqe6U+0ImW0rA=="],
+
+    "dir-glob": ["dir-glob@3.0.1", "", { "dependencies": { "path-type": "^4.0.0" } }, "sha512-WkrWp9GR4KXfKGYzOLmTuGVi1UWFfws377n9cc55/tb6DuqyF6pcQ5AbiHEshaDpY9v6oaSr2XCDidGmMwdzIA=="],
+
+    "dom-serializer": ["dom-serializer@2.0.0", "", { "dependencies": { "domelementtype": "^2.3.0", "domhandler": "^5.0.2", "entities": "^4.2.0" } }, "sha512-wIkAryiqt/nV5EQKqQpo3SToSOV9J0DnbJqwK7Wv/Trc92zIAYZ4FlMu+JPFW1DfGFt81ZTCGgDEabffXeLyJg=="],
+
+    "domelementtype": ["domelementtype@2.3.0", "", {}, "sha512-OLETBj6w0OsagBwdXnPdN0cnMfF9opN69co+7ZrbfPGrdpPVNBUj02spi6B1N7wChLQiPn4CSH/zJvXw56gmHw=="],
+
+    "domhandler": ["domhandler@5.0.3", "", { "dependencies": { "domelementtype": "^2.3.0" } }, "sha512-cgwlv/1iFQiFnU96XXgROh8xTeetsnJiDsTc7TYCLFd9+/WNkIqPTxiM/8pSd8VIrhXGTf1Ny1q1hquVqDJB5w=="],
+
+    "domutils": ["domutils@3.2.2", "", { "dependencies": { "dom-serializer": "^2.0.0", "domelementtype": "^2.3.0", "domhandler": "^5.0.3" } }, "sha512-6kZKyUajlDuqlHKVX1w7gyslj9MPIXzIFiz/rGu35uC1wMi+kMhQwGhl4lt9unC9Vb9INnY9Z3/ZA3+FhASLaw=="],
+
+    "enquirer": ["enquirer@2.4.1", "", { "dependencies": { "ansi-colors": "^4.1.1", "strip-ansi": "^6.0.1" } }, "sha512-rRqJg/6gd538VHvR3PSrdRBb/1Vy2YfzHqzvbhGIQpDRKIa4FgV/54b5Q1xYSxOOwKvjXweS26E0Q+nAMwp2pQ=="],
+
+    "entities": ["entities@6.0.1", "", {}, "sha512-aN97NXWF6AWBTahfVOIrB/NShkzi5H7F9r1s9mD3cDj4Ko5f2qhhVoYMibXF7GlLveb/D2ioWay8lxI97Ven3g=="],
+
+    "escape-string-regexp": ["escape-string-regexp@4.0.0", "", {}, "sha512-TtpcNJ3XAzx3Gq8sWRzJaVajRs0uVxA2YAkdb1jm2YkPz4G6egUFAyA3n5vtEIZefPk5Wa4UXbKuS5fKkJWdgA=="],
+
+    "esprima": ["esprima@4.0.1", "", { "bin": { "esparse": "./bin/esparse.js", "esvalidate": "./bin/esvalidate.js" } }, "sha512-eGuFFw7Upda+g4p+QHvnW0RyTX/SVeJBDM/gCtMARO0cLuT2HcEKnTPvhjV6aGeqrCB/sbNop0Kszm0jsaWU4A=="],
+
+    "extend": ["extend@3.0.2", "", {}, "sha512-fjquC59cD7CyW6urNXK0FBufkZcoiGG80wTuPujX590cB5Ttln20E2UB4S/WARVqhXffZl2LNgS+gQdPIIim/g=="],
+
+    "extendable-error": ["extendable-error@0.1.7", "", {}, "sha512-UOiS2in6/Q0FK0R0q6UY9vYpQ21mr/Qn1KOnte7vsACuNJf514WvCCUHSRCPcgjPT2bAhNIJdlE6bVap1GKmeg=="],
+
+    "fast-glob": ["fast-glob@3.3.3", "", { "dependencies": { "@nodelib/fs.stat": "^2.0.2", "@nodelib/fs.walk": "^1.2.3", "glob-parent": "^5.1.2", "merge2": "^1.3.0", "micromatch": "^4.0.8" } }, "sha512-7MptL8U0cqcFdzIzwOTHoilX9x5BrNqye7Z/LuC7kCMRio1EMSyqRK3BEAUD7sXRq4iT4AzTVuZdhgQ2TCvYLg=="],
+
+    "fastq": ["fastq@1.20.1", "", { "dependencies": { "reusify": "^1.0.4" } }, "sha512-GGToxJ/w1x32s/D2EKND7kTil4n8OVk/9mycTc4VDza13lOvpUZTGX3mFSCtV9ksdGBVzvsyAVLM6mHFThxXxw=="],
+
+    "fill-range": ["fill-range@7.1.1", "", { "dependencies": { "to-regex-range": "^5.0.1" } }, "sha512-YsGpe3WHLK8ZYi4tWDg2Jy3ebRz2rXowDxnld4bkQB00cc/1Zw9AWnC0i9ztDJitivtQvaI9KaLyKrc+hBW0yg=="],
+
+    "find-up": ["find-up@4.1.0", "", { "dependencies": { "locate-path": "^5.0.0", "path-exists": "^4.0.0" } }, "sha512-PpOwAdQ/YlXQ2vj8a3h8IipDuYRi3wceVQQGYWxNINccq40Anw7BlsEXCMbt1Zt+OLA6Fq9suIpIWD0OsnISlw=="],
+
+    "fs-extra": ["fs-extra@7.0.1", "", { "dependencies": { "graceful-fs": "^4.1.2", "jsonfile": "^4.0.0", "universalify": "^0.1.0" } }, "sha512-YJDaCJZEnBmcbw13fvdAM9AwNOJwOzrE4pqMqBq5nFiEqXUqHwlK4B+3pUw6JNvfSPtX05xFHtYy/1ni01eGCw=="],
+
+    "glob-parent": ["glob-parent@5.1.2", "", { "dependencies": { "is-glob": "^4.0.1" } }, "sha512-AOIgSQCepiJYwP3ARnGx+5VnTu2HBYdzbGP45eLw1vr3zB3vZLeyed1sC9hnbcOc9/SrMyM5RPQrkGz4aS9Zow=="],
+
+    "globby": ["globby@11.1.0", "", { "dependencies": { "array-union": "^2.1.0", "dir-glob": "^3.0.1", "fast-glob": "^3.2.9", "ignore": "^5.2.0", "merge2": "^1.4.1", "slash": "^3.0.0" } }, "sha512-jhIXaOzy1sb8IyocaruWSn1TjmnBVs8Ayhcy83rmxNJ8q2uWKCAj3CnJY+KpGSXCueAPc0i05kVvVKtP1t9S3g=="],
+
+    "graceful-fs": ["graceful-fs@4.2.11", "", {}, "sha512-RbJ5/jmFcNNCcDV5o9eTnBLJ/HszWV0P73bc+Ff4nS/rJj+YaS6IGyiOL0VoBYX+l1Wrl3k63h/KrH+nhJ0XvQ=="],
+
+    "html-encoding-sniffer": ["html-encoding-sniffer@6.0.0", "", { "dependencies": { "@exodus/bytes": "^1.6.0" } }, "sha512-CV9TW3Y3f8/wT0BRFc1/KAVQ3TUHiXmaAb6VW9vtiMFf7SLoMd1PdAc4W3KFOFETBJUb90KatHqlsZMWV+R9Gg=="],
+
+    "html-escaper": ["html-escaper@3.0.3", "", {}, "sha512-RuMffC89BOWQoY0WKGpIhn5gX3iI54O6nRA0yC124NYVtzjmFWBIiFd8M0x+ZdX0P9R4lADg1mgP8C7PxGOWuQ=="],
+
+    "htmlparser2": ["htmlparser2@10.1.0", "", { "dependencies": { "domelementtype": "^2.3.0", "domhandler": "^5.0.3", "domutils": "^3.2.2", "entities": "^7.0.1" } }, "sha512-VTZkM9GWRAtEpveh7MSF6SjjrpNVNNVJfFup7xTY3UpFtm67foy9HDVXneLtFVt4pMz5kZtgNcvCniNFb1hlEQ=="],
+
+    "human-id": ["human-id@4.1.3", "", { "bin": { "human-id": "dist/cli.js" } }, "sha512-tsYlhAYpjCKa//8rXZ9DqKEawhPoSytweBC2eNvcaDK+57RZLHGqNs3PZTQO6yekLFSuvA6AlnAfrw1uBvtb+Q=="],
+
+    "iconv-lite": ["iconv-lite@0.7.2", "", { "dependencies": { "safer-buffer": ">= 2.1.2 < 3.0.0" } }, "sha512-im9DjEDQ55s9fL4EYzOAv0yMqmMBSZp6G0VvFyTMPKWxiSBHUj9NW/qqLmXUwXrrM7AvqSlTCfvqRb0cM8yYqw=="],
+
+    "ignore": ["ignore@5.3.2", "", {}, "sha512-hsBTNUqQTDwkWtcdYI2i06Y/nUBEsNEDJKjWdigLvegy8kDuJAS8uRlpkkcQpyEXL0Z/pjDy5HBmMjRCJ2gq+g=="],
+
+    "is-docker": ["is-docker@2.2.1", "", { "bin": { "is-docker": "cli.js" } }, "sha512-F+i2BKsFrH66iaUFc0woD8sLy8getkwTwtOBjvs56Cx4CgJDeKQeqfz8wAYiSb8JOprWhHH5p77PbmYCvvUuXQ=="],
+
+    "is-extglob": ["is-extglob@2.1.1", "", {}, "sha512-SbKbANkN603Vi4jEZv49LeVJMn4yGwsbzZworEoyEiutsN3nJYdbO36zfhGJ6QEDpOZIFkDtnq5JRxmvl3jsoQ=="],
+
+    "is-glob": ["is-glob@4.0.3", "", { "dependencies": { "is-extglob": "^2.1.1" } }, "sha512-xelSayHH36ZgE7ZWhli7pW34hNbNl8Ojv5KVmkJD4hBdD3th8Tfk9vYasLM+mXWOZhFkgZfxhLSnrwRr4elSSg=="],
+
+    "is-number": ["is-number@7.0.0", "", {}, "sha512-41Cifkg6e8TylSpdtTpeLVMqvSBEVzTttHvERD741+pnZ8ANv0004MRL43QKPDlK9cGvNp6NZWZUBlbGXYxxng=="],
+
+    "is-plain-obj": ["is-plain-obj@4.1.0", "", {}, "sha512-+Pgi+vMuUNkJyExiMBt5IlFoMyKnr5zhJ4Uspz58WOhBF5QoIZkFyNHIbBAtHwzVAgk5RtndVNsDRN61/mmDqg=="],
+
+    "is-potential-custom-element-name": ["is-potential-custom-element-name@1.0.1", "", {}, "sha512-bCYeRA2rVibKZd+s2625gGnGF/t7DSqDs4dP7CrLA1m7jKWz6pps0LpYLJN8Q64HtmPKJ1hrN3nzPNKFEKOUiQ=="],
+
+    "is-subdir": ["is-subdir@1.2.0", "", { "dependencies": { "better-path-resolve": "1.0.0" } }, "sha512-2AT6j+gXe/1ueqbW6fLZJiIw3F8iXGJtt0yDrZaBhAZEG1raiTxKWU+IPqMCzQAXOUCKdA4UDMgacKH25XG2Cw=="],
+
+    "is-windows": ["is-windows@1.0.2", "", {}, "sha512-eXK1UInq2bPmjyX6e3VHIzMLobc4J94i4AWn+Hpq3OU5KkrRC96OAcR3PRJ/pGu6m8TRnBHP9dkXQVsT/COVIA=="],
+
+    "is-wsl": ["is-wsl@2.2.0", "", { "dependencies": { "is-docker": "^2.0.0" } }, "sha512-fKzAra0rGJUUBwGBgNkHZuToZcn+TtXHpeCgmkMJMMYx1sQDYaCSyjJBSCa2nH1DGm7s3n1oBnohoVTBaN7Lww=="],
+
+    "isexe": ["isexe@2.0.0", "", {}, "sha512-RHxMLp9lnKHGHRng9QFhRCMbYAcVpn69smSGcq3f36xjgVVWThj4qqLbTLlq7Ssj8B+fIQ1EuCEGI2lKsyQeIw=="],
+
+    "js-yaml": ["js-yaml@4.1.1", "", { "dependencies": { "argparse": "^2.0.1" }, "bin": { "js-yaml": "bin/js-yaml.js" } }, "sha512-qQKT4zQxXl8lLwBtHMWwaTcGfFOZviOJet3Oy/xmGk2gZH677CJM9EvtfdSkgWcATZhj/55JZ0rmy3myCT5lsA=="],
+
+    "jsdom": ["jsdom@29.0.2", "", { "dependencies": { "@asamuzakjp/css-color": "^5.1.5", "@asamuzakjp/dom-selector": "^7.0.6", "@bramus/specificity": "^2.4.2", "@csstools/css-syntax-patches-for-csstree": "^1.1.1", "@exodus/bytes": "^1.15.0", "css-tree": "^3.2.1", "data-urls": "^7.0.0", "decimal.js": "^10.6.0", "html-encoding-sniffer": "^6.0.0", "is-potential-custom-element-name": "^1.0.1", "lru-cache": "^11.2.7", "parse5": "^8.0.0", "saxes": "^6.0.0", "symbol-tree": "^3.2.4", "tough-cookie": "^6.0.1", "undici": "^7.24.5", "w3c-xmlserializer": "^5.0.0", "webidl-conversions": "^8.0.1", "whatwg-mimetype": "^5.0.0", "whatwg-url": "^16.0.1", "xml-name-validator": "^5.0.0" }, "peerDependencies": { "canvas": "^3.0.0" }, "optionalPeers": ["canvas"] }, "sha512-9VnGEBosc/ZpwyOsJBCQ/3I5p7Q5ngOY14a9bf5btenAORmZfDse1ZEheMiWcJ3h81+Fv7HmJFdS0szo/waF2w=="],
+
+    "jsonfile": ["jsonfile@4.0.0", "", { "optionalDependencies": { "graceful-fs": "^4.1.6" } }, "sha512-m6F1R3z8jjlf2imQHS2Qez5sjKWQzbuuhuJ/FKYFRZvPE3PuHcSMVZzfsLhGVOkfd20obL5SWEBew5ShlquNxg=="],
+
+    "lighthouse-logger": ["lighthouse-logger@2.0.2", "", { "dependencies": { "debug": "^4.4.1", "marky": "^1.2.2" } }, "sha512-vWl2+u5jgOQuZR55Z1WM0XDdrJT6mzMP8zHUct7xTlWhuQs+eV0g+QL0RQdFjT54zVmbhLCP8vIVpy1wGn/gCg=="],
+
+    "linkedom": ["linkedom@0.18.12", "", { "dependencies": { "css-select": "^5.1.0", "cssom": "^0.5.0", "html-escaper": "^3.0.3", "htmlparser2": "^10.0.0", "uhyphen": "^0.2.0" }, "peerDependencies": { "canvas": ">= 2" }, "optionalPeers": ["canvas"] }, "sha512-jalJsOwIKuQJSeTvsgzPe9iJzyfVaEJiEXl+25EkKevsULHvMJzpNqwvj1jOESWdmgKDiXObyjOYwlUqG7wo1Q=="],
+
+    "locate-path": ["locate-path@5.0.0", "", { "dependencies": { "p-locate": "^4.1.0" } }, "sha512-t7hw9pI+WvuwNJXwk5zVHpyhIqzg2qTlklJOf0mVxGSbe3Fp2VieZcduNYjaLDoy6p9uGpQEGWG87WpMKlNq8g=="],
+
+    "lodash.startcase": ["lodash.startcase@4.4.0", "", {}, "sha512-+WKqsK294HMSc2jEbNgpHpd0JfIBhp7rEV4aqXWqFr6AlXov+SlcgB1Fv01y2kGe3Gc8nMW7VA0SrGuSkRfIEg=="],
+
+    "longest-streak": ["longest-streak@3.1.0", "", {}, "sha512-9Ri+o0JYgehTaVBBDoMqIl8GXtbWg711O3srftcHhZ0dqnETqLaoIK0x17fUw9rFSlK/0NlsKe0Ahhyl5pXE2g=="],
+
+    "lru-cache": ["lru-cache@11.3.5", "", {}, "sha512-NxVFwLAnrd9i7KUBxC4DrUhmgjzOs+1Qm50D3oF1/oL+r1NpZ4gA7xvG0/zJ8evR7zIKn4vLf7qTNduWFtCrRw=="],
+
+    "markdown-table": ["markdown-table@3.0.4", "", {}, "sha512-wiYz4+JrLyb/DqW2hkFJxP7Vd7JuTDm77fvbM8VfEQdmSMqcImWeeRbHwZjBjIFki/VaMK2BhFi7oUUZeM5bqw=="],
+
+    "marky": ["marky@1.3.0", "", {}, "sha512-ocnPZQLNpvbedwTy9kNrQEsknEfgvcLMvOtz3sFeWApDq1MXH1TqkCIx58xlpESsfwQOnuBO9beyQuNGzVvuhQ=="],
+
+    "mathml-to-latex": ["mathml-to-latex@1.5.0", "", { "dependencies": { "@xmldom/xmldom": "^0.8.10" } }, "sha512-rrWn0eEvcEcdMM4xfHcSGIy+i01DX9byOdXTLWg+w1iJ6O6ohP5UXY1dVzNUZLhzfl3EGcRekWLhY7JT5Omaew=="],
+
+    "mdast-util-find-and-replace": ["mdast-util-find-and-replace@3.0.2", "", { "dependencies": { "@types/mdast": "^4.0.0", "escape-string-regexp": "^5.0.0", "unist-util-is": "^6.0.0", "unist-util-visit-parents": "^6.0.0" } }, "sha512-Tmd1Vg/m3Xz43afeNxDIhWRtFZgM2VLyaf4vSTYwudTyeuTneoL3qtWMA5jeLyz/O1vDJmmV4QuScFCA2tBPwg=="],
+
+    "mdast-util-from-markdown": ["mdast-util-from-markdown@2.0.3", "", { "dependencies": { "@types/mdast": "^4.0.0", "@types/unist": "^3.0.0", "decode-named-character-reference": "^1.0.0", "devlop": "^1.0.0", "mdast-util-to-string": "^4.0.0", "micromark": "^4.0.0", "micromark-util-decode-numeric-character-reference": "^2.0.0", "micromark-util-decode-string": "^2.0.0", "micromark-util-normalize-identifier": "^2.0.0", "micromark-util-symbol": "^2.0.0", "micromark-util-types": "^2.0.0", "unist-util-stringify-position": "^4.0.0" } }, "sha512-W4mAWTvSlKvf8L6J+VN9yLSqQ9AOAAvHuoDAmPkz4dHf553m5gVj2ejadHJhoJmcmxEnOv6Pa8XJhpxE93kb8Q=="],
+
+    "mdast-util-gfm": ["mdast-util-gfm@3.1.0", "", { "dependencies": { "mdast-util-from-markdown": "^2.0.0", "mdast-util-gfm-autolink-literal": "^2.0.0", "mdast-util-gfm-footnote": "^2.0.0", "mdast-util-gfm-strikethrough": "^2.0.0", "mdast-util-gfm-table": "^2.0.0", "mdast-util-gfm-task-list-item": "^2.0.0", "mdast-util-to-markdown": "^2.0.0" } }, "sha512-0ulfdQOM3ysHhCJ1p06l0b0VKlhU0wuQs3thxZQagjcjPrlFRqY215uZGHHJan9GEAXd9MbfPjFJz+qMkVR6zQ=="],
+
+    "mdast-util-gfm-autolink-literal": ["mdast-util-gfm-autolink-literal@2.0.1", "", { "dependencies": { "@types/mdast": "^4.0.0", "ccount": "^2.0.0", "devlop": "^1.0.0", "mdast-util-find-and-replace": "^3.0.0", "micromark-util-character": "^2.0.0" } }, "sha512-5HVP2MKaP6L+G6YaxPNjuL0BPrq9orG3TsrZ9YXbA3vDw/ACI4MEsnoDpn6ZNm7GnZgtAcONJyPhOP8tNJQavQ=="],
+
+    "mdast-util-gfm-footnote": ["mdast-util-gfm-footnote@2.1.0", "", { "dependencies": { "@types/mdast": "^4.0.0", "devlop": "^1.1.0", "mdast-util-from-markdown": "^2.0.0", "mdast-util-to-markdown": "^2.0.0", "micromark-util-normalize-identifier": "^2.0.0" } }, "sha512-sqpDWlsHn7Ac9GNZQMeUzPQSMzR6Wv0WKRNvQRg0KqHh02fpTz69Qc1QSseNX29bhz1ROIyNyxExfawVKTm1GQ=="],
+
+    "mdast-util-gfm-strikethrough": ["mdast-util-gfm-strikethrough@2.0.0", "", { "dependencies": { "@types/mdast": "^4.0.0", "mdast-util-from-markdown": "^2.0.0", "mdast-util-to-markdown": "^2.0.0" } }, "sha512-mKKb915TF+OC5ptj5bJ7WFRPdYtuHv0yTRxK2tJvi+BDqbkiG7h7u/9SI89nRAYcmap2xHQL9D+QG/6wSrTtXg=="],
+
+    "mdast-util-gfm-table": ["mdast-util-gfm-table@2.0.0", "", { "dependencies": { "@types/mdast": "^4.0.0", "devlop": "^1.0.0", "markdown-table": "^3.0.0", "mdast-util-from-markdown": "^2.0.0", "mdast-util-to-markdown": "^2.0.0" } }, "sha512-78UEvebzz/rJIxLvE7ZtDd/vIQ0RHv+3Mh5DR96p7cS7HsBhYIICDBCu8csTNWNO6tBWfqXPWekRuj2FNOGOZg=="],
+
+    "mdast-util-gfm-task-list-item": ["mdast-util-gfm-task-list-item@2.0.0", "", { "dependencies": { "@types/mdast": "^4.0.0", "devlop": "^1.0.0", "mdast-util-from-markdown": "^2.0.0", "mdast-util-to-markdown": "^2.0.0" } }, "sha512-IrtvNvjxC1o06taBAVJznEnkiHxLFTzgonUdy8hzFVeDun0uTjxxrRGVaNFqkU1wJR3RBPEfsxmU6jDWPofrTQ=="],
+
+    "mdast-util-phrasing": ["mdast-util-phrasing@4.1.0", "", { "dependencies": { "@types/mdast": "^4.0.0", "unist-util-is": "^6.0.0" } }, "sha512-TqICwyvJJpBwvGAMZjj4J2n0X8QWp21b9l0o7eXyVJ25YNWYbJDVIyD1bZXE6WtV6RmKJVYmQAKWa0zWOABz2w=="],
+
+    "mdast-util-to-markdown": ["mdast-util-to-markdown@2.1.2", "", { "dependencies": { "@types/mdast": "^4.0.0", "@types/unist": "^3.0.0", "longest-streak": "^3.0.0", "mdast-util-phrasing": "^4.0.0", "mdast-util-to-string": "^4.0.0", "micromark-util-classify-character": "^2.0.0", "micromark-util-decode-string": "^2.0.0", "unist-util-visit": "^5.0.0", "zwitch": "^2.0.0" } }, "sha512-xj68wMTvGXVOKonmog6LwyJKrYXZPvlwabaryTjLh9LuvovB/KAH+kvi8Gjj+7rJjsFi23nkUxRQv1KqSroMqA=="],
+
+    "mdast-util-to-string": ["mdast-util-to-string@4.0.0", "", { "dependencies": { "@types/mdast": "^4.0.0" } }, "sha512-0H44vDimn51F0YwvxSJSm0eCDOJTRlmN0R1yBh4HLj9wiV1Dn0QoXGbvFAWj2hSItVTlCmBF1hqKlIyUBVFLPg=="],
+
+    "mdn-data": ["mdn-data@2.27.1", "", {}, "sha512-9Yubnt3e8A0OKwxYSXyhLymGW4sCufcLG6VdiDdUGVkPhpqLxlvP5vl1983gQjJl3tqbrM731mjaZaP68AgosQ=="],
+
+    "merge2": ["merge2@1.4.1", "", {}, "sha512-8q7VEgMJW4J8tcfVPy8g09NcQwZdbwFEqhe/WZkoIzjn/3TGDwtOCYtXGxA3O8tPzpczCCDgv+P2P5y00ZJOOg=="],
+
+    "micromark": ["micromark@4.0.2", "", { "dependencies": { "@types/debug": "^4.0.0", "debug": "^4.0.0", "decode-named-character-reference": "^1.0.0", "devlop": "^1.0.0", "micromark-core-commonmark": "^2.0.0", "micromark-factory-space": "^2.0.0", "micromark-util-character": "^2.0.0", "micromark-util-chunked": "^2.0.0", "micromark-util-combine-extensions": "^2.0.0", "micromark-util-decode-numeric-character-reference": "^2.0.0", "micromark-util-encode": "^2.0.0", "micromark-util-normalize-identifier": "^2.0.0", "micromark-util-resolve-all": "^2.0.0", "micromark-util-sanitize-uri": "^2.0.0", "micromark-util-subtokenize": "^2.0.0", "micromark-util-symbol": "^2.0.0", "micromark-util-types": "^2.0.0" } }, "sha512-zpe98Q6kvavpCr1NPVSCMebCKfD7CA2NqZ+rykeNhONIJBpc1tFKt9hucLGwha3jNTNI8lHpctWJWoimVF4PfA=="],
+
+    "micromark-core-commonmark": ["micromark-core-commonmark@2.0.3", "", { "dependencies": { "decode-named-character-reference": "^1.0.0", "devlop": "^1.0.0", "micromark-factory-destination": "^2.0.0", "micromark-factory-label": "^2.0.0", "micromark-factory-space": "^2.0.0", "micromark-factory-title": "^2.0.0", "micromark-factory-whitespace": "^2.0.0", "micromark-util-character": "^2.0.0", "micromark-util-chunked": "^2.0.0", "micromark-util-classify-character": "^2.0.0", "micromark-util-html-tag-name": "^2.0.0", "micromark-util-normalize-identifier": "^2.0.0", "micromark-util-resolve-all": "^2.0.0", "micromark-util-subtokenize": "^2.0.0", "micromark-util-symbol": "^2.0.0", "micromark-util-types": "^2.0.0" } }, "sha512-RDBrHEMSxVFLg6xvnXmb1Ayr2WzLAWjeSATAoxwKYJV94TeNavgoIdA0a9ytzDSVzBy2YKFK+emCPOEibLeCrg=="],
+
+    "micromark-extension-gfm": ["micromark-extension-gfm@3.0.0", "", { "dependencies": { "micromark-extension-gfm-autolink-literal": "^2.0.0", "micromark-extension-gfm-footnote": "^2.0.0", "micromark-extension-gfm-strikethrough": "^2.0.0", "micromark-extension-gfm-table": "^2.0.0", "micromark-extension-gfm-tagfilter": "^2.0.0", "micromark-extension-gfm-task-list-item": "^2.0.0", "micromark-util-combine-extensions": "^2.0.0", "micromark-util-types": "^2.0.0" } }, "sha512-vsKArQsicm7t0z2GugkCKtZehqUm31oeGBV/KVSorWSy8ZlNAv7ytjFhvaryUiCUJYqs+NoE6AFhpQvBTM6Q4w=="],
+
+    "micromark-extension-gfm-autolink-literal": ["micromark-extension-gfm-autolink-literal@2.1.0", "", { "dependencies": { "micromark-util-character": "^2.0.0", "micromark-util-sanitize-uri": "^2.0.0", "micromark-util-symbol": "^2.0.0", "micromark-util-types": "^2.0.0" } }, "sha512-oOg7knzhicgQ3t4QCjCWgTmfNhvQbDDnJeVu9v81r7NltNCVmhPy1fJRX27pISafdjL+SVc4d3l48Gb6pbRypw=="],
+
+    "micromark-extension-gfm-footnote": ["micromark-extension-gfm-footnote@2.1.0", "", { "dependencies": { "devlop": "^1.0.0", "micromark-core-commonmark": "^2.0.0", "micromark-factory-space": "^2.0.0", "micromark-util-character": "^2.0.0", "micromark-util-normalize-identifier": "^2.0.0", "micromark-util-sanitize-uri": "^2.0.0", "micromark-util-symbol": "^2.0.0", "micromark-util-types": "^2.0.0" } }, "sha512-/yPhxI1ntnDNsiHtzLKYnE3vf9JZ6cAisqVDauhp4CEHxlb4uoOTxOCJ+9s51bIB8U1N1FJ1RXOKTIlD5B/gqw=="],
+
+    "micromark-extension-gfm-strikethrough": ["micromark-extension-gfm-strikethrough@2.1.0", "", { "dependencies": { "devlop": "^1.0.0", "micromark-util-chunked": "^2.0.0", "micromark-util-classify-character": "^2.0.0", "micromark-util-resolve-all": "^2.0.0", "micromark-util-symbol": "^2.0.0", "micromark-util-types": "^2.0.0" } }, "sha512-ADVjpOOkjz1hhkZLlBiYA9cR2Anf8F4HqZUO6e5eDcPQd0Txw5fxLzzxnEkSkfnD0wziSGiv7sYhk/ktvbf1uw=="],
+
+    "micromark-extension-gfm-table": ["micromark-extension-gfm-table@2.1.1", "", { "dependencies": { "devlop": "^1.0.0", "micromark-factory-space": "^2.0.0", "micromark-util-character": "^2.0.0", "micromark-util-symbol": "^2.0.0", "micromark-util-types": "^2.0.0" } }, "sha512-t2OU/dXXioARrC6yWfJ4hqB7rct14e8f7m0cbI5hUmDyyIlwv5vEtooptH8INkbLzOatzKuVbQmAYcbWoyz6Dg=="],
+
+    "micromark-extension-gfm-tagfilter": ["micromark-extension-gfm-tagfilter@2.0.0", "", { "dependencies": { "micromark-util-types": "^2.0.0" } }, "sha512-xHlTOmuCSotIA8TW1mDIM6X2O1SiX5P9IuDtqGonFhEK0qgRI4yeC6vMxEV2dgyr2TiD+2PQ10o+cOhdVAcwfg=="],
+
+    "micromark-extension-gfm-task-list-item": ["micromark-extension-gfm-task-list-item@2.1.0", "", { "dependencies": { "devlop": "^1.0.0", "micromark-factory-space": "^2.0.0", "micromark-util-character": "^2.0.0", "micromark-util-symbol": "^2.0.0", "micromark-util-types": "^2.0.0" } }, "sha512-qIBZhqxqI6fjLDYFTBIa4eivDMnP+OZqsNwmQ3xNLE4Cxwc+zfQEfbs6tzAo2Hjq+bh6q5F+Z8/cksrLFYWQQw=="],
+
+    "micromark-factory-destination": ["micromark-factory-destination@2.0.1", "", { "dependencies": { "micromark-util-character": "^2.0.0", "micromark-util-symbol": "^2.0.0", "micromark-util-types": "^2.0.0" } }, "sha512-Xe6rDdJlkmbFRExpTOmRj9N3MaWmbAgdpSrBQvCFqhezUn4AHqJHbaEnfbVYYiexVSs//tqOdY/DxhjdCiJnIA=="],
+
+    "micromark-factory-label": ["micromark-factory-label@2.0.1", "", { "dependencies": { "devlop": "^1.0.0", "micromark-util-character": "^2.0.0", "micromark-util-symbol": "^2.0.0", "micromark-util-types": "^2.0.0" } }, "sha512-VFMekyQExqIW7xIChcXn4ok29YE3rnuyveW3wZQWWqF4Nv9Wk5rgJ99KzPvHjkmPXF93FXIbBp6YdW3t71/7Vg=="],
+
+    "micromark-factory-space": ["micromark-factory-space@2.0.1", "", { "dependencies": { "micromark-util-character": "^2.0.0", "micromark-util-types": "^2.0.0" } }, "sha512-zRkxjtBxxLd2Sc0d+fbnEunsTj46SWXgXciZmHq0kDYGnck/ZSGj9/wULTV95uoeYiK5hRXP2mJ98Uo4cq/LQg=="],
+
+    "micromark-factory-title": ["micromark-factory-title@2.0.1", "", { "dependencies": { "micromark-factory-space": "^2.0.0", "micromark-util-character": "^2.0.0", "micromark-util-symbol": "^2.0.0", "micromark-util-types": "^2.0.0" } }, "sha512-5bZ+3CjhAd9eChYTHsjy6TGxpOFSKgKKJPJxr293jTbfry2KDoWkhBb6TcPVB4NmzaPhMs1Frm9AZH7OD4Cjzw=="],
+
+    "micromark-factory-whitespace": ["micromark-factory-whitespace@2.0.1", "", { "dependencies": { "micromark-factory-space": "^2.0.0", "micromark-util-character": "^2.0.0", "micromark-util-symbol": "^2.0.0", "micromark-util-types": "^2.0.0" } }, "sha512-Ob0nuZ3PKt/n0hORHyvoD9uZhr+Za8sFoP+OnMcnWK5lngSzALgQYKMr9RJVOWLqQYuyn6ulqGWSXdwf6F80lQ=="],
+
+    "micromark-util-character": ["micromark-util-character@2.1.1", "", { "dependencies": { "micromark-util-symbol": "^2.0.0", "micromark-util-types": "^2.0.0" } }, "sha512-wv8tdUTJ3thSFFFJKtpYKOYiGP2+v96Hvk4Tu8KpCAsTMs6yi+nVmGh1syvSCsaxz45J6Jbw+9DD6g97+NV67Q=="],
+
+    "micromark-util-chunked": ["micromark-util-chunked@2.0.1", "", { "dependencies": { "micromark-util-symbol": "^2.0.0" } }, "sha512-QUNFEOPELfmvv+4xiNg2sRYeS/P84pTW0TCgP5zc9FpXetHY0ab7SxKyAQCNCc1eK0459uoLI1y5oO5Vc1dbhA=="],
+
+    "micromark-util-classify-character": ["micromark-util-classify-character@2.0.1", "", { "dependencies": { "micromark-util-character": "^2.0.0", "micromark-util-symbol": "^2.0.0", "micromark-util-types": "^2.0.0" } }, "sha512-K0kHzM6afW/MbeWYWLjoHQv1sgg2Q9EccHEDzSkxiP/EaagNzCm7T/WMKZ3rjMbvIpvBiZgwR3dKMygtA4mG1Q=="],
+
+    "micromark-util-combine-extensions": ["micromark-util-combine-extensions@2.0.1", "", { "dependencies": { "micromark-util-chunked": "^2.0.0", "micromark-util-types": "^2.0.0" } }, "sha512-OnAnH8Ujmy59JcyZw8JSbK9cGpdVY44NKgSM7E9Eh7DiLS2E9RNQf0dONaGDzEG9yjEl5hcqeIsj4hfRkLH/Bg=="],
+
+    "micromark-util-decode-numeric-character-reference": ["micromark-util-decode-numeric-character-reference@2.0.2", "", { "dependencies": { "micromark-util-symbol": "^2.0.0" } }, "sha512-ccUbYk6CwVdkmCQMyr64dXz42EfHGkPQlBj5p7YVGzq8I7CtjXZJrubAYezf7Rp+bjPseiROqe7G6foFd+lEuw=="],
+
+    "micromark-util-decode-string": ["micromark-util-decode-string@2.0.1", "", { "dependencies": { "decode-named-character-reference": "^1.0.0", "micromark-util-character": "^2.0.0", "micromark-util-decode-numeric-character-reference": "^2.0.0", "micromark-util-symbol": "^2.0.0" } }, "sha512-nDV/77Fj6eH1ynwscYTOsbK7rR//Uj0bZXBwJZRfaLEJ1iGBR6kIfNmlNqaqJf649EP0F3NWNdeJi03elllNUQ=="],
+
+    "micromark-util-encode": ["micromark-util-encode@2.0.1", "", {}, "sha512-c3cVx2y4KqUnwopcO9b/SCdo2O67LwJJ/UyqGfbigahfegL9myoEFoDYZgkT7f36T0bLrM9hZTAaAyH+PCAXjw=="],
+
+    "micromark-util-html-tag-name": ["micromark-util-html-tag-name@2.0.1", "", {}, "sha512-2cNEiYDhCWKI+Gs9T0Tiysk136SnR13hhO8yW6BGNyhOC4qYFnwF1nKfD3HFAIXA5c45RrIG1ub11GiXeYd1xA=="],
+
+    "micromark-util-normalize-identifier": ["micromark-util-normalize-identifier@2.0.1", "", { "dependencies": { "micromark-util-symbol": "^2.0.0" } }, "sha512-sxPqmo70LyARJs0w2UclACPUUEqltCkJ6PhKdMIDuJ3gSf/Q+/GIe3WKl0Ijb/GyH9lOpUkRAO2wp0GVkLvS9Q=="],
+
+    "micromark-util-resolve-all": ["micromark-util-resolve-all@2.0.1", "", { "dependencies": { "micromark-util-types": "^2.0.0" } }, "sha512-VdQyxFWFT2/FGJgwQnJYbe1jjQoNTS4RjglmSjTUlpUMa95Htx9NHeYW4rGDJzbjvCsl9eLjMQwGeElsqmzcHg=="],
+
+    "micromark-util-sanitize-uri": ["micromark-util-sanitize-uri@2.0.1", "", { "dependencies": { "micromark-util-character": "^2.0.0", "micromark-util-encode": "^2.0.0", "micromark-util-symbol": "^2.0.0" } }, "sha512-9N9IomZ/YuGGZZmQec1MbgxtlgougxTodVwDzzEouPKo3qFWvymFHWcnDi2vzV1ff6kas9ucW+o3yzJK9YB1AQ=="],
+
+    "micromark-util-subtokenize": ["micromark-util-subtokenize@2.1.0", "", { "dependencies": { "devlop": "^1.0.0", "micromark-util-chunked": "^2.0.0", "micromark-util-symbol": "^2.0.0", "micromark-util-types": "^2.0.0" } }, "sha512-XQLu552iSctvnEcgXw6+Sx75GflAPNED1qx7eBJ+wydBb2KCbRZe+NwvIEEMM83uml1+2WSXpBAcp9IUCgCYWA=="],
+
+    "micromark-util-symbol": ["micromark-util-symbol@2.0.1", "", {}, "sha512-vs5t8Apaud9N28kgCrRUdEed4UJ+wWNvicHLPxCa9ENlYuAY31M0ETy5y1vA33YoNPDFTghEbnh6efaE8h4x0Q=="],
+
+    "micromark-util-types": ["micromark-util-types@2.0.2", "", {}, "sha512-Yw0ECSpJoViF1qTU4DC6NwtC4aWGt1EkzaQB8KPPyCRR8z9TWeV0HbEFGTO+ZY1wB22zmxnJqhPyTpOVCpeHTA=="],
+
+    "micromatch": ["micromatch@4.0.8", "", { "dependencies": { "braces": "^3.0.3", "picomatch": "^2.3.1" } }, "sha512-PXwfBhYu0hBCPw8Dn0E+WDYb7af3dSLVWKi3HGv84IdF4TyFoC0ysxFd0Goxw7nSv4T/PzEJQxsYsEiFCKo2BA=="],
+
+    "mri": ["mri@1.2.0", "", {}, "sha512-tzzskb3bG8LvYGFF/mDTpq3jpI6Q9wc3LEmBaghu+DdCssd1FakN7Bc0hVNmEyGq1bq3RgfkCb3cmQLpNPOroA=="],
+
+    "ms": ["ms@2.1.3", "", {}, "sha512-6FlzubTLZG3J2a/NVCAleEhjzq5oxgHyaCU9yYXvcLsvoVaHJq/s5xXI6/XXP6tz7R9xAOtHnSO/tXtF3WRTlA=="],
+
+    "nth-check": ["nth-check@2.1.1", "", { "dependencies": { "boolbase": "^1.0.0" } }, "sha512-lqjrjmaOoAnWfMmBPL+XNnynZh2+swxiX3WUE0s4yEHI6m+AwrK2UZOimIRl3X/4QctVqS8AiZjFqyOGrMXb/w=="],
+
+    "outdent": ["outdent@0.5.0", "", {}, "sha512-/jHxFIzoMXdqPzTaCpFzAAWhpkSjZPF4Vsn6jAfNpmbH/ymsmd7Qc6VE9BGn0L6YMj6uwpQLxCECpus4ukKS9Q=="],
+
+    "p-filter": ["p-filter@2.1.0", "", { "dependencies": { "p-map": "^2.0.0" } }, "sha512-ZBxxZ5sL2HghephhpGAQdoskxplTwr7ICaehZwLIlfL6acuVgZPm8yBNuRAFBGEqtD/hmUeq9eqLg2ys9Xr/yw=="],
+
+    "p-limit": ["p-limit@2.3.0", "", { "dependencies": { "p-try": "^2.0.0" } }, "sha512-//88mFWSJx8lxCzwdAABTJL2MyWB12+eIY7MDL2SqLmAkeKU9qxRvWuSyTjm3FUmpBEMuFfckAIqEaVGUDxb6w=="],
+
+    "p-locate": ["p-locate@4.1.0", "", { "dependencies": { "p-limit": "^2.2.0" } }, "sha512-R79ZZ/0wAxKGu3oYMlz8jy/kbhsNrS7SKZ7PxEHBgJ5+F2mtFW2fK2cOtBh1cHYkQsbzFV7I+EoRKe6Yt0oK7A=="],
+
+    "p-map": ["p-map@2.1.0", "", {}, "sha512-y3b8Kpd8OAN444hxfBbFfj1FY/RjtTd8tzYwhUqNYXx0fXx2iX4maP4Qr6qhIKbQXI02wTLAda4fYUbDagTUFw=="],
+
+    "p-try": ["p-try@2.2.0", "", {}, "sha512-R4nPAVTAU0B9D35/Gk3uJf/7XYbQcyohSKdvAxIRSNghFl4e71hVoGnBNQz9cWaXxO2I10KTC+3jMdvvoKw6dQ=="],
+
+    "package-manager-detector": ["package-manager-detector@0.2.11", "", { "dependencies": { "quansync": "^0.2.7" } }, "sha512-BEnLolu+yuz22S56CU1SUKq3XC3PkwD5wv4ikR4MfGvnRVcmzXR9DwSlW2fEamyTPyXHomBJRzgapeuBvRNzJQ=="],
+
+    "parse5": ["parse5@7.3.0", "", { "dependencies": { "entities": "^6.0.0" } }, "sha512-IInvU7fabl34qmi9gY8XOVxhYyMyuH2xUNpb2q8/Y+7552KlejkRvqvD19nMoUW/uQGGbqNpA6Tufu5FL5BZgw=="],
+
+    "path-exists": ["path-exists@4.0.0", "", {}, "sha512-ak9Qy5Q7jYb2Wwcey5Fpvg2KoAc/ZIhLSLOSBmRmygPsGwkVVt0fZa0qrtMz+m6tJTAHfZQ8FnmB4MG4LWy7/w=="],
+
+    "path-key": ["path-key@3.1.1", "", {}, "sha512-ojmeN0qd+y0jszEtoY48r0Peq5dwMEkIlCOu6Q5f41lfkswXuKtYrhgoTpLnyIcHm24Uhqx+5Tqm2InSwLhE6Q=="],
+
+    "path-type": ["path-type@4.0.0", "", {}, "sha512-gDKb8aZMDeD/tZWs9P6+q0J9Mwkdl6xMV8TjnGP3qJVJ06bdMgkbBlLU8IdfOsIsFz2BW1rNVT3XuNEl8zPAvw=="],
+
+    "picocolors": ["picocolors@1.1.1", "", {}, "sha512-xceH2snhtb5M9liqDsmEw56le376mTZkEX/jEb/RxNFyegNul7eNslCXP9FDj/Lcu0X8KEyMceP2ntpaHrDEVA=="],
+
+    "picomatch": ["picomatch@2.3.2", "", {}, "sha512-V7+vQEJ06Z+c5tSye8S+nHUfI51xoXIXjHQ99cQtKUkQqqO1kO/KCJUfZXuB47h/YBlDhah2H3hdUGXn8ie0oA=="],
+
+    "pify": ["pify@4.0.1", "", {}, "sha512-uB80kBFb/tfd68bVleG9T5GGsGPjJrLAUpR5PZIrhBnIaRTQRjqdJSsIKkOP6OAIFbj7GOrcudc5pNjZ+geV2g=="],
+
+    "prettier": ["prettier@2.8.8", "", { "bin": { "prettier": "bin-prettier.js" } }, "sha512-tdN8qQGvNjw4CHbY+XXk0JgCXn9QiF21a55rBe5LJAU+kDyC4WQn4+awm2Xfk2lQMk5fKup9XgzTZtGkjBdP9Q=="],
+
+    "punycode": ["punycode@2.3.1", "", {}, "sha512-vYt7UD1U9Wg6138shLtLOvdAu+8DsC/ilFtEVHcH+wydcSpNE20AfSOduf6MkRFahL5FY7X1oU7nKVZFtfq8Fg=="],
+
+    "quansync": ["quansync@0.2.11", "", {}, "sha512-AifT7QEbW9Nri4tAwR5M/uzpBuqfZf+zwaEM/QkzEjj7NBuFD2rBuy0K3dE+8wltbezDV7JMA0WfnCPYRSYbXA=="],
+
+    "queue-microtask": ["queue-microtask@1.2.3", "", {}, "sha512-NuaNSa6flKT5JaSYQzJok04JzTL1CA6aGhv5rfLW3PgqA+M2ChpZQnAC8h8i4ZFkBS8X5RqkDBHA7r4hej3K9A=="],
+
+    "read-yaml-file": ["read-yaml-file@1.1.0", "", { "dependencies": { "graceful-fs": "^4.1.5", "js-yaml": "^3.6.1", "pify": "^4.0.1", "strip-bom": "^3.0.0" } }, "sha512-VIMnQi/Z4HT2Fxuwg5KrY174U1VdUIASQVWXXyqtNRtxSr9IYkn1rsI6Tb6HsrHCmB7gVpNwX6JxPTHcH6IoTA=="],
+
+    "remark-gfm": ["remark-gfm@4.0.1", "", { "dependencies": { "@types/mdast": "^4.0.0", "mdast-util-gfm": "^3.0.0", "micromark-extension-gfm": "^3.0.0", "remark-parse": "^11.0.0", "remark-stringify": "^11.0.0", "unified": "^11.0.0" } }, "sha512-1quofZ2RQ9EWdeN34S79+KExV1764+wCUGop5CPL1WGdD0ocPpu91lzPGbwWMECpEpd42kJGQwzRfyov9j4yNg=="],
+
+    "remark-parse": ["remark-parse@11.0.0", "", { "dependencies": { "@types/mdast": "^4.0.0", "mdast-util-from-markdown": "^2.0.0", "micromark-util-types": "^2.0.0", "unified": "^11.0.0" } }, "sha512-FCxlKLNGknS5ba/1lmpYijMUzX2esxW5xQqjWxw2eHFfS2MSdaHVINFmhjo+qN1WhZhNimq0dZATN9pH0IDrpA=="],
+
+    "remark-stringify": ["remark-stringify@11.0.0", "", { "dependencies": { "@types/mdast": "^4.0.0", "mdast-util-to-markdown": "^2.0.0", "unified": "^11.0.0" } }, "sha512-1OSmLd3awB/t8qdoEOMazZkNsfVTeY4fTsgzcQFdXNq8ToTN4ZGwrMnlda4K6smTFKD+GRV6O48i6Z4iKgPPpw=="],
+
+    "require-from-string": ["require-from-string@2.0.2", "", {}, "sha512-Xf0nWe6RseziFMu+Ap9biiUbmplq6S9/p+7w7YXP/JBHhrUDDUhwa+vANyubuqfZWTveU//DYVGsDG7RKL/vEw=="],
+
+    "resolve-from": ["resolve-from@5.0.0", "", {}, "sha512-qYg9KP24dD5qka9J47d0aVky0N+b4fTU89LN9iDnjB5waksiC49rvMB0PrUJQGoTmH50XPiqOvAjDfaijGxYZw=="],
+
+    "reusify": ["reusify@1.1.0", "", {}, "sha512-g6QUff04oZpHs0eG5p83rFLhHeV00ug/Yf9nZM6fLeUrPguBTkTQOdpAWWspMh55TZfVQDPaN3NQJfbVRAxdIw=="],
+
+    "run-parallel": ["run-parallel@1.2.0", "", { "dependencies": { "queue-microtask": "^1.2.2" } }, "sha512-5l4VyZR86LZ/lDxZTR6jqL8AFE2S0IFLMP26AbjsLVADxHdhB/c0GUsH+y39UfCi3dzz8OlQuPmnaJOMoDHQBA=="],
+
+    "safer-buffer": ["safer-buffer@2.1.2", "", {}, "sha512-YZo3K82SD7Riyi0E1EQPojLz7kpepnSQI9IyPbHHg1XXXevb5dJI7tpyN2ADxGcQbHG7vcyRHk0cbwqcQriUtg=="],
+
+    "saxes": ["saxes@6.0.0", "", { "dependencies": { "xmlchars": "^2.2.0" } }, "sha512-xAg7SOnEhrm5zI3puOOKyy1OMcMlIJZYNJY7xLBwSze0UjhPLnWfj2GF2EpT0jmzaJKIWKHLsaSSajf35bcYnA=="],
+
+    "semver": ["semver@7.7.4", "", { "bin": { "semver": "bin/semver.js" } }, "sha512-vFKC2IEtQnVhpT78h1Yp8wzwrf8CM+MzKMHGJZfBtzhZNycRFnXsHk6E5TxIkkMsgNS7mdX3AGB7x2QM2di4lA=="],
+
+    "shebang-command": ["shebang-command@2.0.0", "", { "dependencies": { "shebang-regex": "^3.0.0" } }, "sha512-kHxr2zZpYtdmrN1qDjrrX/Z1rR1kG8Dx+gkpK1G4eXmvXswmcE1hTWBWYUzlraYw1/yZp6YuDY77YtvbN0dmDA=="],
+
+    "shebang-regex": ["shebang-regex@3.0.0", "", {}, "sha512-7++dFhtcx3353uBaq8DDR4NuxBetBzC7ZQOhmTQInHEd6bSrXdiEyzCvG07Z44UYdLShWUyXt5M/yhz8ekcb1A=="],
+
+    "signal-exit": ["signal-exit@4.1.0", "", {}, "sha512-bzyZ1e88w9O1iNJbKnOlvYTrWPDl46O1bG0D3XInv+9tkPrxrN8jUUTiFlDkkmKWgn1M6CfIA13SuGqOa9Korw=="],
+
+    "slash": ["slash@3.0.0", "", {}, "sha512-g9Q1haeby36OSStwb4ntCGGGaKsaVSjQ68fBxoQcutl5fS1vuY18H3wSt3jFyFtrkx+Kz0V1G85A4MyAdDMi2Q=="],
+
+    "source-map-js": ["source-map-js@1.2.1", "", {}, "sha512-UXWMKhLOwVKb728IUtQPXxfYU+usdybtUrK/8uGE8CQMvrhOpwvzDBwj0QhSL7MQc7vIsISBG8VQ8+IDQxpfQA=="],
+
+    "spawndamnit": ["spawndamnit@3.0.1", "", { "dependencies": { "cross-spawn": "^7.0.5", "signal-exit": "^4.0.1" } }, "sha512-MmnduQUuHCoFckZoWnXsTg7JaiLBJrKFj9UI2MbRPGaJeVpsLcVBu6P/IGZovziM/YBsellCmsprgNA+w0CzVg=="],
+
+    "sprintf-js": ["sprintf-js@1.0.3", "", {}, "sha512-D9cPgkvLlV3t3IzL0D0YLvGA9Ahk4PcvVwUbN0dSGr1aP0Nrt4AEnTUbuGvquEC0mA64Gqt1fzirlRs5ibXx8g=="],
+
+    "strip-ansi": ["strip-ansi@6.0.1", "", { "dependencies": { "ansi-regex": "^5.0.1" } }, "sha512-Y38VPSHcqkFrCpFnQ9vuSXmquuv5oXOKpGeT6aGrr3o3Gc9AlVa6JBfUSOCnbxGGZF+/0ooI7KrPuUSztUdU5A=="],
+
+    "strip-bom": ["strip-bom@3.0.0", "", {}, "sha512-vavAMRXOgBVNF6nyEEmL3DBK19iRpDcoIwW+swQ+CbGiu7lju6t+JklA1MHweoWtadgt4ISVUsXLyDq34ddcwA=="],
+
+    "symbol-tree": ["symbol-tree@3.2.4", "", {}, "sha512-9QNk5KwDF+Bvz+PyObkmSYjI5ksVUYtjW7AU22r2NKcfLJcXp96hkDWU3+XndOsUb+AQ9QhfzfCT2O+CNWT5Tw=="],
+
+    "temml": ["temml@0.13.2", "", {}, "sha512-n8fDRSsLscq9nh9j6z+FgkCvFMT0IJm6GCgwfzh+7AHT3Sfb4jFTQlsA6hVcF2dYYr3b66oDBVES95RfoukyrA=="],
+
+    "term-size": ["term-size@2.2.1", "", {}, "sha512-wK0Ri4fOGjv/XPy8SBHZChl8CM7uMc5VML7SqiQ0zG7+J5Vr+RMQDoHa2CNT6KHUnTGIXH34UDMkPzAUyapBZg=="],
+
+    "tldts": ["tldts@7.0.28", "", { "dependencies": { "tldts-core": "^7.0.28" }, "bin": { "tldts": "bin/cli.js" } }, "sha512-+Zg3vWhRUv8B1maGSTFdev9mjoo8Etn2Ayfs4cnjlD3CsGkxXX4QyW3j2WJ0wdjYcYmy7Lx2RDsZMhgCWafKIw=="],
+
+    "tldts-core": ["tldts-core@7.0.28", "", {}, "sha512-7W5Efjhsc3chVdFhqtaU0KtK32J37Zcr9RKtID54nG+tIpcY79CQK/veYPODxtD/LJ4Lue66jvrQzIX2Z2/pUQ=="],
+
+    "to-regex-range": ["to-regex-range@5.0.1", "", { "dependencies": { "is-number": "^7.0.0" } }, "sha512-65P7iz6X5yEr1cwcgvQxbbIw7Uk3gOy5dIdtZ4rDveLqhrdJP+Li/Hx6tyK0NEb+2GCyneCMJiGqrADCSNk8sQ=="],
+
+    "tough-cookie": ["tough-cookie@6.0.1", "", { "dependencies": { "tldts": "^7.0.5" } }, "sha512-LktZQb3IeoUWB9lqR5EWTHgW/VTITCXg4D21M+lvybRVdylLrRMnqaIONLVb5mav8vM19m44HIcGq4qASeu2Qw=="],
+
+    "tr46": ["tr46@6.0.0", "", { "dependencies": { "punycode": "^2.3.1" } }, "sha512-bLVMLPtstlZ4iMQHpFHTR7GAGj2jxi8Dg0s2h2MafAE4uSWF98FC/3MomU51iQAMf8/qDUbKWf5GxuvvVcXEhw=="],
+
+    "trough": ["trough@2.2.0", "", {}, "sha512-tmMpK00BjZiUyVyvrBK7knerNgmgvcV/KLVyuma/SC+TQN167GrMRciANTz09+k3zW8L8t60jWO1GpfkZdjTaw=="],
+
+    "turndown": ["turndown@7.2.2", "", { "dependencies": { "@mixmark-io/domino": "^2.2.0" } }, "sha512-1F7db8BiExOKxjSMU2b7if62D/XOyQyZbPKq/nUwopfgnHlqXHqQ0lvfUTeUIr1lZJzOPFn43dODyMSIfvWRKQ=="],
+
+    "turndown-plugin-gfm": ["turndown-plugin-gfm@1.0.2", "", {}, "sha512-vwz9tfvF7XN/jE0dGoBei3FXWuvll78ohzCZQuOb+ZjWrs3a0XhQVomJEb2Qh4VHTPNRO4GPZh0V7VRbiWwkRg=="],
+
+    "typescript": ["typescript@5.9.3", "", { "bin": { "tsc": "bin/tsc", "tsserver": "bin/tsserver" } }, "sha512-jl1vZzPDinLr9eUt3J/t7V6FgNEw9QjvBPdysz9KfQDD41fQrC2Y4vKQdiaUpFT4bXlb1RHhLpp8wtm6M5TgSw=="],
+
+    "uhyphen": ["uhyphen@0.2.0", "", {}, "sha512-qz3o9CHXmJJPGBdqzab7qAYuW8kQGKNEuoHFYrBwV6hWIMcpAmxDLXojcHfFr9US1Pe6zUswEIJIbLI610fuqA=="],
+
+    "undici": ["undici@7.25.0", "", {}, "sha512-xXnp4kTyor2Zq+J1FfPI6Eq3ew5h6Vl0F/8d9XU5zZQf1tX9s2Su1/3PiMmUANFULpmksxkClamIZcaUqryHsQ=="],
+
+    "undici-types": ["undici-types@7.18.2", "", {}, "sha512-AsuCzffGHJybSaRrmr5eHr81mwJU3kjw6M+uprWvCXiNeN9SOGwQ3Jn8jb8m3Z6izVgknn1R0FTCEAP2QrLY/w=="],
+
+    "unified": ["unified@11.0.5", "", { "dependencies": { "@types/unist": "^3.0.0", "bail": "^2.0.0", "devlop": "^1.0.0", "extend": "^3.0.0", "is-plain-obj": "^4.0.0", "trough": "^2.0.0", "vfile": "^6.0.0" } }, "sha512-xKvGhPWw3k84Qjh8bI3ZeJjqnyadK+GEFtazSfZv/rKeTkTjOJho6mFqh2SM96iIcZokxiOpg78GazTSg8+KHA=="],
+
+    "unist-util-is": ["unist-util-is@6.0.1", "", { "dependencies": { "@types/unist": "^3.0.0" } }, "sha512-LsiILbtBETkDz8I9p1dQ0uyRUWuaQzd/cuEeS1hoRSyW5E5XGmTzlwY1OrNzzakGowI9Dr/I8HVaw4hTtnxy8g=="],
+
+    "unist-util-stringify-position": ["unist-util-stringify-position@4.0.0", "", { "dependencies": { "@types/unist": "^3.0.0" } }, "sha512-0ASV06AAoKCDkS2+xw5RXJywruurpbC4JZSm7nr7MOt1ojAzvyyaO+UxZf18j8FCF6kmzCZKcAgN/yu2gm2XgQ=="],
+
+    "unist-util-visit": ["unist-util-visit@5.1.0", "", { "dependencies": { "@types/unist": "^3.0.0", "unist-util-is": "^6.0.0", "unist-util-visit-parents": "^6.0.0" } }, "sha512-m+vIdyeCOpdr/QeQCu2EzxX/ohgS8KbnPDgFni4dQsfSCtpz8UqDyY5GjRru8PDKuYn7Fq19j1CQ+nJSsGKOzg=="],
+
+    "unist-util-visit-parents": ["unist-util-visit-parents@6.0.2", "", { "dependencies": { "@types/unist": "^3.0.0", "unist-util-is": "^6.0.0" } }, "sha512-goh1s1TBrqSqukSc8wrjwWhL0hiJxgA8m4kFxGlQ+8FYQ3C/m11FcTs4YYem7V664AhHVvgoQLk890Ssdsr2IQ=="],
+
+    "universalify": ["universalify@0.1.2", "", {}, "sha512-rBJeI5CXAlmy1pV+617WB9J63U6XcazHHF2f2dbJix4XzpUF0RS3Zbj0FGIOCAva5P/d/GBOYaACQ1w+0azUkg=="],
+
+    "vfile": ["vfile@6.0.3", "", { "dependencies": { "@types/unist": "^3.0.0", "vfile-message": "^4.0.0" } }, "sha512-KzIbH/9tXat2u30jf+smMwFCsno4wHVdNmzFyL+T/L3UGqqk6JKfVqOFOZEpZSHADH1k40ab6NUIXZq422ov3Q=="],
+
+    "vfile-message": ["vfile-message@4.0.3", "", { "dependencies": { "@types/unist": "^3.0.0", "unist-util-stringify-position": "^4.0.0" } }, "sha512-QTHzsGd1EhbZs4AsQ20JX1rC3cOlt/IWJruk893DfLRr57lcnOeMaWG4K0JrRta4mIJZKth2Au3mM3u03/JWKw=="],
+
+    "w3c-xmlserializer": ["w3c-xmlserializer@5.0.0", "", { "dependencies": { "xml-name-validator": "^5.0.0" } }, "sha512-o8qghlI8NZHU1lLPrpi2+Uq7abh4GGPpYANlalzWxyWteJOCsr/P+oPBA49TOLu5FTZO4d3F9MnWJfiMo4BkmA=="],
+
+    "webidl-conversions": ["webidl-conversions@8.0.1", "", {}, "sha512-BMhLD/Sw+GbJC21C/UgyaZX41nPt8bUTg+jWyDeg7e7YN4xOM05YPSIXceACnXVtqyEw/LMClUQMtMZ+PGGpqQ=="],
+
+    "whatwg-mimetype": ["whatwg-mimetype@5.0.0", "", {}, "sha512-sXcNcHOC51uPGF0P/D4NVtrkjSU2fNsm9iog4ZvZJsL3rjoDAzXZhkm2MWt1y+PUdggKAYVoMAIYcs78wJ51Cw=="],
+
+    "whatwg-url": ["whatwg-url@16.0.1", "", { "dependencies": { "@exodus/bytes": "^1.11.0", "tr46": "^6.0.0", "webidl-conversions": "^8.0.1" } }, "sha512-1to4zXBxmXHV3IiSSEInrreIlu02vUOvrhxJJH5vcxYTBDAx51cqZiKdyTxlecdKNSjj8EcxGBxNf6Vg+945gw=="],
+
+    "which": ["which@2.0.2", "", { "dependencies": { "isexe": "^2.0.0" }, "bin": { "node-which": "./bin/node-which" } }, "sha512-BLI3Tl1TW3Pvl70l3yq3Y64i+awpwXqsGBYWkkqMtnbXgrMD+yj7rhW0kuEDxzJaYXGjEW5ogapKNMEKNMjibA=="],
+
+    "ws": ["ws@8.20.0", "", { "peerDependencies": { "bufferutil": "^4.0.1", "utf-8-validate": ">=5.0.2" }, "optionalPeers": ["bufferutil", "utf-8-validate"] }, "sha512-sAt8BhgNbzCtgGbt2OxmpuryO63ZoDk/sqaB/znQm94T4fCEsy/yV+7CdC1kJhOU9lboAEU7R3kquuycDoibVA=="],
+
+    "xml-name-validator": ["xml-name-validator@5.0.0", "", {}, "sha512-EvGK8EJ3DhaHfbRlETOWAS5pO9MZITeauHKJyb8wyajUfQUenkIg2MvLDTZ4T/TgIcm3HU0TFBgWWboAZ30UHg=="],
+
+    "xmlchars": ["xmlchars@2.2.0", "", {}, "sha512-JZnDKK8B0RCDw84FNdDAIpZK+JuJw+s7Lz8nksI7SIuU3UXJJslUthsi+uWBUYOwPFwW7W7PRLRfUKpxjtjFCw=="],
+
+    "zwitch": ["zwitch@2.0.4", "", {}, "sha512-bXE4cR/kVZhKZX/RjPEflHaKVhUVl85noU3v6b8apfQEc1x4A+zBxjZ4lN8LqGd6WZ3dl98pY4o717VFmoPp+A=="],
+
+    "@manypkg/find-root/@types/node": ["@types/node@12.20.55", "", {}, "sha512-J8xLz7q2OFulZ2cyGTLE1TbbZcjpno7FaN6zdJNrgAdrJ+DZzh/uFR6YrTb4C+nXakvud8Q4+rbhoIWlYQbUFQ=="],
+
+    "@manypkg/find-root/fs-extra": ["fs-extra@8.1.0", "", { "dependencies": { "graceful-fs": "^4.2.0", "jsonfile": "^4.0.0", "universalify": "^0.1.0" } }, "sha512-yhlQgA6mnOJUKOsRUFsgJdQCvkKhcz8tlZG5HBQfReYZy46OwLcY+Zia0mtdHsOo9y/hP+CxMN0TU9QxoOtG4g=="],
+
+    "@manypkg/get-packages/@changesets/types": ["@changesets/types@4.1.0", "", {}, "sha512-LDQvVDv5Kb50ny2s25Fhm3d9QSZimsoUGBsUioj6MC3qbMUCuC8GPIvk/M6IvXx3lYhAs0lwWUQLb+VIEUCECw=="],
+
+    "@manypkg/get-packages/fs-extra": ["fs-extra@8.1.0", "", { "dependencies": { "graceful-fs": "^4.2.0", "jsonfile": "^4.0.0", "universalify": "^0.1.0" } }, "sha512-yhlQgA6mnOJUKOsRUFsgJdQCvkKhcz8tlZG5HBQfReYZy46OwLcY+Zia0mtdHsOo9y/hP+CxMN0TU9QxoOtG4g=="],
+
+    "dom-serializer/entities": ["entities@4.5.0", "", {}, "sha512-V0hjH4dGPh9Ao5p0MoRY6BVqtwCjhz6vI5LT8AJ55H+4g9/4vbHx1I54fS0XuclLhDHArPQCiMjDxjaL8fPxhw=="],
+
+    "htmlparser2/entities": ["entities@7.0.1", "", {}, "sha512-TWrgLOFUQTH994YUyl1yT4uyavY5nNB5muff+RtWaqNVCAK408b5ZnnbNAUEWLTCpum9w6arT70i1XdQ4UeOPA=="],
+
+    "jsdom/parse5": ["parse5@8.0.1", "", { "dependencies": { "entities": "^8.0.0" } }, "sha512-z1e/HMG90obSGeidlli3hj7cbocou0/wa5HacvI3ASx34PecNjNQeaHNo5WIZpWofN9kgkqV1q5YvXe3F0FoPw=="],
+
+    "mdast-util-find-and-replace/escape-string-regexp": ["escape-string-regexp@5.0.0", "", {}, "sha512-/veY75JbMK4j1yjvuUxuVsiS/hr/4iHs9FTT6cgTexxdE0Ly/glccBAkloH/DofkjRbZU3bnoj38mOmhkZ0lHw=="],
+
+    "read-yaml-file/js-yaml": ["js-yaml@3.14.2", "", { "dependencies": { "argparse": "^1.0.7", "esprima": "^4.0.0" }, "bin": { "js-yaml": "bin/js-yaml.js" } }, "sha512-PMSmkqxr106Xa156c2M265Z+FTrPl+oxd/rgOQy2tijQeK5TxQ43psO1ZCwhVOSdnn+RzkzlRz/eY4BgJBYVpg=="],
+
+    "jsdom/parse5/entities": ["entities@8.0.0", "", {}, "sha512-zwfzJecQ/Uej6tusMqwAqU/6KL2XaB2VZ2Jg54Je6ahNBGNH6Ek6g3jjNCF0fG9EWQKGZNddNjU5F1ZQn/sBnA=="],
+
+    "read-yaml-file/js-yaml/argparse": ["argparse@1.0.10", "", { "dependencies": { "sprintf-js": "~1.0.2" } }, "sha512-o5Roy6tNG4SL/FOkCAN6RzjiakZS25RLYFrcMttJqbdd8BWrnA+fGz57iN5Pb06pvBGvl5gQ0B48dJlslXvoTg=="],
+  }
+}

packages/baoyu-fetch/package.json

@@ -0,0 +1,68 @@
+{
+  "name": "baoyu-fetch",
+  "version": "0.1.2",
+  "description": "Read URLs into high-quality Markdown or JSON with Chrome CDP and site adapters.",
+  "type": "module",
+  "bin": {
+    "baoyu-fetch": "dist/cli.js"
+  },
+  "files": [
+    "dist",
+    "README.zh-CN.md",
+    "src/adapters",
+    "src/browser",
+    "src/cli.ts",
+    "src/commands",
+    "src/extract",
+    "src/media",
+    "src/types",
+    "src/utils",
+    "README.md"
+  ],
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/JimLiu/baoyu-skills.git",
+    "directory": "packages/baoyu-fetch"
+  },
+  "bugs": {
+    "url": "https://github.com/JimLiu/baoyu-skills/issues"
+  },
+  "homepage": "https://github.com/JimLiu/baoyu-skills/tree/main/packages/baoyu-fetch#readme",
+  "publishConfig": {
+    "access": "public"
+  },
+  "scripts": {
+    "build": "rm -rf dist && bun build ./src/cli.ts --target bun --outfile ./dist/cli.js && chmod +x ./dist/cli.js",
+    "check": "tsc --noEmit",
+    "dev": "bun run ./src/cli.ts",
+    "release": "changeset publish",
+    "test": "bun test",
+    "version-packages": "changeset version",
+    "prepack": "bun run build"
+  },
+  "engines": {
+    "bun": ">=1.2.0"
+  },
+  "dependencies": {
+    "@mozilla/readability": "^0.6.0",
+    "chrome-launcher": "^1.2.1",
+    "defuddle": "^0.17.0",
+    "jsdom": "^29.0.2",
+    "remark-gfm": "^4.0.1",
+    "remark-parse": "^11.0.0",
+    "turndown": "^7.2.0",
+    "turndown-plugin-gfm": "^1.0.2",
+    "unified": "^11.0.5",
+    "ws": "^8.18.3"
+  },
+  "devDependencies": {
+    "@changesets/cli": "^2.30.0",
+    "@types/bun": "^1.2.23",
+    "@types/jsdom": "^21.1.7",
+    "@types/ws": "^8.18.1",
+    "typescript": "^5.9.2"
+  },
+  "overrides": {
+    "@xmldom/xmldom": "0.8.13"
+  }
+}

packages/baoyu-fetch/src/__tests__/adapters.test.ts

@@ -0,0 +1,25 @@
+import { describe, expect, test } from "bun:test";
+import { resolveAdapter } from "../adapters";
+
+describe("adapter registry", () => {
+  test("matches x adapter for x.com status URLs", () => {
+    const adapter = resolveAdapter({
+      url: new URL("https://x.com/openai/status/1234567890"),
+    });
+    expect(adapter.name).toBe("x");
+  });
+
+  test("matches hn adapter for item URLs", () => {
+    const adapter = resolveAdapter({
+      url: new URL("https://news.ycombinator.com/item?id=47534848"),
+    });
+    expect(adapter.name).toBe("hn");
+  });
+
+  test("falls back to generic adapter", () => {
+    const adapter = resolveAdapter({
+      url: new URL("https://example.com/post"),
+    });
+    expect(adapter.name).toBe("generic");
+  });
+});

packages/baoyu-fetch/src/__tests__/cli.test.ts

@@ -0,0 +1,69 @@
+import { describe, expect, test } from "bun:test";
+import { HELP_TEXT, parseArgs } from "../cli";
+
+describe("parseArgs", () => {
+  test("defaults to markdown output", () => {
+    const options = parseArgs(["bun", "src/cli.ts", "https://example.com"]);
+    expect(options.format).toBe("markdown");
+  });
+
+  test("parses explicit json output format", () => {
+    const options = parseArgs(["bun", "src/cli.ts", "https://example.com", "--format", "json"]);
+    expect(options.format).toBe("json");
+  });
+
+  test("maps --json to json output format", () => {
+    const options = parseArgs(["bun", "src/cli.ts", "https://example.com", "--json"]);
+    expect(options.format).toBe("json");
+  });
+
+  test("parses --wait-for interaction", () => {
+    const options = parseArgs(["bun", "src/cli.ts", "https://example.com", "--wait-for", "interaction"]);
+    expect(options.waitMode).toBe("interaction");
+  });
+
+  test("parses --wait-for force", () => {
+    const options = parseArgs(["bun", "src/cli.ts", "https://example.com", "--wait-for", "force"]);
+    expect(options.waitMode).toBe("force");
+  });
+
+  test("maps legacy wait flags to interaction mode", () => {
+    const options = parseArgs(["bun", "src/cli.ts", "https://example.com", "--wait-for-interaction"]);
+    expect(options.waitMode).toBe("interaction");
+  });
+
+  test("parses media download options", () => {
+    const options = parseArgs([
+      "bun",
+      "src/cli.ts",
+      "https://example.com",
+      "--download-media",
+      "--media-dir",
+      "./assets",
+    ]);
+
+    expect(options.downloadMedia).toBe(true);
+    expect(options.mediaDir).toBe("./assets");
+  });
+
+  test("rejects invalid wait modes", () => {
+    expect(() =>
+      parseArgs(["bun", "src/cli.ts", "https://example.com", "--wait-for", "unknown"]),
+    ).toThrow("Invalid wait mode");
+  });
+
+  test("rejects invalid output formats", () => {
+    expect(() =>
+      parseArgs(["bun", "src/cli.ts", "https://example.com", "--format", "xml"]),
+    ).toThrow("Invalid output format");
+  });
+
+  test("documents wait modes in help text", () => {
+    expect(HELP_TEXT).toContain("baoyu-fetch");
+    expect(HELP_TEXT).toContain("--format <type>");
+    expect(HELP_TEXT).toContain("--wait-for <mode>");
+    expect(HELP_TEXT).toContain("--download-media");
+    expect(HELP_TEXT).toContain("force: start visible Chrome, then auto-continue");
+    expect(HELP_TEXT).toContain("or continue immediately when you press Enter");
+  });
+});

packages/baoyu-fetch/src/__tests__/convert-output.test.ts

@@ -0,0 +1,55 @@
+import { describe, expect, test } from "bun:test";
+import { formatOutputContent } from "../commands/convert";
+
+describe("formatOutputContent", () => {
+  test("returns raw markdown for markdown output", () => {
+    expect(
+      formatOutputContent("markdown", {
+        adapter: "generic",
+        status: "ok",
+        media: [],
+        downloads: null,
+        document: {
+          url: "https://example.com",
+          content: [],
+        },
+        markdown: "# Example",
+      }),
+    ).toBe("# Example");
+  });
+
+  test("returns structured json for json output", () => {
+    const parsed = JSON.parse(
+      formatOutputContent("json", {
+        adapter: "generic",
+        status: "ok",
+        media: [],
+        downloads: null,
+        document: {
+          url: "https://example.com",
+          content: [],
+        },
+        markdown: "# Example",
+      }),
+    );
+
+    expect(parsed.status).toBe("ok");
+    expect(parsed.markdown).toBe("# Example");
+    expect(parsed.document.url).toBe("https://example.com");
+  });
+
+  test("rejects markdown output for interaction-required payloads", () => {
+    expect(() =>
+      formatOutputContent("markdown", {
+        adapter: "x",
+        status: "needs_interaction",
+        interaction: {
+          type: "wait_for_interaction",
+          kind: "login",
+          provider: "x",
+          prompt: "Login required",
+        },
+      }),
+    ).toThrow("Markdown output is only available");
+  });
+});

packages/baoyu-fetch/src/__tests__/hn-adapter.test.ts

@@ -0,0 +1,167 @@
+import { describe, expect, test } from "bun:test";
+import { renderMarkdown } from "../extract/markdown-renderer";
+import {
+  buildHnDocument,
+  buildHnThreadMarkdown,
+  extractHnThreadFromHtml,
+  parseHnItemId,
+  type HnCommentNode,
+  type HnItem,
+} from "../adapters/hn";
+
+describe("hn adapter helpers", () => {
+  test("parses item id from hn item url", () => {
+    expect(parseHnItemId(new URL("https://news.ycombinator.com/item?id=47534848"))).toBe(47534848);
+    expect(parseHnItemId(new URL("https://news.ycombinator.com/newest"))).toBeNull();
+  });
+
+  test("renders threaded comments with author, time, and nested indentation", () => {
+    const story: HnItem = {
+      id: 47534848,
+      type: "story",
+      by: "mmcclure",
+      time: 1774554485,
+      title: "Example & Title",
+      url: "https://example.com/post",
+      score: 257,
+      descendants: 2,
+    };
+
+    const comments: HnCommentNode[] = [
+      {
+        item: {
+          id: 47535377,
+          type: "comment",
+          by: "jackfruitpeel",
+          time: 1774557334,
+          text: "Root comment<p>With two paragraphs.",
+        },
+        children: [
+          {
+            item: {
+              id: 47535469,
+              type: "comment",
+              by: "__MatrixMan__",
+              time: 1774557848,
+              text: "Nested reply with a <a href=\"item?id=1\">relative link</a>.",
+            },
+            children: [],
+          },
+        ],
+      },
+    ];
+
+    const body = buildHnThreadMarkdown(story, comments, "https://news.ycombinator.com/item?id=47534848");
+    expect(body).toContain("Source: [https://example.com/post](https://example.com/post)");
+    expect(body).toContain("Submitted by mmcclure at 2026-03-26 19:48:05 UTC");
+    expect(body).toContain("- jackfruitpeel · [2026-03-26 20:35:34 UTC](https://news.ycombinator.com/item?id=47534848#47535377)");
+    expect(body).toContain("    Root comment");
+    expect(body).toContain("    With two paragraphs.");
+    expect(body).toContain("    - __MatrixMan__ · [2026-03-26 20:44:08 UTC](https://news.ycombinator.com/item?id=47534848#47535469)");
+    expect(body).toContain("        Nested reply with a [relative link](https://news.ycombinator.com/item?id=1).");
+  });
+
+  test("extracts story metadata and nested comments from hn html", () => {
+    const parsed = extractHnThreadFromHtml(
+      `
+      <html>
+        <body>
+          <table class="fatitem">
+            <tr class="athing submission" id="47534848">
+              <td class="title">
+                <span class="titleline">
+                  <a href="https://example.com/post">Example story</a>
+                </span>
+              </td>
+            </tr>
+            <tr>
+              <td class="subtext">
+                <span class="subline">
+                  <span class="score">257 points</span>
+                  by <a href="user?id=mmcclure" class="hnuser">mmcclure</a>
+                  <span class="age" title="2026-03-26T19:48:05 1774554485">
+                    <a href="item?id=47534848">1 hour ago</a>
+                  </span>
+                  <a href="item?id=47534848">152 comments</a>
+                </span>
+              </td>
+            </tr>
+            <tr>
+              <td><div class="toptext">Story <p>body</p></div></td>
+            </tr>
+          </table>
+          <table class="comment-tree">
+            <tr class="athing comtr" id="47535377">
+              <td class="ind" indent="0"></td>
+              <td class="default">
+                <span class="comhead">
+                  <a href="user?id=jackfruitpeel" class="hnuser">jackfruitpeel</a>
+                  <span class="age" title="2026-03-26T20:35:34 1774557334">
+                    <a href="item?id=47535377">36 minutes ago</a>
+                  </span>
+                </span>
+                <div class="comment"><div class="commtext c00">Root</div></div>
+              </td>
+            </tr>
+            <tr class="athing comtr" id="47535469">
+              <td class="ind" indent="1"></td>
+              <td class="default">
+                <span class="comhead">
+                  <a href="user?id=willio58" class="hnuser">willio58</a>
+                  <span class="age" title="2026-03-26T20:44:08 1774557848">
+                    <a href="item?id=47535469">27 minutes ago</a>
+                  </span>
+                </span>
+                <div class="comment"><div class="commtext c00">Child</div></div>
+              </td>
+            </tr>
+          </table>
+        </body>
+      </html>
+      `,
+      "https://news.ycombinator.com/item?id=47534848",
+    );
+
+    expect(parsed).not.toBeNull();
+    expect(parsed?.story.title).toBe("Example story");
+    expect(parsed?.story.url).toBe("https://example.com/post");
+    expect(parsed?.story.by).toBe("mmcclure");
+    expect(parsed?.story.time).toBe(1774554485);
+    expect(parsed?.story.score).toBe(257);
+    expect(parsed?.story.descendants).toBe(152);
+    expect(parsed?.story.text).toContain("Story");
+    expect(parsed?.comments).toHaveLength(1);
+    expect(parsed?.comments[0]?.item.by).toBe("jackfruitpeel");
+    expect(parsed?.comments[0]?.children).toHaveLength(1);
+    expect(parsed?.comments[0]?.children[0]?.item.by).toBe("willio58");
+  });
+
+  test("builds hn document with metadata and markdown body", () => {
+    const document = buildHnDocument(
+      {
+        id: 123,
+        type: "story",
+        by: "pg",
+        time: 1175714200,
+        title: "Ask HN: Example",
+        text: "What are you working on?",
+        score: 111,
+        descendants: 0,
+      },
+      [],
+      "https://news.ycombinator.com/item?id=123",
+    );
+
+    const markdown = renderMarkdown(document);
+    expect(document.adapter).toBe("hn");
+    expect(document.siteName).toBe("Hacker News");
+    expect(document.publishedAt).toBe("2007-04-04T19:16:40.000Z");
+    expect(markdown).toContain('adapter: "hn"');
+    expect(markdown).toContain('siteName: "Hacker News"');
+    expect(markdown).toContain("# Ask HN: Example");
+    expect(markdown).toContain("## Post");
+    expect(markdown).toContain("What are you working on?");
+    expect(markdown).toContain("## Comments");
+    expect(markdown).toContain("No comments.");
+  });
+});

packages/baoyu-fetch/src/__tests__/html-to-markdown.test.ts

@@ -0,0 +1,105 @@
+import { afterEach, describe, expect, test } from "bun:test";
+import {
+  convertHtmlToMarkdown,
+  extractTitleFromMarkdownDocument,
+} from "../extract/html-to-markdown";
+
+const originalFetch = globalThis.fetch;
+
+afterEach(() => {
+  globalThis.fetch = originalFetch;
+});
+
+describe("extractTitleFromMarkdownDocument", () => {
+  test("prefers frontmatter title when present", () => {
+    const title = extractTitleFromMarkdownDocument(`---
+title: "Frontmatter Title"
+---
+
+# Heading Title
+`);
+
+    expect(title).toBe("Frontmatter Title");
+  });
+
+  test("falls back to the first markdown heading", () => {
+    const title = extractTitleFromMarkdownDocument(`
+Intro text
+
+# Heading Title
+
+Body text.
+`);
+
+    expect(title).toBe("Heading Title");
+  });
+});
+
+describe("convertHtmlToMarkdown remote fallback", () => {
+  test("does not call defuddle.md when the remote fallback option is disabled", async () => {
+    let fetchCalls = 0;
+    globalThis.fetch = Object.assign(
+      async () => {
+        fetchCalls += 1;
+        return new Response("# Remote Title\n\nRemote body.", {
+          headers: {
+            "content-type": "text/markdown",
+          },
+        });
+      },
+      {
+        preconnect: originalFetch.preconnect,
+      },
+    ) as typeof fetch;
+
+    const result = await convertHtmlToMarkdown(
+      "<!doctype html><html><head><title>Local Title</title></head><body></body></html>",
+      "https://example.com/post",
+    );
+
+    expect(fetchCalls).toBe(0);
+    expect(result.conversionMethod).not.toBe("defuddle-api");
+  });
+
+  test("uses defuddle.md markdown when local extraction is empty", async () => {
+    const fetchCalls: Array<{ input: RequestInfo | URL; init?: RequestInit }> = [];
+    globalThis.fetch = Object.assign(
+      async (input: RequestInfo | URL, init?: RequestInit) => {
+        fetchCalls.push({ input, init });
+        return new Response(`---
+title: "Remote Title"
+---
+
+# Remote Title
+
+Remote body.
+`, {
+          headers: {
+            "content-type": "text/markdown",
+          },
+        });
+      },
+      {
+        preconnect: originalFetch.preconnect,
+      },
+    ) as typeof fetch;
+
+    const result = await convertHtmlToMarkdown(
+      "<!doctype html><html><head><title>Local Title</title></head><body></body></html>",
+      "https://example.com/post",
+      { enableRemoteMarkdownFallback: true },
+    );
+
+    expect(fetchCalls).toHaveLength(1);
+    expect(String(fetchCalls[0]?.input)).toBe(
+      "https://defuddle.md/https%3A%2F%2Fexample.com%2Fpost",
+    );
+    expect(fetchCalls[0]?.init?.headers).toEqual({
+      accept: "text/markdown,text/plain;q=0.9,*/*;q=0.1",
+    });
+    expect(result.conversionMethod).toBe("defuddle-api");
+    expect(result.metadata.title).toBe("Remote Title");
+    expect(result.markdown).toBe("# Remote Title\n\nRemote body.");
+    expect(result.fallbackReason).toContain("defuddle.md");
+  });
+});

packages/baoyu-fetch/src/__tests__/interaction-gates.test.ts

@@ -0,0 +1,54 @@
+import { describe, expect, test } from "bun:test";
+import { detectInteractionGateFromSnapshot } from "../browser/interaction-gates";
+
+describe("detectInteractionGateFromSnapshot", () => {
+  test("detects cloudflare challenge", () => {
+    const gate = detectInteractionGateFromSnapshot({
+      title: "Just a moment...",
+      currentUrl: "https://example.com/cdn-cgi/challenge-platform/h/b",
+      bodyText: "Checking your browser before accessing example.com",
+      hasCloudflareTurnstile: true,
+      hasCloudflareChallenge: true,
+      hasRecaptcha: false,
+      hasRecaptchaIframe: false,
+      hasHcaptcha: false,
+      hasHcaptchaIframe: false,
+    });
+
+    expect(gate?.kind).toBe("cloudflare");
+    expect(gate?.provider).toBe("cloudflare");
+  });
+
+  test("detects google recaptcha", () => {
+    const gate = detectInteractionGateFromSnapshot({
+      title: "Protected page",
+      currentUrl: "https://example.com/form",
+      bodyText: "Please verify that you're not a robot via reCAPTCHA",
+      hasCloudflareTurnstile: false,
+      hasCloudflareChallenge: false,
+      hasRecaptcha: true,
+      hasRecaptchaIframe: true,
+      hasHcaptcha: false,
+      hasHcaptchaIframe: false,
+    });
+
+    expect(gate?.kind).toBe("recaptcha");
+    expect(gate?.provider).toBe("google_recaptcha");
+  });
+
+  test("returns null when no challenge is present", () => {
+    const gate = detectInteractionGateFromSnapshot({
+      title: "Example",
+      currentUrl: "https://example.com/article",
+      bodyText: "Normal article body",
+      hasCloudflareTurnstile: false,
+      hasCloudflareChallenge: false,
+      hasRecaptcha: false,
+      hasRecaptchaIframe: false,
+      hasHcaptcha: false,
+      hasHcaptchaIframe: false,
+    });
+
+    expect(gate).toBeNull();
+  });
+});

packages/baoyu-fetch/src/__tests__/markdown-media.test.ts

@@ -0,0 +1,138 @@
+import { describe, expect, test } from "bun:test";
+import {
+  collectMediaFromDocument,
+  collectMediaFromMarkdown,
+  normalizeMarkdownMediaLinks,
+  rewriteMarkdownMediaLinks,
+} from "../media/markdown-media";
+
+describe("markdown media helpers", () => {
+  test("collects cover, image markdown, and plain media urls from a document", () => {
+    const media = collectMediaFromDocument({
+      url: "https://example.com/post",
+      metadata: {
+        coverImage: "https://cdn.example.com/cover.jpg",
+      },
+      content: [
+        { type: "paragraph", text: "Poster: https://cdn.example.com/poster.png" },
+        { type: "markdown", markdown: "![inline](https://cdn.example.com/body.webp)\n\n[video](https://cdn.example.com/clip.mp4)" },
+      ],
+    });
+
+    expect(media).toEqual([
+      { url: "https://cdn.example.com/cover.jpg", kind: "image", role: "cover" },
+      { url: "https://cdn.example.com/poster.png", kind: "image", role: "inline" },
+      { url: "https://cdn.example.com/body.webp", kind: "image", role: "inline" },
+      { url: "https://cdn.example.com/clip.mp4", kind: "video", role: "inline" },
+    ]);
+  });
+
+  test("rewrites markdown links, frontmatter cover images, and plain url mentions", () => {
+    const markdown = `---
+coverImage: "https://cdn.example.com/cover.jpg"
+---
+
+![inline](https://cdn.example.com/body.webp)
+
+Poster: https://cdn.example.com/poster.png
+`;
+
+    const rewritten = rewriteMarkdownMediaLinks(markdown, [
+      {
+        url: "https://cdn.example.com/cover.jpg",
+        localPath: "imgs/img-001-cover.jpg",
+        absolutePath: "/tmp/imgs/img-001-cover.jpg",
+        kind: "image",
+      },
+      {
+        url: "https://cdn.example.com/body.webp",
+        localPath: "imgs/img-002-body.webp",
+        absolutePath: "/tmp/imgs/img-002-body.webp",
+        kind: "image",
+      },
+      {
+        url: "https://cdn.example.com/poster.png",
+        localPath: "imgs/img-003-poster.png",
+        absolutePath: "/tmp/imgs/img-003-poster.png",
+        kind: "image",
+      },
+    ]);
+
+    expect(rewritten).toContain('coverImage: "imgs/img-001-cover.jpg"');
+    expect(rewritten).toContain("![inline](imgs/img-002-body.webp)");
+    expect(rewritten).toContain("Poster: imgs/img-003-poster.png");
+  });
+
+  test("normalizes and dedupes linked Substack CDN image variants", () => {
+    const resizedUrl =
+      "https://substackcdn.com/image/fetch/$s_!wORh!,w_1456,c_limit,f_auto,q_auto:good,fl_progressive:steep/https%3A%2F%2Fsubstack-post-media.s3.amazonaws.com%2Fpublic%2Fimages%2Fb83f9d2f-711f-4edd-bc8a-303b8de422e5_1600x1300.png";
+    const linkedUrl =
+      "https://substackcdn.com/image/fetch/$s_!wORh!,f_auto,q_auto:good,fl_progressive:steep/https%3A%2F%2Fsubstack-post-media.s3.amazonaws.com%2Fpublic%2Fimages%2Fb83f9d2f-711f-4edd-bc8a-303b8de422e5_1600x1300.png";
+    const canonicalUrl =
+      "https://substack-post-media.s3.amazonaws.com/public/images/b83f9d2f-711f-4edd-bc8a-303b8de422e5_1600x1300.png";
+    const markdown = `[![](${resizedUrl})](${linkedUrl})`;
+
+    expect(normalizeMarkdownMediaLinks(markdown)).toBe(`![](${canonicalUrl})`);
+    expect(collectMediaFromMarkdown(markdown)).toEqual([
+      {
+        url: canonicalUrl,
+        kind: "image",
+        role: "inline",
+      },
+    ]);
+  });
+
+  test("collapses linked images when href equals image url after normalization", () => {
+    const resizedUrl =
+      "https://substackcdn.com/image/fetch/$s_!wORh!,w_1456,c_limit,f_auto,q_auto:good,fl_progressive:steep/https%3A%2F%2Fsubstack-post-media.s3.amazonaws.com%2Fpublic%2Fimages%2Fb83f9d2f-711f-4edd-bc8a-303b8de422e5_1600x1300.png";
+    const linkedUrl =
+      "https://substackcdn.com/image/fetch/$s_!wORh!,f_auto,q_auto:good,fl_progressive:steep/https%3A%2F%2Fsubstack-post-media.s3.amazonaws.com%2Fpublic%2Fimages%2Fb83f9d2f-711f-4edd-bc8a-303b8de422e5_1600x1300.png";
+    const canonicalUrl =
+      "https://substack-post-media.s3.amazonaws.com/public/images/b83f9d2f-711f-4edd-bc8a-303b8de422e5_1600x1300.png";
+    const markdown = `[
+
+![](${resizedUrl})
+
+](${linkedUrl})`;
+
+    expect(normalizeMarkdownMediaLinks(markdown)).toBe(`![](${canonicalUrl})`);
+  });
+
+  test("compacts linked images when href differs from the image url", () => {
+    const markdown = `[
+
+![diagram](https://cdn.example.com/body.webp)
+
+](https://example.com/source)`;
+
+    expect(normalizeMarkdownMediaLinks(markdown)).toBe(
+      "[![diagram](https://cdn.example.com/body.webp)](https://example.com/source)",
+    );
+  });
+
+  test("keeps single-line linked images on one line after parser-based normalization", () => {
+    const markdown = `[![diagram](https://cdn.example.com/body.webp)](https://example.com/source)`;
+
+    expect(normalizeMarkdownMediaLinks(markdown)).toBe(
+      "[![diagram](https://cdn.example.com/body.webp)](https://example.com/source)",
+    );
+  });
+
+  test("repairs broken linked image blocks without disturbing surrounding paragraphs", () => {
+    const markdown = `Before
+
+[
+
+![diagram](https://cdn.example.com/body.webp)
+
+](https://example.com/source)
+
+After`;
+
+    expect(normalizeMarkdownMediaLinks(markdown)).toBe(`Before
+
+[![diagram](https://cdn.example.com/body.webp)](https://example.com/source)
+
+After`);
+  });
+});

packages/baoyu-fetch/src/__tests__/markdown-renderer.test.ts

@@ -0,0 +1,99 @@
+import { describe, expect, test } from "bun:test";
+import { renderMarkdown } from "../extract/markdown-renderer";
+
+describe("renderMarkdown", () => {
+  test("renders frontmatter and content blocks", () => {
+    const markdown = renderMarkdown({
+      url: "https://example.com/post",
+      requestedUrl: "https://example.com/post?ref=test",
+      title: "Example Title",
+      author: "Alice",
+      siteName: "Example",
+      publishedAt: "2026-03-25",
+      adapter: "generic",
+      metadata: {
+        authorName: "Alice Example",
+        authorUsername: "alice",
+        authorUrl: "https://example.com/@alice",
+        kind: "generic/article",
+      },
+      content: [
+        { type: "paragraph", text: "First paragraph." },
+        { type: "list", ordered: false, items: ["One", "Two"] },
+      ],
+    });
+
+    expect(markdown).toContain("---");
+    expect(markdown).toContain('title: "Example Title"');
+    expect(markdown).toContain('url: "https://example.com/post"');
+    expect(markdown).toContain('requestedUrl: "https://example.com/post?ref=test"');
+    expect(markdown).toContain('author: "Alice"');
+    expect(markdown).toContain('authorName: "Alice Example"');
+    expect(markdown).toContain('authorUsername: "alice"');
+    expect(markdown).toContain('authorUrl: "https://example.com/@alice"');
+    expect(markdown).toContain("# Example Title");
+    expect(markdown).toContain("First paragraph.");
+    expect(markdown).toContain("- One");
+  });
+
+  test("avoids duplicating the title when body already starts with it", () => {
+    const markdown = renderMarkdown({
+      url: "https://example.com/post",
+      title: "Example Title",
+      content: [{ type: "markdown", markdown: "# Example Title\n\nBody text." }],
+    });
+
+    expect(markdown.match(/# Example Title/g)?.length).toBe(1);
+    expect(markdown).toContain("Body text.");
+  });
+
+  test("normalizes Substack CDN image links in rendered markdown", () => {
+    const resizedUrl =
+      "https://substackcdn.com/image/fetch/$s_!wORh!,w_1456,c_limit,f_auto,q_auto:good,fl_progressive:steep/https%3A%2F%2Fsubstack-post-media.s3.amazonaws.com%2Fpublic%2Fimages%2Fb83f9d2f-711f-4edd-bc8a-303b8de422e5_1600x1300.png";
+    const linkedUrl =
+      "https://substackcdn.com/image/fetch/$s_!wORh!,f_auto,q_auto:good,fl_progressive:steep/https%3A%2F%2Fsubstack-post-media.s3.amazonaws.com%2Fpublic%2Fimages%2Fb83f9d2f-711f-4edd-bc8a-303b8de422e5_1600x1300.png";
+    const canonicalUrl =
+      "https://substack-post-media.s3.amazonaws.com/public/images/b83f9d2f-711f-4edd-bc8a-303b8de422e5_1600x1300.png";
+
+    const markdown = renderMarkdown({
+      url: "https://example.com/post",
+      metadata: {
+        coverImage: resizedUrl,
+      },
+      content: [
+        {
+          type: "markdown",
+          markdown: `[
+
+![](${resizedUrl})
+
+](${linkedUrl})`,
+        },
+      ],
+    });
+
+    expect(markdown).toContain(`coverImage: "${canonicalUrl}"`);
+    expect(markdown).toContain(`![](${canonicalUrl})`);
+    expect(markdown).not.toContain(`[![](${canonicalUrl})](${canonicalUrl})`);
+    expect(markdown).not.toContain("substackcdn.com/image/fetch");
+  });
+
+  test("renders linked images on a single line when href differs from the image url", () => {
+    const markdown = renderMarkdown({
+      url: "https://example.com/post",
+      content: [
+        {
+          type: "markdown",
+          markdown: `[
+
+![diagram](https://cdn.example.com/body.webp)
+
+](https://example.com/source)`,
+        },
+      ],
+    });
+
+    expect(markdown).toContain("[![diagram](https://cdn.example.com/body.webp)](https://example.com/source)");
+    expect(markdown).not.toContain("](https://example.com/source)\n");
+  });
+});

packages/baoyu-fetch/src/__tests__/profile.test.ts

@@ -0,0 +1,68 @@
+import { afterEach, describe, expect, test } from "bun:test";
+import fs from "node:fs";
+import path from "node:path";
+import os from "node:os";
+import {
+  ensureChromeProfileDir,
+  hasChromeLockArtifacts,
+  resolveChromeProfileDir,
+  shouldRetryChromeLaunchRecovery,
+} from "../browser/profile";
+
+const originalProfile = process.env.BAOYU_CHROME_PROFILE_DIR;
+
+afterEach(() => {
+  if (originalProfile === undefined) {
+    delete process.env.BAOYU_CHROME_PROFILE_DIR;
+  } else {
+    process.env.BAOYU_CHROME_PROFILE_DIR = originalProfile;
+  }
+});
+
+describe("resolveChromeProfileDir", () => {
+  test("uses BAOYU_CHROME_PROFILE_DIR when set", () => {
+    process.env.BAOYU_CHROME_PROFILE_DIR = "/tmp/baoyu-profile";
+    expect(resolveChromeProfileDir()).toBe("/tmp/baoyu-profile");
+  });
+
+  test("falls back to shared baoyu-skills profile path", () => {
+    delete process.env.BAOYU_CHROME_PROFILE_DIR;
+    const resolved = resolveChromeProfileDir();
+    if (process.platform === "darwin") {
+      expect(resolved).toBe(path.join(os.homedir(), "Library", "Application Support", "baoyu-skills", "chrome-profile"));
+    } else if (process.platform === "win32") {
+      expect(resolved.endsWith(path.join("baoyu-skills", "chrome-profile"))).toBe(true);
+    } else {
+      expect(resolved.endsWith(path.join("baoyu-skills", "chrome-profile"))).toBe(true);
+    }
+  });
+});
+
+describe("ensureChromeProfileDir", () => {
+  test("creates the profile directory when missing", () => {
+    const tempRoot = fs.mkdtempSync(path.join(os.tmpdir(), "baoyu-fetch-profile-"));
+    const profileDir = path.join(tempRoot, "nested", "chrome-profile");
+
+    try {
+      expect(fs.existsSync(profileDir)).toBe(false);
+      expect(ensureChromeProfileDir(profileDir)).toBe(profileDir);
+      expect(fs.statSync(profileDir).isDirectory()).toBe(true);
+    } finally {
+      fs.rmSync(tempRoot, { force: true, recursive: true });
+    }
+  });
+});
+
+describe("stale lock recovery helpers", () => {
+  test("detects Chrome singleton lock artifacts", () => {
+    expect(hasChromeLockArtifacts(["Cookies", "SingletonLock"])).toBe(true);
+    expect(hasChromeLockArtifacts(["chrome.pid"])).toBe(true);
+    expect(hasChromeLockArtifacts(["Preferences", "Cookies"])).toBe(false);
+  });
+
+  test("only retries stale-lock recovery when no live owner exists", () => {
+    expect(shouldRetryChromeLaunchRecovery({ hasLockArtifacts: true, hasLiveOwner: false })).toBe(true);
+    expect(shouldRetryChromeLaunchRecovery({ hasLockArtifacts: true, hasLiveOwner: true })).toBe(false);
+    expect(shouldRetryChromeLaunchRecovery({ hasLockArtifacts: false, hasLiveOwner: false })).toBe(false);
+  });
+});

packages/baoyu-fetch/src/__tests__/wait-mode.test.ts

@@ -0,0 +1,105 @@
+import { describe, expect, test } from "bun:test";
+import { shouldAutoContinueForceWait, shouldKeepBrowserOpenAfterInteraction } from "../commands/convert";
+
+describe("shouldAutoContinueForceWait", () => {
+  test("continues when a challenge disappears", () => {
+    expect(
+      shouldAutoContinueForceWait(
+        {
+          url: "https://example.com/challenge",
+          hasGate: true,
+          loginState: "unknown",
+          sessionReady: true,
+        },
+        {
+          url: "https://example.com/article",
+          hasGate: false,
+          loginState: "unknown",
+          sessionReady: true,
+        },
+      ),
+    ).toBe(true);
+  });
+
+  test("waits for X session cookies before continuing after login", () => {
+    expect(
+      shouldAutoContinueForceWait(
+        {
+          url: "https://x.com/i/flow/login",
+          hasGate: false,
+          loginState: "logged_out",
+          sessionReady: false,
+        },
+        {
+          url: "https://x.com/home",
+          hasGate: false,
+          loginState: "logged_in",
+          sessionReady: false,
+        },
+      ),
+    ).toBe(false);
+
+    expect(
+      shouldAutoContinueForceWait(
+        {
+          url: "https://x.com/i/flow/login",
+          hasGate: false,
+          loginState: "logged_out",
+          sessionReady: false,
+        },
+        {
+          url: "https://x.com/home",
+          hasGate: false,
+          loginState: "logged_in",
+          sessionReady: true,
+        },
+      ),
+    ).toBe(true);
+  });
+
+  test("does not continue when nothing changed yet", () => {
+    expect(
+      shouldAutoContinueForceWait(
+        {
+          url: "https://x.com/lennysan/status/2036483059407810640",
+          hasGate: false,
+          loginState: "unknown",
+          sessionReady: false,
+        },
+        {
+          url: "https://x.com/lennysan/status/2036483059407810640",
+          hasGate: false,
+          loginState: "unknown",
+          sessionReady: false,
+        },
+      ),
+    ).toBe(false);
+  });
+});
+
+describe("shouldKeepBrowserOpenAfterInteraction", () => {
+  test("keeps launched X login browsers open", () => {
+    expect(
+      shouldKeepBrowserOpenAfterInteraction({
+        launched: true,
+        interaction: { kind: "login", provider: "x" },
+      }),
+    ).toBe(true);
+  });
+
+  test("does not keep reused or non-login browsers open", () => {
+    expect(
+      shouldKeepBrowserOpenAfterInteraction({
+        launched: false,
+        interaction: { kind: "login", provider: "x" },
+      }),
+    ).toBe(false);
+
+    expect(
+      shouldKeepBrowserOpenAfterInteraction({
+        launched: true,
+        interaction: { kind: "cloudflare", provider: "cloudflare" },
+      }),
+    ).toBe(false);
+  });
+});

packages/baoyu-fetch/src/__tests__/x-article.test.ts

@@ -0,0 +1,443 @@
+import { describe, expect, test } from "bun:test";
+import { extractArticleDocumentFromPayload } from "../adapters/x/article";
+
+describe("x article extraction", () => {
+  test("renders markdown entities referenced by atomic blocks", () => {
+    const payload = {
+      data: {
+        tweetResult: {
+          result: {
+            rest_id: "2036762680401223946",
+            legacy: {
+              full_text: "Fallback text",
+              favorite_count: 12,
+              retweet_count: 3,
+              reply_count: 1,
+              created_at: "Wed Mar 25 11:10:38 +0000 2026",
+            },
+            core: {
+              user_results: {
+                result: {
+                  legacy: {
+                    name: "Eric Zakariasson",
+                    screen_name: "ericzakariasson",
+                  },
+                },
+              },
+            },
+            article: {
+              article_results: {
+                result: {
+                  title: "Building CLIs for agents",
+                  content_state: {
+                    blocks: [
+                      {
+                        type: "unstyled",
+                        text: "Make it non-interactive.",
+                        data: {},
+                        entityRanges: [],
+                        inlineStyleRanges: [],
+                      },
+                      {
+                        type: "atomic",
+                        text: " ",
+                        data: {},
+                        entityRanges: [{ key: 0, length: 1, offset: 0 }],
+                        inlineStyleRanges: [],
+                      },
+                      {
+                        type: "unstyled",
+                        text: "Return data on success.",
+                        data: {},
+                        entityRanges: [],
+                        inlineStyleRanges: [],
+                      },
+                    ],
+                    entityMap: [
+                      {
+                        key: "0",
+                        value: {
+                          type: "MARKDOWN",
+                          mutability: "Mutable",
+                          data: {
+                            markdown: "```bash\n$ mycli deploy --env production --dry-run\n```",
+                          },
+                        },
+                      },
+                    ],
+                  },
+                },
+              },
+            },
+          },
+        },
+      },
+    };
+
+    const document = extractArticleDocumentFromPayload(
+      payload,
+      "2036762680401223946",
+      "https://x.com/ericzakariasson/status/2036762680401223946",
+    );
+
+    expect(document).not.toBeNull();
+    expect(document?.metadata?.kind).toBe("x/article");
+
+    const content = document?.content[0];
+    expect(content?.type).toBe("markdown");
+    if (!content || content.type !== "markdown") {
+      throw new Error("Expected markdown content");
+    }
+
+    expect(content.markdown).toContain("```bash");
+    expect(content.markdown).toContain("$ mycli deploy --env production --dry-run");
+    expect(content.markdown).toContain("Make it non-interactive.");
+    expect(content.markdown).toContain("Return data on success.");
+  });
+
+  test("renders media, embedded tweets, and cover image from article entities", () => {
+    const embeddedTweetPayload = {
+      data: {
+        tweetResult: {
+          result: {
+            rest_id: "999",
+            legacy: {
+              full_text: "Embedded tweet text",
+              favorite_count: 4,
+              retweet_count: 2,
+              reply_count: 1,
+              created_at: "Wed Mar 25 11:10:38 +0000 2026",
+              extended_entities: {
+                media: [
+                  {
+                    type: "photo",
+                    media_url_https: "https://pbs.twimg.com/media/embedded.jpg",
+                  },
+                ],
+              },
+            },
+            core: {
+              user_results: {
+                result: {
+                  core: {
+                    name: "Embedded Author",
+                    screen_name: "embedded_author",
+                  },
+                  legacy: {},
+                },
+              },
+            },
+          },
+        },
+      },
+    };
+
+    const articlePayload = {
+      data: {
+        tweetResult: {
+          result: {
+            rest_id: "2036670816344064290",
+            legacy: {
+              full_text: "Fallback text",
+              favorite_count: 12,
+              retweet_count: 3,
+              reply_count: 1,
+              created_at: "Wed Mar 25 11:10:38 +0000 2026",
+            },
+            core: {
+              user_results: {
+                result: {
+                  legacy: {
+                    name: "Eric Zakariasson",
+                    screen_name: "ericzakariasson",
+                  },
+                },
+              },
+            },
+            article: {
+              article_results: {
+                result: {
+                  title: "Article with media",
+                  cover_media: {
+                    media_info: {
+                      original_img_url: "https://pbs.twimg.com/media/cover?format=jpeg&name=small",
+                    },
+                  },
+                  media_entities: [
+                    {
+                      media_id: "42",
+                      media_info: {
+                        original_img_url: "https://pbs.twimg.com/media/body.jpg",
+                      },
+                    },
+                  ],
+                  content_state: {
+                    blocks: [
+                      {
+                        type: "unstyled",
+                        text: "Read more: https://t.co/example",
+                        data: {},
+                        entityRanges: [{ key: 2, length: 20, offset: 11 }],
+                        inlineStyleRanges: [],
+                      },
+                      {
+                        type: "atomic",
+                        text: " ",
+                        data: {},
+                        entityRanges: [{ key: 0, length: 1, offset: 0 }],
+                        inlineStyleRanges: [],
+                      },
+                      {
+                        type: "atomic",
+                        text: " ",
+                        data: {},
+                        entityRanges: [{ key: 1, length: 1, offset: 0 }],
+                        inlineStyleRanges: [],
+                      },
+                    ],
+                    entityMap: [
+                      {
+                        key: "0",
+                        value: {
+                          type: "MEDIA",
+                          mutability: "Immutable",
+                          data: {
+                            mediaItems: [{ mediaId: "42" }],
+                          },
+                        },
+                      },
+                      {
+                        key: "1",
+                        value: {
+                          type: "TWEET",
+                          mutability: "Immutable",
+                          data: {
+                            tweetId: "999",
+                          },
+                        },
+                      },
+                      {
+                        key: "2",
+                        value: {
+                          type: "LINK",
+                          mutability: "Mutable",
+                          data: {
+                            url: "https://example.com/report",
+                          },
+                        },
+                      },
+                    ],
+                  },
+                },
+              },
+            },
+          },
+        },
+      },
+    };
+
+    const document = extractArticleDocumentFromPayload(
+      articlePayload,
+      "2036670816344064290",
+      "https://x.com/ericzakariasson/status/2036670816344064290",
+      [articlePayload, embeddedTweetPayload],
+    );
+
+    expect(document).not.toBeNull();
+    expect(document?.metadata?.coverImage).toBe(
+      "https://pbs.twimg.com/media/cover?format=jpg&name=4096x4096",
+    );
+
+    const content = document?.content[0];
+    expect(content?.type).toBe("markdown");
+    if (!content || content.type !== "markdown") {
+      throw new Error("Expected markdown content");
+    }
+
+    expect(content.markdown).toContain("https://example.com/report");
+    expect(content.markdown).toContain("![](https://pbs.twimg.com/media/body?format=jpg&name=4096x4096)");
+    expect(content.markdown).toContain("> Embedded Author (@embedded_author)");
+    expect(content.markdown).toContain("> Embedded tweet text");
+    expect(content.markdown).toContain(
+      "> ![](https://pbs.twimg.com/media/embedded?format=jpg&name=4096x4096)",
+    );
+  });
+
+  test("prefers expanded link entity urls in article blocks", () => {
+    const payload = {
+      data: {
+        tweetResult: {
+          result: {
+            rest_id: "2036670816344064290",
+            legacy: {
+              full_text: "Fallback text",
+              favorite_count: 12,
+              retweet_count: 3,
+              reply_count: 1,
+              created_at: "Wed Mar 25 11:10:38 +0000 2026",
+            },
+            core: {
+              user_results: {
+                result: {
+                  legacy: {
+                    name: "Eric Zakariasson",
+                    screen_name: "ericzakariasson",
+                  },
+                },
+              },
+            },
+            article: {
+              article_results: {
+                result: {
+                  title: "Article with expanded links",
+                  content_state: {
+                    blocks: [
+                      {
+                        type: "unstyled",
+                        text: "Read more: https://t.co/example",
+                        data: {},
+                        entityRanges: [{ key: 0, length: 20, offset: 11 }],
+                        inlineStyleRanges: [],
+                      },
+                    ],
+                    entityMap: [
+                      {
+                        key: "0",
+                        value: {
+                          type: "LINK",
+                          mutability: "Mutable",
+                          data: {
+                            expanded_url: "https://example.com/report",
+                            url: "https://t.co/example",
+                          },
+                        },
+                      },
+                    ],
+                  },
+                },
+              },
+            },
+          },
+        },
+      },
+    };
+
+    const document = extractArticleDocumentFromPayload(
+      payload,
+      "2036670816344064290",
+      "https://x.com/ericzakariasson/status/2036670816344064290",
+    );
+
+    expect(document).not.toBeNull();
+
+    const content = document?.content[0];
+    expect(content?.type).toBe("markdown");
+    if (!content || content.type !== "markdown") {
+      throw new Error("Expected markdown content");
+    }
+
+    expect(content.markdown).toContain("https://example.com/report");
+    expect(content.markdown).not.toContain("https://t.co/example");
+  });
+
+  test("renders article video media as the highest bitrate mp4 link", () => {
+    const payload = {
+      data: {
+        tweetResult: {
+          result: {
+            rest_id: "2046628728210350366",
+            legacy: {
+              full_text: "Fallback text",
+              favorite_count: 12,
+              retweet_count: 3,
+              reply_count: 1,
+              created_at: "Tue Apr 21 16:34:47 +0000 2026",
+            },
+            core: {
+              user_results: {
+                result: {
+                  legacy: {
+                    name: "Google AI Studio",
+                    screen_name: "GoogleAIStudio",
+                  },
+                },
+              },
+            },
+            article: {
+              article_results: {
+                result: {
+                  title: "Article with video",
+                  media_entities: [
+                    {
+                      media_id: "2046627051822530560",
+                      media_info: {
+                        __typename: "ApiVideo",
+                        variants: [
+                          {
+                            bit_rate: 2176000,
+                            content_type: "video/mp4",
+                            url: "https://video.twimg.com/amplify_video/2046627051822530560/vid/avc1/1280x720/medium.mp4",
+                          },
+                          {
+                            content_type: "application/x-mpegURL",
+                            url: "https://video.twimg.com/amplify_video/2046627051822530560/pl/playlist.m3u8",
+                          },
+                          {
+                            bit_rate: 10368000,
+                            content_type: "video/mp4",
+                            url: "https://video.twimg.com/amplify_video/2046627051822530560/vid/avc1/1920x1080/high.mp4",
+                          },
+                        ],
+                      },
+                    },
+                  ],
+                  content_state: {
+                    blocks: [
+                      {
+                        type: "atomic",
+                        text: " ",
+                        data: {},
+                        entityRanges: [{ key: 0, length: 1, offset: 0 }],
+                        inlineStyleRanges: [],
+                      },
+                    ],
+                    entityMap: [
+                      {
+                        key: "0",
+                        value: {
+                          type: "MEDIA",
+                          mutability: "Immutable",
+                          data: {
+                            mediaItems: [{ mediaId: "2046627051822530560" }],
+                          },
+                        },
+                      },
+                    ],
+                  },
+                },
+              },
+            },
+          },
+        },
+      },
+    };
+
+    const document = extractArticleDocumentFromPayload(
+      payload,
+      "2046628728210350366",
+      "https://x.com/GoogleAIStudio/status/2046628728210350366",
+    );
+
+    expect(document).not.toBeNull();
+
+    const content = document?.content[0];
+    expect(content?.type).toBe("markdown");
+    if (!content || content.type !== "markdown") {
+      throw new Error("Expected markdown content");
+    }
+
+    expect(content.markdown).toBe(
+      "[video](https://video.twimg.com/amplify_video/2046627051822530560/vid/avc1/1920x1080/high.mp4)",
+    );
+  });
+});

packages/baoyu-fetch/src/__tests__/x-session.test.ts

@@ -0,0 +1,28 @@
+import { describe, expect, test } from "bun:test";
+
+import { buildXSessionCookieMap, hasRequiredXSessionCookies } from "../adapters/x/session";
+
+describe("X session helpers", () => {
+  test("keeps non-empty X session cookies", () => {
+    expect(
+      buildXSessionCookieMap([
+        { name: "auth_token", value: "auth" },
+        { name: "ct0", value: "csrf" },
+        { name: "twid", value: "u=123" },
+        { name: "ct0", value: "" },
+        { name: "", value: "ignored" },
+        { name: "gt", value: undefined },
+      ]),
+    ).toEqual({
+      auth_token: "auth",
+      ct0: "csrf",
+      twid: "u=123",
+    });
+  });
+
+  test("requires auth_token and ct0 for a ready X session", () => {
+    expect(hasRequiredXSessionCookies({ auth_token: "auth" })).toBe(false);
+    expect(hasRequiredXSessionCookies({ ct0: "csrf" })).toBe(false);
+    expect(hasRequiredXSessionCookies({ auth_token: "auth", ct0: "csrf" })).toBe(true);
+  });
+});

packages/baoyu-fetch/src/__tests__/x-single.test.ts

@@ -0,0 +1,260 @@
+import { describe, expect, test } from "bun:test";
+import { extractSingleTweetDocumentFromPayload } from "../adapters/x/single";
+
+describe("x single tweet extraction", () => {
+  test("replaces t.co links in note tweets with expanded urls", () => {
+    const payload = {
+      data: {
+        tweetResult: {
+          result: {
+            rest_id: "2036483061635039711",
+            legacy: {
+              full_text:
+                "First, some context:\n\n1. This analysis is based on data from @trueupio, one of my favorite collaborators and sources of data. They track job openings at tech companies and top startups around the world (over 9,000 companies) and make it easy to browse open gigs. Their data looks",
+              favorite_count: 43,
+              retweet_count: 1,
+              reply_count: 1,
+              created_at: "Tue Mar 24 16:39:32 +0000 2026",
+              entities: {
+                hashtags: [],
+                symbols: [],
+                timestamps: [],
+                urls: [],
+                user_mentions: [
+                  {
+                    id_str: "1407256023547613193",
+                    indices: [61, 70],
+                    name: "TrueUp",
+                    screen_name: "trueupio",
+                  },
+                ],
+              },
+            },
+            note_tweet: {
+              note_tweet_results: {
+                result: {
+                  text:
+                    "First, some context:\n\n1. This analysis is based on data from @trueupio, one of my favorite collaborators and sources of data. They track job openings at tech companies and top startups around the world (over 9,000 companies) and make it easy to browse open gigs. Their data looks at roles at tech companies—the most sought-after and lucrative jobs. (It doesn’t include roles at non-tech companies and consulting agencies.) Browse open roles here: https://t.co/x7ff2NjpP1\n\n2. Keep reading for highlights, or jump straight to the full report: https://t.co/AbqPp2TEde",
+                  entity_set: {
+                    hashtags: [],
+                    symbols: [],
+                    urls: [
+                      {
+                        display_url: "trueup.io/jobs",
+                        expanded_url: "https://trueup.io/jobs",
+                        indices: [447, 470],
+                        url: "https://t.co/x7ff2NjpP1",
+                      },
+                      {
+                        display_url: "lennysnewsletter.com/i/191595250/if…",
+                        expanded_url:
+                          "https://www.lennysnewsletter.com/i/191595250/if-youre-having-trouble-finding-a-job",
+                        indices: [541, 564],
+                        url: "https://t.co/AbqPp2TEde",
+                      },
+                    ],
+                    user_mentions: [
+                      {
+                        id_str: "1407256023547613193",
+                        indices: [61, 70],
+                        name: "TrueUp",
+                        screen_name: "trueupio",
+                      },
+                    ],
+                  },
+                },
+              },
+            },
+            core: {
+              user_results: {
+                result: {
+                  legacy: {
+                    name: "Lenny Rachitsky",
+                    screen_name: "lennysan",
+                  },
+                },
+              },
+            },
+          },
+        },
+      },
+    };
+
+    const document = extractSingleTweetDocumentFromPayload(
+      payload,
+      "2036483061635039711",
+      "https://x.com/lennysan/status/2036483061635039711",
+    );
+
+    expect(document).not.toBeNull();
+
+    const paragraphBlock = document?.content.find((block) => block.type === "paragraph");
+    expect(paragraphBlock).toEqual({
+      type: "paragraph",
+      text:
+        "First, some context:\n\n1. This analysis is based on data from @trueupio, one of my favorite collaborators and sources of data. They track job openings at tech companies and top startups around the world (over 9,000 companies) and make it easy to browse open gigs. Their data looks at roles at tech companies—the most sought-after and lucrative jobs. (It doesn’t include roles at non-tech companies and consulting agencies.) Browse open roles here: https://trueup.io/jobs\n\n2. Keep reading for highlights, or jump straight to the full report: https://www.lennysnewsletter.com/i/191595250/if-youre-having-trouble-finding-a-job",
+    });
+  });
+
+  test("upgrades image urls to high resolution for tweet and quoted tweet media", () => {
+    const payload = {
+      data: {
+        tweetResult: {
+          result: {
+            rest_id: "2036762680401223946",
+            legacy: {
+              full_text: "Main tweet text https://t.co/media",
+              favorite_count: 12,
+              retweet_count: 3,
+              reply_count: 1,
+              created_at: "Wed Mar 25 11:10:38 +0000 2026",
+              extended_entities: {
+                media: [
+                  {
+                    type: "photo",
+                    media_url_https: "https://pbs.twimg.com/media/main-image.png",
+                    url: "https://t.co/media",
+                  },
+                ],
+              },
+            },
+            core: {
+              user_results: {
+                result: {
+                  legacy: {
+                    name: "Eric Zakariasson",
+                    screen_name: "ericzakariasson",
+                  },
+                },
+              },
+            },
+            quoted_status_result: {
+              result: {
+                rest_id: "999",
+                legacy: {
+                  full_text: "Quoted tweet text",
+                  favorite_count: 4,
+                  retweet_count: 2,
+                  reply_count: 1,
+                  created_at: "Wed Mar 25 10:10:38 +0000 2026",
+                  extended_entities: {
+                    media: [
+                      {
+                        type: "photo",
+                        media_url_https: "https://pbs.twimg.com/media/quoted?format=jpeg&name=small",
+                      },
+                    ],
+                  },
+                },
+                core: {
+                  user_results: {
+                    result: {
+                      legacy: {
+                        name: "Quoted Author",
+                        screen_name: "quoted_author",
+                      },
+                    },
+                  },
+                },
+              },
+            },
+          },
+        },
+      },
+    };
+
+    const document = extractSingleTweetDocumentFromPayload(
+      payload,
+      "2036762680401223946",
+      "https://x.com/ericzakariasson/status/2036762680401223946",
+    );
+
+    expect(document).not.toBeNull();
+
+    const imageBlock = document?.content.find((block) => block.type === "image");
+    expect(imageBlock).toEqual({
+      type: "image",
+      url: "https://pbs.twimg.com/media/main-image?format=png&name=4096x4096",
+    });
+
+    const quoteBlock = document?.content.find((block) => block.type === "quote");
+    expect(quoteBlock).toEqual({
+      type: "quote",
+      text:
+        "Quoted Author (@quoted_author)\n\nQuoted tweet text\n\nphoto: https://pbs.twimg.com/media/quoted?format=jpg&name=4096x4096",
+    });
+  });
+
+  test("uses the highest bitrate mp4 variant for tweet video media", () => {
+    const payload = {
+      data: {
+        tweetResult: {
+          result: {
+            rest_id: "2046628728210350366",
+            legacy: {
+              full_text: "Video post https://t.co/video",
+              favorite_count: 12,
+              retweet_count: 3,
+              reply_count: 1,
+              created_at: "Tue Apr 21 16:34:47 +0000 2026",
+              extended_entities: {
+                media: [
+                  {
+                    type: "video",
+                    media_url_https: "https://pbs.twimg.com/amplify_video_thumb/2046627051822530560/img/poster.jpg",
+                    url: "https://t.co/video",
+                    video_info: {
+                      variants: [
+                        {
+                          content_type: "application/x-mpegURL",
+                          url: "https://video.twimg.com/amplify_video/2046627051822530560/pl/playlist.m3u8",
+                        },
+                        {
+                          bitrate: 256000,
+                          content_type: "video/mp4",
+                          url: "https://video.twimg.com/amplify_video/2046627051822530560/vid/avc1/480x270/low.mp4",
+                        },
+                        {
+                          bitrate: 10368000,
+                          content_type: "video/mp4",
+                          url: "https://video.twimg.com/amplify_video/2046627051822530560/vid/avc1/1920x1080/high.mp4",
+                        },
+                      ],
+                    },
+                  },
+                ],
+              },
+            },
+            core: {
+              user_results: {
+                result: {
+                  legacy: {
+                    name: "Google AI Studio",
+                    screen_name: "GoogleAIStudio",
+                  },
+                },
+              },
+            },
+          },
+        },
+      },
+    };
+
+    const document = extractSingleTweetDocumentFromPayload(
+      payload,
+      "2046628728210350366",
+      "https://x.com/GoogleAIStudio/status/2046628728210350366",
+    );
+
+    expect(document).not.toBeNull();
+
+    const listBlock = document?.content.find((block) => block.type === "list");
+    expect(listBlock).toEqual({
+      type: "list",
+      ordered: false,
+      items: [
+        "video: https://video.twimg.com/amplify_video/2046627051822530560/vid/avc1/1920x1080/high.mp4",
+      ],
+    });
+  });
+});

packages/baoyu-fetch/src/__tests__/x-thread.test.ts

@@ -0,0 +1,305 @@
+import { describe, expect, test } from "bun:test";
+import { extractThreadDocumentFromPayloads, extractThreadTweetsFromPayloads } from "../adapters/x/thread";
+
+function buildTweet(options: {
+  id: string;
+  text: string;
+  createdAt: string;
+  userId?: string;
+  screenName?: string;
+  name?: string;
+  conversationId?: string;
+  inReplyToStatusId?: string;
+  inReplyToUserId?: string;
+  quotedTweet?: unknown;
+}) {
+  const userId = options.userId ?? "3178231";
+  const screenName = options.screenName ?? "dotey";
+  const name = options.name ?? "宝玉";
+
+  return {
+    __typename: "Tweet",
+    rest_id: options.id,
+    legacy: {
+      id_str: options.id,
+      full_text: options.text,
+      favorite_count: 0,
+      retweet_count: 0,
+      reply_count: 0,
+      created_at: options.createdAt,
+      user_id_str: userId,
+      conversation_id_str: options.conversationId ?? options.id,
+      in_reply_to_status_id_str: options.inReplyToStatusId,
+      in_reply_to_user_id_str: options.inReplyToUserId,
+    },
+    core: {
+      user_results: {
+        result: {
+          core: {
+            name,
+            screen_name: screenName,
+          },
+          legacy: {},
+        },
+      },
+    },
+    quoted_status_result: options.quotedTweet
+      ? {
+          result: options.quotedTweet,
+        }
+      : undefined,
+  };
+}
+
+function tweetEntry(tweet: unknown) {
+  return {
+    content: {
+      itemContent: {
+        tweet_results: {
+          result: tweet,
+        },
+      },
+    },
+  };
+}
+
+function moduleTweetItem(tweet: unknown) {
+  return {
+    item: {
+      itemContent: {
+        tweet_results: {
+          result: tweet,
+        },
+      },
+    },
+  };
+}
+
+describe("x thread extraction", () => {
+  test("keeps only the continuous same-author reply chain", () => {
+    const rootId = "1996285439867556304";
+    const reply1Id = "1996285442275340783";
+    const reply2Id = "1996285444582146559";
+    const quotedId = "1993729800922341810";
+    const quotedInsideThreadId = "1993729800922341811";
+    const otherAuthorReplyId = "2000000000000000001";
+    const sameAuthorAfterOtherId = "2000000000000000002";
+
+    const root = buildTweet({
+      id: rootId,
+      text: "A thread for my nana banana pro prompts 🧵",
+      createdAt: "Wed Dec 03 18:28:32 +0000 2025",
+      conversationId: rootId,
+    });
+    const reply1 = buildTweet({
+      id: reply1Id,
+      text: "Prompt 1",
+      createdAt: "Wed Dec 03 18:28:33 +0000 2025",
+      conversationId: rootId,
+      inReplyToStatusId: rootId,
+      inReplyToUserId: "3178231",
+      quotedTweet: buildTweet({
+        id: quotedInsideThreadId,
+        text: "Quoted inside the thread body",
+        createdAt: "Tue Nov 25 18:28:35 +0000 2025",
+        screenName: "quoted_author",
+        name: "Quoted Author",
+      }),
+    });
+    const reply2 = buildTweet({
+      id: reply2Id,
+      text: "Prompt 2",
+      createdAt: "Wed Dec 03 18:28:34 +0000 2025",
+      conversationId: rootId,
+      inReplyToStatusId: reply1Id,
+      inReplyToUserId: "3178231",
+    });
+    const quotedSameAuthor = buildTweet({
+      id: quotedId,
+      text: "Quoted standalone tweet",
+      createdAt: "Tue Nov 25 18:28:34 +0000 2025",
+    });
+    const otherAuthorReply = buildTweet({
+      id: otherAuthorReplyId,
+      text: "Another author joined the conversation",
+      createdAt: "Wed Dec 03 18:28:35 +0000 2025",
+      userId: "42",
+      screenName: "someone_else",
+      name: "Someone Else",
+      conversationId: rootId,
+      inReplyToStatusId: reply2Id,
+      inReplyToUserId: "3178231",
+    });
+    const sameAuthorAfterOther = buildTweet({
+      id: sameAuthorAfterOtherId,
+      text: "This should not be part of the continuous author chain",
+      createdAt: "Wed Dec 03 18:28:36 +0000 2025",
+      conversationId: rootId,
+      inReplyToStatusId: otherAuthorReplyId,
+      inReplyToUserId: "42",
+    });
+
+    const payloads = [
+      {
+        data: {
+          threaded_conversation_with_injections_v2: {
+            instructions: [
+              {
+                type: "TimelineAddEntries",
+                entries: [
+                  tweetEntry(root),
+                  tweetEntry(reply1),
+                  tweetEntry(quotedSameAuthor),
+                  {
+                    content: {
+                      items: [moduleTweetItem(reply2)],
+                    },
+                  },
+                ],
+              },
+              {
+                type: "TimelineAddToModule",
+                moduleItems: [moduleTweetItem(otherAuthorReply), moduleTweetItem(sameAuthorAfterOther)],
+              },
+            ],
+          },
+        },
+      },
+    ];
+
+    const tweets = extractThreadTweetsFromPayloads(
+      payloads,
+      rootId,
+      "https://x.com/dotey/status/1996285439867556304",
+    );
+
+    expect(tweets.map((tweet) => tweet.id)).toEqual([rootId, reply1Id, reply2Id]);
+
+    const document = extractThreadDocumentFromPayloads(
+      payloads,
+      rootId,
+      "https://x.com/dotey/status/1996285439867556304",
+    );
+
+    expect(document).not.toBeNull();
+    expect(document?.metadata?.tweetCount).toBe(3);
+    expect(document?.metadata?.lastTweetId).toBe(reply2Id);
+
+    const content = document?.content[0];
+    expect(content?.type).toBe("markdown");
+    if (!content || content.type !== "markdown") {
+      throw new Error("Expected markdown content");
+    }
+
+    expect(content.markdown).toContain("Prompt 1");
+    expect(content.markdown).toContain("Prompt 2");
+    expect(content.markdown).toContain("Quoted inside the thread body");
+    expect(content.markdown).not.toContain("Quoted standalone tweet");
+    expect(content.markdown).not.toContain("This should not be part of the continuous author chain");
+  });
+
+  test("returns null when there is no same-author reply chain", () => {
+    const rootId = "1996285439867556304";
+    const root = buildTweet({
+      id: rootId,
+      text: "Root tweet",
+      createdAt: "Wed Dec 03 18:28:32 +0000 2025",
+      conversationId: rootId,
+    });
+    const quotedSameAuthor = buildTweet({
+      id: "1993729800922341810",
+      text: "Quoted standalone tweet",
+      createdAt: "Tue Nov 25 18:28:34 +0000 2025",
+    });
+
+    const payloads = [
+      {
+        data: {
+          threaded_conversation_with_injections_v2: {
+            instructions: [
+              {
+                type: "TimelineAddEntries",
+                entries: [tweetEntry(root), tweetEntry(quotedSameAuthor)],
+              },
+            ],
+          },
+        },
+      },
+    ];
+
+    expect(
+      extractThreadDocumentFromPayloads(
+        payloads,
+        rootId,
+        "https://x.com/dotey/status/1996285439867556304",
+      ),
+    ).toBeNull();
+  });
+
+  test("restores ancestors when the requested tweet is in the middle of a thread", () => {
+    const rootId = "1996285439867556304";
+    const reply1Id = "1996285442275340783";
+    const reply2Id = "1996285444582146559";
+
+    const root = buildTweet({
+      id: rootId,
+      text: "Root tweet",
+      createdAt: "Wed Dec 03 18:28:32 +0000 2025",
+      conversationId: rootId,
+    });
+    const reply1 = buildTweet({
+      id: reply1Id,
+      text: "Middle tweet",
+      createdAt: "Wed Dec 03 18:28:33 +0000 2025",
+      conversationId: rootId,
+      inReplyToStatusId: rootId,
+      inReplyToUserId: "3178231",
+    });
+    const reply2 = buildTweet({
+      id: reply2Id,
+      text: "Last tweet",
+      createdAt: "Wed Dec 03 18:28:34 +0000 2025",
+      conversationId: rootId,
+      inReplyToStatusId: reply1Id,
+      inReplyToUserId: "3178231",
+    });
+
+    const payloads = [
+      {
+        data: {
+          threaded_conversation_with_injections_v2: {
+            instructions: [
+              {
+                type: "TimelineAddEntries",
+                entries: [
+                  tweetEntry(root),
+                  tweetEntry(reply1),
+                  tweetEntry(reply2),
+                ],
+              },
+            ],
+          },
+        },
+      },
+    ];
+
+    const tweets = extractThreadTweetsFromPayloads(
+      payloads,
+      reply1Id,
+      "https://x.com/dotey/status/1996285442275340783",
+    );
+
+    expect(tweets.map((tweet) => tweet.id)).toEqual([rootId, reply1Id, reply2Id]);
+
+    const document = extractThreadDocumentFromPayloads(
+      payloads,
+      reply1Id,
+      "https://x.com/dotey/status/1996285442275340783",
+    );
+
+    expect(document).not.toBeNull();
+    expect(document?.metadata?.tweetId).toBe(rootId);
+    expect(document?.metadata?.lastTweetId).toBe(reply2Id);
+    expect(document?.metadata?.tweetCount).toBe(3);
+  });
+});

packages/baoyu-fetch/src/__tests__/youtube-utils.test.ts

@@ -0,0 +1,97 @@
+import { describe, expect, test } from "bun:test";
+import {
+  buildYouTubeThumbnailCandidates,
+  formatTimestampRange,
+  parseYouTubeDescriptionChapters,
+  parseYouTubeVideoId,
+  renderYouTubeTranscriptMarkdown,
+} from "../adapters/youtube/utils";
+
+describe("parseYouTubeVideoId", () => {
+  test("parses watch URLs", () => {
+    expect(parseYouTubeVideoId(new URL("https://www.youtube.com/watch?v=abc123"))).toBe("abc123");
+  });
+
+  test("parses youtu.be URLs", () => {
+    expect(parseYouTubeVideoId(new URL("https://youtu.be/abc123"))).toBe("abc123");
+  });
+
+  test("parses shorts URLs", () => {
+    expect(parseYouTubeVideoId(new URL("https://www.youtube.com/shorts/abc123"))).toBe("abc123");
+  });
+});
+
+describe("parseYouTubeDescriptionChapters", () => {
+  test("extracts chapter timestamps from description lines", () => {
+    expect(
+      parseYouTubeDescriptionChapters(`0:00 Intro
+2:15 What is a product engineer?
+10:05 Career paths`),
+    ).toEqual([
+      { title: "Intro", time: 0 },
+      { title: "What is a product engineer?", time: 135 },
+      { title: "Career paths", time: 605 },
+    ]);
+  });
+
+  test("ignores isolated timestamps that do not look like chapters", () => {
+    expect(parseYouTubeDescriptionChapters("Published on 2026-03-26\nSee you at 1:23")).toEqual([]);
+  });
+});
+
+describe("renderYouTubeTranscriptMarkdown", () => {
+  test("renders description before chapters and keeps every segment on its own line", () => {
+    const markdown = renderYouTubeTranscriptMarkdown({
+      description: "Line one\nLine two",
+      chapters: [
+        { title: "Intro", time: 0 },
+        { title: "Deep Dive", time: 4 },
+      ],
+      segments: [
+        { start: 0, end: 2, text: "Hello everyone." },
+        { start: 2, end: 4, text: "Welcome back." },
+        { start: 4, end: 7, text: "Now the details." },
+      ],
+    });
+
+    expect(markdown).toContain("## Description");
+    expect(markdown).toContain("Line one  \nLine two");
+    expect(markdown).toContain("## Chapters");
+    expect(markdown).toContain("### Intro [0:00 -> 0:04]");
+    expect(markdown).toContain("[0:00 -> 0:02] Hello everyone.");
+    expect(markdown).toContain("[0:02 -> 0:04] Welcome back.");
+    expect(markdown).toContain("### Deep Dive [0:04 -> 0:07]");
+    expect(markdown).toContain("[0:04 -> 0:07] Now the details.");
+  });
+
+  test("falls back to a transcript section when chapters are unavailable", () => {
+    const markdown = renderYouTubeTranscriptMarkdown({
+      segments: [{ start: 65, end: 70, text: "Single line." }],
+      chapters: [],
+    });
+
+    expect(markdown).toContain("## Transcript");
+    expect(markdown).toContain("[1:05 -> 1:10] Single line.");
+  });
+});
+
+describe("thumbnail helpers", () => {
+  test("prefers max resolution thumbnail candidates before listed fallbacks", () => {
+    expect(
+      buildYouTubeThumbnailCandidates("abc123", [
+        "https://i.ytimg.com/vi/abc123/hqdefault.jpg",
+        "https://i.ytimg.com/vi/abc123/mqdefault.jpg?foo=bar",
+      ]),
+    ).toEqual([
+      "https://i.ytimg.com/vi/abc123/maxresdefault.jpg",
+      "https://i.ytimg.com/vi/abc123/sddefault.jpg",
+      "https://i.ytimg.com/vi/abc123/hqdefault.jpg",
+      "https://i.ytimg.com/vi/abc123/mqdefault.jpg",
+      "https://i.ytimg.com/vi/abc123/default.jpg",
+    ]);
+  });
+
+  test("renders timestamp ranges with start and end values", () => {
+    expect(formatTimestampRange(3661, 3675)).toBe("[1:01:01 -> 1:01:15]");
+  });
+});

packages/baoyu-fetch/src/adapters/generic/index.ts

@@ -0,0 +1,74 @@
+import type { Adapter } from "../types";
+import { detectInteractionGate } from "../../browser/interaction-gates";
+import { captureNormalizedPageSnapshot } from "../../browser/page-snapshot";
+import { convertHtmlToMarkdown } from "../../extract/html-to-markdown";
+
+export const genericAdapter: Adapter = {
+  name: "generic",
+  match() {
+    return true;
+  },
+  async process(context) {
+    context.log.info(`Loading ${context.input.url.toString()} with generic adapter`);
+    await context.browser.goto(context.input.url.toString(), context.timeoutMs);
+
+    try {
+      await context.network.waitForIdle({
+        idleMs: 1_200,
+        timeoutMs: Math.min(context.timeoutMs, 15_000),
+      });
+    } catch {
+      context.log.debug("Network idle timed out on initial load; continuing.");
+    }
+
+    await context.browser.scrollToEnd({ maxSteps: 4, delayMs: 300 });
+
+    try {
+      await context.network.waitForIdle({
+        idleMs: 900,
+        timeoutMs: Math.min(context.timeoutMs, 10_000),
+      });
+    } catch {
+      context.log.debug("Network idle timed out after scrolling; continuing.");
+    }
+
+    const interaction = await detectInteractionGate(context.browser);
+    if (interaction) {
+      return {
+        status: "needs_interaction",
+        interaction,
+      };
+    }
+
+    const snapshot = await captureNormalizedPageSnapshot(context.browser);
+    const converted = await convertHtmlToMarkdown(snapshot.html, snapshot.finalUrl, {
+      enableRemoteMarkdownFallback: context.outputFormat === "markdown",
+      preserveBase64Images: context.downloadMedia,
+    });
+    const document = {
+      url: snapshot.finalUrl,
+      canonicalUrl: converted.metadata.canonicalUrl,
+      title: converted.metadata.title,
+      author: converted.metadata.author,
+      siteName: converted.metadata.siteName,
+      publishedAt: converted.metadata.publishedAt,
+      summary: converted.metadata.summary,
+      adapter: "generic",
+      metadata: {
+        coverImage: converted.metadata.coverImage,
+        language: converted.metadata.language,
+        capturedAt: converted.metadata.capturedAt,
+        conversionMethod: converted.conversionMethod,
+        fallbackReason: converted.fallbackReason,
+        kind: "generic/article",
+      },
+      content: converted.markdown ? [{ type: "markdown" as const, markdown: converted.markdown }] : [],
+    };
+
+    return {
+      status: "ok",
+      document,
+      media: converted.media,
+    };
+  },
+};

packages/baoyu-fetch/src/adapters/hn/index.ts

@@ -0,0 +1,391 @@
+import { JSDOM } from "jsdom";
+import TurndownService from "turndown";
+import { gfm } from "turndown-plugin-gfm";
+import type { Adapter } from "../types";
+import type { ExtractedDocument } from "../../extract/document";
+import { collectMediaFromDocument } from "../../media/markdown-media";
+
+const HN_BASE_URL = "https://news.ycombinator.com";
+
+const turndown = new TurndownService({
+  headingStyle: "atx",
+  bulletListMarker: "-",
+  codeBlockStyle: "fenced",
+});
+
+turndown.use(gfm);
+
+export interface HnItem {
+  id: number;
+  type: "story" | "comment" | "job" | "poll" | "pollopt" | string;
+  by?: string;
+  time?: number;
+  text?: string;
+  title?: string;
+  url?: string;
+  score?: number;
+  descendants?: number;
+  kids?: number[];
+  parent?: number;
+  deleted?: boolean;
+  dead?: boolean;
+}
+
+export interface HnCommentNode {
+  item: HnItem;
+  children: HnCommentNode[];
+}
+
+interface ParsedHnThread {
+  story: HnItem;
+  comments: HnCommentNode[];
+}
+
+function decodeHtmlText(value: string | undefined): string | undefined {
+  if (!value) {
+    return undefined;
+  }
+
+  const dom = new JSDOM(`<!doctype html><html><body>${value}</body></html>`);
+  return dom.window.document.body.textContent?.trim() || undefined;
+}
+
+function normalizeMarkdown(markdown: string): string {
+  return markdown
+    .replace(/\r\n/g, "\n")
+    .replace(/[ \t]+\n/g, "\n")
+    .replace(/\n{3,}/g, "\n\n")
+    .trim();
+}
+
+function convertHnHtmlToMarkdown(html: string | undefined, baseUrl: string): string {
+  if (!html?.trim()) {
+    return "";
+  }
+
+  const dom = new JSDOM(`<div id="__root">${html}</div>`, { url: baseUrl });
+  const root = dom.window.document.querySelector("#__root");
+  if (!root) {
+    return "";
+  }
+
+  root.querySelectorAll("a[href]").forEach((element) => {
+    const href = element.getAttribute("href");
+    if (!href) {
+      return;
+    }
+
+    try {
+      element.setAttribute("href", new URL(href, baseUrl).toString());
+    } catch {
+      // Ignore malformed URLs and keep the original href.
+    }
+  });
+
+  return normalizeMarkdown(turndown.turndown(root.innerHTML));
+}
+
+function formatIsoTimestamp(unixSeconds: number | undefined): string | undefined {
+  if (!unixSeconds || !Number.isFinite(unixSeconds)) {
+    return undefined;
+  }
+
+  return new Date(unixSeconds * 1_000).toISOString();
+}
+
+function formatDisplayTimestamp(unixSeconds: number | undefined): string {
+  const iso = formatIsoTimestamp(unixSeconds);
+  if (!iso) {
+    return "unknown time";
+  }
+
+  return iso.replace("T", " ").replace(".000Z", " UTC");
+}
+
+function indentMarkdown(markdown: string, spaces: number): string {
+  const prefix = " ".repeat(spaces);
+  return markdown
+    .split("\n")
+    .map((line) => (line ? `${prefix}${line}` : prefix))
+    .join("\n");
+}
+
+function renderCommentHeader(item: HnItem, pageUrl: string): string {
+  const author = item.by ?? "[deleted]";
+  const time = item.id
+    ? `[${formatDisplayTimestamp(item.time)}](${pageUrl}#${item.id})`
+    : formatDisplayTimestamp(item.time);
+  return `${author} · ${time}`;
+}
+
+function renderCommentNode(node: HnCommentNode, pageUrl: string, depth = 0): string {
+  const baseIndent = " ".repeat(depth * 4);
+  const lines = [`${baseIndent}- ${renderCommentHeader(node.item, pageUrl)}`];
+  const body = convertHnHtmlToMarkdown(node.item.text, pageUrl);
+
+  if (body) {
+    lines.push("");
+    lines.push(indentMarkdown(body, depth * 4 + 4));
+  } else if (node.item.deleted || node.item.dead) {
+    lines.push("");
+    lines.push(`${baseIndent}    [comment unavailable]`);
+  }
+
+  for (const child of node.children) {
+    lines.push("");
+    lines.push(renderCommentNode(child, pageUrl, depth + 1));
+  }
+
+  return lines.join("\n");
+}
+
+export function buildHnThreadMarkdown(
+  story: HnItem,
+  comments: HnCommentNode[],
+  pageUrl: string,
+): string {
+  const lines: string[] = [];
+  const storyUrl = story.url ? new URL(story.url, pageUrl).toString() : undefined;
+  const storyText = convertHnHtmlToMarkdown(story.text, pageUrl);
+
+  if (storyUrl && storyUrl !== pageUrl) {
+    lines.push(`Source: [${storyUrl}](${storyUrl})`);
+  }
+  lines.push(`HN Item: [${story.id}](${pageUrl})`);
+
+  const submittedBy = story.by ? ` by ${story.by}` : "";
+  const submittedAt = formatDisplayTimestamp(story.time);
+  lines.push(`Submitted${submittedBy} at ${submittedAt}`);
+
+  const stats: string[] = [];
+  if (typeof story.score === "number") {
+    stats.push(`${story.score} points`);
+  }
+  if (typeof story.descendants === "number") {
+    stats.push(`${story.descendants} comments`);
+  }
+  if (stats.length > 0) {
+    lines.push(stats.join(" | "));
+  }
+
+  if (storyText) {
+    lines.push("");
+    lines.push("## Post");
+    lines.push("");
+    lines.push(storyText);
+  }
+
+  lines.push("");
+  lines.push("## Comments");
+  lines.push("");
+
+  if (comments.length === 0) {
+    lines.push("No comments.");
+  } else {
+    lines.push(comments.map((comment) => renderCommentNode(comment, pageUrl)).join("\n\n"));
+  }
+
+  return normalizeMarkdown(lines.join("\n"));
+}
+
+export function buildHnDocument(
+  story: HnItem,
+  comments: HnCommentNode[],
+  pageUrl: string,
+): ExtractedDocument {
+  const decodedTitle = decodeHtmlText(story.title) ?? `HN Item ${story.id}`;
+
+  return {
+    url: pageUrl,
+    canonicalUrl: pageUrl,
+    title: decodedTitle,
+    author: story.by,
+    siteName: "Hacker News",
+    publishedAt: formatIsoTimestamp(story.time),
+    adapter: "hn",
+    metadata: {
+      kind: "hn/story",
+      storyId: story.id,
+      storyUrl: story.url ? new URL(story.url, pageUrl).toString() : undefined,
+      points: story.score,
+      commentCount: story.descendants,
+    },
+    content: [
+      {
+        type: "markdown",
+        markdown: buildHnThreadMarkdown(story, comments, pageUrl),
+      },
+    ],
+  };
+}
+
+export function parseHnItemId(url: URL): number | null {
+  if (url.hostname !== "news.ycombinator.com") {
+    return null;
+  }
+
+  if (url.pathname !== "/item") {
+    return null;
+  }
+
+  const value = url.searchParams.get("id");
+  if (!value || !/^\d+$/.test(value)) {
+    return null;
+  }
+
+  return Number(value);
+}
+
+function extractUnixSecondsFromAge(element: Element | null): number | undefined {
+  const title = element?.getAttribute("title")?.trim();
+  if (!title) {
+    return undefined;
+  }
+
+  const match = title.match(/(\d{9,})$/);
+  return match ? Number(match[1]) : undefined;
+}
+
+function extractScore(text: string | null | undefined): number | undefined {
+  if (!text) {
+    return undefined;
+  }
+
+  const match = text.match(/(\d+)/);
+  return match ? Number(match[1]) : undefined;
+}
+
+function extractCommentCount(container: ParentNode): number | undefined {
+  const anchors = Array.from(container.querySelectorAll("a"));
+  for (const anchor of anchors) {
+    const match = anchor.textContent?.trim().match(/(\d+)\s+comments?/i);
+    if (match) {
+      return Number(match[1]);
+    }
+  }
+  return undefined;
+}
+
+function normalizeStoryUrl(storyId: number, href: string | null | undefined, pageUrl: string): string | undefined {
+  if (!href) {
+    return undefined;
+  }
+
+  try {
+    const resolved = new URL(href, pageUrl).toString();
+    if (resolved === pageUrl || resolved === `${HN_BASE_URL}/item?id=${storyId}`) {
+      return undefined;
+    }
+    return resolved;
+  } catch {
+    return undefined;
+  }
+}
+
+export function extractHnThreadFromHtml(html: string, pageUrl: string): ParsedHnThread | null {
+  const dom = new JSDOM(html, { url: pageUrl });
+  const { document } = dom.window;
+  const storyRow = document.querySelector("table.fatitem tr.athing.submission");
+  if (!storyRow) {
+    return null;
+  }
+
+  const storyId = Number(storyRow.getAttribute("id"));
+  if (!Number.isFinite(storyId)) {
+    return null;
+  }
+
+  const titleLink = storyRow.querySelector(".titleline > a");
+  const subline = document.querySelector("table.fatitem .subline");
+  const topText = document.querySelector("table.fatitem .toptext");
+
+  const story: HnItem = {
+    id: storyId,
+    type: "story",
+    by: subline?.querySelector(".hnuser")?.textContent?.trim() || undefined,
+    time: extractUnixSecondsFromAge(subline?.querySelector(".age") ?? null),
+    title: titleLink?.innerHTML?.trim() || undefined,
+    url: normalizeStoryUrl(storyId, titleLink?.getAttribute("href"), pageUrl),
+    text: topText?.innerHTML?.trim() || undefined,
+    score: extractScore(subline?.querySelector(".score")?.textContent),
+    descendants: extractCommentCount(subline ?? document),
+  };
+
+  const roots: HnCommentNode[] = [];
+  const stack: HnCommentNode[] = [];
+
+  document.querySelectorAll("tr.athing.comtr").forEach((row) => {
+    const commentId = Number(row.getAttribute("id"));
+    if (!Number.isFinite(commentId)) {
+      return;
+    }
+
+    const indentRaw = row.querySelector("td.ind")?.getAttribute("indent");
+    const depth = indentRaw && /^\d+$/.test(indentRaw) ? Number(indentRaw) : 0;
+    const comhead = row.querySelector(".comhead");
+    const item: HnItem = {
+      id: commentId,
+      type: "comment",
+      by: comhead?.querySelector(".hnuser")?.textContent?.trim() || undefined,
+      time: extractUnixSecondsFromAge(comhead?.querySelector(".age") ?? null),
+      text: row.querySelector(".comment > .commtext")?.innerHTML?.trim() || undefined,
+      deleted: row.querySelector(".comment > .commtext") === null,
+    };
+
+    const node: HnCommentNode = {
+      item,
+      children: [],
+    };
+
+    while (stack.length > depth) {
+      stack.pop();
+    }
+
+    const parent = stack[stack.length - 1];
+    if (parent) {
+      parent.children.push(node);
+    } else {
+      roots.push(node);
+    }
+
+    stack.push(node);
+  });
+
+  return {
+    story,
+    comments: roots,
+  };
+}
+
+export const hnAdapter: Adapter = {
+  name: "hn",
+  match(input) {
+    return parseHnItemId(input.url) !== null;
+  },
+  async process(context) {
+    const itemId = parseHnItemId(context.input.url);
+    if (!itemId) {
+      return {
+        status: "no_document",
+      };
+    }
+
+    const pageUrl = context.input.url.toString();
+    context.log.info(`Loading ${pageUrl} with hn adapter`);
+    await context.browser.goto(pageUrl, context.timeoutMs);
+    const html = await context.browser.getHTML();
+    const thread = extractHnThreadFromHtml(html, pageUrl);
+    if (!thread) {
+      return {
+        status: "no_document",
+      };
+    }
+
+    const document = buildHnDocument(thread.story, thread.comments, pageUrl);
+    return {
+      status: "ok",
+      document,
+      media: collectMediaFromDocument(document),
+    };
+  },
+};

packages/baoyu-fetch/src/adapters/index.ts

@@ -0,0 +1,29 @@
+import type { Adapter, AdapterInput } from "./types";
+import { genericAdapter } from "./generic";
+import { hnAdapter } from "./hn";
+import { xAdapter } from "./x";
+import { youtubeAdapter } from "./youtube";
+
+const adapters: Adapter[] = [xAdapter, youtubeAdapter, hnAdapter, genericAdapter];
+
+export function listAdapters(): Adapter[] {
+  return adapters;
+}
+
+export function resolveAdapter(input: AdapterInput, forcedName?: string): Adapter {
+  if (forcedName) {
+    const forced = adapters.find((adapter) => adapter.name === forcedName);
+    if (!forced) {
+      throw new Error(`Unknown adapter: ${forcedName}`);
+    }
+    return forced;
+  }
+
+  const matched = adapters.find((adapter) => adapter.match(input));
+  if (!matched) {
+    throw new Error("No adapter matched the URL");
+  }
+  return matched;
+}
+
+export { genericAdapter };

packages/baoyu-fetch/src/adapters/types.ts

@@ -0,0 +1,73 @@
+import type { BrowserSession } from "../browser/session";
+import type { CdpClient } from "../browser/cdp-client";
+import type { NetworkJournal } from "../browser/network-journal";
+import type { ExtractedDocument } from "../extract/document";
+import type { MediaDownloadRequest, MediaDownloadResult, MediaAsset } from "../media/types";
+import type { Logger } from "../utils/logger";
+
+export interface AdapterInput {
+  url: URL;
+}
+
+export type LoginState = "logged_in" | "logged_out" | "unknown";
+export type InteractionKind = "login" | "cloudflare" | "recaptcha" | "hcaptcha" | "captcha" | "challenge";
+
+export interface AdapterLoginInfo {
+  provider: string;
+  state: LoginState;
+  required?: boolean;
+  username?: string;
+  reason?: string;
+}
+
+export interface WaitForInteractionRequest {
+  type: "wait_for_interaction";
+  kind: InteractionKind;
+  provider: string;
+  prompt: string;
+  reason?: string;
+  timeoutMs?: number;
+  pollIntervalMs?: number;
+  requiresVisibleBrowser?: boolean;
+}
+
+export type AdapterProcessResult =
+  | {
+      status: "ok";
+      document: ExtractedDocument;
+      media?: MediaAsset[];
+      login?: AdapterLoginInfo;
+    }
+  | {
+      status: "needs_interaction";
+      interaction: WaitForInteractionRequest;
+      login?: AdapterLoginInfo;
+    }
+  | {
+      status: "no_document";
+      login?: AdapterLoginInfo;
+    };
+
+export interface AdapterContext {
+  input: AdapterInput;
+  browser: BrowserSession;
+  network: NetworkJournal;
+  cdp: CdpClient;
+  log: Logger;
+  outputFormat: "markdown" | "json";
+  timeoutMs: number;
+  interactive: boolean;
+  downloadMedia: boolean;
+}
+
+export interface Adapter {
+  name: string;
+  match(input: AdapterInput): boolean;
+  checkLogin?(context: AdapterContext): Promise<AdapterLoginInfo>;
+  exportCookies?(context: AdapterContext, profileDir?: string): Promise<boolean>;
+  restoreCookies?(context: AdapterContext, profileDir?: string): Promise<boolean>;
+  downloadMedia?(request: MediaDownloadRequest): Promise<MediaDownloadResult>;
+  process(context: AdapterContext): Promise<AdapterProcessResult>;
+}
+
+export type { MediaAsset };

packages/baoyu-fetch/src/adapters/x/article.ts

@@ -0,0 +1,461 @@
+import type { ExtractedDocument } from "../../extract/document";
+import {
+  findTweetNode,
+  findTweetNodeById,
+  formatMediaList,
+  formatTweetAuthor,
+  getTweetAuthorMetadata,
+  getTweetText,
+  getUser,
+  isRecord,
+  normalizeTitle,
+  resolveBestXVideoVariantUrl,
+  toHighResXImageUrl,
+  toXTweet,
+} from "./shared";
+import type { JsonObject } from "./types";
+
+interface ArticleMedia {
+  kind: "image" | "video";
+  url: string;
+}
+
+function resolveArticleMedia(mediaInfo: JsonObject): ArticleMedia | null {
+  const videoUrl = resolveBestXVideoVariantUrl(mediaInfo);
+  if (videoUrl) {
+    return {
+      kind: "video",
+      url: videoUrl,
+    };
+  }
+
+  const rawUrl =
+    (typeof mediaInfo.original_img_url === "string" && mediaInfo.original_img_url) ||
+    (typeof mediaInfo.url === "string" && mediaInfo.url) ||
+    "";
+
+  if (!rawUrl) {
+    return null;
+  }
+
+  return {
+    kind: "image",
+    url: toHighResXImageUrl(rawUrl),
+  };
+}
+
+function resolveArticleMediaUrl(mediaInfo: JsonObject): string {
+  return resolveArticleMedia(mediaInfo)?.url ?? "";
+}
+
+function normalizeEntityMap(entityMap: unknown): Map<string, JsonObject> {
+  const normalized = new Map<string, JsonObject>();
+
+  if (Array.isArray(entityMap)) {
+    for (const entry of entityMap) {
+      if (!isRecord(entry)) {
+        continue;
+      }
+
+      const key =
+        typeof entry.key === "string" || typeof entry.key === "number"
+          ? String(entry.key)
+          : undefined;
+      const value = isRecord(entry.value) ? entry.value : undefined;
+      if (!key || !value) {
+        continue;
+      }
+      normalized.set(key, value);
+    }
+
+    return normalized;
+  }
+
+  if (!isRecord(entityMap)) {
+    return normalized;
+  }
+
+  for (const [key, value] of Object.entries(entityMap)) {
+    if (!isRecord(value)) {
+      continue;
+    }
+    normalized.set(key, value);
+  }
+
+  return normalized;
+}
+
+function getEntityMarkdown(entityMap: Map<string, JsonObject>, entityKey: unknown): string | null {
+  const key =
+    typeof entityKey === "string" || typeof entityKey === "number"
+      ? String(entityKey)
+      : undefined;
+  if (!key) {
+    return null;
+  }
+
+  const entity = entityMap.get(key);
+  if (!entity || entity.type !== "MARKDOWN") {
+    return null;
+  }
+
+  const data = isRecord(entity.data) ? entity.data : {};
+  if (typeof data.markdown !== "string") {
+    return null;
+  }
+
+  const markdown = data.markdown.trim();
+  return markdown || null;
+}
+
+function getLinkUrl(entityMap: Map<string, JsonObject>, entityKey: unknown): string | null {
+  const key =
+    typeof entityKey === "string" || typeof entityKey === "number"
+      ? String(entityKey)
+      : undefined;
+  if (!key) {
+    return null;
+  }
+
+  const entity = entityMap.get(key);
+  if (!entity || entity.type !== "LINK") {
+    return null;
+  }
+
+  const data = isRecord(entity.data) ? entity.data : {};
+  const candidates = [
+    data.expanded_url,
+    data.expandedUrl,
+    data.original_url,
+    data.originalUrl,
+    data.url,
+    data.display_url,
+    data.displayUrl,
+  ];
+
+  for (const candidate of candidates) {
+    if (typeof candidate === "string" && candidate.trim()) {
+      return candidate.trim();
+    }
+  }
+
+  return null;
+}
+
+function getTweetId(entityMap: Map<string, JsonObject>, entityKey: unknown): string | null {
+  const key =
+    typeof entityKey === "string" || typeof entityKey === "number"
+      ? String(entityKey)
+      : undefined;
+  if (!key) {
+    return null;
+  }
+
+  const entity = entityMap.get(key);
+  if (!entity || entity.type !== "TWEET") {
+    return null;
+  }
+
+  const data = isRecord(entity.data) ? entity.data : {};
+  if (typeof data.tweetId !== "string") {
+    return null;
+  }
+
+  return data.tweetId;
+}
+
+function buildMediaMap(articleResult: JsonObject): Map<string, ArticleMedia> {
+  const mediaMap = new Map<string, ArticleMedia>();
+  const mediaEntities = Array.isArray(articleResult.media_entities) ? articleResult.media_entities : [];
+
+  for (const entity of mediaEntities) {
+    if (!isRecord(entity) || typeof entity.media_id !== "string" || !isRecord(entity.media_info)) {
+      continue;
+    }
+
+    const media = resolveArticleMedia(entity.media_info);
+    if (media) {
+      mediaMap.set(entity.media_id, media);
+    }
+  }
+
+  const coverMedia = isRecord(articleResult.cover_media) ? articleResult.cover_media : null;
+  if (coverMedia && typeof coverMedia.media_id === "string" && isRecord(coverMedia.media_info)) {
+    const media = resolveArticleMedia(coverMedia.media_info);
+    if (media) {
+      mediaMap.set(coverMedia.media_id, media);
+    }
+  }
+
+  return mediaMap;
+}
+
+function getMediaMarkdown(
+  entityMap: Map<string, JsonObject>,
+  entityKey: unknown,
+  mediaMap: Map<string, ArticleMedia>,
+): string[] {
+  const key =
+    typeof entityKey === "string" || typeof entityKey === "number"
+      ? String(entityKey)
+      : undefined;
+  if (!key) {
+    return [];
+  }
+
+  const entity = entityMap.get(key);
+  if (!entity || entity.type !== "MEDIA") {
+    return [];
+  }
+
+  const data = isRecord(entity.data) ? entity.data : {};
+  const mediaItems = Array.isArray(data.mediaItems) ? data.mediaItems : [];
+  const media: ArticleMedia[] = [];
+
+  for (const item of mediaItems) {
+    if (!isRecord(item) || typeof item.mediaId !== "string") {
+      continue;
+    }
+    const mediaItem = mediaMap.get(item.mediaId);
+    if (mediaItem && !media.some((value) => value.url === mediaItem.url)) {
+      media.push(mediaItem);
+    }
+  }
+
+  return media.map((item) => item.kind === "image" ? `![](${item.url})` : `[video](${item.url})`);
+}
+
+function resolveTweetMarkdown(payloads: unknown[], tweetId: string, pageUrl: string): string | null {
+  for (const payload of payloads) {
+    const tweet = findTweetNodeById(payload, tweetId);
+    if (!tweet) {
+      continue;
+    }
+
+    const xTweet = toXTweet(tweet, pageUrl);
+    const author = formatTweetAuthor(xTweet) ?? xTweet.url;
+    const lines = [`> ${author}`, ...xTweet.text.split("\n").map((line) => `> ${line}`)];
+
+    const media = formatMediaList(xTweet.media).map((line) =>
+      line.startsWith("photo: ") ? `> ![](${line.slice("photo: ".length)})` : `> - ${line}`,
+    );
+
+    const parts = [lines.join("\n")];
+    if (media.length > 0) {
+      parts.push([">", ...media].join("\n"));
+    }
+    parts.push(`> ${xTweet.url}`);
+
+    return parts.join("\n").trim();
+  }
+
+  return `> Embedded tweet: https://x.com/i/status/${tweetId}`;
+}
+
+function replaceLinkEntities(text: string, block: JsonObject, entityMap: Map<string, JsonObject>): string {
+  const entityRanges = Array.isArray(block.entityRanges) ? block.entityRanges : [];
+  const replacements = entityRanges
+    .filter((range): range is JsonObject => isRecord(range))
+    .map((range) => {
+      const offset = typeof range.offset === "number" ? range.offset : -1;
+      const length = typeof range.length === "number" ? range.length : -1;
+      const url = getLinkUrl(entityMap, range.key);
+      return { offset, length, url };
+    })
+    .filter((range) => range.offset >= 0 && range.length > 0 && range.url)
+    .sort((left, right) => right.offset - left.offset);
+
+  let next = text;
+  for (const replacement of replacements) {
+    next =
+      next.slice(0, replacement.offset) +
+      replacement.url +
+      next.slice(replacement.offset + replacement.length);
+  }
+  return next;
+}
+
+function renderAtomicBlock(
+  block: JsonObject,
+  entityMap: Map<string, JsonObject>,
+  mediaMap: Map<string, ArticleMedia>,
+  payloads: unknown[],
+  pageUrl: string,
+): string | null {
+  const entityRanges = Array.isArray(block.entityRanges) ? block.entityRanges : [];
+  const parts: string[] = [];
+
+  for (const range of entityRanges) {
+    if (!isRecord(range)) {
+      continue;
+    }
+
+    const markdown = getEntityMarkdown(entityMap, range.key);
+    if (markdown) {
+      parts.push(markdown);
+      continue;
+    }
+
+    const mediaMarkdown = getMediaMarkdown(entityMap, range.key, mediaMap);
+    if (mediaMarkdown.length > 0) {
+      parts.push(mediaMarkdown.join("\n\n"));
+      continue;
+    }
+
+    const tweetId = getTweetId(entityMap, range.key);
+    if (tweetId) {
+      const tweetMarkdown = resolveTweetMarkdown(payloads, tweetId, pageUrl);
+      if (tweetMarkdown) {
+        parts.push(tweetMarkdown);
+      }
+    }
+  }
+
+  if (parts.length === 0) {
+    return null;
+  }
+
+  return parts.join("\n\n");
+}
+
+function renderArticleBlocks(
+  blocks: unknown[],
+  entityMap: Map<string, JsonObject>,
+  mediaMap: Map<string, ArticleMedia>,
+  payloads: unknown[],
+  pageUrl: string,
+): string {
+  const parts: string[] = [];
+  let orderedCounter = 0;
+
+  for (const block of blocks) {
+    if (!isRecord(block)) {
+      continue;
+    }
+
+    const blockType = typeof block.type === "string" ? block.type : "unstyled";
+    const rawText = typeof block.text === "string" ? block.text : "";
+    const text = replaceLinkEntities(rawText, block, entityMap).trim();
+    if (!text && blockType !== "atomic") {
+      continue;
+    }
+
+    if (blockType !== "ordered-list-item") {
+      orderedCounter = 0;
+    }
+
+    switch (blockType) {
+      case "header-one":
+        parts.push(`# ${text}`);
+        break;
+      case "header-two":
+        parts.push(`## ${text}`);
+        break;
+      case "header-three":
+        parts.push(`### ${text}`);
+        break;
+      case "blockquote":
+        parts.push(`> ${text}`);
+        break;
+      case "unordered-list-item":
+        parts.push(`- ${text}`);
+        break;
+      case "ordered-list-item":
+        orderedCounter += 1;
+        parts.push(`${orderedCounter}. ${text}`);
+        break;
+      case "code-block":
+        parts.push(`\`\`\`\n${text}\n\`\`\``);
+        break;
+      case "atomic": {
+        const markdown = renderAtomicBlock(block, entityMap, mediaMap, payloads, pageUrl);
+        if (markdown) {
+          parts.push(markdown);
+        }
+        break;
+      }
+      default:
+        parts.push(text);
+        break;
+    }
+  }
+
+  return parts.join("\n\n").trim();
+}
+
+function getArticleResult(tweet: JsonObject): JsonObject | null {
+  if (
+    isRecord(tweet.article) &&
+    isRecord(tweet.article.article_results) &&
+    isRecord(tweet.article.article_results.result)
+  ) {
+    return tweet.article.article_results.result as JsonObject;
+  }
+  return null;
+}
+
+function extractSummary(markdown: string): string | undefined {
+  const segments = markdown
+    .split(/\n\n+/)
+    .map((segment) => segment.trim())
+    .filter(Boolean);
+
+  const preferred = segments.find((segment) => !/^(#|>|- |\d+\. |\`\`\`)/.test(segment));
+  return preferred?.slice(0, 220);
+}
+
+export function extractArticleDocumentFromPayload(
+  payload: unknown,
+  statusId: string,
+  pageUrl: string,
+  payloads: unknown[] = [payload],
+): ExtractedDocument | null {
+  const tweet = findTweetNode(payload, statusId);
+  if (!tweet) {
+    return null;
+  }
+
+  const articleResult = getArticleResult(tweet);
+  if (!articleResult) {
+    return null;
+  }
+
+  const title = typeof articleResult.title === "string" ? articleResult.title.trim() : undefined;
+  const contentState = isRecord(articleResult.content_state) ? articleResult.content_state : {};
+  const blocks = Array.isArray(contentState.blocks) ? contentState.blocks : [];
+  const entityMap = normalizeEntityMap(contentState.entityMap);
+  const mediaMap = buildMediaMap(articleResult);
+  const richMarkdown = renderArticleBlocks(blocks, entityMap, mediaMap, payloads, pageUrl);
+  const plainText = typeof articleResult.plain_text === "string" ? articleResult.plain_text.trim() : "";
+  const markdown = richMarkdown || plainText || getTweetText(tweet);
+  if (!markdown) {
+    return null;
+  }
+
+  const xTweet = toXTweet(tweet, pageUrl);
+  const user = getUser(tweet);
+  const coverMedia = isRecord(articleResult.cover_media) ? articleResult.cover_media : null;
+  const coverMediaInfo = coverMedia && isRecord(coverMedia.media_info) ? coverMedia.media_info : null;
+  const coverImage = coverMediaInfo ? resolveArticleMediaUrl(coverMediaInfo) || undefined : undefined;
+
+  return {
+    url: pageUrl,
+    canonicalUrl: xTweet.url,
+    title: title || normalizeTitle(xTweet.text, "X Article"),
+    author: formatTweetAuthor(xTweet),
+    siteName: "X",
+    publishedAt: xTweet.createdAt,
+    summary: extractSummary(markdown) || xTweet.text.slice(0, 200) || undefined,
+    adapter: "x",
+    metadata: {
+      kind: "x/article",
+      tweetId: xTweet.id,
+      coverImage,
+      authorName: xTweet.authorName ?? user.name,
+      authorUsername: xTweet.author ?? user.screenName,
+      authorUrl: (xTweet.author ?? user.screenName) ? `https://x.com/${xTweet.author ?? user.screenName}` : undefined,
+      ...getTweetAuthorMetadata(xTweet),
+    },
+    content: [{ type: "markdown", markdown }],
+  };
+}

packages/baoyu-fetch/src/adapters/x/index.ts

@@ -0,0 +1,134 @@
+import type { Adapter, AdapterLoginInfo } from "../types";
+import { exportCookies, restoreCookies, type CookieSidecarConfig } from "../../browser/cookie-sidecar";
+import { detectInteractionGate } from "../../browser/interaction-gates";
+import type { ExtractedDocument } from "../../extract/document";
+import { collectMediaFromDocument } from "../../media/markdown-media";
+import { extractArticleDocumentFromPayload } from "./article";
+import { buildNeedsLoginResult, detectXLogin } from "./login";
+import { extractStatusId, isXHost } from "./match";
+import { collectXJsonPayloads, waitForInitialXPayload } from "./payloads";
+import { extractSingleTweetDocumentFromPayload } from "./single";
+import { extractThreadDocumentFromPayloads } from "./thread";
+import { loadFullXThread } from "./thread-loader";
+
+const cookieConfig: CookieSidecarConfig = {
+  urls: ["https://x.com/", "https://twitter.com/"],
+  filename: "x-session-cookies.json",
+  requiredCookieNames: ["auth_token", "ct0"],
+  filterCookie: (c) => {
+    const d = c.domain ?? "";
+    return d.endsWith("x.com") || d.endsWith("twitter.com");
+  },
+};
+
+function extractDocumentFromPayloads(
+  payloads: unknown[],
+  statusId: string,
+  pageUrl: string,
+): ExtractedDocument | null {
+  for (const payload of payloads) {
+    const articleDocument = extractArticleDocumentFromPayload(payload, statusId, pageUrl, payloads);
+    if (articleDocument) {
+      return articleDocument;
+    }
+  }
+
+  const threadDocument = extractThreadDocumentFromPayloads(payloads, statusId, pageUrl);
+  if (threadDocument) {
+    return threadDocument;
+  }
+
+  for (const payload of payloads) {
+    const singleDocument = extractSingleTweetDocumentFromPayload(payload, statusId, pageUrl);
+    if (singleDocument) {
+      return singleDocument;
+    }
+  }
+
+  return null;
+}
+
+async function ensureXLoginState(context: Parameters<Adapter["process"]>[0]): Promise<AdapterLoginInfo> {
+  return detectXLogin(context);
+}
+
+export const xAdapter: Adapter = {
+  name: "x",
+  match(input) {
+    return isXHost(input.url.hostname);
+  },
+  async checkLogin(context) {
+    return detectXLogin(context);
+  },
+  async exportCookies(context, profileDir) {
+    return exportCookies(context.browser.targetSession, cookieConfig, profileDir);
+  },
+  async restoreCookies(context, profileDir) {
+    return restoreCookies(context.browser.targetSession, cookieConfig, profileDir);
+  },
+  async process(context) {
+    const statusId = extractStatusId(context.input.url);
+    if (!statusId) {
+      return {
+        status: "no_document",
+      };
+    }
+
+    context.log.info(`Loading ${context.input.url.toString()} with x adapter`);
+    await context.browser.goto(context.input.url.toString(), context.timeoutMs);
+
+    const interaction = await detectInteractionGate(context.browser);
+    if (interaction) {
+      return {
+        status: "needs_interaction",
+        interaction,
+      };
+    }
+
+    let login = await ensureXLoginState(context);
+    if (login.state === "logged_out") {
+      return buildNeedsLoginResult(login);
+    }
+
+    await waitForInitialXPayload(context);
+    await loadFullXThread(context, statusId);
+
+    const pageUrl = await context.browser.getURL();
+    const postLoadInteraction = await detectInteractionGate(context.browser);
+    if (postLoadInteraction) {
+      return {
+        status: "needs_interaction",
+        interaction: postLoadInteraction,
+        login,
+      };
+    }
+
+    login = await ensureXLoginState(context).catch(() => login);
+    if (login.state === "logged_out") {
+      return buildNeedsLoginResult(login);
+    }
+
+    const payloads = await collectXJsonPayloads(context);
+    if (payloads.length === 0) {
+      return {
+        status: "no_document",
+        login,
+      };
+    }
+
+    const document = extractDocumentFromPayloads(payloads, statusId, pageUrl);
+    if (document) {
+      return {
+        status: "ok",
+        document,
+        media: collectMediaFromDocument(document),
+        login,
+      };
+    }
+
+    return {
+      status: "no_document",
+      login,
+    };
+  },
+};

packages/baoyu-fetch/src/adapters/x/login.ts

@@ -0,0 +1,80 @@
+import type { AdapterContext, AdapterLoginInfo, AdapterProcessResult } from "../types";
+
+interface XLoginSnapshot {
+  currentUrl: string;
+  hasAccountMenu: boolean;
+  hasLoginInputs: boolean;
+  bodyText: string;
+}
+
+export async function detectXLogin(context: AdapterContext): Promise<AdapterLoginInfo> {
+  const snapshot = await context.browser.evaluate<XLoginSnapshot>(`
+    (() => {
+      const bodyText = (document.body?.innerText ?? "").slice(0, 2500);
+      return {
+        currentUrl: window.location.href,
+        hasAccountMenu: Boolean(
+          document.querySelector(
+            '[data-testid="SideNav_AccountSwitcher_Button"], [data-testid="AppTabBar_Profile_Link"], [aria-label="Account menu"]'
+          )
+        ),
+        hasLoginInputs: Boolean(
+          document.querySelector(
+            'input[name="text"], input[name="password"], input[autocomplete="username"], input[autocomplete="current-password"]'
+          )
+        ),
+        bodyText,
+      };
+    })()
+  `).catch(async () => ({
+    currentUrl: await context.browser.getURL().catch(() => context.input.url.toString()),
+    hasAccountMenu: false,
+    hasLoginInputs: false,
+    bodyText: "",
+  }));
+
+  if (
+    /\/i\/flow\/login|\/login/i.test(snapshot.currentUrl) ||
+    snapshot.hasLoginInputs ||
+    /sign in to x|join x today|登录 x|注册 x|登录到 x/i.test(snapshot.bodyText)
+  ) {
+    return {
+      provider: "x",
+      state: "logged_out",
+      required: true,
+      reason: "X login page detected",
+    };
+  }
+
+  if (snapshot.hasAccountMenu) {
+    return {
+      provider: "x",
+      state: "logged_in",
+    };
+  }
+
+  return {
+    provider: "x",
+    state: "unknown",
+  };
+}
+
+export function buildNeedsLoginResult(login: AdapterLoginInfo): AdapterProcessResult {
+  return {
+    status: "needs_interaction",
+    login: {
+      ...login,
+      provider: "x",
+      state: login.state === "logged_in" ? "unknown" : login.state,
+      required: true,
+    },
+    interaction: {
+      type: "wait_for_interaction",
+      kind: "login",
+      provider: "x",
+      reason: login.reason,
+      prompt: "Please sign in to X in the opened Chrome window. Extraction will continue automatically once login is detected.",
+      requiresVisibleBrowser: true,
+    },
+  };
+}

packages/baoyu-fetch/src/adapters/x/match.ts

@@ -0,0 +1,9 @@
+export function isXHost(hostname: string): boolean {
+  return ["x.com", "www.x.com", "twitter.com", "www.twitter.com"].includes(hostname);
+}
+
+export function extractStatusId(url: URL): string | undefined {
+  const match = url.pathname.match(/\/(?:status|article)\/(\d+)/);
+  return match?.[1];
+}
+

packages/baoyu-fetch/src/adapters/x/payloads.ts

@@ -0,0 +1,50 @@
+import type { AdapterContext } from "../types";
+import { filterXGraphQlEntries } from "./shared";
+
+export function getRelevantXThreadEntries(context: AdapterContext) {
+  return filterXGraphQlEntries(context.network.getEntries()).filter(
+    (entry) =>
+      entry.method === "GET" &&
+      entry.finished &&
+      (
+        entry.url.includes("TweetDetail") ||
+        entry.url.includes("TweetResultByRestId") ||
+        entry.url.includes("TweetResultsByRestIds")
+      ),
+  );
+}
+
+export async function prefetchRelevantXThreadBodies(context: AdapterContext): Promise<void> {
+  const entries = getRelevantXThreadEntries(context).filter((entry) => entry.body === undefined && !entry.bodyError);
+  for (const entry of entries) {
+    await context.network.ensureBody(entry);
+  }
+}
+
+export async function collectXJsonPayloads(context: AdapterContext): Promise<unknown[]> {
+  await prefetchRelevantXThreadBodies(context);
+  const entries = getRelevantXThreadEntries(context);
+
+  const payloads: unknown[] = [];
+  for (const entry of entries) {
+    const payload = await context.network.getJsonBody(entry);
+    if (payload) {
+      payloads.push(payload);
+    }
+  }
+  return payloads;
+}
+
+export async function waitForInitialXPayload(context: AdapterContext): Promise<void> {
+  try {
+    await context.network.waitForResponse(
+      (entry) =>
+        entry.url.includes("/graphql/") &&
+        (entry.url.includes("TweetDetail") || entry.url.includes("TweetResultByRestId")),
+      { timeoutMs: Math.min(context.timeoutMs, 15_000) },
+    );
+    await prefetchRelevantXThreadBodies(context);
+  } catch {
+    context.log.debug("No tweet GraphQL response observed before timeout.");
+  }
+}

packages/baoyu-fetch/src/adapters/x/session.ts

@@ -0,0 +1,47 @@
+import type { AdapterContext } from "../types";
+
+const X_SESSION_URLS = ["https://x.com/", "https://twitter.com/"] as const;
+const REQUIRED_X_SESSION_COOKIES = ["auth_token", "ct0"] as const;
+
+interface CookieLike {
+  name?: string;
+  value?: string | null;
+}
+
+interface NetworkGetCookiesResult {
+  cookies?: CookieLike[];
+}
+
+export function buildXSessionCookieMap(cookies: readonly CookieLike[]): Record<string, string> {
+  const cookieMap: Record<string, string> = {};
+  for (const cookie of cookies) {
+    const name = cookie.name?.trim();
+    const value = cookie.value?.trim();
+    if (!name || !value) {
+      continue;
+    }
+    cookieMap[name] = value;
+  }
+  return cookieMap;
+}
+
+export function hasRequiredXSessionCookies(cookieMap: Record<string, string>): boolean {
+  return REQUIRED_X_SESSION_COOKIES.every((name) => Boolean(cookieMap[name]));
+}
+
+export async function readXSessionCookieMap(
+  context: Pick<AdapterContext, "browser">,
+): Promise<Record<string, string>> {
+  const { cookies } = await context.browser.targetSession.send<NetworkGetCookiesResult>(
+    "Network.getCookies",
+    { urls: [...X_SESSION_URLS] },
+  );
+  return buildXSessionCookieMap(cookies ?? []);
+}
+
+export async function isXSessionReady(
+  context: Pick<AdapterContext, "browser">,
+): Promise<boolean> {
+  const cookieMap = await readXSessionCookieMap(context);
+  return hasRequiredXSessionCookies(cookieMap);
+}

packages/baoyu-fetch/src/adapters/x/shared.ts

@@ -0,0 +1,423 @@
+import path from "node:path";
+import type { NetworkEntry } from "../../browser/network-journal";
+import type { XMedia, XQuotedTweet, XTweet, XUser, JsonObject } from "./types";
+
+const X_IMAGE_EXTENSIONS = new Set(["jpg", "jpeg", "png", "webp", "gif", "bmp", "avif"]);
+
+function emptyObject(): JsonObject {
+  return {};
+}
+
+export function isRecord(value: unknown): value is JsonObject {
+  return Boolean(value) && typeof value === "object" && !Array.isArray(value);
+}
+
+export function walk(value: unknown, visitor: (node: unknown) => boolean | void): boolean {
+  if (visitor(value)) {
+    return true;
+  }
+
+  if (Array.isArray(value)) {
+    for (const item of value) {
+      if (walk(item, visitor)) {
+        return true;
+      }
+    }
+    return false;
+  }
+
+  if (isRecord(value)) {
+    for (const child of Object.values(value)) {
+      if (walk(child, visitor)) {
+        return true;
+      }
+    }
+  }
+
+  return false;
+}
+
+function hasTweetText(node: JsonObject): boolean {
+  const legacy = isRecord(node.legacy) ? node.legacy : emptyObject();
+  return (
+    typeof legacy.full_text === "string" ||
+    typeof getNoteTweetText(node) === "string"
+  );
+}
+
+export function findTweetNodeById(payload: unknown, tweetId: string): JsonObject | null {
+  let match: JsonObject | null = null;
+
+  walk(payload, (node) => {
+    if (!isRecord(node) || typeof node.rest_id !== "string" || !isRecord(node.legacy)) {
+      return false;
+    }
+
+    if (!hasTweetText(node)) {
+      return false;
+    }
+
+    if (node.rest_id === tweetId) {
+      match = node;
+      return true;
+    }
+
+    return false;
+  });
+
+  return match;
+}
+
+export function findTweetNode(payload: unknown, statusId: string): JsonObject | null {
+  let firstMatch: JsonObject | null = null;
+  const exactMatch = findTweetNodeById(payload, statusId);
+  if (exactMatch) {
+    return exactMatch;
+  }
+
+  walk(payload, (node) => {
+    if (!isRecord(node) || typeof node.rest_id !== "string" || !isRecord(node.legacy)) {
+      return false;
+    }
+    if (!hasTweetText(node)) {
+      return false;
+    }
+    if (!firstMatch) {
+      firstMatch = node;
+    }
+    return false;
+  });
+
+  return firstMatch;
+}
+
+export function getLegacy(tweet: JsonObject): JsonObject {
+  return isRecord(tweet.legacy) ? tweet.legacy : emptyObject();
+}
+
+export function unwrapTweetResult(node: unknown): JsonObject | null {
+  if (!isRecord(node)) {
+    return null;
+  }
+
+  if (node.__typename === "TweetWithVisibilityResults" && isRecord(node.tweet)) {
+    return unwrapTweetResult(node.tweet);
+  }
+
+  const tweet = isRecord(node.tweet) ? (node.tweet as JsonObject) : node;
+  if (typeof tweet.rest_id !== "string" || !isRecord(tweet.legacy)) {
+    return null;
+  }
+
+  return tweet;
+}
+
+export function getUser(tweet: JsonObject): XUser {
+  const result =
+    isRecord(tweet.core) &&
+    isRecord(tweet.core.user_results) &&
+    isRecord(tweet.core.user_results.result)
+      ? (tweet.core.user_results.result as JsonObject)
+      : emptyObject();
+  const legacy = isRecord(result.legacy) ? result.legacy : emptyObject();
+  const core = isRecord(result.core) ? result.core : emptyObject();
+  return {
+    name:
+      (typeof legacy.name === "string" ? legacy.name : undefined) ??
+      (typeof core.name === "string" ? core.name : undefined),
+    screenName:
+      (typeof legacy.screen_name === "string" ? legacy.screen_name : undefined) ??
+      (typeof core.screen_name === "string" ? core.screen_name : undefined),
+  };
+}
+
+function getNoteTweetResult(tweet: JsonObject): JsonObject | null {
+  if (
+    !isRecord(tweet.note_tweet) ||
+    !isRecord(tweet.note_tweet.note_tweet_results) ||
+    !isRecord(tweet.note_tweet.note_tweet_results.result)
+  ) {
+    return null;
+  }
+
+  return tweet.note_tweet.note_tweet_results.result as JsonObject;
+}
+
+function getNoteTweetText(tweet: JsonObject): string | undefined {
+  const noteTweet = getNoteTweetResult(tweet);
+  return typeof noteTweet?.text === "string" ? noteTweet.text : undefined;
+}
+
+interface TweetUrlEntity {
+  url: string;
+  expandedUrl?: string;
+  displayUrl?: string;
+}
+
+function collectTweetUrlEntities(values: unknown[]): TweetUrlEntity[] {
+  return values.reduce<TweetUrlEntity[]>((entities, value) => {
+      if (!isRecord(value) || typeof value.url !== "string" || !value.url) {
+        return entities;
+      }
+
+      entities.push({
+        url: value.url,
+        expandedUrl: typeof value.expanded_url === "string" ? value.expanded_url : undefined,
+        displayUrl: typeof value.display_url === "string" ? value.display_url : undefined,
+      });
+
+      return entities;
+    }, []);
+}
+
+function getTweetUrlEntities(tweet: JsonObject): TweetUrlEntity[] {
+  const noteTweet = getNoteTweetResult(tweet);
+  const noteTweetEntitySet = noteTweet && isRecord(noteTweet.entity_set) ? noteTweet.entity_set : emptyObject();
+  const noteTweetUrls = collectTweetUrlEntities(Array.isArray(noteTweetEntitySet.urls) ? noteTweetEntitySet.urls : []);
+
+  const legacy = getLegacy(tweet);
+  const legacyEntities = isRecord(legacy.entities) ? legacy.entities : emptyObject();
+  const legacyUrls = collectTweetUrlEntities(Array.isArray(legacyEntities.urls) ? legacyEntities.urls : []);
+
+  const seen = new Set<string>();
+  return [...noteTweetUrls, ...legacyUrls].filter((value) => {
+    if (seen.has(value.url)) {
+      return false;
+    }
+    seen.add(value.url);
+    return true;
+  });
+}
+
+export function getTweetText(tweet: JsonObject): string {
+  const legacy = getLegacy(tweet);
+  let text =
+    getNoteTweetText(tweet) ?? (typeof legacy.full_text === "string" ? legacy.full_text : "");
+
+  for (const value of getTweetUrlEntities(tweet)) {
+    const replacement =
+      (typeof value.expandedUrl === "string" && value.expandedUrl) ||
+      (typeof value.displayUrl === "string" && value.displayUrl) ||
+      value.url;
+    text = text.replaceAll(value.url, replacement);
+  }
+
+  const extendedEntities = isRecord(legacy.extended_entities) ? legacy.extended_entities : emptyObject();
+  const media = Array.isArray(extendedEntities.media) ? extendedEntities.media : [];
+  for (const value of media) {
+    if (isRecord(value) && typeof value.url === "string") {
+      text = text.replaceAll(value.url, "").trim();
+    }
+  }
+
+  return text.replace(/\n{3,}/g, "\n\n").trim();
+}
+
+function normalizeXImageExtension(raw: string | undefined | null): string | undefined {
+  if (!raw) {
+    return undefined;
+  }
+
+  const normalized = raw.replace(/^\./, "").trim().toLowerCase();
+  if (!normalized) {
+    return undefined;
+  }
+
+  return normalized === "jpeg" ? "jpg" : normalized;
+}
+
+export function toHighResXImageUrl(rawUrl: string): string {
+  try {
+    const parsed = new URL(rawUrl);
+    if (parsed.hostname.toLowerCase() !== "pbs.twimg.com") {
+      return rawUrl;
+    }
+
+    const pathExtension = normalizeXImageExtension(path.posix.extname(parsed.pathname));
+    const format = normalizeXImageExtension(parsed.searchParams.get("format")) ?? pathExtension;
+    if (!format || !X_IMAGE_EXTENSIONS.has(format)) {
+      return rawUrl;
+    }
+
+    if (pathExtension) {
+      parsed.pathname = parsed.pathname.replace(new RegExp(`\\.${pathExtension}$`, "i"), "");
+    }
+
+    parsed.searchParams.set("format", format);
+    parsed.searchParams.set("name", "4096x4096");
+    return parsed.toString();
+  } catch {
+    return rawUrl;
+  }
+}
+
+function getVideoVariantBitrate(variant: JsonObject): number {
+  const value = variant.bitrate ?? variant.bit_rate;
+  return typeof value === "number" && Number.isFinite(value) ? value : 0;
+}
+
+function getVideoVariantContentType(variant: JsonObject): string {
+  const value = variant.content_type ?? variant.contentType;
+  return typeof value === "string" ? value.toLowerCase() : "";
+}
+
+export function resolveBestXVideoVariantUrl(mediaInfo: unknown): string | undefined {
+  if (!isRecord(mediaInfo)) {
+    return undefined;
+  }
+
+  const variantsSource =
+    Array.isArray(mediaInfo.variants)
+      ? mediaInfo.variants
+      : isRecord(mediaInfo.video_info) && Array.isArray(mediaInfo.video_info.variants)
+        ? mediaInfo.video_info.variants
+        : [];
+
+  const variants = variantsSource
+    .filter(
+      (variant): variant is JsonObject =>
+        isRecord(variant) && typeof variant.url === "string" && variant.url.length > 0,
+    )
+    .filter((variant) => getVideoVariantContentType(variant) === "video/mp4")
+    .sort((left, right) => getVideoVariantBitrate(right) - getVideoVariantBitrate(left));
+
+  return typeof variants[0]?.url === "string" ? variants[0].url : undefined;
+}
+
+export function getTweetMedia(tweet: JsonObject): XMedia[] {
+  const legacy = getLegacy(tweet);
+  const extendedEntities = isRecord(legacy.extended_entities) ? legacy.extended_entities : emptyObject();
+  const media = Array.isArray(extendedEntities.media) ? extendedEntities.media : [];
+
+  return media
+    .map((value) => {
+      if (!isRecord(value) || typeof value.type !== "string") {
+        return null;
+      }
+      if (value.type === "photo" && typeof value.media_url_https === "string") {
+        return {
+          type: value.type,
+          url: toHighResXImageUrl(value.media_url_https),
+          alt: typeof value.ext_alt_text === "string" ? value.ext_alt_text : undefined,
+        };
+      }
+      if (value.type === "video" || value.type === "animated_gif") {
+        const videoUrl = resolveBestXVideoVariantUrl(value);
+        if (!videoUrl) {
+          return null;
+        }
+        return {
+          type: value.type,
+          url: videoUrl,
+        };
+      }
+      return null;
+    })
+    .filter((value): value is XMedia => value !== null);
+}
+
+export function getTweetUrl(tweet: JsonObject, fallbackUrl: string): string {
+  const user = getUser(tweet);
+  const fallbackScreenName = extractScreenNameFromUrl(fallbackUrl);
+  const id = typeof tweet.rest_id === "string" ? tweet.rest_id : "";
+  const screenName = user.screenName ?? fallbackScreenName;
+  if (screenName && id) {
+    return `https://x.com/${screenName}/status/${id}`;
+  }
+  return fallbackUrl;
+}
+
+export function getQuotedTweet(tweet: JsonObject, fallbackUrl: string): XQuotedTweet | undefined {
+  const quoted = unwrapTweetResult(
+    isRecord(tweet.quoted_status_result) ? tweet.quoted_status_result.result : null,
+  );
+  if (!quoted) {
+    return undefined;
+  }
+
+  const user = getUser(quoted);
+  return {
+    id: typeof quoted.rest_id === "string" ? quoted.rest_id : "",
+    author: user.screenName,
+    authorName: user.name,
+    text: getTweetText(quoted),
+    url: getTweetUrl(quoted, fallbackUrl),
+    media: getTweetMedia(quoted),
+  };
+}
+
+export function extractScreenNameFromUrl(url: string): string | undefined {
+  try {
+    const parsed = new URL(url);
+    const match = parsed.pathname.match(/^\/([^/]+)\/(?:status|article)\//);
+    if (!match) {
+      return undefined;
+    }
+    if (match[1] === "i") {
+      return undefined;
+    }
+    return match[1];
+  } catch {
+    return undefined;
+  }
+}
+
+export function toXTweet(tweet: JsonObject, fallbackUrl: string): XTweet {
+  const legacy = getLegacy(tweet);
+  const user = getUser(tweet);
+  const fallbackScreenName = extractScreenNameFromUrl(fallbackUrl);
+  const screenName = user.screenName ?? fallbackScreenName;
+  return {
+    id: typeof tweet.rest_id === "string" ? tweet.rest_id : "",
+    author: screenName,
+    authorName: user.name,
+    text: getTweetText(tweet),
+    likes: typeof legacy.favorite_count === "number" ? legacy.favorite_count : 0,
+    retweets: typeof legacy.retweet_count === "number" ? legacy.retweet_count : 0,
+    replies: typeof legacy.reply_count === "number" ? legacy.reply_count : 0,
+    createdAt: typeof legacy.created_at === "string" ? legacy.created_at : undefined,
+    inReplyTo: typeof legacy.in_reply_to_status_id_str === "string" ? legacy.in_reply_to_status_id_str : undefined,
+    url: getTweetUrl(tweet, fallbackUrl),
+    media: getTweetMedia(tweet),
+    quotedTweet: getQuotedTweet(tweet, fallbackUrl),
+  };
+}
+
+export function normalizeTitle(text: string, fallback: string): string {
+  const firstLine = text.split("\n")[0]?.trim();
+  if (!firstLine) {
+    return fallback;
+  }
+  return firstLine.slice(0, 120);
+}
+
+export function formatTweetAuthor(tweet: XTweet): string | undefined {
+  if (tweet.author && tweet.authorName) {
+    return `${tweet.authorName} (@${tweet.author})`;
+  }
+  if (tweet.author) {
+    return `@${tweet.author}`;
+  }
+  return tweet.authorName;
+}
+
+export function getTweetAuthorMetadata(tweet: XTweet): Record<string, unknown> {
+  return {
+    authorName: tweet.authorName,
+    authorUsername: tweet.author,
+    authorUrl: tweet.author ? `https://x.com/${tweet.author}` : undefined,
+  };
+}
+
+export function formatMediaList(media: XMedia[]): string[] {
+  return media.map((item) => {
+    if (item.type === "photo") {
+      return `photo: ${item.url}`;
+    }
+    return `${item.type}: ${item.url}`;
+  });
+}
+
+export function filterXGraphQlEntries(entries: NetworkEntry[]): NetworkEntry[] {
+  return entries.filter((entry) => entry.url.includes("/graphql/"));
+}

packages/baoyu-fetch/src/adapters/x/single.ts

@@ -0,0 +1,87 @@
+import type { ExtractedDocument, ContentBlock } from "../../extract/document";
+import { findTweetNode, formatMediaList, formatTweetAuthor, getTweetAuthorMetadata, normalizeTitle, toXTweet } from "./shared";
+
+export function extractSingleTweetDocumentFromPayload(
+  payload: unknown,
+  statusId: string,
+  pageUrl: string,
+): ExtractedDocument | null {
+  const tweet = findTweetNode(payload, statusId);
+  if (!tweet) {
+    return null;
+  }
+
+  const xTweet = toXTweet(tweet, pageUrl);
+  const content: ContentBlock[] = [];
+
+  if (xTweet.text) {
+    content.push({ type: "paragraph", text: xTweet.text });
+  }
+
+  for (const mediaLine of formatMediaList(xTweet.media)) {
+    if (mediaLine.startsWith("photo: ")) {
+      content.push({
+        type: "image",
+        url: mediaLine.slice("photo: ".length),
+      });
+    } else {
+      content.push({
+        type: "list",
+        ordered: false,
+        items: [mediaLine],
+      });
+    }
+  }
+
+  if (xTweet.quotedTweet) {
+    const quotedLines: string[] = [];
+    const quotedAuthor =
+      xTweet.quotedTweet.author && xTweet.quotedTweet.authorName
+        ? `${xTweet.quotedTweet.authorName} (@${xTweet.quotedTweet.author})`
+        : xTweet.quotedTweet.author
+          ? `@${xTweet.quotedTweet.author}`
+          : xTweet.quotedTweet.authorName;
+
+    if (quotedAuthor) {
+      quotedLines.push(quotedAuthor);
+    }
+    if (xTweet.quotedTweet.text) {
+      quotedLines.push(xTweet.quotedTweet.text);
+    }
+    quotedLines.push(...formatMediaList(xTweet.quotedTweet.media));
+
+    if (quotedLines.length > 0) {
+      content.push({ type: "heading", depth: 2, text: "Quoted Tweet" });
+      content.push({ type: "quote", text: quotedLines.join("\n\n") });
+    }
+  }
+
+  return {
+    url: pageUrl,
+    canonicalUrl: xTweet.url,
+    title: normalizeTitle(
+      xTweet.author ? `@${xTweet.author}: ${xTweet.text}` : xTweet.text,
+      "Tweet",
+    ),
+    author: formatTweetAuthor(xTweet),
+    siteName: "X",
+    publishedAt: xTweet.createdAt,
+    summary: xTweet.text.slice(0, 200) || undefined,
+    adapter: "x",
+    metadata: {
+      kind: "x/post",
+      tweetId: xTweet.id,
+      ...getTweetAuthorMetadata(xTweet),
+      conversationId:
+        typeof tweet.legacy === "object" &&
+        tweet.legacy !== null &&
+        typeof (tweet.legacy as Record<string, unknown>).conversation_id_str === "string"
+          ? (tweet.legacy as Record<string, unknown>).conversation_id_str
+          : undefined,
+      favoriteCount: xTweet.likes,
+      replyCount: xTweet.replies,
+      retweetCount: xTweet.retweets,
+    },
+    content,
+  };
+}

packages/baoyu-fetch/src/adapters/x/thread-loader.ts

@@ -0,0 +1,286 @@
+import type { AdapterContext } from "../types";
+import { extractThreadTweetsFromPayloads } from "./thread";
+import { collectXJsonPayloads, getRelevantXThreadEntries, prefetchRelevantXThreadBodies } from "./payloads";
+
+interface ClickTextResult {
+  clicked: boolean;
+  text?: string;
+}
+
+interface ScrollStepResult {
+  moved: boolean;
+  atTop: boolean;
+  atBottom: boolean;
+}
+
+interface ThreadProgress {
+  tweetCount: number;
+  firstTweetId?: string;
+  lastTweetId?: string;
+  requestCount: number;
+  tweetDetailCount: number;
+}
+
+interface TopProbeState {
+  requestCount: number;
+  tweetDetailCount: number;
+  scrollHeight: number;
+}
+
+function sleep(ms: number): Promise<void> {
+  return new Promise((resolve) => setTimeout(resolve, ms));
+}
+
+async function waitForXNetworkSettle(context: AdapterContext, reason: string): Promise<void> {
+  try {
+    await context.network.waitForIdle({
+      idleMs: 650,
+      timeoutMs: Math.min(context.timeoutMs, 5_000),
+    });
+  } catch {
+    context.log.debug(`Network idle timed out after ${reason}.`);
+  }
+}
+
+async function captureTopProbeState(context: AdapterContext): Promise<TopProbeState> {
+  const entries = getRelevantXThreadEntries(context);
+  const scrollHeight = await context.browser.evaluate<number>(`
+    (() => {
+      const scrollRoot = document.scrollingElement ?? document.documentElement ?? document.body;
+      return scrollRoot.scrollHeight;
+    })()
+  `);
+
+  return {
+    requestCount: entries.length,
+    tweetDetailCount: entries.filter((entry) => entry.url.includes("TweetDetail")).length,
+    scrollHeight,
+  };
+}
+
+async function waitForTopProbe(context: AdapterContext): Promise<boolean> {
+  const initial = await captureTopProbeState(context);
+  const deadline = Date.now() + 1_200;
+
+  while (Date.now() < deadline) {
+    try {
+      await context.network.waitForIdle({
+        idleMs: 250,
+        timeoutMs: 350,
+      });
+    } catch {
+      // Keep polling until the shorter top-probe budget expires.
+    }
+
+    await prefetchRelevantXThreadBodies(context);
+    const next = await captureTopProbeState(context);
+    if (
+      next.requestCount > initial.requestCount ||
+      next.tweetDetailCount > initial.tweetDetailCount ||
+      next.scrollHeight > initial.scrollHeight + 4
+    ) {
+      context.log.debug("Observed additional X thread activity while probing the page top.");
+      return true;
+    }
+
+    await sleep(120);
+  }
+
+  return false;
+}
+
+async function scrollThreadToTop(context: AdapterContext): Promise<void> {
+  let settledTopChecks = 0;
+
+  while (settledTopChecks < 2) {
+    const scroll = await context.browser.evaluate<ScrollStepResult>(`
+      (() => {
+        const scrollRoot = document.scrollingElement ?? document.documentElement ?? document.body;
+        const before = window.scrollY;
+        window.scrollTo({ top: 0, left: 0, behavior: "instant" });
+        const after = window.scrollY;
+        return {
+          moved: after !== before,
+          atTop: after <= 4,
+          atBottom: window.innerHeight + after >= scrollRoot.scrollHeight - 4,
+        };
+      })()
+    `);
+    await sleep(140);
+    await waitForXNetworkSettle(context, "scrolling X thread to top");
+    await prefetchRelevantXThreadBodies(context);
+
+    if (scroll.moved) {
+      settledTopChecks = 0;
+      continue;
+    }
+
+    const observedTopActivity = await waitForTopProbe(context);
+    if (observedTopActivity) {
+      settledTopChecks = 0;
+      continue;
+    }
+
+    settledTopChecks += 1;
+  }
+}
+
+async function clickVisibleShowReplies(context: AdapterContext): Promise<ClickTextResult> {
+  return context.browser.evaluate<ClickTextResult>(`
+    (() => {
+      const normalize = (value) => value.replace(/\\s+/g, " ").trim();
+      const matches = [
+        /^Show replies$/i,
+        /^Show more replies$/i,
+        /^Show additional replies$/i,
+        /^显示回复$/,
+        /^展开回复$/,
+      ];
+      const isVisible = (element) => {
+        if (!(element instanceof HTMLElement)) {
+          return false;
+        }
+        const rect = element.getBoundingClientRect();
+        const style = window.getComputedStyle(element);
+        return (
+          rect.width > 0 &&
+          rect.height > 0 &&
+          style.visibility !== "hidden" &&
+          style.display !== "none"
+        );
+      };
+
+      const selectors = [
+        "a",
+        "button",
+        '[role="button"]',
+        '[role="link"]',
+      ];
+
+      for (const element of document.querySelectorAll(selectors.join(","))) {
+        if (!isVisible(element)) {
+          continue;
+        }
+        const text = normalize(element.textContent ?? "");
+        if (!text || !matches.some((pattern) => pattern.test(text))) {
+          continue;
+        }
+        element.scrollIntoView({ block: "center", inline: "nearest" });
+        if (element instanceof HTMLElement) {
+          element.click();
+          return { clicked: true, text };
+        }
+      }
+
+      return { clicked: false };
+    })()
+  `);
+}
+
+async function expandVisibleShowReplies(context: AdapterContext): Promise<number> {
+  let clickCount = 0;
+
+  while (clickCount < 8) {
+    const result = await clickVisibleShowReplies(context).catch<ClickTextResult>(() => ({ clicked: false }));
+    if (!result.clicked) {
+      break;
+    }
+
+    clickCount += 1;
+    context.log.debug(`Expanded X thread replies via "${result.text ?? "Show replies"}".`);
+    await sleep(250);
+    await waitForXNetworkSettle(context, "expanding Show replies");
+    await prefetchRelevantXThreadBodies(context);
+  }
+
+  return clickCount;
+}
+
+async function scrollThreadBy(context: AdapterContext, stepPx: number): Promise<ScrollStepResult> {
+  const result = await context.browser.evaluate<ScrollStepResult>(`
+    (() => {
+      const scrollRoot = document.scrollingElement ?? document.documentElement ?? document.body;
+      const before = window.scrollY;
+      window.scrollBy({ top: ${stepPx}, left: 0, behavior: "instant" });
+      const after = window.scrollY;
+      return {
+        moved: after !== before,
+        atTop: after <= 4,
+        atBottom: window.innerHeight + after >= scrollRoot.scrollHeight - 4,
+      };
+    })()
+  `);
+
+  await sleep(140);
+  await waitForXNetworkSettle(context, "scrolling X thread");
+  await prefetchRelevantXThreadBodies(context);
+  return result;
+}
+
+async function captureThreadProgress(context: AdapterContext, statusId: string): Promise<ThreadProgress> {
+  const entries = getRelevantXThreadEntries(context);
+  const payloads = await collectXJsonPayloads(context);
+  const tweets = extractThreadTweetsFromPayloads(payloads, statusId, context.input.url.toString());
+  return {
+    tweetCount: tweets.length,
+    firstTweetId: tweets[0]?.id,
+    lastTweetId: tweets[tweets.length - 1]?.id,
+    requestCount: entries.length,
+    tweetDetailCount: entries.filter((entry) => entry.url.includes("TweetDetail")).length,
+  };
+}
+
+export async function loadFullXThread(context: AdapterContext, statusId: string): Promise<void> {
+  await scrollThreadToTop(context);
+
+  let progress = await captureThreadProgress(context, statusId);
+  let stagnantRounds = 0;
+  let roundsWithoutMovement = 0;
+  let distanceWithoutThreadActivityPx = 0;
+
+  for (let round = 0; ; round += 1) {
+    const stepPx = round < 12 ? 1_200 : 1_600;
+    let expandedCount = await expandVisibleShowReplies(context);
+    const scroll = await scrollThreadBy(context, stepPx);
+    expandedCount += await expandVisibleShowReplies(context);
+    const nextProgress = await captureThreadProgress(context, statusId);
+    const grew =
+      nextProgress.tweetCount > progress.tweetCount ||
+      nextProgress.firstTweetId !== progress.firstTweetId ||
+      nextProgress.lastTweetId !== progress.lastTweetId ||
+      nextProgress.requestCount > progress.requestCount ||
+      nextProgress.tweetDetailCount > progress.tweetDetailCount;
+
+    if (grew) {
+      context.log.debug(
+        `X thread progress: ${nextProgress.tweetCount} tweets (${nextProgress.firstTweetId ?? "unknown"} -> ${nextProgress.lastTweetId ?? "unknown"}), ${nextProgress.requestCount} requests, ${nextProgress.tweetDetailCount} TweetDetail.`,
+      );
+      stagnantRounds = 0;
+      distanceWithoutThreadActivityPx = 0;
+    } else if (expandedCount > 0) {
+      stagnantRounds = 0;
+      distanceWithoutThreadActivityPx = 0;
+    } else {
+      stagnantRounds += 1;
+      distanceWithoutThreadActivityPx += stepPx;
+    }
+
+    roundsWithoutMovement = scroll.moved ? 0 : roundsWithoutMovement + 1;
+    progress = nextProgress;
+
+    if (scroll.atBottom && stagnantRounds >= 6) {
+      context.log.debug("Stopping X thread scroll after reaching page bottom with no further thread progress.");
+      break;
+    }
+
+    if (roundsWithoutMovement >= 2 && stagnantRounds >= 4) {
+      context.log.debug("Stopping X thread scroll after repeated downward scrolls no longer move the page.");
+      break;
+    }
+
+    if (distanceWithoutThreadActivityPx >= 24_000 && stagnantRounds >= 12) {
+      context.log.debug("Stopping X thread scroll after a long stretch with no thread-related progress.");
+      break;
+    }
+  }
+}

packages/baoyu-fetch/src/adapters/x/thread.ts

@@ -0,0 +1,316 @@
+import type { ExtractedDocument } from "../../extract/document";
+import {
+  formatMediaList,
+  formatTweetAuthor,
+  getLegacy,
+  getTweetAuthorMetadata,
+  isRecord,
+  normalizeTitle,
+  toXTweet,
+  unwrapTweetResult,
+} from "./shared";
+import type { JsonObject, XQuotedTweet, XTweet } from "./types";
+
+interface ParsedThreadTweet extends XTweet {
+  userId?: string;
+  conversationId?: string;
+  inReplyToUserId?: string;
+  sortTimestamp: number;
+}
+
+function compareTweetIds(left: string, right: string): number {
+  try {
+    const leftId = BigInt(left);
+    const rightId = BigInt(right);
+    if (leftId === rightId) {
+      return 0;
+    }
+    return leftId < rightId ? -1 : 1;
+  } catch {
+    return left.localeCompare(right);
+  }
+}
+
+function toTimestamp(value: string | undefined): number {
+  if (!value) {
+    return 0;
+  }
+  const parsed = Date.parse(value);
+  return Number.isNaN(parsed) ? 0 : parsed;
+}
+
+function scoreParsedTweet(tweet: ParsedThreadTweet): number {
+  return (
+    (tweet.text ? 4 : 0) +
+    (tweet.author ? 2 : 0) +
+    (tweet.authorName ? 2 : 0) +
+    (tweet.media.length > 0 ? 1 : 0)
+  );
+}
+
+function toParsedThreadTweet(tweet: JsonObject, pageUrl: string): ParsedThreadTweet {
+  const legacy = getLegacy(tweet);
+  const xTweet = toXTweet(tweet, pageUrl);
+
+  return {
+    ...xTweet,
+    userId: typeof legacy.user_id_str === "string" ? legacy.user_id_str : undefined,
+    conversationId: typeof legacy.conversation_id_str === "string" ? legacy.conversation_id_str : undefined,
+    inReplyToUserId: typeof legacy.in_reply_to_user_id_str === "string" ? legacy.in_reply_to_user_id_str : undefined,
+    sortTimestamp: toTimestamp(xTweet.createdAt),
+  };
+}
+
+function collectTweetFromItemContent(
+  itemContent: unknown,
+  pageUrl: string,
+  tweets: Map<string, ParsedThreadTweet>,
+): void {
+  if (!isRecord(itemContent)) {
+    return;
+  }
+
+  const tweet = unwrapTweetResult(
+    isRecord(itemContent.tweet_results) ? itemContent.tweet_results.result : null,
+  );
+  if (!tweet || typeof tweet.rest_id !== "string") {
+    return;
+  }
+
+  const parsed = toParsedThreadTweet(tweet, pageUrl);
+  const existing = tweets.get(parsed.id);
+  if (!existing || scoreParsedTweet(parsed) >= scoreParsedTweet(existing)) {
+    tweets.set(parsed.id, parsed);
+  }
+}
+
+function collectTweetsFromItems(
+  items: unknown,
+  pageUrl: string,
+  tweets: Map<string, ParsedThreadTweet>,
+): void {
+  if (!Array.isArray(items)) {
+    return;
+  }
+
+  for (const item of items) {
+    if (!isRecord(item)) {
+      continue;
+    }
+
+    if (isRecord(item.item) && isRecord(item.item.itemContent)) {
+      collectTweetFromItemContent(item.item.itemContent, pageUrl, tweets);
+      continue;
+    }
+
+    if (isRecord(item.itemContent)) {
+      collectTweetFromItemContent(item.itemContent, pageUrl, tweets);
+    }
+  }
+}
+
+function getInstructions(payload: unknown): unknown[] {
+  if (!isRecord(payload) || !isRecord(payload.data)) {
+    return [];
+  }
+
+  const { data } = payload;
+  return (
+    (isRecord(data.threaded_conversation_with_injections_v2) &&
+    Array.isArray(data.threaded_conversation_with_injections_v2.instructions)
+      ? data.threaded_conversation_with_injections_v2.instructions
+      : undefined) ??
+    (isRecord(data.threaded_conversation_with_injections) &&
+    Array.isArray(data.threaded_conversation_with_injections.instructions)
+      ? data.threaded_conversation_with_injections.instructions
+      : undefined) ??
+    (isRecord(data.tweetResult) &&
+    isRecord(data.tweetResult.result) &&
+    isRecord(data.tweetResult.result.timeline) &&
+    Array.isArray(data.tweetResult.result.timeline.instructions)
+      ? data.tweetResult.result.timeline.instructions
+      : [])
+  );
+}
+
+function parseTweetDetailPayload(payload: unknown, pageUrl: string): ParsedThreadTweet[] {
+  const tweets = new Map<string, ParsedThreadTweet>();
+
+  const instructions = getInstructions(payload);
+  for (const instruction of instructions) {
+    if (!isRecord(instruction)) {
+      continue;
+    }
+
+    collectTweetsFromItems(instruction.moduleItems, pageUrl, tweets);
+
+    if (!Array.isArray(instruction.entries)) {
+      continue;
+    }
+
+    for (const entry of instruction.entries) {
+      if (!isRecord(entry)) {
+        continue;
+      }
+
+      const content = isRecord(entry.content) ? entry.content : {};
+      collectTweetFromItemContent(content.itemContent, pageUrl, tweets);
+      collectTweetsFromItems(content.items, pageUrl, tweets);
+    }
+  }
+
+  return Array.from(tweets.values());
+}
+
+function buildContinuousThread(tweets: ParsedThreadTweet[], statusId: string): ParsedThreadTweet[] {
+  const byId = new Map<string, ParsedThreadTweet>();
+  for (const tweet of tweets) {
+    const existing = byId.get(tweet.id);
+    if (!existing || scoreParsedTweet(tweet) >= scoreParsedTweet(existing)) {
+      byId.set(tweet.id, tweet);
+    }
+  }
+
+  const rootTweet = byId.get(statusId);
+  if (!rootTweet?.userId || !rootTweet.conversationId) {
+    return [];
+  }
+
+  const candidates = Array.from(byId.values()).filter(
+    (tweet) =>
+      tweet.id === statusId ||
+      (tweet.userId === rootTweet.userId && tweet.conversationId === rootTweet.conversationId),
+  );
+
+  const repliesByParent = new Map<string, ParsedThreadTweet[]>();
+  for (const tweet of candidates) {
+    if (!tweet.inReplyTo || tweet.id === statusId) {
+      continue;
+    }
+    const bucket = repliesByParent.get(tweet.inReplyTo) ?? [];
+    bucket.push(tweet);
+    bucket.sort((left, right) => {
+      if (left.sortTimestamp !== right.sortTimestamp) {
+        return left.sortTimestamp - right.sortTimestamp;
+      }
+      return compareTweetIds(left.id, right.id);
+    });
+    repliesByParent.set(tweet.inReplyTo, bucket);
+  }
+
+  const ancestorPath: ParsedThreadTweet[] = [rootTweet];
+  const ancestorSeen = new Set<string>([rootTweet.id]);
+  let currentAncestor = rootTweet;
+
+  while (currentAncestor.inReplyTo) {
+    const parent = byId.get(currentAncestor.inReplyTo);
+    if (!parent || ancestorSeen.has(parent.id)) {
+      break;
+    }
+    ancestorPath.unshift(parent);
+    ancestorSeen.add(parent.id);
+    currentAncestor = parent;
+  }
+
+  const chain = ancestorPath.slice();
+  const seen = new Set<string>(chain.map((tweet) => tweet.id));
+  let currentId = rootTweet.id;
+
+  while (true) {
+    const next = (repliesByParent.get(currentId) ?? []).find((tweet) => !seen.has(tweet.id));
+    if (!next) {
+      break;
+    }
+    chain.push(next);
+    seen.add(next.id);
+    currentId = next.id;
+  }
+
+  return chain;
+}
+
+export function extractThreadTweetsFromPayloads(
+  payloads: unknown[],
+  statusId: string,
+  pageUrl: string,
+): XTweet[] {
+  const parsedTweets: ParsedThreadTweet[] = [];
+
+  for (const payload of payloads) {
+    parsedTweets.push(...parseTweetDetailPayload(payload, pageUrl));
+  }
+
+  return buildContinuousThread(parsedTweets, statusId).map(({ sortTimestamp: _sortTimestamp, ...tweet }) => tweet);
+}
+
+function buildQuotedTweetMarkdown(quotedTweet: XQuotedTweet): string {
+  const author = quotedTweet.author ? `@${quotedTweet.author}` : "Unknown";
+  const name = quotedTweet.authorName ? `${quotedTweet.authorName} ` : "";
+  const lines: string[] = [`Quoted Tweet${quotedTweet.author || quotedTweet.authorName ? `: ${name}${author}`.trim() : ""}`];
+
+  if (quotedTweet.text) {
+    lines.push(...quotedTweet.text.split("\n"));
+  }
+
+  for (const mediaLine of formatMediaList(quotedTweet.media)) {
+    lines.push(mediaLine);
+  }
+
+  return lines.map((line) => (line ? `> ${line}` : ">")).join("\n");
+}
+
+function buildThreadMarkdown(tweets: XTweet[]): string {
+  return tweets
+    .map((tweet, index) => {
+      const lines: string[] = [];
+      const author = tweet.author ? `@${tweet.author}` : "Unknown";
+      const name = tweet.authorName ? `${tweet.authorName} ` : "";
+      lines.push(`## ${index + 1}. ${name}${author}`.trim());
+      if (tweet.createdAt) {
+        lines.push(`_Published: ${tweet.createdAt}_`);
+      }
+      lines.push(tweet.text || "(No text)");
+      const mediaLines = formatMediaList(tweet.media);
+      if (mediaLines.length > 0) {
+        lines.push(mediaLines.map((line) => `- ${line}`).join("\n"));
+      }
+      if (tweet.quotedTweet) {
+        lines.push(buildQuotedTweetMarkdown(tweet.quotedTweet));
+      }
+      return lines.join("\n\n");
+    })
+    .join("\n\n");
+}
+
+export function extractThreadDocumentFromPayloads(
+  payloads: unknown[],
+  statusId: string,
+  pageUrl: string,
+): ExtractedDocument | null {
+  const tweets = extractThreadTweetsFromPayloads(payloads, statusId, pageUrl);
+  if (tweets.length <= 1) {
+    return null;
+  }
+
+  const rootTweet = tweets[0];
+  const rootAuthor = formatTweetAuthor(rootTweet);
+
+  return {
+    url: pageUrl,
+    canonicalUrl: rootTweet.url,
+    title: normalizeTitle(rootTweet.text, "X Thread"),
+    author: rootAuthor,
+    siteName: "X",
+    publishedAt: rootTweet.createdAt,
+    summary: rootTweet.text.slice(0, 200) || undefined,
+    adapter: "x",
+    metadata: {
+      kind: "x/thread",
+      tweetId: rootTweet.id,
+      tweetCount: tweets.length,
+      lastTweetId: tweets[tweets.length - 1]?.id,
+      ...getTweetAuthorMetadata(rootTweet),
+    },
+    content: [{ type: "markdown", markdown: buildThreadMarkdown(tweets) }],
+  };
+}

packages/baoyu-fetch/src/adapters/x/types.ts

@@ -0,0 +1,36 @@
+export type JsonObject = Record<string, unknown>;
+
+export interface XUser {
+  name?: string;
+  screenName?: string;
+}
+
+export interface XMedia {
+  type: string;
+  url: string;
+  alt?: string;
+}
+
+export interface XQuotedTweet {
+  id: string;
+  author?: string;
+  authorName?: string;
+  text: string;
+  url: string;
+  media: XMedia[];
+}
+
+export interface XTweet {
+  id: string;
+  author?: string;
+  authorName?: string;
+  text: string;
+  likes: number;
+  retweets: number;
+  replies: number;
+  createdAt?: string;
+  inReplyTo?: string;
+  url: string;
+  media: XMedia[];
+  quotedTweet?: XQuotedTweet;
+}

packages/baoyu-fetch/src/adapters/youtube/index.ts

@@ -0,0 +1,33 @@
+import type { Adapter } from "../types";
+import { collectMediaFromDocument } from "../../media/markdown-media";
+import { extractYouTubeTranscriptDocument } from "./transcript";
+import { isYouTubeHost, parseYouTubeVideoId } from "./utils";
+
+export const youtubeAdapter: Adapter = {
+  name: "youtube",
+  match(input) {
+    return isYouTubeHost(input.url.hostname);
+  },
+  async process(context) {
+    const videoId = parseYouTubeVideoId(context.input.url);
+    if (!videoId) {
+      return {
+        status: "no_document",
+      };
+    }
+
+    context.log.info(`Loading ${context.input.url.toString()} with youtube adapter`);
+    const document = await extractYouTubeTranscriptDocument(context, videoId);
+    if (!document) {
+      return {
+        status: "no_document",
+      };
+    }
+
+    return {
+      status: "ok",
+      document,
+      media: collectMediaFromDocument(document),
+    };
+  },
+};

packages/baoyu-fetch/src/adapters/youtube/transcript.ts

@@ -0,0 +1,392 @@
+import type { ExtractedDocument } from "../../extract/document";
+import { detectInteractionGate } from "../../browser/interaction-gates";
+import {
+  buildYouTubeThumbnailCandidates,
+  parseYouTubeDescriptionChapters,
+  renderYouTubeTranscriptMarkdown,
+  type YouTubeChapter,
+  type YouTubeTranscriptSegment,
+} from "./utils";
+
+interface CaptionInfo {
+  captionUrl: string;
+  language: string;
+  kind: string;
+  available: string[];
+  title?: string;
+  author?: string;
+  authorUrl?: string;
+  channelId?: string;
+  description?: string;
+  publishedAt?: string;
+  viewCount?: number;
+  durationSeconds?: number;
+  keywords: string[];
+  category?: string;
+  isLiveContent?: boolean;
+  coverImages: string[];
+}
+
+function normalizeUrl(url: string | undefined): string | undefined {
+  if (!url) {
+    return undefined;
+  }
+
+  try {
+    const parsed = new URL(url);
+    if (parsed.protocol === "http:") {
+      parsed.protocol = "https:";
+    }
+    return parsed.toString();
+  } catch {
+    return url;
+  }
+}
+
+function buildSummary(description: string | undefined, segments: YouTubeTranscriptSegment[]): string | undefined {
+  const descriptionSummary = description
+    ?.replace(/\r\n/g, "\n")
+    .split("\n")
+    .map((line) => line.trim())
+    .find((line) => line && !/^https?:\/\//i.test(line));
+
+  if (descriptionSummary) {
+    return descriptionSummary.slice(0, 240);
+  }
+
+  const transcriptSummary = segments
+    .slice(0, 8)
+    .map((segment) => segment.text)
+    .join(" ")
+    .slice(0, 240)
+    .trim();
+
+  return transcriptSummary || undefined;
+}
+
+async function canFetchThumbnail(url: string): Promise<boolean> {
+  try {
+    const response = await fetch(url, { method: "HEAD", redirect: "follow" });
+    if (response.ok) {
+      return true;
+    }
+
+    if (response.status === 405) {
+      const fallbackResponse = await fetch(url, {
+        method: "GET",
+        headers: { Range: "bytes=0-0" },
+        redirect: "follow",
+      });
+      return fallbackResponse.ok;
+    }
+  } catch {
+    return false;
+  }
+
+  return false;
+}
+
+async function resolveBestCoverImage(videoId: string, coverImages: string[]): Promise<string | undefined> {
+  const candidates = buildYouTubeThumbnailCandidates(videoId, coverImages);
+
+  for (const candidate of candidates) {
+    if (await canFetchThumbnail(candidate)) {
+      return candidate;
+    }
+  }
+
+  return candidates[0];
+}
+
+export async function extractYouTubeTranscriptDocument(
+  context: Parameters<import("../types").Adapter["process"]>[0],
+  videoId: string,
+): Promise<ExtractedDocument | null> {
+  const videoUrl = `https://www.youtube.com/watch?v=${videoId}`;
+  await context.browser.goto(videoUrl, context.timeoutMs);
+
+  const interaction = await detectInteractionGate(context.browser);
+  if (interaction) {
+    context.log.debug(`Interaction gate detected on YouTube: ${interaction.provider}`);
+    return null;
+  }
+
+  try {
+    await context.network.waitForIdle({
+      idleMs: 1_000,
+      timeoutMs: Math.min(context.timeoutMs, 8_000),
+    });
+  } catch {
+    context.log.debug("Network idle timed out on YouTube load.");
+  }
+
+  const captionInfo = await context.browser.evaluate<CaptionInfo | { error: string }>(`
+    (async () => {
+      function readText(value) {
+        if (!value) return undefined;
+        if (typeof value === 'string') {
+          const text = value.trim();
+          return text || undefined;
+        }
+        if (typeof value.simpleText === 'string') {
+          const text = value.simpleText.trim();
+          return text || undefined;
+        }
+        if (Array.isArray(value.runs)) {
+          const text = value.runs
+            .map((run) => typeof run?.text === 'string' ? run.text : '')
+            .join('')
+            .trim();
+          return text || undefined;
+        }
+        return undefined;
+      }
+
+      function parsePositiveInteger(value) {
+        if (typeof value === 'number' && Number.isFinite(value) && value >= 0) {
+          return Math.floor(value);
+        }
+        if (typeof value !== 'string') {
+          return undefined;
+        }
+        const normalized = value.replace(/[^\\d]/g, '');
+        if (!normalized) {
+          return undefined;
+        }
+        const parsed = Number.parseInt(normalized, 10);
+        return Number.isFinite(parsed) ? parsed : undefined;
+      }
+
+      const apiKey = window.ytcfg?.data_?.INNERTUBE_API_KEY;
+      const playerResponse = window.ytInitialPlayerResponse;
+      const videoDetails = playerResponse?.videoDetails || {};
+      const microformat = playerResponse?.microformat?.playerMicroformatRenderer || {};
+      const title =
+        videoDetails.title ||
+        readText(microformat.title) ||
+        document.title.replace(/ - YouTube$/, '').trim();
+      const author =
+        videoDetails.author ||
+        microformat.ownerChannelName ||
+        document.querySelector('link[itemprop="name"]')?.getAttribute('content') ||
+        undefined;
+      const authorUrl =
+        microformat.ownerProfileUrl ||
+        (typeof videoDetails.channelId === 'string' && videoDetails.channelId
+          ? 'https://www.youtube.com/channel/' + videoDetails.channelId
+          : undefined);
+      const description =
+        readText(microformat.description) ||
+        (typeof videoDetails.shortDescription === 'string' ? videoDetails.shortDescription.trim() : undefined);
+      const keywords = Array.isArray(videoDetails.keywords)
+        ? videoDetails.keywords.filter((keyword) => typeof keyword === 'string' && keyword.trim())
+        : [];
+      const thumbnails = [
+        ...(Array.isArray(videoDetails.thumbnail?.thumbnails) ? videoDetails.thumbnail.thumbnails : []),
+        ...(Array.isArray(microformat.thumbnail?.thumbnails) ? microformat.thumbnail.thumbnails : []),
+      ]
+        .filter((thumbnail) => typeof thumbnail?.url === 'string' && thumbnail.url)
+        .sort((left, right) => ((right?.width || 0) * (right?.height || 0)) - ((left?.width || 0) * (left?.height || 0)))
+        .map((thumbnail) => thumbnail.url);
+
+      if (!apiKey) {
+        return { error: 'INNERTUBE_API_KEY not found on page' };
+      }
+
+      const response = await fetch('/youtubei/v1/player?key=' + apiKey + '&prettyPrint=false', {
+        method: 'POST',
+        credentials: 'include',
+        headers: { 'Content-Type': 'application/json' },
+        body: JSON.stringify({
+          context: { client: { clientName: 'ANDROID', clientVersion: '20.10.38' } },
+          videoId: ${JSON.stringify(videoId)}
+        })
+      });
+
+      if (!response.ok) {
+        return { error: 'InnerTube player API returned HTTP ' + response.status };
+      }
+
+      const data = await response.json();
+      const renderer = data.captions?.playerCaptionsTracklistRenderer;
+      if (!renderer?.captionTracks?.length) {
+        return { error: 'No captions available for this video' };
+      }
+
+      const tracks = renderer.captionTracks;
+      const track = tracks.find((item) => item.kind !== 'asr') || tracks[0];
+
+      return {
+        captionUrl: track.baseUrl,
+        language: track.languageCode,
+        kind: track.kind || 'manual',
+        available: tracks.map((item) => {
+          const languageLabel = readText(item.name) || item.languageCode;
+          return item.kind === 'asr'
+            ? languageLabel + ' [' + item.languageCode + ', auto]'
+            : languageLabel + ' [' + item.languageCode + ']';
+        }),
+        title,
+        author,
+        authorUrl,
+        channelId: typeof videoDetails.channelId === 'string' ? videoDetails.channelId : undefined,
+        description,
+        publishedAt:
+          (typeof microformat.publishDate === 'string' && microformat.publishDate) ||
+          (typeof microformat.uploadDate === 'string' && microformat.uploadDate) ||
+          document.querySelector('meta[itemprop="datePublished"]')?.getAttribute('content') ||
+          undefined,
+        viewCount: parsePositiveInteger(videoDetails.viewCount) ?? parsePositiveInteger(microformat.viewCount),
+        durationSeconds: parsePositiveInteger(videoDetails.lengthSeconds),
+        keywords,
+        category: typeof microformat.category === 'string' ? microformat.category : undefined,
+        isLiveContent: Boolean(videoDetails.isLiveContent || microformat.isLiveContent),
+        coverImages: thumbnails,
+      };
+    })()
+  `);
+
+  if ("error" in captionInfo) {
+    context.log.debug(`YouTube transcript unavailable: ${captionInfo.error}`);
+    return null;
+  }
+
+  const segments = await context.browser.evaluate<YouTubeTranscriptSegment[] | { error: string }>(`
+    (async () => {
+      const response = await fetch(${JSON.stringify(captionInfo.captionUrl)});
+      const xml = await response.text();
+      if (!xml) {
+        return { error: 'Caption XML is empty' };
+      }
+
+      function getAttr(tag, name) {
+        const needle = name + '="';
+        const index = tag.indexOf(needle);
+        if (index === -1) return '';
+        const valueStart = index + needle.length;
+        const valueEnd = tag.indexOf('"', valueStart);
+        if (valueEnd === -1) return '';
+        return tag.substring(valueStart, valueEnd);
+      }
+
+      function decodeEntities(value) {
+        return value
+          .replaceAll('&amp;', '&')
+          .replaceAll('&lt;', '<')
+          .replaceAll('&gt;', '>')
+          .replaceAll('&quot;', '"')
+          .replaceAll('&#39;', "'");
+      }
+
+      const marker = xml.includes('<p t="') ? '<p ' : '<text ';
+      const endMarker = marker === '<p ' ? '</p>' : '</text>';
+      const results = [];
+      let position = 0;
+
+      while (true) {
+        const tagStart = xml.indexOf(marker, position);
+        if (tagStart === -1) break;
+        let contentStart = xml.indexOf('>', tagStart);
+        if (contentStart === -1) break;
+        contentStart += 1;
+        const tagEnd = xml.indexOf(endMarker, contentStart);
+        if (tagEnd === -1) break;
+
+        const attrString = xml.substring(tagStart + marker.length, contentStart - 1);
+        const content = xml.substring(contentStart, tagEnd);
+        const start = marker === '<p '
+          ? (parseFloat(getAttr(attrString, 't')) || 0) / 1000
+          : (parseFloat(getAttr(attrString, 'start')) || 0);
+        const duration = marker === '<p '
+          ? (parseFloat(getAttr(attrString, 'd')) || 0) / 1000
+          : (parseFloat(getAttr(attrString, 'dur')) || 0);
+        const text = decodeEntities(content.replace(/<[^>]+>/g, '')).split('\\n').join(' ').trim();
+        if (text) {
+          results.push({ start, end: start + duration, text });
+        }
+
+        position = tagEnd + endMarker.length;
+      }
+
+      if (results.length === 0) {
+        return { error: 'Parsed 0 transcript segments' };
+      }
+      return results;
+    })()
+  `);
+
+  if (!Array.isArray(segments) || segments.length === 0) {
+    context.log.debug("Parsed no YouTube transcript segments.");
+    return null;
+  }
+
+  const extractedChapters = await context.browser.evaluate<YouTubeChapter[]>(`
+    (() => {
+      const data = window.ytInitialData;
+      const markers = data?.playerOverlays?.playerOverlayRenderer
+        ?.decoratedPlayerBarRenderer?.decoratedPlayerBarRenderer
+        ?.playerBar?.multiMarkersPlayerBarRenderer?.markersMap || [];
+      const results = [];
+
+      for (const marker of markers) {
+        const chapters = marker?.value?.chapters;
+        if (!Array.isArray(chapters)) continue;
+        for (const chapter of chapters) {
+          const renderer = chapter?.chapterRenderer;
+          const title = renderer?.title?.simpleText;
+          const timeRangeStartMillis = renderer?.timeRangeStartMillis;
+          if (title && typeof timeRangeStartMillis === 'number') {
+            results.push({ title, time: Math.floor(timeRangeStartMillis / 1000) });
+          }
+        }
+      }
+
+      return results;
+    })()
+  `).catch(() => []);
+
+  const descriptionChapters = parseYouTubeDescriptionChapters(captionInfo.description);
+  const chapters = extractedChapters.length > 0 ? extractedChapters : descriptionChapters;
+  const markdown = renderYouTubeTranscriptMarkdown({
+    description: captionInfo.description,
+    segments,
+    chapters,
+  });
+
+  if (!markdown) {
+    return null;
+  }
+
+  const pageUrl = await context.browser.getURL();
+  const coverImage = await resolveBestCoverImage(videoId, captionInfo.coverImages);
+  const summary = buildSummary(captionInfo.description, segments);
+
+  return {
+    url: pageUrl,
+    canonicalUrl: pageUrl,
+    title: captionInfo.title || "YouTube Transcript",
+    author: captionInfo.author,
+    publishedAt: captionInfo.publishedAt,
+    siteName: "YouTube",
+    summary,
+    adapter: "youtube",
+    metadata: {
+      kind: "youtube/transcript",
+      videoId,
+      authorUrl: normalizeUrl(captionInfo.authorUrl),
+      channelId: captionInfo.channelId,
+      coverImage,
+      description: captionInfo.description,
+      durationSeconds: captionInfo.durationSeconds,
+      language: captionInfo.language,
+      captionKind: captionInfo.kind,
+      availableLanguages: captionInfo.available,
+      viewCount: captionInfo.viewCount,
+      keywords: captionInfo.keywords,
+      category: captionInfo.category,
+      isLiveContent: captionInfo.isLiveContent,
+      chapterCount: chapters.length,
+    },
+    content: [{ type: "markdown", markdown }],
+  };
+}

packages/baoyu-fetch/src/adapters/youtube/utils.ts

@@ -0,0 +1,253 @@
+export interface YouTubeTranscriptSegment {
+  start: number;
+  end: number;
+  text: string;
+}
+
+export interface YouTubeChapter {
+  title: string;
+  time: number;
+}
+
+interface RenderYouTubeTranscriptMarkdownInput {
+  description?: string;
+  segments: YouTubeTranscriptSegment[];
+  chapters: YouTubeChapter[];
+}
+
+const DESCRIPTION_CHAPTER_RE = /^((?:\d{1,2}:)?\d{1,2}:\d{2})(?:\s+[-|:]\s+|\s+)(.+)$/;
+const YOUTUBE_THUMBNAIL_VARIANTS = [
+  "maxresdefault.jpg",
+  "sddefault.jpg",
+  "hqdefault.jpg",
+  "mqdefault.jpg",
+  "default.jpg",
+];
+
+export function isYouTubeHost(hostname: string): boolean {
+  return [
+    "youtube.com",
+    "www.youtube.com",
+    "m.youtube.com",
+    "youtu.be",
+  ].includes(hostname);
+}
+
+export function parseYouTubeVideoId(url: URL): string | null {
+  if (url.hostname === "youtu.be") {
+    return url.pathname.split("/").filter(Boolean)[0] ?? null;
+  }
+
+  if (url.pathname === "/watch") {
+    return url.searchParams.get("v");
+  }
+
+  const shortsMatch = url.pathname.match(/^\/shorts\/([^/?#]+)/);
+  if (shortsMatch) {
+    return shortsMatch[1];
+  }
+
+  const liveMatch = url.pathname.match(/^\/live\/([^/?#]+)/);
+  if (liveMatch) {
+    return liveMatch[1];
+  }
+
+  return null;
+}
+
+function parseTimestampValue(raw: string): number | null {
+  const parts = raw
+    .split(":")
+    .map((part) => Number.parseInt(part, 10))
+    .filter((part) => Number.isFinite(part));
+
+  if (parts.length < 2 || parts.length > 3) {
+    return null;
+  }
+
+  if (parts.some((part) => part < 0)) {
+    return null;
+  }
+
+  if (parts.length === 2) {
+    const [minutes, seconds] = parts;
+    return minutes * 60 + seconds;
+  }
+
+  const [hours, minutes, seconds] = parts;
+  return hours * 3600 + minutes * 60 + seconds;
+}
+
+export function formatTimestamp(totalSeconds: number): string {
+  const rounded = Math.max(0, Math.floor(totalSeconds));
+  const hours = Math.floor(rounded / 3600);
+  const minutes = Math.floor((rounded % 3600) / 60);
+  const seconds = rounded % 60;
+
+  if (hours > 0) {
+    return `${hours}:${String(minutes).padStart(2, "0")}:${String(seconds).padStart(2, "0")}`;
+  }
+  return `${minutes}:${String(seconds).padStart(2, "0")}`;
+}
+
+export function formatTimestampRange(start: number, end: number): string {
+  const safeStart = Math.max(0, start);
+  const safeEnd = Math.max(safeStart, end);
+  return `[${formatTimestamp(safeStart)} -> ${formatTimestamp(safeEnd)}]`;
+}
+
+export function normalizeYouTubeChapters(chapters: YouTubeChapter[]): YouTubeChapter[] {
+  const seenTimes = new Set<number>();
+
+  return chapters
+    .map((chapter) => ({
+      title: chapter.title.trim(),
+      time: Math.max(0, Math.floor(chapter.time)),
+    }))
+    .filter((chapter) => chapter.title)
+    .sort((left, right) => left.time - right.time)
+    .filter((chapter) => {
+      if (seenTimes.has(chapter.time)) {
+        return false;
+      }
+      seenTimes.add(chapter.time);
+      return true;
+    });
+}
+
+export function parseYouTubeDescriptionChapters(description?: string | null): YouTubeChapter[] {
+  if (!description) {
+    return [];
+  }
+
+  const chapters: YouTubeChapter[] = [];
+  const seen = new Set<string>();
+
+  for (const rawLine of description.replace(/\r\n/g, "\n").split("\n")) {
+    const line = rawLine.trim();
+    if (!line) {
+      continue;
+    }
+
+    const match = line.match(DESCRIPTION_CHAPTER_RE);
+    if (!match) {
+      continue;
+    }
+
+    const time = parseTimestampValue(match[1]);
+    const title = match[2]?.trim();
+    if (time === null || !title) {
+      continue;
+    }
+
+    const key = `${time}:${title.toLowerCase()}`;
+    if (seen.has(key)) {
+      continue;
+    }
+
+    seen.add(key);
+    chapters.push({ title, time });
+  }
+
+  const normalized = normalizeYouTubeChapters(chapters);
+  if (normalized.length >= 2) {
+    return normalized;
+  }
+
+  if (normalized.length === 1 && normalized[0]?.time === 0) {
+    return normalized;
+  }
+
+  return [];
+}
+
+function renderDescriptionMarkdown(description: string): string {
+  return description
+    .replace(/\r\n/g, "\n")
+    .trim()
+    .split(/\n{2,}/)
+    .map((block) => block.split("\n").map((line) => line.trimEnd()).join("  \n"))
+    .join("\n\n")
+    .trim();
+}
+
+function renderSegmentLine(segment: YouTubeTranscriptSegment): string {
+  return `${formatTimestampRange(segment.start, segment.end)} ${segment.text}`;
+}
+
+export function renderYouTubeTranscriptMarkdown({
+  description,
+  segments,
+  chapters,
+}: RenderYouTubeTranscriptMarkdownInput): string {
+  if (segments.length === 0) {
+    return "";
+  }
+
+  const parts: string[] = [];
+  const normalizedDescription = description?.trim();
+  const transcriptEnd = segments.reduce((maxEnd, segment) => Math.max(maxEnd, segment.end, segment.start), 0);
+  const normalizedChapters = normalizeYouTubeChapters(chapters).filter(
+    (chapter) => transcriptEnd <= 0 || chapter.time < transcriptEnd,
+  );
+
+  if (normalizedDescription) {
+    parts.push("## Description");
+    parts.push(renderDescriptionMarkdown(normalizedDescription));
+  }
+
+  if (normalizedChapters.length > 0) {
+    parts.push("## Chapters");
+
+    for (let index = 0; index < normalizedChapters.length; index += 1) {
+      const chapter = normalizedChapters[index];
+      const nextChapter = normalizedChapters[index + 1];
+      const chapterEnd = nextChapter ? nextChapter.time : transcriptEnd;
+      const chapterSegments = segments.filter(
+        (segment) => segment.start >= chapter.time && segment.start < chapterEnd,
+      );
+
+      parts.push(`### ${chapter.title} ${formatTimestampRange(chapter.time, chapterEnd)}`);
+
+      if (chapterSegments.length > 0) {
+        parts.push(chapterSegments.map(renderSegmentLine).join("\n"));
+      }
+    }
+  } else {
+    parts.push("## Transcript");
+    parts.push(segments.map(renderSegmentLine).join("\n"));
+  }
+
+  return parts.filter(Boolean).join("\n\n").trim();
+}
+
+function normalizeThumbnailKey(url: string): string {
+  try {
+    const parsed = new URL(url);
+    return `${parsed.origin}${parsed.pathname}`;
+  } catch {
+    return url;
+  }
+}
+
+export function buildYouTubeThumbnailCandidates(videoId: string, listedUrls: string[]): string[] {
+  const candidates = [
+    ...YOUTUBE_THUMBNAIL_VARIANTS.map((variant) => `https://i.ytimg.com/vi/${videoId}/${variant}`),
+    ...listedUrls,
+  ];
+
+  const seen = new Set<string>();
+  return candidates.filter((candidate) => {
+    if (!candidate) {
+      return false;
+    }
+
+    const key = normalizeThumbnailKey(candidate);
+    if (seen.has(key)) {
+      return false;
+    }
+
+    seen.add(key);
+    return true;
+  });
+}

packages/baoyu-fetch/src/browser/cdp-client.ts

@@ -0,0 +1,258 @@
+import { EventEmitter } from "node:events";
+import WebSocket from "ws";
+
+type JsonObject = Record<string, unknown>;
+
+interface CdpPendingCommand {
+  resolve(value: unknown): void;
+  reject(error: unknown): void;
+  method: string;
+}
+
+interface CdpErrorShape {
+  message?: string;
+}
+
+interface CdpCommandResult<T> {
+  result?: T;
+  error?: CdpErrorShape;
+}
+
+interface CreatePageSessionOptions {
+  initialUrl?: string;
+  visible?: boolean;
+}
+
+export class TargetSession extends EventEmitter {
+  constructor(
+    private readonly client: CdpClient,
+    public readonly targetId: string,
+    public readonly sessionId: string,
+  ) {
+    super();
+  }
+
+  async send<T>(method: string, params: JsonObject = {}): Promise<T> {
+    return this.client.sendSessionCommand<T>(this.sessionId, method, params);
+  }
+
+  handleEvent(method: string, params: JsonObject): void {
+    this.emit(method, params);
+    this.emit("event", { method, params });
+  }
+
+  async waitForEvent<T extends JsonObject>(
+    method: string,
+    predicate?: (params: T) => boolean,
+    timeoutMs = 30_000,
+  ): Promise<T> {
+    return new Promise<T>((resolve, reject) => {
+      const timeout = setTimeout(() => {
+        this.off(method, listener);
+        reject(new Error(`Timed out waiting for ${method}`));
+      }, timeoutMs);
+
+      const listener = (params: T): void => {
+        if (predicate && !predicate(params)) {
+          return;
+        }
+        clearTimeout(timeout);
+        this.off(method, listener);
+        resolve(params);
+      };
+
+      this.on(method, listener);
+    });
+  }
+}
+
+export class CdpClient {
+  private readonly ws: WebSocket;
+  private readonly pending = new Map<number, CdpPendingCommand>();
+  private readonly sessions = new Map<string, TargetSession>();
+  private nextId = 1;
+
+  private constructor(ws: WebSocket) {
+    this.ws = ws;
+    this.ws.on("message", (raw) => {
+      this.handleMessage(raw.toString());
+    });
+  }
+
+  static async connect(browserWsUrl: string): Promise<CdpClient> {
+    const ws = await new Promise<WebSocket>((resolve, reject) => {
+      const socket = new WebSocket(browserWsUrl);
+      socket.once("open", () => resolve(socket));
+      socket.once("error", (error) => reject(error));
+    });
+
+    return new CdpClient(ws);
+  }
+
+  private handleMessage(rawMessage: string): void {
+    const message = JSON.parse(rawMessage) as {
+      id?: number;
+      sessionId?: string;
+      method?: string;
+      params?: JsonObject;
+      result?: unknown;
+      error?: CdpErrorShape;
+    };
+
+    if (typeof message.id === "number") {
+      const pending = this.pending.get(message.id);
+      if (!pending) {
+        return;
+      }
+      this.pending.delete(message.id);
+      if (message.error) {
+        pending.reject(new Error(`${pending.method}: ${message.error.message ?? "Unknown CDP error"}`));
+        return;
+      }
+      pending.resolve(message.result);
+      return;
+    }
+
+    if (typeof message.sessionId === "string" && typeof message.method === "string") {
+      const session = this.sessions.get(message.sessionId);
+      if (session) {
+        session.handleEvent(message.method, (message.params ?? {}) as JsonObject);
+      }
+    }
+  }
+
+  private async sendCommand<T>(
+    method: string,
+    params: JsonObject = {},
+    sessionId?: string,
+  ): Promise<T> {
+    const id = this.nextId;
+    this.nextId += 1;
+
+    const payload = sessionId ? { id, method, params, sessionId } : { id, method, params };
+
+    const result = new Promise<T>((resolve, reject) => {
+      this.pending.set(id, {
+        resolve: (value) => resolve(value as T),
+        reject,
+        method,
+      });
+    });
+
+    this.ws.send(JSON.stringify(payload));
+    return result;
+  }
+
+  async sendBrowserCommand<T>(method: string, params: JsonObject = {}): Promise<T> {
+    return this.sendCommand<T>(method, params);
+  }
+
+  async sendSessionCommand<T>(sessionId: string, method: string, params: JsonObject = {}): Promise<T> {
+    return this.sendCommand<T>(method, params, sessionId);
+  }
+
+  private async createPageTarget(initialUrl: string, visible = false): Promise<{ targetId: string }> {
+    const attempts: JsonObject[] = visible
+      ? [
+          {
+            url: initialUrl,
+            newWindow: true,
+            focus: true,
+          },
+          {
+            url: initialUrl,
+            focus: true,
+          },
+          {
+            url: initialUrl,
+          },
+        ]
+      : [
+          {
+            url: initialUrl,
+            hidden: true,
+          },
+          {
+            url: initialUrl,
+            background: true,
+            focus: false,
+          },
+          {
+            url: initialUrl,
+          },
+        ];
+
+    let lastError: unknown;
+
+    for (const params of attempts) {
+      try {
+        return await this.sendBrowserCommand<{ targetId: string }>("Target.createTarget", params);
+      } catch (error) {
+        lastError = error;
+      }
+    }
+
+    throw lastError instanceof Error ? lastError : new Error("Target.createTarget failed");
+  }
+
+  async createPageSession(options: CreatePageSessionOptions = {}): Promise<TargetSession> {
+    const initialUrl = options.initialUrl ?? "about:blank";
+    const created = await this.createPageTarget(initialUrl, Boolean(options.visible));
+    const attached = await this.sendBrowserCommand<{ sessionId: string }>("Target.attachToTarget", {
+      targetId: created.targetId,
+      flatten: true,
+    });
+
+    const session = new TargetSession(this, created.targetId, attached.sessionId);
+    this.sessions.set(attached.sessionId, session);
+
+    if (options.visible) {
+      await this.sendBrowserCommand("Target.activateTarget", {
+        targetId: created.targetId,
+      }).catch(() => {});
+    }
+
+    await session.send("Page.enable");
+    await session.send("Runtime.enable");
+    await session.send("DOM.enable");
+
+    if (options.visible) {
+      await session.send("Page.bringToFront").catch(() => {});
+    }
+
+    return session;
+  }
+
+  async closeTarget(targetId: string): Promise<void> {
+    try {
+      await this.sendBrowserCommand("Target.closeTarget", { targetId });
+    } catch {
+      // Target may already be gone.
+    }
+  }
+
+  async close(): Promise<void> {
+    await new Promise<void>((resolve) => {
+      if (this.ws.readyState === WebSocket.CLOSED) {
+        resolve();
+        return;
+      }
+      this.ws.once("close", () => resolve());
+      this.ws.close();
+    });
+  }
+}
+
+export async function evaluateRuntime<T>(session: TargetSession, expression: string): Promise<T> {
+  const response = await session.send<CdpCommandResult<{ value?: T; description?: string }>>("Runtime.evaluate", {
+    expression,
+    awaitPromise: true,
+    returnByValue: true,
+  });
+
+  if (response.error) {
+    throw new Error(response.error.message ?? "Runtime.evaluate failed");
+  }
+
+  return (response.result?.value as T | undefined) ?? (undefined as T);
+}

packages/baoyu-fetch/src/browser/chrome-launcher.ts

@@ -0,0 +1,187 @@
+import { launch, type LaunchedChrome } from "chrome-launcher";
+import WebSocket from "ws";
+import type { Logger } from "../utils/logger";
+import {
+  cleanChromeLockArtifacts,
+  ensureChromeProfileDir,
+  findChromeProcessUsingProfile,
+  findExistingChromeDebugPort,
+  hasChromeLockArtifacts,
+  listChromeProfileEntries,
+  resolveChromeProfileDir,
+  shouldRetryChromeLaunchRecovery,
+} from "./profile";
+
+interface ChromeVersionResponse {
+  webSocketDebuggerUrl: string;
+}
+
+export interface ChromeConnectOptions {
+  cdpUrl?: string;
+  browserPath?: string;
+  headless?: boolean;
+  logger?: Logger;
+  profileDir?: string;
+}
+
+export interface ChromeConnection {
+  browserWsUrl: string;
+  origin?: string;
+  port?: number;
+  profileDir?: string;
+  launched: boolean;
+  close(): Promise<void>;
+}
+
+async function fetchJson<T>(url: string): Promise<T> {
+  const response = await fetch(url);
+  if (!response.ok) {
+    throw new Error(`Failed to fetch ${url}: HTTP ${response.status}`);
+  }
+  return (await response.json()) as T;
+}
+
+async function connectToHttpEndpoint(origin: string): Promise<ChromeConnection> {
+  const normalizedOrigin = origin.replace(/\/$/, "");
+  const version = await fetchJson<ChromeVersionResponse>(`${normalizedOrigin}/json/version`);
+  return {
+    browserWsUrl: version.webSocketDebuggerUrl,
+    origin: normalizedOrigin,
+    port: Number(new URL(normalizedOrigin).port || 80),
+    launched: false,
+    async close() {
+      // Reused external Chrome, nothing to close here.
+    },
+  };
+}
+
+async function tryReuseChrome(profileDir: string, logger?: Logger): Promise<ChromeConnection | null> {
+  const port = await findExistingChromeDebugPort({ profileDir });
+  if (!port) {
+    return null;
+  }
+
+  const origin = `http://127.0.0.1:${port}`;
+  try {
+    const connection = await connectToHttpEndpoint(origin);
+    logger?.info(`Reusing Chrome debugger at ${origin} for profile ${profileDir}`);
+    return {
+      ...connection,
+      profileDir,
+    };
+  } catch {
+    // Debugger disappeared between detection and connect.
+  }
+  return null;
+}
+
+async function launchFreshChrome(
+  profileDir: string,
+  options: Pick<ChromeConnectOptions, "browserPath" | "headless">,
+): Promise<ChromeConnection> {
+  let launchedChrome: LaunchedChrome | null = null;
+  try {
+    launchedChrome = await launch({
+      chromePath: options.browserPath,
+      userDataDir: profileDir,
+      chromeFlags: [
+        "--disable-background-networking",
+        "--disable-default-apps",
+        "--disable-popup-blocking",
+        "--disable-sync",
+        "--no-first-run",
+        "--no-default-browser-check",
+        "--remote-allow-origins=*",
+        ...(!options.headless ? ["--no-startup-window"] : []),
+        ...(options.headless ? ["--headless=new"] : []),
+      ],
+    });
+
+    const origin = `http://127.0.0.1:${launchedChrome.port}`;
+    const version = await fetchJson<ChromeVersionResponse>(`${origin}/json/version`);
+
+    const chrome = launchedChrome;
+    return {
+      browserWsUrl: version.webSocketDebuggerUrl,
+      origin,
+      port: launchedChrome.port,
+      profileDir,
+      launched: true,
+      async close() {
+        if (!chrome) return;
+        await gracefulCloseChrome(chrome, origin);
+      },
+    };
+  } catch (error) {
+    launchedChrome?.kill();
+    throw error;
+  }
+}
+
+async function gracefulCloseChrome(chrome: LaunchedChrome, origin: string): Promise<void> {
+  try {
+    const resp = await fetch(`${origin}/json/version`);
+    const { webSocketDebuggerUrl } = (await resp.json()) as ChromeVersionResponse;
+    if (webSocketDebuggerUrl) {
+      const ws = await new Promise<WebSocket>((resolve, reject) => {
+        const socket = new WebSocket(webSocketDebuggerUrl);
+        socket.once("open", () => resolve(socket));
+        socket.once("error", reject);
+      });
+      const id = 1;
+      ws.send(JSON.stringify({ id, method: "Browser.close" }));
+      await new Promise<void>((resolve) => {
+        const timer = setTimeout(() => { ws.close(); resolve(); }, 5_000);
+        ws.once("close", () => { clearTimeout(timer); resolve(); });
+      });
+      const exited = await new Promise<boolean>((resolve) => {
+        if (chrome.pid && !isProcessAlive(chrome.pid)) { resolve(true); return; }
+        const timer = setTimeout(() => resolve(false), 3_000);
+        chrome.process.once("exit", () => { clearTimeout(timer); resolve(true); });
+      });
+      if (exited) return;
+    }
+  } catch {}
+  chrome.kill();
+}
+
+function isProcessAlive(pid: number): boolean {
+  try { process.kill(pid, 0); return true; } catch { return false; }
+}
+
+export async function connectChrome(options: ChromeConnectOptions): Promise<ChromeConnection> {
+  if (options.cdpUrl) {
+    if (options.cdpUrl.startsWith("ws://") || options.cdpUrl.startsWith("wss://")) {
+      return {
+        browserWsUrl: options.cdpUrl,
+        launched: false,
+        async close() {},
+      };
+    }
+    return connectToHttpEndpoint(options.cdpUrl);
+  }
+
+  const profileDir = ensureChromeProfileDir(resolveChromeProfileDir(options.profileDir));
+  const reused = await tryReuseChrome(profileDir, options.logger);
+  if (reused) {
+    return reused;
+  }
+
+  options.logger?.warn(`No running Chrome debugger found for profile ${profileDir}. Launching Chrome with that profile.`);
+  try {
+    return await launchFreshChrome(profileDir, options);
+  } catch (error) {
+    const entries = await listChromeProfileEntries(profileDir);
+    const shouldRetry = shouldRetryChromeLaunchRecovery({
+      hasLockArtifacts: hasChromeLockArtifacts(entries),
+      hasLiveOwner: findChromeProcessUsingProfile(profileDir),
+    });
+    if (!shouldRetry) {
+      throw error;
+    }
+
+    options.logger?.warn(`Chrome launch failed with stale profile locks. Cleaning ${profileDir} and retrying once.`);
+    cleanChromeLockArtifacts(profileDir);
+    return await launchFreshChrome(profileDir, options);
+  }
+}

packages/baoyu-fetch/src/browser/cookie-sidecar.ts

@@ -0,0 +1,100 @@
+import { readFile, writeFile, mkdir } from "node:fs/promises";
+import { dirname, join } from "node:path";
+import { resolveChromeProfileDir } from "./profile";
+import type { TargetSession } from "./cdp-client";
+
+export interface CdpCookie {
+  name: string;
+  value: string;
+  domain: string;
+  path: string;
+  expires: number;
+  size: number;
+  httpOnly: boolean;
+  secure: boolean;
+  session: boolean;
+  sameSite?: string;
+  priority?: string;
+  sameParty?: boolean;
+  sourceScheme?: string;
+  sourcePort?: number;
+  partitionKey?: string;
+}
+
+interface SidecarData {
+  savedAt: string;
+  cookies: CdpCookie[];
+}
+
+export interface CookieSidecarConfig {
+  urls: readonly string[];
+  filename: string;
+  requiredCookieNames: readonly string[];
+  filterCookie?: (cookie: CdpCookie) => boolean;
+}
+
+function sidecarPath(filename: string, profileDir?: string): string {
+  return join(resolveChromeProfileDir(profileDir), filename);
+}
+
+function hasRequired(cookies: CdpCookie[], names: readonly string[]): boolean {
+  return names.every((name) =>
+    cookies.some((c) => c.name === name && Boolean(c.value)),
+  );
+}
+
+async function getCookies(session: TargetSession, urls: readonly string[]): Promise<CdpCookie[]> {
+  const { cookies } = await session.send<{ cookies: CdpCookie[] }>(
+    "Network.getCookies",
+    { urls: [...urls] },
+  );
+  return cookies ?? [];
+}
+
+export async function exportCookies(
+  session: TargetSession,
+  config: CookieSidecarConfig,
+  profileDir?: string,
+): Promise<boolean> {
+  const all = await getCookies(session, config.urls);
+  const filtered = config.filterCookie ? all.filter(config.filterCookie) : all;
+  if (!hasRequired(filtered, config.requiredCookieNames)) return false;
+
+  const filePath = sidecarPath(config.filename, profileDir);
+  await mkdir(dirname(filePath), { recursive: true });
+  const data: SidecarData = { savedAt: new Date().toISOString(), cookies: filtered };
+  await writeFile(filePath, JSON.stringify(data, null, 2));
+  return true;
+}
+
+export async function restoreCookies(
+  session: TargetSession,
+  config: CookieSidecarConfig,
+  profileDir?: string,
+): Promise<boolean> {
+  const live = await getCookies(session, config.urls);
+  if (hasRequired(live, config.requiredCookieNames)) return false;
+
+  const filePath = sidecarPath(config.filename, profileDir);
+  const raw = await readFile(filePath, "utf8");
+  const data = JSON.parse(raw) as SidecarData;
+  if (!data.cookies?.length) return false;
+
+  const now = Date.now() / 1000;
+  const valid = data.cookies.filter((c) => c.session || !c.expires || c.expires > now);
+  if (!hasRequired(valid, config.requiredCookieNames)) return false;
+
+  await session.send("Network.setCookies", {
+    cookies: valid.map((c) => ({
+      name: c.name,
+      value: c.value,
+      domain: c.domain,
+      path: c.path,
+      httpOnly: c.httpOnly,
+      secure: c.secure,
+      sameSite: c.sameSite,
+      expires: c.expires,
+    })),
+  });
+  return true;
+}

packages/baoyu-fetch/src/browser/interaction-gates.ts

@@ -0,0 +1,123 @@
+import type { WaitForInteractionRequest } from "../adapters/types";
+import type { BrowserSession } from "./session";
+
+interface GateSnapshot {
+  title: string;
+  currentUrl: string;
+  bodyText: string;
+  hasCloudflareTurnstile: boolean;
+  hasCloudflareChallenge: boolean;
+  hasRecaptcha: boolean;
+  hasRecaptchaIframe: boolean;
+  hasHcaptcha: boolean;
+  hasHcaptchaIframe: boolean;
+}
+
+export function detectInteractionGateFromSnapshot(snapshot: GateSnapshot): WaitForInteractionRequest | null {
+  const text = snapshot.bodyText.toLowerCase();
+  const title = snapshot.title.toLowerCase();
+  const url = snapshot.currentUrl.toLowerCase();
+
+  if (
+    snapshot.hasCloudflareTurnstile ||
+    snapshot.hasCloudflareChallenge ||
+    title.includes("just a moment") ||
+    text.includes("verify you are human") ||
+    text.includes("checking your browser before accessing") ||
+    text.includes("enable javascript and cookies to continue") ||
+    url.includes("/cdn-cgi/challenge-platform/")
+  ) {
+    return {
+      type: "wait_for_interaction",
+      kind: "cloudflare",
+      provider: "cloudflare",
+      reason: "Cloudflare human verification detected",
+      prompt: "Please complete the Cloudflare verification in the opened Chrome window. Extraction will continue automatically once the challenge disappears.",
+      requiresVisibleBrowser: true,
+    };
+  }
+
+  if (
+    snapshot.hasRecaptcha ||
+    snapshot.hasRecaptchaIframe ||
+    text.includes("i'm not a robot") ||
+    text.includes("recaptcha")
+  ) {
+    return {
+      type: "wait_for_interaction",
+      kind: "recaptcha",
+      provider: "google_recaptcha",
+      reason: "Google reCAPTCHA detected",
+      prompt: "Please complete the reCAPTCHA verification in the opened Chrome window. Extraction will continue automatically once the challenge disappears.",
+      requiresVisibleBrowser: true,
+    };
+  }
+
+  if (
+    snapshot.hasHcaptcha ||
+    snapshot.hasHcaptchaIframe ||
+    text.includes("hcaptcha")
+  ) {
+    return {
+      type: "wait_for_interaction",
+      kind: "hcaptcha",
+      provider: "hcaptcha",
+      reason: "hCaptcha verification detected",
+      prompt: "Please complete the hCaptcha verification in the opened Chrome window. Extraction will continue automatically once the challenge disappears.",
+      requiresVisibleBrowser: true,
+    };
+  }
+
+  return null;
+}
+
+export async function detectInteractionGate(browser: BrowserSession): Promise<WaitForInteractionRequest | null> {
+  const snapshot = await browser.evaluate<GateSnapshot>(`
+    (() => {
+      const bodyText = (document.body?.innerText ?? "").slice(0, 4000);
+      return {
+        title: document.title ?? "",
+        currentUrl: window.location.href,
+        bodyText,
+        hasCloudflareTurnstile: Boolean(
+          document.querySelector(
+            '.cf-turnstile, [name="cf-turnstile-response"], iframe[src*="challenges.cloudflare.com"]'
+          )
+        ),
+        hasCloudflareChallenge: Boolean(
+          document.querySelector(
+            '#challenge-running, #cf-challenge-running, .challenge-platform, [data-ray], [data-translate="checking_browser"]'
+          )
+        ),
+        hasRecaptcha: Boolean(
+          document.querySelector(
+            '.g-recaptcha, textarea[name="g-recaptcha-response"], iframe[title*="reCAPTCHA"]'
+          )
+        ),
+        hasRecaptchaIframe: Boolean(
+          document.querySelector('iframe[src*="google.com/recaptcha"], iframe[src*="recaptcha/api2"]')
+        ),
+        hasHcaptcha: Boolean(
+          document.querySelector(
+            '.h-captcha, textarea[name="h-captcha-response"], iframe[title*="hCaptcha"]'
+          )
+        ),
+        hasHcaptchaIframe: Boolean(
+          document.querySelector('iframe[src*="hcaptcha.com"]')
+        ),
+      };
+    })()
+  `).catch(() => ({
+    title: "",
+    currentUrl: "",
+    bodyText: "",
+    hasCloudflareTurnstile: false,
+    hasCloudflareChallenge: false,
+    hasRecaptcha: false,
+    hasRecaptchaIframe: false,
+    hasHcaptcha: false,
+    hasHcaptchaIframe: false,
+  }));
+
+  return detectInteractionGateFromSnapshot(snapshot);
+}

packages/baoyu-fetch/src/browser/network-journal.ts

@@ -0,0 +1,235 @@
+import type { TargetSession } from "./cdp-client";
+import type { Logger } from "../utils/logger";
+
+type JsonObject = Record<string, unknown>;
+
+export interface NetworkEntry {
+  requestId: string;
+  url: string;
+  method: string;
+  resourceType: string;
+  timestamp: number;
+  requestHeaders?: Record<string, string>;
+  requestBody?: string;
+  status?: number;
+  statusText?: string;
+  responseHeaders?: Record<string, string>;
+  mimeType?: string;
+  body?: string;
+  bodyBase64?: boolean;
+  bodyError?: string;
+  failed?: boolean;
+  failureReason?: string;
+  finished: boolean;
+}
+
+function normalizeHeaders(headers: unknown): Record<string, string> | undefined {
+  if (!headers || typeof headers !== "object") {
+    return undefined;
+  }
+  return Object.fromEntries(
+    Object.entries(headers as Record<string, unknown>).map(([key, value]) => [key, String(value)]),
+  );
+}
+
+function sleep(ms: number): Promise<void> {
+  return new Promise((resolve) => setTimeout(resolve, ms));
+}
+
+export class NetworkJournal {
+  private readonly entries = new Map<string, NetworkEntry>();
+  private lastActivityAt = Date.now();
+  private started = false;
+
+  constructor(
+    private readonly session: TargetSession,
+    private readonly log: Logger,
+  ) {}
+
+  async start(): Promise<void> {
+    if (this.started) {
+      return;
+    }
+
+    this.started = true;
+    this.session.on("Network.requestWillBeSent", this.handleRequestWillBeSent);
+    this.session.on("Network.responseReceived", this.handleResponseReceived);
+    this.session.on("Network.loadingFinished", this.handleLoadingFinished);
+    this.session.on("Network.loadingFailed", this.handleLoadingFailed);
+    await this.session.send("Network.enable");
+  }
+
+  stop(): void {
+    if (!this.started) {
+      return;
+    }
+    this.session.off("Network.requestWillBeSent", this.handleRequestWillBeSent);
+    this.session.off("Network.responseReceived", this.handleResponseReceived);
+    this.session.off("Network.loadingFinished", this.handleLoadingFinished);
+    this.session.off("Network.loadingFailed", this.handleLoadingFailed);
+    this.started = false;
+  }
+
+  private touch(): void {
+    this.lastActivityAt = Date.now();
+  }
+
+  private readonly handleRequestWillBeSent = (params: JsonObject): void => {
+    const requestId = typeof params.requestId === "string" ? params.requestId : undefined;
+    const request = params.request as JsonObject | undefined;
+    if (!requestId || !request) {
+      return;
+    }
+
+    this.touch();
+    this.entries.set(requestId, {
+      requestId,
+      url: String(request.url ?? ""),
+      method: String(request.method ?? "GET"),
+      resourceType: String(params.type ?? "Other"),
+      timestamp: Date.now(),
+      requestHeaders: normalizeHeaders(request.headers),
+      requestBody: typeof request.postData === "string" ? request.postData : undefined,
+      finished: false,
+    });
+  };
+
+  private readonly handleResponseReceived = (params: JsonObject): void => {
+    const requestId = typeof params.requestId === "string" ? params.requestId : undefined;
+    const response = params.response as JsonObject | undefined;
+    if (!requestId || !response) {
+      return;
+    }
+
+    this.touch();
+    const existing = this.entries.get(requestId);
+    if (!existing) {
+      return;
+    }
+
+    existing.status = typeof response.status === "number" ? response.status : undefined;
+    existing.statusText = typeof response.statusText === "string" ? response.statusText : undefined;
+    existing.responseHeaders = normalizeHeaders(response.headers);
+    existing.mimeType = typeof response.mimeType === "string" ? response.mimeType : undefined;
+    this.entries.set(requestId, existing);
+  };
+
+  private readonly handleLoadingFinished = (params: JsonObject): void => {
+    const requestId = typeof params.requestId === "string" ? params.requestId : undefined;
+    if (!requestId) {
+      return;
+    }
+
+    this.touch();
+    const existing = this.entries.get(requestId);
+    if (!existing) {
+      return;
+    }
+    existing.finished = true;
+    this.entries.set(requestId, existing);
+  };
+
+  private readonly handleLoadingFailed = (params: JsonObject): void => {
+    const requestId = typeof params.requestId === "string" ? params.requestId : undefined;
+    if (!requestId) {
+      return;
+    }
+
+    this.touch();
+    const existing = this.entries.get(requestId);
+    if (!existing) {
+      return;
+    }
+    existing.finished = true;
+    existing.failed = true;
+    existing.failureReason = typeof params.errorText === "string" ? params.errorText : "Unknown error";
+    this.entries.set(requestId, existing);
+  };
+
+  getEntries(): NetworkEntry[] {
+    return Array.from(this.entries.values());
+  }
+
+  findEntries(predicate: (entry: NetworkEntry) => boolean): NetworkEntry[] {
+    return this.getEntries().filter(predicate);
+  }
+
+  async waitForIdle(options: { idleMs?: number; timeoutMs?: number } = {}): Promise<void> {
+    const idleMs = options.idleMs ?? 1_200;
+    const timeoutMs = options.timeoutMs ?? 15_000;
+    const startedAt = Date.now();
+
+    while (Date.now() - startedAt < timeoutMs) {
+      if (Date.now() - this.lastActivityAt >= idleMs) {
+        return;
+      }
+      await sleep(Math.min(150, idleMs));
+    }
+
+    throw new Error("Timed out waiting for network idle");
+  }
+
+  async waitForResponse(
+    predicate: (entry: NetworkEntry) => boolean,
+    options: { timeoutMs?: number } = {},
+  ): Promise<NetworkEntry> {
+    const timeoutMs = options.timeoutMs ?? 10_000;
+    const startedAt = Date.now();
+
+    while (Date.now() - startedAt < timeoutMs) {
+      const matched = this.getEntries().find((entry) => entry.finished && predicate(entry));
+      if (matched) {
+        return matched;
+      }
+      await sleep(150);
+    }
+
+    throw new Error("Timed out waiting for matching network response");
+  }
+
+  async ensureBody(entry: NetworkEntry): Promise<string | undefined> {
+    if (entry.body !== undefined) {
+      return entry.body;
+    }
+    if (entry.bodyError || entry.failed || !entry.finished) {
+      return undefined;
+    }
+
+    try {
+      const result = await this.session.send<{ body: string; base64Encoded: boolean }>("Network.getResponseBody", {
+        requestId: entry.requestId,
+      });
+      entry.bodyBase64 = result.base64Encoded;
+      entry.body = result.base64Encoded ? Buffer.from(result.body, "base64").toString("utf8") : result.body;
+      return entry.body;
+    } catch (error) {
+      entry.bodyError = error instanceof Error ? error.message : String(error);
+      this.log.debug(`Failed to fetch response body for ${entry.url}: ${entry.bodyError}`);
+      return undefined;
+    }
+  }
+
+  async getJsonBody(entry: NetworkEntry): Promise<unknown | null> {
+    const body = await this.ensureBody(entry);
+    if (!body) {
+      return null;
+    }
+
+    try {
+      return JSON.parse(body);
+    } catch {
+      return null;
+    }
+  }
+
+  async toJSON(options: { includeBodies?: boolean } = {}): Promise<NetworkEntry[]> {
+    const entries = this.getEntries();
+    if (!options.includeBodies) {
+      return entries;
+    }
+
+    await Promise.all(entries.map((entry) => this.ensureBody(entry)));
+    return entries;
+  }
+}
+

packages/baoyu-fetch/src/browser/page-snapshot.ts

@@ -0,0 +1,105 @@
+import type { BrowserSession } from "./session";
+
+export interface CapturedPageSnapshot {
+  html: string;
+  finalUrl: string;
+}
+
+export const CAPTURE_NORMALIZED_PAGE_SCRIPT = String.raw`
+(() => {
+  const baseUrl = document.baseURI || location.href;
+  const htmlClone = document.documentElement.cloneNode(true);
+
+  function materializeShadowDom(sourceRoot, cloneRoot) {
+    const sourceElements = Array.from(sourceRoot.querySelectorAll("*"));
+    const cloneElements = Array.from(cloneRoot.querySelectorAll("*"));
+
+    for (let index = sourceElements.length - 1; index >= 0; index -= 1) {
+      const sourceElement = sourceElements[index];
+      const cloneElement = cloneElements[index];
+      const shadowRoot = sourceElement && sourceElement.shadowRoot;
+      if (!shadowRoot || !cloneElement || !shadowRoot.innerHTML) {
+        continue;
+      }
+
+      if (cloneElement.tagName && cloneElement.tagName.includes("-")) {
+        const wrapper = document.createElement("div");
+        wrapper.setAttribute("data-shadow-host", cloneElement.tagName.toLowerCase());
+        wrapper.innerHTML = shadowRoot.innerHTML;
+        cloneElement.replaceWith(wrapper);
+      } else {
+        cloneElement.innerHTML = shadowRoot.innerHTML;
+      }
+    }
+  }
+
+  function toAbsolute(url) {
+    if (!url) return url;
+    try {
+      return new URL(url, baseUrl).href;
+    } catch {
+      return url;
+    }
+  }
+
+  function absolutizeAttribute(root, selector, attribute) {
+    root.querySelectorAll(selector).forEach((element) => {
+      const value = element.getAttribute(attribute);
+      if (!value) return;
+      const absolute = toAbsolute(value);
+      if (absolute) {
+        element.setAttribute(attribute, absolute);
+      }
+    });
+  }
+
+  function absolutizeSrcset(root, selector) {
+    root.querySelectorAll(selector).forEach((element) => {
+      const srcset = element.getAttribute("srcset");
+      if (!srcset) return;
+      element.setAttribute(
+        "srcset",
+        srcset
+          .split(",")
+          .map((part) => {
+            const trimmed = part.trim();
+            if (!trimmed) return "";
+            const [url, ...descriptor] = trimmed.split(/\s+/);
+            const absolute = toAbsolute(url);
+            return descriptor.length > 0 ? absolute + " " + descriptor.join(" ") : absolute;
+          })
+          .filter(Boolean)
+          .join(", "),
+      );
+    });
+  }
+
+  materializeShadowDom(document.documentElement, htmlClone);
+
+  htmlClone
+    .querySelectorAll("img[data-src], video[data-src], audio[data-src], source[data-src]")
+    .forEach((element) => {
+      const dataSource = element.getAttribute("data-src");
+      const current = element.getAttribute("src");
+      if (dataSource && (!current || current === "" || current.startsWith("data:"))) {
+        element.setAttribute("src", dataSource);
+      }
+    });
+
+  absolutizeAttribute(htmlClone, "a[href]", "href");
+  absolutizeAttribute(htmlClone, "img[src], video[src], audio[src], source[src], iframe[src]", "src");
+  absolutizeAttribute(htmlClone, "video[poster]", "poster");
+  absolutizeSrcset(htmlClone, "img[srcset], source[srcset]");
+
+  return {
+    html: "<!doctype html>\n" + htmlClone.outerHTML,
+    finalUrl: location.href,
+  };
+})()
+`;
+
+export async function captureNormalizedPageSnapshot(
+  browser: BrowserSession,
+): Promise<CapturedPageSnapshot> {
+  return browser.evaluate<CapturedPageSnapshot>(CAPTURE_NORMALIZED_PAGE_SCRIPT);
+}

packages/baoyu-fetch/src/browser/profile.ts

@@ -0,0 +1,201 @@
+import fs from "node:fs";
+import os from "node:os";
+import path from "node:path";
+import process from "node:process";
+import { spawnSync } from "node:child_process";
+
+export interface ResolveSharedChromeProfileDirOptions {
+  envNames?: string[];
+  appDataDirName?: string;
+  profileDirName?: string;
+}
+
+export interface FindExistingChromeDebugPortOptions {
+  profileDir: string;
+  timeoutMs?: number;
+}
+
+interface ChromeVersionResponse {
+  webSocketDebuggerUrl?: string;
+}
+
+const CHROME_LOCK_FILE_NAMES = ["SingletonLock", "SingletonSocket", "SingletonCookie", "chrome.pid"] as const;
+
+function resolveDataBaseDir(): string {
+  if (process.platform === "darwin") {
+    return path.join(os.homedir(), "Library", "Application Support");
+  }
+  if (process.platform === "win32") {
+    return process.env.APPDATA ?? path.join(os.homedir(), "AppData", "Roaming");
+  }
+  return process.env.XDG_DATA_HOME ?? path.join(os.homedir(), ".local", "share");
+}
+
+export function resolveSharedChromeProfileDir(
+  options: ResolveSharedChromeProfileDirOptions = {},
+): string {
+  for (const envName of options.envNames ?? []) {
+    const override = process.env[envName]?.trim();
+    if (override) {
+      return path.resolve(override);
+    }
+  }
+
+  const appDataDirName = options.appDataDirName ?? "baoyu-skills";
+  const profileDirName = options.profileDirName ?? "chrome-profile";
+  return path.join(resolveDataBaseDir(), appDataDirName, profileDirName);
+}
+
+export function resolveChromeProfileDir(profileDir?: string): string {
+  if (profileDir?.trim()) {
+    return path.resolve(profileDir.trim());
+  }
+
+  return resolveSharedChromeProfileDir({
+    envNames: ["BAOYU_CHROME_PROFILE_DIR"],
+    appDataDirName: "baoyu-skills",
+    profileDirName: "chrome-profile",
+  });
+}
+
+export function ensureChromeProfileDir(profileDir: string): string {
+  fs.mkdirSync(profileDir, { recursive: true });
+  return profileDir;
+}
+
+export function hasChromeLockArtifacts(entries: readonly string[]): boolean {
+  return CHROME_LOCK_FILE_NAMES.some((name) => entries.includes(name));
+}
+
+export function shouldRetryChromeLaunchRecovery(options: {
+  hasLockArtifacts: boolean;
+  hasLiveOwner: boolean;
+}): boolean {
+  return options.hasLockArtifacts && !options.hasLiveOwner;
+}
+
+export function findChromeProcessUsingProfile(profileDir: string): boolean {
+  if (process.platform === "win32") {
+    return false;
+  }
+
+  try {
+    const result = spawnSync("ps", ["aux"], {
+      encoding: "utf8",
+      timeout: 5_000,
+    });
+    if (result.status !== 0 || !result.stdout) {
+      return false;
+    }
+
+    return result.stdout
+      .split("\n")
+      .some((line) => line.includes(`--user-data-dir=${profileDir}`));
+  } catch {
+    return false;
+  }
+}
+
+export function cleanChromeLockArtifacts(profileDir: string): void {
+  for (const name of CHROME_LOCK_FILE_NAMES) {
+    try {
+      fs.unlinkSync(path.join(profileDir, name));
+    } catch {
+      // Ignore missing files and continue cleaning the remaining artifacts.
+    }
+  }
+}
+
+export async function listChromeProfileEntries(profileDir: string): Promise<string[]> {
+  try {
+    return await fs.promises.readdir(profileDir);
+  } catch {
+    return [];
+  }
+}
+
+async function fetchWithTimeout(url: string, timeoutMs = 3_000): Promise<Response> {
+  const controller = new AbortController();
+  const timer = setTimeout(() => controller.abort(), timeoutMs);
+  try {
+    return await fetch(url, {
+      redirect: "follow",
+      signal: controller.signal,
+    });
+  } finally {
+    clearTimeout(timer);
+  }
+}
+
+async function fetchJson<T>(url: string, timeoutMs = 3_000): Promise<T> {
+  const response = await fetchWithTimeout(url, timeoutMs);
+  if (!response.ok) {
+    throw new Error(`Request failed: ${response.status} ${response.statusText}`);
+  }
+  return (await response.json()) as T;
+}
+
+async function isDebugPortReady(port: number, timeoutMs = 3_000): Promise<boolean> {
+  try {
+    const version = await fetchJson<ChromeVersionResponse>(`http://127.0.0.1:${port}/json/version`, timeoutMs);
+    return Boolean(version.webSocketDebuggerUrl);
+  } catch {
+    return false;
+  }
+}
+
+function parseDevToolsActivePort(filePath: string): { port: number; wsPath: string } | null {
+  try {
+    const content = fs.readFileSync(filePath, "utf8");
+    const lines = content.split(/\r?\n/);
+    const port = Number.parseInt(lines[0]?.trim() ?? "", 10);
+    const wsPath = lines[1]?.trim() ?? "";
+    if (port > 0 && wsPath) {
+      return { port, wsPath };
+    }
+  } catch {
+    // Ignore and fall back to process inspection.
+  }
+
+  return null;
+}
+
+export async function findExistingChromeDebugPort(
+  options: FindExistingChromeDebugPortOptions,
+): Promise<number | null> {
+  const timeoutMs = options.timeoutMs ?? 3_000;
+  const activePort = parseDevToolsActivePort(path.join(options.profileDir, "DevToolsActivePort"));
+  if (activePort && await isDebugPortReady(activePort.port, timeoutMs)) {
+    return activePort.port;
+  }
+
+  if (process.platform === "win32") {
+    return null;
+  }
+
+  try {
+    const result = spawnSync("ps", ["aux"], {
+      encoding: "utf8",
+      timeout: 5_000,
+    });
+    if (result.status !== 0 || !result.stdout) {
+      return null;
+    }
+
+    const lines = result.stdout
+      .split("\n")
+      .filter((line) => line.includes(options.profileDir) && line.includes("--remote-debugging-port="));
+
+    for (const line of lines) {
+      const match = line.match(/--remote-debugging-port=(\d+)/);
+      const port = Number.parseInt(match?.[1] ?? "", 10);
+      if (port > 0 && await isDebugPortReady(port, timeoutMs)) {
+        return port;
+      }
+    }
+  } catch {
+    // Ignore and report no reusable debugger.
+  }
+
+  return null;
+}

packages/baoyu-fetch/src/browser/session.ts

@@ -0,0 +1,155 @@
+import { execFile } from "node:child_process";
+import { promisify } from "node:util";
+import { CdpClient, TargetSession, evaluateRuntime } from "./cdp-client";
+
+interface NavigationResult {
+  errorText?: string;
+}
+
+const execFileAsync = promisify(execFile);
+const MACOS_BROWSER_APP_IDS = [
+  "com.google.Chrome",
+  "org.chromium.Chromium",
+  "com.brave.Browser",
+  "com.microsoft.edgemac",
+];
+
+function sleep(ms: number): Promise<void> {
+  return new Promise((resolve) => setTimeout(resolve, ms));
+}
+
+async function activateBrowserApp(): Promise<void> {
+  if (process.platform !== "darwin") {
+    return;
+  }
+
+  for (const appId of MACOS_BROWSER_APP_IDS) {
+    try {
+      await execFileAsync("osascript", ["-e", `tell application id "${appId}" to activate`]);
+      return;
+    } catch {
+      // Try the next installed browser bundle id.
+    }
+  }
+}
+
+export class BrowserSession {
+  private constructor(
+    private readonly cdp: CdpClient,
+    public readonly targetSession: TargetSession,
+    public readonly interactive: boolean,
+  ) {}
+
+  static async open(
+    cdp: CdpClient,
+    options: {
+      initialUrl?: string;
+      interactive?: boolean;
+    } = {},
+  ): Promise<BrowserSession> {
+    const targetSession = await cdp.createPageSession({
+      initialUrl: options.initialUrl,
+      visible: options.interactive,
+    });
+    const browser = new BrowserSession(cdp, targetSession, Boolean(options.interactive));
+    if (browser.interactive) {
+      await browser.bringToFront().catch(() => {});
+    }
+    return browser;
+  }
+
+  async goto(url: string, timeoutMs = 30_000): Promise<void> {
+    const loadPromise = this.targetSession.waitForEvent("Page.loadEventFired", undefined, timeoutMs).catch(() => null);
+    const result = await this.targetSession.send<NavigationResult>("Page.navigate", { url });
+    if (result.errorText) {
+      throw new Error(`Navigation failed: ${result.errorText}`);
+    }
+    await loadPromise;
+    await this.waitForReadyState(timeoutMs);
+  }
+
+  async waitForReadyState(timeoutMs = 30_000): Promise<void> {
+    const startedAt = Date.now();
+    while (Date.now() - startedAt < timeoutMs) {
+      const state = await this.evaluate<string>("document.readyState");
+      if (state === "interactive" || state === "complete") {
+        return;
+      }
+      await sleep(150);
+    }
+    throw new Error("Timed out waiting for document.readyState");
+  }
+
+  async evaluate<T>(expression: string): Promise<T> {
+    return evaluateRuntime<T>(this.targetSession, expression);
+  }
+
+  async getHTML(): Promise<string> {
+    return this.evaluate<string>("document.documentElement.outerHTML");
+  }
+
+  async getTitle(): Promise<string> {
+    return this.evaluate<string>("document.title");
+  }
+
+  async getURL(): Promise<string> {
+    return this.evaluate<string>("window.location.href");
+  }
+
+  async bringToFront(): Promise<void> {
+    await this.targetSession.send("Page.bringToFront").catch(async () => {
+      await this.cdp.sendBrowserCommand("Target.activateTarget", {
+        targetId: this.targetSession.targetId,
+      });
+    });
+    if (this.interactive) {
+      await activateBrowserApp().catch(() => {});
+    }
+  }
+
+  async click(selector: string): Promise<void> {
+    const result = await this.evaluate<{ ok: boolean; error?: string }>(`
+      (() => {
+        const element = document.querySelector(${JSON.stringify(selector)});
+        if (!element) {
+          return { ok: false, error: "Element not found" };
+        }
+        element.scrollIntoView({ block: "center", inline: "center" });
+        if (element instanceof HTMLElement) {
+          element.click();
+          return { ok: true };
+        }
+        return { ok: false, error: "Element is not clickable" };
+      })()
+    `);
+
+    if (!result.ok) {
+      throw new Error(result.error ?? `Failed to click ${selector}`);
+    }
+  }
+
+  async scrollToEnd(options: { stepPx?: number; delayMs?: number; maxSteps?: number } = {}): Promise<void> {
+    const stepPx = options.stepPx ?? 1_400;
+    const delayMs = options.delayMs ?? 250;
+    const maxSteps = options.maxSteps ?? 6;
+
+    for (let step = 0; step < maxSteps; step += 1) {
+      const done = await this.evaluate<boolean>(`
+        (() => {
+          const before = window.scrollY;
+          window.scrollBy(0, ${stepPx});
+          const atBottom = window.innerHeight + window.scrollY >= document.body.scrollHeight - 4;
+          return atBottom || window.scrollY === before;
+        })()
+      `);
+      if (done) {
+        break;
+      }
+      await sleep(delayMs);
+    }
+  }
+
+  async close(): Promise<void> {
+    await this.cdp.closeTarget(this.targetSession.targetId);
+  }
+}

packages/baoyu-fetch/src/cli.ts

@@ -0,0 +1,227 @@
+#!/usr/bin/env bun
+
+import {
+  runConvertCommand,
+  type ConvertCommandOptions,
+  type OutputFormat,
+  type WaitMode,
+} from "./commands/convert";
+
+export const HELP_TEXT = `
+baoyu-fetch - Read a URL into Markdown or JSON with Chrome CDP
+
+Usage:
+  baoyu-fetch <url> [options]
+
+Options:
+  --output <file>       Save output to file
+  --format <type>       Output format: markdown | json
+  --json                Alias for --format json
+  --adapter <name>      Force an adapter (e.g. x, generic)
+  --download-media      Download adapter-reported media into ./imgs and ./videos, then rewrite markdown links
+  --media-dir <dir>     Base directory for downloaded media. Defaults to the output directory
+  --debug-dir <dir>     Write debug artifacts
+  --cdp-url <url>       Reuse an existing Chrome DevTools endpoint
+  --browser-path <path> Explicit Chrome binary path
+  --chrome-profile-dir <path>
+                        Chrome user data dir. Defaults to BAOYU_CHROME_PROFILE_DIR
+                        or baoyu-skills/chrome-profile.
+  --headless            Launch a temporary headless Chrome if needed
+  --wait-for <mode>     Wait mode: interaction | force
+                        interaction: start visible Chrome and auto-wait only when login or verification is required
+                        force: start visible Chrome, then auto-continue after it detects login/challenge progress
+                               or continue immediately when you press Enter
+  --wait-for-interaction
+                        Alias for --wait-for interaction
+  --wait-for-login      Alias for --wait-for interaction
+  --interaction-timeout <ms>
+                        How long to wait for manual interaction before failing (default: 600000)
+  --interaction-poll-interval <ms>
+                        How often to poll interaction state while waiting (default: 1500)
+  --login-timeout <ms>  Alias for --interaction-timeout
+  --login-poll-interval <ms>
+                        Alias for --interaction-poll-interval
+  --timeout <ms>        Page timeout in milliseconds (default: 30000)
+  --help                Show help
+
+Examples:
+  baoyu-fetch https://example.com
+  baoyu-fetch https://example.com --format markdown --output article.md --download-media
+  baoyu-fetch https://example.com --format json --output article.json
+  baoyu-fetch https://x.com/lennysan/status/2036483059407810640 --wait-for interaction
+  baoyu-fetch https://x.com/lennysan/status/2036483059407810640 --wait-for force
+`.trim();
+
+interface CliOptions extends ConvertCommandOptions {
+  url?: string;
+  help: boolean;
+}
+
+function normalizeWaitMode(raw: string): WaitMode {
+  const value = raw.toLowerCase();
+  if (value === "interaction" || value === "auto") {
+    return "interaction";
+  }
+  if (value === "force" || value === "manual" || value === "always") {
+    return "force";
+  }
+  throw new Error(`Invalid wait mode: ${raw}. Expected interaction or force.`);
+}
+
+function normalizeOutputFormat(raw: string): OutputFormat {
+  const value = raw.toLowerCase();
+  if (value === "markdown" || value === "json") {
+    return value;
+  }
+
+  throw new Error(`Invalid output format: ${raw}. Expected markdown or json.`);
+}
+
+export function parseArgs(argv: string[]): CliOptions {
+  const options: CliOptions = {
+    format: "markdown",
+    headless: false,
+    downloadMedia: false,
+    waitMode: "none",
+    interactionTimeoutMs: 600_000,
+    interactionPollIntervalMs: 1_500,
+    timeoutMs: 30_000,
+    help: false,
+  };
+
+  const args = argv.slice(2);
+  for (let index = 0; index < args.length; index += 1) {
+    const value = args[index];
+
+    if (value === "--help" || value === "-h") {
+      options.help = true;
+      continue;
+    }
+    if (value === "--format") {
+      const format = args[index + 1];
+      if (!format) {
+        throw new Error("--format requires a value");
+      }
+      options.format = normalizeOutputFormat(format);
+      index += 1;
+      continue;
+    }
+    if (value === "--json") {
+      options.format = "json";
+      continue;
+    }
+    if (value === "--download-media") {
+      options.downloadMedia = true;
+      continue;
+    }
+    if (value === "--headless") {
+      options.headless = true;
+      continue;
+    }
+    if (value === "--wait-for") {
+      const mode = args[index + 1];
+      if (!mode) {
+        throw new Error("--wait-for requires a mode");
+      }
+      options.waitMode = normalizeWaitMode(mode);
+      index += 1;
+      continue;
+    }
+    if (value === "--wait-for-interaction" || value === "--wait-for-login") {
+      options.waitMode = "interaction";
+      continue;
+    }
+    if (value === "--output") {
+      options.output = args[index + 1];
+      index += 1;
+      continue;
+    }
+    if (value === "--adapter") {
+      options.adapter = args[index + 1];
+      index += 1;
+      continue;
+    }
+    if (value === "--debug-dir") {
+      options.debugDir = args[index + 1];
+      index += 1;
+      continue;
+    }
+    if (value === "--media-dir") {
+      options.mediaDir = args[index + 1];
+      index += 1;
+      continue;
+    }
+    if (value === "--cdp-url") {
+      options.cdpUrl = args[index + 1];
+      index += 1;
+      continue;
+    }
+    if (value === "--browser-path") {
+      options.browserPath = args[index + 1];
+      index += 1;
+      continue;
+    }
+    if (value === "--chrome-profile-dir") {
+      options.chromeProfileDir = args[index + 1];
+      index += 1;
+      continue;
+    }
+    if (value === "--timeout") {
+      const parsed = Number(args[index + 1]);
+      if (!Number.isFinite(parsed) || parsed <= 0) {
+        throw new Error(`Invalid timeout: ${args[index + 1]}`);
+      }
+      options.timeoutMs = parsed;
+      index += 1;
+      continue;
+    }
+    if (value === "--interaction-timeout" || value === "--login-timeout") {
+      const parsed = Number(args[index + 1]);
+      if (!Number.isFinite(parsed) || parsed <= 0) {
+        throw new Error(`Invalid interaction timeout: ${args[index + 1]}`);
+      }
+      options.interactionTimeoutMs = parsed;
+      index += 1;
+      continue;
+    }
+    if (value === "--interaction-poll-interval" || value === "--login-poll-interval") {
+      const parsed = Number(args[index + 1]);
+      if (!Number.isFinite(parsed) || parsed <= 0) {
+        throw new Error(`Invalid interaction poll interval: ${args[index + 1]}`);
+      }
+      options.interactionPollIntervalMs = parsed;
+      index += 1;
+      continue;
+    }
+    if (value.startsWith("-")) {
+      throw new Error(`Unknown option: ${value}`);
+    }
+    if (!options.url) {
+      options.url = value;
+      continue;
+    }
+    throw new Error(`Unexpected argument: ${value}`);
+  }
+
+  return options;
+}
+
+async function main(): Promise<void> {
+  try {
+    const options = parseArgs(process.argv);
+    if (options.help || !options.url) {
+      console.log(HELP_TEXT);
+      return;
+    }
+
+    await runConvertCommand(options);
+  } catch (error) {
+    const message = error instanceof Error ? error.message : String(error);
+    console.error(message);
+    process.exitCode = 1;
+  }
+}
+
+if (import.meta.main) {
+  void main();
+}

packages/baoyu-fetch/src/commands/convert.ts

@@ -0,0 +1,580 @@
+import { mkdir, writeFile } from "node:fs/promises";
+import { join } from "node:path";
+import { createInterface } from "node:readline";
+import { connectChrome, type ChromeConnection } from "../browser/chrome-launcher";
+import { CdpClient } from "../browser/cdp-client";
+import { detectInteractionGate } from "../browser/interaction-gates";
+import { NetworkJournal } from "../browser/network-journal";
+import { BrowserSession } from "../browser/session";
+import { genericAdapter, resolveAdapter } from "../adapters";
+import { isXSessionReady } from "../adapters/x/session";
+import type { ExtractedDocument } from "../extract/document";
+import { renderMarkdown } from "../extract/markdown-renderer";
+import { downloadMediaAssets } from "../media/default-downloader";
+import { rewriteMarkdownMediaLinks } from "../media/markdown-media";
+import { createLogger } from "../utils/logger";
+import { normalizeUrl } from "../utils/url";
+import type {
+  Adapter,
+  AdapterContext,
+  AdapterLoginInfo,
+  LoginState,
+  MediaAsset,
+  WaitForInteractionRequest,
+} from "../adapters/types";
+
+export type WaitMode = "none" | "interaction" | "force";
+export type OutputFormat = "markdown" | "json";
+
+export interface ConvertCommandOptions {
+  url?: string;
+  output?: string;
+  format: OutputFormat;
+  adapter?: string;
+  debugDir?: string;
+  cdpUrl?: string;
+  browserPath?: string;
+  chromeProfileDir?: string;
+  headless: boolean;
+  downloadMedia: boolean;
+  mediaDir?: string;
+  waitMode: WaitMode;
+  interactionTimeoutMs: number;
+  interactionPollIntervalMs: number;
+  timeoutMs: number;
+}
+
+interface RuntimeResources {
+  chrome: ChromeConnection;
+  cdp: CdpClient;
+  browser: BrowserSession;
+  network: NetworkJournal;
+  interactive: boolean;
+}
+
+interface ForceWaitSnapshot {
+  url: string;
+  hasGate: boolean;
+  loginState: LoginState | "unavailable";
+  sessionReady: boolean;
+}
+
+interface SuccessfulConvertOutput {
+  adapter: string;
+  status: "ok";
+  login?: AdapterLoginInfo;
+  media: MediaAsset[];
+  downloads: Awaited<ReturnType<typeof downloadMediaAssets>> | null;
+  document: ExtractedDocument;
+  markdown: string;
+}
+
+interface InteractionRequiredOutput {
+  adapter: string;
+  status: "needs_interaction";
+  login?: AdapterLoginInfo;
+  interaction: WaitForInteractionRequest;
+}
+
+function sleep(ms: number): Promise<void> {
+  return new Promise((resolve) => setTimeout(resolve, ms));
+}
+
+function isForceWaitSessionReady(snapshot: ForceWaitSnapshot): boolean {
+  return snapshot.sessionReady;
+}
+
+export function shouldKeepBrowserOpenAfterInteraction(options: {
+  launched: boolean;
+  interaction: Pick<WaitForInteractionRequest, "kind" | "provider">;
+}): boolean {
+  return options.launched && options.interaction.kind === "login" && options.interaction.provider === "x";
+}
+
+export function shouldAutoContinueForceWait(
+  initial: ForceWaitSnapshot,
+  current: ForceWaitSnapshot,
+): boolean {
+  if (initial.hasGate && !current.hasGate) {
+    return true;
+  }
+
+  if (initial.loginState === "logged_out" && current.loginState !== "logged_out" && isForceWaitSessionReady(current)) {
+    return true;
+  }
+
+  if (initial.loginState !== "logged_in" && current.loginState === "logged_in" && isForceWaitSessionReady(current)) {
+    return true;
+  }
+
+  if (
+    current.url !== initial.url &&
+    !current.hasGate &&
+    current.loginState !== "logged_out" &&
+    isForceWaitSessionReady(current)
+  ) {
+    return true;
+  }
+
+  return false;
+}
+
+async function writeOutput(path: string, content: string): Promise<void> {
+  const directory = path.includes("/") ? path.slice(0, path.lastIndexOf("/")) : "";
+  if (directory) {
+    await mkdir(directory, { recursive: true });
+  }
+  await writeFile(path, content, "utf8");
+}
+
+async function writeDebugArtifacts(
+  debugDir: string,
+  document: ExtractedDocument,
+  markdown: string,
+  browser: BrowserSession,
+  network: NetworkJournal,
+): Promise<void> {
+  await mkdir(debugDir, { recursive: true });
+
+  const html = await browser.getHTML().catch(() => "");
+  const networkDump = await network.toJSON({ includeBodies: true });
+
+  await Promise.all([
+    writeFile(join(debugDir, "document.json"), JSON.stringify(document, null, 2), "utf8"),
+    writeFile(join(debugDir, "markdown.md"), markdown, "utf8"),
+    writeFile(join(debugDir, "page.html"), html, "utf8"),
+    writeFile(join(debugDir, "network.json"), JSON.stringify(networkDump, null, 2), "utf8"),
+  ]);
+}
+
+async function openRuntime(
+  options: ConvertCommandOptions,
+  interactive: boolean,
+  debugEnabled: boolean,
+): Promise<RuntimeResources> {
+  const logger = createLogger(debugEnabled);
+  if (interactive) {
+    logger.info("Opening Chrome in interactive mode.");
+  }
+  const chrome = await connectChrome({
+    cdpUrl: options.cdpUrl,
+    browserPath: options.browserPath,
+    profileDir: options.chromeProfileDir,
+    headless: interactive ? false : options.headless,
+    logger,
+  });
+
+  const cdp = await CdpClient.connect(chrome.browserWsUrl);
+  const browser = await BrowserSession.open(cdp, { interactive });
+  if (interactive) {
+    await browser.bringToFront().catch(() => {});
+  }
+  const network = new NetworkJournal(browser.targetSession, logger);
+  await network.start();
+
+  return {
+    chrome,
+    cdp,
+    browser,
+    network,
+    interactive,
+  };
+}
+
+async function closeRuntime(runtime: RuntimeResources | null | undefined): Promise<void> {
+  if (!runtime) {
+    return;
+  }
+  runtime.network.stop();
+  await runtime.browser.close().catch(() => {});
+  await runtime.cdp.close().catch(() => {});
+  await runtime.chrome.close().catch(() => {});
+}
+
+async function isInteractionSessionReady(
+  context: AdapterContext,
+  interaction: WaitForInteractionRequest,
+): Promise<boolean> {
+  if (interaction.provider !== "x") {
+    return true;
+  }
+  return await isXSessionReady(context).catch(() => false);
+}
+
+async function reopenInteractiveRuntime(
+  runtime: RuntimeResources,
+  options: ConvertCommandOptions,
+  debugEnabled: boolean,
+): Promise<RuntimeResources> {
+  if (runtime.interactive) {
+    return runtime;
+  }
+
+  await closeRuntime(runtime);
+  return openRuntime(options, true, debugEnabled);
+}
+
+async function captureForceWaitSnapshot(
+  adapter: Adapter,
+  context: AdapterContext,
+): Promise<ForceWaitSnapshot> {
+  const [gate, url, login] = await Promise.all([
+    detectInteractionGate(context.browser).catch(() => null),
+    context.browser.getURL().catch(() => context.input.url.toString()),
+    adapter.checkLogin?.(context).catch(() => ({
+      provider: adapter.name,
+      state: "unknown" as const,
+    })),
+  ]);
+
+  return {
+    url,
+    hasGate: Boolean(gate),
+    loginState: login?.state ?? "unavailable",
+    sessionReady: adapter.name === "x" ? await isXSessionReady(context).catch(() => false) : true,
+  };
+}
+
+async function waitForForceResume(
+  adapter: Adapter,
+  context: AdapterContext,
+  options: ConvertCommandOptions,
+): Promise<void> {
+  if (context.interactive) {
+    await context.browser.bringToFront().catch(() => {});
+  }
+
+  const prompt =
+    "Chrome is ready. Complete any manual login or verification. Extraction will continue automatically after it detects progress, or press Enter to continue immediately.";
+  context.log.info(prompt);
+
+  const rl = createInterface({
+    input: process.stdin,
+    output: process.stderr,
+  });
+
+  let manualContinue = false;
+  let closed = false;
+  const closeReadline = (): void => {
+    if (!closed) {
+      closed = true;
+      rl.close();
+    }
+  };
+
+  rl.once("line", () => {
+    manualContinue = true;
+    closeReadline();
+  });
+
+  const initial = await captureForceWaitSnapshot(adapter, context);
+  const startedAt = Date.now();
+
+  try {
+    while (Date.now() - startedAt < options.interactionTimeoutMs) {
+      if (manualContinue) {
+        return;
+      }
+
+      const current = await captureForceWaitSnapshot(adapter, context);
+      if (shouldAutoContinueForceWait(initial, current)) {
+        return;
+      }
+
+      await sleep(options.interactionPollIntervalMs);
+    }
+  } finally {
+    closeReadline();
+  }
+
+  throw new Error("Timed out waiting for force-mode interaction to complete");
+}
+
+async function waitForInteraction(
+  adapter: Adapter,
+  context: AdapterContext,
+  interaction: WaitForInteractionRequest,
+  options: ConvertCommandOptions,
+): Promise<AdapterLoginInfo> {
+  const timeoutMs = interaction.timeoutMs ?? options.interactionTimeoutMs;
+  const pollIntervalMs = interaction.pollIntervalMs ?? options.interactionPollIntervalMs;
+  if (context.interactive) {
+    await context.browser.bringToFront().catch(() => {});
+  }
+  context.log.info(interaction.prompt);
+
+  const startedAt = Date.now();
+  let lastLogin: AdapterLoginInfo | null = null;
+
+  while (Date.now() - startedAt < timeoutMs) {
+    if (interaction.kind === "login" && adapter.checkLogin) {
+      lastLogin = await adapter.checkLogin(context);
+      if (lastLogin.state === "logged_in" && await isInteractionSessionReady(context, interaction)) {
+        return lastLogin;
+      }
+    }
+
+    const gate = await detectInteractionGate(context.browser);
+    if (!gate) {
+      if (interaction.kind !== "login") {
+        return lastLogin ?? {
+          provider: interaction.provider,
+          state: "unknown",
+          reason: `${interaction.provider} challenge cleared`,
+        };
+      }
+
+      if (!adapter.checkLogin) {
+        return {
+          provider: interaction.provider,
+          state: "unknown",
+        };
+      }
+
+      lastLogin = await adapter.checkLogin(context);
+      if (lastLogin.state !== "logged_out" && await isInteractionSessionReady(context, interaction)) {
+        return lastLogin;
+      }
+    }
+    await sleep(pollIntervalMs);
+  }
+
+  const reason = lastLogin?.reason ? ` (${lastLogin.reason})` : "";
+  throw new Error(`Timed out waiting for ${interaction.provider} interaction${reason}`);
+}
+
+export function formatOutputContent(
+  format: OutputFormat,
+  payload: SuccessfulConvertOutput | InteractionRequiredOutput,
+): string {
+  if (format === "json") {
+    return JSON.stringify(payload, null, 2);
+  }
+
+  if (payload.status !== "ok") {
+    throw new Error("Markdown output is only available for successful extraction results");
+  }
+
+  return payload.markdown;
+}
+
+function printOutput(content: string): void {
+  process.stdout.write(content);
+  if (!content.endsWith("\n")) {
+    process.stdout.write("\n");
+  }
+}
+
+export async function runConvertCommand(options: ConvertCommandOptions): Promise<void> {
+  if (!options.url) {
+    throw new Error("URL is required");
+  }
+  if (options.downloadMedia && !options.output) {
+    throw new Error("--download-media requires --output so media paths can be rewritten relative to the saved output file");
+  }
+
+  const url = normalizeUrl(options.url);
+  let runtime = await openRuntime(options, options.waitMode !== "none", Boolean(options.debugDir));
+  const logger = createLogger(Boolean(options.debugDir));
+  let didLogin = false;
+  let adapter: Adapter | null = null;
+  let context: AdapterContext | null = null;
+
+  try {
+    adapter = resolveAdapter({ url }, options.adapter);
+    context = {
+      input: { url },
+      browser: runtime.browser,
+      network: runtime.network,
+      cdp: runtime.cdp,
+      log: logger,
+      outputFormat: options.format,
+      timeoutMs: options.timeoutMs,
+      interactive: runtime.interactive,
+      downloadMedia: options.downloadMedia,
+    };
+
+    if (adapter.restoreCookies) {
+      const restored = await adapter.restoreCookies(context, runtime.chrome.profileDir).catch(() => false);
+      if (restored) logger.info(`Restored ${adapter.name} session cookies from sidecar.`);
+    }
+
+    if (options.waitMode === "interaction" && adapter.checkLogin) {
+      await context.browser.goto(url.toString(), options.timeoutMs).catch(() => {});
+      const preLogin = await adapter.checkLogin(context);
+      if (preLogin.state !== "logged_in") {
+        didLogin = true;
+        await waitForInteraction(adapter, context, {
+          type: "wait_for_interaction",
+          kind: "login",
+          provider: preLogin.provider ?? adapter.name,
+          prompt: `Please sign in to ${adapter.name === "x" ? "X" : adapter.name} in the opened Chrome window. Extraction will continue automatically once login is detected.`,
+          reason: preLogin.reason ?? `Not logged in to ${adapter.name}`,
+          requiresVisibleBrowser: true,
+        }, options);
+      }
+    }
+
+    if (options.waitMode === "force") {
+      await context.browser.goto(url.toString(), options.timeoutMs).catch(() => {});
+      await waitForForceResume(adapter, context, options);
+    }
+
+    let result = await adapter.process(context);
+
+    if (result.status === "no_document") {
+      const interaction = await detectInteractionGate(context.browser);
+      if (interaction) {
+        result = {
+          status: "needs_interaction",
+          interaction,
+          login: result.login,
+        };
+      }
+    }
+
+    while (result.status === "needs_interaction") {
+      if (options.waitMode === "none") {
+        if (options.format === "json") {
+          printOutput(
+            formatOutputContent(options.format, {
+            adapter: adapter.name,
+            status: result.status,
+            login: result.login,
+            interaction: result.interaction,
+            }),
+          );
+          return;
+        }
+
+        throw new Error(`${adapter.name} requires manual interaction. Re-run with --wait-for interaction to continue after completing it.`);
+      }
+
+      if (result.interaction.requiresVisibleBrowser !== false) {
+        runtime = await reopenInteractiveRuntime(runtime, options, Boolean(options.debugDir));
+      }
+
+      context = {
+        input: { url },
+        browser: runtime.browser,
+        network: runtime.network,
+        cdp: runtime.cdp,
+        log: logger,
+        outputFormat: options.format,
+        timeoutMs: options.timeoutMs,
+        interactive: runtime.interactive,
+        downloadMedia: options.downloadMedia,
+      };
+
+      await context.browser.goto(url.toString(), options.timeoutMs).catch(() => {});
+      if (result.interaction.kind === "login") {
+        didLogin = true;
+      }
+      await waitForInteraction(adapter, context, result.interaction, options);
+      result = await adapter.process(context);
+
+      if (result.status === "no_document") {
+        const interaction = await detectInteractionGate(context.browser);
+        if (interaction) {
+          result = {
+            status: "needs_interaction",
+            interaction,
+            login: result.login,
+          };
+        }
+      }
+    }
+
+    let document: ExtractedDocument | null = result.status === "ok" ? result.document : null;
+    let media: MediaAsset[] = result.status === "ok" ? (result.media ?? []) : [];
+    let login = result.login;
+    let mediaAdapter = adapter;
+
+    if (!document && adapter.name !== genericAdapter.name && result.status === "no_document") {
+      logger.info(`Adapter ${adapter.name} returned no structured document; falling back to generic extraction`);
+      const fallback = await genericAdapter.process(context);
+      if (fallback.status === "ok") {
+        document = fallback.document;
+        media = fallback.media ?? [];
+        mediaAdapter = genericAdapter;
+      }
+    }
+
+    if (!document) {
+      throw new Error("Failed to extract a document from the target URL");
+    }
+
+    document.requestedUrl ??= url.toString();
+
+    let markdown = renderMarkdown(document);
+    let downloadResult:
+      | Awaited<ReturnType<typeof downloadMediaAssets>>
+      | null = null;
+
+    if (options.downloadMedia && options.output) {
+      downloadResult = mediaAdapter.downloadMedia
+        ? await mediaAdapter.downloadMedia({
+            media,
+            outputPath: options.output,
+            mediaDir: options.mediaDir,
+            log: logger,
+          })
+        : await downloadMediaAssets({
+            media,
+            outputPath: options.output,
+            mediaDir: options.mediaDir,
+            log: logger,
+          });
+
+      markdown = rewriteMarkdownMediaLinks(markdown, downloadResult.replacements);
+      if (downloadResult.downloadedImages > 0 || downloadResult.downloadedVideos > 0) {
+        logger.info(
+          `Downloaded ${downloadResult.downloadedImages} images and ${downloadResult.downloadedVideos} videos`,
+        );
+      }
+    }
+
+    if (options.output) {
+      await writeOutput(
+        options.output,
+        formatOutputContent(options.format, {
+          adapter: document.adapter ?? adapter.name,
+          status: "ok",
+          login,
+          media,
+          downloads: downloadResult,
+          document,
+          markdown,
+        }),
+      );
+      logger.info(`Saved ${options.format} to ${options.output}`);
+    }
+
+    if (options.debugDir) {
+      await writeDebugArtifacts(options.debugDir, document, markdown, runtime.browser, runtime.network);
+      logger.info(`Wrote debug artifacts to ${options.debugDir}`);
+    }
+
+    if (options.format === "json") {
+      printOutput(
+        formatOutputContent(options.format, {
+        adapter: document.adapter ?? adapter.name,
+        status: "ok",
+        login,
+        media,
+        downloads: downloadResult,
+        document,
+        markdown,
+        }),
+      );
+      return;
+    }
+
+    printOutput(markdown);
+  } finally {
+    if (adapter?.exportCookies && context) {
+      await adapter.exportCookies(context, runtime.chrome.profileDir).catch(() => {});
+    }
+    await closeRuntime(runtime);
+  }
+}

packages/baoyu-fetch/src/extract/document.ts

@@ -0,0 +1,51 @@
+export type ContentBlock =
+  | {
+      type: "paragraph";
+      text: string;
+    }
+  | {
+      type: "heading";
+      depth: number;
+      text: string;
+    }
+  | {
+      type: "list";
+      ordered: boolean;
+      items: string[];
+    }
+  | {
+      type: "quote";
+      text: string;
+    }
+  | {
+      type: "code";
+      code: string;
+      language?: string;
+    }
+  | {
+      type: "image";
+      url: string;
+      alt?: string;
+    }
+  | {
+      type: "html";
+      html: string;
+    }
+  | {
+      type: "markdown";
+      markdown: string;
+    };
+
+export interface ExtractedDocument {
+  url: string;
+  requestedUrl?: string;
+  canonicalUrl?: string;
+  title?: string;
+  author?: string;
+  siteName?: string;
+  publishedAt?: string;
+  summary?: string;
+  content: ContentBlock[];
+  metadata?: Record<string, unknown>;
+  adapter?: string;
+}

packages/baoyu-fetch/src/extract/html-cleaner.ts

@@ -0,0 +1,467 @@
+import { JSDOM } from "jsdom";
+
+export interface CleanHtmlOptions {
+  removeAds?: boolean;
+  removeBase64Images?: boolean;
+  onlyMainContent?: boolean;
+  includeSelectors?: string[];
+  excludeSelectors?: string[];
+}
+
+const ALWAYS_REMOVE_SELECTORS = [
+  "script",
+  "style",
+  "noscript",
+  "link[rel='stylesheet']",
+  "[hidden]",
+  "[aria-hidden='true']",
+  "[style*='display: none']",
+  "[style*='display:none']",
+  "[style*='visibility: hidden']",
+  "[style*='visibility:hidden']",
+  "svg[aria-hidden='true']",
+  "svg.icon",
+  "svg[class*='icon']",
+  "template",
+  "meta",
+  "iframe",
+  "canvas",
+  "object",
+  "embed",
+  "form",
+  "input",
+  "select",
+  "textarea",
+  "button",
+];
+
+const OVERLAY_SELECTORS = [
+  "[class*='modal']",
+  "[class*='popup']",
+  "[class*='overlay']",
+  "[class*='dialog']",
+  "[role='dialog']",
+  "[role='alertdialog']",
+  "[class*='cookie']",
+  "[class*='consent']",
+  "[class*='gdpr']",
+  "[class*='privacy-banner']",
+  "[class*='notification-bar']",
+  "[id*='cookie']",
+  "[id*='consent']",
+  "[id*='gdpr']",
+  "[style*='position: fixed']",
+  "[style*='position:fixed']",
+  "[style*='position: sticky']",
+  "[style*='position:sticky']",
+];
+
+const NAVIGATION_SELECTORS = [
+  "header",
+  "footer",
+  "nav",
+  "aside",
+  ".header",
+  ".top",
+  ".navbar",
+  "#header",
+  ".footer",
+  ".bottom",
+  "#footer",
+  ".sidebar",
+  ".side",
+  ".aside",
+  "#sidebar",
+  ".modal",
+  ".popup",
+  "#modal",
+  ".overlay",
+  ".ad",
+  ".ads",
+  ".advert",
+  "#ad",
+  ".lang-selector",
+  ".language",
+  "#language-selector",
+  ".social",
+  ".social-media",
+  ".social-links",
+  "#social",
+  ".menu",
+  ".navigation",
+  "#nav",
+  ".breadcrumbs",
+  "#breadcrumbs",
+  ".share",
+  "#share",
+  ".widget",
+  "#widget",
+  ".cookie",
+  "#cookie",
+];
+
+const FORCE_INCLUDE_SELECTORS = [
+  "#main",
+  "#content",
+  "#main-content",
+  "#article",
+  "#post",
+  "#page-content",
+  "main",
+  "article",
+  "[role='main']",
+  ".main-content",
+  ".content",
+  ".post-content",
+  ".article-content",
+  ".entry-content",
+  ".page-content",
+  ".article-body",
+  ".post-body",
+  ".story-content",
+  ".blog-content",
+];
+
+const AD_SELECTORS = [
+  "ins.adsbygoogle",
+  ".google-ad",
+  ".adsense",
+  "[data-ad]",
+  "[data-ads]",
+  "[data-ad-slot]",
+  "[data-ad-client]",
+  ".ad-container",
+  ".ad-wrapper",
+  ".advertisement",
+  ".sponsored-content",
+  "img[width='1'][height='1']",
+  "img[src*='pixel']",
+  "img[src*='tracking']",
+  "img[src*='analytics']",
+];
+
+function getLinkDensity(element: Element): number {
+  const text = element.textContent || "";
+  const textLength = text.trim().length;
+  if (textLength === 0) {
+    return 1;
+  }
+
+  let linkLength = 0;
+  element.querySelectorAll("a").forEach((link) => {
+    linkLength += (link.textContent || "").trim().length;
+  });
+
+  return linkLength / textLength;
+}
+
+function getContentScore(element: Element): number {
+  let score = 0;
+  const text = element.textContent || "";
+  const textLength = text.trim().length;
+
+  score += Math.min(textLength / 100, 50);
+  score += element.querySelectorAll("p").length * 3;
+  score += element.querySelectorAll("h1, h2, h3, h4, h5, h6").length * 2;
+  score += element.querySelectorAll("img").length;
+
+  score -= element.querySelectorAll("a").length * 0.5;
+  score -= element.querySelectorAll("li").length * 0.2;
+
+  const linkDensity = getLinkDensity(element);
+  if (linkDensity > 0.5) {
+    score -= 30;
+  } else if (linkDensity > 0.3) {
+    score -= 15;
+  }
+
+  const className = typeof element.className === "string" ? element.className : "";
+  const classAndId = `${className} ${element.id || ""}`;
+  if (/article|content|post|body|main|entry/i.test(classAndId)) {
+    score += 25;
+  }
+  if (/comment|sidebar|footer|nav|menu|header|widget|ad/i.test(classAndId)) {
+    score -= 25;
+  }
+
+  return score;
+}
+
+function looksLikeNavigation(element: Element): boolean {
+  const linkDensity = getLinkDensity(element);
+  if (linkDensity > 0.5) {
+    return true;
+  }
+
+  const listItems = element.querySelectorAll("li");
+  const links = element.querySelectorAll("a");
+  return listItems.length > 5 && links.length > listItems.length * 0.8;
+}
+
+function removeElements(document: Document, selectors: string[]): void {
+  for (const selector of selectors) {
+    try {
+      document.querySelectorAll(selector).forEach((element) => element.remove());
+    } catch {
+      // Ignore unsupported selectors.
+    }
+  }
+}
+
+function removeWithProtection(
+  document: Document,
+  selectorsToRemove: string[],
+  protectedSelectors: string[],
+): void {
+  for (const selector of selectorsToRemove) {
+    try {
+      document.querySelectorAll(selector).forEach((element) => {
+        const isProtected = protectedSelectors.some((protectedSelector) => {
+          try {
+            return element.matches(protectedSelector);
+          } catch {
+            return false;
+          }
+        });
+
+        if (isProtected) {
+          return;
+        }
+
+        const containsProtected = protectedSelectors.some((protectedSelector) => {
+          try {
+            return element.querySelector(protectedSelector) !== null;
+          } catch {
+            return false;
+          }
+        });
+
+        if (containsProtected) {
+          return;
+        }
+
+        element.remove();
+      });
+    } catch {
+      // Ignore unsupported selectors.
+    }
+  }
+}
+
+function isValidContent(element: Element | null): element is Element {
+  if (!element) {
+    return false;
+  }
+  const text = element.textContent || "";
+  if (text.trim().length < 100) {
+    return false;
+  }
+  return !looksLikeNavigation(element);
+}
+
+function findMainContent(document: Document): Element | null {
+  const main = document.querySelector("main");
+  if (isValidContent(main) && getLinkDensity(main) < 0.4) {
+    return main;
+  }
+
+  const roleMain = document.querySelector('[role="main"]');
+  if (isValidContent(roleMain) && getLinkDensity(roleMain) < 0.4) {
+    return roleMain;
+  }
+
+  const articles = document.querySelectorAll("article");
+  if (articles.length === 1 && isValidContent(articles[0] ?? null)) {
+    return articles[0] ?? null;
+  }
+
+  const contentSelectors = [
+    "#content",
+    "#main-content",
+    "#main",
+    ".content",
+    ".main-content",
+    ".post-content",
+    ".article-content",
+    ".entry-content",
+    ".page-content",
+    ".article-body",
+    ".post-body",
+    ".story-content",
+    ".blog-content",
+  ];
+
+  for (const selector of contentSelectors) {
+    try {
+      const element = document.querySelector(selector);
+      if (isValidContent(element) && getLinkDensity(element) < 0.4) {
+        return element;
+      }
+    } catch {
+      // Ignore invalid selectors.
+    }
+  }
+
+  const candidates: Array<{ element: Element; score: number }> = [];
+  document.querySelectorAll("div, section, article").forEach((element) => {
+    const text = element.textContent || "";
+    if (text.trim().length < 200) {
+      return;
+    }
+
+    const score = getContentScore(element);
+    if (score > 0) {
+      candidates.push({ element, score });
+    }
+  });
+
+  candidates.sort((left, right) => right.score - left.score);
+  if ((candidates[0]?.score ?? 0) > 20) {
+    return candidates[0]?.element ?? null;
+  }
+
+  return null;
+}
+
+function removeBase64ImagesFromDocument(document: Document): void {
+  document.querySelectorAll("img[src^='data:']").forEach((element) => element.remove());
+
+  document.querySelectorAll("[style*='data:image']").forEach((element) => {
+    const style = element.getAttribute("style");
+    if (!style) {
+      return;
+    }
+
+    const cleanedStyle = style.replace(
+      /background(-image)?:\s*url\([^)]*data:image[^)]*\)[^;]*;?/gi,
+      "",
+    );
+
+    if (cleanedStyle.trim()) {
+      element.setAttribute("style", cleanedStyle);
+    } else {
+      element.removeAttribute("style");
+    }
+  });
+
+  document
+    .querySelectorAll("source[src^='data:'], source[srcset*='data:']")
+    .forEach((element) => element.remove());
+}
+
+function makeAbsoluteUrl(value: string, baseUrl: string): string | null {
+  try {
+    return new URL(value, baseUrl).toString();
+  } catch {
+    return null;
+  }
+}
+
+function convertRelativeUrls(document: Document, baseUrl: string): void {
+  document.querySelectorAll("[src]").forEach((element) => {
+    const src = element.getAttribute("src");
+    if (!src || src.startsWith("http") || src.startsWith("//") || src.startsWith("data:")) {
+      return;
+    }
+
+    const absolute = makeAbsoluteUrl(src, baseUrl);
+    if (absolute) {
+      element.setAttribute("src", absolute);
+    }
+  });
+
+  document.querySelectorAll("[href]").forEach((element) => {
+    const href = element.getAttribute("href");
+    if (
+      !href ||
+      href.startsWith("http") ||
+      href.startsWith("//") ||
+      href.startsWith("#") ||
+      href.startsWith("mailto:") ||
+      href.startsWith("tel:") ||
+      href.startsWith("javascript:")
+    ) {
+      return;
+    }
+
+    const absolute = makeAbsoluteUrl(href, baseUrl);
+    if (absolute) {
+      element.setAttribute("href", absolute);
+    }
+  });
+}
+
+function removeComments(document: Document): void {
+  const walker = document.createTreeWalker(document, document.defaultView?.NodeFilter.SHOW_COMMENT ?? 128);
+  const comments: Comment[] = [];
+  while (walker.nextNode()) {
+    comments.push(walker.currentNode as Comment);
+  }
+  comments.forEach((comment) => comment.parentNode?.removeChild(comment));
+}
+
+export function cleanHtml(
+  html: string,
+  baseUrl: string,
+  options: CleanHtmlOptions = {},
+): string {
+  const {
+    removeAds = true,
+    removeBase64Images = true,
+    onlyMainContent = true,
+    includeSelectors,
+    excludeSelectors,
+  } = options;
+
+  const dom = new JSDOM(html, { url: baseUrl });
+  const { document } = dom.window;
+
+  removeElements(document, ALWAYS_REMOVE_SELECTORS);
+  removeElements(document, OVERLAY_SELECTORS);
+
+  if (removeAds) {
+    removeElements(document, AD_SELECTORS);
+  }
+
+  if (excludeSelectors?.length) {
+    removeElements(document, excludeSelectors);
+  }
+
+  if (onlyMainContent) {
+    removeWithProtection(document, NAVIGATION_SELECTORS, FORCE_INCLUDE_SELECTORS);
+
+    const mainContent = findMainContent(document);
+    if (mainContent && document.body) {
+      const clone = mainContent.cloneNode(true);
+      document.body.innerHTML = "";
+      document.body.appendChild(clone);
+    }
+  }
+
+  if (includeSelectors?.length && document.body) {
+    const matchedElements: Element[] = [];
+    for (const selector of includeSelectors) {
+      try {
+        document.querySelectorAll(selector).forEach((element) => {
+          matchedElements.push(element.cloneNode(true) as Element);
+        });
+      } catch {
+        // Ignore invalid selectors.
+      }
+    }
+
+    if (matchedElements.length > 0) {
+      document.body.innerHTML = "";
+      matchedElements.forEach((element) => document.body?.appendChild(element));
+    }
+  }
+
+  if (removeBase64Images) {
+    removeBase64ImagesFromDocument(document);
+  }
+
+  removeComments(document);
+  convertRelativeUrls(document, baseUrl);
+
+  return document.documentElement.outerHTML || html;
+}

packages/baoyu-fetch/src/extract/html-extractor.ts

@@ -0,0 +1,83 @@
+import { Readability } from "@mozilla/readability";
+import { JSDOM } from "jsdom";
+import type { ExtractedDocument } from "./document";
+
+function getMetaContent(document: Document, selectors: string[]): string | undefined {
+  for (const selector of selectors) {
+    const value = document.querySelector(selector)?.getAttribute("content")?.trim();
+    if (value) {
+      return value;
+    }
+  }
+  return undefined;
+}
+
+export function extractDocumentFromHtml(input: {
+  url: string;
+  html: string;
+  adapter?: string;
+}): ExtractedDocument {
+  const dom = new JSDOM(input.html, { url: input.url });
+  const document = dom.window.document;
+
+  const canonicalUrl =
+    document.querySelector('link[rel="canonical"]')?.getAttribute("href")?.trim() ??
+    getMetaContent(document, ['meta[property="og:url"]']);
+
+  const siteName = getMetaContent(document, [
+    'meta[property="og:site_name"]',
+    'meta[name="application-name"]',
+  ]);
+
+  const metadataAuthor = getMetaContent(document, [
+    'meta[name="author"]',
+    'meta[property="article:author"]',
+    'meta[name="twitter:creator"]',
+  ]);
+
+  const publishedAt = getMetaContent(document, [
+    'meta[property="article:published_time"]',
+    'meta[name="pubdate"]',
+    'meta[name="date"]',
+    'meta[itemprop="datePublished"]',
+  ]);
+
+  const article = new Readability(document).parse();
+  const title =
+    article?.title?.trim() ||
+    getMetaContent(document, ['meta[property="og:title"]']) ||
+    document.title.trim() ||
+    undefined;
+
+  const summary =
+    article?.excerpt?.trim() ||
+    getMetaContent(document, [
+      'meta[name="description"]',
+      'meta[property="og:description"]',
+      'meta[name="twitter:description"]',
+    ]);
+
+  const contentHtml =
+    article?.content?.trim() ||
+    document.querySelector("main")?.innerHTML?.trim() ||
+    document.body?.innerHTML?.trim() ||
+    "";
+
+  const author = article?.byline?.trim() || metadataAuthor;
+
+  return {
+    url: input.url,
+    canonicalUrl,
+    title,
+    author,
+    siteName,
+    publishedAt,
+    summary,
+    adapter: input.adapter ?? "generic",
+    metadata: {
+      language: document.documentElement.lang || undefined,
+    },
+    content: contentHtml ? [{ type: "html", html: contentHtml }] : [],
+  };
+}
+

packages/baoyu-fetch/src/extract/html-to-markdown.ts

@@ -0,0 +1,758 @@
+import { Readability } from "@mozilla/readability";
+import { Defuddle } from "defuddle/node";
+import { JSDOM, VirtualConsole } from "jsdom";
+import TurndownService from "turndown";
+import { gfm } from "turndown-plugin-gfm";
+import { collectMediaFromMarkdown } from "../media/markdown-media";
+import type { MediaAsset } from "../media/types";
+import { cleanHtml } from "./html-cleaner";
+
+export interface HtmlConversionMetadata {
+  url: string;
+  canonicalUrl?: string;
+  siteName?: string;
+  title?: string;
+  summary?: string;
+  author?: string;
+  publishedAt?: string;
+  coverImage?: string;
+  language?: string;
+  capturedAt: string;
+}
+
+export interface ConvertHtmlToMarkdownOptions {
+  enableRemoteMarkdownFallback?: boolean;
+  preserveBase64Images?: boolean;
+}
+
+export interface HtmlToMarkdownResult {
+  metadata: HtmlConversionMetadata;
+  markdown: string;
+  rawHtml: string;
+  cleanedHtml: string;
+  media: MediaAsset[];
+  conversionMethod: string;
+  fallbackReason?: string;
+}
+
+type JsonObject = Record<string, unknown>;
+
+const MIN_CONTENT_LENGTH = 120;
+const DEFUDDLE_API_ORIGIN = "https://defuddle.md";
+const LOCAL_FALLBACK_SCORE_DELTA = 120;
+const REMOTE_FALLBACK_SCORE_DELTA = 20;
+const LOW_QUALITY_MARKERS = [
+  /Join The Conversation/i,
+  /One Community\. Many Voices/i,
+  /Read our community guidelines/i,
+  /Create a free account to share your thoughts/i,
+  /Become a Forbes Member/i,
+  /Subscribe to trusted journalism/i,
+  /\bComments\b/i,
+];
+
+const ARTICLE_TYPES = new Set([
+  "Article",
+  "NewsArticle",
+  "BlogPosting",
+  "WebPage",
+  "ReportageNewsArticle",
+]);
+
+const turndown = new TurndownService({
+  headingStyle: "atx",
+  bulletListMarker: "-",
+  codeBlockStyle: "fenced",
+}) as TurndownService & {
+  remove(selectors: string[]): void;
+  addRule(
+    key: string,
+    rule: {
+      filter: string | ((node: Node) => boolean);
+      replacement: (content: string) => string;
+    },
+  ): void;
+};
+
+turndown.use(gfm);
+turndown.remove(["script", "style", "iframe", "noscript", "template", "svg", "path"]);
+turndown.addRule("collapseFigure", {
+  filter: "figure",
+  replacement(content: string) {
+    return `\n\n${content.trim()}\n\n`;
+  },
+});
+turndown.addRule("dropInvisibleAnchors", {
+  filter(node: Node) {
+    return (
+      node.nodeName === "A" &&
+      !(node as Element).textContent?.trim() &&
+      !(node as Element).querySelector("img, video, picture, source")
+    );
+  },
+  replacement() {
+    return "";
+  },
+});
+
+function pickString(...values: unknown[]): string | undefined {
+  for (const value of values) {
+    if (typeof value !== "string") {
+      continue;
+    }
+    const trimmed = value.trim();
+    if (trimmed) {
+      return trimmed;
+    }
+  }
+  return undefined;
+}
+
+function normalizeMarkdown(markdown: string): string {
+  return markdown
+    .replace(/\r\n/g, "\n")
+    .replace(/[ \t]+\n/g, "\n")
+    .replace(/\n{3,}/g, "\n\n")
+    .trim();
+}
+
+function stripWrappingQuotes(value: string): string {
+  const trimmed = value.trim();
+  if (
+    (trimmed.startsWith('"') && trimmed.endsWith('"')) ||
+    (trimmed.startsWith("'") && trimmed.endsWith("'"))
+  ) {
+    return trimmed.slice(1, -1).trim();
+  }
+  return trimmed;
+}
+
+function stripMarkdownFrontmatter(markdown: string): string {
+  return markdown.replace(/^\uFEFF?---\n[\s\S]*?\n---(?:\n|$)/, "").trim();
+}
+
+function cleanMarkdownTitle(value: string): string | undefined {
+  const cleaned = stripWrappingQuotes(
+    value
+      .replace(/\s+#+\s*$/, "")
+      .replace(/!\[[^\]]*\]\([^)]+\)/g, "")
+      .replace(/\[([^\]]+)\]\([^)]+\)/g, "$1")
+      .replace(/[*_`~]/g, "")
+      .trim(),
+  );
+
+  return cleaned || undefined;
+}
+
+export function extractTitleFromMarkdownDocument(markdown: string): string | undefined {
+  const normalized = markdown.replace(/\r\n/g, "\n").trim();
+  if (!normalized) {
+    return undefined;
+  }
+
+  const frontmatterMatch = normalized.match(/^\uFEFF?---\n([\s\S]*?)\n---(?:\n|$)/);
+  if (frontmatterMatch) {
+    for (const line of frontmatterMatch[1].split("\n")) {
+      const match = line.match(/^title:\s*(.+?)\s*$/i);
+      if (!match) {
+        continue;
+      }
+
+      const title = cleanMarkdownTitle(match[1]);
+      if (title) {
+        return title;
+      }
+    }
+  }
+
+  const body = stripMarkdownFrontmatter(normalized);
+  const headingMatch = body.match(/^#{1,6}\s+(.+)$/m);
+  if (!headingMatch) {
+    return undefined;
+  }
+
+  return cleanMarkdownTitle(headingMatch[1]);
+}
+
+function trimKnownBoilerplate(markdown: string): string {
+  const normalized = normalizeMarkdown(markdown);
+  const lines = normalized.split("\n");
+
+  while (lines.length > 0) {
+    const lastLine = lines[lines.length - 1]?.trim();
+    if (!lastLine) {
+      lines.pop();
+      continue;
+    }
+
+    if (/^继续滑动看下一个$/.test(lastLine) || /^轻触阅读原文$/.test(lastLine)) {
+      lines.pop();
+      continue;
+    }
+
+    break;
+  }
+
+  return normalizeMarkdown(lines.join("\n"));
+}
+
+function buildDefuddleApiUrl(targetUrl: string): string {
+  return `${DEFUDDLE_API_ORIGIN}/${encodeURIComponent(targetUrl)}`;
+}
+
+async function fetchDefuddleApiMarkdown(
+  targetUrl: string,
+): Promise<{ markdown: string; title?: string }> {
+  const response = await fetch(buildDefuddleApiUrl(targetUrl), {
+    headers: {
+      accept: "text/markdown,text/plain;q=0.9,*/*;q=0.1",
+    },
+    redirect: "follow",
+  });
+
+  if (!response.ok) {
+    throw new Error(`defuddle.md returned ${response.status} ${response.statusText}`);
+  }
+
+  const rawMarkdown = (await response.text()).replace(/\r\n/g, "\n").trim();
+  if (!rawMarkdown) {
+    throw new Error("defuddle.md returned empty markdown");
+  }
+
+  const title = extractTitleFromMarkdownDocument(rawMarkdown);
+  const markdown = trimKnownBoilerplate(stripMarkdownFrontmatter(rawMarkdown));
+  if (!markdown) {
+    throw new Error("defuddle.md returned empty markdown");
+  }
+
+  return {
+    markdown,
+    title,
+  };
+}
+
+function sanitizeHtmlFragment(html: string): string {
+  const dom = new JSDOM(`<div id="__root">${html}</div>`);
+  const root = dom.window.document.querySelector("#__root");
+  if (!root) {
+    return html;
+  }
+
+  for (const selector of ["script", "style", "iframe", "noscript", "template", "svg", "path"]) {
+    root.querySelectorAll(selector).forEach((element) => element.remove());
+  }
+
+  return root.innerHTML;
+}
+
+function extractTextFromHtml(html: string): string {
+  const dom = new JSDOM(`<!doctype html><html><body>${html}</body></html>`);
+  const { document } = dom.window;
+  for (const selector of ["script", "style", "noscript", "template", "iframe", "svg", "path"]) {
+    document.querySelectorAll(selector).forEach((element) => element.remove());
+  }
+  return document.body?.textContent?.replace(/\s+/g, " ").trim() ?? "";
+}
+
+function getMetaContent(document: Document, names: string[]): string | undefined {
+  for (const name of names) {
+    const element =
+      document.querySelector(`meta[name="${name}"]`) ??
+      document.querySelector(`meta[property="${name}"]`);
+    const content = element?.getAttribute("content")?.trim();
+    if (content) {
+      return content;
+    }
+  }
+  return undefined;
+}
+
+function normalizeLanguageTag(value: string | null | undefined): string | undefined {
+  if (!value) {
+    return undefined;
+  }
+
+  const trimmed = value.trim();
+  if (!trimmed) {
+    return undefined;
+  }
+
+  const primary = trimmed.split(/[,\s;]/, 1)[0]?.trim();
+  if (!primary) {
+    return undefined;
+  }
+
+  return primary.replace(/_/g, "-");
+}
+
+function flattenJsonLdItems(data: unknown): JsonObject[] {
+  if (!data || typeof data !== "object") {
+    return [];
+  }
+
+  if (Array.isArray(data)) {
+    return data.flatMap(flattenJsonLdItems);
+  }
+
+  const item = data as JsonObject;
+  if (Array.isArray(item["@graph"])) {
+    return (item["@graph"] as unknown[]).flatMap(flattenJsonLdItems);
+  }
+
+  return [item];
+}
+
+function parseJsonLdScripts(document: Document): JsonObject[] {
+  const results: JsonObject[] = [];
+  document.querySelectorAll("script[type='application/ld+json']").forEach((script) => {
+    try {
+      const data = JSON.parse(script.textContent ?? "");
+      results.push(...flattenJsonLdItems(data));
+    } catch {
+      // Ignore malformed json-ld blocks.
+    }
+  });
+  return results;
+}
+
+function extractAuthorFromJsonLd(authorData: unknown): string | undefined {
+  if (typeof authorData === "string") {
+    return authorData.trim() || undefined;
+  }
+
+  if (!authorData || typeof authorData !== "object") {
+    return undefined;
+  }
+
+  if (Array.isArray(authorData)) {
+    return authorData
+      .map((author) => extractAuthorFromJsonLd(author))
+      .filter((value): value is string => Boolean(value))
+      .join(", ") || undefined;
+  }
+
+  const author = authorData as JsonObject;
+  return pickString(author.name);
+}
+
+function extractPrimaryJsonLdMeta(document: Document): Partial<HtmlConversionMetadata> {
+  for (const item of parseJsonLdScripts(document)) {
+    const type = Array.isArray(item["@type"]) ? item["@type"][0] : item["@type"];
+    if (typeof type !== "string" || !ARTICLE_TYPES.has(type)) {
+      continue;
+    }
+
+    return {
+      title: pickString(item.headline, item.name),
+      summary: pickString(item.description),
+      author: extractAuthorFromJsonLd(item.author),
+      publishedAt: pickString(item.datePublished, item.dateCreated),
+      coverImage: pickString(
+        item.image,
+        (item.image as JsonObject | undefined)?.url,
+        Array.isArray(item.image) ? item.image[0] : undefined,
+      ),
+    };
+  }
+
+  return {};
+}
+
+function extractPageMetadata(
+  html: string,
+  url: string,
+  capturedAt: string,
+): HtmlConversionMetadata {
+  const dom = new JSDOM(html, { url });
+  const { document } = dom.window;
+  const jsonLd = extractPrimaryJsonLdMeta(document);
+
+  return {
+    url,
+    canonicalUrl:
+      document.querySelector('link[rel="canonical"]')?.getAttribute("href")?.trim() ??
+      getMetaContent(document, ["og:url"]),
+    siteName: pickString(
+      getMetaContent(document, ["og:site_name"]),
+      document.querySelector('meta[name="application-name"]')?.getAttribute("content"),
+    ),
+    title: pickString(
+      getMetaContent(document, ["og:title", "twitter:title"]),
+      jsonLd.title,
+      document.querySelector("h1")?.textContent,
+      document.title,
+    ),
+    summary: pickString(
+      getMetaContent(document, ["description", "og:description", "twitter:description"]),
+      jsonLd.summary,
+    ),
+    author: pickString(
+      getMetaContent(document, ["author", "article:author", "twitter:creator"]),
+      jsonLd.author,
+    ),
+    publishedAt: pickString(
+      document.querySelector("time[datetime]")?.getAttribute("datetime"),
+      getMetaContent(document, ["article:published_time", "datePublished", "publishdate", "date"]),
+      jsonLd.publishedAt,
+    ),
+    coverImage: pickString(
+      getMetaContent(document, ["og:image", "twitter:image", "twitter:image:src"]),
+      jsonLd.coverImage,
+    ),
+    language: pickString(
+      normalizeLanguageTag(document.documentElement.getAttribute("lang")),
+      normalizeLanguageTag(
+        pickString(
+          getMetaContent(document, ["language", "content-language", "og:locale"]),
+          document.querySelector("meta[http-equiv='content-language']")?.getAttribute("content"),
+        ),
+      ),
+    ),
+    capturedAt,
+  };
+}
+
+function isMarkdownUsable(markdown: string, html: string): boolean {
+  const normalized = normalizeMarkdown(markdown);
+  if (!normalized) {
+    return false;
+  }
+
+  const htmlTextLength = extractTextFromHtml(html).length;
+  if (htmlTextLength < MIN_CONTENT_LENGTH) {
+    return true;
+  }
+
+  if (normalized.length >= 80) {
+    return true;
+  }
+
+  return normalized.length >= Math.min(200, Math.floor(htmlTextLength * 0.2));
+}
+
+function countMarkerHits(markdown: string, markers: RegExp[]): number {
+  let hits = 0;
+  for (const marker of markers) {
+    if (marker.test(markdown)) {
+      hits += 1;
+    }
+  }
+  return hits;
+}
+
+function countUsefulParagraphs(markdown: string): number {
+  const paragraphs = normalizeMarkdown(markdown).split(/\n{2,}/);
+  let count = 0;
+
+  for (const paragraph of paragraphs) {
+    const trimmed = paragraph.trim();
+    if (!trimmed) {
+      continue;
+    }
+    if (/^!?\[[^\]]*\]\([^)]+\)$/.test(trimmed)) {
+      continue;
+    }
+    if (/^#{1,6}\s+/.test(trimmed)) {
+      continue;
+    }
+    if ((trimmed.match(/\b[\p{L}\p{N}']+\b/gu) || []).length < 8) {
+      continue;
+    }
+    count += 1;
+  }
+
+  return count;
+}
+
+function scoreMarkdownQuality(markdown: string): number {
+  const normalized = normalizeMarkdown(markdown);
+  const wordCount = (normalized.match(/\b[\p{L}\p{N}']+\b/gu) || []).length;
+  const usefulParagraphs = countUsefulParagraphs(normalized);
+  const headingCount = (normalized.match(/^#{1,6}\s+/gm) || []).length;
+  const markerHits = countMarkerHits(normalized, LOW_QUALITY_MARKERS);
+  return Math.min(wordCount, 4000) + usefulParagraphs * 40 + headingCount * 10 - markerHits * 180;
+}
+
+function shouldCompareWithFallback(markdown: string): boolean {
+  const normalized = normalizeMarkdown(markdown);
+  return countMarkerHits(normalized, LOW_QUALITY_MARKERS) > 0 || countUsefulParagraphs(normalized) < 6;
+}
+
+function hasMeaningfulMarkdownStructure(markdown: string): boolean {
+  const normalized = normalizeMarkdown(markdown);
+  if (!normalized) {
+    return false;
+  }
+
+  return (
+    countUsefulParagraphs(normalized) > 0 ||
+    /^#{1,6}\s+/m.test(normalized) ||
+    /^[-*]\s+/m.test(normalized) ||
+    /^\d+\.\s+/m.test(normalized) ||
+    /!\[[^\]]*\]\([^)]+\)/.test(normalized)
+  );
+}
+
+function shouldTryRemoteMarkdownFallback(
+  markdown: string,
+  html: string,
+  options: ConvertHtmlToMarkdownOptions,
+): boolean {
+  if (!options.enableRemoteMarkdownFallback) {
+    return false;
+  }
+
+  return !isMarkdownUsable(markdown, html) || shouldCompareWithFallback(markdown);
+}
+
+function shouldPreferRemoteMarkdown(
+  current: HtmlToMarkdownResult,
+  remote: HtmlToMarkdownResult,
+  html: string,
+): boolean {
+  if (!isMarkdownUsable(current.markdown, html)) {
+    return true;
+  }
+
+  if (!hasMeaningfulMarkdownStructure(current.markdown) && hasMeaningfulMarkdownStructure(remote.markdown)) {
+    return true;
+  }
+
+  return scoreMarkdownQuality(remote.markdown) > scoreMarkdownQuality(current.markdown) + REMOTE_FALLBACK_SCORE_DELTA;
+}
+
+function buildRemoteFallbackReason(current: HtmlToMarkdownResult, html: string): string {
+  if (!isMarkdownUsable(current.markdown, html)) {
+    return current.fallbackReason
+      ? `Used defuddle.md markdown fallback after local extraction failed: ${current.fallbackReason}`
+      : "Used defuddle.md markdown fallback after local extraction returned empty or incomplete markdown";
+  }
+
+  return "defuddle.md produced higher-quality markdown than local extraction";
+}
+
+async function tryDefuddleConversion(
+  html: string,
+  url: string,
+  baseMetadata: HtmlConversionMetadata,
+): Promise<{ ok: true; result: HtmlToMarkdownResult } | { ok: false; reason: string }> {
+  try {
+    const virtualConsole = new VirtualConsole();
+    virtualConsole.on("jsdomError", (error: Error & { type?: string }) => {
+      if (error.type === "css parsing" || /Could not parse CSS stylesheet/i.test(error.message)) {
+        return;
+      }
+    });
+
+    const dom = new JSDOM(html, { url, virtualConsole });
+    const result = await Defuddle(dom, url, { markdown: true });
+    const markdown = trimKnownBoilerplate(result.content || "");
+
+    if (!isMarkdownUsable(markdown, html)) {
+      return { ok: false, reason: "Defuddle returned empty or incomplete markdown" };
+    }
+
+    const metadata: HtmlConversionMetadata = {
+      ...baseMetadata,
+      title: pickString(result.title, baseMetadata.title),
+      summary: pickString(result.description, baseMetadata.summary),
+      author: pickString(result.author, baseMetadata.author),
+      publishedAt: pickString(result.published, baseMetadata.publishedAt),
+      coverImage: pickString(result.image, baseMetadata.coverImage),
+      language: pickString(result.language, baseMetadata.language),
+    };
+
+    return {
+      ok: true,
+      result: {
+        metadata,
+        markdown,
+        rawHtml: html,
+        cleanedHtml: html,
+        media: collectMediaFromMarkdown(markdown).concat(
+          metadata.coverImage
+            ? [{ url: metadata.coverImage, kind: "image", role: "cover" as const }]
+            : [],
+        ),
+        conversionMethod: "defuddle",
+      },
+    };
+  } catch (error) {
+    return {
+      ok: false,
+      reason: error instanceof Error ? error.message : String(error),
+    };
+  }
+}
+
+async function tryDefuddleApiConversion(
+  html: string,
+  url: string,
+  baseMetadata: HtmlConversionMetadata,
+): Promise<{ ok: true; result: HtmlToMarkdownResult } | { ok: false; reason: string }> {
+  try {
+    const result = await fetchDefuddleApiMarkdown(url);
+    const markdown = result.markdown;
+
+    if (!isMarkdownUsable(markdown, html) && scoreMarkdownQuality(markdown) < 80) {
+      return { ok: false, reason: "defuddle.md returned empty or incomplete markdown" };
+    }
+
+    const metadata: HtmlConversionMetadata = {
+      ...baseMetadata,
+      title: pickString(result.title, baseMetadata.title),
+    };
+
+    return {
+      ok: true,
+      result: {
+        metadata,
+        markdown,
+        rawHtml: html,
+        cleanedHtml: html,
+        media: collectMediaFromMarkdown(markdown).concat(
+          metadata.coverImage
+            ? [{ url: metadata.coverImage, kind: "image", role: "cover" as const }]
+            : [],
+        ),
+        conversionMethod: "defuddle-api",
+      },
+    };
+  } catch (error) {
+    return {
+      ok: false,
+      reason: error instanceof Error ? error.message : String(error),
+    };
+  }
+}
+
+function convertHtmlFragmentToMarkdown(html: string): string {
+  if (!html.trim()) {
+    return "";
+  }
+
+  try {
+    return turndown.turndown(sanitizeHtmlFragment(html));
+  } catch {
+    return "";
+  }
+}
+
+function fallbackPlainText(html: string): string {
+  return trimKnownBoilerplate(extractTextFromHtml(html));
+}
+
+function convertWithReadability(
+  rawHtml: string,
+  cleanedHtml: string,
+  url: string,
+  baseMetadata: HtmlConversionMetadata,
+): HtmlToMarkdownResult {
+  const dom = new JSDOM(cleanedHtml, { url });
+  const document = dom.window.document;
+  const article = new Readability(document).parse();
+
+  const contentHtml =
+    article?.content?.trim() ??
+    document.querySelector("main")?.innerHTML?.trim() ??
+    document.body?.innerHTML?.trim() ??
+    "";
+
+  let markdown = contentHtml ? convertHtmlFragmentToMarkdown(contentHtml) : "";
+  if (!markdown) {
+    markdown = fallbackPlainText(cleanedHtml);
+  }
+
+  const metadata: HtmlConversionMetadata = {
+    ...baseMetadata,
+    title: pickString(article?.title, baseMetadata.title),
+    summary: pickString(article?.excerpt, baseMetadata.summary),
+    author: pickString(article?.byline, baseMetadata.author),
+  };
+
+  const media = collectMediaFromMarkdown(markdown);
+  if (metadata.coverImage) {
+    media.unshift({
+      url: metadata.coverImage,
+      kind: "image",
+      role: "cover",
+    });
+  }
+
+  return {
+    metadata,
+    markdown: trimKnownBoilerplate(markdown),
+    rawHtml,
+    cleanedHtml,
+    media,
+    conversionMethod: article?.content ? "legacy:readability" : "legacy:body",
+  };
+}
+
+export async function convertHtmlToMarkdown(
+  html: string,
+  url: string,
+  options: ConvertHtmlToMarkdownOptions = {},
+): Promise<HtmlToMarkdownResult> {
+  const capturedAt = new Date().toISOString();
+  const baseMetadata = extractPageMetadata(html, url, capturedAt);
+
+  let cleanedHtml = html;
+  try {
+    cleanedHtml = cleanHtml(html, url, {
+      removeBase64Images: !options.preserveBase64Images,
+    });
+  } catch {
+    cleanedHtml = html;
+  }
+
+  let selectedResult: HtmlToMarkdownResult;
+  const defuddleResult = await tryDefuddleConversion(cleanedHtml, url, baseMetadata);
+  if (defuddleResult.ok) {
+    if (shouldCompareWithFallback(defuddleResult.result.markdown)) {
+      const fallbackResult = convertWithReadability(html, cleanedHtml, url, baseMetadata);
+      if (
+        scoreMarkdownQuality(fallbackResult.markdown) >
+        scoreMarkdownQuality(defuddleResult.result.markdown) + LOCAL_FALLBACK_SCORE_DELTA
+      ) {
+        selectedResult = {
+          ...fallbackResult,
+          fallbackReason: "Readability/Turndown produced higher-quality markdown than Defuddle",
+        };
+      } else {
+        selectedResult = {
+          ...defuddleResult.result,
+          rawHtml: html,
+          cleanedHtml,
+        };
+      }
+    } else {
+      selectedResult = {
+        ...defuddleResult.result,
+        rawHtml: html,
+        cleanedHtml,
+      };
+    }
+  } else {
+    selectedResult = {
+      ...convertWithReadability(html, cleanedHtml, url, baseMetadata),
+      fallbackReason: defuddleResult.reason,
+    };
+  }
+
+  if (!shouldTryRemoteMarkdownFallback(selectedResult.markdown, cleanedHtml, options)) {
+    return selectedResult;
+  }
+
+  const remoteDefuddleResult = await tryDefuddleApiConversion(cleanedHtml, url, baseMetadata);
+  if (!remoteDefuddleResult.ok || !shouldPreferRemoteMarkdown(selectedResult, remoteDefuddleResult.result, cleanedHtml)) {
+    return selectedResult;
+  }
+
+  return {
+    ...remoteDefuddleResult.result,
+    rawHtml: html,
+    cleanedHtml,
+    fallbackReason: buildRemoteFallbackReason(selectedResult, cleanedHtml),
+  };
+}

packages/baoyu-fetch/src/extract/markdown-renderer.ts

@@ -0,0 +1,169 @@
+import TurndownService from "turndown";
+import { gfm } from "turndown-plugin-gfm";
+import { normalizeMarkdownMediaLinks } from "../media/markdown-media";
+import type { ContentBlock, ExtractedDocument } from "./document";
+
+const turndownService = new TurndownService({
+  codeBlockStyle: "fenced",
+  headingStyle: "atx",
+  bulletListMarker: "-",
+});
+
+turndownService.use(gfm);
+
+function renderBlock(block: ContentBlock): string {
+  switch (block.type) {
+    case "paragraph":
+      return block.text.trim();
+    case "heading":
+      return `${"#".repeat(Math.min(Math.max(block.depth, 1), 6))} ${block.text.trim()}`;
+    case "list":
+      return block.items
+        .map((item, index) => (block.ordered ? `${index + 1}. ${item.trim()}` : `- ${item.trim()}`))
+        .join("\n");
+    case "quote":
+      return block.text
+        .split("\n")
+        .map((line) => `> ${line}`)
+        .join("\n");
+    case "code":
+      return `\`\`\`${block.language ?? ""}\n${block.code.trimEnd()}\n\`\`\``;
+    case "image":
+      return `![${block.alt ?? ""}](${block.url})`;
+    case "html":
+      return turndownService.turndown(block.html).trim();
+    case "markdown":
+      return block.markdown.trim();
+  }
+}
+
+function isDefinedValue(value: unknown): boolean {
+  return value !== undefined && value !== null && value !== "";
+}
+
+function renderFrontmatterValue(value: unknown): string {
+  if (typeof value === "string") {
+    if (value.includes("\n")) {
+      return `|-\n${value
+        .replace(/\r\n/g, "\n")
+        .split("\n")
+        .map((line) => `  ${line}`)
+        .join("\n")}`;
+    }
+    return JSON.stringify(value);
+  }
+  if (typeof value === "number" || typeof value === "boolean") {
+    return String(value);
+  }
+  return JSON.stringify(value);
+}
+
+function renderFrontmatter(document: ExtractedDocument): string {
+  const fields = new Map<string, unknown>();
+  const preferredOrder = [
+    "title",
+    "url",
+    "requestedUrl",
+    "author",
+    "authorName",
+    "authorUsername",
+    "authorUrl",
+    "coverImage",
+    "siteName",
+    "publishedAt",
+    "summary",
+    "adapter",
+  ];
+
+  fields.set("title", document.title);
+  fields.set("url", document.canonicalUrl ?? document.url);
+  fields.set("requestedUrl", document.requestedUrl ?? document.url);
+  fields.set("author", document.author);
+  fields.set("siteName", document.siteName);
+  fields.set("publishedAt", document.publishedAt);
+  fields.set("summary", document.summary);
+  fields.set("adapter", document.adapter);
+
+  for (const [key, value] of Object.entries(document.metadata ?? {})) {
+    if (!fields.has(key)) {
+      fields.set(key, value);
+    }
+  }
+
+  const orderedKeys = [
+    ...preferredOrder.filter((key) => fields.has(key)),
+    ...Array.from(fields.keys()).filter((key) => !preferredOrder.includes(key)).sort(),
+  ];
+
+  const lines = orderedKeys
+    .map((key) => [key, fields.get(key)] as const)
+    .filter(([, value]) => isDefinedValue(value))
+    .map(([key, value]) => `${key}: ${renderFrontmatterValue(value)}`);
+
+  if (lines.length === 0) {
+    return "";
+  }
+
+  return `---\n${lines.join("\n")}\n---`;
+}
+
+function cleanMarkdown(markdown: string): string {
+  return normalizeMarkdownMediaLinks(markdown.replace(/\n{3,}/g, "\n\n").trim());
+}
+
+function normalizeComparableTitle(value: string): string {
+  return value
+    .trim()
+    .toLowerCase()
+    .replace(/^>\s*/, "")
+    .replace(/^#+\s+/, "")
+    .replace(/(?:\.{3}|…)\s*$/, "");
+}
+
+function bodyStartsWithTitle(body: string, title: string): boolean {
+  const firstMeaningfulLine = body
+    .replace(/\r\n/g, "\n")
+    .split("\n")
+    .map((line) => line.trim())
+    .find((line) => line && !/^!?\[[^\]]*\]\([^)]+\)$/.test(line));
+
+  if (!firstMeaningfulLine) {
+    return false;
+  }
+
+  const comparableTitle = normalizeComparableTitle(title);
+  const comparableFirstLine = normalizeComparableTitle(firstMeaningfulLine);
+  if (!comparableTitle || !comparableFirstLine) {
+    return false;
+  }
+
+  return (
+    comparableFirstLine === comparableTitle ||
+    comparableFirstLine.startsWith(comparableTitle) ||
+    comparableTitle.startsWith(comparableFirstLine)
+  );
+}
+
+export function renderMarkdown(document: ExtractedDocument): string {
+  const sections: string[] = [];
+  const frontmatter = renderFrontmatter(document);
+
+  if (frontmatter) {
+    sections.push(frontmatter);
+  }
+
+  const body = document.content
+    .map((block) => renderBlock(block))
+    .filter(Boolean)
+    .join("\n\n");
+
+  if (document.title && !bodyStartsWithTitle(body, document.title)) {
+    sections.push(`# ${document.title}`);
+  }
+
+  if (body) {
+    sections.push(body);
+  }
+
+  return cleanMarkdown(sections.join("\n\n"));
+}

packages/baoyu-fetch/src/media/default-downloader.ts

@@ -0,0 +1,161 @@
+import path from "node:path";
+import { mkdir, writeFile } from "node:fs/promises";
+import {
+  buildFileName,
+  isDataUri,
+  normalizeContentType,
+  normalizeMediaUrl,
+  resolveExtensionFromContentType,
+  resolveExtensionFromUrl,
+  resolveMediaKind,
+  resolveOutputExtension,
+  toPosixPath,
+} from "./media-utils";
+import type { MediaAsset, MediaDownloadRequest, MediaDownloadResult, MediaKind } from "./types";
+
+const DOWNLOAD_USER_AGENT =
+  "Mozilla/5.0 (Macintosh; Intel Mac OS X 10_15_7) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/130.0.0.0 Safari/537.36";
+
+function parseBase64DataUri(rawUrl: string): { contentType: string; bytes: Buffer } | null {
+  const match = rawUrl.match(/^data:([^;,]+);base64,([A-Za-z0-9+/=\s]+)$/i);
+  if (!match?.[1] || !match[2]) {
+    return null;
+  }
+
+  const contentType = normalizeContentType(match[1]);
+  if (!contentType) {
+    return null;
+  }
+
+  try {
+    const bytes = Buffer.from(match[2].replace(/\s+/g, ""), "base64");
+    if (bytes.length === 0) {
+      return null;
+    }
+    return { contentType, bytes };
+  } catch {
+    return null;
+  }
+}
+
+function dedupeMedia(media: MediaAsset[]): MediaAsset[] {
+  const deduped: MediaAsset[] = [];
+  const seen = new Set<string>();
+  for (const item of media) {
+    const normalizedUrl = normalizeMediaUrl(item.url);
+    if (!normalizedUrl || seen.has(normalizedUrl)) {
+      continue;
+    }
+    seen.add(normalizedUrl);
+    deduped.push({
+      ...item,
+      url: normalizedUrl,
+    });
+  }
+  return deduped;
+}
+
+function toRelativePath(fromDir: string, absoluteTarget: string): string {
+  const relative = path.relative(fromDir, absoluteTarget) || path.basename(absoluteTarget);
+  return toPosixPath(relative);
+}
+
+export async function downloadMediaAssets(
+  request: MediaDownloadRequest,
+): Promise<MediaDownloadResult> {
+  const dedupedMedia = dedupeMedia(request.media);
+  const absoluteOutputPath = path.resolve(request.outputPath);
+  const markdownDir = path.dirname(absoluteOutputPath);
+  const baseDir = request.mediaDir ? path.resolve(request.mediaDir) : markdownDir;
+  const replacements: MediaDownloadResult["replacements"] = [];
+
+  let downloadedImages = 0;
+  let downloadedVideos = 0;
+
+  for (const asset of dedupedMedia) {
+    try {
+      let sourceUrl = normalizeMediaUrl(asset.url);
+      let contentType = "";
+      let extension: string | undefined;
+      let kind: MediaKind | undefined;
+      let bytes: Buffer | null = null;
+
+      if (isDataUri(asset.url)) {
+        const parsed = parseBase64DataUri(asset.url);
+        if (!parsed) {
+          request.log.warn(`Skipping unsupported embedded media: ${asset.url.slice(0, 32)}...`);
+          continue;
+        }
+
+        contentType = parsed.contentType;
+        extension =
+          resolveExtensionFromContentType(contentType) ??
+          resolveExtensionFromUrl(asset.fileNameHint ?? "");
+        kind = resolveMediaKind(sourceUrl, contentType, extension, asset.kind);
+        bytes = parsed.bytes;
+      } else {
+        const response = await fetch(sourceUrl, {
+          method: "GET",
+          redirect: "follow",
+          headers: {
+            "user-agent": DOWNLOAD_USER_AGENT,
+            ...(asset.headers ?? {}),
+          },
+        });
+
+        if (!response.ok) {
+          request.log.warn(`Skipping media (${response.status}): ${asset.url}`);
+          continue;
+        }
+
+        sourceUrl = normalizeMediaUrl(response.url || sourceUrl);
+        contentType = normalizeContentType(response.headers.get("content-type"));
+        extension =
+          resolveExtensionFromUrl(sourceUrl) ??
+          resolveExtensionFromUrl(asset.url) ??
+          resolveExtensionFromUrl(asset.fileNameHint ?? "");
+        kind = resolveMediaKind(sourceUrl, contentType, extension, asset.kind);
+        bytes = Buffer.from(await response.arrayBuffer());
+      }
+
+      if (!kind || !bytes) {
+        request.log.debug(`Skipping media with unresolved kind: ${asset.url}`);
+        continue;
+      }
+
+      const outputExtension = resolveOutputExtension(contentType, extension, kind);
+      const nextIndex = kind === "image" ? downloadedImages + 1 : downloadedVideos + 1;
+      const dirName = kind === "image" ? "imgs" : "videos";
+      const targetDir = path.join(baseDir, dirName);
+      await mkdir(targetDir, { recursive: true });
+
+      const fileName = buildFileName(kind, nextIndex, sourceUrl, outputExtension, asset.fileNameHint);
+      const absolutePath = path.join(targetDir, fileName);
+      await writeFile(absolutePath, bytes);
+
+      replacements.push({
+        url: asset.url,
+        localPath: toRelativePath(markdownDir, absolutePath),
+        absolutePath,
+        kind,
+      });
+
+      if (kind === "image") {
+        downloadedImages = nextIndex;
+      } else {
+        downloadedVideos = nextIndex;
+      }
+    } catch (error) {
+      const message = error instanceof Error ? error.message : String(error);
+      request.log.warn(`Failed to download media ${asset.url}: ${message}`);
+    }
+  }
+
+  return {
+    replacements,
+    downloadedImages,
+    downloadedVideos,
+    imageDir: downloadedImages > 0 ? path.join(baseDir, "imgs") : null,
+    videoDir: downloadedVideos > 0 ? path.join(baseDir, "videos") : null,
+  };
+}

packages/baoyu-fetch/src/media/markdown-media.ts

@@ -0,0 +1,458 @@
+import remarkGfm from "remark-gfm";
+import remarkParse from "remark-parse";
+import { unified } from "unified";
+import type { ContentBlock, ExtractedDocument } from "../extract/document";
+import {
+  isDataUri,
+  normalizeContentType,
+  normalizeMediaUrl,
+  resolveExtensionFromContentType,
+  resolveExtensionFromUrl,
+  resolveKindFromExtension,
+} from "./media-utils";
+import type { MediaAsset, MediaReplacement } from "./types";
+
+const MARKDOWN_LINK_RE =
+  /(!?\[[^\]\n]*\])\((<)?((?:https?:\/\/[^)\s>]+)|(?:data:[^)>\s]+))(>)?\)/g;
+const FRONTMATTER_COVER_RE = /^(coverImage:\s*")((?:https?:\/\/[^"]+)|(?:data:[^"]+))(")/m;
+const RAW_URL_RE = /(?:https?:\/\/[^\s<>"')\]]+|data:[^\s<>"')\]]+)/g;
+
+interface MarkdownAstNode {
+  type: string;
+  url?: string | null;
+  alt?: string | null;
+  title?: string | null;
+  value?: string | null;
+  children?: MarkdownAstNode[];
+  position?: {
+    start?: { offset?: number | null };
+    end?: { offset?: number | null };
+  };
+}
+
+interface MarkdownReplacementRange {
+  start: number;
+  end: number;
+  value: string;
+}
+
+function inferMediaKindFromLabel(label: string, rawUrl: string): "image" | "video" | undefined {
+  if (label.startsWith("![")) {
+    return "image";
+  }
+
+  const normalizedLabel = label.replace(/[!\[\]]/g, "").trim().toLowerCase();
+  if (/\b(video|animated[_ -]?gif|gif)\b/.test(normalizedLabel)) {
+    return "video";
+  }
+
+  if (isDataUri(rawUrl)) {
+    const contentType = normalizeContentType(rawUrl.slice(5, rawUrl.indexOf(";")));
+    return contentType.startsWith("image/") ? "image" : contentType.startsWith("video/") ? "video" : undefined;
+  }
+
+  return resolveKindFromExtension(resolveExtensionFromUrl(rawUrl));
+}
+
+function inferMediaKindFromRawUrl(rawUrl: string): "image" | "video" | undefined {
+  if (isDataUri(rawUrl)) {
+    const contentType = normalizeContentType(rawUrl.slice(5, rawUrl.indexOf(";")));
+    return contentType.startsWith("image/") ? "image" : contentType.startsWith("video/") ? "video" : undefined;
+  }
+
+  return resolveKindFromExtension(resolveExtensionFromUrl(rawUrl));
+}
+
+function pushMedia(assets: MediaAsset[], seen: Set<string>, media: MediaAsset): void {
+  const normalizedUrl = normalizeMediaUrl(media.url);
+  if (!normalizedUrl || seen.has(normalizedUrl)) {
+    return;
+  }
+  seen.add(normalizedUrl);
+  assets.push({
+    ...media,
+    url: normalizedUrl,
+  });
+}
+
+function getNodeOffsets(node: MarkdownAstNode): { start: number; end: number } | null {
+  const start = node.position?.start?.offset;
+  const end = node.position?.end?.offset;
+  if (typeof start !== "number" || typeof end !== "number" || start < 0 || end < start) {
+    return null;
+  }
+  return { start, end };
+}
+
+function escapeMarkdownLabel(value: string): string {
+  return value.replace(/\\/g, "\\\\").replace(/\[/g, "\\[").replace(/\]/g, "\\]");
+}
+
+function escapeMarkdownTitle(value: string): string {
+  return value.replace(/\\/g, "\\\\").replace(/"/g, '\\"');
+}
+
+function formatMarkdownDestination(url: string): string {
+  return /[\s()<>]/.test(url) ? `<${url}>` : url;
+}
+
+function serializeImageNode(node: MarkdownAstNode): string {
+  const rawUrl = node.url ?? "";
+  const normalizedUrl = normalizeMediaUrl(rawUrl);
+  const alt = escapeMarkdownLabel(node.alt ?? "");
+  const title = node.title ? ` "${escapeMarkdownTitle(node.title)}"` : "";
+  return `![${alt}](${formatMarkdownDestination(normalizedUrl)}${title})`;
+}
+
+function serializeLinkedImageNode(linkNode: MarkdownAstNode, imageNode: MarkdownAstNode): string {
+  const imageMarkdown = serializeImageNode(imageNode);
+  const imageUrl = normalizeMediaUrl(imageNode.url ?? "");
+  const linkUrl = normalizeMediaUrl(linkNode.url ?? "");
+
+  if (!linkUrl || linkUrl === imageUrl) {
+    return imageMarkdown;
+  }
+
+  const title = linkNode.title ? ` "${escapeMarkdownTitle(linkNode.title)}"` : "";
+  return `[${imageMarkdown}](${formatMarkdownDestination(linkUrl)}${title})`;
+}
+
+function isParagraphWithSingleText(node: MarkdownAstNode | undefined, expectedValue: string): boolean {
+  if (node?.type !== "paragraph" || node.children?.length !== 1) {
+    return false;
+  }
+
+  const child = node.children[0];
+  return child?.type === "text" && child.value?.trim() === expectedValue;
+}
+
+function getSingleImageFromParagraph(node: MarkdownAstNode | undefined): MarkdownAstNode | null {
+  if (node?.type !== "paragraph" || node.children?.length !== 1) {
+    return null;
+  }
+
+  return node.children[0]?.type === "image" ? node.children[0] : null;
+}
+
+function extractBrokenLinkedImageDestination(node: MarkdownAstNode | undefined): string | null {
+  if (node?.type !== "paragraph") {
+    return null;
+  }
+
+  const children = node.children ?? [];
+  if (children.length !== 3) {
+    return null;
+  }
+
+  const [prefix, linkNode, suffix] = children;
+  if (prefix?.type !== "text" || prefix.value?.trim() !== "](") {
+    return null;
+  }
+  if (linkNode?.type !== "link" || !linkNode.url) {
+    return null;
+  }
+  if (suffix?.type !== "text" || suffix.value?.trim() !== ")") {
+    return null;
+  }
+
+  return linkNode.url;
+}
+
+function collectLinkedImageReplacements(
+  node: MarkdownAstNode,
+  replacements: MarkdownReplacementRange[],
+): void {
+  const children = node.children ?? [];
+
+  if (node.type === "link" && children.length === 1 && children[0]?.type === "image") {
+    const offsets = getNodeOffsets(node);
+    if (offsets) {
+      replacements.push({
+        start: offsets.start,
+        end: offsets.end,
+        value: serializeLinkedImageNode(node, children[0]),
+      });
+    }
+    return;
+  }
+
+  for (const child of children) {
+    collectLinkedImageReplacements(child, replacements);
+  }
+}
+
+function collectBrokenLinkedImageReplacements(
+  node: MarkdownAstNode,
+  replacements: MarkdownReplacementRange[],
+): void {
+  const children = node.children ?? [];
+  for (let index = 0; index <= children.length - 3; index += 1) {
+    const openParagraph = children[index];
+    const imageParagraph = children[index + 1];
+    const closeParagraph = children[index + 2];
+
+    if (!isParagraphWithSingleText(openParagraph, "[")) {
+      continue;
+    }
+
+    const imageNode = getSingleImageFromParagraph(imageParagraph);
+    if (!imageNode) {
+      continue;
+    }
+
+    const linkUrl = extractBrokenLinkedImageDestination(closeParagraph);
+    if (!linkUrl) {
+      continue;
+    }
+
+    const start = openParagraph.position?.start?.offset;
+    const end = closeParagraph.position?.end?.offset;
+    if (typeof start !== "number" || typeof end !== "number" || end < start) {
+      continue;
+    }
+
+    replacements.push({
+      start,
+      end,
+      value: serializeLinkedImageNode({ type: "link", url: linkUrl }, imageNode),
+    });
+
+    index += 2;
+  }
+
+  for (const child of children) {
+    collectBrokenLinkedImageReplacements(child, replacements);
+  }
+}
+
+function applyReplacements(source: string, replacements: MarkdownReplacementRange[]): string {
+  if (replacements.length === 0) {
+    return source;
+  }
+
+  let result = source;
+  const sorted = [...replacements].sort((left, right) => right.start - left.start);
+  for (const replacement of sorted) {
+    result = `${result.slice(0, replacement.start)}${replacement.value}${result.slice(replacement.end)}`;
+  }
+  return result;
+}
+
+function normalizeLinkedImageMarkdown(markdown: string): string {
+  let tree: MarkdownAstNode;
+  try {
+    tree = unified().use(remarkParse).use(remarkGfm).parse(markdown) as MarkdownAstNode;
+  } catch {
+    return markdown;
+  }
+
+  const replacements: MarkdownReplacementRange[] = [];
+  collectLinkedImageReplacements(tree, replacements);
+  collectBrokenLinkedImageReplacements(tree, replacements);
+  return applyReplacements(markdown, replacements);
+}
+
+export function normalizeMarkdownMediaLinks(markdown: string): string {
+  MARKDOWN_LINK_RE.lastIndex = 0;
+  let result = markdown.replace(MARKDOWN_LINK_RE, (full, label, openAngle, rawUrl, closeAngle) => {
+    const normalizedUrl = normalizeMediaUrl(rawUrl);
+    if (normalizedUrl === rawUrl) {
+      return full;
+    }
+    return `${label}(${openAngle ?? ""}${normalizedUrl}${closeAngle ?? ""})`;
+  });
+
+  result = result.replace(FRONTMATTER_COVER_RE, (full, prefix, rawUrl, suffix) => {
+    const normalizedUrl = normalizeMediaUrl(rawUrl);
+    if (normalizedUrl === rawUrl) {
+      return full;
+    }
+    return `${prefix}${normalizedUrl}${suffix}`;
+  });
+
+  RAW_URL_RE.lastIndex = 0;
+  result = result.replace(RAW_URL_RE, (rawUrl) => normalizeMediaUrl(rawUrl));
+  return normalizeLinkedImageMarkdown(result);
+}
+
+export function collectMediaFromText(
+  text: string,
+  options: {
+    role?: MediaAsset["role"];
+    defaultKind?: MediaAsset["kind"];
+    seen?: Set<string>;
+    into?: MediaAsset[];
+  } = {},
+): MediaAsset[] {
+  const assets = options.into ?? [];
+  const seen = options.seen ?? new Set<string>();
+
+  MARKDOWN_LINK_RE.lastIndex = 0;
+  let linkMatch: RegExpExecArray | null;
+  while ((linkMatch = MARKDOWN_LINK_RE.exec(text))) {
+    const label = linkMatch[1] ?? "";
+    const rawUrl = linkMatch[3] ?? "";
+    const kind = inferMediaKindFromLabel(label, rawUrl) ?? options.defaultKind;
+    if (!kind) {
+      continue;
+    }
+    pushMedia(assets, seen, {
+      url: rawUrl,
+      kind,
+      role: options.role ?? "inline",
+    });
+  }
+
+  RAW_URL_RE.lastIndex = 0;
+  let rawMatch: RegExpExecArray | null;
+  while ((rawMatch = RAW_URL_RE.exec(text))) {
+    const rawUrl = rawMatch[0] ?? "";
+    const kind = inferMediaKindFromRawUrl(rawUrl) ?? options.defaultKind;
+    if (!kind) {
+      continue;
+    }
+    pushMedia(assets, seen, {
+      url: rawUrl,
+      kind,
+      role: options.role ?? "inline",
+    });
+  }
+
+  return assets;
+}
+
+function collectMediaFromBlock(
+  block: ContentBlock,
+  assets: MediaAsset[],
+  seen: Set<string>,
+): void {
+  switch (block.type) {
+    case "image":
+      pushMedia(assets, seen, {
+        url: block.url,
+        kind: "image",
+        role: "inline",
+        alt: block.alt,
+      });
+      return;
+    case "html":
+    case "markdown":
+      collectMediaFromText(block.type === "html" ? block.html : block.markdown, {
+        role: "inline",
+        seen,
+        into: assets,
+      });
+      return;
+    case "paragraph":
+    case "quote":
+      collectMediaFromText(block.text, {
+        role: "inline",
+        seen,
+        into: assets,
+      });
+      return;
+    case "list":
+      for (const item of block.items) {
+        collectMediaFromText(item, {
+          role: "attachment",
+          seen,
+          into: assets,
+        });
+      }
+      return;
+    case "heading":
+    case "code":
+      return;
+  }
+}
+
+export function collectMediaFromDocument(document: ExtractedDocument): MediaAsset[] {
+  const assets: MediaAsset[] = [];
+  const seen = new Set<string>();
+  const coverImage =
+    typeof document.metadata?.coverImage === "string" ? document.metadata.coverImage : undefined;
+
+  if (coverImage) {
+    pushMedia(assets, seen, {
+      url: coverImage,
+      kind: "image",
+      role: "cover",
+    });
+  }
+
+  for (const block of document.content) {
+    collectMediaFromBlock(block, assets, seen);
+  }
+
+  return assets;
+}
+
+export function collectMediaFromMarkdown(markdown: string): MediaAsset[] {
+  const assets: MediaAsset[] = [];
+  const seen = new Set<string>();
+  const fmMatch = markdown.match(/^---\n([\s\S]*?)\n---/);
+  if (fmMatch) {
+    const coverMatch = fmMatch[1]?.match(FRONTMATTER_COVER_RE);
+    if (coverMatch?.[2]) {
+      pushMedia(assets, seen, {
+        url: coverMatch[2],
+        kind: "image",
+        role: "cover",
+      });
+    }
+  }
+
+  collectMediaFromText(markdown, { seen, into: assets });
+  return assets;
+}
+
+export function rewriteMarkdownMediaLinks(
+  markdown: string,
+  replacements: MediaReplacement[],
+): string {
+  if (replacements.length === 0) {
+    return markdown;
+  }
+
+  const replacementMap = new Map<string, string>();
+  for (const item of replacements) {
+    replacementMap.set(item.url, item.localPath);
+    replacementMap.set(normalizeMediaUrl(item.url), item.localPath);
+  }
+
+  MARKDOWN_LINK_RE.lastIndex = 0;
+  let result = markdown.replace(MARKDOWN_LINK_RE, (full, label, _openAngle, rawUrl) => {
+    const replacement = replacementMap.get(rawUrl) ?? replacementMap.get(normalizeMediaUrl(rawUrl));
+    if (!replacement) {
+      return full;
+    }
+    return `${label}(${replacement})`;
+  });
+
+  result = result.replace(FRONTMATTER_COVER_RE, (full, prefix, rawUrl, suffix) => {
+    const replacement = replacementMap.get(rawUrl) ?? replacementMap.get(normalizeMediaUrl(rawUrl));
+    if (!replacement) {
+      return full;
+    }
+    return `${prefix}${replacement}${suffix}`;
+  });
+
+  for (const { url, localPath } of replacements) {
+    result = result.split(url).join(localPath);
+    const normalizedUrl = normalizeMediaUrl(url);
+    if (normalizedUrl !== url) {
+      result = result.split(normalizedUrl).join(localPath);
+    }
+  }
+
+  return result;
+}
+
+export function resolveDataUriExtension(rawUrl: string): string | undefined {
+  if (!isDataUri(rawUrl)) {
+    return undefined;
+  }
+  const separatorIndex = rawUrl.indexOf(";");
+  const contentType = normalizeContentType(rawUrl.slice(5, separatorIndex === -1 ? undefined : separatorIndex));
+  return resolveExtensionFromContentType(contentType);
+}

packages/baoyu-fetch/src/media/media-utils.ts

@@ -0,0 +1,261 @@
+import path from "node:path";
+import type { MediaKind } from "./types";
+
+const IMAGE_EXTENSIONS = new Set([
+  "jpg",
+  "jpeg",
+  "png",
+  "webp",
+  "gif",
+  "bmp",
+  "avif",
+  "heic",
+  "heif",
+  "svg",
+]);
+
+const VIDEO_EXTENSIONS = new Set(["mp4", "m4v", "mov", "webm", "mkv"]);
+
+const MIME_EXTENSION_MAP: Record<string, string> = {
+  "image/jpeg": "jpg",
+  "image/jpg": "jpg",
+  "image/png": "png",
+  "image/webp": "webp",
+  "image/gif": "gif",
+  "image/bmp": "bmp",
+  "image/avif": "avif",
+  "image/heic": "heic",
+  "image/heif": "heif",
+  "image/svg+xml": "svg",
+  "video/mp4": "mp4",
+  "video/webm": "webm",
+  "video/quicktime": "mov",
+  "video/x-m4v": "m4v",
+};
+
+export function normalizeContentType(raw: string | null): string {
+  return raw?.split(";")[0]?.trim().toLowerCase() ?? "";
+}
+
+export function normalizeExtension(raw: string | undefined | null): string | undefined {
+  if (!raw) {
+    return undefined;
+  }
+  const trimmed = raw.replace(/^\./, "").trim().toLowerCase();
+  if (!trimmed) {
+    return undefined;
+  }
+  if (trimmed === "jpeg" || trimmed === "jpg") {
+    return "jpg";
+  }
+  return trimmed;
+}
+
+export function resolveExtensionFromUrl(rawUrl: string): string | undefined {
+  try {
+    const parsed = new URL(rawUrl);
+    const extFromPath = normalizeExtension(path.posix.extname(parsed.pathname));
+    if (extFromPath) {
+      return extFromPath;
+    }
+    const extFromFormat = normalizeExtension(parsed.searchParams.get("format"));
+    if (extFromFormat) {
+      return extFromFormat;
+    }
+  } catch {
+    return undefined;
+  }
+  return undefined;
+}
+
+export function resolveExtensionFromContentType(contentType: string): string | undefined {
+  return normalizeExtension(MIME_EXTENSION_MAP[contentType]);
+}
+
+export function resolveKindFromContentType(contentType: string): MediaKind | undefined {
+  if (!contentType) {
+    return undefined;
+  }
+  if (contentType.startsWith("image/")) {
+    return "image";
+  }
+  if (contentType.startsWith("video/")) {
+    return "video";
+  }
+  return undefined;
+}
+
+export function resolveKindFromExtension(extension: string | undefined): MediaKind | undefined {
+  if (!extension) {
+    return undefined;
+  }
+  if (IMAGE_EXTENSIONS.has(extension)) {
+    return "image";
+  }
+  if (VIDEO_EXTENSIONS.has(extension)) {
+    return "video";
+  }
+  return undefined;
+}
+
+export function resolveMediaKind(
+  rawUrl: string,
+  contentType: string,
+  extension: string | undefined,
+  hint?: MediaKind,
+): MediaKind | undefined {
+  const kindFromType = resolveKindFromContentType(contentType);
+  if (kindFromType) {
+    return kindFromType;
+  }
+
+  const kindFromExtension = resolveKindFromExtension(extension);
+  if (kindFromExtension) {
+    return kindFromExtension;
+  }
+
+  if (contentType && contentType !== "application/octet-stream") {
+    return undefined;
+  }
+
+  if (hint) {
+    return hint;
+  }
+
+  if (rawUrl.startsWith("data:image/")) {
+    return "image";
+  }
+
+  if (rawUrl.startsWith("data:video/")) {
+    return "video";
+  }
+
+  return undefined;
+}
+
+export function resolveOutputExtension(
+  contentType: string,
+  extension: string | undefined,
+  kind: MediaKind,
+): string {
+  const fromMime = resolveExtensionFromContentType(contentType);
+  if (fromMime) {
+    return fromMime;
+  }
+  const normalized = normalizeExtension(extension);
+  if (normalized) {
+    return normalized;
+  }
+  return kind === "video" ? "mp4" : "jpg";
+}
+
+export function isDataUri(value: string): boolean {
+  return value.startsWith("data:");
+}
+
+export function safeDecodeURIComponent(value: string): string {
+  try {
+    return decodeURIComponent(value);
+  } catch {
+    return value;
+  }
+}
+
+function extractEmbeddedUrl(value: string): string | undefined {
+  const encodedMatch = value.match(/https?%3A%2F%2F.+$/i)?.[0];
+  if (encodedMatch) {
+    const decoded = safeDecodeURIComponent(encodedMatch);
+    try {
+      return new URL(decoded).href;
+    } catch {
+      return undefined;
+    }
+  }
+
+  const literalMatch = value.match(/https?:\/\/.+$/i)?.[0];
+  if (!literalMatch) {
+    return undefined;
+  }
+
+  try {
+    return new URL(literalMatch).href;
+  } catch {
+    return undefined;
+  }
+}
+
+export function normalizeMediaUrl(rawUrl: string): string {
+  if (isDataUri(rawUrl)) {
+    return rawUrl;
+  }
+
+  try {
+    const parsed = new URL(rawUrl);
+    const hostname = parsed.hostname.toLowerCase();
+
+    if (hostname === "substackcdn.com" || hostname.endsWith(".substackcdn.com")) {
+      const embeddedUrl = extractEmbeddedUrl(`${parsed.pathname}${parsed.search}`);
+      if (embeddedUrl) {
+        return embeddedUrl;
+      }
+    }
+
+    return parsed.href;
+  } catch {
+    return rawUrl;
+  }
+}
+
+export function sanitizeFileSegment(input: string): string {
+  return input
+    .replace(/[^a-zA-Z0-9_-]+/g, "-")
+    .replace(/-+/g, "-")
+    .replace(/^[-_]+|[-_]+$/g, "")
+    .slice(0, 48);
+}
+
+export function resolveFileStem(rawUrl: string, extension: string, fileNameHint?: string): string {
+  const hintBase = fileNameHint?.trim();
+  if (hintBase) {
+    const parsed = path.posix.parse(hintBase);
+    const stem = parsed.name || parsed.base;
+    return sanitizeFileSegment(stem);
+  }
+
+  if (isDataUri(rawUrl)) {
+    return "";
+  }
+
+  try {
+    const parsed = new URL(rawUrl);
+    const base = path.posix.basename(parsed.pathname);
+    if (!base) {
+      return "";
+    }
+    const decodedBase = safeDecodeURIComponent(base);
+    const normalizedExtension = normalizeExtension(extension);
+    const stripExtension = normalizedExtension ? new RegExp(`\\.${normalizedExtension}$`, "i") : null;
+    const rawStem = stripExtension ? decodedBase.replace(stripExtension, "") : decodedBase;
+    return sanitizeFileSegment(rawStem);
+  } catch {
+    return "";
+  }
+}
+
+export function buildFileName(
+  kind: MediaKind,
+  index: number,
+  sourceUrl: string,
+  extension: string,
+  fileNameHint?: string,
+): string {
+  const stem = resolveFileStem(sourceUrl, extension, fileNameHint);
+  const prefix = kind === "image" ? "img" : "video";
+  const serial = String(index).padStart(3, "0");
+  const suffix = stem ? `-${stem}` : "";
+  return `${prefix}-${serial}${suffix}.${extension}`;
+}
+
+export function toPosixPath(value: string): string {
+  return value.split(path.sep).join(path.posix.sep);
+}

packages/baoyu-fetch/src/media/types.ts

@@ -0,0 +1,34 @@
+import type { Logger } from "../utils/logger";
+
+export type MediaKind = "image" | "video";
+
+export interface MediaAsset {
+  url: string;
+  kind?: MediaKind;
+  role?: "cover" | "inline" | "attachment";
+  alt?: string;
+  fileNameHint?: string;
+  headers?: Record<string, string>;
+}
+
+export interface MediaReplacement {
+  url: string;
+  localPath: string;
+  absolutePath: string;
+  kind: MediaKind;
+}
+
+export interface MediaDownloadRequest {
+  media: MediaAsset[];
+  outputPath: string;
+  mediaDir?: string;
+  log: Logger;
+}
+
+export interface MediaDownloadResult {
+  replacements: MediaReplacement[];
+  downloadedImages: number;
+  downloadedVideos: number;
+  imageDir: string | null;
+  videoDir: string | null;
+}

packages/baoyu-fetch/src/types/defuddle-node.d.ts

@@ -0,0 +1,31 @@
+declare module "defuddle/node" {
+  export interface DefuddleResponse {
+    content?: string;
+    title?: string;
+    description?: string;
+    author?: string;
+    published?: string;
+    image?: string;
+    language?: string;
+  }
+
+  export interface DefuddleOptions {
+    markdown?: boolean;
+  }
+
+  export function Defuddle(
+    input:
+      | Document
+      | string
+      | {
+          window: {
+            document: Document;
+            location: {
+              href: string;
+            };
+          };
+        },
+    url?: string,
+    options?: DefuddleOptions,
+  ): Promise<DefuddleResponse>;
+}

packages/baoyu-fetch/src/types/shims.d.ts

@@ -0,0 +1,17 @@
+declare module "turndown" {
+  export interface TurndownOptions {
+    codeBlockStyle?: "indented" | "fenced";
+    headingStyle?: "setext" | "atx";
+    bulletListMarker?: "-" | "*" | "+";
+  }
+
+  export default class TurndownService {
+    constructor(options?: TurndownOptions);
+    use(plugin: unknown): void;
+    turndown(input: string): string;
+  }
+}
+
+declare module "turndown-plugin-gfm" {
+  export const gfm: unknown;
+}

packages/baoyu-fetch/src/utils/logger.ts

@@ -0,0 +1,30 @@
+export interface Logger {
+  info(message: string): void;
+  warn(message: string): void;
+  error(message: string): void;
+  debug(message: string): void;
+}
+
+export function createLogger(debugEnabled = false): Logger {
+  const print = (level: string, message: string): void => {
+    console.error(`[${level}] ${message}`);
+  };
+
+  return {
+    info(message: string) {
+      print("info", message);
+    },
+    warn(message: string) {
+      print("warn", message);
+    },
+    error(message: string) {
+      print("error", message);
+    },
+    debug(message: string) {
+      if (debugEnabled) {
+        print("debug", message);
+      }
+    },
+  };
+}
+

packages/baoyu-fetch/src/utils/url.ts

@@ -0,0 +1,12 @@
+export function normalizeUrl(input: string): URL {
+  try {
+    return new URL(input);
+  } catch {
+    throw new Error(`Invalid URL: ${input}`);
+  }
+}
+
+export function sanitizeFilename(input: string): string {
+  return input.replace(/[^a-zA-Z0-9._-]+/g, "-").replace(/^-+|-+$/g, "") || "document";
+}
+

packages/baoyu-fetch/tsconfig.json

@@ -0,0 +1,17 @@
+{
+  "compilerOptions": {
+    "target": "ES2022",
+    "module": "ESNext",
+    "moduleResolution": "Bundler",
+    "lib": ["ES2022", "DOM"],
+    "types": ["bun"],
+    "strict": true,
+    "noEmit": true,
+    "skipLibCheck": true,
+    "allowSyntheticDefaultImports": true,
+    "forceConsistentCasingInFileNames": true,
+    "verbatimModuleSyntax": true,
+    "resolveJsonModule": true
+  },
+  "include": ["src/**/*.ts", "src/**/*.d.ts"]
+}