Compare commits
16 Commits
| Author | SHA1 | Date | |
|---|---|---|---|
| 49d0b3a789 | |||
| 5505ac9c5c | |||
| f5bf671410 | |||
| ccb5d5d3ea | |||
| ee825db818 | |||
| cdf984aa0c | |||
| 6798f098b5 | |||
| 33e38254c1 | |||
| 166172e0b8 | |||
| 0bd1caff90 | |||
| f615326514 | |||
| c2c6c9a7f6 | |||
| f26de6cfda | |||
| 1ff4d98a03 | |||
| a953fc0bc7 | |||
| 7f17ee69d7 |
@@ -26,6 +26,7 @@ jobs:
|
||||
|
||||
- name: Setup Python
|
||||
run: |
|
||||
rm -rf /tmp/ci-venv-lint
|
||||
python3 -m venv /tmp/ci-venv-lint
|
||||
/tmp/ci-venv-lint/bin/pip install --quiet --upgrade pip
|
||||
/tmp/ci-venv-lint/bin/pip install --quiet flake8
|
||||
|
||||
@@ -0,0 +1,808 @@
|
||||
# §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 已完成(PR #85)。S3-S5 设计见下方 §11A。
|
||||
|
||||
## 11A. Cron 配置方案(S3-S5 详细设计)
|
||||
|
||||
### 设计决策
|
||||
|
||||
**每个 agent 用自己的 agentId 执行 L1 cron**,不由庞统代理。
|
||||
|
||||
理由(对照设计目标 D4):
|
||||
- L1 核心价值是"每个 agent 是自己经验的最佳蒸馏者"——agent 扫描自己的 JSONL,用自己的判断力识别信号
|
||||
- 如果庞统代理,变成庞统替别人蒸馏,消除不了蒸馏者偏差(D4 要解决的正是这个问题)
|
||||
- openclaw cron 原生支持 `agentId` 参数 + `sessionTarget: "isolated"`,技术上无障碍
|
||||
|
||||
### S3: L1 各 agent 自蒸馏 cron
|
||||
|
||||
6 个 agent,各创建一个 isolated cron,错开 15 分钟(和 discover-l1.md 时间表一致):
|
||||
|
||||
| Agent | agentId | cron 表达式 | 时区 |
|
||||
|-------|---------|-----------|------|
|
||||
| 张飞 | zhangfei-dev | `0 3 * * *` | Asia/Shanghai |
|
||||
| 关羽 | guanyu-dev | `15 3 * * *` | Asia/Shanghai |
|
||||
| 赵云 | zhaoyun-data | `30 3 * * *` | Asia/Shanghai |
|
||||
| 司马懿 | simayi-challenger | `45 3 * * *` | Asia/Shanghai |
|
||||
| 庞统 | pangtong-fujunshi | `0 4 * * *` | Asia/Shanghai |
|
||||
| 姜维 | jiangwei-infra | `15 4 * * *` | Asia/Shanghai |
|
||||
|
||||
**Cron 配置规范**(每个 L1 cron job):
|
||||
|
||||
```json
|
||||
{
|
||||
"schedule": { "kind": "cron", "expr": "<时间>", "tz": "Asia/Shanghai" },
|
||||
"sessionTarget": "isolated",
|
||||
"agentId": "<agent-id>",
|
||||
"payload": {
|
||||
"kind": "agentTurn",
|
||||
"message": "L1 自蒸馏 cron。请执行:\n1. read ~/.sanguo_projects/sanguo_mozi/skills/skill-management/SKILL.md\n2. read ~/.sanguo_projects/sanguo_mozi/skills/skill-management/references/discover-l1.md\n3. 按 discover-l1.md 步骤执行自蒸馏\n4. 如有信号:蒸馏为 HOW 格式,使用 skill_workshop(action=create) 提交 draft proposal\n5. 如无有价值信号:不产出,这是正常的",
|
||||
"timeoutSeconds": 600
|
||||
},
|
||||
"delivery": { "mode": "none" }
|
||||
}
|
||||
```
|
||||
|
||||
**设计要点**:
|
||||
- `sessionTarget: "isolated"`:每次创建临时 session,不污染 main session context
|
||||
- `delivery.mode: "none"`:L1 不需要通知任何人,proposal 存在 skill_workshop 中即可
|
||||
- `timeoutSeconds: 600`:10 分钟足够(扫描 JSONL + 蒸馏 + 提交 proposal)
|
||||
- message 指引 read SKILL.md + discover-l1.md:agent 按 references 指南执行,不依赖 memory
|
||||
|
||||
### S4: L2 庞统整合审查 cron
|
||||
|
||||
庞统的 L2 cron 在所有 L1 完成后执行(最后一个 agent 04:15 开始,L2 设在 05:00):
|
||||
|
||||
| 角色 | agentId | cron 表达式 | 时区 |
|
||||
|------|---------|-----------|------|
|
||||
| 庞统 | pangtong-fujunshi | `0 5 * * *` | Asia/Shanghai |
|
||||
|
||||
**Cron 配置**:
|
||||
|
||||
```json
|
||||
{
|
||||
"schedule": { "kind": "cron", "expr": "0 5 * * *", "tz": "Asia/Shanghai" },
|
||||
"sessionTarget": "isolated",
|
||||
"agentId": "pangtong-fujunshi",
|
||||
"payload": {
|
||||
"kind": "agentTurn",
|
||||
"message": "L2 整合审查 cron。请执行:\n1. read ~/.sanguo_projects/sanguo_mozi/skills/skill-management/references/discover-l2.md\n2. 按 discover-l2.md 步骤执行:\n a. skill_workshop(action=list, status=pending) 获取所有 L1 draft proposals\n b. 全量数据源扫描,识别跨 agent 共性模式\n c. 逐个审查 proposal:approve / merge / reject\n d. 全局提升检查(Recurrence-Count >= 3 的经验提升为规则)\n e. 知识缺口反馈到 knowledge-gaps.md",
|
||||
"timeoutSeconds": 1200
|
||||
},
|
||||
"delivery": { "mode": "none" }
|
||||
}
|
||||
```
|
||||
|
||||
**设计要点**:
|
||||
- `timeoutSeconds: 1200`(20 分钟):L2 需要扫描全量数据源 + 审查多个 proposal,时间更长
|
||||
- 庞统可以访问所有 agent 的 JSONL 和 skill_workshop proposals
|
||||
|
||||
### S5: IMPROVE 每周引用追踪 cron
|
||||
|
||||
庞统每周日 06:00 执行引用追踪(周日选活动量最低的时段):
|
||||
|
||||
| 角色 | agentId | cron 表达式 | 时区 |
|
||||
|------|---------|-----------|------|
|
||||
| 庞统 | pangtong-fujunshi | `0 6 * * 0` | Asia/Shanghai |
|
||||
|
||||
**Cron 配置**:
|
||||
|
||||
```json
|
||||
{
|
||||
"schedule": { "kind": "cron", "expr": "0 6 * * 0", "tz": "Asia/Shanghai" },
|
||||
"sessionTarget": "isolated",
|
||||
"agentId": "pangtong-fujunshi",
|
||||
"payload": {
|
||||
"kind": "agentTurn",
|
||||
"message": "IMPROVE 每周引用追踪 cron。请执行:\n1. read ~/.sanguo_projects/sanguo_mozi/skills/skill-management/references/improve.md\n2. 按 improve.md 步骤执行:\n a. 扫描过去 7 天所有 agent 的 session JSONL,采集 Skill 引用信号\n b. 生成淘汰候选报告(30 天无引用的 Skill)\n c. 庞统审阅决策:quarantine / 保留观察 / 更新后保留\n d. 经验提升检查(被频繁引用 >= 5 次的 Skill)\n e. 反馈知识缺口到 knowledge-gaps.md",
|
||||
"timeoutSeconds": 1800
|
||||
},
|
||||
"delivery": { "mode": "none" }
|
||||
}
|
||||
```
|
||||
|
||||
**设计要点**:
|
||||
- `timeoutSeconds: 1800`(30 分钟):全量 JSONL 扫描是最重的操作
|
||||
- 每周一次频率足够——Skill 引用变化不会很快
|
||||
- 淘汰决策通过 skill_workshop quarantine 执行,提升决策通过手动编辑 AGENTS.md
|
||||
|
||||
### Cron 创建方式
|
||||
|
||||
使用 openclaw cron 工具创建。**不是 moziplus 管理**,而是直接在 openclaw 层面配置。
|
||||
|
||||
创建顺序:先 S3(L1),再 S4(L2),最后 S5(IMPROVE)。
|
||||
|
||||
创建后验证:`cron(action=list)` 确认所有 job 存在且 enabled=true。
|
||||
|
||||
### 去重和幂等
|
||||
|
||||
每个 cron job 的 name 包含 agent 名,避免命名冲突:
|
||||
- `l1-distill-zhangfei`
|
||||
- `l1-distill-guanyu`
|
||||
- `l1-distill-zhaoyun`
|
||||
- `l1-distill-simayi`
|
||||
- `l1-distill-pangtong`
|
||||
- `l1-distill-jiangwei`
|
||||
- `l2-review-pangtong`
|
||||
- `improve-weekly-pangtong`
|
||||
|
||||
创建前先 `cron(action=list)` 检查同名 job 是否已存在,避免重复创建。
|
||||
|
||||
## 11B. 一致性偏差修复清单(S6 补充)
|
||||
|
||||
§19 设计-实现一致性检查(2026-06-18)发现以下偏差,列入 S6 一并修复:
|
||||
|
||||
| # | 偏差 | 严重度 | 修复方式 |
|
||||
|---|------|--------|--------|
|
||||
| B4 | ticker.py:336-348 ExperienceDistiller 调用未移除 | 中 | 移除 experience_distiller 参数和调用,日志改为 debug 级空转提示 |
|
||||
| B5 | skill_system.py / experience.py 未标记 deprecated | 低 | 文件头部加 `# DEPRECATED — §19 重设计,不再参与 skill 发现/加载` 注释 |
|
||||
| B6 | SELF_IMPROVEMENT_REMINDER.md 引用残留 | 低 | AGENTS.md 中已标注废弃,但 system prompt 仍注入。从 workspace 文件列表中移除该文件 |
|
||||
|
||||
**B4 修复细节**:
|
||||
|
||||
ticker.py 构造函数 `__init__` 接受 `experience_distiller` 参数(默认 None),tick() 中第 336-348 行有条件调用。修复方式:
|
||||
- 保留参数(向后兼容),但条件块内加 `logger.debug("ExperienceDistiller deprecated per §19, skipping")` 后直接 return
|
||||
- 不删除代码(P3 级清理时再做物理删除)
|
||||
|
||||
**B6 修复细节**:
|
||||
|
||||
当前 Project Context 中注入了 `SELF_IMPROVEMENT_REMINDER.md` 的内容。该文件在 workspace-pangtong 中已不存在(被删),但 system prompt 模板仍引用它。修复方式:确认文件不存在即可——openclaw 会跳过不存在的注入文件。实际已无影响,标注为 resolved。
|
||||
|
||||
## 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 中
|
||||
```
|
||||
@@ -0,0 +1,66 @@
|
||||
---
|
||||
name: skill-management
|
||||
description: "Use when managing skill lifecycle through the DISCOVER-DISTILL-APPLY-IMPROVE loop, when doing daily experience distillation, or when reviewing/auditing skill proposals."
|
||||
---
|
||||
|
||||
# Skill Management — 经验闭环 + Skill 生命周期
|
||||
|
||||
四阶段闭环:DISCOVER → DISTILL → APPLY → IMPROVE。双层 daily 蒸馏架构。
|
||||
|
||||
## 什么时候用
|
||||
|
||||
- **L1 自蒸馏**(每天 03:00,各 agent):扫描自己的 session JSONL,蒸馏自己的经验 → 提交 draft proposal
|
||||
- **L2 整合审查**(每天 05:00,庞统):扫描全量数据源 + 审查所有 L1 draft → approve/merge/reject
|
||||
- **IMPROVE**(每周,庞统):追踪 Skill 引用情况,淘汰 30 天无引用的 Skill
|
||||
- **自我修补**(实时,任何 agent):使用 Skill 时发现问题 → 立即 revise proposal
|
||||
|
||||
详细操作步骤见 references/ 目录,按当前阶段 `read` 对应文件。
|
||||
|
||||
## 核心原则
|
||||
|
||||
1. **统一产物 Skill-only**:产物只有 Skill(skill_workshop 管理)和 Memory(MEMORY.md),不再有 .learnings/ 等中间形态
|
||||
2. **HOW not WHAT**:蒸馏「怎么做」不是「发生了什么」。描述问题模式,不固化技术细节
|
||||
3. **description = when not how**:Skill 的 description 只描述触发条件,不描述工作流
|
||||
4. **双层蒸馏**:L1 各 agent 自己蒸馏(自己最准);L2 庞统负责跨 agent 共性识别 + 审查
|
||||
5. **矛盾是特征不是 Bug**:保留矛盾,标注类型(时间性/领域性/本质性),不强制调和
|
||||
|
||||
## 四阶段速查
|
||||
|
||||
| 阶段 | 谁 | 何时 | 做什么 | 详细文档 |
|
||||
|------|---|------|--------|---------|
|
||||
| DISCOVER L1 | 每个 agent | 03:00(错开 15min) | 扫描自己 JSONL → 蒸馏 → draft proposal | `references/discover-l1.md` |
|
||||
| DISCOVER L2 | 庞统 | 05:00 | 全量扫描 + 审查 draft → approve/merge/reject | `references/discover-l2.md` |
|
||||
| DISTILL | L1 各 agent + L2 庞统 | 同 DISCOVER | 提取根因模式,按 SKILL.md 格式产出 | `references/distill.md` |
|
||||
| APPLY | openclaw 原生 | 实时 | description 匹配 → read SKILL.md → 执行 | `references/apply.md` |
|
||||
| IMPROVE | 庞统 | 每周 | JSONL 引用追踪 + 淘汰 + 提升 | `references/improve.md` |
|
||||
|
||||
## 验证标准(Recurrence-Count 机制)
|
||||
|
||||
从 draft → active:
|
||||
|
||||
| 维度 | 标准 | 不通过 |
|
||||
|------|------|--------|
|
||||
| Recurrence-Count ≥ 2 | 同一 Pattern-Key 在 ≥2 个场景出现 | 降级为 MEMORY.md |
|
||||
| 有生成力 | 能给出具体操作指引 | 丢弃 |
|
||||
| 有排他性 | 不是常识 | 丢弃 |
|
||||
|
||||
提升触发(全部满足):30 天内 ≥3 次 + 跨 ≥2 个任务。
|
||||
|
||||
## 自我修补规则
|
||||
|
||||
使用 Skill 时发现缺步骤、过时信息、命令变更 → **立即** 通过 skill_workshop 提交 revise proposal。不等定时任务,不等到下次 review。
|
||||
|
||||
## 常见错误
|
||||
|
||||
| 错误 | 后果 | 正确做法 |
|
||||
|------|------|---------|
|
||||
| 蒸馏 WHAT 不 HOW | 经验无法复用 | 描述根因模式 |
|
||||
| description 包含工作流 | Agent 跳过读完整 SKILL.md | description 只描述触发条件 |
|
||||
| 缺少 Recurrence-Count | 偶发问题被固化 | 必须 ≥2 次才提升 |
|
||||
| 强制调和矛盾 | 丢失关键信号 | 保留矛盾,标注类型 |
|
||||
| skill_workshop 写公共目录 | 操作失败 | skill_workshop 只能写 workspace,公共目录用 cp/symlink |
|
||||
|
||||
## 来源
|
||||
|
||||
- 设计文档:`docs/design/19-skill-lifecycle-and-experience-loop.md` v2.0
|
||||
- 参考实践:Hermes skill_manage、nuwa-skill、Superpowers writing-skills、self-improvement skill
|
||||
@@ -0,0 +1,36 @@
|
||||
---
|
||||
name: quality-check
|
||||
description: "Skill 蒸馏产出质量检查清单"
|
||||
---
|
||||
|
||||
# 质量检查清单
|
||||
|
||||
蒸馏产出提交前,逐条检查:
|
||||
|
||||
## 结构检查
|
||||
|
||||
- [ ] frontmatter 有 name 和 description
|
||||
- [ ] description 以「Use when...」开头
|
||||
- [ ] description 只含触发条件,不含工作流
|
||||
- [ ] 有「什么时候用」章节
|
||||
- [ ] 有「怎么做」章节
|
||||
- [ ] 有「常见错误」章节
|
||||
- [ ] 有「来源」章节
|
||||
|
||||
## 内容检查
|
||||
|
||||
- [ ] trigger 是否具体(不是「注意代码质量」这种泛泛而谈)
|
||||
- [ ] action 是否可执行(不是「要小心」这种无操作指引)
|
||||
- [ ] 蒸馏的是 HOW 不是 WHAT(根因模式,不是事件描述)
|
||||
- [ ] 没有项目特定的硬编码值
|
||||
|
||||
## 验证检查
|
||||
|
||||
- [ ] Recurrence-Count ≥ 2(同一模式在 ≥2 个场景出现)
|
||||
- [ ] 有生成力(能给出具体操作指引)
|
||||
- [ ] 有排他性(不是常识)
|
||||
|
||||
## 重复检查
|
||||
|
||||
- [ ] 检查现有 skills 目录中是否已有覆盖
|
||||
- [ ] 如果是对已有 Skill 的增量更新,使用 revise 而非 create
|
||||
@@ -0,0 +1,39 @@
|
||||
---
|
||||
name: signal-format
|
||||
description: "DISCOVER 阶段信号输出格式模板"
|
||||
---
|
||||
|
||||
# 信号输出格式
|
||||
|
||||
每条候选信号包含:
|
||||
|
||||
```
|
||||
信号类型 | 来源(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(稳定去重键)
|
||||
```
|
||||
|
||||
## 字段说明
|
||||
|
||||
| 字段 | 用途 | 示例 |
|
||||
|------|------|------|
|
||||
| ID | 唯一标识,便于交叉引用 | SIG-20260618-001 |
|
||||
| Priority | 优先级排序 | critical: 阻断核心功能; high: 影响常见流程; medium: 有 workaround; low: 边缘场景 |
|
||||
| Status | 生命周期跟踪 | pending → in_progress → resolved / promoted |
|
||||
| See Also | 关联相似信号,发现共性模式 | SIG-20260617-003 |
|
||||
| Recurrence-Count | 同一模式出现次数,≥3 触发自动提升 | 2 |
|
||||
| Pattern-Key | 稳定去重键,跨 agent 匹配同一模式 | sync.field_mapping |
|
||||
|
||||
## 信号类型(5 类)
|
||||
|
||||
| 类型 | 识别特征 |
|
||||
|------|---------|
|
||||
| 失败模式 | 有明确的失败原因 + 排查过程 |
|
||||
| 重复问题 | 同关键词出现 ≥2 次 |
|
||||
| 决策转折 | 原方向被推翻或修正 |
|
||||
| 新实践 | 之前没有的知识 |
|
||||
| 知识缺口 | 查不到/不确定的东西 |
|
||||
@@ -0,0 +1,51 @@
|
||||
---
|
||||
name: skill-template
|
||||
description: "SKILL.md 标准模板 — 蒸馏产出时按此格式编写"
|
||||
---
|
||||
|
||||
# Skill 标准模板
|
||||
|
||||
```yaml
|
||||
---
|
||||
name: <skill-name>
|
||||
description: "Use when <触发条件/问题模式描述>"
|
||||
---
|
||||
|
||||
# <Skill 标题>
|
||||
|
||||
## 什么时候用
|
||||
<具体的触发场景,按问题模式描述,不按技术特定症状>
|
||||
|
||||
## 怎么做
|
||||
<根因分析 + 操作步骤>
|
||||
|
||||
1. <步骤 1>
|
||||
2. <步骤 2>
|
||||
3. <步骤 3>
|
||||
|
||||
## 常见错误
|
||||
<反模式:什么不该做>
|
||||
|
||||
- ❌ <错误做法> → <后果>
|
||||
- ❌ <错误做法> → <后果>
|
||||
|
||||
## 来源
|
||||
<evidence:哪些 task/PR/review 提炼了这条经验>
|
||||
|
||||
- task <id>: <简述>
|
||||
- PR #<num>: <简述>
|
||||
```
|
||||
|
||||
## description 编写要点
|
||||
|
||||
- 以「Use when...」开头
|
||||
- 只描述触发条件(when),**不描述工作流**(how)
|
||||
- 描述问题模式,不描述技术特定症状
|
||||
- 控制在 1-2 句话
|
||||
|
||||
## 质量自检
|
||||
|
||||
- [ ] trigger 是否具体(不是「注意代码质量」)
|
||||
- [ ] action 是否可执行(不是「要小心」)
|
||||
- [ ] 是否与已有 Skill 重复
|
||||
- [ ] description 是否只含触发条件
|
||||
@@ -0,0 +1,34 @@
|
||||
# APPLY — Skill 应用阶段
|
||||
|
||||
## 机制
|
||||
|
||||
APPLY 完全基于 openclaw 原生 skill 机制,不需要额外代码:
|
||||
|
||||
1. openclaw 扫描 skills 目录 → 生成 `<available_skills>` 列表(只有 name + description)
|
||||
2. Agent 按 description 匹配 → `read` SKILL.md 完整内容
|
||||
3. Agent 按内容执行
|
||||
|
||||
## 渐进式加载
|
||||
|
||||
- L1:`<available_skills>` 列表(~100 token/skill)— 每次启动注入
|
||||
- L2:Agent `read` SKILL.md — 按需加载
|
||||
- L3:SKILL.md 内引用的 references/ 文件 — 按需加载
|
||||
|
||||
## Skill 存放位置与可见性
|
||||
|
||||
| 位置 | 可见性 | 优先级 |
|
||||
|------|--------|--------|
|
||||
| `~/.openclaw/workspace-<agent>/skills/` | 仅该 agent | 1(最高) |
|
||||
| `~/.sanguo_projects/sanguo_mozi/skills/` | 所有 moziplus agent | 6(最低) |
|
||||
|
||||
workspace 版本覆盖公共版本——agent 可以有自己改进过的版本。
|
||||
|
||||
## 自我修补
|
||||
|
||||
使用 Skill 时发现问题(缺步骤、过时信息、命令变更)→ **立即** 通过 skill_workshop 提交 revise proposal:
|
||||
|
||||
```python
|
||||
skill_workshop(action="revise", proposal_id="<id>", proposal_content="<修改后的内容>")
|
||||
```
|
||||
|
||||
不等定时任务,不等到下次 review。
|
||||
@@ -0,0 +1,84 @@
|
||||
# DISCOVER L1 — 各 agent 自蒸馏(每天 03:00)
|
||||
|
||||
## 你是谁
|
||||
|
||||
你是某个 agent(张飞/关羽/赵云/司马懿/庞统/姜维),在每天 03:00 被 cron 唤醒,执行自己的经验蒸馏。
|
||||
|
||||
## cron 错开时间
|
||||
|
||||
各 agent 错开 15 分钟避免资源争用:
|
||||
|
||||
| Agent | 时间 |
|
||||
|-------|------|
|
||||
| zhangfei-dev | 03:00 |
|
||||
| guanyu-dev | 03:15 |
|
||||
| zhaoyun-data | 03:30 |
|
||||
| simayi-challenger | 03:45 |
|
||||
| pangtong-fujunshi | 04:00 |
|
||||
| jiangwei-infra | 04:15 |
|
||||
|
||||
## 操作步骤
|
||||
|
||||
### Step 1: 扫描当天 session JSONL
|
||||
|
||||
```
|
||||
输入:~/.openclaw/agents/<your-agent-id>/sessions/*.jsonl
|
||||
时间范围:过去 24 小时(上次 L1 到现在)
|
||||
```
|
||||
|
||||
重点扫描以下内容:
|
||||
- `"tool":"exec"` 失败的命令(exit code 非 0)
|
||||
- `"role":"user"` 消息中的纠正(「不对」「错了」「应该是」等)
|
||||
- `"role":"assistant"` 中的反复返工(同一文件改了 3 次以上)
|
||||
- task status 变更为 failed 的事件
|
||||
- review verdict 为 REQUEST_CHANGES 的记录
|
||||
|
||||
### Step 2: 信号识别(5 类高价值信号)
|
||||
|
||||
| 信号类型 | 识别特征 | 示例 |
|
||||
|---------|---------|------|
|
||||
| 失败模式 | 有明确的失败原因 + 排查过程 | 命令报错、CI 失败、review 驳回 |
|
||||
| 重复问题 | 同关键词在当天出现 ≥2 次 | 反复修改同一段代码、同类错误 |
|
||||
| 决策转折 | 原方向被推翻或修正 | 主公纠正、需求澄清、rebuttal |
|
||||
| 新实践 | 之前没有的知识 | 新工具用法、新架构模式 |
|
||||
| 知识缺口 | 表达不确定、查不到 | 「不确定」「没找到」「推测」 |
|
||||
|
||||
### Step 3: 蒸馏(HOW not WHAT)
|
||||
|
||||
对每个信号,提取根因模式,不是事件描述:
|
||||
|
||||
```
|
||||
❌ "PR #83 修复了 event_type 未知的问题"(WHAT,无法复用)
|
||||
✅ "消费者/生产者字段同步:新增 dataclass 字段时,必须同步所有从 JSON 提取该字段的代码路径"(HOW,可复用)
|
||||
```
|
||||
|
||||
蒸馏规范详见 `references/distill.md`。
|
||||
|
||||
### Step 4: 产出 draft proposal
|
||||
|
||||
对蒸馏后的经验,使用 skill_workshop 提交:
|
||||
|
||||
```
|
||||
skill_workshop(action="create", name="<skill-name>", description="Use when <触发条件>", proposal_content="<SKILL.md 内容>")
|
||||
```
|
||||
|
||||
输出格式(每条信号):
|
||||
```
|
||||
信号类型 | 来源(task_id / session)| 时间 | 简述(≤100 字)
|
||||
ID: SIG-YYYYMMDD-XXX
|
||||
Priority: low | medium | high | critical
|
||||
Status: pending
|
||||
Recurrence-Count: N
|
||||
Pattern-Key: category.subcategory(如 sync.field_mapping)
|
||||
```
|
||||
|
||||
### Step 5: 完成
|
||||
|
||||
所有 draft proposal 提交后,L1 结束。不需要等待 L2 审查结果(庞统会在 05:00 处理)。
|
||||
|
||||
## 注意事项
|
||||
|
||||
- 数据源**只有**你自己的 session JSONL,不需要扫描黑板/Gitea/Mail
|
||||
- 如果当天没有有价值的信号(没踩坑、没被纠正、没新发现),不产出任何 proposal,这是正常的
|
||||
- 不要为了产出而强行蒸馏——偶发问题降级为 MEMORY.md,不提交 proposal
|
||||
- 质量优于数量:1 条高质量 proposal 比 5 条流水账有价值
|
||||
@@ -0,0 +1,118 @@
|
||||
# DISCOVER L2 — 庞统整合审查(每天 05:00)
|
||||
|
||||
## 你是谁
|
||||
|
||||
你是庞统,在每天 05:00 被 cron 唤醒,执行跨 agent 整合 + draft proposal 审查。
|
||||
|
||||
前提:所有 agent 的 L1 自蒸馏(03:00-04:15)已完成。
|
||||
|
||||
## 操作步骤
|
||||
|
||||
### Step 1: 获取所有 L1 draft proposals
|
||||
|
||||
```
|
||||
skill_workshop(action="list", status="pending")
|
||||
```
|
||||
|
||||
列出所有 pending 状态的 proposal,检查哪些是今天 L1 产出的。
|
||||
|
||||
### Step 2: 全量数据源扫描
|
||||
|
||||
扫描以下数据源,识别跨 agent 共性模式:
|
||||
|
||||
| 数据源 | 位置 | 关注什么 |
|
||||
|--------|------|---------|
|
||||
| 黑板 tasks | 各项目 blackboard.db | task failed、状态异常 |
|
||||
| 黑板 reviews | reviews 表 | REQUEST_CHANGES verdict + suggestions |
|
||||
| 黑板 comments | comments 表 | rebuttal 讨论、@mention 争议 |
|
||||
| 黑板 events | events 表 | guardrail 拦截、异常检测 |
|
||||
| Gitea Issues/PRs | Gitea API | 新问题、PR review 评论 |
|
||||
| Gitea CI | Gitea Actions | lint/test/build 失败 |
|
||||
| Mail | mail API | 跨 agent 讨论、推理过程 |
|
||||
| 所有 agent JSONL | ~/.openclaw/agents/*/sessions/ | 全团队当天思考过程 |
|
||||
| MEMORY.md | 各 agent workspace | 已有经验教训 |
|
||||
| knowledge-gaps.md | wiki-vault/_meta/ | 知识缺口 |
|
||||
| L1 draft proposals | skill_workshop pending | 各 agent 当天提交 |
|
||||
|
||||
### Step 3: 跨 agent 共性模式识别
|
||||
|
||||
寻找同一 Pattern-Key 在多个 agent 的 JSONL/proposal 中出现的情况:
|
||||
|
||||
```
|
||||
张飞 SIG-20260618-001: Pattern-Key: sync.field_mapping
|
||||
关羽 SIG-20260618-002: Pattern-Key: sync.field_mapping
|
||||
→ 共性信号!Recurrence-Count = 2,可合并为共享 Skill
|
||||
```
|
||||
|
||||
### Step 4: 审查每个 draft proposal
|
||||
|
||||
对每个 L1 draft proposal,逐条审查:
|
||||
|
||||
```
|
||||
skill_workshop(action="inspect", proposal_id="<id>")
|
||||
```
|
||||
|
||||
审查维度:
|
||||
|
||||
| 维度 | 标准 | 不通过 |
|
||||
|------|------|--------|
|
||||
| Recurrence-Count ≥ 2 | 同一 Pattern-Key 在 ≥2 个场景出现 | 降级为 MEMORY.md |
|
||||
| 有生成力 | 能给出具体操作指引 | 丢弃 |
|
||||
| 有排他性 | 不是常识 | 丢弃 |
|
||||
| description 合规 | 只描述触发条件,不含工作流 | 要求 revise |
|
||||
| trigger 具体 | 不是「注意代码质量」 | 要求 revise |
|
||||
|
||||
### Step 5: 执行决策
|
||||
|
||||
对每个 proposal 做出决策:
|
||||
|
||||
**APPROVE**(个人经验,质量达标):
|
||||
```python
|
||||
skill_workshop(action="apply", proposal_id="<id>")
|
||||
# skill_workshop 自动写入 agent workspace: ~/.openclaw/workspace-<agent>/skills/<skill-name>/
|
||||
# 仅该 agent 可见
|
||||
```
|
||||
|
||||
**MERGE**(跨 agent 共性):
|
||||
```python
|
||||
# 1. 在庞统 workspace apply 合并后的版本
|
||||
skill_workshop(action="apply", proposal_id="<id>")
|
||||
# 2. cp 到公共目录(skill_workshop 不能写 extraDir)
|
||||
cp ~/.openclaw/workspace-pangtong/skills/<skill-name>/SKILL.md \
|
||||
~/.sanguo_projects/sanguo_mozi/skills/<skill-name>/SKILL.md
|
||||
# 3. 通知各 agent quarantine workspace 中的同名 draft
|
||||
# 在相关 PR/Issue 中 @agent 说明
|
||||
```
|
||||
|
||||
**REJECT**(质量不够):
|
||||
```python
|
||||
skill_workshop(action="reject", proposal_id="<id>", reason="<具体原因>")
|
||||
# agent 在下次 L1 时看到反馈
|
||||
```
|
||||
|
||||
**PROMOTE**(高确定性经验,提升为规则):
|
||||
```python
|
||||
# 手动写入 AGENTS.md / SOUL.md / TOOLS.md 对应区块
|
||||
# 这不属于 skill_workshop 管理范围
|
||||
```
|
||||
|
||||
### Step 6: 全局提升检查
|
||||
|
||||
检查是否有经验达到提升条件(Recurrence-Count ≥ 3 + 跨 ≥2 任务 + 30 天内):
|
||||
|
||||
| 提升目标 | 条件 | 效果 |
|
||||
|---------|------|------|
|
||||
| 独立 Skill | 足够通用,有自己的触发条件 | 独立 SKILL.md |
|
||||
| AGENTS.md 规则 | 确定性高,适用于所有 agent | L1 强制注入 |
|
||||
| guardrail | 安全相关,不可违反 | 强制检查 |
|
||||
|
||||
### Step 7: 知识缺口反馈
|
||||
|
||||
IMPROVE 发现的经验缺口或 L2 发现的新领域 → 追加到 `knowledge-gaps.md`。
|
||||
|
||||
## 注意事项
|
||||
|
||||
- L2 时间窗口:05:00 执行,确保 L1 全部完成(最后一个 agent 04:15 开始)
|
||||
- 全量扫描不需要逐行读 JSONL,用 grep 定位关键词再精读匹配段
|
||||
- MERGE 后必须清理各 agent workspace 的同名 draft(避免覆盖公共版本)
|
||||
- REJECT 必须附具体原因,帮 agent 改进而非打击
|
||||
@@ -0,0 +1,137 @@
|
||||
# DISTILL — 蒸馏规范
|
||||
|
||||
## 核心原则:HOW not WHAT
|
||||
|
||||
蒸馏的是「怎么做」不是「发生了什么」:
|
||||
|
||||
```
|
||||
❌ "PR #83 修复了 event_type 未知的问题"
|
||||
→ 这是 WHAT,无法复用
|
||||
|
||||
✅ "消费者/生产者字段同步:新增 dataclass 字段时,必须同步所有从 JSON 提取该字段的代码路径"
|
||||
→ 这是 HOW,可复用到任何消费者/生产者场景
|
||||
```
|
||||
|
||||
## SKILL.md 编写规范
|
||||
|
||||
```yaml
|
||||
---
|
||||
name: skill-name
|
||||
description: Use when [触发条件/问题模式描述],不描述工作流
|
||||
---
|
||||
|
||||
# Skill 标题
|
||||
|
||||
## 什么时候用
|
||||
(具体的触发场景,按问题模式描述,不按技术特定症状)
|
||||
|
||||
## 怎么做
|
||||
(根因分析 + 操作步骤)
|
||||
|
||||
## 常见错误
|
||||
(反模式:什么不该做)
|
||||
|
||||
## 来源
|
||||
(evidence:哪些 task/PR/review 提炼了这条经验)
|
||||
```
|
||||
|
||||
## description 关键规则
|
||||
|
||||
- 只描述触发条件(when to use),**绝不描述工作流**(how)
|
||||
- 以「Use when...」开头
|
||||
- 描述问题模式,不描述技术特定症状
|
||||
- 原因:测试发现 description 如果总结了工作流,agent 会按 description 执行而跳过读完整 SKILL.md
|
||||
|
||||
### 示例
|
||||
|
||||
```yaml
|
||||
# ❌ BAD:描述了工作流
|
||||
description: Use when modifying dataclass — checks all extraction points, runs tests
|
||||
|
||||
# ✅ 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
|
||||
```
|
||||
|
||||
## 蒸馏示例
|
||||
|
||||
**一级蒸馏**(从具体案例提取):
|
||||
|
||||
```yaml
|
||||
# 案例 1:PromptContext event_type 未知
|
||||
# 案例 2:PromptContext from_agent/mail_type 缺失(PR #26 D2)
|
||||
→ 共同根因:消费者/生产者字段同步问题
|
||||
|
||||
## 消费者/生产者字段同步
|
||||
|
||||
**什么时候用**:修改 dataclass 时,如果该 dataclass 由外部 JSON 提取填充
|
||||
|
||||
**怎么做**:
|
||||
1. 改 dataclass 定义
|
||||
2. 检查所有从 JSON 提取字段的代码路径,同步新增提取逻辑
|
||||
3. 检查所有构造该 dataclass 的调用点,同步新增参数
|
||||
4. 跑一次构建测试验证字段不为空
|
||||
|
||||
**常见错误**:只改 dataclass 不改提取逻辑 → 字段默认值为空 → 运行时不报错但行为异常
|
||||
```
|
||||
|
||||
**二级蒸馏**(从多个一级经验提取通用模式):
|
||||
|
||||
如果经验在 ≥2 个不同场景复现,验证通过后,可以提升为独立 Skill 或固化到 AGENTS.md 规则。
|
||||
|
||||
## 验证标准
|
||||
|
||||
从 draft → active:
|
||||
|
||||
| 维度 | 标准 | 不通过 |
|
||||
|------|------|--------|
|
||||
| Recurrence-Count ≥ 2 | 同一 Pattern-Key 在 ≥2 个场景出现 | 降级为 MEMORY.md |
|
||||
| 有生成力 | 能给出具体操作指引 | 丢弃 |
|
||||
| 有排他性 | 不是常识 | 丢弃 |
|
||||
|
||||
提升触发(全部满足):30 天内 ≥3 次 + 跨 ≥2 个任务。
|
||||
|
||||
## Skill Extraction 质量 Gate
|
||||
|
||||
| 标准 | 描述 |
|
||||
|------|------|
|
||||
| Recurring | 有 See Also 链接到 2+ 个相似信号 |
|
||||
| Verified | Status 是 resolved 且有工作修复 |
|
||||
| Non-obvious | 需要实际调试才能发现 |
|
||||
| Broadly applicable | 不是项目特定,可跨场景复用 |
|
||||
|
||||
## 质量检查
|
||||
|
||||
| 检查项 | 标准 |
|
||||
|--------|------|
|
||||
| trigger 是否具体 | 不是「注意代码质量」 |
|
||||
| action 是否可执行 | 不是「要小心」 |
|
||||
| 是否与已有 Skill 重复 | 检查现有 skills 目录 |
|
||||
| description 是否只含触发条件 | 不包含工作流描述 |
|
||||
|
||||
## 矛盾处理
|
||||
|
||||
新经验与已有经验冲突时:
|
||||
- **时间性矛盾**(观点演化)→ 记录演化轨迹,以近期为主
|
||||
- **领域性矛盾**(不同场景不同规则)→ 分场景记录
|
||||
- **本质性张力**(价值观内在冲突)→ 标注为「核心张力」,两个版本都保留
|
||||
|
||||
**矛盾是特征,不是 Bug。** 强制调和会丢失关键信号。
|
||||
|
||||
## 信号输出格式
|
||||
|
||||
每条信号包含:
|
||||
```
|
||||
信号类型 | 来源 | 时间 | 简述(≤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
|
||||
```
|
||||
@@ -0,0 +1,70 @@
|
||||
# IMPROVE — 引用追踪 + 淘汰 + 提升(每周 cron)
|
||||
|
||||
## 你是谁
|
||||
|
||||
你是庞统,每周执行一次 IMPROVE cron,扫描过去 7 天的所有 session JSONL。
|
||||
|
||||
## 操作步骤
|
||||
|
||||
### Step 1: 引用追踪
|
||||
|
||||
扫描过去 7 天所有 agent 的 session JSONL,采集 Skill 引用信号:
|
||||
|
||||
| 信号 | 采集方式 | 可信度 |
|
||||
|------|---------|--------|
|
||||
| Skill 被 read 的时间 | grep `"tool":"read"` + SKILL.md 路径 | 中 |
|
||||
| Skill 在 available_skills 中被注入 | grep available_skills 列表 | 中(注入但未必用) |
|
||||
| Agent 输出中提及 skill name | grep skill name in assistant messages | 高 |
|
||||
| Skill 文件最近修改时间 | git log / 文件 mtime | 高 |
|
||||
|
||||
### Step 2: 生成淘汰候选报告
|
||||
|
||||
对每个 Skill 检查最近 30 天的引用信号:
|
||||
|
||||
```
|
||||
30 天无引用信号
|
||||
→ 加入淘汰候选列表
|
||||
```
|
||||
|
||||
输出淘汰候选报告:
|
||||
```
|
||||
| Skill 名称 | 最后引用时间 | 存放位置 | 建议 |
|
||||
|-----------|------------|---------|------|
|
||||
| xxx | 2026-05-15 | 公共目录 | 建议淘汰 |
|
||||
| yyy | 从未被引用 | 张飞 workspace | 建议淘汰 |
|
||||
```
|
||||
|
||||
### Step 3: 庞统审阅决策
|
||||
|
||||
逐条审阅淘汰候选:
|
||||
|
||||
- **确认淘汰** → `skill_workshop(action="quarantine", proposal_id="<id>")`
|
||||
- **保留观察** → 标注,下轮再查
|
||||
- **更新后保留** → 修改 description / 内容,重置计时
|
||||
|
||||
**注意**:openclaw 本身的 skill(~/.openclaw/plugin-skills/ 和全局 skills)也纳入追踪。报告给主公决定是否禁用。
|
||||
|
||||
### Step 4: 经验提升检查
|
||||
|
||||
检查是否有 Skill 达到提升条件(被频繁引用 ≥5 次 + 多次验证):
|
||||
|
||||
| 提升目标 | 条件 | 效果 |
|
||||
|---------|------|------|
|
||||
| 独立 Skill | 足够通用,有自己的触发条件 | 独立 SKILL.md |
|
||||
| AGENTS.md 规则 | 确定性高,适用于所有 agent | L1 强制注入 |
|
||||
| guardrail | 安全相关,不可违反 | 强制检查 |
|
||||
|
||||
### Step 5: 反馈到 DISCOVER
|
||||
|
||||
IMPROVE 发现的经验缺口写入 knowledge-gaps.md:
|
||||
```
|
||||
- [日期] IMPROVE 发现「<skill-name> 不适用 <场景>」→ 待 DISCOVER 处理
|
||||
```
|
||||
|
||||
成为下一轮 DISCOVER L2 的输入。
|
||||
|
||||
## 注意事项
|
||||
|
||||
- 不追求精确归因,做时间维度的信号采集
|
||||
- 淘汰决策由庞统判断,不自动执行
|
||||
- 提升到 AGENTS.md 的规则需要主公确认(影响所有 agent 的确定性注入)
|
||||
@@ -1,3 +1,5 @@
|
||||
# DEPRECATED per §19 重设计 — 经验蒸馏改为双层 daily cron(L1 各 agent + L2 庞统)
|
||||
# 保留代码供参考,后续 P3 清理时物理删除
|
||||
"""Experience Distillation — 经验蒸馏
|
||||
|
||||
从已完成的任务产出中提取经验:
|
||||
|
||||
@@ -1,3 +1,6 @@
|
||||
# DEPRECATED per §19 重设计 — 不再参与 skill 发现/加载
|
||||
# 实际 skill 发现走 openclaw 原生 <available_skills> 机制
|
||||
# 保留代码供参考,后续 P3 清理时物理删除
|
||||
"""Skill System — 技能注册、加载、匹配、执行
|
||||
|
||||
三层自由度:
|
||||
|
||||
@@ -288,6 +288,8 @@ class AgentSpawner:
|
||||
mail_type = ""
|
||||
action_type = ""
|
||||
action_steps = []
|
||||
event_type = ""
|
||||
event_data = {}
|
||||
try:
|
||||
meta = json.loads(must_haves) if must_haves else {}
|
||||
from_agent = meta.get("from", "")
|
||||
@@ -295,6 +297,8 @@ class AgentSpawner:
|
||||
# toolchain 字段提取
|
||||
action_type = meta.get("action_type", "")
|
||||
action_steps = meta.get("steps", [])
|
||||
event_type = meta.get("event_type", "")
|
||||
event_data = meta.get("context", {})
|
||||
except Exception:
|
||||
pass
|
||||
ctx = PromptContext(
|
||||
@@ -304,6 +308,7 @@ class AgentSpawner:
|
||||
spawn_type=spawn_type,
|
||||
from_agent=from_agent, mail_type=mail_type,
|
||||
action_type=action_type, action_steps=action_steps,
|
||||
event_type=event_type, event_data=event_data,
|
||||
)
|
||||
return handler.build_prompt(ctx)
|
||||
|
||||
@@ -1256,7 +1261,7 @@ curl -X POST http://{api_host}:{api_port}/api/projects/{project_id}/tasks/{task_
|
||||
conn = get_connection(db_path)
|
||||
try:
|
||||
row = conn.execute(
|
||||
"SELECT id, title, status FROM tasks WHERE id=?", (
|
||||
"SELECT id, title, status, must_haves FROM tasks WHERE id=?", (
|
||||
task_id,)
|
||||
).fetchone()
|
||||
if not row:
|
||||
|
||||
+3
-18
@@ -332,25 +332,10 @@ class Ticker:
|
||||
except Exception as e:
|
||||
logger.warning("HealthChecker error for %s: %s", project_id, e)
|
||||
|
||||
# 9. 经验蒸馏(完成的 task 自动触发)
|
||||
# 9. 经验蒸馏 — DEPRECATED per §19, 双层 daily cron 替代
|
||||
# 保留参数向后兼容,不再执行逐任务蒸馏
|
||||
if self.experience_distiller:
|
||||
try:
|
||||
conn2 = get_connection(db_path)
|
||||
try:
|
||||
done_tasks = conn2.execute(
|
||||
"SELECT id FROM tasks WHERE status='done' AND updated_at > datetime('now', '-60 seconds')"
|
||||
).fetchall()
|
||||
finally:
|
||||
conn2.close()
|
||||
for row in done_tasks:
|
||||
t = Blackboard(db_path).get_task(row[0])
|
||||
if t:
|
||||
self.experience_distiller.distill_from_task(
|
||||
task_id=t.id, task_title=t.title, task_type=t.task_type
|
||||
)
|
||||
except Exception as e:
|
||||
logger.warning(
|
||||
"ExperienceDistiller error for %s: %s", project_id, e)
|
||||
logger.debug("ExperienceDistiller deprecated per §19, skipping (use L1/L2 daily cron)")
|
||||
|
||||
# 10. 扫描后状态
|
||||
result["summary_after"] = queries.task_summary()
|
||||
|
||||
Reference in New Issue
Block a user