@allbluecn/web-app 0.12.0 → 0.12.2

package/src/server/ai-gateway/code-mode/index.ts

@@ -0,0 +1,236 @@
+// SPDX-License-Identifier: AGPL-3.0-or-later
+// AllBlue - 理想之海
+// Copyright (C) 2026 AllBlue Contributors
+//
+// This program is free software: you can redistribute it and/or modify
+// it under the terms of the GNU Affero General Public License as published by
+// the Free Software Foundation, either version 3 of the License, or
+// (at your option) any later version.
+//
+// This program is distributed in the hope that it will be useful,
+// but WITHOUT ANY WARRANTY; without even the implied warranty of
+// MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
+// GNU Affero General Public License for more details.
+//
+// You should have received a copy of the GNU Affero General Public License
+// along with this program. If not, see <https://www.gnu.org/licenses/>.
+
+/**
+ * 编排模式（Code Mode）装配层。
+ *
+ * 业务价值：普通模式下 13 个工具的 inputSchema 全量进 function-calling 载荷，
+ * 每轮对话都吃 token；编排模式只发 execute_typescript + discover_tools 两个元工具，
+ * 模型在沙箱程序里按需 discover_tools() 拉类型 stub，长尾工具坍缩为一行目录。
+ *
+ * 三层门控（缺一层不启用，全部失败路径静默回落普通工具调用）：
+ *   1. env AI_CODE_MODE_ENABLED === "true"（默认关闭）
+ *   2. 请求级开关 codeModeEnabled（UI 开关传入，默认关闭）
+ *   3. sandbox 探测通过（isolated-vm 已编译且与当前 Node 版本兼容）
+ *
+ * 顺序不可调换：env 在前，保证未开启时零 probe 调用、零动态 import——
+ * isolated-vm 版本不兼容会 segfault 整个进程，任何 JS 异常处理都拦不住。
+ */
+
+import type {
+  CodeModeTool,
+  CreateCodeModeResult,
+  SecretParameterInfo,
+  ToolBinding,
+} from "@tanstack/ai-code-mode"
+import { createCodeMode, toolsToBindings } from "@tanstack/ai-code-mode"
+import type { AppContext } from "../types"
+import {
+  CODE_MODE_MEMORY_LIMIT_MB,
+  CODE_MODE_TIMEOUT_MS,
+  loadSandbox,
+  resetSandboxCacheForTest,
+  setSandboxLoaderForTest,
+  setSandboxRuntimeProbeForTest,
+} from "./sandbox"
+import { buildSnippetBindings } from "./snippets"
+
+export const CODE_MODE_ENV_KEY = "AI_CODE_MODE_ENABLED"
+
+/**
+ * 不进沙箱的只读高频工具：schema 小、编排程序最常串联，
+ * 直接给全量类型 stub，省掉 discover_tools 往返。
+ */
+const EAGER_TOOL_NAMES = new Set([
+  "knowledge_search",
+  "web_search",
+  "user_data_query",
+])
+
+/**
+ * plan_submit 的 execute 只在引擎 interrupt 决议为 continue 后才被调用，
+ * 放进沙箱等于绕过用户审批直接落库「已批准」决议，必须排除。
+ */
+const CODE_MODE_BLOCKED_TOOL_NAMES = new Set(["plan_submit"])
+
+/**
+ * 沙箱工具的入参类型。`execute` 用方法语法声明：属性形式的方法类型在
+ * strictFunctionTypes 下参数是严格逆变的，真实工具（`execute(args: {query: string})`）
+ * 无法赋给 `execute(args: unknown)`；方法语法下参数检查双变，才能直接接收
+ * ToolRegistry 派生的具体参数类型工具，无需 any 断言。
+ */
+export interface CodeModeToolInput {
+  name: string
+  description?: string
+  inputSchema: unknown
+  outputSchema?: unknown
+  needsApproval?: boolean
+  lazy?: boolean
+  execute?(args: unknown, context?: unknown): unknown
+}
+
+export type CodeModeStack =
+  | { enabled: true; systemPrompts: string[]; tools: CodeModeTools }
+  | { enabled: false }
+
+export type CodeModeTools = CreateCodeModeResult["tools"]
+
+export interface BuildCodeModeStackOptions {
+  tools: readonly CodeModeToolInput[]
+  context: AppContext
+  requested?: boolean
+}
+
+export type CodeModeReadinessReason = "disabled" | "sandbox-unavailable" | null
+
+export interface CodeModeReadiness {
+  enabled: boolean
+  reason: CodeModeReadinessReason
+  detail?: string
+}
+
+export function isCodeModeEnvEnabled(): boolean {
+  return process.env[CODE_MODE_ENV_KEY] === "true"
+}
+
+function filterCodeModeTools(
+  tools: readonly CodeModeToolInput[],
+): CodeModeToolInput[] {
+  const kept: CodeModeToolInput[] = []
+  for (const tool of tools) {
+    if (typeof tool.execute !== "function") continue
+    if (tool.needsApproval === true) continue
+    if (CODE_MODE_BLOCKED_TOOL_NAMES.has(tool.name)) continue
+    kept.push({ ...tool, lazy: !EAGER_TOOL_NAMES.has(tool.name) })
+  }
+  return kept
+}
+
+/**
+ * 沙箱 binding 的 execute 由 createEventAwareBindings 包装，第二个参数只有
+ * { emitCustomEvent }——chat 层注入的 AppContext（userId/knowledgeBaseIds/
+ * threadId）不会进来。工具实现（document_action 写 createdBy、
+ * knowledge_search 做知识域收窄）都从 context 取归属信息，缺失会造成
+ * 跨用户数据写入或知识域校验被绕过，因此这里强制补齐。
+ */
+function injectAppContext(
+  tools: readonly CodeModeToolInput[],
+  appContext: AppContext,
+): CodeModeToolInput[] {
+  return tools.map((tool) => ({
+    ...tool,
+    execute: async (args: unknown, ctx: unknown) => {
+      const base = typeof ctx === "object" && ctx !== null ? ctx : {}
+      return tool.execute!(args, { ...base, context: appContext })
+    },
+  }))
+}
+
+const warnedKeys = new Set<string>()
+
+function warnOnce(key: string, message: string): void {
+  if (warnedKeys.has(key)) return
+  warnedKeys.add(key)
+  console.warn(`[code-mode] ${message}`)
+}
+
+const warnedSecrets = new Set<string>()
+
+function warnSecretParameterOnce(info: SecretParameterInfo): void {
+  const key = `${info.toolName}::${info.paramPath.join(".")}`
+  if (warnedSecrets.has(key)) return
+  warnedSecrets.add(key)
+  warnOnce(
+    `secret:${key}`,
+    `工具 ${info.toolName} 的参数 ${info.paramPath.join(".")} 形似密钥——编排模式会把它暴露给模型生成的代码，请把密钥留在服务端工具实现内部`,
+  )
+}
+
+export async function buildCodeModeStack(
+  opts: BuildCodeModeStackOptions,
+): Promise<CodeModeStack> {
+  if (!isCodeModeEnvEnabled()) return { enabled: false }
+  if (opts.requested !== true) return { enabled: false }
+
+  const sandbox = await loadSandbox()
+  if (sandbox.kind === "unavailable") {
+    warnOnce("sandbox", `编排模式不可用，已回落到普通工具调用：${sandbox.reason}`)
+    return { enabled: false }
+  }
+
+  const tools = filterCodeModeTools(opts.tools)
+  if (tools.length === 0) {
+    warnOnce("no-tools", "编排模式无可用工具（全部为审批型或被排除），已回落到普通工具调用")
+    return { enabled: false }
+  }
+
+  const sandboxTools = injectAppContext(tools, opts.context) as CodeModeTool[]
+  // 片段函数体在嵌套沙箱里只能看到这里的绑定：既保证片段不豁免归属校验
+  //（AppContext 已注入），也保证片段之间不可互相调用（无递归沙箱）。
+  const externalBindings: Record<string, ToolBinding> = toolsToBindings(sandboxTools, "external_")
+
+  const result = createCodeMode({
+    driver: sandbox.driver,
+    tools: sandboxTools,
+    memoryLimit: CODE_MODE_MEMORY_LIMIT_MB,
+    timeout: CODE_MODE_TIMEOUT_MS,
+    onSecretParameter: warnSecretParameterOnce,
+    lazyToolsConfig: { includeDescription: "first-sentence" },
+    getSnippetBindings: () =>
+      buildSnippetBindings({
+        userId: opts.context.userId,
+        driver: sandbox.driver,
+        externalBindings,
+        timeout: CODE_MODE_TIMEOUT_MS,
+        memoryLimit: CODE_MODE_MEMORY_LIMIT_MB,
+        warn: (message) => warnOnce(`snippet:${message}`, message),
+      }),
+  })
+
+  return {
+    enabled: true,
+    systemPrompts: [result.systemPrompt],
+    tools: result.tools,
+  }
+}
+
+/**
+ * 开关可用性探测（供 UI 查询是否呈禁用态）。env 未开时立即返回，
+ * 不触碰动态 import；env 开启时才触发一次沙箱探测并进程内缓存。
+ */
+export async function getCodeModeReadiness(): Promise<CodeModeReadiness> {
+  if (!isCodeModeEnvEnabled()) {
+    return { enabled: false, reason: "disabled" }
+  }
+  const sandbox = await loadSandbox()
+  if (sandbox.kind === "unavailable") {
+    return {
+      enabled: false,
+      reason: "sandbox-unavailable",
+      detail: sandbox.reason,
+    }
+  }
+  return { enabled: true, reason: null }
+}
+
+export function resetCodeModeCacheForTest(): void {
+  resetSandboxCacheForTest()
+  warnedKeys.clear()
+  warnedSecrets.clear()
+}
+
+export { setSandboxLoaderForTest, setSandboxRuntimeProbeForTest } from "./sandbox"

package/src/server/ai-gateway/code-mode/sandbox.ts

@@ -0,0 +1,213 @@
+// SPDX-License-Identifier: AGPL-3.0-or-later
+// AllBlue - 理想之海
+// Copyright (C) 2026 AllBlue Contributors
+//
+// This program is free software: you can redistribute it and/or modify
+// it under the terms of the GNU Affero General Public License as published by
+// the Free Software Foundation, either version 3 of the License, or
+// (at your option) any later version.
+//
+// This program is distributed in the hope that it will be useful,
+// but WITHOUT ANY WARRANTY; without even the implied warranty of
+// MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
+// GNU Affero General Public License for more details.
+//
+// You should have received a copy of the GNU Affero General Public License
+// along with this program. If not, see <https://www.gnu.org/licenses/>.
+
+import { spawnSync } from "node:child_process"
+import type { IsolateDriver } from "@tanstack/ai-code-mode"
+
+import { createVmIsolateDriver } from "./vm-driver"
+
+/**
+ * 编排程序批量调用多个工具（每次 external_* 调用是宿主侧的数据库/检索往返），
+ * 默认 30s 在 2-3 次串联调用下必然超时；放宽到 120s 仍远小于 chat 层链路时限。
+ */
+export const CODE_MODE_TIMEOUT_MS = 120_000
+
+/**
+ * 沙箱内需解析多个工具的 JSON 结果（知识库片段、联网搜索结果均含正文），
+ * 默认 128MB 容易被数 KB 级结果数组打满，放宽到 256MB。
+ */
+export const CODE_MODE_MEMORY_LIMIT_MB = 256
+
+const DEEP_PROBE_TIMEOUT_MS = 20_000
+
+export type SandboxState =
+  | { kind: "ready"; driver: IsolateDriver }
+  | { kind: "unavailable"; reason: string }
+
+type IsolateNodeModule = typeof import("@tanstack/ai-isolate-node")
+
+function describeError(err: unknown): string {
+  return err instanceof Error ? err.message : String(err)
+}
+
+/**
+ * 动态 import 是 segfault 的第一道防线：`@tanstack/ai-isolate-node` 顶层
+ * `import ivm from "isolated-vm"`，原生模块未编译或无法解析时该 import 直接拒绝；
+ * 静态 import 会把这条加载链拉进每次模块初始化，失败时无法隔离。
+ */
+const defaultDriverLoader = () => import("@tanstack/ai-isolate-node")
+
+function resolveDriverUrl(): string | null {
+  try {
+    return import.meta.resolve("@tanstack/ai-isolate-node")
+  } catch {
+    return null
+  }
+}
+
+/**
+ * 子进程深探测：官方 probeIsolatedVm 只验证 `new ivm.Isolate()` 构造，
+ * 而真正会 crash 的是 `isolate.createContext()` + `context.eval()`——
+ * 本机实测「Isolate 可构造但 createContext 直接 libc++abi 终止进程」的组合，
+ * 该终止是进程级 abort，任何 JS try/catch 都拦不住。
+ * 因此在子进程里跑完一遍完整的 createContext → execute → dispose，
+ * 用子进程的退出码/信号判定，宿主进程始终不受影响。
+ *
+ * 探测失败一律降级（跳过深探测、回落到普通工具调用），绝不在宿主进程内执行。
+ */
+async function defaultRuntimeProbe(driverUrl: string): Promise<boolean> {
+  const script = `
+const mod = await import(process.argv[1]);
+const probe = mod.probeIsolatedVm();
+if (!probe.compatible) {
+  console.error("PROBE_INCOMPATIBLE " + (probe.error || "unknown"));
+  process.exit(3);
+}
+const driver = mod.createNodeIsolateDriver({
+  skipProbe: true,
+  memoryLimit: 8,
+  timeout: 5000,
+});
+const ctx = await driver.createContext({ bindings: {} });
+const result = await ctx.execute("return 1");
+await ctx.dispose();
+if (result.success && result.value === 1) process.exit(0);
+process.exit(4);
+`
+  try {
+    const result = spawnSync(
+      process.execPath,
+      ["--input-type=module", "-e", script, driverUrl],
+      { timeout: DEEP_PROBE_TIMEOUT_MS, encoding: "utf8" },
+    )
+    if (result.error) return false
+    if (result.signal) {
+      return false
+    }
+    return result.status === 0
+  } catch {
+    return false
+  }
+}
+
+let driverLoader: () => Promise<IsolateNodeModule> = defaultDriverLoader
+let runtimeProbe: (driverUrl: string) => Promise<boolean> = defaultRuntimeProbe
+
+export function setSandboxLoaderForTest(
+  loader: (() => Promise<IsolateNodeModule>) | null,
+): void {
+  driverLoader = loader ?? defaultDriverLoader
+}
+
+export function setSandboxRuntimeProbeForTest(
+  probe: ((driverUrl: string) => Promise<boolean>) | null,
+): void {
+  runtimeProbe = probe ?? defaultRuntimeProbe
+}
+
+async function probeIsolatedVmDriver(): Promise<SandboxState> {
+  let mod: IsolateNodeModule
+  try {
+    mod = await driverLoader()
+  } catch (err) {
+    return {
+      kind: "unavailable",
+      reason: `无法加载 @tanstack/ai-isolate-node（pnpm-workspace allowBuilds 中 isolated-vm=false 时原生模块未编译）：${describeError(err)}`,
+    }
+  }
+
+  const probe = mod.probeIsolatedVm()
+  if (!probe.compatible) {
+    return {
+      kind: "unavailable",
+      reason: `isolated-vm 与当前 Node ${process.version} 不兼容：${probe.error ?? "probe failed"}`,
+    }
+  }
+
+  const driverUrl = resolveDriverUrl()
+  if (driverUrl) {
+    try {
+      if (!(await runtimeProbe(driverUrl))) {
+        return {
+          kind: "unavailable",
+          reason: `isolated-vm 子进程深探测未通过（createContext/execute 路径会 crash 进程，已隔离在子进程内判定）`,
+        }
+      }
+    } catch {
+      return {
+        kind: "unavailable",
+        reason: "isolated-vm 子进程深探测异常，已回落到普通工具调用",
+      }
+    }
+  }
+
+  try {
+    const driver = mod.createNodeIsolateDriver({
+      memoryLimit: CODE_MODE_MEMORY_LIMIT_MB,
+      timeout: CODE_MODE_TIMEOUT_MS,
+      skipProbe: false,
+    })
+    return { kind: "ready", driver }
+  } catch (err) {
+    return {
+      kind: "unavailable",
+      reason: `isolated-vm driver 构造失败：${describeError(err)}`,
+    }
+  }
+}
+
+async function probeSandbox(): Promise<SandboxState> {
+  const isolated = await probeIsolatedVmDriver()
+  if (isolated.kind === "ready") return isolated
+
+  // node:vm 兜底：isolated-vm 原生模块编译失败（托管运行时无 prebuilds）时，
+  // 用零原生依赖的 node:vm 驱动让编排模式在生产环境可用，而非整体不可用。
+  console.warn(`[code-mode] isolated-vm 不可用，回落 node:vm 驱动：${isolated.reason}`)
+  try {
+    const driver = createVmIsolateDriver({
+      memoryLimit: CODE_MODE_MEMORY_LIMIT_MB,
+      timeout: CODE_MODE_TIMEOUT_MS,
+    })
+    return { kind: "ready", driver }
+  } catch (err) {
+    return {
+      kind: "unavailable",
+      reason: `isolated-vm 与 node:vm 双路径均失败：${describeError(err)}`,
+    }
+  }
+}
+
+let cached: Promise<SandboxState> | null = null
+
+/**
+ * 探测结果进程内单例：首次请求触发动态 import + 官方 probe + 子进程深探测，
+ * 后续请求（含每个 chat 请求）直接复用同一份结果，不再探测。
+ * 缓存的是 promise 而非 state——对 module 级变量在 `.then` 回调内做
+ * `cached = state` 赋值会让 TS 丢掉显式声明的联合类型，直接缓存 promise 即可。
+ */
+export function loadSandbox(): Promise<SandboxState> {
+  if (!cached) {
+    cached = probeSandbox()
+  }
+  return cached
+}
+
+export function resetSandboxCacheForTest(): void {
+  cached = null
+  setSandboxLoaderForTest(null)
+  setSandboxRuntimeProbeForTest(null)
+}

package/src/server/ai-gateway/code-mode/snippets.ts

@@ -0,0 +1,235 @@
+// SPDX-License-Identifier: AGPL-3.0-or-later
+// AllBlue - 理想之海
+// Copyright (C) 2026 AllBlue Contributors
+//
+// This program is free software: you can redistribute it and/or modify
+// it under the terms of the GNU Affero General Public License as published by
+// the Free Software Foundation, either version 3 of the License, or
+// (at your option) any later version.
+//
+// This program is distributed in the hope that it will be useful,
+// but WITHOUT ANY WARRANTY; without even the implied warranty of
+// MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
+// GNU Affero General Public License for more details.
+//
+// You should have received a copy of the GNU Affero General Public License
+// along with this program. If not, see <https://www.gnu.org/licenses/>.
+
+import { prisma } from "@allbluecn/database"
+import type { IsolateDriver, ToolBinding } from "@tanstack/ai-code-mode"
+import { stripTypeScript } from "@tanstack/ai-code-mode"
+
+/**
+ * 编排模式可复用片段（CodeSnippet 表）→ 沙箱绑定。
+ *
+ * 片段是用户保存的跨请求编排逻辑：每次请求经 getSnippetBindings 从 DB 加载，
+ * 暴露为 snippet_<name>(args) 绑定。片段体是函数体形态——可读 args、await
+ * external_* 工具、用 return 交还结果——在**嵌套沙箱**里执行，因此能把一串
+ * 工具调用固化成一次调用，避免模型每轮重新推导同一段编排。
+ *
+ * 安全边界（沙箱即边界，不额外设易误伤的静态正则）：
+ * - 片段体只在服务端沙箱执行，不进客户端 bundle；external_* 绑定已注入
+ *   AppContext，片段不豁免归属校验。
+ * - 嵌套上下文只注入 external_*，不含其他片段绑定 → 片段间不可互调，
+ *   从结构上排除递归沙箱与无限展开。
+ * - 宿主 API（require/process/Buffer/fetch 等）在干净上下文中本就不可见，
+ *   无 SSRF / 提权面；CPU 炸弹与超时由驱动层 timeout + 调用次数上限兜住。
+ * - 单条片段执行独立建上下文并 dispose；执行失败抛错让模型看到并重试，
+ *   绝不把异常漏进 chat 链路。
+ * - 加载失败（DB 异常）或单条不合法一律降级：前者返回空绑定，后者跳过 + warn。
+ *   片段是可选增强，不能成为对话链路的失败点。
+ */
+
+export const SNIPPET_PREFIX = "snippet_"
+export const MAX_SNIPPETS_PER_USER = 20
+export const SNIPPET_CODE_MAX_CHARS = 8_000
+export const SNIPPET_NAME_MAX_CHARS = 48
+
+const IDENTIFIER_RE = /^[a-zA-Z_$][a-zA-Z0-9_$]*$/
+
+const RESERVED = new Set([
+  "do", "if", "in", "for", "let", "new", "try", "var", "else",
+  "case", "void", "with", "catch", "false", "null", "super",
+  "throw", "true", "typeof", "delete", "export", "import", "public",
+  "yield", "class", "const", "enum", "eval", "float", "int",
+  "long", "interface", "package", "private", "protected", "static",
+  "switch", "this", "while", "break", "default", "function",
+  "return", "continue", "debugger", "instanceof", "extends",
+])
+
+/** params JSON 的合法形状：参数名 → 类型 + 说明 + 是否必填 */
+export type ParamSpec = {
+  type?: "string" | "number" | "boolean" | "object" | "array"
+  description?: string
+  required?: boolean
+}
+
+export interface CodeSnippetRow {
+  name: string
+  title: string
+  description: string
+  params: unknown
+  code: string
+}
+
+export function isSafeSnippetName(name: string): boolean {
+  if (name.length === 0 || name.length > SNIPPET_NAME_MAX_CHARS) return false
+  return IDENTIFIER_RE.test(name) && !RESERVED.has(name)
+}
+
+function parseParams(raw: unknown): Record<string, ParamSpec> {
+  if (typeof raw !== "object" || raw === null || Array.isArray(raw)) return {}
+  const out: Record<string, ParamSpec> = {}
+  for (const [key, value] of Object.entries(raw as Record<string, unknown>)) {
+    if (!IDENTIFIER_RE.test(key)) continue
+    if (typeof value === "string") {
+      out[key] = { description: value }
+      continue
+    }
+    if (typeof value === "object" && value !== null) out[key] = value as ParamSpec
+  }
+  return out
+}
+
+export function buildSnippetInputSchema(params: unknown): Record<string, unknown> {
+  const properties: Record<string, unknown> = {}
+  const required: string[] = []
+  for (const [name, spec] of Object.entries(parseParams(params))) {
+    const prop: Record<string, unknown> = { type: spec.type ?? "string" }
+    if (spec.description) prop.description = spec.description
+    properties[name] = prop
+    if (spec.required === true) required.push(name)
+  }
+  const schema: Record<string, unknown> = {
+    type: "object",
+    properties,
+    additionalProperties: true,
+  }
+  if (required.length > 0) schema.required = required
+  return schema
+}
+
+/**
+ * 片段参数 → JS 字面量。JSON 是合法 JS 字面量语法，直接内联即无注入面；
+ * U+2028/U+2029 在 JSON 里不转义但在 JS 源码中是行终止符，必须补转义。
+ */
+function embedArgs(args: unknown): string {
+  return JSON.stringify(args ?? {})
+    .replace(/\u2028/g, "\\u2028")
+    .replace(/\u2029/g, "\\u2029")
+}
+
+/**
+ * 片段参数 + 片段体 → 交给驱动执行的脚本。
+ * 驱动内部会自行 wrapCode（顶层 await + 结果序列化），这里只做两件事：
+ * 内联 args 字面量，以及剥掉 TypeScript 语法。
+ */
+async function buildSnippetScript(code: string, args: unknown): Promise<string> {
+  return `const args = ${embedArgs(args)}\n${await stripTypeScript(code)}`
+}
+
+export interface BuildSnippetBindingsOptions {
+  userId: string
+  driver: IsolateDriver
+  /** 外层已注入 AppContext 的工具绑定（external_*），片段体内可调用 */
+  externalBindings: Record<string, ToolBinding>
+  timeout: number
+  memoryLimit: number
+  warn?: (message: string) => void
+}
+
+export async function loadEnabledSnippets(userId: string): Promise<CodeSnippetRow[]> {
+  const rows = await prisma.codeSnippet.findMany({
+    where: { userId, enabled: true, isDeleted: false },
+    orderBy: { createdAt: "asc" },
+    take: MAX_SNIPPETS_PER_USER,
+  })
+  return rows.map((row) => ({
+    name: row.name,
+    title: row.title,
+    description: row.description,
+    params: row.params,
+    code: row.code,
+  }))
+}
+
+/** 用户已启用片段 → snippet_<name> 绑定表。单条不合法跳过 + warn，不影响其他片段。 */
+export async function buildSnippetBindings(
+  opts: BuildSnippetBindingsOptions,
+): Promise<Record<string, ToolBinding>> {
+  const { userId, driver, externalBindings, timeout, memoryLimit } = opts
+  const warn = opts.warn ?? console.warn
+
+  let rows: CodeSnippetRow[]
+  try {
+    rows = await loadEnabledSnippets(userId)
+  } catch (err) {
+    warn(
+      `[code-mode] 片段加载失败，已回落到无片段编排：${
+        err instanceof Error ? err.message : String(err)
+      }`,
+    )
+    return {}
+  }
+
+  const bindings: Record<string, ToolBinding> = {}
+  for (const row of rows) {
+    const name = row.name.trim()
+    if (!isSafeSnippetName(name)) {
+      warn(`[code-mode] 片段 "${row.name}" 名称不是合法标识符，已跳过`)
+      continue
+    }
+    const code = row.code.trim()
+    if (!code) {
+      warn(`[code-mode] 片段 "${name}" 代码为空，已跳过`)
+      continue
+    }
+    if (code.length > SNIPPET_CODE_MAX_CHARS) {
+      warn(`[code-mode] 片段 "${name}" 代码超过 ${SNIPPET_CODE_MAX_CHARS} 字符，已跳过`)
+      continue
+    }
+    const bindingName = `${SNIPPET_PREFIX}${name}`
+    if (bindingName in bindings) {
+      warn(`[code-mode] 片段 "${name}" 绑定名重复，已跳过`)
+      continue
+    }
+
+    bindings[bindingName] = {
+      name: bindingName,
+      description: row.description.trim() || `${row.title.trim() || name}（用户片段）`,
+      inputSchema: buildSnippetInputSchema(row.params),
+      execute: async (args) => {
+        let script: string
+        try {
+          script = await buildSnippetScript(code, args)
+        } catch (err) {
+          throw new Error(
+            `片段 "${name}" 语法非法：${err instanceof Error ? err.message : String(err)}`,
+          )
+        }
+
+        const context = await driver.createContext({
+          bindings: externalBindings,
+          timeout,
+          memoryLimit,
+        })
+        try {
+          const result = await context.execute<unknown>(script)
+          if (!result.success) {
+            const detail = result.logs?.length
+              ? `｜日志：${result.logs.join(" ")}`
+              : ""
+            throw new Error(
+              `片段 "${name}" 执行失败：${result.error?.message ?? "未知错误"}${detail}`,
+            )
+          }
+          return result.value
+        } finally {
+          await context.dispose()
+        }
+      },
+    }
+  }
+
+  return bindings
+}