self-improving-agent

自我改进技能

将经验和错误记录到 Markdown 文件中，以持续改进。Agent 之后可以处理这些记录并修复问题，重要经验则会提升到工作区记忆中。此版本的技能仅适用于 OpenClaw——其他 Agent 请参阅原始的多 Agent 版本：https://github.com/pskoett/pskoett-ai-skills。

此处已集成记录、审查、复用、提升和维护流程：无需配套技能、服务、插件、记忆后端或修改 OpenClaw 核心。可选钩子只会提醒并捕获可能的错误；它不会强制执行此工作流，也不会重新验证相关说法。

首次使用时初始化

记录任何内容之前，请确保项目或工作区根目录中存在 .learnings/ 目录及其文件。如果有任何缺失，请创建：

mkdir -p .learnings
[ -f .learnings/LEARNINGS.md ] || printf "# Learnings\n\nCorrections, insights, and knowledge gaps captured during development.\n\n**Categories**: correction | insight | knowledge_gap | best_practice\n\n---\n" > .learnings/LEARNINGS.md
[ -f .learnings/ERRORS.md ] || printf "# Errors\n\nCommand failures and integration errors.\n\n---\n" > .learnings/ERRORS.md
[ -f .learnings/FEATURE_REQUESTS.md ] || printf "# Feature Requests\n\nCapabilities requested by the user.\n\n---\n" > .learnings/FEATURE_REQUESTS.md

切勿覆盖现有文件。如果 .learnings/ 已完成初始化，则此操作不会产生任何影响。

除非用户明确要求提供此类详细信息，否则不要记录秘密、令牌、私钥、环境变量或完整的源文件／配置文件。优先使用简短摘要或脱敏摘录，而不是原始命令输出或完整对话记录。

如果你想启用自动提醒和会话结束时的错误检测，请参阅可选：启用钩子中的说明。

快速参考

情况	操作
命令／操作失败	记录到 .learnings/ERRORS.md
用户纠正了你	记录到 .learnings/LEARNINGS.md，类别为 correction
用户希望添加缺失的功能	记录到 .learnings/FEATURE_REQUESTS.md
API／外部工具失败	将集成详情记录到 .learnings/ERRORS.md
知识已过时	记录到 .learnings/LEARNINGS.md，类别为 knowledge_gap
找到更好的方法	记录到 .learnings/LEARNINGS.md，类别为 best_practice
简化／强化重复出现的模式	在 .learnings/LEARNINGS.md 中记录／更新，添加 Source: simplify-and-harden 和稳定的 Pattern-Key
与现有条目相似	按 Pattern-Key 搜索，确认说法／范围相同；只有新发生的情况才计数
复用或提升已保存的知识	按下方的维护说明，审查相关及到期的说法，包括一次性／未提升的条目
来源、决策、依赖项或任务发生变化	重新验证受影响的说法；不要仅因时间流逝就将其过期
工作流改进	提升到工作区的 AGENTS.md
工具注意事项	提升到工作区的 TOOLS.md
行为模式	提升到工作区的 SOUL.md

OpenClaw 设置

OpenClaw 使用基于工作区的提示词注入，并自动加载技能。

安装

通过 OpenClaw 内置安装器（推荐）——安装到当前启用的 OpenClaw 工作区：

openclaw skills install @pskoett/self-improving-agent

通过 ClawHub CLI（npm i -g clawhub）——安装到当前工作目录下的 ./skills，而非工作区：

clawhub install @pskoett/self-improving-agent

手动安装（技能位于仓库的 self-improving-agent/ 子目录中；请复制该目录，而非仓库根目录）：

git clone https://github.com/pskoett/self-improving-agent.git /tmp/self-improving-agent-repo
cp -r /tmp/self-improving-agent-repo/self-improving-agent ~/.openclaw/skills/self-improving-agent

基于原始仓库为 openclaw 重新制作：https://github.com/pskoett/pskoett-ai-skills - https://github.com/pskoett/pskoett-ai-skills/tree/main/skills/self-improvement

工作区结构

OpenClaw 会在每个会话中注入以下文件：

~/.openclaw/workspace/
├── AGENTS.md          # Multi-agent workflows, delegation patterns
├── SOUL.md            # Behavioral guidelines, personality, principles
├── TOOLS.md           # Tool capabilities, integration gotchas
├── MEMORY.md          # Long-term memory (main session only)
├── memory/            # Daily memory files
│   └── YYYY-MM-DD.md
└── .learnings/        # This skill's log files
    ├── LEARNINGS.md
    ├── ERRORS.md
    └── FEATURE_REQUESTS.md

创建经验记录文件

mkdir -p ~/.openclaw/workspace/.learnings

然后创建日志文件（或从 assets/ 复制）：

• LEARNINGS.md — 纠正、知识缺口、最佳实践
• ERRORS.md — 命令失败、异常
• FEATURE_REQUESTS.md — 用户请求的功能

提升目标

当经验已证实具有广泛适用性时，将其提升到工作区文件中：

经验类型	提升到	示例
行为模式	SOUL.md	“简明扼要，避免免责声明”
工作流改进	AGENTS.md	“为长任务启动子 Agent”
工具注意事项	TOOLS.md	“配置好身份验证后才能执行 Git 推送”

跨会话通信

OpenClaw 提供了用于在会话间共享经验的工具：

• sessions_list — 查看活跃／最近的会话
• sessions_history — 阅读其他会话的记录
• sessions_send — 向其他会话发送经验
• sessions_spawn — 启动子 Agent 执行后台工作

仅在可信环境中使用这些工具，并且只有在用户明确希望跨会话共享时才使用。优先发送简短、已清理的摘要和相关文件路径，而不是原始记录、机密或完整命令输出。

可选：启用 Hook

若要在会话开始时自动提醒并在会话结束时检测错误， 请按照安装或升级 Hook中的说明操作， 然后使用 openclaw hooks enable self-improvement 启用。选择实际的 技能／hook 路径，检查本地补丁，并在替换旧副本前妥善保留它。

Hook 会在 agent:bootstrap 时触发（注入提醒，并在自动检测到有待审核的错误时添加待分类提示），还会在 command:new／command:reset 时触发（扫描已结束会话的记录，将错误模式写入 <workspace>/.learnings/ERRORS.md；需主动选择启用——仅当 .learnings/ 存在时才运行）。内部 HOOK.md 事件没有针对每次工具调用的回调，因此此集成会在会话结束时检测错误。OpenClaw 的类型化插件 Hook 另行提供 after_tool_call。请参阅 Hook 系统和限制。

日志格式

使用 assets/LEARNINGS.md、assets/ERRORS.md 或 assets/FEATURE_REQUESTS.md 中的模板追加条目。保留观察结果、背景、建议的操作和元数据。已完成条目的示例请参阅示例。

记录时，请为每项可复用的主张添加下方的 Maintenance 区块。如果尚未得出任何推断，请记录 Claim: unknown — needs triage，而不要编造规则。旧条目仍然是有效日志记录：仅在记录或相关审核中涉及该条目时初始化元数据，不要批量迁移。

Maintenance：按原因进行上下文衰减

历史观察不会过期。应维护可复用的推断或指令，而不是维护事件是否发生过。此规则适用于所有三个 .learnings/ 文件，包括一次性条目和未提升的条目。真实性与实用性是不同的：真实信息可能与当前任务无关；实用的变通方案也可能已不再正确。

类型决定如何重新验证

类型	检查
reality	阅读当前权威来源，或检查当前环境，以验证限定范围内的事实。
decision	查找权威且适用的替代决策；确认其适用范围和生效状态。时间久远或其他团队做出的选择并不能取代它。
dependency	确认相关版本／配置，然后在该环境中进行有代表性的行为验证。升级会触发检查，但不会自动使其失效。
relevance	评估其对当前任务／项目的适用性和实用性。不再使用并不能证明它是错的。

原因尚未明确时，请使用 unknown。如果一项主张涉及多个原因，请逐一检查，或将不同主张拆分到各自命名的 Maintenance 区块中。不要根据优先级、状态、重复出现情况或 Pattern-Key 正则表达式匹配结果推断语义类型／比率。会话扫描可能混入彼此无关的错误：请在分类时判定主张类型，同时保留并链接原始扫描结果。

Rate 决定何时复查

• fast：易变；在每次相关使用前后检查。
• medium：在工作期间的相关任务／项目里程碑时重新审视。
• slow：稳定；在相关重大变更或里程碑时偶尔复查。
• durable：预期会持续有效；当权威性、假设或适用性受到质疑时复查。
• unknown：尚无有依据的频率；依赖之前先进行分流。

这些频率是定性的，并非通用的半衰期、到期日或删除规则。为该声明记录一个具体触发条件。相关事件（来源更新、被取代的决策、依赖项／配置变更、项目／任务变动、矛盾）优先于复查频率，即使对 durable 声明也不例外。无需调度器或自主后台重新验证。

在原始条目旁添加轻量级元数据

### Maintenance
- Claim: reusable inference/instruction, or unknown — needs triage
- Scope: applicable project/task/environment and limits, or unknown
- Authority: source path/section, decision ID, environment, or unknown
- Decay: reality | decision | dependency | relevance | unknown / fast | medium | slow | durable | unknown
- Revalidate: event/cadence; specific check to perform
- Validation: pending | verified | unresolved | contradicted
- Evidence: none yet; when checked, actual date, source/version/configuration, check and result (including failures/conflicts)
- Disposition: retain | revise | externalize | retire; reason and task applicability
- Guidance: none, or target file + section and source-learning ID

除非实际证据支持更高的状态，否则从 Validation: pending、Evidence: none yet 和 Disposition: retain — provisional, not validated 开始。尝试复查不等于验证：证据不可用或相互冲突时，仍标记为 unresolved，并记录尝试日期、阻碍因素和下次检查时间；不要更新成功验证日期。追加后续结果时，保留过往证据的日期和适用范围。Status 跟踪问题的解决／晋级情况，Validation 跟踪对声明的支持情况，Disposition 跟踪当前有效的指导；三者互不代表彼此。

审查、复用与推广闭环

1. 选择：按领域、文件、关键词或来源 ID 选择与当前任务相关的条目，并在自然的检查节点纳入受影响或到期的声明。不要每轮都审查整个日志，也不要只选择待处理、已推广或重复出现的条目。
2. 分诊：梳理旧条目或混合条目，识别可复用的声明、范围、权威性、类型/频率和触发条件。明确保留未知信息。已解决的事件、成功恢复或重复发生，都不能证明某条规则普遍有效。
3. 检查：在复用或推广前，确认适用性，以及触发条件是否已触发或证据是否到期。必要时执行与类型相符的检查；记录实际证据，而非计划执行的命令。如果证据缺失或相互矛盾，不要将该声明作为已验证内容呈现或推广。明确说明不确定性，并查找来源或采用范围恰当的备用方案；受阻期间不要移除保护措施。
4. 选择 retain（有依据且有用，或受阻期间明确标记为暂定）、revise（根据证据纠正或缩小范围）、externalize（用可用的检索说明替换易变细节）或 retire（以有依据的理由将其排除在有效指南之外）。外部化时，应说明去哪里查找、阅读或测试什么，以及遇到无法访问或内容冲突时该怎么做；笼统地说“查阅文档”是不够的。将检索路径视为已验证之前，先确认它确实可用。
5. 记录并传播：追加带日期的审查说明，记录结果、理由、证据，以及变更时的旧声明 → 新声明。保留原始观察、解决方案、推广目标/日期和以往审查记录。不要仅仅因为进行了审查就增加 Recurrence-Count/Last-Seen。

绝不抹除学习/推广历史，也不要按时间长短删除条目。不要仅因用户偏好、安全策略或技能资源过时或未使用，就更改用户偏好、削弱安全策略或改写技能资源。创建/修改技能需要明确且范围限定的批准；对本次集成的批准不代表授权今后改写技能。如果所需目标编辑超出已授权范围，请在来源条目中将拟议更改记录为待处理，并报告仍然有效的指南，不要默默声称已完成更新。

如需查看经过实际验证的审查结果及来源信息，请阅读维护示例。 如需评估维护说明，请使用维护行为评估中的隔离场景。 这些是评估用例，不是日常学习记录期间要运行的检查。

ID 生成

格式：TYPE-YYYYMMDD-XXX

• TYPE：LRN（学习）、ERR（错误）、FEAT（功能）
• YYYYMMDD：当前日期
• XXX：顺序编号或 3 个随机字符（例如，001、A7B）

示例：LRN-20250115-001、ERR-20250115-A3F、FEAT-20250115-002

解决条目

问题修复后，更新条目：

1. 将 **Status**: pending 更改为 **Status**: resolved
2. 在 Metadata 后添加解决方案块：

### Resolution
- **Resolved**: 2025-01-16T09:00:00Z
- **Commit/PR**: abc123 or #42
- **Notes**: Brief description of what was done

其他状态值：

• in_progress - 正在处理
• wont_fix - 决定不予处理（在 Resolution notes 中添加原因）
• promoted - 已提升至工作区文件（SOUL.md、TOOLS.md、AGENTS.md）

推广时保留 Resolution 块。已生效的修复说明了该事件中发生的情况；任何可复用规则都应通过维护流程单独验证。

推广至工作区记忆

当某项学习具有广泛适用性（而非一次性修复）时，将其推广至工作区文件，使每个会话都能继承。

何时推广

• 学习适用于多个文件/功能
• 任何贡献者（人类或 AI）都应该了解的知识
• 有助于防止重复错误
• 记录项目特定约定

推广目标

目标	适用内容
SOUL.md	行为准则、沟通风格、原则
TOOLS.md	工具能力、使用模式、集成注意事项
AGENTS.md	工作流、委派模式、自动化规则

如果经验仅适用于你参与的某个项目仓库（而非工作区），请将其推广到该项目自己的 Agent 文件中（例如该项目的 AGENTS.md）。

如何推广

1. 审查：先通过 Maintenance 审查所限定的声明。仅推广有依据且有用的指导，不要推广尚未解决的假设，也不要仅凭重复出现就推广。
2. 提炼并添加：在适当的目标文件中添加简洁、范围明确的规则或可用的检索说明。将 Source: .learnings/<file>.md#<entry-ID> 写在旁边（使用目标文件中的实际相对路径；即使渲染器生成的锚点不同，也可以通过 ID 搜索）。
3. 更新原始条目：将 **Status** 设为 promoted，追加推广日期和目标文件／章节，并将 Guidance 设为该位置。保留任何解决记录和此前的推广历史。之后的修订遵循这项双向链接。

推广示例

经验（冗长）：

项目使用 pnpm 工作区。尝试过 npm install，但失败了。
锁文件是 pnpm-lock.yaml。必须使用 pnpm install。

在 TOOLS.md 中（检查检索路径后外化）：

## Build & Dependencies
- Before installing, read this repo's `package.json` `packageManager` field and lockfile. Use the declared manager; if missing or conflicting, consult the build instructions/maintainer before installing. Source: .learnings/LEARNINGS.md#LRN-20250115-002

经验（冗长）：

修改 API 端点时，必须重新生成 TypeScript 客户端。
忘记这一步会导致运行时类型不匹配。

在 AGENTS.md 中（可执行）：

## After API Changes
1. Regenerate client: `pnpm run generate:api`
2. Check for type errors: `pnpm tsc --noEmit`
Source: .learnings/LEARNINGS.md#LRN-20250116-001 (scope: this repo's current generator/configuration)

模式键分类

Pattern-Key 是所有三个日志文件中条目的稳定去重和复发键：关键词 grep 会漏掉语义相同但措辞不同的条目，而共用一个键不会——可靠的键正是让 Recurrence-Count 和推广规则发挥作用的基础。

格式：area.symptom——恰好两级，使用小写字母和连字符 （例如 deps.module-not-found）。症状应保持通用，以便在未来重复出现：键中不要包含文件名、版本或主机名。

区域	范围	示例键
api	外部 API／服务行为	api.rate-limit、api.schema-mismatch、api.missing-endpoint
auth	凭据、令牌、作用域	auth.token-expired、auth.missing-scope
build	编译、打包、CI	build.type-error、build.missing-artifact
config	配置文件、环境变量、设置	config.missing-env、config.invalid-json
deps	包管理器、依赖项	deps.module-not-found、deps.npm-error、deps.version-conflict
fs	文件系统	fs.no-such-file、fs.permission-denied
net	网络连接	net.connection-refused、net.timeout
runtime	上述类别未涵盖的语言／运行时错误	runtime.type-error、runtime.python-exception
shell	Shell／命令行机制	shell.command-not-found、shell.nonzero-exit
vcs	Git 和其他版本控制	vcs.fatal-error、vcs.merge-conflict
simplify / harden	来自 simplify-and-harden feed 的代码质量模式	simplify.dead_code、harden.input_validation

规则：

1. 先复用，再创建：grep -rh "Pattern-Key:" .learnings/ | sort -u——有近似匹配时，优先使用现有键。
2. 每个人工录入的条目使用一个键；自动扫描的 OpenClaw 条目可能带有多个键——请分别整理无关的声明，并链接到保留的扫描记录。
3. 谨慎创建新区域——只有多个条目会共用该区域时才创建。
4. 通用扫描键（runtime.error、runtime.failure）表示“未分类”——请在整理时将其替换为具体键。

重复模式检测

如果要记录的内容与现有条目相似：

1. 先按键搜索：grep -n "Pattern-Key: area.symptom" .learnings/*.md — 这是默认的去重检查，可发现关键词搜索会漏掉的改写内容
2. 再进行关键词搜索：对未设置键的条目，使用 grep -ri "keyword" .learnings/ 搜索
3. 合并，不要重复：确认主张和范围相同，而不只是键匹配。对于真正的新发生情况，增加 Recurrence-Count，设置 Last-Seen，并链接证据；审查或重新阅读不算重复发生
4. 如果问题持续重复发生，则提高优先级
5. 考虑系统性修复：重复出现的问题通常意味着：
   • 知识缺失（→ 提升至 TOOLS.md 或 SOUL.md）
   • 自动化缺失（→ 添加到 AGENTS.md）
   • 架构问题（→ 创建技术债务工单）

简化与加固信息流

如果任务提供了简化／加固候选项，请在此处录入；无需其他技能。手动记录时也遵循相同的重复发生和维护规则。

录入工作流

1. 从任务摘要中读取 simplify_and_harden.learning_loop.candidates。
2. 对每个候选项，使用 pattern_key 作为稳定的去重键。
3. 在 .learnings/LEARNINGS.md 中搜索是否已有使用该键的条目：
   • grep -n "Pattern-Key: <pattern_key>" .learnings/LEARNINGS.md
4. 如果找到：
   • 仅当同一范围的主张再次发生时，才增加 Recurrence-Count 并更新 Last-Seen
   • 添加指向相关条目／任务的 See Also 链接
5. 如果未找到：
   • 创建新的 LRN-... 条目
   • 设置 Source: simplify-and-harden
   • 设置 Pattern-Key、Recurrence-Count: 1 和 First-Seen／Last-Seen

提升规则（系统提示词反馈）

满足以下所有条件时，可考虑提升重复模式：

• Recurrence-Count >= 3
• 在至少 2 个不同任务中出现
• 在 30 天内发生

这些只是候选信号，并非证明或过期规则。提升前先执行维护；即使不满足这些阈值，一次性经验仍须维护。

提升目标：SOUL.md、TOOLS.md 或 AGENTS.md（工作区），或者模式仅与项目相关时，提升至项目自身的 Agent 文件。

将提升后的规则写成简短的预防规则（说明编码前／编码时应做什么），不要写成长篇事故报告。

定期审查

在适当的工作间隙，使用维护流程审查相关／到期的主张；不要每轮都审查整个日志：

审查时机

• 开始新的重大任务前
• 完成一项功能后
• 在曾有相关经验的领域开展工作时
• 活跃开发期间每周一次

快速状态检查

# Count pending items
grep -h "Status\*\*: pending" .learnings/*.md | wc -l

# List pending high-priority items
grep -B5 "Priority\*\*: high" .learnings/*.md | grep "^## \["

# Find learnings for a specific area
grep -l "Area\*\*: backend" .learnings/*.md

审查操作

• 解决已修复的事项
• 重新验证相关／到期的主张，无论其状态如何，包括一次性／未提升的经验
• 保留、修订、外部化或淘汰现行指导，同时保留历史记录
• 提升有依据且适用的经验，并附上来源链接
• 链接相关条目
• 升级处理重复出现的问题

检测触发条件

记录前，应结合上下文评估事件。以下短语只是提示， 并非自动记录命令；仅有普通问题和后续任务 不足以成为创建持久条目的理由。

纠正（→ 使用 correction 类别进行学习）：

• “不对，这不正确……”
• “其实应该是……”
• “你说错了……”
• “那已经过时了……”

功能请求（→ 功能请求）：

• 仅当有证据表明相关工具或版本缺少所请求的功能时才记录。记录证据和限制。
• “能不能再……？”或“有没有办法……？”并不能证明缺少某项功能。应正常使用现有功能；不要记录普通的后续请求。
• 如果功能是否可用尚不明确，请查阅文档或检查工具行为，或询问。不要仅凭措辞创建功能请求。

知识缺口（→ 使用 knowledge_gap 类别进行学习）：

• 用户提供了你不知道的信息
• 你引用的文档已过时
• API 行为与你的理解不同

错误（→ 错误条目）：

• 命令返回非零退出代码
• 异常或堆栈跟踪
• 意外的输出或行为
• 超时或连接失败

优先级指南

优先级	使用场景
critical	阻碍核心功能，存在数据丢失风险或安全问题
high	影响重大，会影响常见工作流或问题反复出现
medium	影响中等，存在变通方法
low	轻微不便，边缘情况，锦上添花

区域标签

用于按代码库区域筛选学习记录：

区域	范围
frontend	UI、组件、客户端代码
backend	API、服务、服务端代码
infra	CI/CD、部署、Docker、云
tests	测试文件、测试工具、覆盖率
docs	文档、注释、README
config	配置文件、环境、设置

最佳实践

1. 立即记录 - 问题刚发生后，上下文最清晰
2. 具体说明 - 让后续 Agent 能快速理解
3. 包含复现步骤 - 尤其是错误
4. 关联相关文件 - 让修复更容易
5. 提出具体修复建议 - 不要只说“调查一下”
6. 使用一致的类别 - 便于筛选
7. 推广有依据的指导 - 先验证范围和实用性；保留来源信息
8. 根据原因和发生频率进行复核 - 仅凭时间久远既不能证明内容错误，也不能证明内容无用

Gitignore 选项

仅在本地保留学习记录（每位开发者各自保留）：

.learnings/

此仓库采用该默认设置，以免意外提交敏感或嘈杂的本地日志。

在仓库中跟踪学习记录（整个团队共享）： 不要添加到 .gitignore - 学习记录将成为共享知识。

混合模式（跟踪模板，忽略条目）：

.learnings/*.md
!.learnings/.gitkeep

升级与卸载

升级前请阅读 CHANGELOG.md — 其中包含各版本的说明；钩子变更需要重新复制钩子并重启网关。 要停用或移除此技能，请按 references/uninstall.md 中的说明操作： 停用和卸载会保留 .learnings/ 和已推广的工作区规则。 永久删除数据或编辑已推广的指导内容，均需另行获得明确授权；这些操作不属于卸载流程。

技能提取（需审批）

如果某条学习记录可能值得提炼为可复用技能，请使用 assets/SKILL-TEMPLATE.md。提取是可选的，绝不是维护的前置条件。创建或修改技能资源前，必须先获得明确且范围具体的批准。

模板包含候选标准、辅助命令、质量门槛和双向来源信息。提取前请审查范围具体的主张；事件已解决或问题再次发生，本身并不能作为验证依据。后续修改资源也需要另行获得范围具体的批准。