Archon 工作流错误可见性改造：从静默吞错到可诊断的加载与路由体系

Archon 工作流错误可见性改造从静默吞错到可诊断的加载与路由体系【免费下载链接】ArchonThe first open-source harness builder for AI coding. Make AI coding deterministic and repeatable.项目地址: https://gitcode.com/GitHub_Trending/archon3/Archon本篇文章以 Archon 仓库中的调研文档 issue-260-263-264.md 为骨架剖析工作流系统在「加载」与「路由」两个环节静默吞错的问题根因并完整还原十个步骤的增强方案包括WorkflowLoadError结构化错误类型、逐文件 try-catch 错误累积、/invoke-workflow路由错误反馈与大小写不敏感匹配以及配套测试与验证方法。读完本文你将掌握 Archon 工作流加载与路由链路的内部机制并理解一套可复用的「错误可见性」改造范式如何在不改变整体架构的前提下让被吞掉的错误变成用户可读、可诊断的信息。一、背景工作流系统为什么「静默失败」Archon 的工作流Workflow是运行在 AI Coding Agent 之上的确定性执行单元用户在.archon/workflows/下编写 YAML 工作流AI 通过/invoke-workflow name命令触发路由系统按步骤依次执行。这套链路高度依赖「加载」把 YAML 解析成可执行定义与「路由」把 AI 输出解析成工作流调用两个环节而问题恰恰藏在这两个环节里。调研文档将问题拆解为三个关联 issueMetricValueReasoningPriorityMEDIUM用户无法调试工作流失败变通方案是阅读服务端日志但大多数用户不会这么做ComplexityMEDIUM涉及 4 个文件更新牵动 loader 返回类型、command handler、router 与 types但每个改动自包含ConfidenceHIGH代码中根因明确且已有但未使用的DiscoverWorkflowsResult类型问题陈述工作流系统在两个关键点静默吞掉错误——1loader 会过滤掉解析/读取失败的工作流却不告知用户2当 AI 输出无效的工作流名称时router 静默回退。此外executor.ts与types.ts中还有少量代码清理工作重复 JSDoc、未使用的类型别名、缺失的returns文档、误导性的clearContext注释。三件事叠加导致用户对「工作流加载失败」和「路由失败」完全没有可见性。二、根因分析错误在哪两个环节被吞掉2.1 加载链路目录级 try-catch parseWorkflow返回null调研文档给出的证据链WHY → BECAUSEWHY用户不知道哪些工作流加载失败BECAUSEdiscoverWorkflows()返回WorkflowDefinition[]没有错误通道。原证据位置为loader.ts:294的PromiseWorkflowDefinition[]签名。BECAUSEparseWorkflow()在任何校验失败时返回null调用方直接静默过滤——if (workflow) { workflows.set(entry, workflow); }。BECAUSEloadWorkflowsFromDir没有逐文件 try-catch一次失败会中止整个循环readFile与stat调用未被单独包裹。换句话说加载层只有「目录级」的错误处理目录里任何一个文件出错都会让整批加载中断即使单个文件校验失败被捕获返回的也是null调用方没有任何途径得知「哪个文件、因为什么原因」失败了。2.2 路由链路无效工作流名称产生零用户反馈WHY无效的工作流名称没有任何用户反馈BECAUSEparseWorkflowInvocation在不匹配时返回{ workflowName: null, remainingMessage: message }不携带任何错误信息。BECAUSEtryWorkflowRouting遇到null直接返回false。结果是当 AI 输出了形如/invoke-workflow bad-name的指令时系统把带着畸形命令的原始 AI 响应直接发给用户不做任何解释。用户看到的是「AI 回复了一句命令文本」而不是「这个工作流不存在」。三、改造方案十个步骤完整拆解Step 1新增WorkflowLoadError类型重构发现结果类型目标文件types.ts调研文档原路径为packages/core/src/workflows/types.ts最终实现在packages/workflows包中详见本文第七节。首先处理StepDefinition别名——它只是SingleStep的向后兼容别名应标记为弃用/** * deprecated Use SingleStep directly. Alias kept for external consumers. */ export type StepDefinition SingleStep;同时修正SingleStep.clearContext的注释把「控制会话连续性」的真实语义写清楚export interface SingleStep { command: string; /** Controls session continuity between steps. When true, creates a fresh session. * Only applies to sequential execution; parallel blocks always use fresh sessions. */ clearContext?: boolean; }然后是核心类型设计用「错误 结果」二元结构替换无法表达「部分成功」的判别联合/** * Error encountered while loading a workflow file */ export interface WorkflowLoadError { filename: string; error: string; errorType: read_error | parse_error | validation_error; } /** * Result of workflow discovery - includes both successful loads and errors */ export interface WorkflowLoadResult { workflows: WorkflowDefinition[]; errors: WorkflowLoadError[]; }为什么这样做原有的DiscoverWorkflowsResult类型从未被使用且它用success: true/false判别联合无法表达「部分文件成功、部分文件失败」的中间状态。新的WorkflowLoadResult同时返回工作流与错误让调用方可以把错误信息透出给用户。errorType三值枚举read_error/parse_error/validation_error为上层 UI 提供了分类依据例如read_error通常对应权限问题或文件被占用parse_error对应 YAML 语法错误validation_error对应字段缺失或取值非法。Step 2parseWorkflow返回结构化错误将原本「返回WorkflowDefinition | null」改为返回一个可判定成功/失败的联合类型使每一类校验失败都能携带文件与错误详情type ParseResult | { workflow: WorkflowDefinition; error: null } | { workflow: null; error: WorkflowLoadError }; function parseWorkflow(content: string, filename: string): ParseResult { try { const raw parseYaml(content) as Recordstring, unknown; if (!raw.name || typeof raw.name ! string) { getLog().warn({ filename }, workflow_missing_name); return { workflow: null, error: { filename, error: Missing required field name, errorType: validation_error }, }; } if (!raw.description || typeof raw.description ! string) { getLog().warn({ filename }, workflow_missing_description); return { workflow: null, error: { filename, error: Missing required field description, errorType: validation_error, }, }; } // ... (steps/loop/prompt 等其余校验逻辑改为返回 error 对象而非 null) if (hasSteps hasLoop) { getLog().warn({ filename }, workflow_steps_and_loop_conflict); return { workflow: null, error: { filename, error: Cannot have both steps and loop (mutually exclusive), errorType: validation_error, }, }; } if (hasLoop !hasPrompt) { getLog().warn({ filename }, workflow_loop_missing_prompt); return { workflow: null, error: { filename, error: Loop workflows require a prompt field, errorType: validation_error, }, }; } if (!hasSteps !hasLoop) { getLog().warn({ filename }, workflow_missing_steps_or_loop); return { workflow: null, error: { filename, error: Missing steps or loop configuration, errorType: validation_error, }, }; } // Step 校验失败把 zod 校验错误拼接成可读文本 if (steps.length ! (raw.steps as unknown[]).length) { getLog().warn({ filename, validationErrors }, workflow_step_validation_failed); return { workflow: null, error: { filename, error: Step validation failed: ${validationErrors.join(; )}, errorType: validation_error, }, }; } // ... 成功路径返回 { workflow: definition, error: null } } catch (error) { const err error as Error; const linePattern /line (\d)/i; const lineMatch linePattern.exec(err.message); const lineInfo lineMatch ? (near line ${lineMatch[1]}) : ; getLog().error({ err, filename, lineInfo: lineInfo || undefined }, workflow_parse_failed); return { workflow: null, error: { filename, error: YAML parse error${lineInfo}: ${err.message}, errorType: parse_error, }, }; } }这段实现有两个值得注意的细节校验失败与解析异常分道所有「业务校验」失败缺name、缺description、steps与loop互斥、loop 缺prompt、step 校验失败归类为validation_error而 YAML 语法层面的异常统一归类为parse_error。错误信息可定位解析异常会从错误消息中提取line (\d)并拼进error字符串如YAML parse error (near line 5): ...用户能直接定位到出错行。Step 3loadWorkflowsFromDir逐文件 try-catch 与错误累积原实现把整段读取逻辑包在一个 try-catch 里任何一个文件的stat/readFile抛错都会中止整个目录扫描。改造后每个文件独立 try-catch错误累积进数组单个坏文件不再拖垮整批加载interface DirLoadResult { workflows: Mapstring, WorkflowDefinition; errors: WorkflowLoadError[]; } async function loadWorkflowsFromDir(dirPath: string): PromiseDirLoadResult { const workflows new Mapstring, WorkflowDefinition(); const errors: WorkflowLoadError[] []; try { const entries await readdir(dirPath); for (const entry of entries) { const entryPath join(dirPath, entry); try { const entryStat await stat(entryPath); if (entryStat.isDirectory()) { const subResult await loadWorkflowsFromDir(entryPath); for (const [filename, workflow] of subResult.workflows) { workflows.set(filename, workflow); } errors.push(...subResult.errors); } else if (entry.endsWith(.yaml) || entry.endsWith(.yml)) { const content await readFile(entryPath, utf-8); const result parseWorkflow(content, entry); if (result.workflow) { workflows.set(entry, result.workflow); getLog().debug({ workflowName: result.workflow.name, dirPath }, workflow_loaded); } else { errors.push(result.error); } } } catch (error) { const err error as NodeJS.ErrnoException; getLog().warn({ err, entryPath }, workflow_file_read_error); errors.push({ filename: entry, error: File read error: ${err.message} (${err.code ?? unknown}), errorType: read_error, }); // Continue processing remaining files } } } catch (error) { const err error as NodeJS.ErrnoException; if (err.code ENOENT) { getLog().debug({ dirPath }, workflow_directory_not_found); } else { getLog().warn({ err, dirPath }, workflow_directory_read_error); } } return { workflows, errors }; }要点递归目录也累积错误子目录通过loadWorkflowsFromDir递归返回后errors.push(...subResult.errors)把深层错误逐级向上汇总。文件级错误记录系统错误码${err.code ?? unknown}让ENOENT文件不存在、EACCES权限不足这类信息直接进入错误文本。目录级 ENOENT 被降级为 debug目录不存在属于常见且无害的场景仓库没有.archon/workflows/不值得向用户报错。Step 4discoverWorkflows返回WorkflowLoadResult加载链路的顶层入口签名随之变更并把错误向上传播到命令层与编排层import type { WorkflowLoadResult, WorkflowLoadError } from ./types; export async function discoverWorkflows(cwd: string): PromiseWorkflowLoadResult { const workflowsByFile new Mapstring, WorkflowDefinition(); const allErrors: WorkflowLoadError[] []; // 应用级默认工作流bundled // const appResult await loadWorkflowsFromDir(appDefaultsPath); // for (const [filename, workflow] of appResult.workflows) { ... } // allErrors.push(...appResult.errors); // 仓库级工作流repoWorkflows同样处理 const workflows Array.from(workflowsByFile.values()); getLog().info( { count: workflows.length, errorCount: allErrors.length }, workflows_discovery_complete ); return { workflows, errors: allErrors }; }workflows_discovery_complete日志同时带上count与errorCount运维侧扫一眼日志即可判断加载健康度。Step 5更新全部调用方command handler、orchestrator、CLIdiscoverWorkflows的返回类型变化是破坏性变更所有调用方必须在同一 PR 内同步更新。/workflow list与/workflow lscommand-handler——把错误列表渲染进用户消息case list: case ls: { const { workflows, errors } await discoverWorkflows(codebase.default_cwd); if (workflows.length 0 errors.length 0) { return { success: true, message: No workflows found.\n\nCreate workflows in .archon/workflows/ as YAML files., }; } let msg ; if (workflows.length 0) { msg Available Workflows:\n\n; for (const w of workflows) { const stepsOrLoop w.loop ? Loop: until \${w.loop.until}\ (max ${String(w.loop.max_iterations)} iterations) : Steps: ${w.steps?.map(s (isSingleStep(s) ? \${s.command}\ : [${String(s.parallel.length)} parallel])).join( - ) ?? none}; msg **\${w.name}\**\n ${w.description}\n ${stepsOrLoop}\n\n; } } if (errors.length 0) { msg \n---\n\n**${String(errors.length)} workflow(s) failed to load:**\n\n; for (const e of errors) { msg - \${e.filename}\: ${e.error}\n; } } return { success: true, message: msg }; }/workflow reload——报告发现的错误数量case reload: { const { workflows, errors } await discoverWorkflows(codebase.default_cwd); let msg Discovered ${String(workflows.length)} workflow(s).; if (errors.length 0) { msg \n\n**${String(errors.length)} failed to load:**\n; for (const e of errors) { msg - \${e.filename}\: ${e.error}\n; } } return { success: true, message: msg }; }/workflow run——只需适配新返回结构工作流本体不受影响const { workflows: discoveredWorkflows } await discoverWorkflows(codebase.default_cwd); workflows discoveredWorkflows;orchestrator 消息处理链路——运行时加载失败只进日志不打断主流程const { workflows: discovered, errors: loadErrors } await discoverWorkflows(workflowCwd); availableWorkflows discovered; if (loadErrors.length 0) { getLog().warn( { errorCount: loadErrors.length, errors: loadErrors }, workflow_load_errors ); }CLIpackages/cli/src/commands/workflow.ts同样采用{ workflows, errors }解构模式保持各入口行为一致。Step 6WorkflowInvocation增加错误字段与大小写不敏感匹配路由层WorkflowInvocation从两个字段扩展为可携带error的接口export interface WorkflowInvocation { workflowName: string | null; remainingMessage: string; /** Error message when workflow name was detected but didnt match */ error?: string; }parseWorkflowInvocation的匹配逻辑升级为三段式export function parseWorkflowInvocation( message: string, workflows: WorkflowDefinition[] ): WorkflowInvocation { const trimmed message.trim(); const match /^\/invoke-workflow\s(\S)/im.exec(trimmed); if (match) { const workflowName match[1]; // Exact match —— 精确匹配拥有最高优先级 const workflow workflows.find(w w.name workflowName); if (workflow) { const remainingMessage trimmed.slice(match.index match[0].length).trim(); return { workflowName, remainingMessage }; } // Case-insensitive match —— 兜底处理 AI 的大小写失误 const caseMatch workflows.find(w w.name.toLowerCase() workflowName.toLowerCase()); if (caseMatch) { getLog().info( { requested: workflowName, matched: caseMatch.name }, workflow_case_insensitive_match ); const remainingMessage trimmed.slice(match.index match[0].length).trim(); return { workflowName: caseMatch.name, remainingMessage }; } // No match - build helpful error —— 给出可执行的修复提示 const available workflows.map(w w.name); getLog().warn({ workflowName, available }, unknown_workflow); return { workflowName: null, remainingMessage: message, error: Unknown workflow: \${workflowName}\. Available: ${available.map(n \${n}\).join(, )}, }; } return { workflowName: null, remainingMessage: message }; }设计考量正则使用im多行模式AI 模型偶尔会在指令前加分析文本^配合多行模式可跨行定位/invoke-workflow命令match.index保证remainingMessage切片位置正确这也与 router.ts 中buildRouterPrompt强调「响应必须是单独一行」的提示互为印证。精确匹配优先、大小写不敏感仅作兜底避免「大小写匹配到错误工作流」的风险。错误信息内置可用工作流清单用户看到Unknown workflow: \assit. Available: assist, fix-github-issue, ...能立即意识到是拼写问题并自行修正。Step 7orchestrator 把路由错误发送给用户路由失败不再静默return false而是先把可读错误消息发给用户const { workflowName, remainingMessage, error } parseWorkflowInvocation( aiResponse, ctx.availableWorkflows ); if (!workflowName) { if (error) { getLog().warn({ error }, workflow_routing_failed); await ctx.platform.sendMessage(ctx.conversationId, error); } return false; }效果对比改造前用户看到的是ctx.platform.sendMessage原样转发的畸形 AI 输出如/invoke-workflow bad-name改造后收到的是「Unknown workflow 可用清单」的明确提示并伴随workflow_routing_failed的结构化日志。Step 8executor.ts代码清理#2648a删除重复 JSDocexecuteStepInternal上方叠了两层注释保留语义更完整的一层/** * Internal function that executes a single step * (extracted to allow parallel execution) */ async function executeStepInternal(8b为loadCommandPrompt补充returns文档明确其返回的是判别联合/** * Load command prompt from file * * param cwd - Working directory (repo root) * param commandName - Name of the command (without .md extension) * param configuredFolder - Optional additional folder from config to search * returns On success: { success: true, content }. On failure: { success: false, reason, message }. */ async function loadCommandPrompt(reason字段来自项目既有的LoadCommandResult判别联合模式invalid_name | empty_file | not_found | permission_denied | read_error是本次改造刻意遵循的既有范式见下文「Patterns to Follow」。Step 9移除未使用的DiscoverWorkflowsResult并更新导出DiscoverWorkflowsResult从未被任何调用方使用由 Step 1 的WorkflowLoadErrorWorkflowLoadResult取代同时更新包入口index.ts的导出// 变更前 type DiscoverWorkflowsResult, // 变更后 type WorkflowLoadError, type WorkflowLoadResult,Step 10补充错误路径测试loader 测试loader.test.ts——覆盖「错误累积」三类场景describe(error accumulation, () { it(should return errors for YAML missing name, async () { const workflowDir join(testDir, .archon, workflows); await mkdir(workflowDir, { recursive: true }); await writeFile( join(workflowDir, invalid.yaml), description: Missing name\nsteps:\n - command: plan\n ); const { workflows, errors } await discoverWorkflows(testDir); expect(workflows).toHaveLength(0); expect(errors).toHaveLength(1); expect(errors[0].filename).toBe(invalid.yaml); expect(errors[0].errorType).toBe(validation_error); expect(errors[0].error).toContain(name); }); it(should load valid workflows and report errors for invalid ones, async () { const workflowDir join(testDir, .archon, workflows); await mkdir(workflowDir, { recursive: true }); await writeFile( join(workflowDir, good.yaml), name: good\ndescription: Works\nsteps:\n - command: plan\n ); await writeFile( join(workflowDir, bad.yaml), name: 123\ndescription: Bad name type\nsteps:\n - command: plan\n ); const { workflows, errors } await discoverWorkflows(testDir); expect(workflows).toHaveLength(1); expect(workflows[0].name).toBe(good); expect(errors).toHaveLength(1); expect(errors[0].filename).toBe(bad.yaml); }); it(should report file read errors without aborting, async () { // 构造一个「一个有效文件 一个权限拒绝文件」的目录 //具体实现取决于操作系统权限能力 }); });router 测试router.test.ts——覆盖错误信息与大小写匹配describe(error information, () { it(should return error message for unknown workflow, () { const response /invoke-workflow non-existent; const result parseWorkflowInvocation(response, testWorkflows); expect(result.workflowName).toBeNull(); expect(result.error).toContain(non-existent); expect(result.error).toContain(Available); }); it(should match workflow names case-insensitively, () { const response /invoke-workflow Assist; const result parseWorkflowInvocation(response, testWorkflows); expect(result.workflowName).toBe(assist); }); it(should not have error when no /invoke-workflow pattern found, () { const response Just a normal message; const result parseWorkflowInvocation(response, testWorkflows); expect(result.workflowName).toBeNull(); expect(result.error).toBeUndefined(); }); });第三个测试尤其关键它保证「普通聊天消息」不会因为新增error字段而误报错误——error只在「检测到/invoke-workflow但名称不匹配」时出现。四、可复用的代码范式Patterns to Follow本次改造刻意复用了代码库中已有的两个模式而非发明新风格1. 判别联合结果类型——LoadCommandResult是既有范例types.ts本次的ParseResult与WorkflowLoadResult沿用了「成功携带数据、失败携带原因」的结构export type LoadCommandResult | { success: true; content: string } | { success: false; reason: invalid_name | empty_file | not_found | permission_denied | read_error; message: string; };2. command handler 中的错误兜底——捕获发现异常并转为用户可读消息try { workflows await discoverWorkflows(codebase.default_cwd); } catch (error) { const err error as Error; getLog().error({ err, cwd: codebase.default_cwd }, workflow_discovery_failed); return { success: false, message: Failed to load workflows: ${err.message}\n\nCheck .archon/workflows/ for YAML syntax issues., }; }五、边界情况与风险缓解Risk/Edge CaseMitigationBundled 内置工作流不应报错保留既有的getLog().error处理 bundled 失败不把 bundled 错误混入面向用户的错误列表错误过多会让/workflow list输出冗长限制只展示前 10 个错误附「and N more」提示大小写不敏感匹配可能误配工作流精确匹配拥有最高优先级大小写不敏感仅在精确匹配失败后作为兜底破坏性变更discoverWorkflows返回类型所有调用方必须在同一个 PR 内同步更新CLIworkflow.ts也调用discoverWorkflowsCLI 调用方必须一并更新避免类型断裂六、验证方式自动化检查在仓库根目录执行bun run type-check bun test packages/core/src/workflows/loader.test.ts bun test packages/core/src/workflows/router.test.ts bun run lint手动验证清单在.archon/workflows/broken.yaml写入缺少name字段的畸形 YAML运行/workflow list—— 应同时展示可用工作流与broken.yaml的错误运行/workflow reload—— 应报告发现的错误数量触发 AI 路由输出一个无效工作流名 —— 应看到面向用户的错误消息。七、从调研到落地当前仓库中的最终形态需要特别说明调研文档中的目标文件路径标注为packages/core/src/workflows/*而当前仓库的实际代码位于packages/workflows/src/——调研方案落地时工作流引擎已被独立为packages/workflows包。以当前仓库为准可以逐一验证上述方案已实现的证据类型定义已落地workflow.ts 中存在完整的WorkflowLoadError含filename/error/errorType: read_error | parse_error | validation_error与WorkflowLoadResult含workflows/errors并且WorkflowSource类型明确了工作流的三种来源bundled内嵌于 Archon 二进制、global~/.archon/workflows/对所有仓库生效、projectrepoRoot/.archon/workflows/同名文件的优先级为bundledglobalproject。包入口 schemas/index.ts 同时导出了这两个新类型。加载器错误累积已实现loader.ts 中parseWorkflow返回可判定的联合类型含WorkflowLoadError分支见loader.ts:1310并以workflow_missing_name、workflow_parse_failed等结构化日志事件记录失败workflow-discovery.ts 的discoverWorkflows返回PromiseWorkflowLoadResult内部allErrors数组负责跨 bundled/global/project 三个作用域聚合错误。路由错误与大小写匹配已实现router.ts 的WorkflowInvocation携带可选error字段parseWorkflowInvocation实现了精确匹配 → 大小写不敏感匹配 → 构建「Unknown workflow Available 清单」错误的三段逻辑同文件还提供resolveWorkflowName的四级回退精确 → 大小写 → 后缀 → 子串后缀与子串匹配遇到歧义时抛Ambiguous workflow异常。用户可见的错误消息已实现command-handler.ts 中/workflow list渲染**N workflow(s) failed to load:**错误区块、/workflow reload报告N failed to load在运行阶段command-handler.ts 与L1192均会输出Workflow \xxx failed to load: 错误详情\n\nFix the YAML file and try again. 的用户提示。可见调研文档提出的「结构化错误 逐文件容错 用户可见反馈」三条主线在当前仓库中均已形成可运行的实现——文档本身是一份高质量的工程改造蓝图而源码则是其落地后的活标本。八、范围边界本次明确不做的事内容说明工作流名称的模糊/Levenshtein 匹配#263 中提及但不在本批次范围内独立的/workflow errors命令#260 的 Option A本方案选择「内联展示错误」而非新命令工作流缓存或重载机制不属于本次改动executor 错误处理改动已有良好覆盖不触碰event-emitter 或 logger 模块改动保持不动这条边界清单同样值得借鉴一个高质量的工程改造应当明确「什么不做」把改动面控制在可评审、可回滚的范围内。错误可见性改造的核心价值在于——它没有发明新的架构只是把链路上早已存在、却被null和false吞掉的信息用结构化的方式重新呈现在用户面前。总结本篇文章完整还原了 Archon 仓库中针对工作流错误可见性的调研与改造方案以WorkflowLoadError/WorkflowLoadResult结构化类型为地基通过parseWorkflow的ParseResult联合返回、loadWorkflowsFromDir的逐文件容错、discoverWorkflows的错误聚合打通了「加载错误可见」的链路再通过WorkflowInvocation.error、大小写不敏感匹配与 orchestrator 的用户消息推送打通了「路由错误可见」的链路并辅以测试、边界管理与明确的「不做清单」。这套「静默吞错 → 结构化错误 → 用户可见反馈」的改造思路对于任何把错误藏进null返回值的系统都具备直接的迁移价值——先从类型设计开始让错误成为返回值的一部分可见性就会随之而来。【免费下载链接】ArchonThe first open-source harness builder for AI coding. Make AI coding deterministic and repeatable.项目地址: https://gitcode.com/GitHub_Trending/archon3/Archon创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考