cap-apps-ai-service-layer

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

Rule: Domo App Platform AI (Toolkit-First)

规则：Domo应用平台AI（以工具包优先）

This rule is toolkit-first. Use

AIClient

from

@domoinc/toolkit

Legacy endpoint-first guidance has been archived to
archive/legacy-rules/domo-ai-endpoints.md
.

本规则以工具包优先。请使用

@domoinc/toolkit

中的

AIClient

。

旧版以端点优先的指南已归档至
archive/legacy-rules/domo-ai-endpoints.md
。

Canonical Client

标准客户端

bash

yarn add @domoinc/toolkit

typescript

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

bash

yarn add @domoinc/toolkit

typescript

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

Critical: AIClient methods are static

重点：AIClient的方法为静态方法

Do not instantiate

AIClient

for these methods.

Wrong:

typescript

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

Correct:

typescript

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

请勿为这些方法实例化

AIClient

。

错误示例：

typescript

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

正确示例：

typescript

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

Text Generation

文本生成

typescript

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;

typescript

const response = await AIClient.generate_text(
  '用简单的语言解释这个销售趋势',
  { template: '你是一名商业分析师。${input}' },
  { tone: 'professional' },
  undefined,
  { temperature: 0.7 }
);

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

Additional AI Methods

其他AI方法

text_to_sql

schema argument must be an array

text_to_sql

的schema参数必须为数组

Wrong:

typescript

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

Correct:

typescript

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' }
    ]
  }
]);

错误示例：

typescript

await AIClient.text_to_sql('按支出显示顶级供应商', {
  dataSourceName: 'vendorPayments',
  columns: [{ name: 'amount', type: 'number' }]
});

正确示例：

typescript

await AIClient.text_to_sql('按支出显示顶级供应商', [
  {
    dataSourceName: 'vendorPayments',
    description: '供应商付款发票',
    columns: [
      { name: 'vendor', type: 'string' },
      { name: 'amount', type: 'number' },
      { name: 'date', type: 'date' }
    ]
  }
]);

Signature reference

签名参考

(Approximate; check installed toolkit typings for exact current signature.)

typescript

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

Why array: this supports multi-table SQL generation (including join-aware SQL) when multiple schemas are provided.

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

typescript

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生成（包括支持关联的SQL）。

text_to_sql usage note

text_to_sql使用说明

text_to_sql

is great for ad-hoc SQL, but

/sql/v1

does not automatically apply dashboard/page filters. If filter-awareness is required in embedded cards, use Query API (

/data/v1

via

@domoinc/query

) for execution.

typescript

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' }] }
);

text_to_sql

非常适合临时SQL需求，但

/sql/v1

不会自动应用仪表盘/页面筛选器。如果嵌入卡片中需要支持筛选器，请使用Query API（通过

@domoinc/query

调用

/data/v1

）来执行。

typescript

const sqlResult = await AIClient.text_to_sql('按区域显示总销售额', [
  {
    dataSourceName: 'Sales',
    description: '销售交易记录',
    columns: [{ name: 'region', type: 'string' }, { name: 'amount', type: 'number' }]
  }
]);

const beastModeResult = await AIClient.text_to_beastmode(
  '计算同比增长率',
  { dataSourceName: 'Revenue', columns: [{ name: 'revenue', type: 'number' }, { name: 'date', type: 'date' }] }
);

Response Handling Rule

响应处理规则

AIClient

responses are not always shaped like other toolkit clients:

often uses
```
response.data
```
may include both
```
output
```
and
```
choices
```

Use defensive parsing plus a strict string guard:

typescript

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

的响应格式并不总是与其他工具包客户端一致：

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

请使用防御式解析加上严格的字符串校验：

typescript

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未返回可用输出');

Canonical Rules References

标准规则参考

Toolkit AI methods and caveats:
```
.cursor/rules/04-toolkit.mdc
```
Naming/response gotchas:
```
.cursor/rules/09-gotchas.mdc
```

工具包AI方法及注意事项：
```
.cursor/rules/04-toolkit.mdc
```
命名/响应陷阱：
```
.cursor/rules/09-gotchas.mdc
```

Checklist

检查清单

```
AIClient
```
methods use snake_case (
```
generate_text
```
,
```
text_to_sql
```
, etc.)
```
AIClient
```
methods are called statically (for example
```
AIClient.text_to_sql(...)
```
, not instance methods)
```
AIClient.text_to_sql
```
second argument is
```
DataSourceSchema[]
```
(array), not a single object
Responses parsed from
```
data
```
/
```
body
```
fallback
Output extraction includes string guard and empty-output handling
Error handling and loading state in UI

```
AIClient
```
方法使用蛇形命名法（如
```
generate_text
```
、
```
text_to_sql
```
等）
```
AIClient
```
方法以静态方式调用（例如
```
AIClient.text_to_sql(...)
```
，而非实例方法）
```
AIClient.text_to_sql
```
的第二个参数为
```
DataSourceSchema[]
```
（数组），而非单个对象
响应从
```
data
```
/
```
body
```
降级解析
输出提取包含字符串校验和空输出处理
UI中包含错误处理和加载状态

cap-apps-ai-service-layer

Original

Translation

Rule: Domo App Platform AI (Toolkit-First)

规则：Domo应用平台AI（以工具包优先）

Canonical Client

标准客户端

Critical: AIClient methods are static

重点：AIClient的方法为静态方法

Text Generation

文本生成

Additional AI Methods

其他AI方法

`text_to_sql`
schema argument must be an array

`text_to_sql`
的schema参数必须为数组

Signature reference

签名参考

text_to_sql usage note

text_to_sql使用说明

Response Handling Rule

响应处理规则

Canonical Rules References

标准规则参考

Checklist

检查清单

cap-apps-ai-service-layer

Original

Translation

Rule: Domo App Platform AI (Toolkit-First)

规则：Domo应用平台AI（以工具包优先）

Canonical Client

标准客户端

Critical: AIClient methods are static

重点：AIClient的方法为静态方法

Text Generation

文本生成

Additional AI Methods

其他AI方法

text_to_sql schema argument must be an array

text_to_sql的schema参数必须为数组

Signature reference

签名参考

text_to_sql usage note

text_to_sql使用说明

Response Handling Rule

响应处理规则

Canonical Rules References

标准规则参考

Checklist

检查清单

`text_to_sql`
schema argument must be an array

`text_to_sql`
的schema参数必须为数组