上篇我们深入了 project/workspace 管理——当一切正常时opencode 如何组织工作单元。老实说，这篇来看另一面：当出问题时一条错误从源码到使用者终端的完整链路。按理说，

如果你要设计一个 AI Agent 的错误处理——模型超时、配置格式错、权限不足、插件崩溃——你会怎么组织？一个直观的想法是每个模块各自 try-catch，各写各的格式化逻辑。opencode 的作者也是这么想的开始——但最终做了一个关键决定：分散定义错误类型，集中格式化错误消息。

使用者痛点汇总

• 文案风格参差不齐不同模块自定义错误导致提示不统一，影响使用者体验。
• 调试信息不一致每个模块自行决定展示内容，难以快速定位根因。
• 维护成本高一旦某个错误类添加字段或更改结构，需要遍历全仓库更新格式化逻辑。
• 结构化字段易丢失直接转为字符串后细节信息被抹平，后续处理变得困难。
• 错误级别编码分散exitCode、空串返回等行为分布在多处，不利于统一管理和演进。
• E2E 级别可见性差: 错误类型散落仓库，缺乏全局视角。

— opencode 面对的种失败

至于一个直观想法。各模块各自为政

如果每个命令自己 try-catch、自己决定如何显示错误，后果很清晰：

• 文案风格参差： 调试信息不一致；使用者面对五花八门的错误格式。
• 维护隐患： 当错误结构发生变化，要搜遍全仓库改格式化代码。

opencode 的实际场景

opencode 作为一个 Agent 应用，错误来源天然多元：

• CLI 层： 参数缺失、session 找不到、配置 JSON 格式错;
• 业务层： 模型不可用、provider 初始化失败、权限判定拒绝（DeniedError);
• 程序层： 插件加载失败、SSE 流超时、配置方法拼写错误.

这些场景产出的错误数据结构完全不同——有的带 modelID 和 suggestions。有的带 issues 数组，有的只有一个 message 字符串。但它们最终归宿都是同一个地方：终端使用者看到的一行“Error: …”字句，

— 三层错误架构

至于定义层。TaggedErrorClass 家族

tagged error classes 均继承自 Schema.TaggedErrorClass，每个自带 _tag 标签和结构化字段集。 Schema 自动生成 _tag，使其不可篡改。从而可以通过字符串匹配精准路由，而不是依赖 instanceof 或鸭子类型。下面是典型实现：

// packages/opencode/src/provider/provider.ts
export class ModelNotFoundError extends Schema.TaggedErrorClass
("ProviderModelNotFoundError",{
providerID: ProviderV2.ID,modelID: ModelV2.ID,suggestions: Schema.optional),cause: Schema.optional,}) {}
// packages/core/src/permission.ts
export class DeniedError extends Schema.TaggedErrorClass
("PermissionV2.DeniedError",{
说到rules，PermissionSchema.Ruleset。}) {}
// packages/core/src/session/error.ts
export class MessageDecodeError extends Schema.TaggedErrorClass
("Session.MessageDecodeError",{
sessionID: SessionSchema.ID,messageID: SessionMessage.ID,}) {}

至于路由层，FormatError 的二十路 switch

Status of any error finally flows into cli/error.ts's FormatError function:

// packages/opencode/src/cli/error.ts
export function FormatError: string | undefined {
if ) {
if process.exitCode = input.exitCode;return stringField?，"";}
if ) { /* ... */ }
if ) {
const suggestions = Array.isArray
input.suggestions.filter
:;return : )，"Try: \`opencode models\` to list available models",].join;}
if ) { /* ... */ }
if ) return "";return undefined;}

This function is a pure mapper that can also encode severity via exitCode changes or empty strings.

从显示层来看，UI.error 与 ANSI

// packages/opencode/src/cli/ui.ts
export function error {
if ) {
message = message.slice;不过，}
println;}

The UI layer only handles final rendering—no assumptions about content.

— FormatError 格式塔

从处理链优先级来看。从特定到通用

• Clique errors first — most frequent.
• A follow‑up chain for provider errors.
• The config series and permission series next.
• User‑cancelled errors last – silently ignored.

Provider 错误的特殊处理

// packages/opencode/src/provider/error.ts
export function parseAPICallErro​in(
input这方面，{ providerID:string,error:any}
):ParsedAPICallErro​in{
const m=message;const body=json;if||input.error.statusCode===429||body?.error，.code==="context_length_exceeded"){
return{type:"context_overflow",message:m};}
return{
再看type，"api_error",message:m。statusCode:input.error.statusCode,isRetryable:true//...
};}
This two‑stage parser distinguishes context overflow from generic API errors and guides agent behavior accordingly.

{— 为什么集中路由？}{三个方案对比}

维度 A. 分散式 B. 集中式 C. 全局 catch 

文案统一
❌ N 个模块 N 种风格
✅ 一个维护点 ⚠️只改格式不变内容新增 Error 成本只改本模块改本模块+cli/error.ts不改
语义保留
❌ 易丢失结构化字段
✅ 按 tag 精准提取
全变字符串
⚠️ 隐式

可测试性
分散难测
✅ 单测集中
纯函数。无副作用
单测易编写
E2E 难见

全局可见性
散落仓库
✅ cli/error.ts即目录





B 决策点在于s lossless semantic value outweighs double modification cost.

Error fields are precisely extracted in one place rar than duplicated across modules.

A single modification point makes future format evolution trivial – e.g.,adding JSON output mode would only touch Format ​​ .