人工智能AI Agent代码智能体Agent 编排CLIAI 应用【免费下载链接】gsd-2A powerful meta-prompting, context engineering and spec-driven development system that enables agents to work for long periods of time autonomously without losing track of the big picture项目地址https://gitcode.com/gh_mirrors/gs/gsd-2点击查看免费下载导读本文基于 GSDgsd-2仓库中《Building Coding Agents》系列的Error Taxonomy Routing文档系统讲解不同错误必须差异化处理这一编码 Agent 设计原则如何把错误划分为七类、为每类错误分配最小必要上下文与最优处理器、以及在耗尽重试预算前如何升级。读完本文你将掌握一套可直接落地的错误分类-路由-升级架构并看到它在 GSD 的编排内核UOK、重试处理器与基础设施错误检测模块中的真实实现证据。核心洞见错误不是同质的The key insight:Different errors have fundamentally different causes and optimal resolution strategies. Treating them uniformly is one of the biggest sources of wasted iterations.不同错误具有根本不同的成因和最优解决策略。如果把所有错误一视同仁地丢给 LLM 去试错就会造成大量的无效迭代——这恰恰是编码 Agent 迭代浪费的最大来源之一。原因很简单有的错误根本不需要 LLM一条确定性规则就能秒解比如缺失导入有的错误只需要中等、聚焦的上下文比如一次失败的测试有的错误则需要广泛上下文甚至人工输入比如架构级设计问题还有一类错误根本不该触发修复循环比如不稳定测试。错误路由Error Routing的全部意义在于在正确的时间、把正确的错误、交给正确的处理器并且只携带恰好够用的上下文——而不是把整个代码库倒进一个超大上下文让模型自己翻找。最优错误分类法七类错误原文档给出了一张可直接照抄进自己 Agent 架构的分类表。每一类错误都有四个维度所需上下文、最优处理器、升级策略。错误类别所需上下文最优处理器升级策略语法/类型错误Syntax/Type错误信息 出错文件 类型定义确定性快速路径无需 LLM仅当快速路径失败时逻辑错误Logic失败测试期望 vs 实际 实现代码 规格说明携带中等聚焦上下文的 LLM尝试 3 次之后设计错误Design原始规格 架构 接口契约 实现携带广泛上下文的 LLM常常需要人工输入性能错误Performance性能剖析数据 基准 代码专项优化 Agent若回归 2x安全错误Security静态分析结果 安全模式参考保守修复提示词始终标记给人工审查环境错误Environment环境配置 近期依赖变更 错误输出专项环境上下文若无法自动解决不稳定测试Flaky Tests多次运行测试以确认其不稳定性隔离quarantine不修复交给基础设施 Agent这张表的精髓在于每一类错误都有明确的处理器所有权。语法错误归确定性代码安全错误归静态分析设计错误归 LLM 加人工不稳定测试则直接隔离——每个角色各司其职谁也不要越权。关键路由规则原文档进一步给出了四条必须遵守的路由规则1. 不稳定测试隔离绝不触发修复循环通过多次运行失败测试来确认其是否为不稳定测试。如果结果不一致有时过、有时不过则**隔离quarantine**它——永远不要因为一个不稳定测试触发一轮修复循环。修复一个间歇性失败的测试通常意味着把 Agent 拖进一个没有确定终点的泥潭。2. 环境错误按出现位置分类当错误出现在构建/启动阶段而非测试阶段时应将其分类为潜在的环境错误。这要求路由层具备对错误发生阶段的感知能力——同一段报错文本出现在测试运行里和出现在进程启动时分类可能截然不同。3. 安全错误交给确定性层的静态分析安全错误应由确定性层的静态分析捕获而不是靠 LLM 事后发现。并且要求在每项任务完成后都运行安全 lint——安全不是一次性活动而是每个任务闭环的固定组成部分。4. 语法/类型错误先走确定性快速路径先命中确定性快速路径。例如缺失导入这类错误——先在代码库中搜索该符号的导出位置机械式补上即可。只有机械修复失败时才升级给 LLM。每让 LLM 处理一个if-else能解决的错误都是 token 与幻觉风险的双重浪费。架构编排器如何分类错误并组装上下文原文档给出整个机制的统一架构描述The orchestrator classifies every error → selects the appropriate context assembly strategy → optionally selects a different prompt framing.即三层流水线分类Classify编排器对每个错误进行归类判定它属于七类中的哪一类上下文组装Context Assembly根据错误类别选择对应的上下文组装策略——语法错误只给错误信息文件类型逻辑错误给失败测试实现规格设计错误才给原始规格架构接口契约实现提示框选Prompt Framing可选地切换不同的提示词框选prompt framing让 LLM 以最适合该类错误的姿势工作例如保守修复 vs 根因诊断。对 Agent 的最终体验是我恰好拿到了我需要的信息而不是我被倾倒了一堆东西。这正是本系列文档反复强调的上下文工程Context Engineering在错误处理场景的具体化——03-state-machine-context-management.md 与 11-god-tier-context-engineering.md 从不同侧面论证了同一原则不是上下文越多越好而是越准越好。GSD 仓库中的落地证据错误分类与路由的真实实现上述分类法不是纸上谈兵。GSD 的编排内核UOK与 pi-coding-agent 运行时中可以找到与这套分类法一一对应的实现。下面按照确定性 vs LLM的分工对应 07-system-prompt-llm-vs-deterministic-split.md 的元原则来对照阅读。1. 网关平面FailureClass 与重试矩阵GSD 的 UOK 在 contracts.ts 中定义了类型化的FailureClass其取值几乎就是错误分类法的工程化表达export type FailureClass | none | policy | input | execution | artifact | verification | closeout | git | timeout | manual-attention | unknown; export type GateOutcome pass | fail | retry | manual-attention;而 gate-runner.ts 中的RETRY_MATRIX则直接实现了不同错误类别 → 不同重试预算的路由规则const RETRY_MATRIX: RecordFailureClass, number { none: 0, policy: 0, input: 0, execution: 1, artifact: 1, verification: 1, closeout: 1, git: 1, timeout: 2, manual-attention: 0, unknown: 0, };注意这里的语义与分类法完全一致policy / input / manual-attention 类错误不可重试——重试多少次都没用直接停止或请求人工介入对应原文档设计错误常常需要人工输入与安全错误始终标记审查execution / verification / git 类错误允许 1 次重试——这些是有机会通过换一种做法解决的timeout 允许 2 次重试——超时具有临时性可以多给机会。2. 基础设施错误的确定性检测在 auto/infra-errors.ts 中GSD 用纯确定性代码识别 OS/文件系统/网络级错误对应分类表中的环境错误export const INFRA_ERROR_CODES: ReadonlySetstring new Set([ ENOSPC, ENOMEM, EROFS, EDQUOT, EMFILE, ENFILE, EAGAIN, ENOBUFS, ECONNREFUSED, ENOTFOUND, ENETUNREACH, ]);其isInfrastructureError()函数首先检查 Node 系统错误的code属性再回退到扫描消息文本isTransientCooldownError()则识别凭据冷却窗口这类暂时性错误COOLDOWN_FALLBACK_WAIT_MS 35_000MAX_COOLDOWN_RETRIES 5。这个模块的注释点明了设计意图不可恢复的 OS/文件系统错误与值得重试的瞬时失败必须被区分开——这正是原文档环境错误按出现位置分类的代码级实现出现在构建/启动阶段的环境错误ENOSPC、ENOTFOUND、ECONNREFUSED 等走确定性检测绝不白白烧掉 LLM 预算。3. Provider 错误的分类与重试错误消息 → 错误类别LLM/Provider 层的错误在 retry-handler.ts 中被分类为rate_limit / quota_exhausted / server_error / unknown四类。其私有方法_classifyErrorType()通过正则对错误消息做确定性分类retry-handler.tsprivate _classifyErrorType(errorMessage: string): UsageLimitErrorType { const err errorMessage.toLowerCase(); if (/extra usage is required|long context required/i.test(err)) return quota_exhausted; if (/requires more credits|can only afford|insufficient credits|.../i.test(err)) return quota_exhausted; if (/quota|billing|exceeded.*limit|usage.*limit/i.test(err)) return quota_exhausted; if (/rate.?limit|too many requests|429/i.test(err)) return rate_limit; if (/500|502|503|504|server.?error|internal.?error|service.?unavailable/i.test(err)) return server_error; return unknown; }可重试模式的判定集中在一个零依赖模块 retryable-error-regex.ts 中RETRYABLE_ERROR_RE其注释明确说明了设计取舍temporarily backed off 被有意排除因为那是系统内部生成的消息重新进入重试处理器会造成会话文件里堆叠空错误条目issue #3429。同时上下文溢出context overflow错误不在这里重试——它由压缩compaction机制负责retry-handler.ts。这就是不同错误由不同处理器负责的又一实例同一层出现的错误也按该不该由本层处理来分流。不同类别的重试策略也因此不同retry-handler.tsrate_limit→ 先轮换同 Provider 的备用凭据markUsageLimitReached全部冷却后再通过fallbackResolver跨 Provider 回退quota_exhausted→ 跳过凭据轮换账户级计费门槛轮换凭据无效直接尝试跨 Provider 回退、降maxTokens_tryAffordableMaxTokensRetry或长上下文模型降级_tryLongContextDowngrade仍失败则按baseDelayMs * 2 ** (attempt - 1)指数退避超过maxRetries后终止并保留最终错误证据。这套逻辑对应原文档表格中逻辑错误中等上下文 尝试 3 次后升级的工程化版本——不过 GSD 对 Provider 层的重试预算/退避策略都做成了可配置项settingsManager.getRetrySettings()而不是硬编码。4. 失败再处理矩阵ADR-009 的确定性升级路径在 ADR-009-orchestration-kernel-refactor.md 中GSD 把错误路由上升为编排内核的确定性失败再处理矩阵失败类别处理方式代码失败code failure定向修复提示 有界重试测试失败test failure受影响的测试修复循环工具失败tool failure备选工具 / Provider 回退模型失败model failure回退模型链策略失败policy failure立即硬停并给出明确原因这正对应原文档表格里的五个升级策略列语法/逻辑错误对应定向修复提示 有界重试性能错误对应专项 Agent模型/工具回退安全错误对应始终标记审查策略失败立即硬停。矩阵强调每一类失败都有类型化的再处理路径而不是笼统的再试一次。5. manual-attention设计错误与人工介入的工程化原文档表格中设计错误常常需要人工输入这一行在 GSD 中被实现为网关平面的manual-attention结果。ADR-011progressive-planning-escalation.md将其细化为**执行中升级Mid-Execution Escalation**机制执行器写T##-ESCALATION.json包含问题、带权衡的选项、推荐答案、continueWithDefault网关平面的execution-gate检测到升级工件输出manual-attention通知面板向用户呈现升级请求用户回复后调度器把决策注入后续任务的 carry-forward 上下文并用gsd_decision_save持久化。continueWithDefault: true允许 Agent 先按推荐继续、用户晚到回复时再注入ESCALATION OVERRIDEfalse则暂停执行平面等待用户。这与分类法完全一致设计错误的正确答案无法从代码库推导强行猜测只会把错误传导到下游任务。配套决策机制错误路由之上的模型路由错误分类决定交给谁修而 ADR-004-capability-aware-model-routing.md 决定用哪个模型修——两层叠加后逻辑错误该升级 LLM就进一步细化为这个调试任务应路由到能力画像中 debugging 分数最高的模型。GSD 的模型路由保持两条不变量降级唯一评分永不超过用户配置的模型上限与成本作为约束而非评分维度。能力画像覆盖 coding、debugging、research、reasoning、speed、longContext、instruction 七个维度未知模型默认各维 50 分评分退化为无操作保持同档取最便宜的旧行为。任务需求向量由(unitType, TaskMetadata)动态计算例如带有concurrency/compatibility关键词的执行任务会获得{ debugging: 0.9, reasoning: 0.8 }的需求向量——让该由谁处理这类错误的判断从启发式上升为可测试、可观测的显式数据。实践要点把错误路由装进你自己的 Agent结合原文档与仓库实现落地这套架构时建议遵循以下清单建立类型化的错误分类FailureClass拒绝所有错误都是字符串的原始表达分类要落在确定性代码里而不是让 LLM 事后判断为每类错误定义独立的重试预算可参考RETRY_MATRIX的取值思路策略/输入类 0 次、执行/验证类 1 次、超时类 2 次能确定性地修就不让 LLM 修缺失导入搜代码库、基础设施错误查错误码、安全错误跑静态分析给不稳定测试单独的出路多次运行确认后直接隔离绝不进入修复循环为需要人工输入的错误保留显式通道对应manual-attention用结构化工件 通知面板 决策持久化完成闭环每次重试都保留证据GSD 的每个网关结果都会insertGateRun落库并发出审计事件gate-runner.ts确保为什么重试、重试到第几次、最终结论是什么全程可追溯。参考文件索引本文主体 20-error-taxonomy-routing.md系列总览 building-coding-agents/README.md确定性 vs LLM 分工原则 07-system-prompt-llm-vs-deterministic-split.md失败分类与重试矩阵 gate-runner.ts、contracts.ts基础设施错误确定性检测 auto/infra-errors.tsProvider 错误分类与重试 retry-handler.ts、retryable-error-regex.ts、retry-handler.test.ts编排内核失败再处理矩阵 ADR-009-orchestration-kernel-refactor.md执行中升级与人工介入 ADR-011-progressive-planning-escalation.md能力感知模型路由 ADR-004-capability-aware-model-routing.md赞分享人工智能AI Agent代码智能体Agent 编排CLIAI 应用【免费下载链接】gsd-2A powerful meta-prompting, context engineering and spec-driven development system that enables agents to work for long periods of time autonomously without losing track of the big picture项目地址https://gitcode.com/gh_mirrors/gs/gsd-2点击查看免费下载相关推荐Milvus 错误处理案例手册merr 错误码选型、包装与分类的七类真实陷阱Milvus 错误处理案例手册merr 错误码选型、包装与分类的七类真实陷阱 导读 本文是 Milvus 服务端错误处理体系的配套案例手册记录错误标准化过程数据库向量数据库分布式数据库后端Dalamud错误分类错误类型与处理策略Dalamud错误分类错误类型与处理策略 引言 Dalamud作为FFXIV最终幻想14的插件开发框架在复杂的游戏环境交互中面临着各种异常情况。有效的错CMake编译错误分类指南语法错误、链接错误与配置错误处理CMake编译错误分类指南语法错误、链接错误与配置错误处理 在软件开发过程中使用CMake跨平台构建工具时遇到编译错误是常见问题。本文将详细介绍CMak构建工具开发工具CLI上一篇玄铁E906 RISC-V处理器实战开发指南下一篇AI量化投资革命开源多智能体投资系统深度解析创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考