Skill 版本管理器（CTO 版本治理标准）

执行角色：CTO-001 版本治理 版本：v1.0.0 来源：ai-skill-maintainer §版本号规范 + §五步维护流程 + §回滚策略 合规：semver 2.0 标准

核心原则

1. 版本可追溯：所有变更必须记录 changelog
2. 向后兼容：MINOR/PATCH 不得破坏现有功能
3. 最小变更：只改必要的，拒绝过度工程化
4. 强制审查：所有变更必须通过安全审查

版本号规范（Semver 2.0）

版本格式

v<MAJOR>.<MINOR>.<PATCH>[-<prerelease>][+<build>]

版本升级规则

版本号更新规则

# Bug 修复
vX.Y.Z → vX.Y.(Z+1)

# 功能增强
vX.Y.Z → vX.(Y+1).0

# Breaking Change
vX.Y.Z → (X+1).0.0

# 安全补丁（强制 PATCH）
vX.Y.Z → vX.Y.(Z+1)

标准维护流程（五步）

Step 1 — 诊断（Diagnosis）

输入：用户描述的问题或需求

诊断记录模板：

## 诊断记录

Skill 名称：<name>
当前版本：<version>
问题类型：[Bug / 功能缺失 / 安全漏洞 / 依赖过时 / 其他]

### 问题描述
<用户描述>

### 复现步骤（如适用）
1.
2.
3.

### 影响范围
- 影响的功能：
- 影响的用户/Agent：

### 初步判断
- 根因：
- 修复方案：
- 版本影响：[PATCH / MINOR / MAJOR]

Step 2 — 分析（Analysis）

输出：维护记录文件

2.1 变更范围分析

### 受影响文件
| 文件 | 变更类型 | 风险评估 |
|------|---------|---------|
| SKILL.md | [修改/新增/删除] | 🟢 低 |
| scripts/*.py | ... | ... |

### 兼容性影响
- 向后兼容：✅ / ❌
- 触发关键词变更：✅ / ❌（如有变更需通知用户）
- 工具权限变更：✅ / ❌

### 测试计划
- [ ] 本地测试用例：
- [ ] 回归测试：

2.2 安全影响分析（CTO）

Step 3 — 实施（Implementation）

3.1 版本号更新

# 根据变更类型确定版本
# Bug 修复          → vX.Y.Z → vX.Y.(Z+1)
# 功能增强          → vX.Y.Z → vX.(Y+1).0
# Breaking Change   → vX.Y.Z → (X+1).0.0
# 安全补丁          → vX.Y.Z → vX.Y.(Z+1)  （强制）

3.2 SKILL.md 更新

更新 Frontmatter 版本：

---
name: <skill-name>
version: X.Y.Z   # ← 更新版本号
description: |   # ← 如有变更同步更新
  ...
---

更新版本历史（在文件顶部或底部）：

## 版本历史

| 版本 | 日期 | 变更内容 |
|------|------|---------|
| X.Y.Z | YYYY-MM-DD | <变更摘要> |
| ... | ... | ... |

3.3 scripts/ 更新

更新检查清单：

- [ ] 脚本已更新
- [ ] 脚本版本号已更新（如有版本机制）
- [ ] 依赖已更新（如有）
- [ ] 新增依赖已记录
- [ ] 脚本测试已通过

Step 4 — 安全审查（Security Review）

⚠️ 强制门禁：所有变更必须通过 CISO 安全审查

4.1 变更 diff 审查

审查变更内容（对比上一版本）：

• 新增的代码是否含 RED FLAGS？
• 修改的代码是否引入新漏洞？
• 删除的代码是否影响安全边界？

4.2 依赖审查

# 列出新增/升级的依赖
# 检查 CVE

Step 5 — 验证与发布（Verify & Publish）

5.1 验证清单

## 发布前验证

- [ ] 变更内容与诊断一致
- [ ] 版本号符合变更类型
- [ ] 安全审查通过
- [ ] 脚本测试通过
- [ ] changelog 已更新
- [ ] SKILL.md 已同步更新

5.2 发布命令

# 打包
clawhub package ./<skill-name> --output ./dist

# 发布
clawhub publish ./<skill-name> \
  --slug <skill-name> \
  --name "<Skill Name>" \
  --version X.Y.Z \
  --changelog "<变更摘要>"

回滚策略（Rollback）

如维护操作失败，执行以下步骤恢复：

自动回滚条件

回滚命令

# 恢复到上一个可用版本
git checkout tags/v<上一版本> -- SKILL.md scripts/ references/

# 验证回滚成功
git log --oneline -3

解除 emergency-isolate 条件

1. CVE 已修复（CVSS < 7.0）
2. CISO-001 安全复审通过
3. CQO-001 质量验收通过
4. CTO-001 书面授权解除隔离

维护记录模板

保存至 references/maintenance-log.md：

# Skill 维护记录

## Skill 信息
- 名称：<name>
- 当前版本：<version>
- 维护者：<maintainer>

## 维护历史

### 维护 #N — YYYY-MM-DD

**类型**：[Bug修复/功能增强/安全补丁/废弃/其他]
**版本**：<old> → <new>
**变更摘要**：<summary>

#### 变更详情
<detailed changes>

#### 安全审查
- CVSS：<score>
- 结论：[通过/拒绝/条件通过]

#### 测试结果
- [ ] 测试通过

#### 发布信息
- 发布日期：YYYY-MM-DD
- ClawHub 版本：<version>

快速参考

版本历史