# @devfellowship/ux-paths-spec 中文文档

规范地址：https://npmcn.com/package/%40devfellowship/ux-paths-spec/

版本：1\.3\.1
npm 元数据更新时间：2026-08-13T16:03:00.592Z
中文译文更新时间：2026-11-12T03:02:35.726Z
软件包许可：MIT

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

原始 npm 页面：https://www.npmjs.com/package/%40devfellowship/ux-paths-spec
原文对照：https://npmcn.com/package/%40devfellowship/ux-paths-spec/?lang=original
项目主页：https://github.com/devfellowship/dfl-ux-paths#readme
源码仓库：https://github.com/devfellowship/dfl-ux-paths

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

- 包体积（解压后）：119 kB，17 个文件
- 模块格式：ES Module
- TypeScript 类型：包内自带
- Node.js 要求：\>=20
- 运行依赖：0 个
- 首次发布：2026-08-13T11:58:28.215Z
- 最新版本发布：2026-08-13T16:03:00.380Z
- 近 30 天下载量：8443（2026-10-12 至 2026-11-10，npm 官方下载统计）
- 已发布版本数：2（近 12 个月 2 个）

## 中文简介

DFL UX Paths数据合同:由它产生的v1 JSON Schema,TypeScript类型,以及零运行时间依赖和零网络一/O的验证().

## 安装

```sh
npm install @devfellowship/ux-paths-spec
```

也可以使用：`pnpm add @devfellowship/ux-paths-spec`、`yarn add @devfellowship/ux-paths-spec`、`bun add @devfellowship/ux-paths-spec`

## README

# `@devfellowship/ux-paths-spec`

DFL UX 路径 **数据合同**, 单独: v1 JSON Schema, TypeScript 生成类型,a `validate()` 与 **零运行时间依赖关系** 财务报告和审定财务报表 **零网络 I/ 欧**。 。 。 .

```bash
pnpm add @devfellowship/ux-paths-spec
```

```ts
import { validate, assertValid, SCHEMA_V1 } from "@devfellowship/ux-paths-spec";
import type { UxPathsDoc } from "@devfellowship/ux-paths-spec";

const result = validate(JSON.parse(text));
if (!result.valid) {
  for (const error of result.errors) console.error(error.formatted);
  //  screens[0].id: must be string (expected type: string)
  process.exit(1);
}
result.doc.screens; // typed as UxPathsDoc

// Or the throwing form, which narrows in place.
assertValid(doc, "itera-player.flows.json");
```

## 为什么这是单独的包

它的消费者是一个 **CI 验证器**页:1 **抓取任务** 还有一个 **AI 探险家**。 。 。 . 他们中没有人需要反应来发现 `flows.json` 身材不错, 其中一个在浏览器中运行。 计划是数据合同,所以它作为 数据——没有折叠到组件库中.

也结束了a **以承诺的方式保存销售副本**。 。 。 . `dfl-components-cli` 携带自己的副本 `v1.schema.json` 附有评论 要求人类"在同一回合里模仿它". 一个承诺悄悄地失败了: 复制件会变质,验证器会继续退出 0, 和文档没有人应该有 接受航行通过。 这里,每一个文物 重复的策略是 **生成** 从它,CI失败 如果其中任何一个停止匹配.

## 出口的东西

| 导出 | 这是什么 |
| --- | --- |
| `validate(doc, options?)` | `{ valid: true, doc }` 或者说 `{ valid: false, errors }`没有I/O,同步. |
| `assertValid(doc, location?, options?)` | 掷出 `SpecValidationError`; 窄处 `doc` 改为 `UxPathsDoc` 在成功方面. |
| `formatErrors(errors)` | 每犯一通人可读行. |
| `SCHEMA_V1` | 计划本身,作为一个物体. |
| `SCHEMA_ID` | 计划 `$id`。 。 。 . **一个名字,不是地址** - 见下文. |
| `SUPPORTED_SCHEMA_VERSIONS` | `["1.0.0", "1.1.0", "1.2.0", "1.3.0"]`。 。 。 . |
| `UxPathsDoc`, (中文(简体) ), `Screen`, (中文(简体) ), `Flow`, (中文(简体) ), `Screenshot`, (中文(简体) ), `SourceRef`,, , , , , , , , | 由计划生成的类型 . |
| `stepScreenId`, (中文(简体) ), `flowScreenIds`, (中文(简体) ), `danglingScreenIds` | JSON Schema规则的帮手不能表达. |
| `assertSchemaSupported`, (中文(简体) ), `isDateTime`, (中文(简体) ), `isUri` | 内部,输出用于测试. |

原生的图案还装入了焦油丸,供非TypeScript的消费者使用:

```ts
import schema from "@devfellowship/ux-paths-spec/schema/v1.json" with { type: "json" };
```

## 这个 `$id` 是一个名字,而不是地址

`SCHEMA_ID` 实值 `https://raw.githubusercontent.com/devfellowship/dfl-ux-paths/main/schema/v1.json`。 。 。 .

`dfl-ux-paths` 是一个 **私营** repo, 这样 URL **404s (中文(简体) )** 给外面的任何人 org - GitHub 报告一条私有路径为 _未找到_永远 _禁用内容_,所以请 失败把自己伪装成一个断开的链接. 这个 `$id` **识别** 计划。 这个 从未被获取。 这个软件包在很大程度上是存在的,因此不需要尝试.

## 零运行时间依赖是一个测试属性

`dependencies` 未参加 `package.json`,以及 `src/__tests__/package-contract.test.ts` 如果出现, 如果运出源导入任何非相对的, 则无法构建 , 或者如果它提到 `fetch` 编号 : `node:fs` / 其他主机 API.

`tsconfig.build.json` 滴数 `@types/node` 从已发运的编译中, 所以 `node:` 导入为 a **编译出错** 而不是有人记得的公约.

### 没有Ajv它怎么验证?

这个 **解释** 运行时的计策. `validate()` 读取 `SCHEMA_V1` 继续走 反之,这个计划是输入的,从不转录成 类型脚本 。 向上添加一个字段, 此校验符执行此字段时没有编辑 . 手写验证器会重新创建这个软件包的准确漂移 结束.

两名警卫守口如瓶

-   **Ajv对等.** Ajv是参考执行,并保持依赖性. `src/__tests__/ajv-parity.test.ts` 运行两个引擎 覆盖每一个承诺流量 文档加 ~ 30 单规则变异,并在任何分歧上失败.
-   **未知关键字为硬站.** 解释者执行固定关键字 设置。 如果未来的计划使用了它不知道的, `assertSchemaSupported()` **掷出** 命名关键词,而不是跳过它,悄悄接受 它应当拒绝的文件。 需要一个v1.4 `maxLength` 响亮的在这里失败,在 绕来绕去.

## 版本

`major.minor` 跟踪最高 `schema_version` 包裹承认.. `1.3.x` (原始内容存档于2018-03-25). ships schema v1.3. {\\fn黑体\\fs22\\bord1\\shad0\\3aHBE\\4aH00\\fscx67\\fscy66\\2cHFFFFFF\\3cH808080}一个图案V1.4就成功了 `1.4.0`。一个固定在 `validate()` 是一个 补丁起伏. 测试表明该版本和计划一致.

## 改变计划

`schema/v1.json` 地点 **重传根** 是真理的唯一来源。 编辑它,然后:

```bash
pnpm --filter @devfellowship/ux-paths-spec run generate
```

那个重写 `spec/schema/v1.json` (字节本), `spec/src/schema.generated.ts` 财务报告和审定财务报表 `spec/src/types.generated.ts`。不要用手来编辑这三个。 CI 运行 `generate --check` 并且失败, 如果您忘记了, 则命名陈旧的文件 .

## 还没有在计划之中(一次v1.4对话)

浏览器应用读取了三字段的图案 **从未定义**数字 : `requirements[]`, (中文(简体) ), `screen.fidelity` 财务报告和审定财务报表 `screen.archetype` (单位:千美元) `screen.page_class`) (中文(简体) ). 计划 `additionalProperties: false` 上层和上层 `$defs/screen`, (中文(简体) ), 因此,一个文件 携带其中任何一个是 **拒绝** - 这是一个真正的差距,不是 允许额外。 3个承诺的查看器固定装置无法验证 理由,还有 `ajv-parity.test.ts` 用两台引擎把事实钉住,这样就留下 在 v1.4 关闭前可见.

## 许可证

麻省理工学院.

## 常见问题

### @devfellowship/ux-paths-spec 是什么？

DFL UX Paths数据合同:由它产生的v1 JSON Schema,TypeScript类型,以及零运行时间依赖和零网络一/O的验证\(\)\.

### 如何安装 @devfellowship/ux-paths-spec？

在项目目录运行 npm install @devfellowship/ux-paths-spec，或使用 pnpm add / yarn add / bun add。

### @devfellowship/ux-paths-spec 支持 TypeScript 吗？

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

### @devfellowship/ux-paths-spec 支持 ESM 还是 CommonJS？

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

### @devfellowship/ux-paths-spec 需要什么版本的 Node\.js？

package\.json 的 engines 字段要求 Node\.js \>=20。版本不符时 npm 默认只给出警告，开启 engine-strict 后会拒绝安装。

### @devfellowship/ux-paths-spec 可以商用吗？

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

### @devfellowship/ux-paths-spec 的下载量有多少？

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

### @devfellowship/ux-paths-spec 还在维护吗？

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