让 Agent 原生驱动 WaveTone 2.61：cli-anything-wavetone 音频转写工作流实战指南-育师

让 Agent 原生驱动 WaveTone 2.61：cli-anything-wavetone 音频转写工作流实战指南

【免费下载链接】CLI-Anything"CLI-Anything: Making ALL Software Agent-Native" -- CLI-Hub: https://clianything.cc/项目地址: https://gitcode.com/GitHub_Trending/cl/CLI-Anything

WaveTone 是一款面向音频转写辅助的 Windows 免费软件，可对音频文件进行频谱图与基频分析、调性与和弦检测、音符编辑，并通过 GUI 菜单导出 MIDI、文本与处理后的 WAVE 文件。cli-anything-wavetone 是 CLI-Anything 生态中专门为 WaveTone 2.61 打造的 Agent 原生（agent-native）命令行适配层：它通过结构化的 JSON 项目清单（manifest）准备、检查并启动真实的wavetone.exe。本文以仓库中的技能文档 SKILL.md 为骨架，结合 README.md、WAVETONE.md 及全部核心源码，系统讲解其命令体系、清单结构、后端定位策略与测试验证方案，帮助你（或你的 Agent）快速上手"清单规划 + 真机启动"的 WaveTone 转写工作流。

一、背景与设计理念：为什么不直接调用 WaveTone

WaveTone 2.61 是一个纯 GUI 应用：分析设置、MIDI/文本导出、WAVE 导出全部通过模态对话框完成，没有公开的控制台帮助、批处理模式、脚本 API 或无头导出命令。这意味着任何想用 Agent 自动化 WaveTone 的尝试，都必须面对"无法绕过 GUI"的现实。

cli-anything-wavetone 采取的是一条务实路线（见 WAVETONE.md 的 Backend Strategy）：

不重新实现 WaveTone 的分析引擎。真实后端始终是wavetone.exe，cli-anything-wavetone wavetone launch只是把该二进制（可选附带一个音频文件参数）启动起来。
不假装生成原生 WFD 数据。由于 WFD 格式未公开文档化，清单只负责记录"源音频、预期分析设置、标签、速度（tempo）元数据，以及之后由 WaveTone 自己保存的 WFD 路径"。
JSON 项目清单是 Agent 面向的规划与控制层，真正的分析与导出仍发生在 WaveTone GUI 中。

从源码结构看，整个 harness 由三部分组成（wavetone/agent-harness/cli_anything/wavetone/）：core/（项目清单、音频探测、会话日志）、utils/（真实后端包装、REPL 皮肤）、wavetone_cli.py（Click 命令行入口）。这种"薄 CLI 层 + 结构化数据 + 真实二进制"的组合，正是 CLI-Anything 让"所有软件都变得 Agent 原生"的具体实践。

二、环境要求与安装

2.1 前置条件

根据 SKILL.md 的 Requirements，使用本技能需要：

Windows 主机：wavetone launch在非 Windows 平台上会被明确拒绝（源码见 wavetone_backend.py）。
本地解压好的 WaveTone 2.61。
当不使用默认便携路径时，通过环境变量指定后端位置，二选一：
- WAVETONE_EXE指向wavetone.exe；
- WAVETONE_HOME指向 WaveTone 解压目录。

2.2 后端发现规则

后端查找器（wavetone_backend.py）按以下优先级搜索wavetone.exe：

命令行--exe显式指定的路径；
环境变量WAVETONE_EXE；
WAVETONE_HOME\wavetone.exe与WAVETONE_HOME\WaveTone.exe；
常见便携解压位置，如%USERPROFILE%\Desktop\wavetone2.6.1\wavetone.exe、Downloads下的同名目录、C:\Program Files\WaveTone、C:\Program Files (x86)\WaveTone。

找不到时，会抛出包含"已检查路径清单"的明确错误，方便排查。

2.3 安装 harness

在仓库的 wavetone/agent-harness 目录下执行：

pip install -e .

若 WaveTone 不在默认便携路径，用 PowerShell 设置后端路径：

$env:WAVETONE_HOME = "C:\Users\you\Desktop\wavetone2.6.1" # 或 $env:WAVETONE_EXE = "C:\Users\you\Desktop\wavetone2.6.1\wavetone.exe"

安装后获得cli-anything-wavetone控制台命令（入口声明见 setup.py）。包要求 Python >= 3.10，依赖click>=8.0.0与prompt-toolkit>=3.0.0。不带任何子命令直接运行会进入 REPL 交互循环（wavetone_cli.py）。

三、核心命令体系：五个命令组一屏概览

所有命令都支持顶层--json标志，输出机器可读的 JSON（emit逻辑见 wavetone_cli.py），这是 Agent 解析结果的关键通道。SKILL.md 给出的典型工作流：

cli-anything-wavetone --json wavetone doctor cli-anything-wavetone --json project new input.wav -o project.wt.json cli-anything-wavetone --project project.wt.json --json audio probe cli-anything-wavetone --project project.wt.json --json project set-tempo --bpm 120 --meter 4/4 cli-anything-wavetone --project project.wt.json --json project add-label chorus --time 64.0 cli-anything-wavetone --project project.wt.json --json wavetone launch

五个命令组及其职责（对应 SKILL.md 与 wavetone_cli.py 的@cli.group定义）：

命令组	职责	子命令
`project`	创建/编辑 JSON 清单	`new`、`info`、`set-tempo`、`add-label`、`analysis`、`attach-wfd`
`audio`	在打开前探测音频元数据	`probe`
`wavetone`	检查并启动真实 GUI	`doctor`、`formats`、`launch`
`session`	记录多步 Agent 工作流的轻量事件日志	`record`、`events`
`defaults`	显示新建清单使用的默认分析设置	（无子命令）

四、JSON 项目清单：Agent 的"作战计划"

4.1 清单不是 WFD 文件

这是本技能最重要的心智模型（Agent Guidance 一节明确强调）：JSON 项目清单不是 WaveTone 的 WFD 文件，而是面向 Agent 的、关于源音频、预期分析设置、标签与速度元数据的规划文件。真正的分析数据必须由 WaveTone 自己执行并保存为 WFD/MIDI/text/WAVE 输出。

project new创建清单时（project.py），会自动校验音频文件存在、是文件且扩展名受支持，然后生成如下结构：

{ "schema_version": "wavetone-project/v1", "software": { "name": "WaveTone", "version": "2.61", "backend": "wavetone.exe" }, "project": { "name": "input", "created_at": "…ISO8601 UTC…", "modified_at": "…" }, "audio": { "path": "…input.wav 的绝对路径…", "filename": "input.wav", "extension": ".wav", "size_bytes": 123456 }, "analysis": { "…默认分析设置…" }, "tempo": { "bpm": null, "first_bar_time_seconds": 0.0, "meter": "4/4" }, "labels": [], "notes": [], "wfd_path": null, "limitations": [ "WaveTone 2.61 exposes analysis, MIDI/text export, and WAVE export through GUI menus.", "This manifest is an agent-facing plan; WFD analysis data must be saved by WaveTone itself." ] }

schema_version固定为wavetone-project/v1，加载时会校验版本，避免跨版本误读（project.py）。
limitations字段把"GUI 驱动、清单只是规划"的边界直接写进了数据，让下游 Agent 不会误解清单的能力范围。

4.2 支持与拒绝的音频格式

受支持的音频扩展名集合（project.py）：

.wav、.wave、.aif、.aiff、.mp3、.wma、.aac、.ogg、.oga、.flac、.wv、.ape、.alac、.tta

formats子命令会同时输出扩展名清单与 WaveTone 自述支持的格式名（WAVE、AIFF、MP3、WMA、AAC、Vorbis、FLAC、WavPack、Monkey's Audio、ALAC、TTA）。不在集合内的扩展名会被project new/audio probe拒绝并给出支持清单，避免把 WaveTone 打不开的文件一路带到启动环节。

4.3 默认分析设置（`defaults`与`analysis`子命令）

新建清单时会注入一组默认分析设置（project.py），运行cli-anything-wavetone --json defaults可直接查看：

配置项	默认值	说明
`blocks_per_second`	`12`	每秒分析块数，决定时间分辨率
`blocks_per_semitone`	`5`	每半音分析块数，决定音高分辨率
`note_range`	`"C1-B7"`	音符分析范围
`reference_frequency_hz`	`440.0`	参考频率（A4 基准）
`analyze_fundamental_frequency`	`true`	是否分析基频
`channel`	`"Stereo"`	分析声道，可选`Stereo`/`L-R`/`L+R`/`L`/`R`
`skip_analysis_dialog`	`false`	是否跳过分析对话框

project analysis子命令逐项覆盖这些设置（wavetone_cli.py）。注意其布尔选项--fundamental/--no-fundamental、--skip-dialog/--show-dialog采用三态设计：未提供的选项保持None，不会覆盖清单中已有值——这一点有专门的单元测试test_cli_analysis_preserves_omitted_boolean_flags保障。

4.4 速度（tempo）与标签

project set-tempo记录 WaveTone 在和弦/音符工作前应使用的速度规划，参数为--bpm（必填，须 > 0）、--first-bar（首小节时间，默认0.0秒）、--meter（默认4/4）。

project add-label追加导航标签，参数为标签名（位置参数）、--time（必填，秒，须 >= 0）、可选--note。标签写入后会自动按时间排序（project.py），保证 Agent 读取labels数组时天然按时间轴顺序。

4.5 挂接 WFD（`attach-wfd`）

当 WaveTone 在 GUI 中完成分析并保存出 WFD 文件后，可以用project attach-wfd <xxx.wfd>把该文件路径挂回清单（要求已存在且扩展名为.wfd，见 wavetone_cli.py）。这样多步骤工作流可以"清单 -> 分析 -> 回填结果路径"地串联起来。

五、音频探测：打开之前的"侦察兵"

audio probe在把音频交给 WaveTone 之前，先返回时长、采样率、声道、编码与大小等元数据。其探测策略是三级回退（audio.py）：

WAV/WAVE 文件优先用 Python 标准库wave模块读取，probe 方法标记为python-wave，不依赖外部工具；
其余格式调用ffprobe（ffprobe -show_entries stream=…:format=… -of json），返回编码名、比特率等信息，probe 方法标记为ffprobe；对非数字元数据做了安全解析（_safe_float/_safe_int）；
若 WAV 损坏或 ffprobe 缺失/失败，回退到仅基于文件系统 stat 的元数据，并给出"warning": "Install ffprobe for detailed metadata on this format."提示。

因此，若想对 MP3、FLAC 等格式获得完整探测信息，需要环境中存在ffprobe。测试计划中的test_probe_malformed_wav_falls_back_to_stat与test_ffprobe_uses_single_show_entries_argument分别覆盖了这两条回退与参数构造路径。

audio probe也支持不带参数、直接基于--project指定清单中的音频路径进行探测，便于工作流复用。

六、真实后端：doctor、formats 与 launch

6.1 doctor：启动前的体检

wavetone doctor检查后端是否就绪（wavetone_backend.py），输出ready布尔值与逐项checks列表：

wavetone.exe存在且是文件；
解压根目录下存在data目录，且包含 WaveTone 2.61 打包的解码器支持文件：awlib.dll、bass.dll、bassflac.dll、basswma.dll、basswv.dll、bass_aac.dll、bass_alac.dll、bass_ape.dll、bass_tta.dll、asdecoder.exe（清单见 wavetone_backend.py）；
wthelp帮助目录存在（WaveTone 用 Shift-JIS HTML 帮助文件说明分析与导出）；
当前是 Windows 主机。

任一检查不通过，ready即为false，命令以退出码 1 结束。这正是 SKILL.md 建议把doctor放在工作流第一步的原因——在写清单之前先确认后端可用。

6.2 launch：启动真实 GUI

wavetone launch [audio_path]启动真实的wavetone.exe（工作目录设为 exe 所在目录），可选携带音频文件作为参数。其实现细节（wavetone_backend.py）：

返回backend、executable、cwd、pid、args、running_after_wait、terminated、exit_code等结构化信息；
--wait N指定等待秒数，之后轮询进程是否仍在运行；
--terminate在等待期后结束进程（先terminate，超时再kill），用于冒烟测试。

SKILL.md 特别给出了自动化检查场景的标准写法：

cli-anything-wavetone --json wavetone launch input.wav --wait 1 --terminate

这条命令确认真实后端可以被启动，同时不留下常驻的 GUI 进程。若等待期后进程以非零码提前退出，CLI 会以该退出码失败（对应测试test_wavetone_launch_fails_on_early_nonzero_exit）；非 Windows 主机上调用则直接报RuntimeError。

七、会话日志：多步工作流的"便签本"

session命令组为多步 Agent 工作流提供轻量事件日志（session.py）：

cli-anything-wavetone session record session.log "analysis_started" --payload '{"note": "probe done"}' cli-anything-wavetone session events session.log

record <session_path> <event> [--payload JSON]：追加一条{time, event, payload}记录，payload 必须是 JSON 对象；
events <session_path>：列出全部事件；文件不存在时返回空列表；
日志文件结构为{"schema_version": "wavetone-session/v1", "events": []}；
写入前会递归校验 payload 不含 NaN/Infinity 等非有限浮点数（_assert_json_safe），保证日志始终是合法 JSON。

这让你可以在"探测 -> 规划 -> 启动"的每一步落一条带时间戳的事件，事后完整还原 Agent 的执行轨迹。

八、Agent 使用指南与完整工作流

综合 SKILL.md 的 Agent Guidance 与 README 的 Backend Truthfulness，一个规范的 Agent 工作流如下：

体检后端：cli-anything-wavetone --json wavetone doctor，确认ready: true；
规划清单：cli-anything-wavetone --json project new input.wav -o project.wt.json（如需可--name指定项目名，默认取音频文件主干名）；
探测音频：cli-anything-wavetone --project project.wt.json --json audio probe；
注入元数据：project set-tempo（速度）与project add-label（段落标签，如 intro/verse/chorus）；
定制分析：如默认设置不满足，用project analysis覆盖（例如指定--channel L+R --note-range C2-C6）；
启动真实分析：cli-anything-wavetone --project project.wt.json --json wavetone launch，由用户在 GUI 中完成分析与导出；
回填结果：在 GUI 中保存 WFD 后，project attach-wfd result.wfd把路径挂回清单，project info可随时查看清单全貌。

要点提醒：JSON 清单只是规划层，不要指望它产出 WFD/MIDI/text/WAVE——这些必须由 WaveTone GUI 菜单操作完成；这也是清单中limitations字段反复强调的边界。

九、测试与验证：CI 友好且真实后端可选的方案

测试计划与结果详见 tests/TEST.md，共 32 项：test_core.py24 个单元测试 +test_full_e2e.py8 个端到端测试。

默认运行（无需安装 WaveTone）：

cd wavetone/agent-harness python -m pytest cli_anything/wavetone/tests/ -v

默认结果：30 passed, 2 skipped（跳过两个真实后端测试），覆盖清单创建/往返、标签排序、分析设置、WFD 校验、非有限数值拒绝、WAV 探测与回退、会话日志、后端发现等；
CLI 子进程测试默认解析并使用仓库内的python -m cli_anything.wavetone.wavetone_cli模块，即使环境中存在已安装的cli-anything-wavetone也不会静默切换；
真实后端冒烟测试（TestRealWaveToneBackend）默认跳过，需显式开启：

$env:CLI_ANYTHING_WAVETONE_REAL_BACKEND = "1" $env:WAVETONE_HOME = "C:\Users\Hp\Desktop\wavetone2.6.1" python -m pytest cli_anything\wavetone\tests\ -v -s

开启后结果为32 passed：doctor报告全部打包文件，formats输出文档化扩展名，并真实启动wavetone.exe加载生成的 WAV、等待后终止。这个"默认零依赖可跑、真实后端显式 opt-in"的设计，让没有 WaveTone 的 CI 与贡献者也能完整执行 CLI 侧测试。

十、已知边界与适用前提

诚实呈现本 harness 的能力边界（WAVETONE.md 的 Known Limits）：

WFD 不由本 harness 生成：格式未文档化；
真实分析与导出仍在 WaveTone GUI 中完成：分析设置、MIDI/text/WAVE 导出均为模态 GUI 流程；
无头导出的证据有限：目前覆盖仅限于启动冒烟测试与音频/项目文件校验，直到发现稳定的自动化或脚本化接口为止；
平台前提：wavetone launch仅支持 Windows，后端是硬性运行时依赖，必须通过WAVETONE_EXE/WAVETONE_HOME或默认便携路径定位到 2.61 解压目录。

理解这些边界，恰恰是正确使用该工具的前提：cli-anything-wavetone 的价值不在于替代 WaveTone 的分析能力，而在于为 Agent 提供一条"可校验、可规划、可追溯"的控制通道，把 GUI 软件无缝接入自动化工作流。

【免费下载链接】CLI-Anything"CLI-Anything: Making ALL Software Agent-Native" -- CLI-Hub: https://clianything.cc/项目地址: https://gitcode.com/GitHub_Trending/cl/CLI-Anything

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

让 Agent 原生驱动 WaveTone 2.61：cli-anything-wavetone 音频转写工作流实战指南