CodePawl Video Lab

Самостоятельно размещаемый анализ YouTube для CodePawl, основанный на доказательствах. Расширение Chrome собирает только активный URL YouTube и данные, которые пользователь намеренно импортирует. Cloudflare Worker хранит досье и аналитику авторизованных каналов в D1. Codex читает и записывает результаты анализа через stateless Streamable HTTP MCP-сервер; внутри расширения нет LLM.

YouTube URL → Chrome side panel → Worker + D1 → /mcp → Codex
                                      ↑             │
                                      └── reports ──┘

Рабочая область

apps/extension   WXT + React MV3 side panel and library
apps/worker      Cloudflare Worker, D1, Cron, Google OAuth and remote MCP
packages/contracts  shared Zod schemas, parsers and evidence rules
docs             architecture, security and approval-gated deployment notes

У расширения нет content script. Его собранный манифест запрашивает sidePanel, storage, activeTab и tabs; оно не просматривает DOM YouTube, не загружает субтитры и не получает доступ к байтам видео/аудио.

Related MCP server: yt-mcp

Локальная разработка

Требования: Node 22+, npm 12+, Chrome 114+.

git clone git@github.com:codepawl/codepawl-video-lab.git
cd codepawl-video-lab
npm ci
npm run cf:types
npm run db:migrate:local
npm run dev:worker
npm run dev:extension

Скопируйте apps/worker/.dev.vars.example в .dev.vars, игнорируемый Git, и заполните только локальные учётные данные. Сгенерируйте TOKEN_ENCRYPTION_KEY как 32 случайных байта, закодированных в base64 или base64url. URI перенаправления Google OAuth для локальной разработки:

http://127.0.0.1:8787/oauth/youtube/callback

Создайте десятиминутный код сопряжения через локальный админ-маршрут и введите его на боковой панели. Срок действия полученного токена расширения истекает через 30 дней, и его можно отозвать с помощью Ngắt thiết bị:

curl -X POST http://127.0.0.1:8787/api/v1/admin/pairing-codes \
  -H "Authorization: Bearer $LOCAL_ADMIN_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"label":"Chrome extension"}'

Соберите распакованное расширение:

npm run build --workspace @codepawl/video-lab-extension

Затем загрузите apps/extension/.output/chrome-mv3 из chrome://extensions при включённом режиме разработчика. Установка в личный профиль Chrome намеренно выполняется вручную и только после одобрения.

Правила данных

• Референсные видео: метаданные и анонимизированный текст комментариев поступают из YouTube Data API v3. Комментарии кэшируются на короткое время; личность автора никогда не сохраняется.

• Транскрипты: только вставка пользователем или импорт .srt, .vtt, .txt.

• CodePawl: только youtube.readonly и yt-analytics.readonly. Областей действия для загрузки, редактирования метаданных или публикации не существует.

• Stayed to watch: ручное наблюдение в Studio с явным указанием источника. Эта метрика не представлена в Analytics API.

• Удержание референсного канала, CTR и Stayed to watch никогда не выводятся на основе косвенных данных.

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

• Данные публичного API устаревают через 30 дней. Cron сначала пытается выполнить новое наблюдение через API; устаревшие референсные данные удаляются, если обновление недоступно.

• Google refresh-токены и access-токены шифруются с помощью AES-256-GCM перед сохранением в D1.

MCP

/mcp — это сервер без сохранения состояния на базе createMcpHandler, работающий с D1. Он предоставляет:

• video_inbox_list

• video_dossier_get

• video_dossiers_compare

• channel_performance_get

• retention_curve_get

• analysis_report_save

• experiment_create

• experiment_update

Ресурс: codepawl://rubrics/shorts-v1.

В продакшене Cloudflare Access Managed OAuth защищает /mcp; Worker независимо проверяет издателя утверждения Access, аудиторию и подпись RS256. После развёртывания и настройки Access:

codex mcp add codepawl-video-lab --url https://video-lab.codepawl.com/mcp
codex mcp login codepawl-video-lab

Выполните эти две команды codex mcp на каждой машине, которая должна подключаться к развёрнутому серверу. Аутентификация выполняется отдельно для каждой машины; учётные данные и локальная конфигурация Codex не хранятся в этом репозитории.

Отслеживание

Cron запускается каждые 15 минут и обнаруживает новые загрузки через плейлист загрузок авторизованного канала. Новые видео получают реальные будущие целевые значения на 2, 24 и 72 часа, а также ежедневные сводки. Исторические импорты получают первичное наблюдение в момент подключения и никогда не получают фиктивных ретроспективных временных меток этапов. Пустые ответы Analytics остаются в статусе pending и повторяются с ограниченным backoff. Уникальные ключи заданий и ограничения снапшотов делают повторные запуски идемпотентными.

Проверка

npm run typecheck
npm test
npm run build
npm run db:migrate:local
npm run worker:dry-run

Визуальная фикстура доступна только локально:

cd apps/worker
npx wrangler d1 execute video-lab --local --file test/fixtures/visual-qa.sql
cd ../..
npm run visual:dev --workspace @codepawl/video-lab-extension

Откройте http://127.0.0.1:4173/visual.html?surface=sidepanel или visual.html для библиотеки. Тестовый стенд использует фикстурные данные и не входит в сборку MV3.

Границы одобрения

Никакие ресурсы Cloudflare, DNS-записи, приложения Access, учётные данные Google OAuth или продакшен-развёртывания не создаются при настройке этого репозитория. Точный набор ресурсов, требующий отдельного одобрения, см. в docs/deployment.md.

Лицензия

MIT. См. LICENSE.

Основные ссылки

• Chrome Side Panel API

• YouTube Analytics metrics

• YouTube API developer policies

• YouTube Captions API

• Cloudflare stateless MCP handler

• Cloudflare Access Managed OAuth

• Cloudflare Access JWT validation

• Codex Streamable HTTP MCP