sanguo_moziplus_v2/docs/design/19-skill-lifecycle-and-experience-loop.md

# §19 Skill 生命周期管理 + 经验闭环四阶段设计

> 作者：庞统士元
> 日期：2026-06-18
> 状态：方案待确认
> 前置：§14 Task 五层架构、§16 知识注入四层体系

## 1. 背景

moziplus v2.0 的 P4 剩余两项：
- T7 C3：Skill 生命周期管理（draft → active → deprecated）
- T7 C5：经验闭环 IMPROVE 阶段（DISCOVER → DISTILL → APPLY → IMPROVE 中的最后一步）

### 当前实现状态

| 组件 | 状态 | 问题 |
|------|------|------|
| `SkillRegistry`（skill_system.py） | 死代码 | 只有 register/match 方法，从未被外部调用 |
| `SkillExecutor`（skill_system.py） | 死代码 | 从未被外部调用 |
| `ExperienceDistiller`（experience.py） | 空转 | ticker 调用时没传 review_result 和 outputs，蒸馏函数收到 None 直接返回空 |
| `ExperienceStore`（experience.py） | 空转 | experiences 目录全部为空 |
| `experiences` 表（db.py） | 未使用 | 代码用 jsonl 文件不用 DB 表 |
| Skill 生命周期 | 缺失 | 只有 enabled bool，无 draft/active/deprecated 状态流转 |

**结论**：现有的 experience.py 和 skill_system.py 需要重新设计，不是修补能解决的。

### 实际运行的知识体系

实际的 Skill 发现和加载走的是 **openclaw 原生 skill 机制**：
- openclaw 扫描 skills 目录 → 生成 `<available_skills>` 列表注入 system prompt
- Agent 按 description 匹配 → `read` SKILL.md → 按内容执行
- moziplus 的 SkillRegistry/SkillExecutor 完全不参与

因此本设计**不重建 moziplus 的 skill 引擎**，而是基于 openclaw 原生机制构建。

## 2. 设计目标

1. 经验从「发现→蒸馏→应用→改善」形成完整闭环
2. Skill 有明确的生命周期管理（draft → active → deprecated）
3. 产物统一为 Skill，不再有 experiences.jsonl / .learnings/ 等中间形态散落各处
4. 追踪 Skill 引用情况，支撑淘汰决策
5. 充分利用 openclaw 已有的 skill_workshop 工具和 skill 加载机制

## 3. 核心设计决策

| # | 决策 | 理由 | 参考 |
|---|------|------|------|
| D1 | 统一产物：Skill-only | 不再有中间形态散落各处。Hermes 只有 Skill + Memory 两种载体，没有第三种 | Hermes skill_manage + memory_tool |
| D2 | 生命周期通过 skill_workshop 管理 | OpenClaw 已有 pending → applied → rejected → quarantined 生命周期 | OpenClaw skill_workshop 工具 |
| D3 | 蒸馏频率：每天一次 cron | 任务量不大，全量扫描比逐任务蒸馏更全面。主公确认 | 主公确认 |
| D4 | 蒸馏者：庞统 | 不是自动 LLM 蒸馏，用判断力提炼根因模式。未来再考虑自动化 | moziplus 经验实践 #4（PRD 理想态 vs 架构务实态） |
| D5 | 二级蒸馏抽象为根因模式 | 不固化在特定技术细节。description 描述「问题模式」而非「技术症状」 | Superpowers writing-skills：description = when not how |

## 4. L4 知识层：Skill Workshop

在现有 L0-L3 四层知识体系上新增 L4：

| 层级 | 名称 | 内容 | 加载方式 | 已有 |
|------|------|------|---------|------|
| L0 | 注入式上下文 | MEMORY.md / TOOLS.md | 每次 session 启动 | ✅ |
| L1 | 确定性规则 | SOUL.md / AGENTS.md | 每次 session 启动 | ✅ |
| L2 | 任务上下文 | BootstrapBuilder PromptSection | 按 task_type 注入 | ✅ |
| L3 | 按需 Skill | openclaw skills | description 匹配 → agent read | ✅ |
| **L4** | **Skill 生命周期** | **skill_workshop** | **draft → active → deprecated 管理** | **新增** |

L4 不是一个 prompt 层，而是 Skill 的**管理层**——负责 Skill 的创建、验证、应用、追踪、淘汰。

## 5. DISCOVER 阶段

### 5.1 数据源（全量）

| 数据源 | 位置 | 包含什么 |
|--------|------|---------|
| 黑板 tasks | 各项目 blackboard.db | 任务生命周期：创建、分配、执行、完成/失败 |
| 黑板 reviews | reviews 表 | 审查结论 + 逐步骤 verdict + suggestions |
| 黑板 comments | comments 表 | @mention 讨论、rebuttal 推理、action_report |
| 黑板 outputs | outputs 表 | 任务产出物内容 |
| 黑板 events | events 表 | 状态变更、guardrail 拦截、异常检测 |
| Gitea Issues/PRs | Gitea API | 问题报告、diff、review 评论 |
| Gitea CI | Gitea Actions | lint/test/build 成功/失败 |
| Mail | mail API | 跨 agent 通信、讨论推理过程 |
| Session JSONL | ~/.openclaw/agents/*/sessions/ | Agent 完整思考过程、工具调用、错误恢复 |
| MEMORY.md | 各 agent workspace | 长期记忆、已有经验教训 |
| .learnings/ | 各 agent workspace | 已记录的学习/错误/特征请求 |
| knowledge-gaps.md | wiki-vault/_meta/ | 知识缺口 |

### 5.2 信号识别（5 类高价值信号）

| 信号类型 | 从哪发现 | 识别特征 |
|---------|---------|---------|
| 失败模式 | task failed、CI failed、review rejected | 有明确的失败原因 |
| 重复问题 | 跨多个任务/agent 出现同类问题 | 同关键词出现 ≥2 次 |
| 决策转折 | rebuttal comment、需求澄清、主公纠正 | 原方向被推翻或修正 |
| 新实践 | 设计文档新增、wiki-vault 新页面 | 之前没有的知识 |
| 知识缺口 | knowledge-gaps.md、agent 表达不确定 | 查不到/不确定的东西 |

### 5.3 去重

同一事件在多个数据源出现（CI 失败 → toolchain task → mail → comment 讨论），按时间窗口 + 关键词去重，保留信息量最大的那条。

### 5.4 输出

候选信号列表，每条包含：
```
信号类型 | 来源（task_id / PR / review / session）| 时间 | 简述（≤100 字）
```

## 6. DISTILL 阶段

### 6.1 核心原则：HOW not WHAT

蒸馏的是「怎么做」不是「发生了什么」（nuwa-skill 实践 #5）：

```
❌ "PR #83 修复了 event_type 未知的问题"
    → 这是 WHAT，无法复用

✅ "数据消费者与数据生产者解耦时，新增字段必须同步所有生产者的提取逻辑"
    → 这是 HOW，可复用到任何消费者/生产者场景
```

### 6.2 蒸馏产物 = Skill

直接产出 SKILL.md 格式或对现有 Skill 的 patch，提交到 skill_workshop。

**SKILL.md 编写规范**（参考 Superpowers writing-skills）：

```yaml
---
name: skill-name
description: Use when [触发条件/问题模式描述]，不描述工作流
---

# Skill 标题

## 什么时候用
（具体的触发场景，按问题模式描述，不按技术特定症状）

## 怎么做
（根因分析 + 操作步骤）

## 常见错误
（反模式：什么不该做）

## 来源
（evidence：哪些 task/PR/review 提炼了这条经验）
```

**description 关键规则**（Superpowers 的核心发现）：
- 只描述触发条件（when to use），**绝不描述工作流**（how）
- 以「Use when...」开头
- 描述问题模式，不描述技术特定症状
- 原因：测试发现 description 如果总结了工作流，agent 会按 description 执行而跳过读完整 SKILL.md

### 6.3 蒸馏示例

**一级蒸馏**（从具体案例提取）：

```yaml
# 案例 1：PromptContext event_type 未知
# 案例 2：PromptContext from_agent/mail_type 缺失（PR #26 D2）
→ 共同根因：消费者/生产者字段同步问题

# 蒸馏为 Skill section（加到 trial-and-error-patterns）：
## 消费者/生产者字段同步

**什么时候用**：修改 dataclass 时，如果该 dataclass 由外部 JSON 提取填充

**怎么做**：
1. 改 dataclass 定义
2. 检查所有从 JSON 提取字段的代码路径，同步新增提取逻辑
3. 检查所有构造该 dataclass 的调用点，同步新增参数
4. 跑一次构建测试验证字段不为空

**常见错误**：只改 dataclass 不改提取逻辑 → 字段默认值为空 → 运行时不报错但行为异常
```

**二级蒸馏**（从多个一级经验提取通用模式）：

如果「消费者/生产者字段同步」经验在 ≥2 个不同场景复现（PromptContext + 其他），三重验证通过后，可以提升为独立 Skill 或固化到 AGENTS.md 规则。

### 6.4 三重验证（nuwa-skill 实践 #2）

从 draft → active 的验证标准：

| 验证维度 | 标准 | 不通过的后果 |
|---------|------|------------|
| 跨任务复现 | 同类问题在 ≥2 个不同场景出现过 | 降级为 MEMORY.md 临时记录 |
| 有生成力 | 能给出具体的操作指引 | 丢弃 |
| 有排他性 | 不是「代码要测试」的常识 | 丢弃 |

### 6.5 质量检查自动化

参考 nuwa-skill quality_check.py，对蒸馏产出做结构化检查：

| 检查项 | 标准 |
|--------|------|
| trigger 是否具体 | 不是「注意代码质量」这种泛泛而谈 |
| action 是否可执行 | 不是「要小心」这种无操作指引 |
| 是否与已有 Skill 重复 | 检查现有 skills 目录中是否已有覆盖 |
| description 是否只含触发条件 | 不包含工作流描述 |

### 6.6 矛盾处理（nuwa-skill 实践 #10）

新经验与已有经验冲突时：
- **时间性矛盾**（观点演化）→ 记录演化轨迹，以近期为主
- **领域性矛盾**（不同场景不同规则）→ 分场景记录
- **本质性张力**（价值观内在冲突）→ 标注为「核心张力」，两个版本都保留

**矛盾是特征，不是 Bug。** 强制调和会丢失关键信号。

### 6.7 蒸馏者

庞统作为蒸馏者，每天 cron spawn 时执行：
1. 读取 DISCOVER 产出的候选信号列表
2. 用判断力提取根因模式（不是机械提取）
3. 按 SKILL.md 格式产出
4. 提交到 skill_workshop（pending proposal）

未来考虑半自动化（LLM 辅助草案 + 庞统审阅确认）。

## 7. APPLY 阶段

### 7.1 统一走 openclaw skill 机制

**不新建 ExperienceSection 或任何 moziplus 自定义注入**。因为产物统一为 Skill，openclaw 已有的机制天然支持：

1. openclaw 扫描 skills 目录 → 生成 `<available_skills>` 列表
2. Agent 按 description 匹配 → `read` SKILL.md
3. Agent 按内容执行

### 7.2 Skill description 编写规范

这是 APPLY 阶段效果好坏的关键。参考 Superpowers writing-skills 的核心发现：

```yaml
# ❌ BAD：描述了工作流，agent 会按 description 执行而跳过读 SKILL.md
description: Use when modifying dataclass — checks all extraction points, runs tests, verifies non-null fields

# ✅ GOOD：只描述触发条件
description: Use when modifying a dataclass that is populated from JSON extraction by another module

# ❌ BAD：太抽象
description: Use for code quality

# ✅ GOOD：描述问题模式
description: Use when a field added to a dataclass appears empty or as default value at runtime
```

### 7.3 渐进式加载

openclaw 已有的机制：
- L1：`<available_skills>` 列表（~100 token/skill，只有 name + description）
- L2：Agent `read` SKILL.md（完整内容）
- L3：SKILL.md 内引用的 references/ 文件（按需加载）

## 8. IMPROVE 阶段

### 8.1 Skill 自我修补

参考 Hermes skill_manage 的设计哲学：

> "If you used a skill and hit issues not covered by it, patch it immediately."
> "Skills that aren't maintained become liabilities."

Agent 使用 Skill 时发现问题（缺步骤、过时信息、命令变更）→ 立即通过 skill_workshop 提交 revise proposal（patch）。

这不需要定时任务，靠 agent 的主动维护。关键是在 agent 的 prompt 中注入这条规则（SOUL.md 或 AGENTS.md）。

### 8.2 引用追踪

**设计原则**：不追求精确归因，做时间维度的信号采集。

| 信号 | 采集方式 | 可信度 |
|------|---------|--------|
| Skill 最近被 read 的时间 | 扫描 session JSONL 中 `"tool":"read"` + SKILL.md 路径 | 中 |
| Skill 在 available_skills 中被注入 | 扫描 JSONL 中 available_skills 列表 | 中（被注入但未必被用） |
| Agent 在输出中提及了 skill name | grep skill name in assistant messages | 高（主动提到说明确实用了） |
| Skill 文件最近修改时间 | git log / 文件 mtime | 高 |

**采集频率**：每周一次 cron，扫描过去 7 天的所有 session JSONL。

### 8.3 淘汰机制

**决策流程**：

```
30 天无引用信号
  → 生成淘汰候选报告（庞统审阅）
    → 确认淘汰 → skill_workshop quarantine
    → 保留观察 → 标注，下轮再查
    → 更新后保留 → 修改 description / 内容，重置计时
```

**注意**：openclaw 本身的 skill（~/.openclaw/plugin-skills/ 和全局 skills）也纳入追踪范围。主公可以据此决定哪些 openclaw skill 可以禁用。

### 8.4 经验提升路径

同一 Skill section 被频繁引用（≥5 次）且经过多次验证 → 考虑提升：

| 提升目标 | 条件 | 效果 |
|---------|------|------|
| 独立 Skill | 足够通用，有自己的触发条件 | 独立 SKILL.md，description 匹配 |
| AGENTS.md 规则 | 确定性高，适用于所有 agent | L1 确定性注入，强制生效 |
| guardrail | 安全相关，不可违反 | 强制检查 |

### 8.5 反馈到 DISCOVER

IMPROVE 发现的经验缺口（「这条 Skill 不适用 XXX 场景」）→ 写入 knowledge-gaps.md → 成为下一轮 DISCOVER 的输入。

## 9. 闭环全景

```
DISCOVER（每天 cron）
  数据源：黑板 + Gitea + Mail + JSONL + MEMORY + .learnings + knowledge-gaps
  信号识别：5 类高价值信号
  去重：时间窗口 + 关键词
  输出：候选信号列表
  ↓
DISTILL（同 cron，庞统执行）
  原则：HOW not WHAT（根因模式，不固化技术细节）
  验证：三重验证（跨任务复现 + 生成力 + 排他性）
  质量：自动化检查 + 矛盾保留
  产物：Skill（draft → skill_workshop pending proposal）
  ↓
APPLY（实时，openclaw skill 机制）
  匹配：description 匹配 → agent read SKILL.md
  执行：agent 按内容执行
  自我修补：使用时发现问题 → 立即 revise proposal
  ↓
IMPROVE（每周 cron）
  追踪：scan JSONL 引用信号
  淘汰：30天无引用 → 庞统审查 → quarantine
  提升：高频引用 → 独立 Skill / AGENTS.md 规则 / guardrail
  反馈：知识缺口 → knowledge-gaps.md → 回到 DISCOVER
```

## 10. 与现有实现的关系

| 组件 | 处理方式 |
|------|---------|
| `skill_system.py`（SkillRegistry/SkillExecutor） | **标记 deprecated，后续清理。** 死代码，实际不参与 skill 发现/加载 |
| `experience.py`（ExperienceDistiller/ExperienceStore） | **标记 deprecated，后续清理。** 空转代码，experiences 目录全空 |
| `experiences` 表 / `experience_tags` 表（db.py） | **保留表结构但不再写入。** 未来如果需要 DB 查询可以重新启用 |
| ticker.py:336-348 经验蒸馏逻辑 | **移除。** 不再逐任务蒸馏，改为每天 cron |
| `skill_workshop` 工具 | **核心使用。** 所有 Skill 生命周期通过它管理 |
| openclaw `<available_skills>` 机制 | **核心依赖。** APPLY 阶段完全基于此 |

## 11. 实现计划

| 步骤 | 内容 | 优先级 | 工作量 |
|------|------|--------|--------|
| S1 | 在 SOUL.md / AGENTS.md 加入 Skill 自我修补规则 | P0 | L1（改文案） |
| S2 | 创建 skill-management Skill（本设计的 skill 化封装） | P0 | L2 |
| S3 | 实现 DISCOVER cron：全量数据源扫描 + 信号识别 | P1 | L2-L3 |
| S4 | 实现 DISTILL 流程：庞统 cron 读取信号 + 提交 skill_workshop proposal | P1 | L2 |
| S5 | 实现 IMPROVE cron：JSONL 引用追踪 + 淘汰报告 | P2 | L2-L3 |
| S6 | 清理 deprecated 代码（skill_system.py / experience.py） | P3 | L1 |

S1 和 S2 可以立即做。S3-S5 需要先确认设计文档。

## 12. wiki-vault / 知识库参考实践映射

| 设计决策 | 参考来源 | 核心借鉴 |
|---------|---------|---------|
| 统一产物 Skill-only | Hermes skill_manage + memory_tool | 只有 Skill 和 Memory 两种载体 |
| HOW not WHAT | nuwa-skill 实践 #5 | 蒸馏思维方式不是知识内容 |
| description = when not how | Superpowers writing-skills | description 只描述触发条件 |
| 三重验证 | nuwa-skill 实践 #2 | 跨域复现 + 生成力 + 排他性 |
| 质量检查自动化 | nuwa-skill quality_check.py | 结构化检查代替主观判断 |
| 矛盾处理 | nuwa-skill 实践 #10 | 矛盾是特征不是 Bug |
| Skill 自我修补 | Hermes skill_manage schema | 使用时发现问题立即 patch |
| 闭环学习循环 | 知识管理体系实践 #1 | DISCOVER→DISTILL→APPLY→IMPROVE |
| Experience→Skill 延迟转化 | moziplus 经验实践 #2 | 多次验证后才固化 |
| Skill 生命周期 draft→active→deprecated | OpenClaw skill_workshop | pending→applied→rejected→quarantined |
| 棘轮机制 | moziplus 经验实践 #2 | 经验只能改进不能退化 |
| 优雅降级 | nuwa-skill 实践 #17 | 信息不足时不要强行蒸馏 |
| 迭代上限 | nuwa-skill 实践 #18 | 最多 2 轮验证，不无限打磨 |