dsh-vscode-mode 0.2.0 → 0.3.0

package/src/shared/rpc.ts

@@ -16,6 +16,7 @@ import type { MpcConfig, MpcProject, MpcProjectSaveInput, MpcServer } from './mc
 import type { CompatReport, DevFormInfo } from './compat.js'
 import type { ShellIntegrationStatus, UnityListPayload, UnityProjectEntry } from './integration.js'
 import type { RuleInfo, RuleProject, RuleRefInput, RuleSaveInput } from './rules.js'
+import type { SnippetEntry, SnippetInfo, SnippetProject, SnippetRefInput, SnippetSaveInput } from './snippets.js'
 import type { LspEnvInstallState, LspExtInfo, LspExtUpdate, LspHover, LspLocation, LspMarketItem, LspPosition, LspSemanticTokens, LspServerStatus, LspSymbol } from './lsp.js'
 import type { AiConfigPatch, AiConfigView, AiDirectoryView, AiInlineRequest, AiInlineResult } from './ai.js'
 
@@ -236,6 +237,11 @@ export interface RpcRequestMap {
   'rules.save': RuleSaveInput
   'rules.remove': RuleRefInput
   'rules.toggle': RuleRefInput & { enabled: boolean }
+  'snippets.list': {}
+  'snippets.read': SnippetRefInput
+  'snippets.save': SnippetSaveInput
+  'snippets.remove': SnippetRefInput
+  'snippets.entries': { sessionId?: string }
 }
 
 export type RpcMethod = keyof RpcRequestMap
@@ -324,6 +330,11 @@ export interface RpcOkMap {
   'rules.save': { rule: RuleInfo }
   'rules.remove': object
   'rules.toggle': { rule: RuleInfo }
+  'snippets.list': { user: SnippetInfo[]; projects: SnippetProject[] }
+  'snippets.read': { content: string }
+  'snippets.save': { file: SnippetInfo }
+  'snippets.remove': object
+  'snippets.entries': { entries: SnippetEntry[] }
 }
 
 /** 统一响应：{ok:true, ...payload} 或 {ok:false, error}。 */

package/src/shared/snippets.ts

@@ -0,0 +1,156 @@
+/**
+ * dsh-vscode-mode 代码片段共享数据契约（VS Code 兼容 .code-snippets 文件）。
+ * 纯类型模块：禁 node/react 导入（与 shared/rules.ts 同约束）。
+ * 文件格式与 VS Code 一致：顶层对象 { "<片段名>": { prefix, body, description?, scope? } }，
+ * body 可为字符串或字符串数组（数组按行拼接）；scope 为语言 id 或语言 id 数组。
+ * 作者 ddj 2026年09月10号
+ */
+
+/** 片段作用域：全局片段（~/.dsh/snippets）或项目片段（<工作区>/.dsh/snippets）。 */
+export type SnippetScope = 'user' | 'project'
+
+/** 一个 .code-snippets 文件的元信息（列表行展示 + 补全索引所需的最小集）。 */
+export interface SnippetInfo {
+  scope: SnippetScope
+  /** 文件名（含 .code-snippets 后缀，不含路径）。 */
+  file: string
+  /** 绝对路径（host 解析，供展示与在编辑界面打开）。 */
+  absPath: string
+  /** 相对提示（用户层 snippets/ 或项目层 .dsh/snippets/）。 */
+  relHint: string
+  /** 由文件名推导的语言 id（`global`/无法识别为空串 = 全语言生效）。 */
+  language: string
+  /** 文件内片段条目数（解析失败为 0）。 */
+  count: number
+  /** 文件字节数（列表排序/超大提示用）。 */
+  size: number
+  /** 修改时间毫秒。 */
+  mtime: number
+  /** JSON 解析失败文案（仅 UI 提示，不影响其他文件）。 */
+  error?: string
+}
+
+/** 一个工作区的项目片段聚合（snippets.list 的 projects 项）。 */
+export interface SnippetProject {
+  workspacePath: string
+  title: string
+  files: SnippetInfo[]
+  /** 工作区目录不存在或无片段目录时为 true（UI 显示空态而非报错）。 */
+  missingDir?: boolean
+}
+
+/** 片段文件读取/删除入参公共字段。 */
+export interface SnippetRefInput {
+  scope: SnippetScope
+  /** project 必填：目标工作区绝对路径（须为 DSH 已注册 workspace）。 */
+  workspacePath?: string
+  file: string
+}
+
+/** 片段文件保存入参：content 为完整 JSON 文本（host 原样写盘）。 */
+export interface SnippetSaveInput {
+  scope: SnippetScope
+  workspacePath?: string
+  file: string
+  content: string
+}
+
+/** 一条已展开的片段条目（补全 provider 与插入命令共用）。 */
+export interface SnippetEntry {
+  /** 片段名（对象键，补全候选的 label）。 */
+  key: string
+  /** 触发前缀（VS Code prefix；空串表示仅靠描述/手动插入）。 */
+  prefix: string
+  /** 展开正文（已按数组形式拼接为含换行的字符串）。 */
+  body: string
+  /** 片段描述（补全候选的说明，缺省为空串）。 */
+  description: string
+  scope: SnippetScope
+  /** 来源文件名（补全候选 detail 展示）。 */
+  file: string
+  /** 生效语言 id（空串 = 全语言）。 */
+  language: string
+}
+
+// --region 文件名与模板（纯函数：host 与 client 共用，避免两处漂移）
+/** 全语言生效的文件名（无语言前缀）。 */
+export const SNIPPET_GLOBAL_FILE = 'global.code-snippets'
+/** 片段文件后缀。 */
+export const SNIPPET_EXT = '.code-snippets'
+
+/**
+ * 语言 id → 默认片段文件名（空语言回退 global）。
+ * @author ddj 2026年09月10号
+ * @param language 语言 id
+ * @returns 文件名（如 `lua.code-snippets`）
+ */
+export function snippetFileNameFor(language: string): string {
+  const lang = String(language ?? '').trim().toLowerCase()
+  return (lang || 'global') + SNIPPET_EXT
+}
+
+/**
+ * 归一化新建文件名：用户输入可为裸语言名（补后缀）或完整文件名；空输入为空串。
+ * @author ddj 2026年09月10号
+ * @param raw 用户输入
+ * @returns 归一化后的文件名
+ */
+export function normalizeSnippetFileName(raw: string): string {
+  const text = String(raw ?? '').trim()
+  if (!text) return ''
+  return text.toLowerCase().endsWith(SNIPPET_EXT) ? text : text + SNIPPET_EXT
+}
+
+/**
+ * 新建片段文件模板（一条示例，改 body 即可用）。
+ * @author ddj 2026年09月10号
+ * @param language 目标语言 id（空串 = 全局）
+ * @returns JSON 文本（带尾换行）
+ */
+export function snippetFileTemplate(language: string): string {
+  const lang = String(language ?? '').trim().toLowerCase()
+  const sample = (lang || 'global') + ' 示例片段'
+  return JSON.stringify({
+    [sample]: {
+      prefix: 'hello',
+      body: ['// ' + (lang || 'global') + ' 片段示例', '$1'],
+      description: '示例：输入 hello 后 Tab 展开',
+    },
+  }, null, 2) + '\n'
+}
+
+/**
+ * 可绑定语言目录（新建片段时的语言下拉来源；与 client/monaco/loader 的 LANG_BY_EXT
+ * 取值集合保持一致）。此处冗余一份纯数据，使本模块不依赖浏览器端 Monaco
+ * （shared 禁 import client 侧模块）；一致性由 tests/snippetLanguage.test.ts 断言兜底。
+ */
+export const SNIPPET_LANGUAGES: readonly string[] = [
+  'c', 'cpp', 'csharp', 'css', 'dart', 'dockerfile', 'go', 'html', 'ini', 'java',
+  'javascript', 'json', 'jsonc', 'kotlin', 'less', 'lua', 'markdown', 'mdx', 'php',
+  'plaintext', 'powershell', 'python', 'ruby', 'rust', 'scss', 'shell', 'sql',
+  'swift', 'typescript', 'xml', 'yaml',
+]
+
+/** 语言 id → 展示名（仅收录写法与 id 明显不同的；未收录的原样返回）。 */
+const LANGUAGE_LABELS: Record<string, string> = {
+  cpp: 'C++',
+  csharp: 'C#',
+  javascript: 'JavaScript',
+  typescript: 'TypeScript',
+  jsonc: 'JSON with Comments',
+  powershell: 'PowerShell',
+  plaintext: '纯文本',
+}
+
+/**
+ * 语言 id 的人类可读名（用于下拉与「新建 xx 代码片段文件」文案）。
+ * @author ddj 2026年09月10号
+ * @param id 语言 id（空串表示全语言）
+ * @returns 展示名
+ */
+export function languageLabelOf(id: string): string {
+  const key = String(id ?? '').trim().toLowerCase()
+  if (!key) return '全语言'
+  return LANGUAGE_LABELS[key] ?? key
+}
+// --endregion

package/src/snippets.ts

@@ -0,0 +1,427 @@
+/**
+ * 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号
+ */
+import { existsSync } from 'node:fs'
+import { mkdir, readFile, readdir, rm, stat, writeFile } from 'node:fs/promises'
+import { Buffer } from 'node:buffer'
+import { join } from 'node:path'
+import { dshHome } from './paths.js'
+import type {
+  SnippetEntry,
+  SnippetInfo,
+  SnippetProject,
+  SnippetRefInput,
+  SnippetSaveInput,
+  SnippetScope,
+} from './shared/snippets.js'
+import type { Ctx } from './store.js'
+
+/** 文件名与模板的纯函数定义在 shared（host 与 client 共用，避免两处漂移），此处透传便于 host 调用方单点导入。 */
+export { normalizeSnippetFileName, snippetFileTemplate } from './shared/snippets.js'
+
+// --region 常量与目录定位
+/** 片段文件名白名单：字母数字开头，仅字母数字点横下划线，.code-snippets 后缀（天然拒绝路径分隔符）。 */
+export 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 = 16 * 1024
+
+/**
+ * 全局片段目录（~/.dsh/snippets）。
+ * @author ddj 2026年09月10号
+ * @param home DSH home（缺省自动解析）
+ * @returns 绝对路径
+ */
+export function userSnippetsDir(home = dshHome()): string {
+  return join(home, 'snippets')
+}
+
+/**
+ * 项目片段目录（<工作区>/.dsh/snippets）。
+ * @author ddj 2026年09月10号
+ * @param workspacePath 工作区绝对路径
+ * @returns 绝对路径
+ */
+export function projectSnippetsDir(workspacePath: string): string {
+  return join(workspacePath, '.dsh', 'snippets')
+}
+
+/**
+ * 判定绝对路径是否落在全局片段目录内（edrv.read / edrv.save 的片段分支依据）。
+ * 归一化分隔符后按前缀比较；不在目录内返回 false。
+ * @author ddj 2026年09月10号
+ * @param path 待判定路径
+ * @param home DSH home（缺省自动解析）
+ * @returns 是否为全局片段文件
+ */
+export function isSnippetFilePath(path: string, home = dshHome()): boolean {
+  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: string, dir: string): string | null {
+  const norm = (text: string): string => 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
+}
+// --endregion
+
+// --region JSON 解析（纯函数）
+/** 一条片段的原始 JSON 声明（宽容：字段可能缺失或类型不符）。 */
+interface RawSnippet {
+  prefix?: unknown
+  body?: unknown
+  description?: unknown
+  scope?: unknown
+}
+
+/** parseSnippetsJson 的产出：条目映射 + 可选解析错误。 */
+export interface ParsedSnippets {
+  entries: Record<string, ParsedEntry>
+  error?: string
+}
+
+/** 已解析的单条片段（正文已归一为字符串）。 */
+export interface ParsedEntry {
+  prefix: string
+  body: string
+  description: string
+  scope: string[]
+}
+
+/**
+ * 归一化片段正文：字符串原样；字符串数组按行拼接（VS Code 语义）。
+ * @author ddj 2026年09月10号
+ * @param raw body 原始值
+ * @returns 正文文本；非法类型返回空串
+ */
+export function normalizeBody(raw: unknown): string {
+  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 前缀文本
+ */
+export function normalizePrefix(raw: unknown): string {
+  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 数组
+ */
+export function normalizeScope(raw: unknown): string[] {
+  const list = Array.isArray(raw) ? raw : typeof raw === 'string' ? [raw] : []
+  return list
+    .filter((item): item is string => typeof item === 'string')
+    .map((item) => item.trim().toLowerCase())
+    .filter(Boolean)
+}
+
+/**
+ * 容错解析一个 .code-snippets 文件：顶层须为对象，逐条归一化；单条非法即跳过。
+ * 解析永不抛错（失败以 error 文案返回）。
+ * @author ddj 2026年09月10号
+ * @param text 文件全文
+ * @returns 解析结果（entries 为片段名 → 已解析条目）
+ */
+export function parseSnippetsJson(text: string): ParsedSnippets {
+  const trimmed = String(text ?? '').replace(/^\uFEFF/, '').trim()
+  if (!trimmed) return { entries: {} }
+  let data: unknown
+  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: Record<string, ParsedEntry> = {}
+  for (const [key, value] of Object.entries(data as Record<string, unknown>)) {
+    if (!value || typeof value !== 'object' || Array.isArray(value)) continue
+    const raw = value as RawSnippet
+    const body = normalizeBody(raw.body)
+    if (!body) continue // body 缺失/非法：该条静默跳过（不污染整体）
+    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 }
+}
+// --endregion
+
+// --region 条目展开（纯函数）
+/**
+ * 由文件名推导语言 id：`<language>.code-snippets` → language；`global`/无法识别返回空串。
+ * @author ddj 2026年09月10号
+ * @param file 片段文件名（含后缀）
+ * @returns 语言 id（空串 = 全语言）
+ */
+export function languageOfSnippetFile(file: string): string {
+  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 条目数组（含来源信息）
+ */
+export function entriesOfFile(info: SnippetInfo, parsed: ParsedSnippets): SnippetEntry[] {
+  const fileLanguage = info.language
+  const out: SnippetEntry[] = []
+  for (const [key, entry] of Object.entries(parsed.entries)) {
+    // 条目 scope 覆盖文件语言：有 scope 时按 scope，无 scope 时继承文件语言（空=全语言）
+    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 时项目覆盖全局）
+ */
+export function flattenSnippetEntries(loaded: Array<{ info: SnippetInfo; parsed: ParsedSnippets }>): SnippetEntry[] {
+  const out: SnippetEntry[] = []
+  for (const item of loaded) out.push(...entriesOfFile(item.info, item.parsed))
+  return out
+}
+// --endregion
+
+// --region 文件名与模板（纯函数）
+/**
+ * 校验片段文件名（白名单 + Windows 保留名拒绝）。
+ * @author ddj 2026年09月10号
+ * @param name 文件名（含后缀）
+ * @returns 错误文案；null=合法
+ */
+export function validateSnippetFile(name: string): string | null {
+  if (!SNIPPET_FILE_RE.test(name)) return '文件名不合法：仅允许字母数字开头，含字母/数字/点/横线/下划线，.code-snippets 后缀'
+  if (RESERVED_NAME_RE.test(name)) return '文件名是 Windows 保留设备名，不允许'
+  return null
+}
+// --endregion
+
+// --region IO（列表 / 读 / 存 / 删 / 条目）
+/**
+ * 组装片段文件元信息视图（列表与补全载荷共用）。
+ * @author ddj 2026年09月10号
+ * @param scope 作用域
+ * @param file 文件名
+ * @param absPath 绝对路径
+ * @param parsed 解析结果
+ * @param size 字节数
+ * @param mtime 修改时间毫秒
+ * @returns 片段文件元信息
+ */
+function toSnippetInfo(scope: SnippetScope, file: string, absPath: string, parsed: ParsedSnippets, size: number, mtime: number): SnippetInfo {
+  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: string, scope: SnippetScope): Promise<SnippetInfo[]> {
+  const names = await readdir(dir).catch(() => [] as string[])
+  const files = names.filter((name) => /\.code-snippets$/i.test(name)).sort().slice(0, SNIPPET_DIR_CAP)
+  const out: SnippetInfo[] = []
+  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: Ctx): Array<{ path: string; title?: string }> {
+  const list = ctx.get('workspaceRegistry')?.list?.() ?? []
+  return (list as Array<{ path?: string; title?: string }>).filter(
+    (item): item is { path: string; title?: string } => Boolean(item) && typeof item.path === 'string' && item.path !== '',
+  )
+}
+
+/** 用户显式 GUI 写操作的策略：danger-full-access（照抄 rules.fullPolicy）。 */
+function fullPolicy(ctx: Ctx): unknown {
+  const svc = ctx.get('sandboxPolicy')
+  if (!svc || typeof svc.resolve !== 'function') return undefined
+  return svc.resolve({ mode: 'danger-full-access' })
+}
+
+/**
+ * 校验项目作用域的 workspacePath 已注册为 DSH workspace（防 RPC 写任意目录）。
+ * @author ddj 2026年09月10号
+ * @param ctx DSH 上下文
+ * @param workspacePath 目标项目路径
+ * @returns 命中的工作区项
+ */
+function requireWorkspace(ctx: Ctx, workspacePath: string | undefined): { path: string; title?: string } {
+  const workspace = workspaceList(ctx).find((item) => item.path === workspacePath)
+  if (!workspace) throw new Error('项目未注册为 DSH workspace，不能管理项目片段')
+  return workspace as { path: string; title?: string }
+}
+
+/** 按作用域解析片段目录（project 先过 requireWorkspace）。 */
+function dirOf(ctx: Ctx, scope: SnippetScope, workspacePath?: string): string {
+  if (scope === 'project') return projectSnippetsDir(requireWorkspace(ctx, workspacePath).path)
+  return userSnippetsDir()
+}
+
+/**
+ * 片段文件总列表：全局片段 + 各已注册工作区的项目片段。
+ * @author ddj 2026年09月10号
+ * @param ctx DSH 上下文
+ * @returns snippets.list 载荷
+ */
+export async function snippetsList(ctx: Ctx): Promise<{ user: SnippetInfo[]; projects: SnippetProject[] }> {
+  const user = await listSnippetsDir(userSnippetsDir(), 'user')
+  const projects: SnippetProject[] = []
+  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 ? undefined : true })
+  }
+  return { user, projects }
+}
+
+/**
+ * 读取一个片段文件全文（编辑界面打开用）。
+ * @author ddj 2026年09月10号
+ * @param ctx DSH 上下文
+ * @param ref 作用域 + 文件名（+ 项目工作区）
+ * @returns 文件全文
+ */
+export async function snippetsRead(ctx: Ctx, ref: SnippetRefInput): Promise<string> {
+  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 保存后的片段文件元信息
+ */
+export async function snippetsSave(ctx: Ctx, input: SnippetSaveInput): Promise<SnippetInfo> {
+  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(ctx, input.workspacePath).path })
+    await fs.writeText(target, content, void 0, void 0, fullPolicy(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.byteLength(content), info?.mtimeMs ?? Date.now())
+}
+
+/**
+ * 删除一个片段文件（project 作用域同样先过 workspace 注册校验）。
+ * @author ddj 2026年09月10号
+ * @param ctx DSH 上下文
+ * @param ref 作用域 + 文件名（+ 项目工作区）
+ */
+export async function snippetsRemove(ctx: Ctx, ref: SnippetRefInput): Promise<void> {
+  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 载荷
+ */
+export async function snippetsEntries(ctx: Ctx, workspacePath?: string): Promise<{ entries: SnippetEntry[] }> {
+  const loaded: Array<{ info: SnippetInfo; parsed: ParsedSnippets }> = []
+  const load = async (dir: string, scope: SnippetScope): Promise<void> => {
+    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