artwist-polyakov/polyakov-claude-skills/reddit-skill

reddit-skill

Чтение публичных списков через RSS, постов и комментариев через .json без ключей, а также прямой доступ к Reddit API через OAuth2 без PRAW. Порт MCP-сервера Arindam200/reddit-mcp на shell-скрипты по образцу yandex-metrika / yandex-search-api.

Выбор способа чтения

Для публичного чтения по пользовательским подпискам, в том числе RSS-мониторинга, бери список из config/subscriptions.txt: одно название сабреддита на строку, без r/. Сабреддиты, явно заданные в запросе, имеют приоритет над сохранённым списком. Не ищи подписки в .env или аккаунте и не подключай браузерную сессию для получения этого списка. Если файл отсутствует или пуст, уточни сабреддиты у пользователя.

Если пользователь не указал способ, для публичного чтения сначала используй доступный встроенный инструмент чтения URL (fetch, WebFetch, open или аналог). Открывай конкретный адрес; результаты поиска сами по себе не заменяют содержимое:

• Пост и комментарии: используй адрес с .json; для обычной ссылки добавь

.json к пути поста перед параметрами запроса, например https://www.reddit.com/r/Python/comments/abc123/title/.json?limit=100&raw_json=1.

• Список постов: если инструмент поддерживает XML/Atom, открой RSS-ленту,

например https://www.reddit.com/r/Python/top.rss?t=day&limit=25.

Для этого способа не запускай auth_check.sh и не запрашивай ключи приложения. Список подписок хранится отдельно от .env; наличие или исправность ключей не является условием публичного чтения. При повторном мониторинге запрашивай свежие данные, если инструмент это позволяет; иначе укажи ограничение свежести.

Если инструмента нет, он не поддерживает формат, не вернул нужное содержимое или задача требует скрипта и локального кеша, используй команды ниже. Для чтения без ключей передавай REDDIT_RSS_MODE=1. Ошибка одного способа не доказывает недоступность другого.

Веб-инструмент может возвращать сокращённый текст вместо исходного JSON или RSS. Не выдавай такой ответ за полный файл и не обещай все комментарии: учитывай усечение, параметр limit и элементы more. Локальный кеш описан ниже только для скриптов; при чтении веб-инструментом не сообщай о сохранении файла, если он не был сохранён.

Настройка скриптов

Для мониторинга постов ключи приложения не нужны. Включить RSS явно:

REDDIT_RSS_MODE=1 sh scripts/subreddit_top.sh --subreddit singularity --time day --limit 25

REDDIT_RSS_MODE=1 можно сохранить в config/.env. При передаче через окружение скрипт не читает .env. Для списка из config/subscriptions.txt передавай каждый сабреддит явно через --subreddit: скрипты сами список подписок не загружают. Для RSS есть стандартный User-Agent; его можно заменить через REDDIT_USER_AGENT.

Для полного доступа через API зарегистрировать script-app на https://www.reddit.com/prefs/apps и заполнить config/.env:

• REDDIT_CLIENT_ID, REDDIT_CLIENT_SECRET
• REDDIT_USER_AGENT (обязателен по правилам Reddit)

Подробная инструкция: config/README.md.

Для write/me дополнительно:

• REDDIT_USERNAME, REDDIT_PASSWORD — владелец script-app (без 2FA)
• REDDIT_ENABLE_WRITE=1 + --confirm на каждой write-команде

Поведение скриптов

1. Cache-first — токен, юзеры, сабреддиты, листинги кешируются по детерминированному ключу.
2. Context window hygiene — stdout ≤ 30 строк, полный JSON в cache/listings/<hash>.json.
3. Выбор режима — REDDIT_RSS_MODE=1 включает RSS. Без ключей поддерживаемые команды чтения также используют RSS. С ключами выбирается user mode при наличии REDDIT_USERNAME+REDDIT_PASSWORD, иначе app-only. При отказе авторизации чтение постов автоматически переходит на RSS в текущем запуске; настройки на диске не меняются.
4. Двойная защита write — два уровня:

• Без REDDIT_ENABLE_WRITE=1 в .env write-скрипты отказывают сразу с понятной ошибкой (никакого dry-run — это «ворота» уровня окружения).
• С REDDIT_ENABLE_WRITE=1, но без --confirm — dry-run: печатают что бы сделали, но не отправляют запрос.
• Только при REDDIT_ENABLE_WRITE=1 и --confirm команда реально идёт на Reddit.

1. Rate-limit от заголовков — читаем x-ratelimit-remaining, x-ratelimit-reset, Retry-After. На 429 один retry если ожидание ≤ 60s.

Использование скриптов

Проверка доступа

1. Если выбран скрипт, запускай нужную команду чтения сразу. Если нужно проверить доступ отдельно:

``bash sh scripts/auth_check.sh ` Успех: OK: RSS feed works, OK: app-only token works или OK: user token works`. Для RSS не запрашивай файл с ключами и не требуй регистрации приложения.

1. Если нужна write-операция:

• Убедись, что в .env есть REDDIT_USERNAME+REDDIT_PASSWORD+REDDIT_ENABLE_WRITE=1

(без REDDIT_ENABLE_WRITE=1 команда сразу падает с ошибкой — это намеренно)

• Сначала запусти команду без --confirm — увидишь dry-run
• Только после ревью пользователя — добавляй --confirm

1. Имя сабреддита/юзера можно передавать с префиксом или без: r/python ≡ python, u/spez ≡ spez.

Возможности RSS

RSS поддерживают subreddit_top.sh, search.sh, user_posts.sh и auth_check.sh. Параметры поиска, сортировки, периода и количества передаются в публичную ленту. submission.sh в этом же режиме читает https://www.reddit.com/comments/{id}.json без токена. Можно передать обычную ссылку поста, ссылку с .json или ID. --include-comments у топа загружает посты и комментарии через тот же публичный JSON. Остальные команды требуют API.

Сохраняются доступные в ленте заголовок, ссылка, дата, автор, сабреддит и текст. JSON имеет привычную структуру Listing и признак source: "rss". score и num_comments равны null, в кратком выводе — ?: RSS этих чисел не даёт. Не оценивай по ним популярность поста. Текст ограничен содержимым самой ленты.

Публичный .json сохраняется как массив [Listing поста, Listing комментариев], каждый с source: "public-json"; оценки и другие поля берутся из ответа Reddit. Полный полученный текст и вложенные ответы доступны в кеше, на экран выводится краткая сводка. Не обещай все комментарии: ответ ограничен --limit-comments / --comments-per-post и может содержать more. Скилл не разворачивает more дополнительными запросами; submission.sh сообщает, если нашёл его в дереве.

Автоматический переход срабатывает при отказе выдачи токена (HTTP 400/401/403 или OAuth-ошибка авторизации), API 403 либо повторном API 401 после обновления токена. Сетевые ошибки, 429 и 5xx не означают нерабочий ключ и не включают RSS. Если RSS или публичный JSON также недоступен, команда возвращает явную ошибку. При ошибке загрузки комментариев уже полученный список постов остаётся в кеше.

Scripts

Auth & identity

Read

Общие read-флаги: --limit N, --no-cache, --time T (где применимо), --sort S (где применимо).

Write (опасные — двойной предохранитель)

Все write-команды требуют --confirm и REDDIT_ENABLE_WRITE=1 в .env. Поведение:

• REDDIT_ENABLE_WRITE не установлен → отказ с ошибкой (envelope-уровень).
• REDDIT_ENABLE_WRITE=1, но без --confirm → dry-run (печать, без сети).
• Оба условия выполнены → реальный POST.

Кеш скриптов

cache/
├── token.json                  # OAuth access token + expires_at
├── users/<username>.json       # /user/{u}/about
├── subreddits/<sub>.json       # /r/{sub}/about
├── subreddits/<sub>.rules.json
├── subreddits/<sub>.moderators.json
├── listings/<hash>.json        # листинги (search, top, posts, comments, popular)
├── top_with_comments/<hash>/   # копии постов с комментариями в подпапках api/ и rss/
└── me.json                     # /api/v1/me

Ключи кеша публичного чтения отделены от API. При неудачном обновлении поста или списка прежний файл сохраняется. Для свежих публикаций при повторном мониторинге передавай --no-cache.

Поиск по кешу: grep -r "term" cache/ или rg "term" cache/.

Examples

# 1) Profile of a user
sh scripts/user_info.sh --username spez
 
# 2) Top posts in r/Python this week
sh scripts/subreddit_top.sh --subreddit python --time week --limit 25
 
# 3) Search "machine learning" in r/learnprogramming, sorted by new
sh scripts/search.sh --query "machine learning" --subreddit learnprogramming \
    --sort new --time month --limit 20
 
# 4) Пост и комментарии через публичный JSON без ключей
REDDIT_RSS_MODE=1 sh scripts/submission.sh \
    --url "https://www.reddit.com/r/Python/comments/abc123/some_title/" \
    --limit-comments 50
 
# 5) DRY-RUN of a comment reply (requires REDDIT_ENABLE_WRITE=1; without --confirm only prints)
REDDIT_ENABLE_WRITE=1 sh scripts/comment_reply.sh \
    --parent-id t3_abc123 --content "Looks great!"
 
# 6) Real reply (after dry-run review)
REDDIT_ENABLE_WRITE=1 sh scripts/comment_reply.sh \
    --parent-id t3_abc123 --content "Looks great!" --confirm
 
# 7) Топ с комментариями (один дополнительный API или JSON запрос на пост)
sh scripts/subreddit_top.sh --subreddit Python --time week --limit 5 \
    --include-comments --comments-per-post 25

Rate limits

Reddit OAuth: ~60 req/min для app-only, ~600/10min для user-mode (зависит от истории аккаунта). Скилл читает Reddit-специфичные заголовки x-ratelimit-* и стандартный Retry-After. На 429 делает один retry если ожидание ≤ 60s, иначе fail с понятной ошибкой.

Tests

sh scripts/tests/run.sh

No-network, проверяют:

• парсинг submission URL → id
• детерминированность cache_key
• корректность авто-выбора режима auth
• что write-команды без REDDIT_ENABLE_WRITE или без --confirm ничего не отправляют
• разбор Atom, публичный JSON, чтение без ключей, переход с API и разделение кеша

Differences from upstream

Оригинальный reddit-mcp использует PRAW + Python и зашит как MCP-сервер. Здесь публичное чтение начинается с доступного веб-инструмента агента; shell-скрипты используют curl и кеш в директории скилла. Анализ постов и обсуждений выполняет агент по полученным данным.

Документация