纯前端和弦分析工作台（Harmony Analysis Workbench）。基于 Chakra UI v3 + React 19 + TypeScript + Vite + Zustand + wavesurfer.js，无需后端即可完成调性 / 拍号标记、和弦与注释标注、实时和声监看、节拍器、音频对齐与分析。同一套前端既可跑在浏览器，也可打包为 Wails 桌面应用（WebView2）。
所有音视频处理都在本机完成，不上传任何文件。
时间轴编辑
- 创建 / 拖拽 / 删除和弦与注释块：点击（或右键）空白处新建、拖边缘调整时长、右键块渐隐删除。
- 选中后再点一次即进入行内编辑（和弦直接改根音 / 类型 / 自定义名，注释直接改文本）。
- 套索框选多选，
Ctrl/Cmd+C/Ctrl/Cmd+V复制粘贴（保持相对位置），Delete批量删除。
调性 / 拍号
- 在尺子上右键 → 添加或修改 Marker，可在任意拍切换调性（支持 9 种调式）与拍号；同一拍的多个 Marker 自动堆叠。
- 工具栏按钮一键编辑播放头处当前生效的调性 / 拍号。
和弦编辑（Edit 面板）
- 钢琴八度根音选择：下排 = 调内音（7 个"白键"，字母 A–G 各一次，可含重升降号）；上排 = 调内音之间的半音（"黑键"，只落在全音隙，位置随调式变化，拼写最简、升号优先）。
- 和弦类型按 Bright / Sad / Sharp / Plain 分组；Quick input 直接输入如
Cm11、F♯ø、B♭7。 - 点选根音自动配该级调内三和弦（如 C 大调点 G → maj，点 D → m）。
实时监看（Monitor 面板）
- 播放头下的"正在播放"：大字和弦 + 罗马音级、调性 / 拍号 Badge、小节号与小节内拍位圆点、进度条、注解；进入新和弦有 pop 动画（紧贴连续和弦不弹）。
音频与节拍器
- 导入音频（文件选择 / 拖放），整块拖动与网格对齐；无音频也能用虚拟走带播放。
- 节拍器按当前拍号
da-dum脉动（4/4 → da-dum-dum-dum，6/8 → 三连八分脉动循环）。
工程与体验
.hmn工程文件（仍是 JSON，兼容旧.json）；草稿自动保存，重启可恢复。- 启动对话框：新建 / 恢复上次会话 / 最近工程卡片网格（点击打开、右键移除）。
- 未保存显示
*；关闭前询问保存（桌面原生弹层）。 - 撤销 / 重做（128 步，连续操作自动合并）；亮 / 暗主题；和弦 General/Symbol、根音 Note/Degree 两种显示风格。
| 快捷键 | 作用 |
|---|---|
Ctrl/Cmd + S |
保存 |
Ctrl/Cmd + Z · Ctrl/Cmd + Shift + Z · Ctrl/Cmd + Y |
撤销 / 重做 |
Ctrl/Cmd + C · Ctrl/Cmd + V |
复制 / 粘贴所选块 |
Delete / Backspace |
删除所选块 |
Space |
播放 / 暂停 |
Esc |
取消选择 |
Ctrl + 滚轮 |
缩放时间轴（锚定视口中心） |
在文本输入框内，以上除
Ctrl/Cmd + S外的快捷键保留为原生文本编辑行为。
- 浏览器模式：任意现代浏览器（Chrome / Edge / Firefox，需支持 Web Audio），Node.js ≥ 20 与 npm。
- 桌面模式（额外）：见下方「桌面应用」的前置条件。
npm installnpm run dev默认监听 http://localhost:5173，改动热更新（HMR）。
npm run build类型检查 + Vite 打包，产物在 dist/。
npm run previewnpm test基于 Vitest（只读，不启动服务器）。
npm run build 产出的 dist/ 是可直接部署的静态文件，适用于任意静态托管平台（GitHub Pages / Netlify / Vercel / Cloudflare Pages 等）。工程使用相对路径 / blob URL 保存与恢复音频引用，部署到子路径同样可用，无需服务端。
同一套前端可打包为 Windows / macOS / Linux 桌面应用（Wails v2，底层 WebView2 / WKWebView / WebKitGTK）。桌面版用 Go 原生文件对话框 + 真实磁盘路径替代浏览器的 File System Access API，保存 / 打开 / 自动加载音频更接近普通桌面软件。
main.go / app.go Go 后端：Wails 入口 + 文件/音频/重命名/退出绑定
assoc_windows.go 首次启动自动注册 .hmn "Open with" 关联（HKCU，无需安装器）
assoc_other.go 非 Windows 平台的空实现
wails.json Wails 配置（frontend:dir="."，含 info + .hmn 文件关联）
build/ 构建图标（appicon.png、windows/icon.ico，脚本生成）
scripts/gen-icons.mjs 图标生成脚本（纯 Node，无外部依赖）
src/lib/platform/wails.ts 前端桥接（window.go.main.App 的类型化封装）
src/lib/platform/projectFiles.ts 打开/保存/新建 + 音频自动加载 流程
src/lib/platform/recentProjects.ts 最近工程（localStorage，最多 10 条）
前端在桌面壳内自动走原生对话框；在普通浏览器里保持 File System Access API / 下载行为（isWails() 判定）。
- File 下拉菜单（Chakra，浏览器与桌面共用）：New / Open… / Save / Save As…。
- 原生文件对话框：打开 / 保存走 Go 侧
OpenFileDialog/SaveFileDialog，读写真实磁盘路径。 .hmn工程文件：仍是 JSON，只是换了后缀；兼容旧的.json。顶栏显示完整文件名（含扩展名），点击标题改名 = 重命名磁盘文件。- 打开即自动加载音频：Go 在工程文件同目录解析
audioRef指向的音频并自动加载；导入音频记录真实路径，重新打开无需再选，找不到才弹 "Locate audio"。 - Open with Harmonology：Windows 首次运行自动注册
HKCU\Software\Classes\.hmn，右键.hmn→ 打开方式 → Harmonology（带"%1"传路径，启动即打开该工程）。单实例锁：已运行时双击文件会把路径转给已运行实例。 - 关闭前保存询问：有未保存改动时点关闭 → Save / Don't Save / Cancel（浏览器端为原生
beforeunload兜底）。
- Go ≥ 1.21（
go version确认） - Wails CLI：
go install github.com/wailsapp/wails/v2/cmd/wails@latest - Windows：WebView2 Runtime（Win10/11 一般自带）+ C 编译器（推荐 TDM-GCC 或 MSYS2 的 gcc），用
wails doctor检查 - （可选）NSIS：
wails build -nsis生成带全用户文件关联的安装包，需先安装 NSIS（https://nsis.sourceforge.io/）
go mod tidy # 拉取 Wails 依赖
npm install # 前端依赖
npm run build # 生成 dist/（go:embed all:dist 需要它存在）wails dev启动 Vite 开发服务器并拉起桌面窗口，前端改动即时生效，Go 改动自动重编译。
注意：Wails v2 官方对 Vite ≥ 5 的 dev 注入偶有兼容性问题；若
wails dev异常，可用wails build出正式版运行。
wails build # 默认构建当前平台，产物在 build/bin/（Windows 为 harmonology.exe）
wails build -nsis # 额外生成 NSIS 安装包（需先装 NSIS）常用变体：wails build -clean（清理后构建）、wails build -platform windows/amd64（指定平台）。
| 命令 | 说明 |
|---|---|
npm run dev |
启动开发服务器（HMR） |
npm run build |
类型检查 + 生产构建 → dist/ |
npm run preview |
本地预览 dist/ |
npm test |
运行 Vitest 测试 |
npm run typecheck |
仅类型检查 |
npm run icons |
重新生成 Wails 构建图标（scripts/gen-icons.mjs） |
references/ 下包含 da.wav / dum.wav（节拍器采样）与 Edwin-0.54/（Edwin 字体，SIL OFL-1.1 授权）。