ai-core/debug-logging

用途

本技能用于开启或关闭 TanStack AI 活动的调试日志、缩小打印范围，或将日志接入自定义日志器（如 pino、winston）。同一个 debug 选项适用于每个活动：chat()、summarize()、generateImage()、generateSpeech()、generateTranscription()、generateVideo()。

主要能力

开关日志：在各活动的参数中传入 debug: true 或 debug: false。
按类别控制：传入 DebugConfig 对象，可逐类开启/关闭，未指定的类别默认为 true。
自定义日志器：通过 DebugConfig.logger 替换默认的 ConsoleLogger，可将日志管道化到 pino、winston 等。
统一适用：所有活动共用同一个 debug?: DebugOption 字段；provider 包中的实时会话适配器（如 openaiRealtime、elevenlabsRealtime）在其会话选项中也接受同样的 debug。

日志类别

类别	记录内容	适用活动
request	向 provider 发出的出站调用（模型、消息数、工具数）	所有活动
provider	从 provider SDK 收到的每个原始 chunk/帧	流式活动（chat、realtime）
output	向调用方产出的每个 chunk 或结果	所有活动
middleware	每个 middleware 钩子前后的输入与输出	仅 chat()
tools	工具调用执行前后	仅 chat()
agentLoop	智能体循环的迭代与阶段转换	仅 chat()
config	middleware 的 onConfig 钩子返回的配置变换	仅 chat()
errors	管道中任何位置捕获的每个错误	所有活动

仅 chat 适用的类别在非 chat 活动中不会触发，因为这些概念不存在于其管道中。

使用方式

开启：

import { chat } from '@tanstack/ai'
import { openaiText } from '@tanstack/ai-openai'

const messages = [{ role: 'user' as const, content: 'Hello' }]

const stream = chat({
  adapter: openaiText('gpt-5.5'),
  messages,
  debug: true, // all categories on, prints to console
})

每个日志行带有 emoji 与 [tanstack-ai:<category>] 前缀，例如：

📤 [tanstack-ai:request] 📤 activity=chat provider=openai model=gpt-5.2 messages=1 tools=0 stream=true
🔁 [tanstack-ai:agentLoop] 🔁 run started
📥 [tanstack-ai:provider] 📥 provider=openai type=response.output_text.delta
📨 [tanstack-ai:output] 📨 type=TEXT_MESSAGE_CONTENT

关闭：

chat({
  adapter: openaiText('gpt-5.5'),
  messages,
  debug: false, // silence everything, including errors
})

省略 debug 与 debug: false 不同：省略时 errors 类别仍然开启（错误开销小且重要）；要完全静默需使用 debug: false 或 debug: { errors: false }。

DebugOption 的取值：

import type { Logger } from '@tanstack/ai'

type DebugOption = boolean | DebugConfig

interface DebugConfig {
  // 按类别标志。DebugConfig 中省略的任何标志默认为 true。
  request?: boolean
  provider?: boolean
  output?: boolean
  middleware?: boolean
  tools?: boolean
  agentLoop?: boolean
  config?: boolean
  errors?: boolean
  // 可选自定义 logger。默认使用 ConsoleLogger。
  logger?: Logger
}

解析规则：

debug 取值	效果
省略（undefined）	仅 errors 生效；默认 ConsoleLogger
true	所有类别开启；默认 ConsoleLogger
false	所有类别关闭（含 errors）；默认 ConsoleLogger
DebugConfig 对象	未指定的标志默认为 true；logger 替换 ConsoleLogger

缩小打印范围：由于未指定类别默认开启，最简单的方式是将特定标志设为 false：

chat({
  adapter: openaiText('gpt-5.5'),
  messages,
  debug: { middleware: false }, // everything except middleware
})

若要只打印特定集合，需显式将其余设为 false：

chat({
  adapter: openaiText('gpt-5.5'),
  messages,
  debug: {
    provider: true,
    output: true,
    middleware: false,
    tools: false,
    agentLoop: false,
    config: false,
    errors: true, // keep errors on — they're cheap and important
    request: false,
  },
})

接入自定义 logger：

import { chat, type Logger } from '@tanstack/ai'
import { openaiText } from '@tanstack/ai-openai'
import pino from 'pino'

const pinoLogger = pino()
const logger: Logger = {
  debug: (msg, meta) => pinoLogger.debug(meta, msg),
  info: (msg, meta) => pinoLogger.info(meta, msg),
  warn: (msg, meta) => pinoLogger.warn(meta, msg),
  error: (msg, meta) => pinoLogger.error(meta, msg),
}

const messages = [{ role: 'user' as const, content: 'Hello' }]

chat({
  adapter: openaiText('gpt-5.5'),
  messages,
  debug: { logger }, // all categories on, piped to pino
})

默认控制台 logger 以 ConsoleLogger 导出，便于包装：

import { ConsoleLogger } from '@tanstack/ai'

非 chat 活动（同一个 debug 选项）：

import {
  summarize,
  generateImage,
  generateSpeech,
  generateTranscription,
  generateVideo,
} from '@tanstack/ai'
import {
  openaiSummarize,
  openaiImage,
  openaiSpeech,
  openaiTranscription,
  openaiVideo,
} from '@tanstack/ai-openai'
import { logger } from './logger'
import { audio } from './recording'

summarize({
  adapter: openaiSummarize('gpt-5.5'),
  text: 'Long article…',
  debug: true,
})
generateImage({
  adapter: openaiImage('gpt-image-2'),
  prompt: 'a cat',
  debug: { logger },
})
generateSpeech({
  adapter: openaiSpeech('tts-1-hd'),
  text: 'Hello',
  debug: { request: true },
})
generateTranscription({
  adapter: openaiTranscription('gpt-4o-transcribe'),
  audio,
  debug: false,
})
generateVideo({
  adapter: openaiVideo('sora-2'),
  prompt: 'a wave',
  debug: { output: true },
})

provider 包中的实时会话适配器（如 openaiRealtime、elevenlabsRealtime）在其会话选项上接受同样的 debug?: DebugOption，会输出 request、provider、errors 行；仅 chat 适用的类别不适用。

适用场景

需要快速查看请求、provider 原始帧、输出 chunk、middleware、工具调用、智能体循环等管道细节时。
需要将日志结构化接入现有日志系统（pino、winston 等）时。
需要在开发或测试中按类别精准控制日志噪音时。

限制与注意事项

依赖说明：本技能建立在 ai-core 之上，使用前应先阅读 ai-core 的关键规则。
省略 debug 不等于静默：errors 仍会开启。
若只是观察内置管道，debug 选项严格快于编写日志 middleware；需要转换 chunk 而非仅查看时才应使用 middleware。
用户提供的 Logger 若抛出异常，异常会被 SDK 吞掉以免掩盖触发日志的真实错误；但仍建议实现不抛异常的 logger（例如在 logger 内保护序列化，捕获循环引用等）。
本技能资料未涉及收费、价格、平台或效果等信息。