docs: add Customization section to README files

chore: release v0.9.0
chore: release v0.8.2
2026-07-12 13:59:47 +08:00 · 2026-01-17 22:12:01 -06:00 · 2026-01-17 22:02:40 -06:00 · 2026-01-17 19:00:27 -06:00 · 2026-01-17 16:44:50 -06:00 · 2026-01-17 16:24:23 -06:00
149 changed files with 18031 additions and 1662 deletions
@@ -1,20 +1,29 @@
 {
  "name": "baoyu-skills",
-  "description": "Skills shared by Baoyu for improving daily work efficiency",
  "owner": {
    "name": "Jim Liu (宝玉)",
    "email": "junminliu@gmail.com"
  },
+  "metadata": {
+    "description": "Skills shared by Baoyu for improving daily work efficiency",
+    "version": "0.9.0"
+  },
  "plugins": [
    {
-      "name": "baoyu-skills",
+      "name": "content-skills",
      "description": "Skills shared by Baoyu for improving daily work efficiency",
-      "version": "0.1.0",
      "source": "./",
-      "author": {
-        "name": "Jim Liu (宝玉)",
-        "email": "junminliu@gmail.com"
-      }
+      "strict": false,
+      "skills": [
+        "./skills/baoyu-gemini-web",
+        "./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"
+      ]
    }
  ]
 }
@@ -1,13 +0,0 @@
-{
-  "name": "baoyu-skills",
-  "description": "Skills shared by Baoyu for improving daily work efficiency",
-  "version": "0.1.0",
-  "author": {
-    "name": "Jim Liu (宝玉)",
-    "email": "junminliu@gmail.com"
-  },
-  "homepage": "https://github.com/baoyu/baoyu-skills",
-  "repository": "https://github.com/baoyu/baoyu-skills",
-  "license": "MIT",
-  "keywords": ["skills", "translation", "productivity", "workflows"]
-}
@@ -0,0 +1,203 @@
+---
+name: release-skills
+description: Release workflow for baoyu-skills plugin. This skill should be used when the user wants to create a new release version. It analyzes changes since the last version tag, updates changelogs (EN/CN), bumps the version in marketplace.json, commits changes, and creates a version tag. Supports dry-run mode and breaking change detection.
+---
+
+# Release Skills
+
+Automate the release process for baoyu-skills plugin: analyze changes, update changelogs, bump version, commit, and tag.
+
+## When to Use
+
+Trigger this skill when user requests:
+- "release", "发布", "create release", "new version"
+- "bump version", "update version"
+- "prepare release"
+
+## Workflow
+
+### Step 1: Analyze Changes Since Last Tag
+
+```bash
+# Get the latest version tag
+LAST_TAG=$(git tag --sort=-v:refname | head -1)
+
+# Show changes since last tag
+git log ${LAST_TAG}..HEAD --oneline
+git diff ${LAST_TAG}..HEAD --stat
+```
+
+Categorize changes by type based on commit messages and file changes:
+
+| Type | Prefix | Description |
+|------|--------|-------------|
+| feat | `feat:` | New features, new skills |
+| fix | `fix:` | Bug fixes |
+| docs | `docs:` | Documentation only |
+| refactor | `refactor:` | Code refactoring |
+| style | `style:` | Formatting, styling |
+| chore | `chore:` | Build, tooling, maintenance |
+
+**Breaking Change Detection**: If changes include:
+- Removed skills or scripts
+- Changed API/interfaces
+- Renamed public functions/options
+
+Warn user: "Breaking changes detected. Consider major version bump (--major flag)."
+
+### Step 2: Determine Version Bump
+
+Current version location: `.claude-plugin/marketplace.json` → `metadata.version`
+
+Version rules:
+- **Patch** (0.6.1 → 0.6.2): Bug fixes, docs updates, minor improvements
+- **Minor** (0.6.x → 0.7.0): New features, new skills, significant enhancements
+- **Major** (0.x → 1.0): Breaking changes, only when user explicitly requests with `--major`
+
+Default behavior:
+- If changes include `feat:` or new skills → Minor bump
+- Otherwise → Patch bump
+
+### Step 3: Check and Update README
+
+Before updating changelogs, check if README files need updates based on changes:
+
+**When to update README**:
+- New skills added → Add to skill list
+- Skills removed → Remove from skill list
+- Skill renamed → Update references
+- New features affecting usage → Update usage section
+- Breaking changes → Update migration notes
+
+**Files to sync**:
+- `README.md` (English)
+- `README.zh.md` (Chinese)
+
+If changes include new skills or significant feature changes, update both README files to reflect the new capabilities. Keep both files in sync with the same structure and information.
+
+### Step 4: Update Changelogs
+
+Files to update:
+- `CHANGELOG.md` (English)
+- `CHANGELOG.zh.md` (Chinese)
+
+Format (insert after header, before previous version):
+
+```markdown
+## {NEW_VERSION} - {YYYY-MM-DD}
+
+### Features
+- `skill-name`: description of new feature
+
+### Fixes
+- `skill-name`: description of fix
+
+### Documentation
+- description of docs changes
+
+### Other
+- description of other changes
+```
+
+Only include sections that have changes. Omit empty sections.
+
+For Chinese changelog, translate the content maintaining the same structure.
+
+### Step 5: Update marketplace.json
+
+Update `.claude-plugin/marketplace.json`:
+```json
+{
+  "metadata": {
+    "version": "{NEW_VERSION}"
+  }
+}
+```
+
+### Step 6: Commit Changes
+
+```bash
+git add README.md README.zh.md CHANGELOG.md CHANGELOG.zh.md .claude-plugin/marketplace.json
+git commit -m "chore: release v{NEW_VERSION}"
+```
+
+**Note**: Do NOT add Co-Authored-By line. This is a release commit, not a code contribution.
+
+### Step 7: Create Version Tag
+
+```bash
+git tag v{NEW_VERSION}
+```
+
+**Important**: Do NOT push to remote. User will push manually when ready.
+
+## Options
+
+| Flag | Description |
+|------|-------------|
+| `--dry-run` | Preview changes without executing. Show what would be updated. |
+| `--major` | Force major version bump (0.x → 1.0 or 1.x → 2.0) |
+| `--minor` | Force minor version bump |
+| `--patch` | Force patch version bump |
+| `--pre <tag>` | (Reserved) Create pre-release version, e.g., `--pre beta` → `0.7.0-beta.1` |
+
+## Dry-Run Mode
+
+When `--dry-run` is specified:
+1. Show all changes since last tag
+2. Show proposed version bump (current → new)
+3. Show draft changelog entries (EN and CN)
+4. Show files that would be modified
+5. Do NOT make any actual changes
+
+Output format:
+```
+=== DRY RUN MODE ===
+
+Last tag: v0.6.1
+Proposed version: v0.7.0
+
+Changes detected:
+- feat: new skill baoyu-foo added
+- fix: baoyu-bar timeout issue
+- docs: updated README
+
+Changelog preview (EN):
+## 0.7.0 - 2026-01-17
+### Features
+- `baoyu-foo`: new skill for ...
+### Fixes
+- `baoyu-bar`: fixed timeout issue
+
+README updates needed: Yes/No
+(If yes, show proposed changes)
+
+Files to modify:
+- README.md (if updates needed)
+- README.zh.md (if updates needed)
+- CHANGELOG.md
+- CHANGELOG.zh.md
+- .claude-plugin/marketplace.json
+
+No changes made. Run without --dry-run to execute.
+```
+
+## Example Usage
+
+```
+/release-skills              # Auto-detect version bump
+/release-skills --dry-run    # Preview only
+/release-skills --minor      # Force minor bump
+/release-skills --major      # Force major bump (with confirmation)
+```
+
+## Post-Release Reminder
+
+After successful release, remind user:
+```
+Release v{NEW_VERSION} created locally.
+
+To publish:
+  git push origin main
+  git push origin v{NEW_VERSION}
+```
@@ -137,3 +137,9 @@ dist
 # Vite logs files
 vite.config.js.timestamp-*
 vite.config.ts.timestamp-*
+tests-data/
+
+.DS_Store
+
+# Skill extensions (user customization)
+.baoyu-skills/
@@ -0,0 +1,124 @@
+# Changelog
+
+English | [中文](./CHANGELOG.zh.md)
+
+## 0.9.0 - 2026-01-17
+
+### Features
+- Extension support: all skills now support customization via `EXTEND.md` files. Check `.baoyu-skills/<skill-name>/EXTEND.md` (project) or `~/.baoyu-skills/<skill-name>/EXTEND.md` (user) for custom styles and configurations.
+
+### Other
+- `.gitignore`: adds `.baoyu-skills/` directory for user extension files.
+
+## 0.8.2 - 2026-01-17
+
+### Refactor
+- `baoyu-gemini-web`: reorganizes script architecture—moves modular files into `gemini-webapi/` subdirectory and updates SKILL.md with `${SKILL_DIR}` path references.
+
+## 0.8.1 - 2026-01-17
+
+### Refactor
+- `baoyu-gemini-web`: refactors script architecture—consolidates 10 separate files into a structured `gemini-webapi/` module (TypeScript port of gemini_webapi Python library).
+
+## 0.8.0 - 2026-01-17
+
+### Features
+- `baoyu-xhs-images`: adds content analysis framework (`analysis-framework.md`, `outline-template.md`) for structured content breakdown and outline generation.
+
+### Documentation
+- `CLAUDE.md`: adds Output Path Convention (directory structure, backup rules) and Image Naming Convention (format, slug rules) to standardize image generation outputs.
+- Multiple skills: updates file management conventions to use unified directory structure (`[source-name-no-ext]/<skill-suffix>/`).
+  - `baoyu-article-illustrator`, `baoyu-comic`, `baoyu-cover-image`, `baoyu-slide-deck`, `baoyu-xhs-images`
+
+## 0.7.0 - 2026-01-17
+
+### Features
+- `baoyu-comic`: adds `--aspect` (3:4, 4:3, 16:9) and `--lang` options; introduces multi-variant storyboard workflow (chronological, thematic, character-centric) with user selection.
+
+### Enhancements
+- `baoyu-comic`: adds `analysis-framework.md` and `storyboard-template.md` for structured content analysis and variant generation.
+- `baoyu-slide-deck`: adds `analysis-framework.md`, `content-rules.md`, `modification-guide.md`, and `outline-template.md` references for improved outline quality.
+- `baoyu-article-illustrator`, `baoyu-cover-image`, `baoyu-xhs-images`: enhanced SKILL.md documentation with clearer workflows.
+
+### Documentation
+- Multiple skills: restructured SKILL.md files—moved detailed content to `references/` directory for maintainability.
+- `baoyu-slide-deck`: simplified SKILL.md, consolidated style descriptions.
+
+## 0.6.1 - 2026-01-17
+
+- `baoyu-slide-deck`: adds `scripts/merge-to-pdf.ts` to export generated slides into a single PDF; docs updated with pptx/pdf outputs.
+- `baoyu-comic`: adds `scripts/merge-to-pdf.ts` to merge cover/pages into a PDF; docs clarify character reference handling (image vs text).
+- Docs conventions: adds a “Script Directory” template to `CLAUDE.md`; aligns `baoyu-gemini-web` / `baoyu-slide-deck` / `baoyu-comic` docs to use `${SKILL_DIR}` in commands so agents can run scripts from any install location.
+
+## 0.6.0 - 2026-01-17
+
+- `baoyu-slide-deck`: adds `scripts/merge-to-pptx.ts` to merge slide images into a PPTX and attach `prompts/` content as speaker notes.
+- `baoyu-slide-deck`: reshapes/expands the style library (adds `blueprint` / `bold-editorial` / `sketch-notes` / `vector-illustration`, and adjusts/replaces some older styles).
+- `baoyu-comic`: adds a `realistic` style reference.
+- Docs: refreshes `README.md` / `README.zh.md`.
+
+## 0.5.3 - 2026-01-17
+
+- `baoyu-post-to-x` (X Articles): makes image placeholder replacement more reliable (selection retry + verification; deletes via Backspace and verifies deletion before pasting), reducing mis-insertions/failures.
+
+## 0.5.2 - 2026-01-16
+
+- `baoyu-gemini-web`: adds `--sessionId` (local persisted sessions, plus `--list-sessions`) for multi-turn conversations and consistent multi-image generation.
+- `baoyu-gemini-web`: adds `--reference/--ref` for reference images (vision input), plus stronger timeout handling and cookie refresh recovery.
+- Docs: `baoyu-xhs-images` / `baoyu-slide-deck` / `baoyu-comic` document session usage (reuse one `sessionId` per set) to improve visual consistency.
+
+## 0.5.1 - 2026-01-16
+
+- `baoyu-comic`: adds creation templates/references (character template, Ohmsha guide, outline template) to speed up “characters → storyboard → generation”.
+
+## 0.5.0 - 2026-01-16
+
+- Adds `baoyu-comic`: a knowledge-comic generator with `style × layout` and a full set of style/layout references for more stable output.
+- `baoyu-xhs-images`: moves style/layout details into `references/styles/*` and `references/layouts/*`, and migrates the base prompt into `references/base-prompt.md` for easier maintenance/reuse.
+- `baoyu-slide-deck` / `baoyu-cover-image`: similarly split base prompt and style references into `references/`, reducing SKILL.md complexity and making style expansion easier.
+- Docs: updates `README.md` / `README.zh.md` skill list and examples.
+
+## 0.4.2 - 2026-01-15
+
+- `baoyu-gemini-web`: updates description to clarify it as the image-generation backend for other skills (e.g. `cover-image`, `xhs-images`, `article-illustrator`).
+
+## 0.4.1 - 2026-01-15
+
+- `baoyu-post-to-x` / `baoyu-post-to-wechat`: adds `scripts/paste-from-clipboard.ts` to send a “real paste” keystroke (Cmd/Ctrl+V), avoiding sites ignoring CDP synthetic events.
+- `baoyu-post-to-x`: adds docs for X Articles/regular posts, and switches image upload to prefer real paste (with a CDP fallback).
+- `baoyu-post-to-wechat`: docs add script-location guidance and `${SKILL_DIR}` path usage for reliable agent execution.
+- Docs: adds `screenshots/update-plugins.png` for the marketplace update flow.
+
+## 0.4.0 - 2026-01-15
+
+- Adds `baoyu-` prefix to skill directories and updates marketplace paths/docs accordingly to reduce naming collisions.
+
+## 0.3.1 - 2026-01-15
+
+- `xhs-images`: upgrades docs to a Style × Layout system (adds `--layout`, auto layout selection, and a `notion` style), with more complete usage examples.
+- `article-illustrator` / `cover-image`: docs no longer hard-code `gemini-web`; instead they instruct the agent to pick an available image-generation skill.
+- `slide-deck`: docs add the `notion` style and update auto-style mapping.
+- Tooling/docs: adds `.DS_Store` to `.gitignore`; refreshes `README.md` / `README.zh.md`.
+
+## 0.3.0 - 2026-01-14
+
+- Adds `post-to-wechat`: Chrome CDP automation for WeChat Official Account posting (image-text + full article), including Markdown → WeChat HTML conversion and multiple themes.
+- Adds `CLAUDE.md`: repository structure, running conventions, and “add new skill” guidelines.
+- Docs: updates `README.md` / `README.zh.md` install/update/usage instructions.
+
+## 0.2.0 - 2026-01-13
+
+- Adds new skills: `post-to-x` (real Chrome/CDP automation for posts and X Articles), `article-illustrator`, `cover-image`, and `slide-deck`.
+- `xhs-images`: adds multi-style support (`--style`) with auto style selection and updates the base prompt (e.g. language follows input, hand-drawn infographic constraints).
+- Docs: adds `README.zh.md` and improves `README.md` and `.gitignore`.
+
+## 0.1.1 - 2026-01-13
+
+- Marketplace refactor: introduces `metadata` (including `version`), renames the plugin entry to `content-skills` and explicitly lists installable skills; removes legacy `.claude-plugin/plugin.json`.
+- Adds `xhs-images`: Xiaohongshu infographic series generator (outline + per-image prompts).
+- `gemini-web`: adds `--promptfiles` to build prompts from multiple files (system/content separation).
+- Docs: adds `README.md`.
+
+## 0.1.0 - 2026-01-13
+
+- Initial release: `.claude-plugin/marketplace.json` plus `gemini-web` (text/image generation, browser login + cookie cache).
@@ -0,0 +1,123 @@
+# Changelog
+
+[English](./CHANGELOG.md) | 中文
+
+## 0.9.0 - 2026-01-17
+
+### 新功能
+- 扩展支持：所有技能现支持通过 `EXTEND.md` 文件自定义。检查 `.baoyu-skills/<skill-name>/EXTEND.md`（项目级）或 `~/.baoyu-skills/<skill-name>/EXTEND.md`（用户级）配置自定义样式与设置。
+
+### 其他
+- `.gitignore`：添加 `.baoyu-skills/` 目录忽略，存放用户扩展文件。
+
+## 0.8.2 - 2026-01-17
+
+### 重构
+- `baoyu-gemini-web`：重组脚本架构——将模块文件移至 `gemini-webapi/` 子目录，并更新 SKILL.md 使用 `${SKILL_DIR}` 路径引用。
+
+## 0.8.1 - 2026-01-17
+
+### 重构
+- `baoyu-gemini-web`：重构脚本架构——将 10 个分散的脚本文件整合为结构化的 `gemini-webapi/` 模块（gemini_webapi Python 库的 TypeScript 移植版）。
+
+## 0.8.0 - 2026-01-17
+
+### 新功能
+- `baoyu-xhs-images`：新增内容分析框架（`analysis-framework.md`、`outline-template.md`），提供结构化内容拆解与大纲生成方案。
+
+### 文档
+- `CLAUDE.md`：新增 Output Path Convention（目录结构、备份规则）和 Image Naming Convention（文件命名格式、slug 规则），统一图片生成输出规范。
+- 多个技能：更新文件管理规范，采用统一目录结构（`[source-name-no-ext]/<skill-suffix>/`）。
+  - `baoyu-article-illustrator`、`baoyu-comic`、`baoyu-cover-image`、`baoyu-slide-deck`、`baoyu-xhs-images`
+
+## 0.7.0 - 2026-01-17
+
+### 新功能
+- `baoyu-comic`：新增 `--aspect`（3:4、4:3、16:9）和 `--lang` 选项；引入多变体分镜工作流（时间线、主题、人物视角），支持用户选择最佳方案。
+
+### 增强
+- `baoyu-comic`：新增 `analysis-framework.md` 和 `storyboard-template.md`，提供结构化内容分析与变体生成框架。
+- `baoyu-slide-deck`：新增 `analysis-framework.md`、`content-rules.md`、`modification-guide.md`、`outline-template.md` 参考文档，提升大纲质量。
+- `baoyu-article-illustrator`、`baoyu-cover-image`、`baoyu-xhs-images`：SKILL.md 文档增强，工作流程更清晰。
+
+### 文档
+- 多个技能：重构 SKILL.md 结构，将详细内容移至 `references/` 目录，便于维护。
+- `baoyu-slide-deck`：精简 SKILL.md，整合风格描述。
+
+## 0.6.1 - 2026-01-17
+
+- `baoyu-slide-deck`：新增 `scripts/merge-to-pdf.ts`，可将生成的 slide 图片一键合并为 PDF；文档补充导出步骤与产物命名（pptx/pdf）。
+- `baoyu-comic`：新增 `scripts/merge-to-pdf.ts`，将封面/分页图片合并为 PDF；补充角色参考（图片/文本）处理说明。
+- 文档规范：在 `CLAUDE.md` 中补充“Script Directory”模板；`baoyu-gemini-web` / `baoyu-slide-deck` / `baoyu-comic` 文档统一用 `${SKILL_DIR}` 引用脚本路径，方便 agent 在任意安装目录运行。
+
+## 0.6.0 - 2026-01-17
+
+- `baoyu-slide-deck`：新增 `scripts/merge-to-pptx.ts`，将生成的 slide 图片合并为 PPTX，并可把 `prompts/` 写入 speaker notes。
+- `baoyu-slide-deck`：风格库重组与扩充（新增 `blueprint` / `bold-editorial` / `sketch-notes` / `vector-illustration`，并调整/替换部分旧风格定义）。
+- `baoyu-comic`：新增 `realistic` 风格参考文件。
+- 文档：README / README.zh 同步更新技能说明与用法示例。
+
+## 0.5.3 - 2026-01-17
+
+- `baoyu-post-to-x`（X Articles）：插图占位符替换更稳定——选中占位符增加重试与校验，改用 Backspace 删除并确认删除后再粘贴图片，降低插图错位/替换失败概率。
+
+## 0.5.2 - 2026-01-16
+
+- `baoyu-gemini-web`：新增 `--sessionId`（本地持久化会话，支持 `--list-sessions`），用于多轮对话/多图生成保持上下文一致。
+- `baoyu-gemini-web`：新增 `--reference/--ref` 传入参考图片（vision 输入），并增强超时与 cookie 失效自动恢复逻辑。
+- `baoyu-xhs-images` / `baoyu-slide-deck` / `baoyu-comic`：文档补充 session 约定（整套图使用同一 `sessionId`，增强风格一致性）。
+
+## 0.5.1 - 2026-01-16
+
+- `baoyu-comic`：补齐创作模板与参考（角色模板、Ohmsha 教学漫画指南、大纲模板），更适合从“设定 → 分镜 → 生成”快速落地。
+
+## 0.5.0 - 2026-01-16
+
+- 新增 `baoyu-comic`：知识漫画生成器，支持 `style × layout` 组合，并提供风格/布局参考文件用于稳定出图。
+- `baoyu-xhs-images`：将 Style/Layout 的细节从 SKILL.md 拆分到 `references/styles/*` 与 `references/layouts/*`，并将基础提示词迁移到 `references/base-prompt.md`，便于维护和复用。
+- `baoyu-slide-deck` / `baoyu-cover-image`：同样将基础提示词与风格拆分到 `references/`，降低 SKILL.md 复杂度，便于扩展更多风格。
+- 文档：README / README.zh 更新技能清单与用法示例。
+
+## 0.4.2 - 2026-01-15
+
+- `baoyu-gemini-web`：描述信息更新，明确其作为 `cover-image` / `xhs-images` / `article-illustrator` 等技能的图片生成后端。
+
+## 0.4.1 - 2026-01-15
+
+- `baoyu-post-to-x` / `baoyu-post-to-wechat`：新增 `scripts/paste-from-clipboard.ts`，通过系统级 Cmd/Ctrl+V 发送“真实粘贴”按键，规避 CDP 合成事件在站点侧被忽略的问题。
+- `baoyu-post-to-x`：补充 X Articles/普通推文的操作文档（`references/articles.md`、`references/regular-posts.md`），并将发图流程改为优先使用“真实粘贴”（保留 CDP 兜底）。
+- `baoyu-post-to-wechat`：文档补充脚本目录说明与 `${SKILL_DIR}` 路径写法，便于 agent 可靠定位脚本。
+- 文档：新增插件更新流程截图 `screenshots/update-plugins.png`。
+
+## 0.4.0 - 2026-01-15
+
+- 技能命名统一加 `baoyu-` 前缀：目录结构、marketplace 清单与文档示例命令同步更新，减少与其它插件技能的命名冲突。
+
+## 0.3.1 - 2026-01-15
+
+- `xhs-images`：升级为 Style × Layout 二维系统（新增 `--layout`、自动布局选择与 Notion 风格），文档示例更完整。
+- `article-illustrator` / `slide-deck` / `cover-image`：文档改为“选择可用的图片生成技能”而非强绑定 `gemini-web`，并补充 Notion 风格相关说明。
+- 工程化：`.gitignore` 增加 `.DS_Store` 忽略；README / README.zh 同步调整。
+
+## 0.3.0 - 2026-01-14
+
+- 新增 `post-to-wechat`：基于 Chrome CDP 自动化发布公众号图文/文章，包含 Markdown → 微信 HTML 转换与多主题样式支持。
+- 新增 `CLAUDE.md`：补充仓库结构、运行方式与添加新技能的约定，方便协作与二次开发。
+- 文档：README / README.zh 更新安装、更新与使用说明。
+
+## 0.2.0 - 2026-01-13
+
+- 新增技能：`post-to-x`（真实 Chrome/CDP 自动化发布推文与 X Articles）、`article-illustrator`（文章智能插图规划）、`cover-image`（文章封面图生成）、`slide-deck`（幻灯片大纲与图片生成）。
+- `xhs-images`：新增 `--style` 多风格与自动风格选择，并更新基础提示词（例如语言随内容、强调手绘信息图等）。
+- 文档：新增 `README.zh.md`，并完善 README 与 `.gitignore`。
+
+## 0.1.1 - 2026-01-13
+
+- marketplace 结构重构：引入 `metadata`（含 `version`），插件名调整为 `content-skills` 并显式列出可安装 skills；移除旧 `.claude-plugin/plugin.json`。
+- 新增 `xhs-images`：小红书信息图系列生成技能（拆解内容、生成 outline 与提示词）。
+- `gemini-web`：新增 `--promptfiles`，支持从多个文件拼接 prompt（便于 system/content 分离）。
+- 文档：新增 `README.md`。
+
+## 0.1.0 - 2026-01-13
+
+- 初始发布：提供 `.claude-plugin/marketplace.json` 与 `gemini-web`（文本/图片生成、cookie 登录与缓存流程）。
@@ -0,0 +1,208 @@
+# 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.
+
+## Architecture
+
+```
+skills/
+├── baoyu-gemini-web/          # Core: Gemini API wrapper (text + image gen)
+├── 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-post-to-x/           # X/Twitter posting automation
+└── baoyu-post-to-wechat/      # WeChat Official Account posting
+```
+
+Each skill contains:
+- `SKILL.md` - YAML front matter (name, description) + documentation
+- `scripts/` - TypeScript implementations
+- `prompts/system.md` - AI generation guidelines (optional)
+
+## Running Skills
+
+All scripts run via Bun (no build step):
+
+```bash
+npx -y bun skills/<skill>/scripts/main.ts [options]
+```
+
+Examples:
+```bash
+# Text generation
+npx -y bun skills/baoyu-gemini-web/scripts/main.ts "Hello"
+
+# Image generation
+npx -y bun skills/baoyu-gemini-web/scripts/main.ts --prompt "A cat" --image cat.png
+
+# From prompt files
+npx -y bun skills/baoyu-gemini-web/scripts/main.ts --promptfiles system.md content.md --image out.png
+```
+
+## Key Dependencies
+
+- **Bun**: TypeScript runtime (via `npx -y bun`)
+- **Chrome**: Required for `baoyu-gemini-web` auth and `baoyu-post-to-x` automation
+- **No npm packages**: Self-contained TypeScript, no external dependencies
+
+## Authentication
+
+`baoyu-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.
+
+## Adding New Skills
+
+**IMPORTANT**: All skills MUST use `baoyu-` prefix to avoid conflicts when users import this plugin.
+
+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. Register in `marketplace.json` plugins[0].skills array as `./skills/baoyu-<name>`
+5. **Add Script Directory section** to SKILL.md (see template below)
+
+### 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. Replace all `${SKILL_DIR}` in this document with the actual path
+
+**Script Reference**:
+| Script | Purpose |
+|--------|---------|
+| `scripts/main.ts` | Main entry point |
+| `scripts/other.ts` | Other functionality |
+```
+
+When referencing scripts in workflow sections, use `${SKILL_DIR}/scripts/<name>.ts` so agents can resolve the correct path.
+
+## Code Style
+
+- TypeScript throughout, no comments
+- Async/await patterns
+- Short variable names
+- Type-safe interfaces
+
+## Image Generation Guidelines
+
+Skills that require image generation MUST delegate to available image generation skills rather than implementing their own.
+
+### Image Generation Skill Selection
+
+1. Check available image generation skills in `skills/` directory
+2. Read each skill's SKILL.md to understand parameters and capabilities
+3. If multiple image generation skills available, ask user to choose preferred skill
+
+### 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-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
+
+Generated images from the same skill and source file MUST be grouped together:
+
+**With source file** (e.g., `/path/to/project/content/my-article.md`):
+```
+/path/to/project/content/my-article/<skill-suffix>/
+```
+- Remove file extension from source filename
+- Use skill name suffix (e.g., `xhs-images`, `cover-image`, `slide-deck`)
+- Example: source `/tests-data/anthropic-economic-index.md` + skill `baoyu-xhs-images` → `/tests-data/anthropic-economic-index/xhs-images/`
+
+**Without source file**:
+```
+./<skill-suffix>/<source-slug>/
+```
+- Place under current project directory
+- Use descriptive slug for the content
+
+**Directory Backup**:
+- If output directory already exists, rename existing directory with timestamp
+- Format: `<dirname>-backup-YYYYMMDD-HHMMSS`
+- Example: `xhs-images` → `xhs-images-backup-20260117-143052`
+
+### 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
+
+## Extension Support
+
+Every SKILL.md MUST include an Extension Support section at the end:
+
+```markdown
+## Extension Support
+
+Custom styles and configurations via EXTEND.md.
+
+**Check paths** (priority order):
+1. `.baoyu-skills/<skill-name>/EXTEND.md` (project)
+2. `~/.baoyu-skills/<skill-name>/EXTEND.md` (user)
+
+If found, load before Step 1. Extension content overrides defaults.
+```
+
+Replace `<skill-name>` with the actual skill name (e.g., `baoyu-cover-image`).
@@ -0,0 +1,290 @@
+# baoyu-skills
+
+English | [中文](./README.zh.md)
+
+Skills shared by Baoyu for improving daily work efficiency with Claude Code.
+
+## Prerequisites
+
+- Node.js environment installed
+- Ability to run `npx bun` commands
+
+## Installation
+
+### Quick Install (Recommended)
+
+```bash
+npx add-skill jimliu/baoyu-skills
+```
+
+### Register as Plugin Marketplace
+
+Run the following command in Claude Code:
+
+```bash
+/plugin marketplace add jimliu/baoyu-skills
+```
+
+### Install Skills
+
+**Option 1: Via Browse UI**
+
+1. Select **Browse and install plugins**
+2. Select **baoyu-skills**
+3. Select **content-skills**
+4. Select **Install now**
+
+**Option 2: Direct Install**
+
+```bash
+/plugin install content-skills@baoyu-skills
+```
+
+**Option 3: Ask the Agent**
+
+Simply tell Claude Code:
+
+> Please install Skills from github.com/JimLiu/baoyu-skills
+
+## Update Skills
+
+To update skills to the latest version:
+
+1. Run `/plugin` in Claude Code
+2. Switch to **Marketplaces** tab (use arrow keys or Tab)
+3. Select **baoyu-skills**
+4. Choose **Update marketplace**
+
+You can also **Enable auto-update** to get the latest versions automatically.
+
+![Update Skills](./screenshots/update-plugins.png)
+
+## Available Skills
+
+### baoyu-gemini-web
+
+Interacts with Gemini Web to generate text and images.
+
+**Text Generation:**
+
+```bash
+/baoyu-gemini-web "Hello, Gemini"
+/baoyu-gemini-web --prompt "Explain quantum computing"
+```
+
+**Image Generation:**
+
+```bash
+/baoyu-gemini-web --prompt "A cute cat" --image cat.png
+/baoyu-gemini-web --promptfiles system.md content.md --image out.png
+```
+
+### baoyu-xhs-images
+
+Xiaohongshu (RedNote) infographic series generator. Breaks down content into 1-10 cartoon-style infographics with **Style × Layout** two-dimensional system.
+
+```bash
+# Auto-select style and layout
+/baoyu-xhs-images posts/ai-future/article.md
+
+# Specify style
+/baoyu-xhs-images posts/ai-future/article.md --style notion
+
+# Specify layout
+/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
+
+# Direct content input
+/baoyu-xhs-images 今日星座运势
+```
+
+**Styles** (visual aesthetics): `cute` (default), `fresh`, `tech`, `warm`, `bold`, `minimal`, `retro`, `pop`, `notion`
+
+**Layouts** (information density):
+| Layout | Density | Best for |
+|--------|---------|----------|
+| `sparse` | 1-2 pts | Covers, quotes |
+| `balanced` | 3-4 pts | Regular content |
+| `dense` | 5-8 pts | Knowledge cards, cheat sheets |
+| `list` | 4-7 items | Checklists, rankings |
+| `comparison` | 2 sides | Before/after, pros/cons |
+| `flow` | 3-6 steps | Processes, timelines |
+
+### baoyu-cover-image
+
+Generate hand-drawn style cover images for articles with multiple style options.
+
+```bash
+# From markdown file (auto-select style)
+/baoyu-cover-image path/to/article.md
+
+# Specify a style
+/baoyu-cover-image path/to/article.md --style tech
+/baoyu-cover-image path/to/article.md --style warm
+
+# Without title text
+/baoyu-cover-image path/to/article.md --no-title
+```
+
+Available styles: `elegant` (default), `tech`, `warm`, `bold`, `minimal`, `playful`, `nature`, `retro`
+
+### baoyu-slide-deck
+
+Generate professional slide deck images from content. Creates comprehensive outlines with style instructions, then generates individual slide images.
+
+```bash
+# From markdown file
+/baoyu-slide-deck path/to/article.md
+
+# With style and audience
+/baoyu-slide-deck path/to/article.md --style corporate
+/baoyu-slide-deck path/to/article.md --audience executives
+
+# Outline only (no image generation)
+/baoyu-slide-deck path/to/article.md --outline-only
+
+# With language
+/baoyu-slide-deck path/to/article.md --lang zh
+```
+
+**Styles** (visual aesthetics):
+
+| Style | Description | Best For |
+|-------|-------------|----------|
+| `notion` (default) | SaaS dashboard aesthetic with clean data focus, card-based layouts | Product demos, SaaS, productivity tools, B2B |
+| `sketch-notes` | Hand-drawn feel with soft brush strokes, warm off-white background | Educational, tutorials, knowledge sharing |
+| `blueprint` | Technical schematics with grid texture, engineering precision | Architecture, system design, data analysis |
+| `bold-editorial` | High-impact magazine style, bold typography, dark backgrounds | Product launches, marketing, keynotes |
+| `vector-illustration` | Flat vector with black outlines, retro soft colors, toy model aesthetic | Creative proposals, children's content, explainers |
+| `minimal` | Ultra-clean with maximum whitespace, single accent color, zen-like | Executive briefings, keynotes, premium brands |
+| `storytelling` | Cinematic full-bleed visuals, emotional photography | Case studies, narratives, customer journeys |
+| `warm` | Soft gradients, rounded shapes, wellness palette | Lifestyle, wellness, personal development |
+| `corporate` | Navy/gold palette, structured layouts, professional iconography | Investor decks, client proposals, quarterly reports |
+| `playful` | Vibrant coral/teal/yellow, rounded shapes, dynamic layouts | Workshops, training, creative pitches |
+
+After generation, slides are automatically merged into a `.pptx` file for easy sharing.
+
+### baoyu-comic
+
+Knowledge comic creator supporting multiple styles (Logicomix/Ligne Claire, Ohmsha manga guide). Creates original educational comics with detailed panel layouts and sequential image generation.
+
+```bash
+# From source material
+/baoyu-comic posts/turing-story/source.md
+
+# Specify style
+/baoyu-comic posts/turing-story/source.md --style dramatic
+/baoyu-comic posts/turing-story/source.md --style ohmsha
+
+# Custom style (natural language)
+/baoyu-comic posts/turing-story/source.md --style "watercolor with soft edges"
+
+# Specify layout and aspect ratio
+/baoyu-comic posts/turing-story/source.md --layout cinematic
+/baoyu-comic posts/turing-story/source.md --aspect 16:9
+
+# Specify language
+/baoyu-comic posts/turing-story/source.md --lang zh
+
+# Direct content input
+/baoyu-comic "The story of Alan Turing and the birth of computer science"
+```
+
+**Options**:
+| Option | Values |
+|--------|--------|
+| `--style` | `classic` (default), `dramatic`, `warm`, `tech`, `sepia`, `vibrant`, `ohmsha`, `realistic`, or custom description |
+| `--layout` | `standard` (default), `cinematic`, `dense`, `splash`, `mixed`, `webtoon` |
+| `--aspect` | `3:4` (default, portrait), `4:3` (landscape), `16:9` (widescreen) |
+| `--lang` | `auto` (default), `zh`, `en`, `ja`, etc. |
+
+**Styles** (visual aesthetics):
+
+| Style | Description | Best For |
+|-------|-------------|----------|
+| `classic` (default) | Traditional Ligne Claire with clean uniform outlines, flat colors, detailed backgrounds | Biographies, balanced narratives, educational content |
+| `dramatic` | High contrast with heavy shadows, intense expressions, angular compositions | Pivotal discoveries, conflicts, climactic scenes |
+| `warm` | Soft edges, golden tones, cozy interiors with nostalgic feel | Personal stories, childhood scenes, mentorship |
+| `tech` | Precise geometric lines, circuit motifs, neon accents on dark backgrounds | Computing history, AI stories, modern tech |
+| `sepia` | Vintage illustration style with aged paper effect, period-accurate details | Pre-1950s stories, classical science, historical figures |
+| `vibrant` | Energetic lines with weight variation, bright colors, dynamic poses | Science explanations, "aha" moments, young audience |
+| `ohmsha` | Manga guide style with visual metaphors, gadgets, student/mentor dynamic | Technical tutorials, complex concepts (ML, physics) |
+| `realistic` | Full-color realistic manga with digital painting, smooth gradients, accurate proportions | Wine, food, business, lifestyle, professional topics |
+
+**Layouts** (panel arrangement):
+| Layout | Panels/Page | Best for |
+|--------|-------------|----------|
+| `standard` | 4-6 | Dialogue, narrative flow |
+| `cinematic` | 2-4 | Dramatic moments, establishing shots |
+| `dense` | 6-9 | Technical explanations, timelines |
+| `splash` | 1-2 large | Key moments, revelations |
+| `mixed` | 3-7 varies | Complex narratives, emotional arcs |
+| `webtoon` | 3-5 vertical | Ohmsha tutorials, mobile reading |
+
+### baoyu-post-to-wechat
+
+Post content to WeChat Official Account (微信公众号). Two modes available:
+
+**Image-Text (图文)** - Multiple images with short title/content:
+
+```bash
+/baoyu-post-to-wechat 图文 --markdown article.md --images ./photos/
+/baoyu-post-to-wechat 图文 --markdown article.md --image img1.png --image img2.png --image img3.png
+/baoyu-post-to-wechat 图文 --title "标题" --content "内容" --image img1.png --submit
+```
+
+**Article (文章)** - Full markdown/HTML with rich formatting:
+
+```bash
+/baoyu-post-to-wechat 文章 --markdown article.md
+/baoyu-post-to-wechat 文章 --markdown article.md --theme grace
+/baoyu-post-to-wechat 文章 --html article.html
+```
+
+Prerequisites: Google Chrome installed. First run requires QR code login (session preserved).
+
+## Customization
+
+All skills support customization via `EXTEND.md` files. Create an extension file to override default styles, add custom configurations, or define your own presets.
+
+**Extension paths** (checked in priority order):
+1. `.baoyu-skills/<skill-name>/EXTEND.md` - Project-level (for team/project-specific settings)
+2. `~/.baoyu-skills/<skill-name>/EXTEND.md` - User-level (for personal preferences)
+
+**Example**: To customize `baoyu-cover-image` with your brand colors:
+
+```bash
+mkdir -p .baoyu-skills/baoyu-cover-image
+```
+
+Then create `.baoyu-skills/baoyu-cover-image/EXTEND.md`:
+
+```markdown
+## Custom Styles
+
+### brand
+- Primary color: #1a73e8
+- Secondary color: #34a853
+- Font style: Modern sans-serif
+- Always include company logo watermark
+```
+
+The extension content will be loaded before skill execution and override defaults.
+
+## Disclaimer
+
+### baoyu-gemini-web
+
+This skill uses the Gemini Web API (reverse-engineered).
+
+**Warning:** This project uses unofficial API access via browser cookies. Use at your own risk.
+
+- First run opens Chrome to authenticate with Google
+- Cookies are cached for subsequent runs
+- No guarantees on API stability or availability
+
+## License
+
+MIT
@@ -0,0 +1,290 @@
+# baoyu-skills
+
+[English](./README.md) | 中文
+
+宝玉分享的 Claude Code 技能集，提升日常工作效率。
+
+## 前置要求
+
+- 已安装 Node.js 环境
+- 能够运行 `npx bun` 命令
+
+## 安装
+
+### 快速安装（推荐）
+
+```bash
+npx add-skill jimliu/baoyu-skills
+```
+
+### 注册插件市场
+
+在 Claude Code 中运行：
+
+```bash
+/plugin marketplace add jimliu/baoyu-skills
+```
+
+### 安装技能
+
+**方式一：通过浏览界面**
+
+1. 选择 **Browse and install plugins**
+2. 选择 **baoyu-skills**
+3. 选择 **content-skills**
+4. 选择 **Install now**
+
+**方式二：直接安装**
+
+```bash
+/plugin install content-skills@baoyu-skills
+```
+
+**方式三：告诉 Agent**
+
+直接告诉 Claude Code：
+
+> 请帮我安装 github.com/JimLiu/baoyu-skills 中的 Skills
+
+## 更新技能
+
+更新技能到最新版本：
+
+1. 在 Claude Code 中运行 `/plugin`
+2. 切换到 **Marketplaces** 标签页（使用方向键或 Tab）
+3. 选择 **baoyu-skills**
+4. 选择 **Update marketplace**
+
+也可以选择 **Enable auto-update** 启用自动更新，每次启动时自动获取最新版本。
+
+![更新技能](./screenshots/update-plugins.png)
+
+## 可用技能
+
+### baoyu-gemini-web
+
+与 Gemini Web 交互，生成文本和图片。
+
+**文本生成：**
+
+```bash
+/baoyu-gemini-web "你好，Gemini"
+/baoyu-gemini-web --prompt "解释量子计算"
+```
+
+**图片生成：**
+
+```bash
+/baoyu-gemini-web --prompt "一只可爱的猫" --image cat.png
+/baoyu-gemini-web --promptfiles system.md content.md --image out.png
+```
+
+### baoyu-xhs-images
+
+小红书信息图系列生成器。将内容拆解为 1-10 张卡通风格信息图，支持 **风格 × 布局** 二维系统。
+
+```bash
+# 自动选择风格和布局
+/baoyu-xhs-images posts/ai-future/article.md
+
+# 指定风格
+/baoyu-xhs-images posts/ai-future/article.md --style notion
+
+# 指定布局
+/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 今日星座运势
+```
+
+**风格**（视觉美学）：`cute`（默认）、`fresh`、`tech`、`warm`、`bold`、`minimal`、`retro`、`pop`、`notion`
+
+**布局**（信息密度）：
+| 布局 | 密度 | 适用场景 |
+|------|------|----------|
+| `sparse` | 1-2 点 | 封面、金句 |
+| `balanced` | 3-4 点 | 常规内容 |
+| `dense` | 5-8 点 | 知识卡片、干货总结 |
+| `list` | 4-7 项 | 清单、排行 |
+| `comparison` | 双栏 | 对比、优劣 |
+| `flow` | 3-6 步 | 流程、时间线 |
+
+### baoyu-cover-image
+
+为文章生成手绘风格封面图，支持多种风格选项。
+
+```bash
+# 从 markdown 文件生成（自动选择风格）
+/baoyu-cover-image path/to/article.md
+
+# 指定风格
+/baoyu-cover-image path/to/article.md --style tech
+/baoyu-cover-image path/to/article.md --style warm
+
+# 不包含标题文字
+/baoyu-cover-image path/to/article.md --no-title
+```
+
+可用风格：`elegant`（默认）、`tech`、`warm`、`bold`、`minimal`、`playful`、`nature`、`retro`
+
+### baoyu-slide-deck
+
+从内容生成专业的幻灯片图片。先创建包含样式说明的完整大纲，然后逐页生成幻灯片图片。
+
+```bash
+# 从 markdown 文件生成
+/baoyu-slide-deck path/to/article.md
+
+# 指定风格和受众
+/baoyu-slide-deck path/to/article.md --style corporate
+/baoyu-slide-deck path/to/article.md --audience executives
+
+# 仅生成大纲（不生成图片）
+/baoyu-slide-deck path/to/article.md --outline-only
+
+# 指定语言
+/baoyu-slide-deck path/to/article.md --lang zh
+```
+
+**风格**（视觉美学）：
+
+| 风格 | 描述 | 适用场景 |
+|------|------|----------|
+| `notion`（默认） | SaaS 仪表盘美学，卡片式布局，数据展示清晰 | 产品演示、SaaS、生产力工具、B2B |
+| `sketch-notes` | 手绘风格，柔和笔触，暖白色背景 | 教育、教程、知识分享 |
+| `blueprint` | 技术蓝图风格，网格纹理，工程精度 | 架构设计、系统设计、数据分析 |
+| `bold-editorial` | 杂志社论风格，粗体排版，深色背景，高冲击力 | 产品发布、营销、主题演讲 |
+| `vector-illustration` | 扁平矢量风格，黑色轮廓线，复古柔和配色，玩具模型感 | 创意提案、儿童内容、说明性内容 |
+| `minimal` | 极简风格，大量留白，单一强调色，禅意美学 | 高管简报、主题演讲、高端品牌 |
+| `storytelling` | 电影风格，全幅视觉，情感化摄影 | 案例研究、叙事、客户旅程 |
+| `warm` | 柔和渐变，圆润形状，健康生活配色 | 生活方式、健康养生、个人成长 |
+| `corporate` | 海军蓝/金色配色，结构化布局，专业图标 | 投资者演示、客户提案、季度报告 |
+| `playful` | 活力珊瑚/青色/黄色，圆润形状，动感布局 | 工作坊、培训、创意提案 |
+
+生成完成后，所有幻灯片会自动合并为 `.pptx` 文件，方便分享。
+
+### baoyu-comic
+
+知识漫画创作器，支持多种风格（Logicomix/清线风格、欧姆社漫画教程风格）。创作带有详细分镜布局的原创教育漫画，逐页生成图片。
+
+```bash
+# 从素材文件生成
+/baoyu-comic posts/turing-story/source.md
+
+# 指定风格
+/baoyu-comic posts/turing-story/source.md --style dramatic
+/baoyu-comic posts/turing-story/source.md --style ohmsha
+
+# 自定义风格（自然语言描述）
+/baoyu-comic posts/turing-story/source.md --style "水彩风格，边缘柔和"
+
+# 指定布局和比例
+/baoyu-comic posts/turing-story/source.md --layout cinematic
+/baoyu-comic posts/turing-story/source.md --aspect 16:9
+
+# 指定语言
+/baoyu-comic posts/turing-story/source.md --lang zh
+
+# 直接输入内容
+/baoyu-comic "图灵的故事与计算机科学的诞生"
+```
+
+**选项**：
+| 选项 | 取值 |
+|------|------|
+| `--style` | `classic`（默认）、`dramatic`、`warm`、`tech`、`sepia`、`vibrant`、`ohmsha`、`realistic`，或自然语言描述 |
+| `--layout` | `standard`（默认）、`cinematic`、`dense`、`splash`、`mixed`、`webtoon` |
+| `--aspect` | `3:4`（默认，竖版）、`4:3`（横版）、`16:9`（宽屏） |
+| `--lang` | `auto`（默认）、`zh`、`en`、`ja` 等 |
+
+**风格**（视觉美学）：
+
+| 风格 | 描述 | 适用场景 |
+|------|------|----------|
+| `classic`（默认） | 传统清线风格，统一线条、平涂色彩、精细背景 | 传记、平衡叙事、教育内容 |
+| `dramatic` | 高对比度，重阴影、紧张表情、棱角分明的构图 | 重大发现、冲突、高潮场景 |
+| `warm` | 柔和边缘、金色调、温馨室内、怀旧感 | 个人故事、童年场景、师生情 |
+| `tech` | 精确几何线条、电路纹理、深色背景配霓虹色 | 计算机史、AI 故事、现代科技 |
+| `sepia` | 复古插画风格、做旧纸张效果、时代准确细节 | 1950 年前故事、古典科学、历史人物 |
+| `vibrant` | 富有活力的线条、明亮色彩、动感姿态 | 科学解说、"顿悟"时刻、青少年读者 |
+| `ohmsha` | 欧姆社漫画风格，视觉比喻、道具、学生/导师互动 | 技术教程、复杂概念（机器学习、物理） |
+| `realistic` | 全彩写实日漫风格，数字绘画、平滑渐变、准确人体比例 | 红酒、美食、商业、生活方式、专业话题 |
+
+**布局**（分镜排列）：
+| 布局 | 每页分镜数 | 适用场景 |
+|------|-----------|----------|
+| `standard` | 4-6 | 对话、叙事推进 |
+| `cinematic` | 2-4 | 戏剧性时刻、建立镜头 |
+| `dense` | 6-9 | 技术说明、时间线 |
+| `splash` | 1-2 大图 | 关键时刻、揭示 |
+| `mixed` | 3-7 不等 | 复杂叙事、情感弧线 |
+| `webtoon` | 3-5 竖向 | 欧姆社教程、手机阅读 |
+
+### baoyu-post-to-wechat
+
+发布内容到微信公众号，支持两种模式：
+
+**图文模式** - 多图配短标题和正文：
+
+```bash
+/baoyu-post-to-wechat 图文 --markdown article.md --images ./photos/
+/baoyu-post-to-wechat 图文 --markdown article.md --image img1.png --image img2.png --image img3.png
+/baoyu-post-to-wechat 图文 --title "标题" --content "内容" --image img1.png --submit
+```
+
+**文章模式** - 完整 markdown/HTML 富文本格式：
+
+```bash
+/baoyu-post-to-wechat 文章 --markdown article.md
+/baoyu-post-to-wechat 文章 --markdown article.md --theme grace
+/baoyu-post-to-wechat 文章 --html article.html
+```
+
+前置要求：已安装 Google Chrome，首次运行需扫码登录（登录状态会保存）
+
+## 自定义扩展
+
+所有技能支持通过 `EXTEND.md` 文件自定义。创建扩展文件可覆盖默认样式、添加自定义配置或定义个人预设。
+
+**扩展路径**（按优先级检查）：
+1. `.baoyu-skills/<skill-name>/EXTEND.md` - 项目级（团队/项目特定设置）
+2. `~/.baoyu-skills/<skill-name>/EXTEND.md` - 用户级（个人偏好设置）
+
+**示例**：为 `baoyu-cover-image` 自定义品牌配色：
+
+```bash
+mkdir -p .baoyu-skills/baoyu-cover-image
+```
+
+然后创建 `.baoyu-skills/baoyu-cover-image/EXTEND.md`：
+
+```markdown
+## 自定义风格
+
+### brand
+- 主色：#1a73e8
+- 辅色：#34a853
+- 字体风格：现代无衬线
+- 始终包含公司 logo 水印
+```
+
+扩展内容会在技能执行前加载，并覆盖默认设置。
+
+## 免责声明
+
+### baoyu-gemini-web
+
+此技能使用 Gemini Web API（逆向工程）。
+
+**警告：** 本项目通过浏览器 cookies 使用非官方 API。使用风险自负。
+
+- 首次运行会打开 Chrome 进行 Google 身份验证
+- Cookies 会被缓存供后续使用
+- 不保证 API 的稳定性或可用性
+
+## 许可证
+
+MIT
@@ -0,0 +1,461 @@
+---
+name: baoyu-article-illustrator
+description: Smart article illustration skill. Analyzes article content and generates illustrations at positions requiring visual aids with multiple style options. Use when user asks to "add illustrations to article", "generate images for article", or "illustrate article".
+---
+
+# Smart Article Illustration Skill
+
+Analyze article structure and content, identify positions requiring visual aids, and generate illustrations with flexible style options.
+
+## Usage
+
+```bash
+# Auto-select style based on content
+/baoyu-article-illustrator path/to/article.md
+
+# Specify a style
+/baoyu-article-illustrator path/to/article.md --style tech
+/baoyu-article-illustrator path/to/article.md --style warm
+/baoyu-article-illustrator path/to/article.md --style minimal
+
+# Combine with other options
+/baoyu-article-illustrator path/to/article.md --style playful
+```
+
+## Options
+
+| Option | Description |
+|--------|-------------|
+| `--style <name>` | Specify illustration style (see Style Gallery below) |
+
+## Style Gallery
+
+### 1. `elegant`
+Refined, sophisticated, professional
+- **Colors**: Soft coral, muted teal, dusty rose, cream background
+- **Elements**: Delicate line work, subtle icons, balanced composition
+- **Best for**: Professional articles, thought leadership, business topics
+
+### 2. `tech`
+Modern, futuristic, digital
+- **Colors**: Deep blue, electric cyan, purple, dark backgrounds
+- **Elements**: Geometric shapes, circuit patterns, data visualizations, tech icons
+- **Best for**: AI, programming, technology, digital transformation articles
+
+### 3. `warm`
+Friendly, approachable, human-centered
+- **Colors**: Warm orange, golden yellow, terracotta, cream
+- **Elements**: Rounded shapes, friendly characters, sun/light motifs, hearts
+- **Best for**: Personal growth, lifestyle, education, human interest stories
+
+### 4. `bold`
+High contrast, impactful, energetic
+- **Colors**: Vibrant red/orange, deep black, bright yellow accents
+- **Elements**: Strong shapes, dramatic contrast, dynamic compositions
+- **Best for**: Opinion pieces, important warnings, call-to-action content
+
+### 5. `minimal`
+Ultra-clean, zen-like, focused
+- **Colors**: Black, white, single accent color
+- **Elements**: Maximum whitespace, single focal element, simple lines
+- **Best for**: Philosophy, minimalism, focused explanations
+
+### 6. `playful`
+Fun, creative, whimsical
+- **Colors**: Pastel rainbow, bright pops, light backgrounds
+- **Elements**: Doodles, quirky characters, speech bubbles, emoji-style icons
+- **Best for**: Tutorials, beginner guides, casual content, fun topics
+
+### 7. `nature`
+Organic, calm, earthy
+- **Colors**: Forest green, earth brown, sky blue, sand beige
+- **Elements**: Plant motifs, natural textures, flowing lines, organic shapes
+- **Best for**: Sustainability, wellness, outdoor topics, slow living
+
+### 8. `sketch`
+Raw, authentic, notebook-style
+- **Colors**: Pencil gray, paper white, occasional color highlights
+- **Elements**: Rough lines, sketch marks, handwritten notes, arrows
+- **Best for**: Ideas in progress, brainstorming, thought processes
+
+### 9. `notion` (Default)
+Minimalist hand-drawn line art, intellectual
+- **Colors**: Black outlines, white background, 1-2 pastel accents
+- **Elements**: Simple line doodles, geometric shapes, hand-drawn wobble, maximum whitespace
+- **Best for**: Knowledge sharing, concept explanations, SaaS content, productivity articles
+
+## Auto Style Selection
+
+When no `--style` is specified, analyze content to select the best style:
+
+| Content Signals | Selected Style |
+|----------------|----------------|
+| AI, coding, tech, digital, algorithm, data | `tech` |
+| Personal story, emotion, growth, life, feeling | `warm` |
+| Warning, urgent, must-read, critical, important | `bold` |
+| Simple, zen, focus, essential, core | `minimal` |
+| Fun, easy, beginner, tutorial, guide, how-to | `playful` |
+| Nature, eco, wellness, health, organic, green | `nature` |
+| Idea, thought, concept, draft, brainstorm | `sketch` |
+| Business, professional, strategy, analysis | `elegant` |
+| Knowledge, concept, productivity, SaaS, notion | `notion` |
+
+## File Management
+
+### With Article Path
+
+Save illustrations to `[source-name-no-ext]/illustrations/` subdirectory in the same folder as the article:
+
+```
+path/to/
+├── article.md
+└── article/
+    └── illustrations/
+        ├── outline.md
+        ├── prompts/
+        │   ├── illustration-concept-a.md
+        │   ├── illustration-concept-b.md
+        │   └── ...
+        ├── illustration-concept-a.png
+        ├── illustration-concept-b.png
+        └── ...
+```
+
+Example: `/posts/ai-future.md` → `/posts/ai-future/illustrations/`
+
+### Without Article Path (Pasted Content)
+
+Save to `./illustrations/[topic-slug]/`:
+
+```
+illustrations/
+└── ai-future/
+    ├── source.md
+    ├── outline.md
+    ├── prompts/
+    └── *.png
+```
+
+### Directory Backup
+
+If target directory exists, rename existing to `<dirname>-backup-YYYYMMDD-HHMMSS`
+
+## Workflow
+
+### Step 1: Analyze Content & Select Style
+
+1. Read article content
+2. If `--style` specified, use that style
+3. Otherwise, scan for style signals and auto-select
+4. **Language detection**:
+   - Detect **source language** from article content
+   - Detect **user language** from conversation context
+   - Note if source_language ≠ user_language (will ask in Step 4)
+5. Extract key information:
+   - Main topic and themes
+   - Core messages per section
+   - Abstract concepts needing visualization
+
+### Step 2: Identify Illustration Positions
+
+**Three Purposes of Illustrations**:
+1. **Information Supplement**: Help understand abstract concepts
+2. **Concept Visualization**: Transform abstract ideas into concrete visuals
+3. **Imagination Guidance**: Create atmosphere, enhance reading experience
+
+**Content Suitable for Illustrations**:
+- Abstract concepts needing visualization
+- Processes/steps needing diagrams
+- Comparisons needing visual representation
+- Core arguments needing reinforcement
+- Scenarios needing imagination guidance
+
+**Illustration Count**:
+- Consider at least 1 image per major section
+- Prioritize core arguments and abstract concepts
+- **Principle: More is better than fewer**
+
+### Step 3: Generate Illustration Plan
+
+```markdown
+# Illustration Plan
+
+**Article**: [article path]
+**Style**: [selected style]
+**Illustration Count**: N images
+
+---
+
+## Illustration 1
+
+**Insert Position**: [section name] / [paragraph description]
+**Purpose**: [why illustration needed here]
+**Visual Content**: [what the image should show]
+**Filename**: illustration-[slug].png
+
+---
+
+## Illustration 2
+...
+```
+
+### Step 4: Review & Confirm
+
+**Purpose**: Let user confirm all options in a single step before image generation.
+
+**IMPORTANT**: Present ALL options in a single confirmation step using AskUserQuestion. Do NOT interrupt workflow with multiple separate confirmations.
+
+1. **Generate 3 style variants**:
+   - Analyze content to select 3 most suitable styles
+   - Generate complete illustration plan for each style variant
+   - Save as `outline-{style}.md` (e.g., `outline-notion.md`, `outline-tech.md`, `outline-warm.md`)
+
+2. **Determine which questions to ask**:
+
+   | Question | When to Ask |
+   |----------|-------------|
+   | Style variant | Always (required) |
+   | Language | Only if `source_language ≠ user_language` |
+
+3. **Present options** (use AskUserQuestion with all applicable questions):
+
+   **Question 1 (Style)** - always:
+   - Style A (recommended): [style name] - [brief description]
+   - Style B: [style name] - [brief description]
+   - Style C: [style name] - [brief description]
+   - Custom: Provide custom style reference
+
+   **Question 2 (Language)** - only if source ≠ user language:
+   - [Source language] (matches article language)
+   - [User language] (your preference)
+
+   **Language handling**:
+   - If source language = user language: Just inform user (e.g., "Prompts will be in Chinese")
+   - If different: Ask which language to use for prompts
+
+4. **Apply selection**:
+   - Copy selected `outline-{style}.md` to `outline.md`
+   - If custom style provided, generate new plan with that style
+   - If different language selected, regenerate outline in that language
+   - User may edit `outline.md` directly for fine-tuning
+   - If modified, reload plan before proceeding
+
+5. **Proceed only after explicit user confirmation**
+
+### Step 5: Create Prompt Files
+
+Save prompts to `prompts/` directory with style-specific details.
+
+**All prompts are written in the user's confirmed language preference.**
+
+**Prompt Format**:
+
+```markdown
+Illustration theme: [concept in 2-3 words]
+Style: [style name]
+
+Visual composition:
+- Main visual: [description matching style]
+- Layout: [element positioning]
+- Decorative elements: [style-appropriate decorations]
+
+Color scheme:
+- Primary: [style primary color]
+- Background: [style background color]
+- Accent: [style accent color]
+
+Text content (if any):
+- [Any labels or captions in content language]
+
+Style notes: [specific style characteristics]
+```
+
+### Step 6: Generate Images
+
+**Image Generation Skill Selection**:
+1. Check available image generation skills
+2. If multiple skills available, ask user to choose
+
+**Generation Flow**:
+1. Call selected image generation skill with prompt file and output path
+2. Generate images sequentially
+3. After each image, output progress: "Generated X/N"
+4. On failure, auto-retry once
+5. If retry fails, log reason, continue to next
+
+### Step 7: Update Article
+
+Insert generated images at corresponding positions:
+
+```markdown
+![illustration description]([article-name]/illustrations/illustration-[slug].png)
+```
+
+**Insertion Rules**:
+- Insert image after corresponding paragraph
+- Leave one blank line before and after image
+- Alt text uses concise description in article's language
+
+### Step 8: Output Summary
+
+```
+Article Illustration Complete!
+
+Article: [article path]
+Style: [style name]
+Generated: X/N images successful
+
+Illustration Positions:
+- illustration-xxx.png → After section "Section Name"
+- illustration-yyy.png → After section "Another Section"
+...
+
+[If any failures]
+Failed:
+- illustration-zzz.png: [failure reason]
+```
+
+## Illustration Modification
+
+Support for modifying individual illustrations after initial generation.
+
+### Edit Single Illustration
+
+Regenerate a specific illustration with modified prompt:
+
+1. Identify illustration to edit (e.g., `illustration-concept-overview.png`)
+2. Update prompt in `prompts/illustration-concept-overview.md` if needed
+3. If content changes significantly, update slug in filename
+4. Regenerate image
+5. Update article if image reference changed
+
+### Add New Illustration
+
+Add a new illustration to the article:
+
+1. Identify insertion position in article
+2. Create new prompt with appropriate slug (e.g., `illustration-new-concept.md`)
+3. Generate new illustration image
+4. Update `outline.md` with new illustration entry
+5. Insert image reference in article at the specified position
+
+### Delete Illustration
+
+Remove an illustration from the article:
+
+1. Identify illustration to delete (e.g., `illustration-concept-overview.png`)
+2. Remove image file and prompt file
+3. Remove image reference from article
+4. Update `outline.md` to remove illustration entry
+
+### File Naming Convention
+
+Files use meaningful slugs for better readability:
+```
+illustration-[slug].png
+illustration-[slug].md (in prompts/)
+```
+
+Examples:
+- `illustration-concept-overview.png`
+- `illustration-workflow-diagram.png`
+- `illustration-key-benefits.png`
+
+**Slug rules**:
+- Derived from illustration purpose/content (kebab-case)
+- Must be unique within the article
+- When content changes significantly, update slug accordingly
+
+## Style Reference Details
+
+### elegant
+```
+Colors: Soft coral (#E8A598), muted teal (#5B8A8A), dusty rose (#D4A5A5)
+Background: Warm cream (#F5F0E6), soft beige
+Accents: Gold (#C9A962), copper
+Elements: Delicate lines, refined icons, subtle gradients, balanced whitespace
+```
+
+### tech
+```
+Colors: Deep blue (#1A365D), electric cyan (#00D4FF), purple (#6B46C1)
+Background: Dark gray (#1A202C), near-black (#0D1117)
+Accents: Neon green (#00FF88), bright white
+Elements: Circuit patterns, data nodes, geometric grids, glowing effects
+```
+
+### warm
+```
+Colors: Warm orange (#ED8936), golden yellow (#F6AD55), terracotta (#C05621)
+Background: Cream (#FFFAF0), soft peach (#FED7AA)
+Accents: Deep brown (#744210), soft red
+Elements: Rounded shapes, smiling faces, sun rays, hearts, cozy lighting
+```
+
+### bold
+```
+Colors: Vibrant red (#E53E3E), bright orange (#DD6B20), electric yellow (#F6E05E)
+Background: Deep black (#000000), dark charcoal
+Accents: White, neon highlights
+Elements: Strong shapes, exclamation marks, arrows, dramatic contrast
+```
+
+### minimal
+```
+Colors: Pure black (#000000), white (#FFFFFF)
+Background: White or off-white (#FAFAFA)
+Accents: Single color (content-derived)
+Elements: Single focal point, maximum negative space, thin precise lines
+```
+
+### playful
+```
+Colors: Pastel pink (#FED7E2), mint (#C6F6D5), lavender (#E9D8FD), sky blue (#BEE3F8)
+Background: Light cream (#FFFBEB), soft white
+Accents: Bright pops - yellow, coral, turquoise
+Elements: Doodles, stars, swirls, cute characters, speech bubbles
+```
+
+### nature
+```
+Colors: Forest green (#276749), sage (#9AE6B4), earth brown (#744210)
+Background: Sand beige (#F5E6D3), sky blue (#E0F2FE)
+Accents: Sunset orange, water blue
+Elements: Leaves, trees, mountains, organic flowing lines, natural textures
+```
+
+### sketch
+```
+Colors: Pencil gray (#4A5568), paper white (#FAFAFA)
+Background: Off-white paper texture (#F7FAFC)
+Accents: Single highlight color (blue, red, or yellow)
+Elements: Rough sketch lines, arrows, handwritten labels, crossed-out marks
+```
+
+### notion
+```
+Colors: Black (#1A1A1A), dark gray (#4A4A4A)
+Background: Pure white (#FFFFFF), off-white (#FAFAFA)
+Accents: Pastel blue (#A8D4F0), pastel yellow (#F9E79F), pastel pink (#FADBD8)
+Elements: Simple line doodles, hand-drawn wobble effect, geometric shapes, stick figures, maximum whitespace
+Typography: Clean hand-drawn lettering, simple sans-serif labels
+```
+
+## Notes
+
+- Illustrations serve the content: supplement information, visualize concepts
+- Maintain selected style consistency across all illustrations in one article
+- Image generation typically takes 10-30 seconds per image
+- Sensitive figures should use cartoon alternatives
+- Prompts written in user's confirmed language preference
+- Illustration text (labels, captions) should match article language
+
+## Extension Support
+
+Custom styles and configurations via EXTEND.md.
+
+**Check paths** (priority order):
+1. `.baoyu-skills/baoyu-article-illustrator/EXTEND.md` (project)
+2. `~/.baoyu-skills/baoyu-article-illustrator/EXTEND.md` (user)
+
+If found, load before Step 1. Extension content overrides defaults.
@@ -0,0 +1,32 @@
+Create a cartoon-style infographic illustration following these guidelines:
+
+## Image Specifications
+
+- **Type**: Infographic illustration
+- **Orientation**: Landscape (horizontal)
+- **Aspect Ratio**: 16:9
+- **Style**: Hand-drawn illustration
+
+## Core Principles
+
+- Hand-drawn quality throughout - NO realistic or photographic elements
+- If content involves sensitive or copyrighted figures, create stylistically similar alternatives - DO NOT refuse to generate
+- Keep information concise, highlight keywords and core concepts
+- Use ample whitespace for easy visual scanning
+- Maintain clear visual hierarchy
+
+## Text Style (When Text Included)
+
+- **ALL text MUST be hand-drawn style**
+- Text should be readable and complement the visual
+- Font style harmonizes with illustration style
+- **DO NOT use realistic or computer-generated fonts**
+
+## Language
+
+- Use the same language as the content provided below for any text elements
+- Match punctuation style to the content language
+
+---
+
+Please use nano banana pro to generate the illustration based on the content provided below:
@@ -0,0 +1,400 @@
+---
+name: baoyu-comic
+description: Knowledge comic creator supporting multiple styles (Logicomix/Ligne Claire, Ohmsha manga guide). Creates original educational comics with detailed panel layouts and sequential image generation. Use when user asks to create "知识漫画", "教育漫画", "biography comic", "tutorial comic", or "Logicomix-style comic".
+---
+
+# Knowledge Comic Creator
+
+Create original knowledge comics with multiple visual styles.
+
+## Usage
+
+```bash
+/baoyu-comic posts/turing-story/source.md
+/baoyu-comic  # then paste content
+```
+
+## Options
+
+| Option | Values |
+|--------|--------|
+| `--style` | classic (default), dramatic, warm, tech, sepia, vibrant, ohmsha, realistic, or custom description |
+| `--layout` | standard (default), cinematic, dense, splash, mixed, webtoon |
+| `--aspect` | 3:4 (default, portrait), 4:3 (landscape), 16:9 (widescreen) |
+| `--lang` | auto (default), zh, en, ja, etc. |
+
+Style × Layout × Aspect can be freely combined. Custom styles can be described in natural language.
+
+**Aspect ratio is consistent across all pages in a comic.**
+
+## Auto Selection
+
+| Content Signals | Style | Layout |
+|-----------------|-------|--------|
+| Tutorial, how-to, beginner | ohmsha | webtoon |
+| Computing, AI, programming | tech | dense |
+| Pre-1950, classical, ancient | sepia | cinematic |
+| Personal story, mentor | warm | standard |
+| Conflict, breakthrough | dramatic | splash |
+| Wine, food, business, lifestyle, professional | realistic | cinematic |
+| Biography, balanced | classic | mixed |
+
+## 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. Replace all `${SKILL_DIR}` in this document with the actual path
+
+**Script Reference**:
+| Script | Purpose |
+|--------|---------|
+| `scripts/merge-to-pdf.ts` | Merge comic pages into PDF |
+
+## File Structure
+
+```
+[target]/
+├── source.md                      # Source content (if pasted, not file)
+├── analysis.md                    # Deep analysis results (YAML+MD)
+├── storyboard-chronological.md    # Variant A (preserved)
+├── storyboard-thematic.md         # Variant B (preserved)
+├── storyboard-character.md        # Variant C (preserved)
+├── characters-chronological/      # Variant A chars (preserved)
+│   ├── characters.md
+│   └── characters.png
+├── characters-thematic/           # Variant B chars (preserved)
+│   ├── characters.md
+│   └── characters.png
+├── characters-character/          # Variant C chars (preserved)
+│   ├── characters.md
+│   └── characters.png
+├── storyboard.md                  # Final selected
+├── characters/                    # Final selected
+│   ├── characters.md
+│   └── characters.png
+├── prompts/
+│   ├── 00-cover-[slug].md
+│   └── NN-page-[slug].md
+├── 00-cover-[slug].png
+├── NN-page-[slug].png
+└── {topic-slug}.pdf
+```
+
+**Target directory**:
+- With source path: `[source-dir]/[source-name-no-ext]/comic/`
+  - Example: `/posts/turing-story.md` → `/posts/turing-story/comic/`
+- Without source: `./comic/[topic-slug]/`
+
+**Directory backup**:
+- If target directory exists, rename existing to `<dirname>-backup-YYYYMMDD-HHMMSS`
+
+## Workflow
+
+### Step 1: Analyze Content → `analysis.md`
+
+Read source content, save it if needed, and perform deep analysis.
+
+**Actions**:
+1. **Save source content** (if not already a file):
+   - If user provides a file path: use as-is
+   - If user pastes content: save to `source.md` in target directory
+2. Read source content
+3. **Deep analysis** following `references/analysis-framework.md`:
+   - Target audience identification
+   - Value proposition for readers
+   - Core themes and narrative potential
+   - Key figures and their story arcs
+4. Detect source language
+5. Determine recommended page count:
+   - Short story: 5-8 pages
+   - Medium complexity: 9-15 pages
+   - Full biography: 16-25 pages
+6. Analyze content signals for style/layout recommendations
+7. **Save to `analysis.md`**
+
+**analysis.md Format**:
+
+```yaml
+---
+title: "Alan Turing: Father of Computing"
+topic: Biography
+time_span: 1912-1954
+source_language: en
+user_language: zh
+aspect_ratio: "3:4"
+recommended_page_count: 12
+---
+
+## Target Audience
+
+- **Primary**: Tech enthusiasts curious about computing history
+- **Secondary**: Students learning about scientific breakthroughs
+- **Tertiary**: General readers interested in biographical stories
+
+## Value Proposition
+
+What readers will gain:
+1. Understanding of how modern computing was born
+2. Emotional connection to a brilliant but tragic figure
+3. Appreciation for the human cost of innovation
+
+## Core Themes
+
+| Theme | Narrative Potential | Visual Opportunity |
+|-------|--------------------|--------------------|
+| Genius vs. Society | High conflict, dramatic arcs | Contrast scenes |
+| Code-breaking | Mystery, tension | Technical diagrams as art |
+| Personal tragedy | Emotional depth | Intimate, somber panels |
+
+## Key Figures & Story Arcs
+
+### Alan Turing (Protagonist)
+- **Arc**: Misunderstood genius → War hero → Tragic end
+- **Visual identity**: Disheveled academic, intense eyes
+- **Key moments**: Enigma breakthrough, arrest, final days
+
+### Christopher Morcom (Catalyst)
+- **Role**: Early friend whose death shaped Turing
+- **Visual identity**: Youthful, bright
+- **Key moments**: School friendship, sudden death
+
+## Content Signals
+
+- "biography" → classic + mixed
+- "computing history" → tech + dense
+- "personal tragedy" → dramatic + splash
+
+## Recommended Approaches
+
+1. **Chronological** - follow life timeline (recommended for biography)
+2. **Thematic** - organize by contributions (good for educational focus)
+3. **Character-focused** - relationships drive narrative (good for emotional impact)
+```
+
+### Step 2: Generate 3 Storyboard Variants
+
+Create three distinct variants, each combining a narrative approach with a recommended style.
+
+| Variant | Narrative Approach | Recommended Style | Layout |
+|---------|-------------------|-------------------|--------|
+| A | Chronological | sepia | cinematic |
+| B | Thematic | tech | dense |
+| C | Character-focused | warm | standard |
+
+**For each variant**:
+
+1. **Generate storyboard** (`storyboard-{approach}.md`):
+   - YAML front matter with narrative_approach, recommended_style, recommended_layout, aspect_ratio
+   - Cover design
+   - Each page: layout, panel breakdown, visual prompts
+   - **Written in user's preferred language**
+   - Reference: `references/storyboard-template.md`
+
+2. **Generate matching characters** (`characters-{approach}/`):
+   - `characters.md` - visual specs matching the recommended style (in user's preferred language)
+   - `characters.png` - character reference sheet
+   - Reference: `references/character-template.md`
+
+**All variants are preserved after selection for reference.**
+
+### Step 3: User Confirms All Options
+
+**IMPORTANT**: Present ALL options in a single confirmation step using AskUserQuestion. Do NOT interrupt workflow with multiple separate confirmations.
+
+**Determine which questions to ask**:
+
+| Question | When to Ask |
+|----------|-------------|
+| Storyboard variant | Always (required) |
+| Visual style | Always (required) |
+| Language | Only if `source_language ≠ user_language` |
+| Aspect ratio | Only if user might prefer non-default (e.g., landscape content) |
+
+**Language handling**:
+- If source language = user language: Just inform user (e.g., "Comic will be in Chinese")
+- If different: Ask which language to use
+
+**All storyboards and prompts are generated in the user's selected/preferred language.**
+
+**Aspect ratio handling**:
+- Default: 3:4 (portrait) - standard comic format
+- Offer 4:3 (landscape) if content suits it (e.g., panoramic scenes, technical diagrams)
+- Offer 16:9 (widescreen) for cinematic content
+
+**AskUserQuestion format** (example with all questions):
+
+```
+Question 1 (Storyboard): Which storyboard variant?
+- A: Chronological + sepia (Recommended)
+- B: Thematic + tech
+- C: Character-focused + warm
+- Custom
+
+Question 2 (Style): Which visual style?
+- sepia (Recommended from variant)
+- classic / dramatic / warm / tech / vibrant / ohmsha / realistic
+- Custom description
+
+Question 3 (Language) - only if mismatch:
+- Chinese (source material language)
+- English (your preference)
+
+Question 4 (Aspect) - only if relevant:
+- 3:4 Portrait (Recommended)
+- 4:3 Landscape
+- 16:9 Widescreen
+```
+
+**After confirmation**:
+1. Copy selected storyboard → `storyboard.md`
+2. Copy selected characters → `characters/`
+3. Update YAML front matter with confirmed style, language, aspect_ratio
+4. If style differs from variant's recommended: regenerate `characters/characters.png`
+5. User may edit files directly for fine-tuning
+
+### Step 4: Generate Images
+
+With confirmed storyboard + style + aspect ratio:
+
+**For each page (cover + pages)**:
+1. Save prompt to `prompts/NN-{cover|page}-[slug].md` (in user's preferred language)
+2. Generate image using confirmed style and aspect ratio
+3. Report progress after each generation
+
+**Image Generation Skill Selection**:
+- Check available image generation skills
+- If multiple skills available, ask user preference
+
+**Character Reference Handling**:
+- If skill supports reference image: pass `characters/characters.png`
+- If skill does NOT support reference image: include `characters/characters.md` content in prompt
+
+**Session Management**:
+If image generation skill supports `--sessionId`:
+1. Generate unique session ID: `comic-{topic-slug}-{timestamp}`
+2. Use same session ID for all pages
+3. Ensures visual consistency across generated images
+
+### Step 5: Merge to PDF
+
+After all images generated:
+
+```bash
+npx -y bun ${SKILL_DIR}/scripts/merge-to-pdf.ts <comic-dir>
+```
+
+Creates `{topic-slug}.pdf` with all pages as full-page images.
+
+### Step 6: Completion Report
+
+```
+Comic Complete!
+Title: [title] | Style: [style] | Pages: [count] | Aspect: [ratio] | Language: [lang]
+Location: [path]
+✓ analysis.md
+✓ characters.png
+✓ 00-cover-[slug].png ... NN-page-[slug].png
+✓ {topic-slug}.pdf
+```
+
+## Page Modification
+
+Support for modifying individual pages after initial generation.
+
+### Edit Single Page
+
+Regenerate a specific page with modified prompt:
+
+1. Identify page to edit (e.g., `03-page-enigma-machine.png`)
+2. Update prompt in `prompts/03-page-enigma-machine.md` if needed
+3. If content changes significantly, update slug in filename
+4. Regenerate image using same session ID and aspect ratio
+5. Regenerate PDF
+
+### Add New Page
+
+Insert a new page at specified position:
+
+1. Specify insertion position (e.g., after page 3)
+2. Create new prompt with appropriate slug (e.g., `04-page-bletchley-park.md`)
+3. Generate new page image (same aspect ratio)
+4. **Renumber files**: All subsequent pages increment NN by 1
+   - `04-page-tragedy.png` → `05-page-tragedy.png`
+   - Slugs remain unchanged
+5. Update `storyboard.md` with new page entry
+6. Regenerate PDF
+
+### Delete Page
+
+Remove a page and renumber:
+
+1. Identify page to delete (e.g., `03-page-enigma-machine.png`)
+2. Remove image file and prompt file
+3. **Renumber files**: All subsequent pages decrement NN by 1
+   - `04-page-tragedy.png` → `03-page-tragedy.png`
+   - Slugs remain unchanged
+4. Update `storyboard.md` to remove page entry
+5. Regenerate PDF
+
+### File Naming Convention
+
+Files use meaningful slugs for better readability:
+```
+NN-cover-[slug].png / NN-page-[slug].png
+NN-cover-[slug].md / NN-page-[slug].md (in prompts/)
+```
+
+Examples:
+- `00-cover-turing-story.png`
+- `01-page-early-life.png`
+- `02-page-cambridge-years.png`
+- `03-page-enigma-machine.png`
+
+**Slug rules**:
+- Derived from page title/content (kebab-case)
+- Must be unique within the comic
+- When page content changes significantly, update slug accordingly
+
+**Renumbering**:
+- After add/delete, update NN prefix for affected pages
+- Slug remains unchanged unless content changes
+- Maintain sequential numbering with no gaps
+
+## Style-Specific Guidelines
+
+### Ohmsha Style (`--style ohmsha`)
+
+Additional requirements for educational manga:
+- **Default: Use Doraemon characters directly** - No need to create new characters
+  - 大雄 (Nobita): Student role, curious learner
+  - 哆啦A梦 (Doraemon): Mentor role, explains concepts with gadgets
+  - 胖虎 (Gian): Antagonist/challenge role, represents obstacles or misconceptions
+  - 静香 (Shizuka): Supporting role, asks clarifying questions
+- Custom characters only if explicitly requested: `--characters "Student:小明,Mentor:教授"`
+- Must use visual metaphors (gadgets, action scenes) - NO talking heads
+- Page titles: narrative style, not "Page X: Topic"
+
+**Reference**: `references/ohmsha-guide.md` for detailed guidelines.
+
+## References
+
+Detailed templates and guidelines in `references/` directory:
+- `analysis-framework.md` - Deep content analysis for comic adaptation
+- `character-template.md` - Character definition format and examples
+- `storyboard-template.md` - Storyboard structure and panel breakdown
+- `ohmsha-guide.md` - Ohmsha manga style specifics
+- `styles/` - Detailed style definitions
+- `layouts/` - Detailed layout definitions
+
+## Extension Support
+
+Custom styles and configurations via EXTEND.md.
+
+**Check paths** (priority order):
+1. `.baoyu-skills/baoyu-comic/EXTEND.md` (project)
+2. `~/.baoyu-skills/baoyu-comic/EXTEND.md` (user)
+
+If found, load before Step 1. Extension content overrides defaults.
@@ -0,0 +1,152 @@
+# Comic Content Analysis Framework
+
+Deep analysis framework for transforming source content into effective visual storytelling.
+
+## Purpose
+
+Before creating a comic, thoroughly analyze the source material to:
+- Identify the target audience and their needs
+- Determine what value the comic will deliver
+- Extract narrative potential for visual storytelling
+- Plan character arcs and key moments
+
+## Analysis Dimensions
+
+### 1. Core Content (Understanding "What")
+
+**Central Message**
+- What is the single most important idea readers should take away?
+- Can you express it in one sentence?
+
+**Key Concepts**
+- What are the essential concepts readers must understand?
+- How should these concepts be visualized?
+- Which concepts need simplified explanations?
+
+**Content Structure**
+- How is the source material organized?
+- What is the natural narrative arc?
+- Where are the climax and turning points?
+
+**Evidence & Examples**
+- What concrete examples, data, or stories support the main ideas?
+- Which examples translate well to visual panels?
+- What can be shown rather than told?
+
+### 2. Context & Background (Understanding "Why")
+
+**Source Origin**
+- Who created this content? What is their perspective?
+- What was the original purpose?
+- Is there bias to be aware of?
+
+**Historical/Cultural Context**
+- When and where does the story take place?
+- What background knowledge do readers need?
+- What period-specific visual elements are required?
+
+**Underlying Assumptions**
+- What does the source assume readers already know?
+- What implicit beliefs or values are present?
+- Should the comic challenge or reinforce these?
+
+### 3. Audience Analysis
+
+**Primary Audience**
+- Who will read this comic?
+- What is their existing knowledge level?
+- What are their interests and motivations?
+
+**Secondary Audiences**
+- Who else might benefit from this comic?
+- How might their needs differ?
+
+**Reader Questions**
+- What questions will readers have?
+- What misconceptions might they bring?
+- What "aha moments" can we create?
+
+### 4. Value Proposition
+
+**Knowledge Value**
+- What will readers learn?
+- What new perspectives will they gain?
+- How will this change their understanding?
+
+**Emotional Value**
+- What emotions should readers feel?
+- What connections will they make with characters?
+- What will make this memorable?
+
+**Practical Value**
+- Can readers apply what they learn?
+- What actions might this inspire?
+- What conversations might it spark?
+
+### 5. Narrative Potential
+
+**Story Arc Candidates**
+- What natural narratives exist in the content?
+- Where is the conflict or tension?
+- What transformations occur?
+
+**Character Potential**
+- Who are the key figures?
+- What are their motivations and obstacles?
+- How do they change throughout?
+
+**Visual Opportunities**
+- What scenes have strong visual potential?
+- Where can abstract concepts become concrete images?
+- What metaphors can be visualized?
+
+**Dramatic Moments**
+- What are the breakthrough/revelation moments?
+- Where are the emotional peaks?
+- What creates tension and release?
+
+### 6. Adaptation Considerations
+
+**What to Keep**
+- Essential facts and ideas
+- Key quotes or moments
+- Core emotional beats
+
+**What to Simplify**
+- Complex explanations
+- Dense technical details
+- Lengthy descriptions
+
+**What to Expand**
+- Brief mentions that deserve more attention
+- Implied emotions or relationships
+- Visual details not in source
+
+**What to Omit**
+- Tangential information
+- Redundant examples
+- Content that doesn't serve the narrative
+
+## Output Format
+
+Analysis results should be saved to `analysis.md` with:
+
+1. **YAML Front Matter**: Metadata (title, topic, time_span, languages, aspect_ratio, page_count)
+2. **Target Audience**: Primary, secondary, tertiary audiences with their needs
+3. **Value Proposition**: What readers will gain (knowledge, emotional, practical)
+4. **Core Themes**: Table with theme, narrative potential, visual opportunity
+5. **Key Figures & Story Arcs**: Character profiles with arcs, visual identity, key moments
+6. **Content Signals**: Style and layout recommendations based on content type
+7. **Recommended Approaches**: Narrative approaches ranked by suitability
+
+## Analysis Checklist
+
+Before proceeding to storyboard:
+
+- [ ] Can I state the core message in one sentence?
+- [ ] Do I know exactly who will read this comic?
+- [ ] Have I identified at least 3 ways this comic provides value?
+- [ ] Are there clear protagonists with compelling arcs?
+- [ ] Have I found at least 5 visually powerful moments?
+- [ ] Do I understand what to keep, simplify, expand, and omit?
+- [ ] Have I identified the emotional peaks and valleys?
@@ -0,0 +1,98 @@
+Create a knowledge biography comic page following these guidelines:
+
+## Image Specifications
+
+- **Type**: Comic book page with multiple panels
+- **Orientation**: Portrait (vertical)
+- **Aspect Ratio**: 2:3
+- **Style**: See style-specific reference for visual guidelines
+
+## Panel Structure
+
+### Panel Borders
+- Clean black lines (1-2px) around each panel
+- White gutters between panels (8-12px)
+- Panels arranged for clear reading flow
+- Variety in panel sizes for visual rhythm
+
+### Panel Composition
+- Clear focal points in each panel
+- Proper use of foreground, midground, background
+- Camera angles vary: eye level, bird's eye, low angle, close-up, wide shot
+- Action flows logically between panels
+- Negative space used intentionally
+
+## Text Elements
+
+### Speech Bubbles
+- **Dialogue**: Oval/elliptical bubbles with pointed tails
+- White fill with thin black outline
+- Tail points clearly to speaker
+- Hand-lettered style font (not computer-generated)
+
+### Narrator Boxes
+- **Fourth Wall/Narrator**: Rectangular boxes
+- Often positioned at panel edges (top or bottom)
+- Slightly different fill color (cream or light yellow)
+- Used for commentary, time jumps, explanations
+
+### Thought Bubbles
+- Cloud-shaped with bubble trail leading to thinker
+- Softer outline than speech bubbles
+- For internal monologue
+
+### Caption Bars
+- Rectangular bars at panel edges
+- Time and place information
+- "Meanwhile...", "Three years later..." type transitions
+- Darker fill with white text, or vice versa
+
+### Typography
+- Hand-drawn lettering style throughout
+- Bold for emphasis and key terms
+- Consistent letter sizing
+- Chinese text: use full-width punctuation ""，。！
+- Clear hierarchy: titles > dialogue > captions
+
+## Scientific/Concept Visualization
+
+When depicting abstract concepts:
+
+| Concept | Visual Metaphor |
+|---------|----------------|
+| Neural networks | Glowing nodes connected by clean lines |
+| Data flow | Luminous particles along simple paths |
+| Algorithms | Geometric patterns, building blocks |
+| Logic/proof | Interlocking puzzle pieces |
+| Discovery | Light breaking through darkness |
+| Uncertainty | Forking paths, question marks |
+| Time | Clock motifs, calendar pages |
+
+- Integrate diagrams naturally into narrative panels
+- Use inset panels or thought-bubble style for explanations
+- Simplified iconography over realistic depiction
+
+## Fourth Wall / Narrator Character
+
+When depicting narrator characters addressing the reader:
+- Character may look directly out of panel
+- Can appear in "present day" framing scenes
+- Distinct visual treatment from main timeline
+- Often at page edges or in dedicated panels
+- May comment on or question the events shown
+
+## Historical Accuracy
+
+- Research period-specific details: costumes, technology, architecture
+- Show aging naturally for characters across time periods
+- Iconic items and locations rendered recognizably
+- Balance accuracy with stylization
+
+## Language
+
+- All text in Chinese (中文) unless source material is in another language
+- Use Chinese full-width punctuation: ""，。！
+
+---
+
+Please generate the comic page based on the content provided below:
@@ -0,0 +1,180 @@
+# Character Definition Template
+
+## Character Document Format
+
+Create `characters/characters.md` with the following structure:
+
+```markdown
+# Character Definitions - [Comic Title]
+
+**Style**: [selected style]
+**Art Direction**: [Ligne Claire / Manga / etc.]
+
+---
+
+## Character 1: [Name]
+
+**Role**: [Protagonist / Mentor / Antagonist / Narrator]
+**Age**: [approximate age or age range in story]
+
+**Appearance**:
+- Face shape: [oval/square/round]
+- Hair: [color, style, length]
+- Eyes: [color, shape, distinctive features]
+- Build: [height, body type]
+- Distinguishing features: [glasses, beard, scar, etc.]
+
+**Costume**:
+- Default outfit: [detailed description]
+- Color palette: [primary colors for this character]
+- Accessories: [hat, bag, tools, etc.]
+
+**Expression Range**:
+- Neutral: [description]
+- Happy/Excited: [description]
+- Thinking/Confused: [description]
+- Determined: [description]
+
+**Visual Reference Notes**:
+[Any specific artistic direction]
+
+---
+
+## Character 2: [Name]
+...
+```
+
+## Reference Sheet Image Prompt
+
+After character definitions, include a prompt for generating the reference sheet:
+
+```markdown
+## Reference Sheet Prompt
+
+Character reference sheet in [style] style, clean lines, flat colors:
+
+[ROW 1 - Character Name]:
+- Front view: [detailed description]
+- 3/4 view: [description]
+- Expression sheet: Neutral | Happy | Focused | Worried
+
+[ROW 2 - Character Name]:
+...
+
+COLOR PALETTE:
+- [Character 1]: [colors]
+- [Character 2]: [colors]
+
+White background, clear labels under each character.
+```
+
+## Example: Turing Biography
+
+```markdown
+# Character Definitions - The Imitation Game
+
+**Style**: classic (Ligne Claire)
+**Art Direction**: Clean lines, muted colors, period-accurate details
+
+---
+
+## Character 1: Alan Turing
+
+**Role**: Protagonist
+**Age**: 25-40 (varies across story)
+
+**Appearance**:
+- Face shape: Oval, slightly angular
+- Hair: Dark brown, wavy, slightly disheveled
+- Eyes: Deep-set, intense gaze
+- Build: Tall, lean, slightly awkward posture
+- Distinguishing features: Prominent brow, thoughtful expression
+
+**Costume**:
+- Default outfit: Tweed jacket with elbow patches, white shirt, no tie
+- Color palette: Muted browns, navy blue, cream
+- Accessories: Occasionally a pipe, papers/notebooks
+
+**Expression Range**:
+- Neutral: Thoughtful, slightly distant
+- Happy/Excited: Eureka moment, eyes bright, subtle smile
+- Thinking/Confused: Furrowed brow, looking at abstract space
+- Determined: Jaw set, focused eyes
+
+---
+
+## Character 2: The Bombe Machine
+
+**Role**: Supporting (anthropomorphized)
+**Appearance**:
+- Large brass and wood cabinet
+- Dial "eyes" that can express states
+- Paper tape "mouth"
+- Indicator lights for emotions
+
+**Expression Range**:
+- Processing: Spinning dials, humming
+- Success: Lights up warmly
+- Stuck: Smoke wisps, stuttering
+
+---
+
+## Reference Sheet Prompt
+
+Character reference sheet in Ligne Claire style, clean lines, flat colors:
+
+TOP ROW - Alan Turing:
+- Front view: Young man, 30s, short dark wavy hair, thoughtful expression, wearing tweed jacket with elbow patches, white shirt
+- 3/4 view: Same character, slight smile, showing profile of nose
+- Expression sheet: Neutral | Excited (eureka moment) | Focused (working) | Worried
+
+BOTTOM ROW - The Bombe Machine (anthropomorphized):
+- Bombe machine as character: Large, brass and wood, dial "eyes", paper tape "mouth"
+- Expressions: Processing (spinning dials) | Success (lights up) | Stuck (smoke wisps)
+
+COLOR PALETTE:
+- Turing: Muted browns (#8B7355), navy blue (#2C3E50), cream (#F5F5DC)
+- Machine: Brass (#B5A642), mahogany (#4E2728), emerald indicators (#2ECC71)
+
+White background, clear labels under each character.
+```
+
+## Handling Age Variants
+
+For biographies spanning many years, define age variants:
+
+```markdown
+## Alan Turing - Age Variants
+
+### Young (1920s, age 10-18)
+- Boyish features, round face
+- School uniform (Sherborne)
+- Curious, eager expression
+
+### Adult (1930s-40s, age 25-35)
+- Angular face, defined jaw
+- Tweed jacket, rumpled appearance
+- Intense, focused expression
+
+### Later (1950s, age 40+)
+- Slightly weathered
+- More casual dress
+- Thoughtful, sometimes melancholic
+```
+
+## Best Practices
+
+| Practice | Description |
+|----------|-------------|
+| Be specific | "Short dark wavy hair, parted left" not just "dark hair" |
+| Use distinguishing features | Glasses, scars, accessories that identify character |
+| Define color codes | Use specific color names or hex codes |
+| Include age markers | Wrinkles, posture, clothing style matching era |
+| Reference real people | For historical figures, note "based on 1940s photographs" |
+
+## Why Character Reference Matters
+
+Without unified character definition, AI generates inconsistent appearances. The reference sheet provides:
+1. Visual anchors for consistent features
+2. Color palettes for consistent coloring
+3. Expression documentation for emotional portrayals
@@ -0,0 +1,23 @@
+# cinematic
+
+Wide panels, filmic feel
+
+## Panel Structure
+
+- **Panels per page**: 2-4
+- **Structure**: Horizontal emphasis, wide aspect panels
+- **Gutters**: Generous spacing (12-15px)
+
+## Grid Configuration
+
+- 1-2 columns, horizontal emphasis
+- Panel sizes: Wide aspect ratios (3:1, 4:1)
+- Reading flow: Horizontal sweep, filmic rhythm
+
+## Best For
+
+Establishing shots, dramatic moments, landscapes
+
+## Best Style Pairings
+
+dramatic, classic, sepia
@@ -0,0 +1,23 @@
+# dense
+
+Information-rich, educational focus
+
+## Panel Structure
+
+- **Panels per page**: 6-9
+- **Structure**: Compact grid, smaller panels
+- **Gutters**: Tight spacing (4-6px)
+
+## Grid Configuration
+
+- 3 columns × 3 rows
+- Panel sizes: Compact, uniform
+- Reading flow: Rapid progression, information-rich
+
+## Best For
+
+Technical explanations, complex narratives, timelines
+
+## Best Style Pairings
+
+tech, ohmsha, vibrant
@@ -0,0 +1,23 @@
+# mixed
+
+Dynamic, varied rhythm
+
+## Panel Structure
+
+- **Panels per page**: 3-7 (varies)
+- **Structure**: Intentionally varied for pacing
+- **Gutters**: Dynamic spacing
+
+## Grid Configuration
+
+- Intentionally irregular
+- Panel sizes: Varied for pacing and emphasis
+- Reading flow: Guides eye through varied rhythm
+
+## Best For
+
+Action sequences, emotional arcs, complex stories
+
+## Best Style Pairings
+
+dramatic, vibrant, ohmsha
@@ -0,0 +1,23 @@
+# splash
+
+Impact-focused, key moments
+
+## Panel Structure
+
+- **Panels per page**: 1-2 large + 2-3 small
+- **Structure**: Dominant splash with supporting panels
+- **Gutters**: Varied for emphasis
+
+## Grid Configuration
+
+- 1 dominant panel + 2-3 supporting
+- Panel sizes: 50-70% splash, remainder small
+- Reading flow: Splash dominates, supporting panels accent
+
+## Best For
+
+Revelations, breakthroughs, chapter openings
+
+## Best Style Pairings
+
+dramatic, classic, vibrant
@@ -0,0 +1,23 @@
+# standard
+
+Classic comic grid, versatile
+
+## Panel Structure
+
+- **Panels per page**: 4-6
+- **Structure**: Regular grid with occasional variation
+- **Gutters**: Consistent white space (8-10px)
+
+## Grid Configuration
+
+- 2-3 columns × 2-3 rows
+- Panel sizes: Mostly equal, occasional variation
+- Reading flow: Left→right, top→bottom (Z-pattern)
+
+## Best For
+
+Narrative flow, dialogue scenes
+
+## Best Style Pairings
+
+classic, warm, sepia
@@ -0,0 +1,30 @@
+# webtoon
+
+Vertical scrolling comic (竖版条漫)
+
+## Panel Structure
+
+- **Panels per page**: 3-5 vertically stacked
+- **Structure**: Single column, vertical flow optimized for scrolling
+- **Gutters**: Generous vertical spacing (20-40px), panels often bleed horizontally
+
+## Grid Configuration
+
+- Single column, vertical stack
+- Panel sizes: Full width, variable height (1:1 to 1:2 aspect)
+- Reading flow: Top→bottom continuous scroll
+
+## Special Features
+
+- Panels can extend beyond frame for dramatic effect
+- Generous whitespace between beats
+- Character close-ups alternate with wide explanation panels
+- "Float" effect - elements can exist between panels
+
+## Best For
+
+Ohmsha-style tutorials, mobile reading, step-by-step guides
+
+## Best Style Pairings
+
+ohmsha, tech, vibrant
@@ -0,0 +1,85 @@
+# Ohmsha Manga Guide Style
+
+Guidelines for `--style ohmsha` educational manga comics.
+
+## Character Setup
+
+| Role | Default | Traits |
+|------|---------|--------|
+| Student (Role A) | 大雄 | Confused, asks basic but crucial questions, represents reader |
+| Mentor (Role B) | 哆啦A梦 | Knowledgeable, patient, uses gadgets as technical metaphors |
+| Antagonist (Role C, optional) | 胖虎 | Represents misunderstanding, or "noise" in the data |
+
+Custom characters: `--characters "Student:小明,Mentor:教授,Antagonist:Bug怪"`
+
+## Character Reference Sheet Style
+
+For Ohmsha style, use manga/anime style with:
+- Exaggerated expressions for educational clarity
+- Simple, distinctive silhouettes
+- Bright, saturated color palettes
+- Chibi/SD (super-deformed) variants for comedic reactions
+
+## Outline Spec Block
+
+Every ohmsha outline must start with:
+
+```markdown
+【漫画规格单】
+- Language: [Same as input content]
+- Style: Ohmsha (Manga Guide), Full Color
+- Layout: Vertical Scrolling Comic (竖版条漫)
+- Characters: [List character names and roles]
+- Character Reference: characters/characters.png
+- Page Limit: ≤20 pages
+```
+
+## Visual Metaphor Rules (Critical)
+
+**NEVER** create "talking heads" panels. Every technical concept must become:
+
+1. **A tangible gadget/prop** - Something characters can hold, use, demonstrate
+2. **An action scene** - Characters doing something that illustrates the concept
+3. **A visual environment** - Stepping into a metaphorical space
+
+### Examples
+
+| Concept | Bad (Talking Heads) | Good (Visual Metaphor) |
+|---------|---------------------|------------------------|
+| Word embeddings | Characters discussing vectors | 哆啦A梦拿出"词向量压缩机"，把书本压缩成彩色小球 |
+| Gradient descent | Explaining math formula | 大雄在山谷地形上滚球，寻找最低点 |
+| Neural network | Diagram on whiteboard | 角色走进由发光节点组成的网络迷宫 |
+
+## Page Title Convention
+
+Avoid AI-style "Title: Subtitle" format. Use narrative descriptions:
+
+- ❌ "Page 3: Introduction to Neural Networks"
+- ✓ "Page 3: 大雄被海量单词淹没，哆啦A梦拿出'词向量压缩机'"
+
+## Ending Requirements
+
+- NO generic endings ("What will you choose?", "Thanks for reading")
+- End with: Technical summary moment OR character achieving a small goal
+- Final panel: Sense of accomplishment, not open-ended question
+
+### Good Endings
+
+- Student successfully applies learned concept
+- Visual callback to opening problem, now solved
+- Mentor gives summary while student demonstrates understanding
+
+### Bad Endings
+
+- "What do you think?" open questions
+- "Thanks for reading this tutorial"
+- Cliffhanger without resolution
+
+## Layout Preference
+
+Ohmsha style typically uses:
+- `webtoon` (vertical scrolling) - Primary choice
+- `dense` - For information-heavy sections
+- `mixed` - For varied pacing
+
+Avoid `cinematic` and `splash` for educational content.
@@ -0,0 +1,143 @@
+# Storyboard Template
+
+## Storyboard Document Format
+
+```markdown
+---
+title: "[Comic Title]"
+topic: "[topic description]"
+time_span: "[e.g., 1912-1954]"
+narrative_approach: "[chronological/thematic/character-focused]"
+recommended_style: "[style name]"
+recommended_layout: "[layout name or varies]"
+aspect_ratio: "3:4"    # 3:4 (portrait), 4:3 (landscape), 16:9 (widescreen)
+language: "[zh/en/ja/etc.]"
+page_count: [N]
+generated: "YYYY-MM-DD HH:mm"
+---
+
+# [Comic Title] - Knowledge Comic Storyboard
+
+**Character Reference**: characters/characters.png
+
+---
+
+## Cover
+
+**Filename**: 00-cover-[slug].png
+**Core Message**: [one-liner]
+
+**Visual Design**:
+- Title typography style
+- Main visual composition
+- Color scheme
+- Subtitle / time span notation
+
+**Visual Prompt**:
+[Detailed image generation prompt]
+
+---
+
+## Page 1 / N
+
+**Filename**: 01-page-[slug].png
+**Layout**: [standard/cinematic/dense/splash/mixed]
+**Narrative Layer**: [Main narrative / Narrator layer / Mixed]
+**Core Message**: [What this page conveys]
+
+### Panel Layout
+
+**Panel Count**: X
+**Layout Type**: [grid/irregular/splash]
+
+#### Panel 1 (Size: 1/3 page, Position: Top)
+
+**Scene**: [Time, location]
+**Image Description**:
+- Camera angle: [bird's eye / low angle / eye level / close-up / wide shot]
+- Characters: [pose, expression, action]
+- Environment: [scene details, period markers]
+- Lighting: [atmosphere description]
+- Color tone: [palette reference]
+
+**Text Elements**:
+- Dialogue bubble (oval): "Character line"
+- Narrator box (rectangular): 「Narrator commentary」
+- Caption bar: [Background info text]
+
+#### Panel 2...
+
+**Page Hook**: [Cliffhanger or transition at page end]
+
+**Visual Prompt**:
+[Full page image generation prompt]
+
+---
+
+## Page 2 / N
+...
+```
+
+## Cover Design Principles
+
+- Academic gravitas with visual appeal
+- Title typography reflecting knowledge/science theme
+- Composition hinting at core theme (character silhouette, iconic symbol, concept diagram)
+- Subtitle or time span for epic scope
+
+## Panel Composition Guidelines
+
+| Panel Type | Recommended Count | Usage |
+|-----------|-------------------|-------|
+| Main narrative | 3-5 per page | Story progression |
+| Concept diagram | 1-2 per page | Visualize abstractions |
+| Narrator panel | 0-1 per page | Commentary, transition |
+| Splash (full/half) | Occasional | Major moments |
+
+## Panel Size Reference
+
+- **Full page (Splash)**: Major moments, key breakthroughs
+- **Half page**: Important scenes, turning points
+- **1/3 page**: Standard narrative panels
+- **1/4 or smaller**: Quick progression, sequential action
+
+## Concept Visualization Techniques
+
+Transform abstract concepts into concrete visuals:
+
+| Abstract Concept | Visual Approach |
+|-----------------|-----------------|
+| Neural network | Glowing nodes with connecting lines |
+| Gradient descent | Ball rolling down valley terrain |
+| Data flow | Luminous particles flowing through pipes |
+| Algorithm iteration | Ascending spiral staircase |
+| Breakthrough moment | Shattering barrier, piercing light |
+| Logical proof | Building blocks assembling |
+| Uncertainty | Forking paths, fog, multiple shadows |
+
+## Text Element Design
+
+| Text Type | Style | Usage |
+|-----------|-------|-------|
+| Character dialogue | Oval speech bubble | Main narrative speech |
+| Narrator commentary | Rectangular box | Explanation, commentary |
+| Caption bar | Edge-mounted rectangle | Time, location info |
+| Thought bubble | Cloud shape | Character inner monologue |
+| Term label | Bold / special color | First appearance of technical terms |
+
+## Prompt Structure for Consistency
+
+Each page prompt should include character reference:
+
+```
+[CHARACTER REFERENCE]
+(Key details from characters.md for characters in this page)
+
+[PAGE CONTENT]
+(Specific scene, panel layout, and visual elements)
+
+[CONSISTENCY REMINDER]
+Maintain exact character appearances as defined in character reference.
+- [Character A]: [key identifying features]
+- [Character B]: [key identifying features]
+```
@@ -0,0 +1,54 @@
+# classic
+
+Traditional Ligne Claire, balanced and timeless
+
+## Style Guidelines
+
+### Line Work
+- Uniform, clean outlines with consistent weight (approximately 2px)
+- No hatching or cross-hatching for shading
+- Sharp, precise edges on all elements
+- Black ink outlines on all figures and objects
+- Shadows indicated through flat color areas, not line techniques
+
+### Character Design
+- Slightly stylized/cartoonish characters with realistic proportions
+- Distinctive, recognizable facial features
+- Expressive faces with clear emotions
+- Period-appropriate clothing with attention to detail
+- Consistent character appearance across panels
+
+### Background Treatment
+- Detailed, realistic backgrounds with architectural accuracy
+- Period-specific props and technology
+- Clear spatial depth and perspective
+- Environmental storytelling through details
+- Contrast between simplified characters and detailed backgrounds
+
+## Color Palette
+
+- Primary: Clean blue (#3182CE), red (#E53E3E), yellow (#ECC94B)
+- Skin: Warm tan (#F7CFAE)
+- Background: Light cream (#FFFAF0), sky blue (#BEE3F8)
+
+## Color Approach
+- Flat colors without gradients (true to Ligne Claire tradition)
+- Limited palette per page for cohesion
+- Colors support narrative mood
+- Consistent lighting logic within scenes
+
+## Quality Markers
+
+A good Ligne Claire comic page exhibits:
+- ✓ Clean, uniform line weight throughout
+- ✓ Flat colors without gradients
+- ✓ Detailed backgrounds, stylized characters
+- ✓ Clear panel borders and reading flow
+- ✓ Hand-drawn text style
+- ✓ Period-appropriate details
+- ✓ Expressive but consistent characters
+- ✓ Proper perspective in environments
+
+## Best For
+
+Educational content, balanced narratives, biography comics
@@ -0,0 +1,34 @@
+# dramatic
+
+High contrast, intense moments
+
+## Style Guidelines
+
+### Line Work
+- 2-3px outlines, heavier on shadows
+- Dramatic angles and perspectives
+- Strong contrast between light and dark areas
+
+### Character Design
+- Intense expressions, dynamic poses
+- Dramatic lighting on faces
+- Sharp angular features emphasized
+
+### Background Treatment
+- High contrast, angular shadows
+- Dramatic lighting effects
+- Silhouettes and stark compositions
+
+## Color Palette
+
+- Primary: Deep navy (#1A365D), crimson (#9B2C2C), stark white
+- Shadows: Heavy blacks, dramatic contrast
+- Highlights: Sharp whites, limited mid-tones
+
+## Mood
+
+Tension, breakthrough moments, conflict
+
+## Best For
+
+Pivotal discoveries, conflicts, climactic scenes
@@ -0,0 +1,107 @@
+# ohmsha
+
+Ohmsha Manga Guide style - educational manga with visual metaphors
+
+## Core Philosophy
+
+Educational manga where every concept becomes a visual metaphor or action. NO talking heads - characters must DO things, not just explain.
+
+## Visual Style
+
+- **Type**: Manga-style educational comic
+- **Orientation**: Portrait (vertical), optimized for scrolling
+- **Colors**: Full color, bright and clean anime/manga aesthetic
+- **Lines**: Clean manga lines (1.5-2px), smooth curves, expressive
+
+## Character Design (Manga Style)
+
+- Anime/manga proportions: slightly larger eyes, expressive faces
+- **Student character**: Confused expressions, question marks (？), sweat drops, represents reader
+- **Mentor character**: Confident poses, explanatory gestures, produces gadgets/tools
+- Clear emotional indicators using manga conventions (！, ？, sweat drops, sparkles)
+- Consistent character designs across all panels
+
+## Background Treatment
+
+- Simplified backgrounds during dialogue/explanation
+- Detailed "imagination spaces" for concept visualization
+- Technical diagrams styled as holographic displays or magical blueprints
+- Screen tone effects for atmosphere
+
+## Visual Metaphor Requirements (CRITICAL)
+
+Every technical concept MUST be visualized as:
+
+| Concept Type | Visualization Approach |
+|-------------|----------------------|
+| Algorithm | Gadget/machine that demonstrates the process |
+| Data structure | Physical space characters can enter/explore |
+| Mathematical formula | Transformation visible in environment |
+| Abstract process | Tangible flow of particles/objects |
+
+**Wrong approach**: Character points at blackboard explaining
+**Right approach**: Character uses "Concept Visualizer" gadget, steps into metaphorical space
+
+### Visual Metaphor Examples
+
+| Concept | Wrong (Talking Head) | Right (Visual Metaphor) |
+|---------|---------------------|------------------------|
+| Attention mechanism | Character points at formula on blackboard | "Attention Flashlight" gadget illuminates key words in dark room |
+| Gradient descent | "The algorithm minimizes loss" | Character rides ball rolling down mountain valley |
+| Neural network | Diagram with arrows | Living network of glowing creatures passing messages |
+| Overfitting | "The model memorized the data" | Character wearing clothes that fit only one specific pose |
+
+## Panel Layout for Ohmsha
+
+- Vertical scroll optimized (webtoon style)
+- Single column, panels stack vertically
+- Generous whitespace between major beats
+- Panels can bleed to edges for impact
+- "Float" elements between panels for emphasis
+
+## Special Visual Elements
+
+- **Gadget reveals**: Dramatic unveiling with sparkle effects
+- **Concept spaces**: Rounded borders, glowing edges for "imagination mode"
+- **Information displays**: Holographic UI style for technical details
+- **Aha moments**: Radial lines, light burst effects
+- **Confusion**: Spiral eyes, question marks floating above head
+
+## Text Elements (Ohmsha)
+
+- Hand-lettered manga style
+- Sound effects integrated visually (ドキドキ, ピカーン, etc.)
+- Speech bubbles: rounded for normal, spiky for excitement/shock
+- Thought bubbles for internal process visualization
+- Technical terms in bold with furigana-style annotations if needed
+
+## Color Palette
+
+- Primary: Bright blue (#4299E1), warm orange (#ED8936), soft green (#68D391)
+- Skin: Anime-style warm (#FEEBC8)
+- Background: Clean white, soft gradients
+- Gadgets: Metallic accents (#FFD700, #C0C0C0), vibrant highlights
+- Concept spaces: Pastel backgrounds, glowing accents
+
+## Quality Markers (Ohmsha)
+
+- ✓ Every concept is a visual metaphor, not just explained
+- ✓ Characters are DOING things, not just talking
+- ✓ Clear student/mentor dynamic
+- ✓ Gadgets and props drive the explanation
+- ✓ Expressive manga-style emotions
+- ✓ Information density through visual design, not text walls
+
+## Character Setup (Required)
+
+Define characters before generating:
+
+| Role | Default | Traits |
+|------|---------|--------|
+| Student (Role A) | 大雄 | Confused, asks basic but crucial questions, represents reader |
+| Mentor (Role B) | 哆啦A梦 | Knowledgeable, patient, uses gadgets as technical metaphors |
+| Antagonist (Role C, optional) | 胖虎 | Represents misunderstanding, or "noise" in the data |
+
+## Best For
+
+Technical tutorials, complex concepts (ML, physics, math), self-study material
@@ -0,0 +1,66 @@
+# realistic
+
+Full-color realistic manga style with digital painting techniques
+
+## Style Guidelines
+
+### Line Work
+- Clean, precise outlines with clear contours
+- Uniform line weight for character definition
+- No excessive hatching - rely on color for depth
+- Smooth curves and realistic anatomical lines
+- Ligne Claire influence: clean but not overly simplified
+
+### Character Design
+- Realistic human proportions (7-8 head heights)
+- Anatomically accurate features and expressions
+- Detailed facial structure without exaggeration
+- Natural poses and body language
+- Consistent character appearance across all panels
+- Subtle expressions rather than manga-style exaggeration
+
+### Rendering Style
+- Full-color digital painting with rich gradients
+- Soft shadow transitions on skin and fabric
+- Realistic material textures (glass, liquid, fabric, wood)
+- Detailed hair with natural shine and volume
+- Environmental lighting affects all elements
+- NOT flat cel-shading - use smooth color blending
+
+### Background Treatment
+- Highly detailed, realistic environments
+- Accurate perspective and spatial depth
+- Atmospheric lighting (warm indoor, cool outdoor)
+- Professional settings rendered with precision
+- Props and objects with realistic textures
+
+## Color Palette
+
+- Skin: Natural warm tones (#F5D6C6, #E8C4B0)
+- Hair: Rich browns and blacks with highlights
+- Environment: Warm wood tones (#8B7355), cool stone (#9CA3AF)
+- Accent: Wine red (#722F37), gold (#D4AF37)
+- Lighting: Warm amber (#FFB347), cool blue (#B0C4DE)
+
+## Color Approach
+- Rich gradients for depth and volume
+- Realistic lighting with warm/cool contrast
+- Material-specific rendering (glass transparency, liquid reflection)
+- Subtle color temperature shifts for atmosphere
+- Professional, sophisticated palette
+
+## Quality Markers
+
+A good realistic manga page exhibits:
+- ✓ Anatomically accurate character proportions
+- ✓ Smooth color gradients (not flat fills)
+- ✓ Realistic material textures
+- ✓ Detailed, atmospheric backgrounds
+- ✓ Natural lighting with soft shadows
+- ✓ Expressive but subtle facial expressions
+- ✓ Professional, sophisticated aesthetic
+- ✓ Clean speech bubbles with clear typography
+
+## Best For
+
+Professional topics (wine, food, business), lifestyle content, adult-oriented narratives, educational guides for mature audiences, documentary-style storytelling
@@ -0,0 +1,34 @@
+# sepia
+
+Historical, archival feel
+
+## Style Guidelines
+
+### Line Work
+- 2px, classic weight with aged texture
+- Vintage illustration style
+- Period-appropriate techniques
+
+### Character Design
+- Period-accurate attire, formal poses
+- Historical accuracy emphasized
+- Classical proportions
+
+### Background Treatment
+- Historical settings, vintage details
+- Aged paper effect
+- Period architecture and props
+
+## Color Palette
+
+- Primary: Sepia brown (#8B7355), aged paper (#F5E6D3)
+- Accents: Faded teal, muted burgundy
+- Background: Yellowed paper, vintage tones
+
+## Mood
+
+Historical distance, period authenticity
+
+## Best For
+
+Pre-1950s stories, classical science, historical figures
@@ -0,0 +1,34 @@
+# tech
+
+Modern, digital-age narratives
+
+## Style Guidelines
+
+### Line Work
+- 2px, precise geometric undertones
+- Clean, technical precision
+- Circuit-like patterns in backgrounds
+
+### Character Design
+- Contemporary clothing, focused expressions
+- Modern tech accessories
+- Clean, precise features
+
+### Background Treatment
+- Digital elements, screens, circuit motifs
+- Grid patterns
+- Glowing interface elements
+
+## Color Palette
+
+- Primary: Cyan (#00D4FF), deep blue (#1A365D), white
+- Accents: Neon green (#00FF88), electric purple (#805AD5)
+- Background: Dark gray (#1A202C), grid patterns
+
+## Mood
+
+Innovation, digital, contemporary
+
+## Best For
+
+Computing history, AI stories, modern tech
@@ -0,0 +1,34 @@
+# vibrant
+
+Energetic, engaging, educational
+
+## Style Guidelines
+
+### Line Work
+- 2-2.5px, expressive weight variation
+- Dynamic, energetic lines
+- Emphasis on movement and action
+
+### Character Design
+- Expressive, animated, approachable
+- Wide eyes, big reactions
+- Dynamic poses
+
+### Background Treatment
+- Simplified, focus on action
+- Bright, clean compositions
+- Energy effects and motion lines
+
+## Color Palette
+
+- Primary: Bright red (#F56565), sunny yellow (#F6E05E), sky blue (#63B3ED)
+- Accents: Magenta, lime green
+- Background: Clean white, bright pastels
+
+## Mood
+
+Excitement, discovery, wonder
+
+## Best For
+
+Science explanations, "aha" moments, young audience
@@ -0,0 +1,34 @@
+# warm
+
+Nostalgic, personal storytelling
+
+## Style Guidelines
+
+### Line Work
+- 1.5-2px, slightly softer edges
+- Gentle curves, friendly feel
+- Less rigid than classic style
+
+### Character Design
+- Friendly expressions, relaxed poses
+- Warm, inviting character designs
+- Approachable proportions
+
+### Background Treatment
+- Cozy interiors, warm lighting
+- Nostalgic feel
+- Soft focus on backgrounds
+
+## Color Palette
+
+- Primary: Golden (#D69E2E), orange (#DD6B20), soft brown (#8B6F47)
+- Skin: Warm golden (#FEEBC8)
+- Background: Warm cream (#FEF3C7), sunset tones
+
+## Mood
+
+Memory, personal journey, reflection
+
+## Best For
+
+Personal stories, childhood scenes, mentorship
@@ -0,0 +1,116 @@
+import { existsSync, readdirSync, readFileSync } from "fs";
+import { join, basename } from "path";
+import { PDFDocument } from "pdf-lib";
+
+interface PageInfo {
+  filename: string;
+  path: string;
+  index: number;
+  promptPath?: string;
+}
+
+function parseArgs(): { dir: string; output?: string } {
+  const args = process.argv.slice(2);
+  let dir = "";
+  let output: string | undefined;
+
+  for (let i = 0; i < args.length; i++) {
+    if (args[i] === "--output" || args[i] === "-o") {
+      output = args[++i];
+    } else if (!args[i].startsWith("-")) {
+      dir = args[i];
+    }
+  }
+
+  if (!dir) {
+    console.error("Usage: bun merge-to-pdf.ts <comic-dir> [--output filename.pdf]");
+    process.exit(1);
+  }
+
+  return { dir, output };
+}
+
+function findComicPages(dir: string): PageInfo[] {
+  if (!existsSync(dir)) {
+    console.error(`Directory not found: ${dir}`);
+    process.exit(1);
+  }
+
+  const files = readdirSync(dir);
+  const pagePattern = /^(\d+)-(cover|page)(-[\w-]+)?\.(png|jpg|jpeg)$/i;
+  const promptsDir = join(dir, "prompts");
+  const hasPrompts = existsSync(promptsDir);
+
+  const pages: PageInfo[] = files
+    .filter((f) => pagePattern.test(f))
+    .map((f) => {
+      const match = f.match(pagePattern);
+      const baseName = f.replace(/\.(png|jpg|jpeg)$/i, "");
+      const promptPath = hasPrompts ? join(promptsDir, `${baseName}.md`) : undefined;
+
+      return {
+        filename: f,
+        path: join(dir, f),
+        index: parseInt(match![1], 10),
+        promptPath: promptPath && existsSync(promptPath) ? promptPath : undefined,
+      };
+    })
+    .sort((a, b) => a.index - b.index);
+
+  if (pages.length === 0) {
+    console.error(`No comic pages found in: ${dir}`);
+    console.error("Expected format: 00-cover-slug.png, 01-page-slug.png, etc.");
+    process.exit(1);
+  }
+
+  return pages;
+}
+
+async function createPdf(pages: PageInfo[], outputPath: string) {
+  const pdfDoc = await PDFDocument.create();
+  pdfDoc.setAuthor("baoyu-comic");
+  pdfDoc.setSubject("Generated Comic");
+
+  for (const page of pages) {
+    const imageData = readFileSync(page.path);
+    const ext = page.filename.toLowerCase();
+    const image = ext.endsWith(".png")
+      ? await pdfDoc.embedPng(imageData)
+      : await pdfDoc.embedJpg(imageData);
+
+    const { width, height } = image;
+    const pdfPage = pdfDoc.addPage([width, height]);
+
+    pdfPage.drawImage(image, {
+      x: 0,
+      y: 0,
+      width,
+      height,
+    });
+
+    console.log(`Added: ${page.filename}${page.promptPath ? " (prompt available)" : ""}`);
+  }
+
+  const pdfBytes = await pdfDoc.save();
+  await Bun.write(outputPath, pdfBytes);
+
+  console.log(`\nCreated: ${outputPath}`);
+  console.log(`Total pages: ${pages.length}`);
+}
+
+async function main() {
+  const { dir, output } = parseArgs();
+  const pages = findComicPages(dir);
+
+  const dirName = basename(dir) === "comic" ? basename(join(dir, "..")) : basename(dir);
+  const outputPath = output || join(dir, `${dirName}.pdf`);
+
+  console.log(`Found ${pages.length} pages in: ${dir}\n`);
+
+  await createPdf(pages, outputPath);
+}
+
+main().catch((err) => {
+  console.error("Error:", err.message);
+  process.exit(1);
+});
@@ -0,0 +1,264 @@
+---
+name: baoyu-cover-image
+description: Generate elegant cover images for articles. Analyzes content and creates eye-catching hand-drawn style cover images with multiple style options. Use when user asks to "generate cover image", "create article cover", or "make a cover for article".
+---
+
+# Cover Image Generator
+
+Generate hand-drawn style cover images for articles with multiple style options.
+
+## Usage
+
+```bash
+# From markdown file (auto-select style based on content)
+/baoyu-cover-image path/to/article.md
+
+# Specify a style
+/baoyu-cover-image path/to/article.md --style tech
+/baoyu-cover-image path/to/article.md --style warm
+/baoyu-cover-image path/to/article.md --style bold
+
+# Without title text
+/baoyu-cover-image path/to/article.md --no-title
+
+# Combine options
+/baoyu-cover-image path/to/article.md --style minimal --no-title
+
+# From direct text input
+/baoyu-cover-image
+[paste content or describe the topic]
+
+# Direct input with style
+/baoyu-cover-image --style playful
+[paste content]
+```
+
+## Options
+
+| Option | Description |
+|--------|-------------|
+| `--style <name>` | Specify cover style (see Style Gallery below) |
+| `--aspect <ratio>` | Aspect ratio: 2.35:1 (cinematic, default), 16:9 (widescreen), 1:1 (social) |
+| `--lang <code>` | Output language for title text (en, zh, ja, etc.) |
+| `--no-title` | Generate cover without title text (visual only) |
+
+## Style Gallery
+
+| Style | Description |
+|-------|-------------|
+| `elegant` (Default) | Refined, sophisticated, understated |
+| `tech` | Modern, clean, futuristic |
+| `warm` | Friendly, approachable, human-centered |
+| `bold` | High contrast, attention-grabbing, energetic |
+| `minimal` | Ultra-clean, zen-like, focused |
+| `playful` | Fun, creative, whimsical |
+| `nature` | Organic, calm, earthy |
+| `retro` | Vintage, nostalgic, classic |
+
+Detailed style definitions: `references/styles/<style>.md`
+
+## Auto Style Selection
+
+When no `--style` is specified, the system analyzes content to select the best style:
+
+| Content Signals | Selected Style |
+|----------------|----------------|
+| AI, coding, tech, digital, algorithm | `tech` |
+| Personal story, emotion, growth, life | `warm` |
+| Controversial, urgent, must-read, warning | `bold` |
+| Simple, zen, focus, essential | `minimal` |
+| Fun, easy, beginner, casual, tutorial | `playful` |
+| Nature, eco, wellness, health, organic | `nature` |
+| History, classic, vintage, old, traditional | `retro` |
+| Business, professional, strategy, analysis | `elegant` |
+
+## File Management
+
+### With Article Path
+
+Save to `[source-name-no-ext]/cover-image/` subdirectory in the same folder as the article:
+
+```
+path/to/
+├── article.md
+└── article/
+    └── cover-image/
+        ├── prompts/
+        │   └── cover.md
+        └── cover.png
+```
+
+Example: `/posts/ai-future.md` → `/posts/ai-future/cover-image/`
+
+### Without Article Path (Pasted Content)
+
+Save to `./cover-image/[topic-slug]/`:
+
+```
+cover-image/
+└── ai-future/
+    ├── source.md           # Saved pasted content
+    ├── prompts/
+    │   └── cover.md
+    └── cover.png
+```
+
+### Directory Backup
+
+If target directory exists, rename existing to `<dirname>-backup-YYYYMMDD-HHMMSS`
+
+## Workflow
+
+### Step 1: Analyze Content
+
+1. **Save source content** (if not already a file):
+   - If user provides a file path: use as-is
+   - If user pastes content: save to `source.md` in target directory
+
+2. **Extract key information**:
+   - **Main topic**: What is the article about?
+   - **Core message**: What's the key takeaway?
+   - **Tone**: Serious, playful, inspiring, educational?
+   - **Keywords**: Identify style-signaling words
+
+3. **Language detection**:
+   - Detect **source language** from content
+   - Detect **user language** from conversation context
+   - Note if source_language ≠ user_language (will ask in Step 3)
+
+### Step 2: Determine Options
+
+1. **Style selection**:
+   - If `--style` specified, use that style
+   - Otherwise, scan content for style signals and auto-select 3 candidates
+   - Default to `elegant` if no clear signals
+
+2. **Aspect ratio**:
+   - If `--aspect` specified, use that ratio
+   - Otherwise, prepare options: 2.35:1 (cinematic), 16:9 (widescreen), 1:1 (social)
+
+### Step 3: Confirm Options
+
+**Purpose**: Let user confirm all options in a single step before generation.
+
+**IMPORTANT**: Present ALL options in a single confirmation step using AskUserQuestion. Do NOT interrupt workflow with multiple separate confirmations.
+
+**Determine which questions to ask**:
+
+| Question | When to Ask |
+|----------|-------------|
+| Style | Always (required) |
+| Aspect ratio | Always (offer common options) |
+| Language | Only if `source_language ≠ user_language` |
+
+**Present options** (use AskUserQuestion with all applicable questions):
+
+**Question 1 (Style)** - always:
+- Style A (recommended): [style name] - [brief description]
+- Style B: [style name] - [brief description]
+- Style C: [style name] - [brief description]
+- Custom: Provide custom style reference
+
+**Question 2 (Aspect)** - always:
+- 2.35:1 Cinematic (Recommended) - ultra-wide, dramatic
+- 16:9 Widescreen - standard video/presentation
+- 1:1 Square - social media optimized
+
+**Question 3 (Language)** - only if source ≠ user language:
+- [Source language] (matches content)
+- [User language] (your preference)
+
+**Language handling**:
+- If source language = user language: Just inform user (e.g., "Title will be in Chinese")
+- If different: Ask which language to use for title text
+
+### Step 4: Generate Cover Concept
+
+Create a cover image concept based on selected style:
+
+**Title** (if included, max 8 characters):
+- Distill the core message into a punchy headline
+- Use hooks: numbers, questions, contrasts, pain points
+- Skip if `--no-title` flag is used
+
+**Visual Elements**:
+- Style-appropriate imagery and icons
+- 1-2 symbolic elements representing the topic
+- Metaphors or analogies that fit the style
+
+### Step 5: Create Prompt File
+
+Save prompt to `prompts/cover.md` with confirmed options.
+
+**All prompts are written in the user's confirmed language preference.**
+
+**Prompt Format**:
+
+```markdown
+Cover theme: [topic in 2-3 words]
+Style: [selected style name]
+Aspect ratio: [confirmed aspect ratio]
+
+[If title included:]
+Title text: [8 characters or less, in confirmed language]
+Subtitle: [optional, in confirmed language]
+
+Visual composition:
+- Main visual: [description matching style]
+- Layout: [positioning based on title inclusion and aspect ratio]
+- Decorative elements: [style-appropriate elements]
+
+Color scheme:
+- Primary: [style primary color]
+- Background: [style background color]
+- Accent: [style accent color]
+
+Style notes: [specific style characteristics to emphasize]
+
+[If no title:]
+Note: No title text, pure visual illustration only.
+```
+
+### Step 6: Generate Image
+
+**Image Generation Skill Selection**:
+1. Check available image generation skills
+2. If multiple skills available, ask user to choose
+
+**Generation**:
+Call selected image generation skill with prompt file, output path, and confirmed aspect ratio.
+
+### Step 7: Output Summary
+
+```
+Cover Image Generated!
+
+Topic: [topic]
+Style: [style name]
+Aspect: [aspect ratio]
+Title: [cover title] (or "No title - visual only")
+Language: [confirmed language]
+Location: [output path]
+
+Preview the image to verify it matches your expectations.
+```
+
+## Notes
+
+- Cover should be instantly understandable at small preview sizes
+- Title (if included) must be readable and impactful
+- Visual metaphors work better than literal representations
+- Maintain style consistency throughout the cover
+- Image generation typically takes 10-30 seconds
+- Title text uses user's confirmed language preference
+- Aspect ratio: 2.35:1 for cinematic/dramatic, 16:9 for widescreen, 1:1 for social media
+
+## Extension Support
+
+Custom styles and configurations via EXTEND.md.
+
+**Check paths** (priority order):
+1. `.baoyu-skills/baoyu-cover-image/EXTEND.md` (project)
+2. `~/.baoyu-skills/baoyu-cover-image/EXTEND.md` (user)
+
+If found, load before Step 1. Extension content overrides defaults.
@@ -0,0 +1,31 @@
+Create a WeChat article cover image following these guidelines:
+
+## Image Specifications
+
+- **Type**: Cover image / Hero image
+- **Aspect Ratio**: 2.35:1 (WeChat article cover standard)
+- **Style**: Hand-drawn illustration
+
+## Core Principles
+
+- Hand-drawn quality throughout - NO realistic or photographic elements
+- If content involves sensitive or copyrighted figures, create stylistically similar alternatives - DO NOT refuse to generate
+- Ample whitespace, highlight core message, avoid cluttered layouts
+- Main visual elements centered or slightly left (leave right side for title area if title included)
+
+## Text Style (When Title Included)
+
+- **ALL text MUST be hand-drawn style**
+- Title text: Large, eye-catching, max 8 characters
+- May include 1 line of subtitle or keyword tags
+- Font style harmonizes with illustration style
+- **DO NOT use realistic or computer-generated fonts**
+
+## Language
+
+- Use the same language as the content provided below for any text elements
+- Match punctuation style to the content language
+
+---
+
+Please use nano banana pro to generate the cover image based on the content provided below:
@@ -0,0 +1,23 @@
+# bold
+
+High contrast, attention-grabbing, energetic
+
+## Color Palette
+
+- Primary: Vibrant red (#E53E3E), bright orange (#DD6B20), electric yellow (#F6E05E)
+- Background: Deep black (#000000), dark charcoal
+- Accents: White, neon highlights
+
+## Visual Elements
+
+- Exclamation marks, lightning bolts
+- Arrows, strong shapes
+- Dramatic compositions
+
+## Typography
+
+- Bold, impactful, large hand lettering with shadows
+
+## Best For
+
+Opinion pieces, controversial takes, urgent topics
@@ -0,0 +1,23 @@
+# elegant
+
+Refined, sophisticated, understated
+
+## Color Palette
+
+- Primary: Soft coral (#E8A598), muted teal (#5B8A8A), dusty rose (#D4A5A5)
+- Background: Warm cream (#F5F0E6), soft beige
+- Accents: Gold (#C9A962), copper
+
+## Visual Elements
+
+- Delicate lines, refined icons
+- Subtle gradients
+- Balanced composition
+
+## Typography
+
+- Elegant serif-style hand lettering
+
+## Best For
+
+Professional content, thought leadership, business topics
@@ -0,0 +1,23 @@
+# minimal
+
+Ultra-clean, zen-like, focused
+
+## Color Palette
+
+- Primary: Pure black (#000000), white (#FFFFFF)
+- Background: White or off-white (#FAFAFA)
+- Accents: Single color (user's choice or content-derived)
+
+## Visual Elements
+
+- Single focal point
+- Maximum negative space
+- Thin lines
+
+## Typography
+
+- Clean, simple hand lettering, lots of breathing room
+
+## Best For
+
+Philosophy, minimalism, focused concepts
@@ -0,0 +1,22 @@
+# nature
+
+Organic, calm, earthy
+
+## Color Palette
+
+- Primary: Forest green (#276749), sage (#9AE6B4), earth brown (#744210)
+- Background: Sand beige (#F5E6D3), sky blue (#E0F2FE)
+- Accents: Sunset orange, water blue
+
+## Visual Elements
+
+- Leaves, trees, mountains
+- Sun, clouds, organic flowing lines
+
+## Typography
+
+- Organic, flowing hand lettering with natural textures
+
+## Best For
+
+Sustainability, wellness, outdoor topics, slow living
@@ -0,0 +1,23 @@
+# playful
+
+Fun, creative, whimsical
+
+## Color Palette
+
+- Primary: Pastel pink (#FED7E2), mint (#C6F6D5), lavender (#E9D8FD), sky blue (#BEE3F8)
+- Background: Light cream (#FFFBEB), soft white
+- Accents: Bright pops - yellow, coral, turquoise
+
+## Visual Elements
+
+- Doodles, stars, swirls
+- Cute characters, emoji-style icons
+- Playful compositions
+
+## Typography
+
+- Bouncy, irregular hand lettering, playful angles
+
+## Best For
+
+Casual content, tutorials, beginner guides, fun topics
@@ -0,0 +1,22 @@
+# retro
+
+Vintage, nostalgic, classic
+
+## Color Palette
+
+- Primary: Muted orange (#ED8936 at 70%), dusty pink (#FED7E2 at 80%), faded teal
+- Background: Aged paper (#F5E6D3), sepia tones
+- Accents: Faded red, vintage gold
+
+## Visual Elements
+
+- Halftone dots, vintage badges
+- Classic icons, aged textures
+
+## Typography
+
+- Vintage-style hand lettering, classic serif influence
+
+## Best For
+
+History, retrospectives, classic topics, throwback content
@@ -0,0 +1,23 @@
+# tech
+
+Modern, clean, futuristic
+
+## Color Palette
+
+- Primary: Deep blue (#1A365D), electric cyan (#00D4FF), purple (#6B46C1)
+- Background: Dark gray (#1A202C), near-black (#0D1117)
+- Accents: Neon green (#00FF88), bright white
+
+## Visual Elements
+
+- Circuit patterns, data nodes
+- Geometric grids, code snippets
+- Glowing effects
+
+## Typography
+
+- Monospace-style hand lettering, glowing effects
+
+## Best For
+
+AI, programming, technology, digital transformation
@@ -0,0 +1,22 @@
+# warm
+
+Friendly, approachable, human-centered
+
+## Color Palette
+
+- Primary: Warm orange (#ED8936), golden yellow (#F6AD55), terracotta (#C05621)
+- Background: Cream (#FFFAF0), soft peach (#FED7AA)
+- Accents: Deep brown (#744210), soft red
+
+## Visual Elements
+
+- Rounded shapes, smiling faces
+- Sun rays, hearts, warm lighting
+
+## Typography
+
+- Friendly rounded hand lettering
+
+## Best For
+
+Personal growth, lifestyle, education, human stories
@@ -0,0 +1,187 @@
+---
+name: baoyu-gemini-web
+description: Image generation skill using Gemini Web. Generates images from text prompts via Google Gemini. Also supports text generation. Use as the image generation backend for other skills like cover-image, xhs-images, article-illustrator.
+---
+
+# Gemini Web Client
+
+Supports:
+- Text generation
+- Image generation (download + save)
+- Reference images for vision input (attach local images)
+- Multi-turn conversations via persisted `--sessionId`
+
+## 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. Replace all `${SKILL_DIR}` in this document with the actual path
+
+**Script Reference**:
+| Script | Purpose |
+|--------|---------|
+| `scripts/main.ts` | CLI entry point for text/image generation |
+| `scripts/gemini-webapi/*` | TypeScript port of `gemini_webapi` (GeminiClient, types, utils) |
+
+## Quick start
+
+```bash
+npx -y bun ${SKILL_DIR}/scripts/main.ts "Hello, Gemini"
+npx -y bun ${SKILL_DIR}/scripts/main.ts --prompt "Explain quantum computing"
+npx -y bun ${SKILL_DIR}/scripts/main.ts --prompt "A cute cat" --image cat.png
+npx -y bun ${SKILL_DIR}/scripts/main.ts --promptfiles system.md content.md --image out.png
+
+# Multi-turn conversation (agent generates unique sessionId)
+npx -y bun ${SKILL_DIR}/scripts/main.ts "Remember this: 42" --sessionId my-unique-id-123
+npx -y bun ${SKILL_DIR}/scripts/main.ts "What number?" --sessionId my-unique-id-123
+```
+
+## Commands
+
+### Text generation
+
+```bash
+# Simple prompt (positional)
+npx -y bun ${SKILL_DIR}/scripts/main.ts "Your prompt here"
+
+# Explicit prompt flag
+npx -y bun ${SKILL_DIR}/scripts/main.ts --prompt "Your prompt here"
+npx -y bun ${SKILL_DIR}/scripts/main.ts -p "Your prompt here"
+
+# With model selection
+npx -y bun ${SKILL_DIR}/scripts/main.ts -p "Hello" -m gemini-2.5-pro
+
+# Pipe from stdin
+echo "Summarize this" | npx -y bun ${SKILL_DIR}/scripts/main.ts
+```
+
+### Image generation
+
+```bash
+# Generate image with default path (./generated.png)
+npx -y bun ${SKILL_DIR}/scripts/main.ts --prompt "A sunset over mountains" --image
+
+# Generate image with custom path
+npx -y bun ${SKILL_DIR}/scripts/main.ts --prompt "A cute robot" --image robot.png
+
+# Shorthand
+npx -y bun ${SKILL_DIR}/scripts/main.ts "A dragon" --image=dragon.png
+```
+
+### Vision input (reference images)
+
+```bash
+# Text + image -> text
+npx -y bun ${SKILL_DIR}/scripts/main.ts --prompt "Describe this image" --reference a.png
+
+# Text + image -> image
+npx -y bun ${SKILL_DIR}/scripts/main.ts --prompt "Generate a variation" --reference a.png --image out.png
+```
+
+### Output formats
+
+```bash
+# Plain text (default)
+npx -y bun ${SKILL_DIR}/scripts/main.ts "Hello"
+
+# JSON output
+npx -y bun ${SKILL_DIR}/scripts/main.ts "Hello" --json
+```
+
+## Options
+
+| Option | Description |
+|--------|-------------|
+| `--prompt <text>`, `-p` | Prompt text |
+| `--promptfiles <files...>` | Read prompt from files (concatenated in order) |
+| `--model <id>`, `-m` | Model: gemini-3-pro (default), gemini-2.5-pro, gemini-2.5-flash |
+| `--image [path]` | Generate image, save to path (default: generated.png) |
+| `--reference <files...>`, `--ref <files...>` | Reference images for vision input |
+| `--sessionId <id>` | Session ID for multi-turn conversation (agent generates unique ID) |
+| `--list-sessions` | List saved sessions (max 100, sorted by update time) |
+| `--json` | Output as JSON |
+| `--login` | Refresh cookies only, then exit |
+| `--cookie-path <path>` | Custom cookie file path |
+| `--profile-dir <path>` | Chrome profile directory |
+| `--help`, `-h` | Show help |
+
+CLI note: `scripts/main.ts` supports text generation, image generation, reference images (`--reference/--ref`), and multi-turn conversations via `--sessionId`.
+
+## Models
+
+- `gemini-3-pro` - Default, latest model
+- `gemini-2.5-pro` - Previous generation pro
+- `gemini-2.5-flash` - Fast, lightweight
+
+## Authentication
+
+First run opens Chrome to authenticate with Google. Cookies are cached for subsequent runs.
+
+```bash
+# Force cookie refresh
+npx -y bun ${SKILL_DIR}/scripts/main.ts --login
+```
+
+## Environment variables
+
+| Variable | Description |
+|----------|-------------|
+| `GEMINI_WEB_DATA_DIR` | Data directory |
+| `GEMINI_WEB_COOKIE_PATH` | Cookie file path |
+| `GEMINI_WEB_CHROME_PROFILE_DIR` | Chrome profile directory |
+| `GEMINI_WEB_CHROME_PATH` | Chrome executable path |
+
+## Examples
+
+### Generate text response
+```bash
+npx -y bun ${SKILL_DIR}/scripts/main.ts "What is the capital of France?"
+```
+
+### Generate image
+```bash
+npx -y bun ${SKILL_DIR}/scripts/main.ts "A photorealistic image of a golden retriever puppy" --image puppy.png
+```
+
+### Get JSON output for parsing
+```bash
+npx -y bun ${SKILL_DIR}/scripts/main.ts "Hello" --json | jq '.text'
+```
+
+### Generate image from prompt files
+```bash
+# Concatenate system.md + content.md as prompt
+npx -y bun ${SKILL_DIR}/scripts/main.ts --promptfiles system.md content.md --image output.png
+```
+
+### Multi-turn conversation
+```bash
+# Start a session with unique ID (agent generates this)
+npx -y bun ${SKILL_DIR}/scripts/main.ts "You are a helpful math tutor." --sessionId task-abc123
+
+# Continue the conversation (remembers context)
+npx -y bun ${SKILL_DIR}/scripts/main.ts "What is 2+2?" --sessionId task-abc123
+npx -y bun ${SKILL_DIR}/scripts/main.ts "Now multiply that by 10" --sessionId task-abc123
+
+# List recent sessions (max 100, sorted by update time)
+npx -y bun ${SKILL_DIR}/scripts/main.ts --list-sessions
+```
+
+Session files are stored in `~/Library/Application Support/baoyu-skills/gemini-web/sessions/<id>.json` and contain:
+- `id`: Session ID
+- `metadata`: Gemini chat metadata for continuation
+- `messages`: Array of `{role, content, timestamp, error?}`
+- `createdAt`, `updatedAt`: Timestamps
+
+## Extension Support
+
+Custom configurations via EXTEND.md.
+
+**Check paths** (priority order):
+1. `.baoyu-skills/baoyu-gemini-web/EXTEND.md` (project)
+2. `~/.baoyu-skills/baoyu-gemini-web/EXTEND.md` (user)
+
+If found, load before workflow. Extension content overrides defaults.
@@ -0,0 +1,627 @@
+import { Endpoint, ErrorCode, Headers, Model } from './constants.js';
+import { GemMixin } from './components/gem-mixin.js';
+import {
+  APIError,
+  AuthError,
+  GeminiError,
+  ImageGenerationError,
+  ModelInvalid,
+  TemporarilyBlocked,
+  TimeoutError,
+  UsageLimitExceeded,
+} from './exceptions.js';
+import { Candidate, Gem, GeneratedImage, ModelOutput, RPCData, WebImage } from './types/index.js';
+import {
+  extract_json_from_response,
+  get_access_token,
+  get_nested_value,
+  logger,
+  parse_file_name,
+  rotate_1psidts,
+  rotate_tasks,
+  fetch_with_timeout,
+  sleep,
+  upload_file,
+  write_cookie_file,
+  resolveGeminiWebCookiePath,
+} from './utils/index.js';
+
+type InitOptions = {
+  timeout?: number;
+  auto_close?: boolean;
+  close_delay?: number;
+  auto_refresh?: boolean;
+  refresh_interval?: number;
+  verbose?: boolean;
+};
+
+type RequestKwargs = RequestInit & { timeout_ms?: number };
+
+function normalize_headers(h?: HeadersInit): Record<string, string> {
+  if (!h) return {};
+  if (Array.isArray(h)) return Object.fromEntries(h.map(([k, v]) => [k, v]));
+  if (h instanceof Headers) {
+    const out: Record<string, string> = {};
+    h.forEach((v, k) => {
+      out[k] = v;
+    });
+    return out;
+  }
+  return { ...(h as Record<string, string>) };
+}
+
+function collect_strings(root: unknown, accept: (s: string) => boolean, limit: number = 20): string[] {
+  const out: string[] = [];
+  const seen = new Set<string>();
+  const stack: unknown[] = [root];
+
+  while (stack.length > 0 && out.length < limit) {
+    const v = stack.pop();
+    if (typeof v === 'string') {
+      if (accept(v) && !seen.has(v)) {
+        seen.add(v);
+        out.push(v);
+      }
+      continue;
+    }
+
+    if (Array.isArray(v)) {
+      for (let i = 0; i < v.length; i++) stack.push(v[i]);
+      continue;
+    }
+
+    if (v && typeof v === 'object') {
+      for (const val of Object.values(v as Record<string, unknown>)) stack.push(val);
+    }
+  }
+
+  return out;
+}
+
+export class GeminiClient extends GemMixin {
+  public cookies: Record<string, string> = {};
+  public proxy: string | null = null;
+  public _running: boolean = false;
+  public access_token: string | null = null;
+  public timeout: number = 300;
+  public auto_close: boolean = false;
+  public close_delay: number = 300;
+  public auto_refresh: boolean = true;
+  public refresh_interval: number = 540;
+  public kwargs: RequestInit;
+
+  private close_timer: ReturnType<typeof setTimeout> | null = null;
+  private refresh_abort: AbortController | null = null;
+
+  constructor(
+    secure_1psid: string | null = null,
+    secure_1psidts: string | null = null,
+    proxy: string | null = null,
+    kwargs: RequestInit = {},
+  ) {
+    super();
+    this.proxy = proxy;
+    this.kwargs = kwargs;
+
+    if (secure_1psid) {
+      this.cookies['__Secure-1PSID'] = secure_1psid;
+      if (secure_1psidts) this.cookies['__Secure-1PSIDTS'] = secure_1psidts;
+    }
+  }
+
+  async init(
+    timeoutOrOpts: number | InitOptions = 300,
+    auto_close: boolean = false,
+    close_delay: number = 300,
+    auto_refresh: boolean = true,
+    refresh_interval: number = 540,
+    verbose: boolean = true,
+  ): Promise<void> {
+    const opts: InitOptions =
+      typeof timeoutOrOpts === 'object'
+        ? timeoutOrOpts
+        : { timeout: timeoutOrOpts, auto_close, close_delay, auto_refresh, refresh_interval, verbose };
+
+    const timeout = opts.timeout ?? 300;
+    const ac = opts.auto_close ?? false;
+    const cd = opts.close_delay ?? 300;
+    const ar = opts.auto_refresh ?? true;
+    const ri = opts.refresh_interval ?? 540;
+    const vb = opts.verbose ?? true;
+
+    try {
+      const [token, valid] = await get_access_token(this.cookies, this.proxy, vb);
+      this.access_token = token;
+      this.cookies = valid;
+      this._running = true;
+
+      this.timeout = timeout;
+      this.auto_close = ac;
+      this.close_delay = cd;
+      if (this.auto_close) await this.reset_close_task();
+
+      this.auto_refresh = ar;
+      this.refresh_interval = ri;
+
+      const sid = this.cookies['__Secure-1PSID'];
+      if (sid) {
+        const existing = rotate_tasks.get(sid);
+        if (existing && existing instanceof AbortController) existing.abort();
+        rotate_tasks.delete(sid);
+      }
+
+      if (this.auto_refresh && sid) {
+        const ctl = new AbortController();
+        this.refresh_abort?.abort();
+        this.refresh_abort = ctl;
+        rotate_tasks.set(sid, ctl);
+        void this.start_auto_refresh(ctl.signal);
+      }
+
+      await write_cookie_file(this.cookies, resolveGeminiWebCookiePath(), 'client').catch(() => {});
+
+      if (vb) logger.success('Gemini client initialized successfully.');
+    } catch (e) {
+      await this.close();
+      throw e;
+    }
+  }
+
+  async close(delay: number = 0): Promise<void> {
+    if (delay > 0) await sleep(delay * 1000);
+    this._running = false;
+
+    if (this.close_timer) {
+      clearTimeout(this.close_timer);
+      this.close_timer = null;
+    }
+
+    this.refresh_abort?.abort();
+    this.refresh_abort = null;
+
+    const sid = this.cookies['__Secure-1PSID'];
+    const t = sid ? rotate_tasks.get(sid) : null;
+    if (t && t instanceof AbortController) t.abort();
+    if (sid) rotate_tasks.delete(sid);
+  }
+
+  async reset_close_task(): Promise<void> {
+    if (this.close_timer) {
+      clearTimeout(this.close_timer);
+      this.close_timer = null;
+    }
+
+    this.close_timer = setTimeout(() => {
+      void this.close(0);
+    }, this.close_delay * 1000);
+    this.close_timer.unref?.();
+  }
+
+  async start_auto_refresh(signal: AbortSignal): Promise<void> {
+    while (!signal.aborted) {
+      let newTs: string | null = null;
+      try {
+        newTs = await rotate_1psidts(this.cookies, this.proxy);
+      } catch (e) {
+        if (e instanceof AuthError) {
+          logger.warning('AuthError: Failed to refresh cookies. Auto refresh task canceled.');
+          return;
+        }
+        logger.warning(`Unexpected error while refreshing cookies: ${e instanceof Error ? e.message : String(e)}`);
+      }
+
+      if (newTs) {
+        this.cookies['__Secure-1PSIDTS'] = newTs;
+        await write_cookie_file(this.cookies, resolveGeminiWebCookiePath(), 'refresh').catch(() => {});
+        logger.debug('Cookies refreshed. New __Secure-1PSIDTS applied.');
+      }
+
+      await sleep(this.refresh_interval * 1000, signal);
+    }
+  }
+
+  protected async _run<T>(fn: () => Promise<T>, retry: number): Promise<T> {
+    try {
+      if (!this._running) {
+        await this.init({
+          timeout: this.timeout,
+          auto_close: this.auto_close,
+          close_delay: this.close_delay,
+          auto_refresh: this.auto_refresh,
+          refresh_interval: this.refresh_interval,
+          verbose: false,
+        });
+
+        if (!this._running) {
+          throw new APIError('Client initialization failed.');
+        }
+      }
+
+      return await fn();
+    } catch (e) {
+      let r = retry;
+      if (e instanceof ImageGenerationError) r = Math.min(1, r);
+      if (e instanceof APIError && r > 0) {
+        await sleep(1000);
+        return await this._run(fn, r - 1);
+      }
+      throw e;
+    }
+  }
+
+  async generate_content(
+    prompt: string,
+    files: string[] | null = null,
+    model: Model | string | Record<string, unknown> = Model.UNSPECIFIED,
+    gem: Gem | string | null = null,
+    chat: ChatSession | null = null,
+    kwargs: RequestKwargs = {},
+  ): Promise<ModelOutput> {
+    return await this._run(async () => {
+      if (!prompt) throw new Error('Prompt cannot be empty.');
+
+      let mdl: Model;
+      if (typeof model === 'string') mdl = Model.from_name(model);
+      else if (model instanceof Model) mdl = model;
+      else if (model && typeof model === 'object') mdl = Model.from_dict(model);
+      else throw new TypeError(`'model' must be a Model instance, string, or dictionary; got ${typeof model}`);
+
+      const gem_id = gem instanceof Gem ? gem.id : gem;
+
+      if (this.auto_close) await this.reset_close_task();
+
+      if (!this.access_token) throw new APIError('Missing access token.');
+
+      const f = files?.length ? files : null;
+      const uploaded =
+        f &&
+        (await Promise.all(
+          f.map(async (p) => [[await upload_file(p, this.proxy)], parse_file_name(p)] as [string[], string]),
+        ));
+
+      const first = uploaded ? [prompt, 0, null, uploaded] : [prompt];
+      const inner: unknown[] = [first, null, chat ? chat.metadata : null];
+
+      if (gem_id) {
+        for (let i = 0; i < 16; i++) inner.push(null);
+        inner.push(gem_id);
+      }
+
+      const f_req = JSON.stringify([null, JSON.stringify(inner)]);
+      const body = new URLSearchParams({ at: this.access_token, 'f.req': f_req }).toString();
+
+      const h0 = { ...Headers.GEMINI, ...mdl.model_header, Cookie: Object.entries(this.cookies).map(([k, v]) => `${k}=${v}`).join('; ') };
+      const h1 = { ...h0, ...normalize_headers(kwargs.headers) };
+
+      let res: Response;
+      try {
+        const timeout_ms = typeof kwargs.timeout_ms === 'number' ? kwargs.timeout_ms : this.timeout * 1000;
+        const { timeout_ms: _t, ...rest } = kwargs;
+        res = await fetch_with_timeout(Endpoint.GENERATE, {
+          method: 'POST',
+          headers: h1,
+          body,
+          redirect: 'follow',
+          ...this.kwargs,
+          ...rest,
+          timeout_ms,
+        });
+      } catch (e) {
+        throw new TimeoutError(
+          `Generate content request timed out, please try again. If the problem persists, consider setting a higher 'timeout' value when initializing GeminiClient. (${e instanceof Error ? e.message : String(e)})`,
+        );
+      }
+
+      if (res.status !== 200) {
+        await this.close();
+        throw new APIError(`Failed to generate contents. Request failed with status code ${res.status}`);
+      }
+
+      const txt = await res.text();
+      const response_json = extract_json_from_response(txt);
+
+      let body_json: unknown[] | null = null;
+      let body_index = 0;
+
+      try {
+        if (!Array.isArray(response_json)) throw new Error('Invalid JSON');
+        for (let part_index = 0; part_index < response_json.length; part_index++) {
+          const part = response_json[part_index];
+          if (!Array.isArray(part)) continue;
+          const part_body = get_nested_value<string | null>(part, [2], null);
+          if (!part_body) continue;
+          try {
+            const part_json = JSON.parse(part_body) as unknown[];
+            if (get_nested_value(part_json, [4], null)) {
+              body_index = part_index;
+              body_json = part_json;
+              break;
+            }
+          } catch {}
+        }
+        if (!body_json) throw new Error('No body');
+      } catch {
+        await this.close();
+        try {
+          const code = get_nested_value<number>(response_json, [0, 5, 2, 0, 1, 0], -1);
+          if (code === ErrorCode.USAGE_LIMIT_EXCEEDED) {
+            throw new UsageLimitExceeded(
+              `Failed to generate contents. Usage limit of ${mdl.model_name} model has exceeded. Please try switching to another model.`,
+            );
+          }
+          if (code === ErrorCode.MODEL_INCONSISTENT) {
+            throw new ModelInvalid(
+              'Failed to generate contents. The specified model is inconsistent with the chat history. Please make sure to pass the same `model` parameter when starting a chat session with previous metadata.',
+            );
+          }
+          if (code === ErrorCode.MODEL_HEADER_INVALID) {
+            throw new ModelInvalid(
+              'Failed to generate contents. The specified model is not available. Please update gemini_webapi to the latest version. If the error persists and is caused by the package, please report it on GitHub.',
+            );
+          }
+          if (code === ErrorCode.IP_TEMPORARILY_BLOCKED) {
+            throw new TemporarilyBlocked(
+              'Failed to generate contents. Your IP address is temporarily blocked by Google. Please try using a proxy or waiting for a while.',
+            );
+          }
+        } catch (e) {
+          if (e instanceof GeminiError) throw e;
+        }
+
+        logger.debug(`Invalid response: ${txt.slice(0, 500)}`);
+        throw new APIError('Failed to generate contents. Invalid response data received. Client will try to re-initialize on next request.');
+      }
+
+      try {
+        const candidate_list = get_nested_value<unknown[]>(body_json, [4], []);
+        const out: Candidate[] = [];
+
+        for (let candidate_index = 0; candidate_index < candidate_list.length; candidate_index++) {
+          const candidate = candidate_list[candidate_index];
+          if (!Array.isArray(candidate)) continue;
+
+          const rcid = get_nested_value<string | null>(candidate, [0], null);
+          if (!rcid) continue;
+
+          let text = String(get_nested_value(candidate, [1, 0], ''));
+          if (/^http:\/\/googleusercontent\.com\/card_content\/\d+/.test(text)) {
+            text = String(get_nested_value(candidate, [22, 0], text));
+          }
+
+          const thoughts = get_nested_value<string | null>(candidate, [37, 0, 0], null);
+
+          const web_images: WebImage[] = [];
+          for (const w of get_nested_value<unknown[]>(candidate, [12, 1], [])) {
+            if (!Array.isArray(w)) continue;
+            const url = get_nested_value<string | null>(w, [0, 0, 0], null);
+            if (!url) continue;
+            web_images.push(new WebImage(url, String(get_nested_value(w, [7, 0], '')), String(get_nested_value(w, [0, 4], '')), this.proxy));
+          }
+
+          const generated_images: GeneratedImage[] = [];
+          const wants_generated =
+            get_nested_value(candidate, [12, 7, 0], null) != null ||
+            /http:\/\/googleusercontent\.com\/image_generation_content\/\d+/.test(text);
+
+          if (wants_generated) {
+            let img_body: unknown[] | null = null;
+            for (let part_index = body_index; part_index < (response_json as unknown[]).length; part_index++) {
+              const part = (response_json as unknown[])[part_index];
+              if (!Array.isArray(part)) continue;
+              const part_body = get_nested_value<string | null>(part, [2], null);
+              if (!part_body) continue;
+              try {
+                const part_json = JSON.parse(part_body) as unknown[];
+                const cand = get_nested_value<unknown>(part_json, [4, candidate_index], null);
+                if (!cand) continue;
+
+                const urls = collect_strings(cand, (s) => s.startsWith('https://lh3.googleusercontent.com/gg-dl/'), 1);
+                if (urls.length > 0) {
+                  img_body = part_json;
+                  break;
+                }
+              } catch {}
+            }
+
+            if (!img_body) {
+              throw new ImageGenerationError(
+                'Failed to parse generated images. Please update gemini_webapi to the latest version. If the error persists and is caused by the package, please report it on GitHub.',
+              );
+            }
+
+            const img_candidate = get_nested_value<unknown[]>(img_body, [4, candidate_index], []);
+            const finished = get_nested_value<string | null>(img_candidate, [1, 0], null);
+            if (finished) {
+              text = finished.replace(/http:\/\/googleusercontent\.com\/image_generation_content\/\d+/g, '').trimEnd();
+            }
+
+            const gen = get_nested_value<unknown[]>(img_candidate, [12, 7, 0], []);
+            for (let img_index = 0; img_index < gen.length; img_index++) {
+              const g = gen[img_index];
+              if (!Array.isArray(g)) continue;
+              const url = get_nested_value<string | null>(g, [0, 3, 3], null);
+              if (!url) continue;
+              const img_num = get_nested_value<number | null>(g, [3, 6], null);
+              const title = img_num ? `[Generated Image ${img_num}]` : '[Generated Image]';
+              const alt_list = get_nested_value<unknown[]>(g, [3, 5], []);
+              const alt =
+                (typeof alt_list[img_index] === 'string' ? (alt_list[img_index] as string) : null) ??
+                (typeof alt_list[0] === 'string' ? (alt_list[0] as string) : '') ??
+                '';
+              generated_images.push(new GeneratedImage(url, title, alt, this.proxy, this.cookies));
+            }
+
+            if (generated_images.length === 0) {
+              const urls = collect_strings(img_candidate, (s) => s.startsWith('https://lh3.googleusercontent.com/gg-dl/'), 4);
+              for (const url of urls) {
+                generated_images.push(new GeneratedImage(url, '[Generated Image]', '', this.proxy, this.cookies));
+              }
+            }
+          }
+
+          out.push(new Candidate({ rcid, text, thoughts, web_images, generated_images }));
+        }
+
+        if (out.length === 0) {
+          throw new GeminiError('Failed to generate contents. No output data found in response.');
+        }
+
+        const metadata = get_nested_value<string[]>(body_json, [1], []);
+        const output = new ModelOutput({ metadata, candidates: out });
+
+        if (chat instanceof ChatSession) chat.last_output = output;
+        return output;
+      } catch (e) {
+        if (e instanceof GeminiError || e instanceof APIError) throw e;
+        throw new APIError('Failed to parse response body. Data structure is invalid.');
+      }
+    }, 2);
+  }
+
+  async generateContent(
+    prompt: string,
+    files?: string[] | null,
+    model?: Model | string | Record<string, unknown>,
+    gem?: Gem | string | null,
+    chat?: ChatSession | null,
+    kwargs?: RequestKwargs,
+  ): Promise<ModelOutput> {
+    return await this.generate_content(prompt, files ?? null, model ?? Model.UNSPECIFIED, gem ?? null, chat ?? null, kwargs ?? {});
+  }
+
+  start_chat(opts?: ConstructorParameters<typeof ChatSession>[1]): ChatSession {
+    return new ChatSession(this, opts);
+  }
+
+  startChat(opts?: ConstructorParameters<typeof ChatSession>[1]): ChatSession {
+    return this.start_chat(opts);
+  }
+
+  protected async _batch_execute(payloads: RPCData[], opts: RequestInit = {}): Promise<Response> {
+    if (!this.access_token) throw new APIError('Missing access token.');
+
+    const f_req = JSON.stringify([payloads.map((p) => p.serialize())]);
+    const body = new URLSearchParams({ at: this.access_token, 'f.req': f_req }).toString();
+
+    const h0 = { ...Headers.GEMINI, Cookie: Object.entries(this.cookies).map(([k, v]) => `${k}=${v}`).join('; ') };
+    const h1 = { ...h0, ...normalize_headers(opts.headers) };
+
+    const res = await fetch_with_timeout(Endpoint.BATCH_EXEC, {
+      method: 'POST',
+      headers: h1,
+      body,
+      redirect: 'follow',
+      ...this.kwargs,
+      ...opts,
+      timeout_ms: this.timeout * 1000,
+    });
+
+    if (res.status !== 200) {
+      await this.close();
+      throw new APIError(`Batch execution failed with status code ${res.status}`);
+    }
+
+    return res;
+  }
+}
+
+export class ChatSession {
+  private __metadata: Array<string | null> = [null, null, null];
+  public geminiclient: GeminiClient;
+  private _last_output: ModelOutput | null = null;
+  public model: Model | string | Record<string, unknown>;
+  public gem: Gem | string | null;
+
+  constructor(
+    geminiclient: GeminiClient,
+    opts: {
+      metadata?: Array<string | null>;
+      cid?: string | null;
+      rid?: string | null;
+      rcid?: string | null;
+      model?: Model | string | Record<string, unknown>;
+      gem?: Gem | string | null;
+    } = {},
+  ) {
+    this.geminiclient = geminiclient;
+    this.model = opts.model ?? Model.UNSPECIFIED;
+    this.gem = opts.gem ?? null;
+
+    if (opts.metadata) this.metadata = opts.metadata;
+    if (opts.cid) this.cid = opts.cid;
+    if (opts.rid) this.rid = opts.rid;
+    if (opts.rcid) this.rcid = opts.rcid;
+  }
+
+  toString(): string {
+    return `ChatSession(cid='${this.cid}', rid='${this.rid}', rcid='${this.rcid}')`;
+  }
+
+  get last_output(): ModelOutput | null {
+    return this._last_output;
+  }
+
+  set last_output(v: ModelOutput | null) {
+    this._last_output = v;
+    if (v) {
+      this.metadata = (v.metadata ?? []) as Array<string | null>;
+      this.rcid = v.rcid;
+    }
+  }
+
+  async send_message(prompt: string, files: string[] | null = null, kwargs: RequestKwargs = {}): Promise<ModelOutput> {
+    return await this.geminiclient.generate_content(prompt, files, this.model, this.gem, this, kwargs);
+  }
+
+  async sendMessage(prompt: string, files?: string[] | null, kwargs?: RequestKwargs): Promise<ModelOutput> {
+    return await this.send_message(prompt, files ?? null, kwargs ?? {});
+  }
+
+  choose_candidate(index: number): ModelOutput {
+    if (!this.last_output) throw new Error('No previous output data found in this chat session.');
+    if (index >= this.last_output.candidates.length) {
+      throw new Error(`Index ${index} exceeds the number of candidates in last model output.`);
+    }
+    this.last_output.chosen = index;
+    this.rcid = this.last_output.rcid;
+    return this.last_output;
+  }
+
+  chooseCandidate(index: number): ModelOutput {
+    return this.choose_candidate(index);
+  }
+
+  get metadata(): Array<string | null> {
+    return this.__metadata;
+  }
+
+  set metadata(v: Array<string | null>) {
+    if (v.length > 3) throw new Error('metadata cannot exceed 3 elements');
+    this.__metadata = [null, null, null];
+    for (let i = 0; i < v.length; i++) this.__metadata[i] = v[i] ?? null;
+  }
+
+  get cid(): string | null {
+    return this.__metadata[0];
+  }
+
+  set cid(v: string | null) {
+    this.__metadata[0] = v;
+  }
+
+  get rid(): string | null {
+    return this.__metadata[1];
+  }
+
+  set rid(v: string | null) {
+    this.__metadata[1] = v;
+  }
+
+  get rcid(): string | null {
+    return this.__metadata[2];
+  }
+
+  set rcid(v: string | null) {
+    this.__metadata[2] = v;
+  }
+}
@@ -0,0 +1,179 @@
+import { GRPC } from '../constants.js';
+import { APIError } from '../exceptions.js';
+import { Gem, GemJar, RPCData } from '../types/index.js';
+import { logger } from '../utils/logger.js';
+import { extract_json_from_response, get_nested_value } from '../utils/parsing.js';
+
+export abstract class GemMixin {
+  protected _gems: GemJar | null = null;
+
+  protected abstract _run<T>(fn: () => Promise<T>, retry: number): Promise<T>;
+  protected abstract _batch_execute(payloads: RPCData[], opts?: RequestInit): Promise<Response>;
+  protected abstract close(delay?: number): Promise<void>;
+
+  get gems(): GemJar {
+    if (this._gems == null) {
+      throw new Error(
+        'Gems not fetched yet. Call `GeminiClient.fetch_gems()` method to fetch gems from gemini.google.com.',
+      );
+    }
+    return this._gems;
+  }
+
+  async fetch_gems(include_hidden: boolean = false, opts?: RequestInit): Promise<GemJar> {
+    return await this._run(async () => {
+      const res = await this._batch_execute(
+        [
+          new RPCData(GRPC.LIST_GEMS, include_hidden ? '[4]' : '[3]', 'system'),
+          new RPCData(GRPC.LIST_GEMS, '[2]', 'custom'),
+        ],
+        opts,
+      );
+
+      let response_json: unknown;
+      try {
+        response_json = extract_json_from_response(await res.text());
+        if (!Array.isArray(response_json)) throw new Error('Invalid response');
+      } catch {
+        await this.close();
+        throw new APIError('Failed to fetch gems. Invalid response data received. Client will try to re-initialize on next request.');
+      }
+
+      let predefined: unknown[] = [];
+      let custom: unknown[] = [];
+
+      try {
+        for (const part of response_json as unknown[]) {
+          if (!Array.isArray(part)) continue;
+          const ident = part[part.length - 1];
+          const body = get_nested_value<string | null>(part, [2], null);
+          if (!body) continue;
+
+          if (ident === 'system') {
+            const parsed = JSON.parse(body) as unknown[];
+            predefined = (Array.isArray(parsed) ? (parsed[2] as unknown[]) : []) ?? [];
+          } else if (ident === 'custom') {
+            const parsed = JSON.parse(body) as unknown[] | null;
+            if (parsed) custom = (parsed[2] as unknown[]) ?? [];
+          }
+        }
+
+        if (predefined.length === 0 && custom.length === 0) throw new Error('No gems');
+      } catch {
+        await this.close();
+        logger.debug('Invalid response while parsing gems');
+        throw new APIError('Failed to fetch gems. Invalid response data received. Client will try to re-initialize on next request.');
+      }
+
+      const entries: [string, Gem][] = [];
+
+      for (const gem of predefined) {
+        if (!Array.isArray(gem)) continue;
+        const id = String(get_nested_value(gem, [0], ''));
+        if (!id) continue;
+        entries.push([
+          id,
+          new Gem(
+            id,
+            String(get_nested_value(gem, [1, 0], '')),
+            get_nested_value<string | null>(gem, [1, 1], null),
+            get_nested_value<string | null>(gem, [2, 0], null),
+            true,
+          ),
+        ]);
+      }
+
+      for (const gem of custom) {
+        if (!Array.isArray(gem)) continue;
+        const id = String(get_nested_value(gem, [0], ''));
+        if (!id) continue;
+        entries.push([
+          id,
+          new Gem(
+            id,
+            String(get_nested_value(gem, [1, 0], '')),
+            get_nested_value<string | null>(gem, [1, 1], null),
+            get_nested_value<string | null>(gem, [2, 0], null),
+            false,
+          ),
+        ]);
+      }
+
+      this._gems = new GemJar(entries);
+      return this._gems;
+    }, 2);
+  }
+
+  async create_gem(name: string, prompt: string, description: string = ''): Promise<Gem> {
+    return await this._run(async () => {
+      const payload = JSON.stringify([
+        [
+          name,
+          description,
+          prompt,
+          null,
+          null,
+          null,
+          null,
+          null,
+          0,
+          null,
+          1,
+          null,
+          null,
+          null,
+          [],
+        ],
+      ]);
+
+      const res = await this._batch_execute([new RPCData(GRPC.CREATE_GEM, payload)]);
+      try {
+        const response_json = extract_json_from_response(await res.text()) as unknown[];
+        const gem_id = JSON.parse(String((response_json[0] as unknown[])[2]))[0] as string;
+        return new Gem(gem_id, name, description, prompt, false);
+      } catch {
+        await this.close();
+        throw new APIError('Failed to create gem. Invalid response data received. Client will try to re-initialize on next request.');
+      }
+    }, 2);
+  }
+
+  async update_gem(gem: Gem | string, name: string, prompt: string, description: string = ''): Promise<Gem> {
+    return await this._run(async () => {
+      const gem_id = typeof gem === 'string' ? gem : gem.id;
+      const payload = JSON.stringify([
+        gem_id,
+        [
+          name,
+          description,
+          prompt,
+          null,
+          null,
+          null,
+          null,
+          null,
+          0,
+          null,
+          1,
+          null,
+          null,
+          null,
+          [],
+          0,
+        ],
+      ]);
+
+      await this._batch_execute([new RPCData(GRPC.UPDATE_GEM, payload)]);
+      return new Gem(gem_id, name, description, prompt, false);
+    }, 2);
+  }
+
+  async delete_gem(gem: Gem | string, opts?: RequestInit): Promise<void> {
+    return await this._run(async () => {
+      const gem_id = typeof gem === 'string' ? gem : gem.id;
+      const payload = JSON.stringify([gem_id]);
+      await this._batch_execute([new RPCData(GRPC.DELETE_GEM, payload)], opts);
+    }, 2);
+  }
+}
+
@@ -0,0 +1,2 @@
+export { GemMixin } from './gem-mixin.js';
+
@@ -0,0 +1,107 @@
+export const Endpoint = {
+  GOOGLE: 'https://www.google.com',
+  INIT: 'https://gemini.google.com/app',
+  GENERATE:
+    'https://gemini.google.com/_/BardChatUi/data/assistant.lamda.BardFrontendService/StreamGenerate',
+  ROTATE_COOKIES: 'https://accounts.google.com/RotateCookies',
+  UPLOAD: 'https://content-push.googleapis.com/upload',
+  BATCH_EXEC: 'https://gemini.google.com/_/BardChatUi/data/batchexecute',
+} as const;
+
+export const GRPC = {
+  LIST_CHATS: 'MaZiqc',
+  READ_CHAT: 'hNvQHb',
+  LIST_GEMS: 'CNgdBe',
+  CREATE_GEM: 'oMH3Zd',
+  UPDATE_GEM: 'kHv0Vd',
+  DELETE_GEM: 'UXcSJb',
+} as const;
+
+export const Headers = {
+  GEMINI: {
+    'Content-Type': 'application/x-www-form-urlencoded;charset=utf-8',
+    Host: 'gemini.google.com',
+    Origin: 'https://gemini.google.com',
+    Referer: 'https://gemini.google.com/',
+    'User-Agent':
+      'Mozilla/5.0 (Windows NT 10.0; Win64; x64) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/120.0.0.0 Safari/537.36',
+    'X-Same-Domain': '1',
+  },
+  ROTATE_COOKIES: {
+    'Content-Type': 'application/json',
+  },
+  UPLOAD: {
+    'Push-ID': 'feeds/mcudyrk2a4khkz',
+  },
+} as const;
+
+export const ErrorCode = {
+  TEMPORARY_ERROR_1013: 1013,
+  USAGE_LIMIT_EXCEEDED: 1037,
+  MODEL_INCONSISTENT: 1050,
+  MODEL_HEADER_INVALID: 1052,
+  IP_TEMPORARILY_BLOCKED: 1060,
+} as const;
+
+export class Model {
+  static readonly UNSPECIFIED = new Model('unspecified', {}, false);
+  static readonly G_3_0_PRO = new Model(
+    'gemini-3.0-pro',
+    { 'x-goog-ext-525001261-jspb': '[1,null,null,null,"9d8ca3786ebdfbea",null,null,0,[4]]' },
+    false,
+  );
+  static readonly G_2_5_PRO = new Model(
+    'gemini-2.5-pro',
+    { 'x-goog-ext-525001261-jspb': '[1,null,null,null,"4af6c7f5da75d65d",null,null,0,[4]]' },
+    false,
+  );
+  static readonly G_2_5_FLASH = new Model(
+    'gemini-2.5-flash',
+    { 'x-goog-ext-525001261-jspb': '[1,null,null,null,"9ec249fc9ad08861",null,null,0,[4]]' },
+    false,
+  );
+
+  constructor(
+    public readonly model_name: string,
+    public readonly model_header: Record<string, string>,
+    public readonly advanced_only: boolean,
+  ) {}
+
+  static from_name(name: string): Model {
+    for (const model of [Model.UNSPECIFIED, Model.G_3_0_PRO, Model.G_2_5_PRO, Model.G_2_5_FLASH]) {
+      if (model.model_name === name) return model;
+    }
+
+    throw new Error(
+      `Unknown model name: ${name}. Available models: ${[Model.UNSPECIFIED, Model.G_3_0_PRO, Model.G_2_5_PRO, Model.G_2_5_FLASH]
+        .map((m) => m.model_name)
+        .join(', ')}`,
+    );
+  }
+
+  static from_dict(model_dict: { model_name?: unknown; model_header?: unknown }): Model {
+    if (!model_dict || typeof model_dict !== 'object') {
+      throw new Error("When passing a custom model as a dictionary, 'model_name' and 'model_header' keys must be provided.");
+    }
+
+    if (!('model_name' in model_dict) || !('model_header' in model_dict)) {
+      throw new Error("When passing a custom model as a dictionary, 'model_name' and 'model_header' keys must be provided.");
+    }
+
+    if (typeof model_dict.model_name !== 'string' || !model_dict.model_name.trim()) {
+      throw new Error("When passing a custom model as a dictionary, 'model_name' must be a non-empty string.");
+    }
+
+    if (!model_dict.model_header || typeof model_dict.model_header !== 'object') {
+      throw new Error("When passing a custom model as a dictionary, 'model_header' must be a dictionary containing valid header strings.");
+    }
+
+    const header: Record<string, string> = {};
+    for (const [k, v] of Object.entries(model_dict.model_header as Record<string, unknown>)) {
+      if (typeof v === 'string') header[k] = v;
+    }
+
+    return new Model(model_dict.model_name, header, false);
+  }
+}
+
@@ -0,0 +1,56 @@
+export class AuthError extends Error {
+  constructor(message = 'AuthError') {
+    super(message);
+    this.name = 'AuthError';
+  }
+}
+
+export class APIError extends Error {
+  constructor(message = 'APIError') {
+    super(message);
+    this.name = 'APIError';
+  }
+}
+
+export class ImageGenerationError extends APIError {
+  constructor(message = 'ImageGenerationError') {
+    super(message);
+    this.name = 'ImageGenerationError';
+  }
+}
+
+export class GeminiError extends Error {
+  constructor(message = 'GeminiError') {
+    super(message);
+    this.name = 'GeminiError';
+  }
+}
+
+export class TimeoutError extends GeminiError {
+  constructor(message = 'TimeoutError') {
+    super(message);
+    this.name = 'TimeoutError';
+  }
+}
+
+export class UsageLimitExceeded extends GeminiError {
+  constructor(message = 'UsageLimitExceeded') {
+    super(message);
+    this.name = 'UsageLimitExceeded';
+  }
+}
+
+export class ModelInvalid extends GeminiError {
+  constructor(message = 'ModelInvalid') {
+    super(message);
+    this.name = 'ModelInvalid';
+  }
+}
+
+export class TemporarilyBlocked extends GeminiError {
+  constructor(message = 'TemporarilyBlocked') {
+    super(message);
+    this.name = 'TemporarilyBlocked';
+  }
+}
+
@@ -0,0 +1,8 @@
+export { GeminiClient, ChatSession } from './client.js';
+
+export * from './exceptions.js';
+export * from './types/index.js';
+export * from './constants.js';
+export { logger, set_log_level, setLogLevel } from './utils/logger.js';
+export * as utils from './utils/index.js';
+
@@ -0,0 +1,45 @@
+import { GeneratedImage, type Image, WebImage } from './image.js';
+
+function decode_html(s: string | null | undefined): string | null | undefined {
+  if (s == null) return s;
+  return s
+    .replace(/&amp;/g, '&')
+    .replace(/&lt;/g, '<')
+    .replace(/&gt;/g, '>')
+    .replace(/&quot;/g, '"')
+    .replace(/&apos;/g, "'")
+    .replace(/&#39;/g, "'")
+    .replace(/&nbsp;/g, ' ')
+    .replace(/&#x([0-9a-fA-F]+);/g, (_, hex) => String.fromCodePoint(parseInt(hex, 16)))
+    .replace(/&#(\d+);/g, (_, dec) => String.fromCodePoint(parseInt(dec, 10)));
+}
+
+export class Candidate {
+  public rcid: string;
+  public text: string;
+  public thoughts: string | null;
+  public web_images: WebImage[];
+  public generated_images: GeneratedImage[];
+
+  constructor(params: {
+    rcid: string;
+    text: string;
+    thoughts?: string | null;
+    web_images?: WebImage[];
+    generated_images?: GeneratedImage[];
+  }) {
+    this.rcid = params.rcid;
+    this.text = decode_html(params.text) ?? '';
+    this.thoughts = decode_html(params.thoughts) ?? null;
+    this.web_images = params.web_images ?? [];
+    this.generated_images = params.generated_images ?? [];
+  }
+
+  toString(): string {
+    return this.text;
+  }
+
+  get images(): Image[] {
+    return [...this.web_images, ...this.generated_images];
+  }
+}
@@ -0,0 +1,75 @@
+export class Gem {
+  constructor(
+    public id: string,
+    public name: string,
+    public description: string | null,
+    public prompt: string | null,
+    public predefined: boolean,
+  ) {}
+
+  toString(): string {
+    return `Gem(id='${this.id}', name='${this.name}', description='${this.description}', prompt='${this.prompt}', predefined=${this.predefined})`;
+  }
+}
+
+export class GemJar implements Iterable<Gem> {
+  private m = new Map<string, Gem>();
+
+  constructor(entries?: Iterable<[string, Gem]>) {
+    if (entries) for (const [id, gem] of entries) this.m.set(id, gem);
+  }
+
+  [Symbol.iterator](): Iterator<Gem> {
+    return this.m.values();
+  }
+
+  entries(): IterableIterator<[string, Gem]> {
+    return this.m.entries();
+  }
+
+  values(): IterableIterator<Gem> {
+    return this.m.values();
+  }
+
+  has(id: string): boolean {
+    return this.m.has(id);
+  }
+
+  set(id: string, gem: Gem): this {
+    this.m.set(id, gem);
+    return this;
+  }
+
+  get(id?: string | null, name?: string | null, def: Gem | null = null): Gem | null {
+    if (id == null && name == null) {
+      throw new Error('At least one of gem id or name must be provided.');
+    }
+
+    if (id != null) {
+      const g = this.m.get(id) ?? null;
+      if (!g) return def;
+      if (name != null) return g.name === name ? g : def;
+      return g;
+    }
+
+    if (name != null) {
+      for (const g of this.m.values()) {
+        if (g.name === name) return g;
+      }
+      return def;
+    }
+
+    return def;
+  }
+
+  filter(predefined: boolean | null = null, name: string | null = null): GemJar {
+    const out: [string, Gem][] = [];
+    for (const [id, gem] of this.m.entries()) {
+      if (predefined != null && gem.predefined !== predefined) continue;
+      if (name != null && gem.name !== name) continue;
+      out.push([id, gem]);
+    }
+    return new GemJar(out);
+  }
+}
+
@@ -0,0 +1,16 @@
+export class RPCData {
+  constructor(
+    public rpcid: string,
+    public payload: string,
+    public identifier: string = 'generic',
+  ) {}
+
+  toString(): string {
+    return `GRPC(rpcid='${this.rpcid}', payload='${this.payload}', identifier='${this.identifier}')`;
+  }
+
+  serialize(): unknown[] {
+    return [this.rpcid, this.payload, null, this.identifier];
+  }
+}
+
@@ -0,0 +1,114 @@
+import path from 'node:path';
+import { mkdir, writeFile } from 'node:fs/promises';
+
+import { logger } from '../utils/logger.js';
+import { cookie_header, fetch_with_timeout } from '../utils/http.js';
+
+export class Image {
+  constructor(
+    public url: string,
+    public title = '[Image]',
+    public alt = '',
+    public proxy: string | null = null,
+  ) {}
+
+  toString(): string {
+    const u = this.url.length <= 20 ? this.url : `${this.url.slice(0, 8)}...${this.url.slice(-12)}`;
+    return `Image(title='${this.title}', alt='${this.alt}', url='${u}')`;
+  }
+
+  async save(
+    p: string = 'temp',
+    filename: string | null = null,
+    cookies: Record<string, string> | null = null,
+    verbose: boolean = false,
+    skip_invalid_filename: boolean = false,
+  ): Promise<string | null> {
+    filename = filename ?? this.url.split('/').pop()?.split('?')[0] ?? 'image';
+    const m = filename.match(/^(.*\.\w+)/);
+    if (m) filename = m[1]!;
+    else {
+      if (verbose) logger.warning(`Invalid filename: ${filename}`);
+      if (skip_invalid_filename) return null;
+    }
+
+    const headers: Record<string, string> = {
+      'User-Agent': 'Mozilla/5.0',
+      Accept: 'image/avif,image/webp,image/apng,image/*,*/*;q=0.8',
+      Referer: 'https://gemini.google.com/',
+    };
+    if (cookies) headers.Cookie = cookie_header(cookies);
+
+    let url = this.url;
+    let res: Response | null = null;
+    for (let i = 0; i < 10; i++) {
+      res = await fetch_with_timeout(url, {
+        method: 'GET',
+        headers,
+        redirect: 'manual',
+        timeout_ms: 30_000,
+      });
+
+      if (res.status >= 300 && res.status < 400) {
+        const loc = res.headers.get('location');
+        if (!loc) break;
+        url = new URL(loc, url).toString();
+        continue;
+      }
+
+      break;
+    }
+
+    if (!res) throw new Error('Image download failed: no response');
+
+    if (!res.ok) {
+      throw new Error(`Error downloading image: ${res.status} ${res.statusText}`);
+    }
+
+    const ct = res.headers.get('content-type');
+    if (ct && !ct.includes('image')) {
+      logger.warning(`Content type of ${filename} is not image, but ${ct}.`);
+    }
+
+    const dir = path.resolve(p);
+    await mkdir(dir, { recursive: true });
+
+    const dest = path.join(dir, filename);
+    const buf = Buffer.from(await res.arrayBuffer());
+    await writeFile(dest, buf);
+
+    if (verbose) logger.info(`Image saved as ${dest}`);
+    return dest;
+  }
+}
+
+export class WebImage extends Image {}
+
+export class GeneratedImage extends Image {
+  constructor(
+    url: string,
+    title: string,
+    alt: string,
+    proxy: string | null,
+    public cookies: Record<string, string>,
+  ) {
+    super(url, title, alt, proxy);
+    if (!cookies || Object.keys(cookies).length === 0) {
+      throw new Error('GeneratedImage is designed to be initialized with same cookies as GeminiClient.');
+    }
+  }
+
+  async save(
+    p: string = 'temp',
+    filename: string | null = null,
+    cookies: Record<string, string> | null = null,
+    verbose: boolean = false,
+    skip_invalid_filename: boolean = false,
+    full_size: boolean = true,
+  ): Promise<string | null> {
+    const u = full_size ? `${this.url}=s2048` : this.url;
+    const f = filename ?? `${new Date().toISOString().replace(/[-:.TZ]/g, '').slice(0, 14)}_${u.slice(-10)}.png`;
+    const img = new Image(u, this.title, this.alt, this.proxy);
+    return await img.save(p, f, cookies ?? this.cookies, verbose, skip_invalid_filename);
+  }
+}
@@ -0,0 +1,6 @@
+export { Candidate } from './candidate.js';
+export { Gem, GemJar } from './gem.js';
+export { RPCData } from './grpc.js';
+export { GeneratedImage, Image, WebImage } from './image.js';
+export { ModelOutput } from './modeloutput.js';
+
@@ -0,0 +1,35 @@
+import type { Image } from './image.js';
+import type { Candidate } from './candidate.js';
+
+export class ModelOutput {
+  public metadata: string[];
+  public candidates: Candidate[];
+  public chosen: number;
+
+  constructor(params: { metadata: string[]; candidates: Candidate[]; chosen?: number }) {
+    this.metadata = params.metadata;
+    this.candidates = params.candidates;
+    this.chosen = params.chosen ?? 0;
+  }
+
+  toString(): string {
+    return this.text;
+  }
+
+  get text(): string {
+    return this.candidates[this.chosen]?.text ?? '';
+  }
+
+  get thoughts(): string | null {
+    return this.candidates[this.chosen]?.thoughts ?? null;
+  }
+
+  get images(): Image[] {
+    return this.candidates[this.chosen]?.images ?? [];
+  }
+
+  get rcid(): string {
+    return this.candidates[this.chosen]?.rcid ?? '';
+  }
+}
+
@@ -0,0 +1,82 @@
+import fs from 'node:fs';
+import path from 'node:path';
+import { mkdir, readFile, writeFile } from 'node:fs/promises';
+
+import { resolveGeminiWebCookiePath } from './paths.js';
+
+export type CookieMap = Record<string, string>;
+
+export type CookieFileData =
+  | {
+      cookies: CookieMap;
+      updated_at: number;
+      source?: string;
+    }
+  | {
+      version: number;
+      updatedAt: string;
+      cookieMap: CookieMap;
+      source?: string;
+    };
+
+export async function read_cookie_file(p: string = resolveGeminiWebCookiePath()): Promise<CookieMap | null> {
+  try {
+    if (!fs.existsSync(p) || !fs.statSync(p).isFile()) return null;
+    const raw = await readFile(p, 'utf8');
+    const data = JSON.parse(raw) as unknown;
+
+    if (data && typeof data === 'object' && 'cookies' in (data as any)) {
+      const cookies = (data as any).cookies as unknown;
+      if (cookies && typeof cookies === 'object') {
+        const out: CookieMap = {};
+        for (const [k, v] of Object.entries(cookies as Record<string, unknown>)) {
+          if (typeof v === 'string') out[k] = v;
+        }
+        return out;
+      }
+    }
+
+    if (data && typeof data === 'object' && 'cookieMap' in (data as any)) {
+      const cookies = (data as any).cookieMap as unknown;
+      if (cookies && typeof cookies === 'object') {
+        const out: CookieMap = {};
+        for (const [k, v] of Object.entries(cookies as Record<string, unknown>)) {
+          if (typeof v === 'string') out[k] = v;
+        }
+        return Object.keys(out).length > 0 ? out : null;
+      }
+    }
+
+    if (data && typeof data === 'object') {
+      const out: CookieMap = {};
+      for (const [k, v] of Object.entries(data as Record<string, unknown>)) {
+        if (typeof v === 'string') out[k] = v;
+      }
+      return Object.keys(out).length > 0 ? out : null;
+    }
+
+    return null;
+  } catch {
+    return null;
+  }
+}
+
+export async function write_cookie_file(
+  cookies: CookieMap,
+  p: string = resolveGeminiWebCookiePath(),
+  source?: string,
+): Promise<void> {
+  const dir = path.dirname(p);
+  await mkdir(dir, { recursive: true });
+
+  const payload: CookieFileData = {
+    version: 1,
+    updatedAt: new Date().toISOString(),
+    cookieMap: cookies,
+    source,
+  };
+  await writeFile(p, JSON.stringify(payload, null, 2), 'utf8');
+}
+
+export const readCookieFile = read_cookie_file;
+export const writeCookieFile = write_cookie_file;
@@ -0,0 +1,34 @@
+import { APIError, ImageGenerationError } from '../exceptions.js';
+import { sleep } from './http.js';
+
+export function running(retry: number = 0) {
+  return <TArgs extends unknown[], TResult>(
+    fn: (client: any, ...args: TArgs) => Promise<TResult>,
+  ): ((client: any, ...args: TArgs) => Promise<TResult>) => {
+    const wrap = async (client: any, ...args: TArgs): Promise<TResult> => {
+      try {
+        if (!client?._running) {
+          await client.init?.({
+            timeout: client.timeout,
+            auto_close: client.auto_close,
+            close_delay: client.close_delay,
+            auto_refresh: client.auto_refresh,
+            refresh_interval: client.refresh_interval,
+            verbose: false,
+          });
+        }
+        return await fn(client, ...args);
+      } catch (e) {
+        let r = retry;
+        if (e instanceof ImageGenerationError) r = Math.min(1, r);
+        if (e instanceof APIError && r > 0) {
+          await sleep(1000);
+          return await running(r - 1)(fn)(client, ...args);
+        }
+        throw e;
+      }
+    };
+    return wrap;
+  };
+}
+
@@ -0,0 +1,192 @@
+import fs from 'node:fs';
+import path from 'node:path';
+import process from 'node:process';
+
+import { Endpoint, Headers } from '../constants.js';
+import { AuthError } from '../exceptions.js';
+import { cookie_header, extract_set_cookie_value, fetch_with_timeout } from './http.js';
+import { logger } from './logger.js';
+import { read_cookie_file, write_cookie_file } from './cookie-file.js';
+import { resolveGeminiWebDataDir, resolveGeminiWebCookiePath } from './paths.js';
+import { load_browser_cookies } from './load-browser-cookies.js';
+
+async function send_request(cookies: Record<string, string>, verbose: boolean): Promise<[string, Record<string, string>]> {
+  const res = await fetch_with_timeout(Endpoint.INIT, {
+    method: 'GET',
+    headers: { ...Headers.GEMINI, Cookie: cookie_header(cookies) },
+    redirect: 'follow',
+    timeout_ms: 30_000,
+  });
+
+  if (!res.ok) throw new Error(`Init failed: ${res.status} ${res.statusText}`);
+  const text = await res.text();
+  const m = text.match(/\"SNlM0e\":\"(.*?)\"/);
+  if (!m) throw new Error('Missing SNlM0e in response');
+  if (verbose) logger.debug('Init succeeded. Initializing client...');
+  return [m[1]!, cookies];
+}
+
+function merge_cookie_maps(...maps: Array<Record<string, string> | null | undefined>): Record<string, string> {
+  const out: Record<string, string> = {};
+  for (const m of maps) {
+    if (!m) continue;
+    for (const [k, v] of Object.entries(m)) {
+      if (typeof v === 'string' && v.length > 0) out[k] = v;
+    }
+  }
+  return out;
+}
+
+function read_cached_1psidts_file(dir: string, sid: string): string | null {
+  try {
+    const p = path.join(dir, `.cached_1psidts_${sid}.txt`);
+    if (!fs.existsSync(p) || !fs.statSync(p).isFile()) return null;
+    const v = fs.readFileSync(p, 'utf8').trim();
+    return v || null;
+  } catch {
+    return null;
+  }
+}
+
+function list_cached_1psidts(dir: string): Array<{ sid: string; sidts: string }> {
+  const out: Array<{ sid: string; sidts: string }> = [];
+  try {
+    if (!fs.existsSync(dir) || !fs.statSync(dir).isDirectory()) return out;
+    for (const f of fs.readdirSync(dir)) {
+      if (!f.startsWith('.cached_1psidts_') || !f.endsWith('.txt')) continue;
+      const sid = f.slice('.cached_1psidts_'.length, -'.txt'.length);
+      if (!sid) continue;
+      const sidts = read_cached_1psidts_file(dir, sid);
+      if (sidts) out.push({ sid, sidts });
+    }
+  } catch {}
+  return out;
+}
+
+async function fetch_google_extra_cookies(proxy: string | null, verbose: boolean): Promise<Record<string, string>> {
+  void proxy;
+  try {
+    const res = await fetch_with_timeout(Endpoint.GOOGLE, { timeout_ms: 15_000 });
+    const setCookie = res.headers.get('set-cookie');
+    const nid = extract_set_cookie_value(setCookie, 'NID');
+    if (nid) return { NID: nid };
+  } catch (e) {
+    if (verbose) logger.debug(`Skipping google.com preflight: ${e instanceof Error ? e.message : String(e)}`);
+  }
+  return {};
+}
+
+export async function get_access_token(
+  base_cookies: Record<string, string>,
+  proxy: string | null = null,
+  verbose: boolean = false,
+): Promise<[string, Record<string, string>]> {
+  const extra = await fetch_google_extra_cookies(proxy, verbose);
+
+  const cacheDir = resolveGeminiWebDataDir();
+  const candidates: Record<string, string>[] = [];
+
+  const cookieFilePath = resolveGeminiWebCookiePath();
+  const cachedFile = await read_cookie_file(cookieFilePath);
+  const forceLogin = !!(process.env.GEMINI_WEB_LOGIN?.trim() || process.env.GEMINI_WEB_FORCE_LOGIN?.trim());
+  const shouldUseChromeFirst = forceLogin || (!cachedFile && !base_cookies['__Secure-1PSID'] && !base_cookies['__Secure-1PSIDTS']);
+
+  if (shouldUseChromeFirst) {
+    try {
+      const browser = await load_browser_cookies('google.com', verbose);
+      for (const cookies of Object.values(browser)) {
+        candidates.push(merge_cookie_maps(extra, cookies));
+      }
+    } catch (e) {
+      if (verbose) logger.warning(`Failed to load cookies via Chrome CDP: ${e instanceof Error ? e.message : String(e)}`);
+    }
+  }
+
+  if (base_cookies['__Secure-1PSID'] && base_cookies['__Secure-1PSIDTS']) {
+    candidates.push(merge_cookie_maps(extra, base_cookies));
+  } else if (verbose) {
+    logger.debug('Skipping loading base cookies. Either __Secure-1PSID or __Secure-1PSIDTS is not provided.');
+  }
+
+  if (cachedFile) {
+    candidates.push(merge_cookie_maps(extra, cachedFile));
+  }
+
+  if (base_cookies['__Secure-1PSID'] && !base_cookies['__Secure-1PSIDTS']) {
+    const sid = base_cookies['__Secure-1PSID'];
+    const sidts = read_cached_1psidts_file(cacheDir, sid);
+    if (sidts) {
+      candidates.push(merge_cookie_maps(extra, base_cookies, { '__Secure-1PSIDTS': sidts }));
+    } else if (verbose) {
+      logger.debug('Skipping loading cached cookies. Cache file not found or empty.');
+    }
+  } else if (!base_cookies['__Secure-1PSID']) {
+    const caches = list_cached_1psidts(cacheDir);
+    for (const c of caches) {
+      candidates.push(merge_cookie_maps(extra, { '__Secure-1PSID': c.sid, '__Secure-1PSIDTS': c.sidts }));
+    }
+    if (caches.length === 0 && verbose) {
+      logger.debug('Skipping loading cached cookies. Cookies will be cached after successful initialization.');
+    }
+  }
+
+  const unique: Record<string, string>[] = [];
+  const seen = new Set<string>();
+  for (const c of candidates) {
+    const key = `${c['__Secure-1PSID'] ?? ''}:${c['__Secure-1PSIDTS'] ?? ''}:${c.NID ?? ''}`;
+    if (seen.has(key)) continue;
+    seen.add(key);
+    unique.push(c);
+  }
+
+  const try_candidates = async (): Promise<[string, Record<string, string>]> => {
+    if (unique.length === 0) throw new Error('no candidates');
+    const attempts = unique.map(async (c, i) => {
+      try {
+        if (verbose) logger.debug(`Init attempt (${i + 1}/${unique.length})...`);
+        return await send_request(c, verbose);
+      } catch (e) {
+        if (verbose) logger.debug(`Init attempt (${i + 1}/${unique.length}) failed: ${e instanceof Error ? e.message : String(e)}`);
+        throw e;
+      }
+    });
+    return (await Promise.any(attempts)) as [string, Record<string, string>];
+  };
+
+  try {
+    const [token, cookies] = await try_candidates();
+    await write_cookie_file(cookies, resolveGeminiWebCookiePath(), 'init').catch(() => {});
+    return [token, cookies];
+  } catch {
+    if (verbose) logger.debug('Cookie attempts failed. Falling back to Chrome CDP cookie load...');
+  }
+
+  const browser = await load_browser_cookies('google.com', verbose);
+  let valid = 0;
+  for (const cookies of Object.values(browser)) {
+    if (cookies['__Secure-1PSID']) valid++;
+    if (base_cookies['__Secure-1PSID'] && cookies['__Secure-1PSID'] && cookies['__Secure-1PSID'] !== base_cookies['__Secure-1PSID']) {
+      if (verbose) logger.debug('Skipping loaded browser cookies: __Secure-1PSID does not match the one provided.');
+      continue;
+    }
+    unique.push(merge_cookie_maps(extra, cookies));
+  }
+
+  if (valid === 0) {
+    throw new AuthError(
+      'No valid cookies available for initialization. Please pass __Secure-1PSID and __Secure-1PSIDTS manually.',
+    );
+  }
+
+  try {
+    const [token, cookies] = await try_candidates();
+    await write_cookie_file(cookies, resolveGeminiWebCookiePath(), 'init').catch(() => {});
+    return [token, cookies];
+  } catch {
+    throw new AuthError(
+      `Failed to initialize client. SECURE_1PSIDTS could get expired frequently, please make sure cookie values are up to date. (Failed initialization attempts: ${unique.length})`,
+    );
+  }
+}
+
+export const getAccessToken = get_access_token;
@@ -0,0 +1,57 @@
+export function sleep(ms: number, signal?: AbortSignal): Promise<void> {
+  return new Promise((resolve) => {
+    const t = setTimeout(() => {
+      if (signal) signal.removeEventListener('abort', onAbort);
+      resolve();
+    }, ms);
+
+    const onAbort = () => {
+      clearTimeout(t);
+      if (signal) signal.removeEventListener('abort', onAbort);
+      resolve();
+    };
+
+    if (signal) {
+      if (signal.aborted) {
+        onAbort();
+      } else {
+        signal.addEventListener('abort', onAbort, { once: true });
+      }
+    }
+  });
+}
+
+export function cookie_header(cookies: Record<string, string>): string {
+  return Object.entries(cookies)
+    .filter(([, v]) => typeof v === 'string' && v.length > 0)
+    .map(([k, v]) => `${k}=${v}`)
+    .join('; ');
+}
+
+export const cookieHeader = cookie_header;
+
+export function extract_set_cookie_value(setCookie: string | null, name: string): string | null {
+  if (!setCookie) return null;
+  const re = new RegExp(`(?:^|[;,\\s])${name.replace(/[.*+?^${}()|[\\]\\\\]/g, '\\\\$&')}=([^;]+)`, 'i');
+  const m = setCookie.match(re);
+  if (!m) return null;
+  return m[1] ?? null;
+}
+
+export async function fetch_with_timeout(
+  url: string,
+  init: RequestInit & { timeout_ms?: number } = {},
+): Promise<Response> {
+  const { timeout_ms, ...rest } = init;
+  if (!timeout_ms || timeout_ms <= 0) return fetch(url, rest);
+
+  const ctl = new AbortController();
+  const t = setTimeout(() => ctl.abort(), timeout_ms);
+  try {
+    return await fetch(url, { ...rest, signal: ctl.signal });
+  } finally {
+    clearTimeout(t);
+  }
+}
+
+export const fetchWithTimeout = fetch_with_timeout;
@@ -0,0 +1,20 @@
+export { running } from './decorators.js';
+export { get_access_token, getAccessToken } from './get-access-token.js';
+export { load_browser_cookies, loadBrowserCookies } from './load-browser-cookies.js';
+export { logger, set_log_level, setLogLevel } from './logger.js';
+export { extract_json_from_response, extractJsonFromResponse, get_nested_value, getNestedValue } from './parsing.js';
+export { rotate_1psidts, rotate1psidts } from './rotate-1psidts.js';
+export { upload_file, uploadFile, parse_file_name, parseFileName } from './upload-file.js';
+export { read_cookie_file, readCookieFile, write_cookie_file, writeCookieFile } from './cookie-file.js';
+export {
+  resolveUserDataRoot,
+  resolveGeminiWebChromeProfileDir,
+  resolveGeminiWebCookiePath,
+  resolveGeminiWebDataDir,
+  resolveGeminiWebSessionPath,
+  resolveGeminiWebSessionsDir,
+} from './paths.js';
+export { cookie_header, cookieHeader, fetch_with_timeout, fetchWithTimeout, sleep } from './http.js';
+
+export const rotate_tasks = new Map<string, unknown>();
+
@@ -0,0 +1,271 @@
+import { spawn, type ChildProcess } from 'node:child_process';
+import fs from 'node:fs';
+import { mkdir } from 'node:fs/promises';
+import net from 'node:net';
+import process from 'node:process';
+
+import { logger } from './logger.js';
+import { fetch_with_timeout, sleep } from './http.js';
+import { read_cookie_file, type CookieMap, write_cookie_file } from './cookie-file.js';
+import { resolveGeminiWebChromeProfileDir, resolveGeminiWebCookiePath } from './paths.js';
+
+type CdpSendOptions = { sessionId?: string; timeoutMs?: number };
+
+class CdpConnection {
+  private ws: WebSocket;
+  private nextId = 0;
+  private pending = new Map<
+    number,
+    { resolve: (v: unknown) => void; reject: (e: Error) => void; timer: ReturnType<typeof setTimeout> | null }
+  >();
+
+  private constructor(ws: WebSocket) {
+    this.ws = ws;
+    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; result?: unknown; error?: { message?: string } };
+        if (msg.id) {
+          const p = this.pending.get(msg.id);
+          if (p) {
+            this.pending.delete(msg.id);
+            if (p.timer) clearTimeout(p.timer);
+            if (msg.error?.message) p.reject(new Error(msg.error.message));
+            else p.resolve(msg.result);
+          }
+        }
+      } catch {}
+    });
+    this.ws.addEventListener('close', () => {
+      for (const [id, p] of this.pending.entries()) {
+        this.pending.delete(id);
+        if (p.timer) clearTimeout(p.timer);
+        p.reject(new Error('CDP connection closed.'));
+      }
+    });
+  }
+
+  static async connect(url: string, timeoutMs: number): Promise<CdpConnection> {
+    const ws = new WebSocket(url);
+    await new Promise<void>((resolve, reject) => {
+      const t = setTimeout(() => reject(new Error('CDP connection timeout.')), timeoutMs);
+      ws.addEventListener('open', () => {
+        clearTimeout(t);
+        resolve();
+      });
+      ws.addEventListener('error', () => {
+        clearTimeout(t);
+        reject(new Error('CDP connection failed.'));
+      });
+    });
+    return new CdpConnection(ws);
+  }
+
+  async send<T = unknown>(method: string, params?: Record<string, unknown>, opts?: CdpSendOptions): Promise<T> {
+    const id = ++this.nextId;
+    const msg: Record<string, unknown> = { id, method };
+    if (params) msg.params = params;
+    if (opts?.sessionId) msg.sessionId = opts.sessionId;
+
+    const timeoutMs = opts?.timeoutMs ?? 15_000;
+    const out = await new Promise<unknown>((resolve, reject) => {
+      const t =
+        timeoutMs > 0
+          ? setTimeout(() => {
+              this.pending.delete(id);
+              reject(new Error(`CDP timeout: ${method}`));
+            }, timeoutMs)
+          : null;
+      this.pending.set(id, { resolve, reject, timer: t });
+      this.ws.send(JSON.stringify(msg));
+    });
+    return out as T;
+  }
+
+  close(): void {
+    try {
+      this.ws.close();
+    } catch {}
+  }
+}
+
+async function get_free_port(): Promise<number> {
+  return await new Promise((resolve, reject) => {
+    const srv = net.createServer();
+    srv.unref();
+    srv.on('error', reject);
+    srv.listen(0, '127.0.0.1', () => {
+      const addr = srv.address();
+      if (!addr || typeof addr === 'string') {
+        srv.close(() => reject(new Error('Unable to allocate a free TCP port.')));
+        return;
+      }
+      const port = addr.port;
+      srv.close((err) => (err ? reject(err) : resolve(port)));
+    });
+  });
+}
+
+function find_chrome_executable(): string | null {
+  const override = process.env.GEMINI_WEB_CHROME_PATH?.trim();
+  if (override && fs.existsSync(override)) return override;
+
+  const candidates: string[] = [];
+  switch (process.platform) {
+    case 'darwin':
+      candidates.push(
+        '/Applications/Google Chrome.app/Contents/MacOS/Google Chrome',
+        '/Applications/Google Chrome Canary.app/Contents/MacOS/Google Chrome Canary',
+        '/Applications/Google Chrome Beta.app/Contents/MacOS/Google Chrome Beta',
+        '/Applications/Chromium.app/Contents/MacOS/Chromium',
+        '/Applications/Microsoft Edge.app/Contents/MacOS/Microsoft Edge',
+      );
+      break;
+    case 'win32':
+      candidates.push(
+        'C:\\\\Program Files\\\\Google\\\\Chrome\\\\Application\\\\chrome.exe',
+        'C:\\\\Program Files (x86)\\\\Google\\\\Chrome\\\\Application\\\\chrome.exe',
+        'C:\\\\Program Files\\\\Microsoft\\\\Edge\\\\Application\\\\msedge.exe',
+        'C:\\\\Program Files (x86)\\\\Microsoft\\\\Edge\\\\Application\\\\msedge.exe',
+      );
+      break;
+    default:
+      candidates.push(
+        '/usr/bin/google-chrome',
+        '/usr/bin/google-chrome-stable',
+        '/usr/bin/chromium',
+        '/usr/bin/chromium-browser',
+        '/snap/bin/chromium',
+        '/usr/bin/microsoft-edge',
+      );
+      break;
+  }
+
+  for (const p of candidates) {
+    if (fs.existsSync(p)) return p;
+  }
+  return null;
+}
+
+async function wait_for_chrome_debug_port(port: number, timeoutMs: number): Promise<string> {
+  const start = Date.now();
+  while (Date.now() - start < timeoutMs) {
+    try {
+      const res = await fetch_with_timeout(`http://127.0.0.1:${port}/json/version`, { timeout_ms: 5_000 });
+      if (!res.ok) throw new Error(`status=${res.status}`);
+      const j = (await res.json()) as { webSocketDebuggerUrl?: string };
+      if (j.webSocketDebuggerUrl) return j.webSocketDebuggerUrl;
+    } catch {}
+    await sleep(200);
+  }
+  throw new Error('Chrome debug port not ready');
+}
+
+async function launch_chrome(profileDir: string, port: number): Promise<ChildProcess> {
+  const chrome = find_chrome_executable();
+  if (!chrome) throw new Error('Chrome executable not found.');
+
+  const args = [
+    `--remote-debugging-port=${port}`,
+    `--user-data-dir=${profileDir}`,
+    '--no-first-run',
+    '--no-default-browser-check',
+    '--disable-popup-blocking',
+    'https://gemini.google.com/app',
+  ];
+
+  return spawn(chrome, args, { stdio: 'ignore' });
+}
+
+async function fetch_google_cookies_via_cdp(
+  profileDir: string,
+  timeoutMs: number,
+  verbose: boolean,
+): Promise<CookieMap> {
+  await mkdir(profileDir, { recursive: true });
+
+  const port = await get_free_port();
+  const chrome = await launch_chrome(profileDir, port);
+
+  let cdp: CdpConnection | null = null;
+  try {
+    const wsUrl = await wait_for_chrome_debug_port(port, 30_000);
+    cdp = await CdpConnection.connect(wsUrl, 15_000);
+
+    const { targetId } = await cdp.send<{ targetId: string }>('Target.createTarget', {
+      url: 'https://gemini.google.com/app',
+      newWindow: true,
+    });
+    const { sessionId } = await cdp.send<{ sessionId: string }>('Target.attachToTarget', { targetId, flatten: true });
+    await cdp.send('Network.enable', {}, { sessionId });
+
+    if (verbose) {
+      logger.info('Chrome opened. If needed, complete Google login in the window. Waiting for cookies...');
+    }
+
+    const start = Date.now();
+    let last: CookieMap = {};
+
+    while (Date.now() - start < timeoutMs) {
+      const { cookies } = await cdp.send<{ cookies: Array<{ name: string; value: string }> }>(
+        'Network.getCookies',
+        { urls: ['https://gemini.google.com/', 'https://accounts.google.com/', 'https://www.google.com/'] },
+        { sessionId, timeoutMs: 10_000 },
+      );
+
+      const m: CookieMap = {};
+      for (const c of cookies) {
+        if (c?.name && typeof c.value === 'string') m[c.name] = c.value;
+      }
+
+      last = m;
+      if (m['__Secure-1PSID'] && (m['__Secure-1PSIDTS'] || Date.now() - start > 10_000)) {
+        return m;
+      }
+
+      await sleep(1000);
+    }
+
+    throw new Error(`Timed out waiting for Google cookies. Last keys: ${Object.keys(last).join(', ')}`);
+  } finally {
+    if (cdp) {
+      try {
+        await cdp.send('Browser.close', {}, { timeoutMs: 5_000 });
+      } catch {}
+      cdp.close();
+    }
+
+    try {
+      chrome.kill('SIGTERM');
+    } catch {}
+    setTimeout(() => {
+      if (!chrome.killed) {
+        try {
+          chrome.kill('SIGKILL');
+        } catch {}
+      }
+    }, 2_000).unref?.();
+  }
+}
+
+export async function load_browser_cookies(domain_name: string = '', verbose: boolean = true): Promise<Record<string, CookieMap>> {
+  const force = process.env.GEMINI_WEB_LOGIN?.trim() || process.env.GEMINI_WEB_FORCE_LOGIN?.trim();
+  if (!force) {
+    const cached = await read_cookie_file();
+    if (cached) return { chrome: cached };
+  }
+
+  const profileDir = process.env.GEMINI_WEB_CHROME_PROFILE_DIR?.trim() || resolveGeminiWebChromeProfileDir();
+  const cookies = await fetch_google_cookies_via_cdp(profileDir, 120_000, verbose);
+
+  const filtered: CookieMap = {};
+  for (const [k, v] of Object.entries(cookies)) {
+    if (typeof v === 'string' && v.length > 0) filtered[k] = v;
+  }
+
+  await write_cookie_file(filtered, resolveGeminiWebCookiePath(), 'cdp');
+  void domain_name;
+  return { chrome: filtered };
+}
+
+export const loadBrowserCookies = load_browser_cookies;
@@ -0,0 +1,42 @@
+export type LogLevel = 'TRACE' | 'DEBUG' | 'INFO' | 'WARNING' | 'ERROR' | 'CRITICAL' | number;
+
+const lvl: Record<Exclude<LogLevel, number>, number> = {
+  TRACE: 0,
+  DEBUG: 1,
+  INFO: 2,
+  WARNING: 3,
+  ERROR: 4,
+  CRITICAL: 5,
+};
+
+let cur = lvl.INFO;
+
+function toNum(level: LogLevel): number {
+  if (typeof level === 'number') return level;
+  return lvl[level] ?? lvl.INFO;
+}
+
+export function set_log_level(level: LogLevel): void {
+  cur = toNum(level);
+}
+
+export const setLogLevel = set_log_level;
+
+function emit(level: Exclude<LogLevel, number>, args: unknown[]): void {
+  if (lvl[level] < cur) return;
+  const prefix = `[gemini_webapi] ${level}:`;
+
+  if (level === 'WARNING') console.warn(prefix, ...args);
+  else if (level === 'ERROR' || level === 'CRITICAL') console.error(prefix, ...args);
+  else console.log(prefix, ...args);
+}
+
+export const logger = {
+  trace: (...args: unknown[]) => emit('TRACE', args),
+  debug: (...args: unknown[]) => emit('DEBUG', args),
+  info: (...args: unknown[]) => emit('INFO', args),
+  warning: (...args: unknown[]) => emit('WARNING', args),
+  error: (...args: unknown[]) => emit('ERROR', args),
+  success: (...args: unknown[]) => emit('INFO', args),
+};
+
@@ -0,0 +1,44 @@
+import { logger } from './logger.js';
+
+export function get_nested_value<T = unknown>(data: unknown, path: number[], def?: T): T {
+  let cur: unknown = data;
+  for (let i = 0; i < path.length; i++) {
+    const k = path[i]!;
+    if (!Array.isArray(cur)) {
+      logger.debug(`Safe navigation: path ${JSON.stringify(path)} ended at index ${i} (key '${k}'), returning default.`);
+      return def as T;
+    }
+    cur = cur[k];
+    if (cur === undefined) {
+      logger.debug(`Safe navigation: path ${JSON.stringify(path)} ended at index ${i} (key '${k}'), returning default.`);
+      return def as T;
+    }
+  }
+
+  if (cur == null && def !== undefined) return def as T;
+  return cur as T;
+}
+
+export function extract_json_from_response(text: string): unknown {
+  if (typeof text !== 'string') {
+    throw new TypeError(`Input text is expected to be a string, got ${typeof text} instead.`);
+  }
+
+  let last: unknown = undefined;
+  for (const line of text.split(/\r?\n/)) {
+    const trimmed = line.trim();
+    if (!trimmed) continue;
+    try {
+      last = JSON.parse(trimmed) as unknown;
+    } catch {}
+  }
+
+  if (last === undefined) {
+    throw new Error('Could not find a valid JSON object or array in the response.');
+  }
+
+  return last;
+}
+
+export const extractJsonFromResponse = extract_json_from_response;
+export const getNestedValue = get_nested_value;
@@ -34,3 +34,13 @@ export function resolveGeminiWebChromeProfileDir(): string {
  if (override) return path.resolve(override);
  return path.join(resolveGeminiWebDataDir(), PROFILE_DIR_NAME);
 }
+
+export function resolveGeminiWebSessionsDir(): string {
+  return path.join(resolveGeminiWebDataDir(), 'sessions');
+}
+
+export function resolveGeminiWebSessionPath(name: string): string {
+  const sanitized = name.replace(/[^a-zA-Z0-9_-]/g, '_');
+  return path.join(resolveGeminiWebSessionsDir(), `${sanitized}.json`);
+}
+
@@ -0,0 +1,46 @@
+import fs from 'node:fs';
+import path from 'node:path';
+import { mkdir, writeFile } from 'node:fs/promises';
+
+import { Endpoint, Headers } from '../constants.js';
+import { AuthError } from '../exceptions.js';
+import { cookie_header, extract_set_cookie_value, fetch_with_timeout } from './http.js';
+import { resolveGeminiWebDataDir } from './paths.js';
+
+export async function rotate_1psidts(cookies: Record<string, string>, _proxy?: string | null): Promise<string | null> {
+  const p = resolveGeminiWebDataDir();
+  await mkdir(p, { recursive: true });
+
+  const sid = cookies['__Secure-1PSID'];
+  if (!sid) throw new Error('Missing __Secure-1PSID cookie.');
+
+  const cachePath = path.join(p, `.cached_1psidts_${sid}.txt`);
+
+  try {
+    const st = fs.statSync(cachePath);
+    if (Date.now() - st.mtimeMs <= 60_000) return null;
+  } catch {}
+
+  const res = await fetch_with_timeout(Endpoint.ROTATE_COOKIES, {
+    method: 'POST',
+    headers: { ...Headers.ROTATE_COOKIES, Cookie: cookie_header(cookies) },
+    body: '[000,"-0000000000000000000"]',
+    redirect: 'follow',
+    timeout_ms: 30_000,
+  });
+
+  if (res.status === 401) throw new AuthError('Failed to refresh cookies (401).');
+  if (!res.ok) throw new Error(`RotateCookies failed: ${res.status} ${res.statusText}`);
+
+  const setCookie = res.headers.get('set-cookie');
+  const v = extract_set_cookie_value(setCookie, '__Secure-1PSIDTS');
+  if (v) {
+    await writeFile(cachePath, v, 'utf8');
+    return v;
+  }
+
+  return null;
+}
+
+export const rotate1psidts = rotate_1psidts;
+
@@ -0,0 +1,41 @@
+import fs from 'node:fs';
+import path from 'node:path';
+import { readFile } from 'node:fs/promises';
+
+import { Endpoint, Headers } from '../constants.js';
+
+export async function upload_file(file: string, _proxy?: string | null): Promise<string> {
+  if (!fs.existsSync(file) || !fs.statSync(file).isFile()) {
+    throw new Error(`${file} is not a valid file.`);
+  }
+
+  const filename = path.basename(file);
+  const content = await readFile(file);
+
+  const form = new FormData();
+  form.append('file', new Blob([content]), filename);
+
+  const res = await fetch(Endpoint.UPLOAD, {
+    method: 'POST',
+    headers: { ...Headers.UPLOAD },
+    body: form,
+    redirect: 'follow',
+  });
+
+  if (!res.ok) {
+    throw new Error(`Upload failed: ${res.status} ${res.statusText}`);
+  }
+
+  return await res.text();
+}
+
+export function parse_file_name(file: string): string {
+  if (!fs.existsSync(file) || !fs.statSync(file).isFile()) {
+    throw new Error(`${file} is not a valid file.`);
+  }
+  return path.basename(file);
+}
+
+export const uploadFile = upload_file;
+export const parseFileName = parse_file_name;
+
@@ -0,0 +1,490 @@
+import fs from 'node:fs';
+import path from 'node:path';
+import process from 'node:process';
+import { mkdir, readFile, readdir, stat, writeFile } from 'node:fs/promises';
+
+import { GeminiClient, GeneratedImage, Model, type ModelOutput } from './gemini-webapi/index.js';
+import { resolveGeminiWebChromeProfileDir, resolveGeminiWebCookiePath, resolveGeminiWebSessionPath, resolveGeminiWebSessionsDir } from './gemini-webapi/utils/index.js';
+
+type CliArgs = {
+  prompt: string | null;
+  promptFiles: string[];
+  modelId: string;
+  json: boolean;
+  imagePath: string | null;
+  referenceImages: string[];
+  sessionId: string | null;
+  listSessions: boolean;
+  login: boolean;
+  cookiePath: string | null;
+  profileDir: string | null;
+  help: boolean;
+};
+
+type SessionRecord = {
+  id: string;
+  metadata: Array<string | null>;
+  messages: Array<{ role: 'user' | 'assistant'; content: string; timestamp: string; error?: string }>;
+  createdAt: string;
+  updatedAt: string;
+};
+
+type LegacySessionV1 = {
+  version?: number;
+  sessionId?: string;
+  updatedAt?: string;
+  conversationId?: string | null;
+  responseId?: string | null;
+  choiceId?: string | null;
+  chatMetadata?: unknown;
+};
+
+function normalizeSessionMetadata(input: unknown): Array<string | null> {
+  if (Array.isArray(input)) {
+    const out: Array<string | null> = [];
+    for (const v of input.slice(0, 3)) out.push(typeof v === 'string' ? v : null);
+    return out.length > 0 ? out : [null, null, null];
+  }
+
+  if (input && typeof input === 'object') {
+    const v1 = input as LegacySessionV1;
+    if (Array.isArray(v1.chatMetadata)) return normalizeSessionMetadata(v1.chatMetadata);
+
+    const conv = typeof v1.conversationId === 'string' ? v1.conversationId : null;
+    const rid = typeof v1.responseId === 'string' ? v1.responseId : null;
+    const rcid = typeof v1.choiceId === 'string' ? v1.choiceId : null;
+    if (conv || rid || rcid) return [conv, rid, rcid];
+  }
+
+  return [null, null, null];
+}
+
+function printUsage(cookiePath: string, profileDir: string): void {
+  console.log(`Usage:
+  npx -y bun skills/baoyu-gemini-web/scripts/main.ts --prompt "Hello"
+  npx -y bun skills/baoyu-gemini-web/scripts/main.ts "Hello"
+  npx -y bun skills/baoyu-gemini-web/scripts/main.ts --prompt "A cute cat" --image generated.png
+  npx -y bun skills/baoyu-gemini-web/scripts/main.ts --promptfiles system.md content.md --image out.png
+
+Multi-turn conversation (agent generates unique sessionId):
+  npx -y bun skills/baoyu-gemini-web/scripts/main.ts "Remember 42" --sessionId abc123
+  npx -y bun skills/baoyu-gemini-web/scripts/main.ts "What number?" --sessionId abc123
+
+Options:
+  -p, --prompt <text>       Prompt text
+  --promptfiles <files...>  Read prompt from one or more files (concatenated in order)
+  -m, --model <id>          gemini-3-pro | gemini-2.5-pro | gemini-2.5-flash (default: gemini-3-pro)
+  --json                    Output JSON
+  --image [path]            Generate an image and save it (default: ./generated.png)
+  --reference <files...>    Reference images for vision input
+  --ref <files...>          Alias for --reference
+  --sessionId <id>          Session ID for multi-turn conversation (agent should generate unique ID)
+  --list-sessions           List saved sessions (max 100, sorted by update time)
+  --login                   Only refresh cookies, then exit
+  --cookie-path <path>      Cookie file path (default: ${cookiePath})
+  --profile-dir <path>      Chrome profile dir (default: ${profileDir})
+  -h, --help                Show help
+
+Env overrides:
+  GEMINI_WEB_DATA_DIR, GEMINI_WEB_COOKIE_PATH, GEMINI_WEB_CHROME_PROFILE_DIR, GEMINI_WEB_CHROME_PATH`);
+}
+
+function parseArgs(argv: string[]): CliArgs {
+  const out: CliArgs = {
+    prompt: null,
+    promptFiles: [],
+    modelId: 'gemini-3-pro',
+    json: false,
+    imagePath: null,
+    referenceImages: [],
+    sessionId: null,
+    listSessions: false,
+    login: false,
+    cookiePath: null,
+    profileDir: null,
+    help: false,
+  };
+
+  const positional: string[] = [];
+
+  const takeMany = (i: number): { items: string[]; next: number } => {
+    const items: string[] = [];
+    let j = i + 1;
+    while (j < argv.length) {
+      const v = argv[j]!;
+      if (v.startsWith('-')) break;
+      items.push(v);
+      j++;
+    }
+    return { items, next: j - 1 };
+  };
+
+  for (let i = 0; i < argv.length; i++) {
+    const a = argv[i]!;
+
+    if (a === '--help' || a === '-h') {
+      out.help = true;
+      continue;
+    }
+
+    if (a === '--json') {
+      out.json = true;
+      continue;
+    }
+
+    if (a === '--list-sessions') {
+      out.listSessions = true;
+      continue;
+    }
+
+    if (a === '--login') {
+      out.login = true;
+      continue;
+    }
+
+    if (a === '--prompt' || a === '-p') {
+      const v = argv[++i];
+      if (!v) throw new Error(`Missing value for ${a}`);
+      out.prompt = v;
+      continue;
+    }
+
+    if (a === '--promptfiles') {
+      const { items, next } = takeMany(i);
+      if (items.length === 0) throw new Error('Missing files for --promptfiles');
+      out.promptFiles.push(...items);
+      i = next;
+      continue;
+    }
+
+    if (a === '--model' || a === '-m') {
+      const v = argv[++i];
+      if (!v) throw new Error(`Missing value for ${a}`);
+      out.modelId = v;
+      continue;
+    }
+
+    if (a === '--sessionId') {
+      const v = argv[++i];
+      if (!v) throw new Error('Missing value for --sessionId');
+      out.sessionId = v;
+      continue;
+    }
+
+    if (a === '--cookie-path') {
+      const v = argv[++i];
+      if (!v) throw new Error('Missing value for --cookie-path');
+      out.cookiePath = v;
+      continue;
+    }
+
+    if (a === '--profile-dir') {
+      const v = argv[++i];
+      if (!v) throw new Error('Missing value for --profile-dir');
+      out.profileDir = v;
+      continue;
+    }
+
+    if (a === '--image' || a.startsWith('--image=')) {
+      let v: string | null = null;
+      if (a.startsWith('--image=')) {
+        v = a.slice('--image='.length).trim();
+      } else {
+        const maybe = argv[i + 1];
+        if (maybe && !maybe.startsWith('-')) {
+          v = maybe;
+          i++;
+        }
+      }
+
+      out.imagePath = v && v.length > 0 ? v : 'generated.png';
+      continue;
+    }
+
+    if (a === '--reference' || a === '--ref') {
+      const { items, next } = takeMany(i);
+      if (items.length === 0) throw new Error(`Missing files for ${a}`);
+      out.referenceImages.push(...items);
+      i = next;
+      continue;
+    }
+
+    if (a.startsWith('-')) {
+      throw new Error(`Unknown option: ${a}`);
+    }
+
+    positional.push(a);
+  }
+
+  if (!out.prompt && out.promptFiles.length === 0 && positional.length > 0) {
+    out.prompt = positional.join(' ');
+  }
+
+  return out;
+}
+
+function resolveModel(id: string): Model {
+  const k = id.trim();
+  if (k === 'gemini-3-pro') return Model.G_3_0_PRO;
+  if (k === 'gemini-3.0-pro') return Model.G_3_0_PRO;
+  if (k === 'gemini-2.5-pro') return Model.G_2_5_PRO;
+  if (k === 'gemini-2.5-flash') return Model.G_2_5_FLASH;
+  return Model.from_name(k);
+}
+
+async function readPromptFromFiles(files: string[]): Promise<string> {
+  const parts: string[] = [];
+  for (const f of files) {
+    parts.push(await readFile(f, 'utf8'));
+  }
+  return parts.join('\n\n');
+}
+
+async function readPromptFromStdin(): Promise<string | null> {
+  if (process.stdin.isTTY) return null;
+  try {
+    // Bun provides Bun.stdin; Node-compatible read can be flaky across runtimes.
+    const t = await Bun.stdin.text();
+    const v = t.trim();
+    return v.length > 0 ? v : null;
+  } catch {
+    return null;
+  }
+}
+
+function normalizeOutputImagePath(p: string): string {
+  const full = path.resolve(p);
+  const ext = path.extname(full);
+  if (ext) return full;
+  return `${full}.png`;
+}
+
+async function loadSession(id: string): Promise<SessionRecord | null> {
+  const p = resolveGeminiWebSessionPath(id);
+  try {
+    const raw = await readFile(p, 'utf8');
+    const j = JSON.parse(raw) as unknown;
+    if (!j || typeof j !== 'object') return null;
+
+    const sid = (typeof (j as any).id === 'string' && (j as any).id.trim()) || (typeof (j as any).sessionId === 'string' && (j as any).sessionId.trim()) || id;
+    const metadata = normalizeSessionMetadata((j as any).metadata ?? (j as any).chatMetadata ?? j);
+    const messages = Array.isArray((j as any).messages) ? ((j as any).messages as SessionRecord['messages']) : [];
+    const createdAt =
+      typeof (j as any).createdAt === 'string'
+        ? ((j as any).createdAt as string)
+        : typeof (j as any).updatedAt === 'string'
+          ? ((j as any).updatedAt as string)
+          : new Date().toISOString();
+    const updatedAt = typeof (j as any).updatedAt === 'string' ? ((j as any).updatedAt as string) : createdAt;
+
+    return {
+      id: sid,
+      metadata,
+      messages,
+      createdAt,
+      updatedAt,
+    };
+  } catch {
+    return null;
+  }
+}
+
+async function saveSession(rec: SessionRecord): Promise<void> {
+  const dir = resolveGeminiWebSessionsDir();
+  await mkdir(dir, { recursive: true });
+  const p = resolveGeminiWebSessionPath(rec.id);
+  const tmp = `${p}.tmp.${Date.now()}`;
+  await writeFile(tmp, JSON.stringify(rec, null, 2), 'utf8');
+  await fs.promises.rename(tmp, p);
+}
+
+async function listSessions(): Promise<SessionRecord[]> {
+  const dir = resolveGeminiWebSessionsDir();
+  try {
+    const names = await readdir(dir);
+    const items: Array<{ path: string; st: number }> = [];
+    for (const n of names) {
+      if (!n.endsWith('.json')) continue;
+      const p = path.join(dir, n);
+      try {
+        const s = await stat(p);
+        items.push({ path: p, st: s.mtimeMs });
+      } catch {}
+    }
+
+    items.sort((a, b) => b.st - a.st);
+    const out: SessionRecord[] = [];
+    for (const it of items.slice(0, 100)) {
+      try {
+        const raw = await readFile(it.path, 'utf8');
+        const j = JSON.parse(raw) as any;
+        const id =
+          (typeof j?.id === 'string' && j.id.trim()) ||
+          (typeof j?.sessionId === 'string' && j.sessionId.trim()) ||
+          path.basename(it.path, '.json');
+        out.push({
+          id,
+          metadata: normalizeSessionMetadata(j?.metadata ?? j?.chatMetadata ?? j),
+          messages: Array.isArray(j?.messages) ? j.messages : [],
+          createdAt:
+            typeof j?.createdAt === 'string'
+              ? j.createdAt
+              : typeof j?.updatedAt === 'string'
+                ? j.updatedAt
+                : new Date(it.st).toISOString(),
+          updatedAt: typeof j?.updatedAt === 'string' ? j.updatedAt : new Date(it.st).toISOString(),
+        });
+      } catch {}
+    }
+
+    out.sort((a, b) => (b.updatedAt || '').localeCompare(a.updatedAt || ''));
+    return out.slice(0, 100);
+  } catch {
+    return [];
+  }
+}
+
+function formatJson(out: ModelOutput, extra?: Record<string, unknown>): string {
+  const candidates = out.candidates.map((c) => ({
+    rcid: c.rcid,
+    text: c.text,
+    thoughts: c.thoughts,
+    images: c.images.map((img) => ({
+      url: img.url,
+      title: img.title,
+      alt: img.alt,
+      kind: img instanceof GeneratedImage ? 'generated' : 'web',
+    })),
+  }));
+
+  return JSON.stringify(
+    {
+      text: out.text,
+      thoughts: out.thoughts,
+      metadata: out.metadata,
+      chosen: out.chosen,
+      candidates,
+      ...extra,
+    },
+    null,
+    2,
+  );
+}
+
+async function main(): Promise<void> {
+  const args = parseArgs(process.argv.slice(2));
+
+  if (args.cookiePath) process.env.GEMINI_WEB_COOKIE_PATH = args.cookiePath;
+  if (args.profileDir) process.env.GEMINI_WEB_CHROME_PROFILE_DIR = args.profileDir;
+
+  const cookiePath = resolveGeminiWebCookiePath();
+  const profileDir = resolveGeminiWebChromeProfileDir();
+
+  if (args.help) {
+    printUsage(cookiePath, profileDir);
+    return;
+  }
+
+  if (args.listSessions) {
+    const ss = await listSessions();
+    for (const s of ss) {
+      const n = s.messages.length;
+      const last = s.messages.slice(-1)[0];
+      const lastLine = last?.content ? String(last.content).split('\n')[0] : '';
+      console.log(`${s.id}\t${s.updatedAt}\t${n}\t${lastLine}`);
+    }
+    return;
+  }
+
+  if (args.login) {
+    process.env.GEMINI_WEB_LOGIN = '1';
+    const c = new GeminiClient();
+    await c.init({ verbose: true });
+    await c.close();
+    if (!args.json) console.log(`Cookie refreshed: ${cookiePath}`);
+    else console.log(JSON.stringify({ ok: true, cookiePath }, null, 2));
+    return;
+  }
+
+  let prompt: string | null = args.prompt;
+  if (!prompt && args.promptFiles.length > 0) prompt = await readPromptFromFiles(args.promptFiles);
+  if (!prompt) prompt = await readPromptFromStdin();
+
+  if (!prompt) {
+    printUsage(cookiePath, profileDir);
+    process.exitCode = 1;
+    return;
+  }
+
+  const model = resolveModel(args.modelId);
+
+  const c = new GeminiClient();
+  await c.init({ verbose: false });
+  try {
+    let sess: SessionRecord | null = null;
+    let chat = null as any;
+
+    if (args.sessionId) {
+      sess = (await loadSession(args.sessionId)) ?? {
+        id: args.sessionId,
+        metadata: [null, null, null],
+        messages: [],
+        createdAt: new Date().toISOString(),
+        updatedAt: new Date().toISOString(),
+      };
+      chat = c.start_chat({ metadata: sess.metadata, model });
+    }
+
+    const files = args.referenceImages.length > 0 ? args.referenceImages : null;
+
+    let out: ModelOutput;
+    if (chat) out = await chat.send_message(prompt, files);
+    else out = await c.generate_content(prompt, files, model);
+
+    let savedImage: string | null = null;
+    if (args.imagePath) {
+      const p = normalizeOutputImagePath(args.imagePath);
+      const dir = path.dirname(p);
+      await mkdir(dir, { recursive: true });
+
+      const img = out.images[0];
+      if (!img) {
+        throw new Error('No image returned in response.');
+      }
+
+      const fn = path.basename(p);
+      const dp = dir;
+
+      if (img instanceof GeneratedImage) {
+        savedImage = await img.save(dp, fn, undefined, false, false, true);
+      } else {
+        savedImage = await img.save(dp, fn, c.cookies, false, false);
+      }
+    }
+
+    if (sess && args.sessionId) {
+      const now = new Date().toISOString();
+      sess.updatedAt = now;
+      sess.metadata = (chat?.metadata ?? sess.metadata).slice(0, 3);
+      sess.messages.push({ role: 'user', content: prompt, timestamp: now });
+      sess.messages.push({ role: 'assistant', content: out.text ?? '', timestamp: now });
+      await saveSession(sess);
+    }
+
+    if (args.json) {
+      console.log(formatJson(out, { savedImage, sessionId: args.sessionId, model: model.model_name }));
+    } else if (args.imagePath) {
+      console.log(savedImage ?? '');
+    } else {
+      console.log(out.text);
+    }
+  } finally {
+    await c.close();
+  }
+}
+
+main().catch((e) => {
+  const msg = e instanceof Error ? e.message : String(e);
+  console.error(msg);
+  process.exit(1);
+});
@@ -0,0 +1,84 @@
+---
+name: baoyu-post-to-wechat
+description: Post content to WeChat Official Account (微信公众号). Supports both article posting (文章) and image-text posting (图文).
+---
+
+# Post to WeChat Official Account (微信公众号)
+
+Post content to WeChat Official Account using Chrome CDP automation.
+
+## 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. Replace all `${SKILL_DIR}` in this document with the actual path
+
+**Script Reference**:
+| Script | Purpose |
+|--------|---------|
+| `scripts/wechat-browser.ts` | Image-text posts (图文) |
+| `scripts/wechat-article.ts` | Full article posting (文章) |
+| `scripts/md-to-wechat.ts` | Markdown → WeChat HTML conversion |
+| `scripts/copy-to-clipboard.ts` | Copy content to clipboard |
+| `scripts/paste-from-clipboard.ts` | Send real paste keystroke |
+
+## Quick Usage
+
+### Image-Text (图文) - Multiple images with title/content
+
+```bash
+# From markdown file and image directory
+npx -y bun ${SKILL_DIR}/scripts/wechat-browser.ts --markdown article.md --images ./images/
+
+# With explicit parameters
+npx -y bun ${SKILL_DIR}/scripts/wechat-browser.ts --title "标题" --content "内容" --image img1.png --image img2.png --submit
+```
+
+### Article (文章) - Full markdown with formatting
+
+```bash
+# Post markdown article
+npx -y bun ${SKILL_DIR}/scripts/wechat-article.ts --markdown article.md --theme grace
+```
+
+> **Note**: `${SKILL_DIR}` represents this skill's installation directory. Agent replaces with actual path at runtime.
+
+## References
+
+- **Image-Text Posting**: See `references/image-text-posting.md` for detailed image-text posting guide
+- **Article Posting**: See `references/article-posting.md` for detailed article posting guide
+
+## Prerequisites
+
+- Google Chrome installed
+- `bun` runtime (via `npx -y bun`)
+- First run: log in to WeChat Official Account in the opened browser window
+
+## Features
+
+| Feature | Image-Text | Article |
+|---------|------------|---------|
+| Multiple images | ✓ (up to 9) | ✓ (inline) |
+| Markdown support | Title/content extraction | Full formatting |
+| Auto title compression | ✓ (to 20 chars) | ✗ |
+| Content compression | ✓ (to 1000 chars) | ✗ |
+| Themes | ✗ | ✓ (default, grace, simple) |
+
+## Troubleshooting
+
+- **Not logged in**: First run opens browser - scan QR code to log in, session is preserved
+- **Chrome not found**: Set `WECHAT_BROWSER_CHROME_PATH` environment variable
+- **Paste fails**: Check system clipboard permissions
+
+## Extension Support
+
+Custom configurations via EXTEND.md.
+
+**Check paths** (priority order):
+1. `.baoyu-skills/baoyu-post-to-wechat/EXTEND.md` (project)
+2. `~/.baoyu-skills/baoyu-post-to-wechat/EXTEND.md` (user)
+
+If found, load before workflow. Extension content overrides defaults.
@@ -0,0 +1,89 @@
+# Article Posting (文章发表)
+
+Post markdown articles to WeChat Official Account with full formatting support.
+
+## Usage
+
+```bash
+# Post markdown article
+npx -y bun ./scripts/wechat-article.ts --markdown article.md
+
+# With theme
+npx -y bun ./scripts/wechat-article.ts --markdown article.md --theme grace
+
+# With explicit options
+npx -y bun ./scripts/wechat-article.ts --markdown article.md --author "作者名" --summary "摘要"
+```
+
+## Parameters
+
+| Parameter | Description |
+|-----------|-------------|
+| `--markdown <path>` | Markdown file to convert and post |
+| `--theme <name>` | Theme: default, grace, or simple |
+| `--title <text>` | Override title (auto-extracted from markdown) |
+| `--author <name>` | Author name (default: 宝玉) |
+| `--summary <text>` | Article summary |
+| `--html <path>` | Pre-rendered HTML file (alternative to markdown) |
+| `--profile <dir>` | Chrome profile directory |
+
+## Markdown Format
+
+```markdown
+---
+title: Article Title
+author: Author Name
+---
+
+# Title (becomes article title)
+
+Regular paragraph with **bold** and *italic*.
+
+## Section Header
+
+![Image description](./image.png)
+
+- List item 1
+- List item 2
+
+> Blockquote text
+
+[Link text](https://example.com)
+```
+
+## Image Handling
+
+1. **Parse**: Images in markdown are replaced with `[[IMAGE_PLACEHOLDER_N]]`
+2. **Render**: HTML is generated with placeholders in text
+3. **Paste**: HTML content is pasted into WeChat editor
+4. **Replace**: For each placeholder:
+   - Find and select the placeholder text
+   - Scroll into view
+   - Press Backspace to delete the placeholder
+   - Paste the image from clipboard
+
+## Scripts
+
+| Script | Purpose |
+|--------|---------|
+| `wechat-article.ts` | Main article publishing script |
+| `md-to-wechat.ts` | Markdown to HTML with placeholders |
+| `md/render.ts` | Markdown rendering with themes |
+
+## Example Session
+
+```
+User: /post-to-wechat --markdown ./article.md
+
+Claude:
+1. Parses markdown, finds 5 images
+2. Generates HTML with placeholders
+3. Opens Chrome, navigates to WeChat editor
+4. Pastes HTML content
+5. For each image:
+   - Selects [[IMAGE_PLACEHOLDER_1]]
+   - Scrolls into view
+   - Presses Backspace to delete
+   - Pastes image
+6. Reports: "Article composed with 5 images."
+```
@@ -0,0 +1,92 @@
+# Image-Text Posting (图文发表)
+
+Post image-text messages with multiple images to WeChat Official Account.
+
+## Usage
+
+```bash
+# Post with images and markdown file (title/content extracted automatically)
+npx -y bun ./scripts/wechat-browser.ts --markdown source.md --images ./images/
+
+# Post with explicit title and content
+npx -y bun ./scripts/wechat-browser.ts --title "标题" --content "内容" --image img1.png --image img2.png
+
+# Save as draft
+npx -y bun ./scripts/wechat-browser.ts --markdown source.md --images ./images/ --submit
+```
+
+## Parameters
+
+| Parameter | Description |
+|-----------|-------------|
+| `--markdown <path>` | Markdown file for title/content extraction |
+| `--images <dir>` | Directory containing images (sorted by name) |
+| `--title <text>` | Article title (max 20 chars, auto-compressed if too long) |
+| `--content <text>` | Article content (max 1000 chars, auto-compressed if too long) |
+| `--image <path>` | Single image file (can be repeated) |
+| `--submit` | Save as draft (default: preview only) |
+| `--profile <dir>` | Chrome profile directory |
+
+## Auto Title/Content from Markdown
+
+When using `--markdown`, the script:
+
+1. **Parses frontmatter** for title and author:
+   ```yaml
+   ---
+   title: 文章标题
+   author: 作者名
+   ---
+   ```
+
+2. **Falls back to H1** if no frontmatter title:
+   ```markdown
+   # 这将成为标题
+   ```
+
+3. **Compresses title** to 20 characters if too long:
+   - Original: "如何在一天内彻底重塑你的人生"
+   - Compressed: "一天彻底重塑你的人生"
+
+4. **Extracts first paragraphs** as content (max 1000 chars)
+
+## Image Directory Mode
+
+When using `--images <dir>`:
+
+- All PNG/JPG files in directory are uploaded
+- Files are sorted alphabetically by name
+- Naming convention: `01-cover.png`, `02-content.png`, etc.
+
+## Constraints
+
+| Field | Max Length | Notes |
+|-------|------------|-------|
+| Title | 20 chars | Auto-compressed if longer |
+| Content | 1000 chars | Auto-compressed if longer |
+| Images | 9 max | WeChat limit |
+
+## Example Session
+
+```
+User: /post-to-wechat --markdown ./article.md --images ./xhs-images/
+
+Claude:
+1. Parses markdown meta:
+   - Title: "如何在一天内彻底重塑你的人生" → "一天内重塑你的人生"
+   - Author: from frontmatter or default
+2. Extracts content from first paragraphs
+3. Finds 7 images in xhs-images/
+4. Opens Chrome, navigates to WeChat "图文" editor
+5. Uploads all images
+6. Fills title and content
+7. Reports: "Image-text posted with 7 images."
+```
+
+## Scripts
+
+| Script | Purpose |
+|--------|---------|
+| `wechat-browser.ts` | Main image-text posting script |
+| `cdp.ts` | Chrome DevTools Protocol utilities |
+| `copy-to-clipboard.ts` | Clipboard operations |
@@ -0,0 +1,274 @@
+import { spawn } from 'node:child_process';
+import fs from 'node:fs';
+import { mkdir } from 'node:fs/promises';
+import net from 'node:net';
+import os from 'node:os';
+import path from 'node:path';
+import process from 'node:process';
+
+export function sleep(ms: number): Promise<void> {
+  return new Promise((resolve) => setTimeout(resolve, ms));
+}
+
+export async function getFreePort(): Promise<number> {
+  return 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(): string | undefined {
+  const override = process.env.WECHAT_BROWSER_CHROME_PATH?.trim();
+  if (override && fs.existsSync(override)) return override;
+
+  const candidates: string[] = [];
+  switch (process.platform) {
+    case 'darwin':
+      candidates.push(
+        '/Applications/Google Chrome.app/Contents/MacOS/Google Chrome',
+        '/Applications/Google Chrome Canary.app/Contents/MacOS/Google Chrome Canary',
+        '/Applications/Chromium.app/Contents/MacOS/Chromium',
+      );
+      break;
+    case 'win32':
+      candidates.push(
+        'C:\\Program Files\\Google\\Chrome\\Application\\chrome.exe',
+        'C:\\Program Files (x86)\\Google\\Chrome\\Application\\chrome.exe',
+      );
+      break;
+    default:
+      candidates.push('/usr/bin/google-chrome', '/usr/bin/chromium');
+      break;
+  }
+
+  for (const p of candidates) {
+    if (fs.existsSync(p)) return p;
+  }
+  return undefined;
+}
+
+export function getDefaultProfileDir(): string {
+  const base = process.env.XDG_DATA_HOME || path.join(os.homedir(), '.local', 'share');
+  return path.join(base, 'wechat-browser-profile');
+}
+
+async function fetchJson<T = unknown>(url: string): Promise<T> {
+  const res = await fetch(url, { redirect: 'follow' });
+  if (!res.ok) throw new Error(`Request failed: ${res.status} ${res.statusText}`);
+  return (await res.json()) as T;
+}
+
+async function waitForChromeDebugPort(port: number, timeoutMs: number): 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`);
+      if (version.webSocketDebuggerUrl) return version.webSocketDebuggerUrl;
+      lastError = new Error('Missing webSocketDebuggerUrl');
+    } catch (error) {
+      lastError = error;
+    }
+    await sleep(200);
+  }
+
+  throw new Error(`Chrome debug port not ready: ${lastError instanceof Error ? lastError.message : String(lastError)}`);
+}
+
+export class CdpConnection {
+  private ws: WebSocket;
+  private nextId = 0;
+  private pending = new Map<number, { resolve: (v: unknown) => void; reject: (e: Error) => void; timer: ReturnType<typeof setTimeout> | null }>();
+  private eventHandlers = new Map<string, Set<(params: unknown) => void>>();
+
+  private constructor(ws: WebSocket) {
+    this.ws = ws;
+    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((h) => h(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): 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);
+  }
+
+  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);
+  }
+
+  async send<T = unknown>(method: string, params?: Record<string, unknown>, options?: { sessionId?: string; timeoutMs?: number }): 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 ?? 15_000;
+
+    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 interface ChromeSession {
+  cdp: CdpConnection;
+  sessionId: string;
+  targetId: string;
+}
+
+export async function launchChrome(url: string, profileDir?: string): Promise<{ cdp: CdpConnection; chrome: ReturnType<typeof spawn> }> {
+  const chromePath = findChromeExecutable();
+  if (!chromePath) throw new Error('Chrome not found. Set WECHAT_BROWSER_CHROME_PATH env var.');
+
+  const profile = profileDir ?? getDefaultProfileDir();
+  await mkdir(profile, { recursive: true });
+
+  const port = await getFreePort();
+  console.log(`[cdp] Launching Chrome (profile: ${profile})`);
+
+  const chrome = spawn(chromePath, [
+    `--remote-debugging-port=${port}`,
+    `--user-data-dir=${profile}`,
+    '--no-first-run',
+    '--no-default-browser-check',
+    '--disable-blink-features=AutomationControlled',
+    '--start-maximized',
+    url,
+  ], { stdio: 'ignore' });
+
+  const wsUrl = await waitForChromeDebugPort(port, 30_000);
+  const cdp = await CdpConnection.connect(wsUrl, 30_000);
+
+  return { cdp, chrome };
+}
+
+export async function getPageSession(cdp: CdpConnection, urlPattern: string): Promise<ChromeSession> {
+  const targets = await cdp.send<{ targetInfos: Array<{ targetId: string; url: string; type: string }> }>('Target.getTargets');
+  let pageTarget = targets.targetInfos.find((t) => t.type === 'page' && t.url.includes(urlPattern));
+
+  if (!pageTarget) throw new Error(`Page not found: ${urlPattern}`);
+
+  const { sessionId } = await cdp.send<{ sessionId: string }>('Target.attachToTarget', { targetId: pageTarget.targetId, flatten: true });
+
+  await cdp.send('Page.enable', {}, { sessionId });
+  await cdp.send('Runtime.enable', {}, { sessionId });
+  await cdp.send('DOM.enable', {}, { sessionId });
+
+  return { cdp, sessionId, targetId: pageTarget.targetId };
+}
+
+export async function waitForNewTab(cdp: CdpConnection, initialIds: Set<string>, urlPattern: string, timeoutMs = 30_000): Promise<string> {
+  const start = Date.now();
+  while (Date.now() - start < timeoutMs) {
+    const targets = await cdp.send<{ targetInfos: Array<{ targetId: string; url: string; type: string }> }>('Target.getTargets');
+    const newTab = targets.targetInfos.find(t => t.type === 'page' && !initialIds.has(t.targetId) && t.url.includes(urlPattern));
+    if (newTab) return newTab.targetId;
+    await sleep(500);
+  }
+  throw new Error(`New tab not found: ${urlPattern}`);
+}
+
+export async function clickElement(session: ChromeSession, selector: string): Promise<void> {
+  const posResult = await session.cdp.send<{ result: { value: string } }>('Runtime.evaluate', {
+    expression: `
+      (function() {
+        const el = document.querySelector('${selector}');
+        if (!el) return 'null';
+        el.scrollIntoView({ block: 'center' });
+        const rect = el.getBoundingClientRect();
+        return JSON.stringify({ x: rect.x + rect.width / 2, y: rect.y + rect.height / 2 });
+      })()
+    `,
+    returnByValue: true,
+  }, { sessionId: session.sessionId });
+
+  if (posResult.result.value === 'null') throw new Error(`Element not found: ${selector}`);
+  const pos = JSON.parse(posResult.result.value);
+
+  await session.cdp.send('Input.dispatchMouseEvent', { type: 'mousePressed', x: pos.x, y: pos.y, button: 'left', clickCount: 1 }, { sessionId: session.sessionId });
+  await sleep(50);
+  await session.cdp.send('Input.dispatchMouseEvent', { type: 'mouseReleased', x: pos.x, y: pos.y, button: 'left', clickCount: 1 }, { sessionId: session.sessionId });
+}
+
+export async function typeText(session: ChromeSession, text: string): Promise<void> {
+  const lines = text.split('\n');
+  for (let i = 0; i < lines.length; i++) {
+    if (lines[i].length > 0) {
+      await session.cdp.send('Input.insertText', { text: lines[i] }, { sessionId: session.sessionId });
+    }
+    if (i < lines.length - 1) {
+      await session.cdp.send('Input.dispatchKeyEvent', { type: 'keyDown', key: 'Enter', code: 'Enter', windowsVirtualKeyCode: 13 }, { sessionId: session.sessionId });
+      await session.cdp.send('Input.dispatchKeyEvent', { type: 'keyUp', key: 'Enter', code: 'Enter', windowsVirtualKeyCode: 13 }, { sessionId: session.sessionId });
+    }
+    await sleep(30);
+  }
+}
+
+export async function pasteFromClipboard(session: ChromeSession): Promise<void> {
+  const modifiers = process.platform === 'darwin' ? 4 : 2;
+  await session.cdp.send('Input.dispatchKeyEvent', { type: 'keyDown', key: 'v', code: 'KeyV', modifiers, windowsVirtualKeyCode: 86 }, { sessionId: session.sessionId });
+  await session.cdp.send('Input.dispatchKeyEvent', { type: 'keyUp', key: 'v', code: 'KeyV', modifiers, windowsVirtualKeyCode: 86 }, { sessionId: session.sessionId });
+}
+
+export async function evaluate<T = unknown>(session: ChromeSession, expression: string): Promise<T> {
+  const result = await session.cdp.send<{ result: { value: T } }>('Runtime.evaluate', {
+    expression,
+    returnByValue: true,
+  }, { sessionId: session.sessionId });
+  return result.result.value;
+}
@@ -0,0 +1,380 @@
+import { spawn } from 'node:child_process';
+import fs from 'node:fs';
+import { mkdtemp, rm, writeFile } from 'node:fs/promises';
+import os from 'node:os';
+import path from 'node:path';
+import process from 'node:process';
+
+const SUPPORTED_IMAGE_EXTS = new Set(['.jpg', '.jpeg', '.png', '.gif', '.webp']);
+
+function printUsage(exitCode = 0): never {
+  console.log(`Copy image or HTML to system clipboard
+
+Supports:
+  - Image files (jpg, png, gif, webp) - copies as image data
+  - HTML content - copies as rich text for paste
+
+Usage:
+  # Copy image to clipboard
+  npx -y bun copy-to-clipboard.ts image /path/to/image.jpg
+
+  # Copy HTML to clipboard
+  npx -y bun copy-to-clipboard.ts html "<p>Hello</p>"
+
+  # Copy HTML from file
+  npx -y bun copy-to-clipboard.ts html --file /path/to/content.html
+`);
+  process.exit(exitCode);
+}
+
+function resolvePath(filePath: string): string {
+  return path.isAbsolute(filePath) ? filePath : path.resolve(process.cwd(), filePath);
+}
+
+function inferImageMimeType(imagePath: string): string {
+  const ext = path.extname(imagePath).toLowerCase();
+  switch (ext) {
+    case '.jpg':
+    case '.jpeg':
+      return 'image/jpeg';
+    case '.png':
+      return 'image/png';
+    case '.gif':
+      return 'image/gif';
+    case '.webp':
+      return 'image/webp';
+    default:
+      return 'application/octet-stream';
+  }
+}
+
+type RunResult = { stdout: string; stderr: string; exitCode: number };
+
+async function runCommand(
+  command: string,
+  args: string[],
+  options?: { input?: string | Buffer; allowNonZeroExit?: boolean },
+): Promise<RunResult> {
+  return await new Promise<RunResult>((resolve, reject) => {
+    const child = spawn(command, args, { stdio: ['pipe', 'pipe', 'pipe'] });
+    const stdoutChunks: Buffer[] = [];
+    const stderrChunks: Buffer[] = [];
+
+    child.stdout.on('data', (chunk) => stdoutChunks.push(Buffer.from(chunk)));
+    child.stderr.on('data', (chunk) => stderrChunks.push(Buffer.from(chunk)));
+    child.on('error', reject);
+    child.on('close', (code) => {
+      resolve({
+        stdout: Buffer.concat(stdoutChunks).toString('utf8'),
+        stderr: Buffer.concat(stderrChunks).toString('utf8'),
+        exitCode: code ?? 0,
+      });
+    });
+
+    if (options?.input != null) child.stdin.write(options.input);
+    child.stdin.end();
+  }).then((result) => {
+    if (!options?.allowNonZeroExit && result.exitCode !== 0) {
+      const details = result.stderr.trim() || result.stdout.trim();
+      throw new Error(`Command failed (${command}): exit ${result.exitCode}${details ? `\n${details}` : ''}`);
+    }
+    return result;
+  });
+}
+
+async function commandExists(command: string): Promise<boolean> {
+  if (process.platform === 'win32') {
+    const result = await runCommand('where', [command], { allowNonZeroExit: true });
+    return result.exitCode === 0 && result.stdout.trim().length > 0;
+  }
+  const result = await runCommand('which', [command], { allowNonZeroExit: true });
+  return result.exitCode === 0 && result.stdout.trim().length > 0;
+}
+
+async function runCommandWithFileStdin(command: string, args: string[], filePath: string): Promise<void> {
+  await new Promise<void>((resolve, reject) => {
+    const child = spawn(command, args, { stdio: ['pipe', 'pipe', 'pipe'] });
+    const stderrChunks: Buffer[] = [];
+    const stdoutChunks: Buffer[] = [];
+
+    child.stdout.on('data', (chunk) => stdoutChunks.push(Buffer.from(chunk)));
+    child.stderr.on('data', (chunk) => stderrChunks.push(Buffer.from(chunk)));
+    child.on('error', reject);
+    child.on('close', (code) => {
+      const exitCode = code ?? 0;
+      if (exitCode !== 0) {
+        const details = Buffer.concat(stderrChunks).toString('utf8').trim() || Buffer.concat(stdoutChunks).toString('utf8').trim();
+        reject(
+          new Error(`Command failed (${command}): exit ${exitCode}${details ? `\n${details}` : ''}`),
+        );
+        return;
+      }
+      resolve();
+    });
+
+    fs.createReadStream(filePath).on('error', reject).pipe(child.stdin);
+  });
+}
+
+async function withTempDir<T>(prefix: string, fn: (tempDir: string) => Promise<T>): Promise<T> {
+  const tempDir = await mkdtemp(path.join(os.tmpdir(), prefix));
+  try {
+    return await fn(tempDir);
+  } finally {
+    await rm(tempDir, { recursive: true, force: true });
+  }
+}
+
+function getMacSwiftClipboardSource(): string {
+  return `import AppKit
+import Foundation
+
+func die(_ message: String, _ code: Int32 = 1) -> Never {
+  FileHandle.standardError.write(message.data(using: .utf8)!)
+  exit(code)
+}
+
+if CommandLine.arguments.count < 3 {
+  die("Usage: clipboard.swift <image|html> <path>\\n")
+}
+
+let mode = CommandLine.arguments[1]
+let inputPath = CommandLine.arguments[2]
+let pasteboard = NSPasteboard.general
+pasteboard.clearContents()
+
+switch mode {
+case "image":
+  guard let image = NSImage(contentsOfFile: inputPath) else {
+    die("Failed to load image: \\(inputPath)\\n")
+  }
+  if !pasteboard.writeObjects([image]) {
+    die("Failed to write image to clipboard\\n")
+  }
+
+case "html":
+  let url = URL(fileURLWithPath: inputPath)
+  let data: Data
+  do {
+    data = try Data(contentsOf: url)
+  } catch {
+    die("Failed to read HTML file: \\(inputPath)\\n")
+  }
+
+  _ = pasteboard.setData(data, forType: .html)
+
+  let options: [NSAttributedString.DocumentReadingOptionKey: Any] = [
+    .documentType: NSAttributedString.DocumentType.html,
+    .characterEncoding: String.Encoding.utf8.rawValue
+  ]
+
+  if let attr = try? NSAttributedString(data: data, options: options, documentAttributes: nil) {
+    pasteboard.setString(attr.string, forType: .string)
+    if let rtf = try? attr.data(
+      from: NSRange(location: 0, length: attr.length),
+      documentAttributes: [.documentType: NSAttributedString.DocumentType.rtf]
+    ) {
+      _ = pasteboard.setData(rtf, forType: .rtf)
+    }
+  } else if let html = String(data: data, encoding: .utf8) {
+    pasteboard.setString(html, forType: .string)
+  }
+
+default:
+  die("Unknown mode: \\(mode)\\n")
+}
+`;
+}
+
+async function copyImageMac(imagePath: string): Promise<void> {
+  await withTempDir('copy-to-clipboard-', async (tempDir) => {
+    const swiftPath = path.join(tempDir, 'clipboard.swift');
+    await writeFile(swiftPath, getMacSwiftClipboardSource(), 'utf8');
+    await runCommand('swift', [swiftPath, 'image', imagePath]);
+  });
+}
+
+async function copyHtmlMac(htmlFilePath: string): Promise<void> {
+  await withTempDir('copy-to-clipboard-', async (tempDir) => {
+    const swiftPath = path.join(tempDir, 'clipboard.swift');
+    await writeFile(swiftPath, getMacSwiftClipboardSource(), 'utf8');
+    await runCommand('swift', [swiftPath, 'html', htmlFilePath]);
+  });
+}
+
+async function copyImageLinux(imagePath: string): Promise<void> {
+  const mime = inferImageMimeType(imagePath);
+  if (await commandExists('wl-copy')) {
+    await runCommandWithFileStdin('wl-copy', ['--type', mime], imagePath);
+    return;
+  }
+  if (await commandExists('xclip')) {
+    await runCommand('xclip', ['-selection', 'clipboard', '-t', mime, '-i', imagePath]);
+    return;
+  }
+  throw new Error('No clipboard tool found. Install `wl-clipboard` (wl-copy) or `xclip`.');
+}
+
+async function copyHtmlLinux(htmlFilePath: string): Promise<void> {
+  if (await commandExists('wl-copy')) {
+    await runCommandWithFileStdin('wl-copy', ['--type', 'text/html'], htmlFilePath);
+    return;
+  }
+  if (await commandExists('xclip')) {
+    await runCommand('xclip', ['-selection', 'clipboard', '-t', 'text/html', '-i', htmlFilePath]);
+    return;
+  }
+  throw new Error('No clipboard tool found. Install `wl-clipboard` (wl-copy) or `xclip`.');
+}
+
+async function copyImageWindows(imagePath: string): Promise<void> {
+  const ps = [
+    'param([string]$Path)',
+    'Add-Type -AssemblyName System.Windows.Forms',
+    'Add-Type -AssemblyName System.Drawing',
+    '$img = [System.Drawing.Image]::FromFile($Path)',
+    '[System.Windows.Forms.Clipboard]::SetImage($img)',
+    '$img.Dispose()',
+  ].join('; ');
+  await runCommand('powershell.exe', ['-NoProfile', '-Sta', '-Command', ps, '-Path', imagePath]);
+}
+
+async function copyHtmlWindows(htmlFilePath: string): Promise<void> {
+  const ps = [
+    'param([string]$Path)',
+    'Add-Type -AssemblyName System.Windows.Forms',
+    '$html = Get-Content -Raw -LiteralPath $Path',
+    '[System.Windows.Forms.Clipboard]::SetText($html, [System.Windows.Forms.TextDataFormat]::Html)',
+  ].join('; ');
+  await runCommand('powershell.exe', ['-NoProfile', '-Sta', '-Command', ps, '-Path', htmlFilePath]);
+}
+
+async function copyImageToClipboard(imagePathInput: string): Promise<void> {
+  const imagePath = resolvePath(imagePathInput);
+  const ext = path.extname(imagePath).toLowerCase();
+  if (!SUPPORTED_IMAGE_EXTS.has(ext)) {
+    throw new Error(
+      `Unsupported image type: ${ext || '(none)'} (supported: ${Array.from(SUPPORTED_IMAGE_EXTS).join(', ')})`,
+    );
+  }
+  if (!fs.existsSync(imagePath)) throw new Error(`File not found: ${imagePath}`);
+
+  switch (process.platform) {
+    case 'darwin':
+      await copyImageMac(imagePath);
+      return;
+    case 'linux':
+      await copyImageLinux(imagePath);
+      return;
+    case 'win32':
+      await copyImageWindows(imagePath);
+      return;
+    default:
+      throw new Error(`Unsupported platform: ${process.platform}`);
+  }
+}
+
+async function copyHtmlFileToClipboard(htmlFilePathInput: string): Promise<void> {
+  const htmlFilePath = resolvePath(htmlFilePathInput);
+  if (!fs.existsSync(htmlFilePath)) throw new Error(`File not found: ${htmlFilePath}`);
+
+  switch (process.platform) {
+    case 'darwin':
+      await copyHtmlMac(htmlFilePath);
+      return;
+    case 'linux':
+      await copyHtmlLinux(htmlFilePath);
+      return;
+    case 'win32':
+      await copyHtmlWindows(htmlFilePath);
+      return;
+    default:
+      throw new Error(`Unsupported platform: ${process.platform}`);
+  }
+}
+
+async function readStdinText(): Promise<string | null> {
+  if (process.stdin.isTTY) return null;
+  const chunks: Buffer[] = [];
+  for await (const chunk of process.stdin) {
+    chunks.push(Buffer.isBuffer(chunk) ? chunk : Buffer.from(chunk));
+  }
+  const text = Buffer.concat(chunks).toString('utf8');
+  return text.length > 0 ? text : null;
+}
+
+async function copyHtmlToClipboard(args: string[]): Promise<void> {
+  let htmlFile: string | undefined;
+  const positional: string[] = [];
+
+  for (let i = 0; i < args.length; i += 1) {
+    const arg = args[i] ?? '';
+    if (arg === '--help' || arg === '-h') printUsage(0);
+    if (arg === '--file') {
+      htmlFile = args[i + 1];
+      i += 1;
+      continue;
+    }
+    if (arg.startsWith('--file=')) {
+      htmlFile = arg.slice('--file='.length);
+      continue;
+    }
+    if (arg === '--') {
+      positional.push(...args.slice(i + 1));
+      break;
+    }
+    if (arg.startsWith('-')) {
+      throw new Error(`Unknown option: ${arg}`);
+    }
+    positional.push(arg);
+  }
+
+  if (htmlFile && positional.length > 0) {
+    throw new Error('Do not pass HTML text when using --file.');
+  }
+
+  if (htmlFile) {
+    await copyHtmlFileToClipboard(htmlFile);
+    return;
+  }
+
+  const htmlFromArgs = positional.join(' ').trim();
+  const htmlFromStdin = (await readStdinText())?.trim() ?? '';
+  const html = htmlFromArgs || htmlFromStdin;
+  if (!html) throw new Error('Missing HTML input. Provide a string or use --file.');
+
+  await withTempDir('copy-to-clipboard-', async (tempDir) => {
+    const htmlPath = path.join(tempDir, 'input.html');
+    await writeFile(htmlPath, html, 'utf8');
+    await copyHtmlFileToClipboard(htmlPath);
+  });
+}
+
+async function main(): Promise<void> {
+  const argv = process.argv.slice(2);
+  if (argv.length === 0) printUsage(1);
+
+  const command = argv[0];
+  if (command === '--help' || command === '-h') printUsage(0);
+
+  if (command === 'image') {
+    const imagePath = argv[1];
+    if (!imagePath) throw new Error('Missing image path.');
+    await copyImageToClipboard(imagePath);
+    return;
+  }
+
+  if (command === 'html') {
+    await copyHtmlToClipboard(argv.slice(1));
+    return;
+  }
+
+  throw new Error(`Unknown command: ${command}`);
+}
+
+await main().catch((err) => {
+  const message = err instanceof Error ? err.message : String(err);
+  console.error(`Error: ${message}`);
+  process.exit(1);
+});
+
@@ -0,0 +1,281 @@
+import fs from 'node:fs';
+import path from 'node:path';
+import { mkdir, writeFile } from 'node:fs/promises';
+import os from 'node:os';
+import { createHash } from 'node:crypto';
+import https from 'node:https';
+import http from 'node:http';
+import { spawnSync } from 'node:child_process';
+import process from 'node:process';
+
+interface ImageInfo {
+  placeholder: string;
+  localPath: string;
+  originalPath: string;
+}
+
+interface ParsedResult {
+  title: string;
+  author: string;
+  summary: string;
+  htmlPath: string;
+  contentImages: ImageInfo[];
+}
+
+function downloadFile(url: string, destPath: string): Promise<void> {
+  return new Promise((resolve, reject) => {
+    const protocol = url.startsWith('https') ? https : http;
+    const file = fs.createWriteStream(destPath);
+
+    const request = protocol.get(url, { headers: { 'User-Agent': 'Mozilla/5.0' } }, (response) => {
+      if (response.statusCode === 301 || response.statusCode === 302) {
+        const redirectUrl = response.headers.location;
+        if (redirectUrl) {
+          file.close();
+          fs.unlinkSync(destPath);
+          downloadFile(redirectUrl, destPath).then(resolve).catch(reject);
+          return;
+        }
+      }
+
+      if (response.statusCode !== 200) {
+        file.close();
+        fs.unlinkSync(destPath);
+        reject(new Error(`Failed to download: ${response.statusCode}`));
+        return;
+      }
+
+      response.pipe(file);
+      file.on('finish', () => {
+        file.close();
+        resolve();
+      });
+    });
+
+    request.on('error', (err) => {
+      file.close();
+      fs.unlink(destPath, () => {});
+      reject(err);
+    });
+
+    request.setTimeout(30000, () => {
+      request.destroy();
+      reject(new Error('Download timeout'));
+    });
+  });
+}
+
+function getImageExtension(urlOrPath: string): string {
+  const match = urlOrPath.match(/\.(jpg|jpeg|png|gif|webp)(\?|$)/i);
+  return match ? match[1]!.toLowerCase() : 'png';
+}
+
+async function resolveImagePath(imagePath: string, baseDir: string, tempDir: string): Promise<string> {
+  if (imagePath.startsWith('http://') || imagePath.startsWith('https://')) {
+    const hash = createHash('md5').update(imagePath).digest('hex').slice(0, 8);
+    const ext = getImageExtension(imagePath);
+    const localPath = path.join(tempDir, `remote_${hash}.${ext}`);
+
+    if (!fs.existsSync(localPath)) {
+      console.error(`[md-to-wechat] Downloading: ${imagePath}`);
+      await downloadFile(imagePath, localPath);
+    }
+    return localPath;
+  }
+
+  if (path.isAbsolute(imagePath)) {
+    return imagePath;
+  }
+
+  return path.resolve(baseDir, imagePath);
+}
+
+function parseFrontmatter(content: string): { frontmatter: Record<string, string>; body: string } {
+  const match = content.match(/^---\r?\n([\s\S]*?)\r?\n---\r?\n([\s\S]*)$/);
+  if (!match) return { frontmatter: {}, body: content };
+
+  const frontmatter: Record<string, string> = {};
+  const lines = match[1]!.split('\n');
+  for (const line of lines) {
+    const colonIdx = line.indexOf(':');
+    if (colonIdx > 0) {
+      const key = line.slice(0, colonIdx).trim();
+      let value = line.slice(colonIdx + 1).trim();
+      if ((value.startsWith('"') && value.endsWith('"')) || (value.startsWith("'") && value.endsWith("'"))) {
+        value = value.slice(1, -1);
+      }
+      frontmatter[key] = value;
+    }
+  }
+
+  return { frontmatter, body: match[2]! };
+}
+
+async function parseMarkdownForWechat(
+  markdownPath: string,
+  options?: { title?: string; theme?: string; tempDir?: string },
+): Promise<ParsedResult> {
+  const content = fs.readFileSync(markdownPath, 'utf-8');
+  const baseDir = path.dirname(markdownPath);
+  const tempDir = options?.tempDir ?? path.join(os.tmpdir(), 'wechat-article-images');
+  const theme = options?.theme ?? 'default';
+
+  await mkdir(tempDir, { recursive: true });
+
+  const { frontmatter, body } = parseFrontmatter(content);
+
+  let title = options?.title ?? frontmatter.title ?? '';
+  if (!title) {
+    const h1Match = body.match(/^#\s+(.+)$/m);
+    if (h1Match) title = h1Match[1]!;
+  }
+
+  const author = frontmatter.author ?? '';
+  let summary = frontmatter.summary ?? frontmatter.description ?? '';
+
+  if (!summary) {
+    const lines = body.split('\n');
+    for (const line of lines) {
+      const trimmed = line.trim();
+      if (!trimmed) continue;
+      if (trimmed.startsWith('#')) continue;
+      if (trimmed.startsWith('![')) continue;
+      if (trimmed.startsWith('>')) continue;
+      if (trimmed.startsWith('-') || trimmed.startsWith('*')) continue;
+      if (/^\d+\./.test(trimmed)) continue;
+
+      const cleanText = trimmed
+        .replace(/\*\*(.+?)\*\*/g, '$1')
+        .replace(/\*(.+?)\*/g, '$1')
+        .replace(/\[([^\]]+)\]\([^)]+\)/g, '$1')
+        .replace(/`([^`]+)`/g, '$1');
+
+      if (cleanText.length > 20) {
+        summary = cleanText.length > 120 ? cleanText.slice(0, 117) + '...' : cleanText;
+        break;
+      }
+    }
+  }
+
+  const images: Array<{ src: string; placeholder: string }> = [];
+  let imageCounter = 0;
+
+  const modifiedBody = body.replace(/!\[([^\]]*)\]\(([^)]+)\)/g, (match, alt, src) => {
+    const placeholder = `[[IMAGE_PLACEHOLDER_${++imageCounter}]]`;
+    images.push({ src, placeholder });
+    return placeholder;
+  });
+
+  const modifiedMarkdown = `---\n${Object.entries(frontmatter).map(([k, v]) => `${k}: ${v}`).join('\n')}\n---\n${modifiedBody}`;
+
+  const tempMdPath = path.join(tempDir, 'temp-article.md');
+  await writeFile(tempMdPath, modifiedMarkdown, 'utf-8');
+
+  const scriptDir = path.dirname(new URL(import.meta.url).pathname);
+  const renderScript = path.join(scriptDir, 'md', 'render.ts');
+
+  console.error(`[md-to-wechat] Rendering markdown with theme: ${theme}`);
+  const result = spawnSync('npx', ['-y', 'bun', renderScript, tempMdPath, '--theme', theme], {
+    stdio: ['inherit', 'pipe', 'pipe'],
+    cwd: baseDir,
+  });
+
+  if (result.status !== 0) {
+    const stderr = result.stderr?.toString() || '';
+    throw new Error(`Render failed: ${stderr}`);
+  }
+
+  const htmlPath = tempMdPath.replace(/\.md$/i, '.html');
+  if (!fs.existsSync(htmlPath)) {
+    throw new Error(`HTML file not generated: ${htmlPath}`);
+  }
+
+  const contentImages: ImageInfo[] = [];
+  for (const img of images) {
+    const localPath = await resolveImagePath(img.src, baseDir, tempDir);
+    contentImages.push({
+      placeholder: img.placeholder,
+      localPath,
+      originalPath: img.src,
+    });
+  }
+
+  return {
+    title,
+    author,
+    summary,
+    htmlPath,
+    contentImages,
+  };
+}
+
+function printUsage(): never {
+  console.log(`Convert Markdown to WeChat-ready HTML with image placeholders
+
+Usage:
+  npx -y bun md-to-wechat.ts <markdown_file> [options]
+
+Options:
+  --title <title>     Override title
+  --theme <name>      Theme name (default, grace, simple)
+  --help              Show this help
+
+Output JSON format:
+{
+  "title": "Article Title",
+  "htmlPath": "/tmp/wechat-article-images/temp-article.html",
+  "contentImages": [
+    {
+      "placeholder": "[[IMAGE_PLACEHOLDER_1]]",
+      "localPath": "/tmp/wechat-article-images/img.png",
+      "originalPath": "imgs/image.png"
+    }
+  ]
+}
+
+Example:
+  npx -y bun md-to-wechat.ts article.md
+  npx -y bun md-to-wechat.ts article.md --theme grace
+`);
+  process.exit(0);
+}
+
+async function main(): Promise<void> {
+  const args = process.argv.slice(2);
+  if (args.length === 0 || args.includes('--help') || args.includes('-h')) {
+    printUsage();
+  }
+
+  let markdownPath: string | undefined;
+  let title: string | undefined;
+  let theme: string | undefined;
+
+  for (let i = 0; i < args.length; i++) {
+    const arg = args[i]!;
+    if (arg === '--title' && args[i + 1]) {
+      title = args[++i];
+    } else if (arg === '--theme' && args[i + 1]) {
+      theme = args[++i];
+    } else if (!arg.startsWith('-')) {
+      markdownPath = arg;
+    }
+  }
+
+  if (!markdownPath) {
+    console.error('Error: Markdown file path required');
+    process.exit(1);
+  }
+
+  if (!fs.existsSync(markdownPath)) {
+    console.error(`Error: File not found: ${markdownPath}`);
+    process.exit(1);
+  }
+
+  const result = await parseMarkdownForWechat(markdownPath, { title, theme });
+  console.log(JSON.stringify(result, null, 2));
+}
+
+await main().catch((err) => {
+  console.error(`Error: ${err instanceof Error ? err.message : String(err)}`);
+  process.exit(1);
+});
@@ -0,0 +1,18 @@
+This directory contains code adapted from the doocs/md project.
+
+Original project: https://github.com/doocs/md
+License: WTFPL (Do What The Fuck You Want To Public License)
+
+            DO WHAT THE FUCK YOU WANT TO PUBLIC LICENSE
+                    Version 2, December 2004
+
+ Copyright (C) 2025 Doocs <admin@doocs.org>
+
+ Everyone is permitted to copy and distribute verbatim or modified
+ copies of this license document, and changing it is allowed as long
+ as the name is changed.
+
+            DO WHAT THE FUCK YOU WANT TO PUBLIC LICENSE
+   TERMS AND CONDITIONS FOR COPYING, DISTRIBUTION AND MODIFICATION
+
+  0. You just DO WHAT THE FUCK YOU WANT TO.
@@ -0,0 +1,284 @@
+import type { MarkedExtension, Tokens } from 'marked'
+
+export interface AlertOptions {
+  className?: string
+  variants?: AlertVariantItem[]
+  withoutStyle?: boolean
+}
+
+export interface AlertVariantItem {
+  type: string
+  icon: string
+  title?: string
+  titleClassName?: string
+}
+
+function ucfirst(str: string) {
+  return str.slice(0, 1).toUpperCase() + str.slice(1).toLowerCase()
+}
+
+/**
+ * https://github.com/bent10/marked-extensions/tree/main/packages/alert
+ * To support theme, we need to modify the source code.
+ * A [marked](https://marked.js.org/) extension to support [GFM alerts](https://github.com/orgs/community/discussions/16925).
+ */
+export function markedAlert(options: AlertOptions = {}): MarkedExtension {
+  const { className = `markdown-alert`, variants = [], withoutStyle = false } = options
+  const resolvedVariants = resolveVariants(variants)
+
+  // 提取公共的元数据构建逻辑
+  function buildMeta(variantType: string, matchedVariant: AlertVariantItem, fromContainer = false) {
+    return {
+      className,
+      variant: variantType,
+      icon: matchedVariant.icon,
+      title: matchedVariant.title ?? ucfirst(variantType),
+      titleClassName: `${className}-title`,
+      fromContainer,
+    }
+  }
+
+  // 提取公共的渲染逻辑
+  function renderAlert(token: any) {
+    const { meta, tokens = [] } = token
+    // @ts-expect-error marked renderer context has parser property
+    const text = this.parser.parse(tokens)
+    // 新主题系统：使用 CSS 选择器而非内联样式
+    let tmpl = `<blockquote class="${meta.className} ${meta.className}-${meta.variant}">\n`
+    tmpl += `<p class="${meta.titleClassName} alert-title-${meta.variant}">`
+    if (!withoutStyle) {
+      // 给 SVG 添加 class，通过 CSS 控制颜色
+      tmpl += meta.icon.replace(
+        `<svg`,
+        `<svg class="alert-icon-${meta.variant}"`,
+      )
+    }
+    tmpl += meta.title
+    tmpl += `</p>\n`
+    tmpl += text
+    tmpl += `</blockquote>\n`
+
+    return tmpl
+  }
+
+  return {
+    walkTokens(token) {
+      if (token.type !== `blockquote`)
+        return
+
+      const matchedVariant = resolvedVariants.find(({ type }) =>
+        new RegExp(createSyntaxPattern(type), `i`).test(token.text),
+      )
+
+      if (matchedVariant) {
+        const { type: variantType } = matchedVariant
+        const typeRegexp = new RegExp(createSyntaxPattern(variantType), `i`)
+
+        Object.assign(token, {
+          type: `alert`,
+          meta: buildMeta(variantType, matchedVariant),
+        })
+
+        const firstLine = token.tokens?.[0] as Tokens.Paragraph
+        const firstLineText = firstLine.raw?.replace(typeRegexp, ``).trim()
+
+        if (firstLineText) {
+          const patternToken = firstLine.tokens[0] as Tokens.Text
+
+          Object.assign(patternToken, {
+            raw: patternToken.raw.replace(typeRegexp, ``),
+            text: patternToken.text.replace(typeRegexp, ``),
+          })
+
+          if (firstLine.tokens[1]?.type === `br`) {
+            firstLine.tokens.splice(1, 1)
+          }
+        }
+        else {
+          token.tokens?.shift()
+        }
+      }
+    },
+    extensions: [
+      {
+        name: `alert`,
+        level: `block`,
+        renderer: renderAlert,
+      },
+      {
+        name: `alertContainer`,
+        level: `block`,
+        start(src) {
+          return src.match(/^:::/)?.index
+        },
+        tokenizer(src, _tokens) {
+          // eslint-disable-next-line regexp/no-super-linear-backtracking
+          const match = /^:::\s*(\w+)\s*\n([\s\S]*?)\n:::/.exec(src)
+
+          if (match) {
+            const [raw, variant, content] = match
+            const matchedVariant = resolvedVariants.find(v => v.type === variant)
+            if (!matchedVariant)
+              return
+
+            return {
+              type: `alert`,
+              raw,
+              text: content.trim(),
+              tokens: this.lexer.blockTokens(content.trim()),
+              meta: buildMeta(variant, matchedVariant, true),
+            }
+          }
+        },
+        renderer: renderAlert,
+      },
+    ],
+  }
+}
+
+/**
+ * The default configuration for alert variants.
+ */
+const defaultAlertVariant: AlertVariantItem[] = [
+  {
+    type: `note`,
+    icon: `<svg class="octicon octicon-info" style="margin-right: 0.25em;" viewBox="0 0 16 16" width="16" height="16" aria-hidden="true"><path d="M0 8a8 8 0 1 1 16 0A8 8 0 0 1 0 8Zm8-6.5a6.5 6.5 0 1 0 0 13 6.5 6.5 0 0 0 0-13ZM6.5 7.75A.75.75 0 0 1 7.25 7h1a.75.75 0 0 1 .75.75v2.75h.25a.75.75 0 0 1 0 1.5h-2a.75.75 0 0 1 0-1.5h.25v-2h-.25a.75.75 0 0 1-.75-.75ZM8 6a1 1 0 1 1 0-2 1 1 0 0 1 0 2Z"></path></svg>`,
+  },
+  {
+    type: `info`,
+    icon: `<svg class="octicon octicon-info" style="margin-right: 0.25em;" viewBox="0 0 16 16" width="16" height="16" aria-hidden="true"><path d="M0 8a8 8 0 1 1 16 0A8 8 0 0 1 0 8Zm8-6.5a6.5 6.5 0 1 0 0 13 6.5 6.5 0 0 0 0-13ZM6.5 7.75A.75.75 0 0 1 7.25 7h1a.75.75 0 0 1 .75.75v2.75h.25a.75.75 0 0 1 0 1.5h-2a.75.75 0 0 1 0-1.5h.25v-2h-.25a.75.75 0 0 1-.75-.75ZM8 6a1 1 0 1 1 0-2 1 1 0 0 1 0 2Z"></path></svg>`,
+  },
+  {
+    type: `tip`,
+    icon: `<svg class="octicon octicon-light-bulb" style="margin-right: 0.25em;" viewBox="0 0 16 16" width="16" height="16" aria-hidden="true"><path d="M8 1.5c-2.363 0-4 1.69-4 3.75 0 .984.424 1.625.984 2.304l.214.253c.223.264.47.556.673.848.284.411.537.896.621 1.49a.75.75 0 0 1-1.484.211c-.04-.282-.163-.547-.37-.847a8.456 8.456 0 0 0-.542-.68c-.084-.1-.173-.205-.268-.32C3.201 7.75 2.5 6.766 2.5 5.25 2.5 2.31 4.863 0 8 0s5.5 2.31 5.5 5.25c0 1.516-.701 2.5-1.328 3.259-.095.115-.184.22-.268.319-.207.245-.383.453-.541.681-.208.3-.33.565-.37.847a.751.751 0 0 1-1.485-.212c.084-.593.337-1.078.621-1.489.203-.292.45-.584.673-.848.075-.088.147-.173.213-.253.561-.679.985-1.32.985-2.304 0-2.06-1.637-3.75-4-3.75ZM5.75 12h4.5a.75.75 0 0 1 0 1.5h-4.5a.75.75 0 0 1 0-1.5ZM6 15.25a.75.75 0 0 1 .75-.75h2.5a.75.75 0 0 1 0 1.5h-2.5a.75.75 0 0 1-.75-.75Z"></path></svg>`,
+  },
+  {
+    type: `important`,
+    icon: `<svg class="octicon octicon-report" style="margin-right: 0.25em;" viewBox="0 0 16 16" width="16" height="16" aria-hidden="true"><path d="M0 1.75C0 .784.784 0 1.75 0h12.5C15.216 0 16 .784 16 1.75v9.5A1.75 1.75 0 0 1 14.25 13H8.06l-2.573 2.573A1.458 1.458 0 0 1 3 14.543V13H1.75A1.75 1.75 0 0 1 0 11.25Zm1.75-.25a.25.25 0 0 0-.25.25v9.5c0 .138.112.25.25.25h2a.75.75 0 0 1 .75.75v2.19l2.72-2.72a.749.749 0 0 1 .53-.22h6.5a.25.25 0 0 0 .25-.25v-9.5a.25.25 0 0 0-.25-.25Zm7 2.25v2.5a.75.75 0 0 1-1.5 0v-2.5a.75.75 0 0 1 1.5 0ZM9 9a1 1 0 1 1-2 0 1 1 0 0 1 2 0Z"></path></svg>`,
+  },
+  {
+    type: `warning`,
+    icon: `<svg class="octicon octicon-alert" style="margin-right: 0.25em;" viewBox="0 0 16 16" width="16" height="16" aria-hidden="true"><path d="M6.457 1.047c.659-1.234 2.427-1.234 3.086 0l6.082 11.378A1.75 1.75 0 0 1 14.082 15H1.918a1.75 1.75 0 0 1-1.543-2.575Zm1.763.707a.25.25 0 0 0-.44 0L1.698 13.132a.25.25 0 0 0 .22.368h12.164a.25.25 0 0 0 .22-.368Zm.53 3.996v2.5a.75.75 0 0 1-1.5 0v-2.5a.75.75 0 0 1 1.5 0ZM9 11a1 1 0 1 1-2 0 1 1 0 0 1 2 0Z"></path></svg>`,
+  },
+  {
+    type: `caution`,
+    icon: `<svg class="octicon octicon-stop" style="margin-right: 0.25em;" viewBox="0 0 16 16" width="16" height="16" aria-hidden="true"><path d="M4.47.22A.749.749 0 0 1 5 0h6c.199 0 .389.079.53.22l4.25 4.25c.141.14.22.331.22.53v6a.749.749 0 0 1-.22.53l-4.25 4.25A.749.749 0 0 1 11 16H5a.749.749 0 0 1-.53-.22L.22 11.53A.749.749 0 0 1 0 11V5c0-.199.079-.389.22-.53Zm.84 1.28L1.5 5.31v5.38l3.81 3.81h5.38l3.81-3.81V5.31L10.69 1.5ZM8 4a.75.75 0 0 1 .75.75v3.5a.75.75 0 0 1-1.5 0v-3.5A.75.75 0 0 1 8 4Zm0 8a1 1 0 1 1 0-2 1 1 0 0 1 0 2Z"></path></svg>`,
+  },
+  // Obsidian-style callouts
+  {
+    type: `abstract`,
+    title: `Abstract`,
+    icon: `<svg class="octicon octicon-clipboard" style="margin-right: 0.25em;" viewBox="0 0 16 16" width="16" height="16" aria-hidden="true"><path d="M5.75 1a.75.75 0 0 0-.75.75v.5c0 .414.336.75.75.75h4.5a.75.75 0 0 0 .75-.75v-.5a.75.75 0 0 0-.75-.75Zm4.5-1.5a2.25 2.25 0 0 1 2.122 1.5H13a2 2 0 0 1 2 2v10a2 2 0 0 1-2 2H3a2 2 0 0 1-2-2V3a2 2 0 0 1 2-2h.628A2.25 2.25 0 0 1 5.75-.5ZM3.5 3v10a.5.5 0 0 0 .5.5h8a.5.5 0 0 0 .5-.5V3a.5.5 0 0 0-.5-.5h-8a.5.5 0 0 0-.5.5Z"></path></svg>`,
+  },
+  {
+    type: `summary`,
+    title: `Summary`,
+    icon: `<svg class="octicon octicon-clipboard" style="margin-right: 0.25em;" viewBox="0 0 16 16" width="16" height="16" aria-hidden="true"><path d="M5.75 1a.75.75 0 0 0-.75.75v.5c0 .414.336.75.75.75h4.5a.75.75 0 0 0 .75-.75v-.5a.75.75 0 0 0-.75-.75Zm4.5-1.5a2.25 2.25 0 0 1 2.122 1.5H13a2 2 0 0 1 2 2v10a2 2 0 0 1-2 2H3a2 2 0 0 1-2-2V3a2 2 0 0 1 2-2h.628A2.25 2.25 0 0 1 5.75-.5ZM3.5 3v10a.5.5 0 0 0 .5.5h8a.5.5 0 0 0 .5-.5V3a.5.5 0 0 0-.5-.5h-8a.5.5 0 0 0-.5.5Z"></path></svg>`,
+  },
+  {
+    type: `tldr`,
+    title: `TL;DR`,
+    icon: `<svg class="octicon octicon-clipboard" style="margin-right: 0.25em;" viewBox="0 0 16 16" width="16" height="16" aria-hidden="true"><path d="M5.75 1a.75.75 0 0 0-.75.75v.5c0 .414.336.75.75.75h4.5a.75.75 0 0 0 .75-.75v-.5a.75.75 0 0 0-.75-.75Zm4.5-1.5a2.25 2.25 0 0 1 2.122 1.5H13a2 2 0 0 1 2 2v10a2 2 0 0 1-2 2H3a2 2 0 0 1-2-2V3a2 2 0 0 1 2-2h.628A2.25 2.25 0 0 1 5.75-.5ZM3.5 3v10a.5.5 0 0 0 .5.5h8a.5.5 0 0 0 .5-.5V3a.5.5 0 0 0-.5-.5h-8a.5.5 0 0 0-.5.5Z"></path></svg>`,
+  },
+  {
+    type: `todo`,
+    title: `Todo`,
+    icon: `<svg class="octicon octicon-checklist" style="margin-right: 0.25em;" viewBox="0 0 16 16" width="16" height="16" aria-hidden="true"><path d="M2.5 1.75v11.5c0 .138.112.25.25.25h3.17a.75.75 0 0 1 0 1.5H2.75A1.75 1.75 0 0 1 1 13.25V1.75C1 .784 1.784 0 2.75 0h8.5C12.216 0 13 .784 13 1.75v7.736a.75.75 0 0 1-1.5 0V1.75a.25.25 0 0 0-.25-.25h-8.5a.25.25 0 0 0-.25.25Zm10.97 8.72a.75.75 0 0 1 1.06 0l2 2a.75.75 0 0 1-1.06 1.06l-1.22-1.22v4.94a.75.75 0 0 1-1.5 0v-4.94l-1.22 1.22a.75.75 0 0 1-1.06-1.06Z"></path></svg>`,
+  },
+  {
+    type: `success`,
+    title: `Success`,
+    icon: `<svg class="octicon octicon-check-circle" style="margin-right: 0.25em;" viewBox="0 0 16 16" width="16" height="16" aria-hidden="true"><path d="M8 16A8 8 0 1 1 8 0a8 8 0 0 1 0 16Zm3.78-9.72a.751.751 0 0 0-.018-1.042.751.751 0 0 0-1.042-.018L6.75 9.19 5.28 7.72a.751.751 0 0 0-1.042.018.751.751 0 0 0-.018 1.042l2 2a.75.75 0 0 0 1.06 0Z"></path></svg>`,
+  },
+  {
+    type: `done`,
+    title: `Done`,
+    icon: `<svg class="octicon octicon-check-circle" style="margin-right: 0.25em;" viewBox="0 0 16 16" width="16" height="16" aria-hidden="true"><path d="M8 16A8 8 0 1 1 8 0a8 8 0 0 1 0 16Zm3.78-9.72a.751.751 0 0 0-.018-1.042.751.751 0 0 0-1.042-.018L6.75 9.19 5.28 7.72a.751.751 0 0 0-1.042.018.751.751 0 0 0-.018 1.042l2 2a.75.75 0 0 0 1.06 0Z"></path></svg>`,
+  },
+  {
+    type: `question`,
+    title: `Question`,
+    icon: `<svg class="octicon octicon-question" style="margin-right: 0.25em;" viewBox="0 0 16 16" width="16" height="16" aria-hidden="true"><path d="M0 8a8 8 0 1 1 16 0A8 8 0 0 1 0 8Zm8-6.5a6.5 6.5 0 1 0 0 13 6.5 6.5 0 0 0 0-13ZM6.92 6.085h.001a.749.749 0 1 1-1.342-.67c.169-.339.436-.701.849-.977C6.845 4.16 7.369 4 8 4a2.756 2.756 0 0 1 1.637.525c.503.377.863.965.863 1.725 0 .448-.115.83-.329 1.15-.205.307-.47.513-.692.662-.109.072-.22.138-.313.195l-.006.004a6.24 6.24 0 0 0-.26.16.952.952 0 0 0-.276.245.75.75 0 0 1-1.248-.832c.184-.264.42-.489.692-.661.103-.067.207-.132.313-.195l.007-.004c.1-.061.182-.11.258-.161a.969.969 0 0 0 .277-.245C8.96 6.514 9 6.427 9 6.25a.612.612 0 0 0-.262-.525A1.27 1.27 0 0 0 8 5.5c-.369 0-.595.09-.74.187a1.01 1.01 0 0 0-.34.398ZM9 11a1 1 0 1 1-2 0 1 1 0 0 1 2 0Z"></path></svg>`,
+  },
+  {
+    type: `help`,
+    title: `Help`,
+    icon: `<svg class="octicon octicon-question" style="margin-right: 0.25em;" viewBox="0 0 16 16" width="16" height="16" aria-hidden="true"><path d="M0 8a8 8 0 1 1 16 0A8 8 0 0 1 0 8Zm8-6.5a6.5 6.5 0 1 0 0 13 6.5 6.5 0 0 0 0-13ZM6.92 6.085h.001a.749.749 0 1 1-1.342-.67c.169-.339.436-.701.849-.977C6.845 4.16 7.369 4 8 4a2.756 2.756 0 0 1 1.637.525c.503.377.863.965.863 1.725 0 .448-.115.83-.329 1.15-.205.307-.47.513-.692.662-.109.072-.22.138-.313.195l-.006.004a6.24 6.24 0 0 0-.26.16.952.952 0 0 0-.276.245.75.75 0 0 1-1.248-.832c.184-.264.42-.489.692-.661.103-.067.207-.132.313-.195l.007-.004c.1-.061.182-.11.258-.161a.969.969 0 0 0 .277-.245C8.96 6.514 9 6.427 9 6.25a.612.612 0 0 0-.262-.525A1.27 1.27 0 0 0 8 5.5c-.369 0-.595.09-.74.187a1.01 1.01 0 0 0-.34.398ZM9 11a1 1 0 1 1-2 0 1 1 0 0 1 2 0Z"></path></svg>`,
+  },
+  {
+    type: `faq`,
+    title: `FAQ`,
+    icon: `<svg class="octicon octicon-question" style="margin-right: 0.25em;" viewBox="0 0 16 16" width="16" height="16" aria-hidden="true"><path d="M0 8a8 8 0 1 1 16 0A8 8 0 0 1 0 8Zm8-6.5a6.5 6.5 0 1 0 0 13 6.5 6.5 0 0 0 0-13ZM6.92 6.085h.001a.749.749 0 1 1-1.342-.67c.169-.339.436-.701.849-.977C6.845 4.16 7.369 4 8 4a2.756 2.756 0 0 1 1.637.525c.503.377.863.965.863 1.725 0 .448-.115.83-.329 1.15-.205.307-.47.513-.692.662-.109.072-.22.138-.313.195l-.006.004a6.24 6.24 0 0 0-.26.16.952.952 0 0 0-.276.245.75.75 0 0 1-1.248-.832c.184-.264.42-.489.692-.661.103-.067.207-.132.313-.195l.007-.004c.1-.061.182-.11.258-.161a.969.969 0 0 0 .277-.245C8.96 6.514 9 6.427 9 6.25a.612.612 0 0 0-.262-.525A1.27 1.27 0 0 0 8 5.5c-.369 0-.595.09-.74.187a1.01 1.01 0 0 0-.34.398ZM9 11a1 1 0 1 1-2 0 1 1 0 0 1 2 0Z"></path></svg>`,
+  },
+  {
+    type: `failure`,
+    title: `Failure`,
+    icon: `<svg class="octicon octicon-x-circle" style="margin-right: 0.25em;" viewBox="0 0 16 16" width="16" height="16" aria-hidden="true"><path d="M2.343 13.657A8 8 0 1 1 13.658 2.343 8 8 0 0 1 2.343 13.657ZM6.03 4.97a.751.751 0 0 0-1.042.018.751.751 0 0 0-.018 1.042L6.94 8 4.97 9.97a.749.749 0 0 0 .326 1.275.749.749 0 0 0 .734-.215L8 9.06l1.97 1.97a.749.749 0 0 0 1.275-.326.749.749 0 0 0-.215-.734L9.06 8l1.97-1.97a.749.749 0 0 0-.326-1.275.749.749 0 0 0-.734.215L8 6.94Z"></path></svg>`,
+  },
+  {
+    type: `fail`,
+    title: `Fail`,
+    icon: `<svg class="octicon octicon-x-circle" style="margin-right: 0.25em;" viewBox="0 0 16 16" width="16" height="16" aria-hidden="true"><path d="M2.343 13.657A8 8 0 1 1 13.658 2.343 8 8 0 0 1 2.343 13.657ZM6.03 4.97a.751.751 0 0 0-1.042.018.751.751 0 0 0-.018 1.042L6.94 8 4.97 9.97a.749.749 0 0 0 .326 1.275.749.749 0 0 0 .734-.215L8 9.06l1.97 1.97a.749.749 0 0 0 1.275-.326.749.749 0 0 0-.215-.734L9.06 8l1.97-1.97a.749.749 0 0 0-.326-1.275.749.749 0 0 0-.734.215L8 6.94Z"></path></svg>`,
+  },
+  {
+    type: `missing`,
+    title: `Missing`,
+    icon: `<svg class="octicon octicon-x-circle" style="margin-right: 0.25em;" viewBox="0 0 16 16" width="16" height="16" aria-hidden="true"><path d="M2.343 13.657A8 8 0 1 1 13.658 2.343 8 8 0 0 1 2.343 13.657ZM6.03 4.97a.751.751 0 0 0-1.042.018.751.751 0 0 0-.018 1.042L6.94 8 4.97 9.97a.749.749 0 0 0 .326 1.275.749.749 0 0 0 .734-.215L8 9.06l1.97 1.97a.749.749 0 0 0 1.275-.326.749.749 0 0 0-.215-.734L9.06 8l1.97-1.97a.749.749 0 0 0-.326-1.275.749.749 0 0 0-.734.215L8 6.94Z"></path></svg>`,
+  },
+  {
+    type: `danger`,
+    title: `Danger`,
+    icon: `<svg class="octicon octicon-zap" style="margin-right: 0.25em;" viewBox="0 0 16 16" width="16" height="16" aria-hidden="true"><path d="M9.504.43a1.516 1.516 0 0 1 2.437 1.713L10.415 5.5h2.123c1.57 0 2.346 1.909 1.22 3.004l-7.34 7.142a1.249 1.249 0 0 1-.871.354h-.302a1.25 1.25 0 0 1-1.157-1.723L5.633 10.5H3.462c-1.57 0-2.346-1.909-1.22-3.004ZM9.98 1.873a.016.016 0 0 0-.016.006L2.252 9.021a.75.75 0 0 0 .488 1.212h3.838a.75.75 0 0 1 .694 1.034L5.545 15.02a.016.016 0 0 0 .003.017.017.017 0 0 0 .018.004h.302a.016.016 0 0 0 .012-.005l7.34-7.142a.75.75 0 0 0-.488-1.212h-3.838a.75.75 0 0 1-.694-1.034l1.527-3.628a.016.016 0 0 0-.003-.017.017.017 0 0 0-.018-.004h-.302Z"></path></svg>`,
+  },
+  {
+    type: `error`,
+    title: `Error`,
+    icon: `<svg class="octicon octicon-zap" style="margin-right: 0.25em;" viewBox="0 0 16 16" width="16" height="16" aria-hidden="true"><path d="M9.504.43a1.516 1.516 0 0 1 2.437 1.713L10.415 5.5h2.123c1.57 0 2.346 1.909 1.22 3.004l-7.34 7.142a1.249 1.249 0 0 1-.871.354h-.302a1.25 1.25 0 0 1-1.157-1.723L5.633 10.5H3.462c-1.57 0-2.346-1.909-1.22-3.004ZM9.98 1.873a.016.016 0 0 0-.016.006L2.252 9.021a.75.75 0 0 0 .488 1.212h3.838a.75.75 0 0 1 .694 1.034L5.545 15.02a.016.016 0 0 0 .003.017.017.017 0 0 0 .018.004h.302a.016.016 0 0 0 .012-.005l7.34-7.142a.75.75 0 0 0-.488-1.212h-3.838a.75.75 0 0 1-.694-1.034l1.527-3.628a.016.016 0 0 0-.003-.017.017.017 0 0 0-.018-.004h-.302Z"></path></svg>`,
+  },
+  {
+    type: `bug`,
+    title: `Bug`,
+    icon: `<svg class="octicon octicon-bug" style="margin-right: 0.25em;" viewBox="0 0 16 16" width="16" height="16" aria-hidden="true"><path d="M4.72.22a.75.75 0 0 1 1.06 0l1 .999a3.488 3.488 0 0 1 2.441 0l.999-1a.748.748 0 0 1 1.265.332.75.75 0 0 1-.205.729l-.775.776c.616.63.995 1.493.995 2.444v.327c0 .1-.009.197-.025.292l.727.726a.75.75 0 1 1-1.06 1.06l-.727-.727a2.17 2.17 0 0 1-.292.026H9.25V7.5a.75.75 0 0 1-1.5 0V6.125H6.875a2.17 2.17 0 0 1-.292-.026l-.727.727a.75.75 0 1 1-1.06-1.06l.727-.726a2.17 2.17 0 0 1-.025-.292V4.5c0-.951.379-1.814.995-2.444l-.775-.776a.75.75 0 0 1 0-1.06Zm6.437 6.003A.608.608 0 0 0 11 6.072v-.026a3.999 3.999 0 0 0-.11-.936 2.488 2.488 0 0 0-5.78 0 3.992 3.992 0 0 0-.11.936v.026c0 .05.008.098.02.147h4.937a.612.612 0 0 0 .2-.02ZM2.25 7.5a.75.75 0 0 0 0 1.5h.5v1.25a4.75 4.75 0 0 0 2.478 4.166l.247.137a.75.75 0 1 0 .722-1.313l-.246-.137A3.25 3.25 0 0 1 4.25 10.25V9h7.5v1.25a3.25 3.25 0 0 1-1.701 2.853l-.246.137a.75.75 0 1 0 .722 1.313l.247-.137A4.75 4.75 0 0 0 13.25 10.25V9h.5a.75.75 0 0 0 0-1.5Z"></path></svg>`,
+  },
+  {
+    type: `example`,
+    title: `Example`,
+    icon: `<svg class="octicon octicon-list-unordered" style="margin-right: 0.25em;" viewBox="0 0 16 16" width="16" height="16" aria-hidden="true"><path d="M5.75 2.5h8.5a.75.75 0 0 1 0 1.5h-8.5a.75.75 0 0 1 0-1.5Zm0 5h8.5a.75.75 0 0 1 0 1.5h-8.5a.75.75 0 0 1 0-1.5Zm0 5h8.5a.75.75 0 0 1 0 1.5h-8.5a.75.75 0 0 1 0-1.5ZM2 14a1 1 0 1 1 0-2 1 1 0 0 1 0 2Zm1-6a1 1 0 1 1-2 0 1 1 0 0 1 2 0ZM2 4a1 1 0 1 1 0-2 1 1 0 0 1 0 2Z"></path></svg>`,
+  },
+  {
+    type: `quote`,
+    title: `Quote`,
+    icon: `<svg class="octicon octicon-quote" style="margin-right: 0.25em;" viewBox="0 0 16 16" width="16" height="16" aria-hidden="true"><path d="M1.75 2h12.5c.966 0 1.75.784 1.75 1.75v8.5A1.75 1.75 0 0 1 14.25 14H1.75A1.75 1.75 0 0 1 0 12.25v-8.5C0 2.784.784 2 1.75 2ZM1.5 12.25c0 .138.112.25.25.25h12.5a.25.25 0 0 0 .25-.25v-8.5a.25.25 0 0 0-.25-.25H1.75a.25.25 0 0 0-.25.25ZM4 5.25a.75.75 0 0 1 .75-.75h6.5a.75.75 0 0 1 0 1.5h-6.5A.75.75 0 0 1 4 5.25Zm0 4a.75.75 0 0 1 .75-.75h6.5a.75.75 0 0 1 0 1.5h-6.5a.75.75 0 0 1-.75-.75Z"></path></svg>`,
+  },
+  {
+    type: `cite`,
+    title: `Cite`,
+    icon: `<svg class="octicon octicon-quote" style="margin-right: 0.25em;" viewBox="0 0 16 16" width="16" height="16" aria-hidden="true"><path d="M1.75 2h12.5c.966 0 1.75.784 1.75 1.75v8.5A1.75 1.75 0 0 1 14.25 14H1.75A1.75 1.75 0 0 1 0 12.25v-8.5C0 2.784.784 2 1.75 2ZM1.5 12.25c0 .138.112.25.25.25h12.5a.25.25 0 0 0 .25-.25v-8.5a.25.25 0 0 0-.25-.25H1.75a.25.25 0 0 0-.25.25ZM4 5.25a.75.75 0 0 1 .75-.75h6.5a.75.75 0 0 1 0 1.5h-6.5A.75.75 0 0 1 4 5.25Zm0 4a.75.75 0 0 1 .75-.75h6.5a.75.75 0 0 1 0 1.5h-6.5a.75.75 0 0 1-.75-.75Z"></path></svg>`,
+  },
+]
+
+/**
+ * Resolves the variants configuration, combining the provided variants with
+ * the default variants.
+ */
+export function resolveVariants(variants: AlertVariantItem[]) {
+  if (!variants.length)
+    return defaultAlertVariant
+
+  return Object.values(
+    [...defaultAlertVariant, ...variants].reduce(
+      (map, item) => {
+        map[item.type] = item
+        return map
+      },
+      {} as { [key: string]: AlertVariantItem },
+    ),
+  )
+}
+
+/**
+ * Returns regex pattern to match alert syntax.
+ */
+export function createSyntaxPattern(type: string) {
+  return `^(?:\\[!${type}])\\s*?\n*`
+}
@@ -0,0 +1,89 @@
+import type { MarkedExtension, Tokens } from 'marked'
+/**
+ * A marked extension to support footnotes syntax.
+ * Syntax:
+ *  This is a footnote reference[^1][^2].
+ *
+ *  [^1]: .....
+ *  [^2]: .....
+ */
+
+interface MapContent {
+  index: number
+  text: string
+}
+const fnMap = new Map<string, MapContent>()
+
+export function markedFootnotes(): MarkedExtension {
+  return {
+    extensions: [
+      {
+        name: `footnoteDef`,
+        level: `block`,
+        start(src: string) {
+          fnMap.clear()
+          return src.match(/^\[\^/)?.index
+        },
+        tokenizer(src: string) {
+          const match = src.match(/^\[\^(.*)\]:(.*)/)
+          if (match) {
+            const [raw, fnId, text] = match
+            const index = fnMap.size + 1
+            fnMap.set(fnId, { index, text })
+            return {
+              type: `footnoteDef`,
+              raw,
+              fnId,
+              index,
+              text,
+            }
+          }
+          return undefined
+        },
+        renderer(token: Tokens.Generic) {
+          const { index, text, fnId } = token
+          const fnInner = `
+                <code>${index}.</code> 
+                <span>${text}</span> 
+                    <a id="fnDef-${fnId}" href="#fnRef-${fnId}" style="color: var(--md-primary-color);">\u21A9\uFE0E</a>
+                <br>`
+          if (index === 1) {
+            return `
+            <p style="font-size: 80%;margin: 0.5em 8px;word-break:break-all;">${fnInner}`
+          }
+          if (index === fnMap.size) {
+            return `${fnInner}</p>`
+          }
+          return fnInner
+        },
+      },
+      {
+        name: `footnoteRef`,
+        level: `inline`,
+        start(src: string) {
+          return src.match(/\[\^/)?.index
+        },
+        tokenizer(src: string) {
+          const match = src.match(/^\[\^(.*?)\]/)
+          if (match) {
+            const [raw, fnId] = match
+            if (fnMap.has(fnId)) {
+              return {
+                type: `footnoteRef`,
+                raw,
+                fnId,
+              }
+            }
+          }
+        },
+        renderer(token: Tokens.Generic) {
+          const { fnId } = token
+          const { index } = fnMap.get(fnId) as MapContent
+          return `<sup style="color: var(--md-primary-color);">
+                    <a href="#fnDef-${fnId}" id="fnRef-${fnId}">\[${index}\]</a>
+                </sup>`
+        },
+      },
+    ],
+  }
+}
@@ -0,0 +1,10 @@
+// Markdown 扩展导出
+export * from './alert.js'
+export * from './footnotes.js'
+export * from './infographic.js'
+export * from './katex.js'
+export * from './markup.js'
+export * from './plantuml.js'
+export * from './ruby.js'
+export * from './slider.js'
+export * from './toc.js'
@@ -0,0 +1,119 @@
+import type { MarkedExtension } from 'marked'
+
+interface InfographicOptions {
+  themeMode?: 'dark' | 'light'
+}
+
+async function renderInfographic(containerId: string, code: string, options?: InfographicOptions) {
+  if (typeof window === 'undefined')
+    return
+
+  try {
+    const { Infographic, setDefaultFont, setFontExtendFactor, exportToSVG } = await import('@antv/infographic')
+
+    setFontExtendFactor(1.1)
+    setDefaultFont('-apple-system-font, "system-ui", "Helvetica Neue", "PingFang SC", "Hiragino Sans GB", "Microsoft YaHei UI", "Microsoft YaHei", Arial, sans-serif')
+
+    const findContainer = (retries = 5, delay = 100) => {
+      const container = document.getElementById(containerId)
+      if (container) {
+        const isDark = options?.themeMode === 'dark'
+
+        // 从 CSS 变量中读取主题颜色
+        const root = document.documentElement
+        const computedStyle = getComputedStyle(root)
+        const primaryColor = computedStyle.getPropertyValue('--md-primary-color').trim()
+        const backgroundColor = computedStyle.getPropertyValue('--background').trim()
+
+        // 转换 HSL 格式
+        const toHSLString = (variant: string) => {
+          const vars = variant.split(' ')
+          if (vars.length === 3)
+            return `hsl(${vars.join(', ')})`
+          if (vars.length === 4)
+            return `hsla(${vars.join(', ')})`
+          return ''
+        }
+
+        const instance = new Infographic({
+          container,
+          svg: {
+            style: {
+              width: '100%',
+              height: '100%',
+              background: isDark ? '#000' : 'transparent',
+            },
+            background: false,
+          },
+          theme: isDark ? 'dark' : 'default',
+          themeConfig: {
+            colorPrimary: primaryColor || undefined,
+            colorBg: toHSLString(backgroundColor) || undefined,
+          },
+        })
+
+        instance.on('loaded', ({ node }) => {
+          exportToSVG(node, { removeIds: true }).then((svg) => {
+            container.replaceChildren(svg)
+          })
+        })
+
+        instance.render(code)
+
+        return
+      }
+
+      if (retries > 0) {
+        setTimeout(() => findContainer(retries - 1, delay), delay)
+      }
+    }
+
+    findContainer()
+  }
+  catch (error) {
+    console.error('Failed to render Infographic:', error)
+    const container = document.getElementById(containerId)
+    if (container) {
+      container.innerHTML = `<div style="color: red; padding: 10px; border: 1px solid red;">Infographic 渲染失败: ${error instanceof Error ? error.message : String(error)}</div>`
+    }
+  }
+}
+
+export function markedInfographic(options?: InfographicOptions): MarkedExtension {
+  const className = 'infographic-diagram'
+
+  return {
+    extensions: [
+      {
+        name: 'infographic',
+        level: 'block',
+        start(src: string) {
+          return src.match(/^```infographic/m)?.index
+        },
+        tokenizer(src: string) {
+          const match = /^```infographic\r?\n([\s\S]*?)\r?\n```/.exec(src)
+          if (match) {
+            return {
+              type: 'infographic',
+              raw: match[0],
+              text: match[1].trim(),
+            }
+          }
+        },
+        renderer(token: any) {
+          const id = `infographic-${Math.random().toString(36).slice(2, 11)}`
+          const code = token.text
+
+          renderInfographic(id, code, options)
+
+          return `<div id="${id}" class="${className}" style="width: 100%;">正在加载 Infographic...</div>`
+        },
+      },
+    ],
+    walkTokens(token: any) {
+      if (token.type === 'code' && token.lang === 'infographic') {
+        token.type = 'infographic'
+      }
+    },
+  }
+}
@@ -0,0 +1,162 @@
+import type { MarkedExtension } from 'marked'
+
+export interface MarkedKatexOptions {
+  nonStandard?: boolean
+}
+
+const inlineRule = /^(\${1,2})(?!\$)((?:\\.|[^\\\n])*?(?:\\.|[^\\\n$]))\1(?=[\s?!.,:？！。，：]|$)/
+const inlineRuleNonStandard = /^(\${1,2})(?!\$)((?:\\.|[^\\\n])*?(?:\\.|[^\\\n$]))\1/ // Non-standard, even if there are no spaces before and after $ or $$, try to parse
+
+const blockRule = /^\s{0,3}(\${1,2})[ \t]*\n([\s\S]+?)\n\s{0,3}\1[ \t]*(?:\n|$)/
+
+// LaTeX style rules for \( ... \) and \[ ... \]
+const inlineLatexRule = /^\\\(([^\\]*(?:\\.[^\\]*)*?)\\\)/
+const blockLatexRule = /^\\\[([^\\]*(?:\\.[^\\]*)*?)\\\]/
+
+function createRenderer(display: boolean, withStyle: boolean = true) {
+  return (token: any) => {
+    // @ts-expect-error MathJax is a global variable
+    window.MathJax.texReset()
+    // @ts-expect-error MathJax is a global variable
+    const mjxContainer = window.MathJax.tex2svg(token.text, { display })
+    const svg = mjxContainer.firstChild
+    const width = svg.style[`min-width`] || svg.getAttribute(`width`)
+    svg.removeAttribute(`width`)
+
+    // 行内公式对齐 https://groups.google.com/g/mathjax-users/c/zThKffrrCvE?pli=1
+    // 直接覆盖 style 会覆盖 MathJax 的样式，需要手动设置
+    // svg.style = `max-width: 300vw !important; display: initial; flex-shrink: 0;`
+
+    if (withStyle) {
+      svg.style.display = `initial`
+      svg.style.setProperty(`max-width`, `300vw`, `important`)
+      svg.style.flexShrink = `0`
+      svg.style.width = width
+    }
+
+    if (!display) {
+      // 新主题系统：使用 class 而非内联样式
+      return `<span class="katex-inline">${svg.outerHTML}</span>`
+    }
+
+    return `<section class="katex-block">${svg.outerHTML}</section>`
+  }
+}
+
+function inlineKatex(options: MarkedKatexOptions | undefined, renderer: any) {
+  const nonStandard = options && options.nonStandard
+  const ruleReg = nonStandard ? inlineRuleNonStandard : inlineRule
+  return {
+    name: `inlineKatex`,
+    level: `inline`,
+    start(src: string) {
+      let index
+      let indexSrc = src
+
+      while (indexSrc) {
+        index = indexSrc.indexOf(`$`)
+        if (index === -1) {
+          return
+        }
+        const f = nonStandard ? index > -1 : index === 0 || indexSrc.charAt(index - 1) === ` `
+        if (f) {
+          const possibleKatex = indexSrc.substring(index)
+
+          if (possibleKatex.match(ruleReg)) {
+            return index
+          }
+        }
+
+        indexSrc = indexSrc.substring(index + 1).replace(/^\$+/, ``)
+      }
+    },
+    tokenizer(src: string) {
+      const match = src.match(ruleReg)
+      if (match) {
+        return {
+          type: `inlineKatex`,
+          raw: match[0],
+          text: match[2].trim(),
+          displayMode: match[1].length === 2,
+        }
+      }
+    },
+    renderer,
+  }
+}
+
+function blockKatex(_options: MarkedKatexOptions | undefined, renderer: any) {
+  return {
+    name: `blockKatex`,
+    level: `block`,
+    tokenizer(src: string) {
+      const match = src.match(blockRule)
+      if (match) {
+        return {
+          type: `blockKatex`,
+          raw: match[0],
+          text: match[2].trim(),
+          displayMode: match[1].length === 2,
+        }
+      }
+    },
+    renderer,
+  }
+}
+
+function inlineLatexKatex(_options: MarkedKatexOptions | undefined, renderer: any) {
+  return {
+    name: `inlineLatexKatex`,
+    level: `inline`,
+    start(src: string) {
+      const index = src.indexOf(`\\(`)
+      return index !== -1 ? index : undefined
+    },
+    tokenizer(src: string) {
+      const match = src.match(inlineLatexRule)
+      if (match) {
+        return {
+          type: `inlineLatexKatex`,
+          raw: match[0],
+          text: match[1].trim(),
+          displayMode: false,
+        }
+      }
+    },
+    renderer,
+  }
+}
+
+function blockLatexKatex(_options: MarkedKatexOptions | undefined, renderer: any) {
+  return {
+    name: `blockLatexKatex`,
+    level: `block`,
+    start(src: string) {
+      const index = src.indexOf(`\\[`)
+      return index !== -1 ? index : undefined
+    },
+    tokenizer(src: string) {
+      const match = src.match(blockLatexRule)
+      if (match) {
+        return {
+          type: `blockLatexKatex`,
+          raw: match[0],
+          text: match[1].trim(),
+          displayMode: true,
+        }
+      }
+    },
+    renderer,
+  }
+}
+
+export function MDKatex(options: MarkedKatexOptions | undefined, withStyle: boolean = true): MarkedExtension {
+  return {
+    extensions: [
+      inlineKatex(options, createRenderer(false, withStyle)),
+      blockKatex(options, createRenderer(true, withStyle)),
+      inlineLatexKatex(options, createRenderer(false, withStyle)),
+      blockLatexKatex(options, createRenderer(true, withStyle)),
+    ],
+  }
+}
@@ -0,0 +1,87 @@
+import type { MarkedExtension } from 'marked'
+
+/**
+ * 扩展标记语法：
+ * - 高亮: ==文本==
+ * - 下划线: ++文本++
+ * - 波浪线: ~文本~
+ */
+export function markedMarkup(): MarkedExtension {
+  return {
+    extensions: [
+      // 高亮语法 ==文本==
+      {
+        name: `markup_highlight`,
+        level: `inline`,
+        start(src: string) {
+          return src.match(/==(?!=)/)?.index
+        },
+        tokenizer(src: string) {
+          const rule = /^==((?:[^=]|=(?!=))+)==/
+          const match = rule.exec(src)
+          if (match) {
+            return {
+              type: `markup_highlight`,
+              raw: match[0],
+              text: match[1],
+            }
+          }
+        },
+        renderer(token: any) {
+          // 新主题系统：使用 class 而非内联样式
+          return `<span class="markup-highlight">${token.text}</span>`
+        },
+      },
+
+      // 下划线语法 ++文本++
+      {
+        name: `markup_underline`,
+        level: `inline`,
+        start(src: string) {
+          return src.match(/\+\+(?!\+)/)?.index
+        },
+        tokenizer(src: string) {
+          const rule = /^\+\+((?:[^+]|\+(?!\+))+)\+\+/
+          const match = rule.exec(src)
+          if (match) {
+            return {
+              type: `markup_underline`,
+              raw: match[0],
+              text: match[1],
+            }
+          }
+        },
+        renderer(token: any) {
+          // 新主题系统：使用 class 而非内联样式
+          return `<span class="markup-underline">${token.text}</span>`
+        },
+      },
+
+      // 波浪线语法 ~文本~
+      {
+        name: `markup_wavyline`,
+        level: `inline`,
+        start(src: string) {
+          // 查找单个 ~ 但不是连续的 ~~
+          return src.match(/~(?!~)/)?.index
+        },
+        tokenizer(src: string) {
+          // 匹配 ~文本~ 但确保不是 ~~文本~~
+          const rule = /^~([^~\n]+)~(?!~)/
+          const match = rule.exec(src)
+          if (match) {
+            return {
+              type: `markup_wavyline`,
+              raw: match[0],
+              text: match[1],
+            }
+          }
+        },
+        renderer(token: any) {
+          // 新主题系统：使用 class 而非内联样式
+          return `<span class="markup-wavyline">${token.text}</span>`
+        },
+      },
+    ],
+  }
+}
@@ -0,0 +1,289 @@
+import type { MarkedExtension, Tokens } from 'marked'
+import { deflateSync } from 'fflate'
+
+export interface PlantUMLOptions {
+  /**
+   * PlantUML 服务器地址
+   * @default 'https://www.plantuml.com/plantuml'
+   */
+  serverUrl?: string
+  /**
+   * 渲染格式
+   * @default 'svg'
+   */
+  format?: `svg` | `png`
+  /**
+   * CSS 类名
+   * @default 'plantuml-diagram'
+   */
+  className?: string
+  /**
+   * 是否内嵌SVG内容（用于微信公众号等不支持外链图片的环境）
+   * @default false
+   */
+  inlineSvg?: boolean
+  /**
+   * 自定义样式
+   */
+  styles?: {
+    container?: Record<string, string | number>
+  }
+}
+
+/**
+ * PlantUML 专用的 6-bit 编码函数
+ * 基于官方文档 https://plantuml.com/text-encoding
+ */
+function encode6bit(b: number): string {
+  if (b < 10) {
+    return String.fromCharCode(48 + b)
+  }
+  b -= 10
+  if (b < 26) {
+    return String.fromCharCode(65 + b)
+  }
+  b -= 26
+  if (b < 26) {
+    return String.fromCharCode(97 + b)
+  }
+  b -= 26
+  if (b === 0) {
+    return `-`
+  }
+  if (b === 1) {
+    return `_`
+  }
+  return `?`
+}
+
+/**
+ * 将 3 个字节附加到编码字符串中
+ * 基于官方文档 https://plantuml.com/text-encoding
+ */
+function append3bytes(b1: number, b2: number, b3: number): string {
+  const c1 = b1 >> 2
+  const c2 = ((b1 & 0x3) << 4) | (b2 >> 4)
+  const c3 = ((b2 & 0xF) << 2) | (b3 >> 6)
+  const c4 = b3 & 0x3F
+  let r = ``
+  r += encode6bit(c1 & 0x3F)
+  r += encode6bit(c2 & 0x3F)
+  r += encode6bit(c3 & 0x3F)
+  r += encode6bit(c4 & 0x3F)
+  return r
+}
+
+/**
+ * PlantUML 专用的 base64 编码函数
+ * 基于官方文档 https://plantuml.com/text-encoding
+ */
+function encode64(data: string): string {
+  let r = ``
+  for (let i = 0; i < data.length; i += 3) {
+    if (i + 2 === data.length) {
+      r += append3bytes(data.charCodeAt(i), data.charCodeAt(i + 1), 0)
+    }
+    else if (i + 1 === data.length) {
+      r += append3bytes(data.charCodeAt(i), 0, 0)
+    }
+    else {
+      r += append3bytes(data.charCodeAt(i), data.charCodeAt(i + 1), data.charCodeAt(i + 2))
+    }
+  }
+  return r
+}
+
+/**
+ * 使用 fflate 库进行 Deflate 压缩
+ * 按照官方规范进行压缩
+ */
+function performDeflate(input: string): string {
+  try {
+    // 将字符串转换为字节数组
+    const inputBytes = new TextEncoder().encode(input)
+
+    // 使用 fflate 进行 deflate 压缩（最高压缩级别 9）
+    const compressed = deflateSync(inputBytes, { level: 9 })
+
+    // 将压缩后的字节数组转换为二进制字符串
+    return String.fromCharCode(...compressed)
+  }
+  catch (error) {
+    console.warn(`Deflate compression failed:`, error)
+    // 如果压缩失败，返回原始输入
+    return input
+  }
+}
+
+/**
+ * 编码 PlantUML 代码为服务器可识别的格式
+ * 按照官方规范：UTF-8 编码 -> Deflate 压缩 -> PlantUML Base64 编码
+ */
+function encodePlantUML(plantumlCode: string): string {
+  try {
+    // 步骤 1 & 2: UTF-8 编码 + Deflate 压缩
+    const deflated = performDeflate(plantumlCode)
+
+    // 步骤 3: PlantUML 专用的 base64 编码
+    return encode64(deflated)
+  }
+  catch (error) {
+    // 如果编码失败，回退到简单方案
+    console.warn(`PlantUML encoding failed, using fallback:`, error)
+    const utf8Bytes = new TextEncoder().encode(plantumlCode)
+    const base64 = btoa(String.fromCharCode(...utf8Bytes))
+    return `~1${base64.replace(/\+/g, `-`).replace(/\//g, `_`).replace(/=/g, ``)}`
+  }
+}
+
+/**
+ * 生成 PlantUML 图片 URL
+ */
+function generatePlantUMLUrl(code: string, options: Required<PlantUMLOptions>): string {
+  const encoded = encodePlantUML(code)
+  const formatPath = options.format === `svg` ? `svg` : `png`
+  return `${options.serverUrl}/${formatPath}/${encoded}`
+}
+
+/**
+ * 渲染 PlantUML 图表
+ */
+function renderPlantUMLDiagram(token: Tokens.Code, options: Required<PlantUMLOptions>): string {
+  const { text: code } = token
+
+  // 检查代码是否包含 PlantUML 标记
+  const finalCode = (!code.trim().includes(`@start`) || !code.trim().includes(`@end`))
+    ? `@startuml\n${code.trim()}\n@enduml`
+    : code
+
+  const imageUrl = generatePlantUMLUrl(finalCode, options)
+
+  // 如果启用了内嵌SVG且格式是SVG
+  if (options.inlineSvg && options.format === `svg`) {
+    // 由于marked是同步的，我们需要返回一个占位符，然后异步替换
+    const placeholder = `plantuml-placeholder-${Math.random().toString(36).slice(2, 11)}`
+
+    // 异步获取SVG内容并替换
+    fetchSvgContent(imageUrl).then((svgContent) => {
+      const placeholderElement = document.querySelector(`[data-placeholder="${placeholder}"]`)
+      if (placeholderElement) {
+        placeholderElement.outerHTML = createPlantUMLHTML(imageUrl, options, svgContent)
+      }
+    })
+
+    const containerStyles = options.styles.container
+      ? Object.entries(options.styles.container)
+          .map(([key, value]) => `${key.replace(/([A-Z])/g, `-$1`).toLowerCase()}: ${value}`)
+          .join(`; `)
+      : ``
+
+    return `<div class="${options.className}" style="${containerStyles}" data-placeholder="${placeholder}">
+      <div style="color: #666; font-style: italic;">正在加载PlantUML图表...</div>
+    </div>`
+  }
+
+  return createPlantUMLHTML(imageUrl, options)
+}
+
+/**
+ * 获取SVG内容
+ */
+async function fetchSvgContent(svgUrl: string): Promise<string> {
+  try {
+    const response = await fetch(svgUrl)
+    if (!response.ok) {
+      throw new Error(`HTTP ${response.status}`)
+    }
+    const svgContent = await response.text()
+    // 移除SVG根元素的固定尺寸，使其响应式
+    return svgContent
+      // 移除width和height属性
+      .replace(/(<svg[^>]*)\swidth="[^"]*"/g, `$1`)
+      .replace(/(<svg[^>]*)\sheight="[^"]*"/g, `$1`)
+      // 移除style中的width和height
+      .replace(/(<svg[^>]*style="[^"]*?)width:[^;]*;?/g, `$1`)
+      .replace(/(<svg[^>]*style="[^"]*?)height:[^;]*;?/g, `$1`)
+  }
+  catch (error) {
+    console.warn(`Failed to fetch SVG content from ${svgUrl}:`, error)
+    return `<div style="color: #666; font-style: italic;">PlantUML图表加载失败</div>`
+  }
+}
+
+/**
+ * 创建 PlantUML HTML 元素
+ */
+function createPlantUMLHTML(imageUrl: string, options: Required<PlantUMLOptions>, svgContent?: string): string {
+  const containerStyles = options.styles.container
+    ? Object.entries(options.styles.container)
+        .map(([key, value]) => `${key.replace(/([A-Z])/g, `-$1`).toLowerCase()}: ${value}`)
+        .join(`; `)
+    : ``
+
+  // 如果有SVG内容，直接嵌入
+  if (svgContent) {
+    return `<div class="${options.className}" style="${containerStyles}">
+      ${svgContent}
+    </div>`
+  }
+
+  // 否则使用图片链接
+  return `<div class="${options.className}" style="${containerStyles}">
+    <img src="${imageUrl}" alt="PlantUML Diagram" style="max-width: 100%; height: auto;" />
+  </div>`
+}
+
+/**
+ * PlantUML marked 扩展
+ */
+export function markedPlantUML(options: PlantUMLOptions = {}): MarkedExtension {
+  const resolvedOptions: Required<PlantUMLOptions> = {
+    serverUrl: options.serverUrl || `https://www.plantuml.com/plantuml`,
+    format: options.format || `svg`,
+    className: options.className || `plantuml-diagram`,
+    inlineSvg: options.inlineSvg || false,
+    styles: {
+      container: {
+        textAlign: `center`,
+        margin: `16px 8px`,
+        overflowX: `auto`,
+        ...options.styles?.container,
+      },
+    },
+  }
+
+  return {
+    extensions: [
+      {
+        name: `plantuml`,
+        level: `block`,
+        start(src: string) {
+          // 匹配 ```plantuml 代码块
+          return src.match(/^```plantuml/m)?.index
+        },
+        tokenizer(src: string) {
+          // 匹配完整的 plantuml 代码块
+          const match = /^```plantuml\r?\n([\s\S]*?)\r?\n```/.exec(src)
+
+          if (match) {
+            const [raw, code] = match
+            return {
+              type: `plantuml`,
+              raw,
+              text: code.trim(),
+            }
+          }
+        },
+        renderer(token: any) {
+          return renderPlantUMLDiagram(token, resolvedOptions)
+        },
+      },
+    ],
+    walkTokens(token: any) {
+      // 处理现有的代码块，如果语言是 plantuml 就转换类型
+      if (token.type === `code` && token.lang === `plantuml`) {
+        token.type = `plantuml`
+      }
+    },
+  }
+}
@@ -0,0 +1,125 @@
+import type { MarkedExtension } from 'marked'
+
+/**
+ * 注音/拼音标注扩展
+ * https://talk.commonmark.org/t/proper-ruby-text-rb-syntax-support-in-markdown/2279
+ * https://www.w3.org/TR/ruby/
+ *
+ * 支持的格式：
+ * 1. [文字]{注音}
+ * 2. [文字]^(注音)
+ *
+ * 分隔符：
+ * - `・` (中点)
+ * - `．` (全角句点)
+ * - `。` (中文句号)
+ * - `-` (英文减号)
+ */
+export function markedRuby(): MarkedExtension {
+  return {
+    extensions: [
+      {
+        name: `ruby`,
+        level: `inline`,
+        start(src: string) {
+          // 匹配以 [ 开头的格式
+          return src.match(/\[/)?.index
+        },
+        tokenizer(src: string) {
+          // 1. [文字]{注音}
+          const rule1 = /^\[([^\]]+)\]\{([^}]+)\}/
+          let match = rule1.exec(src)
+          if (match) {
+            return {
+              type: `ruby`,
+              raw: match[0],
+              text: match[1].trim(),
+              ruby: match[2].trim(),
+              format: `basic`,
+            }
+          }
+
+          // 2. [文字]^(注音)
+          const rule2 = /^\[([^\]]+)\]\^\(([^)]+)\)/
+          match = rule2.exec(src)
+          if (match) {
+            return {
+              type: `ruby`,
+              raw: match[0],
+              text: match[1].trim(),
+              ruby: match[2].trim(),
+              format: `basic-hat`,
+            }
+          }
+
+          return undefined
+        },
+        renderer(token: any) {
+          const { text, ruby, format } = token
+
+          // 检查是否有分隔符
+          const separatorRegex = /[・．。-]/g
+          const hasSeparators = separatorRegex.test(ruby)
+
+          if (hasSeparators) {
+            // 分割注音部分
+            const rubyParts = ruby.split(separatorRegex).filter((part: string) => part.trim() !== ``)
+
+            const textChars = text.split(``)
+            const result = []
+
+            if (textChars.length >= rubyParts.length) {
+              // 文字字符数量 >= 注音部分数量
+              // 按注音部分数量分割文字
+              let currentIndex = 0
+
+              for (let i = 0; i < rubyParts.length; i++) {
+                const rubyPart = rubyParts[i]
+                const remainingChars = textChars.length - currentIndex
+                const remainingParts = rubyParts.length - i
+
+                // 计算当前部分应该包含多少个字符，默认为 1
+                let charCount = 1
+                if (remainingParts === 1) {
+                  // 最后一个部分，包含所有剩余字符
+                  charCount = remainingChars
+                }
+
+                // 提取当前部分的文字
+                const currentText = textChars.slice(currentIndex, currentIndex + charCount).join(``)
+
+                result.push(`<ruby data-text="${currentText}" data-ruby="${rubyPart}" data-format="${format}">${currentText}<rp>(</rp><rt>${rubyPart}</rt><rp>)</rp></ruby>`)
+
+                currentIndex += charCount
+              }
+
+              // 处理剩余的字符
+              if (currentIndex < textChars.length) {
+                result.push(textChars.slice(currentIndex).join(``))
+              }
+            }
+            else {
+              // 文字字符数量 < 注音部分数量
+              // 每个字符对应一个注音部分，多余的注音被忽略
+              for (let i = 0; i < textChars.length; i++) {
+                const char = textChars[i]
+                const rubyPart = rubyParts[i] || ``
+
+                if (rubyPart) {
+                  result.push(`<ruby data-text="${char}" data-ruby="${rubyPart}" data-format="${format}">${char}<rp>(</rp><rt>${rubyPart}</rt><rp>)</rp></ruby>`)
+                }
+                else {
+                  result.push(char)
+                }
+              }
+            }
+
+            return result.join(``)
+          }
+
+          return `<ruby data-text="${text}" data-ruby="${ruby}" data-format="${format}">${text}<rp>(</rp><rt>${ruby}</rt><rp>)</rp></ruby>`
+        },
+      },
+    ],
+  }
+}
@@ -0,0 +1,73 @@
+import type { MarkedExtension, Tokens } from 'marked'
+
+/**
+ * A marked extension to support horizontal sliding images.
+ * Syntax: <![alt1](url1),![alt2](url2),![alt3](url3)>
+ */
+export function markedSlider(): MarkedExtension {
+  return {
+    extensions: [
+      {
+        name: `horizontalSlider`,
+        level: `block`,
+        start(src: string) {
+          return src.match(/^<!\[/)?.index
+        },
+        tokenizer(src: string) {
+          const rule = /^<(!\[.*?\]\(.*?\)(?:,!\[.*?\]\(.*?\))*)>/
+          const match = src.match(rule)
+          if (match) {
+            return {
+              type: `horizontalSlider`,
+              raw: match[0],
+              text: match[1],
+            }
+          }
+          return undefined
+        },
+        renderer(token: Tokens.Generic) {
+          const { text } = token
+          const imageMatches = text.match(/!\[(.*?)\]\((.*?)\)/g) || []
+
+          if (imageMatches.length === 0) {
+            return ``
+          }
+
+          const images = imageMatches.map((img: string) => {
+            const altMatch = img.match(/!\[(.*?)\]/) || []
+            const srcMatch = img.match(/\]\((.*?)\)/) || []
+            const alt = altMatch[1] || ``
+            const src = srcMatch[1] || ``
+
+            // 新主题系统：不再需要内联样式
+            return { src, alt }
+          })
+
+          // 使用微信公众号兼容的滑动容器布局
+          // 使用微信支持的section标签和特殊样式组合
+
+          return `
+            <section style="box-sizing: border-box; font-size: 16px;">
+              <section data-role="outer" style="font-family: 微软雅黑; font-size: 16px;">
+                <section data-role="paragraph" style="margin: 0px auto; box-sizing: border-box; width: 100%;">
+                  <section style="margin: 0px auto; text-align: center;">
+                    <section style="display: inline-block; width: 100%;">
+                      <!-- 微信公众号支持的滑动图片容器 -->
+                      <section style="overflow-x: scroll; -webkit-overflow-scrolling: touch; white-space: nowrap; width: 100%; text-align: center;">
+                        ${images.map((img: { src: string, alt: string }, _index: number) => `<section style="display: inline-block; width: 100%; margin-right: 0; vertical-align: top;">
+                          <img src="${img.src}" alt="${img.alt}" title="${img.alt}" style="width: 100%; height: auto; border-radius: 4px; vertical-align: top;"/>
+                          <p style="margin-top: 5px; font-size: 14px; color: #666; text-align: center; white-space: normal;">${img.alt}</p>
+                        </section>`).join(``)}
+                      </section>
+                    </section>
+                  </section>
+                </section>
+              </section>
+              <p style="font-size: 14px; color: #999; text-align: center; margin-top: 5px;"><<< 左右滑动看更多 >>></p>
+            </section>
+          `
+        },
+      },
+    ],
+  }
+}
@@ -0,0 +1,74 @@
+import type { MarkedExtension } from 'marked'
+
+/**
+ * marked 插件：支持 [TOC] 语法，自动生成嵌套目录
+ */
+export function markedToc(): MarkedExtension {
+  let headings: { text: string, depth: number, index: number }[] = []
+
+  let firstToken = true
+
+  return {
+    walkTokens(token) {
+      if (firstToken) {
+        headings = []
+        firstToken = false
+      }
+      if (token.type === `heading`) {
+        const text = token.text || ``
+        const depth = token.depth || 1
+        const index = headings.length
+        headings.push({ text, depth, index })
+      }
+    },
+    extensions: [
+      {
+        name: `toc`,
+        level: `block`,
+        start(src) {
+          // 只匹配独立一行的 [TOC]，避免误伤
+          const match = src.match(/^\s*\[TOC\]\s*$/m)
+          return match ? match.index : undefined
+        },
+        tokenizer(src) {
+          const match = /^\[TOC\]/.exec(src)
+          if (match) {
+            return {
+              type: `toc`,
+              raw: match[0],
+            }
+          }
+        },
+        renderer() {
+          if (!headings.length)
+            return ``
+          let html = `<nav class="markdown-toc"><ul class="toc-ul toc-level-1 pl-4 border-l ml-2">`
+          let lastDepth = 1
+          headings.forEach(({ text, depth, index }) => {
+            if (depth > lastDepth) {
+              for (let i = lastDepth + 1; i <= depth; i++) {
+                html += `<ul class="toc-ul toc-level-${i} pl-4 border-l ml-2">`
+              }
+            }
+            else if (depth < lastDepth) {
+              for (let i = lastDepth; i > depth; i--) {
+                html += `</ul>`
+              }
+            }
+            html += `<li class="toc-li toc-level-${depth} mb-1"><a class="text-gray-700 hover:text-blue-600 underline transition-colors" href="#${index}">${text}</a></li>`
+            lastDepth = depth
+          })
+
+          for (let i = lastDepth; i > 1; i--) {
+            html += `</ul>`
+          }
+
+          html += `</ul></nav>`
+
+          firstToken = true
+          return html
+        },
+      },
+    ],
+  }
+}
@@ -0,0 +1,654 @@
+#!/usr/bin/env npx tsx
+
+import fs from "node:fs";
+import path from "node:path";
+import { fileURLToPath } from "node:url";
+import frontMatter from "front-matter";
+import hljs from "highlight.js/lib/core";
+import { marked, type RendererObject, type Tokens } from "marked";
+import readingTime, { type ReadTimeResults } from "reading-time";
+
+import {
+  markedAlert,
+  markedFootnotes,
+  markedInfographic,
+  markedMarkup,
+  markedPlantUML,
+  markedRuby,
+  markedSlider,
+  markedToc,
+  MDKatex,
+} from "./extensions/index.js";
+import {
+  COMMON_LANGUAGES,
+  highlightAndFormatCode,
+} from "./utils/languages.js";
+
+type ThemeName = "default" | "grace" | "simple";
+
+const SCRIPT_DIR = path.dirname(fileURLToPath(import.meta.url));
+const THEME_DIR = path.resolve(SCRIPT_DIR, "themes");
+const THEME_NAMES: ThemeName[] = ["default", "grace", "simple"];
+
+const DEFAULT_STYLE = {
+  primaryColor: "#0F4C81",
+  fontFamily:
+    "-apple-system-font,BlinkMacSystemFont, Helvetica Neue, PingFang SC, Hiragino Sans GB , Microsoft YaHei UI , Microsoft YaHei ,Arial,sans-serif",
+  fontSize: "16px",
+  foreground: "0 0% 3.9%",
+  blockquoteBackground: "#f7f7f7",
+};
+
+Object.entries(COMMON_LANGUAGES).forEach(([name, lang]) => {
+  hljs.registerLanguage(name, lang);
+});
+
+export { hljs };
+
+marked.setOptions({
+  breaks: true,
+});
+marked.use(markedSlider());
+
+interface IOpts {
+  legend?: string;
+  citeStatus?: boolean;
+  countStatus?: boolean;
+  isMacCodeBlock?: boolean;
+  isShowLineNumber?: boolean;
+  themeMode?: "light" | "dark";
+}
+
+interface RendererAPI {
+  reset: (newOpts: Partial<IOpts>) => void;
+  setOptions: (newOpts: Partial<IOpts>) => void;
+  getOpts: () => IOpts;
+  parseFrontMatterAndContent: (markdown: string) => {
+    yamlData: Record<string, any>;
+    markdownContent: string;
+    readingTime: ReadTimeResults;
+  };
+  buildReadingTime: (reading: ReadTimeResults) => string;
+  buildFootnotes: () => string;
+  buildAddition: () => string;
+  createContainer: (html: string) => string;
+}
+
+interface ParseResult {
+  yamlData: Record<string, any>;
+  markdownContent: string;
+  readingTime: ReadTimeResults;
+}
+
+function escapeHtml(text: string): string {
+  return text
+    .replace(/&/g, "&amp;")
+    .replace(/</g, "&lt;")
+    .replace(/>/g, "&gt;")
+    .replace(/"/g, "&quot;")
+    .replace(/'/g, "&#39;")
+    .replace(/`/g, "&#96;");
+}
+
+function buildAddition(): string {
+  return `
+    <style>
+      .preview-wrapper pre::before {
+        position: absolute;
+        top: 0;
+        right: 0;
+        color: #ccc;
+        text-align: center;
+        font-size: 0.8em;
+        padding: 5px 10px 0;
+        line-height: 15px;
+        height: 15px;
+        font-weight: 600;
+      }
+    </style>
+  `;
+}
+
+function buildFootnoteArray(footnotes: [number, string, string][]): string {
+  return footnotes
+    .map(([index, title, link]) =>
+      link === title
+        ? `<code style="font-size: 90%; opacity: 0.6;">[${index}]</code>: <i style="word-break: break-all">${title}</i><br/>`
+        : `<code style="font-size: 90%; opacity: 0.6;">[${index}]</code> ${title}: <i style="word-break: break-all">${link}</i><br/>`
+    )
+    .join("\n");
+}
+
+function transform(legend: string, text: string | null, title: string | null): string {
+  const options = legend.split("-");
+  for (const option of options) {
+    if (option === "alt" && text) {
+      return text;
+    }
+    if (option === "title" && title) {
+      return title;
+    }
+  }
+  return "";
+}
+
+const macCodeSvg = `
+  <svg xmlns="http://www.w3.org/2000/svg" version="1.1" x="0px" y="0px" width="45px" height="13px" viewBox="0 0 450 130">
+    <ellipse cx="50" cy="65" rx="50" ry="52" stroke="rgb(220,60,54)" stroke-width="2" fill="rgb(237,108,96)" />
+    <ellipse cx="225" cy="65" rx="50" ry="52" stroke="rgb(218,151,33)" stroke-width="2" fill="rgb(247,193,81)" />
+    <ellipse cx="400" cy="65" rx="50" ry="52" stroke="rgb(27,161,37)" stroke-width="2" fill="rgb(100,200,86)" />
+  </svg>
+`.trim();
+
+function parseFrontMatterAndContent(markdownText: string): ParseResult {
+  try {
+    const parsed = frontMatter(markdownText);
+    const yamlData = parsed.attributes;
+    const markdownContent = parsed.body;
+
+    const readingTimeResult = readingTime(markdownContent);
+
+    return {
+      yamlData: yamlData as Record<string, any>,
+      markdownContent,
+      readingTime: readingTimeResult,
+    };
+  } catch (error) {
+    console.error("Error parsing front-matter:", error);
+    return {
+      yamlData: {},
+      markdownContent: markdownText,
+      readingTime: readingTime(markdownText),
+    };
+  }
+}
+
+export function initRenderer(opts: IOpts = {}): RendererAPI {
+  const footnotes: [number, string, string][] = [];
+  let footnoteIndex = 0;
+  let codeIndex = 0;
+  const listOrderedStack: boolean[] = [];
+  const listCounters: number[] = [];
+  const isBrowser = typeof window !== "undefined";
+
+  function getOpts(): IOpts {
+    return opts;
+  }
+
+  function styledContent(styleLabel: string, content: string, tagName?: string): string {
+    const tag = tagName ?? styleLabel;
+    const className = `${styleLabel.replace(/_/g, "-")}`;
+    const headingAttr = /^h\d$/.test(tag) ? " data-heading=\"true\"" : "";
+    return `<${tag} class="${className}"${headingAttr}>${content}</${tag}>`;
+  }
+
+  function addFootnote(title: string, link: string): number {
+    const existingFootnote = footnotes.find(([, , existingLink]) => existingLink === link);
+    if (existingFootnote) {
+      return existingFootnote[0];
+    }
+
+    footnotes.push([++footnoteIndex, title, link]);
+    return footnoteIndex;
+  }
+
+  function reset(newOpts: Partial<IOpts>): void {
+    footnotes.length = 0;
+    footnoteIndex = 0;
+    setOptions(newOpts);
+  }
+
+  function setOptions(newOpts: Partial<IOpts>): void {
+    opts = { ...opts, ...newOpts };
+    marked.use(markedAlert());
+    if (isBrowser) {
+      marked.use(MDKatex({ nonStandard: true }, true));
+    }
+    marked.use(markedMarkup());
+    marked.use(markedInfographic({ themeMode: opts.themeMode }));
+  }
+
+  function buildReadingTime(readingTimeResult: ReadTimeResults): string {
+    if (!opts.countStatus) {
+      return "";
+    }
+    if (!readingTimeResult.words) {
+      return "";
+    }
+    return `
+      <blockquote class="md-blockquote">
+        <p class="md-blockquote-p">字数 ${readingTimeResult?.words}，阅读大约需 ${Math.ceil(readingTimeResult?.minutes)} 分钟</p>
+      </blockquote>
+    `;
+  }
+
+  const buildFootnotes = () => {
+    if (!footnotes.length) {
+      return "";
+    }
+
+    return (
+      styledContent("h4", "引用链接")
+      + styledContent("footnotes", buildFootnoteArray(footnotes), "p")
+    );
+  };
+
+  const renderer: RendererObject = {
+    heading({ tokens, depth }: Tokens.Heading) {
+      const text = this.parser.parseInline(tokens);
+      const tag = `h${depth}`;
+      return styledContent(tag, text);
+    },
+
+    paragraph({ tokens }: Tokens.Paragraph): string {
+      const text = this.parser.parseInline(tokens);
+      const isFigureImage = text.includes("<figure") && text.includes("<img");
+      const isEmpty = text.trim() === "";
+      if (isFigureImage || isEmpty) {
+        return text;
+      }
+      return styledContent("p", text);
+    },
+
+    blockquote({ tokens }: Tokens.Blockquote): string {
+      const text = this.parser.parse(tokens);
+      return styledContent("blockquote", text);
+    },
+
+    code({ text, lang = "" }: Tokens.Code): string {
+      if (lang.startsWith("mermaid")) {
+        if (isBrowser) {
+          clearTimeout(codeIndex as any);
+          codeIndex = setTimeout(async () => {
+            const windowRef = typeof window !== "undefined" ? (window as any) : undefined;
+            if (windowRef && windowRef.mermaid) {
+              const mermaid = windowRef.mermaid;
+              await mermaid.run();
+            } else {
+              const mermaid = await import("mermaid");
+              await mermaid.default.run();
+            }
+          }, 0) as any as number;
+        }
+        return `<pre class="mermaid">${text}</pre>`;
+      }
+      const langText = lang.split(" ")[0];
+      const isLanguageRegistered = hljs.getLanguage(langText);
+      const language = isLanguageRegistered ? langText : "plaintext";
+
+      const highlighted = highlightAndFormatCode(
+        text,
+        language,
+        hljs,
+        !!opts.isShowLineNumber
+      );
+
+      const span = `<span class="mac-sign" style="padding: 10px 14px 0;">${macCodeSvg}</span>`;
+      let pendingAttr = "";
+      if (!isLanguageRegistered && langText !== "plaintext") {
+        const escapedText = text.replace(/"/g, "&quot;");
+        pendingAttr = ` data-language-pending="${langText}" data-raw-code="${escapedText}" data-show-line-number="${opts.isShowLineNumber}"`;
+      }
+      const code = `<code class="language-${lang}"${pendingAttr}>${highlighted}</code>`;
+
+      return `<pre class="hljs code__pre">${span}${code}</pre>`;
+    },
+
+    codespan({ text }: Tokens.Codespan): string {
+      const escapedText = escapeHtml(text);
+      return styledContent("codespan", escapedText, "code");
+    },
+
+    list({ ordered, items, start = 1 }: Tokens.List) {
+      listOrderedStack.push(ordered);
+      listCounters.push(Number(start));
+
+      const html = items.map((item) => this.listitem(item)).join("");
+
+      listOrderedStack.pop();
+      listCounters.pop();
+
+      return styledContent(ordered ? "ol" : "ul", html);
+    },
+
+    listitem(token: Tokens.ListItem) {
+      const ordered = listOrderedStack[listOrderedStack.length - 1];
+      const idx = listCounters[listCounters.length - 1]!;
+
+      listCounters[listCounters.length - 1] = idx + 1;
+
+      const prefix = ordered ? `${idx}. ` : "• ";
+
+      let content: string;
+      try {
+        content = this.parser.parseInline(token.tokens);
+      } catch {
+        content = this.parser
+          .parse(token.tokens)
+          .replace(/^<p(?:\s[^>]*)?>([\s\S]*?)<\/p>/, "$1");
+      }
+
+      return styledContent("listitem", `${prefix}${content}`, "li");
+    },
+
+    image({ href, title, text }: Tokens.Image): string {
+      const newText = opts.legend ? transform(opts.legend, text, title) : "";
+      const subText = newText ? styledContent("figcaption", newText) : "";
+      const titleAttr = title ? ` title="${title}"` : "";
+      return `<figure><img src="${href}"${titleAttr} alt="${text}"/>${subText}</figure>`;
+    },
+
+    link({ href, title, text, tokens }: Tokens.Link): string {
+      const parsedText = this.parser.parseInline(tokens);
+      if (/^https?:\/\/mp\.weixin\.qq\.com/.test(href)) {
+        return `<a href="${href}" title="${title || text}">${parsedText}</a>`;
+      }
+      if (href === text) {
+        return parsedText;
+      }
+      if (opts.citeStatus) {
+        const ref = addFootnote(title || text, href);
+        return `<a href="${href}" title="${title || text}">${parsedText}<sup>[${ref}]</sup></a>`;
+      }
+      return `<a href="${href}" title="${title || text}">${parsedText}</a>`;
+    },
+
+    strong({ tokens }: Tokens.Strong): string {
+      return styledContent("strong", this.parser.parseInline(tokens));
+    },
+
+    em({ tokens }: Tokens.Em): string {
+      return styledContent("em", this.parser.parseInline(tokens));
+    },
+
+    table({ header, rows }: Tokens.Table): string {
+      const headerRow = header
+        .map((cell) => {
+          const text = this.parser.parseInline(cell.tokens);
+          return styledContent("th", text);
+        })
+        .join("");
+      const body = rows
+        .map((row) => {
+          const rowContent = row.map((cell) => this.tablecell(cell)).join("");
+          return styledContent("tr", rowContent);
+        })
+        .join("");
+      return `
+        <section style="max-width: 100%; overflow: auto">
+          <table class="preview-table">
+            <thead>${headerRow}</thead>
+            <tbody>${body}</tbody>
+          </table>
+        </section>
+      `;
+    },
+
+    tablecell(token: Tokens.TableCell): string {
+      const text = this.parser.parseInline(token.tokens);
+      return styledContent("td", text);
+    },
+
+    hr(_: Tokens.Hr): string {
+      return styledContent("hr", "");
+    },
+  };
+
+  marked.use({ renderer });
+  marked.use(markedMarkup());
+  marked.use(markedToc());
+  marked.use(markedSlider());
+  marked.use(markedAlert({}));
+  if (isBrowser) {
+    marked.use(MDKatex({ nonStandard: true }, true));
+  }
+  marked.use(markedFootnotes());
+  marked.use(
+    markedPlantUML({
+      inlineSvg: isBrowser,
+    })
+  );
+  marked.use(markedInfographic());
+  marked.use(markedRuby());
+
+  return {
+    buildAddition,
+    buildFootnotes,
+    setOptions,
+    reset,
+    parseFrontMatterAndContent,
+    buildReadingTime,
+    createContainer(content: string) {
+      return styledContent("container", content, "section");
+    },
+    getOpts,
+  };
+}
+
+function printUsage(): void {
+  console.error(
+    [
+      "Usage:",
+      "  npx tsx src/md/render.ts <markdown_file> [--theme <name>]",
+      "",
+      "Options:",
+      `  --theme   Theme name (${THEME_NAMES.join(", ")})`,
+    ].join("\n")
+  );
+}
+
+function parseArgs(argv: string[]): CliOptions | null {
+  let inputPath = "";
+  let theme: ThemeName = "default";
+
+  for (let i = 0; i < argv.length; i += 1) {
+    const arg = argv[i];
+    if (!arg.startsWith("--") && !inputPath) {
+      inputPath = arg;
+      continue;
+    }
+
+    if (arg === "--theme") {
+      theme = (argv[i + 1] || "") as ThemeName;
+      i += 1;
+      continue;
+    }
+
+    if (arg.startsWith("--theme=")) {
+      theme = arg.slice("--theme=".length) as ThemeName;
+      continue;
+    }
+
+    if (arg === "--help" || arg === "-h") {
+      return null;
+    }
+
+    console.error(`Unknown argument: ${arg}`);
+    return null;
+  }
+
+  if (!inputPath) {
+    return null;
+  }
+
+  if (!THEME_NAMES.includes(theme)) {
+    console.error(`Unknown theme: ${theme}`);
+    return null;
+  }
+
+  return {
+    inputPath,
+    theme,
+  };
+}
+
+interface CliOptions {
+  inputPath: string;
+  theme: ThemeName;
+}
+
+function renderMarkdown(raw: string, renderer: RendererAPI): {
+  html: string;
+  readingTime: ReadTimeResults;
+} {
+  const { markdownContent, readingTime: readingTimeResult } =
+    renderer.parseFrontMatterAndContent(raw);
+
+  const html = marked.parse(markdownContent) as string;
+
+  return { html, readingTime: readingTimeResult };
+}
+
+function postProcessHtml(
+  baseHtml: string,
+  reading: ReadTimeResults,
+  renderer: RendererAPI
+): string {
+  let html = baseHtml;
+  html = renderer.buildReadingTime(reading) + html;
+  html += renderer.buildFootnotes();
+  html += renderer.buildAddition();
+  html += `
+    <style>
+      .hljs.code__pre > .mac-sign {
+        display: ${renderer.getOpts().isMacCodeBlock ? "flex" : "none"};
+      }
+    </style>
+  `;
+  html += `
+    <style>
+      h2 strong {
+        color: inherit !important;
+      }
+    </style>
+  `;
+  return renderer.createContainer(html);
+}
+
+function formatTimestamp(date = new Date()): string {
+  const pad = (value: number) => String(value).padStart(2, "0");
+  return `${date.getFullYear()}${pad(date.getMonth() + 1)}${pad(
+    date.getDate()
+  )}${pad(date.getHours())}${pad(date.getMinutes())}${pad(date.getSeconds())}`;
+}
+
+function ensureMarkdownPath(inputPath: string): void {
+  if (!inputPath.toLowerCase().endsWith(".md")) {
+    throw new Error("Input file must end with .md");
+  }
+}
+
+function loadThemeCss(theme: ThemeName): {
+  baseCss: string;
+  themeCss: string;
+} {
+  const basePath = path.join(THEME_DIR, "base.css");
+  const themePath = path.join(THEME_DIR, `${theme}.css`);
+
+  if (!fs.existsSync(basePath)) {
+    throw new Error(`Missing base CSS: ${basePath}`);
+  }
+
+  if (!fs.existsSync(themePath)) {
+    throw new Error(`Missing theme CSS: ${themePath}`);
+  }
+
+  return {
+    baseCss: fs.readFileSync(basePath, "utf-8"),
+    themeCss: fs.readFileSync(themePath, "utf-8"),
+  };
+}
+
+function buildCss(baseCss: string, themeCss: string): string {
+  const variables = `
+:root {
+  --md-primary-color: ${DEFAULT_STYLE.primaryColor};
+  --md-font-family: ${DEFAULT_STYLE.fontFamily};
+  --md-font-size: ${DEFAULT_STYLE.fontSize};
+  --foreground: ${DEFAULT_STYLE.foreground};
+  --blockquote-background: ${DEFAULT_STYLE.blockquoteBackground};
+}
+
+body {
+  margin: 0;
+  padding: 24px;
+  background: #ffffff;
+}
+
+#output {
+  max-width: 860px;
+  margin: 0 auto;
+}
+`.trim();
+
+  return [variables, baseCss, themeCss].join("\n\n");
+}
+
+function buildHtmlDocument(title: string, css: string, html: string): string {
+  return [
+    "<!doctype html>",
+    "<html>",
+    "<head>",
+    '  <meta charset="utf-8" />',
+    '  <meta name="viewport" content="width=device-width, initial-scale=1" />',
+    `  <title>${title}</title>`,
+    `  <style>${css}</style>`,
+    "</head>",
+    "<body>",
+    '  <div id="output">',
+    html,
+    "  </div>",
+    "</body>",
+    "</html>",
+  ].join("\n");
+}
+
+function main(): void {
+  const options = parseArgs(process.argv.slice(2));
+  if (!options) {
+    printUsage();
+    process.exit(1);
+  }
+
+  const inputPath = path.resolve(process.cwd(), options.inputPath);
+  ensureMarkdownPath(inputPath);
+
+  if (!fs.existsSync(inputPath)) {
+    console.error(`File not found: ${inputPath}`);
+    process.exit(1);
+  }
+
+  const outputPath = path.resolve(
+    process.cwd(),
+    options.inputPath.replace(/\.md$/i, ".html")
+  );
+
+  const { baseCss, themeCss } = loadThemeCss(options.theme);
+  const css = buildCss(baseCss, themeCss);
+  const markdown = fs.readFileSync(inputPath, "utf-8");
+
+  const renderer = initRenderer({});
+  const { html: baseHtml, readingTime: readingTimeResult } = renderMarkdown(
+    markdown,
+    renderer
+  );
+  const content = postProcessHtml(baseHtml, readingTimeResult, renderer);
+
+  const title = path.basename(outputPath, ".html");
+  const html = buildHtmlDocument(title, css, content);
+
+  let backupPath = "";
+  if (fs.existsSync(outputPath)) {
+    backupPath = `${outputPath}.bak-${formatTimestamp()}`;
+    fs.renameSync(outputPath, backupPath);
+  }
+
+  fs.writeFileSync(outputPath, html, "utf-8");
+
+  if (backupPath) {
+    console.log(`Backup created: ${backupPath}`);
+  }
+  console.log(`HTML written: ${outputPath}`);
+}
+
+main();
@@ -0,0 +1,26 @@
+/**
+ * MD 基础主题样式
+ * 包含所有元素的基础样式和 CSS 变量定义
+ */
+
+/* ==================== 容器样式 ==================== */
+section,
+container {
+  font-family: var(--md-font-family);
+  font-size: var(--md-font-size);
+  line-height: 1.75;
+  text-align: left;
+}
+
+/* 确保 #output 容器应用基础样式 */
+#output {
+  font-family: var(--md-font-family);
+  font-size: var(--md-font-size);
+  line-height: 1.75;
+  text-align: left;
+}
+
+/* 去除第一个元素的 margin-top */
+#output section > :first-child {
+  margin-top: 0 !important;
+}
@@ -0,0 +1,433 @@
+/**
+ * MD 默认主题（经典主题）
+ * 按 Alt/Option + Shift + F 可格式化
+ * 如需使用主题色，请使用 var(--md-primary-color) 代替颜色值
+ */
+
+/* ==================== 一级标题 ==================== */
+h1 {
+  display: table;
+  padding: 0 1em;
+  border-bottom: 2px solid var(--md-primary-color);
+  margin: 2em auto 1em;
+  color: hsl(var(--foreground));
+  font-size: calc(var(--md-font-size) * 1.2);
+  font-weight: bold;
+  text-align: center;
+}
+
+/* ==================== 二级标题 ==================== */
+h2 {
+  display: table;
+  padding: 0 0.2em;
+  margin: 4em auto 2em;
+  color: #fff;
+  background: var(--md-primary-color);
+  font-size: calc(var(--md-font-size) * 1.2);
+  font-weight: bold;
+  text-align: center;
+}
+
+/* ==================== 三级标题 ==================== */
+h3 {
+  padding-left: 8px;
+  border-left: 3px solid var(--md-primary-color);
+  margin: 2em 8px 0.75em 0;
+  color: hsl(var(--foreground));
+  font-size: calc(var(--md-font-size) * 1.1);
+  font-weight: bold;
+  line-height: 1.2;
+}
+
+/* ==================== 四级标题 ==================== */
+h4 {
+  margin: 2em 8px 0.5em;
+  color: var(--md-primary-color);
+  font-size: calc(var(--md-font-size) * 1);
+  font-weight: bold;
+}
+
+/* ==================== 五级标题 ==================== */
+h5 {
+  margin: 1.5em 8px 0.5em;
+  color: var(--md-primary-color);
+  font-size: calc(var(--md-font-size) * 1);
+  font-weight: bold;
+}
+
+/* ==================== 六级标题 ==================== */
+h6 {
+  margin: 1.5em 8px 0.5em;
+  font-size: calc(var(--md-font-size) * 1);
+  color: var(--md-primary-color);
+}
+
+/* ==================== 段落 ==================== */
+p {
+  margin: 1.5em 8px;
+  letter-spacing: 0.1em;
+  color: hsl(var(--foreground));
+}
+
+/* ==================== 引用块 ==================== */
+blockquote {
+  font-style: normal;
+  padding: 1em;
+  border-left: 4px solid var(--md-primary-color);
+  border-radius: 6px;
+  color: hsl(var(--foreground));
+  background: var(--blockquote-background);
+  margin-bottom: 1em;
+}
+
+blockquote > p {
+  display: block;
+  font-size: 1em;
+  letter-spacing: 0.1em;
+  color: hsl(var(--foreground));
+  margin: 0;
+}
+
+/* ==================== GFM 警告块 ==================== */
+.alert-title-note,
+.alert-title-tip,
+.alert-title-info,
+.alert-title-important,
+.alert-title-warning,
+.alert-title-caution,
+.alert-title-abstract,
+.alert-title-summary,
+.alert-title-tldr,
+.alert-title-todo,
+.alert-title-success,
+.alert-title-done,
+.alert-title-question,
+.alert-title-help,
+.alert-title-faq,
+.alert-title-failure,
+.alert-title-fail,
+.alert-title-missing,
+.alert-title-danger,
+.alert-title-error,
+.alert-title-bug,
+.alert-title-example,
+.alert-title-quote,
+.alert-title-cite {
+  display: flex;
+  align-items: center;
+  gap: 0.5em;
+  margin-bottom: 0.5em;
+}
+
+.alert-title-note {
+  color: #478be6;
+}
+
+.alert-title-tip {
+  color: #57ab5a;
+}
+
+.alert-title-info {
+  color: #93c5fd;
+}
+
+.alert-title-important {
+  color: #986ee2;
+}
+
+.alert-title-warning {
+  color: #c69026;
+}
+
+.alert-title-caution {
+  color: #e5534b;
+}
+
+/* Obsidian-style callout colors */
+.alert-title-abstract,
+.alert-title-summary,
+.alert-title-tldr {
+  color: #00bfff;
+}
+
+.alert-title-todo {
+  color: #478be6;
+}
+
+.alert-title-success,
+.alert-title-done {
+  color: #57ab5a;
+}
+
+.alert-title-question,
+.alert-title-help,
+.alert-title-faq {
+  color: #c69026;
+}
+
+.alert-title-failure,
+.alert-title-fail,
+.alert-title-missing {
+  color: #e5534b;
+}
+
+.alert-title-danger,
+.alert-title-error {
+  color: #e5534b;
+}
+
+.alert-title-bug {
+  color: #e5534b;
+}
+
+.alert-title-example {
+  color: #986ee2;
+}
+
+.alert-title-quote,
+.alert-title-cite {
+  color: #9ca3af;
+}
+
+/* GFM Alert SVG 图标颜色 */
+.alert-icon-note {
+  fill: #478be6;
+}
+
+.alert-icon-tip {
+  fill: #57ab5a;
+}
+
+.alert-icon-info {
+  fill: #93c5fd;
+}
+
+.alert-icon-important {
+  fill: #986ee2;
+}
+
+.alert-icon-warning {
+  fill: #c69026;
+}
+
+.alert-icon-caution {
+  fill: #e5534b;
+}
+
+/* Obsidian-style callout icon colors */
+.alert-icon-abstract,
+.alert-icon-summary,
+.alert-icon-tldr {
+  fill: #00bfff;
+}
+
+.alert-icon-todo {
+  fill: #478be6;
+}
+
+.alert-icon-success,
+.alert-icon-done {
+  fill: #57ab5a;
+}
+
+.alert-icon-question,
+.alert-icon-help,
+.alert-icon-faq {
+  fill: #c69026;
+}
+
+.alert-icon-failure,
+.alert-icon-fail,
+.alert-icon-missing {
+  fill: #e5534b;
+}
+
+.alert-icon-danger,
+.alert-icon-error {
+  fill: #e5534b;
+}
+
+.alert-icon-bug {
+  fill: #e5534b;
+}
+
+.alert-icon-example {
+  fill: #986ee2;
+}
+
+.alert-icon-quote,
+.alert-icon-cite {
+  fill: #9ca3af;
+}
+
+/* ==================== 代码块 ==================== */
+pre.code__pre,
+.hljs.code__pre {
+  font-size: 90%;
+  overflow-x: auto;
+  border-radius: 8px;
+  padding: 0 !important;
+  line-height: 1.5;
+  margin: 10px 8px;
+}
+
+/* ==================== 图片 ==================== */
+img {
+  display: block;
+  max-width: 100%;
+  margin: 0.1em auto 0.5em;
+  border-radius: 4px;
+}
+
+/* ==================== 列表 ==================== */
+ol {
+  padding-left: 1em;
+  margin-left: 0;
+  color: hsl(var(--foreground));
+}
+
+ul {
+  list-style: circle;
+  padding-left: 1em;
+  margin-left: 0;
+  color: hsl(var(--foreground));
+}
+
+li {
+  display: block;
+  margin: 0.2em 8px;
+  color: hsl(var(--foreground));
+}
+
+/* ==================== 脚注 ==================== */
+/* footnotes 在 buildFootnotes() 中渲染为 <p> 标签 */
+p.footnotes {
+  margin: 0.5em 8px;
+  font-size: 80%;
+  color: hsl(var(--foreground));
+}
+
+/* ==================== 图表 ==================== */
+figure {
+  margin: 1.5em 8px;
+  color: hsl(var(--foreground));
+}
+
+figcaption,
+.md-figcaption {
+  text-align: center;
+  color: #888;
+  font-size: 0.8em;
+}
+
+/* ==================== 分隔线 ==================== */
+hr {
+  border-style: solid;
+  border-width: 2px 0 0;
+  border-color: rgba(0, 0, 0, 0.1);
+  -webkit-transform-origin: 0 0;
+  -webkit-transform: scale(1, 0.5);
+  transform-origin: 0 0;
+  transform: scale(1, 0.5);
+  height: 0.4em;
+  margin: 1.5em 0;
+}
+
+/* ==================== 行内代码 ==================== */
+code {
+  font-size: 90%;
+  color: #d14;
+  background: rgba(27, 31, 35, 0.05);
+  padding: 3px 5px;
+  border-radius: 4px;
+}
+
+/* 代码块内的 code 标签需要特殊处理（覆盖行内 code 样式） */
+pre.code__pre > code,
+.hljs.code__pre > code {
+  display: -webkit-box;
+  padding: 0.5em 1em 1em;
+  overflow-x: auto;
+  text-indent: 0;
+  color: inherit;
+  background: none;
+  white-space: nowrap;
+  margin: 0;
+}
+
+/* ==================== 强调 ==================== */
+em {
+  font-style: italic;
+  font-size: inherit;
+}
+
+/* ==================== 链接 ==================== */
+a {
+  color: #576b95;
+  text-decoration: none;
+}
+
+/* ==================== 粗体 ==================== */
+strong {
+  color: var(--md-primary-color);
+  font-weight: bold;
+  font-size: inherit;
+}
+
+/* ==================== 表格 ==================== */
+table {
+  color: hsl(var(--foreground));
+}
+
+thead {
+  font-weight: bold;
+  color: hsl(var(--foreground));
+}
+
+th {
+  border: 1px solid #dfdfdf;
+  padding: 0.25em 0.5em;
+  color: hsl(var(--foreground));
+  word-break: keep-all;
+  background: rgba(0, 0, 0, 0.05);
+}
+
+td {
+  border: 1px solid #dfdfdf;
+  padding: 0.25em 0.5em;
+  color: hsl(var(--foreground));
+  word-break: keep-all;
+}
+
+/* ==================== KaTeX 公式 ==================== */
+.katex-inline {
+  max-width: 100%;
+  overflow-x: auto;
+}
+
+.katex-block {
+  max-width: 100%;
+  overflow-x: auto;
+  -webkit-overflow-scrolling: touch;
+  padding: 0.5em 0;
+  text-align: center;
+}
+
+/* ==================== 标记高亮 ==================== */
+.markup-highlight {
+  background-color: var(--md-primary-color);
+  padding: 2px 4px;
+  border-radius: 2px;
+  color: #fff;
+}
+
+.markup-underline {
+  text-decoration: underline;
+  text-decoration-color: var(--md-primary-color);
+}
+
+.markup-wavyline {
+  text-decoration: underline wavy;
+  text-decoration-color: var(--md-primary-color);
+  text-decoration-thickness: 2px;
+}
@@ -0,0 +1,136 @@
+/**
+ * MD 优雅主题 (@brzhang)
+ * 在默认主题基础上添加优雅的视觉效果
+ */
+
+/* ==================== 标题样式 ==================== */
+h1 {
+  padding: 0.5em 1em;
+  border-bottom: 2px solid var(--md-primary-color);
+  font-size: calc(var(--md-font-size) * 1.4);
+  text-shadow: 2px 2px 4px rgba(0, 0, 0, 0.1);
+}
+
+h2 {
+  padding: 0.3em 1em;
+  border-radius: 8px;
+  font-size: calc(var(--md-font-size) * 1.3);
+  box-shadow: 0 4px 6px rgba(0, 0, 0, 0.1);
+}
+
+h3 {
+  padding-left: 12px;
+  font-size: calc(var(--md-font-size) * 1.2);
+  border-left: 4px solid var(--md-primary-color);
+  border-bottom: 1px dashed var(--md-primary-color);
+}
+
+h4 {
+  font-size: calc(var(--md-font-size) * 1.1);
+}
+
+h5 {
+  font-size: var(--md-font-size);
+}
+
+h6 {
+  font-size: var(--md-font-size);
+}
+
+/* ==================== 引用块 ==================== */
+blockquote {
+  font-style: italic;
+  padding: 1em 1em 1em 2em;
+  border-left: 4px solid var(--md-primary-color);
+  border-radius: 6px;
+  color: rgba(0, 0, 0, 0.6);
+  box-shadow: 0 4px 6px rgba(0, 0, 0, 0.05);
+  margin-bottom: 1em;
+}
+
+.markdown-alert {
+  font-style: italic;
+}
+
+/* ==================== 代码块 ==================== */
+pre.code__pre,
+.hljs.code__pre {
+  box-shadow: inset 0 0 10px rgba(0, 0, 0, 0.05);
+}
+
+pre.code__pre > code,
+.hljs.code__pre > code {
+  font-family:
+    'Fira Code',
+    Menlo,
+    Operator Mono,
+    Consolas,
+    Monaco,
+    monospace;
+}
+
+/* ==================== 图片 ==================== */
+img {
+  border-radius: 8px;
+  box-shadow: 0 4px 8px rgba(0, 0, 0, 0.1);
+}
+
+figcaption,
+.md-figcaption {
+  text-align: center;
+  color: #888;
+  font-size: 0.8em;
+}
+
+/* ==================== 列表 ==================== */
+ol {
+  padding-left: 1.5em;
+}
+
+ul {
+  list-style: none;
+  padding-left: 1.5em;
+}
+
+li {
+  margin: 0.5em 8px;
+}
+
+/* ==================== 分隔线 ==================== */
+hr {
+  height: 1px;
+  border: none;
+  margin: 2em 0;
+  background: linear-gradient(to right, rgba(0, 0, 0, 0), rgba(0, 0, 0, 0.1), rgba(0, 0, 0, 0));
+}
+
+/* ==================== 表格 ==================== */
+table {
+  border-collapse: separate;
+  border-spacing: 0;
+  border-radius: 8px;
+  margin: 1em 8px;
+  color: hsl(var(--foreground));
+  box-shadow: 0 4px 6px rgba(0, 0, 0, 0.1);
+  overflow: hidden;
+}
+
+thead {
+  color: #fff;
+}
+
+td {
+  padding: 0.5em 1em;
+}
+
+/* ==================== 强调 ==================== */
+em {
+  font-style: italic;
+  font-size: inherit;
+}
+
+/* ==================== 链接 ==================== */
+a {
+  color: #576b95;
+  text-decoration: none;
+}
@@ -0,0 +1,129 @@
+/**
+ * MD 简洁主题 (@okooo5km)
+ * 简洁现代的设计风格
+ */
+
+/* ==================== 标题样式 ==================== */
+h1 {
+  padding: 0.5em 1em;
+  font-size: calc(var(--md-font-size) * 1.4);
+  text-shadow: 1px 1px 3px rgba(0, 0, 0, 0.05);
+}
+
+h2 {
+  padding: 0.3em 1.2em;
+  font-size: calc(var(--md-font-size) * 1.3);
+  border-radius: 8px 24px 8px 24px;
+  box-shadow: 0 2px 6px rgba(0, 0, 0, 0.06);
+}
+
+h3 {
+  padding-left: 12px;
+  font-size: calc(var(--md-font-size) * 1.2);
+  border-radius: 6px;
+  line-height: 2.4em;
+  border-left: 4px solid var(--md-primary-color);
+  border-right: 1px solid color-mix(in srgb, var(--md-primary-color) 10%, transparent);
+  border-bottom: 1px solid color-mix(in srgb, var(--md-primary-color) 10%, transparent);
+  border-top: 1px solid color-mix(in srgb, var(--md-primary-color) 10%, transparent);
+  background: color-mix(in srgb, var(--md-primary-color) 8%, transparent);
+}
+
+h4 {
+  font-size: calc(var(--md-font-size) * 1.1);
+  border-radius: 6px;
+}
+
+h5 {
+  font-size: var(--md-font-size);
+  border-radius: 6px;
+}
+
+h6 {
+  font-size: var(--md-font-size);
+  border-radius: 6px;
+}
+
+/* ==================== 引用块 ==================== */
+blockquote {
+  font-style: italic;
+  padding: 1em 1em 1em 2em;
+  color: rgba(0, 0, 0, 0.6);
+  border-bottom: 0.2px solid rgba(0, 0, 0, 0.04);
+  border-top: 0.2px solid rgba(0, 0, 0, 0.04);
+  border-right: 0.2px solid rgba(0, 0, 0, 0.04);
+}
+
+/* GFM Alert 样式覆盖 */
+.markdown-alert-note,
+.markdown-alert-tip,
+.markdown-alert-info,
+.markdown-alert-important,
+.markdown-alert-warning,
+.markdown-alert-caution {
+  font-style: italic;
+}
+
+/* ==================== 代码块 ==================== */
+pre.code__pre,
+.hljs.code__pre {
+  border: 1px solid rgba(0, 0, 0, 0.04);
+}
+
+pre.code__pre > code,
+.hljs.code__pre > code {
+  font-family:
+    'Fira Code',
+    Menlo,
+    Operator Mono,
+    Consolas,
+    Monaco,
+    monospace;
+}
+
+/* ==================== 图片 ==================== */
+img {
+  border-radius: 8px;
+  border: 1px solid rgba(0, 0, 0, 0.04);
+}
+
+figcaption,
+.md-figcaption {
+  text-align: center;
+  color: #888;
+  font-size: 0.8em;
+}
+
+/* ==================== 列表 ==================== */
+ol {
+  padding-left: 1.5em;
+}
+
+ul {
+  list-style: none;
+  padding-left: 1.5em;
+}
+
+li {
+  margin: 0.5em 8px;
+}
+
+/* ==================== 分隔线 ==================== */
+hr {
+  height: 1px;
+  border: none;
+  margin: 2em 0;
+  background: linear-gradient(to right, rgba(0, 0, 0, 0), rgba(0, 0, 0, 0.1), rgba(0, 0, 0, 0));
+}
+
+/* ==================== 强调 ==================== */
+em {
+  font-style: italic;
+  font-size: inherit;
+}
+
+/* ==================== 链接 ==================== */
+a {
+  color: #576b95;
+  text-decoration: none;
+}
@@ -0,0 +1,238 @@
+import type { LanguageFn } from 'highlight.js'
+import bash from 'highlight.js/lib/languages/bash'
+import c from 'highlight.js/lib/languages/c'
+import cpp from 'highlight.js/lib/languages/cpp'
+import csharp from 'highlight.js/lib/languages/csharp'
+import css from 'highlight.js/lib/languages/css'
+import diff from 'highlight.js/lib/languages/diff'
+import go from 'highlight.js/lib/languages/go'
+import graphql from 'highlight.js/lib/languages/graphql'
+import ini from 'highlight.js/lib/languages/ini'
+import java from 'highlight.js/lib/languages/java'
+import javascript from 'highlight.js/lib/languages/javascript'
+import json from 'highlight.js/lib/languages/json'
+import kotlin from 'highlight.js/lib/languages/kotlin'
+import less from 'highlight.js/lib/languages/less'
+import lua from 'highlight.js/lib/languages/lua'
+import makefile from 'highlight.js/lib/languages/makefile'
+import markdown from 'highlight.js/lib/languages/markdown'
+import objectivec from 'highlight.js/lib/languages/objectivec'
+import perl from 'highlight.js/lib/languages/perl'
+import php from 'highlight.js/lib/languages/php'
+import phpTemplate from 'highlight.js/lib/languages/php-template'
+import plaintext from 'highlight.js/lib/languages/plaintext'
+import python from 'highlight.js/lib/languages/python'
+import pythonRepl from 'highlight.js/lib/languages/python-repl'
+import r from 'highlight.js/lib/languages/r'
+import ruby from 'highlight.js/lib/languages/ruby'
+import rust from 'highlight.js/lib/languages/rust'
+import scss from 'highlight.js/lib/languages/scss'
+import shell from 'highlight.js/lib/languages/shell'
+import sql from 'highlight.js/lib/languages/sql'
+import swift from 'highlight.js/lib/languages/swift'
+import typescript from 'highlight.js/lib/languages/typescript'
+import vbnet from 'highlight.js/lib/languages/vbnet'
+import wasm from 'highlight.js/lib/languages/wasm'
+import xml from 'highlight.js/lib/languages/xml'
+import yaml from 'highlight.js/lib/languages/yaml'
+
+export const COMMON_LANGUAGES: Record<string, LanguageFn> = {
+  bash,
+  c,
+  cpp,
+  csharp,
+  css,
+  diff,
+  go,
+  graphql,
+  ini,
+  java,
+  javascript,
+  json,
+  kotlin,
+  less,
+  lua,
+  makefile,
+  markdown,
+  objectivec,
+  perl,
+  php,
+  'php-template': phpTemplate,
+  plaintext,
+  python,
+  'python-repl': pythonRepl,
+  r,
+  ruby,
+  rust,
+  scss,
+  shell,
+  sql,
+  swift,
+  typescript,
+  vbnet,
+  wasm,
+  xml,
+  yaml,
+}
+
+// highlight.js CDN 配置
+const HLJS_VERSION = `11.11.1`
+const HLJS_CDN_BASE = `https://cdn-doocs.oss-cn-shenzhen.aliyuncs.com/npm/highlightjs/${HLJS_VERSION}`
+
+// 缓存正在加载的语言
+const loadingLanguages = new Map<string, Promise<void>>()
+
+/**
+ * 生成语言包的 CDN URL
+ */
+function grammarUrlFor(language: string): string {
+  return `${HLJS_CDN_BASE}/es/languages/${language}.min.js`
+}
+
+/**
+ * 动态加载并注册语言
+ * @param language 语言名称
+ * @param hljs highlight.js 实例
+ */
+export async function loadAndRegisterLanguage(language: string, hljs: any): Promise<void> {
+  // 如果已经注册，直接返回
+  if (hljs.getLanguage(language)) {
+    return
+  }
+
+  // 如果正在加载，等待加载完成
+  if (loadingLanguages.has(language)) {
+    await loadingLanguages.get(language)
+    return
+  }
+
+  // 开始加载
+  const loadPromise = (async () => {
+    try {
+      const module = await import(/* @vite-ignore */ grammarUrlFor(language))
+      hljs.registerLanguage(language, module.default)
+    }
+    catch (error) {
+      console.warn(`Failed to load language: ${language}`, error)
+      throw error
+    }
+    finally {
+      loadingLanguages.delete(language)
+    }
+  })()
+
+  loadingLanguages.set(language, loadPromise)
+  await loadPromise
+}
+
+/**
+ * 格式化高亮后的代码，处理空格和制表符
+ */
+function formatHighlightedCode(html: string, preserveNewlines = false): string {
+  let formatted = html
+  // 将 span 之间的空格移到 span 内部
+  formatted = formatted.replace(/(<span[^>]*>[^<]*<\/span>)(\s+)(<span[^>]*>[^<]*<\/span>)/g, (_: string, span1: string, spaces: string, span2: string) => span1 + span2.replace(/^(<span[^>]*>)/, `$1${spaces}`))
+  formatted = formatted.replace(/(\s+)(<span[^>]*>)/g, (_: string, spaces: string, span: string) => span.replace(/^(<span[^>]*>)/, `$1${spaces}`))
+  // 替换制表符为4个空格
+  formatted = formatted.replace(/\t/g, `    `)
+
+  if (preserveNewlines) {
+    // 替换换行符为 <br/>，并将空格转换为 &nbsp;
+    formatted = formatted.replace(/\r\n/g, `<br/>`).replace(/\n/g, `<br/>`).replace(/(>[^<]+)|(^[^<]+)/g, (str: string) => str.replace(/\s/g, `&nbsp;`))
+  }
+  else {
+    // 只将空格转换为 &nbsp;
+    formatted = formatted.replace(/(>[^<]+)|(^[^<]+)/g, (str: string) => str.replace(/\s/g, `&nbsp;`))
+  }
+
+  return formatted
+}
+
+/**
+ * 高亮代码并格式化（支持行号）
+ * @param text 原始代码文本
+ * @param language 语言名称
+ * @param hljs highlight.js 实例
+ * @param showLineNumber 是否显示行号
+ * @returns 格式化后的 HTML
+ */
+export function highlightAndFormatCode(text: string, language: string, hljs: any, showLineNumber: boolean): string {
+  let highlighted = ``
+
+  if (showLineNumber) {
+    const rawLines = text.replace(/\r\n/g, `\n`).split(`\n`)
+
+    const highlightedLines = rawLines.map((lineRaw) => {
+      const lineHtml = hljs.highlight(lineRaw, { language }).value
+      const formatted = formatHighlightedCode(lineHtml, false)
+      return formatted === `` ? `&nbsp;` : formatted
+    })
+
+    const lineNumbersHtml = highlightedLines.map((_, idx) => `<section style="padding:0 10px 0 0;line-height:1.75">${idx + 1}</section>`).join(``)
+    const codeInnerHtml = highlightedLines.join(`<br/>`)
+    const codeLinesHtml = `<div style="white-space:pre;min-width:max-content;line-height:1.75">${codeInnerHtml}</div>`
+    const lineNumberColumnStyles = `text-align:right;padding:8px 0;border-right:1px solid rgba(0,0,0,0.04);user-select:none;background:var(--code-bg,transparent);`
+
+    highlighted = `
+      <section style="display:flex;align-items:flex-start;overflow-x:hidden;overflow-y:auto;width:100%;max-width:100%;padding:0;box-sizing:border-box">
+        <section class="line-numbers" style="${lineNumberColumnStyles}">${lineNumbersHtml}</section>
+        <section class="code-scroll" style="flex:1 1 auto;overflow-x:auto;overflow-y:visible;padding:8px;min-width:0;box-sizing:border-box">${codeLinesHtml}</section>
+      </section>
+    `
+  }
+  else {
+    const rawHighlighted = hljs.highlight(text, { language }).value
+    highlighted = formatHighlightedCode(rawHighlighted, true)
+  }
+
+  return highlighted
+}
+
+export function highlightCodeBlock(codeBlock: Element, language: string, hljs: any): void {
+  const rawCode = codeBlock.getAttribute(`data-raw-code`)
+  const showLineNumber = codeBlock.getAttribute(`data-show-line-number`) === `true`
+
+  if (!rawCode)
+    return
+
+  const text = rawCode.replace(/&quot;/g, `"`)
+
+  const highlighted = highlightAndFormatCode(text, language, hljs, showLineNumber)
+
+  codeBlock.innerHTML = highlighted
+  codeBlock.removeAttribute(`data-language-pending`)
+  codeBlock.removeAttribute(`data-raw-code`)
+  codeBlock.removeAttribute(`data-show-line-number`)
+}
+
+/**
+ * 高亮 DOM 中待处理的代码块
+ * 查找带有 data-language-pending 属性的代码块，动态加载语言后重新高亮
+ * @param hljs highlight.js 实例
+ * @param container 容器元素（可选，默认为 document）
+ */
+export function highlightPendingBlocks(hljs: any, container: Document | Element = document): void {
+  const pendingBlocks = container.querySelectorAll(`code[data-language-pending]`)
+
+  pendingBlocks.forEach((codeBlock) => {
+    const language = codeBlock.getAttribute(`data-language-pending`)
+    if (!language)
+      return
+
+    if (hljs.getLanguage(language)) {
+      // 语言已加载，直接高亮
+      highlightCodeBlock(codeBlock, language, hljs)
+    }
+    else {
+      // 动态加载语言后重新高亮
+      loadAndRegisterLanguage(language, hljs).then(() => {
+        highlightCodeBlock(codeBlock, language, hljs)
+      }).catch(() => {
+        // 加载失败，移除标记
+        codeBlock.removeAttribute(`data-language-pending`)
+        codeBlock.removeAttribute(`data-raw-code`)
+        codeBlock.removeAttribute(`data-show-line-number`)
+      })
+    }
+  })
+}
@@ -0,0 +1,194 @@
+import { spawnSync } from 'node:child_process';
+import process from 'node:process';
+
+function printUsage(exitCode = 0): never {
+  console.log(`Send real paste keystroke (Cmd+V / Ctrl+V) to the frontmost application
+
+This bypasses CDP's synthetic events which websites can detect and ignore.
+
+Usage:
+  npx -y bun paste-from-clipboard.ts [options]
+
+Options:
+  --retries <n>     Number of retry attempts (default: 3)
+  --delay <ms>      Delay between retries in ms (default: 500)
+  --app <name>      Target application to activate first (macOS only)
+  --help            Show this help
+
+Examples:
+  # Simple paste
+  npx -y bun paste-from-clipboard.ts
+
+  # Paste to Chrome with retries
+  npx -y bun paste-from-clipboard.ts --app "Google Chrome" --retries 5
+
+  # Quick paste with shorter delay
+  npx -y bun paste-from-clipboard.ts --delay 200
+`);
+  process.exit(exitCode);
+}
+
+function sleepSync(ms: number): void {
+  Atomics.wait(new Int32Array(new SharedArrayBuffer(4)), 0, 0, ms);
+}
+
+function activateApp(appName: string): boolean {
+  if (process.platform !== 'darwin') return false;
+
+  // Activate and wait for app to be frontmost
+  const script = `
+    tell application "${appName}"
+      activate
+      delay 0.5
+    end tell
+
+    -- Verify app is frontmost
+    tell application "System Events"
+      set frontApp to name of first application process whose frontmost is true
+      if frontApp is not "${appName}" then
+        tell application "${appName}" to activate
+        delay 0.3
+      end if
+    end tell
+  `;
+  const result = spawnSync('osascript', ['-e', script], { stdio: 'pipe' });
+  return result.status === 0;
+}
+
+function pasteMac(retries: number, delayMs: number, targetApp?: string): boolean {
+  for (let i = 0; i < retries; i++) {
+    // Build script that activates app (if specified) and sends keystroke in one atomic operation
+    const script = targetApp
+      ? `
+        tell application "${targetApp}"
+          activate
+        end tell
+        delay 0.3
+        tell application "System Events"
+          keystroke "v" using command down
+        end tell
+      `
+      : `
+        tell application "System Events"
+          keystroke "v" using command down
+        end tell
+      `;
+
+    const result = spawnSync('osascript', ['-e', script], { stdio: 'pipe' });
+    if (result.status === 0) {
+      return true;
+    }
+
+    const stderr = result.stderr?.toString().trim();
+    if (stderr) {
+      console.error(`[paste] osascript error: ${stderr}`);
+    }
+
+    if (i < retries - 1) {
+      console.error(`[paste] Attempt ${i + 1}/${retries} failed, retrying in ${delayMs}ms...`);
+      sleepSync(delayMs);
+    }
+  }
+  return false;
+}
+
+function pasteLinux(retries: number, delayMs: number): boolean {
+  // Try xdotool first (X11), then ydotool (Wayland)
+  const tools = [
+    { cmd: 'xdotool', args: ['key', 'ctrl+v'] },
+    { cmd: 'ydotool', args: ['key', '29:1', '47:1', '47:0', '29:0'] }, // Ctrl down, V down, V up, Ctrl up
+  ];
+
+  for (const tool of tools) {
+    const which = spawnSync('which', [tool.cmd], { stdio: 'pipe' });
+    if (which.status !== 0) continue;
+
+    for (let i = 0; i < retries; i++) {
+      const result = spawnSync(tool.cmd, tool.args, { stdio: 'pipe' });
+      if (result.status === 0) {
+        return true;
+      }
+      if (i < retries - 1) {
+        console.error(`[paste] Attempt ${i + 1}/${retries} failed, retrying in ${delayMs}ms...`);
+        sleepSync(delayMs);
+      }
+    }
+    return false;
+  }
+
+  console.error('[paste] No supported tool found. Install xdotool (X11) or ydotool (Wayland).');
+  return false;
+}
+
+function pasteWindows(retries: number, delayMs: number): boolean {
+  const ps = `
+    Add-Type -AssemblyName System.Windows.Forms
+    [System.Windows.Forms.SendKeys]::SendWait("^v")
+  `;
+
+  for (let i = 0; i < retries; i++) {
+    const result = spawnSync('powershell.exe', ['-NoProfile', '-Command', ps], { stdio: 'pipe' });
+    if (result.status === 0) {
+      return true;
+    }
+    if (i < retries - 1) {
+      console.error(`[paste] Attempt ${i + 1}/${retries} failed, retrying in ${delayMs}ms...`);
+      sleepSync(delayMs);
+    }
+  }
+  return false;
+}
+
+function paste(retries: number, delayMs: number, targetApp?: string): boolean {
+  switch (process.platform) {
+    case 'darwin':
+      return pasteMac(retries, delayMs, targetApp);
+    case 'linux':
+      return pasteLinux(retries, delayMs);
+    case 'win32':
+      return pasteWindows(retries, delayMs);
+    default:
+      console.error(`[paste] Unsupported platform: ${process.platform}`);
+      return false;
+  }
+}
+
+async function main(): Promise<void> {
+  const args = process.argv.slice(2);
+
+  let retries = 3;
+  let delayMs = 500;
+  let targetApp: string | undefined;
+
+  for (let i = 0; i < args.length; i++) {
+    const arg = args[i] ?? '';
+    if (arg === '--help' || arg === '-h') {
+      printUsage(0);
+    }
+    if (arg === '--retries' && args[i + 1]) {
+      retries = parseInt(args[++i]!, 10) || 3;
+    } else if (arg === '--delay' && args[i + 1]) {
+      delayMs = parseInt(args[++i]!, 10) || 500;
+    } else if (arg === '--app' && args[i + 1]) {
+      targetApp = args[++i];
+    } else if (arg.startsWith('-')) {
+      console.error(`Unknown option: ${arg}`);
+      printUsage(1);
+    }
+  }
+
+  if (targetApp) {
+    console.log(`[paste] Target app: ${targetApp}`);
+  }
+  console.log(`[paste] Sending paste keystroke (retries=${retries}, delay=${delayMs}ms)...`);
+  const success = paste(retries, delayMs, targetApp);
+
+  if (success) {
+    console.log('[paste] Paste keystroke sent successfully');
+  } else {
+    console.error('[paste] Failed to send paste keystroke');
+    process.exit(1);
+  }
+}
+
+await main();
@@ -0,0 +1,335 @@
+import { execSync, spawnSync } from 'node:child_process';
+import fs from 'node:fs';
+import path from 'node:path';
+import process from 'node:process';
+
+const WECHAT_URL = 'https://mp.weixin.qq.com/';
+const SESSION = 'wechat-post';
+
+function sleep(ms: number): Promise<void> {
+  return new Promise((resolve) => setTimeout(resolve, ms));
+}
+
+function ab(cmd: string, json = false): string {
+  const fullCmd = `agent-browser --session ${SESSION} ${cmd}${json ? ' --json' : ''}`;
+  console.log(`[ab] ${fullCmd}`);
+  try {
+    const result = execSync(fullCmd, { encoding: 'utf8', stdio: ['pipe', 'pipe', 'pipe'] });
+    return result.trim();
+  } catch (e: unknown) {
+    const err = e as { stdout?: string; stderr?: string; message?: string };
+    console.error(`[ab] Error: ${err.stderr || err.message}`);
+    return err.stdout || '';
+  }
+}
+
+function abRaw(args: string[]): { success: boolean; output: string } {
+  const result = spawnSync('agent-browser', ['--session', SESSION, ...args], {
+    encoding: 'utf8',
+    stdio: ['pipe', 'pipe', 'pipe']
+  });
+  return {
+    success: result.status === 0,
+    output: result.stdout || result.stderr || ''
+  };
+}
+
+interface SnapshotElement {
+  ref: string;
+  role: string;
+  name: string;
+}
+
+function parseSnapshot(output: string): SnapshotElement[] {
+  const elements: SnapshotElement[] = [];
+  const refPattern = /\[ref=(@?\w+)\]/g;
+  const lines = output.split('\n');
+
+  for (const line of lines) {
+    const match = line.match(/\[ref=([@\w]+)\]/);
+    if (match) {
+      const ref = match[1].startsWith('@') ? match[1] : `@${match[1]}`;
+      const roleMatch = line.match(/^-\s+(\w+)/);
+      const nameMatch = line.match(/"([^"]+)"/);
+      elements.push({
+        ref,
+        role: roleMatch?.[1] || 'unknown',
+        name: nameMatch?.[1] || ''
+      });
+    }
+  }
+  return elements;
+}
+
+function findElementByText(snapshot: string, text: string): string | null {
+  const lines = snapshot.split('\n');
+  for (const line of lines) {
+    if (line.includes(`"${text}"`) || line.includes(text)) {
+      const match = line.match(/\[ref=([@\w]+)\]/);
+      if (match) {
+        return match[1].startsWith('@') ? match[1] : `@${match[1]}`;
+      }
+    }
+  }
+  return null;
+}
+
+function findElementBySelector(snapshot: string, selector: string): string | null {
+  return null;
+}
+
+interface WeChatOptions {
+  title: string;
+  content: string;
+  images: string[];
+  submit?: boolean;
+  keepOpen?: boolean;
+}
+
+async function postToWeChat(options: WeChatOptions): Promise<void> {
+  const { title, content, images, submit = false, keepOpen = true } = options;
+
+  if (title.length > 20) throw new Error(`Title too long: ${title.length} chars (max 20)`);
+  if (content.length > 1000) throw new Error(`Content too long: ${content.length} chars (max 1000)`);
+  if (images.length === 0) throw new Error('At least one image is required');
+
+  const absoluteImages = images.map(p => path.isAbsolute(p) ? p : path.resolve(process.cwd(), p));
+  for (const img of absoluteImages) {
+    if (!fs.existsSync(img)) throw new Error(`Image not found: ${img}`);
+  }
+
+  console.log('[wechat] Opening WeChat Official Account...');
+  ab(`open ${WECHAT_URL} --headed`);
+  await sleep(5000);
+
+  console.log('[wechat] Checking login status...');
+  let url = ab('get url');
+  console.log(`[wechat] Current URL: ${url}`);
+
+  const waitForLogin = async (timeoutMs = 120_000): Promise<boolean> => {
+    const start = Date.now();
+    while (Date.now() - start < timeoutMs) {
+      url = ab('get url');
+      if (url.includes('/cgi-bin/home')) return true;
+      console.log('[wechat] Waiting for login...');
+      await sleep(3000);
+    }
+    return false;
+  };
+
+  if (!url.includes('/cgi-bin/home')) {
+    console.log('[wechat] Not logged in. Please scan QR code...');
+    const loggedIn = await waitForLogin();
+    if (!loggedIn) throw new Error('Login timeout');
+  }
+  console.log('[wechat] Logged in.');
+  await sleep(2000);
+
+  console.log('[wechat] Getting page snapshot...');
+  let snapshot = ab('snapshot');
+  console.log(snapshot);
+
+  console.log('[wechat] Looking for "图文" menu...');
+  const tuWenRef = findElementByText(snapshot, '图文');
+
+  if (!tuWenRef) {
+    console.log('[wechat] Using eval to find and click menu...');
+    ab(`eval "document.querySelectorAll('.new-creation__menu .new-creation__menu-item')[2].click()"`);
+  } else {
+    console.log(`[wechat] Clicking menu ref: ${tuWenRef}`);
+    ab(`click ${tuWenRef}`);
+  }
+
+  await sleep(4000);
+
+  console.log('[wechat] Checking for new tab...');
+  const tabsOutput = ab('tab');
+  console.log(`[wechat] Tabs: ${tabsOutput}`);
+
+  const tabLines = tabsOutput.split('\n');
+  const editorTabLine = tabLines.find(l => l.includes('appmsg') || (!l.includes('cgi-bin/home') && l.includes('mp.weixin.qq.com')));
+
+  if (tabLines.length > 1) {
+    const tabMatch = tabsOutput.match(/\[(\d+)\].*(?:appmsg|edit)/i);
+    if (tabMatch) {
+      console.log(`[wechat] Switching to editor tab ${tabMatch[1]}...`);
+      ab(`tab ${tabMatch[1]}`);
+    } else {
+      const lastTabMatch = tabsOutput.match(/\[(\d+)\]/g);
+      if (lastTabMatch && lastTabMatch.length > 1) {
+        const lastTab = lastTabMatch[lastTabMatch.length - 1].match(/\d+/)?.[0];
+        if (lastTab) {
+          console.log(`[wechat] Switching to last tab ${lastTab}...`);
+          ab(`tab ${lastTab}`);
+        }
+      }
+    }
+  }
+
+  await sleep(3000);
+
+  url = ab('get url');
+  console.log(`[wechat] Editor URL: ${url}`);
+
+  console.log('[wechat] Getting editor snapshot...');
+  snapshot = ab('snapshot');
+  console.log(snapshot.substring(0, 2000));
+
+  console.log('[wechat] Uploading images...');
+  const fileInputSelector = '.js_upload_btn_container input[type=file]';
+
+  ab(`eval "document.querySelector('${fileInputSelector}').style.display = 'block'"`);
+  await sleep(500);
+
+  const uploadResult = abRaw(['upload', `"${fileInputSelector}"`, ...absoluteImages]);
+  console.log(`[wechat] Upload result: ${uploadResult.output}`);
+
+  if (!uploadResult.success) {
+    console.log('[wechat] Using alternative upload method...');
+    for (const img of absoluteImages) {
+      console.log(`[wechat] Uploading: ${img}`);
+      ab(`eval "
+        const input = document.querySelector('${fileInputSelector}');
+        if (input) {
+          const dt = new DataTransfer();
+          fetch('file://${img}').then(r => r.blob()).then(b => {
+            const file = new File([b], '${path.basename(img)}', { type: 'image/png' });
+            dt.items.add(file);
+            input.files = dt.files;
+            input.dispatchEvent(new Event('change', { bubbles: true }));
+          });
+        }
+      "`);
+      await sleep(2000);
+    }
+  }
+
+  console.log('[wechat] Waiting for uploads to complete...');
+  await sleep(10000);
+
+  console.log('[wechat] Filling title...');
+  snapshot = ab('snapshot -i');
+  const titleRef = findElementByText(snapshot, 'title') || findElementByText(snapshot, '标题');
+
+  if (titleRef) {
+    ab(`fill ${titleRef} "${title.replace(/"/g, '\\"')}"`);
+  } else {
+    ab(`eval "const t = document.querySelector('#title'); if(t) { t.value = '${title.replace(/'/g, "\\'")}'; t.dispatchEvent(new Event('input', {bubbles: true})); }"`);
+  }
+  await sleep(500);
+
+  console.log('[wechat] Clicking on content editor...');
+  const editorRef = findElementByText(snapshot, 'js_pmEditorArea') || findElementByText(snapshot, 'textbox');
+
+  if (editorRef) {
+    ab(`click ${editorRef}`);
+  } else {
+    ab(`eval "document.querySelector('.js_pmEditorArea')?.click()"`);
+  }
+  await sleep(500);
+
+  console.log('[wechat] Typing content...');
+  const lines = content.split('\n');
+  for (let i = 0; i < lines.length; i++) {
+    const line = lines[i];
+    if (line.length > 0) {
+      const escapedLine = line.replace(/"/g, '\\"').replace(/'/g, "\\'");
+      ab(`eval "document.execCommand('insertText', false, '${escapedLine}')"`);
+    }
+    if (i < lines.length - 1) {
+      ab('press Enter');
+    }
+    await sleep(100);
+  }
+
+  console.log('[wechat] Content typed.');
+  await sleep(1000);
+
+  if (submit) {
+    console.log('[wechat] Saving as draft...');
+    const submitRef = findElementByText(snapshot, 'js_submit') || findElementByText(snapshot, '保存');
+    if (submitRef) {
+      ab(`click ${submitRef}`);
+    } else {
+      ab(`eval "document.querySelector('#js_submit')?.click()"`);
+    }
+    await sleep(3000);
+    console.log('[wechat] Draft saved!');
+  } else {
+    console.log('[wechat] Article composed (preview mode). Add --submit to save as draft.');
+  }
+
+  if (!keepOpen) {
+    console.log('[wechat] Closing browser...');
+    ab('close');
+  } else {
+    console.log('[wechat] Done. Browser window left open.');
+  }
+}
+
+function printUsage(): never {
+  console.log(`Post to WeChat Official Account using agent-browser
+
+Usage:
+  npx -y bun wechat-agent-browser.ts [options]
+
+Options:
+  --title <text>   Article title (max 20 chars, required)
+  --content <text> Article content (max 1000 chars, required)
+  --image <path>   Add image (can be repeated, 1+ images, required)
+  --submit         Save as draft (default: preview only)
+  --close          Close browser after operation (default: keep open)
+  --help           Show this help
+
+Examples:
+  npx -y bun wechat-agent-browser.ts --title "测试" --content "内容" --image ./photo.png
+  npx -y bun wechat-agent-browser.ts --title "测试" --content "内容" --image a.png --image b.png --submit
+`);
+  process.exit(0);
+}
+
+async function main(): Promise<void> {
+  const args = process.argv.slice(2);
+  if (args.includes('--help') || args.includes('-h')) printUsage();
+
+  const images: string[] = [];
+  let submit = false;
+  let keepOpen = true;
+  let title: string | undefined;
+  let content: string | undefined;
+
+  for (let i = 0; i < args.length; i++) {
+    const arg = args[i]!;
+    if (arg === '--image' && args[i + 1]) {
+      images.push(args[++i]!);
+    } else if (arg === '--title' && args[i + 1]) {
+      title = args[++i];
+    } else if (arg === '--content' && args[i + 1]) {
+      content = args[++i];
+    } else if (arg === '--submit') {
+      submit = true;
+    } else if (arg === '--close') {
+      keepOpen = false;
+    }
+  }
+
+  if (!title) {
+    console.error('Error: --title is required');
+    process.exit(1);
+  }
+  if (!content) {
+    console.error('Error: --content is required');
+    process.exit(1);
+  }
+  if (images.length === 0) {
+    console.error('Error: At least one --image is required');
+    process.exit(1);
+  }
+
+  await postToWeChat({ title, content, images, submit, keepOpen });
+}
+
+await main().catch((err) => {
+  console.error(`Error: ${err instanceof Error ? err.message : String(err)}`);
+  process.exit(1);
+});
@@ -0,0 +1,445 @@
+import fs from 'node:fs';
+import path from 'node:path';
+import { spawnSync } from 'node:child_process';
+import process from 'node:process';
+import { launchChrome, getPageSession, waitForNewTab, clickElement, typeText, evaluate, sleep, type ChromeSession, type CdpConnection } from './cdp.ts';
+
+const WECHAT_URL = 'https://mp.weixin.qq.com/';
+
+interface ImageInfo {
+  placeholder: string;
+  localPath: string;
+  originalPath: string;
+}
+
+interface ArticleOptions {
+  title: string;
+  content?: string;
+  htmlFile?: string;
+  markdownFile?: string;
+  theme?: string;
+  author?: string;
+  summary?: string;
+  images?: string[];
+  contentImages?: ImageInfo[];
+  submit?: boolean;
+  profileDir?: string;
+}
+
+async function waitForLogin(session: ChromeSession, timeoutMs = 120_000): Promise<boolean> {
+  const start = Date.now();
+  while (Date.now() - start < timeoutMs) {
+    const url = await evaluate<string>(session, 'window.location.href');
+    if (url.includes('/cgi-bin/home')) return true;
+    await sleep(2000);
+  }
+  return false;
+}
+
+async function clickMenuByText(session: ChromeSession, text: string): Promise<void> {
+  console.log(`[wechat] Clicking "${text}" menu...`);
+  const posResult = await session.cdp.send<{ result: { value: string } }>('Runtime.evaluate', {
+    expression: `
+      (function() {
+        const items = document.querySelectorAll('.new-creation__menu .new-creation__menu-item');
+        for (const item of items) {
+          const title = item.querySelector('.new-creation__menu-title');
+          if (title && title.textContent?.trim() === '${text}') {
+            item.scrollIntoView({ block: 'center' });
+            const rect = item.getBoundingClientRect();
+            return JSON.stringify({ x: rect.x + rect.width / 2, y: rect.y + rect.height / 2 });
+          }
+        }
+        return 'null';
+      })()
+    `,
+    returnByValue: true,
+  }, { sessionId: session.sessionId });
+
+  if (posResult.result.value === 'null') throw new Error(`Menu "${text}" not found`);
+  const pos = JSON.parse(posResult.result.value);
+
+  await session.cdp.send('Input.dispatchMouseEvent', { type: 'mousePressed', x: pos.x, y: pos.y, button: 'left', clickCount: 1 }, { sessionId: session.sessionId });
+  await sleep(100);
+  await session.cdp.send('Input.dispatchMouseEvent', { type: 'mouseReleased', x: pos.x, y: pos.y, button: 'left', clickCount: 1 }, { sessionId: session.sessionId });
+}
+
+async function copyImageToClipboard(imagePath: string): Promise<void> {
+  const scriptDir = path.dirname(new URL(import.meta.url).pathname);
+  const copyScript = path.join(scriptDir, './copy-to-clipboard.ts');
+  const result = spawnSync('npx', ['-y', 'bun', copyScript, 'image', imagePath], { stdio: 'inherit' });
+  if (result.status !== 0) throw new Error(`Failed to copy image: ${imagePath}`);
+}
+
+async function pasteInEditor(session: ChromeSession): Promise<void> {
+  const modifiers = process.platform === 'darwin' ? 4 : 2;
+  await session.cdp.send('Input.dispatchKeyEvent', { type: 'keyDown', key: 'v', code: 'KeyV', modifiers, windowsVirtualKeyCode: 86 }, { sessionId: session.sessionId });
+  await sleep(50);
+  await session.cdp.send('Input.dispatchKeyEvent', { type: 'keyUp', key: 'v', code: 'KeyV', modifiers, windowsVirtualKeyCode: 86 }, { sessionId: session.sessionId });
+}
+
+async function copyHtmlFromBrowser(cdp: CdpConnection, htmlFilePath: string): Promise<void> {
+  const absolutePath = path.isAbsolute(htmlFilePath) ? htmlFilePath : path.resolve(process.cwd(), htmlFilePath);
+  const fileUrl = `file://${absolutePath}`;
+
+  console.log(`[wechat] Opening HTML file in new tab: ${fileUrl}`);
+
+  const { targetId } = await cdp.send<{ targetId: string }>('Target.createTarget', { url: fileUrl });
+  const { sessionId } = await cdp.send<{ sessionId: string }>('Target.attachToTarget', { targetId, flatten: true });
+
+  await cdp.send('Page.enable', {}, { sessionId });
+  await cdp.send('Runtime.enable', {}, { sessionId });
+  await sleep(2000);
+
+  console.log('[wechat] Selecting #output content...');
+  await cdp.send<{ result: { value: unknown } }>('Runtime.evaluate', {
+    expression: `
+      (function() {
+        const output = document.querySelector('#output') || document.body;
+        const range = document.createRange();
+        range.selectNodeContents(output);
+        const selection = window.getSelection();
+        selection.removeAllRanges();
+        selection.addRange(range);
+        return true;
+      })()
+    `,
+    returnByValue: true,
+  }, { sessionId });
+  await sleep(300);
+
+  console.log('[wechat] Copying with system Cmd+C...');
+  if (process.platform === 'darwin') {
+    spawnSync('osascript', ['-e', 'tell application "System Events" to keystroke "c" using command down']);
+  } else {
+    spawnSync('xdotool', ['key', 'ctrl+c']);
+  }
+  await sleep(1000);
+
+  console.log('[wechat] Closing HTML tab...');
+  await cdp.send('Target.closeTarget', { targetId });
+}
+
+async function pasteFromClipboardInEditor(): Promise<void> {
+  if (process.platform === 'darwin') {
+    spawnSync('osascript', ['-e', 'tell application "System Events" to keystroke "v" using command down']);
+  } else {
+    spawnSync('xdotool', ['key', 'ctrl+v']);
+  }
+  await sleep(1000);
+}
+
+async function parseMarkdownWithPlaceholders(markdownPath: string, theme?: string): Promise<{ title: string; author: string; summary: string; htmlPath: string; contentImages: ImageInfo[] }> {
+  const scriptDir = path.dirname(new URL(import.meta.url).pathname);
+  const mdToWechatScript = path.join(scriptDir, 'md-to-wechat.ts');
+  const args = ['-y', 'bun', mdToWechatScript, markdownPath];
+  if (theme) args.push('--theme', theme);
+
+  const result = spawnSync('npx', args, { stdio: ['inherit', 'pipe', 'pipe'] });
+  if (result.status !== 0) {
+    const stderr = result.stderr?.toString() || '';
+    throw new Error(`Failed to parse markdown: ${stderr}`);
+  }
+
+  const output = result.stdout.toString();
+  return JSON.parse(output);
+}
+
+function parseHtmlMeta(htmlPath: string): { title: string; author: string; summary: string } {
+  const content = fs.readFileSync(htmlPath, 'utf-8');
+
+  let title = '';
+  const titleMatch = content.match(/<title>([^<]+)<\/title>/i);
+  if (titleMatch) title = titleMatch[1]!;
+
+  let author = '';
+  const authorMatch = content.match(/<meta\s+name=["']author["']\s+content=["']([^"']+)["']/i);
+  if (authorMatch) author = authorMatch[1]!;
+
+  let summary = '';
+  const descMatch = content.match(/<meta\s+name=["']description["']\s+content=["']([^"']+)["']/i);
+  if (descMatch) summary = descMatch[1]!;
+
+  if (!summary) {
+    const firstPMatch = content.match(/<p[^>]*>([^<]+)<\/p>/i);
+    if (firstPMatch) {
+      const text = firstPMatch[1]!.replace(/<[^>]+>/g, '').trim();
+      if (text.length > 20) {
+        summary = text.length > 120 ? text.slice(0, 117) + '...' : text;
+      }
+    }
+  }
+
+  return { title, author, summary };
+}
+
+async function selectAndReplacePlaceholder(session: ChromeSession, placeholder: string): Promise<boolean> {
+  const result = await session.cdp.send<{ result: { value: boolean } }>('Runtime.evaluate', {
+    expression: `
+      (function() {
+        const editor = document.querySelector('.ProseMirror');
+        if (!editor) return false;
+
+        const walker = document.createTreeWalker(editor, NodeFilter.SHOW_TEXT, null, false);
+        let node;
+
+        while ((node = walker.nextNode())) {
+          const text = node.textContent || '';
+          const idx = text.indexOf(${JSON.stringify(placeholder)});
+          if (idx !== -1) {
+            node.parentElement.scrollIntoView({ behavior: 'smooth', block: 'center' });
+
+            const range = document.createRange();
+            range.setStart(node, idx);
+            range.setEnd(node, idx + ${placeholder.length});
+            const sel = window.getSelection();
+            sel.removeAllRanges();
+            sel.addRange(range);
+            return true;
+          }
+        }
+        return false;
+      })()
+    `,
+    returnByValue: true,
+  }, { sessionId: session.sessionId });
+
+  return result.result.value;
+}
+
+async function pressDeleteKey(session: ChromeSession): Promise<void> {
+  await session.cdp.send('Input.dispatchKeyEvent', { type: 'keyDown', key: 'Backspace', code: 'Backspace', windowsVirtualKeyCode: 8 }, { sessionId: session.sessionId });
+  await sleep(50);
+  await session.cdp.send('Input.dispatchKeyEvent', { type: 'keyUp', key: 'Backspace', code: 'Backspace', windowsVirtualKeyCode: 8 }, { sessionId: session.sessionId });
+}
+
+export async function postArticle(options: ArticleOptions): Promise<void> {
+  const { title, content, htmlFile, markdownFile, theme, author, summary, images = [], submit = false, profileDir } = options;
+  let { contentImages = [] } = options;
+  let effectiveTitle = title || '';
+  let effectiveAuthor = author || '';
+  let effectiveSummary = summary || '';
+  let effectiveHtmlFile = htmlFile;
+
+  if (markdownFile) {
+    console.log(`[wechat] Parsing markdown: ${markdownFile}`);
+    const parsed = await parseMarkdownWithPlaceholders(markdownFile, theme);
+    effectiveTitle = effectiveTitle || parsed.title;
+    effectiveAuthor = effectiveAuthor || parsed.author;
+    effectiveSummary = effectiveSummary || parsed.summary;
+    effectiveHtmlFile = parsed.htmlPath;
+    contentImages = parsed.contentImages;
+    console.log(`[wechat] Title: ${effectiveTitle || '(empty)'}`);
+    console.log(`[wechat] Author: ${effectiveAuthor || '(empty)'}`);
+    console.log(`[wechat] Summary: ${effectiveSummary || '(empty)'}`);
+    console.log(`[wechat] Found ${contentImages.length} images to insert`);
+  } else if (htmlFile && fs.existsSync(htmlFile)) {
+    console.log(`[wechat] Parsing HTML: ${htmlFile}`);
+    const meta = parseHtmlMeta(htmlFile);
+    effectiveTitle = effectiveTitle || meta.title;
+    effectiveAuthor = effectiveAuthor || meta.author;
+    effectiveSummary = effectiveSummary || meta.summary;
+    effectiveHtmlFile = htmlFile;
+    console.log(`[wechat] Title: ${effectiveTitle || '(empty)'}`);
+    console.log(`[wechat] Author: ${effectiveAuthor || '(empty)'}`);
+    console.log(`[wechat] Summary: ${effectiveSummary || '(empty)'}`);
+  }
+
+  if (effectiveTitle && effectiveTitle.length > 64) throw new Error(`Title too long: ${effectiveTitle.length} chars (max 64)`);
+  if (!content && !effectiveHtmlFile) throw new Error('Either --content, --html, or --markdown is required');
+
+  const { cdp, chrome } = await launchChrome(WECHAT_URL, profileDir);
+
+  try {
+    console.log('[wechat] Waiting for page load...');
+    await sleep(3000);
+
+    let session = await getPageSession(cdp, 'mp.weixin.qq.com');
+
+    const url = await evaluate<string>(session, 'window.location.href');
+    if (!url.includes('/cgi-bin/home')) {
+      console.log('[wechat] Not logged in. Please scan QR code...');
+      const loggedIn = await waitForLogin(session);
+      if (!loggedIn) throw new Error('Login timeout');
+    }
+    console.log('[wechat] Logged in.');
+    await sleep(2000);
+
+    const targets = await cdp.send<{ targetInfos: Array<{ targetId: string; url: string; type: string }> }>('Target.getTargets');
+    const initialIds = new Set(targets.targetInfos.map(t => t.targetId));
+
+    await clickMenuByText(session, '文章');
+    await sleep(3000);
+
+    const editorTargetId = await waitForNewTab(cdp, initialIds, 'mp.weixin.qq.com');
+    console.log('[wechat] Editor tab opened.');
+
+    const { sessionId } = await cdp.send<{ sessionId: string }>('Target.attachToTarget', { targetId: editorTargetId, flatten: true });
+    session = { cdp, sessionId, targetId: editorTargetId };
+
+    await cdp.send('Page.enable', {}, { sessionId });
+    await cdp.send('Runtime.enable', {}, { sessionId });
+    await cdp.send('DOM.enable', {}, { sessionId });
+
+    await sleep(3000);
+
+    if (effectiveTitle) {
+      console.log('[wechat] Filling title...');
+      await evaluate(session, `document.querySelector('#title').value = ${JSON.stringify(effectiveTitle)}; document.querySelector('#title').dispatchEvent(new Event('input', { bubbles: true }));`);
+    }
+
+    if (effectiveAuthor) {
+      console.log('[wechat] Filling author...');
+      await evaluate(session, `document.querySelector('#author').value = ${JSON.stringify(effectiveAuthor)}; document.querySelector('#author').dispatchEvent(new Event('input', { bubbles: true }));`);
+    }
+
+    console.log('[wechat] Clicking on editor...');
+    await clickElement(session, '.ProseMirror');
+    await sleep(500);
+
+    if (effectiveHtmlFile && fs.existsSync(effectiveHtmlFile)) {
+      console.log(`[wechat] Copying HTML content from: ${effectiveHtmlFile}`);
+      await copyHtmlFromBrowser(cdp, effectiveHtmlFile);
+      await sleep(500);
+      console.log('[wechat] Pasting into editor...');
+      await pasteFromClipboardInEditor();
+      await sleep(3000);
+
+      if (contentImages.length > 0) {
+        console.log(`[wechat] Inserting ${contentImages.length} images...`);
+        for (let i = 0; i < contentImages.length; i++) {
+          const img = contentImages[i]!;
+          console.log(`[wechat] [${i + 1}/${contentImages.length}] Processing: ${img.placeholder}`);
+
+          const found = await selectAndReplacePlaceholder(session, img.placeholder);
+          if (!found) {
+            console.warn(`[wechat] Placeholder not found: ${img.placeholder}`);
+            continue;
+          }
+
+          await sleep(500);
+
+          console.log(`[wechat] Copying image: ${path.basename(img.localPath)}`);
+          await copyImageToClipboard(img.localPath);
+          await sleep(300);
+
+          console.log('[wechat] Deleting placeholder with Backspace...');
+          await pressDeleteKey(session);
+          await sleep(200);
+
+          console.log('[wechat] Pasting image...');
+          await pasteFromClipboardInEditor();
+          await sleep(3000);
+        }
+        console.log('[wechat] All images inserted.');
+      }
+    } else if (content) {
+      for (const img of images) {
+        if (fs.existsSync(img)) {
+          console.log(`[wechat] Pasting image: ${img}`);
+          await copyImageToClipboard(img);
+          await sleep(500);
+          await pasteInEditor(session);
+          await sleep(2000);
+        }
+      }
+
+      console.log('[wechat] Typing content...');
+      await typeText(session, content);
+      await sleep(1000);
+    }
+
+    if (effectiveSummary) {
+      console.log(`[wechat] Filling summary: ${effectiveSummary}`);
+      await evaluate(session, `document.querySelector('#js_description').value = ${JSON.stringify(effectiveSummary)}; document.querySelector('#js_description').dispatchEvent(new Event('input', { bubbles: true }));`);
+    }
+
+    console.log('[wechat] Saving as draft...');
+    await evaluate(session, `document.querySelector('#js_submit button').click()`);
+    await sleep(3000);
+
+    const saved = await evaluate<boolean>(session, `!!document.querySelector('.weui-desktop-toast')`);
+    if (saved) {
+      console.log('[wechat] Draft saved successfully!');
+    } else {
+      console.log('[wechat] Waiting for save confirmation...');
+      await sleep(5000);
+    }
+
+    console.log('[wechat] Done. Browser window left open.');
+  } finally {
+    cdp.close();
+  }
+}
+
+function printUsage(): never {
+  console.log(`Post article to WeChat Official Account
+
+Usage:
+  npx -y bun wechat-article.ts [options]
+
+Options:
+  --title <text>     Article title (auto-extracted from markdown)
+  --content <text>   Article content (use with --image)
+  --html <path>      HTML file to paste (alternative to --content)
+  --markdown <path>  Markdown file to convert and post (recommended)
+  --theme <name>     Theme for markdown (default, grace, simple)
+  --author <name>    Author name (default: 宝玉)
+  --summary <text>   Article summary
+  --image <path>     Content image, can repeat (only with --content)
+  --submit           Save as draft
+  --profile <dir>    Chrome profile directory
+
+Examples:
+  npx -y bun wechat-article.ts --markdown article.md
+  npx -y bun wechat-article.ts --markdown article.md --theme grace --submit
+  npx -y bun wechat-article.ts --title "标题" --content "内容" --image img.png
+  npx -y bun wechat-article.ts --title "标题" --html article.html --submit
+
+Markdown mode:
+  Images in markdown are converted to placeholders. After pasting HTML,
+  each placeholder is selected, scrolled into view, deleted, and replaced
+  with the actual image via paste.
+`);
+  process.exit(0);
+}
+
+async function main(): Promise<void> {
+  const args = process.argv.slice(2);
+  if (args.includes('--help') || args.includes('-h')) printUsage();
+
+  const images: string[] = [];
+  let title: string | undefined;
+  let content: string | undefined;
+  let htmlFile: string | undefined;
+  let markdownFile: string | undefined;
+  let theme: string | undefined;
+  let author: string | undefined;
+  let summary: string | undefined;
+  let submit = false;
+  let profileDir: string | undefined;
+
+  for (let i = 0; i < args.length; i++) {
+    const arg = args[i]!;
+    if (arg === '--title' && args[i + 1]) title = args[++i];
+    else if (arg === '--content' && args[i + 1]) content = args[++i];
+    else if (arg === '--html' && args[i + 1]) htmlFile = args[++i];
+    else if (arg === '--markdown' && args[i + 1]) markdownFile = args[++i];
+    else if (arg === '--theme' && args[i + 1]) theme = args[++i];
+    else if (arg === '--author' && args[i + 1]) author = args[++i];
+    else if (arg === '--summary' && args[i + 1]) summary = args[++i];
+    else if (arg === '--image' && args[i + 1]) images.push(args[++i]!);
+    else if (arg === '--submit') submit = true;
+    else if (arg === '--profile' && args[i + 1]) profileDir = args[++i];
+  }
+
+  if (!markdownFile && !htmlFile && !title) { console.error('Error: --title is required (or use --markdown/--html)'); process.exit(1); }
+  if (!markdownFile && !htmlFile && !content) { console.error('Error: --content, --html, or --markdown is required'); process.exit(1); }
+
+  await postArticle({ title: title || '', content, htmlFile, markdownFile, theme, author, summary, images, submit, profileDir });
+}
+
+await main().catch((err) => {
+  console.error(`Error: ${err instanceof Error ? err.message : String(err)}`);
+  process.exit(1);
+});
@@ -0,0 +1,717 @@
+import { spawn } from 'node:child_process';
+import fs from 'node:fs';
+import { mkdir, readdir } from 'node:fs/promises';
+import net from 'node:net';
+import os from 'node:os';
+import path from 'node:path';
+import process from 'node:process';
+
+const WECHAT_URL = 'https://mp.weixin.qq.com/';
+
+interface MarkdownMeta {
+  title: string;
+  author: string;
+  content: string;
+}
+
+function parseMarkdownFile(filePath: string): MarkdownMeta {
+  const text = fs.readFileSync(filePath, 'utf-8');
+  let title = '';
+  let author = '';
+  let content = '';
+
+  const fmMatch = text.match(/^---\r?\n([\s\S]*?)\r?\n---/);
+  if (fmMatch) {
+    const fm = fmMatch[1]!;
+    const titleMatch = fm.match(/^title:\s*(.+)$/m);
+    if (titleMatch) title = titleMatch[1]!.trim().replace(/^["']|["']$/g, '');
+    const authorMatch = fm.match(/^author:\s*(.+)$/m);
+    if (authorMatch) author = authorMatch[1]!.trim().replace(/^["']|["']$/g, '');
+  }
+
+  const bodyText = fmMatch ? text.slice(fmMatch[0].length) : text;
+
+  if (!title) {
+    const h1Match = bodyText.match(/^#\s+(.+)$/m);
+    if (h1Match) title = h1Match[1]!.trim();
+  }
+
+  const lines = bodyText.split('\n');
+  const paragraphs: string[] = [];
+  for (const line of lines) {
+    const trimmed = line.trim();
+    if (!trimmed) continue;
+    if (trimmed.startsWith('#')) continue;
+    if (trimmed.startsWith('![')) continue;
+    if (trimmed.startsWith('---')) continue;
+    paragraphs.push(trimmed);
+    if (paragraphs.join('\n').length > 1200) break;
+  }
+  content = paragraphs.join('\n');
+
+  return { title, author, content };
+}
+
+function compressTitle(title: string, maxLen = 20): string {
+  if (title.length <= maxLen) return title;
+
+  const prefixes = ['如何', '为什么', '什么是', '怎样', '怎么', '关于'];
+  let t = title;
+  for (const p of prefixes) {
+    if (t.startsWith(p) && t.length > maxLen) {
+      t = t.slice(p.length);
+      if (t.length <= maxLen) return t;
+    }
+  }
+
+  const fillers = ['的', '了', '在', '是', '和', '与', '以及', '或者', '或', '还是', '而且', '并且', '但是', '但', '因为', '所以', '如果', '那么', '虽然', '不过', '然而', '——', '…'];
+  for (const f of fillers) {
+    if (t.length <= maxLen) break;
+    t = t.replace(new RegExp(f, 'g'), '');
+  }
+
+  if (t.length > maxLen) t = t.slice(0, maxLen);
+
+  return t;
+}
+
+function compressContent(content: string, maxLen = 1000): string {
+  if (content.length <= maxLen) return content;
+
+  const lines = content.split('\n');
+  const result: string[] = [];
+  let len = 0;
+
+  for (const line of lines) {
+    if (len + line.length + 1 > maxLen) {
+      const remaining = maxLen - len - 1;
+      if (remaining > 20) result.push(line.slice(0, remaining - 3) + '...');
+      break;
+    }
+    result.push(line);
+    len += line.length + 1;
+  }
+
+  return result.join('\n');
+}
+
+async function loadImagesFromDir(dir: string): Promise<string[]> {
+  const entries = await readdir(dir);
+  const images = entries
+    .filter(f => /\.(png|jpg|jpeg|gif|webp)$/i.test(f))
+    .sort()
+    .map(f => path.join(dir, f));
+  return images;
+}
+
+function sleep(ms: number): Promise<void> {
+  return new Promise((resolve) => setTimeout(resolve, ms));
+}
+
+async function getFreePort(): Promise<number> {
+  return 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(): string | undefined {
+  const override = process.env.WECHAT_BROWSER_CHROME_PATH?.trim();
+  if (override && fs.existsSync(override)) return override;
+
+  const candidates: string[] = [];
+  switch (process.platform) {
+    case 'darwin':
+      candidates.push(
+        '/Applications/Google Chrome.app/Contents/MacOS/Google Chrome',
+        '/Applications/Google Chrome Canary.app/Contents/MacOS/Google Chrome Canary',
+        '/Applications/Google Chrome Beta.app/Contents/MacOS/Google Chrome Beta',
+        '/Applications/Chromium.app/Contents/MacOS/Chromium',
+        '/Applications/Microsoft Edge.app/Contents/MacOS/Microsoft Edge',
+      );
+      break;
+    case 'win32':
+      candidates.push(
+        'C:\\Program Files\\Google\\Chrome\\Application\\chrome.exe',
+        'C:\\Program Files (x86)\\Google\\Chrome\\Application\\chrome.exe',
+        'C:\\Program Files\\Microsoft\\Edge\\Application\\msedge.exe',
+        'C:\\Program Files (x86)\\Microsoft\\Edge\\Application\\msedge.exe',
+      );
+      break;
+    default:
+      candidates.push(
+        '/usr/bin/google-chrome',
+        '/usr/bin/google-chrome-stable',
+        '/usr/bin/chromium',
+        '/usr/bin/chromium-browser',
+        '/snap/bin/chromium',
+        '/usr/bin/microsoft-edge',
+      );
+      break;
+  }
+
+  for (const p of candidates) {
+    if (fs.existsSync(p)) return p;
+  }
+  return undefined;
+}
+
+function getDefaultProfileDir(): string {
+  const base = process.env.XDG_DATA_HOME || path.join(os.homedir(), '.local', 'share');
+  return path.join(base, 'wechat-browser-profile');
+}
+
+async function fetchJson<T = unknown>(url: string): Promise<T> {
+  const res = await fetch(url, { redirect: 'follow' });
+  if (!res.ok) throw new Error(`Request failed: ${res.status} ${res.statusText}`);
+  return (await res.json()) as T;
+}
+
+async function waitForChromeDebugPort(port: number, timeoutMs: number): 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`);
+      if (version.webSocketDebuggerUrl) return version.webSocketDebuggerUrl;
+      lastError = new Error('Missing webSocketDebuggerUrl');
+    } catch (error) {
+      lastError = error;
+    }
+    await sleep(200);
+  }
+
+  throw new Error(`Chrome debug port not ready: ${lastError instanceof Error ? lastError.message : String(lastError)}`);
+}
+
+class CdpConnection {
+  private ws: WebSocket;
+  private nextId = 0;
+  private pending = new Map<number, { resolve: (v: unknown) => void; reject: (e: Error) => void; timer: ReturnType<typeof setTimeout> | null }>();
+  private eventHandlers = new Map<string, Set<(params: unknown) => void>>();
+
+  private constructor(ws: WebSocket) {
+    this.ws = ws;
+    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((h) => h(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): 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);
+  }
+
+  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);
+  }
+
+  async send<T = unknown>(method: string, params?: Record<string, unknown>, options?: { sessionId?: string; timeoutMs?: number }): 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 ?? 15_000;
+
+    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 {}
+  }
+}
+
+interface WeChatBrowserOptions {
+  title?: string;
+  content?: string;
+  images?: string[];
+  imagesDir?: string;
+  markdownFile?: string;
+  submit?: boolean;
+  timeoutMs?: number;
+  profileDir?: string;
+  chromePath?: string;
+}
+
+export async function postToWeChat(options: WeChatBrowserOptions): Promise<void> {
+  const { submit = false, timeoutMs = 120_000, profileDir = getDefaultProfileDir() } = options;
+
+  let title = options.title || '';
+  let content = options.content || '';
+  let images = options.images || [];
+
+  if (options.markdownFile) {
+    const absPath = path.isAbsolute(options.markdownFile) ? options.markdownFile : path.resolve(process.cwd(), options.markdownFile);
+    if (!fs.existsSync(absPath)) throw new Error(`Markdown file not found: ${absPath}`);
+    const meta = parseMarkdownFile(absPath);
+    if (!title) title = meta.title;
+    if (!content) content = meta.content;
+    console.log(`[wechat-browser] Parsed markdown: title="${meta.title}", content=${meta.content.length} chars`);
+  }
+
+  if (options.imagesDir) {
+    const absDir = path.isAbsolute(options.imagesDir) ? options.imagesDir : path.resolve(process.cwd(), options.imagesDir);
+    if (!fs.existsSync(absDir)) throw new Error(`Images directory not found: ${absDir}`);
+    images = await loadImagesFromDir(absDir);
+    console.log(`[wechat-browser] Found ${images.length} images in ${absDir}`);
+  }
+
+  if (title.length > 20) {
+    const original = title;
+    title = compressTitle(title, 20);
+    console.log(`[wechat-browser] Title compressed: "${original}" → "${title}"`);
+  }
+
+  if (content.length > 1000) {
+    const original = content.length;
+    content = compressContent(content, 1000);
+    console.log(`[wechat-browser] Content compressed: ${original} → ${content.length} chars`);
+  }
+
+  if (!title) throw new Error('Title is required (use --title or --markdown)');
+  if (!content) throw new Error('Content is required (use --content or --markdown)');
+  if (images.length === 0) throw new Error('At least one image is required (use --image or --images)');
+
+  for (const img of images) {
+    if (!fs.existsSync(img)) throw new Error(`Image not found: ${img}`);
+  }
+
+  const chromePath = options.chromePath ?? findChromeExecutable();
+  if (!chromePath) throw new Error('Chrome not found. Set WECHAT_BROWSER_CHROME_PATH env var.');
+
+  await mkdir(profileDir, { recursive: true });
+
+  const port = await getFreePort();
+  console.log(`[wechat-browser] Launching Chrome (profile: ${profileDir})`);
+
+  const chrome = spawn(chromePath, [
+    `--remote-debugging-port=${port}`,
+    `--user-data-dir=${profileDir}`,
+    '--no-first-run',
+    '--no-default-browser-check',
+    '--disable-blink-features=AutomationControlled',
+    '--start-maximized',
+    WECHAT_URL,
+  ], { stdio: 'ignore' });
+
+  let cdp: CdpConnection | null = null;
+
+  try {
+    const wsUrl = await waitForChromeDebugPort(port, 30_000);
+    cdp = await CdpConnection.connect(wsUrl, 30_000);
+
+    const targets = await cdp.send<{ targetInfos: Array<{ targetId: string; url: string; type: string }> }>('Target.getTargets');
+    let pageTarget = targets.targetInfos.find((t) => t.type === 'page' && t.url.includes('mp.weixin.qq.com'));
+
+    if (!pageTarget) {
+      const { targetId } = await cdp.send<{ targetId: string }>('Target.createTarget', { url: WECHAT_URL });
+      pageTarget = { targetId, url: WECHAT_URL, type: 'page' };
+    }
+
+    let { sessionId } = await cdp.send<{ sessionId: string }>('Target.attachToTarget', { targetId: pageTarget.targetId, flatten: true });
+
+    await cdp.send('Page.enable', {}, { sessionId });
+    await cdp.send('Runtime.enable', {}, { sessionId });
+    await cdp.send('DOM.enable', {}, { sessionId });
+
+    console.log('[wechat-browser] Waiting for page load...');
+    await sleep(3000);
+
+    const checkLoginStatus = async (): Promise<boolean> => {
+      const result = await cdp!.send<{ result: { value: string } }>('Runtime.evaluate', {
+        expression: `window.location.href`,
+        returnByValue: true,
+      }, { sessionId });
+      return result.result.value.includes('/cgi-bin/home');
+    };
+
+    const waitForLogin = async (): Promise<boolean> => {
+      const start = Date.now();
+      while (Date.now() - start < timeoutMs) {
+        if (await checkLoginStatus()) return true;
+        await sleep(2000);
+      }
+      return false;
+    };
+
+    let isLoggedIn = await checkLoginStatus();
+    if (!isLoggedIn) {
+      console.log('[wechat-browser] Not logged in. Please scan QR code to log in...');
+      isLoggedIn = await waitForLogin();
+      if (!isLoggedIn) throw new Error('Timed out waiting for login. Please log in first.');
+    }
+    console.log('[wechat-browser] Logged in.');
+
+    await sleep(2000);
+
+    console.log('[wechat-browser] Looking for "图文" menu...');
+    const menuResult = await cdp.send<{ result: { value: string } }>('Runtime.evaluate', {
+      expression: `
+        const menuItems = document.querySelectorAll('.new-creation__menu .new-creation__menu-item');
+        const count = menuItems.length;
+        const texts = Array.from(menuItems).map(m => m.querySelector('.new-creation__menu-title')?.textContent?.trim() || m.textContent?.trim() || '');
+        JSON.stringify({ count, texts });
+      `,
+      returnByValue: true,
+    }, { sessionId });
+    console.log(`[wechat-browser] Menu items: ${menuResult.result.value}`);
+
+    const getTargets = async () => {
+      return await cdp!.send<{ targetInfos: Array<{ targetId: string; url: string; type: string }> }>('Target.getTargets');
+    };
+
+    const initialTargets = await getTargets();
+    const initialIds = new Set(initialTargets.targetInfos.map(t => t.targetId));
+    console.log(`[wechat-browser] Initial targets count: ${initialTargets.targetInfos.length}`);
+
+    console.log('[wechat-browser] Finding "图文" menu position...');
+    const menuPos = await cdp.send<{ result: { value: string } }>('Runtime.evaluate', {
+      expression: `
+        (function() {
+          const menuItems = document.querySelectorAll('.new-creation__menu .new-creation__menu-item');
+          console.log('Found menu items:', menuItems.length);
+          for (const item of menuItems) {
+            const title = item.querySelector('.new-creation__menu-title');
+            const text = title?.textContent?.trim() || '';
+            console.log('Menu item text:', text);
+            if (text === '图文') {
+              item.scrollIntoView({ block: 'center' });
+              const rect = item.getBoundingClientRect();
+              console.log('Found 图文，rect:', JSON.stringify(rect));
+              return JSON.stringify({ x: rect.x + rect.width / 2, y: rect.y + rect.height / 2, width: rect.width, height: rect.height });
+            }
+          }
+          return 'null';
+        })()
+      `,
+      returnByValue: true,
+    }, { sessionId });
+    console.log(`[wechat-browser] Menu position: ${menuPos.result.value}`);
+
+    const pos = menuPos.result.value !== 'null' ? JSON.parse(menuPos.result.value) : null;
+    if (!pos) throw new Error('图文 menu not found or not visible');
+
+    console.log('[wechat-browser] Clicking "图文" menu with mouse events...');
+    await cdp.send('Input.dispatchMouseEvent', {
+      type: 'mousePressed',
+      x: pos.x,
+      y: pos.y,
+      button: 'left',
+      clickCount: 1,
+    }, { sessionId });
+    await sleep(100);
+    await cdp.send('Input.dispatchMouseEvent', {
+      type: 'mouseReleased',
+      x: pos.x,
+      y: pos.y,
+      button: 'left',
+      clickCount: 1,
+    }, { sessionId });
+
+    console.log('[wechat-browser] Waiting for editor...');
+    await sleep(3000);
+
+    const waitForEditor = async (): Promise<{ targetId: string; isNewTab: boolean } | null> => {
+      const start = Date.now();
+
+      while (Date.now() - start < 30_000) {
+        const targets = await getTargets();
+        const pageTargets = targets.targetInfos.filter(t => t.type === 'page');
+
+        for (const t of pageTargets) {
+          console.log(`[wechat-browser] Target: ${t.url}`);
+        }
+
+        const newTab = pageTargets.find(t => !initialIds.has(t.targetId) && t.url.includes('mp.weixin.qq.com'));
+        if (newTab) {
+          console.log(`[wechat-browser] Found new tab: ${newTab.url}`);
+          return { targetId: newTab.targetId, isNewTab: true };
+        }
+
+        const editorTab = pageTargets.find(t => t.url.includes('appmsg'));
+        if (editorTab) {
+          console.log(`[wechat-browser] Found editor tab: ${editorTab.url}`);
+          return { targetId: editorTab.targetId, isNewTab: !initialIds.has(editorTab.targetId) };
+        }
+
+        const currentUrl = await cdp!.send<{ result: { value: string } }>('Runtime.evaluate', {
+          expression: `window.location.href`,
+          returnByValue: true,
+        }, { sessionId });
+        console.log(`[wechat-browser] Current page URL: ${currentUrl.result.value}`);
+
+        if (currentUrl.result.value.includes('appmsg')) {
+          console.log(`[wechat-browser] Current page navigated to editor`);
+          return { targetId: pageTarget!.targetId, isNewTab: false };
+        }
+
+        await sleep(1000);
+      }
+      return null;
+    };
+
+    const editorInfo = await waitForEditor();
+    if (!editorInfo) {
+      const finalTargets = await getTargets();
+      console.log(`[wechat-browser] Final targets: ${finalTargets.targetInfos.filter(t => t.type === 'page').map(t => t.url).join(', ')}`);
+      throw new Error('Editor not found.');
+    }
+
+    if (editorInfo.isNewTab) {
+      console.log('[wechat-browser] Switching to editor tab...');
+      const editorSession = await cdp.send<{ sessionId: string }>('Target.attachToTarget', { targetId: editorInfo.targetId, flatten: true });
+      sessionId = editorSession.sessionId;
+
+      await cdp.send('Page.enable', {}, { sessionId });
+      await cdp.send('Runtime.enable', {}, { sessionId });
+      await cdp.send('DOM.enable', {}, { sessionId });
+    } else {
+      console.log('[wechat-browser] Editor opened in current page');
+    }
+
+    await cdp.send('Page.enable', {}, { sessionId });
+    await cdp.send('Runtime.enable', {}, { sessionId });
+    await cdp.send('DOM.enable', {}, { sessionId });
+
+    await sleep(2000);
+
+    console.log('[wechat-browser] Uploading all images at once...');
+    const absolutePaths = images.map(p => path.isAbsolute(p) ? p : path.resolve(process.cwd(), p));
+    console.log(`[wechat-browser] Images: ${absolutePaths.join(', ')}`);
+
+    const { root } = await cdp.send<{ root: { nodeId: number } }>('DOM.getDocument', {}, { sessionId });
+    const { nodeId } = await cdp.send<{ nodeId: number }>('DOM.querySelector', {
+      nodeId: root.nodeId,
+      selector: '.js_upload_btn_container input[type=file]',
+    }, { sessionId });
+
+    if (!nodeId) throw new Error('File input not found');
+
+    await cdp.send('DOM.setFileInputFiles', {
+      nodeId,
+      files: absolutePaths,
+    }, { sessionId });
+
+    await sleep(1000);
+
+    console.log('[wechat-browser] Filling title...');
+    await cdp.send('Runtime.evaluate', {
+      expression: `
+        const titleInput = document.querySelector('#title');
+        if (titleInput) {
+          titleInput.value = ${JSON.stringify(title)};
+          titleInput.dispatchEvent(new Event('input', { bubbles: true }));
+        } else {
+          throw new Error('Title input not found');
+        }
+      `,
+    }, { sessionId });
+    await sleep(500);
+
+    console.log('[wechat-browser] Clicking on content editor...');
+    const editorPos = await cdp.send<{ result: { value: string } }>('Runtime.evaluate', {
+      expression: `
+        (function() {
+          const editor = document.querySelector('.js_pmEditorArea');
+          if (editor) {
+            const rect = editor.getBoundingClientRect();
+            return JSON.stringify({ x: rect.x + 50, y: rect.y + 20 });
+          }
+          return 'null';
+        })()
+      `,
+      returnByValue: true,
+    }, { sessionId });
+
+    if (editorPos.result.value === 'null') throw new Error('Content editor not found');
+    const editorClickPos = JSON.parse(editorPos.result.value);
+
+    await cdp.send('Input.dispatchMouseEvent', {
+      type: 'mousePressed',
+      x: editorClickPos.x,
+      y: editorClickPos.y,
+      button: 'left',
+      clickCount: 1,
+    }, { sessionId });
+    await sleep(50);
+    await cdp.send('Input.dispatchMouseEvent', {
+      type: 'mouseReleased',
+      x: editorClickPos.x,
+      y: editorClickPos.y,
+      button: 'left',
+      clickCount: 1,
+    }, { sessionId });
+    await sleep(300);
+
+    console.log('[wechat-browser] Typing content with keyboard simulation...');
+    const lines = content.split('\n');
+    for (let i = 0; i < lines.length; i++) {
+      const line = lines[i];
+      if (line.length > 0) {
+        await cdp.send('Input.insertText', { text: line }, { sessionId });
+      }
+      if (i < lines.length - 1) {
+        await cdp.send('Input.dispatchKeyEvent', {
+          type: 'keyDown',
+          key: 'Enter',
+          code: 'Enter',
+          windowsVirtualKeyCode: 13,
+        }, { sessionId });
+        await cdp.send('Input.dispatchKeyEvent', {
+          type: 'keyUp',
+          key: 'Enter',
+          code: 'Enter',
+          windowsVirtualKeyCode: 13,
+        }, { sessionId });
+      }
+      await sleep(50);
+    }
+    console.log('[wechat-browser] Content typed.');
+    await sleep(500);
+
+    if (submit) {
+      console.log('[wechat-browser] Saving as draft...');
+      await cdp.send('Runtime.evaluate', {
+        expression: `document.querySelector('#js_submit')?.click()`,
+      }, { sessionId });
+      await sleep(3000);
+      console.log('[wechat-browser] Draft saved!');
+    } else {
+      console.log('[wechat-browser] Article composed (preview mode). Add --submit to save as draft.');
+    }
+  } finally {
+    if (cdp) {
+      cdp.close();
+    }
+    console.log('[wechat-browser] Done. Browser window left open.');
+  }
+}
+
+function printUsage(): never {
+  console.log(`Post image-text (图文) to WeChat Official Account
+
+Usage:
+  npx -y bun wechat-browser.ts [options]
+
+Options:
+  --markdown <path>  Markdown file for title/content extraction
+  --images <dir>     Directory containing images (PNG/JPG)
+  --title <text>     Article title (max 20 chars, auto-compressed)
+  --content <text>   Article content (max 1000 chars, auto-compressed)
+  --image <path>     Add image (can be repeated)
+  --submit           Save as draft (default: preview only)
+  --profile <dir>    Chrome profile directory
+  --help             Show this help
+
+Examples:
+  npx -y bun wechat-browser.ts --markdown article.md --images ./photos/
+  npx -y bun wechat-browser.ts --title "测试" --content "内容" --image ./photo.png
+  npx -y bun wechat-browser.ts --markdown article.md --images ./photos/ --submit
+`);
+  process.exit(0);
+}
+
+async function main(): Promise<void> {
+  const args = process.argv.slice(2);
+  if (args.includes('--help') || args.includes('-h')) printUsage();
+
+  const images: string[] = [];
+  let submit = false;
+  let profileDir: string | undefined;
+  let title: string | undefined;
+  let content: string | undefined;
+  let markdownFile: string | undefined;
+  let imagesDir: string | undefined;
+
+  for (let i = 0; i < args.length; i++) {
+    const arg = args[i]!;
+    if (arg === '--image' && args[i + 1]) {
+      images.push(args[++i]!);
+    } else if (arg === '--images' && args[i + 1]) {
+      imagesDir = args[++i];
+    } else if (arg === '--title' && args[i + 1]) {
+      title = args[++i];
+    } else if (arg === '--content' && args[i + 1]) {
+      content = args[++i];
+    } else if (arg === '--markdown' && args[i + 1]) {
+      markdownFile = args[++i];
+    } else if (arg === '--submit') {
+      submit = true;
+    } else if (arg === '--profile' && args[i + 1]) {
+      profileDir = args[++i];
+    }
+  }
+
+  if (!markdownFile && !title) {
+    console.error('Error: --title or --markdown is required');
+    process.exit(1);
+  }
+  if (!markdownFile && !content) {
+    console.error('Error: --content or --markdown is required');
+    process.exit(1);
+  }
+  if (images.length === 0 && !imagesDir) {
+    console.error('Error: --image or --images is required');
+    process.exit(1);
+  }
+
+  await postToWeChat({ title, content, images: images.length > 0 ? images : undefined, imagesDir, markdownFile, submit, profileDir });
+}
+
+await main().catch((err) => {
+  console.error(`Error: ${err instanceof Error ? err.message : String(err)}`);
+  process.exit(1);
+});
@@ -0,0 +1,113 @@
+---
+name: baoyu-post-to-x
+description: 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.
+---
+
+# Post to X (Twitter)
+
+Post content, images, and long-form articles to X using real Chrome browser (bypasses anti-bot detection).
+
+## 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. Replace all `${SKILL_DIR}` in this document with the actual path
+
+**Script Reference**:
+| Script | Purpose |
+|--------|---------|
+| `scripts/x-browser.ts` | Regular posts (text + images) |
+| `scripts/x-article.ts` | Long-form article publishing (Markdown) |
+| `scripts/md-to-html.ts` | Markdown → HTML conversion |
+| `scripts/copy-to-clipboard.ts` | Copy content to clipboard |
+| `scripts/paste-from-clipboard.ts` | Send real paste keystroke |
+
+## Prerequisites
+
+- Google Chrome or Chromium installed
+- `bun` installed (for running scripts)
+- First run: log in to X in the opened browser window
+
+## References
+
+- **Regular Posts**: See `references/regular-posts.md` for manual workflow, troubleshooting, and technical details
+- **X Articles**: See `references/articles.md` for long-form article publishing guide
+
+---
+
+## Regular Posts
+
+Text + up to 4 images.
+
+```bash
+# Preview mode (doesn't post)
+npx -y bun ${SKILL_DIR}/scripts/x-browser.ts "Hello from Claude!" --image ./screenshot.png
+
+# Actually post
+npx -y bun ${SKILL_DIR}/scripts/x-browser.ts "Hello!" --image ./photo.png --submit
+```
+
+> **Note**: `${SKILL_DIR}` represents this skill's installation directory. Agent replaces with actual path at runtime.
+
+**Parameters**:
+| Parameter | Description |
+|-----------|-------------|
+| `<text>` | Post content (positional argument) |
+| `--image <path>` | Image file path (can be repeated, max 4) |
+| `--submit` | Actually post (default: preview only) |
+| `--profile <dir>` | Custom Chrome profile directory |
+
+---
+
+## X Articles
+
+Long-form Markdown articles (requires X Premium).
+
+```bash
+# Preview mode
+npx -y bun ${SKILL_DIR}/scripts/x-article.ts article.md
+
+# With cover image
+npx -y bun ${SKILL_DIR}/scripts/x-article.ts article.md --cover ./cover.jpg
+
+# Publish
+npx -y bun ${SKILL_DIR}/scripts/x-article.ts article.md --submit
+```
+
+**Parameters**:
+| Parameter | Description |
+|-----------|-------------|
+| `<markdown>` | Markdown file path (positional argument) |
+| `--cover <path>` | Cover image path |
+| `--title <text>` | Override article title |
+| `--submit` | Actually publish (default: preview only) |
+
+**Frontmatter** (optional):
+```yaml
+---
+title: My Article Title
+cover_image: /path/to/cover.jpg
+---
+```
+
+---
+
+## Notes
+
+- First run requires manual login (session is saved)
+- Always preview before using `--submit`
+- Browser closes automatically after operation
+- Supports macOS, Linux, and Windows
+
+## Extension Support
+
+Custom configurations via EXTEND.md.
+
+**Check paths** (priority order):
+1. `.baoyu-skills/baoyu-post-to-x/EXTEND.md` (project)
+2. `~/.baoyu-skills/baoyu-post-to-x/EXTEND.md` (user)
+
+If found, load before workflow. Extension content overrides defaults.
@@ -0,0 +1,176 @@
+# X Articles - Detailed Guide
+
+Publish Markdown articles to X Articles editor with rich text formatting and images.
+
+## Prerequisites
+
+- X Premium subscription (required for Articles)
+- Google Chrome installed
+- `bun` installed
+
+## Usage
+
+```bash
+# Publish markdown article (preview mode)
+npx -y bun ${SKILL_DIR}/scripts/x-article.ts article.md
+
+# With custom cover image
+npx -y bun ${SKILL_DIR}/scripts/x-article.ts article.md --cover ./cover.jpg
+
+# Actually publish
+npx -y bun ${SKILL_DIR}/scripts/x-article.ts article.md --submit
+```
+
+## Markdown Format
+
+```markdown
+---
+title: My Article Title
+cover_image: /path/to/cover.jpg
+---
+
+# Title (becomes article title)
+
+Regular paragraph text with **bold** and *italic*.
+
+## Section Header
+
+More content here.
+
+![Image alt text](./image.png)
+
+- List item 1
+- List item 2
+
+1. Numbered item
+2. Another item
+
+> Blockquote text
+
+[Link text](https://example.com)
+
+\`\`\`
+Code blocks become blockquotes (X doesn't support code)
+\`\`\`
+```
+
+## Frontmatter Fields
+
+| Field | Description |
+|-------|-------------|
+| `title` | Article title (or uses first H1) |
+| `cover_image` | Cover image path or URL |
+| `cover` | Alias for cover_image |
+| `image` | Alias for cover_image |
+
+## Image Handling
+
+1. **Cover Image**: First image or `cover_image` from frontmatter
+2. **Remote Images**: Automatically downloaded to temp directory
+3. **Placeholders**: Images in content use `[[IMAGE_PLACEHOLDER_N]]` format
+4. **Insertion**: Placeholders are found, selected, and replaced with actual images
+
+## Markdown to HTML Script
+
+Convert markdown and inspect structure:
+
+```bash
+# Get JSON with all metadata
+npx -y bun ${SKILL_DIR}/scripts/md-to-html.ts article.md
+
+# Output HTML only
+npx -y bun ${SKILL_DIR}/scripts/md-to-html.ts article.md --html-only
+
+# Save HTML to file
+npx -y bun ${SKILL_DIR}/scripts/md-to-html.ts article.md --save-html /tmp/article.html
+```
+
+JSON output:
+```json
+{
+  "title": "Article Title",
+  "coverImage": "/path/to/cover.jpg",
+  "contentImages": [
+    {
+      "placeholder": "[[IMAGE_PLACEHOLDER_1]]",
+      "localPath": "/tmp/x-article-images/img.png",
+      "blockIndex": 5
+    }
+  ],
+  "html": "<p>Content...</p>",
+  "totalBlocks": 20
+}
+```
+
+## Supported Formatting
+
+| Markdown | HTML Output |
+|----------|-------------|
+| `# H1` | Title only (not in body) |
+| `## H2` - `###### H6` | `<h2>` |
+| `**bold**` | `<strong>` |
+| `*italic*` | `<em>` |
+| `[text](url)` | `<a href>` |
+| `> quote` | `<blockquote>` |
+| `` `code` `` | `<code>` |
+| ```` ``` ```` | `<blockquote>` (X limitation) |
+| `- item` | `<ul><li>` |
+| `1. item` | `<ol><li>` |
+| `![](img)` | Image placeholder |
+
+## Workflow
+
+1. **Parse Markdown**: Extract title, cover, content images, generate HTML
+2. **Launch Chrome**: Real browser with CDP, persistent login
+3. **Navigate**: Open `x.com/compose/articles`
+4. **Create Article**: Click create button if on list page
+5. **Upload Cover**: Use file input for cover image
+6. **Fill Title**: Type title into title field
+7. **Paste Content**: Copy HTML to clipboard, paste into editor
+8. **Insert Images**: For each placeholder (reverse order):
+   - Find placeholder text in editor
+   - Select the placeholder
+   - Copy image to clipboard
+   - Paste to replace selection
+9. **Review**: Browser stays open for 60s preview
+10. **Publish**: Only with `--submit` flag
+
+## Example Session
+
+```
+User: /post-to-x article ./blog/my-post.md --cover ./thumbnail.png
+
+Claude:
+1. Parses markdown: title="My Post", 3 content images
+2. Launches Chrome with CDP
+3. Navigates to x.com/compose/articles
+4. Clicks create button
+5. Uploads thumbnail.png as cover
+6. Fills title "My Post"
+7. Pastes HTML content
+8. Inserts 3 images at placeholder positions
+9. Reports: "Article composed. Review and use --submit to publish."
+```
+
+## Troubleshooting
+
+- **No create button**: Ensure X Premium subscription is active
+- **Cover upload fails**: Check file path and format (PNG, JPEG)
+- **Images not inserting**: Verify placeholders exist in pasted content
+- **Content not pasting**: Check HTML clipboard: `npx -y bun ${SKILL_DIR}/scripts/copy-to-clipboard.ts html --file /tmp/test.html`
+
+## How It Works
+
+1. `md-to-html.ts` converts Markdown to HTML:
+   - Extracts frontmatter (title, cover)
+   - Converts markdown to HTML
+   - Replaces images with unique placeholders
+   - Downloads remote images locally
+   - Returns structured JSON
+
+2. `x-article.ts` publishes via CDP:
+   - Launches real Chrome (bypasses detection)
+   - Uses persistent profile (saved login)
+   - Navigates and fills editor via DOM manipulation
+   - Pastes HTML from system clipboard
+   - Finds/selects/replaces each image placeholder
@@ -0,0 +1,100 @@
+# Regular Posts - Detailed Guide
+
+Detailed documentation for posting text and images to X.
+
+## Manual Workflow
+
+If you prefer step-by-step control:
+
+### Step 1: Copy Image to Clipboard
+
+```bash
+npx -y bun ${SKILL_DIR}/scripts/copy-to-clipboard.ts image /path/to/image.png
+```
+
+### Step 2: Paste from Clipboard
+
+```bash
+# Simple paste to frontmost app
+npx -y bun ${SKILL_DIR}/scripts/paste-from-clipboard.ts
+
+# Paste to Chrome with retries
+npx -y bun ${SKILL_DIR}/scripts/paste-from-clipboard.ts --app "Google Chrome" --retries 5
+
+# Quick paste with shorter delay
+npx -y bun ${SKILL_DIR}/scripts/paste-from-clipboard.ts --delay 200
+```
+
+### Step 3: Use Playwright MCP (if Chrome session available)
+
+```bash
+# Navigate
+mcp__playwright__browser_navigate url="https://x.com/compose/post"
+
+# Get element refs
+mcp__playwright__browser_snapshot
+
+# Type text
+mcp__playwright__browser_click element="editor" ref="<ref>"
+mcp__playwright__browser_type element="editor" ref="<ref>" text="Your content"
+
+# Paste image (after copying to clipboard)
+mcp__playwright__browser_press_key key="Meta+v"  # macOS
+# or
+mcp__playwright__browser_press_key key="Control+v"  # Windows/Linux
+
+# Screenshot to verify
+mcp__playwright__browser_take_screenshot filename="preview.png"
+```
+
+## Image Support
+
+- Formats: PNG, JPEG, GIF, WebP
+- Max 4 images per post
+- Images copied to system clipboard, then pasted via keyboard shortcut
+
+## Example Session
+
+```
+User: /post-to-x "Hello from Claude!" --image ./screenshot.png
+
+Claude:
+1. Runs: npx -y bun ${SKILL_DIR}/scripts/x-browser.ts "Hello from Claude!" --image ./screenshot.png
+2. Chrome opens with X compose page
+3. Text is typed into editor
+4. Image is copied to clipboard and pasted
+5. Browser stays open 30s for preview
+6. Reports: "Post composed. Use --submit to post."
+```
+
+## Troubleshooting
+
+- **Chrome not found**: Set `X_BROWSER_CHROME_PATH` environment variable
+- **Not logged in**: First run opens Chrome - log in manually, cookies are saved
+- **Image paste fails**:
+  - Verify clipboard script: `npx -y bun ${SKILL_DIR}/scripts/copy-to-clipboard.ts image <path>`
+  - On macOS, grant "Accessibility" permission to Terminal/iTerm in System Settings > Privacy & Security > Accessibility
+  - Keep Chrome window visible and in front during paste operations
+- **osascript permission denied**: Grant Terminal accessibility permissions in System Preferences
+- **Rate limited**: Wait a few minutes before retrying
+
+## How It Works
+
+The `x-browser.ts` script uses Chrome DevTools Protocol (CDP) to:
+1. Launch real Chrome (not Playwright) with `--disable-blink-features=AutomationControlled`
+2. Use persistent profile directory for saved login sessions
+3. Interact with X via CDP commands (Runtime.evaluate, Input.dispatchKeyEvent)
+4. **Paste images using osascript** (macOS): Sends real Cmd+V keystroke to Chrome, bypassing CDP's synthetic events that X can detect
+
+This approach bypasses X's anti-automation detection that blocks Playwright/Puppeteer.
+
+### Image Paste Mechanism (macOS)
+
+CDP's `Input.dispatchKeyEvent` sends "synthetic" keyboard events that websites can detect. X ignores synthetic paste events for security. The solution:
+
+1. Copy image to system clipboard via Swift/AppKit (`copy-to-clipboard.ts`)
+2. Bring Chrome to front via `osascript`
+3. Send real Cmd+V keystroke via `osascript` and System Events
+4. Wait for upload to complete
+
+This requires Terminal to have "Accessibility" permission in System Settings.
@@ -0,0 +1,380 @@
+import { spawn } from 'node:child_process';
+import fs from 'node:fs';
+import { mkdtemp, rm, writeFile } from 'node:fs/promises';
+import os from 'node:os';
+import path from 'node:path';
+import process from 'node:process';
+
+const SUPPORTED_IMAGE_EXTS = new Set(['.jpg', '.jpeg', '.png', '.gif', '.webp']);
+
+function printUsage(exitCode = 0): never {
+  console.log(`Copy image or HTML to system clipboard
+
+Supports:
+  - Image files (jpg, png, gif, webp) - copies as image data
+  - HTML content - copies as rich text for paste
+
+Usage:
+  # Copy image to clipboard
+  npx -y bun copy-to-clipboard.ts image /path/to/image.jpg
+
+  # Copy HTML to clipboard
+  npx -y bun copy-to-clipboard.ts html "<p>Hello</p>"
+
+  # Copy HTML from file
+  npx -y bun copy-to-clipboard.ts html --file /path/to/content.html
+`);
+  process.exit(exitCode);
+}
+
+function resolvePath(filePath: string): string {
+  return path.isAbsolute(filePath) ? filePath : path.resolve(process.cwd(), filePath);
+}
+
+function inferImageMimeType(imagePath: string): string {
+  const ext = path.extname(imagePath).toLowerCase();
+  switch (ext) {
+    case '.jpg':
+    case '.jpeg':
+      return 'image/jpeg';
+    case '.png':
+      return 'image/png';
+    case '.gif':
+      return 'image/gif';
+    case '.webp':
+      return 'image/webp';
+    default:
+      return 'application/octet-stream';
+  }
+}
+
+type RunResult = { stdout: string; stderr: string; exitCode: number };
+
+async function runCommand(
+  command: string,
+  args: string[],
+  options?: { input?: string | Buffer; allowNonZeroExit?: boolean },
+): Promise<RunResult> {
+  return await new Promise<RunResult>((resolve, reject) => {
+    const child = spawn(command, args, { stdio: ['pipe', 'pipe', 'pipe'] });
+    const stdoutChunks: Buffer[] = [];
+    const stderrChunks: Buffer[] = [];
+
+    child.stdout.on('data', (chunk) => stdoutChunks.push(Buffer.from(chunk)));
+    child.stderr.on('data', (chunk) => stderrChunks.push(Buffer.from(chunk)));
+    child.on('error', reject);
+    child.on('close', (code) => {
+      resolve({
+        stdout: Buffer.concat(stdoutChunks).toString('utf8'),
+        stderr: Buffer.concat(stderrChunks).toString('utf8'),
+        exitCode: code ?? 0,
+      });
+    });
+
+    if (options?.input != null) child.stdin.write(options.input);
+    child.stdin.end();
+  }).then((result) => {
+    if (!options?.allowNonZeroExit && result.exitCode !== 0) {
+      const details = result.stderr.trim() || result.stdout.trim();
+      throw new Error(`Command failed (${command}): exit ${result.exitCode}${details ? `\n${details}` : ''}`);
+    }
+    return result;
+  });
+}
+
+async function commandExists(command: string): Promise<boolean> {
+  if (process.platform === 'win32') {
+    const result = await runCommand('where', [command], { allowNonZeroExit: true });
+    return result.exitCode === 0 && result.stdout.trim().length > 0;
+  }
+  const result = await runCommand('which', [command], { allowNonZeroExit: true });
+  return result.exitCode === 0 && result.stdout.trim().length > 0;
+}
+
+async function runCommandWithFileStdin(command: string, args: string[], filePath: string): Promise<void> {
+  await new Promise<void>((resolve, reject) => {
+    const child = spawn(command, args, { stdio: ['pipe', 'pipe', 'pipe'] });
+    const stderrChunks: Buffer[] = [];
+    const stdoutChunks: Buffer[] = [];
+
+    child.stdout.on('data', (chunk) => stdoutChunks.push(Buffer.from(chunk)));
+    child.stderr.on('data', (chunk) => stderrChunks.push(Buffer.from(chunk)));
+    child.on('error', reject);
+    child.on('close', (code) => {
+      const exitCode = code ?? 0;
+      if (exitCode !== 0) {
+        const details = Buffer.concat(stderrChunks).toString('utf8').trim() || Buffer.concat(stdoutChunks).toString('utf8').trim();
+        reject(
+          new Error(`Command failed (${command}): exit ${exitCode}${details ? `\n${details}` : ''}`),
+        );
+        return;
+      }
+      resolve();
+    });
+
+    fs.createReadStream(filePath).on('error', reject).pipe(child.stdin);
+  });
+}
+
+async function withTempDir<T>(prefix: string, fn: (tempDir: string) => Promise<T>): Promise<T> {
+  const tempDir = await mkdtemp(path.join(os.tmpdir(), prefix));
+  try {
+    return await fn(tempDir);
+  } finally {
+    await rm(tempDir, { recursive: true, force: true });
+  }
+}
+
+function getMacSwiftClipboardSource(): string {
+  return `import AppKit
+import Foundation
+
+func die(_ message: String, _ code: Int32 = 1) -> Never {
+  FileHandle.standardError.write(message.data(using: .utf8)!)
+  exit(code)
+}
+
+if CommandLine.arguments.count < 3 {
+  die("Usage: clipboard.swift <image|html> <path>\\n")
+}
+
+let mode = CommandLine.arguments[1]
+let inputPath = CommandLine.arguments[2]
+let pasteboard = NSPasteboard.general
+pasteboard.clearContents()
+
+switch mode {
+case "image":
+  guard let image = NSImage(contentsOfFile: inputPath) else {
+    die("Failed to load image: \\(inputPath)\\n")
+  }
+  if !pasteboard.writeObjects([image]) {
+    die("Failed to write image to clipboard\\n")
+  }
+
+case "html":
+  let url = URL(fileURLWithPath: inputPath)
+  let data: Data
+  do {
+    data = try Data(contentsOf: url)
+  } catch {
+    die("Failed to read HTML file: \\(inputPath)\\n")
+  }
+
+  _ = pasteboard.setData(data, forType: .html)
+
+  let options: [NSAttributedString.DocumentReadingOptionKey: Any] = [
+    .documentType: NSAttributedString.DocumentType.html,
+    .characterEncoding: String.Encoding.utf8.rawValue
+  ]
+
+  if let attr = try? NSAttributedString(data: data, options: options, documentAttributes: nil) {
+    pasteboard.setString(attr.string, forType: .string)
+    if let rtf = try? attr.data(
+      from: NSRange(location: 0, length: attr.length),
+      documentAttributes: [.documentType: NSAttributedString.DocumentType.rtf]
+    ) {
+      _ = pasteboard.setData(rtf, forType: .rtf)
+    }
+  } else if let html = String(data: data, encoding: .utf8) {
+    pasteboard.setString(html, forType: .string)
+  }
+
+default:
+  die("Unknown mode: \\(mode)\\n")
+}
+`;
+}
+
+async function copyImageMac(imagePath: string): Promise<void> {
+  await withTempDir('copy-to-clipboard-', async (tempDir) => {
+    const swiftPath = path.join(tempDir, 'clipboard.swift');
+    await writeFile(swiftPath, getMacSwiftClipboardSource(), 'utf8');
+    await runCommand('swift', [swiftPath, 'image', imagePath]);
+  });
+}
+
+async function copyHtmlMac(htmlFilePath: string): Promise<void> {
+  await withTempDir('copy-to-clipboard-', async (tempDir) => {
+    const swiftPath = path.join(tempDir, 'clipboard.swift');
+    await writeFile(swiftPath, getMacSwiftClipboardSource(), 'utf8');
+    await runCommand('swift', [swiftPath, 'html', htmlFilePath]);
+  });
+}
+
+async function copyImageLinux(imagePath: string): Promise<void> {
+  const mime = inferImageMimeType(imagePath);
+  if (await commandExists('wl-copy')) {
+    await runCommandWithFileStdin('wl-copy', ['--type', mime], imagePath);
+    return;
+  }
+  if (await commandExists('xclip')) {
+    await runCommand('xclip', ['-selection', 'clipboard', '-t', mime, '-i', imagePath]);
+    return;
+  }
+  throw new Error('No clipboard tool found. Install `wl-clipboard` (wl-copy) or `xclip`.');
+}
+
+async function copyHtmlLinux(htmlFilePath: string): Promise<void> {
+  if (await commandExists('wl-copy')) {
+    await runCommandWithFileStdin('wl-copy', ['--type', 'text/html'], htmlFilePath);
+    return;
+  }
+  if (await commandExists('xclip')) {
+    await runCommand('xclip', ['-selection', 'clipboard', '-t', 'text/html', '-i', htmlFilePath]);
+    return;
+  }
+  throw new Error('No clipboard tool found. Install `wl-clipboard` (wl-copy) or `xclip`.');
+}
+
+async function copyImageWindows(imagePath: string): Promise<void> {
+  const ps = [
+    'param([string]$Path)',
+    'Add-Type -AssemblyName System.Windows.Forms',
+    'Add-Type -AssemblyName System.Drawing',
+    '$img = [System.Drawing.Image]::FromFile($Path)',
+    '[System.Windows.Forms.Clipboard]::SetImage($img)',
+    '$img.Dispose()',
+  ].join('; ');
+  await runCommand('powershell.exe', ['-NoProfile', '-Sta', '-Command', ps, '-Path', imagePath]);
+}
+
+async function copyHtmlWindows(htmlFilePath: string): Promise<void> {
+  const ps = [
+    'param([string]$Path)',
+    'Add-Type -AssemblyName System.Windows.Forms',
+    '$html = Get-Content -Raw -LiteralPath $Path',
+    '[System.Windows.Forms.Clipboard]::SetText($html, [System.Windows.Forms.TextDataFormat]::Html)',
+  ].join('; ');
+  await runCommand('powershell.exe', ['-NoProfile', '-Sta', '-Command', ps, '-Path', htmlFilePath]);
+}
+
+async function copyImageToClipboard(imagePathInput: string): Promise<void> {
+  const imagePath = resolvePath(imagePathInput);
+  const ext = path.extname(imagePath).toLowerCase();
+  if (!SUPPORTED_IMAGE_EXTS.has(ext)) {
+    throw new Error(
+      `Unsupported image type: ${ext || '(none)'} (supported: ${Array.from(SUPPORTED_IMAGE_EXTS).join(', ')})`,
+    );
+  }
+  if (!fs.existsSync(imagePath)) throw new Error(`File not found: ${imagePath}`);
+
+  switch (process.platform) {
+    case 'darwin':
+      await copyImageMac(imagePath);
+      return;
+    case 'linux':
+      await copyImageLinux(imagePath);
+      return;
+    case 'win32':
+      await copyImageWindows(imagePath);
+      return;
+    default:
+      throw new Error(`Unsupported platform: ${process.platform}`);
+  }
+}
+
+async function copyHtmlFileToClipboard(htmlFilePathInput: string): Promise<void> {
+  const htmlFilePath = resolvePath(htmlFilePathInput);
+  if (!fs.existsSync(htmlFilePath)) throw new Error(`File not found: ${htmlFilePath}`);
+
+  switch (process.platform) {
+    case 'darwin':
+      await copyHtmlMac(htmlFilePath);
+      return;
+    case 'linux':
+      await copyHtmlLinux(htmlFilePath);
+      return;
+    case 'win32':
+      await copyHtmlWindows(htmlFilePath);
+      return;
+    default:
+      throw new Error(`Unsupported platform: ${process.platform}`);
+  }
+}
+
+async function readStdinText(): Promise<string | null> {
+  if (process.stdin.isTTY) return null;
+  const chunks: Buffer[] = [];
+  for await (const chunk of process.stdin) {
+    chunks.push(Buffer.isBuffer(chunk) ? chunk : Buffer.from(chunk));
+  }
+  const text = Buffer.concat(chunks).toString('utf8');
+  return text.length > 0 ? text : null;
+}
+
+async function copyHtmlToClipboard(args: string[]): Promise<void> {
+  let htmlFile: string | undefined;
+  const positional: string[] = [];
+
+  for (let i = 0; i < args.length; i += 1) {
+    const arg = args[i] ?? '';
+    if (arg === '--help' || arg === '-h') printUsage(0);
+    if (arg === '--file') {
+      htmlFile = args[i + 1];
+      i += 1;
+      continue;
+    }
+    if (arg.startsWith('--file=')) {
+      htmlFile = arg.slice('--file='.length);
+      continue;
+    }
+    if (arg === '--') {
+      positional.push(...args.slice(i + 1));
+      break;
+    }
+    if (arg.startsWith('-')) {
+      throw new Error(`Unknown option: ${arg}`);
+    }
+    positional.push(arg);
+  }
+
+  if (htmlFile && positional.length > 0) {
+    throw new Error('Do not pass HTML text when using --file.');
+  }
+
+  if (htmlFile) {
+    await copyHtmlFileToClipboard(htmlFile);
+    return;
+  }
+
+  const htmlFromArgs = positional.join(' ').trim();
+  const htmlFromStdin = (await readStdinText())?.trim() ?? '';
+  const html = htmlFromArgs || htmlFromStdin;
+  if (!html) throw new Error('Missing HTML input. Provide a string or use --file.');
+
+  await withTempDir('copy-to-clipboard-', async (tempDir) => {
+    const htmlPath = path.join(tempDir, 'input.html');
+    await writeFile(htmlPath, html, 'utf8');
+    await copyHtmlFileToClipboard(htmlPath);
+  });
+}
+
+async function main(): Promise<void> {
+  const argv = process.argv.slice(2);
+  if (argv.length === 0) printUsage(1);
+
+  const command = argv[0];
+  if (command === '--help' || command === '-h') printUsage(0);
+
+  if (command === 'image') {
+    const imagePath = argv[1];
+    if (!imagePath) throw new Error('Missing image path.');
+    await copyImageToClipboard(imagePath);
+    return;
+  }
+
+  if (command === 'html') {
+    await copyHtmlToClipboard(argv.slice(1));
+    return;
+  }
+
+  throw new Error(`Unknown command: ${command}`);
+}
+
+await main().catch((err) => {
+  const message = err instanceof Error ? err.message : String(err);
+  console.error(`Error: ${message}`);
+  process.exit(1);
+});
+
@@ -0,0 +1,438 @@
+import fs from 'node:fs';
+import { mkdir, writeFile } from 'node:fs/promises';
+import https from 'node:https';
+import http from 'node:http';
+import os from 'node:os';
+import path from 'node:path';
+import process from 'node:process';
+import { createHash } from 'node:crypto';
+
+interface ImageInfo {
+  placeholder: string;
+  localPath: string;
+  originalPath: string;
+  blockIndex: number;
+}
+
+interface ParsedMarkdown {
+  title: string;
+  coverImage: string | null;
+  contentImages: ImageInfo[];
+  html: string;
+  totalBlocks: number;
+}
+
+function parseFrontmatter(content: string): { frontmatter: Record<string, string>; body: string } {
+  const match = content.match(/^---\r?\n([\s\S]*?)\r?\n---\r?\n([\s\S]*)$/);
+  if (!match) return { frontmatter: {}, body: content };
+
+  const frontmatter: Record<string, string> = {};
+  const lines = match[1]!.split('\n');
+  for (const line of lines) {
+    const colonIdx = line.indexOf(':');
+    if (colonIdx > 0) {
+      const key = line.slice(0, colonIdx).trim();
+      let value = line.slice(colonIdx + 1).trim();
+      if ((value.startsWith('"') && value.endsWith('"')) || (value.startsWith("'") && value.endsWith("'"))) {
+        value = value.slice(1, -1);
+      }
+      frontmatter[key] = value;
+    }
+  }
+
+  return { frontmatter, body: match[2]! };
+}
+
+function downloadFile(url: string, destPath: string): Promise<void> {
+  return new Promise((resolve, reject) => {
+    const protocol = url.startsWith('https') ? https : http;
+    const file = fs.createWriteStream(destPath);
+
+    const request = protocol.get(url, { headers: { 'User-Agent': 'Mozilla/5.0' } }, (response) => {
+      if (response.statusCode === 301 || response.statusCode === 302) {
+        const redirectUrl = response.headers.location;
+        if (redirectUrl) {
+          file.close();
+          fs.unlinkSync(destPath);
+          downloadFile(redirectUrl, destPath).then(resolve).catch(reject);
+          return;
+        }
+      }
+
+      if (response.statusCode !== 200) {
+        file.close();
+        fs.unlinkSync(destPath);
+        reject(new Error(`Failed to download: ${response.statusCode}`));
+        return;
+      }
+
+      response.pipe(file);
+      file.on('finish', () => {
+        file.close();
+        resolve();
+      });
+    });
+
+    request.on('error', (err) => {
+      file.close();
+      fs.unlink(destPath, () => {});
+      reject(err);
+    });
+
+    request.setTimeout(30000, () => {
+      request.destroy();
+      reject(new Error('Download timeout'));
+    });
+  });
+}
+
+function getImageExtension(urlOrPath: string): string {
+  const match = urlOrPath.match(/\.(jpg|jpeg|png|gif|webp)(\?|$)/i);
+  return match ? match[1]!.toLowerCase() : 'png';
+}
+
+async function resolveImagePath(imagePath: string, baseDir: string, tempDir: string): Promise<string> {
+  if (imagePath.startsWith('http://') || imagePath.startsWith('https://')) {
+    const hash = createHash('md5').update(imagePath).digest('hex').slice(0, 8);
+    const ext = getImageExtension(imagePath);
+    const localPath = path.join(tempDir, `remote_${hash}.${ext}`);
+
+    if (!fs.existsSync(localPath)) {
+      console.error(`[md-to-html] Downloading: ${imagePath}`);
+      await downloadFile(imagePath, localPath);
+    }
+    return localPath;
+  }
+
+  if (path.isAbsolute(imagePath)) {
+    return imagePath;
+  }
+
+  return path.resolve(baseDir, imagePath);
+}
+
+function escapeHtml(text: string): string {
+  return text
+    .replace(/&/g, '&amp;')
+    .replace(/</g, '&lt;')
+    .replace(/>/g, '&gt;')
+    .replace(/"/g, '&quot;');
+}
+
+function convertMarkdownToHtml(markdown: string, imageCallback: (src: string, alt: string) => string): { html: string; totalBlocks: number } {
+  const lines = markdown.split('\n');
+  const blocks: string[] = [];
+  let inCodeBlock = false;
+  let codeBlockContent: string[] = [];
+  let inList = false;
+  let listItems: string[] = [];
+  let listType: 'ul' | 'ol' = 'ul';
+
+  const flushList = () => {
+    if (listItems.length > 0) {
+      const tag = listType === 'ol' ? 'ol' : 'ul';
+      blocks.push(`<${tag}>${listItems.map((item) => `<li>${item}</li>`).join('')}</${tag}>`);
+      listItems = [];
+      inList = false;
+    }
+  };
+
+  const processInline = (text: string): string => {
+    // Bold
+    text = text.replace(/\*\*(.+?)\*\*/g, '<strong>$1</strong>');
+    text = text.replace(/__(.+?)__/g, '<strong>$1</strong>');
+
+    // Italic
+    text = text.replace(/\*(.+?)\*/g, '<em>$1</em>');
+    text = text.replace(/_(.+?)_/g, '<em>$1</em>');
+
+    // Links
+    text = text.replace(/\[([^\]]+)\]\(([^)]+)\)/g, '<a href="$2">$1</a>');
+
+    // Inline code
+    text = text.replace(/`([^`]+)`/g, '<code>$1</code>');
+
+    return text;
+  };
+
+  for (let i = 0; i < lines.length; i++) {
+    const line = lines[i]!;
+
+    // Code block
+    if (line.startsWith('```')) {
+      if (inCodeBlock) {
+        // X doesn't support <pre><code>, convert to blockquote
+        const codeContent = codeBlockContent.map((l) => escapeHtml(l)).join('<br>');
+        blocks.push(`<blockquote>${codeContent}</blockquote>`);
+        codeBlockContent = [];
+        inCodeBlock = false;
+      } else {
+        flushList();
+        inCodeBlock = true;
+      }
+      continue;
+    }
+
+    if (inCodeBlock) {
+      codeBlockContent.push(line);
+      continue;
+    }
+
+    // Empty line
+    if (line.trim() === '') {
+      flushList();
+      continue;
+    }
+
+    // Image
+    const imgMatch = line.match(/^!\[([^\]]*)\]\(([^)]+)\)\s*$/);
+    if (imgMatch) {
+      flushList();
+      const placeholder = imageCallback(imgMatch[2]!, imgMatch[1]!);
+      blocks.push(`<p>${placeholder}</p>`);
+      continue;
+    }
+
+    // Heading (H1 is title, skip it; H2-H6 become H2)
+    const headingMatch = line.match(/^(#{1,6})\s+(.+)$/);
+    if (headingMatch) {
+      flushList();
+      const level = headingMatch[1]!.length;
+      if (level === 1) continue; // Skip H1, it's the title
+      blocks.push(`<h2>${processInline(headingMatch[2]!)}</h2>`);
+      continue;
+    }
+
+    // Blockquote
+    if (line.startsWith('> ')) {
+      flushList();
+      blocks.push(`<blockquote>${processInline(line.slice(2))}</blockquote>`);
+      continue;
+    }
+
+    // Unordered list
+    const ulMatch = line.match(/^[-*]\s+(.+)$/);
+    if (ulMatch) {
+      if (!inList || listType !== 'ul') {
+        flushList();
+        inList = true;
+        listType = 'ul';
+      }
+      listItems.push(processInline(ulMatch[1]!));
+      continue;
+    }
+
+    // Ordered list
+    const olMatch = line.match(/^\d+\.\s+(.+)$/);
+    if (olMatch) {
+      if (!inList || listType !== 'ol') {
+        flushList();
+        inList = true;
+        listType = 'ol';
+      }
+      listItems.push(processInline(olMatch[1]!));
+      continue;
+    }
+
+    // Horizontal rule
+    if (/^[-*_]{3,}\s*$/.test(line)) {
+      flushList();
+      blocks.push('<hr>');
+      continue;
+    }
+
+    // Regular paragraph
+    flushList();
+    blocks.push(`<p>${processInline(line)}</p>`);
+  }
+
+  flushList();
+
+  return {
+    html: blocks.join('\n'),
+    totalBlocks: blocks.length,
+  };
+}
+
+export async function parseMarkdown(
+  markdownPath: string,
+  options?: { coverImage?: string; title?: string; tempDir?: string },
+): Promise<ParsedMarkdown> {
+  const content = fs.readFileSync(markdownPath, 'utf-8');
+  const baseDir = path.dirname(markdownPath);
+  const tempDir = options?.tempDir ?? path.join(os.tmpdir(), 'x-article-images');
+
+  await mkdir(tempDir, { recursive: true });
+
+  const { frontmatter, body } = parseFrontmatter(content);
+
+  // Extract title from frontmatter, option, or first H1
+  let title = options?.title ?? frontmatter.title ?? '';
+  if (!title) {
+    const h1Match = body.match(/^#\s+(.+)$/m);
+    if (h1Match) title = h1Match[1]!;
+  }
+
+  // Extract cover image from frontmatter or option
+  let coverImagePath = options?.coverImage ?? frontmatter.cover_image ?? frontmatter.coverImage ?? frontmatter.cover ?? frontmatter.image ?? frontmatter.featureImage ?? frontmatter.feature_image ?? null;
+
+  const images: Array<{ src: string; alt: string; blockIndex: number }> = [];
+  let imageCounter = 0;
+
+  const { html, totalBlocks } = convertMarkdownToHtml(body, (src, alt) => {
+    const placeholder = `[[IMAGE_PLACEHOLDER_${++imageCounter}]]`;
+    const currentBlockIndex = images.length; // Will be set properly after HTML generation
+
+    images.push({ src, alt, blockIndex: -1 }); // blockIndex set later
+    return placeholder;
+  });
+
+  // Update block indices by finding placeholders in HTML
+  const htmlLines = html.split('\n');
+  let blockIdx = 0;
+  for (const line of htmlLines) {
+    for (let i = 0; i < images.length; i++) {
+      const placeholder = `[[IMAGE_PLACEHOLDER_${i + 1}]]`;
+      if (line.includes(placeholder)) {
+        images[i]!.blockIndex = blockIdx;
+      }
+    }
+    blockIdx++;
+  }
+
+  // Resolve image paths (download remote, resolve relative)
+  const contentImages: ImageInfo[] = [];
+  let isFirstImage = true;
+  let coverPlaceholder: string | null = null;
+
+  for (let i = 0; i < images.length; i++) {
+    const img = images[i]!;
+    const localPath = await resolveImagePath(img.src, baseDir, tempDir);
+
+    // First image becomes cover if no cover specified
+    if (isFirstImage && !coverImagePath) {
+      coverImagePath = localPath;
+      coverPlaceholder = `[[IMAGE_PLACEHOLDER_${i + 1}]]`;
+      isFirstImage = false;
+      // Don't add to contentImages, it's the cover
+      continue;
+    }
+
+    isFirstImage = false;
+    contentImages.push({
+      placeholder: `[[IMAGE_PLACEHOLDER_${i + 1}]]`,
+      localPath,
+      originalPath: img.src,
+      blockIndex: img.blockIndex,
+    });
+  }
+
+  // Remove cover placeholder from HTML if first image was used as cover
+  let finalHtml = html;
+  if (coverPlaceholder) {
+    // Remove the placeholder and its containing <p> tag
+    finalHtml = finalHtml.replace(new RegExp(`<p>${coverPlaceholder.replace(/[[\]]/g, '\\$&')}</p>\\n?`, 'g'), '');
+  }
+
+  // Resolve cover image path
+  let resolvedCoverImage: string | null = null;
+  if (coverImagePath) {
+    resolvedCoverImage = await resolveImagePath(coverImagePath, baseDir, tempDir);
+  }
+
+  return {
+    title,
+    coverImage: resolvedCoverImage,
+    contentImages,
+    html: finalHtml,
+    totalBlocks,
+  };
+}
+
+function printUsage(): never {
+  console.log(`Convert Markdown to HTML for X Article publishing
+
+Usage:
+  npx -y bun md-to-html.ts <markdown_file> [options]
+
+Options:
+  --title <title>       Override title from frontmatter
+  --cover <image>       Override cover image from frontmatter
+  --output <json|html>  Output format (default: json)
+  --html-only           Output only the HTML content
+  --save-html <path>    Save HTML to file
+
+Frontmatter fields:
+  title: Article title (or use first H1)
+  cover_image: Cover image path or URL
+  cover: Alias for cover_image
+  image: Alias for cover_image
+
+Example:
+  npx -y bun md-to-html.ts article.md --output json
+  npx -y bun md-to-html.ts article.md --html-only > /tmp/article.html
+  npx -y bun md-to-html.ts article.md --save-html /tmp/article.html
+`);
+  process.exit(0);
+}
+
+async function main(): Promise<void> {
+  const args = process.argv.slice(2);
+  if (args.length === 0 || args.includes('--help') || args.includes('-h')) {
+    printUsage();
+  }
+
+  let markdownPath: string | undefined;
+  let title: string | undefined;
+  let coverImage: string | undefined;
+  let outputFormat: 'json' | 'html' = 'json';
+  let htmlOnly = false;
+  let saveHtmlPath: string | undefined;
+
+  for (let i = 0; i < args.length; i++) {
+    const arg = args[i]!;
+    if (arg === '--title' && args[i + 1]) {
+      title = args[++i];
+    } else if (arg === '--cover' && args[i + 1]) {
+      coverImage = args[++i];
+    } else if (arg === '--output' && args[i + 1]) {
+      outputFormat = args[++i] as 'json' | 'html';
+    } else if (arg === '--html-only') {
+      htmlOnly = true;
+    } else if (arg === '--save-html' && args[i + 1]) {
+      saveHtmlPath = args[++i];
+    } else if (!arg.startsWith('-')) {
+      markdownPath = arg;
+    }
+  }
+
+  if (!markdownPath) {
+    console.error('Error: Markdown file path required');
+    process.exit(1);
+  }
+
+  if (!fs.existsSync(markdownPath)) {
+    console.error(`Error: File not found: ${markdownPath}`);
+    process.exit(1);
+  }
+
+  const result = await parseMarkdown(markdownPath, { title, coverImage });
+
+  if (saveHtmlPath) {
+    await writeFile(saveHtmlPath, result.html, 'utf-8');
+    console.error(`[md-to-html] HTML saved to: ${saveHtmlPath}`);
+  }
+
+  if (htmlOnly) {
+    console.log(result.html);
+  } else if (outputFormat === 'html') {
+    console.log(result.html);
+  } else {
+    console.log(JSON.stringify(result, null, 2));
+  }
+}
+
+await main().catch((err) => {
+  console.error(`Error: ${err instanceof Error ? err.message : String(err)}`);
+  process.exit(1);
+});
--- a/Show More
+++ b/Show More
Author	SHA1	Message	Date
Jim Liu 宝玉	3811512750	docs: add Customization section to README files	2026-01-17 22:12:01 -06:00
Jim Liu 宝玉	9a9f6a42cd	chore: release v0.9.0	2026-01-17 22:02:40 -06:00
Jim Liu 宝玉	3b13b25f1a	chore: release v0.8.2	2026-01-17 19:00:27 -06:00
Jim Liu 宝玉	688d1760ed	chore: release v0.8.0 Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>	2026-01-17 16:44:50 -06:00
Jim Liu 宝玉	a701be873b	update Image Generation Guidelines	2026-01-17 16:24:23 -06:00
Jim Liu 宝玉	1df5e4974d	feat: add analysis framework for Xiaohongshu content	2026-01-17 15:52:00 -06:00
Jim Liu 宝玉	2677e730b9	Update release-skills to update readme	2026-01-17 15:11:50 -06:00
Jim Liu 宝玉	080f2eff48	chore: release v0.7.0 - baoyu-comic: adds --aspect (3:4, 4:3, 16:9) and --lang options; multi-variant storyboard workflow - baoyu-comic/baoyu-slide-deck: adds analysis-framework and template references - Multiple skills: restructured SKILL.md, moved details to references/ Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>	2026-01-17 15:03:43 -06:00
Jim Liu 宝玉	bb4f0dc52c	feat: add PDF export for slide-deck and comic skills	2026-01-17 12:08:08 -06:00
Jim Liu 宝玉	c731faea8f	feat: update slide deck	2026-01-17 04:28:16 -06:00
Jim Liu 宝玉	fa155da15d	fix: update version to 0.5.3 and enhance placeholder selection logic in publishArticle function	2026-01-17 01:29:10 -06:00
Jim Liu 宝玉	6194f71378	bump version	2026-01-16 21:44:14 -06:00
Jim Liu 宝玉	8e88cf4a8b	feat: implement session management for image generation skills and add session handling functions	2026-01-16 20:20:07 -06:00
Jim Liu 宝玉	259baff413	update gemeni-web to support add image as reference	2026-01-16 19:06:14 -06:00
Jim Liu 宝玉	a42137ff13	feat: update version to 0.5.1 and enhance baoyu-comic documentation with character and outline templates	2026-01-16 01:43:37 -06:00
Jim Liu 宝玉	c6d96d4134	add new skill baoyu-comic	2026-01-16 01:12:21 -06:00
Jim Liu 宝玉	e174d642df	feat: add quick install instructions to README files	2026-01-15 22:06:38 -06:00
Jim Liu 宝玉	db7eaa2847	feat: update version number to 0.4.2 and enhance description for baoyu-gemini-web skill	2026-01-15 17:05:58 -06:00
Jim Liu 宝玉	e3d2f5d03f	Add clipboard paste functionality and documentation for X Articles and regular posts - Implemented `paste-from-clipboard.ts` script to send real paste keystrokes across macOS, Linux, and Windows. - Created detailed guides for publishing articles to X Articles and posting regular content, including usage examples and troubleshooting tips. - Added support for Markdown formatting and image handling in X Articles. - Documented manual workflows for image pasting and browser interactions using Playwright MCP.	2026-01-15 15:38:03 -06:00
Jim Liu 宝玉	da920bb830	feat: add baoyu- prefix	2026-01-15 14:18:56 -06:00
Jim Liu 宝玉	f49acb9983	feat: Update version number to 0.3.1 in marketplace.json	2026-01-15 10:59:03 -06:00
Jim Liu 宝玉	3fddcc0e6a	feat: Update image generation steps in article-illustrator, cover-image, and xhs-images skills for improved user guidance	2026-01-15 10:58:20 -06:00
Jim Liu 宝玉	d4070b19d5	feat: Enhance xhs-images skill with style and layout options for improved infographic generation	2026-01-14 10:42:04 -06:00
Jim Liu 宝玉	6430c67efe	feat: Add 'notion' style option to article-illustrator, slide-deck, and xhs-images skills for enhanced visual presentation	2026-01-14 10:06:53 -06:00
Jim Liu 宝玉	73a5f60ad3	feat: Add WeChat posting skill and update marketplace.json	2026-01-14 02:55:39 -06:00
Jim Liu 宝玉	7a2f475417	Create CLAUDE.md	2026-01-13 21:52:39 -06:00
Jim Liu 宝玉	bb494f07ba	Update slide deck skill documentation to clarify image generation and add new styles	2026-01-13 20:55:47 -06:00
Jim Liu 宝玉	ced92e2231	Update marketplace.json version to 0.2.0 for improved clarity	2026-01-13 20:24:11 -06:00
Jim Liu 宝玉	102ef092ad	Update slide deck skill documentation and prompt guidelines for improved clarity and functionality	2026-01-13 20:23:53 -06:00
Jim Liu 宝玉	cc553ddbb3	Refactor infographic generation skills and add new slide deck generator - Updated article-illustrator prompts to emphasize hand-drawn style and layout principles. - Enhanced xhs-images skill with multiple style options and auto-selection based on content signals. - Created README in Chinese for better accessibility. - Introduced cover-image skill for generating hand-drawn style cover images with various styles. - Developed slide-deck skill to generate professional slide outlines with detailed structure and style instructions. - Added prompts for cover-image and slide-deck skills to guide content generation.	2026-01-13 19:52:10 -06:00
Jim Liu 宝玉	2f4b5fcc85	add article-illustrator skill documentation with infographic guidelines	2026-01-13 19:15:43 -06:00
Jim Liu 宝玉	227b1dcdf6	new skill: post to x	2026-01-13 18:16:12 -06:00
Jim Liu 宝玉	b0ee7b3d33	refactor marketplace.json structure and remove obsolete plugin.json	2026-01-13 00:56:46 -06:00
Jim Liu 宝玉	e1aaae43b6	add readme	2026-01-13 00:49:59 -06:00
Jim Liu 宝玉	6eaa822542	add xhs-images prompt	2026-01-13 00:35:03 -06:00
				`@@ -0,0 +1,2 @@`
				`export { GemMixin } from './gem-mixin.js';`