first commit

2026-03-21 18:57:10 +08:00
commit c49aa1a5e9
570 changed files with 107167 additions and 0 deletions
--- a/skills/self-improving-agent-3.0.5/SKILL.md
+++ b/skills/self-improving-agent-3.0.5/SKILL.md
@@ -0,0 +1,646 @@
+---
+name: self-improvement
+description: "记录 learnings、errors 和 corrections，以支持持续改进。适用于：(1) 命令或操作意外失败，(2) 用户纠正 Claude（'No, that's wrong...', 'Actually...'），(3) 用户请求当前不存在的能力，(4) 外部 API 或工具失败，(5) Claude 意识到自己的知识已过时或不正确，(6) 为重复任务发现了更好的处理方式。在开始重大任务前，也应先回顾 learnings。"
+metadata:
+---
+
+# Self-Improvement Skill
+
+将 learnings 和 errors 记录到 markdown 文件中，以支持持续改进。后续 coding agents 可以基于这些记录推进修复，而重要的学习项则可以提升为项目级 memory。
+
+## 快速参考
+
+| Situation | Action |
+|-----------|--------|
+| Command/operation fails | 记录到 `.learnings/ERRORS.md` |
+| User corrects you | 以 `correction` category 记录到 `.learnings/LEARNINGS.md` |
+| User wants missing feature | 记录到 `.learnings/FEATURE_REQUESTS.md` |
+| API/external tool fails | 将集成细节记录到 `.learnings/ERRORS.md` |
+| Knowledge was outdated | 以 `knowledge_gap` category 记录到 `.learnings/LEARNINGS.md` |
+| Found better approach | 以 `best_practice` category 记录到 `.learnings/LEARNINGS.md` |
+| Simplify/Harden recurring patterns | 使用 `Source: simplify-and-harden` 和稳定的 `Pattern-Key` 记录或更新 `.learnings/LEARNINGS.md` |
+| Similar to existing entry | 通过 `**See Also**` 建立关联，并考虑提升优先级 |
+| Broadly applicable learning | 提升到 `CLAUDE.md`、`AGENTS.md` 和/或 `.github/copilot-instructions.md` |
+| Workflow improvements | 提升到 `AGENTS.md`（OpenClaw workspace） |
+| Tool gotchas | 提升到 `TOOLS.md`（OpenClaw workspace） |
+| Behavioral patterns | 提升到 `SOUL.md`（OpenClaw workspace） |
+
+## OpenClaw Setup（推荐）
+
+OpenClaw 是这个 skill 的主要运行平台。它通过基于 workspace 的 prompt injection 和自动 skill loading 工作。
+
+### Installation
+
+**Via ClawdHub（推荐）：**
+```bash
+clawdhub install self-improving-agent
+```
+
+**Manual：**
+```bash
+git clone https://github.com/peterskoett/self-improving-agent.git ~/.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
+
+### Workspace Structure
+
+OpenClaw 会将这些文件注入到每个 session 中：
+
+```
+~/.openclaw/workspace/
+├── AGENTS.md          # 多代理工作流与委派模式
+├── SOUL.md            # 行为指导、个性与原则
+├── TOOLS.md           # 工具能力、集成 gotchas
+├── MEMORY.md          # 长期 memory（仅主 session）
+├── memory/            # 每日 memory 文件
+│   └── YYYY-MM-DD.md
+└── .learnings/        # 本 skill 的日志文件
+    ├── LEARNINGS.md
+    ├── ERRORS.md
+    └── FEATURE_REQUESTS.md
+```
+
+### Create Learning Files
+
+```bash
+mkdir -p ~/.openclaw/workspace/.learnings
+```
+
+然后创建这些日志文件（或从 `assets/` 复制）：
+- `LEARNINGS.md` — corrections、knowledge gaps、best practices
+- `ERRORS.md` — command failures、exceptions
+- `FEATURE_REQUESTS.md` — 用户请求的 capabilities
+
+### Promotion Targets
+
+当 learnings 被证明具有广泛适用性时，将它们提升到 workspace 文件：
+
+| Learning Type | Promote To | Example |
+|---------------|------------|---------|
+| Behavioral patterns | `SOUL.md` | "Be concise, avoid disclaimers" |
+| Workflow improvements | `AGENTS.md` | "Spawn sub-agents for long tasks" |
+| Tool gotchas | `TOOLS.md` | "Git push needs auth configured first" |
+
+### Inter-Session Communication
+
+OpenClaw 提供了这些工具，用于跨 session 共享 learnings：
+
+- **sessions_list** — 查看活跃/最近 session
+- **sessions_history** — 读取另一个 session 的 transcript
+- **sessions_send** — 向另一个 session 发送 learning
+- **sessions_spawn** — 为后台工作启动 sub-agent
+
+### Optional: Enable Hook
+
+如需在 session 启动时自动提醒：
+
+```bash
+# Copy hook to OpenClaw hooks directory
+cp -r hooks/openclaw ~/.openclaw/hooks/self-improvement
+
+# Enable it
+openclaw hooks enable self-improvement
+```
+
+完整细节见 `references/openclaw-integration.md`。
+
+---
+
+## Generic Setup（其他 agents）
+
+对于 Claude Code、Codex、Copilot 或其他 agents，在你的项目中创建 `.learnings/`：
+
+```bash
+mkdir -p .learnings
+```
+
+从 `assets/` 复制模板，或自行创建带标题的文件。
+
+### 在 agent 文件 AGENTS.md、CLAUDE.md 或 .github/copilot-instructions.md 中加入提示，提醒自己记录 learnings。（这是 hook-based reminders 的替代方案）
+
+#### Self-Improvement Workflow
+
+当出现 errors 或 corrections 时：
+1. 记录到 `.learnings/ERRORS.md`、`LEARNINGS.md` 或 `FEATURE_REQUESTS.md`
+2. 回顾并将具有广泛适用性的 learnings 提升到：
+   - `CLAUDE.md` - 项目事实和约定
+   - `AGENTS.md` - workflow 和 automation
+   - `.github/copilot-instructions.md` - Copilot 上下文
+
+## Logging Format
+
+### Learning Entry
+
+追加到 `.learnings/LEARNINGS.md`：
+
+```markdown
+## [LRN-YYYYMMDD-XXX] category
+
+**Logged**: ISO-8601 timestamp
+**Priority**: low | medium | high | critical
+**Status**: pending
+**Area**: frontend | backend | infra | tests | docs | config
+
+### Summary
+用一行描述本次学到了什么
+
+### Details
+完整上下文：发生了什么、哪里错了、正确做法是什么
+
+### Suggested Action
+建议采取的具体修复或改进措施
+
+### Metadata
+- Source: conversation | error | user_feedback
+- Related Files: path/to/file.ext
+- Tags: tag1, tag2
+- See Also: LRN-20250110-001 (if related to existing entry)
+- Pattern-Key: simplify.dead_code | harden.input_validation (optional, for recurring-pattern tracking)
+- Recurrence-Count: 1 (optional)
+- First-Seen: 2025-01-15 (optional)
+- Last-Seen: 2025-01-15 (optional)
+
+---
+```
+
+### Error Entry
+
+追加到 `.learnings/ERRORS.md`：
+
+```markdown
+## [ERR-YYYYMMDD-XXX] skill_or_command_name
+
+**Logged**: ISO-8601 timestamp
+**Priority**: high
+**Status**: pending
+**Area**: frontend | backend | infra | tests | docs | config
+
+### Summary
+简要说明失败了什么
+
+### Error
+```
+Actual error message or output
+```
+
+### Context
+- 尝试执行的 command/operation
+- 使用的输入或参数
+- 如有必要，补充环境细节
+
+### Suggested Fix
+如果能够识别，写明可能的解决方式
+
+### Metadata
+- Reproducible: yes | no | unknown
+- Related Files: path/to/file.ext
+- See Also: ERR-20250110-001 (if recurring)
+
+---
+```
+
+### Feature Request Entry
+
+追加到 `.learnings/FEATURE_REQUESTS.md`：
+
+```markdown
+## [FEAT-YYYYMMDD-XXX] capability_name
+
+**Logged**: ISO-8601 timestamp
+**Priority**: medium
+**Status**: pending
+**Area**: frontend | backend | infra | tests | docs | config
+
+### Requested Capability
+用户想要完成的能力
+
+### User Context
+他们为什么需要它，要解决什么问题
+
+### Complexity Estimate
+simple | medium | complex
+
+### Suggested Implementation
+可以如何实现，它可能扩展哪部分能力
+
+### Metadata
+- Frequency: first_time | recurring
+- Related Features: existing_feature_name
+
+---
+```
+
+## ID Generation
+
+格式：`TYPE-YYYYMMDD-XXX`
+- TYPE: `LRN`（learning）、`ERR`（error）、`FEAT`（feature）
+- YYYYMMDD: 当前日期
+- XXX: 顺序号或随机 3 个字符（例如 `001`、`A7B`）
+
+示例：`LRN-20250115-001`、`ERR-20250115-A3F`、`FEAT-20250115-002`
+
+## Resolving Entries
+
+当问题被修复后，更新该 entry：
+
+1. 将 `**Status**: pending` 改为 `**Status**: resolved`
+2. 在 Metadata 后追加 resolution block：
+
+```markdown
+### Resolution
+- **Resolved**: 2025-01-16T09:00:00Z
+- **Commit/PR**: abc123 or #42
+- **Notes**: 简要描述做了什么
+```
+
+其他 status 值：
+- `in_progress` - 正在处理
+- `wont_fix` - 决定不处理（在 Resolution notes 中补充原因）
+- `promoted` - 已提升到 CLAUDE.md、AGENTS.md 或 .github/copilot-instructions.md
+
+## Promoting to Project Memory
+
+当某条 learning 具有广泛适用性（不是一次性修复）时，将它提升为永久性的项目 memory。
+
+### When to Promote
+
+- 该 learning 适用于多个文件/功能
+- 是任何 contributor（human 或 AI）都应该知道的知识
+- 能防止重复犯错
+- 记录了项目特定的约定
+
+### Promotion Targets
+
+| Target | What Belongs There |
+|--------|-------------------|
+| `CLAUDE.md` | 所有 Claude 交互都应知道的项目事实、约定、gotchas |
+| `AGENTS.md` | agent 专用 workflow、tool usage patterns、automation rules |
+| `.github/copilot-instructions.md` | GitHub Copilot 的项目上下文与约定 |
+| `SOUL.md` | 行为指导、沟通风格、原则（OpenClaw workspace） |
+| `TOOLS.md` | 工具能力、usage patterns、integration gotchas（OpenClaw workspace） |
+
+### How to Promote
+
+1. **Distill**：将 learning 提炼成简洁的规则或事实
+2. **Add**：加入目标文件的适当 section（如无则创建）
+3. **Update** 原始 entry：
+   - 将 `**Status**: pending` 改为 `**Status**: promoted`
+   - 添加 `**Promoted**: CLAUDE.md`、`AGENTS.md` 或 `.github/copilot-instructions.md`
+
+### Promotion Examples
+
+**Learning**（详细版）：
+> Project uses pnpm workspaces. Attempted `npm install` but failed.
+> Lock file is `pnpm-lock.yaml`. Must use `pnpm install`.
+
+**在 CLAUDE.md 中**（简洁版）：
+```markdown
+## Build & Dependencies
+- Package manager: pnpm (not npm) - use `pnpm install`
+```
+
+**Learning**（详细版）：
+> When modifying API endpoints, must regenerate TypeScript client.
+> Forgetting this causes type mismatches at runtime.
+
+**在 AGENTS.md 中**（可执行版）：
+```markdown
+## After API Changes
+1. Regenerate client: `pnpm run generate:api`
+2. Check for type errors: `pnpm tsc --noEmit`
+```
+
+## Recurring Pattern Detection
+
+如果你记录的内容与已有 entry 类似：
+
+1. **Search first**：`grep -r "keyword" .learnings/`
+2. **Link entries**：在 Metadata 中添加 `**See Also**: ERR-20250110-001`
+3. 如果问题持续复发，**Bump priority**
+4. **Consider systemic fix**：重复问题往往意味着：
+   - 缺少 documentation（→ 提升到 CLAUDE.md 或 .github/copilot-instructions.md）
+   - 缺少 automation（→ 加到 AGENTS.md）
+   - 存在 architectural problem（→ 创建 tech debt ticket）
+
+## Simplify & Harden Feed
+
+使用这套 workflow 吸收 `simplify-and-harden`
+skill 中反复出现的模式，并将其转化为更持久的 prompt guidance。
+
+### Ingestion Workflow
+
+1. 从任务总结中读取 `simplify_and_harden.learning_loop.candidates`。
+2. 对每个 candidate，使用 `pattern_key` 作为稳定的 dedupe key。
+3. 在 `.learnings/LEARNINGS.md` 中搜索是否已存在该 key 对应的 entry：
+   - `grep -n "Pattern-Key: <pattern_key>" .learnings/LEARNINGS.md`
+4. 如果已存在：
+   - 增加 `Recurrence-Count`
+   - 更新 `Last-Seen`
+   - 为相关 entries/tasks 添加 `See Also` links
+5. 如果不存在：
+   - 创建新的 `LRN-...` entry
+   - 设置 `Source: simplify-and-harden`
+   - 设置 `Pattern-Key`、`Recurrence-Count: 1` 以及 `First-Seen`/`Last-Seen`
+
+### Promotion Rule（System Prompt Feedback）
+
+当以下条件同时满足时，将 recurring patterns 提升到 agent context/system prompt files：
+
+- `Recurrence-Count >= 3`
+- 出现在至少 2 个不同任务中
+- 发生在 30 天窗口内
+
+Promotion targets：
+- `CLAUDE.md`
+- `AGENTS.md`
+- `.github/copilot-instructions.md`
+- 在适用时，提升到 `SOUL.md` / `TOOLS.md` 作为 OpenClaw workspace-level guidance
+
+写入被提升的规则时，要写成简短的 prevention rules（编码前/编码中该做什么），而不是冗长的 incident write-ups。
+
+## Periodic Review
+
+在自然断点回顾 `.learnings/`：
+
+### When to Review
+- 开始新的重大任务前
+- 完成一个 feature 后
+- 进入某个已有历史 learning 的 area 时
+- 活跃开发期间每周一次
+
+### Quick Status Check
+```bash
+# 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
+```
+
+### Review Actions
+- 解决已修复的 items
+- 提升适合沉淀的 learnings
+- 关联相关 entries
+- 升级 recurring issues
+
+## Detection Triggers
+
+当你注意到这些情况时，自动记录：
+
+**Corrections**（→ 使用 `correction` category 的 learning）：
+- "No, that's not right..."
+- "Actually, it should be..."
+- "You're wrong about..."
+- "That's outdated..."
+
+**Feature Requests**（→ feature request）：
+- "Can you also..."
+- "I wish you could..."
+- "Is there a way to..."
+- "Why can't you..."
+
+**Knowledge Gaps**（→ 使用 `knowledge_gap` category 的 learning）：
+- 用户提供了你此前不知道的信息
+- 你引用的 documentation 已过时
+- API behavior 与你的理解不一致
+
+**Errors**（→ error entry）：
+- command 返回 non-zero exit code
+- exception 或 stack trace
+- 非预期输出或行为
+- timeout 或 connection failure
+
+## Priority Guidelines
+
+| Priority | When to Use |
+|----------|-------------|
+| `critical` | 阻塞核心功能、存在数据丢失风险、安全问题 |
+| `high` | 影响显著、影响常见 workflow、重复出现的问题 |
+| `medium` | 影响中等，存在 workaround |
+| `low` | 轻微不便、边缘 case、nice-to-have |
+
+## Area Tags
+
+用于按 codebase 区域筛选 learnings：
+
+| Area | Scope |
+|------|-------|
+| `frontend` | UI、components、client-side code |
+| `backend` | API、services、server-side code |
+| `infra` | CI/CD、deployment、Docker、cloud |
+| `tests` | test files、testing utilities、coverage |
+| `docs` | documentation、comments、READMEs |
+| `config` | configuration files、environment、settings |
+
+## Best Practices
+
+1. **Log immediately** - 问题刚出现时上下文最完整
+2. **Be specific** - 未来的 agents 需要快速理解
+3. **Include reproduction steps** - 对 errors 尤其重要
+4. **Link related files** - 让修复更容易
+5. **Suggest concrete fixes** - 不要只写 "investigate"
+6. **Use consistent categories** - 便于过滤
+7. **Promote aggressively** - 如果拿不准，就加到 CLAUDE.md 或 .github/copilot-instructions.md
+8. **Review regularly** - 过期的 learnings 会迅速失去价值
+
+## Gitignore Options
+
+**Keep learnings local**（按开发者本地保留）：
+```gitignore
+.learnings/
+```
+
+**Track learnings in repo**（团队共享）：
+不要添加到 `.gitignore` 中，这样 learnings 会成为共享知识。
+
+**Hybrid**（跟踪模板，忽略具体 entries）：
+```gitignore
+.learnings/*.md
+!.learnings/.gitkeep
+```
+
+## Hook Integration
+
+通过 agent hooks 启用自动提醒。该能力是 **opt-in** 的，你必须显式配置 hooks。
+
+### Quick Setup（Claude Code / Codex）
+
+在项目中创建 `.claude/settings.json`：
+
+```json
+{
+  "hooks": {
+    "UserPromptSubmit": [{
+      "matcher": "",
+      "hooks": [{
+        "type": "command",
+        "command": "./skills/self-improvement/scripts/activator.sh"
+      }]
+    }]
+  }
+}
+```
+
+这会在每次 prompt 后注入一个 learning evaluation reminder（约增加 50-100 tokens 开销）。
+
+### Full Setup（带 Error Detection）
+
+```json
+{
+  "hooks": {
+    "UserPromptSubmit": [{
+      "matcher": "",
+      "hooks": [{
+        "type": "command",
+        "command": "./skills/self-improvement/scripts/activator.sh"
+      }]
+    }],
+    "PostToolUse": [{
+      "matcher": "Bash",
+      "hooks": [{
+        "type": "command",
+        "command": "./skills/self-improvement/scripts/error-detector.sh"
+      }]
+    }]
+  }
+}
+```
+
+### Available Hook Scripts
+
+| Script | Hook Type | Purpose |
+|--------|-----------|---------|
+| `scripts/activator.sh` | UserPromptSubmit | 提醒在任务结束后回顾 learnings |
+| `scripts/error-detector.sh` | PostToolUse (Bash) | 在 command errors 出现时触发 |
+
+详见 `references/hooks-setup.md` 中的详细配置与故障排查。
+
+## Automatic Skill Extraction
+
+当某条 learning 足够有价值，可以演化为可复用的 skill 时，使用提供的 helper 进行提取。
+
+### Skill Extraction Criteria
+
+当满足以下任意条件时，这条 learning 就适合做 skill extraction：
+
+| Criterion | Description |
+|-----------|-------------|
+| **Recurring** | 有 2 条以上相似问题的 `See Also` links |
+| **Verified** | `Status` 为 `resolved`，并且 fix 已验证可用 |
+| **Non-obvious** | 需要真实 debugging/investigation 才能发现 |
+| **Broadly applicable** | 不是项目特定问题；对多个 codebase 都有帮助 |
+| **User-flagged** | 用户明确说 “save this as a skill” 或类似表达 |
+
+### Extraction Workflow
+
+1. **Identify candidate**：该 learning 满足 extraction criteria
+2. **Run helper**（或手动创建）：
+   ```bash
+   ./skills/self-improvement/scripts/extract-skill.sh skill-name --dry-run
+   ./skills/self-improvement/scripts/extract-skill.sh skill-name
+   ```
+3. **Customize SKILL.md**：将 learning 内容填入模板
+4. **Update learning**：将 status 设为 `promoted_to_skill`，并补充 `Skill-Path`
+5. **Verify**：在新的 session 中读取该 skill，确保它是 self-contained 的
+
+### Manual Extraction
+
+如果你更偏向手工创建：
+
+1. 创建 `skills/<skill-name>/SKILL.md`
+2. 使用 `assets/SKILL-TEMPLATE.md` 中的模板
+3. 遵循 [Agent Skills spec](https://agentskills.io/specification)：
+   - 使用包含 `name` 和 `description` 的 YAML frontmatter
+   - name 必须与 folder name 一致
+   - skill folder 内不要放 README.md
+
+### Extraction Detection Triggers
+
+注意这些信号，它们通常意味着某条 learning 应该升级为 skill：
+
+**In conversation：**
+- "Save this as a skill"
+- "I keep running into this"
+- "This would be useful for other projects"
+- "Remember this pattern"
+
+**In learning entries：**
+- 存在多个 `See Also` links（说明是 recurring issue）
+- 高优先级且已 resolved
+- category 为 `best_practice` 且具有广泛适用性
+- 用户对该 solution 给出明显正向反馈
+
+### Skill Quality Gates
+
+在提取前，确认：
+
+- [ ] Solution 已测试并可用
+- [ ] Description 在脱离原始上下文后仍然清晰
+- [ ] Code examples 是 self-contained 的
+- [ ] 没有项目特定的 hardcoded values
+- [ ] 遵循 skill naming conventions（lowercase、hyphens）
+
+## Multi-Agent Support
+
+该 skill 可以在不同 AI coding agents 中工作，但 activation 方式因 agent 而异。
+
+### Claude Code
+
+**Activation**：Hooks（UserPromptSubmit、PostToolUse）
+**Setup**：在 `.claude/settings.json` 中配置 hooks
+**Detection**：通过 hook scripts 自动检测
+
+### Codex CLI
+
+**Activation**：Hooks（与 Claude Code 相同模式）
+**Setup**：在 `.codex/settings.json` 中配置 hooks
+**Detection**：通过 hook scripts 自动检测
+
+### GitHub Copilot
+
+**Activation**：手动（不支持 hooks）
+**Setup**：加入 `.github/copilot-instructions.md`：
+
+```markdown
+## Self-Improvement
+
+在解决 non-obvious issues 后，考虑将其记录到 `.learnings/`：
+1. 使用 self-improvement skill 的格式
+2. 用 See Also 关联相关 entries
+3. 将高价值 learnings 提升为 skills
+
+可以在 chat 中提问："Should I log this as a learning?"
+```
+
+**Detection**：在 session 结束时手动回顾
+
+### OpenClaw
+
+**Activation**：Workspace injection + inter-agent messaging
+**Setup**：见上文 “OpenClaw Setup” section
+**Detection**：通过 session tools 和 workspace files
+
+### Agent-Agnostic Guidance
+
+无论使用什么 agent，当你遇到以下情况时都应应用 self-improvement：
+
+1. **Discover something non-obvious** - solution 不是立刻想到的
+2. **Correct yourself** - 最初方案是错的
+3. **Learn project conventions** - 发现了未文档化的 patterns
+4. **Hit unexpected errors** - 特别是 diagnosis 很费劲时
+5. **Find better approaches** - 相比原始方案找到了更优路径
+
+### Copilot Chat Integration
+
+对于 Copilot 用户，在相关场景下可以把这句话加进 prompt：
+
+> After completing this task, evaluate if any learnings should be logged to `.learnings/` using the self-improvement skill format.
+
+也可以使用这些快速 prompts：
+- "Log this to learnings"
+- "Create a skill from this solution"
+- "Check .learnings/ for related issues"