livewiki

Документация, привязанная к коду, которая знает, когда она устарела.

livewiki превращает репозиторий в Markdown-вики, где каждая ссылка на код привязана к реальному индексированному символу. LLM пишет текст; livewiki делает детерминированную работу — планирует страницы, выполняет структурные антигаллюцинационные проверки написанного моделью, отслеживает, какие привязанные символы изменились, и сохраняет ваши правки.

Вики доступна любому агенту разработки через @livewiki/mcp — MCP-сервер (Model Context Protocol) с восемью инструментами для чтения, поиска и безопасной записи в вики.

livewiki view собирает автономный офлайн-сайт из вики — сгруппированную боковую панель, офлайн-поиск, диаграммы и тёмную тему:

Пример вики, созданной livewiki для MoneyPrinterTurbo-Plus — внешнего Python-репозитория.

Зачем

Техническая документация устаревает в тот момент, когда меняется код. livewiki делает это видимым и дешёвым для исправления, а не оставляет незамеченным:

• Детерминированные антигаллюцинационные проверки. Каждая ссылка на код должна указывать на реальный индексированный символ. livewiki verify читает вики заново с диска и завершается ошибкой на выдуманных символах, битых якорях и сигнатурах, которые больше не совпадают, — включая ссылки, которые LLM написала несколько секунд назад, без предварительного запуска index и без затрат токенов. Проверка структурная, а не семантическая; граница проведена в разделе ниже.

• Ваши правки в приоритете. Страницы, помеченные вами как owner: human, никогда не переписываются, а блоки lw:manual сохраняются байт в байт.

• Долг отслеживается, а не обнаруживается. livewiki status ранжирует то, что разошлось с кодом; GitHub Action может блокировать каждый merge при ненулевом долге документации, не тратя токены.

• Работает там, где вы уже работаете. Начните и поддерживайте вики через используемого вами агента разработки или запустите полностью автоматический пакетный режим.

Что проверяет verify — а чего не проверяет

Антигаллюцинационный слой детерминирован и структурен. livewiki verify читает вики заново с диска — поэтому страница, написанная LLM несколько секунд назад, проверяется без предварительного запуска index — и завершается ошибкой в следующих случаях:

• цитируемый символ не существует в коде;

• якорь сломан, потому что символ перемещён, переименован или удалён;

• цитируемая сигнатура больше не совпадает с индексированной;

• внутренняя ссылка не разрешается;

• упомянутый артефакт отсутствует на диске;

• frontmatter или структура страницы нарушают контракт формата.

Это устраняет целые классы выдуманного содержимого — вымышленную функцию, API, которого никогда не существовало, ссылку, которая тихо протухла, — прежде чем читатель это увидит, и при нулевой стоимости в токенах. Всё, что не прошло проверку, отклоняется и откатывается, а не попадает в merge.

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

Related MCP server: wiki-helper

Быстрый старт

Требуется Node.js 24 или новее.

1. Установка

npm install -g @livewiki/cli

(Подойдёт и npx @livewiki/cli — без глобальной установки.)

2. Инициализация

Из корня репозитория, который вы хотите задокументировать:

livewiki init

Индексирует код и создаёт каркас вики в livewiki/, а также производный кэш в .livewiki/ (добавляется в .gitignore). Детерминированно — без вызова LLM и без затрат токенов.

3. Одноразовая начальная генерация вики

У вас есть два пути — выберите один.

Путь A — через вашего агента разработки (ключ API не нужен):

livewiki install

Установщик определяет вашего агента, подключает MCP-сервер, навык документирования по ходу работы и git-хуки. Затем попросите агента сгенерировать вики; он берёт задачи из livewiki_next_task и отправляет страницы через livewiki_write_doc, используя уже имеющуюся у него модель.

Путь B — настроенный API LLM (без участия оператора):

livewiki config

Мастер показывает список провайдеров, запрашивает ваш API-ключ (вводится без эха) и сохраняет его. Команда livewiki без аргументов в ненастроенном репозитории запускает тот же мастер. Затем:

livewiki init --batch

Возобновляемый конвейер планирует реальные единицы страниц и создаёт по одной странице на каждый исходный файл и папку, а также потоки, концептуальные темы, диаграммы и синтез в understanding.md. Прервите его и возобновите с помощью livewiki batch resume <runId>.

4. Проверка и просмотр

livewiki verify   # validate code references, internal links, and artifacts
livewiki view     # build an offline site with search, Mermaid, and dark mode

Работает с вашим агентом разработки

livewiki install автоматически определяет и подключает 13 агентов через MCP (с навыками и хуками, если агент их поддерживает):

Claude Code · Codex · Cursor · Kimi · Gemini CLI · OpenCode · OpenClaw · Cline · Kiro · Qwen · Warp · Zed · Hermes

Предпочитаете ручное подключение? Подойдёт любой stdio-совместимый MCP-клиент:

{
  "mcpServers": {
    "livewiki": {
      "command": "npx",
      "args": ["-y", "@livewiki/mcp", "--repo", "/path/to/repo"]
    }
  }
}

Языки

Страницы с якорями ссылаются на реальные символы; прозаический минимум при этом даёт каждому файлу место в вики. Поддержка языков первого уровня расширяется по мере подтверждения паттерна (Go, Rust и Java появились именно так).

Провайдеры

livewiki config выводит список этих 17 пресетов. Каждый читает собственную переменную окружения с API-ключом; livewiki config show показывает, какую переменную ожидает ваш пресет, никогда не отображая её значение.

ollama и lmstudio не требуют ключа для локального сервера. Для CI и headless-автоматизации задайте переменную окружения напрямую — она имеет приоритет над сохранённым ключом.

Как выглядит сгенерированная страница

Фрагмент из собственного livewiki/core-src/verify.md этого репозитория:

## Discovery: walking the wiki from disk

The verifier never trusts the index for which pages exist — a doc freshly written by an LLM must be caught without first running `index`. Two walkers enumerate the `livewiki/` directory from disk; both skip hidden directories but keep dot-prefixed files.

<!-- lw:anchors packages/core/src/verify.ts#collectWikiPages packages/core/src/verify.ts#collectWikiArtifactPaths -->

```ts
async function collectWikiPages(absRoot: string): Promise<{ relPath: string }[]>
```

Текст объясняет реализацию; маркер lw:anchors привязывает раздел к реальным индексированным символам, поэтому устаревание и недействительные ссылки обнаруживаются механически.

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

• Детерминированный слой — CLI индексирует исходный код, извлекает символы, вычисляет устаревание, планирует работу, отслеживает долг и выполняет проверки — без модели.

• Слой написания — подключённый агент (или пакетный режим на основе API) пишет текст, используя закрытый список разрешённых ключей символов.

• Антигаллюцинационный слой — детерминированный и структурный: якоря кода, цитируемые сигнатуры, внутренние ссылки, артефакты и структура страниц проверяются на соответствие диску; недействительные записи откатываются. Он устраняет выдуманные и протухшие ссылки, а не смысловые ошибки.

• Владение человеком — страницы owner: human никогда не переписываются; блоки lw:manual сохраняются байт в байт.

• Переносимый эталон — принятое состояние всех обязательств по документации хранится в версионируемом livewiki/.baseline.json, поэтому долг контролируется относительно реального эталона, а вики переживает удаление локального кэша.

Долг по документации может блокировать каждый merge в CI без вызовов LLM и токенов — см. шаблон GitHub Actions.

Методология исторических сравнений и датированные результаты архивированы в Benchmarks.

Пакеты

Документация

• SPEC.md — контракты поведения и формата

• VISION.md — обоснование продукта и не-цели

• docs/ROADMAP.md — утверждённый бэклог и порядок выполнения

Лицензия

MIT — см. LICENSE.