docs(ui-subagent): align catalog preparation descriptions

2026-11-07 01:06:12 +08:00
1 parent 8e98ccff62
commit c867b5cc7e
@@ -9,8 +9,8 @@
  en: ab63c8127d68d294
  zh: d3f99489c96ff1d4
 /agent-note-open-the-session-when-migration-is-required/decision:
-  en: 32627d744a6e7410
-  zh: 2836a95ee5390111
+  en: 310ff84cece51901
+  zh: a9a29e3ba30e03a8
 /agent-note-open-the-session-when-migration-is-required/alternatives-considered:
  en: baea781018a49252
  zh: bcc452029bf229fd
@@ -18,7 +18,7 @@ Other fork callers omit that option and allow automatic migration.

 The `formatStatus` returned by `stat` carries the migration library's existing classification; `header` remains the current logical format. It describes the stored format, not migration-task progress or prepared in-memory history.

-When migration is required and `subagentCatalog` is absent, Web marks the Session's row “Migration required” and keeps its history-opening actions without descendant expansion or changing its subagent mode. Opening the Session supplies its catalog through history and control projections. Available catalogs remain usable, including empty catalogs. Session-list lineage resolves navigation addresses, not missing catalog membership. Ordinary loading, cancellation, and storage errors do not become this migration branch.
+When migration is required and `subagentCatalog` is absent, Web keeps the Session row's history-opening actions without a format notice, descendant expansion, or changing its subagent mode. Opening the Session supplies its catalog through history and control projections. Available catalogs remain usable, including empty catalogs. Session-list lineage resolves navigation addresses, not missing catalog membership. Ordinary loading, cancellation, and storage errors do not become this migration branch.

 Create/adopt, full-text search, and ordinary history opening allow automatic migration.

@@ -18,7 +18,7 @@ WorkspaceBrowser 行菜单的 fork 请求携带 `allowMigration: false`，由 Ho

 `stat` 返回的 `formatStatus` 携带迁移库已有的分类；`header` 仍是当前逻辑格式。它描述存储格式，不描述迁移任务进度或内存准备缓存。

-在需要迁移且缺少 `subagentCatalog` 时，Web 将该会话行标为“需要迁移”，保留打开历史的操作，但不能展开下级，也不改变子会话的 mode。打开会话后，历史与 control 投影提供其目录。已有目录仍可使用，包括空目录。会话列表的谱系用于解析导航地址，不用于补齐缺失的目录成员。普通加载、取消和存储错误不转换成这一迁移分支。
+在需要迁移且缺少 `subagentCatalog` 时，Web 保留该会话行打开历史的操作，不显示格式提示，不展开下级，也不改变子会话的 mode。打开会话后，历史与 control 投影提供其目录。已有目录仍可使用，包括空目录。会话列表的谱系用于解析导航地址，不用于补齐缺失的目录成员。普通加载、取消和存储错误不转换成这一迁移分支。

 create/adopt、全文搜索和普通历史打开允许自动迁移。

@@ -30,8 +30,8 @@
  en: c158f12dcaed87b7
  zh: e5d315e7b1fb4fa9
 /deepseek-ai-dsh-client-ui-subagent/understand-the-implementation/catalog-derivation:
-  en: 22b8ca76ca8d64a6
-  zh: 300231110a4a208d
+  en: c7a6ed23ce7ec331
+  zh: 92b60359a490b270
 /deepseek-ai-dsh-client-ui-subagent/understand-the-implementation/duration-completion-and-tokens:
  en: dcbc58d4cad47fa8
  zh: e962a8cbdfd4a914
@@ -61,11 +61,11 @@ The [subagent runtime](../../subagent/subagent/README.md) owns continuation and

 ### Catalog derivation

-The header lineage renderer reads `subagentCatalog` only from `projectionsBySession` through the standard `useSessions` hook. The Session object layer merges list-cache hints, explicit reads, and the Host-wide control stream into these shared values; live frames update loaded levels without per-menu subscriptions. Activity prefers the unified UI status and falls back to Session summaries; summaries also supply titles and usage. Rendering, hovering, and expanding the tree use only local projections and never request missing catalogs. Missing and explicitly empty catalogs have no expansion arrow; a later shared projection with children makes the arrow available. Failures require explicit retry. Migration-required rows keep their history-opening actions without a format notice or descendant expansion; opening the Session supplies its catalog through history and control projections. External rows are always leaves and do not load child Sessions.
+The header lineage renderer reads `subagentCatalog` only from `projectionsBySession` through the standard `useSessions` hook. The Session object layer merges list-cache hints, explicit reads, and the Host-wide control stream into these shared values; live frames update loaded levels without per-menu subscriptions. Activity prefers the unified UI status and falls back to Session summaries; summaries also supply titles and usage. Rendering and hovering use only local projections and never request missing catalogs. Missing and explicitly empty catalogs have no expansion arrow; a later shared projection with children makes the arrow available. Failures require explicit retry. Migration-required rows keep their history-opening actions without a format notice or descendant expansion; opening the Session supplies its catalog through history and control projections. External rows are always leaves and do not load child Sessions.

 Each header entry declares a footer slot below its tree. Optional UI contributes there within the same scroll container; the catalog owns opening and dismissal. CSS anchors keep the panel attached to its trigger within layout-viewport size limits. Browser zoom and panning move it with the page, so it may extend beyond the visual viewport. Internal scrolling, hover behavior, pinned opening, and focus restoration remain independent.

-Opening a catalog dropdown does not request its root catalog. Only explicit failed-read retries call `refreshProjection`; the Session object layer owns request deduplication and reconnect recovery.
+Explicit menu activation and branch expansion call `prepareCatalog` to read the current catalog and its direct children. Ancestor-title clicks navigate to that Session. Failed-read retry buttons call `refreshProjection`; the Session object layer deduplicates reads and refreshes previously requested projections after reconnect.

 Breadcrumb addresses derive from the Provider-bound Session address, loaded parent catalogs, or already-listed subagent lineage, including never-selected ancestors.

@@ -61,11 +61,11 @@ kind: "package-reference"

 ### 目录派生

-页头谱系 renderer 通过标准 `useSessions` 钩子，仅从 `projectionsBySession` 读取 `subagentCatalog`。Session 对象层将列表缓存提示、显式读取和 Host 全局 control 流合并到这些共享值；实时帧更新已加载层级，无需每个菜单单独订阅。活动状态优先使用统一 UI status，缺少时使用 Session 摘要；摘要还提供标题与用量。渲染、悬停和展开目录树仅使用本地投影，不会请求缺失目录。缺失或显式为空的目录没有展开箭头；后续共享投影包含下级时才显示箭头。读取失败后需要显式重试。需要迁移的行保留打开历史的操作，不显示格式提示，也不展开下级；打开 Session 后，历史与 control 投影提供其目录。外部行始终为叶子，不加载子 Session。
+页头谱系 renderer 通过标准 `useSessions` 钩子，仅从 `projectionsBySession` 读取 `subagentCatalog`。Session 对象层将列表缓存提示、显式读取和 Host 全局 control 流合并到这些共享值；实时帧更新已加载层级，无需每个菜单单独订阅。活动状态优先使用统一 UI status，缺少时使用 Session 摘要；摘要还提供标题与用量。渲染与悬停仅使用本地投影，不会请求缺失目录。缺失或显式为空的目录没有展开箭头；后续共享投影包含下级时才显示箭头。读取失败后需要显式重试。需要迁移的行保留打开历史的操作，不显示格式提示，也不展开下级；打开 Session 后，历史与 control 投影提供其目录。外部行始终为叶子，不加载子 Session。

 每个页头入口在树下方声明 footer 插槽。可选 UI 通过该插槽加入同一滚动容器；目录负责打开和关闭。CSS 锚点让面板跟随触发器，并按布局视口限制尺寸。浏览器缩放和平移时面板随页面移动，因此可以超出视觉视口。内部滚动、悬停行为、点击固定展开和焦点恢复保持独立。

-打开目录下拉菜单不会请求其根目录。只有显式重试失败读取时才调用 `refreshProjection`；Session 对象层负责请求去重和重连恢复。
+显式激活菜单或展开分支时，`prepareCatalog` 读取当前目录及其直接子节点。点击祖先标题会导航到该 Session。失败读取的重试按钮调用 `refreshProjection`；Session 对象层合并重复读取，并在重连后刷新之前请求过的投影。

 面包屑地址从 Provider 所绑定的 Session 地址、已加载的 parent 目录或已列出的 subagent 谱系推导，也包括从未选中过的祖先。