# @dforge-core/metadata 中文文档

规范地址：https://npmcn.com/package/%40dforge-core/metadata/

版本：0\.0\.53
npm 元数据更新时间：2026-11-10T21:44:21.891Z
中文译文更新时间：2026-11-12T05:38:03.856Z
软件包许可：MIT

本文由上游 README 翻译，可能存在偏差，请结合原文核对 API、命令与配置。版权与许可归原作者所有。

原始 npm 页面：https://www.npmjs.com/package/%40dforge-core/metadata
原文对照：https://npmcn.com/package/%40dforge-core/metadata/?lang=original
项目主页：https://github.com/iash44/dForge-core/tree/main/clients/packages/metadata#readme
源码仓库：https://github.com/iash44/dForge-core

## 关键信息（来自 npm 元数据）

- 包体积（解压后）：1.1 MB，79 个文件
- 模块格式：ES Module
- TypeScript 类型：包内自带
- 运行依赖：0 个
- 首次发布：2026-06-13T16:03:57.676Z
- 最新版本发布：2026-11-10T21:44:21.732Z
- 近 30 天下载量：3014（2026-10-12 至 2026-11-10，npm 官方下载统计）
- 已发布版本数：51（近 12 个月 51 个）

## 中文简介

Canonical dForge 作者登记册 - 字段类型,基础数据类型,列类型,特征,数据视图类型和图表类型 - 有衍生帮助. 运行时无依赖性;由编辑器,网络应用和CLI共享的单一真理源.

## 安装

```sh
npm install @dforge-core/metadata
```

也可以使用：`pnpm add @dforge-core/metadata`、`yarn add @dforge-core/metadata`、`bun add @dforge-core/metadata`

## README

# @dforge-core/元数据

Canonical dForge 作者登记册、模块文件类型和 JSON 计划 网络应用程序、SDK、图表库、 CLI,MCP服务器,和VS代码扩展.

-   **运行时无依赖.** 可在任何地方安全导入——编辑器,捆绑的网络 应用,节点CLI,MCP服务器.
-   **一个真理的来源.** 登记册反映平台元数据种子 (单位:千美元)`server/database/system-modules/metadata/seed-data/`和结构 类型 : `docs/schemas/`。对等测试失败 如果有漂移的话就建起来.

## 安装

```sh
pnpm add @dforge-core/metadata
```

## 里面的东西

| 表面 | 出口 |
| --- | --- |
| **字段类型** | `fieldTypes`, (中文(简体) ), `fieldTypeCds`, (中文(简体) ), `isFieldTypeCd`, (中文(简体) ), `getFieldType`, (中文(简体) ), `fieldTypesByColumnType` |
| **基础数据类型** | `baseDatatypes`, (中文(简体) ), `baseToDbDatatype` |
| **列类型** | `columnTypes`, (中文(简体) ), `getColumnType` |
| **特质** | `traits`, (中文(简体) ), `getTrait`, (中文(简体) ), `expandTrait`, (中文(简体) ), `expandTraits` |
| **衍生** | `deriveDbDatatype`, (中文(简体) ), `deriveBaseDatatype`, (中文(简体) ), `defaultParams`, (中文(简体) ), `NUMERIC_TOTAL` |
| **合计** | `AggType`, (中文(简体) ), `AGG_TYPE_LIST` |
| **显示旗帜** | `flagDefs` (单位:千美元)`V` 可见 `I` 身份证明 `E` 可编辑 `M` 强制性 `H` 隐藏) |
| **查看/ 报告类型** | `dataViewKinds`, (中文(简体) ), `vizTypes`, (中文(简体) ), `chartTypes` |
| **斯卡拉海内** | `FieldTypeCd`, (中文(简体) ), `BaseDatatypeCd`, (中文(简体) ), `ColumnTypeCd`, (中文(简体) ), `FlagCd`, (中文(简体) ), `AlignType` |
| **模块文件类型** | `ManifestDef`, (中文(简体) ), `EntityDef`, (中文(简体) ), `DataViewsFile`, (中文(简体) ), `ReportsFile`, (中文(简体) ), `MenusFile`, (中文(简体) ), `FoldersFile`, (中文(简体) ), `RolesFile`, (中文(简体) ), `SettingsFile`, (中文(简体) ), `JobsFile`, (中文(简体) ), `TriggersFile`, (中文(简体) ), `WebhooksFile`, (中文(简体) ), `PrintTemplatesFile`, (中文(简体) ), `SeedDataFile`, (中文(简体) ), `ActionsFile`,, , , , , , , , |
| **过滤表达式** | `Filter`, (中文(简体) ), `FilterCondition`, (中文(简体) ), `FilterGroup`, (中文(简体) ), `SortClause` |
| **DSL 分析器** | `./dsl` —— 说 `checkDsl`, (中文(简体) ), `parseDsl`, (中文(简体) ), `tokenize`, (中文(简体) ), `BUILTINS` (见 [动作 DSL](https://npmcn.com/package/%40dforge-core/metadata/#readme-action-dsl)(中文(简体) ) |
| **JSON 计划** | `./schemas/<name>.schema.json` (见 [示马斯](https://npmcn.com/package/%40dforge-core/metadata/#readme-json-schemas)(中文(简体) ) |

## 注册和衍生

作者选一个友好的 `fieldTypeCd`; 帮助者获得物理 元数据,所以没有人手动输入一个原始 SQL 类型 .

```ts
import {
  getFieldType,
  isFieldTypeCd,
  deriveDbDatatype,
  deriveBaseDatatype,
  defaultParams,
} from "@dforge-core/metadata";

isFieldTypeCd("currency");          // true
isFieldTypeCd("reference");         // false — not a real code (it's `lookup`)

getFieldType("currency");
// { cd: "currency", columnType: "D", baseDatatypeCd: "number", precision: 2, ... }

deriveDbDatatype("currency");       // "numeric(18,2)"
deriveDbDatatype("text");           // "varchar"
deriveDbDatatype("textarea");       // "text"
deriveDbDatatype("lookup");         // null — relationship-backed, no own column
deriveBaseDatatype("color");        // "string"
defaultParams("flags");             // { style: "buttons" }
defaultParams("number");            // undefined — numeric types carry no defaults
```

### 特质

```ts
import { expandTrait, expandTraits } from "@dforge-core/metadata";

// Expand a trait into the FieldDef map it contributes to an entity.
expandTrait("audit", "invoice");
expandTraits(["identity", "audit"], "invoice");
```

## 模块文件类型

结构类型描述 _撰写_ a 中每个文件的形状 `.dforge` 模块包——相同的形状是JSON schemas验证.

```ts
import type { ManifestDef, EntityDef, DataViewsFile } from "@dforge-core/metadata";

const entity: EntityDef = {
  description: "Customer",
  dbObject: "customer",
  fields: {
    /* … */
  },
};
```

> 注:这些是: **撰写** 形状。 决心 **运行时间** 模式 由 API 返回(`metadata.getModel`)是不同的合同——见 `@dforge/sdk`是因为 `Model*` 类型,可以重用此包中的 scalar enum.

## 动作 DSL

`@dforge-core/metadata/dsl` 是一个单独的切入点, 持有 lexer, parser 行动机构的静态规则`logic/actions/*.dsl`) (中文(简体) ). 一个执行 为检查这些文件的两台主机服务: 语言服务器, 它会转弯 和模块校验器,它打开一个包.

```ts
import { checkDsl } from "@dforge-core/metadata/dsl";

const issues = checkDsl(source, {
  moduleCode: "wms",
  action: { code: "transfer_stock", executionMode: "single" },
  currentEntity: { qualified: "wms.stock_movement", columns: entityColumns },
});
// → [{ rule: "dsl/unknown-column", severity: "error", message, start, end, line, column }]
```

一个规则知道什么 模块通过上下文到达—— 模块代码, 和列搜索(任何 `Set` 或者说 `Map` ——而不是 通过一个模块加载器,让同样的规则运行在编辑器和 在文件行走器. **每一个字段都是可选的,每个读出一个字的规则都会失败 打开**: 如果上下文为空, 仅文本规则仍然运行, 其余的站点 安静地下来。 假“ 未知列” 下划线 包; 漏出一个需要安装往返.

一项义务是 `currentEntity`数字 : `columns` 必须是 **特性扩展**, (中文(简体) ), 内置特性和模块本身 `traits.json` 一样,因为身份 PK 和 (中文) `[status]` 生活于特质而非 `fields`未扩展的集 把规则变成错误的墙壁。 当实体无法解决时—— 桥接模块在另一模块的实体上作用——通过 `null` 而不是现在 你确实有碎片.

问题既包含字节抵销,又包含1个索引 `line`编号 :`column`,所以一个 基于范围的主机和 a `file.dsl:12` 记者每人得到他们需要的.

块,块 `[field]` 看着后面,案件规则也跟着 `ActionDslCompiler` 5个区种,包括: `schema:`,以 第 0 栏为锚(缩进为正文,为 报告)和 `execute:` 运行到文件尾端.

它不从包根再出口:导入 `@dforge-core/metadata` 在浏览器捆绑中,不能在后方拉出指示器.

## JSON 计划

14克恩克的计程车是随同型号一起运送的,保持字节一致 改为 `docs/schemas/` (一) 实行平等测试; `prepack` 重同步前 (原始内容存档于2017-03-25). Publishing. 直接导入它们或者在文件上指定一个验证符 / 编辑器 .

```ts
import entitySchema from "@dforge-core/metadata/schemas/entity.schema.json" with { type: "json" };
```

```jsonc
// VS Code settings.json — validate module files against the shipped schemas
"json.schemas": [
  {
    "fileMatch": ["entities/*.json"],
    "url": "./node_modules/@dforge-core/metadata/schemas/entity.schema.json"
  }
]
```

可用 : `manifest`, (中文(简体) ), `entity`, (中文(简体) ), `data_views`, (中文(简体) ), `folders`, (中文(简体) ), `menus`, (中文(简体) ), `roles`, (中文(简体) ), `settings`, (中文(简体) ), `reports`, (中文(简体) ), `jobs`, (中文(简体) ), `triggers`, (中文(简体) ), `webhooks`, (中文(简体) ), `print_templates`, (中文(简体) ), `traits`, (中文(简体) ), `seed_data`, (中文(简体) ), `demo_vars`。 。 。 .

## 真理与平等来源

这个软件包从不编辑 Canonical 源头—— 它照亮它们并守护着 镜像 :

-   **书记官处** 镜像平台元数据种子; `test/registries.test.ts` 如果代码漂移到 `field_types.json` (和编译时间覆盖) 守护失败, 如果 `FieldTypeCd` 工会和工会 `fieldTypes` 数组差异).
-   **示马斯** 复制自 `docs/schemas/` 以 `pnpm sync-schemas`· ; `test/schemas.test.ts` 如果运出的副本漂移则失败 . `prepack` 复作是语.

当单独消费(软件包周围没有单列)时,对等检查是 跳出 —— 已发运的数据本身是权威的 .

## 脚本

```sh
pnpm build          # tsc → dist/
pnpm test           # vitest (registry + schema parity)
pnpm sync-schemas   # refresh schemas/ from docs/schemas/
```

## 许可证

麻省理工学院

## 常见问题

### @dforge-core/metadata 是什么？

Canonical dForge 作者登记册 - 字段类型,基础数据类型,列类型,特征,数据视图类型和图表类型 - 有衍生帮助\. 运行时无依赖性;由编辑器,网络应用和CLI共享的单一真理源\.

### 如何安装 @dforge-core/metadata？

在项目目录运行 npm install @dforge-core/metadata，或使用 pnpm add / yarn add / bun add。

### @dforge-core/metadata 支持 TypeScript 吗？

支持。包内自带 TypeScript 类型声明（package\.json 声明了 types 入口），安装后即可获得类型提示，无需再安装 @types 包。

### @dforge-core/metadata 支持 ESM 还是 CommonJS？

以 ES Module 形式发布，推荐使用 import 引入。在 CommonJS 项目中，Node\.js 20\.19\+ / 22\.12\+ 可以直接 require\(\) 不含顶层 await 的 ES Module，更早的版本需要改用动态 import\(\)。

### @dforge-core/metadata 可以商用吗？

@dforge-core/metadata 使用 MIT 许可。宽松许可：允许商业使用、修改和再分发，通常只需在分发时保留原版权与许可声明。以上为概括，不构成法律意见，请以许可原文为准。

### @dforge-core/metadata 的下载量有多少？

根据 npm 官方下载统计，@dforge-core/metadata 在 2026/10/12 – 2026/11/10 这 30 天内被下载 3,014 次，日均约 100 次。下载量会把 CI 构建、镜像同步和作为其他包依赖的安装一并计入，适合横向比较热度，不能直接等同于使用人数。

### @dforge-core/metadata 还在维护吗？

最新版本 0\.0\.53 发布于 2026/11/11（1 天前）；至今共发布 51 个版本，其中过去 12 个月发布了 51 个；首次发布于 2026/06/14。发布频率只是参考信号：功能稳定的工具可能很少需要更新，建议结合源码仓库的 issue 和提交记录判断。