ollos-mcp

ollos-mcp

AI Agent 的眼睛和耳朵。 本地离线转录、关键帧提取、屏幕文字识别，以及发布前审核，适用于任何音频、视频或图像——可作为 MCP 服务、CLI 和 Node 库使用。无需 Python、云服务或 API 密钥。

文档： 工具参考 · 设计文档——决策与测量 · 评估结果 · 贡献指南 · 安全 · 更新日志

11 分钟的屏幕录制会变成 14 张缩略图集和 3 KB 的文本。它还能告诉你 API 密钥是否在 2:50 时出现在屏幕上。

npx ollos-mcp            # MCP server on stdio
npx ollos review talk.mp4

Ollos 在加利西亚语中意为眼睛。

---

目录： 为什么 · 安装 · 工具 · 来源 · CLI · 库 · 工作原理及测量结果 · 评估 · 要求与性能 · 隐私与安全 · 配置 · 故障排除 · 已知限制 · 路线图

为什么

Agent 无法听见或观看内容。目前，你要么付费使用转录 API，要么安装 Python 流水线，要么手动粘贴画面帧。Ollos 通过 ONNX Runtime 在你的设备上使用 Node 运行 Whisper、说话人分段、基于感知哈希的关键帧提取和 OCR。文件不会离开设备。

它最初是为一种工作流打造的——发布前审核屏幕录制——后来扩展到更多场景：会议、课程、播客和下载的视频。

安装

需要 Node 20+。npm install 会自带 ffmpeg（ffmpeg-static）；如果系统中已安装 ffmpeg，则会优先使用。

Claude Code

claude mcp add ollos -- npx -y ollos-mcp

也可以在项目的 .mcp.json 中配置（相同的 JSON 也适用于 Claude Desktop 的 claude_desktop_config.json、Cursor 的 .cursor/mcp.json 和 Windsurf 的 mcp_config.json）：

{
  "mcpServers": {
    "ollos": { "command": "npx", "args": ["-y", "ollos-mcp"] }
  }
}

VS Code — .vscode/mcp.json 使用 servers，而不是 mcpServers：

{
  "servers": {
    "ollos": { "type": "stdio", "command": "npx", "args": ["-y", "ollos-mcp"] }
  }
}

在 macOS 上，Claude Desktop 会读取 ~/Library/Application Support/Claude/claude_desktop_config.json；在 Windows 上会读取 %APPDATA%\Claude\claude_desktop_config.json。环境变量（OLLOS_HOME、OLLOS_YTDLP 等）应放在与 args 同级的 env 对象中；请使用绝对路径，~ 不会展开。

CLI

npm i -g ollos-mcp
ollos warmup            # download the default ASR model and VAD (2.75 GB)
ollos warmup --all      # every model: fast ASR, speakers, search, OCR data (3.3 GB total)
ollos doctor            # check ffmpeg, models, free memory, cores

模型会在首次使用时下载到 ~/.ollos/models。之后设置 OLLOS_OFFLINE=1 即可禁止所有网络访问。

工具

共有十种工具，每种对应一种不同的契约。长时间运行的任务不会阻塞：会返回一个 jobId，供你轮询。

工具	功能
ollos_probe	判断文件的真实信息：类型、时长、分辨率、宽高比（以及适配的平台）、编解码器和轨道。可检测 Zoom 录制文件夹。即时完成。
ollos_transcribe	使用 Whisper 进行转录并添加时间戳。通过语音活动门控跳过静音；过滤已知幻觉；使用 vocabulary 修正领域术语。
ollos_keyframes	提取承载信息的帧，并整理成带时间戳的 3×3 联系表。适用于场景检测无法识别画面的屏幕录制。
ollos_read_screen	OCR 识别屏幕文字，并进行机密扫描：API 密钥、JWT、.env 行、私有部署 URL。始终会屏蔽机密信息。
ollos_review	发布前给出评估：响度与平台要求的对比、待剪除的静音、宽高比、屏幕上的机密信息。
ollos_frames	将一张联系表或单帧作为图像查看。
ollos_diarize	判断谁在何时说话：pyannote 分段 + WeSpeaker 嵌入 + 聚类，并为每位说话者提供一段 8 秒的语音片段，让你通过听声音辨认。若有 Zoom 按参与者分轨的录音，则直接使用这些轨道。实验性功能——详见限制。
ollos_search	使用 BM25 与多语言嵌入，对所有转录和读取内容进行混合搜索，并通过倒数排名融合结果。返回带时间戳的段落，而非完整转录文本。
ollos_job · ollos_cancel	轮询并停止任务。任务存储在磁盘上，服务器重启后仍会保留。

所有参数均记录在 docs/TOOLS.md 中（每个工具各有一个锚点，例如 ollos_transcribe）；Agent 看到的工具说明也包含相同信息。

来源

source 接受本地路径、file:// URL、Zoom 本地录制文件夹（每位参与者各有一条音轨）、直接的 https:// 媒体 URL、视频站点 URL（YouTube、Instagram、TikTok、Vimeo、X、Loom……通过 yt-dlp）以及 data: URI。URL 只会下载一次并缓存；下载在任务中运行，且可以取消。以下情况会被拒绝：任意重定向跳转中的私有、环回和链路本地地址（允许时设置 OLLOS_ALLOW_PRIVATE=1）；超过 OLLOS_MAX_DOWNLOAD_MB 限制的下载；来自任何来源且超过 OLLOS_MAX_DURATION_SEC 限制的媒体。

ollos transcribe "https://www.youtube.com/watch?v=eur8dUO9mvE" --lang en --from 0 --to 30

已测试的命令、yt-dlp 配置和代理说明：examples/url-sources.md。

结果默认简洁，并指向 MCP 资源（ollos://jobs/<id>/transcript、/ocr、/report、/sheet/<n>）以获取完整内容，避免两小时的会议记录塞满上下文窗口。需要完整内容时，传入 format: "detailed"。

CLI

ollos probe recording.mp4
ollos transcribe meeting.mp4 --lang pt --vocab "Claude Code,n8n,webhook"
ollos keyframes lesson.mp4 --sensitivity normal --max-frames 120
ollos read-screen demo.mp4
ollos review episode.mp4 --platform youtube     # exit 3 = block, 1 = warn or failure, 2 = usage error, 0 = ok
ollos jobs · ollos job <id> · ollos events <id> · ollos cancel <id>

添加 --json 以输出机器可读内容。

库

import { createOllos, type TranscribeResult } from 'ollos-mcp'

const ollos = createOllos()
const { job, result } = await ollos.transcribe({ source: 'talk.mp4', language: 'pt', vocabulary: ['MCP'] })
const transcript = result ?? (await ollos.wait<TranscribeResult>(job.id)).result // inline when small, a job otherwise
console.log(transcript?.segments[0])

更多示例：examples/library.ts（涵盖所有功能）和 examples/library-url.ts（以 YouTube URL 作为来源）。

ollos-mcp/core 不依赖 MCP：可在 n8n、脚本或 Lambda 中使用。

工作原理及测量结果

以下数据是在一台 16 核笔记本电脑上，对一段 11:37 的录屏（1890×1080，带摄像头画中画）进行测量得出的。这些数据也说明了为何设计如此。

转录。 Silero VAD 标记语音；Whisper 只处理语音（幻觉更少，会议处理量减少 20–40%）。whisper-large-v3-turbo 的速度为实时速度的 1.7 倍，能正确识别“MCP servers”“n8n”和“VS Code”；而 whisper-base（5.4 倍）这三个都识别错了。唯一遗留的语音识别错误“Cloud Code”通过 vocabulary 修正。实测发现，两个 Whisper 会话并行运行反而更慢（0.6–1.0 倍），因此 ASR 并发数设为 1，速度提升则来自 VAD 和并行运行视觉处理。

防止幻觉。 静音时，Whisper 不会安静下来——它会编造“Obrigado.”和“Subtitles by the Amara.org community”。根据 Vexa 项目分享的生产经验，采用了四种过滤方式：按语言精确屏蔽、折叠重复循环、无语音门控，以及不可能的语速检测。

关键帧。 ffmpeg 场景检测在 11 分钟的录屏中仅保留了4 帧；mpdecimate 没有移除任何帧（光标和流式文本会改变每一个像素）。采用 64 位感知哈希（dHash）并设置汉明距离 ≥ 6 后，保留了 20% 的帧——每 5–8 秒一帧，这就是默认设置。硬切换、转录锚点和 20 秒下限用于填补空缺。

OCR。 Tesseract 在完整的 1890 像素帧上完全漏掉了屏幕上的 URL；而在放大 3 倍的图块上，它以 90% 的置信度在 2.8 秒内完整读出了 URL。因此 OCR 按图块运行，并会在 OCR 拆分类似 URL 的文本时重新拼接（“up. railway .app”）。

机密信息。 由于 OCR 识别机密信息时出错的频率高于其周围的文字，因此使用三种信号。在一个真实的“API Key Created”模态框中，普通 JWT 正则表达式未能识别（OCR 将 eyJ 读成了 eyl），熵检测器则捕获了这个 157 个字符的令牌，上下文 UI 读取的置信度为 66%。采用容错 OCR 的 JWT 模式、原生分辨率帧和中心图块后，端到端运行现在会将其报告为 high · jwt · near "API Key" → block。第一版还产生了 58 个误报，因为它对移除空白后的文本运行熵检测；现在这已成为回归测试。值始终会被遮蔽；用于警告泄漏的工具绝不能自身泄漏。

对于这项特定检查，基于变化检测的关键帧并不合适：凭据在不变的屏幕上留存一分钟，只会生成一个 dHash 候选帧，而帧数上限的剪枝步骤曾以与真正冗余帧相同的条件丢弃这唯一的候选帧——这是一次真实漏检，已记录为 #3。ollos_review 的机密信息检查现在会以固定的 4 秒间隔读取屏幕，无论画面是否发生变化；通过帧数上限（preserveFloor）确保这一点，并在发现结果中说明实际覆盖情况——正常长度的录制会显示 Read the full 11:37 at a 4s cadence，超长录制则会显示受 OLLOS_MAX_FRAMES 限制的明确说明 Partial coverage: …，而不是给出看似干净、却悄悄检查了更少内容的结论。

说话人。 单独进行分段时，一段只有一人的视频被标记为三名说话人（其 ID 仅在各自的 10 秒窗口内有效）。对每个时长 ≥ 1.5 秒的轮次生成嵌入，采用余弦距离 0.35 进行平均连接聚类，并合并极小簇后，结果变为一名说话人。随后评估揭示了真正的失败模式：同一声音在不同位置和时长下与自身的相似度为 0.58–0.86，但背景音乐一旦叠加，相似度就会降至 0.06–0.16，因此无论阈值如何设置，短促的音乐或片尾曲都会成为自己的“说话人”。该工具仍处于实验阶段，并会在输出中明确说明。

任务。 客户端超时时间较短（Messages API 约 60 秒）。每个耗时较长的工具都会返回一个任务句柄；状态保存在 ~/.ollos/jobs/<id>/job.json 中，以原子方式写入，并每 5 秒发送一次心跳。重启时，孤立任务会变为 interrupted，而不是无限期挂起。预计耗时较短（< 8 秒）的工作会内联运行并直接返回。

评估

npm run eval 会在公开视频上运行 ollos，并将结果写入 eval/RESULTS.md。参考转录文本来自 YouTube 字幕，因此对于自动生成字幕的测试样本，WER 表示两个识别器之间的一致率，而非绝对错误率。

测试样本	类型	参考文本	WER	CER	说话人（预期 → 检出）
IBM Technology，什么是 MCP？（en，3:46）	灯光板讲解	专业字幕	1.4%	0.5%	1 → 2（片尾音乐）
Karine Lago，n8n 助手（pt，10:35）	屏幕录制	自动生成字幕	8.9%	6.1%	1 → 1
Bolder Podcast，开发者访谈（pt，5:28）	访谈	自动生成字幕	26.3%	17.0%	2 → 3（提示音）

在访谈中，一半的“错误”是插入错误：Whisper 保留了自动生成字幕省略的重复内容和语气词，而且好几个参考词是字幕错误（例如把 Glassdoor 写成“Clash Orto”，而 ollos 识别正确）。关键帧将 10 分钟的屏幕录制缩减为 14 张图纸上的 120 帧，将讲解缩减为 6 张图纸上的 51 帧。在那次运行中，机器负载较高，速度为实时速度的 0.2–0.35 倍；同一模型在单独运行时测得的速度为 1.7 倍。复现方法以及各项数字的含义见 eval/README.md。

要求和性能

在评估测试样本上测量，进程内存每 200 ms 采样一次（scripts/probe-memory.mts）。机器：Intel i9-12900HX（16 核）、Windows 11、Node 20，同时其他进程约占用 18% 的 CPU。

项目	磁盘（模型）	进程内存峰值	速度
不带 OCR 的 ollos_probe、ollos_keyframes、ollos_review	无	~200 MB	关键帧：约 15 s 处理 2 min 视频
转录，model: "fast"（whisper-base）	280 MB	~1.9 GB	加载后约 15 s 处理 60 s 音频（约为实时速度的 4 倍）
转录，默认设置（whisper-large-v3-turbo，fp32 编码器 + q4 解码器）	2.75 GB	~4.3 GB	约 46 s 处理 60 s 音频（约为实时速度的 1.3 倍；空闲机器上为 1.7 倍）
+ ollos_diarize（pyannote + WeSpeaker）	+32 MB	+0.1 GB	加载后约 5 s 处理 60 s 音频
+ ollos_search（multilingual-e5-small）	+465 MB	+0.8 GB	每份转录文本约 4 s 构建索引
带 OCR 的 ollos_read_screen / review（2 个 Tesseract 工作进程）	8 MB	+0.3 GB	原始分辨率下每帧约需 1–3 s，具体取决于 CPU
同时加载所有内容	3.3 GB	~5.1 GB

由此得出的最低要求：默认模型需要 8 GB RAM（model: "fast" 使用 4 GB 即可），所有模型需要 4 GB 可用磁盘空间，CPU 可以是任意 x64 或 arm64 架构（不使用 GPU）。转录速度随 CPU 核心数提升，是唯一受计算能力限制的阶段；使用默认模型时，4 核笔记本的速度预计约为实时速度的 0.4 倍，因此一小时的会议需要两个多小时，使用 model: "fast" 则约需 40 分钟。

模型会在服务进程的整个生命周期内保持加载状态；目前空闲时不会卸载任何内容。过去内存峰值约为 10 GB：transformers.js 的文件缓存会将 2.4 GB 的编码器权重流式传输到无人读取的 JavaScript 缓冲区中，除此之外还有 ONNX Runtime 自己的内存映射副本。现在 ollos 会直接将模型路径交给 ONNX Runtime（参见 src/core/models.ts 中的 PathCache）。设置 OLLOS_DEBUG_MEM=1 可在每个作业事件中记录进程内存，并使用 ollos events <id> 查看这些记录。

内存限制

目前没有内存上限设置，而且只要服务进程运行，模型就不会卸载。 使用默认模型运行 ollos_transcribe 后，进程会一直占用约 4.3 GB 内存，直到退出；再加上搜索功能后，会一直占用约 5.1 GB。这是为了提升速度而有意做出的取舍（冷启动加载默认模型需要 50–60 s），也是 0.1.0 版本的实际情况。

目前你可以控制以下各项：

调节项	效果
每次调用设置 model: "fast"	占用约 1.9 GB，而不是约 4.3 GB；速度快 3 倍；但会误读技术术语
在任何工具上设置 from / to	限定解码的音频和提取的帧；PCM 和帧的内存占用随时间窗口变化，而非随文件大小变化
OLLOS_MAX_DURATION_SEC（默认 4 h）	拒绝处理时长超过此设置的媒体，并提示使用时间窗口
OLLOS_CONCURRENCY_VISION / _OCR（默认 2）	减少并行运行的 ffmpeg/Tesseract 工作进程数；ASR 始终为 1
OLLOS_MAX_DOWNLOAD_MB（默认 2048）	限制获取的源文件大小
重启服务	目前释放模型内存的唯一方法
ollos doctor	启动前显示可用 RAM 和核心数，并与测得的需求进行比较
OLLOS_DEBUG_MEM=1	为每个作业事件添加 rss、heap 和 arrayBuffers（MB）信息；使用 ollos events <id> 查看

Node 自带的 --max-old-space-size 无济于事：权重存放在 ONNX Runtime 的原生内存中，不属于 V8 堆。

按优先级计划实现以下功能（参见路线图）：

1. 空闲时卸载 — 作业空闲 N 分钟后释放模型（OLLOS_MODEL_IDLE_MIN），并接受下次调用时需要 50–60 s 重新加载。实现成本低；各条处理管线已经采用惰性加载。
2. 内存保护机制 — OLLOS_MAX_MEMORY_MB：加载模型前，将测得的峰值内存与上限和可用 RAM 进行比较；如果超出，则返回明确错误，或在 OLLOS_MEMORY_FALLBACK=fast 时降级为 model: "fast"。src/core/models.ts 中的目录已包含所需的大小数据。

隐私与安全

• 不会上传任何内容。网络仅用于下载一次模型，以及获取你提供的源 URL。
• 获取 URL 时会拒绝私有、环回、链路本地和 IPv6 过渡地址（SSRF），并会在首次请求和每次重定向时进行检查，除非设置了 OLLOS_ALLOW_PRIVATE=1。
• 转录文本和屏幕上的文字会在 <untrusted-content> 中返回——它们是数据，而不是指令。捆绑的技能也会向 Agent 说明这一点。
• 结果、日志和事件中会对发现的机密进行遮蔽；与机密一同返回的 OCR 文本也会使用相同的遮蔽内容进行脱敏——用于警告泄露的工具本身不会造成泄露。
• 在你所在的地区，录制他人需要征得其同意。

配置

变量	默认值	含义
OLLOS_HOME	~/.ollos	作业、缓存、模型
OLLOS_OFFLINE	0	1 表示禁止联网；必须预热模型
OLLOS_ALLOW_PRIVATE	0	允许从私有网络获取内容
OLLOS_MAX_DOWNLOAD_MB	2048	下载上限
OLLOS_MAX_DURATION_SEC	14400	超过此时长的媒体将被拒绝（使用 from/to）
OLLOS_CONCURRENCY_VISION / _OCR / _DOWNLOAD	2	每类任务的并行数（ASR 固定为 1）
OLLOS_MAX_FRAMES	500	每个关键帧作业的帧数硬上限；同时限制 ollos_review 的机密检查按固定间隔可覆盖的超长录制时长（见上文“机密”）
OLLOS_RESPONSE_TOKENS	20000	响应截断前的预算，截断时会附上资源指针
OLLOS_INLINE_THRESHOLD_SEC	8	预计耗时低于此值的任务将内联运行；0 表示始终不内联
OLLOS_FFMPEG / OLLOS_FFPROBE / OLLOS_YTDLP	自动	显式指定二进制文件路径
OLLOS_YTDLP_ARGS	—	适用于每次站点下载的额外 yt-dlp 标志，经过允许列表限制（例如 --no-check-certificates --js-runtimes node）
OLLOS_DEBUG_MEM	0	1 表示为每个作业事件标注进程内存（rss、heap、arrayBuffers，单位为 MB）

从站点（YouTube、Instagram、TikTok 等）下载内容需要将 yt-dlp 放在 PATH 中（或设置 OLLOS_YTDLP），且仅尽力提供支持：平台经常变化。在会重新签署 TLS 的企业代理后使用时，请设置 OLLOS_YTDLP_ARGS="--no-check-certificates"。本地文件始终可用。

故障排除

症状	原因及解决方法
FFMPEG_MISSING	未找到 ffmpeg，且 ffmpeg-static 未能为你的平台安装。请安装 ffmpeg，或设置 OLLOS_FFMPEG / OLLOS_FFPROBE。
YTDLP_MISSING	视频站点 URL 需要 PATH 中有 yt-dlp，或设置 OLLOS_YTDLP。本地文件和直接 URL 无需它即可使用。
YTDLP_FAILED 且出现 CERTIFICATE_VERIFY_FAILED	企业代理重新签署了 TLS。请设置 OLLOS_YTDLP_ARGS="--no-check-certificates"。其他故障：运行 yt-dlp -U，或下载文件并传入其路径。
MODEL_MISSING_OFFLINE	已设置 OLLOS_OFFLINE=1，但模型尚未下载。请在联网时运行一次 ollos warmup --all。
PRIVATE_ADDRESS_BLOCKED	URL（或其返回的重定向）指向私有地址或环回地址。若这是有意设置的，请设置 OLLOS_ALLOW_PRIVATE=1。
DURATION_EXCEEDED	媒体时长超过 OLLOS_MAX_DURATION_SEC（4 小时）。请传入 from/to，或提高上限。
启动时出现 Could not load the "sharp" module using the win32-x64 runtime（或其他平台）	npx 缓存中的安装缺少 sharp 的平台二进制文件（曾在 Windows 上出现过：有 macOS 和 Linux 二进制文件，但缺少 win32-x64）。请清除缓存后重试，或全局安装：npm i -g ollos-mcp，并让客户端使用 ollos-mcp 命令。
客户端报告 JSON 解析错误，或服务“立即退出”	有内容写入了 stdout。服务会保护 stdout，因此这表明安装损坏：运行 node dist/mcp/bin.js，并手动发送一行 initialize（CI 正是这样做的）；运行 npm run smoke:mcp 可复现此问题。
转录速度慢或机器开始使用交换空间	默认模型需要约 4.3 GB 内存和所有 CPU 核心。可使用 model: "fast"（约 1.9 GB），或指定 from/to 时间范围。ollos doctor 会显示可用内存和核心数。
服务被终止后，作业仍保持 running	心跳超过 30 秒后，下一次轮询会将其报告为 interrupted；请重新提交，缓存阶段会复用。

已知限制

• 首次运行会下载 2.75 GB（高精度 ASR），转录时需要约 4.3 GB 内存。model: "fast" 使用 280 MB 模型，约需 1.9 GB 内存，但会误读专业术语。目前没有内存上限；模型在空闲时不会卸载。
• 片段的 confidence 是一种启发式指标（语音覆盖率、语速、过滤器），并非模型概率。
• 源视频中约 8 px 大小的文字已接近 OCR 的识别极限：能否检测到这么小的秘密取决于具体帧，因此 ollos 会读取每次硬切前后的多个帧。再小一些时，UI 上下文信号仍会标记这种情况（能够可靠读取“API Key Created”）。
• ollos_diarize 仍处于实验阶段。带背景音乐的语音（片头、短曲、片尾）与干净语音中的同一声音嵌入距离很远，无论合并阈值如何设置，都会被识别为额外的说话人（在 eval/ 中测得）。严重的串话问题尚未解决。使用 Zoom 的每位参与者独立音轨时，结果准确无误。
• 网站下载依赖于已安装 yt-dlp；目前尚未捆绑独立二进制文件。请参阅 examples/url-sources.md。
• 目前尚未使用进度通知和 MCP Tasks 扩展；如今所有客户端都通过轮询 ollos_job 来交互。

路线图

• 内存：空闲时卸载模型（OLLOS_MODEL_IDLE_MIN），并添加内存保护机制（OLLOS_MAX_MEMORY_MB，可选回退到 model: "fast"）；请参阅 内存限制
• 客户端支持后启用 MCP Tasks 扩展模式（作业引擎已经与协议无关），并支持 notifications/progress
• ollos_diarize：感知音乐的轮次过滤（仅嵌入 VAD 标记为干净语音的轮次，或先运行语音／音乐分类器）、发布基于轮次级标注的 DER、在不同录音间持久保存说话人名称
• 捆绑独立的 yt-dlp，使网站下载无需安装 Python
• 评估：基于轮次级标注的 DER、植入帧中秘密的精确率／召回率、ollos_search 的检索指标（命中率、MRR、NDCG）

致谢

基于 transformers.js 和 onnx-community 移植的模型、tesseract.js、sharp 和 ffmpeg 构建。幻觉屏蔽列表以 Vexa（Apache-2.0）为基础。面向 Agent 的场景感知关键帧技术由 claude-real-video 开创；ollos 采用了不同的方向（审查、说话人、Node），并借鉴了它的联系表构想。

许可证

Apache-2.0 — © 2026 Kelvin Biffi