diff --git a/docs/design/19-skill-lifecycle-and-experience-loop.md b/docs/design/19-skill-lifecycle-and-experience-loop.md index 88ef246..665db21 100644 --- a/docs/design/19-skill-lifecycle-and-experience-loop.md +++ b/docs/design/19-skill-lifecycle-and-experience-loop.md @@ -289,7 +289,7 @@ description: Use when [触发条件/问题模式描述]，不描述工作流 ### 6.7 蒸馏者（双层） -**L1：每个 agent 自己（每天 03:00 cron，各 agent 错开 5 分钟避免资源争用）** +**L1：每个 agent 自己（每天 03:00 cron，各 agent 错开 15 分钟避免资源争用：03:00, 03:15, 03:30, ...）** 1. 扫描自己的 session JSONL 2. 用判断力提取根因模式（不是机械提取） 3. 按 SKILL.md 格式产出 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 的确定性注入）