Читать документацию локально

Что происходит

03Агент выполняет vibe cache add org.vibevm.core/vibevm-docs. Пакет документации никогда не ставится в проект; он прогревается в машинное хранилище вместе с пакетами, которые описывает, чтобы каждое правило, которое он цитирует, разрешалось без сети. Затем агент выполняет vibe doc serve: vibe запускает маленький веб-сервер, который слушает только на вашей машине, отрисовывает каждую страницу из хранилища по запросу и печатает адрес. Пока вы читаете, из интернета ничего не скачивается, и ни одна страница не покидает машину.

04 vibe install MUST refuse a doc package with a hint naming the warm-up command; documentation is warmed into the machine store with vibe cache add (§11), and the local reader and vibe explain read the store.

05 vibe doc serve starts an HTTP server on 127.0.0.1 only, serves the shell and, on every request, glues in the island rendered from the machine store, the current project's lock file or a private registry. The language preference comes from the project's [i18n].preferred when present. The mode is fully autonomous: no request to vibevm.org, no external CDN or fonts, everything in the bundle. The server serves files only from known roots (the store, the shell), without path traversal and without directory listing, with a content security policy naming no external source.

Руками

061. Прогрейте хранилище. Внутри проекта источник — его реестры; вне проекта — реестры всей машины:

082. Запустите читалку и откройте напечатанный адрес в браузере. Остановите её через Ctrl+C:

103. Выберите язык переключателем на любой странице. Там, где у страницы нет перевода, читалка показывает язык самого руководства и говорит об этом.

Приватные пакеты

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

12 The local reader listens on 127.0.0.1 only, serves only known roots, loads nothing external, and contacts the network only for a shell download the user explicitly confirmed.

Оболочка читалки

13Выпущенный vibe несёт интерфейс читалки внутри бинарника. vibe, собранный из исходников, несёт простую запасную оболочку; vibe doc shell install скачивает полный интерфейс для своей версии из ассетов выпуска в ~/.vibe/opt/, проверив размер и отпечаток, и только по вашей просьбе. Без него читалка работает, просто скромнее, а vibe doc serve --print-shell говорит, какую из двух оболочек она держит.

14 When the instance's shell pin names a shell that is not in the shell store and there is no network, the reader falls back to the bare shell and warns; it never contacts the network without consent (§12).

Особые случаи и правила

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

16 Warming a doc package with vibe cache add warms its subjects too, so that spec:// citations resolve offline.

17Внутри проекта, чей локальный реестр держит пакет прямо в дереве, vibe cache add --offline прогревает его без сети. Язык читалки берётся из [i18n].preferred проекта или из флага при запуске.

18 The store is warmed with vibe cache add <coordinate> from a registry, or vibe cache add --offline <coordinate> from a project root whose project-local registry holds the package in-tree; the sources of vibe-doc are the store (lookup, list_all), the lock file (Lockfile::read, slot_abs_path), a registry (resolve_and_fetch) and a checkout (LocalRegistry).

19 The local reader serves the same from the store; the preference comes from the project's [i18n].preferred or a launch flag.

20На сайте та же страница живёт под /doc/: язык идёт следующим сегментом пути, а у языка источника префикса нет. Адрес с номером версии показывает текущее содержимое этой версии, потому что версию могут опубликовать заново, а реестр не хранит прошлых публикаций.

21 The site is mounted under the path /doc of the main domain. The language is the path segment after /doc/; the source language of a documentation carries no prefix. The address map is deterministic and needs no index:

22 An address with a version number always shows the current content of that version in the registry: one number may be published ten times a day, and the site shows the last publication. There are no permanent links to past publications — they do not exist in the registry either (§14).

23Читалку может встроить плагин редактора через iframe; тогда плагин передаёт при запуске собственный origin, и читалка принимает фреймы только из него.

24 The policy is sent as a header, not a <meta>: default-src 'self'; script-src 'self'; style-src 'self'; img-src 'self' data:; font-src 'self'; connect-src 'self'; media-src 'self'; object-src 'none'; base-uri 'none'; form-action 'none'; frame-ancestors <origin>, where frame-ancestors names only the origin of the host that launched the reader — the launch parameter vibe doc serve --frame-ancestor <origin>, because a webview's origin changes from window to window — and is 'none' without the parameter. The reader has no CORS layer at all and sends x-content-type-options: nosniff. The public site is not embeddable in frames.

25Агент читает то же хранилище: vibe explain "spec://org.vibevm.core/vibevm-docs-ru/start/what-vibevm-is" печатает страницу или блок текстом.