[Windows] resident 进程在命令返回后仍阻塞父进程约 60 秒（疑似 #139 未完全修复）

[hqy2435662352]

maintainer 你们好，

我在 Windows 上使用 officecli 1.0.135 时遇到了一个和 #139 表现相近的问题。#139 已被标记为 completed，但我这边在最新版本上仍能稳定复现，所以新开一个 issue 跟进，烦请确认是否属于同一根因。

现象

通过 PowerShell 非交互式调用 officecli view / get / query 等命令时：

• 命令本身的 stdout 输出很快就能收到（内容正确）
• 但 PowerShell 子进程不会立即退出
• 大约要等 61 秒 后，子进程才退出
• 设置 OFFICECLI_NO_AUTO_RESIDENT=1 后，问题消失，所有命令都在 1 秒内完成

环境

• OS: Windows 11
• Shell: PowerShell 5.1
• officecli: 1.0.135
• 安装方式：官方 install.ps1

复现脚本

下面是一个不依赖 OpenCode / AI agent 的独立 PowerShell 脚本。它模拟 agent shell 工具的执行环境：创建一个 stdout 被重定向到管道的子 PowerShell 进程，在里面调用 officecli。

#Requires -Version 5.1
# repro-officecli-139.ps1
param(
    [string]$TestFile = "$env:TEMP\minimal.pptx",
    [int]$TimeoutSeconds = 65
)

function Invoke-OfficeCliViewTest {
    param([string]$Name, [hashtable]$EnvVars = @{})
    Write-Host "`n=========================================="
    Write-Host "TEST: $Name"
    Write-Host "Started at: $(Get-Date -Format 'HH:mm:ss')"

    $inner = ""
    foreach ($k in $EnvVars.Keys) { $inner += "`$env:$k = '$($EnvVars[$k])'; " }
    $inner += "& officecli view '$($TestFile.Replace('\', '\\'))' outline"
    $encoded = [Convert]::ToBase64String([Text.Encoding]::Unicode.GetBytes($inner))

    $psi = New-Object System.Diagnostics.ProcessStartInfo
    $psi.FileName = "powershell.exe"
    $psi.Arguments = "-NoLogo -NoProfile -NonInteractive -EncodedCommand $encoded"
    $psi.RedirectStandardOutput = $true
    $psi.RedirectStandardError = $true
    $psi.UseShellExecute = $false
    $psi.CreateNoWindow = $true

    $proc = [System.Diagnostics.Process]::Start($psi)
    $sw = [System.Diagnostics.Stopwatch]::StartNew()
    $completed = $proc.WaitForExit($TimeoutSeconds * 1000)
    $sw.Stop()
    $stdout = $proc.StandardOutput.ReadToEnd()

    if (-not $completed) {
        Write-Host "RESULT: TIMEOUT after $($sw.Elapsed.TotalSeconds.ToString('F1'))s"
        try { $proc.Kill() } catch { }
    } else {
        Write-Host "RESULT: EXITED in $($sw.Elapsed.TotalSeconds.ToString('F1'))s"
    }
    Write-Host "stdout length: $($stdout.Length)"
}

Invoke-OfficeCliViewTest -Name "Default (auto-resident)"
Invoke-OfficeCliViewTest -Name "OFFICECLI_NO_AUTO_RESIDENT=1" -EnvVars @{ OFFICECLI_NO_AUTO_RESIDENT = '1' }

运行方式：

powershell -ExecutionPolicy Bypass -File repro-officecli-139.ps1

验证结果

我用 officecli 自己 create 出来的最小文件做了多组对照，结果如下：

命令	auto-resident	OFFICECLI_NO_AUTO_RESIDENT=1
view minimal.pptx outline	TIMEOUT 61.5s	OK 0.8s
view minimal.xlsx outline	TIMEOUT 61.5s	OK 1.0s
get minimal.pptx /slide[1]	TIMEOUT 61.6s	-
get minimal.xlsx /Sheet1/A1	TIMEOUT 61.5s	-
query minimal.xlsx cell	TIMEOUT 61.5s	-

说明：

1. 不是某个文件格式的问题（PPTX / XLSX 都复现）
2. 不是某个命令的问题（view / get / query 都复现）
3. stdout 内容很快就能收到，但子进程要等约 61 秒才退出

我的理解

我推测这可能是 #139 中提到的 resident 进程句柄继承问题在 1.0.135 中仍然存在：resident 进程继承了子 PowerShell 的 stdout/stderr 管道句柄，导致即使命令输出已经返回，管道也无法关闭，父进程只能等到 resident idle timeout（约 60 秒）后才能继续。

如果我的理解有误，还请指正。

Workaround

目前可以通过设置环境变量规避：

$env:OFFICECLI_NO_AUTO_RESIDENT='1'

设置后，上述所有命令都能在 1 秒左右完成。

相关 issue

• [Windows] stdout pipe hangs ~30s when used via AI agent shell tools (OpenCode) #139

感谢维护者的时间，期待反馈。

[goworm]

感谢详细的复现脚本。这个问题我们目前还没能复现确认,需要在 Windows 环境重现后再定位,这里先不对原因下结论。

在此之前先给一个绕过方案 —— 关掉 auto-resident 即可让命令不再阻塞。在 PowerShell 里执行一次(对所有新会话永久生效):

[Environment]::SetEnvironmentVariable("OFFICECLI_NO_AUTO_RESIDENT", "1", "User")

重开 PowerShell 后生效,命令就会在约 1s 内返回。(想恢复:把 "1" 换成 $null 再执行一次。)

有 Windows 环境复现后会继续跟进,谢谢!

[hqy2435662352]

@goworm 感谢你的回复，这个问题十分影响officecli在Windows native上的使用体验，任务执行时间极长，对于不知道绕过方法的人来说只会感觉officecli运行很慢，期待早日修复。

[hqy2435662352]

更新：已定位根因并提交修复 PR #210。

根因：Windows 下 .NET 的 UseShellExecute=false 会通过 CreateProcess(..., bInheritHandles=TRUE) 让 resident 子进程继承调用方的 stdout/stderr 管道句柄。当 PowerShell/CI/agent 的 stdout 被重定向到管道时，resident 活着就会让管道保持打开，导致父进程等到 resident 60 秒 idle timeout 后才能继续。

修复方向：

• Windows 上改用 UseShellExecute=true 启动 resident，避免句柄继承
• 将 OFFICECLI_RESIDENT_IDLE_SECONDS 的传递从环境变量改为 --idle-seconds 命令行参数（因为 UseShellExecute=true 不能设置 ProcessStartInfo.Environment）
• 新增 EscapeWindowsArgument 安全处理 Windows 命令行参数
• Windows 启动失败时给出可操作回退提示（OFFICECLI_NO_AUTO_RESIDENT=1 或手动 resident-serve）
• 启动失败的完整异常写入 CLI 日志便于诊断

已在 Windows 11 上完成构建和边界测试（空格路径、单引号路径、相对路径、--idle-seconds、环境变量后备等），PR body 中有详细结果。

[goworm]

@hqy2435662352 感谢反馈和这么完整的复现脚本!

我们定位下来:这个卡顿很可能是 Windows 上某些第三方软件(例如安全/杀毒类) 在进程启动时对管道句柄留了额外引用,导致后台常驻进程被动持有了你命令行的 stdout 管道,一直到它空闲退出(约 60s)才释放——所以你会看到命令输出早就回来了、进程却迟迟不退。

我们没有继续用之前的环境变量绕过,而是换了一种方式从根上处理:让后台进程启动时只继承它自己需要的句柄,这样任何第三方软件留下的多余句柄都不会再泄漏进去。改动已合入 main,会在下个版本发布。

麻烦你更新到带此修复的版本后再测一下是否恢复正常;如果还卡,顺便告诉我们你装的是哪款安全软件,方便进一步确认。再次感谢!

[hqy2435662352]

已在 v1.0.137 中验证，问题已解决。

验证方式：从最新 main 分支构建 v1.0.137（包含 commit 991bea6），在 Windows 11 上测试 PPTX/XLSX 的 view/get/query 命令，auto-resident 模式下均在 2 秒左右完成，不再出现约 60 秒的挂起。OFFICECLI_NO_AUTO_RESIDENT=1 模式也仍然正常工作。

相关 PR #210 已关闭。