dsh-vscode-mode 0.2.0 → 0.3.0

package/lib/index.js

@@ -131,7 +131,8 @@ const KEYBINDING_DEFAULTS = {
 	"edrv.prevTab": "Ctrl+Alt+ArrowLeft|Ctrl+PageUp",
 	"edrv.showCommands": "Ctrl+Shift+P|F1",
 	"edrv.nextEditorRow": "Ctrl+Alt+ArrowDown",
-	"edrv.prevEditorRow": "Ctrl+Alt+ArrowUp"
+	"edrv.prevEditorRow": "Ctrl+Alt+ArrowUp",
+	"edrv.addSelectionRef": "Ctrl+U"
 };
 //#endregion
 //#region src/shared/integration.ts
@@ -3827,7 +3828,7 @@ async function restoreFile(ctx, session, rec) {
 /** 规则文件名白名单：字母数字开头，仅字母数字点横下划线，.mdc 后缀（天然拒绝路径分隔符）。 */
 const RULE_FILE_RE = /^[A-Za-z0-9][A-Za-z0-9._-]*\.mdc$/;
 /** Windows 保留设备名（防意外创建系统设备文件）。 */
-const RESERVED_NAME_RE = /^(con|prn|aux|nul|com[1-9]|lpt[1-9])(\..*)?$/i;
+const RESERVED_NAME_RE$1 = /^(con|prn|aux|nul|com[1-9]|lpt[1-9])(\..*)?$/i;
 /** 单目录最多加载的规则文件数（防失控目录拖垮装配）。 */
 const RULE_DIR_CAP = 200;
 /** 注入时单条规则正文字节上限（超出截断）。 */
@@ -3951,7 +3952,7 @@ function ruleTypeOf(parsed) {
 */
 function validateRuleFile(name) {
 	if (!RULE_FILE_RE.test(name)) return "文件名不合法：仅允许字母数字开头，含字母/数字/点/横线/下划线，.mdc 后缀";
-	if (RESERVED_NAME_RE.test(name)) return "文件名是 Windows 保留设备名，不允许";
+	if (RESERVED_NAME_RE$1.test(name)) return "文件名是 Windows 保留设备名，不允许";
 	return null;
 }
 /**
@@ -4063,24 +4064,24 @@ async function listRulesDir(dir, scope) {
 	return out;
 }
 /** 已注册 workspace 列表（项目 Tab 与写入校验共用）。 */
-function workspaceList(ctx) {
+function workspaceList$1(ctx) {
 	return (ctx.get("workspaceRegistry")?.list?.() ?? []).filter((item) => Boolean(item) && typeof item.path === "string" && item.path !== "");
 }
 /** 用户显式 GUI 写操作的策略：danger-full-access（照抄 mcpProject.fullPolicy）。 */
-function fullPolicy$1(ctx) {
+function fullPolicy$2(ctx) {
 	const svc = ctx.get("sandboxPolicy");
 	if (!svc || typeof svc.resolve !== "function") return void 0;
 	return svc.resolve({ mode: "danger-full-access" });
 }
 /** 校验项目作用域的 workspacePath 已注册为 DSH workspace（防 RPC 写任意目录）。 */
-function requireWorkspace$1(ctx, workspacePath) {
-	const workspace = workspaceList(ctx).find((item) => item.path === workspacePath);
+function requireWorkspace$2(ctx, workspacePath) {
+	const workspace = workspaceList$1(ctx).find((item) => item.path === workspacePath);
 	if (!workspace) throw new Error("项目未注册为 DSH workspace，不能管理项目规则");
 	return workspace;
 }
 /** 按作用域解析规则目录（project 先过 requireWorkspace）。 */
-function dirOf(ctx, scope, workspacePath) {
-	if (scope === "project") return projectRulesDir(requireWorkspace$1(ctx, workspacePath).path);
+function dirOf$1(ctx, scope, workspacePath) {
+	if (scope === "project") return projectRulesDir(requireWorkspace$2(ctx, workspacePath).path);
 	return userRulesDir();
 }
 /**
@@ -4092,7 +4093,7 @@ function dirOf(ctx, scope, workspacePath) {
 async function rulesList(ctx) {
 	const user = await listRulesDir(userRulesDir(), "user");
 	const projects = [];
-	for (const workspace of workspaceList(ctx)) {
+	for (const workspace of workspaceList$1(ctx)) {
 		const dir = projectRulesDir(workspace.path);
 		const exists = existsSync(dir);
 		const rules = exists ? await listRulesDir(dir, "project") : [];
@@ -4116,7 +4117,7 @@ async function rulesList(ctx) {
 * @returns 文件全文
 */
 async function rulesRead(ctx, ref) {
-	const dir = dirOf(ctx, ref.scope, ref.workspacePath);
+	const dir = dirOf$1(ctx, ref.scope, ref.workspacePath);
 	return readFile(join(dir, ref.file), "utf8");
 }
 /**
@@ -4155,15 +4156,15 @@ function toRuleInfo(scope, file, absPath, parsed, size, mtime) {
 async function rulesSave(ctx, input) {
 	const invalid = validateRuleFile(input.file);
 	if (invalid) throw new Error(invalid);
-	const dir = dirOf(ctx, input.scope, input.workspacePath);
+	const dir = dirOf$1(ctx, input.scope, input.workspacePath);
 	await mkdir(dir, { recursive: true });
 	const absPath = join(dir, input.file);
 	const content = String(input.content ?? "");
 	if (input.scope === "project") {
 		const fs = ctx.get("fs");
 		if (!fs) throw new Error("缺少 fs 服务");
-		const target = await fs.resolve(".dsh/rules/" + input.file, { cwd: requireWorkspace$1(ctx, input.workspacePath).path });
-		await fs.writeText(target, content, void 0, void 0, fullPolicy$1(ctx));
+		const target = await fs.resolve(".dsh/rules/" + input.file, { cwd: requireWorkspace$2(ctx, input.workspacePath).path });
+		await fs.writeText(target, content, void 0, void 0, fullPolicy$2(ctx));
 	} else await writeFile(absPath, content, "utf8");
 	const info = await stat(absPath).catch(() => null);
 	return toRuleInfo(input.scope, input.file, absPath, parseRuleMdc(content), info?.size ?? Buffer$1.byteLength(content), info?.mtimeMs ?? Date.now());
@@ -4174,7 +4175,7 @@ async function rulesSave(ctx, input) {
 * @param ref 作用域 + 文件名（+ 项目工作区）
 */
 async function rulesRemove(ctx, ref) {
-	const dir = dirOf(ctx, ref.scope, ref.workspacePath);
+	const dir = dirOf$1(ctx, ref.scope, ref.workspacePath);
 	await rm(join(dir, ref.file), { force: true });
 }
 /**
@@ -4185,7 +4186,7 @@ async function rulesRemove(ctx, ref) {
 * @returns 更新后的规则元信息
 */
 async function rulesToggle(ctx, ref, enabled) {
-	const dir = dirOf(ctx, ref.scope, ref.workspacePath);
+	const dir = dirOf$1(ctx, ref.scope, ref.workspacePath);
 	const absPath = join(dir, ref.file);
 	const text = await readRuleText(ctx, ref, absPath);
 	if (text === null) throw new Error("规则文件不存在：" + ref.file);
@@ -4199,7 +4200,7 @@ async function readRuleText(ctx, ref, absPath) {
 	if (ref.scope !== "project") return readFile(absPath, "utf8").catch(() => null);
 	const fs = ctx.get("fs");
 	if (!fs) throw new Error("缺少 fs 服务");
-	const target = await fs.resolve(".dsh/rules/" + ref.file, { cwd: requireWorkspace$1(ctx, ref.workspacePath).path });
+	const target = await fs.resolve(".dsh/rules/" + ref.file, { cwd: requireWorkspace$2(ctx, ref.workspacePath).path });
 	try {
 		return await fs.readText(target);
 	} catch {
@@ -4214,8 +4215,8 @@ async function rulesSaveContent(ctx, ref, absPath, content) {
 	}
 	const fs = ctx.get("fs");
 	if (!fs) throw new Error("缺少 fs 服务");
-	const target = await fs.resolve(".dsh/rules/" + ref.file, { cwd: requireWorkspace$1(ctx, ref.workspacePath).path });
-	await fs.writeText(target, content, void 0, void 0, fullPolicy$1(ctx));
+	const target = await fs.resolve(".dsh/rules/" + ref.file, { cwd: requireWorkspace$2(ctx, ref.workspacePath).path });
+	await fs.writeText(target, content, void 0, void 0, fullPolicy$2(ctx));
 }
 /** 重建单条规则元信息（toggle 后回传 UI；stat 失败时用内容长度 + 当前时间兜底）。 */
 async function ruleInfoOf(ref, absPath, content) {
@@ -4304,6 +4305,363 @@ function installRulesSection(ctx) {
 	return true;
 }
 //#endregion
+//#region src/snippets.ts
+/**
+* dsh-vscode-mode host — 代码片段管理（VS Code 兼容 .code-snippets 文件）。
+* - 存储：全局片段 ~/.dsh/snippets/*.code-snippets；项目片段 <工作区>/.dsh/snippets/*.code-snippets
+*   （随仓库共享）。文件名约定与 VS Code 一致：`<language>.code-snippets`（`global.code-snippets`
+*   表示全语言生效）。
+* - 格式：顶层对象 { "<片段名>": { prefix, body, description?, scope? } }；body 支持字符串或
+*   字符串数组（数组按行拼接）。解析容错：单文件 JSON 损坏只影响该文件（error 字段提示）。
+* - 生效：client 侧 Monaco completion provider 按 model 语言拉取 snippetsEntries 后过滤展开；
+*   与 rules.ts 同一套 IO 通道（user 走 node fs；project 走 ctx fs + danger-full-access）。
+* --region 划分：常量与目录定位 / JSON 解析（纯）/ 条目展开（纯）/ 文件名与模板（纯）/ IO
+* 作者 ddj 2026年09月10号
+*/
+/** 片段文件名白名单：字母数字开头，仅字母数字点横下划线，.code-snippets 后缀（天然拒绝路径分隔符）。 */
+const SNIPPET_FILE_RE = /^[A-Za-z0-9][A-Za-z0-9._-]*\.code-snippets$/;
+/** Windows 保留设备名（防意外创建系统设备文件）。 */
+const RESERVED_NAME_RE = /^(con|prn|aux|nul|com[1-9]|lpt[1-9])(\..*)?$/i;
+/** 单目录最多加载的片段文件数（防失控目录拖垮装配）。 */
+const SNIPPET_DIR_CAP = 200;
+/** 单条片段正文字节上限（超出截断，防超长片段撑爆补全载荷）。 */
+const SNIPPET_SINGLE_CAP = 16384;
+/**
+* 全局片段目录（~/.dsh/snippets）。
+* @author ddj 2026年09月10号
+* @param home DSH home（缺省自动解析）
+* @returns 绝对路径
+*/
+function userSnippetsDir(home = dshHome()) {
+	return join(home, "snippets");
+}
+/**
+* 项目片段目录（<工作区>/.dsh/snippets）。
+* @author ddj 2026年09月10号
+* @param workspacePath 工作区绝对路径
+* @returns 绝对路径
+*/
+function projectSnippetsDir(workspacePath) {
+	return join(workspacePath, ".dsh", "snippets");
+}
+/**
+* 判定绝对路径是否落在全局片段目录内（edrv.read / edrv.save 的片段分支依据）。
+* 归一化分隔符后按前缀比较；不在目录内返回 false。
+* @author ddj 2026年09月10号
+* @param path 待判定路径
+* @param home DSH home（缺省自动解析）
+* @returns 是否为全局片段文件
+*/
+function isSnippetFilePath(path, home = dshHome()) {
+	const raw = String(path ?? "");
+	if (!raw) return false;
+	return resolveSnippetPath(raw, userSnippetsDir(home)) !== null;
+}
+/**
+* 归一化并校验「路径是否位于 dir 直下」（拒绝 `..` 穿越与子目录）。
+* @author ddj 2026年09月10号
+* @param path 待判定路径
+* @param dir 目标目录
+* @returns 命中时返回归一化后的绝对路径（`/` 分隔）；否则 null
+*/
+function resolveSnippetPath(path, dir) {
+	const norm = (text) => String(text).replace(/\\/g, "/").replace(/\/+$/, "");
+	const target = norm(path);
+	const base = norm(dir);
+	if (!target.startsWith(base + "/")) return null;
+	const rest = target.slice(base.length + 1);
+	if (!rest || rest.includes("/")) return null;
+	return SNIPPET_FILE_RE.test(rest) ? target : null;
+}
+/**
+* 归一化片段正文：字符串原样；字符串数组按行拼接（VS Code 语义）。
+* @author ddj 2026年09月10号
+* @param raw body 原始值
+* @returns 正文文本；非法类型返回空串
+*/
+function normalizeBody(raw) {
+	if (typeof raw === "string") return raw;
+	if (Array.isArray(raw)) return raw.filter((line) => typeof line === "string").join("\n");
+	return "";
+}
+/**
+* 归一化片段前缀：字符串去空白；字符串数组取首项；其余为空串。
+* @author ddj 2026年09月10号
+* @param raw prefix 原始值
+* @returns 前缀文本
+*/
+function normalizePrefix(raw) {
+	if (typeof raw === "string") return raw.trim();
+	if (Array.isArray(raw)) {
+		const first = raw.find((item) => typeof item === "string");
+		return typeof first === "string" ? first.trim() : "";
+	}
+	return "";
+}
+/**
+* 归一化 scope：字符串或字符串数组，去空白并小写；其余为空数组（= 全语言）。
+* @author ddj 2026年09月10号
+* @param raw scope 原始值
+* @returns 语言 id 数组
+*/
+function normalizeScope(raw) {
+	return (Array.isArray(raw) ? raw : typeof raw === "string" ? [raw] : []).filter((item) => typeof item === "string").map((item) => item.trim().toLowerCase()).filter(Boolean);
+}
+/**
+* 容错解析一个 .code-snippets 文件：顶层须为对象，逐条归一化；单条非法即跳过。
+* 解析永不抛错（失败以 error 文案返回）。
+* @author ddj 2026年09月10号
+* @param text 文件全文
+* @returns 解析结果（entries 为片段名 → 已解析条目）
+*/
+function parseSnippetsJson(text) {
+	const trimmed = String(text ?? "").replace(/^\uFEFF/, "").trim();
+	if (!trimmed) return { entries: {} };
+	let data;
+	try {
+		data = JSON.parse(trimmed);
+	} catch (error) {
+		return {
+			entries: {},
+			error: "JSON 解析失败：" + String(error)
+		};
+	}
+	if (!data || typeof data !== "object" || Array.isArray(data)) return {
+		entries: {},
+		error: "顶层必须是对象（{ \"片段名\": { prefix, body } }）"
+	};
+	const entries = {};
+	for (const [key, value] of Object.entries(data)) {
+		if (!value || typeof value !== "object" || Array.isArray(value)) continue;
+		const raw = value;
+		const body = normalizeBody(raw.body);
+		if (!body) continue;
+		entries[key] = {
+			prefix: normalizePrefix(raw.prefix),
+			body: body.length > SNIPPET_SINGLE_CAP ? body.slice(0, SNIPPET_SINGLE_CAP) : body,
+			description: typeof raw.description === "string" ? raw.description : "",
+			scope: normalizeScope(raw.scope)
+		};
+	}
+	return { entries };
+}
+/**
+* 由文件名推导语言 id：`<language>.code-snippets` → language；`global`/无法识别返回空串。
+* @author ddj 2026年09月10号
+* @param file 片段文件名（含后缀）
+* @returns 语言 id（空串 = 全语言）
+*/
+function languageOfSnippetFile(file) {
+	const base = String(file ?? "").replace(/\.code-snippets$/i, "");
+	if (!base || base.toLowerCase() === "global") return "";
+	return base.toLowerCase();
+}
+/**
+* 把「一个文件的解析结果」展开为补全条目：文件语言与条目 scope 取交集。
+* 条目 scope 为空 → 跟随文件语言；文件语言为空（global）→ 该条目对全语言生效。
+* @author ddj 2026年09月10号
+* @param info 文件元信息
+* @param parsed 解析结果
+* @returns 条目数组（含来源信息）
+*/
+function entriesOfFile(info, parsed) {
+	const fileLanguage = info.language;
+	const out = [];
+	for (const [key, entry] of Object.entries(parsed.entries)) {
+		const languages = entry.scope.length ? entry.scope : [fileLanguage];
+		for (const language of languages) out.push({
+			key,
+			prefix: entry.prefix,
+			body: entry.body,
+			description: entry.description,
+			scope: info.scope,
+			file: info.file,
+			language
+		});
+	}
+	return out;
+}
+/**
+* 展开全部文件的条目（补全 provider 载荷）。
+* @author ddj 2026年09月10号
+* @param loaded 已加载的文件（元信息 + 解析结果）
+* @returns 条目数组（项目文件靠后，同 key 时项目覆盖全局）
+*/
+function flattenSnippetEntries(loaded) {
+	const out = [];
+	for (const item of loaded) out.push(...entriesOfFile(item.info, item.parsed));
+	return out;
+}
+/**
+* 校验片段文件名（白名单 + Windows 保留名拒绝）。
+* @author ddj 2026年09月10号
+* @param name 文件名（含后缀）
+* @returns 错误文案；null=合法
+*/
+function validateSnippetFile(name) {
+	if (!SNIPPET_FILE_RE.test(name)) return "文件名不合法：仅允许字母数字开头，含字母/数字/点/横线/下划线，.code-snippets 后缀";
+	if (RESERVED_NAME_RE.test(name)) return "文件名是 Windows 保留设备名，不允许";
+	return null;
+}
+/**
+* 组装片段文件元信息视图（列表与补全载荷共用）。
+* @author ddj 2026年09月10号
+* @param scope 作用域
+* @param file 文件名
+* @param absPath 绝对路径
+* @param parsed 解析结果
+* @param size 字节数
+* @param mtime 修改时间毫秒
+* @returns 片段文件元信息
+*/
+function toSnippetInfo(scope, file, absPath, parsed, size, mtime) {
+	return {
+		scope,
+		file,
+		absPath,
+		relHint: scope === "project" ? ".dsh/snippets/" : "snippets/",
+		language: languageOfSnippetFile(file),
+		count: Object.keys(parsed.entries).length,
+		size,
+		mtime,
+		error: parsed.error
+	};
+}
+/** 单目录片段文件列表（仅 *.code-snippets，最多 SNIPPET_DIR_CAP 个；目录缺失返回空）。 */
+async function listSnippetsDir(dir, scope) {
+	const files = (await readdir(dir).catch(() => [])).filter((name) => /\.code-snippets$/i.test(name)).sort().slice(0, SNIPPET_DIR_CAP);
+	const out = [];
+	for (const file of files) {
+		const absPath = join(dir, file);
+		const info = await stat(absPath).catch(() => null);
+		if (!info || !info.isFile()) continue;
+		const parsed = parseSnippetsJson(await readFile(absPath, "utf8").catch(() => ""));
+		out.push(toSnippetInfo(scope, file, absPath, parsed, info.size, info.mtimeMs));
+	}
+	return out;
+}
+/** 已注册 workspace 列表（项目页与写入校验共用）。 */
+function workspaceList(ctx) {
+	return (ctx.get("workspaceRegistry")?.list?.() ?? []).filter((item) => Boolean(item) && typeof item.path === "string" && item.path !== "");
+}
+/** 用户显式 GUI 写操作的策略：danger-full-access（照抄 rules.fullPolicy）。 */
+function fullPolicy$1(ctx) {
+	const svc = ctx.get("sandboxPolicy");
+	if (!svc || typeof svc.resolve !== "function") return void 0;
+	return svc.resolve({ mode: "danger-full-access" });
+}
+/**
+* 校验项目作用域的 workspacePath 已注册为 DSH workspace（防 RPC 写任意目录）。
+* @author ddj 2026年09月10号
+* @param ctx DSH 上下文
+* @param workspacePath 目标项目路径
+* @returns 命中的工作区项
+*/
+function requireWorkspace$1(ctx, workspacePath) {
+	const workspace = workspaceList(ctx).find((item) => item.path === workspacePath);
+	if (!workspace) throw new Error("项目未注册为 DSH workspace，不能管理项目片段");
+	return workspace;
+}
+/** 按作用域解析片段目录（project 先过 requireWorkspace）。 */
+function dirOf(ctx, scope, workspacePath) {
+	if (scope === "project") return projectSnippetsDir(requireWorkspace$1(ctx, workspacePath).path);
+	return userSnippetsDir();
+}
+/**
+* 片段文件总列表：全局片段 + 各已注册工作区的项目片段。
+* @author ddj 2026年09月10号
+* @param ctx DSH 上下文
+* @returns snippets.list 载荷
+*/
+async function snippetsList(ctx) {
+	const user = await listSnippetsDir(userSnippetsDir(), "user");
+	const projects = [];
+	for (const workspace of workspaceList(ctx)) {
+		const dir = projectSnippetsDir(workspace.path);
+		const exists = existsSync(dir);
+		const files = exists ? await listSnippetsDir(dir, "project") : [];
+		projects.push({
+			workspacePath: workspace.path,
+			title: workspace.title ?? "",
+			files,
+			missingDir: exists ? void 0 : true
+		});
+	}
+	return {
+		user,
+		projects
+	};
+}
+/**
+* 读取一个片段文件全文（编辑界面打开用）。
+* @author ddj 2026年09月10号
+* @param ctx DSH 上下文
+* @param ref 作用域 + 文件名（+ 项目工作区）
+* @returns 文件全文
+*/
+async function snippetsRead(ctx, ref) {
+	const dir = dirOf(ctx, ref.scope, ref.workspacePath);
+	return readFile(join(dir, ref.file), "utf8");
+}
+/**
+* 保存（新建或覆盖）一个片段文件：project 作用域写盘走 ctx fs + danger-full-access（镜像 rules）。
+* @author ddj 2026年09月10号
+* @param ctx DSH 上下文
+* @param input 保存入参
+* @returns 保存后的片段文件元信息
+*/
+async function snippetsSave(ctx, input) {
+	const invalid = validateSnippetFile(input.file);
+	if (invalid) throw new Error(invalid);
+	const dir = dirOf(ctx, input.scope, input.workspacePath);
+	await mkdir(dir, { recursive: true });
+	const absPath = join(dir, input.file);
+	const content = String(input.content ?? "");
+	if (input.scope === "project") {
+		const fs = ctx.get("fs");
+		if (!fs) throw new Error("缺少 fs 服务");
+		const target = await fs.resolve(".dsh/snippets/" + input.file, { cwd: requireWorkspace$1(ctx, input.workspacePath).path });
+		await fs.writeText(target, content, void 0, void 0, fullPolicy$1(ctx));
+	} else await writeFile(absPath, content, "utf8");
+	const info = await stat(absPath).catch(() => null);
+	return toSnippetInfo(input.scope, input.file, absPath, parseSnippetsJson(content), info?.size ?? Buffer$1.byteLength(content), info?.mtimeMs ?? Date.now());
+}
+/**
+* 删除一个片段文件（project 作用域同样先过 workspace 注册校验）。
+* @author ddj 2026年09月10号
+* @param ctx DSH 上下文
+* @param ref 作用域 + 文件名（+ 项目工作区）
+*/
+async function snippetsRemove(ctx, ref) {
+	const dir = dirOf(ctx, ref.scope, ref.workspacePath);
+	await rm(join(dir, ref.file), { force: true });
+}
+/**
+* 补全 provider 载荷：全局片段 + 指定工作区项目片段的全部条目。
+* 项目条目排在全局之后（同 key 时后出现的项目条目在 client 侧优先）。
+* @author ddj 2026年09月10号
+* @param ctx DSH 上下文
+* @param workspacePath 当前会话工作区（可选；未注册则仅全局片段）
+* @returns snippets.entries 载荷
+*/
+async function snippetsEntries(ctx, workspacePath) {
+	const loaded = [];
+	const load = async (dir, scope) => {
+		for (const info of await listSnippetsDir(dir, scope)) {
+			const parsed = parseSnippetsJson(await readFile(info.absPath, "utf8").catch(() => ""));
+			if (parsed.error) continue;
+			loaded.push({
+				info,
+				parsed
+			});
+		}
+	};
+	await load(userSnippetsDir(), "user");
+	const registered = workspaceList(ctx).some((item) => item.path === workspacePath);
+	if (workspacePath && registered) await load(projectSnippetsDir(workspacePath), "project");
+	return { entries: flattenSnippetEntries(loaded) };
+}
+//#endregion
 //#region src/mcpProject.ts
 /**
 * dsh-vscode-mode host — 项目级 MCP 管理。
@@ -6136,6 +6494,16 @@ async function requireSession(ctx, sessionId) {
 	};
 }
 /**
+* 片段文件路径解析：命中全局片段目录（~/.dsh/snippets）返回归一化绝对路径，否则 null。
+* 全局片段位于工作区之外，edrv.read / edrv.save 需绕开 resolveTarget 的 cwd 语义直读直写。
+* @author ddj 2026年09月10号
+* @param path 客户端请求路径（绝对路径）
+* @returns 归一化后的绝对路径或 null
+*/
+function snippetTargetOf(path) {
+	return isSnippetFilePath(path) ? path.replace(/\\/g, "/") : null;
+}
+/**
 * 手动保存收尾（edrv.save / edrv.saveBinary 共用）：目录树失效 + 该路径 pending
 * 文本差异记录标记 superseded 并归档（旧文本 diff 不得再应用到新内容上）。
 * @author ddj 2026年09月22号
@@ -6322,6 +6690,21 @@ function buildHandlers(ctx, registry, searcher = newSearcher(ctx), contentSearch
 			};
 		},
 		"edrv.read": async (args) => {
+			const snippetTarget = snippetTargetOf(args.path);
+			if (snippetTarget && args.encoding !== "base64") try {
+				const content = await readFile(snippetTarget, "utf8");
+				return {
+					ok: true,
+					content,
+					size: content.length
+				};
+			} catch (error) {
+				return {
+					ok: false,
+					error: "读取片段文件失败：" + String(error),
+					resolvedPath: snippetTarget
+				};
+			}
 			const sc = await requireSession(ctx, args.sessionId);
 			if ("err" in sc) return {
 				ok: false,
@@ -6425,6 +6808,16 @@ function buildHandlers(ctx, registry, searcher = newSearcher(ctx), contentSearch
 			}
 		},
 		"edrv.save": async (args) => {
+			const snippetTarget = snippetTargetOf(args.path);
+			if (snippetTarget) try {
+				await writeFile(snippetTarget, args.content, "utf8");
+				return { ok: true };
+			} catch (error) {
+				return {
+					ok: false,
+					error: "保存片段文件失败：" + String(error)
+				};
+			}
 			const sc = await requireSession(ctx, args.sessionId);
 			if ("err" in sc) return {
 				ok: false,
@@ -7297,6 +7690,70 @@ function buildHandlers(ctx, registry, searcher = newSearcher(ctx), contentSearch
 					error: "切换规则失败：" + String(error)
 				};
 			}
+		},
+		"snippets.list": async () => {
+			try {
+				return {
+					ok: true,
+					...await snippetsList(ctx)
+				};
+			} catch (error) {
+				return {
+					ok: false,
+					error: "读取代码片段失败：" + String(error)
+				};
+			}
+		},
+		"snippets.read": async (args) => {
+			try {
+				return {
+					ok: true,
+					content: await snippetsRead(ctx, args)
+				};
+			} catch (error) {
+				return {
+					ok: false,
+					error: "读取代码片段失败：" + String(error)
+				};
+			}
+		},
+		"snippets.save": async (args) => {
+			try {
+				return {
+					ok: true,
+					file: await snippetsSave(ctx, args)
+				};
+			} catch (error) {
+				return {
+					ok: false,
+					error: "保存代码片段失败：" + String(error)
+				};
+			}
+		},
+		"snippets.remove": async (args) => {
+			try {
+				await snippetsRemove(ctx, args);
+				return { ok: true };
+			} catch (error) {
+				return {
+					ok: false,
+					error: "删除代码片段失败：" + String(error)
+				};
+			}
+		},
+		"snippets.entries": async (args) => {
+			try {
+				const sc = await requireSession(ctx, args.sessionId);
+				return {
+					ok: true,
+					...await snippetsEntries(ctx, "err" in sc ? void 0 : sc.cwd)
+				};
+			} catch (error) {
+				return {
+					ok: false,
+					error: "读取代码片段条目失败：" + String(error)
+				};
+			}
 		}
 	};
 }