AI Sana

AI Sana — MVP для хакатона: бизнес превращает слабое описание потребности в проверяемую карточку, повышает её рейтинг и публикует в каталоге. Студенты подают предложения, бизнес вручную выбирает команды и подтверждает выполненные этапы.

Основной сценарий: черновик → вопросы → редактируемая карточка → рейтинг → публикация → отклики → выбор бизнеса → баллы за результат.

Быстрый запуск

Нужен Python 3; сторонние Python-пакеты не требуются.

1. Откройте терминал в папке проекта (в VS Code: Terminal → New Terminal).
2. Выполните:

python3 server.py

3. Откройте http://localhost:8000/.
4. Для остановки нажмите Ctrl+C в терминале.

Без API-ключа доступны все основные действия и локальный fallback. Для показа используйте один и тот же адрес: localhost, 127.0.0.1 и разные порты имеют разные данные браузера.

После изменения server.py или .env перезапустите сервер. После изменения интерфейса обновите страницу.

Запуск с OpenAI

Если .env отсутствует, создайте его из .env.example. Существующий файл с настройками не перезаписывайте.

LLM_PROVIDER=openai
LLM_API_KEY=ваш_ключ
LLM_MODEL=gpt-5
LLM_BASE_URL=https://api.openai.com/v1
PORT=8000

Заполните ключ локально, запустите python3 server.py и откройте приложение. Каждый настоящий запрос к модели использует API вашего аккаунта.

Проверка настроек без вызова модели:

curl http://localhost:8000/api/llm/status

configured: true означает, что сервер нашёл непустой ключ. Это не проверка действительности ключа, баланса или успешной генерации. Подтверждение работы в интерфейсе: «Вопросы подготовлены LLM API» либо «Черновик подготовлен LLM API».

При ошибке API, тайм-ауте или неверном JSON приложение показывает локальный fallback. Сохранение и повторная генерация заблокированы, пока зависимая карточка готовится; старые поля очищаются. Ответ закрытой карточки не переносится в другую задачу.

Ключ не передаётся клиентскому JavaScript. Оба встроенных сервера отдают только index.html, app.js, styles.css и demo.html; запросы к .env, исходникам серверов и тестам запрещены. .env исключён из Git. При передаче ZIP исключите его вручную: .gitignore не управляет содержимым архива.

Node.js — альтернативный сервер

Требуется Node.js 20.6+ с поддержкой --env-file:

node --env-file=.env server.js

Если .env отсутствует и нужен fallback: node server.js. Не запускайте Python и Node на одном порту одновременно.

Для другого OpenAI-compatible сервера предусмотрены LLM_PROVIDER, LLM_BASE_URL, LLM_API_KEY / CODEX_API_KEY. Совместимость такого сервера нужно проверять отдельно.

Live Server и автономное демо

Для основного запуска Live Server не нужен: server.py обслуживает и страницу, и API.

Если нужен Live Server, используйте отдельную папку с четырьмя публичными файлами: index.html, styles.css, app.js, demo.html. Откройте в ней index.html → Open with Live Server. Для LLM отдельно запустите python3 server.py из исходной папки на порту 8000. Клиент попробует локальный API, если сервер страницы не поддерживает этот маршрут.

Не помещайте .env в папку, которую раздаёт Live Server или обычный статический сервер: правила защиты наших прокси на эти серверы не распространяются.

demo.html — собранная версия в одном файле. Её можно открыть двойным щелчком; при доступном API на localhost:8000 она также может вызвать модель, иначе использует fallback. После правок исходников пересоберите:

node build-demo.cjs

Что реализовано

• Свободное описание задачи, компания, отрасль и редактируемый контакт.
• Уточнения по недостающим полям; для встроенного слабого примера формируется шесть вопросов. При почти полной карточке вопросов меньше — по оставшимся пробелам.
• Карточка: название, контекст и потребность, пользователи, данные, результат, критерии успеха, ограничения, контакт и формат взаимодействия.
• Рейтинг 0–100 с расшифровкой и пересчётом при редактировании.
• Ручное подтверждение публикации.
• Каталог: поиск, отдельные фильтры отрасли и готовности, сортировка по рейтингу или дате.
• Отклики с идеей, планом и сроком, необязательной ссылкой на прототип.
• Выбор одной, нескольких или ни одной команды вручную.
• Подтверждённые этапы и баллы команд без повторного начисления.
• AI Task Agent: зависимая подзадача из родительской карточки, роли и фокуса.
• Пять черновиков, пять карточек, пять профилей команд и пять тестовых откликов.

Формула рейтинга задачи

Рейтинг — сумма весов заполненных критериев:

Критерий	Баллы
Контекст и потребность	20
Данные и материалы	20
Ожидаемый результат	15
Критерии успеха	15
Ограничения	10
Пользователи	10
Связь с бизнесом: контакт и формат взаимодействия	10
Максимум	100

В MVP текст считается заполненным, если после удаления пробелов по краям содержит не менее 8 символов. Для связи с бизнесом это условие должно выполняться отдельно для контакта и формата. Критерий даёт полный вес либо 0. Это оценка полноты, а не автоматическая гарантия качества содержания.

Баллы	Уровень
0–39	Черновик, требуется уточнение
40–69	Рабочая
70–89	Готовая
90–100	Приоритетная

При вводе показан предварительный рейтинг. Сохранение записывает карточку; публикация требует названия, контакта и ручного подтверждения. Низкий рейтинг не запрещает публикацию и отклики.

Правила каталога и выбора

В каталоге показаны все опубликованные задачи текущего браузера. По умолчанию сверху задачи с большим рейтингом. Поиск и оба фильтра применяются совместно; очистка фильтров возвращает весь каталог.

Рекомендации, проверка полноты отклика и сравнение команд рассчитываются локально по явным правилам; они не являются ответами LLM. Они не скрывают остальные задачи и не назначают исполнителей.

Каждая из тестовых команд может отправить один отклик на задачу; ограничение предотвращает дубликаты. Общего лимита откликов разных команд нет. Идея и план должны содержать не менее 20 символов каждый. Срок указывается в плане, а ссылка при наличии должна начинаться с http:// или https://.

Бизнес может принять несколько откликов независимо или не принять ни одного. Переключатель ролей демонстрационный, серверной авторизации нет.

Баллы за фактический прогресс

Этапы: исследование, прототип, разработка, тестирование и финальная передача.

1. Бизнес принимает отклик и открывает «+ Этап».
2. Указывает этап и фактически выполненный результат.
3. Выбирает «Этап завершён» и отмечает подтверждение проверки результата.
4. Команда получает 20 баллов за этот этап.

За один и тот же этап одной команды в одной задаче баллы начисляются только один раз. Повторная запись остаётся в журнале, но даёт 0 новых баллов. Статусы «В работе» и «Есть блокер» баллов не дают. Студент и непринятая команда не могут подтвердить этап через интерфейс.

Максимум на команду в одной задаче — 100 баллов. В разделе «Команды и данные» показана сумма по всем задачам; она может превышать 100. Рейтинг задачи и баллы команды — разные показатели. Старые записи прогресса без явного подтверждения не получают баллы задним числом.

AI, ограничения и проверка человеком

Два серверных маршрута:

• POST /api/llm/clarify: получает описание, карточку и недостающие поля; возвращает missingFields, questions, пустой suggestions.
• POST /api/llm/decompose: получает название и поля родительской задачи, роль и фокус; возвращает строго шесть строковых полей:

{
  "title": "",
  "goal": "",
  "input_data": "",
  "expected_artifact": "",
  "acceptance_criteria": "",
  "constraints": ""
}

Сервер использует OpenAI Responses API с text.format / JSON Schema, strict: true и store: false. Формат сверяется повторно сервером и клиентом. Документация Structured Outputs.

Промпт запрещает придумывать исходные данные и предписывает уточнять неизвестное. Для критериев приёмки запрашиваются до трёх ключевых проверок; это правило промпта, а не отдельная проверка количества в коде. Правильная JSON-схема не гарантирует достоверность текста: человек проверяет все поля.

Зависимая карточка сохраняется только вручную как черновик. Сохраняется источник llm-api либо local-fallback. ИИ не публикует задачи и не принимает команды.

Архитектура

Браузер: index.html + app.js + styles.css
  ├─ карточки, рейтинг, каталог, отклики, прогресс
  ├─ localStorage: ai-sana-mvp-v1
  └─ /api/llm/clarify и /api/llm/decompose
       └─ server.py или server.js
            └─ OpenAI Responses API

Файл	Назначение
app.js	Логика интерфейса, сохранение, рейтинг, баллы и API
index.html, styles.css	Интерфейс
server.py, server.js	API-прокси и раздача разрешённых публичных файлов
.env.example	Шаблон настроек без ключа
build-demo.cjs, demo.html	Сборщик и автономная версия
tests/	Регрессионные проверки и тестирование обоих серверов
DEMO.md	Сценарий защиты на пять минут

Проверки

Node.js нужен только для тестов, альтернативного сервера и пересборки демо. Из корня проекта:

node tests/app.test.cjs
node tests/regression.test.cjs
node tests/server.test.cjs
node --check app.js
node --check server.js
node build-demo.cjs

Серверные тесты поднимают Python- и Node-прокси на временных портах и используют локальную имитацию провайдера. Реальный ключ и платные запросы для них не нужны. Проверяются закрытие служебных файлов, CORS, корректный ответ, неверный JSON и нарушения схемы. PYTHON=/путь/к/python3 позволяет указать Python для теста.

Ручная проверка в браузере:

1. Загрузить слабое описание; увидеть вопросы и рейтинг 20/100.
2. Ответить на вопросы, заполнить карточку; увидеть рост до 100/100.
3. Изменить контакт, сохранить, обновить страницу; убедиться, что сохранён новый контакт.
4. Подтвердить публикацию; найти задачу по отрасли и рейтингу.
5. Отправить два отклика от разных команд; вручную принять обе.
6. Подтвердить этап одной команды: +20; повторить тот же этап: сумма не меняется.
7. Создать зависимую карточку; проверить ожидание, итоговый статус LLM/fallback и ручное сохранение.
8. Включить «Демо: принудительно проверить fallback» и убедиться, что вопросы доступны без ответа API.

Сброс демо удаляет изменения текущего браузера. Для репетиции используйте отдельный профиль или отдельный порт, например PORT=8001 python3 server.py, и открывайте именно этот адрес.

Типовые проблемы

• Порт занят: остановите свой прежний сервер через Ctrl+C или используйте PORT=8001 python3 server.py.
• configured: false: проверьте .env и перезапустите сервер.
• Ключ есть, но включился fallback: проверьте действительность ключа, доступ к модели, квоту и сеть; наличие ключа само по себе не подтверждает работу API.
• Ожидание генерации: запрос к провайдеру ограничен 90 секундами, клиент — 100 секундами на адрес; при ошибке интерфейс возвращается к fallback.
• После смены адреса исчезли карточки: localStorage привязан к адресу и порту.
• demo.html показывает старую версию: выполните node build-demo.cjs.
• Невозможно сохранить в браузере: приложение показывает ошибку; проверьте доступность localStorage.

Границы MVP и сдача

Данные локальны для браузера и не синхронизируются между компьютерами. Сервер обслуживает API модели, но не является общей базой задач. Нет регистрации, серверных ролей, чата и реальных интеграций с бизнес-системами. Демонстрационные профили и примеры синтетические.

Для защиты подготовьте исходники без .env, эту инструкцию, рабочий локальный запуск и демонстрацию по DEMO.md. Публичный deployment в проекте не заявлен; для него отдельно потребуются защита API, общее хранилище и серверная авторизация.