Merge remote-tracking branch 'origin/master' into xtr/react-loop-simplification

# Conflicts: # examples/acp-agent/tests/goal-snapshots/goal-session/input.json # packages/client/ui-conversation/README.i18n.yaml # packages/session-persistence/session-persistence-jsonl/src/zstd.ts # packages/support/acp-snapshot/src/harness.ts
2026-08-04 14:14:57 +08:00
parent ab441389b2 4b591c0abc
commit 1b16cef582
32 changed files with 432 additions and 230 deletions
--- a/packages/client/ui-conversation/README.i18n.yaml
+++ b/packages/client/ui-conversation/README.i18n.yaml
@@ -2,5 +2,5 @@
 # side as of the last confirmed-consistent state. Both languages carry equal authority;
 # after editing either side, bring the other along and re-record with:
 #   pnpm run verify-translation-pairing --write packages/client/ui-conversation/README.md
-README.md: 2584b58494d2f9650e2d935b8692d91fbd860b04
-README.zh.md: cd18810164eee01d4681b557399c5808140d079f
+README.md: 8d39ff1bf39ccf175a4bb80938d24a6478657155
+README.zh.md: e6e82ca61e429d8a4042f13246cc80108b3887ca
--- a/packages/client/ui-conversation/README.md
+++ b/packages/client/ui-conversation/README.md
@@ -22,7 +22,7 @@ Generic tool rows classify the built-in bash, read, search, write, edit, and run

 A tool call declaring the `terminal` render intent renders its command output inline, at both conversation render sites, through ui-primitives' `TerminalBlock`. `contract/terminal-card-model.ts` is the single derivation from the snapshot's `callView`/`resultView` pair, so the sites cannot disagree about a command, its cwd, or its exit status; it yields null — the generic path — for any other card tag, including one this client version does not know. Both sites therefore also show the card's run-state dot, which is the same `StateDot` semantic a tool row's leading icon carries, so a row and its own card always agree about one command's state. A multi-line command gets one prompt row per line, with the dot marking the call once on the first row — the exit status is the whole call's, so a dot per line would claim a per-line outcome bash does not report. The keyed `BashRow` carries the card resident below its summary row; since tool rows are no longer details-panel click targets, the card's copy and expand controls are the row's only interactions. The render-site fallback row keeps the card behind its existing expand control. Rows cap at `CHAT_TERMINAL_MAX_LINES` (8) against the panel's 16, which is what keeps a summary surface bounded — the panel stays the single-call reading surface. Inline output is licensed per render intent — the terminal and web cards, each with its own bound. A Bash execution failure that settles on the generic path instead exposes its original arguments and full error through the same bounded IN/OUT disclosure, while successful generic results such as a background-start acknowledgement remain summary-only ([decision](../../../.agents/notes/implemented/feature/2026-07-28-web-terminal-card.md)).

-A tool call declaring the `web` render intent renders its web retrieval inline, at both conversation render sites, through ui-primitives' `WebBlock`. `contract/web-card-model.ts` is the single derivation from the snapshot's `resultView`, mirroring the terminal card, so the sites cannot disagree about what a web call shows; it yields null — the generic path — for a running call, a non-web result view, a generic result view, a `card` tag this client version does not know, or a web card whose `kind` this client version does not know (a newer host's value, which the wire cannot be trusted to be `search` or `fetch`). The keyed `WebRow` registers one component under both `web_search` and `web_fetch`, discriminating on the tool name only for its icon and title; it composes the shared `ToolRow`, feeding the card as ToolRow's `web` body, so the retrieval is the row's collapsed-by-default expanded card (the same unified expand every card row has). A web-declaring tool without a keyed row lands on the `GenericToolCard` fallback, which routes the card through ToolRow the same way, and the details panel renders it at the primitive's full source allowance and, below the card, the flattened model-visible result content — a fetch body is readable only there, since its card carries only the URL and status. Rows cap at `CHAT_WEB_MAX_SOURCES` (8) against the panel's 16, the same summary-versus-reading split the terminal card draws ([decision](../../../.agents/notes/implemented/feature/2026-07-30-web-result-card-frontend.md)).
+A tool call declaring the `web` render intent renders its web retrieval inline, at both conversation render sites, through ui-primitives' `WebBlock`. `contract/web-card-model.ts` is the single derivation from the snapshot's `resultView`, mirroring the terminal card, so the sites cannot disagree about what a web call shows; it yields null — the generic path — for a running call, a non-web result view, a generic result view, a `card` tag this client version does not know, or a web card whose `kind` this client version does not know (a newer host's value, which the wire cannot be trusted to be `search` or `fetch`). The keyed `WebRow` registers one component under both `web_search` and `web_fetch`, discriminating on the tool name only for its icon and title; it composes the shared `ToolRow`, feeding the card as ToolRow's `web` body, so the retrieval is the row's collapsed-by-default expanded card (the same unified expand every card row has). A web-declaring tool without a keyed row lands on the `GenericToolCard` fallback, which routes the card through ToolRow the same way, and the details panel renders it and, below the card, the flattened model-visible result content — a fetch body is readable only there, since its card carries only the URL and status. Both render sites show the same complete source list — the one the tool returned and the model saw — bounded only by the card's own scroll container height, with no row-versus-panel cap ([decision](../../../.agents/notes/implemented/feature/2026-07-30-web-result-card-frontend.md), [source scroll](../../../.agents/notes/implemented/feature/2026-08-03-web-search-source-scroll.md)).

 A `read` call declaring the `read` render intent renders the returned file window inline, at both conversation render sites, through ui-primitives' `ReadBlock` — the line-numbered, syntax-highlighted content the tool projects. `contract/read-card-model.ts` is the single derivation from the snapshot's `resultView`; the read card is result-side only (a call carries no file content until `execute` returns), so a running read shows its summary alone and it yields null — the generic path — for a non-read result view or a `card` tag this client version does not know. The keyed `ReadRow` composes the shared `ToolRow`, feeding the card as ToolRow's `read` body, so it is the row's collapsed-by-default expanded card; the summary stays a path link that opens the file through the host. The render-site fallback and the details panel are read-aware too. Rows cap at `CHAT_READ_MAX_LINES` (8) against the panel's 16 ([decision](../../../.agents/notes/implemented/feature/2026-07-30-web-read-card-frontend.md)).

--- a/packages/client/ui-conversation/README.zh.md
+++ b/packages/client/ui-conversation/README.zh.md
@@ -20,7 +20,7 @@ Think 行默认保持折叠，并在不展开思维链的情况下暴露实时

 声明 `terminal` 渲染意图的工具调用，会在两个对话渲染点上都通过 ui-primitives 的 `TerminalBlock` 内联渲染其命令输出。`contract/terminal-card-model.ts` 是从快照的 `callView`／`resultView` 对推导的唯一位置，因此两个渲染点不可能在命令、cwd 或退出状态上产生分歧；对任何其他 card 标签——包括当前客户端版本不认识的标签——它返回 null，落回通用路径。因此两个渲染点也都显示卡片的运行状态点，它与工具行行首图标承载同一套 `StateDot` 语义，所以一行与其自身的卡片对同一条命令的状态总是一致。多行命令的每一行各占一个提示行，状态点只在第一行为整次调用标记一次——退出状态属于整次调用，因此每行一枚就会声称一个 bash 并不报告的逐行结果。键控的 `BashRow` 把卡片常驻在摘要行下方；由于工具行已不再是详情面板的点击目标，卡片的复制与展开控件就是该行唯一的交互。渲染点兜底行则保持其既有的展开控件。行的上限是 `CHAT_TERMINAL_MAX_LINES`（8），面板为 16，正是这一点让摘要面保持有界——面板仍是单次调用的阅读面。内联输出按渲染意图开放——终端卡片与 web 卡片，各有自己的上限。若 Bash 执行失败时落在通用路径，则改用同样有界的 IN/OUT 展开区暴露原始参数和完整错误；后台启动确认等成功的通用结果仍只显示摘要（[决策](../../../.agents/notes/implemented/feature/2026-07-28-web-terminal-card.md)）。

-声明 `web` 渲染意图的工具调用，会在两个对话渲染点上都通过 ui-primitives 的 `WebBlock` 内联渲染其 web 检索。`contract/web-card-model.ts` 是从快照的 `resultView` 推导的唯一位置，镜像终端卡片，因此两个渲染点不可能对一次 web 调用的显示产生分歧；对运行中的调用、非 web 的 result view、generic result view、本客户端版本不认识的 `card` 标签，或本客户端版本不认识 `kind` 的 web 卡片（更新的 host 发来的值，wire 上不可信其为 `search` 或 `fetch`），它返回 null，落回通用路径。键控的 `WebRow` 把一个组件注册在 `web_search` 与 `web_fetch` 两个键下，仅根据工具名判别以选取图标与标题；它组合共享的 `ToolRow`，把卡片作为 ToolRow 的 `web` body 传入，因此检索成为该行默认折叠的展开卡片（与每个卡片行相同的统一展开交互）。没有自己键控行的 web 声明工具落到 `GenericToolCard` 兜底，它以同样方式经 ToolRow 渲染卡片，详情面板则以原语的完整 source 额度渲染它，并在卡片下方渲染摊平的模型可见结果内容——fetch 正文只在此处可读，因为其卡片只携带 URL 和状态。行的上限是 `CHAT_WEB_MAX_SOURCES`（8），面板为 16，与终端卡片所画的摘要面对阅读面的同一划分（[决策](../../../.agents/notes/implemented/feature/2026-07-30-web-result-card-frontend.md)）。
+声明 `web` 渲染意图的工具调用，会在两个对话渲染点上都通过 ui-primitives 的 `WebBlock` 内联渲染其 web 检索。`contract/web-card-model.ts` 是从快照的 `resultView` 推导的唯一位置，镜像终端卡片，因此两个渲染点不可能对一次 web 调用的显示产生分歧；对运行中的调用、非 web 的 result view、generic result view、本客户端版本不认识的 `card` 标签，或本客户端版本不认识 `kind` 的 web 卡片（更新的 host 发来的值，wire 上不可信其为 `search` 或 `fetch`），它返回 null，落回通用路径。键控的 `WebRow` 把一个组件注册在 `web_search` 与 `web_fetch` 两个键下，仅根据工具名判别以选取图标与标题；它组合共享的 `ToolRow`，把卡片作为 ToolRow 的 `web` body 传入，因此检索成为该行默认折叠的展开卡片（与每个卡片行相同的统一展开交互）。没有自己键控行的 web 声明工具落到 `GenericToolCard` 兜底，它以同样方式经 ToolRow 渲染卡片，详情面板渲染它，并在卡片下方渲染摊平的模型可见结果内容——fetch 正文只在此处可读，因为其卡片只携带 URL 和状态。两个渲染点显示同一份完整来源列表——工具返回、模型看到的那一份——仅受卡片自身滚动容器的高度约束，不存在行与面板的两级上限（[决策](../../../.agents/notes/implemented/feature/2026-07-30-web-result-card-frontend.md)、[来源滚动](../../../.agents/notes/implemented/feature/2026-08-03-web-search-source-scroll.md)）。

 声明 `read` 渲染意图的 `read` 调用，会在两个对话渲染点上都通过 ui-primitives 的 `ReadBlock` 内联渲染返回的文件窗口——工具投影出的带行号、语法高亮的内容。`contract/read-card-model.ts` 是从快照的 `resultView` 推导的唯一位置；read 卡片是仅结果侧的(调用在 `execute` 返回前不携带文件内容)，所以运行中的 read 只显示摘要，且对非 read 的 result view 或本客户端版本不认识的 `card` 标签返回 null，落回通用路径。键控的 `ReadRow` 组合共享的 `ToolRow`，把卡片作为 ToolRow 的 `read` body 传入，因此它是该行默认折叠的展开卡片；摘要仍是一个经 host 打开文件的路径链接。渲染点兜底行与详情面板同样感知 read。行的上限是 `CHAT_READ_MAX_LINES`（8），面板为 16（[决策](../../../.agents/notes/implemented/feature/2026-07-30-web-read-card-frontend.md)）。

--- a/packages/client/ui-conversation/src/client/chat/ToolRow.tsx
+++ b/packages/client/ui-conversation/src/client/chat/ToolRow.tsx
@@ -30,7 +30,6 @@ import type { TranslateNS } from '@deepseek-ai/dsh-client-ui-slots'
 import { CHAT_DIFF_MAX_LINES, type DiffCardModel } from '../contract/diff-card-model.ts'
 import { CHAT_READ_MAX_LINES, type ReadCardModel } from '../contract/read-card-model.ts'
 import { CHAT_SEARCH_MAX_LINES, type SearchCardModel } from '../contract/search-card-model.ts'
-import { CHAT_WEB_MAX_SOURCES } from '../contract/web-card-model.ts'
 import { terminalBlockLabels, type TerminalCardModel } from '../contract/terminal-card-model.ts'
 import type { ToolRowState, ToolRowVariant } from '../contract/tool-call-model.ts'
 import { DisclosureRow } from './DisclosureRow.tsx'
@@ -276,7 +275,7 @@ export function ToolRow({
                    </>
                  )
                  : webBody !== null
-                    ? <WebBlock {...webBody} maxSources={CHAT_WEB_MAX_SOURCES} className={css.webBody} />
+                    ? <WebBlock {...webBody} className={css.webBody} />
                    : isThink
                      ? <div className={css.thinkBody}>{body}</div>
                      : (
--- a/packages/client/ui-conversation/src/client/contract/web-card-model.ts
+++ b/packages/client/ui-conversation/src/client/contract/web-card-model.ts
@@ -15,16 +15,6 @@
 import type { WebBlockProps } from '@deepseek-ai/dsh-client-ui-primitives'
 import type { ToolCallBlock } from './tool-call-model.ts'

-/**
- * Sources the chat row's web body shows before collapsing the middle — half
- * the primitive's own default, which the details panel keeps. A chat row is a
- * summary surface inside the message flow: the flow must stay scannable across
- * many calls, while the details panel is the single-call reading surface. A
- * design constant of this UI's row geometry, not a deployment choice, so it is
- * fixed here rather than a plugin Config field.
- */
-export const CHAT_WEB_MAX_SOURCES = 8
-
 /**
 * Derive the web-card props for a tool call, or null when this call is not a
 * web card and belongs on the generic path.
--- a/packages/client/ui-conversation/src/client/skeleton/DetailsPanel.tsx
+++ b/packages/client/ui-conversation/src/client/skeleton/DetailsPanel.tsx
@@ -180,13 +180,12 @@ function OutputBody({ material, cwd, t }: { material: CallMaterial; cwd: string
    )
  }
  const web = webCardModel(material.block)
-  // Full source-list allowance here (the panel is the single-call reading
-  // surface); the chat rows cap it at CHAT_WEB_MAX_SOURCES. Below the card the
-  // panel also renders the flattened result content — the model-visible text
-  // the card does not carry verbatim (a web_fetch card shows only the URL and
-  // status, so its fetched body lives only here; a search card's answer and
-  // sources are structured, so the flattened form repeats them as the raw text
-  // the model saw).
+  // The card shows every source the tool returned (the same list the model saw),
+  // scrolling within its own capped height. Below the card the panel also renders
+  // the flattened result content — the model-visible text the card does not carry
+  // verbatim (a web_fetch card shows only the URL and status, so its fetched body
+  // lives only here; a search card's answer and sources are structured, so the
+  // flattened form repeats them as the raw text the model saw).
  if (web !== null) {
    const settled = 'kind' in material.block ? material.block : null
    const body = settled === null ? '' : resultText(settled)
--- a/packages/client/ui-conversation/tests/web-card.spec.tsx
+++ b/packages/client/ui-conversation/tests/web-card.spec.tsx
@@ -17,7 +17,7 @@ import type {
 import type { ToolResultView } from '@deepseek-ai/dsh-client-connection/client'
 import { bindSnapshotSelector } from '@deepseek-ai/dsh-client-web-react'
 import type { SelectionTarget, ToolRowOwnerProps } from '@deepseek-ai/dsh-client-ui-conversation/client'
-import { CHAT_WEB_MAX_SOURCES, webCardModel } from '../src/client/contract/web-card-model.ts'
+import { webCardModel } from '../src/client/contract/web-card-model.ts'
 import { createChatStore } from '../src/client/stores.ts'
 import { GenericToolCard } from '../src/client/chat/GenericToolCard.tsx'
 import { DetailsPanel } from '../src/client/skeleton/DetailsPanel.tsx'
@@ -135,8 +135,7 @@ describe('chat row web body', () => {
    fireEvent.click(view.container.querySelector('[data-expandable]')!)
  }

-  it('the WebRow collapses to the summary row, expanding to the search card capped tighter than the panel', () => {
-    expect(CHAT_WEB_MAX_SOURCES).toBeLessThan(16)
+  it('the WebRow collapses to the summary row, expanding to the full search card', () => {
    const view = render(<WebRow {...rowProps(settledSearch(), 'web_search')} />)
    // Collapsed: the summary row alone, no card in the DOM.
    expect(view.getByText('Search')).toBeTruthy()
--- a/packages/client/ui-primitives/README.i18n.yaml
+++ b/packages/client/ui-primitives/README.i18n.yaml
@@ -2,5 +2,5 @@
 # side as of the last confirmed-consistent state. Both languages carry equal authority;
 # after editing either side, bring the other along and re-record with:
 #   pnpm run verify-translation-pairing --write packages/client/ui-primitives/README.md
-README.md: 7318acd9b9a6047b1144789bcd2655132237f6c5
-README.zh.md: e326846dc2099472bc0a81dff093ff24b614559b
+README.md: 00e9560f43c83e1edc61c185a4fc562c6c923e8b
+README.zh.md: 21226ab211106b7722139828762605cb71a4b498
--- a/packages/client/ui-primitives/README.md
+++ b/packages/client/ui-primitives/README.md
@@ -30,7 +30,7 @@ Pure React atoms (zero cordis): StateDot, ic_ds_* icons, Button/Pill/Menu/Modal/

 ## Web retrieval

-`WebBlock` renders a completed web retrieval, one component for both kinds of the `web` render intent (discriminated by `kind`). A `search` shows an optional provider answer (through `MarkdownText`) above an ordered citation list: each source is a safe external link labelled by its title, or its hostname, falling back to the raw URL when the URL does not parse or has no hostname (a `file:`/`data:` URL) so a label is never blank; its snippet and publication date render below it. Only http(s) URLs become anchors (`target`/`rel` set) — the http(s) subset of the allowlist `MarkdownText` applies to untrusted links (it also permits `mailto:`, excluded here); any other URL renders as plain text. A long list caps at `maxSources` (default 16, the TerminalBlock split arithmetic) with a head/tail collapse; the collapsed tail keeps each source's original citation number via `<li value>`, and the expand control is a marker-less `<li>` so the `<ol>` stays valid HTML. When a search legitimately returns no answer and no sources, the card shows an explicit empty-state note rather than a blank `<ol>` (the chat row does not surface the raw result content). A `fetch` shows a compact summary: the linked final URL and its HTTP status. Both mark a capped retrieval. Rationale: [the web result card note](../../../.agents/notes/implemented/feature/2026-07-30-web-result-card-frontend.md).
+`WebBlock` renders a completed web retrieval, one component for both kinds of the `web` render intent (discriminated by `kind`). A `search` shows an optional provider answer (through `MarkdownText`) above an ordered citation list: each source is a safe external link labelled by its title, or its hostname, falling back to the raw URL when the URL does not parse or has no hostname (a `file:`/`data:` URL) so a label is never blank; its snippet and publication date render below it. Only http(s) URLs become anchors (`target`/`rel` set) — the http(s) subset of the allowlist `MarkdownText` applies to untrusted links (it also permits `mailto:`, excluded here); any other URL renders as plain text. The whole list renders in one fixed-height scroll container (`max-height: 320px`, `overflow-y: auto`), so a list taller than that scrolls vertically in place instead of growing the card; `<li value>` pins each source's citation number, contiguous from 1, rather than leaving it to the `<ol>`'s implicit count. When a search legitimately returns no answer and no sources, the card shows an explicit empty-state note rather than a blank `<ol>` (the chat row does not surface the raw result content). A `fetch` shows a compact summary: the linked final URL and its HTTP status. Both mark a capped retrieval. Rationale: [the web result card note](../../../.agents/notes/implemented/feature/2026-07-30-web-result-card-frontend.md) and [the source scroll note](../../../.agents/notes/implemented/feature/2026-08-03-web-search-source-scroll.md).

 ## Model Experience

@@ -45,5 +45,5 @@ None; this package neither assembles nor sends a provider request.
 - **Glyph-level icons are redrawn approximations** — the fish logo (and the sparkle held by ui-conversation) come from font glyphs whose vector geometry is not exportable from the local design data; hand-authored recreations stand in until an exact export path exists.
 - **Pill and Input have no design source** — both atoms are self-defined; the sidebar search field and view-tab strip that resemble them are consumer-owned compositions, not these atoms.
 - **StateDot `Active` variant is a hidden placeholder in the design** — not implemented; the four shipped states (done/warning/ongoing/error) are the complete P-I surface.
- **User-facing copy localizes through label props, defaulting to the original Chinese literals** — the atoms are zero-cordis and cannot reach `ctx.locale`, so `HoverCard` (`copyLabel`/`copiedLabel`), `TerminalBlock` (`labels`), `JsonTree` (`labels`), `CodeBlock` (`copyLabel`/`copiedLabel`), `MarkdownText` (`codeLabels`), `JsonBlock` (`truncatedLabel`), `ConnectionBanner` (`label`), and `Modal` (`closeLabel`) take their copy as optional props with the previous hardcoded strings as defaults. Localized plugins pass dictionary-driven labels from their own `t` seat; a consumer that passes nothing renders exactly the pre-localization output. `WebBlock` does not yet follow this pattern: its source expand/collapse controls, source-list and fetch truncation notes, and empty-search note stay inline Chinese, pending the same label-prop treatment.
+- **User-facing copy localizes through label props, defaulting to the original Chinese literals** — the atoms are zero-cordis and cannot reach `ctx.locale`, so `HoverCard` (`copyLabel`/`copiedLabel`), `TerminalBlock` (`labels`), `JsonTree` (`labels`), `CodeBlock` (`copyLabel`/`copiedLabel`), `MarkdownText` (`codeLabels`), `JsonBlock` (`truncatedLabel`), `ConnectionBanner` (`label`), and `Modal` (`closeLabel`) take their copy as optional props with the previous hardcoded strings as defaults. Localized plugins pass dictionary-driven labels from their own `t` seat; a consumer that passes nothing renders exactly the pre-localization output. `WebBlock` does not yet follow this pattern: its source-list and fetch truncation notes and its empty-search note stay inline Chinese, pending the same label-prop treatment.
 - **`TerminalBlock` is not a terminal emulator** — it renders settled or still-running command output, not an interactive session: SGR color and attributes are honored, and so are the in-line cursor movements a progress line uses — carriage return, backspace, erase-in-line, tab stops and character width. Absolute cursor positioning, screen clearing, and alternate-screen sequences are stripped. Basic-16 magenta and cyan have no token equivalent and stay literal rgb.
--- a/packages/client/ui-primitives/README.zh.md
+++ b/packages/client/ui-primitives/README.zh.md
@@ -30,7 +30,7 @@

 ## Web 检索

-`WebBlock` 渲染一次已完成的 web 检索，用一个组件绘制 `web` 渲染意图的两种 kind（由 `kind` 判别）。`search` 在有序引用列表上方显示可选的 provider answer（通过 `MarkdownText`）：每个 source 是一个安全外链，以其标题为标签，或以其主机名为标签，当 URL 无法解析或没有主机名（`file:`/`data:` URL）时回退到原始 URL，因此标签绝不为空；其下渲染 snippet 与发布日期。只有 http(s) URL 会成为锚点（设置 `target`/`rel`）——这是 `MarkdownText` 对不受信任链接所用 allowlist 的 http(s) 子集（该 allowlist 还允许 `mailto:`，此处排除）；任何其他 URL 渲染为纯文本。长列表在 `maxSources`（默认 16，即 TerminalBlock 的切分算术）处折叠为头部/尾部；折叠的尾部通过 `<li value>` 保留每个 source 原始的引用编号，展开控件是无 marker 的 `<li>`，使 `<ol>` 保持为合法 HTML。当一次 search 合法地返回无 answer 且无 source 时，卡片显示一个明确的空状态提示，而不是空的 `<ol>`（chat 行不呈现原始 result content）。`fetch` 显示一个紧凑摘要：带链接的最终 URL 及其 HTTP 状态。两者都会标记一次被截断的检索。原理：[Web result 卡片笔记](../../../.agents/notes/implemented/feature/2026-07-30-web-result-card-frontend.md)。
+`WebBlock` 渲染一次已完成的 web 检索，用一个组件绘制 `web` 渲染意图的两种 kind（由 `kind` 判别）。`search` 在有序引用列表上方显示可选的 provider answer（通过 `MarkdownText`）：每个 source 是一个安全外链，以其标题为标签，或以其主机名为标签，当 URL 无法解析或没有主机名（`file:`/`data:` URL）时回退到原始 URL，因此标签绝不为空；其下渲染 snippet 与发布日期。只有 http(s) URL 会成为锚点（设置 `target`/`rel`）——这是 `MarkdownText` 对不受信任链接所用 allowlist 的 http(s) 子集（该 allowlist 还允许 `mailto:`，此处排除）；任何其他 URL 渲染为纯文本。整份列表渲染在一个定高滚动容器里（`max-height: 320px`、`overflow-y: auto`），因此超出该高度的列表在原地纵向滚动，而不是把卡片撑高；`<li value>` 固定每个 source 的引用编号，从 1 起连续，而不依赖 `<ol>` 的隐式计数。当一次 search 合法地返回无 answer 且无 source 时，卡片显示一个明确的空状态提示，而不是空的 `<ol>`（chat 行不呈现原始 result content）。`fetch` 显示一个紧凑摘要：带链接的最终 URL 及其 HTTP 状态。两者都会标记一次被截断的检索。原理：[Web result 卡片笔记](../../../.agents/notes/implemented/feature/2026-07-30-web-result-card-frontend.md)与[来源滚动笔记](../../../.agents/notes/implemented/feature/2026-08-03-web-search-source-scroll.md)。

 ## 模型体验

@@ -45,5 +45,5 @@
 - **字形级图标是重新绘制的近似版本**：鱼形标志（以及 ui-conversation 持有的闪光图标）来自字体字形，而本地设计数据无法导出其矢量几何；在获得精确导出路径前，使用手工重建版本代替。
 - **Pill 与 Input 没有设计来源**：两个原子组件均自行定义；与其相似的侧边栏搜索字段和视图标签条由消费方组合，不是这些原子组件。
 - **StateDot 的 `Active` 变体是设计中的隐藏占位符**：尚未实现；已交付的四种状态（done/warning/ongoing/error）构成完整的 P-I 表层。
- **面向用户的文案经 label props 本地化，默认值为原中文字面量**：这些原子组件是 zero-cordis 的，拿不到 `ctx.locale`，因此 `HoverCard`（`copyLabel`/`copiedLabel`）、`TerminalBlock`（`labels`）、`JsonTree`（`labels`）、`CodeBlock`（`copyLabel`/`copiedLabel`）、`MarkdownText`（`codeLabels`）、`JsonBlock`（`truncatedLabel`）、`ConnectionBanner`（`label`）和 `Modal`（`closeLabel`）都把文案作为可选 props 接收，默认值即此前的硬编码字符串。已本地化的插件用自己的 `t` 席位传入字典驱动的 label；什么都不传的消费者渲染与本地化之前逐字节一致。`WebBlock` 尚未跟进这一模式：它的来源展开/收起控件、来源列表与 fetch 截断提示、以及空搜索提示仍是内联中文，待同样的 label-prop 处理。
+- **面向用户的文案经 label props 本地化，默认值为原中文字面量**：这些原子组件是 zero-cordis 的，拿不到 `ctx.locale`，因此 `HoverCard`（`copyLabel`/`copiedLabel`）、`TerminalBlock`（`labels`）、`JsonTree`（`labels`）、`CodeBlock`（`copyLabel`/`copiedLabel`）、`MarkdownText`（`codeLabels`）、`JsonBlock`（`truncatedLabel`）、`ConnectionBanner`（`label`）和 `Modal`（`closeLabel`）都把文案作为可选 props 接收，默认值即此前的硬编码字符串。已本地化的插件用自己的 `t` 席位传入字典驱动的 label；什么都不传的消费者渲染与本地化之前逐字节一致。`WebBlock` 尚未跟进这一模式：它的来源列表与 fetch 截断提示、以及空搜索提示仍是内联中文，待同样的 label-prop 处理。
 - **`TerminalBlock` 不是终端模拟器**：它渲染已结束或仍在运行的命令输出，而不是交互式会话：SGR 颜色与属性会被遵循，进度行所用的行内光标移动同样被遵循——回车、退格、行内擦除、制表位与字符宽度。绝对光标定位、清屏与备用屏幕序列会被剥离。基础 16 色中的洋红与青色没有对应 token，保持字面 rgb。
--- a/packages/client/ui-primitives/src/WebBlock.module.css
+++ b/packages/client/ui-primitives/src/WebBlock.module.css
@@ -1,7 +1,8 @@
 /* Geometry mirrors CodeBlock/TerminalBlock (12px radius, code-block surface,
   16px vertical margin) so a web card, a terminal card, and a fenced code block
-   read as one family. A source list is prose, not aligned output, so it wraps
-   normally rather than scrolling horizontally like a terminal card's output. */
+   read as one family. A source list is prose, not aligned output, so each row
+   wraps horizontally rather than scrolling sideways like a terminal card; the
+   list as a whole scrolls vertically within a capped height (see .sources). */

 .block {
  --dsl-web-radius: 12px;
@@ -27,13 +28,29 @@
  margin-bottom: 0;
 }

-/* The citation list: ordered so each source reads as a numbered reference. */
+/* The citation list: ordered so each source reads as a numbered reference. The
+   whole list — the sources the tool returned, matching what the model saw —
+   renders here; a max-height caps the card so a long list scrolls in place
+   rather than growing the card unbounded. The height is a design constant of the
+   card's geometry, not a deployment choice, so it lives here rather than a plugin
+   config field.
+
+   `overflow-y` makes this a scroll container, which also clips inline-start
+   overflow: a marker wider than `padding-left` loses its leading digits with no
+   way to scroll them back. Markers are right-aligned to the content edge, so the
+   padding must fit the widest one the list can produce. `searchMaxResults` is an
+   unbounded positive integer, so the padding is sized in `em` — against this
+   element's own font, the one a marker inherits — to hold a three-digit marker
+   (`999. ` measures 2.35em in the app font stack) plus the gap the one-digit
+   case already had. */
 .sources {
  margin: 0;
-  padding-left: 20px;
+  padding-left: 2.5em;
  display: flex;
  flex-direction: column;
  gap: 10px;
+  max-height: 320px;
+  overflow-y: auto;
 }

 .source {
@@ -65,26 +82,6 @@
  font: var(--dsw-font-xs-13);
 }

-.expandItem {
-  list-style: none;
-}
-
-.expand {
-  display: block;
-  width: 100%;
-  padding: 0;
-  border: none;
-  background-color: transparent;
-  color: var(--dsw-alias-label-tertiary);
-  cursor: pointer;
-  font: inherit;
-  text-align: left;
-}
-
-.expand:hover {
-  color: var(--dsw-alias-label-secondary);
-}
-
 .truncated {
  margin-top: 8px;
  color: var(--dsw-alias-label-tertiary);
--- a/packages/client/ui-primitives/src/WebBlock.tsx
+++ b/packages/client/ui-primitives/src/WebBlock.tsx
@@ -9,22 +9,20 @@
 // allowlist MarkdownText applies to untrusted assistant-authored links (it also
 // permits mailto, excluded here); an unparseable or non-http URL renders as
 // plain text. Geometry, radius, and fonts mirror CodeBlock/TerminalBlock so a
-// web card reads as one family with them; a long source list caps at maxSources
-// with a head/tail collapse using the same arithmetic as TerminalBlock's output
-// cap.
+// web card reads as one family with them; the whole source list renders inside a
+// fixed-height scroll container (its `.sources` max-height), so a long list
+// scrolls in place rather than growing the card — and that container's
+// `padding-left` must stay wide enough for the widest `<li>` marker, since a
+// scroll container clips inline-start overflow irrecoverably. The card draws every source the
+// view carries: the tool already cut the list to its source cap, and `truncated`
+// reports that cut. A content-only transform downstream of the tool — spill-policy
+// replacing an oversized result's text while leaving its presentationMeta whole —
+// can still narrow what the model reads below this list.

-import { useCallback, useState } from 'react'
 import clsx from 'clsx'
 import { MarkdownText } from './markdown/MarkdownText.tsx'
 import css from './WebBlock.module.css'

-/**
- * Sources shown before the height cap collapses the middle of a citation list.
- * Matches TerminalBlock's default output budget so both cards cut a long body
- * at the same place; the chat row narrows it through the maxSources prop.
- */
-export const DEFAULT_WEB_MAX_SOURCES = 16
-
 /**
 * One citeable source drawn in a search card: the projection of the contract's
 * `WebSource`, with the optional fields kept optional so a provider that
@@ -50,8 +48,6 @@ export interface WebSearchBlockProps {
  sources: WebSourceView[]
  /** True when the tool cut the source list to its result cap. */
  truncated: boolean
-  /** Sources shown before the middle collapses (default {@link DEFAULT_WEB_MAX_SOURCES}). */
-  maxSources?: number | undefined
  /** Extra class merged onto the wrapper (callers position; this component draws). */
  className?: string | undefined
 }
@@ -65,13 +61,6 @@ export interface WebFetchBlockProps {
  statusCode: number
  /** True when the provider or the output cap cut the fetched content. */
  truncated: boolean
-  /**
-   * Accepted and ignored, so both card kinds take one uniform prop set (a fetch
-   * card has no source list to cap) — the same way TerminalBlock accepts one
-   * `maxLines` across its arms. Lets a render site spread `maxSources` onto
-   * either kind without a per-kind conditional.
-   */
-  maxSources?: number | undefined
  /** Extra class merged onto the wrapper (callers position; this component draws). */
  className?: string | undefined
 }
@@ -137,9 +126,9 @@ function SafeLink({ url, label, className }: { url: string; label: string; class

 /**
 * One source row in a search card: the safe link plus its snippet and date. The
- * `<li value>` pins the source's original 1-based position, so a collapsed list
- * whose tail is drawn after the head still numbers each source by its real
- * citation index rather than by its position in the visible subset.
+ * `<li value>` pins the source's 1-based citation index explicitly rather than
+ * relying on the `<ol>`'s implicit numbering, so a row reads by its real index
+ * even inside the scroll container.
 * @param props.source - the source to render.
 * @param props.ordinal - the source's 1-based position in the full list.
 * @returns the source list item.
@@ -159,21 +148,12 @@ function SourceItem({ source, ordinal }: { source: WebSourceView; ordinal: numbe
 }

 /**
- * The search card body: the answer over the capped source list.
+ * The search card body: the answer over the full source list, which scrolls in
+ * place once it exceeds the `.sources` container height.
 * @param props - see {@link WebSearchBlockProps}.
 * @returns the search card element.
 */
-function WebSearchBlock({ answer, sources, truncated, maxSources = DEFAULT_WEB_MAX_SOURCES, className }: WebSearchBlockProps) {
-  const [expanded, setExpanded] = useState(false)
-  const onToggle = useCallback(() => { setExpanded(value => !value) }, [])
-  const hidden = sources.length - maxSources
-  const capped = hidden > 0 && !expanded
-  // Same split arithmetic as TerminalBlock's output cap, so a long body's head
-  // and tail slices agree between the two cards.
-  const headCount = Math.ceil(maxSources / 2)
-  const tailCount = maxSources - headCount
-  const head = capped ? sources.slice(0, headCount) : sources
-  const tail = capped ? sources.slice(sources.length - tailCount) : []
+function WebSearchBlock({ answer, sources, truncated, className }: WebSearchBlockProps) {
  // A provider may legitimately return no answer and no sources; the chat WebRow
  // does not show the raw result content, so without this the user would see an
  // empty card. Mirror the backend's `No results found.` render text.
@@ -187,27 +167,7 @@ function WebSearchBlock({ answer, sources, truncated, maxSources = DEFAULT_WEB_M
        <div className={css.empty}>未找到结果</div>
      ) : (
        <ol className={css.sources}>
-          {head.map((source, index) => <SourceItem key={index} source={source} ordinal={index + 1} />)}
-          {hidden > 0 && (
-            <li className={css.expandItem}>
-              <button
-                type="button"
-                className={css.expand}
-                aria-expanded={expanded}
-                aria-label={expanded ? '收起来源' : `展开其余 ${hidden} 条来源`}
-                onClick={onToggle}
-              >
-                {expanded ? '收起' : `… 其余 ${hidden} 条来源`}
-              </button>
-            </li>
-          )}
-          {tail.map((source, index) => (
-            <SourceItem
-              key={sources.length - tailCount + index}
-              source={source}
-              ordinal={sources.length - tailCount + index + 1}
-            />
-          ))}
+          {sources.map((source, index) => <SourceItem key={index} source={source} ordinal={index + 1} />)}
        </ol>
      )}
      {truncated && <div className={css.truncated}>来源列表已截断</div>}
--- a/packages/client/ui-primitives/src/index.ts
+++ b/packages/client/ui-primitives/src/index.ts
@@ -32,7 +32,7 @@ export { SearchBlock, DEFAULT_SEARCH_MAX_LINES } from './SearchBlock.tsx'
 export type {
  SearchBlockProps, SearchMatchesBlockProps, SearchPathsBlockProps, SearchFileGroup, SearchBlockLineMatch,
 } from './SearchBlock.tsx'
-export { WebBlock, DEFAULT_WEB_MAX_SOURCES } from './WebBlock.tsx'
+export { WebBlock } from './WebBlock.tsx'
 export type { WebBlockProps, WebSearchBlockProps, WebFetchBlockProps, WebSourceView } from './WebBlock.tsx'
 export { CodeBlock } from './markdown/CodeBlock.tsx'
 export type { CodeBlockProps } from './markdown/CodeBlock.tsx'
--- a/packages/client/ui-primitives/tests/web-block.spec.tsx
+++ b/packages/client/ui-primitives/tests/web-block.spec.tsx
@@ -1,19 +1,19 @@
 // @vitest-environment jsdom
 // WebBlock: both kinds of the web card. The search card's answer, its citation
 // list with the title-or-hostname label fallback and optional snippet/date, the
-// source-list height cap and its expand control, and the truncated indicator;
-// the fetch card's linked URL, status, and truncation. Safe-link attributes on
-// both kinds: an http(s) URL becomes an external anchor (target/rel), any other
-// URL renders as plain text with no href.
+// full source list under one <ol>, and the truncated indicator; the fetch
+// card's linked URL, status, and truncation. Safe-link
+// attributes on both kinds: an http(s) URL becomes an external anchor
+// (target/rel), any other URL renders as plain text with no href.

 import { afterEach, describe, expect, it } from 'vitest'
-import { cleanup, fireEvent, render } from '@testing-library/react'
-import { DEFAULT_WEB_MAX_SOURCES, WebBlock } from '../src/index.ts'
+import { cleanup, render } from '@testing-library/react'
+import { WebBlock } from '../src/index.ts'
 import type { WebSourceView } from '../src/index.ts'

 afterEach(cleanup)

-/** `count` sources with sequential hostnames, so the cap slices read distinctly. */
+/** `count` sources with sequential hostnames, so each row reads distinctly. */
 function sources(count: number): WebSourceView[] {
  return Array.from({ length: count }, (_value, index) => ({
    url: `https://site-${index}.example.com/page`,
@@ -123,58 +123,25 @@ describe('WebBlock search card', () => {
    expect(off.queryByText('来源列表已截断')).toBeNull()
  })

-  it('renders every source and no expand control under the cap', () => {
-    const view = render(<WebBlock kind="search" sources={sources(4)} truncated={false} maxSources={4} />)
-    expect(view.container.querySelectorAll('[class^="_source_"]')).toHaveLength(4)
+  it('renders every source in one <ol> with no expand control', () => {
+    // The card shows the whole list the tool returned, with no head/tail
+    // collapse and no expand button. jsdom does not resolve the CSS Modules
+    // layout, so the scroll geometry the `.sources` max-height produces is
+    // pinned by the assembled browser case in apps/web/tests/web-search-round.e2e.ts,
+    // not here.
+    const view = render(<WebBlock kind="search" sources={sources(30)} truncated={false} />)
+    expect(view.container.querySelectorAll('li[class^="_source_"]')).toHaveLength(30)
    expect(view.container.querySelector('[aria-expanded]')).toBeNull()
-  })
-
-  it('slices head and tail over the cap and expands on click', () => {
-    const view = render(<WebBlock kind="search" sources={sources(10)} truncated={false} maxSources={4} />)
-    // maxSources 4: head = ceil(4/2) = 2, tail = 4 - 2 = 2, 6 hidden.
-    expect([...view.container.querySelectorAll('[class^="_sourceLink_"]')].map(n => n.textContent))
-      .toEqual(['Source 0', 'Source 1', 'Source 8', 'Source 9'])
-    const toggle = view.getByRole('button', { name: '展开其余 6 条来源' })
-    expect(toggle.getAttribute('aria-expanded')).toBe('false')
-    expect(toggle.textContent).toBe('… 其余 6 条来源')
-
-    fireEvent.click(toggle)
-    expect(view.container.querySelectorAll('[class^="_source_"]')).toHaveLength(10)
-    const collapse = view.getByRole('button', { name: '收起来源' })
-    expect(collapse.getAttribute('aria-expanded')).toBe('true')
-    expect(collapse.textContent).toBe('收起')
-
-    fireEvent.click(collapse)
-    expect(view.container.querySelectorAll('[class^="_source_"]')).toHaveLength(4)
-  })
-
-  it('numbers a collapsed tail by each source original position, not its visible slot', () => {
-    // maxSources 4 over 10 sources: the tail is sources 8 and 9, which must read
-    // as citations 9 and 10 (via <li value>), not renumbered 3 and 4.
-    const view = render(<WebBlock kind="search" sources={sources(10)} truncated={false} maxSources={4} />)
-    const items = [...view.container.querySelectorAll('li[class^="_source_"]')]
-    expect(items.map(li => li.getAttribute('value'))).toEqual(['1', '2', '9', '10'])
-  })
-
-  it('keeps the expander out of the ordered-list numbering', () => {
-    // The expander is a marker-less <li>, so it is valid inside <ol> and does not
-    // consume a citation number between the head and tail sources.
-    const view = render(<WebBlock kind="search" sources={sources(10)} truncated={false} maxSources={4} />)
+    expect(view.container.querySelector('button')).toBeNull()
+    // Every direct child of the <ol> is a source <li> (no marker-less expander).
    const ol = view.container.querySelector('ol')!
-    // Every direct child is an <li> (no bare <button> child — invalid HTML).
    expect([...ol.children].every(child => child.tagName === 'LI')).toBe(true)
  })

-  it('renders the head slice alone when the cap leaves no tail', () => {
-    const view = render(<WebBlock kind="search" sources={sources(5)} truncated={false} maxSources={1} />)
-    expect([...view.container.querySelectorAll('[class^="_sourceLink_"]')].map(n => n.textContent)).toEqual(['Source 0'])
-    expect(view.getByRole('button', { name: '展开其余 4 条来源' })).toBeTruthy()
-  })
-
-  it('caps at the documented default when maxSources is absent', () => {
-    const view = render(<WebBlock kind="search" sources={sources(DEFAULT_WEB_MAX_SOURCES + 1)} truncated={false} />)
-    expect(view.container.querySelectorAll('[class^="_source_"]')).toHaveLength(DEFAULT_WEB_MAX_SOURCES)
-    expect(view.getByRole('button', { name: '展开其余 1 条来源' })).toBeTruthy()
+  it('numbers every source by its 1-based citation index via <li value>', () => {
+    const view = render(<WebBlock kind="search" sources={sources(4)} truncated={false} />)
+    const items = [...view.container.querySelectorAll('li[class^="_source_"]')]
+    expect(items.map(li => li.getAttribute('value'))).toEqual(['1', '2', '3', '4'])
  })
 })