Guion Web

Guion Web 是一个 Node.js 网页研究工具包。它通过 CLI、stdio MCP 服务器、Pi 扩展和 DeepSeek Harness（DSH）集成提供 Exa 或 Brave 搜索、Context7 库文档查找、Sourcegraph 公共代码搜索，以及两种页面抓取后端：直接进行 HTML 到 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 可在 stdout 上恰好输出一个 JSON 文档，这对自动化很实用。

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。对于客户端渲染的页面，请显式调用带 render: "agent-browser" 参数和整数 waitMs 参数的 fetch；此可选重试需要主机已安装某个可执行文件，并且永远不会自动发生。

Pi

安装独立捆绑的 Pi 扩展：

pi install npm:@guionai/pi-web

它会注册 web_search、web_fetch、web_docs 和 web_source_search，并在进程内调用捆绑的核心。Pi 和 TypeBox 是宿主提供的 peer 依赖；不需要 CLI 可执行文件或 MCP 配置。web_fetch 默认使用直接抓取，并且当宿主提供可选的可执行文件时，可以显式使用 render: "agent-browser" 并带上整数 waitMs 参数。

DSH

在现有 Web 配置中安装 DSH 捆绑包：

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

附带的 profile 补丁会将内置的 PTC 网页搜索路由到所选的 Exa 或 Brave 提供方。它的设置界面会存储提供方选择，并管理带命名空间的只写凭据。Fetch、文档和 Sourcegraph 工具也都在进程内运行。宿主 DSH 包和 React 是由 DSH 提供的 peer 依赖。web_fetch 默认使用直接抓取，并且当宿主提供可选的可执行文件时，可以显式使用 render: "agent-browser" 并带上整数 waitMs 参数。

页面抓取后端

web fetch 有两个后端。fetch（默认）使用 Node fetch、linkedom 和 Defuddle，从静态页面、SSR 页面和预渲染页面中直接进行 HTML 到 Markdown 的提取。agent-browser 通过单独安装的主机可执行文件来渲染客户端页面。默认使用直接抓取；需要时反显式选择 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。MCP fetch、Pi web_fetch 和 DSH web_fetch 工具上也提供了相同的 render: "agent-browser" 和必填的 waitMs 字段。直接抓取失败时可能会返回结构化的 javascript_rendering_may_be_required 提示，并附带 2,000 ms 的建议；代理会决定是使用更长的等待时间重试，还是放弃该页面。

渲染是宿主的一种可选能力。如果你选择使用它，请在主机上单独安装 agent-browser：

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

agent-browser install 管理自己的浏览器运行时；Guion 包从不运行它、捆绑它，也不会复用浏览器凭据。兼容的可执行文件必须能从 PATH 中直接运行，且不需要 shell。该渲染器支持 macOS 和 Linux 主机。直接抓取仍然可用，并且当 agent-browser 缺失时，这三个 npm 包仍然可以安装。

渲染会话是全新的且非持久的。启动前，目标必须是 HTTP(S) 公共主机名或地址。然后，浏览器允许列表只包含请求的主机名、*.<requested-hostname>（目标及其子域）以及这个固定的常见 CDN 集合：

• cdn.jsdelivr.net

• unpkg.com

• cdnjs.cloudflare.com

• ajax.googleapis.com

• fonts.googleapis.com

• fonts.gstatic.com

• esm.sh

调用方无法扩大此列表。对未知域名的重定向、API、iframe、worker、socket 或其他依赖都会按默认拒绝的方式返回 render_domain_not_allowed；增加 waitMs 不会有帮助。如果你认为缺少了某个第一方或常见 CDN 域名，请在 https://github.com/guionai/web/issues/new 报告，包括页面 URL 和被阻止的域名。请不要在 issue 中包含凭据或页面秘密。

这是一个浏览器级别的主机名边界，不是完整的 SSRF 防护或主机出口防火墙。字面性和 DNS 解析的私有/保留目标会在启动前被拒绝，但一个已允许的恶意主机名可以在校验后将 DNS 应答更改为私有地址（DNS 重绑定），这里没有操作系统级别的主机出口隔离。如果没有按连接进行 SSRF 过滤的代理，或没有容器/microVM 出口隔离，请不要将此后端用于公共或多租户服务中的任意不受信任的 URL。

开发

这是一个 pnpm workspace。安装依赖项，并运行 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 的发布来源唯一来源。发布预检会从该标签同步其 checkout 清单，然后再完成格式化、类型检查、构建、测试、发布版本检查和打包冒烟测试，然后才开始任何发布。

三个独立、非快速失败、受保护的 npm Environment 矩阵单元会通过带 provenance 的 npm Trusted Publishing 各发布一个包。同步的版本会为稳定版 SemVer 选择 npm 的 latest，为预发布选择 beta 标签。当三个单元全部成功后，工作流会创建 GitHub Release，包含生成的说明和源码归档。它不发布二进制文件或平台归档。

如果发布部分失败，请使用 GitHub Actions 的 Re-run failed jobs。绝不要使用 Re-run all jobs：npm 版本是不可变的，因此已成功发布的作业不得再次运行。

首次 beta 引导与 Trusted Publishing

在发布提交合并之后，启用常规 OIDC 发布之前，只需执行一次：

1. 检出一个干净的目标发布提交，并选择一个同步的 beta 版本，例如 0.1.0-beta.1。

2. 使用一个有 @guionai 发布权限并启用了 2FA 的维护者 npm 账户，运行 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 发布同步的 beta 包。此引导由维护者进行身份验证；不要在 GitHub OIDC 发布作业外传递 provenance。

4. 在 npm 包设置中，为 @guionai/web、@guionai/pi-web 和 @guionai/dsh-web 分别创建一个 GitHub Trusted Publisher 关系。每个都必须指向仓库 guionai/web、工作流 .github/workflows/release.yaml 以及受保护的 npm Environment。

5. 在 npm 中验证所有三个关系和 npm 发布访问策略，然后启用/标记常规发布工作流。它使用 GitHub OIDC，不需要 npm 令牌，并为每次常规发布请求 provenance。

不要覆盖或取消发布某个版本。如果 GitHub 发布部分失败，只重新运行失败的单元。