Guion Web

Guion Web — это Node.js-инструментарий для веб-исследований. Он предоставляет поиск Exa или Brave, поиск по библиотечной документации через Context7, публичный поиск по коду через Sourcegraph и два бэкенда загрузки страниц через CLI, stdio MCP-сервер, расширение Pi и интеграцию с DeepSeek Harness (DSH): прямое извлечение HTML-to-Markdown и явный рендеринг через agent-browser для страниц, отображаемых на стороне клиента, на поддерживаемых хостах.

Установка и настройка

Требуется Node.js 20 или новее. @guionai/web преднамеренно предоставляет только свой исполняемый файл web и stdio MCP-сервер; у него нет корневого JavaScript/TypeScript SDK. Для этих хост-интеграций используйте пакеты Pi или DSH.

npm install --global @guionai/web
# or run without a global install
npx @guionai/web --help

Для поиска требуется один набор учетных данных провайдера. Если присутствуют оба, по умолчанию выбирается Exa; явно выберите провайдера с помощью --provider exa или --provider brave. При отсутствии ключа Context7 работает анонимно.

export EXA_API_KEY="..."
# or
export BRAVE_API_KEY="..."
# optional, for authenticated Context7 requests
export CONTEXT7_API_KEY="..."

Не размещайте учетные данные в аргументах команд и не коммитьте их. CLI считывает эти переменные окружения напрямую; он не загружает dotenv-файл и не использует старый путь конфигурации приложения.

Related MCP server: FireScrape MCP Server

CLI

По умолчанию web выводит данные в удобочитаемом формате. Добавьте --json, чтобы получить ровно один JSON-документ в stdout, что удобно для автоматизации.

web search --provider exa -- "Node AbortSignal"
web fetch https://example.com/article --tree
web fetch https://example.com/article --section introduction
web docs resolve react
web docs fetch /facebook/react --topic hooks --tokens 2000
web sgraph --count 10 -- "repo:^github\\.com/nodejs/node$ AbortSignal"

Используйте -- перед поисковым или Sourcegraph-запросом, начинающимся с дефиса. fetch поддерживает --full, --tree и --section; для больших извлеченных документов по умолчанию строится дерево заголовков, чтобы последующий запрос мог получить стабильный ID раздела.

MCP

Запускайте stdio-сервер с тем же окружением, содержащим учетные данные:

web mcp
# Pin search selection for the lifetime of this MCP process:
web mcp --provider brave

Сервер предоставляет пять инструментов только для чтения: search, fetch, docs_resolve, docs_fetch и source_search. Его stdout зарезервирован для сообщений протокола MCP; диагностика выводится в stderr. Для страницы, отрисованной на клиенте, явно вызовите fetch с render: "agent-browser" и целочисленным waitMs; эта необязательная повторная попытка требует установленного на хосте исполняемого файла и никогда не выполняется автоматически.

Pi

Установите отдельно распространяемое расширение Pi:

pi install npm:@guionai/pi-web

Оно регистрирует web_search, web_fetch, web_docs и web_source_search и обращается к встроенному ядру в том же процессе. Pi и TypeBox — это peer-зависимости, предоставляемые хостом; ни CLI-исполняемый файл, ни настройка MCP не требуются. web_fetch по умолчанию использует прямой fetch и может явно использовать render: "agent-browser" с целочисленным waitMs, когда хост поддерживает этот необязательный исполняемый файл.

DSH

Установите DSH-пакет из репозитория в существующем профиле Web:

dsh plugin --profile web add @guionai/dsh-web

Включенный конфигурация профиля направляет стандартный веб-поиск PTC через выбранного провайдера Exa или Brave. В интерфейсе его настроек хранится выбор провайдера и управляются защищенные write-only учетные данные, организованные по пространствам имён. Инструменты fetch, документации и Sourcegraph также запускаются в процессе. Хост-пакеты DSH и React являются peer-зависимостями, предоставляемыми DSH. web_fetch по умолчанию использует прямой fetch и может явно использовать render: "agent-browser" с целочисленным waitMs на хосте, где предоставлен соответствующий исполняемый файл.

Бэкенды загрузки страниц

web fetch имеет два бэкенда. fetch (по умолчанию) использует Node fetch, linkedom и Defuddle для прямого извлечения HTML-в-Markdown из статических, SSH и предварительно отрендеренных страниц. agent-browser отображает клиентские страницы через отдельно установленный исполняемый файл хоста. По умолчанию используется прямой fetch; при необходимости выбирайте agent-browser вручную. Реализация никогда не делает откат автоматически:

web fetch https://example.com/app --render=agent-browser --wait=2000
# If it is still incomplete, retry explicitly with more time, or abandon it:
web fetch https://example.com/app --render=agent-browser --wait=10000

--wait обязателен с --render=agent-browser, включая --wait=0, и принимает только целое число от 0 до 30 000 миллисекунд. При прямых запросах fetch нельзя указывать --wait. Те же поля render: "agent-browser" и обязательный waitMs доступны в инструментах MCP fetch, Pi web_fetch и DSH web_fetch. При сбое прямого fetch может возвращаться структурированная подсказка javascript_rendering_may_be_required с рекомендация использование 2,000 мс; агент сам решает, повторить запрос с более длинным ожиданием или прекратить работу со страницей.

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

npm install --global agent-browser
agent-browser install

agent-browser install управляет собственным runtime браузера; пакеты Guion не запускают и не встраивают его и не повторно используют браузерные учетные данные. Совместимый исполняемый файл должен запускаться непосредственно из PATH без промежуточной оболочки. Рендерер поддерживается на хостах macOS и Linux. Прямой fetch остается доступен, а все три npm-пакета устанавливаются и в отсутствии agent-browser.

Сеанс рендеринга создается заново и не имеет состояния. Перед запуском цель должна быть публичным именем компьютера в HTTP(S) или IP-адресом. После этого список разрешенных доменов браузера содержит только запрошенное имя узла, *.<запрошенное-имя-узла> (цель и её поддомены), а также следующий фиксированный набор общих CDN:

• cdn.jsdelivr.net

• unpkg.com

• cdnjs.cloudflare.com

• ajax.googleapis.com

• fonts.googleapis.com

• fonts.gstatic.com

• esm.sh

Вызывающий код не может расширить этот список. Зависимости от неизвестных доменов (редиректы, API, фреймы, фримы, сокеты и т. п.) закрываются с ошибкой render_domain_not_allowed; увеличение waitMs не поможет. Обратите внимание на возможный отсутствующий домен первой стороны или общий CDN-домен на странице https://github.com/guionai/web/issues/new, включив URL страницы и заблокированный домен. Не включайте в проблему данные для входа или секреты страницы.

Это граница имен узлов на уровне браузера, а не полный защита от SSRF или межсетевой экран для исходящих подключений хоста. Литеральные и DNS-разрешенные частные/зарезервированные адреса отклоняются перед запуском загрузки, но разрешенный вредный узел может после проверки изменить свой DNS-ответ на частный адрес (DNS rebinding), а изоляции исходящих подключений хоста на уровне операционной системы здесь нет. Не используйте этот бэкенд для произвольных недоверенных URL-адресов в публичном или многоквартирном сервисе без с фильтрующего SSRF-прокси на каждом подключении либо изоляции исходящего трафика кластера/микроВМ.

Разработка

Это pnpm-воркспейс. Установите зависимости и запустите те же локальные проверки, что использует CI:

pnpm install --frozen-lockfile
pnpm format:check
pnpm typecheck
pnpm build
pnpm test
pnpm test:release
pnpm test:pack

test:release использует одноразовые манифесты для проверки синхронизации версии тега. test:pack выполняет контракт заводской установки или загрузки хоста для каждого публичного пакета во временных каталогах, принадлежащих тестам.

Релизы

Тег v<semver> — источник истины для релиза всех трёх публичных пакетов: @guionai/web, @guionai/pi-web и @guionai/dsh-web. Предварительный этап release-цикла синхронизирует манифесты рабочей копии с этим тегом, затем выполняет форматирование, typechecking, сборку, тесты, проверки версии релиза и упакованные smoke-тесты до начала публикации.

Три независимых, non-fail-fast защищённых ячейки матрицы npm публикуют по одному пакету каждая через npm Trusted Publishing с provenance. Синхронизированная версия выбирает у npm тег latest для стабильной SemVer и beta для пре-релиза. После успеха всех трёх ячеек процесс создает GitHub-релиз с сгенерированным примечаниями и архивами исходногокода. Он не публикует бинарные или платформенные архивы.

Если публикация части недоопубликован – используйте GitHub Actions Re-run failed jobs. Никогда не используйте Re-run all jobs. npm-версии неизменяемы, поэтому успешные, уже выполнявшие правильную публикацию задания не должны запускаться снова.

Первый beta bootstrap и Trusted Publishing

Это выполняется один раз после слияния релизного коммита и до включения штатных OIDC-релизов:

1. Выполните чекаут чистого целевого коммита релиза и выберите синхронизированную бета-версию, например 0.1.0-beta.1.

2. На аккаунте мойнтейнера npm, у которого есть разрешение публикации для @guionai и 2FA, запустите node scripts/sync-version.mjs 0.1.0-beta.1, затем выполните проверки сборки, тестов, упаковки и node scripts/release-dry-run.mjs 0.1.0-beta.1.

3. Из каждой папки публичного пакета опубликуйте синхронизированную бета-версию через npm publish --access public --tag beta . Bootstrap выполняется мейнтейнером с ролью pub; не передавайте provenance за пределы GitHub OIDC release job.

4. В настройках каждого npm-пакета создайте одну связь GitHub Trusted Publisher для @guionai/web, @guionai/pi-web и @guionai/dsh-web. Каждая связь должна указывать на репозиторий guionai/web, workflow .github/workflows/release.yaml и защищённое окружение npm.

5. Проверьте все три отношения и политики прав npm-публикации, затем активируйте (или добавьте тег) обычный цикл release. Он использует GitHub OIDC без маркера npm и запрашивает provenance для каждой штатной публикации.

Никогда не перезаписывайте версию и не отзывайте её. При частичном выпуске GitHub повторно запускайте только те результаты публикации, которые завершились неудачно.