@xiaozhi-client/config 1.9.4-beta.5

package/src/adapter.ts

@@ -0,0 +1,432 @@
+/**
+ * 配置适配器
+ * 将旧的配置格式转换为新的 MCPServiceConfig 格式，确保向后兼容性
+ */
+
+import { isAbsolute, resolve } from "node:path";
+import type {
+  LocalMCPServerConfig,
+  MCPServerConfig,
+  SSEMCPServerConfig,
+  StreamableHTTPMCPServerConfig,
+} from "./manager.js";
+
+// 从外部导入 MCP 类型（这些类型将在运行时从 backend 包解析）
+// 为了避免循环依赖，这里使用动态导入的方式
+// 在实际使用时，adapter 将作为 config 包的一部分被使用
+
+/**
+ * 配置验证错误类
+ */
+export class ConfigValidationError extends Error {
+  constructor(
+    message: string,
+    public readonly configName?: string
+  ) {
+    super(message);
+    this.name = "ConfigValidationError";
+  }
+}
+
+// 定义简化的 MCP 传输类型（与 core/mcp/types 保持一致）
+export enum MCPTransportType {
+  STDIO = "stdio",
+  SSE = "sse",
+  STREAMABLE_HTTP = "streamable-http",
+}
+
+// 定义简化的 MCPServiceConfig 接口
+export interface MCPServiceConfig {
+  name: string;
+  type: MCPTransportType;
+  command?: string;
+  args?: string[];
+  env?: Record<string, string>;
+  url?: string;
+  timeout?: number;
+  headers?: Record<string, string>;
+  modelScopeAuth?: boolean;
+}
+
+/**
+ * URL 类型推断函数
+ * 与 MCPService 的推断逻辑保持一致
+ * 基于 URL 路径末尾推断传输类型
+ */
+function inferTransportTypeFromUrl(url: string): MCPTransportType {
+  try {
+    const parsedUrl = new URL(url);
+    const pathname = parsedUrl.pathname;
+
+    // 检查路径末尾
+    if (pathname.endsWith("/sse")) {
+      return MCPTransportType.SSE;
+    }
+    if (pathname.endsWith("/mcp")) {
+      return MCPTransportType.STREAMABLE_HTTP;
+    }
+
+    // 默认类型
+    return MCPTransportType.STREAMABLE_HTTP;
+  } catch (error) {
+    // URL 解析失败时使用默认类型
+    return MCPTransportType.STREAMABLE_HTTP;
+  }
+}
+
+/**
+ * 将旧的 MCPServerConfig 转换为新的 MCPServiceConfig
+ */
+export function convertLegacyToNew(
+  serviceName: string,
+  legacyConfig: MCPServerConfig
+): MCPServiceConfig {
+  console.log("转换配置", { serviceName, legacyConfig });
+
+  try {
+    // 验证输入参数
+    if (!serviceName || typeof serviceName !== "string") {
+      throw new ConfigValidationError("服务名称必须是非空字符串");
+    }
+
+    if (!legacyConfig || typeof legacyConfig !== "object") {
+      throw new ConfigValidationError("配置对象不能为空", serviceName);
+    }
+
+    // 根据配置类型进行转换
+    const newConfig = convertByConfigType(serviceName, legacyConfig);
+
+    // 验证转换后的配置
+    validateNewConfig(newConfig);
+
+    console.log("配置转换成功", { serviceName, type: newConfig.type });
+    return newConfig;
+  } catch (error) {
+    console.error("配置转换失败", { serviceName, error });
+    throw error instanceof ConfigValidationError
+      ? error
+      : new ConfigValidationError(
+          `配置转换失败: ${error instanceof Error ? error.message : String(error)}`,
+          serviceName
+        );
+  }
+}
+
+/**
+ * 根据配置类型进行转换
+ */
+function convertByConfigType(
+  serviceName: string,
+  legacyConfig: MCPServerConfig
+): MCPServiceConfig {
+  // 检查是否为本地 stdio 配置（最高优先级）
+  if (isLocalConfig(legacyConfig)) {
+    return convertLocalConfig(serviceName, legacyConfig);
+  }
+
+  // 检查是否有显式指定的类型
+  if ("type" in legacyConfig) {
+    switch (legacyConfig.type) {
+      case "sse":
+        return convertSSEConfig(serviceName, legacyConfig);
+      case "streamable-http":
+        return convertStreamableHTTPConfig(serviceName, legacyConfig);
+      default:
+        throw new ConfigValidationError(
+          `不支持的传输类型: ${legacyConfig.type}`,
+          serviceName
+        );
+    }
+  }
+
+  // 检查是否为网络配置（自动推断类型）
+  if ("url" in legacyConfig) {
+    // 如果 URL 是 undefined 或 null，抛出错误
+    if (legacyConfig.url === undefined || legacyConfig.url === null) {
+      throw new ConfigValidationError(
+        "网络配置必须包含有效的 url 字段",
+        serviceName
+      );
+    }
+
+    // 先推断类型，然后根据推断的类型选择正确的转换函数
+    const inferredType = inferTransportTypeFromUrl(legacyConfig.url || "");
+
+    if (inferredType === MCPTransportType.SSE) {
+      // 为SSE类型添加显式type字段
+      const sseConfig = { ...legacyConfig, type: "sse" as const };
+      return convertSSEConfig(serviceName, sseConfig);
+    }
+    // 为STREAMABLE_HTTP类型添加显式type字段
+    const httpConfig = { ...legacyConfig, type: "streamable-http" as const };
+    return convertStreamableHTTPConfig(serviceName, httpConfig);
+  }
+
+  throw new ConfigValidationError("无法识别的配置类型", serviceName);
+}
+
+/** * 转换本地 stdio 配置 */
+function convertLocalConfig(
+  serviceName: string,
+  config: LocalMCPServerConfig
+): MCPServiceConfig {
+  if (!config.command) {
+    throw new ConfigValidationError(
+      "本地配置必须包含 command 字段",
+      serviceName
+    );
+  }
+
+  // 获取用户的工作目录（优先使用环境变量，否则使用当前工作目录）
+  const workingDir = process.env.XIAOZHI_CONFIG_DIR || process.cwd();
+
+  // 解析 args 中的相对路径
+  const resolvedArgs = (config.args || []).map((arg) => {
+    // 检查是否为相对路径（以 ./ 开头或不以 / 开头且包含文件扩展名）
+    if (isRelativePath(arg)) {
+      const resolvedPath = resolve(workingDir, arg);
+      console.log("解析相对路径", { arg, resolvedPath });
+      return resolvedPath;
+    }
+    return arg;
+  });
+
+  return {
+    name: serviceName,
+    type: MCPTransportType.STDIO,
+    command: config.command,
+    args: resolvedArgs,
+    env: config.env, // 传递环境变量
+    timeout: 30000,
+  };
+}
+
+/**
+ * 转换 SSE 配置
+ */
+function convertSSEConfig(
+  serviceName: string,
+  config: SSEMCPServerConfig
+): MCPServiceConfig {
+  if (config.url === undefined || config.url === null) {
+    throw new ConfigValidationError("SSE 配置必须包含 url 字段", serviceName);
+  }
+
+  // 优先使用显式指定的类型，如果没有则进行推断
+  const inferredType =
+    config.type === "sse"
+      ? MCPTransportType.SSE
+      : inferTransportTypeFromUrl(config.url || "");
+  const isModelScope = config.url ? isModelScopeURL(config.url) : false;
+
+  const baseConfig: MCPServiceConfig = {
+    name: serviceName,
+    type: inferredType,
+    url: config.url,
+    timeout: 30000,
+    headers: config.headers,
+  };
+
+  // 如果是 ModelScope 服务，添加特殊配置
+  if (isModelScope) {
+    baseConfig.modelScopeAuth = true;
+  }
+
+  console.log("SSE配置转换", {
+    serviceName,
+    url: config.url,
+    inferredType,
+    isModelScope,
+  });
+
+  return baseConfig;
+}
+
+/**
+ * 转换 Streamable HTTP 配置
+ */
+function convertStreamableHTTPConfig(
+  serviceName: string,
+  config: StreamableHTTPMCPServerConfig
+): MCPServiceConfig {
+  // 检查 URL 是否存在
+  if (config.url === undefined || config.url === null) {
+    throw new ConfigValidationError(
+      "STREAMABLE_HTTP 配置必须包含 url 字段",
+      serviceName
+    );
+  }
+
+  const url = config.url || "";
+
+  return {
+    name: serviceName,
+    type: MCPTransportType.STREAMABLE_HTTP,
+    url,
+    timeout: 30000,
+    headers: config.headers,
+  };
+}
+
+/**
+ * 批量转换配置
+ */
+export function convertLegacyConfigBatch(
+  legacyConfigs: Record<string, MCPServerConfig>
+): Record<string, MCPServiceConfig> {
+  const newConfigs: Record<string, MCPServiceConfig> = {};
+  const errors: Array<{ serviceName: string; error: Error }> = [];
+
+  for (const [serviceName, legacyConfig] of Object.entries(legacyConfigs)) {
+    try {
+      newConfigs[serviceName] = convertLegacyToNew(serviceName, legacyConfig);
+    } catch (error) {
+      errors.push({
+        serviceName,
+        error: error instanceof Error ? error : new Error(String(error)),
+      });
+    }
+  }
+
+  if (errors.length > 0) {
+    const errorMessages = errors
+      .map(({ serviceName, error }) => `${serviceName}: ${error.message}`)
+      .join("; ");
+    throw new ConfigValidationError(`批量配置转换失败: ${errorMessages}`);
+  }
+
+  console.log("批量配置转换成功", { count: Object.keys(newConfigs).length });
+  return newConfigs;
+}
+
+/**
+ * 检查是否为相对路径
+ */
+function isRelativePath(path: string): boolean {
+  // 使用 Node.js 的 path.isAbsolute() 来正确检测绝对路径
+  // 这个方法能够正确处理 Windows、macOS、Linux 三个平台的路径格式
+  if (isAbsolute(path)) {
+    return false; // 绝对路径不是相对路径
+  }
+
+  // 检查是否为相对路径的条件：
+  // 1. 以 ./ 或 ../ 开头
+  // 2. 包含常见的脚本文件扩展名（且不是绝对路径）
+  if (path.startsWith("./") || path.startsWith("../")) {
+    return true;
+  }
+
+  // 如果包含文件扩展名且不是绝对路径，也认为是相对路径
+  if (/\.(js|py|ts|mjs|cjs)$/i.test(path)) {
+    return true;
+  }
+
+  return false;
+}
+
+/**
+ * 检查是否为本地配置
+ */
+function isLocalConfig(
+  config: MCPServerConfig
+): config is LocalMCPServerConfig {
+  return "command" in config && typeof config.command === "string";
+}
+
+/**
+ * 检查是否为 ModelScope URL
+ * 使用 URL hostname 检查而非简单的字符串包含检查，防止安全绕过
+ */
+export function isModelScopeURL(url: string): boolean {
+  try {
+    const parsedUrl = new URL(url);
+    const hostname = parsedUrl.hostname.toLowerCase();
+    return (
+      hostname.endsWith(".modelscope.net") ||
+      hostname.endsWith(".modelscope.cn") ||
+      hostname === "modelscope.net" ||
+      hostname === "modelscope.cn"
+    );
+  } catch {
+    return false;
+  }
+}
+
+/**
+ * 验证新配置格式
+ */
+function validateNewConfig(config: MCPServiceConfig): void {
+  if (!config.name || typeof config.name !== "string") {
+    throw new ConfigValidationError("配置必须包含有效的 name 字段");
+  }
+
+  if (config.type && !Object.values(MCPTransportType).includes(config.type)) {
+    throw new ConfigValidationError(`无效的传输类型: ${config.type}`);
+  }
+
+  // 根据传输类型验证必需字段
+  if (!config.type) {
+    throw new ConfigValidationError("传输类型未指定，请检查配置或启用自动推断");
+  }
+
+  switch (config.type) {
+    case MCPTransportType.STDIO:
+      if (!config.command) {
+        throw new ConfigValidationError("STDIO 配置必须包含 command 字段");
+      }
+      break;
+
+    case MCPTransportType.SSE:
+      // SSE 配置必须有 URL（即使是空字符串也会被推断为 STREAMABLE_HTTP）
+      if (config.url === undefined || config.url === null) {
+        throw new ConfigValidationError("SSE 配置必须包含 url 字段");
+      }
+      break;
+
+    case MCPTransportType.STREAMABLE_HTTP:
+      // STREAMABLE_HTTP 配置允许空 URL，会在后续处理中设置默认值
+      // 只有当 URL 完全不存在时才报错
+      if (config.url === undefined || config.url === null) {
+        throw new ConfigValidationError(
+          "STREAMABLE_HTTP 配置必须包含 url 字段"
+        );
+      }
+      break;
+
+    default:
+      throw new ConfigValidationError(`不支持的传输类型: ${config.type}`);
+  }
+}
+
+/**
+ * 获取配置类型描述
+ */
+export function getConfigTypeDescription(config: MCPServerConfig): string {
+  if (isLocalConfig(config)) {
+    return `本地进程 (${config.command})`;
+  }
+
+  if ("url" in config) {
+    // 检查是否为显式 streamable-http 配置
+    if ("type" in config && config.type === "streamable-http") {
+      return `Streamable HTTP (${config.url})`;
+    }
+
+    // 检查是否为显式 sse 配置
+    if ("type" in config && config.type === "sse") {
+      const isModelScope = isModelScopeURL(config.url);
+      return `SSE${isModelScope ? " (ModelScope)" : ""} (${config.url})`;
+    }
+
+    // 对于只有 url 的配置，根据路径推断类型
+    const inferredType = inferTransportTypeFromUrl(config.url);
+    const isModelScope = isModelScopeURL(config.url);
+
+    if (inferredType === MCPTransportType.SSE) {
+      return `SSE${isModelScope ? " (ModelScope)" : ""} (${config.url})`;
+    }
+    return `Streamable HTTP (${config.url})`;
+  }
+
+  return "未知类型";
+}

package/src/index.ts

@@ -0,0 +1,2 @@
+export * from "./manager.js";
+export * from "./adapter.js";

package/src/json5-adapter.ts

@@ -0,0 +1,52 @@
+/**
+ * JSON5 注释保留适配器
+ * 使用 comment-json 实现 JSON5/JSONC 注释保留功能
+ *
+ * 注意：为了使用 comment-json 保留注释，JSON5 配置文件的键需要带引号。
+ * 这与 JSON5 标准语法允许不带引号的键略有不同，但能实现注释保留功能。
+ */
+import * as commentJson from "comment-json";
+
+/**
+ * JSON5 写入器适配器接口
+ * 保持与 json5-writer 兼容的 API
+ */
+export interface Json5WriterAdapter {
+  write(data: unknown): void;
+  toSource(): string;
+}
+
+/**
+ * 创建 JSON5 写入器适配器
+ * @param content 原始 JSON5 内容字符串
+ * @returns Json5WriterAdapter 实例
+ */
+export function createJson5Writer(content: string): Json5WriterAdapter {
+  // 使用 comment-json 解析原始内容
+  // comment-json 会保留注释信息在返回的对象中
+  const parsedData = commentJson.parse(content) as Record<string, unknown>;
+
+  return {
+    write(data: unknown): void {
+      // 通过 Object.assign 合并新数据
+      if (parsedData && typeof parsedData === "object" && data) {
+        Object.assign(parsedData, data);
+      }
+    },
+
+    toSource(): string {
+      // 使用 comment-json 序列化，保留注释和格式
+      return commentJson.stringify(parsedData, null, 2);
+    },
+  };
+}
+
+/**
+ * 解析 JSON5 内容(带注释保留)
+ * @param content JSON5 内容字符串
+ * @returns 解析后的对象
+ */
+export function parseJson5(content: string): unknown {
+  // 使用 comment-json 解析，支持注释保留
+  return commentJson.parse(content);
+}