dsh-vscode-mode 0.20.2 → 0.20.4

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "dsh-vscode-mode",
-  "version": "0.20.2",
+  "version": "0.20.4",
   "description": "DSH 上的类 VSCode 编码体验：Monaco 编辑器（文件页签/QuickOpen/状态栏，可驻 DSH 0.1.5+ 官方右侧 Sidebar 与对话同屏）+ 命令栏（Ctrl+Shift+P）与可扩展指令系统 + VS Code 兼容代码片段（.code-snippets 全局/项目，IntelliSense 展开）+ Agent 编辑差异审查（整文件差异/采纳/拒绝/归档/回滚）+ SVN 集成（侧栏变更面板/日志弹窗/并排差异）+ 语言服务器（LSP）智能（跳转定义/引用/hover/大纲 + VSIX 扩展市场安装），状态持久化到工作区旁车，界面状态（页签/光标/侧栏/编辑 Tab/导航历史）镜像到 DSH home 跨重启恢复",
   "icon": "assets/icon.svg",
   "keywords": [

package/src/client/reviewBar.ts

@@ -0,0 +1,126 @@
+/**
+ * 官方差异栏派生视图：位置、导航提示、失效说明与 Keep 提示的唯一来源。
+ * 计数口径分离：待审是「记录数」，可跳转是「块数」，两者不同源，
+ * 全部块失效时必须给出可操作叙事，不能只留一句「无法定位」。
+ * 另含侧车（legacy）栏的标识文案与官方链路不可用说明：两套栏外观相近，
+ * 必须显式区分，否则用户会误判为插件未升级。
+ * 作者 ddj 2026年10月27号
+ */
+import { sessionErrorText } from './sessionError.js'
+
+/** 官方差异栏输入：全部来自 EditorView dock 快照，不读取磁盘或 RPC。 */
+export interface ReviewBarInput {
+  /** 可定位（非 stale）的差异块数 */
+  jumps: number
+  /** 无法定位的历史差异块数 */
+  stale: number
+  /** 当前差异块索引（0 基） */
+  index: number
+  /** 编辑器内容是否已就绪；未就绪时不得断言差异失效 */
+  ready: boolean
+  /** 当前文件的官方待审记录数 */
+  pendingRecords: number
+  /** 当前记录是否可 Keep（detail.capability.keep） */
+  canKeep: boolean
+}
+
+/** 官方差异栏派生文案；调用方只负责渲染，不再自行拼装计数与提示。 */
+export interface ReviewBarView {
+  /** 差异位置文案，如 `2 / 6`、`无可跳转`、`载入中` */
+  position: string
+  /** 上一个差异按钮提示（兼作禁用原因） */
+  navPrevTitle: string
+  /** 下一个差异按钮提示（兼作禁用原因） */
+  navNextTitle: string
+  /** 失效说明，空串表示不显示 */
+  notice: string
+  /** 说明级别：warn 表示需要用户决策 */
+  noticeTone: 'info' | 'warn'
+  /** Keep 按钮提示 */
+  keepHint: string
+  /** 待审计数提示 */
+  pendingTitle: string
+}
+
+/** @private @author ddj 2026年10月27号 @param value 任意计数输入 @returns 非负整数，NaN/负数/非数字归零 */
+function safeCount(value: unknown): number {
+  const parsed = Number(value)
+  return Number.isFinite(parsed) && parsed > 0 ? Math.floor(parsed) : 0
+}
+
+/** @private @author ddj 2026年10月27号 @returns 无差异可跳转时的 Keep 提示 */
+function fullStaleKeepHint(): string {
+  return '保留该记录的全部改动并结案：这些改动已不在文件中，记录将被标记为已采纳（不改写磁盘）'
+}
+
+/**
+ * 派生差异栏文案。
+ * @public
+ * @author ddj 2026年10月27号
+ * @param input 差异计数、就绪状态与 Keep 能力
+ * @returns 栏内位置、导航提示与失效说明
+ */
+export function reviewBarView(input: ReviewBarInput): ReviewBarView {
+  const jumps = safeCount(input.jumps)
+  const stale = safeCount(input.stale)
+  const index = safeCount(input.index)
+  const pendingTitle = `${safeCount(input.pendingRecords)} 条官方待审记录` + (input.ready ? `，本文件可跳转 ${jumps} 处` : '')
+  const keepHint = jumps === 0 && stale > 0 && input.canKeep ? fullStaleKeepHint() : '保留当前记录的未处理修改'
+
+  // 载入期所有块天然 stale，此时只能报告进度，不能断言改动已失效。
+  if (input.ready !== true) {
+    return { position: '载入中', navPrevTitle: '文件载入中', navNextTitle: '文件载入中', notice: '', noticeTone: 'info', keepHint, pendingTitle }
+  }
+
+  if (jumps > 0) {
+    const at = Math.min(index + 1, jumps)
+    const notice = stale > 0 ? `${stale} 处历史差异无法定位（其余 ${jumps} 处可跳转），展开详情查看原始增删。` : ''
+    return { position: `${at} / ${jumps}`, navPrevTitle: '上一个差异', navNextTitle: '下一个差异', notice, noticeTone: 'info', keepHint, pendingTitle }
+  }
+
+  if (stale > 0) {
+    const reason = '该记录的改动已不在当前文件中，无可跳转差异'
+    const notice = `本记录 ${stale} 处改动均已不在当前文件中（被后续编辑覆盖或已撤销）；可点 Keep 结案（只标记已采纳，不改写磁盘），或展开详情核对原始增删。`
+    return { position: '无可跳转', navPrevTitle: reason, navNextTitle: reason, notice, noticeTone: 'warn', keepHint, pendingTitle }
+  }
+
+  return { position: '—', navPrevTitle: '当前文件没有可定位差异', navNextTitle: '当前文件没有可定位差异', notice: '', noticeTone: 'info', keepHint, pendingTitle }
+}
+
+/** 非官方栏标识：没有官方待审记录时回落的那套栏必须自述来源，避免被当成旧版插件。 */
+export const SIDECAR_LABEL = '历史改动'
+
+/** 非官方栏标识的悬停说明：讲清这些改动为何不在官方列表里。 */
+export const SIDECAR_LABEL_TITLE = '这些改动没有进入官方审查列表，是插件早期版本自动保存的改动留痕。Keep 只标记为已看过，不改文件；Undo 会校验后写回文件。'
+
+/** 非官方 Keep 的作用域说明：只标记记录，不写磁盘。 */
+export const SIDECAR_KEEP_TITLE = '标记这些历史改动为已看过：只改记录，不改写磁盘文件，也不影响官方审查。'
+
+/** 非官方 Undo 的作用域说明：走原有回滚校验写回磁盘，但不影响官方记录。 */
+export const SIDECAR_UNDO_TITLE = '撤销这些历史改动（写回受回滚校验保护）：只影响这份历史记录，不影响官方审查。'
+
+/** 当前端没有该会话时，差异栏里给中性说明而不是红色报错。 */
+export const SESSION_DOWN_NOTICE = '这个会话没在当前端激活，官方审查数据暂时读不到；下面的历史改动仍可查看、Keep、Undo。'
+
+/** 官方链路不可用提示；null 表示官方元数据正常，不需要提示。 */
+export interface OfficialDownView {
+  /** 提示正文，已含「官方差异不可用」前缀与可读原因 */
+  text: string
+  /** 重试按钮文案 */
+  retryLabel: string
+}
+
+/**
+ * 把官方元数据通道的失败翻译成可操作提示。
+ * @public
+ * @author ddj 2026年10月28号
+ * @param error `edrv.review.list` 返回的错误原文（reviewFeed 的 error 字段）
+ * @returns 提示正文与重试文案；空错误表示官方通道正常
+ */
+export function officialDownView(error: unknown): OfficialDownView | null {
+  const reason = sessionErrorText(error).trim()
+  if (!reason) return null
+
+  return { text: `官方差异不可用：${reason}`, retryLabel: '重试' }
+}
+

package/src/client/sessionError.ts

@@ -36,3 +36,15 @@ export function sessionMissingDetail(): string {
   return '该会话可能正被其他 DSH 实例（桌面端 / Web 端）占用，或尚未在当前实例激活。' +
     '请在持有该会话的一端查看，或在本端打开该会话后重试。'
 }
+
+/**
+ * 把任意错误文本归一为可展示文案：会话缺失类替换为终态提示，其余原样返回。
+ * 差异栏等狭窄区域共用，避免裸「会话不存在」与业务提示混排。
+ * @author ddj 2026年10月27号
+ * @param text 任意错误文本（host 业务 error、异常 message 等原始形态）
+ * @returns 会话缺失为「标题：详情」，其他错误为原文本，空值返回空串
+ */
+export function sessionErrorText(text: unknown): string {
+  if (isSessionMissingError(text)) return sessionMissingTitle() + '：' + sessionMissingDetail()
+  return String(text ?? '')
+}

package/src/client/styles/editor.css

@@ -304,6 +304,10 @@
 [data-edrv-diff-dock-shell] .edrv-reviewbar button:focus-visible { outline: 2px solid var(--dsw-alias-brand-primary, #3b63d9); outline-offset: 2px; }
 [data-edrv-diff-dock-shell] .edrv-review-notice { padding: 7px 12px; border-top: 1px solid var(--dsw-alias-border-l1, #e5e9ef); color: var(--dsw-alias-label-secondary, #697586); font-size: 11px; overflow-wrap: anywhere; }
 [data-edrv-diff-dock-shell] .edrv-review-error { color: var(--dsw-alias-state-error-primary, #b64043); }
+[data-edrv-diff-dock-shell] .edrv-review-notice-warn { color: var(--dsw-alias-state-warning-primary, #a86a1f); }
+[data-edrv-diff-dock-shell] .edrv-review-source { flex: none; padding: 1px 6px; border-radius: 999px; border: 1px solid var(--dsw-alias-border-secondary, #d4dae3); color: var(--dsw-alias-label-secondary, #697586); font-size: 11px; line-height: 16px; white-space: nowrap; }
+[data-edrv-diff-dock-shell] .edrv-sidecar-down { display: flex; align-items: center; gap: 8px; }
+[data-edrv-diff-dock-shell] .edrv-sidecar-down-text { flex: 1; min-width: 0; }
 [data-edrv-diff-dock-shell] .edrv-review-body { border-top: 1px solid var(--dsw-alias-border-l1, #e5e9ef); max-height: min(240px, 30vh); overflow: auto; padding: 8px 12px; }
 @container edrv-review (max-width: 420px) {
   .edrv-reviewbar .edrv-review-heading { gap: 6px; padding-inline: 10px; }

package/src/client/ui/DiffBox.ts

@@ -1,58 +1,24 @@
 // @ts-nocheck
 /**
- * dsh-vscode-mode client — DiffBox：每个文件底部紧凑差异条（per-file hunk + ⋮ 二级菜单）。
- * 迁移自原 src/client/index.ts 的 DiffBox，语义不改。
+ * dsh-vscode-mode client — DiffBox：差异条入口，按数据源选栏。
+ * 官方记录 → OfficialDiffBar；其余（侧车历史捕获）→ SidecarDiffBar，
+ * 两套栏同版式，避免用户把侧车栏误判成旧版插件。
  * 作者 ddj 2026-08-20
  */
 import React from 'react'
-import { callIdAttr } from '../state/records.js'
-import { canDecideFile, diffDockText } from '../diffDock.js'
-import { badgeOf } from './shared.js'
+import { diffDockText } from '../diffDock.js'
 import { OfficialDiffBar } from './OfficialDiffBar.js'
+import { SidecarDiffBar } from './SidecarDiffBar.js'
 
 /**
- * 折叠控制使用任务栏同尺寸的 chevron 轮廓，避免依赖未声明的运行时图标包。
+ * 差异条：当前文件内 diff 导航、Keep/Undo、详情展开与 ⋮ 二级菜单。
+ * @public
  * @author ddj 2026年08月25号
- * @param open 是否已展开
- * @returns 14×14 的装饰性 chevron SVG
- */
-function chevronOf(open) {
-  const path = open ? 'M3.25 5.25 7 9l3.75-3.75' : 'M3.25 8.75 7 5l3.75 3.75'
-  return React.createElement('svg', {
-    width: 14,
-    height: 14,
-    viewBox: '0 0 14 14',
-    fill: 'none',
-    'aria-hidden': true,
-    focusable: false,
-  }, React.createElement('path', {
-    d: path,
-    stroke: 'currentColor',
-    strokeWidth: 1.2,
-    strokeLinecap: 'round',
-    strokeLinejoin: 'round',
-  }))
-}
-
-/**
- * 差异条：当前文件内 diff 导航（↑↓←→）、Keep/Undo、展开 hunk 列表、⋮ 二级菜单
- * （Keep All / Undo All / 差异总览 / 归档 / 回滚 / 刷新）+ 其他差异文件小节。
+ * @param props 差异上下文（官方或侧车），由 EditorView dock 快照提供
+ * @returns 会话态精简入口，或按数据源路由到的差异栏
  */
 export function DiffBox(props) {
-  const {
-    pendingRegions = [], staleRegions = [], onAct, onAcceptFile, onUndoFile, onAcceptAllFiles, onUndoAllFiles,
-    allPendingCount = 0, onRollback, onJump, otherFiles = [], onOpenOther, onOpenLauncher, onRefresh, activePath,
-    diffIdx = 0, diffTotal = 0, fileIdx = 0, fileTotal = 0, onPrevDiff, onNextDiff, onPrevFile, onNextFile,
-    mode = 'editor', onOpenNextFile, dock = false,
-  } = props
-  const [expanded, setExpanded] = React.useState(false)
-  const [detailsOpen, setDetailsOpen] = React.useState(false)
-  const detailsId = React.useId()
-  const canAct = pendingRegions.length > 0
-  // Keep/Undo 覆盖无法定位的冲突差异：它们仍占待处理列表，但不在 pendingRegions 内
-  const canDecide = canDecideFile(pendingRegions.length, staleRegions.length)
-
-  const base = String(activePath || '').split(/[\\/]/).pop() || ''
+  const { fileTotal = 0, onOpenNextFile, mode = 'editor' } = props
 
   if (mode === 'chat' || mode === 'editor-empty') {
     return React.createElement('div', { className: 'edrv-diffbar edrv-diffbar-dock', 'data-edrv-diffbox': '1', 'data-edrv-diff-mode': mode },
@@ -67,68 +33,5 @@ export function DiffBox(props) {
   }
 
   if (props.official) return React.createElement(OfficialDiffBar, props)
-
-  let bodyEl = null
-  if (expanded) {
-    const rows = pendingRegions.map((r) => {
-      const key = callIdAttr(r.callId, r.idx)
-      return React.createElement('div', { key, className: 'edrv-diffrow', 'data-edrv-hunk': key, title: '跳转到 L' + (r.start ?? '?'), onClick: () => onJump(r) },
-        React.createElement('span', { className: 'edrv-diffrow-l' }, 'L' + (r.start ?? '?') + '-' + (r.end ?? '?')),
-        (r.oldLines.length ? React.createElement('span', { className: 'edrv-diffrow-o' }, '-' + r.oldLines.length) : null),
-        (r.newLines.length ? React.createElement('span', { className: 'edrv-diffrow-n' }, '+' + r.newLines.length) : null),
-        (r.create ? React.createElement('span', { className: 'edrv-diffrow-tag' }, '新建') : null),
-        React.createElement('span', { style: { flex: 1 } }))
-    })
-    const stale = staleRegions.map((r) => React.createElement('div', { key: 'stale' + callIdAttr(r.callId, r.idx), className: 'edrv-diffrow edrv-diffrow-stale', title: '差异无法定位（文件可能已被手动修改）' },
-      React.createElement('span', { className: 'edrv-diffrow-l' }, 'L' + (r.start ?? '?') + ' 无法定位'),
-      React.createElement('span', { className: 'edrv-diffrow-tag' }, '冲突/需刷新'),
-      React.createElement('span', { className: 'edrv-diffrow-tag' }, badgeOf(r.status))))
-    let othersEl = null
-    if (otherFiles.length) {
-      othersEl = React.createElement('div', { className: 'edrv-diffbox-others' },
-        React.createElement('span', { className: 'edrv-diffrow-tag' }, '其他差异文件 (' + otherFiles.length + '):'),
-        otherFiles.map((f) => React.createElement('button', { key: f.path, className: 'edrv-diffrow-file', title: f.label ?? f.path, onClick: () => onOpenOther(f.path) },
-          String(f.path).split(/[\\/]/).pop() + ' (' + f.pending + ')')))
-    }
-    bodyEl = React.createElement('div', { className: 'edrv-diffbar-body' }, ...rows, ...stale, othersEl)
-  }
-
-  const details = detailsOpen
-    ? React.createElement('div', { className: 'edrv-diff-details', id: detailsId },
-        React.createElement('button', { className: 'edrv-diffmenu-item', disabled: !allPendingCount, onClick: onAcceptAllFiles }, '✓ Keep All（全部文件采纳）'),
-        React.createElement('button', { className: 'edrv-diffmenu-item danger', disabled: !allPendingCount, onClick: onUndoAllFiles }, '↩ Undo All（全部文件不采纳）'),
-        React.createElement('div', { className: 'edrv-diffmenu-sep' }),
-        React.createElement('button', { className: 'edrv-diffmenu-item', onClick: () => onOpenLauncher('pending') }, '🗂 差异总览'),
-        React.createElement('button', { className: 'edrv-diffmenu-item', onClick: () => onOpenLauncher('archive') }, '📁 归档'),
-        React.createElement('div', { className: 'edrv-diffmenu-sep' }),
-        React.createElement('button', { className: 'edrv-diffmenu-item', disabled: !canAct, onClick: onRollback }, '⟲ 回滚文件'),
-        React.createElement('button', { className: 'edrv-diffmenu-item', onClick: onRefresh }, '⟳ 刷新'))
-    : null
-
-  return React.createElement('div', { className: 'edrv-diffbar edrv-diffbar-dock', 'data-edrv-diffbox': '1', 'data-edrv-diff-mode': 'editor' },
-    React.createElement('div', { className: 'edrv-diffbar-row edrv-diffbar-editor-row' },
-      React.createElement('div', { className: 'edrv-diffbar-editor-content' },
-        React.createElement('div', { className: 'edrv-diffbar-nav' },
-          React.createElement('button', { className: 'edrv-pill edrv-pill-ghost', title: '上一个差异', disabled: !canAct, onClick: onPrevDiff }, '↑'),
-          React.createElement('span', { className: 'edrv-diffbar-count edrv-diffbar-progress', title: '当前文件内差异位置（点击展开/收起差异列表）', onClick: () => setExpanded((v) => !v) }, diffTotal ? (diffIdx + 1) + '/' + diffTotal : '0/0'),
-          React.createElement('button', { className: 'edrv-pill edrv-pill-ghost', title: '下一个差异', disabled: !canAct, onClick: onNextDiff }, '↓')),
-        React.createElement('div', { className: 'edrv-diffbar-files' },
-          React.createElement('button', { className: 'edrv-pill edrv-pill-ghost', title: '上一个差异文件', disabled: !fileTotal, onClick: onPrevFile }, '←'),
-          React.createElement('span', { className: 'edrv-diffbar-count edrv-count-file edrv-diffbar-progress', title: '差异文件位置' }, fileTotal ? (fileIdx + 1) + '/' + fileTotal + ' 文件' : '0/0 文件'),
-          React.createElement('button', { className: 'edrv-pill edrv-pill-ghost', title: '下一个差异文件', disabled: !fileTotal, onClick: onNextFile }, '→'),
-          React.createElement('span', { className: 'edrv-diffbar-file edrv-diffbar-summary', title: activePath || '' }, base)),
-
-        React.createElement('div', { className: 'edrv-diffbar-actions' },
-          React.createElement('button', { className: 'edrv-pill edrv-pill-keep', title: '采纳当前文件的全部差异', disabled: !canDecide, onClick: onAcceptFile }, '✓ Keep'),
-          React.createElement('button', { className: 'edrv-pill edrv-pill-undo', title: '不采纳当前文件的全部差异（回滚）', disabled: !canDecide, onClick: onUndoFile }, '↩ Undo'),
-          React.createElement('button', {
-            className: 'edrv-pill edrv-pill-ghost edrv-diff-details-toggle',
-            title: detailsOpen ? '收起差异操作' : '展开差异操作',
-            'aria-label': detailsOpen ? '收起差异操作' : '展开差异操作',
-            'aria-expanded': detailsOpen,
-            'aria-controls': detailsId,
-            onClick: () => setDetailsOpen((value) => !value),
-          }, chevronOf(detailsOpen))))),
-    bodyEl,
-    details)
+  return React.createElement(SidecarDiffBar, props)
 }

package/src/client/ui/EditorView.ts

@@ -127,7 +127,11 @@ import { buildBpMenu } from '../dap/bpMenu.js'
 import { clampToolbarPosition, loadToolbarPosition, saveToolbarPosition } from '../dap/toolbarDrag.js'
 import { editorModelPathOf } from '../dap/modelPath.js'
 import { dapTrace } from '../dap/trace.js'
-import { isSessionMissingError, sessionMissingDetail, sessionMissingTitle } from '../sessionError.js'
+import { isSessionMissingError, sessionErrorText, sessionMissingDetail, sessionMissingTitle } from '../sessionError.js'
+import { officialDownView, SESSION_DOWN_NOTICE } from '../reviewBar.js'
+
+/** 官方差异读取失败前缀：仅用于清理同源陈旧错误，不吞并保存类错误。@author ddj 2026年10月27号 */
+const REVIEW_LOAD_ERROR = '官方差异读取失败：'
 
 /**
  * 只在 Lua 注解类型槽开启注释自动建议；跨文件/离开类型槽立即恢复默认。
@@ -588,7 +592,9 @@ export function EditorView(props) {
         if (!result.ok) throw new Error(result.error)
         setOfficialRecords((previous) => JSON.stringify(previous) === JSON.stringify(page.page.items) ? previous : page.page.items)
         setOfficialDetail((previous) => JSON.stringify(previous) === JSON.stringify(result.detail) ? previous : result.detail)
-      } catch (cause) { if (!controller.signal.aborted) setError('官方差异读取失败：' + String(cause)) }
+        // 读取成功后清除同源陈旧错误，避免会话恢复后仍挂着上一次失败提示。
+        setError((previous) => (typeof previous === 'string' && previous.startsWith(REVIEW_LOAD_ERROR) ? null : previous))
+      } catch (cause) { if (!controller.signal.aborted) setError(REVIEW_LOAD_ERROR + String(cause)) }
     }
     void loadReview()
     return () => controller.abort()
@@ -4482,12 +4488,22 @@ export function EditorView(props) {
    * @returns 含布局及操作回调的差异快照
    */
   const officialFile = review.page?.overview?.coveredPaths.find((path) => sameFile(path, active))
+  // 官方通道自身的失败（list 失败 / 缺 overview）只影响官方栏，不能混进保存类错误。
+  const officialDown = officialFile ? null : officialDownView(review.error)
+  const rawReviewError = review.error || error
+  // 会话未在当前端激活属于环境提示，不是需要用户处置的错误：降级为中性说明，避免整栏红字。
+  const sessionDown = isSessionMissingError(rawReviewError)
+  const reviewErrorTone = sessionDown ? 'info' : 'error'
+  const reviewErrorText = !rawReviewError ? undefined : sessionDown ? SESSION_DOWN_NOTICE : sessionErrorText(rawReviewError)
   const buildDockSnapshot = () => ({
     mode: editorDockMode(active),
     official: officialFile ? { sessionId, page: review.page, path: officialFile,
       pending: sum.files.find((file) => sameFile(file.path, active))?.pending ?? 0,
       detail: officialDetail, records: officialRecords, onSelect: setSelectedReview } : null,
-    reviewError: review.error || error,
+    officialDown: officialDown ?? undefined,
+    onRetryOfficial: () => refreshReview(sessionId),
+    reviewError: reviewErrorText,
+    reviewErrorTone,
     layout,
     pendingRegions,
     staleRegions,
@@ -4507,6 +4523,7 @@ export function EditorView(props) {
     onRefresh: reloadFile,
     activePath: active,
     diffIdx: contentReady ? diffIdx : 0,
+    contentReady,
     diffTotal: displayDiffTotal(contentReady, pendingRegions.length, sum.files.find((file) => sameFile(file.path, active))?.pending ?? 0),
     fileIdx,
     fileTotal: sum.pendingFiles.length,

package/src/client/ui/OfficialDiffBar.tsx

@@ -2,6 +2,8 @@ import React from 'react'
 import { Button, Menu } from '@deepseek-ai/dsh-client-ui-primitives'
 import type { ReviewDetail, ReviewItem, ReviewPage } from '../../shared/review.js'
 import { ReviewLedger } from './OfficialReview.js'
+import { reviewBarView } from '../reviewBar.js'
+import { ReviewAllRow } from './reviewAllRow.js'
 
 export interface OfficialBarProps {
   official: { sessionId: string; path: string; pending: number; detail?: ReviewDetail; records?: ReviewItem[]; page: ReviewPage; onSelect: (id: string) => void }
@@ -9,6 +11,8 @@ export interface OfficialBarProps {
   pendingRegions?: unknown[]
   staleRegions?: unknown[]
   diffIdx?: number
+  /** 编辑器内容是否就绪；未就绪时不得断言差异失效 */
+  contentReady?: boolean
   fileTotal?: number
   fileIdx?: number
   allPendingCount?: number
@@ -24,6 +28,7 @@ export interface OfficialBarProps {
   onUndoFile: () => void
   onOpenLauncher: (tab: string) => void
   reviewError?: string
+  reviewErrorTone?: 'info' | 'error'
 }
 
 type Mark = 'left' | 'right' | 'up' | 'down' | 'check' | 'undo' | 'more' | 'file'
@@ -33,25 +38,17 @@ const marks: Record<Mark, string> = {
   more: 'M3 8h.01M8 8h.01M13 8h.01', file: 'M9 2H4v12h8V5L9 2Zm0 0v4h3M6 9h4M6 11h3',
 }
 
-/** @private @author ddj 2026年10月27号 @param mark Toolbar action. @returns Decorative consistent-stroke icon; labels live on buttons. */
-function barIcon(mark: Mark): React.ReactElement {
+/**
+ * 差异栏图标：官方栏与侧车栏共用同一套 16×16 线性图标，避免两套栏外观不一致。
+ * @public
+ * @author ddj 2026年10月27号
+ * @param mark 工具栏动作
+ * @returns 装饰性一致描边图标（标签文字在按钮上）
+ */
+export function barIcon(mark: Mark): React.ReactElement {
   return <svg width="16" height="16" viewBox="0 0 16 16" fill="none" stroke="currentColor" strokeWidth={1.5} strokeLinecap="round" strokeLinejoin="round" aria-hidden="true"><path d={marks[mark]} /></svg>
 }
 
-/** @private @author ddj 2026年10月27号 @param props Global workspace counts and bulk handlers. @returns Persistent global review controls, distinct from current-file actions. */
-function ReviewAllRow(props: OfficialBarProps): React.ReactElement {
-  const total = props.fileTotal ?? 0
-  const current = total && (props.fileIdx ?? -1) >= 0 ? (props.fileIdx ?? 0) + 1 : 0
-  const disabled = props.reviewBatchBusy || !!props.batchUnavailable || !props.allPendingCount
-  return <div className="edrv-review-global" role="group" aria-label="全部待审文件">
-    <Button size="sm" variant="ghost" className="edrv-review-total" onClick={() => props.onOpenLauncher('pending')} title="打开当前工作区全部待审差异文件">差异文件 <strong>{current} / {total}</strong></Button>
-    <span className="edrv-review-all-actions">
-      <Button size="sm" variant="ghost" onClick={props.onAcceptAllFiles} disabled={disabled || !props.onAcceptAllFiles} title={props.batchUnavailable || 'Keep 当前工作区全部待审文件（含其他轮次），不改写磁盘'}>Keep All</Button>
-      <Button size="sm" variant="ghost" className="edrv-review-undo" onClick={props.onUndoAllFiles} disabled={disabled || !props.onUndoAllFiles} title={props.batchUnavailable || '检查全部待审记录后逐项 Undo；缺少证据或遇到冲突停止，不强制覆盖'}>Undo All</Button>
-    </span>
-  </div>
-}
-
 /** @public @author ddj 2026年10月27号 @param props Existing review callbacks and immutable record metadata. @returns Responsive review toolbar; no disk or decision side effects until an explicit action. */
 export function OfficialDiffBar(props: OfficialBarProps): React.ReactElement {
   const { official, pendingRegions = [], staleRegions = [], diffIdx = 0 } = props
@@ -61,7 +58,8 @@ export function OfficialDiffBar(props: OfficialBarProps): React.ReactElement {
   const detail = official.detail
   const records = official.records ?? []
   const count = pendingRegions.length
-  const position = count ? `${Math.min(diffIdx + 1, count)} / ${count}` : '—'
+  const view = reviewBarView({ jumps: count, stale: staleRegions.length, index: diffIdx, ready: props.contentReady === true,
+    pendingRecords: official.pending, canKeep: detail?.capability.keep === true })
 
   /** @private @author ddj 2026年10月27号 @returns Close current popup without changing selection. */
   function closeMenu(): void { setMenu(null) }
@@ -69,9 +67,9 @@ export function OfficialDiffBar(props: OfficialBarProps): React.ReactElement {
   function selectRecord(id: string): void { official.onSelect(id); closeMenu() }
   /** @private @author ddj 2026年10月27号 @param tab Existing launcher tab. @returns Open existing overview, never create another review entry. */
   function openOverview(tab: string): void { props.onOpenLauncher(tab); closeMenu() }
-  /** @private @author ddj 2026年10月27号 @param mark Navigation icon. @param label Accessible action. @param action Existing callback. @param disabled Whether navigation is unavailable. @returns Compact keyboard-focusable navigation control. */
-  function navButton(mark: Mark, label: string, action: () => void, disabled: boolean): React.ReactElement {
-    return <Button size="sm" variant="ghost" className="edrv-review-icon" aria-label={label} title={label} disabled={disabled} onClick={action}>{barIcon(mark)}</Button>
+  /** @private @author ddj 2026年10月27号 @param mark Navigation icon. @param label Accessible action. @param action Existing callback. @param disabled Whether navigation is unavailable. @param title Hover reason, defaults to the label. @returns Compact keyboard-focusable navigation control. */
+  function navButton(mark: Mark, label: string, action: () => void, disabled: boolean, title?: string): React.ReactElement {
+    return <Button size="sm" variant="ghost" className="edrv-review-icon" aria-label={label} title={title || label} disabled={disabled} onClick={action}>{barIcon(mark)}</Button>
   }
 
   const recordTrigger = <Button size="sm" variant="ghost" className="edrv-review-record" aria-label="选择官方差异记录" aria-haspopup="menu" aria-expanded={menu === 'records'} disabled={!records.length} onClick={() => setMenu(menu === 'records' ? null : 'records')}>
@@ -80,12 +78,23 @@ export function OfficialDiffBar(props: OfficialBarProps): React.ReactElement {
   const moreTrigger = <Button size="sm" variant="ghost" className="edrv-review-icon" aria-label="更多审查操作" title="更多审查操作" aria-haspopup="menu" aria-expanded={menu === 'more'} onClick={() => setMenu(menu === 'more' ? null : 'more')}>{barIcon('more')}</Button>
 
   return <div className="edrv-diffbar edrv-diffbar-dock edrv-reviewbar" data-edrv-diffbox="1" data-edrv-diff-source="official" role="region" aria-label="文件差异审查">
-    <ReviewAllRow {...props} />
+    <ReviewAllRow
+      total={props.fileTotal ?? 0}
+      current={(props.fileTotal ?? 0) && (props.fileIdx ?? -1) >= 0 ? (props.fileIdx ?? 0) + 1 : 0}
+      busy={props.reviewBatchBusy}
+      unavailable={props.batchUnavailable}
+      pending={props.allPendingCount}
+      onOpen={() => props.onOpenLauncher('pending')}
+      onKeepAll={props.onAcceptAllFiles}
+      onUndoAll={props.onUndoAllFiles}
+      keepTitle="Keep 当前工作区全部待审文件（含其他轮次），不改写磁盘"
+      undoTitle="检查全部待审记录后逐项 Undo；缺少证据或遇到冲突停止，不强制覆盖"
+    />
     {props.reviewBatchBusy ? <div className="edrv-review-notice" role="status">正在处理全部待审记录…</div> : null}
     <div className="edrv-review-heading">
       <span className="edrv-review-filemark">{barIcon('file')}</span>
       <span className="edrv-review-filename" title={props.activePath}>{name}</span>
-      <span className="edrv-review-pending" title={`${official.pending} 条官方待审记录`}>待审 <strong>{official.pending}</strong></span>
+      <span className="edrv-review-pending" title={view.pendingTitle}>待审 <strong>{official.pending}</strong></span>
       <Menu open={menu === 'records'} anchor={recordTrigger} items={records.map((item) => ({ id: item.id, label: `轮次 ${item.turn} / 事件 ${item.seq}` }))} selectedId={detail?.item.id} onSelect={selectRecord} onClose={closeMenu} side="top" align="end" portal compact autoFocus />
     </div>
     <div className="edrv-review-tools">
@@ -94,19 +103,19 @@ export function OfficialDiffBar(props: OfficialBarProps): React.ReactElement {
         {navButton('right', '下一个差异文件', props.onNextFile, !props.fileTotal)}
       </div>
       <div className="edrv-review-nav edrv-review-blocknav" role="group" aria-label="差异导航">
-        {navButton('up', '上一个差异', props.onPrevDiff, !count)}
-        <span className="edrv-review-position" aria-live="polite">{position}</span>
-        {navButton('down', '下一个差异', props.onNextDiff, !count)}
+        {navButton('up', '上一个差异', props.onPrevDiff, !count, view.navPrevTitle)}
+        <span className="edrv-review-position" aria-live="polite">{view.position}</span>
+        {navButton('down', '下一个差异', props.onNextDiff, !count, view.navNextTitle)}
       </div>
       <div className="edrv-review-actions">
         <Button size="sm" variant="ghost" className="edrv-review-undo" icon={barIcon('undo')} onClick={props.onUndoFile} disabled={props.reviewBatchBusy || !detail?.capability.undo} title={detail?.capability.reason}>Undo</Button>
-        <Button size="sm" variant="primary" className="edrv-review-keep" icon={barIcon('check')} onClick={props.onAcceptFile} disabled={props.reviewBatchBusy || !detail?.capability.keep} title="保留当前记录的未处理修改">Keep</Button>
+        <Button size="sm" variant="primary" className="edrv-review-keep" icon={barIcon('check')} onClick={props.onAcceptFile} disabled={props.reviewBatchBusy || !detail?.capability.keep} title={detail?.capability.keep ? view.keepHint : detail?.capability.reason}>Keep</Button>
         <Button size="sm" variant="ghost" className="edrv-review-details" onClick={() => setExpanded(!expanded)} aria-expanded={expanded} aria-label={expanded ? '收起差异' : '展开差异'} title={expanded ? '收起差异' : '展开差异'}>详情{barIcon(expanded ? 'up' : 'down')}</Button>
         <Menu open={menu === 'more'} anchor={moreTrigger} items={[{ id: 'pending', label: '差异总览' }, { id: 'archive', label: '归档 / 历史' }]} onSelect={openOverview} onClose={closeMenu} side="top" align="end" portal compact autoFocus />
       </div>
     </div>
-    {detail && staleRegions.length > 0 ? <div className="edrv-review-notice" role="status">{staleRegions.length} 处历史差异无法定位，展开详情查看原始增删。</div> : null}
-    {props.reviewError ? <div className="edrv-review-notice edrv-review-error" role="alert">{props.reviewError}</div> : null}
+    {detail && view.notice ? <div className={view.noticeTone === 'warn' ? 'edrv-review-notice edrv-review-notice-warn' : 'edrv-review-notice'} role="status">{view.notice}</div> : null}
+    {props.reviewError ? <div className={props.reviewErrorTone === 'info' ? 'edrv-review-notice' : 'edrv-review-notice edrv-review-error'} role={props.reviewErrorTone === 'info' ? 'status' : 'alert'}>{props.reviewError}</div> : null}
     {expanded ? <div className="edrv-review-body"><ReviewLedger key={`${official.sessionId}:${official.path}`} sessionId={official.sessionId} first={official.page} path={official.path} /></div> : null}
   </div>
 }

package/src/client/ui/PerfSettings.ts

@@ -320,7 +320,7 @@ export function PerfSettings() {
   ) : null
 
   const guideBody = React.createElement('section', { className: 'vsm-panel' },
-    React.createElement('h3', { className: 'vsm-panel-title' }, '侧车摘要（agent/脚本取关键字段，不整份读 sidecar）'),
+    React.createElement('h3', { className: 'vsm-panel-title' }, '历史改动摘要（agent / 脚本只取关键字段，不整份读）'),
     React.createElement('div', { className: 'vsm-panel-body' },
     React.createElement('p', null, '工作区根目录的 .dsh-edit-review.json（可能数 MB）只应通过摘要接口读取，禁止 agent 整份 read/write 进对话：'),
     React.createElement('pre', { className: 'vsm-perf-block' },