@cxyhhhhh/qqbot-cli 0.1.0-dev.202606011703

package/dist/chunk-XIJ6OSLY.js

@@ -0,0 +1,3654 @@
+// src/config/loader.ts
+import * as fs from "fs";
+import * as path from "path";
+import { parse as parseYaml } from "yaml";
+
+// src/config/schema.ts
+import { z } from "zod";
+var coerceString = z.preprocess(
+  (val) => val === void 0 || val === null ? val : String(val),
+  z.string()
+);
+var qqSchema = z.object({
+  appId: coerceString.pipe(z.string().min(1, "qq.appId \u5FC5\u586B")),
+  appSecret: coerceString.pipe(z.string().min(1, "qq.appSecret \u5FC5\u586B")),
+  markdown: z.boolean().default(false),
+  /** 自定义 User-Agent（默认 qqbot-cli/<version>） */
+  userAgent: z.string().optional(),
+  /** QQ Open Platform API 基址（默认 https://api.sgroup.qq.com） */
+  baseUrl: z.string().optional(),
+  /** Token 接口基址（默认 https://bots.qq.com） */
+  tokenBaseUrl: z.string().optional(),
+  /**
+   * 启动时 Token 获取策略。
+   * - "sync" (默认): 阻塞等待 token 获取成功后再接受流量，凭证错误立即暴露。
+   * - "async": 后台异步获取 token，服务更快启动，但首次请求可能失败。
+   */
+  tokenPrefetch: z.enum(["sync", "async"]).default("sync"),
+  /**
+   * 事件传输模式。
+   * - "websocket" (默认): WS 长连（心跳/重连/RESUME）
+   * - "webhook": QQ 平台 POST 回调到你的 HTTPS 端点
+   */
+  transport: z.enum(["websocket", "webhook"]).default("websocket"),
+  /** Webhook 模式配置（仅 transport=webhook 时生效） */
+  webhook: z.object({
+    /** 监听端口，默认 8080 */
+    port: z.number().default(8080),
+    /** 监听路径，默认 "/" */
+    path: z.string().default("/callback")
+  }).default({})
+});
+var cloudagentSchema = z.object({
+  apiKey: z.string().optional(),
+  endpoint: z.string().default("https://www.codebuddy.cn/v2"),
+  sandbox: z.object({
+    /** auto: 自动创建 Runtime | manual: 指定 runtimeId | direct: 直连 ACP 端点 */
+    mode: z.enum(["auto", "manual", "direct"]).default("auto"),
+    runtimeName: z.string().optional(),
+    runtimeId: z.string().optional(),
+    /** direct 模式：ACP 端点 URL（如 http://localhost:65225/acp） */
+    acpEndpoint: z.string().optional(),
+    /** direct 模式：ACP 认证 token */
+    acpToken: z.string().optional()
+  }).default({}),
+  manifest: z.object({
+    systemPrompt: z.string().optional(),
+    systemPromptFile: z.string().optional()
+  }).default({}),
+  acp: z.object({
+    lazyConnect: z.boolean().default(true),
+    maxRetries: z.number().default(20),
+    retryIntervalMs: z.number().default(3e3),
+    /** 等待下一个 ACP 事件的超时时间（ms），工具调用可能耗时较长。默认 180s */
+    eventTimeoutMs: z.number().default(18e4)
+  }).default({}),
+  /** 多用户 Session 连接池配置 */
+  session: z.object({
+    /** 最大并发连接数。默认 20 */
+    maxConnections: z.number().default(20),
+    /** 是否启用空闲清理。默认 false */
+    enableCleanup: z.boolean().default(false),
+    /** 连接空闲超时（ms）。默认 30min */
+    idleTimeoutMs: z.number().default(18e5),
+    /** 清理扫描间隔（ms）。默认 60s */
+    cleanupIntervalMs: z.number().default(6e4),
+    /** 淘汰时保留服务端 session（下次自动恢复上下文）。默认 true */
+    preserveOnEvict: z.boolean().default(true)
+  }).default({}),
+  /** 额外的 MCP Server，和内置的一起传给 ACP session */
+  mcpServers: z.array(z.object({
+    type: z.enum(["http", "sse"]).default("http"),
+    name: z.string(),
+    url: z.string(),
+    headers: z.record(z.string()).default({})
+  })).default([])
+});
+var openaiSchema = z.object({
+  apiKey: z.string().min(1, "backend.openai.apiKey \u5FC5\u586B"),
+  baseUrl: z.string().default("https://api.openai.com/v1"),
+  model: z.string().default("gpt-4o"),
+  systemPrompt: z.string().default("\u4F60\u662F\u4E00\u4E2A QQ \u673A\u5668\u4EBA\u52A9\u624B\u3002"),
+  maxTokens: z.number().default(2048),
+  temperature: z.number().default(0.7)
+});
+var backendSchema = z.object({
+  type: z.enum(["echo", "openai", "cloudagent"]).default("echo"),
+  cloudagent: cloudagentSchema.optional(),
+  openai: openaiSchema.optional()
+});
+var middlewareSchema = z.object({
+  messageFilter: z.object({
+    skipSelfEcho: z.boolean().default(true),
+    dedup: z.object({ windowMs: z.number().default(5e3) }).default({})
+  }).default({}),
+  contentSanitizer: z.object({
+    stripBotMention: z.boolean().default(true),
+    collapseWhitespace: z.boolean().default(true)
+  }).default({}),
+  mentionGate: z.object({
+    requireMentionInGroup: z.boolean().default(true),
+    alwaysAnswerC2C: z.boolean().default(true)
+  }).default({}),
+  rateLimiter: z.object({
+    enabled: z.boolean().default(false),
+    perSender: z.object({ max: z.number().default(5), windowMs: z.number().default(1e4) }).default({}),
+    global: z.object({ max: z.number().default(50), windowMs: z.number().default(6e4) }).default({})
+  }).default({}),
+  typingIndicator: z.object({
+    enabled: z.boolean().default(true),
+    /** typing 指示器持续时间（秒）。默认 15 */
+    durationSec: z.number().default(15),
+    /** keepAlive 重发间隔（ms）。默认根据 durationSec 自动计算 */
+    keepAliveIntervalMs: z.number().optional()
+  }).default({}).transform((raw) => ({
+    ...raw,
+    // 自动计算：比 durationSec 提前 5s 重发，确保 typing 状态不中断
+    keepAliveIntervalMs: raw.keepAliveIntervalMs ?? Math.max((raw.durationSec - 5) * 1e3, 5e3)
+  })),
+  slashCommands: z.object({
+    enabled: z.boolean().default(true),
+    prefixes: z.array(z.string()).default(["/", "!"]),
+    /** 指令白名单（用户 OpenID 列表）。为空则所有人可用。 */
+    allowFrom: z.array(z.string().nullable()).default([]).transform(
+      (arr) => arr.filter((v) => v != null && v !== "")
+    )
+  }).default({}),
+  concurrency: z.object({
+    /** Strategy: queue | drop | abort | merge. Default: merge. */
+    strategy: z.enum(["queue", "drop", "abort", "merge"]).default("merge"),
+    /** Max queued messages per target. Default: 50. */
+    maxQueue: z.number().default(50)
+  }).default({})
+}).default({});
+var displaySchema = z.object({
+  /** Preset: full | compact | minimal | text-only */
+  preset: z.enum(["full", "compact", "minimal", "text-only"]).default("minimal"),
+  /** Show tool calls */
+  tool: z.boolean().optional(),
+  /** Show agent thought chunks */
+  thought: z.boolean().optional(),
+  /** Show execution plan */
+  plan: z.boolean().optional(),
+  /** Show emoji before tool name */
+  toolEmoji: z.boolean().optional(),
+  /** Show tool kind label (Search/Fetch/...) */
+  toolKind: z.boolean().optional(),
+  /** Show tool title (URL, query, command, ...) */
+  toolTitle: z.boolean().optional(),
+  /** Max display length for tool detail when truncation is enabled. Default: 120 */
+  toolDetailMaxLength: z.number().optional(),
+  /** Tool kinds whose detail should be truncated. Default: [] (no truncation) */
+  toolDetailTruncate: z.array(z.string()).optional()
+}).default({}).transform((raw) => {
+  const base = DISPLAY_PRESET_DEFAULTS[raw.preset] ?? DISPLAY_PRESET_DEFAULTS["compact"];
+  return {
+    preset: raw.preset,
+    tool: raw.tool ?? base.tool,
+    thought: raw.thought ?? base.thought,
+    plan: raw.plan ?? base.plan,
+    toolEmoji: raw.toolEmoji ?? base.toolEmoji,
+    toolKind: raw.toolKind ?? base.toolKind,
+    toolTitle: raw.toolTitle ?? base.toolTitle,
+    toolDetailMaxLength: raw.toolDetailMaxLength,
+    toolDetailTruncate: raw.toolDetailTruncate
+  };
+});
+var DISPLAY_PRESET_DEFAULTS = {
+  "full": { tool: true, thought: true, plan: true, toolEmoji: true, toolKind: true, toolTitle: true },
+  "compact": { tool: true, thought: false, plan: true, toolEmoji: true, toolKind: true, toolTitle: true },
+  "minimal": { tool: true, thought: false, plan: false, toolEmoji: true, toolKind: true, toolTitle: false },
+  "text-only": { tool: false, thought: false, plan: false, toolEmoji: false, toolKind: false, toolTitle: false }
+};
+function expandDisplayPreset(preset) {
+  const base = DISPLAY_PRESET_DEFAULTS[preset] ?? DISPLAY_PRESET_DEFAULTS["compact"];
+  return { preset, ...base, toolDetailMaxLength: void 0, toolDetailTruncate: void 0 };
+}
+var streamingSchema = z.object({
+  c2c: z.boolean().default(true),
+  throttleMs: z.number().default(500)
+}).default({});
+var messageSchema = z.object({
+  /** 展示样式配置 */
+  display: displaySchema,
+  /** 异常兜底文案配置 */
+  errorMessages: z.object({
+    /**
+     * 错误匹配规则，按顺序匹配。
+     * 每条 rule: match 为关键词数组（任一命中即匹配，大小写不敏感），reply 为回复文案。
+     * 可选 hint: 追加在 reply 后的排查指引（覆盖全局 troubleshootHint）。
+     */
+    rules: z.array(z.object({
+      match: z.array(z.string()),
+      reply: z.string(),
+      hint: z.string().optional()
+    })).default([]),
+    /** Agent 未生成回复 */
+    emptyReply: z.string().default("\u26A0\uFE0F Agent \u672A\u751F\u6210\u56DE\u590D\u5185\u5BB9\uFF0C\u8BF7\u6362\u4E2A\u65B9\u5F0F\u63CF\u8FF0\u6216\u91CD\u8BD5\u3002"),
+    /** 所有规则都未命中时的兜底 */
+    unknown: z.string().default("\u26A0\uFE0F \u5904\u7406\u5931\u8D25\uFF0C\u8BF7\u7A0D\u540E\u91CD\u8BD5\u3002"),
+    /** 全局排查指引，追加在所有错误消息后面（rule 级别 hint 优先） */
+    troubleshootHint: z.string().optional(),
+    /** 调试模式：错误消息中追加原始 errMsg。默认 false */
+    debug: z.boolean().default(false)
+  }).default({})
+}).default({});
+var sessionSchema = z.object({
+  isolation: z.enum(["per-qualifier", "global"]).default("per-qualifier"),
+  persistence: z.object({
+    type: z.enum(["file", "memory"]).default("file"),
+    dir: z.string().default("./.qqbot-data")
+  }).default({})
+}).default({});
+var logSchema = z.object({
+  level: z.enum(["debug", "info", "warn", "error"]).default("info"),
+  /** 控制台输出格式：pretty（人类可读）| json（结构化）。默认 pretty */
+  console: z.enum(["json", "pretty"]).default("pretty"),
+  /** 文件日志（滚动） */
+  file: z.object({
+    enabled: z.boolean().default(false),
+    dir: z.string().default("./logs"),
+    /** 单文件最大大小，支持 "10m" "1g" 等 */
+    maxSize: z.string().default("10m"),
+    /** 保留文件数 */
+    maxFiles: z.number().default(7),
+    /** 按时间滚动：daily | hourly | weekly */
+    frequency: z.enum(["daily", "hourly", "weekly"]).optional(),
+    /** 文件名日期格式（需配合 frequency），如 "yyyy-MM-dd" */
+    dateFormat: z.string().optional(),
+    /** 创建 current.log 符号链接指向当前活跃文件 */
+    symlink: z.boolean().default(false)
+  }).default({})
+}).default({});
+var mcpSchema = z.object({
+  enabled: z.boolean().default(false),
+  /** MCP Server 监听地址，默认 127.0.0.1；Docker 容器内需设为 0.0.0.0 */
+  host: z.string().default("127.0.0.1"),
+  /** MCP Server 监听端口，0 为随机分配 */
+  port: z.number().int().min(0).default(0),
+  /** 文件路径前缀，拼接在工具接收到的 file_path 之前，用于容器卷映射 */
+  pathPrefix: z.string().default("")
+}).default({ enabled: false, host: "127.0.0.1", port: 0, pathPrefix: "" });
+var openApiParamSchema = z.object({
+  name: z.string(),
+  type: z.enum(["string", "number", "boolean", "string[]", "number[]"]).default("string"),
+  desc: z.string(),
+  required: z.boolean().default(false),
+  default: z.unknown().optional()
+});
+var openApiItemSchema = z.object({
+  name: z.string(),
+  desc: z.string(),
+  method: z.enum(["GET", "POST", "PUT", "DELETE", "PATCH"]).default("POST"),
+  path: z.string(),
+  fixed_body: z.record(z.unknown()).optional(),
+  params: z.array(openApiParamSchema).default([]),
+  param_mapping: z.record(z.string()).optional()
+});
+var openApiSchema = z.object({
+  /** 全局超时（ms），默认 10000 */
+  timeoutMs: z.number().default(1e4),
+  /** 接口声明列表 */
+  apis: z.array(openApiItemSchema).default([])
+}).optional();
+var telemetrySchema = z.object({
+  enabled: z.boolean().default(false),
+  /** 开启 OTEL 内部诊断日志和控制台指标输出 */
+  debug: z.boolean().default(false),
+  serviceName: z.string().default("qqbot-cli"),
+  endpoint: z.string().default("http://localhost:4318"),
+  protocol: z.enum(["http", "grpc"]).default("http"),
+  sampleRate: z.number().min(0).max(1).default(1),
+  exportIntervalMs: z.number().default(3e4),
+  attributes: z.record(z.string()).default({}),
+  /** 平台扩展配置 */
+  galileo: z.object({
+    platform: z.string(),
+    app: z.string(),
+    server: z.string(),
+    namespace: z.string().default("Production"),
+    envName: z.string().default("formal")
+  }).optional()
+}).default({});
+var botConfigSchema = z.object({
+  qq: qqSchema,
+  backend: backendSchema,
+  middleware: middlewareSchema,
+  streaming: streamingSchema,
+  message: messageSchema,
+  session: sessionSchema,
+  log: logSchema,
+  mcp: mcpSchema,
+  openapi: openApiSchema,
+  telemetry: telemetrySchema
+});
+
+// src/config/loader.ts
+function interpolateEnv(text) {
+  return text.replace(/\$\{([^}]+)\}/g, (_, expr) => {
+    const match = expr.match(/^([^:}-]+)(?::-([\s\S]*))?$/);
+    if (!match) return "";
+    const varName = match[1].trim();
+    const defaultVal = match[2] ?? "";
+    const val = process.env[varName];
+    if (val === void 0 || val === "") {
+      return defaultVal;
+    }
+    return val;
+  });
+}
+async function loadConfig(configPath) {
+  const resolved = path.resolve(configPath);
+  if (!fs.existsSync(resolved)) {
+    throw new Error(`\u914D\u7F6E\u6587\u4EF6\u4E0D\u5B58\u5728: ${resolved}
+\u63D0\u793A: \u8FD0\u884C qqbot-cli init \u751F\u6210\u6A21\u677F\u914D\u7F6E`);
+  }
+  const raw = fs.readFileSync(resolved, "utf-8");
+  const interpolated = interpolateEnv(raw);
+  let data;
+  const ext = path.extname(resolved).toLowerCase();
+  if (ext === ".yaml" || ext === ".yml") {
+    data = parseYaml(interpolated);
+  } else if (ext === ".json" || ext === ".jsonc") {
+    data = JSON.parse(interpolated);
+  } else {
+    try {
+      data = parseYaml(interpolated);
+    } catch {
+      data = JSON.parse(interpolated);
+    }
+  }
+  const result = botConfigSchema.safeParse(data);
+  if (!result.success) {
+    const issues = result.error.issues.map((i) => `  - ${i.path.join(".")}: ${i.message}`).join("\n");
+    throw new Error(`\u914D\u7F6E\u6821\u9A8C\u5931\u8D25:
+${issues}`);
+  }
+  const config = result.data;
+  if (config.backend.type === "cloudagent" && !config.backend.cloudagent) {
+    throw new Error("backend.type=cloudagent \u65F6\uFF0Cbackend.cloudagent \u914D\u7F6E\u5757\u5FC5\u586B");
+  }
+  if (config.backend.type === "openai" && !config.backend.openai) {
+    throw new Error("backend.type=openai \u65F6\uFF0Cbackend.openai \u914D\u7F6E\u5757\u5FC5\u586B");
+  }
+  return config;
+}
+
+// src/config/watcher.ts
+import * as fs2 from "fs";
+import { parseDocument } from "yaml";
+var ConfigWatcher = class {
+  watcher = null;
+  debounceTimer = null;
+  currentConfig;
+  opts;
+  paused = false;
+  constructor(opts) {
+    this.opts = opts;
+    this.currentConfig = opts.currentConfig;
+  }
+  start() {
+    const { configPath, logger } = this.opts;
+    const debounceMs = this.opts.debounceMs ?? 500;
+    try {
+      this.watcher = fs2.watch(configPath, () => {
+        if (this.paused) return;
+        if (this.debounceTimer) clearTimeout(this.debounceTimer);
+        this.debounceTimer = setTimeout(() => this.reload(), debounceMs);
+      });
+      logger.info(`[config] watching ${configPath} for changes`);
+    } catch (err) {
+      logger.warn?.(
+        `[config] failed to watch ${configPath}: ${err instanceof Error ? err.message : String(err)}`
+      );
+    }
+  }
+  stop() {
+    if (this.debounceTimer) {
+      clearTimeout(this.debounceTimer);
+      this.debounceTimer = null;
+    }
+    if (this.watcher) {
+      this.watcher.close();
+      this.watcher = null;
+    }
+  }
+  /**
+   * 将指定的键值对写回 YAML 配置文件。
+   *
+   * 使用 yaml `parseDocument` 保留原始注释和格式，
+   * 仅修改目标字段，然后重新序列化写入。
+   *
+   * 写入期间自动暂停文件监听，避免触发循环重载。
+   *
+   * @param patches - 要写入的路径-值映射，路径用点号分隔（如 "message.display.preset"）
+   * @param currentConfig - 当前内存中的最新配置，同步到 watcher 防止 reload 回退
+   */
+  writeBack(patches, currentConfig) {
+    const { configPath, logger } = this.opts;
+    try {
+      const raw = fs2.readFileSync(configPath, "utf-8");
+      const doc = parseDocument(raw);
+      for (const [dotPath, value] of Object.entries(patches)) {
+        const keys = dotPath.split(".");
+        doc.setIn(keys, value);
+      }
+      this.paused = true;
+      fs2.writeFileSync(configPath, doc.toString(), "utf-8");
+      logger.info(`[config] wrote back: ${Object.keys(patches).join(", ")}`);
+      if (currentConfig) {
+        this.currentConfig = currentConfig;
+      }
+      setTimeout(() => {
+        this.paused = false;
+      }, 1500);
+    } catch (err) {
+      this.paused = false;
+      logger.error(
+        `[config] writeBack failed: ${err instanceof Error ? err.message : String(err)}`
+      );
+    }
+  }
+  async reload() {
+    const { configPath, logger, onChange } = this.opts;
+    try {
+      const newConfig = await loadConfig(configPath);
+      const oldConfig = this.currentConfig;
+      this.currentConfig = newConfig;
+      logger.info("[config] reloaded successfully");
+      onChange(newConfig, oldConfig);
+    } catch (err) {
+      logger.error(
+        `[config] reload failed, keeping old config: ${err instanceof Error ? err.message : String(err)}`
+      );
+    }
+  }
+};
+
+// src/runner.ts
+import { createRequire } from "module";
+import {
+  QQBot,
+  messageFilter,
+  contentSanitizer,
+  mentionGate,
+  rateLimiter,
+  concurrencyGuard,
+  quoteRef,
+  typingIndicator,
+  envelopeFormatter,
+  errorHandler
+} from "@tencent/qqbot-nodejs";
+
+// src/backend/echo.ts
+var EchoBackend = class {
+  name = "echo";
+  async init() {
+  }
+  async getOrCreateSession(qualifier) {
+    return `echo-${qualifier}`;
+  }
+  async *chat(params) {
+    const reply = params.text ? `Echo: ${params.text}` : "(\u7A7A\u6D88\u606F)";
+    let buffer = "";
+    for (const char of reply) {
+      buffer += char;
+      yield { type: "text", content: char };
+      await sleep(50);
+    }
+    yield { type: "done", content: "", stopReason: "end" };
+  }
+  async shutdown() {
+  }
+};
+function sleep(ms) {
+  return new Promise((r) => setTimeout(r, ms));
+}
+
+// src/telemetry/metrics.ts
+import { metrics, ValueType } from "@opentelemetry/api";
+
+// src/telemetry/constants.ts
+var GALILEO_RESOURCE = {
+  TARGET: "target",
+  SERVICE_NAME: "service_name",
+  NAMESPACE: "namespace",
+  ENV_NAME: "env_name",
+  INSTANCE: "instance",
+  CONTAINER_NAME: "container_name",
+  VERSION: "version",
+  CON_SETID: "con_setid",
+  APP_ID: "app_id",
+  SDK_LANGUAGE: "telemetry.sdk.language",
+  SDK_NAME: "telemetry.sdk.name"
+};
+var GALILEO_METRICS = {
+  /** 被调处理耗时 */
+  SERVER_HANDLED_SECONDS: "rpc_server_handled_seconds",
+  /** 被调请求计数 */
+  SERVER_STARTED_TOTAL: "rpc_server_started_total",
+  /** 被调完成计数 */
+  SERVER_HANDLED_TOTAL: "rpc_server_handled_total",
+  /** 主调耗时 */
+  CLIENT_HANDLED_SECONDS: "rpc_client_handled_seconds",
+  /** 主调请求计数 */
+  CLIENT_STARTED_TOTAL: "rpc_client_started_total",
+  /** 主调完成计数 */
+  CLIENT_HANDLED_TOTAL: "rpc_client_handled_total"
+};
+var METRIC_ATTRS = {
+  CALLER_SERVICE: "caller_service",
+  CALLER_METHOD: "caller_method",
+  CALLER_CON_SETID: "caller_con_setid",
+  CALLEE_SERVICE: "callee_service",
+  CALLEE_METHOD: "callee_method",
+  CALLEE_CON_SETID: "callee_con_setid",
+  CALLEE_IP: "callee_ip",
+  CALLEE_CONTAINER: "callee_container",
+  CALLER_SERVER: "caller_server",
+  CALLEE_SERVER: "callee_server",
+  CODE: "code",
+  CODE_TYPE: "code_type",
+  CALLER_GROUP: "caller_group",
+  USER_EXT1: "user_ext1",
+  USER_EXT2: "user_ext2",
+  USER_EXT3: "user_ext3"
+};
+
+// src/telemetry/metrics.ts
+var bizDefaultAttrs = {};
+function setBizDefaultAttrs(attrs) {
+  bizDefaultAttrs = attrs;
+}
+function fillBizAttrs(attrs) {
+  return { ...bizDefaultAttrs, ...attrs };
+}
+function getServerMeter() {
+  return metrics.getMeter("server_metrics");
+}
+function getClientMeter() {
+  return metrics.getMeter("client_metrics");
+}
+function getBizMeter() {
+  return metrics.getMeter("qqbot_biz");
+}
+function fillClientAttrs(attrs) {
+  return {
+    [METRIC_ATTRS.CALLER_SERVICE]: "",
+    [METRIC_ATTRS.CALLER_METHOD]: "",
+    [METRIC_ATTRS.CALLER_CON_SETID]: "",
+    [METRIC_ATTRS.CALLEE_SERVICE]: "",
+    [METRIC_ATTRS.CALLEE_METHOD]: "",
+    [METRIC_ATTRS.CALLEE_CON_SETID]: "",
+    [METRIC_ATTRS.CALLEE_IP]: "",
+    [METRIC_ATTRS.CALLEE_CONTAINER]: "",
+    [METRIC_ATTRS.CODE]: 0,
+    [METRIC_ATTRS.CODE_TYPE]: "",
+    [METRIC_ATTRS.CALLER_GROUP]: "",
+    [METRIC_ATTRS.USER_EXT1]: "",
+    [METRIC_ATTRS.USER_EXT2]: "",
+    [METRIC_ATTRS.USER_EXT3]: "",
+    [METRIC_ATTRS.CALLER_SERVER]: "",
+    [METRIC_ATTRS.CALLEE_SERVER]: "",
+    ...attrs
+  };
+}
+function fillServerAttrs(attrs) {
+  return {
+    [METRIC_ATTRS.CALLER_SERVICE]: "",
+    [METRIC_ATTRS.CALLER_METHOD]: "",
+    [METRIC_ATTRS.CALLER_CON_SETID]: "",
+    caller_ip: "",
+    caller_container: "",
+    [METRIC_ATTRS.CALLEE_SERVICE]: "",
+    [METRIC_ATTRS.CALLEE_METHOD]: "",
+    [METRIC_ATTRS.CALLEE_CON_SETID]: "",
+    [METRIC_ATTRS.CODE]: 0,
+    [METRIC_ATTRS.CODE_TYPE]: "",
+    [METRIC_ATTRS.CALLER_GROUP]: "",
+    [METRIC_ATTRS.USER_EXT1]: "",
+    [METRIC_ATTRS.USER_EXT2]: "",
+    [METRIC_ATTRS.USER_EXT3]: "",
+    [METRIC_ATTRS.CALLER_SERVER]: "",
+    [METRIC_ATTRS.CALLEE_SERVER]: "",
+    ...attrs
+  };
+}
+var serverHandledSeconds = {
+  record(value, attrs) {
+    getServerMeter().createHistogram(GALILEO_METRICS.SERVER_HANDLED_SECONDS, {
+      unit: "s",
+      valueType: ValueType.DOUBLE
+    }).record(value, fillServerAttrs(attrs ?? {}));
+  }
+};
+var serverStartedTotal = {
+  add(value, attrs) {
+    getServerMeter().createCounter(GALILEO_METRICS.SERVER_STARTED_TOTAL, {
+      valueType: ValueType.INT
+    }).add(value, fillServerAttrs(attrs ?? {}));
+  }
+};
+var serverHandledTotal = {
+  add(value, attrs) {
+    getServerMeter().createCounter(GALILEO_METRICS.SERVER_HANDLED_TOTAL, {
+      valueType: ValueType.INT
+    }).add(value, fillServerAttrs(attrs ?? {}));
+  }
+};
+var clientHandledSeconds = {
+  record(value, attrs) {
+    getClientMeter().createHistogram(GALILEO_METRICS.CLIENT_HANDLED_SECONDS, {
+      unit: "s",
+      valueType: ValueType.DOUBLE
+    }).record(value, fillClientAttrs(attrs ?? {}));
+  }
+};
+var clientStartedTotal = {
+  add(value, attrs) {
+    getClientMeter().createCounter(GALILEO_METRICS.CLIENT_STARTED_TOTAL, {
+      valueType: ValueType.INT
+    }).add(value, fillClientAttrs(attrs ?? {}));
+  }
+};
+var clientHandledTotal = {
+  add(value, attrs) {
+    getClientMeter().createCounter(GALILEO_METRICS.CLIENT_HANDLED_TOTAL, {
+      valueType: ValueType.INT
+    }).add(value, fillClientAttrs(attrs ?? {}));
+  }
+};
+var mergeTotal = {
+  add(value, attrs) {
+    getBizMeter().createCounter("qqbot.concurrency.merged").add(value, fillBizAttrs(attrs));
+  }
+};
+var mergeEventsTotal = {
+  add(value, attrs) {
+    getBizMeter().createCounter("qqbot.concurrency.merge_events").add(value, fillBizAttrs(attrs));
+  }
+};
+var dropTotal = {
+  add(value, attrs) {
+    getBizMeter().createCounter("qqbot.concurrency.dropped").add(value, fillBizAttrs(attrs));
+  }
+};
+var toolCallsTotal = {
+  add(value, attrs) {
+    getBizMeter().createCounter("qqbot.acp.tool_calls.total").add(value, fillBizAttrs(attrs));
+  }
+};
+var acpTtfbSeconds = {
+  record(value, attrs) {
+    getBizMeter().createHistogram("qqbot.acp.ttfb_seconds", {
+      unit: "s",
+      valueType: ValueType.DOUBLE
+    }).record(value, fillBizAttrs(attrs));
+  }
+};
+var acpConnectSeconds = {
+  record(value, attrs) {
+    getBizMeter().createHistogram("qqbot.acp.connect_seconds", {
+      unit: "s",
+      valueType: ValueType.DOUBLE
+    }).record(value, fillBizAttrs(attrs));
+  }
+};
+var acpConnectRetries = {
+  add(value, attrs) {
+    getBizMeter().createCounter("qqbot.acp.connect_retries").add(value, fillBizAttrs(attrs));
+  }
+};
+var chatRetryTotal = {
+  add(value, attrs) {
+    getBizMeter().createCounter("qqbot.acp.chat_retry_total").add(value, fillBizAttrs(attrs));
+  }
+};
+var poolSize = {
+  record(value) {
+    getBizMeter().createHistogram("qqbot.pool.size", {
+      valueType: ValueType.INT
+    }).record(value, fillBizAttrs());
+  }
+};
+var poolEvictTotal = {
+  add(value, attrs) {
+    getBizMeter().createCounter("qqbot.pool.evict_total").add(value, fillBizAttrs(attrs));
+  }
+};
+var poolRestoreTotal = {
+  add(value, attrs) {
+    getBizMeter().createCounter("qqbot.pool.restore_total").add(value, fillBizAttrs(attrs));
+  }
+};
+var poolCreateSeconds = {
+  record(value, attrs) {
+    getBizMeter().createHistogram("qqbot.pool.create_seconds", {
+      unit: "s",
+      valueType: ValueType.DOUBLE
+    }).record(value, fillBizAttrs(attrs));
+  }
+};
+var sandboxStartSeconds = {
+  record(value, attrs) {
+    getBizMeter().createHistogram("qqbot.sandbox.start_seconds", {
+      unit: "s",
+      valueType: ValueType.DOUBLE
+    }).record(value, fillBizAttrs(attrs));
+  }
+};
+var sessionCreateSeconds = {
+  record(value, attrs) {
+    getBizMeter().createHistogram("qqbot.session.create_seconds", {
+      unit: "s",
+      valueType: ValueType.DOUBLE
+    }).record(value, fillBizAttrs(attrs));
+  }
+};
+var replyEmptyTotal = {
+  add(value, attrs) {
+    getBizMeter().createCounter("qqbot.reply.empty_total").add(value, fillBizAttrs(attrs));
+  }
+};
+var replyFallbackTotal = {
+  add(value, attrs) {
+    getBizMeter().createCounter("qqbot.reply.fallback_total").add(value, fillBizAttrs(attrs));
+  }
+};
+var replyChunksTotal = {
+  add(value, attrs) {
+    getBizMeter().createCounter("qqbot.reply.chunks_total").add(value, fillBizAttrs(attrs));
+  }
+};
+var replyLength = {
+  record(value, attrs) {
+    getBizMeter().createHistogram("qqbot.reply.length", {
+      valueType: ValueType.INT
+    }).record(value, fillBizAttrs(attrs));
+  }
+};
+var slashCommandTotal = {
+  add(value, attrs) {
+    getBizMeter().createCounter("qqbot.slash.total").add(value, fillBizAttrs(attrs));
+  }
+};
+var rateLimitRejectedTotal = {
+  add(value, attrs) {
+    getBizMeter().createCounter("qqbot.ratelimit.rejected_total").add(value, fillBizAttrs(attrs));
+  }
+};
+var envelopeLength = {
+  record(value, attrs) {
+    getBizMeter().createHistogram("qqbot.envelope.length", {
+      valueType: ValueType.INT
+    }).record(value, fillBizAttrs(attrs));
+  }
+};
+var transportDisconnectTotal = {
+  add(value, attrs) {
+    getBizMeter().createCounter("qqbot.transport.disconnect_total").add(value, fillBizAttrs(attrs));
+  }
+};
+
+// src/backend/openai.ts
+var OpenAIBackend = class {
+  name = "openai";
+  opts;
+  /** qualifier → 对话历史 */
+  histories = /* @__PURE__ */ new Map();
+  constructor(opts) {
+    this.opts = opts;
+  }
+  async init() {
+    this.opts.logger.info(`[openai] \u521D\u59CB\u5316: model=${this.opts.model} baseUrl=${this.opts.baseUrl}`);
+  }
+  async getOrCreateSession(qualifier) {
+    if (!this.histories.has(qualifier)) {
+      this.histories.set(qualifier, []);
+    }
+    return qualifier;
+  }
+  async *chat(params) {
+    const clientAttrs = {
+      [METRIC_ATTRS.CALLER_SERVICE]: "qqbot-cli",
+      [METRIC_ATTRS.CALLER_METHOD]: "chat",
+      [METRIC_ATTRS.CALLER_SERVER]: "qqbot-cli",
+      [METRIC_ATTRS.CALLEE_SERVICE]: "openai",
+      [METRIC_ATTRS.CALLEE_METHOD]: "chat/completions",
+      [METRIC_ATTRS.CALLEE_SERVER]: "openai",
+      [METRIC_ATTRS.CODE]: 0,
+      [METRIC_ATTRS.CODE_TYPE]: "success"
+    };
+    clientStartedTotal.add(1, clientAttrs);
+    const startTime = Date.now();
+    let hasError = false;
+    try {
+      const history = this.histories.get(params.qualifier) ?? [];
+      history.push({ role: "user", content: params.text });
+      if (history.length > 20) {
+        history.splice(0, history.length - 20);
+      }
+      const messages = [
+        { role: "system", content: this.opts.systemPrompt },
+        ...history
+      ];
+      const response = await fetch(`${this.opts.baseUrl}/chat/completions`, {
+        method: "POST",
+        headers: {
+          "Content-Type": "application/json",
+          Authorization: `Bearer ${this.opts.apiKey}`
+        },
+        body: JSON.stringify({
+          model: this.opts.model,
+          messages,
+          max_tokens: this.opts.maxTokens,
+          temperature: this.opts.temperature,
+          stream: true
+        })
+      });
+      if (!response.ok) {
+        const text = await response.text();
+        throw new Error(`OpenAI API ${response.status}: ${text.slice(0, 200)}`);
+      }
+      const reader = response.body?.getReader();
+      if (!reader) {
+        throw new Error("OpenAI API \u65E0\u54CD\u5E94\u4F53");
+      }
+      const decoder = new TextDecoder();
+      let buffer = "";
+      let fullReply = "";
+      try {
+        while (true) {
+          const { done, value } = await reader.read();
+          if (done) break;
+          buffer += decoder.decode(value, { stream: true });
+          const lines = buffer.split("\n");
+          buffer = lines.pop() ?? "";
+          for (const line of lines) {
+            const trimmed = line.trim();
+            if (!trimmed || !trimmed.startsWith("data: ")) continue;
+            const data = trimmed.slice(6);
+            if (data === "[DONE]") continue;
+            try {
+              const parsed = JSON.parse(data);
+              const delta = parsed.choices?.[0]?.delta?.content;
+              if (delta) {
+                fullReply += delta;
+                yield { type: "text", content: delta };
+              }
+            } catch {
+            }
+          }
+        }
+      } finally {
+        reader.releaseLock();
+      }
+      if (fullReply) {
+        history.push({ role: "assistant", content: fullReply });
+      }
+      yield { type: "done", content: "", stopReason: "stop" };
+    } catch (err) {
+      hasError = true;
+      clientHandledTotal.add(1, { ...clientAttrs, [METRIC_ATTRS.CODE]: 1, [METRIC_ATTRS.CODE_TYPE]: "error" });
+      throw err;
+    } finally {
+      if (!hasError) {
+        clientHandledTotal.add(1, clientAttrs);
+      }
+      clientHandledSeconds.record((Date.now() - startTime) / 1e3, clientAttrs);
+    }
+  }
+  async shutdown() {
+    this.histories.clear();
+  }
+};
+
+// src/cloudagent/acp-client.ts
+import {
+  ClientSideConnection,
+  PROTOCOL_VERSION
+} from "@agentclientprotocol/sdk";
+
+// src/cloudagent/acp-transport.ts
+function createTransport(options) {
+  const { endpoint, authToken, logger } = options;
+  let connectionId;
+  let closed = false;
+  const abortController = new AbortController();
+  let resolveReady;
+  let rejectReady;
+  const ready = new Promise((resolve2, reject) => {
+    resolveReady = resolve2;
+    rejectReady = reject;
+  });
+  const queue = [];
+  const waiters = [];
+  const enqueue = (m) => {
+    if (waiters.length > 0) waiters.shift()(m);
+    else queue.push(m);
+  };
+  const dequeue = () => {
+    if (closed && queue.length === 0) return Promise.resolve(null);
+    if (queue.length > 0) return Promise.resolve(queue.shift());
+    return new Promise((resolve2) => waiters.push(resolve2));
+  };
+  const closeAll = () => {
+    closed = true;
+    while (waiters.length > 0) waiters.shift()(null);
+  };
+  const baseHeaders = () => ({
+    Authorization: `Bearer ${authToken}`
+  });
+  async function startSSE() {
+    try {
+      const headers = baseHeaders();
+      headers["Accept"] = "text/event-stream";
+      const res = await fetch(endpoint, {
+        method: "GET",
+        headers,
+        signal: abortController.signal
+      });
+      if (!res.ok) {
+        throw new Error(`SSE GET failed: HTTP ${res.status} ${res.statusText}`);
+      }
+      const id = res.headers.get("Acp-Connection-Id");
+      if (!id) throw new Error("Missing Acp-Connection-Id header");
+      connectionId = id;
+      resolveReady();
+      logger?.info?.(`[acp:transport] SSE connected, connectionId=${id}`);
+      const reader = res.body?.getReader();
+      if (!reader) throw new Error("No SSE body reader");
+      const decoder = new TextDecoder();
+      let buf = "";
+      let evtData = "";
+      let evtType = "";
+      while (!closed) {
+        const { value, done } = await reader.read();
+        if (done) break;
+        buf += decoder.decode(value, { stream: true });
+        const lines = buf.split("\n");
+        buf = lines.pop() ?? "";
+        for (const line of lines) {
+          if (line === "") {
+            if (evtData && evtType !== "connected") {
+              try {
+                const msg = JSON.parse(evtData);
+                if (msg && typeof msg === "object" && "jsonrpc" in msg) {
+                  enqueue(msg);
+                }
+              } catch {
+              }
+            }
+            evtData = "";
+            evtType = "";
+            continue;
+          }
+          if (line.startsWith(":")) continue;
+          const idx = line.indexOf(":");
+          if (idx === -1) continue;
+          const field = line.slice(0, idx);
+          let val = line.slice(idx + 1);
+          if (val.startsWith(" ")) val = val.slice(1);
+          if (field === "event") evtType = val;
+          if (field === "data") evtData = (evtData || "") + val;
+        }
+      }
+    } catch (err) {
+      if (!closed && err?.name !== "AbortError") {
+        transportDisconnectTotal.add(1);
+        logger?.error?.(`[acp:transport] SSE error: ${err?.message ?? err}`);
+        rejectReady(err instanceof Error ? err : new Error(String(err)));
+      }
+    } finally {
+      closeAll();
+    }
+  }
+  async function sendMessage(message) {
+    if (closed) throw new Error("Transport closed");
+    await ready;
+    const headers = baseHeaders();
+    headers["Content-Type"] = "application/json";
+    headers["Accept"] = "application/json, text/event-stream";
+    headers["Acp-Connection-Id"] = connectionId;
+    const res = await fetch(endpoint, {
+      method: "POST",
+      headers,
+      body: JSON.stringify(message)
+    });
+    if (!res.ok) {
+      const t = await res.text().catch(() => "");
+      throw new Error(`POST failed: HTTP ${res.status} ${t.slice(0, 200)}`);
+    }
+    const ct = res.headers.get("Content-Type") ?? "";
+    if (ct.includes("text/event-stream")) {
+      const reader = res.body?.getReader();
+      if (reader) {
+        processPostSSE(reader).catch(
+          (e) => logger?.error?.(`[acp:transport] POST SSE error: ${e?.message ?? e}`)
+        );
+      }
+    } else if (ct.includes("application/json")) {
+      const data = await res.json();
+      if (data && typeof data === "object" && "jsonrpc" in data) {
+        enqueue(data);
+      }
+    }
+  }
+  async function processPostSSE(reader) {
+    const decoder = new TextDecoder();
+    let buf = "";
+    let data = "";
+    try {
+      while (true) {
+        const { value, done } = await reader.read();
+        if (done) break;
+        buf += decoder.decode(value, { stream: true });
+        const lines = buf.split("\n");
+        buf = lines.pop() ?? "";
+        for (const line of lines) {
+          if (line === "") {
+            if (data) {
+              try {
+                const m = JSON.parse(data);
+                if (m && typeof m === "object" && "jsonrpc" in m) {
+                  enqueue(m);
+                }
+              } catch {
+              }
+            }
+            data = "";
+            continue;
+          }
+          if (line.startsWith(":")) continue;
+          const idx = line.indexOf(":");
+          if (idx === -1) continue;
+          const f = line.slice(0, idx);
+          let v = line.slice(idx + 1);
+          if (v.startsWith(" ")) v = v.slice(1);
+          if (f === "data") data = (data || "") + v;
+        }
+      }
+    } finally {
+      reader.releaseLock();
+    }
+  }
+  async function close() {
+    if (closed) return;
+    if (connectionId) {
+      try {
+        const headers = baseHeaders();
+        headers["Acp-Connection-Id"] = connectionId;
+        await fetch(endpoint, {
+          method: "DELETE",
+          headers,
+          signal: AbortSignal.timeout(5e3)
+        });
+        logger?.debug?.(`[acp:transport] DELETE sent`);
+      } catch {
+      }
+    }
+    abortController.abort();
+    closeAll();
+  }
+  const readable = new ReadableStream({
+    async pull(controller) {
+      const m = await dequeue();
+      if (m === null) controller.close();
+      else controller.enqueue(m);
+    },
+    cancel() {
+      closeAll();
+      abortController.abort();
+    }
+  });
+  const writable = new WritableStream({
+    async write(m) {
+      await sendMessage(m);
+    },
+    close() {
+      closeAll();
+    },
+    abort() {
+      closeAll();
+      abortController.abort();
+    }
+  });
+  startSSE();
+  return { readable, writable, ready, close };
+}
+
+// src/cloudagent/acp-client.ts
+var AcpClient = class {
+  opts;
+  transport;
+  connection;
+  _connected = false;
+  /** Agent 能力集（initialize 后填充） */
+  agentCapabilities = null;
+  /** 内部事件缓冲：sessionUpdate 推送的 chunk 暂存于此 */
+  eventBuffer = [];
+  eventWaiters = [];
+  promptDone = false;
+  /** Only accept chunks when actively prompting (ignore session resume replay). */
+  prompting = false;
+  /** Last time any ACP activity was received (for idle timeout). */
+  lastActivityAt = 0;
+  constructor(opts) {
+    this.opts = opts;
+  }
+  get isConnected() {
+    return this._connected;
+  }
+  // ============ 连接 ============
+  /**
+   * 建立 SSE + initialize 握手。
+   * 自动重试（默认 20 次 × 3s），触发沙箱唤醒。
+   */
+  async connect() {
+    const { logger, endpoint, authToken, maxRetries, retryIntervalMs } = this.opts;
+    logger.info(`[acp] connecting to ${endpoint} ...`);
+    const connectStart = Date.now();
+    for (let attempt = 1; attempt <= maxRetries; attempt++) {
+      try {
+        this.transport = createTransport({ endpoint, authToken, logger });
+        this.connection = new ClientSideConnection(
+          () => ({
+            sessionUpdate: async (params) => {
+              try {
+                this.handleSessionUpdate(params);
+                this.opts.onSessionUpdate?.(params);
+              } catch (e) {
+                logger.error(`[acp] onSessionUpdate error: ${e?.message ?? e}`);
+              }
+            },
+            requestPermission: async (params) => {
+              if (this.opts.onRequestPermission) {
+                return this.opts.onRequestPermission(params);
+              }
+              const first = params.options?.[0];
+              logger.debug?.(
+                `[acp] auto-approve permission: ${first?.optionId ?? "approve"}`
+              );
+              return {
+                outcome: {
+                  outcome: "selected",
+                  optionId: first?.optionId ?? "approve"
+                }
+              };
+            },
+            // 处理 SDK 未内置的扩展通知（消除 "Method not found" 警告）
+            extNotification: async (method, params) => {
+              if (!this.prompting) return;
+              switch (method) {
+                case "session/endTurn": {
+                  const stopReason = params?.stopReason ?? "end_turn";
+                  logger.debug?.(`[acp] endTurn: stopReason=${stopReason}`);
+                  this.promptDone = true;
+                  const doneEvent = { type: "done", text: "", stopReason };
+                  if (this.eventWaiters.length > 0) {
+                    this.eventWaiters.shift()(doneEvent);
+                  } else {
+                    this.eventBuffer.push(doneEvent);
+                  }
+                  break;
+                }
+                default:
+                  logger.debug?.(`[acp] unknown notification: ${method}`);
+                  break;
+              }
+            }
+          }),
+          this.transport
+        );
+        await this.transport.ready;
+        const initResp = await this.connection.initialize({
+          protocolVersion: PROTOCOL_VERSION,
+          clientCapabilities: {
+            fs: { readTextFile: false, writeTextFile: false }
+          }
+        });
+        this.agentCapabilities = initResp.agentCapabilities;
+        this._connected = true;
+        acpConnectSeconds.record((Date.now() - connectStart) / 1e3, { result: "success" });
+        if (attempt > 1) {
+          acpConnectRetries.add(attempt - 1, { result: "success" });
+        }
+        logger.info(
+          `[acp] initialized (attempt=${attempt}, capabilities=${JSON.stringify(initResp.agentCapabilities)})`
+        );
+        return;
+      } catch (e) {
+        this.transport = void 0;
+        this.connection = void 0;
+        if (attempt >= maxRetries) {
+          acpConnectSeconds.record((Date.now() - connectStart) / 1e3, { result: "fail" });
+          acpConnectRetries.add(attempt, { result: "fail" });
+          throw new Error(
+            `ACP connect failed after ${maxRetries} attempts: ${e?.message ?? e}`
+          );
+        }
+        logger.info(
+          `[acp] attempt ${attempt}/${maxRetries} failed: ${e?.message ?? e}, retrying in ${retryIntervalMs / 1e3}s`
+        );
+        await new Promise((r) => setTimeout(r, retryIntervalMs));
+      }
+    }
+  }
+  // ============ Session 管理 ============
+  /** 创建新 ACP session */
+  async createSession(cwd = "/workspace") {
+    if (!this.connection) throw new Error("ACP not connected");
+    const mcpServers = this.opts.extraMcpServers ?? [];
+    const resp = await this.connection.newSession({ cwd, mcpServers });
+    this.opts.logger.info(
+      `[acp] session created: ${resp.sessionId} (cwd=${cwd}, mcp=${mcpServers.length})`
+    );
+    this.opts.logger.debug?.(`[acp] newSession response: ${JSON.stringify(resp)}`);
+    return resp.sessionId;
+  }
+  /** 加载已有 session（含历史回放） */
+  async loadSession(sessionId, cwd = "/workspace") {
+    if (!this.connection) throw new Error("ACP not connected");
+    const mcpServers = this.opts.extraMcpServers ?? [];
+    const resp = await this.connection.loadSession({ sessionId, cwd, mcpServers });
+    this.opts.logger.info(`[acp] session loaded: ${sessionId}`);
+    this.opts.logger.debug?.(`[acp] loadSession response: ${JSON.stringify(resp)}`);
+  }
+  /** 取消当前正在执行的 prompt */
+  cancelPrompt(sessionId) {
+    if (!this.connection) return;
+    this.connection.cancel({ sessionId }).catch((err) => {
+      this.opts.logger.debug?.(`[acp] cancel error: ${err?.message ?? err}`);
+    });
+    this.opts.logger.info(`[acp] cancel sent for session=${sessionId}`);
+  }
+  /** 切换权限模式 */
+  async setMode(sessionId, modeId) {
+    if (!this.connection) throw new Error("ACP not connected");
+    await this.connection.request?.("session/set_mode", { sessionId, modeId });
+    this.opts.logger.info(`[acp] mode set to ${modeId} for session=${sessionId}`);
+  }
+  /** 切换模型 */
+  async setModel(sessionId, modelId) {
+    if (!this.connection) throw new Error("ACP not connected");
+    await this.connection.request?.("session/set_model", { sessionId, modelId });
+    this.opts.logger.info(`[acp] model set to ${modelId} for session=${sessionId}`);
+  }
+  // ============ Prompt（流式输出） ============
+  /**
+   * 发送 prompt 并流式接收回复。
+   *
+   * 同时消费：
+   *   - POST SSE（prompt 直接响应流）
+   *   - GET SSE（session/update 推送的 agent_message_chunk 等）
+   *
+   * 通过 eventBuffer + waitForStable 实现双流时序补偿。
+   */
+  async *promptStream(sessionId, blocks) {
+    if (!this.connection) throw new Error("ACP not connected");
+    this.eventBuffer = [];
+    this.eventWaiters = [];
+    this.promptDone = false;
+    this.prompting = true;
+    this.lastActivityAt = Date.now();
+    const promptPromise = this.connection.prompt({
+      sessionId,
+      prompt: blocks
+    });
+    promptPromise.catch((err) => {
+      this.promptDone = true;
+      const errorEvent = {
+        type: "done",
+        text: err?.message ?? String(err),
+        stopReason: "error"
+      };
+      if (this.eventWaiters.length > 0) {
+        this.eventWaiters.shift()(errorEvent);
+      } else {
+        this.eventBuffer.push(errorEvent);
+      }
+    });
+    try {
+      while (true) {
+        const event = await this.nextEvent();
+        if (event === null) {
+          yield { type: "done", text: "", stopReason: "timeout" };
+          break;
+        }
+        yield event;
+        if (event.type === "done") break;
+      }
+    } finally {
+      try {
+        const result = await promptPromise;
+        await this.waitForStable();
+        while (this.eventBuffer.length > 0) {
+          const ev = this.eventBuffer.shift();
+          if (ev.type !== "done") {
+          }
+        }
+        if (!this.promptDone) {
+          this.promptDone = true;
+        }
+      } catch (e) {
+        this.opts.logger.error(`[acp] prompt error: ${e?.message ?? e}`);
+        throw e;
+      } finally {
+        this.prompting = false;
+      }
+    }
+  }
+  /**
+   * 发送 prompt（非流式，等待完成后返回 stopReason）。
+   * 适合不需要流式输出的场景。
+   */
+  async prompt(sessionId, input) {
+    if (!this.connection) throw new Error("ACP not connected");
+    const blocks = typeof input === "string" ? [{ type: "text", text: input }] : input;
+    const resp = await this.connection.prompt({
+      sessionId,
+      prompt: blocks
+    });
+    return resp.stopReason;
+  }
+  // ============ 关闭 ============
+  async close() {
+    if (this.transport) {
+      await this.transport.close();
+      this.transport = void 0;
+    }
+    this.connection = void 0;
+    this._connected = false;
+    while (this.eventWaiters.length > 0) {
+      this.eventWaiters.shift()(null);
+    }
+    this.opts.logger.info("[acp] closed");
+  }
+  /**
+   * 标记连接已断开（由外部错误处理调用）。
+   * 下次 ensureAcpReady 会触发重连。
+   */
+  markDisconnected() {
+    this._connected = false;
+    while (this.eventWaiters.length > 0) {
+      this.eventWaiters.shift()(null);
+    }
+  }
+  // ============ 内部 ============
+  /**
+   * 处理 GET SSE 推送的 session/update 通知。
+   * 将解析后的事件入队到 eventBuffer，供 promptStream 消费。
+   */
+  handleSessionUpdate(n) {
+    const update = n.update ?? {};
+    const t = update.sessionUpdate ?? update.type;
+    if (!this.prompting) return;
+    this.lastActivityAt = Date.now();
+    this.opts.logger.debug?.(
+      `[acp:raw] type=${t} ${JSON.stringify(update)}`
+    );
+    let event = null;
+    switch (t) {
+      case "agent_message_chunk": {
+        const txt = update.content?.text ?? "";
+        if (txt) event = { type: "agent_message_chunk", text: txt };
+        break;
+      }
+      case "agent_thought_chunk": {
+        const txt = update.content?.text ?? "";
+        if (txt) event = { type: "agent_thought_chunk", text: txt };
+        break;
+      }
+      case "tool_call": {
+        event = {
+          type: "tool_call",
+          text: "",
+          title: update.title,
+          toolCallId: update.toolCallId,
+          kind: update.kind,
+          status: update.status,
+          rawInput: update.rawInput
+        };
+        break;
+      }
+      case "tool_call_update": {
+        if (update.status === "completed" || update.status === "failed") {
+          event = {
+            type: "tool_call_update",
+            text: "",
+            toolCallId: update.toolCallId,
+            status: update.status
+          };
+        }
+        break;
+      }
+      case "plan": {
+        event = { type: "plan", text: "", entries: update.entries };
+        break;
+      }
+      default:
+        break;
+    }
+    if (event) {
+      if (this.eventWaiters.length > 0) {
+        this.eventWaiters.shift()(event);
+      } else {
+        this.eventBuffer.push(event);
+      }
+    }
+  }
+  /** 从 eventBuffer 取下一个事件（阻塞等待） */
+  nextEvent() {
+    if (this.eventBuffer.length > 0) {
+      return Promise.resolve(this.eventBuffer.shift());
+    }
+    if (this.promptDone) {
+      return Promise.resolve(null);
+    }
+    const timeoutMs = this.opts.eventTimeoutMs ?? 18e4;
+    return new Promise((resolve2) => {
+      this.eventWaiters.push(resolve2);
+      const checkInterval = setInterval(() => {
+        const idx = this.eventWaiters.indexOf(resolve2);
+        if (idx < 0) {
+          clearInterval(checkInterval);
+          return;
+        }
+        const idle = Date.now() - this.lastActivityAt;
+        if (idle >= timeoutMs) {
+          clearInterval(checkInterval);
+          this.eventWaiters.splice(idx, 1);
+          this.opts.logger.debug?.(`[acp] nextEvent idle timeout (${timeoutMs / 1e3}s), returning null`);
+          resolve2(null);
+        }
+      }, 5e3);
+    });
+  }
+  /**
+   * 双流时序补偿：等待 GET SSE 中可能还在路上的 chunk 落地。
+   * prompt POST SSE 返回后，GET SSE 可能还有 ~80ms 延迟的 chunk。
+   */
+  async waitForStable(quietMs = 300, maxWaitMs = 1500) {
+    const start = Date.now();
+    let lastEventAt = Date.now();
+    while (Date.now() - start < maxWaitMs) {
+      if (this.eventBuffer.length > 0) {
+        lastEventAt = Date.now();
+        await new Promise((r) => setTimeout(r, 50));
+        continue;
+      }
+      const silent = Date.now() - lastEventAt;
+      if (silent >= quietMs) return;
+      await new Promise((r) => setTimeout(r, quietMs - silent));
+    }
+  }
+};
+
+// src/cloudagent/sandbox.ts
+import JSONBig from "json-bigint";
+var JSONB = JSONBig({ storeAsString: true });
+async function createSandbox(params) {
+  const { runtimeName, apiKey, endpoint, systemPrompt, logger } = params;
+  const url = `${endpoint}/agentos/runtimes`;
+  const body = JSON.stringify({ runtimeName, agentManifest: {
+    id: runtimeName,
+    name: runtimeName,
+    manifestVersion: "1.0",
+    system_prompt: systemPrompt ?? "You are a helpful assistant running inside a QQ Bot.",
+    secrets: [{ key: "CODEBUDDY_API_KEY", value: apiKey }]
+  } });
+  logger?.debug?.(`[agentos] >>> POST ${url}`);
+  const res = await fetch(url, {
+    method: "POST",
+    headers: { "Content-Type": "application/json", "x-api-key": apiKey, "X-Sandbox-Type": "AGS" },
+    body
+  });
+  return parseApiResponse(res, `POST ${url}`, logger);
+}
+async function getRuntime(runtimeId, apiKey, endpoint, logger) {
+  const url = `${endpoint}/agentos/runtimes/${runtimeId}`;
+  logger?.debug?.(`[agentos] >>> GET ${url}`);
+  const res = await fetch(url, {
+    method: "GET",
+    headers: { "x-api-key": apiKey }
+  });
+  return parseApiResponse(res, `GET ${url}`, logger);
+}
+async function waitForRunning(runtimeId, apiKey, endpoint, opts = {}) {
+  const maxWaitMs = opts.maxWaitMs ?? 18e4;
+  const intervalMs = opts.intervalMs ?? 3e3;
+  const start = Date.now();
+  while (Date.now() - start < maxWaitMs) {
+    const rt = await getRuntime(runtimeId, apiKey, endpoint, opts.logger);
+    if (rt.status === "RUNNING") {
+      sandboxStartSeconds.record((Date.now() - start) / 1e3);
+      return rt;
+    }
+    if (rt.status === "FAILED") {
+      throw new Error(`Runtime ${runtimeId} FAILED: ${rt.failureReason ?? "unknown"}`);
+    }
+    const elapsed = Math.round((Date.now() - start) / 1e3);
+    opts.logger?.info?.(`[sandbox] status=${rt.status}, waiting... (${elapsed}s)`);
+    await new Promise((r) => setTimeout(r, intervalMs));
+  }
+  throw new Error(`Runtime ${runtimeId} not ready within ${maxWaitMs / 1e3}s`);
+}
+async function createControlPlaneSession(runtimeId, sessionId, apiKey, endpoint, logger) {
+  const url = `${endpoint}/agentos/runtimes/${runtimeId}/sessions`;
+  const body = JSON.stringify({
+    sessionId,
+    agentManifest: {
+      id: "qqbot-cli",
+      name: "QQBot-CLI",
+      manifestVersion: "1.0"
+    }
+  });
+  logger?.debug?.(`[agentos] >>> POST ${url} body=${body}`);
+  const res = await fetch(url, {
+    method: "POST",
+    headers: { "Content-Type": "application/json", "x-api-key": apiKey },
+    body
+  });
+  return parseApiResponse(res, `POST ${url}`, logger);
+}
+async function getSession(runtimeId, sessionId, apiKey, endpoint, logger) {
+  const url = `${endpoint}/agentos/runtimes/${runtimeId}/sessions/${sessionId}`;
+  logger?.debug?.(`[agentos] >>> GET ${url}`);
+  const res = await fetch(url, {
+    method: "GET",
+    headers: { "x-api-key": apiKey }
+  });
+  if (res.status === 404) {
+    const text = await res.text().catch(() => "");
+    logger?.debug?.(`[agentos] <<< 404 ${text}`);
+    return null;
+  }
+  return parseApiResponse(res, `GET ${url}`, logger);
+}
+async function waitForSessionReady(runtimeId, sessionId, apiKey, endpoint, opts = {}) {
+  const maxWaitMs = opts.maxWaitMs ?? 3e4;
+  const intervalMs = opts.intervalMs ?? 1e3;
+  const start = Date.now();
+  while (Date.now() - start < maxWaitMs) {
+    const sess = await getSession(runtimeId, sessionId, apiKey, endpoint, opts.logger);
+    if (!sess) {
+      await new Promise((r) => setTimeout(r, intervalMs));
+      continue;
+    }
+    const status = sess.sessionStatus.toUpperCase();
+    if (status === "RUNNING" || status === "READY" || status === "ACTIVE") {
+      sessionCreateSeconds.record((Date.now() - start) / 1e3);
+      return sess;
+    }
+    if (status === "FAILED" || status === "ERROR") {
+      throw new Error(`Session ${sessionId} failed: status=${sess.sessionStatus}`);
+    }
+    await new Promise((r) => setTimeout(r, intervalMs));
+  }
+  throw new Error(`Session ${sessionId} not ready within ${maxWaitMs / 1e3}s`);
+}
+async function deleteControlPlaneSession(runtimeId, sessionId, apiKey, endpoint, logger) {
+  const url = `${endpoint}/agentos/runtimes/${runtimeId}/sessions/${sessionId}/delete`;
+  logger?.debug?.(`[agentos] >>> POST ${url}`);
+  const res = await fetch(url, {
+    method: "POST",
+    headers: { "x-api-key": apiKey },
+    signal: AbortSignal.timeout(5e3)
+  });
+  if (!res.ok) {
+    const t = await res.text().catch(() => "");
+    logger?.debug?.(`[agentos] <<< ${res.status} ${t}`);
+    throw new Error(`deleteSession HTTP ${res.status}: ${t}`);
+  }
+  logger?.debug?.(`[agentos] <<< ${res.status} OK`);
+}
+async function parseApiResponse(res, path2, logger) {
+  const text = await res.text().catch(() => "");
+  logger?.debug?.(`[agentos] <<< ${res.status} ${text}`);
+  if (!res.ok) {
+    throw new Error(`AgentOS HTTP ${res.status}: ${text} [${path2}]`);
+  }
+  let json;
+  try {
+    json = JSONB.parse(text);
+  } catch {
+    throw new Error(`AgentOS response parse failed [${path2}]`);
+  }
+  if (json.code !== 0) {
+    throw new Error(`AgentOS error [${path2}] code=${json.code}: ${json.msg}`);
+  }
+  if (!json.data) {
+    throw new Error(`AgentOS empty data [${path2}]`);
+  }
+  return json.data;
+}
+
+// src/telemetry/client-interceptor.ts
+import { trace, SpanKind, SpanStatusCode } from "@opentelemetry/api";
+var tracer = trace.getTracer("qqbot-cli");
+async function withClientMetrics(opts, fn) {
+  const attrs = buildAttrs(opts);
+  const spanName = `${opts.calleeService}/${opts.calleeMethod}`;
+  return tracer.startActiveSpan(
+    spanName,
+    {
+      kind: SpanKind.CLIENT,
+      attributes: {
+        "rpc.system": "custom",
+        "rpc.service": opts.calleeService,
+        "rpc.method": opts.calleeMethod,
+        "caller.service": "qqbot-cli",
+        "caller.method": opts.callerMethod,
+        ...opts.extras
+      }
+    },
+    async (span) => {
+      clientStartedTotal.add(1, attrs);
+      const startTime = Date.now();
+      try {
+        const result = await fn();
+        span.setStatus({ code: SpanStatusCode.OK });
+        clientHandledTotal.add(1, attrs);
+        return result;
+      } catch (err) {
+        span.setStatus({
+          code: SpanStatusCode.ERROR,
+          message: err instanceof Error ? err.message : String(err)
+        });
+        span.recordException(err instanceof Error ? err : new Error(String(err)));
+        clientHandledTotal.add(1, {
+          ...attrs,
+          [METRIC_ATTRS.CODE]: 1,
+          [METRIC_ATTRS.CODE_TYPE]: "error"
+        });
+        throw err;
+      } finally {
+        span.end();
+        clientHandledSeconds.record((Date.now() - startTime) / 1e3, attrs);
+      }
+    }
+  );
+}
+function buildAttrs(opts) {
+  return {
+    [METRIC_ATTRS.CALLER_SERVICE]: "qqbot-cli",
+    [METRIC_ATTRS.CALLER_METHOD]: opts.callerMethod,
+    [METRIC_ATTRS.CALLER_SERVER]: "qqbot-cli",
+    [METRIC_ATTRS.CALLEE_SERVICE]: opts.calleeService,
+    [METRIC_ATTRS.CALLEE_METHOD]: opts.calleeMethod,
+    [METRIC_ATTRS.CALLEE_SERVER]: opts.calleeServer ?? opts.calleeService,
+    [METRIC_ATTRS.CODE]: 0,
+    [METRIC_ATTRS.CODE_TYPE]: "success",
+    ...opts.extras
+  };
+}
+
+// src/cloudagent/connection-pool.ts
+var AcpConnectionPool = class {
+  entries = /* @__PURE__ */ new Map();
+  /** soft-close 的 session（qualifier → sessionId），恢复时用 */
+  evicted = /* @__PURE__ */ new Map();
+  /** 并发创建去重 */
+  pendingCreates = /* @__PURE__ */ new Map();
+  cleanupTimer = null;
+  cleaning = false;
+  config;
+  constructor(config) {
+    this.config = config;
+    if (config.enableCleanup) {
+      this.startCleanup();
+    }
+  }
+  /** 当前活跃连接数 */
+  get size() {
+    return this.entries.size;
+  }
+  /** 获取 qualifier 对应的连接和 sessionId */
+  get(qualifier) {
+    return this.entries.get(qualifier);
+  }
+  /**
+   * 获取或创建 qualifier 对应的连接。
+   * extSessionId: 外部指定的会话 ID（用于 session/load），undefined 则直接 session/new。
+   */
+  async getOrCreate(qualifier, extSessionId) {
+    const existing = this.entries.get(qualifier);
+    if (existing && existing.status === "active") {
+      existing.lastActivityAt = Date.now();
+      return { client: existing.client, sessionId: existing.sessionId };
+    }
+    const pending = this.pendingCreates.get(qualifier);
+    if (pending) {
+      const entry = await pending;
+      return { client: entry.client, sessionId: entry.sessionId };
+    }
+    const createPromise = this.ensureSession(qualifier, extSessionId);
+    this.pendingCreates.set(qualifier, createPromise);
+    try {
+      const entry = await createPromise;
+      return { client: entry.client, sessionId: entry.sessionId };
+    } finally {
+      this.pendingCreates.delete(qualifier);
+    }
+  }
+  /** 刷新活跃时间 */
+  touch(qualifier) {
+    const entry = this.entries.get(qualifier);
+    if (entry) {
+      entry.lastActivityAt = Date.now();
+    }
+  }
+  /**
+   * 恢复断线的连接（外部调用，如 chat 捕获到 connection error）。
+   * 关闭旧连接 → ensureSession 重新建立。
+   */
+  async restore(qualifier) {
+    const entry = this.entries.get(qualifier);
+    if (entry) {
+      await entry.client.close().catch(() => {
+      });
+      this.entries.delete(qualifier);
+    }
+    try {
+      const restored = await this.ensureSession(qualifier);
+      poolRestoreTotal.add(1, { result: "success" });
+      return { client: restored.client, sessionId: restored.sessionId };
+    } catch (err) {
+      poolRestoreTotal.add(1, { result: "fail" });
+      throw err;
+    }
+  }
+  /** 主动关闭某个 qualifier 的连接 */
+  async close(qualifier) {
+    const entry = this.entries.get(qualifier);
+    if (!entry) return;
+    entry.status = "closing";
+    await entry.client.close().catch(() => {
+    });
+    this.entries.delete(qualifier);
+    if (this.config.controlPlane) {
+      const { runtimeId, apiKey, endpoint } = this.config.controlPlane;
+      await deleteControlPlaneSession(runtimeId, entry.sessionId, apiKey, endpoint, this.config.logger).catch((err) => {
+        this.config.logger.debug(
+          `[pool] deleteSession failed: ${err instanceof Error ? err.message : String(err)}`
+        );
+      });
+    }
+  }
+  /** 关闭所有连接（graceful shutdown） */
+  async closeAll() {
+    this.stopCleanup();
+    const qualifiers = [...this.entries.keys()];
+    await Promise.allSettled(qualifiers.map((q) => this.close(q)));
+    this.entries.clear();
+    this.evicted.clear();
+  }
+  // ─── 内部方法 ───
+  /** 创建新连接 + 新 session */
+  async createEntry(qualifier, extSessionId) {
+    await this.ensureCapacity();
+    const now = Date.now();
+    const { logger } = this.config;
+    let sessionId = extSessionId ?? qualifier;
+    const client = this.createClient();
+    await withClientMetrics({
+      callerMethod: "connect",
+      calleeService: "cloudagent-acp",
+      calleeMethod: "connect"
+    }, () => client.connect());
+    if (this.config.controlPlane) {
+      const { runtimeId, apiKey, endpoint } = this.config.controlPlane;
+      let alreadyExists = false;
+      try {
+        await withClientMetrics({
+          callerMethod: "session",
+          calleeService: "agentos",
+          calleeMethod: "createSession"
+        }, () => createControlPlaneSession(runtimeId, sessionId, apiKey, endpoint, logger));
+      } catch (err) {
+        const msg = err instanceof Error ? err.message : String(err);
+        if (!msg.includes("already exists")) {
+          throw err;
+        }
+        alreadyExists = true;
+        logger.info(`[pool] session already exists: ${sessionId}, will load`);
+      }
+      if (!alreadyExists) {
+        await waitForSessionReady(runtimeId, sessionId, apiKey, endpoint, { logger });
+      }
+      await withClientMetrics({
+        callerMethod: "session",
+        calleeService: "cloudagent-acp",
+        calleeMethod: "loadSession"
+      }, () => client.loadSession(sessionId));
+    } else {
+      if (extSessionId) {
+        try {
+          await client.loadSession(extSessionId);
+          sessionId = extSessionId;
+          logger.info(`[pool] direct session/load: ${sessionId}`);
+        } catch {
+          sessionId = await client.createSession("/workspace");
+          logger.info(`[pool] direct session/new (load failed): ${sessionId}`);
+        }
+      } else {
+        sessionId = await client.createSession("/workspace");
+        logger.info(`[pool] direct session/new: ${sessionId}`);
+      }
+    }
+    const entry = {
+      qualifier,
+      sessionId,
+      client,
+      status: "active",
+      createdAt: now,
+      lastActivityAt: now
+    };
+    this.entries.set(qualifier, entry);
+    poolCreateSeconds.record((Date.now() - now) / 1e3);
+    poolSize.record(this.size);
+    logger.info(`[pool] created: qualifier=${qualifier} sessionId=${sessionId} (active=${this.size})`);
+    return entry;
+  }
+  /**
+   * 确保 session 存在并连接。
+   * 1. 控制面 getSession 查是否已存在
+   * 2. 存在 → connect + loadSession
+   * 3. 不存在 → 控制面 create → 等就绪 → connect + loadSession
+   */
+  async ensureSession(qualifier, extSessionId) {
+    await this.ensureCapacity();
+    const { logger } = this.config;
+    const sessionId = extSessionId ?? qualifier;
+    this.evicted.delete(qualifier);
+    let sessionExists = false;
+    if (this.config.controlPlane) {
+      const { runtimeId, apiKey, endpoint } = this.config.controlPlane;
+      const sess = await getSession(runtimeId, sessionId, apiKey, endpoint, logger);
+      if (sess) {
+        const status = sess.sessionStatus.toUpperCase();
+        sessionExists = status !== "FAILED" && status !== "ERROR";
+        logger.info(`[pool] session exists: ${sessionId} status=${sess.sessionStatus}`);
+      } else {
+        logger.info(`[pool] session not found: ${sessionId}, will create`);
+      }
+    }
+    if (!sessionExists) {
+      return this.createEntry(qualifier, extSessionId);
+    }
+    const client = this.createClient();
+    await withClientMetrics({
+      callerMethod: "connect",
+      calleeService: "cloudagent-acp",
+      calleeMethod: "connect"
+    }, () => client.connect());
+    await withClientMetrics({
+      callerMethod: "session",
+      calleeService: "cloudagent-acp",
+      calleeMethod: "loadSession"
+    }, () => client.loadSession(sessionId));
+    const now = Date.now();
+    const entry = {
+      qualifier,
+      sessionId,
+      client,
+      status: "active",
+      createdAt: now,
+      lastActivityAt: now
+    };
+    this.entries.set(qualifier, entry);
+    logger.info(`[pool] restored: qualifier=${qualifier} sessionId=${sessionId} (active=${this.size})`);
+    return entry;
+  }
+  /** 确保有容量，超限则 LRU 淘汰 */
+  async ensureCapacity() {
+    const activeCount = [...this.entries.values()].filter((e) => e.status === "active").length;
+    if (activeCount >= this.config.maxConnections) {
+      await this.evictLRU();
+    }
+  }
+  /** LRU 淘汰最久未活跃的连接 */
+  async evictLRU() {
+    let oldest = null;
+    for (const entry of this.entries.values()) {
+      if (entry.status !== "active") continue;
+      if (!oldest || entry.lastActivityAt < oldest.lastActivityAt) {
+        oldest = entry;
+      }
+    }
+    if (oldest) {
+      poolEvictTotal.add(1);
+      this.config.logger.info(
+        `[pool] evicting LRU: qualifier=${oldest.qualifier} idle=${Date.now() - oldest.lastActivityAt}ms`
+      );
+      if (this.config.preserveOnEvict) {
+        this.softClose(oldest.qualifier);
+      } else {
+        await this.close(oldest.qualifier);
+      }
+    }
+  }
+  /** Soft-close：关闭 SSE 连接但保留服务端 session */
+  softClose(qualifier) {
+    const entry = this.entries.get(qualifier);
+    if (!entry) return;
+    this.config.logger.info(
+      `[pool] soft-close: qualifier=${qualifier} sessionId=${entry.sessionId}`
+    );
+    entry.client.close().catch(() => {
+    });
+    this.evicted.set(qualifier, entry.sessionId);
+    this.entries.delete(qualifier);
+  }
+  /** 创建 AcpClient 实例（不连接） */
+  createClient() {
+    return new AcpClient({
+      endpoint: this.config.acpEndpoint,
+      authToken: this.config.acpToken,
+      maxRetries: this.config.acpConnectRetries,
+      retryIntervalMs: this.config.acpRetryIntervalMs,
+      eventTimeoutMs: this.config.eventTimeoutMs,
+      extraMcpServers: this.config.mcpServers,
+      logger: this.config.logger
+    });
+  }
+  // ─── 定时清理 ───
+  startCleanup() {
+    if (this.cleanupTimer) return;
+    this.cleanupTimer = setInterval(() => {
+      void this.runCleanup();
+    }, this.config.cleanupIntervalMs);
+  }
+  stopCleanup() {
+    if (this.cleanupTimer) {
+      clearInterval(this.cleanupTimer);
+      this.cleanupTimer = null;
+    }
+  }
+  async runCleanup() {
+    if (this.cleaning) return;
+    this.cleaning = true;
+    try {
+      const now = Date.now();
+      const expired = [];
+      for (const [qualifier, entry] of this.entries) {
+        if (entry.status === "active" && now - entry.lastActivityAt > this.config.idleTimeoutMs) {
+          expired.push(qualifier);
+        }
+      }
+      if (expired.length > 0) {
+        this.config.logger.info(
+          `[pool] cleanup: ${expired.length} idle connections (preserve=${this.config.preserveOnEvict})`
+        );
+        if (this.config.preserveOnEvict) {
+          for (const q of expired) {
+            this.softClose(q);
+          }
+        } else {
+          await Promise.allSettled(expired.map((q) => this.close(q)));
+        }
+      }
+    } finally {
+      this.cleaning = false;
+    }
+  }
+};
+
+// src/backend/cloudagent.ts
+import { trace as trace2, SpanKind as SpanKind2, SpanStatusCode as SpanStatusCode2 } from "@opentelemetry/api";
+var tracer2 = trace2.getTracer("qqbot-cli");
+var CloudAgentBackend = class {
+  name = "cloudagent";
+  opts;
+  pool = null;
+  runtimeId = null;
+  acpEndpoint = null;
+  acpToken = null;
+  constructor(opts) {
+    this.opts = opts;
+  }
+  async init() {
+    const { config, logger } = this.opts;
+    logger.info(`[cloudagent] \u521D\u59CB\u5316: endpoint=${config.endpoint} sandbox.mode=${config.sandbox.mode}`);
+    if (config.sandbox.mode === "direct") {
+      if (!config.sandbox.acpEndpoint) {
+        throw new Error("sandbox.mode=direct \u65F6\uFF0Csandbox.acpEndpoint \u5FC5\u586B");
+      }
+      this.acpEndpoint = config.sandbox.acpEndpoint;
+      this.acpToken = config.sandbox.acpToken ?? config.apiKey ?? "";
+      logger.info(`[cloudagent] \u76F4\u8FDE ACP: ${this.acpEndpoint}`);
+    } else if (config.sandbox.mode === "manual" && config.sandbox.runtimeId) {
+      if (!config.apiKey) {
+        throw new Error("sandbox.mode=manual \u65F6\uFF0Cbackend.cloudagent.apiKey \u5FC5\u586B");
+      }
+      this.runtimeId = config.sandbox.runtimeId;
+      const rt = await getRuntime(config.sandbox.runtimeId, config.apiKey, config.endpoint, logger);
+      this.acpEndpoint = rt.links.acpLink.url;
+      this.acpToken = rt.links.acpLink.token;
+      logger.info(`[cloudagent] \u4F7F\u7528\u5DF2\u6709 runtime: ${this.runtimeId}`);
+    } else {
+      if (!config.apiKey) {
+        throw new Error("sandbox.mode=auto \u65F6\uFF0Cbackend.cloudagent.apiKey \u5FC5\u586B");
+      }
+      const runtimeName = config.sandbox.runtimeName ?? `qqbot-${this.opts.appId}-${Date.now()}`;
+      logger.info(`[cloudagent] \u521B\u5EFA\u6C99\u7BB1: ${runtimeName}`);
+      const rt = await createSandbox({
+        runtimeName,
+        apiKey: config.apiKey,
+        endpoint: config.endpoint,
+        systemPrompt: config.manifest.systemPrompt,
+        logger
+      });
+      this.runtimeId = rt.id;
+      logger.info(`[cloudagent] \u6C99\u7BB1\u5DF2\u521B\u5EFA: id=${rt.id} status=${rt.status}`);
+      if (rt.status !== "RUNNING") {
+        logger.info(`[cloudagent] \u7B49\u5F85 Runtime RUNNING...`);
+        const ready = await waitForRunning(rt.id, config.apiKey, config.endpoint, { logger });
+        this.acpEndpoint = ready.links.acpLink.url;
+        this.acpToken = ready.links.acpLink.token;
+      } else {
+        this.acpEndpoint = rt.links.acpLink.url;
+        this.acpToken = rt.links.acpLink.token;
+      }
+    }
+    const poolConfig = {
+      maxConnections: config.session.maxConnections,
+      enableCleanup: config.session.enableCleanup,
+      idleTimeoutMs: config.session.idleTimeoutMs,
+      cleanupIntervalMs: config.session.cleanupIntervalMs,
+      preserveOnEvict: config.session.preserveOnEvict,
+      acpEndpoint: this.acpEndpoint,
+      acpToken: this.acpToken,
+      acpConnectRetries: config.acp.maxRetries,
+      acpRetryIntervalMs: config.acp.retryIntervalMs,
+      eventTimeoutMs: config.acp.eventTimeoutMs,
+      mcpServers: this.opts.extraMcpServers ?? [],
+      controlPlane: this.runtimeId && config.apiKey ? { runtimeId: this.runtimeId, apiKey: config.apiKey, endpoint: config.endpoint } : void 0,
+      logger
+    };
+    this.pool = new AcpConnectionPool(poolConfig);
+    logger.info(`[cloudagent] \u8FDE\u63A5\u6C60\u5C31\u7EEA (max=${poolConfig.maxConnections})`);
+  }
+  async getOrCreateSession(qualifier, extSessionId) {
+    const { sessionId } = await this.pool.getOrCreate(qualifier, extSessionId);
+    return sessionId;
+  }
+  async *chat(params) {
+    const scopeType = params.qualifier.startsWith("group") ? "group" : "c2c";
+    const hasAttachments = (params.attachments?.length ?? 0) > 0;
+    const clientAttrs = {
+      [METRIC_ATTRS.CALLER_SERVICE]: "qqbot-cli",
+      [METRIC_ATTRS.CALLER_METHOD]: "chat",
+      [METRIC_ATTRS.CALLER_SERVER]: "qqbot-cli",
+      [METRIC_ATTRS.CALLEE_SERVICE]: "cloudagent-acp",
+      [METRIC_ATTRS.CALLEE_METHOD]: "prompt",
+      [METRIC_ATTRS.CALLEE_SERVER]: "cloudagent-acp",
+      [METRIC_ATTRS.CODE]: 0,
+      [METRIC_ATTRS.CODE_TYPE]: "success",
+      [METRIC_ATTRS.USER_EXT1]: scopeType,
+      [METRIC_ATTRS.USER_EXT2]: hasAttachments ? "multimodal" : "text"
+    };
+    const span = tracer2.startSpan("cloudagent-acp/prompt", {
+      kind: SpanKind2.CLIENT,
+      attributes: {
+        "rpc.system": "acp",
+        "rpc.service": "cloudagent-acp",
+        "rpc.method": "prompt",
+        "caller.method": "chat",
+        "msg.scope": scopeType,
+        "msg.input_type": hasAttachments ? "multimodal" : "text"
+      }
+    });
+    clientStartedTotal.add(1, clientAttrs);
+    const startTime = Date.now();
+    let hasError = false;
+    let firstChunkReceived = false;
+    try {
+      for await (const chunk of this.chatWithRetry(params, 1)) {
+        if (!firstChunkReceived) {
+          firstChunkReceived = true;
+          acpTtfbSeconds.record((Date.now() - startTime) / 1e3, { scope: scopeType });
+          span.addEvent("first_chunk", { ttfb_ms: Date.now() - startTime });
+        }
+        if (chunk.type === "tool" && chunk.status === "in_progress") {
+          toolCallsTotal.add(1, { "tool.kind": chunk.kind ?? "other", scope: scopeType });
+        }
+        yield chunk;
+      }
+    } catch (err) {
+      hasError = true;
+      span.setStatus({
+        code: SpanStatusCode2.ERROR,
+        message: err instanceof Error ? err.message : String(err)
+      });
+      span.recordException(err instanceof Error ? err : new Error(String(err)));
+      clientHandledTotal.add(1, {
+        ...clientAttrs,
+        [METRIC_ATTRS.CODE]: 1,
+        [METRIC_ATTRS.CODE_TYPE]: "error"
+      });
+      throw err;
+    } finally {
+      if (!hasError) {
+        span.setStatus({ code: SpanStatusCode2.OK });
+        clientHandledTotal.add(1, clientAttrs);
+      }
+      span.end();
+      clientHandledSeconds.record((Date.now() - startTime) / 1e3, clientAttrs);
+    }
+  }
+  async *chatWithRetry(params, retriesLeft) {
+    const { qualifier, text, attachments } = params;
+    try {
+      const { client, sessionId } = await this.pool.getOrCreate(qualifier);
+      const blocks = this.buildPromptBlocks(qualifier, text, attachments);
+      this.opts.logger.debug?.(`[acp:prompt] session=${sessionId} ${JSON.stringify(blocks)}`);
+      for await (const event of client.promptStream(sessionId, blocks)) {
+        switch (event.type) {
+          case "agent_message_chunk":
+            yield { type: "text", content: event.text };
+            break;
+          case "agent_thought_chunk":
+            yield { type: "thought", content: event.text };
+            break;
+          case "tool_call": {
+            const kind = event.kind ?? "other";
+            const title = event.title ?? "";
+            if (event.status === "in_progress" || event.status === "completed" || event.status === "failed") {
+              yield {
+                type: "tool",
+                content: title,
+                status: event.status,
+                toolCallId: event.toolCallId,
+                kind,
+                detail: summarizeRawInput(kind, title, event.rawInput)
+              };
+            }
+            break;
+          }
+          case "tool_call_update":
+            if (event.status === "completed" || event.status === "failed") {
+              yield {
+                type: "tool",
+                content: "",
+                status: event.status,
+                toolCallId: event.toolCallId
+              };
+            }
+            break;
+          case "plan":
+            yield { type: "plan", content: this.formatPlan(event.entries) };
+            break;
+          case "done": {
+            if (event.stopReason === "error" && this.isConnectionError(new Error(event.text))) {
+              throw new Error(event.text);
+            }
+            yield { type: "done", content: "", stopReason: event.stopReason };
+            break;
+          }
+        }
+      }
+      this.pool.touch(qualifier);
+    } catch (err) {
+      if (retriesLeft > 0 && this.isConnectionError(err)) {
+        chatRetryTotal.add(1, { result: "retry" });
+        this.opts.logger.warn(
+          `[cloudagent] \u8FDE\u63A5\u9519\u8BEF\uFF0C\u6062\u590D\u540E\u91CD\u8BD5: ${err instanceof Error ? err.message : String(err)}`
+        );
+        const { sessionId: newSessionId } = await this.pool.restore(qualifier);
+        yield* this.chatWithRetry(
+          { ...params, sessionId: newSessionId },
+          retriesLeft - 1
+        );
+      } else {
+        if (retriesLeft <= 0 && this.isConnectionError(err)) {
+          chatRetryTotal.add(1, { result: "exhausted" });
+        }
+        throw err;
+      }
+    }
+  }
+  isConnectionError(err) {
+    const msg = err instanceof Error ? err.message : String(err);
+    return msg.includes("agent not alive") || msg.includes("connection closed") || msg.includes("ACP connection closed") || msg.includes("Transport closed") || msg.includes("session not bound") || msg.includes("session not found") || msg.includes("session expired");
+  }
+  /** 取消当前 prompt */
+  cancel(qualifier) {
+    const entry = this.pool?.get(qualifier);
+    if (entry) {
+      entry.client.cancelPrompt(entry.sessionId);
+    }
+  }
+  /** 切换权限模式 */
+  async setMode(qualifier, mode) {
+    const entry = this.pool?.get(qualifier);
+    if (entry) {
+      await entry.client.setMode(entry.sessionId, mode);
+    }
+  }
+  /** 切换模型 */
+  async setModel(qualifier, modelId) {
+    const entry = this.pool?.get(qualifier);
+    if (entry) {
+      await entry.client.setModel(entry.sessionId, modelId);
+    }
+  }
+  async shutdown() {
+    if (this.pool) {
+      await this.pool.closeAll();
+      this.pool = null;
+    }
+  }
+  formatPlan(entries) {
+    if (!entries || entries.length === 0) return "";
+    return entries.map((e, i) => `${i + 1}. ${e.content ?? e.title ?? `step ${i + 1}`}`).join("\n");
+  }
+  buildPromptBlocks(_qualifier, text, attachments) {
+    const blocks = [];
+    if (text) {
+      blocks.push({ type: "text", text });
+    }
+    if (attachments) {
+      for (const att of attachments) {
+        blocks.push({
+          type: "resource_link",
+          uri: att.url,
+          name: att.name,
+          mimeType: att.mimeType,
+          ...att.size ? { size: att.size } : {}
+        });
+      }
+    }
+    if (blocks.length === 0) {
+      blocks.push({ type: "text", text: "(\u7A7A\u6D88\u606F)" });
+    }
+    return blocks;
+  }
+};
+function summarizeRawInput(kind, title, rawInput) {
+  if (!rawInput) return "";
+  switch (kind) {
+    case "search":
+      return str(rawInput.query ?? rawInput.pattern ?? rawInput.regex);
+    case "read":
+      return str(rawInput.filePath ?? rawInput.path ?? rawInput.file);
+    case "edit":
+    case "write":
+      return str(rawInput.filePath ?? rawInput.path ?? rawInput.file);
+    case "delete":
+      return str(rawInput.filePath ?? rawInput.path);
+    case "fetch":
+      return str(rawInput.url ?? rawInput.uri);
+    case "execute":
+      return str(rawInput.command ?? rawInput.cmd);
+    case "think":
+      return "";
+    default:
+      break;
+  }
+  const s = rawInput.skill ?? rawInput.command ?? rawInput.tool;
+  const args = rawInput.args ?? rawInput.arguments ?? rawInput.input;
+  if (s) {
+    return args ? truncate(`${s}: ${typeof args === "string" ? args : JSON.stringify(args)}`) : str(s);
+  }
+  for (const v of Object.values(rawInput)) {
+    if (typeof v === "string" && v.length > 0 && v.length < 120) {
+      return truncate(v);
+    }
+  }
+  return "";
+}
+function str(v) {
+  return typeof v === "string" ? truncate(v) : "";
+}
+function truncate(s) {
+  return s;
+}
+
+// src/mcp/server.ts
+import { McpServer as MCP } from "@modelcontextprotocol/sdk/server/mcp.js";
+import { StreamableHTTPServerTransport } from "@modelcontextprotocol/sdk/server/streamableHttp.js";
+import { SSEServerTransport } from "@modelcontextprotocol/sdk/server/sse.js";
+import { createServer } from "http";
+import { randomBytes } from "crypto";
+import { existsSync as existsSync2 } from "fs";
+import { stat } from "fs/promises";
+import { basename, join } from "path";
+import { URL as URL2 } from "url";
+import { z as z3 } from "zod";
+
+// src/mcp/openapi-tools.ts
+import { z as z2 } from "zod";
+function buildParamSchema(param) {
+  let schema;
+  switch (param.type) {
+    case "string":
+      schema = z2.string();
+      break;
+    case "number":
+      schema = z2.number();
+      break;
+    case "boolean":
+      schema = z2.boolean();
+      break;
+    case "string[]":
+      schema = z2.array(z2.string());
+      break;
+    case "number[]":
+      schema = z2.array(z2.number());
+      break;
+    default:
+      schema = z2.string();
+  }
+  schema = schema.describe(param.desc);
+  if (!param.required) {
+    schema = schema.optional();
+  }
+  return schema;
+}
+function buildInputSchema(params) {
+  const shape = {};
+  for (const param of params) {
+    shape[param.name] = buildParamSchema(param);
+  }
+  return shape;
+}
+function buildRequestBody(args, config) {
+  const body = { ...config.fixed_body };
+  const params = config.params ?? [];
+  const mapping = config.param_mapping ?? {};
+  for (const param of params) {
+    const value = args[param.name] ?? param.default;
+    if (value === void 0) continue;
+    const fieldName = mapping[param.name] ?? param.name;
+    body[fieldName] = value;
+  }
+  return body;
+}
+function buildOpenApiTools(config) {
+  const tools = {};
+  const globalTimeout = config.timeoutMs ?? 1e4;
+  for (const api of config.apis) {
+    const toolName = api.name;
+    const method = (api.method ?? "POST").toUpperCase();
+    tools[toolName] = {
+      description: api.desc,
+      inputSchema: buildInputSchema(api.params ?? []),
+      timeoutMs: globalTimeout,
+      handler: async (args, deps) => {
+        const { bot, logger } = deps;
+        const body = buildRequestBody(args, api);
+        logger.info(`[mcp/openapi] ${toolName} \u2192 ${method} ${api.path} body=${JSON.stringify(body)}`);
+        return withClientMetrics({
+          callerMethod: `mcp_${toolName}`,
+          calleeService: "qq-openapi",
+          calleeMethod: api.path
+        }, async () => {
+          switch (method) {
+            case "GET": {
+              const query = {};
+              for (const [k, v] of Object.entries(body)) {
+                if (v !== void 0 && v !== null && typeof v !== "object") {
+                  query[k] = v;
+                }
+              }
+              return bot.api.get(api.path, Object.keys(query).length > 0 ? query : void 0);
+            }
+            case "POST":
+              return bot.api.post(api.path, Object.keys(body).length > 0 ? body : void 0);
+            case "PUT":
+              return bot.api.put(api.path, Object.keys(body).length > 0 ? body : void 0);
+            case "PATCH":
+              return bot.api.patch(api.path, Object.keys(body).length > 0 ? body : void 0);
+            case "DELETE":
+              return bot.api.delete(api.path);
+            default:
+              throw new Error(`\u4E0D\u652F\u6301\u7684 HTTP \u65B9\u6CD5: ${method}`);
+          }
+        });
+      }
+    };
+  }
+  return tools;
+}
+
+// src/mcp/server.ts
+var MSG_ID_CACHE_SIZE = 10;
+var MSG_ID_TTL_MS = 60 * 60 * 1e3;
+var MSG_ID_MAX_TARGETS = 200;
+var MsgIdCache = class {
+  cache = /* @__PURE__ */ new Map();
+  /** 记录一条消息 ID（LRU：访问即提升到最新） */
+  push(targetKey, msgId) {
+    const existing = this.cache.get(targetKey);
+    if (existing) {
+      this.cache.delete(targetKey);
+      existing.push({ msgId, timestamp: Date.now() });
+      if (existing.length > MSG_ID_CACHE_SIZE) {
+        existing.shift();
+      }
+      this.cache.set(targetKey, existing);
+    } else {
+      this.cache.set(targetKey, [{ msgId, timestamp: Date.now() }]);
+      if (this.cache.size > MSG_ID_MAX_TARGETS) {
+        const oldest = this.cache.keys().next().value;
+        if (oldest) this.cache.delete(oldest);
+      }
+    }
+  }
+  /** 获取最近的有效 msgId（未过期），过期返回 undefined */
+  getLatest(targetKey) {
+    const list = this.cache.get(targetKey);
+    if (!list || list.length === 0) return void 0;
+    const now = Date.now();
+    for (let i = list.length - 1; i >= 0; i--) {
+      if (now - list[i].timestamp < MSG_ID_TTL_MS) {
+        return list[i].msgId;
+      }
+    }
+    return void 0;
+  }
+};
+var TOOLS = {
+  send_file: {
+    description: "\u5C06\u672C\u5730\u6587\u4EF6\u53D1\u9001\u7ED9 QQ \u7528\u6237\u6216\u7FA4\u3002\u652F\u6301\u56FE\u7247\u3001\u89C6\u9891\u3001\u8BED\u97F3\u548C\u901A\u7528\u6587\u4EF6\u3002",
+    inputSchema: {
+      file_path: z3.string().describe("\u672C\u5730\u6587\u4EF6\u7684\u7EDD\u5BF9\u8DEF\u5F84\uFF0C\u4F8B\u5982 /tmp/report.pdf"),
+      target: z3.string().describe("\u53D1\u9001\u76EE\u6807\uFF0C\u683C\u5F0F\u4E3A scope:openid\uFF0C\u4F8B\u5982 c2c:xxx \u6216 group:xxx")
+    },
+    timeoutMs: 12e4,
+    handler: async (args, deps) => {
+      const { bot, logger, pathPrefix, msgIdCache } = deps;
+      const resolvedPath = pathPrefix ? join(pathPrefix, args.file_path) : args.file_path;
+      const [scope, targetId] = args.target.split(":", 2);
+      if (!targetId || scope !== "c2c" && scope !== "group") {
+        throw new Error(`target \u683C\u5F0F\u9519\u8BEF\uFF0C\u9700\u8981 c2c:openid \u6216 group:openid\uFF0C\u6536\u5230: ${args.target}`);
+      }
+      const msgId = msgIdCache.getLatest(args.target);
+      const target = { scope, targetId, msgId };
+      logger.debug?.(`[mcp/send_file] target=${args.target} msgId=${msgId ?? "(\u4E3B\u52A8\u6D88\u606F)"}`);
+      if (!existsSync2(resolvedPath)) {
+        throw new Error(`\u6587\u4EF6\u4E0D\u5B58\u5728: ${resolvedPath}`);
+      }
+      const fileStat = await stat(resolvedPath);
+      if (!fileStat.isFile()) {
+        throw new Error(`\u8DEF\u5F84\u4E0D\u662F\u666E\u901A\u6587\u4EF6: ${resolvedPath}`);
+      }
+      const fileName = basename(resolvedPath);
+      const ext = resolvedPath.slice(resolvedPath.lastIndexOf(".")).toLowerCase();
+      const sendMethod = IMAGE_EXTS.has(ext) ? "image" : VIDEO_EXTS.has(ext) ? "video" : VOICE_EXTS.has(ext) ? "voice" : "file";
+      logger.info(
+        `[mcp/send_file] \u53D1\u9001${sendMethod}: ${fileName} (${fileStat.size} bytes) \u2192 ${target.scope}:${target.targetId}`
+      );
+      const source = { localPath: resolvedPath };
+      const result = await withClientMetrics({
+        callerMethod: "mcp_send_file",
+        calleeService: "qq-platform",
+        calleeMethod: `send${sendMethod.charAt(0).toUpperCase()}${sendMethod.slice(1)}`
+      }, async () => {
+        return sendMethod === "image" ? await bot.sendImage(target, source) : sendMethod === "video" ? await bot.sendVideo(target, source) : sendMethod === "voice" ? await bot.sendVoice(target, source) : await bot.sendFile(target, source, { fileName });
+      });
+      return {
+        success: true,
+        fileName,
+        fileSize: fileStat.size,
+        target: `${target.scope}:${target.targetId}`,
+        fileUuid: result.upload.file_uuid,
+        messageId: result.message?.id
+      };
+    }
+  }
+};
+var MCPServerHost = class {
+  http;
+  deps;
+  /** Streamable HTTP sessions: sessionId → transport */
+  sessions = /* @__PURE__ */ new Map();
+  /** Legacy SSE sessions: sessionId → transport */
+  sseSessions = /* @__PURE__ */ new Map();
+  /** 动态生成的 OpenAPI tools（从配置加载） */
+  dynamicTools = {};
+  port = 0;
+  host = "127.0.0.1";
+  async start(deps, listenPort = 0, listenHost = "127.0.0.1", openApiConfig) {
+    this.deps = deps;
+    this.host = listenHost;
+    if (openApiConfig?.apis?.length) {
+      this.dynamicTools = buildOpenApiTools(openApiConfig);
+      deps.logger.info(`[mcp] \u5DF2\u52A0\u8F7D ${Object.keys(this.dynamicTools).length} \u4E2A OpenAPI tools: ${Object.keys(this.dynamicTools).join(", ")}`);
+    }
+    this.http = createServer(async (req, res) => {
+      const url = new URL2(req.url ?? "/", `http://${req.headers.host ?? "localhost"}`);
+      const path2 = url.pathname;
+      try {
+        if (path2 === "/mcp") {
+          await this.handleStreamableHTTP(req, res);
+        } else if (path2 === "/sse") {
+          await this.handleSSEConnect(req, res);
+        } else if (path2 === "/messages") {
+          await this.handleSSEMessage(req, res);
+        } else {
+          res.writeHead(404).end("Not Found");
+        }
+      } catch (err) {
+        deps.logger.error(`[mcp] request error: ${err instanceof Error ? err.message : String(err)}`);
+        if (!res.headersSent) {
+          res.writeHead(500).end("Internal Server Error");
+        }
+      }
+    });
+    await new Promise(
+      (resolve2) => this.http.listen(listenPort, listenHost, () => resolve2())
+    );
+    this.port = this.http.address().port;
+    deps.logger.info(`[mcp] listening ${listenHost}:${this.port}`);
+  }
+  // ── Streamable HTTP：每个 initialize 创建新 session ──
+  async handleStreamableHTTP(req, res) {
+    const sessionId = req.headers["mcp-session-id"];
+    if (sessionId && this.sessions.has(sessionId)) {
+      const transport = this.sessions.get(sessionId);
+      await transport.handleRequest(req, res);
+      return;
+    }
+    if (req.method === "POST") {
+      const transport = new StreamableHTTPServerTransport({
+        sessionIdGenerator: () => randomBytes(16).toString("hex"),
+        onsessioninitialized: (id) => {
+          this.sessions.set(id, transport);
+          this.deps.logger.info(`[mcp] streamable session created: ${id}`);
+        }
+      });
+      transport.onclose = () => {
+        const id = transport.sessionId;
+        if (id) {
+          this.sessions.delete(id);
+          this.deps.logger.info(`[mcp] streamable session closed: ${id}`);
+        }
+      };
+      const mcp = this.createMcpServer();
+      await mcp.connect(transport);
+      await transport.handleRequest(req, res);
+      return;
+    }
+    res.writeHead(400, { "Content-Type": "application/json" });
+    res.end(JSON.stringify({
+      jsonrpc: "2.0",
+      error: { code: -32e3, message: "Bad Request: No valid session. Send an initialize request first." },
+      id: null
+    }));
+  }
+  // ── Legacy SSE：GET /sse 建立流，POST /messages 发消息 ──
+  async handleSSEConnect(req, res) {
+    if (req.method !== "GET") {
+      res.writeHead(405).end("Method Not Allowed");
+      return;
+    }
+    const transport = new SSEServerTransport("/messages", res);
+    const sessionId = transport.sessionId;
+    this.sseSessions.set(sessionId, transport);
+    this.deps.logger.info(`[mcp] SSE session created: ${sessionId}`);
+    transport.onclose = () => {
+      this.sseSessions.delete(sessionId);
+      this.deps.logger.info(`[mcp] SSE session closed: ${sessionId}`);
+    };
+    const mcp = this.createMcpServer();
+    await mcp.connect(transport);
+  }
+  async handleSSEMessage(req, res) {
+    if (req.method !== "POST") {
+      res.writeHead(405).end("Method Not Allowed");
+      return;
+    }
+    const url = new URL2(req.url ?? "/", `http://${req.headers.host ?? "localhost"}`);
+    const sessionId = url.searchParams.get("sessionId");
+    if (!sessionId || !this.sseSessions.has(sessionId)) {
+      res.writeHead(400).end("Invalid or missing sessionId");
+      return;
+    }
+    const transport = this.sseSessions.get(sessionId);
+    await transport.handlePostMessage(req, res);
+  }
+  // ── 创建带工具注册的 MCP Server 实例 ──
+  createMcpServer() {
+    const mcp = new MCP({ name: "qqbot-tools", version: "0.1.0" });
+    const allTools = { ...TOOLS, ...this.dynamicTools };
+    for (const [name, tool] of Object.entries(allTools)) {
+      const toolDeps = this.deps;
+      const toolDef = tool;
+      mcp.registerTool(
+        name,
+        {
+          description: tool.description,
+          inputSchema: tool.inputSchema
+        },
+        async (args) => {
+          const t0 = Date.now();
+          try {
+            const result = await withTimeout(
+              toolDef.handler(args, toolDeps),
+              toolDef.timeoutMs
+            );
+            toolDeps.logger.info(`[mcp] ${name} ok ${Date.now() - t0}ms`);
+            return {
+              content: [{ type: "text", text: JSON.stringify(result) }]
+            };
+          } catch (e) {
+            toolDeps.logger.error(`[mcp] ${name} fail ${Date.now() - t0}ms: ${e?.message ?? e}`);
+            return {
+              isError: true,
+              content: [{ type: "text", text: e?.message ?? String(e) }]
+            };
+          }
+        }
+      );
+    }
+    return mcp;
+  }
+  /** 给 ACP 用的 mcpServers 配置项 */
+  getAcpEntry() {
+    const callbackHost = this.host === "0.0.0.0" ? "127.0.0.1" : this.host;
+    return {
+      type: "http",
+      name: "qqbot-tools",
+      url: `http://${callbackHost}:${this.port}/mcp`,
+      headers: []
+    };
+  }
+  async stop() {
+    for (const transport of this.sessions.values()) {
+      await transport.close?.().catch(() => {
+      });
+    }
+    for (const transport of this.sseSessions.values()) {
+      await transport.close?.().catch(() => {
+      });
+    }
+    this.sessions.clear();
+    this.sseSessions.clear();
+    await new Promise(
+      (resolve2) => this.http?.close(() => resolve2()) ?? resolve2()
+    );
+  }
+};
+function withTimeout(p, ms) {
+  return new Promise((resolve2, reject) => {
+    const timer = setTimeout(() => reject(new Error(`timeout ${ms}ms`)), ms);
+    p.then(
+      (v) => {
+        clearTimeout(timer);
+        resolve2(v);
+      },
+      (e) => {
+        clearTimeout(timer);
+        reject(e);
+      }
+    );
+  });
+}
+var IMAGE_EXTS = /* @__PURE__ */ new Set([".jpg", ".jpeg", ".png", ".gif", ".webp", ".bmp"]);
+var VIDEO_EXTS = /* @__PURE__ */ new Set([".mp4", ".mov", ".avi", ".mkv", ".webm"]);
+var VOICE_EXTS = /* @__PURE__ */ new Set([".mp3", ".wav", ".ogg", ".aac", ".silk", ".amr"]);
+
+// src/slash/index.ts
+import {
+  slashCommand
+} from "@tencent/qqbot-nodejs";
+function createSlashMiddleware(opts) {
+  const slash = slashCommand({
+    prefixes: opts.prefixes,
+    autoHelp: false,
+    allowFrom: opts.allowFrom
+  });
+  for (const cmd of buildCommands(opts.ctx, slash.list)) {
+    const originalHandler = cmd.handler;
+    cmd.handler = (ctx) => {
+      slashCommandTotal.add(1, { command: cmd.name });
+      return originalHandler(ctx);
+    };
+    slash.register(cmd);
+  }
+  return slash.middleware;
+}
+var DISPLAY_PRESETS = ["full", "compact", "minimal", "text-only"];
+function buildCommands(ctx, listCommands) {
+  return [
+    {
+      name: "bot-help",
+      description: "QQ Bot \u5E2E\u52A9\u6307\u4EE4",
+      scope: "c2c",
+      usage: [
+        `/bot-help`,
+        ``,
+        `\u67E5\u770B\u6240\u6709\u53EF\u7528\u7684\u5185\u7F6E\u547D\u4EE4\u53CA\u5176\u7B80\u8981\u8BF4\u660E\u3002`
+      ].join("\n"),
+      handler: ({ message }) => {
+        const msgKind = message.kind;
+        const isC2C = msgKind === "c2c";
+        const isGroup = msgKind === "group";
+        const lines = [`### \u{1F916} QQ Bot \u5E2E\u52A9\u6307\u4EE4`, ``];
+        for (const cmd of listCommands()) {
+          if (cmd.hidden) continue;
+          const cmdScope = cmd.scope ?? "all";
+          if (cmdScope === "c2c" && !isC2C) continue;
+          if (cmdScope === "group" && !isGroup) continue;
+          const name = Array.isArray(cmd.name) ? cmd.name[0] : cmd.name;
+          const desc = cmd.description ?? "";
+          lines.push(`<qqbot-cmd-input text="/${name}" show="/${name}"/> ${desc}`);
+        }
+        return lines.join("\n");
+      }
+    },
+    {
+      name: "bot-me",
+      description: "\u67E5\u770B\u5F53\u524D\u7528\u6237\u7684 OpenID",
+      scope: "c2c",
+      usage: [
+        `/bot-me`,
+        ``,
+        `\u663E\u793A\u5F53\u524D\u7528\u6237\u7684 OpenID\u3002`
+      ].join("\n"),
+      handler: ({ message }) => {
+        const lines = [`\u{1F464} **${message.senderId}**`];
+        if (message.groupOpenid) {
+          lines.push(`\u{1F465} \u7FA4: **${message.groupOpenid}**`);
+        }
+        return lines.join("\n");
+      }
+    },
+    {
+      name: "bot-ping",
+      description: "\u6D4B\u8BD5 Agent \u670D\u52A1\u4E0E QQ \u95F4\u7F51\u7EDC\u5EF6\u8FDF",
+      scope: "c2c",
+      usage: [
+        `/bot-ping`,
+        ``,
+        `\u6D4B\u8BD5 Agent \u670D\u52A1\u4E0E QQ \u670D\u52A1\u5668\u4E4B\u95F4\u7684\u7F51\u7EDC\u5EF6\u8FDF\u3002`,
+        `\u8FD4\u56DE\u7F51\u7EDC\u4F20\u8F93\u8017\u65F6\u548C\u5904\u7406\u8017\u65F6\u3002`
+      ].join("\n"),
+      handler: (ctx2) => {
+        const now = Date.now();
+        const eventTime = new Date(ctx2.message.timestamp).getTime();
+        if (Number.isNaN(eventTime)) {
+          return `\u2705 pong!`;
+        }
+        const totalMs = now - eventTime;
+        const qqToSdk = ctx2.receivedAt - eventTime;
+        const sdkProcess = now - ctx2.receivedAt;
+        return [
+          `\u2705 pong!`,
+          ``,
+          `\u23F1 \u5EF6\u8FDF\uFF1A${totalMs}ms`,
+          `  \u251C \u7F51\u7EDC\u4F20\u8F93\uFF1A${qqToSdk}ms`,
+          `  \u2514 \u5904\u7406\u8017\u65F6\uFF1A${sdkProcess}ms`
+        ].join("\n");
+      }
+    },
+    {
+      name: "bot-msg-mode",
+      description: "\u5207\u6362\u6D88\u606F\u5C55\u793A\u6A21\u5F0F",
+      scope: "c2c",
+      usage: [
+        `/bot-msg-mode <mode>   \u5207\u6362\u5C55\u793A\u6A21\u5F0F`,
+        `/bot-msg-mode          \u67E5\u770B\u5F53\u524D\u6A21\u5F0F`,
+        ``,
+        `\u53EF\u9009\u6A21\u5F0F: ${DISPLAY_PRESETS.join(" | ")}`
+      ].join("\n"),
+      handler: ({ command }) => {
+        const preset = command.args[0];
+        if (!preset) {
+          const cur = ctx.getConfig().message.display.preset;
+          return [
+            `\u5F53\u524D\u6A21\u5F0F\uFF1A**${cur}**`,
+            ``,
+            `<qqbot-cmd-input text="/bot-msg-mode full" show="full"/> \u{1F50D} \u8BE6\u7EC6\u6A21\u5F0F \u2014 \u5C55\u793A AI \u7684\u6BCF\u4E00\u6B65\u601D\u8003\u548C\u64CD\u4F5C\u8FC7\u7A0B`,
+            `<qqbot-cmd-input text="/bot-msg-mode compact" show="compact"/> \u{1F4CB} \u666E\u901A\u6A21\u5F0F \u2014 \u53EA\u5C55\u793A\u5173\u952E\u64CD\u4F5C\u548C\u7ED3\u679C`,
+            `<qqbot-cmd-input text="/bot-msg-mode minimal" show="minimal"/> \u{1F4AC} \u7B80\u6D01\u6A21\u5F0F \u2014 \u53EA\u663E\u793A\u64CD\u4F5C\u540D\u79F0\uFF0C\u5185\u5BB9\u6298\u53E0`,
+            `<qqbot-cmd-input text="/bot-msg-mode text-only" show="text-only"/> \u2728 \u7EAF\u51C0\u6A21\u5F0F \u2014 \u53EA\u770B\u5BF9\u8BDD\uFF0C\u9690\u85CF\u6240\u6709\u8FC7\u7A0B`
+          ].join("\n");
+        }
+        if (!DISPLAY_PRESETS.includes(preset)) {
+          return [
+            `\u274C \u65E0\u6548\u7684\u6A21\u5F0F: ${preset}`,
+            ``,
+            `\u53EF\u9009: ${DISPLAY_PRESETS.join(" | ")}`
+          ].join("\n");
+        }
+        ctx.updateConfig({ display: expandDisplayPreset(preset) });
+        return `\u2705 \u5DF2\u5207\u6362\u4E3A **${preset}** \u6A21\u5F0F`;
+      }
+    },
+    {
+      name: "bot-streaming",
+      description: "\u5F00\u5173\u6D41\u5F0F\u6D88\u606F",
+      scope: "c2c",
+      usage: [
+        `/bot-streaming on     \u5F00\u542F\u6D41\u5F0F\u6D88\u606F`,
+        `/bot-streaming off    \u5173\u95ED\u6D41\u5F0F\u6D88\u606F`,
+        `/bot-streaming        \u67E5\u770B\u5F53\u524D\u72B6\u6001`,
+        ``,
+        `\u5F00\u542F\u540E\uFF0CAI \u56DE\u590D\u4EE5\u6D41\u5F0F\u5F62\u5F0F\u9010\u6B65\u663E\u793A\u3002`
+      ].join("\n"),
+      handler: ({ command }) => {
+        const val = command.args[0];
+        const currentOn = ctx.getConfig().streaming.c2c;
+        if (!val) {
+          return [
+            `\u{1F4E1} \u6D41\u5F0F\u6D88\u606F\u72B6\u6001\uFF1A${currentOn ? "\u2705 \u5DF2\u5F00\u542F" : "\u274C \u5DF2\u5173\u95ED"}`,
+            ``,
+            `<qqbot-cmd-input text="/bot-streaming on" show="on"/> \u5F00\u542F`,
+            `<qqbot-cmd-input text="/bot-streaming off" show="off"/> \u5173\u95ED`
+          ].join("\n");
+        }
+        if (val !== "on" && val !== "off") {
+          return [
+            `\u274C \u53C2\u6570\u9519\u8BEF\uFF0C\u8BF7\u4F7F\u7528 on \u6216 off`,
+            ``,
+            `\u793A\u4F8B\uFF1A/bot-streaming on`
+          ].join("\n");
+        }
+        const wantOn = val === "on";
+        if (wantOn === currentOn) {
+          return `\u{1F4E1} \u6D41\u5F0F\u6D88\u606F\u5DF2\u7ECF\u662F${wantOn ? "\u5F00\u542F" : "\u5173\u95ED"}\u72B6\u6001\uFF0C\u65E0\u9700\u64CD\u4F5C`;
+        }
+        ctx.updateConfig({ streamingC2c: wantOn });
+        return [
+          `\u2705 \u6D41\u5F0F\u6D88\u606F\u5DF2${wantOn ? "\u5F00\u542F" : "\u5173\u95ED"}`,
+          ``,
+          wantOn ? `AI \u7684\u56DE\u590D\u5C06\u4EE5\u6D41\u5F0F\u5F62\u5F0F\u9010\u6B65\u663E\u793A\u3002` : `AI \u7684\u56DE\u590D\u5C06\u6062\u590D\u4E3A\u5B8C\u6574\u53D1\u9001\u3002`
+        ].join("\n");
+      }
+    },
+    {
+      name: "bot-config",
+      description: "\u67E5\u770B\u5F53\u524D\u8FD0\u884C\u914D\u7F6E",
+      scope: "c2c",
+      usage: [
+        `/bot-config`,
+        ``,
+        `\u67E5\u770B\u5F53\u524D\u8FD0\u884C\u65F6\u7684\u5173\u952E\u914D\u7F6E\u9879\u3002`
+      ].join("\n"),
+      handler: () => {
+        const c = ctx.getConfig();
+        const presetLabels = {
+          full: "\u8BE6\u7EC6\u6A21\u5F0F",
+          compact: "\u666E\u901A\u6A21\u5F0F",
+          minimal: "\u7B80\u6D01\u6A21\u5F0F",
+          "text-only": "\u7EAF\u51C0\u6A21\u5F0F"
+        };
+        const presetLabel = `${presetLabels[c.message.display.preset] ?? c.message.display.preset} (${c.message.display.preset})`;
+        return [
+          `### \u2699\uFE0F \u5F53\u524D\u8FD0\u884C\u914D\u7F6E`,
+          ``,
+          `| \u914D\u7F6E\u9879 | \u503C |`,
+          `| --- | --- |`,
+          `| \u6D88\u606F\u6A21\u5F0F | ${presetLabel} |`,
+          `| \u6D41\u5F0F\u6D88\u606F | ${c.streaming.c2c ? "\u2705 \u5F00\u542F" : "\u274C \u5173\u95ED"} |`
+        ].join("\n");
+      }
+    }
+  ];
+}
+
+// src/envelope.ts
+function formatQQBotEnvelope(ctx) {
+  const parts = [];
+  const msg = ctx.message;
+  const content = (msg.content ?? "").trim();
+  const isCommand = content.startsWith("/");
+  if (!isCommand) {
+    if (msg.kind === "group") {
+      parts.push(`<routing target="group:${msg.groupOpenid ?? ""}" />`);
+    } else {
+      parts.push(`<routing target="c2c:${msg.senderId}" />`);
+    }
+  }
+  const quote = ctx.state.quote;
+  if (quote?.text) {
+    parts.push(`[\u5F15\u7528] ${quote.text}`);
+  }
+  if (msg.kind === "group" && !isCommand) {
+    const sender = msg.senderName || msg.senderId;
+    parts.push(`<sender name="${sender}" />`);
+  }
+  if (content) {
+    parts.push(content);
+  }
+  if (msg.attachments && msg.attachments.length > 0) {
+    for (const att of msg.attachments) {
+      if (att.asr_refer_text) {
+        parts.push(`[\u8BED\u97F3\u8F6C\u6587\u5B57] ${att.asr_refer_text}`);
+      } else {
+        const name = att.filename ?? att.content_type ?? "file";
+        parts.push(`[\u9644\u4EF6] ${name}`);
+      }
+    }
+  }
+  if (msg.kind === "group") {
+    const mentioned = Array.isArray(msg.mentions) && msg.mentions.some((m) => m?.is_you === true);
+    if (mentioned) {
+      parts.push("(@you)");
+    }
+  }
+  return parts.join("\n");
+}
+
+// src/display.ts
+var TOOL_EMOJI = {
+  search: "\u{1F50D}",
+  fetch: "\u{1F310}",
+  execute: "\u26A1",
+  read: "\u{1F4D6}",
+  edit: "\u270F\uFE0F",
+  think: "\u{1F4AD}",
+  delete: "\u{1F5D1}\uFE0F",
+  other: "\u{1F527}"
+};
+var TITLE_EMOJI = [
+  ["skill", "\u{1F9E9}"],
+  ["mcp", "\u{1F50C}"],
+  ["bash", "\u26A1"],
+  ["terminal", "\u26A1"],
+  ["shell", "\u26A1"],
+  ["browser", "\u{1F310}"],
+  ["web", "\u{1F310}"],
+  ["file", "\u{1F4C4}"],
+  ["write", "\u270F\uFE0F"],
+  ["create", "\u270F\uFE0F"],
+  ["list", "\u{1F4CB}"],
+  ["analyze", "\u{1F52C}"],
+  ["deploy", "\u{1F680}"],
+  ["install", "\u{1F4E6}"],
+  ["test", "\u{1F9EA}"],
+  ["git", "\u{1F4CC}"],
+  ["image", "\u{1F5BC}\uFE0F"],
+  ["upload", "\u{1F4E4}"],
+  ["download", "\u{1F4E5}"],
+  ["database", "\u{1F5C4}\uFE0F"],
+  ["sql", "\u{1F5C4}\uFE0F"],
+  ["api", "\u{1F50C}"]
+];
+function resolveEmoji(kind, title) {
+  if (kind !== "other" || !title) return TOOL_EMOJI[kind] ?? "\u{1F527}";
+  const lower = title.toLowerCase();
+  for (const [prefix, emoji] of TITLE_EMOJI) {
+    if (lower.startsWith(prefix) || lower.includes(prefix)) return emoji;
+  }
+  return "\u{1F527}";
+}
+function extractUrl(title) {
+  const match = title.match(/https?:\/\/\S+/);
+  return match?.[0];
+}
+function shortenUrl(url) {
+  try {
+    const parsed = new URL(url);
+    const host = parsed.hostname.replace(/^www\./, "");
+    const pathname = parsed.pathname;
+    if (pathname.length <= 1 && !parsed.search) {
+      return host;
+    }
+    const shortPath = pathname.length > 20 ? `${pathname.slice(0, 20)}\u2026` : pathname;
+    return `${host}${shortPath}`;
+  } catch {
+    return url.length > 40 ? `${url.slice(0, 40)}\u2026` : url;
+  }
+}
+function formatTool(display, kind, title, detail) {
+  const parts = [];
+  const k = kind ?? "other";
+  if (display.toolEmoji) {
+    parts.push(resolveEmoji(k, title));
+  }
+  if (display.toolKind) {
+    const label = k === "other" && title ? title : k.charAt(0).toUpperCase() + k.slice(1);
+    parts.push(label);
+  }
+  if (display.toolTitle && title) {
+    if (k === "execute" && detail) {
+      const shouldTruncate = display.toolDetailTruncate?.includes(k);
+      const maxLen = shouldTruncate ? display.toolDetailMaxLength ?? 120 : 0;
+      const cmd = truncateDetail(detail, maxLen);
+      const header = parts.join(" ");
+      return `${header}
+\`\`\`
+${cmd}
+\`\`\``;
+    }
+    if (k === "fetch") {
+      const url = extractUrl(title);
+      if (url) {
+        parts.push(`[${shortenUrl(url)}](${url})`);
+        return parts.join(" ");
+      }
+    }
+    const labelUsed = k === "other" && display.toolKind;
+    if (!labelUsed) {
+      const t = title.toLowerCase().startsWith(k.toLowerCase()) ? display.toolKind ? title.slice(k.length).trim() : title : title;
+      if (t) parts.push(t);
+    }
+  }
+  if (display.toolTitle && detail && detail.trim()) {
+    const titleLower = (title ?? "").toLowerCase().trim();
+    const detailLower = detail.toLowerCase().trim();
+    const titleNorm = titleLower.replace(/["""''`]/g, "").trim();
+    const detailNorm = detailLower.replace(/["""''`]/g, "").trim();
+    const isRedundant = titleNorm === detailNorm || titleNorm.includes(detailNorm) || detailNorm.includes(titleNorm);
+    if (!isRedundant) {
+      const shouldTruncate = display.toolDetailTruncate?.includes(k);
+      const maxLen = shouldTruncate ? display.toolDetailMaxLength ?? 120 : 0;
+      const truncated = truncateDetail(detail, maxLen);
+      parts.push(`\`${truncated}\``);
+    }
+  }
+  return parts.join(" ");
+}
+function truncateDetail(detail, maxLen) {
+  if (maxLen <= 0 || detail.length <= maxLen) return detail;
+  return `${detail.slice(0, maxLen - 1)}\u2026`;
+}
+
+// src/reply.ts
+async function streamReply(rctx, ctx, msg, sessionId, qualifier, text, attachments) {
+  const { bot, backend, config, logger } = rctx;
+  const emptyReplyMsg = config.message.errorMessages.emptyReply;
+  const stream = bot.openStream({
+    target: msg.replyTarget,
+    throttleMs: config.streaming.throttleMs
+  });
+  let replyText = "";
+  const seenTools = /* @__PURE__ */ new Set();
+  let planShown = false;
+  let chunkCount = 0;
+  const display = config.message.display;
+  const scopeType = msg.replyTarget.scope.startsWith("group") ? "group" : "c2c";
+  try {
+    for await (const chunk of backend.chat({ sessionId, qualifier, text, attachments })) {
+      if (ctx.signal.aborted) {
+        logger.debug(`[stream] ${qualifier} aborted, stopping`);
+        backend.cancel?.(qualifier);
+        stream.cancel();
+        return;
+      }
+      switch (chunk.type) {
+        case "text":
+          chunkCount++;
+          replyText += chunk.content;
+          await stream.update(replyText);
+          break;
+        case "thought":
+          if (display.thought) {
+            replyText += chunk.content;
+            await stream.update(replyText);
+          }
+          break;
+        case "tool": {
+          if (!display.tool) break;
+          const tid = chunk.toolCallId ?? chunk.content;
+          if (chunk.status === "in_progress" && !seenTools.has(tid)) {
+            seenTools.add(tid);
+            replyText += `
+${formatTool(display, chunk.kind, chunk.content, chunk.detail)}
+`;
+            await stream.update(replyText);
+          }
+          break;
+        }
+        case "plan":
+          if (display.plan && !planShown && chunk.content) {
+            planShown = true;
+            replyText += `
+\u{1F4CB} \u6267\u884C\u8BA1\u5212\uFF1A
+${chunk.content}
+`;
+            await stream.update(replyText);
+          }
+          break;
+        case "done": {
+          const stopReason = chunk.stopReason ?? "end_turn";
+          if (stopReason !== "end_turn" && stopReason !== "cancelled") {
+            if (replyText) {
+              replyChunksTotal.add(chunkCount, { scope: scopeType });
+              replyLength.record(replyText.length, { scope: scopeType });
+              await stream.complete();
+              logger.info(`[stream] ${qualifier} \u5B8C\u6210(${stopReason}) (len=${replyText.length})`);
+              return;
+            }
+            stream.cancel();
+            throw new Error(`[${stopReason}] ${chunk.content || ""}`);
+          }
+          replyChunksTotal.add(chunkCount, { scope: scopeType });
+          if (replyText) {
+            replyLength.record(replyText.length, { scope: scopeType });
+            await stream.complete();
+          } else {
+            replyEmptyTotal.add(1, { scope: scopeType });
+            stream.cancel();
+            await bot.sendText(msg.replyTarget, emptyReplyMsg);
+          }
+          logger.info(`[stream] ${qualifier} \u5B8C\u6210 (len=${replyText.length})`);
+          return;
+        }
+      }
+    }
+    if (!ctx.signal.aborted) {
+      replyChunksTotal.add(chunkCount, { scope: scopeType });
+      if (replyText) {
+        replyLength.record(replyText.length, { scope: scopeType });
+        await stream.complete();
+      } else {
+        replyEmptyTotal.add(1, { scope: scopeType });
+        stream.cancel();
+        await bot.sendText(msg.replyTarget, emptyReplyMsg);
+      }
+      logger.info(`[stream] ${qualifier} \u5B8C\u6210 (len=${replyText.length})`);
+    } else {
+      backend.cancel?.(qualifier);
+      stream.cancel();
+      logger.debug(`[stream] ${qualifier} aborted after loop`);
+    }
+  } catch (err) {
+    stream.cancel();
+    if (replyText && !ctx.signal.aborted) {
+      replyFallbackTotal.add(1, { scope: scopeType });
+      await bot.sendText(msg.replyTarget, replyText);
+    }
+    throw err;
+  }
+}
+async function batchReply(rctx, ctx, msg, sessionId, qualifier, text, attachments) {
+  const { bot, backend, config, logger } = rctx;
+  const emptyReplyMsg = config.message.errorMessages.emptyReply;
+  let replyText = "";
+  const seenTools = /* @__PURE__ */ new Set();
+  let planShown = false;
+  let chunkCount = 0;
+  const display = config.message.display;
+  const scopeType = msg.replyTarget.scope.startsWith("group") ? "group" : "c2c";
+  for await (const chunk of backend.chat({ sessionId, qualifier, text, attachments })) {
+    if (ctx.signal.aborted) {
+      logger.debug(`[batch] ${qualifier} aborted, stopping`);
+      backend.cancel?.(qualifier);
+      return;
+    }
+    switch (chunk.type) {
+      case "text":
+        chunkCount++;
+        replyText += chunk.content;
+        break;
+      case "thought":
+        if (display.thought) {
+          replyText += chunk.content;
+        }
+        break;
+      case "tool": {
+        if (!display.tool) break;
+        const tid = chunk.toolCallId ?? chunk.content;
+        if (chunk.status === "in_progress" && !seenTools.has(tid)) {
+          seenTools.add(tid);
+          replyText += `
+${formatTool(display, chunk.kind, chunk.content, chunk.detail)}
+`;
+        }
+        break;
+      }
+      case "plan":
+        if (display.plan && !planShown && chunk.content) {
+          planShown = true;
+          replyText += `
+\u{1F4CB} \u6267\u884C\u8BA1\u5212\uFF1A
+${chunk.content}
+`;
+        }
+        break;
+      case "done": {
+        const stopReason = chunk.stopReason ?? "end_turn";
+        if (stopReason !== "end_turn" && stopReason !== "cancelled") {
+          if (replyText) break;
+          throw new Error(`[${stopReason}] ${chunk.content || ""}`);
+        }
+        break;
+      }
+    }
+  }
+  if (ctx.signal.aborted) {
+    backend.cancel?.(qualifier);
+    logger.debug(`[batch] ${qualifier} aborted after loop`);
+    return;
+  }
+  const reply = replyText.trim() || emptyReplyMsg;
+  replyChunksTotal.add(chunkCount, { scope: scopeType });
+  if (!replyText.trim()) {
+    replyEmptyTotal.add(1, { scope: scopeType });
+  } else {
+    replyLength.record(reply.length, { scope: scopeType });
+  }
+  await bot.sendText(msg.replyTarget, reply);
+  logger.info(`[batch] ${qualifier} \u53D1\u9001 (len=${reply.length})`);
+}
+
+// src/telemetry/middleware.ts
+import { trace as trace3, SpanStatusCode as SpanStatusCode3 } from "@opentelemetry/api";
+var tracer3 = trace3.getTracer("qqbot-cli");
+function telemetryMiddleware(opts) {
+  return async (ctx, next) => {
+    const msg = ctx.message;
+    const scope = msg.replyTarget.scope;
+    const kind = msg.kind ?? "unknown";
+    const scopeType = scope.startsWith("group") ? "group" : "c2c";
+    const attrs = {
+      [METRIC_ATTRS.CALLER_SERVICE]: "qq-platform",
+      [METRIC_ATTRS.CALLER_METHOD]: kind,
+      [METRIC_ATTRS.CALLER_SERVER]: "qq-platform",
+      [METRIC_ATTRS.CALLEE_SERVICE]: "qqbot-cli",
+      [METRIC_ATTRS.CALLEE_METHOD]: "handleMessage",
+      [METRIC_ATTRS.CALLEE_SERVER]: "qqbot-cli",
+      [METRIC_ATTRS.USER_EXT1]: scopeType
+    };
+    const startTime = Date.now();
+    await tracer3.startActiveSpan(
+      "message",
+      {
+        attributes: {
+          "bot.app_id": opts.appId,
+          "msg.kind": kind,
+          "msg.scope": scope,
+          "msg.sender": msg.senderId ?? "",
+          "msg.content.length": (msg.content ?? "").length
+        }
+      },
+      async (span) => {
+        let hasError = false;
+        try {
+          await next();
+          span.setStatus({ code: SpanStatusCode3.OK });
+        } catch (err) {
+          hasError = true;
+          span.setStatus({
+            code: SpanStatusCode3.ERROR,
+            message: err instanceof Error ? err.message : String(err)
+          });
+          span.recordException(err instanceof Error ? err : new Error(String(err)));
+          throw err;
+        } finally {
+          span.end();
+          const handleType = ctx.state.handled ? "handled" : "buffered";
+          const baseAttrs = {
+            ...attrs,
+            [METRIC_ATTRS.USER_EXT2]: handleType
+          };
+          serverStartedTotal.add(1, { ...baseAttrs, [METRIC_ATTRS.CODE]: 0, [METRIC_ATTRS.CODE_TYPE]: "success" });
+          const resultAttrs = { ...baseAttrs, [METRIC_ATTRS.CODE]: hasError ? 1 : 0, [METRIC_ATTRS.CODE_TYPE]: hasError ? "error" : "success" };
+          serverHandledTotal.add(1, resultAttrs);
+          serverHandledSeconds.record((Date.now() - startTime) / 1e3, resultAttrs);
+        }
+      }
+    );
+  };
+}
+
+// src/runner.ts
+var require2 = createRequire(import.meta.url);
+var { version: CLI_VERSION } = require2("../package.json");
+var BotRunner = class {
+  bot;
+  backend;
+  config;
+  logger;
+  mcpHost;
+  msgIdCache = new MsgIdCache();
+  /** 写回配置文件的回调，由外部（cli.ts）注入 */
+  configWriter;
+  constructor(config, logger) {
+    this.config = config;
+    this.logger = logger;
+    this.bot = new QQBot({
+      appId: config.qq.appId,
+      appSecret: config.qq.appSecret,
+      markdownSupport: config.qq.markdown,
+      baseUrl: config.qq.baseUrl,
+      tokenBaseUrl: config.qq.tokenBaseUrl,
+      tokenPrefetch: config.qq.tokenPrefetch,
+      userAgent: `${config.qq.userAgent ?? `qqbot-cli/${CLI_VERSION}`} (Node/${process.versions.node})`,
+      transport: config.qq.transport,
+      ...config.qq.transport === "webhook" ? {
+        webhook: {
+          port: config.qq.webhook.port,
+          path: config.qq.webhook.path
+        }
+      } : {},
+      logger
+    });
+    this.backend = this.createBackend(config);
+    this.setupMiddleware(config);
+    this.bot.on("ready", () => {
+      logger.info("\u{1F7E2} Bot online");
+    });
+    this.bot.on("resumed", () => {
+      logger.info("\u{1F7E2} Bot resumed");
+    });
+    this.bot.on("error", (err) => {
+      logger.error(`\u{1F534} ${err.message}`);
+    });
+    this.bot.on("message", (ctx, msg) => this.handleMessage(ctx, msg));
+  }
+  // ============ 生命周期 ============
+  async start(signal) {
+    const mcpServers = [];
+    if (this.config.mcp.enabled) {
+      this.mcpHost = new MCPServerHost();
+      await this.mcpHost.start(
+        {
+          logger: this.logger,
+          bot: this.bot,
+          pathPrefix: this.config.mcp.pathPrefix,
+          msgIdCache: this.msgIdCache
+        },
+        this.config.mcp.port,
+        this.config.mcp.host,
+        this.config.openapi
+      );
+      mcpServers.push(this.mcpHost.getAcpEntry());
+      this.logger.info(`[runner] MCP Server \u5DF2\u542F\u52A8 (${this.config.mcp.host}:${this.mcpHost.port})`);
+    }
+    const cloudagentCfg = this.config.backend.cloudagent;
+    if (cloudagentCfg?.mcpServers) {
+      for (const srv of cloudagentCfg.mcpServers) {
+        const headers = Object.entries(srv.headers).map(([name, value]) => ({ name, value }));
+        mcpServers.push({ type: srv.type, name: srv.name, url: srv.url, headers });
+      }
+    }
+    if (mcpServers.length > 0 && this.backend instanceof CloudAgentBackend) {
+      this.backend.opts.extraMcpServers = mcpServers;
+      this.logger.info(`[runner] MCP Servers: ${mcpServers.map((s) => s.name).join(", ")}`);
+    }
+    this.logger.info(`[runner] \u521D\u59CB\u5316\u540E\u7AEF: ${this.backend.name}`);
+    await this.backend.init();
+    const transport = this.config.qq.transport;
+    if (transport === "webhook") {
+      this.logger.info(`[runner] \u540E\u7AEF\u5C31\u7EEA\uFF0C\u542F\u52A8 Webhook \u670D\u52A1 (port=${this.config.qq.webhook.port}, path=${this.config.qq.webhook.path})...`);
+    } else {
+      this.logger.info(`[runner] \u540E\u7AEF\u5C31\u7EEA\uFF0C\u542F\u52A8 QQ WebSocket...`);
+    }
+    await this.bot.start(signal);
+  }
+  async stop() {
+    this.bot.stop();
+    await this.backend.shutdown();
+    await this.mcpHost?.stop().catch(() => {
+    });
+    this.logger.info(`[runner] \u5DF2\u505C\u6B62`);
+  }
+  // ============ 配置管理 ============
+  /** 注入配置文件写回能力（由 cli.ts 在创建 ConfigWatcher 后调用） */
+  setConfigWriter(writer) {
+    this.configWriter = writer;
+  }
+  /**
+   * 热更新配置。校验通过后立即生效的字段：
+   *   - middleware（mentionGate/rateLimiter/concurrency/typingIndicator 等）
+   *   - message.display（展示样式）
+   *   - streaming.throttleMs
+   *   - log.level
+   *   - backend.cloudagent.acp.eventTimeoutMs
+   *   - backend.cloudagent.manifest.systemPrompt
+   *
+   * 需要重启才能生效的字段（仅日志提示）：
+   *   - qq.appId/appSecret/transport
+   *   - backend.type
+   *   - backend.cloudagent.sandbox
+   */
+  applyConfigUpdate(newConfig) {
+    const old = this.config;
+    const restartNeeded = [];
+    if (old.qq.appId !== newConfig.qq.appId) restartNeeded.push("qq.appId");
+    if (old.qq.appSecret !== newConfig.qq.appSecret) restartNeeded.push("qq.appSecret");
+    if (old.qq.transport !== newConfig.qq.transport) restartNeeded.push("qq.transport");
+    if (old.backend.type !== newConfig.backend.type) restartNeeded.push("backend.type");
+    if (JSON.stringify(old.backend.cloudagent?.sandbox) !== JSON.stringify(newConfig.backend.cloudagent?.sandbox)) {
+      restartNeeded.push("backend.cloudagent.sandbox");
+    }
+    if (restartNeeded.length > 0) {
+      this.logger.warn(
+        `[config] \u4EE5\u4E0B\u914D\u7F6E\u53D8\u66F4\u9700\u8981\u91CD\u542F\u624D\u80FD\u751F\u6548: ${restartNeeded.join(", ")}`
+      );
+    }
+    this.config = newConfig;
+    if (old.log.level !== newConfig.log.level) {
+      this.logger.info(`[config] log.level: ${old.log.level} \u2192 ${newConfig.log.level}`);
+    }
+    this.logger.info("[config] hot reload applied");
+  }
+  /**
+   * 通过斜杠指令部分更新配置。
+   * 同时写回配置文件（如果 configWriter 已注入）。
+   */
+  applyConfigPatch(patch) {
+    const c = this.config;
+    const filePatches = {};
+    if (patch.display) {
+      c.message.display = patch.display;
+      filePatches["message.display.preset"] = patch.display.preset;
+      this.logger.info(`[config] display \u2192 ${patch.display.preset} (tool=${patch.display.tool}, thought=${patch.display.thought}, plan=${patch.display.plan})`);
+      this.logger.debug(`[config] display verify: preset=${this.config.message.display.preset} thought=${this.config.message.display.thought}`);
+    }
+    if (patch.logLevel) {
+      c.log.level = patch.logLevel;
+      filePatches["log.level"] = patch.logLevel;
+      this.logger.info(`[config] log.level \u2192 ${patch.logLevel}`);
+    }
+    if (patch.streamingC2c !== void 0) {
+      c.streaming.c2c = patch.streamingC2c;
+      filePatches["streaming.c2c"] = patch.streamingC2c;
+      this.logger.info(`[config] streaming.c2c \u2192 ${patch.streamingC2c}`);
+    }
+    if (patch.streamingThrottleMs !== void 0) {
+      c.streaming.throttleMs = patch.streamingThrottleMs;
+      filePatches["streaming.throttleMs"] = patch.streamingThrottleMs;
+    }
+    if (this.configWriter && Object.keys(filePatches).length > 0) {
+      this.configWriter(filePatches, this.config);
+    }
+  }
+  // ============ Backend 工厂 ============
+  createBackend(config) {
+    switch (config.backend.type) {
+      case "echo":
+        return new EchoBackend();
+      case "openai": {
+        const opts = config.backend.openai;
+        if (!opts) throw new Error("backend.openai \u914D\u7F6E\u7F3A\u5931");
+        return new OpenAIBackend({
+          apiKey: opts.apiKey,
+          baseUrl: opts.baseUrl,
+          model: opts.model,
+          systemPrompt: opts.systemPrompt,
+          maxTokens: opts.maxTokens,
+          temperature: opts.temperature,
+          logger: this.logger
+        });
+      }
+      case "cloudagent": {
+        const opts = config.backend.cloudagent;
+        if (!opts) throw new Error("backend.cloudagent \u914D\u7F6E\u7F3A\u5931");
+        return new CloudAgentBackend({
+          config: opts,
+          appId: config.qq.appId,
+          logger: this.logger
+        });
+      }
+      default:
+        throw new Error(`\u672A\u77E5\u540E\u7AEF\u7C7B\u578B: ${config.backend.type}`);
+    }
+  }
+  // ============ Middleware 装配 ============
+  setupMiddleware(config) {
+    const mw = config.middleware;
+    this.bot.use(errorHandler());
+    this.bot.use(telemetryMiddleware({ appId: this.config.qq.appId }));
+    this.bot.use(messageFilter({
+      skipSelfEcho: mw.messageFilter.skipSelfEcho,
+      dedup: mw.messageFilter.dedup
+    }));
+    this.bot.use(contentSanitizer({
+      stripBotMention: mw.contentSanitizer.stripBotMention,
+      collapseWhitespace: mw.contentSanitizer.collapseWhitespace
+    }));
+    this.bot.use(mentionGate({
+      requireMentionInGroup: mw.mentionGate.requireMentionInGroup,
+      alwaysAnswerC2C: mw.mentionGate.alwaysAnswerC2C
+    }));
+    if (mw.slashCommands.enabled) {
+      this.bot.use(createSlashMiddleware({
+        prefixes: mw.slashCommands.prefixes,
+        allowFrom: mw.slashCommands.allowFrom,
+        ctx: {
+          backend: this.backend,
+          logger: this.logger,
+          getConfig: () => this.config,
+          updateConfig: (patch) => this.applyConfigPatch(patch)
+        }
+      }));
+    }
+    if (mw.rateLimiter.enabled) {
+      this.bot.use(rateLimiter({
+        perSender: mw.rateLimiter.perSender,
+        global: mw.rateLimiter.global,
+        onLimit: (ctx, tier) => {
+          const scopeType = ctx.message.replyTarget.scope.startsWith("group") ? "group" : "c2c";
+          rateLimitRejectedTotal.add(1, { scope: scopeType, tier });
+        }
+      }));
+    }
+    this.bot.use(quoteRef());
+    this.bot.use(envelopeFormatter({
+      format: (ctx) => formatQQBotEnvelope(ctx)
+    }));
+    this.bot.use(concurrencyGuard({
+      strategy: mw.concurrency.strategy,
+      maxQueue: mw.concurrency.maxQueue,
+      onMerge: (buffered) => {
+        const scopeType = buffered[0].message.replyTarget.scope.startsWith("group") ? "group" : "c2c";
+        mergeTotal.add(buffered.length, { scope: scopeType });
+        const last = buffered[buffered.length - 1];
+        if (buffered.length === 1) return last;
+        const envelopes = buffered.map((ctx) => ctx.state.envelope ?? ctx.message.content ?? "").filter(Boolean);
+        if (envelopes.length > 0) {
+          last.state.envelope = envelopes.join("\n\n");
+        }
+        const allAttachments = buffered.flatMap((ctx) => ctx.message.attachments ?? []);
+        if (allAttachments.length > 0) {
+          last.message.attachments = allAttachments;
+        }
+        return last;
+      },
+      onDispatch: (merged) => {
+        const scopeType = merged.message.replyTarget.scope.startsWith("group") ? "group" : "c2c";
+        mergeEventsTotal.add(1, { scope: scopeType });
+        return this.handleMessage(merged, merged.message);
+      },
+      onDrop: (ctx) => {
+        const scopeType = ctx.message.replyTarget.scope.startsWith("group") ? "group" : "c2c";
+        dropTotal.add(1, { scope: scopeType });
+      }
+    }));
+    if (mw.typingIndicator.enabled) {
+      this.bot.use(typingIndicator({
+        durationSec: mw.typingIndicator.durationSec,
+        keepAliveIntervalMs: mw.typingIndicator.keepAliveIntervalMs
+      }));
+    }
+  }
+  // ============ 消息路由 ============
+  async handleMessage(ctx, msg) {
+    ctx.state.handled = true;
+    const envelope = ctx.state.envelope;
+    const text = (msg.content ?? "").trim();
+    if (!envelope && !text && (!msg.attachments || msg.attachments.length === 0)) {
+      return;
+    }
+    const qualifier = `${msg.replyTarget.scope}-${msg.replyTarget.targetId}`;
+    const extSessionId = this.resolveExtSessionId(msg);
+    const scopeType = msg.replyTarget.scope.startsWith("group") ? "group" : "c2c";
+    if (envelope) {
+      envelopeLength.record(envelope.length, { scope: scopeType });
+    }
+    const targetKey = `${msg.replyTarget.scope}:${msg.replyTarget.targetId}`;
+    if (msg.replyTarget.msgId) {
+      this.msgIdCache.push(targetKey, msg.replyTarget.msgId);
+    }
+    const rctx = {
+      bot: this.bot,
+      backend: this.backend,
+      config: this.config,
+      logger: this.logger
+    };
+    try {
+      const sessionId = await this.backend.getOrCreateSession(qualifier, extSessionId);
+      let attachments = msg.attachments?.map((att) => ({
+        url: att.url.startsWith("//") ? `https:${att.url}` : att.url,
+        mimeType: att.content_type,
+        name: att.filename ?? "file",
+        size: att.size
+      }));
+      let effectiveText = envelope || text;
+      const cmdMatch = /^\/(\S+)(?:\s+(.*))?$/.exec(text);
+      if (cmdMatch && !attachments?.length) {
+        const [, cmd, args] = cmdMatch;
+        effectiveText = args ?? "";
+        attachments = [{ url: `command://${cmd}`, mimeType: "text/x-command", name: cmd, size: void 0 }];
+      }
+      const replyMethod = this.config.streaming.c2c && msg.replyTarget.scope === "c2c" && msg.replyTarget.msgId ? "streamReply" : "batchReply";
+      await withClientMetrics({
+        callerMethod: "reply",
+        calleeService: "qq-platform",
+        calleeMethod: replyMethod,
+        extras: { user_ext1: scopeType }
+      }, async () => {
+        if (replyMethod === "streamReply") {
+          await streamReply(rctx, ctx, msg, sessionId, qualifier, effectiveText, attachments);
+        } else {
+          await batchReply(rctx, ctx, msg, sessionId, qualifier, effectiveText, attachments);
+        }
+      });
+    } catch (err) {
+      if (ctx.aborted) {
+        this.logger.debug(`[handler] ${qualifier} aborted, skip error reply`);
+        return;
+      }
+      const errMsg = err instanceof Error ? err.message : String(err);
+      this.logger.error(`[handler] ${qualifier} \u5904\u7406\u5931\u8D25: ${errMsg}`);
+      try {
+        let userMessage = this.formatErrorForUser(errMsg);
+        if (this.config.message.errorMessages.debug) {
+          userMessage += `
+
+[debug] ${errMsg}`;
+        }
+        await this.bot.sendText(msg.replyTarget, userMessage);
+      } catch {
+      }
+    }
+  }
+  /**
+   * 从 messageScene.ext 中提取外部 sessionid。
+   * 返回 undefined 表示事件中没有指定 sessionid。
+   */
+  resolveExtSessionId(msg) {
+    const ext = msg.messageScene?.ext;
+    if (ext) {
+      for (const entry of ext) {
+        if (entry.startsWith("sessionid=")) {
+          const sessionId = entry.slice("sessionid=".length);
+          if (sessionId) {
+            this.logger.debug?.(`[handler] using ext sessionid: ${sessionId}`);
+            return sessionId;
+          }
+        }
+      }
+    }
+    return void 0;
+  }
+  formatErrorForUser(errMsg) {
+    const { rules, unknown, troubleshootHint } = this.config.message.errorMessages;
+    const lower = errMsg.toLowerCase();
+    for (const rule of rules) {
+      if (rule.match.some((keyword) => lower.includes(keyword.toLowerCase()))) {
+        const hint = rule.hint ?? troubleshootHint;
+        return hint ? `${rule.reply}
+${hint}` : rule.reply;
+      }
+    }
+    return troubleshootHint ? `${unknown}
+${troubleshootHint}` : unknown;
+  }
+};
+
+export {
+  loadConfig,
+  ConfigWatcher,
+  GALILEO_RESOURCE,
+  setBizDefaultAttrs,
+  BotRunner
+};
+//# sourceMappingURL=chunk-XIJ6OSLY.js.map