ellm-proxy 0.0.3 → 0.0.7

package/manager/api/harness/codex.js

@@ -1,123 +1,123 @@
-// Codex 代理开关：~/.codex/config.toml 顶层 model_provider + [model_providers.ellm-proxy] 段
-// 指向本机 ellm-proxy 网关（语法见 openai/codex docs/config.md；wire_api 仅支持 chat|responses，
-// 此处用 chat 走 /v1/chat/completions）。
-// TOML 解析/校验用 smol-toml 库（不手写解析器）；写入采用文本级编辑以保留用户注释与排版，
-// 且写盘前必须通过库校验（结果文本可解析且 model_provider 正确），否则抛错保留原文件。
-import { readFileSync, writeFileSync, existsSync, mkdirSync } from "node:fs";
-import { homedir } from "node:os";
-import { join, dirname } from "node:path";
-import { parse as parseToml } from "smol-toml";
-import { backupOnce, restoreFromBackup } from "./backup.js";
-
-const PROVIDER_ID = "ellm-proxy"; // Codex provider id（避开官方保留 id: openai/ollama/lmstudio）
-const CODEX_CONFIG = join(homedir(), ".codex", "config.toml");
-
-function readCodexConfig() {
-  return existsSync(CODEX_CONFIG) ? readFileSync(CODEX_CONFIG, "utf-8") : null;
-}
-
-/** 是否已写顶层 model_provider = "ellm-proxy"（库解析；文本不合法按未开启处理，enable 时会给出明确报错） */
-function codexProviderActive(text) {
-  try {
-    return parseToml(text)?.model_provider === PROVIDER_ID;
-  } catch {
-    return false;
-  }
-}
-
-/** 库校验：文本必须可解析，且 expectProvider 为 true 时顶层 model_provider 必须是本 provider（写盘前强制调用） */
-function validateTomlText(text, expectProvider) {
-  let parsed;
-  try {
-    parsed = parseToml(text);
-  } catch (err) {
-    throw new Error(`编辑后的 config.toml 不是合法 TOML，已保留原文件: ${err.message}`);
-  }
-  if (expectProvider && parsed?.model_provider !== PROVIDER_ID) {
-    throw new Error(`编辑后的 config.toml 顶层 model_provider 不是 "${PROVIDER_ID}"，已保留原文件`);
-  }
-}
-
-/** Codex 开关状态：顶层 model_provider 是否为 ellm-proxy */
-export function codexStatus() {
-  const text = readCodexConfig();
-  return text ? codexProviderActive(text) : false;
-}
-
-/** 移除已有的 [model_providers.ellm-proxy] 段（从段头到下一个段头/文件尾），供重写为最新 base_url */
-function removeProviderSection(text) {
-  const lines = text.split("\n");
-  const out = [];
-  let skipping = false;
-  for (const line of lines) {
-    if (/^\s*\[model_providers\.ellm-proxy\]\s*$/.test(line)) {
-      skipping = true;
-      continue;
-    }
-    if (skipping && /^\s*\[/.test(line)) skipping = false; // 下一个段头，恢复收集
-    if (!skipping) out.push(line);
-  }
-  return out.join("\n").replace(/\n{3,}$/, "\n\n");
-}
-
-/** 设置顶层 model_provider = "ellm-proxy"：已有该键则替换（忽略注释行），否则插到首个段头前（TOML 顶层键必须在任何 [section] 之前） */
-function setTopLevelProvider(text) {
-  const lines = text.split("\n");
-  const keyLine = `model_provider = "${PROVIDER_ID}"`;
-  let replaced = false;
-  const out = lines.map((line) => {
-    if (!replaced && /^\s*model_provider\s*=/.test(line) && !line.trim().startsWith("#")) {
-      replaced = true;
-      return keyLine;
-    }
-    return line;
-  });
-  if (replaced) return out.join("\n");
-  const firstSection = out.findIndex((line) => /^\s*\[/.test(line));
-  if (firstSection === -1) return [...out, keyLine].join("\n");
-  out.splice(firstSection, 0, keyLine, "");
-  return out.join("\n");
-}
-
-/** 开启 Codex 代理：备份 → 写 model_provider + [model_providers.ellm-proxy] 段（重复开启幂等刷新 base_url）。
- *  原文本不合法时直接报错（不覆盖坏文件）；编辑结果写盘前经库校验 */
-export function codexEnable({ gatewayBase }) {
-  mkdirSync(dirname(CODEX_CONFIG), { recursive: true });
-  const original = readCodexConfig();
-  if (original !== null) {
-    try {
-      parseToml(original);
-    } catch (err) {
-      throw new Error(`${CODEX_CONFIG} 不是合法 TOML，拒绝修改（请先手工修复）: ${err.message}`);
-    }
-  }
-  let text = original ?? "";
-  backupOnce(CODEX_CONFIG);
-  text = removeProviderSection(text);
-  text = setTopLevelProvider(text);
-  const section = [
-    `[model_providers.${PROVIDER_ID}]`,
-    `name = "ellm-proxy gateway"`,
-    `base_url = "${gatewayBase}/v1"`,
-    `wire_api = "chat"`,
-    `env_key = "ELLM_PROXY_API_KEY"`,
-  ].join("\n");
-  text = text.replace(/\s*$/, "") + "\n\n" + section + "\n";
-  validateTomlText(text, true);
-  writeFileSync(CODEX_CONFIG, text, "utf-8");
-}
-
-/** 关闭 Codex 代理：从备份还原（无备份时移除 provider 段与顶层键，写盘前经库校验） */
-export function codexDisable() {
-  if (restoreFromBackup(CODEX_CONFIG)) return true;
-  const text = readCodexConfig();
-  if (!text || !codexProviderActive(text)) return false;
-  let out = removeProviderSection(text);
-  out = out
-    .split("\n")
-    .filter((line) => !/^\s*model_provider\s*=\s*["']?ellm-proxy["']?\s*$/.test(line))
-    .join("\n");
-  validateTomlText(out, false);
-  writeFileSync(CODEX_CONFIG, out, "utf-8");
-  return true;
-}
+// Codex 代理开关：~/.codex/config.toml 顶层 model_provider + [model_providers.ellm-proxy] 段
+// 指向本机 ellm-proxy 网关（语法见 openai/codex docs/config.md；wire_api 仅支持 chat|responses，
+// 此处用 chat 走 /v1/chat/completions）。
+// TOML 解析/校验用 smol-toml 库（不手写解析器）；写入采用文本级编辑以保留用户注释与排版，
+// 且写盘前必须通过库校验（结果文本可解析且 model_provider 正确），否则抛错保留原文件。
+import { readFileSync, writeFileSync, existsSync, mkdirSync } from "node:fs";
+import { homedir } from "node:os";
+import { join, dirname } from "node:path";
+import { parse as parseToml } from "smol-toml";
+import { backupOnce, restoreFromBackup } from "./backup.js";
+
+const PROVIDER_ID = "ellm-proxy"; // Codex provider id（避开官方保留 id: openai/ollama/lmstudio）
+const CODEX_CONFIG = join(homedir(), ".codex", "config.toml");
+
+function readCodexConfig() {
+  return existsSync(CODEX_CONFIG) ? readFileSync(CODEX_CONFIG, "utf-8") : null;
+}
+
+/** 是否已写顶层 model_provider = "ellm-proxy"（库解析；文本不合法按未开启处理，enable 时会给出明确报错） */
+function codexProviderActive(text) {
+  try {
+    return parseToml(text)?.model_provider === PROVIDER_ID;
+  } catch {
+    return false;
+  }
+}
+
+/** 库校验：文本必须可解析，且 expectProvider 为 true 时顶层 model_provider 必须是本 provider（写盘前强制调用） */
+function validateTomlText(text, expectProvider) {
+  let parsed;
+  try {
+    parsed = parseToml(text);
+  } catch (err) {
+    throw new Error(`编辑后的 config.toml 不是合法 TOML，已保留原文件: ${err.message}`);
+  }
+  if (expectProvider && parsed?.model_provider !== PROVIDER_ID) {
+    throw new Error(`编辑后的 config.toml 顶层 model_provider 不是 "${PROVIDER_ID}"，已保留原文件`);
+  }
+}
+
+/** Codex 开关状态：顶层 model_provider 是否为 ellm-proxy */
+export function codexStatus() {
+  const text = readCodexConfig();
+  return text ? codexProviderActive(text) : false;
+}
+
+/** 移除已有的 [model_providers.ellm-proxy] 段（从段头到下一个段头/文件尾），供重写为最新 base_url */
+function removeProviderSection(text) {
+  const lines = text.split("\n");
+  const out = [];
+  let skipping = false;
+  for (const line of lines) {
+    if (/^\s*\[model_providers\.ellm-proxy\]\s*$/.test(line)) {
+      skipping = true;
+      continue;
+    }
+    if (skipping && /^\s*\[/.test(line)) skipping = false; // 下一个段头，恢复收集
+    if (!skipping) out.push(line);
+  }
+  return out.join("\n").replace(/\n{3,}$/, "\n\n");
+}
+
+/** 设置顶层 model_provider = "ellm-proxy"：已有该键则替换（忽略注释行），否则插到首个段头前（TOML 顶层键必须在任何 [section] 之前） */
+function setTopLevelProvider(text) {
+  const lines = text.split("\n");
+  const keyLine = `model_provider = "${PROVIDER_ID}"`;
+  let replaced = false;
+  const out = lines.map((line) => {
+    if (!replaced && /^\s*model_provider\s*=/.test(line) && !line.trim().startsWith("#")) {
+      replaced = true;
+      return keyLine;
+    }
+    return line;
+  });
+  if (replaced) return out.join("\n");
+  const firstSection = out.findIndex((line) => /^\s*\[/.test(line));
+  if (firstSection === -1) return [...out, keyLine].join("\n");
+  out.splice(firstSection, 0, keyLine, "");
+  return out.join("\n");
+}
+
+/** 开启 Codex 代理：备份 → 写 model_provider + [model_providers.ellm-proxy] 段（重复开启幂等刷新 base_url）。
+ *  原文本不合法时直接报错（不覆盖坏文件）；编辑结果写盘前经库校验 */
+export function codexEnable({ gatewayBase }) {
+  mkdirSync(dirname(CODEX_CONFIG), { recursive: true });
+  const original = readCodexConfig();
+  if (original !== null) {
+    try {
+      parseToml(original);
+    } catch (err) {
+      throw new Error(`${CODEX_CONFIG} 不是合法 TOML，拒绝修改（请先手工修复）: ${err.message}`);
+    }
+  }
+  let text = original ?? "";
+  backupOnce(CODEX_CONFIG);
+  text = removeProviderSection(text);
+  text = setTopLevelProvider(text);
+  const section = [
+    `[model_providers.${PROVIDER_ID}]`,
+    `name = "ellm-proxy gateway"`,
+    `base_url = "${gatewayBase}/v1"`,
+    `wire_api = "chat"`,
+    `env_key = "ELLM_PROXY_API_KEY"`,
+  ].join("\n");
+  text = text.replace(/\s*$/, "") + "\n\n" + section + "\n";
+  validateTomlText(text, true);
+  writeFileSync(CODEX_CONFIG, text, "utf-8");
+}
+
+/** 关闭 Codex 代理：从备份还原（无备份时移除 provider 段与顶层键，写盘前经库校验） */
+export function codexDisable() {
+  if (restoreFromBackup(CODEX_CONFIG)) return true;
+  const text = readCodexConfig();
+  if (!text || !codexProviderActive(text)) return false;
+  let out = removeProviderSection(text);
+  out = out
+    .split("\n")
+    .filter((line) => !/^\s*model_provider\s*=\s*["']?ellm-proxy["']?\s*$/.test(line))
+    .join("\n");
+  validateTomlText(out, false);
+  writeFileSync(CODEX_CONFIG, out, "utf-8");
+  return true;
+}

package/manager/api/harness/dsh.js

@@ -1,175 +1,175 @@
-// DeepSeek Harness（dsh）代理开关：~/.dsh/settings.yaml 的 llm-deepseek.baseURL 指向本机网关，
-// 密钥写入官方托管凭据库 ~/.dsh/.credentials.yaml（refs.DEEPSEEK_API_KEY）。
-// dsh 解析口径（0.1.x developer preview）：llm-deepseek 适配器拼 {baseURL}/chat/completions，
-// 故 baseURL 需带 /v1；密钥解析优先级 = 进程环境变量 > .credentials.yaml > .env（进程已设
-// DEEPSEEK_API_KEY 时本开关写入的值不生效，需用户自行调整）。DSH_HOME env 可重定向 ~/.dsh。
-// YAML 解析/校验用 yaml 库 Document API（保留用户注释），不手写解析器；写盘前经库回读校验。
-import { readFileSync, writeFileSync, existsSync, mkdirSync } from "node:fs";
-import { homedir } from "node:os";
-import { join, dirname } from "node:path";
-import { parseDocument, isMap } from "yaml";
-import { backupOnce, restoreFromBackup } from "./backup.js";
-
-/** dsh 密钥引用名（llm-deepseek 的 apiKeyEnv 默认值） */
-const KEY_REF = "DEEPSEEK_API_KEY";
-/** 凭据文档 schema 版本（dsh credentials-local 的 version: 1） */
-const CREDENTIALS_VERSION = 1;
-/** 网关未配 masterKey 时写入的占位密钥（值任意：网关未设 masterKey 时放行，但 dsh 本地要求非空） */
-const PLACEHOLDER_KEY = "ellm-proxy";
-
-const dshHome = () => process.env.DSH_HOME || join(homedir(), ".dsh");
-const settingsFile = () => join(dshHome(), "settings.yaml");
-const credentialsFile = () => join(dshHome(), ".credentials.yaml");
-
-/** 去尾斜杠比较，容忍 http://x:1/ 与 http://x:1 视为同一地址 */
-function sameUrl(a, b) {
-  return String(a || "").replace(/\/+$/, "") === String(b || "").replace(/\/+$/, "");
-}
-
-function readTextIfExists(file) {
-  if (!existsSync(file)) return null;
-  const text = readFileSync(file, "utf-8");
-  return text.trim() === "" ? null : text; // 空文件按不存在处理（dsh：absent = empty store）
-}
-
-/** 解析 YAML 文档（不合法抛错，保留原文件语义同 claude-code 的 JSON 处理） */
-function parseYamlDoc(text, file) {
-  const doc = parseDocument(text);
-  if (doc.errors.length > 0) {
-    throw new Error(`${file} 不是合法 YAML，拒绝修改（请先手工修复）: ${doc.errors[0].message}`);
-  }
-  return doc;
-}
-
-/** 开关目标端点：dsh 适配器在 baseURL 后拼 /chat/completions，故带 /v1 走网关正式路由 */
-function targetBase(gatewayBase) {
-  return `${gatewayBase}/v1`;
-}
-
-/** dsh 开关状态：settings.yaml 的 llm-deepseek.baseURL 是否已指向网关（文件缺失/不合法按未开启） */
-export function dshStatus(gatewayBase) {
-  const text = readTextIfExists(settingsFile());
-  if (!text) return false;
-  try {
-    const data = parseYamlDoc(text, settingsFile()).toJS();
-    return sameUrl(data?.["llm-deepseek"]?.baseURL, targetBase(gatewayBase));
-  } catch {
-    return false;
-  }
-}
-
-/**
- * 开启 dsh 代理：备份 → settings.yaml 写 llm-deepseek.baseURL（幂等刷新）→
- * .credentials.yaml 写 refs.DEEPSEEK_API_KEY（masterKey 缺省时写占位值）。
- * 原文件不合法时直接报错（不覆盖坏文件）；凭据文档仅支持 version:1 与旧版扁平两种形态。
- */
-export function dshEnable({ gatewayBase, masterKey }) {
-  const target = targetBase(gatewayBase);
-
-  // 1) settings.yaml：先解析校验，后备份写入
-  mkdirSync(dshHome(), { recursive: true });
-  const settingsPath = settingsFile();
-  const origSettings = readTextIfExists(settingsPath);
-  const doc = origSettings === null ? parseYamlDoc("", settingsPath) : parseYamlDoc(origSettings, settingsPath);
-  const settingsData = doc.toJS();
-  if (settingsData && typeof settingsData["llm-deepseek"] !== "undefined" && typeof settingsData["llm-deepseek"] !== "object") {
-    throw new Error(`${settingsPath} 的 llm-deepseek 不是映射结构，拒绝修改`);
-  }
-  backupOnce(settingsPath);
-  doc.setIn(["llm-deepseek", "baseURL"], target);
-  writeValidatedYaml(settingsPath, doc);
-
-  // 2) .credentials.yaml：官方托管凭据库（优先级低于进程环境变量，高于 .env 两层）
-  const credPath = credentialsFile();
-  const key = masterKey || PLACEHOLDER_KEY;
-  const origCred = readTextIfExists(credPath);
-  backupOnce(credPath);
-  if (origCred === null) {
-    const credDoc = parseYamlDoc("", credPath);
-    credDoc.set("version", CREDENTIALS_VERSION);
-    credDoc.setIn(["refs", KEY_REF], key);
-    writeValidatedYaml(credPath, credDoc);
-    return;
-  }
-  const credDoc = parseYamlDoc(origCred, credPath);
-  const credData = credDoc.toJS();
-  if (!isMap(credDoc.contents)) throw new Error(`${credPath} 根节点不是映射结构，拒绝修改`);
-  if (typeof credData.version !== "undefined" && credData.version !== CREDENTIALS_VERSION) {
-    throw new Error(`${credPath} 的 version 为 ${credData.version}，本开关仅支持 version: ${CREDENTIALS_VERSION}`);
-  }
-  if (typeof credData.version === "undefined") {
-    // 旧版扁平文档（dsh 启动时会自行迁移为 version:1）：保持扁平形态写入
-    const flat = Object.values(credData).every((v) => typeof v === "string" && v.length > 0);
-    if (!flat) throw new Error(`${credPath} 既非 version:1 也非旧版扁平结构，请手工整理后重试`);
-    credDoc.set(KEY_REF, key);
-  } else {
-    if (typeof credData.refs !== "undefined" && (typeof credData.refs !== "object" || credData.refs === null)) {
-      throw new Error(`${credPath} 的 refs 不是映射结构，拒绝修改`);
-    }
-    credDoc.setIn(["refs", KEY_REF], key);
-  }
-  writeValidatedYaml(credPath, credDoc);
-}
-
-/**
- * 关闭 dsh 代理：优先从备份还原两个文件（各自独立备份）；无备份时移除本开关写入的字段——
- * settings.yaml 仅在 baseURL 仍指向网关时移除（连带清理空 llm-deepseek 段）；
- * 凭据库仅在 DEEPSEEK_API_KEY 取值为本开关写入值（masterKey 或占位值）时移除，避免误删用户自己的官方 key。
- * 返回是否实际发生了还原/移除。
- */
-export function dshDisable(gatewayBase, masterKey) {
-  const settingsPath = settingsFile();
-  const credPath = credentialsFile();
-  let changed = false;
-
-  if (restoreFromBackup(settingsPath)) {
-    changed = true;
-  } else {
-    const text = readTextIfExists(settingsPath);
-    if (text) {
-      const doc = parseYamlDoc(text, settingsPath);
-      const data = doc.toJS();
-      if (sameUrl(data?.["llm-deepseek"]?.baseURL, targetBase(gatewayBase))) {
-        doc.deleteIn(["llm-deepseek", "baseURL"]);
-        const rest = doc.toJS()?.["llm-deepseek"];
-        if (!rest || typeof rest !== "object" || Object.keys(rest).length === 0) doc.deleteIn(["llm-deepseek"]);
-        writeValidatedYaml(settingsPath, doc);
-        changed = true;
-      }
-    }
-  }
-
-  if (restoreFromBackup(credPath)) {
-    changed = true;
-  } else {
-    const text = readTextIfExists(credPath);
-    if (text) {
-      const doc = parseYamlDoc(text, credPath);
-      const data = doc.toJS();
-      const ours = (v) => v === masterKey || v === PLACEHOLDER_KEY;
-      if (data?.version === CREDENTIALS_VERSION && ours(data?.refs?.[KEY_REF])) {
-        doc.deleteIn(["refs", KEY_REF]);
-        if (Object.keys(doc.toJS()?.refs ?? {}).length === 0) doc.deleteIn(["refs"]);
-        writeValidatedYaml(credPath, doc);
-        changed = true;
-      } else if (typeof data?.version === "undefined" && ours(data?.[KEY_REF])) {
-        doc.deleteIn([KEY_REF]);
-        writeValidatedYaml(credPath, doc);
-        changed = true;
-      }
-    }
-  }
-  return changed;
-}
-
-/** 写盘前经库回读校验（结果必须可解析），失败保留原文件 */
-function writeValidatedYaml(file, doc) {
-  const text = doc.toString();
-  try {
-    parseDocument(text);
-  } catch (err) {
-    throw new Error(`编辑后的 ${file} 不是合法 YAML，已保留原文件: ${err.message}`);
-  }
-  mkdirSync(dirname(file), { recursive: true });
-  writeFileSync(file, text, "utf-8");
-}
+// DeepSeek Harness（dsh）代理开关：~/.dsh/settings.yaml 的 llm-deepseek.baseURL 指向本机网关，
+// 密钥写入官方托管凭据库 ~/.dsh/.credentials.yaml（refs.DEEPSEEK_API_KEY）。
+// dsh 解析口径（0.1.x developer preview）：llm-deepseek 适配器拼 {baseURL}/chat/completions，
+// 故 baseURL 需带 /v1；密钥解析优先级 = 进程环境变量 > .credentials.yaml > .env（进程已设
+// DEEPSEEK_API_KEY 时本开关写入的值不生效，需用户自行调整）。DSH_HOME env 可重定向 ~/.dsh。
+// YAML 解析/校验用 yaml 库 Document API（保留用户注释），不手写解析器；写盘前经库回读校验。
+import { readFileSync, writeFileSync, existsSync, mkdirSync } from "node:fs";
+import { homedir } from "node:os";
+import { join, dirname } from "node:path";
+import { parseDocument, isMap } from "yaml";
+import { backupOnce, restoreFromBackup } from "./backup.js";
+
+/** dsh 密钥引用名（llm-deepseek 的 apiKeyEnv 默认值） */
+const KEY_REF = "DEEPSEEK_API_KEY";
+/** 凭据文档 schema 版本（dsh credentials-local 的 version: 1） */
+const CREDENTIALS_VERSION = 1;
+/** 网关未配 masterKey 时写入的占位密钥（值任意：网关未设 masterKey 时放行，但 dsh 本地要求非空） */
+const PLACEHOLDER_KEY = "ellm-proxy";
+
+const dshHome = () => process.env.DSH_HOME || join(homedir(), ".dsh");
+const settingsFile = () => join(dshHome(), "settings.yaml");
+const credentialsFile = () => join(dshHome(), ".credentials.yaml");
+
+/** 去尾斜杠比较，容忍 http://x:1/ 与 http://x:1 视为同一地址 */
+function sameUrl(a, b) {
+  return String(a || "").replace(/\/+$/, "") === String(b || "").replace(/\/+$/, "");
+}
+
+function readTextIfExists(file) {
+  if (!existsSync(file)) return null;
+  const text = readFileSync(file, "utf-8");
+  return text.trim() === "" ? null : text; // 空文件按不存在处理（dsh：absent = empty store）
+}
+
+/** 解析 YAML 文档（不合法抛错，保留原文件语义同 claude-code 的 JSON 处理） */
+function parseYamlDoc(text, file) {
+  const doc = parseDocument(text);
+  if (doc.errors.length > 0) {
+    throw new Error(`${file} 不是合法 YAML，拒绝修改（请先手工修复）: ${doc.errors[0].message}`);
+  }
+  return doc;
+}
+
+/** 开关目标端点：dsh 适配器在 baseURL 后拼 /chat/completions，故带 /v1 走网关正式路由 */
+function targetBase(gatewayBase) {
+  return `${gatewayBase}/v1`;
+}
+
+/** dsh 开关状态：settings.yaml 的 llm-deepseek.baseURL 是否已指向网关（文件缺失/不合法按未开启） */
+export function dshStatus(gatewayBase) {
+  const text = readTextIfExists(settingsFile());
+  if (!text) return false;
+  try {
+    const data = parseYamlDoc(text, settingsFile()).toJS();
+    return sameUrl(data?.["llm-deepseek"]?.baseURL, targetBase(gatewayBase));
+  } catch {
+    return false;
+  }
+}
+
+/**
+ * 开启 dsh 代理：备份 → settings.yaml 写 llm-deepseek.baseURL（幂等刷新）→
+ * .credentials.yaml 写 refs.DEEPSEEK_API_KEY（masterKey 缺省时写占位值）。
+ * 原文件不合法时直接报错（不覆盖坏文件）；凭据文档仅支持 version:1 与旧版扁平两种形态。
+ */
+export function dshEnable({ gatewayBase, masterKey }) {
+  const target = targetBase(gatewayBase);
+
+  // 1) settings.yaml：先解析校验，后备份写入
+  mkdirSync(dshHome(), { recursive: true });
+  const settingsPath = settingsFile();
+  const origSettings = readTextIfExists(settingsPath);
+  const doc = origSettings === null ? parseYamlDoc("", settingsPath) : parseYamlDoc(origSettings, settingsPath);
+  const settingsData = doc.toJS();
+  if (settingsData && typeof settingsData["llm-deepseek"] !== "undefined" && typeof settingsData["llm-deepseek"] !== "object") {
+    throw new Error(`${settingsPath} 的 llm-deepseek 不是映射结构，拒绝修改`);
+  }
+  backupOnce(settingsPath);
+  doc.setIn(["llm-deepseek", "baseURL"], target);
+  writeValidatedYaml(settingsPath, doc);
+
+  // 2) .credentials.yaml：官方托管凭据库（优先级低于进程环境变量，高于 .env 两层）
+  const credPath = credentialsFile();
+  const key = masterKey || PLACEHOLDER_KEY;
+  const origCred = readTextIfExists(credPath);
+  backupOnce(credPath);
+  if (origCred === null) {
+    const credDoc = parseYamlDoc("", credPath);
+    credDoc.set("version", CREDENTIALS_VERSION);
+    credDoc.setIn(["refs", KEY_REF], key);
+    writeValidatedYaml(credPath, credDoc);
+    return;
+  }
+  const credDoc = parseYamlDoc(origCred, credPath);
+  const credData = credDoc.toJS();
+  if (!isMap(credDoc.contents)) throw new Error(`${credPath} 根节点不是映射结构，拒绝修改`);
+  if (typeof credData.version !== "undefined" && credData.version !== CREDENTIALS_VERSION) {
+    throw new Error(`${credPath} 的 version 为 ${credData.version}，本开关仅支持 version: ${CREDENTIALS_VERSION}`);
+  }
+  if (typeof credData.version === "undefined") {
+    // 旧版扁平文档（dsh 启动时会自行迁移为 version:1）：保持扁平形态写入
+    const flat = Object.values(credData).every((v) => typeof v === "string" && v.length > 0);
+    if (!flat) throw new Error(`${credPath} 既非 version:1 也非旧版扁平结构，请手工整理后重试`);
+    credDoc.set(KEY_REF, key);
+  } else {
+    if (typeof credData.refs !== "undefined" && (typeof credData.refs !== "object" || credData.refs === null)) {
+      throw new Error(`${credPath} 的 refs 不是映射结构，拒绝修改`);
+    }
+    credDoc.setIn(["refs", KEY_REF], key);
+  }
+  writeValidatedYaml(credPath, credDoc);
+}
+
+/**
+ * 关闭 dsh 代理：优先从备份还原两个文件（各自独立备份）；无备份时移除本开关写入的字段——
+ * settings.yaml 仅在 baseURL 仍指向网关时移除（连带清理空 llm-deepseek 段）；
+ * 凭据库仅在 DEEPSEEK_API_KEY 取值为本开关写入值（masterKey 或占位值）时移除，避免误删用户自己的官方 key。
+ * 返回是否实际发生了还原/移除。
+ */
+export function dshDisable(gatewayBase, masterKey) {
+  const settingsPath = settingsFile();
+  const credPath = credentialsFile();
+  let changed = false;
+
+  if (restoreFromBackup(settingsPath)) {
+    changed = true;
+  } else {
+    const text = readTextIfExists(settingsPath);
+    if (text) {
+      const doc = parseYamlDoc(text, settingsPath);
+      const data = doc.toJS();
+      if (sameUrl(data?.["llm-deepseek"]?.baseURL, targetBase(gatewayBase))) {
+        doc.deleteIn(["llm-deepseek", "baseURL"]);
+        const rest = doc.toJS()?.["llm-deepseek"];
+        if (!rest || typeof rest !== "object" || Object.keys(rest).length === 0) doc.deleteIn(["llm-deepseek"]);
+        writeValidatedYaml(settingsPath, doc);
+        changed = true;
+      }
+    }
+  }
+
+  if (restoreFromBackup(credPath)) {
+    changed = true;
+  } else {
+    const text = readTextIfExists(credPath);
+    if (text) {
+      const doc = parseYamlDoc(text, credPath);
+      const data = doc.toJS();
+      const ours = (v) => v === masterKey || v === PLACEHOLDER_KEY;
+      if (data?.version === CREDENTIALS_VERSION && ours(data?.refs?.[KEY_REF])) {
+        doc.deleteIn(["refs", KEY_REF]);
+        if (Object.keys(doc.toJS()?.refs ?? {}).length === 0) doc.deleteIn(["refs"]);
+        writeValidatedYaml(credPath, doc);
+        changed = true;
+      } else if (typeof data?.version === "undefined" && ours(data?.[KEY_REF])) {
+        doc.deleteIn([KEY_REF]);
+        writeValidatedYaml(credPath, doc);
+        changed = true;
+      }
+    }
+  }
+  return changed;
+}
+
+/** 写盘前经库回读校验（结果必须可解析），失败保留原文件 */
+function writeValidatedYaml(file, doc) {
+  const text = doc.toString();
+  try {
+    parseDocument(text);
+  } catch (err) {
+    throw new Error(`编辑后的 ${file} 不是合法 YAML，已保留原文件: ${err.message}`);
+  }
+  mkdirSync(dirname(file), { recursive: true });
+  writeFileSync(file, text, "utf-8");
+}