@yarlisai/core

共享基础模块 — 环境变量辅助工具、日志记录器、流式类型、追踪类型。

安装

npm install @yarlisai/core

设计理念

@yarlisai/core 遵循端口/适配器契约：使用方依赖端口（SomeProvider 接口）并在运行时实例化适配器。切换第三方服务商只需修改一行配置。

使用方式

该包的 README 提供了完整的快速入门指南。mybotbox-platform 本身即为参考使用方 — apps/sat/lib/core/（或同名模块）展示了每个调用点如何使用端口而非直接调用第三方 SDK。

追踪 Span 变换

@yarlisai/core/trace 子路径提供了可移植的执行追踪原语：TraceSpan / ToolCall 类型，以及在展示或存储前对追踪进行规范化处理的纯 span 树变换函数。每个变换函数仅操作 TraceSpan 树，不依赖任何执行器或应用层导入，因此任何能够产生追踪 span 的运行时均可复用同一套处理管道。

import {
  ensureNestedWorkflowsProcessed,
  flattenWorkflowChildren,
  getTraceSpanKey,
  groupIterationBlocks,
  isSyntheticWorkflowWrapper,
  mergeTraceSpanChildren,
  stripCustomToolPrefix,
  type TraceSpan,
} from '@yarlisai/core/trace'

// Unwrap synthetic "Workflow Execution" wrappers from child-workflow traces
const children = flattenWorkflowChildren(childTraceSpans)

// Merge child groups, deduped by span identity (id, or name + time range)
const merged = mergeTraceSpanChildren(existingChildren, children)

// Fold "<name> (iteration <n>)" spans into loop/parallel iteration containers
const rootSpans = groupIterationBlocks(merged)

• flattenWorkflowChildren(spans) — 递归展开合成的工作流包装器，并对嵌套子工作流 span 进行规范化处理。
• mergeTraceSpanChildren(...groups) — 合并多个 span 组，通过 getTraceSpanKey 去重（先出现的组优先）。
• groupIterationBlocks(spans) — 将循环/并行迭代 span 按迭代次序归组到各迭代容器中，并按开始时间排序。
• ensureNestedWorkflowsProcessed(span) — 将 output.childTraceSpans 提升为 children（去重处理），并从输出载荷中移除原字段。
• isSyntheticWorkflowWrapper(span) / getTraceSpanKey(span) / stripCustomToolPrefix(name) — 构成管道的小型断言函数。

将具体执行结果映射为 span 的逻辑保留在产品侧：在 MyBotBox 中，apps/sat/lib/logs/execution/trace-spans/trace-spans.ts 维护 buildTraceSpans(result)（该函数了解执行器的 BlockLog 及 isWorkflowBlockType 断言），并负责组合以上各变换函数。

另请参阅

• 源码
• npm
• ADR 0007 — 端口/适配器契约