@jerryliang122/openclaw-qqbot 1.0.8 → 2.0.0

package/src/tools/secret-input.ts

@@ -10,23 +10,31 @@
  * 记录里，且 AI 随后要读取使用；secret kind 是「受保护的机密」
  * （write-only，代理不可读），存进去 AI 反而用不了（2026-08-30 用户反馈）。
  *
+ * 会话目标解析（2026-09-23 修复）：双层回退——请求级 ALS 优先，框架
+ * run 级 deliveryContext 兜底。openclaw 把 turn 延迟到入站消息异步子树
+ * 之外执行（followup/collect 队列）时 ALS 为空，此前工具直接报
+ * 「无法获取当前会话目标」失败；工厂注册形式拿到的 deliveryContext
+ * 由框架按当前 run 的 sessionCtx 派生，延迟 turn 下依然正确（见
+ * src/tools/tool-session.ts）。
+ *
  * 非阻塞：工具发卡后立即返回，AI 应结束本轮；执行与回执完全由插件自治。
  */
 import type { OpenClawPluginApi } from 'openclaw/plugin-sdk';
-import { tryGetBotForAccount } from '../bot-instance.js';
+import { resolveGatewayForSend } from '../outbound/outbound-service.js';
 import { isValidSecretName } from '../features/secret-store-cli.js';
 import {
   DEFAULT_SECRET_INPUT_TTL_MS,
   cancelPendingSecretInput,
   registerPendingSecretInput,
 } from '../features/secret-input-store.js';
-import { getRequestAccountId, getRequestTarget } from '../request-context.js';
-import { parseTarget } from '../outbound/target.js';
+import { parseTarget, QQBOT_PREFIX_RE } from '../outbound/target.js';
 import { createPluginLogger } from '../utils/plugin-logger.js';
+import { resolveToolSessionRoute, type ToolDeliveryContext } from './tool-session.js';
 import type { InlineKeyboard, KeyboardButton } from '../types.js';
 
-// 工具 execute 无 logger 参数可传；request-context 在工具执行期间处于活跃，
-// 模块级 logger 的 enrichMeta 会自动带上 accountId/openId/messageId
+// 工具 execute 无 logger 参数可传；入站消息处理链路内 request-context
+// 处于活跃，模块级 logger 的 enrichMeta 自动带上 accountId/openId/messageId
+// （延迟/排队 turn 中 ALS 为空，路由解析回退 deliveryContext）
 const toolLog = createPluginLogger({ prefix: '[tool:secret-input]' });
 
 // ========== JSON Schema ==========
@@ -104,89 +112,113 @@ function json(data: unknown) {
 
 // ========== 注册入口 ==========
 
+// 工厂注册形式（2026-09-23 修复）：框架调用工厂时携带当次 run 的
+// deliveryContext——turn 被框架延迟/排队执行（ALS 已失效）时，工具
+// 仍能从 deliveryContext 解析当前会话目标（见 tool-session.ts）。
 export function registerSecretInputTool(api: OpenClawPluginApi): void {
   api.registerTool(
-    {
-      name: 'qqbot_secret_input',
-      label: 'QQBot Secret Input Card',
-      description:
-        '当用户要交付一个新密钥/凭据（API Key、Token 等）给系统保存时调用：' +
-        '向用户私聊发送一张密钥输入卡片，用户把密钥粘贴在输入框发送后，' +
-        '插件会自动拦截该消息并执行 openclaw secrets store set 完成保存，' +
-        '结果由插件直接回复用户。密钥内容不会进入对话。' +
-        '必须由用户提供 name 参数（环境变量名）。',
-      parameters: SecretInputSchema,
-      async execute(_toolCallId, params) {
-        const p = params as { name?: string; description?: string };
-        const name = (p.name ?? '').trim();
-        if (!name) return json({ error: 'name 为必填参数（环境变量名）' });
-        if (!isValidSecretName(name)) {
-          return json({
-            error:
-              '环境变量名不合法：必须以大写字母开头，仅含大写字母/数字/下划线，最长 128 字符' +
-              `（收到 "${name}"）。示例：OPENWEATHER_API_KEY。请修正后重试。`,
-          });
-        }
-        // 恒为 env：见文件头注释（卡片值 = 代理可读环境，secret 是 write-only 代理不可读）
-        const kind = 'env' as const;
+    (factoryCtx) => {
+      const delivery = (factoryCtx as { deliveryContext?: ToolDeliveryContext }).deliveryContext;
+      return {
+        name: 'qqbot_secret_input',
+        label: 'QQBot Secret Input Card',
+        description:
+          '当用户要交付一个新密钥/凭据（API Key、Token 等）给系统保存时调用：' +
+          '向用户私聊发送一张密钥输入卡片，用户把密钥粘贴在输入框发送后，' +
+          '插件会自动拦截该消息并执行 openclaw secrets store set 完成保存，' +
+          '结果由插件直接回复用户。密钥内容不会进入对话。' +
+          '必须由用户提供 name 参数（环境变量名）。',
+        parameters: SecretInputSchema,
+        async execute(_toolCallId: string, params: unknown) {
+          const p = params as { name?: string; description?: string };
+          const name = (p.name ?? '').trim();
+          if (!name) return json({ error: 'name 为必填参数（环境变量名）' });
+          if (!isValidSecretName(name)) {
+            return json({
+              error:
+                '环境变量名不合法：必须以大写字母开头，仅含大写字母/数字/下划线，最长 128 字符' +
+                `（收到 "${name}"）。示例：OPENWEATHER_API_KEY。请修正后重试。`,
+            });
+          }
+          // 恒为 env：见文件头注释（卡片值 = 代理可读环境，secret 是 write-only 代理不可读）
+          const kind = 'env' as const;
 
-        const target = getRequestTarget();
-        const accountId = getRequestAccountId() ?? 'default';
-        if (!target) {
-          return json({ error: '无法获取当前会话目标，此工具仅支持在 QQ Bot 消息会话中使用' });
-        }
-        const parsed = parseTarget(target);
-        if (parsed.scope !== 'c2c' || !parsed.targetId) {
-          return json({
-            error:
-              `密钥输入卡片仅支持私聊（c2c）会话，当前目标 ${target} 不适用` +
-              '——密钥不应出现在群聊中。请引导用户在私聊中发起。',
-          });
-        }
+          const route = resolveToolSessionRoute(delivery);
+          if (!route) {
+            return json({
+              error:
+                '当前运行没有 QQ 会话来源（可能由定时任务或框架内部触发的 run），' +
+                '无法定位要发卡的用户。请引导用户在 QQ 私聊中直接发起密钥输入，' +
+                '不要在无会话上下文的任务里调用本工具。',
+            });
+          }
+          // scope 必须在 parseTarget 之前显式判定：parseTarget 会把 channel:
+          // 归一化为 c2c（target.ts「channel 不被 SDK ChatScope 支持」），
+          // 频道会话若不在此拦截就会把频道 ID 当 c2c openid 发卡
+          // （Sourcery 复审，2026-09-23）
+          const scope = QQBOT_PREFIX_RE.exec(route.target)?.[1]?.toLowerCase();
+          const parsed = parseTarget(route.target);
+          if (scope !== 'c2c' || !parsed.targetId) {
+            return json({
+              error:
+                `密钥输入卡片仅支持私聊（c2c）会话，当前目标 ${route.target} 不适用` +
+                '——密钥不应出现在群聊或频道中。请引导用户在私聊中发起。',
+            });
+          }
 
-        const bot = tryGetBotForAccount(accountId);
-        if (!bot) {
-          return json({ error: `账户 ${accountId} 的 gateway 尚未启动，无法发送密钥输入卡片` });
-        }
+          // 发送账户解析：路由 accountId（缺省 default）→ 精确命中，
+          // 未命中且仅单账号运行时回退（与出站发送路径一致，issue #15 约定）。
+          // pending 必须登记在**实际发送账号**名下——捕获中间件按其网关的
+          // accountId 查询 pending。
+          const requestedAccountId = route.accountId ?? 'default';
+          const resolvedGateway = resolveGatewayForSend(requestedAccountId);
+          if (!resolvedGateway) {
+            return json({ error: `账户 ${requestedAccountId} 的 gateway 尚未启动，无法发送密钥输入卡片` });
+          }
+          const accountId = resolvedGateway.accountId;
+          const bot = resolvedGateway.gw.bot;
 
-        const description = p.description?.trim() || undefined;
-        // 先登记后发卡（避免「先发后登」竞态，同 multi-question 约定）
-        registerPendingSecretInput({
-          accountId,
-          senderOpenid: parsed.targetId,
-          name,
-          kind,
-          description,
-          createdAt: Date.now(),
-        });
-        try {
-          await bot.sendTextWithKeyboard(
-            { scope: 'c2c', targetId: parsed.targetId },
-            buildSecretInputCard(name, description, DEFAULT_SECRET_INPUT_TTL_MS / 60_000),
-            buildSecretInputKeyboard() as never,
-          );
-        } catch (err) {
-          cancelPendingSecretInput(accountId, parsed.targetId);
-          toolLog.error(`card send failed: ${err instanceof Error ? err.message : String(err)}`, { name, accountId });
-          return json({
-            error: `密钥输入卡片发送失败：${err instanceof Error ? err.message : String(err)}`,
+          const description = p.description?.trim() || undefined;
+          // 先登记后发卡（避免「先发后登」竞态，同 multi-question 约定）
+          registerPendingSecretInput({
+            accountId,
+            senderOpenid: parsed.targetId,
+            name,
+            kind,
+            description,
+            createdAt: Date.now(),
           });
-        }
+          try {
+            await bot.sendTextWithKeyboard(
+              { scope: 'c2c', targetId: parsed.targetId },
+              buildSecretInputCard(name, description, DEFAULT_SECRET_INPUT_TTL_MS / 60_000),
+              buildSecretInputKeyboard() as never,
+            );
+          } catch (err) {
+            cancelPendingSecretInput(accountId, parsed.targetId);
+            toolLog.error(`card send failed: ${err instanceof Error ? err.message : String(err)}`, { name, accountId });
+            return json({
+              error: `密钥输入卡片发送失败：${err instanceof Error ? err.message : String(err)}`,
+            });
+          }
 
-        toolLog.info(`card sent, pending registered name=${name} ttlMinutes=${DEFAULT_SECRET_INPUT_TTL_MS / 60_000}`);
+          toolLog.info(
+            `card sent, pending registered name=${name} accountId=${accountId} route=${route.source} ttlMinutes=${DEFAULT_SECRET_INPUT_TTL_MS / 60_000}`,
+          );
 
-        return json({
-          ok: true,
-          name,
-          kind,
-          command: `openclaw secrets store set ${name} --kind env --value <用户输入>`,
-          instruction:
-            '卡片已发送给用户。用户下一条私聊消息将被插件自动拦截（不会进入对话），' +
-            `执行上述命令保存密钥，成功/失败由插件直接回复用户。` +
-            '请直接结束本轮（可告知用户按卡片提示发送密钥），不要等待用户输入，' +
-            '也不要让用户把密钥内容发到对话里。',
-        });
-      },
+          return json({
+            ok: true,
+            name,
+            kind,
+            command: `openclaw secrets store set ${name} --kind env --value <用户输入>`,
+            instruction:
+              '卡片已发送给用户。用户下一条私聊消息将被插件自动拦截（不会进入对话），' +
+              `执行上述命令保存密钥，成功/失败由插件直接回复用户。` +
+              '请直接结束本轮（可告知用户按卡片提示发送密钥），不要等待用户输入，' +
+              '也不要让用户把密钥内容发到对话里。',
+          });
+        },
+      };
     },
     { name: 'qqbot_secret_input' },
   );

package/src/tools/tool-session.ts

@@ -0,0 +1,74 @@
+/**
+ * 工具执行时的会话路由解析（双层回退）
+ *
+ * 背景（2026-09-23 事故）：qqbot_secret_input 等工具此前仅靠
+ * request-context（AsyncLocalStorage）获取当前会话目标。ALS 只在
+ * handleMessage → dispatchToOpenClaw 的异步子树内有效；openclaw 框架
+ * 经常把 agent turn 延迟到该子树之外执行——活动 turn 之后排队的
+ * followup/collect 批处理、框架自有定时器驱动的队列 drain 等。此时
+ * 工具执行处 ALS 为空，工具报「无法获取当前会话目标」直接失败。
+ *
+ * 修复：优先 ALS（逐消息精确，含 messageId/openId 供日志富化）；
+ * ALS 缺失时回退到框架在工具工厂上下文里提供的 deliveryContext
+ * （openclaw 按当前 run 的 sessionCtx 派生的可信投递路由：
+ * { channel, to, accountId }，qqbot 通道的 to 即规范目标地址
+ * qqbot:c2c:{openid} / qqbot:group:{group_openid}）。
+ *
+ * 工厂注册形式：api.registerTool((ctx) => ({ ...tool }), { name })。
+ * 框架在装配工具面（或缓存描述符路径下的每次执行）时调用工厂，
+ * ctx 携带当次 run 的 deliveryContext——描述符缓存键包含
+ * deliveryContext，不会跨会话复用旧路由。
+ */
+
+import { getRequestAccountId, getRequestTarget } from '../request-context.js';
+
+/** 框架 deliveryContext 中本项目用到的字段（见 openclaw OpenClawPluginToolContext） */
+export interface ToolDeliveryContext {
+  channel?: string;
+  to?: string;
+  accountId?: string;
+  threadId?: string;
+}
+
+/** 解析出的会话路由 */
+export interface ToolSessionRoute {
+  /** 规范目标地址：qqbot:c2c:{openid} / qqbot:group:{group_openid} */
+  target: string;
+  /** 账户 ID（多账户场景；可能为空，由调用方决定回退策略） */
+  accountId?: string;
+  /** 路由来源：request-context（ALS）优先，delivery-context（框架 run 级）回退 */
+  source: 'request-context' | 'delivery-context';
+}
+
+/**
+ * 解析当前工具调用所属的会话路由。
+ *
+ * 返回 undefined 表示当前 run 没有可识别的 QQ 会话来源
+ * （如 cron/定时任务、内部 UI 发起的 run）——调用方应返回明确错误。
+ */
+export function resolveToolSessionRoute(
+  delivery?: ToolDeliveryContext | null,
+): ToolSessionRoute | undefined {
+  // 第一层：请求级 ALS（入站消息处理链路内，逐消息精确）
+  const alsTarget = getRequestTarget();
+  if (alsTarget) {
+    return {
+      target: alsTarget,
+      accountId: getRequestAccountId(),
+      source: 'request-context',
+    };
+  }
+
+  // 第二层：框架 run 级 deliveryContext（延迟/排队 turn 的回退）
+  const to = typeof delivery?.to === 'string' ? delivery.to.trim() : '';
+  if (!to) return undefined;
+  const channel = typeof delivery?.channel === 'string' ? delivery.channel.trim() : '';
+  // 防御：deliveryContext 属于其他通道（理论上不会发生）时不误认
+  if (channel && channel !== 'qqbot') return undefined;
+  if (!/^qqbot:(c2c|group|channel):/i.test(to)) return undefined;
+  return {
+    target: to,
+    accountId: delivery?.accountId,
+    source: 'delivery-context',
+  };
+}

package/src/types.ts

@@ -211,8 +211,9 @@ export interface QQBotAccountConfig {
     sendMode?: 'stream' | 'static';
   };
   /**
-   * STT (语音转文字) 配置
-   * 配置后，收到语音消息时会自动调用 STT 服务转录为文字
+   * STT (语音转文字) 行为开关
+   * 转录凭证统一走框架 tools.media.audio.models；
+   * 框架未配置时直接使用 QQ 平台转写（asr_refer_text）
    */
   stt?: STTChannelConfig;
   /**
@@ -301,17 +302,30 @@ export interface AudioFormatPolicy {
 
 /**
  * STT (语音转文字) 配置
+ *
+ * 2026-10 起转录统一走框架音频理解管线（tools.media.audio.models 凭证），
+ * 本块只保留行为开关；旧凭证键已废弃（检测到会打迁移提示日志）。
+ * 框架 STT 未配置时，QQ 平台转写（asr_refer_text）直接作为唯一来源。
  */
 export interface STTChannelConfig {
-  /** 是否启用 STT（默认 true，配置了 baseUrl+apiKey 即自动启用） */
+  /**
+   * 是否启用框架 STT 转录（默认 true）。
+   * false = 不调用外部 STT，语音只用平台转写（或无转写时占位文本）。
+   */
   enabled?: boolean;
-  /** STT 服务提供商 ID（对应 models.providers 中的 key，默认 "openai"） */
+  /**
+   * 平台转写（asr_refer_text）参与开关。默认参与：
+   * 框架 STT 未配置时直接作为唯一来源，STT 失败/为空时兜底。
+   * 设为 false 恢复严格模式——所有场景丢弃平台转写。
+   */
+  asrFallback?: boolean;
+  /** @deprecated 2026-10 起忽略——STT 凭证统一配置在框架 tools.media.audio.models */
   provider?: string;
-  /** STT API 地址（如 https://api.openai.com/v1） */
+  /** @deprecated 同上 */
   baseUrl?: string;
-  /** STT API 密钥 */
+  /** @deprecated 同上 */
   apiKey?: string;
-  /** STT 模型名称（默认 "whisper-1"） */
+  /** @deprecated 同上 */
   model?: string;
 }
 

package/src/utils/stt.ts

@@ -1,114 +1,83 @@
 /**
- * STT (Speech-to-Text) 语音转文字服务
+ * STT (Speech-to-Text) 语音转文字 — 框架音频理解管线
  *
- * 支持 OpenAI 兼容的 /audio/transcriptions 接口。
- * 配置优先级：
- *   1. channels.qqbot.stt（插件级）
- *   2. 框架级 audio model 配置
+ * 转录统一委托给 openclaw/plugin-sdk/media-understanding-runtime 的
+ * `transcribeAudioFile`（provider 注册表、附件缓存、SSRF 策略与错误语义
+ * 均由框架维护），插件不再自带 OpenAI 兼容 HTTP 调用；STT 凭证只认
+ * 框架级 `tools.media.audio.models` 配置（与内置 telegram 通道一致）。
+ *
+ * 平台转写（asr_refer_text）：QQ 平台对语音消息自动 STT 并随事件 JSON 下发。
+ * 默认策略——框架 STT 未配置时**直接采用平台转写**；已配置时平台转写作为
+ * 自有转录失败/为空的兜底。`channels.qqbot.stt.asrFallback: false` 可整体
+ * 禁用平台转写（严格模式，恢复 2026-08-17 的丢弃行为）。
  */
-import * as fs from 'node:fs';
 import * as path from 'node:path';
+import { transcribeAudioFile } from 'openclaw/plugin-sdk/media-understanding-runtime';
 
-export interface STTConfig {
-  enabled: boolean;
-  baseUrl: string;
-  apiKey: string;
-  model: string;
-}
+type TranscribeParams = Parameters<typeof transcribeAudioFile>[0];
 
 /**
- * 平台转写（asr_refer_text）参与判定。
- * 仅当显式配置 channels.qqbot.stt.asrFallback: true 时保留平台转写；
- * 缺省、false 或 stt 块整体不存在时一律丢弃——包括 STT 未配置的场景
- * （此时语音消息落占位文本，而不是退回平台转写）。
- * 读取独立于 STT 凭证解析成败：stt 块无凭证但 asrFallback: true 仍生效。
+ * 平台转写（asr_refer_text）是否参与（独立于框架 STT 配置读取）。
+ * 默认 true；显式 `channels.qqbot.stt.asrFallback: false` 时关闭（严格模式）。
  */
 export function shouldUsePlatformAsr(cfg: Record<string, unknown>): boolean {
   const channels = asRecord(cfg.channels);
   const qqbot = asRecord(channels?.qqbot);
-  return asRecord(qqbot?.stt)?.asrFallback === true;
+  return asRecord(qqbot?.stt)?.asrFallback !== false;
 }
 
 /**
- * 从 OpenClaw 配置中解析 STT 设置
+ * 框架 STT（tools.media.audio）是否可用：
+ * - `channels.qqbot.stt.enabled === false` → 插件级显式关闭（只用平台转写）
+ * - `tools.media.audio.enabled === false` → 框架级关闭
+ * - `models` 为空 → 未配置
+ *
+ * 仅做存在性探测控制流程；provider 解析与实际调用由 transcribeAudioFile 完成。
  */
-export function resolveSTTConfig(cfg: Record<string, unknown>): STTConfig | null {
+export function isFrameworkSttConfigured(cfg: Record<string, unknown>): boolean {
   const channels = asRecord(cfg.channels);
   const qqbot = asRecord(channels?.qqbot);
-  const sttCfg = asRecord(qqbot?.stt);
-
-  // 显式禁用
-  if (sttCfg?.enabled === false) {
-    return null;
-  }
-
-  const models = asRecord(cfg.models);
-  const providers = asRecord(models?.providers);
-
-  // 1. 插件级 STT 配置
-  if (sttCfg) {
-    const providerId = readString(sttCfg, 'provider') ?? 'openai';
-    const providerCfg = asRecord(providers?.[providerId]);
-    const baseUrl = readString(sttCfg, 'baseUrl') ?? readString(providerCfg, 'baseUrl');
-    const apiKey = readString(sttCfg, 'apiKey') ?? readString(providerCfg, 'apiKey');
-    const model = readString(sttCfg, 'model') ?? 'whisper-1';
-    if (baseUrl && apiKey) {
-      return { enabled: true, baseUrl: baseUrl.replace(/\/+$/, ''), apiKey, model };
-    }
+  if (asRecord(qqbot?.stt)?.enabled === false) {
+    return false;
   }
-
-  // 2. 框架级 audio model fallback
   const tools = asRecord(cfg.tools);
   const media = asRecord(tools?.media);
   const audio = asRecord(media?.audio);
-  const audioModels = audio?.models;
-  const audioModelEntry = Array.isArray(audioModels) ? asRecord(audioModels[0]) : undefined;
-  if (audioModelEntry) {
-    const providerId = readString(audioModelEntry, 'provider') ?? 'openai';
-    const providerCfg = asRecord(providers?.[providerId]);
-    const baseUrl = readString(audioModelEntry, 'baseUrl') ?? readString(providerCfg, 'baseUrl');
-    const apiKey = readString(audioModelEntry, 'apiKey') ?? readString(providerCfg, 'apiKey');
-    const model = readString(audioModelEntry, 'model') ?? 'whisper-1';
-    if (baseUrl && apiKey) {
-      return { enabled: true, baseUrl: baseUrl.replace(/\/+$/, ''), apiKey, model };
-    }
+  if (!audio || audio.enabled === false) {
+    return false;
   }
+  return Array.isArray(audio.models) && audio.models.length > 0;
+}
 
-  return null;
+/**
+ * 检测已废弃的插件级 STT 凭证（channels.qqbot.stt.provider/baseUrl/apiKey/model）。
+ * 2026-10 起凭证统一走框架 `tools.media.audio.models`，旧键被忽略；
+ * 返回 true 时调用方打一次性迁移提示。
+ */
+export function hasLegacySttCredentials(cfg: Record<string, unknown>): boolean {
+  const channels = asRecord(cfg.channels);
+  const qqbot = asRecord(channels?.qqbot);
+  const stt = asRecord(qqbot?.stt);
+  if (!stt) return false;
+  return ['provider', 'baseUrl', 'apiKey', 'model'].some(
+    (key) => typeof stt[key] === 'string' && (stt[key] as string).trim().length > 0,
+  );
 }
 
 /**
- * 调用 STT 服务转录音频文件
+ * 经框架音频理解管线转录本地音频文件。
+ * 返回修剪后的转录文本；无文本返回 null。
+ * provider 缺失/调用失败会抛错，由调用方捕获后走平台转写兜底。
  */
-export async function transcribeAudio(
+export async function transcribeAudioViaFramework(
   audioPath: string,
   cfg: Record<string, unknown>,
 ): Promise<string | null> {
-  const sttCfg = resolveSTTConfig(cfg);
-  if (!sttCfg) {
-    return null;
-  }
-
-  const fileBuffer = fs.readFileSync(audioPath);
-  const fileName = sanitizeFileName(path.basename(audioPath));
-  const mime = guessMimeType(fileName);
-
-  const form = new FormData();
-  form.append('file', new Blob([fileBuffer], { type: mime }), fileName);
-  form.append('model', sttCfg.model);
-
-  const resp = await fetch(`${sttCfg.baseUrl}/audio/transcriptions`, {
-    method: 'POST',
-    headers: { Authorization: `Bearer ${sttCfg.apiKey}` },
-    body: form,
+  const result = await transcribeAudioFile({
+    filePath: audioPath,
+    cfg: cfg as unknown as TranscribeParams['cfg'],
+    mime: guessMimeType(audioPath),
   });
-
-  if (!resp.ok) {
-    const detail = await resp.text().catch(() => '');
-    throw new Error(`STT failed (HTTP ${resp.status}): ${detail.slice(0, 300)}`);
-  }
-
-  const result = (await resp.json()) as { text?: string };
   return result.text?.trim() || null;
 }
 
@@ -121,18 +90,6 @@ function asRecord(value: unknown): Record<string, unknown> | undefined {
   return undefined;
 }
 
-function readString(obj: Record<string, unknown> | undefined, key: string): string | undefined {
-  const val = obj?.[key];
-  if (typeof val === 'string' && val.trim()) {
-    return val.trim();
-  }
-  return undefined;
-}
-
-function sanitizeFileName(name: string): string {
-  return name.replace(/[^a-zA-Z0-9._-]/g, '_');
-}
-
 function guessMimeType(fileName: string): string {
   const ext = path.extname(fileName).toLowerCase();
   const mimeMap: Record<string, string> = {