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）：

---
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 蒸馏示例

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

# 案例 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 的核心发现：

# ❌ 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 轮验证，不无限打磨