nolo-cli 0.1.13 → 0.1.15

package/ai/tools/agent/createDialogTool.ts

@@ -0,0 +1,69 @@
+// 文件路径: ai/tools/agent/createDialogTool.ts
+
+import type { RootState } from "app/store";
+import { createDialogAction } from "chat/dialog/actions/createDialogAction";
+import { streamAgentChatTurn } from "ai/agent/agentSlice";
+
+export const createDialogFunctionSchema = {
+    name: "createDialog",
+    description:
+        "创建一个新的对话（Dialog），可以指定由哪个 Agent 来响应，并可选地发送第一条消息触发 Agent 立即执行。" +
+        "常用于：派生子任务对话、让某个专用 Agent 在后台处理问题、睡前布置任务等场景。" +
+        "返回 dialogId，可通过 read({ dbKey: dialogId }) 随时查看对话结果。",
+    parameters: {
+        type: "object",
+        properties: {
+            agentKey: {
+                type: "string",
+                description: "负责响应这个对话的 Agent ID（dbKey，格式如 agent-xxx）。",
+            },
+            firstMessage: {
+                type: "string",
+                description: "可选。创建对话后立即发送的第一条消息，Agent 会自动开始执行。如果不传则只创建空对话。",
+            },
+            title: {
+                type: "string",
+                description: "可选。对话标题，方便后续识别。",
+            },
+        },
+        required: ["agentKey"],
+    },
+};
+
+export const createDialogFunc = async (
+    args: { agentKey: string; firstMessage?: string; title?: string },
+    context: { getState: () => RootState; dispatch: any }
+) => {
+    const { agentKey, firstMessage, title } = args;
+    const { getState, dispatch } = context;
+
+    const dialogConfig = await createDialogAction(
+        {
+            // TODO: 后续改为 [agentKey, ...subAgents] 组合，支持多 Agent 协作
+            // 目前仅使用主 agentKey 作为 cybots[0]
+            cybots: [agentKey],
+            title: title ?? `Dialog with ${agentKey}`,
+        },
+        { getState, dispatch }
+    );
+
+    const dialogId = dialogConfig.id;
+
+    if (firstMessage) {
+        void dispatch(
+            streamAgentChatTurn({
+                agentKey,
+                userInput: firstMessage,
+                dialogKey: dialogConfig.dbKey,
+            })
+        );
+    }
+
+    return {
+        dialogId,
+        dialogKey: dialogConfig.dbKey,
+        message: firstMessage
+            ? `已创建对话并发送任务，Agent 正在后台执行。可通过 read({ dbKey: "${dialogConfig.dbKey}" }) 查看进度。`
+            : `已创建空对话。可通过 read({ dbKey: "${dialogConfig.dbKey}" }) 查看。`,
+    };
+};

package/ai/tools/agent/createSkillAgentTool.ts

@@ -0,0 +1,62 @@
+import { createAgentToolFunc } from "./createAgentTool";
+import {
+  buildCreateSkillAgentArgs,
+  type CreateSkillAgentToolArgs,
+} from "./skillAgentArgs";
+
+export const createSkillAgentToolFunctionSchema = {
+  name: "createSkillAgent",
+  description:
+    "创建一个专门用于创建/评估 skill 文档协议的 Agent，支持 creator、evaluator 或二合一模式。",
+  parameters: {
+    type: "object",
+    properties: {
+      mode: {
+        type: "string",
+        enum: ["creator", "evaluator", "creator_evaluator"],
+        description: "要创建的 skill agent 类型。",
+      },
+      name: {
+        type: "string",
+        description: "可选：Agent 名称。",
+      },
+      model: {
+        type: "string",
+        description: "可选：覆盖默认模型。",
+      },
+      provider: {
+        type: "string",
+        description: "可选：覆盖默认 provider。",
+      },
+      isPublic: {
+        type: "boolean",
+        description: "可选：是否公开。",
+      },
+      references: {
+        type: "array",
+        description: "可选：创建后默认挂载的 references。",
+        items: {
+          type: "object",
+          properties: {
+            dbKey: { type: "string" },
+            title: { type: "string" },
+            type: { type: "string", enum: ["knowledge", "instruction", "page"] },
+          },
+          required: ["dbKey"],
+        },
+      },
+      linkedSpaces: {
+        type: "array",
+        items: { type: "string" },
+        description: "可选：额外挂载的 linked spaces。",
+      },
+    },
+  } as const,
+};
+
+export async function createSkillAgentToolFunc(
+  args: CreateSkillAgentToolArgs,
+  thunkApi: any
+): Promise<{ rawData: unknown; displayData: string }> {
+  return createAgentToolFunc(buildCreateSkillAgentArgs(args), thunkApi);
+}

package/ai/tools/agent/parallelBudget.ts

@@ -0,0 +1,221 @@
+import { prepareTokenUsageData } from "ai/token/prepareTokenUsageData";
+import type { RawUsage } from "ai/token/types";
+
+const roundCredits = (value: number) => Number(value.toFixed(6));
+const toRoundedFiniteNumber = (value: unknown): number | null =>
+  typeof value === "number" && Number.isFinite(value) ? roundCredits(value) : null;
+const getUsageCost = (usage: unknown): number | null => {
+  if (!usage || typeof usage !== "object") {
+    return null;
+  }
+  const cost = (usage as { cost?: unknown }).cost;
+  return typeof cost === "number" && Number.isFinite(cost) && cost >= 0
+    ? roundCredits(cost)
+    : null;
+};
+const getUsageBillingServiceTier = (usage: unknown): string | null => {
+  if (!usage || typeof usage !== "object") {
+    return null;
+  }
+  const serviceTier = (usage as { billing_service_tier?: unknown }).billing_service_tier;
+  return typeof serviceTier === "string" && serviceTier.trim()
+    ? serviceTier.trim()
+    : null;
+};
+
+const normalizePositiveNumber = (value: unknown): number | undefined => {
+  if (typeof value !== "number" || !Number.isFinite(value) || value <= 0) {
+    return undefined;
+  }
+  return roundCredits(value);
+};
+
+export const normalizeBudgetCredits = (value: unknown): number | undefined =>
+  normalizePositiveNumber(value);
+
+export interface ParallelBranchPricingInput {
+  usage?: unknown;
+  agentKey: string;
+  dialogId?: string | null;
+  agentConfig: {
+    id?: string;
+    model?: string | null;
+    provider?: string | null;
+    inputPrice?: number | null;
+    outputPrice?: number | null;
+  };
+}
+
+export interface ParallelBranchPricingResult {
+  spentCredits: number | null;
+  billedModel: string | null;
+  billedProvider: string | null;
+  billingServiceTier: string | null;
+  pricingError: string | null;
+}
+
+export const calculateParallelBranchPricing = (
+  input: ParallelBranchPricingInput
+): ParallelBranchPricingResult => {
+  if (!input.usage || typeof input.usage !== "object") {
+    return {
+      spentCredits: null,
+      billedModel: null,
+      billedProvider: null,
+      billingServiceTier: null,
+      pricingError: "missing usage",
+    };
+  }
+
+  const model =
+    typeof input.agentConfig.model === "string" && input.agentConfig.model.trim()
+      ? input.agentConfig.model.trim()
+      : null;
+  const provider =
+    typeof input.agentConfig.provider === "string" && input.agentConfig.provider.trim()
+      ? input.agentConfig.provider.trim()
+      : null;
+  const fallbackUsageCost = getUsageCost(input.usage);
+  const fallbackBillingServiceTier = getUsageBillingServiceTier(input.usage);
+  if (!model) {
+    return {
+      spentCredits: null,
+      billedModel: null,
+      billedProvider: null,
+      billingServiceTier: null,
+      pricingError: "missing model",
+    };
+  }
+
+  try {
+    const prepared = prepareTokenUsageData({
+      rawUsage: input.usage as RawUsage,
+      agentConfig: {
+        id: input.agentConfig.id ?? input.agentKey,
+        model,
+        ...(typeof input.agentConfig.provider === "string" &&
+        input.agentConfig.provider.trim()
+          ? { provider: input.agentConfig.provider.trim() }
+          : {}),
+        ...(typeof input.agentConfig.inputPrice === "number" &&
+        Number.isFinite(input.agentConfig.inputPrice)
+          ? { inputPrice: input.agentConfig.inputPrice }
+          : {}),
+        ...(typeof input.agentConfig.outputPrice === "number" &&
+        Number.isFinite(input.agentConfig.outputPrice)
+          ? { outputPrice: input.agentConfig.outputPrice }
+          : {}),
+      },
+      cybotId: input.agentKey,
+      dialogId: input.dialogId ?? `parallel-${input.agentKey}`,
+    });
+    const preparedCost = toRoundedFiniteNumber(prepared.tokenData.cost);
+    if (preparedCost != null) {
+      return {
+        spentCredits: preparedCost,
+        billedModel: prepared.billedModel,
+        billedProvider: prepared.recordProvider,
+        billingServiceTier: prepared.billedServiceTier ?? null,
+        pricingError: null,
+      };
+    }
+
+    if (fallbackUsageCost != null) {
+      return {
+        spentCredits: fallbackUsageCost,
+        billedModel: prepared.billedModel ?? model,
+        billedProvider: prepared.recordProvider ?? provider,
+        billingServiceTier:
+          prepared.billedServiceTier ?? fallbackBillingServiceTier ?? null,
+        pricingError: null,
+      };
+    }
+
+    return {
+      spentCredits: null,
+      billedModel: null,
+      billedProvider: null,
+      billingServiceTier: null,
+      pricingError: "invalid cost",
+    };
+  } catch (error: any) {
+    if (fallbackUsageCost != null) {
+      return {
+        spentCredits: fallbackUsageCost,
+        billedModel: model,
+        billedProvider: provider,
+        billingServiceTier: fallbackBillingServiceTier,
+        pricingError: null,
+      };
+    }
+    return {
+      spentCredits: null,
+      billedModel: null,
+      billedProvider: null,
+      billingServiceTier: null,
+      pricingError: error?.message || String(error),
+    };
+  }
+};
+
+export interface ParallelCostSummary {
+  spentCredits: number;
+  pricedBranches: number;
+  unpricedBranches: number;
+}
+
+export interface ParallelBudgetSummary extends ParallelCostSummary {
+  budgetCredits: number;
+  remainingCredits: number;
+  exhausted: boolean;
+}
+
+export const summarizeParallelCosts = (
+  results: Array<{ spentCredits?: number | null; ok?: boolean }>
+): ParallelCostSummary => {
+  const spentCredits = roundCredits(
+    results.reduce(
+      (sum, item) =>
+        sum +
+        (typeof item.spentCredits === "number" && Number.isFinite(item.spentCredits)
+          ? item.spentCredits
+          : 0),
+      0
+    )
+  );
+
+  return {
+    spentCredits,
+    pricedBranches: results.filter(
+      (item) => typeof item.spentCredits === "number" && Number.isFinite(item.spentCredits)
+    ).length,
+    unpricedBranches: results.filter(
+      (item) =>
+        item.ok &&
+        (item.spentCredits == null ||
+          (typeof item.spentCredits === "number" && !Number.isFinite(item.spentCredits)))
+    ).length,
+  };
+};
+
+export const summarizeParallelBudget = (input: {
+  budgetCredits?: number;
+  results: Array<{ spentCredits?: number | null; ok?: boolean }>;
+}): ParallelBudgetSummary | null => {
+  const budgetCredits = normalizePositiveNumber(input.budgetCredits);
+  if (budgetCredits === undefined) {
+    return null;
+  }
+
+  const costSummary = summarizeParallelCosts(input.results);
+  const remainingCredits = roundCredits(
+    Math.max(0, budgetCredits - costSummary.spentCredits)
+  );
+
+  return {
+    ...costSummary,
+    budgetCredits,
+    remainingCredits,
+    exhausted: remainingCredits <= 0,
+  };
+};

package/ai/tools/agent/presets/appBuilderPreset.ts

@@ -0,0 +1,147 @@
+/**
+ * App Builder 预设：面向非技术用户的网站型小应用构建助手配置
+ * 用途：在 AgentForm 中预填充，或通过 createAgent 工具一键创建
+ */
+import { FIREWORKS_KIMI_LATEST_MODEL } from "ai/llm/kimi";
+
+export const APP_BUILDER_PRESET = {
+  name: "App Builder",
+  introduction: "帮你把想法变成真正可以访问的网站型小应用，无需任何编程知识",
+  model: FIREWORKS_KIMI_LATEST_MODEL,
+  provider: "fireworks",
+  inputPrice: 7.6,
+  outputPrice: 32,
+  useServerProxy: true,
+  greeting:
+    `你好！我是 App Builder 🚀
+
+**如果你想改这个应用**，直接告诉我要改什么就行——
+• "把首页改得更温柔一点"
+• "加一个预约入口"
+• "让博客页更适合手机阅读"
+
+我会自动读取现有代码、修改并重新发布，你不需要动任何代码。
+
+**如果你想新建一个应用**，直接描述你想做的网站或小应用，我来帮你构建并生成可访问的链接。
+
+比如：个人品牌站、博客 + AI 分身、咨询预约页、作品集站、轻互动工具……`,
+  tools: [
+    "appPreflight",
+    "appDeploy",
+    "appList",
+    "appDelete",
+    "appRead",
+    "openAIGptImage",
+    "createTable",
+    "addTableRow",
+    "addTableRows",
+    "queryTableRows",
+    "updateTableRow",
+    "deleteTableRow",
+  ],
+  prompt: `你是一个应用构建助手，专门帮助没有任何编程经验的用户创建和管理 Web 应用。
+
+## 工作方式
+
+1. **理解需求**：用简单的对话了解用户想要什么，最多问 1-2 个关键问题，不要追问太多技术细节
+2. **自动构建**：根据用户描述，自动生成代码并调用部署工具，用户不需要看到任何代码
+3. **给出结果**：部署成功后，立即告诉用户可以访问的链接
+4. **持续迭代**：用户说"帮我加个功能"或"改一下样式"，先用 appList 找到目标应用，再用 appRead 读取现有代码；一旦拿到 appId，后续修改和重发都必须复用这个 appId
+5. **管理应用**：用户问"我有哪些应用"，先调用 appList；用户说"删掉它"时，也先从 appList 确认目标 appId，再按 appId 删除，不要靠 name 兜底
+6. **先预检再部署**：生成或修改完代码后，先调用 \`appPreflight\` 看问题；只有预检通过后再调用 \`appDeploy\`
+7. **收到 repairPlan 就直接修**：如果 \`appPreflight\` 或 \`appDeploy\` 返回 \`repairPlan\` / \`issues\`，立即基于当前代码做定点修复并重新预检，不要先问用户要不要修，也不要整页重写
+8. **遇到通道异常就止损**：如果工具返回 HTML / 非 JSON / transport failure / \`retryable=false\`，停止自动部署重试；这代表当前是平台接口异常，不是代码问题
+9. **看到部署产物先止损**：如果 \`appRead\` 读出来的是 HTML 壳、importmap、压缩 bundle，或明显不像原始源码文件，说明当前拿到的更像部署产物而不是可维护源码。此时如果用户只是想“小改一处”，不要静默整站重写；必须先告诉用户“当前缺少原始源码快照，继续修改更像整体重建”，得到确认后再继续。
+10. **视觉微调默认走设计系统**：用户说“字大一点”“颜色柔和一点”“卡片圆一点”这类小改动时，优先修改现有主题 token / design system；如果当前应用还没有，就先补一层最小共享 token（颜色、字号层级、间距、圆角、阴影），再基于 token 调整，不要顺手重做整页结构。
+11. **项目素材直接出图**：如果用户要首页插画、海报、封面、功能配图、活动横幅、按钮图标草图等视觉素材，优先调用 \`openAIGptImage\` 生成或改图，再把产物接入当前应用；不要只给文案描述。
+
+## 对话风格
+
+- 语气轻松友好，避免所有技术术语（不说 Worker、JavaScript、API、部署等词）
+- 部署成功后，用 1-2 句话说明应用能做什么、怎么使用
+- 如果用户描述模糊，举例说明你能做什么，让用户选择或细化
+- **绝不把代码展示给用户**，除非用户明确说"我想看代码"
+- 优先把需求收敛成“内容驱动的网站型小应用”：个人品牌站、博客 + AI 助手、咨询/预约站、作品集、知识站、轻互动工具
+
+## 技术规范（内部遵守，不暴露给用户）
+
+简单应用可以直接生成 \`export default { fetch }\`。
+复杂交互、图表、组件化界面优先使用 React SPA 模式：调用 \`appDeploy\` 时传 \`framework: "react-spa"\` 和 \`files\`，推荐至少包含 \`main.tsx\` 与 \`App.tsx\`。
+严禁把 React 组件直接塞进 \`code\` 字段当单文件 Worker 部署；只要出现 \`import React\`、\`react-dom/client\`、\`createRoot\`、JSX 组件树，就必须走 \`framework: "react-spa"\` + \`files\`。
+如果上游临时生成的是 \`pages\` 字段，可直接原样传给 \`appDeploy\`，系统会兼容成 \`files\`；但你在新回复里应优先自己使用 \`files\` 命名。
+React SPA 当前优先支持这些内置依赖：\`react\`、\`react-dom/client\`、\`react-icons/lu\`、\`echarts\`、\`echarts-for-react\`、\`docx\`、\`@xyflow/react\`、\`three\`、\`@react-three/fiber\`、\`@react-three/drei\`、\`leaflet\`、\`react-leaflet\`、\`xlsx\`、\`d3\`、\`recharts\`、\`dayjs\`。
+React SPA 暂不使用 CSS 文件 import；优先用内联样式、style 对象或组件内 style 标签。像 flow / three 这类库如果默认文档依赖外部 CSS，请直接在应用内补最小必要样式，不要写 \`import "./x.css"\`。leaflet 的 CSS 会由平台自动注入，无需手动 import。
+
+**设计系统与小改动纪律**：
+- 新建 React SPA 时，默认先建立一层轻量设计系统（如 \`theme\` / \`tokens\` / \`designSystem\` 对象），至少统一：\`colors\`、\`typography\`、\`spacing\`、\`radius\`、\`shadow\`。
+- 如果现有应用已经有主题变量、token、共享样式常量或 design system，优先沿用和扩展，不要再平行创建第二套。
+- 如果现有应用还是旧写法：样式值直接硬编码在多个组件 / 内联 style / 重复常量里，而用户需求又是字体、颜色、间距、圆角、阴影这类视觉微调，默认先做一次**最小设计系统迁移**：把这批视觉值抽到一层很薄的 \`tokens\` / \`theme\` 对象（必要时可新增 \`tokens.ts\`），再让当前页面消费它。除非用户明确要求“只改数字不要重构”，否则不要继续在旧代码上追加更多分散硬编码。
+- 用户只要求调整字体大小、字重、颜色、圆角、阴影、间距等视觉参数时，优先改 token 或当前命中的局部组件；不要顺手改布局、组件树、文案、数据流、路由或整套页面结构。
+- 如果只是局部视觉修改，尽量把改动收敛在命中的 1-3 个文件；非必要不要重命名组件、改文件结构或大面积重新格式化。
+- 新增页面或模块时，也应消费同一套 token，避免不同页面各自写一套颜色和字号。
+
+**react-icons/lu 图标使用规范（违反会部署失败）**：
+- 只能使用 \`react-icons/lu\` 中实际存在的图标，如 \`LuCode\`、\`LuMap\`、\`LuChart\`、\`LuSearch\`、\`LuSettings\`、\`LuStar\`
+- 常见错误：\`LuCode2\`（不存在，应用 \`LuCode\`）、\`LuGithub\`（不存在，用 \`LuGitBranch\`）
+- 不确定时优先用基础图标：\`LuCircle\`、\`LuCheck\`、\`LuX\`、\`LuPlus\`、\`LuMinus\`、\`LuInfo\`、\`LuArrowRight\`
+- 每次使用图标前确认名称已知存在，不要猜测或推断变体名称
+
+构建要求：
+- 响应式设计，手机和电脑都正常显示
+- 简洁现代的中文界面（用户未指定语言时默认中文）
+- 对计算/工具类应用：优先产出可直接访问的页面；复杂页面优先 React SPA
+- 对数据接口：返回规范 JSON，设置正确的 Content-Type
+- 代码质量：干净、无注释堆砌、运行稳定
+
+**大数据文件处理规范**：
+- 绝对禁止把大型数据（JSON 数组、GeoJSON、CSV 解析结果等超过 50KB 的数据）直接内嵌到代码里作为常量
+- 用户通过对话上传的文件已存储在 nolo.chat，必须通过运行时 fetch 加载，URL 格式为：\`https://nolo.chat/api/database/file/content/{fileKey}\`
+- 对话中提到"用这个文件"/"用我上传的数据"时，先从消息历史或 appRead 里找 fileKey，用 fetch 加载，不要重新内嵌数据
+- 示例：\`const data = await fetch("https://nolo.chat/api/database/file/content/file-b2e06f801f-01XXXXX").then(r => r.json())\`
+- 此 URL 已开放 CORS，任何域名部署的应用都可以直接访问，无需鉴权
+
+部署时：
+- name 参数使用简洁的英文或拼音（如 brand-home、tarot-blog）
+- 默认发布到平台托管地址（nolo.chat/apps/{appId}/），这是用户分享给别人的链接
+- 更新应用时必须传入 appId，避免重复创建新应用
+- 读取和删除应用时必须使用 appId；如果还没有 appId，就先调用 appList 找到目标应用
+- 一旦通过 appList / appRead / appDeploy 拿到 appId，就把它当成后续操作的主标识
+- 如果现有应用是 React SPA，修改时继续沿用 React SPA + files，不要退回单文件 Worker
+- 如果 \`appRead\` 结果更像部署后的 bundle / HTML 壳，而不是源文件，不要假装自己拿到了可维护源码；这种情况下默认先提示用户风险，而不是直接覆盖整个应用
+- React SPA 首次部署前，先调用 \`appPreflight\`；重点检查：是否传了 \`files\`、是否包含 \`main.tsx\` 与 \`App.tsx\`、是否误用了 \`code\`
+- 如果首次部署失败，尝试调整代码重新部署，给用户友好的提示
+- 如果工具返回了 \`repairPlan\`：
+  - 严格按 repairPlan 只修改命中的文件 / 依赖 / 图标 / 入口，不要为了省事重建整个应用
+  - 默认继续在当前轮自动修复，不需要再次征求用户确认
+  - 修完后必须重新 \`appPreflight\`，通过后再 \`appDeploy\`
+- 如果工具返回 HTML 页面、非 JSON、transport failure 或 \`retryable=false\`：
+  - 立即停止自动 \`appDeploy\` / \`appPreflight\` 重试
+  - 不要把这种错误误判成图标/依赖/入口问题
+  - 直接告诉用户当前是平台部署通道异常，建议稍后再试
+
+表单/提交类功能：
+- 如果用户要做博客留言、联系表单、预约申请、订阅邮箱、反馈收集这类“收集记录”的功能，优先使用表工具，不要自己发明 JSON 文件存储结构。
+- 先调用 \`createTable\` 创建表，再把返回结果中的 \`tenantId\` 和 \`tableId\` 记住，随后让应用代码直接调用现有表接口（如 \`/api/table/add-row\`、\`/api/table/query-rows\`）。
+- 当前阶段允许把 \`tenantId\` 和 \`tableId\` 直接写进应用代码配置中；这是最小实现，目的是先把功能跑通。
+- 但在生成代码时，**必须在这两个字段附近添加简短注释**，明确说明：
+  1. 这里直接暴露了 \`tenantId/tableId\`，当前是最小实现；
+  2. 后续应替换为更安全的服务端映射或 app 级数据接口；
+  3. 当前表接口默认按用户自己可写模型工作，后续应补充额外权限控制。
+- **不要**把现有表接口直接当成公开留言/公开评论入口；未登录访客提交、公开写入、限流和防滥用策略需要后续单独设计。
+- 因此当前阶段更适合：用户自己管理的数据后台、登录后提交、站长自己录入或内部运营使用；不适合直接上线公开评论区。
+- 如果是博客应用，优先支持这些轻数据能力：评论/留言、订阅邮箱、联系反馈；文章正文、封面图、插图等内容资产优先继续使用文件。
+
+## 示例应答模板
+
+部署成功后：
+"✅ 你的应用已经好了！
+
+🔗 访问链接：[URL]
+
+这个应用可以帮你 [一句话功能描述]，直接打开链接就能使用，也可以把链接分享给任何人。
+
+想要修改或添加功能，直接告诉我就行！"
+`,
+} as const;
+
+export type AppBuilderPreset = typeof APP_BUILDER_PRESET;

package/ai/tools/agent/runLlmTool.ts

@@ -0,0 +1,96 @@
+// 文件路径: ai/tools/agent/runLlmTool.ts
+
+/**
+ * runLlm 工具
+ *
+ * 单轮 LLM 调用，不加载 Agent 的 references（知识库），不触发多轮 tool loop。
+ * 工具列表和系统提示均可在调用时覆盖 Agent 的默认配置。
+ *
+ * 与 callAgent 的区别：
+ * - runLlm：1 轮回复，不加载知识库；可携带工具但不会循环调用，更快且可预期
+ * - callAgent：可能多轮（agent 内部有 tool loop），带完整 agent 上下文
+ */
+
+import { runLlm } from "ai/agent/agentSlice";
+
+export const runLlmFunctionSchema = {
+    name: "runLlm",
+    description:
+        "对指定模型发起一次单轮 LLM 调用并返回结果。" +
+        "不加载 Agent 知识库（references），适合摘要、分类、格式化、翻译等纯文本处理任务。" +
+        "可选择注入临时系统提示或覆盖工具列表。",
+    parameters: {
+        type: "object",
+        properties: {
+            agentKey: {
+                type: "string",
+                description:
+                    "要使用的模型配置 ID。若不填，使用当前对话绑定的默认模型。",
+            },
+            userInput: {
+                type: "string",
+                description: "发送给模型的提示词或问题。",
+            },
+            systemPrompt: {
+                type: "string",
+                description:
+                    "可选。临时系统提示，会覆盖 Agent 原有配置中的 prompt。适合临时调整模型行为或角色。",
+            },
+            tools: {
+                type: "array",
+                items: { type: "string" },
+                description:
+                    "可选。工具 ID 列表，覆盖 Agent 默认配置的工具集。传空数组则禁用所有工具。",
+            },
+        },
+        required: ["userInput"],
+    },
+};
+
+interface RunLlmToolArgs {
+    agentKey?: string;
+    userInput: string;
+    systemPrompt?: string;
+    tools?: string[];
+}
+
+export async function runLlmToolFunc(
+    args: RunLlmToolArgs,
+    thunkApi: any,
+    _context?: { parentMessageId: string }
+): Promise<{ rawData: any; displayData?: string }> {
+    const { agentKey, userInput, systemPrompt, tools } = args;
+
+    if (!userInput?.trim()) {
+        throw new Error("runLlm: 缺少 userInput 参数。");
+    }
+
+    const { dispatch } = thunkApi;
+
+    try {
+        const result = await dispatch(
+            runLlm({
+                agentKey,
+                content: userInput,
+                isStreaming: false,
+                ...(systemPrompt !== undefined && { systemPromptOverride: systemPrompt }),
+                ...(tools !== undefined && { toolsOverride: tools }),
+            })
+        ).unwrap();
+
+        // 取前 60 字作为 header 摘要
+        const preview = typeof result === "string"
+            ? result.slice(0, 60) + (result.length > 60 ? "…" : "")
+            : "";
+
+        return {
+            rawData: { result, userInput },
+            displayData: preview || "✅ runLlm 完成",
+        };
+    } catch (e: any) {
+        const msg = e?.message || String(e);
+        throw new Error(`runLlm 调用失败: ${msg}`);
+    }
+}
+
+

package/ai/tools/agent/runStreamingAgentTool.ts

@@ -0,0 +1,73 @@
+// 路径: ai/tools/agent/runStreamingAgentTool.ts
+
+/**
+ * [Schema] 定义 'runStreamingAgent' 工具的结构，供 LLM 调用。
+ *
+ * 主要用于用户希望立刻看到回复的临时调用，无法后台运行。
+ * 调用后 Agent 的输出会以流式方式实时呈现给用户，适合需要即时反馈的场景。
+ *
+ * 注意：
+ * - 这里只是一个「数据工具」：返回要调用的 Agent 信息，不直接发起流式调用。
+ * - 真正的 streamAgentChatTurn 在 chat/messages/toolThunks.ts 的 handleToolCalls 里触发，
+ *   这样就可以做到：
+ *   1）先写标准的 tool 消息（符合 OpenAI 消息格式）
+ *   2）再启动一个生命周期独立的 streamAgentChatTurn
+ */
+export const runStreamingAgentFunctionSchema = {
+  name: "runStreamingAgent",
+  description:
+    "准备调用一个指定的 Agent (智能代理)，并以流式方式处理用户输入。该工具本身只返回要调用的 Agent 信息，实际流式调用由系统在工具执行后发起。",
+  parameters: {
+    type: "object",
+    properties: {
+      agentKey: {
+        type: "string",
+        description: "要运行的 Agent 的唯一标识符 (Key)。",
+      },
+      userInput: {
+        type: "string",
+        description: "要发送给该 Agent 的用户输入或问题。",
+      },
+      serverBase: {
+        type: "string",
+        description:
+          "可选。目标 Agent 所在的 nolo server origin，例如 Windows 机器通过 Cloudflare 暴露的 https://win.example.com。" +
+          "跨域目标必须由服务端 AGENT_TOOL_ALLOWED_SERVER_BASES 明确放行。" +
+          "如果目标 Agent 记录声明了 delegation.serverBase / runtimeServerBase，服务端会在未显式传入时自动路由。",
+      },
+    },
+    required: ["agentKey", "userInput"],
+  },
+};
+
+/**
+ * [Executor] 'runStreamingAgent' 工具执行函数。
+ *
+ * - 不直接发起 streamAgentChatTurn。
+ * - 返回 { agentKey, userInput }，供上层在写完 tool 消息后再启动真正的流式 Agent 调用。
+ */
+export async function runStreamingAgentFunc(
+  args: { agentKey: string; userInput: string; serverBase?: string },
+  _thunkApi: any,
+  _context?: { parentMessageId: string }
+): Promise<{ rawData: any; displayData: string }> {
+  const { agentKey, userInput, serverBase } = args;
+
+  if (!agentKey) {
+    throw new Error("调用 'runStreamingAgent' 失败：缺少 'agentKey' 参数。");
+  }
+  if (!userInput) {
+    throw new Error("调用 'runStreamingAgent' 失败：缺少 'userInput' 参数。");
+  }
+
+  // 这里只返回调用参数，由 handleToolCalls 决定何时真正发起流式调用
+  const rawData = {
+    agentKey,
+    userInput,
+    ...(serverBase ? { serverBase } : {}),
+  };
+
+  const displayData = `将调用 Agent(${agentKey}) 执行一轮流式对话`;
+
+  return { rawData, displayData };
+}