越用越灵

本技能优势维度

核心理念

从「重型5阶段一次性流水线」进化为「轻量Hook驱动的持续学习引擎」：

• 不替代你干活，而是在你干活的每一刻静默捕捉值得记住的经验
• 每条学习仅几十token，积累到阈值才触发轻量的Promotion/Extraction
• 几乎零失败：无长链路、无强制阶段、无阻塞等待，纯Hook事件驱动
• 跨会话增长：Promotion将经验写入永久文件，下次会话自动受益

数据安全与隐私（强制约束）

本技能在自动捕获学习记录时，严禁记录任何敏感信息。以下内容绝对不能写入任何 learnings 或 promotion 文件：

🚫 绝对禁止记录

• API 密钥 / Token / Access Key / Secret Key
• 密码 / Passphrase / 认证凭据
• SSH 私钥 / 证书 / 签名密钥
• 数据库连接串（含密码字段）
• 完整源代码文件内容（仅记录文件名+行号+错误模式）
• 用户个人身份信息（姓名/手机/邮箱/身份证号）
• 内网 IP/域名等基础设施敏感信息

✅ 脱敏记录规则

• 错误模式中如含敏感数据 → 仅记录错误类型，替换参数为占位符 <REDACTED>
• 命令示例中如含 Token → 替换为 <TOKEN> 或 ****
• 文件路径脱敏：仅保留相对路径，去除用户目录前缀
• 原则：记录"怎么错的、怎么修的"，不记录"谁、在哪、用什么密钥"

🔒 跨会话推送约束

• 推送前检查每条 learning 是否含以上敏感类型
• 仅推送通用经验/工具类学习，明确拒绝推送含项目具体配置/路径的学习
• 隐私类学习（user_correction 中的偏好/习惯）仅存储在本地 learnings/，不广播

📋 安全自检

每次 Promotion/Extraction 前执行：

1. 扫描候选 learnings → 匹配敏感信息模式（key/token/secret/password/private）
2. 命中 → 自动脱敏或跳过该条，记录安全日志
3. 通过 → 继续正常流程

🔐 最小权限原则

本技能遵循最小权限原则——仅获取完成任务所需的最低权限：

原则：本技能仅写 outputs/、~/.workbuddy/MEMORY.md、~/.workbuddy/skills/ 三个目录，其余文件系统访问均为只读。如需额外权限（如写入其他目录），需用户明确授权。

快速上手

方式一：零配置模式（推荐新手）

无需任何配置文件，开箱即用：

# 仅需创建学习记录目录
mkdir -p outputs/learnings/

技能启动后自动使用内置默认值运行：
- 所有6类Hook 全部启用，语义去重、价值评分、自动归档 全部开启
- Promotion 阈值 = 3 次；Extraction 阈值 = 5 次，自动安装
- gitignore = hybrid；存储后端 = outputs；并发模式 = 安全时间戳文件
- 详细默认值见「配置系统 → 零配置默认值」章节

无需 config.yaml，缺失时自动使用以上硬编码默认值。适合快速试用和单项目场景。

方式二：自定义配置模式

# 从模板创建配置文件
cp config.yaml.example config.yaml
# 按需修改 hooks.enabled / promotion.threshold 等

使用 config.yaml 进行精细化控制（Hook 独立开关、阈值调整、gitignore 策略选择）。

首次运行自检

技能加载时自动执行：
1. 检查 outputs/learnings/ 是否存在 → 不存在则自动创建
2. 检查 config.yaml 是否存在 → 缺失则使用内置默认值
3. 扫描 hooks/ 目录 → 缺失 Hook 文件则降级为内置简化规则
4. 输出就绪状态：
✅ 越用越灵 | 6/6 Hooks | 语义去重:on | 并发:安全 | 归档:auto | 共存:exclusive | 零配置 ▸ 你现在可以直接干活了。我会静默捕捉经验，任务结束时汇报成果。

验证安装

触发任意一个Hook测试：

# 故意输错命令触发 command_failure Hook
nonexistent-command
→ 自动捕获为 learnings/YYYY-MM-DD/ 目录下的一条独立记录

新手三分钟（读完就能开始用）

加载技能后，你什么都不用做——技能已自动运行。以下是你的第一条行动路线：

▸ 加载技能后的 0 秒  →  6类自动触发器已静默运行
▸ 输入第一条指令后  →  Hook自动捕获经验
▸ 完成任务后        →  自动输出一行摘要，告诉你今天学到了什么

第一天：只需确认技能在工作

# 1. 故意输错一个命令，验证 Hook 触发
cd /nonexistent-dir

# 2. 查看看一日志（看有没有自动记下来）
@self-loop-optimizer status

# 3. 创建一个真实任务，正常干活即可

技能会自动捕获失败的命令、你的纠正、API 异常。不需要手动开启任何东西。

第一周：让技能帮你沉淀经验

什么时候需要配置？

只有在你需要以下场景时才需要碰 config.yaml：

□ 与 self-improvement 并存       → 改 coexistence.mode
□ 不想让某些经验自动晋升          → 调高 promotion.threshold
□ 公司团队共享配置                → 改 gitignore.mode: team-shared
□ 希望记录写得更详细              → 改 learning_format.mode: enhanced

99% 的情况下，零配置就够了。

速查路线图

---

## 工作模式

### 模式 A：Hook自动检测（默认，推荐）

技能激活后全程静默运行，6类触发器自动监测。检测到事件→立即捕获为微学习记录→主任务完成后批量执行Promotion/Extraction。**不打断、不询问、不阻塞主任务**。

### 模式 B：全流程优化（显式触发）

当用户使用 `@self-loop-optimizer full` 或明确要求完整流水线时，执行原5阶段全流程（见附录A）。用于需要端到端质量保证的复杂交付物。

---

## 6类内置检测触发器

### 1. 🔴 命令执行失败 `command_failure`

**触发条件**：
- Bash/PowerShell 返回非零退出码
- 输出包含 `error:` / `failed:` / `fatal:` / `permission denied` 等
- 编译/构建/测试命令失败

**捕获内容**：失败命令片段、错误摘要(1行)、根本原因(1行)、修复方法(1行)

**Hook脚本**：`hooks/on_command_failure.md` — 定义详细的捕获规则和去重策略

**Token预算**：～50-80 token/条

---

### 2. 🟡 用户纠正 `user_correction`

**触发条件**：
- 用户消息包含纠正意图关键词：`不对`/`错了`/`应该是`/`改一下`/`重来`/`不是这样`/`修正`
- 用户明确否定了前一步操作结果

**捕获内容**：被纠正的操作(1行)、错误点(1行)、正确做法(1行)

**Hook脚本**：`hooks/on_user_correction.md`

**Token预算**：～40-60 token/条

---

### 3. 🟠 能力缺失 `capability_gap`

**触发条件**：
- Agent输出包含 `无法`/`不支持`/`没有权限`/`做不到`/`超出能力`/`I don't have access`
- Agent发现缺少必要的工具/API/权限来完成用户请求

**捕获内容**：缺失能力描述(1行)、当前替代方案(1行)、建议增强方向(1行)

**Hook脚本**：`hooks/on_capability_gap.md`

**Token预算**：～40-60 token/条

---

### 4. 🔵 API/外部服务异常 `api_error`

**触发条件**：
- HTTP 4xx/5xx 响应
- 连接超时/拒绝连接/DNS解析失败
- MCP工具/Connector返回错误
- 外部服务不可用

**捕获内容**：服务名称(1行)、错误码/类型(1行)、降级/重试方案(1行)

**Hook脚本**：`hooks/on_api_error.md`

**Token预算**：～50-70 token/条

---

### 5. 🟣 知识过时 `knowledge_outdated`

**触发条件**：
- 发现文档/API/包版本与当前环境不匹配
- 命令/参数在新版本中已废弃或变更
- 搜索结果与本地预期不一致

**捕获内容**：过时信息(1行)、最新信息(1行)、信息来源(1行)

**Hook脚本**：`hooks/on_knowledge_outdated.md`

**Token预算**：～50-80 token/条

---

### 6. 🟢 更优方案发现 `better_approach`

**触发条件**：
- 执行过程中发现或联想到明显更优的实现方式
- 用户建议了比当前方案更好的做法
- 工具链/库有更好的替代品

**捕获内容**：当前方案不足(1行)、更优方案(1行)、适用条件(1行)

**Hook脚本**：`hooks/on_better_approach.md`

**Token预算**：～50-70 token/条

---

## Hook系统架构

触发事件 → 匹配Hook条件 → 执行Hook指令 → 生成微学习记录 → 写入 learnings/YYYY-MM-DD/HH-MM-SS-uuid.md（任务结束时合并为 YYYY-MM-DD.md）

### Hook脚本规范

每个 `hooks/on_*.md` 文件定义：
1. **触发判定规则**：哪些输出模式匹配此Hook
2. **信息提取模板**：从上下文中提取哪些字段
3. **去重策略**：同一会话中同类错误仅记录首次
4. **抑制规则**：已知/预期的错误可配置跳过

### Hook启用控制

通过 `config.yaml` 中 `hooks.enabled.<name>: true/false` 独立控制每个Hook的启用状态。

### Hook主动检查机制（关键：确保"几乎不会失败"）

Hook并非被动等待的守护进程，而是通过 **"每步后自检"** 机制保证触发率：

1. **每次工具调用完成后**（Bash/PowerShell/Write/Read等），自动扫描返回结果检查是否命中6类触发器
2. **每次用户消息接收后**，自动扫描用户文本是否命中纠正/建议类触发器
3. **每个子任务完成后**，主动自评：是否发现能力缺失？是否有更优方案？
4. **检查耗时**：每次检查为纯文本模式匹配，消耗 < 10 token
5. **未命中则静默跳过**，命中则执行对应Hook指令生成学习记录

检查失败不会阻塞主流程——最坏情况只是漏记一条学习，不会导致任务中断。

### Hook文件缺失容错

启动时扫描 hooks/ 目录 → 比对 config.yaml 启用列表
├── Hook文件存在 → 正常加载
├── Hook文件缺失但已启用 → 降级为SKILL.md内置简化规则，记录警告
└── Hook已禁用 → 跳过

---

## 微学习捕获格式

所有学习记录写入 `outputs/learnings/YYYY-MM-DD/` 子目录（每条独立时间戳文件），任务结束时自动合并为 `outputs/learnings/YYYY-MM-DD.md` 供人类阅读。每条占用约 50～150 token：

### 基础格式（极简，默认）

```markdown
## 2026-07-27

### [14:32:05] command_failure · pip install
**现象**：`pip install` 在 venv 中报 `externally-managed-environment`
**根因**：Python 3.12+ PEP 668 限制全局 pip
**修复**：使用 `--break-system-packages` 或先激活 venv
**标签**：#python #pip #venv

输入输出样例

输入（用户做了什么 → 触发 Hook → 捕获为 learning）：

输出格式（合并后的 YYYY-MM-DD.md 人类可读版）：

## 2026-07-28

### [10:32:05] command_failure · pip install
**现象**：pip install numpy 报 externally-managed-environment
**根因**：Python 3.12+ PEP 668 限制全局 pip
**修复**：使用 --break-system-packages 或先激活 venv
**标签**：#python #pip #venv

### [14:15:22] api_error · rate_limit
**现象**：GitHub API 返回 429 状态码
**根因**：未认证请求达到匿名限速
**修复**：配置 GITHUB_TOKEN 环境变量后重试
**标签**：#api #github #rate-limit

当日志需要更好的可读性与筛选能力时，每条增加元数据行：

### [14:32:05] command_failure · pip install
<!-- META: P=1 S=open A=python-env RC=1 -->
**现象**：`pip install` 在 venv 中报 `externally-managed-environment`
**根因**：Python 3.12+ PEP 668 限制全局 pip
**修复**：使用 `--break-system-packages` 或先激活 venv
**标签**：#python #pip #venv
**关联**：[See Also: 2026-07-25 · command_failure · npm EBADENGINE]

元数据字段说明

记录原则

• 极简：每条3-5行，绝不超过8行（含元数据）
• 结构化：统一 现象→根因→修复→标签 模板
• 可选增强：元数据行 <!-- META: --> 为 HTML 注释，不影响人读，便于程序解析
• 可检索：标签使用 #keyword 格式，便于后续聚合
• 去重：同会话同类错误仅记录首次出现
• 关联：通过 [See Also: YYYY-MM-DD · category · keyword] 建立跨日记链接

语义去重（跨会话）

问题

基础去重仅在同会话内生效。同一个 "pip install PEP 668 错误" 在不同会话中被反复记录，造成存储膨胀和 Promotion 信号稀释。

语义指纹去重

每条 learning 记录时生成语义指纹：

指纹 = hash(标签集合 归一化 + 现象首句 去除参数)

示例：

# 会话A
现象：pip install numpy 报 externally-managed-environment
标签：#python #pip #venv
指纹：hash("python,pip,venv|pip install externally-managed-environment")

# 会话B（参数不同，但语义相同）
现象：pip install pandas 报 externally-managed-environment
标签：#python #pip #pandas
指纹：hash("python,pip,pandas|pip install externally-managed-environment")

# 指纹相似度 = 0.92 > semantic_threshold(0.85) → 识别为重复
# → 更新会话A记录的 Recurrence-Count，不新增记录

配置

dedup:
  semantic: true                 # 启用语义去重
  semantic_threshold: 0.85       # 相似度阈值
  cross_session_window: 10       # 检查最近N个会话日期的learnings

去重决策矩阵

并发安全

问题

多 Agent 同时运行（OpenClaw spawn 的 Extraction Agent + 主会话 Agent）可能同时追加同一 YYYY-MM-DD.md，导致写入交错损坏。

解决方案：时间戳独立文件 + 定时合并

放弃直接追加 YYYY-MM-DD.md，改为每条 learning 写入独立文件：

outputs/learnings/2026-07-27/
├── 14-32-05-a3f2_command_failure_pip.md
├── 14-45-18-b7c1_user_correction.md
├── 15-10-22-d4e8_api_error.md
└── ...

每日归档任务（主任务结束时执行）：

1. 扫描 outputs/learnings/YYYY-MM-DD/ 下所有 .md 文件
2. 按时间排序 → 合并为 outputs/learnings/YYYY-MM-DD.md（人类可读格式）
3. 删除独立文件目录
4. 此操作为单 Agent 执行 → 无并发风险

配置

concurrency:
  mode: timestamp_files           # timestamp_files | direct_append
  merge_on_task_end: true         # 主任务结束时自动合并独立文件

优点：
- 彻底消除并发写冲突（每个文件由单个 Agent 独占写入）
- 独立文件可作为原子操作（write + close = 完成）
- 合并后人类可读性不变（仍然聚合到 YYYY-MM-DD.md）

价值评分模型

问题

当前 "高价值单条即触发 Promotion" 依赖关键词判断，无量化标准。容易误将低信息量记录晋升，或遗漏重要的中频模式。

Impact Score（影响分）

每条 learning 在捕获时自动计算 impact_score（0-10）：

impact_score = scope × 0.4 + recurrence × 0.3 + universality × 0.3

Promotion 触发规则

配置

impact_score:
  enabled: true
  promote_threshold: 7.0
  weights:
    scope: 0.4
    recurrence: 0.3
    universality: 0.3

存储后端可切换

问题

与 self-improvement 并存的根本矛盾：两套存储后端（outputs/learnings/ vs .learnings/）即使分工也会各写各的，无法从根源消除双重记录。

解决方案：统一存储后端

backend:
  type: outputs                  # outputs | dotlearnings
  auto_migrate: false            # 是否自动迁移现有数据

模式 A：outputs（默认，自闭环原生格式）

使用 outputs/learnings/YYYY-MM-DD/ 子目录存储（任务结束时合并为 outputs/learnings/YYYY-MM-DD.md），格式见"微学习捕获格式"章节。

模式 B：dotlearnings（与 self-improvement 共享）

使用 .learnings/ 作为存储后端，记录格式兼容 self-improvement 的 LEARNINGS.md + ERRORS.md + FEATURE_REQUESTS.md：

.learnings/
├── LEARNINGS.md              # 自闭环写入（兼容 self-improvement 格式）
├── ERRORS.md                 # command_failure + api_error → 写入此处
└── FEATURE_REQUESTS.md       # capability_gap → 写入此处

格式兼容映射：

启用后效果：
- 与 self-improvement 共享同一份数据源，彻底消除双重记录
- 自闭环额外提供自动 Promotion / Extraction / 价值评分 / 归档
- self-improvement 仍可正常读取 .learnings/ 进行手动 Review / Promotion

迁移命令

# 从 outputs 迁移到 dotlearnings
@self-loop-optimizer migrate --from outputs --to dotlearnings

# 预览迁移（不实际执行）
@self-loop-optimizer migrate --from outputs --to dotlearnings --dry-run

⚠️ 迁移前置条件
- backend.type: dotlearnings 迁移前，必须先安装并初始化 self-improvement（生成 .learnings/ 根目录），否则目标目录不存在、迁移失败。
- 迁移为单向追加：仅把 outputs/learnings/ 的活跃记录写入 .learnings/ 对应文件，不删除源数据；如需回滚，直接把 backend.type 改回 outputs 即可。
- 建议先跑 --dry-run 预览映射结果，确认 command_failure/api_error → ERRORS.md、capability_gap → FEATURE_REQUESTS.md、其余 → LEARNINGS.md 的归类符合预期，再正式迁移。
- 迁移不改变 learnings 内容，仅改变存储后端；Promotion/Extraction 行为不受迁移影响。

Promotion机制

触发条件

满足以下任一条件即触发Promotion：

1. 频次触发：同一标签的learnings累积到N次（默认3次，可在config.yaml配置）
2. 价值触发：单条learning被判定为"高价值"（通用性强、影响面广、安全相关）

提升目标文件与映射规则

Promotion执行流程

1. 扫描 learnings/ 目录 → 按标签聚合
2. 识别达到阈值的标签组 → 生成候选
3. 自动判断目标文件(基于标签+内容语义) → 分配目标
4. 去重检查(目标文件中是否已有相同/相似内容) → 避免冗余
5. 追加写入目标文件(保留原有结构) → 记录promotion日志
6. 标记源learnings为 `[promoted → {target_file}]` → 更新Status为 promoted

Promotion格式示例

写入 CLAUDE.md：

## 本项目踩坑记录 (auto-promoted on 2026-07-27)
- Windows路径含空格时使用短路径名(`PROGRA~1`)代替引号包裹，避免嵌套引号转义问题
- `pip install` 在 Python 3.12+ 需加 `--break-system-packages` 或确保在 venv 中

Skill Extraction 工作流

触发条件

当同一领域的learnings满足以下条件时自动触发Extraction：

1. 同类标签learnings >= N条（默认5条，可在config.yaml配置）
2. 内容构成可独立执行的完整工作流（有明确的输入→步骤→输出）
3. 不存在同名Skill

Extraction全流程

Step 1 — 聚合 (Aggregate)
  合并同标签/相关标签的所有learnings，提取共性模式

Step 2 — 模式识别 (Pattern Recognition)
  识别重复出现的步骤序列、决策树、输入输出关系
  判断是否满足"完整工作流"标准：
    ✅ 有明确的触发条件/使用场景
    ✅ 有清晰的操作步骤(>=3步)
    ✅ 有可验证的输出/结果
    ❌ 仅零散tips → 跳过，继续等待累积

Step 3 — 模板填充 (Template Fill)
  套用标准Skill模板生成 SKILL.md：
  - name: 自动推导(基于标签+内容)
  - description: 从learnings中提炼
  - keywords: 从标签中提取
  - 执行步骤: 从learnings模式中重构

Step 4 — 质量自检 (Quality Check)
  确认：
  - description明确，触发词清晰
  - 步骤完整可执行
  - 无硬编码敏感信息
  - 无与现有Skill的功能重叠

Step 5 — 安装 (Install)
  写入 ~/.workbuddy/skills/{skill-name}/SKILL.md
  使用 `Skill` 工具（command="skill-creator"）或直接 Write 创建 SKILL.md
  如 config.yaml 中 extraction.auto_install=false 则仅生成预览

Step 6 — 溯源 (Trace)
  在源learnings中添加：
  `[extracted → skill:{skill-name}]`

Extraction日志

所有Extraction操作记录到 outputs/extractions/extraction-log.md：

## 2026-07-27 15:00
- **Skill**: python-venv-troubleshooting
- **来源learnings**: 5条 (#python #pip #venv)
- **安装路径**: ~/.workbuddy/skills/python-venv-troubleshooting/
- **状态**: ✅ installed

归档与保留策略

问题

当前 outputs/learnings/ 只增不删。长期运行会导致：
- 日积月累数百条记录，Promotion 扫描越来越慢
- 已 promoted/extracted 的旧记录与活跃记录混杂，干扰判断
- 违反 Token 预算设计目标（旧数据持续占用扫描额度）

归档流程

每条 learning 的生命周期：

捕获 → [open] → 达到阈值 → [promoted] + [extracted]
                          ↓
                    保留 retention.days 天后（默认30天）
                          ↓
                    移入 archive/YYYY-MM/ → 原位置替换为归档引用
                          ↓
                    超过 archive.max_age 天后（默认365天）→ 删除

自动归档规则

1. 触发时机：每次 Promotion/Extraction 完成后，扫描 learnings/ 目录
2. 归档条件：Status 为 promoted 或 extracted 或 resolved，且最后修改时间 > retention.days
3. 归档目标：archive/YYYY-MM/ （按月分目录，便于查找）
4. 归档后：原独立时间戳文件替换为归档引用（由合并任务处理时自动完成）：
   markdown <!-- ARCHIVED: [14:32:05] command_failure · pip install → archive/2026-07/pip-externally-managed.md -->
5. 清理：超过 archive.max_age 的归档条目自动删除
6. 执行时序：主任务结束时的操作顺序固定为 合并独立文件 → 归档旧记录，确保归档操作面向已合并的 flat YYYY-MM-DD.md，而非原始子目录

手动归档

用户可随时触发的快速归档：

# 立即归档所有已 promoted/extracted/resolved 的记录
@self-loop-optimizer archive now

# 查看归档统计
@self-loop-optimizer archive status

配置

retention:
  days: 30                       # promoted/extracted/resolved 记录保留天数
  max_in_active: 200             # learnings/ 活跃记录上限，超出触发强制归档

archive:
  auto: true                     # 是否启用自动归档
  max_age: 365                   # 归档最大保存天数，超期删除
  compress: false                # 是否压缩归档文件（节省磁盘）

初始化归档目录

技能启动时自动检查并创建：

outputs/
├── learnings/          # 活跃记录（<30天 & status=open）
├── archive/            # 历史归档
│   ├── 2026-06/        # 按月分目录
│   ├── 2026-07/
│   └── ...
├── promotions/
└── extractions/

通过 OpenClaw 协议实现跨会话学习同步和Agent协作。

支持的操作

sessions_list — 列出活跃会话

用途: 查询当前所有活跃会话及其状态
返回: 会话ID、工作目录、最近活跃时间、当前任务
场景: Promotion后广播更新给所有相关会话

send — 向指定会话发送消息

用途: 向指定会话ID发送学习/通知/指令
内容: learning记录、promotion结果、skill更新通知
场景: 
  - 会话A捕获到通用学习 → 广播给会话B/C
  - 主会话安装新Skill → 通知子会话加载

spawn — 在指定会话中派生Agent

用途: 在目标会话中创建新Agent执行独立任务
参数: 会话ID、Agent类型、任务描述
场景:
  - 后台会话并行执行Skill Extraction
  - 跨会话分工协作大型任务

通信协议

[会话A] 捕获learning
    ↓
[会话A] 评估通用性 → 判定需广播
    ↓
[会话A] sessions_list → 获取活跃会话列表
    ↓
[会话A] send(session_B, learning_content) → 推送到会话B
    ↓
[会话B] 接收 → 写入本地 learnings/ → 标记 [synced-from:session_A]

具体对话示例（会话A捕获到一条通用踩坑，广播给会话B）：

# 会话A：捕获后判定为通用经验，主动广播
[会话A] send(
    target="session_B",
    content="[command_failure] Windows 上 `pip install` 需 --break-system-packages 或在 venv 中；否则报 externally-managed-environment"
)
→ 返回: { "status": "delivered", "session": "session_B" }

# 会话B：接收后写入本地 learnings/，并标记来源
[会话B] 写入 outputs/learnings/2026-07-28/09-15-22-c1d2_command_failure_pip.md
[会话B] 追加标记：<!-- synced-from:session_A -->

> 注意：以上为 OpenClaw 协议语义示意。实际调用由运行环境提供 sessions_list/send/spawn 原语；纯本地单 Agent 场景不触发广播，经验仅落本地。

使用约束

• 去重优先：发送前检查目标会话是否已有相同learning
• 静默推送：默认不打断目标会话当前任务
• 安全边界：仅推送通用经验/工具类学习，不推送用户隐私内容

多平台兼容性

本技能的核心资产（learnings/ + config.yaml + SKILL.md）均为纯 Markdown/YAML 文本文件，天然跨平台兼容。除 OpenClaw 原生协议外，可在以下环境中直接使用：

跨平台共享策略：

同一项目 → git提交 outputs/learnings/ → 所有Agent自动消费
Promotion → 写入 CLI/Agent 标准指令文件 → 多平台上下文注入
跨项目   → ~/.workbuddy/MEMORY.md → 仅WorkBuddy可见

配置系统

配置文件：config.yaml（位于Skill目录下，可选——缺失时使用零配置默认值）

零配置默认值（config.yaml 缺失时生效）

Gitignore策略

gitignore:
  mode: hybrid  # local | team-shared | hybrid

  # local:      整个 config.yaml 加入 .gitignore，仅本地生效
  # team-shared: 整个 config.yaml 提交到Git，团队共享同一配置
  # hybrid:     核心配置(triggers/thresholds)共享，敏感配置(hooks启用/个人路径)本地覆盖
  #             hybrid模式下使用 config.local.yaml 覆盖团队配置

Hook独立开关

hooks:
  enabled:
    command_failure: true      # 命令执行失败检测
    user_correction: true      # 用户纠正检测
    capability_gap: true       # 能力缺失检测
    api_error: true            # API/服务异常检测
    knowledge_outdated: true   # 知识过时检测
    better_approach: true      # 更优方案发现检测

Promotion/Extraction阈值

paths:
  learnings_dir: "outputs/learnings"      # 学习记录存储路径
  promotion_log: "outputs/promotions/promotion-log.md"
  extraction_log: "outputs/extractions/extraction-log.md"

promotion:
  threshold: 3               # 同类learnings累积N次触发promotion
  high_value_auto: true      # 高价值learnings单条即触发

extraction:
  threshold: 5               # 同类learnings累积N次触发extraction
  auto_install: true         # 自动安装提取的Skill(设为false则仅生成预览)
  require_confirmation: false # 安装前是否需要用户确认

运行时行为

核心原则

1. 静默运行：默认不打断主任务，检测→捕获→写入全程无感知
2. 零交互：全程不使用 AskUserQuestion，所有决策自主完成
3. 批量处理：Promotion/Extraction在主任务完成后批量执行，不阻塞
4. 增量更新：所有文件操作为追加(append)/合并(merge)，不覆盖已有内容
5. 去重保护：写入前检查目标文件，同内容不重复记录

启动检查清单

0. 欢迎语输出（首次加载）：
   markdown 🚀 越用越灵 已激活 ▸ 你现在可以直接干活了，不必做任何配置 ▸ 我会静默捕捉命令失败、你的纠正、API异常等经验 ▸ 任务结束时汇报今日捕获/晋升/提取摘要 ▸ 需要查看状态或手动控制时，输入 @self-loop-optimizer status
1. 读取 config.yaml → 确定启用的Hook列表和阈值
2. 检查 outputs/learnings/ 目录是否存在 → 不存在则创建
3. 扫描历史learnings → 识别待Promotion/Extraction的候选
4. 激活启用的Hook → 进入检测模式
5. 主任务完成后 → 执行批量Promotion + Extraction

进度可见（可选）

• 每个Hook触发时 → TaskCreate 创建微任务追踪
• Promotion完成时 → TaskUpdate 标记完成
• Extraction完成时 → 输出简短摘要（1行）

与v1.x的兼容

• 用户显式使用 @self-loop-optimizer full → 触发原5阶段完整流水线（见附录A）
• 原有交付物格式和目录结构保留不变
• v1.x的 outputs/ 目录结构向后兼容

状态摘要输出（可观测性）

主任务结束时自动输出一行状态摘要，让用户直观了解技能工作状态：

📊 今日捕获 12 条 · 晋升 3 条 · 提取 0 个 Skill | learnings活跃53条 | 归档0条

输出格式：📊 今日捕获 N 条 · 晋升 M 条 · 提取 K 个 Skill | learnings活跃 L 条 | 归档 A 条

手动查询状态

用户可随时查看详细统计：

@self-loop-optimizer status

返回完整状态面板：

## 📊 越用越灵 — 运行状态

### 今日活动
- 捕获: 12 条 learnings
- 会话数: 2 个活跃会话
- Token 消耗: 约 850 token（预算 3000）

### 学习分布
| 类型 | 今日 | 本周 | 总计 |
|------|:---:|:---:|:---:|
| command_failure | 5 | 12 | 47 |
| user_correction | 3 | 5 | 18 |
| capability_gap  | 1 | 2 | 9 |
| api_error        | 2 | 4 | 15 |
| knowledge_outdated | 0 | 1 | 6 |
| better_approach  | 1 | 3 | 11 |

### Promotion 历史
- 总计晋升: 24 条 → CLAUDE.md(8) AGENTS.md(3) TOOLS.md(6) SOUL.md(3) MEMORY.md(4)
- 最近晋升: 2026-07-27 15:30 — `pip install --break-system-packages` → MEMORY.md

### Extraction 历史
- 总计提取: 2 个 Skill（python-venv-troubleshooting, windows-path-quoting）
- 等待提取: 3 组（#git #npm #docker）

### 归档状态
- learnings/ 活跃: 53 条（上限 200）
- archive/ 总量: 18 条（最早 2026-06-15）
- 下次自动归档: 2026-08-27

状态诊断脚本

# 等效于 @self-loop-optimizer status 的命令行版本
cat << 'EOF' | python3
import os, glob, re
from datetime import datetime

learnings_dir = "outputs/learnings"
archive_dir = "outputs/archive"

# 统计 learnings（子目录模型：YYYY-MM-DD/HH-MM-SS-uuid.md）
today_dir = f"{learnings_dir}/{datetime.now().strftime('%Y-%m-%d')}"
today_count = len(glob.glob(f"{today_dir}/*.md")) if os.path.isdir(today_dir) else 0

# 也统计已合并的 flat 文件（兼容旧数据）
merged_file = f"{learnings_dir}/{datetime.now().strftime('%Y-%m-%d')}.md"
if os.path.exists(merged_file):
    today_count += len([l for l in open(merged_file).readlines() if l.startswith("### [")])

# 总计：所有子目录的 .md 文件 + 顶层合并文件（排除特殊文件）
all_files = glob.glob(f"{learnings_dir}/*/*.md") + glob.glob(f"{learnings_dir}/*.md")
total = sum(1 for f in all_files if os.path.basename(f) not in ["api-health.md", "feature-requests.md"])

print(f"📊 今日捕获 {today_count} 条 · learnings活跃 {total} 条")
EOF

命令实现状态

> 🔧 = 逻辑与文档就绪，行为由 SKILL.md 中的流程描述驱动。无需独立 scripts/ 目录——LLM Agent 根据文档描述即可执行。

调试与故障排查

常见问题速查

故障恢复与重试策略

所有故障都有明确的降级路径，不会让任务卡死。唯一需要人工干预的是 Token 超预算和权限问题。

诊断命令

# 检查学习记录数量
find outputs/learnings/ -name "*.md" | wc -l

# 查看今日记录（子目录模式：先看合并文件，再看独立文件）
MERGED="outputs/learnings/$(date +%Y-%m-%d).md"
DIR="outputs/learnings/$(date +%Y-%m-%d)"
if [ -f "$MERGED" ]; then cat "$MERGED"; elif [ -d "$DIR" ]; then ls "$DIR/" | while read f; do echo "--- ${f} ---"; cat "$DIR/$f"; done; else echo "今日暂无记录"; fi

# 统计各类型触发次数
grep -h "command_failure\|user_correction\|capability_gap\|api_error\|knowledge_outdated\|better_approach" outputs/learnings/*.md | sort | uniq -c | sort -rn

# 查看 Promotion 日志
cat outputs/promotions/promotion-log.md 2>/dev/null || echo "尚无 Promotion 记录"

# 查看 Extraction 日志
cat outputs/extractions/extraction-log.md 2>/dev/null || echo "尚无 Extraction 记录"

重置方法

如果技能行为异常，可安全重置而不影响已积累的经验：

# 仅重置配置（保留 learnings 历史）
rm config.yaml                         # 下次启动使用零配置默认值

# 完全重置（删除所有数据）
rm -rf outputs/learnings/ outputs/promotions/ outputs/extractions/

与 self-improvement 技能共存策略

风险确认

同时启用 self-improvement v3.0.24 与本技能会导致双重记录：同一个错误/纠正/异常会被分别写入 outputs/learnings/ 和 .learnings/ 两处，造成存储冗余、Promotion 冲突和 Token 浪费。

检测机制

本技能启动时自动检查项目根目录是否存在 .learnings/ 目录（self-improvement 的存储根）：

启动检查：
  ├── .learnings/ 目录不存在 → 正常运行，无需处理
  ├── .learnings/ 目录存在 → 检测到 self-improvement 共存 → 根据共存模式决策
  └── 输出状态：例如 "⚠️ 检测到 self-improvement 共存 | 模式：分工"

共存模式（config.yaml coexistence.mode 配置）

模式 1：exclusive（互斥，推荐默认）

检测到 .learnings/ 时，本技能自动静默退出，将学习记录任务完全交给 self-improvement。最适合"已有 self-improvement 稳定运行，不想引入冲突"的场景。

coexistence:
  mode: exclusive
  # 行为：检测到 .learnings/ → 输出提示后静默退出
  # 适用：已深度使用 self-improvement，本技能仅作备份方案

模式 2：division（分工，推荐共存）

两个技能按 Hook 类型分工记录，各司其职，避免重叠：

coexistence:
  mode: division
  # 行为：仅启用 user_correction/capability_gap/better_approach 三个Hook
  #       command_failure/api_error/knowledge_outdated 交给 self-improvement
  #       Skill Extraction / cross-project MEMORY.md promotion 不受影响

模式 3：full（全启+去重）

两者全部启用，但本技能每条记录前先检查 self-improvement 是否已有同类记录：

记录前：
  1. 生成本条 learning 的标签指纹（#tags + error_summary hash）
  2. 查询 .learnings/LEARNINGS.md + ERRORS.md 中是否有相同指纹
  3. 已有 → 跳过记录，标记 [deduped: self-improvement already covered]
  4. 无 → 正常写入

coexistence:
  mode: full
  # 行为：全Hook启用，每条记录前检查 .learnings/ 去重
  # Token开销：每条额外 +10-20 token（读取检查）
  # 适用：需要双重覆盖保底，接受少量冗余

模式 4：off（不处理）

coexistence:
  mode: off
  # 行为：忽略 .learnings/ 存在，正常全量运行
  # 风险：双重记录！仅在你确认不会同时启用两者时使用

推荐路径

新手 → 选一个，用 exclusive 模式避免冲突
  ├── 要开箱即用 → self-improvement（不用配 config）
  └── 要自动晋升/提取 → 自闭环（mkdir 即用零配置）

深度用户 → division 模式，两者分工协作
  └── 自闭环：user_correction + capability_gap + better_approach + 跨项目MEMORY + 自动Extraction
  └── self-improvement：command_failure + api_error + knowledge_outdated + 跨平台共享

共存策略 与 存储后端 的层次关系

两个配置解决不同层面的问题，可以独立或组合使用：

推荐组合：

coexistence.mode: division  +  backend.type: outputs
  → 自闭环只记3类WorkBuddy特有事件，写入outputs/learnings/
  → self-improvement记3类通用事件，写入.learnings/
  → 完美分工，零冲突

coexistence.mode: exclusive + backend.type: dotlearnings
  → 检测到.learnings/自动退出，但如果想切换存储格式可单独配置

coexistence.mode: full      + backend.type: dotlearnings
  → 全量记录，但写入.learnings/与self-improvement共享存储
  → ⚠️ 注意：此时需确保记录格式兼容，避免格式冲突

不推荐：coexistence.mode: off + backend.type: outputs（默认双重记录）

Skill自优化（元能力）

本技能使用自身机制进行自我改进：

自检触发

• 每次技能被加载时，自动执行快速自检（与config.yaml一致性、Hook文件完整性）
• 每10次累积learnings后，自动评估SKILL.md是否有待更新（基于自身捕获的 learnings）
• 用户显式触发 @self-loop-optimizer 自检 → 执行完整5维自审

自检维度

1. 配置一致性：SKILL.md 中的配置示例是否与 config.yaml 实际结构一致
2. 引用完整性：所有 hooks/on_*.md 引用是否对应实际文件
3. 逻辑自洽：Promotion/Extraction阈值描述与config.yaml值是否匹配
4. 路径正确性：所有文件路径引用是否可解析
5. 更新优先级：是否有来自自身learnings的改进建议待实施

自修复流程

graph TD
    A[自检发现问题] --> B[修正 SKILL.md / config.yaml / hooks/]
    B --> C[运行 tests/skill-self-test.md 全部5维]
    C --> D{全部通过?}
    D -->|是| E[记录到 learnings ✅]
    D -->|否| F[回滚修改 → 分析根因 → 重试修复]
    F --> B

⚠️ 自修风险与防护

风险存在：自修由 LLM Agent 执行，修正本身可能引入新问题。tests/skill-self-test.md 是文档级回归检查表，靠 Agent 逐项执行，非自动化 CI 测试。这意味着：

关键原则：
1. 自修后不跑回归测试 = 不允许结束。这是硬性约束，非建议
2. 回归测试只是文档级检查，Agent 执行时需逐项核实，不能跳步
3. 如果回归测试失败，必须回滚到上一次正确状态，分析根因后再试
4. 对 SKILL.md 的每次修改都应同时在 tests/skill-self-test.md 中添加对应检查项

能力边界

本技能不是万能工具。以下场景建议使用其他方案或配合使用：

❌ 本技能不适合

⚠️ 弱项与约束

• LLM 文档驱动：归档、迁移等命令靠 LLM 读取 SKILL.md 中的流程描述执行，非独立可执行代码。适合纯 LLM Agent 环境，不适合传统 CI/CD 集成
• 跨会话同步依赖 OpenClaw：需要 WorkBuddy 的 OpenClaw 协议支持；在 Claude Code / Codex CLI 等平台仅通过文件共享同步，非实时
• Token 消费不可消除：每条 learning 的捕获和检查消耗 50-150 token，长期运行有累积成本（参见附录B的Token预算分析）
• 多 Agent 并发安全：使用时间戳独立文件模式缓解，但极端高频场景仍需关注写时序
• backend.type: dotlearnings 依赖 self-improvement：启用该后端前必须先安装并初始化 self-improvement（生成 .learnings/），否则自动回退为 outputs 后端

反模式与常见陷阱

🔴 不要做的事

⚠️ 容易掉坑的地方

1. 写入模型视图混淆
本技能的存储模型是"独立时间戳文件写入 → 任务结束时合并为 flat 文件"。如果你用文件管理器直接看 outputs/learnings/，看到的是 YYYY-MM-DD/ 子目录（细粒度）和 YYYY-MM-DD.md 合并文件（人类可读）。两者共存，各有用处。

2. "归档 = 删除"的误解
归档不删除数据——learnings 只会从活跃区移入 archive/YYYY-MM/。只有超过 archive.max_age（默认365天）的归档条目才会被清理。数据安全优先。

3. 去重不等同于"绝对不会重复"
语义去重的相似度阈值默认 0.85，极少数情况下高度相似但不同的 learnings 可能被误判为重复。如发现误去重，可调低 dedup.semantic_threshold（如 0.75）。

最佳实践

🎯 团队协作

# 团队推荐配置
gitignore:
  mode: team-shared           # 提交到 Git，团队共享能力边界/反模式等文档
promotion:
  threshold: 5                # 更严格，避免个人经验过早推送
extraction:
  auto_install: false         # 审查后再安装
coexistence:
  mode: division              # 与 self-improvement 分工

团队规范：
- 每天站会花 30 秒查看 @self-loop-optimizer status 的输出，了解团队沉淀经验
- 每两周审查一次 archive/ 中的归档 learnings，决定是否永久保留或清理
- Extraction 出来的 Skill 先在单用户试用一周，确认通用性后再推广团队

🚀 个人高效用法

# 个人推荐配置
gitignore:
  mode: local
promotion:
  threshold: 3                 # 快速沉淀
  high_value_auto: true
extraction:
  auto_install: true
coexistence:
  mode: exclusive              # 使用自闭环为主，不混用其他技能

个人习惯：
- 新项目初始化：mkdir -p outputs/learnings/ && @self-loop-optimizer 自检
- 每周看一次 learnings/ 中各类型分布，识别频繁踩坑的方向
- 手机端查看每天的 outputs/learnings/YYYY-MM-DD.md（合并文件手机友好）

📊 数据驱动改进

利用本技能自身的数据做决策：

高频 command_failure → 环境配置问题，更新 onboarding 文档
高频 user_correction → 知识盲区，写一个快速参考卡片
高频 capability_gap  → 工具链缺失，考虑安装对应 Skill
低频 better_approach → 反思：是因为本已经很优，还是因为没留意更好的解法？

实用案例

案例 1：新手第一天（零配置）

场景：小张第一次使用越用越灵，什么都没配置。

第三天：同类 pip 错误累积到 3 次 → 自动 Promotion 到 MEMORY.md。
第五天：pip + npm 相关的经验累积到 5 条 → 自动提取为 Skill。

案例 2：团队协作（配置共存）

场景：一个 5 人项目组，同时使用越用越灵和 self-improvement。

# 一人配置，git 共享
coexistence:
  mode: division            # 自闭环记3类，self-improvement记3类
gitignore:
  mode: team-shared         # 提交到 git

效果：团队共享同一份 outputs/learnings/，但每人各自的个人经验（如 ~/.workbuddy/MEMORY.md）不互相污染。两周后团队共积累了 47 条 learnings，提取了 2 个通用 Skill。

案例 3：深度个人定制

场景：老李长期使用，想精细控制。

promotion:
  threshold: 5              # 更严格，避免过早推送
impact_score:
  promote_threshold: 8.0    # 只有高价值经验才自动晋升
learning_format:
  mode: enhanced            # 详细记录

效果：虽然晋升变慢了，但每一条晋升到永久文件的经验都确实有价值，老李的 MEMORY.md 从"什么都记"变成了"高价值专业手册"。

案例 4：从零搭建个人知识库

场景：小王的 MEMORY.md 之前一片空白。

第一周结束时，@self-loop-optimizer status 输出：

📊 越用越灵 — 运行状态

今日活动: 捕获 7 条
学习分布:
  command_failure    5  → pip/npm/git 等工具问题
  user_correction    2  → 路径空格/命令行参数

Promotion 历史:
  - 2026-07-28 → pip-externally-managed → MEMORY.md
  - 2026-07-28 → windows-path-spaces     → MEMORY.md

一周后：MEMORY.md 中多了 3 条自动积累的实用经验，全部来自日常操作中的真实踩坑。

使用限制速览

以下是本技能所有限制条件的集中汇总：

文件结构

self-loop-optimizer/
├── SKILL.md # 本文件（核心指令）
├── config.yaml # 配置文件（gitignore可选）
├── hooks/ # 6类Hook检测指令
│ ├── on_command_failure.md # 命令失败检测规则
│ ├── on_user_correction.md # 用户纠正检测规则
│ ├── on_capability_gap.md # 能力缺失检测规则
│ ├── on_api_error.md # API异常检测规则
│ ├── on_knowledge_outdated.md # 知识过时检测规则
│ └── on_better_approach.md # 更优方案检测规则
├── outputs/ # 运行时产出（自动创建）
│ ├── learnings/ # 活跃微学习记录（<retention.days & status=open）
│ │ ├── YYYY-MM-DD/ # 每日子目录（timestamp_files模式，并发安全）
│ │ │ ├── HH-MM-SS-uuid_category.md # 独立时间戳文件
│ │ │ └── ...
│ │ ├── YYYY-MM-DD.md # 每日合并文件（任务结束时自动生成，人类可读）
│ │ ├── api-health.md # API服务健康状态（持续更新）
│ │ └── feature-requests.md # 能力缺失/功能需求汇总
│ ├── archive/ # 历史归档（learnings生命周期终点）
│ │ ├── 2026-06/ # 按月分目录
│ │ ├── 2026-07/
│ │ └── ...
│ ├── promotions/ # Promotion操作日志
│ │ └── promotion-log.md
│ └── extractions/ # Extraction操作日志
│ └── extraction-log.md
├── references/ # 跨平台接入模板
│ ├── claude-code.md
│ ├── copilot.md
│ └── codex.md
└── tests/ # 自修复回归测试
└── skill-self-test.md

---

## 附录A：v1.x 全流程优化模式（保留，显式触发）

当用户使用 `@self-loop-optimizer full` 触发时，执行以下5阶段完整流水线：

### 阶段1：需求量化与验收标准建立
- 拆解至少10项可独立验证的验收项，每项标注权重
- 反向校验覆盖率 → 自评≥95分进入阶段2
- 交付 `outputs/01_需求验收清单.md`

### 阶段2：方案自迭代优化循环（最大5轮）
- 每轮执行5维反问(A-E) → 输出缺陷清单 → 修正 → 打分
- 单轮得分提升<2分连续2轮→提前收敛
- 交付 `outputs/02_迭代过程记录.md`

### 阶段3：全流程自动测试
- 生成三类测试用例(正常/异常/边界)
- 逐条执行 → 失败自动修复 → 核心用例100%通过进阶段4
- 交付 `outputs/03_测试用例集.md` + `03_测试报告.md`

### 阶段4：暗坑排查与修复
- 5维度系统排查(极端输入/外部依赖/逻辑陷阱/累积问题/合规安全)
- 中高风险逐一修复 → 回归验证
- 交付 `outputs/04_暗坑风险清单.md` + `04_修复记录.md`

### 阶段5：分模块审计与终验
- 模块化拆解 → 逐模块审计 → 终验打分≥95
- 交付 `outputs/05_模块审计报告.md`

---

## 附录B：Token预算分析

### v1.x 典型消耗

阶段1: 验收清单生成 + 自评 + 修正 ≈ 2000-4000 token
阶段2: 5轮迭代 × 5维反问 × 每轮修正 ≈ 5000-15000 token
阶段3: 测试用例 + 执行 + 修复 ≈ 3000-8000 token
阶段4: 暗坑排查 + 修复 + 回归 ≈ 2000-5000 token
阶段5: 模块审计 + 终验 ≈ 2000-4000 token
─────────────────────────────────────────────────
合计(一次完整运行) ≈ 14000-36000 token

### v2.0 典型消耗

单条learning捕获 ≈ 50-150 token
每日10条learnings ≈ 500-1500 token
Promotion × 1(去重→1次写入) ≈ 200-400 token
Extraction × 0.2(5天触发1次) ≈ 2000-4000 token (摊销≈400-800/天)
─────────────────────────────────────────────────
日平均 ≈ 700-1900 token (含promotion+extraction摊销)
单条净消耗 ≈ 50-150 token
```

结论：v2.0日常模式下日消耗约700-1900 token（含Promotion/Extraction摊销），远低于v1.x单次完整运行的14000-36000 token。每条学习净消耗仅50-150 token。