Що я вмію — і чим саме до цього дотягуюсь¶
Читати згори: спершу про дві поверхні, бо половина розчарувань тут — не «застосунок не вміє», а «я стукав не в ті двері».
🔴 Поверхонь дві, і повна з них — командний рядок¶
Операцій у реєстрі 76. Перелік tool'ів показує 18. Різниця — не борг і
не «ще не зробили»: перелік tool'ів має стелю (TOOL_LIMIT), за якою модель
перестає читати описи й починає вгадувати, а вгадування коштує дорожче за
відсутність інструмента.
| поверхня | скільки операцій | як звертатись |
|---|---|---|
| командний рядок | усі 76 | nysh op <ім'я> --args '<json>' |
| перелік tool'ів (MCP) | 18 | nysh_<ім'я_з_підкресленнями> |
nysh op workspace.info # без аргументів
nysh op pages.status --args '{"case": "230-1-4"}' # з аргументами
nysh op search.run --args '{"q": "Іваненко", "where": "decode"}'
Обидві поверхні — тонкі обгортки одного реєстру: та сама валідація, той самий
конверт відповіді, ті самі попередження. Розійтись вони не можуть — це
перевіряється тестом (test_triptych_parity.py), а не домовленістю.
🔴 Тому «tool'а немає» ніколи не означає «зробити не можна». Якщо ти
працюєш без MCP — ти не в обмеженому режимі, ти в повному. Якщо працюєш із
MCP — 58 операцій все одно лишаються за командним рядком, і серед них
geog.find (де взагалі є метрики цього села по ВСІХ фондах),
archive.fond (чи входить опис у ключ справи), parish.in_case (які села
всередині зведеної книги — до того, як її читати), read.plan, library.list.
Розвідка: імена, аргументи, причини¶
Найдорожче тут — вгадувати назви полів. Не вгадуй, питай:
nysh ops # перелік для ока: ✎ пише · ⏳ довга · 🤖 є tool
nysh ops --agent # лише те, що видно через перелік tool'ів
nysh ops --json # усе разом зі схемами аргументів, машинно
nysh op pages.note --describe # одна операція: схема + ПОВНИЙ докстрінг
--describe нічого не виконує — навіть у мутації. Це важливо: інакше єдиним
способом дізнатись аргументи запису лишався б виклик «щоб подивитись, що
відповість», тобто запис у чуже сховище заради довідки.
🔴 --describe віддає те, чого немає більше ніде. У переліку tool'ів до
тебе доїжджає однорядковий підпис; у докстрінгу операції лежить причина, чому
вона така, — із замірами й ціною помилки («дефолт — рядок, бо сторінка коштує
моделі вчетверо дорожче», «позиційний розбір уже віддав 2944 справи з нулем
аркушів, і за числом рядків це виглядало успіхом»). Якщо поведінка здається
дивною — причина майже напевно там, і прочитати її дешевше, ніж здогадуватись.
🔴 Довга робота: два режими, і вибір робиться ДО виклику¶
Читання справи й завантаження кадрів — години. Такі операції не повертають результат, вони повертають посилання на завдання, а завдання живе в черзі. Черга є тільки в піднятому застосунку.
| що робиш | черги немає (типово) | черга є (nysh serve в іншому вікні) |
|---|---|---|
| прочитати справу | nysh read <тека> — читає в процесі, друкує прогрес |
nysh_read_start → стан через nysh_job_query |
| завантажити кадри | nysh get <джерело> <ref> --out <тека> — маніфест ДО качання |
nysh_acquire_start → nysh_job_query |
| перезібрати реєстр | nysh cases build |
кнопка в застосунку |
Синхронний шлях — не запасний, а основний: прогін ставлять на ніч, часто по ssh, і вимагати для найдовшої роботи піднятого браузера означало б зробити її найкрихкішою.
Викликана без черги, довга операція відповідає відмовою «підніміть nysh
serve» — чесно, але дізнається про це той, хто вже витратив хід. Тому режим
названо в докстрінгу: nysh op read.start --describe каже це перед тим, як
ти щось запустиш.
⚠ nysh read не має ідемпотентності. Повторний запуск = другий прогін по
тій самій теці, який б'ється з першим за карту. Перед запуском перевір, чи
читання вже не йде (nysh op runs.list).
Чотири кроки, які роблять раз на сесію¶
Tool'ів для них немає навмисно — це не робота дослідження, а орієнтація в
чужому просторі. Через nysh op вони теж доступні (setup.check,
profile.show, sections.show), але дружня команда друкує їх зрозуміліше.
| потрібно | команда | чому це важливо |
|---|---|---|
| стан машини | nysh doctor --json |
хмарна тека й CPU-збірка torch — усе, що потім виглядатиме як «зависло» |
| чий рід шукаємо | nysh profile |
без профілю всі написання прізвища доводиться пригадувати самому — і нуль виходить із неповного набору |
| увімкнені частини | nysh sections |
вимкнена секція відмовить посеред роботи, а не на початку |
| перезібрати реєстр | nysh cases build |
після твоїх же записів реєстр застаріває |
Карта дій¶
Колонка «tool» заповнена там, де операція є ще й у переліку tool'ів; порожня
клітинка означає лише «через nysh op».
Орієнтація¶
| операція | tool | що прочитати у відповіді |
|---|---|---|
workspace.info |
nysh_workspace_info |
locked_by: не null — людина працює в браузері просто зараз |
cases.list |
nysh_cases_list |
stale — якщо is: true, числам вірити не можна |
material.look |
nysh_material_look |
чи взагалі придатне до читання: скільки кадрів, одна справа чи багато |
sources.list |
nysh_sources_list |
caps — не кожне джерело вміє все |
library.list |
— | що вже на руках і який вердикт винесла людина |
runs.list |
— | що вже прочитано і чим |
Знайти матеріал¶
| операція | tool | що прочитати |
|---|---|---|
catalog.search |
nysh_catalog_search |
coverage і попередження: у яких каталогах шукали. Шифра в запиті («127-1078-1662») веде адресним маршрутом: address у відповіді, address_route у попередженнях, каталоги при цьому НЕ прочісувались |
catalog.browse |
nysh_catalog_browse |
— |
catalog.manifest |
nysh_catalog_manifest |
обсяг у байтах: справа буває 30 ГБ |
geog.find, geog.card |
— | де є метрики села по всіх фондах, а не лише в православному розділі |
archive.fond |
— | 🔴 чи входить ОПИС у ключ справи цього архіву — недогляд тут уже злив дві книги в одну справу |
fond.list, fond.rows |
— | що описано й що з того вже в нас |
Читати й дивитись¶
| операція | tool | що прочитати |
|---|---|---|
page.text |
nysh_page_text |
lines — готовий перелік рядків; geometry.has |
page.view |
nysh_page_view |
note — чи не підмінили рядок сторінкою |
page.lines |
— | рамки рядків, коли треба клікати по знімку |
read.plan |
— | чим і як читатимемо — до запуску: письмо, модель, скільки кадрів |
🔴 Дефолт page.view — рядок, і не міняй його без потреби. Ціла сторінка
коштує моделі приблизно вчетверо дорожче за вирізку рядка, а звірок за сеанс
бувають десятки. Сторінку бери свідомо: коли потрібен контекст навколо запису
(заголовок, ліва колонка формуляра, сусідні акти).
Навколо рядка домальовується рамка. Без неї ти бачиш кілька рядків і не знаєш, який із них оцінюєш, — і чесно оцінюєш не той.
Подивитись на рядок із термінала можна — перевірено:
nysh op page.view --args '{"run": "…", "page": "0012.jpg", "line": 3}'
Поле image — data URL (data:image/png;base64,…); розкодуй base64 у файл і
відкрий його засобами свого середовища. 🔴 Це не обхідний маневр, а нормальний
шлях: якщо ти вирішив, що без tool'а звірка неможлива, ти закриєш КРОК 4 —
єдиний, на якому кандидат стає знахідкою, — і подаси людині текстовий здогад
замість зображення.
Шукати й записувати¶
| операція | tool | що прочитати |
|---|---|---|
search.run |
nysh_search_run |
знаменник у попередженні + line_index кожного хіта; role/rtype/axis звужують і потрапляють у coverage |
pages.status |
nysh_pages_status |
перед переглядом, не після |
pages.note ✎ |
nysh_pages_note |
— |
records.add ✎ |
nysh_records_add |
replace стирає всю справу й вимагає confirm числом |
export.case |
nysh_export_case |
кожен рядок несе скан |
pages.show |
— (командний рядок) | сховище як воно є: agent, noted, один запис за rid |
case.register ✎ |
nysh_case_register |
— |
⚠ line_no і line_index — різні числа. Перше для людини (з одиниці),
друге — індекс рамки для page.view (з нуля). Передаси не те — побачиш
сусідній рядок і не помітиш цього.
⚠ Твої записи нічим не стримані¶
Мутації (pages.note, records.add, case.register) пишуть на диск
одразу: без підтвердження, без токена, без блокування. Якщо людина працює в
браузері паралельно, ви пишете в те саме сховище.
І кожен твій успішний запис застарює реєстр людини — вона побачить у себе
«⚠ зріз застарів». Це нормально й задумано, але означає: після партії записів
виконай nysh cases build, інакше і твій наступний cases.list, і її екран
показуватимуть учорашню картину.
Позначку «пише на диск» видно до виклику: ✎ у nysh ops, поле
"mutates": true у --describe.
🛑 Чого немає навмисно¶
Тут різниця принципова: попередній розділ — про те, чого немає в переліку tool'ів; цей — про те, чого немає ніде й для тебе.
| немає | чому |
|---|---|
cases.bind серед агентних |
прив'язка «нічийого» прогону до справи — рішення людини, яке перебиває всі автоматичні канали. Правдоподібна прив'язка = чужий декод під правильною шифрою, з якого потім цитують знахідки |
library.verdict серед агентних |
вердикт «наше / не наше» виносить дослідник. Твоя частина — покласти кандидата з кропом |
sections.set, sample.install серед агентних |
переналаштування застосунку й розгортання зразка — не робота дослідження |
Ці операції існують і доступні nysh op, але виконує їх людина, а не ти:
побачивши їх у переліку, не роби з цього дозволу.
Якщо тебе питають, чого бракує¶
Канону тут немає: особи, родини, факти й цитати — окремий шар, і в цьому пакеті
його не редагують операціями. Знахідка доходить до дослідження як запис у
сховищі прочитаного (pages.note, records.add) плюс кроп для ока; звести їх у
родовід — робота людини в її власному сховищі.
Не намагайся підмінити це: запис «особи» кудись у простір створить четверту копію факту, яка почне розходитись із рештою.