--- name: chatu-ai description: 平台 LLM 中继（@chatu-ai/app-sdk 的 ai）。含用量查询与月度配额（ai.usage / ai.setQuota）。当应用需要 AI 能力——对话/助手、摘要、翻译、润色、分类、信息抽取、结构化 JSON、图片理解、工具调用、语义检索/知识库、OCR/文档解析、AI 生图（文生图/图生图）、AI 视频生成（文生视频/图生视频）——时使用。禁止安装 openai / @anthropic-ai/sdk / ai(vercel) 直连模型，禁止让用户填 API Key。 --- # AI 能力（ai） 平台托管的 OpenAI 兼容中继：**不需要 API Key、不需要选模型**，用量计入应用所有者的 ChatU 点数。 **模型策略（不要问用户选模型）**：`ai.chat` / `ai.json` / `ai.stream` / `ai.runTools` 一律**不传 `model`**，用平台给这个应用配好的默认模型（沙箱与部署环境都注入了）。用户明确要换模型时，也不是改代码：告诉他在发布面板「环境变量」Tab 加 `CHATU_AI_MODEL=<模型 id>`，预览和部署同时生效。`ai.models()` 能列出当前可用的模型 id，**只用于**应用内要做"让最终用户自己选模型"的下拉框，或用户问"能用哪些模型"时给他看；平时不要调。生图 / 视频的 agent 选择同理：默认档不传，见下文各节的价格阶梯。 **参数以速查表为准，禁止试探**：本 SDK 全部方法的签名 / 参数 / 默认值 / 字段说明在 `chatu-quickstart/references/sdk-api.md`（随 SDK 自动生成，与工作区安装的版本一致）。不确定怎么传就查它；查不到的参数**不传、用默认值**。**不要**为了摸清接口写试探代码、发试探请求、读 `node_modules` 里的 `.d.ts`——这些都是白白消耗轮次。 ## 结构化输出：`ai.json` 需要"模型返回可直接用的对象"时不要让它回文本再自己抠字段——用 `ai.json`：强制只回 JSON、剥掉代码围栏、解析、可选校验，不合格会带着错误自动重试。 ```ts import { ai } from '@/lib/platform'; import { z } from 'zod'; const Result = z.object({ sentiment: z.enum(['正面', '中性', '负面']), reasons: z.array(z.string()).max(3) }); const data = await ai.json(`判断这条评论的情绪：${comment}`, { schema: z.toJSONSchema(Result), // 走 response_format: json_schema 硬约束（模型不支持时自动降级） validate: Result, // 直接传 zod schema（或 v => Result.parse(v)）；不合格自动重试，默认 1 次 retries: 2, }); data.sentiment; // 类型安全 ``` 不传 `validate` 也能用（只解析不校验），但线上强烈建议配 zod —— 见 `chatu-validation`。 ## API（只能在服务端调用） ```ts import { ai } from '@/lib/platform'; const { content, usage } = await ai.chat('用一句话介绍杭州'); // 字符串 = 单条 user 消息 const { content } = await ai.chat([ { role: 'system', content: '你是简洁的中文助手，只输出结论。' }, { role: 'user', content: text }, ], { temperature: 0.3, maxTokens: 500 }); const stream = ai.stream(messages, { signal }); for await (const delta of stream) { /* 文本增量 */ } stream.usage; // 迭代结束后可读（token 数） const vec = await ai.embed('一段文本'); // 向量，见「语义检索」 const { content: md } = await ai.ocr(bytes, { filename: 'a.pdf' }); // OCR，见「OCR」 const { images } = await ai.generateImage({ prompt: '海报主视觉' }); // 生图，见「AI 生图」 const { video } = await ai.generateVideo({ prompt: '产品展示短片' }); // 视频（异步轮询，很贵），见「AI 视频」 ``` `model` 可以不传（用平台默认）。返回的 `usage` 含 token 数，可用于展示。 ## 标准写法 A：一次性任务（摘要/翻译/分类） ```ts // src/app/api/summarize/route.ts import { ai } from '@/lib/platform'; export async function POST(req: Request) { const { text } = await req.json(); if (!text?.trim()) return Response.json({ error: 'EMPTY' }, { status: 400 }); const { content } = await ai.chat([ { role: 'system', content: '把用户文本压缩成不超过 50 字的中文摘要，只输出摘要本身。' }, { role: 'user', content: text }, ], { temperature: 0.2, maxTokens: 200 }); return Response.json({ summary: content }); } ``` ## 标准写法 B：流式对话（打字机效果） ```ts // src/app/api/chat/route.ts import { ai } from '@/lib/platform'; export async function POST(req: Request) { const { messages } = await req.json(); const enc = new TextEncoder(); return new Response( new ReadableStream({ async start(c) { try { for await (const delta of ai.stream(messages, { signal: req.signal })) c.enqueue(enc.encode(delta)); c.close(); } catch (e) { c.error(e); } }, }), { headers: { 'content-type': 'text/plain; charset=utf-8', 'cache-control': 'no-cache' } }, ); } ``` ```ts // 客户端：逐段渲染 const res = await fetch('/api/chat', { method: 'POST', body: JSON.stringify({ messages }) }); const reader = res.body!.getReader(); const dec = new TextDecoder(); for (;;) { const { value, done } = await reader.read(); if (done) break; setText((t) => t + dec.decode(value, { stream: true })); } ``` ## 标准写法 C：要结构化结果（JSON） 用上面的 `ai.json`，不要自己写"正则抠 JSON + try/catch"那一套。只有在需要流式输出结构化内容时才手写解析。 ## 选型：什么时候要先问用户 本 SKILL 里的能力**都按用量计入应用所有者的点数**，且多数都有零成本的简化替代。分两档处理（细则见 `chatu-quickstart`「必须先问用户的三个决策」第 3 条）： - **资料问答 / 知识库：动手前先问**。做不做语义检索决定了要不要建向量集合、上传时要不要切段入库，事后换要把已存的资料全部重新入库。 - **OCR、工具调用、图片理解、语义搜索、AI 生图、AI 视频**：别打断，**先用零成本的做法出第一版**（手工填表 / 先查好数据再喂模型 / 让用户文字描述 / 关键词过滤 / 让用户自己上传图片、视频或用占位素材），在总结里点明升级路径，用户要再升级——它们都是新增一条路径，不动已有数据。视频是其中最贵的（一条约 2~8 元），总结里升级路径必须带上这个价。 ## 图片理解（多模态） `content` 传片段数组即可；图片用公网 https URL，或用 `toDataUrl` 把上传的文件转成 data URL。 ```ts import { ai, toDataUrl } from '@/lib/platform'; const bytes = new Uint8Array(await file.arrayBuffer()); const { content } = await ai.chat([{ role: 'user', content: [ { type: 'text', text: '这张图里有什么？用中文回答' }, { type: 'image_url', image_url: { url: toDataUrl(bytes, file.type), detail: 'low' } }, ] }]); ``` 图片按 token 计费，`detail: 'low'` 便宜很多；大图先压缩到 1024px 以内。 ## 工具调用（让模型查数据再回答） ```ts const { content, steps } = await ai.runTools(question, { tools: [{ name: 'getOrder', description: '按订单号查订单状态', parameters: { type: 'object', properties: { orderNo: { type: 'string' } }, required: ['orderNo'] }, execute: async ({ orderNo }) => await getOrder(orderNo), // 返回值自动 JSON 化回填给模型 }], maxRounds: 5, // 最后一轮不再给工具，逼模型直接作答 }); ``` `execute` 里只做**只读查询或幂等操作**；删除/扣款这类动作要让模型只返回意图，由代码二次确认后执行。 想自己控制循环就用 `ai.chat(msgs, { tools })`，它只返回 `toolCalls` 不执行。 `ai.stream` **不支持工具**（流式只吐文本增量），传了会抛 `AI_STREAM_TOOLS_UNSUPPORTED`；要边用工具边流式，先 `runTools` 拿结果再流式复述。 ## 语义检索 / 知识库（RAG） `ai.embed` + `vectorSearch` 就能做"上传文档→按语义问答"。完整流程（切段、入库、检索、拼 prompt）见 `references/rag.md`。规模上限：单次检索候选 ≤ 2000 条，务必用 `filter` 按用户/文档缩小范围。 ## OCR / 文档解析 ```ts const { content, pages } = await ai.ocr(bytes, { // Uint8Array | ArrayBuffer | Blob filename: 'invoice.pdf', // pdf / png / jpg / tiff / docx / xlsx / pptx / html features: ['keyValuePairs'], // 可选附加能力，逐项按页额外计费 }); // content 是 Markdown（表格已转成 Markdown 表格），直接喂给 ai.chat / ai.json 抽字段 ``` **按页计费**，不要对同一文件重复调用——解析结果存进 `kv` / `db` 复用。 ## AI 生图（文生图 / 图生图） ```ts // src/app/api/generate-image/route.ts import { ai, storage } from '@/lib/platform'; export async function POST(req: Request) { const { prompt } = await req.json(); if (!prompt?.trim()) return Response.json({ error: 'EMPTY' }, { status: 400 }); const { images } = await ai.generateImage({ prompt, // 中英文都行；把风格/构图/用途写清楚 count: 1, // 每张都计费，默认 1 size: '2K', // '1K' | '2K' | '4K'、'16:9' 或 '1024x1024'，SDK 按 agent 映射 // agent: 'NanoBanana', // 不传用平台默认（最便宜的 Seedream4） // referenceImages: [url], // 图生图 / 风格参考（Image2 不支持） }); return Response.json({ url: images[0].url }); } ``` - **同步等待**：通常 5~60 秒，多图高质量可到 2~3 分钟。页面要有"生成中"状态；Route Handler 别设短超时；不要在页面加载时自动触发。 - **按张计费到应用所有者**，失败不扣费。`count` 别默认给多张；同一提示词的结果存进 `db`/`kv` 或用 `storage` 存下来复用，不要每次刷新都重新生成。 - 返回的 `images[].url` 是平台托管地址，可直接 `` 展示；要长期保存或改名就用 `storage` 转存。 - 可选 agent：`Seedream4`（默认，最便宜）、`Seedream5Lite` / `Seedream45` / `Seedream5Pro`（质量递增）、`NanoBanana` / `NanoBananaPro`（约 2 倍价，擅长图生图与文字渲染）、`Image2`。不确定就不传。`ai.agents()` 能列出当前开放的 agent。 - 错误：`AI_INSUFFICIENT_BALANCE`（余额不足，提示应用所有者充值）、`AI_IMAGE_FAILED`（把 message 展示给用户即可，常见是提示词触发内容安全）。 - 生图入口必须限流（`ratelimit`），并且只对登录用户开放——除视频外它是本 SKILL 里单次最贵的能力。 ## AI 视频（文生视频 / 图生视频） 视频 agent 在平台上**只有异步模式**：提交后立刻拿到 `taskId`，SDK 每 5 秒轮询一次直到完成（通常 1~5 分钟）。 ```ts // src/app/api/generate-video/route.ts —— 提交，立刻返回 taskId import { ai } from '@/lib/platform'; export async function POST(req: Request) { const { prompt, firstFrameUrl } = await req.json(); if (!prompt?.trim()) return Response.json({ error: 'EMPTY' }, { status: 400 }); const task = await ai.generateVideo({ prompt, // 写清主体、动作、镜头、风格 duration: 5, // 秒；Seedance 2.x 只有 5 | 10，越长越贵 ratio: '16:9', // '16:9' | '9:16' | '1:1' resolution: '720p', // '480p' 便宜一半 firstFrameUrl, // 可选：图生视频（Sora2 不支持） // agent: 'Seedance2Fast', // 不传用平台默认（最便宜最快） wait: false, // 只提交，不占着请求等 }); return Response.json({ taskId: task.taskId, agent: task.agent }); } // src/app/api/generate-video/[id]/route.ts —— 前端每 5 秒查一次 export async function GET(_: Request, { params }: { params: Promise<{ id: string }> }) { const { id } = await params; const t = await ai.getTask('Seedance2Fast', id); // agent 要和提交时一致 if (t.state === 'completed') return Response.json({ done: true, url: t.output.video.url }); if (t.state === 'failed') return Response.json({ done: true, error: t.error }); return Response.json({ done: false, message: t.message }); // '排队中...' / '生成中...' } ``` - **标准做法是上面的两段式**（提交 + 前端轮询），Route Handler 有执行时限、也不该被一个 3 分钟的请求占着。只有在长任务 / 脚本里才用不带 `wait:false` 的 `await ai.generateVideo(...)` 一把等到完成（内部轮询，默认最长 15 分钟，超时抛 `AI_VIDEO_TIMEOUT`，任务仍在服务端跑、稍后可再查）。 - **按秒 × 分辨率计费到应用所有者，非常贵**：一条 5 秒 720p 约 10~40 万点（约 2~8 元），Sora2 / MiniMaxH3 2K 更贵；失败不扣费。所以：入口必须限流 + 只对登录用户开放；**绝不**在页面加载或列表渲染时自动触发；生成结果一定存进 `db`（`taskId`、`url`）复用，不要刷新就重生成；页面上展示预计耗时和"生成中"状态。 - 前端拿到 `url` 直接 `