manifest

manifest.json

manifest.json 文件至关重要——它声明了你的应用所需的所有外部资源。Domo 使用它来：

1. 了解需要连接哪些数据集、集合、工作流和代码引擎函数
2. 将别名（在你的代码中使用）映射到实际的 Domo 资源 ID（在发布时配置）

关于为 packagesMapping 提供数据的 package 创建/更新生命周期详情，请使用：

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

基本结构

{
  "name": "My App Name",
  "version": "1.0.0",
  "id": "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx",
  "fullpage": true,
  "size": {
    "width": 4,
    "height": 3
  },
  "datasetsMapping": [],
  "collections": [],
  "workflowMapping": [],
  "packagesMapping": []
}

关键属性

• name / version - 应用元数据
• id - 首次发布时生成（参见部署部分）
• fullpage - 对于全页应用设置为 true
• size - 卡片尺寸（以网格单位表示的宽度/高度）
• datasetsMapping - 应用可以查询的数据集
• collections - 用于存储的 AppDB 集合
• workflowMapping - 应用可以触发的工作流
• packagesMapping - 代码引擎函数映射与契约

必需文件

• manifest.json - 应用配置（必需）
• thumbnail.png - 应用缩略图（必需，必须为 300x300 像素，必须与 manifest.json 位于同一目录）

数据集映射结构

{
  "datasetsMapping": [
    {
      "alias": "transactions",           // Used in code: new Query().fetch('transactions')
      "dataSetId": "abc-123-def-456",   // ⚠️ Use 'dataSetId' NOT 'id'
      "fields": []                       // ⚠️ REQUIRED - must be present even if empty
    }
  ]
}

关键要点：

• 数据集标识符使用 dataSetId（而非 id）
• fields 数组是必需的——即使为空 [] 也必须存在
• 省略 fields 会导致：Cannot read properties of undefined (reading 'map')
• 别名必须符合标识符安全规则：仅限字母/数字（推荐 ^[A-Za-z][A-Za-z0-9]*$）
• 别名中不要使用空格、连字符、点或其他特殊字符

别名命名约束（所有映射）

适用于数据集别名、代码引擎别名、工作流别名，以及应用代码引用的任何别名。

✅ Good: storeSales, Sales2026, RevenuePulse
❌ Bad: store-sales, store sales, store.sales, store@sales

如果别名包含特殊字符，运行时调用可能会失败，或者映射可能难以一致地解析。

代码引擎 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"
      }
    }
  ]
}

代码引擎 manifest 注意事项：

• 使用 packagesMapping（带 s），而非 packageMapping。
• 在每个参数和输出上包含完整的契约字段。
• 确保参数名称/类型/可空性与应用代码实际发送的内容一致。
• 当你希望获得确定性行为时，显式设置 packagesMapping[].version（例如 "1.0.0"）。
• version: null 被视为未固定/最新行为，通常在发布后仍会保持/显示为 null。

集合映射结构（collectionsMapping）

在已发布的 manifest 中将应用连接到现有 AppDB 集合时，使用带有 id + name 的 collectionsMapping 条目。

{
  "collectionsMapping": [
    {
      "id": "47bd2c9e-b22d-4436-8265-4798be8b218e",
      "name": "RandomFunIdeas",
      "syncEnabled": false
    }
  ]
}

集合映射注意事项：

• 不要在 collectionsMapping 中使用诸如 alias + collectionId 之类的临时键；这可能导致 manifest 解析失败。
• 对于映射的集合对象，name 是必需的。
• 对于现有集合的连接，除非应用需求明确要求同步数据集行为，否则 syncEnabled 默认为 false。

FileSets —— 无需 manifest 条目

FileSets 是"在 manifest 中声明一切"这一模式的例外。不存在 filesetsMapping 或等效键。在服务代码中直接将 fileset ID 作为常量引用：

// src/services/filesetApi.js
const FILESET_ID = 'b6ebf7e9-64ae-4e6d-b8ca-b356fe62923f';

fileset ID 是一个 UUID，你可以从 Domo UI 获取，或通过 community-domo-cli filesets search 获取。完整的 API 模式请参见 fileset-api skill。