dsh-armory 2.3.0 → 2.3.2

package/lib/loadout.js

@@ -0,0 +1,178 @@
+// 装备清单（loadout）：把「这台机器装了什么」变成一份可分享、可对比的清单。
+//
+// 边界（决定了这里为什么只做投影，不做安装）：
+//   - 只记录名称 / 类型 / 来源 / 版本这类**身份信息**，绝不写入 env、header、
+//     token、authorization 或任何配置值；MCP 最多保留 env/header 的**键名**。
+//   - 导入只做解析与差异计算，不写盘、不安装、不调用任何市场写链。
+//   - 清单是用户主动导出、主动分享的文件；没有后端、没有账号、没有遥测。
+//
+// 数据层保持纯函数：宿主只负责收集本机条目，校验与 diff 都在这里，可独立测试。
+export const LOADOUT_SCHEMA = "dsh-armory/loadout@1";
+export const LOADOUT_MAX_ITEMS = 200;
+export const LOADOUT_MAX_BYTES = 256 * 1024;
+export const LOADOUT_DEFAULT_NAME = "我的 DSH 装备清单";
+
+const KINDS = new Set(["mcp", "skill", "expert", "plugin"]);
+const TRANSPORTS = new Set(["http", "stdio", "local", "?"]);
+const CONTROL_CHARS = /[\u0000-\u001f\u007f]+/g;
+
+function text(value, limit) {
+  return String(value ?? "").replace(CONTROL_CHARS, " ").trim().slice(0, limit);
+}
+
+function keyOf(item) {
+  return `${item.kind}\u0000${item.name}`;
+}
+
+/** 单条投影：只放行白名单字段，其余（含任何看起来像密钥的键）一律丢弃。 */
+function normalizeItem(raw) {
+  if (!raw || typeof raw !== "object" || Array.isArray(raw)) return null;
+  const kind = text(raw.kind, 20).toLowerCase();
+  if (!KINDS.has(kind)) return null;
+  const name = text(raw.name, 120);
+  if (!name) return null;
+
+  const item = { kind, name };
+  const source = text(raw.source, 200);
+  if (source) item.source = source;
+  const version = text(raw.version, 100);
+  if (version) item.version = version;
+  const updatedAt = text(raw.updatedAt, 60);
+  if (updatedAt) item.updatedAt = updatedAt;
+
+  if (kind === "mcp") {
+    const transport = text(raw.transport, 12).toLowerCase();
+    if (TRANSPORTS.has(transport)) item.transport = transport;
+    const endpointHost = text(raw.endpointHost, 200);
+    if (endpointHost) item.endpointHost = endpointHost;
+    if (Array.isArray(raw.configKeys)) {
+      const keys = [];
+      for (const value of raw.configKeys) {
+        const key = text(value, 80);
+        if (!key || keys.includes(key)) continue;
+        keys.push(key);
+        if (keys.length >= 20) break;
+      }
+      if (keys.length) item.configKeys = keys;
+    }
+    if (typeof raw.enabled === "boolean") item.enabled = raw.enabled;
+  } else if (kind === "expert") {
+    const plugin = text(raw.plugin, 160);
+    if (plugin) item.plugin = plugin;
+  } else if (kind === "plugin") {
+    const key = text(raw.key, 160);
+    if (key) item.key = key;
+  }
+  return item;
+}
+
+function countItems(items) {
+  const counts = { total: items.length, mcp: 0, skill: 0, expert: 0, plugin: 0 };
+  for (const item of items) counts[item.kind] += 1;
+  return counts;
+}
+
+function countStatuses(rows) {
+  const counts = { total: rows.length, installed: 0, update: 0, missing: 0 };
+  for (const row of rows) counts[row.status] += 1;
+  return counts;
+}
+
+/**
+ * 解析并校验一份清单（对象或 JSON 文本）。
+ * 非法结构直接抛错；单条非法 / 重复静默丢弃，避免一个坏行毁掉整份清单。
+ */
+export function normalizeLoadout(input) {
+  let raw = input;
+  if (typeof input === "string") {
+    if (input.length > LOADOUT_MAX_BYTES) throw new Error("装备清单文件过大（上限 256KB）");
+    try {
+      raw = JSON.parse(input);
+    } catch {
+      throw new Error("不是有效的 JSON");
+    }
+  }
+  if (!raw || typeof raw !== "object" || Array.isArray(raw)) throw new Error("装备清单必须是一个对象");
+  if (raw.schema !== LOADOUT_SCHEMA) throw new Error("不是 dsh-armory 装备清单（schema 不匹配）");
+  if (!Array.isArray(raw.items)) throw new Error("装备清单缺少 items 数组");
+
+  const items = [];
+  const seen = new Set();
+  for (const row of raw.items) {
+    const item = normalizeItem(row);
+    if (!item) continue;
+    const key = keyOf(item);
+    if (seen.has(key)) continue;
+    seen.add(key);
+    items.push(item);
+    if (items.length >= LOADOUT_MAX_ITEMS) break;
+  }
+
+  const loadout = {
+    schema: LOADOUT_SCHEMA,
+    name: text(raw.name, 120) || LOADOUT_DEFAULT_NAME,
+    generatedAt: text(raw.generatedAt, 60),
+    items,
+    counts: countItems(items),
+  };
+  if (raw.app && typeof raw.app === "object") {
+    const name = text(raw.app.name, 80);
+    const version = text(raw.app.version, 40);
+    if (name) loadout.app = { name, ...(version ? { version } : {}) };
+  }
+  if (raw.truncated === true) loadout.truncated = true;
+  return loadout;
+}
+
+/** 由本机收集到的条目构建一份可导出的清单。 */
+export function buildLoadout({ name, items, generatedAt, appVersion } = {}) {
+  const sourceItems = Array.isArray(items) ? items : [];
+  const loadout = normalizeLoadout({
+    schema: LOADOUT_SCHEMA,
+    name: text(name, 120) || LOADOUT_DEFAULT_NAME,
+    generatedAt: text(generatedAt, 60) || new Date().toISOString(),
+    app: { name: "dsh-armory", version: text(appVersion, 40) },
+    items: sourceItems,
+  });
+  if (sourceItems.length > LOADOUT_MAX_ITEMS) loadout.truncated = true;
+  return loadout;
+}
+
+/**
+ * 与清单做本机差异对比。
+ * 只按 kind + name 匹配；双方都有版本且不同才算「可更新」，避免把缺版本的条目误判。
+ */
+export function diffLoadout(remoteInput, localItems) {
+  const remote = normalizeLoadout(remoteInput);
+  const local = new Map();
+  for (const row of Array.isArray(localItems) ? localItems : []) {
+    const item = normalizeItem(row);
+    if (item && !local.has(keyOf(item))) local.set(keyOf(item), item);
+  }
+  const rows = remote.items.map((item) => {
+    const hit = local.get(keyOf(item));
+    const status = !hit ? "missing" : item.version && hit.version && item.version !== hit.version ? "update" : "installed";
+    return { ...item, status, localVersion: hit?.version || "" };
+  });
+  return {
+    loadout: {
+      schema: remote.schema,
+      name: remote.name,
+      generatedAt: remote.generatedAt,
+      counts: remote.counts,
+    },
+    rows,
+    counts: countStatuses(rows),
+  };
+}
+
+/** 稳定、人类可读的导出文本。 */
+export function stringifyLoadout(input) {
+  return JSON.stringify(normalizeLoadout(input), null, 2);
+}
+
+/** 下载文件名：保留中文，只清理 Windows / URL 不接受的字符。 */
+export function loadoutFileName(name) {
+  const base = text(name, 80).replace(/[\\/:*?"<>|\s]+/g, "-").replace(/^-+|-+$/g, "");
+  return `${base || "dsh-loadout"}.json`;
+}

package/lib/mcp-config.js

@@ -1,79 +1,14 @@
 import { parseDocument, Scalar, YAMLMap, YAMLSeq, isMap, isSeq } from 'yaml'
 import { isSafeExpression, makeEnvExpression, makeExpression } from './env-expression.js'
-import { MCP_CATALOG, CATEGORY_ORDER, CATEGORY_LABELS, catalogById } from './mcp-catalog.js'
-import { MCP_CATALOG_EN, CATEGORY_LABELS_EN, CATALOG_LABELS_EN } from './mcp-catalog-en.js'
 
 export const MCP_PLUGIN_NAME = '@deepseek-ai/dsh-mcp-client'
 const JS_TAG = 'tag:yaml.org,2002:js'
 const SERVER_NAME_PATTERN = /^[A-Za-z0-9_-]{1,32}$/
 const MAX_TIMER_DELAY_MS = 2147483647
 const MANAGED_CONFIG_FIELDS = ['transport', 'command', 'args', 'env', 'cwd', 'url', 'headers', 'toolCallTimeoutMs', 'failOnStartupError', 'reconnect']
-// 分类取值域与标签都来自生成的目录文件：那里是唯一真相源，顺序由生成器的 CATEGORY_ORDER
-// 决定（生成器会按它重排 MCP_CATALOG，面板的 chips 因此取到的首次出现序就是它）。
-// 再抄一份到这里就会漂移（加了分类忘了改第二处，市场的 chips 会缺一个分组）。
-export const MCP_CATEGORIES = CATEGORY_ORDER
-export const MCP_CATEGORY_LABELS = CATEGORY_LABELS
 const INTERPOLATION = /\$\{(?:env:)?([A-Za-z_][A-Za-z0-9_]*)(?::-(.*?))?\}/g
 const UNSUPPORTED_TEMPLATE = '不支持的变量表达式（只允许 ${VAR}、${VAR:-fallback} 与 ${env:VAR}）'
 
-// 内置目录 = 市场目录的投影。以前这里是硬编码的 5 条，现在是 `lib/mcp-catalog.js`
-// 的派生视图：目录加一条，内置清单与身份识别表同时跟上，不需要在两处各改一遍。
-//
-// `name`（写进配置的 serverName）取 id，是刻意的：id 一旦发布就不能改，而 serverName
-// 决定工具名 `mcp__<serverName>__<tool>`，让两者同源就不会出现「目录改名导致老配置变孤儿」。
-export const BUILTIN_MCP_SERVERS = MCP_CATALOG.map((entry) => {
-  // P1：英文覆盖与生成目录分开维护（lib/mcp-catalog-en.js）。生成器没有随本仓库
-  // 分发，直接改 mcp-catalog.js 会在下次生成时被冲掉；覆盖表缺失时逐字段回落中文。
-  const en = MCP_CATALOG_EN[entry.id] || {}
-  const server = {
-    id: entry.id,
-    label: entry.label,
-    labelEn: CATALOG_LABELS_EN[entry.id] || entry.label,
-    summary: entry.summary,
-    summaryEn: en.summary || entry.summary,
-    access: entry.access,
-    accessEn: en.access || entry.access,
-    // OPT-24：`auth` 是给面板判断「当前宿主装不装得上」的展示元数据，不是配置字段——
-    // `builtinSpec()` 只挑 MANAGED_CONFIG_FIELDS、`makeEntry()` 只挑固定字段表，两者都
-    // 不会带它，所以它和 authNote 落不进用户配置文件，mcp-client 收不到不认识的键。
-    auth: entry.auth,
-    // authNoteEn 与 authNote 同生同灭：`none` 条目没有说明，补空串会让面板分不清
-    // 「没有说明」和「说明是空的」。
-    ...(entry.authNote !== undefined ? { authNoteEn: en.authNote || entry.authNote } : {}),
-    name: entry.id,
-    transport: entry.transport,
-  }
-  for (const field of ['url', 'headers', 'command', 'args', 'authNote']) {
-    if (entry[field] !== undefined) server[field] = structuredClone(entry[field])
-  }
-  return server
-})
-
-/**
- * 「这个已配置的 server 是不是目录里的某一条」——按 endpoint / 包名认，不只看名字。
- *
- * 从目录派生而不是手工维护：以前这张表只有 5 条、和上面的硬编码清单两处同步，加一条就得
- * 记得改两个地方。现在 hosts 取自 url、packages 取自目录的 `packages`（stdio 型可从 args
- * 推导），新增条目自动生效。
- *
- * 为什么需要它：用户可能把 Exa 配成了 `my-exa`。安装时靠它识别「已经装过」而跳过，
- * 而不是再插入一条重复的。
- */
-const BUILTIN_MCP_IDENTITIES = Object.fromEntries(MCP_CATALOG.map((entry) => {
-  const hosts = []
-  if (typeof entry.url === 'string') {
-    try {
-      hosts.push(new URL(entry.url).hostname.toLowerCase())
-    } catch { /* url 不是合法 URL 时没有可认领的 host，交给 packages 兜底 */ }
-  }
-  // 包名优先取目录里显式写的（HTTP 型也可能有对应的本地 npx 包，那层知识推不出来），
-  // 没有才从 args 推导：只认非开关的参数，`-y`、`--flag` 这类不是包名。
-  const packages = entry.packages ?? (entry.args || []).filter((arg) => typeof arg === 'string'
-    && !arg.startsWith('-')
-    && /^[@a-z0-9]/i.test(arg))
-  return [entry.id, { hosts, packages }]
-}))
-
 function isObject(value) {
   return value !== null && typeof value === 'object' && !Array.isArray(value)
 }
@@ -517,109 +452,3 @@ export function updateManagedMcpPatch(content, specs, { replace = false, removeN
   }
   return String(doc)
 }
-
-function packageTokenMatches(value, packageName) {
-  if (typeof value !== 'string') return false
-  return value.split(/\s+/).some((token) => token === packageName || token.startsWith(`${packageName}@`))
-}
-
-function matchesBuiltinIdentity(server, builtin) {
-  const name = server?.name ?? server?.serverName
-  if (name === builtin.name) return true
-  const identity = BUILTIN_MCP_IDENTITIES[builtin.id]
-  const invocation = [server?.url, server?.command, ...(Array.isArray(server?.args) ? server.args : [])].filter((value) => typeof value === 'string')
-  if (identity.hosts?.some((host) => invocation.some((value) => {
-    try {
-      return new URL(value).hostname.toLowerCase() === host
-    } catch {
-      return value.includes(`://${host}/`) || value.includes(`://${host}?`)
-    }
-  }))) return true
-  return identity.packages?.some((packageName) => invocation.some((value) => packageTokenMatches(value, packageName))) === true
-}
-
-function builtinSpec(builtin) {
-  const spec = { name: builtin.name }
-  for (const field of MANAGED_CONFIG_FIELDS) {
-    if (builtin[field] !== undefined) spec[field] = structuredClone(builtin[field])
-  }
-  return spec
-}
-
-/**
- * 目录 → 面板要的形状。
- *
- * 浏览器那半是预构建 bundle，**拿不到本模块的常量**（不 import Host 侧代码），所以市场的
- * 展示字段（分类、提供方、主页、需要哪些密钥）必须随这次 RPC 一起过去。少带一个字段的
- * 后果是面板侧只能显示 undefined，而那是 jsdom 看不出来的。
- *
- * @param {ReadonlyArray<object>} effectiveServers - 当前生效的 MCP 配置（用来判「已配置」）。
- * @returns {object[]} 面板用的目录条目。
- */
-export function builtinMcpCatalog(effectiveServers) {
-  return BUILTIN_MCP_SERVERS.map((builtin) => {
-    const matches = effectiveServers.filter((server) => matchesBuiltinIdentity(server, builtin))
-    const installedAs = [...new Set(matches.map((server) => server?.name ?? server?.serverName).filter(Boolean))]
-    const source = catalogById().get(builtin.id) || {}
-    return {
-      id: builtin.id,
-      label: builtin.label,
-      labelEn: builtin.labelEn || builtin.label,
-      summary: builtin.summary,
-      summaryEn: builtin.summaryEn || builtin.summary,
-      access: builtin.access,
-      accessEn: builtin.accessEn || builtin.access,
-      // OPT-24：`auth` 走 builtin（BUILTIN_MCP_SERVERS 已投影），面板据此降级提示
-      // oauth 条目；`authNote` 只在存在时挂键——`none` 条目根本没有这个字段，补成空串
-      // 会让面板分不清「没有说明」和「说明是空的」。
-      auth: builtin.auth,
-      ...(builtin.authNote !== undefined ? { authNote: builtin.authNote } : {}),
-      ...(builtin.authNoteEn !== undefined ? { authNoteEn: builtin.authNoteEn } : {}),
-      name: builtin.name,
-      transport: builtin.transport,
-      configuration: builtinSpec(builtin),
-      installed: installedAs.length > 0,
-      installedAs,
-      // —— 市场展示字段（bundle 侧读不到常量，只能这里带过去）——
-      category: source.category,
-      categoryLabel: MCP_CATEGORY_LABELS[source.category],
-      categoryLabelEn: CATEGORY_LABELS_EN[source.category] || MCP_CATEGORY_LABELS[source.category],
-      vendor: source.vendor,
-      homepage: source.homepage,
-      envKeys: source.envKeys || [],
-      // 连接参数（HOST/PORT/USER）与凭据分开：市场对前者显示「需填连接信息」而不是
-      // 「需密钥」——Redis / ClickHouse 是本机服务，说成要申请 Key 是误导。
-      configKeys: source.configKeys || [],
-      // 含 `<占位符>` 的条目（如 filesystem 的 `<允许访问的目录>`）装完**不能直接用**：
-      // 拿占位符当真实参数启动会失败。市场要据此提示用户先编辑，而不是显示「安装成功」。
-      placeholders: source.placeholders || [],
-    }
-  })
-}
-
-function selectedBuiltins(ids) {
-  if (!Array.isArray(ids) || !ids.length || !ids.every((id) => typeof id === 'string')) {
-    throw new Error('内置 MCP ids 必须是非空字符串数组')
-  }
-  const selectedIds = new Set(ids)
-  const knownIds = new Set(BUILTIN_MCP_SERVERS.map((builtin) => builtin.id))
-  const unknown = [...selectedIds].filter((id) => !knownIds.has(id))
-  if (unknown.length) throw new Error(`未知的内置 MCP：${unknown.join(', ')}`)
-  return BUILTIN_MCP_SERVERS.filter((builtin) => selectedIds.has(builtin.id))
-}
-
-export function appendSelectedBuiltinMcpServers(content, effectiveServers, ids, { reservedIds = [] } = {}) {
-  const selected = selectedBuiltins(ids)
-  const skipped = selected.filter((builtin) => effectiveServers.some((server) => matchesBuiltinIdentity(server, builtin)))
-  const skippedIds = new Set(skipped.map((builtin) => builtin.id))
-  const additions = selected.filter((builtin) => !skippedIds.has(builtin.id))
-  const updated = additions.length
-    ? updateManagedMcpPatch(content, additions.map(builtinSpec), { replace: false, reservedIds })
-    : content
-
-  return {
-    content: updated,
-    added: additions.map((builtin) => builtin.id),
-    skipped: skipped.map((builtin) => builtin.id),
-  }
-}

package/lib/mcp-oauth.js

@@ -29,7 +29,7 @@ import { homedir } from "node:os";
 import { join } from "node:path";
 
 /** 插件版本：DCR 的 clientInfo 与 UA 共用一处，避免两边各自漂移。 */
-const PLUGIN_VERSION = "2.3.0";
+const PLUGIN_VERSION = "2.3.2";
 const USER_AGENT = `dsh-armory/${PLUGIN_VERSION} (+mcp-oauth)`;
 const NET_TIMEOUT_MS = 15_000;
 /** 授权流程整体存活时间：超过就判过期，避免会话表无限增长。 */
@@ -59,6 +59,69 @@ function sha256hex(text) {
   return createHash("sha256").update(String(text)).digest("hex");
 }
 
+// ── 凭据形状 ────────────────────────────────────────────────────────────
+// 这一层存在的理由是一条真实事故：`ensureAccessToken()` 返回的是对象
+// `{ok, accessToken, ...}`，调用方写成 `String(await ensureAccessToken(url))` 就得到
+// `"[object Object]"` —— 真值、非空、于是被当成正经令牌注进 `authorization` 头并落盘。
+// 服务器收到后回的不是 401「empty access token」而是 400「token parse failed」，
+// 装前探测只认 401/403，于是「需要授权」被彻底漏判：配置写进去了、授权页永远不弹、
+// 连接永远失败。所以「什么才算一个能用的令牌」必须只写一次、放在这里。
+
+/** Bearer 令牌长度上限：正常签发物不会这么长，超长基本是把整坨响应粘回来了。 */
+const BEARER_TOKEN_MAX = 8192;
+
+/** 去掉可选的 `Bearer ` 前缀与首尾空白（光杆一个 "Bearer" 等于没有令牌）。 */
+function stripBearerPrefix(value) {
+  return String(value ?? "").replace(/^\s*Bearer\b[ \t]*/i, "").trim();
+}
+
+/**
+ * 一眼假：序列化残骸（`[object Object]` / `undefined` / `NaN`）、空值、光杆 `Bearer`。
+ * 未替换的 `${TOKEN}` 占位符**不算**残骸——那是 R7 令牌引导的合法中间态，
+ * 由 `missingSlots` 单独回报面板，不能被这里悄悄抹掉。
+ */
+export function isSerializedGarbageCredential(value) {
+  if (value === null || value === undefined) return true;
+  if (typeof value !== "string") return true;
+  const text = value.trim();
+  if (!text) return true;
+  if (/^\[object\s+\w+\]$/i.test(text) || /\[object\s+\w+\]/i.test(text)) return true;
+  if (/^(?:undefined|null|NaN)$/i.test(stripBearerPrefix(text))) return true;
+  return !stripBearerPrefix(text);
+}
+
+/** 是不是一个可以原样发给服务器的 access token。 */
+export function isUsableBearerToken(value) {
+  if (isSerializedGarbageCredential(value)) return false;
+  const token = stripBearerPrefix(value);
+  if (token.length > BEARER_TOKEN_MAX) return false;
+  if (/\$\{[^}]*\}/.test(token)) return false;
+  // 控制符/换行：HTTP 头里出现就是注入面（fetch 也会拒），一律视为不可用。
+  return !/[\u0000-\u001f\u007f\u0080-\u009f]/.test(token);
+}
+
+// ── 「这是鉴权失败吗」判定 ───────────────────────────────────────────────
+
+/**
+ * 各家网关的鉴权失败措辞（JSON-RPC error.message 里常见）。刻意只列鉴权语义，
+ * 不收 "not found" / "invalid params" 这类——把服务器故障判成「要授权」会把用户
+ * 引到一条根本走不通的授权路上。
+ */
+const AUTH_BODY_RE =
+  /(empty access token|access token (?:empty|missing|invalid)|token parse|invalid[ _-]?token|missing[ _-]?token|no (?:access )?token|token (?:expired|invalid)|unauthorized|unauthenticated|(?:authentication|authorization) (?:failed|error|required)|(?:需要|请)(?:登录|授权|鉴权))/i;
+
+/**
+ * 一次 MCP 握手失败是不是「缺凭据」。
+ * 401/403 无条件算；其它 4xx 只有在响应体明确说鉴权时才算（腾讯 ima 就是 400 +
+ * `msg:token parse failed`，且不带 `WWW-Authenticate`）；2xx/3xx/5xx 一律不算。
+ */
+export function mcpAuthFailure(status, bodyText = "") {
+  const code = Number(status) || 0;
+  if (code === 401 || code === 403) return true;
+  if (code < 400 || code >= 500) return false;
+  return AUTH_BODY_RE.test(String(bodyText || ""));
+}
+
 /** PKCE 授权码流程的 verifier/challenge（S256）。 */
 export function createPkce() {
   const verifier = b64url(randomBytes(48));
@@ -114,8 +177,8 @@ async function fetchJson(url, init = {}) {
 // ── 探测 ────────────────────────────────────────────────────────────────
 
 /**
- * 打一次 MCP initialize，拿回状态码与 `WWW-Authenticate`。
- * 只用于确认「这颗 server 是不是 401 且声明了 OAuth」，不做其它判断。
+ * 打一次 MCP initialize，拿回状态码、`WWW-Authenticate` 与响应体摘要。
+ * 只用于确认「这颗 server 是不是要凭据」，不做其它判断。
  */
 export async function probeServer(serverUrl, headers = {}) {
   const body = JSON.stringify({
@@ -142,16 +205,18 @@ export async function probeServer(serverUrl, headers = {}) {
       },
       body
     });
-    // 读掉 body，避免 socket 悬挂
-    await response.text().catch(() => "");
+    // 读掉 body，避免 socket 悬挂；正文还要留给鉴权判定（不少网关 400 也带鉴权语义）。
+    const text = await response.text().catch(() => "");
     return {
       ok: true,
       status: response.status,
       wwwAuthenticate: response.headers.get("www-authenticate") || "",
+      body: trimText(text, 400),
+      authRequired: mcpAuthFailure(response.status, text),
       error: ""
     };
   } catch (error) {
-    return { ok: false, status: 0, wwwAuthenticate: "", error: String(error?.message || error) };
+    return { ok: false, status: 0, wwwAuthenticate: "", body: "", authRequired: false, error: String(error?.message || error) };
   }
 }
 
@@ -439,7 +504,8 @@ export async function clearTokenRecord(serverUrl) {
 
 /** 记录里是否有一个「还没过期」的 access token（留 60s 余量）。 */
 export function tokenIsFresh(record) {
-  if (!record || !str(record.accessToken)) return false;
+  // 形状先于时效：`[object Object]` 这种残骸哪怕带着未来的 expiresAt 也不是令牌。
+  if (!record || !isUsableBearerToken(record.accessToken)) return false;
   if (!record.expiresAt) return true; // 服务器没给 expires_in：视为长期有效，等 401 再说
   // 落盘时写的是 ISO 串（见 exchangeCode），但令牌库是纯 JSON、可能被人手改或由
   // 旧版本写成数字毫秒，两种都认：数字直接当时间戳，字符串才走 Date.parse。
@@ -478,7 +544,7 @@ async function refreshAccessToken(record) {
     headers: { "content-type": "application/x-www-form-urlencoded" },
     body: body.toString()
   });
-  if (!result.ok || !str(result.json?.access_token)) {
+  if (!result.ok || !isUsableBearerToken(result.json?.access_token)) {
     return { ok: false, accessToken: "", error: `刷新 token 失败（HTTP ${result.status || "网络错误"}）：${trimText(result.text)}` };
   }
   await writeTokenRecord(record.serverUrl, tokenRecordPatch(result.json));
@@ -512,20 +578,35 @@ function tokenRecordPatch(tokenResponse) {
 export async function beginAuthorization({ serverName, serverUrl, headers = {}, clientName = "DeepSeek Harness" } = {}) {
   if (!serverUrl) return fail("", "", "", "缺少 server url");
   const probe = await probeServer(serverUrl, headers);
-  if (!probe.ok) return fail("", "", "", `无法连接 ${serverUrl}：${probe.error}`);
-  if (probe.status !== 401 && probe.status !== 403) {
-    // 有些服务器首次 initialize 回 200，鉴权在 tools/call 才触发；这里仍允许继续试一次。
-    if (probe.status >= 400 && probe.status !== 401 && probe.status !== 403) {
-      return fail("", "", "", `服务器返回 HTTP ${probe.status}，不是预期的 401/403，无法确认其 OAuth 要求`);
-    }
+  if (!probe.ok) return fail("", "", "", `无法连接 ${serverUrl}：${probe.error}`, { serverUrl });
+  if (probe.status >= 400 && !probe.authRequired) {
+    // 明确的非鉴权失败（404 路径错、500 服务器挂了…）：继续往下走只会把用户
+    // 引到一条根本不存在的授权路上，直接说清楚更省时间。
+    return fail("", "", "", `服务器返回 HTTP ${probe.status}，不是预期的鉴权错误：${probe.body || "（无响应体）"}`, { serverUrl });
   }
+  // 到这里要么服务器点名要凭据（401/403/4xx 鉴权体），要么匿名握手就过了
+  // （有些实现把鉴权推迟到 tools/call）——两种都继续试一次发现流程。
 
   const resource = await resolveProtectedResource({ serverUrl, wwwAuthenticate: probe.wwwAuthenticate });
-  if (!resource.ok) return fail("", "", "", resource.error);
+  if (!resource.ok) return fail("", "", "", resource.error, { serverUrl, manualTokenOnly: true });
   const as = await resolveAuthorizationServer(resource.authorizationServers[0]);
-  if (!as.ok) return fail("", "", "", as.error);
+  if (!as.ok) {
+    // 现实里很常见：服务器要 Bearer token，但压根不实现 RFC 9728/8414 的 well-known
+    // 发现（腾讯 ima 就是这样）。这时没有任何 authorizeUrl 可开，硬报错等于把用户
+    // 关在门外——回 manualTokenOnly，让面板把手填令牌那条兜底路摊开给他。
+    return fail("", "", "", `${as.error}\n该服务器没有提供标准 OAuth 授权发现，无法自动打开授权页；如果你已有访问令牌，可以直接粘贴安装。`, {
+      serverUrl,
+      manualTokenOnly: true
+    });
+  }
   if (!as.tokenEndpointAuthMethods.includes("none")) {
-    return fail("", "", "", `该授权服务器要求客户端认证（${as.tokenEndpointAuthMethods.join("/")}），本插件只支持公共客户端（none）`);
+    return fail(
+      "",
+      "",
+      "",
+      `该授权服务器要求客户端认证（${as.tokenEndpointAuthMethods.join("/")}），本插件只支持公共客户端（none）；如果你已有访问令牌，可以直接粘贴安装。`,
+      { serverUrl, manualTokenOnly: true }
+    );
   }
 
   const scope = as.scopesSupported.length ? as.scopesSupported.join(" ") : "";
@@ -543,13 +624,22 @@ export async function beginAuthorization({ serverName, serverUrl, headers = {},
     const template = extractExpectedRedirectUri(registration.raw || registration.error);
     if (!template) {
       loopback.close();
-      return fail("", "", "", registration.error);
+      return fail("", "", "", `${registration.error}\n动态注册走不通，无法生成授权页；如果你已有访问令牌，可以直接粘贴安装。`, {
+        serverUrl,
+        manualTokenOnly: true
+      });
     }
     const expected = substituteRedirectPlaceholder(template, serverName || clientName);
     const retry = await registerClient(as, { redirectUri: expected, clientName, scope });
     if (!retry.ok) {
       loopback.close();
-      return fail("", "", "", `${registration.error}\n改用服务器指定的回调地址 ${expected} 重试仍失败：${retry.error}`);
+      return fail(
+        "",
+        "",
+        "",
+        `${registration.error}\n改用服务器指定的回调地址 ${expected} 重试仍失败：${retry.error}\n如果你已有访问令牌，可以直接粘贴安装。`,
+        { serverUrl, manualTokenOnly: true }
+      );
     }
     registration = retry;
     redirectUri = expected;
@@ -619,8 +709,21 @@ function buildAuthorizeUrl({ authorizationEndpoint, clientId, redirectUri, scope
   return url.href;
 }
 
-function fail(sessionId, authorizeUrl, mode, error) {
-  return { ok: false, sessionId, authorizeUrl, mode, redirectUri: "", hint: "", error };
+function fail(sessionId, authorizeUrl, mode, error, extra = {}) {
+  return {
+    ok: false,
+    sessionId,
+    authorizeUrl,
+    mode,
+    redirectUri: "",
+    hint: "",
+    // manualTokenOnly：授权页这条路走不通，但「手填访问令牌」仍然可用。面板据此
+    // 也要把弹层开出来（而不是只甩一行红字），否则用户看到的是死路。
+    manualTokenOnly: false,
+    serverUrl: "",
+    error,
+    ...extra
+  };
 }
 
 function pruneSessions() {
@@ -667,7 +770,7 @@ async function exchangeCode(session, code) {
     headers: { "content-type": "application/x-www-form-urlencoded" },
     body: body.toString()
   });
-  if (!result.ok || !str(result.json?.access_token)) {
+  if (!result.ok || !isUsableBearerToken(result.json?.access_token)) {
     session.status = "failed";
     session.error = `换取 token 失败（HTTP ${result.status || "网络错误"}）：${trimText(result.text)}`;
     return;
@@ -775,8 +878,12 @@ export async function saveManualToken({ serverUrl, serverName = "", token, token
   const raw = String(token || "").trim();
   if (!serverUrl) return { ok: false, error: "缺少 server url" };
   if (!raw) return { ok: false, error: "token 不能为空" };
-  const accessToken = raw.replace(/^Bearer\s+/i, "").trim();
+  const accessToken = stripBearerPrefix(raw);
   if (!accessToken) return { ok: false, error: "token 不能为空" };
+  // 手填这条路最容易粘进残骸（`[object Object]`、没替换的 ${TOKEN}、带换行的整段 curl）。
+  if (!isUsableBearerToken(accessToken)) {
+    return { ok: false, error: "这不像是个可用的访问令牌（空值、未替换的 ${...} 占位符或序列化残骸），请重新从服务方复制。" };
+  }
   await writeTokenRecord(serverUrl, {
     accessToken,
     tokenType: "Bearer",
@@ -801,6 +908,4 @@ export async function authorizationOverview(serverUrl) {
     refreshable: Boolean(str(record.refreshToken)),
     savedAt: str(record.savedAt)
   };
-}
-
-export const __testing = { sessions, recordPathFor, buildAuthorizeUrl, tokenRecordPatch };
+}