dsh-voice 0.3.6 → 0.3.7

package/CHANGELOG.md

@@ -4,6 +4,15 @@
 
 [历史英文记录](docs/CHANGELOG.en.md)
 
+## 0.3.7 (2026-10-20)
+
+- 修复 voice_stt 的引擎/地址错配：openai、groq 分支不再写死厂商地址，一律使用配置 `asrBaseUrl`；模型传的 `engine` 与配置 `asrEngine` 不一致时直接报错，避免把 groq 的密钥发给 OpenAI 或把自建服务的密钥发给厂商
+- 修复读写越界：`audio` 与 `output`/`outputDir` 解析后必须落在会话工作区内（含符号链接解析），工作区外的文件不再被整份上传给 ASR，也不再在工作区外创建文件
+- 拒绝跟随符号链接写入（含悬空链接），新建文件用 `O_EXCL`；转写文本改为 0600
+- `voice_preview` 复用 `resolveOutputPath`：`overwrite=false` 时同名样例加序号，不再直接覆盖
+- 音频大小按实际读到的字节数复查，`stat` 报 0 字节的伪文件不再绕过 25MB 预检
+- 新增 8 项回归测试（工作区越界、私钥不被上传、符号链接、engine 错配、自定义网关、preview 不覆盖）
+
 ## 0.3.6 (2026-10-05)
 
 - ASR 网络与响应体读取均受超时和取消控制；保留用户取消原因，空白或缺失识别结果明确报错，不伪造成功文本文件。

package/README.en.md

@@ -8,6 +8,8 @@ Generate speech from text or transcribe audio through a compatible API.
 
 [![npm](https://img.shields.io/npm/v/dsh-voice)](https://www.npmjs.com/package/dsh-voice) [![downloads](https://raw.githubusercontent.com/STARDUSTLC666/dsh-suite/npm-downloads/assets/dsh-voice-downloads.svg)](https://www.npmjs.com/package/dsh-voice)
 
+Feedback and contributions are welcome: report [issues](https://github.com/STARDUSTLC666/dsh-voice/issues) or submit [pull requests](https://github.com/STARDUSTLC666/dsh-voice/pulls).
+
 ## What it does
 
 - Generate speech using the Edge online read-aloud service.

package/README.md

@@ -8,6 +8,8 @@
 
 [![npm](https://img.shields.io/npm/v/dsh-voice)](https://www.npmjs.com/package/dsh-voice) [![downloads](https://raw.githubusercontent.com/STARDUSTLC666/dsh-suite/npm-downloads/assets/dsh-voice-downloads.svg)](https://www.npmjs.com/package/dsh-voice)
 
+欢迎使用，遇到问题或有改进建议，请提交 [issues](https://github.com/STARDUSTLC666/dsh-voice/issues) 和 [PR](https://github.com/STARDUSTLC666/dsh-voice/pulls)。
+
 ## 功能
 
 - 使用 Edge 在线朗读服务生成语音。

package/docs/USAGE.en.md

@@ -40,7 +40,7 @@ Then restart the web service. To clean up fully, also remove the plugin entry fr
 | Tool | Purpose | Key parameters |
 | :-- | :-- | :-- |
 | `voice_tts` | Synthesize MP3 from text (Edge online service) | `text` required; `voice`/`rate`/`pitch`/`output` optional |
-| `voice_stt` | Transcribe audio to text | `audio` required; `engine`/`model`/`language`/`prompt`/`output` optional |
+| `voice_stt` | Transcribe audio to text | `audio` required; `model`/`language`/`prompt`/`output` optional; `engine` may only repeat the configured `asrEngine` |
 | `voice_list` | Curated voice catalog | none |
 | `voice_preview` | Batch-generate short preview MP3s | optional `voices` (≤8) / `text` / `outputDir` |
 | `voice_health` | Offline config self-check | none |
@@ -50,7 +50,7 @@ Then restart the web service. To clean up fully, also remove the plugin entry fr
 ```text
 voice_tts { text: hello world }                              # outputs voice_output.mp3
 voice_tts { text: hello, voice: en-US-AriaNeural }           # English female voice
-voice_stt { audio: E:\audio\meeting.mp3, language: zh }     # transcribe a recording
+voice_stt { audio: meeting.mp3, language: zh }               # transcribe a recording inside the session workspace
 voice_list {}
 voice_preview { voices: [zh-CN-XiaoxiaoNeural, en-US-AriaNeural] } # generate two preview samples
 voice_health {}                                              # self-check TTS / ASR / proxy config
@@ -60,7 +60,11 @@ voice_health {}                                              # self-check TTS /
 
 - **Direct edge-tts protocol**: the Sec-MS-GEC token is **generated locally** with the official DRM algorithm (SHA256 of Windows file time + trusted client token, 5-minute windows); transport uses the `ws` library with permessage-deflate and an optional HTTP CONNECT proxy tunnel
 - **API configuration**: TTS needs no separate API key. STT uses your configured ASR service, whose pricing and limits apply.
-- Up-front validation: text ≤ 5000 chars, audio ≤ 25MB; same-name outputs auto-suffixed
+- Up-front validation: text ≤ 5000 chars, audio ≤ 25MB (re-checked against the bytes actually read); same-name outputs auto-suffixed
+- **Reads and writes stay inside the session workspace**: `audio`, `output` and `outputDir` must resolve (symlinks included) under `session.header.cwd`; anything outside is rejected. Copy the file in first.
+- **Symlinks are never written through**: a target that is a symlink (including a dangling one) is refused, and new files are created with `O_EXCL`.
+- **Transcripts are 0600**: the `.txt` written by `voice_stt` is owner-only (Windows does not enforce the mode bits).
+- **The key only goes to the configured endpoint**: ASR always uses `asrBaseUrl` from config (the groq/openai presets are defaults only); an `engine` argument that differs from config is rejected instead of shipping the key to another vendor.
 - Protocol aligned with current open-source edge-tts (7.x) — no reliance on the outdated token endpoint
 
 ## Development

package/docs/USAGE.md

@@ -40,7 +40,7 @@ dsh plugin --profile web remove dsh-voice
 | 工具 | 作用 | 关键参数 |
 | :-- | :-- | :-- |
 | `voice_tts` | 文字合成 MP3（Edge 在线服务） | `text` 必填；`voice`/`rate`/`pitch`/`output` 可选 |
-| `voice_stt` | 音频转文字 | `audio` 必填；`engine`/`model`/`language`/`prompt`/`output` 可选 |
+| `voice_stt` | 音频转文字 | `audio` 必填；`model`/`language`/`prompt`/`output` 可选；`engine` 只能与配置 `asrEngine` 相同 |
 | `voice_list` | 常用音色清单 | 无 |
 | `voice_preview` | 音色试听：批量生成短样例 MP3 | `voices`（≤8 个）/ `text` / `outputDir` 可选 |
 | `voice_health` | 配置自检（不联网） | 无 |
@@ -50,7 +50,7 @@ dsh plugin --profile web remove dsh-voice
 ```text
 voice_tts { text: 今天的 AI 早报来了 }                    # 晓晓女声，输出 voice_output.mp3
 voice_tts { text: hello, voice: en-US-AriaNeural }        # 英文女声
-voice_stt { audio: E:\audio\meeting.mp3, language: zh } # 转写会议录音
+voice_stt { audio: meeting.mp3, language: zh }           # 转写会话工作区里的录音
 voice_list {}
 voice_preview { voices: [zh-CN-XiaoxiaoNeural, en-US-AriaNeural] } # 生成两个试听样例
 voice_health {}                                          # 自检 TTS / ASR / 代理配置
@@ -60,7 +60,11 @@ voice_health {}                                          # 自检 TTS / ASR /
 
 - **edge-tts 协议直连**：Sec-MS-GEC 令牌按官方 DRM 算法**本地生成**（SHA256(Windows 文件时间 + TrustedClientToken)，5 分钟窗口），WS 传输用 `ws` 库 + permessage-deflate 压缩 + 可选 HTTP CONNECT 代理隧道
 - **接口配置**：TTS 无需另填 API Key；STT 使用你配置的 ASR 服务，其计费与额度由该服务决定。
-- 文本 ≤5000 字符、音频 ≤25MB 前置校验；输出同名自动加序号
+- 文本 ≤5000 字符、音频 ≤25MB 前置校验（读入后再按实际字节数复查一次）；输出同名自动加序号
+- **读写都在会话工作区内**：`audio` 与 `output` / `outputDir` 解析后（含符号链接）必须落在 `session.header.cwd` 之下，越界直接报错。想转写工作区外的录音，先复制进来；输出同理
+- **不跟随符号链接写文件**：目标是符号链接（含悬空链接）时拒绝写入，新建文件用 `O_EXCL`，避免检查完再被换成链接
+- **转写文本 0600**：`voice_stt` 写出的 `.txt` 只给当前用户读写（Windows 不检查权限位）
+- **密钥只发给配置的地址**：ASR 请求地址一律取配置 `asrBaseUrl`（groq/openai 的预设只是缺省值），模型传的 `engine` 与配置不一致会直接报错，避免把密钥发到另一家的主机
 - Edge TTS 协议适配保留在插件实现中，不使用旧令牌端点。
 
 ## 开发

package/lib/paths.d.ts

@@ -1,4 +1,23 @@
-/** 校验音频文件存在且是文件；相对路径按 cwd（会话工作区）解析，返回绝对路径。 */
+/**
+ * 校验音频文件：必须存在于会话工作区内，且是普通文件。
+ *
+ * 相对路径按 cwd（会话工作区）解析，返回解析后的绝对路径；符号链接会先
+ * 解析真实路径再判断边界，避免把工作区外的隐私文件（如 id_ed25519）当成
+ * 音频整份上传给 ASR 服务。
+ */
 export declare function assertAudioFile(input: string, cwd?: string): string;
-/** 决定输出路径：缺省放在会话工作目录（缺省回退宿主 cwd），同名自动加 _1/_2 序号。 */
+/**
+ * 决定输出路径：缺省放在会话工作目录（缺省回退宿主 cwd），同名自动加 _1/_2 序号。
+ *
+ * 目标必须落在会话工作区内；已存在的符号链接直接拒绝，避免顺着悬空链接
+ * 在工作区外创建文件。overwrite=false 时跳过已存在的路径（含符号链接）。
+ */
 export declare function resolveOutputPath(explicit: string | undefined, defaultName: string, overwrite: boolean, cwd?: string): string;
+/** 确保输出目录存在且落在工作区内：不存在则创建，越界或符号链接报错。 */
+export declare function ensureWorkspaceDirectory(input: string, cwd?: string): string;
+/**
+ * 写工作区内的文件：先建父目录，再按「新建用 wx / 覆盖用 w」落盘。
+ *
+ * 新建时用 O_EXCL，避免检查完成到写入之间被人塞进一个符号链接。
+ */
+export declare function writeWorkspaceFile(target: string, data: string | Buffer, cwd?: string, mode?: number): void;

package/lib/paths.js

@@ -1,30 +1,152 @@
 /**
- * 输出路径与音频文件校验。
+ * 输出路径、音频文件与工作区边界校验。
  *
  * @module dsh-voice/paths
  */
-import { existsSync, statSync } from 'node:fs';
-import { basename, dirname, extname, join, resolve } from 'node:path';
-/** 校验音频文件存在且是文件；相对路径按 cwd（会话工作区）解析，返回绝对路径。 */
+import { lstatSync, mkdirSync, openSync, closeSync, realpathSync, statSync, writeFileSync } from 'node:fs';
+import { basename, dirname, extname, isAbsolute, join, relative, resolve, sep } from 'node:path';
+/** 会话工作区的真实路径（解析符号链接）；取不到就退回解析后的绝对路径。 */
+function workspaceRoot(cwd) {
+    const absolute = resolve(cwd);
+    try {
+        return realpathSync(absolute);
+    }
+    catch {
+        return absolute;
+    }
+}
+/** candidate 是否等于 root 或位于 root 之下。 */
+function isInside(root, candidate) {
+    const rel = relative(root, candidate);
+    return rel === '' || (!isAbsolute(rel) && rel !== '..' && !rel.startsWith('..' + sep));
+}
+function pathState(target) {
+    try {
+        return lstatSync(target).isSymbolicLink() ? 'symlink' : 'present';
+    }
+    catch {
+        return 'missing';
+    }
+}
+/**
+ * 沿着最近的已存在祖先解析真实路径，再接回尚不存在的后缀。
+ *
+ * 用于输出路径：目标文件通常还不存在，但仍要判断它落盘时会不会被
+ * 中间某一层符号链接带到工作区之外。
+ */
+function resolveThroughExistingAncestor(target) {
+    let current = target;
+    const missing = [];
+    for (;;) {
+        try {
+            const real = realpathSync(current);
+            return missing.length === 0 ? real : join(real, ...missing.slice().reverse());
+        }
+        catch {
+            const parent = dirname(current);
+            if (parent === current)
+                return target;
+            missing.push(basename(current));
+            current = parent;
+        }
+    }
+}
+/** 输出路径必须落在工作区内，且不能是符号链接（含悬空链接）。 */
+function assertWritableTarget(target, root, label) {
+    if (pathState(target) === 'symlink') {
+        throw new Error(label + ' 是符号链接，拒绝写入：' + target + '（请改用工作区内的普通文件路径）');
+    }
+    const real = resolveThroughExistingAncestor(target);
+    if (!isInside(root, real)) {
+        throw new Error(label + ' 超出会话工作区：' + target + '（实际解析到 ' + real + '）。请把输出放在会话工作目录内。');
+    }
+}
+/**
+ * 校验音频文件：必须存在于会话工作区内，且是普通文件。
+ *
+ * 相对路径按 cwd（会话工作区）解析，返回解析后的绝对路径；符号链接会先
+ * 解析真实路径再判断边界，避免把工作区外的隐私文件（如 id_ed25519）当成
+ * 音频整份上传给 ASR 服务。
+ */
 export function assertAudioFile(input, cwd = process.cwd()) {
-    const absolute = resolve(cwd, input);
-    if (!existsSync(absolute) || !statSync(absolute).isFile()) {
+    const root = workspaceRoot(cwd);
+    const requested = resolve(root, input);
+    let real;
+    try {
+        real = realpathSync(requested);
+    }
+    catch {
         throw new Error('音频文件不存在：' + input);
     }
-    return absolute;
+    if (!isInside(root, real)) {
+        throw new Error('音频文件必须位于会话工作区内：' + input + '（实际解析到 ' + real + '）。请先复制到工作目录再转写。');
+    }
+    if (!statSync(real).isFile())
+        throw new Error('音频文件不是普通文件：' + input);
+    return requested;
 }
-/** 决定输出路径：缺省放在会话工作目录（缺省回退宿主 cwd），同名自动加 _1/_2 序号。 */
+/**
+ * 决定输出路径：缺省放在会话工作目录（缺省回退宿主 cwd），同名自动加 _1/_2 序号。
+ *
+ * 目标必须落在会话工作区内；已存在的符号链接直接拒绝，避免顺着悬空链接
+ * 在工作区外创建文件。overwrite=false 时跳过已存在的路径（含符号链接）。
+ */
 export function resolveOutputPath(explicit, defaultName, overwrite, cwd = process.cwd()) {
-    let target = explicit !== undefined && explicit.trim() !== '' ? resolve(cwd, explicit.trim()) : resolve(cwd, defaultName);
-    if (overwrite || !existsSync(target))
+    const root = workspaceRoot(cwd);
+    const requested = explicit !== undefined && explicit.trim() !== '' ? explicit.trim() : defaultName;
+    const target = resolve(root, requested);
+    assertWritableTarget(target, root, '输出路径');
+    if (overwrite || pathState(target) === 'missing')
         return target;
     const directory = dirname(target);
     const base = basename(target, extname(target));
     const extension = extname(target);
     for (let index = 1; index < 1000; index++) {
         const candidate = join(directory, base + '_' + index + extension);
-        if (!existsSync(candidate))
-            return candidate;
+        if (pathState(candidate) !== 'missing')
+            continue;
+        assertWritableTarget(candidate, root, '输出路径');
+        return candidate;
     }
     throw new Error('找不到可用的输出文件名（同名文件超过 999 个），请显式指定 output。');
 }
+/** 确保输出目录存在且落在工作区内：不存在则创建，越界或符号链接报错。 */
+export function ensureWorkspaceDirectory(input, cwd = process.cwd()) {
+    const root = workspaceRoot(cwd);
+    const target = resolve(root, input);
+    if (pathState(target) === 'symlink') {
+        throw new Error('输出目录是符号链接，拒绝写入：' + target);
+    }
+    const real = resolveThroughExistingAncestor(target);
+    if (!isInside(root, real)) {
+        throw new Error('输出目录超出会话工作区：' + target + '（实际解析到 ' + real + '）。请把输出放在会话工作目录内。');
+    }
+    mkdirSync(target, { recursive: true });
+    const after = realpathSync(target);
+    if (!isInside(root, after)) {
+        throw new Error('输出目录超出会话工作区：' + target + '（实际解析到 ' + after + '）');
+    }
+    return target;
+}
+/**
+ * 写工作区内的文件：先建父目录，再按「新建用 wx / 覆盖用 w」落盘。
+ *
+ * 新建时用 O_EXCL，避免检查完成到写入之间被人塞进一个符号链接。
+ */
+export function writeWorkspaceFile(target, data, cwd = process.cwd(), mode) {
+    const root = workspaceRoot(cwd);
+    assertWritableTarget(target, root, '输出路径');
+    mkdirSync(dirname(target), { recursive: true });
+    assertWritableTarget(target, root, '输出路径');
+    if (pathState(target) === 'missing') {
+        const fd = openSync(target, 'wx', mode);
+        try {
+            writeFileSync(fd, data);
+        }
+        finally {
+            closeSync(fd);
+        }
+        return;
+    }
+    writeFileSync(target, data, mode === undefined ? undefined : { mode });
+}

package/lib/tools.js

@@ -3,10 +3,10 @@
  *
  * @module dsh-voice/tools
  */
-import { mkdirSync, readFileSync, statSync, writeFileSync } from 'node:fs';
-import { basename, dirname, join, resolve } from 'node:path';
+import { readFileSync, statSync } from 'node:fs';
+import { basename, join } from 'node:path';
 import { synthesizeSpeech } from './edge-tts.js';
-import { assertAudioFile, resolveOutputPath } from './paths.js';
+import { assertAudioFile, ensureWorkspaceDirectory, resolveOutputPath, writeWorkspaceFile } from './paths.js';
 import { createProxyFetch } from './proxy-fetch.js';
 import { assertAudioSize, transcribe } from './stt.js';
 import { isValidVoiceId, VOICES } from './voices.js';
@@ -87,11 +87,6 @@ function sessionCwd(exec) {
     const cwd = exec?.agent?.session?.header?.cwd;
     return typeof cwd === 'string' && cwd.trim() !== '' ? cwd : process.cwd();
 }
-/** 写文件前先建父目录，避免合成/转写完成后才因 ENOENT 白烧一次接口调用。 */
-function writeFileWithDir(target, data) {
-    mkdirSync(dirname(target), { recursive: true });
-    writeFileSync(target, data);
-}
 const voiceItemSchema = {
     type: 'object',
     properties: { id: { type: 'string' }, gender: { type: 'string' }, locale: { type: 'string' } },
@@ -135,6 +130,8 @@ const previewSchema = {
     },
     additionalProperties: true,
 };
+/** 自定义端点没配 asrModel 时的兜底模型名。 */
+const FALLBACK_ASR_MODEL = 'whisper-1';
 /** 默认试听文本（中英混合，便于感知发音差异）。 */
 export const DEFAULT_PREVIEW_TEXT = '你好，这是音色试听。Hello, this is a voice preview.';
 /** voice_preview 同时合成的音色数上限：有界并发，避免 8 个音色串行把最坏等待拖成 8 倍超时。 */
@@ -203,7 +200,7 @@ export function buildVoiceTools(config, deps = {}) {
             const output = resolveOutputPath(optionalString(args, 'output'), 'voice_output.mp3', cfg.overwrite, sessionCwd(exec));
             const audio = await raceAbort((deps.tts ?? synthesizeSpeech)({ text, voice, rate, pitch }, { proxyUrl: cfg.proxyUrl }, timeout, signal), signal);
             throwIfAborted(signal);
-            writeFileWithDir(output, audio);
+            writeWorkspaceFile(output, audio, sessionCwd(exec));
             return { output, bytes: audio.length, voice, rate, pitch, textLength: text.length };
         },
         timeoutMs: timeout + 10000,
@@ -213,7 +210,7 @@ export function buildVoiceTools(config, deps = {}) {
         description: '语音转文字：调用 OpenAI 兼容 ASR 接口（默认 Groq whisper-large-v3-turbo；可切 openai/custom）。audio 为音频文件路径（mp3/wav/m4a/ogg/flac，≤25MB）；language/prompt 可选；output 可把转写文本写成 .txt。密钥用环境变量 DSH_VOICE_ASR_KEY 或配置 asrApiKey。',
         parameters: compileParameters({
             audio: { type: 'string', required: true, description: '音频文件路径（必填）。' },
-            engine: { type: 'string', enum: ['groq', 'openai', 'custom'], description: '引擎：groq / openai / custom（可选，默认配置值）。' },
+            engine: { type: 'string', enum: ['groq', 'openai', 'custom'], description: '引擎（可选）：只接受与配置 asrEngine 相同的值，用于显式确认；接口地址与密钥始终取配置。' },
             model: { type: 'string', description: '模型名（可选，覆盖配置）。' },
             language: { type: 'string', description: '语言提示，如 zh（可选）。' },
             prompt: { type: 'string', description: '提示词（专有名词/术语纠偏，可选）。' },
@@ -230,27 +227,26 @@ export function buildVoiceTools(config, deps = {}) {
             const signal = execSignal(exec);
             throwIfAborted(signal);
             const args = asRecord(rawArgs);
-            const audioPath = assertAudioFile(requiredString(args, 'audio', '音频文件'), sessionCwd(exec));
-            assertAudioSize(statSync(audioPath).size);
-            const engine = optionalString(args, 'engine') ?? cfg.asrEngine;
-            let baseUrl;
-            let model;
-            if (engine === 'openai') {
-                baseUrl = 'https://api.openai.com/v1';
-                model = optionalString(args, 'model') ?? 'whisper-1';
+            const cwd = sessionCwd(exec);
+            const audioPath = assertAudioFile(requiredString(args, 'audio', '音频文件'), cwd);
+            const requestedEngine = optionalString(args, 'engine');
+            if (requestedEngine !== undefined && !['groq', 'openai', 'custom'].includes(requestedEngine)) {
+                throw new Error('engine 必须是 groq / openai / custom 之一（当前：' + requestedEngine + '）。');
             }
-            else if (engine === 'custom') {
-                baseUrl = cfg.asrBaseUrl;
-                model = optionalString(args, 'model') ?? cfg.asrModel;
+            if (requestedEngine !== undefined && requestedEngine !== cfg.asrEngine) {
+                throw new Error('voice_stt 不支持用 engine 参数临时换引擎（配置 asrEngine=' + cfg.asrEngine + '，本次传入 ' + requestedEngine + '）。接口地址与密钥是一组配置，混着用会把密钥发到非预期的服务；如需切换请改配置里的 asrEngine / asrBaseUrl。');
             }
-            else if (engine === 'groq') {
-                baseUrl = 'https://api.groq.com/openai/v1';
-                model = optionalString(args, 'model') ?? (cfg.asrModel !== '' && cfg.asrEngine === 'groq' ? cfg.asrModel : 'whisper-large-v3-turbo');
-            }
-            else
-                throw new Error('engine 必须是 groq / openai / custom 之一（当前：' + engine + '）。');
+            // 接口地址一律取配置：openai/groq 预设已由 resolveConfig 回填，自定义端点原样使用。
+            const baseUrl = cfg.asrBaseUrl;
+            if (baseUrl === '')
+                throw new Error('未配置 ASR 接口地址：asrEngine=custom 时必须在配置里提供 asrBaseUrl。');
+            assertAudioSize(statSync(audioPath).size);
+            const audio = readFileSync(audioPath);
+            // 伪文件（如 procfs）stat 报 0 字节，按实际读到的长度再判一次。
+            assertAudioSize(audio.length);
+            const model = optionalString(args, 'model') ?? (cfg.asrModel !== '' ? cfg.asrModel : FALLBACK_ASR_MODEL);
             const { text } = await raceAbort((deps.stt ?? transcribe)(baseUrl, cfg.asrApiKey, {
-                audio: readFileSync(audioPath),
+                audio,
                 filename: basename(audioPath),
                 model,
                 language: optionalString(args, 'language'),
@@ -260,8 +256,9 @@ export function buildVoiceTools(config, deps = {}) {
             let transcriptFile = '';
             const output = optionalString(args, 'output');
             if (output !== undefined) {
-                const target = resolveOutputPath(output, '', cfg.overwrite, sessionCwd(exec));
-                writeFileWithDir(target, text);
+                const target = resolveOutputPath(output, '', cfg.overwrite, cwd);
+                // 转写文本可能含隐私内容，只用 0600 写入。
+                writeWorkspaceFile(target, text, cwd, 0o600);
                 transcriptFile = target;
             }
             // The output schema declares these as strings — never return null, or
@@ -309,8 +306,8 @@ export function buildVoiceTools(config, deps = {}) {
             const text = optionalString(args, 'text') ?? DEFAULT_PREVIEW_TEXT;
             if (text.length > 200)
                 throw new Error('试听文本请控制在 200 字以内（试听要短平快）。');
-            const outDir = resolve(sessionCwd(exec), optionalString(args, 'outputDir') ?? 'voice_previews');
-            mkdirSync(outDir, { recursive: true });
+            const cwd = sessionCwd(exec);
+            const outDir = ensureWorkspaceDirectory(optionalString(args, 'outputDir') ?? 'voice_previews', cwd);
             const outcomes = await mapLimit(targets, PREVIEW_CONCURRENCY, signal, async (voice) => {
                 throwIfAborted(signal);
                 if (!isValidVoiceId(voice)) {
@@ -319,8 +316,10 @@ export function buildVoiceTools(config, deps = {}) {
                 try {
                     const audio = await raceAbort((deps.tts ?? synthesizeSpeech)({ text, voice, rate: cfg.ttsRate, pitch: cfg.ttsPitch }, { proxyUrl: cfg.proxyUrl }, timeout, signal), signal);
                     throwIfAborted(signal);
-                    const file = join(outDir, 'voice-preview-' + voice.replace(/[^a-zA-Z0-9-]/g, '_') + '.mp3');
-                    writeFileSync(file, audio);
+                    const name = 'voice-preview-' + voice.replace(/[^a-zA-Z0-9-]/g, '_') + '.mp3';
+                    // 复用 resolveOutputPath：overwrite=false 时改名加序号，不再直接覆盖同名样例。
+                    const file = resolveOutputPath(join(outDir, name), '', cfg.overwrite, cwd);
+                    writeWorkspaceFile(file, audio, cwd);
                     return { voice, output: file, bytes: audio.length };
                 }
                 catch (error) {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "dsh-voice",
-  "version": "0.3.6",
+  "version": "0.3.7",
   "description": "把文字生成语音，或通过兼容接口把音频转为文字。",
   "type": "module",
   "main": "lib/index.js",