docs: 完善安装脚本说明与错误处理文档

setup.ps1

@@ -108,6 +108,60 @@ function Get-UvInstallDir {
     return Join-Path $HOME ".local\bin"
 }
 
+function Invoke-NativeCommand {
+    # 安全地调用原生程序（uv/pngquant 等）。
+    # 这些程序的进度/提示信息常写到 stderr（例如 "Python 3.13 is already installed"），
+    # 而本脚本 $ErrorActionPreference="Stop" 会把 stderr 当作终止错误抛出，导致重跑误失败。
+    # 此函数临时关闭 Stop，合并 stdout/stderr，并按退出码判断成败。
+    param(
+        [Parameter(Mandatory)][string]$LiteralCommand,
+        [string]$FailureMessage
+    )
+
+    $prevEAP = $ErrorActionPreference
+    $ErrorActionPreference = 'Continue'
+    try {
+        $output = Invoke-Expression "$LiteralCommand 2>&1"
+    } finally {
+        $ErrorActionPreference = $prevEAP
+    }
+
+    if ($LASTEXITCODE -ne 0) {
+        $msg = if ($FailureMessage) { $FailureMessage } else { "命令失败" }
+        throw "$msg（退出码 $LASTEXITCODE）：$($output -join "`n")"
+    }
+
+    return $output
+}
+
+function Test-PowerPointInstalled {
+    # 通过注册表 ProgID 检测，不启动 PowerPoint 进程
+    try {
+        $null = Get-Item "Registry::HKEY_CLASSES_ROOT\PowerPoint.Application" -ErrorAction Stop
+        return $true
+    } catch {
+        return $false
+    }
+}
+
+function Get-PngquantInstallDir {
+    # pngquant 可能的安装位置：默认 %APPDATA%\pngquant，或 scoop 的 shims 目录
+    $candidates = @("$env:APPDATA\pngquant")
+    if ($env:SCOOP) {
+        $candidates += (Join-Path $env:SCOOP "shims")
+    }
+    $candidates += (Join-Path $HOME "scoop\shims")
+
+    foreach ($candidate in $candidates) {
+        if (Test-Path $candidate) {
+            return $candidate
+        }
+    }
+
+    # 找不到就返回默认（即便不存在，Add-ToCurrentPath 内部会跳过）
+    return "$env:APPDATA\pngquant"
+}
+
 function Invoke-Step {
     param(
         [Parameter(Mandatory)][string]$Title,
@@ -178,7 +232,10 @@ Invoke-Step -Title "步骤 1/5：安装 uv" -Action {
 # 第二步：安装 Python 3.13
 Invoke-Step -Title "步骤 2/5：安装 Python 3.13" -Action {
     Write-Information "正在使用 uv 安装 Python 3.13..."
-    uv python install 3.13
+    # uv 在 Python 已安装时会向 stderr 输出 "Python 3.13 is already installed"（退出码仍为 0），
+    # 通过 Invoke-NativeCommand 绕过 Stop 模式对 stderr 的误判。
+    $output = Invoke-NativeCommand -LiteralCommand "uv python install 3.13" -FailureMessage "uv python install 失败"
+    Write-Information ($output -join "`n")
     Write-Information "Python 安装完成。"
 }
 
@@ -205,7 +262,8 @@ if (-not $SkipPngquant) {
         }
 
         # install-pngquant.ps1 内部已刷新当前会话 PATH，这里再做一次保险
-        Add-ToCurrentPath -LiteralPath "$env:APPDATA\pngquant"
+        # 覆盖默认安装位置和 scoop 安装位置两种情况
+        Add-ToCurrentPath -LiteralPath (Get-PngquantInstallDir)
 
         $pngquantPath = Test-CommandExists -Name "pngquant"
         if (-not $pngquantPath) {
@@ -230,7 +288,9 @@ if (-not $SkipPptopicInstall) {
         }
 
         Write-Information "正在使用 uv tool install -e $ProjectRoot 安装 pptopic..."
-        uv tool install -e $ProjectRoot
+        # uv 的进度/解析信息会写 stderr，通过 Invoke-NativeCommand 绕过 Stop 模式误判。
+        $output = Invoke-NativeCommand -LiteralCommand "uv tool install -e `"$ProjectRoot`"" -FailureMessage "uv tool install 失败"
+        Write-Information ($output -join "`n")
         Write-Information "pptopic 安装完成。"
     }
 } else {
@@ -242,20 +302,38 @@ if (-not $SkipPptopicInstall) {
 
 # 第五步：验证
 Invoke-Step -Title "步骤 5/5：验证安装" -Action {
+    # 版本命令可能写到 stderr（部分 CLI 行为不一致），
+    # 在 Stop 模式下会误报失败，统一通过 Invoke-NativeCommand 安全调用。
+
     Write-Information ""
     Write-Information "--- uv 版本 ---"
-    uv --version
+    $v = Invoke-NativeCommand -LiteralCommand "uv --version" -FailureMessage "uv 版本查询失败"
+    Write-Information ($v -join "`n")
 
     if (-not $SkipPngquant) {
         Write-Information ""
         Write-Information "--- pngquant 版本 ---"
-        pngquant --version
+        $v = Invoke-NativeCommand -LiteralCommand "pngquant --version" -FailureMessage "pngquant 版本查询失败"
+        Write-Information ($v -join "`n")
     }
 
     if (-not $SkipPptopicInstall) {
         Write-Information ""
         Write-Information "--- pptopic 版本 ---"
-        pptopic version
+        $v = Invoke-NativeCommand -LiteralCommand "pptopic version" -FailureMessage "pptopic 版本查询失败"
+        Write-Information ($v -join "`n")
+    }
+
+    # PowerPoint 是运行时必需依赖（win32com 调用），但安装阶段无法自动安装，
+    # 这里只做检测并给出明确提示，把缺失问题前置，避免用户装完后才发现用不了。
+    Write-Information ""
+    Write-Information "--- PowerPoint 检测 ---"
+    if (Test-PowerPointInstalled) {
+        Write-Information "PowerPoint 已安装（检测到 PowerPoint.Application 注册项）。"
+    } else {
+        Write-Information "警告：未检测到 PowerPoint。"
+        Write-Information "pptopic 导出 PPTX 时需要调用 PowerPoint（Office 2016 或更新版本）。"
+        Write-Information "请先安装 PowerPoint，否则 'pptopic export' 命令将无法运行。"
     }
 }