SuperAPI AI 工具集

use-semantius

通用与其它

查看项目

更新于 10-16 02:20

技能介绍

use-semantius 技能用于通过 semantius CLI 操作 Semantius 平台。Semantius 是一个低代码平台,你可以定义语义数据模型(实体、字段、关系和访问规则),并立即获得一个完全托管的 PostgreSQL 数据库、REST API、自动生成的 UI 和分析层。你定义数据的样子(第一层),Semantius 负责存储、查询(第二层)和跨表分析(第三层)。

架构分为三层:

  • 第一层:语义数据模型。定义实体、字段、模块、关系、基于角色的访问控制。涉及表包括 entities、fields、modules、permissions、roles 等。使用 create_entity、create_field、create_permission 等工具。
  • 第二层:业务数据(通过 PostgREST 访问 PostgreSQL)。实体表中的实际记录,例如 /products、/orders。使用 postgrestRequest 工具(GET/POST/PATCH/DELETE),以及 sqlToRest 进行 SQL 到 PostgREST 的转换。
  • 第三层:分析(兼容 CubeJS 的 API)。多表查询、聚合、指标、时间序列。使用 cube 的 discover → validate → load / chart 工具。

选择原则:定义存在什么(模式、权限、角色)使用第一层类型化工具;处理单表中的实际记录使用第二层 postgrestRequest;跨表查询或需要聚合/指标使用第三层 cube。

使用方式:技能附带多个参考文件,分别覆盖 CLI 用法、数据建模、实体家族、JsonLogic 规则、select_rule 行级安全、RBAC、CRUD 工具、Cube 查询、Cube 工具、webhook 导入等内容。环境设置需要检查 semantius 是否已安装(semantius --version),并检查连接状态(semantius whoami 或 getCurrentUser)。核心 CLI 命令包括 semantius(列出所有服务器和工具)、semantius -d(带描述列出)、semantius info <server>(显示服务器的工具)、semantius info <server> <tool>(获取工具的 JSON 模式)、semantius grep "<pattern>"(按 glob 搜索工具)、semantius call <server> <tool> '{}'(内联 JSON 调用)等。在 Windows PowerShell 中必须始终传入内联 JSON 或显式管道空输入,否则会挂起。

crud 服务器负责模式管理和记录操作(第一层和第二层),cube 服务器提供兼容 CubeJS 的分析(第三层)。当需要向用户展示 web 应用中的记录或列表时,可以从 getCurrentUser 的 ui_baseurl 构建链接。

黄金规则包括:写前先读(任何 create_* 前先调用 read_* 检查重复);模式优先顺序为 模块 → 权限 → 所有实体 → 字段;不要创建自动生成的字段;reference_table 必须使用 relational 格式;风险变更前警告用户;在有用时提供 UI 链接;始终批量操作(一组记录一次调用,不要循环单次调用);不要仅依赖退出码,需检查响应主体(crud 服务器默认返回 JSON 数组,零行结果返回 exit 0 和空数组 [],这属于协议层成功但领域层未找到)。