社区导读

简体中文

English

简体中文

English

外观

源文件索引：packages/client（第 7/11 部分） ​

本页由 study-tools/generate-source-index.mjs 根据官方提交 aa6c361a972c8369148dea7380bb5c21c24e07ec 生成，共 923 个代码或界面源文件。每个标题对应一个真实路径；用途和拆分原因是面向初学者的结构化解释，自动索引不等于人工精读。

本页是 packages-client.md 总览的第 7 部分，覆盖：packages/client/ui-primitives（92 条）、packages/client/ui-reference（6 条）。

图例 ​

本页所有条目共用以下说明：

  • 自动索引只提供定位线索，复杂行为需要回到源码和测试确认。
  • 条目中的行数、声明、结构线索和静态 import 数字是文件级定位证据，用来约束“为什么这样设计”的解释范围；它们用于定位，不替代人工源码阅读。
  • 源码链接固定到官方提交；如果当前条目与运行版本不同，应先重新生成索引再下结论。

条目按所属包分组：packages/client/connection（28 条）、packages/client/hmr（6 条）、packages/client/locale（20 条）、packages/client/modules（8 条）、packages/client/runtime（70 条）、packages/client/tsdown.client.ts（1 条）、packages/client/ui-agent-preset（25 条）、packages/client/ui-attachment（24 条）、packages/client/ui-brand-official（7 条）、packages/client/ui-commands（17 条）、packages/client/ui-conversation（124 条）、packages/client/ui-deliverables（11 条）、packages/client/ui-directory-picker-browse（10 条）、packages/client/ui-directory-picker-native（6 条）、packages/client/ui-goal（15 条）、packages/client/ui-input-trigger（21 条）、packages/client/ui-jobs（10 条）、packages/client/ui-layout（17 条）、packages/client/ui-message-feedback（14 条）、packages/client/ui-model-selection（13 条）、packages/client/ui-permission-presets（13 条）、packages/client/ui-plan（10 条）、packages/client/ui-primitives（92 条）、packages/client/ui-reference（6 条）、packages/client/ui-renderer（19 条）、packages/client/ui-settings-general（23 条）、packages/client/ui-settings-models（35 条）、packages/client/ui-settings-plugin-inventory（11 条）、packages/client/ui-settings-plugins（27 条）、packages/client/ui-settings（14 条）、packages/client/ui-sidebar（16 条）、packages/client/ui-skill（10 条）、packages/client/ui-slots（9 条）、packages/client/ui-subagent（12 条）、packages/client/ui-theme（26 条）、packages/client/ui-tool（46 条）、packages/client/ui-trajectory（45 条）、packages/client/ui-user-questions（15 条）、packages/client/ui-workflow-run（10 条）、packages/client/ui-workspace（23 条）、packages/client/web（14 条）。

packages/client/ui-primitives ​

packages/client/ui-primitives/src/BrandWordmark.tsx ​

  • 所属层：packages/client：可复用的 Harness 功能包
  • 文件角色：界面组件或界面逻辑
  • 这个文件有什么用：它实现名为 BrandWordmark 的界面组件或交互逻辑，并导出 BrandWordmarkProps、BrandWordmark，把输入、局部状态和用户操作组织成可渲染的 UI 单元；源码顶部还说明：DeepSeek Harness brand wordmark (figma 356:14644, exact extract): whale + "deepseek-official" letterforms + HARNESS badge plate in one svg. Native 182x24. Ink rides currentColor; the badge text is knocked out in the inverted label color so the plate stays l...。
  • 为什么这样设计：固定提交的文件顶部注释把它定位为“DeepSeek Harness brand wordmark (figma 356:14644, exact extract): whale + "deepseek-official" letterforms + HARNESS badge plate in one svg. Native 182x24. Ink rides currentColor; the badge text is knocked out in the inverted label color so the plate stays l...”；把这项职责单独放置，可以让边界、输入和失败处理在一个地方被阅读和测试。
  • 文件级设计证据：源码顶部注释把它定位为“DeepSeek Harness brand wordmark (figma 356:14644, exact extract): whale + "deepseek-official" letterforms + HARNESS badge plate in one svg. Native 182x24. Ink rides currentColor; the badge text is knocked out in the inverted label color so the plate stays l...”；固定提交中扫描到的声明包括 BrandWordmarkProps、BrandWordmark；本地静态 import 图显示它直接依赖 1 个源文件，并被 1 个源文件直接引用。
  • 直接协作者：packages/client/ui-primitives/README.md、packages/client/ui-primitives/src/icons/props.ts、packages/client/ui-primitives/src/index.ts
  • 对应测试：间接测试线索（通过本地 import 链，非直接覆盖）：packages/client/locale/tests/apply.client.spec.ts、packages/client/locale/tests/document-language.client.spec.ts、packages/client/locale/tests/invariant.client.spec.ts、packages/client/locale/tests/language-row.client.spec.tsx、packages/client/locale/tests/locale.client.spec.ts、packages/client/ui-agent-preset/tests/apply.client.spec.ts
  • 测试关联依据：固定提交源码中的本地静态 import 传递引用；这些测试通过包入口或中间模块到达本文件，不等于本文件被直接覆盖。
  • 阅读顺序：先读客户端运行时契约或呈现模型，再读当前界面文件，沿着 packages/client/ui-primitives/src/index.ts 确认状态如何进入 UI，最后对照 packages/client/locale/tests/apply.client.spec.ts、packages/client/locale/tests/document-language.client.spec.ts、packages/client/locale/tests/invariant.client.spec.ts。
  • 代码证据：固定提交归档实际读取结果：约 64 行；扫描到的声明包括 BrandWordmarkProps、BrandWordmark；源码顶部原注释（英文，仅作回查线索）：DeepSeek Harness brand wordmark (figma 356:14644, exact extract): whale + "deepseek-official" letterforms + HARNESS badge plate in one svg. Native 182x24. Ink rides currentColor; the badge text is knocked out in the inverted label color so the plate stays l...。
  • 固定版本：源码链接固定到官方提交 aa6c361a972c8369148dea7380bb5c21c24e07ec。

packages/client/ui-primitives/src/Button.module.css ​

  • 所属层：packages/client：可复用的 Harness 功能包
  • 文件角色：界面样式
  • 这个文件有什么用：它定义 Button 的网页外观、布局和状态样式，让界面逻辑与视觉规则可以分别修改。
  • 为什么这样设计：把 Button 的样式与业务流程分开，浏览器端可以调整外观而不改变服务端或 agent 的行为；组件只通过 class 和状态选择器使用它。
  • 文件级设计证据：源码顶部注释把它定位为“Capsule geometry from the figma Button component (1:155 instances: h36, pad 14/7, gap 4, r18; the wide New Session form is r24 at h38 — owners with the wide form set their own radius/width).”；固定提交中扫描到的结构线索是：样式结构包含选择器 .button、.md、.sm、.primary、.ghost、.outline；本地静态 import 图显示它直接依赖 0 个源文件，并被 1 个源文件直接引用。
  • 直接协作者：packages/client/ui-primitives/README.md、packages/client/ui-primitives/src/Button.tsx
  • 对应测试：间接测试线索（通过本地 import 链，非直接覆盖）：packages/client/locale/tests/apply.client.spec.ts、packages/client/locale/tests/language-row.client.spec.tsx、packages/client/ui-agent-preset/tests/apply.client.spec.ts、packages/client/ui-agent-preset/tests/components.client.spec.tsx、packages/client/ui-agent-preset/tests/section.client.spec.tsx、packages/client/ui-attachment/tests/attachment-rail.client.spec.tsx
  • 测试关联依据：固定提交源码中的本地静态 import 传递引用；这些测试通过包入口或中间模块到达本文件，不等于本文件被直接覆盖。
  • 阅读顺序：先读客户端运行时契约或呈现模型，再读当前界面文件，沿着 packages/client/ui-primitives/src/Button.tsx 确认状态如何进入 UI，最后对照 packages/client/locale/tests/apply.client.spec.ts、packages/client/locale/tests/language-row.client.spec.tsx、packages/client/ui-agent-preset/tests/apply.client.spec.ts。
  • 代码证据：固定提交归档实际读取结果：约 79 行；样式结构包含选择器 .button、.md、.sm、.primary、.ghost、.outline；源码顶部原注释（英文，仅作回查线索）：Capsule geometry from the figma Button component (1:155 instances: h36, pad 14/7, gap 4, r18; the wide New Session form is r24 at h38 — owners with the wide form set their own radius/width).。
  • 固定版本：源码链接固定到官方提交 aa6c361a972c8369148dea7380bb5c21c24e07ec。

packages/client/ui-primitives/src/Button.tsx ​

  • 所属层：packages/client：可复用的 Harness 功能包
  • 文件角色：界面组件或界面逻辑
  • 这个文件有什么用：它实现名为 Button 的界面组件或交互逻辑，并导出 ButtonVariant、Button，把输入、局部状态和用户操作组织成可渲染的 UI 单元；源码顶部还说明：Button: token-styled button atom. Variants map to the --dsw-alias-button-* fill families; no framework imports, all behavior via props.。
  • 为什么这样设计：固定提交的文件顶部注释把它定位为“Button: token-styled button atom. Variants map to the --dsw-alias-button-* fill families; no framework imports, all behavior via props.”；把这项职责单独放置，可以让边界、输入和失败处理在一个地方被阅读和测试。
  • 文件级设计证据：源码顶部注释把它定位为“Button: token-styled button atom. Variants map to the --dsw-alias-button-* fill families; no framework imports, all behavior via props.”；固定提交中扫描到的声明包括 ButtonVariant、Button；本地静态 import 图显示它直接依赖 1 个源文件，并被 2 个源文件直接引用。
  • 直接协作者：packages/client/ui-primitives/README.md、packages/client/ui-primitives/src/Button.module.css、packages/client/ui-primitives/src/RiskConfirmation.tsx、packages/client/ui-primitives/src/index.ts
  • 对应测试：间接测试线索（通过本地 import 链，非直接覆盖）：packages/client/locale/tests/apply.client.spec.ts、packages/client/locale/tests/document-language.client.spec.ts、packages/client/locale/tests/invariant.client.spec.ts、packages/client/locale/tests/language-row.client.spec.tsx、packages/client/locale/tests/locale.client.spec.ts、packages/client/ui-agent-preset/tests/apply.client.spec.ts
  • 测试关联依据：固定提交源码中的本地静态 import 传递引用；这些测试通过包入口或中间模块到达本文件，不等于本文件被直接覆盖。
  • 阅读顺序：先读客户端运行时契约或呈现模型，再读当前界面文件，沿着 packages/client/ui-primitives/src/RiskConfirmation.tsx、packages/client/ui-primitives/src/index.ts 确认状态如何进入 UI，最后对照 packages/client/locale/tests/apply.client.spec.ts、packages/client/locale/tests/document-language.client.spec.ts、packages/client/locale/tests/invariant.client.spec.ts。
  • 代码证据：固定提交归档实际读取结果：约 31 行；扫描到的声明包括 ButtonVariant、Button；源码顶部原注释（英文，仅作回查线索）：Button: token-styled button atom. Variants map to the --dsw-alias-button-* fill families; no framework imports, all behavior via props.。
  • 固定版本：源码链接固定到官方提交 aa6c361a972c8369148dea7380bb5c21c24e07ec。

packages/client/ui-primitives/src/ConnectionBanner.module.css ​

packages/client/ui-primitives/src/ConnectionBanner.tsx ​

  • 所属层：packages/client：可复用的 Harness 功能包
  • 文件角色：界面组件或界面逻辑
  • 这个文件有什么用：它实现名为 ConnectionBanner 的界面组件或交互逻辑，并导出 ConnectionBanner，把输入、局部状态和用户操作组织成可渲染的 UI 单元；源码顶部还说明：ConnectionBanner: top strip surfacing connection loss. The atom is pure: the owner subscribes to connection state and passes reconnecting down. A null/connecting state upstream should stay quiet too — only an actual outage (reconnect backoff in progress) sh...。
  • 为什么这样设计：固定提交的文件顶部注释把它定位为“ConnectionBanner: top strip surfacing connection loss. The atom is pure: the owner subscribes to connection state and passes reconnecting down. A null/connecting state upstream should stay quiet too — only an actual outage (reconnect backoff in progress) sh...”；把这项职责单独放置，可以让边界、输入和失败处理在一个地方被阅读和测试。
  • 文件级设计证据：源码顶部注释把它定位为“ConnectionBanner: top strip surfacing connection loss. The atom is pure: the owner subscribes to connection state and passes reconnecting down. A null/connecting state upstream should stay quiet too — only an actual outage (reconnect backoff in progress) sh...”；固定提交中扫描到的声明包括 ConnectionBanner；本地静态 import 图显示它直接依赖 1 个源文件，并被 1 个源文件直接引用。
  • 直接协作者：packages/client/ui-primitives/README.md、packages/client/ui-primitives/src/ConnectionBanner.module.css、packages/client/ui-primitives/src/index.ts
  • 对应测试：间接测试线索（通过本地 import 链，非直接覆盖）：packages/client/locale/tests/apply.client.spec.ts、packages/client/locale/tests/document-language.client.spec.ts、packages/client/locale/tests/invariant.client.spec.ts、packages/client/locale/tests/language-row.client.spec.tsx、packages/client/locale/tests/locale.client.spec.ts、packages/client/ui-agent-preset/tests/apply.client.spec.ts
  • 测试关联依据：固定提交源码中的本地静态 import 传递引用；这些测试通过包入口或中间模块到达本文件，不等于本文件被直接覆盖。
  • 阅读顺序：先读客户端运行时契约或呈现模型，再读当前界面文件，沿着 packages/client/ui-primitives/src/index.ts 确认状态如何进入 UI，最后对照 packages/client/locale/tests/apply.client.spec.ts、packages/client/locale/tests/document-language.client.spec.ts、packages/client/locale/tests/invariant.client.spec.ts。
  • 代码证据：固定提交归档实际读取结果：约 21 行；扫描到的声明包括 ConnectionBanner；源码顶部原注释（英文，仅作回查线索）：ConnectionBanner: top strip surfacing connection loss. The atom is pure: the owner subscribes to connection state and passes reconnecting down. A null/connecting state upstream should stay quiet too — only an actual outage (reconnect backoff in progress) sh...。
  • 固定版本：源码链接固定到官方提交 aa6c361a972c8369148dea7380bb5c21c24e07ec。

packages/client/ui-primitives/src/DiffBlock.module.css ​

  • 所属层：packages/client：可复用的 Harness 功能包
  • 文件角色：界面样式
  • 这个文件有什么用：它定义 DiffBlock 的网页外观、布局和状态样式，让界面逻辑与视觉规则可以分别修改。
  • 为什么这样设计：把 DiffBlock 的样式与业务流程分开，浏览器端可以调整外观而不改变服务端或 agent 的行为；组件只通过 class 和状态选择器使用它。
  • 文件级设计证据：源码顶部注释把它定位为“Geometry mirrors CodeBlock/TerminalBlock (12px radius, code-block surface + banner row, markdown code-block font) so a diff card reads as one family with a fenced block and a terminal card. The deliberate divergence, shared with TerminalBlock: the body keep...”；固定提交中扫描到的结构线索是：样式结构包含选择器 .block、.copyButton、.body、.line、.path、.gap；自定义属性 --dsl-diff-radius、--dsl-diff-line-height；本地静态 import 图显示它直接依赖 0 个源文件，并被 1 个源文件直接引用。
  • 直接协作者：packages/client/ui-primitives/README.md、packages/client/ui-primitives/src/DiffBlock.tsx
  • 对应测试：间接测试线索（通过本地 import 链，非直接覆盖）：packages/client/locale/tests/apply.client.spec.ts、packages/client/locale/tests/language-row.client.spec.tsx、packages/client/ui-agent-preset/tests/apply.client.spec.ts、packages/client/ui-agent-preset/tests/components.client.spec.tsx、packages/client/ui-agent-preset/tests/section.client.spec.tsx、packages/client/ui-attachment/tests/attachment-rail.client.spec.tsx
  • 测试关联依据：固定提交源码中的本地静态 import 传递引用；这些测试通过包入口或中间模块到达本文件，不等于本文件被直接覆盖。
  • 阅读顺序：先读客户端运行时契约或呈现模型，再读当前界面文件，沿着 packages/client/ui-primitives/src/DiffBlock.tsx 确认状态如何进入 UI，最后对照 packages/client/locale/tests/apply.client.spec.ts、packages/client/locale/tests/language-row.client.spec.tsx、packages/client/ui-agent-preset/tests/apply.client.spec.ts。
  • 代码证据：固定提交归档实际读取结果：约 107 行；样式结构包含选择器 .block、.copyButton、.body、.line、.path、.gap；自定义属性 --dsl-diff-radius、--dsl-diff-line-height；源码顶部原注释（英文，仅作回查线索）：Geometry mirrors CodeBlock/TerminalBlock (12px radius, code-block surface + banner row, markdown code-block font) so a diff card reads as one family with a fenced block and a terminal card. The deliberate divergence, shared with TerminalBlock: the body keep...。
  • 固定版本：源码链接固定到官方提交 aa6c361a972c8369148dea7380bb5c21c24e07ec。

packages/client/ui-primitives/src/DiffBlock.tsx ​

  • 所属层：packages/client：可复用的 Harness 功能包
  • 文件角色：界面组件或界面逻辑
  • 这个文件有什么用：它实现名为 DiffBlock 的界面组件或交互逻辑，并导出 DEFAULT_DIFF_MAX_LINES、DiffHunk、DiffBlockProps，把输入、局部状态和用户操作组织成可渲染的 UI 单元；源码顶部还说明：DiffBlock: the inline-diff surface for a file mutation (write/edit) — a copy control over one or more per-file hunks, each a bold path header followed by the removed block (-, error color) and the added block (+, success color), with a dim └ +A -R · N file(...。
  • 为什么这样设计：固定提交的文件顶部注释把它定位为“DiffBlock: the inline-diff surface for a file mutation (write/edit) — a copy control over one or more per-file hunks, each a bold path header followed by the removed block (-, error color) and the added block (+, success color), with a dim └ +A -R · N file(...”；把这项职责单独放置，可以让边界、输入和失败处理在一个地方被阅读和测试。
  • 文件级设计证据：源码顶部注释把它定位为“DiffBlock: the inline-diff surface for a file mutation (write/edit) — a copy control over one or more per-file hunks, each a bold path header followed by the removed block (-, error color) and the added block (+, success color), with a dim └ +A -R · N file(...”；固定提交中扫描到的声明包括 DEFAULT_DIFF_MAX_LINES、DiffHunk、DiffBlockProps、DiffBlock、assertNever；本地静态 import 图显示它直接依赖 2 个源文件，并被 1 个源文件直接引用。
  • 直接协作者：packages/client/ui-primitives/README.md、packages/client/ui-primitives/src/DiffBlock.module.css、packages/client/ui-primitives/src/clipboard.ts、packages/client/ui-primitives/src/index.ts
  • 对应测试：间接测试线索（通过本地 import 链，非直接覆盖）：packages/client/locale/tests/apply.client.spec.ts、packages/client/locale/tests/document-language.client.spec.ts、packages/client/locale/tests/invariant.client.spec.ts、packages/client/locale/tests/language-row.client.spec.tsx、packages/client/locale/tests/locale.client.spec.ts、packages/client/ui-agent-preset/tests/apply.client.spec.ts
  • 测试关联依据：固定提交源码中的本地静态 import 传递引用；这些测试通过包入口或中间模块到达本文件，不等于本文件被直接覆盖。
  • 阅读顺序：先读客户端运行时契约或呈现模型，再读当前界面文件，沿着 packages/client/ui-primitives/src/index.ts 确认状态如何进入 UI，最后对照 packages/client/locale/tests/apply.client.spec.ts、packages/client/locale/tests/document-language.client.spec.ts、packages/client/locale/tests/invariant.client.spec.ts。
  • 代码证据：固定提交归档实际读取结果：约 195 行；扫描到的声明包括 DEFAULT_DIFF_MAX_LINES、DiffHunk、DiffBlockProps、DiffBlock、assertNever、buildRows、contentLines、copyText；源码顶部原注释（英文，仅作回查线索）：DiffBlock: the inline-diff surface for a file mutation (write/edit) — a copy control over one or more per-file hunks, each a bold path header followed by the removed block (-, error color) and the added block (+, success color), with a dim └ +A -R · N file(...。
  • 固定版本：源码链接固定到官方提交 aa6c361a972c8369148dea7380bb5c21c24e07ec。

packages/client/ui-primitives/src/DisclosureRow.module.css ​

  • 所属层：packages/client：可复用的 Harness 功能包
  • 文件角色：界面样式
  • 这个文件有什么用：它定义 DisclosureRow 的网页外观、布局和状态样式，让界面逻辑与视觉规则可以分别修改。
  • 为什么这样设计：把 DisclosureRow 的样式与业务流程分开，浏览器端可以调整外观而不改变服务端或 agent 的行为；组件只通过 class 和状态选择器使用它。
  • 文件级设计证据：源码顶部注释把它定位为“Shared disclosure header: 16px leading gap 6 title 14/24.”；固定提交中扫描到的结构线索是：样式结构包含选择器 .root、.row、.leading、.iconIdle、.chevronHover、.title；本地静态 import 图显示它直接依赖 0 个源文件，并被 1 个源文件直接引用。
  • 直接协作者：packages/client/ui-primitives/README.md、packages/client/ui-primitives/src/DisclosureRow.tsx
  • 对应测试：间接测试线索（通过本地 import 链，非直接覆盖）：packages/client/locale/tests/apply.client.spec.ts、packages/client/locale/tests/language-row.client.spec.tsx、packages/client/ui-agent-preset/tests/apply.client.spec.ts、packages/client/ui-agent-preset/tests/components.client.spec.tsx、packages/client/ui-agent-preset/tests/section.client.spec.tsx、packages/client/ui-attachment/tests/attachment-rail.client.spec.tsx
  • 测试关联依据：固定提交源码中的本地静态 import 传递引用；这些测试通过包入口或中间模块到达本文件，不等于本文件被直接覆盖。
  • 阅读顺序：先读客户端运行时契约或呈现模型，再读当前界面文件，沿着 packages/client/ui-primitives/src/DisclosureRow.tsx 确认状态如何进入 UI，最后对照 packages/client/locale/tests/apply.client.spec.ts、packages/client/locale/tests/language-row.client.spec.tsx、packages/client/ui-agent-preset/tests/apply.client.spec.ts。
  • 代码证据：固定提交归档实际读取结果：约 69 行；样式结构包含选择器 .root、.row、.leading、.iconIdle、.chevronHover、.title；源码顶部原注释（英文，仅作回查线索）：Shared disclosure header: 16px leading gap 6 title 14/24.。
  • 固定版本：源码链接固定到官方提交 aa6c361a972c8369148dea7380bb5c21c24e07ec。

packages/client/ui-primitives/src/DisclosureRow.tsx ​

packages/client/ui-primitives/src/FishLogo.tsx ​

  • 所属层：packages/client：可复用的 Harness 功能包
  • 文件角色：界面组件或界面逻辑
  • 这个文件有什么用：它实现名为 FishLogo 的界面组件或交互逻辑，并导出 FishLogo，把输入、局部状态和用户操作组织成可渲染的 UI 单元；源码顶部还说明：DeepSeek fish logo (figma I39:24057;88:8943 fillGeometry, exact extract; the full-canvas rectangle path from the raw dump is a background plate and is intentionally dropped). Native 23.16x17.04, rendered 24x18 by default; hero usage scales to 34x25. Color r...。
  • 为什么这样设计：固定提交的文件顶部注释把它定位为“DeepSeek fish logo (figma I39:24057;88:8943 fillGeometry, exact extract; the full-canvas rectangle path from the raw dump is a background plate and is intentionally dropped). Native 23.16x17.04, rendered 24x18 by default; hero usage scales to 34x25. Color r...”；把这项职责单独放置，可以让边界、输入和失败处理在一个地方被阅读和测试。
  • 文件级设计证据：源码顶部注释把它定位为“DeepSeek fish logo (figma I39:24057;88:8943 fillGeometry, exact extract; the full-canvas rectangle path from the raw dump is a background plate and is intentionally dropped). Native 23.16x17.04, rendered 24x18 by default; hero usage scales to 34x25. Color r...”；固定提交中扫描到的声明包括 FishLogo；本地静态 import 图显示它直接依赖 1 个源文件，并被 1 个源文件直接引用。
  • 直接协作者：packages/client/ui-primitives/README.md、packages/client/ui-primitives/src/icons/props.ts、packages/client/ui-primitives/src/index.ts
  • 对应测试：间接测试线索（通过本地 import 链，非直接覆盖）：packages/client/locale/tests/apply.client.spec.ts、packages/client/locale/tests/document-language.client.spec.ts、packages/client/locale/tests/invariant.client.spec.ts、packages/client/locale/tests/language-row.client.spec.tsx、packages/client/locale/tests/locale.client.spec.ts、packages/client/ui-agent-preset/tests/apply.client.spec.ts
  • 测试关联依据：固定提交源码中的本地静态 import 传递引用；这些测试通过包入口或中间模块到达本文件，不等于本文件被直接覆盖。
  • 阅读顺序：先读客户端运行时契约或呈现模型，再读当前界面文件，沿着 packages/client/ui-primitives/src/index.ts 确认状态如何进入 UI，最后对照 packages/client/locale/tests/apply.client.spec.ts、packages/client/locale/tests/document-language.client.spec.ts、packages/client/locale/tests/invariant.client.spec.ts。
  • 代码证据：固定提交归档实际读取结果：约 27 行；扫描到的声明包括 FishLogo；源码顶部原注释（英文，仅作回查线索）：DeepSeek fish logo (figma I39:24057;88:8943 fillGeometry, exact extract; the full-canvas rectangle path from the raw dump is a background plate and is intentionally dropped). Native 23.16x17.04, rendered 24x18 by default; hero usage scales to 34x25. Color r...。
  • 固定版本：源码链接固定到官方提交 aa6c361a972c8369148dea7380bb5c21c24e07ec。

packages/client/ui-primitives/src/HoverCard.module.css ​

  • 所属层：packages/client：可复用的 Harness 功能包
  • 文件角色：界面样式
  • 这个文件有什么用：它定义 HoverCard 的网页外观、布局和状态样式，让界面逻辑与视觉规则可以分别修改。
  • 为什么这样设计：把 HoverCard 的样式与业务流程分开，浏览器端可以调整外观而不改变服务端或 agent 的行为；组件只通过 class 和状态选择器使用它。
  • 文件级设计证据：源码顶部注释把它定位为“Block, not inline-flex: consumers wrap full-width list rows and an inline wrapper would shrink them; the card still measures this rect.”；固定提交中扫描到的结构线索是：样式结构包含选择器 .root、.card、.copyable、.feedback、.copied、.status；自定义属性 --dsw-hovercard-bg；本地静态 import 图显示它直接依赖 0 个源文件，并被 1 个源文件直接引用。
  • 直接协作者：packages/client/ui-primitives/README.md、packages/client/ui-primitives/src/HoverCard.tsx
  • 对应测试：间接测试线索（通过本地 import 链，非直接覆盖）：packages/client/locale/tests/apply.client.spec.ts、packages/client/locale/tests/language-row.client.spec.tsx、packages/client/ui-agent-preset/tests/apply.client.spec.ts、packages/client/ui-agent-preset/tests/components.client.spec.tsx、packages/client/ui-agent-preset/tests/section.client.spec.tsx、packages/client/ui-attachment/tests/attachment-rail.client.spec.tsx
  • 测试关联依据：固定提交源码中的本地静态 import 传递引用；这些测试通过包入口或中间模块到达本文件，不等于本文件被直接覆盖。
  • 阅读顺序：先读客户端运行时契约或呈现模型，再读当前界面文件，沿着 packages/client/ui-primitives/src/HoverCard.tsx 确认状态如何进入 UI，最后对照 packages/client/locale/tests/apply.client.spec.ts、packages/client/locale/tests/language-row.client.spec.tsx、packages/client/ui-agent-preset/tests/apply.client.spec.ts。
  • 代码证据：固定提交归档实际读取结果：约 54 行；样式结构包含选择器 .root、.card、.copyable、.feedback、.copied、.status；自定义属性 --dsw-hovercard-bg；源码顶部原注释（英文，仅作回查线索）：Block, not inline-flex: consumers wrap full-width list rows and an inline wrapper would shrink them; the card still measures this rect.。
  • 固定版本：源码链接固定到官方提交 aa6c361a972c8369148dea7380bb5c21c24e07ec。

packages/client/ui-primitives/src/HoverCard.tsx ​

  • 所属层：packages/client：可复用的 Harness 功能包
  • 文件角色：界面组件或界面逻辑
  • 这个文件有什么用：它实现名为 HoverCard 的界面组件或交互逻辑，并导出 HoverCard，把输入、局部状态和用户操作组织成可渲染的 UI 单元；源码顶部还说明：HoverCard: delayed hover-preview card portaled to document.body. Same portal mechanics as Menu: the wrapper span supplies the anchor rect, the card is fixed-positioned at its right edge and repositions on scroll/resize while open. The card is reachable: it ...。
  • 为什么这样设计：固定提交的文件顶部注释把它定位为“HoverCard: delayed hover-preview card portaled to document.body. Same portal mechanics as Menu: the wrapper span supplies the anchor rect, the card is fixed-positioned at its right edge and repositions on scroll/resize while open. The card is reachable: it ...”；把这项职责单独放置，可以让边界、输入和失败处理在一个地方被阅读和测试。
  • 文件级设计证据：源码顶部注释把它定位为“HoverCard: delayed hover-preview card portaled to document.body. Same portal mechanics as Menu: the wrapper span supplies the anchor rect, the card is fixed-positioned at its right edge and repositions on scroll/resize while open. The card is reachable: it ...”；固定提交中扫描到的声明包括 HoverCard；本地静态 import 图显示它直接依赖 3 个源文件，并被 1 个源文件直接引用。
  • 直接协作者：packages/client/ui-primitives/README.md、packages/client/ui-primitives/src/HoverCard.module.css、packages/client/ui-primitives/src/clipboard.ts、packages/client/ui-primitives/src/pointer-grace.ts、packages/client/ui-primitives/src/index.ts
  • 对应测试：间接测试线索（通过本地 import 链，非直接覆盖）：packages/client/locale/tests/apply.client.spec.ts、packages/client/locale/tests/document-language.client.spec.ts、packages/client/locale/tests/invariant.client.spec.ts、packages/client/locale/tests/language-row.client.spec.tsx、packages/client/locale/tests/locale.client.spec.ts、packages/client/ui-agent-preset/tests/apply.client.spec.ts
  • 测试关联依据：固定提交源码中的本地静态 import 传递引用；这些测试通过包入口或中间模块到达本文件，不等于本文件被直接覆盖。
  • 阅读顺序：先读客户端运行时契约或呈现模型，再读当前界面文件，沿着 packages/client/ui-primitives/src/index.ts 确认状态如何进入 UI，最后对照 packages/client/locale/tests/apply.client.spec.ts、packages/client/locale/tests/document-language.client.spec.ts、packages/client/locale/tests/invariant.client.spec.ts。
  • 代码证据：固定提交归档实际读取结果：约 216 行；扫描到的声明包括 HoverCard；源码顶部原注释（英文，仅作回查线索）：HoverCard: delayed hover-preview card portaled to document.body. Same portal mechanics as Menu: the wrapper span supplies the anchor rect, the card is fixed-positioned at its right edge and repositions on scroll/resize while open. The card is reachable: it ...。
  • 固定版本：源码链接固定到官方提交 aa6c361a972c8369148dea7380bb5c21c24e07ec。

packages/client/ui-primitives/src/Input.module.css ​

packages/client/ui-primitives/src/Input.tsx ​

  • 所属层：packages/client：可复用的 Harness 功能包
  • 文件角色：界面组件或界面逻辑
  • 这个文件有什么用：它实现名为 Input 的界面组件或交互逻辑，并导出 Input，把输入、局部状态和用户操作组织成可渲染的 UI 单元；源码顶部还说明：Input: single-line text input atom (search boxes, inline forms). Composer textareas are NOT this atom — they live with the conversation package.。
  • 为什么这样设计：固定提交的文件顶部注释把它定位为“Input: single-line text input atom (search boxes, inline forms). Composer textareas are NOT this atom — they live with the conversation package.”；把这项职责单独放置，可以让边界、输入和失败处理在一个地方被阅读和测试。
  • 文件级设计证据：源码顶部注释把它定位为“Input: single-line text input atom (search boxes, inline forms). Composer textareas are NOT this atom — they live with the conversation package.”；固定提交中扫描到的声明包括 Input；本地静态 import 图显示它直接依赖 1 个源文件，并被 1 个源文件直接引用。
  • 直接协作者：packages/client/ui-primitives/README.md、packages/client/ui-primitives/src/Input.module.css、packages/client/ui-primitives/src/index.ts
  • 对应测试：间接测试线索（通过本地 import 链，非直接覆盖）：packages/client/locale/tests/apply.client.spec.ts、packages/client/locale/tests/document-language.client.spec.ts、packages/client/locale/tests/invariant.client.spec.ts、packages/client/locale/tests/language-row.client.spec.tsx、packages/client/locale/tests/locale.client.spec.ts、packages/client/ui-agent-preset/tests/apply.client.spec.ts
  • 测试关联依据：固定提交源码中的本地静态 import 传递引用；这些测试通过包入口或中间模块到达本文件，不等于本文件被直接覆盖。
  • 阅读顺序：先读客户端运行时契约或呈现模型，再读当前界面文件，沿着 packages/client/ui-primitives/src/index.ts 确认状态如何进入 UI，最后对照 packages/client/locale/tests/apply.client.spec.ts、packages/client/locale/tests/document-language.client.spec.ts、packages/client/locale/tests/invariant.client.spec.ts。
  • 代码证据：固定提交归档实际读取结果：约 23 行；扫描到的声明包括 Input；源码顶部原注释（英文，仅作回查线索）：Input: single-line text input atom (search boxes, inline forms). Composer textareas are NOT this atom — they live with the conversation package.。
  • 固定版本：源码链接固定到官方提交 aa6c361a972c8369148dea7380bb5c21c24e07ec。

packages/client/ui-primitives/src/JsonTree.module.css ​

  • 所属层：packages/client：可复用的 Harness 功能包
  • 文件角色：界面样式
  • 这个文件有什么用：它定义 JsonTree 的网页外观、布局和状态样式，让界面逻辑与视觉规则可以分别修改。
  • 为什么这样设计：把 JsonTree 的样式与业务流程分开，浏览器端可以调整外观而不改变服务端或 agent 的行为；组件只通过 class 和状态选择器使用它。
  • 文件级设计证据：固定提交中扫描到的结构线索是：样式结构包含选择器 .root、.container、.expandedTopLevel、.expandedTopLevelContainer、.topLevelBracket、.children；自定义属性 --json-tree-property、--json-tree-string、--json-tree-number、--json-tree-keyword、--json-tree-punctuation、--json-tree-icon；本地静态 import 图显示它直接依赖 0 个源文件，并被 1 个源文件直接引用。
  • 直接协作者：packages/client/ui-primitives/README.md、packages/client/ui-primitives/src/JsonTree.tsx
  • 对应测试：间接测试线索（通过本地 import 链，非直接覆盖）：packages/client/locale/tests/apply.client.spec.ts、packages/client/locale/tests/language-row.client.spec.tsx、packages/client/ui-agent-preset/tests/apply.client.spec.ts、packages/client/ui-agent-preset/tests/components.client.spec.tsx、packages/client/ui-agent-preset/tests/section.client.spec.tsx、packages/client/ui-attachment/tests/attachment-rail.client.spec.tsx
  • 测试关联依据：固定提交源码中的本地静态 import 传递引用；这些测试通过包入口或中间模块到达本文件，不等于本文件被直接覆盖。
  • 阅读顺序：先读客户端运行时契约或呈现模型，再读当前界面文件，沿着 packages/client/ui-primitives/src/JsonTree.tsx 确认状态如何进入 UI，最后对照 packages/client/locale/tests/apply.client.spec.ts、packages/client/locale/tests/language-row.client.spec.tsx、packages/client/ui-agent-preset/tests/apply.client.spec.ts。
  • 代码证据：固定提交归档实际读取结果：约 222 行；样式结构包含选择器 .root、.container、.expandedTopLevel、.expandedTopLevelContainer、.topLevelBracket、.children；自定义属性 --json-tree-property、--json-tree-string、--json-tree-number、--json-tree-keyword、--json-tree-punctuation、--json-tree-icon。
  • 固定版本：源码链接固定到官方提交 aa6c361a972c8369148dea7380bb5c21c24e07ec。

packages/client/ui-primitives/src/JsonTree.tsx ​

packages/client/ui-primitives/src/Menu.module.css ​

packages/client/ui-primitives/src/Menu.tsx ​

  • 所属层：packages/client：可复用的 Harness 功能包
  • 文件角色：界面组件或界面逻辑
  • 这个文件有什么用：它实现名为 Menu 的界面组件或交互逻辑，并导出 MenuItem、MenuSeparator、MenuLabel，把输入、局部状态和用户操作组织成可渲染的 UI 单元；源码顶部还说明：Menu: minimal controlled dropdown (group-by pickers, project selectors). Default: pure CSS positioning relative to the anchor wrapper — no popper. Opt-in portal renders the list into document.body, fixed-positioned from the anchor rect, for anchors inside o...。
  • 为什么这样设计：固定提交的文件顶部注释把它定位为“Menu: minimal controlled dropdown (group-by pickers, project selectors). Default: pure CSS positioning relative to the anchor wrapper — no popper. Opt-in portal renders the list into document.body, fixed-positioned from the anchor rect, for anchors inside o...”；把这项职责单独放置，可以让边界、输入和失败处理在一个地方被阅读和测试。
  • 文件级设计证据：源码顶部注释把它定位为“Menu: minimal controlled dropdown (group-by pickers, project selectors). Default: pure CSS positioning relative to the anchor wrapper — no popper. Opt-in portal renders the list into document.body, fixed-positioned from the anchor rect, for anchors inside o...”；固定提交中扫描到的声明包括 MenuItem、MenuSeparator、MenuLabel、MenuEntry、Menu；本地静态 import 图显示它直接依赖 3 个源文件，并被 2 个源文件直接引用。
  • 直接协作者：packages/client/ui-primitives/README.md、packages/client/ui-primitives/src/Menu.module.css、packages/client/ui-primitives/src/icons/index.tsx、packages/client/ui-primitives/src/pointer-grace.ts、packages/client/ui-primitives/src/JsonTree.tsx
  • 对应测试：间接测试线索（通过本地 import 链，非直接覆盖）：packages/client/locale/tests/apply.client.spec.ts、packages/client/locale/tests/document-language.client.spec.ts、packages/client/locale/tests/invariant.client.spec.ts、packages/client/locale/tests/language-row.client.spec.tsx、packages/client/locale/tests/locale.client.spec.ts、packages/client/ui-agent-preset/tests/apply.client.spec.ts
  • 测试关联依据：固定提交源码中的本地静态 import 传递引用；这些测试通过包入口或中间模块到达本文件，不等于本文件被直接覆盖。
  • 阅读顺序：先读客户端运行时契约或呈现模型，再读当前界面文件，沿着 packages/client/ui-primitives/src/JsonTree.tsx、packages/client/ui-primitives/src/index.ts 确认状态如何进入 UI，最后对照 packages/client/locale/tests/apply.client.spec.ts、packages/client/locale/tests/document-language.client.spec.ts、packages/client/locale/tests/invariant.client.spec.ts。
  • 代码证据：固定提交归档实际读取结果：约 302 行；扫描到的声明包括 MenuItem、MenuSeparator、MenuLabel、MenuEntry、Menu、isSeparator、isLabel；源码顶部原注释（英文，仅作回查线索）：Menu: minimal controlled dropdown (group-by pickers, project selectors). Default: pure CSS positioning relative to the anchor wrapper — no popper. Opt-in portal renders the list into document.body, fixed-positioned from the anchor rect, for anchors inside o...。
  • 固定版本：源码链接固定到官方提交 aa6c361a972c8369148dea7380bb5c21c24e07ec。

packages/client/ui-primitives/src/Modal.module.css ​

  • 所属层：packages/client：可复用的 Harness 功能包
  • 文件角色：界面样式
  • 这个文件有什么用：它定义 Modal 的网页外观、布局和状态样式，让界面逻辑与视觉规则可以分别修改。
  • 为什么这样设计：把 Modal 的样式与业务流程分开，浏览器端可以调整外观而不改变服务端或 agent 的行为；组件只通过 class 和状态选择器使用它。
  • 文件级设计证据：源码顶部注释把它定位为“Full-viewport layer (figma Mask + Dialog 451:18655): mask + centered card.”；固定提交中扫描到的结构线索是：样式结构包含选择器 .root、.mask、.dialog、.content、.header、.title；本地静态 import 图显示它直接依赖 0 个源文件，并被 1 个源文件直接引用。
  • 直接协作者：packages/client/ui-primitives/README.md、packages/client/ui-primitives/src/Modal.tsx
  • 对应测试：间接测试线索（通过本地 import 链，非直接覆盖）：packages/client/locale/tests/apply.client.spec.ts、packages/client/locale/tests/language-row.client.spec.tsx、packages/client/ui-agent-preset/tests/apply.client.spec.ts、packages/client/ui-agent-preset/tests/components.client.spec.tsx、packages/client/ui-agent-preset/tests/section.client.spec.tsx、packages/client/ui-attachment/tests/attachment-rail.client.spec.tsx
  • 测试关联依据：固定提交源码中的本地静态 import 传递引用；这些测试通过包入口或中间模块到达本文件，不等于本文件被直接覆盖。
  • 阅读顺序：先读客户端运行时契约或呈现模型，再读当前界面文件，沿着 packages/client/ui-primitives/src/Modal.tsx 确认状态如何进入 UI，最后对照 packages/client/locale/tests/apply.client.spec.ts、packages/client/locale/tests/language-row.client.spec.tsx、packages/client/ui-agent-preset/tests/apply.client.spec.ts。
  • 代码证据：固定提交归档实际读取结果：约 103 行；样式结构包含选择器 .root、.mask、.dialog、.content、.header、.title；源码顶部原注释（英文，仅作回查线索）：Full-viewport layer (figma Mask + Dialog 451:18655): mask + centered card.。
  • 固定版本：源码链接固定到官方提交 aa6c361a972c8369148dea7380bb5c21c24e07ec。

packages/client/ui-primitives/src/Modal.tsx ​

  • 所属层：packages/client：可复用的 Harness 功能包
  • 文件角色：界面组件或界面逻辑
  • 这个文件有什么用：它实现名为 Modal 的界面组件或交互逻辑，并导出 Modal，把输入、局部状态和用户操作组织成可渲染的 UI 单元；源码顶部还说明：Modal: controlled full-viewport dialog (create-workspace and similar). The overlay portals to this document's body so ancestor stacking contexts cannot leave sticky page controls above the mask. This is still an in-page WebUI dialog; it never creates or tar...。
  • 为什么这样设计：固定提交的文件顶部注释把它定位为“Modal: controlled full-viewport dialog (create-workspace and similar). The overlay portals to this document's body so ancestor stacking contexts cannot leave sticky page controls above the mask. This is still an in-page WebUI dialog; it never creates or tar...”；把这项职责单独放置，可以让边界、输入和失败处理在一个地方被阅读和测试。
  • 文件级设计证据：源码顶部注释把它定位为“Modal: controlled full-viewport dialog (create-workspace and similar). The overlay portals to this document's body so ancestor stacking contexts cannot leave sticky page controls above the mask. This is still an in-page WebUI dialog; it never creates or tar...”；固定提交中扫描到的声明包括 Modal；本地静态 import 图显示它直接依赖 2 个源文件，并被 2 个源文件直接引用。
  • 直接协作者：packages/client/ui-primitives/README.md、packages/client/ui-primitives/src/Modal.module.css、packages/client/ui-primitives/src/icons/index.tsx、packages/client/ui-primitives/src/RiskConfirmation.tsx、packages/client/ui-primitives/src/index.ts
  • 对应测试：间接测试线索（通过本地 import 链，非直接覆盖）：packages/client/locale/tests/apply.client.spec.ts、packages/client/locale/tests/document-language.client.spec.ts、packages/client/locale/tests/invariant.client.spec.ts、packages/client/locale/tests/language-row.client.spec.tsx、packages/client/locale/tests/locale.client.spec.ts、packages/client/ui-agent-preset/tests/apply.client.spec.ts
  • 测试关联依据：固定提交源码中的本地静态 import 传递引用；这些测试通过包入口或中间模块到达本文件，不等于本文件被直接覆盖。
  • 阅读顺序：先读客户端运行时契约或呈现模型，再读当前界面文件，沿着 packages/client/ui-primitives/src/RiskConfirmation.tsx、packages/client/ui-primitives/src/index.ts 确认状态如何进入 UI，最后对照 packages/client/locale/tests/apply.client.spec.ts、packages/client/locale/tests/document-language.client.spec.ts、packages/client/locale/tests/invariant.client.spec.ts。
  • 代码证据：固定提交归档实际读取结果：约 86 行；扫描到的声明包括 Modal；源码顶部原注释（英文，仅作回查线索）：Modal: controlled full-viewport dialog (create-workspace and similar). The overlay portals to this document's body so ancestor stacking contexts cannot leave sticky page controls above the mask. This is still an in-page WebUI dialog; it never creates or tar...。
  • 固定版本：源码链接固定到官方提交 aa6c361a972c8369148dea7380bb5c21c24e07ec。

packages/client/ui-primitives/src/OnboardingSurface.module.css ​

  • 所属层：packages/client：可复用的 Harness 功能包
  • 文件角色：界面样式
  • 这个文件有什么用：它定义 OnboardingSurface 的网页外观、布局和状态样式，让界面逻辑与视觉规则可以分别修改。
  • 为什么这样设计：把 OnboardingSurface 的样式与业务流程分开，浏览器端可以调整外观而不改变服务端或 agent 的行为；组件只通过 class 和状态选择器使用它。
  • 文件级设计证据：源码顶部注释把它定位为“First-run stage: keep the product top bar visible, then let onboarding own the complete workspace instead of presenting another settings modal.”；固定提交中扫描到的结构线索是：样式结构包含选择器 .onboardingOverlay、.onboardingMask、.onboardingStage；本地静态 import 图显示它直接依赖 0 个源文件，并被 1 个源文件直接引用。
  • 直接协作者：packages/client/ui-primitives/README.md、packages/client/ui-primitives/src/OnboardingSurface.tsx
  • 对应测试：间接测试线索（通过本地 import 链，非直接覆盖）：packages/client/locale/tests/apply.client.spec.ts、packages/client/locale/tests/language-row.client.spec.tsx、packages/client/ui-agent-preset/tests/apply.client.spec.ts、packages/client/ui-agent-preset/tests/components.client.spec.tsx、packages/client/ui-agent-preset/tests/section.client.spec.tsx、packages/client/ui-attachment/tests/attachment-rail.client.spec.tsx
  • 测试关联依据：固定提交源码中的本地静态 import 传递引用；这些测试通过包入口或中间模块到达本文件，不等于本文件被直接覆盖。
  • 阅读顺序：先读客户端运行时契约或呈现模型，再读当前界面文件，沿着 packages/client/ui-primitives/src/OnboardingSurface.tsx 确认状态如何进入 UI，最后对照 packages/client/locale/tests/apply.client.spec.ts、packages/client/locale/tests/language-row.client.spec.tsx、packages/client/ui-agent-preset/tests/apply.client.spec.ts。
  • 代码证据：固定提交归档实际读取结果：约 29 行；样式结构包含选择器 .onboardingOverlay、.onboardingMask、.onboardingStage；源码顶部原注释（英文，仅作回查线索）：First-run stage: keep the product top bar visible, then let onboarding own the complete workspace instead of presenting another settings modal.。
  • 固定版本：源码链接固定到官方提交 aa6c361a972c8369148dea7380bb5c21c24e07ec。

packages/client/ui-primitives/src/OnboardingSurface.tsx ​

  • 所属层：packages/client：可复用的 Harness 功能包
  • 文件角色：界面组件或界面逻辑
  • 这个文件有什么用：它实现名为 OnboardingSurface 的界面组件或交互逻辑，并导出 OnboardingSurface，把输入、局部状态和用户操作组织成可渲染的 UI 单元；源码顶部还说明：OnboardingSurface: the full-viewport first-run takeover an onboarding step wraps its visible content in. The overlay portals to this document's body (the Modal precedent: ancestor stacking contexts cannot leave sticky page controls above the mask), and the ...。
  • 为什么这样设计：固定提交的文件顶部注释把它定位为“OnboardingSurface: the full-viewport first-run takeover an onboarding step wraps its visible content in. The overlay portals to this document's body (the Modal precedent: ancestor stacking contexts cannot leave sticky page controls above the mask), and the ...”；把这项职责单独放置，可以让边界、输入和失败处理在一个地方被阅读和测试。
  • 文件级设计证据：源码顶部注释把它定位为“OnboardingSurface: the full-viewport first-run takeover an onboarding step wraps its visible content in. The overlay portals to this document's body (the Modal precedent: ancestor stacking contexts cannot leave sticky page controls above the mask), and the ...”；固定提交中扫描到的声明包括 OnboardingSurface；本地静态 import 图显示它直接依赖 1 个源文件，并被 1 个源文件直接引用。
  • 直接协作者：packages/client/ui-primitives/README.md、packages/client/ui-primitives/src/OnboardingSurface.module.css、packages/client/ui-primitives/src/index.ts
  • 对应测试：间接测试线索（通过本地 import 链，非直接覆盖）：packages/client/locale/tests/apply.client.spec.ts、packages/client/locale/tests/document-language.client.spec.ts、packages/client/locale/tests/invariant.client.spec.ts、packages/client/locale/tests/language-row.client.spec.tsx、packages/client/locale/tests/locale.client.spec.ts、packages/client/ui-agent-preset/tests/apply.client.spec.ts
  • 测试关联依据：固定提交源码中的本地静态 import 传递引用；这些测试通过包入口或中间模块到达本文件，不等于本文件被直接覆盖。
  • 阅读顺序：先读客户端运行时契约或呈现模型，再读当前界面文件，沿着 packages/client/ui-primitives/src/index.ts 确认状态如何进入 UI，最后对照 packages/client/locale/tests/apply.client.spec.ts、packages/client/locale/tests/document-language.client.spec.ts、packages/client/locale/tests/invariant.client.spec.ts。
  • 代码证据：固定提交归档实际读取结果：约 34 行；扫描到的声明包括 OnboardingSurface；源码顶部原注释（英文，仅作回查线索）：OnboardingSurface: the full-viewport first-run takeover an onboarding step wraps its visible content in. The overlay portals to this document's body (the Modal precedent: ancestor stacking contexts cannot leave sticky page controls above the mask), and the ...。
  • 固定版本：源码链接固定到官方提交 aa6c361a972c8369148dea7380bb5c21c24e07ec。

packages/client/ui-primitives/src/Pill.module.css ​

packages/client/ui-primitives/src/Pill.tsx ​

packages/client/ui-primitives/src/ReadBlock.module.css ​

  • 所属层：packages/client：可复用的 Harness 功能包
  • 文件角色：界面样式
  • 这个文件有什么用：它定义 ReadBlock 的网页外观、布局和状态样式，让界面逻辑与视觉规则可以分别修改。
  • 为什么这样设计：把 ReadBlock 的样式与业务流程分开，浏览器端可以调整外观而不改变服务端或 agent 的行为；组件只通过 class 和状态选择器使用它。
  • 文件级设计证据：源码顶部注释把它定位为“Geometry mirrors CodeBlock (12px radius, code-block surface + banner row, markdown code-block font) so a read card and a fenced code block read as one family. Content keeps white-space: pre and scrolls horizontally rather than folding, because a source line...”；固定提交中扫描到的结构线索是：样式结构包含选择器 .block、.banner、.label、.action、.count、.lang；自定义属性 --dsl-read-radius、--dsl-read-line-height、--dsl-read-gutter；本地静态 import 图显示它直接依赖 0 个源文件，并被 1 个源文件直接引用。
  • 直接协作者：packages/client/ui-primitives/README.md、packages/client/ui-primitives/src/ReadBlock.tsx
  • 对应测试：间接测试线索（通过本地 import 链，非直接覆盖）：packages/client/locale/tests/apply.client.spec.ts、packages/client/locale/tests/language-row.client.spec.tsx、packages/client/ui-agent-preset/tests/apply.client.spec.ts、packages/client/ui-agent-preset/tests/components.client.spec.tsx、packages/client/ui-agent-preset/tests/section.client.spec.tsx、packages/client/ui-attachment/tests/attachment-rail.client.spec.tsx
  • 测试关联依据：固定提交源码中的本地静态 import 传递引用；这些测试通过包入口或中间模块到达本文件，不等于本文件被直接覆盖。
  • 阅读顺序：先读客户端运行时契约或呈现模型，再读当前界面文件，沿着 packages/client/ui-primitives/src/ReadBlock.tsx 确认状态如何进入 UI，最后对照 packages/client/locale/tests/apply.client.spec.ts、packages/client/locale/tests/language-row.client.spec.tsx、packages/client/ui-agent-preset/tests/apply.client.spec.ts。
  • 代码证据：固定提交归档实际读取结果：约 117 行；样式结构包含选择器 .block、.banner、.label、.action、.count、.lang；自定义属性 --dsl-read-radius、--dsl-read-line-height、--dsl-read-gutter；源码顶部原注释（英文，仅作回查线索）：Geometry mirrors CodeBlock (12px radius, code-block surface + banner row, markdown code-block font) so a read card and a fenced code block read as one family. Content keeps white-space: pre and scrolls horizontally rather than folding, because a source line...。
  • 固定版本：源码链接固定到官方提交 aa6c361a972c8369148dea7380bb5c21c24e07ec。

packages/client/ui-primitives/src/ReadBlock.tsx ​

  • 所属层：packages/client：可复用的 Harness 功能包
  • 文件角色：界面组件或界面逻辑
  • 这个文件有什么用：它实现名为 ReadBlock 的界面组件或交互逻辑，并导出 DEFAULT_READ_MAX_LINES、ReadBlockLine、ReadBlockProps，把输入、局部状态和用户操作组织成可渲染的 UI 单元；源码顶部还说明：ReadBlock: the file surface for a read tool result — a banner (label + language + a "showing N of M" note when the read is a window + a copy control) over line-numbered, syntax-highlighted source. Each row carries the file's OWN line number in a gutter, so ...。
  • 为什么这样设计：固定提交的文件顶部注释把它定位为“ReadBlock: the file surface for a read tool result — a banner (label + language + a "showing N of M" note when the read is a window + a copy control) over line-numbered, syntax-highlighted source. Each row carries the file's OWN line number in a gutter, so ...”；把这项职责单独放置，可以让边界、输入和失败处理在一个地方被阅读和测试。
  • 文件级设计证据：源码顶部注释把它定位为“ReadBlock: the file surface for a read tool result — a banner (label + language + a "showing N of M" note when the read is a window + a copy control) over line-numbered, syntax-highlighted source. Each row carries the file's OWN line number in a gutter, so ...”；固定提交中扫描到的声明包括 DEFAULT_READ_MAX_LINES、ReadBlockLine、ReadBlockProps、ReadBlock、renderSpans；本地静态 import 图显示它直接依赖 3 个源文件，并被 1 个源文件直接引用。
  • 直接协作者：packages/client/ui-primitives/README.md、packages/client/ui-primitives/src/ReadBlock.module.css、packages/client/ui-primitives/src/clipboard.ts、packages/client/ui-primitives/src/markdown/highlight.ts、packages/client/ui-primitives/src/index.ts
  • 对应测试：间接测试线索（通过本地 import 链，非直接覆盖）：packages/client/locale/tests/apply.client.spec.ts、packages/client/locale/tests/document-language.client.spec.ts、packages/client/locale/tests/invariant.client.spec.ts、packages/client/locale/tests/language-row.client.spec.tsx、packages/client/locale/tests/locale.client.spec.ts、packages/client/ui-agent-preset/tests/apply.client.spec.ts
  • 测试关联依据：固定提交源码中的本地静态 import 传递引用；这些测试通过包入口或中间模块到达本文件，不等于本文件被直接覆盖。
  • 阅读顺序：先读客户端运行时契约或呈现模型，再读当前界面文件，沿着 packages/client/ui-primitives/src/index.ts 确认状态如何进入 UI，最后对照 packages/client/locale/tests/apply.client.spec.ts、packages/client/locale/tests/document-language.client.spec.ts、packages/client/locale/tests/invariant.client.spec.ts。
  • 代码证据：固定提交归档实际读取结果：约 172 行；扫描到的声明包括 DEFAULT_READ_MAX_LINES、ReadBlockLine、ReadBlockProps、ReadBlock、renderSpans；源码顶部原注释（英文，仅作回查线索）：ReadBlock: the file surface for a read tool result — a banner (label + language + a "showing N of M" note when the read is a window + a copy control) over line-numbered, syntax-highlighted source. Each row carries the file's OWN line number in a gutter, so ...。
  • 固定版本：源码链接固定到官方提交 aa6c361a972c8369148dea7380bb5c21c24e07ec。

packages/client/ui-primitives/src/RiskConfirmation.module.css ​

packages/client/ui-primitives/src/RiskConfirmation.tsx ​

  • 所属层：packages/client：可复用的 Harness 功能包
  • 文件角色：界面组件或界面逻辑
  • 这个文件有什么用：它实现名为 RiskConfirmation 的界面组件或交互逻辑，并导出 RiskConfirmationProps、RiskConfirmation，把输入、局部状态和用户操作组织成可渲染的 UI 单元；源码顶部还说明：Controlled risk acknowledgement dialog shared by product surfaces that must gate a sensitive action behind an explicit checkbox.。
  • 为什么这样设计：固定提交的文件顶部注释把它定位为“Controlled risk acknowledgement dialog shared by product surfaces that must gate a sensitive action behind an explicit checkbox.”；把这项职责单独放置，可以让边界、输入和失败处理在一个地方被阅读和测试。
  • 文件级设计证据：源码顶部注释把它定位为“Controlled risk acknowledgement dialog shared by product surfaces that must gate a sensitive action behind an explicit checkbox.”；固定提交中扫描到的声明包括 RiskConfirmationProps、RiskConfirmation；本地静态 import 图显示它直接依赖 4 个源文件，并被 1 个源文件直接引用。
  • 直接协作者：packages/client/ui-primitives/README.md、packages/client/ui-primitives/src/Button.tsx、packages/client/ui-primitives/src/Modal.tsx、packages/client/ui-primitives/src/RiskConfirmation.module.css、packages/client/ui-primitives/src/index.ts
  • 对应测试：间接测试线索（通过本地 import 链，非直接覆盖）：packages/client/locale/tests/apply.client.spec.ts、packages/client/locale/tests/document-language.client.spec.ts、packages/client/locale/tests/invariant.client.spec.ts、packages/client/locale/tests/language-row.client.spec.tsx、packages/client/locale/tests/locale.client.spec.ts、packages/client/ui-agent-preset/tests/apply.client.spec.ts
  • 测试关联依据：固定提交源码中的本地静态 import 传递引用；这些测试通过包入口或中间模块到达本文件，不等于本文件被直接覆盖。
  • 阅读顺序：先读客户端运行时契约或呈现模型，再读当前界面文件，沿着 packages/client/ui-primitives/src/index.ts 确认状态如何进入 UI，最后对照 packages/client/locale/tests/apply.client.spec.ts、packages/client/locale/tests/document-language.client.spec.ts、packages/client/locale/tests/invariant.client.spec.ts。
  • 代码证据：固定提交归档实际读取结果：约 80 行；扫描到的声明包括 RiskConfirmationProps、RiskConfirmation；源码顶部原注释（英文，仅作回查线索）：Controlled risk acknowledgement dialog shared by product surfaces that must gate a sensitive action behind an explicit checkbox.。
  • 固定版本：源码链接固定到官方提交 aa6c361a972c8369148dea7380bb5c21c24e07ec。

packages/client/ui-primitives/src/SearchBlock.module.css ​

  • 所属层：packages/client：可复用的 Harness 功能包
  • 文件角色：界面样式
  • 这个文件有什么用：它定义 SearchBlock 的网页外观、布局和状态样式，让界面逻辑与视觉规则可以分别修改。
  • 为什么这样设计：把 SearchBlock 的样式与业务流程分开，浏览器端可以调整外观而不改变服务端或 agent 的行为；组件只通过 class 和状态选择器使用它。
  • 文件级设计证据：源码顶部注释把它定位为“Geometry mirrors CodeBlock and TerminalBlock (12px radius, code-block surface + banner row, markdown code-block font) so a search card reads as one family with them. The deliberate divergence they share: the result rows keep white-space: pre and scroll hori...”；固定提交中扫描到的结构线索是：样式结构包含选择器 .block、.header、.summary、.copyButton、.body、.line；自定义属性 --dsl-search-radius、--dsl-search-line-height；本地静态 import 图显示它直接依赖 0 个源文件，并被 1 个源文件直接引用。
  • 直接协作者：packages/client/ui-primitives/README.md、packages/client/ui-primitives/src/SearchBlock.tsx
  • 对应测试：间接测试线索（通过本地 import 链，非直接覆盖）：packages/client/locale/tests/apply.client.spec.ts、packages/client/locale/tests/language-row.client.spec.tsx、packages/client/ui-agent-preset/tests/apply.client.spec.ts、packages/client/ui-agent-preset/tests/components.client.spec.tsx、packages/client/ui-agent-preset/tests/section.client.spec.tsx、packages/client/ui-attachment/tests/attachment-rail.client.spec.tsx
  • 测试关联依据：固定提交源码中的本地静态 import 传递引用；这些测试通过包入口或中间模块到达本文件，不等于本文件被直接覆盖。
  • 阅读顺序：先读客户端运行时契约或呈现模型，再读当前界面文件，沿着 packages/client/ui-primitives/src/SearchBlock.tsx 确认状态如何进入 UI，最后对照 packages/client/locale/tests/apply.client.spec.ts、packages/client/locale/tests/language-row.client.spec.tsx、packages/client/ui-agent-preset/tests/apply.client.spec.ts。
  • 代码证据：固定提交归档实际读取结果：约 120 行；样式结构包含选择器 .block、.header、.summary、.copyButton、.body、.line；自定义属性 --dsl-search-radius、--dsl-search-line-height；源码顶部原注释（英文，仅作回查线索）：Geometry mirrors CodeBlock and TerminalBlock (12px radius, code-block surface + banner row, markdown code-block font) so a search card reads as one family with them. The deliberate divergence they share: the result rows keep white-space: pre and scroll hori...。
  • 固定版本：源码链接固定到官方提交 aa6c361a972c8369148dea7380bb5c21c24e07ec。

packages/client/ui-primitives/src/SearchBlock.tsx ​

  • 所属层：packages/client：可复用的 Harness 功能包
  • 文件角色：界面组件或界面逻辑
  • 这个文件有什么用：它实现名为 SearchBlock 的界面组件或交互逻辑，并导出 DEFAULT_SEARCH_MAX_LINES、SearchBlockLineMatch、SearchFileGroup，把输入、局部状态和用户操作组织成可渲染的 UI 单元；源码顶部还说明：SearchBlock: the search surface for a completed content or path search — a banner (result summary that folds the pre-cap total in when the tool capped the result, plus a copy control), then either grep matches grouped by file (each file a bold path header w...。
  • 为什么这样设计：固定提交的文件顶部注释把它定位为“SearchBlock: the search surface for a completed content or path search — a banner (result summary that folds the pre-cap total in when the tool capped the result, plus a copy control), then either grep matches grouped by file (each file a bold path header w...”；把这项职责单独放置，可以让边界、输入和失败处理在一个地方被阅读和测试。
  • 文件级设计证据：源码顶部注释把它定位为“SearchBlock: the search surface for a completed content or path search — a banner (result summary that folds the pre-cap total in when the tool capped the result, plus a copy control), then either grep matches grouped by file (each file a bold path header w...”；固定提交中扫描到的声明包括 DEFAULT_SEARCH_MAX_LINES、SearchBlockLineMatch、SearchFileGroup、SearchMatchesBlockProps、SearchPathsBlockProps；本地静态 import 图显示它直接依赖 3 个源文件，并被 1 个源文件直接引用。
  • 直接协作者：packages/client/ui-primitives/README.md、packages/client/ui-primitives/src/SearchBlock.module.css、packages/client/ui-primitives/src/head-tail-cap.ts、packages/client/ui-primitives/src/use-copy-feedback.ts、packages/client/ui-primitives/src/index.ts
  • 对应测试：间接测试线索（通过本地 import 链，非直接覆盖）：packages/client/locale/tests/apply.client.spec.ts、packages/client/locale/tests/document-language.client.spec.ts、packages/client/locale/tests/invariant.client.spec.ts、packages/client/locale/tests/language-row.client.spec.tsx、packages/client/locale/tests/locale.client.spec.ts、packages/client/ui-agent-preset/tests/apply.client.spec.ts
  • 测试关联依据：固定提交源码中的本地静态 import 传递引用；这些测试通过包入口或中间模块到达本文件，不等于本文件被直接覆盖。
  • 阅读顺序：先读客户端运行时契约或呈现模型，再读当前界面文件，沿着 packages/client/ui-primitives/src/index.ts 确认状态如何进入 UI，最后对照 packages/client/locale/tests/apply.client.spec.ts、packages/client/locale/tests/document-language.client.spec.ts、packages/client/locale/tests/invariant.client.spec.ts。
  • 代码证据：固定提交归档实际读取结果：约 277 行；扫描到的声明包括 DEFAULT_SEARCH_MAX_LINES、SearchBlockLineMatch、SearchFileGroup、SearchMatchesBlockProps、SearchPathsBlockProps、SearchBlockProps、SearchBlock、copyText；源码顶部原注释（英文，仅作回查线索）：SearchBlock: the search surface for a completed content or path search — a banner (result summary that folds the pre-cap total in when the tool capped the result, plus a copy control), then either grep matches grouped by file (each file a bold path header w...。
  • 固定版本：源码链接固定到官方提交 aa6c361a972c8369148dea7380bb5c21c24e07ec。

packages/client/ui-primitives/src/StateDot.module.css ​

  • 所属层：packages/client：可复用的 Harness 功能包
  • 文件角色：界面样式
  • 这个文件有什么用：它定义 StateDot 的网页外观、布局和状态样式，让界面逻辑与视觉规则可以分别修改。
  • 为什么这样设计：把 StateDot 的样式与业务流程分开，浏览器端可以调整外观而不改变服务端或 agent 的行为；组件只通过 class 和状态选择器使用它。
  • 文件级设计证据：源码顶部注释把它定位为“Ongoing blue has no alias token (state-business-primary is the 500 step, not this 450) — component-level var pinned to the static scale instead.”；固定提交中扫描到的结构线索是：样式结构包含选择器 .dot、.matrix、.cell；自定义属性 --dsh-state-ongoing；本地静态 import 图显示它直接依赖 0 个源文件，并被 1 个源文件直接引用。
  • 直接协作者：packages/client/ui-primitives/README.md、packages/client/ui-primitives/src/StateDot.tsx
  • 对应测试：间接测试线索（通过本地 import 链，非直接覆盖）：packages/client/locale/tests/apply.client.spec.ts、packages/client/locale/tests/language-row.client.spec.tsx、packages/client/ui-agent-preset/tests/apply.client.spec.ts、packages/client/ui-agent-preset/tests/components.client.spec.tsx、packages/client/ui-agent-preset/tests/section.client.spec.tsx、packages/client/ui-attachment/tests/attachment-rail.client.spec.tsx
  • 测试关联依据：固定提交源码中的本地静态 import 传递引用；这些测试通过包入口或中间模块到达本文件，不等于本文件被直接覆盖。
  • 阅读顺序：先读客户端运行时契约或呈现模型，再读当前界面文件，沿着 packages/client/ui-primitives/src/StateDot.tsx 确认状态如何进入 UI，最后对照 packages/client/locale/tests/apply.client.spec.ts、packages/client/locale/tests/language-row.client.spec.tsx、packages/client/ui-agent-preset/tests/apply.client.spec.ts。
  • 代码证据：固定提交归档实际读取结果：约 65 行；样式结构包含选择器 .dot、.matrix、.cell；自定义属性 --dsh-state-ongoing；源码顶部原注释（英文，仅作回查线索）：Ongoing blue has no alias token (state-business-primary is the 500 step, not this 450) — component-level var pinned to the static scale instead.。
  • 固定版本：源码链接固定到官方提交 aa6c361a972c8369148dea7380bb5c21c24e07ec。

packages/client/ui-primitives/src/StateDot.tsx ​

  • 所属层：packages/client：可复用的 Harness 功能包
  • 文件角色：界面组件或界面逻辑
  • 这个文件有什么用：它实现名为 StateDot 的界面组件或交互逻辑，并导出 StateDotState、StateDot，把输入、局部状态和用户操作组织成可渲染的 UI 单元；源码顶部还说明：StateDot: session state indicator (figma nodes 14:3303/3305/3312, 122:9182). done/warning/error: 10x10 halo (same color, 10% opacity) around a 6x6 solid core. ongoing: a pixel-art chase — the 8 outer cells of a 3x3 matrix light up clockwise with a stepped t...。
  • 为什么这样设计：固定提交的文件顶部注释把它定位为“StateDot: session state indicator (figma nodes 14:3303/3305/3312, 122:9182). done/warning/error: 10x10 halo (same color, 10% opacity) around a 6x6 solid core. ongoing: a pixel-art chase — the 8 outer cells of a 3x3 matrix light up clockwise with a stepped t...”；把这项职责单独放置，可以让边界、输入和失败处理在一个地方被阅读和测试。
  • 文件级设计证据：源码顶部注释把它定位为“StateDot: session state indicator (figma nodes 14:3303/3305/3312, 122:9182). done/warning/error: 10x10 halo (same color, 10% opacity) around a 6x6 solid core. ongoing: a pixel-art chase — the 8 outer cells of a 3x3 matrix light up clockwise with a stepped t...”；固定提交中扫描到的声明包括 StateDotState、StateDot；本地静态 import 图显示它直接依赖 1 个源文件，并被 2 个源文件直接引用。
  • 直接协作者：packages/client/ui-primitives/README.md、packages/client/ui-primitives/src/StateDot.module.css、packages/client/ui-primitives/src/TerminalBlock.tsx、packages/client/ui-primitives/src/index.ts
  • 对应测试：间接测试线索（通过本地 import 链，非直接覆盖）：packages/client/locale/tests/apply.client.spec.ts、packages/client/locale/tests/document-language.client.spec.ts、packages/client/locale/tests/invariant.client.spec.ts、packages/client/locale/tests/language-row.client.spec.tsx、packages/client/locale/tests/locale.client.spec.ts、packages/client/ui-agent-preset/tests/apply.client.spec.ts
  • 测试关联依据：固定提交源码中的本地静态 import 传递引用；这些测试通过包入口或中间模块到达本文件，不等于本文件被直接覆盖。
  • 阅读顺序：先读客户端运行时契约或呈现模型，再读当前界面文件，沿着 packages/client/ui-primitives/src/TerminalBlock.tsx、packages/client/ui-primitives/src/index.ts 确认状态如何进入 UI，最后对照 packages/client/locale/tests/apply.client.spec.ts、packages/client/locale/tests/document-language.client.spec.ts、packages/client/locale/tests/invariant.client.spec.ts。
  • 代码证据：固定提交归档实际读取结果：约 63 行；扫描到的声明包括 StateDotState、StateDot；源码顶部原注释（英文，仅作回查线索）：StateDot: session state indicator (figma nodes 14:3303/3305/3312, 122:9182). done/warning/error: 10x10 halo (same color, 10% opacity) around a 6x6 solid core. ongoing: a pixel-art chase — the 8 outer cells of a 3x3 matrix light up clockwise with a stepped t...。
  • 固定版本：源码链接固定到官方提交 aa6c361a972c8369148dea7380bb5c21c24e07ec。

packages/client/ui-primitives/src/TerminalBlock.module.css ​

  • 所属层：packages/client：可复用的 Harness 功能包
  • 文件角色：界面样式
  • 这个文件有什么用：它定义 TerminalBlock 的网页外观、布局和状态样式，让界面逻辑与视觉规则可以分别修改。
  • 为什么这样设计：把 TerminalBlock 的样式与业务流程分开，浏览器端可以调整外观而不改变服务端或 agent 的行为；组件只通过 class 和状态选择器使用它。
  • 文件级设计证据：源码顶部注释把它定位为“Geometry mirrors CodeBlock (12px radius, code-block surface + banner rows, markdown code-block font) so a terminal card and a fenced code block read as one family. The one deliberate divergence: output keeps white-space: pre and scrolls horizontally, becaus...”；固定提交中扫描到的结构线索是：样式结构包含选择器 .block、.header、.prompt、.promptLine、.runState、.runStateLabel；自定义属性 --dsl-terminal-radius、--dsl-terminal-line-height、--dsl-terminal-font、--dsl-terminal-gutter；本地静态 import 图显示它直接依赖 0 个源文件，并被 1 个源文件直接引用。
  • 直接协作者：packages/client/ui-primitives/README.md、packages/client/ui-primitives/src/TerminalBlock.tsx
  • 对应测试：间接测试线索（通过本地 import 链，非直接覆盖）：packages/client/locale/tests/apply.client.spec.ts、packages/client/locale/tests/language-row.client.spec.tsx、packages/client/ui-agent-preset/tests/apply.client.spec.ts、packages/client/ui-agent-preset/tests/components.client.spec.tsx、packages/client/ui-agent-preset/tests/section.client.spec.tsx、packages/client/ui-attachment/tests/attachment-rail.client.spec.tsx
  • 测试关联依据：固定提交源码中的本地静态 import 传递引用；这些测试通过包入口或中间模块到达本文件，不等于本文件被直接覆盖。
  • 阅读顺序：先读客户端运行时契约或呈现模型，再读当前界面文件，沿着 packages/client/ui-primitives/src/TerminalBlock.tsx 确认状态如何进入 UI，最后对照 packages/client/locale/tests/apply.client.spec.ts、packages/client/locale/tests/language-row.client.spec.tsx、packages/client/ui-agent-preset/tests/apply.client.spec.ts。
  • 代码证据：固定提交归档实际读取结果：约 211 行；样式结构包含选择器 .block、.header、.prompt、.promptLine、.runState、.runStateLabel；自定义属性 --dsl-terminal-radius、--dsl-terminal-line-height、--dsl-terminal-font、--dsl-terminal-gutter；源码顶部原注释（英文，仅作回查线索）：Geometry mirrors CodeBlock (12px radius, code-block surface + banner rows, markdown code-block font) so a terminal card and a fenced code block read as one family. The one deliberate divergence: output keeps white-space: pre and scrolls horizontally, becaus...。
  • 固定版本：源码链接固定到官方提交 aa6c361a972c8369148dea7380bb5c21c24e07ec。

packages/client/ui-primitives/src/TerminalBlock.tsx ​

  • 所属层：packages/client：可复用的 Harness 功能包
  • 文件角色：界面组件或界面逻辑
  • 这个文件有什么用：它实现名为 TerminalBlock 的界面组件或交互逻辑，并导出 DEFAULT_TERMINAL_MAX_LINES、TerminalBlockLabels、TerminalBlockProps，把输入、局部状态和用户操作组织成可渲染的 UI 单元；源码顶部还说明：TerminalBlock: the terminal surface for a shell command and its output — prompt line (run-state dot + shortened cwd + command), ANSI-colored output, settled exit status, and a copy control for the raw output. Output never soft-wraps: column-aligned output (...。
  • 为什么这样设计：固定提交的文件顶部注释把它定位为“TerminalBlock: the terminal surface for a shell command and its output — prompt line (run-state dot + shortened cwd + command), ANSI-colored output, settled exit status, and a copy control for the raw output. Output never soft-wraps: column-aligned output (...”；把这项职责单独放置，可以让边界、输入和失败处理在一个地方被阅读和测试。
  • 文件级设计证据：源码顶部注释把它定位为“TerminalBlock: the terminal surface for a shell command and its output — prompt line (run-state dot + shortened cwd + command), ANSI-colored output, settled exit status, and a copy control for the raw output. Output never soft-wraps: column-aligned output (...”；固定提交中扫描到的声明包括 DEFAULT_TERMINAL_MAX_LINES、TerminalBlockLabels、TerminalBlockProps、TerminalBlock、promptLabel；本地静态 import 图显示它直接依赖 6 个源文件，并被 1 个源文件直接引用。
  • 直接协作者：packages/client/ui-primitives/README.md、packages/client/ui-primitives/src/Pill.tsx、packages/client/ui-primitives/src/StateDot.tsx、packages/client/ui-primitives/src/TerminalBlock.module.css、packages/client/ui-primitives/src/index.ts
  • 对应测试：间接测试线索（通过本地 import 链，非直接覆盖）：packages/client/locale/tests/apply.client.spec.ts、packages/client/locale/tests/document-language.client.spec.ts、packages/client/locale/tests/invariant.client.spec.ts、packages/client/locale/tests/language-row.client.spec.tsx、packages/client/locale/tests/locale.client.spec.ts、packages/client/ui-agent-preset/tests/apply.client.spec.ts
  • 测试关联依据：固定提交源码中的本地静态 import 传递引用；这些测试通过包入口或中间模块到达本文件，不等于本文件被直接覆盖。
  • 阅读顺序：先读客户端运行时契约或呈现模型，再读当前界面文件，沿着 packages/client/ui-primitives/src/index.ts 确认状态如何进入 UI，最后对照 packages/client/locale/tests/apply.client.spec.ts、packages/client/locale/tests/document-language.client.spec.ts、packages/client/locale/tests/invariant.client.spec.ts。
  • 代码证据：固定提交归档实际读取结果：约 286 行；扫描到的声明包括 DEFAULT_TERMINAL_MAX_LINES、TerminalBlockLabels、TerminalBlockProps、TerminalBlock、promptLabel、statusText、runState、renderLine；源码顶部原注释（英文，仅作回查线索）：TerminalBlock: the terminal surface for a shell command and its output — prompt line (run-state dot + shortened cwd + command), ANSI-colored output, settled exit status, and a copy control for the raw output. Output never soft-wraps: column-aligned output (...。
  • 固定版本：源码链接固定到官方提交 aa6c361a972c8369148dea7380bb5c21c24e07ec。

packages/client/ui-primitives/src/Toast.module.css ​

  • 所属层：packages/client：可复用的 Harness 功能包
  • 文件角色：界面样式
  • 这个文件有什么用：它定义 Toast 的网页外观、布局和状态样式，让界面逻辑与视觉规则可以分别修改。
  • 为什么这样设计：把 Toast 的样式与业务流程分开，浏览器端可以调整外观而不改变服务端或 agent 的行为；组件只通过 class 和状态选择器使用它。
  • 文件级设计证据：源码顶部注释把它定位为“Transient top-center banner (DeepSeek Chat toast look): contrast fill, inverted label, slide-in, then hold-and-fade. The fade delay/duration MUST agree with HOLD_MS/FADE_MS in Toast.tsx: the component unmounts at their sum, so a mismatched sheet either cuts...”；固定提交中扫描到的结构线索是：样式结构包含选择器 .tsx、.toast、.icon、.text；本地静态 import 图显示它直接依赖 0 个源文件，并被 1 个源文件直接引用。
  • 直接协作者：packages/client/ui-primitives/README.md、packages/client/ui-primitives/src/Toast.tsx
  • 对应测试：间接测试线索（通过本地 import 链，非直接覆盖）：packages/client/locale/tests/apply.client.spec.ts、packages/client/locale/tests/language-row.client.spec.tsx、packages/client/ui-agent-preset/tests/apply.client.spec.ts、packages/client/ui-agent-preset/tests/components.client.spec.tsx、packages/client/ui-agent-preset/tests/section.client.spec.tsx、packages/client/ui-attachment/tests/attachment-rail.client.spec.tsx
  • 测试关联依据：固定提交源码中的本地静态 import 传递引用；这些测试通过包入口或中间模块到达本文件，不等于本文件被直接覆盖。
  • 阅读顺序：先读客户端运行时契约或呈现模型，再读当前界面文件，沿着 packages/client/ui-primitives/src/Toast.tsx 确认状态如何进入 UI，最后对照 packages/client/locale/tests/apply.client.spec.ts、packages/client/locale/tests/language-row.client.spec.tsx、packages/client/ui-agent-preset/tests/apply.client.spec.ts。
  • 代码证据：固定提交归档实际读取结果：约 70 行；样式结构包含选择器 .tsx、.toast、.icon、.text；源码顶部原注释（英文，仅作回查线索）：Transient top-center banner (DeepSeek Chat toast look): contrast fill, inverted label, slide-in, then hold-and-fade. The fade delay/duration MUST agree with HOLD_MS/FADE_MS in Toast.tsx: the component unmounts at their sum, so a mismatched sheet either cuts...。
  • 固定版本：源码链接固定到官方提交 aa6c361a972c8369148dea7380bb5c21c24e07ec。

packages/client/ui-primitives/src/Toast.tsx ​

  • 所属层：packages/client：可复用的 Harness 功能包
  • 文件角色：界面组件或界面逻辑
  • 这个文件有什么用：它实现名为 Toast 的界面组件或交互逻辑，并导出 Toast，把输入、局部状态和用户操作组织成可渲染的 UI 单元。
  • 为什么这样设计：固定提交中扫描到的声明包括 Toast；把这些相互关联的声明集中在同一文件，可以让输入、输出和修改边界更容易一起检查。
  • 文件级设计证据：固定提交中扫描到的声明包括 Toast；本地静态 import 图显示它直接依赖 1 个源文件，并被 2 个源文件直接引用。
  • 直接协作者：packages/client/ui-primitives/README.md、packages/client/ui-primitives/src/Toast.module.css、packages/client/ui-primitives/src/index.ts、packages/client/ui-primitives/tests/toast.client.spec.tsx
  • 对应测试：packages/client/ui-primitives/tests/toast.client.spec.tsx
  • 测试关联依据：固定提交源码中的本地静态 import 直接引用；测试用例直接导入了这个源文件。
  • 阅读顺序：先读客户端运行时契约或呈现模型，再读当前界面文件，沿着 packages/client/ui-primitives/src/index.ts、packages/client/ui-primitives/tests/toast.client.spec.tsx 确认状态如何进入 UI，最后对照 packages/client/ui-primitives/tests/toast.client.spec.tsx。
  • 代码证据：固定提交归档实际读取结果：约 59 行；扫描到的声明包括 Toast。
  • 固定版本：源码链接固定到官方提交 aa6c361a972c8369148dea7380bb5c21c24e07ec。

packages/client/ui-primitives/src/Tooltip.module.css ​

  • 所属层：packages/client：可复用的 Harness 功能包
  • 文件角色：界面样式
  • 这个文件有什么用：它定义 Tooltip 的网页外观、布局和状态样式，让界面逻辑与视觉规则可以分别修改。
  • 为什么这样设计：把 Tooltip 的样式与业务流程分开，浏览器端可以调整外观而不改变服务端或 agent 的行为；组件只通过 class 和状态选择器使用它。
  • 文件级设计证据：源码顶部注释把它定位为“Visual spec mirrors deepsuite @deepseek/ui Tooltip.css (size m, no arrow), except padding tightened 6/12 -> 3/7, type 14/22 -> 13/20, radius 10 -> 8, a tooltip-bg plate, one text color across both themes (the plate stays dark in light and dark mode). Behavi...”；固定提交中扫描到的结构线索是：样式结构包含选择器 .bubble；本地静态 import 图显示它直接依赖 0 个源文件，并被 1 个源文件直接引用。
  • 直接协作者：packages/client/ui-primitives/README.md、packages/client/ui-primitives/src/Tooltip.tsx
  • 对应测试：间接测试线索（通过本地 import 链，非直接覆盖）：packages/client/locale/tests/apply.client.spec.ts、packages/client/locale/tests/language-row.client.spec.tsx、packages/client/ui-agent-preset/tests/apply.client.spec.ts、packages/client/ui-agent-preset/tests/components.client.spec.tsx、packages/client/ui-agent-preset/tests/section.client.spec.tsx、packages/client/ui-attachment/tests/attachment-rail.client.spec.tsx
  • 测试关联依据：固定提交源码中的本地静态 import 传递引用；这些测试通过包入口或中间模块到达本文件，不等于本文件被直接覆盖。
  • 阅读顺序：先读客户端运行时契约或呈现模型，再读当前界面文件，沿着 packages/client/ui-primitives/src/Tooltip.tsx 确认状态如何进入 UI，最后对照 packages/client/locale/tests/apply.client.spec.ts、packages/client/locale/tests/language-row.client.spec.tsx、packages/client/ui-agent-preset/tests/apply.client.spec.ts。
  • 代码证据：固定提交归档实际读取结果：约 49 行；样式结构包含选择器 .bubble；源码顶部原注释（英文，仅作回查线索）：Visual spec mirrors deepsuite @deepseek/ui Tooltip.css (size m, no arrow), except padding tightened 6/12 -> 3/7, type 14/22 -> 13/20, radius 10 -> 8, a tooltip-bg plate, one text color across both themes (the plate stays dark in light and dark mode). Behavi...。
  • 固定版本：源码链接固定到官方提交 aa6c361a972c8369148dea7380bb5c21c24e07ec。

packages/client/ui-primitives/src/Tooltip.tsx ​

  • 所属层：packages/client：可复用的 Harness 功能包
  • 文件角色：界面组件或界面逻辑
  • 这个文件有什么用：它实现名为 Tooltip 的界面组件或交互逻辑，并导出 TooltipSide、Tooltip，把输入、局部状态和用户操作组织成可渲染的 UI 单元；源码顶部还说明：Hover/focus label bubble (figma tooltip pill: dark plate, white text). TODO: interaction is a placeholder (horizontal overflow clamps and a vertical collision flips the bubble to the other side, but there is no arrow) — visuals and behavior get a proper pas...。
  • 为什么这样设计：固定提交的文件顶部注释把它定位为“Hover/focus label bubble (figma tooltip pill: dark plate, white text). TODO: interaction is a placeholder (horizontal overflow clamps and a vertical collision flips the bubble to the other side, but there is no arrow) — visuals and behavior get a proper pas...”；把这项职责单独放置，可以让边界、输入和失败处理在一个地方被阅读和测试。
  • 文件级设计证据：源码顶部注释把它定位为“Hover/focus label bubble (figma tooltip pill: dark plate, white text). TODO: interaction is a placeholder (horizontal overflow clamps and a vertical collision flips the bubble to the other side, but there is no arrow) — visuals and behavior get a proper pas...”；固定提交中扫描到的声明包括 TooltipSide、Tooltip；本地静态 import 图显示它直接依赖 1 个源文件，并被 1 个源文件直接引用。
  • 直接协作者：packages/client/ui-primitives/README.md、packages/client/ui-primitives/src/Tooltip.module.css、packages/client/ui-primitives/src/index.ts
  • 对应测试：间接测试线索（通过本地 import 链，非直接覆盖）：packages/client/locale/tests/apply.client.spec.ts、packages/client/locale/tests/document-language.client.spec.ts、packages/client/locale/tests/invariant.client.spec.ts、packages/client/locale/tests/language-row.client.spec.tsx、packages/client/locale/tests/locale.client.spec.ts、packages/client/ui-agent-preset/tests/apply.client.spec.ts
  • 测试关联依据：固定提交源码中的本地静态 import 传递引用；这些测试通过包入口或中间模块到达本文件，不等于本文件被直接覆盖。
  • 阅读顺序：先读客户端运行时契约或呈现模型，再读当前界面文件，沿着 packages/client/ui-primitives/src/index.ts 确认状态如何进入 UI，最后对照 packages/client/locale/tests/apply.client.spec.ts、packages/client/locale/tests/document-language.client.spec.ts、packages/client/locale/tests/invariant.client.spec.ts。
  • 代码证据：固定提交归档实际读取结果：约 168 行；扫描到的声明包括 TooltipSide、Tooltip；源码顶部原注释（英文，仅作回查线索）：Hover/focus label bubble (figma tooltip pill: dark plate, white text). TODO: interaction is a placeholder (horizontal overflow clamps and a vertical collision flips the bubble to the other side, but there is no arrow) — visuals and behavior get a proper pas...。
  • 固定版本：源码链接固定到官方提交 aa6c361a972c8369148dea7380bb5c21c24e07ec。

packages/client/ui-primitives/src/WebBlock.module.css ​

  • 所属层：packages/client：可复用的 Harness 功能包
  • 文件角色：界面样式
  • 这个文件有什么用：它定义 WebBlock 的网页外观、布局和状态样式，让界面逻辑与视觉规则可以分别修改。
  • 为什么这样设计：把 WebBlock 的样式与业务流程分开，浏览器端可以调整外观而不改变服务端或 agent 的行为；组件只通过 class 和状态选择器使用它。
  • 文件级设计证据：源码顶部注释把它定位为“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 each row wraps horizontally rather th...”；固定提交中扫描到的结构线索是：样式结构包含选择器 .block、.answer、.sources、.source、.sourceLink、.snippet；自定义属性 --dsl-web-radius；本地静态 import 图显示它直接依赖 0 个源文件，并被 1 个源文件直接引用。
  • 直接协作者：packages/client/ui-primitives/README.md、packages/client/ui-primitives/src/WebBlock.tsx
  • 对应测试：间接测试线索（通过本地 import 链，非直接覆盖）：packages/client/locale/tests/apply.client.spec.ts、packages/client/locale/tests/language-row.client.spec.tsx、packages/client/ui-agent-preset/tests/apply.client.spec.ts、packages/client/ui-agent-preset/tests/components.client.spec.tsx、packages/client/ui-agent-preset/tests/section.client.spec.tsx、packages/client/ui-attachment/tests/attachment-rail.client.spec.tsx
  • 测试关联依据：固定提交源码中的本地静态 import 传递引用；这些测试通过包入口或中间模块到达本文件，不等于本文件被直接覆盖。
  • 阅读顺序：先读客户端运行时契约或呈现模型，再读当前界面文件，沿着 packages/client/ui-primitives/src/WebBlock.tsx 确认状态如何进入 UI，最后对照 packages/client/locale/tests/apply.client.spec.ts、packages/client/locale/tests/language-row.client.spec.tsx、packages/client/ui-agent-preset/tests/apply.client.spec.ts。
  • 代码证据：固定提交归档实际读取结果：约 130 行；样式结构包含选择器 .block、.answer、.sources、.source、.sourceLink、.snippet；自定义属性 --dsl-web-radius；源码顶部原注释（英文，仅作回查线索）：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 each row wraps horizontally rather th...。
  • 固定版本：源码链接固定到官方提交 aa6c361a972c8369148dea7380bb5c21c24e07ec。

packages/client/ui-primitives/src/WebBlock.tsx ​

  • 所属层：packages/client：可复用的 Harness 功能包
  • 文件角色：界面组件或界面逻辑
  • 这个文件有什么用：它实现名为 WebBlock 的界面组件或交互逻辑，并导出 WebSourceView、WebSearchBlockProps、WebFetchBlockProps，把输入、局部状态和用户操作组织成可渲染的 UI 单元；源码顶部还说明：WebBlock: the surface for a completed web retrieval. One component draws both kinds of the web render intent, discriminated by kind: a search shows an optional provider answer above a citation list of sources (each a safe external link labelled by its title...。
  • 为什么这样设计：固定提交的文件顶部注释把它定位为“WebBlock: the surface for a completed web retrieval. One component draws both kinds of the web render intent, discriminated by kind: a search shows an optional provider answer above a citation list of sources (each a safe external link labelled by its title...”；把这项职责单独放置，可以让边界、输入和失败处理在一个地方被阅读和测试。
  • 文件级设计证据：源码顶部注释把它定位为“WebBlock: the surface for a completed web retrieval. One component draws both kinds of the web render intent, discriminated by kind: a search shows an optional provider answer above a citation list of sources (each a safe external link labelled by its title...”；固定提交中扫描到的声明包括 WebSourceView、WebSearchBlockProps、WebFetchBlockProps、WebBlockProps、WebBlock；本地静态 import 图显示它直接依赖 2 个源文件，并被 1 个源文件直接引用。
  • 直接协作者：packages/client/ui-primitives/README.md、packages/client/ui-primitives/src/WebBlock.module.css、packages/client/ui-primitives/src/markdown/MarkdownText.tsx、packages/client/ui-primitives/src/index.ts
  • 对应测试：间接测试线索（通过本地 import 链，非直接覆盖）：packages/client/locale/tests/apply.client.spec.ts、packages/client/locale/tests/document-language.client.spec.ts、packages/client/locale/tests/invariant.client.spec.ts、packages/client/locale/tests/language-row.client.spec.tsx、packages/client/locale/tests/locale.client.spec.ts、packages/client/ui-agent-preset/tests/apply.client.spec.ts
  • 测试关联依据：固定提交源码中的本地静态 import 传递引用；这些测试通过包入口或中间模块到达本文件，不等于本文件被直接覆盖。
  • 阅读顺序：先读客户端运行时契约或呈现模型，再读当前界面文件，沿着 packages/client/ui-primitives/src/index.ts 确认状态如何进入 UI，最后对照 packages/client/locale/tests/apply.client.spec.ts、packages/client/locale/tests/document-language.client.spec.ts、packages/client/locale/tests/invariant.client.spec.ts。
  • 代码证据：固定提交归档实际读取结果：约 202 行；扫描到的声明包括 WebSourceView、WebSearchBlockProps、WebFetchBlockProps、WebBlockProps、WebBlock、safeHref、linkLabel、SafeLink；源码顶部原注释（英文，仅作回查线索）：WebBlock: the surface for a completed web retrieval. One component draws both kinds of the web render intent, discriminated by kind: a search shows an optional provider answer above a citation list of sources (each a safe external link labelled by its title...。
  • 固定版本：源码链接固定到官方提交 aa6c361a972c8369148dea7380bb5c21c24e07ec。

packages/client/ui-primitives/src/ansi.ts ​

  • 所属层：packages/client：可复用的 Harness 功能包
  • 文件角色：界面交互逻辑
  • 这个文件有什么用：这个文件属于一个界面功能包，负责用户操作、视图状态或 UI 适配；它把浏览器体验接到稳定的运行时契约上。
  • 为什么这样设计：把用户操作和视图状态放在界面包内，能让 Web 组件复用同一套交互契约，也让服务端和领域逻辑不被浏览器细节污染。
  • 文件级设计证据：源码顶部注释把它定位为“ANSI model behind TerminalBlock: anser splits the SGR runs, this module resolves each run's colors and decorations into a plain style record and folds the runs into per-line span arrays so a height cap can slice whole lines. Sequences anser does not turn in...”；固定提交中扫描到的声明包括 AnsiSpan、AnsiLine、parseAnsiLines、isWide、foldSgr；本地静态 import 图显示它直接依赖 0 个源文件，并被 2 个源文件直接引用。
  • 直接协作者：packages/client/ui-primitives/README.md、packages/client/ui-primitives/src/TerminalBlock.tsx、packages/client/ui-primitives/tests/ansi.client.spec.ts
  • 对应测试：packages/client/ui-primitives/tests/ansi.client.spec.ts
  • 测试关联依据：固定提交源码中的本地静态 import 直接引用；测试用例直接导入了这个源文件。
  • 阅读顺序：先读客户端运行时契约或呈现模型，再读当前界面文件，沿着 packages/client/ui-primitives/src/TerminalBlock.tsx、packages/client/ui-primitives/tests/ansi.client.spec.ts 确认状态如何进入 UI，最后对照 packages/client/ui-primitives/tests/ansi.client.spec.ts。
  • 代码证据：固定提交归档实际读取结果：约 447 行；扫描到的声明包括 AnsiSpan、AnsiLine、parseAnsiLines、isWide、foldSgr、openSgr、sameSgr、replayLine；源码顶部原注释（英文，仅作回查线索）：ANSI model behind TerminalBlock: anser splits the SGR runs, this module resolves each run's colors and decorations into a plain style record and folds the runs into per-line span arrays so a height cap can slice whole lines. Sequences anser does not turn in...。
  • 固定版本：源码链接固定到官方提交 aa6c361a972c8369148dea7380bb5c21c24e07ec。

packages/client/ui-primitives/src/clipboard.ts ​

  • 所属层：packages/client：可复用的 Harness 功能包
  • 文件角色：界面交互逻辑
  • 这个文件有什么用：这个文件属于一个界面功能包，负责用户操作、视图状态或 UI 适配；它把浏览器体验接到稳定的运行时契约上。
  • 为什么这样设计：把用户操作和视图状态放在界面包内，能让 Web 组件复用同一套交互契约，也让服务端和领域逻辑不被浏览器细节污染。
  • 文件级设计证据：源码顶部注释把它定位为“Host clipboard write shared by Web UI copy controls. Success feedback stays with each control; this helper only reports whether the host accepted a write.”；固定提交中扫描到的声明包括 writeClipboard；本地静态 import 图显示它直接依赖 0 个源文件，并被 7 个源文件直接引用。
  • 直接协作者：packages/client/ui-primitives/README.md、packages/client/ui-primitives/src/DiffBlock.tsx、packages/client/ui-primitives/src/HoverCard.tsx、packages/client/ui-primitives/src/ReadBlock.tsx
  • 对应测试：packages/client/ui-primitives/tests/terminal-block.client.spec.tsx
  • 测试关联依据：固定提交源码中的本地静态 import 直接引用；测试用例直接导入了这个源文件。
  • 阅读顺序：先读客户端运行时契约或呈现模型，再读当前界面文件，沿着 packages/client/ui-primitives/src/DiffBlock.tsx、packages/client/ui-primitives/src/HoverCard.tsx、packages/client/ui-primitives/src/ReadBlock.tsx 确认状态如何进入 UI，最后对照 packages/client/ui-primitives/tests/terminal-block.client.spec.tsx。
  • 代码证据：固定提交归档实际读取结果：约 47 行；扫描到的声明包括 writeClipboard；源码顶部原注释（英文，仅作回查线索）：Host clipboard write shared by Web UI copy controls. Success feedback stays with each control; this helper only reports whether the host accepted a write.。
  • 固定版本：源码链接固定到官方提交 aa6c361a972c8369148dea7380bb5c21c24e07ec。

packages/client/ui-primitives/src/css-modules.d.ts ​

  • 所属层：packages/client：可复用的 Harness 功能包
  • 文件角色：类型声明
  • 这个文件有什么用：这个文件补充运行时库或构建工具的类型声明，让调用者在编译期知道可用字段、参数和返回值，而不改变运行时行为。
  • 为什么这样设计：它位于 packages/client/ui-primitives/src的类型声明层；固定提交没有解析到本地依赖或顶层声明，因此先把它作为独立边界阅读，再回到源码确认具体实现。
  • 文件级设计证据：本次固定提交归档没有扫描到顶部注释、顶层声明或专门的结构线索；本地静态 import 图显示它直接依赖 0 个源文件，并被 0 个源文件直接引用。
  • 直接协作者：packages/client/ui-primitives/README.md
  • 对应测试：没有确认到直接测试；公共入口可能仍有间接覆盖。
  • 测试关联依据：固定提交中没有找到直接或传递的本地静态 import，也没有找到明显的同包同名测试；公共入口可能仍有间接覆盖。
  • 阅读顺序：先读 packages/client/ui-primitives/README.md、入口和消费者，再读当前契约，沿着所在包的入口或服务看它怎样约束运行时，最后对照同包中与它同名或覆盖相近场景的测试。
  • 代码证据：固定提交归档实际读取结果：约 6 行。
  • 固定版本：源码链接固定到官方提交 aa6c361a972c8369148dea7380bb5c21c24e07ec。

packages/client/ui-primitives/src/head-tail-cap.ts ​

  • 所属层：packages/client：可复用的 Harness 功能包
  • 文件角色：界面交互逻辑
  • 这个文件有什么用：这个文件属于一个界面功能包，负责用户操作、视图状态或 UI 适配；它把浏览器体验接到稳定的运行时契约上。
  • 为什么这样设计：把用户操作和视图状态放在界面包内，能让 Web 组件复用同一套交互契约，也让服务端和领域逻辑不被浏览器细节污染。
  • 文件级设计证据：源码顶部注释把它定位为“Head/tail height-cap arithmetic shared by the block primitives (TerminalBlock, SearchBlock), so long results use consistent head and tail slices. The split is ceil(maxLines / 2) head rows and the remainder as tail rows; a result within the cap shows every r...”；固定提交中扫描到的声明包括 HeadTailCap、headTailCap；本地静态 import 图显示它直接依赖 0 个源文件，并被 2 个源文件直接引用。
  • 直接协作者：packages/client/ui-primitives/README.md、packages/client/ui-primitives/src/SearchBlock.tsx、packages/client/ui-primitives/src/TerminalBlock.tsx
  • 对应测试：间接测试线索（通过本地 import 链，非直接覆盖）：packages/client/locale/tests/apply.client.spec.ts、packages/client/locale/tests/language-row.client.spec.tsx、packages/client/ui-agent-preset/tests/apply.client.spec.ts、packages/client/ui-agent-preset/tests/components.client.spec.tsx、packages/client/ui-agent-preset/tests/section.client.spec.tsx、packages/client/ui-attachment/tests/attachment-rail.client.spec.tsx
  • 测试关联依据：固定提交源码中的本地静态 import 传递引用；这些测试通过包入口或中间模块到达本文件，不等于本文件被直接覆盖。
  • 阅读顺序：先读客户端运行时契约或呈现模型，再读当前界面文件，沿着 packages/client/ui-primitives/src/SearchBlock.tsx、packages/client/ui-primitives/src/TerminalBlock.tsx 确认状态如何进入 UI，最后对照 packages/client/locale/tests/apply.client.spec.ts、packages/client/locale/tests/language-row.client.spec.tsx、packages/client/ui-agent-preset/tests/apply.client.spec.ts。
  • 代码证据：固定提交归档实际读取结果：约 32 行；扫描到的声明包括 HeadTailCap、headTailCap；源码顶部原注释（英文，仅作回查线索）：Head/tail height-cap arithmetic shared by the block primitives (TerminalBlock, SearchBlock), so long results use consistent head and tail slices. The split is ceil(maxLines / 2) head rows and the remainder as tail rows; a result within the cap shows every r...。
  • 固定版本：源码链接固定到官方提交 aa6c361a972c8369148dea7380bb5c21c24e07ec。

packages/client/ui-primitives/src/icons/index.tsx ​

  • 所属层：packages/client：可复用的 Harness 功能包
  • 文件角色：模块入口
  • 这个文件有什么用：它把浏览器端、用户界面相关的公开能力集中导出，并决定调用者可以依赖哪些边界；调用者因此不必记住所有内部文件。
  • 为什么这样设计：入口文件把公开边界固定下来，内部文件可以继续拆分或替换；其他包只依赖入口暴露的 API，依赖方向更稳定。
  • 文件级设计证据：源码顶部注释把它定位为“ic_ds_* icon set for the dsh web UI. All glyphs render fill="currentColor" and take {size, className}. Batch A mirrors the deepsuite icon library (same figma source); batch B glyphs are harness-only figma extracts.”；固定提交中扫描到的声明包括 IconNewChatOutline16、IconSearchOutline16、IconGlobeOutline14、IconSettingsOutline14、IconSettingsOutline16；本地静态 import 图显示它直接依赖 1 个源文件，并被 6 个源文件直接引用。
  • 直接协作者：packages/client/ui-primitives/README.md、packages/client/ui-primitives/src/icons/props.ts、packages/client/ui-primitives/src/DisclosureRow.tsx、packages/client/ui-primitives/src/JsonTree.tsx、packages/client/ui-primitives/src/Menu.tsx
  • 对应测试：间接测试线索（通过本地 import 链，非直接覆盖）：packages/client/locale/tests/apply.client.spec.ts、packages/client/locale/tests/document-language.client.spec.ts、packages/client/locale/tests/invariant.client.spec.ts、packages/client/locale/tests/language-row.client.spec.tsx、packages/client/locale/tests/locale.client.spec.ts、packages/client/ui-agent-preset/tests/apply.client.spec.ts
  • 测试关联依据：固定提交源码中的本地静态 import 传递引用；这些测试通过包入口或中间模块到达本文件，不等于本文件被直接覆盖。
  • 阅读顺序：先读 packages/client/ui-primitives/README.md、入口和消费者，再读当前契约，沿着 packages/client/ui-primitives/src/DisclosureRow.tsx、packages/client/ui-primitives/src/JsonTree.tsx、packages/client/ui-primitives/src/Menu.tsx 看它怎样约束运行时，最后对照 packages/client/locale/tests/apply.client.spec.ts、packages/client/locale/tests/document-language.client.spec.ts、packages/client/locale/tests/invariant.client.spec.ts。
  • 代码证据：固定提交归档实际读取结果：约 872 行；扫描到的声明包括 IconNewChatOutline16、IconSearchOutline16、IconGlobeOutline14、IconSettingsOutline14、IconSettingsOutline16、IconPanelLeftOutline16、IconEllipsisOutline16、IconPlusOutline16；源码顶部原注释（英文，仅作回查线索）：ic_ds_* icon set for the dsh web UI. All glyphs render fill="currentColor" and take {size, className}. Batch A mirrors the deepsuite icon library (same figma source); batch B glyphs are harness-only figma extracts.。
  • 固定版本：源码链接固定到官方提交 aa6c361a972c8369148dea7380bb5c21c24e07ec。

packages/client/ui-primitives/src/icons/props.ts ​

packages/client/ui-primitives/src/index.ts ​

packages/client/ui-primitives/src/invariant.ts ​

  • 所属层：packages/client：可复用的 Harness 功能包
  • 文件角色：运行时不变量
  • 这个文件有什么用：它检查浏览器端、用户界面必须始终成立的条件，在错误刚出现时报告，而不是等到更深层才出现难以解释的结果。
  • 为什么这样设计：把不变量集中在一个位置，调用者和测试就能用同一条规则检查状态；错误在边界处报告，比在后续 UI 或网络请求中才暴露更容易修复。
  • 文件级设计证据：源码顶部注释把它定位为“Package-owned invariant companion for @deepseek-ai/dsh-client-ui-primitives. @module @deepseek-ai/dsh-client-ui-primitives/invariant”；固定提交中扫描到的声明包括 name、inject、apply；本地静态 import 图显示它直接依赖 2 个源文件，并被 1 个源文件直接引用。
  • 直接协作者：packages/client/ui-primitives/README.md、packages/runtime-diagnostics/invariants/src/index.ts、vendor/cordis/src/index.ts、packages/client/ui-primitives/tests/invariant.client.spec.ts
  • 对应测试：packages/client/ui-primitives/tests/invariant.client.spec.ts
  • 测试关联依据：固定提交源码中的本地静态 import 直接引用；测试用例直接导入了这个源文件。
  • 阅读顺序：先读相关类型和事件，再读当前状态或存储实现，沿着 packages/runtime-diagnostics/invariants/src/index.ts、vendor/cordis/src/index.ts 和 packages/client/ui-primitives/tests/invariant.client.spec.ts 理解状态变化，最后对照 packages/client/ui-primitives/tests/invariant.client.spec.ts。
  • 代码证据：固定提交归档实际读取结果：约 31 行；扫描到的声明包括 name、inject、apply；源码顶部原注释（英文，仅作回查线索）：Package-owned invariant companion for @deepseek-ai/dsh-client-ui-primitives. @module @deepseek-ai/dsh-client-ui-primitives/invariant。
  • 固定版本：源码链接固定到官方提交 aa6c361a972c8369148dea7380bb5c21c24e07ec。

packages/client/ui-primitives/src/markdown/CodeBlock.module.css ​

  • 所属层：packages/client：可复用的 Harness 功能包
  • 文件角色：界面样式
  • 这个文件有什么用：它定义 CodeBlock 的网页外观、布局和状态样式，让界面逻辑与视觉规则可以分别修改。
  • 为什么这样设计：把 CodeBlock 的样式与业务流程分开，浏览器端可以调整外观而不改变服务端或 agent 的行为；组件只通过 class 和状态选择器使用它。
  • 文件级设计证据：源码顶部注释把它定位为“Visual baseline: deepsuite @deepseek/md code-block.css. Highlight colors stay on the existing shiki --shiki-* sheet (not Prism highlight.css).”；固定提交中扫描到的结构线索是：样式结构包含选择器 .block、.bannerWrap、.banner、.infostring、.action、.copyButton；自定义属性 --dsl-code-block-banner-background-color、--dsl-code-block-border-radius、--dsl-code-block-banner-font、--dsl-code-block-content-font；本地静态 import 图显示它直接依赖 0 个源文件，并被 1 个源文件直接引用。
  • 直接协作者：packages/client/ui-primitives/README.md、packages/client/ui-primitives/src/markdown/CodeBlock.tsx
  • 对应测试：间接测试线索（通过本地 import 链，非直接覆盖）：packages/client/locale/tests/apply.client.spec.ts、packages/client/locale/tests/language-row.client.spec.tsx、packages/client/ui-agent-preset/tests/apply.client.spec.ts、packages/client/ui-agent-preset/tests/components.client.spec.tsx、packages/client/ui-agent-preset/tests/section.client.spec.tsx、packages/client/ui-attachment/tests/attachment-rail.client.spec.tsx
  • 测试关联依据：固定提交源码中的本地静态 import 传递引用；这些测试通过包入口或中间模块到达本文件，不等于本文件被直接覆盖。
  • 阅读顺序：先读客户端运行时契约或呈现模型，再读当前界面文件，沿着 packages/client/ui-primitives/src/markdown/CodeBlock.tsx 确认状态如何进入 UI，最后对照 packages/client/locale/tests/apply.client.spec.ts、packages/client/locale/tests/language-row.client.spec.tsx、packages/client/ui-agent-preset/tests/apply.client.spec.ts。
  • 代码证据：固定提交归档实际读取结果：约 96 行；样式结构包含选择器 .block、.bannerWrap、.banner、.infostring、.action、.copyButton；自定义属性 --dsl-code-block-banner-background-color、--dsl-code-block-border-radius、--dsl-code-block-banner-font、--dsl-code-block-content-font；源码顶部原注释（英文，仅作回查线索）：Visual baseline: deepsuite @deepseek/md code-block.css. Highlight colors stay on the existing shiki --shiki-* sheet (not Prism highlight.css).。
  • 固定版本：源码链接固定到官方提交 aa6c361a972c8369148dea7380bb5c21c24e07ec。

packages/client/ui-primitives/src/markdown/CodeBlock.tsx ​

  • 所属层：packages/client：可复用的 Harness 功能包
  • 文件角色：界面组件或界面逻辑
  • 这个文件有什么用：它实现名为 CodeBlock 的界面组件或交互逻辑，并导出 CodeBlockProps、CodeBlock，把输入、局部状态和用户操作组织成可渲染的 UI 单元；源码顶部还说明：CodeBlock: one code surface for every consumer — markdown fences, the run_code program body, and the details panel's raw args/output — with shiki highlighting for the registered grammars and an identical-geometry plain fallback for everything else. Chrome (...。
  • 为什么这样设计：固定提交的文件顶部注释把它定位为“CodeBlock: one code surface for every consumer — markdown fences, the run_code program body, and the details panel's raw args/output — with shiki highlighting for the registered grammars and an identical-geometry plain fallback for everything else. Chrome (...”；把这项职责单独放置，可以让边界、输入和失败处理在一个地方被阅读和测试。
  • 文件级设计证据：源码顶部注释把它定位为“CodeBlock: one code surface for every consumer — markdown fences, the run_code program body, and the details panel's raw args/output — with shiki highlighting for the registered grammars and an identical-geometry plain fallback for everything else. Chrome (...”；固定提交中扫描到的声明包括 CodeBlockProps、CodeBlock；本地静态 import 图显示它直接依赖 3 个源文件，并被 3 个源文件直接引用。
  • 直接协作者：packages/client/ui-primitives/README.md、packages/client/ui-primitives/src/clipboard.ts、packages/client/ui-primitives/src/markdown/CodeBlock.module.css、packages/client/ui-primitives/src/markdown/highlight.ts、packages/client/ui-primitives/src/index.ts
  • 对应测试：packages/client/ui-primitives/tests/code-block.client.spec.tsx
  • 测试关联依据：固定提交源码中的本地静态 import 直接引用；测试用例直接导入了这个源文件。
  • 阅读顺序：先读客户端运行时契约或呈现模型，再读当前界面文件，沿着 packages/client/ui-primitives/src/index.ts、packages/client/ui-primitives/src/markdown/render.tsx、packages/client/ui-primitives/tests/code-block.client.spec.tsx 确认状态如何进入 UI，最后对照 packages/client/ui-primitives/tests/code-block.client.spec.tsx。
  • 代码证据：固定提交归档实际读取结果：约 74 行；扫描到的声明包括 CodeBlockProps、CodeBlock；源码顶部原注释（英文，仅作回查线索）：CodeBlock: one code surface for every consumer — markdown fences, the run_code program body, and the details panel's raw args/output — with shiki highlighting for the registered grammars and an identical-geometry plain fallback for everything else. Chrome (...。
  • 固定版本：源码链接固定到官方提交 aa6c361a972c8369148dea7380bb5c21c24e07ec。

packages/client/ui-primitives/src/markdown/JsonBlock.module.css ​

packages/client/ui-primitives/src/markdown/JsonBlock.tsx ​

  • 所属层：packages/client：可复用的 Harness 功能包
  • 文件角色：界面组件或界面逻辑
  • 这个文件有什么用：它实现名为 JsonBlock 的界面组件或交互逻辑，并导出 JsonBlock、defaultTruncatedLabel，把输入、局部状态和用户操作组织成可渲染的 UI 单元；源码顶部还说明：JsonBlock: collapsible JSON block (conversation side; independent from the RPC panel's PayloadJson to avoid cross-panel coupling).。
  • 为什么这样设计：固定提交的文件顶部注释把它定位为“JsonBlock: collapsible JSON block (conversation side; independent from the RPC panel's PayloadJson to avoid cross-panel coupling).”；把这项职责单独放置，可以让边界、输入和失败处理在一个地方被阅读和测试。
  • 文件级设计证据：源码顶部注释把它定位为“JsonBlock: collapsible JSON block (conversation side; independent from the RPC panel's PayloadJson to avoid cross-panel coupling).”；固定提交中扫描到的声明包括 JsonBlock、defaultTruncatedLabel；本地静态 import 图显示它直接依赖 1 个源文件，并被 1 个源文件直接引用。
  • 直接协作者：packages/client/ui-primitives/README.md、packages/client/ui-primitives/src/markdown/JsonBlock.module.css、packages/client/ui-primitives/src/index.ts
  • 对应测试：间接测试线索（通过本地 import 链，非直接覆盖）：packages/client/locale/tests/apply.client.spec.ts、packages/client/locale/tests/document-language.client.spec.ts、packages/client/locale/tests/invariant.client.spec.ts、packages/client/locale/tests/language-row.client.spec.tsx、packages/client/locale/tests/locale.client.spec.ts、packages/client/ui-agent-preset/tests/apply.client.spec.ts
  • 测试关联依据：固定提交源码中的本地静态 import 传递引用；这些测试通过包入口或中间模块到达本文件，不等于本文件被直接覆盖。
  • 阅读顺序：先读客户端运行时契约或呈现模型，再读当前界面文件，沿着 packages/client/ui-primitives/src/index.ts 确认状态如何进入 UI，最后对照 packages/client/locale/tests/apply.client.spec.ts、packages/client/locale/tests/document-language.client.spec.ts、packages/client/locale/tests/invariant.client.spec.ts。
  • 代码证据：固定提交归档实际读取结果：约 41 行；扫描到的声明包括 JsonBlock、defaultTruncatedLabel；源码顶部原注释（英文，仅作回查线索）：JsonBlock: collapsible JSON block (conversation side; independent from the RPC panel's PayloadJson to avoid cross-panel coupling).。
  • 固定版本：源码链接固定到官方提交 aa6c361a972c8369148dea7380bb5c21c24e07ec。

packages/client/ui-primitives/src/markdown/MarkdownText.module.css ​

  • 所属层：packages/client：可复用的 Harness 功能包
  • 文件角色：界面样式
  • 这个文件有什么用：它定义 MarkdownText 的网页外观、布局和状态样式，让界面逻辑与视觉规则可以分别修改。
  • 为什么这样设计：把 MarkdownText 的样式与业务流程分开，浏览器端可以调整外观而不改变服务端或 agent 的行为；组件只通过 class 和状态选择器使用它。
  • 文件级设计证据：源码顶部注释把它定位为“Visual baseline: deepsuite @deepseek/md markdown.css, adapted to CSS Modules. Cite pills, header anchors, and thinking-small variants are intentionally absent (no matching DOM). Token names match that sheet.”；固定提交中扫描到的结构线索是：样式结构包含选择器 .css、.markdown、.tableScroll、.wrapper、.imageAlt、.image；本地静态 import 图显示它直接依赖 0 个源文件，并被 2 个源文件直接引用。
  • 直接协作者：packages/client/ui-primitives/README.md、packages/client/ui-primitives/src/markdown/MarkdownText.tsx、packages/client/ui-primitives/src/markdown/render.tsx
  • 对应测试：间接测试线索（通过本地 import 链，非直接覆盖）：packages/client/locale/tests/apply.client.spec.ts、packages/client/locale/tests/language-row.client.spec.tsx、packages/client/ui-agent-preset/tests/apply.client.spec.ts、packages/client/ui-agent-preset/tests/components.client.spec.tsx、packages/client/ui-agent-preset/tests/section.client.spec.tsx、packages/client/ui-attachment/tests/attachment-rail.client.spec.tsx
  • 测试关联依据：固定提交源码中的本地静态 import 传递引用；这些测试通过包入口或中间模块到达本文件，不等于本文件被直接覆盖。
  • 阅读顺序：先读客户端运行时契约或呈现模型，再读当前界面文件，沿着 packages/client/ui-primitives/src/markdown/MarkdownText.tsx、packages/client/ui-primitives/src/markdown/render.tsx 确认状态如何进入 UI，最后对照 packages/client/locale/tests/apply.client.spec.ts、packages/client/locale/tests/language-row.client.spec.tsx、packages/client/ui-agent-preset/tests/apply.client.spec.ts。
  • 代码证据：固定提交归档实际读取结果：约 304 行；样式结构包含选择器 .css、.markdown、.tableScroll、.wrapper、.imageAlt、.image；源码顶部原注释（英文，仅作回查线索）：Visual baseline: deepsuite @deepseek/md markdown.css, adapted to CSS Modules. Cite pills, header anchors, and thinking-small variants are intentionally absent (no matching DOM). Token names match that sheet.。
  • 固定版本：源码链接固定到官方提交 aa6c361a972c8369148dea7380bb5c21c24e07ec。

packages/client/ui-primitives/src/markdown/MarkdownText.tsx ​

  • 所属层：packages/client：可复用的 Harness 功能包
  • 文件角色：界面组件或界面逻辑
  • 这个文件有什么用：它实现名为 MarkdownText 的界面组件或交互逻辑，并导出 MarkdownText、renderSettled、StreamingRenderer，把输入、局部状态和用户操作组织成可渲染的 UI 单元；源码顶部还说明：Untrusted assistant-Markdown renderer over the direct mdast pipeline: parse.ts grammars, the incremental streaming parser, and render.tsx. While a message streams, all but the trailing two blocks freeze as cached React elements and only the source tail behi...。
  • 为什么这样设计：固定提交的文件顶部注释把它定位为“Untrusted assistant-Markdown renderer over the direct mdast pipeline: parse.ts grammars, the incremental streaming parser, and render.tsx. While a message streams, all but the trailing two blocks freeze as cached React elements and only the source tail behi...”；把这项职责单独放置，可以让边界、输入和失败处理在一个地方被阅读和测试。
  • 文件级设计证据：源码顶部注释把它定位为“Untrusted assistant-Markdown renderer over the direct mdast pipeline: parse.ts grammars, the incremental streaming parser, and render.tsx. While a message streams, all but the trailing two blocks freeze as cached React elements and only the source tail behi...”；固定提交中扫描到的声明包括 MarkdownText、renderSettled、StreamingRenderer；本地静态 import 图显示它直接依赖 4 个源文件，并被 2 个源文件直接引用。
  • 直接协作者：packages/client/ui-primitives/README.md、packages/client/ui-primitives/src/markdown/MarkdownText.module.css、packages/client/ui-primitives/src/markdown/incremental.ts、packages/client/ui-primitives/src/markdown/parse.ts、packages/client/ui-primitives/src/WebBlock.tsx
  • 对应测试：间接测试线索（通过本地 import 链，非直接覆盖）：packages/client/locale/tests/apply.client.spec.ts、packages/client/locale/tests/document-language.client.spec.ts、packages/client/locale/tests/invariant.client.spec.ts、packages/client/locale/tests/language-row.client.spec.tsx、packages/client/locale/tests/locale.client.spec.ts、packages/client/ui-agent-preset/tests/apply.client.spec.ts
  • 测试关联依据：固定提交源码中的本地静态 import 传递引用；这些测试通过包入口或中间模块到达本文件，不等于本文件被直接覆盖。
  • 阅读顺序：先读客户端运行时契约或呈现模型，再读当前界面文件，沿着 packages/client/ui-primitives/src/WebBlock.tsx、packages/client/ui-primitives/src/index.ts 确认状态如何进入 UI，最后对照 packages/client/locale/tests/apply.client.spec.ts、packages/client/locale/tests/document-language.client.spec.ts、packages/client/locale/tests/invariant.client.spec.ts。
  • 代码证据：固定提交归档实际读取结果：约 176 行；扫描到的声明包括 MarkdownText、renderSettled、StreamingRenderer；源码顶部原注释（英文，仅作回查线索）：Untrusted assistant-Markdown renderer over the direct mdast pipeline: parse.ts grammars, the incremental streaming parser, and render.tsx. While a message streams, all but the trailing two blocks freeze as cached React elements and only the source tail behi...。
  • 固定版本：源码链接固定到官方提交 aa6c361a972c8369148dea7380bb5c21c24e07ec。

packages/client/ui-primitives/src/markdown/MessageText.module.css ​

packages/client/ui-primitives/src/markdown/MessageText.tsx ​

  • 所属层：packages/client：可复用的 Harness 功能包
  • 文件角色：界面组件或界面逻辑
  • 这个文件有什么用：它实现名为 MessageText 的界面组件或交互逻辑，并导出 MessageText，把输入、局部状态和用户操作组织成可渲染的 UI 单元；源码顶部还说明：MessageText is the literal-text primitive for user and steering content; assistant output uses MarkdownText.。
  • 为什么这样设计：固定提交的文件顶部注释把它定位为“MessageText is the literal-text primitive for user and steering content; assistant output uses MarkdownText.”；把这项职责单独放置，可以让边界、输入和失败处理在一个地方被阅读和测试。
  • 文件级设计证据：源码顶部注释把它定位为“MessageText is the literal-text primitive for user and steering content; assistant output uses MarkdownText.”；固定提交中扫描到的声明包括 MessageText；本地静态 import 图显示它直接依赖 1 个源文件，并被 1 个源文件直接引用。
  • 直接协作者：packages/client/ui-primitives/README.md、packages/client/ui-primitives/src/markdown/MessageText.module.css、packages/client/ui-primitives/src/index.ts
  • 对应测试：间接测试线索（通过本地 import 链，非直接覆盖）：packages/client/locale/tests/apply.client.spec.ts、packages/client/locale/tests/document-language.client.spec.ts、packages/client/locale/tests/invariant.client.spec.ts、packages/client/locale/tests/language-row.client.spec.tsx、packages/client/locale/tests/locale.client.spec.ts、packages/client/ui-agent-preset/tests/apply.client.spec.ts
  • 测试关联依据：固定提交源码中的本地静态 import 传递引用；这些测试通过包入口或中间模块到达本文件，不等于本文件被直接覆盖。
  • 阅读顺序：先读客户端运行时契约或呈现模型，再读当前界面文件，沿着 packages/client/ui-primitives/src/index.ts 确认状态如何进入 UI，最后对照 packages/client/locale/tests/apply.client.spec.ts、packages/client/locale/tests/document-language.client.spec.ts、packages/client/locale/tests/invariant.client.spec.ts。
  • 代码证据：固定提交归档实际读取结果：约 7 行；扫描到的声明包括 MessageText；源码顶部原注释（英文，仅作回查线索）：MessageText is the literal-text primitive for user and steering content; assistant output uses MarkdownText.。
  • 固定版本：源码链接固定到官方提交 aa6c361a972c8369148dea7380bb5c21c24e07ec。

packages/client/ui-primitives/src/markdown/cjkFriendlyStrong.ts ​

  • 所属层：packages/client：可复用的 Harness 功能包
  • 文件角色：界面交互逻辑
  • 这个文件有什么用：这个文件属于一个界面功能包，负责用户操作、视图状态或 UI 适配；它把浏览器体验接到稳定的运行时契约上。
  • 为什么这样设计：把用户操作和视图状态放在界面包内，能让 Web 组件复用同一套交互契约，也让服务端和领域逻辑不被浏览器细节污染。
  • 文件级设计证据：源码顶部注释把它定位为“Let asterisk strong emphasis close after punctuation when CJK prose continues without whitespace.”；固定提交中扫描到的声明包括 cjkFriendlyStrong、isCjkCharacter、start、inside；本地静态 import 图显示它直接依赖 0 个源文件，并被 2 个源文件直接引用。
  • 直接协作者：packages/client/ui-primitives/README.md、packages/client/ui-primitives/src/markdown/parse.ts、packages/client/ui-primitives/tests/markdown.client.spec.tsx
  • 对应测试：packages/client/ui-primitives/tests/markdown.client.spec.tsx
  • 测试关联依据：固定提交源码中的本地静态 import 直接引用；测试用例直接导入了这个源文件。
  • 阅读顺序：先读客户端运行时契约或呈现模型，再读当前界面文件，沿着 packages/client/ui-primitives/src/markdown/parse.ts、packages/client/ui-primitives/tests/markdown.client.spec.tsx 确认状态如何进入 UI，最后对照 packages/client/ui-primitives/tests/markdown.client.spec.tsx。
  • 代码证据：固定提交归档实际读取结果：约 83 行；扫描到的声明包括 cjkFriendlyStrong、isCjkCharacter、start、inside；源码顶部原注释（英文，仅作回查线索）：Let asterisk strong emphasis close after punctuation when CJK prose continues without whitespace.。
  • 固定版本：源码链接固定到官方提交 aa6c361a972c8369148dea7380bb5c21c24e07ec。

packages/client/ui-primitives/src/markdown/highlight.ts ​

  • 所属层：packages/client：可复用的 Harness 功能包
  • 文件角色：界面交互逻辑
  • 这个文件有什么用：这个文件属于一个界面功能包，负责用户操作、视图状态或 UI 适配；它把浏览器体验接到稳定的运行时契约上。
  • 为什么这样设计：把用户操作和视图状态放在界面包内，能让 Web 组件复用同一套交互契约，也让服务端和领域逻辑不被浏览器细节污染。
  • 文件级设计证据：源码顶部注释把它定位为“The client's ONE syntax highlighter: a synchronous fine-grained shiki core (JavaScript regex engine — no oniguruma WASM, bundle-friendly) with an explicit grammar allowlist and a CSS-variables theme. Colors live in the theme package's token sheets as --shik...”；固定提交中扫描到的声明包括 subscribeGrammarLoaded、grammarLoadCount、highlightToHtml、HighlightSpan、highlightLines；本地静态 import 图显示它直接依赖 0 个源文件，并被 4 个源文件直接引用。
  • 直接协作者：packages/client/ui-primitives/README.md、packages/client/ui-primitives/src/ReadBlock.tsx、packages/client/ui-primitives/src/markdown/CodeBlock.tsx、packages/client/ui-primitives/tests/code-block.client.spec.tsx
  • 对应测试：packages/client/ui-primitives/tests/code-block.client.spec.tsx、packages/client/ui-primitives/tests/read-block.client.spec.tsx
  • 测试关联依据：固定提交源码中的本地静态 import 直接引用；测试用例直接导入了这个源文件。
  • 阅读顺序：先读客户端运行时契约或呈现模型，再读当前界面文件，沿着 packages/client/ui-primitives/src/ReadBlock.tsx、packages/client/ui-primitives/src/markdown/CodeBlock.tsx、packages/client/ui-primitives/tests/code-block.client.spec.tsx 确认状态如何进入 UI，最后对照 packages/client/ui-primitives/tests/code-block.client.spec.tsx、packages/client/ui-primitives/tests/read-block.client.spec.tsx。
  • 代码证据：固定提交归档实际读取结果：约 311 行；扫描到的声明包括 subscribeGrammarLoaded、grammarLoadCount、highlightToHtml、HighlightSpan、highlightLines、createHighlighter、highlighter、ensureGrammar；源码顶部原注释（英文，仅作回查线索）：The client's ONE syntax highlighter: a synchronous fine-grained shiki core (JavaScript regex engine — no oniguruma WASM, bundle-friendly) with an explicit grammar allowlist and a CSS-variables theme. Colors live in the theme package's token sheets as --shik...。
  • 固定版本：源码链接固定到官方提交 aa6c361a972c8369148dea7380bb5c21c24e07ec。

packages/client/ui-primitives/src/markdown/incremental.ts ​

  • 所属层：packages/client：可复用的 Harness 功能包
  • 文件角色：界面交互逻辑
  • 这个文件有什么用：这个文件属于一个界面功能包，负责用户操作、视图状态或 UI 适配；它把浏览器体验接到稳定的运行时契约上。
  • 为什么这样设计：把用户操作和视图状态放在界面包内，能让 Web 组件复用同一套交互契约，也让服务端和领域逻辑不被浏览器细节污染。
  • 文件级设计证据：源码顶部注释把它定位为“Incremental block-level markdown parsing for an append-only text stream. Re-parsing the whole accumulated document on every streaming chunk is quadratic in the final reply length. CommonMark block parsing is line-based and appended text can only reshape the...”；固定提交中扫描到的声明包括 PositionedBlock、IncrementalBlocks、IncrementalMarkdownParser、blockKey；本地静态 import 图显示它直接依赖 0 个源文件，并被 3 个源文件直接引用。
  • 直接协作者：packages/client/ui-primitives/README.md、packages/client/ui-primitives/src/markdown/MarkdownText.tsx、packages/client/ui-primitives/src/markdown/render.tsx、packages/client/ui-primitives/tests/markdown-incremental.client.spec.tsx
  • 对应测试：packages/client/ui-primitives/tests/markdown-incremental.client.spec.tsx
  • 测试关联依据：固定提交源码中的本地静态 import 直接引用；测试用例直接导入了这个源文件。
  • 阅读顺序：先读客户端运行时契约或呈现模型，再读当前界面文件，沿着 packages/client/ui-primitives/src/markdown/MarkdownText.tsx、packages/client/ui-primitives/src/markdown/render.tsx、packages/client/ui-primitives/tests/markdown-incremental.client.spec.tsx 确认状态如何进入 UI，最后对照 packages/client/ui-primitives/tests/markdown-incremental.client.spec.tsx。
  • 代码证据：固定提交归档实际读取结果：约 130 行；扫描到的声明包括 PositionedBlock、IncrementalBlocks、IncrementalMarkdownParser、blockKey；源码顶部原注释（英文，仅作回查线索）：Incremental block-level markdown parsing for an append-only text stream. Re-parsing the whole accumulated document on every streaming chunk is quadratic in the final reply length. CommonMark block parsing is line-based and appended text can only reshape the...。
  • 固定版本：源码链接固定到官方提交 aa6c361a972c8369148dea7380bb5c21c24e07ec。

packages/client/ui-primitives/src/markdown/katex.tsx ​

  • 所属层：packages/client：可复用的 Harness 功能包
  • 文件角色：界面组件或界面逻辑
  • 这个文件有什么用：它实现名为 katex 的界面组件或交互逻辑，并导出 renderTexToReact、styleObject、domToReact，把输入、局部状态和用户操作组织成可渲染的 UI 单元；源码顶部还说明：TeX-to-React via KaTeX, replicating the rehype-katex pipeline this renderer replaced: the same three-arm error chain (strict render, strict: 'ignore' retry, error span) and a DOM-identical element tree, so settled math keeps its exact markup. KaTeX emits an...。
  • 为什么这样设计：固定提交的文件顶部注释把它定位为“TeX-to-React via KaTeX, replicating the rehype-katex pipeline this renderer replaced: the same three-arm error chain (strict render, strict: 'ignore' retry, error span) and a DOM-identical element tree, so settled math keeps its exact markup. KaTeX emits an...”；把这项职责单独放置，可以让边界、输入和失败处理在一个地方被阅读和测试。
  • 文件级设计证据：源码顶部注释把它定位为“TeX-to-React via KaTeX, replicating the rehype-katex pipeline this renderer replaced: the same three-arm error chain (strict render, strict: 'ignore' retry, error span) and a DOM-identical element tree, so settled math keeps its exact markup. KaTeX emits an...”；固定提交中扫描到的声明包括 renderTexToReact、styleObject、domToReact；本地静态 import 图显示它直接依赖 0 个源文件，并被 1 个源文件直接引用。
  • 直接协作者：packages/client/ui-primitives/README.md、packages/client/ui-primitives/src/markdown/render.tsx
  • 对应测试：间接测试线索（通过本地 import 链，非直接覆盖）：packages/client/ui-primitives/tests/atoms.client.spec.tsx、packages/client/ui-primitives/tests/diff-block.client.spec.tsx、packages/client/ui-primitives/tests/hover-card.client.spec.tsx、packages/client/ui-primitives/tests/icons.client.spec.tsx、packages/client/ui-primitives/tests/json-tree.client.spec.tsx、packages/client/ui-primitives/tests/markdown-dom-parity.client.spec.tsx
  • 测试关联依据：固定提交源码中的本地静态 import 传递引用；这些测试通过包入口或中间模块到达本文件，不等于本文件被直接覆盖。
  • 阅读顺序：先读客户端运行时契约或呈现模型，再读当前界面文件，沿着 packages/client/ui-primitives/src/markdown/render.tsx 确认状态如何进入 UI，最后对照 packages/client/ui-primitives/tests/atoms.client.spec.tsx、packages/client/ui-primitives/tests/diff-block.client.spec.tsx、packages/client/ui-primitives/tests/hover-card.client.spec.tsx。
  • 代码证据：固定提交归档实际读取结果：约 90 行；扫描到的声明包括 renderTexToReact、styleObject、domToReact；源码顶部原注释（英文，仅作回查线索）：TeX-to-React via KaTeX, replicating the rehype-katex pipeline this renderer replaced: the same three-arm error chain (strict render, strict: 'ignore' retry, error span) and a DOM-identical element tree, so settled math keeps its exact markup. KaTeX emits an...。
  • 固定版本：源码链接固定到官方提交 aa6c361a972c8369148dea7380bb5c21c24e07ec。

packages/client/ui-primitives/src/markdown/mathCompatibility.ts ​

  • 所属层：packages/client：可复用的 Harness 功能包
  • 文件角色：界面交互逻辑
  • 这个文件有什么用：这个文件属于一个界面功能包，负责用户操作、视图状态或 UI 适配；它把浏览器体验接到稳定的运行时契约上。
  • 为什么这样设计：把用户操作和视图状态放在界面包内，能让 Web 组件复用同一套交互契约，也让服务端和领域逻辑不被浏览器细节污染。
  • 文件级设计证据：源码顶部注释把它定位为“Extend upstream dollar-only math syntax with TeX delimiters while reusing its token vocabulary.”；固定提交中扫描到的声明包括 mathCompatibility、start、open、between、afterCloseAttempt；本地静态 import 图显示它直接依赖 0 个源文件，并被 2 个源文件直接引用。
  • 直接协作者：packages/client/ui-primitives/README.md、packages/client/ui-primitives/src/markdown/parse.ts、packages/client/ui-primitives/tests/markdown.client.spec.tsx
  • 对应测试：packages/client/ui-primitives/tests/markdown.client.spec.tsx
  • 测试关联依据：固定提交源码中的本地静态 import 直接引用；测试用例直接导入了这个源文件。
  • 阅读顺序：先读客户端运行时契约或呈现模型，再读当前界面文件，沿着 packages/client/ui-primitives/src/markdown/parse.ts、packages/client/ui-primitives/tests/markdown.client.spec.tsx 确认状态如何进入 UI，最后对照 packages/client/ui-primitives/tests/markdown.client.spec.tsx。
  • 代码证据：固定提交归档实际读取结果：约 349 行；扫描到的声明包括 mathCompatibility、start、open、between、afterCloseAttempt、dataStart、afterDataBackslash、data；源码顶部原注释（英文，仅作回查线索）：Extend upstream dollar-only math syntax with TeX delimiters while reusing its token vocabulary.。
  • 固定版本：源码链接固定到官方提交 aa6c361a972c8369148dea7380bb5c21c24e07ec。

packages/client/ui-primitives/src/markdown/parse.ts ​

  • 所属层：packages/client：可复用的 Harness 功能包
  • 文件角色：界面交互逻辑
  • 这个文件有什么用：这个文件属于一个界面功能包，负责用户操作、视图状态或 UI 适配；它把浏览器体验接到稳定的运行时契约上。
  • 为什么这样设计：把用户操作和视图状态放在界面包内，能让 Web 组件复用同一套交互契约，也让服务端和领域逻辑不被浏览器细节污染。
  • 文件级设计证据：源码顶部注释把它定位为“The markdown renderer's two mdast grammars, one per rendering arm. Each arm is internally consistent — the incremental tail parses, the one-shot parses, and the plain-text projection of a given grammar always agree on where blocks start and end — and the se...”；固定提交中扫描到的声明包括 parseGfm、parseGfmWithMath；本地静态 import 图显示它直接依赖 2 个源文件，并被 3 个源文件直接引用。
  • 直接协作者：packages/client/ui-primitives/README.md、packages/client/ui-primitives/src/markdown/cjkFriendlyStrong.ts、packages/client/ui-primitives/src/markdown/mathCompatibility.ts、packages/client/ui-primitives/src/markdown/MarkdownText.tsx、packages/client/ui-primitives/src/markdown/plain-text.ts
  • 对应测试：packages/client/ui-primitives/tests/markdown-incremental.client.spec.tsx
  • 测试关联依据：固定提交源码中的本地静态 import 直接引用；测试用例直接导入了这个源文件。
  • 阅读顺序：先读客户端运行时契约或呈现模型，再读当前界面文件，沿着 packages/client/ui-primitives/src/markdown/MarkdownText.tsx、packages/client/ui-primitives/src/markdown/plain-text.ts、packages/client/ui-primitives/tests/markdown-incremental.client.spec.tsx 确认状态如何进入 UI，最后对照 packages/client/ui-primitives/tests/markdown-incremental.client.spec.tsx。
  • 代码证据：固定提交归档实际读取结果：约 44 行；扫描到的声明包括 parseGfm、parseGfmWithMath；源码顶部原注释（英文，仅作回查线索）：The markdown renderer's two mdast grammars, one per rendering arm. Each arm is internally consistent — the incremental tail parses, the one-shot parses, and the plain-text projection of a given grammar always agree on where blocks start and end — and the se...。
  • 固定版本：源码链接固定到官方提交 aa6c361a972c8369148dea7380bb5c21c24e07ec。

packages/client/ui-primitives/src/markdown/plain-text.ts ​

  • 所属层：packages/client：可复用的 Harness 功能包
  • 文件角色：界面交互逻辑
  • 这个文件有什么用：这个文件属于一个界面功能包，负责用户操作、视图状态或 UI 适配；它把浏览器体验接到稳定的运行时契约上。
  • 为什么这样设计：把用户操作和视图状态放在界面包内，能让 Web 组件复用同一套交互契约，也让服务端和领域逻辑不被浏览器细节污染。
  • 文件级设计证据：源码顶部注释把它定位为“Markdown-to-plain-text projection for compact summaries and labels. Parsing shares the renderer's streaming GFM grammar (parseGfm), so the projection strips exactly the markup the renderer would draw; raw HTML stays literal, links keep their labels, images ...”；固定提交中扫描到的声明包括 MarkdownPlainTextMode、MarkdownPlainTextOptions、extractMarkdownPlainText、inlineText、compactInline；本地静态 import 图显示它直接依赖 1 个源文件，并被 1 个源文件直接引用。
  • 直接协作者：packages/client/ui-primitives/README.md、packages/client/ui-primitives/src/markdown/parse.ts、packages/client/ui-primitives/src/index.ts
  • 对应测试：间接测试线索（通过本地 import 链，非直接覆盖）：packages/client/locale/tests/apply.client.spec.ts、packages/client/locale/tests/document-language.client.spec.ts、packages/client/locale/tests/invariant.client.spec.ts、packages/client/locale/tests/language-row.client.spec.tsx、packages/client/locale/tests/locale.client.spec.ts、packages/client/ui-agent-preset/tests/apply.client.spec.ts
  • 测试关联依据：固定提交源码中的本地静态 import 传递引用；这些测试通过包入口或中间模块到达本文件，不等于本文件被直接覆盖。
  • 阅读顺序：先读客户端运行时契约或呈现模型，再读当前界面文件，沿着 packages/client/ui-primitives/src/index.ts 确认状态如何进入 UI，最后对照 packages/client/locale/tests/apply.client.spec.ts、packages/client/locale/tests/document-language.client.spec.ts、packages/client/locale/tests/invariant.client.spec.ts。
  • 代码证据：固定提交归档实际读取结果：约 121 行；扫描到的声明包括 MarkdownPlainTextMode、MarkdownPlainTextOptions、extractMarkdownPlainText、inlineText、compactInline、blockText、findFirstParagraph、fullText；源码顶部原注释（英文，仅作回查线索）：Markdown-to-plain-text projection for compact summaries and labels. Parsing shares the renderer's streaming GFM grammar (parseGfm), so the projection strips exactly the markup the renderer would draw; raw HTML stays literal, links keep their labels, images ...。
  • 固定版本：源码链接固定到官方提交 aa6c361a972c8369148dea7380bb5c21c24e07ec。

packages/client/ui-primitives/src/markdown/render.tsx ​

  • 所属层：packages/client：可复用的 Harness 功能包
  • 文件角色：呈现转换
  • 这个文件有什么用：它把浏览器端、用户界面、渲染转换成界面或终端可以消费的呈现结构，执行逻辑因此不需要知道具体 UI 组件。
  • 为什么这样设计：领域事实和可见表示分开，CLI、Web 或其他宿主可以各自渲染同一份结果；执行代码也不会被 UI 细节反向污染。
  • 文件级设计证据：源码顶部注释把它定位为“Direct mdast→React markdown renderer. Replaces the react-markdown / remark-rehype pipeline with one switch over parsed nodes so streaming can cache frozen blocks as React elements; the rendered DOM is pinned byte-for-byte by tests/fixtures/markdown-dom and ...”；固定提交中扫描到的声明包括 MarkdownCodeLabels、ReferenceTargets、createReferenceTargets、collectReferenceTargets、MarkdownFileMentions；本地静态 import 图显示它直接依赖 4 个源文件，并被 2 个源文件直接引用。
  • 直接协作者：packages/client/ui-primitives/README.md、packages/client/ui-primitives/src/markdown/CodeBlock.tsx、packages/client/ui-primitives/src/markdown/MarkdownText.module.css、packages/client/ui-primitives/src/markdown/incremental.ts、packages/client/ui-primitives/src/markdown/MarkdownText.tsx
  • 对应测试：packages/client/ui-primitives/tests/markdown-render-units.client.spec.tsx
  • 测试关联依据：固定提交源码中的本地静态 import 直接引用；测试用例直接导入了这个源文件。
  • 阅读顺序：先读客户端运行时契约或呈现模型，再读当前界面文件，沿着 packages/client/ui-primitives/src/markdown/MarkdownText.tsx、packages/client/ui-primitives/tests/markdown-render-units.client.spec.tsx 确认状态如何进入 UI，最后对照 packages/client/ui-primitives/tests/markdown-render-units.client.spec.tsx。
  • 代码证据：固定提交归档实际读取结果：约 604 行；扫描到的声明包括 MarkdownCodeLabels、ReferenceTargets、createReferenceTargets、collectReferenceTargets、MarkdownFileMentions、MarkdownRenderContext、renderBlocks、wrapBlockChildren；源码顶部原注释（英文，仅作回查线索）：Direct mdast→React markdown renderer. Replaces the react-markdown / remark-rehype pipeline with one switch over parsed nodes so streaming can cache frozen blocks as React elements; the rendered DOM is pinned byte-for-byte by tests/fixtures/markdown-dom and ...。
  • 固定版本：源码链接固定到官方提交 aa6c361a972c8369148dea7380bb5c21c24e07ec。

packages/client/ui-primitives/src/pointer-grace.ts ​

  • 所属层：packages/client：可复用的 Harness 功能包
  • 文件角色：界面交互逻辑
  • 这个文件有什么用：这个文件属于一个界面功能包，负责用户操作、视图状态或 UI 适配；它把浏览器体验接到稳定的运行时契约上。
  • 为什么这样设计：把用户操作和视图状态放在界面包内，能让 Web 组件复用同一套交互契约，也让服务端和领域逻辑不被浏览器细节污染。
  • 文件级设计证据：源码顶部注释把它定位为“Shared close timing for pointer-dismissed popups (HoverCard, hover-closing Menu). Both float free of their anchor, so the pointer has to cross ground that belongs to neither on its way in; closing on the first pointerleave makes the popup unreachable. The g...”；固定提交中扫描到的声明包括 POINTER_GRACE_MS、PointerGrace、usePointerGrace；本地静态 import 图显示它直接依赖 0 个源文件，并被 4 个源文件直接引用。
  • 直接协作者：packages/client/ui-primitives/README.md、packages/client/ui-primitives/src/HoverCard.tsx、packages/client/ui-primitives/src/Menu.tsx、packages/client/ui-primitives/tests/atoms.client.spec.tsx
  • 对应测试：packages/client/ui-primitives/tests/atoms.client.spec.tsx、packages/client/ui-primitives/tests/hover-card.client.spec.tsx
  • 测试关联依据：固定提交源码中的本地静态 import 直接引用；测试用例直接导入了这个源文件。
  • 阅读顺序：先读客户端运行时契约或呈现模型，再读当前界面文件，沿着 packages/client/ui-primitives/src/HoverCard.tsx、packages/client/ui-primitives/src/Menu.tsx、packages/client/ui-primitives/tests/atoms.client.spec.tsx 确认状态如何进入 UI，最后对照 packages/client/ui-primitives/tests/atoms.client.spec.tsx、packages/client/ui-primitives/tests/hover-card.client.spec.tsx。
  • 代码证据：固定提交归档实际读取结果：约 53 行；扫描到的声明包括 POINTER_GRACE_MS、PointerGrace、usePointerGrace；源码顶部原注释（英文，仅作回查线索）：Shared close timing for pointer-dismissed popups (HoverCard, hover-closing Menu). Both float free of their anchor, so the pointer has to cross ground that belongs to neither on its way in; closing on the first pointerleave makes the popup unreachable. The g...。
  • 固定版本：源码链接固定到官方提交 aa6c361a972c8369148dea7380bb5c21c24e07ec。

packages/client/ui-primitives/src/use-copy-feedback.ts ​

  • 所属层：packages/client：可复用的 Harness 功能包
  • 文件角色：界面交互逻辑
  • 这个文件有什么用：这个文件属于一个界面功能包，负责用户操作、视图状态或 UI 适配；它把浏览器体验接到稳定的运行时契约上。
  • 为什么这样设计：把用户操作和视图状态放在界面包内，能让 Web 组件复用同一套交互契约，也让服务端和领域逻辑不被浏览器细节污染。
  • 文件级设计证据：源码顶部注释把它定位为“The copy-to-clipboard-with-feedback hook shared by the block primitives (TerminalBlock, SearchBlock): write the given text, and on success flip a transient copied flag that the caller renders as a "复制成功" label for one second. A refused write leaves the flag...”；固定提交中扫描到的声明包括 CopyFeedback、useCopyFeedback；本地静态 import 图显示它直接依赖 1 个源文件，并被 2 个源文件直接引用。
  • 直接协作者：packages/client/ui-primitives/README.md、packages/client/ui-primitives/src/clipboard.ts、packages/client/ui-primitives/src/SearchBlock.tsx、packages/client/ui-primitives/src/TerminalBlock.tsx
  • 对应测试：间接测试线索（通过本地 import 链，非直接覆盖）：packages/client/locale/tests/apply.client.spec.ts、packages/client/locale/tests/language-row.client.spec.tsx、packages/client/ui-agent-preset/tests/apply.client.spec.ts、packages/client/ui-agent-preset/tests/components.client.spec.tsx、packages/client/ui-agent-preset/tests/section.client.spec.tsx、packages/client/ui-attachment/tests/attachment-rail.client.spec.tsx
  • 测试关联依据：固定提交源码中的本地静态 import 传递引用；这些测试通过包入口或中间模块到达本文件，不等于本文件被直接覆盖。
  • 阅读顺序：先读客户端运行时契约或呈现模型，再读当前界面文件，沿着 packages/client/ui-primitives/src/SearchBlock.tsx、packages/client/ui-primitives/src/TerminalBlock.tsx 确认状态如何进入 UI，最后对照 packages/client/locale/tests/apply.client.spec.ts、packages/client/locale/tests/language-row.client.spec.tsx、packages/client/ui-agent-preset/tests/apply.client.spec.ts。
  • 代码证据：固定提交归档实际读取结果：约 37 行；扫描到的声明包括 CopyFeedback、useCopyFeedback；源码顶部原注释（英文，仅作回查线索）：The copy-to-clipboard-with-feedback hook shared by the block primitives (TerminalBlock, SearchBlock): write the given text, and on success flip a transient copied flag that the caller renders as a "复制成功" label for one second. A refused write leaves the flag...。
  • 固定版本：源码链接固定到官方提交 aa6c361a972c8369148dea7380bb5c21c24e07ec。

packages/client/ui-primitives/src/useAnchoredMaxHeight.ts ​

  • 所属层：packages/client：可复用的 Harness 功能包
  • 文件角色：界面交互逻辑
  • 这个文件有什么用：这个文件属于一个界面功能包，负责用户操作、视图状态或 UI 适配；它把浏览器体验接到稳定的运行时契约上。
  • 为什么这样设计：把用户操作和视图状态放在界面包内，能让 Web 组件复用同一套交互契约，也让服务端和领域逻辑不被浏览器细节污染。
  • 文件级设计证据：源码顶部注释把它定位为“Viewport-fit hook for bottom-anchored overlays (slash menu, popupSelect): the element's bottom edge is laid out independent of its height, so it grows upward and only the top edge can collide with the viewport — clamp the design cap to the space between tha...”；固定提交中扫描到的声明包括 useAnchoredMaxHeight；本地静态 import 图显示它直接依赖 0 个源文件，并被 1 个源文件直接引用。
  • 直接协作者：packages/client/ui-primitives/README.md、packages/client/ui-primitives/src/index.ts
  • 对应测试：间接测试线索（通过本地 import 链，非直接覆盖）：packages/client/locale/tests/apply.client.spec.ts、packages/client/locale/tests/document-language.client.spec.ts、packages/client/locale/tests/invariant.client.spec.ts、packages/client/locale/tests/language-row.client.spec.tsx、packages/client/locale/tests/locale.client.spec.ts、packages/client/ui-agent-preset/tests/apply.client.spec.ts
  • 测试关联依据：固定提交源码中的本地静态 import 传递引用；这些测试通过包入口或中间模块到达本文件，不等于本文件被直接覆盖。
  • 阅读顺序：先读客户端运行时契约或呈现模型，再读当前界面文件，沿着 packages/client/ui-primitives/src/index.ts 确认状态如何进入 UI，最后对照 packages/client/locale/tests/apply.client.spec.ts、packages/client/locale/tests/document-language.client.spec.ts、packages/client/locale/tests/invariant.client.spec.ts。
  • 代码证据：固定提交归档实际读取结果：约 38 行；扫描到的声明包括 useAnchoredMaxHeight；源码顶部原注释（英文，仅作回查线索）：Viewport-fit hook for bottom-anchored overlays (slash menu, popupSelect): the element's bottom edge is laid out independent of its height, so it grows upward and only the top edge can collide with the viewport — clamp the design cap to the space between tha...。
  • 固定版本：源码链接固定到官方提交 aa6c361a972c8369148dea7380bb5c21c24e07ec。

packages/client/ui-primitives/src/useAnchoredPosition.ts ​

  • 所属层：packages/client：可复用的 Harness 功能包
  • 文件角色：界面交互逻辑
  • 这个文件有什么用：这个文件属于一个界面功能包，负责用户操作、视图状态或 UI 适配；它把浏览器体验接到稳定的运行时契约上。
  • 为什么这样设计：把用户操作和视图状态放在界面包内，能让 Web 组件复用同一套交互契约，也让服务端和领域逻辑不被浏览器细节污染。
  • 文件级设计证据：源码顶部注释把它定位为“Keep a fixed-position floating element anchored to a trigger. A portaled panel is positioned from its anchor's viewport rect, which stops being true the moment anything scrolls or the window resizes. This owns that one concern: measure the anchor, offset th...”；固定提交中扫描到的声明包括 AnchoredPositionOptions、useAnchoredPosition；本地静态 import 图显示它直接依赖 0 个源文件，并被 2 个源文件直接引用。
  • 直接协作者：packages/client/ui-primitives/README.md、packages/client/ui-primitives/src/index.ts、packages/client/ui-primitives/tests/use-anchored-position.client.spec.tsx
  • 对应测试：packages/client/ui-primitives/tests/use-anchored-position.client.spec.tsx
  • 测试关联依据：固定提交源码中的本地静态 import 直接引用；测试用例直接导入了这个源文件。
  • 阅读顺序：先读客户端运行时契约或呈现模型，再读当前界面文件，沿着 packages/client/ui-primitives/src/index.ts、packages/client/ui-primitives/tests/use-anchored-position.client.spec.tsx 确认状态如何进入 UI，最后对照 packages/client/ui-primitives/tests/use-anchored-position.client.spec.tsx。
  • 代码证据：固定提交归档实际读取结果：约 81 行；扫描到的声明包括 AnchoredPositionOptions、useAnchoredPosition；源码顶部原注释（英文，仅作回查线索）：Keep a fixed-position floating element anchored to a trigger. A portaled panel is positioned from its anchor's viewport rect, which stops being true the moment anything scrolls or the window resizes. This owns that one concern: measure the anchor, offset th...。
  • 固定版本：源码链接固定到官方提交 aa6c361a972c8369148dea7380bb5c21c24e07ec。

packages/client/ui-primitives/src/useDismissOnOutsidePointer.ts ​

  • 所属层：packages/client：可复用的 Harness 功能包
  • 文件角色：界面交互逻辑
  • 这个文件有什么用：这个文件属于一个界面功能包，负责用户操作、视图状态或 UI 适配；它把浏览器体验接到稳定的运行时契约上。
  • 为什么这样设计：把用户操作和视图状态放在界面包内，能让 Web 组件复用同一套交互契约，也让服务端和领域逻辑不被浏览器细节污染。
  • 文件级设计证据：源码顶部注释把它定位为“Outside-pointer dismissal for trigger-owned popovers (jobs list, Cordis panel): while the surface is open, a pointerdown outside the root closes it.”；固定提交中扫描到的声明包括 useDismissOnOutsidePointer；本地静态 import 图显示它直接依赖 0 个源文件，并被 1 个源文件直接引用。
  • 直接协作者：packages/client/ui-primitives/README.md、packages/client/ui-primitives/src/index.ts
  • 对应测试：间接测试线索（通过本地 import 链，非直接覆盖）：packages/client/locale/tests/apply.client.spec.ts、packages/client/locale/tests/document-language.client.spec.ts、packages/client/locale/tests/invariant.client.spec.ts、packages/client/locale/tests/language-row.client.spec.tsx、packages/client/locale/tests/locale.client.spec.ts、packages/client/ui-agent-preset/tests/apply.client.spec.ts
  • 测试关联依据：固定提交源码中的本地静态 import 传递引用；这些测试通过包入口或中间模块到达本文件，不等于本文件被直接覆盖。
  • 阅读顺序：先读客户端运行时契约或呈现模型，再读当前界面文件，沿着 packages/client/ui-primitives/src/index.ts 确认状态如何进入 UI，最后对照 packages/client/locale/tests/apply.client.spec.ts、packages/client/locale/tests/document-language.client.spec.ts、packages/client/locale/tests/invariant.client.spec.ts。
  • 代码证据：固定提交归档实际读取结果：约 29 行；扫描到的声明包括 useDismissOnOutsidePointer；源码顶部原注释（英文，仅作回查线索）：Outside-pointer dismissal for trigger-owned popovers (jobs list, Cordis panel): while the surface is open, a pointerdown outside the root closes it.。
  • 固定版本：源码链接固定到官方提交 aa6c361a972c8369148dea7380bb5c21c24e07ec。

packages/client/ui-primitives/tests/ansi.client.spec.ts ​

  • 所属层：packages/client：可复用的 Harness 功能包
  • 文件角色：测试用例
  • 这个文件有什么用：它用自动化测试检查浏览器端、用户界面的具体场景，包括“parseAnsiLines: text without SGR state”、“leaves plain text as one unstyled span”、“returns exactly one empty line for empty input”、“splits a multi-line run and drops the empty line between two blocks”；这些断言把“应该发生什么”变成可以重复运行的证据。
  • 为什么这样设计：把测试主题“parseAnsiLines: text without SGR state”写成独立测试用例，读者可以从输入、触发动作和断言反推实现的不变量；不同回归问题也不会互相遮蔽。
  • 文件级设计证据：源码顶部注释把它定位为“parseAnsiLines, the ANSI model behind TerminalBlock: anser's SGR runs resolved into inline styles and folded into per-line span arrays, with every escape and control character that carries no color removed first. The DOM side of the same model (which runs g...”；固定提交中扫描到的声明包括 sgr、onlySpan；本地静态 import 图显示它直接依赖 1 个源文件，并被 0 个源文件直接引用。
  • 直接协作者：packages/client/ui-primitives/README.md、packages/client/ui-primitives/src/ansi.ts
  • 对应测试：本文件本身就是测试用例。
  • 测试关联依据：本文件本身就是测试用例，不把同目录的其他测试冒充成它的“对应测试”。
  • 阅读顺序：先看它直接导入的被测实现 packages/client/ui-primitives/src/ansi.ts，再读本文件的测试主题、输入和断言；最后对照测试支持和失败输出。
  • 代码证据：固定提交归档实际读取结果：约 513 行；扫描到的声明包括 sgr、onlySpan；扫描到的测试主题包括 “parseAnsiLines: text without SGR state”、“leaves plain text as one unstyled span”、“returns exactly one empty line for empty input”、“splits a multi-line run and drops the empty line between two blocks”、“keeps tabs, which the terminal surface needs for column layout”、“parseAnsiLines: basic colors mapped onto theme tokens”；源码顶部原注释（英文，仅作回查线索）：parseAnsiLines, the ANSI model behind TerminalBlock: anser's SGR runs resolved into inline styles and folded into per-line span arrays, with every escape and control character that carries no color removed first. The DOM side of the same model (which runs g...。
  • 固定版本：源码链接固定到官方提交 aa6c361a972c8369148dea7380bb5c21c24e07ec。

packages/client/ui-primitives/tests/atoms.client.spec.tsx ​

  • 所属层：packages/client：可复用的 Harness 功能包
  • 文件角色：测试用例
  • 这个文件有什么用：它用自动化测试检查浏览器端、用户界面的具体场景，包括“Button”、“renders children, icon, and forwards clicks”、“disabled blocks interaction”、“outline variant renders a bordered cancel-style button”；这些断言把“应该发生什么”变成可以重复运行的证据。
  • 为什么这样设计：把测试主题“Button”写成独立测试用例，读者可以从输入、触发动作和断言反推实现的不变量；不同回归问题也不会互相遮蔽。
  • 文件级设计证据：源码顶部注释把它定位为“@vitest-environment jsdom”；本地静态 import 图显示它直接依赖 2 个源文件，并被 0 个源文件直接引用。
  • 直接协作者：packages/client/ui-primitives/README.md、packages/client/ui-primitives/src/index.ts、packages/client/ui-primitives/src/pointer-grace.ts
  • 对应测试：本文件本身就是测试用例。
  • 测试关联依据：本文件本身就是测试用例，不把同目录的其他测试冒充成它的“对应测试”。
  • 阅读顺序：先看它直接导入的被测实现 packages/client/ui-primitives/src/index.ts、packages/client/ui-primitives/src/pointer-grace.ts，再读本文件的测试主题、输入和断言；最后对照测试支持和失败输出。
  • 代码证据：固定提交归档实际读取结果：约 418 行；扫描到的测试主题包括 “Button”、“renders children, icon, and forwards clicks”、“disabled blocks interaction”、“outline variant renders a bordered cancel-style button”、“Pill”、“is a span when static, a button when clickable”；源码顶部原注释（英文，仅作回查线索）：@vitest-environment jsdom。
  • 固定版本：源码链接固定到官方提交 aa6c361a972c8369148dea7380bb5c21c24e07ec。

packages/client/ui-primitives/tests/code-block.client.spec.tsx ​

  • 所属层：packages/client：可复用的 Harness 功能包
  • 文件角色：测试用例
  • 这个文件有什么用：它用自动化测试检查浏览器端、用户界面的具体场景，包括“highlightToHtml”、“highlights a registered grammar into css-variables token spans”、“returns undefined for unknown or absent languages”、“lazily loads every read-card grammar: plain first, highlighted after load”；这些断言把“应该发生什么”变成可以重复运行的证据。
  • 为什么这样设计：把测试主题“highlightToHtml”写成独立测试用例，读者可以从输入、触发动作和断言反推实现的不变量；不同回归问题也不会互相遮蔽。
  • 文件级设计证据：源码顶部注释把它定位为“@vitest-environment jsdom CodeBlock + the shiki singleton: registered grammars highlight into token spans colored by --shiki-* custom properties; unknown/absent languages take the identical-geometry plain arm; aliases resolve; the trailing newline is displa...”；本地静态 import 图显示它直接依赖 2 个源文件，并被 0 个源文件直接引用。
  • 直接协作者：packages/client/ui-primitives/README.md、packages/client/ui-primitives/src/markdown/CodeBlock.tsx、packages/client/ui-primitives/src/markdown/highlight.ts
  • 对应测试：本文件本身就是测试用例。
  • 测试关联依据：本文件本身就是测试用例，不把同目录的其他测试冒充成它的“对应测试”。
  • 阅读顺序：先看它直接导入的被测实现 packages/client/ui-primitives/src/markdown/CodeBlock.tsx、packages/client/ui-primitives/src/markdown/highlight.ts，再读本文件的测试主题、输入和断言；最后对照测试支持和失败输出。
  • 代码证据：固定提交归档实际读取结果：约 156 行；扫描到的测试主题包括 “highlightToHtml”、“highlights a registered grammar into css-variables token spans”、“returns undefined for unknown or absent languages”、“lazily loads every read-card grammar: plain first, highlighted after load”、“CodeBlock”、“renders the highlighted tree for TypeScript”；源码顶部原注释（英文，仅作回查线索）：@vitest-environment jsdom CodeBlock + the shiki singleton: registered grammars highlight into token spans colored by --shiki-* custom properties; unknown/absent languages take the identical-geometry plain arm; aliases resolve; the trailing newline is displa...。
  • 固定版本：源码链接固定到官方提交 aa6c361a972c8369148dea7380bb5c21c24e07ec。

packages/client/ui-primitives/tests/diff-block.client.spec.tsx ​

  • 所属层：packages/client：可复用的 Harness 功能包
  • 文件角色：测试用例
  • 这个文件有什么用：它用自动化测试检查浏览器端、用户界面的具体场景，包括“DiffBlock structure”、“renders a create as a path header and an added block (no removed side)”、“renders an edit as a removed block above an added block”、“opens a same-file second hunk with a gap instead of repeating the path”；这些断言把“应该发生什么”变成可以重复运行的证据。
  • 为什么这样设计：把测试主题“DiffBlock structure”写成独立测试用例，读者可以从输入、触发动作和断言反推实现的不变量；不同回归问题也不会互相遮蔽。
  • 文件级设计证据：源码顶部注释把它定位为“@vitest-environment jsdom DiffBlock: the per-file hunk rows (path header, removed block, added block), the same-file second-hunk gap separator, the +A -R · N file(s) footer and its singular/plural, the head/tail height cap and its expand control, the empty-...”；固定提交中扫描到的声明包括 bodyRows、changeRows、added；本地静态 import 图显示它直接依赖 1 个源文件，并被 0 个源文件直接引用。
  • 直接协作者：packages/client/ui-primitives/README.md、packages/client/ui-primitives/src/index.ts
  • 对应测试：本文件本身就是测试用例。
  • 测试关联依据：本文件本身就是测试用例，不把同目录的其他测试冒充成它的“对应测试”。
  • 阅读顺序：先看它直接导入的被测实现 packages/client/ui-primitives/src/index.ts，再读本文件的测试主题、输入和断言；最后对照测试支持和失败输出。
  • 代码证据：固定提交归档实际读取结果：约 182 行；扫描到的声明包括 bodyRows、changeRows、added；扫描到的测试主题包括 “DiffBlock structure”、“renders a create as a path header and an added block (no removed side)”、“renders an edit as a removed block above an added block”、“opens a same-file second hunk with a gap instead of repeating the path”、“opens a new file with its own path header”、“renders nothing for empty diffs”；源码顶部原注释（英文，仅作回查线索）：@vitest-environment jsdom DiffBlock: the per-file hunk rows (path header, removed block, added block), the same-file second-hunk gap separator, the +A -R · N file(s) footer and its singular/plural, the head/tail height cap and its expand control, the empty-...。
  • 固定版本：源码链接固定到官方提交 aa6c361a972c8369148dea7380bb5c21c24e07ec。

packages/client/ui-primitives/tests/hover-card.client.spec.tsx ​

  • 所属层：packages/client：可复用的 Harness 功能包
  • 文件角色：测试用例
  • 这个文件有什么用：它用自动化测试检查浏览器端、用户界面的具体场景，包括“HoverCard”、“opens after the dwell delay, positioned right of the anchor”、“honors a custom openDelayMs”、“pointerleave before the delay cancels the pending open”；这些断言把“应该发生什么”变成可以重复运行的证据。
  • 为什么这样设计：把测试主题“HoverCard”写成独立测试用例，读者可以从输入、触发动作和断言反推实现的不变量；不同回归问题也不会互相遮蔽。
  • 文件级设计证据：源码顶部注释把它定位为“@vitest-environment jsdom”；固定提交中扫描到的声明包括 stubAnchorRect、mount、installClipboard；本地静态 import 图显示它直接依赖 2 个源文件，并被 0 个源文件直接引用。
  • 直接协作者：packages/client/ui-primitives/README.md、packages/client/ui-primitives/src/index.ts、packages/client/ui-primitives/src/pointer-grace.ts
  • 对应测试：本文件本身就是测试用例。
  • 测试关联依据：本文件本身就是测试用例，不把同目录的其他测试冒充成它的“对应测试”。
  • 阅读顺序：先看它直接导入的被测实现 packages/client/ui-primitives/src/index.ts、packages/client/ui-primitives/src/pointer-grace.ts，再读本文件的测试主题、输入和断言；最后对照测试支持和失败输出。
  • 代码证据：固定提交归档实际读取结果：约 429 行；扫描到的声明包括 stubAnchorRect、mount、installClipboard；扫描到的测试主题包括 “HoverCard”、“opens after the dwell delay, positioned right of the anchor”、“honors a custom openDelayMs”、“pointerleave before the delay cancels the pending open”、“pointerleave closes an open card a grace later; re-enter after that restarts the dwell”、“reaching the card inside the grace keeps it open without restarting the dwell”；源码顶部原注释（英文，仅作回查线索）：@vitest-environment jsdom。
  • 固定版本：源码链接固定到官方提交 aa6c361a972c8369148dea7380bb5c21c24e07ec。

packages/client/ui-primitives/tests/icons.client.spec.tsx ​

  • 所属层：packages/client：可复用的 Harness 功能包
  • 文件角色：测试用例
  • 这个文件有什么用：它用自动化测试检查浏览器端、用户界面的具体场景，包括“ic_ds_ icon set”、“exports the full icon set (46 deepsuite + 20 figma extracts + four product glyphs outsi...”、“size and className props land on the root svg”、“each glyph defaults to its own drawn size, not one set-wide default”；这些断言把“应该发生什么”变成可以重复运行的证据。
  • 为什么这样设计：把测试主题“ic_ds_ icon set”写成独立测试用例，读者可以从输入、触发动作和断言反推实现的不变量；不同回归问题也不会互相遮蔽。
  • 文件级设计证据：源码顶部注释把它定位为“@vitest-environment jsdom”；本地静态 import 图显示它直接依赖 1 个源文件，并被 0 个源文件直接引用。
  • 直接协作者：packages/client/ui-primitives/README.md、packages/client/ui-primitives/src/index.ts
  • 对应测试：本文件本身就是测试用例。
  • 测试关联依据：本文件本身就是测试用例，不把同目录的其他测试冒充成它的“对应测试”。
  • 阅读顺序：先看它直接导入的被测实现 packages/client/ui-primitives/src/index.ts，再读本文件的测试主题、输入和断言；最后对照测试支持和失败输出。
  • 代码证据：固定提交归档实际读取结果：约 81 行；扫描到的测试主题包括 “ic_ds_ icon set”、“exports the full icon set (46 deepsuite + 20 figma extracts + four product glyphs outside those sets)”、“size and className props land on the root svg”、“each glyph defaults to its own drawn size, not one set-wide default”、“renders reusable goal glyphs without document-global ids”、“FishLogo”；源码顶部原注释（英文，仅作回查线索）：@vitest-environment jsdom。
  • 固定版本：源码链接固定到官方提交 aa6c361a972c8369148dea7380bb5c21c24e07ec。

packages/client/ui-primitives/tests/invariant.client.spec.ts ​

  • 所属层：packages/client：可复用的 Harness 功能包
  • 文件角色：测试用例
  • 这个文件有什么用：它用自动化测试检查浏览器端、用户界面的具体场景，包括“invariant companion”、“registers under the package name with an empty installer”；这些断言把“应该发生什么”变成可以重复运行的证据。
  • 为什么这样设计：把测试主题“invariant companion”写成独立测试用例，读者可以从输入、触发动作和断言反推实现的不变量；不同回归问题也不会互相遮蔽。
  • 文件级设计证据：本次固定提交归档没有扫描到顶部注释、顶层声明或专门的结构线索；本地静态 import 图显示它直接依赖 3 个源文件，并被 0 个源文件直接引用。
  • 直接协作者：packages/client/ui-primitives/README.md、packages/client/ui-primitives/src/invariant.ts、packages/runtime-diagnostics/invariants/src/index.ts、vendor/cordis/src/index.ts
  • 对应测试：本文件本身就是测试用例。
  • 测试关联依据：本文件本身就是测试用例，不把同目录的其他测试冒充成它的“对应测试”。
  • 阅读顺序：先看它直接导入的被测实现 packages/client/ui-primitives/src/invariant.ts、packages/runtime-diagnostics/invariants/src/index.ts、vendor/cordis/src/index.ts，再读本文件的测试主题、输入和断言；最后对照测试支持和失败输出。
  • 代码证据：固定提交归档实际读取结果：约 12 行；扫描到的测试主题包括 “invariant companion”、“registers under the package name with an empty installer”。
  • 固定版本：源码链接固定到官方提交 aa6c361a972c8369148dea7380bb5c21c24e07ec。

packages/client/ui-primitives/tests/json-tree.client.spec.tsx ​

  • 所属层：packages/client：可复用的 Harness 功能包
  • 文件角色：测试用例
  • 这个文件有什么用：它用自动化测试检查浏览器端、用户界面的具体场景，包括“JsonTree”、“keeps the top level open and renders expandable value previews”、“moves the single tab stop between visible expanders with arrow keys”、“copies an array element path without recovering data from rendered labels”；这些断言把“应该发生什么”变成可以重复运行的证据。
  • 为什么这样设计：把测试主题“JsonTree”写成独立测试用例，读者可以从输入、触发动作和断言反推实现的不变量；不同回归问题也不会互相遮蔽。
  • 文件级设计证据：源码顶部注释把它定位为“@vitest-environment jsdom”；本地静态 import 图显示它直接依赖 1 个源文件，并被 0 个源文件直接引用。
  • 直接协作者：packages/client/ui-primitives/README.md、packages/client/ui-primitives/src/index.ts
  • 对应测试：本文件本身就是测试用例。
  • 测试关联依据：本文件本身就是测试用例，不把同目录的其他测试冒充成它的“对应测试”。
  • 阅读顺序：先看它直接导入的被测实现 packages/client/ui-primitives/src/index.ts，再读本文件的测试主题、输入和断言；最后对照测试支持和失败输出。
  • 代码证据：固定提交归档实际读取结果：约 339 行；扫描到的测试主题包括 “JsonTree”、“keeps the top level open and renders expandable value previews”、“moves the single tab stop between visible expanders with arrow keys”、“copies an array element path without recovering data from rendered labels”、“renders empty containers, JSON-adjacent primitives, and bounded deep previews”、“renders child commas and lets a clickable property label toggle its node”；源码顶部原注释（英文，仅作回查线索）：@vitest-environment jsdom。
  • 固定版本：源码链接固定到官方提交 aa6c361a972c8369148dea7380bb5c21c24e07ec。

packages/client/ui-primitives/tests/markdown-dom-parity.client.spec.tsx ​

  • 所属层：packages/client：可复用的 Harness 功能包
  • 文件角色：测试用例
  • 这个文件有什么用：它用自动化测试检查浏览器端、用户界面的具体场景，包括“MarkdownText DOM parity fixtures”、“settled: ${name}”、“streaming: ${name}”；这些断言把“应该发生什么”变成可以重复运行的证据。
  • 为什么这样设计：把测试主题“MarkdownText DOM parity fixtures”写成独立测试用例，读者可以从输入、触发动作和断言反推实现的不变量；不同回归问题也不会互相遮蔽。
  • 文件级设计证据：源码顶部注释把它定位为“@vitest-environment jsdom DOM-parity contract for MarkdownText: every corpus document's rendered DOM is pinned as a file snapshot. The fixtures were recorded from the react-markdown implementation this renderer replaced; the custom mdast renderer must repro...”；固定提交中扫描到的声明包括 serialize、serializeChildren、renderCase；本地静态 import 图显示它直接依赖 1 个源文件，并被 0 个源文件直接引用。
  • 直接协作者：packages/client/ui-primitives/README.md、packages/client/ui-primitives/src/index.ts
  • 对应测试：本文件本身就是测试用例。
  • 测试关联依据：本文件本身就是测试用例，不把同目录的其他测试冒充成它的“对应测试”。
  • 阅读顺序：先看它直接导入的被测实现 packages/client/ui-primitives/src/index.ts，再读本文件的测试主题、输入和断言；最后对照测试支持和失败输出。
  • 代码证据：固定提交归档实际读取结果：约 276 行；扫描到的声明包括 serialize、serializeChildren、renderCase；扫描到的测试主题包括 “MarkdownText DOM parity fixtures”、“settled: ${name}”、“streaming: ${name}”；源码顶部原注释（英文，仅作回查线索）：@vitest-environment jsdom DOM-parity contract for MarkdownText: every corpus document's rendered DOM is pinned as a file snapshot. The fixtures were recorded from the react-markdown implementation this renderer replaced; the custom mdast renderer must repro...。
  • 固定版本：源码链接固定到官方提交 aa6c361a972c8369148dea7380bb5c21c24e07ec。

packages/client/ui-primitives/tests/markdown-incremental.client.spec.tsx ​

  • 所属层：packages/client：可复用的 Harness 功能包
  • 文件角色：测试用例
  • 这个文件有什么用：它用自动化测试检查浏览器端、用户界面的具体场景，包括“incremental streaming rendering”、“matches a fresh render at every prefix (chunk=${chunkSize})”、“keeps frozen block DOM nodes across freezes instead of remounting”、“recovers when the text diverges instead of appending”；这些断言把“应该发生什么”变成可以重复运行的证据。
  • 为什么这样设计：把测试主题“incremental streaming rendering”写成独立测试用例，读者可以从输入、触发动作和断言反推实现的不变量；不同回归问题也不会互相遮蔽。
  • 文件级设计证据：源码顶部注释把它定位为“@vitest-environment jsdom Incremental streaming behavior: a MarkdownText kept mounted across append-only rerenders must show, at every step, exactly the DOM a fresh mount of the same prefix shows, while reusing the frozen blocks' DOM nodes instead of remoun...”；本地静态 import 图显示它直接依赖 3 个源文件，并被 0 个源文件直接引用。
  • 直接协作者：packages/client/ui-primitives/README.md、packages/client/ui-primitives/src/index.ts、packages/client/ui-primitives/src/markdown/incremental.ts、packages/client/ui-primitives/src/markdown/parse.ts
  • 对应测试：本文件本身就是测试用例。
  • 测试关联依据：本文件本身就是测试用例，不把同目录的其他测试冒充成它的“对应测试”。
  • 阅读顺序：先看它直接导入的被测实现 packages/client/ui-primitives/src/index.ts、packages/client/ui-primitives/src/markdown/incremental.ts、packages/client/ui-primitives/src/markdown/parse.ts，再读本文件的测试主题、输入和断言；最后对照测试支持和失败输出。
  • 代码证据：固定提交归档实际读取结果：约 427 行；扫描到的测试主题包括 “incremental streaming rendering”、“matches a fresh render at every prefix (chunk=${chunkSize})”、“keeps frozen block DOM nodes across freezes instead of remounting”、“recovers when the text diverges instead of appending”、“drops the streaming cache when the copy labels change identity”、“settles into the full math-enabled render after streaming”；源码顶部原注释（英文，仅作回查线索）：@vitest-environment jsdom Incremental streaming behavior: a MarkdownText kept mounted across append-only rerenders must show, at every step, exactly the DOM a fresh mount of the same prefix shows, while reusing the frozen blocks' DOM nodes instead of remoun...。
  • 固定版本：源码链接固定到官方提交 aa6c361a972c8369148dea7380bb5c21c24e07ec。

packages/client/ui-primitives/tests/markdown-plain-text.client.spec.ts ​

  • 所属层：packages/client：可复用的 Harness 功能包
  • 文件角色：测试用例
  • 这个文件有什么用：它用自动化测试检查浏览器端、用户界面的具体场景，包括“extractMarkdownPlainText”、“projects the complete GFM document without presentation syntax”、“selects the first visible line or first semantic paragraph”、“preserves raw HTML while removing Markdown presentation markup”；这些断言把“应该发生什么”变成可以重复运行的证据。
  • 为什么这样设计：把测试主题“extractMarkdownPlainText”写成独立测试用例，读者可以从输入、触发动作和断言反推实现的不变量；不同回归问题也不会互相遮蔽。
  • 文件级设计证据：本次固定提交归档没有扫描到顶部注释、顶层声明或专门的结构线索；本地静态 import 图显示它直接依赖 1 个源文件，并被 0 个源文件直接引用。
  • 直接协作者：packages/client/ui-primitives/README.md、packages/client/ui-primitives/src/index.ts
  • 对应测试：本文件本身就是测试用例。
  • 测试关联依据：本文件本身就是测试用例，不把同目录的其他测试冒充成它的“对应测试”。
  • 阅读顺序：先看它直接导入的被测实现 packages/client/ui-primitives/src/index.ts，再读本文件的测试主题、输入和断言；最后对照测试支持和失败输出。
  • 代码证据：固定提交归档实际读取结果：约 71 行；扫描到的测试主题包括 “extractMarkdownPlainText”、“projects the complete GFM document without presentation syntax”、“selects the first visible line or first semantic paragraph”、“preserves raw HTML while removing Markdown presentation markup”、“projects GFM tables, references, hard breaks, and block structure”。
  • 固定版本：源码链接固定到官方提交 aa6c361a972c8369148dea7380bb5c21c24e07ec。

packages/client/ui-primitives/tests/markdown-render-units.client.spec.tsx ​

  • 所属层：packages/client：可复用的 Harness 功能包
  • 文件角色：测试用例
  • 这个文件有什么用：它用自动化测试检查浏览器端、用户界面、渲染的具体场景，包括“renderBlocks over hand-built trees”、“reverts unresolved references to their bracketed source”、“keeps the first definition when identifiers repeat”、“renders a bare list item, computing looseness from the item itself”；这些断言把“应该发生什么”变成可以重复运行的证据。
  • 为什么这样设计：把测试主题“renderBlocks over hand-built trees”写成独立测试用例，读者可以从输入、触发动作和断言反推实现的不变量；不同回归问题也不会互相遮蔽。
  • 文件级设计证据：源码顶部注释把它定位为“@vitest-environment jsdom Branch coverage for the mdast renderer that real parses cannot reach: the grammar only emits references whose definitions exist, always stamps positions and align arrays, and never emits bare list items — but the renderer is a pure...”；固定提交中扫描到的声明包括 makeContext、renderNodes；本地静态 import 图显示它直接依赖 2 个源文件，并被 0 个源文件直接引用。
  • 直接协作者：packages/client/ui-primitives/README.md、packages/client/ui-primitives/src/index.ts、packages/client/ui-primitives/src/markdown/render.tsx
  • 对应测试：本文件本身就是测试用例。
  • 测试关联依据：本文件本身就是测试用例，不把同目录的其他测试冒充成它的“对应测试”。
  • 阅读顺序：先看它直接导入的被测实现 packages/client/ui-primitives/src/index.ts、packages/client/ui-primitives/src/markdown/render.tsx，再读本文件的测试主题、输入和断言；最后对照测试支持和失败输出。
  • 代码证据：固定提交归档实际读取结果：约 234 行；扫描到的声明包括 makeContext、renderNodes；扫描到的测试主题包括 “renderBlocks over hand-built trees”、“reverts unresolved references to their bracketed source”、“keeps the first definition when identifiers repeat”、“renders a bare list item, computing looseness from the item itself”、“renders spread-null lists and align-less tables”、“renders a rowless align-less table as an empty fill wrapper”；源码顶部原注释（英文，仅作回查线索）：@vitest-environment jsdom Branch coverage for the mdast renderer that real parses cannot reach: the grammar only emits references whose definitions exist, always stamps positions and align arrays, and never emits bare list items — but the renderer is a pure...。
  • 固定版本：源码链接固定到官方提交 aa6c361a972c8369148dea7380bb5c21c24e07ec。

packages/client/ui-primitives/tests/markdown.client.spec.tsx ​

  • 所属层：packages/client：可复用的 Harness 功能包
  • 文件角色：测试用例
  • 这个文件有什么用：它用自动化测试检查浏览器端、用户界面的具体场景，包括“MessageText”、“renders the text verbatim”、“MarkdownText”、“renders CommonMark and GFM elements as semantic DOM”；这些断言把“应该发生什么”变成可以重复运行的证据。
  • 为什么这样设计：把测试主题“MessageText”写成独立测试用例，读者可以从输入、触发动作和断言反推实现的不变量；不同回归问题也不会互相遮蔽。
  • 文件级设计证据：源码顶部注释把它定位为“@vitest-environment jsdom”；本地静态 import 图显示它直接依赖 3 个源文件，并被 0 个源文件直接引用。
  • 直接协作者：packages/client/ui-primitives/README.md、packages/client/ui-primitives/src/index.ts、packages/client/ui-primitives/src/markdown/cjkFriendlyStrong.ts、packages/client/ui-primitives/src/markdown/mathCompatibility.ts
  • 对应测试：本文件本身就是测试用例。
  • 测试关联依据：本文件本身就是测试用例，不把同目录的其他测试冒充成它的“对应测试”。
  • 阅读顺序：先看它直接导入的被测实现 packages/client/ui-primitives/src/index.ts、packages/client/ui-primitives/src/markdown/cjkFriendlyStrong.ts、packages/client/ui-primitives/src/markdown/mathCompatibility.ts，再读本文件的测试主题、输入和断言；最后对照测试支持和失败输出。
  • 代码证据：固定提交归档实际读取结果：约 518 行；扫描到的测试主题包括 “MessageText”、“renders the text verbatim”、“MarkdownText”、“renders CommonMark and GFM elements as semantic DOM”、“closes punctuation-terminated strong emphasis before adjacent CJK text”、“keeps the CJK strong extension out of escaped, code, math, and ASCII contexts”；源码顶部原注释（英文，仅作回查线索）：@vitest-environment jsdom。
  • 固定版本：源码链接固定到官方提交 aa6c361a972c8369148dea7380bb5c21c24e07ec。

packages/client/ui-primitives/tests/onboarding-surface.client.spec.tsx ​

  • 所属层：packages/client：可复用的 Harness 功能包
  • 文件角色：测试用例
  • 这个文件有什么用：它用自动化测试检查浏览器端、用户界面的具体场景，包括“OnboardingSurface”、“portals the overlay chrome to document.body around its content”、“holds #root inert for exactly its own lifetime”、“renders without an #root element (compositions that mount elsewhere)”；这些断言把“应该发生什么”变成可以重复运行的证据。
  • 为什么这样设计：把测试主题“OnboardingSurface”写成独立测试用例，读者可以从输入、触发动作和断言反推实现的不变量；不同回归问题也不会互相遮蔽。
  • 文件级设计证据：源码顶部注释把它定位为“@vitest-environment jsdom”；本地静态 import 图显示它直接依赖 1 个源文件，并被 0 个源文件直接引用。
  • 直接协作者：packages/client/ui-primitives/README.md、packages/client/ui-primitives/src/index.ts
  • 对应测试：本文件本身就是测试用例。
  • 测试关联依据：本文件本身就是测试用例，不把同目录的其他测试冒充成它的“对应测试”。
  • 阅读顺序：先看它直接导入的被测实现 packages/client/ui-primitives/src/index.ts，再读本文件的测试主题、输入和断言；最后对照测试支持和失败输出。
  • 代码证据：固定提交归档实际读取结果：约 47 行；扫描到的测试主题包括 “OnboardingSurface”、“portals the overlay chrome to document.body around its content”、“holds #root inert for exactly its own lifetime”、“renders without an #root element (compositions that mount elsewhere)”；源码顶部原注释（英文，仅作回查线索）：@vitest-environment jsdom。
  • 固定版本：源码链接固定到官方提交 aa6c361a972c8369148dea7380bb5c21c24e07ec。

packages/client/ui-primitives/tests/read-block.client.spec.tsx ​

  • 所属层：packages/client：可复用的 Harness 功能包
  • 文件角色：测试用例
  • 这个文件有什么用：它用自动化测试检查浏览器端、用户界面的具体场景，包括“highlightLines”、“tokenizes a registered grammar into per-line css-variables runs”、“colors every run through a --shiki-* custom property”、“drops the trailing terminator line so the run count matches the source lines”；这些断言把“应该发生什么”变成可以重复运行的证据。
  • 为什么这样设计：把测试主题“highlightLines”写成独立测试用例，读者可以从输入、触发动作和断言反推实现的不变量；不同回归问题也不会互相遮蔽。
  • 文件级设计证据：源码顶部注释把它定位为“@vitest-environment jsdom ReadBlock + the highlightLines token path: the banner (label, language, the "showing N of M" note only when the read is a window, copy control), the gutter-numbered rows keeping the file's own line numbers, the shiki per-line highl...”；固定提交中扫描到的声明包括 lines、rowTexts、gutters；本地静态 import 图显示它直接依赖 2 个源文件，并被 0 个源文件直接引用。
  • 直接协作者：packages/client/ui-primitives/README.md、packages/client/ui-primitives/src/index.ts、packages/client/ui-primitives/src/markdown/highlight.ts
  • 对应测试：本文件本身就是测试用例。
  • 测试关联依据：本文件本身就是测试用例，不把同目录的其他测试冒充成它的“对应测试”。
  • 阅读顺序：先看它直接导入的被测实现 packages/client/ui-primitives/src/index.ts、packages/client/ui-primitives/src/markdown/highlight.ts，再读本文件的测试主题、输入和断言；最后对照测试支持和失败输出。
  • 代码证据：固定提交归档实际读取结果：约 241 行；扫描到的声明包括 lines、rowTexts、gutters；扫描到的测试主题包括 “highlightLines”、“tokenizes a registered grammar into per-line css-variables runs”、“colors every run through a --shiki-* custom property”、“drops the trailing terminator line so the run count matches the source lines”、“keeps a genuinely blank final line when the source ends in two newlines”、“returns undefined for an unknown or absent language”；源码顶部原注释（英文，仅作回查线索）：@vitest-environment jsdom ReadBlock + the highlightLines token path: the banner (label, language, the "showing N of M" note only when the read is a window, copy control), the gutter-numbered rows keeping the file's own line numbers, the shiki per-line highl...。
  • 固定版本：源码链接固定到官方提交 aa6c361a972c8369148dea7380bb5c21c24e07ec。

packages/client/ui-primitives/tests/search-block.client.spec.tsx ​

  • 所属层：packages/client：可复用的 Harness 功能包
  • 文件角色：测试用例
  • 这个文件有什么用：它用自动化测试检查浏览器端、用户界面的具体场景，包括“SearchBlock matches kind”、“renders each file as a header group with its matched lines”、“collapses and re-expands a single file group without touching the others”、“folds the pre-cap total into the summary when truncated”；这些断言把“应该发生什么”变成可以重复运行的证据。
  • 为什么这样设计：把测试主题“SearchBlock matches kind”写成独立测试用例，读者可以从输入、触发动作和断言反推实现的不变量；不同回归问题也不会互相遮蔽。
  • 文件级设计证据：源码顶部注释把它定位为“@vitest-environment jsdom SearchBlock: both kinds (grouped grep matches and a flat glob path list), the folded truncation summary, the empty arm, per-file collapse/expand, the head/tail height cap and its expand control, the tail slice restoring its owning ...”；固定提交中扫描到的声明包括 lines、fileHeaders、group；本地静态 import 图显示它直接依赖 1 个源文件，并被 0 个源文件直接引用。
  • 直接协作者：packages/client/ui-primitives/README.md、packages/client/ui-primitives/src/index.ts
  • 对应测试：本文件本身就是测试用例。
  • 测试关联依据：本文件本身就是测试用例，不把同目录的其他测试冒充成它的“对应测试”。
  • 阅读顺序：先看它直接导入的被测实现 packages/client/ui-primitives/src/index.ts，再读本文件的测试主题、输入和断言；最后对照测试支持和失败输出。
  • 代码证据：固定提交归档实际读取结果：约 214 行；扫描到的声明包括 lines、fileHeaders、group；扫描到的测试主题包括 “SearchBlock matches kind”、“renders each file as a header group with its matched lines”、“collapses and re-expands a single file group without touching the others”、“folds the pre-cap total into the summary when truncated”、“SearchBlock paths kind”、“renders a flat path list with a path-count summary”；源码顶部原注释（英文，仅作回查线索）：@vitest-environment jsdom SearchBlock: both kinds (grouped grep matches and a flat glob path list), the folded truncation summary, the empty arm, per-file collapse/expand, the head/tail height cap and its expand control, the tail slice restoring its owning ...。
  • 固定版本：源码链接固定到官方提交 aa6c361a972c8369148dea7380bb5c21c24e07ec。

packages/client/ui-primitives/tests/state-dot.client.spec.tsx ​

  • 所属层：packages/client：可复用的 Harness 功能包
  • 文件角色：测试用例
  • 这个文件有什么用：它用自动化测试检查浏览器端、用户界面的具体场景，包括“StateDot”、“solid states are spans; ongoing is an svg pixel matrix”、“sizes via the size prop in both shapes”、“rejects unknown states at the type level”；这些断言把“应该发生什么”变成可以重复运行的证据。
  • 为什么这样设计：把测试主题“StateDot”写成独立测试用例，读者可以从输入、触发动作和断言反推实现的不变量；不同回归问题也不会互相遮蔽。
  • 文件级设计证据：源码顶部注释把它定位为“@vitest-environment jsdom”；本地静态 import 图显示它直接依赖 1 个源文件，并被 0 个源文件直接引用。
  • 直接协作者：packages/client/ui-primitives/README.md、packages/client/ui-primitives/src/index.ts
  • 对应测试：本文件本身就是测试用例。
  • 测试关联依据：本文件本身就是测试用例，不把同目录的其他测试冒充成它的“对应测试”。
  • 阅读顺序：先看它直接导入的被测实现 packages/client/ui-primitives/src/index.ts，再读本文件的测试主题、输入和断言；最后对照测试支持和失败输出。
  • 代码证据：固定提交归档实际读取结果：约 46 行；扫描到的测试主题包括 “StateDot”、“solid states are spans; ongoing is an svg pixel matrix”、“sizes via the size prop in both shapes”、“rejects unknown states at the type level”；源码顶部原注释（英文，仅作回查线索）：@vitest-environment jsdom。
  • 固定版本：源码链接固定到官方提交 aa6c361a972c8369148dea7380bb5c21c24e07ec。

packages/client/ui-primitives/tests/terminal-block.client.spec.tsx ​

  • 所属层：packages/client：可复用的 Harness 功能包
  • 文件角色：测试用例
  • 这个文件有什么用：它用自动化测试检查浏览器端、用户界面、持久终端的具体场景，包括“TerminalBlock prompt label”、“collapses the home directory itself to ~”、“shows only the last segment below home”、“ignores trailing separators on both the cwd and home”；这些断言把“应该发生什么”变成可以重复运行的证据。
  • 为什么这样设计：把测试主题“TerminalBlock prompt label”写成独立测试用例，读者可以从输入、触发动作和断言反推实现的不变量；不同回归问题也不会互相遮蔽。
  • 文件级设计证据：源码顶部注释把它定位为“@vitest-environment jsdom TerminalBlock: the prompt label's cwd shortening, the running/empty/settled arms, the prompt line's run-state dot, the exit-status pill, the head/tail height cap and its expand control, and the copy control writing the raw output o...”；固定提交中扫描到的声明包括 outputLines、runStateOf、promptRows、body；本地静态 import 图显示它直接依赖 2 个源文件，并被 0 个源文件直接引用。
  • 直接协作者：packages/client/ui-primitives/README.md、packages/client/ui-primitives/src/clipboard.ts、packages/client/ui-primitives/src/index.ts
  • 对应测试：本文件本身就是测试用例。
  • 测试关联依据：本文件本身就是测试用例，不把同目录的其他测试冒充成它的“对应测试”。
  • 阅读顺序：先看它直接导入的被测实现 packages/client/ui-primitives/src/clipboard.ts、packages/client/ui-primitives/src/index.ts，再读本文件的测试主题、输入和断言；最后对照测试支持和失败输出。
  • 代码证据：固定提交归档实际读取结果：约 430 行；扫描到的声明包括 outputLines、runStateOf、promptRows、body；扫描到的测试主题包括 “TerminalBlock prompt label”、“collapses the home directory itself to ~”、“shows only the last segment below home”、“ignores trailing separators on both the cwd and home”、“drops trailing separators before taking the last segment”、“takes the last segment when no home is known”；源码顶部原注释（英文，仅作回查线索）：@vitest-environment jsdom TerminalBlock: the prompt label's cwd shortening, the running/empty/settled arms, the prompt line's run-state dot, the exit-status pill, the head/tail height cap and its expand control, and the copy control writing the raw output o...。
  • 固定版本：源码链接固定到官方提交 aa6c361a972c8369148dea7380bb5c21c24e07ec。

packages/client/ui-primitives/tests/toast.client.spec.tsx ​

  • 所属层：packages/client：可复用的 Harness 功能包
  • 文件角色：测试用例
  • 这个文件有什么用：它用自动化测试检查浏览器端、用户界面的具体场景，包括“Toast”、“announces its text and reports done after the hold-and-fade lifetime”、“centers over its anchor and re-measures on window resize”、“renders without an icon and cancels its timer on unmount”；这些断言把“应该发生什么”变成可以重复运行的证据。
  • 为什么这样设计：把测试主题“Toast”写成独立测试用例，读者可以从输入、触发动作和断言反推实现的不变量；不同回归问题也不会互相遮蔽。
  • 文件级设计证据：源码顶部注释把它定位为“@vitest-environment jsdom”；本地静态 import 图显示它直接依赖 1 个源文件，并被 0 个源文件直接引用。
  • 直接协作者：packages/client/ui-primitives/README.md、packages/client/ui-primitives/src/Toast.tsx
  • 对应测试：本文件本身就是测试用例。
  • 测试关联依据：本文件本身就是测试用例，不把同目录的其他测试冒充成它的“对应测试”。
  • 阅读顺序：先看它直接导入的被测实现 packages/client/ui-primitives/src/Toast.tsx，再读本文件的测试主题、输入和断言；最后对照测试支持和失败输出。
  • 代码证据：固定提交归档实际读取结果：约 57 行；扫描到的测试主题包括 “Toast”、“announces its text and reports done after the hold-and-fade lifetime”、“centers over its anchor and re-measures on window resize”、“renders without an icon and cancels its timer on unmount”；源码顶部原注释（英文，仅作回查线索）：@vitest-environment jsdom。
  • 固定版本：源码链接固定到官方提交 aa6c361a972c8369148dea7380bb5c21c24e07ec。

packages/client/ui-primitives/tests/tooltip.client.spec.tsx ​

  • 所属层：packages/client：可复用的 Harness 功能包
  • 文件角色：测试用例
  • 这个文件有什么用：它用自动化测试检查浏览器端、用户界面的具体场景，包括“Tooltip”、“resolves lazy labels only after the bubble becomes visible”、“can delay pointer hover without delaying keyboard focus”、“shows the bubble to the right on hover and hides it on leave”；这些断言把“应该发生什么”变成可以重复运行的证据。
  • 为什么这样设计：把测试主题“Tooltip”写成独立测试用例，读者可以从输入、触发动作和断言反推实现的不变量；不同回归问题也不会互相遮蔽。
  • 文件级设计证据：源码顶部注释把它定位为“@vitest-environment jsdom”；本地静态 import 图显示它直接依赖 1 个源文件，并被 0 个源文件直接引用。
  • 直接协作者：packages/client/ui-primitives/README.md、packages/client/ui-primitives/src/index.ts
  • 对应测试：本文件本身就是测试用例。
  • 测试关联依据：本文件本身就是测试用例，不把同目录的其他测试冒充成它的“对应测试”。
  • 阅读顺序：先看它直接导入的被测实现 packages/client/ui-primitives/src/index.ts，再读本文件的测试主题、输入和断言；最后对照测试支持和失败输出。
  • 代码证据：固定提交归档实际读取结果：约 357 行；扫描到的测试主题包括 “Tooltip”、“resolves lazy labels only after the bubble becomes visible”、“can delay pointer hover without delaying keyboard focus”、“shows the bubble to the right on hover and hides it on leave”、“supports bottom placement and the focus/blur channel”、“caps the bubble width where the label would otherwise slab across the surface”；源码顶部原注释（英文，仅作回查线索）：@vitest-environment jsdom。
  • 固定版本：源码链接固定到官方提交 aa6c361a972c8369148dea7380bb5c21c24e07ec。

packages/client/ui-primitives/tests/use-anchored-position.client.spec.tsx ​

  • 所属层：packages/client：可复用的 Harness 功能包
  • 文件角色：测试用例
  • 这个文件有什么用：它用自动化测试检查浏览器端、用户界面的具体场景，包括“useAnchoredPosition”、“observes the panel while open and disconnects when it closes”、“replaces the panel when its own size changes”、“still places the panel where ResizeObserver does not exist”；这些断言把“应该发生什么”变成可以重复运行的证据。
  • 为什么这样设计：把测试主题“useAnchoredPosition”写成独立测试用例，读者可以从输入、触发动作和断言反推实现的不变量；不同回归问题也不会互相遮蔽。
  • 文件级设计证据：源码顶部注释把它定位为“@vitest-environment jsdom”；固定提交中扫描到的声明包括 stubResizeObserver、Host；本地静态 import 图显示它直接依赖 1 个源文件，并被 0 个源文件直接引用。
  • 直接协作者：packages/client/ui-primitives/README.md、packages/client/ui-primitives/src/useAnchoredPosition.ts
  • 对应测试：本文件本身就是测试用例。
  • 测试关联依据：本文件本身就是测试用例，不把同目录的其他测试冒充成它的“对应测试”。
  • 阅读顺序：先看它直接导入的被测实现 packages/client/ui-primitives/src/useAnchoredPosition.ts，再读本文件的测试主题、输入和断言；最后对照测试支持和失败输出。
  • 代码证据：固定提交归档实际读取结果：约 111 行；扫描到的声明包括 stubResizeObserver、Host；扫描到的测试主题包括 “useAnchoredPosition”、“observes the panel while open and disconnects when it closes”、“replaces the panel when its own size changes”、“still places the panel where ResizeObserver does not exist”、“attaches no listeners while the element is closed”；源码顶部原注释（英文，仅作回查线索）：@vitest-environment jsdom。
  • 固定版本：源码链接固定到官方提交 aa6c361a972c8369148dea7380bb5c21c24e07ec。

packages/client/ui-primitives/tests/web-block.client.spec.tsx ​

  • 所属层：packages/client：可复用的 Harness 功能包
  • 文件角色：测试用例
  • 这个文件有什么用：它用自动化测试检查浏览器端、用户界面、Web 界面的具体场景，包括“WebBlock search card”、“renders the answer above the citation list”、“omits the answer block when there is no answer”、“shows the empty-state note when a search returns no answer and no sources”；这些断言把“应该发生什么”变成可以重复运行的证据。
  • 为什么这样设计：把测试主题“WebBlock search card”写成独立测试用例，读者可以从输入、触发动作和断言反推实现的不变量；不同回归问题也不会互相遮蔽。
  • 文件级设计证据：源码顶部注释把它定位为“@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 full source list under one <ol>, and the truncated indicator; the fetch card...”；固定提交中扫描到的声明包括 sources；本地静态 import 图显示它直接依赖 1 个源文件，并被 0 个源文件直接引用。
  • 直接协作者：packages/client/ui-primitives/README.md、packages/client/ui-primitives/src/index.ts
  • 对应测试：本文件本身就是测试用例。
  • 测试关联依据：本文件本身就是测试用例，不把同目录的其他测试冒充成它的“对应测试”。
  • 阅读顺序：先看它直接导入的被测实现 packages/client/ui-primitives/src/index.ts，再读本文件的测试主题、输入和断言；最后对照测试支持和失败输出。
  • 代码证据：固定提交归档实际读取结果：约 178 行；扫描到的声明包括 sources；扫描到的测试主题包括 “WebBlock search card”、“renders the answer above the citation list”、“omits the answer block when there is no answer”、“shows the empty-state note when a search returns no answer and no sources”、“shows the source list, not the empty note, when a source is present”、“shows the source list when an empty source list still carries an answer”；源码顶部原注释（英文，仅作回查线索）：@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 full source list under one <ol>, and the truncated indicator; the fetch card...。
  • 固定版本：源码链接固定到官方提交 aa6c361a972c8369148dea7380bb5c21c24e07ec。

packages/client/ui-primitives/tsdown.config.ts ​

  • 所属层：packages/client：可复用的 Harness 功能包
  • 文件角色：构建或测试配置
  • 这个文件有什么用：它告诉工具链怎样处理浏览器端、用户界面：从哪里开始、使用哪个环境、解析哪些依赖以及输出什么产物；这些规则集中后，构建和测试才可重复。
  • 为什么这样设计：工具链配置独立于业务实现，构建、测试和发布可以复用同一套入口规则；改配置时也能单独看出运行环境变化。
  • 文件级设计证据：本次固定提交归档没有扫描到顶部注释、顶层声明或专门的结构线索；本地静态 import 图显示它直接依赖 1 个源文件，并被 0 个源文件直接引用。
  • 直接协作者：packages/client/ui-primitives/README.md、packages/client/tsdown.client.ts
  • 对应测试：没有确认到直接测试；公共入口可能仍有间接覆盖。
  • 测试关联依据：固定提交中没有找到直接或传递的本地静态 import，也没有找到明显的同包同名测试；公共入口可能仍有间接覆盖。
  • 阅读顺序：先读 packages/client/ui-primitives/README.md，再读本配置/脚本，沿着所在包的入口或服务确认它如何影响入口和产物，最后对照对应 gate 或快照测试。
  • 代码证据：固定提交归档实际读取结果：约 6 行。
  • 固定版本：源码链接固定到官方提交 aa6c361a972c8369148dea7380bb5c21c24e07ec。

packages/client/ui-reference ​

packages/client/ui-reference/src/client/index.ts ​

  • 所属层：packages/client：可复用的 Harness 功能包
  • 文件角色：模块入口
  • 这个文件有什么用：它把浏览器端、用户界面相关的公开能力集中导出，并决定调用者可以依赖哪些边界；调用者因此不必记住所有内部文件。
  • 为什么这样设计：入口文件把公开边界固定下来，内部文件可以继续拆分或替换；其他包只依赖入口暴露的 API，依赖方向更稳定。
  • 文件级设计证据：源码顶部注释把它定位为“Unified Web @ reference source. File and session discovery run through the cancellable generated Remote namespaces in parallel with deterministic ordering and labels. @module @deepseek-ai/dsh-client-ui-reference/client”；固定提交中扫描到的声明包括 inject、apply、fileCandidate、sessionCandidate、parseCandidate；本地静态 import 图显示它直接依赖 8 个源文件，并被 1 个源文件直接引用。
  • 直接协作者：packages/client/ui-reference/README.md、packages/api/remotes/src/client/index.ts、packages/client/locale/src/client/index.ts、packages/client/runtime/src/client/index.ts、packages/client/ui-reference/tests/browser-plugin.client.spec.ts
  • 对应测试：packages/client/ui-reference/tests/browser-plugin.client.spec.ts
  • 测试关联依据：固定提交源码中的本地静态 import 直接引用；测试用例直接导入了这个源文件。
  • 阅读顺序：先读 packages/client/ui-reference/README.md、入口和消费者，再读当前契约，沿着 packages/client/ui-reference/tests/browser-plugin.client.spec.ts 看它怎样约束运行时，最后对照 packages/client/ui-reference/tests/browser-plugin.client.spec.ts。
  • 代码证据：固定提交归档实际读取结果：约 136 行；扫描到的声明包括 inject、apply、fileCandidate、sessionCandidate、parseCandidate；源码顶部原注释（英文，仅作回查线索）：Unified Web @ reference source. File and session discovery run through the cancellable generated Remote namespaces in parallel with deterministic ordering and labels. @module @deepseek-ai/dsh-client-ui-reference/client。
  • 固定版本：源码链接固定到官方提交 aa6c361a972c8369148dea7380bb5c21c24e07ec。

packages/client/ui-reference/src/client/locales.ts ​

  • 所属层：packages/client：可复用的 Harness 功能包
  • 文件角色：本地化资源
  • 这个文件有什么用：它为浏览器端、用户界面、本地化提供语言文本、键名或本地化格式，让界面切换语言时不必改动业务流程。
  • 为什么这样设计：文本资源与业务流程分开，新增语言或修改措辞时不必改动状态机和领域逻辑；键名也能成为组件与翻译文件之间的稳定契约。
  • 文件级设计证据：源码顶部注释把它定位为“reference namespace dictionaries for the unified @ source.”；固定提交中扫描到的声明包括 NS、zh、ReferenceKey、en；本地静态 import 图显示它直接依赖 1 个源文件，并被 1 个源文件直接引用。
  • 直接协作者：packages/client/ui-reference/README.md、packages/client/ui-slots/src/index.ts、packages/client/ui-reference/src/client/index.ts
  • 对应测试：间接测试线索（通过本地 import 链，非直接覆盖）：packages/client/ui-reference/tests/browser-plugin.client.spec.ts
  • 测试关联依据：固定提交源码中的本地静态 import 传递引用；这些测试通过包入口或中间模块到达本文件，不等于本文件被直接覆盖。
  • 阅读顺序：先读客户端运行时契约或呈现模型，再读当前界面文件，沿着 packages/client/ui-reference/src/client/index.ts 确认状态如何进入 UI，最后对照 packages/client/ui-reference/tests/browser-plugin.client.spec.ts。
  • 代码证据：固定提交归档实际读取结果：约 36 行；扫描到的声明包括 NS、zh、ReferenceKey、en；源码顶部原注释（英文，仅作回查线索）：reference namespace dictionaries for the unified @ source.。
  • 固定版本：源码链接固定到官方提交 aa6c361a972c8369148dea7380bb5c21c24e07ec。

packages/client/ui-reference/src/index.ts ​

  • 所属层：packages/client：可复用的 Harness 功能包
  • 文件角色：模块入口
  • 这个文件有什么用：它把浏览器端、用户界面相关的公开能力集中导出，并决定调用者可以依赖哪些边界；调用者因此不必记住所有内部文件。
  • 为什么这样设计：入口文件把公开边界固定下来，内部文件可以继续拆分或替换；其他包只依赖入口暴露的 API，依赖方向更稳定。
  • 文件级设计证据：源码顶部注释把它定位为“File/session reference plugin, node half. Pure UI plugin: the empty apply exists so the plugin appears in the host cordis.yml / Loader; the browser half ships via exports"./client", discovered through the package.json dsh.client declaration.”；固定提交中扫描到的声明包括 apply；本地静态 import 图显示它直接依赖 0 个源文件，并被 1 个源文件直接引用。
  • 直接协作者：packages/client/ui-reference/README.md、packages/client/ui-reference/tests/browser-plugin.client.spec.ts
  • 对应测试：packages/client/ui-reference/tests/browser-plugin.client.spec.ts
  • 测试关联依据：固定提交源码中的本地静态 import 直接引用；测试用例直接导入了这个源文件。
  • 阅读顺序：先读 packages/client/ui-reference/README.md、入口和消费者，再读当前契约，沿着 packages/client/ui-reference/tests/browser-plugin.client.spec.ts 看它怎样约束运行时，最后对照 packages/client/ui-reference/tests/browser-plugin.client.spec.ts。
  • 代码证据：固定提交归档实际读取结果：约 9 行；扫描到的声明包括 apply；源码顶部原注释（英文，仅作回查线索）：File/session reference plugin, node half. Pure UI plugin: the empty apply exists so the plugin appears in the host cordis.yml / Loader; the browser half ships via exports"./client", discovered through the package.json dsh.client declaration.。
  • 固定版本：源码链接固定到官方提交 aa6c361a972c8369148dea7380bb5c21c24e07ec。

packages/client/ui-reference/src/invariant.ts ​

  • 所属层：packages/client：可复用的 Harness 功能包
  • 文件角色：运行时不变量
  • 这个文件有什么用：它检查浏览器端、用户界面必须始终成立的条件，在错误刚出现时报告，而不是等到更深层才出现难以解释的结果。
  • 为什么这样设计：把不变量集中在一个位置，调用者和测试就能用同一条规则检查状态；错误在边界处报告，比在后续 UI 或网络请求中才暴露更容易修复。
  • 文件级设计证据：源码顶部注释把它定位为“Package-owned invariant companion for @deepseek-ai/dsh-client-ui-reference. @module @deepseek-ai/dsh-client-ui-reference/invariant”；固定提交中扫描到的声明包括 name、inject、apply；本地静态 import 图显示它直接依赖 2 个源文件，并被 0 个源文件直接引用。
  • 直接协作者：packages/client/ui-reference/README.md、packages/runtime-diagnostics/invariants/src/index.ts、vendor/cordis/src/index.ts
  • 对应测试：没有确认到直接测试；公共入口可能仍有间接覆盖。
  • 测试关联依据：固定提交中没有找到直接或传递的本地静态 import，也没有找到明显的同包同名测试；公共入口可能仍有间接覆盖。
  • 阅读顺序：先读相关类型和事件，再读当前状态或存储实现，沿着 packages/runtime-diagnostics/invariants/src/index.ts、vendor/cordis/src/index.ts 和所在包的入口或服务理解状态变化，最后对照同包中与它同名或覆盖相近场景的测试。
  • 代码证据：固定提交归档实际读取结果：约 31 行；扫描到的声明包括 name、inject、apply；源码顶部原注释（英文，仅作回查线索）：Package-owned invariant companion for @deepseek-ai/dsh-client-ui-reference. @module @deepseek-ai/dsh-client-ui-reference/invariant。
  • 固定版本：源码链接固定到官方提交 aa6c361a972c8369148dea7380bb5c21c24e07ec。

packages/client/ui-reference/tests/browser-plugin.client.spec.ts ​

  • 所属层：packages/client：可复用的 Harness 功能包
  • 文件角色：测试用例
  • 这个文件有什么用：它用自动化测试检查浏览器端、用户界面的具体场景，包括“apply”、“declares its services and releases the @ reference registration on disposal”、“the node half applies without host-side behavior”、“candidates”；这些断言把“应该发生什么”变成可以重复运行的证据。
  • 为什么这样设计：把测试主题“apply”写成独立测试用例，读者可以从输入、触发动作和断言反推实现的不变量；不同回归问题也不会互相遮蔽。
  • 文件级设计证据：源码顶部注释把它定位为“Web reference source coverage: Remote-backed file/session discovery, deterministic ordering and labels, quoted-path suppression, pick projections, codec round-trip, and registration lifecycle.”；固定提交中扫描到的声明包括 request、bench、RemoteService；本地静态 import 图显示它直接依赖 8 个源文件，并被 0 个源文件直接引用。
  • 直接协作者：packages/client/ui-reference/README.md、packages/client/locale/src/client/index.ts、packages/client/runtime/src/client/index.ts、packages/client/ui-input-trigger/src/client/index.ts
  • 对应测试：本文件本身就是测试用例。
  • 测试关联依据：本文件本身就是测试用例，不把同目录的其他测试冒充成它的“对应测试”。
  • 阅读顺序：先看它直接导入的被测实现 packages/client/locale/src/client/index.ts、packages/client/runtime/src/client/index.ts、packages/client/ui-input-trigger/src/client/index.ts，再读本文件的测试主题、输入和断言；最后对照测试支持和失败输出。
  • 代码证据：固定提交归档实际读取结果：约 326 行；扫描到的声明包括 request、bench、RemoteService；扫描到的测试主题包括 “apply”、“declares its services and releases the @ reference registration on disposal”、“the node half applies without host-side behavior”、“candidates”、“starts both Remote lookups together and renders files before sessions with stable labels”、“suppresses sessions for an open quoted path and degrades each failed domain independently”；源码顶部原注释（英文，仅作回查线索）：Web reference source coverage: Remote-backed file/session discovery, deterministic ordering and labels, quoted-path suppression, pick projections, codec round-trip, and registration lifecycle.。
  • 固定版本：源码链接固定到官方提交 aa6c361a972c8369148dea7380bb5c21c24e07ec。

packages/client/ui-reference/tsdown.config.ts ​

  • 所属层：packages/client：可复用的 Harness 功能包
  • 文件角色：构建或测试配置
  • 这个文件有什么用：它告诉工具链怎样处理浏览器端、用户界面：从哪里开始、使用哪个环境、解析哪些依赖以及输出什么产物；这些规则集中后，构建和测试才可重复。
  • 为什么这样设计：工具链配置独立于业务实现，构建、测试和发布可以复用同一套入口规则；改配置时也能单独看出运行环境变化。
  • 文件级设计证据：本次固定提交归档没有扫描到顶部注释、顶层声明或专门的结构线索；本地静态 import 图显示它直接依赖 1 个源文件，并被 0 个源文件直接引用。
  • 直接协作者：packages/client/ui-reference/README.md、packages/client/tsdown.client.ts
  • 对应测试：没有确认到直接测试；公共入口可能仍有间接覆盖。
  • 测试关联依据：固定提交中没有找到直接或传递的本地静态 import，也没有找到明显的同包同名测试；公共入口可能仍有间接覆盖。
  • 阅读顺序：先读 packages/client/ui-reference/README.md，再读本配置/脚本，沿着所在包的入口或服务确认它如何影响入口和产物，最后对照对应 gate 或快照测试。
  • 代码证据：固定提交归档实际读取结果：约 3 行。
  • 固定版本：源码链接固定到官方提交 aa6c361a972c8369148dea7380bb5c21c24e07ec。