本文约定 opencode-observer 的职责边界、模块依赖、观测契约和运行约束,用于指导实现与重构。当前支持 run、interaction、LLM、tool、skill.load、compaction 和 permission.check 七类 span。
- Trace Schema:期望规范 定义目标 trace 结构与 span 属性语义。
- OpenCode Trace Schema 定义当前可观察行为、trace 拓扑、生命周期、导出字段和实现差距。
- 适配层设计 定义源数据识别、模型采集和跨对象协调机制。
- README 定义配置方式、启用条件和使用限制。
- 本文定义这些要求由哪一层承担。内部实现可调整,但不得隐式改变上述行为与数据口径。
- 行为识别与遥测分离:适配层识别业务行为及其生命周期,遥测层依据契约调用管理 span,不重复推断业务边界。
- 契约独立:层间只传递已识别的行为和 SDK 无关的数据,使宿主适配与遥测实现能够独立演进、测试。
- 以证据为准:只记录有源数据支持的行为、时间和关联,缺失时按 OpenCode Trace Schema 降级或省略。
- 不干扰宿主:遥测和正文采集默认关闭;采集、导出及诊断失败不得影响 OpenCode 的执行。
使用 TypeScript 和 Bun,通过模块边界落实分层,无需拆包或引入跨进程通信。
三层之间的代码依赖如下,箭头表示“依赖于”:
adapter → contract ← telemetry
| 层 | 负责 | 不负责 |
|---|---|---|
| 适配层 | 接入宿主,解析源数据,识别对象身份、归属、开始、更新、结束及结果 | 创建或修改 OTel 对象,编码遥测属性,透传原始 SDK 对象 |
| 契约层 | 定义对象引用、数据、操作及其语义 | 处理源事件,维护运行状态,执行网络请求 |
| 遥测层 | 实现契约,维护对象到 span 的映射及上下文,编码数据,导出并清理资源 | 重新识别业务行为,读取源 SDK 对象,通过宿主 client 补查数据 |
适配层可以维护行为状态,遥测层可以维护 span 状态。例如,上下文溢出(overflow)能否恢复由适配层判断;确认任务失败后才提交结束操作,遥测层据此结束 span。
下表为各目录允许的依赖,未列出的跨层依赖均禁止;类型导入、重导出和动态加载同样受限。
| 目录 | 允许的依赖 |
|---|---|
src/adapter/ |
本层、契约、OpenCode SDK、AI SDK、平台库 |
src/contract/ |
本层契约类型 |
src/telemetry/ |
本层、契约、OTel SDK、gRPC 传输库、平台库、包版本元数据 |
src/user/ |
本模块、平台库 |
user 是三层之外的独立身份模块,由插件初始化模块装配,见第 3 节。
内部依赖方向为 opencode → trackers → model → shared,允许越级使用下游模块,禁止反向依赖:
opencode:接入宿主 hooks/events,负责事件分发、session 关联、恢复判断及跨对象协调。trackers:负责自身观测对象的行为识别与生命周期跟踪,可以接收并解析相关的源 SDK 对象,也可以使用已解析的数据。所有 tracker 遵循同一职责与依赖边界;全局事件分发和跨对象协调由opencode协调模块负责,tracker 不直接创建或调用其他 tracker。model:接入 AI SDK 回调,解析消息与请求、归一化用量并处理传播字段,不依赖 tracker。LLM 与压缩摘要共用用量归一化规则。shared:提供适配层内部共用的数据快照、错误归一化、数值校验和错误隔离。
以上模块均属于适配层。tracker 必须将观测结果转换为 SDK 无关的契约数据,通过注入的 Observer 接口提交,不直接依赖遥测实现;对应的 span 状态和导出由遥测层管理。
每个 coordinator 只创建一组 run、interaction、LLM、tool、permission 和 compaction tracker,跨 run 复用行为对象及其回调连接。各 tracker 自己持有数据;interaction、LLM、tool、permission 和 compaction 的数据按 (sessionID, runID) 分区,不建立集中业务状态模型。coordinator 的 ActiveRunState 只保存活动 run 引用、父工具及 overflow 恢复信息。
skill.load 复用 tool tracker 的源事件状态机和分区,不新增独立 tracker。适配层将 skill 工具调用识别为技能加载,通过独立的 Skill 契约提交名称、目录、截断状态及可选返回内容;遥测层独立管理 skill.load span。工具调用开始通知经 coordinator 关联提前到达的权限请求,结束通知共用权限清理路径;task 的子 run 关联仍只适用于 task 工具。
coordinator 在接受新 run 时显式调用各 tracker 的 open(run) 登记数据分区。事件处理、归属查询及收尾操作携带完整 run 引用,只使用已有分区。close / finish 提交观测结果,release(run) 释放该 run 的全部数据。tracker 不提供实例关闭时的数据清理接口。shared/runs.ts 仅提供各 tracker 独立使用的分区容器,不保存共享业务数据;具体数据类型和识别规则留在对应 tracker 中。
跨对象归属由 coordinator 查询并解析,再作为数据传入 tracker;tracker 不接收其他 tracker 的查询、解析函数或返回归属的回调。tracker 可以暴露自身的归属查询,以及 unresolved(run) 所需关联线索;coordinator 在相关证据到达后调用 associate 补齐归属。已有归属在提交观测对象后固定。onFinish、onChildSessionObserved 等回调只通知生命周期变化,由 coordinator 安排清理和绑定,不用于反向获取归属。
由观测操作与对象引用、结构化消息与数据类型组成,只表达层间协作所需的语义。契约类型可在本层复用,不包含 tracker、SDK 接入或 span 实现;接口约束见第 4 节。
内部依赖方向为 factory → observer → spans:工厂装配 OTel SDK/exporter,Observer 实现观测契约并协调记录、导出与关闭,span 模块维护遥测状态及数据映射。span 模块不反向依赖工厂或 Observer。
这里的 Observer 是契约的具体实现,其接口定义仍属于契约层。OTLP 编码和传输使用 SDK/exporter,不自行实现协议。遥测工厂按 otlpProtocol 按需加载 HTTP/JSON、HTTP/Protobuf 或 gRPC exporter,默认使用 http/json。HTTP 协议默认使用 4318 端口并补齐 /v1/traces;gRPC 默认使用 4317 端口,不追加路径。otlpHeaders 在 gRPC 下转换为 metadata,其余导出超时和 span 处理逻辑共用。
LLM 在请求准备阶段创建 span 以传播上下文;fetch 计时边界后到时,通过 LlmFinish.timing 提供。遥测层保留相同 span ID,用实例内 WeakMap 将实际起点交给时间处理器,在 BatchSpanProcessor 之前创建只读导出视图,校准 startTime/duration,不修改 SDK span 的只读字段。结束时间和首块耗时同步使用选定边界;首块终点由 LlmUpdate.firstChunkObservedAt 暂存,在收尾确定起点后计算。没有校准时按原消息边界导出;不把适配层的 fetch 对象交给遥测层。
本文所称插件初始化模块,对应 src/index.ts。ObserverPlugin 读取插件配置并返回宿主 hooks;首次 config 回调完成身份解析、遥测实现创建和适配层装配。入口 hooks 将行为回调转发给适配层,不承载行为识别。重复配置回调复用首次装配,关闭后不重新初始化。
插件初始化模块可以同时依赖配置、用户身份、适配层和遥测层以完成装配。插件初始化模块和配置模块不承载行为识别或遥测实现;事件处理必须经契约调用,不能借装配逻辑绕过边界。
首次装配成功后,入口通过宿主日志 API 异步记录初始化成功,并调用遥测层的 TCP probe 检查接收端主机和端口。probe 最长 5 秒,仅建立并关闭 TCP 连接,不发送协议数据或创建 span;入口负责记录结果并在关闭时取消探测。探测和日志不阻塞配置回调,失败不影响宿主或禁用导出。初始化日志不表示上报成功,TCP 可达也不表示 TLS、鉴权或 OTLP 接收成功。
各层定义自身需要的配置类型,由插件初始化模块传入数据,不反向依赖根目录的配置解析逻辑。遥测关闭时不创建实现或注册采集逻辑;开启后才加载 OTel 等较重依赖。支持的模型路径按需接入 SDK 回调,正文关闭时仍可观察响应模型和输出类型,包括 SDK 确认未配置 output 时的默认 text。
用户身份模块独立于三层,由插件初始化模块直接调用。身份结果须区分成功、最终失败和未解析,避免把不同情况统一当作空值。初始化模块将身份结果与静态属性合并进 spanAttributes,tracker 和观测契约不读取、保存或传递 user ID。
attributePrefix 控制插件生成的内建 opencode.* span 属性键,独立于控制名称的 tracePrefix,两者默认均为 opencode.。配置仅传入遥测层,在 span 创建、更新和结束时生成最终键名,适配层及契约不参与命名。显式自定义属性保持原键名;Observer 初始化时按默认前缀和配置前缀生成内建字段保护规则。
契约以行为为单位提供开始、更新、结束操作,以及上下文传播、刷新和关闭能力。完整接口与类型见 Observer 契约,本文约束其语义,不重复维护类型定义。
- 标识与关联:对象 ID 稳定且明确作用域;更新、结束和父子关系使用精确引用,不按调用时的“当前交互”猜测归属。
- 时间:统一使用 Unix epoch 毫秒,明确区分源发生时间和本地观察时间,不以异步处理或导出时间替代。
- 更新:明确快照替换和增量追加语义;增量可去重,重复输入保留首次快照。区分未提供、已知为空与明确清除,提交后的快照不受源对象后续修改影响。
- 终态:错误使用结构化契约数据,不传源异常对象。重复结束或迟到更新不得重建、改写已结束对象;对象结束不等于网络导出成功。
- 抽象边界:契约不接收原始事件,不暴露 OTel 对象或通用 span 操作。属性名称、span kind、状态及序列化由遥测层按 OpenCode Trace Schema 映射。
适配层的源事件去重与遥测层的契约幂等分别维护各自的状态。适配层在提交观测和触发生命周期回调前识别重复输入,避免重复开启 run、重复关联或重复收尾;遥测层按 span 类型和完整契约引用保证对象不会重复创建、已结束对象不会重建。即使底层 OTel 忽略重复结束,也不能代替这两个边界的保证。契约层只定义语义,不保存共享去重状态。
幂等按操作语义落实:RunUpdate.input 按输入 ID 追加一次并保留首次快照;模型请求、响应和工具参数等更新仍允许同一对象的新快照替换旧值,不能仅因对象 ID 相同就忽略更新。正文采集关闭时,遥测层不创建 run 输入聚合缓存;防止旧用户消息被识别为新任务的历史仍由适配层保留。
captureContent 同时约束适配层和遥测层,控制正文、LLM 工具定义和工具执行描述;关闭时不为遥测解析、保留、传递或导出这些内容。模型请求/响应 HTTP headers(含错误响应)还要求 captureHttpHeaders 开启;两个开关默认关闭,任一关闭时均不为遥测解析、保留、传递或导出 headers。输出类型及技能名称、目录、截断状态不受这些开关控制;技能名称通过白名单字段提取,不要求保留完整工具参数。未采集数据不能由自定义属性补造,内建派生字段不能被覆盖;具体字段范围见 OpenCode Trace Schema。
插件初始化模块在首次 config 回调中取得身份结果后创建遥测实现,身份解析失败后继续启动。身份在实例内保持固定,不自动刷新或回填既有 span,以保持同一实例内身份一致。
| 通道 | 职责与来源 |
|---|---|
span 的 user.id |
插件初始化模块合并查询结果与静态配置,通过通用 spanAttributes 交给遥测层;七类 span 均使用这份初始化快照 |
出站 tracestate 的 user_id |
插件初始化模块将出站身份快照交给适配层,由适配层编码;不以静态 span 属性替代解析结果 |
两个通道的未知值处理不同,须遵循 身份字段规则 和 传播规则。遥测层不参与身份解析,不增加专用身份回调或 processor;身份属性独立于正文采集。
顶层 run 从空上下文创建独立 trace;前台子 run 仅通过明确关联的活动 task 工具继承父 trace,不恢复外部 trace 上下文配置。
模型请求发出前,适配层通过 llmTraceHeaders 同步取得指定活动 LLM 的 W3C 字符串字段。遥测层使用实例内 propagator 序列化该 span,不依赖全局 active context;引用未知、已结束或实现已关闭时不返回传播字段。
适配层负责将 trace 上下文和可传播的身份字段写入请求。此过程不修改契约返回对象、OTel SpanContext 或导出 traceState。无法唯一关联时不传播;正文开关不影响传播。native 路径及同名 headers 冲突的当前限制见 OpenCode Trace Schema §3.3。
观测记录在本地同步处理;触发刷新的事件回调在记录完成后等待 Observer.flush()。导出队列、超时及失败处理由遥测层统一管理,各 hook 不自行排队、重试或操作 provider。
OTLP 发送与重试预算、批处理导出等待、主动刷新等待分别通过 otlpTimeoutMillis、batchExportTimeoutMillis、forceFlushTimeoutMillis 配置,默认值为 10 秒、30 秒、30 秒。配置层解析插件选项及对应环境变量,遥测工厂将值传给 exporter、BatchSpanProcessor 和 provider。重试由 SDK 执行;最终失败的批次不重新入队,也不持久化。主动刷新超时不等同于关闭总超时。
宿主 hooks 和 SDK 回调边界均须隔离同步异常与异步拒绝;事件内的刷新由外层 hook 统一保护。日志不阻塞回调,其自身失败直接忽略。进程内共享回调按监听器隔离失败,保护内部关联标识的清理,诊断只发送给仍活动的实例。观测不得修改 hook 的业务输出,传播所需的请求 headers 按第 5.2 节处理。
失败隔离以宿主入口、后台异步任务和独立监听器为边界。同一同步处理阶段共用保护;未被调用方等待的后台任务单独处理失败,字段降级直接安全上报错误。
| 接口 | 语义 |
|---|---|
flush(): Promise<void> |
异步刷新 SDK 缓冲区中已结束的数据,不结束活动对象;触发刷新的事件回调等待完成 |
shutdown(): Promise<void> |
清理未完成对象,由 SDK/exporter 排空并关闭; |
适配层在 session idle、error 或删除后触发刷新。协调器在宿主 dispose hook 内统一关闭:先注销模型采集监听器,再提交仍在等待的 LLM 结果,保留已经取得的 assistant 完成时间,最后调用注入的 Observer.shutdown()。遥测层按实际父子关系结束剩余活动 span,再异步等待导出并关闭资源。重复调用返回同一个关闭 Promise。插件初始化模块只负责装配,不再中转关闭回调。
关闭只要求完成观测收尾、解除外部订阅并停止向已关闭实例提交采集数据;LLM tracker 提交等待中的结果后释放调用,不额外遍历清空其他 tracker、session registry 或 SDK 请求缓存。宿主和异步任务不再持有实例后,剩余纯数据由垃圾回收处理。正常运行期间移除已结束对象、释放父子绑定及清理所属 run 的上下文仍属于生命周期管理。
Observer 统一持有已结束 span 的历史记录,按 run、span 类型和完整对象引用隔离;需要保留的 interaction / compaction 上下文与去重标识使用同一条记录。span 模块只查询和登记完成状态,由 Observer 在结束 run 时先收尾后代,再统一释放子 span 记录,仅保留 run 的关闭标记至实例结束,用于拒绝旧任务重建。清理一个 run 不影响其他活动 run 的历史记录。
关闭必须幂等,多次调用共享同一过程;关闭开始后不再修改遥测状态。刷新和关闭失败通过 Promise 拒绝反馈,由调用边界隔离并诊断。
适配层根据源证据识别对象身份、归属和生命周期,并处理重复、迟到及乱序输入。tracker 负责自身对象,协调模块负责跨对象关联、状态联动和清理;遥测层依据已提交的契约操作维护 span,不参与源证据判断。
具体识别、采集和状态管理规则见 适配层设计。观测结果的创建条件、时间、父子关系、失败分类和降级口径以 OpenCode Trace Schema 为准;层间提交遵循第 4 节契约,失败隔离与实例关闭遵循第 6 节。
- 依赖边界:检查实际静态与动态依赖,覆盖类型导入、重导出和相对路径,避免绕过模块限制。
- 独立测试:适配层可注入记录调用的契约实现,无需 OTel provider;遥测层可直接接受契约调用,无需构造宿主事件或 client。各 tracker 按其实际接口使用源 SDK 对象或已解析数据测试,全局事件分发与跨对象协调用协调模块测试。
- 行为一致:验证 OpenCode Trace Schema 中的对象关系、生命周期、时间、状态和字段口径,并覆盖重复通知、迟到数据、跨会话隔离、重试及恢复。
- 去重边界:适配层测试直接断言 Observer 操作和生命周期回调次数,避免遥测层的幂等掩盖重复处理;遥测层测试直接重放契约调用,验证完整引用隔离、首次快照和终态保护。
- 采集隔离:验证正文开关、快照替换、回调乱序、跨实例隔离、关联标识清理,以及身份和传播独立于正文采集。
- 宿主不受影响:集成/E2E 覆盖 hook 到 OTLP 的完整路径;慢导出和失败不改变业务执行或时间边界,关闭清理未完成对象且不重复导出。
验证命令及修改类型对应的必需检查见 AGENTS.md。