dsh-vscode-mode 0.20.0 → 0.20.2

package/src/client/ui/McpSessionStatus.ts

@@ -20,7 +20,7 @@ function useMcpView({ sessionId, store }: McpRowProps): SessionMcpView {
 
 /** @public @author ddj 2026年10月20号 @param view Current observation. @returns Accessible row label; steady states deliberately do not occupy the leading slot. */
 export function mcpRowLabel(view: SessionMcpView): string | undefined {
-  if (view.stale) return '项目 MCP 状态暂不可用（上次状态已过期）'
+  if (view.stale) return undefined
   if (!view.status || (!busy.has(view.status.phase) && view.status.phase !== 'error')) return undefined
   return '项目 MCP：' + labels[view.status.phase]
 }
@@ -30,7 +30,7 @@ export function McpSessionIcon(props: McpRowProps): React.ReactElement | null {
   const view = useMcpView(props)
   const label = mcpRowLabel(view)
   if (!label) return null
-  const warning = view.stale || view.status?.phase === 'error'
+  const warning = view.status?.phase === 'error'
   return React.createElement('span', {
     role: 'img', 'aria-label': label, title: label,
     style: { display: 'inline-flex', width: 16, height: 16, alignItems: 'center', justifyContent: 'center',
@@ -41,6 +41,13 @@ export function McpSessionIcon(props: McpRowProps): React.ReactElement | null {
 /** @private @author ddj 2026年10月20号 @param start Stage start. @param end Stage finish or local clock. @returns Human-readable elapsed time, without claiming a timeout. */
 function elapsed(start: number, end: number): string { return Math.max(0, (end - start) / 1000).toFixed(1) + ' 秒' }
 
+/** @private @author ddj 2026年10月27号 @param view Query observation. @returns Query-only explanation, separate from initialization health. */
+function queryMessage(view: SessionMcpView): string {
+  if (view.reason === 'paused') return '状态查询已暂停'
+  if (view.reason === 'pending') return '正在查询项目 MCP 状态'
+  return '状态查询暂不可用，不代表 MCP 初始化失败'
+}
+
 /** @public @author ddj 2026年10月20号 @param props Official hover sessionId and poller. @returns Project-only diagnostic detail, never transport credentials. */
 export function McpSessionDetail(props: McpRowProps): React.ReactElement {
   const view = useMcpView(props)
@@ -53,10 +60,18 @@ export function McpSessionDetail(props: McpRowProps): React.ReactElement {
   }, [status, view.stale])
 
   const children: React.ReactNode[] = [React.createElement('strong', { key: 'title' }, '项目 MCP')]
-  if (view.stale) children.push(React.createElement('div', { key: 'stale', role: 'status' }, '状态暂不可用；以下如有记录，为上次观测结果'))
-  if (!status) children.push(React.createElement('div', { key: 'empty' }, view.stale ? '等待状态查询' : '当前无活跃 MCP 实例'))
-  else {
-    const end = status.finishedAt ?? now
+  if (view.stale) {
+    children.push(React.createElement('div', { key: 'stale', role: 'status' }, queryMessage(view)))
+    if (status) children.push(React.createElement('div', { key: 'history' }, '以下为上次观测结果，不代表当前状态'))
+    if (view.observedAt !== undefined) children.push(React.createElement('div', { key: 'observed' },
+      '上次观测时间：' + new Date(view.observedAt).toLocaleString()))
+  }
+  if (!status && !view.stale) children.push(React.createElement('div', { key: 'empty' }, '当前无活跃 MCP 实例'))
+  if (status) {
+    // Unobserved time must not look like continued initialization, including per-server timing.
+    let observedNow = now
+    if (view.stale) observedNow = view.observedAt ?? status.phaseAt
+    const end = status.finishedAt ?? observedNow
     const completed = status.servers.filter((server) => server.phase === 'ready').length
     const slow = !view.stale && busy.has(status.phase) && now - status.phaseAt > 10000
     children.push(React.createElement('div', { key: 'phase' }, labels[status.phase], slow ? '（耗时较长，不代表失败）' : ''))
@@ -64,7 +79,7 @@ export function McpSessionDetail(props: McpRowProps): React.ReactElement {
     if (status.configMs !== undefined) children.push(React.createElement('div', { key: 'config' }, `配置准备 ${elapsed(0, status.configMs)}`))
     if (status.error) children.push(React.createElement('div', { key: 'error' }, status.error))
     for (const server of status.servers) children.push(React.createElement('div', { key: 'server:' + server.serverName },
-      `${server.serverName}：${labels[server.phase]}${server.reused ? ' · 复用已有连接' : ''}${server.phase === 'idle' ? '' : ' · ' + elapsed(server.startedAt, server.finishedAt ?? now)}`,
+      `${server.serverName}：${labels[server.phase]}${server.reused ? ' · 复用已有连接' : ''}${server.phase === 'idle' ? '' : ' · ' + elapsed(server.startedAt, server.finishedAt ?? observedNow)}`,
       server.queuedMs === undefined ? '' : ' · 排队 ' + elapsed(0, server.queuedMs),
       server.connectMs === undefined ? '' : ' · 初始化 ' + elapsed(0, server.connectMs),
       server.firstCallMs === undefined ? '' : ' · 首次工具执行 ' + elapsed(0, server.firstCallMs),

package/src/client/ui/OfficialDiffBar.tsx

@@ -0,0 +1,112 @@
+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'
+
+export interface OfficialBarProps {
+  official: { sessionId: string; path: string; pending: number; detail?: ReviewDetail; records?: ReviewItem[]; page: ReviewPage; onSelect: (id: string) => void }
+  activePath: string
+  pendingRegions?: unknown[]
+  staleRegions?: unknown[]
+  diffIdx?: number
+  fileTotal?: number
+  fileIdx?: number
+  allPendingCount?: number
+  reviewBatchBusy?: boolean
+  batchUnavailable?: string
+  onAcceptAllFiles?: () => void
+  onUndoAllFiles?: () => void
+  onPrevFile: () => void
+  onNextFile: () => void
+  onPrevDiff: () => void
+  onNextDiff: () => void
+  onAcceptFile: () => void
+  onUndoFile: () => void
+  onOpenLauncher: (tab: string) => void
+  reviewError?: string
+}
+
+type Mark = 'left' | 'right' | 'up' | 'down' | 'check' | 'undo' | 'more' | 'file'
+const marks: Record<Mark, string> = {
+  left: 'm10 4-5 4 5 4', right: 'm6 4 5 4-5 4', up: 'm4 10 4-5 4 5', down: 'm4 6 4 5 4-5',
+  check: 'm3 8 3 3 7-7', undo: 'M5 3 2 6l3 3M2 6h7a4 4 0 0 1 0 8',
+  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 {
+  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
+  const [expanded, setExpanded] = React.useState(false)
+  const [menu, setMenu] = React.useState<'records' | 'more' | null>(null)
+  const name = String(props.activePath || '').split(/[\\/]/).pop() || '当前文件'
+  const detail = official.detail
+  const records = official.records ?? []
+  const count = pendingRegions.length
+  const position = count ? `${Math.min(diffIdx + 1, count)} / ${count}` : '—'
+
+  /** @private @author ddj 2026年10月27号 @returns Close current popup without changing selection. */
+  function closeMenu(): void { setMenu(null) }
+  /** @private @author ddj 2026年10月27号 @param id Immutable record ID. @returns Select record and dismiss popup. */
+  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>
+  }
+
+  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')}>
+    {detail ? `轮次 ${detail.item.turn}` : '选择记录'}{barIcon('down')}
+  </Button>
+  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} />
+    {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>
+      <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">
+      <div className="edrv-review-nav" role="group" aria-label="文件导航">
+        {navButton('left', '上一个差异文件', props.onPrevFile, !props.fileTotal)}
+        {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)}
+      </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="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}
+    {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/ReviewAllConfirm.ts

@@ -0,0 +1,35 @@
+import React from 'react'
+import { Button, Modal } from '@deepseek-ai/dsh-client-ui-primitives'
+
+interface ReviewAllProps {
+  reject: boolean
+  count: number
+  onCancel: () => void
+  onConfirm: () => void
+}
+
+/**
+ * @public
+ * @author ddj 2026年10月27号
+ * @description Confirm workspace-wide review through the DSH modal; dismissing never applies a decision.
+ * @param props Pending file count, action and explicit confirmation callbacks.
+ * @returns DSH-themed confirmation with distinct Keep and Undo safety descriptions.
+ */
+export function ReviewAllConfirm(props: ReviewAllProps): React.ReactElement {
+  const action = props.reject ? 'Undo All' : 'Keep All'
+  const warning = props.reject
+    ? '撤销会改写磁盘；逐项安全校验，遇到冲突停止，已完成项不会自动恢复。'
+    : '只标记待审修改为保留，不改写文件。'
+  const footer = React.createElement(React.Fragment, null,
+    React.createElement(Button, { variant: 'ghost', onClick: props.onCancel, autoFocus: true }, '取消'),
+    React.createElement(Button, { variant: 'primary', onClick: props.onConfirm }, '确认 ' + action))
+
+  return React.createElement(Modal, {
+    open: true,
+    title: action + ' 确认',
+    closeLabel: '取消',
+    onClose: props.onCancel,
+    description: `处理当前工作区全部 ${props.count} 个待审差异文件（含其他轮次）？`,
+    footer,
+  }, React.createElement('p', null, warning))
+}

package/src/client-primitives.d.ts

@@ -7,6 +7,40 @@
  * 作者 ddj 2026-09-10
  */
 declare module '@deepseek-ai/dsh-client-ui-primitives' {
+  /** Compact theme-backed button; mirrors official Button.d.ts. @author ddj 2026年10月27号 */
+  export const Button: import('react').ComponentType<import('react').ButtonHTMLAttributes<HTMLButtonElement> & {
+    variant?: 'primary' | 'ghost' | 'outline' | 'toolbar'
+    size?: 'md' | 'sm'
+    icon?: import('react').ReactNode
+  }>
+
+  /** Centered body-portaled dialog; mirrors official Modal.d.ts. @author ddj 2026年10月27号 */
+  export const Modal: import('react').ComponentType<{
+    open: boolean
+    onClose: () => void
+    title: string
+    description?: string
+    children?: import('react').ReactNode
+    footer?: import('react').ReactNode
+    className?: string
+    contentClassName?: string
+  } & ({ headless: true; closeLabel?: never } | { headless?: false; closeLabel: string })>
+
+  /** Anchored selectable menu; mirrors the subset used from official Menu.d.ts. @author ddj 2026年10月27号 */
+  export const Menu: import('react').ComponentType<{
+    open: boolean
+    anchor: import('react').ReactNode
+    items: readonly { id: string; label: import('react').ReactNode; disabled?: boolean }[]
+    selectedId?: string
+    onSelect: (id: string) => void
+    onClose: () => void
+    side?: 'top' | 'bottom' | 'right'
+    align?: 'start' | 'end'
+    portal?: boolean
+    compact?: boolean
+    autoFocus?: boolean
+  }>
+
   /** 图标组件通用 props（官方 Icon* 组件与 FileTypeIcon 共用形状）。 */
   export interface EdrvIconProps {
     /** 图标边长（px）；省略时用图标自带尺寸。 */

package/src/index.ts

@@ -2,6 +2,7 @@
 import { registerRoutes } from './routes.js'
 import { captureToolResult } from './capture.js'
 import { installCapture } from './officialCapture.js'
+import { installEvidence } from './reviewCapture.js'
 import { closeArchiveDbs } from './archiveDb.js'
 import { handleRpc, integrationBaseUrlOf } from './rpc.js'
 import { newSearcher } from './search/orchestrator.js'
@@ -68,7 +69,8 @@ function createRuntime(ctx: Ctx, config: unknown) {
  * @param runtime Managers created by this instance.
  */
 function attachRuntime(ctx: Ctx, runtime: Runtime): void {
-  const stopCapture = installCapture(ctx)
+  const evidence = installEvidence(ctx)
+  const stopCapture = installCapture(ctx, (cwd, snapshot) => { evidence.persist(cwd, snapshot); return true })
   /** @author ddj 2026年09月28号 @param exec Tool execution. @param result Tool result. */
   function onResult(exec: unknown, result: unknown): void {
     void captureToolResult(ctx, runtime.registry, exec, result)
@@ -87,6 +89,7 @@ function attachRuntime(ctx: Ctx, runtime: Runtime): void {
   /** @author ddj 2026年09月28号 Release every manager even if another cleanup rejects. */
   async function cleanup(): Promise<void> {
     await stopCapture()
+    evidence.dispose()
     runtime.fileVersions.dispose()
     closeArchiveDbs()
     disposeAllServers()

package/src/officialCapture.ts

@@ -1,6 +1,6 @@
 /** Deferred official-event collection; no private snapshot access. @author ddj 2026年10月26号 */
 import { captureState, repairPaths, saveSnapshot } from './reviewDb.js'
-import type { OfficialDiff, OfficialSummary } from './shared/review.js'
+import type { OfficialDiff, OfficialSummary, ReviewSnapshot } from './shared/review.js'
 import type { Ctx } from './store.js'
 import { loadBucket } from './store.js'
 import { log } from './log.js'
@@ -148,12 +148,16 @@ async function readDiff(source: SourceService, task: CaptureTask, index: number,
 }
 
 /** @public @author ddj 2026年10月26号 @param ctx Host lifecycle owner; services remain optional for older Hosts. */
-export function installCapture(ctx: Ctx): () => Promise<void> {
+export function installCapture(ctx: Ctx, onSnapshot?: (cwd: string, snapshot: ReviewSnapshot) => void): () => Promise<void> {
   const collector = createCollector({
     source: () => ctx.get('workspaceChanges'),
     prepare: async (cwd) => { await loadBucket(ctx, cwd); await repairPaths(cwd, resolvePath) },
     identity: resolvePath,
-    persist: saveSnapshot, state: captureState, report: (message) => log.warn(message),
+    persist: (cwd, snapshot) => {
+      const saved = saveSnapshot(cwd, snapshot)
+      onSnapshot?.(cwd, snapshot)
+      return saved
+    }, state: captureState, report: (message) => log.warn(message),
   })
   // Subscribe first: seed reads must not create a live-event race window.
   ctx.on('session/event', collector.enqueue)

package/src/reviewCapture.ts

@@ -0,0 +1,112 @@
+/** Independent byte evidence; official diff remains the only display authority. @author ddj 2026年10月27号 */
+import { rawReviewFile, evidenceBlocks } from './reviewEvidence.js'
+import type { RawReviewFile } from './reviewEvidence.js'
+import type { ReviewSnapshot } from './shared/review.js'
+import { reviewDb } from './reviewDb.js'
+import { resolveTarget } from './store.js'
+import type { Ctx } from './store.js'
+import { log } from './log.js'
+
+interface ByteChain { before: RawReviewFile; after: RawReviewFile; busy: boolean; invalid: boolean }
+interface EvidenceCapture {
+  persist(cwd: string, snapshot: ReviewSnapshot): void
+  dispose(): void
+}
+
+/** @public @author ddj 2026年10月27号 @param ctx Host lifecycle owner. @returns Scoped byte recorder; failures disable undo evidence only, never tool execution. */
+export function installEvidence(ctx: Ctx): EvidenceCapture {
+  const chains = new Map<string, Map<string, ByteChain>>()
+  const staged = new Map<string, Map<string, ByteChain>>()
+  let stopped = false
+  ctx.on('tools/execute', aroundTool)
+  ctx.on('session/event', onEvent)
+  ctx.on('session/disposed', onDisposed)
+
+  /** @private @author ddj 2026年10月27号 @param session Disposed owner. Drops optional in-memory evidence, never persisted official facts. */
+  function onDisposed(session: { id: string }): void { chains.delete(session.id) }
+
+  /** @private @author ddj 2026年10月27号 @returns Current bounded capture footprint, excluding transient filesystem reads. */
+  function footprint(): number {
+    let bytes = 0
+    for (const group of [chains, staged]) {
+      for (const files of group.values()) {
+        for (const chain of files.values()) bytes += chain.before.bytes.length + chain.after.bytes.length
+      }
+    }
+    return bytes
+  }
+
+  /** @private @author ddj 2026年10月27号 @param exec Allowed tool dispatch. @param next Original dispatch. @returns Original result unchanged, regardless of capture failure. */
+  async function aroundTool(exec: any, next: () => Promise<any>): Promise<any> {
+    const session = exec.agent?.session
+    const path = exec.arguments?.file_path
+    if (stopped || !session?.id || !['edit', 'write'].includes(exec.name) || typeof path !== 'string') return next()
+    let fs: any
+    let chain: ByteChain | undefined
+    let target: any
+    try {
+      if ((chains.size >= 16 && !chains.has(session.id)) || footprint() >= 32 * 1024 * 1024) return next()
+      fs = ctx.get('fs')
+      target = await resolveTarget(ctx, session, path)
+      const identity = fs.processPath(target)
+      const before = await readRaw(fs, target, exec.signal)
+      let files = chains.get(session.id)
+      if (!files) { files = new Map(); chains.set(session.id, files) }
+      if (files.size >= 64 && !files.has(identity)) return next()
+      chain = files.get(identity)
+      if (!chain) { chain = { before, after: before, busy: false, invalid: false }; files.set(identity, chain) }
+      if (chain.busy || chain.after.hash !== before.hash) chain.invalid = true
+      chain.busy = true
+    } catch { /* No trustworthy read means no undo evidence, not a failed user tool. */ }
+    try { return await next() }
+    finally {
+      if (chain) {
+        try { chain.after = await readRaw(fs, target, exec.signal) } catch { chain.invalid = true }
+        chain.busy = false
+      }
+    }
+  }
+
+  /** @private @author ddj 2026年10月27号 @param session Source session. @param event Published official turn. Freezes the chain before the next turn can mutate it. */
+  function onEvent(session: any, event: any): void {
+    if (stopped || event.type !== 'workspace/changes') return
+    const files = chains.get(session.id)
+    chains.delete(session.id)
+    if (!files || staged.size >= 128) return
+    staged.set(JSON.stringify([session.id, event.seq]), structuredClone(files))
+  }
+
+  /** @public @author ddj 2026年10月27号 @param cwd Official workspace. @param snapshot Committed official facts. Persists only independently validated, exact-correspondence byte chains. */
+  function persist(cwd: string, snapshot: ReviewSnapshot): void {
+    const key = JSON.stringify([snapshot.sessionId, snapshot.seq])
+    const files = staged.get(key)
+    staged.delete(key)
+    if (!files || stopped) return
+    const db = reviewDb(cwd)
+    for (const file of snapshot.files) {
+      const chain = files.get(file.identity)
+      if (!chain || chain.invalid || chain.busy) continue
+      try {
+        const evidence = { before: chain.before, after: chain.after }
+        evidenceBlocks(file.diff, evidence)
+        db.prepare(`INSERT OR IGNORE INTO review_evidence(file_id,payload)
+          SELECT id,? FROM review_files WHERE session_id=? AND turn=? AND seq=? AND identity=?`)
+          .run(JSON.stringify(evidence), snapshot.sessionId, snapshot.turn, snapshot.seq, file.identity)
+      } catch (error) { log.warn('官方回滚证据不可用：' + String(error)) }
+    }
+  }
+
+  /** @public @author ddj 2026年10月27号 Release bounded in-memory images after capture has drained. */
+  function dispose(): void { stopped = true; chains.clear(); staged.clear() }
+  return { persist, dispose }
+}
+
+/** @private @author ddj 2026年10月27号 @param fs Public filesystem. @param target Backend identity. @returns Raw bounded file or confirmed missing. @throws Any non-missing read error. */
+async function readRaw(fs: any, target: any, signal?: AbortSignal): Promise<RawReviewFile> {
+  try { return rawReviewFile(await fs.readBytes(target, signal, 1024 * 1024)) }
+  catch (error) {
+    const code = (error as { code?: string }).code
+    if (code === 'ENOENT' || code === 'FS_NOT_FOUND') return rawReviewFile(null)
+    throw error
+  }
+}

package/src/reviewDb.ts

@@ -1,5 +1,9 @@
 /** Official history shares the archive connection, but never the legacy callId namespace. @author ddj 2026年10月26号 */
 import { createHash } from 'node:crypto'
+import { existsSync } from 'node:fs'
+import { archiveDbFile } from './paths.js'
+import { reviewBlocks } from './shared/reviewRegions.js'
+import type { ReviewBlockState } from './shared/reviewRegions.js'
 import type { DatabaseSync } from 'node:sqlite'
 import { activeReady, dbFor } from './archiveDb.js'
 import type { CaptureGap, DecideReview, OfficialDiff, ReviewDetail, ReviewItem, ReviewPage, ReviewSnapshot } from './shared/review.js'
@@ -11,7 +15,7 @@ export function reviewDb(cwd: string): DatabaseSync {
   if (!activeReady(cwd)) throw new Error('官方审查要求先完成活跃库迁移')
   const db = dbFor(cwd)
   const version = db.prepare("SELECT value FROM metadata WHERE name='schema'").get() as Row
-  if (version.value === '4') return db
+  if (version.value === '4') { migrateBlocks(cwd, db); return db }
   db.exec('BEGIN IMMEDIATE')
   try {
     db.exec(`CREATE TABLE review_snapshots (
@@ -37,9 +41,37 @@ export function reviewDb(cwd: string): DatabaseSync {
     if (db.isTransaction) db.exec('ROLLBACK')
     throw error
   }
+  migrateBlocks(cwd, db)
   return db
 }
 
+/** @private @author ddj 2026年10月27号 @param cwd Workspace backup identity. @param db Open schema4 database. Extends the official-review sub-schema without changing legacy archive schema. @throws Migration failure, leaving prior decisions intact. */
+function migrateBlocks(cwd: string, db: DatabaseSync): void {
+  if (db.prepare("SELECT value FROM metadata WHERE name='review_schema'").get()) return
+  const backup = archiveDbFile(cwd) + '.before-review-blocks.bak'
+  if (!existsSync(backup)) db.exec(`VACUUM INTO '${backup.replace(/'/g, "''")}'`)
+
+  db.exec('BEGIN IMMEDIATE')
+  try {
+    db.exec(`CREATE TABLE review_blocks (file_id TEXT NOT NULL, block_id TEXT NOT NULL,
+      decision TEXT NOT NULL, PRIMARY KEY(file_id,block_id));
+      CREATE TABLE review_evidence (file_id TEXT PRIMARY KEY, payload TEXT NOT NULL);
+      INSERT INTO metadata(name,value) VALUES('review_schema','2');`)
+    const files = db.prepare('SELECT id,diff,decision FROM review_files').all() as Row[]
+    for (const file of files) seedBlocks(db, String(file.id), JSON.parse(String(file.diff)), String(file.decision))
+    db.exec('COMMIT')
+  } catch (error) {
+    if (db.isTransaction) db.exec('ROLLBACK')
+    throw error
+  }
+}
+
+/** @private @author ddj 2026年10月27号 @param db Transaction connection. @param id File record. @param diff Immutable official source. @param decision Prior file decision. Seeds deterministic blocks without changing source facts. */
+function seedBlocks(db: DatabaseSync, id: string, diff: OfficialDiff, decision: string): void {
+  const insert = db.prepare('INSERT INTO review_blocks VALUES(?,?,?)')
+  for (const block of reviewBlocks(diff)) insert.run(id, block.id, decision)
+}
+
 /** @private @author ddj 2026年10月26号 @param text Canonical serialized input. @returns Collision-resistant identity. */
 function digest(text: string): string { return createHash('sha256').update(text).digest('hex') }
 
@@ -107,7 +139,7 @@ export async function repairPaths(cwd: string, resolvePath: (cwd: string, path:
 /** @private @author ddj 2026年10月26号 @param db Transaction. @param snapshot Source payload. @param hash Source digest. */
 function insertSnapshot(db: DatabaseSync, snapshot: ReviewSnapshot, hash: string): void {
   const { sessionId, turn, seq } = snapshot
-  const previous = db.prepare('SELECT identity,diff,decision FROM review_files WHERE session_id=? AND turn=? AND current=1').all(sessionId, turn) as Row[]
+  const previous = db.prepare('SELECT id,identity,diff,decision FROM review_files WHERE session_id=? AND turn=? AND current=1').all(sessionId, turn) as Row[]
   db.prepare('UPDATE review_snapshots SET current=0 WHERE session_id=? AND turn=?').run(sessionId, turn)
   db.prepare('UPDATE review_files SET current=0 WHERE session_id=? AND turn=?').run(sessionId, turn)
   db.prepare('INSERT INTO review_snapshots VALUES(?,?,?,?,?,1)').run(sessionId, turn, seq, JSON.stringify(snapshot), hash)
@@ -116,7 +148,17 @@ function insertSnapshot(db: DatabaseSync, snapshot: ReviewSnapshot, hash: string
     const encoded = JSON.stringify(file.diff)
     const unchanged = previous.find((item) => item.identity === file.identity && item.diff === encoded)
     const id = digest(JSON.stringify([sessionId, turn, seq, file.identity]))
-    insert.run(id, sessionId, turn, seq, file.identity, JSON.stringify(snapshot.summary.files[index]), encoded, unchanged?.decision ?? 'pending')
+    const decision = String(unchanged?.decision ?? 'pending')
+    insert.run(id, sessionId, turn, seq, file.identity, JSON.stringify(snapshot.summary.files[index]), encoded, decision)
+    seedBlocks(db, id, file.diff, decision)
+    if (unchanged) {
+      // A same-turn republish must preserve mixed per-block decisions, not seed all blocks as mixed.
+      db.prepare(`UPDATE review_blocks SET decision=(SELECT p.decision FROM review_blocks p
+        WHERE p.file_id=? AND p.block_id=review_blocks.block_id)
+        WHERE file_id=? AND EXISTS(SELECT 1 FROM review_blocks p WHERE p.file_id=? AND p.block_id=review_blocks.block_id)`)
+        .run(unchanged.id, id, unchanged.id)
+      db.prepare('INSERT INTO review_evidence SELECT ?,payload FROM review_evidence WHERE file_id=?').run(id, unchanged.id)
+    }
   }
 }
 
@@ -181,9 +223,33 @@ export function reviewDetail(cwd: string, id: string): ReviewDetail | null {
   const row = db.prepare(`SELECT f.*,json_extract(s.payload,'$.capturedAt') AS captured_at FROM review_files f JOIN review_snapshots s
     USING(session_id,turn,seq) WHERE f.id=?`).get(id) as Row | undefined
   if (!row) return null
-  return { item: itemOf(row), diff: JSON.parse(String(row.diff)), capturedAt: String(row.captured_at),
-    capability: { keep: row.current === 1 && row.decision === 'pending', undo: false,
-      reason: '官方仅提供差异块，缺少可验证的历史全文及原始字节；拒绝写回已禁用。可标记已审或打开当前文件继续编辑。' } }
+  const blocks = db.prepare('SELECT block_id AS id,decision FROM review_blocks WHERE file_id=? ORDER BY rowid').all(id) as unknown as ReviewBlockState[]
+  const diff = JSON.parse(String(row.diff)) as OfficialDiff
+  const evidence = db.prepare('SELECT 1 FROM review_evidence WHERE file_id=?').get(id)
+  const pending = row.current === 1 && row.decision === 'pending'
+  const undo = pending && !!evidence && diff.kind === 'text' && diff.before && diff.after && !diff.coarse
+  return { item: itemOf(row), diff, capturedAt: String(row.captured_at), blocks,
+    capability: { keep: pending, undo,
+      reason: undo ? 'Undo 将校验原始字节、当前文件版本及已处理差异块；文件变化会安全拒绝。'
+        : '该记录缺少可验证的原始字节或受控写回能力；仍可显示差异和 Keep，不能猜测历史全文执行 Undo。' } }
+}
+
+/** @public @author ddj 2026年10月27号 @param db Active decision transaction. @param request File or block action. Updates aggregate without losing mixed decisions. @throws Invalid or already-decided block. */
+export function changeBlocks(db: DatabaseSync, request: DecideReview): void {
+  if (request.scope === 'hunk') {
+    const changed = db.prepare("UPDATE review_blocks SET decision=? WHERE file_id=? AND block_id=? AND decision='pending'")
+      .run(request.decision, request.id, request.blockId ?? '')
+    if (changed.changes !== 1) throw new Error('差异块不存在或已处理')
+  } else {
+    db.prepare("UPDATE review_blocks SET decision=? WHERE file_id=? AND decision='pending'").run(request.decision, request.id)
+  }
+  const states = db.prepare('SELECT DISTINCT decision FROM review_blocks WHERE file_id=?').all(request.id) as Row[]
+  const decisions = states.map((row) => String(row.decision))
+  let aggregate = request.decision as string
+  if (decisions.includes('pending')) aggregate = 'pending'
+  else if (decisions.length > 1) aggregate = 'mixed'
+  else if (decisions.length === 1) aggregate = decisions[0]
+  db.prepare('UPDATE review_files SET decision=? WHERE id=?').run(aggregate, request.id)
 }
 
 /** @public @author ddj 2026年10月26号 @param cwd Workspace. @param request Frozen identity/revision. @returns Idempotent decision; rejection never guesses a target. */
@@ -196,13 +262,18 @@ export function decideReview(cwd: string, request: DecideReview): { revision: nu
     const previous = db.prepare('SELECT request,result FROM review_ops WHERE operation_id=?').get(request.operationId) as Row | undefined
     if (previous) {
       if (previous.request !== encoded) throw new Error('operationId 已用于其他请求')
+      if (!previous.result) throw new Error('Undo 尚待写后核对，请重试原操作')
       db.exec('COMMIT')
       return JSON.parse(String(previous.result))
     }
+    if (db.prepare("SELECT 1 FROM review_ops WHERE state='prepared' AND json_extract(request,'$.id')=?").get(request.id)) {
+      throw new Error('该文件有尚待核对的 Undo，暂不能 Keep')
+    }
     if (request.decision !== 'accepted') throw new Error('缺少可信全文证据，禁止拒绝写回')
     const change = db.prepare(`UPDATE review_files SET decision='accepted',revision=revision+1
       WHERE id=? AND seq=? AND revision=? AND current=1 AND decision='pending'`).run(request.id, request.seq, request.revision)
     if (change.changes !== 1) throw new Error('审查版本冲突，请刷新后重试')
+    changeBlocks(db, request)
     const result = { revision: request.revision + 1 }
     db.prepare("INSERT INTO review_ops VALUES(?,?,'committed',?,NULL)").run(request.operationId, encoded, JSON.stringify(result))
     db.exec('COMMIT')

package/src/reviewEvidence.ts

@@ -0,0 +1,70 @@
+/** Raw UTF-8 evidence and patch correspondence; never reconstructs a historical file from disk. @author ddj 2026年10月27号 */
+import { createHash } from 'node:crypto'
+import { reviewBlocks } from './shared/reviewRegions.js'
+import type { OfficialDiff } from './shared/review.js'
+
+export interface RawReviewFile { present: boolean; bytes: string; hash: string }
+export interface ReviewEvidence { before: RawReviewFile; after: RawReviewFile }
+export interface RawReviewBlock { id: string; before: string; after: string; offset: number }
+
+/** @public @author ddj 2026年10月27号 @param bytes File bytes, or null for confirmed absence. @returns Existence-sensitive immutable digest and base64. */
+export function rawReviewFile(bytes: Uint8Array | null): RawReviewFile {
+  const payload = bytes === null ? Buffer.alloc(0) : Buffer.from(bytes)
+  return { present: bytes !== null, bytes: payload.toString('base64'), hash: createHash('sha256')
+    .update(bytes === null ? 'absent:' : 'present:').update(payload).digest('hex') }
+}
+
+/** @private @author ddj 2026年10月27号 @param file Persisted raw image. @returns UTF-8 storage text preserving BOM and terminators. @throws Binary, invalid encoding or corrupt hash. */
+function rawText(file: RawReviewFile): string {
+  const bytes = Buffer.from(file.bytes, 'base64')
+  if (bytes.length > 8 * 1024 * 1024 || bytes.includes(0)) throw new Error('回滚证据不是受支持的 UTF-8 文本')
+  if (rawReviewFile(file.present ? bytes : null).hash !== file.hash) throw new Error('回滚证据哈希不匹配')
+  // ignoreBOM=true retains the BOM codepoint, allowing byte-identical writeText.
+  const text = new TextDecoder('utf-8', { fatal: true, ignoreBOM: true }).decode(bytes)
+  if (!Buffer.from(text, 'utf8').equals(bytes)) throw new Error('回滚证据无法字节往返')
+  return text
+}
+
+/** @private @author ddj 2026年10月27号 @param text Storage text. @returns Physical lines, retaining each original line ending and excluding BOM. */
+function rawLines(text: string): string[] {
+  const body = text.replace(/^\uFEFF/, '')
+  return body.match(/[^\r\n]*(?:\r\n|\n|\r|$)/g)?.filter((line, index, lines) => line !== '' || index !== lines.length - 1) ?? []
+}
+
+/** @private @author ddj 2026年10月27号 @param lines Physical storage lines. @returns Official logical-line comparison basis. */
+function logical(lines: string[]): string[] { return lines.map((line) => line.replace(/(?:\r\n|\r|\n)$/, '')) }
+
+/** @public @author ddj 2026年10月27号 @param diff Official source. @param evidence Independent raw captures. @returns Exact raw segments only when every official hunk reproduces the entire captured result. @throws Incomplete chain, coarse patch or mismatched context/content. */
+export function evidenceBlocks(diff: OfficialDiff, evidence: ReviewEvidence): RawReviewBlock[] {
+  if (diff.kind !== 'text' || diff.coarse) throw new Error('该官方差异没有可靠文本基线')
+  if (diff.before !== evidence.before.present || diff.after !== evidence.after.present) throw new Error('文件存在性证据不一致')
+  const beforeText = rawText(evidence.before), afterText = rawText(evidence.after)
+  const before = rawLines(beforeText), after = rawLines(afterText)
+  const expected = logical(before)
+  let delta = 0
+  for (const hunk of diff.hunks) {
+    const old = hunk.lines.filter((line) => line[0] === ' ' || line[0] === '-').map((line) => line.slice(1))
+    const next = hunk.lines.filter((line) => line[0] === ' ' || line[0] === '+').map((line) => line.slice(1))
+    if (old.length !== hunk.oldLines || next.length !== hunk.newLines) throw new Error('官方差异行数不一致')
+    const position = Math.max(0, hunk.oldStart - 1) + delta
+    if (JSON.stringify(expected.slice(position, position + old.length)) !== JSON.stringify(old)) throw new Error('原始基线与官方上下文不一致')
+    expected.splice(position, old.length, ...next)
+    delta += next.length - old.length
+  }
+  if (JSON.stringify(expected) !== JSON.stringify(logical(after))) throw new Error('采集链未覆盖全部官方变更')
+  if (!diff.hunks.length && beforeText !== afterText) throw new Error('官方没有提供可撤销的变更块')
+  const blocks = reviewBlocks(diff)
+  const segments = blocks.map((block) => ({ id: block.id,
+    before: before.slice(block.oldStart - 1, block.oldStart - 1 + block.oldLines.length).join(''),
+    after: after.slice(block.newStart - 1, block.newStart - 1 + block.newLines.length).join(''),
+    offset: (afterText.startsWith('\uFEFF') ? 1 : 0) + after.slice(0, block.newStart - 1).join('').length }))
+  let reversed = afterText
+  for (const segment of [...segments].reverse()) reversed = reversed.slice(0, segment.offset) + segment.before + reversed.slice(segment.offset + segment.after.length)
+  if (reversed !== beforeText) throw new Error('官方变更外的 BOM、行尾或末尾换行发生变化，证据不足')
+  return segments
+}
+
+/** @public @author ddj 2026年10月27号 @param evidence Raw original images. @returns Exact before and after UTF-8 storage text for guarded writes. */
+export function evidenceText(evidence: ReviewEvidence): { before: string; after: string } {
+  return { before: rawText(evidence.before), after: rawText(evidence.after) }
+}