桌面应用开发者工具人工智能AI 应用AI Agent代码智能体【免费下载链接】warpWarp is an agentic development environment, born out of the terminal.项目地址https://gitcode.com/GitHub_Trending/wa/warp点击查看免费下载Warp开源仓库wa/warp在云端 Agent 任务中支持通过第三方 CLI HarnessClaude Code、Codex、Gemini执行提示词。为避免任务启动后因 API Key 失效或额度耗尽而长时间空转、最终以晦涩失败告终的体验问题Warp 在驱动层AgentDriver实现了**认证预检auth preflight与运行期故障检测runtime failure detection**两套机制。本文基于 specs/REMOTE-1385/TECH.md 及其配套产品说明 specs/REMOTE-1385/PRODUCT.md结合仓库中已落地的源码实现harness_output_monitor.rs、error_classification.rs、driver/terminal.rs等完整讲解 trait 变更、错误分类、DFA 扫描器、停滞确认循环与run_harness集成读完后你可以透彻理解这套早期失败、可操作报错机制的设计动机与每一行关键实现。一、背景第三方 Harness 的运行生命周期在 harness/mod.rs 中所有第三方 Harness 都实现ThirdPartyHarnesstrait。一次第三方 Harness 运行的生命周期由三个步骤构成ThirdPartyHarness::validate()——检查 CLI 是否在PATH上默认实现调用resolve_executable失败返回HarnessSetupFailed并附带安装文档链接见validate_cli_installed。ThirdPartyHarness::build_runner()——写配置文件auth、trust、system prompt、MCP 等返回一个HarnessRunner。HarnessRunner::start()——在服务端创建外部会话并在终端中启动主 CLI 命令返回携带退出码的CommandHandle。这些步骤由 driver.rs 中的AgentDriver::run_internal统一编排setup_harness → prepare_harness → run_preflight_checks → run_harness。驱动错误随后在 error_classification.rs 中被分类成(AgentTaskState, TaskStatusUpdate)二元组经report_driver_error上报服务端PlatformErrorCode枚举中已有AUTHENTICATION_REQUIRED可供复用。本特性就是在上述链路的两个位置注入故障检测启动主命令之前做一次轻量认证检查主命令运行期间挂一个后台输出扫描器命中已知失败子串即提前终止任务。二、认证预检Auth Preflight启动前的 30 秒门槛2.1 新增 trait 方法auth_check_commandThirdPartyHarnesstrait 提供可选的auth_check_command方法默认返回None不执行检查/// Shell command to verify authentication credentials are valid. /// Exit code 0 pass; non-zero fail. fn auth_check_command(self) - OptionString { None }各 Harness 的实现Harness认证检查命令说明Claude Codeclaude auth status --json见 claude_code.rsCodexcodex login status见 codex.rsGemini无静默跳过继承默认None未来新 Harness 只需覆写该 trait 方法即可接入默认不检查。2.2 判定语义与 UI 呈现成败只看退出码退出码 0 视为通过任何非零退出码视为失败。若命令在 30 秒内未退出则视为失败并给出检查超时提示见 PRODUCT.md 第 22 条。可见的会话块认证检查以可见 block 的形式在共享会话 UI 中执行并归入既有的Set up environment commands设置环境命令可折叠分组与其它环境设置块一致。每个 block 可单独展开查看 CLI 捕获输出整组在 Harness 会话开始后折叠为 Ran setup commands。预检失败时分组保持展开方便用户直接检查失败块。错误细节透传捕获的 block 输出同时被塞进驱动侧错误的detail字段使同一文本能到达服务端日志与失败状态消息见 PRODUCT.md 第 11 条。2.3 与既有检查的交互顺序预检严格发生在ThirdPartyHarness::validate()确认 CLI 已安装与build_runner()把认证配置写入磁盘之后、HarnessRunner::start()之前。这个顺序保证先有可执行文件、先有落盘凭据再尝试使用它们认证检查失败时主命令永远不会被启动PRODUCT.md 第 24、25 条。auth_check_command_for帮助函数harness/mod.rs返回预检命令供视图层通过精确字符串相等识别预检块确保它们始终归入环境设置分组而不会被误认为与主命令共享 CLI 前缀的主调用。2.4 边界情况磁盘满导致 auth 配置文件写入失败 → 检查以非零退出码失败这是正确行为运行无法在无有效认证下继续。网络不可用 → 以通用 auth 失败消息失败stderr 日志包含 CLI 自身的诊断输出。CLI 版本过旧、不支持预检命令如claude auth status不存在→ 非零退出码失败可接受后续主命令大概率也会失败PRODUCT.md 第 29–31 条。三、运行期故障扫描器替代 billing 预检的 90 秒观察窗口3.1 设计动机原有设计是运行前的billing 预检billing_check_command它要烧掉一次真实的测试 API 请求而返回的信息并不比真实运行早几秒。因此本特性移除 billing 预检改为在运行期间扫描输出子串同样能覆盖无效 Key、额度耗尽、无计费权限、配额超限等场景。3.2 trait 变更runtime_error_patterns/// Substrings to scan for in the running harness blocks output. A hit /// indicates the harness cant make a successful API request (e.g. /// invalid key, no billing, quota exhausted). The driver matches /// case-insensitively against the blocks plaintext via the same DFA /// machinery used by the find feature. fn runtime_error_patterns(self) - static [static str] { [] }默认返回空切片因此对未接入的 Harness 零成本。Claude Code 与 Codex 覆写该方法。以 claude_code.rs 中的真实 needle 列表为例fn runtime_error_patterns(self) - static [static str] { [ // Out-of-credits / billing. Credit balance too low, // Plan/usage limits emitted as Youve hit your kind limit. // We match on the common prefix so the variants (session, // weekly, Opus, etc.) all hit. Youve hit your, // Invalid or malformed API key. Invalid API key, This organization has been disabled, belongs to a disabled organization, // OAuth / login state. // … ] }注意 Youve hit your 这类公共前缀 needle的写法通过匹配前缀即可同时覆盖 session/weekly/Opus 等多种限流变体这是 needle 设计上的关键技巧。新增一个 needle 只需在对应 Harness 文件里加一行PRODUCT.md 第 16 条。3.3 自适应轮询调度扫描器采用自适应轮询节奏前 30 秒每 5 秒轮询一次随后 60 秒每 15 秒轮询一次总观察预算 90 秒、约 10 次轮询。仓库中 harness_output_monitor.rs 将其实现为显式时长列表const SCAN_INTERVALS: [Duration] [ Duration::from_secs(5), // ×6前 30 秒 Duration::from_secs(15), // ×4后 60 秒 // … ];调度耗尽且未命中时扫描器停止Harness 继续运行不受打扰扫描器不对 Harness 本身施加超时PRODUCT.md 第 23 条。3.4 匹配原理复用查找功能的 DFA 基础设施每个轮询 tick 在foreground上调用TerminalDriver::find_first_match_in_block_output它直接对 block 的输出网格运行既有的RegexDFAs机器——与查找find功能每次按键走的是同一条路径因此无需在网格侧新增任何代码详见第五节。pub(crate) fn build_dfas(patterns: [static str]) - OptionRegexDFAs { if patterns.is_empty() { return None; } let escaped: VecString patterns.iter().map(|p| escape(p)).collect(); // RegexDFAs::new_many(…, case_sensitive false) —— 大小写不敏感 match RegexDFAs::new_many(refs, false /* unicode word boundary */, false /* case sensitive */) { … } }在扫描器入口用RegexDFAs::new_many一次性构建合并 DFAneedle 先经regex::escape转义且大小写不敏感再用Arc包裹每个 tick 只需廉价克隆。合并 DFA 的匹配结果是最初命中的 needle 本身对大小写不敏感因此pattern_for_match通过小写比较把matched_text映射回原始的staticneedle用于错误消息展示。pub(crate) fn pattern_for_match( matched_text: str, patterns: [static str], ) - Optionstatic str { let matched_lower matched_text.to_lowercase(); patterns .iter() .copied() .find(|p| p.to_lowercase() matched_lower) }每次 tick 都从头扫描单元格存储不需要last_scanned_len游标——regex_automata 缓存会记忆转换见 TECH.md 第四节实现说明。3.5 停滞确认循环stall confirmation防误报的关键设计Claude Code、Codex 这类 Harness 有时会打印瞬时 API 错误然后自动重试。若采用首中即杀的朴素策略会误杀正在恢复的运行。因此扫描器在命中后先进入停滞确认循环PRODUCT.md 第 17 条/// Gap between consecutive plaintext snapshots while confirming a hit. const STALL_POLL_INTERVAL: Duration Duration::from_secs(10); /// Total budget for the stall-confirmation loop. const STALL_CONFIRMATION_BUDGET: Duration Duration::from_secs(60); /// Pure equality check kept out of the async body for easy unit tests. fn outputs_stalled(before: Optionstr, after: Optionstr) - bool { matches!((before, after), (Some(a), Some(b)) if a b) }流程命中模式后先对 Harness block 的可见纯文本plaintext做一次快照。每 10 秒再取一次快照并逐字节比较最长 60 秒。只要两次快照不同——即 Harness 仍在产出新字节包括spinner 帧——循环就继续spinner 单元格在两次采样之间变化 → 快照不同 → 循环不退出。首次出现两次连续快照逐字节相同、且原始 pattern 仍存在于 block 中时确认命中任务被判失败。60 秒预算耗尽仍未稳定 → 丢弃本次检测外层扫描调度恢复正常轮询后续 tick 可再次检出。输出虽已稳定、但匹配行已滚出可见窗口Harness 恢复得足够好、错误已消失→ 同样丢弃检测。为什么用纯文本相等而不是dirty_cells_range技术文档的解释很关键GridHandler::dirty_cells_range是按 PTY pass 作用域的它在每次on_finish_byte_processing调用时重置回光标点不能作为最近是否有任何动静的判据。对可见纯文本采样两次再比较直接获得等价信息且对仅 spinner 在转的重试也能正确工作。confirm_stall返回(OptionBlockOutputMatch, Duration)——第二个返回值是确认耗时因为它要计入外层扫描调度预算PRODUCT.md 第 18 条。否则一个反复触发同一 pattern 的不稳定 Harness 会无限延长观察窗口每次候选命中都能再买 60 秒。仓库中watch_block_for_errors用total_budget SCAN_INTERVALS 之和即 90 秒作为确认后的提前退出守卫let total_budget: Duration SCAN_INTERVALS.iter().copied().sum(); // 命中 → confirm_stall → elapsed confirmation_elapsed // 若 elapsed total_budget 且未确认直接 break3.6 摘要截断与安全约束确认命中后DetectedHarnessError { pattern, excerpt }中的 excerpt 被cap_excerpt截断到240 字符EXCERPT_MAX_LEN避免终端宽度行撑爆状态消息与日志const EXCERPT_MAX_LEN: usize 240; fn cap_excerpt(excerpt: str) - String { if excerpt.chars().count() EXCERPT_MAX_LEN { return excerpt.to_owned(); } let mut out: String excerpt.chars().take(EXCERPT_MAX_LEN).collect(); out.push(…); out }所有文本提取matched text 与 excerpt都以include_esc_sequencesfalse、RespectObfuscatedSecrets::Yes执行保证失败消息永不泄漏凭据。此外should_suppress_runtime_failure会在 CLI 会话已处于Success或Failed状态时抑制扫描器报错——此时任务状态已由会话直接更新无需再做运行时模式匹配见 harness_output_monitor.rs。四、新增的find_first_match_in_block_output助手terminal.rs 为扫描器新增了两个与block_snapshot平级的助手pub struct BlockOutputMatch { pub matched_text: String, pub excerpt: String, } pub fn find_first_match_in_block_output( self, block_id: BlockId, dfas: RegexDFAs, ctx: AppContext, ) - OptionBlockOutputMatch;内部实现与block_snapshot同一把终端模型锁作用域加锁获取 terminal model按block_id查 block缺失返回None。运行block.output_grid().find(dfas).next()拿到第一个Match RangeInclusivePoint。用网格 handler 的bounds_to_string提取matched substring用于pattern_for_match反查 origin needle匹配所触及的整行作为用户可见的 excerpt从匹配起始行首取到匹配结束行末。两者都带include_esc_sequencesfalse与RespectObfuscatedSecrets::Yes。配套的block_output_plaintext助手在同一把锁下读取block.output_grid().contents_to_string(false, None)并做相同的秘密混淆供停滞确认循环采样整个可见输出。值得注意的是注释强调传None作为max_rows以比较完整可见输出——若限定行数内容滚出上限而实际有变化时会被误判为停滞。网格侧无需新增代码BlockGrid::find就是查找功能每次按键走的路径TECH.md 第三节。相关基础设施见 app/src/terminal/model/find.rs 与 app/src/terminal/model/blockgrid.rs。五、新错误变体与分类上报5.1AgentDriverError变更在 driver.rs 的AgentDriverError中原HarnessAuthFailureKind枚举及HarnessAuthCheckFailed上的kind字段被移除并新增一个错误变体#[error(Harness {harness} auth preflight failed)] HarnessAuthCheckFailed { harness: String, detail: String, }, // Added: #[error(Harness {harness} reported a runtime failure matching {pattern})] HarnessRuntimeFailureDetected { harness: String, pattern: String, excerpt: String, },5.2 分类映射error_classification.rs两个变体在 error_classification.rs 中都映射为(AgentTaskState::Failed, PlatformErrorCode::AuthenticationRequired)但携带不同的用户可见消息AgentDriverError::HarnessAuthCheckFailed { harness, .. } { let message format!( Harness {harness} authentication check failed: login credentials \ are invalid or expired. Verify that the authentication secret \ configured for this harness is correct. ); (AgentTaskState::Failed, TaskStatusUpdate::with_error_code(message, PlatformErrorCode::AuthenticationRequired)) } AgentDriverError::HarnessRuntimeFailureDetected { harness, pattern, excerpt } { let message format!( Harness {harness} could not make a successful API request. \ Matched failure pattern {pattern} in harness output: \{excerpt}\. \ This usually means the API key is invalid, out of credits, or the \ account is misconfigured. ); (AgentTaskState::Failed, TaskStatusUpdate::with_error_code(message, PlatformErrorCode::AuthenticationRequired)) }运行时失败消息同时呈现命中的 needle与harness 输出的 excerpt把失败原因直接摆在用户面前。5.3 服务端零改动两种失败模式都映射到既有的AUTHENTICATION_REQUIREDPlatformErrorCode仅靠人类可读的statusMessage区分服务端已有的AUTHENTICATION_REQUIRED任务状态转换逻辑无需任何修改TECH.md 第七节。上报失败后驱动会向 Harness 发出/exit并终止进程不做重试PRODUCT.md 第 21 条。六、将扫描器接入run_harness6.1run_harness新签名与 select 第四分支run_harness新增两个参数runtime_error_patterns、foreground并在既有 select 循环中加入扫描器分支async fn run_harness( runner: Arcdyn HarnessRunner, harness_name: String, runtime_error_patterns: static [static str], foreground: ModelSpawnerSelf, harness_exit_rx: oneshot::Receiver(), ) - Result(), AgentDriverError { let command_handle runner.start(foreground).await?; let block_id command_handle.block_id().clone(); // … let scanner_fut harness_output_monitor::watch_block_for_errors( block_id, runtime_error_patterns, foreground, ).fuse(); futures::pin_mut!(scanner_fut); let command_result loop { futures::select! { exit_code command_handle break exit_code, _ warpui::r#async::Timer::after(HARNESS_SAVE_INTERVAL).fuse() { /* 既有周期保存 */ } _ harness_exit_rx { /* 既有优雅退出分支 */ } detected scanner_fut { if let Some(error) detected { let _ runner.exit(foreground).await; // 优雅退出让清理逻辑运行 detected_runtime_failure Some(error); } // 调度耗尽且无命中时Fuse 让该分支永远保持 Pending不会忙循环 } } }; // 既有最终保存 清理 if let Some(error) detected_runtime_failure { return Err(AgentDriverError::HarnessRuntimeFailureDetected { harness: harness_name, pattern: error.pattern, excerpt: error.excerpt, }); } // 既有退出码映射 }关键设计点扫描器与 harness 命令、周期会话保存、闲置完成信号在同一 select 循环中赛跑PRODUCT.md 第 26 条。scanner_fut用fuse()包裹调度耗尽解析为None后该分支永久保持Pending不会忙循环TECH.md 第五节说明。tick 用warpui::r#async::Timer::after驱动与既有run_harness周期保存模式一致。检测到的运行时失败优先于 harness 自身退出码即使 harness 在/exit信号处理前自行以看似成功的退出码退出驱动仍上报HarnessRuntimeFailureDetected避免API 已失败却报告成功的迷惑场景PRODUCT.md 第 32 条。清理处置考虑detected_runtime_failure一旦发生运行时失败清理处置一律置为DropResumptionStateHarnessCleanupDisposition——失败的运行不应被静默地允许恢复TECH.md 第五节说明枚举定义见 harness/mod.rs。检测到的失败会触发runner.exit(foreground)优雅退出从而保证会话清理与最终保存照常执行。6.2 调用方更新run_internalrun_internal的第三方分支原本就持有harness.as_ref()只需把 harness 名与运行时 pattern 同时灌入凭据刷新分支与无刷新分支let harness_name harness.cli_agent().command_prefix().to_owned(); let runtime_error_patterns harness.runtime_error_patterns(); Self::run_harness(runner, harness_name, runtime_error_patterns, foreground, harness_exit_rx).await七、测试与验证7.1 单元测试harness_output_monitor_tests.rs新文件见 harness_output_monitor_tests.rsbuild_dfas空 patterns 返回None非空返回Someneedle 中的正则元字符被正确转义。pattern_for_match把大小写不同的匹配文本映射回原始staticneedle无 needle 匹配时返回None存在多个小写相等候选时取第一个。error_classification_tests.rs见 error_classification_tests.rsHarnessAuthCheckFailed→(Failed, AuthenticationRequired)携带 auth 失败消息原TestRequestFailed变体已删相应测试移除。HarnessRuntimeFailureDetected→(Failed, AuthenticationRequired)用户可见消息同时包含命中的pattern与excerpt。harness/mod_tests.rs见 harness/mod_tests.rs移除全部 billing 测试preflight_commands_for_*中断言改为只含 auth 检查。claude_runtime_error_patterns_returns_slice、codex_runtime_error_patterns_returns_slice、gemini_runtime_error_patterns_is_empty_by_default分别固定各 Harness 的 pattern 返回。auth_check_command_for_*系列验证 Gemini/Oz/Unsupported/Unknown 均返回None。7.2 手工验证矩阵来自 PRODUCT.md 与 TECH.md场景预期行为Claude Code 有效 API Keyauth 通过harness 正常运行90 秒内扫描器无命中任务正常完成Claude Code 无效 API Keyauth 检查失败任务标记 FAILED显示 auth 失败消息Claude Code 有效 Key 但额度耗尽auth 通过harness 向 block 输出余额错误扫描器命中并确认任务标记 FAILED显示含 pattern excerpt 的运行时失败消息同样的矩阵应用于 Codex行为同上Geminiauth 检查跳过扫描器为 no-opharness 行为与之前完全一致八、并行化约束本变更在单一 crate 内高度耦合trait 方法、分类器、驱动循环、扫描器模块、新助手、测试属于单 Agent 任务并行 Agent 会互相踩踏TECH.md 最后一节。结语从auth_check_command的 30 秒启动前门槛到runtime_error_patterns DFA 扫描 停滞确认的 90 秒观察窗口这套认证预检 运行期故障检测把第三方 Harness 运行中最高频的失败原因Key 失效、额度耗尽、组织被禁用从数分钟后晦涩退出提前到数秒内可操作报错并且全程复用既有 find 功能的RegexDFAs基础设施、保持零服务端改动。源码实现与设计文档高度一致读者可沿 harness/mod.rs → harness_output_monitor.rs → error_classification.rs → terminal.rs 的路径逐层验证。赞分享桌面应用开发者工具人工智能AI 应用AI Agent代码智能体【免费下载链接】warpWarp is an agentic development environment, born out of the terminal.项目地址https://gitcode.com/GitHub_Trending/wa/warp点击查看免费下载相关推荐容器零信任扫描Vuls实现Docker与containerd漏洞秒级检测容器零信任扫描Vuls实现Docker与containerd漏洞秒级检测 Vuls是一款强大的无代理漏洞扫描器支持Linux、FreeBSD、容器、Word漏洞扫描网络安全运维SWE-bench 评测实战从生成预测到运行 Evaluation Harness 的完整指南SWE bench 评测实战从生成预测到运行 Evaluation Harness 的完整指南 SWE bench 是一个衡量语言模型解决真实世界 GitHu模型评测AI 评测大模型人工智能使用 osquery 与 Fleet 检测 Log4j 漏洞从 JAR 发现到 YARA 扫描的完整实践指南使用 osquery 与 Fleet 检测 Log4j 漏洞从 JAR 发现到 YARA 扫描的完整实践指南 图片 altFleet 使用 osquer后端前端企业应用运维网络安全上一篇OpenClaw 接入 Hugging Face Inference Providers认证、模型发现与路由配置完全指南下一篇Crawlee v3 升级完全指南从 Apify SDK v2 迁移的破坏性变更与实战迁移手册创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考