企业官网建设流程全解析

CLI-Anything WaveTone Harness：以 JSON 项目清单驱动 WaveTone 2.61 的 Agent 原生转录工作流

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

本指南介绍cli-anything-wavetone——一个面向 Agent 的 CLI harness，它以结构化 JSON 项目清单为控制面，对音频文件做元数据探测、标签与速度编排，并最终拉起真实的 WaveTone 2.61 Windows 可执行程序完成频谱分析、音符编辑与 MIDI/文本/WAVE 导出。读完本文你将掌握该 harness 的安装、全部命令组用法、项目清单结构、后端真实性边界与可落地的测试策略。

一、背景：为什么需要给 WaveTone 包一层 JSON 控制面

WaveTone 是面向音频文件的转录辅助工具，核心能力包括频谱图与基频分析、调性与和弦检测、音符编辑，以及通过 GUI 菜单完成的 MIDI/文本/WAVE 导出。它是一款以桌面 GUI 为中心的应用，2.61 版本并未暴露官方 headless 脚本接口，因此传统 Agent 很难直接驱动它。

cli-anything-wavetone的解决思路是"清单 + 真后端"双轨结构：

• 在 Agent 一侧，用 core/project.py 生成结构化项目清单（schemawavetone-project/v1），记录源音频、计划使用的分析设置、标签与速度元数据；
• 在后端一侧，通过 utils/wavetone_backend.py 定位并拉起真实的wavetone.exe，让分析、转录、导出仍由 WaveTone 本体完成。

该包发布名为cli-anything-wavetone，版本 1.0.0，Python 依赖仅click>=8.0.0与prompt-toolkit>=3.0.0，见 setup.py。

二、安装与后端路径配置

2.1 安装 harness

在仓库的wavetone/agent-harness目录下以可编辑模式安装：

cd wavetone/agent-harness pip install -e .

安装后控制台脚本cli-anything-wavetone会注册到PATH（entry point 指向 wavetone_cli.py 的main）。

2.2 指定 WaveTone 后端路径

WaveTone 2.61 以便携目录形式分发时，若不在默认路径下，通过环境变量告诉 harness 后端位置（二选一即可，也可同时设置）：

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

从源码看，后端定位的候选顺序在 wavetone_backend.py 的 default_candidates 中定义：优先WAVETONE_EXE指向的完整路径，其次WAVETONE_HOME下的wavetone.exe与WaveTone.exe，最后依次检查Desktop/wavetone2.6.1、Downloads/wavetone2.6.1、C:/Program Files/WaveTone与C:/Program Files (x86)/WaveTone。

wavetone doctor子命令会系统性地校验后端完整性：可执行文件本身、同级data目录（内含awlib.dll、bass.dll、bassflac.dll、basswma.dll、basswv.dll、bass_aac.dll、bass_alac.dll、bass_ape.dll、bass_tta.dll、asdecoder.exe等解码组件）以及wthelp帮助目录，全部通过才返回ready: true，否则以退出码 1 结束（实现见 doctor）。

三、快速上手：一条完整的工作流

以一段song.wav为例，五个步骤覆盖"探测后端 → 建清单 → 探音频 → 设速度 → 打标签 → 启动 GUI"：

cli-anything-wavetone --json wavetone doctor cli-anything-wavetone --json project new song.wav -o song.wt.json cli-anything-wavetone --project song.wt.json --json audio probe cli-anything-wavetone --project song.wt.json --json project set-tempo --bpm 128 cli-anything-wavetone --project song.wt.json --json project add-label verse --time 32.5 cli-anything-wavetone --project song.wt.json --json wavetone launch

要点：

• 顶层--json标志使所有子命令输出机器可读的 JSON（json.dumps(indent=2, sort_keys=True)），便于 Agent 直接解析；
• 顶层--project PATH设置当前项目上下文，后续命令可省去重复传参；
• 不带任何子命令直接运行cli-anything-wavetone会进入交互式 REPL（见 repl 实现），支持help、exit/quit，并且_split_repl_args会用shlex.split(posix=False)解析并剥除成对引号，兼容 Windows 带空格与引号的路径。

四、命令组详解

CLI 由五个命令组加一个defaults命令构成，均继承顶层--json与--project上下文。

4.1project：项目清单的创建与编辑

analysis子命令的完整参数与 WaveTone 分析设置一一对应：

默认值常量定义在 project.py 的 DEFAULT_ANALYSIS_SETTINGS。注意布尔参数采用flag_value双向开关设计，未传时保持None语义——测试 test_cli_analysis_preserves_omitted_boolean_flags 专门验证了只改channel时不会意外覆盖analyze_fundamental_frequency与skip_analysis_dialog的既有值。

数据校验同样在核心层完成：add_label拒绝负时间并对标签按时间升序排序（add_label）；set_tempo要求 BPM > 0（set_tempo）；所有数值参数都经_finite_float拒绝 NaN/Inf，测试 test_rejects_non_finite_project_numbers 覆盖了bpm=nan与reference_frequency_hz=inf两类异常输入。

4.2audio：打开 WaveTone 前的音频探测

audio probe [AUDIO]返回时长、采样率、声道、编码与文件大小。传AUDIO时直接探测该文件，否则回落到--project清单中的audio.path（见 audio_probe）。

探测实现（audio.py）采用三级降级策略：

1. .wav/.wave优先用 Python 标准库wave模块（probe_method: python-wave），无外部依赖；
2. 失败或非 WAV 格式时调用ffprobe（probe_method: ffprobe），一次-show_entries同时取流级与格式级字段，测试 test_ffprobe_uses_single_show_entries_argument 校验了参数构造；
3. 两者都不可用时退回纯stat元数据（probe_method: stat），并附warning: Install ffprobe for detailed metadata on this format.。

入口处的normalize_audio_path会同时校验文件存在且扩展名落在支持集合内（SUPPORTED_AUDIO_EXTENSIONS）：.wav、.wave、.aif、.aiff、.mp3、.wma、.aac、.ogg、.oga、.flac、.wv、.ape、.alac、.tta。

4.3wavetone：真实后端的检查与启动

• wavetone doctor [--exe PATH]：运行前述完整性检查，ready为假时以退出码 1 结束；
• wavetone formats：输出 WaveTone 2.61 文档化的音频格式列表（扩展名集合 +WAVE、AIFF、MP3、WMA、AAC、Vorbis、FLAC、WavPack、Monkey's Audio、ALAC、TTA等格式名，见 supported_formats）；
• wavetone launch [AUDIO] [--exe PATH] [--wait SECONDS] [--terminate]：拉起真实 GUI。可选传入音频文件或使用清单中的audio.path；--wait指定等待秒数后轮询进程存活状态，配合--terminate可在自动化检查中启动后即关闭、不留常驻 GUI 进程。非 Windows 主机上调用会直接抛RuntimeError("WaveTone launch requires Windows")，对应测试见 test_launch_requires_windows。

4.4session：跨步骤工作流的轻量事件日志

session record SESSION_PATH EVENT --payload '{"k": 1}'与session events SESSION_PATH提供追加式事件记录（schemawavetone-session/v1）。写入时会对 payload 递归校验 JSON 安全（拒绝 NaN/Inf），文件不存在时自动初始化，见 session.py。

4.5defaults：查看默认分析设置

cli-anything-wavetone defaults直接回显DEFAULT_ANALYSIS_SETTINGS的当前值，便于 Agent 在规划阶段读取基线。

五、JSON 项目清单结构

project new生成的清单（以song.wt.json为例）顶层字段如下，完整定义见 create_project：

{ "schema_version": "wavetone-project/v1", "software": {"name": "WaveTone", "version": "2.61", "backend": "wavetone.exe"}, "project": {"name": "song", "created_at": "...", "modified_at": "..."}, "audio": { "path": ".../song.wav", "filename": "song.wav", "extension": ".wav", "size_bytes": 0 }, "analysis": { "blocks_per_second": 12, "blocks_per_semitone": 5, "note_range": "C1-B7", "reference_frequency_hz": 440.0, "analyze_fundamental_frequency": true, "channel": "Stereo", "skip_analysis_dialog": false }, "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." ] }

时间戳采用 UTC ISO8601（秒级精度）；save_project每次写入都会刷新modified_at，并以sort_keys=True、allow_nan=False输出。加载时load_project会校验文件为 JSON 对象且schema_version必须为wavetone-project/v1，否则拒绝读取——测试 test_load_project_rejects_non_object_json 覆盖了非对象根节点的场景。

六、后端真实性原则：清单是计划，不是 WFD

这是本 harness 最重要的设计边界：它不重新实现WaveTone 的分析、转录与导出引擎，也不能代替WaveTone 保存 WFD 分析结果。

• JSON 项目清单只是面向 Agent 的"控制与规划层"，记录源音频、意向分析参数、标签和速度元数据；
• 真正执行分析并产出 WFD/MIDI/文本/WAVE 输出的，永远是 GUI 内的菜单流程；
• 因此attach-wfd命令只负责把 WaveTone 已保存的.wfd文件路径回填进清单，便于后续步骤引用。

这一点在 skills/SKILL.md 的 Agent 指引中也有明确声明：清单不是 WFD 文件，分析请交给 WaveTone 本体。自动化冒烟检查则推荐用wavetone launch input.wav --wait 1 --terminate，确认真实后端可启动且不残留进程。

七、测试策略：默认跳过真后端，按需开启 Windows 冒烟

在wavetone/agent-harness下运行：

python -m pytest cli_anything/wavetone/tests/ -v

默认测试套件（test_core.py 等）跳过需要真实 WaveTone 的后端测试，保证 CI 与无 WaveTone 的贡献者也能完整跑通 CLI 层用例。若要开启真实 Windows 冒烟，设置：

$env:CLI_ANYTHING_WAVETONE_REAL_BACKEND = "1" $env:WAVETONE_EXE = "C:\path\to\wavetone2.6.1\wavetone.exe" # 或 $env:WAVETONE_HOME = "C:\path\to\wavetone2.6.1"

其中WAVETONE_EXE/WAVETONE_HOME必须指向一个包含wavetone.exe与随附data目录的 WaveTone 2.61 解压目录。E2E 子进程测试默认调用仓库内模块python -m cli_anything.wavetone.wavetone_cli，而不会静默优先使用PATH中已安装的cli-anything-wavetone，从而保证测试结果可复现、不受本机安装状态干扰。

八、适用前提与限制

• 运行环境：启动真实 WaveTone 仅支持 Windows；CLI 层（清单、探测、会话日志）在任意平台可运行。
• 后端版本：清单与后端检查面向 WaveTone 2.61，software.version固定为"2.61"。
• Python 版本：python_requires=">=3.10"，支持 3.10/3.11/3.12（见 setup.py 分类器）。
• 交互边界：分析与导出仍是 GUI 流程，Agent 通过清单做计划、通过launch拉起应用，二者由人工在 GUI 内衔接完成。

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