16.5 Skills版本管理

为什么需要版本管理#

Skills 的版本管理帮助我们：

• 跟踪变化：记录 Skills 的功能更新和 bug 修复
• 确保兼容性：知道哪些版本可以安全升级
• 管理依赖：避免不同版本之间的冲突
• 团队协作：多人开发时协调代码变更

版本号的基本概念#

语义化版本格式#

Skills 使用 主版本.次版本.修订版本 的格式，例如：1.2.3

• 主版本（1）：重大变更，可能不兼容旧版本
• 次版本（2）：新增功能，但保持向后兼容
• 修订版本（3）：修复 bug，不影响功能

版本示例#

bash
复制
1.0.0 - 初始版本
1.0.1 - 修复了一个 bug
1.1.0 - 添加了新功能
2.0.0 - 重大重构，不兼容旧版本

在 Skills 中声明版本#

yaml
复制
---
name: my-skill
description: Brief description of the skill
metadata:
  version: "1.2.0"
  author: your-name
---

使用 Git 管理版本#

基本的 Git 工作流#

1. 创建版本标签

bash
复制
# 创建新版本的标签git tag v1.0.0

# 查看所有版本git tag --list

# 查看版本历史git log --oneline --decorate

2. 分支管理

bash
复制
# 创建开发分支git checkout -b feature/new-function

# 开发完成后合并到主分支git checkout main
git merge feature/new-function

# 删除临时分支git branch -d feature/new-function

3. 版本发布

bash
复制
# 准备发布git checkout main
git pull

# 创建发布标签git tag -a v1.1.0 -m "Release version 1.1.0"
# 推送到远程仓库git push origin main --tags

维护变更日志#

CHANGELOG.md 文件#

记录版本之间的变更：

markdown
复制
# Changelog

## [1.1.0] - 2024-01-15
### Added
- 新增 PDF 表单处理功能

### Fixed
- 修复中文字符编码问题

## [1.0.0] - 2024-01-01
### Added
- 基本的 PDF 文本提取功能
- 支持多种 PDF 格式

版本发布流程#

发布前的准备#

1. 更新版本号：

   yaml
   复制
   metadata:
     version: "1.1.0"

2. 更新变更日志：

   • 记录所有新增功能
   • 列出修复的 bug
   • 说明不兼容的变更

3. 测试验证：

   • 确保新版本正常工作
   • 检查向后兼容性

发布步骤#

1. 提交代码变更
2. 创建版本标签
3. 推送到代码仓库
4. 更新文档

处理版本冲突#

向后兼容性#

• 小版本更新（1.0.x → 1.1.0）：新增功能，不会破坏现有使用
• 大版本更新（1.x.x → 2.0.0）：可能包含不兼容的变更

迁移指南#

当发布不兼容的变更时，提供迁移说明：

markdown
复制
## 迁移到 v2.0.0

### 破坏性变更
- `old_function()` 已移除，请使用 `new_function()`

### 迁移步骤
1. 更新函数调用
2. 修改配置参数
3. 测试功能是否正常

版本管理最佳实践#

为用户考虑#

• 保持向后兼容：尽量避免破坏性变更
• 提供迁移路径：大版本更新时给出详细的升级指南
• 及时发布补丁：快速修复发现的 bug

为开发者考虑#

• 使用语义化版本：让版本号含义清晰
• 维护变更日志：记录每次更新的内容
• 标签化发布：用 Git 标签标记重要版本

版本管理检查清单#

发布前检查

• 版本号是否正确递增
• 变更日志是否更新
• 所有测试是否通过
• 文档是否同步更新

发布后跟进

• 用户反馈是否收集
• 兼容性问题是否解决
• 后续版本规划是否制定

总结#

版本管理虽然看起来复杂，但核心原则很简单：

1. 清晰的版本号：用数字表达变更的性质
2. 详细的记录：changelog 让用户了解变化
3. 平稳的过渡：迁移指南帮助用户升级
4. 持续的维护：定期发布改进和修复

通过良好的版本管理，Skills 能够稳定演进，为用户提供可靠的功能扩展。