# @codluv/versionguard 中文文档

规范地址：https://npmcn.com/package/%40codluv/versionguard/

版本：1\.2\.0
npm 元数据更新时间：2026-03-30T23:50:11.599Z
中文译文更新时间：2026-11-10T09:18:40.081Z
软件包许可：MIT

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

原始 npm 页面：https://www.npmjs.com/package/%40codluv/versionguard
原文对照：https://npmcn.com/package/%40codluv/versionguard/?lang=original
项目主页：https://github.com/kryptobaseddev/versionguard#readme
源码仓库：https://github.com/kryptobaseddev/versionguard

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

- 包体积（解压后）：867 kB，68 个文件
- 模块格式：ES Module
- TypeScript 类型：包内自带
- Node.js 要求：\>=22\.0\.0
- 运行依赖：8 个
- 首次发布：2026-03-22T05:57:47.429Z
- 最新版本发布：2026-03-30T23:50:11.281Z
- 近 30 天下载量：6164（2026-10-10 至 2026-11-08，npm 官方下载统计）
- 已发布版本数：13（近 12 个月 13 个）

## 中文简介

严格版本执行 SemVer 和 CalVer —— 语言不可知的显示支持, git hooks, changlog 验证, 文件同步

## 安装

```sh
npm install @codluv/versionguard
```

也可以使用：`pnpm add @codluv/versionguard`、`yarn add @codluv/versionguard`、`bun add @codluv/versionguard`

## README

# 版本守护

对任何项目的严格版本治理——SemVer和CalVer执行,语言-不可知的显示支持,git hooks,更动日志验证,文件同步,以及重播版扫描.

VersionGuard 保存您的列表,更改日志条目, git 标记, 并配置版本引用同步, 因此人类和 LLM 代理停止传输混乱的发布状态 .

## 为什么它存在

不同地点的版本中断 :

-   版本在文档、 CI 配置和 Docker 文件之间获得硬码
-   更改日志条目被遗忘或使用错误的段落名称
-   标记从软件包版本漂移
-   SemVer和CalVer的规则在压力下弯曲
-   代理人员使用快捷键, 将重播保留在无效的释放状态

版本Guard将那些变成可执行的检查,并有面向修复的反馈.

## 它会做什么

-   验证带有可配置规则的SemVer和CalVer格式
-   继续根据您的清单同步配置文件( package.json, Cargo.toml, pyproject.toml等)
-   扫描整个重播版本的文字( 默认启用)
-   对照您的软件包登记表( npm、 箱子. io、 PyPI等) 核实发布状态
-   保留带有区域执行的更改日志结构
-   安装合作基特钩 `pre-commit`, (中文(简体) ), `pre-push`,以及 `post-tag`
-   提供 CLI 命令进行校验、同步、出错和标记
-   需要钩子或工作树脏时拒绝不安全标记
-   用于人类和LLM代理的内置CKM帮助系统(`vg ckm`(中文(简体) )

## 它运行的地方

版本Guard在开发生命周期的三点执行:

1.  **本地 dev( 挂钩) :** `pre-commit` 财务报告和审定财务报表 `pre-push` 钩子运行 `vg validate` 自动。 此抓取版本漂移,更改日志问题,以及代码离开开发者的机器前同步不匹配. 这是主要执行点.
    
2.  **CI( GitHub 动作 ):** `vg validate` 在CI中作为一个建筑门运行。 这捕捉到钩子漏掉的任何东西( 钩可以跳过) `--no-verify`),在每个PR上验证,并确保Depabot PRs不会打破版本一致性.
    
3.  **CLI(开发工作流程):** `vg check`, (中文(简体) ), `vg fix`, (中文(简体) ), `vg sync`, (中文(简体) ), `vg tag`, (中文(简体) ), `vg doctor` ——开发者和代理在发行流程中使用的手动指令.
    

## 谁需要呢

-   **任何船舶版本软件的项目** 并想要停止版本相关的漂移 : 在 docs 中 stale 安装命令, 缺少更改日志条目, CI 配置或 Dockerfile 中硬码版本字符串, 标记/ 明显不匹配
-   **使用AI代理的团队** 修改代码的 VG 是代理机跳过版本步骤时抓取的护栏
-   **Polyglot项目** 在npm、rust、Python、Dart、PHP、Java和更多

## 安装

```bash
npm install -D @codluv/versionguard@latest
vg init
vg hooks install
```

> `vg` 是用于 `versionguard`两者工作相同.

这给你:

-   (单位:千美元) `.versionguard.yml` 配置文件
-   管理着的钩子
-   围绕您的列表构建的本地版本政策

## 快开始

运行基本版本检查 :

```bash
vg check
```

运行完整的仓库验证( 包括扫描、 守护和默认公布检查) :

```bash
vg validate
```

对于CI或代理工作流程:

```bash
vg validate --json
```

将配置的文件同步到显示的版本 :

```bash
vg sync
```

自动修复常见问题 :

```bash
vg fix
```

## 示例输出

有效版本 :

```text
Current version: 1.2.3
Versioning type: semver

✓ Version is valid
```

有可操作指导的无效版本 :

```text
Current version: v1.0.0
Versioning type: semver

✗ Version has issues:

  ✗ Version should not start with 'v': v1.0.0

How to fix:
  → Remove the 'v' prefix
    Run: npm version 1.0.0
```

## 配置

版本Guard使用单一的YAML配置文件. 两者 `semver:` 财务报告和审定财务报表 `calver:` 块总是存在的——变化 `type` 切换.

示例

```yaml
versioning:
  type: semver
  semver:
    allowVPrefix: false
    allowBuildMetadata: true
    requirePrerelease: false
  calver:
    format: "YYYY.MM.PATCH"
    preventFutureDates: true

sync:
  files:
    - "README.md"
    - "CHANGELOG.md"
  patterns:
    - regex: '(version\s*[=:]\s*["'])(.+?)(["'])'
      template: '$1{{version}}$3'
    - regex: '(##\s*\[)(.+?)(\])'
      template: '$1{{version}}$3'

changelog:
  enabled: true
  file: "CHANGELOG.md"
  strict: true
  requireEntry: true
  enforceStructure: false
  sections:
    - Added
    - Changed
    - Deprecated
    - Removed
    - Fixed
    - Security

# All checks below are enabled by default — opt OUT via config
guard:
  enabled: true          # hook bypass detection

publish:
  enabled: true          # registry publish status verification
  timeout: 5000          # ms, fail-open on timeout

scan:
  enabled: true          # repo-wide stale version detection
  allowlist: []

git:
  hooks:
    pre-commit: true
    pre-push: true
    post-tag: true
  enforceHooks: true

ignore:
  - "node_modules/**"
  - "dist/**"
  - ".git/**"
  - "*.lock"
```

## 支持的版本模式

### 交换器

版本Guard 支持严格的语义性版本验证,并通过 `semver:` 块 :

-   `MAJOR.MINOR.PATCH` 提前释放(`1.2.3-alpha.1`)和建立元数据(`1.2.3+build.5`(中文(简体) )
-   `allowVPrefix` ——宽容 `v1.2.3` 格式( 在解析前划出)
-   `allowBuildMetadata` - 允许或拒绝 `+build` 元数据后缀
-   `requirePrerelease` · 要求在每个版本上预发标签
-   `schemeRules.allowedModifiers` ——白名单预释标签(如:, `alpha`, (中文(简体) ), `beta`, (中文(简体) ), `rc`(中文(简体) )
-   优先比较和递增帮助

### 卡尔维尔

支持所有 calver.org 令牌的可编译以符号为基础的格式字符串 :

-   年份 : `YYYY`, (中文(简体) ), `YY`, (中文(简体) ), `0Y`
-   月数 : `MM`, (中文(简体) ), `M`, (中文(简体) ), `0M`
-   周数 : `WW`, (中文(简体) ), `0W`
-   天数 : `DD`, (中文(简体) ), `D`, (中文(简体) ), `0D`
-   计数器 : `MICRO`, (中文(简体) ), `PATCH`

CalVer验证可以拒绝未来日期的版本并强制修改允许列表.

### 语言不可知表

版本Guard从任何支持的列表中读取版本:

-   `package.json` (节点.js), `Cargo.toml` (鲁斯特), `pyproject.toml` (P
-   `pubspec.yaml` (达特/弗卢特), `composer.json` (菲律宾), `pom.xml` (贾瓦/马文)
-   `VERSION` (平面文本), Git 标记( Go/ Swift), 自定义正则图案

设定 `manifest.source: auto` 用于自动检测.

## 图标

| 命令 | 说明 |
| --- | --- |
| `vg init` | 创建 `.versionguard.yml` (交互向导或无头) |
| `vg check` | 以可操作反馈验证当前版本 |
| `vg validate` | 运行所有检查: 版本、 同步、 更改日志、 扫描、 守护、 发布 |
| `vg doctor` | 报告储存库准备就绪一次 |
| `vg fix` | 对常见漂移应用决定性修正 |
| `vg fix-changelog` | 修复更改ets- mangled changlogs以保留更改log格式 |
| `vg sync` | 更新已配置的文件以匹配显示版本 |
| `vg bump` | 推荐下一个版本并选择应用 |
| `vg tag [version]` | 安全创建附加说明的释放标签 |
| `vg hooks install` | 安装管理的 git 钩子 |
| `vg hooks uninstall` | 删除已管理的 git 钩 |
| `vg hooks status` | 检查是否安装了钩子 |
| `vg ckm [topic]` | 密码库知识宣言——自动生成的帮助 |
| `vg ckm [topic] --json` | LLM 代理机读 CKM |

## Git 钩子行为

版本Guard可以安装这些钩:

-   `pre-commit`
-   `pre-push`
-   `post-tag`

何时 `git.enforceHooks` 被启用,释放标记也期望有管理下的钩子.

## 医生指挥

使用 `doctor` 在发布前需要单行录准备报告时:

```bash
vg doctor
```

对于CI或代理工作流程:

```bash
vg doctor --json
```

它报告说:

-   当前软件包版本
-   版本有效性
-   同步状态
-   换行准备
-   钩子安装状态
-   工作树木清洁

## 验证 JSON 输出

使用 `validate --json` 当您需要机器可读验证输出时:

```bash
vg validate --json
```

JSON有效载荷包括:

-   `valid`
-   `version`
-   `versionValid`
-   `syncValid`
-   `changelogValid`
-   `scanValid`
-   `guardValid`
-   `publishValid`
-   `publishCheck`
-   `guardReport`
-   `errors`
-   `hook`
-   `postTag`

## 纠缠行为

`versionguard tag` 故意严格.

在下列情况下,法院可拒绝继续审理:

-   需要挂钩,但没有安装
-   工作树是肮脏的
-   请求的标签已经存在
-   软件包版本或更改日志状态无效
-   同步文件已过期

这使得释放标记不会成为绕行正常验证的绕道.

## 稳定政策

1.x保持所有CLI命令和配置格式的后向相容性. 断裂变化只发生于2.0+.

贬值的旗帜`--strict`, (中文(简体) ), `--scan`继续使用1.x并打印出警告。 他们的行为现在是默认的。 要选择退出特定检查, 请使用配置 :

```yaml
guard:
  enabled: false
scan:
  enabled: false
publish:
  enabled: false
```

## 典型工作流程

### 实施前验证

```bash
vg validate
```

### 修改手动版本后修复漂移

```bash
npm version patch
vg fix
```

### 建议并应用下一个版本

```bash
vg bump --apply
```

### 安全创建释放标签

```bash
vg tag 1.2.3 -m "Release 1.2.3"
```

## 使用更改器

版本担保和 [更改](https://github.com/changesets/changesets) 是处理释放生命周期不同部分的补充工具.

| 关切 | 更改 | 版本守护 |
| --- | --- | --- |
| 决定下一个版本 | 对 | 不( 验证, 不选择) |
| 更新表单版本 | 对 | 不(读作真理之源) |
| 验证版本格式 | 没有 | 有(SemVer/CalVer严格) |
| 文件之间的同步版本 | 没有 | 是( 基于 regex 的同步) |
| 验证更改日志结构 | 没有 | 是( 保留 Changelog + 节执行) |
| 扫描已过期版本的重播 | 没有 | 对 |
| 核实登记册上的公布状况 | 没有 | 是( 未打开) |
| Git 钩子执行 | 没有 | 对 |
| 发布到 npm | 对 | 没有 |

**更改器决定下一个版本 。 版本Guard验证结果正确.**

### 建议的工作流程

```bash
# 1. Add a changeset when making changes
npx changeset

# 2. When ready to release, version the packages
npx changeset version

# 3. VersionGuard validates the new state
vg validate

# 4. Publish
npx changeset publish
```

### CI 整合

在"GitHub Action"中,两个工具都按顺序运行. 更改器在等待更改器时创建"Version套件"PR. 版本Guard在发布前验证结果:

```yaml
- run: npm run build
- run: vg validate
- uses: changesets/action@v1
  with:
    publish: npx changeset publish --access public
```

版本Guard不替换更改器,也不与之相冲突. 使用变换器进行发布自动化. 使用版本Guard来发布正确性.

## 发展

本储存库使用现代无害环境管理工具链:

-   用于构建的虚拟
-   测试测试
-   用于格式化和基线衬线化的生物群落
-   语义类型语言的 ESLintScript linting

有用命令 :

```bash
npm run lint
npm test
npm run build
```

Forge 命令 :

```bash
npm run forge:check
npm run forge:test
npm run forge:build
npm run forge:doctor
```

初始化或刷新 Forge 脚手架 :

```bash
npm run forge:docs:init
```

运行单个测试文件 :

```bash
npx vitest run src/__tests__/semver.test.ts
```

按名称进行单一测试 :

```bash
npx vitest run src/__tests__/calver.test.ts -t "increments patch-based versions"
```

## 文档

-   产品视觉: `docs/VISION.md`
-   经核实的功能分类账和路线图: `docs/FEATURES.md`
-   CKM模块文档: `src/ckm/README-CKM.md`
-   捐助方代理指导: `AGENTS.md`

## 福尔吉

这回波是用 `@forge-ts/cli` 和项目配置 `forge-ts.config.ts`。 。 。 .

有用命令 :

```bash
npm run forge:check
npm run forge:test
npm run forge:build
npm run forge:doctor
```

目前情况:

-   安装并初始化
-   `forge-ts check` 目前报告大量TSDoc债务
-   生成的文献 文物被写入 `docs/`

建议的工作流程:

```bash
npm run forge:check
npm run forge:build
```

然后按照Forge报告的顺序解决TSDoc问题.

## 许可证

麻省理工学院

## 常见问题

### @codluv/versionguard 是什么？

严格版本执行 SemVer 和 CalVer —— 语言不可知的显示支持, git hooks, changlog 验证, 文件同步

### 如何安装 @codluv/versionguard？

在项目目录运行 npm install @codluv/versionguard，或使用 pnpm add / yarn add / bun add。它还提供命令行工具 versionguard、vg，可以用 npx versionguard 直接运行。

### @codluv/versionguard 支持 TypeScript 吗？

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

### @codluv/versionguard 支持 ESM 还是 CommonJS？

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

### @codluv/versionguard 需要什么版本的 Node\.js？

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

### @codluv/versionguard 可以商用吗？

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

### @codluv/versionguard 的下载量有多少？

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

### @codluv/versionguard 还在维护吗？

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