dsh-vscode-mode 0.7.0 → 0.9.0

package/lib/index.js

@@ -7,6 +7,7 @@ import { homedir, tmpdir } from "node:os";
 import { createHash, randomUUID } from "node:crypto";
 import { Buffer as Buffer$1 } from "node:buffer";
 import { execFile, spawn } from "node:child_process";
+import z from "@deepseek-ai/schemastery";
 import { inflateRawSync } from "node:zlib";
 //#region src/mcp.ts
 /**
@@ -190,6 +191,17 @@ function tortoiseLaunchArgv(exe, action, absPath) {
 		"/path:" + absPath
 	];
 }
+/**
+* 是否属于「工作副本变更」（`normal`/`external` 不算；`ignored` 由开关决定是否收录）。
+* @author ddj 2026年09月16号
+* @param entry 变更条目
+* @returns 是否计入变更清单
+*/
+function isSvnChange(entry) {
+	if (entry.status === "normal" || entry.status === "external") return false;
+	if (entry.status === "ignored") return false;
+	return true;
+}
 /** W2-6 内容护栏嗅探窗（字符数；NUL/U+FFFD 只看前 8K，全量扫描大文本得不偿失）。 */
 const GUARD_SNIFF_CHARS = 8192;
 /**
@@ -207,6 +219,245 @@ function contentGuardOf(text) {
 	if (window.includes("�")) return { encodingHint: true };
 	return {};
 }
+/**
+* 分区名（changelist 名）合法性校验：返回错误文案，合法返回 null。
+* 规则：去首尾空白后非空、不以 `-` 开头（防被 svn 当成选项解析）、长度 ≤ 上限。
+* client 预检 + host 权威校验共用，避免两处漂移。
+* @author ddj 2026年09月23号
+* @param name 用户输入的分区名
+* @returns 错误文案；合法为 null
+*/
+function svnChangelistNameErrorOf(name) {
+	const trimmed = String(name ?? "").trim();
+	if (!trimmed) return "分区名不能为空";
+	if (trimmed.startsWith("-")) return "分区名不能以 - 开头";
+	if (trimmed.length > 64) return "分区名最长 64 字符";
+	return null;
+}
+/** AI 方案分析条目数上限（超出仅按路径分析并标记截断）。 */
+const AI_PLAN_PATHS_CAP = 1500;
+/** AI 方案 diff 上下文字节上限（超出降级 paths-only）。 */
+const AI_PLAN_DIFF_CAP = 2097152;
+/** AI 方案 LLM 调用超时（毫秒；推理模型 + 高思考档位 + diff 上下文实测 120s 不够（huoshan/glm-5.3-flash），放宽到 5 分钟）。 */
+const AI_PLAN_TIMEOUT_MS = 3e5;
+/** 松散数组取值（非数组按空处理；AI 输出形状容错）。 */
+function listOf(raw) {
+	return Array.isArray(raw) ? raw : [];
+}
+/**
+* AI 方案条目解析（宽松：接受 `{path, reason}` 或裸路径字符串；反斜杠归一为 `/`）。
+* @author ddj 2026年09月23号
+* @param raw 原始元素
+* @returns 解析结果（不可解析返回 null——非路径垃圾不作数）
+*/
+function planItemOf(raw) {
+	const obj = typeof raw === "string" ? { path: raw } : raw && typeof raw === "object" ? raw : 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）
+*/
+function planGroupOf(raw) {
+	if (!raw || typeof raw !== "object") return null;
+	const obj = raw;
+	const name = typeof obj.name === "string" ? obj.name.trim() : "";
+	if (!name) return null;
+	const paths = [];
+	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 归一化方案与被丢弃的候选路径数
+*/
+function normalizeAiPlan(raw, entries) {
+	const plan = {
+		groups: [],
+		reverts: [],
+		ignores: []
+	};
+	if (!raw || typeof raw !== "object") return {
+		plan,
+		dropped: 0
+	};
+	const byPath = /* @__PURE__ */ new Map();
+	for (const entry of entries) if (entry?.path) byPath.set(entry.path, entry);
+	const claimed = /* @__PURE__ */ new Set();
+	let dropped = 0;
+	/** 单条裁决：真实存在 + 状态符合 + 未被更高优先级段认领。 */
+	const accept = (path, wantVersioned) => {
+		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;
+	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) {
+			const obj = el && typeof el === "object" ? el : 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 >= 20;
+		const valid = [];
+		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
+	};
+}
+//#endregion
+//#region src/shared/nativeOpen.ts
+/**
+* dsh-vscode-mode shared — 原生打开范围判定（host/client 双面契约）。
+* 背景：DSH 文件预览双形态——本插件认领 `dsh-resource://file/**` 进 Monaco 编辑，
+* 官方渲染器（Office 预览/不可预览提示/表格预览）看认领让位。本模块承载「原生打开」
+* 范围的单一事实源：默认集 = 让位清单（插件本来就不认领的后缀），用户可经设置
+* `nativeOpenExts`（逗号分隔）增删；host 的 Config schema 默认值与 client 的
+* 文件树点击判定 / claim 认领判定共用，保证三处永不同源漂移。
+* 决策沿袭（不因本模块迁移而变）：CSV/TSV **不在**默认集——官方 0.1.7 有表格预览，
+* 但编辑器可编辑性优先，仅用户显式加入 nativeOpenExts 才让位（同 avif 例外先例）。
+* 作者 ddj 2026年09月22号
+*/
+/**
+* Office 文档后缀：官方 `dsh-client-ui-sidebar-documentpreview` 的 Office 渲染器
+* 声明 `doc/docx/xls/xlsx/ppt/pptx`（0.1.6 起侧栏 Office 预览；0.1.7 扩展表格 CSV/TSV
+* 只读预览——本清单刻意不含 csv/tsv，见文件头决策）。本插件让位官方（不认领），
+* 否则会把这些文件路由进 Monaco 而丢掉官方预览。
+*/
+const OFFICE_EXT = [
+	"doc",
+	"docx",
+	"xls",
+	"xlsx",
+	"ppt",
+	"pptx",
+	"odt",
+	"ods",
+	"odp",
+	"pages",
+	"numbers"
+];
+/**
+* 官方「不可预览二进制容器」清单（`UNVIEWABLE_BINARY_EXTENSIONS`，逐项取自
+* `dsh-client-ui-sidebar-documentpreview/lib/client.js`）。这些后缀官方会给出
+* 「无法预览」提示；本插件让位官方，避免把二进制当文本读成乱码。
+*
+* ⚠️ 刻意例外：官方清单含 `avif`，但本插件图片预览支持 avif（浏览器原生解码），
+* 故从本表**移除** `avif` —— 保留本插件的图片预览优于官方的「不可预览」。
+* @author ddj 2026年09月18号
+*/
+const BLIND_EXT = [
+	"mp4",
+	"mov",
+	"avi",
+	"mkv",
+	"webm",
+	"flv",
+	"wmv",
+	"m4v",
+	"mp3",
+	"wav",
+	"flac",
+	"ogg",
+	"m4a",
+	"aac",
+	"wma",
+	"opus",
+	"zip",
+	"gz",
+	"tgz",
+	"bz2",
+	"xz",
+	"zst",
+	"7z",
+	"rar",
+	"tar",
+	"jar",
+	"exe",
+	"dll",
+	"so",
+	"dylib",
+	"bin",
+	"o",
+	"class",
+	"pyc",
+	"wasm",
+	"ttf",
+	"otf",
+	"woff",
+	"woff2",
+	"eot",
+	"dmg",
+	"iso",
+	"img",
+	"sqlite",
+	"db",
+	"psd",
+	"ai",
+	"sketch",
+	"tiff",
+	"tif",
+	"heic",
+	"heif"
+];
+/** 默认范围的设置序列（逗号分隔；Config schema 默认值与设置页回显同源）。 */
+const DEFAULT_NATIVE_CSV = [...OFFICE_EXT, ...BLIND_EXT].join(",");
 //#endregion
 //#region src/shared/logger.ts
 /**
@@ -322,19 +573,23 @@ function bindHostLog(ctx) {
 * dsh-vscode-mode host — 文件链接打开工具 + 快捷键的持久化设置。
 * 依赖守卫：schemastery 动态加载；@deepseek-ai/dsh-settings 仅作 legacy 探测——
 * rc 线导出 installSettingsSection free function，0.1.2-alpha 起移除（改由 settings
-* 服务的 installSection 方法承载，见 runSettingsInstall 三策略）。
+* 服务的 installSection 方法承载），0.1.7 再移除 installSection（设置并入 profile
+* 插件 Config schema，见 runSettingsInstall 四策略：legacy/service/forms/none）。
 * 缺失/任一策略失败时插件仍可加载（fileOpenTool 降级为配置值，compat 报告可见），
 * 全程 try/catch，不产生未捕获 rejection。
-* 作者 ddj 2026年08月24号 / 2026年08月26号 / 2026年09月02号
+* 作者 ddj 2026年08月24号 / 2026年08月26号 / 2026年09月02号 / 2026年09月22号 / 2026年09月23号
 */
 const FILE_OPEN_SETTINGS_NS = "dsh-vscode-mode";
 const FILE_OPEN_DEFAULT = "auto";
-/** AI 内联补全配置默认值（默认关闭；路由空 = 自动；档位空 = 跟随模型默认）。 */
+/** AI 配置默认值（补全默认关；路由空 = 自动；档位空 = 跟随模型默认；任务模型空 = 跟随补全配置）。 */
 const AI_CONFIG_DEFAULT = {
 	enabled: false,
 	provider: "",
 	model: "",
-	effort: ""
+	effort: "",
+	taskProvider: "",
+	taskModel: "",
+	taskEffort: ""
 };
 let depsPromise;
 /**
@@ -437,6 +692,7 @@ function loadSettingsDeps(importFn = hostImport) {
 const INSTALL_UNMOUNTED = "设置 section 尚未装配";
 const INSTALL_LEGACY = "rc 线：dsh-settings.installSettingsSection";
 const INSTALL_SERVICE = "0.1.2-alpha 线：settings 服务 installSection";
+const INSTALL_FORMS = "0.1.7 线：设置并入插件 Config schema（SettingsForms）";
 const INSTALL_NONE = "两路均不可用：设置持久化降级为配置值";
 let observedInstall = {
 	strategy: "unknown",
@@ -459,14 +715,51 @@ function settingsInstallNote() {
 	return observedInstall.note;
 }
 /**
+* 判定设置写冲突错误（0.1.7 SettingsConflictError：code 常量 / 构造器名双通道）。
+* @author ddj 2026年09月22号
+* @param error 捕获到的错误
+* @returns 是否为 revision 冲突
+*/
+function isConflictError(error) {
+	if (!error || typeof error !== "object") return false;
+	const e = error;
+	return e.code === "SETTINGS_CONFLICT" || e.name === "SettingsConflictError";
+}
+/**
+* 0.1.7 forms 策略：订阅 settings/document-updated 事件，目标 namespace 变化时
+* 把 describe 最新值推给 hooks（setSource + onChange），替代旧 installSection 的
+* 变更回调；disposer 经 ctx.effect 随插件 fiber 卸载（热重载不泄漏）。
+* @author ddj 2026年09月22号
+* @param ctx DSH host 上下文
+* @param provider settings 服务（SettingsForms）
+* @param ns 目标设置命名空间
+* @param hooks 设置源绑定与变更回调
+*/
+function watchDocUpdates(ctx, provider, ns, hooks) {
+	try {
+		const bus = ctx;
+		if (typeof bus.on !== "function") return;
+		const off = bus.on("settings/document-updated", (updatedNs) => {
+			if (updatedNs !== ns) return;
+			hooks.setSource(() => readSectionValue(provider, ns));
+			hooks.onChange();
+		});
+		if (typeof bus.effect === "function" && typeof off === "function") bus.effect(() => off);
+	} catch (error) {
+		log.warn("settings/document-updated 订阅失败：" + String(error));
+	}
+}
+/**
 * 设置 section 版本自适应安装（核心策略分派）。
 * legacy：dsh-settings 仍导出 installSettingsSection（rc 线）→ 原样调用，行为与旧版一致。
 * service：该导出已移除（0.1.2-alpha 起）→ 经 ctx.inject(['settings']) 走服务方法
 *          provider.installSection(owner, ns, schema, entry, hooks)（等义封装，含
-*          base 层与 fiber 卸载回退）。回调内方法缺失再降级记录 none。
+*          base 层与 fiber 卸载回退）。
+* forms：0.1.7 起 installSection 移除，设置并入 profile 插件 Config（SettingsForms
+*          的 describe+update 在场即成立）→ 不装 section，改订阅 document-updated。
 * none：两条路由都不存在 → 仅记录并告警，调用方按配置值运行。
 * 全程不抛错、不产生未捕获 rejection。
-* @author ddj 2026年09月02号
+* @author ddj 2026年09月02号（2026年09月22号 增补 forms 策略）
 * @param ctx DSH host 上下文（inject 可选探测）
 * @param ns 设置命名空间
 * @param schema schemastery schema
@@ -499,6 +792,12 @@ async function runSettingsInstall(ctx, ns, schema, entry, hooks, loader = loadSe
 			const provider = typeof sc.get === "function" ? sc.get("settings") : sc.settings;
 			const install = provider?.installSection;
 			if (typeof install !== "function") {
+				const forms = provider;
+				if (typeof forms?.describe === "function" && typeof forms?.update === "function") {
+					recordInstall("forms", INSTALL_FORMS);
+					watchDocUpdates(ctx, forms, ns, hooks);
+					return;
+				}
 				log.warn("settings 服务无 installSection（DSH 版本 API 变化），section " + ns + " 降级为配置值");
 				recordInstall("none", INSTALL_NONE);
 				return;
@@ -529,26 +828,205 @@ function keybindingsShape(z) {
 	for (const [id, chord] of Object.entries(KEYBINDING_DEFAULTS)) shape[id] = z.string().default(chord);
 	return shape;
 }
+/**
+* 设置节 describe 项的形状校验：value 须为普通对象。
+* ns 在两代语义不同（旧=自装 section 名，0.1.7=profile entry id），同名撞车时
+* 以形状兜底防误命中非设置数据；0.1.7 下本插件 entry 的 Config 值与旧 section
+* 值同为设置键对象，两形状天然兼容。
+* @author ddj 2026年09月22号
+* @param value describe 项的 value 字段
+* @returns 是否具备设置节形状
+*/
+function isSectionShaped(value) {
+	return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+/**
+* 按 ns + 形状校验查找设置节（host 读路径统一入口）。
+* @author ddj 2026年09月22号
+* @param provider settings 服务（可空）
+* @param ns 设置命名空间
+* @returns 命中的 describe 项；未命中返回 undefined
+*/
+function sectionOf(provider, ns) {
+	const items = provider?.describe?.({ redactSecrets: true });
+	if (!items) return void 0;
+	return items.find((item) => item.ns === ns && isSectionShaped(item.value));
+}
+/** 读设置节存储值（未就绪/形状不符返回 undefined）。 */
+function readSectionValue(provider, ns) {
+	return sectionOf(provider, ns)?.value;
+}
+/**
+* 带冲突自愈的设置写入：0.1.7 SettingsConflictError（revision 拒写）时重读
+* revision 重试一次；其余错误与服务缺失一律结构化返回，绝不抛未捕获异常。
+* @author ddj 2026年09月22号
+* @param provider settings 服务（可空）
+* @param ns 设置命名空间
+* @param patch 写入字段
+* @param expectedRevision 读侧携带的 revision（缺省用 describe 最新值）
+* @returns 写入结果
+*/
+async function updateSection(provider, ns, patch, expectedRevision) {
+	if (!provider?.update) return {
+		ok: false,
+		error: "settings 服务无 update"
+	};
+	const first = expectedRevision ?? sectionOf(provider, ns)?.revision;
+	try {
+		await provider.update(ns, patch, first);
+		return { ok: true };
+	} catch (error) {
+		if (!isConflictError(error)) return {
+			ok: false,
+			error: String(error)
+		};
+	}
+	const fresh = sectionOf(provider, ns)?.revision;
+	try {
+		await provider.update(ns, patch, fresh);
+		return {
+			ok: true,
+			conflict: true
+		};
+	} catch (error) {
+		return {
+			ok: false,
+			conflict: true,
+			error: String(error)
+		};
+	}
+}
+/**
+* 构建设置 section schema（install 路径与插件 Config 声明共用，保证两代形状同源）。
+* 字段集 = fileOpenTool/keybindings/sidebarMinWidth/maxOpenEditors/integrationBaseUrl/
+* aiInline/aiProvider/aiModel/aiEffort/svnPath/tortoisePath/nativeOpenExts，全部带默认值
+* （Config 启动校验在 undefined/空配置下自动填充，rc/alpha 两代 cordis 均通过）。
+* options.volatile：DSH 0.1.7 线的 Config 导出专用——SettingsForms.describe 只下发
+* 含 volatile 字段的 entry（volatileForm 门槛），不标记则 ns 永不出现在 describe、
+* client configForms 恒 unavailable；且字段须位于固定 object 路径（keybindings 整个
+* object 标记、子键不标）。section 安装路径（legacy/service）**不标**：rc/0.1.6 的
+* register→resolve 无该门槛，标了反而让 scope.get() 返回引用污染读取。
+* 标记经 markVolatile 能力守卫：z 无 .volatile()（旧 schemastery）或调用抛错时保持
+* 原字段并记录观测态，模块加载绝不抛错（降级=维持现状，兼容性报告可见）。
+* @author ddj 2026年09月22号（2026年09月23号 增补 options.volatile 与观测）
+* @param z schemastery 命名空间（静态 import 或动态加载均可）
+* @param options volatile：是否按 0.1.7 Config 语义标记字段
+* @returns schemastery object schema
+*/
+function buildSettingsSchema(z, options) {
+	const wantVolatile = options?.volatile === true;
+	let marked = 0;
+	const withVol = (field) => {
+		if (!wantVolatile) return field;
+		const result = markVolatile(field);
+		if (result.marked) marked += 1;
+		return result.field;
+	};
+	const shape = {
+		fileOpenTool: withVol(z.string().default(FILE_OPEN_DEFAULT)),
+		keybindings: withVol(z.object(keybindingsShape(z)).default({ ...KEYBINDING_DEFAULTS })),
+		sidebarMinWidth: withVol(z.number().default(300)),
+		maxOpenEditors: withVol(z.number().default(10)),
+		integrationBaseUrl: withVol(z.string().default(INTEGRATION_BASE_DEFAULT)),
+		aiInline: withVol(z.boolean().default(AI_CONFIG_DEFAULT.enabled)),
+		aiProvider: withVol(z.string().default(AI_CONFIG_DEFAULT.provider)),
+		aiModel: withVol(z.string().default(AI_CONFIG_DEFAULT.model)),
+		aiEffort: withVol(z.string().default(AI_CONFIG_DEFAULT.effort)),
+		aiTaskProvider: withVol(z.string().default(AI_CONFIG_DEFAULT.taskProvider)),
+		aiTaskModel: withVol(z.string().default(AI_CONFIG_DEFAULT.taskModel)),
+		aiTaskEffort: withVol(z.string().default(AI_CONFIG_DEFAULT.taskEffort)),
+		svnPath: withVol(z.string().default("")),
+		tortoisePath: withVol(z.string().default(TORTOISE_DIR_DEFAULT)),
+		nativeOpenExts: withVol(z.string().default(DEFAULT_NATIVE_CSV))
+	};
+	if (wantVolatile) configVolatile = {
+		requested: true,
+		marked,
+		total: Object.keys(shape).length
+	};
+	return z.object(shape);
+}
+let configVolatile = {
+	requested: false,
+	marked: 0,
+	total: 0
+};
+/**
+* 读取 Config volatile 标记观测（0.1.7 设置页可用性的构建期判据）。
+* @author ddj 2026年09月23号
+* @returns 观测态（requested=是否按 Config 语义构建；marked/total=成功标记字段数）
+*/
+function configVolatileState() {
+	return configVolatile;
+}
+/**
+* 为已完成 default 链的 schema 字段追加 volatile 标记（能力守卫）。
+* @author ddj 2026年09月23号
+* @param field schema 字段（两代 schemastery 兼容面，可能没有 volatile 方法）
+* @returns 处理后字段与是否成功标记
+*/
+function markVolatile(field) {
+	const target = field;
+	if (!target || typeof target.volatile !== "function") return {
+		field,
+		marked: false
+	};
+	try {
+		return {
+			field: target.volatile(),
+			marked: true
+		};
+	} catch {
+		return {
+			field,
+			marked: false
+		};
+	}
+}
+/** cosmokit volatile 引用写协议符号（Symbol.for 跨拷贝一致，同 cosmokit.isVolatile 判据）。 */
+const VOLATILE_WRITE = Symbol.for("cosmokit.volatile.write");
+/**
+* 解引用 0.1.7 volatile 配置引用（普通值直传）。
+* cordis resolveConfig 会把 .volatile() 字段解析成稳定引用，直接读会得到引用对象；
+* 不解引用则配置回退值全部落入默认值分支。
+* @author ddj 2026年09月23号
+* @param value 配置字段原始值
+* @returns 引用的当前快照，或原值
+*/
+function unref(value) {
+	if (value !== null && typeof value === "object" && VOLATILE_WRITE in value) return value.get();
+	return value;
+}
+/**
+* 读插件组合配置字段并解引用（配置读取唯一入口）。
+* @author ddj 2026年09月23号
+* @param config 插件组合配置（apply 收到的 Config 值）
+* @param key 字段名
+* @returns 字段值（引用已解包；缺失为 undefined）
+*/
+function configField(config, key) {
+	return unref(config?.[key]);
+}
 function normalizeValue(value) {
 	if (typeof value !== "string" || value.trim() === "") return FILE_OPEN_DEFAULT;
 	return value.trim();
 }
 function configValue(config) {
-	return normalizeValue(config?.fileOpenTool);
+	return normalizeValue(configField(config, "fileOpenTool"));
 }
 /** 配置/设置里的深链基址（缺省/非法回退默认值）。 */
 function baseValueOf(config) {
-	const raw = config?.integrationBaseUrl;
+	const raw = configField(config, "integrationBaseUrl");
 	return typeof raw === "string" && raw.trim() ? raw.trim() : INTEGRATION_BASE_DEFAULT;
 }
 /** 配置/设置里的 svn CLI 覆盖（空 = 从 PATH 解析 'svn'）。 */
 function svnPathValueOf(config) {
-	const raw = config?.svnPath;
+	const raw = configField(config, "svnPath");
 	return typeof raw === "string" ? raw.trim() : "";
 }
 /** 配置/设置里的 TortoiseSVN 目录（空 = 默认安装目录）。 */
 function tortoiseDirValueOf(config) {
-	const raw = config?.tortoisePath;
+	const raw = configField(config, "tortoisePath");
 	return typeof raw === "string" && raw.trim() ? raw.trim() : TORTOISE_DIR_DEFAULT;
 }
 /**
@@ -567,23 +1045,11 @@ async function installOpenSettingsSection(ctx, ns, entry, hooks, loader = loadSe
 		deps = await loader();
 	} catch {}
 	if (!deps) return false;
-	const strategy = await runSettingsInstall(ctx, ns, deps.z.object({
-		fileOpenTool: deps.z.string().default(FILE_OPEN_DEFAULT),
-		keybindings: deps.z.object(keybindingsShape(deps.z)).default({ ...KEYBINDING_DEFAULTS }),
-		sidebarMinWidth: deps.z.number().default(300),
-		maxOpenEditors: deps.z.number().default(10),
-		integrationBaseUrl: deps.z.string().default(INTEGRATION_BASE_DEFAULT),
-		aiInline: deps.z.boolean().default(AI_CONFIG_DEFAULT.enabled),
-		aiProvider: deps.z.string().default(AI_CONFIG_DEFAULT.provider),
-		aiModel: deps.z.string().default(AI_CONFIG_DEFAULT.model),
-		aiEffort: deps.z.string().default(AI_CONFIG_DEFAULT.effort),
-		svnPath: deps.z.string().default(""),
-		tortoisePath: deps.z.string().default(TORTOISE_DIR_DEFAULT)
-	}), entry, {
+	const strategy = await runSettingsInstall(ctx, ns, buildSettingsSchema(deps.z), entry, {
 		setSource: (source) => hooks.setSource(source),
 		onChange: hooks.onChange
 	}, loader);
-	return strategy === "legacy" || strategy === "service";
+	return strategy === "legacy" || strategy === "service" || strategy === "forms";
 }
 /** AI 配置脏值读取（settings 未就绪时回退默认）。 */
 function aiValueOf(stored) {
@@ -592,7 +1058,10 @@ function aiValueOf(stored) {
 		enabled: raw.aiInline === true,
 		provider: typeof raw.aiProvider === "string" ? raw.aiProvider : AI_CONFIG_DEFAULT.provider,
 		model: typeof raw.aiModel === "string" ? raw.aiModel : AI_CONFIG_DEFAULT.model,
-		effort: typeof raw.aiEffort === "string" ? raw.aiEffort : AI_CONFIG_DEFAULT.effort
+		effort: typeof raw.aiEffort === "string" ? raw.aiEffort : AI_CONFIG_DEFAULT.effort,
+		taskProvider: typeof raw.aiTaskProvider === "string" ? raw.aiTaskProvider : AI_CONFIG_DEFAULT.taskProvider,
+		taskModel: typeof raw.aiTaskModel === "string" ? raw.aiTaskModel : AI_CONFIG_DEFAULT.taskModel,
+		taskEffort: typeof raw.aiTaskEffort === "string" ? raw.aiTaskEffort : AI_CONFIG_DEFAULT.taskEffort
 	};
 }
 /**
@@ -612,13 +1081,13 @@ function setupOpenSettings(ctx, config, onChange) {
 		onChange(current);
 	};
 	const syncRevision = () => {
-		revision = (provider?.describe?.({ redactSecrets: true })?.find((item) => item.ns === FILE_OPEN_SETTINGS_NS))?.revision;
+		revision = sectionOf(provider, FILE_OPEN_SETTINGS_NS)?.revision;
 	};
 	const settingsChange = () => syncRevision();
 	/** AI 配置当前值（settings 未就绪回退默认）。 */
 	let aiCurrent = { ...AI_CONFIG_DEFAULT };
 	const aiSync = () => {
-		const stored = (provider?.describe?.({ redactSecrets: true })?.find((item) => item.ns === FILE_OPEN_SETTINGS_NS))?.value;
+		const stored = readSectionValue(provider, FILE_OPEN_SETTINGS_NS);
 		aiCurrent = stored !== void 0 ? aiValueOf(stored) : aiCurrent;
 	};
 	/** SVN 路径当前值（settings 未就绪回退配置值）。 */
@@ -634,7 +1103,7 @@ function setupOpenSettings(ctx, config, onChange) {
 	};
 	/** 读取 settings 存储值（describe 未就绪返回 undefined）。 */
 	const storedValue = () => {
-		return provider?.describe?.({ redactSecrets: true })?.find((item) => item.ns === FILE_OPEN_SETTINGS_NS)?.value;
+		return readSectionValue(provider, FILE_OPEN_SETTINGS_NS);
 	};
 	installOpenSettingsSection(ctx, FILE_OPEN_SETTINGS_NS, {
 		fileOpenTool: current,
@@ -652,8 +1121,11 @@ function setupOpenSettings(ctx, config, onChange) {
 	});
 	ctx.inject?.(["settings"], (settingsCtx) => {
 		provider = settingsCtx.get("settings");
-		aiSync();
-		svnSync(storedValue());
+		const stored = storedValue();
+		const section = stored;
+		if (section?.fileOpenTool !== void 0) notify(section.fileOpenTool);
+		aiCurrent = stored !== void 0 ? aiValueOf(stored) : aiCurrent;
+		svnSync(stored);
 		syncRevision();
 	});
 	return {
@@ -665,25 +1137,15 @@ function setupOpenSettings(ctx, config, onChange) {
 		},
 		update: async (value, expectedRevision) => {
 			const next = normalizeValue(value);
-			if (!provider?.update) {
-				notify(next);
-				return;
-			}
-			await provider.update(FILE_OPEN_SETTINGS_NS, { fileOpenTool: next }, expectedRevision);
-			const stored = (provider.describe?.({ redactSecrets: true })?.find((item) => item.ns === FILE_OPEN_SETTINGS_NS))?.value;
+			const result = await updateSection(provider, FILE_OPEN_SETTINGS_NS, { fileOpenTool: next }, expectedRevision);
+			if (!result.ok) log.warn("fileOpenTool 设置写入失败：" + (result.error ?? "未知原因"));
+			const stored = readSectionValue(provider, FILE_OPEN_SETTINGS_NS);
 			notify(stored?.fileOpenTool ?? next);
 			syncRevision();
 		},
 		ai: () => aiCurrent,
 		svn: () => svnCurrent,
 		aiUpdate: async (patch, expectedRevision) => {
-			if (!provider?.update) {
-				if (patch.enabled !== void 0) aiCurrent.enabled = patch.enabled;
-				if (patch.provider !== void 0) aiCurrent.provider = patch.provider;
-				if (patch.model !== void 0) aiCurrent.model = patch.model;
-				if (patch.effort !== void 0) aiCurrent.effort = patch.effort;
-				return aiCurrent;
-			}
 			const stored = { ...aiCurrent };
 			const body = {};
 			if (patch.enabled !== void 0) {
@@ -702,7 +1164,22 @@ function setupOpenSettings(ctx, config, onChange) {
 				stored.effort = patch.effort;
 				body.aiEffort = patch.effort;
 			}
-			await provider.update(FILE_OPEN_SETTINGS_NS, body, expectedRevision);
+			if (patch.taskProvider !== void 0) {
+				stored.taskProvider = patch.taskProvider;
+				body.aiTaskProvider = patch.taskProvider;
+			}
+			if (patch.taskModel !== void 0) {
+				stored.taskModel = patch.taskModel;
+				body.aiTaskModel = patch.taskModel;
+			}
+			if (patch.taskEffort !== void 0) {
+				stored.taskEffort = patch.taskEffort;
+				body.aiTaskEffort = patch.taskEffort;
+			}
+			if (!(await updateSection(provider, "dsh-vscode-mode", body, expectedRevision)).ok) {
+				aiCurrent = stored;
+				return aiCurrent;
+			}
 			aiSync();
 			return aiCurrent;
 		}
@@ -919,13 +1396,14 @@ function inDshRange(version, range) {
 /**
 * 版本线标签：报告与文档展示版本归属；不可解析返回 '未知'。
 * 逐线自新到旧匹配，先命中先返回（区间无上界，故顺序即优先级）。
-* @author ddj 2026年09月02号 / 2026年09月18号
+* @author ddj 2026年09月02号 / 2026年09月18号 / 2026年09月22号
 * @param input 版本串（如 '0.1.6-alpha.2'）
 * @returns 版本线标签
 */
 function familyLabel(input) {
 	const version = parseDshVersion(input);
 	if (!version) return "未知";
+	if (inDshRange(version, { from: "0.1.7-alpha.1" })) return "0.1.7-alpha.1 及更新（设置=profile Config + configForms 客户端面 + 会话 V4）";
 	if (inDshRange(version, { from: "0.1.6-alpha.2" })) return "0.1.6-alpha.2 及更新（会话多实例共存 + 回合改动卡片 + Office 侧栏预览 + 侧栏浏览器）";
 	if (inDshRange(version, { from: "0.1.6-alpha.1" })) return "0.1.6-alpha 及更新（MCP SDK v2 + Web 侧边栏终端 + 文件链接默认侧栏预览）";
 	if (inDshRange(version, { from: "0.1.5-alpha.1" })) return "0.1.5-alpha 及更新（官方右侧 Sidebar 编辑区 + sidebar.panellist）";
@@ -1864,8 +2342,10 @@ function detectGuards(ctx) {
 	}];
 }
 /** 已实测覆盖的最高 DSH 版本（适配矩阵上界，超过则提示，见 buildReport）。 */
-const TESTED_DSH_MAX = "0.1.6-alpha.2";
-/** 版本适配机制状态行：DSH 版本探测 + 设置 section 安装策略。 */
+const TESTED_DSH_MAX = "0.1.7-alpha.2";
+/** Config volatile 标记起效的版本线（此前设置走 section 安装，与 volatile 无关）。 */
+const CONFIG_VOLATILE_MIN = "0.1.7-alpha.1";
+/** 版本适配机制状态行：DSH 版本探测 + 设置 section 安装策略 + Config volatile 标记。 */
 function versionAdapters(dshVersion) {
 	const adapters = [];
 	const parsed = parseDshVersion(dshVersion);
@@ -1887,14 +2367,23 @@ function versionAdapters(dshVersion) {
 	const strategy = settingsInstallStrategy();
 	adapters.push({
 		name: "设置 section 安装（版本适配）",
-		active: strategy === "legacy" || strategy === "service",
+		active: strategy === "legacy" || strategy === "service" || strategy === "forms",
 		note: settingsInstallNote()
 	});
+	const volatileState = configVolatileState();
+	if (volatileState.requested) {
+		const volatileOk = volatileState.total > 0 && volatileState.marked === volatileState.total;
+		adapters.push({
+			name: "Config volatile 字段（0.1.7 设置页）",
+			active: volatileOk,
+			note: volatileOk ? volatileState.marked + "/" + volatileState.total + " 已标记（SettingsForms 可下发本插件 ns）" : volatileState.marked + "/" + volatileState.total + " 已标记：schemastery 依赖过旧无 .volatile()，0.1.7 设置页不可用"
+		});
+	}
 	return adapters;
 }
 /**
 * 构建完整兼容性报告（RPC 与启动日志共用）。
-* @author ddj 2026年08月24号 / 2026年09月02号
+* @author ddj 2026年08月24号 / 2026年09月02号 / 2026年09月23号
 * @param ctx DSH host 上下文
 * @param options 测试注入：depsAvailable 跳过动态导入、version 固定插件版本、dshVersion 固定 DSH 版本
 * @returns 兼容性报告
@@ -1910,7 +2399,10 @@ async function buildReport(ctx, options) {
 	if (settingsInstallStrategy() === "none") warnings.push("设置 section 安装不可用：" + settingsInstallNote());
 	const parsed = parseDshVersion(dshVersion);
 	const testedMax = parseDshVersion(TESTED_DSH_MAX);
-	if (parsed && testedMax && compareDshVersions(parsed, testedMax) > 0) warnings.push("DSH " + dshVersion + " 高于已实测版本（0.1.6-alpha.2）：设置 API 按能力探测运行，异常时请回报适配矩阵");
+	if (parsed && testedMax && compareDshVersions(parsed, testedMax) > 0) warnings.push("DSH " + dshVersion + " 高于已实测版本（0.1.7-alpha.2）：设置 API 按能力探测运行，异常时请回报适配矩阵");
+	const volatileState = configVolatileState();
+	const volatileMin = parseDshVersion(CONFIG_VOLATILE_MIN);
+	if (volatileState.requested && volatileState.marked < volatileState.total && parsed && volatileMin && compareDshVersions(parsed, volatileMin) >= 0) warnings.push("插件 Config volatile 标记不完整（" + volatileState.marked + "/" + volatileState.total + "）：@deepseek-ai/schemastery 依赖过旧，0.1.7 设置页不可用（重装插件依赖后重启 DSH）");
 	for (const guard of guards) if (!guard.active && guard.note) warnings.push(guard.note);
 	return {
 		pluginVersion: options?.version ?? pluginVersionOf(),
@@ -2000,6 +2492,16 @@ function registerRoutes(ctx, config, handleRpc, onWarning) {
 					input = {};
 				}
 				const result = await handleRpc(typeof input.method === "string" ? input.method : "", input.args ?? {});
+				const bin = result?.binary;
+				if (result && result.ok === true && bin?.bytes instanceof Uint8Array) {
+					res.statusCode = 200;
+					res.setHeader("content-type", "application/octet-stream");
+					res.setHeader("x-edrv-mime", String(bin.mime ?? ""));
+					res.setHeader("x-edrv-version", String(bin.version ?? ""));
+					res.setHeader("x-edrv-size", String(bin.size ?? bin.bytes.byteLength));
+					res.end(Buffer.from(bin.bytes));
+					return;
+				}
 				res.statusCode = 200;
 				res.setHeader("content-type", "application/json");
 				res.end(JSON.stringify(result));
@@ -2302,7 +2804,7 @@ function normalizeRecord(raw) {
 			...Number.isInteger(item.beforeEnd) ? { beforeEnd: item.beforeEnd } : {}
 		};
 	}) : [];
-	const toolName = r.toolName === "write" ? "write" : "edit";
+	const toolName = r.toolName === "write" || r.toolName === "remote_ssh_write" ? r.toolName : "edit";
 	const rawDecisions = r.decisions && typeof r.decisions === "object" ? r.decisions : {};
 	const call = rawDecisions.call === "accepted" || rawDecisions.call === "rejected" ? rawDecisions.call : "pending";
 	const rawPerHunk = Array.isArray(rawDecisions.perHunk) ? rawDecisions.perHunk : [];
@@ -2761,6 +3263,149 @@ function bucketOf(registry, ctx, cwd) {
 	});
 }
 //#endregion
+//#region src/remoteWorkspace.ts
+/**
+* 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号
+*/
+/** dsh-remote-ssh 工作区标记文件名。 */
+const MARKER = ".remote-ssh.json";
+/** 向上探测的最大层数（含 cwd 自身；与上游 findMirrorRoot 的 8 层有界一致）。 */
+const MAX_DEPTH = 8;
+/** 探测结果 TTL（edrv.list 为 5s 轮询，避免每轮都做文件 IO）。 */
+const TTL_MS = 6e4;
+/** cwd → { at, ws } 探测缓存（含阴性结果）。 */
+const cache$2 = /* @__PURE__ */ new Map();
+/**
+* 标记内容 → 远程工作区（host/user/remotePath 缺任一字段判非法，与上游一致）。
+* @author ddj 2026年09月23号
+* @param root 标记所在目录
+* @param raw 标记文件文本
+* @returns 合法返回 RemoteWs；非法返回 null
+*/
+function markerWsOf(root, raw) {
+	try {
+		const info = JSON.parse(raw);
+		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 = {
+			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) {
+	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 {}
+		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
+*/
+function findRemoteWs(cwd) {
+	if (!cwd) return null;
+	const now = Date.now();
+	const hit = cache$2.get(cwd);
+	if (hit && now - hit.at < TTL_MS) return hit.ws;
+	const ws = walkRemoteWs(cwd);
+	cache$2.set(cwd, {
+		at: now,
+		ws
+	});
+	return ws;
+}
+/**
+* 前缀剥离：path 必须严格位于 root 之下；等于 root 或不匹配返回 null。
+* @author ddj 2026年09月23号
+* @param path 待剥离路径（posix 形态）
+* @param root 前缀（posix 形态、无尾斜杠）
+* @returns 相对段；不匹配返回 null
+*/
+function prefixRel(path, root) {
+	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, ws) {
+	const path = argPath.replace(/\\/g, "/").replace(/^\.\//, "");
+	if (!path) return null;
+	const root = ws.remotePath.replace(/\\/g, "/").replace(/\/+$/, "");
+	if (!root) return null;
+	let rel;
+	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
+*/
+function mirrorTargetOf(argPath, ws) {
+	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）
+*/
+function remoteDisplayOf(mirrorAbs, ws) {
+	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;
+	return ws.remotePath.replace(/\/+$/, "") + "/" + rel;
+}
+//#endregion
 //#region src/tree.ts
 /** 目录在文件前、名称按小写字母序的比较器（对齐 VSCode 资源管理器习惯）。 */
 function entryOrder(a, b) {
@@ -3215,6 +3860,16 @@ async function listDirCached(ctx, cwd, rel, force) {
 }
 //#endregion
 //#region src/capture.ts
+/**
+* dsh-vscode-mode host — 捕获层：监听 tools/result，把 edit/write/remote_ssh_write
+* 差异落成审查记录。
+* 迁移自原 src/index.ts 的 tools/result 处理；2026-09-23（issue #7）增补
+* remote_ssh_write：远端工作区会话里 agent 直写远端的全量覆写——before 取本地
+* 镜像快照、after 取参数 content，捕获后把同一内容**写穿**回镜像（node:fs 直写，
+* 刻意不走 ctx.fs，避开 dsh-remote-ssh 写桥的重复推送与补丁次序问题），使镜像 =
+* 远端最新内容，读/stale/决策口径与远端一致。
+* 作者 ddj 2026-08-20（2026-09-23 扩展 remote_ssh_write 捕获）
+*/
 /** 校验并提取工具 result meta 中的文件 hunk。 */
 function validHunks(raw) {
 	if (!Array.isArray(raw)) return [];
@@ -3252,8 +3907,190 @@ function fallbackHunks(toolName, args, before, after, create) {
 	return [];
 }
 /**
-* 捕获一次工具执行结果（tools/result）：edit/write 成功时构造记录、
-* 递增文件批次、融合归档被后续修改取代的旧差异、落盘。
+* 是否为纳入审查的编辑类工具（本地 edit/write + 远端 remote_ssh_write）。
+* @author ddj 2026年09月23号
+* @param name 工具名
+* @returns 纳入审查返回 true
+*/
+function isCapturable(name) {
+	return name === "edit" || name === "write" || name === "remote_ssh_write";
+}
+/**
+* 本地 edit/write 执行结果 → 审查记录（原 captureToolResult 主体语义不变）。
+* @author ddj 2026年09月23号
+* @param exec 工具执行描述
+* @param args 工具参数
+* @param result 工具执行结果
+* @returns 记录；hunk 为空或缺 callId 返回 null
+*/
+function buildLocalRecord(exec, args, result) {
+	const value = result.value;
+	const path = value && typeof value.path === "string" ? value.path : args.file_path;
+	if (typeof path !== "string" || !path) return null;
+	const before = value && typeof value.before === "string" ? value.before : null;
+	const after = value && typeof value.after === "string" ? value.after : typeof args.content === "string" ? args.content : null;
+	const create = exec.name === "write" && !!value && value.before === null;
+	const callHunk = exec.name === "edit" && typeof args.old_string === "string" && typeof args.new_string === "string" ? {
+		oldText: args.old_string,
+		newText: args.new_string
+	} : null;
+	const metaHunks = validHunks(result.meta?.diffs);
+	const hunks = annotateHunks(metaHunks.length ? metaHunks : fallbackHunks(String(exec.name), args, before, after, create), before, after);
+	if (!hunks.length || typeof exec.callId !== "string") return null;
+	return {
+		callId: exec.callId,
+		toolName: exec.name === "write" ? "write" : "edit",
+		path,
+		before,
+		after,
+		baseFingerprint: fingerprint(before),
+		afterFingerprint: fingerprint(after),
+		legacy: false,
+		conflict: false,
+		create,
+		callHunk,
+		hunks,
+		decisions: {
+			call: "pending",
+			perHunk: hunks.map(() => "pending")
+		},
+		note: create ? "新建文件：全部拒绝将删除该文件" : before === null ? "未捕获修改前内容（大文件）" : null,
+		superseded: false,
+		archived: false,
+		batch: 0,
+		at: (/* @__PURE__ */ new Date()).toISOString()
+	};
+}
+/**
+* 读取镜像文件当前内容（node:fs 直读；缺失 → missing，非文件/过大/读失败 → unreadable）。
+* @author ddj 2026年09月23号
+* @param absPath 镜像内绝对路径
+* @returns 读取状态
+*/
+async function readMirrorState(absPath) {
+	let info;
+	try {
+		info = await stat(absPath);
+	} catch {
+		return { kind: "missing" };
+	}
+	if (!info.isFile()) return { kind: "unreadable" };
+	if ((info.size ?? 0) > 8388608) return { kind: "unreadable" };
+	try {
+		return {
+			kind: "content",
+			content: await readFile(absPath, "utf8")
+		};
+	} catch {
+		return { kind: "unreadable" };
+	}
+}
+/**
+* 把远端写入内容写穿回本地镜像（node:fs 直写 + mkdir -p 父目录）。
+* 刻意不用 ctx.fs：避免触发 dsh-remote-ssh 写桥把相同内容再推回远端。
+* @author ddj 2026年09月23号
+* @param absPath 镜像内绝对路径
+* @param content 远端写入后的完整内容
+* @returns 成功返回 null；失败返回错误文案（不抛）
+*/
+async function syncMirrorFile(absPath, content) {
+	try {
+		await mkdir(dirname(absPath), { recursive: true });
+		await writeFile(absPath, content, "utf8");
+		return null;
+	} catch (error) {
+		return String(error);
+	}
+}
+/**
+* 远端记录的 note 组装（新建/未捕获 before/镜像外路径/写穿失败可叠加）。
+* @author ddj 2026年09月23号
+* @param create 镜像中目标不存在（远端新建）
+* @param before 镜像快照内容（null = 未捕获）
+* @param mirrorAbs 可映射的镜像绝对路径（null = 路径不在镜像内）
+* @param syncErr 写穿失败原因（null = 成功）
+* @returns note 文本；无需提示返回 null
+*/
+function remoteNoteOf(create, before, mirrorAbs, syncErr) {
+	const notes = [];
+	if (!mirrorAbs) notes.push("远端路径不在工作区镜像内（仅记录，无法本地审查）");
+	else if (create) notes.push("新建文件：全部拒绝将删除该文件");
+	else if (before === null) notes.push("未捕获修改前内容（大文件）");
+	if (syncErr) notes.push("远端内容写回镜像失败（记录仍已保存）：" + syncErr);
+	return notes.length ? notes.join("；") : null;
+}
+/**
+* remote_ssh_write 执行 → 审查记录（含镜像写穿，issue #7）。
+* 非远程工作区、参数不合法或内容无变化返回 null（不产生记录）。
+* @author ddj 2026年09月23号
+* @param cwd 会话工作区（远程会话即镜像根）
+* @param exec 工具执行描述
+* @param args 工具参数（path 相对远端工作区目录，或绝对/`~` 形态）
+* @returns 记录；不满足捕获条件返回 null
+*/
+async function buildRemoteRecord(cwd, exec, args) {
+	const ws = findRemoteWs(cwd);
+	if (!ws) return null;
+	const argPath = typeof args.path === "string" ? args.path : "";
+	const after = typeof args.content === "string" ? args.content : null;
+	if (!argPath || after === null || typeof exec.callId !== "string") return null;
+	const mirrorAbs = mirrorTargetOf(argPath, ws);
+	const state = mirrorAbs ? await readMirrorState(mirrorAbs) : { kind: "unreadable" };
+	const before = state.kind === "content" ? state.content : null;
+	const create = state.kind === "missing";
+	if (before !== null && before === after) return null;
+	const syncErr = mirrorAbs ? await syncMirrorFile(mirrorAbs, after) : null;
+	const hunks = annotateHunks([{
+		oldText: before,
+		newText: after
+	}], before, after);
+	return {
+		callId: exec.callId,
+		toolName: "remote_ssh_write",
+		path: mirrorAbs ?? argPath,
+		before,
+		after,
+		baseFingerprint: fingerprint(before),
+		afterFingerprint: fingerprint(after),
+		legacy: false,
+		conflict: false,
+		create,
+		callHunk: null,
+		hunks,
+		decisions: {
+			call: "pending",
+			perHunk: hunks.map(() => "pending")
+		},
+		note: remoteNoteOf(create, before, mirrorAbs, syncErr),
+		superseded: false,
+		archived: false,
+		batch: 0,
+		at: (/* @__PURE__ */ new Date()).toISOString()
+	};
+}
+/**
+* 记录入桶：按工作区分桶（缺失先加载）、按文件递增批次、裁剪、落盘。
+* @author ddj 2026年09月23号
+* @param ctx DSH 上下文
+* @param registry 工作区记录桶注册表
+* @param session 会话
+* @param cwd 会话工作区
+* @param record 待入桶记录
+*/
+async function persistRecord(ctx, registry, session, cwd, record) {
+	let bucket = registry.get(cwd);
+	if (!bucket) {
+		bucket = await loadBucket(ctx, cwd);
+		registry.set(cwd, bucket);
+	}
+	record.batch = fileMaxBatch(bucket, record.path) + 1;
+	bucket.set(record.callId, record);
+	prune(bucket);
+	await saveBucket(ctx, cwd, bucket, session);
+}
+/**
+* 捕获一次工具执行结果（tools/result）：edit/write/remote_ssh_write 成功时
+* 构造记录、递增文件批次、落盘；远端写入额外做镜像写穿（issue #7）。
 * @author ddj 2026年08月20号
 * @param ctx DSH 上下文
 * @param registry 工作区记录桶注册表
@@ -3262,58 +4099,17 @@ function fallbackHunks(toolName, args, before, after, create) {
 */
 async function captureToolResult(ctx, registry, exec, result) {
 	const session = exec?.agent?.session;
-	if (!session || exec?.name !== "edit" && exec?.name !== "write") return;
-	if (result?.isError || !result?.value) return;
+	if (!session || !isCapturable(exec?.name)) return;
+	if (result?.isError) return;
+	if (exec.name !== "remote_ssh_write" && !result?.value) return;
 	try {
 		const cwd = cwdOf(session);
 		if (!cwd) return;
-		const value = result.value;
 		const args = exec.arguments || {};
-		const path = typeof value.path === "string" ? value.path : args.file_path;
-		if (typeof path !== "string" || !path) return;
-		const before = typeof value.before === "string" ? value.before : null;
-		const after = typeof value.after === "string" ? value.after : typeof args.content === "string" ? args.content : null;
-		const create = exec.name === "write" && value.before === null;
-		const callHunk = exec.name === "edit" && typeof args.old_string === "string" && typeof args.new_string === "string" ? {
-			oldText: args.old_string,
-			newText: args.new_string
-		} : null;
-		const metaHunks = validHunks(result.meta?.diffs);
-		const hunks = annotateHunks(metaHunks.length ? metaHunks : fallbackHunks(exec.name, args, before, after, create), before, after);
-		if (!hunks.length || typeof exec.callId !== "string") return;
-		const record = {
-			callId: exec.callId,
-			toolName: exec.name,
-			path,
-			before,
-			after,
-			baseFingerprint: fingerprint(before),
-			afterFingerprint: fingerprint(after),
-			legacy: false,
-			conflict: false,
-			create,
-			callHunk,
-			hunks,
-			decisions: {
-				call: "pending",
-				perHunk: hunks.map(() => "pending")
-			},
-			note: create ? "新建文件：全部拒绝将删除该文件" : before === null ? "未捕获修改前内容（大文件）" : null,
-			superseded: false,
-			archived: false,
-			batch: 0,
-			at: (/* @__PURE__ */ new Date()).toISOString()
-		};
-		let bucket = registry.get(cwd);
-		if (!bucket) {
-			bucket = await loadBucket(ctx, cwd);
-			registry.set(cwd, bucket);
-		}
-		record.batch = fileMaxBatch(bucket, path) + 1;
-		bucket.set(exec.callId, record);
-		prune(bucket);
-		await saveBucket(ctx, cwd, bucket, session);
-		invalidateIndex(ctx, cwd, path);
+		const record = exec.name === "remote_ssh_write" ? await buildRemoteRecord(cwd, exec, args) : buildLocalRecord(exec, args, result);
+		if (!record) return;
+		await persistRecord(ctx, registry, session, cwd, record);
+		invalidateIndex(ctx, cwd, record.path);
 	} catch (error) {
 		log.error("capture failed: " + String(error));
 	}
@@ -7104,28 +7900,86 @@ async function scanSessionInventory(home = dshHome(), archive = sessionsArchiveR
 		}
 	};
 }
-/** 标记活跃会话（live id 与目录段名双向匹配，兼容编码差异）。 */
-function markActiveSessions(sessions, activeIds) {
-	const raw = new Set(activeIds);
+/** id 双向匹配器：原始 id 与编码段名任一命中（兼容编码差异）。 */
+function idMatcher(ids) {
+	const raw = new Set(ids);
 	const encoded = /* @__PURE__ */ new Set();
 	for (const id of raw) encoded.add(sessionIdSegment(id));
-	for (const s of sessions) if (raw.has(s.sessionId) || encoded.has(s.sessionId)) s.active = true;
+	return (id) => raw.has(id) || encoded.has(id);
+}
+/** 标记活跃会话（live id 与目录段名双向匹配，兼容编码差异）。 */
+function markActiveSessions(sessions, activeIds) {
+	const match = idMatcher(activeIds);
+	for (const s of sessions) if (match(s.sessionId)) s.active = true;
+}
+/** 空标志集合（服务/字段缺失的统一降级返回值）。 */
+function emptyFlagIds() {
+	return {
+		archived: /* @__PURE__ */ new Set(),
+		pinned: /* @__PURE__ */ new Set()
+	};
+}
+/** 任意值 → id 字符串集合（非数组或非字符串元素一律丢弃）。 */
+function toIdSet(ids) {
+	if (!Array.isArray(ids)) return /* @__PURE__ */ new Set();
+	return new Set(ids.filter((id) => typeof id === "string"));
 }
 /**
-* 移出规划（纯函数）：从盘点中按「显式集合」或「规则（minBytes / olderThanDays）」
-* 圈选可移出会话。活跃会话一律排除；无显式集合且无规则时不选（防误移）。
-* @author ddj 2026年09月02号
-* @param inventory 盘点结果
-* @param criteria 圈选条件
-* @returns 待移出清单与释放字节
+* 一次读取 workspaceRegistry 的官方归档/置顶 id 集合（摊到盘点各行使用）。
+* 服务缺失、字段缺失或非数组（DSH 0.1.6 及更旧没有）一律视为空集，绝不抛错。
+* @author ddj 2026年09月22号
+* @param ctx DSH 上下文
+* @returns archived/pinned 两组 id 集合（缺失即空集）
 */
-function planMoveOut(inventory, criteria) {
-	const items = [];
-	const explicit = Array.isArray(criteria.sessionIds) && criteria.sessionIds.length > 0;
-	const cutoff = criteria.olderThanDays ? Date.now() - criteria.olderThanDays * 24 * 60 * 60 * 1e3 : 0;
-	for (const s of inventory.sessions) {
-		if (s.active) continue;
-		if (criteria.workspaceKey && s.workspaceKey !== criteria.workspaceKey) continue;
+function registryFlags(ctx) {
+	try {
+		const registry = ctx.get("workspaceRegistry");
+		if (!registry) return emptyFlagIds();
+		return {
+			archived: toIdSet(registry.archivedSessionIds),
+			pinned: toIdSet(registry.pinnedSessionIds)
+		};
+	} catch (error) {
+		log.debug("registryFlags 跳过（服务缺失或读取失败）：" + String(error));
+		return emptyFlagIds();
+	}
+}
+/**
+* 给盘点行附官方归档/置顶标志（best-effort：仅命中附 true，缺失/未命中不附字段），
+* 让 PerfSettings 会话行能看到官方侧栏的归档/置顶状态。id 匹配复用 markActiveSessions
+* 的双向（原始 id / 编码段名）口径；服务/字段缺失不附字段、绝不抛错（旧 host 兼容降级）。
+* @author ddj 2026年09月22号
+* @param sessions 盘点会话行（就地附加 archived/pinned）
+* @param ctx DSH 上下文
+*/
+function markOfficialFlags(sessions, ctx) {
+	try {
+		const flags = registryFlags(ctx);
+		const archived = idMatcher(flags.archived);
+		const pinned = idMatcher(flags.pinned);
+		for (const s of sessions) {
+			if (archived(s.sessionId)) s.archived = true;
+			if (pinned(s.sessionId)) s.pinned = true;
+		}
+	} catch (error) {
+		log.debug("markOfficialFlags 跳过（读取失败，保持无标志）：" + String(error));
+	}
+}
+/**
+* 移出规划（纯函数）：从盘点中按「显式集合」或「规则（minBytes / olderThanDays）」
+* 圈选可移出会话。活跃会话一律排除；无显式集合且无规则时不选（防误移）。
+* @author ddj 2026年09月02号
+* @param inventory 盘点结果
+* @param criteria 圈选条件
+* @returns 待移出清单与释放字节
+*/
+function planMoveOut(inventory, criteria) {
+	const items = [];
+	const explicit = Array.isArray(criteria.sessionIds) && criteria.sessionIds.length > 0;
+	const cutoff = criteria.olderThanDays ? Date.now() - criteria.olderThanDays * 24 * 60 * 60 * 1e3 : 0;
+	for (const s of inventory.sessions) {
+		if (s.active) continue;
+		if (criteria.workspaceKey && s.workspaceKey !== criteria.workspaceKey) continue;
 		if (explicit) {
 			if (!criteria.sessionIds.includes(s.sessionId)) continue;
 		} else {
@@ -7273,6 +8127,27 @@ async function restoreSession(home, archive, workspaceKey, sessionId) {
 		};
 	}
 }
+/**
+* 恢复后对齐官方归档标志（best-effort）：官方 archive 是 workspaceRegistry 的
+* archivedSessionIds 持久标志（只藏 UI/拦模型步骤，不搬目录；dsh-workspace 源码注明
+* unarchiveSession 对未归档与未知 id 均为无写入 no-op、对失踪会话也容忍）。
+* 插件把目录搬回后若该会话曾被官方归档，官方侧栏会继续隐藏它、0.1.7 的
+* archived-session-gate 会继续拦它的模型步骤——这里探测 host 的 workspaceRegistry
+* 服务做一次幂等清除；服务缺失、id 编码差异未命中或调用抛错一律静默跳过
+* （保持现状，不加猜的行为）。有效期：仅恢复成功后触发一次，不轮询不重试。
+* @author ddj 2026年09月22号
+* @param ctx DSH 上下文
+* @param sessionId 恢复的会话 id（目录段名与原始 id 同形时可命中官方标志）
+*/
+async function unarchiveOfficial(ctx, sessionId) {
+	try {
+		const registry = ctx.get("workspaceRegistry");
+		if (!registry || typeof registry.unarchiveSession !== "function") return;
+		await registry.unarchiveSession(sessionId);
+	} catch (error) {
+		log.debug("unarchiveOfficial 跳过（服务缺失或调用失败，保持现状）：" + String(error));
+	}
+}
 /** 清除归档区早于 N 天的会话（破坏性，仅限归档区）。 */
 async function purgeArchive(archive, olderThanDays) {
 	const cutoff = Date.now() - olderThanDays * 24 * 60 * 60 * 1e3;
@@ -7465,8 +8340,8 @@ function patchInsertPerfConfig(text) {
 const staleCheckedAt = /* @__PURE__ */ new Map();
 /** stale 自动清理最小间隔。 */
 const STALE_CHECK_MIN_MS = 1e4;
-/** 记录 → 客户端视图（不含 before 全文，仅长度）。 */
-function recView(record) {
+/** 记录 → 客户端视图（不含 before 全文，仅长度）；远程工作区附远端展示路径（issue #7）。 */
+function recView(record, ws = null) {
 	return {
 		callId: record.callId,
 		toolName: record.toolName,
@@ -7483,7 +8358,8 @@ function recView(record) {
 		afterFingerprint: record.afterFingerprint ?? null,
 		conflict: record.conflict === true,
 		legacy: record.legacy === true,
-		at: record.at
+		at: record.at,
+		...ws ? { displayPath: remoteDisplayOf(record.path, ws) ?? void 0 } : {}
 	};
 }
 /** 会话/工作区公共前置：返回 {session,cwd} 或错误文案。 */
@@ -7508,6 +8384,52 @@ function snippetTargetOf(path) {
 	return isSnippetFilePath(path) ? path.replace(/\\/g, "/") : null;
 }
 /**
+* 二进制/文本读取共用前置（edrv.read 与 edrv.readBinary）：解析路径 + debugRecord +
+* stat + 文件类型校验 + 32MB 二进制上限，保证两条读通道的错误口径完全一致。
+* @author ddj 2026年09月22号
+* @param ctx DSH 上下文
+* @param sc requireSession 成功结果（session + cwd）
+* @param path 客户端请求路径
+* @returns 成功返回解析目标与 stat；失败返回错误文案（文件不存在时附 resolvedPath）
+*/
+async function readTargetOf(ctx, sc, path) {
+	const fs = ctx.get("fs");
+	if (!fs) return { err: "缺少 fs" };
+	try {
+		const target = await resolveTarget(ctx, sc.session, path);
+		debugRecord(ctx, sc.cwd, "[DEBUG path.resolve] input=" + String(path ?? "") + " resolved=" + fs.processPath(target), "debug");
+		const info = await fs.stat(target);
+		if (!info || info.type !== "file") return {
+			err: "文件不存在",
+			resolvedPath: fs.processPath(target)
+		};
+		if ((info.size ?? 0) > 33554432) return { err: "文件过大（>32MB），不支持整文件预览" };
+		return {
+			target,
+			fs,
+			info
+		};
+	} catch (error) {
+		return { err: "读取失败：" + String(error) };
+	}
+}
+/**
+* readTargetOf 失败结果 → RPC 错误载荷（文件不存在时保留 resolvedPath 供诊断）。
+* @author ddj 2026年09月22号
+* @param prep readTargetOf 的失败分支
+* @returns { ok:false } 形态载荷
+*/
+function targetErrOf(prep) {
+	return prep.resolvedPath !== void 0 ? {
+		ok: false,
+		error: prep.err,
+		resolvedPath: prep.resolvedPath
+	} : {
+		ok: false,
+		error: prep.err
+	};
+}
+/**
 * 本地文件系统版本令牌（mtime+size）：与 ctx.fs 的不透明版本串用途相同，
 * 仅供全局片段文件（走 node:fs 直读、不经 ctx.fs）在 edrv.read 时回带。
 * @author ddj 2026年09月15号
@@ -7567,6 +8489,7 @@ async function afterManualSave(ctx, registry, sc, path) {
 async function applyDecisions(ctx, session, cwd, bucket, items) {
 	const results = [];
 	const resolved = [];
+	const ws = findRemoteWs(cwd);
 	let changed = false;
 	for (const item of items) {
 		const record = bucket.get(item.callId);
@@ -7601,7 +8524,7 @@ async function applyDecisions(ctx, session, cwd, bucket, items) {
 		const result = {
 			callId: item.callId,
 			ok: true,
-			record: recView(record)
+			record: recView(record, ws)
 		};
 		if (revertedStale) result.stale = true;
 		results.push(result);
@@ -7633,7 +8556,7 @@ async function latestPatchBackup(patchPath) {
 }
 /** 读取设置中的深链基址（缺省/非法回退默认 3080）。 */
 async function integrationBaseUrlOf(ctx) {
-	const value = (ctx.get("settings")?.describe?.({ redactSecrets: true })?.find((item) => item.ns === FILE_OPEN_SETTINGS_NS))?.value;
+	const value = sectionOf(ctx.get("settings"), FILE_OPEN_SETTINGS_NS)?.value;
 	return (typeof value?.integrationBaseUrl === "string" ? value.integrationBaseUrl.trim() : "") || "http://127.0.0.1:3080";
 }
 /**
@@ -7756,10 +8679,11 @@ function buildHandlers(ctx, registry, searcher = newSearcher(ctx), contentSearch
 				}
 			}
 			const out = [];
+			const ws = findRemoteWs(sc.cwd);
 			for (const rec of bucket.values()) {
 				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 {
@@ -7846,45 +8770,56 @@ function buildHandlers(ctx, registry, searcher = newSearcher(ctx), contentSearch
 				ok: false,
 				error: sc.err
 			};
-			const fs = ctx.get("fs");
-			if (!fs) return {
-				ok: false,
-				error: "缺少 fs"
-			};
+			const prep = await readTargetOf(ctx, sc, args.path);
+			if ("err" in prep) return targetErrOf(prep);
 			try {
-				const target = await resolveTarget(ctx, sc.session, args.path);
-				debugRecord(ctx, sc.cwd, "[DEBUG path.resolve] input=" + String(args.path ?? "") + " resolved=" + fs.processPath(target), "debug");
-				const info = await fs.stat(target);
-				if (!info || info.type !== "file") return {
-					ok: false,
-					error: "文件不存在",
-					resolvedPath: fs.processPath(target)
-				};
-				if ((info.size ?? 0) > 33554432) return {
-					ok: false,
-					error: "文件过大（>32MB），不支持整文件预览"
-				};
 				if (args.encoding === "base64") {
-					const bytes = await fs.readBytes(target, void 0, BINARY_READ_CAP);
+					const bytes = await prep.fs.readBytes(prep.target, void 0, BINARY_READ_CAP);
 					return {
 						ok: true,
 						content: Buffer.from(bytes).toString("base64"),
 						size: bytes.byteLength,
 						encoding: "base64",
 						mime: binaryMimeOf(args.path),
-						version: String(info.version ?? "")
+						version: String(prep.info.version ?? "")
 					};
 				}
-				if ((info.size ?? 0) > 8388608) return {
+				if ((prep.info.size ?? 0) > 8388608) return {
 					ok: false,
 					error: "文件过大（>8MB），不支持整文件预览"
 				};
-				const content = await fs.readText(target);
+				const content = await prep.fs.readText(prep.target);
 				return {
 					ok: true,
 					content,
 					size: content.length,
-					version: String(info.version ?? "")
+					version: String(prep.info.version ?? "")
+				};
+			} catch (error) {
+				return {
+					ok: false,
+					error: "读取失败：" + String(error)
+				};
+			}
+		},
+		"edrv.readBinary": async (args) => {
+			const sc = await requireSession(ctx, args.sessionId);
+			if ("err" in sc) return {
+				ok: false,
+				error: sc.err
+			};
+			const prep = await readTargetOf(ctx, sc, args.path);
+			if ("err" in prep) return targetErrOf(prep);
+			try {
+				const bytes = await prep.fs.readBytes(prep.target, void 0, BINARY_READ_CAP);
+				return {
+					ok: true,
+					binary: {
+						bytes,
+						mime: binaryMimeOf(args.path),
+						size: bytes.byteLength,
+						version: String(prep.info.version ?? "")
+					}
 				};
 			} catch (error) {
 				return {
@@ -8054,7 +8989,9 @@ function buildHandlers(ctx, registry, searcher = newSearcher(ctx), contentSearch
 				ok: false,
 				error: sc.err
 			};
-			const entries = parseArchive(await readArchiveText(ctx, sc.cwd)).filter((b) => b.cwd === sc.cwd).map((b) => {
+			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) => {
 					const sm = r.summary || {
@@ -8078,6 +9015,7 @@ function buildHandlers(ctx, registry, searcher = newSearcher(ctx), contentSearch
 					at: b.at,
 					lastAt: b.lastAt || b.at,
 					path: b.path,
+					...ws ? { displayPath: remoteDisplayOf(b.path, ws) ?? void 0 } : {},
 					batch: b.batch ?? null,
 					reason: b.reason ?? null,
 					nRecords: recs.length,
@@ -8633,39 +9571,32 @@ function buildHandlers(ctx, registry, searcher = newSearcher(ctx), contentSearch
 			}
 		},
 		"vscode.fileOpenSettingsGet": async () => {
-			const descriptor = ctx.get("settings")?.describe?.({ redactSecrets: true })?.find((item) => item.ns === FILE_OPEN_SETTINGS_NS);
-			const value = descriptor?.value;
+			const section = sectionOf(ctx.get("settings"), FILE_OPEN_SETTINGS_NS);
+			const value = section?.value;
 			return {
 				ok: true,
 				fileOpenTool: normalizeFileOpenTool(value?.fileOpenTool ?? "auto"),
 				integrationBaseUrl: await integrationBaseUrlOf(ctx),
-				revision: descriptor?.revision
+				revision: section?.revision
 			};
 		},
 		"vscode.fileOpenSettingsUpdate": async (args) => {
 			const settings = ctx.get("settings");
-			if (!settings?.update) return {
+			const patch = { fileOpenTool: normalizeFileOpenTool(args.fileOpenTool) };
+			if (typeof args.integrationBaseUrl === "string" && args.integrationBaseUrl.trim()) patch.integrationBaseUrl = args.integrationBaseUrl.trim();
+			const result = await updateSection(settings, FILE_OPEN_SETTINGS_NS, patch, args.expectedRevision);
+			if (!result.ok) return {
 				ok: false,
-				error: "设置服务不可用"
+				error: result.error ?? "设置服务不可用"
+			};
+			const section = sectionOf(settings, FILE_OPEN_SETTINGS_NS);
+			const value = section?.value;
+			return {
+				ok: true,
+				fileOpenTool: normalizeFileOpenTool(value?.fileOpenTool),
+				integrationBaseUrl: await integrationBaseUrlOf(ctx),
+				revision: section?.revision
 			};
-			try {
-				const patch = { fileOpenTool: normalizeFileOpenTool(args.fileOpenTool) };
-				if (typeof args.integrationBaseUrl === "string" && args.integrationBaseUrl.trim()) patch.integrationBaseUrl = args.integrationBaseUrl.trim();
-				await settings.update(FILE_OPEN_SETTINGS_NS, patch, args.expectedRevision);
-				const descriptor = settings.describe?.({ redactSecrets: true })?.find((item) => item.ns === FILE_OPEN_SETTINGS_NS);
-				const value = descriptor?.value;
-				return {
-					ok: true,
-					fileOpenTool: normalizeFileOpenTool(value?.fileOpenTool),
-					integrationBaseUrl: await integrationBaseUrlOf(ctx),
-					revision: descriptor?.revision
-				};
-			} catch (error) {
-				return {
-					ok: false,
-					error: String(error)
-				};
-			}
 		},
 		"compat": async () => ({
 			ok: true,
@@ -8829,6 +9760,7 @@ function buildHandlers(ctx, registry, searcher = newSearcher(ctx), contentSearch
 				const inventory = await scanSessionInventory(home, sessionsArchiveRoot(home));
 				const active = activeSessionIds(ctx);
 				markActiveSessions(inventory.sessions, active);
+				markOfficialFlags(inventory.sessions, ctx);
 				return {
 					ok: true,
 					...inventory,
@@ -8897,13 +9829,15 @@ function buildHandlers(ctx, registry, searcher = newSearcher(ctx), contentSearch
 		"edrv.perf.restore": async (args) => {
 			try {
 				const result = await restoreSession(dshHome(), sessionsArchiveRoot(dshHome()), args.workspaceKey, args.sessionId);
-				return result.ok ? {
-					ok: true,
-					restored: true
-				} : {
+				if (!result.ok) return {
 					ok: false,
 					error: result.error ?? "恢复失败"
 				};
+				await unarchiveOfficial(ctx, args.sessionId);
+				return {
+					ok: true,
+					restored: true
+				};
 			} catch (error) {
 				return {
 					ok: false,
@@ -9616,6 +10550,9 @@ function createLspClient(transport, events = {}) {
 		workspaceSymbol: false,
 		hover: false,
 		semanticTokens: false,
+		completion: false,
+		completionResolve: false,
+		signatureHelp: false,
 		semanticTokenTypes: [],
 		semanticTokenModifiers: []
 	};
@@ -9749,6 +10686,23 @@ function createLspClient(transport, events = {}) {
 						references: { dynamicRegistration: false },
 						documentSymbol: { dynamicRegistration: false },
 						hover: { dynamicRegistration: false },
+						completion: {
+							dynamicRegistration: false,
+							contextSupport: true,
+							completionItem: {
+								snippetSupport: true,
+								documentationFormat: ["markdown", "plaintext"],
+								resolveSupport: { properties: [
+									"documentation",
+									"detail",
+									"additionalTextEdits"
+								] }
+							}
+						},
+						signatureHelp: {
+							dynamicRegistration: false,
+							signatureInformation: { documentationFormat: ["markdown", "plaintext"] }
+						},
 						semanticTokens: {
 							dynamicRegistration: false,
 							requests: {
@@ -9771,6 +10725,9 @@ function createLspClient(transport, events = {}) {
 				workspaceSymbol: Boolean(caps.workspaceSymbolProvider),
 				hover: Boolean(caps.hoverProvider),
 				semanticTokens: Boolean(caps.semanticTokensProvider),
+				completion: Boolean(caps.completionProvider),
+				completionResolve: Boolean(caps.completionProvider?.resolveProvider),
+				signatureHelp: Boolean(caps.signatureHelpProvider),
 				semanticTokenTypes: Array.isArray(legend?.tokenTypes) ? legend.tokenTypes.filter((item) => typeof item === "string") : [...LSP_SEMANTIC_TOKEN_TYPES],
 				semanticTokenModifiers: Array.isArray(legend?.tokenModifiers) ? legend.tokenModifiers.filter((item) => typeof item === "string") : [...LSP_SEMANTIC_TOKEN_MODIFIERS]
 			};
@@ -9972,6 +10929,9 @@ function createLspServer(spec, root, languageId, logger) {
 		workspaceSymbol: false,
 		hover: false,
 		semanticTokens: false,
+		completion: false,
+		completionResolve: false,
+		signatureHelp: false,
 		semanticTokenTypes: [...LSP_SEMANTIC_TOKEN_TYPES],
 		semanticTokenModifiers: [...LSP_SEMANTIC_TOKEN_MODIFIERS]
 	};
@@ -10228,6 +11188,68 @@ function createLspServer(spec, root, languageId, logger) {
 			if (!result || !result.contents) return null;
 			return { contents: stringifyHoverContents(result.contents) };
 		},
+		/**
+		* 查询补全列表（textDocument/completion）。
+		*
+		* 列表阶段**剥离 documentation**：EmmyLua 把文档挂在 resolve 阶段（我方 initialize 已声明
+		* resolveSupport），但并非所有服务器都遵守；每条都带长文档会让单次 RPC 载荷暴涨。
+		* `data` 原样透传，resolve 时由服务器回认该条目。
+		* @author ddj 2026年09月22号
+		* @param path 工作区相对路径
+		* @param line 0-based 行
+		* @param character 0-based 列
+		* @param context LSP CompletionContext（触发字符/触发类型）
+		* @returns 归一化补全列表；不支持或文档未打开时 null
+		*/
+		async completion(path, line, character, context) {
+			const doc = docs.get(path);
+			if (!doc || !await readyWait || !capabilities.completion) return null;
+			const params = {
+				textDocument: { uri: doc.uri },
+				position: {
+					line,
+					character
+				}
+			};
+			if (context) params.context = context;
+			return normCompletion(await ensureClient().request("textDocument/completion", params));
+		},
+		/**
+		* 补全项惰性补全（completionItem/resolve）：按 `data` 取回 documentation/detail/additionalTextEdits。
+		*
+		* 必须回传**完整条目**（服务器按 data + label 精确匹配），只发 label/data 可能被服务器忽略。
+		* @author ddj 2026年09月22号
+		* @param path 工作区相对路径
+		* @param item 列表阶段返回的补全项
+		* @returns 补全后的条目；服务器不支持时原样返回
+		*/
+		async resolveCompletion(path, item) {
+			if (!item || typeof item.label !== "string") return null;
+			if (!await readyWait || !capabilities.completionResolve) return item;
+			return normCompItem(await ensureClient().request("completionItem/resolve", toLspCompItem(item))) ?? item;
+		},
+		/**
+		* 查询签名帮助（textDocument/signatureHelp）。
+		*
+		* activeSignature/activeParameter 做边界裁剪：服务器可能给越界值（多签名时按实参推进出错），
+		* Monaco 拿到越界索引会取不到签名而不渲染 —— 裁剪后至少显示首个签名。
+		* @author ddj 2026年09月22号
+		* @param path 工作区相对路径
+		* @param line 0-based 行
+		* @param character 0-based 列
+		* @returns 归一化签名帮助；无签名/不支持时 null
+		*/
+		async signatureHelp(path, line, character) {
+			const doc = docs.get(path);
+			if (!doc || !await readyWait || !capabilities.signatureHelp) return null;
+			return toSignatureHelp(await ensureClient().request("textDocument/signatureHelp", {
+				textDocument: { uri: doc.uri },
+				position: {
+					line,
+					character
+				}
+			}));
+		},
 		/** 查询全文 semantic tokens，并将服务器 legend 归一到插件固定 legend。 */
 		async semanticTokens(path) {
 			const doc = docs.get(path);
@@ -10333,8 +11355,205 @@ function normalizeSymbol(item) {
 	}
 	return symbol;
 }
-/** hover contents → 文本行（MarkupContent | MarkedString | MarkedString[]）。 */
-function stringifyHoverContents(contents) {
+/** hover/markdown 内容 → 纯文本（string | MarkupContent | MarkedString[] | MarkedString）。 */
+function plainText(value) {
+	if (typeof value === "string") return value || void 0;
+	if (Array.isArray(value)) {
+		const parts = value.map(plainText).filter((part) => Boolean(part));
+		return parts.length ? parts.join("\n\n") : void 0;
+	}
+	if (value && typeof value === "object") {
+		const text = value.value;
+		if (typeof text === "string") return text || void 0;
+	}
+}
+/**
+* 归一化补全文本编辑范围（单 range 与 insert/replace 双 range 两种形态）。
+*
+* 两种形态必须都认：只认一种会让采用另一种形态的服务器补全落点错位（替换范围算错，
+* 已输入的前缀被重复插入）。双 range 时 insert 用于「保留前缀插入」，replace 用于覆盖。
+* @author ddj 2026年09月22号
+* @param raw 原始 textEdit
+* @returns 归一化文本编辑；无有效范围或文本时 null
+*/
+function normalizeTextEdit(raw) {
+	if (!raw || typeof raw !== "object") return null;
+	const obj = raw;
+	const newText = typeof obj.newText === "string" ? obj.newText : "";
+	if (!newText) return null;
+	const single = normalizeRange(obj.range);
+	if (single) return {
+		range: single,
+		newText
+	};
+	const insert = normalizeRange(obj.insert);
+	const replace = normalizeRange(obj.replace);
+	if (!insert && !replace) return null;
+	return {
+		insert: insert ?? replace,
+		replace: replace ?? insert,
+		newText
+	};
+}
+/** 归一化 LSP Range（缺字段返回 null，避免产出畸形范围）。 */
+function normalizeRange(raw) {
+	if (!raw || typeof raw !== "object") return null;
+	const r = raw;
+	if (!r.start || !r.end) return null;
+	return {
+		start: {
+			line: toInt(r.start.line),
+			character: toInt(r.start.character)
+		},
+		end: {
+			line: toInt(r.end.line),
+			character: toInt(r.end.character)
+		}
+	};
+}
+/**
+* 归一化单个补全项。
+* @author ddj 2026年09月22号
+* @param raw 原始条目
+* @returns 归一化条目；缺 label 时 null
+*/
+function normCompItem(raw) {
+	if (!raw || typeof raw !== "object") return null;
+	const obj = raw;
+	const label = typeof obj.label === "string" ? obj.label : "";
+	if (!label) return null;
+	const item = { label };
+	if (typeof obj.kind === "number") item.kind = toInt(obj.kind);
+	if (typeof obj.detail === "string" && obj.detail) item.detail = obj.detail;
+	const documentation = plainText(obj.documentation);
+	if (documentation) item.documentation = documentation;
+	if (typeof obj.insertText === "string") item.insertText = obj.insertText;
+	if (typeof obj.insertTextFormat === "number") item.insertTextFormat = toInt(obj.insertTextFormat);
+	const textEdit = normalizeTextEdit(obj.textEdit);
+	if (textEdit) item.textEdit = textEdit;
+	if (obj.data !== void 0) item.data = obj.data;
+	if (typeof obj.sortText === "string") item.sortText = obj.sortText;
+	if (typeof obj.filterText === "string") item.filterText = obj.filterText;
+	if (obj.preselect === true) item.preselect = true;
+	if (Array.isArray(obj.commitCharacters)) {
+		const chars = obj.commitCharacters.filter((c) => typeof c === "string");
+		if (chars.length) item.commitCharacters = chars;
+	}
+	const tags = Array.isArray(obj.tags) ? obj.tags : [];
+	if (obj.deprecated === true || tags.some((tag) => toInt(tag) === 1)) item.deprecated = true;
+	if (Array.isArray(obj.additionalTextEdits)) {
+		const edits = obj.additionalTextEdits.map((edit) => {
+			const range = normalizeRange(edit?.range);
+			const text = edit?.newText;
+			if (!range || typeof text !== "string") return null;
+			return {
+				range,
+				newText: text
+			};
+		}).filter((edit) => edit !== null);
+		if (edits.length) item.additionalTextEdits = edits;
+	}
+	return item;
+}
+/**
+* 归一化补全结果（CompletionList | CompletionItem[]）。
+*
+* 两种顶层形态都要认：`{ isIncomplete, items }` 与裸数组。裸数组是最常见形态，
+* 只认 CompletionList 会让「补全列表恒为空」且无报错。
+* @author ddj 2026年09月22号
+* @param result 原始响应
+* @returns 归一化列表；无效时 null
+*/
+function normCompletion(result) {
+	if (result == null) return null;
+	const list = Array.isArray(result) ? {
+		items: result,
+		isIncomplete: false
+	} : result;
+	if (!Array.isArray(list.items)) return null;
+	return {
+		items: list.items.map(normCompItem).filter((item) => item !== null),
+		incomplete: list.isIncomplete === true
+	};
+}
+/**
+* 补全项 → LSP 载荷（resolve 回传用）。
+* 只回传协议字段，剔除 client 侧衍生字段；`data` 必须原样带上，服务器靠它认条目。
+* @author ddj 2026年09月22号
+* @param item 归一化条目
+* @returns LSP CompletionItem 载荷
+*/
+function toLspCompItem(item) {
+	const out = { label: item.label };
+	if (item.kind !== void 0) out.kind = item.kind;
+	if (item.detail !== void 0) out.detail = item.detail;
+	if (item.documentation !== void 0) out.documentation = item.documentation;
+	if (item.insertText !== void 0) out.insertText = item.insertText;
+	if (item.insertTextFormat !== void 0) out.insertTextFormat = item.insertTextFormat;
+	if (item.data !== void 0) out.data = item.data;
+	if (item.sortText !== void 0) out.sortText = item.sortText;
+	if (item.filterText !== void 0) out.filterText = item.filterText;
+	if (item.textEdit) out.textEdit = item.textEdit.range ? {
+		range: item.textEdit.range,
+		newText: item.textEdit.newText
+	} : item.textEdit;
+	if (item.additionalTextEdits) out.additionalTextEdits = item.additionalTextEdits;
+	if (item.commitCharacters) out.commitCharacters = item.commitCharacters;
+	return out;
+}
+/** 归一化单个签名参数（label 支持字符串与 [start, end] 元组，两者原样透传）。 */
+function toSignatureParam(raw) {
+	if (!raw || typeof raw !== "object") return null;
+	const obj = raw;
+	const tuple = Array.isArray(obj.label) && obj.label.length >= 2 ? [toInt(obj.label[0]), toInt(obj.label[1])] : null;
+	if (typeof obj.label !== "string" && !tuple) return null;
+	const param = { label: typeof obj.label === "string" ? obj.label : tuple };
+	const documentation = plainText(obj.documentation);
+	if (documentation) param.documentation = documentation;
+	return param;
+}
+/** 归一化单个签名。 */
+function toSignature(raw) {
+	if (!raw || typeof raw !== "object") return null;
+	const obj = raw;
+	if (typeof obj.label !== "string") return null;
+	const signature = {
+		label: obj.label,
+		parameters: []
+	};
+	const documentation = plainText(obj.documentation);
+	if (documentation) signature.documentation = documentation;
+	if (Array.isArray(obj.parameters)) signature.parameters = obj.parameters.map(toSignatureParam).filter((param) => param !== null);
+	if (typeof obj.activeParameter === "number") signature.activeParameter = toInt(obj.activeParameter);
+	return signature;
+}
+/**
+* 归一化签名帮助，并裁剪越界的 activeSignature / activeParameter。
+*
+* 为什么必须裁：Monaco 用这两个索引直接取签名与参数，越界时取不到签名就整个浮窗不渲染；
+* 服务器在「实参刚敲下逗号」等边界时刻常给超前一位的索引。裁剪后至少显示首个签名/末个参数，
+* 观感是「高亮没跟上」，而不是「参数提示整个不见」。
+* @author ddj 2026年09月22号
+* @param result 原始响应
+* @returns 归一化结果；无有效签名时 null
+*/
+function toSignatureHelp(result) {
+	if (!result || typeof result !== "object") return null;
+	const obj = result;
+	if (!Array.isArray(obj.signatures)) return null;
+	const signatures = obj.signatures.map(toSignature).filter((signature) => signature !== null);
+	if (!signatures.length) return null;
+	const activeSignature = Math.min(Math.max(0, toInt(obj.activeSignature)), signatures.length - 1);
+	const current = signatures[activeSignature];
+	const rawActive = typeof obj.activeParameter === "number" ? toInt(obj.activeParameter) : current.activeParameter ?? 0;
+	const count = current.parameters.length;
+	return {
+		signatures,
+		activeSignature,
+		activeParameter: count > 0 ? Math.min(Math.max(0, rawActive), count - 1) : 0
+	};
+}
+/** hover contents → 文本行（MarkupContent | MarkedString | MarkedString[]）。 */ function stringifyHoverContents(contents) {
 	if (typeof contents === "string") return [contents];
 	if (Array.isArray(contents)) return contents.map(stringifyHoverContents).flat().filter(Boolean);
 	if (contents && typeof contents === "object") {
@@ -12243,6 +13462,99 @@ function createLspRpc(deps) {
 					};
 				}
 			},
+			"edrv.lsp.completion": async (args) => {
+				const lang = langOfPath(args.path);
+				if (!lang) return {
+					ok: true,
+					completions: void 0
+				};
+				const sc = await rootOf(args.sessionId);
+				if ("err" in sc) return {
+					ok: false,
+					error: sc.err
+				};
+				try {
+					const server = serverOf(sc.root, lang);
+					if (!server) return {
+						ok: true,
+						completions: void 0
+					};
+					const completions = await server.completion(wsPath(sc.root, args.path), args.position.line, args.position.character, args.context);
+					if (!completions) return {
+						ok: true,
+						completions: void 0
+					};
+					return {
+						ok: true,
+						completions: completions.items.length > 500 ? {
+							...completions,
+							items: completions.items.slice(0, 500),
+							truncated: true
+						} : completions
+					};
+				} catch (error) {
+					return {
+						ok: false,
+						error: "LSP 补全查询失败：" + String(error)
+					};
+				}
+			},
+			"edrv.lsp.resolveCompletion": async (args) => {
+				const lang = langOfPath(args.path);
+				if (!lang) return {
+					ok: true,
+					item: void 0
+				};
+				const sc = await rootOf(args.sessionId);
+				if ("err" in sc) return {
+					ok: false,
+					error: sc.err
+				};
+				try {
+					const server = serverOf(sc.root, lang);
+					if (!server) return {
+						ok: true,
+						item: args.item
+					};
+					return {
+						ok: true,
+						item: await server.resolveCompletion(wsPath(sc.root, args.path), args.item) ?? void 0
+					};
+				} catch (error) {
+					return {
+						ok: false,
+						error: "LSP 补全解析失败：" + String(error)
+					};
+				}
+			},
+			"edrv.lsp.signatureHelp": async (args) => {
+				const lang = langOfPath(args.path);
+				if (!lang) return {
+					ok: true,
+					signatureHelp: void 0
+				};
+				const sc = await rootOf(args.sessionId);
+				if ("err" in sc) return {
+					ok: false,
+					error: sc.err
+				};
+				try {
+					const server = serverOf(sc.root, lang);
+					if (!server) return {
+						ok: true,
+						signatureHelp: void 0
+					};
+					return {
+						ok: true,
+						signatureHelp: await server.signatureHelp(wsPath(sc.root, args.path), args.position.line, args.position.character) ?? void 0
+					};
+				} catch (error) {
+					return {
+						ok: false,
+						error: "LSP 签名帮助查询失败：" + String(error)
+					};
+				}
+			},
 			"edrv.lsp.semanticTokens": async (args) => {
 				const lang = langOfPath(args.path);
 				if (!lang) return {
@@ -12489,6 +13801,29 @@ async function routeOf(llm, cfg) {
 	};
 }
 /**
+* AI 任务模型路由（非补全场景如 AI 智能整理）：任务配置优先，空则回落补全配置链。
+* 回落序：taskProvider/taskModel 双非空直用 → routeOf（补全配置 → 自动首个）；
+* effort 同序：taskEffort 非空用之，否则 cfg.effort（空串 = 不携带）。
+* @author ddj 2026年09月23号
+* @param llm llm 运行时
+* @param cfg AI 配置（含可选任务模型字段）
+* @returns 路由（provider/model/effort）；不可路由返回 null
+*/
+async function taskRouteOf(llm, cfg) {
+	const effort = cfg.taskEffort || cfg.effort || "";
+	if (cfg.taskProvider && cfg.taskModel) return {
+		provider: cfg.taskProvider,
+		model: cfg.taskModel,
+		effort
+	};
+	const base = await routeOf(llm, cfg);
+	if (!base) return null;
+	return {
+		...base,
+		effort
+	};
+}
+/**
 * 单次 AI 内联补全。
 * @author ddj
 * @param deps 服务依赖
@@ -12774,6 +14109,126 @@ function createFileVersions(ctx) {
 	};
 }
 //#endregion
+//#region src/ai/svnTriage.ts
+/** 方案生成最大输出 token（三段 JSON 上限；再大是幻觉温床）。 */
+const AI_PLAN_MAX_TOKENS = 8192;
+/** 系统指令：输出唯一 JSON + 三段判据 + 硬约束（不虚构路径/一路径一类）。 */
+const AI_PLAN_SYSTEM = [
+	"你是 SVN 变更整理助手。根据给出的工作副本变更清单（可能附 diff），产出整理方案，",
+	"输出唯一 JSON 对象，除 JSON 外不得输出任何文本（不要围栏、不要解释）：",
+	"{",
+	"  \"groups\": [{ \"name\": \"英文短名\", \"paths\": [\"路径1\"], \"reason\": \"分组理由\" }],",
+	"  \"reverts\": [{ \"path\": \"路径\", \"reason\": \"还原理由\" }],",
+	"  \"ignores\": [{ \"path\": \"路径\", \"reason\": \"忽略理由\" }]",
+	"}",
+	"规则：",
+	"1. 只可使用清单中出现的路径，绝不虚构或改写路径。",
+	"2. 每个路径至多归入一段（groups/reverts/ignores 互斥），拿不准的路径三段都不列。",
+	"3. groups：按功能主题把待提交改动分入 changelist 组；name 用简短英文（不以 - 开头），",
+	"   同一主题合并为一组，组数尽量少。",
+	"4. reverts：仅针对受版本控制的改动建议还原——行尾/空白噪音、误改、试验性改动等。",
+	"5. ignores：仅针对未版本化的条目建议忽略——构建产物、缓存、日志、临时文件等生成物。",
+	"6. reason 用简短中文一句话说明判定依据。"
+].join("\n");
+/**
+* 构造分析用户段：变更清单行（status | path | changelist）+ 可选 diff 上下文。
+* @author ddj 2026年09月23号
+* @param entries 变更清单（调用方已按 AI_PLAN_PATHS_CAP 截断）
+* @param diffText diff 文本（null = paths-only 降级）
+* @param truncated 清单是否已截断（prompt 注明，防 AI 误以为是全集）
+* @returns 用户消息文本
+*/
+function buildAiPrompt(entries, diffText, truncated = false) {
+	const lines = entries.map((entry) => entry.status + " | " + entry.path + (entry.changelist ? " | " + entry.changelist : ""));
+	let text = (truncated ? "变更清单（已截断，仅分析所列条目；status | path | changelist）：" : "变更清单（status | path | changelist）：") + "\n" + lines.join("\n");
+	if (diffText) text += "\n\n变更 diff（unified，0 上下文行）：\n" + diffText;
+	else text += "\n\n（无 diff 上下文，仅按路径与状态判断）";
+	return text;
+}
+/**
+* 解析 AI 输出 JSON：剥 ``` 围栏 → 取首个 `{` 至末个 `}` → JSON.parse。
+* 失败抛带原文摘要的错误（调用方整体报错零执行，不静默降级）。
+* @author ddj 2026年09月23号
+* @param text 模型输出原文
+* @returns 解析出的对象（形状由 normalizeAiPlan 容错）
+*/
+function parseAiPlanJson(text) {
+	const raw = String(text ?? "");
+	const start = raw.indexOf("{");
+	const end = raw.lastIndexOf("}");
+	if (start < 0 || end <= start) throw new Error("AI 输出不含 JSON 对象：" + raw.slice(0, 200));
+	const body = raw.slice(start, end + 1);
+	try {
+		return JSON.parse(body);
+	} catch (error) {
+		throw new Error("AI 输出无法解析为 JSON：" + String(error) + "（原文摘要：" + body.slice(0, 200) + "）");
+	}
+}
+/**
+* 一次 AI 智能整理分析（一次性非会话流式调用）。
+* llm 缺失/不可路由/流失败/解析失败一律抛错，由 handler 转 `{ok:false, error}`（零执行）。
+* @author ddj 2026年09月23号
+* @param ctx DSH 上下文（取 llm）
+* @param cfg AI 配置（任务模型路由优先，回落补全配置）
+* @param prompt 用户段（buildAiPrompt 产物）
+* @returns 原始方案对象与模型标识
+*/
+async function svnAiPlanOf(ctx, cfg, prompt) {
+	const llm = llmOf(ctx);
+	if (!llm) throw new Error("llm 服务不可用（请检查 DSH 模型配置）");
+	const route = await taskRouteOf(llm, cfg);
+	if (!route) throw new Error("未找到可用模型（请检查 DSH 模型配置）");
+	const controller = new AbortController();
+	let timedOut = false;
+	const timer = setTimeout(() => {
+		timedOut = true;
+		controller.abort(/* @__PURE__ */ new Error("timeout"));
+	}, AI_PLAN_TIMEOUT_MS);
+	try {
+		const stream = llm.stream({
+			provider: route.provider,
+			model: route.model,
+			...route.effort ? { reasoningEffort: route.effort } : {},
+			messages: [{
+				role: "user",
+				content: [{
+					type: "text",
+					text: prompt
+				}],
+				source: { kind: "user" }
+			}],
+			system: AI_PLAN_SYSTEM,
+			temperature: .2,
+			maxTokens: AI_PLAN_MAX_TOKENS,
+			signal: controller.signal
+		});
+		let text = "";
+		let failNote = "";
+		for await (const chunk of stream) {
+			const c = chunk;
+			if (c.type === "text-delta") text += c.text;
+			else if (c.type === "finish") {
+				const kind = c.reason?.kind;
+				if (kind === "error" || kind === "aborted") {
+					const failure = c.reason.failure;
+					failNote = "模型流失败 " + (failure?.code ?? kind) + ": " + (failure?.message ?? "模型调用失败");
+				}
+				break;
+			}
+		}
+		if (failNote) throw new Error(failNote);
+		return {
+			raw: parseAiPlanJson(text),
+			model: route.provider + "/" + route.model
+		};
+	} catch (error) {
+		if (timedOut) throw new Error("AI 分析超时（" + Math.round(AI_PLAN_TIMEOUT_MS / 1e3) + "s）：可在设置页调低任务模型思考强度或换更快模型");
+		throw error;
+	} finally {
+		clearTimeout(timer);
+	}
+}
+//#endregion
 //#region src/svnXml.ts
 /**
 * dsh-vscode-mode host — SVN XML 解析基元（零第三方依赖，可单测）。
@@ -13338,6 +14793,22 @@ async function findTortoiseProc(dirSetting, exists = defaultExists, platform = p
 	return null;
 }
 /**
+* svn:ignore 名称合法性校验（host 权威；防换行注入 propset 值与路径穿越）。
+* 规则：去空白后非空、无换行、无路径分隔符、不以 `-` 开头（防被 svn 当选项解析）。
+* @author ddj 2026年09月23号
+* @param name 待写入的忽略名（basename / 通配模式）
+* @returns 错误文案；合法为 null
+*/
+function ignoreNameErrorOf(name) {
+	if (typeof name !== "string") return "忽略名必须是字符串";
+	const trimmed = name.trim();
+	if (!trimmed) return "忽略名不能为空";
+	if (/[\r\n]/.test(trimmed)) return "忽略名不能包含换行";
+	if (trimmed.includes("/") || trimmed.includes("\\")) return "忽略名不能包含路径分隔符";
+	if (trimmed.startsWith("-")) return "忽略名不能以 - 开头";
+	return null;
+}
+/**
 * 本插件已自研的 SVN 能力（「自研替换时间线」的推进点）。
 *
 * 每完成一个阶段就把对应能力加进来：client 会据此隐藏被覆盖的 TortoiseProc 项，
@@ -13642,6 +15113,8 @@ function createSvnRpc(deps) {
 	const statusCache = /* @__PURE__ */ new Map();
 	/** 变更清单缓存（键 = 工作副本根；TTL 短，仅合并同一轮 UI 的多处拉取）。 */
 	const changesCache = /* @__PURE__ */ new Map();
+	/** 混合通道方案收件箱（key = 工作副本根；覆盖式入箱 + TTL，见 svn.aiPlanSubmit/Pending）。 */
+	const planInbox = /* @__PURE__ */ new Map();
 	/** 工作副本根 relative-url 缓存（日志路径映射用；探测失败也缓存空串避免反复 spawn）。 */
 	const urlCache = /* @__PURE__ */ new Map();
 	let cliProbe = null;
@@ -14071,6 +15544,63 @@ function createSvnRpc(deps) {
 		};
 		return merged.binary || merged.encodingHint ? merged : {};
 	};
+	/**
+	* svn:ignore 写入执行（AI 整理执行段③）：逐目录 `propget` 读既有值 → 合并去重 → `propset`。
+	* 不整体覆盖（保留团队既有 ignore）；逐目录失败收集不中断，全部失败才 ok:false。
+	* @author ddj 2026年09月23号
+	* @param wcRoot 工作副本根
+	* @param items 目录聚合写入项（dir 已归一，根为 '.'）
+	* @returns 新增计数/摘要/原文
+	*/
+	const ignoreApplyOf = async (wcRoot, items) => {
+		let count = 0;
+		const notes = [];
+		const failures = [];
+		for (const item of items) {
+			const getOutcome = await runSvn(wcRoot, [
+				"propget",
+				"svn:ignore",
+				"--",
+				item.dir
+			], READ_GRACE_MS);
+			if (getOutcome.code !== 0) {
+				failures.push(item.dir + " 读取失败：" + tailOfText(getOutcome.stderr || getOutcome.stdout));
+				continue;
+			}
+			const merged = [...getOutcome.stdout.split(/\r?\n/).map((line) => line.trim()).filter(Boolean)];
+			let added = 0;
+			for (const name of item.names) {
+				if (merged.includes(name)) continue;
+				merged.push(name);
+				added++;
+			}
+			if (!added) {
+				notes.push(item.dir + "：无新增（已在忽略列表）");
+				continue;
+			}
+			const setOutcome = await runSvn(wcRoot, [
+				"propset",
+				"svn:ignore",
+				merged.join("\n"),
+				"--",
+				item.dir
+			], MUTATE_GRACE_MS);
+			if (setOutcome.code !== 0) {
+				failures.push(item.dir + " 写入失败：" + tailOfText(setOutcome.stderr || setOutcome.stdout));
+				continue;
+			}
+			count += added;
+			notes.push(item.dir + "：新增 " + added + " 项");
+		}
+		const ok = failures.length < items.length;
+		const summary = failures.length ? "svn:ignore 写入 " + count + " 项；失败 " + failures.length + " 个目录" : count > 0 ? "svn:ignore 写入 " + count + " 项" : "无新增忽略项";
+		return {
+			ok,
+			count,
+			summary,
+			output: [...notes, ...failures].join("\n")
+		};
+	};
 	return { handlers: {
 		"svn.status": async (args) => {
 			const sc = await requireSvnSession(ctx, args.sessionId);
@@ -14186,6 +15716,26 @@ function createSvnRpc(deps) {
 		"svn.add": async (args) => {
 			return mutate("加入版本控制", ["add"], args.sessionId, args.paths);
 		},
+		/**
+		* 分区（changelist）批量操作：关联或解除工作副本条目的 changelist 登记。
+		* 复用 mutate 全套护栏（路径白名单 / BATCH_PATHS_CAP / 超时 / 变更缓存作废）；
+		* 分区名 host 权威校验（`-` 开头会被 svn 当成选项解析），remove 分支不需要名字。
+		* @author ddj 2026年09月23号
+		* @param args.paths 工作区相对路径列表
+		* @param args.name 目标分区名（remove 时忽略）
+		* @param args.remove true = 移出分区（`changelist --remove`）
+		* @returns 批量动作结果
+		*/
+		"svn.changelist": async (args) => {
+			if (args.remove !== true) {
+				const nameError = svnChangelistNameErrorOf(String(args.name ?? ""));
+				if (nameError) return {
+					ok: false,
+					error: nameError
+				};
+			}
+			return mutate(args.remove === true ? "移出分区" : "分区", args.remove === true ? ["changelist", "--remove"] : ["changelist", String(args.name ?? "").trim()], args.sessionId, args.paths);
+		},
 		"svn.log": async (args) => {
 			const sc = await requireSvnSession(ctx, args.sessionId);
 			if ("err" in sc) return {
@@ -14615,35 +16165,255 @@ function createSvnRpc(deps) {
 				ok: false,
 				error: "缺少 fs"
 			};
-			const sizes = [];
-			for (const raw of list) {
+			const sizeOne = async (raw) => {
 				const rel = safeRel(raw);
-				if (rel === null || rel === "") {
-					sizes.push({
-						path: String(raw ?? ""),
-						size: null
-					});
-					continue;
-				}
+				if (rel === null || rel === "") return {
+					path: String(raw ?? ""),
+					size: null
+				};
 				try {
 					const resolved = await fs.resolve(rel, { cwd: sc.cwd });
 					const info = await fs.stat(resolved);
-					sizes.push({
+					return {
 						path: rel,
 						size: info && info.type === "file" ? info.size ?? null : null
-					});
+					};
 				} catch {
-					sizes.push({
+					return {
 						path: rel,
 						size: null
-					});
+					};
 				}
-			}
+			};
+			const sizes = [];
+			const BATCH = 16;
+			for (let start = 0; start < list.length; start += BATCH) sizes.push(...await Promise.all(list.slice(start, start + BATCH).map(sizeOne)));
 			return {
 				ok: true,
 				sizes
 			};
 		},
+		/**
+		* AI 智能整理分析（只读）：拉最新变更 → 附 diff 上下文（超限降级 paths-only）→
+		* LLM 流式产出 JSON → normalizeAiPlan 以真实清单白名单归一。任何失败零执行只报错。
+		* @author ddj 2026年09月23号
+		* @param args.sessionId 会话 id
+		* @returns 三段方案 + 分析元信息（条目数/是否含 diff/丢弃数/模型）
+		*/
+		"svn.aiPlan": async (args) => {
+			const sc = await requireSvnSession(ctx, args.sessionId);
+			if ("err" in sc) return {
+				ok: false,
+				error: sc.err
+			};
+			const status = await statusOf(sc.cwd);
+			if (!status.managed || !status.wcRoot) return {
+				ok: false,
+				error: "当前工作区不受 SVN 管理"
+			};
+			if (!status.svnCli) return {
+				ok: false,
+				error: "svn 命令不可用（可在设置页配置 svn 路径）"
+			};
+			try {
+				const { entries } = await changesOf(status.wcRoot, true);
+				let diffText = null;
+				try {
+					const outcome = await runSvn(status.wcRoot, [
+						"diff",
+						"-x",
+						"-U0"
+					], READ_GRACE_MS, AI_PLAN_DIFF_CAP);
+					if (outcome.code === 0 && outcome.stdout.trim() && outcome.stdout.length < 2097152) diffText = outcome.stdout;
+				} catch {}
+				const capped = entries.length > AI_PLAN_PATHS_CAP;
+				const used = capped ? entries.slice(0, AI_PLAN_PATHS_CAP) : entries;
+				const diffIncluded = diffText !== null && !capped;
+				const prompt = buildAiPrompt(used, diffIncluded ? diffText : null, capped);
+				const cfg = settings.ai ? settings.ai() : {
+					enabled: true,
+					provider: "",
+					model: "",
+					effort: ""
+				};
+				const result = await svnAiPlanOf(ctx, cfg, prompt);
+				const { plan, dropped } = normalizeAiPlan(result.raw, entries);
+				return {
+					ok: true,
+					plan,
+					entriesCount: entries.length,
+					diffIncluded,
+					dropped,
+					model: result.model
+				};
+			} catch (error) {
+				return {
+					ok: false,
+					error: String(error instanceof Error ? error.message : error)
+				};
+			}
+		},
+		/**
+		* AI 智能整理执行段③：按目录合并写入 svn:ignore 属性（propget 合并，不整体覆盖）。
+		* 复用受管理/svnCli 校验与变更缓存作废语义（对齐 mutate）。
+		* @author ddj 2026年09月23号
+		* @param args.items 目录聚合写入项（dir + 该目录下新增忽略名）
+		* @returns 新增计数/摘要/原文
+		*/
+		"svn.ignore": async (args) => {
+			const sc = await requireSvnSession(ctx, args.sessionId);
+			if ("err" in sc) return {
+				ok: false,
+				error: sc.err
+			};
+			const items = Array.isArray(args.items) ? args.items : [];
+			if (!items.length) return {
+				ok: false,
+				error: "未选择任何路径"
+			};
+			const clean = [];
+			let total = 0;
+			for (const item of items) {
+				const rel = safeRel(item?.dir);
+				if (rel === null) return {
+					ok: false,
+					error: "路径不合法"
+				};
+				const names = Array.isArray(item?.names) ? item.names : [];
+				if (!names.length) return {
+					ok: false,
+					error: "忽略名列表为空"
+				};
+				const checked = [];
+				for (const name of names) {
+					const nameError = ignoreNameErrorOf(name);
+					if (nameError) return {
+						ok: false,
+						error: nameError
+					};
+					checked.push(String(name).trim());
+				}
+				total += checked.length;
+				if (total > 64) return {
+					ok: false,
+					error: "一次最多处理 64 个路径"
+				};
+				clean.push({
+					dir: rel === "" ? "." : rel,
+					names: checked
+				});
+			}
+			const status = await statusOf(sc.cwd);
+			if (!status.managed || !status.wcRoot) return {
+				ok: false,
+				error: "当前工作区不受 SVN 管理"
+			};
+			if (!status.svnCli) return {
+				ok: false,
+				error: "svn 命令不可用（可在设置页配置 svn 路径）"
+			};
+			try {
+				const result = await ignoreApplyOf(status.wcRoot, clean);
+				changesCache.delete(status.wcRoot);
+				if (!result.ok) return {
+					ok: false,
+					error: result.summary + (result.output ? "\n" + tailOfText(result.output) : "")
+				};
+				return {
+					ok: true,
+					count: result.count,
+					summary: result.summary,
+					output: result.output
+				};
+			} catch (error) {
+				return {
+					ok: false,
+					error: "svn:ignore 写入失败：" + String(error)
+				};
+			}
+		},
+		/**
+		* 混合通道投递口（01-hybrid-deep-analysis）：会话 agent 深度分析后 POST 方案入收件箱。
+		* 只读 + 内存态：经 normalizeAiPlan 以最新变更清单白名单归一（幻觉路径丢弃计数），
+		* 零接受拒收（防 agent 空转误报成功）；覆盖式入箱（新投递顶掉旧件）。
+		* @author ddj 2026年09月23号
+		* @param args.plan agent 产出的方案 JSON（形状宽松，归一兜底）
+		* @returns 接受路径数与丢弃数
+		*/
+		"svn.aiPlanSubmit": async (args) => {
+			const sc = await requireSvnSession(ctx, args.sessionId);
+			if ("err" in sc) return {
+				ok: false,
+				error: sc.err
+			};
+			const status = await statusOf(sc.cwd);
+			if (!status.managed || !status.wcRoot) return {
+				ok: false,
+				error: "当前工作区不受 SVN 管理"
+			};
+			if (!status.svnCli) return {
+				ok: false,
+				error: "svn 命令不可用（可在设置页配置 svn 路径）"
+			};
+			try {
+				const { entries } = await changesOf(status.wcRoot, true);
+				const { plan, dropped } = normalizeAiPlan(args.plan, entries);
+				const accepted = plan.reverts.length + plan.ignores.length + plan.groups.reduce((n, group) => n + group.paths.length, 0);
+				if (!accepted) return {
+					ok: false,
+					error: "方案为空：无任何路径通过白名单校验（丢弃 " + dropped + " 项）"
+				};
+				planInbox.set(status.wcRoot, {
+					plan,
+					dropped,
+					at: now()
+				});
+				return {
+					ok: true,
+					accepted,
+					dropped
+				};
+			} catch (error) {
+				return {
+					ok: false,
+					error: "方案投递失败：" + String(error)
+				};
+			}
+		},
+		/**
+		* 混合通道取件口：面板轮询取收件箱方案。
+		* since = 注入时刻——早于它的旧投递不算新件（防上一轮残留被误认为本轮结果）；
+		* TTL 过期返回 plan:null。非破坏性读取（重复取到同一份由 client 侧取件即停消化）。
+		* @author ddj 2026年09月23号
+		* @param args.since 注入时刻时间戳（缺省 0 = 取任意件）
+		* @returns 方案与元信息（无新件 plan 为 null）
+		*/
+		"svn.aiPlanPending": async (args) => {
+			const sc = await requireSvnSession(ctx, args.sessionId);
+			if ("err" in sc) return {
+				ok: false,
+				error: sc.err
+			};
+			const status = await statusOf(sc.cwd);
+			if (!status.managed || !status.wcRoot) return {
+				ok: false,
+				error: "当前工作区不受 SVN 管理"
+			};
+			const hit = planInbox.get(status.wcRoot);
+			const since = Number(args.since) || 0;
+			if (!hit || hit.at < since || now() - hit.at > 18e5) return {
+				ok: true,
+				plan: null,
+				dropped: 0,
+				at: 0
+			};
+			return {
+				ok: true,
+				plan: hit.plan,
+				dropped: hit.dropped,
+				at: hit.at
+			};
+		},
 		"svn.wcRev": async (args) => {
 			const sc = await requireSvnSession(ctx, args.sessionId);
 			if ("err" in sc) return {
@@ -16428,6 +18198,20 @@ const inject = [
 	"agents"
 ];
 /**
+* 插件 Config schema（cordis 从 module 导出读 `plugin.Config` 做启动校验；
+* DSH 0.1.7 起设置页按此 schema 自动生成表单，设置值 = profile 插件配置）。
+* 字段集与 installOpenSettingsSection 的 section schema 同源（buildSettingsSchema），
+* 全字段带默认值——undefined/空配置经 schemastery 校验自动填充（rc/alpha 两代
+* cordis 均读该导出，实测 4.0.0-rc.8 与 0.1.7 行为一致，校验必过）。
+* volatile: true —— 0.1.7 的 SettingsForms.describe 只下发含 volatile 字段的 entry
+* （volatileForm 门槛），漏标则 ns 不出现 → client configForms 恒 unavailable →
+* 设置页「设置服务暂不可用」；同时 volatile 字段由 Loader 就地提交免重载。
+* 运行时解析：@deepseek-ai/schemastery 经插件自身 dependencies（link/dev/npm 安装
+* 三形态一致，钉 ~3.18.4 —— 3.18.1 起才有 .volatile()，低版本经 markVolatile 守卫降级）。
+* @author ddj 2026年09月22号（2026年09月23号 增补 volatile 标记）
+*/
+const Config = buildSettingsSchema(z, { volatile: true });
+/**
 * 装配插件：挂事件监听、注册路由、安装兼容层。
 * @author ddj 2026年08月20号
 * @param ctx DSH 上下文（sessions/fs/webServer 由 inject 提供；sandboxPolicy/subprocess 惰性获取）
@@ -16517,6 +18301,6 @@ async function logCompatSummary(ctx, warnings) {
 	}
 }
 //#endregion
-export { apply, inject, name };
+export { Config, apply, inject, name };
 
 //# sourceMappingURL=index.js.map