跪拜 Guibai
← All articles
GitHub

Modern Web Guidance: A Searchable Browser API Spec for Coding Agents

By dong_junshuai ·
Read original on juejin.cn ↗ Google Translate ↗ Alt translation

The browser platform moves faster than model training data, so agents need a reliable way to look up current APIs and per-project compatibility rules. This tool gives them that without forcing a full vector database or a live LLM call, and its evaluation harness makes 'guidance works' a testable claim.

Summary

Coding agents routinely produce hand-rolled modal dialogs with custom overlays, Esc listeners, and inert tricks when the browser's native <dialog> element already covers most of that behavior. Modern Web Guidance, a Google Chrome project now on GitHub, treats the mismatch between browser platform changes and model training data as a retrieval problem. It ships a CLI and Agent skills that search short English queries against a curated set of Web platform guides, retrieve relevant sections, and apply per-project compatibility gates via .mwgrc.

The implementation keeps retrieval cheap and self-contained: static Int8 word embeddings for queries, BM25 for literal matches, and Reciprocal Rank Fusion to merge both lists. Feature gating blocks preview or Origin Trial capabilities unless a project explicitly opts in. A separate legacy-scan entry finds existing patterns that match modernization opportunities. The repo also includes a harness that compares guided versus unguided agents on real tasks, with Playwright assertions against behavior expectations, so guide authors can measure whether their advice actually changes generated code.

Takeaways
— Modern Web Guidance is a Google Chrome project split into a source repo (GoogleChrome/modern-web-guidance-src) and a distribution repo (GoogleChrome/modern-web-guidance).
— Query encoding uses static Int8 word embeddings with 256 dimensions, no remote model calls for unknown words.
— Retrieval merges dense cosine similarity and BM25 lexical scores via Reciprocal Rank Fusion with k=60, returning up to 10 guide IDs by default.
— Feature gating in retrieve throws an error unless the project's .mwgrc explicitly allows Origin Trial or volatile capabilities; the CLI exits with code 1 on any gated error.
— The legacy-scan entry finds modernization opportunities based on rules but does not rewrite code; results can carry keepWhen/dropWhen flags.
— Telemetry is enabled by default and logs search queries, hit guides, and latency; set DISABLE_TELEMETRY=1 to disable.
— Node.js 22+ is required for the published CLI.
— Guides are licensed CC BY 4.0 while the software is Apache-2.0.
— The evaluation harness uses Playwright assertions on concrete tasks to compare guided vs. unguided agent outputs.
— The .mwgrc configuration stops at the nearest .git or .mwgrc, so user-level settings don't inherit inside a Git project.
Conclusions

The deliberate choice to keep query embeddings static and lexical means retrieval is cheap and self-contained, but it also caps expressiveness; the tool is tuned for a bounded set of Web guides, not general semantic search.

Hard feature gating in retrieve is a policy gate, not a security boundary; an agent can still write code from its own knowledge, so compliance depends on the calling context.

The evaluation harness measures success on specific tasks and assertions, not overall code quality; a guide that improves a dialog task may not transfer to other scenarios.

Search and retrieval are deliberately separated: ranking signals relevance, while retrieval checks compatibility, preventing high-ranking but unsafe recommendations from being treated as production-ready.

Concepts & terms
Reciprocal Rank Fusion (RRF)
A method for merging two ranked lists by summing the reciprocal ranks of each item across lists, so items appearing high on both lists get a boost without needing scores on the same scale.
BM25
A lexical ranking function that scores documents based on term frequency and inverse document frequency, useful for matching literal API names and abbreviations.
Static embeddings
Pre-computed word vectors from a distilled teacher model, stored as Int8 with per-row scales; used for query encoding at runtime without loading a full Transformer model.
Feature gating
A mechanism in retrieve that blocks guides associated with Origin Trial or volatile browser features unless the project's .mwgrc explicitly sets the corresponding field to true.
Baseline
A target browser support level (e.g., Widely available, newly, limited) that influences the prompt text returned with retrieved guides, helping agents align with a project's compatibility goals.
Source: juejin.cn ↗ Google Translate ↗ Backup ↗