touch-browser

Plantea una afirmación. Obtén evidencia basada en la página, veredictos y citas.

touch-browser es una capa de verificación de evidencia para agentes de IA. Hace más que simplemente obtener una página o convertir HTML a Markdown. Abre una página, compila una instantánea estructurada y te dice si la página actual respalda una afirmación, la contradice o si aún se necesita navegar más.

Úsalo cuando necesites:

• evidencia vinculada a la fuente en lugar de volcados de HTML sin procesar

• fragmentos de respaldo y explicaciones de veredictos que un agente pueda inspeccionar antes de responder

• una ruta segura no resuelta para afirmaciones dudosas en lugar de improvisar

• navegación restringida por políticas en lugar de automatización ciega

• sesiones de investigación de varias páginas reproducibles y auditables

Primero la evidencia, no el hecho final:

• touch-browser ayuda a una IA a recopilar evidencia local de la página y rastrear de dónde proviene

• un modelo de nivel superior o un humano aún decide qué es verdad a través de las páginas o en el mundo en general

Qué devuelve extract

Forma abreviada de claimOutcome del extractor actual:

{
  "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."
}

El extractor devuelve cuatro veredictos:

• evidence-supported: la página actual mostró respaldo utilizable

• contradicted: la página actual mostró evidencia contradictoria

• insufficient-evidence: la página actual no proporcionó suficiente respaldo directo

• needs-more-browsing: la página actual aún no es lo suficientemente específica, por lo que el siguiente paso es otra página

confidenceBand, reviewRecommended, supportSnippets, verdictExplanation y matchSignals están ahí para que un agente pueda decidir qué hacer a continuación sin confiar ciegamente en la primera coincidencia.

Paquete MCP

Ruta MCP principal del host local:

• paquete npm: @nangman-infra/touch-browser-mcp

• alcance: documentos públicos y web de investigación

• contrato MCP: solo sin interfaz gráfica (headless), selección automática de motor de búsqueda, transferencia de recuperación supervisada para desafíos/autenticación/MFA

Configuración de host recomendada:

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

En el primer lanzamiento, el paquete descarga el paquete de tiempo de ejecución independiente correspondiente desde GitHub Releases, verifica el .sha256 publicado, lo instala en ~/.touch-browser/npm-mcp/versions/ y luego inicia touch-browser mcp.

Usa este paquete cuando desees que un host MCP local como Claude Desktop, Cursor o Codex se conecte sin una instalación manual separada del tiempo de ejecución.

Paquete independiente

Las versiones etiquetadas como v* ahora crean paquetes independientes para macOS y Linux en el flujo de trabajo Standalone Release. Cada paquete incluye:

• bin/touch-browser

• el binario de Rust optimizado en runtime/touch-browser-bin

• un tiempo de ejecución de Node empaquetado y un adaptador de Playwright

• los scripts de ejecución semántica predeterminados y la caché del modelo

Cuando se publique una versión etiquetada, descarga el archivo tar correspondiente desde GitHub Releases, descomprímelo y ejecuta:

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

Para crear el mismo paquete portátil localmente:

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

La ruta independiente sigue siendo la ruta oficial de CLI, operaciones, sin conexión y de instalación de respaldo:

1. descomprimir un paquete independiente

2. ejecutar install.sh

3. usar el comando touch-browser instalado para cada operación de CLI y servicio

El instalador ahora realiza una instalación gestionada:

• las versiones gestionadas viven en ~/.touch-browser/install/versions/<bundle-name>

• la versión activa es ~/.touch-browser/install/current

• el comando PATH apunta a ~/.touch-browser/install/current/bin/touch-browser

• touch-browser update cambia current a un paquete de lanzamiento recién verificado

• touch-browser uninstall --purge-all --yes elimina la instalación gestionada y todos los datos almacenados

Primera ejecución

Esta es la ruta de prueba solo de comandos que coincide con la experiencia de usuario instalada:

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

La búsqueda instalada ahora mantiene un perfil de confianza persistente a nivel de motor de forma predeterminada:

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

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

• metadatos del estado del perfil: ~/.touch-browser/browser-search/<engine>.profile-state.json

Construcción desde la fuente para colaboradores

Requisitos previos: 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

La descarga de la fuente es un flujo de trabajo para colaboradores. Los documentos de lanzamiento y operaciones aún asumen el comando touch-browser instalado desde el paquete independiente.

bootstrap-local.sh instala los modelos semánticos predeterminados en:

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

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

Usa TOUCH_BROWSER_EVIDENCE_EMBEDDING_MODEL_PATH o TOUCH_BROWSER_EVIDENCE_NLI_MODEL_PATH solo cuando necesites anular esas ubicaciones predeterminadas.

¿Por qué no solo Markdown?

touch-browser no intenta reemplazar cada herramienta de rastreo o navegador. Su trabajo comienza después de la adquisición de la página.

Superficie del producto

Superficie principal:

• extract: verificar afirmaciones contra la página actual y devolver resultados de afirmaciones estructurados

Superficies de lectura de apoyo:

• read-view: Markdown legible para un revisor humano o un modelo verificador

• compact-view: estado semántico de bajo token para bucles de agentes

• search: descubrimiento estructurado antes de abrir páginas candidatas

Superficies de seguridad y auditoría:

• policy: clasificar páginas y acciones como permitir, revisar o bloquear

• session-synthesize: convertir una sesión de varias páginas en JSON o Markdown con citas

• serve: exponer el tiempo de ejecución a través de stdio JSON-RPC para MCP o integración de agentes

Qué es touch-browser

• un extractor que prioriza la evidencia

• una superficie de predicción selectiva

• una capa de enrutamiento amigable para el verificador

Qué no es touch-browser

• un oráculo de verdad universal

• un reemplazo genérico de rastreador

• una garantía de que cada afirmación no respaldada es falsa

Ejemplo de MCP

Configuración de MCP recomendada para hosts locales:

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

El paquete MCP es intencionalmente más limitado que la CLI completa:

• el alcance es documentos públicos y web de investigación

• el bucle recomendado es tb_search -> tb_search_open_top -> tb_read_view -> tb_extract

• engine no se expone a través de MCP

• headed no se expone a través de MCP

• si la página indica un desafío, autenticación, MFA u otra recuperación supervisada, detente y transfiere a un humano en lugar de volver a intentar con diferentes configuraciones del navegador

Configuración de puente MCP alternativa para un comando independiente instalado:

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

El puente inicia touch-browser serve por debajo y expone herramientas como tb_search, tb_search_open_top, tb_open, tb_read_view, tb_extract, tb_tab_open y tb_session_synthesize.

Activo de integración de descarga del repositorio:

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

El paquete independiente incluye touch-browser mcp y touch-browser serve. El lanzador de Node incluido sigue siendo un activo de integración del repositorio para descargas de repositorios o imágenes de contenedores.

De forma predeterminada, el puente prefiere un TOUCH_BROWSER_SERVE_COMMAND explícito, luego una ruta binaria explícita, luego un binario touch-browser instalado o empaquetado, luego binarios locales del repositorio target/{release,debug}. Si ninguno está disponible, falla rápidamente con una instrucción de instalación/construcción en lugar de volver a cargo run.

Usa TOUCH_BROWSER_SERVE_COMMAND si deseas forzar un binario construido específico o un comando contenedor.

Arquitectura

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

Documentos y pruebas

• inicio rápido y operaciones: doc/INSTALL_AND_OPERATIONS.md

• superficie de comandos: doc/CLI_SURFACE_SPEC.md

• modelo operativo de evidencia: doc/EVIDENCE_OPERATING_MODEL.md

• paquete npm MCP: packages/mcp/README.md

• ejemplos: examples/README.md

• integraciones: integrations/README.md

• puntos de referencia y posicionamiento: doc/README.md

• paquete piloto y de operaciones: doc/PILOT_PACKAGE_SPEC.md, doc/OPERATIONS_SECURITY_PACKAGE_SPEC.md

Licencia

Este repositorio ahora usa MPL-2.0.

• se permite el uso comercial y no comercial

• si distribuyes archivos modificados cubiertos por MPL, esos archivos cubiertos permanecen bajo MPL-2.0

• los archivos separados en una obra más grande pueden usar términos diferentes

• texto legal completo: LICENSE

• política en lenguaje sencillo: LICENSE-POLICY.md