16.5 Skills版本管理
约 1065 字大约 4 分钟
为什么需要版本管理
Skills 的版本管理帮助我们：
- 跟踪变化：记录 Skills 的功能更新和 bug 修复
- 确保兼容性：知道哪些版本可以安全升级
- 管理依赖：避免不同版本之间的冲突
- 团队协作：多人开发时协调代码变更
版本号的基本概念
语义化版本格式
Skills 使用 主版本.次版本.修订版本 的格式，例如：1.2.3
- 主版本（1）：重大变更，可能不兼容旧版本
- 次版本（2）：新增功能，但保持向后兼容
- 修订版本（3）：修复 bug，不影响功能
版本示例
在 Skills 中声明版本
---
name: my-skill
description: Brief description of the skill
metadata:
version: "1.2.0"
author: your-name
---使用 Git 管理版本
基本的 Git 工作流
1. 创建版本标签
# 创建新版本的标签
git tag v1.0.0
# 查看所有版本
git tag --list
# 查看版本历史
git log --oneline --decorate2. 分支管理
# 创建开发分支
git checkout -b feature/new-function
# 开发完成后合并到主分支
git checkout main
git merge feature/new-function
# 删除临时分支
git branch -d feature/new-function3. 版本发布
# 准备发布
git checkout main
git pull
# 创建发布标签
git tag -a v1.1.0 -m "Release version 1.1.0"
# 推送到远程仓库
git push origin main --tags维护变更日志
CHANGELOG.md 文件
记录版本之间的变更：
# Changelog
## [1.1.0] - 2024-01-15
### Added
- 新增 PDF 表单处理功能
### Fixed
- 修复中文字符编码问题
## [1.0.0] - 2024-01-01
### Added
- 基本的 PDF 文本提取功能
- 支持多种 PDF 格式版本发布流程
发布前的准备
- 更新版本号： yaml复制metadata: version: "1.1.0"
- 更新变更日志：
记录所有新增功能 列出修复的 bug 说明不兼容的变更 3. 记录所有新增功能 4. 列出修复的 bug 5. 说明不兼容的变更 6. 测试验证：
确保新版本正常工作 检查向后兼容性 7. 确保新版本正常工作 8. 检查向后兼容性
更新版本号：
metadata:
version: "1.1.0"更新变更日志：
记录所有新增功能
列出修复的 bug
说明不兼容的变更
确保新版本正常工作
检查向后兼容性
发布步骤
- 提交代码变更
- 创建版本标签
- 推送到代码仓库
- 更新文档
处理版本冲突
向后兼容性
- 小版本更新（1.0.x → 1.1.0）：新增功能，不会破坏现有使用
- 大版本更新（1.x.x → 2.0.0）：可能包含不兼容的变更
迁移指南
当发布不兼容的变更时，提供迁移说明：
## 迁移到 v2.0.0
### 破坏性变更
- `old_function()` 已移除，请使用 `new_function()`
### 迁移步骤
1. 更新函数调用
2. 修改配置参数
3. 测试功能是否正常版本管理最佳实践
为用户考虑
- 保持向后兼容：尽量避免破坏性变更
- 提供迁移路径：大版本更新时给出详细的升级指南
- 及时发布补丁：快速修复发现的 bug
为开发者考虑
- 使用语义化版本：让版本号含义清晰
- 维护变更日志：记录每次更新的内容
- 标签化发布：用 Git 标签标记重要版本
版本管理检查清单
发布前检查
- 版本号是否正确递增
- 变更日志是否更新
- 所有测试是否通过
- 文档是否同步更新
发布后跟进
- 用户反馈是否收集
- 兼容性问题是否解决
- 后续版本规划是否制定
总结
版本管理虽然看起来复杂，但核心原则很简单：
- 清晰的版本号：用数字表达变更的性质
- 详细的记录：changelog 让用户了解变化
- 平稳的过渡：迁移指南帮助用户升级
- 持续的维护：定期发布改进和修复
通过良好的版本管理，Skills 能够稳定演进，为用户提供可靠的功能扩展。
技术说明：本章中的 Git 命令示例是为了帮助您理解版本管理流程。实际操作时，您可以根据团队的 Git 工作流进行调整。