tesserae ingest

<!-- translations:start -->

English · 한국어 · 中文 · 日本語 · Русский · Español · Français · Deutsch

<!-- translations:end --> Вливает один файл документа или URL в базу знаний.

Использование

tesserae ingest <input>... [--title T] [--source-kind K] [--full] [--dry-run]

<input> — один или несколько локальных путей к файлам или http(s)-URL. URL скачиваются, конвертируются в markdown и сохраняются под data/ingested/<slug>.md с provenance-фронтматтером (source_url, fetched_at, content_sha256 и arxiv_id, когда он распознан), а затем вливаются. Локальные файлы извне проекта копируются в data/ingested/, чтобы стать отслеживаемыми источниками (последующая полная компиляция воспроизводит их идентично).

Инжест URL требует опционального экстра:

pip install tesserae[ingest-url]

Как это работает

По умолчанию ingest вливает новый источник через инкрементальную компиляцию — он не переизвлекает весь корпус — и результат байт-в-байт идентичен полной компиляции (автоматический откат к полной перекомпиляции гарантирует корректность в любом случае, который инкрементальный путь не может обработать). Передайте --full, чтобы принудить полную перекомпиляцию всего корпуса.

Флаги

• --full — принудительная полная перекомпиляция всего корпуса.
• --dry-run — скачать и сообщить, что было бы влито; граф не пишется.
• --title — переопределение заголовка, полезно для «голых» URL.
• --source-kind — переопределить классификацию источника.

Слой концептов (--extractor)

Tesserae — это LLM-wiki, поэтому compile строит слой концептов/утверждений по умолчанию (--extractor llm): он прочитывает каждый документ через настроенного LLM-провайдера — codex / claude / Anthropic API, согласно llm_provider — и порождает концепты, утверждения, возможности, технические термины, диапазоны свидетельств и типизированные рёбра между ними. Именно этот слой позволяет графу отвечать на вопрос «что это за идея и как она связана», а не только «в каком файле это сказано».

tesserae compile # LLM concept layer, configured provider tesserae compile --llm-provider codex # force a provider for this run

Если LLM-бэкенд не настроен/не авторизован, compile деградирует до детерминированного экстрактора (только структура — источники, секции, явные ссылки) и предупреждает. Его также можно запросить явно — он быстрый, не требует ключей и байт-стабилен, режим для CI / воспроизводимости:

tesserae compile --extractor deterministic

Выбор аккаунтов, которые будут расходоваться (llm_claude_config_dirs)

С провайдером claude Tesserae перебирает ваши авторизованные аккаунты Claude CLI: аккаунт, упёршийся в лимит, уступает место следующему, вместо того чтобы обрушить остаток запуска в детерминированное извлечение. По умолчанию автоматически находятся все каталоги ~/.claude*.

Провайдер codex работает так же — перебирает аутентифицированные домашние каталоги ~/.codex* (каталог считается домом, только если содержит auth.json) и настраивается ключом llm_codex_homes. У каждого провайдера свой ключ, потому что у каждого своя раскладка аккаунтов на диске: каталоги конфигурации Claude CLI и домашние каталоги Codex невзаимозаменяемы:

Чтобы точно задать, какие аккаунты можно расходовать и в каком порядке, укажите llm_claude_config_dirs в .tesserae/config.json (проект) или ~/.tesserae/config.json (глобально):

{
  "llm_claude_config_dirs": [
    "/Users/you/.claude-work",
    "/Users/you/.claude-personal"
  ]
}

Этот список авторитетен — ничего вне его не пробуется. Он также важнее внешней переменной CLAUDE_CONFIG_DIR, которую наследует каждый процесс, порождённый сессией Claude Code, и которая иначе привязала бы всю компиляцию к квоте одной этой сессии. Если ничего не настроено, CLAUDE_CONFIG_DIR по-прежнему берётся как первый аккаунт для попытки.

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

tesserae compile --changed-only --retry-fallbacks

С учётом стоимости (selective-llm) — через LLM идут только совпадающие документы, остальные — детерминированно:

tesserae compile --extractor selective-llm \ --llm-include "docs/**/*.md" --llm-limit 20

Те же флаги работают у tesserae extract <paths> (автономно) и tesserae compile <paths> (ad-hoc инжест путей).

Настройка:

• --llm-provider codex|claude|anthropic — переопределить провайдера (по умолчанию: llm_provider из конфига).
• --llm-model — модель для экстрактора (по умолчанию: модель провайдера по умолчанию).
• --llm-include <glob> — для selective-llm: какие файлы идут через LLM (повторяйте для нескольких; паттерны матчатся в любом месте абсолютного пути, например "*docs/superpowers*").
• --llm-limit N — ограничить, сколько файлов достигает LLM (остальные остаются детерминированными).

Нет таймаута по умолчанию. Большой дизайн-документ порождает много JSON и может занять минуты; извлечение выполняется до конца, а не обрывается молча (таймаут — только по явному запросу).

Устойчивость на реальных корпусах. Один шумный или медленный документ никогда не прерывает всю компиляцию: сбой LLM на документе (аутентификация, ошибка, неразбираемая генерация) откатывает этот документ на детерминированную базу, ребро или тип узла вне контролируемого словаря отбрасывается, а кеширование по ключу контента означает, что перекомпиляция неизменённых документов переиспользует прежнее извлечение.

Имена экстракторов claude-cli / selective-claude (и флаги --claude-*) — устаревшие псевдонимы для llm / selective-llm (и --llm-*); они всё ещё работают, но выводят замечание об устаревании.

Управление областью компиляции (sources)

tesserae compile (без аргументов) компилирует каталоги из списка sources проекта. Управляйте этим списком — локальным или глобальным — через подкоманды sources:

tesserae sources add docs # local: inside the project (stored project-relative) tesserae sources add /data/shared-notes # global: an absolute path outside the project tesserae sources add ../sibling-project # global: a relative path that escapes the root tesserae sources list # shows each source tagged local/global, flags missing tesserae sources remove docs

Путь внутри проекта хранится относительно проекта (переносимо); всё вне — хранится абсолютно. Оба разрешаются во время компиляции, поэтому глобальный источник компилируется так же, как локальный. (Добавления дедуплицируются по разрешённому расположению, поэтому абсолютная и ../-относительная формы одного и того же каталога никогда не считаются дважды.)

Связанные команды

• tesserae compile (без аргументов) переизвлекает весь отслеживаемый корпус.
• tesserae ingest <x> добавляет один источник инкрементально.
• tesserae code ingest порождает граф кода из исходников Python (другая команда).