diff --git a/docs/design/19-skill-lifecycle-and-experience-loop.md b/docs/design/19-skill-lifecycle-and-experience-loop.md index 4261ca2..665db21 100644 --- a/docs/design/19-skill-lifecycle-and-experience-loop.md +++ b/docs/design/19-skill-lifecycle-and-experience-loop.md @@ -1,10 +1,22 @@ # §19 Skill 生命周期管理 + 经验闭环四阶段设计 > 作者：庞统士元 -> 日期：2026-06-18 +> 日期：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 剩余两项： @@ -40,6 +52,7 @@ moziplus v2.0 的 P4 剩余两项： 3. 产物统一为 Skill，不再有 experiences.jsonl / .learnings/ 等中间形态散落各处 4. 追踪 Skill 引用情况，支撑淘汰决策 5. 充分利用 openclaw 已有的 skill_workshop 工具和 skill 加载机制 +6. **每个 agent 是自己经验的最佳蒸馏者**——经验 per-agent，精益求精 ## 3. 核心设计决策 @@ -47,9 +60,11 @@ moziplus v2.0 的 P4 剩余两项： |---|------|------|------| | 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 架构务实态） | +| 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 @@ -65,9 +80,37 @@ moziplus v2.0 的 P4 剩余两项： L4 不是一个 prompt 层，而是 Skill 的**管理层**——负责 Skill 的创建、验证、应用、追踪、淘汰。 -## 5. DISCOVER 阶段 +## 5. DISCOVER 阶段（双层） -### 5.1 数据源（全量） +### 5.1 L1 各 agent 自蒸馏（每天 03:00） + +每个 agent 的 cron 扫描**自己当天**的 session JSONL，识别信号，蒸馏为 draft proposal。 + +**数据源（1 个）**： + +| 数据源 | 位置 | 包含什么 | +|--------|------|---------| +| 自己的 Session JSONL | ~/.openclaw/agents//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。 + +**数据源（全量）**： | 数据源 | 位置 | 包含什么 | |--------|------|---------| @@ -79,32 +122,50 @@ L4 不是一个 prompt 层，而是 Skill 的**管理层**——负责 Skill 的 | Gitea Issues/PRs | Gitea API | 问题报告、diff、review 评论 | | Gitea CI | Gitea Actions | lint/test/build 成功/失败 | | Mail | mail API | 跨 agent 通信、讨论推理过程 | -| Session JSONL | ~/.openclaw/agents/*/sessions/ | Agent 完整思考过程、工具调用、错误恢复 | +| **所有 agent 的 Session JSONL** | ~/.openclaw/agents/*/sessions/ | 全团队完整思考过程 | | MEMORY.md | 各 agent workspace | 长期记忆、已有经验教训 | -| .learnings/ | 各 agent workspace | 已记录的学习/错误/特征请求 | | knowledge-gaps.md | wiki-vault/_meta/ | 知识缺口 | +| **L1 draft proposals** | skill_workshop pending | 各 agent 当天提交的 draft | -### 5.2 信号识别（5 类高价值信号） +**核心职责**： -| 信号类型 | 从哪发现 | 识别特征 | -|---------|---------|---------| -| 失败模式 | task failed、CI failed、review rejected | 有明确的失败原因 | -| 重复问题 | 跨多个任务/agent 出现同类问题 | 同关键词出现 ≥2 次 | -| 决策转折 | rebuttal comment、需求澄清、主公纠正 | 原方向被推翻或修正 | -| 新实践 | 设计文档新增、wiki-vault 新页面 | 之前没有的知识 | -| 知识缺口 | knowledge-gaps.md、agent 表达不确定 | 查不到/不确定的东西 | +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 讨论），按时间窗口 + 关键词去重，保留信息量最大的那条。 -### 5.4 输出 +跨 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 @@ -177,18 +238,35 @@ description: Use when [触发条件/问题模式描述]，不描述工作流 **二级蒸馏**（从多个一级经验提取通用模式）： -如果「消费者/生产者字段同步」经验在 ≥2 个不同场景复现（PromptContext + 其他），三重验证通过后，可以提升为独立 Skill 或固化到 AGENTS.md 规则。 +如果「消费者/生产者字段同步」经验在 ≥2 个不同场景复现（PromptContext + 其他），验证通过后，可以提升为独立 Skill 或固化到 AGENTS.md 规则。 -### 6.4 三重验证（nuwa-skill 实践 #2） +### 6.4 验证机制（融合 self-improvement Recurrence-Count + Skill Extraction Criteria） 从 draft → active 的验证标准： -| 验证维度 | 标准 | 不通过的后果 | +| 验证维度 | 标准 | 不通过的处理 | |---------|------|------------| -| 跨任务复现 | 同类问题在 ≥2 个不同场景出现过 | 降级为 MEMORY.md 临时记录 | +| 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，对蒸馏产出做结构化检查： @@ -209,15 +287,20 @@ description: Use when [触发条件/问题模式描述]，不描述工作流 **矛盾是特征，不是 Bug。** 强制调和会丢失关键信号。 -### 6.7 蒸馏者 +### 6.7 蒸馏者（双层） -庞统作为蒸馏者，每天 cron spawn 时执行： -1. 读取 DISCOVER 产出的候选信号列表 +**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） -未来考虑半自动化（LLM 辅助草案 + 庞统审阅确认）。 +**L2：庞统（每天 05:00 cron）** +1. 审查所有 agent 提交的 draft proposal（approve / merge / reject） +2. 跨 agent 共性模式识别和合并 +3. 高频/高确定性经验提升到 AGENTS.md 规则 + +未来考虑半自动化（LLM 辅助草案 + agent 审阅确认）。 ## 7. APPLY 阶段 @@ -254,6 +337,22 @@ openclaw 已有的机制： - 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 自我修补 @@ -306,33 +405,39 @@ Agent 使用 Skill 时发现问题（缺步骤、过时信息、命令变更） ### 8.5 反馈到 DISCOVER -IMPROVE 发现的经验缺口（「这条 Skill 不适用 XXX 场景」）→ 写入 knowledge-gaps.md → 成为下一轮 DISCOVER 的输入。 +IMPROVE 发现的经验缺口（「这条 Skill 不适用 XXX 场景」）→ 写入 knowledge-gaps.md → 成为下一轮 DISCOVER L2 的输入。 ## 9. 闭环全景 ``` -DISCOVER（每天 cron） - 数据源：黑板 + Gitea + Mail + JSONL + MEMORY + .learnings + knowledge-gaps +DISCOVER L1（每天 03:00，各 agent cron） + 数据源：自己的 session JSONL 信号识别：5 类高价值信号 - 去重：时间窗口 + 关键词 - 输出：候选信号列表 + 输出：draft skill proposal（structured，带 ID/Priority/Pattern-Key/Recurrence-Count） ↓ -DISTILL（同 cron，庞统执行） +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（draft → skill_workshop pending proposal） + 产物：Skill（通过 skill_workshop 管理） ↓ APPLY（实时，openclaw skill 机制） 匹配：description 匹配 → agent read SKILL.md 执行：agent 按内容执行 自我修补：使用时发现问题 → 立即 revise proposal + per-agent 隔离：专属 Skill 在 agent workspace，共享 Skill 在公共目录 ↓ -IMPROVE（每周 cron） +IMPROVE（每周 cron，庞统执行） 追踪：scan JSONL 引用信号 淘汰：30天无引用 → 庞统审查 → quarantine 提升：高频引用 → 独立 Skill / AGENTS.md 规则 / guardrail - 反馈：知识缺口 → knowledge-gaps.md → 回到 DISCOVER + 反馈：知识缺口 → knowledge-gaps.md → 回到 DISCOVER L2 ``` ## 10. 与现有实现的关系 @@ -342,20 +447,23 @@ IMPROVE（每周 cron） | `skill_system.py`（SkillRegistry/SkillExecutor） | **标记 deprecated，后续清理。** 死代码，实际不参与 skill 发现/加载 | | `experience.py`（ExperienceDistiller/ExperienceStore） | **标记 deprecated，后续清理。** 空转代码，experiences 目录全空 | | `experiences` 表 / `experience_tags` 表（db.py） | **保留表结构但不再写入。** 未来如果需要 DB 查询可以重新启用 | -| ticker.py:336-348 经验蒸馏逻辑 | **移除。** 不再逐任务蒸馏，改为每天 cron | +| ticker.py:336-348 经验蒸馏逻辑 | **移除。** 不再逐任务蒸馏，改为双层 daily cron | | `skill_workshop` 工具 | **核心使用。** 所有 Skill 生命周期通过它管理 | | openclaw `` 机制 | **核心依赖。** 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 自我修补规则 | 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 | 在 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 需要先确认设计文档。 @@ -366,7 +474,6 @@ S1 和 S2 可以立即做。S3-S5 需要先确认设计文档。 | 统一产物 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 | @@ -376,3 +483,181 @@ S1 和 S2 可以立即做。S3-S5 需要先确认设计文档。 | 棘轮机制 | 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 | `/skills` | 只对该 agent | +| 2 | Project agent skills | `/.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-/.skill-workshop/） + ↓ +L2 审查（庞统 05:00） + ↓ skill_workshop list → inspect → 决策 + ↓ + ├─ APPROVE（个人经验，质量达标） + │ → skill_workshop apply + │ → 写入：~/.openclaw/workspace-/skills//SKILL.md + │ → 仅该 agent 可见（workspace skill，优先级 1） + │ + ├─ MERGE（跨 agent 共性） + │ → 合并多个 proposal 为共享 Skill + │ → skill_workshop apply 到庞统 workspace，然后 cp/symlink 到公共目录 + │ → 写入：~/.sanguo_projects/sanguo_mozi/skills//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-/.skill-workshop/ +├── proposals/ +│ ├── / +│ │ ├── 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-/skills//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//sessions/*.jsonl +# 产出：skill_workshop create → proposal（pending） +# 存储：~/.openclaw/workspace-/.skill-workshop/proposals/ + +# L2（05:00 庞统） +# 输入：全量数据源 + 所有 pending proposals +# 审查：skill_workshop list → inspect → apply/merge/reject +# 产出： +# APPROVE → ~/.openclaw/workspace-/skills//（per-agent） +# MERGE → ~/.sanguo_projects/sanguo_mozi/skills//（共享） +# 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 中 +``` diff --git a/skills/skill-management/SKILL.md b/skills/skill-management/SKILL.md new file mode 100644 index 0000000..253503f --- /dev/null +++ b/skills/skill-management/SKILL.md @@ -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 diff --git a/skills/skill-management/assets/checklists/quality-check.md b/skills/skill-management/assets/checklists/quality-check.md new file mode 100644 index 0000000..6b3f9d0 --- /dev/null +++ b/skills/skill-management/assets/checklists/quality-check.md @@ -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 diff --git a/skills/skill-management/assets/templates/signal-format.md b/skills/skill-management/assets/templates/signal-format.md new file mode 100644 index 0000000..cd7c772 --- /dev/null +++ b/skills/skill-management/assets/templates/signal-format.md @@ -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 次 | +| 决策转折 | 原方向被推翻或修正 | +| 新实践 | 之前没有的知识 | +| 知识缺口 | 查不到/不确定的东西 | diff --git a/skills/skill-management/assets/templates/skill-template.md b/skills/skill-management/assets/templates/skill-template.md new file mode 100644 index 0000000..2b1c94f --- /dev/null +++ b/skills/skill-management/assets/templates/skill-template.md @@ -0,0 +1,51 @@ +--- +name: skill-template +description: "SKILL.md 标准模板 — 蒸馏产出时按此格式编写" +--- + +# Skill 标准模板 + +```yaml +--- +name: +description: "Use when <触发条件/问题模式描述>" +--- + +# + +## 什么时候用 +<具体的触发场景，按问题模式描述，不按技术特定症状> + +## 怎么做 +<根因分析 + 操作步骤> + +1. <步骤 1> +2. <步骤 2> +3. <步骤 3> + +## 常见错误 +<反模式：什么不该做> + +- ❌ <错误做法> → <后果> +- ❌ <错误做法> → <后果> + +## 来源 + + +- task : <简述> +- PR #: <简述> +``` + +## description 编写要点 + +- 以「Use when...」开头 +- 只描述触发条件（when），**不描述工作流**（how） +- 描述问题模式，不描述技术特定症状 +- 控制在 1-2 句话 + +## 质量自检 + +- [ ] trigger 是否具体（不是「注意代码质量」） +- [ ] action 是否可执行（不是「要小心」） +- [ ] 是否与已有 Skill 重复 +- [ ] description 是否只含触发条件 diff --git a/skills/skill-management/references/apply.md b/skills/skill-management/references/apply.md new file mode 100644 index 0000000..ce2412a --- /dev/null +++ b/skills/skill-management/references/apply.md @@ -0,0 +1,34 @@ +# APPLY — Skill 应用阶段 + +## 机制 + +APPLY 完全基于 openclaw 原生 skill 机制，不需要额外代码： + +1. openclaw 扫描 skills 目录 → 生成 `` 列表（只有 name + description） +2. Agent 按 description 匹配 → `read` SKILL.md 完整内容 +3. Agent 按内容执行 + +## 渐进式加载 + +- L1：`` 列表（~100 token/skill）— 每次启动注入 +- L2：Agent `read` SKILL.md — 按需加载 +- L3：SKILL.md 内引用的 references/ 文件 — 按需加载 + +## Skill 存放位置与可见性 + +| 位置 | 可见性 | 优先级 | +|------|--------|--------| +| `~/.openclaw/workspace-/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="", proposal_content="<修改后的内容>") +``` + +不等定时任务，不等到下次 review。 diff --git a/skills/skill-management/references/discover-l1.md b/skills/skill-management/references/discover-l1.md new file mode 100644 index 0000000..a889703 --- /dev/null +++ b/skills/skill-management/references/discover-l1.md @@ -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//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="", description="Use when <触发条件>", proposal_content="") +``` + +输出格式（每条信号）： +``` +信号类型 | 来源（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 条流水账有价值 diff --git a/skills/skill-management/references/discover-l2.md b/skills/skill-management/references/discover-l2.md new file mode 100644 index 0000000..09084a1 --- /dev/null +++ b/skills/skill-management/references/discover-l2.md @@ -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="") +``` + +审查维度： + +| 维度 | 标准 | 不通过 | +|------|------|--------| +| Recurrence-Count ≥ 2 | 同一 Pattern-Key 在 ≥2 个场景出现 | 降级为 MEMORY.md | +| 有生成力 | 能给出具体操作指引 | 丢弃 | +| 有排他性 | 不是常识 | 丢弃 | +| description 合规 | 只描述触发条件，不含工作流 | 要求 revise | +| trigger 具体 | 不是「注意代码质量」 | 要求 revise | + +### Step 5: 执行决策 + +对每个 proposal 做出决策： + +**APPROVE**（个人经验，质量达标）： +```python +skill_workshop(action="apply", proposal_id="") +# skill_workshop 自动写入 agent workspace: ~/.openclaw/workspace-/skills// +# 仅该 agent 可见 +``` + +**MERGE**（跨 agent 共性）： +```python +# 1. 在庞统 workspace apply 合并后的版本 +skill_workshop(action="apply", proposal_id="") +# 2. cp 到公共目录（skill_workshop 不能写 extraDir） +cp ~/.openclaw/workspace-pangtong/skills//SKILL.md \ + ~/.sanguo_projects/sanguo_mozi/skills//SKILL.md +# 3. 通知各 agent quarantine workspace 中的同名 draft +# 在相关 PR/Issue 中 @agent 说明 +``` + +**REJECT**（质量不够）： +```python +skill_workshop(action="reject", proposal_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 改进而非打击 diff --git a/skills/skill-management/references/distill.md b/skills/skill-management/references/distill.md new file mode 100644 index 0000000..3fe2104 --- /dev/null +++ b/skills/skill-management/references/distill.md @@ -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 +``` diff --git a/skills/skill-management/references/improve.md b/skills/skill-management/references/improve.md new file mode 100644 index 0000000..357da93 --- /dev/null +++ b/skills/skill-management/references/improve.md @@ -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="")` +- **保留观察** → 标注，下轮再查 +- **更新后保留** → 修改 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 发现「 不适用 <场景>」→ 待 DISCOVER 处理 +``` + +成为下一轮 DISCOVER L2 的输入。 + +## 注意事项 + +- 不追求精确归因，做时间维度的信号采集 +- 淘汰决策由庞统判断，不自动执行 +- 提升到 AGENTS.md 的规则需要主公确认（影响所有 agent 的确定性注入）