huozige-ontology-builder

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

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

整个过程不依赖 AI，只依赖文件扫描和 JSON 结构解析。

解析范围

• Tables/**/*.json
• ServerCommands/**/*.json
• Pages/**/*.json
• MasterPages/**/*.json
• UserControlPages/**/*.json

当前对带 HTTP 触发器的服务端命令判定规则是：

• ServerCommands 中包含 PostRequestTrigger

服务端命令扫描模式由 --sc_mode 控制，默认值是 all：

• all：扫描所有服务端命令
• whitelist：仅扫描备注中包含 [HOB_INCLUDE] 的服务端命令
• blacklist：扫描所有服务端命令，但跳过备注中包含 [HOB_EXCLUDE] 的服务端命令

安装

npm install -g huozige-ontology-builder

全局安装后，可直接执行：

huozige-ontology-builder

使用

huozige-ontology-builder https://gitee.com/kadbbz_admin/hzg-ontology-builder-sample

指定工作目录：

huozige-ontology-builder https://gitee.com/kadbbz_admin/hzg-ontology-builder-sample --workdir /tmp/hzg-workspace

指定服务端命令扫描模式：

huozige-ontology-builder https://gitee.com/kadbbz_admin/hzg-ontology-builder-sample --sc_mode whitelist

指定应用信息：

huozige-ontology-builder https://gitee.com/kadbbz_admin/hzg-ontology-builder-sample --app_info "这是一个示例应用，没有具体业务"

本地开发调试：

npm install
npm run build
node dist/cli.js https://gitee.com/kadbbz_admin/hzg-ontology-builder-sample --workdir /tmp/hzg-workspace

组合使用：

node dist/cli.js https://gitee.com/kadbbz_admin/hzg-ontology-builder-sample --workdir /tmp/hzg-workspace --sc_mode blacklist

如果你只是在当前项目目录执行了 npm install，命令不会自动安装到全局 PATH。此时可以改用以下任一方式运行：

npm run start -- https://gitee.com/kadbbz_admin/hzg-ontology-builder-sample

npx huozige-ontology-builder https://gitee.com/kadbbz_admin/hzg-ontology-builder-sample

输出目录

CLI 会在工作目录下创建一次运行对应的时间戳目录：

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

其中：

• clone 路径：<timestamp>/src/<git-name>/
• 输出路径：<timestamp>/result/<git-name>/

输出内容

会同时输出：

• ontology.json
• index.md
• entities/entity-{实体名}.md
• servercommands/sc-{服务端命令名}.md
• bindings/binding-{页面名}.md

ontology.json

核心结构如下：

{
  "repo-name": "simple-forguncy-reporting-system",
  "app_info": "示例应用",
  "huozige-version": "11.0.104.0",
  "builder-version": "0.3.0",
  "tables": [
    {
      "table-name": "数据表",
      "table-description": "",
      "columns": [
        {
          "column-name": "id",
          "column-alias": "主键",
          "column-datatype": "Number",
          "column-required": true,
          "column-unique": true
        }
      ],
      "relationships": []
    }
  ],
  "candidatesbindings": [
    {
      "page-name": "页面1",
      "component-type": "ComboBox",
      "column-bindings": [
        {
          "column-type": "ID",
          "TableName": "数据表",
          "ColumnName": "ID",
          "GUID": "a0b4a492-276b-4a0c-a3c2-1d8fe1596f8a"
        },
        {
          "column-type": "text",
          "TableName": "数据表",
          "ColumnName": "文本",
          "GUID": "2bfc7ad4-c23b-460e-877e-b0ed785be45b"
        }
      ]
    }
  ],
  "tablebindings": [
    {
      "page-name": "页面1",
      "view-name": "页面1表格1",
      "list-view-location": "页面1|表格1",
      "table-name": "数据表",
      "columns": [
        {
          "table-name": "数据表",
          "column-name": "文本",
          "guid": "067cc6ea-73f0-4f2f-9dee-9d5d8a178e96"
        }
      ]
    }
  ],
  "data-source-bindings": [
    {
      "page-name": "页面1",
      "cell-location": "102,2",
      "table-name": "数据表",
      "columns": [
        {
          "display-name": "label",
          "table-name": "数据表",
          "column-name": "文本"
        }
      ],
      "query-params": [
        {
          "#": 1,
          "key": "=页面1!ComboBox1",
          "table-name": "数据表",
          "column-name": "外键列"
        }
      ]
    }
  ],
  "servercommands": [
    {
      "servercommand-name": "ExampleCommand",
      "servercommand-description": "PostRequestTrigger",
      "verb": "post",
      "input-arguments": [],
      "output-arguments": [],
      "used-by": []
    }
  ]
}

Table Extraction Rules

• table-name 读取自表 JSON 的 Name
• table-description 固定输出空字符串，不读取表级 Comment
• column-alias 读取自列 JSON 的 Alias，如果缺失则回退到列 Name
• app_info 读取自命令行参数 --app_info
• 校验样例：https://gitee.com/kadbbz_admin/hzg-ontology-builder-sample/blob/master/Tables/new_table_%E8%A1%A8%E5%88%AB%E5%90%8D_.json

Markdown 输出

• entities/entity-{实体名}.md：单个实体的字段与关系
• index.md：项目总览，包含 Entities、Bindings 和 ServerCommands 摘要
• servercommands/sc-{服务端命令名}.md：单个服务端命令详情
• bindings/binding-{页面名}.md：单个页面的 candidatesbindings、tablebindings 和 data-source-bindings 汇总

index.md 中会保留三类摘要信息：

• Entities：数量、目录、命名规则、完整实体名列表
• Bindings：页面数量、目录、命名规则、完整页面名列表
• ServerCommands：数量、目录、命名规则、完整命令名列表

规则说明

候选项绑定

会扫描页面上的：

• RadioGroupCellType
• CheckBoxGroupCellType
• DropDownListCellType

字段映射规则：

• ValueColumnBindingInfo 输出为 column-type: "ID"
• DisplayColumnBindingInfo 输出为 column-type: "text"

表格绑定

识别规则：

1. 在 AttachInfos 中查找包含 ListViewInfo 的单元格，作为表格锚点。
2. 读取 ListViewInfo.Name、TableName、RowIndex、ColumnIndex、RowCount、ColumnCount。
3. 在表格区域内查找带 BindingInfo 的单元格。
4. 只收集与当前 ListViewInfo.TableName 相同的绑定列。

数据源绑定

识别规则：

1. 在 Pages/**/*.json 的 AttachInfos 中查找坐标单元格。
2. 在单元格内容中查找名为 bindingOptions 的对象。
3. 仅匹配 $type 等于 ServerDesignerCommon.Model.BindingDataSourceModel, ServerDesignerCommon 的数据源绑定。
4. cell-location 输出 AttachInfos 的外层坐标；没有外层坐标的数据源（例如图表数据映射中的 DataSource）不输出。
5. 输出 bindingOptions.TableName 和 BindingInfos 中的展示名、数据表名、数据列名。
6. query-params 只输出由页面/组件公式引用传入的动态查询条件，即 Value.$type 为 Forguncy.Model.FormulaReferObject, ServerDesignerCommon 且 SerializeProperty 引用页面单元格或组件。固定值过滤条件不输出为参数。
7. query-params.key 输出动态条件的 Value.SerializeProperty 公式。
8. 如果 bindingOptions.SqlCondition 没有 SubConditions，且当前条件符合第 6 条，读取当前条件的 ColumnBindingInfo 作为 query-params。
9. 如果 bindingOptions.SqlCondition 带 SubConditions，按数组顺序展开下级条件，并只输出符合第 6 条的下级 ColumnBindingInfo；不读取父级条件的 ColumnBindingInfo。

服务端命令扫描模式

• all：扫描 ServerCommands/**/*.json 下的全部服务端命令
• whitelist：仅保留备注中包含 [HOB_INCLUDE] 的命令
• blacklist：排除备注中包含 [HOB_EXCLUDE] 的命令
• 服务端命令备注读取自 Description

示例文件

• output-sample/ontology.json
• output-sample/entities/entity-answer.md
• output-sample/index.md
• output-sample/servercommands/sc-CreatPaper.md
• output-sample/bindings/binding-页面1.md

校验

npm run check
npm run build
npm pack --dry-run