Guion Web

Guion Web ist ein Node.js-Webrecherche-Toolkit. Es stellt Exa- oder Brave-Suche, Context7-Bibliotheksdokumentationsabfrage, die öffentliche Codesuche von Sourcegraph sowie zwei Seitenabruf-Backends über eine CLI, einen stdio-MCP-Server, eine Pi-Erweiterung und eine DeepSeek-Harness-Integration (DSH) bereit: direkte HTML-zu-Markdown-Extraktion und explizites agent-browser-Rendering für clientgerenderte Seiten auf unterstützten Hosts.

Installation und Konfiguration

Node.js 20 oder höher ist erforderlich. @guionai/web stellt bewusst nur sein web-Executable und den stdio-MCP-Server bereit; es bietet kein JavaScript- oder TypeScript-SDK auf Root-Ebene. Verwenden Sie für diese Host-Integrationen die Pi- oder DSH-Pakete.

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

Für die Suche ist eine Anbieteranmeldeinformation erforderlich. Wenn beide vorhanden sind, wird standardmäßig Exa ausgewählt. Wählen Sie einen Anbieter explizit mit --provider exa oder --provider brave aus. Context7 arbeitet anonym, wenn kein Schlüssel vorhanden ist.

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

Geben Sie keine Anmeldedaten in Befehlsargumenten ein und committen Sie sie nicht. Die CLI liest diese Umgebungsvariablen direkt; sie lädt keine Dotenv-Datei und keinen älteren Anwendungskonfigurationspfad.

Related MCP server: FireScrape MCP Server

CLI

web gibt standardmäßig eine menschenlesbare Ausgabe aus. Fügen Sie --json für genau ein JSON-Dokument auf stdout hinzu, das für Automatisierung nützlich ist.

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"

Verwenden Sie -- vor einer Such- oder Sourcegraph-Abfrage, die mit einem Bindestrich beginnt. fetch unterstützt --full, --tree und --section; lange extrahierte Dokumente verwenden standardmäßig eine Überschriftenstruktur, damit eine spätere Anfrage eine stabile Abschnitts-ID abrufen kann.

MCP

Starten Sie den stdio-Server mit derselben Umgebung von Anmeldedaten:

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

Der Server stellt fünf Tools bereit: search, fetch, docs_resolve, docs_fetch und source_search. Seine Standardausgabe ist für MCP-Protokollnachrichten reserviert; Diagnosen gehen an stderr. Für eine clientgerenderte Seite rufen Sie fetch explizit mit render: "agent-browser" und einem Integer waitMs auf; dieser optionale Wiederholungsversuch erfordert eine installierbare Datei auf dem Host und geschieht nie automatisch.

Pi

Installieren Sie die separat gebündelte Pi-Erweiterung:

pi install npm:@guionai/pi-web

Sie registriert web_search, web_fetch, web_docs und web_source_search und ruft den gebündelten Kernel im selben Prozess auf. Pi und TypeBox sind Peer-Abhängigkeiten, die vom Host bereitgestellt werden; es ist keine CLI- web_fetch-Extension oder MCP-Konfiguration erforderlich. web_fetch verwendet standardmäßig direkten Abruf und kann explizit render: "agent-browser" mit einem Integer waitMs verwenden, wenn sein Host diese optionale ausführbare Datei bereitstellt.

DSH

Installieren Sie das DSH-Bundle im bestehenden Web-Profil:

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

Der enthaltene Profil-Patch leitet die Standard-PTC-Websuche über den ausgewählten Exa- oder Brave-Anbieter. Seine Oberfläche speichert die Anbieterauswahl und verwaltet namensgeschützte Schreibschutz-Zugangsdaten. Fetch-, Dokumentations- und Sourcegraph-Tools laufen ebenfalls im Prozess. Die DSH-Hostpakete und React sind Peer-Abhängigkeiten DSH. web_fetch verwendet standardmäßig direkten Abruf und kann explizit render: "agent-browser" mit einem Integer waitMs auf einem Host verwenden, der die optionale ausführbare Datei bereitstellt.

Seitenabruf-Backends

web fetch hat zwei Backends. fetch (das Standard) verwendet Node fetch, linkedom und Defuddle für die direkte HTML-zu-Markdown-Extraktion from static, SSR and pre-rendered Seiten. agent-browser rendert clientseitige Seiten. . Import a agent-browser self. Direct fetch is used by default; select agent-browser explicitly when needed. The implementation never falls back automatically:

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 ist mit --render=agent-browser erforderlich, einschließlich --wait=0, und akzeptiert nur eine Ganzzahl von 0 bis 30.000 Millisekunden. Direkte fetch-Anfragen dürfen keuchs --wait angeben. Dasselbe render: "agent-browser" ist erforderlich: the same fields are available in the MCP fetch, Pi web_fetch, and DSH web_fetch tools. On failure of a direct fetch, the structured javascript_rendering_may_be_required hint with the suggestion of 2,000 ms can be returned – the agent decides whether to retry with a longer wait or discontinue the page.

Rendering ist eine optionale Host- funktion. Am If you want to use it, install agent-browser separately on the host:

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

agent-browser install manages its own browser runtime; Guion does not execute it, bundle it, or reuse browser credentials. A compatible executable must be directly runnable from PATH without a shell. The renderer is supported on macOS and Linux hosts. Direct fetch remains available, and the three npm packages remain installable if agent-browser is absent.

A rendered session is fresh and non-persistent. Before the start, the target must be a public HTTP(S) hostname or address. The browser allowlist then contains only the requested hostname, *.<requested-hostname> (the target and its subdomains), plus this fixed common-CDN set:

• cdn.jsdelivr.net

• unpkg.com

• cdnjs.cloudflare.com

• ajax.googleapis.com

• fonts.googleapis.com

• fonts.gstatic.com

• esm.sh

The caller cannot widen this list. Redirects, APIs, frames, workers, sockets, or other dependencies on unknown domains fail closed as render_domain_not_allowed; increasing waitMs does not help. If a first-party or common-CDN domain is likely missing, report it at https://github.com/guionai/web/issues/new, including the page URL and blocked domain. Do not include credentials or page secrets in an issue.

This is browser-level hostname isolation, not complete SSRF protection or an operating-system host- egress firewall. Literal and DNS-resolved private/reserved targets are rejected before launch, but an allowlisted malicious host can change its DNS answer to a private address after validation (DNS rebinding); there is no host-egress isolation here. Do not use this backend for arbitrary untrusted URLs in a public or multi-tenant service without a per-connection SSRF-filter proxy or container/microVM egress isolation.

Development

This is a pnpm workspace. Install dependencies and run the same local gates as the CI:

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

test:release uses disposable manifests to exercise tag-version synchronization. test:pack runs each public package's packed installation or host-loading contract in test-owned temporary directories.

Releases

A v<semver> tag is the source of truth for all three public packages: @guionai/web, @guionai/pi-web, and @guionai/dsh-web. The release preflight synchronizes the checkout manifests to this tag, then completes formatting, typechecking, build, tests, release-version checks, and packed smoke tests before any publication begins.

Three independent, non-fail-fast protected npm-environment matrix cells then publish one package each using trust-ed publishing with provenance. The synchronized version selects npm's latest tag for stable SemVer and beta for a pre-release. After every three cells succeed, the workflow creates the GitHub release with generated notes and source archives. It publishes no binaries or platform archives.

If publication partially fails, use GitHub Actions Re-run failed jobs. Never use Re-run all jobs: npm versions are unchangeable, so jobs that already published must not run again.

Initial or early beta bootstrap and Trusted Publishing

Run this once after the release commit is merged, before enabling recurring OIDC releases:

1. Check out a clean intended release commit and use a synchronized beta version such as 0.1.0-beta.1.

2. With a maintainer npm account with @guionai publish permission and 2FA, run node scripts/sync-version.mjs 0.1.0-beta.1 and then the build, test, pack and node scripts/release-dry-run.mjs 0.1.0-beta.1 checks.

3. Publish the synchronized beta from each public package directory with npm publish --access public --tag beta. This bootstrap is authenticated by the maintainer; do not submit provenance to the GitHub OIDC release job.

4. In npm package settings, create one GitHub Trusted Publisher relationship for each of @guionai/web, @guionai/pi-web, and @guionai/dsh-web. Each must target the guionai/web repository, workflow .github/workflows/release.yaml, and the protected npm environment.

5. Verify all three relationships and the publishing-access policies in npm, then enable/tag the normal release workflow. It uses GitHub OIDC without npm token and requests provenance for every normal published release.

Never overwrite or unpublish a version. For a partial GitHub release, rerun its failed publishing cells only.