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

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

## 变更摘要（v2.0）

| 变更项 | 原设计 | 新设计 | 理由 |
|--------|--------|--------|------|
| 蒸馏频率 | 庞统每天一次 | **双层 daily**：各 agent 03:00 自蒸馏 + 庞统 05:00 整合 | agent 是自己经验的最佳蒸馏者；庞统负责跨 agent 整合 |
| 蒸馏者 | 庞统一人 | **双层**：L1 各 agent + L2 庞统 | 消除蒸馏者偏差；经验是 per-agent 的 |
| .learnings/ | DISCOVER 数据源之一 | **废弃**。JSONL 是唯一数据源 | 信息冗余；agent 执行中不应分心写 .learnings/ |
| 三重验证 | 跨任务复现 + 生成力 + 排他性 | **Recurrence-Count 机制**（融合 self-improvement skill） | ≥3 次自动触发提升，比主观判断更客观 |
| Skill 数量 | 未明确 | **一个 skill：skill-management** + references/ 四阶段 | 减少上下文开销；DISCOVER/IMPROVE 是 cron 场景不需要独立 skill description |
| self-improvement skill | 未提及 | **废弃**。优势融合到 DISCOVER 输出格式 | 职责重叠；统一为单一闭环 |
| Skill 存放 | 未区分 | **per-agent 目录 + 公共目录** | agent 专属经验不污染其他 agent 上下文 |

## 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 加载机制
6. **每个 agent 是自己经验的最佳蒸馏者**——经验 per-agent，精益求精

## 3. 核心设计决策

| # | 决策 | 理由 | 参考 |
|---|------|------|------|
| D1 | 统一产物：Skill-only | 不再有中间形态散落各处。Hermes 只有 Skill + Memory 两种载体，没有第三种 | Hermes skill_manage + memory_tool |
| D2 | 生命周期通过 skill_workshop 管理 | OpenClaw 已有 pending → applied → rejected → quarantined 生命周期 | OpenClaw skill_workshop 工具 |
| D3 | 蒸馏频率：双层 daily | L1 各 agent 每天 03:00 自蒸馏；L2 庞统每天 05:00 整合。有距离感的蒸馏优于即时记录 | self-improvement skill daily review；主公确认 |
| D4 | 蒸馏者：双层（各 agent + 庞统） | L1 每个 agent 蒸馏自己的经验（自己最准）；L2 庞统负责跨 agent 共性识别 + draft 审查 | Hermes skill_manage：「每个将军都应建立自己的 Skill 库」 |
| D5 | 二级蒸馏抽象为根因模式 | 不固化在特定技术细节。description 描述「问题模式」而非「技术症状」 | Superpowers writing-skills：description = when not how |
| D6 | 废弃 .learnings/ 作为数据源 | JSONL 已包含完整信息（工具调用、推理过程、错误输出）。.learnings/ 只是重复抄写，且打断 agent 执行流 | DISCOVER 统一采集；主公确认 |
| D7 | 只创建一个 skill：skill-management | 四阶段的详细操作放到 references/ 目录。DISCOVER/IMPROVE 是 cron 场景不需要独立 skill description 常驻上下文 | moziplus skill-engineering practices §4：组合模式 |

## 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 L1 各 agent 自蒸馏（每天 03:00）

每个 agent 的 cron 扫描**自己当天**的 session JSONL，识别信号，蒸馏为 draft proposal。

**数据源（1 个）**：

| 数据源 | 位置 | 包含什么 |
|--------|------|---------|
| 自己的 Session JSONL | ~/.openclaw/agents/<agent_id>/sessions/*.jsonl | 当天完整思考过程、工具调用、错误恢复、用户对话 |

**不需要**扫描黑板/Gitea/Mail 等——那是 L2 庞统的职责。L1 聚焦自己的经验。

**信号识别（5 类高价值信号）**：

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

**输出**：draft skill proposal（提交到 skill_workshop，pending 状态）

### 5.2 L2 庞统整合（每天 05:00）

庞统的 cron 在 L1 全部完成后执行，扫描全量数据源 + 审查所有 L1 draft proposal。

**数据源（全量）**：

| 数据源 | 位置 | 包含什么 |
|--------|------|---------|
| 黑板 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 通信、讨论推理过程 |
| **所有 agent 的 Session JSONL** | ~/.openclaw/agents/*/sessions/ | 全团队完整思考过程 |
| MEMORY.md | 各 agent workspace | 长期记忆、已有经验教训 |
| knowledge-gaps.md | wiki-vault/_meta/ | 知识缺口 |
| **L1 draft proposals** | skill_workshop pending | 各 agent 当天提交的 draft |

**核心职责**：

a. **跨 agent 共性模式识别**：张飞和关羽都在类似场景踩坑 → 合并为共享 Skill
b. **审查 L1 draft proposals**：
   - APPROVE：质量达标的个人经验 → 变 active（仅作者 agent 可见）
   - MERGE：跨 agent 共性 → 合并为共享 Skill（所有 agent 可见）
   - REJECT：质量不够（附原因，agent 看到反馈后改进）
c. **全局提升**：高确定性/高频率经验 → 提升到 AGENTS.md 规则（所有 agent 强制注入）

### 5.3 去重

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

跨 agent 的同一模式，按 Pattern-Key 去重，合并为共享信号。

### 5.4 输出格式（融合 self-improvement skill 结构化字段）

每条候选信号包含：
```
信号类型 | 来源（task_id / PR / review / session）| 时间 | 简述（≤100 字）
ID: SIG-YYYYMMDD-XXX
Priority: low | medium | high | critical
Status: pending | in_progress | resolved | promoted
See Also: SIG-YYYYMMDD-XXX（关联信号）
Recurrence-Count: N（同一模式出现次数）
Pattern-Key: category.subcategory（稳定去重键，如 sync.field_mapping）
```

**字段说明**（汲取自 self-improvement skill）：

| 字段 | 用途 | 借鉴来源 |
|------|------|---------|
| ID | 唯一标识，便于交叉引用 | self-improvement logging format |
| Priority | 优先级排序，critical/high 优先处理 | self-improvement priority guidelines |
| Status | 生命周期跟踪 | self-improvement status lifecycle |
| See Also | 关联相似信号，发现共性模式 | self-improvement recurring pattern detection |
| Recurrence-Count | 同一模式出现次数，≥3 触发自动提升 | self-improvement recurring pattern + Skill Extraction Criteria |
| Pattern-Key | 稳定去重键，跨 agent 匹配同一模式 | self-improvement Pattern-Key |

## 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 验证机制（融合 self-improvement Recurrence-Count + Skill Extraction Criteria）

从 draft → active 的验证标准：

| 验证维度 | 标准 | 不通过的处理 |
|---------|------|------------|
| Recurrence-Count ≥ 2 | 同一 Pattern-Key 在 ≥2 个不同场景出现过 | 降级为 MEMORY.md 临时记录 |
| 有生成力 | 能给出具体的操作指引 | 丢弃 |
| 有排他性 | 不是「代码要测试」的常识 | 丢弃 |

**提升触发条件**（从 draft 提升为 active Skill，融合 self-improvement Skill Extraction Criteria）：

全部满足时触发提升：
- Recurrence-Count ≥ 3（同一模式 30 天内出现 3 次以上）
- 跨 ≥2 个不同任务验证

**时间窗口**：Recurrence-Count 以 30 天为窗口，超过 30 天的记录不计入。6 个月内 3 次 vs 1 周内 3 次信号强度不同，30 天窗口确保经验仍然新鲜。

**Skill Extraction 质量 Gate**（汲取自 self-improvement skill）：

| 标准 | 描述 |
|------|------|
| Recurring | 有 See Also 链接到 2+ 个相似信号 |
| Verified | Status 是 resolved 且有工作修复 |
| Non-obvious | 需要实际调试才能发现（不是常识） |
| Broadly applicable | 不是项目特定，可跨场景复用 |

### 6.5 质量检查自动化

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

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

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

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

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

### 6.7 蒸馏者（双层）

**L1：每个 agent 自己（每天 03:00 cron，各 agent 错开 15 分钟避免资源争用：03:00, 03:15, 03:30, ...）**
1. 扫描自己的 session JSONL
2. 用判断力提取根因模式（不是机械提取）
3. 按 SKILL.md 格式产出
4. 提交到 skill_workshop（pending proposal）

**L2：庞统（每天 05:00 cron）**
1. 审查所有 agent 提交的 draft proposal（approve / merge / reject）
2. 跨 agent 共性模式识别和合并
3. 高频/高确定性经验提升到 AGENTS.md 规则

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

## 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/ 文件（按需加载）

### 7.4 Skill 存放位置与可见性

agent 专属经验放到 agent 自己的 workspace skills 目录，全局共享 Skill 放到公共 skills 目录。openclaw 扫描时自动合并。

| Skill 位置 | 谁能看到 | 适用场景 |
|-----------|---------|---------|
| `~/.openclaw/workspace-zhangfei/skills/` | 只有张飞 | 编码模式、个人踩坑经验 |
| `~/.openclaw/workspace-pangtong/skills/` | 只有庞统 | 规划经验、方向把控 |
| `~/.openclaw/workspace-simayi/skills/` | 只有司马懿 | 审查技巧、挑战模式 |
| `~/.sanguo_projects/sanguo_mozi/skills/` | 所有 moziplus agent | 团队共识、协作规范、通用实践 |

**设计原则**：
- 个人经验不污染其他 agent 上下文（张飞的编码坑不需要司马懿看到）
- 共性经验自动共享（庞统 MERGE 后放到公共目录）
- openclaw 原生机制天然支持（扫描时合并所有 skills 目录）

## 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 L2 的输入。

## 9. 闭环全景

```
DISCOVER L1（每天 03:00，各 agent cron）
  数据源：自己的 session JSONL
  信号识别：5 类高价值信号
  输出：draft skill proposal（structured，带 ID/Priority/Pattern-Key/Recurrence-Count）
  ↓
DISCOVER L2（每天 05:00，庞统 cron）
  数据源：全量 12 个数据源（含 L1 draft proposals）
  跨 agent 共性模式识别
  审查 draft proposals：approve / merge / reject
  ↓
DISTILL（L2 庞统执行）
  原则：HOW not WHAT（根因模式，不固化技术细节）
  验证：Recurrence-Count ≥ 2 + 生成力 + 排他性
  提升：Recurrence-Count ≥ 3 → 独立 Skill / AGENTS.md 规则
  质量：自动化检查 + 矛盾保留
  产物：Skill（通过 skill_workshop 管理）
  ↓
APPLY（实时，openclaw skill 机制）
  匹配：description 匹配 → agent read SKILL.md
  执行：agent 按内容执行
  自我修补：使用时发现问题 → 立即 revise proposal
  per-agent 隔离：专属 Skill 在 agent workspace，共享 Skill 在公共目录
  ↓
IMPROVE（每周 cron，庞统执行）
  追踪：scan JSONL 引用信号
  淘汰：30天无引用 → 庞统审查 → quarantine
  提升：高频引用 → 独立 Skill / AGENTS.md 规则 / guardrail
  反馈：知识缺口 → knowledge-gaps.md → 回到 DISCOVER L2
```

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

| 组件 | 处理方式 |
|------|---------|
| `skill_system.py`（SkillRegistry/SkillExecutor） | **标记 deprecated，后续清理。** 死代码，实际不参与 skill 发现/加载 |
| `experience.py`（ExperienceDistiller/ExperienceStore） | **标记 deprecated，后续清理。** 空转代码，experiences 目录全空 |
| `experiences` 表 / `experience_tags` 表（db.py） | **保留表结构但不再写入。** 未来如果需要 DB 查询可以重新启用 |
| ticker.py:336-348 经验蒸馏逻辑 | **移除。** 不再逐任务蒸馏，改为双层 daily cron |
| `skill_workshop` 工具 | **核心使用。** 所有 Skill 生命周期通过它管理 |
| openclaw `<available_skills>` 机制 | **核心依赖。** APPLY 阶段完全基于此 |
| **self-improvement skill**（`~/.openclaw/workspace/skills/self-improving-agent/`） | **废弃。** 其优势（结构化 ID/Status/Priority/See Also/Recurrence-Count）已融合到 DISCOVER 输出格式中。原 skill 文件保留但标记 deprecated |
| **.learnings/ 目录**（各 agent workspace） | **废弃。** JSONL 是唯一数据源。目录保留但不再写入新内容（历史数据保留） |
| **SELF_IMPROVEMENT_REMINDER.md** | **废弃。** 规则已融合到 skill-management skill 中 |

## 11. 实现计划

| 步骤 | 内容 | 优先级 | 工作量 |
|------|------|--------|--------|
| S1 | 在 SOUL.md / AGENTS.md 加入 Skill 自我修补规则 + 双层 daily 蒸馏规则 | P0 | L1（改文案） |
| S2 | 创建 skill-management Skill（主 SKILL.md + references/ 四阶段详细操作） | P0 | L2 |
| S3 | 创建各 agent 的 03:00 cron（自蒸馏 L1） | P1 | L1 |
| S4 | 创建庞统的 05:00 cron（整合 + 审查 L2） | P1 | L1-L2 |
| S5 | 实现 IMPROVE cron：JSONL 引用追踪 + 淘汰报告（每周） | P2 | L2-L3 |
| S6 | 清理 deprecated 代码（skill_system.py / experience.py / self-improvement skill / SELF_IMPROVEMENT_REMINDER.md） | 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 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 轮验证，不无限打磨 |
| **双层 daily 蒸馏** | self-improvement skill daily review | 有距离感的蒸馏优于即时记录 |
| **结构化信号格式** | self-improvement skill logging format | ID/Status/Priority/See Also/Recurrence-Count |
| **Recurrence-Count 验证** | self-improvement skill recurring pattern detection | ≥3 次自动触发提升，比主观判断更客观 |
| **Skill Extraction Criteria** | self-improvement skill extraction | Recurring + Verified + Non-obvious + Broadly applicable |
| **per-agent Skill 目录** | Hermes skill_manage + self-improving-agent practice §5 | 每个 agent 建立自己的 Skill 库 |
| **废弃 .learnings/** | DISCOVER 统一采集 | JSONL 是唯一数据源，避免信息冗余 |
| **组合模式（主 skill + references）** | moziplus skill-engineering practices §4 | Skill 之间通过产出物松耦合传递 |

## 13. 部署目录结构

### 13.1 openclaw skill 加载优先级

OpenClaw 按 6 级优先级扫描 skill 目录，同名 skill 高优先级覆盖低优先级：

| 优先级 | 来源 | 路径 | 可见性 |
|--------|------|------|--------|
| 1 — 最高 | Workspace skills | `<workspace>/skills` | 只对该 agent |
| 2 | Project agent skills | `<workspace>/.agents/skills` | 只对该 workspace 的 agent |
| 3 | Personal agent skills | `~/.agents/skills` | 所有 agent |
| 4 | Managed / local skills | `~/.openclaw/skills` | 所有 agent |
| 5 | Bundled skills | 随安装包（`/opt/homebrew/.../openclaw/skills/`） | 所有 agent |
| 6 — 最低 | Extra dirs + plugin skills | `skills.load.extraDirs` + `~/.openclaw/plugin-skills/` | 所有 agent |

### 13.2 skill-management Skill 目录结构

放在公共目录（`~/.sanguo_projects/sanguo_mozi/skills/`），所有 moziplus agent 可见：

```
~/.sanguo_projects/sanguo_mozi/skills/skill-management/
├── SKILL.md                    # 主 Skill：综述 + 核心原则 + 各阶段职责摘要
├── references/
│   ├── discover-l1.md          # L1 各 agent 自蒸馏详细操作（03:00 cron 读这个）
│   ├── discover-l2.md          # L2 庞统整合详细操作（05:00 cron 读这个）
│   ├── distill.md              # DISTILL 阶段详细操作（蒸馏规范 + 验证标准）
│   ├── apply.md                # APPLY 阶段说明（openclaw 原生机制，简短）
│   └── improve.md              # IMPROVE 阶段详细操作（引用追踪 + 淘汰 + 提升）
└── assets/
    ├── templates/
    │   ├── skill-template.md   # SKILL.md 标准模板
    │   └── signal-format.md    # 信号输出格式模板（ID/Priority/Pattern-Key）
    └── checklists/
        └── quality-check.md    # 质量检查清单
```

**为什么放公共目录**：所有 agent 都需要触发这个 skill（DISCOVER L1 时各 agent 按 description 匹配 → read SKILL.md → 再按需 read references/）。DISCOVER/IMPROVE 是 cron 场景，cron payload 中直接指定 `read references/xxx.md` 按内容执行。

**为什么不拆分为独立 skill**：5 个 skill = 5 条 description 常驻上下文（~500-800 token）。其中 DISCOVER 和 IMPROVE 是 cron 触发不是 agent 按描述触发，不需要常驻 description。用 references/ 按需加载更省上下文。

### 13.3 Cron 产出流转路径

```
L1 产出（各 agent 03:00）
  ↓ skill_workshop create（pending proposal）
  ↓ 存储：skill_workshop 内部管理（~/.openclaw/workspace-<agent>/.skill-workshop/）
  ↓
L2 审查（庞统 05:00）
  ↓ skill_workshop list → inspect → 决策
  ↓
  ├─ APPROVE（个人经验，质量达标）
  │   → skill_workshop apply
  │   → 写入：~/.openclaw/workspace-<agent>/skills/<skill-name>/SKILL.md
  │   → 仅该 agent 可见（workspace skill，优先级 1）
  │
  ├─ MERGE（跨 agent 共性）
  │   → 合并多个 proposal 为共享 Skill
  │   → skill_workshop apply 到庞统 workspace，然后 cp/symlink 到公共目录
  │   → 写入：~/.sanguo_projects/sanguo_mozi/skills/<skill-name>/SKILL.md
  │   → 所有 agent 可见（extra dir，优先级 6）
  │   → 清理：MERGE 后通知各 agent quarantine workspace 中的同名 draft
  │
  │   ⚠️ skill_workshop 只能写 workspace skills，不能写 extraDir。
  │   MERGE 流程的实际写入方式：庞统在 workspace apply 后，
  │   手动 cp 到公共目录（或配置 skills.load.allowSymlinkTargets 用 symlink）。
  │
  ├─ REJECT（质量不够）
  │   → skill_workshop reject（附原因）
  │   → agent 在下次 L1 蒸馏时看到反馈
  │
  └─ PROMOTE（高确定性，提升为确定性规则）
      → 手动写入 AGENTS.md / SOUL.md / TOOLS.md
      → 所有 agent 强制注入（L1 确定性规则层）
```

**关键设计**：APPROVE 写入 per-agent workspace（优先级 1，最高），MERGE 写入公共目录（优先级 6，最低）。如果同名 skill 在两边都有，workspace 版本覆盖公共版本——agent 可以有自己改进过的版本。

### 13.4 Per-agent Skill 目录

各 agent workspace 下的 skills 目录（目前不存在，L2 审查 APPROVE 后由 skill_workshop 自动创建）：

```
~/.openclaw/workspace-zhangfei/skills/    # 张飞的个人经验 Skill
~/.openclaw/workspace-guanyu/skills/       # 关羽的个人经验 Skill
~/.openclaw/workspace-zhaoyun/skills/      # 赵云的个人经验 Skill
~/.openclaw/workspace-simayi/skills/       # 司马懿的个人经验 Skill
~/.openclaw/workspace-pangtong/skills/     # 庞统的个人经验 Skill
~/.openclaw/workspace-jiangwei/skills/     # 姜维的个人经验 Skill
```

**适用场景**：
- 张飞的编码踩坑模式 → 只有张飞需要，不污染其他 agent 上下文
- 司马懿的审查技巧 → 只有司马懿需要
- 庞统的规划经验 → 只有庞统需要

### 13.5 Proposal 中间产物存储

```
~/.openclaw/workspace-<agent>/.skill-workshop/
├── proposals/
│   ├── <proposal-id>/
│   │   ├── PROPOSAL.md          # 草案内容
│   │   ├── metadata.json        # 状态、hash、scanner state
│   │   └── support-files/       # 附带的 references/assets
│   └── ...
├── applied/                      # 已 apply 的 proposal 归档
├── rejected/                     # 已 reject 的 proposal 归档
└── quarantined/                  # 已 quarantine 的 proposal 归档
```

**注意**：proposal 存储由 skill_workshop 内部管理，不需要手动操作。首次使用 skill_workshop 时自动创建 `.skill-workshop/` 目录。庞统 L2 cron 通过 `skill_workshop list`（查看所有 agent 的 pending proposal）+ `skill_workshop inspect`（查看具体内容）+ `skill_workshop apply/reject/quarantine`（执行决策）完成审查。

### 13.6 全景目录结构

```
# ━━━━━━━ Skill 来源（按 openclaw 优先级） ━━━━━━━━

# P1: Per-agent workspace skills（个人经验，L2 APPROVE 后写入）
~/.openclaw/workspace-<agent>/skills/<skill-name>/SKILL.md

# P4: Managed / local skills（保留，目前为空）
~/.openclaw/skills/

# P5: Bundled skills（openclaw 自带，不动）
/opt/homebrew/lib/node_modules/openclaw/skills/

# P6: Extra dirs + plugin skills
~/.sanguo_projects/sanguo_mozi/skills/          # moziplus 团队共享 Skill
├── skill-management/                           # ← §19 核心 Skill
│   ├── SKILL.md
│   ├── references/{discover-l1, discover-l2, distill, apply, improve}.md
│   └── assets/{templates, checklists}/
├── blackboard-executor/                        # 现有
├── blackboard-reviewer/                        # 现有
├── trial-and-error-patterns/                   # 现有（经验会追加到这里）
└── ...（其他现有 skill）

~/.openclaw/plugin-skills/                      # plugin Skill（feishu 等）

# ━━━━━━━ Cron 产出流转 ━━━━━━━━

# L1（03:00 各 agent）
#   输入：~/.openclaw/agents/<agent_id>/sessions/*.jsonl
#   产出：skill_workshop create → proposal（pending）
#   存储：~/.openclaw/workspace-<agent>/.skill-workshop/proposals/

# L2（05:00 庞统）
#   输入：全量数据源 + 所有 pending proposals
#   审查：skill_workshop list → inspect → apply/merge/reject
#   产出：
#     APPROVE → ~/.openclaw/workspace-<agent>/skills/<skill-name>/（per-agent）
#     MERGE   → ~/.sanguo_projects/sanguo_mozi/skills/<skill-name>/（共享）
#     REJECT  → proposal 归档到 rejected/
#     PROMOTE → 手动写入 AGENTS.md / SOUL.md / TOOLS.md

# IMPROVE（每周 庞统）
#   输入：过去 7 天所有 agent 的 session JSONL
#   产出：淘汰候选报告 → skill_workshop quarantine

# ━━━━━━━ 废弃的目录（保留历史，不再写入） ━━━━━━━━

# .learnings/ — 不再写入
~/.openclaw/workspace-*/.learnings/

# self-improvement skill — 不再激活
~/.openclaw/workspace/skills/self-improving-agent/

# SELF_IMPROVEMENT_REMINDER.md — 废弃
# 规则已融合到 skill-management skill 中
```