huozige-ontology-builder

一个基于 TypeScript 的命令行工具，用确定性规则扫描活字格工程并输出简化版 Ontology 文件，包含：

• 表结构 tables：对应实体与实体间关系
• 页面候选项绑定 candidates-bindings：对应候选列绑定信息
• 页面表格绑定 table-bindings：对应表格列绑定信息
• 页面数据源绑定 data-source-bindings：对应图文列表、EL组件等数据源绑定信息
• 服务端命令 servercommands：对应实体动作或函数
• 服务端命令在页面中的使用位置

整个过程不依赖 AI，只依赖文件扫描和 JSON 结构解析，点击详细了解扫描策略。

使用方法

1、安装

在开发活字格应用的电脑上执行命令：

npm install -g huozige-ontology-builder

2、扫描

安装完成后，可以传入活字格协同工程的 Git 地址：

huozige-ontology-builder https://gitee.com/low-code-dev-lab/hzg-ontology-demo-wms --app_info "库存管理系统，提供仓库管理、销售管理功能。"

也可以传入本地 .fgcc 文件：

huozige-ontology-builder ./playground.fgcc --app_info "库存管理系统，提供仓库管理、销售管理功能。"

其中：

• 第一个参数可以是活字格协同工程的 Git 地址，也可以是本地 .fgcc 文件路径
• 传入 Git 地址时，工具会先克隆仓库再扫描。如果执行命令的电脑上第一次打开该协同工程所在的 Git 服务器，可能需要按照界面提示完成登录
• 传入 .fgcc 文件时，工具会直接把该文件按 zip 解压到临时源目录，然后执行后续扫描
• --app_info 是必填参数，用来设置该应用的简要描述，通常需要介绍该应用中覆盖的典型应用场景，这些信息会被写入 Ontology 文件中，帮助 AI 快速定位需要使用的系统
• 服务端命令只有配置了 PostRequestTrigger 且备注不包含 [HOB_EXCLUDE] 才会进入 Ontology；没有 PostRequestTrigger 的私有或内部辅助命令会被直接忽略

可选参数：

• --workdir 参数用来设置工作目录，临时文件和最终生成结果都会被保存到这个目录，如果不指定，则会使用执行命令时的当前目录作为工作目录

扫描生成的 Ontology zip 包位于 result 目录：

<workspace>/
  <timestamp>/
    src/
      <source-name>/
    result/
      <source-name>/
        ontology.json
        index.md
        entities/
          entity-<EntityName>.md
        servercommands/
          sc-<ServerCommandName>.md
        bindings/
          binding-<PageName>.md
        governance-suggestions.md
        ontology-<timestamp>.zip

3、输出包

CLI 会保留原始输出文件，同时生成提供给 AI 使用的“业务系统本体压缩包”：

• 输出目录会保留 ontology.json、index.md 和各个 Markdown 文件夹
• 输出目录会额外生成 governance-suggestions.md，按高优先级和低优先级列出元数据治理建议
• 压缩包文件名为 ontology-<timestamp>.zip
• 压缩包根目录直接包含 index.md
• 压缩包中包含 entities/、servercommands/、bindings/ 等 Markdown 文件夹
• ontology.json 和 governance-suggestions.md 作为原始文件保留在输出目录，但不会写入压缩包

推荐的治理方法

因为 Ontology 均来自活字格中各种元素的命名和说明，为了尽量提升 Ontology 的质量，我们推荐您针对活字格工程进行一些治理工作。这些工作仅限于重命名和补全说明信息，不涉及对业务逻辑、交互或界面的修改。

• 不希望 AI 直接调用的非私有服务端命令，可以在备注中加入 [HOB_EXCLUDE]
• 确保表、列、服务端命令和输入输出参数的命名具有业务含义，不要使用无意义的词语，如 abc 等
• 表、列和参数、服务端命令的命名需要遵循最佳实践
• 服务端命令中的参数如果是枚举值或标记位，需要在备注中补充可以接受的值。例如：
  • 修改产品状态 服务端命令的 状态 输入参数，是一个枚举值，需要在备注中写清 0为正常，1为仅直销，2为停售
  • 维护采购单 服务端命令中，根据 ID 输入参数是否为 %Null% 来决定是创建还是修改，需要在备注中写清 null：新建；否则为修改
  • 删除部门 服务端命令中，根据 组织节点ID 输入参数中是否包含 , 来决定是按照单值处理还是按照数组处理，需要在备注中写清 如需批量处理，用半角逗号分隔
• 表中的列如果是枚举值，需要在表的备注中补充可以接受的值，或者将枚举创建为字典表，然后将该字典表与当前列建立关联

此外，如果 AI 依然难以找到准确的数据或服务端命令，以下的治理工作通常会有所帮助：

• 为表、列设置别名，为服务端命令增加描述，为参数增加备注，都能帮助 AI 更好的理解您的业务，但需要确保这些人工编写的信息和实际业务逻辑保持一致，修改逻辑时，也要同步修改这些内容
• 对于能够建立起关联的表，尽量建立关联，这将会帮助 AI 更好的理解相关业务
• 保持服务端命令的“单一职责”，尽量避免用同一个服务端命令承载多项业务（通过参数来做区分具体的业务逻辑）。如果不能进行逻辑层面的重构，也可以尝试为该参数增加备注，能够在一定程度上缓解 AI 的误解风险
• 保持数据表的设计满足主流数据库设计范式，每张表中仅存放一类业务数据，该数据需要和表名的业务含义保持一致。字典表也要遵循本原则。如不要将 客户 和 供应商 存放在同一张表，也不要将 供应商类型枚举 与 单据类型枚举 存放在同一张表。
• 如果某个表没有绑定到页面元素、也没有相关的服务端命令， Ontology 中将不会包含读取该表数据的能力，建议专门开发查询该表的服务端命令或在孤立的页面中放置绑定了该表的 表格，作为补充

注意：更新发布 Web App 后，需要在将工程推送至 Git 后重新生成 Ontology 文件，并在 AIOS 中编辑该业务系统，重新上传，以确保 AI 能够理解最新版 App 的操作方法。

技术限制

当前版本在扫描和生成 Ontology 时，存在以下技术限制：

• 无法扫描 附件/图片 类型的列，这将导致 AI 无法操作涉及到文件上传/下载的业务系统功能。对于输入或输出参数中包含这种列的服务端命令，推荐在备注中加入 [HOB_EXCLUDE]
• 无法扫描 外部服务端命令，这将导致 AI 无法直接调用注册到应用的外部服务端命令。如有需要，可以将其封装为服务端命令。

本地开发

npm install
npm run build
node dist/cli.js https://gitee.com/low-code-dev-lab/hzg-ontology-demo-wms --app_info "库存管理系统，提供仓库管理、销售管理功能。" --workdir /tmp/hzg-workspace

npm run check
npm pack --dry-run