aitable-workflow-cli 0.1.22 → 0.1.23

package/templates/support-qa/lib/sandbox-agent.ts

@@ -0,0 +1,653 @@
+import { createHash } from "node:crypto";
+import { existsSync, readFileSync, readdirSync, realpathSync } from "node:fs";
+import path from "node:path";
+import { zipSync } from "fflate";
+import { getAgentConfig, loadAgentConfig, workspaceAgentConfigPath } from "aitable-workflow-core";
+import { SandboxManager } from "@ali/aone-sandbox";
+import {
+  CodeInterpreter,
+  QoderRemoteAgent,
+  Sandbox,
+  type AcpClient,
+  type AcpSessionUpdate,
+  type QoderConfig,
+  type SandboxClient,
+} from "@ali/aone-remote-agent";
+
+/**
+ * support-qa 沙箱 Agent 执行器
+ *
+ * 解决 4G 部署机只能并发 1 个本地 qodercli 的问题：把 Agent 执行搬到 Aone Sandbox，
+ * 维护 3 个独立 Sandbox，每个 Sandbox 只运行 1 个 QoderRemoteAgent。进程启动后的首次请求
+ * 会清理同 workspace 的遗留 Sandbox，再创建新池；Sandbox 生命周期 24h，到期前自动重建。
+ */
+
+const CONCURRENT_AGENTS = 3;
+
+/** Sandbox 创建 TTL（秒）：24h，接近 Aone 单创建最大 24h 上限 */
+const SANDBOX_TTL_SECONDS = 24 * 60 * 60;
+
+/** 在 TTL 前多久重建整个池（秒）：23h，留 1h 缓冲处理进行中的请求 */
+const POOL_REBUILD_BEFORE_TTL_SECONDS = 60 * 60;
+
+const NPM_REGISTRY = "https://registry.anpm.alibaba-inc.com/";
+const WORKSPACE_DIR = "/workspace";
+const SANDBOX_KB_ROOT = `${WORKSPACE_DIR}/.kb/faq-support`;
+const SANDBOX_KB_LINK = `${WORKSPACE_DIR}/wiki/faq-support`;
+const SANDBOX_MEDIA_ROOT = `${WORKSPACE_DIR}/.media`;
+const SANDBOX_METADATA = { application: "aitable-agent", workload: "support-qa" };
+
+/**
+ * code-interpreter 镜像将 Node 22 安装在 /opt/taobao/install/nvm 下，却没有把 npm 放进 PATH，
+ * 因此必须显式找到同版本 npm 执行安装。
+ */
+function npmInstallCommand(args: string): string {
+  return [
+    "set -eu",
+    "for node_exec in /opt/taobao/install/nvm/versions/node/*/bin/node \"$HOME\"/.nvm/versions/node/*/bin/node /root/.nvm/versions/node/*/bin/node /home/admin/.nvm/versions/node/*/bin/node /usr/local/bin/node /usr/bin/node; do",
+    "  [ -x \"$node_exec\" ] || continue",
+    "  node_major=$(\"$node_exec\" -p 'process.versions.node.split(\".\")[0]' 2>/dev/null || true)",
+    "  [ \"$node_major\" -ge 22 ] 2>/dev/null || continue",
+    "  npm_exec=$(dirname \"$node_exec\")/npm",
+    "  [ -x \"$npm_exec\" ] || continue",
+    "  export PATH=$(dirname \"$node_exec\"):$PATH",
+    "  [ -x \"$(dirname \"$node_exec\")/qodercli\" ] && exit 0",
+    `  exec \"$npm_exec\" ${args} --registry=${NPM_REGISTRY}`,
+    "done",
+    "echo 'npm for Node.js >= 22: command not found' >&2",
+    "exit 127",
+  ].join("\n");
+}
+
+export type SandboxLogFn = (msg: string) => void;
+
+interface PooledAgent {
+  agent: QoderRemoteAgent;
+  sandbox: Sandbox;
+  client: SandboxClient;
+  busy: boolean;
+}
+
+interface PoolGeneration {
+  agents: PooledAgent[];
+}
+
+function requireEnv(name: string): string {
+  const value = process.env[name]?.trim();
+  if (!value) {
+    throw new Error(`缺少环境变量 ${name}，support-qa 沙箱模式无法启动`);
+  }
+  return value;
+}
+
+function logDefault(msg: string): void {
+  // eslint-disable-next-line no-console
+  console.log(`[sandbox-agent] ${msg}`);
+}
+
+/**
+ * 从更新事件中提取文本片段。
+ *
+ * ACP 协议的具体 update shape 取决于远端 Agent 实现，这里做防御性抽取：
+ * 先匹配最常见的 Anthropic 风格 text_delta，再回退到若干常见字段。
+ */
+function extractTextFromUpdate(update: AcpSessionUpdate): string {
+  const u = update.update;
+  if (!u || typeof u !== "object") return "";
+
+  const anyU = u as Record<string, unknown>;
+
+  // Anthropic / claude-agent-sdk 风格
+  const delta = anyU.delta;
+  if (delta && typeof delta === "object") {
+    const d = delta as Record<string, unknown>;
+    if (d.type === "text_delta" && typeof d.text === "string") {
+      return d.text;
+    }
+  }
+
+  // ACP agent_message_chunk 使用 content 对象承载文本
+  if (anyU.content && typeof anyU.content === "object" && !Array.isArray(anyU.content)) {
+    const content = anyU.content as Record<string, unknown>;
+    if (typeof content.text === "string") return content.text;
+  }
+
+  // 常见直接字段
+  if (typeof anyU.text === "string") return anyU.text;
+  if (typeof anyU.output === "string") return anyU.output;
+  if (typeof anyU.content === "string") return anyU.content;
+
+  // content 数组
+  if (Array.isArray(anyU.content)) {
+    return anyU.content
+      .map((c: unknown) => {
+        if (c && typeof c === "object") {
+          const cc = c as Record<string, unknown>;
+          return typeof cc.text === "string" ? cc.text : typeof cc.output === "string" ? cc.output : "";
+        }
+        return "";
+      })
+      .join("");
+  }
+
+  return "";
+}
+
+async function uploadPromptImages(
+  sandbox: SandboxClient,
+  prompt: string,
+  localWorkDir: string,
+  log: SandboxLogFn,
+): Promise<string> {
+  if (!sandbox.files.writeFiles) {
+    throw new Error("当前 Sandbox 不支持 writeFiles，无法同步消息图片");
+  }
+
+  const mediaRoot = path.resolve(localWorkDir, "..", "..", ".aitable", "media", "dingtalk");
+  if (!existsSync(mediaRoot)) return prompt;
+
+  const realMediaRoot = realpathSync(mediaRoot);
+  const replacements = new Map<string, string>();
+  const uploads = new Map<string, { path: string; data: Uint8Array }>();
+  const imagePattern = /!\[[^\n]*?\]\((?:<([^>\n]+)>|([^)\n]+))\)/g;
+
+  for (const match of prompt.matchAll(imagePattern)) {
+    const destination = (match[1] ?? match[2] ?? "").trim();
+    if (!path.isAbsolute(destination) || !existsSync(destination)) continue;
+
+    const realSource = realpathSync(destination);
+    const relative = path.relative(realMediaRoot, realSource);
+    if (relative.startsWith("..") || path.isAbsolute(relative)) continue;
+
+    const data = readFileSync(realSource);
+    const digest = createHash("sha256").update(data).digest("hex").slice(0, 20);
+    const extension = path.extname(realSource).toLowerCase().replace(/[^.a-z0-9]/g, "");
+    const sandboxPath = `${SANDBOX_MEDIA_ROOT}/${digest}${extension}`;
+    replacements.set(destination, sandboxPath);
+    uploads.set(sandboxPath, { path: sandboxPath, data });
+  }
+
+  if (uploads.size === 0) return prompt;
+  await sandbox.files.writeFiles([...uploads.values()]);
+  log(`沙箱：已同步消息图片 ${uploads.size} 张`);
+  let rewritten = prompt;
+  for (const [localPath, sandboxPath] of replacements) {
+    rewritten = rewritten.split(localPath).join(sandboxPath);
+  }
+  return rewritten;
+}
+
+function createKbArchive(localWorkDir: string): { archive: Uint8Array; digest: string } {
+  const kbLink = path.join(path.resolve(localWorkDir), "wiki", "faq-support");
+  if (!existsSync(kbLink)) {
+    throw new Error(`本地知识库软链不存在: ${kbLink}`);
+  }
+
+  const compiledWikiDir = realpathSync(kbLink);
+  const kbDir = path.dirname(compiledWikiDir);
+  const indexPath = path.join(compiledWikiDir, "_index.md");
+  if (!existsSync(indexPath)) {
+    throw new Error(`本地知识库未编译或缺少索引: ${indexPath}`);
+  }
+
+  const files: Record<string, Uint8Array> = {};
+  const visit = (dir: string): void => {
+    const entries = readdirSync(dir, { withFileTypes: true }).sort((left, right) => left.name.localeCompare(right.name));
+    for (const entry of entries) {
+      const absolutePath = path.join(dir, entry.name);
+      if (entry.isDirectory()) {
+        visit(absolutePath);
+      } else if (entry.isFile()) {
+        const archivePath = path.relative(kbDir, absolutePath).split(path.sep).join("/");
+        files[archivePath] = readFileSync(absolutePath);
+      }
+    }
+  };
+  visit(kbDir);
+
+  const hash = createHash("sha256");
+  for (const archivePath of Object.keys(files).sort()) {
+    hash.update(archivePath).update("\0").update(files[archivePath]).update("\0");
+  }
+  const archive = zipSync(files, { level: 6, mtime: "1980-01-01T00:00:00.000Z" });
+  const digest = hash.digest("hex").slice(0, 16);
+  return { archive, digest };
+}
+
+async function syncSandboxFilesOnce(
+  sandbox: SandboxClient,
+  localWorkDir: string,
+  log: SandboxLogFn,
+  kbDigests: WeakMap<SandboxClient, string>,
+): Promise<void> {
+  if (!sandbox.files.writeFiles) {
+    throw new Error("当前 Sandbox 不支持 writeFiles，无法同步动态知识库");
+  }
+
+  const resolvedWorkDir = path.resolve(localWorkDir);
+  const entries: Array<{ path: string; data: string | Uint8Array }> = [];
+  const requestCommands = [`mkdir -p ${WORKSPACE_DIR}/.request`];
+  for (const fileName of ["AGENTS.md", "owner-map.json", ".long-term.md"]) {
+    const localPath = path.join(resolvedWorkDir, fileName);
+    const stagingPath = `${WORKSPACE_DIR}/.request/${fileName}`;
+    const targetPath = `${WORKSPACE_DIR}/${fileName}`;
+    if (existsSync(localPath)) {
+      entries.push({ path: stagingPath, data: readFileSync(localPath) });
+      requestCommands.push(`cp ${stagingPath} ${targetPath}`);
+    } else {
+      requestCommands.push(`rm -f ${targetPath}`);
+    }
+  }
+
+  const { archive, digest } = createKbArchive(resolvedWorkDir);
+  const kbChanged = kbDigests.get(sandbox) !== digest;
+  const commands = ["set -eu", ...requestCommands];
+
+  if (kbChanged) {
+    const archivePath = `${SANDBOX_KB_ROOT}/${digest}.zip`;
+    entries.push({ path: archivePath, data: archive });
+
+    log(`沙箱：同步动态知识库 ${digest}...`);
+    const targetDir = `${SANDBOX_KB_ROOT}/${digest}`;
+    const stagingDir = `${targetDir}.tmp`;
+    const stagingLink = `${WORKSPACE_DIR}/wiki/.faq-support-${digest}`;
+    commands.push(
+      `mkdir -p ${SANDBOX_KB_ROOT} ${WORKSPACE_DIR}/wiki`,
+      `rm -rf ${stagingDir}`,
+      `mkdir -p ${stagingDir}`,
+      `python3 -c 'import sys, zipfile; zipfile.ZipFile(sys.argv[1]).extractall(sys.argv[2])' ${archivePath} ${stagingDir}`,
+      `test -f ${stagingDir}/wiki/_index.md`,
+      `if [ -f ${targetDir}/wiki/_index.md ]; then rm -rf ${stagingDir}; else mv ${stagingDir} ${targetDir}; fi`,
+      `rm -f ${stagingLink}`,
+      `ln -s ${targetDir}/wiki ${stagingLink}`,
+      `if [ -L ${SANDBOX_KB_LINK} ]; then mv -Tf ${stagingLink} ${SANDBOX_KB_LINK}; else rm -rf ${SANDBOX_KB_LINK}; mv ${stagingLink} ${SANDBOX_KB_LINK}; fi`,
+      `rm -f ${archivePath}`,
+    );
+  }
+
+  await sandbox.files.writeFiles(entries);
+  const syncRes = await sandbox.commands.runCommand(commands.join("\n"));
+  if ((syncRes.exitCode ?? 1) !== 0) {
+    throw new Error(
+      `同步 Sandbox 工作区失败: exit=${syncRes.exitCode}, stderr=${JSON.stringify(syncRes.logs?.stderr)}`,
+    );
+  }
+
+  if (kbChanged) {
+    kbDigests.set(sandbox, digest);
+    log("沙箱：动态知识库已就绪");
+  }
+}
+
+async function syncSandboxFiles(
+  sandbox: SandboxClient,
+  localWorkDir: string,
+  log: SandboxLogFn,
+  kbDigests: WeakMap<SandboxClient, string>,
+  syncs: WeakMap<SandboxClient, Promise<void>>,
+): Promise<void> {
+  const previous = syncs.get(sandbox) ?? Promise.resolve();
+  const current = previous
+    .catch(() => undefined)
+    .then(() => syncSandboxFilesOnce(sandbox, localWorkDir, log, kbDigests));
+  syncs.set(sandbox, current);
+  try {
+    await current;
+  } finally {
+    if (syncs.get(sandbox) === current) syncs.delete(sandbox);
+  }
+}
+
+async function buildQoderConfig(pat: string, localWorkDir: string): Promise<QoderConfig> {
+  const configDir = path.resolve(localWorkDir, "..", "..");
+  const agentConfig = getAgentConfig(
+    await loadAgentConfig(workspaceAgentConfigPath(configDir)),
+    "qoder",
+  );
+  const model = agentConfig.model?.trim();
+  return {
+    personalAccessToken: pat,
+    ...(model ? { model } : {}),
+    permissionMode: "allow_always",
+    // qodercli 已在 prepareSandbox 中预装，避免 QoderRemoteAgent 默认的 sh -lc npm install 在
+    // code-interpreter 镜像里找不到 npm 而报 exit 127。
+    skipInstall: true,
+    acpRuntime: {
+      requestTimeoutMs: 420_000,
+    },
+  };
+}
+
+/** 把 @ali/aone-sandbox 的 Sandbox 包装成 QoderRemoteAgent 需要的 SandboxClient。 */
+async function createSandboxClient(sandbox: Sandbox): Promise<SandboxClient> {
+  const interpreter = await CodeInterpreter.fromSandbox(sandbox);
+  type ExecutionResult = Awaited<ReturnType<SandboxClient["commands"]["runCommand"]>>;
+  const toExecutionResult = (execution: { error?: unknown; logs?: unknown; exitCode?: number | null }): ExecutionResult => ({
+    error: typeof execution.error === "string" ? execution.error : undefined,
+    logs: execution.logs as ExecutionResult["logs"],
+    exitCode: execution.exitCode,
+  });
+
+  return {
+    commands: {
+      runCommand: async (command) => toExecutionResult(await interpreter.commands.run(command)),
+    },
+    files: {
+      readFile: (path, options) => interpreter.files.readFile(path, options),
+      writeFiles: (entries) => interpreter.files.writeFiles(entries),
+    },
+    getEndpoint: async (port) => {
+      const endpoint = await sandbox.getEndpoint(port);
+      if (!endpoint?.endpoint) throw new Error("Sandbox endpoint is not available");
+      return { endpoint: endpoint.endpoint, headers: { ...endpoint.headers ?? {} } };
+    },
+    kill: () => sandbox.kill(),
+    id: sandbox.id,
+    connection: {
+      baseUrl: sandbox.connectionConfig.getBaseUrl(),
+      apiKey: sandbox.connectionConfig.apiKey,
+    },
+  };
+}
+
+export interface SupportQaSandboxAgentPoolStatus {
+  capacity: number;
+  busy: number;
+  idle: number;
+  initializing: boolean;
+  sandboxIds: string[];
+}
+
+export interface SandboxAgentRunResult {
+  response: string;
+  sandboxId: string;
+  sessionId: string;
+}
+
+export class SupportQaSandboxAgentPool {
+  private generation: PoolGeneration | null = null;
+  private starting: Promise<PoolGeneration> | null = null;
+  private rebuilding: Promise<void> | null = null;
+  private lifecycleTimer: NodeJS.Timeout | null = null;
+  private workspaceDir: string | null = null;
+  private readonly kbDigests = new WeakMap<SandboxClient, string>();
+  private readonly syncs = new WeakMap<SandboxClient, Promise<void>>();
+
+  constructor(private readonly capacity = CONCURRENT_AGENTS) {}
+
+  status(): SupportQaSandboxAgentPoolStatus {
+    const agents = this.generation?.agents ?? [];
+    const busy = agents.filter((entry) => entry.busy).length;
+    return {
+      capacity: this.capacity,
+      busy,
+      idle: agents.length - busy,
+      initializing: this.starting !== null || this.rebuilding !== null,
+      sandboxIds: agents.map((entry) => entry.sandbox.id).filter((id): id is string => Boolean(id)),
+    };
+  }
+
+  async run(
+    prompt: string,
+    localWorkDir: string,
+    log: SandboxLogFn = logDefault,
+  ): Promise<SandboxAgentRunResult> {
+    const pooled = await this.acquireAgent(localWorkDir, log);
+
+    try {
+      await syncSandboxFiles(pooled.client, localWorkDir, log, this.kbDigests, this.syncs);
+      const sandboxPrompt = await uploadPromptImages(pooled.client, prompt, localWorkDir, log);
+
+      const client: AcpClient = pooled.agent.client();
+      const sessionId = await client.newAcpSession(WORKSPACE_DIR);
+      const sandboxId = pooled.sandbox.id ?? "unknown";
+      log(`沙箱：ACP Session 已创建 sandboxId=${sandboxId} sessionId=${sessionId}`);
+      const chunks: string[] = [];
+      const unsubscribe = client.addUpdateListener((update) => {
+        if (update.sessionId === sessionId) {
+          const text = extractTextFromUpdate(update);
+          if (text) chunks.push(text);
+        }
+      });
+
+      let result;
+      try {
+        result = await client.query(sandboxPrompt, sessionId);
+      } catch (error) {
+        const partialResponse = chunks.join("");
+        const reason = error instanceof Error ? error.message : String(error);
+        throw new Error(
+          `sandbox agent 调用失败: sandboxId=${sandboxId}, sessionId=${sessionId}, ` +
+          `responseLength=${partialResponse.length}, response=${JSON.stringify(partialResponse)}, error=${reason}`,
+        );
+      } finally {
+        unsubscribe();
+        await client.closeAcpSession(sessionId).catch(() => undefined);
+      }
+
+      let responseText = chunks.join("");
+      if (!responseText && result?.raw) {
+        const raw = result.raw as Record<string, unknown>;
+        responseText =
+          typeof raw.text === "string" ? raw.text
+          : typeof raw.output === "string" ? raw.output
+          : typeof raw.content === "string" ? raw.content
+          : "";
+      }
+      if (!responseText.trim()) {
+        throw new Error(`sandbox agent 返回空响应: sandboxId=${sandboxId}, sessionId=${sessionId}`);
+      }
+      return { response: responseText, sandboxId, sessionId };
+    } finally {
+      pooled.busy = false;
+    }
+  }
+
+  async stop(log: SandboxLogFn = logDefault): Promise<void> {
+    this.clearLifecycleTimer();
+    if (this.rebuilding) await this.rebuilding.catch(() => undefined);
+
+    const generation = this.generation ?? (this.starting ? await this.starting.catch(() => null) : null);
+    this.generation = null;
+    this.starting = null;
+    this.workspaceDir = null;
+
+    if (generation) {
+      log("沙箱：停止 Agent 池并释放全部 Sandbox");
+      await this.disposeGeneration(generation, log);
+    }
+  }
+
+  private bindWorkspace(localWorkDir: string): string {
+    const resolved = path.resolve(localWorkDir);
+    if (this.workspaceDir && this.workspaceDir !== resolved) {
+      throw new Error(`Sandbox Agent 池已绑定工作目录 ${this.workspaceDir}，不能切换到 ${resolved}`);
+    }
+    this.workspaceDir = resolved;
+    return resolved;
+  }
+
+  private reuseKey(localWorkDir: string): string {
+    return createHash("sha256").update(localWorkDir).digest("hex").slice(0, 16);
+  }
+
+  private async cleanupExistingSandboxes(apiKey: string, localWorkDir: string, log: SandboxLogFn): Promise<void> {
+    const manager = SandboxManager.create({ connectionConfig: { apiKey } });
+    try {
+      const response = await manager.listSandboxInfos({
+        states: ["Running"],
+        metadata: { ...SANDBOX_METADATA, reuseKey: this.reuseKey(localWorkDir) },
+        pageSize: 20,
+      });
+      await Promise.all(response.items.map(async (info) => {
+        await manager.killSandbox(info.id);
+        log(`沙箱：已清理上次进程遗留的 Sandbox ${info.id}`);
+      }));
+    } finally {
+      await manager.close().catch(() => undefined);
+    }
+  }
+
+  private async createAgentSandbox(
+    apiKey: string,
+    qoderConfig: QoderConfig,
+    localWorkDir: string,
+    index: number,
+    log: SandboxLogFn,
+  ): Promise<PooledAgent> {
+    let sandbox: Sandbox | null = null;
+    let agent: QoderRemoteAgent | null = null;
+    try {
+      log(`沙箱：创建 Agent ${index + 1}/${this.capacity}...`);
+      sandbox = await Sandbox.create({
+        connectionConfig: { apiKey },
+        template: "code-interpreter",
+        timeoutSeconds: SANDBOX_TTL_SECONDS,
+        readyTimeoutSeconds: 120,
+        env: {
+          PYTHON_VERSION: "3.12",
+          JAVA_VERSION: "21",
+          NODE_VERSION: "22",
+          NPM_CONFIG_REGISTRY: NPM_REGISTRY,
+        },
+        metadata: {
+          ...SANDBOX_METADATA,
+          reuseKey: this.reuseKey(localWorkDir),
+          slot: String(index + 1),
+        },
+      });
+
+      const client = await createSandboxClient(sandbox);
+      const qoderInstall = await client.commands.runCommand(npmInstallCommand("install -g @qoder-ai/qodercli"));
+      if ((qoderInstall.exitCode ?? 1) !== 0) {
+        throw new Error(
+          `准备 qodercli 失败: exit=${qoderInstall.exitCode}, stderr=${JSON.stringify(qoderInstall.logs?.stderr)}`,
+        );
+      }
+
+      agent = new QoderRemoteAgent(client, qoderConfig, WORKSPACE_DIR, false);
+      await agent.start();
+      log(`沙箱：Agent ${index + 1}/${this.capacity} 已就绪 sandboxId=${sandbox.id ?? "unknown"}`);
+      return { agent, sandbox, client, busy: false };
+    } catch (error) {
+      await agent?.stop().catch(() => undefined);
+      await sandbox?.kill().catch(() => undefined);
+      await sandbox?.close().catch(() => undefined);
+      throw error;
+    }
+  }
+
+  private async createGeneration(
+    localWorkDir: string,
+    log: SandboxLogFn,
+    cleanupExisting: boolean,
+  ): Promise<PoolGeneration> {
+    const apiKey = requireEnv("SANDBOX_API_KEY");
+    const pat = requireEnv("QODER_PERSONAL_ACCESS_TOKEN");
+    const qoderConfig = await buildQoderConfig(pat, localWorkDir);
+    if (cleanupExisting) await this.cleanupExistingSandboxes(apiKey, localWorkDir, log);
+
+    const settled = await Promise.allSettled(
+      Array.from({ length: this.capacity }, (_, index) =>
+        this.createAgentSandbox(apiKey, qoderConfig, localWorkDir, index, log)),
+    );
+    const agents = settled
+      .filter((result): result is PromiseFulfilledResult<PooledAgent> => result.status === "fulfilled")
+      .map((result) => result.value);
+    const failed = settled.find((result): result is PromiseRejectedResult => result.status === "rejected");
+    if (failed) {
+      await this.disposeGeneration({ agents }, log);
+      throw failed.reason;
+    }
+    return { agents };
+  }
+
+  private async ensureGeneration(localWorkDir: string, log: SandboxLogFn): Promise<PoolGeneration> {
+    const workspace = this.bindWorkspace(localWorkDir);
+    if (this.generation) return this.generation;
+    if (this.rebuilding) {
+      await this.rebuilding;
+      if (this.generation) return this.generation;
+    }
+    if (!this.starting) {
+      const starting = this.createGeneration(workspace, log, true)
+        .then((generation) => {
+          this.generation = generation;
+          this.scheduleRebuild(log);
+          return generation;
+        })
+        .finally(() => {
+          if (this.starting === starting) this.starting = null;
+        });
+      this.starting = starting;
+    }
+    return this.starting;
+  }
+
+  private async acquireAgent(localWorkDir: string, log: SandboxLogFn): Promise<PooledAgent> {
+    while (true) {
+      const generation = await this.ensureGeneration(localWorkDir, log);
+      const idle = generation.agents.find((entry) => !entry.busy);
+      if (idle) {
+        idle.busy = true;
+        return idle;
+      }
+      await new Promise((resolve) => setTimeout(resolve, 100));
+    }
+  }
+
+  private scheduleRebuild(log: SandboxLogFn): void {
+    this.clearLifecycleTimer();
+    const delayMs = Math.max(60_000, (SANDBOX_TTL_SECONDS - POOL_REBUILD_BEFORE_TTL_SECONDS) * 1000);
+    this.lifecycleTimer = setTimeout(() => {
+      log("沙箱：接近生命周期上限，排空请求后重建 Agent 池");
+      void this.rebuild(log).catch((error) => log(`沙箱：Agent 池重建失败: ${error}`));
+    }, delayMs);
+  }
+
+  private async rebuild(log: SandboxLogFn): Promise<void> {
+    if (this.rebuilding || !this.generation || !this.workspaceDir) return this.rebuilding ?? Promise.resolve();
+    const oldGeneration = this.generation;
+    const rebuilding = (async () => {
+      this.generation = null;
+      while (oldGeneration.agents.some((entry) => entry.busy)) {
+        await new Promise((resolve) => setTimeout(resolve, 100));
+      }
+      await this.disposeGeneration(oldGeneration, log);
+      const nextGeneration = await this.createGeneration(this.workspaceDir!, log, false);
+      this.generation = nextGeneration;
+      this.scheduleRebuild(log);
+    })().finally(() => {
+      if (this.rebuilding === rebuilding) this.rebuilding = null;
+    });
+    this.rebuilding = rebuilding;
+    return rebuilding;
+  }
+
+  private clearLifecycleTimer(): void {
+    if (this.lifecycleTimer) clearTimeout(this.lifecycleTimer);
+    this.lifecycleTimer = null;
+  }
+
+  private async disposeGeneration(generation: PoolGeneration, log: SandboxLogFn): Promise<void> {
+    await Promise.all(generation.agents.map(async ({ agent, sandbox }) => {
+      await agent.stop().catch((error) => log(`沙箱：停止 Agent 失败（忽略）: ${error}`));
+      await sandbox.kill().catch((error) => log(`沙箱：释放 Sandbox 失败（忽略）: ${error}`));
+      await sandbox.close().catch((error) => log(`沙箱：关闭 Sandbox 客户端失败（忽略）: ${error}`));
+    }));
+  }
+}
+
+const defaultSandboxAgentPool = new SupportQaSandboxAgentPool();
+
+export function runSandboxAgent(
+  prompt: string,
+  localWorkDir: string,
+  log: SandboxLogFn = logDefault,
+): Promise<SandboxAgentRunResult> {
+  return defaultSandboxAgentPool.run(prompt, localWorkDir, log);
+}
+
+export function stopSandboxAgentPool(log: SandboxLogFn = logDefault): Promise<void> {
+  return defaultSandboxAgentPool.stop(log);
+}

package/templates/support-qa/package.json

@@ -6,12 +6,22 @@
   "description": "通用群答疑助手（由 aitable-workflow init --template support-qa 生成）。业务差异全部在 profile/profile.yml。",
   "scripts": {
     "run": "aitable-workflow run",
-    "setup": "aitable-workflow setup"
+    "setup": "aitable-workflow setup",
+    "test": "vitest run",
+    "typecheck": "tsc --noEmit"
   },
   "dependencies": {
     "aitable-workflow-core": "^0.1.5",
+    "@ali/aone-remote-agent": "^4.1.0",
+    "@ali/aone-sandbox": "^1.0.10",
+    "fflate": "^0.8.2",
     "tsx": "^4.20.6",
     "yaml": "^2.8.1",
     "zod": "^4.1.13"
+  },
+  "devDependencies": {
+    "@types/node": "^24.10.1",
+    "typescript": "^5.9.3",
+    "vitest": "^3.0.0"
   }
 }

package/templates/support-qa/tsconfig.json

@@ -0,0 +1,16 @@
+{
+  "compilerOptions": {
+    "target": "ES2022",
+    "module": "NodeNext",
+    "moduleResolution": "NodeNext",
+    "lib": ["ES2022"],
+    "strict": true,
+    "esModuleInterop": true,
+    "skipLibCheck": true,
+    "forceConsistentCasingInFileNames": true,
+    "noEmit": true,
+    "rootDir": "."
+  },
+  "include": ["lib/**/*.ts", "workflows/**/*.ts"],
+  "exclude": ["**/__tests__/**", "**/node_modules/**", "**/dist/**"]
+}