跳到主要内容

AI Agent 系统搭建

1. 简介​

zgg-cli 是智管工零代码平台的命令行工具，安装后可以让 AI 助手（如 WorkBuddy）直接用自然语言帮你搭建智管工平台上的业务系统。

举个例子：

以前你要在智管工里创建一个表单，需要：

  1. 打开网页
  2. 点击创建表单
  3. 逐个添加字段（姓名、手机号、部门……）
  4. 配置每个字段的属性
  5. 保存、发布

现在你只需要跟 AI 说一句话：

"帮我创建一个员工信息表，包含姓名、手机号、部门和入职日期。"

AI 就会自动帮你完成所有操作，几分钟就搞定。

2. 安装​

2.1 环境要求​

项目要求
操作系统Windows 10/11、macOS 12+、Linux（Ubuntu 20.04+、CentOS 8+）
网络能正常访问智管工平台
权限智管工平台运营中心权限

2.2 安装命令​

macOS / Linux​

curl -fsSL https://zgg.tos-cn-guangzhou.volces.com/zgg-cli/install.sh | bash

Windows (PowerShell)​

irm https://zgg.tos-cn-guangzhou.volces.com/zgg-cli/install.ps1 | iex

安装完成后，关闭所有已打开的终端窗口，重新打开一个新的终端，验证安装：

zgg --version

如果显示版本号（如 zgg 0.1.7），说明安装成功。

3. 升级​

zgg-cli 支持通过相同的安装命令直接升级到最新版本，安装脚本会自动检测并下载最新版本，覆盖旧版本。也可以使用zgg update 命令检查版本更新并进行升级。

同时还可以指定版本号安装：

  • macOS/Linux: curl -fsSL .../install.sh | bash -s -- --version 0.2.0
  • Windows: irm .../install.ps1 | iex -Version 0.2.0

4. 使用​

4.1 使用前准备​

4.1.1 创建工作区文件夹​

由于在AI创建表单的过程会生成一些配置文件以及单位的id配置，所以需要在电脑中创建一个文件夹用于保存这些配置，并且在AI 助手开始对话前也需要选择对应的文件夹作为工作空间（下图是WorkBuddy的示例）

workbuddy

4.1.2 登录智管工账号​

AI 助手需要以你的身份操作智管工平台，所以第一次使用前需要登录。由于登录时会生成区作区的单位配置信息，所以最好在终端进入工作区目录后再登录，如：

# windows系统
D:
cd D:\workspace\projectName

# mac/linux
cd /Users/username/workspace/projectName

方式一：账号密码登录

zgg auth login

按提示输入账号和密码。

方式二：使用已有 Token 登录

如果你已经有 Token（从浏览器开发者工具获取的）：

zgg auth login --token <YOUR_TOKEN>

方式三：浏览器登录

zgg auth login --browser

输入后，会自动打开浏览器，进行登录操作，并将 Token 保存在你的电脑里（默认存入系统钥匙串）。

4.1.3 验证登录状态​

zgg auth status

4.1.4 配置单位信息​

登录账号后会默认把用户的当前单位写入工作区的配置文件，如果需要为其他单位创建表单，需要修改配置文件（很重要，因为默认配置是首次登录的单位，如果不修改，表单会创建到这个单位中），详见【配置文件说明】

4.2 配置文件说明​

4.2.1 用户目录配置文件​

记录了当前使用的配置，包括基础接口地址，当前单位id，登录的用户信息等

windows路径：C:\Users\你的用户名.zgg\config.json

mac/linux路径：/Users/你的用户名/.zgg/config.json

什么是 Profile？

Profile 就是一套环境配置。你可以为不同的环境创建不同的 Profile：

  • default — 开发环境
  • prod — 生产环境
  • custom — 私有化环境（注意：私有化环境的base_url在域名之后还需要添加/zos/ops/api)

profile_config

通过 zgg config switch <名称> 可以在不同环境之间切换。

4.2.2 工作区配置文件：​

工作区配置文件位于工作区内的 .zgg/config.json，只记录单位id和名称，配置系统时的单位ID从该文件读取。 在开始单位的配置前，需要确认单位信息与目标单位的ID一至（可以到运营中心的单位信息中查看），可以在终端中进入工作区目录后运行命令进行设置：zgg config workspace-init --company-id <ID> --company-name <名称> ，或者在搭建系统前直接告诉AI 单位ID和名称，叫AI设置。

单位ID config

4.3 通过 AI 助手使用​

安装完成后，你可以通过支持 Skill 的 AI 助手（如 Claude Code、WorkBuddy）来使用本工具，安装脚本会默认将本工具专用的技能安装到WorkBuddy的技能目录。

如果需要使用其他本地 AI 助手，可以通过zgg skills link --dir <YOUR AGENT SKILL DIR> 来将技能链接到你的AI助手的技能目录，也可以手动将 ~/.zgg/skills/ 内的技能拷到 AI 助手的技能目录。

使用方式：直接跟 AI 说话​

打开你的 AI 助手，像平时聊天一样描述你的需求即可。(如果描述中没有触发技能，请显性调用技能 /zgg-system-builder)

示例 1：创建简单表单​

你说：

"帮我创建一个产品信息表，包含产品名称、产品编号、产品分类和状态。"

AI 会自动：

  1. 在智管工平台创建表单
  2. 添加你提到的所有字段
  3. 配置合适的字段类型（文本、编号、下拉选项等）
  4. 创建列表视图
  5. 挂载到导航目录

然后告诉你：

"已完成产品信息表的创建，包含 4 个字段。您可以通过 [链接] 访问。"

示例 2：创建复杂系统​

你说：

"帮我搭建一个订单管理系统，需要订单表（订单编号、客户名称、订单金额、下单日期）、客户表（客户名称、联系人、电话），订单表要能关联客户表。"

AI 会自动：

  1. 创建"订单管理"导航目录
  2. 创建客户表并配置字段
  3. 创建订单表并配置字段
  4. 在订单表中添加"关联客户"字段（关联到客户表）
  5. 为两个表分别创建视图
  6. 挂载到导航目录

示例 3：修改已有表单​

你说：

"在员工信息表里加一个'入职日期'字段。"

AI 会自动找到员工信息表，在末尾添加新字段。

4.4 支持的字段类型​

AI 可以帮你配置以下类型的字段：

常用字段​

字段类型说明示例
单行文本普通的文字输入框姓名、产品名称
多行文本大段的文字输入备注、说明
数字只能输入数字价格、数量、年龄
手机号专门的手机号输入联系电话
日期时间日期选择器入职日期、下单日期
单选框只能选一个性别（男/女）
多选框可以选多个兴趣爱好
下拉单选下拉菜单选一个状态（上架/下架）
下拉多选下拉菜单选多个标签
图片上传上传图片产品图片
附件上传上传文件合同附件

高级字段​

字段类型说明
成员选择选择公司里的某个人
部门选择选择某个部门
子表单在一个表单里嵌套另一个表单
关联数据关联到另一个表的数据
汇总自动计算汇总值
流水号自动生成编号
手写签名电子签名
地址地址选择
定位GPS 定位
富文本带格式的文字编辑

4.5 推荐工作流​

  1. 根据需求创建功能清单，并将其放入工作区

最好使用Markdown格式，写好系统描述及所有需要的表单和表单字段，并将字段类型和字段配置描述清楚（可以由AI 助手生成）。

  1. 在AI 助手中调用技能创建系统表单

例如在WorkBuddy中描述：

/zgg-system-builder @功能清单.md 请按照这个清单创建系统

注意：如果系统比较大，表单和字段较多，最好分多个文档写好，然后分多次调用，防止 AI 大模型因为上下文太长导致注意力分散，执行质量下降

5. 常用命令参考​

5.1 认证​

命令说明
zgg auth login交互式账号密码登录
zgg auth login --save-inlineToken 直接存配置文件
zgg auth login --token <TOKEN>用已有 token 登录
zgg auth login --browser在浏览器中登录
zgg auth status查看登录状态
zgg auth logout退出登录

5.2 配置​

命令说明
zgg config init交互式初始化配置
zgg config list列出所有 Profile
zgg config switch <name>切换 Profile

5.3 表单​

命令说明
zgg form create --title "..." [--dir-id ID]创建表单
zgg form save --form-id ID --file path.json保存表单组件设计
zgg form detail --form-id ID获取表单详情
zgg form fields --form-id ID获取表单字段列表

5.4 文件夹​

命令说明
zgg folder create-nav --title "..."创建导航文件夹
zgg folder create-form --title "..."创建表单文件夹
zgg folder create-view --title "..."创建视图文件夹
zgg folder tree获取目录树

5.5 视图​

命令说明
zgg view create --form-id ID [--title "..."]实例化视图

5. 常见问题​

Q1：安装后提示"找不到命令"​

A： 请关闭所有终端窗口后重新打开。PATH 环境变量的修改需要新窗口才能生效。

Q2：Mac系统登录时频繁弹系统密码提示​

A： 使用 --save-inline 参数登录，Token 将直接写入配置文件而非系统钥匙串：

zgg auth login --save-inline

Q3：如何切换环境（开发/生产）？​

A：

# 查看所有配置
zgg config list

# 切换到生产环境
zgg config switch prod

Q4：如何卸载？​

A： 直接删除安装目录即可：

  • macOS/Linux: rm -rf ~/.zgg
  • Windows: 删除 %USERPROFILE%\.zgg 文件夹

然后从 PATH 环境变量中移除对应路径。

Q5：Company ID 是什么？如何获取？​

A： Company ID 是智管工平台分配给每个企业的唯一标识。

获取方式：

  1. 在运行中心>单位配置>单位信息中查看
  2. 登录后自动获取：执行 zgg auth login 后，系统会自动从你账号信息中读取