内容
through-m<!-- mcp-name: io.github.korovin-aa97/talkthrough-mcp -->
[](https://github.com/korovin-aa97/talkthrough-mcp/actions/workflows/ci.yml)
[](LICENSE)
[](pyproject.toml)
[](https://pypi.org/project/talkthrough-mcp/)
[快速开始](#快速开始) · [工具](#工具) · [常见问题](#常见问题) ·
[故障排除](docs/TROUBLESHOOTING.md) · [更新日志](CHANGELOG.md) ·
[贡献](CONTRIBUTING.md)
**AI 代理的反馈摄取。** 记录您的屏幕并讲话；您的代理
会完成其余工作 — 将错误归档，编写规范，构建待办事项。
`talkthrough-mcp` 是一个本地优先的 MCP 服务器，可以将有旁白的屏幕
录像（或任何视频/音频文件）转换为代理准备的结构化数据：
带有时间戳的转录段，场景变化关键帧，屏幕上的 OCR 文本，
以及实时时钟锚定。所有内容都通过惰性检索工具提供，因此
30 分钟的录像不会淹没模型上下文 — 代理会提取确切的
转录片段，时刻包或它需要的帧。
服务器中没有 LLM ，也没有云路径：ffmpeg，faster-whisper 和 RapidOCR 在您的机器上运行，
调用代理带来智能。是什么使它与屏幕录像 SaaS 和
视频分析 MCP 不同：它适用于任意本地文件，它提供代理工作流
（服务器提示 + 示例代理），并将每个时间戳锚定到
**实时时钟** — 因此“我在检查点卡住时说的话”直接映射到
服务器日志的正确窗口。
## 快速开始
一条命令，无需系统依赖：ffmpeg 降级为捆绑构建，
OCR 仅限 pip，whisper 模型在首次使用时自行下载。
<!-- gen:install — generated by scripts/gen_integrations.py; do not hand-edit -->
[](https://cursor.com/en/install-mcp?name=talkthrough&config=eyJjb21tYW5kIjoidXZ4IiwiYXJncyI6WyJ0YWxrdGhyb3VnaC1tY3AiXX0%3D)
[](https://vscode.dev/redirect/mcp/install?name=talkthrough&config=%7B%22command%22%3A%22uvx%22%2C%22args%22%3A5B%22talkthrough-mcp%22XX%7D)
[](https://insiders.vscode.dev/redirect/mcp/install?name=talkthrough&config=%7B%22command%22%3A%22uvx%22%2C%22args%22%3A5B%22talkthrough-mcp%22XX%7D&quality=insiders)
[](https://lmstudio.ai/install-mcp?name=talkthrough&config=eyJjb21tYW5kIjoidXZ4IiwiYXJncyI6WyJ0YWxrdGhyb3VnaC1tY3AiXX0%3D)
[](https://kiro.dev/launch/mcp/add?name=talkthrough&config=%7B%22command%22%3A%22uvx%22%2C%22args%22%3A5B%22talkthrough-mcp%22XX%7D)
[](https://block.github.io/goose/extension?cmd=uvx&arg=talkthrough-mcp&id=talkthrough&name=Talkthrough&description=Turn%20narrated%20screen%20recordings%20into%20agent-ready%20data)
### Claude 代码
两种安装路径 — **选择一种**，而不是两者（插件已经包含
服务器；安装两者会注册两次）：
**仅服务器** — 7 种工具 + 5 种提示，并且系统上没有其他内容。
选择此选项以进行最小化设置，或在多个客户端上自行管理 MCP 服务器：
```bash
claude mcp add -s user talkthrough -- uvx talkthrough-mcp
```
**完整插件** — 相同的服务器，加上原生斜杠命令
（ `/talkthrough:triage-recording`，…）为您处理仪式，
一个现成的分类子代理，以及一个教 Claude 工作流的代理技能。
选择此选项以获得最佳开箱体验：
```bash
/plugin marketplace add korovin-aa97/talkthrough-mcp
/plugin install talkthrough@talkthrough
```
### 每个其他 MCP 客户端
<details>
<summary><b>Claude Desktop</b></summary>
`claude_desktop_config.json`:
```json
{
"mcpServers": {
"talkthrough": {
"command": "uvx",
"args": [
"talkthrough-mcp"
]
}
}
}
```
更多信息： [`integrations/claude-desktop/`](integrations/claude-desktop/)
</details>
<details>
<summary><b>Cursor</b></summary>
`~/.cursor/mcp.json （或项目 .cursor/mcp.json）`:
```json
{
"mcpServers": {
"talkthrough": {
"command": "uvx",
"args": [
"talkthrough-mcp"
]
}
}
}
```
更多信息： [`integrations/cursor/`](integrations/cursor/)
</details>
<details>
<summary><b> Codex CLI</b></summary>
`~/.codex/config.toml受信任项目中的项目范围 .codex/config`:
```tomlcp_servers.talkcommand = "uvx"
args = ["talkcp"]
```
更多信息： [`integrations/code`](integrations/code</details>
<details>
<summary><b>Gemini CLI</b>
`~/./settings.json`:
```{
"m": {
"": {
" "uvx",
args": [
"talkthrough-mcp"
]
}
}
}
```
更多信息：ations/gemini`](integrations/g-cli/)
</details>
<summary><line / Roo 代码></summary>
`cline_mcp_settings.json （ 服务器 UI）`:
```json
{
"mcpServers": {
"talkthrough": {
command": "uvx",
"args": "talkthrough-mcp"
]
}
}
```
更多信息： [`integrations/cl`](integrations/cl</details>
<details>
<summary><b>OpenClaw</b></`~/./openclaw.json`:
```json
{
"": {
"servers": {
"talkthrough": {
"commanduvx",
args": [
"talkthrough-mcp"
}
}
}
```
更多信息： [`integrations/openclaw/`](integrations/openclaw/)
</details>
<detailssummary><b>OpenCode</b></summary>
`opencode.json （项目）或 ~/.config/opencode.json`:
```json
{
"mcp": {
"talkthrough": {
"type": "local",
"command": [
"uvx",
"talkthrough-m ],
"enabled": true
}
}
信息： [`/opencode/`](/opencode/)
</details>
<summary>Goose</b></summary>
`config/goose/config.yaml`:
```yml
extensions talkthrough:
enabled: true
type: stdio
cmd: uvx
argstalkthrough-mcp"]
```
更多信息： [`integrations/goose/`](integrations/goosedetails>
<details>
<summary><b>Gitilot CLI</summary>
`~ilot/mcp-config.json`:
```json
{
mcpServers "talkthrough "command": "uvx",
"args": [
"-mcp"
}
}
}
```
更多信息： [`integropilot-cli/`](integrations/copilot-cli/)
>
<details>
<summary><b>W</b></summary>
`~/.codeiumurf/mcp_config```json
{
mcpServers": {
"talkthrough "command": "uvx",
"args": [
"talkthrough-mcp"
]
}
}
}
```
更多信息： [`/windsurf/`](integrations/windsurfdetails>
<details>
<summary><b></b></summary>
`settings.json （）`:
```json
{
"context_servers": "talkthrough": {
"source": "custom",
"command": {
"path": "uvx",
"args": [
"talkthrough-mcp"
]
}
}
}
}
```
更多信息： [`integrations/`](integrations/zed/)
</details>
MCP stdio 客户端都使用相同的服务器命令：`uvx talkthrough-mcp`。
每个夹都包含片段和验证步骤；
代理可以通过 [`llms-install.md`](llms-install.md) 自行安装。
<!-- /gen:install -->
### 本地检出（开发）
```bash
git clone https://github.com/korovin-aa97/talkthrough-mcp
claude m talkthrough -- uv run --directory /path/to/talkthrough-mcp talkthrough-mcp
```
然后，在您的代理中：
> 处理 `~/Desktop/recording.mov` 并对其进行分类 — 或直接调用
> `triage-recording` 服务器提示。
## 工具
| 工具 | 功能 |
|---|---|
| `process_media(path, recorded_at?, vocabulary?, language?, model?, force?)` | 摄取视频/音频文件：本地 STT，关键帧，OCR，实时时钟。返回紧凑。根据内容哈希，操作是幂等的 — 重新调用是瞬 |
| `cript(job_id,?, end_ms?,` | 分页转录为 `segments`text` 或rt`；返回 `next_start。 |
|_frames(job_id,? \| start_msend_ms?,?, include_duplicates?)` | 关键帧时间戳附近或均匀变薄情况下，唯一帧最多 6 个）。 |
| `get(job_id, start_ms, end_ms)`一个备注”包录片段 + 最3 帧它们的 OCR 文本实时时钟范围| `search(job query)` |文本和屏幕上的本的 substring；点击携带 ``/`t_wall帧引用。 `extract_frame(job at_ms,` | 从源可选裁剪精确时间戳的重新提取（当错过该瞬间时）。 |
| `()` | 最近处理的录像，包含时长时钟开始时间和 |
每个工具描述带 10示例，因此代理无需选择正确的工具。
## 服务器提示（MCP 客户端中的斜杠命令）
| 提示 | 工作流 |
|---|---|
| `triage-recording` | 有旁白的屏幕录像 → 精确的发现 JSON（错误/功能/，帧证据| `spec-from-workshop` | 记录工作坊 → 和开放问题的规范 |
|log-from-demo`演示 → 带有时间戳证据的优先事项待办事项 |
| `meeting-actions` |音频 → 动作项，决策，开放| `cor-with-logs`实时时钟窗口像备注 ↔ 系统日志关联起来 |
相同的在 [`examples/prompts/`](examples/prom中，如果您的客户端不支持 MCP 提示。`triage-recording` 使用的发现合约是
[`examples/output-contract.schema.json`](examples/output-contract.schema.json)。
## 也可以作为技能使用（无需 MCP）
相同的工作流作为跨引擎 [Agent 技能](https://agentskills.io)
位于 [`.agents/skills/talkthrough/`](.agents/skills/talkthrough/) —
Claude Code，Codex CLI（`$talkthrough`），Cursor，Copilot，Gemini CLI，Goose
和其他兼容 SKILL.md 的工具会读取它。没有 MCP 连接的代理可以直接驱动
[CLI](#cli)：`talkthrough-mcp process recording.mov --json` 打印与
MCP 工具返回的相同摘要，并且作业存储共享。
## 实时时钟锚定
每个带时间戳的结果都带有 `t_ms`（相对于视频）和 `t_wall`
（ISO 8601 真实时间），一旦录像开始时间已知。解析阶梯：
1. `recorded_at` 参数（代理/用户覆盖）→ 置信度 `exact`
2. QuickTime `com.apple.quicktime.creationdate` 标签，携带本地
时区（QuickTime Player 录像；⌘⇧5 在 macOS 26 之前写入）→ `high`
3. 容器 `creation_time` 标签（UTC）→ `medium` — macOS 26+ ⌘⇧5/ReplayKit
屏幕录像（不再有 `creationdate` 标签；请在本地时区 `t_wall` 重要时传递
`recorded_at=`）→ `low`
4. 文件修改时间减去时长（录像机在录像结束时最终确定文件）→ `low`
5. 没有 → 工具仍仅使用相对 `t_ms`
为什么它很重要：“上传旋转器在 *这里* 卡住了”变成服务器日志中
的 ±30 秒 grep 窗口。
## 隐私
所有操作都在本地运行：您的录像从未离开您的机器，语音由本地 Whisper 模型转录，
OCR 由本地 ONNX 推理，并且没有遥测数据。唯一的网络访问是一次性工具/模型下载
（ffmpeg 构建，whisper 模型，OCR 模型）。
## 语言
Whisper 支持的 ~99 种语言中的任何一种都有效：语言会在每个录像中自动检测，
摘要报告 `language` 和 `language_probability`，以便代理可以区分自信的检测
和不确定的检测（开始默或音乐可能会使检测器失效 — 如果发生这种情况，
请使用 `ru"` 和 `force=true` 固定）。
为您的语言选择模型 — 按调用（`model=` 参数，代理会自行执行，
当转录返回模糊时）；或作为服务器默认值（`TALKTHROUGH_WHISPER_MODEL`）：
| 模型 | 大小 | 最适合 |
|---|---|---|
| `（默认） | 464 MB | 英语和主要语言叙述在 CPU 上 |
| `large-v3-turbo` | ~1.5 GB | **推荐用于非英语** — 接近大质量接近小速度 |
| `medium` | ~1.5 GB | 保守的 turbo 替代品 |
|` / `base` | 75–145 MB | 快速草稿 |
| `*.en` 变体 | — | 仅限英语，略快/更好，适用于英语 |
每个语言的提示：通过 `vocabulary="Term1, Term2"` 名称
（偏袒解码器，使专业术语存活下来），并且注意工作流提示指示代理
用**讲述者的语言**编写摘要，同时保持引号逐字逐句 —
服务器从不翻译（确切的引用是证据；翻译是代理的任务）文本（OCR）默认为 RapidOCR丁语 + 中文模型。对于其他脚本，
设置 `TALKTHROUGH_OCR_LANG` 为您的语言 — `ru`/`uk`（→ `eslav`
软件包），`ja`，`ko`，`ar`，`hi`，`el`，`th`，或任何 RapidOCR 软件包名称
如 `cyril — 并使用 `force=true` 重新处理；匹配识别模型一次性## 配置
| 环境变量 | 默认值 | 含义 |
|---|---|---|
| `TALKTHROUGH_WHISPER_MODEL` | `small` | 默认 whisper 模型（`tiny`/`base`/`small`/`medium`/`large-v3`/`large-v3-turbo`）；`model` 工具参数覆盖每个调用 |
| `TALKTHROUGH_OCR` | `on` | 设置 `off` 跳过 OCR |
| `TALKTHROUGH_OCR_LANG` | 拉丁语+中文 | 屏幕文本识别脚本：语言代码（`ru`，`ja`，`ko`，`ar`，`hi`，...）或 RapidOCR 软件包名称（`eslav`，`cyrillic`，`latin`，...）；模型一次性下载 |
| `TALKTHROUGH_OCR_PARAMS` | — | 高级：原始 RapidOCR 参数的 JSON 对象合并到派生的参数中，例如 `{ "Rec.lang_type": "cyrillic" }` |
| `TALKTHROUGH_MAX_SECONDS` | `7200` | 最大媒体时长 |
| `TALKTHROUGH_MAX_FRAMES` | `600` | 每个作业的关键帧上限 |
| `TALKTHROUGH_HOME` | `~/.talkthrough` | 作业存储根目录 |
## 命令行界面
该流程也是一个命令行界面 — 在代理会话之外预处理长录像很有用
（存储是内容寻址的，因此代理会立即查询相同的作业）：
```bash
talkthrough-mcp process ~/Videos/long-session.mov # 打印摘要
talkthrough-mcp process demo.mov --json # 机器可读
talkthrough-mcp gc --keep-days 30 # 清理作业存储
talkthrough-mcp serve # 标准输入/输出 MCP 服务器（默认）
```
首次运行注意事项：缺少系统 ffmpeg 会触发一次性 `static-ffmpeg`
下载；首次转录会下载 whisper 模型（~460 MB for
`small`）；两者都缓存。之后，预计在 Apple-Silicon CPU 上，大约比实时快 3 倍，
默认模型包括 OCR（2 分钟剪辑在 ~40 秒内处理）— 即时重新运行
相同的档案。进度流式传输为 MCP 进度通知，CLI 打印阶段行。
更多信息：[docs/TROUBLESHOOTING.md](docs/TROUBLESHOOTING.md)。
## Windows（尽力而为）
CI 在 `windows-latest` 上运行 lint，单元测试和完整的 CLI 烟雾测试
（静态 ffmpeg Windows 构建，whisper `tiny` 转录，OCR 和
即时幂等重新运行）。注意：每个作业的锁是 POSIX `fcntl` 并且
降级为 Windows 上的无操作 — 适用于单用户机器；引用路径
带有空格（`uv run talkthrough-mcp process "C:\Videos\Screen Recording.mp4"`）。
Windows 不是发布门控 — 如果出现问题，请打开一个问题。
## 支持的输入
视频：`.mov` `.mp4` `.webm` `.mkv` — 音频：`.m4a` `.mp3` `.wav` `.ogg`
`.flac`（仅限转录工具；帧工具解释为什么它们不可用）。
仅限本地文件。
## 限制
诚实的边界，以便您可以快速决定：
- **一位扬声器流。** 暂无说话人分离 — “谁说”未跟踪
([#4](https://github.com/korovin-aa97/talkthrough-mcp/issues/4))。
- **仅限本地文件。** 无 URL/YouTube 提取
([#5](https://github.com/korovin-aa97/talkthrough-mcp/issues/5)) — 下载 首先。
- **关键帧 + 转录，而非运动分析。** 场景变化之间的故障可能在帧集中不可见；
`extract_frame` 重新检查任何瞬间，但逐帧运动推理是您的多模态模型的任务。
- **STT 质量取决于您选择的模型。** 默认的 `small` 优先考虑速度；
非英语叙述需要 `model="large-v3-turbo"`（参见
[语言](#languages))。
- **OCR 很好地读取清晰的 UI 文本；** 微小或低对比度的打印是尽力而为。
- **实时时钟置信度取决于录制元数据** — 最坏情况传递 `recorded_at=`
（参见上面的阶梯）。
- **Windows 是尽力而为**（参见上文）。
## 比较
| | talkthrough | 云录音 SaaS | 会议记笔记工具 | 典型的视频分析 MCP |
|---|---|---|---|---|
| 完全本地运行 | ✅ | ❌ | ❌ | 取决于 |
| 任意本地视频/音频文件 | ✅ | 浏览器/应用捕获 | 仅限会议 | ✅ |
| 实时时钟锚定（日志关联） | ✅ | ❌ | ❌ | ❌ |
| 提供代理工作流（提示，技能，找到合约） | ✅ | ❌ | ❌ | ❌ |
| 屏幕文本的 OCR，可搜索 | ✅ | 部分 | ❌ | 罕见 |
## 常见问题
**为什么不直接将视频上传到多模态模型（如 Gemini）？**
对于短小、非敏感的视频片段，可以这样做。但是，随着视频长度和敏感度的增加，权衡就出现了：一个小时的屏幕录像成本大约为每问一百万个 tokens，文件会离开您的机器，而且仍然无法将备注映射到 `14:32:07 UTC` 以便 grep 服务器日志。talkthrough 只索引一次，本地进行，然后回答任意数量的后续问题。
**为什么不使用 screenpipe？**
这是不同的工作。screenpipe 是一个始终在线的记录器，用于记录 *您自己的* 机器（商业许可）。它无法打开 teammate 或客户刚刚发送给您的 `.mov` 文件。talkthrough 可以分析它接收到的任何文件 - 这两者配合得很好。
**有可以“观看”视频的代理技能。为什么需要带有索引的服务器？**
观看风格的技能会将预算内的帧转储到上下文窗口（对于长视频会变得稀疏），通常会调用云 STT 进行音频处理，并且不会保留任何信息。talkthrough 构建了一个持久的本地索引 - 包括文字记录 + 光学字符识别（OCR），全文可搜索 - 延迟检索精确的帧，将所有内容锚定到时钟时间，并回答下一个问题而无需重新处理。
**我使用 Jam 进行 bug 报告 - 我需要这个吗？**
继续使用 Jam 进行浏览器错误报告：记录时捕获的控制台 + 网络信息是很好的证据。talkthrough 涵盖了浏览器扩展无法覆盖的内容 - 桌面应用程序、移动屏幕录像、运维事故、会议、任何文件 - 无需账户，并通过时钟时间与服务器端日志相关联。
**我可以直接使用 ffmpeg + whisper 脚本吗？**
可以 - 这正是该管道的作用。您需要重建的是：具有感知重复去除的场景变更检测、OCR、文字记录 + OCR 搜索、时钟阶梯、MCP 工具以及嵌入的使用示例、五个工作流提示和结果合同。一个 `uvx` 命令代替了大量的胶水代码。
**它真的本地运行吗？什么会离开我的机器？**
运行时没有任何内容离开。网络仅用于一次性下载（ffmpeg 构建、whisper/OCR 模型）。没有遥测数据。请参阅 [隐私](#隐私) - [SECURITY.md](SECURITY.md) 将违反此承诺视为漏洞。
## 适用于代理和工具
机器可读的入口点，以便 AI 代理可以安装和使用此服务器，而无需人类阅读文档：
- [`llms-install.md`](llms-install.md) - 代理的逐步安装说明
- [`llms.txt`](llms.txt) - 文档索引
- [`.agents/skills/talkthrough/SKILL.md`](.agents/skills/talkthrough/SKILL.md) - 一个 [Agent Skill](https://agentskills.io) 教学工具工作流程；由 Codex CLI（`$talkthrough`）在结账时自动发现，并且可被 Claude Code、Cursor、Copilot、Gemini CLI 等其他 SKILL.md 兼容工具读取
- [`AGENTS.md`](AGENTS.md) - 为贡献此仓库的编码代理提供说明
- [`server.json`](server.json) - MCP 注册表清单
- [`integrations/`](integrations/) - 每个引擎的适配器，均从一个真实来源生成并经过漂移测试（包括 [`integrations/claude-code/`](integrations/claude-code/) 下的 Claude Code 插件）
## 路线图（不在 v1 中）
URL/YouTube 摄入 · 说话者分割 · 云 STT · 嵌入/语义搜索 · 主机/远程模式 · `.mcpb` 包 · whisper.cpp 后端
## 许可证
MIT
MCP 配置
以下是此 MCP Server 的配置信息，可直接复制到 Cursor 或其他 MCP 客户端中使用。
mcp.json
连接信息
猜你喜欢
暂无推荐服务器