fix(proxy): 降低代理开启配置和地址输入成本

mudssky · mudssky · commit 552a1138f7f6 · 2026-04-30T17:05:21.000+08:00
代理初始化需要保留默认自动开启的兼容行为，但也要允许通过环境变量显式关闭自动探测，避免 profile 缓存回放绕过用户配置。代理开启命令同时支持完整 URL，减少 host/port 分拆输入的心智负担，并让 Bash 与 PowerShell 入口保持一致。

Constraint: 默认自动开启代理的历史行为必须保持兼容
Constraint: 项目要求修改 psutils/pwsh 相关内容后执行 pnpm qa 与 pnpm test:pwsh:all
Rejected: 将默认行为改为关闭 | 会破坏既有 profile 自动代理体验
Rejected: 只改 PowerShell 入口 | shell/shared.d/proxy.sh 仍会出现不一致输入体验
Confidence: high
Scope-risk: narrow
Directive: 后续新增代理子命令时复用同一套 endpoint 解析语义，避免 URL、端口、host+port 行为分叉
Tested: bash -n shell/shared.d/proxy.sh
Tested: Invoke-Pester -Path ./psutils/tests/proxy.Tests.ps1 -Output Detailed
Tested: pnpm qa
Tested: pnpm test:pwsh:all
Not-tested: 实际写入 Docker daemon/container 代理配置，避免触碰本机 Docker 服务配置
diff --git a/profile/Debug-ProfilePerformance.ps1 b/profile/Debug-ProfilePerformance.ps1
@@ -213,7 +213,7 @@ if ($IsLinux) {
 Lap '4.02-linux-path-sync'
 
 # 4.3 代理自动检测
-if (-not $SkipProxy) {
+if ((-not $SkipProxy) -and (Test-EnvSwitchEnabled -Name 'PROXY_AUTO_ENABLE' -DefaultEnabled)) {
     try {
         $proxyState = Invoke-WithCache `
             -Key "proxy-auto-detect" `
diff --git a/profile/core/mode.ps1 b/profile/core/mode.ps1
@@ -1,13 +1,31 @@
 function Test-EnvSwitchEnabled {
+    <#
+    .SYNOPSIS
+        解析环境变量形式的布尔开关。
+
+    .DESCRIPTION
+        支持 0/false/off/no/n 作为显式关闭值，其他非空值视为开启；DefaultEnabled 用于描述默认开启的配置项。
+
+    .PARAMETER Name
+        需要读取的环境变量名称。
+
+    .PARAMETER DefaultEnabled
+        环境变量不存在或为空白时是否返回开启。
+
+    .OUTPUTS
+        System.Boolean。返回 $true 表示开关开启，返回 $false 表示开关关闭。
+    #>
     [CmdletBinding()]
     param(
         [Parameter(Mandatory = $true)]
-        [string]$Name
+        [string]$Name,
+
+        [switch]$DefaultEnabled
     )
 
     $rawValue = [System.Environment]::GetEnvironmentVariable($Name)
-    if ($null -eq $rawValue) { return $false }
-    if ([string]::IsNullOrWhiteSpace($rawValue)) { return $false }
+    if ($null -eq $rawValue) { return [bool]$DefaultEnabled }
+    if ([string]::IsNullOrWhiteSpace($rawValue)) { return [bool]$DefaultEnabled }
 
     switch ($rawValue.Trim().ToLowerInvariant()) {
         '0' { return $false }
diff --git a/profile/features/environment.ps1 b/profile/features/environment.ps1
@@ -348,8 +348,8 @@ function Initialize-Environment {
         }
     }
 
-    # 自动检测代理（缓存 5 分钟避免每次 profile 加载都做 TCP 探测）
-    if (-not $SkipProxy) {
+    # 自动检测代理默认保持开启；PROXY_AUTO_ENABLE=0/false/off/no/n 时跳过检测与缓存回放。
+    if ((-not $SkipProxy) -and (Test-EnvSwitchEnabled -Name 'PROXY_AUTO_ENABLE' -DefaultEnabled)) {
         try {
             $proxyState = Invoke-WithCache -Key "proxy-auto-detect" -MaxAge ([TimeSpan]::FromMinutes(30)) -CacheType Text -ScriptBlock {
                 Set-Proxy -Command auto
diff --git a/psutils/README.md b/psutils/README.md
@@ -424,6 +424,8 @@ New-Shortcut -Path "C:\Program Files\App\app.exe" -Destination "C:\Users\Desktop
 
 提供网络代理配置管理功能。
 
+默认会在 profile 初始化或 shell 脚本加载时自动探测 `PROXY_DEFAULT_HOST:PROXY_DEFAULT_PORT`，端口可连通则自动开启当前会话代理。若希望保留 `proxy on/off` 命令但关闭自动开启，可设置 `PROXY_AUTO_ENABLE=0`（也支持 `false`、`off`、`no`、`n`）。
+
 ### 💻 PowerShell 工具 (pwsh)
 
 提供 PowerShell 环境增强功能。
diff --git a/psutils/modules/proxy.psm1 b/psutils/modules/proxy.psm1
@@ -79,15 +79,17 @@ function Set-Proxy {
         支持通过环境变量配置默认代理：
         - $env:PROXY_DEFAULT_HOST: 默认代理主机 (默认: 127.0.0.1)
         - $env:PROXY_DEFAULT_PORT: 默认代理端口 (默认: 7890)
+        - $env:PROXY_AUTO_ENABLE: 是否允许 auto 自动开启代理 (默认: 1；0/false/off/no/n 表示关闭)
         
     .PARAMETER Command
         操作命令: on, off, status, test, docker, container, auto, help。
         默认值为 'status'。
     
     .PARAMETER Target
-        目标主机或端口。
+        目标主机、端口或完整代理 URL。
         如果仅提供端口 (如 7890)，则主机默认为 127.0.0.1。
         如果提供主机 (如 192.168.1.10)，则需要通过 Port 参数提供端口，或使用默认端口。
+        如果提供完整 URL (如 http://192.168.1.10:7890)，则直接使用该地址的协议、主机和端口。
     
     .PARAMETER Port
         代理端口，仅在 Target 为主机时使用。
@@ -100,6 +102,10 @@ function Set-Proxy {
         proxy on 192.168.1.100 1080
         开启代理，指向 192.168.1.100:1080
 
+    .EXAMPLE
+        proxy on http://192.168.21.90:7890
+        使用完整 URL 开启代理。
+
     .EXAMPLE
         proxy off
         关闭当前会话代理
@@ -127,16 +133,70 @@ function Set-Proxy {
         $DefaultHost = if (-not [string]::IsNullOrWhiteSpace($env:PROXY_DEFAULT_HOST)) { $env:PROXY_DEFAULT_HOST } else { "127.0.0.1" }
         $DefaultPort = if (-not [string]::IsNullOrWhiteSpace($env:PROXY_DEFAULT_PORT)) { $env:PROXY_DEFAULT_PORT } else { "7890" }
         $NoProxyList = "localhost,127.0.0.1,::1,192.168.0.0/16,10.0.0.0/8,172.16.0.0/12"
+
+        function Test-ProxyAutoEnable {
+            <#
+            .SYNOPSIS
+                判断是否允许自动探测并开启代理。
+
+            .DESCRIPTION
+                通过 PROXY_AUTO_ENABLE 控制 profile 或 auto 命令的自动开启行为；未设置时保持兼容，默认允许自动开启。
+
+            .OUTPUTS
+                System.Boolean。返回 $true 表示允许自动开启，返回 $false 表示跳过自动开启。
+            #>
+            param()
+
+            $rawValue = [System.Environment]::GetEnvironmentVariable('PROXY_AUTO_ENABLE')
+            if ([string]::IsNullOrWhiteSpace($rawValue)) { return $true }
+
+            switch ($rawValue.Trim().ToLowerInvariant()) {
+                '0' { return $false }
+                'false' { return $false }
+                'off' { return $false }
+                'no' { return $false }
+                'n' { return $false }
+                default { return $true }
+            }
+        }
         
         # 内部辅助函数：解析主机和端口
         function Get-ProxyEndpoint {
+            <#
+            .SYNOPSIS
+                解析代理目标参数。
+
+            .DESCRIPTION
+                兼容端口、主机加端口、完整 URL 三种输入形式，并统一返回代理环境变量使用的 URL。
+
+            .PARAMETER InputTarget
+                端口、主机或完整代理 URL。
+
+            .PARAMETER InputPort
+                当 InputTarget 为主机时使用的代理端口。
+
+            .OUTPUTS
+                System.Management.Automation.PSCustomObject。包含 Host、Port、Url 三个字段。
+            #>
             param ($InputTarget, $InputPort)
             
             $hostName = $DefaultHost
             $portNum = $DefaultPort
+            $scheme = "http"
 
             if (-not [string]::IsNullOrWhiteSpace($InputTarget)) {
-                if ($InputTarget -match '^\d+$') {
+                if ($InputTarget -match '^[a-zA-Z][a-zA-Z0-9+.-]*://') {
+                    $uri = [System.Uri]$InputTarget
+                    $scheme = $uri.Scheme
+                    $hostName = $uri.Host
+                    if (-not $uri.IsDefaultPort) {
+                        $portNum = [string]$uri.Port
+                    }
+                    elseif (-not [string]::IsNullOrWhiteSpace($InputPort)) {
+                        $portNum = $InputPort
+                    }
+                }
+                elseif ($InputTarget -match '^\d+$') {
                     $portNum = $InputTarget
                 }
                 else {
@@ -146,7 +206,7 @@ function Set-Proxy {
                     }
                 }
             }
-            return [pscustomobject]@{ Host = $hostName; Port = $portNum; Url = "http://${hostName}:${portNum}" }
+            return [pscustomobject]@{ Host = $hostName; Port = $portNum; Url = "${scheme}://${hostName}:${portNum}" }
         }
     }
 
@@ -185,6 +245,11 @@ function Set-Proxy {
             }
 
             "auto" {
+                if (-not (Test-ProxyAutoEnable)) {
+                    Write-Verbose "PROXY_AUTO_ENABLE 已关闭，跳过代理自动开启。"
+                    return
+                }
+
                 # 自动尝试连接默认端口，如果通了就开启
                 $endpoint = Get-ProxyEndpoint -InputTarget $null -InputPort $null
                 try {
diff --git a/psutils/tests/proxy.Tests.ps1 b/psutils/tests/proxy.Tests.ps1
@@ -21,7 +21,7 @@ BeforeAll {
     $proxyVarNames = @(
         "http_proxy", "https_proxy", "ftp_proxy", "rsync_proxy", "all_proxy", "no_proxy",
         "HTTP_PROXY", "HTTPS_PROXY", "FTP_PROXY", "RSYNC_PROXY", "ALL_PROXY", "NO_PROXY",
-        "PROXY_DEFAULT_HOST", "PROXY_DEFAULT_PORT"
+        "PROXY_DEFAULT_HOST", "PROXY_DEFAULT_PORT", "PROXY_AUTO_ENABLE"
     )
     foreach ($varName in $proxyVarNames) {
         $script:savedEnvVars[$varName] = [System.Environment]::GetEnvironmentVariable($varName)
@@ -76,6 +76,7 @@ Describe "Set-Proxy 函数测试" -Tag 'Proxy' {
         # 清除默认值环境变量，确保测试使用硬编码默认值
         Remove-Item "env:\PROXY_DEFAULT_HOST" -ErrorAction SilentlyContinue
         Remove-Item "env:\PROXY_DEFAULT_PORT" -ErrorAction SilentlyContinue
+        Remove-Item "env:\PROXY_AUTO_ENABLE" -ErrorAction SilentlyContinue
     }
 
     Context "on 命令 - 开启代理" {
@@ -140,6 +141,25 @@ Describe "Set-Proxy 函数测试" -Tag 'Proxy' {
             $env:all_proxy | Should -Be "http://192.168.1.100:1080"
         }
 
+        It "使用完整 URL 时应该直接设置代理地址" {
+            Mock -ModuleName proxy New-Object {
+                $mockTcp = [PSCustomObject]@{}
+                $mockAsync = [PSCustomObject]@{
+                    AsyncWaitHandle = [PSCustomObject]@{}
+                }
+                $mockAsync.AsyncWaitHandle | Add-Member -MemberType ScriptMethod -Name WaitOne -Value { param($ms) return $false } -Force
+                $mockTcp | Add-Member -MemberType ScriptMethod -Name BeginConnect -Value { param($h, $p, $a, $b) return $mockAsync } -Force
+                $mockTcp | Add-Member -MemberType ScriptMethod -Name Close -Value {} -Force
+                return $mockTcp
+            } -ParameterFilter { $TypeName -eq 'System.Net.Sockets.TcpClient' }
+
+            Set-Proxy -Command "on" -Target "http://192.168.21.90:7890"
+
+            $env:http_proxy | Should -Be "http://192.168.21.90:7890"
+            $env:https_proxy | Should -Be "http://192.168.21.90:7890"
+            $env:all_proxy | Should -Be "http://192.168.21.90:7890"
+        }
+
         It "应该同时设置 ftp_proxy 和 rsync_proxy" {
             Mock -ModuleName proxy New-Object {
                 $mockTcp = [PSCustomObject]@{}
@@ -293,6 +313,21 @@ Describe "Set-Proxy 函数测试" -Tag 'Proxy' {
         It "不传参数时应该默认执行 status 命令且不抛出异常" {
             { Set-Proxy } | Should -Not -Throw
         }
+
+        It "PROXY_AUTO_ENABLE 关闭时 auto 命令不应该探测或开启代理" {
+            $env:PROXY_AUTO_ENABLE = "0"
+
+            Mock -ModuleName proxy New-Object {
+                throw "关闭自动代理时不应创建 TCP 客户端"
+            } -ParameterFilter { $TypeName -eq 'System.Net.Sockets.TcpClient' }
+
+            Set-Proxy -Command "auto"
+
+            $env:http_proxy | Should -BeNullOrEmpty
+            Should -Invoke New-Object -ModuleName proxy -Times 0 -Exactly -ParameterFilter {
+                $TypeName -eq 'System.Net.Sockets.TcpClient'
+            }
+        }
     }
 
     Context "环境变量默认值" {
diff --git a/shell/shared.d/proxy.sh b/shell/shared.d/proxy.sh
diff --git a/tests/ProfileMode.Tests.ps1 b/tests/ProfileMode.Tests.ps1

Original file line number	Diff line number	Diff line change
`@@ -348,8 +348,8 @@ function Initialize-Environment {`
`348`	`348`	`}`
`349`	`349`	`}`
`350`	`350`
`351`		`- # 自动检测代理（缓存 5 分钟避免每次 profile 加载都做 TCP 探测）`
`352`		`- if (-not $SkipProxy) {`
	`351`	`+ # 自动检测代理默认保持开启；PROXY_AUTO_ENABLE=0/false/off/no/n 时跳过检测与缓存回放。`
	`352`	`+ if ((-not $SkipProxy) -and (Test-EnvSwitchEnabled -Name 'PROXY_AUTO_ENABLE' -DefaultEnabled)) {`
`353`	`353`	`try {`
`354`	`354`	`$proxyState = Invoke-WithCache -Key "proxy-auto-detect" -MaxAge ([TimeSpan]::FromMinutes(30)) -CacheType Text -ScriptBlock {`
`355`	`355`	`Set-Proxy -Command auto`