setup

此技能的基础目录：${CLAUDE_PLUGIN_BASE_DIR}

你的任务

根据用户的 Python 环境和所需组件，引导用户安装 bitwize-music 插件依赖项。

---

设置助手

帮助用户安装并验证插件依赖项。

---

第 1 步：检测环境

并行运行以下检查：

# Python version
python3 --version

# Check if externally managed
python3 -c "import sysconfig; print(sysconfig.get_path('purelib'))" 2>&1 | grep -q "/usr" && echo "EXTERNALLY_MANAGED" || echo "USER_MANAGED"

# Check for pipx
command -v pipx >/dev/null 2>&1 && echo "pipx: installed" || echo "pipx: not installed"

# Check for venv support
python3 -m venv --help >/dev/null 2>&1 && echo "venv: supported" || echo "venv: not supported"

# Platform
uname -s

---

第 2 步：检查组件状态

重要： 按顺序运行以下检查，切勿并行运行。如果某项检查失败，请继续执行其余检查，以显示完整状态。

关键： 始终检查虚拟环境，而非系统 Python！

# Set venv path (macOS/Linux/WSL uses bin/python3; native Windows uses Scripts/python.exe)
VENV_PYTHON=~/.bitwize-music/venv/bin/python3
[ -f "$VENV_PYTHON" ] || VENV_PYTHON=~/.bitwize-music/venv/Scripts/python.exe

# Check if venv exists
if [ -f "$VENV_PYTHON" ]; then
    echo "✅ Venv exists at ~/.bitwize-music/venv"

    # Check each component in the venv
    # 2.x serves MCPServer from mcp.server.mcpserver, 1.x serves FastMCP from
    # mcp.server.fastmcp; the server takes either, so probe both (#537).
    $VENV_PYTHON -c "import mcp.server.mcpserver" 2>/dev/null || $VENV_PYTHON -c "import mcp.server.fastmcp" 2>/dev/null && echo "✅ mcp installed" || echo "❌ mcp not installed (need mcp[cli]>=1.28.1,<3)"
    $VENV_PYTHON -c "import matchering; print('✅ matchering installed')" 2>&1 || echo "❌ matchering not installed"
    $VENV_PYTHON -c "import boto3; print('✅ boto3 installed')" 2>&1 || echo "❌ boto3 not installed"
    $VENV_PYTHON -c "from playwright.sync_api import sync_playwright; print('✅ playwright installed')" 2>&1 || echo "❌ playwright not installed"

    # Check for version drift against requirements.txt
    $VENV_PYTHON -c "
import importlib.metadata, pathlib
reqs = pathlib.Path('${CLAUDE_PLUGIN_ROOT}/requirements.txt').read_text()
stale = []
for line in reqs.splitlines():
    line = line.split('#')[0].strip()
    if not line or '==' not in line:
        continue
    name, _, ver = line.partition('==')
    name = name.split('[')[0].strip()
    try:
        installed = importlib.metadata.version(name)
        if installed != ver:
            stale.append(f'  {name}: {installed} → {ver}')
    except importlib.metadata.PackageNotFoundError:
        stale.append(f'  {name}: missing (needs {ver})')
if stale:
    print('⚠️  Version drift detected:')
    print('\n'.join(stale))
else:
    print('✅ All package versions match requirements.txt')
" 2>&1
else
    echo "❌ Venv not found at ~/.bitwize-music/venv"
    echo "   Run: python3 -m venv ~/.bitwize-music/venv   # macOS/Linux/WSL"
    echo "   Or:  py -3 -m venv ~/.bitwize-music/venv      # Windows"
fi

所有组件都会通过 requirements.txt 一并安装到虚拟环境中。

---

第 3 步：显示安装命令

始终使用统一的虚拟环境方案——它适用于所有平台，并由插件自动检测。

# Create unified venv (if it doesn't exist)
python3 -m venv ~/.bitwize-music/venv                                                    # macOS/Linux/WSL
py -3 -m venv ~/.bitwize-music/venv                                                       # Windows (native)

# Install ALL plugin dependencies
~/.bitwize-music/venv/bin/pip install -r ${CLAUDE_PLUGIN_ROOT}/requirements.txt                     # macOS/Linux/WSL
~/.bitwize-music/venv/Scripts/python.exe -m pip install -r ${CLAUDE_PLUGIN_ROOT}/requirements.txt   # Windows (native)

# Set up document hunter browser
~/.bitwize-music/venv/bin/playwright install chromium                                     # macOS/Linux/WSL
~/.bitwize-music/venv/Scripts/playwright.exe install chromium                             # Windows (native)

就是这样！ 插件会自动检测并使用平台对应的虚拟环境（macOS/Linux/WSL 上为 ~/.bitwize-music/venv，原生 Windows 上为 %USERPROFILE%\.bitwize-music\venv）。无需配置。

适用于：

• ✅ Linux（外部管理的 Python）
• ✅ macOS
• ✅ Windows（原生——Core 层级，尽力支持；音频工具需要 WSL2）
• ✅ Windows（WSL）
• ✅ 所有其他系统

---

第 4 步：安装指南

提供清晰、简单的安装指南：

1. 检测到的环境：[Python 版本，平台]
2. 缺少的组件：[列出需要安装的内容]
3. 安装命令：

   python3 -m venv ~/.bitwize-music/venv                                                  # macOS/Linux/WSL
   ~/.bitwize-music/venv/bin/pip install -r ${CLAUDE_PLUGIN_ROOT}/requirements.txt         # macOS/Linux/WSL
   ~/.bitwize-music/venv/bin/playwright install chromium                                   # macOS/Linux/WSL
   
   py -3 -m venv ~/.bitwize-music/venv                                                               # Windows (native)
   ~/.bitwize-music/venv/Scripts/python.exe -m pip install -r ${CLAUDE_PLUGIN_ROOT}/requirements.txt # Windows (native)
   ~/.bitwize-music/venv/Scripts/playwright.exe install chromium                                     # Windows (native)
   

4. 安装后：
   • 重启 Claude Code 以重新加载插件
   • 在 /plugin 状态中，MCP 服务应显示为正在运行
   • 再次运行 /bitwize-music:setup 进行验证

---

第 5 步：验证安装（如有需要）

用户告知已完成安装后，重新运行第 2 步中的检查并确认：

✅ MCP 服务：就绪 ✅ 音频母带处理：就绪 ✅ 云端上传：就绪 ✅ 文档检索器：就绪

后续步骤：运行 /bitwize-music:configure 设置工作区路径。

---

输出格式

使用清晰的分区和复选框显示状态：

## bitwize-music Setup

### Environment
- Python: 3.12.3
- System: Linux

### Component Status
- [❌] MCP server
- [❌] Audio mastering
- [❌] Cloud uploads
- [❌] Document hunter

### Installation

Run these commands to install all plugin dependencies (macOS/Linux/WSL shown; see Step 3 for the Windows native `py -3` / `Scripts\` equivalents):

```bash
# Create unified venv
python3 -m venv ~/.bitwize-music/venv

# Install ALL dependencies
~/.bitwize-music/venv/bin/pip install -r ${CLAUDE_PLUGIN_ROOT}/requirements.txt

# Set up browser
~/.bitwize-music/venv/bin/playwright install chromium

安装后：

1. 重启 Claude Code
2. 所有组件都将自动运行
3. 运行 /bitwize-music:setup 进行验证

插件会自动检测 ~/.bitwize-music/venv——一切都会自动运行！

---

## Remember

- **Be specific** - show exact commands for their environment
- **Prioritize user install** for externally-managed Python
- **Explain what each component does** so they can decide what to install
- **Test commands work** before suggesting them
- **Clear next steps** after installation