Guion Web

Guion Web es un kit de herramientas de Node.js para investigación web. Proporciona búsqueda en Exa o Brave, consultas de documentación de bibliotecas Context7, búsqueda pública de código en Sourcegraph y dos backends de recuperación de páginas mediante una CLI, un servidor MCP stdio, una extensión Pi y la integración con DeepSeek Harness (DSH): extracción directa de HTML a Markdown y renderizado explícito con agent-browser para páginas renderizadas en el cliente en hosts compatibles.

Instalación y configuración

Se requiere Node.js 20 o posterior. @guionai/web expone intencionadamente únicamente su ejecutable web y el servidor MCP stdio; no ofrece ningún SDK raíz de JavaScript o TypeScript. Para esas integraciones de host, use los paquetes Pi o DSH.

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

La búsqueda necesita una credencial de proveedor. Si ambas están presentes, Exa se selecciona por defecto; seleccione un proveedor explícitamente con --provider exa o --provider brave. Context7 funciona de forma anónima cuando su clave no está presente.

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

No ponga credenciales en los argumentos de los comandos ni las confirme en el sistema de control de versiones. La CLI lee estas variables de entorno directamente; no carga un archivo dotenv ni una ruta antigua de configuración de la aplicación.

Related MCP server: FireScrape MCP Server

CLI

La salida de web es legible por humanos por defecto. Añada --json para obtener exactamente un documento JSON en la salida estándar, lo que resulta útil para automatizar procesos.

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"

Use -- antes de una consulta de búsqueda o de Sourcegraph que comience con un guion. fetch admite --full, --tree, y --section; los documentos largos extraídos usan por defecto un árbol de encabezados, de modo que una petición posterior pueda recuperar un ID de sección estable.

MCP

Ejecute el servidor stdio con el mismo entorno de credenciales:

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

El servidor expone cinco herramientas de solo lectura: search, fetch, docs_resolve, docs_fetch y source_search. Su stdout está reservado para las mensajes del protocolo MCP; los diagnósticos se envían a stderr. Para una página renderizada en el cliente, tenga explícitamente fetch con render: "agent-browser" y un waitMs entero; este reintento opcional requiere un ejecutable instalado en el host y nunca se produce automáticamente.

Pi

Instale la extensión de Pi empaquetada de forma independiente:

pi install npm:@guionai/pi-web

Registra web_search, web_fetch, web_docs, y web_source_search, y llama el núcleo empaquetado dentro del mismo proceso. Pi y TypeBox son dependencias peer que aporta el host; no se requiere ejecutable de CLI ni configuración de MCP. web_fetch usa por defecto la recuperación directa (fetch) y puede usar explícitamente render: "agent-browser" con un waitMs entero cuando su el host proporciona ese ejecutable opcional.

DSH

Instale d uniforme DSH en un el perfil Web existente:

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

El parche de perfil incluido enruta la búsqueda web estándar de PTC a través del proveedor Exa o Brave seleccionado. Su interfaz de configuración almacena la selección de proveedor y gestiona credenciales de solo escritura con espacio de nombres (namespaced). Las herramientas de recuperación (fetch), documentación y Sourcegraph también se ejecutan dentro del proceso. Los paquetes DSH del host y React son dependencias de pares (peer) que aporta el propio DSH. web_fetch usa por defecto la recuperación directa y puede usar explícitamente render: "agent-browser" con un waitMs entero en un host que suministre el ejecutable opcional.

Backends de recuperación de páginas

web fetch tiene dos backends. fetch (el que se usa por defecto) combina el fetch de Node, linkedom y Defuddle para la extracción directa de HTML a Markdown de páginas estáticas, renderizadas en el servidor (SSR) y prerenderizadas. agent-browser hace el renderizado de páginas del lado del cliente mediante un ejecutable instalado por separado en el host. La recuperación directa se usa por defecto; elija agent-browser explícitamente cuando sea necesario. La implementación nunca conmuta automáticamente:

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 es obligatorio con --render=agent-browser, incluido --wait=0, y solo acepta un entero de 0 a 30 000 milisegundos. Las solicitudes de fetch directo no deben proporcionar --wait. Los mismos confroles render: "agent-browser" y waitMs (obligatorio) están disponibles en las herramientas fetch de MCP, web_fetch de Pi y web_fetch de DSH. Un fallo de la recuperación directa puede devolver la sugerencia estructurada javascript_rendering_may_be_required con la opción de 2000 ms; el agente decide si reintentar con una espera más larga o abandonar la página.

El renderizado es una capacidad opcional del host. Si decide usarlo, instale agent-browser por separado en el host:

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

agent-browserinstall gestiona su propio tiempo de ejecución de navegador; los paquetes de Guion nunca lo ejecutan, no lo incluyen y no reutilizan credenciales del navegador. El ejecutable compatible debe poder ejecutarse diríamente desde PATH, sin shell intermedio. El renderizador es compatible con hosts macOS y Linux. La recuperación directa sigue disponible y los tres paquetes npm siguen siendo instalables cuando agent-browser no está presente.

Una sesión renderizada es nueva y no persistente. Antes del lanzamiento, el destino debe ser un nombre de host o una dirección HTTP(S) pública. La lista de permitidos del navegador contiene entonces solo el nombre de host solicitado y el comodín *.<requested-hostname> (el destino y sus subdominios), junto con este conjunto fijo de CDN comunes:

• cdn.jsdelivr.net

• unpkg.com

• cdnjs.cloudflare.com

• ajax.googleapis.com

• fonts.googleapis.com

• fonts.gstatic.com

• esm.sh

Quienplica la llamada no puede ampliar esta lista. Las redirecciones, las APIs, los iframes, los workers, los sockets u otras dependencias de los dominios desconocidos no se satisfacen evera; devuelven un bloqueo e r_domainailed de forma infalible (fail closed). Aumentar waitMs no ayudará. Informe de una posible falta de un dominio de primera parte (first-party) o de un CDN común en https://github.com/guionai/web/issues/new, y añada a página URL URL and el dominio bloqueado. No incluya credenciales ni datos secretos de la página en el informe.

Esto es un límite de nombre de host a nivel de navegador, no una protección SSRF completa ni un cortafuegos de salida del host. Los destinos privados o reservados, delito en forma literal o resueltos por DNS, se rechazan antes del lanzamiento, pero un nombre de host malicioso en la lista permitida puede cambiar su respuesta DNS a una dirección privada después de la validación (binding de DNS) y no existe aquí un aislamiento de salida del sistema host. No use este backend en un servicio público o multiinquilino con URL de entidad“ no confiables, a men os que sepueda usar un proxy de filtrado SSRF por conexión o un aislamiento de salida (egress) por contenedor/microVM.

Desarrollo

Este es un workspace pnpm. Instale las dependencias y ejecute las mismas comprobaciones locales que usa la CI:

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

test:release usa manifiestos desechables para probar la sincronización de la versión de la etiqueta. test:pack ejecuta el contrato de instalación empaquetada o de carga al host de cada paquete público en directorios temporales las de prueba.

Lanzamientos

La etiqueta v<semver> es la fuente de verdad del lanzamiento de los tres paquetes públicos: @guionai/web, @guionai/pi-web y @guionai/dsh-web. La comprobación previa del lanzamiento sincroniza sus manifiestos de checkout a partir de queda etiqueta y luego completa el formateo, la verificación de tipos, y la vía de citas, las de la vía, las de lanzamiento y las pruebas de humo de los paquetes antes de que comience cualquier publicación.

Tres celdas independentes, sin detención anticipada (non-fail-fast), dentro del entorno protegido npm se cuadrá las celdas de una matriz y publican, cada una, un paquete a través de npm Trusted Publishing con procedencia hex. La versión sincronizada elige la etiqueta latest de npm para las versiones SemVer estables y la beta para las versiones previas. Tras el éxito de las tres celdas, el flujo de trabajo crea el release de GitHub con notas generadas y los archivos de origen del solicitud. No publica binoidnor archivos de plataforma.

Si la publicación falla parcialmente, use de GitHub Actions Re-run failed jobs. Nunca utilice Re-run all jobs: las versiones de npm son inmutables, de modo que los jobs que ya publicaron con éxito no deben volver a ejecutarse.

Primer bootstrap de la versión beta y Trusted Publishing

Haga esto una sola vez después de que la commit de lanzamiento se haya integrado y antes de poder hacer lanzamientos normales con OIDC:

1. Haga checkout de una commit de destino limpia y previstola, y elija una versión beta sincronizada como, por ejemplo, 0.1.0-beta.1.

2. Con una cuenta de mantenedor npm con permiso de publicación para @guionai y 2FA, ejecute node scripts/sync-version.mjs 0.1.0-beta.1; después, las comprobaciones (gates) de build, test, pack y node scripts/release-dry-run.mjs 0.1.0-beta.1.

3. Desde la carpeta de cada paquete público, publica la versión beta sincronizada con npm publish --access public --tag beta. Este bootstrap se autentica con el mantenedor: no pase provenance lengthoutside the OIDC release job of GitHub.

4. En la configuración del paquete npm, crear causa para cada uno de @guionai/web, @guionai/pi-web y @guionai/dsh-web una relación de GitHub Trusted Publisher. Cada una debe apuntar hacia el repositorio guionai/web, el flujo de trabajo .github/workflows/release.yaml y el entorno protegido npm.

5. Verifique las tres relaciones y las políticas de acceso de publicación en npm; luego active el "etiqué de" el flujo de trabajo de release rutinario. Este usa el OIDC de GitHub con no necesita token npm y solicita procedencia en cada publicación normal.

Nunca sobrescriban ni despubliquen una versión. En un release parcial de GitHub, vuelve a ejecutar settlement what una de las to end cells de publicación que fallaron.