voyager-browser

@dir-ai/voyager-browser

Voyager 的网页感知能力。 安全、只读地观察一个实时 URL： 其结构、表单、链接、脚本来源、安全状况（HTTPS / HSTS / CSP / 混合内容 / Cookie）和无障碍信号（语言、图片 alt 覆盖率、标题顺序）——针对每一项都提供描述但绝不应用的修复建议。

它会解析静态 HTML——不执行 JavaScript，也不使用无头浏览器——因此会如实说明它能看到和不能看到的内容（不会渲染客户端 SPA 的运行时状态）。所有页面文本都会以不可信内容的形式返回。它受 SSRF 防护：拒绝非 http(s) URL，以及解析到私有、环回或云元数据地址的 URL。

Voyager 系列中的一种感知能力。与所有感知能力一样，它是只读的——绝不会提交表单、点击或修改任何内容。

安装

npm i -g @dir-ai/voyager-browser

使用

voyager-browser observe https://example.com
voyager-browser observe https://example.com --json

https://example.com/
https://example.com — 200; 3 finding(s), worst: medium. 0 form(s), 1 link(s).

  title: Example Domain
  security: https  ·  a11y lang:yes alt:n/a

  med   HTTPS without HSTS
        ↳ add Strict-Transport-Security: max-age=63072000; includeSubDomains
  med   no Content-Security-Policy
        ↳ add a Content-Security-Policy to constrain scripts/resources
  low   no X-Content-Type-Options: nosniff
        ↳ add X-Content-Type-Options: nosniff

作为 MCP 服务

提供一个工具：observe_page。

{ "command": "voyager-browser", "args": ["mcp"] }

作为库

import { observe } from '@dir-ai/voyager-browser'

const brief = await observe('https://example.com')
console.log(brief.summary)
console.log(brief.security)   // { https, hsts, csp, mixedContent, thirdPartyScripts, … }
console.log(brief.forms)      // insecure / cross-origin / sensitive flags
console.log(brief.findings)   // severity + described fix

检查内容

• 安全状况（关注质量，而不只是是否存在）——普通 HTTP；缺少/弱 HSTS；缺少 CSP，或 CSP 被评为弱（unsafe-inline / unsafe-eval / 通配符 / 无 object-src / 无 base-uri）；缺少点击劫持防护（X-Frame-Options / frame-ancestors）；缺少 nosniff、Referrer-Policy、Permissions-Policy；Server / X-Powered-By 泄露版本信息；HTTPS 页面上的混合内容（按来源比较，而不是前缀比较）；逐个 Cookie 检查 Secure/HttpOnly；第三方脚本缺少子资源完整性。
• 表单——HTTPS 页面上的表单提交到普通 HTTP（critical）；敏感表单（密码/付款）跨源或通过 HTTP 提交；敏感 POST 请求缺少防 CSRF 令牌；通过 GET 传输敏感数据。
• 链接——外部 target="_blank" 缺少 rel="noopener"（反向标签劫持）。
• 正文内容泄露——目录列表（Apache/nginx 自动索引）、特定语言的堆栈跟踪（Python/Java/PHP/Node/Oracle/SQLSTATE/MySQL）以及在响应正文中泄露的详细框架调试页面（Werkzeug/Flask、Rails、Symfony/Whoops、ASP.NET YSOD）——每项都会提供匹配的特征（以不可信内容形式呈现）。
• 暴露的 JWT——从 HTML、响应头、Set-Cookie 和同源脚本包中找到的 JWT 格式令牌会被解码（标头和载荷、base64url、不验证签名、不破解密钥），并标记 alg:none（critical）、已过期（exp 在过去）或缺少 exp。声明值会以不可信内容的形式呈现。
• 被动发现众所周知的敏感路径——对一个简短的固定列表（/.git/config、/.env、/.svn/entries、/.DS_Store、/config.json、/wp-config.php~、/backup/、/uploads/）执行有界、同源、只读的 GET 请求，只在确认正文特征时标记——绝不只凭 200 状态码判定。请求固定到已审核的 IP；遵循 --authorized。使用 --no-discovery 禁用。
• 无障碍性——缺少 <html lang>、图片缺少 alt、标题级别跳跃、表单字段未标注。
• 渲染情况说明——提供 render: static | hybrid | client-heavy 字段：如果页面内容由 JavaScript 渲染，简报会明确说明，并标记为 PARTIAL，而不是将空壳页面报告为正常。
• 组合提示——第三方脚本来源，可通过 @dir-ai/voyager / @dir-ai/voyager-net 进行审核。

安全性

• 只读。 使用单次 GET 获取页面；绝不提交、点击或修改内容。
• 不执行代码。 仅解析静态 HTML，不会运行页面的 JavaScript。
• 受 SSRF 防护，并固定 IP。 仅允许 http(s)；只接受单个 URL（不接受列表或凭据）。系统会解析主机，并对每个地址进行规范分类（IPv4 映射的 IPv6、未指定地址、CGNAT、NAT64、链路本地地址、私有地址、环回地址和元数据地址一律拒绝），并将连接固定到经过验证的 IP，防止 DNS 重绑定在检查和获取之间替换为内部地址。每次重定向都会重新验证并固定 IP。
• 从设计上即视为不可信。 所有进入摘要的、由站点所有者控制的字符串——标题、标题文本、元数据、链接、表单操作和字段名称——都会经过注入清理并加以标记；Agent 必须将其视为数据，而非指令。
• 有严格限制。 单一期限涵盖响应头和正文；正文有字节数上限；读取被截断时会降低置信度，绝不会报告为“干净”。
• 如实说明限制。 它读取服务器发送的内容。它看不到客户端渲染的状态，而 render 字段会准确说明它看到了多少内容。

路线图

• v0.3 — 对同源 JS 包进行静态扫描（暴露的密钥/端点/源映射）、盘点第三方服务/跟踪器/ Cookie 并进行技术指纹识别、增加映射到 WCAG 的无障碍深度检查，以及添加 CognitiveClaim 适配器，让页面观察结果可直接纳入 @dir-ai/voyager-agent 任务（页面 → 主机 → 依赖链）。
• v1.0 — 提供可选且需经同意的 --render 沙箱无头浏览器处理流程（网络隔离、资源受限），以真正覆盖 SPA/渲染后的 DOM，并始终标记为渲染模式输出；建立稳定的发现项 kind 分类体系和完整的安全态势评分。

原则始终不变：voyager-browser 通过读取更多已提供的内容来扩展能力，绝不通过对服务器采取更多操作来扩展。任何主动操作（提交、模糊测试、探测）都应属于单独且需经同意的组件。

Voyager 系列

软件包	感知
@dir-ai/voyager	Web — 已验证的互联网检索
@dir-ai/voyager-browser	网页 — 观察一个实时 URL
@dir-ai/voyager-repo	代码 — 熟悉代码仓库
@dir-ai/voyager-net	主机 — 经授权的主机审计
@dir-ai/voyager-contract	各种感知能力所遵循的认知契约
@dir-ai/voyager-agent	组合这些能力的 Agent

许可证

MIT © dir-ai