自我改进

捕获、复盘、推广并提炼可长期复用的经验教训，使后续会话避免重复相同错误。

核心理念

本能力专用于可复用的学习，而非应对每处微小阻碍。

一条优质记录通常至少具备以下任一特征：

• 纠正了一个错误的假设。
• 揭示了项目特有的约定。
• 需要真实调试或深入调查。
• 很可能再次发生。
• 应改变未来的工作流程、记忆或工具使用方式。

切勿记录常规干扰项，例如明显拼写错误、预期中的校验失败，或无需沉淀经验即可立即解决的错误。

关键路径模型

本能力包含两个不同根目录：

1. 技能根目录（Skill root） —— 存放打包资源的位置：

   • scripts/...
   • references/...
   • assets/...

2. 工作区根目录（Workspace root） —— 项目或当前活跃工作区所在位置：

   • .learnings/LEARNINGS.md
   • .learnings/ERRORS.md
   • .learnings/FEATURE_REQUESTS.md
   • CLAUDE.md、AGENTS.md、.github/copilot-instructions.md、SOUL.md、TOOLS.md

切勿将学习记录写入已安装的技能目录中。所有操作必须始终面向工作区根目录。

快速决策表

标准工作流

1) 首先定位工作区根目录

在读写 .learnings/ 前，请先确认 WORKSPACE_ROOT。

合理默认值包括：

• 当前代码库的仓库根目录
• OpenClaw 工作区根目录
• 正在编辑文件所在的目录

若不确定，优先选择包含 .git、AGENTS.md、CLAUDE.md 或用户当前活跃项目文件的目录。

2) 如需则初始化 .learnings/

请使用辅助脚本而非手动创建文件：

python3 scripts/learnings.py init --root /absolute/path/to/workspace

该命令将生成：

• .learnings/LEARNINGS.md
• .learnings/ERRORS.md
• .learnings/FEATURE_REQUESTS.md

3) 在执行高风险任务或熟悉任务前，先复盘已有经验

以下情况建议优先复盘：

• 你正回到此前曾出现失败的模块或领域
• 任务涉及基础设施、CI、部署、鉴权、数据迁移或生成代码等敏感环节
• 用户明确表示“记住这一点”、“我们之前遇到过”等类似提示

使用辅助脚本：

python3 scripts/learnings.py status --root /absolute/path/to/workspace
python3 scripts/learnings.py search --root /absolute/path/to/workspace --query "pnpm" --limit 5

4) 记录前务必搜索，避免重复

创建新条目前，始终先搜索是否存在相关内容。

python3 scripts/learnings.py search --root /absolute/path/to/workspace --query "keyword or pattern" --limit 10

若已存在相似条目：

• 优先使用 See Also 进行链接
• 为高频问题复用或新增稳定的 Pattern-Key
• 仅当问题确实反复发生时才提升优先级
• 优先更新现有模式描述，而非分散创建近似条目

5) 正确选择条目类型进行记录

Learning

适用于事实修正、知识盲区、最佳实践及长期有效的约定。

python3 scripts/learnings.py log-learning 
  --root /absolute/path/to/workspace 
  --category correction 
  --priority high 
  --area backend 
  --summary "Project uses pnpm workspaces, not npm" 
  --details "Attempted npm install. Lockfile and workspace config showed pnpm." 
  --suggested-action "Check for pnpm-lock.yaml before assuming npm." 
  --source error 
  --related-files pnpm-lock.yaml pnpm-workspace.yaml 
  --tags package-manager,pnpm

Error

适用于非显而易见的故障、异常或值得长期记忆的工具/API 问题。

python3 scripts/learnings.py log-error 
  --root /absolute/path/to/workspace 
  --name docker-build 
  --priority high 
  --area infra 
  --summary "Docker build failed on Apple Silicon due to platform mismatch" 
  --error-text "error: failed to solve: no match for platform linux/arm64" 
  --context "docker build -t myapp . on Apple Silicon" 
  --suggested-fix "Retry with --platform linux/amd64 or update base image" 
  --reproducible yes 
  --related-files Dockerfile

Feature request

当用户提出缺失功能，或某类反复出现的使用摩擦点应被实现为正式功能时使用。

python3 scripts/learnings.py log-feature 
  --root /absolute/path/to/workspace 
  --capability export-to-csv 
  --priority medium 
  --area backend 
  --summary "User needs report export to CSV" 
  --user-context "Needed for sharing weekly reports with non-technical stakeholders" 
  --complexity-estimate simple 
  --suggested-implementation "Add --output csv alongside existing JSON output" 
  --frequency recurring 
  --related-features analyze-command,json-output

6) 将经验证的教训推广至项目记忆

当某条经验具备广泛适用性、已被多次复现，或任何未来协作者都应知晓时，即应推广。

常见目标文件包括：

• CLAUDE.md —— 长期有效的项目事实与约定
• AGENTS.md —— 工作流规则与自动化指导
• .github/copilot-instructions.md —— 共享的 Copilot 上下文
• SOUL.md —— OpenClaw 工作区中的行为准则
• TOOLS.md —— OpenClaw 工作区中各工具的典型陷阱

推广内容应写作简短的预防性规则，而非冗长的事件报告。

示例：

• 差的推广：“2026-03-12 npm 安装失败，因为……”
• 好的推广：“本仓库使用 pnpm install；这是一个 pnpm workspace。”

完成推广后，请将原始条目的状态更新为 promoted 或 promoted_to_skill，并注明目标文件。

7) 当模式真正成熟时，抽取为可复用技能

当解决方案满足以下全部条件时，应抽取为新技能：

• 已解决且运行正常
• 价值超越单个文件或单一仓库，具备跨项目通用性
• 足够非显而易见，能切实帮助未来 agent 避免同类问题
• 足够高频，值得拥有专属说明文档

使用辅助脚本：

python3 scripts/extract_skill.py 
  --root /absolute/path/to/workspace 
  docker-build-fixes 
  --description "Fix recurring Docker build and platform mismatch issues. Use when Docker builds fail due to architecture, base image, or runtime packaging problems." 
  --from-learning-id LRN-20260313-001 
  --scaffold-evals

若已有自动化流程调用旧入口点，则可保留原路径：

bash scripts/extract-skill.sh docker-build-fixes --root /absolute/path/to/workspace --dry-run

最关键的记录规范

1. 先搜索。 重复条目比缺失标签更严重。
2. 聚焦持久性经验。 仅记录那些应影响未来行为的内容。
3. 保持具体明确。 清晰指出被修正的假设、失败现象或约定本身。
4. 附带修复方案或预防规则。 没有下一步行动建议的条目效力薄弱。
5. 为高频问题使用稳定 Pattern-Key。 便于问题复现时自动聚合。
6. 规则一经验证，立即积极推广。 目标是显著减少重复失误。
7. 不因记录而打断用户。 默认静默记录；仅当用户明确要求查看，或你需要补充缺失信息时才主动呈现。

推荐参考资料

仅在必要时查阅：

• references/entry-formats.md —— 完整字段定义与手工模板
• references/examples.md —— 优质条目与推广案例
• references/promotion-and-extraction.md —— 推广规则与技能抽取标准
• references/platform-setup.md —— Claude Code、Codex、Copilot 及 OpenClaw 环境配置说明
• references/evaluation.md —— 本技能的触发/输出评估方案
• references/openclaw-integration.md —— 更深入的 OpenClaw 工作流指南

钩子（Hooks）

钩子辅助脚本为可选设计。

当前可用钩子脚本包括：

• scripts/activator.sh —— 在终端提示符启动时轻量提醒
• scripts/error-detector.sh —— 在 Bash 类命令失败后轻量提示

钩子配置示例详见 references/platform-setup.md。

本技能“进阶形态”的表现

成熟应用体现为闭环循环：

捕获 → 去重 → 推广 → 抽取 → 评估

这意味着：

• 所有条目均以确定性 ID 创建，并采用一致字段结构
• 同类问题相互链接，而非碎片化分散
• 经验证的规则持续沉淀至项目记忆文件
• 广泛适用的修复方案升格为独立技能
• 本技能自身亦通过 evals/ 中的触发与输出评估进行测试