code-engine

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

对 Code Engine 调用采用契约优先模式。 在实践中，在应用代码中发起调用时，优先直接使用 domo.post('/domo/codeengine/v2/packages/{alias}', params)。

包生命周期操作由 CLI 技能处理：

• ~/.agents/skills/code-engine-create/SKILL.md
• ~/.agents/skills/code-engine-update/SKILL.md

本技能适用于应用代码内部的运行时调用模式，而非包的创建/更新编排。

可用的调用模式 (domo.post)

npm install ryuu.js

import domo from 'ryuu.js';

const response = await domo.post('/domo/codeengine/v2/packages/calculateTax', {
  amount: 1000,
  state: 'CA'
});

响应解析要求

// First integration pass: inspect exact response shape for this function
console.log('Code Engine response:', response);

const body = response?.body ?? response?.data ?? response;

// Some package contracts return nested envelopes:
// { response: { ... } } or { response: { response: { ... } } }
const unwrapResponse = (value: unknown) => {
  let current = value as any;
  let depth = 0;
  while (current && typeof current === 'object' && 'response' in current && depth < 6) {
    current = current.response;
    depth += 1;
  }
  return current;
};
const normalized = unwrapResponse(body);

// Handle common output shapes
const output =
  normalized?.output ??
  normalized?.result ??
  normalized?.value ??
  normalized;

if (typeof output === 'number') {
  // numeric output
} else if (typeof output === 'string') {
  // string output
} else if (output && typeof output === 'object') {
  // structured object output
} else {
  throw new Error('Code Engine returned no usable output');
}

Manifest 要求：packagesMapping（带 s）

使用 packagesMapping 并定义完整的参数/输出契约。

{
  "packagesMapping": [
    {
      "name": "myPackage",
      "alias": "myFunction",
      "packageId": "00000000-0000-0000-0000-000000000000",
      "version": "1.0.0",
      "functionName": "myFunction",
      "parameters": [
        {
          "name": "param1",
          "displayName": "param1",
          "type": "decimal",
          "value": null,
          "nullable": false,
          "isList": false,
          "children": [],
          "entitySubType": null,
          "alias": "param1"
        }
      ],
      "output": {
        "name": "result",
        "displayName": "result",
        "type": "number",
        "value": null,
        "nullable": false,
        "isList": false,
        "children": [],
        "entitySubType": null,
        "alias": "result"
      }
    }
  ]
}

版本固定规则：

• 如果用户期望固定的包构建版本，请在每个 packagesMapping 条目中显式设置 "version": "x.y.z"。
• 除非用户明确希望使用不固定/最新版本的行为，否则不要将 version 保留为 null。

必须向用户披露的契约

在推荐或生成 Code Engine 调用时，Agent 必须明确告知用户：

• 确切的输入参数名称、类型以及 nullable 预期
• 预期的输出名称、类型和结构（number/string/object）
• 输出是否包裹在 response 信封中（以及是否可能存在嵌套信封）

这是必需的，以便用户能够构建匹配的 Code Engine 函数和 manifest 契约。

错误处理模式

async function executeFunction(alias: string, payload: Record<string, unknown>) {
  try {
    const response = await domo.post(`/domo/codeengine/v2/packages/${alias}`, payload);
    console.log('Code Engine response:', response);
    return response?.body ?? response?.data ?? response;
  } catch (error) {
    console.error(`Code Engine call failed for alias ${alias}`, error);
    throw error;
  }
}

在全局 Domo 包中发现函数名称

在调用 Domo 提供的全局包（例如 DOMO Notifications、DOMO DataSets、DOMO Users）时， 导出的函数名称及其确切的参数签名无法通过 REST API 发现 —— 对于所有全局包，GET /api/codeengine/v2/packages/{id}/versions/{v} 都会返回 "functions": []。

如何找到它们： 在 Domo UI 中导航到包的源代码：

https://{instance}.domo.com/codeengine/{packageId}

这会打开 Code Engine 编辑器，显示该包的完整 JavaScript 源代码。阅读它以找到：

• 确切的导出函数名称（例如 sendEmail、sendBuzzRequest）
• 位置参数名称和顺序（Code Engine 按位置映射，而不是按键名映射）
• 哪些参数是可选的 / 可为空的

为什么这很重要： 针对 API 猜测函数名称，每个错误的名称都会返回 404， 而且不会给出正确名称的任何提示。如果不先阅读源代码，你将 浪费多次往返调用，并且可能需要用户手动粘贴源代码。

示例 — DOMO Notifications (03ba6971-98d0-4654-9bfd-aa897816df33)

在源代码中找到的关键函数：

函数	参数（位置）	备注
sendEmail	recipientEmails, subject, body, personRecipients, groupRecipients, attachments, attachment, includeReplyAll	recipientEmails 是单个逗号分隔的字符串，而不是数组
sendEmailToListOfEmails	to, subject, body, attachments, attachment, includeReplyAll	to 是字符串数组
sendBuzzRequest	channelId, message	channelId 必须是有效的 UUID
sendExternalEmail	to, subject, body, attachments, attachment, includeReplyAll	会根据授权域名白名单进行校验

注意事项： sendEmail 的 recipientEmails 是一个普通字符串（例如 "[email protected]"）， 而不是数组。传入数组会导致静默失败或错误路由。

检查清单

• 在编写任何调用之前，阅读 https://{instance}.domo.com/codeengine/{packageId} 上的包源代码
• 已从源代码确认确切的函数名（不要猜测）
• 已从源代码 JSDoc 注释确认参数名称和类型
• 调用使用 domo.post('/domo/codeengine/v2/packages/{alias}', params) 模式
• Manifest 使用 packagesMapping（而不是 packageMapping）
• 当需要确定性的包行为时，packagesMapping.version 被显式固定
• packagesMapping.parameters 和 output 包含完整的契约字段（name、displayName、type、value、nullable、isList、children、entitySubType、alias）
• Agent 向用户说明输入参数名称、类型和可空状态
• Agent 向用户说明预期的输出名称/类型/结构
• 首次实现时记录响应并验证真实响应结构
• 输出解析处理 body/data/原始响应结构以及嵌套的 response 信封
• 错误已被处理并呈现到 UI 或日志