每日备份 2026-06-10 12:57:13
This commit is contained in:
root-backup committed
1 parent
fda2ccb8c2
commit
3d2e638c6a
244 files changed
+58890
-3
No files matched your search
@@ -0,0 +1,314 @@
|
||||
---
|
||||
name: agent-reach
|
||||
description: >
|
||||
Give your AI agent eyes to see the entire internet.
|
||||
Search and read 17 platforms: Twitter/X, Reddit, YouTube, GitHub, Bilibili,
|
||||
XiaoHongShu, Douyin, Weibo, WeChat Articles, Xiaoyuzhou Podcast, LinkedIn,
|
||||
V2EX, Xueqiu, RSS, Exa web search, and any web page.
|
||||
Zero config for 8 channels. Use when user asks to search, read, or interact
|
||||
on any supported platform, shares a URL, or asks to search the web.
|
||||
Triggers: "搜推特", "搜小红书", "看视频", "搜一下", "上网搜", "帮我查",
|
||||
"search twitter", "youtube transcript", "search reddit", "read this link",
|
||||
"B站", "bilibili", "抖音视频", "微信文章", "公众号", "微博", "V2EX",
|
||||
"小宇宙", "播客", "podcast", "雪球", "股票", "stock quote",
|
||||
"web search", "research", "帮我安装".
|
||||
metadata:
|
||||
openclaw:
|
||||
homepage: https://github.com/Panniantong/Agent-Reach
|
||||
---
|
||||
|
||||
# Agent Reach — Usage Guide
|
||||
|
||||
Upstream tools for 13+ platforms. Call them directly.
|
||||
|
||||
Run `agent-reach doctor` to check which channels are available.
|
||||
|
||||
## ⚠️ Workspace Rules
|
||||
|
||||
**Never create files in the agent workspace.** Use `/tmp/` for temporary output and `~/.agent-reach/` for persistent data.
|
||||
|
||||
## Web — Any URL
|
||||
|
||||
```bash
|
||||
curl -s "https://r.jina.ai/URL"
|
||||
```
|
||||
|
||||
## Web Search (Exa)
|
||||
|
||||
```bash
|
||||
mcporter call 'exa.web_search_exa(query: "query", numResults: 5)'
|
||||
mcporter call 'exa.get_code_context_exa(query: "code question", tokensNum: 3000)'
|
||||
```
|
||||
|
||||
## Twitter/X (bird)
|
||||
|
||||
```bash
|
||||
bird search "query" -n 10 # search
|
||||
bird read URL_OR_ID # read tweet (supports /status/ and /article/ URLs)
|
||||
bird user-tweets @username -n 20 # user timeline
|
||||
bird thread URL_OR_ID # full thread
|
||||
```
|
||||
|
||||
## YouTube (yt-dlp)
|
||||
|
||||
```bash
|
||||
yt-dlp --dump-json "URL" # video metadata
|
||||
yt-dlp --write-sub --write-auto-sub --sub-lang "zh-Hans,zh,en" --skip-download -o "/tmp/%(id)s" "URL"
|
||||
# download subtitles, then read the .vtt file
|
||||
yt-dlp --dump-json "ytsearch5:query" # search
|
||||
```
|
||||
|
||||
## Bilibili (yt-dlp)
|
||||
|
||||
```bash
|
||||
yt-dlp --dump-json "https://www.bilibili.com/video/BVxxx"
|
||||
yt-dlp --write-sub --write-auto-sub --sub-lang "zh-Hans,zh,en" --convert-subs vtt --skip-download -o "/tmp/%(id)s" "URL"
|
||||
```
|
||||
|
||||
> Server IPs may get 412. Use `--cookies-from-browser chrome` or configure proxy.
|
||||
|
||||
## Reddit
|
||||
|
||||
```bash
|
||||
curl -s "https://www.reddit.com/r/SUBREDDIT/hot.json?limit=10" -H "User-Agent: agent-reach/1.0"
|
||||
curl -s "https://www.reddit.com/search.json?q=QUERY&limit=10" -H "User-Agent: agent-reach/1.0"
|
||||
```
|
||||
|
||||
> Server IPs may get 403. Search via Exa instead, or configure proxy.
|
||||
|
||||
## GitHub (gh CLI)
|
||||
|
||||
```bash
|
||||
gh search repos "query" --sort stars --limit 10
|
||||
gh repo view owner/repo
|
||||
gh search code "query" --language python
|
||||
gh issue list -R owner/repo --state open
|
||||
gh issue view 123 -R owner/repo
|
||||
```
|
||||
|
||||
## 小红书 / XiaoHongShu (mcporter)
|
||||
|
||||
```bash
|
||||
mcporter call 'xiaohongshu.search_feeds(keyword: "query")'
|
||||
mcporter call 'xiaohongshu.get_feed_detail(feed_id: "xxx", xsec_token: "yyy")'
|
||||
mcporter call 'xiaohongshu.get_feed_detail(feed_id: "xxx", xsec_token: "yyy", load_all_comments: true)'
|
||||
mcporter call 'xiaohongshu.publish_content(title: "标题", content: "正文", images: ["/path/img.jpg"], tags: ["tag"])'
|
||||
```
|
||||
|
||||
> Requires login. Use Cookie-Editor to import cookies.
|
||||
|
||||
> **Tip: Clean bloated output.** XHS API returns large JSON with many unused fields.
|
||||
> Pipe through the formatter to save context:
|
||||
> ```bash
|
||||
> mcporter call 'xiaohongshu.search_feeds(keyword: "query")' | agent-reach format xhs
|
||||
> ```
|
||||
> This keeps only: title, content, author, engagement counts, image URLs, and tags.
|
||||
|
||||
## 抖音 / Douyin (mcporter)
|
||||
|
||||
```bash
|
||||
mcporter call 'douyin.parse_douyin_video_info(share_link: "https://v.douyin.com/xxx/")'
|
||||
mcporter call 'douyin.get_douyin_download_link(share_link: "https://v.douyin.com/xxx/")'
|
||||
```
|
||||
|
||||
> No login needed.
|
||||
|
||||
## 微信公众号 / WeChat Articles
|
||||
|
||||
**Search** (miku_ai):
|
||||
```bash
|
||||
# miku_ai is installed inside the agent-reach Python environment.
|
||||
# Use the same interpreter that runs agent-reach (handles pipx / venv installs):
|
||||
AGENT_REACH_PYTHON=$(python3 -c "import agent_reach, sys; print(sys.executable)" 2>/dev/null || echo python3)
|
||||
$AGENT_REACH_PYTHON -c "
|
||||
import asyncio
|
||||
from miku_ai import get_wexin_article
|
||||
async def s():
|
||||
for a in await get_wexin_article(\'query\', 5):
|
||||
print(f\'{a[\"title\"]} | {a[\"url\"]}\')
|
||||
asyncio.run(s())
|
||||
"
|
||||
```
|
||||
|
||||
**Read** (Camoufox — bypasses WeChat anti-bot):
|
||||
```bash
|
||||
cd ~/.agent-reach/tools/wechat-article-for-ai && python3 main.py "https://mp.weixin.qq.com/s/ARTICLE_ID"
|
||||
```
|
||||
|
||||
> WeChat articles cannot be read with Jina Reader or curl. Must use Camoufox.
|
||||
|
||||
## 微博 / Weibo (mcporter)
|
||||
|
||||
```bash
|
||||
# 热搜榜
|
||||
mcporter call 'weibo.get_trendings(limit: 20)'
|
||||
|
||||
# 搜索用户
|
||||
mcporter call 'weibo.search_users(keyword: "雷军", limit: 10)'
|
||||
|
||||
# 获取用户资料
|
||||
mcporter call 'weibo.get_profile(uid: "1195230310")'
|
||||
|
||||
# 获取用户微博动态
|
||||
mcporter call 'weibo.get_feeds(uid: "1195230310", limit: 20)'
|
||||
|
||||
# 获取用户热门微博
|
||||
mcporter call 'weibo.get_hot_feeds(uid: "1195230310", limit: 10)'
|
||||
|
||||
# 搜索微博内容
|
||||
mcporter call 'weibo.search_content(keyword: "人工智能", limit: 20)'
|
||||
|
||||
# 搜索话题
|
||||
mcporter call 'weibo.search_topics(keyword: "AI", limit: 10)'
|
||||
|
||||
# 获取微博评论
|
||||
mcporter call 'weibo.get_comments(mid: "5099916367123456", limit: 50)'
|
||||
|
||||
# 获取粉丝列表
|
||||
mcporter call 'weibo.get_fans(uid: "1195230310", limit: 20)'
|
||||
|
||||
# 获取关注列表
|
||||
mcporter call 'weibo.get_followers(uid: "1195230310", limit: 20)'
|
||||
```
|
||||
|
||||
> Zero config. No login needed. Uses mobile API with auto visitor cookies.
|
||||
|
||||
## 小宇宙播客 / Xiaoyuzhou Podcast (groq-whisper + ffmpeg)
|
||||
|
||||
```bash
|
||||
# 转录单集播客（输出文本到 /tmp/）
|
||||
~/.agent-reach/tools/xiaoyuzhou/transcribe.sh "https://www.xiaoyuzhoufm.com/episode/EPISODE_ID"
|
||||
```
|
||||
|
||||
> 需要 ffmpeg + Groq API Key（免费）。
|
||||
> 配置 Key：`agent-reach configure groq-key YOUR_KEY`
|
||||
> 首次运行需安装工具：`agent-reach install --env=auto`
|
||||
> 运行 `agent-reach doctor` 检查状态。
|
||||
> 输出 Markdown 文件默认保存到 `/tmp/`。
|
||||
|
||||
|
||||
## LinkedIn (mcporter)
|
||||
|
||||
```bash
|
||||
mcporter call 'linkedin.get_person_profile(linkedin_url: "https://linkedin.com/in/username")'
|
||||
mcporter call 'linkedin.search_people(keyword: "AI engineer", limit: 10)'
|
||||
```
|
||||
|
||||
Fallback: `curl -s "https://r.jina.ai/https://linkedin.com/in/username"`
|
||||
|
||||
## V2EX (public API)
|
||||
|
||||
```bash
|
||||
# 热门主题
|
||||
curl -s "https://www.v2ex.com/api/topics/hot.json" -H "User-Agent: agent-reach/1.0"
|
||||
|
||||
# 节点主题（node_name 如 python、tech、jobs、qna）
|
||||
curl -s "https://www.v2ex.com/api/topics/show.json?node_name=python&page=1" -H "User-Agent: agent-reach/1.0"
|
||||
|
||||
# 主题详情（topic_id 从 URL 获取，如 https://www.v2ex.com/t/1234567）
|
||||
curl -s "https://www.v2ex.com/api/topics/show.json?id=TOPIC_ID" -H "User-Agent: agent-reach/1.0"
|
||||
|
||||
# 主题回复
|
||||
curl -s "https://www.v2ex.com/api/replies/show.json?topic_id=TOPIC_ID&page=1" -H "User-Agent: agent-reach/1.0"
|
||||
|
||||
# 用户信息
|
||||
curl -s "https://www.v2ex.com/api/members/show.json?username=USERNAME" -H "User-Agent: agent-reach/1.0"
|
||||
```
|
||||
|
||||
Python 调用示例（V2EXChannel）：
|
||||
|
||||
```python
|
||||
from agent_reach.channels.v2ex import V2EXChannel
|
||||
|
||||
ch = V2EXChannel()
|
||||
|
||||
# 获取热门帖子（默认 20 条）
|
||||
# 返回字段：id, title, url, replies, node_name, node_title, content(前200字), created
|
||||
topics = ch.get_hot_topics(limit=10)
|
||||
for t in topics:
|
||||
print(f"[{t['node_title']}] {t['title']} ({t['replies']} 回复) {t['url']}")
|
||||
print(f" id={t['id']} created={t['created']}")
|
||||
|
||||
# 获取指定节点的最新帖子
|
||||
# 返回字段：id, title, url, replies, node_name, node_title, content(前200字), created
|
||||
node_topics = ch.get_node_topics("python", limit=5)
|
||||
for t in node_topics:
|
||||
print(t["id"], t["title"], t["url"])
|
||||
|
||||
# 获取单个帖子详情 + 回复列表
|
||||
# 返回字段：id, title, url, content, replies_count, node_name, node_title,
|
||||
# author, created, replies (list of {author, content, created})
|
||||
topic = ch.get_topic(1234567)
|
||||
print(topic["title"], "—", topic["author"])
|
||||
for r in topic["replies"]:
|
||||
print(f" {r['author']}: {r['content'][:80]}")
|
||||
|
||||
# 获取用户信息
|
||||
# 返回字段：id, username, url, website, twitter, psn, github, btc, location, bio, avatar, created
|
||||
user = ch.get_user("Livid")
|
||||
print(user["username"], user["bio"], user["github"])
|
||||
|
||||
# 搜索（V2EX 公开 API 不支持，会返回说明信息）
|
||||
result = ch.search("asyncio")
|
||||
print(result[0]["error"]) # 提示使用站内搜索或 Exa channel
|
||||
```
|
||||
|
||||
> No auth required. Results are public JSON. V2EX 节点名见 https://www.v2ex.com/planes
|
||||
|
||||
## 雪球 / Xueqiu (public API)
|
||||
|
||||
```python
|
||||
from agent_reach.channels.xueqiu import XueqiuChannel
|
||||
|
||||
ch = XueqiuChannel()
|
||||
|
||||
# 获取股票行情（符号格式：SH600519 沪市、SZ000858 深市、AAPL 美股、00700 港股）
|
||||
# 返回字段：symbol, name, current, percent, chg, high, low, open, last_close,
|
||||
# volume, amount, market_capital, turnover_rate, pe_ttm, timestamp
|
||||
quote = ch.get_stock_quote("SH600519")
|
||||
print(f"{quote['name']} ({quote['symbol']}): {quote['current']} ({quote['percent']}%)")
|
||||
|
||||
# 搜索股票
|
||||
# 返回字段：symbol, name, exchange
|
||||
stocks = ch.search_stock("茅台", limit=5)
|
||||
for s in stocks:
|
||||
print(f"{s['name']} ({s['symbol']}) - {s['exchange']}")
|
||||
|
||||
# 热门帖子
|
||||
# 返回字段：id, title, text(前200字), author, likes, url
|
||||
posts = ch.get_hot_posts(limit=10)
|
||||
for p in posts:
|
||||
print(f"{p['author']}: {p['text'][:50]}... ({p['likes']} 赞)")
|
||||
|
||||
# 热门股票（stock_type=10 人气榜，stock_type=12 关注榜）
|
||||
# 返回字段：symbol, name, current, percent, rank
|
||||
hot = ch.get_hot_stocks(limit=10, stock_type=10)
|
||||
for s in hot:
|
||||
print(f"#{s['rank']} {s['name']} ({s['symbol']}): {s['current']} ({s['percent']}%)")
|
||||
```
|
||||
|
||||
> 无需登录。自动获取会话 Cookie，所有公开 API 均可直接使用。
|
||||
|
||||
## RSS (feedparser)
|
||||
|
||||
## RSS
|
||||
|
||||
```python
|
||||
python3 -c "
|
||||
import feedparser
|
||||
for e in feedparser.parse('FEED_URL').entries[:5]:
|
||||
print(f'{e.title} — {e.link}')
|
||||
"
|
||||
```
|
||||
|
||||
## Troubleshooting
|
||||
|
||||
- **Channel not working?** Run `agent-reach doctor` — shows status and fix instructions.
|
||||
- **Twitter fetch failed?** Ensure `undici` is installed: `npm install -g undici`. Configure proxy: `agent-reach configure proxy URL`.
|
||||
|
||||
## Setting Up a Channel ("帮我配 XXX")
|
||||
|
||||
If a channel needs setup (cookies, Docker, etc.), fetch the install guide:
|
||||
https://raw.githubusercontent.com/Panniantong/agent-reach/main/docs/install.md
|
||||
|
||||
User only provides cookies. Everything else is your job.
|
||||
@@ -0,0 +1,112 @@
|
||||
---
|
||||
name: browser-chromium
|
||||
version: 1.1.0
|
||||
description: 基于 patchright + CloakBrowser 双引擎的反检测 Chromium 浏览器自动化
|
||||
---
|
||||
|
||||
# browser-chromium (v1.1.0)
|
||||
|
||||
基于 patchright + CloakBrowser 双引擎的反检测浏览器，适合需要绕过检测的网站。
|
||||
|
||||
**新增 v1.1.0**: CloakBrowser C++级源码补丁引擎，可通过 `--engine cloak` 切换
|
||||
|
||||
## 双引擎架构
|
||||
|
||||
| 引擎 | 命令 | 原理 | 适用场景 |
|
||||
|------|------|------|---------|
|
||||
| **patchright** (默认) | `--engine patchright` | JS注入反检测，兼容Playwright API | 普通反爬站(Twitter/X等) |
|
||||
| **CloakBrowser** | `--engine cloak` | C++源码级Chromium补丁，最强反检测 | Cloudflare/Turnstile/高防护站 |
|
||||
| **auto** | `--engine auto` | 自动选择(检测到防护站自动切CloakBrowser) | 通用 |
|
||||
|
||||
## 与 browser-desktop 的区别
|
||||
|
||||
| 维度 | browser-desktop | browser-chromium |
|
||||
|------|----------------|-----------------|
|
||||
| 浏览器 | Firefox (Playwright) | Chromium (patchright + CloakBrowser) |
|
||||
| 反检测 | 无 | 多层指纹伪装 |
|
||||
| 适用场景 | 普通网站 | 反爬/反机器人检测/高防护站 |
|
||||
| 速度 | 正常 | 正常 |
|
||||
|
||||
## 安装
|
||||
|
||||
```bash
|
||||
pip install patchright --break-system-packages
|
||||
patchright install chromium
|
||||
pip install cloakbrowser --break-system-packages
|
||||
pip install crawlee --break-system-packages # 指纹套件
|
||||
```
|
||||
|
||||
## 使用
|
||||
|
||||
```bash
|
||||
# 标准浏览 (patchright 引擎)
|
||||
python3 /home/yh6788/.openclaw/skills/browser-chromium/scripts/browse.py "https://x.com"
|
||||
|
||||
# 截图
|
||||
python3 /home/yh6788/.openclaw/skills/browser-chromium/scripts/browse.py "https://example.com" --screenshot
|
||||
|
||||
# 高防护站 (CloakBrowser 引擎)
|
||||
python3 /home/yh6788/.openclaw/skills/browser-chromium/scripts/browse.py "https://cloudflare.com" --engine cloak
|
||||
|
||||
# 自动选择引擎
|
||||
python3 /home/yh6788/.openclaw/skills/browser-chromium/scripts/browse.py "https://x.com" --engine auto
|
||||
|
||||
# 带代理
|
||||
python3 /home/yh6788/.openclaw/skills/browser-chromium/scripts/browse.py "https://example.com" --proxy "http://192.168.0.66:7890"
|
||||
|
||||
# 检测指纹强度
|
||||
python3 /home/yh6788/.openclaw/skills/browser-chromium/scripts/browse.py --check-fingerprint --engine patchright
|
||||
```
|
||||
|
||||
## API（Python 脚本中引用）
|
||||
|
||||
```python
|
||||
from patchright.sync_api import sync_playwright
|
||||
|
||||
with sync_playwright() as p:
|
||||
browser = p.chromium.launch(headless=True)
|
||||
page = browser.new_page()
|
||||
page.goto("https://x.com")
|
||||
page.screenshot()
|
||||
browser.close()
|
||||
```
|
||||
|
||||
## CloakBrowser 用法
|
||||
|
||||
```python
|
||||
from cloakbrowser import CloakBrowser
|
||||
|
||||
cb = CloakBrowser(headless=True, proxy="http://192.168.0.66:7890")
|
||||
page = cb.page
|
||||
page.goto("https://cloudflare.com")
|
||||
print(page.content())
|
||||
```
|
||||
|
||||
## 引擎选择建议
|
||||
|
||||
```
|
||||
简单站/登录站 → patchright (默认，Cookie持久化)
|
||||
Cloudflare/Turnstile → cloak
|
||||
未知站 → auto
|
||||
```
|
||||
|
||||
## 持久化会话
|
||||
|
||||
Cookie 自动保存到 `~/.openclaw/browser-chromium-cookies.json`，下次打开自动复用登录状态。（CloakBrowser模式除外）
|
||||
|
||||
## 依赖生态
|
||||
|
||||
| 库 | 用途 | 状态 |
|
||||
|----|------|------|
|
||||
| patchright | 主引擎 | ✅ |
|
||||
| playwright | patchright 依赖 | ✅ |
|
||||
| cloakbrowser | C++级反检测 | ✅ |
|
||||
| crawlee | fingerprint_suite | ✅ |
|
||||
| parsel | crawlee 依赖 | ✅ |
|
||||
| jaro-winkler | crawlee 依赖 | ✅ |
|
||||
|
||||
## 注意事项
|
||||
|
||||
- patchright 只支持 Chromium，Firefox/WebKit 不支持
|
||||
- 如遇检测，优先尝试 `--engine cloak` 或加代理
|
||||
- CloakBrowser 会话不持久化（每次新建）
|
||||
@@ -0,0 +1,72 @@
|
||||
# Camoufox Stealth Browser 🦊
|
||||
|
||||
**C++ level** anti-bot evasion — not JavaScript band-aids.
|
||||
|
||||
[](LICENSE)
|
||||
|
||||
## Why Camoufox > Chrome-Based Tools
|
||||
|
||||
| Approach | Patches At | Detectable? |
|
||||
|----------|-----------|-------------|
|
||||
| **Camoufox** ✅ | C++ (compiled into browser) | No — fingerprints are genuinely different |
|
||||
| undetected-chromedriver | JS runtime | Yes — timing analysis reveals patches |
|
||||
| puppeteer-stealth | JS injection | Yes — applied after page load |
|
||||
| playwright-stealth | JS injection | Yes — same limitations |
|
||||
|
||||
Most "stealth" tools patch Chrome with JavaScript after the browser starts. Anti-bot systems detect this via timing analysis and consistency checks.
|
||||
|
||||
**Camoufox is different.** It's a Firefox fork with stealth patches compiled into the C++ source code. WebGL, Canvas, and AudioContext fingerprints are genuinely spoofed — not masked by JS overrides.
|
||||
|
||||
## Key Features
|
||||
|
||||
- 🦊 **C++ Level Stealth** — Fingerprints baked into the browser binary
|
||||
- 📦 **Container Isolation** — Runs in distrobox, keeps host clean
|
||||
- ⚡ **Dual-Tool Design** — Camoufox for browsers, curl_cffi for fast API-only scraping
|
||||
- 🔥 **Firefox-Based** — Less fingerprinted than Chrome (bots love Chrome)
|
||||
|
||||
## Quick Start
|
||||
|
||||
```bash
|
||||
# Setup (first time)
|
||||
distrobox-enter pybox -- python3.14 -m pip install camoufox curl_cffi
|
||||
|
||||
# Fetch a Cloudflare-protected page
|
||||
distrobox-enter pybox -- python3.14 scripts/camoufox-fetch.py \
|
||||
"https://yelp.com/biz/example" --headless
|
||||
|
||||
# API scraping (no browser needed)
|
||||
distrobox-enter pybox -- python3.14 scripts/curl-api.py \
|
||||
"https://api.example.com" --impersonate chrome120
|
||||
```
|
||||
|
||||
## Requirements
|
||||
|
||||
- `distrobox` with a `pybox` container
|
||||
- Residential proxy for Airbnb/Yelp (datacenter IPs = instant block)
|
||||
|
||||
## Tools
|
||||
|
||||
| Tool | Use Case | Speed |
|
||||
|------|----------|-------|
|
||||
| **Camoufox** | Full browser automation, JS-heavy sites | ~3-5s/page |
|
||||
| **curl_cffi** | API endpoints, no JS needed | ~100ms/request |
|
||||
|
||||
## Documentation
|
||||
|
||||
- [SKILL.md](SKILL.md) — Full usage guide with session management
|
||||
- [references/proxy-setup.md](references/proxy-setup.md) — Proxy configuration
|
||||
- [references/fingerprint-checks.md](references/fingerprint-checks.md) — What anti-bot systems check
|
||||
|
||||
## Comparison with Other Skills
|
||||
|
||||
This skill focuses on **doing one thing well**: C++ level stealth with Camoufox.
|
||||
|
||||
For CAPTCHA solving, task checkpointing, and proxy rotation, see the [GitHub issues](https://github.com/kesslerio/stealth-browser-clawhub-skill/issues) for planned features.
|
||||
|
||||
## License
|
||||
|
||||
Apache 2.0 — See [LICENSE](LICENSE)
|
||||
|
||||
---
|
||||
|
||||
Made with 🦊 by [Kessler.io](https://kessler.io)
|
||||
@@ -0,0 +1,51 @@
|
||||
---
|
||||
name: camoufox
|
||||
version: 1.0.0
|
||||
description: Anti-detect browser automation using Camoufox (Firefox-based). Use instead of Chrome/Playwright for bot-detection-heavy sites like X/Twitter, Naver, and other protected sites. Provides stealth browsing with OS/browser fingerprint spoofing, humanized mouse movements, and persistent sessions.
|
||||
---
|
||||
|
||||
# Camoufox
|
||||
|
||||
**Use instead of OpenClaw's built-in browser tool for bot-detection sites.**
|
||||
|
||||
## Setup (one-time)
|
||||
```bash
|
||||
bash scripts/setup.sh
|
||||
```
|
||||
|
||||
## Usage
|
||||
```bash
|
||||
source ~/.openclaw/workspace/camoufox-env/bin/activate
|
||||
xvfb-run -a --server-args="-screen 0 1920x1080x24" python3 your_script.py
|
||||
```
|
||||
|
||||
## Required Settings
|
||||
```python
|
||||
from camoufox.sync_api import Camoufox
|
||||
|
||||
with Camoufox(
|
||||
headless=False, # MUST be False (True gets detected)
|
||||
os='linux', # MUST match server OS (stack traces leak real OS)
|
||||
humanize=True,
|
||||
persistent_context=True,
|
||||
user_data_dir='~/.openclaw/camoufox-profile'
|
||||
) as browser:
|
||||
page = browser.new_page()
|
||||
# Use standard Playwright API from here
|
||||
```
|
||||
|
||||
## Paths
|
||||
- venv: `~/.openclaw/workspace/camoufox-env/`
|
||||
- profile: `~/.openclaw/camoufox-profile/`
|
||||
|
||||
## CAPTCHA Handling
|
||||
First visit to protected sites may need manual CAPTCHA:
|
||||
```bash
|
||||
DISPLAY=:1 python3 scripts/login_session.py https://site.com/login
|
||||
```
|
||||
Solve via VNC, session saves to profile for future automation.
|
||||
|
||||
## Scripts
|
||||
- `scripts/setup.sh` - Install dependencies
|
||||
- `scripts/browse.py <url> --screenshot out.png` - Quick browse
|
||||
- `scripts/login_session.py <url>` - VNC manual login
|
||||
@@ -0,0 +1,11 @@
|
||||
{
|
||||
"owner": "kesslerio",
|
||||
"slug": "camoufox-stealth",
|
||||
"displayName": "Camoufox Stealth Browser",
|
||||
"latest": {
|
||||
"version": "1.0.0",
|
||||
"publishedAt": 1770018858396,
|
||||
"commit": "https://github.com/clawdbot/skills/commit/d9bc4033c40e02a8cfd481bf4a363bbe072104a4"
|
||||
},
|
||||
"history": []
|
||||
}
|
||||
@@ -0,0 +1,239 @@
|
||||
# Browser Fingerprint Checks
|
||||
|
||||
What anti-bot systems check and how to evade.
|
||||
|
||||
## Detection Layers
|
||||
|
||||
```
|
||||
┌─────────────────────────────────────────────┐
|
||||
│ Layer 1: Network/IP │
|
||||
│ • IP reputation score │
|
||||
│ • Datacenter vs residential │
|
||||
│ • Geo-location consistency │
|
||||
├─────────────────────────────────────────────┤
|
||||
│ Layer 2: TLS Fingerprint │
|
||||
│ • JA3/JA4 hash │
|
||||
│ • Cipher suite order │
|
||||
│ • TLS extensions │
|
||||
├─────────────────────────────────────────────┤
|
||||
│ Layer 3: HTTP Headers │
|
||||
│ • User-Agent consistency │
|
||||
│ • Header order │
|
||||
│ • Accept-Language │
|
||||
├─────────────────────────────────────────────┤
|
||||
│ Layer 4: Browser Fingerprint │
|
||||
│ • navigator.webdriver │
|
||||
│ • Canvas/WebGL hash │
|
||||
│ • Audio fingerprint │
|
||||
│ • Font enumeration │
|
||||
├─────────────────────────────────────────────┤
|
||||
│ Layer 5: Behavioral │
|
||||
│ • Mouse movements │
|
||||
│ • Scroll patterns │
|
||||
│ • Timing analysis │
|
||||
│ • Click patterns │
|
||||
└─────────────────────────────────────────────┘
|
||||
```
|
||||
|
||||
## Specific Checks & Countermeasures
|
||||
|
||||
### 1. navigator.webdriver
|
||||
|
||||
**What:** `navigator.webdriver` returns `true` for automated browsers.
|
||||
|
||||
**Check:**
|
||||
```javascript
|
||||
navigator.webdriver // true = bot
|
||||
```
|
||||
|
||||
**Countermeasure:**
|
||||
- Nodriver: Automatically patches
|
||||
- Camoufox: Patched at C++ level
|
||||
- Playwright-stealth: `delete navigator.webdriver` (weak, can be detected)
|
||||
|
||||
### 2. Chrome DevTools Protocol (CDP)
|
||||
|
||||
**What:** Presence of CDP side-channels reveals automation.
|
||||
|
||||
**Check:**
|
||||
```javascript
|
||||
// Sites check for CDP artifacts
|
||||
window.cdc_adoQpoasnfa76pfcZLmcfl_Array
|
||||
window.cdc_adoQpoasnfa76pfcZLmcfl_Promise
|
||||
```
|
||||
|
||||
**Countermeasure:**
|
||||
- Nodriver: Uses CDP but patches artifacts
|
||||
- Camoufox: No CDP (native Firefox)
|
||||
- Patchright: Patches CDP artifacts
|
||||
|
||||
### 3. Canvas Fingerprint
|
||||
|
||||
**What:** Each GPU/driver combo renders slightly differently.
|
||||
|
||||
**Check:**
|
||||
```javascript
|
||||
canvas.toDataURL() // Unique hash per system
|
||||
```
|
||||
|
||||
**Countermeasure:**
|
||||
- Camoufox: Injects deterministic noise
|
||||
- Some detection tools look for perfectly identical canvas = bot
|
||||
|
||||
### 4. WebGL Fingerprint
|
||||
|
||||
**What:** GPU vendor/renderer strings.
|
||||
|
||||
**Check:**
|
||||
```javascript
|
||||
gl.getParameter(gl.RENDERER) // "ANGLE (Intel HD Graphics)"
|
||||
gl.getParameter(gl.VENDOR) // "Google Inc."
|
||||
```
|
||||
|
||||
**Countermeasure:**
|
||||
- Camoufox: Spoofs to common values
|
||||
- Avoid VMs with "llvmpipe" or "SwiftShader" (instant bot flag)
|
||||
|
||||
### 5. Audio Fingerprint
|
||||
|
||||
**What:** AudioContext processing variations.
|
||||
|
||||
**Check:**
|
||||
```javascript
|
||||
new AudioContext().createOscillator() // Unique waveform
|
||||
```
|
||||
|
||||
**Countermeasure:**
|
||||
- Camoufox: Adds noise to audio processing
|
||||
|
||||
### 6. Font Enumeration
|
||||
|
||||
**What:** Bots often have minimal fonts installed.
|
||||
|
||||
**Check:**
|
||||
```javascript
|
||||
// Test if specific fonts render
|
||||
document.fonts.check('12px "Segoe UI"')
|
||||
```
|
||||
|
||||
**Countermeasure:**
|
||||
- Install standard fonts in your environment
|
||||
- Camoufox: Spoofs font list
|
||||
|
||||
### 7. Screen/Window Size
|
||||
|
||||
**What:** Unusual dimensions = bot.
|
||||
|
||||
**Check:**
|
||||
```javascript
|
||||
screen.width, screen.height
|
||||
window.innerWidth, window.innerHeight
|
||||
```
|
||||
|
||||
**Countermeasure:**
|
||||
- Use standard resolutions: 1920x1080, 1366x768
|
||||
- Avoid: 800x600, odd dimensions
|
||||
|
||||
### 8. Timezone Consistency
|
||||
|
||||
**What:** Timezone must match IP geo-location.
|
||||
|
||||
**Check:**
|
||||
```javascript
|
||||
Intl.DateTimeFormat().resolvedOptions().timeZone
|
||||
new Date().getTimezoneOffset()
|
||||
```
|
||||
|
||||
**Countermeasure:**
|
||||
- Set timezone to match proxy location:
|
||||
```bash
|
||||
TZ="America/New_York" python script.py
|
||||
```
|
||||
|
||||
### 9. Language Consistency
|
||||
|
||||
**What:** Browser language should match geo.
|
||||
|
||||
**Check:**
|
||||
```javascript
|
||||
navigator.language // "en-US"
|
||||
navigator.languages // ["en-US", "en"]
|
||||
```
|
||||
|
||||
**Countermeasure:**
|
||||
- Configure browser locale to match proxy:
|
||||
```python
|
||||
# Camoufox
|
||||
async with AsyncCamoufox(locale="en-US") as browser:
|
||||
```
|
||||
|
||||
### 10. Hardware Concurrency
|
||||
|
||||
**What:** VMs often report 1-2 CPUs.
|
||||
|
||||
**Check:**
|
||||
```javascript
|
||||
navigator.hardwareConcurrency // 1 or 2 = suspicious
|
||||
```
|
||||
|
||||
**Countermeasure:**
|
||||
- Camoufox: Spoofs to 4-8
|
||||
- Or use real hardware, not minimal VM
|
||||
|
||||
### 11. Headless Detection
|
||||
|
||||
**What:** Multiple signals reveal headless mode.
|
||||
|
||||
**Checks:**
|
||||
```javascript
|
||||
navigator.plugins.length === 0
|
||||
navigator.mimeTypes.length === 0
|
||||
window.chrome === undefined
|
||||
```
|
||||
|
||||
**Countermeasure:**
|
||||
- Use "new headless" mode: `headless="new"`
|
||||
- Or run headed in Xvfb
|
||||
- Camoufox headless is well-patched
|
||||
|
||||
### 12. Mouse/Keyboard Events
|
||||
|
||||
**What:** Bots often have no mouse history.
|
||||
|
||||
**Check:**
|
||||
```javascript
|
||||
// Sites track mouse movement patterns
|
||||
document.addEventListener('mousemove', analyze)
|
||||
```
|
||||
|
||||
**Countermeasure:**
|
||||
- Inject random mouse movements
|
||||
- Nodriver/Camoufox: Built-in human-like movement
|
||||
- Don't teleport cursor - use bezier curves
|
||||
|
||||
## Test Sites
|
||||
|
||||
Check your stealth setup:
|
||||
|
||||
| Site | What It Tests |
|
||||
|------|--------------|
|
||||
| https://bot.sannysoft.com | Comprehensive bot detection |
|
||||
| https://browserleaks.com | All fingerprints |
|
||||
| https://nowsecure.nl | Cloudflare detection |
|
||||
| https://pixelscan.net | Bot detection score |
|
||||
| https://abrahamjuliot.github.io/creepjs | Advanced fingerprinting |
|
||||
|
||||
## Tool Comparison
|
||||
|
||||
| Check | Camoufox | Plain Playwright |
|
||||
|-------|----------|------------------|
|
||||
| webdriver | ✅ | ❌ |
|
||||
| CDP artifacts | ✅ (no CDP) | ❌ |
|
||||
| Canvas | ✅ | ❌ |
|
||||
| WebGL | ✅ | ❌ |
|
||||
| Audio | ✅ | ❌ |
|
||||
| Fonts | ✅ | ❌ |
|
||||
| Headless | ✅ | ❌ |
|
||||
| TLS | ✅ | ❌ |
|
||||
|
||||
Legend: ✅ = patched, ❌ = detected
|
||||
@@ -0,0 +1,145 @@
|
||||
# Proxy Setup Guide
|
||||
|
||||
## Why Proxies Matter
|
||||
|
||||
**Datacenter IPs = INSTANT BLOCK** on protected sites like Airbnb, Yelp, and anything with Cloudflare/Datadome.
|
||||
|
||||
Anti-bot systems check IP reputation scores. AWS, DigitalOcean, Vultr, Linode IPs have high "fraud scores" and are blocked immediately.
|
||||
|
||||
## Proxy Types (Best to Worst for Anti-Bot)
|
||||
|
||||
| Type | Detection Risk | Speed | Cost | Best For |
|
||||
|------|---------------|-------|------|----------|
|
||||
| **Mobile 4G/5G** | Very Low | Medium | $$$ | Hardest targets |
|
||||
| **Residential Rotating** | Low | Medium | $$ | General scraping |
|
||||
| **Residential Static** | Low | Fast | $$ | Session-based work |
|
||||
| **ISP Proxies** | Medium | Fast | $$ | Light protection |
|
||||
| **Datacenter** | BLOCKED | Fast | $ | Non-protected sites only |
|
||||
|
||||
## Recommended Providers
|
||||
|
||||
### Residential/Mobile Proxies
|
||||
- **Bright Data** (formerly Luminati) - Enterprise grade
|
||||
- **Oxylabs** - Good residential pool
|
||||
- **Smartproxy** - Budget friendly
|
||||
- **IPRoyal** - Cheap residential
|
||||
- **PacketStream** - P2P residential
|
||||
|
||||
### Proxy Format
|
||||
|
||||
```
|
||||
# Without auth
|
||||
http://host:port
|
||||
socks5://host:port
|
||||
|
||||
# With auth
|
||||
http://username:password@host:port
|
||||
socks5://username:password@host:port
|
||||
|
||||
# Rotating (some providers)
|
||||
http://username:password@gate.provider.com:port
|
||||
```
|
||||
|
||||
## Configuration Examples
|
||||
|
||||
### Camoufox
|
||||
|
||||
```python
|
||||
from camoufox.async_api import AsyncCamoufox
|
||||
|
||||
async with AsyncCamoufox(
|
||||
proxy={
|
||||
"server": "http://proxy.example.com:8080",
|
||||
"username": "user",
|
||||
"password": "pass"
|
||||
}
|
||||
) as browser:
|
||||
page = await browser.new_page()
|
||||
```
|
||||
|
||||
### curl_cffi
|
||||
|
||||
```python
|
||||
from curl_cffi import requests
|
||||
|
||||
response = requests.get(
|
||||
"https://example.com",
|
||||
proxies={
|
||||
"http": "http://user:pass@proxy.example.com:8080",
|
||||
"https": "http://user:pass@proxy.example.com:8080"
|
||||
},
|
||||
impersonate="chrome120"
|
||||
)
|
||||
```
|
||||
|
||||
### Environment Variable
|
||||
|
||||
```bash
|
||||
export HTTP_PROXY="http://user:pass@proxy.example.com:8080"
|
||||
export HTTPS_PROXY="http://user:pass@proxy.example.com:8080"
|
||||
```
|
||||
|
||||
## Session Stickiness
|
||||
|
||||
**Don't rotate every request!** This looks like a bot.
|
||||
|
||||
Real users:
|
||||
- Stay on same IP for 10-30 minutes
|
||||
- Make multiple requests from same session
|
||||
- Have consistent fingerprints
|
||||
|
||||
```python
|
||||
# Good: Sticky session
|
||||
session_proxy = "http://user-session-abc123:pass@gate.provider.com:8080"
|
||||
|
||||
# Bad: Rotate every request
|
||||
rotating_proxy = "http://user:pass@rotate.provider.com:8080" # Only for initial requests
|
||||
```
|
||||
|
||||
## Geo-Targeting
|
||||
|
||||
Match proxy location to expected user location:
|
||||
|
||||
```python
|
||||
# Scraping US Airbnb listings? Use US proxy
|
||||
us_proxy = "http://user-country-us:pass@gate.provider.com:8080"
|
||||
|
||||
# Scraping UK Yelp? Use UK proxy
|
||||
uk_proxy = "http://user-country-gb:pass@gate.provider.com:8080"
|
||||
```
|
||||
|
||||
## Testing Your Proxy
|
||||
|
||||
```bash
|
||||
# Check IP and detection
|
||||
distrobox-enter pybox -- python -c "
|
||||
from curl_cffi import requests
|
||||
r = requests.get('https://httpbin.org/ip', impersonate='chrome120',
|
||||
proxies={'https': 'http://user:pass@proxy:port'})
|
||||
print(r.json())
|
||||
"
|
||||
|
||||
# Check for bot detection
|
||||
distrobox-enter pybox -- python scripts/nodriver-fetch.py \
|
||||
"https://bot.sannysoft.com" \
|
||||
--proxy "http://user:pass@proxy:port" \
|
||||
--screenshot bot-test.png
|
||||
```
|
||||
|
||||
## Cost Optimization
|
||||
|
||||
1. **Use datacenter for non-protected sites** - Save residential bandwidth
|
||||
2. **Cache aggressively** - Don't re-fetch unchanged pages
|
||||
3. **Use API endpoints** - Faster than full browser rendering
|
||||
4. **Rotate only when blocked** - Start with sticky sessions
|
||||
5. **Off-peak scraping** - Some providers charge less at night
|
||||
|
||||
## Troubleshooting
|
||||
|
||||
| Issue | Cause | Fix |
|
||||
|-------|-------|-----|
|
||||
| 403 immediately | Datacenter IP | Use residential |
|
||||
| 403 after few requests | IP burned | Rotate to new IP |
|
||||
| Captcha appears | Suspicious behavior | Slow down, add randomness |
|
||||
| Connection timeout | Bad proxy | Try different proxy/provider |
|
||||
| SSL errors | Proxy doesn't support HTTPS | Use HTTPS proxy or tunnel |
|
||||
@@ -0,0 +1,39 @@
|
||||
#!/bin/bash
|
||||
# Setup stealth browser tools in pybox
|
||||
# Usage: bash scripts/setup.sh
|
||||
|
||||
set -e
|
||||
|
||||
echo "🥷 Setting up stealth browser tools in pybox..."
|
||||
|
||||
# Check if distrobox is available
|
||||
if ! command -v distrobox &> /dev/null; then
|
||||
echo "❌ Error: distrobox not found. Install it first."
|
||||
exit 1
|
||||
fi
|
||||
|
||||
# Check if pybox exists
|
||||
if ! distrobox list | grep -q "pybox"; then
|
||||
echo "❌ Error: pybox container not found."
|
||||
echo " Create it with: distrobox create --name pybox --image fedora:latest"
|
||||
exit 1
|
||||
fi
|
||||
|
||||
echo "📦 Installing Python packages..."
|
||||
distrobox-enter pybox -- pip install --upgrade pip
|
||||
distrobox-enter pybox -- pip install camoufox curl_cffi
|
||||
|
||||
echo "🦊 Installing Camoufox browser..."
|
||||
distrobox-enter pybox -- python -c "import camoufox; camoufox.install()"
|
||||
|
||||
echo "🔧 Installing system dependencies for headed mode..."
|
||||
distrobox-enter pybox -- sudo dnf install -y gtk3 libXt nss at-spi2-atk cups-libs libdrm mesa-libgbm 2>/dev/null || true
|
||||
|
||||
echo ""
|
||||
echo "✅ Setup complete!"
|
||||
echo ""
|
||||
echo "Test with:"
|
||||
echo " distrobox-enter pybox -- python scripts/nodriver-fetch.py https://bot.sannysoft.com --screenshot test.png"
|
||||
echo ""
|
||||
echo "Or for maximum stealth:"
|
||||
echo " distrobox-enter pybox -- python scripts/camoufox-fetch.py https://nowsecure.nl --screenshot test.png"
|
||||
@@ -0,0 +1,59 @@
|
||||
# Cursor CLI Agent Skill
|
||||
|
||||
This repository contains the definition and documentation for the `cursor-agent` skill, updated for 2026 features.
|
||||
|
||||
## Overview
|
||||
|
||||
The `cursor-agent` skill encapsulates workflows and commands for the Cursor CLI, enabling efficient AI-pair programming directly from the terminal. This skill includes all modern features from the January 2026 update.
|
||||
|
||||
## What's New in v2.0.0
|
||||
|
||||
- **Model Switching**: Switch between AI models with `agent models`, `--model` flag, and `/models` command
|
||||
- **MCP Management**: Enable/disable MCP servers on the fly with `/mcp enable` and `/mcp disable`
|
||||
- **Rules & Commands**: Create and edit rules directly from CLI with `/rules` and `/commands`
|
||||
- **Modern Command Interface**: Use `agent` as the primary command (backward compatible with `cursor-agent`)
|
||||
- **Enhanced Headless Mode**: New flags including `--force`, `--output-format json`, and `--stream-partial-output`
|
||||
- **Interactive Features**: Context selection with `@`, slash commands, and keyboard shortcuts
|
||||
- **Cross-Platform Support**: Complete instructions for macOS (including Homebrew), Linux/Ubuntu, and Windows WSL
|
||||
|
||||
## Contents
|
||||
|
||||
- **SKILL.md**: The core skill definition file containing all commands, workflows, and usage instructions
|
||||
- **README.md**: This file, providing an overview and quick reference
|
||||
|
||||
## Quick Start
|
||||
|
||||
Install the Cursor CLI:
|
||||
```bash
|
||||
# Standard installation (macOS, Linux, WSL)
|
||||
curl https://cursor.com/install -fsS | bash
|
||||
|
||||
# Homebrew (macOS only)
|
||||
brew install --cask cursor-cli
|
||||
```
|
||||
|
||||
Authenticate:
|
||||
```bash
|
||||
agent login
|
||||
```
|
||||
|
||||
Start an interactive session:
|
||||
```bash
|
||||
agent
|
||||
```
|
||||
|
||||
Switch models:
|
||||
```bash
|
||||
agent models
|
||||
```
|
||||
|
||||
## Usage
|
||||
|
||||
Refer to `SKILL.md` for comprehensive instructions on:
|
||||
- Installation and authentication
|
||||
- Interactive and non-interactive modes
|
||||
- Model switching and configuration
|
||||
- MCP server management
|
||||
- Rules and commands creation
|
||||
- Slash commands and keyboard shortcuts
|
||||
- Workflows for code review, refactoring, debugging, and CI/CD integration
|
||||
@@ -0,0 +1,310 @@
|
||||
---
|
||||
name: cursor-agent
|
||||
version: 2.1.0
|
||||
description: A comprehensive skill for using the Cursor CLI agent for various software engineering tasks (updated for 2026 features, includes tmux automation guide).
|
||||
author: Pushpinder Pal Singh
|
||||
---
|
||||
|
||||
# Cursor CLI Agent Skill
|
||||
|
||||
This skill provides a comprehensive guide and set of workflows for utilizing the Cursor CLI tool, including all features from the January 2026 update.
|
||||
|
||||
## Installation
|
||||
|
||||
### Standard Installation (macOS, Linux, Windows WSL)
|
||||
|
||||
```bash
|
||||
curl https://cursor.com/install -fsS | bash
|
||||
```
|
||||
|
||||
### Homebrew (macOS only)
|
||||
|
||||
```bash
|
||||
brew install --cask cursor-cli
|
||||
```
|
||||
|
||||
### Post-Installation Setup
|
||||
|
||||
**macOS:**
|
||||
- Add to PATH in `~/.zshrc` (zsh) or `~/.bashrc` (bash):
|
||||
```bash
|
||||
export PATH="$HOME/.local/bin:$PATH"
|
||||
```
|
||||
- Restart terminal or run `source ~/.zshrc` (or `~/.bashrc`)
|
||||
- Requires macOS 10.15 or later
|
||||
- Works on both Intel and Apple Silicon Macs
|
||||
|
||||
**Linux/Ubuntu:**
|
||||
- Restart your terminal or source your shell config
|
||||
- Verify with `agent --version`
|
||||
|
||||
**Both platforms:**
|
||||
- Commands: `agent` (primary) and `cursor-agent` (backward compatible)
|
||||
- Verify installation: `agent --version` or `cursor-agent --version`
|
||||
|
||||
## Authentication
|
||||
|
||||
Authenticate via browser:
|
||||
|
||||
```bash
|
||||
agent login
|
||||
```
|
||||
|
||||
Or use API key:
|
||||
|
||||
```bash
|
||||
export CURSOR_API_KEY=your_api_key_here
|
||||
```
|
||||
|
||||
## Update
|
||||
|
||||
Keep your CLI up to date:
|
||||
|
||||
```bash
|
||||
agent update
|
||||
# or
|
||||
agent upgrade
|
||||
```
|
||||
|
||||
## Commands
|
||||
|
||||
### Interactive Mode
|
||||
|
||||
Start an interactive session with the agent:
|
||||
|
||||
```bash
|
||||
agent
|
||||
```
|
||||
|
||||
Start with an initial prompt:
|
||||
|
||||
```bash
|
||||
agent "Add error handling to this API"
|
||||
```
|
||||
|
||||
**Backward compatibility:** `cursor-agent` still works but `agent` is now the primary command.
|
||||
|
||||
### Model Switching
|
||||
|
||||
List all available models:
|
||||
|
||||
```bash
|
||||
agent models
|
||||
# or
|
||||
agent --list-models
|
||||
```
|
||||
|
||||
Use a specific model:
|
||||
|
||||
```bash
|
||||
agent --model gpt-5
|
||||
```
|
||||
|
||||
Switch models during a session:
|
||||
|
||||
```
|
||||
/models
|
||||
```
|
||||
|
||||
### Session Management
|
||||
|
||||
Manage your agent sessions:
|
||||
|
||||
- **List sessions:** `agent ls`
|
||||
- **Resume most recent:** `agent resume`
|
||||
- **Resume specific session:** `agent --resume="[chat-id]"`
|
||||
|
||||
### Context Selection
|
||||
|
||||
Include specific files or folders in the conversation:
|
||||
|
||||
```
|
||||
@filename.ts
|
||||
@src/components/
|
||||
```
|
||||
|
||||
### Slash Commands
|
||||
|
||||
Available during interactive sessions:
|
||||
|
||||
- **`/models`** - Switch between AI models interactively
|
||||
- **`/compress`** - Summarize conversation and free up context window
|
||||
- **`/rules`** - Create and edit rules directly from CLI
|
||||
- **`/commands`** - Create and modify custom commands
|
||||
- **`/mcp enable [server-name]`** - Enable an MCP server
|
||||
- **`/mcp disable [server-name]`** - Disable an MCP server
|
||||
|
||||
### Keyboard Shortcuts
|
||||
|
||||
- **`Shift+Enter`** - Add newlines for multi-line prompts
|
||||
- **`Ctrl+D`** - Exit CLI (requires double-press for safety)
|
||||
- **`Ctrl+R`** - Review changes (press `i` for instructions, navigate with arrow keys)
|
||||
- **`ArrowUp`** - Cycle through previous messages
|
||||
|
||||
### Non-interactive / CI Mode
|
||||
|
||||
Run the agent in a non-interactive mode, suitable for CI/CD pipelines:
|
||||
|
||||
```bash
|
||||
agent -p 'Run tests and report coverage'
|
||||
# or
|
||||
agent --print 'Refactor this file to use async/await'
|
||||
```
|
||||
|
||||
**Output formats:**
|
||||
|
||||
```bash
|
||||
# Plain text (default)
|
||||
agent -p 'Analyze code' --output-format text
|
||||
|
||||
# Structured JSON
|
||||
agent -p 'Find bugs' --output-format json
|
||||
|
||||
# Real-time streaming JSON
|
||||
agent -p 'Run tests' --output-format stream-json --stream-partial-output
|
||||
```
|
||||
|
||||
**Force mode (auto-apply changes without confirmation):**
|
||||
|
||||
```bash
|
||||
agent -p 'Fix all linting errors' --force
|
||||
```
|
||||
|
||||
**Media support:**
|
||||
|
||||
```bash
|
||||
agent -p 'Analyze this screenshot: screenshot.png'
|
||||
```
|
||||
|
||||
### ⚠️ Using with AI Agents / Automation (tmux required)
|
||||
|
||||
**CRITICAL:** When running Cursor CLI from automated environments (AI agents, scripts, subprocess calls), the CLI requires a real TTY. Direct execution will hang indefinitely.
|
||||
|
||||
**The Solution: Use tmux**
|
||||
|
||||
```bash
|
||||
# 1. Install tmux if not available
|
||||
sudo apt install tmux # Ubuntu/Debian
|
||||
brew install tmux # macOS
|
||||
|
||||
# 2. Create a tmux session
|
||||
tmux kill-session -t cursor 2>/dev/null || true
|
||||
tmux new-session -d -s cursor
|
||||
|
||||
# 3. Navigate to project
|
||||
tmux send-keys -t cursor "cd /path/to/project" Enter
|
||||
sleep 1
|
||||
|
||||
# 4. Run Cursor agent
|
||||
tmux send-keys -t cursor "agent 'Your task here'" Enter
|
||||
|
||||
# 5. Handle workspace trust prompt (first run)
|
||||
sleep 3
|
||||
tmux send-keys -t cursor "a" # Trust workspace
|
||||
|
||||
# 6. Wait for completion
|
||||
sleep 60 # Adjust based on task complexity
|
||||
|
||||
# 7. Capture output
|
||||
tmux capture-pane -t cursor -p -S -100
|
||||
|
||||
# 8. Verify results
|
||||
ls -la /path/to/project/
|
||||
```
|
||||
|
||||
**Why this works:**
|
||||
- tmux provides a persistent pseudo-terminal (PTY)
|
||||
- Cursor's TUI requires interactive terminal capabilities
|
||||
- Direct `agent` calls from subprocess/exec hang without TTY
|
||||
|
||||
**What does NOT work:**
|
||||
```bash
|
||||
# ❌ These will hang indefinitely:
|
||||
agent "task" # No TTY
|
||||
agent -p "task" # No TTY
|
||||
subprocess.run(["agent", ...]) # No TTY
|
||||
script -c "agent ..." /dev/null # May crash Cursor
|
||||
```
|
||||
|
||||
## Rules & Configuration
|
||||
|
||||
The agent automatically loads rules from:
|
||||
- `.cursor/rules`
|
||||
- `AGENTS.md`
|
||||
- `CLAUDE.md`
|
||||
|
||||
Use `/rules` command to create and edit rules directly from the CLI.
|
||||
|
||||
## MCP Integration
|
||||
|
||||
MCP servers are automatically loaded from `mcp.json` configuration.
|
||||
|
||||
Enable/disable servers on the fly:
|
||||
|
||||
```
|
||||
/mcp enable server-name
|
||||
/mcp disable server-name
|
||||
```
|
||||
|
||||
**Note:** Server names with spaces are fully supported.
|
||||
|
||||
## Workflows
|
||||
|
||||
### Code Review
|
||||
|
||||
Perform a code review on the current changes or a specific branch:
|
||||
|
||||
```bash
|
||||
agent -p 'Review the changes in the current branch against main. Focus on security and performance.'
|
||||
```
|
||||
|
||||
### Refactoring
|
||||
|
||||
Refactor code for better readability or performance:
|
||||
|
||||
```bash
|
||||
agent -p 'Refactor src/utils.ts to reduce complexity and improve type safety.'
|
||||
```
|
||||
|
||||
### Debugging
|
||||
|
||||
Analyze logs or error messages to find the root cause:
|
||||
|
||||
```bash
|
||||
agent -p 'Analyze the following error log and suggest a fix: [paste log here]'
|
||||
```
|
||||
|
||||
### Git Integration
|
||||
|
||||
Automate git operations with context awareness:
|
||||
|
||||
```bash
|
||||
agent -p 'Generate a commit message for the staged changes adhering to conventional commits.'
|
||||
```
|
||||
|
||||
### Batch Processing (CI/CD)
|
||||
|
||||
Run automated checks in CI pipelines:
|
||||
|
||||
```bash
|
||||
# Set API key in CI environment
|
||||
export CURSOR_API_KEY=$CURSOR_API_KEY
|
||||
|
||||
# Run security audit with JSON output
|
||||
agent -p 'Audit this codebase for security vulnerabilities' --output-format json --force
|
||||
|
||||
# Generate test coverage report
|
||||
agent -p 'Run tests and generate coverage report' --output-format text
|
||||
```
|
||||
|
||||
### Multi-file Analysis
|
||||
|
||||
Use context selection to analyze multiple files:
|
||||
|
||||
```bash
|
||||
agent
|
||||
# Then in interactive mode:
|
||||
@src/api/
|
||||
@src/models/
|
||||
Review the API implementation for consistency with our data models
|
||||
```
|
||||
@@ -0,0 +1,11 @@
|
||||
{
|
||||
"owner": "swiftlysingh",
|
||||
"slug": "cursor-agent",
|
||||
"displayName": "Cursor CLI Agent",
|
||||
"latest": {
|
||||
"version": "2.1.0",
|
||||
"publishedAt": 1768339191701,
|
||||
"commit": "https://github.com/clawdbot/skills/commit/785f5c8ae12bc3467a2be475ebe81dd1950246ce"
|
||||
},
|
||||
"history": []
|
||||
}
|
||||
@@ -0,0 +1,29 @@
|
||||
# Skill: deep-scraper
|
||||
|
||||
## Overview
|
||||
A high-performance engineering tool for deep web scraping. It uses a containerized Docker + Crawlee (Playwright) environment to penetrate protections on complex websites like YouTube and X/Twitter, providing "interception-level" raw data.
|
||||
|
||||
## Requirements
|
||||
1. **Docker**: Must be installed and running on the host machine.
|
||||
2. **Image**: Build the environment with the tag `clawd-crawlee`.
|
||||
* Build command: `docker build -t clawd-crawlee skills/deep-scraper/`
|
||||
|
||||
## Integration Guide
|
||||
Simply copy the `skills/deep-scraper` directory into your `skills/` folder. Ensure the Dockerfile remains within the skill directory for self-contained deployment.
|
||||
|
||||
## Standard Interface (CLI)
|
||||
```bash
|
||||
docker run -t --rm -v $(pwd)/skills/deep-scraper/assets:/usr/src/app/assets clawd-crawlee node assets/main_handler.js [TARGET_URL]
|
||||
```
|
||||
|
||||
## Output Specification (JSON)
|
||||
The scraping results are printed to stdout as a JSON string:
|
||||
- `status`: SUCCESS | PARTIAL | ERROR
|
||||
- `type`: TRANSCRIPT | DESCRIPTION | GENERIC
|
||||
- `videoId`: (For YouTube) The validated Video ID.
|
||||
- `data`: The core text content or transcript.
|
||||
|
||||
## Core Rules
|
||||
1. **ID Validation**: All YouTube tasks MUST verify the Video ID to prevent cache contamination.
|
||||
2. **Privacy**: Strictly forbidden from scraping password-protected or non-public personal information.
|
||||
3. **Alpha-Focused**: Automatically strips ads and noise, delivering pure data optimized for LLM processing.
|
||||
@@ -0,0 +1,11 @@
|
||||
{
|
||||
"owner": "opsun",
|
||||
"slug": "deep-scraper",
|
||||
"displayName": "Deep Scraper",
|
||||
"latest": {
|
||||
"version": "1.0.1",
|
||||
"publishedAt": 1770205151953,
|
||||
"commit": "https://github.com/clawdbot/skills/commit/0609dee8b158bc95d246a5446f5c4ab95f54cac7"
|
||||
},
|
||||
"history": []
|
||||
}
|
||||
@@ -0,0 +1,27 @@
|
||||
{
|
||||
"name": "deep-scraper",
|
||||
"version": "1.0.0",
|
||||
"description": "High-performance containerized scraper for YouTube, X (Twitter), and dynamic SPAs. Features raw API interception and ID validation.",
|
||||
"main": "assets/main_handler.js",
|
||||
"scripts": {
|
||||
"test": "node assets/main_handler.js https://www.youtube.com/watch?v=dQw4w9WgXcQ"
|
||||
},
|
||||
"keywords": [
|
||||
"scraper",
|
||||
"crawlee",
|
||||
"youtube",
|
||||
"alpha",
|
||||
"openclaw"
|
||||
],
|
||||
"author": "Joseph",
|
||||
"license": "MIT",
|
||||
"dependencies": {
|
||||
"crawlee": "^3.0.0",
|
||||
"playwright": "^1.40.0"
|
||||
},
|
||||
"openclaw": {
|
||||
"requires": {
|
||||
"docker": true
|
||||
}
|
||||
}
|
||||
}
|
||||
@@ -0,0 +1,194 @@
|
||||
---
|
||||
name: desktop-browser
|
||||
description: 通过真实桌面操作浏览器自动化，包含反检测模式。使用场景：(1) 需要登录或 cookie 认证的网站操作 (2) 需要保持会话状态的浏览器操作 (3) OpenClaw 浏览器失败时的备选方案 (4) 需要操作桌面应用的场景 (5) 反检测浏览器操作
|
||||
---
|
||||
|
||||
# Desktop Browser Skill
|
||||
|
||||
通过 X11 连接真实桌面，操作 Chrome/Chromium 浏览器进行自动化。
|
||||
|
||||
## 快速开始
|
||||
|
||||
### 环境要求
|
||||
|
||||
```bash
|
||||
# 安装依赖
|
||||
pip install pyautogui pillow gnome-screenshot
|
||||
|
||||
# 复制 Xauthority (首次需要)
|
||||
cp /home/yh6788/.Xauthority /root/
|
||||
```
|
||||
|
||||
### 基础操作
|
||||
|
||||
```python
|
||||
import pyautogui
|
||||
import os
|
||||
|
||||
# 设置环境变量
|
||||
os.environ['DISPLAY'] = ':0'
|
||||
os.environ['XAUTHORITY'] = '/home/yh6788/.Xauthority'
|
||||
|
||||
# 截图
|
||||
img = pyautogui.screenshot('/path/to/screenshot.png')
|
||||
|
||||
# 点击坐标 (需先获取坐标)
|
||||
pyautogui.click(x, y)
|
||||
|
||||
# 输入文字
|
||||
pyautogui.typewrite("text", interval=0.1)
|
||||
|
||||
# 快捷键
|
||||
pyautogui.hotkey('ctrl', 't') # 新标签页
|
||||
pyautogui.hotkey('ctrl', 'w') # 关闭标签页
|
||||
```
|
||||
|
||||
## 反检测浏览器 (Camoufox)
|
||||
|
||||
### 什么是 Camoufox
|
||||
|
||||
Camoufox 是基于 Firefox 的反检测浏览器，在 C++ 级别进行指纹伪装，能绕过：
|
||||
- Cloudflare Turnstile
|
||||
- Datadome
|
||||
- Airbnb
|
||||
- Yelp
|
||||
- 其他反爬虫机制
|
||||
|
||||
### 使用 Camoufox
|
||||
|
||||
**方式1: 通过命令行调用 Camoufox**
|
||||
|
||||
```bash
|
||||
# 进入 pybox 容器
|
||||
distrobox-enter pybox
|
||||
|
||||
# 使用 Camoufox 打开网站
|
||||
python3.14 -m camoufox open https://example.com
|
||||
```
|
||||
|
||||
**方式2: 桌面浏览器改用 Camoufox**
|
||||
|
||||
1. 安装 Camoufox: `distrobox-enter pybox -- python3.14 -m pip install camoufox`
|
||||
2. 桌面浏览器使用 Camoufox 替代 Chrome
|
||||
|
||||
### Camoufox vs 普通浏览器
|
||||
|
||||
| 特性 | Desktop Browser (普通) | Camoufox (反检测) |
|
||||
|------|----------------------|-----------------|
|
||||
| 反指纹 | ❌ | ✅ C++级别 |
|
||||
| Cloudflare | ❌ | ✅ 自动绕过 |
|
||||
| 代理支持 | 系统代理 | 可配置 Residential |
|
||||
| 速度 | 快 | 稍慢 |
|
||||
|
||||
### 何时用反检测
|
||||
|
||||
- OpenClaw 浏览器被检测
|
||||
- 遇到 Cloudflare 挑战
|
||||
- 目标网站反爬严格
|
||||
- 普通浏览器无法访问
|
||||
|
||||
### 启动反检测环境
|
||||
|
||||
```bash
|
||||
# 启动 pybox 容器
|
||||
distrobox start pybox
|
||||
|
||||
# 进入容器
|
||||
distrobox-enter pybox
|
||||
|
||||
# 安装 Camoufox (首次)
|
||||
python3.14 -m pip install camoufox
|
||||
```
|
||||
|
||||
### 注意事项
|
||||
|
||||
- Camoufox 需要在 pybox 中运行
|
||||
- 首次运行会自动下载 (~700MB)
|
||||
- 建议使用 residential 代理 (数据中心IP容易被封)
|
||||
|
||||
## 获取坐标
|
||||
|
||||
### 方法1: 手动获取
|
||||
|
||||
1. 截取屏幕
|
||||
2. 用图片查看器查看坐标
|
||||
3. 记录需要点击的位置
|
||||
|
||||
### 方法2: 打印鼠标位置
|
||||
|
||||
```python
|
||||
import pyautogui
|
||||
while True:
|
||||
print(pyautogui.position())
|
||||
time.sleep(1)
|
||||
```
|
||||
|
||||
## 常用脚本
|
||||
|
||||
### 打开浏览器并操作
|
||||
|
||||
```python
|
||||
import pyautogui
|
||||
import time
|
||||
|
||||
os.environ['DISPLAY'] = ':0'
|
||||
os.environ['XAUTHORITY'] = '/home/yh6788/.Xauthority'
|
||||
|
||||
# 点击任务栏 Chrome 图标 (位置需根据实际情况调整)
|
||||
pyautogui.click(100, 1050) # 假设 Chrome 在左下角
|
||||
time.sleep(2)
|
||||
|
||||
# 新标签页
|
||||
pyautogui.hotkey('ctrl', 't')
|
||||
time.sleep(0.5)
|
||||
|
||||
# 输入网址
|
||||
pyautogui.typewrite("https://www.example.com", interval=0.05)
|
||||
pyautogui.press('enter')
|
||||
time.sleep(3)
|
||||
|
||||
# 截图
|
||||
pyautogui.screenshot('result.png')
|
||||
```
|
||||
|
||||
### 自动登录
|
||||
|
||||
```python
|
||||
# 1. 截取登录界面
|
||||
# 2. 点击用户名输入框
|
||||
pyautogui.click(username_x, username_y)
|
||||
pyautogui.typewrite("username", interval=0.1)
|
||||
|
||||
# 3. 点击密码输入框
|
||||
pyautogui.click(password_x, password_y)
|
||||
pyautogui.typewrite("password", interval=0.1)
|
||||
|
||||
# 4. 点击登录按钮或按回车
|
||||
pyautogui.press('enter')
|
||||
```
|
||||
|
||||
## 注意事项
|
||||
|
||||
- 坐标需要根据屏幕分辨率调整 (当前: 1366x768)
|
||||
- 操作间隙添加 time.sleep() 等待页面加载
|
||||
- 敏感操作前先截图确认
|
||||
- XAUTHORITY 必须正确，否则无法连接桌面
|
||||
|
||||
## 故障排除
|
||||
|
||||
### Xlib 认证错误
|
||||
|
||||
```
|
||||
Xlib.error.DisplayConnectionError: Can't connect to display ":0"
|
||||
```
|
||||
|
||||
解决:
|
||||
```bash
|
||||
cp /home/yh6788/.Xauthority /root/
|
||||
export XAUTHORITY=/home/yh6788/.Xauthority
|
||||
```
|
||||
|
||||
### 坐标不准
|
||||
|
||||
- 截图后用图像查看器确认坐标
|
||||
- 不同分辨率坐标不同
|
||||
@@ -0,0 +1,47 @@
|
||||
#!/bin/bash
|
||||
# Desktop Browser 快捷命令
|
||||
# 用法: desktop-browser.sh screenshot|click|type|press|hotkey|open|pos [参数]
|
||||
|
||||
export DISPLAY=:0
|
||||
export XAUTHORITY=/home/yh6788/.Xauthority
|
||||
|
||||
SCRIPT_DIR="$(cd "$(dirname "$0")" && pwd)"
|
||||
|
||||
case "$1" in
|
||||
screenshot)
|
||||
python3 "$SCRIPT_DIR/desktop_browser.py" screenshot "${2:-/root/.openclaw/workspace/desktop.png}"
|
||||
;;
|
||||
click)
|
||||
python3 "$SCRIPT_DIR/desktop_browser.py" click "$2" "$3"
|
||||
;;
|
||||
type)
|
||||
shift
|
||||
python3 "$SCRIPT_DIR/desktop_browser.py" type "$@"
|
||||
;;
|
||||
press)
|
||||
python3 "$SCRIPT_DIR/desktop_browser.py" press "$2"
|
||||
;;
|
||||
hotkey)
|
||||
shift
|
||||
python3 "$SCRIPT_DIR/desktop_browser.py" hotkey "$@"
|
||||
;;
|
||||
open)
|
||||
python3 "$SCRIPT_DIR/desktop_browser.py" open "$2"
|
||||
;;
|
||||
pos)
|
||||
python3 "$SCRIPT_DIR/desktop_browser.py" pos
|
||||
;;
|
||||
*)
|
||||
echo "用法: $0 {screenshot|click|type|press|hotkey|open|pos} [参数]"
|
||||
echo ""
|
||||
echo "示例:"
|
||||
echo " $0 screenshot # 截图到默认位置"
|
||||
echo " $0 screenshot /path/to/img.png # 截图到指定位置"
|
||||
echo " $0 click 100 200 # 点击坐标 (100,200)"
|
||||
echo " $0 type Hello World # 输入文字"
|
||||
echo " $0 press enter # 按键"
|
||||
echo " $0 hotkey ctrl t # 快捷键"
|
||||
echo " $0 open https://baidu.com # 打开网址"
|
||||
echo " $0 pos # 打印鼠标位置"
|
||||
;;
|
||||
esac
|
||||
@@ -0,0 +1,448 @@
|
||||
# AI Desktop Agent - Cognitive Automation Guide
|
||||
|
||||
## 🤖 What Is This?
|
||||
|
||||
The **AI Desktop Agent** is an intelligent layer on top of the basic desktop control that **understands** what you want and figures out how to do it autonomously.
|
||||
|
||||
Unlike basic automation that requires exact instructions, the AI Agent:
|
||||
- **Understands natural language** ("Draw a cat in Paint")
|
||||
- **Plans the steps** automatically
|
||||
- **Executes autonomously**
|
||||
- **Adapts** based on what it sees
|
||||
|
||||
---
|
||||
|
||||
## 🎯 What Can It Do?
|
||||
|
||||
### ✅ Autonomous Drawing
|
||||
```python
|
||||
from skills.desktop_control.ai_agent import AIDesktopAgent
|
||||
|
||||
agent = AIDesktopAgent()
|
||||
|
||||
# Just describe what you want!
|
||||
agent.execute_task("Draw a circle in Paint")
|
||||
agent.execute_task("Draw a star in MS Paint")
|
||||
agent.execute_task("Draw a house with a sun")
|
||||
```
|
||||
|
||||
**What it does:**
|
||||
1. Opens MS Paint
|
||||
2. Selects pencil tool
|
||||
3. Figures out how to draw the requested shape
|
||||
4. Draws it autonomously
|
||||
5. Takes a screenshot of the result
|
||||
|
||||
### ✅ Autonomous Text Entry
|
||||
```python
|
||||
# It figures out where to type
|
||||
agent.execute_task("Type 'Hello World' in Notepad")
|
||||
agent.execute_task("Write an email saying thank you")
|
||||
```
|
||||
|
||||
**What it does:**
|
||||
1. Opens Notepad (or finds active text editor)
|
||||
2. Types the text naturally
|
||||
3. Formats if needed
|
||||
|
||||
### ✅ Autonomous Application Control
|
||||
```python
|
||||
# It knows how to open apps
|
||||
agent.execute_task("Open Calculator")
|
||||
agent.execute_task("Launch Microsoft Paint")
|
||||
agent.execute_task("Open File Explorer")
|
||||
```
|
||||
|
||||
### ✅ Autonomous Game Playing (Advanced)
|
||||
```python
|
||||
# It will try to play the game!
|
||||
agent.execute_task("Play Solitaire for me")
|
||||
agent.execute_task("Play Minesweeper")
|
||||
```
|
||||
|
||||
**What it does:**
|
||||
1. Analyzes the game screen
|
||||
2. Detects game state (cards, mines, etc.)
|
||||
3. Decides best move
|
||||
4. Executes the move
|
||||
5. Repeats until win/lose
|
||||
|
||||
---
|
||||
|
||||
## 🏗️ How It Works
|
||||
|
||||
### Architecture
|
||||
|
||||
```
|
||||
User Request ("Draw a cat")
|
||||
↓
|
||||
Natural Language Understanding
|
||||
↓
|
||||
Task Planning (Step-by-step plan)
|
||||
↓
|
||||
Step Execution Loop:
|
||||
- Observe Screen (Computer Vision)
|
||||
- Decide Action (AI Reasoning)
|
||||
- Execute Action (Desktop Control)
|
||||
- Verify Result
|
||||
↓
|
||||
Task Complete!
|
||||
```
|
||||
|
||||
### Key Components
|
||||
|
||||
1. **Task Planner** - Breaks down high-level tasks into steps
|
||||
2. **Vision System** - Understands what's on screen (screenshots, OCR, object detection)
|
||||
3. **Reasoning Engine** - Decides what to do next
|
||||
4. **Action Executor** - Performsthe actual mouse/keyboard actions
|
||||
5. **Feedback Loop** - Verifies actions succeeded
|
||||
|
||||
---
|
||||
|
||||
## 📋 Supported Tasks (Current)
|
||||
|
||||
### Tier 1: Fully Automated ✅
|
||||
|
||||
| Task Pattern | Example | Status |
|
||||
|-------------|---------|---------|
|
||||
| Draw shapes in Paint | "Draw a circle" | ✅ Working |
|
||||
| Basic text entry | "Type Hello" | ✅ Working |
|
||||
| Launch applications | "Open Paint" | ✅ Working |
|
||||
|
||||
### Tier 2: Partially Automated 🔨
|
||||
|
||||
| Task Pattern | Example | Status |
|
||||
|-------------|---------|---------|
|
||||
| Form filling | "Fill out this form" | 🔨 In Progress |
|
||||
| File operations | "Copy these files" | 🔨 In Progress |
|
||||
| Web navigation | "Find on Google" | 🔨 Planned |
|
||||
|
||||
### Tier 3: Experimental 🧪
|
||||
|
||||
| Task Pattern | Example | Status |
|
||||
|-------------|---------|---------|
|
||||
| Game playing | "Play Solitaire" | 🧪 Experimental |
|
||||
| Image editing | "Resize this photo" | 🧪 Planned |
|
||||
| Code editing | "Fix this bug" | 🧪 Research |
|
||||
|
||||
---
|
||||
|
||||
## 🎨 Example: Drawing in Paint
|
||||
|
||||
### Simple Request
|
||||
```python
|
||||
agent = AIDesktopAgent()
|
||||
result = agent.execute_task("Draw a circle in Paint")
|
||||
|
||||
# Check result
|
||||
print(f"Status: {result['status']}")
|
||||
print(f"Steps taken: {len(result['steps'])}")
|
||||
```
|
||||
|
||||
### What Happens Behind the Scenes
|
||||
|
||||
**1. Planning Phase:**
|
||||
```
|
||||
Plan generated:
|
||||
Step 1: Launch MS Paint
|
||||
Step 2: Wait 2s for Paint to load
|
||||
Step 3: Activate Paint window
|
||||
Step 4: Select pencil tool (press 'P')
|
||||
Step 5: Draw circle at canvas center
|
||||
Step 6: Screenshot the result
|
||||
```
|
||||
|
||||
**2. Execution Phase:**
|
||||
```
|
||||
[✓] Launched Paint via Win+R → mspaint
|
||||
[✓] Waited 2.0s
|
||||
[✓] Activated window "Paint"
|
||||
[✓] Pressed 'P' to select pencil
|
||||
[✓] Drew circle with 72 points
|
||||
[✓] Screenshot saved: drawing_result.png
|
||||
```
|
||||
|
||||
**3. Result:**
|
||||
```python
|
||||
{
|
||||
"task": "Draw a circle in Paint",
|
||||
"status": "completed",
|
||||
"success": True,
|
||||
"steps": [... 6 steps ...],
|
||||
"screenshots": [... 6 screenshots ...],
|
||||
}
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 🎮 Example: Game Playing
|
||||
|
||||
```python
|
||||
agent = AIDesktopAgent()
|
||||
|
||||
# Play a simple game
|
||||
result = agent.execute_task("Play Solitaire for me")
|
||||
```
|
||||
|
||||
### Game Playing Loop
|
||||
|
||||
```
|
||||
1. Analyze screen → Detect cards, positions
|
||||
2. Identify valid moves → Find legal plays
|
||||
3. Evaluate moves → Which is best?
|
||||
4. Execute move → Click and drag card
|
||||
5. Repeat until game ends
|
||||
```
|
||||
|
||||
### Game-Specific Intelligence
|
||||
|
||||
The agent can learn patterns for:
|
||||
- **Solitaire**: Card stacking rules, suit matching
|
||||
- **Minesweeper**: Probability calculations, safe clicks
|
||||
- **2048**: Tile merging strategy
|
||||
- **Chess** (if integrated with engine): Move evaluation
|
||||
|
||||
---
|
||||
|
||||
## 🧠 Enhancing the AI
|
||||
|
||||
### Adding Application Knowledge
|
||||
|
||||
```python
|
||||
# In ai_agent.py, add to app_knowledge:
|
||||
|
||||
self.app_knowledge = {
|
||||
"photoshop": {
|
||||
"name": "Adobe Photoshop",
|
||||
"launch_command": "photoshop",
|
||||
"common_actions": {
|
||||
"new_layer": {"hotkey": ["ctrl", "shift", "n"]},
|
||||
"brush_tool": {"hotkey": ["b"]},
|
||||
"eraser": {"hotkey": ["e"]},
|
||||
}
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
### Adding Custom Task Patterns
|
||||
|
||||
```python
|
||||
# Add a custom planning method
|
||||
def _plan_photo_edit(self, task: str) -> List[Dict]:
|
||||
"""Plan for photo editing tasks."""
|
||||
return [
|
||||
{"type": "launch_app", "app": "photoshop"},
|
||||
{"type": "wait", "duration": 3.0},
|
||||
{"type": "open_file", "path": extracted_path},
|
||||
{"type": "apply_filter", "filter": extracted_filter},
|
||||
{"type": "save_file"},
|
||||
]
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 🔥 Advanced: Vision + Reasoning
|
||||
|
||||
### Screen Analysis
|
||||
|
||||
The agent can analyze screenshots to:
|
||||
- **Detect UI elements** (buttons, text fields, menus)
|
||||
- **Read text** (OCR for labels, instructions)
|
||||
- **Identify objects** (icons, images, game pieces)
|
||||
- **Understand layout** (where things are)
|
||||
|
||||
```python
|
||||
# Analyze what's on screen
|
||||
analysis = agent._analyze_screen()
|
||||
|
||||
print(analysis)
|
||||
# Output:
|
||||
# {
|
||||
# "active_window": "Untitled - Paint",
|
||||
# "mouse_position": (640, 480),
|
||||
# "detected_elements": [...],
|
||||
# "text_found": [...],
|
||||
# }
|
||||
```
|
||||
|
||||
### Integration with OpenClaw LLM
|
||||
|
||||
```python
|
||||
# Future: Use OpenClaw's LLM for reasoning
|
||||
agent = AIDesktopAgent(llm_client=openclaw_llm)
|
||||
|
||||
# The agent can now:
|
||||
# - Reason about complex tasks
|
||||
# - Understand context better
|
||||
# - Plan more sophisticated workflows
|
||||
# - Learn from feedback
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 🛠️ Extending for Your Needs
|
||||
|
||||
### Add Support for New Apps
|
||||
|
||||
1. **Identify the app**
|
||||
2. **Document common actions**
|
||||
3. **Add to knowledge base**
|
||||
4. **Create planning method**
|
||||
|
||||
Example: Adding Excel support
|
||||
|
||||
```python
|
||||
# Step 1: Add to app_knowledge
|
||||
"excel": {
|
||||
"name": "Microsoft Excel",
|
||||
"launch_command": "excel",
|
||||
"common_actions": {
|
||||
"new_sheet": {"hotkey": ["shift", "f11"]},
|
||||
"sum_formula": {"action": "type", "text": "=SUM()"},
|
||||
}
|
||||
}
|
||||
|
||||
# Step 2: Create planner
|
||||
def _plan_excel_task(self, task: str) -> List[Dict]:
|
||||
return [
|
||||
{"type": "launch_app", "app": "excel"},
|
||||
{"type": "wait", "duration": 2.0},
|
||||
# ... specific Excel steps
|
||||
]
|
||||
|
||||
# Step 3: Hook into main planner
|
||||
if "excel" in task_lower or "spreadsheet" in task_lower:
|
||||
return self._plan_excel_task(task)
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 🎯 Real-World Use Cases
|
||||
|
||||
### 1. Automated Form Filling
|
||||
```python
|
||||
agent.execute_task("Fill out the job application with my resume data")
|
||||
```
|
||||
|
||||
### 2. Batch Image Processing
|
||||
```python
|
||||
agent.execute_task("Resize all images in this folder to 800x600")
|
||||
```
|
||||
|
||||
### 3. Social Media Posting
|
||||
```python
|
||||
agent.execute_task("Post this image to Instagram with caption 'Beautiful sunset'")
|
||||
```
|
||||
|
||||
### 4. Data Entry
|
||||
```python
|
||||
agent.execute_task("Copy data from this PDF to Excel spreadsheet")
|
||||
```
|
||||
|
||||
### 5. Testing
|
||||
```python
|
||||
agent.execute_task("Test the login form with invalid credentials")
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## ⚙️ Configuration
|
||||
|
||||
### Enable/Disable Failsafe
|
||||
```python
|
||||
# Safe mode (default)
|
||||
agent = AIDesktopAgent(failsafe=True)
|
||||
|
||||
# Fast mode (no failsafe)
|
||||
agent = AIDesktopAgent(failsafe=False)
|
||||
```
|
||||
|
||||
### Set Max Steps
|
||||
```python
|
||||
# Prevent infinite loops
|
||||
result = agent.execute_task("Play game", max_steps=100)
|
||||
```
|
||||
|
||||
### Access Action History
|
||||
```python
|
||||
# Review what the agent did
|
||||
print(agent.action_history)
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 🐛 Debugging
|
||||
|
||||
### View Step-by-Step Execution
|
||||
```python
|
||||
result = agent.execute_task("Draw a star in Paint")
|
||||
|
||||
for i, step in enumerate(result['steps'], 1):
|
||||
print(f"Step {i}: {step['step']['description']}")
|
||||
print(f" Success: {step['success']}")
|
||||
if 'error' in step:
|
||||
print(f" Error: {step['error']}")
|
||||
```
|
||||
|
||||
### View Screenshots
|
||||
```python
|
||||
# Each step captures before/after screenshots
|
||||
for screenshot_pair in result['screenshots']:
|
||||
before = screenshot_pair['before']
|
||||
after = screenshot_pair['after']
|
||||
|
||||
# Display or save for analysis
|
||||
before.save(f"step_{screenshot_pair['step']}_before.png")
|
||||
after.save(f"step_{screenshot_pair['step']}_after.png")
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 🚀 Future Enhancements
|
||||
|
||||
Planned features:
|
||||
|
||||
- [ ] **Computer Vision**: OCR, object detection, UI element recognition
|
||||
- [ ] **LLM Integration**: Natural language understanding with OpenClaw LLM
|
||||
- [ ] **Learning**: Remember successful patterns, improve over time
|
||||
- [ ] **Multi-App Workflows**: "Get data from Chrome and put in Excel"
|
||||
- [ ] **Voice Control**: "Alexa, draw a cat in Paint"
|
||||
- [ ] **Autonomous Debugging**: Fix errors automatically
|
||||
- [ ] **Game AI**: Reinforcement learning for game playing
|
||||
- [ ] **Web Automation**: Full browser control with understanding
|
||||
|
||||
---
|
||||
|
||||
## 📚 Full API
|
||||
|
||||
### Main Methods
|
||||
|
||||
```python
|
||||
# Execute a task
|
||||
result = agent.execute_task(task: str, max_steps: int = 50)
|
||||
|
||||
# Analyze screen
|
||||
analysis = agent._analyze_screen()
|
||||
|
||||
# Manual mode: Execute individual steps
|
||||
step = {"type": "launch_app", "app": "paint"}
|
||||
result = agent._execute_step(step)
|
||||
```
|
||||
|
||||
### Result Structure
|
||||
|
||||
```python
|
||||
{
|
||||
"task": str, # Original task
|
||||
"status": str, # "completed", "failed", "error"
|
||||
"success": bool, # Overall success
|
||||
"steps": List[Dict], # All steps executed
|
||||
"screenshots": List[Dict], # Before/after screenshots
|
||||
"failed_at_step": int, # If failed, which step
|
||||
"error": str, # Error message if failed
|
||||
}
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
**🦞 Built for OpenClaw - The future of desktop automation!**
|
||||
@@ -0,0 +1,269 @@
|
||||
# Desktop Control - Quick Reference Card
|
||||
|
||||
## 🚀 Instant Start
|
||||
|
||||
```python
|
||||
from skills.desktop_control import DesktopController
|
||||
|
||||
dc = DesktopController()
|
||||
```
|
||||
|
||||
## 🖱️ Mouse Control (Top 10)
|
||||
|
||||
```python
|
||||
# 1. Move mouse
|
||||
dc.move_mouse(500, 300, duration=0.5)
|
||||
|
||||
# 2. Click
|
||||
dc.click(500, 300) # Left click at position
|
||||
dc.click() # Click at current position
|
||||
|
||||
# 3. Right click
|
||||
dc.right_click(500, 300)
|
||||
|
||||
# 4. Double click
|
||||
dc.double_click(500, 300)
|
||||
|
||||
# 5. Drag & drop
|
||||
dc.drag(100, 100, 500, 500, duration=1.0)
|
||||
|
||||
# 6. Scroll
|
||||
dc.scroll(-5) # Scroll down 5 clicks
|
||||
|
||||
# 7. Get position
|
||||
x, y = dc.get_mouse_position()
|
||||
|
||||
# 8. Move relative
|
||||
dc.move_relative(100, 50) # Move 100px right, 50px down
|
||||
|
||||
# 9. Smooth movement
|
||||
dc.move_mouse(1000, 500, duration=1.0, smooth=True)
|
||||
|
||||
# 10. Middle click
|
||||
dc.middle_click()
|
||||
```
|
||||
|
||||
## ⌨️ Keyboard Control (Top 10)
|
||||
|
||||
```python
|
||||
# 1. Type text (instant)
|
||||
dc.type_text("Hello World")
|
||||
|
||||
# 2. Type text (human-like, 60 WPM)
|
||||
dc.type_text("Hello World", wpm=60)
|
||||
|
||||
# 3. Press key
|
||||
dc.press('enter')
|
||||
dc.press('tab')
|
||||
dc.press('escape')
|
||||
|
||||
# 4. Hotkeys (shortcuts)
|
||||
dc.hotkey('ctrl', 'c') # Copy
|
||||
dc.hotkey('ctrl', 'v') # Paste
|
||||
dc.hotkey('ctrl', 's') # Save
|
||||
dc.hotkey('win', 'r') # Run dialog
|
||||
dc.hotkey('alt', 'tab') # Switch window
|
||||
|
||||
# 5. Hold & release
|
||||
dc.key_down('shift')
|
||||
dc.type_text("hello") # Types "HELLO"
|
||||
dc.key_up('shift')
|
||||
|
||||
# 6. Arrow keys
|
||||
dc.press('up')
|
||||
dc.press('down')
|
||||
dc.press('left')
|
||||
dc.press('right')
|
||||
|
||||
# 7. Function keys
|
||||
dc.press('f5') # Refresh
|
||||
|
||||
# 8. Multiple presses
|
||||
dc.press('backspace', presses=5)
|
||||
|
||||
# 9. Special keys
|
||||
dc.press('home')
|
||||
dc.press('end')
|
||||
dc.press('pagedown')
|
||||
dc.press('delete')
|
||||
|
||||
# 10. Fast combo
|
||||
dc.hotkey('ctrl', 'alt', 'delete')
|
||||
```
|
||||
|
||||
## 📸 Screen Operations (Top 5)
|
||||
|
||||
```python
|
||||
# 1. Screenshot (full screen)
|
||||
img = dc.screenshot()
|
||||
dc.screenshot(filename="screen.png")
|
||||
|
||||
# 2. Screenshot (region)
|
||||
img = dc.screenshot(region=(100, 100, 800, 600))
|
||||
|
||||
# 3. Get pixel color
|
||||
r, g, b = dc.get_pixel_color(500, 300)
|
||||
|
||||
# 4. Find image on screen
|
||||
location = dc.find_on_screen("button.png")
|
||||
|
||||
# 5. Get screen size
|
||||
width, height = dc.get_screen_size()
|
||||
```
|
||||
|
||||
## 🪟 Window Management (Top 5)
|
||||
|
||||
```python
|
||||
# 1. Get all windows
|
||||
windows = dc.get_all_windows()
|
||||
|
||||
# 2. Activate window
|
||||
dc.activate_window("Chrome")
|
||||
|
||||
# 3. Get active window
|
||||
active = dc.get_active_window()
|
||||
|
||||
# 4. List windows
|
||||
for title in dc.get_all_windows():
|
||||
print(title)
|
||||
|
||||
# 5. Switch to app
|
||||
dc.activate_window("Visual Studio Code")
|
||||
```
|
||||
|
||||
## 📋 Clipboard (Top 2)
|
||||
|
||||
```python
|
||||
# 1. Copy to clipboard
|
||||
dc.copy_to_clipboard("Hello!")
|
||||
|
||||
# 2. Get from clipboard
|
||||
text = dc.get_from_clipboard()
|
||||
```
|
||||
|
||||
## 🔥 Real-World Examples
|
||||
|
||||
### Example 1: Auto-fill Form
|
||||
```python
|
||||
dc.click(300, 200) # Name field
|
||||
dc.type_text("John Doe", wpm=80)
|
||||
dc.press('tab')
|
||||
dc.type_text("john@email.com", wpm=80)
|
||||
dc.press('tab')
|
||||
dc.type_text("Password123", wpm=60)
|
||||
dc.press('enter')
|
||||
```
|
||||
|
||||
### Example 2: Copy-Paste Automation
|
||||
```python
|
||||
# Select all
|
||||
dc.hotkey('ctrl', 'a')
|
||||
# Copy
|
||||
dc.hotkey('ctrl', 'c')
|
||||
# Wait
|
||||
dc.pause(0.5)
|
||||
# Switch window
|
||||
dc.hotkey('alt', 'tab')
|
||||
# Paste
|
||||
dc.hotkey('ctrl', 'v')
|
||||
```
|
||||
|
||||
### Example 3: File Operations
|
||||
```python
|
||||
# Select multiple files
|
||||
dc.key_down('ctrl')
|
||||
dc.click(100, 200)
|
||||
dc.click(100, 250)
|
||||
dc.click(100, 300)
|
||||
dc.key_up('ctrl')
|
||||
# Copy
|
||||
dc.hotkey('ctrl', 'c')
|
||||
```
|
||||
|
||||
### Example 4: Screenshot Workflow
|
||||
```python
|
||||
# Take screenshot
|
||||
dc.screenshot(filename=f"capture_{time.time()}.png")
|
||||
# Open in Paint
|
||||
dc.hotkey('win', 'r')
|
||||
dc.pause(0.5)
|
||||
dc.type_text('mspaint')
|
||||
dc.press('enter')
|
||||
```
|
||||
|
||||
### Example 5: Search & Replace
|
||||
```python
|
||||
# Open Find & Replace
|
||||
dc.hotkey('ctrl', 'h')
|
||||
dc.pause(0.3)
|
||||
# Type find text
|
||||
dc.type_text("old_text")
|
||||
dc.press('tab')
|
||||
# Type replace text
|
||||
dc.type_text("new_text")
|
||||
# Replace all
|
||||
dc.hotkey('alt', 'a')
|
||||
```
|
||||
|
||||
## ⚙️ Configuration
|
||||
|
||||
```python
|
||||
# With failsafe (move to corner to abort)
|
||||
dc = DesktopController(failsafe=True)
|
||||
|
||||
# With approval mode (ask before each action)
|
||||
dc = DesktopController(require_approval=True)
|
||||
|
||||
# Maximum speed (no safety checks)
|
||||
dc = DesktopController(failsafe=False)
|
||||
```
|
||||
|
||||
## 🛡️ Safety
|
||||
|
||||
```python
|
||||
# Check if safe to continue
|
||||
if dc.is_safe():
|
||||
dc.click(500, 500)
|
||||
|
||||
# Pause execution
|
||||
dc.pause(2.0) # Wait 2 seconds
|
||||
|
||||
# Emergency abort: Move mouse to any screen corner
|
||||
```
|
||||
|
||||
## 🎯 Pro Tips
|
||||
|
||||
1. **Instant typing**: `interval=0` or `wpm=None`
|
||||
2. **Human typing**: `wpm=60` (60 words/min)
|
||||
3. **Smooth mouse**: `duration=0.5, smooth=True`
|
||||
4. **Instant mouse**: `duration=0`
|
||||
5. **Wait for UI**: `dc.pause(0.5)` between actions
|
||||
6. **Failsafe**: Always enable for safety
|
||||
7. **Test first**: Use `demo.py` to test features
|
||||
8. **Coordinates**: Use `get_mouse_position()` to find them
|
||||
9. **Screenshots**: Capture before/after for verification
|
||||
10. **Hotkeys > Menus**: Faster and more reliable
|
||||
|
||||
## 📦 Dependencies
|
||||
|
||||
```bash
|
||||
pip install pyautogui pillow opencv-python pygetwindow pyperclip
|
||||
```
|
||||
|
||||
## 🚨 Common Issues
|
||||
|
||||
**Mouse not moving correctly?**
|
||||
- Check DPI scaling in Windows settings
|
||||
- Verify coordinates with `get_mouse_position()`
|
||||
|
||||
**Keyboard not working?**
|
||||
- Ensure target app has focus
|
||||
- Some apps block automation (games, secure apps)
|
||||
|
||||
**Failsafe triggering?**
|
||||
- Keep mouse away from screen corners
|
||||
- Disable if needed: `failsafe=False`
|
||||
|
||||
---
|
||||
|
||||
**Built for OpenClaw** 🦞 - Desktop automation made easy!
|
||||
@@ -0,0 +1,650 @@
|
||||
---
|
||||
description: Advanced desktop automation with mouse, keyboard, and screen control
|
||||
---
|
||||
|
||||
# Desktop Control Skill
|
||||
|
||||
**The most advanced desktop automation skill for OpenClaw.** Provides pixel-perfect mouse control, lightning-fast keyboard input, screen capture, window management, and clipboard operations.
|
||||
|
||||
## 🎯 Features
|
||||
|
||||
### Mouse Control
|
||||
- ✅ **Absolute positioning** - Move to exact coordinates
|
||||
- ✅ **Relative movement** - Move from current position
|
||||
- ✅ **Smooth movement** - Natural, human-like mouse paths
|
||||
- ✅ **Click types** - Left, right, middle, double, triple clicks
|
||||
- ✅ **Drag & drop** - Drag from point A to point B
|
||||
- ✅ **Scroll** - Vertical and horizontal scrolling
|
||||
- ✅ **Position tracking** - Get current mouse coordinates
|
||||
|
||||
### Keyboard Control
|
||||
- ✅ **Text typing** - Fast, accurate text input
|
||||
- ✅ **Hotkeys** - Execute keyboard shortcuts (Ctrl+C, Win+R, etc.)
|
||||
- ✅ **Special keys** - Enter, Tab, Escape, Arrow keys, F-keys
|
||||
- ✅ **Key combinations** - Multi-key press combinations
|
||||
- ✅ **Hold & release** - Manual key state control
|
||||
- ✅ **Typing speed** - Configurable WPM (instant to human-like)
|
||||
|
||||
### Screen Operations
|
||||
- ✅ **Screenshot** - Capture entire screen or regions
|
||||
- ✅ **Image recognition** - Find elements on screen (via OpenCV)
|
||||
- ✅ **Color detection** - Get pixel colors at coordinates
|
||||
- ✅ **Multi-monitor** - Support for multiple displays
|
||||
|
||||
### Window Management
|
||||
- ✅ **Window list** - Get all open windows
|
||||
- ✅ **Activate window** - Bring window to front
|
||||
- ✅ **Window info** - Get position, size, title
|
||||
- ✅ **Minimize/Maximize** - Control window states
|
||||
|
||||
### Safety Features
|
||||
- ✅ **Failsafe** - Move mouse to corner to abort
|
||||
- ✅ **Pause control** - Emergency stop mechanism
|
||||
- ✅ **Approval mode** - Require confirmation for actions
|
||||
- ✅ **Bounds checking** - Prevent out-of-screen operations
|
||||
- ✅ **Logging** - Track all automation actions
|
||||
|
||||
---
|
||||
|
||||
## 🚀 Quick Start
|
||||
|
||||
### Installation
|
||||
|
||||
First, install required dependencies:
|
||||
|
||||
```bash
|
||||
pip install pyautogui pillow opencv-python pygetwindow
|
||||
```
|
||||
|
||||
### Basic Usage
|
||||
|
||||
```python
|
||||
from skills.desktop_control import DesktopController
|
||||
|
||||
# Initialize controller
|
||||
dc = DesktopController(failsafe=True)
|
||||
|
||||
# Mouse operations
|
||||
dc.move_mouse(500, 300) # Move to coordinates
|
||||
dc.click() # Left click at current position
|
||||
dc.click(100, 200, button="right") # Right click at position
|
||||
|
||||
# Keyboard operations
|
||||
dc.type_text("Hello from OpenClaw!")
|
||||
dc.hotkey("ctrl", "c") # Copy
|
||||
dc.press("enter")
|
||||
|
||||
# Screen operations
|
||||
screenshot = dc.screenshot()
|
||||
position = dc.get_mouse_position()
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 📋 Complete API Reference
|
||||
|
||||
### Mouse Functions
|
||||
|
||||
#### `move_mouse(x, y, duration=0, smooth=True)`
|
||||
Move mouse to absolute screen coordinates.
|
||||
|
||||
**Parameters:**
|
||||
- `x` (int): X coordinate (pixels from left)
|
||||
- `y` (int): Y coordinate (pixels from top)
|
||||
- `duration` (float): Movement time in seconds (0 = instant, 0.5 = smooth)
|
||||
- `smooth` (bool): Use bezier curve for natural movement
|
||||
|
||||
**Example:**
|
||||
```python
|
||||
# Instant movement
|
||||
dc.move_mouse(1000, 500)
|
||||
|
||||
# Smooth 1-second movement
|
||||
dc.move_mouse(1000, 500, duration=1.0)
|
||||
```
|
||||
|
||||
#### `move_relative(x_offset, y_offset, duration=0)`
|
||||
Move mouse relative to current position.
|
||||
|
||||
**Parameters:**
|
||||
- `x_offset` (int): Pixels to move horizontally (positive = right)
|
||||
- `y_offset` (int): Pixels to move vertically (positive = down)
|
||||
- `duration` (float): Movement time in seconds
|
||||
|
||||
**Example:**
|
||||
```python
|
||||
# Move 100px right, 50px down
|
||||
dc.move_relative(100, 50, duration=0.3)
|
||||
```
|
||||
|
||||
#### `click(x=None, y=None, button='left', clicks=1, interval=0.1)`
|
||||
Perform mouse click.
|
||||
|
||||
**Parameters:**
|
||||
- `x, y` (int, optional): Coordinates to click (None = current position)
|
||||
- `button` (str): 'left', 'right', 'middle'
|
||||
- `clicks` (int): Number of clicks (1 = single, 2 = double)
|
||||
- `interval` (float): Delay between multiple clicks
|
||||
|
||||
**Example:**
|
||||
```python
|
||||
# Simple left click
|
||||
dc.click()
|
||||
|
||||
# Double-click at specific position
|
||||
dc.click(500, 300, clicks=2)
|
||||
|
||||
# Right-click
|
||||
dc.click(button='right')
|
||||
```
|
||||
|
||||
#### `drag(start_x, start_y, end_x, end_y, duration=0.5, button='left')`
|
||||
Drag and drop operation.
|
||||
|
||||
**Parameters:**
|
||||
- `start_x, start_y` (int): Starting coordinates
|
||||
- `end_x, end_y` (int): Ending coordinates
|
||||
- `duration` (float): Drag duration
|
||||
- `button` (str): Mouse button to use
|
||||
|
||||
**Example:**
|
||||
```python
|
||||
# Drag file from desktop to folder
|
||||
dc.drag(100, 100, 500, 500, duration=1.0)
|
||||
```
|
||||
|
||||
#### `scroll(clicks, direction='vertical', x=None, y=None)`
|
||||
Scroll mouse wheel.
|
||||
|
||||
**Parameters:**
|
||||
- `clicks` (int): Scroll amount (positive = up/left, negative = down/right)
|
||||
- `direction` (str): 'vertical' or 'horizontal'
|
||||
- `x, y` (int, optional): Position to scroll at
|
||||
|
||||
**Example:**
|
||||
```python
|
||||
# Scroll down 5 clicks
|
||||
dc.scroll(-5)
|
||||
|
||||
# Scroll up 10 clicks
|
||||
dc.scroll(10)
|
||||
|
||||
# Horizontal scroll
|
||||
dc.scroll(5, direction='horizontal')
|
||||
```
|
||||
|
||||
#### `get_mouse_position()`
|
||||
Get current mouse coordinates.
|
||||
|
||||
**Returns:** `(x, y)` tuple
|
||||
|
||||
**Example:**
|
||||
```python
|
||||
x, y = dc.get_mouse_position()
|
||||
print(f"Mouse is at: {x}, {y}")
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
### Keyboard Functions
|
||||
|
||||
#### `type_text(text, interval=0, wpm=None)`
|
||||
Type text with configurable speed.
|
||||
|
||||
**Parameters:**
|
||||
- `text` (str): Text to type
|
||||
- `interval` (float): Delay between keystrokes (0 = instant)
|
||||
- `wpm` (int, optional): Words per minute (overrides interval)
|
||||
|
||||
**Example:**
|
||||
```python
|
||||
# Instant typing
|
||||
dc.type_text("Hello World")
|
||||
|
||||
# Human-like typing at 60 WPM
|
||||
dc.type_text("Hello World", wpm=60)
|
||||
|
||||
# Slow typing with 0.1s between keys
|
||||
dc.type_text("Hello World", interval=0.1)
|
||||
```
|
||||
|
||||
#### `press(key, presses=1, interval=0.1)`
|
||||
Press and release a key.
|
||||
|
||||
**Parameters:**
|
||||
- `key` (str): Key name (see Key Names section)
|
||||
- `presses` (int): Number of times to press
|
||||
- `interval` (float): Delay between presses
|
||||
|
||||
**Example:**
|
||||
```python
|
||||
# Press Enter
|
||||
dc.press('enter')
|
||||
|
||||
# Press Space 3 times
|
||||
dc.press('space', presses=3)
|
||||
|
||||
# Press Down arrow
|
||||
dc.press('down')
|
||||
```
|
||||
|
||||
#### `hotkey(*keys, interval=0.05)`
|
||||
Execute keyboard shortcut.
|
||||
|
||||
**Parameters:**
|
||||
- `*keys` (str): Keys to press together
|
||||
- `interval` (float): Delay between key presses
|
||||
|
||||
**Example:**
|
||||
```python
|
||||
# Copy (Ctrl+C)
|
||||
dc.hotkey('ctrl', 'c')
|
||||
|
||||
# Paste (Ctrl+V)
|
||||
dc.hotkey('ctrl', 'v')
|
||||
|
||||
# Open Run dialog (Win+R)
|
||||
dc.hotkey('win', 'r')
|
||||
|
||||
# Save (Ctrl+S)
|
||||
dc.hotkey('ctrl', 's')
|
||||
|
||||
# Select All (Ctrl+A)
|
||||
dc.hotkey('ctrl', 'a')
|
||||
```
|
||||
|
||||
#### `key_down(key)` / `key_up(key)`
|
||||
Manually control key state.
|
||||
|
||||
**Example:**
|
||||
```python
|
||||
# Hold Shift
|
||||
dc.key_down('shift')
|
||||
dc.type_text("hello") # Types "HELLO"
|
||||
dc.key_up('shift')
|
||||
|
||||
# Hold Ctrl and click (for multi-select)
|
||||
dc.key_down('ctrl')
|
||||
dc.click(100, 100)
|
||||
dc.click(200, 100)
|
||||
dc.key_up('ctrl')
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
### Screen Functions
|
||||
|
||||
#### `screenshot(region=None, filename=None)`
|
||||
Capture screen or region.
|
||||
|
||||
**Parameters:**
|
||||
- `region` (tuple, optional): (left, top, width, height) for partial capture
|
||||
- `filename` (str, optional): Path to save image
|
||||
|
||||
**Returns:** PIL Image object
|
||||
|
||||
**Example:**
|
||||
```python
|
||||
# Full screen
|
||||
img = dc.screenshot()
|
||||
|
||||
# Save to file
|
||||
dc.screenshot(filename="screenshot.png")
|
||||
|
||||
# Capture specific region
|
||||
img = dc.screenshot(region=(100, 100, 500, 300))
|
||||
```
|
||||
|
||||
#### `get_pixel_color(x, y)`
|
||||
Get color of pixel at coordinates.
|
||||
|
||||
**Returns:** RGB tuple `(r, g, b)`
|
||||
|
||||
**Example:**
|
||||
```python
|
||||
r, g, b = dc.get_pixel_color(500, 300)
|
||||
print(f"Color at (500, 300): RGB({r}, {g}, {b})")
|
||||
```
|
||||
|
||||
#### `find_on_screen(image_path, confidence=0.8)`
|
||||
Find image on screen (requires OpenCV).
|
||||
|
||||
**Parameters:**
|
||||
- `image_path` (str): Path to template image
|
||||
- `confidence` (float): Match threshold (0-1)
|
||||
|
||||
**Returns:** `(x, y, width, height)` or None
|
||||
|
||||
**Example:**
|
||||
```python
|
||||
# Find button on screen
|
||||
location = dc.find_on_screen("button.png")
|
||||
if location:
|
||||
x, y, w, h = location
|
||||
# Click center of found image
|
||||
dc.click(x + w//2, y + h//2)
|
||||
```
|
||||
|
||||
#### `get_screen_size()`
|
||||
Get screen resolution.
|
||||
|
||||
**Returns:** `(width, height)` tuple
|
||||
|
||||
**Example:**
|
||||
```python
|
||||
width, height = dc.get_screen_size()
|
||||
print(f"Screen: {width}x{height}")
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
### Window Functions
|
||||
|
||||
#### `get_all_windows()`
|
||||
List all open windows.
|
||||
|
||||
**Returns:** List of window titles
|
||||
|
||||
**Example:**
|
||||
```python
|
||||
windows = dc.get_all_windows()
|
||||
for title in windows:
|
||||
print(f"Window: {title}")
|
||||
```
|
||||
|
||||
#### `activate_window(title_substring)`
|
||||
Bring window to front by title.
|
||||
|
||||
**Parameters:**
|
||||
- `title_substring` (str): Part of window title to match
|
||||
|
||||
**Example:**
|
||||
```python
|
||||
# Activate Chrome
|
||||
dc.activate_window("Chrome")
|
||||
|
||||
# Activate VS Code
|
||||
dc.activate_window("Visual Studio Code")
|
||||
```
|
||||
|
||||
#### `get_active_window()`
|
||||
Get currently focused window.
|
||||
|
||||
**Returns:** Window title (str)
|
||||
|
||||
**Example:**
|
||||
```python
|
||||
active = dc.get_active_window()
|
||||
print(f"Active window: {active}")
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
### Clipboard Functions
|
||||
|
||||
#### `copy_to_clipboard(text)`
|
||||
Copy text to clipboard.
|
||||
|
||||
**Example:**
|
||||
```python
|
||||
dc.copy_to_clipboard("Hello from OpenClaw!")
|
||||
```
|
||||
|
||||
#### `get_from_clipboard()`
|
||||
Get text from clipboard.
|
||||
|
||||
**Returns:** str
|
||||
|
||||
**Example:**
|
||||
```python
|
||||
text = dc.get_from_clipboard()
|
||||
print(f"Clipboard: {text}")
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## ⌨️ Key Names Reference
|
||||
|
||||
### Alphabet Keys
|
||||
`'a'` through `'z'`
|
||||
|
||||
### Number Keys
|
||||
`'0'` through `'9'`
|
||||
|
||||
### Function Keys
|
||||
`'f1'` through `'f24'`
|
||||
|
||||
### Special Keys
|
||||
- `'enter'` / `'return'`
|
||||
- `'esc'` / `'escape'`
|
||||
- `'space'` / `'spacebar'`
|
||||
- `'tab'`
|
||||
- `'backspace'`
|
||||
- `'delete'` / `'del'`
|
||||
- `'insert'`
|
||||
- `'home'`
|
||||
- `'end'`
|
||||
- `'pageup'` / `'pgup'`
|
||||
- `'pagedown'` / `'pgdn'`
|
||||
|
||||
### Arrow Keys
|
||||
- `'up'` / `'down'` / `'left'` / `'right'`
|
||||
|
||||
### Modifier Keys
|
||||
- `'ctrl'` / `'control'`
|
||||
- `'shift'`
|
||||
- `'alt'`
|
||||
- `'win'` / `'winleft'` / `'winright'`
|
||||
- `'cmd'` / `'command'` (Mac)
|
||||
|
||||
### Lock Keys
|
||||
- `'capslock'`
|
||||
- `'numlock'`
|
||||
- `'scrolllock'`
|
||||
|
||||
### Punctuation
|
||||
- `'.'` / `','` / `'?'` / `'!'` / `';'` / `':'`
|
||||
- `'['` / `']'` / `'{'` / `'}'`
|
||||
- `'('` / `')'`
|
||||
- `'+'` / `'-'` / `'*'` / `'/'` / `'='`
|
||||
|
||||
---
|
||||
|
||||
## 🛡️ Safety Features
|
||||
|
||||
### Failsafe Mode
|
||||
|
||||
Move mouse to **any corner** of the screen to abort all automation.
|
||||
|
||||
```python
|
||||
# Enable failsafe (enabled by default)
|
||||
dc = DesktopController(failsafe=True)
|
||||
```
|
||||
|
||||
### Pause Control
|
||||
|
||||
```python
|
||||
# Pause all automation for 2 seconds
|
||||
dc.pause(2.0)
|
||||
|
||||
# Check if automation is safe to proceed
|
||||
if dc.is_safe():
|
||||
dc.click(500, 500)
|
||||
```
|
||||
|
||||
### Approval Mode
|
||||
|
||||
Require user confirmation before actions:
|
||||
|
||||
```python
|
||||
dc = DesktopController(require_approval=True)
|
||||
|
||||
# This will ask for confirmation
|
||||
dc.click(500, 500) # Prompt: "Allow click at (500, 500)? [y/n]"
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 🎨 Advanced Examples
|
||||
|
||||
### Example 1: Automated Form Filling
|
||||
|
||||
```python
|
||||
dc = DesktopController()
|
||||
|
||||
# Click name field
|
||||
dc.click(300, 200)
|
||||
dc.type_text("John Doe", wpm=80)
|
||||
|
||||
# Tab to next field
|
||||
dc.press('tab')
|
||||
dc.type_text("john@example.com", wpm=80)
|
||||
|
||||
# Tab to password
|
||||
dc.press('tab')
|
||||
dc.type_text("SecurePassword123", wpm=60)
|
||||
|
||||
# Submit form
|
||||
dc.press('enter')
|
||||
```
|
||||
|
||||
### Example 2: Screenshot Region and Save
|
||||
|
||||
```python
|
||||
# Capture specific area
|
||||
region = (100, 100, 800, 600) # left, top, width, height
|
||||
img = dc.screenshot(region=region)
|
||||
|
||||
# Save with timestamp
|
||||
import datetime
|
||||
timestamp = datetime.datetime.now().strftime("%Y%m%d_%H%M%S")
|
||||
img.save(f"capture_{timestamp}.png")
|
||||
```
|
||||
|
||||
### Example 3: Multi-File Selection
|
||||
|
||||
```python
|
||||
# Hold Ctrl and click multiple files
|
||||
dc.key_down('ctrl')
|
||||
dc.click(100, 200) # First file
|
||||
dc.click(100, 250) # Second file
|
||||
dc.click(100, 300) # Third file
|
||||
dc.key_up('ctrl')
|
||||
|
||||
# Copy selected files
|
||||
dc.hotkey('ctrl', 'c')
|
||||
```
|
||||
|
||||
### Example 4: Window Automation
|
||||
|
||||
```python
|
||||
# Activate Calculator
|
||||
dc.activate_window("Calculator")
|
||||
time.sleep(0.5)
|
||||
|
||||
# Type calculation
|
||||
dc.type_text("5+3=", interval=0.2)
|
||||
time.sleep(0.5)
|
||||
|
||||
# Take screenshot of result
|
||||
dc.screenshot(filename="calculation_result.png")
|
||||
```
|
||||
|
||||
### Example 5: Drag & Drop File
|
||||
|
||||
```python
|
||||
# Drag file from source to destination
|
||||
dc.drag(
|
||||
start_x=200, start_y=300, # File location
|
||||
end_x=800, end_y=500, # Folder location
|
||||
duration=1.0 # Smooth 1-second drag
|
||||
)
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## ⚡ Performance Tips
|
||||
|
||||
1. **Use instant movements** for speed: `duration=0`
|
||||
2. **Batch operations** instead of individual calls
|
||||
3. **Cache screen positions** instead of recalculating
|
||||
4. **Disable failsafe** for maximum performance (use with caution)
|
||||
5. **Use hotkeys** instead of menu navigation
|
||||
|
||||
---
|
||||
|
||||
## ⚠️ Important Notes
|
||||
|
||||
- **Screen coordinates** start at (0, 0) in top-left corner
|
||||
- **Multi-monitor setups** may have negative coordinates for secondary displays
|
||||
- **Windows DPI scaling** may affect coordinate accuracy
|
||||
- **Failsafe corners** are: (0,0), (width-1, 0), (0, height-1), (width-1, height-1)
|
||||
- **Some applications** may block simulated input (games, secure apps)
|
||||
|
||||
---
|
||||
|
||||
## 🔧 Troubleshooting
|
||||
|
||||
### 🔒 锁屏检测与处理 (重要!)
|
||||
|
||||
**在使用真实桌面操作前，必须先检测锁屏状态:**
|
||||
|
||||
```python
|
||||
import subprocess
|
||||
|
||||
def is_screen_locked():
|
||||
"""检测屏幕是否锁屏"""
|
||||
result = subprocess.run(
|
||||
["loginctl", "show-session", "-p", "LockedHint", "14"],
|
||||
capture_output=True, text=True
|
||||
)
|
||||
return "yes" in result.stdout.lower()
|
||||
```
|
||||
|
||||
**检测流程:**
|
||||
1. 先截屏查看画面状态
|
||||
2. 如果显示锁屏界面 → 输入密码解锁
|
||||
3. 如果显示登录页面 → 输入账号密码
|
||||
4. 如果是正常桌面 → 可以开始操作
|
||||
|
||||
**重要提示:**
|
||||
- 长时间不操作会导致自动锁屏
|
||||
- 操作前先检查锁屏状态
|
||||
- Ubuntu 锁屏密码: a12345678
|
||||
|
||||
### Mouse not moving to correct position
|
||||
- Check DPI scaling settings
|
||||
- Verify screen resolution matches expectations
|
||||
- Use `get_screen_size()` to confirm dimensions
|
||||
|
||||
### Keyboard input not working
|
||||
- Ensure target application has focus
|
||||
- Some apps require admin privileges
|
||||
- Try increasing `interval` for reliability
|
||||
|
||||
### Failsafe triggering accidentally
|
||||
- Increase screen border tolerance
|
||||
- Move mouse away from corners during normal use
|
||||
- Disable if needed: `DesktopController(failsafe=False)`
|
||||
|
||||
### Permission errors
|
||||
- Run Python with administrator privileges for some operations
|
||||
- Some secure applications block automation
|
||||
|
||||
---
|
||||
|
||||
## 📦 Dependencies
|
||||
|
||||
- **PyAutoGUI** - Core automation engine
|
||||
- **Pillow** - Image processing
|
||||
- **OpenCV** (optional) - Image recognition
|
||||
- **PyGetWindow** - Window management
|
||||
|
||||
Install all:
|
||||
```bash
|
||||
pip install pyautogui pillow opencv-python pygetwindow
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
**Built for OpenClaw** - The ultimate desktop automation companion 🦞
|
||||
@@ -0,0 +1,11 @@
|
||||
{
|
||||
"owner": "matagul",
|
||||
"slug": "desktop-control",
|
||||
"displayName": "Desktop Control",
|
||||
"latest": {
|
||||
"version": "1.0.0",
|
||||
"publishedAt": 1770255200863,
|
||||
"commit": "https://github.com/clawdbot/skills/commit/66090236946d6a2ab565cf9d425ae7102f881b0a"
|
||||
},
|
||||
"history": []
|
||||
}
|
||||
@@ -0,0 +1,42 @@
|
||||
---
|
||||
name: firecrawl
|
||||
description: Web search and scraping via Firecrawl API. Use when you need to search the web, scrape websites (including JS-heavy pages), crawl entire sites, or extract structured data from web pages. Requires FIRECRAWL_API_KEY environment variable.
|
||||
---
|
||||
|
||||
# Firecrawl
|
||||
|
||||
Web search and scraping via Firecrawl API.
|
||||
|
||||
## Prerequisites
|
||||
|
||||
Set `FIRECRAWL_API_KEY` in your environment or `.env` file:
|
||||
```bash
|
||||
export FIRECRAWL_API_KEY=fc-xxxxxxxxxx
|
||||
```
|
||||
|
||||
## Quick Start
|
||||
|
||||
### Search the web
|
||||
```bash
|
||||
firecrawl_search "your search query" --limit 10
|
||||
```
|
||||
|
||||
### Scrape a single page
|
||||
```bash
|
||||
firecrawl_scrape "https://example.com"
|
||||
```
|
||||
|
||||
### Crawl an entire site
|
||||
```bash
|
||||
firecrawl_crawl "https://example.com" --max-pages 50
|
||||
```
|
||||
|
||||
## API Reference
|
||||
|
||||
See [references/api.md](references/api.md) for detailed API documentation and advanced options.
|
||||
|
||||
## Scripts
|
||||
|
||||
- `scripts/search.py` - Search the web with Firecrawl
|
||||
- `scripts/scrape.py` - Scrape a single URL
|
||||
- `scripts/crawl.py` - Crawl an entire website
|
||||
@@ -0,0 +1,11 @@
|
||||
{
|
||||
"owner": "ashwingupy",
|
||||
"slug": "firecrawl-search",
|
||||
"displayName": "Firecrawl Search",
|
||||
"latest": {
|
||||
"version": "1.0.0",
|
||||
"publishedAt": 1769544521483,
|
||||
"commit": "https://github.com/clawdbot/skills/commit/7c6e584a7b59012f3c4566b53f748a946d5a9a24"
|
||||
},
|
||||
"history": []
|
||||
}
|
||||
@@ -0,0 +1,85 @@
|
||||
# Firecrawl API Reference
|
||||
|
||||
## Environment
|
||||
|
||||
Set your API key:
|
||||
```bash
|
||||
export FIRECRAWL_API_KEY=fc-xxxxxxxxxx
|
||||
```
|
||||
|
||||
## API Endpoints
|
||||
|
||||
### Search
|
||||
```bash
|
||||
POST https://api.firecrawl.dev/v1/search
|
||||
```
|
||||
|
||||
Request body:
|
||||
```json
|
||||
{
|
||||
"query": "search terms",
|
||||
"limit": 10,
|
||||
"lang": "en",
|
||||
"country": "us"
|
||||
}
|
||||
```
|
||||
|
||||
### Scrape
|
||||
```bash
|
||||
POST https://api.firecrawl.dev/v1/scrape
|
||||
```
|
||||
|
||||
Request body:
|
||||
```json
|
||||
{
|
||||
"url": "https://example.com",
|
||||
"formats": ["markdown", "html", "screenshot"],
|
||||
"onlyMainContent": true,
|
||||
"includeTags": ["h1", "p", "article"],
|
||||
"excludeTags": ["nav", "footer", "aside"]
|
||||
}
|
||||
```
|
||||
|
||||
### Crawl
|
||||
```bash
|
||||
POST https://api.firecrawl.dev/v1/crawl
|
||||
```
|
||||
|
||||
Request body:
|
||||
```json
|
||||
{
|
||||
"url": "https://example.com",
|
||||
"limit": 50,
|
||||
"excludePaths": ["/blog", "/admin"],
|
||||
"scrapeOptions": {
|
||||
"formats": ["markdown"],
|
||||
"onlyMainContent": true
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
Check status:
|
||||
```bash
|
||||
GET https://api.firecrawl.dev/v1/crawl/{job_id}
|
||||
```
|
||||
|
||||
## Response Format
|
||||
|
||||
All responses follow this structure:
|
||||
```json
|
||||
{
|
||||
"success": true,
|
||||
"data": { ... },
|
||||
"status": "completed"
|
||||
}
|
||||
```
|
||||
|
||||
## Rate Limits
|
||||
|
||||
- Search: Check your Firecrawl dashboard
|
||||
- Scrape: Check your Firecrawl dashboard
|
||||
- Crawl: Check your Firecrawl dashboard
|
||||
|
||||
## Pricing
|
||||
|
||||
See https://firecrawl.dev/pricing for current rates.
|
||||
@@ -0,0 +1,7 @@
|
||||
{
|
||||
"version": 1,
|
||||
"registry": "https://clawhub.ai",
|
||||
"slug": "skill-self-evolution-enhancer",
|
||||
"installedVersion": "1.0.0",
|
||||
"installedAt": 1773868802966
|
||||
}
|
||||
@@ -0,0 +1,213 @@
|
||||
# Errors
|
||||
|
||||
Error logs and failure patterns for **skill-self-evolution-enhancer**.
|
||||
|
||||
**Categories**: timeout | context_overhead | missing_data | workflow_error
|
||||
**Statuses**: pending | in_progress | resolved | wont_fix | promoted
|
||||
|
||||
## Status Definitions
|
||||
|
||||
| Status | Meaning |
|
||||
|--------|---------|
|
||||
| `pending` | Not yet addressed |
|
||||
| `in_progress` | Actively being worked on |
|
||||
| `resolved` | Issue fixed or workaround found |
|
||||
| `wont_fix` | Decided not to address |
|
||||
| `promoted` | Elevated to evolution rules |
|
||||
|
||||
## Error Entry Format
|
||||
|
||||
```markdown
|
||||
## [ERR-YYYYMMDD-XXX] category
|
||||
|
||||
**Logged**: ISO-8601 timestamp
|
||||
**Priority**: low | medium | high | critical
|
||||
**Status**: pending
|
||||
**Area**: 领域
|
||||
|
||||
### Summary
|
||||
One-line description
|
||||
|
||||
### Details
|
||||
Full context
|
||||
|
||||
### Root Cause
|
||||
Likely cause if known
|
||||
|
||||
### Workaround
|
||||
What was tried or could be tried
|
||||
|
||||
### Metadata
|
||||
- Source: error_log | user_report | test
|
||||
- Tags: tag1, tag2
|
||||
- Recurrence-Count: 1
|
||||
|
||||
---
|
||||
```
|
||||
|
||||
## [ERR-20260326-001] cron_timeout_context_overhead
|
||||
|
||||
**Logged**: 2026-03-26T04:14:00Z
|
||||
**Priority**: high
|
||||
**Status**: resolved
|
||||
**Area**: cron任务调度
|
||||
|
||||
### Summary
|
||||
cron agentTurn timeout设置120s但实际超时，原因是session上下文大(205k)导致agent处理慢
|
||||
|
||||
### Details
|
||||
- 脚本 `evolution-report.sh` 本身执行仅需 4秒
|
||||
- 但 cron agentTurn 报告超时 120028ms（连续3次）
|
||||
- session 状态显示: `unknown/205k (?%)` 说明上下文很大
|
||||
- 日志分析显示脚本实际在 4s 内完成
|
||||
|
||||
### Root Cause
|
||||
timeoutSeconds 设置的是 cron job 的硬性超时，但 OpenClaw agent 处理大上下文时初始化+推理本身就耗时很长，与实际脚本执行时间无关
|
||||
|
||||
### Workaround
|
||||
将 `timeoutSeconds` 从 120 降到 60（脚本只需4s，60s足够让agent初始化完成）
|
||||
已对 `dbd84977`（GitHub进化猎手）和 `b0afa4db`（日志清理）应用修复
|
||||
|
||||
### Metadata
|
||||
- Source: heartbeat_analysis
|
||||
- Tags: cron, timeout, context-size, self-healing
|
||||
- Recurrence-Count: 3
|
||||
- See Also: HEARTBEAT.md
|
||||
|
||||
---
|
||||
|
||||
## [ERR-20260326-002] resource_guard_cpu_parsing_bug
|
||||
|
||||
**Logged**: 2026-03-26T09:25:00Z
|
||||
**Priority**: high
|
||||
**Status**: resolved
|
||||
**Area**: 资源监控
|
||||
|
||||
### Summary
|
||||
资源守卫脚本CPU解析bug：int($2)对"4.5"返回0，显示95%而非5%
|
||||
|
||||
### Details
|
||||
- `top -bn1 | grep "Cpu(s)"` 输出: `4.5 us, 0.0 sy, 0.0 ni, 95.5 id`
|
||||
- 脚本用 `awk '{print int($2)}'` 取字段2，得到 `4.5`，但 `int("4.5")` 在awk中返回 0
|
||||
- 导致 CPU 显示为 idle 字段值（95%），实际是空闲95%，使用仅5%
|
||||
|
||||
### Root Cause
|
||||
awk int()函数对含小数点的字符串处理有误，且脚本逻辑不对：应该用 idle 计算使用率，而非直接取us字段
|
||||
|
||||
### Workaround
|
||||
修改为 `cpu_usage=$(top -bn1 | grep "Cpu(s)" | awk '{print int($8)}')` 然后 `cpu_usage=$((100 - cpu_usage))`
|
||||
|
||||
### Metadata
|
||||
- Source: heartbeat_false_alarm
|
||||
- Tags: monitoring, awk, parsing
|
||||
- Recurrence-Count: 1
|
||||
- File: /home/yh6788/.openclaw/scripts/resource-guard.sh
|
||||
|
||||
---
|
||||
|
||||
## [ERR-20260326-002] camoufox_browse_headless_crash
|
||||
|
||||
**Logged**: 2026-03-26T14:01:00Z
|
||||
**Priority**: high
|
||||
**Status**: resolved
|
||||
**Area**: 浏览器自动化
|
||||
|
||||
### Summary
|
||||
camoufox browse.py 硬编码 headless=False，在服务器上会卡住等待用户输入
|
||||
|
||||
### Details
|
||||
- 原脚本最后有 input("Press Enter to close...")，headless模式下无法交互
|
||||
- 原脚本没有 headless 参数选项
|
||||
- camoufox 安装在 ~/.local/lib/python3.13/site-packages/，不在 venv 里
|
||||
|
||||
### Root Cause
|
||||
脚本设计假设在有GUI环境运行，未考虑服务器无头模式
|
||||
|
||||
### Workaround
|
||||
修复后的 browse.py:
|
||||
1. 添加 --headless 参数
|
||||
2. 无DISPLAY时自动启用headless
|
||||
3. headless模式下跳过等待用户输入
|
||||
4. 添加 USER_SITE 路径到 sys.path
|
||||
|
||||
### Metadata
|
||||
- Source: self_discovery
|
||||
- Tags: camoufox, headless, server
|
||||
- Recurrence-Count: 1
|
||||
- See Also: camoufox/scripts/browse.py
|
||||
|
||||
---
|
||||
|
||||
## [ERR-20260327-001] log_cleaner_timeout
|
||||
|
||||
**Logged**: 2026-03-27T18:35:00Z
|
||||
**Priority**: high
|
||||
**Status**: resolved
|
||||
**Area**: cron任务调度
|
||||
|
||||
### Summary
|
||||
日志清理脚本本身只需1.3秒，但cron timeout 60秒仍超时
|
||||
|
||||
### Root Cause
|
||||
同GitHub进化猎手问题：agent初始化（含session加载、context初始化）耗时远超脚本执行时间
|
||||
|
||||
### Workaround
|
||||
将timeout从60s降到30s，脚本仅需1.3s，30s足够agent初始化完成
|
||||
|
||||
### Metadata
|
||||
- Source: heartbeat_check
|
||||
- Tags: cron, timeout, agent-initialization
|
||||
- Recurrence-Count: 2
|
||||
- See Also: ERR-20260326-001
|
||||
|
||||
---
|
||||
|
||||
## [ERR-20260327-001] cron_timeout_agent_context_overhead_v2
|
||||
|
||||
**Logged**: 2026-03-27T03:05:00Z
|
||||
**Priority**: high
|
||||
**Status**: resolved
|
||||
**Area**: cron任务调度
|
||||
|
||||
### Summary
|
||||
降低cron timeout反而导致更多超时：agent加载205k上下文需要60-120s
|
||||
|
||||
### Details
|
||||
- 脚本本身执行只需 1.2 秒
|
||||
- 但 agent 加载 205k 上下文需要 60-120s
|
||||
- 60s timeout: 持续超时
|
||||
- 180s timeout: 足够agent初始化完成
|
||||
|
||||
### Root Cause
|
||||
OpenClaw agentTurn timeout 指的是 agent 整个执行周期，不是脚本执行时间。agent 需要时间初始化大上下文 session。
|
||||
|
||||
### Workaround
|
||||
对于简单脚本任务，timeout 应设置为 120-300s，保证 agent 有足够时间初始化后再执行脚本
|
||||
|
||||
### Metadata
|
||||
- Source: heartbeat_analysis
|
||||
- Tags: cron, timeout, context-size, agent-overhead
|
||||
- Recurrence-Count: 2
|
||||
- See Also: ERR-20260326-001
|
||||
|
||||
---
|
||||
|
||||
## 2026-03-27 日志清理超时问题
|
||||
|
||||
**问题**: log-cleaner.sh 连续2次 timeout（cron 设置 60s）
|
||||
**根因**: 逐文件循环 `stat` + 条件判断，大目录极慢
|
||||
**解决方案**: 改用 `find -mtime +N -print -delete` 批量操作，timeout 提升至 120s
|
||||
**进化**: 脚本已优化，cron 已更新
|
||||
|
||||
## 日志清理脚本超时问题 (2026-03-27)
|
||||
|
||||
**问题**: 日志清理cron任务连续2次超时（timeout）
|
||||
|
||||
**根因**: 脚本扫描目录包含node_modules等大目录，导致1.5GB数据遍历超时
|
||||
|
||||
**解决方案**:
|
||||
- 排除目录：node_modules、.cache、.npm、.pnpm-store、.git
|
||||
- 聚焦日志目录：workspace/sleep-learning、logs、token-monitor/logs
|
||||
- 不再扫描整个workspace和openclaw根目录
|
||||
|
||||
**验证**: 修复后执行耗时0秒，正常完成
|
||||
@@ -0,0 +1,163 @@
|
||||
# Learnings
|
||||
|
||||
Corrections, insights, and best practices for **skill-self-evolution-enhancer**.
|
||||
|
||||
**Categories**: correction | insight | knowledge_gap | best_practice
|
||||
**Statuses**: pending | in_progress | resolved | wont_fix | promoted
|
||||
|
||||
## [LRN-20260326-001] insight
|
||||
|
||||
**Logged**: 2026-03-26T04:14:00Z
|
||||
**Priority**: high
|
||||
**Status**: resolved
|
||||
**Area**: 自进化冷启动
|
||||
|
||||
### Summary
|
||||
learnings文件初始为空时，需要从heartbeat/cron日志/执行输出中主动提取进化素材
|
||||
|
||||
### Details
|
||||
skill自进化需要真实错误数据驱动，但冷启动时.learnings/是空白模板
|
||||
解决方案：从系统日志(cron状态、资源使用)、执行输出(stderr/stdout)、用户反馈中主动提取
|
||||
|
||||
### Suggested Action
|
||||
在HEARTBEAT.md中增加"每次心跳检查时提取一条可进化的错误/改进项"规则
|
||||
|
||||
### Metadata
|
||||
- Source: heartbeat_automation_session
|
||||
- Tags: cold-start, self-evolution, data-driven
|
||||
- Recurrence-Count: 1
|
||||
|
||||
---
|
||||
|
||||
## [LRN-20260327-001] insight
|
||||
|
||||
**Logged**: 2026-03-27T08:04:00Z
|
||||
**Priority**: medium
|
||||
**Status**: resolved
|
||||
**Area**: GitHub进化猎手-克隆超时
|
||||
|
||||
### Summary
|
||||
GitHub进化猎手在心跳/cron环境中克隆大型仓库容易超时，需要优化分析策略
|
||||
|
||||
### Details
|
||||
心跳/cron环境网络受限，克隆⭐49306的deer-flow和⭐20811的agentscope均超时失败
|
||||
解决方案：改用web_fetch读取README+API分析结构，不依赖git clone
|
||||
|
||||
### Suggested Action
|
||||
修改github-intel.sh，增加"克隆前先web_fetch README预览"逻辑，对⭐>20000项目改用API+README分析
|
||||
|
||||
### Metadata
|
||||
- Source: github-intel-cron-20260327
|
||||
- Tags: network-timeout, github-analysis, optimization
|
||||
- Recurrence-Count: 1
|
||||
|
||||
---
|
||||
|
||||
## [LRN-20260327-002] insight
|
||||
|
||||
**Logged**: 2026-03-27T08:04:00Z
|
||||
**Priority**: high
|
||||
**Status**: in_progress
|
||||
**Area**: 重大突破性项目发现
|
||||
|
||||
### Summary
|
||||
本期发现2个⭐>20000的突破性项目，需要深度研究
|
||||
|
||||
### Details
|
||||
发现两个突破性项目：
|
||||
1. **bytedance/deer-flow** (⭐49306) - SuperAgent框架，集成sandbox/memories/tools/skill/subagents/message gateway
|
||||
2. **agentscope-ai/agentscope** (⭐20811) - "Build and run agents you can see, understand and trust"
|
||||
|
||||
这两个项目代表了当前Agent架构的最新方向，值得深入研究代码结构
|
||||
|
||||
### Suggested Action
|
||||
下次有充足时间时，手动克隆这两个项目分析代码结构
|
||||
|
||||
### Metadata
|
||||
- Source: github-intel-cron-20260327
|
||||
- Tags: breakthrough-project, deer-flow, agentscope, agent-framework
|
||||
- Recurrence-Count: 1
|
||||
|
||||
---
|
||||
|
||||
## [LRN-20260327-004] best_practice
|
||||
|
||||
**Logged**: 2026-03-27T12:04:00Z
|
||||
**Priority**: high
|
||||
**Status**: resolved
|
||||
**Area**: GitHub进化猎手-本期深度分析
|
||||
|
||||
### Summary
|
||||
本期分析3个高价值项目：last30days-skill、superpowers、dexter
|
||||
|
||||
### Details
|
||||
从 **mvanhorn/last30days-skill** (⭐11702) 学到：
|
||||
1. **Open Claw原生适配**: 明确说明"Designed for Open Claw and similar always-on AI environments"，提供open variant
|
||||
2. **Watchlist + briefings模式**: SQLite持久化研究数据，支持自然语言查询历史，支持定时cron触发
|
||||
3. **多信号并行 + 质量排序**: 10个平台并行搜索，双向文本相似度 + 参与度速度归一化
|
||||
4. **Comparative Mode**: "X vs Y"模式并行3次研究 + 并排对比
|
||||
|
||||
从 **obra/superpowers** (⭐117412) 学到：
|
||||
1. **Subagent驱动开发**: dispatching-parallel-agents + 两阶段review (spec compliance → code quality)
|
||||
2. **Skills自动触发**: agent在执行任务前自动检查相关skills，无需手动调用
|
||||
3. **brainstorming skill**: Socratic设计澄清，在写代码前先确认真正需求
|
||||
4. **git-worktrees隔离**: 每个任务在独立branch的worktree执行，避免污染主分支
|
||||
5. **skills库生态**: 测试/调试/协作/元技能分类，writing-skills指导创建新skill
|
||||
|
||||
从 **virattt/dexter** (⭐19354) 学到：
|
||||
1. **自验证循环**: 执行任务后检查结果，迭代直到confidence足够
|
||||
2. **Scratchpad调试日志**: 每个query生成JSONL文件，记录tool调用和LLM推理过程
|
||||
3. **Task Planning自动分解**: 复杂query自动拆解为结构化研究步骤
|
||||
4. **Loop Detection**: 内置循环检测和step limits防止无限执行
|
||||
5. **WhatsApp Gateway**: 通过WhatsApp与agent交互
|
||||
|
||||
### Suggested Action
|
||||
1. 考虑为OpenClaw skills增加watchlist/briefings持久化模式
|
||||
2. 引入superpowers的"执行前先brainstorm"流程
|
||||
3. 学习dexter的scratchpad日志机制用于调试
|
||||
4. last30days-skill的"对比模式"可作为GitHub进化的分析模板
|
||||
|
||||
### Metadata
|
||||
- Source: github-intel-cron-20260327-deep-analysis-2
|
||||
- Tags: last30days-skill, superpowers, dexter, agent-framework
|
||||
- Recurrence-Count: 1
|
||||
|
||||
---
|
||||
|
||||
## [LRN-20260327-003] best_practice
|
||||
|
||||
**Logged**: 2026-03-27T08:29:00Z
|
||||
**Priority**: high
|
||||
**Status**: resolved
|
||||
**Area**: GitHub进化猎手-多源情报融合设计模式
|
||||
|
||||
### Summary
|
||||
oh-my-claudecode的团队协作模式揭示了multi-agent编排的最佳实践
|
||||
|
||||
### Details
|
||||
从oh-my-claudecode (⭐13148)学到：
|
||||
1. **Team Pipeline架构**: team-plan → team-prd → team-exec → team-verify → team-fix 循环
|
||||
2. **Deep Interview技能**: Socratic追问 + 数学模糊度门控 (ambiguity ≤ 20%才允许执行)
|
||||
3. **tmux CLI Workers**: 真实终端窗口作为worker，支持多agent并行
|
||||
4. **AGENTS.md规范**: 用guidance_schema_contract定义角色契约，operating_principles + delegation_rules
|
||||
|
||||
从last30days-skill (⭐11242)学到：
|
||||
1. **多信号质量排序**: 8个平台并行搜索，双向文本相似度 + 参与度速度归一化 + 跨平台收敛检测
|
||||
2. **Polymarket预测市场集成**: 用真钱 bets 作为信号源，比Reddit更可靠
|
||||
3. **Per-project .env配置**: 项目级环境变量隔离
|
||||
4. **自动归档**: 每次运行保存到 ~/Documents/ 构建个人研究库
|
||||
|
||||
从agentscope (⭐20827)学到：
|
||||
1. **"可观测的Agent"理念**: Build and run agents you can see, understand and trust
|
||||
2. **A2A协议支持**: Agent间标准通信协议
|
||||
3. **VNC-powered GUI沙箱**: 运行时可视化调试
|
||||
4. **OTel生产部署**: K8s + Docker内置支持
|
||||
|
||||
### Suggested Action
|
||||
将team pipeline分阶段架构引入OpenClaw skill编排；考虑增加"模糊度门控"机制在执行危险操作前要求用户确认
|
||||
|
||||
### Metadata
|
||||
- Source: github-intel-cron-20260327-deep-analysis
|
||||
- Tags: multi-agent, orchestration, team-pipeline, skill-design
|
||||
- Recurrence-Count: 1
|
||||
|
||||
@@ -0,0 +1,52 @@
|
||||
# Skill Self-Evolution Enhancer
|
||||
|
||||
A Cursor skill that enables **any skill** to gain self-evolution capabilities. Based on self-improving-agent, it equips skills with: logging, learning from user feedback, promotion of experience to rules, and a Review→Apply→Report loop—all tailored to the target skill's domain.
|
||||
|
||||
[中文](README.zh.md)
|
||||
|
||||
## Features
|
||||
|
||||
- **Domain analysis**: Deep analysis of target skill's capabilities, scenarios, and evolution directions
|
||||
- **Generate .learnings/**: Domain-specific LEARNINGS.md, ERRORS.md, FEATURE_REQUESTS.md
|
||||
- **Generate EVOLUTION.md**: Triggers, Review-Apply-Report workflow, OpenClaw feedback rules
|
||||
- **Multi-skill scaling**: Support multiple skills, each with its own evolution logic
|
||||
|
||||
## When to Use
|
||||
|
||||
- User says: "Add self-evolution to skill X"
|
||||
- Scaling self-improvement across many skills (each with its own evolution direction)
|
||||
- Target skill is non-coding (e.g., content rewriting, system optimization) and needs domain-specific triggers
|
||||
|
||||
## Quick Start
|
||||
|
||||
1. Enable this skill in Cursor
|
||||
2. Provide the target skill's path (e.g., `skills/xxx`, `~/.cursor/skills/xxx`)
|
||||
3. Follow the flow: Read target skill → Domain analysis → Generate .learnings/ and EVOLUTION.md
|
||||
|
||||
## Structure
|
||||
|
||||
```
|
||||
skill-self-evolution-enhancer/
|
||||
├── SKILL.md # Main skill doc
|
||||
├── assets/ # Templates
|
||||
│ ├── DOMAIN-CONFIG-TEMPLATE.md
|
||||
│ ├── EVOLUTION-RULES-TEMPLATE.md
|
||||
│ ├── LEARNINGS-TEMPLATE.md
|
||||
│ ├── ERRORS-TEMPLATE.md
|
||||
│ └── FEATURE_REQUESTS-TEMPLATE.md
|
||||
├── references/ # Examples
|
||||
│ ├── domain-examples.md
|
||||
│ └── openclaw-feedback.md
|
||||
└── scripts/
|
||||
└── generate-evolution.sh # Optional scaffold generator
|
||||
```
|
||||
|
||||
## References
|
||||
|
||||
- [SKILL.md](SKILL.md) — Full workflow and documentation
|
||||
- [references/domain-examples.md](references/domain-examples.md) — Domain examples (e.g., content rewriting, system optimization)
|
||||
|
||||
## Source
|
||||
|
||||
- Based on: self-improving-agent 3.0.1
|
||||
- Purpose: Enable any skill to gain self-evolution capabilities similar to self-improving-agent
|
||||
@@ -0,0 +1,52 @@
|
||||
# Skill Self-Evolution Enhancer
|
||||
|
||||
为任意 Cursor Skill 赋予自进化能力的增强技能。基于 self-improving-agent，让原本不具备自进化的技能获得：日志记录、从用户反馈学习、经验提升为规则、以及 Review→Apply→Report 循环——全部按目标技能的领域定制。
|
||||
|
||||
[English](README.md)
|
||||
|
||||
## 功能
|
||||
|
||||
- **领域分析**：深度分析目标技能的能力、场景与进化方向
|
||||
- **生成 .learnings/**：领域化的 LEARNINGS.md、ERRORS.md、FEATURE_REQUESTS.md
|
||||
- **生成 EVOLUTION.md**：触发条件、Review-Apply-Report 流程、OpenClaw 反馈规则
|
||||
- **多技能扩展**：支持为多个技能分别配置各自的进化逻辑
|
||||
|
||||
## 使用场景
|
||||
|
||||
- 用户说：「给 skill X 加上自进化能力」
|
||||
- 需要将自改进能力扩展到多个技能（每个技能有独立进化方向）
|
||||
- 目标技能为非编程类（如洗稿能手、电脑加速），需要领域特定的触发条件
|
||||
|
||||
## 快速开始
|
||||
|
||||
1. 在 Cursor 中启用本技能
|
||||
2. 提供目标技能的路径（如 `skills/xxx`、`~/.cursor/skills/xxx`）
|
||||
3. 按提示完成：读取目标技能 → 领域分析 → 生成 .learnings/ 与 EVOLUTION.md
|
||||
|
||||
## 目录结构
|
||||
|
||||
```
|
||||
skill-self-evolution-enhancer/
|
||||
├── SKILL.md # 技能主文档
|
||||
├── assets/ # 模板
|
||||
│ ├── DOMAIN-CONFIG-TEMPLATE.md
|
||||
│ ├── EVOLUTION-RULES-TEMPLATE.md
|
||||
│ ├── LEARNINGS-TEMPLATE.md
|
||||
│ ├── ERRORS-TEMPLATE.md
|
||||
│ └── FEATURE_REQUESTS-TEMPLATE.md
|
||||
├── references/ # 参考示例
|
||||
│ ├── domain-examples.md
|
||||
│ └── openclaw-feedback.md
|
||||
└── scripts/
|
||||
└── generate-evolution.sh # 可选脚手架生成脚本
|
||||
```
|
||||
|
||||
## 参考
|
||||
|
||||
- [SKILL.md](SKILL.md) — 完整工作流与说明
|
||||
- [references/domain-examples.md](references/domain-examples.md) — 洗稿能手、电脑加速等示例
|
||||
|
||||
## 来源
|
||||
|
||||
- 基于：self-improving-agent 3.0.1
|
||||
- 用途：让任意技能获得与 self-improving-agent 类似的自进化能力
|
||||
@@ -0,0 +1,202 @@
|
||||
---
|
||||
name: skill-self-evolution-enhancer
|
||||
description: "Enables any skill to gain self-evolution capabilities. Use when: (1) User asks to add self-evolution to a skill, (2) User wants a skill to learn from feedback and errors, (3) Scaling self-improvement to multiple skills with per-skill evolution logic. Outputs domain-specific .learnings/, EVOLUTION.md, and Review-Apply-Report workflow."
|
||||
metadata:
|
||||
---
|
||||
|
||||
# Skill Self-Evolution Enhancer
|
||||
|
||||
This skill enables **other skills** to gain self-evolution capabilities similar to self-improving-agent. A skill that originally has no self-evolution will, after enhancement, have: logging, learning from user feedback, promotion to rules, and a Review→Apply→Report loop—all tailored to its domain.
|
||||
|
||||
## Quick Reference
|
||||
|
||||
| Step | Action |
|
||||
|------|--------|
|
||||
| User requests evolution for skill X | Read target skill's SKILL.md |
|
||||
| Deep analysis | Identify capabilities, scenarios, evolution directions |
|
||||
| Extract domain | Name, use cases, triggers, areas, promotion targets |
|
||||
| Generate .learnings/ | Domain-specific LEARNINGS.md, ERRORS.md, FEATURE_REQUESTS.md |
|
||||
| Generate EVOLUTION.md | Triggers, Review-Apply-Report, OpenClaw feedback rules |
|
||||
| Language | Match target skill's user language (infer from SKILL.md) |
|
||||
|
||||
## When to Use
|
||||
|
||||
- User says: "给 skill X 加上自进化能力" / "Add self-evolution to skill X"
|
||||
- Scaling self-improvement across many skills (each with its own evolution direction)
|
||||
- Target skill is non-coding (e.g., 洗稿能手, 电脑加速) and needs domain-specific triggers
|
||||
|
||||
## Workflow
|
||||
|
||||
### Step 1: Read Target Skill
|
||||
|
||||
```
|
||||
Read(target_skill_path/SKILL.md)
|
||||
```
|
||||
|
||||
Obtain path from user or infer (e.g., `skills/xxx`, `~/.cursor/skills/xxx`).
|
||||
|
||||
### Step 2: Deep Capability & Scenario Analysis
|
||||
|
||||
**Before generating** any config, analyze the target skill deeply:
|
||||
|
||||
**Capabilities** (what the skill does):
|
||||
- Primary outputs and workflows
|
||||
- Secondary or edge capabilities
|
||||
- Dependencies (tools, APIs, formats)
|
||||
|
||||
**Scenarios** (when and how it is used):
|
||||
- User personas
|
||||
- Typical tasks (e.g., 科普改写 vs 汇报改写)
|
||||
- Input/output patterns
|
||||
|
||||
**Evolution directions** (what can improve):
|
||||
- User feedback patterns (e.g., "改得不通顺" → style)
|
||||
- Failure modes (e.g., "优化无效" → strategy)
|
||||
- Recurring corrections → domain-specific rules
|
||||
|
||||
**Use cases** → infer from description, Quick Reference, examples
|
||||
|
||||
### Step 3: Extract Domain Config
|
||||
|
||||
When reading the target skill, extract:
|
||||
|
||||
| Field | Where to Find | Example |
|
||||
|-------|---------------|---------|
|
||||
| **Domain name** | `name` in frontmatter, title | 洗稿能手, 电脑加速 |
|
||||
| **Use cases / scenarios** | Description, Quick Reference, examples | 科普、汇报、直播 |
|
||||
| **Learning triggers** | User feedback phrases in examples | "改得不通顺", "不像口播", "风格不对" |
|
||||
| **Error triggers** | Failure modes | "优化无效", "某些电脑不适用", "报错" |
|
||||
| **Areas** | Output types, workflow stages | 文案/口播/短视频脚本, 或 系统优化/卡顿/报错 |
|
||||
| **Promotion targets** | Skill-specific rules | `{skill}-专属进化规则.md`, `{skill}-最佳实践.md` |
|
||||
|
||||
**Language**: Infer from SKILL.md content (Chinese vs English). Generate all output files in that language.
|
||||
|
||||
Use [assets/DOMAIN-CONFIG-TEMPLATE.md](assets/DOMAIN-CONFIG-TEMPLATE.md) to structure the extracted data.
|
||||
|
||||
### Step 4: Generate .learnings/
|
||||
|
||||
Create inside target skill directory: `target_skill_path/.learnings/`
|
||||
|
||||
**Structure** (same as self-improving-agent):
|
||||
- `.learnings/LEARNINGS.md`
|
||||
- `.learnings/ERRORS.md`
|
||||
- `.learnings/FEATURE_REQUESTS.md`
|
||||
|
||||
Use templates from `assets/`; parameterize with domain areas, categories, promotion targets. Write in the target skill's language.
|
||||
|
||||
### Step 5: Generate EVOLUTION.md
|
||||
|
||||
Create `target_skill_path/EVOLUTION.md` using [assets/EVOLUTION-RULES-TEMPLATE.md](assets/EVOLUTION-RULES-TEMPLATE.md).
|
||||
|
||||
**Must include**:
|
||||
- Quick Reference: domain triggers → actions
|
||||
- **Review→Apply→Report** loop (see below)
|
||||
- Detection triggers (when to log)
|
||||
- Promotion decision tree
|
||||
- Area tags
|
||||
- Domain-specific activation conditions (for hooks)
|
||||
- Experience invalidation / update rules (when user corrects again)
|
||||
|
||||
### Step 6: Optional – Activator Script
|
||||
|
||||
If target skill has `scripts/`, add `scripts/activator.sh` with domain-specific reminder text. Adapt from self-improving-agent; replace generic prompts with domain triggers.
|
||||
|
||||
## Review → Apply → Report Loop
|
||||
|
||||
The enhanced skill must **use** learnings, not only log them. Include this in EVOLUTION.md or the enhanced skill's instructions:
|
||||
|
||||
### Before Task
|
||||
|
||||
- Load relevant entries from `.learnings/LEARNINGS.md` (and ERRORS.md if applicable)
|
||||
- Filter by area, tags, or keywords
|
||||
- Note which entries apply to the current task
|
||||
|
||||
### During Task
|
||||
|
||||
- Apply learnings when relevant
|
||||
- Optionally annotate output: "本次参考了 [LRN-xxx]: ..." (or equivalent in target language)
|
||||
|
||||
### After Task
|
||||
|
||||
- Summarize for user: which learnings were used, what evolution result, what improvement
|
||||
- Let OpenClaw decide: per-use mention vs end-of-task summary
|
||||
|
||||
**Example** (Chinese): "本次改写了口播稿，参考了经验 [LRN-20250115-001]（科普场景应避免过于书面），相比之前更口语化。"
|
||||
|
||||
**Example** (English): "Used learning [LRN-20250115-001] (avoid formal tone for科普) in this rewrite; output is more conversational than before."
|
||||
|
||||
## User Preference vs Domain Best Practice
|
||||
|
||||
| Type | Storage | Example |
|
||||
|------|---------|---------|
|
||||
| **User preference** | MEMORY.md (user-level) | "This user prefers shorter sentences" |
|
||||
| **Domain best practice** | `.learnings/LEARNINGS.md` | "科普场景应避免过于书面" |
|
||||
|
||||
Evolution is driven by **user feedback**; log and promote based on user corrections and recurring patterns.
|
||||
|
||||
## OpenClaw Active Feedback
|
||||
|
||||
Add to the enhanced skill or SOUL.md/AGENTS.md:
|
||||
|
||||
- When using experience from `.learnings/`, briefly tell the user
|
||||
- At end of task, optionally summarize: evolution used, improvements
|
||||
- Let OpenClaw decide when to surface (per-use vs summary)
|
||||
|
||||
See [references/openclaw-feedback.md](references/openclaw-feedback.md) for SOUL.md and AGENTS.md snippets.
|
||||
|
||||
## Experience Invalidation & Update
|
||||
|
||||
When user corrects again after a learning was applied:
|
||||
|
||||
- Add `Contradicted-By: LRN-YYYYMMDD-XXX` to the original entry
|
||||
- Mark `Last-Valid` or `Status: superseded` if the learning is no longer valid
|
||||
- Increment `Recurrence-Count` if the pattern recurs but the fix is different
|
||||
|
||||
Include in LEARNINGS template: `Recurrence-Count`, `Last-Valid`, `Contradicted-By`.
|
||||
|
||||
## Domain Extraction Framework
|
||||
|
||||
### Trigger Extraction
|
||||
|
||||
**Learning triggers** (user feedback → log to LEARNINGS.md):
|
||||
- Look for: "用户说", "when user says", example dialogs
|
||||
- Infer: common corrections, style mismatches, scene-specific preferences
|
||||
- Add generic fallbacks: "不对", "不是这样", "改一下"
|
||||
|
||||
**Error triggers** (failures → log to ERRORS.md):
|
||||
- Look for: "失败", "报错", "不适用", "when X fails"
|
||||
- Infer: environment-specific failures, edge cases
|
||||
- Add generic fallbacks: "操作失败", "未达到预期"
|
||||
|
||||
### Area Mapping
|
||||
|
||||
Define 3–6 areas that partition the skill's scope. Use domain-specific areas, not coding areas.
|
||||
|
||||
### Promotion Target Naming
|
||||
|
||||
- `{skill-name}-专属进化规则.md` — evolution rules, style preferences
|
||||
- `{skill-name}-最佳实践.md` — best practices
|
||||
- `{skill-name}-安全规范.md` — safety constraints (e.g., 电脑加速)
|
||||
|
||||
Use kebab-case for skill name in filenames.
|
||||
|
||||
## Logging Format (Reuse from Self-Improving-Agent)
|
||||
|
||||
ID format: `LRN-YYYYMMDD-XXX`, `ERR-YYYYMMDD-XXX`, `FEAT-YYYYMMDD-XXX`
|
||||
|
||||
Statuses: `pending` | `in_progress` | `resolved` | `wont_fix` | `promoted` | `promoted_to_skill`
|
||||
|
||||
For full entry formats, see the self-improving-agent skill's Logging Format section.
|
||||
|
||||
## References
|
||||
|
||||
- [assets/DOMAIN-CONFIG-TEMPLATE.md](assets/DOMAIN-CONFIG-TEMPLATE.md) — Schema for domain config
|
||||
- [assets/EVOLUTION-RULES-TEMPLATE.md](assets/EVOLUTION-RULES-TEMPLATE.md) — EVOLUTION.md template
|
||||
- [references/domain-examples.md](references/domain-examples.md) — 洗稿能手, 电脑加速 examples
|
||||
- [references/openclaw-feedback.md](references/openclaw-feedback.md) — SOUL.md, AGENTS.md snippets for active feedback
|
||||
- [scripts/generate-evolution.sh](scripts/generate-evolution.sh) — Optional scaffold generator
|
||||
|
||||
## Source
|
||||
|
||||
- Based on: self-improving-agent 3.0.1
|
||||
- Purpose: Enable any skill to gain self-evolution capabilities similar to self-improving-agent
|
||||
@@ -0,0 +1,6 @@
|
||||
{
|
||||
"ownerId": "kn73p6rbsz7t6kfxtv1h84v84h82h6z6",
|
||||
"slug": "skill-self-evolution-enhancer",
|
||||
"version": "1.0.0",
|
||||
"publishedAt": 1773303234062
|
||||
}
|
||||
+66
@@ -0,0 +1,66 @@
|
||||
# Domain Config for: [skill-name]
|
||||
|
||||
Fill this template when extracting domain from a target skill. Use the extracted values to parameterize LEARNINGS.md, ERRORS.md, FEATURE_REQUESTS.md, and EVOLUTION.md.
|
||||
|
||||
## Capability & Scenario Analysis (before extraction)
|
||||
|
||||
**Capabilities** (what the skill does):
|
||||
- Primary outputs:
|
||||
- Secondary/edge capabilities:
|
||||
- Dependencies:
|
||||
|
||||
**Scenarios** (when and how it is used):
|
||||
- User personas:
|
||||
- Typical tasks:
|
||||
- Input/output patterns:
|
||||
|
||||
**Evolution directions** (what can improve):
|
||||
- User feedback patterns:
|
||||
- Failure modes:
|
||||
- Recurring corrections → domain rules:
|
||||
|
||||
---
|
||||
|
||||
## Domain
|
||||
|
||||
- **Name**: (human-readable domain name, e.g., 洗稿能手, 电脑加速)
|
||||
- **Use cases**: (comma-separated scenarios, e.g., 科普、汇报、直播)
|
||||
- **Areas**: (domain-specific areas for filtering, e.g., 文案 | 口播 | 短视频脚本)
|
||||
- **Language**: (target language for generated files: zh | en)
|
||||
|
||||
## Learning Triggers (user feedback phrases)
|
||||
|
||||
Phrases that indicate user correction or style mismatch → log to LEARNINGS.md:
|
||||
|
||||
- "phrase1"
|
||||
- "phrase2"
|
||||
- "phrase3"
|
||||
|
||||
## Error Triggers (failure modes)
|
||||
|
||||
Situations that indicate operation failure → log to ERRORS.md:
|
||||
|
||||
- failure1
|
||||
- failure2
|
||||
- failure3
|
||||
|
||||
## Promotion Targets
|
||||
|
||||
Files to promote learnings to when they prove broadly applicable:
|
||||
|
||||
- **专属进化规则**: [skill-name]-专属进化规则.md
|
||||
- **最佳实践 / 安全规范**: [skill-name]-最佳实践.md (or [skill-name]-安全规范.md)
|
||||
|
||||
## Domain Categories (optional)
|
||||
|
||||
If the skill needs categories beyond correction | insight | knowledge_gap | best_practice:
|
||||
|
||||
- category1
|
||||
- category2
|
||||
|
||||
## Notes
|
||||
|
||||
- Use kebab-case for skill-name in file paths
|
||||
- Areas should partition the skill's output/workflow scope
|
||||
- Add 3+ learning triggers and 2+ error triggers for effective capture
|
||||
- Storage: same as self-improving-agent — `.learnings/` directly (LEARNINGS.md, ERRORS.md, FEATURE_REQUESTS.md)
|
||||
@@ -0,0 +1,50 @@
|
||||
# Errors Log
|
||||
|
||||
{DOMAIN_DESCRIPTION}
|
||||
|
||||
**Areas**: {DOMAIN_AREAS}
|
||||
**Statuses**: pending | in_progress | resolved | wont_fix
|
||||
|
||||
## Error Entry Format
|
||||
|
||||
Append entries in this format:
|
||||
|
||||
```markdown
|
||||
## [ERR-YYYYMMDD-XXX] operation_or_error_type
|
||||
|
||||
**Logged**: ISO-8601 timestamp
|
||||
**Priority**: high
|
||||
**Status**: pending
|
||||
**Area**: {DOMAIN_AREAS_EXAMPLE}
|
||||
|
||||
### Summary
|
||||
Brief description of what failed
|
||||
|
||||
### Error
|
||||
```
|
||||
Actual error message or output
|
||||
```
|
||||
|
||||
### Context
|
||||
- Operation attempted
|
||||
- Input or parameters used
|
||||
- Environment details if relevant
|
||||
|
||||
### Suggested Fix
|
||||
If identifiable, what might resolve this
|
||||
|
||||
### Metadata
|
||||
- Reproducible: yes | no | unknown
|
||||
- Related Files: path/to/file.ext
|
||||
- See Also: ERR-YYYYMMDD-XXX (if recurring)
|
||||
|
||||
---
|
||||
```
|
||||
|
||||
## Placeholders to Replace
|
||||
|
||||
- `{DOMAIN_DESCRIPTION}`: e.g., "Operation failures, exceptions, and unexpected behaviors for [skill-name]."
|
||||
- `{DOMAIN_AREAS}`: e.g., "文案 | 口播 | 短视频脚本" or "系统优化 | 卡顿 | 报错"
|
||||
- `{DOMAIN_AREAS_EXAMPLE}`: One example area from the list
|
||||
|
||||
---
|
||||
+100
@@ -0,0 +1,100 @@
|
||||
# [Skill Name] Evolution Rules
|
||||
|
||||
Domain-specific self-improvement rules for [skill-name]. Log learnings and errors to `.learnings/`; promote proven patterns to the targets below. **Evolution is driven by user feedback.**
|
||||
|
||||
## Quick Reference
|
||||
|
||||
| Situation | Action |
|
||||
|-----------|--------|
|
||||
| {LEARNING_TRIGGER_1} | Log to `.learnings/LEARNINGS.md` with category `correction` or `style_mismatch` |
|
||||
| {LEARNING_TRIGGER_2} | Log to `.learnings/LEARNINGS.md` |
|
||||
| {ERROR_TRIGGER_1} | Log to `.learnings/ERRORS.md` |
|
||||
| {ERROR_TRIGGER_2} | Log to `.learnings/ERRORS.md` |
|
||||
| User wants missing capability | Log to `.learnings/FEATURE_REQUESTS.md` |
|
||||
| Pattern proven across 3+ instances | Promote to {PROMOTION_TARGET_1} |
|
||||
| Safety/correctness rule | Promote to {PROMOTION_TARGET_2} |
|
||||
|
||||
## Review → Apply → Report Loop
|
||||
|
||||
**Before task**: Load relevant entries from `.learnings/LEARNINGS.md` (and ERRORS.md if applicable). Filter by area, tags, or keywords.
|
||||
|
||||
**During task**: Apply learnings when relevant. Optionally annotate: "本次参考了 [LRN-xxx]: ..." (or equivalent in target language).
|
||||
|
||||
**After task**: Tell user which learnings were used, what evolution result, what improvement. Decide per-use mention vs end-of-task summary based on context.
|
||||
|
||||
## Detection Triggers
|
||||
|
||||
### Learning Triggers (→ LEARNINGS.md)
|
||||
|
||||
- {LEARNING_TRIGGER_1}
|
||||
- {LEARNING_TRIGGER_2}
|
||||
- {LEARNING_TRIGGER_3}
|
||||
- User provides correction or preference
|
||||
- Better approach discovered for recurring task
|
||||
|
||||
### Error Triggers (→ ERRORS.md)
|
||||
|
||||
- {ERROR_TRIGGER_1}
|
||||
- {ERROR_TRIGGER_2}
|
||||
- {ERROR_TRIGGER_3}
|
||||
- Operation fails unexpectedly
|
||||
- Unexpected output or behavior
|
||||
|
||||
## Domain Activation Conditions (for hooks)
|
||||
|
||||
When to remind the agent to check learnings:
|
||||
|
||||
- {ACTIVATION_CONDITION_1}
|
||||
- {ACTIVATION_CONDITION_2}
|
||||
|
||||
## Promotion Decision Tree
|
||||
|
||||
```
|
||||
Is the learning skill-specific?
|
||||
├── Yes → Keep in .learnings/
|
||||
└── No → Is it style/behavior-related?
|
||||
├── Yes → Promote to {PROMOTION_TARGET_1}
|
||||
└── No → Is it safety/correctness-related?
|
||||
├── Yes → Promote to {PROMOTION_TARGET_2}
|
||||
└── No → Promote to {PROMOTION_TARGET_1}
|
||||
```
|
||||
|
||||
## Experience Invalidation & Update
|
||||
|
||||
When user corrects again after a learning was applied:
|
||||
|
||||
- Add `Contradicted-By: LRN-YYYYMMDD-XXX` to the original entry
|
||||
- Mark `Status: superseded` or `Last-Valid: YYYY-MM-DD` if the learning is no longer valid
|
||||
- Increment `Recurrence-Count` if the pattern recurs but the fix is different
|
||||
|
||||
## Area Tags
|
||||
|
||||
| Area | Scope |
|
||||
|------|-------|
|
||||
| {AREA_1} | {AREA_1_SCOPE} |
|
||||
| {AREA_2} | {AREA_2_SCOPE} |
|
||||
| {AREA_3} | {AREA_3_SCOPE} |
|
||||
|
||||
## Priority Guidelines
|
||||
|
||||
| Priority | When to Use |
|
||||
|----------|-------------|
|
||||
| `critical` | Blocks core functionality, safety risk |
|
||||
| `high` | Significant impact, affects common workflows |
|
||||
| `medium` | Moderate impact, workaround exists |
|
||||
| `low` | Minor inconvenience, edge case |
|
||||
|
||||
## Promotion Targets
|
||||
|
||||
- **{PROMOTION_TARGET_1}**: Evolution rules, style preferences, best practices
|
||||
- **{PROMOTION_TARGET_2}**: Safety guidelines, correctness rules (if applicable)
|
||||
|
||||
## Placeholders to Replace
|
||||
|
||||
- `[skill-name]`, `[Skill Name]`: Domain name
|
||||
- `{LEARNING_TRIGGER_1}`, `{LEARNING_TRIGGER_2}`, `{LEARNING_TRIGGER_3}`: User feedback phrases from domain config
|
||||
- `{ERROR_TRIGGER_1}`, `{ERROR_TRIGGER_2}`, `{ERROR_TRIGGER_3}`: Failure modes from domain config
|
||||
- `{ACTIVATION_CONDITION_1}`, `{ACTIVATION_CONDITION_2}`: Domain-specific activation (e.g., "User says 改得不通顺", "Optimization reported无效")
|
||||
- `{PROMOTION_TARGET_1}`, `{PROMOTION_TARGET_2}`: e.g., `[skill-name]-专属进化规则.md`, `[skill-name]-最佳实践.md`
|
||||
- `{AREA_1}`, `{AREA_2}`, `{AREA_3}`: Domain areas
|
||||
- `{AREA_1_SCOPE}`, etc.: Brief scope description for each area
|
||||
+45
@@ -0,0 +1,45 @@
|
||||
# Feature Requests
|
||||
|
||||
{DOMAIN_DESCRIPTION}
|
||||
|
||||
**Areas**: {DOMAIN_AREAS}
|
||||
**Statuses**: pending | in_progress | resolved | wont_fix
|
||||
|
||||
## Feature Request Entry Format
|
||||
|
||||
Append entries in this format:
|
||||
|
||||
```markdown
|
||||
## [FEAT-YYYYMMDD-XXX] capability_name
|
||||
|
||||
**Logged**: ISO-8601 timestamp
|
||||
**Priority**: medium
|
||||
**Status**: pending
|
||||
**Area**: {DOMAIN_AREAS_EXAMPLE}
|
||||
|
||||
### Requested Capability
|
||||
What the user wanted to do
|
||||
|
||||
### User Context
|
||||
Why they needed it, what problem they're solving
|
||||
|
||||
### Complexity Estimate
|
||||
simple | medium | complex
|
||||
|
||||
### Suggested Implementation
|
||||
How this could be built, what it might extend
|
||||
|
||||
### Metadata
|
||||
- Frequency: first_time | recurring
|
||||
- Related Features: existing_feature_name
|
||||
|
||||
---
|
||||
```
|
||||
|
||||
## Placeholders to Replace
|
||||
|
||||
- `{DOMAIN_DESCRIPTION}`: e.g., "Capabilities requested by user that don't currently exist for [skill-name]."
|
||||
- `{DOMAIN_AREAS}`: e.g., "文案 | 口播 | 短视频脚本" or "系统优化 | 卡顿 | 报错"
|
||||
- `{DOMAIN_AREAS_EXAMPLE}`: One example area from the list
|
||||
|
||||
---
|
||||
@@ -0,0 +1,62 @@
|
||||
# Learnings
|
||||
|
||||
{DOMAIN_DESCRIPTION}
|
||||
|
||||
**Categories**: {DOMAIN_CATEGORIES}
|
||||
**Areas**: {DOMAIN_AREAS}
|
||||
**Statuses**: pending | in_progress | resolved | wont_fix | promoted | promoted_to_skill | superseded
|
||||
|
||||
## Status Definitions
|
||||
|
||||
| Status | Meaning |
|
||||
|--------|---------|
|
||||
| `pending` | Not yet addressed |
|
||||
| `in_progress` | Actively being worked on |
|
||||
| `resolved` | Issue fixed or knowledge integrated |
|
||||
| `wont_fix` | Decided not to address (reason in Resolution) |
|
||||
| `promoted` | Elevated to {PROMOTION_TARGETS} |
|
||||
| `promoted_to_skill` | Extracted as a reusable skill |
|
||||
| `superseded` | User corrected again; this learning is no longer valid |
|
||||
|
||||
## Learning Entry Format
|
||||
|
||||
Append entries in this format:
|
||||
|
||||
```markdown
|
||||
## [LRN-YYYYMMDD-XXX] category
|
||||
|
||||
**Logged**: ISO-8601 timestamp
|
||||
**Priority**: low | medium | high | critical
|
||||
**Status**: pending
|
||||
**Area**: {DOMAIN_AREAS_EXAMPLE}
|
||||
|
||||
### Summary
|
||||
One-line description of what was learned
|
||||
|
||||
### Details
|
||||
Full context: what happened, what was wrong, what's correct
|
||||
|
||||
### Suggested Action
|
||||
Specific fix or improvement to make
|
||||
|
||||
### Metadata
|
||||
- Source: conversation | error | user_feedback
|
||||
- Related Files: path/to/file.ext
|
||||
- Tags: tag1, tag2
|
||||
- See Also: LRN-YYYYMMDD-XXX (if related to existing entry)
|
||||
- Recurrence-Count: 1 (optional, bump when pattern recurs)
|
||||
- Last-Valid: YYYY-MM-DD (optional, when user contradicted)
|
||||
- Contradicted-By: LRN-YYYYMMDD-XXX (optional, when superseded)
|
||||
|
||||
---
|
||||
```
|
||||
|
||||
## Placeholders to Replace
|
||||
|
||||
- `{DOMAIN_DESCRIPTION}`: e.g., "Corrections, insights, and style preferences captured for [skill-name]."
|
||||
- `{DOMAIN_CATEGORIES}`: e.g., "correction | insight | knowledge_gap | best_practice | style_mismatch | scene_adaptation"
|
||||
- `{DOMAIN_AREAS}`: e.g., "文案 | 口播 | 短视频脚本" or "系统优化 | 卡顿 | 报错"
|
||||
- `{DOMAIN_AREAS_EXAMPLE}`: One example area from the list
|
||||
- `{PROMOTION_TARGETS}`: e.g., "[skill-name]-专属进化规则.md, [skill-name]-最佳实践.md"
|
||||
|
||||
---
|
||||
+134
@@ -0,0 +1,134 @@
|
||||
# Domain Examples
|
||||
|
||||
Concrete examples for extracting domain config and generating evolution scaffolding. Use these as reference when enhancing skills.
|
||||
|
||||
---
|
||||
|
||||
## Example 1: 洗稿能手 (Content Rewriting Skill)
|
||||
|
||||
**Domain**: 文案 / 口播 / 短视频脚本改写
|
||||
|
||||
### Capability & Scenario Analysis
|
||||
|
||||
- **Capabilities**: Rewrite text for different formats (文案, 口播, 短视频); adapt style by scene (科普, 汇报, 直播)
|
||||
- **Scenarios**: User provides source text; requests rewrite for specific format/scene; may correct style
|
||||
- **Evolution directions**: User feedback on style ("不通顺", "不像口播") → learn scene-specific preferences; recurring corrections → promote to 专属进化规则
|
||||
|
||||
### Domain Config
|
||||
|
||||
```markdown
|
||||
## Domain
|
||||
- Name: 洗稿能手
|
||||
- Use cases: 科普, 汇报, 直播, 短视频脚本, 口播稿
|
||||
- Areas: 文案 | 口播 | 短视频脚本 | 科普 | 汇报 | 直播
|
||||
- Language: zh
|
||||
|
||||
## Learning Triggers
|
||||
- "改得不通顺"
|
||||
- "不像口播"
|
||||
- "风格不对"
|
||||
- "太书面了"
|
||||
- "读起来不顺"
|
||||
- "语气不对"
|
||||
|
||||
## Error Triggers
|
||||
- 改写后用户多次要求重改
|
||||
- 风格与场景不匹配（如科普写成汇报风）
|
||||
- 口播稿读起来拗口
|
||||
|
||||
## Promotion Targets
|
||||
- 洗稿能手-专属进化规则.md
|
||||
- 洗稿能手-最佳实践.md
|
||||
```
|
||||
|
||||
### Generated EVOLUTION.md Quick Reference
|
||||
|
||||
| Situation | Action |
|
||||
|-----------|--------|
|
||||
| 用户说"改得不通顺" | Log to `.learnings/LEARNINGS.md` with category `style_mismatch` |
|
||||
| 用户说"不像口播" | Log to `.learnings/LEARNINGS.md` with category `scene_adaptation` |
|
||||
| 用户说"风格不对" | Log to `.learnings/LEARNINGS.md` with category `correction` |
|
||||
| 改写后多次重改 | Log to `.learnings/ERRORS.md` |
|
||||
| 风格与场景不匹配 | Log to `.learnings/LEARNINGS.md` with area 科普/汇报/直播 |
|
||||
|
||||
### Domain Categories
|
||||
|
||||
- correction
|
||||
- style_mismatch
|
||||
- scene_adaptation
|
||||
- best_practice
|
||||
- knowledge_gap
|
||||
|
||||
### Activation Conditions
|
||||
|
||||
- User says "改得不通顺", "不像口播", "风格不对"
|
||||
- User requests rewrite for a specific scene (科普/汇报/直播)
|
||||
|
||||
---
|
||||
|
||||
## Example 2: 电脑加速 (PC Optimization Skill)
|
||||
|
||||
**Domain**: Windows 优化 / 卡慢 / 卡顿
|
||||
|
||||
### Capability & Scenario Analysis
|
||||
|
||||
- **Capabilities**: System optimization, startup speed, memory release; diagnose slowdowns
|
||||
- **Scenarios**: User reports slow PC; agent suggests optimizations; some may fail or cause issues
|
||||
- **Evolution directions**: "优化无效", "某些电脑不适用" → learn environment-specific solutions; safety issues → promote to 安全规范
|
||||
|
||||
### Domain Config
|
||||
|
||||
```markdown
|
||||
## Domain
|
||||
- Name: 电脑加速
|
||||
- Use cases: 系统优化, 卡顿排查, 启动加速, 内存释放
|
||||
- Areas: 系统优化 | 卡顿 | 报错 | 兼容性 | 安全
|
||||
- Language: zh
|
||||
|
||||
## Learning Triggers
|
||||
- "优化无效"
|
||||
- "某些电脑不适用"
|
||||
- "这样改有问题"
|
||||
- "上次的方法不行"
|
||||
|
||||
## Error Triggers
|
||||
- 优化后系统报错
|
||||
- 某些电脑/系统版本不适用
|
||||
- 操作导致异常或蓝屏
|
||||
- 命令执行失败
|
||||
|
||||
## Promotion Targets
|
||||
- 电脑加速-安全规范.md
|
||||
- 电脑加速-最佳实践.md
|
||||
```
|
||||
|
||||
### Generated EVOLUTION.md Quick Reference
|
||||
|
||||
| Situation | Action |
|
||||
|-----------|--------|
|
||||
| 用户说"优化无效" | Log to `.learnings/ERRORS.md` with area 系统优化 |
|
||||
| 用户说"某些电脑不适用" | Log to `.learnings/LEARNINGS.md` with category `knowledge_gap` |
|
||||
| 优化后报错 | Log to `.learnings/ERRORS.md` with area 报错 |
|
||||
| 发现安全风险 | Log to `.learnings/LEARNINGS.md`, promote to 电脑加速-安全规范.md |
|
||||
|
||||
### Domain Categories
|
||||
|
||||
- correction
|
||||
- knowledge_gap
|
||||
- best_practice
|
||||
- safety_constraint
|
||||
|
||||
### Activation Conditions
|
||||
|
||||
- User reports "优化无效", "报错", "某些电脑不适用"
|
||||
- After suggesting optimization steps
|
||||
|
||||
---
|
||||
|
||||
## Extraction Tips
|
||||
|
||||
1. **Sparse skills**: If the target skill has little content, infer from the name and description. Add generic triggers like "用户纠正", "操作失败".
|
||||
2. **Coding skills**: Use areas like frontend | backend | infra if the skill is coding-related; otherwise use domain-specific areas.
|
||||
3. **Safety-critical domains** (e.g., 电脑加速): Always include a 安全规范 promotion target.
|
||||
4. **Style domains** (e.g., 洗稿能手): Include style_mismatch, scene_adaptation categories.
|
||||
5. **Language**: Infer from SKILL.md; generate all output in that language.
|
||||
+58
@@ -0,0 +1,58 @@
|
||||
# OpenClaw Active Feedback Integration
|
||||
|
||||
When a skill is enhanced with self-evolution, the agent must **tell the user** when experience was used and what improvement resulted. Add these snippets to SOUL.md or AGENTS.md in the OpenClaw workspace (or to the enhanced skill's EVOLUTION.md) so OpenClaw proactively surfaces evolution feedback.
|
||||
|
||||
## SOUL.md Snippet (Behavioral Guidelines)
|
||||
|
||||
```markdown
|
||||
## Self-Evolution Feedback
|
||||
|
||||
When using experience from `.learnings/` (LEARNINGS.md, ERRORS.md):
|
||||
|
||||
1. **During task**: Optionally mention when a learning was applied: "本次参考了经验 [LRN-xxx]: ..."
|
||||
2. **After task**: Summarize when relevant: which learnings were used, what evolution result, what improvement
|
||||
3. **Decide contextually**: Per-use mention vs end-of-task summary — choose based on task length and user need
|
||||
|
||||
Do not leave the user in the dark. If evolution was used, surface it at an appropriate moment.
|
||||
```
|
||||
|
||||
## AGENTS.md Snippet (Workflow)
|
||||
|
||||
```markdown
|
||||
## Self-Evolution Workflow
|
||||
|
||||
Before using an enhanced skill:
|
||||
1. Load relevant entries from `.learnings/LEARNINGS.md` (filter by area/tags)
|
||||
2. Apply learnings during the task
|
||||
3. After completing the task, evaluate: did we use any learnings?
|
||||
- If yes: Tell the user (per-use or summary, decide based on context)
|
||||
- Include: which entries, what improvement
|
||||
```
|
||||
|
||||
## EVOLUTION.md Integration
|
||||
|
||||
When generating EVOLUTION.md for an enhanced skill, include a section:
|
||||
|
||||
```markdown
|
||||
## OpenClaw Feedback
|
||||
|
||||
When this skill uses experience from .learnings/:
|
||||
- Mention to user: which learning was used, what improvement
|
||||
- Let OpenClaw decide: per-use mention vs end-of-task summary
|
||||
- Example: "本次改写了口播稿，参考了 [LRN-xxx]（科普场景应避免过于书面），相比之前更口语化。"
|
||||
```
|
||||
|
||||
## Hook Reminder (Optional)
|
||||
|
||||
For domain-specific activation, the activator script can remind:
|
||||
|
||||
```bash
|
||||
# In scripts/activator.sh for the enhanced skill
|
||||
cat << 'EOF'
|
||||
<self-evolution-reminder>
|
||||
After this task, if you used any entries from .learnings/:
|
||||
- Tell the user which learnings were applied
|
||||
- Summarize the evolution result and improvement
|
||||
</self-evolution-reminder>
|
||||
EOF
|
||||
```
|
||||
+155
@@ -0,0 +1,155 @@
|
||||
#!/bin/bash
|
||||
# Skill Self-Evolution Scaffold Generator
|
||||
# Creates .learnings/ and template files in a target skill for domain-specific self-improvement.
|
||||
# Usage: ./generate-evolution.sh <target-skill-path> [--dry-run]
|
||||
#
|
||||
# Part of skill-self-evolution-enhancer. The agent should then:
|
||||
# 1. Read the target skill's SKILL.md
|
||||
# 2. Perform deep capability & scenario analysis
|
||||
# 3. Fill DOMAIN-CONFIG-DRAFT.md with extracted domain
|
||||
# 4. Parameterize and finalize .learnings/ files and EVOLUTION.md
|
||||
# 5. Add Review→Apply→Report and OpenClaw feedback rules
|
||||
|
||||
set -e
|
||||
|
||||
# Resolve script directory (skill-self-evolution-enhancer/scripts/)
|
||||
SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
|
||||
ASSETS_DIR="$(cd "$SCRIPT_DIR/../assets" && pwd)"
|
||||
|
||||
# Colors
|
||||
RED='\033[0;31m'
|
||||
GREEN='\033[0;32m'
|
||||
YELLOW='\033[1;33m'
|
||||
NC='\033[0m'
|
||||
|
||||
usage() {
|
||||
cat << EOF
|
||||
Usage: $(basename "$0") <target-skill-path> [options]
|
||||
|
||||
Create self-evolution scaffolding in a target skill. Output structure matches self-improving-agent:
|
||||
target-skill/.learnings/LEARNINGS.md, ERRORS.md, FEATURE_REQUESTS.md
|
||||
|
||||
Arguments:
|
||||
target-skill-path Path to the skill directory (e.g., ./skills/my-skill, ~/skills/rewrite-master)
|
||||
|
||||
Options:
|
||||
--dry-run Show what would be created without creating files
|
||||
-h, --help Show this help message
|
||||
|
||||
Examples:
|
||||
$(basename "$0") ./skills/rewrite-master
|
||||
$(basename "$0") ~/.cursor/skills/pc-optimizer --dry-run
|
||||
|
||||
Output:
|
||||
- target-skill/.learnings/LEARNINGS.md, ERRORS.md, FEATURE_REQUESTS.md (with placeholders)
|
||||
- target-skill/DOMAIN-CONFIG-DRAFT.md (for agent to fill)
|
||||
- target-skill/EVOLUTION.md (with placeholders)
|
||||
EOF
|
||||
}
|
||||
|
||||
log_info() { echo -e "${GREEN}[INFO]${NC} $1"; }
|
||||
log_warn() { echo -e "${YELLOW}[WARN]${NC} $1"; }
|
||||
log_error() { echo -e "${RED}[ERROR]${NC} $1" >&2; }
|
||||
|
||||
# Parse arguments
|
||||
TARGET_PATH=""
|
||||
DRY_RUN=false
|
||||
|
||||
while [[ $# -gt 0 ]]; do
|
||||
case $1 in
|
||||
--dry-run)
|
||||
DRY_RUN=true
|
||||
shift
|
||||
;;
|
||||
-h|--help)
|
||||
usage
|
||||
exit 0
|
||||
;;
|
||||
-*)
|
||||
log_error "Unknown option: $1"
|
||||
usage
|
||||
exit 1
|
||||
;;
|
||||
*)
|
||||
if [ -z "$TARGET_PATH" ]; then
|
||||
TARGET_PATH="$1"
|
||||
else
|
||||
log_error "Unexpected argument: $1"
|
||||
usage
|
||||
exit 1
|
||||
fi
|
||||
shift
|
||||
;;
|
||||
esac
|
||||
done
|
||||
|
||||
if [ -z "$TARGET_PATH" ]; then
|
||||
log_error "Target skill path is required"
|
||||
usage
|
||||
exit 1
|
||||
fi
|
||||
|
||||
# Resolve to absolute path
|
||||
TARGET_PATH="$(cd "$TARGET_PATH" 2>/dev/null && pwd)" || {
|
||||
log_error "Target path does not exist or is not accessible: $TARGET_PATH"
|
||||
exit 1
|
||||
}
|
||||
|
||||
# Validate target has SKILL.md
|
||||
if [ ! -f "$TARGET_PATH/SKILL.md" ]; then
|
||||
log_error "Target skill must have SKILL.md: $TARGET_PATH/SKILL.md"
|
||||
exit 1
|
||||
fi
|
||||
|
||||
# Validate assets exist
|
||||
for f in DOMAIN-CONFIG-TEMPLATE.md LEARNINGS-TEMPLATE.md ERRORS-TEMPLATE.md FEATURE_REQUESTS-TEMPLATE.md EVOLUTION-RULES-TEMPLATE.md; do
|
||||
if [ ! -f "$ASSETS_DIR/$f" ]; then
|
||||
log_error "Missing asset: $ASSETS_DIR/$f"
|
||||
exit 1
|
||||
fi
|
||||
done
|
||||
|
||||
# Same structure as self-improving-agent: .learnings/ directly
|
||||
LEARNINGS_DIR="$TARGET_PATH/.learnings"
|
||||
|
||||
if [ "$DRY_RUN" = true ]; then
|
||||
log_info "Dry run - would create:"
|
||||
echo " $LEARNINGS_DIR/"
|
||||
echo " $LEARNINGS_DIR/LEARNINGS.md (from LEARNINGS-TEMPLATE.md, placeholders)"
|
||||
echo " $LEARNINGS_DIR/ERRORS.md (from ERRORS-TEMPLATE.md, placeholders)"
|
||||
echo " $LEARNINGS_DIR/FEATURE_REQUESTS.md (from FEATURE_REQUESTS-TEMPLATE.md, placeholders)"
|
||||
echo " $TARGET_PATH/DOMAIN-CONFIG-DRAFT.md (from DOMAIN-CONFIG-TEMPLATE.md)"
|
||||
echo " $TARGET_PATH/EVOLUTION.md (from EVOLUTION-RULES-TEMPLATE.md, placeholders)"
|
||||
echo ""
|
||||
log_info "Agent should: 1) Read SKILL.md 2) Deep analysis 3) Fill DOMAIN-CONFIG-DRAFT.md 4) Replace placeholders"
|
||||
exit 0
|
||||
fi
|
||||
|
||||
# Create .learnings/
|
||||
log_info "Creating $LEARNINGS_DIR/"
|
||||
mkdir -p "$LEARNINGS_DIR"
|
||||
|
||||
# Copy templates with generic placeholders (agent fills domain-specific values later)
|
||||
log_info "Creating LEARNINGS.md, ERRORS.md, FEATURE_REQUESTS.md"
|
||||
cp "$ASSETS_DIR/LEARNINGS-TEMPLATE.md" "$LEARNINGS_DIR/LEARNINGS.md"
|
||||
cp "$ASSETS_DIR/ERRORS-TEMPLATE.md" "$LEARNINGS_DIR/ERRORS.md"
|
||||
cp "$ASSETS_DIR/FEATURE_REQUESTS-TEMPLATE.md" "$LEARNINGS_DIR/FEATURE_REQUESTS.md"
|
||||
|
||||
# Create DOMAIN-CONFIG-DRAFT.md for agent to fill
|
||||
SKILL_NAME=$(basename "$TARGET_PATH")
|
||||
sed "s/\[skill-name\]/$SKILL_NAME/g" "$ASSETS_DIR/DOMAIN-CONFIG-TEMPLATE.md" > "$TARGET_PATH/DOMAIN-CONFIG-DRAFT.md"
|
||||
log_info "Created DOMAIN-CONFIG-DRAFT.md (agent should fill this)"
|
||||
|
||||
# Create EVOLUTION.md with placeholders
|
||||
cp "$ASSETS_DIR/EVOLUTION-RULES-TEMPLATE.md" "$TARGET_PATH/EVOLUTION.md"
|
||||
log_info "Created EVOLUTION.md (agent should replace placeholders)"
|
||||
|
||||
echo ""
|
||||
log_info "Scaffold created successfully!"
|
||||
echo ""
|
||||
echo "Next steps:"
|
||||
echo " 1. Read $TARGET_PATH/SKILL.md and perform deep capability & scenario analysis"
|
||||
echo " 2. Fill $TARGET_PATH/DOMAIN-CONFIG-DRAFT.md with extracted domain config"
|
||||
echo " 3. Replace placeholders in .learnings/*.md and EVOLUTION.md using the domain config"
|
||||
echo " 4. Ensure language of generated files matches target skill's user language"
|
||||
echo " 5. Add Review→Apply→Report and OpenClaw feedback rules (see references/openclaw-feedback.md)"
|
||||
@@ -0,0 +1,93 @@
|
||||
# Find 技能进化规则
|
||||
|
||||
Domain-specific self-improvement rules for **Find** skill. Log learnings and errors to `.learnings/`; promote proven patterns to the targets below. **Evolution is driven by user feedback.**
|
||||
|
||||
## Quick Reference
|
||||
|
||||
| Situation | Action |
|
||||
|-----------|--------|
|
||||
| 用户说"不是这个"、"不对" | Log to `.learnings/LEARNINGS.md` with category `correction` |
|
||||
| 搜索结果不相关 | Log to `.learnings/LEARNINGS.md` with category `style_mismatch` |
|
||||
| 信息源访问失败 | Log to `.learnings/ERRORS.md` |
|
||||
| 搜索超时 | Log to `.learnings/ERRORS.md` |
|
||||
| 用户需要新能力 | Log to `.learnings/FEATURE_REQUESTS.md` |
|
||||
| 某模式重复验证3+次 | Promote to `find-最佳实践.md` |
|
||||
| 安全/准确性规则 | Promote to `find-专属进化规则.md` |
|
||||
|
||||
## Review → Apply → Report Loop
|
||||
|
||||
**Before task**: Load relevant entries from `.learnings/LEARNINGS.md` (and ERRORS.md if applicable). Filter by area, tags, or keywords.
|
||||
|
||||
**During task**: Apply learnings when relevant. Optionally annotate: "本次参考了 [LRN-xxx]: ...".
|
||||
|
||||
**After task**: Tell user which learnings were used, what evolution result, what improvement.
|
||||
|
||||
## Detection Triggers
|
||||
|
||||
### Learning Triggers (→ LEARNINGS.md)
|
||||
|
||||
- 用户说"不是这个"、"不对"、"不是这样"
|
||||
- 用户提供更精准的搜索关键词
|
||||
- 发现更好的信息源或搜索路径
|
||||
- 用户补充了新的约束条件（预算、时间、格式）
|
||||
- 某类搜索场景重复出现
|
||||
|
||||
### Error Triggers (→ ERRORS.md)
|
||||
|
||||
- 信息源访问失败（403/404/超时）
|
||||
- 搜索结果与目标完全不匹配
|
||||
- 验证步骤失败
|
||||
- 代理/网络连接问题
|
||||
- 工具执行异常
|
||||
|
||||
## Domain Activation Conditions (for hooks)
|
||||
|
||||
When to remind the agent to check learnings:
|
||||
|
||||
- 用户说"找不到"、"搜不到"
|
||||
- 搜索返回空结果
|
||||
- 连续2次搜索都未命中目标
|
||||
|
||||
## Promotion Decision Tree
|
||||
|
||||
```
|
||||
Is the learning skill-specific?
|
||||
├── Yes → Keep in .learnings/
|
||||
└── No → Is it style/behavior-related?
|
||||
├── Yes → Promote to find-最佳实践.md
|
||||
└── No → Is it safety/correctness-related?
|
||||
├── Yes → Promote to find-专属进化规则.md
|
||||
└── No → Promote to find-最佳实践.md
|
||||
```
|
||||
|
||||
## Experience Invalidation & Update
|
||||
|
||||
When user corrects again after a learning was applied:
|
||||
|
||||
- Add `Contradicted-By: LRN-YYYYMMDD-XXX` to the original entry
|
||||
- Mark `Status: superseded` or `Last-Valid: YYYY-MM-DD` if the learning is no longer valid
|
||||
- Increment `Recurrence-Count` if the pattern recurs but the fix is different
|
||||
|
||||
## Area Tags
|
||||
|
||||
| Area | Scope |
|
||||
|------|-------|
|
||||
| 搜索策略 | 从狭义到广义的扩展路径选择 |
|
||||
| 验证方式 | 结果可靠性确认方法 |
|
||||
| 结果呈现 | 格式、结构、置信度表达 |
|
||||
| 用户交互 | 澄清问题的方式和时机 |
|
||||
| 信息源扩展 | 哪些源适合哪些类型查找 |
|
||||
|
||||
## Priority Guidelines
|
||||
|
||||
| Priority | When to Use |
|
||||
|----------|-------------|
|
||||
| `critical` | 搜索功能完全不可用 |
|
||||
| `high` | 常用场景搜不到目标 |
|
||||
| `medium` | 结果质量可接受但不理想 |
|
||||
| `low` | 边缘案例的微小改进 |
|
||||
|
||||
## Promotion Targets
|
||||
|
||||
- **find-最佳实践.md**: Evolution rules, style preferences, best practices
|
||||
- **find-专属进化规则.md**: Safety guidelines, correctness rules
|
||||
@@ -0,0 +1,79 @@
|
||||
---
|
||||
name: Find
|
||||
description: Locate anything with progressive search expansion, multi-source validation, and iterative refinement until found.
|
||||
---
|
||||
|
||||
## Pattern
|
||||
|
||||
```
|
||||
Need → Clarify → Search → Validate → [Found? Deliver : Expand]
|
||||
```
|
||||
|
||||
Keep searching until found or exhausted. Start narrow, expand progressively. Validate before delivering.
|
||||
|
||||
## When to Use
|
||||
|
||||
- User needs to find something specific
|
||||
- Location or source is unknown
|
||||
- "Find me...", "Where can I get...", "I need to find..."
|
||||
|
||||
**Not for:** Things you already know, simple lookups, browsing.
|
||||
|
||||
## Setup
|
||||
|
||||
Before searching, clarify:
|
||||
|
||||
| Element | Why |
|
||||
|---------|-----|
|
||||
| What exactly? | Avoid finding wrong thing |
|
||||
| Success criteria | How will we know it's right? |
|
||||
| Constraints | Budget, location, time, format |
|
||||
| Already tried? | Don't repeat failed paths |
|
||||
|
||||
If user is vague → ask ONE clarifying question, then start.
|
||||
|
||||
## Search Expansion
|
||||
|
||||
Start narrow, expand if not found:
|
||||
|
||||
```
|
||||
1. Obvious sources → Direct lookup, known locations
|
||||
2. Specialized sources → Domain-specific databases, expert communities
|
||||
3. Alternative queries → Different words, related concepts
|
||||
4. Indirect paths → Who would know? What links to this?
|
||||
5. Ask human → More context, different angle
|
||||
```
|
||||
|
||||
Each expansion: try multiple sources in parallel when possible.
|
||||
|
||||
## Validation
|
||||
|
||||
Before delivering, verify:
|
||||
- Is this actually what was asked for?
|
||||
- Is the source reliable?
|
||||
- Is it current/valid?
|
||||
- Any caveats user should know?
|
||||
|
||||
If uncertain → say so. "Found X but not 100% sure it's what you need."
|
||||
|
||||
## Delivery
|
||||
|
||||
```
|
||||
FOUND: [what]
|
||||
WHERE: [source]
|
||||
CONFIDENCE: [high/medium/low]
|
||||
CAVEATS: [if any]
|
||||
```
|
||||
|
||||
If multiple results: summarize and let user choose.
|
||||
|
||||
## Not Found
|
||||
|
||||
If exhausted all paths:
|
||||
1. Report what was tried
|
||||
2. Closest alternatives found
|
||||
3. Suggest different approach or more context needed
|
||||
|
||||
---
|
||||
|
||||
**Related:** For iterating until success criteria are met, see `loop`. For multi-phase workflows, see `cycle`.
|
||||
@@ -0,0 +1,6 @@
|
||||
{
|
||||
"ownerId": "kn73vp5rarc3b14rc7wjcw8f8580t5d1",
|
||||
"slug": "find",
|
||||
"version": "1.0.0",
|
||||
"publishedAt": 1770932409497
|
||||
}
|
||||
@@ -0,0 +1,52 @@
|
||||
---
|
||||
name: mp3-player
|
||||
description: MP3音乐播放器，支持战争模式和提示音模式。当用户说"播放mp3"、"开启战争模式"、"mp3循环播放"、"设定播放时间"时使用。功能：(1)播放列表动态扫描 /d/mp3 目录 (2)战争模式-随机暂停模拟战斗效果 (3)支持--hours参数定时停止 (4)纯提示音模式（只播提示音，不播歌曲） (5)自动检测并结束旧进程。
|
||||
---
|
||||
|
||||
# MP3 Player Skill
|
||||
|
||||
## 快速启动
|
||||
|
||||
```bash
|
||||
# 普通战争模式（播放歌曲 + 随机停火）
|
||||
cd /d/mp3 && python3 -u playlist_war.py --war
|
||||
|
||||
# 纯提示音模式（只播放提示音，不播放歌曲）
|
||||
cd /d/mp3 && python3 -u playlist_war.py --msg
|
||||
|
||||
# 战争模式 + 随机提示音（播放歌曲 + 停火 + 提示音）
|
||||
cd /d/mp3 && python3 -u playlist_war.py --war --msg
|
||||
|
||||
# 纯提示音模式 + 定时停止（10分钟）
|
||||
cd /d/mp3 && python3 -u playlist_war.py --msg --hours 0.167
|
||||
```
|
||||
|
||||
## 核心参数
|
||||
|
||||
| 参数 | 说明 |
|
||||
|------|------|
|
||||
| `--war` | 战争模式（播放歌曲，每10-20秒随机停1-5秒） |
|
||||
| `--msg` | 纯提示音模式（只播放提示音，不播放歌曲） |
|
||||
| `--war --msg` | 战争模式 + 随机提示音（播放歌曲 + 停火 + 提示音） |
|
||||
| `--hours <N>` | 播放N小时后自动停止 |
|
||||
| `--random` | 随机打乱播放顺序 |
|
||||
| 无参数 | 普通模式，无限时播放歌曲 |
|
||||
|
||||
## 播放列表机制
|
||||
- **动态扫描**：每次启动时自动扫描 `/d/mp3` 目录
|
||||
- **支持格式**：mp3 / wav / flac / m4a / ogg
|
||||
|
||||
## 纯提示音模式（--msg）
|
||||
- 只循环播放提示音，不播放歌曲
|
||||
- 触发间隔：1-30秒随机
|
||||
- 提示音文件：`/d/mp3/notification.mp3`（可替换）
|
||||
|
||||
## 战争模式效果（--war）
|
||||
- 每10-20秒随机暂停1-5秒，模拟战斗中随机停火
|
||||
|
||||
## 进程管理
|
||||
- 启动前自动检测并结束旧进程
|
||||
- 日志输出到 `/d/mp3/playlist_war.log`
|
||||
|
||||
## 脚本位置
|
||||
`/d/mp3/playlist_war.py`
|
||||
Executable
+237
@@ -0,0 +1,237 @@
|
||||
# LEARNINGS.md - 进化学习记录
|
||||
|
||||
> 格式：学 → 验证 → 落地 闭环
|
||||
> 每条记录可执行、可验证
|
||||
|
||||
---
|
||||
|
||||
## [LRN-20260331-001] obra/superpowers - Subagent双层Review机制
|
||||
|
||||
**来源**: obra/superpowers (⭐127,519) - skills/subagent-driven-development/SKILL.md
|
||||
|
||||
**原文**:
|
||||
每个任务分3个阶段：
|
||||
1. **Implementer subagent** - 执行实现，自测，commit，自review
|
||||
2. **Spec reviewer subagent** - 验证是否符合规格（先于质量审查）
|
||||
3. **Code quality reviewer subagent** - 验证代码质量
|
||||
|
||||
Review顺序：spec compliance → code quality，绝不能颠倒。
|
||||
|
||||
```dot
|
||||
digraph per_task {
|
||||
"Implementer" -> "Spec Reviewer" -> "Code Quality Reviewer"
|
||||
}
|
||||
```
|
||||
|
||||
模型分级使用：
|
||||
- 机械实现任务（1-2文件，清晰spec）→ 最便宜模型
|
||||
- 集成/判断任务（多文件协调）→ 标准模型
|
||||
- 架构/设计/审查任务 → 最强模型
|
||||
|
||||
**可落地**:
|
||||
在OpenClaw中实现subagent任务分发时，对每个子任务强制执行 spec → quality 两阶段review
|
||||
|
||||
**验证方法**:
|
||||
检查subagent结果是否包含 spec compliance check 和 code quality check 两个独立环节
|
||||
|
||||
---
|
||||
|
||||
## [LRN-20260331-002] obra/superpowers - TDD驱动Skill编写
|
||||
|
||||
**来源**: obra/superpowers skills/writing-skills/SKILL.md
|
||||
|
||||
**原文**:
|
||||
Skill编写 = TDD：
|
||||
- **Test case** = 压力场景 + subagent
|
||||
- **RED**: 跑baseline场景，观察agent如何失败（记录具体rationalizations）
|
||||
- **GREEN**: 写skill后，验证agent是否遵守
|
||||
- **REFACTOR**: 发现新漏洞 → 补上 → 再验证
|
||||
|
||||
```
|
||||
没有看过agent失败，就不知道skill是否有效
|
||||
```
|
||||
|
||||
**可落地**:
|
||||
创建新skill前，先运行一个会失败的场景，记录失败方式，再写skill
|
||||
|
||||
**验证方法**:
|
||||
新旧skill创建流程对比：是否有"先测试失败"这一步
|
||||
|
||||
---
|
||||
|
||||
## [LRN-20260331-003] obra/superpowers - HARD-GATE强制设计确认
|
||||
|
||||
**来源**: obra/superpowers skills/brainstorming/SKILL.md
|
||||
|
||||
**原文**:
|
||||
```markdown
|
||||
<HARD-GATE>
|
||||
Do NOT invoke any implementation skill, write any code,
|
||||
scaffold any project, or take any implementation action
|
||||
until you have presented a design and the user has approved it.
|
||||
</HARD-GATE>
|
||||
```
|
||||
|
||||
每个项目都必须经历设计阶段。"简单"项目更要做设计——这里最容易出现未检验的假设。
|
||||
|
||||
设计文档必须自审：占位符扫描、内部一致性、范围检查、歧义检查
|
||||
|
||||
**可落地**:
|
||||
HARD-GATE已内嵌在SOUL.md中，但可以强化"设计文档必须保存到文件并commit"这一步骤
|
||||
|
||||
**验证方法**:
|
||||
检查每个需要设计的任务是否有对应的 `docs/superpowers/specs/YYYY-MM-DD-*-design.md` 文件
|
||||
|
||||
---
|
||||
|
||||
## [LRN-20260331-004] obra/superpowers - Bite-sized Task粒度
|
||||
|
||||
**来源**: obra/superpowers skills/writing-plans/SKILL.md
|
||||
|
||||
**原文**:
|
||||
每个step是2-5分钟的动作：
|
||||
- "Write the failing test" - step
|
||||
- "Run it to make sure it fails" - step
|
||||
- "Implement the minimal code" - step
|
||||
- "Run tests to make sure they pass" - step
|
||||
- "Commit" - step
|
||||
|
||||
每个任务必须有：
|
||||
- 精确文件路径
|
||||
- 完整代码（包括测试代码）
|
||||
- 精确命令 + 期望输出
|
||||
- 无占位符（无TBD/TODO/"类似Task N"）
|
||||
|
||||
**可落地**:
|
||||
在执行复杂任务时，将步骤分解到2-5分钟粒度，每步有精确命令和期望输出
|
||||
|
||||
**验证方法**:
|
||||
检查plan文件中的步骤是否都包含完整代码块和精确命令
|
||||
|
||||
---
|
||||
|
||||
## [LRN-20260331-005] obra/superpowers - 模型分级节省成本
|
||||
|
||||
**来源**: obra/superpowers skills/subagent-driven-development/SKILL.md
|
||||
|
||||
**原文**:
|
||||
```
|
||||
Mechanical tasks (1-2 files, clear spec) → cheapest model
|
||||
Integration/judgment tasks → standard model
|
||||
Architecture/design/review → most capable model
|
||||
```
|
||||
|
||||
**可落地**:
|
||||
在OpenClaw subagent调度时，根据任务复杂度选择不同能力的模型
|
||||
|
||||
**验证方法**:
|
||||
统计不同任务类型的模型使用分布
|
||||
|
||||
---
|
||||
|
||||
*最后更新: 2026-03-31 23:10*
|
||||
|
||||
---
|
||||
|
||||
## Review闭环记录 [REV-20260331]
|
||||
|
||||
**Review对象**: obra/superpowers (⭐127,519)
|
||||
**Review时间**: 2026-03-31 23:12
|
||||
**Review员**: GitHub进化猎手
|
||||
|
||||
### 检查结果
|
||||
|
||||
**✅ 类似条目已存在**:
|
||||
- 2026-03-29归档中已有superpowers TDD-Skills框架条目
|
||||
- skill-self-evolution-enhancer已有相关learnings
|
||||
|
||||
**✅ 可验证项**:
|
||||
- Subagent双层Review机制 → 可通过检查subagent调用记录验证
|
||||
- 模型分级策略 → 可通过统计模型使用分布验证
|
||||
|
||||
**✅ 落地优先级**:
|
||||
1. **立即可落地**: 双层Review（spec→quality顺序强制）
|
||||
2. **下次创建skill时**: 先运行失败场景再写skill（TDD）
|
||||
3. **长期**: bite-sized task分解规范
|
||||
|
||||
**Review结论**:
|
||||
superpowers是目前最高质量的agent skill framework，127k star实至名归。
|
||||
核心价值：把软件开发最佳实践（TDD、设计优先、小步提交）系统化进skill系统。
|
||||
LEARNINGS 5条全部可操作，建议立即在下一个skill创建任务中验证TDD流程。
|
||||
|
||||
---
|
||||
|
||||
## [LRN-20260401-001] openai/codex - 模块大小硬限制 + codex-core反增长规则
|
||||
|
||||
**来源**: openai/codex (⭐70,921) - AGENTS.md + 代码结构分析
|
||||
|
||||
**原文**:
|
||||
- 目标 Rust 模块 < 500 LoC；超过 ~800 LoC **必须**拆分为新模块
|
||||
- 特别点名高变动文件：`app.rs`, `chat_composer.rs`, `footer.rs`, `chatwidget.rs`, `bottom_pane/mod.rs`
|
||||
- **抵抗往 codex-core 堆代码**：优先考虑其他已有crate，或新建独立crate
|
||||
|
||||
```rust
|
||||
// AGENTS.md 原文
|
||||
// "Over time, the codex-core crate has become bloated because it is the largest
|
||||
// crate, so it is often easier to add something new to codex-core rather than
|
||||
// refactor out the library code you need"
|
||||
//
|
||||
// "To that end: resist adding code to codex-core!"
|
||||
```
|
||||
|
||||
**可落地**:
|
||||
OpenClaw的模块也应遵循类似原则：
|
||||
- 单个脚本/模块 < 500行目标
|
||||
- 核心共享逻辑不应堆在"中央"模块
|
||||
- 定期检查并拆分过大的模块
|
||||
|
||||
**验证方法**:
|
||||
`wc -l` 检查各模块行数，超过800行触发拆分提醒
|
||||
|
||||
---
|
||||
|
||||
## [LRN-20260401-002] openai/codex - TUI Stylize Helpers标准化模式
|
||||
|
||||
**来源**: openai/codex codex-rs/tui - AGENTS.md TUI样式约定
|
||||
|
||||
**原文**:
|
||||
```rust
|
||||
// ✅ 推荐：使用 ratatui Stylize trait
|
||||
"text".into() // 基础span
|
||||
"text".red() // 带颜色
|
||||
"text".dim().bold() // 链式调用
|
||||
|
||||
// vec![...].into() 构建 Line
|
||||
// ❌ 避免：硬编码 .white()，使用默认前景色
|
||||
|
||||
// 文件路径渲染示例（来自AGENTS.md）：
|
||||
vec![" └ ".into(), "M".red(), " ".dim(), "tui/src/app.rs".dim()]
|
||||
```
|
||||
|
||||
**可落地**:
|
||||
OpenClaw TUI/Canvas渲染时，参考此Stylize模式统一颜色和样式使用
|
||||
|
||||
**验证方法**:
|
||||
检查TUI相关代码是否使用了ratatui Stylize helpers而非手动Style构造
|
||||
|
||||
---
|
||||
|
||||
## [LRN-20260401-003] openai/codex - Snapshot Testing + insta
|
||||
|
||||
**来源**: openai/codex codex-rs/tui - AGENTS.md测试约定
|
||||
|
||||
**原文**:
|
||||
- UI变更（文本、渲染输出）必须包含对应 `insta` snapshot覆盖
|
||||
- Snapshot更新流程：
|
||||
```bash
|
||||
cargo test -p codex-tui # 生成更新的snapshots
|
||||
cargo insta pending-snapshots # 查看待接受
|
||||
cargo insta accept -p codex-tui # 接受变更
|
||||
```
|
||||
- 断言使用 `pretty_assertions::assert_eq` 获取清晰diff
|
||||
|
||||
**可落地**:
|
||||
OpenClaw的UI组件可以考虑引入snapshot测试，防止渲染退化
|
||||
|
||||
**验证方法**:
|
||||
UI相关PR是否包含snapshot测试或更新
|
||||
+49
@@ -0,0 +1,49 @@
|
||||
### [LRN-20260401] Claude Code插件系统架构
|
||||
**置信度**: 0.65
|
||||
**来源**: observation
|
||||
**Scope**: global
|
||||
**可落地**: 是
|
||||
**分析日期**: 2026-04-01
|
||||
|
||||
## 核心发现
|
||||
|
||||
分析了 anthropics/claude-code (⭐97,878)，发现其插件系统设计精妙：
|
||||
|
||||
### 1. 插件结构标准化
|
||||
```
|
||||
plugin-name/
|
||||
├── .claude-plugin/plugin.json # 元数据
|
||||
├── commands/ # 斜杠命令
|
||||
├── agents/ # 专业代理
|
||||
├── skills/ # 技能
|
||||
├── hooks/ # 事件钩子
|
||||
└── .mcp.json # 外部工具配置
|
||||
```
|
||||
|
||||
### 2. 五大插件类型
|
||||
| 类型 | 用途 | 示例 |
|
||||
|------|------|------|
|
||||
| commands | 斜杠命令 | /code-review, /commit |
|
||||
| agents | 专业代理 | code-reviewer, code-explorer |
|
||||
| skills | 自动触发技能 | frontend-design |
|
||||
| hooks | 事件钩子 | PreToolUse, SessionStart |
|
||||
| MCP | 外部工具 | 代码检查、数据库等 |
|
||||
|
||||
### 3. 关键实现细节
|
||||
- **Hook系统**: PreToolUse/PostToolUse可以拦截工具调用，甚至支持`defer`延迟执行
|
||||
- **权限决策**: Hook可以返回`{retry: true}`重试或`{updatedInput}`修改输入
|
||||
- **条件过滤**: Hook支持`if`字段用permission rule语法过滤触发条件
|
||||
|
||||
### 4. 对OpenClaw的借鉴价值
|
||||
1. 我们的scripts/目录可以学习这种标准化结构
|
||||
2. verification-loop.sh的6阶段验证模式值得深入研究
|
||||
3. session-observer.sh的自动记录机制已有雏形
|
||||
|
||||
## 验证状态
|
||||
- [x] 代码结构确认
|
||||
- [x] README分析完成
|
||||
- [x] CHANGELOG关键版本分析完成
|
||||
- [ ] 待进一步验证具体实现
|
||||
|
||||
---
|
||||
*观察来源: GitHub Trending Top1, 2026-04-01*
|
||||
+118
@@ -0,0 +1,118 @@
|
||||
### [LRN-20260402] Claude Code 插件系统架构分析
|
||||
|
||||
**置信度**: 0.7
|
||||
**来源**: observation
|
||||
**Scope**: global
|
||||
**可落地**: 高
|
||||
|
||||
---
|
||||
|
||||
## 核心发现
|
||||
|
||||
### 1. Hookify - 自然语言创建Hook规则
|
||||
|
||||
**机制**: 用户说 "warn me when I use rm -rf"，系统自动分析并生成hook配置文件
|
||||
|
||||
**关键文件**:
|
||||
- `hooks/pretooluse.py` - 拦截工具执行
|
||||
- `hooks/userpromptsubmit.py` - 拦截用户提交
|
||||
- `core/rule_engine.py` - 规则引擎
|
||||
- `core/config_loader.py` - 配置加载
|
||||
|
||||
**OpenClaw借鉴**: 可创建类似 `/hookify` 命令，用户描述想要的行为，自动生成对应hook
|
||||
|
||||
**Pattern**:
|
||||
```
|
||||
用户: "当使用 rm -rf 时警告我"
|
||||
系统 → 分析 → 生成 .claude/hookify.rm.local.md
|
||||
```
|
||||
|
||||
### 2. Security Guidance - PreToolUse 9宫格监控
|
||||
|
||||
**监控的9个pattern**:
|
||||
1. Command injection (shell元字符)
|
||||
2. XSS patterns
|
||||
3. eval/exec usage
|
||||
4. Dangerous HTML
|
||||
5. Pickle deserialization
|
||||
6. os.system calls
|
||||
7. SQL injection
|
||||
8. Path traversal
|
||||
9. Hardcoded secrets
|
||||
|
||||
**实现**: `hooks/pretooluse.py` + 正则匹配表
|
||||
|
||||
**OpenClaw借鉴**: 为OpenClaw安全模块增加类似 PreToolUse hook，拦截危险操作
|
||||
|
||||
### 3. Code Review Plugin - 多Agent并行+置信度评分
|
||||
|
||||
**架构**:
|
||||
- 4个并行Agent独立审查 (CLAUDE.md合规 x2, Bug检测, 历史分析)
|
||||
- 每个Issue独立打分 0-100
|
||||
- 阈值80过滤false positive
|
||||
- 只报告≥80分的问题
|
||||
|
||||
**OpenClaw借鉴**:
|
||||
- OpenClaw的 verification-loop.sh 已有6阶段验证
|
||||
- 可增加类似置信度评分机制
|
||||
- 问题分级: 0-50忽略, 50-80警告, 80+阻止
|
||||
|
||||
### 4. Learning Output Style - 交互式学习模式
|
||||
|
||||
**机制**: 在决策点请求用户写5-10行代码，而非全部AI完成
|
||||
|
||||
**触发条件**:
|
||||
- 业务逻辑有多种实现方式时
|
||||
- 错误处理策略选择时
|
||||
- 算法/数据结构决策时
|
||||
|
||||
**不触发**:
|
||||
- 样板代码
|
||||
- 配置/CRUD
|
||||
- 明显实现
|
||||
|
||||
**OpenClaw借鉴**: 可在skill执行时，对关键决策点插入用户确认/参与环节
|
||||
|
||||
---
|
||||
|
||||
## 落地优先级
|
||||
|
||||
| 优先级 | 改进项 | 工作量 | 价值 |
|
||||
|--------|--------|--------|------|
|
||||
| P0 | Hookify式安全拦截 | 中 | 高 |
|
||||
| P1 | 验证循环增加置信度评分 | 低 | 高 |
|
||||
| P2 | 交互式学习模式 | 高 | 中 |
|
||||
|
||||
---
|
||||
|
||||
## 直接可用代码片段
|
||||
|
||||
### 安全拦截Hook模板
|
||||
```python
|
||||
# security-reminder-hook.py 核心逻辑
|
||||
DANGEROUS_PATTERNS = [
|
||||
(r'rm\s+-rf', 'Destructive rm command'),
|
||||
(r'eval\s*\(', 'Dangerous eval usage'),
|
||||
(r'\.format\(.*\$', 'Possible injection'),
|
||||
# ... 9 patterns total
|
||||
]
|
||||
|
||||
def check_command(command: str) -> list[str]:
|
||||
warnings = []
|
||||
for pattern, description in DANGEROUS_PATTERNS:
|
||||
if re.search(pattern, command):
|
||||
warnings.append(f"⚠️ {description}")
|
||||
return warnings
|
||||
```
|
||||
|
||||
### 置信度评分模板
|
||||
```python
|
||||
def score_issue(evidence: dict) -> int:
|
||||
"""0-100 confidence score"""
|
||||
score = 50 # base
|
||||
if evidence.get('explicit_mentioned'): score += 30
|
||||
if evidence.get('high_severity'): score += 20
|
||||
if evidence.get('verified'): score += 20
|
||||
if evidence.get('false_positive_pattern'): score -= 40
|
||||
return min(100, max(0, score))
|
||||
```
|
||||
Executable
+198
@@ -0,0 +1,198 @@
|
||||
|
||||
---
|
||||
|
||||
### [LRN-20260401] obra/superpowers — Agentic Skills Framework架构
|
||||
**置信度**: 0.65
|
||||
**来源**: observation
|
||||
**Scope**: global
|
||||
**可落地**: high
|
||||
**触发**: 复杂任务执行、代码质量把关、团队协作流程
|
||||
|
||||
## 核心洞察（来自⭐128K顶级项目）
|
||||
|
||||
### 1. HARD-GATE设计确认机制（来自brainstorming skill）
|
||||
**原理**: 强制设计审查，不存在"太简单不需要设计"的情况
|
||||
```markdown
|
||||
<HARD-GATE>
|
||||
Do NOT invoke any implementation skill...until you have presented a design and the user has approved it.
|
||||
```
|
||||
**落地**:
|
||||
- 复杂任务先展示设计方案，确认后再执行
|
||||
- 与我现有SOUL.md的HARD-GATE条款完全一致
|
||||
- **新发现**: Anti-Pattern表格专门列出"This Is Too Simple To Need A Design"作为必须避免的错误
|
||||
|
||||
### 2. 两阶段审查模型（来自subagent-driven-development skill）
|
||||
**原理**: 先spec compliance（是否符合规格），后code quality（代码质量），顺序不能乱
|
||||
```dot
|
||||
"Spec reviewer subagent confirms code matches spec?" -> [yes] -> "Code quality reviewer"
|
||||
-> [no] -> "Implementer fixes spec gaps"
|
||||
```
|
||||
**与我的区别**:
|
||||
- 我之前没有区分这两层审查
|
||||
- spec compliance失败不应该进入quality审查
|
||||
- review循环：发现issues → 修复 → re-review，必须完整闭环
|
||||
|
||||
### 3. Subagent状态机（来自subagent-driven-development）
|
||||
```markdown
|
||||
DONE → proceed to spec review
|
||||
DONE_WITH_CONCERNS → read concerns, assess before proceeding
|
||||
NEEDS_CONTEXT → provide missing context, re-dispatch same model
|
||||
BLOCKED → assess blocker type, adjust approach (context/reasoning/size/plan)
|
||||
```
|
||||
**新规则**: Never ignore escalation or force same model retry without changes
|
||||
|
||||
### 4. Session-Start Hook自动技能注入（来自hooks/session-start）
|
||||
**原理**: 新会话启动时自动注入using-superpowers技能内容，不需要手动加载
|
||||
```bash
|
||||
# 平台检测 → 格式适配(Cursor/Claude/Copilot) → JSON输出additionalContext
|
||||
```
|
||||
**OpenClaw对应**: 可考虑在cron任务入口实现类似机制
|
||||
|
||||
### 5. Skills即代码（来自AGENTS.md）
|
||||
**原理**: Skills是影响代理行为的代码，修改需要eval证据
|
||||
```markdown
|
||||
Skills are not prose — they are code that shapes agent behavior.
|
||||
If you modify skill content: show before/after eval results
|
||||
```
|
||||
**对我意味着**: learnings写入skills前需要验证，而非仅凭直觉
|
||||
|
||||
### 6. Red Flags表格化（具体禁止行为）
|
||||
**来源**: subagent-driven-development SKILL.md
|
||||
```markdown
|
||||
Never:
|
||||
- Start implementation on main/master branch without explicit user consent
|
||||
- Skip reviews (spec compliance OR code quality)
|
||||
- Proceed with unfixed issues
|
||||
- Dispatch multiple implementation subagents in parallel
|
||||
- Start code quality review before spec compliance is ✅
|
||||
```
|
||||
**价值**: 将隐性规则显性化，AI可精确遵守
|
||||
|
||||
### 7. 模型选择策略（来自subagent-driven-development）
|
||||
| 任务类型 | 模型选择 | 理由 |
|
||||
|---------|---------|------|
|
||||
| 机械实现（1-2文件，清晰spec） | 最便宜模型 | 节省成本 |
|
||||
| 集成/判断（多文件协调） | 标准模型 | 需要推理 |
|
||||
| 架构/设计/审查 | 最强模型 | 需要最大能力 |
|
||||
|
||||
### 8. 证据优先哲学（来自README.md）
|
||||
```markdown
|
||||
**Evidence over claims** - Verify before declaring success
|
||||
```
|
||||
与我SOUL.md的"准确第二"原则高度一致
|
||||
|
||||
### 9. Subagent驱动开发的真实优势（来自skill文档）
|
||||
**vs. Manual execution:**
|
||||
- Subagents follow TDD naturally
|
||||
- Fresh context per task (no confusion)
|
||||
- Subagent can ask questions (before AND during work)
|
||||
|
||||
**vs. 在同一session执行:**
|
||||
- No file reading overhead (controller provides full text)
|
||||
- Controller curates exactly what context is needed
|
||||
- Questions surfaced before work begins (not after)
|
||||
|
||||
### 10. PR提交护栏（来自AGENTS.md）
|
||||
```markdown
|
||||
This repo has a 94% PR rejection rate.
|
||||
Your job is to protect your human partner from that outcome.
|
||||
```
|
||||
**原理**: AI需要保护人类合作者的声誉，而不是"帮忙"提交低质量PR
|
||||
|
||||
## 与everything-claude-code的关联
|
||||
- ECC提出"三层知识架构"，Superpowers本身就是skills系统的极致实现
|
||||
- Superpowers是ECC冠军作品（Anthropic黑客马拉松），⭐128K验证了其工程价值
|
||||
- brainstorming skill的HARD-GATE与我SOUL.md的HARD-GATE设计高度吻合，印证了这个方向的正确性
|
||||
|
||||
## 待验证落地项
|
||||
1. 在复杂任务中区分spec compliance vs code quality两阶段审查
|
||||
2. 细化subagent状态机的处理逻辑
|
||||
3. 模型选择策略应用到sessions_spawn的model参数
|
||||
|
||||
### [LRN-20260401] obra/superpowers - 技能框架架构
|
||||
**置信度**: 0.7
|
||||
**来源**: observation
|
||||
**Scope**: global
|
||||
**可落地**: 技能自动触发 + 两阶段review + 隔离subagent上下文
|
||||
|
||||
**核心发现**:
|
||||
1. **技能自动触发机制** - 技能在特定上下文自动激活，不需要手动调用
|
||||
2. **两阶段review** - 每个任务先做spec compliance审查，再做code quality审查
|
||||
3. **隔离subagent上下文** - 每个subagent获得精确的上下文，不继承父agent历史
|
||||
4. **TDD强制循环** - RED-GREEN-REFACTOR是强制性流程，不是建议
|
||||
|
||||
**执行流程**:
|
||||
- brainstorming → using-git-worktrees → writing-plans → subagent-driven-development → test-driven-development → requesting-code-review → finishing-a-development-branch
|
||||
|
||||
**关键设计**:
|
||||
- 技能链自动组合，形成完整开发工作流
|
||||
- subagent驱动开发用fresh subagent per task保证隔离性
|
||||
- 保护人类合作者：94% PR拒绝率警示，agent要防止提交垃圾PR
|
||||
|
||||
**对我系统的启发**:
|
||||
OpenClaw的skills可参考"自动触发+链式组合"模式
|
||||
|
||||
### [LRN-20260401-001] obra/superpowers 架构解析
|
||||
**置信度**: 0.75
|
||||
**来源**: observation
|
||||
**Scope**: global
|
||||
**可落地**: 是
|
||||
|
||||
## 核心发现
|
||||
|
||||
### 1. subagent-driven-development 双阶段审查
|
||||
|
||||
superpowers 实现了**两阶段审查流程**:
|
||||
1. **Spec Compliance Review** - 确保代码符合规格
|
||||
2. **Code Quality Review** - 确保代码质量
|
||||
|
||||
**关键洞察**: 先审查合规性，再审查质量。这个顺序不能颠倒。
|
||||
|
||||
### 2. TDD for Skills (Iron Law)
|
||||
|
||||
**核心原则**: "NO SKILL WITHOUT A FAILING TEST FIRST"
|
||||
|
||||
技能创建遵循 TDD 流程:
|
||||
- **RED**: 用 subagent 运行压力测试场景，记录 baseline 行为和 rationalizations
|
||||
- **GREEN**: 编写最小化 skill 解决特定 rationalizations
|
||||
- **REFACTOR**: 关闭 loopholes，添加显式反制
|
||||
|
||||
### 3. Claude Search Optimization (CSO) - 描述陷阱
|
||||
|
||||
**重大发现**: Skill 描述字段只应包含触发条件，**不应该**总结工作流。
|
||||
|
||||
```
|
||||
# ❌ 错误：描述了工作流 - Claude 会走捷径
|
||||
description: Use when executing plans - dispatches subagent per task with code review
|
||||
|
||||
# ✅ 正确：只描述触发条件
|
||||
description: Use when executing implementation plans with independent tasks
|
||||
```
|
||||
|
||||
**原因**: 测试发现当描述总结工作流时，Claude 会按照描述行动而不是读取完整 skill 内容。
|
||||
|
||||
### 4. 模型分级策略
|
||||
|
||||
- **Mechanical tasks** (清晰规格，1-2文件): 用最便宜最快的模型
|
||||
- **Integration/judgment tasks**: 用标准模型
|
||||
- **Architecture/design/review**: 用最强模型
|
||||
|
||||
### 5. 隔离上下文原则
|
||||
|
||||
每个 subagent 应该只收到**精确构造的指令和必要上下文**，不应该继承 controller 的 session 上下文。这避免上下文污染。
|
||||
|
||||
## 对现有系统的改进建议
|
||||
|
||||
### 可立即落地
|
||||
1. **将 subagent-driven-development 的两阶段审查模式**引入 evolution/runner.sh
|
||||
2. **Skill 描述改为仅触发条件格式** - 这是描述字段的正确用法
|
||||
3. **引入 TDD 理念到 skill 自进化** - 先测试再改进
|
||||
|
||||
### 需要验证
|
||||
- 模型分级策略在具体任务中的效果
|
||||
|
||||
## 关键引用
|
||||
- "Your job is to protect your human partner from that outcome" - 强调保护人类伙伴的声誉
|
||||
- "RED-GREEN-REFACTOR for skills" - 技能创建同样是 TDD
|
||||
- "Never start code quality review before spec compliance is ✅" - 顺序至关重要
|
||||
|
||||
Executable
+126
@@ -0,0 +1,126 @@
|
||||
|
||||
### [LRN-20260401] obra/superpowers 核心架构分析
|
||||
**置信度**: 0.65
|
||||
**来源**: observation
|
||||
**Scope**: global
|
||||
**可落地**: 高
|
||||
|
||||
## 核心洞察
|
||||
|
||||
### 1. TDD-Skill创建法（最重要）
|
||||
Skills用TDD方法创建：先跑baseline看agent如何犯错，再写skill文档，最后验证合规。
|
||||
- RED阶段：运行压力场景subagent，记录agent的rationalizations
|
||||
- GREEN阶段：写SKILL.md针对性解决这些rationalizations
|
||||
- REFACTOR：发现新漏洞，补充skill
|
||||
|
||||
### 2. Subagent两阶段审查（不可跳过顺序）
|
||||
**Spec compliance review → Code quality review**（永远是这个顺序）
|
||||
- 先验证是否按spec实现（防止over/under-building）
|
||||
- 再验证代码质量
|
||||
- 永远不能跳过任何一环
|
||||
|
||||
### 3. Model分层策略（成本控制）
|
||||
| 任务类型 | 模型选择 |
|
||||
|---------|---------|
|
||||
| 机械实现（1-2文件，清晰spec） | 最便宜模型 |
|
||||
| 集成/判断（多文件协调） | 标准模型 |
|
||||
| 架构/设计/审查 | 最强模型 |
|
||||
|
||||
### 4. Subagent隔离原则
|
||||
- 每个task用全新subagent
|
||||
- 不继承controller session context
|
||||
- Controller精确构造subagent需要的信息
|
||||
- Subagent可以提问（before AND during work）
|
||||
|
||||
### 5. Skill触发链（工作流编排）
|
||||
```
|
||||
brainstorming → using-git-worktrees → writing-plans → subagent-driven-development → test-driven-development → requesting-code-review → finishing-a-development-branch
|
||||
```
|
||||
每个skill都是mandatory workflow，不是suggestion。
|
||||
|
||||
### 6. 禁止行为（Red Flags）
|
||||
- ❌ 不允许并行dispatch多个implementer subagent
|
||||
- ❌ 不允许跳过任何review
|
||||
- ❌ 不允许在spec compliance未通过前进入code quality review
|
||||
- ❌ 不允许让subagent自己读plan文件（要controller提供完整信息）
|
||||
- ❌ 不允许"差不多就行"（review发现问题=没完成）
|
||||
|
||||
### 7. 状态处理
|
||||
Subagent返回4种状态：DONE/DONE_WITH_CONCERNS/NEEDS_CONTEXT/BLOCKED
|
||||
- NEEDS_CONTEXT: 提供缺失信息后重新dispatch
|
||||
- BLOCKED: 评估原因后选择更强大模型/拆分任务/上报人类
|
||||
|
||||
## 对OpenClaw进化引擎的启发
|
||||
1. **learnings验证循环**：learnings写入前应先"压测"——模拟agent在无此learnings时会怎么犯错
|
||||
2. **Confidence更新机制**：observation → instinct(0.3-0.5) → validated(0.5-0.7) → skill固化(≥0.7)
|
||||
3. **Skill分级**：低置信度放learnings，高置信度固化为正式skill
|
||||
|
||||
---
|
||||
*来源: obra/superpowers (⭐127,819) - agentic skills framework*
|
||||
|
||||
### [LRN-20260401] obra/superpowers 深度分析
|
||||
**置信度**: 0.65
|
||||
**来源**: observation
|
||||
**Scope**: global
|
||||
**可落地**: 部分落地
|
||||
**核心洞察**:
|
||||
|
||||
Superpowers 是一个 **Agentic Skills Framework + 软件开发方法论**，与 everything-claude-code 并列但更成熟：
|
||||
|
||||
1. **Subagent驱动开发**（ECC借鉴来源）
|
||||
- 核心：每个任务派发 fresh subagent + 两阶段 review（spec compliance → code quality）
|
||||
- 与 ECC 的 verification-loop 互补：ECC 专注6阶段验证，Superpowers 专注任务分派+review
|
||||
- 模型分级使用：简单任务用便宜模型，复杂任务用强模型
|
||||
|
||||
2. **TDD铁律**
|
||||
- "NO PRODUCTION CODE WITHOUT A FAILING TEST FIRST"
|
||||
- 违反=删除重写，无例外
|
||||
- 包含完整的RED-GREEN-REFACTOR流程图和常见rationalization反驳
|
||||
|
||||
3. **规划技能**（writing-plans）
|
||||
- 文件结构先于任务分解
|
||||
- 每个step是2-5分钟的原子操作
|
||||
- 规划保存到 `docs/superpowers/plans/YYYY-MM-DD-<feature-name>.md`
|
||||
|
||||
4. **vs ECC**
|
||||
- ECC: 3层知识架构（即兴→直觉→技能）+ 验证循环
|
||||
- Superpowers: Skills触发系统 + Subagent驱动 + TDD铁律
|
||||
- 两者互补：ECC管知识积累，Superpowers管执行流程
|
||||
|
||||
**落地建议**:
|
||||
- OpenClaw 可借鉴 subagent 两阶段 review 模式
|
||||
- TDD 铁律可强化现有验证循环
|
||||
- 规划文件结构对复杂任务有帮助
|
||||
|
||||
**参考价值**: 高 - 项目12.9万星，方法论成熟，覆盖多平台（Claude/Cursor/Codex/OpenCode/Gemini）
|
||||
|
||||
### [LRN-20260402] Claude Code的Hookify模式
|
||||
**置信度**: 0.6
|
||||
**来源**: observation
|
||||
**Scope**: global
|
||||
**可落地**: hookify规则系统可移植到青龙，markdown配置+正则匹配+事件触发，比当前scripts/更灵活
|
||||
**关键洞察**:
|
||||
- 用markdown YAML frontmatter定义规则，无需编辑复杂JSON
|
||||
- 支持多条件组合(AND逻辑)
|
||||
- 事件类型: bash/file/stop/prompt/all
|
||||
- 支持block/warn两种action
|
||||
- conversation-analyzer agent可自动分析会话找问题模式
|
||||
**落地路径**: 在青龙scripts/下创建hookify模块
|
||||
|
||||
---
|
||||
|
||||
### [LRN-20260402] Claude Code多Agent置信度评分模式
|
||||
**置信度**: 0.65
|
||||
**来源**: observation
|
||||
**Scope**: global
|
||||
**可落地**:
|
||||
1. 重要任务用2-3个独立Agent并行验证
|
||||
2. 每条发现打分0-100，低于阈值(如80)过滤
|
||||
3. 低于阈值的发现只记录不报告
|
||||
**关键洞察**:
|
||||
- 避免单一Agent的确认偏差
|
||||
- 独立评分比共识更可靠
|
||||
- 80分阈值过滤大部分噪音
|
||||
- CLAUDE.md合规检查是天然的高置信度规则库
|
||||
**落地路径**: 在verification-loop.sh中集成多Agent独立验证
|
||||
|
||||
+114
@@ -0,0 +1,114 @@
|
||||
|
||||
### [LRN-20260401-01] obra/superpowers - Agentic Skills Framework架构
|
||||
**置信度**: 0.65
|
||||
**来源**: observation
|
||||
**Scope**: global
|
||||
**可落地**: 高
|
||||
|
||||
**核心发现**:
|
||||
|
||||
1. **验证铁律（Verification Iron Law）**
|
||||
- "NO COMPLETION CLAIMS WITHOUT FRESH VERIFICATION EVIDENCE"
|
||||
- 任何成功声明前必须: 识别证明命令 → 执行 → 读取输出 → 验证
|
||||
- 与我们的verification-loop.sh完全对齐，但更严格
|
||||
|
||||
2. **Subagent双阶段审查模式**
|
||||
- 每次任务分派fresh subagent → spec compliance review → code quality review
|
||||
- 不信任agent自我报告，必须独立验证
|
||||
- 关键洞察: 先做spec compliance检查，再做code quality检查（顺序不能反）
|
||||
|
||||
3. **Model Tiering（模型分级使用）**
|
||||
- 机械实现任务(1-2文件，清晰spec) → 便宜快速模型
|
||||
- 集成/判断任务(多文件协调) → 标准模型
|
||||
- 架构/设计/审查任务 → 最高能力模型
|
||||
- 节省成本 + 加快速度
|
||||
|
||||
4. **并行调查模式**
|
||||
- 多个独立失败 → 一个agent per problem domain并行调查
|
||||
- 关键判断: failures是否独立(不相关可并)/ related(串行)
|
||||
- 避免shared state冲突
|
||||
|
||||
**与现有模块的关系**:
|
||||
- ✅ verification-loop.sh 已实现铁律概念（但superpowers更严格）
|
||||
- ✅ learnings-with-confidence.sh 已有置信度系统
|
||||
- ❌ subagent-driven workflow 未独立实现（可整合）
|
||||
|
||||
**可落地行动**:
|
||||
1. 将verification-loop.sh的"Build→Type→Lint→Test→Security→Diff"改为"Evidence→Claim"铁律模式
|
||||
2. 添加model tiering注释到subagent任务模板
|
||||
3. 为dispatching-parallel-agents模式添加快速判断流程
|
||||
|
||||
### [LRN-20260401-001] obra/superpowers 核心架构借鉴
|
||||
**置信度**: 0.7
|
||||
**来源**: observation
|
||||
**Scope**: global
|
||||
**可落地**: 是
|
||||
|
||||
## 核心发现
|
||||
|
||||
### 1. Skills 的 TDD 法则（Iron Law）
|
||||
```
|
||||
NO SKILL WITHOUT A FAILING TEST FIRST
|
||||
```
|
||||
Skills 是"流程文档的测试驱动开发"。创建 skill 前必须先运行压力场景看 agent 如何失败，然后才写 skill 约束行为。
|
||||
|
||||
### 2. 两阶段 Review 顺序
|
||||
- **第一阶段**: Spec compliance（是否符合规范）
|
||||
- **第二阶段**: Code quality（代码质量）
|
||||
顺序不能颠倒！
|
||||
|
||||
### 3. Claude Search Optimization (CSO) 陷阱
|
||||
- Description 只能写"触发条件"，不能写"工作流摘要"
|
||||
- ❌ `description: "执行计划 - 分配 subagent 每个任务 + 代码审查"`
|
||||
- ✅ `description: "Use when executing implementation plans with independent tasks in the current session"`
|
||||
- 原因：Description 总结 workflow 会让 Claude 走捷径，跳过完整 skill 内容
|
||||
|
||||
### 4. 预阻 Rationalization
|
||||
Discipline 类 skill（如 TDD）必须包含：
|
||||
- Rationalization Table（借口表格）
|
||||
- Red Flags List（红旗列表）
|
||||
- 明确禁止的变通方案
|
||||
|
||||
### 5. Model Selection by Task Complexity
|
||||
| 任务类型 | 模型选择 |
|
||||
|---------|---------|
|
||||
| 机械实现（1-2 文件，清晰 spec）| 最便宜模型 |
|
||||
| 集成/判断（多文件）| 标准模型 |
|
||||
| 架构/设计/审查 | 最强模型 |
|
||||
|
||||
## 对 OpenClaw 的落地建议
|
||||
1. **skill-self-evolution-enhancer** 更新：增加 rationalization table 和 red flags
|
||||
2. **learnings 管理**：引入 TDD 测试循环
|
||||
3. **验证循环**：改用两阶段（spec → quality）
|
||||
|
||||
---
|
||||
|
||||
## 📊 本次进化分析报告（2026-04-01）
|
||||
|
||||
**分析项目**: obra/superpowers (⭐128,712)
|
||||
**分析深度**: README + 关键 Skills 源码
|
||||
|
||||
### 学到的核心内容
|
||||
|
||||
1. **Skills 的 TDD 法则**（高价值）
|
||||
- 写 skill 前必须先"看 agent 失败"
|
||||
- RED: 运行压力场景记录 baseline
|
||||
- GREEN: 写 skill 约束行为
|
||||
- REFACTOR: 堵住 rationalization 漏洞
|
||||
|
||||
2. **两阶段 Review 顺序**（可直接落地）
|
||||
- 第一阶段：Spec compliance（是否符合规范）
|
||||
- 第二阶段：Code quality（代码质量）
|
||||
- 顺序固定，不能颠倒
|
||||
|
||||
3. **CSO Description 陷阱**（高频踩坑）
|
||||
- Description 只写"触发条件"
|
||||
- 禁止写"工作流摘要"（会让 Claude 跳过正文）
|
||||
|
||||
4. **预阻 Rationalization**（Skill 必做）
|
||||
- Rationalization Table（借口表格）
|
||||
- Red Flags List（红旗列表）
|
||||
|
||||
### 置信度评估
|
||||
- **整体置信度**: 0.7（基于源码精读 + ECC 架构印证）
|
||||
- **可落地性**: 高（多个模式可直接迁移到 OpenClaw skills）
|
||||
+4
@@ -0,0 +1,4 @@
|
||||
## 2026-04-02 13:25 | observer-20260402-1306.log
|
||||
### 内容
|
||||
[2026-04-02 13:06]
|
||||
|
||||
+8
@@ -0,0 +1,8 @@
|
||||
## 规则提取结果 - 2026-04-02 13:06
|
||||
|
||||
| 类型 | 值 | 置信度 |
|
||||
|------|-----|--------|
|
||||
| activity | 优化需要持续跟踪最新算法变化 | 0.68 |
|
||||
|
||||
**原始文本**: SEO优化需要持续跟踪最新算法变化...
|
||||
---
|
||||
+4
@@ -0,0 +1,4 @@
|
||||
# L1片段汇总 - 2026-04-02 13:25
|
||||
|
||||
## 学习点提取
|
||||
|
||||
@@ -0,0 +1,19 @@
|
||||
# 全局Learnings汇总
|
||||
|
||||
## 2026-04-02 吸收总结
|
||||
|
||||
### 来自风筝的高价值技能
|
||||
1. github-trending-browser.py - GitHub情报系统
|
||||
2. evolution-*.sh - 进化引擎系列
|
||||
3. auto-consolidator.sh - 自动整合器
|
||||
|
||||
### 关键洞察
|
||||
- Claude Code插件系统安全钩子机制
|
||||
- 两阶段审查模型(Spec→Quality)
|
||||
- Subagent状态机设计
|
||||
|
||||
### 待学习目标
|
||||
- f/prompts.chat - Prompt最佳实践
|
||||
- anthropics/claude-code - Agentic开发框架
|
||||
- openai/codex - 轻量级Coding Agent
|
||||
|
||||
@@ -0,0 +1,49 @@
|
||||
---
|
||||
name: web-access
|
||||
description: 联网工具自动选择 + 站点经验积累。根据场景自主选择最优抓取方式，支持 Jina Reader、curl、web_search，并记住站点特征。
|
||||
---
|
||||
|
||||
# web-access - 站点经验积累
|
||||
|
||||
## 工具选择策略
|
||||
|
||||
```
|
||||
1. 简单页面 → curl 直接抓
|
||||
2. 动态页面(JS渲染) → Jina Reader
|
||||
3. 搜索 → web_search
|
||||
4. 已知站点 → 加载站点经验，选择最优方式
|
||||
```
|
||||
|
||||
## 工具脚本
|
||||
|
||||
| 工具 | 路径 |
|
||||
|------|------|
|
||||
| Jina Reader | /root/.openclaw/scripts/jina-reader.sh |
|
||||
| 站点经验 | /root/.openclaw/scripts/site-experience.sh |
|
||||
|
||||
## 自主进化规则
|
||||
|
||||
### 触发条件
|
||||
|
||||
| 场景 | 条件 | 动作 |
|
||||
|------|------|------|
|
||||
| 反爬 | curl 返回空白/403/重定向 | 切换 Jina，保存经验 |
|
||||
| JS渲染 | 页面内容与源码不符 | 记录使用 Jina |
|
||||
| 成功抓取 | 某种方式成功 | 保存站点经验 |
|
||||
|
||||
### 用法
|
||||
|
||||
```bash
|
||||
# 添加站点经验
|
||||
bash /root/.openclaw/scripts/site-experience.sh add "example.com" "需要Jina Reader"
|
||||
|
||||
# 获取站点经验
|
||||
bash /root/.openclaw/scripts/site-experience.sh get "example.com"
|
||||
|
||||
# 列出所有经验
|
||||
bash /root/.openclaw/scripts/site-experience.sh list
|
||||
```
|
||||
|
||||
## 站点经验存储
|
||||
|
||||
路径: /root/.openclaw/memory/06-site-experience/
|
||||
@@ -0,0 +1,245 @@
|
||||
---
|
||||
name: x-tweet-fetcher
|
||||
description: >
|
||||
Fetch tweets, replies, and user timelines from X/Twitter without login or API keys.
|
||||
Also supports Chinese platforms (Weibo, Bilibili, CSDN, WeChat).
|
||||
Includes camofox_search() for zero-cost Google search without API keys.
|
||||
Basic tweet fetching: zero dependencies. Replies/timelines/search: requires Camofox.
|
||||
---
|
||||
|
||||
# X Tweet Fetcher
|
||||
|
||||
Fetch tweets from X/Twitter without authentication. Supports tweet content, reply threads, user timelines, and Chinese platforms.
|
||||
|
||||
## Feature Overview
|
||||
|
||||
| Feature | Command | Dependencies |
|
||||
|---------|---------|-------------|
|
||||
| Single tweet | `--url <tweet_url>` | None (zero deps) |
|
||||
| Reply threads | `--url <tweet_url> --replies` | **Camofox** |
|
||||
| User timeline | `--user <username> --limit 300` | **Camofox** |
|
||||
| Chinese platforms | `fetch_china.py --url <url>` | **Camofox** (except WeChat) |
|
||||
| Google search | `camofox_search("query")` | **Camofox** |
|
||||
|
||||
---
|
||||
|
||||
## Basic Usage (Zero Dependencies)
|
||||
|
||||
### Fetch a Single Tweet
|
||||
|
||||
```bash
|
||||
# JSON output
|
||||
python3 scripts/fetch_tweet.py --url "https://x.com/user/status/123456"
|
||||
|
||||
# Text only (human readable)
|
||||
python3 scripts/fetch_tweet.py --url "https://x.com/user/status/123456" --text-only
|
||||
|
||||
# Pretty JSON
|
||||
python3 scripts/fetch_tweet.py --url "https://x.com/user/status/123456" --pretty
|
||||
```
|
||||
|
||||
### What It Fetches
|
||||
|
||||
| Content Type | Support |
|
||||
|-------------|---------|
|
||||
| Regular tweets | ✅ Full text + stats |
|
||||
| Long tweets (Twitter Blue) | ✅ Full text |
|
||||
| X Articles (long-form) | ✅ Complete article text |
|
||||
| Quoted tweets | ✅ Included |
|
||||
| Stats (likes/RT/views) | ✅ Included |
|
||||
| Media URLs | ✅ Images + videos |
|
||||
|
||||
---
|
||||
|
||||
## Advanced Features (Requires Camofox)
|
||||
|
||||
> ⚠️ The following features require **Camofox** browser service running on `localhost:9377`.
|
||||
> See [Camofox Setup](#camofox-setup) below.
|
||||
|
||||
### Fetch Reply Threads
|
||||
|
||||
```bash
|
||||
# Fetch tweet + all replies (including nested replies)
|
||||
python3 scripts/fetch_tweet.py --url "https://x.com/user/status/123456" --replies
|
||||
|
||||
# Text-only mode with replies
|
||||
python3 scripts/fetch_tweet.py --url "https://x.com/user/status/123456" --replies --text-only
|
||||
```
|
||||
|
||||
### Fetch User Timeline
|
||||
|
||||
```bash
|
||||
# Fetch latest tweets from a user (supports pagination, MAX_PAGES=20)
|
||||
python3 scripts/fetch_tweet.py --user <username> --limit 300
|
||||
```
|
||||
|
||||
### Fetch Chinese Platform Content
|
||||
|
||||
```bash
|
||||
# Auto-detects platform from URL
|
||||
python3 scripts/fetch_china.py --url "https://weibo.com/..." # Weibo
|
||||
python3 scripts/fetch_china.py --url "https://bilibili.com/..." # Bilibili
|
||||
python3 scripts/fetch_china.py --url "https://csdn.net/..." # CSDN
|
||||
python3 scripts/fetch_china.py --url "https://mp.weixin.qq.com/..." # WeChat (no Camofox needed!)
|
||||
```
|
||||
|
||||
| Platform | Status | Notes |
|
||||
|----------|--------|-------|
|
||||
| WeChat Articles | ✅ | Uses web_fetch directly, no Camofox |
|
||||
| Weibo | ✅ | Camofox renders JS |
|
||||
| Bilibili | ✅ | Video info + stats |
|
||||
| CSDN | ✅ | Articles + code blocks |
|
||||
| Zhihu / Xiaohongshu | ⚠️ | Needs cookie import for login |
|
||||
|
||||
### Google Search (Zero API Key)
|
||||
|
||||
```python
|
||||
# Python
|
||||
from scripts.camofox_client import camofox_search
|
||||
results = camofox_search("your search query")
|
||||
# Returns: [{"title": "...", "url": "...", "snippet": "..."}, ...]
|
||||
```
|
||||
|
||||
```bash
|
||||
# CLI
|
||||
python3 scripts/camofox_client.py "your search query"
|
||||
```
|
||||
|
||||
Uses Camofox browser to search Google directly. **No Brave API key needed, no cost.**
|
||||
|
||||
---
|
||||
|
||||
## Camofox Setup
|
||||
|
||||
### What is Camofox?
|
||||
|
||||
Camofox is an anti-detection browser service based on [Camoufox](https://camoufox.com) (a Firefox fork with C++ level fingerprint masking). It bypasses:
|
||||
- Cloudflare bot detection
|
||||
- Browser fingerprinting
|
||||
- JavaScript challenges
|
||||
|
||||
### Installation
|
||||
|
||||
**Option 1: OpenClaw Plugin**
|
||||
|
||||
```bash
|
||||
openclaw plugins install @askjo/camofox-browser
|
||||
```
|
||||
|
||||
**Option 2: Manual Install**
|
||||
|
||||
```bash
|
||||
git clone https://github.com/jo-inc/camofox-browser
|
||||
cd camofox-browser
|
||||
npm install && npm start
|
||||
```
|
||||
|
||||
### Verify
|
||||
|
||||
```bash
|
||||
curl http://localhost:9377/health
|
||||
# Should return: {"status":"ok"}
|
||||
```
|
||||
|
||||
### REST API
|
||||
|
||||
```bash
|
||||
# Create tab
|
||||
POST http://localhost:9377/tabs
|
||||
Body: {"userId":"test", "sessionKey":"test", "url":"https://example.com"}
|
||||
|
||||
# Get page snapshot
|
||||
GET http://localhost:9377/tabs/<TAB_ID>/snapshot?userId=test
|
||||
|
||||
# Close tab
|
||||
DELETE http://localhost:9377/tabs/<TAB_ID>?userId=test
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## From Agent Code
|
||||
|
||||
```python
|
||||
from scripts.fetch_tweet import fetch_tweet
|
||||
|
||||
result = fetch_tweet("https://x.com/user/status/123456")
|
||||
tweet = result["tweet"]
|
||||
|
||||
# Regular tweet
|
||||
print(tweet["text"])
|
||||
print(f"Likes: {tweet['likes']}, Views: {tweet['views']}")
|
||||
|
||||
# X Article (long-form)
|
||||
if tweet.get("is_article"):
|
||||
print(tweet["article"]["title"])
|
||||
print(tweet["article"]["full_text"])
|
||||
|
||||
# Links found in replies
|
||||
for reply in result.get("replies", []):
|
||||
for link in reply.get("links", []):
|
||||
print(link)
|
||||
```
|
||||
|
||||
## Output Format
|
||||
|
||||
```json
|
||||
{
|
||||
"url": "https://x.com/user/status/123",
|
||||
"username": "user",
|
||||
"tweet_id": "123",
|
||||
"tweet": {
|
||||
"text": "Tweet content...",
|
||||
"author": "Display Name",
|
||||
"screen_name": "username",
|
||||
"likes": 100,
|
||||
"retweets": 50,
|
||||
"bookmarks": 25,
|
||||
"views": 10000,
|
||||
"replies_count": 30,
|
||||
"created_at": "Mon Jan 01 12:00:00 +0000 2026",
|
||||
"is_note_tweet": false,
|
||||
"is_article": true,
|
||||
"article": {
|
||||
"title": "Article Title",
|
||||
"full_text": "Complete article content...",
|
||||
"word_count": 4847
|
||||
}
|
||||
},
|
||||
"replies": [
|
||||
{
|
||||
"author": "@someone",
|
||||
"text": "Reply text...",
|
||||
"likes": 5,
|
||||
"links": ["https://github.com/..."],
|
||||
"thread_replies": [{"text": "Nested reply..."}]
|
||||
}
|
||||
]
|
||||
}
|
||||
```
|
||||
|
||||
## File Structure
|
||||
|
||||
```
|
||||
x-tweet-fetcher/
|
||||
├── SKILL.md # This file
|
||||
├── README.md # GitHub page with full docs
|
||||
├── scripts/
|
||||
│ ├── fetch_tweet.py # Main fetcher (tweet + replies + timeline)
|
||||
│ ├── fetch_china.py # Chinese platform fetcher
|
||||
│ ├── camofox_client.py # Camofox REST API client + camofox_search()
|
||||
│ └── x-profile-analyzer.py # User profile analysis (AI-powered)
|
||||
└── CHANGELOG.md
|
||||
```
|
||||
|
||||
## Requirements
|
||||
|
||||
- **Basic**: Python 3.7+, no external packages, no API keys
|
||||
- **Advanced**: Camofox running on localhost:9377
|
||||
- **Profile Analyzer**: MiniMax M2.5 API key (for AI analysis)
|
||||
|
||||
## How It Works
|
||||
|
||||
- **Basic tweets**: [FxTwitter](https://github.com/FxEmbed/FxEmbed) public API
|
||||
- **Replies/timelines**: Camofox → Nitter (privacy-respecting X frontend)
|
||||
- **Chinese platforms**: Camofox renders JS → extracts content
|
||||
- **Google search**: Camofox opens Google → parses results
|
||||
Reference in new issue
Block a user