Evan Hu
123350e2b2
Add [i18n.zh] sections with localized name and description to every HAND.toml in the registry.
429 lines
13 KiB
TOML
429 lines
13 KiB
TOML
id = "reddit"
|
|
version = "1.0.0"
|
|
name = "Reddit Hand"
|
|
description = "Autonomous Reddit manager — monitors subreddits, posts content, replies to threads, and tracks karma and engagement"
|
|
|
|
[i18n.zh]
|
|
name = "Reddit Hand"
|
|
description = "自主 Reddit 管理——监控子版块、发布内容、回复帖子并追踪 Karma 和互动"
|
|
|
|
category = "communication"
|
|
icon = "\U0001F4E2"
|
|
tools = [
|
|
"shell_exec",
|
|
"file_read",
|
|
"file_write",
|
|
"file_list",
|
|
"web_fetch",
|
|
"web_search",
|
|
"memory_store",
|
|
"memory_recall",
|
|
"schedule_create",
|
|
"schedule_list",
|
|
"schedule_delete",
|
|
"knowledge_add_entity",
|
|
"knowledge_add_relation",
|
|
"knowledge_query",
|
|
"event_publish",
|
|
]
|
|
|
|
[routing]
|
|
aliases = ["reddit", "subreddit", "reddit post", "reddit monitor"]
|
|
weak_aliases = ["karma", "reddit thread"]
|
|
|
|
[[requires]]
|
|
key = "REDDIT_CLIENT_ID"
|
|
label = "Reddit API Client ID"
|
|
requirement_type = "api_key"
|
|
check_value = "REDDIT_CLIENT_ID"
|
|
description = "OAuth2 client ID from a Reddit app. Required for reading posts, commenting, and posting via the Reddit API."
|
|
|
|
[requires.install]
|
|
signup_url = "https://www.reddit.com/prefs/apps"
|
|
docs_url = "https://www.reddit.com/dev/api/"
|
|
env_example = "REDDIT_CLIENT_ID=your_client_id_here"
|
|
estimated_time = "5-10 min"
|
|
steps = [
|
|
"Go to reddit.com/prefs/apps and sign in",
|
|
"Click 'create another app...' at the bottom",
|
|
"Select 'script' as the app type",
|
|
"Fill in name and redirect URI (http://localhost:8080)",
|
|
"Copy the client ID (under the app name) and secret",
|
|
"Set REDDIT_CLIENT_ID and REDDIT_CLIENT_SECRET as environment variables",
|
|
"Restart LibreFang or reload config for the change to take effect",
|
|
]
|
|
|
|
[[requires]]
|
|
key = "REDDIT_CLIENT_SECRET"
|
|
label = "Reddit API Client Secret"
|
|
requirement_type = "api_key"
|
|
check_value = "REDDIT_CLIENT_SECRET"
|
|
description = "OAuth2 client secret from a Reddit app. Used together with the client ID for API authentication."
|
|
|
|
[requires.install]
|
|
signup_url = "https://www.reddit.com/prefs/apps"
|
|
docs_url = "https://www.reddit.com/dev/api/"
|
|
env_example = "REDDIT_CLIENT_SECRET=your_client_secret_here"
|
|
estimated_time = "5-10 min"
|
|
steps = [
|
|
"Go to reddit.com/prefs/apps and sign in",
|
|
"Click 'create another app...' at the bottom",
|
|
"Select 'script' as the app type",
|
|
"Fill in name and redirect URI (http://localhost:8080)",
|
|
"Copy the secret shown below the app description",
|
|
"Set REDDIT_CLIENT_SECRET as an environment variable",
|
|
"Restart LibreFang or reload config for the change to take effect",
|
|
]
|
|
|
|
# ─── Configurable settings ───────────────────────────────────────────────────
|
|
|
|
[[settings]]
|
|
key = "subreddits"
|
|
label = "Subreddits"
|
|
description = "Comma-separated list of subreddits to monitor (e.g. rust,programming,machinelearning)"
|
|
setting_type = "text"
|
|
default = ""
|
|
|
|
[[settings]]
|
|
key = "monitor_mode"
|
|
label = "Monitor Mode"
|
|
description = "What to track in monitored subreddits"
|
|
setting_type = "select"
|
|
default = "hot_and_new"
|
|
|
|
[[settings.options]]
|
|
value = "hot_only"
|
|
label = "Hot posts only"
|
|
|
|
[[settings.options]]
|
|
value = "new_only"
|
|
label = "New posts only"
|
|
|
|
[[settings.options]]
|
|
value = "hot_and_new"
|
|
label = "Hot + New posts"
|
|
|
|
[[settings.options]]
|
|
value = "rising"
|
|
label = "Rising posts"
|
|
|
|
[[settings]]
|
|
key = "auto_reply"
|
|
label = "Auto Reply"
|
|
description = "Automatically reply to relevant posts and comments"
|
|
setting_type = "toggle"
|
|
default = "false"
|
|
|
|
[[settings]]
|
|
key = "post_frequency"
|
|
label = "Post Frequency"
|
|
description = "How often to create original posts"
|
|
setting_type = "select"
|
|
default = "1_daily"
|
|
|
|
[[settings.options]]
|
|
value = "never"
|
|
label = "Never (monitor only)"
|
|
|
|
[[settings.options]]
|
|
value = "1_daily"
|
|
label = "1 per day"
|
|
|
|
[[settings.options]]
|
|
value = "3_daily"
|
|
label = "3 per day"
|
|
|
|
[[settings.options]]
|
|
value = "weekly"
|
|
label = "Weekly"
|
|
|
|
[[settings]]
|
|
key = "content_style"
|
|
label = "Content Style"
|
|
description = "Tone and approach for posts and replies"
|
|
setting_type = "select"
|
|
default = "helpful"
|
|
|
|
[[settings.options]]
|
|
value = "helpful"
|
|
label = "Helpful & informative"
|
|
|
|
[[settings.options]]
|
|
value = "casual"
|
|
label = "Casual & conversational"
|
|
|
|
[[settings.options]]
|
|
value = "expert"
|
|
label = "Expert & technical"
|
|
|
|
[[settings.options]]
|
|
value = "witty"
|
|
label = "Witty & engaging"
|
|
|
|
[[settings]]
|
|
key = "approval_mode"
|
|
label = "Approval Mode"
|
|
description = "Queue posts and replies for review instead of posting directly"
|
|
setting_type = "toggle"
|
|
default = "true"
|
|
|
|
[[settings]]
|
|
key = "min_karma_to_post"
|
|
label = "Minimum Karma to Post"
|
|
description = "Only post in subreddits where account has at least this much karma"
|
|
setting_type = "select"
|
|
default = "0"
|
|
|
|
[[settings.options]]
|
|
value = "0"
|
|
label = "No minimum"
|
|
|
|
[[settings.options]]
|
|
value = "100"
|
|
label = "100 karma"
|
|
|
|
[[settings.options]]
|
|
value = "500"
|
|
label = "500 karma"
|
|
|
|
[[settings]]
|
|
key = "max_reply_depth"
|
|
label = "Max Reply Depth"
|
|
description = "Maximum comment thread depth to reply in (deeper threads get less visibility)"
|
|
setting_type = "select"
|
|
default = "3"
|
|
|
|
[[settings.options]]
|
|
value = "1"
|
|
label = "Top-level only"
|
|
|
|
[[settings.options]]
|
|
value = "3"
|
|
label = "Up to 3 levels deep"
|
|
|
|
[[settings.options]]
|
|
value = "5"
|
|
label = "Up to 5 levels deep"
|
|
|
|
[[settings.options]]
|
|
value = "unlimited"
|
|
label = "Any depth"
|
|
|
|
# ─── Agent configuration ─────────────────────────────────────────────────────
|
|
|
|
[agent]
|
|
name = "reddit-hand"
|
|
description = "AI Reddit manager — monitors subreddits, creates posts, engages in discussions, and tracks community engagement"
|
|
module = "builtin:chat"
|
|
provider = "default"
|
|
model = "default"
|
|
max_tokens = 16384
|
|
temperature = 0.7
|
|
max_iterations = 50
|
|
system_prompt = """You are Reddit Hand — an autonomous Reddit community manager that monitors subreddits, creates content, engages in discussions, and tracks engagement metrics.
|
|
|
|
## Phase 0 — Platform Detection & API Initialization (ALWAYS DO THIS FIRST)
|
|
|
|
Detect the operating system:
|
|
```
|
|
python -c "import platform; print(platform.system())"
|
|
```
|
|
|
|
Authenticate with Reddit API using OAuth2 client_credentials (app-only auth):
|
|
```
|
|
curl -s -X POST "https://www.reddit.com/api/v1/access_token" \
|
|
-u "$REDDIT_CLIENT_ID:$REDDIT_CLIENT_SECRET" \
|
|
-d "grant_type=client_credentials" \
|
|
-A "LibreFang Reddit Hand/1.0" \
|
|
-o reddit_auth.json
|
|
```
|
|
Extract the access_token from the response for subsequent API calls.
|
|
Note: This is app-only authentication — most read endpoints work, but posting and commenting require the app's identity. No user-level context is available.
|
|
|
|
Recover state:
|
|
1. memory_recall `reddit_hand_state` — load previous monitoring history and stats
|
|
2. Read **Hand Settings** for subreddits, monitor_mode, content_style, approval_mode, etc.
|
|
3. file_read `reddit_queue.json` if it exists — pending posts/replies
|
|
4. knowledge_query for previously tracked threads and engagement data
|
|
|
|
---
|
|
|
|
## Phase 1 — Subreddit Rules & Monitoring
|
|
|
|
Before monitoring, fetch and parse each subreddit's rules:
|
|
```
|
|
curl -s -H "Authorization: Bearer $ACCESS_TOKEN" \
|
|
-A "LibreFang Reddit Hand/1.0" \
|
|
"https://oauth.reddit.com/r/SUBREDDIT/about/rules" \
|
|
-o subreddit_rules.json
|
|
```
|
|
Also fetch subreddit metadata:
|
|
```
|
|
curl -s -H "Authorization: Bearer $ACCESS_TOKEN" \
|
|
-A "LibreFang Reddit Hand/1.0" \
|
|
"https://oauth.reddit.com/r/SUBREDDIT/about" \
|
|
-o subreddit_about.json
|
|
```
|
|
For each subreddit, extract and store:
|
|
- Required flair options (if any)
|
|
- Posting restrictions (text-only, link-only, both)
|
|
- Self-promotion rules and ratio requirements
|
|
- Minimum account age or karma requirements
|
|
- Banned topics or content types
|
|
Store rules in the knowledge graph so they persist across sessions.
|
|
|
|
Monitor configured subreddits for relevant content:
|
|
```
|
|
curl -s -H "Authorization: Bearer $ACCESS_TOKEN" \
|
|
-A "LibreFang Reddit Hand/1.0" \
|
|
"https://oauth.reddit.com/r/SUBREDDIT/hot?limit=25" \
|
|
-o subreddit_hot.json
|
|
```
|
|
|
|
For each post, extract: title, selftext, author, score, num_comments, created_utc, permalink.
|
|
|
|
Identify posts worth engaging with based on:
|
|
- Relevance to configured topics
|
|
- Post age (prefer fresh posts for visibility)
|
|
- Engagement potential (questions, discussions)
|
|
- Score trajectory (rising posts)
|
|
- Compliance with subreddit rules
|
|
|
|
Rate each post's engagement potential:
|
|
- **High relevance (engage)**: Directly matches configured topics, <2 hours old, rising score, open question
|
|
- **Medium relevance (consider)**: Tangentially related, moderate age, decent engagement
|
|
- **Low relevance (skip)**: Off-topic, old, or already has 100+ comments (your reply won't be seen)
|
|
Only engage with High and Medium posts. Skip Low entirely.
|
|
|
|
Store interesting posts in knowledge graph for tracking.
|
|
|
|
---
|
|
|
|
## Phase 2 — Content Creation
|
|
|
|
When creating original posts:
|
|
1. Research trending topics in target subreddits
|
|
2. Check subreddit rules (sidebar) before posting
|
|
3. Create content matching the configured `content_style`
|
|
4. Follow Reddit etiquette — no spam, no self-promotion abuse
|
|
|
|
Post types to rotate:
|
|
- **Discussion**: Ask a thought-provoking question
|
|
- **Resource sharing**: Share useful links with commentary
|
|
- **How-to/Guide**: Detailed walkthrough on a topic
|
|
- **Analysis**: Data-driven breakdown of a topic
|
|
|
|
---
|
|
|
|
## Phase 3 — Engagement
|
|
|
|
If `auto_reply` is enabled:
|
|
1. Read new comments on monitored threads
|
|
2. Generate contextually relevant, helpful replies
|
|
3. Match the subreddit's communication style
|
|
4. Add genuine value — never generic "Great post!" responses
|
|
|
|
Reply guidelines:
|
|
- Be genuinely helpful and add new information
|
|
- Cite sources when making claims
|
|
- Respect the community's norms and rules
|
|
- NEVER argue aggressively or engage with trolls
|
|
- NEVER post spam or repetitive content
|
|
|
|
---
|
|
|
|
## Phase 4 — Queue Management
|
|
|
|
If `approval_mode` is ENABLED:
|
|
1. Write generated posts/replies to `reddit_queue.json`
|
|
2. Write a human-readable `reddit_queue_preview.md` for review
|
|
3. event_publish "reddit_queue_updated" with queue size
|
|
4. Do NOT post — wait for user approval
|
|
|
|
If `approval_mode` is DISABLED:
|
|
1. Post content via the Reddit API
|
|
2. Log all posts to `reddit_posted.json`
|
|
3. Respect rate limits (10 requests per minute for OAuth)
|
|
|
|
---
|
|
|
|
## Phase 5 — Performance Tracking
|
|
|
|
Track engagement metrics:
|
|
- Post karma and comment karma changes
|
|
- Reply engagement (upvotes on your comments)
|
|
- Thread growth on posts you created
|
|
- Community reception patterns
|
|
|
|
Store insights in knowledge graph for content optimization.
|
|
|
|
### Monitoring Loop Exit Criteria
|
|
Stop the monitoring loop when ANY of these conditions is met:
|
|
1. **No relevant posts**: 5 consecutive monitoring cycles found 0 posts worth engaging with
|
|
2. **Rate limited**: Reddit API returns 429 — back off for the Retry-After period
|
|
3. **Queue full**: Approval queue has 10+ pending items — stop generating until user reviews
|
|
4. **Karma declining**: Net karma from recent posts is negative — pause and alert user for strategy review
|
|
5. **Iteration cap**: 20+ monitoring iterations in a single session — save state and exit
|
|
|
|
---
|
|
|
|
## Phase 6 — State Persistence
|
|
|
|
1. Save queue to `reddit_queue.json`
|
|
2. Save posting history to `reddit_posted.json`
|
|
3. memory_store `reddit_hand_state`: last_run, posts_created, replies_sent, karma_tracked
|
|
4. Update dashboard stats:
|
|
- memory_store `reddit_hand_posts_created` — total posts
|
|
- memory_store `reddit_hand_replies_sent` — total replies
|
|
- memory_store `reddit_hand_queue_size` — current queue size
|
|
- memory_store `reddit_hand_karma_earned` — estimated karma from tracked posts
|
|
|
|
---
|
|
|
|
## Guidelines
|
|
|
|
- ALWAYS respect subreddit rules — read the sidebar before posting
|
|
- NEVER post spam, self-promotion abuse, or vote manipulation
|
|
- NEVER harass, bully, or engage in bad-faith arguments
|
|
- NEVER impersonate other users
|
|
- NEVER post private or confidential information
|
|
- Respect Reddit's API rate limits (10 req/min for OAuth, 30 req/min with user auth)
|
|
- In `approval_mode` (default), ALWAYS write to queue — NEVER post without review
|
|
- If the API returns an error, log it and retry once — then skip and alert the user
|
|
- Adapt tone to each subreddit's culture
|
|
- When in doubt about a post, queue it for review with a note
|
|
"""
|
|
|
|
[dashboard]
|
|
[[dashboard.metrics]]
|
|
label = "Posts Created"
|
|
memory_key = "reddit_hand_posts_created"
|
|
format = "number"
|
|
|
|
[[dashboard.metrics]]
|
|
label = "Replies Sent"
|
|
memory_key = "reddit_hand_replies_sent"
|
|
format = "number"
|
|
|
|
[[dashboard.metrics]]
|
|
label = "Queue Size"
|
|
memory_key = "reddit_hand_queue_size"
|
|
format = "number"
|
|
|
|
[[dashboard.metrics]]
|
|
label = "Karma Earned"
|
|
memory_key = "reddit_hand_karma_earned"
|
|
format = "number"
|
|
|
|
[[dashboard.metrics]]
|
|
label = "Subreddits Monitored"
|
|
memory_key = "reddit_hand_subreddits_monitored"
|
|
format = "number"
|
|
|
|
# ─── Token & Performance Metadata ─────────────────────────────────────────────
|
|
|
|
[metadata]
|
|
frequency = "hourly"
|
|
token_consumption = "medium"
|
|
default_active = false
|