dsh-obsidian-memo 0.16.3

package/lib/config-picker.js

@@ -0,0 +1,29 @@
+/** 原生 JSON 文件选择；目录选择仍使用 DSH 的 directoryPickerController。 */
+import { execFile } from 'node:child_process'
+import { failure } from './files.js'
+
+let pickerOverride = null
+export function setConfigFilePickerForTests(picker) { pickerOverride = picker }
+
+export function configFilePickerCommand(platform = process.platform) {
+  if (platform === 'darwin') return { command: '/usr/bin/osascript', args: ['-e',
+    'try\nreturn POSIX path of (choose file with prompt "选择 JSON 配置文件" of type {"json"})\non error number -128\nreturn ""\nend try'] }
+  if (platform === 'win32') {
+    const script = '[Console]::OutputEncoding=[Text.UTF8Encoding]::new(); Add-Type -AssemblyName System.Windows.Forms; $picker=New-Object System.Windows.Forms.OpenFileDialog; $picker.Title="Select JSON configuration"; $picker.Filter="JSON (*.json)|*.json"; $picker.Multiselect=$false; try { if ($picker.ShowDialog() -eq [System.Windows.Forms.DialogResult]::OK) { [Console]::Write($picker.FileName) } } finally { $picker.Dispose() }'
+    return { command: 'powershell.exe', args: ['-NoProfile', '-STA', '-EncodedCommand', Buffer.from(script, 'utf16le').toString('base64')] }
+  }
+  return { command: 'zenity', args: ['--file-selection', '--title=Select JSON configuration', '--file-filter=JSON | *.json'] }
+}
+
+export function pickConfigFile({ platform = process.platform, exec = execFile } = {}) {
+  if (pickerOverride) return Promise.resolve().then(pickerOverride)
+  const { command, args } = configFilePickerCommand(platform)
+  return new Promise((resolve, reject) => {
+    exec(command, args, { timeout: 10 * 60 * 1000, windowsHide: true, encoding: 'utf8' }, (error, stdout) => {
+      // Zenity 用 exit 1 表示取消；macOS / Windows 的取消返回空输出。
+      if (error && platform !== 'darwin' && platform !== 'win32' && error.code === 1) return resolve(null)
+      if (error) return reject(failure('picker-unavailable', '文件选择失败：' + error.message, error))
+      resolve(String(stdout || '').trim() || null)
+    })
+  })
+}

package/lib/filename.js

@@ -0,0 +1,33 @@
+/**
+ * 便签文件名的唯一规范化入口：新建（capture）与编辑改名（saveNote）共用同一套规则。
+ * 只处理文件名本体（不含 .md），不负责路径边界与重名检查。
+ * @module dsh-obsidian-memo/filename
+ */
+
+import { LIMITS } from './shared.js'
+
+// 路径分隔符 / Windows 保留字符 / Markdown 链接特殊字符 / C0 控制符 / 零宽与双向控制符 / BOM。
+const INVALID_NAME_CHARS = /[\\/:*?"<>|#^[\]\x00-\x1f\x7f\u200b-\u200f\u202a-\u202e\u2060-\u206f\ufeff]/g
+// Windows 会忽略基础名尾随空格并截断扩展名；这里按第一个点前的基础名判断。
+const WINDOWS_RESERVED = /^(?:CON|PRN|AUX|NUL|COM[0-9]|LPT[0-9])$/
+
+/**
+ * 规范化便签文件名。
+ * @param {unknown} raw - 用户输入（可含扩展名、空白、控制字符）。
+ * @param {number} [maxBytes] - UTF-8 字节上限，默认 `LIMITS.noteNameBytes`。
+ * @returns {{ name: string, error: 'empty' | 'reserved' | 'too-long' | null }}
+ */
+export function sanitizeNoteFileName(raw, maxBytes = LIMITS.noteNameBytes) {
+  let name = String(raw ?? '')
+    .normalize('NFC')
+    .replace(INVALID_NAME_CHARS, ' ')
+    .replace(/\s+/g, ' ')
+    .trim()
+  // 先 trim 再删首尾点/空格，避免 " .foo" 变成隐藏文件 " .foo"。
+  name = name.replace(/^\.+/, '').replace(/[. ]+$/, '').trim()
+  if (name === '') return { name, error: 'empty' }
+  const base = name.split('.')[0].trim().toUpperCase()
+  if (WINDOWS_RESERVED.test(base)) return { name, error: 'reserved' }
+  if (Buffer.byteLength(name, 'utf8') > maxBytes) return { name, error: 'too-long' }
+  return { name, error: null }
+}

package/lib/files.js

@@ -0,0 +1,88 @@
+/** 文件边界与写入原语；所有 Host 入口共用同一套真实路径规则。 */
+import { createHash, randomUUID } from 'node:crypto'
+import { constants } from 'node:fs'
+import { copyFile, link, lstat, readFile, realpath, rename, stat, unlink, writeFile } from 'node:fs/promises'
+import { basename, dirname, isAbsolute, join, relative, resolve, sep } from 'node:path'
+import { LIMITS } from './shared.js'
+
+export function failure(code, message, cause) {
+  return Object.assign(new Error(message), { code, ...(cause === undefined ? {} : { cause }) })
+}
+
+export function isInside(root, target) {
+  const rel = relative(root, target)
+  return rel === '' || (rel !== '..' && !rel.startsWith(`..${sep}`) && !isAbsolute(rel))
+}
+
+/** 是否落在仓库内的隐藏路径（Obsidian 不索引以 . 开头的目录/文件，如 .obsidian / .trash）。 */
+export function isHiddenVaultPath(root, target) {
+  const rel = relative(resolve(root), resolve(target))
+  if (rel === '' || isAbsolute(rel) || rel === '..' || rel.startsWith(`..${sep}`)) return false
+  return rel.split(sep).some((segment) => segment.startsWith('.'))
+}
+
+/** 新建路径按最近的已有父目录解析；悬空符号链接不能当作尚未创建的目录。 */
+async function realLocation(target, allowMissing) {
+  try {
+    return await realpath(target)
+  } catch (error) {
+    if (!allowMissing || error.code !== 'ENOENT') throw error
+    const entry = await lstat(target).catch((cause) => {
+      if (cause.code !== 'ENOENT') throw cause
+      return null
+    })
+    if (entry !== null) throw failure('bad-request', `路径无法解析：${target}`)
+    const parent = dirname(target)
+    if (parent === target) throw error
+    return join(await realLocation(parent, true), basename(target))
+  }
+}
+
+/** 同时限制用户路径与真实位置，返回真实位置供读取/扩展名检查使用。 */
+export async function assertPathWithin(root, target, { allowMissing = false } = {}) {
+  const absolute = resolve(target)
+  if (!isInside(resolve(root), absolute)) throw failure('bad-request', `路径必须在配置目录内：${target}`)
+  let rootReal, targetReal
+  try {
+    ;[rootReal, targetReal] = await Promise.all([realpath(root), realLocation(absolute, allowMissing)])
+  } catch (error) {
+    if (error.code === 'bad-request') throw error
+    throw failure('not-found', `路径不存在或无法读取：${target}`, error)
+  }
+  if (!isInside(rootReal, targetReal)) throw failure('bad-request', `路径符号链接指向了配置目录之外：${target}`)
+  return targetReal
+}
+
+export function contentRevision(text) {
+  return createHash('sha256').update(text).digest('hex')
+}
+
+export async function readNoteFile(filePath) {
+  const info = await stat(filePath)
+  if (!info.isFile()) throw failure('not-found', '便签不是文件')
+  if (info.size > LIMITS.maxFileBytes) throw failure('bad-request', '便签文件过大')
+  return readFile(filePath, 'utf8')
+}
+
+/** 独占发布并移走源文件；不支持硬链接时使用独占复制，目标存在则绝不覆盖。 */
+export async function moveFileExclusive(from, to) {
+  try { await link(from, to) } catch (error) {
+    if (!['EXDEV', 'EPERM', 'EACCES', 'ENOTSUP', 'EOPNOTSUPP', 'ENOSYS'].includes(error.code)) throw error
+    await copyFile(from, to, constants.COPYFILE_EXCL)
+  }
+  try { await unlink(from) } catch (error) {
+    await unlink(to)
+    throw error
+  }
+}
+
+/** 替换已有文件；项目创建策略仍由原来的开档流程决定。 */
+export async function atomicWrite(filePath, content, { mode } = {}) {
+  const tmp = `${filePath}.${randomUUID()}.tmp`
+  try {
+    await writeFile(tmp, content, { encoding: 'utf8', flag: 'wx', mode })
+    await rename(tmp, filePath)
+  } finally {
+    await unlink(tmp).catch((error) => { if (error.code !== 'ENOENT') throw error })
+  }
+}

package/lib/host/ai-jobs.js

@@ -0,0 +1,118 @@
+/** 评论与开档任务实现；复用实例任务表、默认模型和逐文件写锁。 */
+import { buildCommentRequest, buildProjectDocument, buildProjectRequest, generateText, sourceWikilink } from '../ai.js'
+import { assertPathWithin, atomicWrite, failure, isInside, readNoteFile } from '../files.js'
+import { appendComment, setProjectsLink } from '../notes.js'
+import { LIMITS, localStamp } from '../shared.js'
+import { ensureDir, fileExists, readModelSource } from './note-content.js'
+import { join, relative, sep } from 'node:path'
+
+function createAiEndpoints({
+  assertNotePath, ctx, finishJob, getSettings, invalidateAndScan, invalidateScan, jobs, requireNotes,
+  runningJob, startJob, withNoteWrite,
+}) {
+  async function runCommentJob(job, emoji) {
+    try {
+      const note = await readModelSource(job.path)
+      const generated = await generateText(ctx, buildCommentRequest(note, emoji))
+      await withNoteWrite(job.path, async () => {
+        await assertNotePath(job.path)
+        const original = await readNoteFile(job.path)
+        const next = appendComment(original, {
+          type: emoji.callout,
+          title: `${emoji.emoji} ${emoji.label} · ${localStamp()}`,
+          text: generated.text,
+        })
+        await atomicWrite(job.path, next)
+        invalidateScan(job.path)
+      })
+      // 撞上 token 上限但有正文：内容已写入，Client 用 job.truncated 提示「可能被截断」。
+      if (generated.truncated) job.truncated = true
+      finishJob(job)
+    } catch (error) {
+      finishJob(job, error)
+    }
+  }
+
+  async function endpointComment(payload) {
+    const filePath = await assertNotePath(payload?.path)
+    const emojiId = typeof payload?.emojiId === 'string' ? payload.emojiId : ''
+    const emoji = getSettings().emojis.find((item) => item.id === emojiId)
+    if (!emoji) throw failure('bad-request', '找不到这个 emoji 的配置')
+    await readNoteFile(filePath)
+    const running = runningJob('comment', filePath, emojiId)
+    if (running !== undefined) return { jobId: running.id }
+    const runningCount = [...jobs.values()].filter((job) => job.status === 'running').length
+    if (runningCount >= 4) throw failure('busy', '同时运行的 AI 任务太多了，稍等一下')
+    const job = startJob('comment', filePath, { emojiId })
+    void runCommentJob(job, emoji)
+    return { jobId: job.id }
+  }
+
+  function sanitizeProjectName(input) {
+    let name = String(input ?? '').trim().replace(/\u0000/g, '')
+    name = name.replace(/[\\/:*?"<>|#^[\]]/g, ' ').replace(/\s+/g, ' ').trim()
+    name = name.replace(/^\.+/, '').slice(0, LIMITS.projectNameChars).trim()
+    return name
+  }
+
+  async function runProjectJob(job, name, sourcePath) {
+    try {
+      const paths = requireNotes()
+      const note = await readModelSource(sourcePath)
+      await assertPathWithin(paths.vault, job.projectFolder, { allowMissing: true })
+      await ensureDir(job.projectFolder)
+      const request = buildProjectRequest(note, getSettings().projectPrompt, name, getSettings().projectAi)
+      const generated = await generateText(ctx, request)
+      const sourceRel = relative(paths.vault, sourcePath).split(sep).join('/')
+      const document = buildProjectDocument({
+        name,
+        generated: generated.text,
+        sourceRelPath: sourceRel,
+        sourceTitle: note.title || name,
+      })
+      await assertPathWithin(paths.vault, job.projectPath, { allowMissing: true })
+      await atomicWrite(job.projectPath, document)
+      const projectRel = relative(paths.vault, job.projectPath).split(sep).join('/')
+      const link = sourceWikilink(projectRel, name)
+      await withNoteWrite(sourcePath, async () => {
+        await assertNotePath(sourcePath)
+        const original = await readNoteFile(sourcePath)
+        const linked = setProjectsLink(original, link)
+        if (linked.changed) {
+          await atomicWrite(sourcePath, linked.text)
+          job.link = 'linked'
+        } else {
+          job.link = linked.reason
+        }
+      })
+      await invalidateAndScan(sourcePath)
+      // 撞上 token 上限但有正文：文档已写入，Client 用 job.truncated 提示「可能被截断」。
+      if (generated.truncated) job.truncated = true
+      finishJob(job)
+    } catch (error) {
+      finishJob(job, error)
+    }
+  }
+
+  async function endpointOpenProject(payload) {
+    const paths = requireNotes()
+    if (!paths.project) throw failure('not-configured', '还没有配置开档目录')
+    if (!isInside(paths.vault, paths.project)) throw failure('bad-request', '开档目录不在仓库内')
+    const sourcePath = await assertNotePath(payload?.path)
+    const name = sanitizeProjectName(payload?.name)
+    if (name === '') throw failure('bad-request', '项目名不能为空')
+    const projectFolder = join(paths.project, name)
+    const projectPath = join(projectFolder, `${name}.md`)
+    await assertPathWithin(paths.vault, projectPath, { allowMissing: true })
+    if (await fileExists(projectPath)) throw failure('exists', `开档目录里已有「${name}」`)
+    const running = runningJob('project', sourcePath)
+    if (running !== undefined) return { jobId: running.id, projectPath: running.projectPath }
+    const job = startJob('project', sourcePath, { name, projectFolder, projectPath })
+    void runProjectJob(job, name, sourcePath)
+    return { jobId: job.id, projectPath }
+  }
+
+  return { endpointComment, endpointOpenProject }
+}
+
+export { createAiEndpoints }

package/lib/host/configuration.js

@@ -0,0 +1,151 @@
+/** 持有当前配置、文件位置和配置队列；接受新设置后通知组合入口。 */
+import { pickConfigFile } from '../config-picker.js'
+import { assertPathWithin, failure, isHiddenVaultPath, isInside } from '../files.js'
+import { openExternalUrl } from '../obsidian.js'
+import { NotesScanner } from '../scan.js'
+import {
+  DEFAULT_SETTINGS, locateConfig, normalizeSettings, readConfigFile, rememberConfig, resolveUserPath,
+  writeConfigFile,
+} from '../settings.js'
+import { LEGACY_SETTINGS_FILE, PACKAGE_DIR } from './environment.js'
+import { stat } from 'node:fs/promises'
+import { dirname, isAbsolute, resolve } from 'node:path'
+
+async function createConfiguration({ config, onSettingsChange }) {
+  const fallback = config && typeof config === 'object' ? { ...DEFAULT_SETTINGS, ...config } : DEFAULT_SETTINGS
+
+  const location = await locateConfig({ legacyPath: LEGACY_SETTINGS_FILE })
+
+  let settingsFile = location.path
+
+  let settings
+
+  let configError = ''
+
+  try { settings = await readConfigFile(settingsFile) } catch (error) {
+    settings = normalizeSettings(fallback)
+    if (error.code === 'ENOENT') await writeConfigFile(settingsFile, settings, { exclusive: true })
+    else configError = '配置未加载：' + error.message
+  }
+
+  let configSignature = ''
+
+  let settingsQueue = Promise.resolve()
+
+  function queueSettings(action) {
+    const pending = settingsQueue.then(action)
+    settingsQueue = pending.catch(() => {})
+    return pending
+  }
+
+  function publicSettings() {
+    return { ...JSON.parse(JSON.stringify(settings)), configFile: { path: settingsFile, pinned: location.pinned, error: configError, revision: configRevision() } }
+  }
+
+  function configRevision() { return NotesScanner.hash(settingsFile + '\u0000' + JSON.stringify(settings)) }
+
+  function settingsFingerprint() {
+    return JSON.stringify(publicSettings())
+  }
+
+  async function validateSettings(raw) {
+    if (raw === null || typeof raw !== 'object' || Array.isArray(raw)) throw failure('bad-request', '设置格式不对')
+    const normalized = normalizeSettings(raw)
+    const vault = normalized.vaultPath ? resolve(normalized.vaultPath) : ''
+    if (vault) {
+      if (!(await stat(vault)).isDirectory()) throw failure('bad-request', '仓库必须是文件夹')
+      const checks = [
+        ['便签目录', normalized.notesDir],
+        ['开档目录', normalized.projectDir],
+        ['图片文件夹', normalized.attachmentDir],
+        ...normalized.archiveTargets.map((target) => ['归档目录', target.path]),
+      ]
+      for (const [label, value] of checks) {
+        if (!value) continue
+        if (!isInside(vault, resolve(value))) throw failure('bad-request', `${label}必须在仓库内：${value}`)
+        await assertPathWithin(vault, value, { allowMissing: true })
+      }
+      if (normalized.attachmentDir && isHiddenVaultPath(vault, normalized.attachmentDir)) {
+        throw failure('bad-request', `图片文件夹不能位于隐藏目录（Obsidian 不索引以 . 开头的目录）：${normalized.attachmentDir}`)
+      }
+      const notesInfo = normalized.notesDir ? await stat(resolve(normalized.notesDir)).catch(() => null) : null
+      if (normalized.notesDir && (notesInfo === null || !notesInfo.isDirectory())) {
+        throw failure('bad-request', `便签目录不存在：${normalized.notesDir}`)
+      }
+      if (normalized.attachmentDir) {
+        const info = await stat(normalized.attachmentDir).catch((error) => {
+          if (error.code === 'ENOENT') return null
+          throw error
+        })
+        if (info && !info.isDirectory()) throw failure('bad-request', `图片文件夹不是目录：${normalized.attachmentDir}`)
+      }
+    }
+    return normalized
+  }
+
+  function acceptSettings(next) {
+    const previous = settings
+    settings = next
+    configError = ''
+    onSettingsChange(next, previous)
+  }
+
+  async function refreshConfig() {
+    try {
+      const info = await stat(settingsFile)
+      const signature = `${info.mtimeMs}:${info.ctimeMs}:${info.size}:${info.ino}`
+      if (signature === configSignature) return
+      const next = await validateSettings(await readConfigFile(settingsFile))
+      if (JSON.stringify(next) !== JSON.stringify(settings)) acceptSettings(next)
+      configSignature = signature
+      configError = ''
+    } catch (error) { configError = `配置未加载，继续使用上次有效设置：${error.message}` }
+  }
+
+  async function endpointSaveSettings(payload) {
+    const normalized = await validateSettings(payload?.settings)
+    await refreshConfig()
+    if (configError) throw failure('conflict', configError)
+    if (payload?.expected && payload.expected !== configRevision()) throw failure('conflict', '配置已在其他位置更新，请重新打开设置后保存')
+    acceptSettings(await writeConfigFile(settingsFile, normalized))
+    return { settings: publicSettings() }
+  }
+
+  async function endpointConfigFile(payload) {
+    const action = payload?.action
+    if (action === 'open' || action === 'reveal') {
+      const opened = action === 'open' ? await openExternalUrl(settingsFile) : await openExternalUrl(dirname(settingsFile))
+      if (!opened.ok) throw failure('open-failed', opened.message)
+    } else if (action === 'load' || action === 'relocate') {
+      if (location.pinned) throw failure('bad-request', 'DSH_STICKY_NOTES_SETTINGS 已固定配置位置，请先移除环境变量')
+      const target = resolveUserPath(payload?.path)
+      if (!target || !target.toLowerCase().endsWith('.json') || !isAbsolute(target)) throw failure('bad-request', '请选择绝对路径的 JSON 文件')
+      if (isInside(PACKAGE_DIR, target)) throw failure('bad-request', '配置应保存在插件安装目录以外')
+      if (action === 'relocate') {
+        await refreshConfig()
+        if (configError) throw failure('conflict', configError)
+      }
+      const next = action === 'load' ? await validateSettings(await readConfigFile(target)) : settings
+      if (action === 'relocate') await writeConfigFile(target, next, { exclusive: true })
+      await rememberConfig(location, target)
+      settingsFile = target
+      configSignature = ''
+      acceptSettings(next)
+    } else if (action === 'reload') {
+      acceptSettings(await validateSettings(await readConfigFile(settingsFile)))
+      configSignature = ''
+    } else throw failure('bad-request', '未知配置操作')
+    return { settings: publicSettings() }
+  }
+
+  async function endpointChooseConfigFile() {
+    if (location.pinned) throw failure('bad-request', 'DSH_STICKY_NOTES_SETTINGS 已固定配置位置，请先移除环境变量')
+    return { path: await pickConfigFile() }
+  }
+
+  function getSettings() { return settings }
+
+  return { queueSettings, publicSettings, settingsFingerprint, refreshConfig, endpointSaveSettings, endpointConfigFile, endpointChooseConfigFile, getSettings }
+}
+
+export { createConfiguration }

package/lib/host/dispatch.js

@@ -0,0 +1,32 @@
+/** endpoint 分发、错误信封与写入/配置/删除操作的串行化规则。 */
+import { resolve } from 'node:path'
+
+function createDispatcher({ endpoints, queueSettings, withNoteWrite }) {
+  let deleteQueue = Promise.resolve()
+
+  async function dispatch(endpoint, payload) {
+    // DSH 的 client-connection 解析器（0.2.x）要求失败信封带 details 对象；缺了会把业务错误当成 transport 错误。
+    if (typeof endpoint !== 'string' || !Object.hasOwn(endpoints, endpoint)) {
+      return { ok: false, error: { code: 'bad-request', message: `未知 endpoint：${endpoint}`, details: {} } }
+    }
+    const handler = endpoints[endpoint]
+    try {
+      const mutating = ['saveNote', 'toggleTask', 'archive', 'deleteNote'].includes(endpoint)
+      const run = () => mutating && typeof payload?.path === 'string'
+        ? withNoteWrite(resolve(payload.path), () => handler(payload)) : handler(payload)
+      const deleting = endpoint === 'deleteNote' || endpoint === 'undoDelete' || endpoint === 'trash'
+      const configuring = ['saveSettings', 'configFile', 'settings'].includes(endpoint)
+      const pending = deleting ? deleteQueue.catch(() => {}).then(run) : configuring ? queueSettings(run) : run()
+      if (deleting) deleteQueue = pending.catch(() => {})
+      const value = await pending
+      return { ok: true, value }
+    } catch (error) {
+      const code = typeof error?.code === 'string' ? error.code : 'fs-failed'
+      return { ok: false, error: { code, message: error?.message ?? String(error), details: {} } }
+    }
+  }
+
+  return dispatch
+}
+
+export { createDispatcher }

package/lib/host/environment.js

@@ -0,0 +1,24 @@
+/** 包根目录、版本和调试日志；安装位置变化不影响旧配置迁移。 */
+import { createRequire } from 'node:module'
+import { join } from 'node:path'
+import { fileURLToPath } from 'node:url'
+
+const PACKAGE_DIR = fileURLToPath(new URL('../..', import.meta.url))
+
+const LEGACY_SETTINGS_FILE = join(PACKAGE_DIR, 'data', 'settings.json')
+
+const PACKAGE_JSON = createRequire(import.meta.url)('../../package.json')
+
+const VERSION = typeof PACKAGE_JSON?.version === 'string' && PACKAGE_JSON.version !== '' ? PACKAGE_JSON.version : '0.0.0'
+
+const DEBUG = process.env.DSH_STICKY_NOTES_DEBUG === '1'
+
+function debugLog(...args) {
+  if (DEBUG) console.info('[sticky-notes]', ...args)
+}
+
+function now() {
+  return Date.now()
+}
+
+export { PACKAGE_DIR, LEGACY_SETTINGS_FILE, VERSION, debugLog, now }

package/lib/host/folders.js

@@ -0,0 +1,77 @@
+/** 仓库内目录浏览、新建与系统选择器。 */
+import { assertPathWithin, failure, isHiddenVaultPath } from '../files.js'
+import { resolveUserPath } from '../settings.js'
+import { mkdir, readdir, stat } from 'node:fs/promises'
+import { isAbsolute, join, relative } from 'node:path'
+
+function createFolderEndpoints({ ctx, getSettings }) {
+  async function folderInVault(payload, allowMissing = false) {
+    const vault = resolveUserPath(payload?.vaultPath || getSettings().vaultPath)
+    if (!vault || !isAbsolute(vault)) throw failure('not-configured', '请先选择仓库文件夹')
+    if (!(await stat(vault)).isDirectory()) throw failure('bad-request', '仓库必须是文件夹')
+    const path = resolveUserPath(payload?.path || '.', vault)
+    await assertPathWithin(vault, path, { allowMissing })
+    if (isHiddenVaultPath(vault, path)) throw failure('bad-request', '请选择仓库内非隐藏文件夹')
+    return { vault, path }
+  }
+
+  async function endpointListFolders(payload) {
+    const { vault } = await folderInVault(payload)
+    const folders = ['.']
+    let truncated = false
+    async function walk(dir) {
+      for (const item of await readdir(dir, { withFileTypes: true })) {
+        if (item.name.startsWith('.') || item.name === 'node_modules' || !item.isDirectory() || item.isSymbolicLink()) continue
+        if (folders.length >= 1500) { truncated = true; return }
+        const path = join(dir, item.name)
+        await assertPathWithin(vault, path)
+        folders.push(relative(vault, path))
+        await walk(path)
+        if (truncated) return
+      }
+    }
+    await walk(vault)
+    return { folders: folders.sort((a, b) => a.localeCompare(b)), truncated }
+  }
+
+  async function endpointCreateFolder(payload) {
+    if (typeof payload?.path !== 'string' || !payload.path.trim() || payload.path.split(/[\\/]/).includes('..')) throw failure('bad-request', '请填写仓库内的文件夹名称')
+    const { vault, path } = await folderInVault(payload, true)
+    await mkdir(path, { recursive: true })
+    await assertPathWithin(vault, path)
+    return { path }
+  }
+
+  async function endpointChooseConfigDirectory() {
+    const result = await endpointPickDirectory()
+    if (!result.path) return { path: null, files: [] }
+    const files = (await readdir(result.path, { withFileTypes: true }))
+      .filter((item) => item.isFile() && item.name.toLowerCase().endsWith('.json'))
+      .map((item) => join(result.path, item.name)).sort()
+    return { path: result.path, files }
+  }
+
+  async function endpointPickDirectory(payload) {
+    const controller = ctx.get('directoryPickerController')
+    if (controller === undefined) throw failure('picker-unavailable', '当前环境没有目录选择器')
+    const abort = new AbortController()
+    const timeout = setTimeout(() => abort.abort(new Error('timeout')), 10 * 60 * 1000)
+    try {
+      const path = await controller.pick(abort.signal)
+      if (path && payload?.vaultPath) {
+        const checked = await folderInVault({ vaultPath: payload.vaultPath, path })
+        if (!(await stat(checked.path)).isDirectory()) throw failure('bad-request', '请选择文件夹')
+      }
+      return { path: typeof path === 'string' && path !== '' ? path : null }
+    } catch (error) {
+      if (error?.code === 'bad-request' || error?.code === 'not-configured') throw error
+      throw failure('picker-unavailable', `目录选择失败：${error?.message ?? error}`, error)
+    } finally {
+      clearTimeout(timeout)
+    }
+  }
+
+  return { endpointListFolders, endpointCreateFolder, endpointChooseConfigDirectory, endpointPickDirectory }
+}
+
+export { createFolderEndpoints }