mcpField
A
ai-service-layer

ai-service-layer

github.com/stahura开发24192 次安装26 周前更新
代码仓库

关于 ai-service-layer

ai-service-layer 是面向 Domo App Platform 开发者的 AIClient 使用指南，涵盖文本生成和自然语言转 SQL，并说明参数格式与响应解析。

主要功能

  1. 01调用静态 AIClient 方法
  2. 02生成文本
  3. 03根据多个数据源模式生成 SQL
  4. 04解析不同结构的响应

适用场景

  1. 01为 Domo 应用生成文本内容
  2. 02将自然语言问题转换为 SQL
  3. 03处理 AI 响应并校验输出

安装

复制下面的命令，在终端中运行。

$npx skills add https://github.com/stahura/domo-ai-vibe-rules --skill ai-service-layer

安装后在 Claude Code 中输入/ai-service-layer确认已加载。

详细介绍

规则：Domo App Platform AI（工具包优先）

本规则工具包优先。使用来自 @domoinc/toolkit 的 AIClient。

规范客户端

yarn add @domoinc/toolkit

import { AIClient } from '@domoinc/toolkit';

关键：AIClient 方法是静态的

不要为这些方法实例化 AIClient。

错误：

const ai = new AIClient();
await ai.text_to_sql('...');

正确：

await AIClient.text_to_sql('...');

文本生成

const response = await AIClient.generate_text(
  'Explain this sales trend in simple terms',
  { template: 'You are a business analyst. ${input}' },
  { tone: 'professional' },
  undefined,
  { temperature: 0.7 }
);

const body = response.data || response.body || response;
const text = body.output || body.choices?.[0]?.output;

其他 AI 方法

text_to_sql 的 schema 参数必须是数组

错误：

await AIClient.text_to_sql('Show top vendors by spend', {
  dataSourceName: 'vendorPayments',
  columns: [{ name: 'amount', type: 'number' }]
});

正确：

await AIClient.text_to_sql('Show top vendors by spend', [
  {
    dataSourceName: 'vendorPayments',
    description: 'Vendor payment invoices',
    columns: [
      { name: 'vendor', type: 'string' },
      { name: 'amount', type: 'number' },
      { name: 'date', type: 'date' }
    ]
  }
]);

签名参考

（近似值；请查看已安装工具包的类型定义以获取当前准确的签名。）

AIClient.text_to_sql(
  input: string,
  dataSourceSchemas?: DataSourceSchema[], // array
  promptTemplate?: any,
  parameters?: Record<string, string>,
  model?: string,
  modelConfiguration?: Record<string, Object>
): Promise<Response<TextAIResponse>>;

为什么用数组：当提供多个 schema 时，这支持多表 SQL 生成（包括感知 join 的 SQL）。

text_to_sql 使用说明

text_to_sql 非常适合临时 SQL，但 /sql/v1 不会自动应用仪表板/页面筛选器。 如果嵌入卡片中需要感知筛选器，请使用 Query API（通过 @domoinc/query 调用 /data/v1）来执行。

const sqlResult = await AIClient.text_to_sql('Show total sales by region', [
  {
    dataSourceName: 'Sales',
    description: 'Sales transactions',
    columns: [{ name: 'region', type: 'string' }, { name: 'amount', type: 'number' }]
  }
]);

const beastModeResult = await AIClient.text_to_beastmode(
  'Calculate year over year growth percentage',
  { dataSourceName: 'Revenue', columns: [{ name: 'revenue', type: 'number' }, { name: 'date', type: 'date' }] }
);

响应处理规则

AIClient 的响应并不总是与其他工具包客户端的结构相同：

  • 通常使用 response.data
  • 可能同时包含 output 和 choices

使用防御性解析并加上严格的字符串守卫：

const body = response?.data ?? response?.body ?? response;
const outputCandidate = body?.output ?? body?.choices?.[0]?.output;
const output = typeof outputCandidate === 'string' ? outputCandidate.trim() : '';

if (!output) throw new Error('AI returned no usable output');

检查清单

  • AIClient 方法使用 snake_case（generate_text、text_to_sql 等）
  • AIClient 方法是静态调用的（例如 AIClient.text_to_sql(...)，而不是实例方法）
  • AIClient.text_to_sql 的第二个参数是 DataSourceSchema[]（数组），而不是单个对象
  • 从 data/body 回退解析响应
  • 输出提取包含字符串守卫和空输出处理
  • UI 中有错误处理和加载状态

评论

支持 Markdown