ellm-proxy 0.0.2 → 0.0.6

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");
+}

package/manager/api/harness/index.js

@@ -1,118 +1,118 @@
-// harness 代理开关聚合：Claude Code / Codex CLI / DeepSeek Harness 流量指向本机 ellm-proxy 网关。
-//   纯开关实现：claude-code.js（~/.claude/settings.json）/ codex.js（~/.codex/config.toml）/
-//   dsh.js（~/.dsh/settings.yaml + ~/.dsh/.credentials.yaml）/ backup.js（共用备份还原）
-//   createHarnessApp = HTTP 路由子应用（挂载于 /harness）：状态查询 + 开关切换（含 masterKey 校验与提示文案）
-import { Hono } from "hono";
-import { readFileSync } from "node:fs";
-import { resolveGatewayBase } from "../../../utils/service.js";
-import { claudeCodeStatus, claudeCodeEnable, claudeCodeDisable } from "./claude-code.js";
-import { codexStatus, codexEnable, codexDisable } from "./codex.js";
-import { dshStatus, dshEnable, dshDisable } from "./dsh.js";
-
-/** 配置文件顶层 masterKey（Claude Code 代理的 AUTH_TOKEN 取值；网关侧用它做鉴权） */
-function readMasterKey(configFile) {
-  try {
-    return JSON.parse(readFileSync(configFile, "utf-8")).masterKey || "";
-  } catch {
-    return "";
-  }
-}
-
-/** harness 开关子应用（挂载于 /harness）：GET / · POST /claude-code · POST /codex · POST /dsh（body {enabled}） */
-export function createHarnessApp({ startOpts }) {
-  const app = new Hono();
-
-  // GET /harness：三个开关状态
-  app.get("/", (c) => {
-    const { base } = resolveGatewayBase(startOpts.config);
-    return c.json({ ok: true, claudeCode: claudeCodeStatus(base), codex: codexStatus(), dsh: dshStatus(base), gatewayBase: base });
-  });
-
-  /** 读 body 并校验 enabled；合法返回 boolean，非法返回 400 Response（调用方直接 return 该响应） */
-  const requireEnabled = async (c) => {
-    let enabled;
-    try {
-      enabled = (await c.req.json())?.enabled;
-    } catch {
-      return c.json({ ok: false, error: "请求体不是合法 JSON" }, 400);
-    }
-    if (typeof enabled !== "boolean") {
-      return c.json({ ok: false, error: 'body 需为 {"enabled": true|false}' }, 400);
-    }
-    return enabled;
-  };
-
-  app.post("/claude-code", async (c) => {
-    const enabled = await requireEnabled(c);
-    if (enabled instanceof Response) return enabled;
-    const { base, configFile } = resolveGatewayBase(startOpts.config);
-    if (enabled) {
-      const masterKey = readMasterKey(configFile);
-      if (!masterKey) {
-        return c.json(
-          {
-            ok: false,
-            error: `配置未设置 masterKey，Claude Code 代理无法鉴权。请先在配置文件中设置 masterKey: ${configFile}`,
-          },
-          400,
-        );
-      }
-      claudeCodeEnable({ gatewayBase: base, token: masterKey });
-      return c.json({
-        ok: true,
-        claudeCode: true,
-        file: "~/.claude/settings.json",
-        note: "已备份原文件为 settings.json.ellm-bak，重启 Claude Code 会话后生效",
-      });
-    }
-    const changed = claudeCodeDisable(base);
-    return c.json({ ok: true, claudeCode: false, changed, note: changed ? "已从备份还原" : "原本未开启，无操作" });
-  });
-
-  app.post("/codex", async (c) => {
-    const enabled = await requireEnabled(c);
-    if (enabled instanceof Response) return enabled;
-    const { base, configFile } = resolveGatewayBase(startOpts.config);
-    if (enabled) {
-      codexEnable({ gatewayBase: base });
-      const masterKey = readMasterKey(configFile);
-      return c.json({
-        ok: true,
-        codex: true,
-        file: "~/.codex/config.toml",
-        note: masterKey
-          ? `已备份原文件为 config.toml.ellm-bak；请设置环境变量 ELLM_PROXY_API_KEY=${masterKey}（Codex 以 env_key 读取鉴权）`
-          : "已备份原文件为 config.toml.ellm-bak；请设置环境变量 ELLM_PROXY_API_KEY（网关未配 masterKey 时取值任意）",
-      });
-    }
-    const changed = codexDisable();
-    return c.json({ ok: true, codex: false, changed, note: changed ? "已从备份还原" : "原本未开启，无操作" });
-  });
-
-  app.post("/dsh", async (c) => {
-    const enabled = await requireEnabled(c);
-    if (enabled instanceof Response) return enabled;
-    const { base, configFile } = resolveGatewayBase(startOpts.config);
-    const masterKey = readMasterKey(configFile);
-    if (enabled) {
-      dshEnable({ gatewayBase: base, masterKey });
-      return c.json({
-        ok: true,
-        dsh: true,
-        file: "~/.dsh/settings.yaml",
-        note: masterKey
-          ? "已写入 settings.yaml（llm-deepseek.baseURL）与 .credentials.yaml（refs.DEEPSEEK_API_KEY），原文件备份为 *.ellm-bak。注意：进程环境里已设 DEEPSEEK_API_KEY 时其优先级更高，需自行改用网关 masterKey；模型请在 dsh 内选择与网关部署名一致的模型"
-          : "已写入 settings.yaml 与 .credentials.yaml（网关未配 masterKey，密钥为占位值即可放行），原文件备份为 *.ellm-bak。模型请在 dsh 内选择与网关部署名一致的模型",
-      });
-    }
-    const changed = dshDisable(base, masterKey);
-    return c.json({ ok: true, dsh: false, changed, note: changed ? "已从备份还原（或移除本开关写入的字段）" : "原本未开启，无操作" });
-  });
-
-  return app;
-}
-
-// 纯开关函数同时聚合导出（供不经过 HTTP 的调用方直接使用）
-export * from "./claude-code.js";
-export * from "./codex.js";
-export * from "./dsh.js";
+// harness 代理开关聚合：Claude Code / Codex CLI / DeepSeek Harness 流量指向本机 ellm-proxy 网关。
+//   纯开关实现：claude-code.js（~/.claude/settings.json）/ codex.js（~/.codex/config.toml）/
+//   dsh.js（~/.dsh/settings.yaml + ~/.dsh/.credentials.yaml）/ backup.js（共用备份还原）
+//   createHarnessApp = HTTP 路由子应用（挂载于 /harness）：状态查询 + 开关切换（含 masterKey 校验与提示文案）
+import { Hono } from "hono";
+import { readFileSync } from "node:fs";
+import { resolveGatewayBase } from "../../../utils/service.js";
+import { claudeCodeStatus, claudeCodeEnable, claudeCodeDisable } from "./claude-code.js";
+import { codexStatus, codexEnable, codexDisable } from "./codex.js";
+import { dshStatus, dshEnable, dshDisable } from "./dsh.js";
+
+/** 配置文件顶层 masterKey（Claude Code 代理的 AUTH_TOKEN 取值；网关侧用它做鉴权） */
+function readMasterKey(configFile) {
+  try {
+    return JSON.parse(readFileSync(configFile, "utf-8")).masterKey || "";
+  } catch {
+    return "";
+  }
+}
+
+/** harness 开关子应用（挂载于 /harness）：GET / · POST /claude-code · POST /codex · POST /dsh（body {enabled}） */
+export function createHarnessApp({ startOpts }) {
+  const app = new Hono();
+
+  // GET /harness：三个开关状态
+  app.get("/", (c) => {
+    const { base } = resolveGatewayBase(startOpts.config);
+    return c.json({ ok: true, claudeCode: claudeCodeStatus(base), codex: codexStatus(), dsh: dshStatus(base), gatewayBase: base });
+  });
+
+  /** 读 body 并校验 enabled；合法返回 boolean，非法返回 400 Response（调用方直接 return 该响应） */
+  const requireEnabled = async (c) => {
+    let enabled;
+    try {
+      enabled = (await c.req.json())?.enabled;
+    } catch {
+      return c.json({ ok: false, error: "请求体不是合法 JSON" }, 400);
+    }
+    if (typeof enabled !== "boolean") {
+      return c.json({ ok: false, error: 'body 需为 {"enabled": true|false}' }, 400);
+    }
+    return enabled;
+  };
+
+  app.post("/claude-code", async (c) => {
+    const enabled = await requireEnabled(c);
+    if (enabled instanceof Response) return enabled;
+    const { base, configFile } = resolveGatewayBase(startOpts.config);
+    if (enabled) {
+      const masterKey = readMasterKey(configFile);
+      if (!masterKey) {
+        return c.json(
+          {
+            ok: false,
+            error: `配置未设置 masterKey，Claude Code 代理无法鉴权。请先在配置文件中设置 masterKey: ${configFile}`,
+          },
+          400,
+        );
+      }
+      claudeCodeEnable({ gatewayBase: base, token: masterKey });
+      return c.json({
+        ok: true,
+        claudeCode: true,
+        file: "~/.claude/settings.json",
+        note: "已备份原文件为 settings.json.ellm-bak，重启 Claude Code 会话后生效",
+      });
+    }
+    const changed = claudeCodeDisable(base);
+    return c.json({ ok: true, claudeCode: false, changed, note: changed ? "已从备份还原" : "原本未开启，无操作" });
+  });
+
+  app.post("/codex", async (c) => {
+    const enabled = await requireEnabled(c);
+    if (enabled instanceof Response) return enabled;
+    const { base, configFile } = resolveGatewayBase(startOpts.config);
+    if (enabled) {
+      codexEnable({ gatewayBase: base });
+      const masterKey = readMasterKey(configFile);
+      return c.json({
+        ok: true,
+        codex: true,
+        file: "~/.codex/config.toml",
+        note: masterKey
+          ? `已备份原文件为 config.toml.ellm-bak；请设置环境变量 ELLM_PROXY_API_KEY=${masterKey}（Codex 以 env_key 读取鉴权）`
+          : "已备份原文件为 config.toml.ellm-bak；请设置环境变量 ELLM_PROXY_API_KEY（网关未配 masterKey 时取值任意）",
+      });
+    }
+    const changed = codexDisable();
+    return c.json({ ok: true, codex: false, changed, note: changed ? "已从备份还原" : "原本未开启，无操作" });
+  });
+
+  app.post("/dsh", async (c) => {
+    const enabled = await requireEnabled(c);
+    if (enabled instanceof Response) return enabled;
+    const { base, configFile } = resolveGatewayBase(startOpts.config);
+    const masterKey = readMasterKey(configFile);
+    if (enabled) {
+      dshEnable({ gatewayBase: base, masterKey });
+      return c.json({
+        ok: true,
+        dsh: true,
+        file: "~/.dsh/settings.yaml",
+        note: masterKey
+          ? "已写入 settings.yaml（llm-deepseek.baseURL）与 .credentials.yaml（refs.DEEPSEEK_API_KEY），原文件备份为 *.ellm-bak。注意：进程环境里已设 DEEPSEEK_API_KEY 时其优先级更高，需自行改用网关 masterKey；模型请在 dsh 内选择与网关部署名一致的模型"
+          : "已写入 settings.yaml 与 .credentials.yaml（网关未配 masterKey，密钥为占位值即可放行），原文件备份为 *.ellm-bak。模型请在 dsh 内选择与网关部署名一致的模型",
+      });
+    }
+    const changed = dshDisable(base, masterKey);
+    return c.json({ ok: true, dsh: false, changed, note: changed ? "已从备份还原（或移除本开关写入的字段）" : "原本未开启，无操作" });
+  });
+
+  return app;
+}
+
+// 纯开关函数同时聚合导出（供不经过 HTTP 的调用方直接使用）
+export * from "./claude-code.js";
+export * from "./codex.js";
+export * from "./dsh.js";