Grounded Citations

Обоснование ответов и документов проверяемыми, процитированными источниками.

Метаданные навыка

Справочник: полный SKILL.md

Grounded Citations

Каждое утверждение, взятое из внешнего источника, получает встроенную нумерованную ссылку и список Sources: — как в Perplexity. Скрипт-реестр сам владеет соответствием url → [n], так что номера и URL берутся из результатов поиска, а не из памяти модели — модель лишь подставляет небольшие числа, которые ей выдали.

Для ответственных задач тот же реестр служит и цепочкой проверки фактов: к каждому источнику прикрепляются дословные цитаты (они отклоняются, если буквально не встречаются в тексте загруженной страницы), утверждения из знаний модели помечаются [unverified], а verify --evidence завершается с ошибкой на любом черновике, чьи процитированные источники не подкреплены доказательствами.

Этот навык охватывает ответы в чате, письменные документы (markdown, PDF, docx, слайды) и исследовательские отчёты. Он не покрывает академические BibTeX-конвейеры — для конференционных статей используйте навык arxiv, который данный навык питает данными (см. references/citation-formats.md).

Когда использовать

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

• Исследования, сравнения, новостные сводки, «каково текущее состояние X»
• Любой сохраняемый на диск результат, который цитирует, пересказывает или излагает внешние факты — отчёты, брифы, документация, презентации, страницы вики
• Поиск фактов, когда пользователь захочет проверить вашу работу
• Синтез из нескольких источников, где нужно указать, какому источнику принадлежит каждое из противоречащих друг другу утверждений

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

Предварительные требования

Ничего сверх стандартного набора инструментов. scripts/sources.py — чистый Python 3 на stdlib. Получение данных идёт через то, что настроено: web_search, web_extract, browser_navigate или terminal (curl, CLI-утилиты).

Расположение реестра: $HERMES_HOME/cache/citations/ledger.json (учитывает профиль). Переопределяется для конкретной задачи через --ledger <path> или HERMES_CITATION_LEDGER.

Как запустить

S=~/.hermes/skills/research/grounded-citations/scripts/sources.py

python "$S" reset                                  # начать чистый реестр
python "$S" add https://example.com/a --title "A"  # выведет: [1]
python "$S" add https://example.com/b --title "B"  # выведет: [2]
python "$S" list                                   # таблица реестра
python "$S" render                                 # блок Sources:
python "$S" verify draft.md                        # найти неверные ссылки

add идемпотентен и нормализует URL: одна и та же страница всегда получает один и тот же id в рамках реестра, поэтому идентификаторы остаются стабильными через много раундов поиска/извлечения.

Краткий справочник

Процедура

① Сбросьте реестр в начале задачи, результатом которой станет обоснованный ответ или документ. Пропустите сброс, если продолжаете работу над черновиком, чьи id уже в нём фигурируют, — так нумерация останется стабильной.

② Регистрируйте каждый источник в момент его получения. После каждого вызова web_search / web_extract / browser_navigate или запроса передавайте URL в sources.py add (или прогоняйте сырой JSON через sources.py ingest). Делайте это до написания текста. Регистрация постфактум, по памяти, — именно тот сбой, для предотвращения которого создан этот навык.

③ Пишите с цитированием по ходу черновика. Ставьте id в скобках сразу после каждого предложения, которое источник подтверждает:

Лёд плавает, потому что он менее плотный, чем жидкая вода.[1][2]

• Без пробела перед скобкой; каждый id — в своих скобках.
• Не больше 3 id на предложение. Цитируйте по предложениям, а не одной свалкой в конце.
• Только те id, что вернул реестр. Никогда не придумывайте id или URL.
• Утверждения из собственных знаний модели ссылки не получают.
• Противоречащие источники: приводите обе трактовки, каждую со своим id.
• Точные цифры, даты и имена цитируйте так, как их даёт источник; явно отмечайте пробелы («источник для X не найден»), а не сглаживайте их.

④ Добавьте блок Sources командой sources.py render --cited-in <draft>, чтобы соответствие id → URL формировалось механически из реестра, а не перепечатывалось вручную. Для форматов, отличных от markdown, выберите нужный --style и следуйте references/citation-formats.md в части размещения (сноски в docx, концевые сноски в PDF/LaTeX, слайд с источниками в презентациях, постраничные списки источников в вики).

⑤ Проверяйте перед сдачей — sources.py verify <draft> завершается с ненулевым кодом при неизвестных id, при расхождении блока Sources с реестром или (с --min-coverage) при слишком слабо процитированном тексте. Исправьте и запустите заново.

⑥ Ответы в чате проходят те же шаги, только черновик — сам ответ: зарегистрируйте источники, цитируйте по ходу, завершите отрисованным списком Sources:. Для короткого ответа блок можно отрисовать через sources.py render --only <ids>, не записывая в файл.

Прочёсывание нескольких платформ

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

Навыки reddit-reading и rss-feeds — опциональные. Если их нет, поставьте заранее: hermes skills install official/social-media/reddit-reading или hermes skills install official/research/rss-feeds.

Каждый адрес с каждого маршрута регистрируйте в реестре по мере поступления (шаг ②). Мнение и измерение держите порознь: тред на Reddit — свидетельство того, что пользователи о чём-то сообщают, а не того, что это правда; подкрепите его первичным источником либо пометьте как оценку настроений. Пробелы в покрытии по каждой платформе сообщайте вслух («поиск по Reddit не дал ничего свежее марта»), а не сужайте молча выводы до того, что сработало.

Режим проверки фактов

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

① Прикрепите дословную цитату к каждому источнику. После извлечения страницы сохраните её текст в файл и прикрепите предложение(я), несущее(ие) каждое утверждение:

python "$S" quote 1 --text "Лёд примерно на 9% менее плотен, чем жидкая вода." --from page1.txt

Цитата отклоняется, если не встречается дословно в тексте доказательства (без учёта пробелов, регистра и markdown-разметки — встроенные ссылки вида _[ERAP1](https://…)_ в извлечённом тексте сопоставляются с обычной прозой, которую видит читатель), так что перефразировка или неточно вспомненная цифра не смогут сойти за доказательство. Копируйте из полученного текста, никогда не перепечатывайте вручную. Цитируйте предложение так, как его видит читатель, — сопоставитель сам «видит» сквозь разметку экстрактора, вам не нужно воспроизводить синтаксис ссылок или экранированные звёздочки в цитате.

② Помечайте утверждения из знаний модели меткой [unverified]. Значимое утверждение, для которого не нашлось источника, получает явную метку вместо ссылки:

Рефакторинг, вероятно, был выполнен до релиза 2.0.[unverified]

verify --min-coverage засчитывает предложения с [unverified] как покрытые — цель в том, чтобы у каждого утверждения было заявленное происхождение, а не в том, чтобы ссылка стояла на каждом предложении. Если ключевое утверждение можно проверить — проверьте его; [unverified] предназначена для того, что действительно нельзя проверить, а результат проверки фактов, где преобладают метки [unverified], должен об этом сообщать в своём резюме.

③ Сверяйте спорные факты со вторым независимым источником. Когда два источника расходятся, цитируйте обе трактовки с их собственными id и цитатами и укажите, какой вы считаете более весомым и почему. Один источник — это просто сообщение; два независимых источника — уже подтверждение.

④ Проверьте через фильтр доказательств и отрисуйте блок доказательств:

python "$S" verify report.md --evidence --min-coverage 0.5
python "$S" render --style evidence --replace-in report.md

--evidence проваливает черновик, если у любого процитированного источника нет прикреплённой цитаты. Стиль отрисовки evidence выводит цитаты каждого источника под его URL, так что итоговый документ показывает цепочку утверждение → источник → точный подтверждающий текст, без ничего на веру. Используйте --replace-in <draft>, чтобы переписать существующий блок Sources на месте (идемпотентно — безопасно перезапускать после добавления новых цитат); --cited-in выводит результат в stdout. Оба варианта выводят заголовок ## Sources (--style plain выводит Sources:).

Что считает --min-coverage. Покрытие — это предложения с заявленным происхождением / предложения с прозой. Предложением с прозой считается непустой фрагмент строки из 4+ слов после блока Sources; заголовки (#), строки таблиц (|) и блоки кода в оградках (```) отбрасываются; маркеры цитат > удаляются. Происхождение считается заявленным, если есть либо ссылка [n], либо метка [unverified], так что предложение с обоими засчитывается один раз. Сначала запустите verify без порога и посмотрите строку info: stats:, чтобы увидеть счётчики перед выбором значения.

Типичные ошибки

• Регистрация после написания. Реестр должен наполняться из вывода инструментов, а не восстанавливаться по черновику — это возвращает именно тот риск галлюцинированных URL, от которого избавляет нумерация.
• Перенумерация посреди задачи. Никогда не редактируйте id в черновике вручную. Id — это идентичность записи в реестре; если черновик цитирует [4], [4] должен оставаться тем же источником. Запускайте reset только между задачами.
• Перепечатывание URL в блок Sources. Всегда используйте render. URL, набранный вручную, — это непроверенное утверждение.
• Цитирование сниппета поиска так, будто вы прочли страницу. Описание из web_search подтверждает только то, что в нём буквально написано. Если утверждению нужно тело страницы — сначала извлеките страницу через web_extract и цитируйте её.
• Избыточное цитирование. Три id на предложение — потолок; ссылка на каждой части предложения делает текст нечитаемым и скрывает, какой источник несёт основную нагрузку.
• Цитирование реестра в артефактах кода/конфигурации. Комментарии с источниками уместны в текстовых результатах и заголовках документов, но не внутри генерируемого кода.
• Параллельные субагенты. У каждого субагента свой рабочий каталог; если их результаты потом объединяются, направьте всех на один реестр через --ledger (или HERMES_CITATION_LEDGER), иначе их id столкнутся.
• Цитирование сниппета вместо страницы. Цитаты-доказательства должны браться из извлечённого текста страницы, а не из описания в результатах поиска — сначала web_extract, сохраните текст, затем quote --from этого файла.
• Перефразировка в quote --text. Проверка на дословность отклонит такую цитату; решение — найти реальное предложение, а не подбирать формулировку, пока она не совпадёт.
• Использование [unverified] как лазейки. Эта метка — для редкого утверждения, которое действительно нельзя подтвердить источником; если ею помечено большинство предложений, задаче нужно больше поиска, а не больше меток.
• Ручное редактирование блока Sources. Используйте render --replace-in <draft>; нарезка файла вручную рискует оставить устаревший или задвоенный блок, который затем отловит verify.

Проверка

python "$S" verify report.md --strict --min-coverage 0.5

Зелёный результат означает: каждая ссылка [n] в черновике существует в реестре, блок Sources перечисляет ровно процитированные id с URL из реестра, а доля процитированных предложений с источниками достигает порога. Читайте предупреждения даже при нулевом коде выхода — незадействованные, но зарегистрированные источники обычно значат, что какое-то утверждение потеряло привязку в процессе редактирования.