# @cxtms/cx-schema 中文文档 规范地址：https://npmcn.com/package/%40cxtms/cx-schema/ 版本：1\.9\.285 npm 元数据更新时间：2026-10-27T10:36:20.122Z 中文译文更新时间：2026-11-11T05:58:08.807Z 软件包许可：MIT 本文由上游 README 翻译，可能存在偏差，请结合原文核对 API、命令与配置。版权与许可归原作者所有。 原始 npm 页面：https://www.npmjs.com/package/%40cxtms/cx-schema 原文对照：https://npmcn.com/package/%40cxtms/cx-schema/?lang=original 项目主页：https://github.com/cargoxplorer/cx-schema#readme 源码仓库：https://github.com/cargoxplorer/cx-schema ## 关键信息（来自 npm 元数据） - 包体积（解压后）：1.9 MB，262 个文件 - 模块格式：CommonJS - TypeScript 类型：包内自带 - Node.js 要求：\>=14\.0\.0 - 运行依赖：5 个 - 首次发布：2025-12-13T03:05:37.297Z - 最新版本发布：2026-10-27T10:36:19.220Z - 近 30 天下载量：3613（2026-10-11 至 2026-11-09，npm 官方下载统计） - 已发布版本数：140（近 12 个月 140 个） ## 中文简介 CXTMS YAML 模块的Schema 验证软件包 ## 安装 ```sh npm install @cxtms/cx-schema ``` 也可以使用：`pnpm add @cxtms/cx-schema`、`yarn add @cxtms/cx-schema`、`bun add @cxtms/cx-schema` ## README # @cxtms/cx-schema (英语) [![npm version](https://img.shields.io/npm/v/@cxtms/cx-schema.svg)](https://www.npmjs.com/package/@cxtms/cx-schema) [![npm downloads](https://img.shields.io/npm/dm/@cxtms/cx-schema.svg)](https://www.npmjs.com/package/@cxtms/cx-schema) [![Build Status](https://github.com/cargoxplorer/cx-schema/workflows/Publish%20to%20npm/badge.svg)](https://github.com/cargoxplorer/cx-schema/actions) [![License: MIT](https://img.shields.io/badge/License-MIT-blue.svg)](https://opensource.org/licenses/MIT) CXTMS YAML 模块和工作流程的Schema验证软件包. 这个软件包为CXTMS中使用的基于YAML的配置提供了全面的验证. ## 特征 - **模块和工作流程验证**: 验证用户界面模块和工作流程定义 - **CLI 工具**: 有多个命令的全功能命令行接口 - **项目脚手架**数字 : `init` 命令以拖曳新工程 - **模板生成**数字 : `create` 命令从模板生成模块和工作流程 - **报表生成**: 生成 HTML 、 Markdown 或 JSON 格式的验证报告 - **自动检测**: 自动检测文件类型(模块 vs 工作流程) - **类型脚本支持**: 包含全部类型脚本类型和声明 - **VS 代码整合**: VS 代码中YAML schema 验证的可选设置 - **详细错误报告**: 用路径和建议清除错误消息 ## 安装 ```bash npm install @cxtms/cx-schema ``` ## 快速启动 ```bash # Initialize a new project npx cxtms init # Create a new module npx cxtms create module orders # Create a new workflow npx cxtms create workflow invoice-processor # Validate files npx cxtms modules/*.yaml workflows/*.yaml # Generate validation report npx cxtms report modules/*.yaml --report report.html ``` ## CLI 命令 ### 验证( 默认) 对照 JSON Schema 定义验证 YAML 文件 . ```bash cxtms [files...] cxtms validate [files...] # Examples cxtms modules/orders-module.yaml cxtms modules/*.yaml workflows/*.yaml cxtms --verbose modules/orders-module.yaml cxtms --format json modules/orders-module.yaml ``` ### 输入 初始化带有配置文件的新 CX 项目 . ```bash cxtms init ``` 创建 : - `app.yaml` - 项目配置 - `README.md` 项目文件 - `AGENTS.md` - 关于鉴定的AI助理指示 - `modules/` - 模块文件目录 - `workflows/` - 工作流程文件目录 ### 创建 从模板创建新模块或工作流程 . ```bash cxtms create # Examples cxtms create module orders cxtms create workflow invoice-generator ``` 生成的文件包括: - 独特的UUID标识符 - `fileName` gitHub repo 跟踪的属性 - 具有共同模式的样本结构 ### 报告 生成多个文件的验证报告 . ```bash cxtms report [files...] --report # Examples cxtms report modules/*.yaml --report report.html cxtms report workflows/*.yaml --report report.md cxtms report modules/*.yaml workflows/*.yaml --report results.json ``` 报告格式(自动从扩展名中查找): - **HTML 语言** - 有摘要卡和详细错误的样式报告 - **标记** - 方便文件的表格和清单 - **贾森** - CI/CD输油管机读取 ### 计划 为组件或任务显示 JSON Schema 定义. ```bash cxtms schema # Examples cxtms schema form cxtms schema dataGrid cxtms schema workflow cxtms schema foreach ``` ### 实例 显示组件或任务的示例 YAML . ```bash cxtms example # Examples cxtms example form cxtms example workflow ``` ### 列表 列出所有可用的验证计划 . ```bash cxtms list cxtms list --type module cxtms list --type workflow ``` ## CLI 选项 | 选项 | 短数 | 说明 | | --- | --- | --- | | `--help` | `-h` | 显示帮助消息 | | `--version` | `-v` | 显示版本编号 | | `--type ` | `-t` | 验证类型 : `module`, (中文(简体) ), `workflow`,或 `auto` (默认 : `auto`(中文(简体) ) | | `--format ` | `-f` | 输出格式 : `pretty`, (中文(简体) ), `json`,或 `compact` (默认 : `pretty`(中文(简体) ) | | `--schemas ` | `-s` | 自定义计划目录路径 | | `--verbose` | | 以方案路径显示详细输出 | | `--quiet` | `-q` | 只显示出错, 压制其他输出 | | `--report ` | `-r` | 生成报告到文件( html、 md、 或 json) | | `--report-format ` | | 报告格式 : `html`, (中文(简体) ), `markdown`,或 `json` | ## 输出格式 ### 漂亮( 默认) 人可读出有彩色格式和详细出错信息. ``` ╔═══════════════════════════════════════════════════════════════════╗ ║ CX SCHEMA VALIDATION REPORT ║ ╚═══════════════════════════════════════════════════════════════════╝ File: modules/my-module.yaml Type: module Status: ✓ PASSED Errors: 0 Warnings:0 ``` ### 压缩 批量处理最小输出. ``` PASS modules/orders-module.yaml PASS modules/contacts-module.yaml FAIL modules/broken-module.yaml (3 errors) ``` ### 贾森 JSON方案处理产出. ```json { "isValid": true, "errors": [], "warnings": [], "summary": { "file": "modules/my-module.yaml", "status": "PASSED", "errorCount": 0 } } ``` ## 程序化 API ```typescript import { ModuleValidator, WorkflowValidator } from '@cxtms/cx-schema'; // Validate a module const moduleValidator = new ModuleValidator({ schemasPath: './.cx-schema' }); const moduleResult = await moduleValidator.validateModule('modules/orders.yaml'); // Validate a workflow const workflowValidator = new WorkflowValidator({ schemasPath: './.cx-schema/workflows' }); const workflowResult = await workflowValidator.validateWorkflow('workflows/process.yaml'); if (moduleResult.isValid) { console.log('✓ Module is valid'); } else { moduleResult.errors.forEach(error => { console.error(`${error.type}: ${error.message} at ${error.path}`); }); } ``` ## 模板 模板存储于 `templates/` 目录和使用占位符语法 : | 占位符 | 说明 | | --- | --- | | `{{name}}` | 化名( 小写、 破折号) | | `{{displayName}}` | 标题大小写显示名 | | `{{uuid}}` | 生成的 UUID | | `{{fileName}}` | 文件的相对路径 | ### 模块模板 生成模块包括: - 模块元数据 `appModuleId` 财务报告和审定财务报表 `fileName` - 样本实体和权限 - 列表和详细视图的路径 - 带有数据Grid和窗体的布局组件 ### 工作流程模板 生成的工作流程包括: - 工作流程元数据 `workflowId` 财务报告和审定财务报表 `fileName` - 投入、产出和变量样本 - 有共同任务实例的活动(Log、Query/GraphQL、开关) - 手动触发 ## 可用的外观 ### 模块图 **组件 :** 布局、窗体、数据Grid、标签、标签、字段、按钮、收集、下放、数据源、日历、卡片、导航栏、时间表 **字段 :** 文本、文本区域、数字、选择、选择、同步、日期、日期、时间、复选框、收音机、附件、自动完整浏览器 **行动:** 导航、导航Back、突变、查询、通知、对话框、工作流程、设置域、设置Store、验证Form ### 工作流程图 **核心 :** 工作流程、活动、输入、产出、可变、触发、时间表 **控制流量 :** foreach, 切换, 同时, 验证 **公用事业:** 映射、 设置变量、 httprequest、 日志、 错误、 csv、 导出、 模板 **实体:** 订单、联系人、商品、工作、附件、收费、付款 **通讯:** 电子邮件发送、文档发送、文档发送 **查询 :** 图ql (查询/ GraphQL, 查询/ GraphQL@ 1) ## 退出代码 | 代码 | 说明 | | --- | --- | | `0` | 通过验证( 无出错) | | `1` | 验证失败( 发现错误) | | `2` | CLI 错误( 无效参数, 文件未找到等) | ## CI/CD 一体化 ### GitHub 动作 ```yaml - name: Validate YAML files run: | npx cxtms --format compact modules/*.yaml workflows/*.yaml - name: Generate validation report run: | npx cxtms report modules/*.yaml workflows/*.yaml --report validation-report.html - name: Upload report uses: actions/upload-artifact@v3 with: name: validation-report path: validation-report.html ``` ### GitLab CI 语录 ```yaml validate: script: - npx cxtms --format json modules/*.yaml > validation-results.json artifacts: paths: - validation-results.json ``` ### 承诺前虎克 ```bash #!/bin/bash # .git/hooks/pre-commit staged_files=$(git diff --cached --name-only --diff-filter=ACM | grep -E '\.(yaml|yml)$') if [ -n "$staged_files" ]; then npx cxtms --format compact $staged_files if [ $? -ne 0 ]; then echo "Validation failed. Please fix errors before committing." exit 1 fi fi ``` ## VS 代码整合 要启用 VS 代码中的 YAML 计划验证和自动完成 : ```bash node node_modules/@cxtms/cx-schema/scripts/setup-vscode.js ``` 此创建/ 更新 `.vscode/settings.json` 有计划协会. ## 环境变量 | 变量 | 说明 | | --- | --- | | `CX_SCHEMA_PATH` | 计划目录的默认路径 | | `NO_COLOR` | 禁用彩色输出 | ## 发展 ### 来源建筑 ```bash git clone cd cx-schema npm install npm run build ``` ### 本地测试 ```bash npm pack # In another project: npm install /path/to/cxtms-cx-schema-1.0.0.tgz ``` ## 许可证 麻省理工学院 ## 支助 关于问题,请访问 [GitHub 仓库](https://github.com/cargoxplorer/cx-schema/issues)。 。 。 . ## 常见问题 ### @cxtms/cx-schema 是什么？ CXTMS YAML 模块的Schema 验证软件包 ### 如何安装 @cxtms/cx-schema？ 在项目目录运行 npm install @cxtms/cx-schema，或使用 pnpm add / yarn add / bun add。它还提供命令行工具 cxtms、cx-cli，可以用 npx cxtms 直接运行。 ### @cxtms/cx-schema 支持 TypeScript 吗？ 支持。包内自带 TypeScript 类型声明（package\.json 声明了 types 入口），安装后即可获得类型提示，无需再安装 @types 包。 ### @cxtms/cx-schema 支持 ESM 还是 CommonJS？ 以 CommonJS 形式发布，可以直接 require\(\)；在 ES Module 项目中也可以用 import 引入（Node\.js 会把 module\.exports 作为默认导出）。 ### @cxtms/cx-schema 需要什么版本的 Node\.js？ package\.json 的 engines 字段要求 Node\.js \>=14\.0\.0。版本不符时 npm 默认只给出警告，开启 engine-strict 后会拒绝安装。 ### @cxtms/cx-schema 可以商用吗？ @cxtms/cx-schema 使用 MIT 许可。宽松许可：允许商业使用、修改和再分发，通常只需在分发时保留原版权与许可声明。以上为概括，不构成法律意见，请以许可原文为准。 ### @cxtms/cx-schema 的下载量有多少？ 根据 npm 官方下载统计，@cxtms/cx-schema 在 2026/10/11 – 2026/11/09 这 30 天内被下载 3,613 次，日均约 120 次。下载量会把 CI 构建、镜像同步和作为其他包依赖的安装一并计入，适合横向比较热度，不能直接等同于使用人数。 ### @cxtms/cx-schema 还在维护吗？ 最新版本 1\.9\.285 发布于 2026/10/27（14 天前）；至今共发布 140 个版本，其中过去 12 个月发布了 140 个；首次发布于 2025/12/13。发布频率只是参考信号：功能稳定的工具可能很少需要更新，建议结合源码仓库的 issue 和提交记录判断。