first commit
This commit is contained in:
douboer
373
skills/self-improving-agent-3.0.5/references/examples.md
Normal file
373
skills/self-improving-agent-3.0.5/references/examples.md
Normal file
@@ -0,0 +1,373 @@
|
||||
# Entry Examples
|
||||
|
||||
这里给出字段完整、格式规范的 entries 示例。
|
||||
|
||||
## Learning: Correction
|
||||
|
||||
```markdown
|
||||
## [LRN-20250115-001] correction
|
||||
|
||||
**Logged**: 2025-01-15T10:30:00Z
|
||||
**Priority**: high
|
||||
**Status**: pending
|
||||
**Area**: tests
|
||||
|
||||
### Summary
|
||||
错误地认为 pytest fixtures 默认都是 function scope
|
||||
|
||||
### Details
|
||||
编写 test fixtures 时，我假设所有 fixtures 都是 function scope。
|
||||
用户纠正我：虽然 function scope 是默认值，但这个 codebase 的约定是，
|
||||
数据库连接这类开销较大的资源应使用 module scope，以提升 test 性能。
|
||||
|
||||
### Suggested Action
|
||||
当创建涉及昂贵初始化（DB、network）的 fixtures 时，
|
||||
不要默认用 function scope，先检查现有 fixtures 的 scope 模式。
|
||||
|
||||
### Metadata
|
||||
- Source: user_feedback
|
||||
- Related Files: tests/conftest.py
|
||||
- Tags: pytest, testing, fixtures
|
||||
|
||||
---
|
||||
```
|
||||
|
||||
## Learning: Knowledge Gap (Resolved)
|
||||
|
||||
```markdown
|
||||
## [LRN-20250115-002] knowledge_gap
|
||||
|
||||
**Logged**: 2025-01-15T14:22:00Z
|
||||
**Priority**: medium
|
||||
**Status**: resolved
|
||||
**Area**: config
|
||||
|
||||
### Summary
|
||||
项目使用 pnpm，而不是 npm，作为 package manager
|
||||
|
||||
### Details
|
||||
尝试运行 `npm install`，但项目实际上使用 pnpm workspaces。
|
||||
锁文件是 `pnpm-lock.yaml`，而不是 `package-lock.json`。
|
||||
|
||||
### Suggested Action
|
||||
在默认假设 npm 之前，先检查是否存在 `pnpm-lock.yaml` 或 `pnpm-workspace.yaml`。
|
||||
对于该项目，应使用 `pnpm install`。
|
||||
|
||||
### Metadata
|
||||
- Source: error
|
||||
- Related Files: pnpm-lock.yaml, pnpm-workspace.yaml
|
||||
- Tags: package-manager, pnpm, setup
|
||||
|
||||
### Resolution
|
||||
- **Resolved**: 2025-01-15T14:30:00Z
|
||||
- **Commit/PR**: N/A - knowledge update
|
||||
- **Notes**: 已加入 CLAUDE.md 作为后续参考
|
||||
|
||||
---
|
||||
```
|
||||
|
||||
## Learning: Promoted to CLAUDE.md
|
||||
|
||||
```markdown
|
||||
## [LRN-20250115-003] best_practice
|
||||
|
||||
**Logged**: 2025-01-15T16:00:00Z
|
||||
**Priority**: high
|
||||
**Status**: promoted
|
||||
**Promoted**: CLAUDE.md
|
||||
**Area**: backend
|
||||
|
||||
### Summary
|
||||
API responses 必须包含来自 request headers 的 correlation ID
|
||||
|
||||
### Details
|
||||
所有 API responses 都应回传请求中的 `X-Correlation-ID` header。
|
||||
这是 distributed tracing 的要求。缺少该 header 的 response
|
||||
会破坏 observability pipeline。
|
||||
|
||||
### Suggested Action
|
||||
在 API handlers 中始终加入 correlation ID passthrough。
|
||||
|
||||
### Metadata
|
||||
- Source: user_feedback
|
||||
- Related Files: src/middleware/correlation.ts
|
||||
- Tags: api, observability, tracing
|
||||
|
||||
---
|
||||
```
|
||||
|
||||
## Learning: Promoted to AGENTS.md
|
||||
|
||||
```markdown
|
||||
## [LRN-20250116-001] best_practice
|
||||
|
||||
**Logged**: 2025-01-16T09:00:00Z
|
||||
**Priority**: high
|
||||
**Status**: promoted
|
||||
**Promoted**: AGENTS.md
|
||||
**Area**: backend
|
||||
|
||||
### Summary
|
||||
修改 OpenAPI spec 后必须重新生成 API client
|
||||
|
||||
### Details
|
||||
修改 API endpoints 时，必须重新生成 TypeScript client。
|
||||
忘记执行这一步会导致 type mismatches，只在运行时才暴露出来。
|
||||
generate script 还会顺带执行 validation。
|
||||
|
||||
### Suggested Action
|
||||
把它加入 agent workflow：只要有 API 变更，就运行 `pnpm run generate:api`。
|
||||
|
||||
### Metadata
|
||||
- Source: error
|
||||
- Related Files: openapi.yaml, src/client/api.ts
|
||||
- Tags: api, codegen, typescript
|
||||
|
||||
---
|
||||
```
|
||||
|
||||
## Error Entry
|
||||
|
||||
```markdown
|
||||
## [ERR-20250115-A3F] docker_build
|
||||
|
||||
**Logged**: 2025-01-15T09:15:00Z
|
||||
**Priority**: high
|
||||
**Status**: pending
|
||||
**Area**: infra
|
||||
|
||||
### Summary
|
||||
Docker build 在 M1 Mac 上因 platform mismatch 失败
|
||||
|
||||
### Error
|
||||
```
|
||||
error: failed to solve: python:3.11-slim: no match for platform linux/arm64
|
||||
```
|
||||
|
||||
### Context
|
||||
- Command: `docker build -t myapp .`
|
||||
- Dockerfile 使用 `FROM python:3.11-slim`
|
||||
- 运行环境为 Apple Silicon（M1/M2）
|
||||
|
||||
### Suggested Fix
|
||||
在 command 中加 platform flag：`docker build --platform linux/amd64 -t myapp .`
|
||||
或者更新 Dockerfile：`FROM --platform=linux/amd64 python:3.11-slim`
|
||||
|
||||
### Metadata
|
||||
- Reproducible: yes
|
||||
- Related Files: Dockerfile
|
||||
|
||||
---
|
||||
```
|
||||
|
||||
## Error Entry: Recurring Issue
|
||||
|
||||
```markdown
|
||||
## [ERR-20250120-B2C] api_timeout
|
||||
|
||||
**Logged**: 2025-01-20T11:30:00Z
|
||||
**Priority**: critical
|
||||
**Status**: pending
|
||||
**Area**: backend
|
||||
|
||||
### Summary
|
||||
第三方 payment API 在 checkout 期间 timeout
|
||||
|
||||
### Error
|
||||
```
|
||||
TimeoutError: Request to payments.example.com timed out after 30000ms
|
||||
```
|
||||
|
||||
### Context
|
||||
- Command: POST /api/checkout
|
||||
- timeout 设为 30s
|
||||
- 高峰时段更容易发生（午间、晚间）
|
||||
|
||||
### Suggested Fix
|
||||
实现 exponential backoff retry，并考虑 circuit breaker pattern。
|
||||
|
||||
### Metadata
|
||||
- Reproducible: yes (during peak hours)
|
||||
- Related Files: src/services/payment.ts
|
||||
- See Also: ERR-20250115-X1Y, ERR-20250118-Z3W
|
||||
|
||||
---
|
||||
```
|
||||
|
||||
## Feature Request
|
||||
|
||||
```markdown
|
||||
## [FEAT-20250115-001] export_to_csv
|
||||
|
||||
**Logged**: 2025-01-15T16:45:00Z
|
||||
**Priority**: medium
|
||||
**Status**: pending
|
||||
**Area**: backend
|
||||
|
||||
### Requested Capability
|
||||
将分析结果导出为 CSV 格式
|
||||
|
||||
### User Context
|
||||
用户每周都会生成报表，需要把结果分享给非技术 stakeholders 在 Excel 中查看。
|
||||
目前他们只能手工复制输出。
|
||||
|
||||
### Complexity Estimate
|
||||
simple
|
||||
|
||||
### Suggested Implementation
|
||||
为 analyze command 增加 `--output csv` flag。使用标准 csv module。
|
||||
也可以沿用现有的 `--output json` 模式扩展。
|
||||
|
||||
### Metadata
|
||||
- Frequency: recurring
|
||||
- Related Features: analyze command, json output
|
||||
|
||||
---
|
||||
```
|
||||
|
||||
## Feature Request: Resolved
|
||||
|
||||
```markdown
|
||||
## [FEAT-20250110-002] dark_mode
|
||||
|
||||
**Logged**: 2025-01-10T14:00:00Z
|
||||
**Priority**: low
|
||||
**Status**: resolved
|
||||
**Area**: frontend
|
||||
|
||||
### Requested Capability
|
||||
dashboard 支持 dark mode
|
||||
|
||||
### User Context
|
||||
用户经常在深夜工作，觉得亮色界面太刺眼。
|
||||
另外还有几位用户也非正式提过这个需求。
|
||||
|
||||
### Complexity Estimate
|
||||
medium
|
||||
|
||||
### Suggested Implementation
|
||||
使用 CSS variables 管理颜色，并在 user settings 中加入 toggle。
|
||||
同时考虑 system preference detection。
|
||||
|
||||
### Metadata
|
||||
- Frequency: recurring
|
||||
- Related Features: user settings, theme system
|
||||
|
||||
### Resolution
|
||||
- **Resolved**: 2025-01-18T16:00:00Z
|
||||
- **Commit/PR**: #142
|
||||
- **Notes**: 已实现 system preference detection 和手动 toggle
|
||||
|
||||
---
|
||||
```
|
||||
|
||||
## Learning: Promoted to Skill
|
||||
|
||||
```markdown
|
||||
## [LRN-20250118-001] best_practice
|
||||
|
||||
**Logged**: 2025-01-18T11:00:00Z
|
||||
**Priority**: high
|
||||
**Status**: promoted_to_skill
|
||||
**Skill-Path**: skills/docker-m1-fixes
|
||||
**Area**: infra
|
||||
|
||||
### Summary
|
||||
Docker build 在 Apple Silicon 上因 platform mismatch 失败
|
||||
|
||||
### Details
|
||||
在 M1/M2 Mac 上构建 Docker images 时，build 会失败，
|
||||
因为 base image 没有 ARM64 variant。这个问题很常见，
|
||||
会影响很多开发者。
|
||||
|
||||
### Suggested Action
|
||||
在 docker build command 中添加 `--platform linux/amd64`，
|
||||
或者在 Dockerfile 中使用 `FROM --platform=linux/amd64`。
|
||||
|
||||
### Metadata
|
||||
- Source: error
|
||||
- Related Files: Dockerfile
|
||||
- Tags: docker, arm64, m1, apple-silicon
|
||||
- See Also: ERR-20250115-A3F, ERR-20250117-B2D
|
||||
|
||||
---
|
||||
```
|
||||
|
||||
## Extracted Skill Example
|
||||
|
||||
当上面的 learning 被提炼为 skill 时，会变成：
|
||||
|
||||
**File**: `skills/docker-m1-fixes/SKILL.md`
|
||||
|
||||
```markdown
|
||||
---
|
||||
name: docker-m1-fixes
|
||||
description: "修复 Apple Silicon（M1/M2）上的 Docker build failures。在 docker build 因 platform mismatch errors 失败时使用。"
|
||||
---
|
||||
|
||||
# Docker M1 Fixes
|
||||
|
||||
用于解决 Apple Silicon Mac 上的 Docker build 问题。
|
||||
|
||||
## Quick Reference
|
||||
|
||||
| Error | Fix |
|
||||
|-------|-----|
|
||||
| `no match for platform linux/arm64` | 在 build 时添加 `--platform linux/amd64` |
|
||||
| Image runs but crashes | 使用 emulation，或寻找兼容 ARM 的 base |
|
||||
|
||||
## The Problem
|
||||
|
||||
许多 Docker base images 没有 ARM64 variants。
|
||||
当在 Apple Silicon（M1/M2/M3）上构建时，Docker 默认会尝试拉取 ARM64 images，
|
||||
从而导致 platform mismatch errors。
|
||||
|
||||
## Solutions
|
||||
|
||||
### Option 1: Build Flag (Recommended)
|
||||
|
||||
在 build command 中添加 platform flag：
|
||||
|
||||
\`\`\`bash
|
||||
docker build --platform linux/amd64 -t myapp .
|
||||
\`\`\`
|
||||
|
||||
### Option 2: Dockerfile Modification
|
||||
|
||||
在 FROM instruction 中显式指定 platform：
|
||||
|
||||
\`\`\`dockerfile
|
||||
FROM --platform=linux/amd64 python:3.11-slim
|
||||
\`\`\`
|
||||
|
||||
### Option 3: Docker Compose
|
||||
|
||||
为 service 添加 platform：
|
||||
|
||||
\`\`\`yaml
|
||||
services:
|
||||
app:
|
||||
platform: linux/amd64
|
||||
build: .
|
||||
\`\`\`
|
||||
|
||||
## Trade-offs
|
||||
|
||||
| Approach | Pros | Cons |
|
||||
|----------|------|------|
|
||||
| Build flag | 不需要改文件 | 必须记得每次都加 flag |
|
||||
| Dockerfile | 显式且可版本化 | 会影响所有 builds |
|
||||
| Compose | 对开发场景方便 | 需要 compose |
|
||||
|
||||
## Performance Note
|
||||
|
||||
在 ARM64 上运行 AMD64 images 依赖 Rosetta 2 emulation。
|
||||
这对开发场景通常可行，但可能更慢。对于生产环境，应尽量寻找 ARM-native
|
||||
alternatives。
|
||||
|
||||
## Source
|
||||
|
||||
- Learning ID: LRN-20250118-001
|
||||
- Category: best_practice
|
||||
- Extraction Date: 2025-01-18
|
||||
```
|
||||
223
skills/self-improving-agent-3.0.5/references/hooks-setup.md
Normal file
223
skills/self-improving-agent-3.0.5/references/hooks-setup.md
Normal file
@@ -0,0 +1,223 @@
|
||||
# Hook Setup Guide
|
||||
|
||||
为 AI coding agents 配置自动 self-improvement triggers。
|
||||
|
||||
## Overview
|
||||
|
||||
hooks 会在关键时机注入提醒，以便主动记录 learnings：
|
||||
- **UserPromptSubmit**：每次 prompt 后提醒是否需要记录 learnings
|
||||
- **PostToolUse (Bash)**：当 command 失败时进行 error detection
|
||||
|
||||
## Claude Code Setup
|
||||
|
||||
### Option 1: Project-Level Configuration
|
||||
|
||||
在项目根目录创建 `.claude/settings.json`：
|
||||
|
||||
```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"
|
||||
}
|
||||
]
|
||||
}
|
||||
]
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
### Option 2: User-Level Configuration
|
||||
|
||||
将以下内容加入 `~/.claude/settings.json`，实现全局启用：
|
||||
|
||||
```json
|
||||
{
|
||||
"hooks": {
|
||||
"UserPromptSubmit": [
|
||||
{
|
||||
"matcher": "",
|
||||
"hooks": [
|
||||
{
|
||||
"type": "command",
|
||||
"command": "~/.claude/skills/self-improvement/scripts/activator.sh"
|
||||
}
|
||||
]
|
||||
}
|
||||
]
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
### Minimal Setup（仅 Activator）
|
||||
|
||||
如果希望降低开销，只使用 UserPromptSubmit hook：
|
||||
|
||||
```json
|
||||
{
|
||||
"hooks": {
|
||||
"UserPromptSubmit": [
|
||||
{
|
||||
"matcher": "",
|
||||
"hooks": [
|
||||
{
|
||||
"type": "command",
|
||||
"command": "./skills/self-improvement/scripts/activator.sh"
|
||||
}
|
||||
]
|
||||
}
|
||||
]
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
## Codex CLI Setup
|
||||
|
||||
Codex 使用与 Claude Code 相同的 hook system。在 `.codex/settings.json` 中写入：
|
||||
|
||||
```json
|
||||
{
|
||||
"hooks": {
|
||||
"UserPromptSubmit": [
|
||||
{
|
||||
"matcher": "",
|
||||
"hooks": [
|
||||
{
|
||||
"type": "command",
|
||||
"command": "./skills/self-improvement/scripts/activator.sh"
|
||||
}
|
||||
]
|
||||
}
|
||||
]
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
## GitHub Copilot Setup
|
||||
|
||||
Copilot 不直接支持 hooks。可以改为在 `.github/copilot-instructions.md` 中加入提示：
|
||||
|
||||
```markdown
|
||||
## Self-Improvement
|
||||
|
||||
在完成包含以下情况的任务后：
|
||||
- Debugging non-obvious issues
|
||||
- 发现 workarounds
|
||||
- 学到项目特定 patterns
|
||||
- 解决 unexpected errors
|
||||
|
||||
考虑使用 self-improvement skill 的格式，将这条 learning 记录到 `.learnings/`。
|
||||
|
||||
对于对其他 sessions 也有价值的高价值 learnings，考虑做 skill extraction。
|
||||
```
|
||||
|
||||
## Verification
|
||||
|
||||
### Test Activator Hook
|
||||
|
||||
1. 启用 hook 配置
|
||||
2. 启动新的 Claude Code session
|
||||
3. 发送任意 prompt
|
||||
4. 确认上下文中出现 `<self-improvement-reminder>`
|
||||
|
||||
### Test Error Detector Hook
|
||||
|
||||
1. 为 Bash 启用 PostToolUse hook
|
||||
2. 运行一个会失败的 command：`ls /nonexistent/path`
|
||||
3. 确认出现 `<error-detected>` reminder
|
||||
|
||||
### Dry Run Extract Script
|
||||
|
||||
```bash
|
||||
./skills/self-improvement/scripts/extract-skill.sh test-skill --dry-run
|
||||
```
|
||||
|
||||
预期输出会展示将要创建的 skill scaffold。
|
||||
|
||||
## Troubleshooting
|
||||
|
||||
### Hook Not Triggering
|
||||
|
||||
1. **Check script permissions**：`chmod +x scripts/*.sh`
|
||||
2. **Verify path**：使用绝对路径，或使用相对项目根目录的路径
|
||||
3. **Check settings location**：确认是 project 级还是 user 级配置
|
||||
4. **Restart session**：hooks 会在 session 启动时加载
|
||||
|
||||
### Permission Denied
|
||||
|
||||
```bash
|
||||
chmod +x ./skills/self-improvement/scripts/activator.sh
|
||||
chmod +x ./skills/self-improvement/scripts/error-detector.sh
|
||||
chmod +x ./skills/self-improvement/scripts/extract-skill.sh
|
||||
```
|
||||
|
||||
### Script Not Found
|
||||
|
||||
如果使用相对路径，请确认当前目录正确；否则使用绝对路径：
|
||||
|
||||
```json
|
||||
{
|
||||
"command": "/absolute/path/to/skills/self-improvement/scripts/activator.sh"
|
||||
}
|
||||
```
|
||||
|
||||
### Too Much Overhead
|
||||
|
||||
如果 activator 让你觉得太打断：
|
||||
|
||||
1. **Use minimal setup**：仅启用 UserPromptSubmit，不启用 PostToolUse
|
||||
2. **Add matcher filter**：只在特定 prompts 下触发：
|
||||
|
||||
```json
|
||||
{
|
||||
"matcher": "fix|debug|error|issue",
|
||||
"hooks": [...]
|
||||
}
|
||||
```
|
||||
|
||||
## Hook Output Budget
|
||||
|
||||
activator 被设计为轻量输出：
|
||||
- **Target**：约 50-100 tokens 每次触发
|
||||
- **Content**：结构化 reminder，而不是冗长说明
|
||||
- **Format**：XML tags，便于解析
|
||||
|
||||
如果还需要进一步降低开销，可以直接修改 `activator.sh`，让输出更短。
|
||||
|
||||
## Security Considerations
|
||||
|
||||
- hook scripts 以与 Claude Code 相同的权限运行
|
||||
- scripts 只输出文本；不会修改文件，也不会执行额外 commands
|
||||
- error detector 会读取 `CLAUDE_TOOL_OUTPUT` environment variable
|
||||
- 所有 scripts 都是 opt-in 的（必须手动配置才会启用）
|
||||
|
||||
## Disabling Hooks
|
||||
|
||||
如果想临时停用，又不想删除配置：
|
||||
|
||||
1. **Comment out in settings**：
|
||||
```json
|
||||
{
|
||||
"hooks": {
|
||||
// "UserPromptSubmit": [...]
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
2. **或直接删除 settings file**：没有配置时 hooks 就不会运行
|
||||
@@ -0,0 +1,248 @@
|
||||
# OpenClaw Integration
|
||||
|
||||
将 self-improvement skill 集成到 OpenClaw 的完整 setup 与使用指南。
|
||||
|
||||
## Overview
|
||||
|
||||
OpenClaw 使用基于 workspace 的 prompt injection，并结合 event-driven hooks。上下文会在 session 启动时从 workspace files 注入，hooks 则会在生命周期事件上触发。
|
||||
|
||||
## Workspace Structure
|
||||
|
||||
```
|
||||
~/.openclaw/
|
||||
├── workspace/ # 工作目录
|
||||
│ ├── AGENTS.md # 多代理协作模式
|
||||
│ ├── SOUL.md # 行为指导与个性
|
||||
│ ├── TOOLS.md # 工具能力与 gotchas
|
||||
│ ├── MEMORY.md # 长期 memory（仅主 session）
|
||||
│ └── memory/ # 每日 memory 文件
|
||||
│ └── YYYY-MM-DD.md
|
||||
├── skills/ # 已安装 skills
|
||||
│ └── <skill-name>/
|
||||
│ └── SKILL.md
|
||||
└── hooks/ # 自定义 hooks
|
||||
└── <hook-name>/
|
||||
├── HOOK.md
|
||||
└── handler.ts
|
||||
```
|
||||
|
||||
## Quick Setup
|
||||
|
||||
### 1. Install the Skill
|
||||
|
||||
```bash
|
||||
clawdhub install self-improving-agent
|
||||
```
|
||||
|
||||
或手动复制：
|
||||
|
||||
```bash
|
||||
cp -r self-improving-agent ~/.openclaw/skills/
|
||||
```
|
||||
|
||||
### 2. Install the Hook（可选）
|
||||
|
||||
将 hook 复制到 OpenClaw 的 hooks 目录：
|
||||
|
||||
```bash
|
||||
cp -r hooks/openclaw ~/.openclaw/hooks/self-improvement
|
||||
```
|
||||
|
||||
启用 hook：
|
||||
|
||||
```bash
|
||||
openclaw hooks enable self-improvement
|
||||
```
|
||||
|
||||
### 3. Create Learning Files
|
||||
|
||||
在 workspace 中创建 `.learnings/` 目录：
|
||||
|
||||
```bash
|
||||
mkdir -p ~/.openclaw/workspace/.learnings
|
||||
```
|
||||
|
||||
或者在 skill 目录中创建：
|
||||
|
||||
```bash
|
||||
mkdir -p ~/.openclaw/skills/self-improving-agent/.learnings
|
||||
```
|
||||
|
||||
## Injected Prompt Files
|
||||
|
||||
### AGENTS.md
|
||||
|
||||
用途：多代理 workflows 与 delegation patterns。
|
||||
|
||||
```markdown
|
||||
# Agent Coordination
|
||||
|
||||
## Delegation Rules
|
||||
- 对开放式 codebase 问题使用 explore agent
|
||||
- 对长时间任务启动 sub-agents
|
||||
- 使用 sessions_send 做跨 session 通信
|
||||
|
||||
## Session Handoff
|
||||
在委派给另一个 session 时：
|
||||
1. 在 handoff message 中提供完整上下文
|
||||
2. 包含相关文件路径
|
||||
3. 指定期望的输出格式
|
||||
```
|
||||
|
||||
### SOUL.md
|
||||
|
||||
用途：行为指导与沟通风格。
|
||||
|
||||
```markdown
|
||||
# Behavioral Guidelines
|
||||
|
||||
## Communication Style
|
||||
- 保持直接和简洁
|
||||
- 避免不必要的 caveats 和 disclaimers
|
||||
- 使用符合上下文的技术语言
|
||||
|
||||
## Error Handling
|
||||
- 及时承认错误
|
||||
- 立即给出更正后的信息
|
||||
- 将重要 errors 记录到 learnings
|
||||
```
|
||||
|
||||
### TOOLS.md
|
||||
|
||||
用途：工具能力、integration gotchas、本地配置。
|
||||
|
||||
```markdown
|
||||
# Tool Knowledge
|
||||
|
||||
## Self-Improvement Skill
|
||||
将 learnings 记录到 `.learnings/`，以支持持续改进。
|
||||
|
||||
## Local Tools
|
||||
- 在这里记录 tool-specific gotchas
|
||||
- 记录 authentication requirements
|
||||
- 跟踪 integration quirks
|
||||
```
|
||||
|
||||
## Learning Workflow
|
||||
|
||||
### Capturing Learnings
|
||||
|
||||
1. **In-session**：像平时一样记录到 `.learnings/`
|
||||
2. **Cross-session**：提升到 workspace files
|
||||
|
||||
### Promotion Decision Tree
|
||||
|
||||
```
|
||||
Is the learning project-specific?
|
||||
├── Yes → Keep in .learnings/
|
||||
└── No → Is it behavioral/style-related?
|
||||
├── Yes → Promote to SOUL.md
|
||||
└── No → Is it tool-related?
|
||||
├── Yes → Promote to TOOLS.md
|
||||
└── No → Promote to AGENTS.md (workflow)
|
||||
```
|
||||
|
||||
### Promotion Format Examples
|
||||
|
||||
**From learning：**
|
||||
> 在未配置 auth 的情况下执行 Git push 到 GitHub 会失败，并触发 desktop prompt
|
||||
|
||||
**To TOOLS.md：**
|
||||
```markdown
|
||||
## Git
|
||||
- 在确认 auth 已配置前不要执行 push
|
||||
- 使用 `gh auth status` 检查 GitHub CLI auth
|
||||
```
|
||||
|
||||
## Inter-Agent Communication
|
||||
|
||||
OpenClaw 提供这些工具用于跨 session 通信：
|
||||
|
||||
### sessions_list
|
||||
|
||||
查看活跃和最近的 sessions：
|
||||
```
|
||||
sessions_list(activeMinutes=30, messageLimit=3)
|
||||
```
|
||||
|
||||
### sessions_history
|
||||
|
||||
读取另一个 session 的 transcript：
|
||||
```
|
||||
sessions_history(sessionKey="session-id", limit=50)
|
||||
```
|
||||
|
||||
### sessions_send
|
||||
|
||||
向另一个 session 发送消息：
|
||||
```
|
||||
sessions_send(sessionKey="session-id", message="Learning: API requires X-Custom-Header")
|
||||
```
|
||||
|
||||
### sessions_spawn
|
||||
|
||||
启动一个后台 sub-agent：
|
||||
```
|
||||
sessions_spawn(task="Research X and report back", label="research")
|
||||
```
|
||||
|
||||
## Available Hook Events
|
||||
|
||||
| Event | When It Fires |
|
||||
|-------|---------------|
|
||||
| `agent:bootstrap` | 在 workspace files 注入前触发 |
|
||||
| `command:new` | 执行 `/new` command 时触发 |
|
||||
| `command:reset` | 执行 `/reset` command 时触发 |
|
||||
| `command:stop` | 执行 `/stop` command 时触发 |
|
||||
| `gateway:startup` | gateway 启动时触发 |
|
||||
|
||||
## Detection Triggers
|
||||
|
||||
### Standard Triggers
|
||||
- 用户纠正（"No, that's wrong..."）
|
||||
- command failures（non-zero exit codes）
|
||||
- API errors
|
||||
- knowledge gaps
|
||||
|
||||
### OpenClaw-Specific Triggers
|
||||
|
||||
| Trigger | Action |
|
||||
|---------|--------|
|
||||
| Tool call error | 记录到 TOOLS.md，并标明 tool name |
|
||||
| Session handoff confusion | 记录到 AGENTS.md，并补充 delegation pattern |
|
||||
| Model behavior surprise | 记录到 SOUL.md，并说明 expected vs actual |
|
||||
| Skill issue | 记录到 .learnings/ 或向上游反馈 |
|
||||
|
||||
## Verification
|
||||
|
||||
检查 hook 是否已注册：
|
||||
|
||||
```bash
|
||||
openclaw hooks list
|
||||
```
|
||||
|
||||
检查 skill 是否已加载：
|
||||
|
||||
```bash
|
||||
openclaw status
|
||||
```
|
||||
|
||||
## Troubleshooting
|
||||
|
||||
### Hook not firing
|
||||
|
||||
1. 确保 hooks 已在配置中启用
|
||||
2. 修改配置后重启 gateway
|
||||
3. 检查 gateway logs 中是否有 errors
|
||||
|
||||
### Learnings not persisting
|
||||
|
||||
1. 确认 `.learnings/` 目录存在
|
||||
2. 检查文件权限
|
||||
3. 确认 workspace path 配置正确
|
||||
|
||||
### Skill not loading
|
||||
|
||||
1. 检查 skill 是否位于 skills 目录中
|
||||
2. 确认 SKILL.md 的 frontmatter 正确
|
||||
3. 运行 `openclaw status` 查看已加载 skills
|
||||
Reference in New Issue
Block a user