# AI工作台解决方案：AIOS工程与部署手册

**Repository Path**: low-code-dev-lab/ai-workstation-manual

## Basic Information

- **Project Name**: AI工作台解决方案：AIOS工程与部署手册
- **Description**: 葡萄城AI工作台解决方案：AIOS工程与部署手册
- **Primary Language**: Unknown
- **License**: Not specified
- **Default Branch**: main
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2026-03-29
- **Last Updated**: 2026-04-30

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# 企业级 AI 工作台解决方案部署手册（Docker部署）

## 用途

快速构建**能使用现有业务系统能力**的企业级 AI 工作台。

体验环境：[在线演示](https://marketplacedemo.app.hzgcloud.cn/ai-workstation)

## 系统架构

本方案由 Agent 交互层、Agent 执行层（简称：`OC端`）和业务系统层组成，连接用户与业务数据。按照国安部关于使用 OpenClaw 等具备 Computer Use 能力的 AI 智能体的指导建议，OC端和业务系统层+Agent交互层（因为两者部署在同一台服务商，合并称为`服务器端`）之间推荐采用网络隔离，由此衍生出两种网络拓扑。

### 网络拓扑A：公网部署

```mermaid
graph TD
  subgraph 公网
    Agent["Agent 执行器\n如 OpenClaw"]
    subgraph 中间层
      MQTT["MQTT Broker\n如 EMQX Cloud"]
      OSS["OSS 对象存储\n如七牛云"]
    end
  end

  subgraph 内网
    BIZ["业务系统"]
    AI["AI 工作台"]
    FG["活字格服务器端（基础组件）"]
  end

  Agent -->|MQTT| MQTT
  Agent -->|OSS| OSS

  BIZ -.-> MQTT
  AI -.-> MQTT
  AI -.-> OSS

  BIZ --> FG
  AI --> FG
```

优势：

- 不依赖复杂的网络配置，可快速完成部署
- 采用公网服务作为中间层，稳定性高，维护简单

### 网络拓扑B：DMZ 部署

```mermaid
graph TD
  subgraph DMZ
    Agent["Agent 执行器\n如 OpenClaw"]
    subgraph 中间层
      MQTT["MQTT Broker\n私有化部署 EMQX"]
      OSS["OSS 对象存储\n私有化部署 MinIO"]
    end
  end

  subgraph 内网
    BIZ["业务系统"]
    AI["AI 工作台"]
    FG["活字格服务器端（基础组件）"]
  end

  Agent -->|MQTT| MQTT
  Agent -->|OSS| OSS

  BIZ -.-> MQTT
  AI -.-> MQTT
  AI -.-> OSS

  BIZ --> FG
  AI --> FG
```

优势：

- 借助内网到 DMZ 的单向通讯，在确保安全的前提下，可以在内网通过 SSH 直接操作，操作更便利
- 配合私有化部署的 LLM，可以实现高度自主可控

## 1、准备 活字格

按照官方帮助手册，在 `服务器端` 安装 `活字格服务管理器` 程序，并确保其正常工作。

推荐配置：

- 系统架构：x64
- 操作系统：Ubuntu 24.x 或更新版本
- 硬件：8 Core / 16 GB RAM（20+ 并发）
- 数据库：MySQL 8 或更新版本
- 网络：需要确保该服务器可以连接到互联网（包括 MQTT Broker 和 OSS）

## 2、准备 MQTT Broker

> 以 EMQX Cloud 为例，可采用其他 MQTT Broker，如私有化部署的 [EMQX](https://docs.emqx.com/zh/emqx/latest/deploy/install-docker.html) 。采用私有化部署的 EMQX 时，需要确保 `OC端` 和 `服务器端` 均可访问该服务。

EMQX Cloud 地址：`https://cloud.emqx.com/console/`

1. 按照官方说明注册 EMQX Cloud 账号并登录。
2. 新建一个 Serverless 部署（截止 2026 年 4 月 8 日，EMQX Cloud 为 Serverless 部署提供每月 100 万分钟连接时间，可满足基本验证测试要求）。
3. 在新建的部署中创建一个客户端认证，保管好用户名和密码。
4. 在部署概览中获取 MQTT 连接信息（形如 mqtts://sample.ala.cn-hangzhou.emqxsl.cn:8883 ），如访问地址和 MQTT over TLS/SSL 端口。
5. 使用 EMQX Cloud 提供的在线调试功能，尝试发布和订阅，确保该部署可以正常工作。

这一步需要记录以下信息备用：

- 访问地址：`？`
- 用户名：`？`
- 密码：`？`

## 3、准备 OSS（S3 兼容）

> 以七牛云 Kodo 对象存储为例，可采用兼容 AWS S3 操作接口的其他服务，如私有化部署的 [Minio aistor](https://docs.min.io/enterprise/aistor-object-store/installation/container/install/) 对象存储服务器。采用私有化部署的 OSS 时，需要确保 `OC端` 和 `服务器端` 均可访问该服务。

七牛云对象存储官网：`https://www.qiniu.com/products/kodo`

1. 按照官方说明注册 七牛云 账号并登录
2. 按照页面提示完成实名认证（截止 2026年4月8日，七牛云为用户创建的桶提供少量的免费配额，可满足基本的验证测试要求）
3. 在控制台的密钥管理页面，启用密钥访问
4. 创建一个新的密钥，保存好 AK 和 SK
5. 确认所用空间所属 Region 和对应 S3 Endpoint，例如 `cn-east-1` 与 `https://s3.cn-east-1.qiniucs.com`
6. 创建两个存储空间 `agents-in`（收件箱） 和 `agents-out`（发件箱），设置为 `公开`

这一步需要记录以下信息备用：

- AK：`？`
- SK：`？`
- Region：`？`
- S3 Endpoint：`？`

## 4、准备 Agent 执行器

在`OC端`的服务器上部署执行器，并确保其正常工作。

推荐配置：

- 系统架构 ： x64
- 操作系统 ： Ubuntu 24.x 或更新版本
- 硬件 ： 2 Core / 8 GB RAM （10+并发）
- LLM ：公网的大模型服务，如 GPT5.4、Qwen3.5-Plus 等
- 网络 ：需要确保该服务器可以连接到互联网（包括 MQTT Broker 和对象存储）

### 4.1 准备执行器的配置文件

创建工作目录，如 `/var/platform_data` 作为 AI 工作台的 `DATA` 目录，并且为 Docker 的运行身份 `1001:1001` 授权：

```bash
sudo mkdir -p /var/platform_data
sudo chown 1001:1001 /var/platform_data -R
sudo chmod 755 /var/platform_data
```

在 DATA 中创建 `config.json`，指定大模型的配置信息（支持 OpenAI 风格接口和 Anthropic 风格接口）。配置的结构与 OpenClaw 2026.4.15 保持一致，具体含义，请参考官方文档。

```json
{
  "agents": {
    "defaults": {
      "workspace": "/var/platform_data/openclaw/workspaces/default",
      "model": {
        "primary": "corp-openai/qwen3.5-plus"
      },
      "models": {
        "corp-openai/qwen3.5-plus": {
          "alias": "qwen3.5-plus"
        }
      }
    }
  },
  "gateway": {
    "mode": "local"
  },
  "memory": {
    "backend": "qmd"
  },
  "models": {
    "mode": "merge",
    "providers": {
      "corp-openai": {
        "api": "openai-completions",
        "baseUrl": "https://dashscope.aliyuncs.com/compatible-mode/v1",
        "apiKey": {
          "source": "env",
          "provider": "default",
          "id": "OC_OPENAI_API_KEY"
        },
        "models": [
          {
            "id": "qwen3.5-plus",
            "name": "Qwen 3.5 Plus",
            "contextTokens": 1000000
          }
        ]
      }
    }
  },
  "plugins": {
    "entries": {
      "mqtt-channel": {
        "enabled": true
      }
    }
  },
  "secrets": {
    "providers": {
      "default": {
        "source": "env"
      }
    }
  },
  "session": {
    "dmScope": "per-channel-peer"
  },
  "tools": {
    "exec": {
      "ask": "off",
      "security": "full"
    }
  }
}

```

接下来，在 `DATA` 文件夹中创建 `env.json`，指定各类配置。

```json

{
  "HZG_CLI_MQTT_BROKER": "mqtts://example.ala.cn-hangzhou.emqxsl.cn:8883",
  "HZG_CLI_REQUEST_TOPIC": "agents/cli/req",
  "HZG_CLI_RESPONSE_TOPIC": "agents/cli/res",
  "HZG_CLI_TIMEOUT": "500",
  "HZG_CLI_USERNAME": "xxx",
  "HZG_CLI_PASSWORD": "xxx",
  "OC_OPENAI_API_KEY": "sk-xxx",
  "OC_ANTHROPIC_API_KEY": "",
  "OC_MQTT_CHANNEL_BROKER": "mqtts://example.ala.cn-hangzhou.emqxsl.cn:8883",
  "OC_MQTT_CHANNEL_USERNAME": "xxx",
  "OC_MQTT_CHANNEL_PASSWORD": "xxx",
  "OC_MQTT_CHANNEL_INBOUND_TOPIC_TPL": "agents/channel/{agent-name}/inbound",
  "OC_MQTT_CHANNEL_OUTBOUND_TOPIC_TPL": "agents/channel/{agent-name}/outbound",
  "S3_ACCESS_KEY_ID": "xxx",
  "S3_SECRET_ACCESS_KEY": "xxx",
  "S3_ENDPOINT_URL": "https://s3.cn-east-1.qiniucs.com",
  "S3_REGION": "cn-east-1"
}

```

各项配置的来源如下：

- HZG_CLI_MQTT_BROKER：步骤2中记录的访问地址
- HZG_CLI_USERNAME、OC_MQTT_CHANNEL_USERNAME：步骤2中记录的用户名
- HZG_CLI_PASSWORD、OC_MQTT_CHANNEL_PASSWORD：步骤2中记录的密码
- OC_OPENAI_API_KEY：如果你采用的大模型是 OpenAI 风格接口，将密钥配置到这里
- OC_ANTHROPIC_API_KEY：如果你采用的大模型是 Anthropic 风格接口，将密钥配置到这里
- S3_ACCESS_KEY_ID：步骤3中记录的 AK
- S3_SECRET_ACCESS_KEY：步骤3中记录的 SK
- S3_REGION：步骤3中记录的 Region
- S3_ENDPOINT_URL：步骤3中记录的 S3 Endpoint

其他项目直接采用默认值即可。

### 4.2 安装 Docker

以 Ubuntu 24.04 为例，推荐使用 Docker 官方 `apt` 仓库安装 Docker Engine。

```bash
sudo apt update
sudo apt remove -y docker.io docker-compose docker-compose-v2 docker-doc podman-docker containerd runc || true

sudo apt install -y ca-certificates curl
sudo install -m 0755 -d /etc/apt/keyrings
sudo curl -fsSL https://download.docker.com/linux/ubuntu/gpg -o /etc/apt/keyrings/docker.asc
sudo chmod a+r /etc/apt/keyrings/docker.asc

sudo tee /etc/apt/sources.list.d/docker.sources > /dev/null <<EOF
Types: deb
URIs: https://download.docker.com/linux/ubuntu
Suites: $(. /etc/os-release && echo "${UBUNTU_CODENAME:-$VERSION_CODENAME}")
Components: stable
Architectures: $(dpkg --print-architecture)
Signed-By: /etc/apt/keyrings/docker.asc
EOF

sudo apt update
sudo apt install -y docker-ce docker-ce-cli containerd.io docker-buildx-plugin docker-compose-plugin
```

安装完成后，先验证 Docker 服务状态和基础运行是否正常：

```bash
sudo systemctl status docker --no-pager
sudo docker run hello-world
docker compose version
docker buildx version
```

### 4.3 拉取镜像并启动

Agent 执行器的镜像保存在阿里云，您需要将其拉取到 `OC端`。该镜像文件尺寸超10GB，拉取时间较长。

```bash
docker pull crpi-4auaoyyj6r36p6lb.cn-hangzhou.personal.cr.aliyuncs.com/huozige_lab/enterprise-agent-platform-oc-x64:{版本号}
```

版本号请参考本方案的 release ，如 `20260429.02`。如需在 arm64 架构的服务器上部署，请发邮件联系：`will.ning@grapecity.com`

拉取完成后，您需要执行命令并启动名为 `enterprise-agent-platform-oc` 的容器。

```bash
docker run -d \
  --name enterprise-agent-platform-oc \
  --init \
  --restart unless-stopped \
  -e PLATFORM_DATA_ROOT=/var/platform_data \
  -v "/var/platform_data:/var/platform_data" \
  crpi-4auaoyyj6r36p6lb.cn-hangzhou.personal.cr.aliyuncs.com/huozige_lab/enterprise-agent-platform-oc-x64:{版本号}

```

其中 `-v "/var/platform_data:/var/platform_data"` 中第一个 `/var/platform_data` 为 DATA 的路径。

### 4.3.1 升级已有容器到新镜像

如果服务器上已经使用旧版本 image 创建了容器，升级时不要直接复用旧 container，而是要保留原来的 DATA 目录，删除旧 container，再用新 image 创建一个同名或新名 container，并继续挂载同一个 DATA 目录。

推荐先备份整个 DATA 目录，至少备份以下内容：

- `env.json`
- `config.json`
- `.openclaw/`
- `platform-version.json`

升级步骤如下：

1. 拉取新版本镜像。
2. 停止并删除旧 container。
3. 使用新 image 按原来的挂载参数、重启策略、环境变量重新创建 container。
4. 启动新 container。
5. 执行 `doctor`、`agents list`、`logs` 检查升级结果。

示例命令如下：

```bash
docker pull crpi-4auaoyyj6r36p6lb.cn-hangzhou.personal.cr.aliyuncs.com/huozige_lab/enterprise-agent-platform-oc-x64:{新版本号}

docker stop enterprise-agent-platform-oc
docker rm enterprise-agent-platform-oc

docker create \
  --name enterprise-agent-platform-oc \
  --init \
  --restart unless-stopped \
  -e PLATFORM_DATA_ROOT=/var/platform_data \
  -v "/var/platform_data:/var/platform_data" \
  crpi-4auaoyyj6r36p6lb.cn-hangzhou.personal.cr.aliyuncs.com/huozige_lab/enterprise-agent-platform-oc-x64:{新版本号}

docker start enterprise-agent-platform-oc
```

升级完成后，建议立即执行：

```bash
docker exec enterprise-agent-platform-oc doctor
docker exec enterprise-agent-platform-oc agents list
docker exec enterprise-agent-platform-oc logs
```

说明：

- 旧 container 执行 `docker restart` 不会切换到新 image，只会重启旧 image 创建出的 container。
- 只要继续挂载原来的 DATA 目录，已有 agent、workspace、日志和运行态配置都会被保留。
- 当前镜像启动时会自动识别 `/var/platform_data/platform-version.json`，并按初始化、同版本复用或升级流程处理受管文件。
- 如果某个 DATA 目录已经被更高版本 image 升级过，再用低版本 image 启动时会被拒绝，避免降级破坏数据。

### 4.4 创建 Agent（数字员工）

在 Docker 中执行 `agents add` 和  `agents inject` 命令，创建一个名为 `tester` 的 agent，用于测试使用；再将业务约束注入到 agent 的 AGENT.md、SOUL.md 和 USER.md。

```bash
docker exec enterprise-agent-platform-oc agents add tester
docker exec enterprise-agent-platform-oc agents inject tester
docker restart enterprise-agent-platform-oc
```

执行 `agents list` 命令，获取并记录下新创建 agent 的 `inbound` 和 `outbound` topic

```bash
docker exec enterprise-agent-platform-oc agents list
```

### 4.5 Agent 执行器的命令行工具

Agent 执行器内置了一些创建的操作命令，均可通过 `docker exec` 调用，具体如下：

`agents` 命令：用于操作实际执行操作的agent

- agents add <agent_name> ：创建一个 agent，并更新运行态配置与 workspace 文件；执行完成后，请手工执行 `docker restart <container>` 使变更生效。
- agents list：列出所有 agent 的信息，会输出 `AGENT_ID / ACCOUNT_ID / WORKSPACE / INBOUND / OUTBOUND` 五列，适合在注册到业务系统前先核对 topic 和 workspace。
- agents delete <agent_name>：删除一个 agent，并更新运行态配置；执行完成后，请手工执行 `docker restart <container>` 使变更生效。
- agents info <agent_name>： 获取指定 agent 的信息
- agents inject [agent_name]：为指定的 agent 更新 AGENTS.md、SOUL.md 和 USER.md；执行完成后，请手工执行 `docker restart <container>` 使变更生效。

`logs` 命令：查看执行器的运行日志

- logs：查看 OpenClaw gateway 的运行日志；如果需要看容器入口脚本或容器级重启信息，再配合 `docker logs <container>` 一起看。

`doctor` 命令：用于执行配置自检，确保配置层面的完整性

- doctor：检查配置，包含 `config.json`、`env.json`、目录权限、QMD/OpenClaw CLI/AWS CLI 可用性、S3 客户端配置、`openclaw config validate`，以及 gateway 是否处于运行状态；建议在首次部署、升级镜像、修改 `env.json` 或排查 agent 无响应问题时先执行一次。

### 4.6 Agent 执行器的内置组件

Agent 执行器基于 `OpenClaw`，内置了以下常用组件（CLI 程序 / APT 类库）

- QMD：用于对 Memory 进行语义检索，提升效率
- Agent-Browser：基于 Chrome 的无头浏览器
- Tesseract-ocr：类库，用于 OCR

你和 AI 都可以在使用过程中通过 `npm` 或 `pip` 安装并运行 JavaScript/TypeScript 或 Python 的脚本。

更多信息，请阅读： [DEV_GUIDE.md](/DEV_GUIDE.md)

这一步需要记录以下信息备用：

- Inound Topic
- OUtbound Topic

## 5、配置活字格 Agent 门户应用

使用活字格设计器打开 `https://gitee.com/low-code-dev-lab/open-claw-enterprise-terminal` 示例工程，将其导入到您的工程，适配您的数据库、用户管理、界面风格后再发布到 `服务器端`，成为 AI 工作台应用（如命名为 `claw`）。

您也可以直接将该示例工程修改认证方式为普通认证后发布到 `服务器端`，做学习和验证使用，默认应用管理员角色为：`OpenClaw管理员`。

### 5.1 管理控制台

在管理控制台上，设置 `claw` 应用的全局变量：

- MQTT_BROKER_HOST ： 步骤2中记录的访问地址（去掉 schema 和端口，如 example.ala.cn-hangzhou.emqxsl.cn）
- MQTT_BROKER_SCHEMA ： 步骤2中记录的访问地址的 schema，如 `mqtts` 或 `mqtt`
- MQTT_BROKER_PORT ： 步骤2中记录的访问地址的端口
- MQTT_BROKER_USER ： 步骤2中记录的用户名
- MQTT_BROKER_PASSWORD ： 步骤2中记录的密码
- OPENCLAW_CLIENT_NAME ： 你喜欢的名字，会出现在日志中，如使用你的公司名
- MQTT_RES_CHANNEL_NAME ： agents/cli/req 和步骤4中 `HZG_CLI_REQUEST_TOPIC` 一致
- MQTT_REQ_CHANNEL_NAME ： agents/cli/res 和步骤4中 `HZG_CLI_RESPONSE_TOPIC` 一致
- S3_ENDPOINT ： 步骤3中记录的 S3 Endpoint
- S3_REGION ：步骤3中记录的 Region
- S3_AK ： 步骤3中记录的 AK
- S3_SK ： 步骤3中记录的 SK
- S3_BUCKET_INBOX ：固定为 `agents-in`

### 5.2 Agent 门户应用

登录到 `claw` 后，在 `数字员工管理` 页面中注册你的 Agent，与步骤4的 Agent 配置一一对应。每一个希望让用户操作的 Agent，都需要在这里注册。

- 数字员工名称 ： 你喜欢的名称
- Inbound-Channel ： 步骤4中记录的该 Agent 对应的 `inbound topic`
- Outbound-Channel ： 步骤4中记录的该 Agent 对应的 `outbound topic`

然后修改 `Template` 提示词模板，其中提供了4个用于替换的关键字：

- `[Input]`：用户输入的问题，必须保留
- `[Session]`：`服务器端` 的会话 ID，“一个用户 + 一个 Agent 的组合”对应一个会话，这个信息会影响鉴权，必须保留
- `[UserName]`：当前使用的用户名，可选
- `[FullName]`：当前使用的用户全名，可选

最后修改 `Users` 字段，设置有权限使用该 Agent 的用户列表，多个用户间采用半角逗号分隔。

建议：**为小组建立共享 Agent，而不是为每个员工建立 Agent，这样能通过工作文件共享提升协作效率。**

重要：**注册 Agent 后，需要在管理控制台中重启活字格应用方可生效。**

### 5.3 测试一下

在 `开始对话` 页面中，选择一个 `AI助理`（即数字员工），和 AI 交流。如上传一个文本文件，让AI阅读后告诉你文件中的内容，以确保系统工作正常、通讯链路顺畅。

## 6、连接活字格 App

### 6.1 生成并上传 Ontology 文档

`Ontology 文件` 是 OpenClaw 可以像人类员工一样操作使用活字格开发的 Web App 的关键。

`Ontology 文件` 中包含该 App 中所有实体、动作和关系，可以帮助 AI 理解企业业务本身，更好地选择最合适的 Web API。

`Ontology 文件` 是一个包含诸多 markdown 文件的文件夹，使用 `huozige-ontology-builder` 生成。

安装生成工具：

```bash
npm install -g huozige-ontology-builder
```

使用生成工具：

```bash
huozige-ontology-builder https://gitee.com/kadbbz_admin/hzg-ontology-builder-sample --workdir /tmp/hzg-workspace --app_info xxx系统，主要提供xxx、yyy、zzz等功能。
```

其中：

`Ontology文件` 统一存储在 `OC端` 的 `/var/platform_data/ontology` 文件夹中（映射到 {DATA}/ontology ，{DATA}是步骤4中创建的DATA文件夹路径）。每个 App 对应了一个子文件夹，如 wms App（活字格中应用名是 wms ）的 `Ontology文件` 需要上传到 `wms`子文件夹，上传时需要注意，`index.md` 务必要直接放到该文件夹，不要再套一层子文件夹。

为了进一步提升 Agent 操作业务系统的准确性，推荐按照以下最佳实践，对活字格的应用进行重构：

- 确保表、列、服务端命令和输入输出参数的命名具有业务含义，不要使用无意义的词语，如 `abc` 等
- 表、列和参数、服务端命令的命名需要遵循[最佳实践](https://www.grapecity.com.cn/lowcode/enterprise-low-code-practice/development/tips-naming-conventions)
- 服务端命令中的参数如果是枚举值，需要在备注中补充可以接受的值，如 `修改产品状态` 的 `状态` 参数，需要在备注中写清 `0为正常，1为仅直销，2为停售`
- 为表、列设置别名，为服务端命令增加描述，为参数增加备注，都能帮助 AI 更好的理解您的业务，但需要确保这些人工编写的信息和实际业务逻辑保持一致，修改逻辑时，也要同步修改这些内容
- 对于能够建立起关联的表，尽量建立关联，这将会帮助 AI 更好的理解相关业务
- 保持服务端命令的“单一职责”，尽量避免用同一个服务端命令承载多项业务（通过参数来做区分具体的业务逻辑）。如果不能进行逻辑层面的重构，也可以尝试为该参数增加备注，能够在一定程度上缓解 AI 的误解风险
- 保持数据表的设计满足主流数据库设计范式，每张表中仅存放一类业务数据，该数据需要和表名的业务含义保持一致。字典表也要遵循本原则。如不要将 `客户` 和 `供应商` 存放在同一张表，也不要将 `供应商类型枚举` 与 `单据类型枚举` 存放在同一张表。
- 如果某个表仅通过 `图文列表`、`图表`、`报表`、`ReportSheet`、`甘特图`、`ELementPlus系列` 单元格类型（如 `EL选择器`）绑定使用， `Ontology文件` 中将不会包含读取该表数据的能力，这在主数据、字典数据上并不罕见，建议专门开发查询该表的服务端命令或在孤立的页面中放置绑定了该表的 `表格`，作为补充

每个 App 对应一个子文件夹。例如 `wms` App（活字格中应用名是 `wms`）的 `Ontology 文件` 需要上传到 `/opt/openclaw_enterprise_terminal/ontology/wms`。上传时需要注意，`index.md` 务必要直接放到该文件夹，不要再套一层子文件夹。

为了进一步提升 AI 操作业务系统的准确性，推荐按照以下最佳实践，对活字格应用进行重构：

- 确保表、列、服务端命令和输入输出参数命名具有业务含义，不要使用无意义词语，如 `abc`
- 表、列、参数、服务端命令的命名需要遵循最佳实践
- 服务端命令中的参数如果是枚举值，需要在备注中补充可以接受的值。例如 `修改产品状态` 的 `状态` 参数，需要在备注中写清 `0为正常，1为仅直销，2为停售`
- 为表、列设置别名，为服务端命令增加描述，为参数增加备注，都能帮助 AI 更好理解业务，但需要确保这些人工编写的信息和实际业务逻辑保持一致，修改逻辑时也要同步修改
- 对于能够建立关联的表，尽量建立关联，这将帮助 AI 更好理解相关业务
- 保持服务端命令的“单一职责”，尽量避免用同一个服务端命令承载多项业务。如果不能进行逻辑层面重构，也可以尝试为该参数增加备注，在一定程度上缓解 AI 误解风险
- 保持数据表设计满足主流数据库设计范式，每张表中仅存放一类业务数据，该数据需要和表名业务含义保持一致
- 如果某个表仅通过 `图文列表`、`图表`、`报表`、`ReportSheet`、`甘特图`、`ElementPlus` 系列单元格类型绑定使用，`Ontology 文件` 中将不会包含读取该表数据的能力，建议专门开发查询该表的服务端命令，或在孤立页面中放置绑定了该表的 `表格` 作为补充

注意：**更新发布 Web App 后，需要在将工程推送至 Git 后重新生成 Ontology 文件，并上传到 OC 端，确保 AI 能够理解最新版 App 的操作方法。**

### 6.2 注册 App 信息

登录到 `claw` 后，在 `应用管理` 页面注册该应用：

- 应用名称：发布到服务器上的应用名
- 应用访问地址：该应用的访问地址，通常为 `http://localhost:{port}/{appName}`

### 6.3 测试一下

在 `开始对话` 页面中，选择一个 `AI助理`，和 AI 交流。如询问 AI 该应用开放的能力清单，以确保 `Ontology文件` 被成功加载；请 AI 帮你执行一个简单的查询操作，以确保 `活字格Web APP Cli` 和通讯链路正常运行。

### 6.4 技术限制

截止活字格 `v12.0` 版本，本方案存在以下技术限制：

- 无法读取活字格 App 存储在数据库的文件（含附件和图片），也无法上传文件到活字格 App。这将导致附件/图片类型的列，和附件/图片类型的参数在调用时被忽略
- 无法调用活字格工程中引用的“外部服务端命令”。

## 技术支持

发送邮件到 <will.ning@grapecity.com>

## 协议

MIT

## 其他

- [二次开发与编译](/DEV_GUIDE.md)
- [裸机部署](/MANUAL_DEPLOY.md) ，可以有更高的灵活度