Поставити й підключити помічника¶

Головний шлях — без жодної команди: три програми в правильному порядку й один готовий запит. Займає 30–40 хвилин, більшість часу — завантаження.

Чому не чат на сайті

У чаті на claude.ai чи chatgpt.com Нишпорка не працює: чат відповідає текстом і не має доступу до вашого диска. Потрібна програма-помічник, яка розмовляє так само, як чат, але сама виконує дії на комп'ютері й питає дозволу перед кожною.

Те саме на відео

Уроки 3–5 серії відеоуроків показують встановлення на Windows крок за кроком. У відео помічник — Codex (див. «Інші помічники» нижче); з Claude Desktop порядок той самий: Git, Нишпорка, помічник, робоча тека, готовий запит.

Що потрібно¶

Windows 10 або 11, macOS чи Linux.
Близько 5 ГБ вільного місця: моделі читання й усе потрібне для них — 2.5 ГБ.
Підписка Claude Pro або Max — для Claude Desktop (плани). Або підписка ChatGPT — для Codex. Сама Нишпорка безкоштовна: платите лише за помічника.

Крок 1. Git for Windows¶

Завантажте Git for Windows і поставте, скрізь натискаючи «Next». Без нього в Claude Desktop не відкривається вкладка Code, а Нишпорці він потрібен, щоб поставити моделі читання. На macOS Git зазвичай уже є.

Крок 2. Поставити Нишпорку¶

Нишпорка ставиться після Git: без нього не стане програма читання рукопису. Помічник — останнім (чому — у кроці 3).

WindowsmacOS і Linux

Завантажте інсталятор і запустіть його.
Якщо Windows пише «Windows захистив ваш ПК» — «Докладніше» → «Виконати в будь-якому разі». Так Windows зустрічає кожну програму, яку ще мало хто завантажував. Якщо ж антивірус називає інсталятор трояном і забирає файл, дивіться «Антивірус назвав інсталятор трояном».
На сторінці «Де жити Нишпорці» оберіть теку на диску, де вдосталь місця (потрібно близько 10 ГБ), наприклад D:\Genealogy\Нишпорка. У цій одній теці буде все: програма, рушії читання й ваше дослідження.
На питання «Що ставимо» лишіть «Усе (рекомендовано)». Легкий набір — лише каталоги архівів, без читання рукописів і без пошуку роду.
Наприкінці лишіть обидві галочки: «Запустити Нишпорку» відкриє застосунок у браузері (це ваш комп'ютер, а не сайт: без інтернету він теж працює), а друга — цю інструкцію з наступного кроку.

Відкрийте «Термінал», вставте один рядок і натисніть Enter:

curl -LsSf https://raw.githubusercontent.com/SERGIUSH-UA/nyshporka/main/install/unix.sh | sh

Коли скрипт скінчить, закрийте вікно термінала.

Крок 3. Claude Desktop¶

Завантажте застосунок: Windows, macOS.
Запустіть і увійдіть у свій обліковий запис.
Натисніть вкладку Code угорі по центру.

Якщо Claude уже стояв на комп'ютері

Закрийте його повністю — правою кнопкою на іконці біля годинника → «Вийти» (Quit) — і відкрийте знову. Програма запам'ятовує, де шукати команди, у момент запуску, тож про щойно поставлену Нишпорку не знає. Симптом: помічник пише, що команду nysh не знайдено.

Крок 4. Відкрити робочу теку¶

У вкладці Code, перш ніж щось писати:

Оберіть Local — помічник працюватиме на вашому комп'ютері.
Select folder → тека, яку ви обрали в інсталяторі на сторінці «Де жити Нишпорці» (типово Документи\Нишпорка). Там житимуть скани, прочитане й нотатки. Забули, де вона, — шлях написано внизу головної сторінки застосунку.
Режим дозволів — Manual: помічник питатиме перед кожною дією, і ви бачите, що саме він робить.

Крок 5. Вставити готовий запит¶

Скопіюйте текст цілком у поле вводу й натисніть Enter:

Прочитай https://raw.githubusercontent.com/SERGIUSH-UA/nyshporka/main/AGENTS.md
Спершу коротко розкажи мені, що таке Нишпорка і що ми зараз зробимо.
Потім зроби за інструкцією все, щоб Нишпорка була готова на цьому комп'ютері: перевір
машину, за потреби постав рушії читання й моделі й поклади скіли для всіх
проєктів. Кожен крок пояснюй мені простими словами.
Коли все зелене — спитай, яке прізвище я шукаю і в яких написаннях.

Помічник прочитає інструкцію, написану для нього, і, щоразу питаючи дозволу:

перевірить машину (nysh doctor);
поставить моделі читання (nysh htr install, nysh models get) — це найдовший крок, близько 2.5 ГБ;
покладе скіли — готові порядки роботи (nysh skills install --user);
спитає, яке прізвище шукаємо.

Готово, коли помічник каже, що перевірка без червоних рядків, і питає прізвище. Далі — «Як працювати».

Інші помічники¶

Codex (OpenAI, підписка ChatGPT): застосунок або версія для термінала. Кроки 1 і 2 ті самі; у кроці 4 відкрийте теку Документи\Нишпорка; у запиті замість «поклади скіли для всіх проєктів» напишіть «поклади скіли в теку ~/.agents/skills».

Claude Code у терміналі — достатньо одного рядка й запуску:

nysh skills install --user   # скіли для всіх проєктів
claude

Інші — будь-який помічник, що читає скіли у форматі SKILL.md (Agent Skills), зокрема OpenClaw. Покласти їх у його теку: nysh skills install --target <тека>.

Якщо щось не так¶

що ви бачите	що робити
помічник: «команду `nysh` не знайдено»	Повністю закрити Claude (іконка біля годинника → Вийти) і відкрити знову. У терміналі — відкрити нове вікно; не допомогло — перезапустити комп'ютер
вкладка Code пропонує оновити план	Потрібна підписка Claude Pro або Max
помічник: «середовище рушіїв не готове»	Скажіть йому: «постав рушії читання й моделі»
помічник: «torch не вантажиться», «бракує Visual C++»	Скажіть йому: «постав рушії читання». Нишпорка поставить компонент Microsoft Visual C++ — Windows попросить дозволу адміністратора, погодьтесь
помічник не бачить теку зі сканами	Тека лежить поза робочою текою; помічник має спитати дозволу взяти її під облік (`nysh roots add`). Файли нікуди не переносяться
інсталятор завершився «код 1»	Дивіться останні рядки виводу. Найчастіше — обірване завантаження, брак місця або антивірус
щось інше	Написати авторові, додавши дослівно, що написав помічник

Антивірус назвав інсталятор трояном¶

Microsoft Defender іноді позначає nyshporka-setup.exe як троян, найчастіше з назвою на кшталт Trojan:Win32/Bearfoos.B!ml. Закінчення !ml означає, що програму запідозрила автоматична модель за загальними ознаками, а не знайшла в ній відомий вірус. Так буває з програмами без цифрового підпису, які ще мало хто завантажував.

Перш ніж дозволяти файл, переконайтесь, що він справжній:

Інсталятор має бути завантажений кнопкою з цієї сторінки або зі сторінки випусків на GitHub. Файл, отриманий іншим шляхом (месенджер, файлообмінник, чужий сайт), видаліть і завантажте наново.
Поверніть файл із карантину: «Безпека Windows» → «Захист від вірусів і загроз» → «Журнал захисту» → запис про файл → «Дії» → «Відновити». Запускати його поки не треба.

Відкрийте PowerShell (Пуск → наберіть PowerShell) і вставте три рядки. Якщо файл лежить не в «Завантаженнях», замініть шлях у першому рядку:

$f = "$env:USERPROFILE\Downloads\nyshporka-setup.exe"
$r = Invoke-RestMethod https://api.github.com/repos/SERGIUSH-UA/nyshporka/releases/latest
($r.assets | Where-Object name -eq 'nyshporka-setup.exe').digest -eq ('sha256:' + (Get-FileHash $f).Hash.ToLower())

True: файл збігається з останнім випуском на GitHub, спрацювання хибне. Запускайте інсталятор. Якщо Defender знову його забирає, у «Журналі захисту» оберіть «Дозволити на пристрої».
False: файл не той, або відтоді вийшов новий випуск. Не запускайте його: видаліть і завантажте наново кнопкою з кроку 2. Якщо й новий файл дає False, напишіть авторові.

Без помічника або з Python¶

Якщо Python або uv уже є, пакет ставиться з PyPI:

uv tool install "nyshporka[app,archives,htr]"   # або: pip install "nyshporka[app,archives,htr]"
nysh init                      # створити робочу теку
nysh doctor                    # перевірити машину
nysh serve                     # відкрити застосунок у браузері
nysh htr install               # середовище для моделей читання, разово
nysh models get                # моделі читання, ~225 МБ, разово

Однорядковий інсталятор для Windows без Python — у PowerShell:

irm https://raw.githubusercontent.com/SERGIUSH-UA/nyshporka/main/install/windows.ps1 -OutFile "$env:TEMP\nysh-install.ps1"
powershell -ExecutionPolicy Bypass -File "$env:TEMP\nysh-install.ps1"

Для досвідчених: набори, важелі інсталятора, де лежить дослідження

Набори. nysh init питає, чим ви користуватиметесь; змінити будь-коли — nysh sections, без перевстановлення.

набір	що є
`catalog`	каталоги, газетир, описи фондів — без моделей читання, економить ~2.5 ГБ
`amateur`	+ читання рукопису й гортач
`researcher` (типово)	+ пошук у прочитаному, облік, експорт
`lab`	+ розмітка рядків і дотренування моделей (`nysh train`)

Важелі. Однаково для скриптів і .exe:

що задаємо	`windows.ps1`	`unix.sh`	`.exe`
набір	`-Preset catalog`	`NYSH_PRESET=catalog`	`/PRESET=catalog`
склад пакета цілком	`-Source 'nyshporka[app,archives]'`	`NYSH_SOURCE=…`	—
конкретна версія	`-Version X.Y.Z`	через `NYSH_SOURCE`	вшита в файл
одна тека на все	`-Workspace D:\Genealogy\Нишпорка -Home_ D:\Genealogy\Нишпорка\.program`	—	`/WORKSPACE=D:\Genealogy\Нишпорка`
перенести вже поставлене	`nysh relocate D:\Genealogy\Нишпорка`	те саме	те саме
без питань	—	—	`/VERYSILENT`
без пака довідників	`-NoCatalog`	`NYSH_NO_CATALOG=1`	—
журнал	—	—	`/LOG=setup.log`
де жити дослідженню	`NYSHPORKA_WORKSPACE`	`NYSHPORKA_WORKSPACE`	`NYSHPORKA_WORKSPACE`

⚠ irm … | iex для скрипта Windows не працює (файл має UTF-8 BOM) — спершу -OutFile, потім -File.

Машина розробника. Інсталятор нічого не переставляє: uv і власний Python 3.12 лягають у теку застосунку, pyenv, conda і збірки під CUDA лишаються як були. Поза своїми теками — лише допис у PATH. sh -s -- --dry-run показує зміни й нічого не робить, NYSH_NO_MODIFY_PATH=1 не чіпає PATH. Перелік змін лягає в install-trace.txt.

Де лежить дослідження. Робоча тека (у командах — простір):

nysh init D:/Дослідження                      # обрати місце при створенні
export NYSHPORKA_WORKSPACE=D:/Дослідження     # закріпити для всіх команд
nysh --workspace D:/Дослідження doctor        # разово

Без змінної команди шукають nyshporka.toml угору від поточної теки. Куди дивиться застосунок зараз — nysh doctor, рядок «Робочий простір».

Mac з процесором Intel. Ставиться як усюди; nysh htr install бере Python і torch із conda-forge, бо PyPI не має для нього колес torch новіших за 2.2.2.

Відеокарта не потрібна. Без неї сторінка читається за ~20 с – 1 хв (залежно від процесора й того, скільки на сторінці рядків), із картою — за ~10–15 с. Прискорення картою — окремим кроком, його підкаже nysh doctor.