custom-provider-pi 0.1.0

package/custom-provider.ts

@@ -0,0 +1,2066 @@
+import { readFileSync, writeFileSync, existsSync, mkdirSync } from "fs";
+import { execSync } from "child_process";
+import { homedir } from "os";
+import { join } from "path";
+import https from "https";
+import http from "http";
+import type { ExtensionAPI, ProviderConfig, ProviderModelConfig } from "@earendil-works/pi-coding-agent";
+
+const CONFIG_PATH = join(homedir(), ".pi", "agent", "custom-providers.json");
+const SPEC_CACHE_PATH = join(homedir(), ".pi", "agent", "model-specs-cache.json");
+
+// 远程规格缓存有效期（毫秒）：24 小时
+const SPEC_CACHE_TTL = 24 * 60 * 60 * 1000;
+// OpenRouter 公开模型目录（含各模型真实 context_length / max_completion_tokens，无需 key）
+const OPENROUTER_MODELS_URL = "https://openrouter.ai/api/v1/models";
+
+// 默认浏览器 UA：部分中转/反代服务（如 Cloudflare WAF）会按 User-Agent 指纹拦截
+// SDK 请求（OpenAI/JS、Anthropic/JS 等）。未显式配置 UA 时默认使用浏览器 UA 规避。
+// 官方 API（OpenAI/Anthropic/DeepSeek 等）不校验 UA，此默认值对其无副作用。
+const DEFAULT_USER_AGENT =
+  "Mozilla/5.0 (Windows NT 10.0; Win64; x64) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/120.0.0.0 Safari/537.36";
+
+// 预设 User-Agent：部分中转/反代服务会按 UA 指纹拦截非浏览器/SDK 请求。
+// 版本号取各 CLI/工具当前最新稳定版（2026-08 查询），反代一般只校验前缀关键字。
+const UA_PRESETS: Record<string, string> = {
+  "browser": "Mozilla/5.0 (Windows NT 10.0; Win64; x64) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/131.0.0.0 Safari/537.36",
+  // 真实 Claude Code 发送格式为 claude-code/<版本>（无后缀）
+  "claude-code": "claude-code/2.1.237",
+  "codex": "codex_cli_rs/0.148.0 (cli)",
+  "opencode": "opencode/1.18.19",
+  "cursor": "Cursor/3.16.0 (Windows; 64bit)",
+  "windsurf": "Windsurf/2.0.0 (Windows)",
+  "openwebui": "OpenWebUI/0.11.0",
+  "chatgpt": "Mozilla/5.0 (Windows NT 10.0; Win64; x64) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/131.0.0.0 Safari/537.36 ChatGPT-Desktop/1.2025.0",
+};
+
+// 请求头模板（借鉴 LiveAgent：按客户端/CLI 预设整组请求头，而非只预设 UA）：
+// 不同客户端携带的头集合不同（Claude Code 有 x-app/anthropic-version/X-Stainless-* 等）。
+// 选模板一次性灌入；选「自定义」逐头输入。
+interface HeaderPreset {
+  label: string;
+  key?: string; // undefined = 自定义
+  headers: Record<string, string>;
+}
+const HEADER_PRESETS: HeaderPreset[] = [
+  { label: "浏览器（默认，仅 UA）", key: "browser", headers: { "User-Agent": UA_PRESETS.browser } },
+  {
+    label: "Claude Code CLI",
+    key: "claude-code",
+    headers: {
+      "User-Agent": UA_PRESETS["claude-code"],
+      "x-app": "cli",
+      "anthropic-version": "2023-06-01",
+      "content-type": "application/json",
+      "anthropic-dangerous-direct-browser-access": "true",
+    },
+  },
+  {
+    label: "Codex CLI",
+    key: "codex",
+    headers: { "User-Agent": UA_PRESETS.codex, "accept": "application/json" },
+  },
+  { label: "OpenCode CLI", key: "opencode", headers: { "User-Agent": UA_PRESETS.opencode } },
+  { label: "Cursor IDE", key: "cursor", headers: { "User-Agent": UA_PRESETS.cursor } },
+  { label: "Windsurf IDE", key: "windsurf", headers: { "User-Agent": UA_PRESETS.windsurf } },
+  {
+    label: "OpenWebUI",
+    key: "openwebui",
+    headers: { "User-Agent": UA_PRESETS.openwebui, "accept": "application/json" },
+  },
+  { label: "ChatGPT Desktop", key: "chatgpt", headers: { "User-Agent": UA_PRESETS.chatgpt } },
+  { label: "自定义（逐头输入）", key: undefined, headers: {} },
+];
+
+// 头名校验：HTTP token 字符集（含 ASCII 特殊符号，无空格/换行）
+const HEADER_NAME_RE = /^[!#$%&'*+\-.^_`|~0-9A-Za-z]+$/;
+// 头值只允许可见 ASCII 与制表符：CR/LF 会造成 header 注入，非 ASCII 可能让请求出错
+const HEADER_VALUE_RE = /^[\t\x20-\x7e]*$/;
+// 设置这些头可能覆盖认证/协议逻辑：允许但给予提示
+const SENSITIVE_HEADER_HINTS = ["authorization", "x-api-key", "x-goog-api-key", "anthropic-beta", "host", "content-length"];
+
+// 合法的 provider 名称：小写字母/数字/中划线/下划线，长度 1-32
+const NAME_RE = /^[a-zA-Z0-9][a-zA-Z0-9_-]{0,31}$/;
+
+function hasHeader(headers: Record<string, string> | undefined, name: string): boolean {
+  if (!headers) return false;
+  const lower = name.toLowerCase();
+  return Object.keys(headers).some((k) => k.toLowerCase() === lower);
+}
+
+// ---- 远程规格查询（OpenRouter 公开目录，带磁盘缓存）----
+
+// 输出上限处置（借鉴 LiveAgent normalizeModelLimits）
+// 社区目录/中转对不公布独立输出上限的模型常给退化值「输出==窗口」，
+// 照单全收会把「窗口−输出预留」的输入预算挤成零。处理：钳到保守上限，
+// 并保底留 3/4 窗口给输入。
+const MAX_OUTPUT_TOKEN_CAP = 32000;
+
+function normalizeModelLimits(ctx: number, out: number): { contextWindow: number; maxTokens: number } {
+  if (ctx <= 0) return { contextWindow: ctx, maxTokens: out };
+  if (out < ctx) return { contextWindow: ctx, maxTokens: out };
+  return {
+    contextWindow: ctx,
+    maxTokens: Math.min(MAX_OUTPUT_TOKEN_CAP, Math.max(1, Math.floor(ctx / 4))),
+  };
+}
+
+// 长上下文后缀约定：部分中转用 [1m] 标记模型为 1M 长上下文形态
+function hasLongContextSuffix(modelId: string): boolean {
+  return /\[1m\]$/i.test(modelId.trim());
+}
+
+// 官方 Anthropic/Vertex/Bedrock 端点不支持 1M 上下文（1M 仅第三方中转可用）
+function isOfficialAnthropicEndpoint(baseUrl: string | undefined): boolean {
+  const lower = (baseUrl ?? "").toLowerCase();
+  return (
+    lower.includes("api.anthropic.com") ||
+    lower.includes("aiplatform.googleapis.com") ||
+    lower.includes("vertexai.googleapis.com") ||
+    lower.includes("amazonaws.com")
+  );
+}
+
+// 按协议/API 类型的未知模型兜底限额（借鉴 LiveAgent PROVIDER_FALLBACK_LIMITS）
+const PROVIDER_FALLBACK: Record<string, { contextWindow: number; maxTokens: number }> = {
+  "anthropic-messages": { contextWindow: 200000, maxTokens: 32000 },
+  "google-generative-ai": { contextWindow: 1048576, maxTokens: 65536 },
+  "openai-completions": { contextWindow: 258000, maxTokens: 32000 },
+  "openai-responses": { contextWindow: 258000, maxTokens: 32000 },
+};
+const FALLBACK_DEFAULT: { contextWindow: number; maxTokens: number } = {
+  contextWindow: 128000,
+  maxTokens: 32000,
+};
+
+// 远程规格表：normalize 后的模型 id -> { contextWindow, maxTokens }
+let remoteSpecStore: Map<string, { contextWindow: number; maxTokens: number }> | null = null;
+
+// 归一化候选链（借鉴 LiveAgent normalizeModelIdCandidates）：
+// 原始 id → 小写 → 去 @版本 → 去 [1m] 后缀 → 去日期段 → 去变体词 → 剥路径前缀。
+// 候选链让目录命中覆盖中转常见的装饰：bailian/deepseek-v4-pro、xxx@20250601、xxx[1m] 等。
+function normalizeModelIdCandidates(modelId: string): string[] {
+  const candidates: string[] = [];
+  const push = (v: string) => {
+    if (v && !candidates.includes(v)) candidates.push(v);
+  };
+  const raw = modelId.trim();
+  push(raw);
+  const lower = raw.toLowerCase();
+  push(lower);
+  const withoutAt = lower.split("@")[0];
+  push(withoutAt);
+  const withoutSuffix = withoutAt.replace(/\[1m\]$/i, "");
+  push(withoutSuffix);
+  push(withoutSuffix.replace(/-20\d{6}$/, "")); // 日期段 -20250601
+  push(withoutSuffix.replace(/-\d{2,9}$/, "")); // 日期/序号 -0731
+  push(
+    withoutSuffix.replace(
+      /-(?:latest|recent|free|preview|stable|thinking|reasoning|turbo|hi|highspeed|dev|beta|auto|labs)$/,
+      ""
+    )
+  );
+  // 路径前缀（bailian/x → x）放链尾：所有精确形态查空后才剥前缀
+  const lastSegment = withoutSuffix.split("/").pop() ?? "";
+  if (lastSegment && lastSegment !== withoutSuffix) {
+    push(lastSegment);
+    push(lastSegment.replace(/-20\d{6}$/, ""));
+  }
+  return candidates;
+}
+
+// 将 OpenRouter 模型目录灌入远程规格表（同 id 多条时取更大上下文）
+function ingestRemoteModels(data: any[]): void {
+  if (!remoteSpecStore) remoteSpecStore = new Map();
+  for (const m of data) {
+    const ctx = m.context_length;
+    // 部分模型未公布 max_completion_tokens（如 grok-4.5），给保守默认避免整条被跳过
+    const rawOut = (m.top_provider?.max_completion_tokens ?? m.max_completion_tokens) ?? 131072;
+    if (!ctx) continue;
+    // 入库即卫生化：输出吃满窗口的退化数据钳到保守上限，避免输入预算被挤成零
+    const limited = normalizeModelLimits(Number(ctx), rawOut);
+    const key = normalizeModelIdCandidates(m.id)[4] ?? m.id.toLowerCase(); // 去 @ 与 [1m] 后的规范形
+    const prev = remoteSpecStore.get(key);
+    if (
+      !prev ||
+      limited.contextWindow > prev.contextWindow ||
+      (limited.contextWindow === prev.contextWindow && limited.maxTokens > prev.maxTokens)
+    ) {
+      remoteSpecStore.set(key, limited);
+    }
+  }
+}
+
+function loadSpecCache(): void {
+  try {
+    if (!existsSync(SPEC_CACHE_PATH)) return;
+    const raw = JSON.parse(readFileSync(SPEC_CACHE_PATH, "utf8"));
+    if (Date.now() - (raw.fetchedAt || 0) > SPEC_CACHE_TTL) return;
+    remoteSpecStore = new Map(raw.specs ?? []);
+  } catch {
+    remoteSpecStore = null;
+  }
+}
+
+function saveSpecCache(): void {
+  try {
+    if (!remoteSpecStore) return;
+    writeFileSync(
+      SPEC_CACHE_PATH,
+      JSON.stringify({ fetchedAt: Date.now(), specs: [...remoteSpecStore.entries()] }),
+      "utf8"
+    );
+  } catch {
+    /* 缓存写失败不影响主流程 */
+  }
+}
+
+// 从 OpenRouter 拉取模型目录并刷新本地规格表；失败静默降级（不影响已有配置/预设）
+async function refreshRemoteSpecs(): Promise<void> {
+  try {
+    // 模型目录较大（~700KB），放宽超时到 30s；后台异步执行不阻塞启动
+    const json = await httpGet(OPENROUTER_MODELS_URL, undefined, undefined, 30000);
+    if (!json?.data || !Array.isArray(json.data)) throw new Error("OpenRouter 响应格式异常");
+    ingestRemoteModels(json.data);
+    saveSpecCache();
+  } catch (error) {
+    console.error(
+      `[custom-provider] 拉取模型规格失败（使用缓存/预设降级）: ${
+        error instanceof Error ? error.message : String(error)
+      }`
+    );
+  }
+}
+
+// 查询模型规格：远程实时表 → 本地已知预设 → undefined
+function lookupModelSpec(modelId: string): { contextWindow: number; maxTokens: number } | undefined {
+  if (remoteSpecStore && remoteSpecStore.size > 0) {
+    // 候选链逐形态命中：deepseek-v4-flash-free → deepseek-v4-flash → deepseek-v4 …
+    for (const candidate of normalizeModelIdCandidates(modelId)) {
+      const hit = remoteSpecStore.get(candidate);
+      if (hit) return hit;
+      // 渐进去尾段（- 连接）：最后一个候选之后逐步剥段
+      let probe = candidate;
+      for (let i = 0; i < 6 && probe; i++) {
+        const idx = probe.lastIndexOf("-");
+        if (idx <= 0) break;
+        probe = probe.slice(0, idx);
+        const h = remoteSpecStore.get(probe);
+        if (h) return h;
+      }
+    }
+  }
+  return getKnownSpec(modelId);
+}
+
+// ---- 本地已知规格预设（离线兜底；远程规格优先于它）----
+const KNOWN_SPECS: Record<string, { contextWindow: number; maxTokens: number }> = {
+  // DeepSeek V4（1M 上下文为输入+输出共享预算）
+  "deepseek-v4-flash": { contextWindow: 1000000, maxTokens: 384000 },
+  "deepseek-v4-pro": { contextWindow: 1000000, maxTokens: 384000 },
+  // 智谱 GLM-5 系列
+  "glm-5": { contextWindow: 200000, maxTokens: 131072 },
+  "glm-5.1": { contextWindow: 200000, maxTokens: 131072 },
+  "glm-5.2": { contextWindow: 200000, maxTokens: 131072 },
+  "glm-5.3": { contextWindow: 200000, maxTokens: 131072 },
+  // xAI Grok（4.5/4.6 输出上限未官宣，取 128K 保守值）
+  "grok-4.5": { contextWindow: 500000, maxTokens: 131072 },
+  "grok-4.6": { contextWindow: 500000, maxTokens: 131072 },
+  // 腾讯混元 Hy3
+  "hy3": { contextWindow: 256000, maxTokens: 131072 },
+  "hy3-preview": { contextWindow: 256000, maxTokens: 131072 },
+  // MiniMax M2.x 系列（官方未公布超大上下文，保守 256K）
+  "mimo-v2": { contextWindow: 262144, maxTokens: 65536 },
+  "mimo-v2.1": { contextWindow: 262144, maxTokens: 65536 },
+  "mimo-v2.5": { contextWindow: 262144, maxTokens: 65536 },
+  "minimax-m2": { contextWindow: 262144, maxTokens: 65536 },
+};
+
+function getKnownSpec(modelId: string): { contextWindow: number; maxTokens: number } | undefined {
+  const candidates = normalizeModelIdCandidates(modelId);
+  for (const c of candidates) {
+    if (KNOWN_SPECS[c]) return KNOWN_SPECS[c];
+  }
+  // 前缀匹配兜底（deepseek-v4-flash-free → deepseek-v4-flash）
+  const key = Object.keys(KNOWN_SPECS).find((k) =>
+    candidates.some((c) => c === k || c.startsWith(k + "-") || c.startsWith(k + "_") || c.startsWith(k + ":"))
+  );
+  return key ? KNOWN_SPECS[key] : undefined;
+}
+
+interface IModel {
+  id: string;
+  name?: string;
+  api?: string;
+  baseUrl?: string;
+  reasoning?: boolean;
+  input?: ("text" | "image")[];
+  contextWindow?: number;
+  maxTokens?: number;
+  cost?: {
+    input?: number;
+    output?: number;
+    cacheRead?: number;
+    cacheWrite?: number;
+  };
+  headers?: Record<string, string>;
+  compat?: Record<string, any>;
+}
+
+interface IProvider {
+  name: string;
+  baseUrl: string;
+  api?: string;
+  apiKey?: string;
+  headers?: Record<string, string>;
+  authHeader?: boolean;
+  compat?: Record<string, any>;
+  /** 可选 HTTP/SOCKS 代理地址（含端口，支持 $ENV 引用）。
+   *  生效方式：注册时写入 HTTPS_PROXY/HTTP_PROXY/ALL_PROXY 环境变量，
+   *  需请求库读取这些变量（Node 21+ 的 fetch 需启用 NODE_USE_ENV_PROXY=1） */
+  proxy?: string;
+  /** false 表示已禁用（不注册、不出现在 /model）；缺失视为启用 */
+  enabled?: boolean;
+  models: (string | IModel)[];
+}
+
+interface IConfig {
+  providers: IProvider[];
+}
+
+function loadConfig(): IConfig {
+  try {
+    if (!existsSync(CONFIG_PATH)) return { providers: [] };
+    const raw = readFileSync(CONFIG_PATH, "utf8");
+    const config = JSON.parse(raw) as IConfig;
+    return config;
+  } catch (error) {
+    console.error(`[custom-provider] 读取 ${CONFIG_PATH} 失败:`, error);
+    return { providers: [] };
+  }
+}
+
+function saveConfig(config: IConfig): void {
+  try {
+    const dir = join(homedir(), ".pi", "agent");
+    if (!existsSync(dir)) {
+      mkdirSync(dir, { recursive: true });
+    }
+    writeFileSync(CONFIG_PATH, JSON.stringify(config, null, 2), "utf8");
+  } catch (error) {
+    throw new Error(`保存配置失败: ${error instanceof Error ? error.message : String(error)}`);
+  }
+}
+
+function resolveValue(raw: string | undefined): string {
+  if (!raw) return "local";
+
+  // 环境变量插值: $VAR 或 ${VAR}
+  if (raw.startsWith("$")) {
+    const varName = raw.startsWith("${") && raw.endsWith("}")
+      ? raw.slice(2, -1)
+      : raw.slice(1);
+    return process.env[varName] || "";
+  }
+
+  // 命令执行: !command
+  if (raw.startsWith("!")) {
+    try {
+      return execSync(raw.slice(1), { encoding: "utf8" }).trim();
+    } catch {
+      return "";
+    }
+  }
+
+  return raw;
+}
+
+// 仅用于探测请求（如拉取模型列表）时获取真实值；存储与注册保留原始 $VAR/!cmd 引用，
+// 交由 pi 在每次请求时动态解析，环境变量变更可即时生效。
+function resolveHeaders(headers?: Record<string, string>): Record<string, string> {
+  const resolved: Record<string, string> = {};
+  for (const [key, value] of Object.entries(headers ?? {})) {
+    resolved[key] = resolveValue(value);
+  }
+  return resolved;
+}
+
+function inferApi(baseUrl: string, explicitApi?: string): string {
+  if (explicitApi) return explicitApi;
+
+  const lower = baseUrl.toLowerCase();
+  if (lower.includes("generativelanguage") || lower.includes("generativeai")) {
+    return "google-generative-ai";
+  }
+  if (lower.includes("anthropic")) {
+    return "anthropic-messages";
+  }
+  return "openai-completions";
+}
+
+// 去掉 baseUrl 中用户可能粘贴的多余路径段，返回"规范根地址"（不含 /v1）
+function stripBasePath(baseUrl: string): string {
+  return baseUrl
+    .replace(/\/+$/, "")
+    .replace(/\/v1\/models\/?$/i, "")
+    .replace(/\/chat\/completions\/?$/i, "")
+    .replace(/\/models\/?$/i, "")
+    .replace(/\/+$/, "");
+}
+
+function normalizeBaseUrl(baseUrl: string, api: string): string {
+  const root = stripBasePath(baseUrl);
+
+  switch (api) {
+    case "openai-completions":
+    case "openai-responses":
+    case "anthropic-messages":
+      // OpenAI/Anthropic 兼容协议要求 /v1 前缀；只在"不以 /v1 结尾"时补，
+      // 避免路径中段含 /v1/ 的历史误判
+      return /\/v1$/i.test(root) ? root : `${root}/v1`;
+
+    case "google-generative-ai":
+      // Google Generative AI 需要 /v1beta 或 /v1 前缀
+      if (!/(\/v1|\/v1beta)(\/|$)/i.test(root)) return `${root}/v1`;
+      return root;
+
+    default:
+      return root;
+  }
+}
+
+function prepareModel(raw: string | IModel, provider: IProvider): ProviderModelConfig {
+  const src = typeof raw === "string" ? { id: raw } : raw;
+  if (!src.id) {
+    throw new Error(`provider "${provider.name}" 下存在缺少 id 的模型`);
+  }
+
+  // 协议：模型级覆盖 > provider 级
+  const modelApi = (src.api as string | undefined) ?? inferApi(provider.baseUrl, provider.api);
+  const spec = lookupModelSpec(src.id);
+
+  // 规格填充优先级：显式配置 > [1m] 长上下文规则 > 远程实时规格 > 本地预设 > 按协议兜底
+  const hasExplicitCtx = src.contextWindow !== undefined;
+  const hasExplicitMax = src.maxTokens !== undefined;
+  let contextWindow: number | undefined = src.contextWindow;
+  let maxTokens: number | undefined = src.maxTokens;
+
+  if (!hasExplicitCtx) {
+    if (hasLongContextSuffix(src.id)) {
+      // [1m] 后缀：Anthropic 兼容中转的 1M 形态。
+      // 官方端点（api.anthropic.com / Vertex / Bedrock）不支持 1M，钳回 200K
+      contextWindow = isOfficialAnthropicEndpoint(provider.baseUrl)
+        ? Math.min(spec?.contextWindow ?? 200000, 200000)
+        : 1000000;
+    } else {
+      contextWindow = spec?.contextWindow ?? PROVIDER_FALLBACK[modelApi]?.contextWindow ?? FALLBACK_DEFAULT.contextWindow;
+    }
+  }
+  if (!hasExplicitMax) {
+    maxTokens = spec?.maxTokens ?? PROVIDER_FALLBACK[modelApi]?.maxTokens ?? FALLBACK_DEFAULT.maxTokens;
+  }
+
+  // 数据卫生：非显式的输出值若吃满/超过窗口（社区目录退化数据），
+  // 舞到保守上限并保底留 3/4 窗口给输入，避免 pi 的上下文预算被挤成零。
+  // 显式用户配置完全信任，不自动钳。
+  if (!hasExplicitMax && maxTokens! >= contextWindow!) {
+    const limited = normalizeModelLimits(contextWindow!, maxTokens!);
+    contextWindow = limited.contextWindow;
+    maxTokens = limited.maxTokens;
+  }
+
+  const model: ProviderModelConfig = {
+    id: src.id,
+    name: src.name ?? src.id,
+    reasoning: src.reasoning ?? false,
+    input: src.input ?? ["text"],
+    contextWindow: contextWindow!,
+    maxTokens: maxTokens!,
+    cost: {
+      input: src.cost?.input ?? 0,
+      output: src.cost?.output ?? 0,
+      cacheRead: src.cost?.cacheRead ?? 0,
+      cacheWrite: src.cost?.cacheWrite ?? 0,
+    },
+  };
+  if (src.api) model.api = src.api as any;
+  if (src.baseUrl) model.baseUrl = src.baseUrl;
+  if (src.headers) model.headers = src.headers;
+  if (src.compat) model.compat = src.compat as any;
+  return model;
+}
+
+function buildProviderConfig(provider: IProvider): ProviderConfig {
+  const api = inferApi(provider.baseUrl, provider.api);
+
+  // 请求头原样透传（保留 $ENV / ${ENV} / !cmd 引用），pi 在每次请求时动态解析，
+  // 避免把解析结果明文固化为死值。
+  const providerHeaders: Record<string, string> = { ...(provider.headers ?? {}) };
+
+  // WAF 指纹加固：未显式设置 User-Agent 时，默认补浏览器 UA
+  if (!hasHeader(providerHeaders, "user-agent")) {
+    providerHeaders["User-Agent"] = DEFAULT_USER_AGENT;
+  }
+
+  const providerConfig: ProviderConfig = {
+    name: provider.name,
+    baseUrl: provider.baseUrl,
+    apiKey: provider.apiKey ?? "local",
+    models: provider.models.map((m) => prepareModel(m, provider)),
+  };
+
+  if (Object.keys(providerHeaders).length > 0) {
+    providerConfig.headers = providerHeaders;
+  }
+
+  // authHeader：非标准 API 需要 Authorization: Bearer 时由用户显式开启（pi 负责生成）
+  if (provider.authHeader) {
+    providerConfig.authHeader = true;
+  }
+
+  // 代理：写入环境变量使底层请求走代理（仅当用户显式配置且未设置时；
+  // 注意 Node 的 fetch 需 NODE_USE_ENV_PROXY=1 才启用，详见 README）
+  const proxyUrl = provider.proxy ? resolveValue(provider.proxy) : undefined;
+  if (proxyUrl) {
+    if (!process.env.HTTPS_PROXY) process.env.HTTPS_PROXY = proxyUrl;
+    if (!process.env.HTTP_PROXY) process.env.HTTP_PROXY = proxyUrl;
+    if (!process.env.ALL_PROXY) process.env.ALL_PROXY = proxyUrl;
+  }
+
+  const baseCompat = provider.compat || {};
+  providerConfig.models!.forEach((model) => {
+    if (!model.api) model.api = api as any;
+    if (!model.baseUrl) model.baseUrl = provider.baseUrl;
+    if (!model.compat) model.compat = {};
+    Object.assign(model.compat, baseCompat, model.compat);
+  });
+
+  return providerConfig;
+}
+
+async function fetchModels(
+  baseUrl: string,
+  apiKey: string,
+  api: string,
+  headers?: Record<string, string>
+): Promise<string[]> {
+  const cleanBase = stripBasePath(baseUrl);
+  const v1Base = /\/v1$/i.test(cleanBase) ? cleanBase : `${cleanBase}/v1`;
+
+  // 尝试多种端点路径（google / anthropic 也走标准 /models 列表端点）
+  const endpoints = api === "google-generative-ai"
+    ? [`${v1Base}/models`]
+    : [ `${v1Base}/models`, `${cleanBase}/models`, `${cleanBase}/api/models` ];
+
+  // 按协议组装认证头：anthropic 用 x-api-key，google 用 x-goog-api-key，其余 Bearer
+  const requestHeaders: Record<string, string> = { ...resolveHeaders(headers) };
+  let bearerKey = apiKey;
+  if (api === "anthropic-messages") {
+    if (apiKey) requestHeaders["x-api-key"] = apiKey;
+    requestHeaders["anthropic-version"] = "2023-06-01";
+    bearerKey = "";
+  } else if (api === "google-generative-ai") {
+    if (apiKey) requestHeaders["x-goog-api-key"] = apiKey;
+    bearerKey = "";
+  }
+
+  const attempts: string[] = [];
+
+  for (const url of endpoints) {
+    try {
+      const json = await httpGet(url, bearerKey, requestHeaders);
+
+      // 支持多种响应格式
+      let models: string[] = [];
+      if (json.data && Array.isArray(json.data)) {
+        models = json.data.map((m: any) => m.id || m.name).filter(Boolean);
+      } else if (Array.isArray(json)) {
+        models = json.map((m: any) => m.id || m.name || m).filter(Boolean);
+      } else if (json.models && Array.isArray(json.models)) {
+        models = json.models.map((m: any) => m.id || m.name || m).filter(Boolean);
+      }
+
+      if (models.length > 0) {
+        return models;
+      }
+      attempts.push(`${url} -> 响应中未找到模型列表`);
+    } catch (error) {
+      attempts.push(`${url} -> ${error instanceof Error ? error.message : String(error)}`);
+    }
+  }
+
+  throw new Error(
+    `拉取模型列表失败（已尝试 ${endpoints.length} 个端点）:\n${attempts.join("\n")}`
+  );
+}
+
+function httpGet(
+  url: string,
+  apiKey?: string,
+  extraHeaders?: Record<string, string>,
+  timeoutMs = 10000
+): Promise<any> {
+  return new Promise((resolve, reject) => {
+    const urlObj = new URL(url);
+    const lib = urlObj.protocol === "https:" ? https : http;
+    const options = {
+      hostname: urlObj.hostname,
+      port: urlObj.port,
+      path: urlObj.pathname + urlObj.search,
+      method: "GET",
+      headers: {
+        "User-Agent": DEFAULT_USER_AGENT,
+        "Content-Type": "application/json",
+        ...(extraHeaders ?? {}),
+        ...(apiKey ? { Authorization: `Bearer ${apiKey}` } : {}),
+      },
+    };
+
+    const req = lib.request(options, (res) => {
+      let data = "";
+      res.on("data", (chunk) => (data += chunk));
+      res.on("end", () => {
+        if (res.statusCode && res.statusCode >= 200 && res.statusCode < 300) {
+          try {
+            resolve(JSON.parse(data));
+          } catch (e) {
+            reject(new Error(`JSON 解析失败: ${e}`));
+          }
+        } else {
+          reject(new Error(`HTTP ${res.statusCode}: ${res.statusMessage}`));
+        }
+      });
+    });
+
+    req.on("error", reject);
+    req.setTimeout(timeoutMs, () => {
+      req.destroy();
+      reject(new Error("请求超时"));
+    });
+    req.end();
+  });
+}
+
+// ---- 名称校验 ----
+function validateProviderName(name: string): string | null {
+  if (!name) return "名称不能为空";
+  if (name.length > 32) return "名称过长（最多 32 字符）";
+  if (!NAME_RE.test(name)) {
+    return "名称只能包含字母、数字、中划线、下划线，且不能以符号开头（如: deepseek, my-proxy, kimi_2）";
+  }
+  return null;
+}
+
+// 应用高级配置中的按模型覆盖（modelOverrides: { modelId: { reasoning, input, contextWindow, ... } }）
+function applyModelOverrides(
+  models: (string | IModel)[],
+  overrides: Record<string, Partial<IModel>>
+): (string | IModel)[] {
+  return models.map((m) => {
+    const id = typeof m === "string" ? m : m.id;
+    const o = overrides?.[id];
+    if (!o || typeof o !== "object") return m;
+    if (typeof m === "string") return { id, ...o } as IModel;
+    return { ...m, ...o };
+  });
+}
+
+// ---- 命令行参数解析（/custom-provider 子命令 flags）----
+
+interface ParsedArgs {
+  positional: string[];
+  flags: Map<string, string[]>;
+}
+
+// 无需取值的布尔 flag
+const BOOLEAN_FLAGS = new Set(["auth-header", "force", "yes"]);
+
+function unquoteFlag(s: string): string {
+  if (s.length >= 2) {
+    const c = s[0];
+    if ((c === '"' || c === "'") && s.endsWith(c)) return s.slice(1, -1);
+  }
+  return s;
+}
+
+// 解析 --key=value / --key value / 短 flag -f -y；引号包裹的值会被剥引号
+function parseFlagArgs(args: string): ParsedArgs {
+  const positional: string[] = [];
+  const flags = new Map<string, string[]>();
+  const tokens = args.match(/(?:[^\s"']+|"[^"]*"|'[^']*')+/g) ?? [];
+  const addFlag = (key: string, value: string) => {
+    const arr = flags.get(key) ?? [];
+    arr.push(value);
+    flags.set(key, arr);
+  };
+  const SHORT_ALIAS: Record<string, string> = { f: "force", y: "yes" };
+
+  for (let i = 0; i < tokens.length; i++) {
+    const tok = tokens[i];
+    if (tok.startsWith("--")) {
+      const eq = tok.indexOf("=");
+      if (eq >= 0) {
+        addFlag(tok.slice(2, eq).toLowerCase(), unquoteFlag(tok.slice(eq + 1)));
+      } else {
+        const key = tok.slice(2).toLowerCase();
+        if (BOOLEAN_FLAGS.has(key)) {
+          addFlag(key, "true");
+        } else {
+          const next = tokens[i + 1];
+          if (next !== undefined && !next.startsWith("-")) {
+            addFlag(key, unquoteFlag(next));
+            i++;
+          } else {
+            addFlag(key, "true"); // 无值 flag 视为 true
+          }
+        }
+      }
+    } else if (/^-[a-z]$/i.test(tok)) {
+      addFlag(SHORT_ALIAS[tok.slice(1).toLowerCase()] ?? tok.slice(1).toLowerCase(), "true");
+    } else {
+      positional.push(unquoteFlag(tok));
+    }
+  }
+  return { positional, flags };
+}
+
+// 取 flag 的值：按名字顺序取第一个存在的，多值时取最后（后者覆盖前者）
+function getFlag(flags: Map<string, string[]>, ...names: string[]): string | undefined {
+  for (const n of names) {
+    const arr = flags.get(n);
+    if (arr && arr.length > 0) return arr[arr.length - 1];
+  }
+  return undefined;
+}
+
+export default function customProviderExtension(pi: ExtensionAPI) {
+  const registerProviders = () => {
+    const config = loadConfig();
+    config.providers.forEach((provider) => {
+      if (provider.enabled === false) return; // 已禁用的不注册
+      try {
+        const providerConfig = buildProviderConfig(provider);
+        pi.registerProvider(provider.name, providerConfig);
+      } catch (error) {
+        console.error(`[custom-provider] 注册 provider "${provider.name}" 失败:`, error);
+      }
+    });
+  };
+
+  // 保存配置并注册 provider；注册失败时回滚磁盘配置，避免"文件已写入但运行态不一致"
+  const persistProvider = (
+    config: IConfig,
+    provider: IProvider,
+    ctx: { ui: { notify(m: string, t?: "info" | "warning" | "error"): void } }
+  ): boolean => {
+    const previous = JSON.parse(JSON.stringify(config.providers));
+    const idx = findProviderIndex(config, provider.name);
+    if (idx >= 0) {
+      // 覆盖时保留原有禁用状态（除非新配置显式指定 enabled）
+      if (config.providers[idx].enabled === false && provider.enabled === undefined) {
+        provider.enabled = false;
+      }
+      config.providers[idx] = provider;
+    } else {
+      config.providers.push(provider);
+    }
+
+    try {
+      saveConfig(config);
+    } catch (error) {
+      ctx.ui.notify(`保存配置失败: ${error instanceof Error ? error.message : String(error)}`, "error");
+      return false;
+    }
+
+    try {
+      const providerConfig = buildProviderConfig(provider);
+      pi.registerProvider(provider.name, providerConfig);
+      return true;
+    } catch (error) {
+      config.providers = previous;
+      try {
+        saveConfig(config);
+      } catch {
+        /* 回滚写失败时保留现状 */
+      }
+      ctx.ui.notify(
+        `注册 provider "${provider.name}" 失败，已回滚保存: ${
+          error instanceof Error ? error.message : String(error)
+        }`,
+        "error"
+      );
+      return false;
+    }
+  };
+
+  // 大小写不敏感的 provider 查找（优先精确匹配）
+  const findProviderIndex = (config: IConfig, name: string): number => {
+    const exact = config.providers.findIndex((p) => p.name === name);
+    if (exact >= 0) return exact;
+    const lower = name.toLowerCase();
+    return config.providers.findIndex((p) => p.name.toLowerCase() === lower);
+  };
+
+  // 非交互式添加：/add-provider '{"name":"...","baseUrl":"...","apiKey":"...",...}'
+  const addProviderFromJson = (jsonText: string, ctx: any): boolean => {
+    let data: any;
+    try {
+      data = JSON.parse(jsonText);
+    } catch (error) {
+      ctx.ui.notify(`JSON 解析失败: ${error instanceof Error ? error.message : String(error)}`, "error");
+      return false;
+    }
+
+    const name = String(data.name ?? "").trim();
+    const nameErr = validateProviderName(name);
+    if (nameErr) {
+      ctx.ui.notify(`名称无效: ${nameErr}`, "error");
+      return false;
+    }
+    const baseUrl = String(data.baseUrl ?? "").trim();
+    if (!baseUrl) {
+      ctx.ui.notify("缺少必填字段 baseUrl", "error");
+      return false;
+    }
+    const models: (string | IModel)[] = Array.isArray(data.models) ? data.models.filter(Boolean) : [];
+    if (models.length === 0) {
+      ctx.ui.notify("model 列表不能为空（models 需为数组）", "error");
+      return false;
+    }
+
+    const provider: IProvider = {
+      name,
+      baseUrl,
+      apiKey: data.apiKey !== undefined ? String(data.apiKey) : "local",
+      models,
+    };
+    if (data.api) provider.api = String(data.api);
+    // 统一 /v1 归一化（与交互路径一致），根据显式 api 或 URL 推断协议
+    const apiForNormalize = provider.api ?? inferApi(provider.baseUrl);
+    const normalized = normalizeBaseUrl(provider.baseUrl, apiForNormalize);
+    if (normalized !== provider.baseUrl) {
+      provider.baseUrl = normalized;
+      console.log(`[custom-provider] 已自动调整端点: → ${normalized}`);
+    }
+    if (typeof data.authHeader === "boolean") provider.authHeader = data.authHeader;
+    if (typeof data.proxy === "string" && data.proxy.trim()) provider.proxy = data.proxy;
+    if (typeof data.enabled === "boolean") provider.enabled = data.enabled;
+    if (data.headers && typeof data.headers === "object") {
+      // 与 flags/向导同一套校验：拒绝非法名称/值（含 CR/LF 注入）
+      const bad = Object.entries(data.headers).find(([k, v]) => {
+        const val = String(v);
+        return !HEADER_NAME_RE.test(k) || !HEADER_VALUE_RE.test(val) || val === "";
+      });
+      if (bad) {
+        ctx.ui.notify(`请求头 ${bad[0]} 名称或值含非法字符（不允许换行/非 ASCII/空值）`, "error");
+        return false;
+      }
+      provider.headers = data.headers;
+    }
+    if (data.compat && typeof data.compat === "object") provider.compat = data.compat;
+
+    const config = loadConfig();
+    const ok = persistProvider(config, provider, ctx);
+    if (ok) {
+      const msg = `Provider "${name}" 已添加并注册，共 ${models.length} 个模型`;
+      if (ctx.ui.notify) ctx.ui.notify(msg, "info");
+      else console.log(`[custom-provider] ${msg}`);
+    }
+    return ok;
+  };
+
+  // 参数归一化：兼容字符串与数组两种调用形态
+  const toArgText = (args: unknown): string =>
+    Array.isArray(args) ? args.join(" ") : typeof args === "string" ? args : "";
+
+  // 先读本地规格缓存并同步注册（离线也可用：缓存 → 预设 → 默认）
+  loadSpecCache();
+  registerProviders();
+
+  // 后台拉取 OpenRouter 最新模型规格；成功后热更新注册，使配置立即使用真实规格
+  refreshRemoteSpecs().then(() => {
+    registerProviders();
+  });
+
+  // 监听 session_start 以支持热重载
+  pi.on("session_start", () => {
+    registerProviders();
+  });
+
+// ================= 子命令实现 =================
+
+  // 交互式过滤模型列表（按关键字保留/排除）；返回 null 表示保留全部
+  const filterModelsInteractive = async (
+    ctx: any,
+    models: (string | IModel)[]
+  ): Promise<(string | IModel)[] | null> => {
+    if (models.length === 0 || !ctx.hasUI) return null;
+    const idOf = (m: string | IModel) => (typeof m === "string" ? m : m.id).toLowerCase();
+
+    const mode = await ctx.ui.select(
+      `共拉取 ${models.length} 个模型，如何处理？`,
+      ["全部保留", "按关键字保留", "按关键字排除"]
+    );
+    if (!mode || mode === "全部保留") return null;
+
+    const kwInput = await ctx.ui.input(
+      mode === "按关键字保留"
+        ? "保留含任一关键字的模型（逗号分隔，如: deepseek,glm；留空=全部）"
+        : "排除含任一关键字的模型（逗号分隔，如: qwen,mini；留空=不排除）",
+      mode === "按关键字保留" ? "deepseek,glm" : "qwen,mini"
+    );
+    if (!kwInput || !kwInput.trim()) return null;
+    const keywords = kwInput.split(",").map((s: string) => s.trim().toLowerCase()).filter(Boolean);
+    if (keywords.length === 0) return null;
+
+    const filtered = models.filter((m) => {
+      const id = idOf(m);
+      return mode === "按关键字保留"
+        ? keywords.some((k: string) => id.includes(k))
+        : !keywords.some((k: string) => id.includes(k));
+    });
+
+    ctx.ui.notify(`过滤后剩 ${filtered.length} 个（原 ${models.length} 个）`, "info");
+    if (filtered.length === 0) {
+      const keepAll = await ctx.ui.confirm(
+        "过滤结果为空",
+        "选择 Yes 保留全部模型，No 取消本次操作"
+      );
+      if (keepAll) return null;
+      await ctx.ui.notify("已取消", "info");
+      return null;
+    }
+    const ok = await ctx.ui.confirm(
+      `确认写入这 ${filtered.length} 个模型？`,
+      "选择 Yes 仅保存过滤后的模型，No 保留全部"
+    );
+    return ok ? filtered : null;
+  };
+
+  // 交互式添加向导（TUI/RPC 对话引导）
+  const doAddInteractive = async (ctx: any, nameDefault: string): Promise<void> => {
+    try {
+      // ---- 1. 名称 ----
+      const name = await ctx.ui.input(
+        `Provider 名称（字母/数字/-/_，必填）`,
+        nameDefault || "deepseek"
+      );
+      if (!name) return;
+
+      const nameErr = validateProviderName(name);
+      if (nameErr) {
+        ctx.ui.notify(`名称无效: ${nameErr}`, "error");
+        return;
+      }
+
+      // 提前检查重名，避免用户填完所有信息才发现已存在
+      const early = loadConfig();
+      const existingIndex = early.providers.findIndex((p) => p.name === name);
+      if (existingIndex >= 0) {
+        const ok = await ctx.ui.confirm(
+          `Provider "${name}" 已存在，是否覆盖？`,
+          "选择 Yes 覆盖现有配置（模型详情将按本次输入重建），No 取消本次操作"
+        );
+        if (!ok) {
+          ctx.ui.notify("已取消", "info");
+          return;
+        }
+      }
+
+      // ---- 2. 端点 ----
+      const baseUrl = await ctx.ui.input(
+        "API 端点 URL（完整地址，通常含 /v1；粘贴 /v1/models 也会被自动清理）",
+        "https://api.deepseek.com/v1"
+      );
+      if (!baseUrl) return;
+
+      // ---- 3. API Key ----
+      const apiKeyInput = await ctx.ui.input(
+        "API Key（支持 $ENV 环境变量 / !命令 / 字面量 sk-xxx / 留空表示无认证本地服务）",
+        "$DEEPSEEK_API_KEY"
+      );
+      const apiKey = apiKeyInput || "local";
+
+      // 提前解析校验：空结果（env 未设置 / 命令输出空）静默会导致请求 401，先警告
+      const resolvedKey = resolveValue(apiKey);
+      if (resolvedKey === "" && apiKey !== "local") {
+        const origin = apiKey.startsWith("$")
+          ? `环境变量 ${apiKey} 未设置或为空`
+          : apiKey.startsWith("!")
+            ? "命令执行无输出"
+            : "API Key 为空";
+        const proceed = await ctx.ui.confirm(
+          `${origin}，解析结果为空`,
+          "保存后请求可能无认证（401）。仍要继续吗？选择 No 可重新输入"
+        );
+        if (!proceed) {
+          ctx.ui.notify("已取消添加", "info");
+          return;
+        }
+      }
+
+      // ---- 4. 协议类型 ----
+      const apiType = await ctx.ui.select(
+        "API 协议类型（推荐「自动推断」，按 URL 自动识别）",
+        ["自动推断", "openai-completions", "openai-responses", "anthropic-messages", "google-generative-ai"]
+      );
+      if (!apiType) return;
+
+      // 所有路径都做 /v1 归一化（自动推断先推断协议，再按协议规范化）
+      const inferredApi =
+        apiType === "自动推断" ? inferApi(baseUrl) : apiType;
+      const finalBaseUrl = normalizeBaseUrl(baseUrl, inferredApi);
+      if (finalBaseUrl !== baseUrl) {
+        ctx.ui.notify(`已自动调整端点: ${baseUrl} → ${finalBaseUrl}`, "info");
+      }
+
+      // ---- 4.5 代理（可选：需要走代理出网的渠道，如本地/公司代理）----
+      const needProxy = await ctx.ui.confirm(
+        "需要通过代理访问此渠道吗？",
+        "如本地代理 http://127.0.0.1:7890 或公司代理；不支持可跳过（选 No）"
+      );
+      let proxyUrl: string | undefined;
+      if (needProxy) {
+        const proxyInput = await ctx.ui.input(
+          "代理地址（http://host:port 或 socks5://host:port，支持 $ENV 引用）",
+          "http://127.0.0.1:7890"
+        );
+        proxyUrl = proxyInput?.trim() || undefined;
+        if (proxyUrl) {
+          ctx.ui.notify(`将请求经代理 ${proxyUrl} 出网（需 NODE_USE_ENV_PROXY=1 生效，见 README）`, "info");
+        }
+      }
+
+      // ---- 5. 是否自动拉取模型 ----
+      const autoFetch = await ctx.ui.confirm(
+        "自动从 /v1/models 拉取模型列表？",
+        "若服务支持模型列表端点可自动获取；否则将手动输入"
+      );
+
+      // ---- 6. 请求头模板（预设整组请求头，不同 CLI 头集合不同；选「自定义」逐头输入）----
+      const presetLabels = HEADER_PRESETS.map((p) => p.label);
+      const presetChoice = await ctx.ui.select(
+        "请求头模板？",
+        presetLabels
+      );
+
+      let customHeaders: Record<string, string> | undefined;
+
+      // 校验并写入一组请求头（名称/值合法性校验 + 敏感头提示）
+      const applyHeaderSet = (raw: Record<string, string>, source: string) => {
+        let ok = true;
+        for (const [k, v] of Object.entries(raw)) {
+          const val = String(v);
+          if (!HEADER_NAME_RE.test(k) || !HEADER_VALUE_RE.test(val)) {
+            ctx.ui.notify(`${source}: 请求头 ${k} 名称或值含非法字符（不允许换行/非 ASCII）→ 已跳过`, "error");
+            ok = false;
+            continue;
+          }
+          if (SENSITIVE_HEADER_HINTS.includes(k.toLowerCase())) {
+            ctx.ui.notify(`${source}: ${k} 属于敏感头，设置后可能覆盖认证/协议逻辑，请确认服务端要求`, "warning");
+          }
+          customHeaders = customHeaders ?? {};
+          customHeaders[k] = val; // 值保留 $ENV 引用，pi 请求时动态解析
+        }
+        return ok;
+      };
+
+      if (presetChoice) {
+        const preset = HEADER_PRESETS.find((p) => p.label === presetChoice);
+        if (preset?.key) {
+          if (preset.key !== "browser") {
+            applyHeaderSet({ ...preset.headers }, `模板「${preset.label}」`);
+            ctx.ui.notify(
+              `已应用请求头模板「${preset.label}」: ${Object.keys(preset.headers).join(", ")}`,
+              "info"
+            );
+          } // 浏览器模板 = 不写头，由 pi 自动补充浏览器 UA
+        } else {
+          // 自定义：JSON 对象，或每行 "Key: Value"（值支持 $ENV）
+          const headersInput = await ctx.ui.input(
+            '自定义请求头（JSON 对象，或每行 "Key: Value"：值支持 $ENV；留空取消）',
+            '{"X-API-Key": "$MY_API_KEY"}'
+          );
+          if (headersInput && headersInput.trim()) {
+            const t = headersInput.trim();
+            try {
+              const parsed = JSON.parse(t);
+              if (parsed && typeof parsed === "object" && !Array.isArray(parsed)) {
+                applyHeaderSet({ ...parsed }, "自定义请求头");
+              } else {
+                ctx.ui.notify("JSON 需为对象（{...}）", "error");
+              }
+            } catch {
+              // 非 JSON：按行解析 "Key: Value"
+              const lines = t.split(/\r\n|\r|\n/);
+
+              const kv: Record<string, string> = {};
+              let parseOk = true;
+              for (const line of lines) {
+                if (!line.trim()) continue;
+                const idx = line.indexOf(":");
+                if (idx <= 0) {
+                  ctx.ui.notify(`无法解析行: ${line}`, "error");
+                  parseOk = false;
+                  break;
+                }
+                kv[line.slice(0, idx).trim()] = line.slice(idx + 1).trim();
+              }
+              if (parseOk) applyHeaderSet(kv, "自定义请求头");
+            }
+          }
+        }
+      }
+
+      // ---- 7. 补充/覆盖请求头（在模板/自定义基础上追加，可覆盖；无需直接跳过）----
+      const needMore = await ctx.ui.confirm(
+        "需要补充/覆盖请求头吗？",
+        "在现有头部上追加或覆盖（如 X-API-Key），值支持 $ENV 插值"
+      );
+      if (needMore) {
+        const headersInput = await ctx.ui.input(
+          "请求头 JSON（合并进现有头部，可覆盖模板值）",
+          '{"X-API-Key": "$MY_API_KEY"}'
+        );
+        if (headersInput && headersInput.trim()) {
+          try {
+            const parsed = JSON.parse(headersInput);
+            if (parsed && typeof parsed === "object" && !Array.isArray(parsed)) {
+              applyHeaderSet({ ...parsed }, "补充请求头");
+            } else {
+              ctx.ui.notify("JSON 需为对象", "error");
+            }
+          } catch {
+            ctx.ui.notify("JSON 格式错误，已跳过", "error");
+          }
+        }
+      }
+
+      // ---- 8. 高级配置      // ---- 8. 高级配置：authHeader / compat / 按模型覆盖（vision、reasoning、cost 等）----
+      const advancedSkeleton = {
+        authHeader: false,
+        compat: {},
+        modelOverrides: {},
+      };
+      const needAdvanced = await ctx.ui.confirm(
+        "需要高级配置吗？",
+        "如 authHeader、compat、按模型覆盖（input 图像、reasoning、contextWindow、cost、maxTokens、api 协议）。支持双协议混用: modelOverrides 里给单个模型设 api + baseUrl"
+      );
+      let authHeader = false;
+      let compat: Record<string, any> | undefined;
+      let modelOverrides: Record<string, Partial<IModel>> | undefined;
+      if (needAdvanced) {
+        const advText = await ctx.ui.editor(
+          "高级配置 JSON（对象字段：authHeader / compat / modelOverrides，直接编辑或留空跳过）",
+          JSON.stringify(advancedSkeleton, null, 2)
+        );
+        if (advText && advText.trim()) {
+          try {
+            const adv = JSON.parse(advText);
+            if (typeof adv.authHeader === "boolean") authHeader = adv.authHeader;
+            if (adv.compat && typeof adv.compat === "object") compat = adv.compat;
+            if (adv.modelOverrides && typeof adv.modelOverrides === "object") {
+              modelOverrides = adv.modelOverrides;
+            }
+            if (adv.authHeader) {
+              ctx.ui.notify(
+                "authHeader=true 已开启：将以 Authorization: Bearer <API Key> 发送认证",
+                "info"
+              );
+            }
+          } catch {
+            ctx.ui.notify("高级配置 JSON 格式错误，已忽略", "error");
+          }
+        }
+      }
+
+      // ---- 9. 收集模型 ----
+      let models: (string | IModel)[] = [];
+      if (autoFetch) {
+        ctx.ui.notify("正在拉取模型列表…", "info");
+        try {
+          const modelIds = await fetchModels(finalBaseUrl, resolvedKey, inferredApi, customHeaders);
+          models = modelIds;
+          ctx.ui.notify(`成功拉取 ${models.length} 个模型`, "info");
+          // 过滤：避免把渠道全量模型写入（按关键字保留/排除）
+          if (ctx.hasUI && models.length > 0) {
+            const filtered = await filterModelsInteractive(ctx, models);
+            if (filtered) models = filtered;
+          }
+        } catch (error) {
+          ctx.ui.notify(
+            `${error instanceof Error ? error.message : String(error)}\n可手动输入模型，或重新检查端点/Key`,
+            "error"
+          );
+          const fallback = await ctx.ui.input(
+            "手动输入模型 ID（逗号分隔，可留空取消）",
+            "model-a,model-b"
+          );
+          if (fallback && fallback.trim()) {
+            models = fallback.split(",").map((s: string) => s.trim()).filter(Boolean);
+          }
+        }
+      } else {
+        const input = await ctx.ui.input(
+          "模型 ID（逗号分隔，可留空取消）",
+          "deepseek-chat,deepseek-reasoner"
+        );
+        if (input && input.trim()) {
+          models = input.split(",").map((s: string) => s.trim()).filter(Boolean);
+        }
+      }
+
+      if (models.length === 0) {
+        ctx.ui.notify("未提供模型，取消添加", "warning");
+        return;
+      }
+
+      // 手动输入时提供连通性测试（自动拉取成功则已证明连通）
+      if (!autoFetch) {
+        const test = await ctx.ui.confirm(
+          "测试连接？",
+          `将请求 ${finalBaseUrl}/models 验证端点与 API Key`
+        );
+        if (test) {
+          ctx.ui.notify("测试中…", "info");
+          try {
+            const ids = await fetchModels(finalBaseUrl, resolvedKey, inferredApi, customHeaders);
+            ctx.ui.notify(`连接正常，检测到 ${ids.length} 个模型`, "info");
+          } catch (error) {
+            const msg = error instanceof Error ? error.message : String(error);
+            const keep = await ctx.ui.confirm(
+              "连接测试失败",
+              `${msg}\n仍要保存此配置吗？`
+            );
+            if (!keep) {
+              ctx.ui.notify("已取消添加", "info");
+              return;
+            }
+          }
+        }
+      }
+
+      // ---- 10. 应用高级覆盖并持久化 ----
+      if (modelOverrides) {
+        models = applyModelOverrides(models, modelOverrides);
+      }
+
+      // ---- 10.1 Anthropic 1M 长上下文提示：
+      // 含 [1m] 后缀或大窗口模型的 anthropic-messages 中转，需要携带
+      // anthropic-beta: context-1m-2025-08-07 请求头，1M 窗口才生效（官方端点不支持）
+      const hasLongCtxModel =
+        inferredApi === "anthropic-messages" &&
+        !isOfficialAnthropicEndpoint(finalBaseUrl) &&
+        models.some((m) => hasLongContextSuffix(typeof m === "string" ? m : m.id));
+      if (hasLongCtxModel && !hasHeader(customHeaders, "anthropic-beta")) {
+        const addBeta = await ctx.ui.confirm(
+          "检测到 1M 长上下文模型（[1m]）",
+          "将自动添加请求头 anthropic-beta: context-1m-2025-08-07，否则 1M 窗口不生效（官方端点不支持此头）。要添加吗？"
+        );
+        if (addBeta) {
+          if (!customHeaders) customHeaders = {};
+          customHeaders["anthropic-beta"] = "context-1m-2025-08-07";
+        }
+      }
+
+      const newProvider: IProvider = {
+        name,
+        baseUrl: finalBaseUrl,
+        apiKey,
+        models,
+      };
+      if (proxyUrl) newProvider.proxy = proxyUrl;
+      if (apiType !== "自动推断" || inferredApi !== "openai-completions") {
+        // 显式选择的协议，或自动推断出的非默认协议，需存盘保证幂等
+        newProvider.api = inferredApi;
+      }
+      if (authHeader) newProvider.authHeader = true;
+      if (customHeaders && Object.keys(customHeaders).length > 0) {
+        newProvider.headers = customHeaders;
+      }
+      if (compat && Object.keys(compat).length > 0) {
+        newProvider.compat = compat;
+      }
+
+      const ok = persistProvider(loadConfig(), newProvider, ctx);
+      if (ok) {
+        ctx.ui.notify(
+          `Provider "${name}" 已添加并注册，共 ${models.length} 个模型。用 /model 选择模型`,
+          "info"
+        );
+      }
+    } catch (error) {
+      ctx.ui.notify(
+        `添加失败: ${error instanceof Error ? error.message : String(error)}`,
+        "error"
+      );
+    }
+  };
+
+  // 由 flags 组装（无交互）Provider 配置；失败返回 null 并已通知原因
+  const buildProviderFromFlags = (parsed: ParsedArgs, ctx: any): IProvider | null => {
+    const { positional, flags } = parsed;
+    const name = getFlag(flags, "name") || positional[0];
+    if (!name || validateProviderName(name)) {
+      ctx.ui.notify(`名称无效: ${validateProviderName(name) ?? "缺少名称（--name 或位置参数）"}`, "error");
+      return null;
+    }
+    const baseUrl = getFlag(flags, "base-url", "url");
+    if (!baseUrl) {
+      ctx.ui.notify("缺少 --base-url", "error");
+      return null;
+    }
+    const apiKey = getFlag(flags, "api-key", "key") ?? "local";
+    const apiRaw = getFlag(flags, "api");
+    const api = !apiRaw || apiRaw === "auto" ? inferApi(baseUrl) : apiRaw;
+
+    let models: (string | IModel)[] = [];
+    const modelsCsv = getFlag(flags, "models");
+    if (modelsCsv) models = modelsCsv.split(",").map((s) => s.trim()).filter(Boolean);
+    for (const m of flags.get("model") ?? []) {
+      if (m.trim()) models.push(m.trim());
+    }
+    if (models.length === 0) {
+      ctx.ui.notify("缺少 --models（逗号分隔）或 --model（可多次）", "error");
+      return null;
+    }
+
+    // --model-api "模型id:协议" 与 --model-base-url "模型id:url"（可重复）:
+    // 让单个模型覆盖协议/端点（如同一网关内部分模型走 anthropic 协议）
+    const modelApiPairs = flags.get("model-api") ?? [];
+    const modelBaseUrlPairs = flags.get("model-base-url") ?? [];
+    if (modelApiPairs.length > 0 || modelBaseUrlPairs.length > 0) {
+      const byId = new Map<string, Partial<IModel>>();
+      const applyPair = (pair: string, key: "api" | "baseUrl", label: string): boolean => {
+        const idx = pair.indexOf(":");
+        if (idx <= 0) {
+          ctx.ui.notify(`${label} 格式错误（应为 "模型id:值"）: ${pair}`, "error");
+          return false;
+        }
+        const id = pair.slice(0, idx).trim();
+        const val = pair.slice(idx + 1).trim();
+        if (!id || !val) {
+          ctx.ui.notify(`${label} 格式错误（模型id与值不能为空）: ${pair}`, "error");
+          return false;
+        }
+        const entry = byId.get(id) ?? {};
+        if (key === "api" && !/^(?:(?:openai-completions|openai-responses|anthropic-messages|google-generative-ai|auto))$/.test(val)) {
+          ctx.ui.notify(`未知协议类型: ${val}（可选: openai-completions / openai-responses / anthropic-messages / google-generative-ai）`, "error");
+          return false;
+        }
+        entry[key] = val;
+        byId.set(id, entry);
+        return true;
+      };
+      for (const p of modelApiPairs) {
+        if (!applyPair(p, "api", "--model-api")) return null;
+      }
+      for (const p of modelBaseUrlPairs) {
+        if (!applyPair(p, "baseUrl", "--model-base-url")) return null;
+      }
+      if (byId.size > 0) {
+        models = models.map((m) => {
+          const id = typeof m === "string" ? m : m.id;
+          const patch = byId.get(id);
+          if (!patch) return m;
+          return typeof m === "string" ? ({ id, ...patch } as IModel) : { ...m, ...patch };
+        });
+      }
+    }
+
+    const headers: Record<string, string> = {};
+    for (const h of flags.get("header") ?? []) {
+      const idx = h.indexOf(":");
+      if (idx <= 0) {
+        ctx.ui.notify(`--header 格式错误（应为 "Name: value"）: ${h}`, "error");
+        return null;
+      }
+      headers[h.slice(0, idx).trim()] = h.slice(idx + 1).trim();
+    }
+    const headersJson = getFlag(flags, "headers");
+    if (headersJson) {
+      try {
+        const obj = JSON.parse(headersJson);
+        if (typeof obj === "object" && obj !== null) Object.assign(headers, obj);
+        else {
+          ctx.ui.notify("--headers 需为 JSON 对象", "error");
+          return null;
+        }
+      } catch {
+        ctx.ui.notify("--headers JSON 解析失败", "error");
+        return null;
+      }
+    }
+
+    const provider: IProvider = {
+      name,
+      baseUrl: normalizeBaseUrl(baseUrl, api),
+      apiKey,
+      models,
+    };
+    const proxyFlag = getFlag(flags, "proxy");
+    if (proxyFlag) provider.proxy = proxyFlag;
+    if (apiRaw && apiRaw !== "auto") provider.api = apiRaw;
+    else if (api !== "openai-completions") provider.api = api;
+    if (getFlag(flags, "auth-header")) provider.authHeader = true;
+
+    const compatJson = getFlag(flags, "compat");
+    if (compatJson) {
+      try {
+        const obj = JSON.parse(compatJson);
+        if (obj && typeof obj === "object") provider.compat = obj;
+        else {
+          ctx.ui.notify("--compat 需为 JSON 对象", "error");
+          return null;
+        }
+      } catch {
+        ctx.ui.notify("--compat JSON 解析失败", "error");
+        return null;
+      }
+    }
+
+    const overridesJson = getFlag(flags, "overrides");
+    if (overridesJson) {
+      try {
+        const obj = JSON.parse(overridesJson);
+        if (obj && typeof obj === "object") {
+          provider.models = applyModelOverrides(provider.models, obj);
+        } else {
+          ctx.ui.notify("--overrides 需为 JSON 对象", "error");
+          return null;
+        }
+      } catch {
+        ctx.ui.notify("--overrides JSON 解析失败", "error");
+        return null;
+      }
+    }
+
+    // --profile 应用完整请求头模板（不覆盖 --header/--headers 显式写入的头）
+    const profileFlag = getFlag(flags, "profile");
+    if (profileFlag) {
+      const preset = HEADER_PRESETS.find((p) => p.key === profileFlag.toLowerCase());
+      if (!preset || preset.key === undefined) {
+        const keys = HEADER_PRESETS.filter((p) => p.key).map((p) => p.key).join(", ");
+        ctx.ui.notify(`未知模板 "${profileFlag}"，可用: ${keys}`, "error");
+        return null;
+      }
+      if (preset.key !== "browser") {
+        const lowerKeys = new Set(Object.keys(headers).map((k) => k.toLowerCase()));
+        for (const [k, v] of Object.entries(preset.headers)) {
+          if (!lowerKeys.has(k.toLowerCase())) headers[k] = v; // 不覆盖显式
+        }
+      }
+    }
+
+    // --ua 预设 User-Agent（preset 键名或原始字符串）；显式 headers 里已有 User-Agent 则不覆盖
+    const uaFlag = getFlag(flags, "ua", "user-agent");
+    if (uaFlag && !hasHeader(headers, "user-agent") && !profileFlag) {
+      const presetKey = uaFlag.toLowerCase();
+      if (UA_PRESETS[presetKey]) {
+        headers["User-Agent"] = UA_PRESETS[presetKey];
+      } else {
+        headers["User-Agent"] = uaFlag;
+      }
+    }
+
+    if (Object.keys(headers).length > 0) provider.headers = headers;
+    return provider;
+  };
+
+  // add：JSON / flags 非交互 / 交互向导 三种路径
+  const doAdd = async (argText: string, ctx: any): Promise<void> => {
+    const t = argText.trim();
+
+    // 路径 1：JSON 参数（位置参数或 --json）
+    if (t.startsWith("{")) {
+      addProviderFromJson(t, ctx);
+      return;
+    }
+    const parsed = parseFlagArgs(t);
+    const jsonFlag = getFlag(parsed.flags, "json");
+    if (jsonFlag) {
+      addProviderFromJson(jsonFlag, ctx);
+      return;
+    }
+
+    const baseUrl = getFlag(parsed.flags, "base-url", "url");
+    const modelsCsv = getFlag(parsed.flags, "models");
+    const modelFlags = parsed.flags.get("model") ?? [];
+    const hasModels = !!modelsCsv || modelFlags.length > 0;
+
+    // 路径 2：flags 非交互添加
+    if (baseUrl && hasModels) {
+      const provider = buildProviderFromFlags(parsed, ctx);
+      if (!provider) return;
+
+      const config = loadConfig();
+      const exists = config.providers.some((p) => p.name === provider.name);
+      if (exists && !getFlag(parsed.flags, "force") && !getFlag(parsed.flags, "yes")) {
+        if (ctx.hasUI) {
+          const ok = await ctx.ui.confirm(
+            `Provider "${provider.name}" 已存在，是否覆盖？`,
+            "选择 Yes 覆盖现有配置，No 取消（--force 可跳过此确认）"
+          );
+          if (!ok) {
+            ctx.ui.notify("已取消", "info");
+            return;
+          }
+        } else {
+          ctx.ui.notify(`已存在 provider "${provider.name}"，如需覆盖请加 --force`, "error");
+          return;
+        }
+      }
+
+      const ok = persistProvider(config, provider, ctx);
+      if (ok) {
+        ctx.ui.notify(
+          `Provider "${provider.name}" 已添加并注册，共 ${provider.models.length} 个模型。用 /model 选择模型`,
+          "info"
+        );
+      }
+      return;
+    }
+
+    // 路径 3：交互向导
+    if (!ctx.hasUI) {
+      ctx.ui.notify(
+        "非交互环境请用参数添加: /custom-provider add --name x --base-url URL --models a,b [--api-key $K] [--api TYPE] [--force]，或用 --json '{...}'",
+        "warning"
+      );
+      return;
+    }
+    await doAddInteractive(ctx, getFlag(parsed.flags, "name") || parsed.positional[0] || "deepseek");
+  };
+
+  // remove：按名称删除（--yes / -y 跳过确认）
+  const doRemove = async (argText: string, ctx: any): Promise<void> => {
+    const config = loadConfig();
+    if (config.providers.length === 0) {
+      ctx.ui.notify("暂无已配置的 provider，请先用 /custom-provider add 添加", "warning");
+      return;
+    }
+
+    const parsed = parseFlagArgs(argText);
+    let name = parsed.positional[0] || getFlag(parsed.flags, "name");
+    if (!name && ctx.hasUI) {
+      const selected = await ctx.ui.select(
+        "选择要删除的 Provider",
+        config.providers.map((p) => p.name)
+      );
+      if (!selected) return;
+      name = selected;
+    }
+    if (!name) {
+      ctx.ui.notify("请指定名称: /custom-provider remove <名称> [--yes]", "warning");
+      return;
+    }
+
+    const idx = findProviderIndex(config, name);
+    if (idx < 0) {
+      ctx.ui.notify(`未找到 provider "${name}"`, "error");
+      return;
+    }
+
+    if (ctx.hasUI && !getFlag(parsed.flags, "yes")) {
+      const ok = await ctx.ui.confirm(
+        `删除 Provider "${name}"？（共 ${config.providers[idx].models.length} 个模型）`,
+        "将同时注销该 provider，不可撤销；--yes 可跳过确认"
+      );
+      if (!ok) {
+        ctx.ui.notify("已取消", "info");
+        return;
+      }
+    }
+
+    config.providers.splice(idx, 1);
+    try {
+      saveConfig(config);
+      pi.unregisterProvider(name);
+      ctx.ui.notify(`Provider "${name}" 已删除并注销`, "info");
+    } catch (error) {
+      ctx.ui.notify(`删除失败: ${error instanceof Error ? error.message : String(error)}`, "error");
+    }
+  };
+
+  // refresh：重拉模型列表（保留已存在模型的详细配置）
+  const doRefresh = async (argText: string, ctx: any): Promise<void> => {
+    const config = loadConfig();
+    if (config.providers.length === 0) {
+      ctx.ui.notify("暂无已配置的 provider，请先用 /custom-provider add 添加", "warning");
+      return;
+    }
+
+    const parsed = parseFlagArgs(argText);
+    const argName = parsed.positional[0] || getFlag(parsed.flags, "name");
+    let target: IProvider | undefined;
+    if (argName) {
+      const argIdx = findProviderIndex(config, argName);
+      if (argIdx < 0) {
+        ctx.ui.notify(`未找到 provider "${argName}"`, "error");
+        return;
+      }
+      target = config.providers[argIdx];
+    } else if (ctx.hasUI) {
+      const selected = await ctx.ui.select(
+        "选择要刷新模型的 Provider",
+        config.providers.map((p) => p.name)
+      );
+      if (!selected) return;
+      target = config.providers.find((p) => p.name === selected);
+    } else {
+      target = config.providers[0];
+    }
+    if (!target) return;
+
+    if (target.enabled === false) {
+      ctx.ui.notify(`Provider "${target.name}" 已禁用，请先 /custom-provider enable ${target.name}`, "warning");
+      return;
+    }
+
+    ctx.ui.notify(`正在从 ${target.baseUrl} 拉取模型列表…`, "info");
+    try {
+      const apiKey = resolveValue(target.apiKey);
+      const api = inferApi(target.baseUrl, target.api);
+      const modelIds = await fetchModels(target.baseUrl, apiKey, api, target.headers);
+
+      if (modelIds.length === 0) {
+        ctx.ui.notify("端点未返回任何模型", "error");
+        return;
+      }
+
+      // 合并：保留已存在模型的详细配置（contextWindow/maxTokens 等），新模型用默认配置
+      const existing = new Map(
+        target.models.map((m) => [typeof m === "string" ? m : m.id, m])
+      );
+      target.models = modelIds.map((id) => existing.get(id) ?? id);
+
+      const ok = persistProvider(config, target, ctx);
+      if (ok) {
+        ctx.ui.notify(
+          `已更新 provider "${target.name}"，共 ${target.models.length} 个模型。用 /model 切换`,
+          "info"
+        );
+      }
+    } catch (error) {
+      ctx.ui.notify(`${error instanceof Error ? error.message : String(error)}`, "error");
+    }
+  };
+
+  // list：列出全部 provider
+  const doList = (ctx: any): void => {
+    const config = loadConfig();
+    if (config.providers.length === 0) {
+      ctx.ui.notify("暂无已配置的 provider，用 /custom-provider add 添加", "info");
+      return;
+    }
+    const lines = config.providers.map((p) => {
+      const api = p.api ?? inferApi(p.baseUrl);
+      const state = p.enabled === false ? "✗ 禁用" : "✓ 启用";
+      const ids = p.models.map((m) => (typeof m === "string" ? m : m.id));
+      const preview =
+        ids.length <= 4 ? ids.join(", ") : `${ids.slice(0, 4).join(", ")}, …（共 ${ids.length} 个）`;
+      const proxyLine = p.proxy ? `\n  代理: ${p.proxy}` : "";
+      return `• ${p.name}  [${state}] [${api}]\n  端点: ${p.baseUrl}${proxyLine}\n  模型: ${preview}`;
+    });
+    ctx.ui.notify(`已配置 ${config.providers.length} 个 provider:\n\n${lines.join("\n\n")}\n\n启用/禁用: /custom-provider enable|disable <名称>` , "info");
+  };
+
+  // test：测试连接（已配置 provider 或临时端点）
+  const doTest = async (argText: string, ctx: any): Promise<void> => {
+    const parsed = parseFlagArgs(argText);
+    const name = parsed.positional[0] || getFlag(parsed.flags, "name");
+    const tmpBaseUrl = getFlag(parsed.flags, "base-url", "url");
+
+    let baseUrl: string;
+    let apiKey: string;
+    let api: string;
+    let headers: Record<string, string> | undefined;
+    let label: string;
+
+    if (tmpBaseUrl) {
+      // 测试临时端点（不保存配置）
+      baseUrl = tmpBaseUrl;
+      apiKey = getFlag(parsed.flags, "api-key", "key") ?? "";
+      const apiRaw = getFlag(parsed.flags, "api");
+      api = !apiRaw || apiRaw === "auto" ? inferApi(baseUrl) : apiRaw;
+      label = name || baseUrl;
+    } else {
+      if (!name) {
+        ctx.ui.notify("请指定名称: /custom-provider test <名称>，或提供临时端点: test --base-url URL --api-key KEY", "warning");
+        return;
+      }
+      const config = loadConfig();
+      const pIdx = findProviderIndex(config, name);
+      if (pIdx < 0) {
+        ctx.ui.notify(`未找到 provider "${name}"`, "error");
+        return;
+      }
+      const p = config.providers[pIdx];
+      if (p.enabled === false) {
+        ctx.ui.notify(`Provider "${name}" 已禁用，请先 /custom-provider enable ${name}`, "warning");
+        return;
+      }
+      baseUrl = p.baseUrl;
+      apiKey = resolveValue(p.apiKey);
+      api = inferApi(p.baseUrl, p.api);
+      headers = p.headers;
+      label = p.name;
+    }
+
+    ctx.ui.notify(`正在测试 ${label}（${baseUrl}）…`, "info");
+    try {
+      const ids = await fetchModels(baseUrl, apiKey, api, headers);
+      ctx.ui.notify(`测试通过：端点可用，检测到 ${ids.length} 个模型`, "info");
+      if (!tmpBaseUrl && !ids.length) ctx.ui.notify("提示: 端点可用但未返回模型，可尝试 /custom-provider refresh", "info");
+    } catch (error) {
+      ctx.ui.notify(`测试失败: ${error instanceof Error ? error.message : String(error)}`, "error");
+    }
+  };
+
+  // prune：修剪已配置 provider 的模型列表（交互过滤，或 --keep/--drop 按关键字）
+  const doPrune = async (argText: string, ctx: any): Promise<void> => {
+    const config = loadConfig();
+    if (config.providers.length === 0) {
+      ctx.ui.notify("暂无已配置的 provider", "warning");
+      return;
+    }
+    const parsed = parseFlagArgs(argText);
+    let name = parsed.positional[0] || getFlag(parsed.flags, "name");
+    if (!name && ctx.hasUI) {
+      const selected = await ctx.ui.select(
+        "选择要修剪模型的 Provider",
+        config.providers.map((p) => p.name)
+      );
+      if (!selected) return;
+      name = selected;
+    }
+    if (!name) {
+      ctx.ui.notify("请指定名称: /custom-provider prune <名称> [--keep 关键词] [--drop 关键词]", "warning");
+      return;
+    }
+    const idx = findProviderIndex(config, name);
+    if (idx < 0) {
+      ctx.ui.notify(`未找到 provider "${name}"`, "error");
+      return;
+    }
+    const target = config.providers[idx];
+    if (target.enabled === false) {
+      ctx.ui.notify(`Provider "${name}" 已禁用，请先 /custom-provider enable ${name}`, "warning");
+      return;
+    }
+
+    const keepKw = getFlag(parsed.flags, "keep");
+    const dropKw = getFlag(parsed.flags, "drop");
+    const originalCount = target.models.length;
+    let models = target.models;
+
+    if (keepKw || dropKw) {
+      // 非交互：按关键字过滤（大小写不敏感子串匹配）
+      const ks = (keepKw ?? "").split(",").map((s) => s.trim().toLowerCase()).filter(Boolean);
+      const ds = (dropKw ?? "").split(",").map((s) => s.trim().toLowerCase()).filter(Boolean);
+      if (ks.length === 0 && ds.length === 0) {
+        ctx.ui.notify("--keep/--drop 关键词不能为空", "error");
+        return;
+      }
+      const filtered = models.filter((m) => {
+        const id = (typeof m === "string" ? m : m.id).toLowerCase();
+        if (ks.length > 0 && !ks.some((k) => id.includes(k))) return false;
+        if (ds.length > 0 && ds.some((k) => id.includes(k))) return false;
+        return true;
+      });
+      if (filtered.length === 0) {
+        ctx.ui.notify(`过滤后为空（原 ${originalCount} 个），未做修改`, "warning");
+        return;
+      }
+      if (filtered.length === originalCount) {
+        ctx.ui.notify("过滤条件未命中任何模型，配置未变", "info");
+        return;
+      }
+      target.models = filtered;
+    } else if (ctx.hasUI) {
+      const filtered = await filterModelsInteractive(ctx, target.models);
+      if (!filtered || filtered.length === originalCount) return; // null = 保留全部
+      target.models = filtered;
+    } else {
+      ctx.ui.notify(
+        "非交互环境请用: prune <名称> --keep \"kw1,kw2\" 或 --drop \"kw1,kw2\"",
+        "warning"
+      );
+      return;
+    }
+
+    const removed = originalCount - target.models.length;
+    const ok = persistProvider(config, target, ctx);
+    if (ok) {
+      ctx.ui.notify(
+        `Provider "${name}" 模型已修剪: ${originalCount} → ${target.models.length}（移除 ${removed} 个）`,
+        "info"
+      );
+    }
+  };
+
+  // config：查看摘要 / 单个详情 / edit 编辑 / path 路径 / 重置（不实现 reset）
+  const doConfig = async (argText: string, ctx: any): Promise<void> => {
+    const parsed = parseFlagArgs(argText);
+    const rawTarget = parsed.positional[0] || getFlag(parsed.flags, "name") || "";
+    const target = rawTarget.toLowerCase();
+    const config = loadConfig();
+
+    if (target === "path") {
+      ctx.ui.notify(`配置文件: ${CONFIG_PATH}`, "info");
+      return;
+    }
+
+    if (target === "edit") {
+      if (!ctx.hasUI) {
+        ctx.ui.notify("config edit 需要交互环境（TUI/RPC），可直接编辑 JSON 文件后 /reload", "warning");
+        return;
+      }
+      const text = await ctx.ui.editor(
+        `编辑配置文件（JSON，保存即校验并重新注册）`,
+        JSON.stringify(config, null, 2)
+      );
+      if (!text || !text.trim()) {
+        ctx.ui.notify("已取消编辑", "info");
+        return;
+      }
+      try {
+        const next = JSON.parse(text);
+        if (!Array.isArray(next.providers)) throw new Error("缺少 providers 数组");
+        for (const p of next.providers) {
+          if (!p || !p.name || !p.baseUrl) throw new Error("存在缺少 name/baseUrl 的 provider");
+          if (!Array.isArray(p.models)) throw new Error(`provider "${p.name}" 的 models 需为数组`);
+          const nameErr = validateProviderName(String(p.name));
+          if (nameErr) throw new Error(`provider 名称无效: ${nameErr}`);
+        }
+        saveConfig(next);
+        registerProviders(); // 全量重注册（自动跳过 enabled=false）
+        ctx.ui.notify(`配置已保存并重新注册（${next.providers.length} 个 provider）`, "info");
+      } catch (error) {
+        ctx.ui.notify(
+          `配置无效，未保存: ${error instanceof Error ? error.message : String(error)}`,
+          "error"
+        );
+      }
+      return;
+    }
+
+    if (!target) {
+      if (config.providers.length === 0) {
+        ctx.ui.notify(`配置文件: ${CONFIG_PATH}（当前无 provider）`, "info");
+        return;
+      }
+      const lines = config.providers.map((p) => {
+        const api = p.api ?? inferApi(p.baseUrl);
+        const state = p.enabled === false ? "✗ 禁用" : "✓ 启用";
+        const proxyLine = p.proxy ? `\n  代理: ${p.proxy}` : "";
+        return `• ${p.name}  [${state}] [${api}]  ${p.models.length} 个模型\n  端点: ${p.baseUrl}${proxyLine}`;
+      });
+      ctx.ui.notify(
+        `配置文件: ${CONFIG_PATH}\n已配置 ${config.providers.length} 个 provider:\n\n${lines.join("\n\n")}\n\nconfig <name> 查看详情 · config edit 编辑 · config path 路径`,
+        "info"
+      );
+      return;
+    }
+
+    const pIdx = findProviderIndex(config, rawTarget);
+    if (pIdx < 0) {
+      ctx.ui.notify(`未找到 provider "${rawTarget}"（可用: edit / path / provider 名称）`, "error");
+      return;
+    }
+    const p = config.providers[pIdx];
+    ctx.ui.notify(`Provider "${p.name}" 配置:\n${JSON.stringify(p, null, 2)}`, "info");
+  };
+
+  // enable / disable：切换启用状态（禁用者不注册，/model 中不再出现）
+  const setEnabled = async (argText: string, ctx: any, enabled: boolean): Promise<void> => {
+    const verb = enabled ? "enable" : "disable";
+    const config = loadConfig();
+    const parsed = parseFlagArgs(argText);
+    let name = parsed.positional[0] || getFlag(parsed.flags, "name");
+
+    if (!name && ctx.hasUI) {
+      const options = config.providers
+        .filter((p) => (enabled ? p.enabled === false : p.enabled !== false))
+        .map((p) => p.name);
+      if (options.length === 0) {
+        ctx.ui.notify(
+          config.providers.length === 0 ? "暂无已配置的 provider" : `没有需要 ${verb} 的 provider`,
+          "warning"
+        );
+        return;
+      }
+      const selected = await ctx.ui.select(`选择要 ${verb} 的 Provider`, options);
+      if (!selected) return;
+      name = selected;
+    }
+
+    if (!name) {
+      ctx.ui.notify(`请指定名称: /custom-provider ${verb} <名称>`, "warning");
+      return;
+    }
+
+    const idx = findProviderIndex(config, name);
+    if (idx < 0) {
+      ctx.ui.notify(`未找到 provider "${name}"`, "error");
+      return;
+    }
+    const p = config.providers[idx];
+    const already = enabled ? p.enabled !== false : p.enabled === false;
+    if (already) {
+      ctx.ui.notify(`Provider "${name}" 已经是${enabled ? "启用" : "禁用"}状态`, "info");
+      return;
+    }
+
+    if (enabled) {
+      delete p.enabled; // 启用后配置里不残留 false
+    } else {
+      p.enabled = false;
+    }
+
+    try {
+      saveConfig(config);
+      if (enabled) {
+        pi.registerProvider(p.name, buildProviderConfig(p));
+        ctx.ui.notify(`Provider "${name}" 已启用并注册`, "info");
+      } else {
+        pi.unregisterProvider(p.name);
+        ctx.ui.notify(`Provider "${name}" 已禁用并注销（配置保留，可随时 enable 恢复）`, "info");
+      }
+    } catch (error) {
+      ctx.ui.notify(`操作失败: ${error instanceof Error ? error.message : String(error)}`, "error");
+    }
+  };
+
+  // 子命令参数补全
+  const SUBCOMMANDS = ["add", "remove", "refresh", "list", "test", "config", "enable", "disable", "prune", "help"];
+  const providerNameCompletions = () =>
+    loadConfig().providers.map((p) => ({ value: p.name, label: p.name }));
+
+  const HELP_TEXT = [
+    "custom-provider —— 管理第三方 Provider",
+    "",
+    "用法:",
+    "  /custom-provider add [名称] [flags]   交互引导或参数添加",
+    "  /custom-provider remove <名称>        删除（--yes 跳过确认）",
+    "  /custom-provider refresh [名称]       重新拉取模型列表",
+    "  /custom-provider list                 列出所有 provider（含启用状态）",
+    "  /custom-provider test <名称>          测试连接（或传 --base-url 测临时端点）",
+    "  /custom-provider config [edit|path|<名称>]  查看/编辑配置",
+    "  /custom-provider prune <名称> [--keep/--drop 关键词]  修剪模型列表（避免全量保留）",
+    "  /custom-provider enable|disable <名称> 启用/禁用 provider",
+    "  /custom-provider help                 显示本帮助",
+    "",
+    "add 常用 flags:",
+    "  --name · --base-url/--url · --api-key/--key · --api TYPE",
+    "  --models \"m1,m2\" · --model m（可多次）",
+    "  --header \"K: V\"（可多次）· --headers '{\"k\":\"v\"}'",
+    "  --auth-header · --compat '{...}' · --overrides '{\"modelId\":{...}}'",
+    "  --force（覆盖已存在）· --json '{...}'（完整配置）",
+        "  --ua <预设|原始UA>（如 claude-code / codex / opencode / cursor，或直接给自定义串）",
+"  --model-api 'id:协议'（可多次，如 claude-x:anthropic-messages）",
+    "  --model-base-url 'id:url'（可多次，和 --model-api 搭配混用双协议）",
+    "",
+    "示例:",
+    "  /custom-provider add deepseek --base-url https://api.deepseek.com/v1 \\",
+    "      --api-key $DEEPSEEK_API_KEY --models deepseek-chat,deepseek-reasoner",
+    "  /custom-provider add --json '{\"name\":\"x\",\"baseUrl\":\"...\",\"models\":[\"a\"]}'",
+    "  /custom-provider test --base-url http://localhost:8080/v1 --api-key local",
+  ].join("\n");
+
+  pi.registerCommand("custom-provider", {
+    description: "管理第三方 Provider：add / remove / refresh / list / test / help",
+    getArgumentCompletions: (prefix: string) => {
+      // 注意: pi 会用 item.value 替换整个参数段（命令名后的全部文本），
+      // 所以 value 必须是「子命令 + 完整名称」的完整参数，label 才是用于显示的名称。
+      const trimmed = prefix.trim();
+      const match = trimmed.match(/^(\S+)(?:\s+(.*))?$/);
+      const first = (match?.[1] ?? "").toLowerCase();
+      // 子命令后需要 provider 名（remove/refresh/test/enable/disable）
+      if (
+        SUBCOMMANDS.includes(first) &&
+        first !== "add" &&
+        first !== "list" &&
+        first !== "help" &&
+        first !== "config"
+      ) {
+        const rest = match?.[2] ?? "";
+        const items = providerNameCompletions()
+          .filter((i) => i.value.toLowerCase().startsWith(rest.toLowerCase()))
+          .map((i) => ({ value: `${first} ${i.value}`, label: i.label }));
+        return items.length > 0 ? items : null;
+      }
+      if (first === "config") {
+        const rest = match?.[2] ?? "";
+        const extras = ["edit", "path"].map((s) => ({ value: `config ${s}`, label: s }));
+        const providerItems = providerNameCompletions().map((i) => ({
+          value: `config ${i.value}`,
+          label: i.label,
+        }));
+        const items = [...extras, ...providerItems].filter((i) =>
+          i.value.toLowerCase().startsWith(trimmed.toLowerCase())
+        );
+        return items.length > 0 ? items : null;
+      }
+      if (first === "add") {
+        // 补全 --ua 预设键（value 保留完整参数段：add --ua <键>）
+        const uaMatch = trimmed.match(/^add\s+--ua\s*(.*)$/i);
+        if (uaMatch) {
+          const p = uaMatch[1].toLowerCase();
+          const items = Object.keys(UA_PRESETS)
+            .filter((k) => k.toLowerCase().startsWith(p))
+            .map((k) => ({
+              value: `add --ua ${k}`,
+              label: k,
+              description: UA_PRESETS[k].slice(0, 60),
+            }));
+          return items.length > 0 ? items : null;
+        }
+      }
+      const items = SUBCOMMANDS.filter((s) => s.startsWith(first)).map((s) => ({ value: s, label: s }));
+      return items.length > 0 ? items : null;
+    },
+    handler: async (args, ctx) => {
+      const t = toArgText(args).trim();
+      const parsed = parseFlagArgs(t);
+      const sub = (parsed.positional[0] || "").toLowerCase();
+      // 去掉子命令本身，剩余参数交给对应实现
+      const rest = t.replace(/^\S+/, "").trim();
+
+      switch (sub) {
+        case "add":
+          await doAdd(rest, ctx);
+          break;
+        case "remove":
+          await doRemove(rest, ctx);
+          break;
+        case "refresh":
+          await doRefresh(rest, ctx);
+          break;
+        case "list":
+          doList(ctx);
+          break;
+        case "test":
+          await doTest(rest, ctx);
+          break;
+        case "config":
+          await doConfig(rest, ctx);
+          break;
+        case "enable":
+          await setEnabled(rest, ctx, true);
+          break;
+        case "disable":
+          await setEnabled(rest, ctx, false);
+          break;
+        case "prune":
+          await doPrune(rest, ctx);
+          break;
+        case "help":
+          ctx.ui.notify(HELP_TEXT, "info");
+          break;
+        default:
+          ctx.ui.notify(sub ? `未知子命令 "${sub}"，可用: ${SUBCOMMANDS.join(" / ")}` : HELP_TEXT, sub ? "error" : "info");
+      }
+    },
+  });
+}