在 JavaScript/TypeScript 项目中接入…

适用于 Node.js、浏览器、React、Next.js 等 JS/TS 环境，用 @inferencesh/sdk 调用 AI 应用、构建带工具/流式/审批的 Agent，并通过后端代理保护 API Key。

适用场景

解决思路

1. 安装 SDK：运行 `npm install @inferencesh/sdk`，或 `yarn add @inferencesh/sdk`，或 `pnpm add @inferencesh/sdk`；运行环境需 Node.js 18.0.0+，或支持 fetch 的现代浏览器。
2. 快速初始化：`import { inference } from '@inferencesh/sdk'; const client = inference({ apiKey: 'inf_your_key' });`。
3. 认证方式：直接传 `apiKey`；推荐 `const client = inference({ apiKey: process.env.INFERENCE_API_KEY });`；前端应用传 `proxyUrl: '/api/inference/proxy'`；在 Settings → API Keys → Create API Key 获取 API key。
4. 运行 AI app：`const result = await client.run({ app: 'infsh/flux-schnell', input: { prompt: 'A sunset over mountains' } }); console.log(result.output);`，并读取 `result.status` 与 `result.output`。
5. Fire and forget：`const task = await client.run({ app: 'google/veo-3-1-fast', input: { prompt: 'Drone flying over mountains' } }, { wait: false });`，记录 `task.id`，之后用 `client.getTask(task.id)` 查询。
6. 流式进度：`const stream = await client.run({ ... }, { stream: true }); for await (const update of stream) { ... }`，读取 `update.status`，并用 `update.logs?.at(-1)` 查看最后一条日志。
7. 设置运行参数：`app` 为 App ID（`namespace/name@version`）；`input` 匹配 app schema；`setup` 为隐藏 setup 配置；`infra` 为 `'cloud'` 或 `'private'`；`session` 为状态执行 session ID；`session_timeout` 为空闲超时 1-3600 秒。
8. 自动上传文件：在 `input` 中直接传本地文件路径，如 `image: '/path/to/image.png'`，SDK 会自动上传。
9. 手动上传文件：`const file = await client.uploadFile('/path/to/image.png');`；可传 `{ filename: 'custom_name.png', contentType: 'image/png', public: true }`；运行时使用 `file.uri`。
10. 浏览器文件上传：`const input = document.querySelector('input[type=file]'); const file = await client.uploadFile(input.files[0]);`。
11. 使用 Sessions：首次 `run` 传 `session: 'new'` 和 `session_timeout: 300`，从 `result.session_id` 取 ID；后续 `run` 传 `session: sessionId` 复用同一个热 worker。
12. 模板 Agent：`const agent = client.agent('my-team/support-agent@latest');`；`await agent.sendMessage('Hello!')` 读 `response.text`；可多轮 `sendMessage`；用 `agent.reset()` 重置；用 `agent.getChat()` 获取历史。
13. Ad-hoc Agent：从 SDK 导入 `tool, string, number, appTool`；用 `tool('calculate').describe('Perform a calculation').param('expression', string('Math expression')).build()` 定义工具；用 `appTool('generate_image', 'infsh/flux-schnell@latest').describe('Generate an image').param('prompt', string('Image description')).build()` 定义 app 工具；再 `client.agent({ core_app: { ref: 'infsh/claude-sonnet-4@latest' }, system_prompt: 'You are a helpful assistant.', tools: [calculator, imageGen], temperature: 0.7, max_tokens: 4096 })` 创建 agent；`await agent.sendMessage('What is 25 * 4?')`。
14. 可选核心 app：`infsh/claude-sonnet-4@latest`、`infsh/claude-haiku-35@latest`、`infsh/gpt-4o@latest`、`infsh/gpt-4o-mini@latest`。
15. Tool Builder 参数类型：导入 `string, number, integer, boolean, enumOf, array, obj, optional`；用 `string('...')`、`integer('...')`、`number('...')`、`boolean('...')`、`enumOf([...], '...')`、`array(string('Tag'), '...')`、`obj({...}, '...')`、`optional(string('...'))`。
16. Client Tools：`tool('greet').display('Greet User').describe('Greets a user by name').param('name', string('Name to greet')).requireApproval().build()`。
17. App Tools：`appTool('generate_image', 'infsh/flux-schnell@latest').describe('Generate an image from text').param('prompt', string('Image description')).setup({ model: 'schnell' }).input({ steps: 20 }).requireApproval().build()`。
18. Agent Tools：`agentTool('research', 'my-org/researcher@v1').describe('Research a topic').param('topic', string('Topic to research')).build()`。
19. Webhook Tools：`webhookTool('slack', 'https://hooks.slack.com/...').describe('Send Slack notification').secret('SLACK_SECRET').param('channel', string('Channel')).param('message', string('Message')).build()`。
20. Internal Tools：`internalTools().plan().memory().webSearch(true).codeExecution(true).imageGeneration({ enabled: true, appRef: 'infsh/flux@latest' }).build()`；将结果作为 `internal_tools` 传给 `client.agent`。
21. 流式 Agent 响应：`agent.sendMessage('Explain quantum computing', { onMessage: (msg) => { if (msg.content) { process.stdout.write(msg.content); } }, onToolCall: async (call) => { console.log(call.name); const result = await executeTool(call.name, call.args); agent.submitToolResult(call.id, result); } })`。
22. 给 Agent 附加文件：Node.js 用 `readFileSync('image.png')` 传给 `files`；或用 base64 data URL；或浏览器 `input.files[0]`。
23. 给 Agent 添加可复用 Skills：在 `client.agent({ ... skills: [...] })` 中传 `{ name: 'code-review', description: 'Code review guidelines', content: '...' }` 或 `{ name: 'api-docs', description: 'API documentation', url: 'https://example.com/skills/api-docs.md' }`。
24. 前端安全代理客户端：`const client = inference({ proxyUrl: '/api/inference/proxy' });`，不在前端放 apiKey。
25. Next.js Proxy：在 `app/api/inference/proxy/route.ts` 中 `import { createRouteHandler } from '@inferencesh/sdk/proxy/nextjs'; const route = createRouteHandler({ apiKey: process.env.INFERENCE_API_KEY }); export const POST = route.POST;`。
26. Express Proxy：`import { createProxyMiddleware } from '@inferencesh/sdk/proxy/express'; app.use('/api/inference/proxy', createProxyMiddleware({ apiKey: process.env.INFERENCE_API_KEY }));`。
27. 支持代理框架：Next.js（App Router 与 Pages Router）、Express、Hono、Remix、SvelteKit。
28. TypeScript 类型支持：从 `@inferencesh/sdk` 导入 `TaskDTO, ChatDTO, ChatMessageDTO, AgentTool, TaskStatusCompleted, TaskStatusFailed` 等；用 `result.status === TaskStatusCompleted` 或 `TaskStatusFailed` 做类型安全判断。
29. 错误处理：导入 `RequirementsNotMetException, InferenceError`；在 try/catch 中若 `RequirementsNotMetException`，遍历 `e.errors` 打印 `err.type` 和 `err.key`；若 `InferenceError`，打印 `e.message`。
30. 人工审批工作流：在 `sendMessage` 的 `onToolCall` 中检查 `call.requiresApproval`；用 `promptUser` 请求批准；批准则执行工具并 `agent.submitToolResult(call.id, result)`，拒绝则 `agent.submitToolResult(call.id, { error: 'Denied by user' })`。
31. CommonJS 支持：`const { inference, tool, string } = require('@inferencesh/sdk'); const client = inference({ apiKey: 'inf_...' }); const result = await client.run({...});`。
32. 安装相关技能：运行 `npx skills add belt-sh/cli` 安装 belt CLI skill；需要其他 SDK 或平台能力时运行 `npx skills add inference-sh/skills@python-sdk`、`npx skills add inference-sh/skills@infsh-cli`、`npx skills add inference-sh/skills@llm-models`、`npx skills add inference-sh/skills@ai-image-generation`。
33. 按需查阅参考文件：`references/agent-patterns.md`、`references/tool-builder.md`、`references/server-proxy.md`、`references/streaming.md`、`references/files.md`、`references/sessions.md`、`references/typescript.md`、`references/react-integration.md`。
34. 查阅官方文档：JavaScript SDK Reference、Agent SDK Overview、Tool Builder Reference、Server Proxy Setup、Authentication、Streaming、File Uploads。

适用边界 · 注意事项

• 没有 inference.sh 账号、API key，或项目不想使用该平台时。
• 仅使用 Python 或其他非 JavaScript/TypeScript 环境时，应改用对应 SDK。
• Node.js 低于 18 且没有 fetch，或前端无法搭建后端代理却必须隐藏 API key 时。