版本解析

源文件

对应的 Skill 定义位于 skills/version-parsing/SKILL.md。

前置： 一次性安装见 /installation，完成 SDK / CLI / MCP 配置。
三层入口： SDK (Go) → CLI (shell) → MCP (AI 工具)，按需选用。

When to Use

Parse a version string ("v1.2.3-rc1") into structured components (prefix, numbers, suffix)
Validate whether a string is a valid version number
Determine version type: prerelease, stable, alpha, beta, RC, dev, snapshot, nightly, etc.
Extract segments, sub-version, suffix weight, group ID, or core version
Use custom delimiters for non-standard formats (e.g. underscore-separated)

Decision Tree

Raw version string → what do you need?
├─ Structured breakdown?          → NewVersion() / version_parse / versions parse
├─ Yes/no validity?               → IsValid() / version_validate / versions validate
├─ All type flags at once?        → version_info / versions info
├─ Specific type check?           → IsBeta(), IsStable(), IsRC() etc.
├─ Segments (major/minor/patch)?  → Major()/Minor()/Patch()/Segments()
├─ Core version (no suffix)?      → Core()
└─ Suffix weight for ordering?    → SuffixWeight()

Task Patterns

Parse & inspect

Goal: Break "v1.2.3-rc1" into prefix "v", numbers [1,2,3], suffix "-rc1".

Layer	Approach
SDK	`v := versions.NewVersion("v1.2.3-rc1"); v.IsValid()`
CLI	`versions parse v1.2.3-rc1`
MCP	`{"tool": "version_parse", "arguments": {"version_string": "v1.2.3-rc1"}}`

Validate

Goal: Confirm "1.2.3" is valid, "not-a-version" is not.

Layer	Approach
SDK	`v.Validate() != nil` → invalid
CLI	`versions validate 1.2.3` (exit 0 = valid, exit 1 = invalid)
MCP	`{"tool": "version_validate", "arguments": {"version_string": "1.2.3"}}`

Check type

Goal: Determine if "1.0.0-beta2" is a beta prerelease.

Layer	Approach
SDK	`v.IsBeta()`, `v.IsPrerelease()`, `v.IsStable()`, `v.SubVersion()`
CLI	`versions check --beta 1.0.0-beta2` (exit 0 = match)
MCP	`{"tool": "version_info", ...}` returns all Is* flags

Extract segments

Goal: Get [1, 2, 3] from "1.2.3".

Layer	Approach
SDK	`v.Major()`, `v.Minor()`, `v.Patch()`, `v.Segments()`
CLI	`versions segments 1.2.3`
MCP	`{"tool": "version_parse", ...}` → `segments` field

Get core (strip suffix)

Goal: "v1.2.3-beta1" → "v1.2.3".

Layer	Approach
SDK	`v.Core().RawString()`
CLI	`versions core v1.2.3-beta1`
MCP	`{"tool": "version_core", "arguments": {"version_string": "v1.2.3-beta1"}}`

Custom delimiters

Goal: Parse "curl-7_85_0" with - and _ delimiters.

Layer	Approach
SDK	`versions.NewVersionWithOption(s, versions.ParserOption{Delimiters: ".-_"})`
CLI	`versions parse --delimiters "_-" curl-7_85_0`
MCP	`{"tool": "version_parse", "arguments": {"version_string": "curl-7_85_0", "delimiters": ".-_"}}`

API Reference

SDK — Constructor Functions

versions.NewVersion(versionStr string) *Version           // never nil, check IsValid()
versions.NewVersionE(versionStr string) (*Version, error)  // returns error for invalid
versions.MustParse(versionStr string) *Version             // panics on invalid — test data only
versions.NewVersions(strings ...string) []*Version         // batch parse
versions.NewVersionWithOption(s string, opt ParserOption) *Version  // custom delimiters
versions.NewVersionStringParser(s string) *VersionStringParser     // low-level parser

SDK — Version Struct Fields

type Version struct {
    Prefix         string    // e.g. "v"
    VersionNumbers []int     // e.g. [1, 2, 3]
    Suffix         string    // e.g. "-rc1"
    Metadata       string    // semver build metadata (after +)
    PublicTime     time.Time // optional release timestamp
    Raw            string    // original input string
}

SDK — Type Checks

v.IsValid() bool       // has VersionNumbers
v.IsStable() bool      // no suffix
v.IsPrerelease() bool  // has any suffix
v.IsAlpha() bool       // suffix contains "alpha"
v.IsBeta() bool        // suffix contains "beta"
v.IsRC() bool          // suffix contains "rc"
v.IsDev() bool         // suffix contains "dev"
v.IsSnapshot() bool    // suffix contains "snapshot"
v.IsNightly() bool     // suffix contains "nightly"
v.IsMilestone() bool   // suffix contains "milestone" or "m"
v.IsFinal() bool       // suffix contains "final"
v.IsGA() bool          // suffix contains "ga"
v.IsPre() bool         // suffix contains "-pre"
v.IsRelease() bool     // suffix contains "-release"
v.IsSP() bool          // suffix contains "sp"
v.IsPost() bool        // suffix contains "post"

SDK — Segment Accessors

v.Major() int           // VersionNumbers[0] or 0
v.Minor() int           // VersionNumbers[1] or 0
v.Patch() int           // VersionNumbers[2] or 0
v.Segments() []int      // all VersionNumbers
v.Segments64() []int64  // as int64
v.SubVersion() int      // numeric from suffix (e.g. "beta2" → 2)
v.SuffixWeight() SuffixWeight  // semantic ordering weight

SDK — Core, Clone, Serialization

v.Core() *Version                    // strip suffix
v.Clone() *Version                   // deep copy
v.BuildGroupID() string              // e.g. "1.2.3"
v.WithPrefix(p string) *Version      // immutable — returns new Version
v.WithSuffix(s string) *Version
v.WithMajor(n int) *Version
v.WithMinor(n int) *Version
v.WithPatch(n int) *Version
v.WithNumbers(ns []int) *Version
v.WithPublicTime(t time.Time) *Version
v.WithMetadata(m string) *Version
// JSON/Text/SQL serialization via MarshalText/UnmarshalText/MarshalJSON/UnmarshalJSON/Scan/Value

SDK — Parser Options

type ParserOption struct {
    Delimiters string  // custom delimiter set, e.g. ".-_" (default: ".-")
}

CLI Commands

bash

versions parse <version>              # structured JSON output
versions parse --delimiters "_-" <v>  # custom delimiters
versions validate <version>           # exit 0 = valid, 1 = invalid
versions info <version>               # all Is* flags + segments
versions segments <version>           # [major, minor, patch, ...]
versions sub-version <version>        # numeric suffix index
versions suffix-weight <version>      # semantic weight int
versions pure-prefix <version>        # prefix without trailing delimiters
versions group-id <version>           # e.g. "v1.2.3-beta" → "1.2.3"
versions core <version>               # strip suffix
versions clone <version>              # deep copy as JSON
versions check --<type> <version>     # --alpha, --beta, --rc, --stable, etc.
versions check --prerelease <v>       # exit 0 if prerelease
versions check --is-valid <v>         # exit 0 if valid

MCP Tools

Tool	Arguments	Returns
`version_parse`	`version_string`, `delimiters?`	prefix, numbers, suffix, metadata
`version_validate`	`version_string`	`{valid: bool, error: string?}`
`version_info`	`version_string`	all Is* flags, segments, suffix info
`version_core`	`version_string`	core version string

Cross-References

[[version-check]] — boolean type checks, comparison predicates
[[version-comparison]] — CompareTo, IsNewerThan, IsOlderThan
[[version-sorting]] — sorting parsed versions
[[version-constraints]] — constraint expression matching
[[version-mutation]] — bumping, building, modifying versions

Important Notes

NewVersion() never returns nil — always check IsValid() for invalid input
IsValid() checks for non-empty VersionNumbers; Validate() is stricter (rejects negative numbers)
IsPrerelease() means "has any suffix"; IsPre() means "has explicit -pre suffix"
IsStable() means "no suffix"; IsRelease() means "has explicit -release suffix"
Semver build metadata (+ part) is in Metadata field, not Suffix
All With* methods return new Version objects — the original is never modified
MustParse panics on invalid input — use only for hardcoded/test data

版本解析 ​

When to Use ​

Decision Tree ​

Task Patterns ​

Parse & inspect ​

Validate ​

Check type ​

Extract segments ​

Get core (strip suffix) ​

Custom delimiters ​

API Reference ​

SDK — Constructor Functions ​

SDK — Version Struct Fields ​

SDK — Type Checks ​

SDK — Segment Accessors ​

SDK — Core, Clone, Serialization ​

SDK — Parser Options ​

CLI Commands ​

MCP Tools ​

Cross-References ​

Important Notes ​