/ Spikes

Цикл обратной связи для разработки с помощью ИИ

ИИ может собрать прототип за час. Превращение обратной связи в действия по-прежнему остаётся медленной частью.

Быстрый старт · Справочник CLI · Документация виджета · Онлайн-дашборд · Самостоятельный хостинг

Что это?

Spikes — это инструмент обратной связи для разработки с помощью ИИ. Он позволяет рецензентам оставлять точечные комментарии прямо на веб-страницах — без скриншотов, без «вот той кнопки», без потери контекста.

Кликните любой элемент. Оцените его. Оставьте комментарий. Spikes фиксирует точный CSS-селектор, ограничивающую рамку и контекст страницы. Ваш ИИ-агент получает структурированный JSON, с которым может немедленно работать.

Не нужны аккаунты. Не нужен шаг сборки. Работает на file://, localhost, где угодно.

Related MCP server: Aceto

Быстрый старт

1. Установите CLI

curl -fsSL https://spikes.sh/install.sh | sh
# Or: cargo install spikes

2. Инициализируйте проект

spikes init                     # Defaults to hosted spikes.sh
# spikes init --self-host       # Opt out — scaffold a self-hosted config instead

spikes init создаёт .spikes/config.toml с секцией [remote], указывающей на https://spikes.sh по умолчанию. Передайте --self-host (или ответьте s в приглашении), чтобы пропустить облачные настройки по умолчанию.

3. Добавьте виджет в ваш HTML

spikes inject ./mockups/        # Injects widget script tag (uses configured endpoint)
spikes serve                    # http://localhost:3847

4. Собирайте и используйте обратную связь

spikes list                     # See all feedback
spikes list --json              # Feed to your agent
spikes list --rating no         # Find problems
spikes hotspots                 # Elements with most feedback
spikes resolve <id>             # Mark items done

Команды CLI

Все команды поддерживают --json для скриптов. См. полный справочник CLI.

Просмотр spikes для размещённого проекта:

Онлайн-дашборд на https://spikes.sh/dashboard перечисляет все ваши проекты и позволяет просматривать отдельные spikes (фильтр по странице, оценке, статусу resolved, переключение resolved прямо в списке). Войдите прямо в браузере: нажмите Sign in, откройте страницу проверки и подтвердите вход через magic-ссылку, отправленную на вашу почту — CLI не требуется.

Вы также можете обращаться к JSON API напрямую с вашим bearer-токеном ($SPIKES_TOKEN из spikes login):

# GET /me/projects
# List all projects you own (with spike_count + last_activity)
curl -H "Authorization: Bearer $SPIKES_TOKEN" \
  https://spikes.sh/me/projects

# GET /me/projects/:key/spikes
# List spikes for one of your projects (paginated, filterable: page, per_page,
# filter_page, filter_rating, filter_resolved)
curl -H "Authorization: Bearer $SPIKES_TOKEN" \
  "https://spikes.sh/me/projects/my-project/spikes?page=1&per_page=50"

# PATCH /me/projects/:key/spikes/:id
# Toggle the `resolved` flag on one spike
curl -X PATCH -H "Authorization: Bearer $SPIKES_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"resolved": true}' \
  https://spikes.sh/me/projects/my-project/spikes/<spike_id>

# POST /projects
# Create a new project (user bearer only)
curl -X POST -H "Authorization: Bearer $SPIKES_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"key": "my-project", "allowed_origins": ["https://example.com"]}' \
  https://spikes.sh/projects

# Single-line variant (copy-paste friendly)
curl -H "Authorization: Bearer $SPIKES_TOKEN" https://spikes.sh/me/projects

Все конечные точки /me/* ограничены пользователем: вы видите только свои проекты и spikes. Запросы между арендаторами возвращают 404 PROJECT_NOT_FOUND (защита от перечисления).

Примечание по безопасности: API-ключи (sk_spikes_*) и административный SPIKES_TOKEN не принимаются на конечных точках /me/* или POST /projects — для них требуется пользовательский bearer-токен из spikes login. Конечная точка сбора POST /spikes применяет список разрешённых источников и лимиты запросов для каждого проекта; отклонённые запросы виджета отображаются как маленький красный индикатор #spikes-error-dot на кнопке виджета (404 / 403 / 429).

Интеграция с ИИ-агентами

Spikes говорит с агентами на родном языке. Ваш ИИ-ассистент для кода может читать, создавать и управлять обратной связью, не выходя из своего рабочего процесса.

npx spikes-mcp            # Zero-install MCP server — just works
# or: spikes mcp serve    # If you have the CLI installed

MCP-сервер — 9 инструментов

spikes mcp serve запускает сервер Model Context Protocol, который предоставляет 9 инструментов:

Поддерживает транспорты stdio и HTTP, локальный и удалённый режимы данных:

spikes mcp serve                              # stdio, local JSONL
spikes mcp serve --remote                     # stdio, hosted API
spikes mcp serve --transport http --port 3848 # HTTP for sandboxed agents

API-ключи

Агенты получают собственную идентичность. Без почты, без magic-ссылки, без участия человека:

spikes auth create-key --name "my-agent"   # → sk_spikes_...
spikes auth list-keys                       # See all keys
spikes auth revoke-key <key_id>            # Revoke

Ключи поддерживают права read/write/full и опциональные лимиты бюджета.

Биллинг для агентов

Тарификация по потреблению для использования в масштабах агентов. Оплата за spike, а не за рабочее место:

spikes usage    # See current spend and limits

При достижении лимита система возвращает 429 BUDGET_EXCEEDED — агенты могут проверить, прежде чем израсходовать бюджет.

Экспорт контекста

Экспорт структурированного Markdown, оптимизированного для потребления агентами:

spikes export --format cursor-context > cursor-feedback.md
spikes export --format claude-context > claude-feedback.md

Обнаружение

• llms.txt — Все 9 MCP-инструментов, параметры, краткое руководство для агентов

• agents.md — Машиночитаемая целевая страница для агентов

• Smithery — Указан в реестре MCP-серверов

• spikes mcp install — Генерирует конфигурацию для Claude Desktop / Cursor

Подробнее: llms.txt · agents.md

GitHub Action

Шлюз CI по качеству обратной связи. spikes-action завершает сборку ошибкой, когда количество нерешённых негативных отзывов превышает заданный порог.

name: CI
on: [push, pull_request]

jobs:
  feedback-gate:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - uses: bierlingm/spikes/action@v0.3.1
        with:
          threshold: 0           # Fail if any blocking spikes
          ignore-paths: ""     # Optional: pages to ignore
          require-resolution: false

Полную документацию см. в action/README.md.

Атрибуты виджета

Простая настройка — просто добавьте ключ проекта и можно собирать обратную связь:

<script src="https://spikes.sh/spikes.js" data-project="my-app"></script>

Когда вы задаёте data-project, обратная связь автоматически синхронизируется с https://spikes.sh/spikes. Настраивать endpoint не нужно, если только вы не разворачиваете собственный хостинг.

Полная конфигурация — все доступные атрибуты:

<script src="https://spikes.sh/spikes.js"
  data-project="my-app"
  data-position="bottom-right"
  data-color="#e74c3c"
  data-theme="dark"
  data-reviewer="Pat"
  data-collect-email="true"
  data-admin="true">
</script>

Самостоятельный хостинг — укажите свой собственный бэкенд:

<script src="/spikes.js"
  data-project="my-app"
  data-endpoint="https://my-worker.workers.dev/spikes">
</script>

Полную документацию см. в справочнике атрибутов виджета.

Архитектура

Spikes состоит из трёх компонентов, которые работают вместе или по отдельности:

┌─────────────┐     ┌─────────────┐     ┌─────────────┐
│   CLI       │────▶│   Widget    │◄────│   Worker    │
│  (Rust)     │     │  (Vanilla   │     │ (Cloudflare │
│             │     │    JS)      │     │  + D1)      │
└─────────────┘     └─────────────┘     └─────────────┘
     │                                            │
     │          spikes.sh (hosted)                │
     └────────────────────────────────────────────┘

CLI — бинарный файл на Rust для локальной разработки, управления spikes и развёртывания. Хранит spikes в ~/.local/share/spikes/.

Widget — 14KB (gzip) ванильного JS. Захватывает селекторы элементов, ограничивающие рамки, оценки и комментарии. Работает офлайн через localStorage.

Worker — опциональный бэкенд на Cloudflare Worker + D1 для синхронизации между несколькими рецензентами, публикации и облачных развёртываний. Живёт в spikes-hosted/.

Разработка

CLI

cd cli
cargo build --release
cargo test              # 160+ tests
cargo run -- --help

Widget

cd widget
# Edit src/spikes.js
# Test by running: spikes serve from the project root

Регрессионные тесты виджета

CI-набор, который ловит класс ошибок тихой потери данных (например, виджет, загруженный на неразрешённом origin, не синхронизируется и не показывает ошибку):

cd tests/widget
npm install
npx playwright install chromium    # one-time
npm test                           # 23 tests: marker checks + happy/reverse/boundary specs (<60s)

Также подключён в локальный agent-ci:

npx agent-ci run --workflow workflows-local/widget.yml

Worker

Бэкенд Worker находится в приватном репозитории spikes-hosted. Чтобы протестировать его:

cd ../spikes-hosted/worker
npm test              # Worker test suite (vitest)
npx wrangler dev

Самостоятельный хостинг

Хотите собственный бэкенд? Одна команда:

spikes deploy cloudflare    # Creates spikes-worker/ directory
cd spikes-worker && npx wrangler deploy

Полную настройку с базой D1, аутентификацией и интеграцией Stripe см. в руководстве по самостоятельному хостингу.

Share или Deploy Cloudflare: что выбрать?

Используйте spikes share, когда нужна мгновенная публикация без какой-либо настройки — файлы загружаются на spikes.sh и раздаются с нашей инфраструктуры. Отлично подходит для быстрых ревью, клиентской обратной связи и случаев, когда вы не хотите управлять бэкендом.

Используйте spikes deploy cloudflare, когда нужна изоляция данных (обратная связь остаётся в вашем аккаунте Cloudflare), собственный домен или полный контроль над инфраструктурой. Для самостоятельного хостинга требуется аккаунт Cloudflare и одноразовая настройка развёртывания.

Что изменилось (недавняя переработка)

• Безопасность: хеширование паролей PBKDF2, исправления обхода пути, защита от XSS

• Аутентификация: вход по magic-ссылке (не нужно запоминать пароли)

• Биллинг: интеграция Stripe с поддержкой Pro-тарифа

• Тестирование: набор тестов CLI (Rust) + набор тестов Worker (в ../spikes-hosted/worker)

• Архитектура: модульный worker с чётким разделением ответственности

• CI/CD: автоматизированные конвейеры тестирования и развёртывания

Подробная документация

• Справочник по CLI — Полная документация по командам

• Атрибуты виджета — Все параметры конфигурации

• Руководство по самостоятельному хостингу — Разверните собственный бэкенд

• Справочник по API — Документация REST API

• Руководство по откату — Экстренные процедуры

Почему Spikes

Цены

Бесплатно навсегда. Pro, если нужно больше.

Для начала аккаунт не нужен. Войдите, когда понадобятся функции Pro.

Лицензия MIT. Оплата — это благодарность, а не доступ.

spikes upgrade, когда будете готовы. Никакого давления.

Сайт · Документация · GitHub · Issues

Лицензия MIT · Сделано для разработчиков, работающих с ИИ.