常见问题与错误处理

常见错误与排查​

读懂错误：错误码与 OperationId​

qk 调用失败时抛出 ActionApiException（不需要 using）。它有四个关键信息：

OperationId 的取值：

• 域.方法：如 Files.ReadText、Window.Activate；根方法为 Log、Wait；
• 类型.成员：图片、文本窗口、进度窗口等句柄上的方法，如 Img.Crop、TextWin.Append、ProgressWin.Update；
• input：绑定 Main 参数时出错（如缺少必填参数，错误码 INPUT_MISSING）；
• return：转换返回值时出错（如返回了 Win）；
• run：运行前的准备阶段出错（如用户拒绝了授权，错误码 CAPABILITY_DENIED）。

在脚本里按错误码处理：

string Main(string path = @"C:\temp\不存在.txt")
{
    try
    {
        return qk.Files.ReadText(path);
    }
    catch (ActionApiException e) when (e.Code == ActionErrorCode.FileNotFound)
    {
        return null;   // 文件不存在就返回空
    }
    catch (ActionApiException e)
    {
        // 其他失败：把错误码、调用名和扩展码写进日志，便于排查
        qk.Log($"{e.Code.Value} @ {e.OperationId}，Detail={e.Detail ?? "无"}：{e.Message}", "error");
        return null;
    }
}

• 每个错误码都有同名的静态成员（错误码的帕斯卡写法，如 ActionErrorCode.FileNotFound），也可以写 e.Code.Value == "FILE_NOT_FOUND"。
• 不要解析 e.Message：消息文字可能随版本调整，错误码用于程序判断，不随消息文字变化。
• 没有捕获的错误会让动作运行失败，“结果”页只显示错误说明文字，不单独显示错误码与 OperationId；需要时按上面的写法记录到日志。
• 全部错误码见 API 参考·错误码表。

用户取消与停止​

• 用户取消对话框不是错误：qk.Ui.Select、Prompt、Form、PickFile 等取消时返回 null，Confirm 返回 false。
• 停止不是错误：用户点停止、超过动作超时、被调用的动作被取消时，脚本会被停止，catch 捕获不到（包括 catch (Exception)），只会执行 finally。停止后的 finally 里只能做有限的清理（如写日志、恢复剪贴板、松开按键、清除角标），其他 qk 调用会报 CAPABILITY_DENIED。

常见问题速查​

排查的一般顺序：先点“检查”→ 看“问题”页；再运行 → 看“结果”页和“日志”页；仍不明白时点“让 AI 修复”，或用 try/catch 把 e.Code.Value、e.OperationId、e.Detail 记到日志里。