GuionAI/web

Guion Web

Guion Web 是一个 Node.js 网络研究工具包。它通过 CLI、stdio MCP 服务器、个人 HTTP 服务、Pi 扩展和 DeepSeek Harness (DSH) 集成，提供 Exa、Brave、DeepSeek 或托管的 Kepos Bridge 搜索端点、Context7 库文档查询、Sourcegraph 公开代码搜索、页面链接发现，以及两种页面渲染模式：HTTP HTML 转 Markdown 提取，以及针对受支持主机上客户端渲染页面的显式浏览器渲染。

DSH 设置说明： 在安装 DSH 包之前运行 web dsh sync，安装之后运行 web dsh doctor。该工作流会创建熟悉的原版预设 ID 的兼容副本，并隐藏其官方随附的重复项，同时保留普通用户预设。

安装与配置

需要 Node.js 20 或更高版本。@guionai/web 暴露其 web 可执行文件、stdio MCP 服务器和个人 HTTP 服务；它不提供根级 JavaScript 或 TypeScript SDK。如需这些宿主集成，请使用 Pi 或 DSH 包。

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

搜索需要 Exa、Brave 或 DeepSeek 其中一个提供商凭据。如果 Exa 和 Brave 同时存在，默认选择 Exa；DeepSeek 绝不会被隐式选择。可使用 --provider exa、--provider brave、--provider deepseek 或 --provider kepos-bridge 显式选择提供商。DeepSeek 使用其原生网络搜索工具进行一次辅助模型调用，并返回与其他提供商相同的规范化排序 URL/标题/摘要结果。Kepos Bridge 使用捆绑的默认路由，除非它在 DSH 中运行，此时其实时设置卡片可以覆盖该路由。
Context7 在其密钥缺失时可匿名工作。

HTTP 服务默认始终使用 Bridge 到 Exa 的策略，并且其重试需要非空的 EXA_API_KEY。设置服务器本地的 WEB_SEARCH_PROVIDER=deepseek 可改为选择 DeepSeek；这需要非空的 DEEPSEEK_API_KEY，并且当 DeepSeek 请求失败时不会回退到 Bridge 或 Exa。HTTP 客户端无法按请求选择提供商、传递凭据或覆盖 Bridge 路由。设置 KEPOS_BRIDGE_ENDPOINT 可替换默认路由
（http://codex-bridge.localhost:17480/codex/web-search）；它必须是完整的 HTTP(S) URL，且不带凭据、查询或片段。

export EXA_API_KEY="..."
or
export BRAVE_API_KEY="..."
for explicit DeepSeek selection in CLI, MCP, Pi, or DSH
export DEEPSEEK_API_KEY="..."
optional, for authenticated Context7 requests
export CONTEXT7_API_KEY="..."
optional complete Bridge route for web serve
export KEPOS_BRIDGE_ENDPOINT="http://127.0.0.1:8787/codex/web-search"
optional Browser Rendering Gateway origin for web serve browser requests
export BROWSER_GATEWAY_URL="http://browser-gateway"
HTTP/Pi: select DeepSeek server-side (HTTP clients still send {"query":"..."})
export WEB_SEARCH_PROVIDER="deepseek"
不要将凭据放在命令参数中，也不要提交它们。CLI 直接读取这些
环境变量；它不会加载 dotenv 文件或更早的
应用程序配置路径。

个人 HTTP 服务

使用上述服务器本地环境运行该服务。对于 Bridge-to-Exa，保持
WEB_SEARCH_PROVIDER 未设置；对于仅 DeepSeek 路径，将其设置为 deepseek：

web serve --host 0.0.0.0 --port 8787
或使用已发布的镜像
docker run --rm -p 8787:8787 \
-e EXA_API_KEY="$EXA_API_KEY" \
-e KEPOS_BRIDGE_ENDPOINT="http://host.docker.internal:17480/codex/web-search" \
-e BROWSER_GATEWAY_URL="http://host.docker.internal:8788" \
ghcr.io/guionai/web:v0.1.0

每个 HTTP 操作都是一个带版本的 JSON POST 路由。请求和响应模式
由同一组路由定义生成到 openapi.yaml 中：

| 路由                 | 请求                                                      | 用途                                                            |
| -------------------- | --------------------------------------------------------- | --------------------------------------------------------------- |
| /api/v1/web/search | { "query": "..." }                                      | 服务器选择的搜索：默认 Bridge→Exa，或仅 DeepSeek                |
| /api/v1/web/fetch  | { "url", "mode?", "section_id?", "render?", "waitMs?" } | 获取 Markdown                                                   |
| /api/v1/web/links  | { "url", "limit?", "render?", "waitMs?" }               | 列出页面 HTTP(S) 链接                                           |

完整的人类可读契约见 HTTP 服务参考。

搜索会保留成功的空 Bridge 结果；当未选择服务器提供商时，对于非取消的
Bridge 失败，会恰好重试 Exa 一次，并在响应中报告提供商。DeepSeek 选择是
服务器本地的，没有自动回退。在任何情况下，请求都保持为 { "query": "..." }。
天气、体育、金融和时间未暴露，因为所配置的提供商不提供契约等价的
官方类型化数据 API。无效的 JSON 正文、未知字段和无效的类型化值会在
上游调用之前被拒绝。上游失败是有界的 JSON 错误，并且绝不包含凭据或原始
提供商响应正文。
错误响应使用稳定的 { "code", "message", "details"? } JSON 结构；
上游失败使用 502（上游超时则为 504），而客户端取消报告为 499。

当省略 render（或设置为 "http"）时，Fetch 和 Links 使用 HTTP 渲染。
浏览器渲染是显式的，并且同时需要 render: "browser" 和从 0 到 30,000 的
整数 waitMs；HTTP 渲染绝不会静默切换后端。本地/npm web serve 保留其
提供的直接操作。
GHCR 镜像设置 GUIONAI_HTTP_IMAGE=1，并将浏览器请求发送到由
BROWSER_GATEWAY_URL 配置的服务器本地浏览器渲染网关。
GHCR 镜像不包含 Chromium 或 agent-browser；网关缺失、不可达、过载或故障时，会返回显式的浏览器渲染失败，而普通 HTTP 渲染仍然可用。

这是一个个人 Web 服务：面向其操作者和代理的单信任边界部署。它并未针对公共或多租户暴露进行加固；SSRF/出口隔离、浏览器沙箱、配额和身份验证仍推迟在 .scratch/defered/public-http-service-security.md 中处理。

CLI

web 默认输出人类可读的内容。添加 --json 可在 stdout 上仅输出一个 JSON 文档，这对自动化很有用。
运行 web --version（或 web -V）可打印已安装包的版本。

web search --provider exa -- "Node AbortSignal"
web search --provider deepseek -- "Node AbortSignal"
web search --provider kepos-bridge -- "Node AbortSignal"
web fetch https://example.com/article
web fetch https://example.com/article --section introduction
web fetch https://example.com/article --mode auto --section introduction
web fetch https://example.com/article --mode tree
web fetch https://example.com/article --mode full
web links https://example.com/article --limit 50
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
支持 --mode auto|full|tree；省略 mode 表示 auto。--section 可与省略 mode 或 --mode auto 一起使用以检索某个章节，与 --mode full 或 --mode tree 一起使用时会被拒绝。带有可导航标题的长提取文档会自动返回标题树，以便后续请求可以检索稳定的 section_id。普通自动文档结果报告 mode: "auto"；
标题树、显式完整文档和章节结果分别报告 "tree"、
"full" 和 "section"。无标题的长文档使用
正常的受限自动响应。仅当该响应
被内容长度限制截断时，truncated 才为 true。mode: "full" 返回完整的
提取 Markdown，而 mode: "tree" 始终返回标题树
表示，包括显式的无标题结果。links 最多列出
原始页面 DOM 中的 100 个唯一 HTTP(S) 锚点。

MCP

使用相同的凭据环境运行 stdio 服务器：

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

该服务器公开六个只读工具：search、fetch、links、docs_resolve、
docs_fetch 和 source_search。其 stdout 保留用于 MCP 协议
消息；诊断信息发送到 stderr。对于客户端渲染的页面，请显式调用
fetch 或 links，并传入 render: "browser" 和整数 waitMs；此可选
重试需要主机安装的可执行文件，且绝不会自动发生。
fetch 工具接受输入 mode: "auto" | "full" | "tree"（默认
"auto"）。传入返回的 section_id 并省略 mode 或使用 mode: "auto"
可检索该 section；mode: "full" 和 mode: "tree" 会拒绝
section_id。结果包含 mode: "auto" | "full" | "tree" | "section"
和 truncated，仅当内容因长度限制被截断时，truncated 才为 true。

Pi

安装独立打包的 Pi 扩展：

pi install npm:@guionai/pi-web

它注册 web_search、web_fetch、web_links、web_docs 和 web_source_search，并在进程内调用
打包的核心。Pi 和 TypeBox 是由宿主提供的 peer 依赖；无需 CLI 可执行文件或
MCP 配置。web_fetch 默认使用
HTTP 渲染，并且当其宿主提供该可选可执行文件时，可以显式使用 render: "browser" 并配合
整数 waitMs。
其导航输入为 mode: "auto" | "full" | "tree"（默认 "auto"）；
section_id 配合省略/"auto" mode 可检索 section，而 full/tree
会拒绝它。结果报告 mode: "auto" | "full" | "tree" | "section" 和一个
truncated 标志，该标志仅表示内容因长度限制被截断。
web_links 使用相同的显式渲染契约，并列出原始页面 DOM 中的 HTTP(S) 锚点。

在启动 Pi 前设置 WEB_SEARCH_PROVIDER=kepos-bridge 以选择
免凭据的 Kepos Bridge provider，或设置 WEB_SEARCH_PROVIDER=deepseek 并配合
DEEPSEEK_API_KEY 以显式使用 DeepSeek 搜索。Pi 使用打包的默认
Bridge 路由；只有 DSH 暴露路由设置。DeepSeek 绝不会仅因其密钥存在而被选中。

DSH

该 bundle 使用熟悉的 stock preset id，但其兼容副本由 Guion 拥有，位于 DSH 用户 preset 根目录中。在
安装或激活 profile bundle 之前，请同步这些副本：

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

web dsh sync 读取已安装的官方
@deepseek-ai/dsh-agent-presets@0.1.2-rc.1 包，并创建兼容的
standard、ptc、cordis 和 minimal 副本。它仅从前三个中移除
顶层官方 tool-web 行；Minimal 被原样复制，
因为它已经省略了该行。该命令是幂等的，并将现有的同 id 目录与官方和兼容
树进行比较。完全匹配的项会自动刷新。被修改的同 id preset
需要交互式确认；使用 web dsh sync --yes 进行有意的
非交互式覆盖。在升级受支持的 DSH
运行时后，请再次运行 sync。只读 doctor 命令会报告缺失、过期和冲突的
副本，并在 roster 未就绪时以非零状态退出。

该 bundle 的 preset roster 设置 includeShippedRoot: false、
includeUserRoot: true 和 default: standard。这会隐藏所有官方
随附的重复项，同时保留 Yuki 和所有其他普通用户
preset。现有会话、凭据和已部署的 profile 不会
自动迁移；在成功同步并运行 doctor 后，单独激活或部署该 bundle。

该 profile patch 会禁用官方 DSH Web registry、search/fetch providers 以及 tool-web，然后直接注册 Guion 完整的 DSH Research Surface。其设置 UI 存储 provider 选择和完整的非机密 Kepos Bridge 路由（默认 http://codex-bridge.localhost:17480/codex/web-search），并管理带命名空间的只写凭据，包括一个只写的 DeepSeek API key。DeepSeek 使用相同的 provider picker/key 工作流，并且不暴露任何 DeepSeek endpoint 字段。选择 Kepos Bridge 还会额外暴露 web_weather、web_sports、web_finance 和 web_time；当选择其他 provider 时，这些工具会被移除。宿主 DSH 目标为 0.1.2-rc.1；其 packages 和 React 是由 DSH 提供的 peers。
web_fetch 默认使用 HTTP rendering，并且可以在提供可选可执行文件的宿主上，显式使用带整数 waitMs 的 render: "browser"。
其导航输入使用与其他 adapters 相同的 mode 和 section_id 契约：输入 mode 为 auto|full|tree（默认 auto），省略 mode 或使用 auto mode 并配合 section_id 会检索一个 section。结果会报告 auto|full|tree|section 和 truncated。
web_links 使用相同的显式 rendering 契约，并从原始页面 DOM 中列出 HTTP(S) anchors。

Guion 在 native 和 PTC 两种 presentation modes 中拥有 web_search、web_fetch、web_links、web_docs 和 web_source_search。web_search 接受一到四个经过 trim 的 queries，并发运行它们，确定性地合并部分成功结果，并清晰地报告完全失败。web_fetch 接受 mode: "auto" | "full" | "tree"、可选的 section_id 且 mode 省略或为 auto、render: "http" | "browser"，以及从 0 到 30,000 的 browser waitMs。web_links 具有相同的 rendering 和 wait 契约。完整 schemas 会被每个兼容的 stock-equivalent preset 继承。

页面渲染模式

web fetch 有两个 renderers。http（默认）使用 Node fetch、linkedom 和 Defuddle，从静态、SSR 和预渲染页面中提取 HTML 到 Markdown。browser 通过宿主能力渲染客户端页面：web serve 委托给其配置的 Browser Rendering Gateway，而 CLI、MCP、Pi 和 DSH 使用单独安装的 agent-browser 能力。默认使用 HTTP rendering；需要时显式选择 browser。该实现绝不会自动回退：

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

web links 使用相同的 HTTP 或显式 browser-rendered source，但解析原始 DOM，而不是 Defuddle 输出，因此可读文章之外的导航和其他链接仍然可被发现。它只返回 HTTP(S) a[href]
目标地址，去重后默认上限为 100 个。

--wait 在 --render=browser 时是必需的，包括 --wait=0，并且只接受 0 到 30,000 毫秒之间的整数。HTTP fetch 或 links 请求不得提供 --wait。相同的 render: "browser" 和必需的 waitMs 字段在 MCP fetch/links、Pi web_fetch/web_links 以及 DSH web_fetch/web_links 工具上均可用。HTTP 渲染失败可能会返回结构化的 javascript_rendering_may_be_required 提示，并附带 2,000 毫秒的建议；由 agent 决定是使用更长的等待时间重试，还是放弃该页面。

直接渲染是 CLI、MCP、Pi 和 DSH 的可选宿主能力。如果你选择使用它，请在宿主上单独安装 agent-browser：

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

agent-browser install 管理其自身的浏览器运行时；Guion 软件包从不运行它、捆绑它或复用浏览器凭据。兼容的可执行文件必须能够直接从 PATH 运行，而无需 shell。该渲染器在 macOS 和 Linux 宿主上受支持。HTTP 渲染仍然可用，并且在 agent-browser 缺失时，这三个 npm 软件包仍可安装。

渲染会话是全新且非持久化的。启动前，目标必须是 HTTP(S) 公共主机名或地址。随后浏览器允许列表仅包含所请求的主机名、*.（目标及其子域），以及以下固定的通用 CDN 集合：

- cdn.jsdelivr.net
- unpkg.com
- cdnjs.cloudflare.com
- ajax.googleapis.com
- fonts.googleapis.com
- fonts.gstatic.com
- esm.sh

调用方无法扩大此列表。对未知域的重定向、API、框架、worker、socket 或其他依赖会以 render_domain_not_allowed 失败关闭；增加 waitMs 也无济于事。请在 https://github.com/guionai/web/issues/new 报告可能缺失的第一方或通用 CDN 域，并附上页面 URL 和被阻止的域。不要在 issue 中包含凭据或页面机密。

这是浏览器级别的主机名边界，并非完整的 SSRF 防护或宿主出口防火墙。字面量和 DNS 解析后的私有/保留目标会在启动前被拒绝，但允许列表中的恶意主机名可以在验证后将其 DNS 应答更改为私有地址（DNS 重绑定），并且此处没有操作系统级别的宿主出口隔离。在没有按连接进行 SSRF 过滤的代理或容器/微虚拟机出口隔离的情况下，不要在公共或多租户服务中将此后端用于任意不受信任的 URL。

开发

这是一个 pnpm workspace。安装依赖并运行与 CI 相同的本地门禁：

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

test:release 使用一次性 manifest 来演练 tag-version
同步。test:pack 在测试自有的临时目录中运行每个公共包的打包安装或宿主加载契约。test:image 构建一个测试自有的一次性 Docker 镜像，针对伪造的 /api/render 网关运行它，并验证该镜像不包含浏览器可执行文件。

发布

v 标签是全部三个公共包的发布事实来源：@guionai/web、@guionai/pi-web 和 @guionai/dsh-web。发布预检会从该标签同步其检出清单，然后在任何发布开始之前完成格式化、类型检查、构建、测试、发布版本检查、打包冒烟测试以及 Docker 镜像契约。

随后，三个独立、非快速失败且受保护的 npm Environment 矩阵单元各自通过 npm Trusted Publishing 发布一个包，并附带来源证明。同步后的版本会为稳定版 SemVer 选择 npm 的 latest 标签，为预发布版选择 beta。一个匹配的不可变标签镜像会以 web serve 入口点发布到 ghcr.io/guionai/web:。该镜像将显式浏览器渲染委托给配置的内部 Browser Rendering Gateway，并且不包含浏览器可执行文件。在所有三个 npm 单元和镜像任务成功后，工作流会创建 GitHub 发布，包含生成的说明、源代码归档以及构建生成的 openapi.yaml 资产。该资产由与镜像和包相同的 Hono 路由模式生成；它不会被检入，也不会独立进行版本管理。它不发布任何二进制文件或平台归档。

如果发布部分失败，请使用 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 发布作业之外传递来源证明。
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 令牌，并为每次正常发布请求来源证明。
永远不要覆盖或取消发布某个版本。对于部分完成的 GitHub 发布，只重新运行其失败的发布单元格。