ppxans-harness 2.4.0 → 3.2.0

package/src/tools/vad.js

@@ -0,0 +1,176 @@
+// src/tools/vad.js - 语音活动检测 (VAD, 零依赖)
+//
+// 用途: 语音消息/音频切分 —— 找出"有人说话"的片段, 供 ASR 只转写有效段 (省时省钱),
+//       或语音通道做"说到停"的断句。
+//
+// 双后端:
+//   energy (默认, 零依赖): 解析 WAV (PCM 16bit) → 按帧算 RMS → 能量阈值 + 滞回判定语音段。
+//     对干净录音效果够用; 嘈杂环境弱于神经网络方案。
+//   silero (可选): 动态 import onnxruntime-node 跑 Silero-VAD ONNX 模型 —— 包或模型缺失时
+//     返回明确错误 (不静默降级, 让调用方自己选能量版)。
+//     模型: silero_vad.onnx (https://github.com/snakers4/silero-vad), config 路径传入。
+import fs from "node:fs";
+import path from "node:path";
+import { TOOL_ERROR_PREFIX } from "./seam.js";
+
+function err(name, msg) {
+  return `${TOOL_ERROR_PREFIX} ${name}: ${msg}`;
+}
+
+// ---- WAV 解析 (16-bit PCM only, 零依赖) ----
+export function parseWavPcm16(buf) {
+  if (buf.length < 44 || buf.toString("ascii", 0, 4) !== "RIFF" || buf.toString("ascii", 8, 12) !== "WAVE") {
+    throw new Error("不是 WAV (RIFF) 文件");
+  }
+  let off = 12;
+  let fmt = null;
+  let data = null;
+  while (off + 8 <= buf.length) {
+    const id = buf.toString("ascii", off, off + 4);
+    const size = buf.readUInt32LE(off + 4);
+    if (id === "fmt ") {
+      fmt = {
+        format: buf.readUInt16LE(off + 8),
+        channels: buf.readUInt16LE(off + 10),
+        sampleRate: buf.readUInt32LE(off + 12),
+        bitsPerSample: buf.readUInt16LE(off + 22),
+      };
+    } else if (id === "data") {
+      data = buf.subarray(off + 8, off + 8 + size);
+    }
+    off += 8 + size + (size % 2);
+  }
+  if (!fmt || !data) throw new Error("WAV 缺少 fmt/data 块");
+  if (fmt.format !== 1) throw new Error(`仅支持 PCM (format=1), 当前 format=${fmt.format}`);
+  if (fmt.bitsPerSample !== 16) throw new Error(`仅支持 16-bit (当前 ${fmt.bitsPerSample}-bit), 请先转码`);
+  return { sampleRate: fmt.sampleRate, channels: fmt.channels, samples: data };
+}
+
+// 16-bit 交错样本 → 单声道 Float32 (-1..1)
+function toMono(samples, channels) {
+  const n = Math.floor(samples.length / 2 / channels);
+  const out = new Float32Array(n);
+  for (let i = 0; i < n; i++) {
+    let acc = 0;
+    for (let c = 0; c < channels; c++) acc += samples.readInt16LE((i * channels + c) * 2);
+    out[i] = acc / channels / 32768;
+  }
+  return out;
+}
+
+// ---- 能量 VAD: 按帧 RMS + 滞回 (进入阈值 > 退出阈值, 防抖) ----
+export function energyVad(pcm, { sampleRate = 16000, frameMs = 30, threshold = 0.015, hangoverMs = 300, minSpeechMs = 120 } = {}) {
+  const frameLen = Math.max(1, Math.round((sampleRate * frameMs) / 1000));
+  const hangFrames = Math.max(1, Math.round(hangoverMs / frameMs));
+  const minSpeechFrames = Math.max(1, Math.round(minSpeechMs / frameMs));
+  const frames = [];
+  for (let i = 0; i + frameLen <= pcm.length; i += frameLen) {
+    let sum = 0;
+    for (let j = 0; j < frameLen; j++) { const v = pcm[i + j]; sum += v * v; }
+    frames.push(Math.sqrt(sum / frameLen)); // RMS
+  }
+  // 自适应底噪: 取最安静的 20% 帧均值, 阈值 = max(固定下限, 底噪×4)
+  const sorted = [...frames].sort((a, b) => a - b);
+  const noise = sorted.slice(0, Math.max(1, Math.floor(sorted.length * 0.2))).reduce((a, b) => a + b, 0) / Math.max(1, Math.floor(sorted.length * 0.2));
+  const enterAt = Math.max(threshold, noise * 4);
+  const exitAt = Math.max(threshold * 0.6, noise * 2.5);
+  const segments = [];
+  let inSpeech = false, start = 0, quietRun = 0;
+  frames.forEach((rms, idx) => {
+    if (!inSpeech && rms > enterAt) { inSpeech = true; start = idx; quietRun = 0; }
+    else if (inSpeech) {
+      if (rms < exitAt) { quietRun++; if (quietRun >= hangFrames) { inSpeech = false; if ((idx - quietRun + 1 - start) >= minSpeechFrames) segments.push([start, idx - quietRun + 1]); } }
+      else quietRun = 0;
+    }
+  });
+  if (inSpeech && frames.length - start >= minSpeechFrames) segments.push([start, frames.length]);
+  const speechFrames = segments.reduce((a, [s, e]) => a + (e - s), 0);
+  return {
+    backend: "energy",
+    durationMs: Math.round((frames.length * frameMs)),
+    noiseFloor: Number(noise.toFixed(5)),
+    threshold: Number(enterAt.toFixed(5)),
+    speechRatio: frames.length ? Number((speechFrames / frames.length).toFixed(3)) : 0,
+    segments: segments.map(([s, e]) => ({ startMs: Math.round(s * frameMs), endMs: Math.round(e * frameMs) })),
+  };
+}
+
+// ---- Silero 后端 (可选): onnxruntime-node + silero_vad.onnx ----
+async function sileroVad(abs, opts) {
+  let ort;
+  try { ort = await import("onnxruntime-node"); } catch {
+    return err("vad_detect", "silero 后端需要 onnxruntime-node (npm i onnxruntime-node), 未安装。改用默认 energy 后端 (零依赖)");
+  }
+  if (!opts.model) return err("vad_detect", "silero 后端需指定模型路径: args.model = silero_vad.onnx 的绝对路径");
+  const wav = parseWavPcm16(fs.readFileSync(abs));
+  const mono = toMono(wav.samples, wav.channels);
+  const session = await ort.InferenceSession.create(opts.model);
+  // Silero-VAD v4/v5: 逐帧 (512 样本 @16k) 推理, state (h/c) 迭代传递
+  const frame = 512;
+  let h = new ort.Tensor("float32", new Float32Array(2 * 64), [2, 1, 64]);
+  let c = new ort.Tensor("float32", new Float32Array(2 * 64), [2, 1, 64]);
+  const probs = [];
+  for (let i = 0; i + frame <= mono.length; i += frame) {
+    const input = new ort.Tensor("float32", mono.subarray(i, i + frame), [1, frame]);
+    const sr = new ort.Tensor("int64", BigInt64Array.from([BigInt(wav.sampleRate)]), []);
+    const feeds = { input, h, c, sample_rate: sr };
+    const out = await session.run(feeds);
+    probs.push(out.output?.data?.[0] ?? 0);
+    h = out.hn || h; c = out.cn || c;
+  }
+  const enterAt = opts.threshold ?? 0.5;
+  const segments = [];
+  let inSpeech = false, start = 0, quiet = 0;
+  const frameMs = Math.round((frame / wav.sampleRate) * 1000);
+  probs.forEach((p, idx) => {
+    if (!inSpeech && p > enterAt) { inSpeech = true; start = idx; quiet = 0; }
+    else if (inSpeech) {
+      if (p < enterAt * 0.6) { quiet++; if (quiet >= Math.round(300 / frameMs)) { inSpeech = false; segments.push([start, idx - quiet + 1]); } }
+      else quiet = 0;
+    }
+  });
+  if (inSpeech) segments.push([start, probs.length]);
+  return JSON.stringify({
+    backend: "silero",
+    durationMs: Math.round((mono.length / wav.sampleRate) * 1000),
+    speechRatio: probs.length ? Number((segments.reduce((a, [s, e]) => a + (e - s), 0) / probs.length).toFixed(3)) : 0,
+    segments: segments.map(([s, e]) => ({ startMs: s * frameMs, endMs: e * frameMs })),
+  });
+}
+
+export function registerVadTools(catalog, { rootDir = process.cwd() } = {}) {
+  catalog.register({
+    name: "vad_detect",
+    description: "语音活动检测 (VAD): 找出音频里有人说话的时间段。默认零依赖能量算法 (16-bit PCM WAV); 可选 silero 神经网络后端 (需 onnxruntime-node + onnx 模型)。用于 ASR 前切分、语音断句。",
+    parameters: {
+      type: "object",
+      properties: {
+        path: { type: "string", description: "WAV 文件路径 (16-bit PCM; 其他格式请先转码)" },
+        backend: { type: "string", enum: ["energy", "silero"], description: "energy=零依赖能量阈值 (默认); silero=神经网络 (需 onnxruntime-node)" },
+        model: { type: "string", description: "silero 后端: silero_vad.onnx 模型路径" },
+        threshold: { type: "number", description: "能量后端: RMS 进入阈值 (默认 0.015 自适应底噪); silero 后端: 概率阈值 (默认 0.5)" },
+      },
+      required: ["path"],
+    },
+    category: "net",
+    power: "user",
+    idempotent: true,
+    capability: { readOnly: true, riskLevel: "low", sideEffect: "none" },
+    execute: async (args) => {
+      const abs = path.isAbsolute(args.path) ? args.path : path.resolve(rootDir, args.path);
+      if (!fs.existsSync(abs)) return err("vad_detect", `文件不存在: ${args.path}`);
+      if (args.backend === "silero") return sileroVad(abs, args);
+      let wav;
+      try {
+        wav = parseWavPcm16(fs.readFileSync(abs));
+      } catch (e) {
+        return err("vad_detect", `${e.message} (仅支持 16-bit PCM WAV; mp3/m4a 请先转码: ffmpeg -i in.mp3 -acodec pcm_s16le -ar 16000 out.wav)`);
+      }
+      if (wav.sampleRate < 8000 || wav.sampleRate > 192000) return err("vad_detect", `采样率异常: ${wav.sampleRate}Hz`);
+      const mono = toMono(wav.samples, wav.channels);
+      const r = energyVad(mono, { sampleRate: wav.sampleRate, threshold: Number(args.threshold) || 0.015 });
+      return JSON.stringify(r);
+    },
+  });
+  return catalog;
+}

package/src/tools/voice.js

@@ -0,0 +1,238 @@
+// src/tools/voice.js - 语音能力 (ASR 语音转文本 + TTS 文本转语音)
+// 设计原则: 零运行时依赖 —— 走 OpenAI 兼容 HTTP 端点
+//   ASR: POST {base_url}/audio/transcriptions  (multipart/form-data)
+//   TTS: POST {base_url}/audio/speech          (返回二进制音频)
+// multipart 用 Node 内置的 FormData + Blob (18+ 全局), 不引入任何 npm 包。
+// 兼容: OpenAI / 硅基流动 / 火山 / 智谱 / 本地 whisper.cpp server 等任意 OpenAI 兼容端点。
+import fs from "node:fs";
+import path from "node:path";
+import { TOOL_ERROR_PREFIX } from "./seam.js";
+import { info } from "../utils/logger.js";
+
+// 常见音频扩展名 (用于路径与格式校验)
+const AUDIO_EXT = new Set([".wav", ".mp3", ".m4a", ".aac", ".flac", ".ogg", ".opus", ".webm", ".mp4", ".amr", ".silk"]);
+const MAX_ASR_BYTES = 25 * 1024 * 1024; // 25MB: OpenAI 兼容端点通用上限
+
+function err(name, msg) {
+  return `${TOOL_ERROR_PREFIX} ${name}: ${msg}`;
+}
+
+// 从配置解析一段语音端点 (asr / tts); 传入**完整 config**, 内部读 config.voice[kind]。
+// 返回 {baseUrl, apiKey, model, ...} 或 null (未配置 / 声明了 key 环境变量但没设值)
+// v3.1: voice.asr 支持 backend:"local" —— 走本地 whisper 绑定 (nodejs-whisper, 可选依赖),
+//       配 local 时 resolveVoice 返回 null 不影响本地路径 (本地判定在 resolveLocalAsr)。
+export function resolveVoice(config = {}, kind = "asr") {
+  const sec = config?.voice?.[kind];
+  if (!sec || typeof sec !== "object") return null;
+  if (sec.backend === "local") return null; // 本地后端不走 OpenAI 兼容端点
+  const baseUrl = String(sec.base_url || "").replace(/\/+$/, "");
+  if (!baseUrl) return null;
+  const apiKey = sec.api_key || (sec.api_key_env ? process.env[sec.api_key_env] : "") || "";
+  if (sec.api_key_env && !apiKey) return null; // 声明了 key 环境变量但没设 → 视为未配置
+  return {
+    baseUrl,
+    apiKey,
+    model: String(sec.model || (kind === "asr" ? "whisper-1" : "tts-1")),
+    voice: String(sec.voice || "alloy"),
+    format: String(sec.format || "mp3"),
+    timeoutMs: Number(sec.timeout_ms) || 120000,
+  };
+}
+
+// 本地 ASR 配置解析 (v3.1): voice.asr = { backend: "local", model, model_root_path?, auto_download?, language? }
+// 依赖 nodejs-whisper (可选依赖, 动态 import; 未安装时报错并给出安装指引)
+export function resolveLocalAsr(config = {}) {
+  const sec = config?.voice?.asr;
+  if (!sec || typeof sec !== "object" || sec.backend !== "local") return null;
+  return {
+    model: String(sec.model || "base"),
+    modelRootPath: sec.model_root_path ? String(sec.model_root_path) : undefined,
+    autoDownload: sec.auto_download !== false,
+    defaultLanguage: sec.language ? String(sec.language) : undefined,
+    timeoutMs: Number(sec.timeout_ms) || 300000, // 本地 CPU 推理给足 5 分钟
+  };
+}
+
+// 本地转写实现: 优先 nodejs-whisper (whisper.cpp 绑定, 全格式自动转 WAV), 失败给出可执行的安装指引
+async function localTranscribe(abs, opts, language) {
+  try {
+    const mod = await import("nodejs-whisper");
+    const out = await mod.nodewhisper(abs, {
+      modelName: opts.model,
+      modelRootPath: opts.modelRootPath,
+      autoDownloadModelName: opts.autoDownload ? opts.model : undefined,
+      whisperOptions: { outputInJson: true, wordTimestamps: false, ...(language ? { } : {}) },
+    });
+    // nodejs-whisper 的 JSON 输出为分段数组 [{start,end,text}], 拼接; 字符串则直用
+    if (Array.isArray(out)) {
+      return out.map((s) => (s && (s.text || s.speech)) || "").join("").trim();
+    }
+    return String(out || "").trim();
+  } catch (e) {
+    const hint = e?.code === "ERR_MODULE_NOT_FOUND" || String(e?.message || "").includes("Cannot find package")
+      ? "本地 ASR 依赖未安装。安装: npm i nodejs-whisper (Windows 需先装 MinGW-w64/MSYS2 提供 make), 或改用云端端点 voice.asr { base_url, api_key_env }"
+      : `本地转写失败: ${e.message || e}`;
+    throw new Error(hint);
+  }
+}
+
+// 语音能力是否就绪 (供 list_capabilities / 诊断展示)
+export function voiceStatus(config = {}) {
+  const asrSec = config?.voice?.asr;
+  return {
+    asr: asrSec?.backend === "local" ? "local" : !!resolveVoice(config, "asr"),
+    tts: !!resolveVoice(config, "tts"),
+    enabled: config?.voice?.enabled !== false,
+  };
+}
+
+const MIME = {
+  ".wav": "audio/wav", ".mp3": "audio/mpeg", ".m4a": "audio/mp4", ".aac": "audio/aac",
+  ".flac": "audio/flac", ".ogg": "audio/ogg", ".opus": "audio/opus", ".webm": "audio/webm",
+  ".mp4": "audio/mp4", ".amr": "audio/amr", ".silk": "audio/silk",
+};
+
+export function registerVoiceTools(catalog, { config = {}, rootDir = process.cwd() } = {}) {
+  // ---- ASR: 语音转文本 ----
+  catalog.register({
+    name: "voice_transcribe",
+    description: "把语音/音频文件转成文字 (ASR)。支持 wav/mp3/m4a/flac/ogg/webm 等, 上限 25MB。用于处理语音消息、会议录音、口述笔记。",
+    parameters: {
+      type: "object",
+      properties: {
+        path: { type: "string", description: "音频文件路径 (相对工作目录或绝对路径)" },
+        language: { type: "string", description: "语言代码 (如 zh / en), 留空自动检测" },
+        prompt: { type: "string", description: "提示词: 引导术语/人名/专有名词的识别 (可选)" },
+      },
+      required: ["path"],
+    },
+    category: "net",
+    power: "user",
+    idempotent: true,
+    capability: { readOnly: true, riskLevel: "low", sideEffect: "network" },
+    execute: async (args) => {
+      // v3.1: 本地 ASR 后端 (voice.asr.backend="local") —— 零 API key, 离线可用
+      const localOpts = resolveLocalAsr(config);
+      if (localOpts) {
+        const abs = path.isAbsolute(args.path) ? args.path : path.resolve(rootDir, args.path);
+        if (!fs.existsSync(abs)) return err("voice_transcribe", `文件不存在: ${args.path}`);
+        const st = fs.statSync(abs);
+        if (st.size > MAX_ASR_BYTES) {
+          return err("voice_transcribe", `文件过大 (${(st.size / 1048576).toFixed(1)}MB > 25MB), 请先切片`);
+        }
+        const ext = path.extname(abs).toLowerCase();
+        if (!AUDIO_EXT.has(ext)) return err("voice_transcribe", `不支持的音频格式: ${ext}`);
+        try {
+          const text = await localTranscribe(abs, localOpts, args.language || localOpts.defaultLanguage);
+          info(`[voice] 本地 ASR 完成: ${path.basename(abs)} (${(st.size / 1024).toFixed(0)}KB)`);
+          return text || "(识别结果为空)";
+        } catch (e) {
+          return err("voice_transcribe", e.message || String(e));
+        }
+      }
+      const v = resolveVoice(config, "asr");
+      if (!v) {
+        return err("voice_transcribe", "未配置 ASR。二选一: ① 云端 config/ppx.json → voice.asr { base_url, api_key_env, model }; ② 本地 voice.asr { backend: \"local\", model: \"base\" } (需 npm i nodejs-whisper)");
+      }
+      const abs = path.isAbsolute(args.path) ? args.path : path.resolve(rootDir, args.path);
+      if (!fs.existsSync(abs)) return err("voice_transcribe", `文件不存在: ${args.path}`);
+      const st = fs.statSync(abs);
+      if (st.size > MAX_ASR_BYTES) {
+        return err("voice_transcribe", `文件过大 (${(st.size / 1048576).toFixed(1)}MB > 25MB), 请先切片`);
+      }
+      const ext = path.extname(abs).toLowerCase();
+      if (!AUDIO_EXT.has(ext)) return err("voice_transcribe", `不支持的音频格式: ${ext}`);
+
+      const form = new FormData();
+      form.append("file", new Blob([fs.readFileSync(abs)], { type: MIME[ext] || "application/octet-stream" }), path.basename(abs));
+      form.append("model", v.model);
+      if (args.language) form.append("language", String(args.language));
+      if (args.prompt) form.append("prompt", String(args.prompt).slice(0, 800));
+
+      const ctrl = new AbortController();
+      const timer = setTimeout(() => ctrl.abort(), v.timeoutMs);
+      try {
+        const res = await fetch(`${v.baseUrl}/audio/transcriptions`, {
+          method: "POST",
+          headers: v.apiKey ? { Authorization: `Bearer ${v.apiKey}` } : {},
+          body: form,
+          signal: ctrl.signal,
+        });
+        const text = await res.text();
+        if (!res.ok) return err("voice_transcribe", `HTTP ${res.status}: ${text.slice(0, 300)}`);
+        let out = text;
+        try {
+          const j = JSON.parse(text);
+          out = j.text ?? j.result ?? text;
+        } catch { /* 非 JSON 就直接用原文 */ }
+        info(`[voice] ASR 完成: ${path.basename(abs)} (${(st.size / 1024).toFixed(0)}KB)`);
+        return String(out).trim() || "(识别结果为空)";
+      } catch (e) {
+        return err("voice_transcribe", e.name === "AbortError" ? `请求超时 (${v.timeoutMs}ms)` : String(e.message || e));
+      } finally {
+        clearTimeout(timer);
+      }
+    },
+  });
+
+  // ---- TTS: 文本转语音 ----
+  catalog.register({
+    name: "voice_speak",
+    description: "把文字合成语音文件 (TTS)。返回保存路径。用于生成语音播报、回复语音消息、口播稿试听。",
+    parameters: {
+      type: "object",
+      properties: {
+        text: { type: "string", description: "要合成的文本" },
+        out: { type: "string", description: "输出文件路径 (默认 data/voice/tts-<时间戳>.<格式>)" },
+        voice: { type: "string", description: "音色名 (默认取配置, 如 alloy / zh-CN-XiaoxiaoNeural)" },
+        format: { type: "string", enum: ["mp3", "wav", "opus", "aac", "flac"], description: "音频格式, 默认 mp3" },
+      },
+      required: ["text"],
+    },
+    category: "net",
+    power: "user",
+    capability: { riskLevel: "low", sideEffect: "filesystem+network" },
+    execute: async (args) => {
+      const v = resolveVoice(config, "tts");
+      if (!v) {
+        return err("voice_speak", "未配置 TTS 端点。在 config/ppx.json 里加 voice.tts { base_url, api_key_env, model, voice }");
+      }
+      const text = String(args.text || "").trim();
+      if (!text) return err("voice_speak", "text 不能为空");
+      if (text.length > 4000) return err("voice_speak", `文本过长 (${text.length} > 4000 字), 请分段合成`);
+      const format = String(args.format || v.format || "mp3");
+
+      const ctrl = new AbortController();
+      const timer = setTimeout(() => ctrl.abort(), v.timeoutMs);
+      try {
+        const res = await fetch(`${v.baseUrl}/audio/speech`, {
+          method: "POST",
+          headers: {
+            "content-type": "application/json",
+            ...(v.apiKey ? { Authorization: `Bearer ${v.apiKey}` } : {}),
+          },
+          body: JSON.stringify({ model: v.model, input: text, voice: args.voice || v.voice, response_format: format }),
+          signal: ctrl.signal,
+        });
+        if (!res.ok) {
+          const t = await res.text();
+          return err("voice_speak", `HTTP ${res.status}: ${t.slice(0, 300)}`);
+        }
+        const buf = Buffer.from(await res.arrayBuffer());
+        const out = args.out
+          ? (path.isAbsolute(args.out) ? args.out : path.resolve(rootDir, args.out))
+          : path.join(rootDir, "data", "voice", `tts-${Date.now()}.${format}`);
+        fs.mkdirSync(path.dirname(out), { recursive: true });
+        fs.writeFileSync(out, buf);
+        info(`[voice] TTS 完成: ${buf.length} 字节 → ${out}`);
+        return JSON.stringify({ ok: true, path: out, bytes: buf.length, format, chars: text.length });
+      } catch (e) {
+        return err("voice_speak", e.name === "AbortError" ? `请求超时 (${v.timeoutMs}ms)` : String(e.message || e));
+      } finally {
+        clearTimeout(timer);
+      }
+    },
+  });
+
+  return catalog;
+}

package/src/utils/async.js

@@ -0,0 +1,14 @@
+// src/utils/async.js - 异步小工具 (唯一实现, 2026-09-18 重构收敛)
+// 背景: withTimeout 原先在 orchestrator/supervisor.js 与 tools/delegate.js 各写一份,
+// 逐字相同 (含定时器清理注释)。收敛后 orchestrator 仍 re-export 同名函数, 对外接口不变。
+
+// 带超时等待 (防子 agent 卡死)。
+// 定时器必须清理, 否则 promise 快速 resolve 后残留的 setTimeout 仍会挂住事件循环
+// (最长到超时时间), 阻止进程正常退出。
+export function withTimeout(p, ms, label) {
+  let timer;
+  const timeout = new Promise((_, rej) => {
+    timer = setTimeout(() => rej(new Error(`${label}超时 (${ms / 1000}s)`)), ms);
+  });
+  return Promise.race([p, timeout]).finally(() => clearTimeout(timer));
+}

package/src/utils/config-file.js

@@ -0,0 +1,53 @@
+// src/utils/config-file.js - config/ppx.json 共享读写 (唯一实现)
+// 职责:
+//   - configFilePath(root): 统一配置文件路径 (原来 providers/channels/settings 三处各写一份)
+//   - readPpxConfig(root):  读整个 config JSON, 缺文件/损坏返回 fallback
+//   - writeConfigAtomic:    备份 (保留最近 3 个 .bak) → 原子写 (.tmp + rename), 防中途崩溃损坏
+// 收录自 src/config/{providers,channels,settings}.js 的逐字重复实现 (2026-09-18 重构),
+// 以后改备份策略/写盘语义只动这一处。
+import fs from "node:fs";
+import path from "node:path";
+import { atomicWrite } from "./store.js";
+import { warn } from "./logger.js";
+import { debug } from "../utils/logger.js";
+
+// 备份文件最多保留个数
+const MAX_BACKUPS = 3;
+
+export function configFilePath(root) {
+  return path.join(root, "config", "ppx.json");
+}
+
+// 读取整个 config, 文件不存在或 JSON 损坏时返回 fallback
+export function readPpxConfig(root, fallback = {}) {
+  const p = configFilePath(root);
+  if (!fs.existsSync(p)) return fallback;
+  try {
+    return JSON.parse(fs.readFileSync(p, "utf8"));
+  } catch (e) {
+    warn("config/ppx.json 读取失败:", e.message);
+    return fallback;
+  }
+}
+
+// 写盘: 先备份 (最多保留最近 MAX_BACKUPS 个 .bak-时间戳), 再原子写 (.tmp + rename)
+export function writeConfigAtomic(root, cfg) {
+  const p = configFilePath(root);
+  if (fs.existsSync(p)) {
+    const bak = p + ".bak-" + new Date().toISOString().replace(/[:.]/g, "-");
+    try { fs.copyFileSync(p, bak); } catch (e) { warn("备份失败:", e.message); }
+    try {
+      const dir = path.dirname(p);
+      const base = path.basename(p);
+      const baks = fs.readdirSync(dir)
+        .filter((f) => f.startsWith(base + ".bak-"))
+        .map((f) => ({ f, t: fs.statSync(path.join(dir, f)).mtimeMs }));
+      baks.sort((a, b) => b.t - a.t);
+      for (const old of baks.slice(MAX_BACKUPS)) {
+        try { fs.unlinkSync(path.join(dir, old.f)); } catch (e) { debug(`[utils/config-file] 已忽略异常: ${e && e.message ? e.message : e}`); }
+      }
+    } catch (e) { debug(`[utils/config-file] 已忽略异常: ${e && e.message ? e.message : e}`); }
+  }
+  // 原子写: store.atomicWrite 带随机 .tmp 后缀 + Windows rename 重试 (EPERM/EEXIST 兜底)
+  atomicWrite(p, JSON.stringify(cfg, null, 2));
+}

package/src/utils/crashguard.js

@@ -0,0 +1,88 @@
+// src/utils/crashguard.js - 全局异常兜底 (2026-09-17 体检新增, P1)
+//
+// 问题: 全项目此前只处理 SIGINT/SIGTERM, 没有 uncaughtException / unhandledRejection 兜底。
+//   Node >= 15 的默认行为是未处理的 Promise 拒绝直接终止进程 —— 对一个"双击即用"的
+//   桌面产品, 表现为窗口里的服务突然消失、用户只看到"未连接", 且没有任何线索。
+//
+// 策略 (可配置):
+//   默认: 记录完整堆栈 + 回调通知 (供总线广播/落盘), 然后**继续运行**。
+//     理由: 桌面场景下"带伤继续"远好于"静默消失"; 绝大多数异常来自单个请求/工具,
+//     进程级状态并未损坏。
+//   PPX_EXIT_ON_UNCAUGHT=1: 恢复"记录后退出"的传统行为 (适合作为 systemd/pm2 托管进程,
+//     由外部守护拉起)。退出码 1。
+//
+// 结构: 上报逻辑抽成独立工厂 createCrashReporter, 与 process 事件解耦 —— 便于单测,
+//   也避免测试进程里手动 emit 事件被 node:test 判为用例失败。
+const DEDUPE_WINDOW_MS = 5000;
+let installed = false; // 模块级单例标记: 兜底只需装一次
+
+function signature(err) {
+  return String(err?.stack || err?.message || err || "unknown").split("\n").slice(0, 3).join("|");
+}
+
+/**
+ * 创建一个"带去重折叠"的异常上报器。
+ * @param {object} opts
+ * @param {string}   [opts.tag="ppx"]  日志前缀
+ * @param {function} [opts.onError]    (err, kind) => void, 额外回调 (广播/落盘)
+ * @param {object}   [opts.logger]     日志器 (需有 warn/error), 默认 console
+ * @param {number}   [opts.dedupeMs]   同类错误折叠窗口
+ * @returns {(kind: string, err: unknown) => void} report
+ */
+export function createCrashReporter({ tag = "ppx", onError = null, logger = null, dedupeMs = DEDUPE_WINDOW_MS } = {}) {
+  const log = logger || { error: (...a) => console.error(...a), warn: (...a) => console.warn(...a) };
+  let lastSig = "";
+  let lastAt = 0;
+  let dupes = 0;
+
+  return function report(kind, err) {
+    const now = Date.now();
+    const sig = signature(err);
+    if (sig === lastSig && now - lastAt < dedupeMs) {
+      dupes++;
+      if (dupes % 20 === 0) log.warn(`[${tag}] ${kind} 重复出现 ${dupes} 次 (同类错误已折叠)`);
+      return;
+    }
+    lastSig = sig;
+    lastAt = now;
+    dupes = 0;
+    const detail = err?.stack || err?.message || String(err);
+    log.error(`[${tag}] 捕获 ${kind} (进程保持运行): ${detail}`);
+    try { onError && onError(err, kind); } catch { /* 兜底本身不得再抛 */ }
+  };
+}
+
+/**
+ * 安装全局异常兜底 (幂等: 重复调用只安装一次)。
+ * @param {object} opts 见 createCrashReporter; 另支持 exitOnUncaught 覆盖环境变量
+ * @returns {function} 卸载函数
+ */
+export function installCrashGuard(opts = {}) {
+  if (installed) return () => {};
+  installed = true;
+
+  const log = opts.logger || { error: (...a) => console.error(...a), warn: (...a) => console.warn(...a) };
+  const report = createCrashReporter(opts);
+  const exitOn = opts.exitOnUncaught != null
+    ? !!opts.exitOnUncaught
+    : String(process.env.PPX_EXIT_ON_UNCAUGHT || "") === "1";
+
+  const onUncaught = (err) => {
+    report("uncaughtException", err);
+    if (exitOn) {
+      log.error("[ppx] PPX_EXIT_ON_UNCAUGHT=1 → 退出 (退出码 1), 请交由外部守护拉起");
+      process.exit(1);
+    }
+  };
+  // 未处理的 Promise 拒绝在 Node >= 15 会终止进程; 桌面形态下改为记录后继续
+  const onRejection = (reason) => report("unhandledRejection", reason);
+
+  process.on("uncaughtException", onUncaught);
+  process.on("unhandledRejection", onRejection);
+
+  return () => {
+    process.off("uncaughtException", onUncaught);
+    process.off("unhandledRejection", onRejection);
+    installed = false;
+  };
+}

package/src/utils/http.js

@@ -0,0 +1,53 @@
+// src/utils/http.js - HTTP 请求/响应小工具 (唯一实现, 2026-09-18 重构收敛)
+// 收敛前重复情况:
+//   - readBody 在 channels/base、channels/http、mcp/http、aml-server 各写一份 (读循环 + 上限判定)
+//   - JSON 响应样板 (writeHead + Content-Type + JSON.stringify + end) 在四处共约 20 处手写
+// 提取后语义由本文件单点决定; 各调用方保留自己的错误码/降级策略 (413 写响应 vs 返回 null vs 抛错)。
+
+// 读满请求体。
+//   maxBytes > 0 时: 累计字节数超限即停止累积并返回 null, 由调用方决定回 413 / 抛错。
+//   注意: 超限后仍把剩余数据读完 (只丢弃不累积), 不能中途 break —— 提前跳出 for await
+//   会销毁请求流, 客户端还在上传时收不到响应, 表现为请求挂死而非 413。
+// 2026-09-18 修复: 原实现按块 `body += chunk` 逐块 toString, TCP 分块边界落在多字节
+//   UTF-8 字符中间时产生 U+FFFD, 中文请求体被静默损坏。现先 Buffer.concat 再整体 decode。
+export async function readBody(req, { maxBytes = 0 } = {}) {
+  const chunks = [];
+  let total = 0;
+  let overflow = false;
+  for await (const chunk of req) {
+    if (overflow) continue; // 已超限: 只消费不累积, 保证连接正常关闭
+    const buf = Buffer.isBuffer(chunk) ? chunk : Buffer.from(String(chunk));
+    chunks.push(buf);
+    total += buf.length;
+    if (maxBytes > 0 && total > maxBytes) { overflow = true; chunks.length = 0; total = 0; }
+  }
+  return overflow ? null : Buffer.concat(chunks).toString("utf8");
+}
+
+// 读满请求体并解析 JSON。
+//   空体 → {} (与 channels/http 既有语义一致); 超限 → null; JSON 非法 → 抛错 (调用方转 400)。
+export async function readJsonBody(req, { maxBytes = 0 } = {}) {
+  const body = await readBody(req, { maxBytes });
+  if (body === null) return null;
+  return JSON.parse(body || "{}");
+}
+
+// SSE 响应头 (channels/http 与 mcp/http 的流式响应共用, 原先各写一份字面量)
+// 冻结以防调用方误改共享对象; flushHeaders 的时机仍由调用方决定 (发头后应立即 flush)。
+export const SSE_HEADERS = Object.freeze({
+  "Content-Type": "text/event-stream",
+  "Cache-Control": "no-cache",
+  "Connection": "keep-alive",
+  "X-Accel-Buffering": "no",
+});
+
+// 统一 JSON 响应。
+//   obj === undefined 时只结束响应不写 body (channels/http 的 204 语义)。
+//   contentLength=true 时补 Content-Length (aml-server 需要)。
+export function sendJson(res, code, obj, { headers = {}, contentLength = false } = {}) {
+  const body = obj === undefined ? "" : JSON.stringify(obj);
+  const h = { "Content-Type": "application/json", ...headers };
+  if (contentLength) h["Content-Length"] = Buffer.byteLength(body);
+  res.writeHead(code, h);
+  res.end(body);
+}

package/src/utils/id.js

@@ -0,0 +1,8 @@
+// src/utils/id.js - 短 ID 生成 (唯一实现, 2026-09-18 重构收敛)
+// 原先 trace/playbook/mcp-tasks/asset-hub/failure-episode 各写一份
+// `prefix + Date.now().toString(36) + Math.random().toString(36).slice(2, n)`, 易漂移。
+// randEnd 传 Math.random().toString(36).slice(2, randEnd) 的结束下标, 与历史格式逐字节一致
+// (各调用方原有 randEnd: 5/6/8, 保持不变 —— ID 只要求唯一, 不保证加密安全)。
+export function shortId(prefix = "", randEnd = 6) {
+  return prefix + Date.now().toString(36) + Math.random().toString(36).slice(2, randEnd);
+}