Invoice verification rule management and maintenance skill

管理校验规则、规则组和校验场景的全流程操作。支持通过统一 CLI 工具快速执行 API 调用，自动处理参数解析、配置加载和错误提示。使用当用户需要进行校验规则管理、规则组维护、校验场景配置、启停操作或相关查询时，即使用户只说"帮我创建一条规则"或"查一下场景列表"也应触发。

Security Scan

代码和文档总体匹配其“校验规则管理 CLI”用途, 但发布元数据未声明必需的环境变量且客户端会向由用户/配置指定的任意 baseUrl 发送 token，存在配置/凭据暴露和元数据不一致的风险。

Purpose & Capability

Skill 名称、描述、命令和代码（commands/*.js + lib/api-client.js）一致地实现了“校验规则 / 场景 / 规则组”的管理功能 — 所需网络访问（baseUrl + token）与用途一致。问题是 registry metadata 声明“Required env vars: none / Primary credential: none”，但 SKILL.md 和 lib/api-client.js 实际上依赖 VALIDATE_BASE_URL 和 VALIDATE_TOKEN（或 config.json 中的 baseUrl/token）。这种元数据与实际依赖不一致应被视为问题。

Instruction Scope

SKILL.md 指示运行 npm install 并通过 npx vr 执行命令，或通过环境变量 / config.json 提供 baseUrl 和 token。指令范围限于 CLI 功能，没有要求读取用户主目录以外的敏感系统配置。但 lib/api-client.js 会按层级从当前工作目录和脚本目录向上查找 config.json（process.cwd() 的父目录等），这可能意外读取到在运行目录树上存在的其它 config.json（潜在凭据来源）。指令不会将数据发送到第三方域，最终接收方由 baseUrl 决定。

Install Mechanism

没有远程下载、不含可疑 URL 或可执行的 extract 操作。代码是 Node.js CLI，package.json 提供本地 bin。SKILL.md 建议在 skill 目录执行 npm install，这只是常规安装步骤，风险较低。

Credentials

实际运行需要 VALIDATE_BASE_URL 和 VALIDATE_TOKEN（或 config.json 中的 baseUrl/token），这些是与功能直接相关的最小凭据集，但 registry 元数据未声明这些需要（声明为 none），造成透明度不足。token 将被放入 HTTP header 'X-Access-Token' 并随请求发往 baseUrl，用户应确认 baseUrl 是可信的内部服务。

Persistence & Privilege

无 always:true，默认允许用户/代理调用（user-invocable / autonomous invocation 默认）。Skill 不修改其它 skill 或系统级配置。唯一需要注意的是它会在运行时从文件系统查找 config.json（向上遍历目录），这给凭据发现带来一定风险，但不等同于持久化特权。

What to consider before installing

该 skill 的代码实现与其描述一致：它是一个用于管理校验规则/规则组/场景的本地 Node.js CLI，需提供 VALIDATE_BASE_URL 和 VALIDATE_TOKEN（或在 config.json 中设置 baseUrl/token）。注意事项： - 元数据不声明所需环境变量（registry 显示 none），但运行时确实需要 VALIDATE_BASE_URL 和 VALIDATE_TOKEN；在安装或运行前要求作者/发布方修正元数据或在受控环境中运行。 - 在运行前，确认 VALIDATE_BASE_URL 指向可信的内部服务（否则 token 会被发送到任意域）。不要把生产 token 传给不明域名。优先在受限网络或测试环境验证行为。 - api-client 会从当前工作目录及上级目录查找 config.json，可能会意外读取到路径树上的其他配置文件；在运行时检查你的当前目录避免无意暴露凭据。 - 如果你缺乏信任或无法验证发布者：在隔离环境（容器或受控 VM）中先运行 npm install 并本地测试，或审阅代码（特别是 loadConfig 和 apiRequest）并确认 baseUrl/token 的处理逻辑满足你的安全要求。 总结：功能本身合理且与用途一致，但发布元数据的遗漏和 config.json 向上查找行为带来透明度与凭据暴露风险，建议在修正元数据并在受控环境中验证之前谨慎使用。

校验规则管理

核心概念

校验场景 (ValidateScene)
  └─ 1:N 校验规则组 (ValidateRuleGroup)
           └─ 1:N 校验规则 (ValidateRule)

状态：draft（草稿）/ enabled（启用）/ disabled（禁用）

---

初始化（首次使用必做）

在使用任何命令前，先检查 CLI 是否就绪：

npx vr help 2>/dev/null || (cd <skill目录> && npm install)

如果 npx vr help 无输出或报错，说明还未初始化，执行：

cd /path/to/validation-rule-management
npm install

完成后即可在任意目录通过 npx --prefix /path/to/validation-rule-management vr <action> 调用，或直接在 skill 目录下用 npx vr <action>。

---

配置

方式 1 — 环境变量（推荐，适合脚本/CI）

export VALIDATE_BASE_URL=http://global-masterdata-http.default.yf-bw-test-2.test.51baiwang.com
export VALIDATE_TOKEN=your-token-here

方式 2 — config.json（放在项目根目录或 skill 目录）

{
  "baseUrl": "http://global-masterdata-http.default.yf-bw-test-2.test.51baiwang.com",
  "token": "your-token-here"
}

---

命令速查

所有命令统一格式：npx vr <action> [--key value ...] 值含空格时 shell 自动处理，含 = 等特殊字符时用 --json '{...}'

规则组

npx vr create-rule-group  --groupName "基础信息校验组" --orderNum 1 [--description "描述"]
npx vr query-rule-groups  [--groupName "关键字"] [--pageNum 1] [--pageSize 10]
npx vr update-rule-group  --id 1 --groupName "新名称" --orderNum 2
npx vr delete-rule-group  --id 1

规则

npx vr create-rule  --groupId 1 --objectId Invoice --countryCode CN \
                    --ruleCode CN-SELLER-001 --ruleName "卖方名称必填" \
                    --ruleType required [--fieldKey sellerName] [--errorMessage "{field}不能为空"]

npx vr query-rules  [--groupId 1] [--status enabled] [--countryCode CN] [--pageSize 20]
npx vr enable-rule  --id 42 --status enabled|disabled
npx vr delete-rule  --id 42

场景

npx vr create-scene  --sceneCode CN_VAT_SPECIAL --sceneName "中国增值税专票场景" \
                     [--errorStrategy stop_on_error|continue_all]

npx vr query-scenes  [--sceneCode CN_VAT] [--status enabled] [--pageSize 10]
npx vr enable-scene  --id 10 --status enabled|disabled
npx vr delete-scene  --id 10

---

目录结构

validation-rule-management/
├── SKILL.md
├── package.json              # 定义 bin: { "vr": "./cli.js" }
├── cli.js                    # 入口：解析 action → 路由到对应命令模块
├── commands/                 # 按业务域划分的命令模块
│   ├── scenes.js             #   场景操作
│   ├── rule-groups.js        #   规则组操作
│   └── rules.js              #   规则操作
├── lib/                      # 基础设施
│   ├── api-client.js         #   HTTP 客户端 + 配置加载
│   ├── arg-parser.js         #   命令行参数解析
│   └── utils.js              #   公共工具函数
└── references/               # 参考文档（按需读取）
    ├── data-model.md         #   完整 DTO 定义 + API 端点汇总
    └── examples.md           #   典型使用示例

查阅字段定义或 API 路径时，读取 references/data-model.md。

---

常见问题

错误信息	原因	解决
npx vr 无响应	未执行 npm install	在 skill 目录执行 npm install
未找到配置	没有环境变量或 config.json	设置环境变量或创建配置文件
缺少必填参数	参数不完整	运行 npx vr help 查看必填项
业务错误	token 失效或权限不足	刷新 token，确认 appId 正确