1. 从“找不到能用的视频分割工具”说起一个跨平台小工具的真实需求事情的起点很朴素我手里有一批课程录屏每段大概 40 到 90 分钟需要按固定时长切成小段方便后续上传和分发。要求也不复杂——指定一个源文件夹指定一个输出文件夹设定每段时长精确到 0.1 秒然后批量跑完最后一段不足时长的按整段保存。我先去搜现成软件。结果要么是付费的要么是免费版限制时长、限制文件数、加水印要么只支持 Windows。我需要的其实是一个能在 Macos、Linux、Windows 三端都跑起来的小工具界面简单逻辑清晰最好还能自己改。搜了一圈没找到合适的索性决定自己写。但我不想从零手敲。一是时间紧二是这种“文件夹遍历 ffmpeg 调用 简单 GUI”的活儿正是 AI 编程最擅长的场景。于是我打开 Cursor用自然语言把需求描述清楚让它生成第一版代码。十几分钟后一个基于 PySide6 ffmpeg 的跨平台视频分割软件就跑起来了。这篇文章我会把整个过程拆开讲需求怎么拆、Cursor 项目规则文件怎么写、TaoToken 统一 Key 怎么接入、ffmpeg 分割命令怎么组织、三端怎么构建验证以及中间踩过的坑。目标很明确——你照着做能一次跑通一个属于自己的跨平台视频分割工具。核心检索词先摆出来Cursor AI 编程、跨平台视频分割软件、Macos/Linux/Windows 通用、TaoToken 统一 Key 接入、ffmpeg 分割命令。适合谁看有基础 Python 能力、想用 AI 提效的开发者需要批量处理视频但不想买会员的内容创作者以及想了解 Cursor 在真实项目里怎么落地的人。2. TaoToken 统一 Key 接入让 Cursor 里的模型调用不再东拼西凑2.1 为什么要在 Cursor 里接统一 KeyCursor 本身支持配置自定义模型端点。默认情况下你要么用它内置的额度要么自己填各家厂商的 Key。问题是写这个视频分割工具的过程中我会在不同环节切换模型——需求拆解用推理强的生成 PySide6 界面代码用代码能力强的排查 ffmpeg 报错用上下文长的。如果每个模型都单独配 Key、单独记 Base URL管理成本很高。TaoToken 的思路是提供一个统一的 API 入口一个 Key 走通多个模型。官网地址是 https://taotoken.net/?utm_sourcetaotoken_aicg_blog_endutm_mediumcsdnutm_campaignrewriteutm_content API 端点是 https://taotoken.net/api 这个不加 UTM。你注册后在控制台生成 Key然后在 Cursor 里把 Base URL 指向它就能在同一个配置下切换模型。这里要强调一点TaoToken 是合规的 API 聚合服务不是所谓“中转”。你用它调用的是正规模型接口只是省去了多平台分别配置的麻烦。2.2 在 Cursor 里配置自定义模型端点打开 Cursor进入设置找到 Models 面板。关键操作是第一关闭 Cursor 自带的模型开关如果你只想用自定义端点。第二在 OpenAI API Key 一栏填入你在 TaoToken 控制台生成的 Key。第三展开 Override OpenAI Base URL填入https://taotoken.net/api。第四点击 Verify确认连接成功。配置完成后你可以在模型下拉框里选择需要的模型。Cursor 会把请求发到 TaoToken 的端点由它路由到对应模型。整个过程你只需要维护一个 Key。如果你用的是 Claude Code 这类命令行工具配置逻辑类似但走的是环境变量。下面这段是 Claude Code 的接入配置Base URL、Key、Model ID 三件套齐全export ANTHROPIC_BASE_URLhttps://taotoken.net/api export ANTHROPIC_API_KEYsk-你的TaoToken密钥 export ANTHROPIC_MODELclaude-sonnet-4-20250514注意 Model ID 要和你实际调用的模型一致不同模型 ID 不同填错会报 model not found。2.3 获取 Key 与查看文档Key 的获取路径登录 TaoToken 控制台进入 API Keys 页面新建一个 Key复制保存。控制台地址是 https://taotoken.net/console 。接入文档在 https://taotoken.net/doc 里面有各语言、各工具的配置示例。我建议你第一次配置时先用模型对话页面发一条测试消息确认 Key 和端点都通再去 Cursor 里配。模型对话入口https://taotoken.net/models 。这样能把“Key 问题”和“Cursor 配置问题”分开排查省时间。3. Cursor 项目规则文件与可复制配置把需求写进 .cursorrules3.1 为什么要写项目规则文件Cursor 每次对话都会读取项目根目录下的规则文件。如果你不写它每次生成代码都靠猜你的技术栈和风格。这个视频分割工具涉及 PySide6、ffmpeg、多线程、跨平台路径处理如果不在规则里说清楚生成的代码可能一会儿用 tkinter一会儿用 PyQt5一会儿又用 subprocess 调 ffmpeg 但参数写错。所以第一步在项目根目录建一个.cursorrules文件把技术约束写进去。下面是我实际用的版本你可以直接复制# 项目跨平台视频分割工具 # 技术栈Python 3.10 / PySide6 / ffmpeg / 多线程 ## 代码规范 - GUI 使用 PySide6界面文件单独保存为 main_window.ui用 pyside6-uic 生成 py 文件 - 视频处理逻辑放在 core/splitter.py与界面解耦 - 所有路径处理使用 pathlib.Path禁止硬编码分隔符 - 跨平台Windows 用 .exeMacos 用 .appLinux 用可执行文件构建脚本分开写 ## ffmpeg 调用 - 使用 subprocess.run参数用列表传递禁止 shellTrue - 分割命令ffmpeg -i input.mp4 -c copy -map 0 -segment_time {seconds} -f segment -reset_timestamps 1 output_%03d.mp4 - 最后一段不足时长时ffmpeg 会自动按剩余时长输出无需额外处理 - 需要捕获 stderr失败时把错误信息写入日志 ## 功能需求 1. 选择源视频文件夹和输出文件夹 2. 遍历源文件夹中的 mp4/avi/mov/mkv 文件 3. 设定分割时长单位秒最小 0.1 秒 4. 从头开始按设定时长分割剩余部分按整段保存 5. 开始/停止按钮控制多线程避免界面卡死 6. 显示进度条和日志 ## 禁止 - 禁止使用 shellTrue - 禁止在 GUI 线程里直接调用 ffmpeg - 禁止硬编码 ffmpeg 路径用 shutil.which 查找这个文件写好后Cursor 生成的代码会稳定很多。我试过不写规则直接让它生成结果它给我混用了 PyQt5 和 PySide6还用了os.system调 ffmpeg跨平台直接崩。3.2 项目结构规则文件定好后让 Cursor 按这个结构生成splitvideo/ ├── .cursorrules ├── main.py ├── ui/ │ └── main_window.ui ├── core/ │ └── splitter.py ├── build/ │ ├── build_macos.sh │ ├── build_linux.sh │ └── build_windows.bat └── requirements.txtmain.py是入口加载 UI 并绑定信号槽。core/splitter.py是纯逻辑接收源目录、输出目录、时长返回生成的文件列表。build/下放三端构建脚本。3.3 核心分割逻辑让 Cursor 生成core/splitter.py时我在对话里补了一句“用 ffmpeg 的 segment 模式-c copy不重新编码速度快用-reset_timestamps 1保证每段时间戳从零开始。” 它生成的代码大致如下import subprocess import shutil from pathlib import Path VIDEO_EXTS {.mp4, .avi, .mov, .mkv} def split_video(input_path: Path, output_dir: Path, segment_seconds: float) - list[Path]: ffmpeg shutil.which(ffmpeg) if not ffmpeg: raise RuntimeError(未找到 ffmpeg请先安装并加入 PATH) output_dir.mkdir(parentsTrue, exist_okTrue) output_pattern output_dir / f{input_path.stem}_%03d{input_path.suffix} cmd [ ffmpeg, -i, str(input_path), -c, copy, -map, 0, -segment_time, str(segment_seconds), -f, segment, -reset_timestamps, 1, str(output_pattern), ] result subprocess.run(cmd, capture_outputTrue, textTrue) if result.returncode ! 0: raise RuntimeError(fffmpeg 失败: {result.stderr[-500:]}) return sorted(output_dir.glob(f{input_path.stem}_*{input_path.suffix}))这段代码的关键点-c copy表示不重新编码直接复制流速度极快-segment_time控制每段时长-reset_timestamps 1让每段视频的时间戳从零开始避免播放器识别异常最后一段不足时长时ffmpeg 会自动按剩余时长输出不需要额外判断。3.4 界面与多线程UI 文件用 Qt Designer 画或者直接让 Cursor 生成.ui的 XML。核心控件就几个两个路径选择按钮、一个时长输入框QDoubleSpinBox最小值 0.1、开始/停止按钮、进度条、日志文本框。多线程部分让 Cursor 用QThread封装分割任务通过信号把进度和日志发回主线程。这样界面不会卡死停止按钮也能及时响应。4. 三端构建与运行验证Macos/Linux/Windows 一次跑通4.1 依赖安装三端都需要 Python 3.10 和 ffmpeg。ffmpeg 的安装方式Macos 用 Homebrewbrew install ffmpeg。Linux 用 aptsudo apt install ffmpeg。Windows 去 ffmpeg 官网下载压缩包解压后把bin目录加入 PATH。Python 依赖写在requirements.txtPySide66.5.0安装pip install -r requirements.txt。4.2 打包工具选择三端打包统一用 PyInstaller。Macos 和 Linux 用命令行Windows 用 bat 脚本。下面是三端构建脚本。Macos 构建脚本build/build_macos.sh#!/bin/bash set -e cd $(dirname $0)/.. pyinstaller --noconfirm --windowed --name SplitVideo \ --add-data ui/main_window.ui:ui \ main.py echo 构建完成dist/SplitVideo.appLinux 构建脚本build/build_linux.sh#!/bin/bash set -e cd $(dirname $0)/.. pyinstaller --noconfirm --onefile --name splitvideo \ --add-data ui/main_window.ui:ui \ main.py echo 构建完成dist/splitvideoWindows 构建脚本build/build_windows.batecho off cd /d %~dp0.. pyinstaller --noconfirm --windowed --name SplitVideo ^ --add-data ui\main_window.ui;ui ^ main.py echo 构建完成dist\SplitVideo.exe注意--add-data的分隔符Macos/Linux 用冒号Windows 用分号。这是跨平台打包最容易踩的坑之一。4.3 三端运行验证Macos 验证双击dist/SplitVideo.app选择源文件夹和输出文件夹时长填 10 秒点开始。观察日志是否逐条输出输出目录是否生成xxx_000.mp4、xxx_001.mp4等文件。用ffprobe检查每段时长ffprobe -v error -show_entries formatduration -of csvp0 output_000.mp4Linux 验证chmod x dist/splitvideo后直接运行。Linux 下要注意 ffmpeg 是否在 PATH如果报“未找到 ffmpeg”用which ffmpeg确认。Windows 验证双击dist\SplitVideo.exe。Windows 下路径分隔符是反斜杠但代码里用了pathlib.Path所以不用改。如果杀毒软件误报把 dist 目录加入白名单。三端都跑通后一个跨平台视频分割工具就成型了。整个过程从需求到成品Cursor 承担了大部分代码生成我主要做需求描述、规则约束和验证。5. 常见报错排查401、local proxy failed、reading choices、OAuth5.1 401 Unauthorized这是最常见的。原因通常是 Key 填错、Key 过期、或者 Base URL 写错。排查顺序先确认 Key 复制完整没有多余空格再确认 Base URL 是https://taotoken.net/api末尾不要加/v1或斜杠最后去控制台看 Key 是否被禁用。如果你在 Cursor 里配了自定义端点但没关内置模型开关也可能出现 401因为请求发到了错误的地方。5.2 local proxy failed这个报错通常出现在 Cursor 或命令行工具尝试走本地代理时。检查你的环境变量里有没有HTTP_PROXY、HTTPS_PROXY指向一个不存在的本地端口。如果有清掉unset HTTP_PROXY unset HTTPS_PROXY然后重启 Cursor。注意这里说的是清理无效的本地代理配置不是让你去配代理。5.3 reading choices 相关报错这个报错一般出现在流式响应解析时模型返回的格式和客户端预期不一致。常见原因是 Model ID 填错或者端点不支持该模型的流式输出。解决办法确认 Model ID 和 TaoToken 文档里列出的完全一致如果还是报错换一个模型试试排除是单个模型的问题。5.4 OAuth 相关报错如果你用的是 Claude Code 或类似工具它可能默认走 OAuth 登录流程。当你配置了自定义 Base URL 和 API Key 后要确保工具走的是 Key 认证而不是 OAuth。检查配置文件里是否有残留的 OAuth token有的话删掉只保留 API Key 配置。5.5 ffmpeg 相关报错“未找到 ffmpeg”确认 ffmpeg 在 PATH 里用ffmpeg -version测试。“Invalid argument”检查-segment_time的值是否是合法数字0.1 秒要写成0.1。“Output file #0 does not contain any stream”源文件可能损坏或者-map 0选错了流。6. 把工具用起来从单次分割到批量工作流工具跑通后我把它用在了实际工作流里。每周录完课把源文件夹指向录屏目录输出文件夹指向待上传目录时长设成 15 分钟点开始去干别的。回来时文件已经切好命名规整直接上传。如果你想让这个工具更顺手可以在这几个方向继续用 Cursor 迭代加一个“递归子目录”选项加一个“按文件大小分割”模式把日志导出成 CSV或者做一个命令行版本方便在服务器上跑。整个项目从需求到三端跑通Cursor 加 TaoToken 的组合帮我省了大量查文档和写样板代码的时间。核心经验就一条把需求写清楚把约束写进规则文件把验证做扎实。剩下的交给 AI 和 ffmpeg。如果你也想复现这个流程建议先从配置 TaoToken 的 Key 开始把模型对话跑通再进 Cursor 写规则文件。接入文档在 https://taotoken.net/doc API Keys 在 https://taotoken.net/api-keys 长期做编码和 Agent 任务的话可以看看 Coding Planhttps://taotoken.net/coding-plan 。