Summarize 📝 — Chrome 侧边栏 + CLI

快速从 URL、文件和媒体中生成摘要。支持终端、Chrome 侧边栏（Side Panel）和 Firefox 侧边栏（Sidebar）。

亮点功能

• Chrome 侧边栏内置 聊天 功能（流式代理 + 历史记录）。
• YouTube 幻灯片：截图 + OCR（光学字符识别）+ 字幕卡片，带时间戳跳转，支持 OCR/字幕切换。
• 媒体感知摘要：自动检测视频/音频内容 vs 网页内容。
• 流式 Markdown 输出 + 指标 + 缓存状态提示。
• CLI 支持 URL、文件、播客、YouTube、音视频、PDF 等多种输入。

功能概览

• 支持多种输入源：网页、PDF、图片、音视频、YouTube、播客、RSS。
• 视频源（YouTube/直接媒体）的幻灯片提取，结合 OCR 与带时间戳的卡片。
• 优先使用已发布的字幕；若无，则回退至 Groq/ONNX/whisper.cpp/AssemblyAI/Gemini/OpenAI/FAL 进行转录。
• 流式输出，支持 Markdown 渲染、指标展示和缓存状态提示。
• 支持本地、付费和免费模型：兼容 OpenAI 的本地端点、付费服务商，以及 OpenRouter 提供的免费预设。
• 多种输出模式：Markdown/纯文本、JSON 诊断信息、仅提取内容、指标、耗时和成本估算。
• 智能默认行为：若内容长度小于请求的摘要长度，则直接返回原文（使用 --force-summary 可强制摘要）。

获取扩展程序（推荐）

一键为当前标签页生成摘要。支持 Chrome 侧边栏、Firefox 侧边栏及本地守护进程（daemon），用于流式 Markdown 输出。

Chrome 网上应用店： Summarize Side Panel

浏览器中的 YouTube 幻灯片截图：

初学者快速入门（扩展程序）

1. 安装 CLI（任选其一）：
   • npm（跨平台）：npm i -g @steipete/summarize
   • Homebrew（macOS arm64）：brew install steipete/tap/summarize
2. 安装上述扩展程序，并打开侧边栏。
3. 面板会显示一个 token 和安装命令。在终端中运行：
   • summarize daemon install --token <TOKEN>

为何需要守护进程（daemon）？

• 扩展程序无法在浏览器内执行重型提取任务。它通过本地后台服务（运行于 127.0.0.1）实现快速流式处理和媒体工具调用（如 yt-dlp、ffmpeg、OCR、转录）。
• 该服务会自动启动（通过 launchd/systemd/计划任务），确保侧边栏随时可用。

如果你只需要 CLI，完全可以跳过守护进程的安装。

注意事项：

• 摘要仅在侧边栏打开时运行。
• 自动模式会在页面导航时（包括 SPA）自动摘要；否则请手动点击按钮。
• 守护进程仅限本地回环地址（localhost），需共享 token；再次运行 summarize daemon install --token <TOKEN> 会新增一个配对 token，而非使旧 token 失效。
• 自启机制：macOS（launchd）、Linux（systemd 用户级）、Windows（计划任务）。
• 提示：通过 summarize refresh-free 配置 free 模型（需设置 OPENROUTER_API_KEY）。添加 --set-default 可将模型设为 free。

更多详情：

• 分步安装指南：apps/chrome-extension/README.md
• 架构与故障排查：docs/chrome-extension.md
• Firefox 兼容性说明：apps/chrome-extension/docs/firefox.md

幻灯片功能（扩展程序）

• 在 Summarize 选择器中选择 Video + Slides。
• 幻灯片显示在顶部；可展开为全宽卡片并附带时间戳。
• 点击幻灯片可跳转视频；当 OCR 内容显著时，可切换 Transcript/OCR。
• 依赖项：yt-dlp + ffmpeg 用于提取；tesseract 用于 OCR。缺少工具时，面板内会显示提示。

高级用法（未打包 / 开发模式）

1. 构建并加载扩展程序（未打包）：
   • Chrome：pnpm -C apps/chrome-extension build
     • 访问 chrome://extensions → 启用开发者模式 → 加载已解压的扩展程序
     • 选择路径：apps/chrome-extension/.output/chrome-mv3
   • Firefox：pnpm -C apps/chrome-extension build:firefox
     • 访问 about:debugging#/runtime/this-firefox → 加载临时附加组件
     • 选择文件：apps/chrome-extension/.output/firefox-mv3/manifest.json
2. 打开侧边栏 → 复制 token。
3. 以开发模式安装守护进程：
   • pnpm summarize daemon install --token <TOKEN> --dev

CLI

安装

需要 Node 22+。

• npx（无需安装）：

npx -y @steipete/summarize "https://example.com"

• npm（全局安装）：

npm i -g @steipete/summarize

• npm（作为库 / 最小依赖）：

npm i @steipete/summarize-core

import { createLinkPreviewClient } from "@steipete/summarize-core/content";

• Homebrew（自定义 tap）：

brew install steipete/tap/summarize

Homebrew 的可用性取决于当前 tap 中针对你架构的 formula。
如果在 Intel/x64 上 Homebrew 安装失败，请使用上方的 npm 全局安装方式。

可选的本地依赖

如需重度媒体功能，请安装以下工具：

• ffmpeg：--slides 及许多本地媒体/转录流程必需
• yt-dlp：YouTube 幻灯片提取及部分远程媒体流程必需
• tesseract：--slides-ocr 的可选 OCR 工具
• 可选的云端转录服务提供商：
  • GROQ_API_KEY
  • ASSEMBLYAI_API_KEY
  • GEMINI_API_KEY / GOOGLE_GENERATIVE_AI_API_KEY / GOOGLE_API_KEY
  • OPENAI_API_KEY
  • FAL_KEY

macOS（通过 Homebrew）：

brew install ffmpeg yt-dlp
brew install tesseract # 可选，用于 --slides-ocr

若启用 --slides 但缺少上述工具，Summarize 会发出警告并继续运行（不生成幻灯片）。

CLI 与扩展程序对比

• 仅 CLI：只需通过 npm/Homebrew 安装并运行 summarize ...（无需守护进程）。
• Chrome/Firefox 扩展程序：需安装 CLI 并运行 summarize daemon install --token <TOKEN>，以便侧边栏能流式接收结果并使用本地工具。

快速入门

summarize "https://example.com"

输入源

支持 URL 或本地路径：

summarize "/path/to/file.pdf" --model google/gemini-3-flash
summarize "https://example.com/report.pdf" --model google/gemini-3-flash
summarize "/path/to/audio.mp3"
summarize "/path/to/video.mp4"

标准输入（通过 - 管道传入内容）：

echo "content" | summarize -
pbpaste | summarize -

二进制标准输入也支持（PDF/图像/音频/视频字节流）

cat /path/to/file.pdf | summarize -

注意事项：

• 标准输入（stdin）有 50MB 大小限制
• - 参数告诉 summarize 从标准输入读取内容
• 文本标准输入被视为 UTF-8 文本（仅包含空白字符的输入会被视为为空而拒绝）
• 二进制标准输入会保留为原始字节，文件类型会在可能的情况下自动检测
• 适用于管道传递剪贴板内容或命令输出

YouTube（支持 youtube.com 和 youtu.be）：

summarize "https://youtu.be/dQw4w9WgXcQ" --youtube auto

播客 RSS（转录最新一期的 enclosure）：

summarize "https://feeds.npr.org/500005/podcast.xml"

Apple Podcasts 节目页面：

summarize "https://podcasts.apple.com/us/podcast/2424-jelly-roll/id360084272?i=1000740717432"

Spotify 节目页面（尽力而为；独家内容可能失败）：

summarize "https://open.spotify.com/episode/5auotqWAXhhKyb9ymCuBJY"

输出长度

--length 控制我们请求的输出量（仅为指导值），并非硬性上限。

summarize "https://example.com" --length long
summarize "https://example.com" --length 20k

• 预设值：short|medium|long|xl|xxl
• 字符目标值：1500、20k、20000
• 可选硬性上限：--max-output-tokens <count>（例如 2000、2k）
  • 提供商/模型 API 仍会强制执行其自身的最大输出限制。
  • 如果省略，则不会发送最大 token 参数（使用提供商默认值）。
  • 除非需要硬性上限，否则建议优先使用 --length。
• 短内容：当提取的内容比请求的长度更短时，CLI 会原样返回该内容。
  • 使用 --force-summary 可强制始终运行 LLM。
• 最小值限制：--length 的数值必须 ≥ 50 个字符；--max-output-tokens 必须 ≥ 16。
• 预设目标值（权威来源：packages/core/src/prompts/summary-lengths.ts）：
  • short: 目标约 900 字符（范围 600–1,200）
  • medium: 目标约 1,800 字符（范围 1,200–2,500）
  • long: 目标约 4,200 字符（范围 2,500–6,000）
  • xl: 目标约 9,000 字符（范围 6,000–14,000）
  • xxl: 目标约 17,000 字符（范围 14,000–22,000）

支持哪些文件类型？

尽力支持，具体取决于提供商。以下类型通常效果良好：

• text/* 及常见结构化文本（.txt、.md、.json、.yaml、.xml 等）
  • 类文本文件会被内联到提示中，以提高与提供商的兼容性。
• PDF：application/pdf（提供商支持情况各异；Google 在此最为可靠）
• 图像：image/jpeg、image/png、image/webp、image/gif
• 音频/视频：audio/*、video/*（本地音频/视频文件如 MP3/WAV/M4A/OGG/FLAC/MP4/MOV/WEBM 会在模型支持时自动转录）

注意事项：

• 如果提供商拒绝某种媒体类型，CLI 会快速失败并给出友好提示。
• xAI 模型不支持通过 AI SDK 附加通用文件（如 PDF）；此类场景请使用 Google/OpenAI/Anthropic。

模型 ID

使用网关风格的 ID：<provider>/<model>。

示例：

• openai/gpt-5-mini
• anthropic/claude-sonnet-4-5
• xai/grok-4-fast-non-reasoning
• google/gemini-3-flash
• zai/glm-4.7
• openrouter/openai/gpt-5-mini（强制使用 OpenRouter）

注意：某些模型/提供商不支持流式输出或特定文件媒体类型。发生这种情况时，CLI 会打印友好错误（或在提供商支持的情况下自动为该模型禁用流式输出）。

限制

• 超过 10 MB 的文本输入会在分词前被拒绝。
• 文本提示会通过 GPT 分词器预先检查是否超出模型输入限制（基于 LiteLLM 目录）。

常用标志

summarize <input> [flags]

使用 summarize --help 或 summarize help 查看完整帮助信息。

• --model <provider/model>：指定使用的模型（默认为 auto）
• --model auto：自动选择模型并启用备选方案（默认）
• --model <name>：使用配置中定义的模型（参见 Configuration）
• --timeout <duration>：超时时间，如 30s、2m、5000ms（默认 2m）
• --retries <count>：LLM 超时时的重试次数（默认 1）
• --length short|medium|long|xl|xxl|s|m|l|<chars>
• --language, --lang <language>：输出语言（auto = 与源语言一致）
• --max-output-tokens <count>：LLM 输出 token 的硬性上限
• --cli [provider]：使用 CLI 提供商（--model cli/<provider>）。支持 claude、gemini、codex、agent。若省略，则启用 CLI 并自动选择提供商。
• --stream auto|on|off：流式输出 LLM 结果（auto = 仅在 TTY 中启用；在 --json 模式下禁用）
• --plain：保留原始输出（不进行 ANSI/OSC Markdown 渲染）
• --no-color：禁用 ANSI 颜色
• --theme <name>：CLI 主题（aurora、ember、moss、mono）
• --format md|text：网站/文件内容格式（默认 text）
• --markdown-mode off|auto|llm|readability：HTML → Markdown 转换模式（默认 readability）
• --preprocess off|auto|always：控制 uvx markitdown 的使用（默认 auto）
  • 安装 uvx：brew install uv（或 https://astral.sh/uv/）
• --extract：打印提取的内容并退出（仅适用于 URL；不支持标准输入 -）
  • 已弃用的别名：--extract-only
• --slides：为 YouTube/直接视频 URL 提取幻灯片，并在摘要叙述中内联渲染（在支持的终端中自动内联显示）
• --slides-ocr：对提取的幻灯片运行 OCR（需安装 tesseract）
• --slides-dir <dir>：幻灯片图像的基础输出目录（默认 ./slides）
• --slides-scene-threshold <value>：场景检测阈值（0.1–1.0）
• --slides-max <count>：最多提取的幻灯片数量（默认 6）
• --slides-min-duration <seconds>：幻灯片之间的最小间隔秒数
• --json：机器可读的输出，包含诊断信息、提示、metrics 和可选摘要
• --verbose：在 stderr 输出调试/诊断信息
• --metrics off|on|detailed：指标输出（默认 on）

编码 CLI（Codex、Claude、Gemini、Agent）

Summarize 可以使用常见的编码 CLI 作为本地模型后端：

• codex -> --cli codex / --model cli/codex/<model>
• claude -> --cli claude / --model cli/claude/<model>
• gemini -> --cli gemini / --model cli/gemini/<model>
• agent（Cursor Agent CLI）-> --cli agent / --model cli/agent/<model>

要求：

• 二进制文件已安装并位于 PATH 中（或设置 CODEX_PATH、CLAUDE_PATH、GEMINI_PATH、AGENT_PATH）
• 提供商已完成身份验证（codex login、claude auth、gemini 登录流程、agent login 或 CURSOR_API_KEY）

快速冒烟测试：

printf "Summarize CLI smoke input.\nOne short paragraph. Reply can be brief.\n" >/tmp/summarize-cli-smoke.txt

summarize --cli codex --plain --timeout 2m /tmp/summarize-cli-smoke.txt
summarize --cli claude --plain --timeout 2m /tmp/summarize-cli-smoke.txt
summarize --cli gemini --plain --timeout 2m /tmp/summarize-cli-smoke.txt
summarize --cli agent --plain --timeout 2m /tmp/summarize-cli-smoke.txt

设置显式的 CLI 白名单/顺序：

{
  "cli": { "enabled": ["codex", "claude", "gemini", "agent"] }
}

配置隐式自动 CLI 回退：

{
  "cli": {
    "autoFallback": {
      "enabled": true,
      "onlyWhenNoApiKeys": true,
      "order": ["claude", "gemini", "codex", "agent"]
    }
  }
}

更多详情：docs/cli.md

自动模型排序

--model auto 会根据内置规则（或你自定义的 model.rules 覆盖）构建候选尝试列表。
当满足以下任一条件时，CLI 尝试会被前置：

• 设置了 cli.enabled（显式白名单/顺序），或
• 启用了隐式自动选择且 cli.autoFallback 已启用。

默认回退行为：仅在未配置任何 API 密钥时触发，顺序为 claude, gemini, codex, agent，并记住/优先使用上次成功的提供商（记录于 ~/.summarize/cli-state.json）。

设置显式的 CLI 尝试：

{
  "cli": { "enabled": ["gemini"] }
}

禁用隐式自动 CLI 回退：

{
  "cli": { "autoFallback": { "enabled": false } }
}

注意：显式使用 --model auto 不会触发隐式自动 CLI 回退，除非设置了 cli.enabled。

网站内容提取（Firecrawl + Markdown）

非 YouTube URL 会经过 fetch -> extract 流程。当直接抓取/提取被阻止或内容过少时，
若已配置，--firecrawl auto 会回退到 Firecrawl。

• --firecrawl off|auto|always（默认 auto）
• --extract --format md|text（默认 text；若省略 --format，则对非 YouTube URL 默认使用 md）
• --markdown-mode off|auto|llm|readability（默认 readability）
  • auto：在配置了 LLM 转换器时使用；可能回退到 uvx markitdown
  • llm：强制使用 LLM 转换（需要配置模型密钥）
  • off：禁用 LLM 转换（但若已配置 Firecrawl，仍可能返回其生成的 Markdown）
• 纯文本模式：使用 --format text。

YouTube 字幕转录

--youtube auto 首先尝试尽力而为的网页字幕端点。当字幕不可用时，会按以下顺序回退：

1. Apify（若设置了 APIFY_API_TOKEN）：使用爬虫 Actor (faVsWy9VTSNVIhWpR)
2. yt-dlp + Whisper（若 yt-dlp 可用）：下载音频，若已安装则使用本地 whisper.cpp 进行转录（优先），否则依次回退至 Groq (GROQ_API_KEY)、AssemblyAI (ASSEMBLYAI_API_KEY)、Gemini (GEMINI_API_KEY / Google 别名)、OpenAI (OPENAI_API_KEY)，最后是 FAL (FAL_KEY)

yt-dlp 模式环境变量：

• YT_DLP_PATH - yt-dlp 二进制文件的可选路径（否则通过 PATH 解析）
• SUMMARIZE_WHISPER_CPP_MODEL_PATH - 本地 whisper.cpp 模型文件的可选覆盖路径
• SUMMARIZE_WHISPER_CPP_BINARY - 本地二进制文件的可选覆盖路径（默认：whisper-cli）
• SUMMARIZE_DISABLE_LOCAL_WHISPER_CPP=1 - 禁用本地 whisper.cpp（强制使用远程服务）
• GROQ_API_KEY - Groq Whisper 转录
• ASSEMBLYAI_API_KEY - AssemblyAI 转录
• GEMINI_API_KEY - Gemini 转录（GOOGLE_GENERATIVE_AI_API_KEY / GOOGLE_API_KEY 同样有效）
• OPENAI_API_KEY - OpenAI Whisper 转录
• OPENAI_WHISPER_BASE_URL - 可选的 OpenAI 兼容 Whisper 端点覆盖
• FAL_KEY - FAL AI Whisper 回退方案

Apify 需付费，但在字幕存在时通常更可靠。

幻灯片提取（YouTube + 直接视频链接）

提取幻灯片截图（通过 ffmpeg 进行场景检测）并可选 OCR：

依赖项：

• ffmpeg：用于场景检测和帧提取
• yt-dlp：用于 YouTube 视频下载/流解析
• tesseract：仅在使用 --slides-ocr 时需要

summarize "https://www.youtube.com/watch?v=..." --slides
summarize "https://www.youtube.com/watch?v=..." --slides --slides-ocr

输出写入 ./slides/<sourceId>/（或通过 --slides-dir 指定）。OCR 结果包含在 JSON 输出中（--json），并存储在幻灯片目录内的 slides.json 文件中。当场景检测过于稀疏时，提取器还会以固定间隔采样以提高覆盖率。
使用 --slides 时，支持的终端（kitty/iTerm/Konsole）会在摘要叙述中自动渲染内联缩略图（模型插入 [slide:N] 标记）。当终端支持 OSC-8 时，时间戳链接可点击（适用于 YouTube/Vimeo/Loom/Dropbox）。若不支持内联图像，Summarize 会打印一条提示，说明磁盘上的幻灯片目录位置。

使用 --slides --extract 可打印完整的时间戳转录，并在匹配的时间点内联插入幻灯片图像。

通过 LLM 将提取的转录格式化为 Markdown（标题 + 段落）：

summarize "https://www.youtube.com/watch?v=..." --extract --format md --markdown-mode llm

媒体转录（Whisper）

本地音视频文件会先进行转录，再进行摘要。--video-mode transcript 强制将直接媒体 URL（及嵌入媒体）先通过 Whisper 处理。优先使用本地 whisper.cpp（若可用）；否则需要配置以下任一密钥：GROQ_API_KEY、ASSEMBLYAI_API_KEY、GEMINI_API_KEY（或 Google 别名）、OPENAI_API_KEY 或 FAL_KEY。

本地 ONNX 转录（Parakeet/Canary）

Summarize 可通过你提供的本地 CLI 使用 NVIDIA Parakeet/Canary ONNX 模型。自动选择（默认）在配置后优先使用 ONNX。

• 设置助手：summarize transcriber setup
• 从上游二进制文件/构建安装 sherpa-onnx（Homebrew 可能没有公式）
• 自动选择：设置 SUMMARIZE_ONNX_PARAKEET_CMD 或 SUMMARIZE_ONNX_CANARY_CMD（无需额外标志）
• 强制指定模型：--transcriber parakeet|canary|whisper|auto
• 文档：docs/nvidia-onnx-transcription.md

已验证的播客服务（截至 2025-12-25）

运行：summarize <url>

• Apple Podcasts
• Spotify
• Amazon Music / Audible 播客页面
• Podbean
• Podchaser
• RSS 订阅源（若有 Podcasting 2.0 转录则优先使用）
• 嵌入式 YouTube 播客页面（例如 JREPodcast）

转录：若已安装，优先使用本地 whisper.cpp；否则在设置了密钥的情况下，依次使用 Groq、AssemblyAI、Gemini、OpenAI 或 FAL。

翻译路径

--language/--lang 控制摘要（及其他 LLM 生成文本）的输出语言，默认为 auto。

当输入为音频/视频时，CLI 需要先获取转录文本。转录文本来自以下路径之一：

1. 已有转录文本（优先）
   • YouTube：在可用时使用 youtubei / captionTracks。
   • 播客（Podcasts）：当 RSS 订阅源发布时，使用 Podcasting 2.0 标准中的 <podcast:transcript>（JSON/VTT 格式）。
2. Whisper 转录（后备方案）
   • YouTube：在配置后，若无现成字幕，则回退到 yt-dlp（音频下载）+ Whisper 转录；Apify 是最后的选择。
   • 若已安装本地 whisper.cpp 且模型可用，则优先使用。
   • 否则按以下顺序使用云端转录服务：Groq (GROQ_API_KEY) → AssemblyAI (ASSEMBLYAI_API_KEY) → Gemini (GEMINI_API_KEY 或 Google 别名) → OpenAI (OPENAI_API_KEY) → FAL (FAL_KEY)。

对于直接媒体 URL，可使用 --video-mode transcript 强制执行“转录 → 摘要”流程：

summarize https://example.com/file.mp4 --video-mode transcript --lang en

配置

单一配置位置：

• ~/.summarize/config.json

当前支持的键：

{
  "model": { "id": "openai/gpt-5-mini" },
  "env": { "OPENAI_API_KEY": "sk-..." },
  "ui": { "theme": "ember" }
}

简写形式（等效）：

{
  "model": "openai/gpt-5-mini"
}

其他支持项：

• model: { "mode": "auto" }（自动选择模型并回退；详见 docs/model-auto.md）
• model.rules（自定义候选模型及排序）
• models（定义可通过 --model <preset> 选择的预设）
• env（通用环境变量默认值；进程环境变量仍优先）
• apiKeys（旧版快捷方式，映射为环境变量名；新配置建议使用 env）
• cache.media（媒体下载缓存：默认 TTL 7 天，上限 2048 MB；--no-media-cache 可禁用）
• media.videoMode: "auto"|"transcript"|"understand"
• slides.enabled / slides.max / slides.ocr / slides.dir（--slides 的默认值）
• ui.theme: "aurora"|"ember"|"moss"|"mono"
• openai.useChatCompletions: true（强制使用 OpenAI 兼容的聊天补全接口）

注意：配置文件采用宽松解析（JSON5），但不允许注释。未知键将被忽略。

媒体缓存默认值：

{
  "cache": {
    "media": { "enabled": true, "ttlDays": 7, "maxMb": 2048, "verify": "size" }
  }
}

注意：--no-cache 仅跳过摘要缓存（LLM 输出），提取/转录缓存仍生效。使用 --no-media-cache 可跳过媒体文件缓存。

模型优先级顺序：

1. --model
2. SUMMARIZE_MODEL
3. ~/.summarize/config.json
4. 默认值 (auto)

主题（theme）优先级顺序：

1. --theme
2. SUMMARIZE_THEME
3. ~/.summarize/config.json (ui.theme)
4. 默认值 (aurora)

环境变量优先级顺序：

1. 进程环境变量
2. ~/.summarize/config.json (env)
3. ~/.summarize/config.json (apiKeys，旧版)

环境变量

设置与所选 --model 对应的密钥：

• 可选的回退默认值可存储在配置中：

  • ~/.summarize/config.json → "env": { "OPENAI_API_KEY": "sk-..." }
  • 进程环境变量始终优先
  • 旧版 "apiKeys" 仍有效（映射为环境变量名）

• OPENAI_API_KEY（用于 openai/...）

• NVIDIA_API_KEY（用于 nvidia/...）

• ANTHROPIC_API_KEY（用于 anthropic/...）

• XAI_API_KEY（用于 xai/...）

• Z_AI_API_KEY（用于 zai/...；支持别名 ZAI_API_KEY）

• GEMINI_API_KEY（用于 google/...）

  • 同时接受别名 GOOGLE_GENERATIVE_AI_API_KEY 和 GOOGLE_API_KEY

OpenAI 兼容聊天补全开关：

• OPENAI_USE_CHAT_COMPLETIONS=1（或在配置中设置 openai.useChatCompletions）

UI 主题：

• SUMMARIZE_THEME=aurora|ember|moss|mono
• SUMMARIZE_TRUECOLOR=1（强制启用 24-bit ANSI）
• SUMMARIZE_NO_TRUECOLOR=1（禁用 24-bit ANSI）

OpenRouter（OpenAI 兼容）：

• 设置 OPENROUTER_API_KEY=...
• 建议通过模型 ID 显式指定 OpenRouter：--model openrouter/<author>/<slug>
• 内置预设：--model free（使用一组默认的 OpenRouter :free 模型）

summarize refresh-free

快速开始：将 free 设为默认（同时保留 auto 可用）

summarize refresh-free --set-default
summarize "https://example.com"
summarize "https://example.com" --model auto

该命令会重新生成 free 预设（即 ~/.summarize/config.json 中的 models.free），具体步骤如下：

• 获取 OpenRouter /models 接口数据，筛选出 :free 模型
• 默认跳过明显较小的模型（根据模型 ID/名称推断参数量 <27B）
• 并发测试（并发数 4，超时 10 秒）哪些模型能返回非空文本
• 混合选择“较智能”（上下文长度/输出上限更大）和“较快”的模型
• 优化响应时间并写回排序后的列表

如果 --model free 停止工作，请运行：

summarize refresh-free

参数说明：

• --runs 2（默认）：对每个选定模型额外进行 N 次计时测试（总次数 = 1 + runs）
• --smart 3（默认）：优先选择多少个“较智能”的模型（其余由最快模型填充）
• --min-params 27b（默认）：忽略推断参数量小于 N 十亿的模型
• --max-age-days 180（默认）：忽略超过 N 天未更新的模型（设为 0 可禁用）
• --set-default：同时在 ~/.summarize/config.json 中设置 "model": "free"

示例：

OPENROUTER_API_KEY=sk-or-... summarize "https://example.com" --model openrouter/meta-llama/llama-3.1-8b-instruct:free
OPENROUTER_API_KEY=sk-or-... summarize "https://example.com" --model openrouter/minimax/minimax-m2.5

如果你的 OpenRouter 账户设置了允许的提供商列表，请确保所选模型至少有一个提供商被允许。路由失败时，summarize 会打印出需要允许的具体提供商。

旧版兼容：设置 OPENAI_BASE_URL=https://openrouter.ai/api/v1（并提供 OPENAI_API_KEY 或 OPENROUTER_API_KEY）也可工作。

NVIDIA API Catalog（OpenAI 兼容；提供免费额度）：

• 设置 NVIDIA_API_KEY=...
• 可选：NVIDIA_BASE_URL=https://integrate.api.nvidia.com/v1
• 免费额度：注册后 API Catalog 试用账户初始赠送 1000 点免费 API 积分（通过 API Catalog 个人资料页的 “Request More” 最多可增至 5000 点）
• 从 /v1/models 中选择模型 ID（例如：快速模型 stepfun-ai/step-3.5-flash，较强但较慢的 z-ai/glm5）

export NVIDIA_API_KEY="nvapi-..."
summarize "https://example.com" --model nvidia/stepfun-ai/step-3.5-flash

Z.AI（OpenAI 兼容）：

• Z_AI_API_KEY=...（或 ZAI_API_KEY=...）
• 可选基础 URL 覆盖：Z_AI_BASE_URL=...

可选服务：

• FIRECRAWL_API_KEY（网站内容提取后备）
• YT_DLP_PATH（用于音频提取的 yt-dlp 二进制路径）
• GROQ_API_KEY（Groq Whisper 转录）
• ASSEMBLYAI_API_KEY（AssemblyAI 转录）
• GEMINI_API_KEY / GOOGLE_GENERATIVE_AI_API_KEY / GOOGLE_API_KEY（Gemini 转录）
• OPENAI_API_KEY / OPENAI_WHISPER_BASE_URL（OpenAI Whisper 转录）
• FAL_KEY（通过 FAL AI API 使用 Whisper 进行音频转录）
• APIFY_API_TOKEN（YouTube 转录后备）

模型限制（Model limits）

CLI 使用 LiteLLM 模型目录来获取模型限制（例如最大输出 token 数）：

• 下载自：https://raw.githubusercontent.com/BerriAI/litellm/main/model_prices_and_context_window.json
• 缓存位置：~/.summarize/cache/

库的使用方式（可选）

推荐（依赖最少）：

• @steipete/summarize-core/content
• @steipete/summarize-core/prompts

兼容性版本（会引入 CLI 的依赖）：

• @steipete/summarize/content
• @steipete/summarize/prompts

开发

pnpm install
pnpm check

更多内容

• 文档索引：docs/README.md
• CLI 提供商与配置：docs/cli.md
• 自动模型规则：docs/model-auto.md
• 网站内容提取：docs/website.md
• YouTube 处理：docs/youtube.md
• 媒体处理流水线：docs/media.md
• 配置结构与优先级：docs/config.md

故障排查

• “Receiving end does not exist”（接收端不存在）：Chrome 尚未注入内容脚本（content script）。
  • 扩展详情 -> 站点访问权限 -> 设置为“在所有站点上”（或允许当前域名）
  • 刷新一次页面标签页。
• “Failed to fetch”（获取失败）/ 守护进程（daemon）不可达：
  • 执行命令：summarize daemon status
  • 日志位置：~/.summarize/logs/daemon.err.log

许可证：MIT

Summarize 快速上手指南

环境准备

• Node.js：需 Node 22 或更高版本（推荐使用 nvm 管理）
• 可选依赖（用于媒体处理）：
  • ffmpeg：处理音视频
  • yt-dlp：下载 YouTube 视频
  • tesseract：OCR 文字识别（用于幻灯片）

💡 国内用户建议通过 Homebrew 安装依赖（macOS/Linux）或使用清华源加速 npm：

npm config set registry https://registry.npmmirror.com

安装步骤

1. 安装 CLI 工具（任选其一）

# 使用 npm（推荐，跨平台）
npm i -g @steipete/summarize

# 或使用 Homebrew（仅 macOS arm64）
brew install steipete/tap/summarize

2. （可选）安装浏览器扩展

• Chrome 用户：Chrome 应用商店安装
• 安装后打开侧边栏，复制显示的 token
• 在终端运行（替换 <TOKEN>）：

  summarize daemon install --token <TOKEN>
  

  此步骤会启动本地后台服务，供浏览器扩展调用媒体处理能力。

3. （可选）安装媒体处理工具（如需处理视频/幻灯片）

# macOS (Homebrew)
brew install ffmpeg yt-dlp tesseract

# Ubuntu/Debian
sudo apt install ffmpeg yt-dlp tesseract-ocr

基本使用

最简示例

# 总结网页
summarize "https://example.com"

# 总结本地 PDF
summarize "./report.pdf"

# 从剪贴板总结（macOS）
pbpaste | summarize -

# 总结 YouTube 视频（自动提取字幕+幻灯片）
summarize "https://youtu.be/dQw4w9WgXcQ" --youtube auto

常用参数

# 指定摘要长度（short/medium/long/xl/xxl 或字符数）
summarize "https://example.com" --length long

# 强制生成摘要（即使原文很短）
summarize "https://example.com" --force-summary

# 指定模型（格式：<provider>/<model>）
summarize "https://example.com" --model google/gemini-3-flash

# 提取内容但不总结（仅 URL）
summarize "https://example.com" --extract

✅ 提示：首次使用建议先尝试 summarize "https://example.com" 验证安装是否成功。