dsh-vscode-mode 0.7.0 → 0.9.0

package/src/shared/rpc.ts

@@ -17,9 +17,9 @@ import type { CompatReport, DevFormInfo } from './compat.js'
 import type { ShellIntegrationStatus, UnityListPayload, UnityProjectEntry } from './integration.js'
 import type { RuleInfo, RuleProject, RuleRefInput, RuleSaveInput } from './rules.js'
 import type { SnippetEntry, SnippetInfo, SnippetProject, SnippetRefInput, SnippetSaveInput } from './snippets.js'
-import type { LspEnvInstallState, LspExtInfo, LspExtUpdate, LspHover, LspLocation, LspMarketItem, LspPosition, LspSemanticTokens, LspServerStatus, LspSymbol } from './lsp.js'
+import type { LspCompletionItem, LspCompletionList, LspEnvInstallState, LspExtInfo, LspExtUpdate, LspHover, LspLocation, LspMarketItem, LspPosition, LspSemanticTokens, LspServerStatus, LspSignatureHelp, LspSymbol } from './lsp.js'
 import type { AiConfigPatch, AiConfigView, AiDirectoryView, AiInlineRequest, AiInlineResult } from './ai.js'
-import type { SvnAction, SvnChangeEntry, SvnConflictArtifact, SvnDiffRevResult, SvnLogEntry, SvnRemoteOutdatedEntry, SvnStatusPayload, SvnSumEntry, SvnUpdateResult } from './svn.js'
+import type { SvnAction, SvnAiPlan, SvnChangeEntry, SvnConflictArtifact, SvnDiffRevResult, SvnIgnoreItem, SvnLogEntry, SvnRemoteOutdatedEntry, SvnStatusPayload, SvnSumEntry, SvnUpdateResult } from './svn.js'
 import type { DapAction, DapAdapterInfo, DapBreakpointAck, DapBreakpointInput, DapConfigSnippet, DapConfigSource, DapDebugConfig, DapFrameView, DapPhase, DapPollResult, DapProcessInfo, DapScopeView, DapVariableView } from './dap.js'
 import { DAP_ACTIONS } from './dap.js'
 import type { LoggerLevel } from './logger.js'
@@ -73,6 +73,139 @@ export function binaryMimeOf(path: string): string {
   return imageMimeOf(path)
 }
 
+// --region 二进制预览通道（edrv.readBinary：响应侧原始字节，省 ~33% base64 编码开销）
+
+/** 二进制读成功响应头（octet-stream 携带元数据；同源请求可直接读取自定义头）。 */
+export const BINARY_READ_HEADERS = {
+  mime: 'x-edrv-mime',
+  size: 'x-edrv-size',
+  version: 'x-edrv-version',
+} as const
+
+/** edrv.readBinary 成功载荷（host Uint8Array 信封；routes 接线后以 octet-stream 原样直出）。 */
+export interface BinaryReadPayload {
+  bytes: Uint8Array
+  mime: string
+  size: number
+  version: string
+}
+
+/** 普通 JSON RPC 调用签名（回退通道复用；shared 不反向依赖 client 包装）。 */
+export type RpcJsonCall = <M extends RpcMethod>(method: M, args: RpcRequestMap[M]) => Promise<RpcResult<M>>
+
+/** 二进制预览读取统一结果：binary=新通道原始字节，base64=回退通道，probed=本次尝试过新通道。 */
+export type PreviewRead =
+  | ({ ok: true; via: 'binary' } & BinaryReadPayload)
+  | { ok: true; via: 'base64'; content: string; size: number; encoding?: 'base64'; mime?: string; version?: string; probed?: boolean }
+  | { ok: false; error: string; resolvedPath?: string; probed?: boolean }
+
+/** 通道探测状态：unknown=按次尝试；unwired=host 有 handler 但 routes 仍强制 JSON（本页不再尝试）。 */
+let binaryTransport: 'unknown' | 'unwired' = 'unknown'
+
+/**
+ * 二进制预览读取（edrv.readBinary，失败自动回退 edrv.read base64 现有路径）。
+ * 降级链：非 200 / 非 octet-stream / 元数据头缺失或长度不符 / 网络错 / host 未接线
+ * 把信封 JSON 化 → 一律立即回退 base64 路径，功能不降级；
+ * 其中「信封被 JSON 化」判定为未接线，探测一次后本页生命周期内不再尝试新通道
+ * （避免每次读图都付一次无效往返与大响应序列化）；其余失败不关停通道（瞬时故障可自愈）。
+ * @author ddj 2026年09月22号
+ * @param rpcJson 类型化 JSON RPC 调用（调用方传入 client rpc 包装）
+ * @param args edrv.readBinary 请求参数
+ * @returns 统一读取结果（via 标记实际通道；probed 供调用方做一次性回退日志）
+ */
+export async function readBinaryPreview(
+  rpcJson: RpcJsonCall,
+  args: RpcRequestMap['edrv.readBinary'],
+): Promise<PreviewRead> {
+  const attempted = binaryTransport !== 'unwired'
+  if (attempted) {
+    const direct = await tryBinaryRead(args)
+    if (direct) return direct
+  }
+  return fallbackRead(rpcJson, args, attempted)
+}
+
+/**
+ * 新通道单次尝试：响应完全符合约定才返回二进制结果，否则返回 null 触发回退。
+ * @author ddj 2026年09月22号
+ * @param args edrv.readBinary 请求参数
+ * @returns 二进制读取结果或 null（null=回退 base64）
+ */
+async function tryBinaryRead(args: RpcRequestMap['edrv.readBinary']): Promise<PreviewRead | null> {
+  try {
+    const res = await fetch(RPC_PATH, {
+      method: 'POST',
+      headers: { 'content-type': 'application/json' },
+      body: JSON.stringify({ method: 'edrv.readBinary', args }),
+    })
+    if (!res.ok) return null
+    const type = res.headers.get('content-type') ?? ''
+    if (!type.includes('application/octet-stream')) return noteJsonBody(res)
+    const size = Number(res.headers.get(BINARY_READ_HEADERS.size))
+    const bytes = new Uint8Array(await res.arrayBuffer())
+    // 元数据头长度必须与实际字节数一致，否则视为非本插件响应（防御中间层/代理）
+    if (!Number.isFinite(size) || size !== bytes.byteLength) return null
+    return {
+      ok: true,
+      via: 'binary',
+      bytes,
+      mime: res.headers.get(BINARY_READ_HEADERS.mime) || binaryMimeOf(args.path),
+      size: bytes.byteLength,
+      version: res.headers.get(BINARY_READ_HEADERS.version) || '',
+    }
+  } catch (error) {
+    return null // 网络错按瞬时故障处理：回退但不关停通道
+  }
+}
+
+/**
+ * 非 octet-stream 响应体判定：host 已有 edrv.readBinary 但 routes 尚未接线时，
+ * 二进制信封会被 JSON 序列化成 {bytes:{0:..}} 普通对象——识别到该形态即标记
+ * 「未接线」（本页不再尝试）；其余 JSON（错误响应/未知方法）仅本次回退不关停。
+ * @author ddj 2026年09月22号
+ * @param res JSON 形态的响应
+ * @returns 恒为 null（统一由调用方回退）
+ */
+async function noteJsonBody(res: Response): Promise<null> {
+  try {
+    const body = (await res.json()) as { ok?: unknown; binary?: { bytes?: unknown } } | null
+    if (body && body.ok === true && body.binary && typeof body.binary === 'object' && body.binary.bytes != null) {
+      binaryTransport = 'unwired'
+    }
+  } catch (error) {
+    /* 非 JSON（代理页/空体）：不判定，仅本次回退 */
+  }
+  return null
+}
+
+/**
+ * base64 回退读取（现有 edrv.read JSON 通道，载荷形状与历史实现一致）。
+ * @author ddj 2026年09月22号
+ * @param rpcJson 类型化 JSON RPC 调用
+ * @param args 请求参数
+ * @param attempted 本次是否尝试过新通道（回带给调用方做一次性日志）
+ * @returns 统一读取结果（调用失败转错误结果，不向上抛）
+ */
+async function fallbackRead(
+  rpcJson: RpcJsonCall,
+  args: RpcRequestMap['edrv.readBinary'],
+  attempted: boolean,
+): Promise<PreviewRead> {
+  const probed = attempted ? { probed: true } : {}
+  try {
+    const res = await rpcJson('edrv.read', { sessionId: args.sessionId, path: args.path, encoding: 'base64' })
+    if (!res.ok) {
+      const legacy = res as { ok: false; error: string; resolvedPath?: string }
+      return { ok: false, error: legacy.error, ...probed, ...(legacy.resolvedPath !== undefined ? { resolvedPath: legacy.resolvedPath } : {}) }
+    }
+    if (res.encoding !== 'base64') return { ok: false, error: '读取失败', ...probed }
+    return { ok: true, via: 'base64', content: res.content, size: res.size, encoding: res.encoding, mime: res.mime, version: res.version, ...probed }
+  } catch (error) {
+    return { ok: false, error: 'read异常:' + String(error), ...probed }
+  }
+}
+// --endregion
+
 /** 决策作用域：call=整条记录，hunk=单个差异块。 */
 export type RpcScope = 'call' | 'hunk'
 
@@ -101,6 +234,10 @@ export interface PerfSession {
   bytes: number
   mtime: number
   active: boolean
+  /** 官方侧栏已归档（0.1.7+ workspaceRegistry.archivedSessionIds 持久位；旧 host 不回传 → undefined，按 false 渲染）。 */
+  archived?: boolean
+  /** 官方侧栏已置顶（0.1.7+ workspaceRegistry.pinnedSessionIds 持久位；旧 host 不回传 → undefined，按 false 渲染）。 */
+  pinned?: boolean
 }
 
 /** 一个工作区的会话聚合（edrv.perf.inventory）。 */
@@ -200,6 +337,7 @@ export interface RpcRequestMap {
   'edrv.reject': { sessionId?: string; callId: string; scope?: RpcScope; hunkIndex?: number }
   'edrv.decideBatch': { sessionId?: string; items: DecideItem[] }
   'edrv.read': { sessionId?: string; path: string; encoding?: 'base64' }
+  'edrv.readBinary': { sessionId?: string; path: string }
   'edrv.versions': { sessionId?: string; paths: string[] }
   'edrv.original': { sessionId?: string; path: string }
   'edrv.save': { sessionId?: string; path: string; content: string; rev?: string }
@@ -258,6 +396,9 @@ export interface RpcRequestMap {
   'edrv.lsp.workspaceSymbol': { sessionId?: string; query: string }
   'edrv.lsp.hover': { sessionId?: string; path: string; position: LspPosition }
   'edrv.lsp.semanticTokens': { sessionId?: string; path: string }
+  'edrv.lsp.completion': { sessionId?: string; path: string; position: LspPosition; context?: { triggerKind?: number; triggerCharacter?: string } }
+  'edrv.lsp.resolveCompletion': { sessionId?: string; path: string; item: LspCompletionItem }
+  'edrv.lsp.signatureHelp': { sessionId?: string; path: string; position: LspPosition }
   'edrv.lsp.redetect': { languageId: string }
   'edrv.lsp.envInstall': { languageId: string; id: string }
   'edrv.lsp.envState': {}
@@ -298,6 +439,7 @@ export interface RpcRequestMap {
   'svn.diffBase': { sessionId?: string; path: string }
   'svn.revert': { sessionId?: string; paths: string[] }
   'svn.add': { sessionId?: string; paths: string[] }
+  'svn.changelist': { sessionId?: string; paths: string[]; name?: string; remove?: boolean }
   'svn.log': { sessionId?: string; path?: string; limit?: number; stopOnCopy?: boolean; startRev?: number; endRev?: number; showMerged?: boolean }
   'svn.diffRev': { sessionId?: string; path: string; revision: number }
   'svn.diffPair': { sessionId?: string; path: string; revA: number; revB: number }
@@ -312,6 +454,14 @@ export interface RpcRequestMap {
   'svn.conflictArtifacts': { sessionId?: string; path: string }
   'svn.diffLocalPair': { sessionId?: string; left: string; right: string }
   'svn.fileSizes': { sessionId?: string; paths: string[] }
+  /** AI 智能整理：只读分析全部变更，产出分组/还原/忽略三段方案（不写工作副本）。 */
+  'svn.aiPlan': { sessionId?: string }
+  /** AI 智能整理执行段：按目录合并写入 svn:ignore 属性（propget 合并，不整体覆盖）。 */
+  'svn.ignore': { sessionId?: string; items: SvnIgnoreItem[] }
+  /** 混合通道投递口：会话 agent 深度分析后把方案 POST 回面板收件箱（免鉴权本地 RPC）。 */
+  'svn.aiPlanSubmit': { sessionId?: string; plan: unknown }
+  /** 混合通道取件口：面板轮询取收件箱方案（since = 注入时刻，早于它的旧投递不算新件）。 */
+  'svn.aiPlanPending': { sessionId?: string; since?: number }
   'edrv.dap.configs': { workspacePath: string }
   'edrv.dap.snippets': {}
   'edrv.dap.processes': { processName?: string }
@@ -335,6 +485,7 @@ export interface RpcOkMap {
   'edrv.reject': { record: RecordView }
   'edrv.decideBatch': { results: DecideResult[] }
   'edrv.read': { content: string; size: number; encoding?: 'base64'; mime?: string; version?: string }
+  'edrv.readBinary': { binary: BinaryReadPayload }
   'edrv.versions': { items: FileVersionItem[] }
   'edrv.original': { content: string; size: number; stale: StaleHunk[]; fallback: boolean }
   'edrv.save': { rev?: string; conflict?: boolean }
@@ -393,6 +544,9 @@ export interface RpcOkMap {
   'edrv.lsp.workspaceSymbol': { symbols: LspSymbol[]; truncated?: boolean }
   'edrv.lsp.hover': { hover?: LspHover }
   'edrv.lsp.semanticTokens': { tokens?: LspSemanticTokens }
+  'edrv.lsp.completion': { completions?: LspCompletionList }
+  'edrv.lsp.resolveCompletion': { item?: LspCompletionItem }
+  'edrv.lsp.signatureHelp': { signatureHelp?: LspSignatureHelp }
   'edrv.lsp.redetect': { servers: LspServerStatus[] }
   'edrv.lsp.envInstall': { started: boolean }
   'edrv.lsp.envState': { states: LspEnvInstallState[] }
@@ -433,6 +587,7 @@ export interface RpcOkMap {
   'svn.diffBase': { base: string | null; working: string; reason?: string; error?: string; binary?: boolean; encodingHint?: boolean }
   'svn.revert': { count: number; summary: string; output: string }
   'svn.add': { count: number; summary: string; output: string }
+  'svn.changelist': { count: number; summary: string; output: string }
   'svn.log': { entries: SvnLogEntry[]; truncated: boolean; target: string; limit?: number }
   'svn.diffRev': SvnDiffRevResult
   'svn.diffPair': SvnDiffRevResult
@@ -447,6 +602,11 @@ export interface RpcOkMap {
   'svn.conflictArtifacts': { artifacts: SvnConflictArtifact[] }
   'svn.diffLocalPair': SvnDiffRevResult
   'svn.fileSizes': { sizes: Array<{ path: string; size: number | null }> }
+  'svn.aiPlan': { plan: SvnAiPlan; entriesCount: number; diffIncluded: boolean; dropped: number; model?: string }
+  'svn.ignore': { count: number; summary: string; output: string }
+  /** accepted = 归一后三段总路径数（0 = ok:false 拒收）；dropped = 幻觉/落选丢弃数。 */
+  'svn.aiPlanSubmit': { accepted: number; dropped: number }
+  'svn.aiPlanPending': { plan: SvnAiPlan | null; dropped: number; at: number }
   'edrv.dap.configs': { configs: DapDebugConfig[]; adapters: DapAdapterInfo[]; source: DapConfigSource }
   'edrv.dap.snippets': { snippets: DapConfigSnippet[] }
   'edrv.dap.processes': { items: DapProcessInfo[] }

package/src/shared/svn.ts

@@ -292,24 +292,39 @@ export interface SvnChangeFilter {
   name?: string
 }
 
+/**
+ * 名称过滤匹配器（性能版）：模式解析与正则编译只做一次，循环内零构造。
+ * `*` 任意串、`?` 单字符（忽略大小写）；无通配符回落子串包含；
+ * 非法正则元字符已转义，永不抛错。与 changeNameMatch 语义一致。
+ * @author ddj 2026年09月23号
+ * @param pattern 过滤串（空/空白 = 全命中）
+ * @returns 单条路径命中判定
+ */
+export function nameMatcherOf(pattern: string | undefined): (path: string) => boolean {
+  const query = String(pattern ?? '').trim().toLowerCase()
+  if (!query) return () => true
+  if (!query.includes('*') && !query.includes('?')) {
+    return (path) => String(path ?? '').toLowerCase().includes(query)
+  }
+  const source = query
+    .replace(/[.+^${}()|[\]\\]/g, '\\$&')
+    .replaceAll('*', '.*')
+    .replaceAll('?', '.')
+  const tester = new RegExp('^' + source + '$')
+  return (path) => tester.test(String(path ?? '').toLowerCase())
+}
+
 /**
  * 路径名称过滤匹配（W1-2）：`*` 任意串、`?` 单字符（忽略大小写）；
  * 无通配符时回落子串包含。非法正则元字符已转义，永不抛错。
+ * 大列表循环场景请改用 nameMatcherOf（预编译，避免逐条构造正则）。
  * @author ddj 2026年09月20号
  * @param path 条目路径（`/` 分隔）
  * @param pattern 过滤串（空/空白 = 不过滤）
  * @returns 是否命中
  */
 export function changeNameMatch(path: string, pattern: string | undefined): boolean {
-  const query = String(pattern ?? '').trim().toLowerCase()
-  if (!query) return true
-  const target = String(path ?? '').toLowerCase()
-  if (!query.includes('*') && !query.includes('?')) return target.includes(query)
-  const source = query
-    .replace(/[.+^${}()|[\]\\]/g, '\\$&')
-    .replaceAll('*', '.*')
-    .replaceAll('?', '.')
-  return new RegExp('^' + source + '$').test(target)
+  return nameMatcherOf(pattern)(path)
 }
 
 /**
@@ -325,8 +340,10 @@ export function svnVisibleChanges(
 ): SvnChangeEntry[] {
   const showUnversioned = filter.unversioned !== false
   const showIgnored = filter.ignored === true
+  // 名称匹配器循环外编译一次（大列表逐条 new RegExp 是键入卡顿主源之一）
+  const nameHit = nameMatcherOf(filter.name)
   return entries.filter((entry) => {
-    if (!changeNameMatch(entry.path, filter.name)) return false
+    if (!nameHit(entry.path)) return false
     if (entry.status === 'ignored') return showIgnored
     if (entry.status === 'unversioned') return showUnversioned
     return isSvnChange(entry)
@@ -443,6 +460,53 @@ export interface SvnRenamePair {
   unversionedPath: string
 }
 
+/** 改名配对 size 批量查询单次上限（host `svn.fileSizes` 同值护栏；client 预截断对齐，防请求白打）。 */
+export const FILE_SIZES_CAP = 200
+
+/** 批量路径动作单次上限（revert/add/changelist 共用；host mutate 权威护栏，client 预分块对齐）。 */
+export const BATCH_PATHS_CAP = 64
+
+/** 分区名（changelist 名）长度上限（过长名可读性差且易混入选项位）。 */
+export const SVN_CHANGELIST_NAME_MAX = 64
+
+// --region P5 分区管理（changelist）
+
+/**
+ * 分区名（changelist 名）合法性校验：返回错误文案，合法返回 null。
+ * 规则：去首尾空白后非空、不以 `-` 开头（防被 svn 当成选项解析）、长度 ≤ 上限。
+ * client 预检 + host 权威校验共用，避免两处漂移。
+ * @author ddj 2026年09月23号
+ * @param name 用户输入的分区名
+ * @returns 错误文案；合法为 null
+ */
+export function svnChangelistNameErrorOf(name: string): string | null {
+  const trimmed = String(name ?? '').trim()
+  if (!trimmed) return '分区名不能为空'
+  if (trimmed.startsWith('-')) return '分区名不能以 - 开头'
+  if (trimmed.length > SVN_CHANGELIST_NAME_MAX) return '分区名最长 ' + SVN_CHANGELIST_NAME_MAX + ' 字符'
+  return null
+}
+
+/**
+ * 路径清单按单次上限分块（host 批量路径上限护栏的客户端对齐）。
+ * @author ddj 2026年09月23号
+ * @param paths 路径列表
+ * @param cap 单块上限（≤0 或非有限值视为不分块，整包一块）
+ * @returns 分块数组（保持原顺序；空入参返回 []）
+ */
+export function svnChunksOf(paths: readonly string[], cap: number): string[][] {
+  const size = Number.isFinite(cap) && cap > 0 ? Math.floor(cap) : 0
+  if (!paths.length) return []
+  if (!size || paths.length <= size) return [[...paths]]
+  const chunks: string[][] = []
+  for (let start = 0; start < paths.length; start += size) {
+    chunks.push(paths.slice(start, start + size))
+  }
+  return chunks
+}
+
+// --endregion
+
 /** 取路径 basename（`/`/`\` 通用；纯函数）。 */
 function baseNameOf(path: string): string {
   return String(path ?? '').split(/[\\/]/).pop() ?? ''
@@ -522,3 +586,225 @@ export interface SvnConflictArtifact {
 }
 
 // --endregion
+
+// --region AI 智能整理（方案类型/归一化，11-ai-changelist-triage）
+
+/** AI 整理方案单条建议（还原/忽略）。 */
+export interface SvnAiPlanItem {
+  /** 工作区相对路径。 */
+  path: string
+  /** AI 判定理由（预览展示用；可缺省）。 */
+  reason?: string
+}
+
+/** AI 整理方案分组建议（目标 changelist 组）。 */
+export interface SvnAiPlanGroup {
+  /** 目标分区名（changelist 名）。 */
+  name: string
+  /** 组内路径（工作区相对）。 */
+  paths: string[]
+  /** 分组理由（预览展示用；可缺省）。 */
+  reason?: string
+}
+
+/** AI 整理方案（三段互斥：分组/还原/忽略；normalizeAiPlan 归一后一路径至多一段）。 */
+export interface SvnAiPlan {
+  /** 建议分组（changelist）。 */
+  groups: SvnAiPlanGroup[]
+  /** 建议还原（revert）。 */
+  reverts: SvnAiPlanItem[]
+  /** 建议忽略（写 svn:ignore 属性）。 */
+  ignores: SvnAiPlanItem[]
+}
+
+/** svn:ignore 写入项（目标目录 + 该目录下新增忽略名列表）。 */
+export interface SvnIgnoreItem {
+  /** 目录（工作区相对；'' = 工作副本根）。 */
+  dir: string
+  /** 该目录下要忽略的文件/目录名（basename）。 */
+  names: string[]
+}
+
+/** AI 方案分组数上限（超出丢弃，防止过度碎片化）。 */
+export const AI_PLAN_GROUPS_CAP = 20
+
+/** AI 方案分析条目数上限（超出仅按路径分析并标记截断）。 */
+export const AI_PLAN_PATHS_CAP = 1500
+
+/** AI 方案 diff 上下文字节上限（超出降级 paths-only）。 */
+export const AI_PLAN_DIFF_CAP = 2 * 1024 * 1024
+
+/** AI 方案 LLM 调用超时（毫秒；推理模型 + 高思考档位 + diff 上下文实测 120s 不够（huoshan/glm-5.3-flash），放宽到 5 分钟）。 */
+export const AI_PLAN_TIMEOUT_MS = 300 * 1000
+
+/** 松散数组取值（非数组按空处理；AI 输出形状容错）。 */
+function listOf(raw: unknown): unknown[] {
+  return Array.isArray(raw) ? raw : []
+}
+
+/**
+ * AI 方案条目解析（宽松：接受 `{path, reason}` 或裸路径字符串；反斜杠归一为 `/`）。
+ * @author ddj 2026年09月23号
+ * @param raw 原始元素
+ * @returns 解析结果（不可解析返回 null——非路径垃圾不作数）
+ */
+export function planItemOf(raw: unknown): SvnAiPlanItem | null {
+  const obj = typeof raw === 'string' ? { path: raw } : (raw && typeof raw === 'object' ? raw as { path?: unknown; reason?: unknown } : null)
+  if (!obj) return null
+  const path = typeof obj.path === 'string' ? obj.path.trim().replace(/\\/g, '/') : ''
+  if (!path) return null
+  const reason = typeof obj.reason === 'string' ? obj.reason.trim().slice(0, 120) : ''
+  return reason ? { path, reason } : { path }
+}
+
+/**
+ * AI 方案分组解析（宽松：name + paths 数组；路径逐个规范化）。
+ * @author ddj 2026年09月23号
+ * @param raw 原始元素
+ * @returns 解析结果（无合法名返回 null）
+ */
+export function planGroupOf(raw: unknown): { name: string; paths: string[]; reason?: string } | null {
+  if (!raw || typeof raw !== 'object') return null
+  const obj = raw as { name?: unknown; paths?: unknown; reason?: unknown }
+  const name = typeof obj.name === 'string' ? obj.name.trim() : ''
+  if (!name) return null
+  const paths: string[] = []
+  for (const p of listOf(obj.paths)) {
+    const path = typeof p === 'string' ? p.trim().replace(/\\/g, '/') : ''
+    if (path) paths.push(path)
+  }
+  const reason = typeof obj.reason === 'string' ? obj.reason.trim().slice(0, 120) : ''
+  return reason ? { name, paths, reason } : { name, paths }
+}
+
+/**
+ * AI 方案归一化（纯函数）：以真实变更清单为白名单裁决三段建议。
+ * - 幻觉路径（不在清单中）/状态不符（revert 须 versioned、ignore 须 unversioned）→ 丢弃并计数；
+ * - 互斥优先级 revert > ignore > group（同一路径至多归一段，还原后条目消失故优先）；
+ * - 组名过 svnChangelistNameErrorOf、组数上限 AI_PLAN_GROUPS_CAP，空组剔除。
+ * @author ddj 2026年09月23号
+ * @param raw AI 输出解析结果（形状不定，内部容错）
+ * @param entries 真实变更清单（白名单来源）
+ * @returns 归一化方案与被丢弃的候选路径数
+ */
+export function normalizeAiPlan(raw: unknown, entries: readonly SvnChangeEntry[]): { plan: SvnAiPlan; dropped: number } {
+  const plan: SvnAiPlan = { groups: [], reverts: [], ignores: [] }
+  if (!raw || typeof raw !== 'object') return { plan, dropped: 0 }
+  const byPath = new Map<string, SvnChangeEntry>()
+  for (const entry of entries) if (entry?.path) byPath.set(entry.path, entry)
+  const claimed = new Set<string>()
+  let dropped = 0
+  /** 单条裁决：真实存在 + 状态符合 + 未被更高优先级段认领。 */
+  const accept = (path: string, wantVersioned: boolean): boolean => {
+    const entry = byPath.get(path)
+    if (!entry || !isSvnChange(entry) || entry.versioned !== wantVersioned || claimed.has(path)) { dropped++; return false }
+    claimed.add(path)
+    return true
+  }
+  const src = raw as { groups?: unknown; reverts?: unknown; ignores?: unknown }
+  // 互斥优先级：revert > ignore > group
+  for (const el of listOf(src.reverts)) {
+    const item = planItemOf(el)
+    if (item && accept(item.path, true)) plan.reverts.push(item)
+  }
+  for (const el of listOf(src.ignores)) {
+    const item = planItemOf(el)
+    if (item && accept(item.path, false)) plan.ignores.push(item)
+  }
+  for (const el of listOf(src.groups)) {
+    const group = planGroupOf(el)
+    if (!group) {
+      // 形状不整但含路径候选（如空名组）：候选路径同样计入 dropped，保持丢弃口径一致
+      const obj = el && typeof el === 'object' ? el as { paths?: unknown } : null
+      for (const p of listOf(obj?.paths)) {
+        if (typeof p === 'string' && p.trim()) dropped++
+      }
+      continue
+    }
+    const nameError = svnChangelistNameErrorOf(group.name) !== null
+    const over = plan.groups.length >= AI_PLAN_GROUPS_CAP
+    const valid: string[] = []
+    for (const path of group.paths) {
+      if (nameError || over) { dropped++; continue }
+      if (accept(path, true)) valid.push(path)
+    }
+    if (valid.length && !nameError && !over) {
+      plan.groups.push(group.reason ? { name: group.name, paths: valid, reason: group.reason } : { name: group.name, paths: valid })
+    }
+  }
+  return { plan, dropped }
+}
+
+/**
+ * 忽略路径清单 → 目录聚合写入项（纯函数）：路径拆 dir + basename，同目录合并、同名去重。
+ * 供 `svn.ignore` 的执行载荷构造（一个目录一次 propset，进度粒度按目录）。
+ * @author ddj 2026年09月23号
+ * @param paths 未版本化路径清单（工作区相对）
+ * @returns 目录聚合写入项（保持目录首次出现顺序；空入参返回 []）
+ */
+export function ignoreItemsOf(paths: readonly string[]): SvnIgnoreItem[] {
+  const byDir = new Map<string, string[]>()
+  for (const raw of paths) {
+    const norm = String(raw ?? '').trim().replace(/\\/g, '/').replace(/^\.\//, '').replace(/\/+$/, '')
+    if (!norm) continue
+    const cut = norm.lastIndexOf('/')
+    const dir = cut <= 0 ? '' : norm.slice(0, cut)
+    const name = cut <= 0 ? norm : norm.slice(cut + 1)
+    if (!name) continue
+    const bucket = byDir.get(dir)
+    if (bucket) {
+      if (!bucket.includes(name)) bucket.push(name)
+    } else {
+      byDir.set(dir, [name])
+    }
+  }
+  return [...byDir.entries()].map(([dir, names]) => ({ dir, names }))
+}
+
+/** 深度分析投递口地址（host RPC 本地免鉴权；agent 用 shell 直接 POST）。 */
+const AGENT_SUBMIT_URL = 'http://127.0.0.1:3080/edrv/rpc'
+
+/**
+ * 会话 agent 深度分析任务文本（混合通道 02-deep-session-prompt 修正版）。
+ * 在**独立新会话**草稿箱填入后由用户发送；agent 自跑只读 `svn status` 取清单
+ * （prompt 定长瘦身，不随变更数膨胀），借 codegraph/读文件/sub agent 深度分析，
+ * 产出方案经免鉴权 RPC `svn.aiPlanSubmit` 投递回面板收件箱——确认与执行仍全部
+ * 走面板（agent 禁写、只读放行）。
+ * @author ddj 2026年09月23号
+ * @param wcRoot 工作副本根（取数指引内嵌）
+ * @param sessionId 会话 id（投递命令内嵌；host 按它解析工作副本）
+ * @returns 任务文本（定长 ~1KB：取数指引/分析要求/投递命令/硬约束）
+ */
+export function buildAgentPrompt(wcRoot: string, sessionId: string): string {
+  return [
+    '请对 SVN 工作副本「' + wcRoot + '」的本地变更做**深度分析**，产出整理方案（分组/还原/忽略三段）。',
+    '',
+    '取数（只读命令允许）：',
+    '- 先执行 `svn status`（只读）获取完整变更清单；',
+    '- 判断改动性质时用 `svn diff`（只读）查看具体改动。',
+    '',
+    '分析要求（按需使用你的工具）：',
+    '- 借助 codegraph 查询调用链/模块归属，判断哪些文件属于同一功能主题（分组依据）；',
+    '- 按需读取文件内容，判断改动性质（误改/行尾空白噪音/试验性改动 → 建议还原）；',
+    '- 未版本化条目判断是否为生成物/临时文件/日志/缓存（建议忽略）；',
+    '- 需要并行探索时可用 sub agent。',
+    '',
+    '方案 JSON 形状（reason 为简短中文一句话）：',
+    '{ "groups": [{ "name": "英文短横线名", "paths": ["路径1"], "reason": "理由" }],',
+    '  "reverts": [{ "path": "路径", "reason": "理由" }],',
+    '  "ignores": [{ "path": "路径", "reason": "理由" }] }',
+    '',
+    '硬约束：',
+    '1. 禁止任何**写**操作（revert/commit/changelist/propset/update/merge 等一律禁止）；只读命令（status/diff/log/cat/info）允许；',
+    '2. 每个路径至多归一类（groups/reverts/ignores 互斥），拿不准的不填；',
+    '3. 组名用简短英文、不以 - 开头；',
+    '4. 只使用 `svn status` 实际返回的路径，绝不虚构或改写路径。',
+    '',
+    '分析完成后，用 shell 执行下面的命令把方案投递回面板（把 <PLAN_JSON> 替换为方案 JSON）：',
+    'Invoke-RestMethod -Uri ' + AGENT_SUBMIT_URL + ' -Method Post -ContentType \'application/json\' -Body (@{ method = \'svn.aiPlanSubmit\'; args = @{ sessionId = \'' + sessionId + '\'; plan = <PLAN_JSON> } } | ConvertTo-Json -Depth 8)',
+    '',
+    '投递成功会返回 { ok, accepted, dropped }；随后我会在面板弹窗中确认执行，你无需再做任何操作。',
+  ].join('\n')
+}
+
+// --endregion

package/src/shared/types.ts

@@ -38,7 +38,7 @@ export interface Decisions {
 /** 审查记录（host 内部存储与传给 client 的视图共用核心字段）。 */
 export interface RecordBase {
   callId: string
-  toolName: 'edit' | 'write'
+  toolName: 'edit' | 'write' | 'remote_ssh_write'
   path: string
   create: boolean
   callHunk: CallHunk | null
@@ -68,6 +68,8 @@ export interface DiffRecord extends RecordBase {
 /** 发往 client 的记录视图（不含 before 全文，仅长度）。 */
 export interface RecordView extends RecordBase {
   beforeLen: number
+  /** 展示路径（远程工作区为远端路径；运行时计算，不持久化）。 */
+  displayPath?: string
 }
 
 /** 归档条目内单条记录的存档视图。 */
@@ -109,6 +111,8 @@ export interface ArchiveEntry {
   at: string
   lastAt: string
   path: string
+  /** 展示路径（远程工作区为远端路径；运行时计算，不持久化）。 */
+  displayPath?: string
   batch: number | null
   reason: string | null
   nRecords: number