dsh-inner-browser-use 0.39.0 → 0.41.0

package/README.md

@@ -12,7 +12,7 @@ live picture of that browser, and your own cursor keeps working on the picture.
 | --- | --- |
 | `browser_open` | Starts the browser (or reuses the running one) and opens an address. `headless: false` shows a real window on the desktop instead. |
 | `browser_view` | Returns the address, the title, every control as `1 … 120`, and the visible text. |
-| `browser_read` | Reads the page the way a person does: one Markdown block of headings, paragraphs, lists and links, no controls. Far fewer tokens than a snapshot on long pages, and the links stay usable. Give it a `query` and only the passages that answer it come back, ranked (BM25 over Readability-style blocks, link-heavy menus down-weighted). |
+| `browser_read` | Reads the page the way a person does: one Markdown block of headings, paragraphs, lists and links, no controls. Far fewer tokens than a snapshot on long pages, and the links stay usable. Give it a `query` and only the sentences that answer it come back: BM25 over Readability-style blocks, then per-sentence scoring with heading, position and link-density priors, idf-weighted coverage, MMR de-duplication and a character budget — 92% fewer tokens on a long page in the bench. A question the page cannot answer returns the nearest passages and says so instead of pasting the page (79% fewer tokens in the bench). |
 | `browser_find` | Finds words (or a regex) anywhere on the page: matching controls come back with a clickable number, matching text with its point, each saying whether it is on screen. |
 | `browser_extract` | Returns the items a CSS selector matches, one compact line each with its link, instead of the whole page. |
 | `browser_click` | Clicks a numbered control, or an `x`/`y` point. `double: true` double-clicks. A cookie banner or modal over the control is cleared first, then the click happens. |

package/README.zh.md

@@ -11,7 +11,7 @@ profile，不是产品自带的那个浏览页签：右栏放的是它的画面
 | --- | --- |
 | `browser_open` | 启动浏览器（已在跑就复用）并打开一个地址。传 `headless: false` 会改为在桌面上开真实窗口。 |
 | `browser_view` | 返回地址、标题、编号成 `1 … 120` 的控件，以及可见文字。 |
-| `browser_read` | 按人读文章的方式给 Markdown（标题、段落、列表、链接）。带 `query` 只回能回答的段落；问不到时自动改为整页，不再空手回来。页面和上次读的没变就只回一行，不重发正文（`force: true` 强制重发）。 |
+| `browser_read` | 按人读文章的方式给 Markdown（标题、段落、列表、链接）。带 `query` 只回能回答的那几句（段落排序后再按句子打分，标题、位置、链接密度做先验，重复句去掉，按字符预算装箱）；问不到时只回最近的三段并明说没答上，不再把整页端回来。页面和上次读的没变就只回一行，不重发正文（`force: true` 强制重发）。 |
 | `browser_extract` | 按 CSS 选择器把列表项读成一行一条、带链接，比整页读省得多。 |
 | `browser_view` 的 `map` | 大页面先看地标：各类控件各多少个、去重后的控件和编号、正文多少字，但不带回正文。 |
 | `browser_click` | 点编号控件，或点 `x`/`y` 坐标。`double: true` 双击。控件被横幅或弹层挡着时，先关掉它再点。 |

package/docs/ARCHITECTURE.md

@@ -165,6 +165,33 @@ picture comes back on the mutation that satisfies it. A page that changes 137 ms
 starts answers at 138 ms, not at the next 100 ms tick — the same reason `idle` (a mutation-free
 window) costs one round trip on an animation-heavy page instead of one per frame.
 
+## Reading for an answer
+
+`browser_read` with a `query` does not return the page; it returns the sentences that answer the
+question. The page-side block reader already returns paragraphs with their heading and link
+density, so the work stays in `read.js` and costs no extra round trip.
+
+Paragraphs are ranked first (BM25 over the question's terms, link-heavy menus down-weighted), then
+split into sentences. Each sentence is scored on its own with the same saturation and length
+normalisation, and that score is multiplied by three priors: the words of its heading, the rank of
+the paragraph it sits in, and inverse link density. Words the page says everywhere are dropped
+before scoring — a term in most sentences cannot point at anything — and a sentence that matches
+only part of the question is scaled by the share of the question's idf weight it actually covers,
+which is what stops a paragraph containing "to" from competing with one containing "refund".
+
+Selection is not "the top N scores": each pick subtracts its Jaccard overlap with what is already
+chosen (MMR), selection stops when the best remaining sentence is worth nothing, and picked
+sentences are packed to a character budget and restored to document order. Terms are folded
+(plurals, trailing `-ing`/`-ed`) so a question can use a different inflection than the page.
+
+`sentences: false` keeps the paragraph path for callers who want the whole section.
+
+A question the page cannot answer costs the miss, not the page: when no sentence clears the
+cut, `readRelevant` returns the three blocks that ranked highest (each trimmed towards 260
+characters) and no text, and the tool turns that into a line saying nothing directly answers the
+question plus those passages. The whole page is still one `browser_view` away, so the expensive
+fallback — a page pasted into the context for a question it never addressed — is gone.
+
 ## Sign-ins and reclaim
 
 Sign-in state lives in the profile, and session cookies — the kind a sign-in usually sets,

package/docs/BENCH.md

@@ -1,3 +1,36 @@
+## 问了但页面没答（0.41.0）
+
+同一张故事页，问一个页面里根本没有的词（`quantum chromodynamics`）。左边是旧的兜底：
+把整页当答案交出去；右边是现在只给最近的三段加一句说明。
+
+| 项 | 整页兜底 | 最近几段 |
+| --- | --- | --- |
+| 回来的字符数 | 2089 | 438 |
+| 折合 token | 614 | 129 |
+| 省下 | — | 79% |
+| 最近几段 | — | 3 段（每段 ≤ 260 字） |
+| 是否明说没答上 | 否 | 是 |
+| 读这一趟 | — | 7 ms |
+
+命中路径的 `read-answer` 行不受影响（1172 → 90 字，省 92%）。
+
+## 只读答案那几句（0.40.0）
+
+同一张本地故事页：24 段会议记录里夹着一段账单说明，问题是「退款多久到账」。一条路按段
+落读（`sentences: false`），另一条走默认的句子级证据。
+
+| 项 | 整页段落 | 句子证据 |
+| --- | --- | --- |
+| 回来的字符数 | 1172 | 90 |
+| 折合 token | 345 | 26 |
+| 答案还在 | 是 | 是（`30 days`） |
+| 命中的块 / 总块 | 8 / 49 | 1 / 49 |
+| 读这一趟 | — | 11 ms |
+
+省下 92%，`read-answer` 预算 250 ms。句子级这一步没有新增进程、没有模型、没有依赖：分句、
+打分、去重都在已有的阅读调用里完成。同一批里的 `read` / `read-repeat` / `read-changed` 行与
+0.39.0 持平（`dense` 6 ms / 337 token，`full` 6 ms / 624 token）。
+
 ## 登录能留、能切、关得掉（0.39.0）
 
 本地页签在加载时写一个会话 cookie 和一个 `localStorage` 令牌，然后用工具层实际走一遍：保存 → 清空浏览器里的一切 → 切回。磁盘上那一份同时用字符串搜一遍。

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "dsh-inner-browser-use",
-  "version": "0.39.0",
+  "version": "0.41.0",
   "description": "An agent-owned Chromium sidecar mirrored into the DeepSeek Harness right column: the agent drives it, the person watches and can take the mouse, and logins survive restarts.",
   "type": "module",
   "main": "index.js",

package/read.js

@@ -1185,7 +1185,22 @@ const tokenPattern = /[a-z0-9]+|[\u3400-\u9fff]/g
  * @returns {string[]} lower-case terms.
  */
 export function terms(text) {
-  return String(text ?? '').toLowerCase().match(tokenPattern) ?? []
+  const raw = String(text ?? '').toLowerCase().match(tokenPattern) ?? []
+  return raw.map(fold)
+}
+
+/** "refunds" and "refund" are the same idea; a light fold lets a question that
+ * says one word find a page that says the other. Deliberately not a stemmer —
+ * no dictionary, no suffix table beyond plurals and a trailing -ing/-ed. */
+function fold(word) {
+  if (word.length <= 3 || /[0-9]/.test(word) || /[^a-z]/.test(word)) return word
+  if (word.endsWith('ies') && word.length > 4) return `${word.slice(0, -3)}y`
+  if (word.endsWith('sses')) return word.slice(0, -2)
+  if (word.endsWith('ing') && word.length > 5) return word.slice(0, -3)
+  if (word.endsWith('ed') && word.length > 4 && !word.endsWith('eed')) return word.slice(0, -2)
+  if (word.endsWith('es') && word.length > 4) return word.slice(0, -2)
+  if (word.endsWith('s') && !word.endsWith('ss') && !word.endsWith('us') && !word.endsWith('is')) return word.slice(0, -1)
+  return word
 }
 
 /** How often a term may occur before it stops adding meaning. */
@@ -1230,6 +1245,134 @@ export function rank(blocks, query) {
   return scored
 }
 
+/** A sentence ends at a full stop, a question mark, an exclamation, or their
+ * CJK equivalents; a very short fragment joins its neighbour rather than
+ * travelling alone. */
+const SENTENCE_BREAK = /(?<=[。！？；])|(?<=[.!?;])\s+/u
+
+/**
+ * @param {string} text - a paragraph.
+ * @returns {string[]} its sentences, trimmed.
+ */
+export function sentences(text) {
+  const raw = String(text ?? '').replace(/\s+/g, ' ').trim()
+  if (raw === '') return []
+  const out = []
+  for (const piece of raw.split(SENTENCE_BREAK)) {
+    const one = piece.trim()
+    if (one === '') continue
+    /* A full stop inside "e.g." leaves a fragment whose continuation starts
+       lowercase; that is the one case where the break was not real. */
+    const continues = /^[a-z(]/.test(one) || out[out.length - 1]?.length < 4
+    if (out.length > 0 && continues) out[out.length - 1] = `${out[out.length - 1]} ${one}`
+    else out.push(one)
+  }
+  return out
+}
+
+/**
+ * The sentences that answer a query, chosen the way a retriever picks
+ * evidence: BM25 over sentences, a prior for the paragraph and heading they
+ * sit in, and maximal-marginal-relevance so the second sentence adds
+ * something the first did not say. Purely local — no model, no network.
+ * @param {{h?: string, t?: string, d?: number}[]} blocks - paragraphs.
+ * @param {string} query - what the caller wants to know.
+ * @param {{maxChars?: number, limit?: number, blocks?: number, lambda?: number}} [options] - ceilings.
+ * @returns {{rows: {text: string, heading: string, at: number, step: number}[], total: number, matched: number}} picked sentences in page order.
+ */
+export function evidence(blocks, query, options = {}) {
+  const typed = terms(query)
+  if (typed.length === 0) return { rows: [], total: blocks.length, matched: 0 }
+  const near = rank(blocks, query).slice(0, Math.max(1, Math.min(60, Number(options.blocks ?? 40))))
+  const units = []
+  for (const row of near) {
+    const heading = String(row.block.h ?? '')
+    const body = String(row.block.t ?? '')
+    const parts = sentences(body)
+    for (let step = 0; step < parts.length; step += 1) {
+      const spoken = terms(parts[step])
+      if (spoken.length === 0) continue
+      units.push({ text: parts[step], terms: spoken, heading, at: blocks.indexOf(row.block), step, prior: row.score, block: row.block })
+    }
+  }
+  if (units.length === 0) return { rows: [], total: blocks.length, matched: 0 }
+  const total = Math.max(1, units.length)
+  const seen = new Map()
+  for (const unit of units) for (const term of new Set(unit.terms)) seen.set(term, (seen.get(term) ?? 0) + 1)
+  const average = units.reduce((sum, unit) => sum + unit.terms.length, 0) / total
+  /* A word the page says everywhere cannot point at anything: "to" is in every
+     paragraph of a long article. Keep the terms that actually narrow the page;
+     if the question is all common words, keep them all. */
+  const weight = (term) => {
+    const inHowMany = seen.get(term) ?? 0
+    return inHowMany === 0 ? 0 : Math.log(1 + (total - inHowMany + 0.5) / (inHowMany + 0.5))
+  }
+  const sharp = typed.filter((term) => weight(term) >= 0.5)
+  const asked = sharp.length > 0 ? sharp : typed
+  const askedWeight = asked.reduce((sum, term) => sum + weight(term), 0)
+  for (const unit of units) {
+    const counts = new Map()
+    for (const term of unit.terms) counts.set(term, (counts.get(term) ?? 0) + 1)
+    let score = 0
+    let covered = 0
+    for (const term of asked) {
+      const tf = counts.get(term) ?? 0
+      if (tf === 0) continue
+      covered += weight(term)
+      score += weight(term) * ((tf * (SATURATION + 1)) / (tf + SATURATION * (1 - 0.75 + (0.75 * unit.terms.length) / average)))
+    }
+    /* Matching one frequent word of a nine-word question is not evidence; the
+       share of the question's weight the sentence actually answers is. */
+    score *= covered / Math.max(1e-6, askedWeight)
+    /* The paragraph's own relevance and the words of the heading it sits under
+       both say "this is the right place", so they lift their sentences. */
+    const headingHit = asked.filter((term) => terms(unit.heading).includes(term)).length
+    /* A menu sentence can match the words without saying anything about them;
+       the paragraph's link density is what tells the two apart. */
+    const linkish = 1 - 0.8 * Number(unit.block?.d ?? 0)
+    unit.score = score * linkish * (1 + 0.25 * headingHit) * (1 + 0.5 * (unit.prior > 0 ? 1 : 0))
+  }
+  /* Below a fifth of the best sentence, a match is coincidence rather than
+     evidence; carrying it only costs tokens. */
+  const best = units.reduce((top, unit) => Math.max(top, unit.score), 0)
+  for (const unit of units) if (unit.score < best * 0.2) unit.score = 0
+  const lambda = Math.max(0, Math.min(0.9, Number(options.lambda ?? 0.35)))
+  const ceiling = Math.max(200, Math.min(24_000, Number(options.maxChars ?? 4000)))
+  const limit = Math.max(1, Math.min(60, Number(options.limit ?? 24)))
+  const chosen = []
+  const left = units.filter((unit) => unit.score > 0)
+  let used = 0
+  let lastHeading = ''
+  while (left.length > 0 && chosen.length < limit) {
+    let best = -1
+    let bestValue = -Infinity
+    for (let i = 0; i < left.length; i += 1) {
+      const candidate = left[i]
+      const spoken = new Set(candidate.terms)
+      let overlap = 0
+      for (const picked of chosen) {
+        const other = new Set(picked.terms)
+        let shared = 0
+        for (const term of spoken) if (other.has(term)) shared += 1
+        overlap = Math.max(overlap, shared / Math.max(1, spoken.size + other.size - shared))
+      }
+      const value = candidate.score * (1 - lambda) - lambda * overlap
+      if (value > bestValue) { bestValue = value; best = i }
+    }
+    /* Once the best sentence left is no better than nothing — or is simply a
+       repeat of one already picked — the answer is complete. */
+    if (best < 0 || bestValue <= 0) break
+    const pick = left.splice(best, 1)[0]
+    const heading = pick.heading !== lastHeading && pick.heading !== '' ? pick.heading.length + 8 : 0
+    if (used + pick.text.length + heading > ceiling && chosen.length > 0) break
+    lastHeading = pick.heading
+    used += pick.text.length + heading
+    chosen.push(pick)
+  }
+  chosen.sort((a, b) => a.at - b.at || a.step - b.step)
+  return { rows: chosen.map((one) => ({ text: one.text, heading: one.heading, at: one.at, step: one.step })), total: blocks.length, matched: chosen.length }
+}
+
 /**
  * Read only the passages of a page that answer a query, so a long page costs
  * what the answer costs instead of what the page costs.
@@ -1240,20 +1383,37 @@ export function rank(blocks, query) {
  */
 export async function readRelevant(page, query, options = {}) {
   const budget = Math.max(400, Math.min(24_000, Number(options.maxChars ?? 4000)))
+  /* A short, untrimmed paragraph is what a miss shows: enough to say what the
+     page is about, never enough to be the page. */
+  const near = (blocks) => blocks
+    .map((block) => String(block?.t ?? '').replace(/\s+/g, ' ').trim())
+    .filter((body) => body !== '')
+    .slice(0, 3)
+    .map((body) => {
+      const cut = body.length > 260 ? `${body.slice(0, 260).replace(/\s+\S*$/, '')}…` : body
+      return { heading: '', text: cut }
+    })
   try {
     const raw = String((await evaluateIn(page, blocks(budget * 8))) ?? '{}')
     const said = JSON.parse(raw)
     const all = Array.isArray(said?.blocks) ? said.blocks : []
     const ranked = rank(all, query)
     if (ranked.length === 0) {
-      return { title: String(said?.title ?? page.title ?? ''), url: String(page.url ?? ''), text: '', chars: 0, matched: 0, total: all.length }
+      return { title: String(said?.title ?? page.title ?? ''), url: String(page.url ?? ''), text: '', chars: 0, matched: 0, total: all.length, nearby: near(all) }
+    }
+    /* Passages cost whole paragraphs; sentences cost only the ones that say
+       something about the query, which on a long page is most of the saving. */
+    let pieces = ranked
+    if (options.sentences !== false) {
+      const picked = evidence(all, query, { maxChars: budget, limit: options.limit, blocks: options.blocks, lambda: options.lambda })
+      pieces = picked.rows.map((row) => ({ block: { h: row.heading, t: row.text }, score: 0 }))
     }
-    const limit = Math.max(1, Math.min(20, Number(options.limit ?? 8)))
+    const limit = Math.max(1, Math.min(60, Number(options.limit ?? (options.sentences === false ? 8 : 24))))
     const lines = []
     let used = 0
     let matched = 0
     let lastHeading = ''
-    for (const row of ranked.slice(0, limit)) {
+    for (const row of pieces.slice(0, limit)) {
       const body = String(row.block.t ?? '')
       if (used + body.length > budget) continue
       const heading = String(row.block.h ?? '')
@@ -1263,10 +1423,15 @@ export async function readRelevant(page, query, options = {}) {
       matched += 1
       if (used >= budget) break
     }
+    /* A question the page does not answer should not cost the page: the few
+       blocks that came closest say what the page is about, and the caller can
+       still ask for everything. */
+    const nearby = matched === 0 ? near(ranked.slice(0, 3).map((row) => row.block)) : []
     return {
       title: String(said?.title ?? page.title ?? ''),
       url: String(page.url ?? ''),
       text: lines.join('\n\n'),
+      nearby,
       chars: used,
       matched,
       total: all.length,

package/tools.js

@@ -2260,8 +2260,16 @@ export function sidecarTools(sidecar, refs, host = {}) { // ui-copy-ignore
           const found = await readRelevant(page, asked, { maxChars: ceiling })
           if (found.fault !== undefined) return `the page did not answer when read — ${String(found.fault).split('\n')[0].slice(0, 200)}`
           if (found.text === '') {
-            /* The question missed every block: the page is still the answer, so
-               hand it over whole rather than make the caller guess again. */
+            /* A question the page does not answer costs the nearest passages and
+               a sentence saying so, not the whole page: whole pages are what
+               this tool exists to avoid, and the caller can ask for one. */
+            const closest = Array.isArray(found.nearby) ? found.nearby : []
+            if (closest.length > 0) {
+              const body = closest
+                .map((row) => `${row.heading === '' ? '' : `## ${String(row.heading)}\n`}${String(row.text)}`)
+                .join('\n\n')
+              return keep(`${found.url}\n# ${found.title === '' ? '(untitled)' : found.title}\n\nnothing directly answers ${JSON.stringify(asked)} (${String(found.total)} blocks read). The closest passages:\n\n${body}\n\nask for the whole page with browser_view, or try other words.`)
+            }
             const whole = await readArticle(page, { maxChars: ceiling })
             if (whole.fault === undefined && whole.text !== '') {
               return keep(`${whole.url}\n# ${whole.title === '' ? '(untitled)' : whole.title}\n\nnothing here answers ${JSON.stringify(asked)} (${String(found.total)} blocks read), so the whole page follows:\n\n${whole.text}${whole.truncated ? `\n\n(cut at ${String(whole.chars)} characters; raise max_chars for more)` : ''}`)