touch-browser

提出一个主张。获取基于页面的证据、结论和引用。

touch-browser 是 AI 代理的证据验证层。它不仅仅是抓取页面或将 HTML 转换为 Markdown。它会打开页面，编译结构化快照，并告诉你当前页面是支持该主张、反驳该主张，还是需要进一步浏览。

在以下场景中使用它：

• 需要源链接证据而非原始 HTML 转储时

• 需要代理在回答前可以检查的支持片段和结论解释时

• 针对边缘主张需要安全的未决路径而非盲目猜测时

• 需要策略限制的浏览而非盲目自动化时

• 需要可重放、可审计的多页面研究会话时

证据优先，而非事实终结：

• touch-browser 帮助 AI 收集页面局部证据并追踪其来源

• 更高级别的模型或人类仍然决定跨页面或更广阔世界中的事实真相

extract 返回的内容

来自当前提取器的缩写 claimOutcome 形状：

{
  "statement": "The Starter plan costs $29 per month.",
  "verdict": "evidence-supported",
  "confidenceBand": "high",
  "reviewRecommended": false,
  "supportSnippets": [
    {
      "blockId": "b4",
      "stableRef": "rmain:table:plan-monthly-price-snapshots-starter-29-10-000-t",
      "snippet": "Starter | $29 | 10,000"
    }
  ],
  "verdictExplanation": "Matched direct support in 3 page block(s). Review the attached snippets before reusing the claim."
}

提取器返回四个结论：

• evidence-supported：当前页面提供了可用的支持

• contradicted：当前页面提供了相互冲突的证据

• insufficient-evidence：当前页面未提供足够的直接支持

• needs-more-browsing：当前页面尚不够具体，因此下一步是浏览另一个页面

confidenceBand、reviewRecommended、supportSnippets、verdictExplanation 和 matchSignals 的存在是为了让代理在不盲目信任第一个匹配项的情况下决定下一步操作。

MCP 包

主要的本地主机 MCP 路径：

• npm 包：@nangman-infra/touch-browser-mcp

• 范围：公共文档和研究网络

• MCP 合约：仅限无头模式、自动搜索引擎选择、针对挑战/身份验证/MFA 的监督恢复移交

推荐的主机配置：

{
  "mcpServers": {
    "touch-browser": {
      "command": "npx",
      "args": ["-y", "@nangman-infra/touch-browser-mcp"]
    }
  }
}

首次启动时，该包会从 GitHub Releases 下载匹配的独立运行时包，验证已发布的 .sha256，将其安装在 ~/.touch-browser/npm-mcp/versions/ 下，然后启动 touch-browser mcp。

当你希望本地 MCP 主机（如 Claude Desktop、Cursor 或 Codex）在无需手动安装运行时的情况下进行连接时，请使用此包。

独立包

标记为 v* 的推送现在会在 Standalone Release 工作流中构建独立的 macOS 和 Linux 包。每个包包含：

• bin/touch-browser

• runtime/touch-browser-bin 下的优化 Rust 二进制文件

• 打包的 Node 运行时和 Playwright 适配器

• 默认的语义运行脚本和模型缓存

当发布标记版本时，从 GitHub Releases 下载匹配的 tarball，解压并运行：

./touch-browser-<version>-<platform>-<arch>/install.sh
touch-browser telemetry-summary
touch-browser update --check

要在本地构建相同的便携包：

pnpm install --frozen-lockfile
pnpm run build:standalone-bundle -- v0.1.0-rc1

# Then install the bundled command into PATH
./dist/standalone/touch-browser-v0.1.0-rc1-<platform>-<arch>/install.sh
touch-browser telemetry-summary
touch-browser update --check

独立路径仍然是官方的 CLI、操作、离线和回退安装路径：

1. 解压独立包

2. 运行 install.sh

3. 对所有 CLI 和服务操作使用已安装的 touch-browser 命令

安装程序现在执行托管安装：

• 托管版本位于 ~/.touch-browser/install/versions/<bundle-name> 下

• 活动版本为 ~/.touch-browser/install/current

• PATH 命令指向 ~/.touch-browser/install/current/bin/touch-browser

• touch-browser update 将 current 切换到新验证的发布包

• touch-browser uninstall --purge-all --yes 删除托管安装和所有存储的数据

首次运行

这是与已安装用户体验相匹配的仅命令验证路径：

touch-browser open https://www.iana.org/help/example-domains --browser --session-file /tmp/tb-first-run.json
touch-browser session-read --session-file /tmp/tb-first-run.json --main-only
touch-browser session-extract --session-file /tmp/tb-first-run.json \
  --claim "As described in RFC 2606 and RFC 6761, a number of domains such as example.com and example.org are maintained for documentation purposes."
touch-browser session-synthesize --session-file /tmp/tb-first-run.json --format markdown
touch-browser session-close --session-file /tmp/tb-first-run.json

已安装的搜索现在默认保持引擎级的持久信任配置文件：

• Google：~/.touch-browser/browser-search/profiles/google-default

• Brave：~/.touch-browser/browser-search/profiles/brave-default

• 配置文件状态元数据：~/.touch-browser/browser-search/<engine>.profile-state.json

贡献者从源码构建

先决条件：rustup、Node.js 18+、pnpm。

bash scripts/bootstrap-local.sh
cargo build --release -p touch-browser-cli
pnpm run build:standalone-bundle -- local-dev
./dist/standalone/touch-browser-local-dev-<platform>-<arch>/install.sh

源码检出是贡献者工作流。发布和操作文档仍然假设使用来自独立包的已安装 touch-browser 命令。

bootstrap-local.sh 将默认语义模型安装在：

• ~/.touch-browser/models/evidence/embedding

• ~/.touch-browser/models/evidence/nli

仅当你需要覆盖这些默认位置时，才使用 TOUCH_BROWSER_EVIDENCE_EMBEDDING_MODEL_PATH 或 TOUCH_BROWSER_EVIDENCE_NLI_MODEL_PATH。

为什么不仅仅使用 Markdown？

touch-browser 并不试图取代每一个爬虫或浏览器工具。它的工作在页面获取之后开始。

产品界面

主要界面：

• extract：根据当前页面验证主张并返回结构化的主张结果

支持的读取界面：

• read-view：供人类审阅者或验证模型阅读的 Markdown

• compact-view：用于代理循环的低 Token 语义状态

• search：在打开候选页面之前的结构化发现

安全和审计界面：

• policy：将页面和操作分类为允许、审阅或阻止

• session-synthesize：将多页面会话转换为带有引用的 JSON 或 Markdown

• serve：通过 stdio JSON-RPC 公开运行时，用于 MCP 或代理集成

touch-browser 是什么

• 一个证据优先的提取器

• 一个选择性预测界面

• 一个验证器友好的路由层

touch-browser 不是什么

• 一个通用真理预言机

• 一个通用的爬虫替代品

• 一个保证每个不支持的主张都是错误的工具

MCP 示例

推荐用于本地主机的 MCP 设置：

{
  "mcpServers": {
    "touch-browser": {
      "command": "npx",
      "args": ["-y", "@nangman-infra/touch-browser-mcp"]
    }
  }
}

MCP 包有意比完整的 CLI 更窄：

• 范围是公共文档和研究网络

• 推荐循环是 tb_search -> tb_search_open_top -> tb_read_view -> tb_extract

• engine 不通过 MCP 公开

• headed 不通过 MCP 公开

• 如果页面显示挑战、身份验证、MFA 或其他监督恢复，请停止并移交给人类，而不是尝试使用不同的浏览器设置重试

用于已安装独立命令的替代 MCP 桥接设置：

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

该桥接在底层启动 touch-browser serve 并公开工具，如 tb_search、tb_search_open_top、tb_open、tb_read_view、tb_extract、tb_tab_open 和 tb_session_synthesize。

仓库检出集成资产：

{
  "mcpServers": {
    "touch-browser": {
      "command": "node",
      "args": ["integrations/mcp/bridge/index.mjs"]
    }
  }
}

独立包附带 touch-browser mcp 和 touch-browser serve。检入的 Node 启动器仍然是用于仓库检出或容器镜像的仓库集成资产。

默认情况下，桥接优先使用显式的 TOUCH_BROWSER_SERVE_COMMAND，然后是显式的二进制路径，然后是已安装或打包的 touch-browser 二进制文件，最后是仓库本地的 target/{release,debug} 二进制文件。如果都不可用，它会快速失败并给出安装/构建说明，而不是回退到 cargo run。

如果你想强制使用特定的构建二进制文件或包装命令，请使用 TOUCH_BROWSER_SERVE_COMMAND。

架构

Query / URL / fixture / browser tab
  -> browser-first search result parsing
  -> Acquisition
  -> Observation compiler
  -> read-view / compact-view
  -> extract (evidence + citations + optional verifier)
  -> policy
  -> session synthesis / replay
  -> CLI / JSON-RPC serve / MCP

文档与证明

• 快速入门和操作：doc/INSTALL_AND_OPERATIONS.md

• 命令界面：doc/CLI_SURFACE_SPEC.md

• 证据操作模型：doc/EVIDENCE_OPERATING_MODEL.md

• npm MCP 包：packages/mcp/README.md

• 示例：examples/README.md

• 集成：integrations/README.md

• 基准测试和定位：doc/README.md

• 试点和操作包：doc/PILOT_PACKAGE_SPEC.md, doc/OPERATIONS_SECURITY_PACKAGE_SPEC.md

许可证

本仓库现在使用 MPL-2.0。

• 允许商业和非商业使用

• 如果你分发修改后的 MPL 覆盖文件，这些覆盖文件仍受 MPL-2.0 约束

• 大型作品中的独立文件可以使用不同的条款

• 完整法律文本：LICENSE

• 通俗语言政策：LICENSE-POLICY.md