应用开发指南

概述

应用 (App) 是智航云 AI 中台最顶层的资源单位。每个应用代表一个与 AI 中台集成的外部系统，包含完整的工具集、服务配置、仪表盘定义等。

平台内置的集成示例包括：

太古里运维平台 -- IoT 能耗管理系统
智慧园区标准版 -- 智慧园区综合管理
智航云DHR -- 人力资源平台 (60+ 工具)
智航云BIM -- 建筑 BIM 管理
双子塔数字孪生 -- 数字孪生可视化

应用定义格式

应用定义与平台内部 custom-apps/*.json 格式完全一致，包含四个核心部分：

json

{
  "app": {
    "id": "my-erp",
    "name": "My ERP Connector",
    "nameZh": "我的ERP连接器",
    "domain": "operations",
    "subsystem": "ERP"
  },
  "serviceConfig": {
    "credentials": ["username", "password"],
    "baseUrl": "https://erp.example.com"
  },
  "dashboard": {
    "widgets": [
      { "type": "stat", "title": "库存总量", "source": "erp_get_inventory_count" }
    ]
  },
  "toolPacks": ["erp-inventory-pack", "erp-orders-pack"]
}

app -- 基本信息

字段	类型	必填	说明
`id`	string	是	应用唯一标识符，建议使用 kebab-case
`name`	string	是	英文名称
`nameZh`	string	否	中文名称
`domain`	string	否	所属领域 (operations, hr, finance, etc.)
`subsystem`	string	否	子系统类型 (ERP, CRM, IoT, etc.)

serviceConfig -- 服务配置

定义应用连接外部系统所需的凭据和参数。平台只暴露用户名/密码配置，URL 和 token 由后端管理。

json

{
  "serviceConfig": {
    "credentials": ["username", "password"],
    "baseUrl": "https://erp.example.com",
    "headers": {
      "X-Custom-Header": "value"
    }
  }
}

安全提示

serviceConfig 中的敏感信息（密码、token）在后端加密存储，API 响应中不会返回明文。

dashboard -- 仪表盘

定义应用在 AI 中台仪表盘上的展示组件：

json

{
  "dashboard": {
    "widgets": [
      {
        "type": "stat",
        "title": "在线设备数",
        "source": "iot_get_device_count"
      },
      {
        "type": "chart",
        "title": "本月能耗趋势",
        "source": "iot_get_energy_trend",
        "chartType": "line"
      }
    ]
  }
}

toolPacks -- 工具包引用

引用已创建的工具包 ID 列表。工具包的创建参见工具开发指南。

创建应用

cURLPythonNode.js

bash

curl -X POST https://api.invoratec.cn/v1/apps \
  -H "X-API-Key: claw_xxxx" \
  -H "Content-Type: application/json" \
  -d '{
    "app": {
      "id": "my-erp",
      "name": "My ERP Connector",
      "nameZh": "我的ERP连接器",
      "domain": "operations",
      "subsystem": "ERP"
    },
    "serviceConfig": {
      "credentials": ["username", "password"]
    },
    "dashboard": {},
    "toolPacks": []
  }'

python

app = claw.apps.create(
    app={
        "id": "my-erp",
        "name": "My ERP Connector",
        "nameZh": "我的ERP连接器",
        "domain": "operations",
        "subsystem": "ERP"
    },
    serviceConfig={
        "credentials": ["username", "password"]
    }
)
print(app["appId"])

javascript

const app = await claw.apps.create({
  app: {
    id: 'my-erp',
    name: 'My ERP Connector',
    nameZh: '我的ERP连接器',
    domain: 'operations',
    subsystem: 'ERP'
  },
  serviceConfig: {
    credentials: ['username', 'password']
  }
})
console.log(app.appId)

如果 app.id 已存在，API 会自动执行更新操作而非报错。

完整开发流程

第一步：规划应用结构

确定你的外部系统需要暴露哪些能力给 AI：

我的 ERP 系统
├── 库存管理
│   ├── 查询库存 (erp_get_inventory)
│   ├── 更新库存 (erp_update_stock)
│   └── 库存预警 (erp_stock_alert)
├── 订单管理
│   ├── 查询订单 (erp_get_orders)
│   └── 创建订单 (erp_create_order)
└── 报表
    └── 月度汇总 (erp_monthly_report)

第二步：注册工具

为每个操作注册对应的工具：

bash

# 注册库存查询工具
curl -X POST https://api.invoratec.cn/v1/tools \
  -H "X-API-Key: claw_xxxx" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "erp_get_inventory",
    "description": "查询 ERP 系统库存数据",
    "appId": "my-erp",
    "input_schema": {
      "type": "object",
      "properties": {
        "warehouse_id": { "type": "string", "description": "仓库ID" },
        "product_code": { "type": "string", "description": "产品编码（可选）" }
      },
      "required": ["warehouse_id"]
    },
    "execution": {
      "type": "http",
      "method": "GET",
      "url": "https://erp.example.com/api/inventory?wh={warehouse_id}&product={product_code}"
    }
  }'

第三步：创建工具包

将相关工具组织为工具包：

bash

curl -X POST https://api.invoratec.cn/v1/tools/packs \
  -H "X-API-Key: claw_xxxx" \
  -H "Content-Type: application/json" \
  -d '{
    "id": "erp-inventory-pack",
    "name": "ERP Inventory Pack",
    "nameZh": "ERP 库存工具包",
    "description": "ERP 库存查询和管理工具",
    "tools": ["erp_get_inventory", "erp_update_stock", "erp_stock_alert"],
    "knowledge": "仓库编号规则：WH-XXX，其中 XXX 为三位数字。产品编码规则：PRD-XXXX。库存数据每5分钟从ERP同步一次。"
  }'

第四步：创建应用并关联工具包

bash

curl -X POST https://api.invoratec.cn/v1/apps \
  -H "X-API-Key: claw_xxxx" \
  -H "Content-Type: application/json" \
  -d '{
    "app": {
      "id": "my-erp",
      "name": "My ERP Connector",
      "nameZh": "我的ERP连接器",
      "domain": "operations",
      "subsystem": "ERP"
    },
    "serviceConfig": {
      "credentials": ["username", "password"]
    },
    "toolPacks": ["erp-inventory-pack", "erp-orders-pack"]
  }'

第五步：测试

bash

# 用 AI 对话测试
curl -X POST https://api.invoratec.cn/v1/ai/chat \
  -H "X-API-Key: claw_xxxx" \
  -H "Content-Type: application/json" \
  -d '{
    "message": "查询 WH-001 仓库的库存",
    "appContext": "my-erp"
  }'

第六步：发布到市场

测试完成后，将应用发布到平台市场供其他用户使用：

bash

curl -X POST https://api.invoratec.cn/v1/apps/my-erp/publish \
  -H "X-API-Key: claw_xxxx"

应用生命周期

draft → published → (更新) → published
                  → (下架) → draft

状态	说明
`draft`	草稿状态，仅开发者自己可见
`published`	已发布，市场可见

下一步

工具开发指南 -- 详细了解工具注册和执行方式
知识库指南 -- 为应用添加 RAG 知识库
API 参考: 应用 -- 完整 API 端点文档

应用开发指南 ​

概述 ​

应用定义格式 ​

app -- 基本信息 ​

serviceConfig -- 服务配置 ​

dashboard -- 仪表盘 ​

toolPacks -- 工具包引用 ​

创建应用 ​

完整开发流程 ​

第一步：规划应用结构 ​

第二步：注册工具 ​

第三步：创建工具包 ​

第四步：创建应用并关联工具包 ​

第五步：测试 ​

第六步：发布到市场 ​

应用生命周期 ​

下一步 ​

应用开发指南

概述

应用定义格式

app -- 基本信息

serviceConfig -- 服务配置

dashboard -- 仪表盘

toolPacks -- 工具包引用

创建应用

完整开发流程

第一步：规划应用结构

第二步：注册工具

第三步：创建工具包

第四步：创建应用并关联工具包

第五步：测试

第六步：发布到市场

应用生命周期

下一步