dsh-vscode-mode 0.8.0 → 0.9.0

package/src/remoteWorkspace.ts

@@ -0,0 +1,177 @@
+/**
+ * dsh-vscode-mode host — dsh-remote-ssh 远程工作区探测与镜像↔远端路径映射。
+ * 背景（issue #7）：dsh-remote-ssh 的「原生远程工作区」cwd 指向本机镜像目录
+ * （如 ~/.dsh/remote-workspaces/<id>，根下含 .remote-ssh.json {profileId, host,
+ * user, remotePath}），agent 的 remote_ssh_write 直写远端；差异审查需要把
+ * 远端参数路径映射回镜像（捕获/读/决策复用本地链路），并把展示路径翻译成远端形态。
+ * 判据与上游 dsh-remote-ssh 的 findMirrorRoot 对齐（host/user/remotePath 必填、
+ * 向上 ≤8 层有界）；纯函数为主，node:fs 仅用于标记读取（带 60s TTL 缓存）。
+ * 作者 ddj 2026年09月23号
+ */
+import { readFileSync } from 'node:fs'
+import { dirname, join } from 'node:path'
+
+// --region 常量与类型
+/** dsh-remote-ssh 工作区标记文件名。 */
+const MARKER = '.remote-ssh.json'
+/** 向上探测的最大层数（含 cwd 自身；与上游 findMirrorRoot 的 8 层有界一致）。 */
+const MAX_DEPTH = 8
+/** 探测结果 TTL（edrv.list 为 5s 轮询，避免每轮都做文件 IO）。 */
+const TTL_MS = 60_000
+
+/** 远程工作区（镜像根 + 标记内容）。 */
+export interface RemoteWs {
+  /** 镜像根（含标记文件的目录，平台绝对路径）。 */
+  root: string
+  host: string
+  user: string
+  /** 远端工作区目录（`~/proj` 或绝对路径，原样保留）。 */
+  remotePath: string
+  profileId?: string
+}
+// --endregion
+
+// --region 探测
+/** cwd → { at, ws } 探测缓存（含阴性结果）。 */
+const cache = new Map<string, { at: number; ws: RemoteWs | null }>()
+
+/**
+ * 标记内容 → 远程工作区（host/user/remotePath 缺任一字段判非法，与上游一致）。
+ * @author ddj 2026年09月23号
+ * @param root 标记所在目录
+ * @param raw 标记文件文本
+ * @returns 合法返回 RemoteWs；非法返回 null
+ */
+function markerWsOf(root: string, raw: string): RemoteWs | null {
+  try {
+    const info = JSON.parse(raw) as Record<string, unknown>
+    if (typeof info.host !== 'string' || !info.host) return null
+    if (typeof info.user !== 'string' || !info.user) return null
+    if (typeof info.remotePath !== 'string' || !info.remotePath) return null
+    const ws: RemoteWs = { root, host: info.host, user: info.user, remotePath: info.remotePath }
+    if (typeof info.profileId === 'string' && info.profileId) ws.profileId = info.profileId
+    return ws
+  } catch {
+    return null
+  }
+}
+
+/**
+ * 从 cwd 起向上有界探测标记（不走缓存）。
+ * @author ddj 2026年09月23号
+ * @param cwd 会话工作区根
+ * @returns 命中合法标记返回 RemoteWs；否则 null
+ */
+function walkRemoteWs(cwd: string): RemoteWs | null {
+  let dir = cwd
+  for (let i = 0; i < MAX_DEPTH; i++) {
+    try {
+      const ws = markerWsOf(dir, readFileSync(join(dir, MARKER), 'utf8'))
+      if (ws) return ws
+    } catch {
+      // 无标记或不可读/JSON 损坏：继续向上（与上游 findMirrorRoot 行为一致）
+    }
+    const parent = dirname(dir)
+    if (parent === dir) break
+    dir = parent
+  }
+  return null
+}
+
+/**
+ * 探测工作区是否为 dsh-remote-ssh 远程工作区（cwd 或向上 ≤8 层找 .remote-ssh.json）。
+ * 结果按 cwd 缓存 60s（含阴性）；标记变更后可用 clearWsCache 立即重置。
+ * @author ddj 2026年09月23号
+ * @param cwd 会话工作区根（可空）
+ * @returns 远程工作区信息；非远程或标记非法返回 null
+ */
+export function findRemoteWs(cwd: string | null | undefined): RemoteWs | null {
+  if (!cwd) return null
+  const now = Date.now()
+  const hit = cache.get(cwd)
+  if (hit && now - hit.at < TTL_MS) return hit.ws
+  const ws = walkRemoteWs(cwd)
+  cache.set(cwd, { at: now, ws })
+  return ws
+}
+
+/**
+ * 清空探测缓存（测试与标记变更后重置用）。
+ * @author ddj 2026年09月23号
+ */
+export function clearWsCache(): void {
+  cache.clear()
+}
+// --endregion
+
+// --region 路径映射
+/**
+ * 前缀剥离：path 必须严格位于 root 之下；等于 root 或不匹配返回 null。
+ * @author ddj 2026年09月23号
+ * @param path 待剥离路径（posix 形态）
+ * @param root 前缀（posix 形态、无尾斜杠）
+ * @returns 相对段；不匹配返回 null
+ */
+function prefixRel(path: string, root: string): string | null {
+  if (path === root || !path.startsWith(root + '/')) return null
+  return path.slice(root.length + 1)
+}
+
+/**
+ * 远端参数路径 → 相对远端工作区目录的相对段。
+ * 支持：相对路径（工具语义即基于远端工作区目录）、绝对路径且 remotePath 为绝对
+ * 形态并为其前缀、`~` 形态且 remotePath 同为 `~` 前缀；Windows 盘符形态按
+ * 非远端语义拒绝。含 `..` 逃逸或空相对段返回 null。
+ * @author ddj 2026年09月23号
+ * @param argPath remote_ssh_write 的 path 参数
+ * @param ws 远程工作区
+ * @returns posix 相对段；不可映射返回 null
+ */
+function remoteRelOf(argPath: string, ws: RemoteWs): string | null {
+  const path = argPath.replace(/\\/g, '/').replace(/^\.\//, '')
+  if (!path) return null
+  const root = ws.remotePath.replace(/\\/g, '/').replace(/\/+$/, '')
+  if (!root) return null
+  let rel: string | null
+  if (path.startsWith('/')) {
+    rel = root.startsWith('/') ? prefixRel(path, root) : null
+  } else if (path === '~' || path.startsWith('~/')) {
+    rel = root.startsWith('~/') ? prefixRel(path, root) : null
+  } else if (/^[A-Za-z]:\//.test(path)) {
+    rel = null
+  } else {
+    rel = path
+  }
+  if (rel === null || rel.split('/').some((seg) => seg === '..')) return null
+  return rel
+}
+
+/**
+ * 远端工具参数路径 → 本机镜像绝对路径。
+ * @author ddj 2026年09月23号
+ * @param argPath remote_ssh_write 的 path 参数
+ * @param ws 远程工作区
+ * @returns 镜像内绝对路径；镜像外/前缀形态不一致/逃逸返回 null
+ */
+export function mirrorTargetOf(argPath: string, ws: RemoteWs): string | null {
+  const rel = remoteRelOf(argPath, ws)
+  return rel === null ? null : join(ws.root, rel)
+}
+
+/**
+ * 镜像内绝对路径 → 远端展示路径（remotePath + 相对段，posix 拼接）。
+ * @author ddj 2026年09月23号
+ * @param mirrorAbs 镜像内绝对路径（通常是记录 path）
+ * @param ws 远程工作区
+ * @returns 远端路径；不在镜像根下返回 null（调用方回落原 path）
+ */
+export function remoteDisplayOf(mirrorAbs: string, ws: RemoteWs): string | null {
+  const path = mirrorAbs.replace(/\\/g, '/')
+  const root = ws.root.replace(/\\/g, '/').replace(/\/+$/, '')
+  if (!root) return null
+  const rel = prefixRel(path, root)
+  if (rel === null || rel.split('/').some((seg) => seg === '..')) return null
+  const remoteRoot = ws.remotePath.replace(/\/+$/, '')
+  return remoteRoot + '/' + rel
+}
+// --endregion

package/src/rpc.ts

@@ -44,6 +44,7 @@ import { findProfileDir, readDevForm, setDevForm } from './devForm.js'
 import { normalizeRel } from './tree.js'
 import { baseNameOf, checkNewName, checkRenameName, isSubPath, joinRelPath, parentRelOf } from './shared/fsNames.js'
 import { invalidateIndex, listDirCached } from './treeIndex.js'
+import { findRemoteWs, remoteDisplayOf, type RemoteWs } from './remoteWorkspace.js'
 import { revealInExplorer } from './reveal.js'
 import { dshHome, debugLogFile, pluginLogRoot } from './paths.js'
 import { clearDebugLog, debugRecord, isDebugLogName, listDebugLogs, readDebugLog } from './debugLog.js'
@@ -56,8 +57,8 @@ const staleCheckedAt = new Map<string, number>()
 /** stale 自动清理最小间隔。 */
 const STALE_CHECK_MIN_MS = 10_000
 
-/** 记录 → 客户端视图（不含 before 全文，仅长度）。 */
-function recView(record: DiffRecord): RecordView {
+/** 记录 → 客户端视图（不含 before 全文，仅长度）；远程工作区附远端展示路径（issue #7）。 */
+function recView(record: DiffRecord, ws: RemoteWs | null = null): RecordView {
   return {
     callId: record.callId,
     toolName: record.toolName,
@@ -75,6 +76,7 @@ function recView(record: DiffRecord): RecordView {
     conflict: record.conflict === true,
     legacy: record.legacy === true,
     at: record.at,
+    ...(ws ? { displayPath: remoteDisplayOf(record.path, ws) ?? undefined } : {}),
   }
 }
 
@@ -232,6 +234,7 @@ async function applyDecisions(
 ): Promise<DecideResult[]> {
   const results: DecideResult[] = []
   const resolved: DiffRecord[] = []
+  const ws = findRemoteWs(cwd)
   let changed = false
   for (const item of items) {
     const record = bucket.get(item.callId)
@@ -255,7 +258,7 @@ async function applyDecisions(
     markDecision(record, item.scope ?? 'call', item.hunkIndex, item.decision)
     changed = true
     if (!wasResolved && recordResolved(record)) resolved.push(record)
-    const result: DecideResult = { callId: item.callId, ok: true, record: recView(record) }
+    const result: DecideResult = { callId: item.callId, ok: true, record: recView(record, ws) }
     if (revertedStale) result.stale = true
     results.push(result)
   }
@@ -434,11 +437,12 @@ export function buildHandlers(
         }
       }
       const out: RecordView[] = []
+      const ws = findRemoteWs(sc.cwd)
       for (const rec of bucket.values()) {
         // 面板全量查询过滤已归档；聊天条按 callId 查询保留（状态徽章仍需正确显示）
         if (!want && rec.archived) continue
         if (want && !want.has(rec.callId)) continue
-        out.push(recView(rec))
+        out.push(recView(rec, ws))
       }
       out.sort((a, b) => (a.at < b.at ? -1 : 1))
       return { ok: true, records: out }
@@ -610,6 +614,7 @@ export function buildHandlers(
       const sc = await requireSession(ctx, args.sessionId)
       if ('err' in sc) return { ok: false, error: sc.err }
       const batches = parseArchive(await readArchiveText(ctx, sc.cwd)).filter((b) => b.cwd === sc.cwd)
+      const ws = findRemoteWs(sc.cwd)
       const entries = batches.map((b) => {
         const recs = Array.isArray(b.records) ? b.records : []
         const sum = recs.reduce((s, r) => {
@@ -620,7 +625,16 @@ export function buildHandlers(
           if (sm.superseded) s.superseded++
           return s
         }, { accepted: 0, rejected: 0, pending: 0, superseded: 0 })
-        return { at: b.at, lastAt: b.lastAt || b.at, path: b.path, batch: b.batch ?? null, reason: b.reason ?? null, nRecords: recs.length, summary: sum }
+        return {
+          at: b.at,
+          lastAt: b.lastAt || b.at,
+          path: b.path,
+          ...(ws ? { displayPath: remoteDisplayOf(b.path, ws) ?? undefined } : {}),
+          batch: b.batch ?? null,
+          reason: b.reason ?? null,
+          nRecords: recs.length,
+          summary: sum,
+        }
       })
       entries.sort((a, b) => (Number(b.batch ?? -1) - Number(a.batch ?? -1)) || (a.at < b.at ? 1 : -1))
       return { ok: true, entries }

package/src/shared/ai.ts

@@ -66,6 +66,12 @@ export interface AiConfigView {
   model: string
   /** 空 = 跟随模型默认（请求不携带 reasoningEffort）。 */
   effort: string
+  /** AI 任务模型（非补全场景）：空/缺省 = 跟随补全配置。 */
+  taskProvider?: string
+  /** AI 任务模型 id（与 taskProvider 成对；空/缺省 = 跟随补全配置）。 */
+  taskModel?: string
+  /** AI 任务模型思考档位（空/缺省 = 跟随补全配置的 effort）。 */
+  taskEffort?: string
 }
 
 /** AI 补全配置更新载荷（edrv.ai.configUpdate）。 */
@@ -75,6 +81,12 @@ export interface AiConfigPatch {
   model?: string
   /** 空 = 清除（跟随默认）。 */
   effort?: string
+  /** AI 任务模型（非补全场景）：空 = 清除（跟随补全配置）。 */
+  taskProvider?: string
+  /** AI 任务模型 id（与 taskProvider 成对更新）。 */
+  taskModel?: string
+  /** AI 任务模型思考档位：空 = 清除（跟随补全配置的 effort）。 */
+  taskEffort?: string
 }
 
 /**

package/src/shared/rpc.ts

@@ -19,7 +19,7 @@ import type { RuleInfo, RuleProject, RuleRefInput, RuleSaveInput } from './rules
 import type { SnippetEntry, SnippetInfo, SnippetProject, SnippetRefInput, SnippetSaveInput } from './snippets.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'
@@ -439,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 }
@@ -453,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 }
@@ -578,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
@@ -592,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