Разбор анализов с границами: health-advisor

Начнём с неудобного вопроса: зачем нужен помощник по анализам, если есть врач?

Знакомься: Мира. Ты уже встречал её в курсах по dz и по конвейеру фич — там она собирала инструменты для разработчиков. Сегодня задача другая и куда более личная: у неё на руках стопка бланков из лаборатории, выписка из клиники и назначение, а приём у врача через две недели. Мира хочет прийти на этот приём подготовленной: понимать, что означают числа, какие вопросы задать и чего в её данных не хватает.

@dzhechkov/health-advisor — это набор навыков для Claude Code: 20 базовых компонентов ядра плюс 25 расширенных медицинских навыков. Исходники и публичное зеркало — github.com/djd1m/dz-harness.

Ключевая идея пакета в одной фразе: это медицинский помощник с границами компетенции. Не «второй врач» и не диагност. Он делает три вещи, которые человеку делать долго и скучно:

1. читает — распознаёт PDF и фото бланков, складывает значения в одно место;
2. сопоставляет — сверяет число с референсом лаборатории, с клинической целью и с условиями, при которых кровь брали;
3. предъявляет доказательство — рядом с каждым утверждением показывает источник и честно говорит, открывал ли этот источник хоть кто-нибудь.

Компромиссы: пакет даёт структуру и провенанс — ты видишь, откуда взялось каждое число, и можешь спорить с машиной. Но он не ставит диагноз, не назначает лечение и не заменяет приём. Всё, что он производит, — материал для разговора с врачом.

💬 Просто попроси.
- «Расскажи, что умеет health-advisor» → ассистент откроет README пакета и перескажет разделы «Что умеет» и «Что включено».
- «У меня есть анализы, помоги подготовиться к приёму» → ассистент предложит установить пакет и начнёт с разбора условий забора.

Мира открывает пустую папку ~/health-research и хочет получить рабочий инструмент до того, как остынет кофе.

Установка навыков делается одной командой:

npx @dzhechkov/health-advisor init

Что именно происходит. Глагол init кладёт навыки в .claude/skills/ как обычные (bare) навыки — Claude Code подхватывает их сам при открытии проекта, без маркетплейса и на любой версии. Дальше они вызываются напрямую: мастер-оркестратор — /health-advisor, отдельные медицинские навыки — /health-advisor-lab-results, /health-advisor-drug-interaction-checker и так далее.

Зачем префикс health-advisor-. В твоём проекте уже могут жить навыки с именами explore или deep-research из других пакетов. Префикс исключает коллизию имён: два разных explore не подменяют друг друга.

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

• init --base — только ядро: оркестратор, модули и промпты;
• init --extended — только 25 медицинских навыков;
• init --dir <path> — своя директория установки;
• list — показать, что вообще есть в пакете;
• validate — проверить, что установленные навыки на месте и целы.

Компромиссы: установка «всё сразу» проста и не требует размышлений, но занимает место в контексте проекта; --base экономнее, однако тогда базовые модули идут общим исследовательским путём и не дают той точности, что специализированные навыки.

💬 Просто попроси.
- «Установи health-advisor в эту папку» → ассистент выполнит npx @dzhechkov/health-advisor init и покажет список установленного.
- «Проверь, что навыки встали корректно» → ассистент запустит validate и назовёт каждый навык, которого не хватает.

Самое приятное открытие для новичка: команды знать необязательно.

Мира печатает в чат обычную человеческую фразу: «У меня повышен холестерин и низкий витамин D, что делать?» Это и есть свободный запрос без указания команды — оркестратор сам решает, какие модули поднять и в каком порядке.

Что происходит дальше, по шагам:

1. Распознавание. Мастер-навык видит тему «анализ здоровья» и выбирает модули Profile и Medications.
2. Уточнение. Навык explore задаёт встречные вопросы: какой именно холестерин повышен — ЛПНП, триглицериды? Есть ли свежие анализы? Без ответов дальше дело не идёт: вывод, построенный на догадке, хуже, чем отсутствие вывода.
3. Исследование. goap-research-ed25519 ищет в PubMed, и у каждого факта появляется адрес источника, потолок доверия к его типу и явно названный уровень уверенности.
4. Рекомендации. problem-solver-enhanced собирает план с разбором пользы и риска.
5. Полный разбор. По фразе «проведи полный анализ» включается трёхфазный путь analyst-manual-full с контрольными точками, где Мира может вмешаться.

Результат — отчёт в Markdown и HTML со ссылками на исследования, оценкой качества доказательств и медицинской оговоркой.

Одна честная оговорка про подписи: криптографическая проверка Ed25519 включается только там, где у источников реально есть ключи издателей. PubMed и Cochrane подписанных материалов не поставляют, поэтому строгий режим честно вернёт «цель недостижима» вместо выдуманного «проверенного» плана.

Компромиссы: свободный запрос снимает порог входа, но делает путь менее предсказуемым — чем подробнее описание (возраст, диагнозы, текущие препараты), тем точнее маршрут.

💬 Просто попроси.
- «У меня повышен холестерин и низкий витамин D, что делать?» → ассистент поднимет модули профиля и лекарств и начнёт с уточняющих вопросов.
- «Проведи полный анализ безопасности этого препарата» → ассистент запустит трёхфазный путь с контрольными точками.

Вот момент, ради которого стоит прочитать весь курс.

Мира приносит значение: общий тестостерон 7.9 нмоль/л. Оно ниже референсной полосы, и напрашивается слово «дефицит». Но то же самое число получается у человека, который голодал 56 часов, — и по ЛГ/ФСГ эти две ситуации неразличимы. Гипофиз не умеет отличить артефакт голодания от настоящего дефицита.

Отсюда правило: условия забора крови до интерпретации, а не после. Навык preanalytical-guard отрабатывает раньше, чем движок интерпретации увидит число. Фильтровать готовый вывод поздно: фраза уже произнесена.

Что кодируется для каждого показателя — это данные в реестре, а не проза, и каждая запись обязана нести величину эффекта и источник, иначе пакет просто не загрузится:

• голодание 48 часов и дольше — значение придерживается (withhold), потому что артефакт неотличим от дефицита;
• открытое окно восстановления после голодания — тоже придерживается: голодание кончилось, а искажение — ещё нет;
• сон 5 часов и меньше в среднем за неделю — значение допускается, но оговорка от него неотделима;
• общий тестостерон без ГСПГ — блокировка: сначала назначить сопутствующий анализ;
• первое значение ниже референсной полосы — повтор до любых выводов;
• условия неизвестны — это полноценное состояние conditions_unknown, а не «нет данных».

Тонкость, которую легко пропустить: величина эффекта сообщается, но никогда не применяется. Никакого «значения, исправленного на −34 %», в отчёте не появится: это была бы вторая величина, неотличимая от измерения.

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

💬 Просто попроси.
- «Проанализируй мои анализы крови» → ассистент сначала соберёт условия забора и только потом перейдёт к интерпретации.
- «Покажи аудит условий забора без выводов» → ассистент вызовет preanalytical-guard напрямую и покажет, что придержано и почему.

Мира смотрит на бланк: апоB 118 мг/дл, референс 66–133, статус «в норме». Успокоиться? Не спешим.

Референсный интервал — это диапазон, в который попадает бо́льшая часть популяции. Клиническая цель — это то, где следует быть именно тебе при задокументированном состоянии. Это два разных вопроса с разными источниками истины, и одно поле «статус» не может ответить на оба сразу: один ответ молча затирает другой. Поэтому в пакете живёт клиническая цель отдельно от лабораторного референса.

Два случая из практики:

• апоB 118 мг/дл при референсе 66–133 читается как «в норме», но при документированном атеросклерозе применимая цель — ниже 80;
• насыщение трансферрина 48 % при референсе 16–54 читается как «в норме», хотя для женщин настороженность по перегрузке железом начинается уже с 45 %.

Навык clinical-targets показывает оба числа и вычисляет расхождение как поле, а не как фразу, которую кто-то мог забыть написать. В выводе рядом стоят: значение, референс лаборатории с источником, цель с дословной цитатой порога, кому этот порог адресован, сверка контекста пациента по полям — и рамка «это не диагноз».

Запускается так:

node .../skills/clinical-targets/engine/cli.js examples/apob-field-case.json

Фраза «выше цели» допустима только вместе с обоими числами, цитатой источника и рамкой. Это не договорённость на ревью, а конструктор: объект утверждения невозможно собрать без всех трёх частей, а значит, и напечатать нечего.

Компромиссы: два числа рядом честнее одного вердикта, но читать их сложнее, а сами пороги в примерах помечены как заявленные, а не как открытые инструментом. Расширяется данными: новый порог — это JSON-файл в реестре, без единой правки кода.

💬 Просто попроси.
- «Мой апоB 118 при референсе 66–133, у меня атеросклероз — это нормально?» → ассистент покажет референс и клиническую цель рядом с пометкой о расхождении.
- «Переведи 1.06 г/л в мг/дл и сравни с порогом» → ассистент сделает перевод единиц и сравнение с явным допуском.

Есть ошибка, которая не ловится ни подписью, ни проверкой ссылки: уверенный пересказ непрочитанного.

Мира читает отчёт, где стоит ссылка на исследование. Ссылка живая, запись подписана, всё выглядит надёжно. Вопрос, который никто не задаёт: а текст по этой ссылке кто-нибудь открывал?

Поэтому у факта две независимые оси:

1. Доверие к записи — запись не подменили после подписания. Значения: подписана издателем, самозаверена, не проверена.
2. Класс доказательства источника — источник реально открывали. Значения: FETCH_VERIFIED (скрипт выполнил запрос и получил тело ответа), LISTING_ONLY (видели только карточку из выдачи), ASSERTED (утверждение без открытия).

Факт бывает подписанным и ASSERTED одновременно — это законно, выразимо и опасно.

Правила, которые из этого следуют:

• ASSERTED в отчёт не попадает вовсе;
• LISTING_ONLY допускается только с видимой пометкой рядом с каждым упоминанием;
• итоговая уверенность равна самому слабому звену из трёх: подпись, доказательство, тип источника. ASSERTED даёт ноль — это не слабое доказательство, а его отсутствие.

Проверяет это гейт, который возвращает код выхода, а не совет:

python3 scripts/check_report_evidence.py --report report.md --facts facts.json

Честная граница, которую печатает сам инструмент: FETCH_VERIFIED означает «запрос выполнен и получено тело с таким хешем в такую дату». Это не значит, что источник авторитетен, что утверждение из него следует и что его правильно поняли. Это провенанс, а не истина.

Компромиссы: дисциплина классов делает отчёт скучнее и короче — многое просто нельзя написать. Взамен читатель про каждую строку знает, чем именно она подкреплена.

💬 Просто попроси.
- «Проверь мой отчёт перед отправкой врачу» → ассистент прогонит гейт доказательств и назовёт каждое нарушение.
- «Откуда это утверждение и открывал ли кто-нибудь источник?» → ассистент покажет класс доказательства для каждого факта.

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

Мира сталкивается с двумя способами промахнуться, и оба встречались в реальной работе.

Первый: число измеряли не на тех людях. «Похудение поднимает тестостерон» измеряли у мужчин с ИМТ 30 и выше — а перед тобой женщина с ИМТ 24. «Омега-3 повышает ЛПНП на 44 %» наблюдали при триглицеридах от 800 мг/дл — а в разбираемом бланке 190. Число настоящее — просто не про него.

Второй: относительный риск без абсолютного. «Риск инфаркта выше в 21 раз» — это один избыточный случай на 1394 человека. «Риск удваивается» — это 4 случая на 1000 за 25 лет. В каждой паре оба предложения верны; интерпретируемо только одно, а цитируют обычно другое.

Отсюда — применимость к этому пациенту и абсолютный риск как обязательные поля, а не как пожелание:

• население исследования — обязательный аргумент без значения по умолчанию: пропустил — и ошибку выдаст сам язык;
• сопоставление даёт четыре вердикта: full, partial (пациент мог бы участвовать, но эффект мерили не от той стартовой точки), none (критерий отбора его исключает), unknown (ось не указана). И unknown никогда не сворачивается в partial: неустановленный критерий — это не более мягкое совпадение;
• относительный эффект не ходит в одиночку: рядом либо реальные абсолютные числа, либо явное «базовый риск не установлен» с названной причиной. Число NNT вычисляется из абсолютных чисел, а при невозможности возвращает названную причину, а не бесконечность.

Компромиссы: такой отчёт длиннее и требует от читателя усилия, зато перечисление расхождений ценнее самого вердикта — человек видит, по какой именно оси он не похож на участников исследования, и может переспорить машину.

💬 Просто попроси.
- «Это исследование вообще про таких, как я?» → ассистент сверит профиль с населением исследования и назовёт расходящиеся оси.
- «Переведи „риск выше в 21 раз“ в понятные числа» → ассистент покажет абсолютный риск и NNT либо честно скажет, что базовый риск неизвестен.

Клиника отдала выгрузку одним zip-архивом, и Мира стоит перед соблазном распаковать его руками. Именно так теряется всё, что делает медицинский корпус пригодным для работы.

Сравни, что даёт обычная распаковка и что даёт приём архива с проверкой sha256 до разбора:

1. Это точно тот архив? Обычная распаковка не знает. Здесь sha256 сверяется с дайджестом, полученным независимо от архива, до того как что-то распаковано.
2. Не запишет ли элемент файл вне папки? Пути с .., абсолютные пути и символические ссылки отвергаются по имени.
3. Не съест ли архивная бомба диск? Есть ограничения на число элементов, размер, степень сжатия и глубину пути — и по объявленным, и по фактическим байтам.
4. Что если сломается на середине? Не ляжет ничего: сначала промежуточная зона, потом один атомарный перенос.
5. Что вообще в корпусе? Опись sources/manifest.json — строка на файл: хеш, размер, тип, дата приёма.
6. Что пытались принять? Журнал sources/LOG.jsonl — строка на каждую попытку, включая отказы.

Команда выглядит так:

node .../bin/health-advisor.js intake-archive --workspace <dir> --file labs.zip

Повторный приём того же архива идемпотентен: ни байта по сети, ни байта на диск. А --verify перечитывает опись и пересчитывает хеш каждого файла — это проверка, а не самоотчёт.

Дальше появляется вторая половина истории — якорь источника. В заключении стоит число; через полгода вопрос: из какого документа оно взято и тот ли это ещё документ? Якорь — это адрес строки в описи, а не копия текста: в нём нет ни содержимого, ни ссылки для скачивания. При возврате к источнику хеш пересчитывается до чтения, и байты выдаются только при совпадении; при расхождении — отказ с названной причиной, и флага «прочитать всё равно» не существует.

Компромиссы: дисциплина приёма требует получить хеш от отправителя отдельным каналом и запрещает часть форматов (не-zip, зашифрованные архивы). Взамен корпус пациента становится тем, чему можно доверять спустя годы.

💬 Просто попроси.
- «Прими вот этот архив из клиники в мой рабочий каталог» → ассистент выполнит intake-archive и покажет опись принятых файлов.
- «Откуда взялось это число в заключении?» → ассистент разрешит якорь и предъявит исходный файл с пересчитанным хешем.

Год работы над одним случаем выглядит так: значения живут в переписке, проверенные источники — в разрозненных файлах, а «спросить об этом позже» теряется через месяц.

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

Навык case-state даёт случаю одно каноническое состояние — профиль, реестр фактов и открытые вопросы:

1. Профиль (profile.json). «Текущее» значение нигде не хранится: оно вычисляется свёрткой на явную дату. Вывод принимает значение только как расписку, выданную в этом же вызове.
2. Реестр фактов (facts.json). Запись адресуется парой «утверждение + источник»; повторная проверка дописывает историю, а не создаёт вторую запись. Истёкший срок годности даёт явное «устарело», а не тихо отдаёт старое значение.
3. Открытые вопросы (open_questions.json). Вопрос переживает сессию и всплывает по дате или по условию; открытый блокирующий вопрос не даёт построить вывод в своей области.

Пять глаголов с одинаковыми кодами возврата — 0 норма, 1 ожидаемый отрицательный ответ, 2 ошибка использования:

node .../skills/case-state/engine/cli.js profile validate profile.json 2026-01-01
node .../skills/case-state/engine/cli.js profile diff profile.json 2025-10-15 2026-04-15
node .../skills/case-state/engine/cli.js facts stale facts.json 2026-04-15

Честная граница названа прямо: гарантия связывает выводы, построенные через модуль. Свободная проза агента в чате никакому коду не подвластна, и пакет этого не утверждает. Расписка доказывает, что чтение было, но не то, что прочитанное значение — именно то, которое затем пересказали словами.

Компромиссы: состояние случая нужно вести — это дисциплина, а не магия. Взамен через полгода видно, что именно изменилось между заборами и какие вопросы созрели к сегодняшней дате.

💬 Просто попроси.
- «Что изменилось у меня между двумя последними заборами?» → ассистент выполнит profile diff и покажет разрыв между поколениями значений.
- «Какие открытые вопросы созрели к сегодняшнему дню?» → ассистент поднимет вопросы по дате срабатывания перед началом сессии.

Сложный случай — это несколько специальностей сразу: кардиология, фармакология, эндокринология. Каждая пишет своё, а кто-то потом собирает общий синтез. И вот тут теряются оговорки.

Мира видит это на своём примере: специалист написал «доза допустима при сохранной функции почек», а в синтез попало только «доза допустима». Текст стал короче, смысл — противоположным.

Отсюда гейт сохранности оговорок в консилиуме. Как он устроен:

1. Схема находок. Каждый специалист отвечает структурным JSON, а не прозой: обязательный список оговорок, и каждая оговорка привязана полями к тому, к чему относится, — к утверждению, дозе, популяции или значениям. Ответ, который не удалось разобрать, — это названный по имени упавший специалист, а не молчаливый пропуск.
2. Сверка по связке, а не по тексту. Гейт сравнивает множества привязок: оговорка, оказавшаяся под чужим утверждением, — это промах, даже если текст переписан дословно. Цитируемые значения сверяются побайтово, вместе с единицей и без округления.
3. Две раздельные оси. Полнота и точность считаются отдельно; вердикт — по худшей оси, никаких средних и композитных баллов. Выдуманные лишние оговорки не улучшают ни одну ось и отмечаются отдельно.
4. Ожидаемый состав. Флаг --expect перечисляет специальности; линия специалиста, которая упала и не написала файл, становится названным отказом, а не тихо исчезает из проверки.

По умолчанию гейт работает в теневом режиме: только отчёт, вывод не меняется. Принудительный режим включается двумя независимыми переключателями и требует одновременно --expect, --run-id и --report; отсутствие любого из них — это ошибка использования, а не «проверка прошла».

Рядом живёт экстренный триаж: детерминированный компаратор из 12 канонических порогов, где действие («скорая» или «врач в течение суток») — это данные строки таблицы, а не суждение. Чистый результат честно оформлен рамкой замкнутого мира: «ни один из 12 порогов не сработал» — это не «экстренности нет».

Честная рамка про сам пакет: он ставит схему, контракт синтеза, компаратор и гейт. Разворачивание параллельных специалистов — работа хоста, а не npm-пакета; приписать пакету оркестрацию было бы присвоением чужой возможности.

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

💬 Просто попроси.
- «Проверь синтез консилиума на потерю оговорок» → ассистент запустит гейт по папке с находками специалистов и покажет отчёт.
- «Есть ли в моих показателях что-то экстренное?» → ассистент прогонит триаж по 12 порогам и покажет действие из таблицы.

Последняя секция — про то, чего пакет не делает. Это не мелкий шрифт: у медицинского инструмента честные границы важнее списка возможностей.

Мира заканчивает курс с тремя вещами, которые стоит запомнить дословно.

Первое: это не медицинский прибор. Всё, что производит пакет, носит информационный характер. Не принимайте медицинских решений только на основании этих данных — проверяйте их с квалифицированным врачом. Пакет и построен как материал для разговора, а не как замена разговору.

Второе: приватность медицинских данных — это граница, а не намерение. Принятые документы никогда не попадают в общее хранилище паттернов — это проверено запретительным сканом по всей поверхности, а не обещано в документации. Медицинские уроки живут в отдельном хранилище <проект>/.health-brain, и логика простая: хранилище, которое не получает данные, не может их отдать — ни одной командой, включая те, которых ещё не написали. Фильтр на каждой команде — это дисциплина, отдельное хранилище — свойство.

Третье: веди медицинскую работу в отдельном каталоге. Разделение, о котором сказано выше, покрывает то, что пишет пакет, но не то, что харнесс записывает про разговор: текст твоих сообщений в чате попадает в общий журнал проекта независимо от пакета — эти данные входят в систему выше него. Лечение простое:

mkdir ~/health-research && cd ~/health-research

Тогда общее хранилище этого проекта само по себе медицинское, делить нечего, и всё лежит в одном каталоге, который можно осмотреть или удалить целиком. Не веди медицинские исследования внутри рабочего репозитория с кодом.

Компромиссы: цена изоляции названа честно — перенос знаний стал односторонним. Инженерные уроки приходят в медицинскую работу, а медицинская находка больше не всплывёт во время инженерной. Это менее ценное направление, и оно обменяно на изоляцию, которая не зависит от того, вспомнит ли о ней автор будущей команды.

Куда идти дальше: страница пакета на npm, публичное зеркало исходников и раздел README «Важно знать».

💬 Просто попроси.
- «Где сейчас лежат мои медицинские данные и уроки?» → ассистент покажет каталог .health-brain и журнал проекта.
- «Настрой отдельный каталог под медицинскую работу» → ассистент создаст рабочую папку вне репозитория с кодом и объяснит, что куда пишется.