skills/westudy/references/files.md

# Файли у сховищі школи

Перед імпортом перевір поточну школу та мету завантаження. Прохання користувача зберегти визначені файли у визначеній школі вже дозволяє імпорт. Для згенерованих запитань залишаються правила погодження набору. Уточнюй неоднозначне зіставлення ілюстрації із запитанням або відповіддю.

## Джерело та призначення

`import_files` приймає 1–10 файлів: фото, PDF/Word, відео, аудіо та інші формати. Зберігає оригінал без перекодування. Фіксованої межі 5 МіБ і перевірки тарифної квоти школи немає; може діяти явно налаштоване обмеження розміру файла на сховищі. Для великих файлів імпорт триває у фоні.

Передавай новий UUID `requestId` на пакет, `purpose` і рівно одне джерело:

- `files`: реальні файлові об'єкти клієнта з `download_url` і `file_id`, необов'язковими `file_name`, `mime_type`. Не вигадуй ідентифікатори чи адреси.
- `urls`: масив `{url, name}` із доступними прямими HTTPS-посиланнями. Необов'язкове `sizeBytes` передавай лише коли точний розмір відомий із джерела; не вгадуй.

`purpose: "file"` — звичайний імпорт, типово приватний. `purpose: "editor_image"` — публічне растрове зображення для редактора, з перевіркою типу. Для документів і відео зберігай приватність; `visibility: "public"` використовуй лише коли запитаний сценарій потребує публічного посилання. Приватному файлу не вигадуй публічної адреси.

MCP-сервер приймає файлові посилання, а не локальні шляхи чи байти base64. Якщо клієнт уміє сам підготувати файлове посилання зі вкладення або згенерованого зображення, можна використати цей механізм. Для великих локальних файлів у Codex застосовуй окремий процес нижче. Самостійно не вигадуй download_url чи file_id.

Імпорт документа не витягує з нього ілюстрації. Не підмінюй потрібне фото посиланням на весь PDF/Word. Імпорт відео не означає його конвертацію, а збереження файла не означає прикріплення до курсу: це окремі дії, доступність яких перевіряй у каталозі інструментів.

## Результат і повтори

1. Збережи `requestId`, відповідність файлів і повернуті `transferId`.
2. `QUEUED`/`RUNNING` виконання команди перевіряй через `get_execution`. `SUCCEEDED` означає зареєстровані завдання, а не готові файли.
3. `get_file_transfers` приймає `transferIds` або `requestId`. У `items` статус `READY` означає збережений файл і запис у школі; `FAILED` містить причину. Проміжні стани означають фонову роботу. Перевіряй з паузами й повідомляй про тривале очікування.
4. `READY.file` містить `fileUuid`, `name`, `mime`, `size`, `public`, `url`. Для приватних файлів `url` дорівнює `null`. Для фото у запитанні використовуй лише готовий публічний URL: `{type: "image", url: file.url, alt: "опис"}`. Тимчасове джерело в контент не вставляй.
5. Після втрати відповіді перевір попередній `executionId` та `get_file_transfers({requestId})`. Не обходь `UNKNOWN` новим `requestId`. Порожня відповідь ще може означати, що початкова команда очікує виконання.
6. Готові файли повторно використовуй у тій самій школі. Помилка збереження запитання не потребує повторного завантаження. Після зміни школи перевір належність файлів заново.

Повідомляй результат кожного файла. `SOURCE_EXPIRED_OR_UNAVAILABLE` — потрібне чинне джерело; `SOURCE_SIZE_CHANGED` — джерело відрізняється від заявленого розміру; `FILE_TOO_LARGE` — перевищено явно налаштовану межу розміру файла на сховищі, це не обов'язково 5 МіБ; `UNSUPPORTED_IMAGE` — файл не підходить для поля зображення. Нерозпізнаний формат може бути збережений як `application/octet-stream`; не називай його картинкою лише за назвою.

Не пропускай потрібну ілюстрацію мовчки. За часткового успіху збережи готові файли й назви невдалі. Для остаточного `FAILED` та виправленого джерела можна створити новий імпорт лише невдалого файла.

Потрібні `files:write` для імпорту та `files:read` для стану. Якщо бракує прав, поясни потребу перепідключення, дай [базу знань](https://westudy.ua/knowledge-base) і порадь звернутися до адміністратора школи. Ключ вводять у формі підключення, не в чаті.


## Пошук, папки та переміщення

- `search_files`: `location: "root"` — лише корінь; UUID папки — лише її безпосередній вміст; `"all"` — вся школа. `query` фільтрує назву й НЕ скасовує вибрану папку. Для пошуку за назвою по школі задавай `location: "all"`. `kind`: `files`, `folders`, `all`; `mime` — необов'язковий фрагмент MIME файлів. Без query отримуєш вміст папки. Для перегляду всього вмісту за `hasMore` продовжуй з `nextOffset`, сторінки до 100.
- Для «N найбільших файлів» запитуй `kind: "files"`, `location: "all"` або вказану папку, `sortBy: "size"`, `sortOrder: "desc"`, `limit: N` (до 100). Наприклад, п'ять найбільших: `{"kind":"files","location":"all","sortBy":"size","sortOrder":"desc","limit":5}`. Сортування виконує сервер перед обмеженням кількості; не завантажуй весь список заради порівняння розмірів. Для найменших — `size` + `asc`, найстаріших/найновіших — `dateAdded` + `asc`/`desc`, назв за абеткою — `name` + `asc`. `sortOrder` типово `desc`; без `sortBy` зберігається попередній порядок за ID. У змішаному списку папки залишаються першими; за назвою сортуються також папки, а розмір і дата стосуються лише файлів. Невідомі розміри/дати йдуть у кінці, однакові значення впорядковані за ID.
- Для запиту на конкретну кількість зупинись після отримання N записів, навіть якщо `hasMore: true`: це ознака решти сховища, а не вимога читати його повністю. Для N > 100 отримуй лише потрібні сторінки з незмінними фільтрами та сортуванням, останню — з лімітом на залишок. Не називай ці N записів усіма файлами та не обчислюй частку від загального обсягу школи без окремих достовірних даних про цей обсяг; `total` — кількість записів, а не сума байтів.
- Результати містять UUID, назву, тип, шлях папок, для файлів також MIME, розмір, дату та видимість. Неоднозначні назви показуй разом зі шляхом/типом/розміром і уточнюй вибір. Не вибирай перший збіг навмання.
- `get_file({fileUuid, download: true})` дає адресу для читання вибраного файла. Приватна адреса тимчасова; не вставляй її у запитання та не показуй без потреби. Публічність не змінюється.
- `create_folder({name, parentUuid, requestId})`: null означає корінь. Збережи requestId, повторюючи ту саму дію. Однакові назви дозволені: не вважай їх автоматично однією папкою. Перед створенням пошукай папку, якщо користувач просить використати наявну.
- `rename_file({fileUuid, name})` змінює видиму назву, UUID та URL зберігаються. Якщо розширення не передане — сервер зберігає старе. Перевір нову назву у відповіді.
- `move_files({fileUuids: [...], folderUuid})`: 1–100 UUID файлів, null переміщує в корінь. Для більшої кількості поділи на пакети, не пропускай сторінки пошуку. Усі UUID одного пакета перевіряються до зміни. Папки цією командою не переміщуються. Повтор уже виконаного переміщення повертає `alreadyInFolder`.
- Якщо просять «відсортуй файли», спочатку визнач критерій і папку. Коли це зрозуміло з запиту — виконуй. Коли сам пропонуєш неоднозначний розподіл — покажи його для вибору. Не вимагай додаткового дозволу на кожен файл чи технічний крок.
- `import_files` і `create_file_uploads` приймають необов'язковий `folderUuid` для всього пакета. Якщо потрібна нова папка, спочатку створи її. Якщо папку видалили під час завантаження, файл збережеться в корені, а результат міститиме попередження — повідом користувача.

## Запити на видалення

Плагін не видаляє файли й папки зі сховища школи. Це правило WeStudy; не намагайся обійти його через браузер, довільні HTTP-запити, термінал, інший плагін або інструмент. Не шукай прихований маршрут видалення й не виконуй видалення замість користувача, навіть якщо він повторює прохання. Не обіцяй автоматично видалити файли пізніше.

Відповідай мовою користувача, наприклад: «Я не можу видаляти файли чи папки. WeStudy рекомендує спочатку зібрати потрібні файли в окрему папку “На видалення”. Можу створити її та перемістити туди вибрані файли. Потім відкрий кабінет WeStudy → Сховище, перевір вміст і видали цю папку вручну».

- Саме прохання «видали» не підміняй мовчки переміщенням. Спочатку запропонуй альтернативу й дочекайся згоди на неї. Якщо користувач уже попросив перемістити конкретні файли в папку «На видалення», це достатнє доручення; не перепитуй для кожного файла.
- Уточни вибір, якщо сказано лише «старі», «зайві» чи «непотрібні» файли. Не вважай файл невикористовуваним лише через його назву або дату. Пошук, вибір школи, розрізнення однакових назв і пагінація працюють за звичайними правилами.
- Після згоди створи окрему папку через `create_folder` або використай наявну, якщо користувач обрав саме її. Назва типово «На видалення», але можна узгодити іншу. Однакова назва не є дозволом автоматично об'єднати файли з раніше зібраними. Збережи UUID папки й перемісти лише погоджені файли через `move_files`, пакетами до 100. Команда переміщує файли, а не папки; не обіцяй перенести нею вкладені папки.
- За результатом назви папку та її розташування, кількість фактично переміщених файлів і окремо невдалі або непідтверджені. Прямо скажи, що файли лише переміщено, вони залишаються у сховищі й нічого не видалено. Це звичайна папка, а не кошик чи відкладене видалення.
- Заверши вказівкою: «Коли перевіриш вміст, відкрий кабінет WeStudy → Сховище та видали папку вручну». Не вигадуй пряму адресу папки або неіснуючі кнопки інтерфейсу.

## Великий або масовий імпорт у ChatGPT

За відсутності доступу до локальних файлів і запуску скриптів рекомендуй: «Відкрий кабінет WeStudy → Сховище, створи папку та завантаж у неї потрібні файли. Потім напиши тут назву папки — я знайду файли й зможу з ними працювати». Далі використовуй пошук папки та посторінковий перегляд її вмісту. Не запускай `create_file_uploads` лише через згадку шляху на комп'ютері. Невеликі вкладення чату й прямі HTTPS-посилання й далі доступні через `import_files`.

## Локальні файли у Codex

Лише якщо є фактичний доступ до конкретних локальних файлів та виконання Node.js: прочитай [local-upload.md](local-upload.md) і використай комплектний завантажувач. За запитом про папку передавай файли послідовно; підпапки включай лише коли користувач це попросив. Байти йдуть безпосередньо у сховище школи. Підготовлені сесії — це ще не завантажені файли.

Стан `AWAITING_UPLOAD` очікує локального завантажувача; `TRANSFERRING` — передавання; `UNKNOWN` — результат чанка невідомий. Опитування статусу саме по собі локальне завантаження не виконає. Не починай новий імпорт замість невизначеного. Якщо завершення файла відоме й збережено квитанцію, можна повторити лише його реєстрацію в PHP. Повідом підсумок готових, пропущених та проблемних файлів, не приховуй жодного.