第 5 章：Skill 进化与持续优化¶

主版本。次版本.修订版本
  ↑      ↑      ↑
  │      │      └─ Bug 修复（向后兼容）
  │      └──────── 新功能（向后兼容）
  └─────────────── 破坏性变更

1.0.0 → 初始发布
1.0.1 → Bug 修复
1.1.0 → 新功能
2.0.0 → 破坏性变更

小版本（x.x.1-9）：每 1-2 周
  - Bug 修复
  - 性能优化
  - 文档更新

中版本（x.1-9.0）：每月
  - 新功能
  - 显著改进
  - 向后兼容

大版本（1-9.0.0）：每季度/半年
  - 架构变更
  - API 变更
  - 破坏性更新

## [1.1.0] - 2026-03-26

### 新增
- 新增 PDF 合并功能
- 新增批量处理支持

### 改进
- 提取性能提升 50%
- 错误提示更清晰

### 修复
- 修复大文件处理崩溃
- 修复编码问题

### 变更
- 默认输出格式改为 UTF-8
- 弃用旧 API（将在 2.0.0 移除）

1. 每次发布前创建备份
2. 保留最近 3 个版本
3. 一键回滚能力
4. 回滚后数据兼容

def rollback_skill(skill_name, target_version):
    # 1. 备份当前版本
    backup_current(skill_name)

    # 2. 恢复目标版本
    restore_version(skill_name, target_version)

    # 3. 验证
    if not verify_skill(skill_name):
        # 恢复失败，回滚回滚
        restore_from_backup()
        raise Exception("Rollback failed")

    # 4. 通知用户
    notify_users(f"{skill_name} 已回滚到 {target_version}")

在 Skill 末尾添加：

## 反馈

遇到问题或有改进建议？
- 📝 [提交反馈](链接)
- 💬 [Discord 社区](链接)
- 🐛 [报告 Bug](链接)
- ⭐ [评价 Skill](链接)

任务完成后（可选）：

"这次体验如何？"
😊 满意 → "谢谢！有什么可以改进的吗？[文本框]"
😐 一般 → "请告诉我们如何改进：[文本框]"
😞 不满意 → "抱歉！问题是什么？[文本框]"

# 自动收集错误和纠正
def collect_feedback(session):
    feedback = {
        'errors': extract_errors(session),
        'corrections': extract_corrections(session),
        'retries': count_retries(session),
        'duration': session.duration
    }

    if feedback['errors'] or feedback['corrections']:
        save_feedback(feedback)

用户反馈
  ├── Bug 报告（功能错误）
  │    └─→ 优先级：高 → 修复 → 验证 → 发布
  ├── 功能请求（新能力）
  │    └─→ 评估价值 → 规划 → 开发 → 发布
  ├── 体验问题（难用、困惑）
  │    └─→ 分析原因 → 优化 → 测试 → 发布
  └── 表扬建议（保持、推广）
       └─→ 记录 → 在营销中使用

def prioritize_feedback(feedback):
    score = 0

    # 影响范围
    if feedback.affects_all_users:
        score += 30
    elif feedback.affects_many_users:
        score += 20
    else:
        score += 10

    # 严重程度
    if feedback.is_blocking:
        score += 40
    elif feedback.is_major:
        score += 25
    else:
        score += 10

    # 频率
    if feedback.is_recurring:
        score += 20

    # 用户价值
    if feedback.high_value_user:
        score += 10

    return score

# 优先级
# 80-100: 立即处理
# 60-79:  本周处理
# 40-59:  本月处理
# <40:     backlog

新建 → 确认 → 处理中 → 待验证 → 已解决 → 已发布
  ↓      ↓
  └─→ 拒绝（说明原因）

## 反馈 #123

**类型：** Bug 报告
**优先级：** P1
**状态：** 已解决

### 描述
用户报告 PDF 合并时文件顺序错误

### 复现
1. 选择 3 个 PDF
2. 调整顺序为 2-1-3
3. 执行合并
4. 输出顺序为 1-2-3（错误）

### 原因
排序逻辑使用了字母排序而非用户指定顺序

### 修复
修改排序逻辑，使用用户指定的索引

### 验证
- [x] 单元测试通过
- [x] 手动测试通过
- [x] 用户确认

### 发布
包含在 v1.1.2 中发布

使用 → 记录 → 分析 → 学习 → 应用 → 验证
  ↑                                      ↓
  └──────────────────────────────────────┘

记录错误：
- 什么操作失败了
- 错误信息
- 上下文
- 最终解决方案

应用：
- 更新故障排查文档
- 添加错误处理
- 创建预防措施

记录纠正：
- 用户纠正了什么
- 正确做法
- 为什么错了

应用：
- 更新 SKILL.md
- 添加注意事项
- 修改默认行为

记录优化：
- 发现了更好的方法
- 性能提升
- 用户体验改善

应用：
- 更新最佳实践
- 修改工作流
- 分享经验

.learnings/
├── ERRORS.md
│   ## [ERR-20260326-001] pdf_merge
│   **Logged**: 2026-03-26T10:30:00Z
│   **Priority**: high
│   **Status**: resolved
│   
│   ### Summary
│   PDF 合并时文件顺序错误
│   
│   ### Error
│   输出顺序与用户指定顺序不符
│   
│   ### Fix
│   修改排序逻辑
│   
│   ### Prevention
│   添加顺序验证测试

├── LEARNINGS.md
│   ## [LRN-20260326-001] best_practice
│   **Logged**: 2026-03-26T14:00:00Z
│   **Priority**: medium
│   **Status**: promoted
│   
│   ### Summary
│   批量处理时先验证文件存在
│   
│   ### Details
│   发现批量处理时如果有文件不存在会中途失败
│   
│   ### Best Practice
│   1. 先验证所有文件存在
│   2. 再开始处理

└── FEATURE_REQUESTS.md
    ## [FEAT-20260326-001] pdf_split
    **Logged**: 2026-03-26T16:00:00Z
    **Priority**: medium
    **Status**: planned

    ### Request
    用户需要按页码拆分 PDF

    ### Use Case
    提取特定页面发送给不同人

    ### Implementation
    添加 split_by_pages 功能

def apply_learning(learning):
    if learning.type == 'error':
        # 添加错误处理
        add_error_handling(learning)
        # 更新文档
        update_troubleshooting(learning)

    elif learning.type == 'correction':
        # 更新主逻辑
        update_main_logic(learning)
        # 添加测试
        add_test_case(learning)

    elif learning.type == 'optimization':
        # 应用优化
        apply_optimization(learning)
        # 更新文档
        update_best_practices(learning)

定期审核学习（每周）：

## 本周学习审核

### 待应用学习
1. [LRN-001] - 批量处理验证 → 计划本周
2. [LRN-002] - 错误提示优化 → 计划下周

### 已应用学习
1. [ERR-001] - PDF 顺序修复 → v1.1.2
2. [LRN-003] - 性能优化 → v1.1.1

### 待讨论学习
1. [FEAT-001] - 拆分功能 → 需要评估工作量

满足以下任一条件：
1. 重复出现 3+ 次
2. 跨 2+ 不同任务
3. 30 天内频繁使用
4. 用户明确要求
5. 有通用价值

def should_extract_skill(learning):
    score = 0

    # 频率
    if learning.recurrence_count >= 3:
        score += 30

    # 跨任务
    if learning.task_diversity >= 2:
        score += 25

    # 时间窗口
    if learning.time_window_days <= 30:
        score += 20

    # 用户请求
    if learning.user_requested:
        score += 15

    # 通用性
    if learning.is_generalizable:
        score += 10

    return score >= 60  # 阈值

1. 识别候选学习
       ↓
2. 评估提取价值
       ↓
3. 设计 Skill 结构
       ↓
4. 实现核心功能
       ↓
5. 编写文档
       ↓
6. 测试验证
       ↓
7. 发布 Skill
       ↓
8. 更新原学习状态

原始学习：
"在处理用户 A 的 PDF 时，发现需要先验证文件存在"

抽象后：
"批量处理文件前，先验证所有文件存在"

→ 移除特定用户、特定文件

原始：
"用 pdfplumber 打开 file.pdf"

抽象：
```python
def process_pdf(file_path):
    with pdfplumber.open(file_path) as pdf:
        ...

**原则 3：可配置**
```markdown
原始：
"设置超时为 30 秒"

抽象：
```python
def process(timeout=30):
    ...

### 提取模板

```markdown
# 技能提取模板

## 原始学习
- 学习 ID: LRN-XXXX
- 出现次数：X
- 涉及任务：[任务列表]

## 抽象 Skill

### 名称
[skill-name]

### 用途
[一句话描述]

### 触发条件
[何时使用]

### 核心功能
[功能列表]

### 与原始学习的区别
[去情境化、参数化、可配置说明]

## 验证
- [ ] 单元测试通过
- [ ] 集成测试通过
- [ ] 用户测试通过

# 发布到 ClawHub
clawhub publish ./my-skill

# 用户安装
clawhub install my-skill

仓库结构：
my-skill/
├── SKILL.md
├── scripts/
├── references/
├── .github/
│   └── workflows/
│       └── publish.yml  # 自动发布
└── README.md  # 人类可读文档

# 打包
python scripts/package_skill.py ./my-skill

# 分享 .skill 文件
# 用户安装
clawhub install ./my-skill.skill

仓库公开，欢迎贡献：
- Issues: 报告问题、请求功能
- PRs: 代码贡献
- Discussions: 讨论想法

维护者职责：
- 审查 PR
- 回答问题
- 发布版本

核心团队 + 社区贡献者：
- 核心团队：架构、发布
- 社区贡献者：功能、修复

治理模式：
- RFC 流程
- 投票决策
- 透明路线图

内部 Skill 仓库：
- 私有 ClawHub
- 内部 GitHub
- 文档门户

审核流程：
- 安全审查
- 功能验证
- 文档完整

# .github/workflows/sync.yml
name: Sync to ClawHub

on:
  release:
    types: [published]

jobs:
  publish:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v2

      - name: Publish to ClawHub
        run: |
          clawhub publish ./my-skill \
            --token ${{ secrets.CLAWHUB_TOKEN }}

Skill 依赖声明：

dependencies:
  - pdf-tools: ">=1.0.0"
  - data-utils: ">=2.0.0"

→ 安装时自动检查依赖

- 基础日志功能
- 三种日志类型
- 手动提升

新增：
- 自动错误检测
- Hook 集成
- 激活脚本

改进：
- 日志格式标准化

新增：
- 技能提取脚本
- 提取条件判断
- 自动模板生成

改进：
- 提升流程自动化

变更：
- 新的日志存储格式
- OpenClaw 深度集成
- 跨会话通信

移除：
- 旧 Hook 系统（不兼容）

1. 早期用户反馈至关重要
2. 破坏性变更需要充分沟通
3. 自动化是规模化的关键
4. 文档更新与代码同步

- 基础优化功能
- 单一供应商心跳
- 手动配置

新增：
- 回滚功能
- 健康检查
- Diff 预览
- --no-color 选项

改进：
- 多供应商支持
- 更好的错误提示

1. 安全功能（回滚、预览）提高采用率
2. CLI 体验影响用户满意度
3. 量化收益（节省金额）促进传播

## 版本策略

### 版本号规范
[说明你使用的版本规范]

### 发布周期
- 小版本：[周期]
- 中版本：[周期]
- 大版本：[周期]

### 变更日志格式
[示例变更日志]

### 回滚计划
[如何实现回滚]

## 反馈闭环设计

### 收集渠道
1. [渠道 1]: [说明]
2. [渠道 2]: [说明]
3. [渠道 3]: [说明]

### 分类处理
[如何分类和处理反馈]

### 优先级评估
[评估标准和权重]

### 响应 SLA
| 优先级 | 响应时间 | 解决时间 |
|-------|---------|---------|
| ... | ... | ... |

### 追踪模板
[反馈追踪的格式]

## 自学习机制

### 学习类型
1. 错误学习：[如何记录和应用]
2. 纠正学习：[如何记录和应用]
3. 优化学习：[如何记录和应用]

### 学习存储
[存储结构和格式]

### 学习应用
[如何自动/手动应用学习]

### 审核流程
[定期审核的安排]

## 技能提取计划

### 候选学习
| 学习 ID | 出现次数 | 跨任务数 | 通用性 | 评分 |
|--------|---------|---------|-------|------|
| ... | ... | ... | ... | ... |

### 提取优先级
1. [最高优先级的学习]
2. ...
3. ...

### 提取时间表
- Q1: [计划提取的技能]
- Q2: ...
- Q3: ...

□ 有明确的版本策略
□ 有反馈收集渠道
□ 有反馈处理流程
□ 有学习记录机制
□ 有学习应用机制
□ 定期审核和改进
□ 有技能提取计划
□ 有分发渠道
□ 有社区协作机制

发布 → 收集反馈 → 分析学习 → 改进优化 → 发布新版本
  ↑                                              ↓
  └──────────────────────────────────────────────┘

每个周期：
- 修复 Bug
- 优化体验
- 添加功能
- 提升性能