feat(kaisa): UCM2 Jack-driven HDMI + WirePlumber UCM Lua

Add GoogleKaisa HiFi UCM with JackControl and IEC958 sequences for HDMI1/2/3,
card entry under conf.d/sof-rt5682, and main.lua.d rule to enable UCM/ACP on
sof-rt5682. Add install/disable helper scripts and OPERATION section for
verification; restore pro-audio wireplumber sample under docs.

Made-with: Cursor

scripts/disable-kaisa-pro-audio-wireplumber.sh

@@ -0,0 +1,65 @@
+#!/usr/bin/env bash
+# 切换到 UCM 路线前：禁用本仓库提供的「强制 pro-audio」WirePlumber 片段（与 UCM 互斥）。
+# 用法：./scripts/disable-kaisa-pro-audio-wireplumber.sh
+# 会重命名用户级与（可选）系统级 drop-in，并重启用户 pipewire 栈。
+set -euo pipefail
+
+disable_dir() {
+	local d="$1"
+	[[ -d "$d" ]] || return 0
+	shopt -s nullglob
+	local f
+	for f in "$d"/*; do
+		[[ -f "$f" ]] || continue
+		local b
+		b="$(basename "$f")"
+		if [[ "$b" == *kaisa* ]] || [[ "$b" == 50-kaisa* ]]; then
+			if [[ "$b" == *.disabled ]] || [[ "$b" == *.bak ]]; then
+				continue
+			fi
+			local target="${f}.disabled"
+			if [[ -e "$target" ]]; then
+				target="${f}.disabled.$(date +%s)"
+			fi
+			echo "rename: $f -> $target"
+			mv -n -- "$f" "$target"
+		fi
+	done
+}
+
+echo ">>> 用户级: ${HOME}/.config/wireplumber/wireplumber.conf.d"
+mkdir -p "${HOME}/.config/wireplumber/wireplumber.conf.d"
+disable_dir "${HOME}/.config/wireplumber/wireplumber.conf.d"
+
+if [[ "${1:-}" == "--system" ]]; then
+	if ! command -v sudo &>/dev/null; then
+		echo "需要 sudo 以处理 /etc/wireplumber/。" >&2
+		exit 1
+	fi
+	echo ">>> 系统级: /etc/wireplumber/wireplumber.conf.d（需 sudo）"
+	sudo bash -c '
+		d="/etc/wireplumber/wireplumber.conf.d"
+		[[ -d "$d" ]] || exit 0
+		shopt -s nullglob
+		for f in "$d"/*; do
+			[[ -f "$f" ]] || continue
+			b="$(basename "$f")"
+			if [[ "$b" == *kaisa* ]] || [[ "$b" == 50-kaisa* ]]; then
+				[[ "$b" == *.disabled ]] && continue
+				t="${f}.disabled"
+				[[ -e "$t" ]] && t="${f}.disabled.$(date +%s)"
+				echo "rename: $f -> $t"
+				mv -n -- "$f" "$t"
+			fi
+		done
+	'
+fi
+
+if systemctl --user is-system-running &>/dev/null; then
+	echo ">>> systemctl --user restart wireplumber pipewire pipewire-pulse"
+	systemctl --user restart wireplumber pipewire pipewire-pulse
+else
+	echo "（无 user systemd 会话，请登录桌面后手动执行 restart）" >&2
+fi
+
+echo "完成。随后请安装 UCM overlay 与 wireplumber/main.lua.d/60-kaisa-ucm.lua（见 OPERATION）。"

scripts/install-kaisa-ucm-overlay.sh

@@ -0,0 +1,33 @@
+#!/usr/bin/env bash
+# 将仓库内 UCM2 overlay 与 WirePlumber Lua 安装到系统路径（需 sudo）。
+# 用法：在仓库根目录执行  ./scripts/install-kaisa-ucm-overlay.sh
+# 安装前请先运行 ./scripts/disable-kaisa-pro-audio-wireplumber.sh
+set -euo pipefail
+
+REPO_ROOT="$(cd "$(dirname "${BASH_SOURCE[0]}")/.." && pwd)"
+if [[ ! -f "$REPO_ROOT/reference/ucm2/conf.d/sof-rt5682/sof-rt5682.conf" ]]; then
+	echo "未找到 UCM 文件，请在仓库根目录执行。" >&2
+	exit 1
+fi
+
+if ! command -v sudo &>/dev/null; then
+	echo "需要 sudo。" >&2
+	exit 1
+fi
+
+echo ">>> 安装 UCM2 -> /usr/share/alsa/ucm2/"
+sudo cp -a "$REPO_ROOT/reference/ucm2/conf.d/sof-rt5682" /usr/share/alsa/ucm2/conf.d/
+sudo cp -a "$REPO_ROOT/reference/ucm2/GoogleKaisa" /usr/share/alsa/ucm2/
+
+echo ">>> 安装 WirePlumber Lua -> /usr/share/wireplumber/main.lua.d/"
+sudo install -D -m0644 "$REPO_ROOT/wireplumber/main.lua.d/60-kaisa-ucm.lua" \
+	/usr/share/wireplumber/main.lua.d/60-kaisa-ucm.lua
+
+echo ">>> 重启用户 pipewire 栈"
+if systemctl --user is-system-running &>/dev/null; then
+	systemctl --user restart wireplumber pipewire pipewire-pulse
+else
+	echo "（无 user 会话，请登录后执行: systemctl --user restart wireplumber pipewire pipewire-pulse）" >&2
+fi
+
+echo "完成。请按 OPERATION「UCM Jack 自动显示/隐藏」一节验收。"