Добавьте комментарии в ваше приложение Django

Дайте вашему код‑агенту контекст FastComments, который ему нужен — виджеты, конфигурацию, Secure SSO, REST API и SDK:

npx skills add fastcomments/skills

Работает с Claude Code, Codex, Cursor, Copilot, Gemini и любым другим агентом, поддерживаемым skills CLI.

• Python 3.10+
• Django 4.2, 5.0, 5.1, or 5.2
• Идентификатор арендатора FastComments (используйте demo, чтобы попробовать без учётной записи)
• Секрет API требуется только для Secure SSO

Установите из тега релиза (этот проект распространяется через git‑теги, а не через PyPI):

pip install "git+https://github.com/fastcomments/fastcomments-django.git@v0.1.0"

Для доступа к REST‑интерфейсу на сервере (вспомогательные функции admin() / public_api()), добавьте api‑дополнение, которое подтягивает сгенерированный клиент SDK:

pip install "fastcomments-django[api] @ git+https://github.com/fastcomments/fastcomments-django.git@v0.1.0"

Добавьте приложение в INSTALLED_APPS:

INSTALLED_APPS = [
    # ...
    "fastcomments_django",
]

Настройте вашего арендатора в settings.py:

import os

FASTCOMMENTS = {
    "TENANT_ID": os.environ.get("FASTCOMMENTS_TENANT_ID", "demo"),
}

Поместите виджет в любой шаблон:

{% load fastcomments %}

{% fastcomments url_id="my-page" %}

Чтобы автоматически передать вошедшего пользователя в виджет, теги читают
текущего пользователя из запроса. Убедитесь, что ваш проект содержит оба эти элемента (они
включены по умолчанию в стандартном проекте Django):

• django.template.context_processors.request in TEMPLATES["OPTIONS"]["context_processors"]
• django.contrib.auth.middleware.AuthenticationMiddleware in MIDDLEWARE

Если в контексте шаблона отсутствует запрос, виджеты отображаются для анонимного
посетителя. Вы всегда можете передать пользователя явно: {% fastcomments user=some_user %}.

У каждого виджета есть свой тег. Все они принимают именованные аргументы **extra, которые добавляются в конфигурацию виджета как есть (используйте ключи в camelCase) для всего, что не покрывается именованными аргументами ниже.

Именованные аргументы соответствуют ключам конфигурации виджета в camelCase:

Примеры:

{% load fastcomments %}

{% fastcomments url_id="my-page" locale="en_us" default_sort_direction="MR" %}

{% fastcomments_live_chat url_id="room-1" %}

Comments: {% fastcomments_comment_count url_id="my-page" number_only=True %}

{# Совместный чат привязывается к существующему элементу на странице #}
<article id="post-body">...</article>
{% fastcomments_collab_chat target="#post-body" %}

{# Массовый подсчёт: расставьте маркеры, затем один массовый загрузчик заполнит их все #}
{% for post in posts %}
    <a href="\{{ post.url }}">\{{ post.title }}</a>
    {% fastcomments_count_marker url_id=post.url_id %}
{% endfor %}
{% fastcomments_comment_count_bulk %}

Включите SSO и выберите режим в settings.py. Secure SSO подписывает пользователя на стороне сервера с помощью HMAC-SHA256, используя ваш API secret, и является рекомендуемым вариантом.

FASTCOMMENTS = {
    "TENANT_ID": os.environ["FASTCOMMENTS_TENANT_ID"],
    "API_KEY": os.environ["FASTCOMMENTS_API_KEY"],   # ваш API secret; подписывает Secure SSO
    "SSO": {
        "ENABLED": True,
        "MODE": "secure",                            # "secure" | "simple"
        # Сопоставьте поля FastComments с вашей моделью пользователя. Значением может быть
        # имя атрибута, путь через точку ("profile.avatar_url"), callable(user) или None.
        "USER_MAP": {
            "id": "id",
            "email": "email",
            "username": "username",
            "avatar": None,
            "display_name": None,
            "website_url": None,
        },
        "IS_ADMIN": lambda user: user.is_staff,      # callable(user) -> bool, или путь через точку
        "IS_MODERATOR": None,
        "GROUP_IDS": None,                           # callable(user) -> list, или путь через точку
    },
}

Осознанно выбирайте SSO id. id в FastComments — это постоянный идентификатор истории комментариев пользователя. По умолчанию USER_MAP сопоставляет его с первичным ключом Django для удобства настройки «из коробки», но последовательные целочисленные PK перебираемы, и их сложно изменить позже (смена id пользователя разделяет его историю на новый аккаунт). Для чего-либо помимо демо сопоставьте id со стабильным, непрозрачным значением, выбранным заранее (UUID или отдельный публичный id), и никогда не помещайте в него приватные данные. Пример приложения использует id на основе имени пользователя именно по этой причине.

SSO автоматически внедряется в {% fastcomments %}, {% fastcomments_live_chat %}, {% fastcomments_collab_chat %}, {% fastcomments_image_chat %} и {% fastcomments_user_activity %} для текущего пользователя.

URL-адреса входа/выхода, отображаемые неавторизованным посетителям, по умолчанию указывают на reverse("login") / reverse("logout"); переопределите их с помощью SSO["LOGIN_URL"] / SSO["LOGOUT_URL"].

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

Два варианта с более высоким приоритетом имеют преимущество над USER_MAP:

• Метод в вашей модели пользователя (питонический аналог интерфейса):

  class User(AbstractUser):
      def to_fastcomments_user_data(self):
          return {"id": self.pk, "email": self.email, "username": self.get_username()}

• Глобальный маппер — путь через точку к callable(user) -> dict:

  FASTCOMMENTS = {"SSO": {"USER_MAPPER": "myapp.sso.map_user"}}

Приоритет: USER_MAPPER > to_fastcomments_user_data() > USER_MAP.

С установленным дополнительным модулем [api] вызовите FastComments REST API через SDK, предварительно настроенный с вашим ключом API и регионом:

from fastcomments_django import admin, public_api, get_manager

admin().get_comments("YOUR_TENANT_ID", ...)     # authenticated (DefaultApi)
public_api().get_comments_public(...)            # public (PublicApi)

# Generate an SSO token for API calls or client hand-off:
token = get_manager().sso().token_for(request.user)

Установите REGION, чтобы направлять виджеты и API в ЕС:

FASTCOMMENTS = {"TENANT_ID": "...", "REGION": "eu"}

Переопределите fastcomments/widget.html, разместив свою собственную копию раньше в
пути поиска шаблонов (проект templates/fastcomments/widget.html). Это
аналог в Django команды Laravel vendor:publish --tag=fastcomments-views.

Рабочий демонстрационный пример находится в example/: приложение с левой панелью + основной сценой, имеющее страницу для каждого виджета и страницу входа, перечисляющую заранее подготовленных демо‑пользователей.
Войдите под любым из них, и виджеты комментариев и живого чата аутентифицируют эту личность через Secure SSO. Из этого каталога:

python manage.py migrate
# Use your own tenant to see Secure SSO in action (an API secret enables it):
FASTCOMMENTS_TENANT_ID=... FASTCOMMENTS_API_KEY=... python manage.py runserver

Без секрета API он переходит к публичному арендатору demo (анонимный).
example/browser_smoke.py — это e2e‑тест Playwright, который загружает страницу в реальном браузере и публикует комментарий от имени пользователя Secure-SSO.