dsh-sub2api-sync 0.1.0 → 0.2.1

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Shuai-S
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -25,19 +25,13 @@ dsh plugin --profile web add @mangoc/dsh-sub2api-sync   # canonical (scoped)
 dsh plugin --profile web add dsh-sub2api-sync           # alias (unscoped short name)
 ```
 
-**GitHub Releases tarball** (no npm involved; the URLs always point to the
-latest release; both variants are equivalent):
+**GitHub Releases tarball** (no npm involved; the URL always points to the
+latest release):
 
 ```sh
-dsh plugin --profile web add https://github.com/Shuai-S/dsh-sub2api-sync/releases/latest/download/mangoc-dsh-sub2api-sync.tgz
-# or the short-name variant:
 dsh plugin --profile web add https://github.com/Shuai-S/dsh-sub2api-sync/releases/latest/download/dsh-sub2api-sync.tgz
 ```
 
-You can also copy a version-pinned tarball URL (e.g.
-`mangoc-dsh-sub2api-sync-0.1.0.tgz` / `dsh-sub2api-sync-0.1.0.tgz`) from the
-[Releases page](https://github.com/Shuai-S/dsh-sub2api-sync/releases).
-
 **From source** (pnpm runs the `prepare` build on git dependencies; needs a
 local toolchain and is slower on first install):
 
@@ -59,7 +53,7 @@ CI ([.github/workflows/release.yml](../../../.github/workflows/release.yml))
 runs the whole flow: bump `version` in
 `packages/llm/sub2api-sync/package.json` → commit →
 `git tag vX.Y.Z && git push origin vX.Y.Z` → `pnpm check` → two tarballs →
-GitHub Release (4 assets: 2 versioned + 2 stable-name copies) → npm dual
+GitHub Release (1 stable-name tarball asset) → npm dual
 publish (requires the repo secret `NPM_TOKEN`; `publishConfig.registry` is
 pinned to the official npmjs registry, immune to mirror configs). Manual dual
 publish from a local checkout:

package/README.zh.md

@@ -26,16 +26,12 @@ dsh plugin --profile web add @mangoc/dsh-sub2api-sync   # canonical（scoped）
 dsh plugin --profile web add dsh-sub2api-sync           # 别名（无 scope 短名）
 ```
 
-**GitHub Releases tarball**（不依赖 npm；地址始终指向最新版，两种变体内容等价）：
+**GitHub Releases tarball**（不依赖 npm；地址始终指向最新版）：
 
 ```sh
-dsh plugin --profile web add https://github.com/Shuai-S/dsh-sub2api-sync/releases/latest/download/mangoc-dsh-sub2api-sync.tgz
-# 或短名变体：
 dsh plugin --profile web add https://github.com/Shuai-S/dsh-sub2api-sync/releases/latest/download/dsh-sub2api-sync.tgz
 ```
 
-也可以从 [Releases 页](https://github.com/Shuai-S/dsh-sub2api-sync/releases) 复制带版本号的 tarball URL（形如 `mangoc-dsh-sub2api-sync-0.1.0.tgz` / `dsh-sub2api-sync-0.1.0.tgz`）以锁定版本。
-
 **从源码安装**（pnpm 会对 git 依赖自动执行 `prepare` 构建；需要本机构建链，首次较慢）：
 
 ```sh
@@ -46,7 +42,7 @@ dsh plugin --profile web add github:Shuai-S/dsh-sub2api-sync#path:packages/llm/s
 
 ### 发布（维护者）
 
-每次发版**双包同步发布**（[scripts/pack-all.mjs](scripts/pack-all.mjs)）：scoped canonical 与无 scope 别名各出一个 tarball，版本号完全一致；客户端 bundle 内嵌的插件名（挂载 key、详情页匹配、ModuleLoader id）与 `cordis.patch.yml` 在打包时按包名注入，两个变体都可独立安装。CI（[.github/workflows/release.yml](../../../.github/workflows/release.yml)）自动完成全流程：bump `packages/llm/sub2api-sync/package.json` 的 `version` → 提交 → `git tag vX.Y.Z && git push origin vX.Y.Z` → `pnpm check` → 双 tarball → GitHub Release（4 个资产：2 个版本号 tarball + 2 个固定名副本）→ npm 双发布（需要仓库 secret `NPM_TOKEN`；`publishConfig.registry` 已锁定 npmjs 官方源，不受 npmmirror 镜像影响）。本地手动双发布：
+每次发版**双包同步发布**（[scripts/pack-all.mjs](scripts/pack-all.mjs)）：scoped canonical 与无 scope 别名各出一个 tarball，版本号完全一致；客户端 bundle 内嵌的插件名（挂载 key、详情页匹配、ModuleLoader id）与 `cordis.patch.yml` 在打包时按包名注入，两个变体都可独立安装。CI（[.github/workflows/release.yml](../../../.github/workflows/release.yml)）自动完成全流程：bump `packages/llm/sub2api-sync/package.json` 的 `version` → 提交 → `git tag vX.Y.Z && git push origin vX.Y.Z` → `pnpm check` → 双 tarball → npm 双发布（需要仓库 secret `NPM_TOKEN`；`publishConfig.registry` 已锁定 npmjs 官方源，不受 npmmirror 镜像影响）；GitHub Release 附短名 tarball 资产。本地手动双发布：
 
 ```sh
 pnpm pack:all    # 产出 dist/ 下两个 tarball，仓库文件自动还原

package/lib/client.cjs

@@ -125,8 +125,8 @@ const zh = {
 	detailSectionEmpty: "还没有同步过——在设置 → Sub2API 同步 完成首次同步",
 	activationTitle: "开始使用 Sub2API 同步",
 	activationStep1: "1. 在设置中连接面板（账号密码或网页授权）",
-	activationStep2: "2. 勾选要同步的分组（key 自动准备）",
-	activationStep3: "3. 点击「立即同步」，模型即可使用",
+	activationStep2: "2. 在 Keys 卡勾选要同步的 key（可跨分组）",
+	activationStep3: "3. 点击「同步所选」，模型即可使用",
 	activationOpenConfig: "打开配置页",
 	activationDismiss: "知道了",
 	keysTitle: "Keys",
@@ -235,8 +235,8 @@ const en = {
 	detailSectionEmpty: "Never synced — finish the first sync in Settings → Sub2API Sync",
 	activationTitle: "Get started with Sub2API Sync",
 	activationStep1: "1. Connect the panel in Settings (account password or web authorization)",
-	activationStep2: "2. Check the groups to sync (keys are prepared automatically)",
-	activationStep3: "3. Click \"Sync now\" and the models are ready",
+	activationStep2: "2. Tick the keys to sync on the Keys card (cross-group)",
+	activationStep3: "3. Click \"Sync selected\" and the models are ready",
 	activationOpenConfig: "Open configuration",
 	activationDismiss: "Got it",
 	keysTitle: "Keys",
@@ -1518,7 +1518,7 @@ function Sub2apiSyncSection({ t, api, config, useStatus: useStatus$1 }) {
 	const instanceMarker = (configValues?.baseURL ?? "").trim().replace(/\/+$/, "").toLowerCase();
 	const previousInstance = (0, react.useRef)(undefined);
 	(0, react.useEffect)(() => {
-		const markerKey = "sub2api-sync:last-instance";
+		const markerKey = `${PKG_NAME}:last-instance`;
 		let stored;
 		try {
 			stored = window.localStorage.getItem(markerKey) ?? undefined;
@@ -2313,7 +2313,7 @@ function DetailSectionBody({ t }) {
 //#endregion
 //#region src/client/plugins/ActivationGuide.tsx
 function ActivationGuide(props) {
-	const { t, onDismiss, onOpenDetails } = props;
+	const { t, onDismiss, onOpenDetails, openBundleDetails } = props;
 	return (0, react_jsx_runtime.jsxs)("div", {
 		className: "s2s-card",
 		children: [
@@ -2333,7 +2333,9 @@ function ActivationGuide(props) {
 				className: "s2s-actions",
 				children: [(0, react_jsx_runtime.jsx)(__deepseek_ai_dsh_client_ui_primitives.Button, {
 					variant: "primary",
-					onClick: onOpenDetails,
+					onClick: () => {
+						if (!(openBundleDetails?.() ?? false)) onOpenDetails();
+					},
 					children: t("activationOpenConfig")
 				}), (0, react_jsx_runtime.jsx)(__deepseek_ai_dsh_client_ui_primitives.Button, {
 					variant: "ghost",
@@ -2391,10 +2393,17 @@ function mount(ctx) {
 		id: "sub2api-sync",
 		locale: NS
 	}, DetailSection));
+	const activationOps = { openBundleDetails: () => {
+		const nav = ctx.pluginNavigation;
+		if (nav === undefined) return false;
+		nav.openBundle(PKG_NAME);
+		return true;
+	} };
 	ctx.slots.inject("plugins.bundle.activation", () => ctx.slots.register({
 		name: "plugins.bundle.activation",
 		key: PKG_NAME,
-		locale: NS
+		locale: NS,
+		inject: () => activationOps
 	}, ActivationGuide));
 }
 
@@ -2404,7 +2413,8 @@ const name = "dsh-sub2api-sync-client";
 const inject = [
 	"slots",
 	"locale",
-	"configForms"
+	"configForms",
+	"pluginNavigation"
 ];
 function apply(ctx) {
 	mount(ctx);

package/lib/client.js

@@ -131,8 +131,8 @@ const zh = {
 	detailSectionEmpty: "还没有同步过——在设置 → Sub2API 同步 完成首次同步",
 	activationTitle: "开始使用 Sub2API 同步",
 	activationStep1: "1. 在设置中连接面板（账号密码或网页授权）",
-	activationStep2: "2. 勾选要同步的分组（key 自动准备）",
-	activationStep3: "3. 点击「立即同步」，模型即可使用",
+	activationStep2: "2. 在 Keys 卡勾选要同步的 key（可跨分组）",
+	activationStep3: "3. 点击「同步所选」，模型即可使用",
 	activationOpenConfig: "打开配置页",
 	activationDismiss: "知道了",
 	keysTitle: "Keys",
@@ -241,8 +241,8 @@ const en = {
 	detailSectionEmpty: "Never synced — finish the first sync in Settings → Sub2API Sync",
 	activationTitle: "Get started with Sub2API Sync",
 	activationStep1: "1. Connect the panel in Settings (account password or web authorization)",
-	activationStep2: "2. Check the groups to sync (keys are prepared automatically)",
-	activationStep3: "3. Click \"Sync now\" and the models are ready",
+	activationStep2: "2. Tick the keys to sync on the Keys card (cross-group)",
+	activationStep3: "3. Click \"Sync selected\" and the models are ready",
 	activationOpenConfig: "Open configuration",
 	activationDismiss: "Got it",
 	keysTitle: "Keys",
@@ -1524,7 +1524,7 @@ function Sub2apiSyncSection({ t, api, config, useStatus: useStatus$1 }) {
 	const instanceMarker = (configValues?.baseURL ?? "").trim().replace(/\/+$/, "").toLowerCase();
 	const previousInstance = (0, react.useRef)(undefined);
 	(0, react.useEffect)(() => {
-		const markerKey = "sub2api-sync:last-instance";
+		const markerKey = `${PKG_NAME}:last-instance`;
 		let stored;
 		try {
 			stored = window.localStorage.getItem(markerKey) ?? undefined;
@@ -2319,7 +2319,7 @@ function DetailSectionBody({ t }) {
 //#endregion
 //#region src/client/plugins/ActivationGuide.tsx
 function ActivationGuide(props) {
-	const { t, onDismiss, onOpenDetails } = props;
+	const { t, onDismiss, onOpenDetails, openBundleDetails } = props;
 	return (0, react_jsx_runtime.jsxs)("div", {
 		className: "s2s-card",
 		children: [
@@ -2339,7 +2339,9 @@ function ActivationGuide(props) {
 				className: "s2s-actions",
 				children: [(0, react_jsx_runtime.jsx)(__deepseek_ai_dsh_client_ui_primitives.Button, {
 					variant: "primary",
-					onClick: onOpenDetails,
+					onClick: () => {
+						if (!(openBundleDetails?.() ?? false)) onOpenDetails();
+					},
 					children: t("activationOpenConfig")
 				}), (0, react_jsx_runtime.jsx)(__deepseek_ai_dsh_client_ui_primitives.Button, {
 					variant: "ghost",
@@ -2397,10 +2399,17 @@ function mount(ctx) {
 		id: "sub2api-sync",
 		locale: NS
 	}, DetailSection));
+	const activationOps = { openBundleDetails: () => {
+		const nav = ctx.pluginNavigation;
+		if (nav === undefined) return false;
+		nav.openBundle(PKG_NAME);
+		return true;
+	} };
 	ctx.slots.inject("plugins.bundle.activation", () => ctx.slots.register({
 		name: "plugins.bundle.activation",
 		key: PKG_NAME,
-		locale: NS
+		locale: NS,
+		inject: () => activationOps
 	}, ActivationGuide));
 }
 
@@ -2410,7 +2419,8 @@ const name = "dsh-sub2api-sync-client";
 const inject = [
 	"slots",
 	"locale",
-	"configForms"
+	"configForms",
+	"pluginNavigation"
 ];
 function apply(ctx) {
 	mount(ctx);

package/lib/config.d.ts

@@ -24,9 +24,22 @@
  * @module sub2api-sync/config
  */
 import z from '@deepseek-ai/schemastery';
-import type { ModelTemplate } from './protocols.ts';
+import type { ModelTemplate, PiAiRetryPolicy } from './protocols.ts';
 ./protocols.jsApiProtocol } from './types.ts';
-/** ./types.jskey-source options; `keyId` absent = 自动（组名建/复用）. */
+/** ./types.jsn overrides over the plugin's built-in lenient retry policy
+ * (`SUB2API_RETRY_POLICY`): an absent key inherits the built-in value.
+ * YAML-only advanced field (一字段一写面 — the tuning card does not render it). */
+export interface RetryPolicyOverride {
+    mode?: PiAiRetryPolicy['mode'];
+    maxRetries?: number;
+    retryableCodes?: string[];
+    backoff?: {
+        initialDelayMs?: number;
+        maxDelayMs?: number;
+        jitterRatio?: number;
+    };
+}
+/** Per-group key-source options; `keyId` absent = 自动（组名建/复用）. */
 export interface Sub2apiSyncConfig {
     /** sub2api instance address, with or without a trailing `/v1`. */
     baseURL?: string;
@@ -56,6 +69,15 @@ export interface Sub2apiSyncConfig {
     deleteOrphanKeys?: boolean;
     /** Scheduled resync interval; absent = off. */
     syncIntervalMs?: number;
+    /** Retry policy overrides merged over the built-in policy every synced
+     * route carries (see `RetryPolicyOverride`). */
+    retryPolicy?: RetryPolicyOverride;
+    /** Route-level context-window default for models the metadata enrichment
+     * cannot match. Default 128000. */
+    defaultContextWindow?: number;
+    /** Route-level max-output-tokens default for models the metadata
+     * enrichment cannot match. Default 8192. */
+    defaultMaxTokens?: number;
     /** Escape hatch: allow action routes from private-network peers (§11). Default false. */
     allowRemoteActions?: boolean;
 }
@@ -63,7 +85,7 @@ export declare const Config: z<Sub2apiSyncConfig, any>;
 /** The default provider-name template — owned by `types.ts` (browser-safe), re-exported here. */
 export { DEFAULT_PROVIDER_NAME_TEMPLATE } from './types.ts';
 /**
- * One resolved volatile field:./types.jsreference whose `get()` yields the
+ * One resolved volatile field: a stable refe./types.jse `get()` yields the
  * current immutable snapshot. Structurally `cosmokit`'s `Volatile<T>`; kept
  * local so this package need not depend on it.
  */

package/lib/engine.d.ts

@@ -108,8 +108,8 @@ export declare class Sub2apiSyncEngine {
     isRunning(): boolean;
     /**
      * Run one sync. At most one runs at a time — later callers queue behind
-     * the previous one (the settings-card button, the tool, and the timer all
-     * share this queue).
+     * the previous one (the settings-card button and the timer share this
+     * queue).
      */
     sync(config: Sub2apiSyncConfig, keyIds?: number[]): Promise<SyncReport>;
     private runSync;
@@ -125,5 +125,4 @@ export declare class Sub2apiSyncEngine {
      */
     private discoverModels;
     private readCurrentProviders;
-    private revisionOf;
 }

package/lib/enrich.d.ts

@@ -91,9 +91,9 @@ export declare function bundledIndex(): ModelMetaIndex;
 /**
  * Resolve the index for one sync run. With `enrich` on, a fresh fetch is
  * attempted and cached for 24h (failures degrade to the bundled snapshot and
- * are cached for the same TTL so a dead endpoint is not retried per sync);
- * with `enrich` off, only the bundled snapshot is used — deterministic and
- * offline.
+ * are negative-cached for 1h so a dead endpoint is not retried per sync but
+ * an outage self-heals within the hour); with `enrich` off, only the bundled
+ * snapshot is used — deterministic and offline.
  */
 export declare function loadModelIndex(options: {
     enrich: boolean;

package/lib/index.js

@@ -211,6 +211,26 @@ function parseGroupId(input) {
 	const id = Number(input);
 	return Number.isSafeInteger(id) && id > 0 ? id : undefined;
 }
+function isSettingsConflict(error) {
+	const shape = error;
+	return shape?.code === "SETTINGS_CONFLICT" || shape?.name === "SettingsConflictError";
+}
+async function mutateWithRetry(settings, ns, buildOps, options = {}) {
+	const maxAttempts = options.attempts ?? 3;
+	for (let attempt = 1;; attempt++) {
+		const ops = await buildOps();
+		const descriptor = settings.describe().find((candidate) => candidate.ns === ns);
+		if (descriptor === undefined) throw new Error(options.missingError ?? `sub2api-sync: 设置命名空间 "${ns}" 未注册`);
+		if (ops.length === 0) return;
+		try {
+			await settings.mutate(ns, ops, descriptor.revision);
+			return;
+		} catch (error) {
+			if (attempt < maxAttempts && isSettingsConflict(error)) continue;
+			throw error;
+		}
+	}
+}
 
 //#endregion
 //#region src/protocols.ts
@@ -283,6 +303,16 @@ const THINKING_LEVELS = [
 function buildProviderProfile(input) {
 	const compat = input.template?.compat;
 	const reasoning = input.template?.reasoningEfforts;
+	const override = input.retryPolicy ?? {};
+	const retryPolicy = {
+		...SUB2API_RETRY_POLICY,
+		...override,
+		retryableCodes: [...override.retryableCodes ?? SUB2API_RETRY_POLICY.retryableCodes],
+		backoff: {
+			...SUB2API_RETRY_POLICY.backoff,
+			...override.backoff
+		}
+	};
 	return {
 		displayName: input.displayName.length > 0 ? input.displayName : `Group ${input.groupId}`,
 		apiKeyEnv: input.apiKeyEnv,
@@ -298,14 +328,10 @@ function buildProviderProfile(input) {
 			...reasoning === false ? { reasoningEfforts: false } : reasoning !== undefined ? { reasoningEfforts: { ...reasoning } } : model.reasoningEfforts !== undefined ? { reasoningEfforts: { ...model.reasoningEfforts } } : {}
 		})),
 		...input.template?.reasoning !== undefined ? { reasoning: input.template.reasoning } : {},
-		defaultContextWindow: 128e3,
-		defaultMaxTokens: 8192,
+		defaultContextWindow: input.defaultContextWindow ?? 128e3,
+		defaultMaxTokens: input.defaultMaxTokens ?? 8192,
 		defaultInput: ["text"],
-		retryPolicy: {
-			...SUB2API_RETRY_POLICY,
-			retryableCodes: [...SUB2API_RETRY_POLICY.retryableCodes],
-			backoff: { ...SUB2API_RETRY_POLICY.backoff }
-		}
+		retryPolicy
 	};
 }
 
@@ -342,6 +368,18 @@ const Config = z.object({
 	keyExpiresInDays: z.number().step(1).volatile(),
 	deleteOrphanKeys: z.boolean().default(false).volatile(),
 	syncIntervalMs: z.number().step(1).volatile(),
+	retryPolicy: z.object({
+		mode: z.union([z.const("normal"), z.const("always")]),
+		maxRetries: z.number().step(1),
+		retryableCodes: z.array(z.string()),
+		backoff: z.object({
+			initialDelayMs: z.number(),
+			maxDelayMs: z.number(),
+			jitterRatio: z.number()
+		})
+	}).volatile(),
+	defaultContextWindow: z.number().step(1).volatile(),
+	defaultMaxTokens: z.number().step(1).volatile(),
 	allowRemoteActions: z.boolean().default(false).volatile()
 });
 /** Unwrap one live cell into its current snapshot; plain values pass through. */
@@ -359,6 +397,22 @@ function validateConfig(config) {
 	const template = config.providerNameTemplate;
 	if (template !== undefined && template.length > 0 && !template.includes("{keyName}") && !template.includes("{siteName}")) throw new Error("sub2api-sync: providerNameTemplate 必须包含 {keyName} 或 {siteName} 占位符");
 	for (const id of config.selectedKeys ?? []) if (!Number.isSafeInteger(id) || id <= 0) throw new Error(`sub2api-sync: selectedKeys 含非法 key id ${String(id)}`);
+	if (config.syncIntervalMs !== undefined && config.syncIntervalMs < 6e4) throw new Error("sub2api-sync: syncIntervalMs 定时同步间隔不能小于 60000ms（删除该字段即关闭定时同步）");
+	if (config.keyQuota !== undefined && config.keyQuota < 0) throw new Error("sub2api-sync: keyQuota 不能为负数");
+	if (config.keyExpiresInDays !== undefined && (!Number.isSafeInteger(config.keyExpiresInDays) || config.keyExpiresInDays < 1)) throw new Error("sub2api-sync: keyExpiresInDays 必须是 ≥1 的整数");
+	if (config.defaultContextWindow !== undefined && (!Number.isSafeInteger(config.defaultContextWindow) || config.defaultContextWindow <= 0)) throw new Error("sub2api-sync: defaultContextWindow 必须是正整数");
+	if (config.defaultMaxTokens !== undefined && (!Number.isSafeInteger(config.defaultMaxTokens) || config.defaultMaxTokens <= 0)) throw new Error("sub2api-sync: defaultMaxTokens 必须是正整数");
+	const retry = config.retryPolicy;
+	if (retry !== undefined) {
+		if (retry.mode !== undefined && retry.mode !== "normal" && retry.mode !== "always") throw new Error("sub2api-sync: retryPolicy.mode 必须是 normal 或 always");
+		if (retry.maxRetries !== undefined && (!Number.isSafeInteger(retry.maxRetries) || retry.maxRetries < 0)) throw new Error("sub2api-sync: retryPolicy.maxRetries 必须是非负整数");
+		const backoff = retry.backoff;
+		if (backoff !== undefined) {
+			if (backoff.initialDelayMs !== undefined && (!Number.isSafeInteger(backoff.initialDelayMs) || backoff.initialDelayMs < 0)) throw new Error("sub2api-sync: retryPolicy.backoff.initialDelayMs 必须是非负整数");
+			if (backoff.maxDelayMs !== undefined && (!Number.isSafeInteger(backoff.maxDelayMs) || backoff.maxDelayMs < 0)) throw new Error("sub2api-sync: retryPolicy.backoff.maxDelayMs 必须是非负整数");
+			if (backoff.jitterRatio !== undefined && (backoff.jitterRatio < 0 || backoff.jitterRatio > 1)) throw new Error("sub2api-sync: retryPolicy.backoff.jitterRatio 必须在 [0, 1] 之间");
+		}
+	}
 }
 
 //#endregion
@@ -433,7 +487,16 @@ function readModelList(payload) {
 //#region src/enrich.ts
 const SNAPSHOT_PATH = join(dirname(fileURLToPath(import.meta.url)), "../data/models-dev.snapshot.json");
 const SOURCE_URL = "https://models.dev/api.json";
+/** How long a successful catalog fetch is trusted. */
 const TTL = 864e5;
+/**
+* How long a FAILED fetch defers the next attempt. Much shorter than the
+* success TTL on purpose: a negative cache exists so an unreachable endpoint
+* is not hammered per sync, but a models.dev outage (or a local network
+* blip) should self-heal within the hour instead of freezing the catalog
+* metadata for a full day.
+*/
+const NEGATIVE_TTL = 36e5;
 const EFFORT_VOCABULARY = [
 	"none",
 	"minimal",
@@ -673,7 +736,7 @@ function bundledIndex() {
 }
 async function loadModelIndex(options) {
 	const now = (options.now ?? Date.now)();
-	if (networkCache !== undefined && now - networkCache.at < TTL) return networkCache.index;
+	if (networkCache !== undefined && now - networkCache.at < (networkCache.ok ? TTL : NEGATIVE_TTL)) return networkCache.index;
 	if (options.enrich) try {
 		const doFetch = options.fetchImpl ?? globalThis.fetch;
 		if (doFetch === undefined) throw new Error("no fetch available");
@@ -683,14 +746,16 @@ async function loadModelIndex(options) {
 		const index = parseCatalog(catalog);
 		networkCache = {
 			index,
-			at: now
+			at: now,
+			ok: true
 		};
 		return index;
 	} catch {}
 	const bundled = bundledIndex();
 	if (options.enrich) networkCache = {
 		index: bundled,
-		at: now
+		at: now,
+		ok: false
 	};
 	return bundled;
 }
@@ -721,10 +786,6 @@ var Sub2apiSyncError = class extends Error {
 		this.name = "Sub2apiSyncError";
 	}
 };
-function isSettingsConflict(error) {
-	const shape = error;
-	return shape?.code === "SETTINGS_CONFLICT" || shape?.name === "SettingsConflictError";
-}
 function messageOf(error) {
 	return error instanceof Error ? error.message : String(error);
 }
@@ -786,8 +847,8 @@ var Sub2apiSyncEngine = class {
 	}
 	/**
 	* Run one sync. At most one runs at a time — later callers queue behind
-	* the previous one (the settings-card button, the tool, and the timer all
-	* share this queue).
+	* the previous one (the settings-card button and the timer share this
+	* queue).
 	*/
 	sync(config, keyIds) {
 		const run = this.queue.then(() => this.runSync(config, keyIds), () => this.runSync(config, keyIds));
@@ -807,6 +868,7 @@ var Sub2apiSyncEngine = class {
 		if (!/^https?:\/\//i.test(instance)) throw new Sub2apiSyncError("sub2api-sync: baseURL 未配置或不是 http(s) 地址");
 		const entries = [];
 		const desired = new Map();
+		let keyWalkTruncated = false;
 		const { groups, keyRows } = await this.gateway.use(async (panel, token) => {
 			const groupList = await panel.listAvailableGroups(token);
 			const rows = [];
@@ -816,6 +878,7 @@ var Sub2apiSyncEngine = class {
 					pageSize: 100
 				});
 				rows.push(...result.items);
+				if (result.pages > 10) keyWalkTruncated = true;
 				if (page >= result.pages || result.items.length === 0) break;
 			}
 			return {
@@ -830,6 +893,7 @@ var Sub2apiSyncEngine = class {
 		}).catch(() => new Map());
 		const site = await this.siteName?.().catch(() => undefined);
 		const syncWarnings = [];
+		if (keyWalkTruncated) syncWarnings.push("面板 key 数量超过单次同步的读取上限（10 页 × 100 = 1000 把）——超出部分未参与同步，也不会被移除");
 		const effective = {
 			...config,
 			selectedKeys: selection ?? config.selectedKeys
@@ -875,7 +939,7 @@ var Sub2apiSyncEngine = class {
 		const removed = [];
 		let ops = [];
 		let routeActions = new Map();
-		for (;;) {
+		await mutateWithRetry(this.settings, PI_AI_NS, () => {
 			attempts++;
 			const now = this.readCurrentProviders();
 			const plan = planOps(now, desired);
@@ -883,15 +947,8 @@ var Sub2apiSyncEngine = class {
 			routeActions = plan.actions;
 			removed.length = 0;
 			for (const op of ops) if (op.op === "unset") removed.push(op.path[1]);
-			const revision = this.revisionOf(PI_AI_NS);
-			try {
-				if (ops.length > 0) await this.settings.mutate(PI_AI_NS, ops, revision);
-				break;
-			} catch (error) {
-				if (isSettingsConflict(error) && attempts < 3) continue;
-				throw error;
-			}
-		}
+			return ops;
+		});
 		for (const entry of entries) {
 			const action = routeActions.get(entry.route);
 			if (action !== undefined) entry.action = action;
@@ -922,7 +979,7 @@ var Sub2apiSyncEngine = class {
 				op: "unset",
 				path: ["routeKeyIds", route]
 			});
-			if (mapOps.length > 0) await this.settings.mutate(OWN_NS, mapOps, this.revisionOf(OWN_NS));
+			if (mapOps.length > 0) await mutateWithRetry(this.settings, OWN_NS, () => mapOps, { missingError: "sub2api-sync: 自身 settings 命名空间未注册" });
 		} catch {}
 		return {
 			entries,
@@ -1016,7 +1073,10 @@ var Sub2apiSyncEngine = class {
 				instance,
 				models: enriched,
 				apiKeyEnv: ref,
-				template
+				template,
+				retryPolicy: config.retryPolicy,
+				defaultContextWindow: config.defaultContextWindow,
+				defaultMaxTokens: config.defaultMaxTokens
 			}),
 			warnings
 		};
@@ -1048,11 +1108,6 @@ var Sub2apiSyncEngine = class {
 		if (typeof providers !== "object" || Array.isArray(providers)) throw new Sub2apiSyncError("llm-pi-ai.providers 形状异常（不是对象）");
 		return providers;
 	}
-	revisionOf(ns) {
-		const descriptor = this.settings.describe().find((candidate) => candidate.ns === ns);
-		if (descriptor === undefined) throw new Sub2apiSyncError(`设置命名空间 "${ns}" 未注册，无法取得 revision`);
-		return descriptor.revision;
-	}
 };
 /** Attach the enriched facts (display name, capacity, efforts) to one discovered model. */
 function enrichModel(model, index) {
@@ -1414,6 +1469,7 @@ var OAuthAttemptStore = class {
 		this.ttlMs = ttlMs;
 	}
 	create(input, now = Date.now()) {
+		for (const [id, attempt$1] of this.attempts) if (this.expired(attempt$1, now)) this.drop(attempt$1);
 		const attempt = {
 			id: randomBase64url(24),
 			state: randomBase64url(32),
@@ -1718,16 +1774,10 @@ var PanelClient = class {
 	}
 	/** Password login; classifies 2FA and captcha outcomes. */
 	async login(email, password) {
-		let payload;
-		try {
-			payload = await this.call(undefined, "POST", "/auth/login", {
-				email,
-				password
-			});
-		} catch (error) {
-			if (error instanceof PanelError) throw error;
-			throw error;
-		}
+		const payload = await this.call(undefined, "POST", "/auth/login", {
+			email,
+			password
+		});
 		const data = payload;
 		if (data !== null && typeof data === "object" && data.requires_2fa === true) {
 			const tempToken = data.temp_token;
@@ -2105,9 +2155,19 @@ function isPrivateAddress(address) {
 	if (lowered === "::1") return true;
 	return lowered.startsWith("fc") || lowered.startsWith("fd");
 }
+/** Request bodies here are tiny JSON documents; a larger stream is a broken
+* or hostile peer — refuse it before buffering (same posture as icon.ts's
+* MAX_BYTES). */
+const MAX_BODY_BYTES = 1e6;
 async function readJson(req) {
 	const chunks = [];
-	for await (const chunk of req) chunks.push(Buffer.isBuffer(chunk) ? chunk : Buffer.from(chunk));
+	let total = 0;
+	for await (const chunk of req) {
+		const buffer = Buffer.isBuffer(chunk) ? chunk : Buffer.from(chunk);
+		total += buffer.length;
+		if (total > MAX_BODY_BYTES) throw new Error(`request body 超过 ${MAX_BODY_BYTES} 字节上限`);
+		chunks.push(buffer);
+	}
 	const text = Buffer.concat(chunks).toString("utf8").trim();
 	if (text.length === 0) return {};
 	const value = JSON.parse(text);
@@ -2141,8 +2201,7 @@ function safeMessage(error) {
 	return error instanceof Error ? error.message : String(error);
 }
 function conflictStatus(error) {
-	const shape = error;
-	return shape?.code === "SETTINGS_CONFLICT" || shape?.name === "SettingsConflictError" ? 409 : undefined;
+	return isSettingsConflict(error) ? 409 : undefined;
 }
 function registerRoutes(ctx, deps) {
 	ctx.inject(["webServer"], (webCtx) => {
@@ -2519,23 +2578,7 @@ function apply(ctx, config) {
 	judge();
 	/** Conflict-retried write into the llm-pi-ai section (purge path mirrors
 	* the engine's conflict policy without touching its queue). */
-	const mutatePiAi = async (ops) => {
-		let attempts = 0;
-		for (;;) {
-			attempts++;
-			const revision = ctx.settings.describe().find((descriptor) => descriptor.ns === PI_AI_NS)?.revision;
-			if (revision === undefined) throw new Error("sub2api-sync: llm-pi-ai 设置条目未注册");
-			try {
-				await ctx.settings.mutate(PI_AI_NS, ops, revision);
-				return;
-			} catch (error) {
-				const shape = error;
-				const conflict = shape?.code === "SETTINGS_CONFLICT" || shape?.name === "SettingsConflictError";
-				if (conflict && attempts < 3) continue;
-				throw error;
-			}
-		}
-	};
+	const mutatePiAi = (ops) => mutateWithRetry(ctx.settings, PI_AI_NS, () => ops, { missingError: "sub2api-sync: llm-pi-ai 设置条目未注册" });
 	const credentials = {
 		resolve: (ref) => ctx.credentials.resolve(credentialRef(ref)),
 		set: (ref, value) => ctx.credentials.set(credentialRef(ref), value),
@@ -2581,25 +2624,9 @@ function apply(ctx, config) {
 		gateway,
 		siteName: () => instanceProbe.siteName(instance())
 	});
-	const ownRevision = () => ctx.settings.describe().find((descriptor) => descriptor.ns === OWN_NS)?.revision;
+	let pendingTypedPassword;
 	/** Conflict-retried write into this plugin's own section (best effort). */
-	const mutateOwn = async (ops) => {
-		let attempts = 0;
-		for (;;) {
-			attempts++;
-			const revision = ownRevision();
-			if (revision === undefined) throw new Error("sub2api-sync: 自身 settings 命名空间未注册");
-			try {
-				await ctx.settings.mutate(OWN_NS, ops, revision);
-				return;
-			} catch (error) {
-				const shape = error;
-				const conflict = shape?.code === "SETTINGS_CONFLICT" || shape?.name === "SettingsConflictError";
-				if (conflict && attempts < 3) continue;
-				throw error;
-			}
-		}
-	};
+	const mutateOwn = (ops) => mutateWithRetry(ctx.settings, OWN_NS, () => ops, { missingError: "sub2api-sync: 自身 settings 命名空间未注册" });
 	const instance = () => source().baseURL?.trim() ?? "";
 	const instanceProbe = createInstanceProbe();
 	const oauthAttempts = new OAuthAttemptStore();
@@ -2607,27 +2634,37 @@ function apply(ctx, config) {
 		instance,
 		authState: () => gateway.authState(source().email),
 		login: async (email, password) => {
-			let pwd = password;
-			if (pwd === undefined || pwd.length === 0) pwd = (await credentials.resolve(panelPasswordRef(instance())))?.value;
+			const typed = password !== undefined && password.length > 0 ? password : undefined;
+			let pwd = typed ?? (await credentials.resolve(panelPasswordRef(instance())))?.value;
 			if (pwd === undefined || pwd.length === 0) throw new Error("请输入面板密码（首次登录后密码会保存到凭据存储，之后可免输入）");
-			if (password !== undefined && password.length > 0) await credentials.set(panelPasswordRef(instance()), password);
 			await mutateOwn([{
 				op: "set",
 				path: ["email"],
 				value: email
 			}]).catch(() => undefined);
 			const outcome = await gateway.login(email, pwd);
-			if (outcome.kind === "2fa") return {
-				ok: true,
-				kind: "2fa",
-				requires2FA: true
-			};
+			if (outcome.kind === "2fa") {
+				pendingTypedPassword = typed;
+				return {
+					ok: true,
+					kind: "2fa",
+					requires2FA: true
+				};
+			}
+			if (outcome.kind === "ok" && typed !== undefined) await credentials.set(panelPasswordRef(instance()), typed).catch(() => undefined);
+			pendingTypedPassword = undefined;
 			return {
 				ok: true,
 				kind: "ok"
 			};
 		},
-		login2FA: (code) => gateway.login2FA(code),
+		login2FA: async (code) => {
+			await gateway.login2FA(code);
+			if (pendingTypedPassword !== undefined) {
+				await credentials.set(panelPasswordRef(instance()), pendingTypedPassword).catch(() => undefined);
+				pendingTypedPassword = undefined;
+			}
+		},
 		logout: async () => {
 			await gateway.logout();
 			await purgeSyncState().catch(() => undefined);
@@ -2641,8 +2678,7 @@ function apply(ctx, config) {
 				status: group.status,
 				rateMultiplier: group.rateMultiplier,
 				isExclusive: group.isExclusive,
-				claudeCodeOnly: group.claudeCodeOnly,
-				enabled: false
+				claudeCodeOnly: group.claudeCodeOnly
 			}));
 		},
 		sync: async (keyIds) => {

package/lib/protocols.d.ts

@@ -114,6 +114,12 @@ export interface ProfileInput {
     models: readonly ProfileModelInput[];
     apiKeyEnv: string;
     template?: ModelTemplate;
+    /** Overrides over {@link SUB2API_RETRY_POLICY}; absent keys inherit it. */
+    retryPolicy?: Partial<PiAiRetryPolicy>;
+    /** Route-level defaults for models the enrichment could not match
+     * (Config `defaultContextWindow`/`defaultMaxTokens`). */
+    defaultContextWindow?: number;
+    defaultMaxTokens?: number;
 }
 /** Build one hand-declared llm-pi-ai provider profile for a group. */
 export declare function buildProviderProfile(input: ProfileInput): PiAiProviderProfile;

package/lib/routes.d.ts

@@ -103,10 +103,6 @@ export interface GroupsView {
     rateMultiplier?: number;
     isExclusive?: boolean;
     claudeCodeOnly?: boolean;
-    /** Whether the group is checked for sync (`enabledGroups`). */
-    enabled: boolean;
-    /** The stored key source (`groups[gid].keyId`), when one is pinned. */
-    keyId?: number;
 }
 export interface GroupsResponse {
     ok: true;
@@ -190,12 +186,9 @@ export interface RouteDeps {
     login2FA(code: string): Promise<void>;
     /** Drop panel tokens. */
     logout(): Promise<void>;
-    /** Live panel groups annotated with the card's checked/keyId state. */
+    /** Live panel groups as the panel reports them (the card's checked state
+     * rides the config's `selectedKeys`, not this response). */
     listGroups(): Promise<GroupsView[]>;
-    /** One group's relay keys, metadata only (no plaintext). */
-    /** Store or clear one group's pasted relay key (empty/absent clears). */
-    /** Model preview for one group: pasted override wins over the stored key. */
-    /** Best-effort subscription group-name probe for one group's key. */
     /** Run one sync; the implementation serializes and records the report. */
     sync(keyIds?: number[]): Promise<SyncReport>;
     lastReport(): SyncReport | undefined;

package/lib/types.d.ts

@@ -128,3 +128,24 @@ export interface CredentialsLike {
     set(ref: string, value: string): Promise<void>;
     unset(ref: string): Promise<void>;
 }
+/**
+ * The settings service's concurrent-writer error shape (`code` or `name`).
+ * One predicate for every conflict surface: the shared mutate helper below,
+ * the engine's plan loop, and the route layer's 409 projection.
+ */
+export declare function isSettingsConflict(error: unknown): boolean;
+/**
+ * Conflict-retried write into one settings namespace: build the ops, read
+ * the namespace's live revision, mutate, and on a concurrent-writer conflict
+ * rebuild + retry (bounded — 3 attempts total, matching the engine's policy).
+ *
+ * `buildOps` runs per attempt so a retry can recompute the plan against the
+ * just-re-read state; it may close over outer holders to surface the final
+ * ops/actions (the engine does exactly that for its sync report). An empty
+ * ops list skips the wire round trip entirely — but the namespace must still
+ * exist (the same loud failure the engine's revision read used to produce).
+ */
+export declare function mutateWithRetry(settings: SettingsLike, ns: string, buildOps: () => SettingsPathOp[] | Promise<SettingsPathOp[]>, options?: {
+    missingError?: string;
+    attempts?: number;
+}): Promise<void>;

package/locale/en.json

@@ -1,6 +1,6 @@
 {
   "meta": {
     "title": "Sub2API Sync",
-    "description": "Sync one sub2api instance's groups, keys, and models into dsh-llm-pi-ai provider routes: panel-driven login (PAT / password / OAuth) first, one group one provider."
+    "description": "Sync one sub2api instance's groups, keys, and models into dsh-llm-pi-ai provider routes: panel-driven login (password / OAuth), one relay key one provider."
   }
 }

package/locale/zh.json

@@ -1,6 +1,6 @@
 {
   "meta": {
     "title": "Sub2API 同步",
-    "description": "把一个 sub2api 实例的分组、key 与模型同步为 dsh-llm-pi-ai 供应商路由：先连接面板（PAT / 密码 / OAuth），一个分组一个供应商。"
+    "description": "把一个 sub2api 实例的分组、key 与模型同步为 dsh-llm-pi-ai 供应商路由：面板登录（密码 / OAuth），一把 key 一个供应商。"
   }
 }

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "dsh-sub2api-sync",
-  "description": "Sync one sub2api instance's groups, keys, and models into dsh-llm-pi-ai provider routes: panel-driven login (password / OAuth) first, one group one provider.",
-  "version": "0.1.0",
+  "description": "Sync one sub2api instance's groups, keys, and models into dsh-llm-pi-ai provider routes: panel-driven login (password / OAuth), one relay key one provider.",
+  "version": "0.2.1",
   "license": "MIT",
   "author": "Shuai-S",
   "homepage": "https://github.com/Shuai-S/dsh-sub2api-sync#readme",