OpenViking vikingbot summarize 技能实战：URL、本地文件与 YouTube 的一键摘要与转写指南-酒店常州论坛

OpenViking vikingbot summarize 技能实战：URL、本地文件与 YouTube 的一键摘要与转写指南

【免费下载链接】OpenVikingSelf-evolving Context Database for AI Agents. Unify Agent Memory, Knowledge RAG and Skills.项目地址: https://gitcode.com/GitHub_Trending/op/OpenViking

summarize是 OpenViking 仓库内 vikingbot 内置工作区技能（Skill）之一，其定义位于 bot/workspace/skills/summarize/SKILL.md。它以summarize.shCLI 为核心，让 Agent 能够在对话中直接对网页 URL、本地文件（PDF 等）以及 YouTube 视频执行摘要或最佳努力转写（best-effort transcript），无需依赖yt-dlp等额外工具。读完本文，你将掌握该技能的触发方式、命令行用法、模型与 API Key 配置、常用 flag、配置文件结构，以及它在 vikingbot 技能加载体系中的底层工作机制。

技能是什么：一段给 Agent 的指令，而不是一段普通脚本

在 vikingbot 中，Skill 是一份 Markdown 指令文件（SKILL.md），用来教会 Agent“如何完成某一类任务”，区别于代表“具体操作”的 Tool（JSON Schema 函数）。二者关系与运行机制在 bot/docs/en/concepts/02-agent-capabilities.md 中有明确说明：

Skill告诉 Agent 如何完成一类任务，形式是SKILL.md指令与资源；Tool让 Agent 执行一次具体操作，形式是注册给模型的 JSON Schema 函数。

summarize技能位于仓库 bot/workspace/skills 目录下，与其他内置技能（github、weather、tmux、skill-creator等）并列，总览见 bot/workspace/skills/README.md。

SKILL.md 的结构与 frontmatter

每个技能目录下的SKILL.md由两部分组成：YAML frontmatter（元数据）与面向 Agent 的 Markdown 指令正文。summarize技能的 frontmatter 如下：

--- name: summarize description: Summarize or extract text/transcripts from URLs, podcasts, and local files (great fallback for "transcribe this YouTube/video"). homepage: https://summarize.sh metadata: {"vikingbot":{"emoji":"🧾","requires":{"bins":["summarize"]},"install":[{"id":"brew","kind":"brew","formula":"steipete/tap/summarize","bins":["summarize"],"label":"Install summarize (brew)"}]}} ---

这段元数据承载了 vikingbot 技能系统识别与过滤该技能所需的全部关键信息：

name：技能名，与目录名一致（summarize）；
description：技能用途描述，会被加载器展示给模型，帮助模型在合适的场景选中该技能；
homepage：上游工具summarize.sh的官方主页；
metadata.vikingbot：vikingbot 专有元数据，包含：
- emoji：展示用图标（🧾）；
- requires.bins：该技能运行所依赖的可执行命令（这里是summarize）；
- install：安装指引（macOS 下可通过brew安装steipete/tap/summarize）。

注意metadata是一个 JSON 字符串。在 bot/vikingbot/agent/skills.py 中，_parse_vikingbot_metadata专门处理这种“scoped or plain”的元数据：先尝试当作 dict，否则用json.loads解析字符串，最终从vikingbot作用域中取出配置。

依赖检查：summarize 未安装时技能会被标记为不可用

requires.bins不是摆设。在 bot/vikingbot/agent/skills.py 的_check_requirements中，加载器会遍历requires.bins并通过shutil.which检查对应命令是否存在，同时对requires.env中的环境变量做os.environ.get检查；任一依赖不满足，该技能就会被判定为不可用。

这意味着：如果用户机器上没有安装summarize命令，Agent 看到的就是available="false"的技能。此时构建 skills 摘要时，加载器会通过_get_missing_requirements（skills.py）输出缺失项（例如CLI: summarize），子代理 prompt 中也会提示“可以尝试用 apt/brew 安装依赖”。因此，第一步通常是安装 CLI：

brew install steipete/tap/summarize

这一“依赖检查 + 缺失提示 + 允许 Agent 自行安装”的行为，由 bot/tests/test_skills_metadata.py 中的test_skill_requirements_support_nested_yaml用例做了回归验证。

何时使用：触发短语

SKILL.md明确列出了 Agent 应立即使用该技能的触发场景：

用户说“use summarize.sh”；
用户问“what’s this link/video about?”（这个链接/视频讲什么）；
用户要求“summarize this URL/article”（摘要这个 URL/文章）；
用户要求“transcribe this YouTube/video”（转写这个 YouTube 视频）——技能会做最佳努力转写，无需yt-dlp。

也就是说，无论用户想要“网页摘要”“本地文件摘要”还是“视频转写/摘要”，Agent 都应优先调用summarize技能完成任务。

快速上手：三条核心命令

技能文档给出的 Quick start 示例：

summarize "https://example.com" --model google/gemini-3-flash-preview summarize "/path/to/file.pdf" --model google/gemini-3-flash-preview summarize "https://youtu.be/dQw4w9WgXcQ" --youtube auto

第一个参数是目标：URL 或本地文件路径；
--model显式指定用于摘要的模型；
处理 YouTube 链接时需要--youtube auto，让工具决定最佳处理方式。

summarize的模型标识采用provider/model形式，例如google/gemini-3-flash-preview、openai/gpt-5.2，便于在不同厂商之间切换。

YouTube：摘要与转写的区别

对 YouTube 视频，技能区分两种产出：

最佳努力转写（仅对 URL 有效）：

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

--extract-only表示只抽取文本/字幕内容而不生成摘要，相当于“把视频内容变成文字”。

处理超大转写结果的策略：技能文档特别叮嘱 Agent——如果用户要的是转写、但结果非常庞大，应先返回一个紧凑的摘要，再询问用户希望展开哪个段落/时间范围。这是一条重要的交互规范：避免一次性输出海量文本淹没对话，同时保留按需深挖的能力。

模型与 API Key 配置

summarize支持多家大模型厂商，对应 API Key 环境变量如下：

厂商	环境变量
OpenAI	`OPENAI_API_KEY`
Anthropic	`ANTHROPIC_API_KEY`
xAI	`XAI_API_KEY`
Google	`GEMINI_API_KEY`（别名：`GOOGLE_GENERATIVE_AI_API_KEY`、`GOOGLE_API_KEY`）

默认模型：若未通过--model指定，默认使用google/gemini-3-flash-preview。

使用前只需为所选厂商设置对应的环境变量即可，例如：

export GEMINI_API_KEY="your-key" summarize "https://example.com" # 使用默认模型 google/gemini-3-flash-preview

常用 flag 一览

技能文档列出的实用参数：

Flag	作用
`--length short\\|medium\\|long\\|xl\\|xxl\\|<chars>`	控制摘要长度，可选预置档位或直接指定字符数
`--max-output-tokens <count>`	限制输出 token 上限
`--extract-only`	仅抽取文本/转写，不生成摘要（仅 URL 有效）
`--json`	输出机器可读的 JSON 格式
`--firecrawl auto\\|off\\|always`	使用 Firecrawl 作为兜底抽取方案（用于被拦截的站点）
`--youtube auto`	YouTube 处理模式；设置`APIFY_API_TOKEN`时可用 Apify 作为兜底

组合使用示例：

# 生成 JSON 格式、长度 medium 的摘要 summarize "https://example.com" --length medium --json # 对被反爬拦截的站点启用 Firecrawl 兜底 summarize "https://blocked-site.com" --firecrawl auto

配置文件：`~/.summarize/config.json`

可选配置文件为~/.summarize/config.json，可在不修改命令行的情况下固化默认参数。技能文档给出的最小示例：

{ "model": "openai/gpt-5.2" }

即在配置文件中设置默认模型为openai/gpt-5.2；此后不带--model调用时，将优先使用配置中的模型（命令行显式传入的参数仍可覆盖配置）。

可选服务

FIRECRAWL_API_KEY：用于被封锁/反爬站点的兜底抽取（对应--firecrawl）；
APIFY_API_TOKEN：用于 YouTube 处理的 Apify 兜底（对应--youtube auto）。

两个都是可选增强项：不设置时，普通 URL 与 YouTube 链接的基本处理依然可用，设置后能提升对复杂站点的成功率。

技能在 vikingbot 中如何被加载与使用

理解了 CLI 用法之后，再看仓库源码，能完整还原该技能在 Agent 运行时中的生命周期。

渐进式加载：先摘要、按需读全文

vikingbot 的技能采用**渐进式加载（progressive loading）**策略，见 bot/docs/en/concepts/02-agent-capabilities.md：

每一轮对话都会携带 Always Skills 的完整内容；其他技能只贡献 name、description 和 path，直到 Agent 用read_file读取完整内容。

落实到代码上：SkillsLoader.build_skills_summary（skills.py）会为每个可用技能生成如下形式的 XML 摘要块，塞进系统提示：

<skills> <skill available="true"> <name>summarize</name> <description>Summarize or extract text/transcripts from URLs, podcasts, and local files ...</description> <location>skills/summarize/SKILL.md</location> </skill> </skills>

summarize技能没有always: true标记，因此它属于“按需加载”类：模型先看到名称与描述，判断任务匹配后才调用read_file读取 skills/summarize/SKILL.md 的完整指令（包括上面提到的各条命令与触发规范），再执行exec调用summarizeCLI。

工作区技能 vs 内置技能：同名时工作区优先

SkillsLoader.load_skill（skills.py）的查找顺序是：先查当前工作区的skills/<name>/SKILL.md，找不到再查内置目录BUILTIN_SKILLS_DIR（即仓库中的bot/workspace/skills）。因此用户可以放置同名技能到自己的工作区来覆盖内置行为。

主 Agent 与子代理都能使用技能

该技能体系同样适用于后台子代理：SubagentManager._build_subagent_skills_context（bot/vikingbot/agent/subagent.py）会为主 Agent 和子代理构造一致的技能上下文——先注入always技能的完整内容，再注入所有可用技能的摘要清单，并提示“Skill 的可用性为 false 时需要先安装依赖，可尝试 apt/brew 安装”。这与技能 frontmatter 中的install（brew install steipete/tap/summarize）形成了闭环：依赖缺失 → 技能标记不可用 → Agent 依据安装指引自行安装 → 技能变为可用。

技能的边界：不自动获得额外权限

需要强调的是，技能只提供“做法的指导”，不自动授予额外能力。正如 bot/docs/en/concepts/02-agent-capabilities.md 所述，一个 Skill 可以编排多个 Tool，但它不会自动获得额外权限；工具可见性仍取决于运行时模式、渠道设置、请求参数与沙箱策略。也就是说，即使summarize技能要求调用 CLI，Agent 仍需要拥有exec工具权限（受沙箱后端约束）才能真正执行summarize命令。

完整实战流程：从“用户提问”到“返回摘要”

综合以上所有机制，一次典型的 summarize 调用在 vikingbot 中的完整链路如下：

用户在任意接入渠道提问：“这个链接讲了什么？”；
vikingbot 构建上下文时，通过SkillsLoader.build_skills_summary将summarize的名称、描述注入系统提示；
模型判断任务匹配summarize技能（description 中的触发语义命中），用read_file读取 bot/workspace/skills/summarize/SKILL.md 获取完整指令；
模型按指令通过exec执行summarize "<url>" [--model ...] [--length ...]；
若目标为 YouTube 且用户要转写，则追加--youtube auto --extract-only；结果过大时先给紧凑摘要再询问展开范围；
工具返回结果，Agent 将摘要以自然语言回复给用户。

对于需要长时间运行的批量摘要，还可以利用spawn将任务交给后台子代理执行（子代理同样具备技能上下文，见 subagent.py），完成后通过消息总线向主会话汇报结果。

小结

summarize技能把summarize.sh这个轻量 CLI 无缝接入了 vikingbot 的技能体系：通过标准化的SKILL.mdfrontmatter 声明依赖与安装方式，借助渐进式加载让 Agent 按需读取指令，并依赖exec沙箱完成真实调用。无论是网页文章、本地 PDF，还是 YouTube 视频的摘要与转写，用户都只需在对话中自然表达，Agent 即可自行完成工具选择、命令拼接与结果组织，是一条开箱即用的 Agent 内容理解能力。

如需进一步了解技能机制的底层实现，可继续阅读 bot/vikingbot/agent/skills.py、bot/vikingbot/agent/subagent.py 以及相关回归测试 bot/tests/test_skills_metadata.py、bot/tests/test_subagent_skills_context.py。

【免费下载链接】OpenVikingSelf-evolving Context Database for AI Agents. Unify Agent Memory, Knowledge RAG and Skills.项目地址: https://gitcode.com/GitHub_Trending/op/OpenViking

创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考

企业官网建设流程全解析