@xopcai/xopc 0.0.208 → 0.0.211

package/dist/src/providers/provider-auth-service.d.ts

@@ -15,6 +15,7 @@ export declare class ProviderAuthService {
     private runtime;
     constructor(options?: ProviderAuthServiceOptions);
     resolveApiKey(providerId: string, signal?: AbortSignal): Promise<string | null>;
+    invalidate(): void;
     private getRuntime;
 }
 export declare function getProviderAuthService(): ProviderAuthService;

package/dist/src/providers/provider-auth-service.js

@@ -55,6 +55,9 @@ var init_provider_auth_service = __esmMin((() => {
 			}
 			return await this.resolver.resolveApiKey(providerId);
 		}
+		invalidate() {
+			this.runtime = void 0;
+		}
 		getRuntime() {
 			this.runtime ??= this.runtimeFactory(this.credentials).catch((error) => {
 				this.runtime = void 0;

package/dist/src/providers/provider-disconnect.d.ts

@@ -0,0 +1,11 @@
+import { CredentialResolver } from '../auth/credentials.js';
+interface ProviderDisconnectOptions {
+    resolver?: Pick<CredentialResolver, 'deleteProviderCredential'>;
+    invalidateAuth?: () => void;
+    clearCloudCatalog?: () => Promise<void>;
+    refreshModels?: () => void;
+    evictRunners?: () => void;
+    withLock?: <T>(providerId: string, operation: () => Promise<T>) => Promise<T>;
+}
+export declare function disconnectProvider(providerId: string, options?: ProviderDisconnectOptions): Promise<void>;
+export {};

package/dist/src/providers/provider-disconnect.js

@@ -0,0 +1,33 @@
+import { createLogger } from "../utils/logger/index.js";
+import { init_logger } from "../utils/logger.js";
+import { getModelRegistry, init_model_registry } from "./model-registry.js";
+import { init_oauth_provider_lock, withOAuthProviderLock } from "../auth/oauth-provider-lock.js";
+import { CredentialResolver, init_credentials } from "../auth/credentials.js";
+import { getProviderAuthService, init_provider_auth_service } from "./provider-auth-service.js";
+import { evictAllEmbeddedSessionRunners } from "../agent/embedded/session-runner.js";
+import { getXopcCloudCatalogCoordinator } from "./xopc-cloud-catalog-coordinator.js";
+//#region src/providers/provider-disconnect.ts
+init_credentials();
+init_oauth_provider_lock();
+init_logger();
+init_model_registry();
+init_provider_auth_service();
+const log = createLogger("ProviderDisconnect");
+async function disconnectProvider(providerId, options = {}) {
+	const provider = providerId.trim().toLowerCase();
+	if (!provider) throw new Error("Provider id is required");
+	const resolver = options.resolver ?? new CredentialResolver();
+	await (options.withLock ?? ((id, operation) => withOAuthProviderLock(id, operation)))(provider, async () => {
+		await resolver.deleteProviderCredential(provider);
+		(options.invalidateAuth ?? (() => getProviderAuthService().invalidate()))();
+		if (provider === "xopc-cloud") await (options.clearCloudCatalog ?? (() => getXopcCloudCatalogCoordinator().clear("revoke")))();
+		else (options.refreshModels ?? (() => getModelRegistry().refresh()))();
+		(options.evictRunners ?? (() => evictAllEmbeddedSessionRunners("provider_disconnected")))();
+	});
+	log.info({
+		provider,
+		phase: "provider_revoked"
+	}, `Disconnected provider: ${provider}`);
+}
+//#endregion
+export { disconnectProvider };

package/dist/src/providers/xopc-cloud-catalog-coordinator.d.ts

@@ -0,0 +1,56 @@
+import { ModelCatalogPersistence } from './model-catalog-persistence.js';
+import { type CatalogSourceOrigin, type ModelCatalogStore } from './model-catalog-store.js';
+import { XopcCloudModelSource } from './xopc-cloud-model-source.js';
+export type CatalogEnsureReason = 'startup' | 'oauth' | 'agent-run' | 'manual' | 'recovery';
+export interface EnsureCatalogOptions {
+    reason: CatalogEnsureReason;
+    network: 'never' | 'if-empty' | 'always';
+    timeoutMs?: number;
+}
+export interface CatalogReadiness {
+    state: 'not-authorized' | 'ready' | 'stale' | 'refreshing' | 'unavailable';
+    source: CatalogSourceOrigin | 'none';
+    fetchedAt?: number;
+    catalogVersion?: string | null;
+    modelCount: number;
+    error?: {
+        code: string;
+        message: string;
+        retryable: boolean;
+    };
+}
+interface CatalogCoordinatorOptions {
+    source?: Pick<XopcCloudModelSource, 'fetch'>;
+    store?: ModelCatalogStore;
+    persistence?: Pick<ModelCatalogPersistence, 'loadSync' | 'save' | 'clear'>;
+    staleAfterMs?: number;
+    refreshModels?: () => void;
+    reloadImageProviders?: () => void;
+    withLock?: <T>(operation: () => Promise<T>) => Promise<T>;
+    onPermanentAuthFailure?: () => Promise<void>;
+}
+export declare class XopcCloudCatalogCoordinator {
+    private readonly source;
+    private readonly store;
+    private readonly persistence;
+    private readonly staleAfterMs;
+    private readonly refreshModels;
+    private readonly reloadImageProviders;
+    private readonly withLock;
+    private readonly onPermanentAuthFailure;
+    private refreshPromise;
+    private generation;
+    private lastError;
+    private notAuthorized;
+    constructor(options?: CatalogCoordinatorOptions);
+    hydrate(): Promise<CatalogReadiness>;
+    ensure(options: EnsureCatalogOptions): Promise<CatalogReadiness>;
+    refresh(reason: CatalogEnsureReason, timeoutMs?: number): Promise<CatalogReadiness>;
+    clear(reason: 'revoke' | 'invalid-grant'): Promise<void>;
+    snapshot(): CatalogReadiness;
+    private buildSnapshot;
+    private runRefresh;
+}
+export declare function getXopcCloudCatalogCoordinator(): XopcCloudCatalogCoordinator;
+export declare function resetXopcCloudCatalogCoordinator(): void;
+export {};

package/dist/src/providers/xopc-cloud-catalog-coordinator.js

@@ -0,0 +1,182 @@
+import { createLogger } from "../utils/logger/index.js";
+import { init_logger } from "../utils/logger.js";
+import { ModelCatalogPersistence, init_model_catalog_persistence } from "./model-catalog-persistence.js";
+import { getModelCatalogStore, init_model_catalog_store } from "./model-catalog-store.js";
+import { getModelRegistry, init_model_registry } from "./model-registry.js";
+import { init_oauth_provider_lock, withOAuthProviderLock } from "../auth/oauth-provider-lock.js";
+import { reloadImageGenerationProviders } from "../agent/image/generation/provider-registry.js";
+import { XopcCloudModelSource } from "./xopc-cloud-model-source.js";
+//#region src/providers/xopc-cloud-catalog-coordinator.ts
+init_oauth_provider_lock();
+init_logger();
+init_model_catalog_persistence();
+init_model_catalog_store();
+init_model_registry();
+const log = createLogger("XopcCloudCatalog");
+const DEFAULT_STALE_AFTER_MS = 1440 * 6e4;
+var XopcCloudCatalogCoordinator = class {
+	source;
+	store;
+	persistence;
+	staleAfterMs;
+	refreshModels;
+	reloadImageProviders;
+	withLock;
+	onPermanentAuthFailure;
+	refreshPromise = null;
+	generation = 0;
+	lastError;
+	notAuthorized = false;
+	constructor(options = {}) {
+		this.source = options.source ?? new XopcCloudModelSource();
+		this.store = options.store ?? getModelCatalogStore();
+		this.persistence = options.persistence ?? new ModelCatalogPersistence();
+		this.staleAfterMs = options.staleAfterMs ?? DEFAULT_STALE_AFTER_MS;
+		this.refreshModels = options.refreshModels ?? (() => getModelRegistry().refresh());
+		this.reloadImageProviders = options.reloadImageProviders ?? reloadImageGenerationProviders;
+		this.withLock = options.withLock ?? ((operation) => withOAuthProviderLock("xopc-cloud", operation));
+		this.onPermanentAuthFailure = options.onPermanentAuthFailure ?? (async () => {
+			const { disconnectProvider } = await import("./provider-disconnect.js");
+			await disconnectProvider("xopc-cloud");
+		});
+	}
+	async hydrate() {
+		if (!this.store.getSource("xopc-cloud")) {
+			const source = this.persistence.loadSync();
+			if (source) this.store.saveSource("xopc-cloud", source, "disk");
+		}
+		return this.snapshot();
+	}
+	async ensure(options) {
+		await this.hydrate();
+		if (options.network === "never") return this.snapshot();
+		if (options.network === "if-empty" && this.store.getSource("xopc-cloud")) return this.snapshot();
+		return this.refresh(options.reason, options.timeoutMs);
+	}
+	refresh(reason, timeoutMs = 3e4) {
+		if (this.refreshPromise) return this.refreshPromise;
+		const generation = this.generation;
+		this.refreshPromise = this.runRefresh(reason, generation, timeoutMs).finally(() => {
+			this.refreshPromise = null;
+		});
+		return this.refreshPromise;
+	}
+	async clear(reason) {
+		this.generation += 1;
+		await this.withLock(async () => {
+			this.store.removeSource("xopc-cloud");
+			await this.persistence.clear();
+			this.lastError = void 0;
+			this.notAuthorized = reason === "revoke" || reason === "invalid-grant";
+			this.refreshModels();
+			this.reloadImageProviders();
+			log.info({
+				provider: "xopc-cloud",
+				reason,
+				phase: "catalog_commit"
+			}, "Cleared XOPC Cloud model catalog");
+		});
+	}
+	snapshot() {
+		return this.buildSnapshot(this.refreshPromise !== null);
+	}
+	buildSnapshot(refreshing) {
+		const source = this.store.getSource("xopc-cloud");
+		if (!source) return {
+			state: this.notAuthorized ? "not-authorized" : "unavailable",
+			source: "none",
+			modelCount: 0,
+			...this.lastError ? { error: this.lastError } : {}
+		};
+		const stale = Date.now() - source.lastSuccessAt > this.staleAfterMs;
+		return {
+			state: refreshing ? "refreshing" : stale ? "stale" : "ready",
+			source: this.store.getSourceOrigin("xopc-cloud") ?? "memory",
+			fetchedAt: source.lastSuccessAt,
+			catalogVersion: source.etag,
+			modelCount: source.models.filter((model) => model.availability === "available").length,
+			...this.lastError ? { error: this.lastError } : {}
+		};
+	}
+	async runRefresh(reason, generation, timeoutMs) {
+		const startedAt = Date.now();
+		try {
+			const readiness = await this.withLock(async () => {
+				const result = await this.source.fetch(AbortSignal.timeout(timeoutMs));
+				if (result.status === "skipped") {
+					await this.clear("revoke");
+					return this.buildSnapshot(false);
+				}
+				if (generation !== this.generation) return this.buildSnapshot(false);
+				const previous = this.store.getSource("xopc-cloud");
+				const previousOrigin = this.store.getSourceOrigin("xopc-cloud");
+				this.store.replaceSourceModels("xopc-cloud", result.source, result.models, "network");
+				const committed = this.store.getSource("xopc-cloud");
+				if (!committed) throw new Error("XOPC Cloud catalog commit failed");
+				try {
+					await this.persistence.save(committed);
+				} catch (error) {
+					if (previous) this.store.saveSource("xopc-cloud", previous, previousOrigin ?? "memory");
+					else this.store.removeSource("xopc-cloud");
+					throw error;
+				}
+				if (generation !== this.generation) {
+					this.store.removeSource("xopc-cloud");
+					await this.persistence.clear();
+					return this.buildSnapshot(false);
+				}
+				this.notAuthorized = false;
+				this.lastError = void 0;
+				this.refreshModels();
+				this.reloadImageProviders();
+				return this.buildSnapshot(false);
+			});
+			log.info({
+				provider: "xopc-cloud",
+				reason,
+				phase: "catalog_refresh",
+				durationMs: Date.now() - startedAt
+			}, `XOPC Cloud model catalog refresh completed with ${readiness.modelCount} models`);
+			return readiness;
+		} catch (err) {
+			const message = err instanceof Error ? err.message : String(err);
+			const modelError = asXopcCloudModelError(err);
+			if (modelError?.status === 401 && (modelError.code === "invalid_grant" || modelError.code === "invalid_token")) {
+				await this.onPermanentAuthFailure();
+				this.notAuthorized = true;
+			}
+			this.lastError = {
+				code: modelError ? modelError.code ?? `http_${modelError.status}` : "refresh_failed",
+				message,
+				retryable: !modelError || modelError.status === 429 || modelError.status >= 500
+			};
+			log.warn({
+				err,
+				provider: "xopc-cloud",
+				reason,
+				phase: "catalog_refresh",
+				durationMs: Date.now() - startedAt
+			}, `XOPC Cloud model catalog refresh failed: ${message}`);
+			return this.buildSnapshot(false);
+		}
+	}
+};
+function asXopcCloudModelError(error) {
+	if (!(error instanceof Error) || error.name !== "XopcCloudModelError") return void 0;
+	const candidate = error;
+	if (typeof candidate.status !== "number") return void 0;
+	return {
+		status: candidate.status,
+		...typeof candidate.code === "string" ? { code: candidate.code } : {}
+	};
+}
+let globalCoordinator;
+function getXopcCloudCatalogCoordinator() {
+	globalCoordinator ??= new XopcCloudCatalogCoordinator();
+	return globalCoordinator;
+}
+function resetXopcCloudCatalogCoordinator() {
+	globalCoordinator = void 0;
+}
+//#endregion
+export { XopcCloudCatalogCoordinator, getXopcCloudCatalogCoordinator, resetXopcCloudCatalogCoordinator };

package/dist/src/providers/xopc-cloud-model-source.d.ts

@@ -1,12 +1,12 @@
-import { type ModelCatalogStore } from './model-catalog-store.js';
+import type { AvailableCatalogModel, CatalogSource } from './model-catalog-store.js';
 import { type ProviderAuthService } from './provider-auth-service.js';
-export type XopcCloudModelRefreshResult = {
+export type XopcCloudCatalogFetchResult = {
     status: 'skipped';
     reason: 'not_configured';
 } | {
-    status: 'updated';
-    modelCount: number;
-    models: string[];
+    status: 'fetched';
+    source: Omit<CatalogSource, 'models'>;
+    models: AvailableCatalogModel[];
 };
 export declare class XopcCloudModelError extends Error {
     readonly status: number;
@@ -17,14 +17,10 @@ export declare class XopcCloudModelSource {
     private readonly fetchImpl;
     private readonly routerUrl;
     private readonly credentials;
-    private readonly catalogStore;
-    private readonly refreshModels;
     constructor(options?: {
         fetchImpl?: typeof fetch;
         routerUrl?: string;
         credentials?: Pick<ProviderAuthService, 'resolveApiKey'>;
-        catalogStore?: ModelCatalogStore;
-        refreshModels?: () => void;
     });
-    refresh(): Promise<XopcCloudModelRefreshResult>;
+    fetch(signal?: AbortSignal): Promise<XopcCloudCatalogFetchResult>;
 }

package/dist/src/providers/xopc-cloud-model-source.js

@@ -1,11 +1,6 @@
-import { getModelCatalogStore, init_model_catalog_store } from "./model-catalog-store.js";
-import { getModelRegistry, init_model_registry } from "./model-registry.js";
 import { init_xopc_cloud_config, resolveXopcModelRouterUrl } from "./xopc-cloud-config.js";
 import { getProviderAuthService, init_provider_auth_service } from "./provider-auth-service.js";
-import { reloadImageGenerationProviders } from "../agent/image/generation/provider-registry.js";
 //#region src/providers/xopc-cloud-model-source.ts
-init_model_catalog_store();
-init_model_registry();
 init_provider_auth_service();
 init_xopc_cloud_config();
 var XopcCloudModelError = class extends Error {
@@ -20,17 +15,14 @@ var XopcCloudModelSource = class {
 	fetchImpl;
 	routerUrl;
 	credentials;
-	catalogStore;
-	refreshModels;
 	constructor(options = {}) {
 		this.fetchImpl = options.fetchImpl ?? fetch;
 		this.routerUrl = resolveXopcModelRouterUrl(options.routerUrl);
 		this.credentials = options.credentials ?? getProviderAuthService();
-		this.catalogStore = options.catalogStore ?? getModelCatalogStore();
-		this.refreshModels = options.refreshModels ?? (() => getModelRegistry().refresh());
 	}
-	async refresh() {
-		const accessToken = await this.credentials.resolveApiKey("xopc-cloud");
+	async fetch(signal) {
+		const requestSignal = signal ? AbortSignal.any([signal, AbortSignal.timeout(3e4)]) : AbortSignal.timeout(3e4);
+		const accessToken = await this.credentials.resolveApiKey("xopc-cloud", requestSignal);
 		if (!accessToken) return {
 			status: "skipped",
 			reason: "not_configured"
@@ -40,7 +32,7 @@ var XopcCloudModelSource = class {
 				authorization: `Bearer ${accessToken}`,
 				accept: "application/json"
 			},
-			signal: AbortSignal.timeout(3e4)
+			signal: requestSignal
 		});
 		const body = await response.json().catch(() => null);
 		if (!response.ok) throw new XopcCloudModelError(typeof body?.error?.message === "string" ? body.error.message : `XOPC model discovery failed (${response.status})`, response.status, typeof body?.error?.code === "string" ? body.error.code : void 0);
@@ -58,7 +50,7 @@ var XopcCloudModelSource = class {
 			const generation = parseImageGenerationCapabilities(model.xopc?.capabilities?.imageGeneration);
 			const stt = kind === "stt" ? parseSttCapabilities(model.xopc?.capabilities) : void 0;
 			const tts = kind === "tts" ? parseTtsCapabilities(model.xopc?.capabilities, model.xopc?.defaultVoice) : void 0;
-			return [model.id, {
+			const catalogModel = {
 				id: model.id,
 				name: model.id,
 				kind,
@@ -68,28 +60,58 @@ var XopcCloudModelSource = class {
 				reasoning: model.xopc?.capabilities?.reasoning === true,
 				contextWindow: 128e3,
 				maxOutputTokens: typeof maxOutputTokens === "number" && Number.isSafeInteger(maxOutputTokens) ? maxOutputTokens : null,
+				...model.xopc?.stability === "stable" || model.xopc?.stability === "preview" || model.xopc?.stability === "deprecated" ? { stability: model.xopc.stability } : {},
+				...typeof model.xopc?.priority === "number" && Number.isFinite(model.xopc.priority) ? { priority: model.xopc.priority } : {},
+				...typeof model.xopc?.tier === "string" && model.xopc.tier ? { tier: model.xopc.tier } : {},
+				...typeof model.xopc?.bestEffort === "boolean" ? { bestEffort: model.xopc.bestEffort } : {},
 				...generation ? { imageGeneration: generation } : {},
 				...stt ? { stt } : {},
 				...tts ? { tts } : {}
-			}];
+			};
+			return [model.id, catalogModel];
 		})).values()];
-		this.catalogStore.replaceSourceModels("xopc-cloud", {
-			providerId: "xopc-cloud",
-			baseUrl: this.routerUrl,
-			api: "openai-completions",
-			etag: response.headers.get("x-xopc-model-catalog-version"),
-			recommendedModel: models[0]?.id ?? null,
-			lastSuccessAt: Date.now()
-		}, models);
-		this.refreshModels();
-		reloadImageGenerationProviders();
+		const recommended = parseRecommendations(body.xopc?.defaults, models);
 		return {
-			status: "updated",
-			modelCount: models.length,
-			models: models.map((model) => model.id)
+			status: "fetched",
+			source: {
+				providerId: "xopc-cloud",
+				baseUrl: this.routerUrl,
+				api: "openai-completions",
+				etag: response.headers.get("x-xopc-model-catalog-version"),
+				recommendedModel: models[0]?.id ?? null,
+				...Object.keys(recommended).length > 0 ? { recommended } : {},
+				lastSuccessAt: Date.now()
+			},
+			models
 		};
 	}
 };
+function parseRecommendations(value, models) {
+	if (!value || typeof value !== "object" || Array.isArray(value)) return {};
+	const raw = value;
+	const capabilities = [
+		"vision",
+		"image-generation",
+		"stt",
+		"tts"
+	];
+	const recommended = {};
+	for (const capability of capabilities) {
+		const modelId = raw[capability];
+		if (typeof modelId !== "string") continue;
+		const model = models.find((entry) => entry.id === modelId);
+		if (model && modelMatchesRecommendation(model, capability)) recommended[capability] = modelId;
+	}
+	return recommended;
+}
+function modelMatchesRecommendation(model, capability) {
+	switch (capability) {
+		case "vision": return model.kind === "language" && model.input.includes("image");
+		case "image-generation": return model.kind === "image" && model.operations.includes("images.generate");
+		case "stt": return model.kind === "stt" && model.operations.includes("audio.transcription");
+		case "tts": return model.kind === "tts" && model.operations.includes("audio.speech");
+	}
+}
 function parseSttCapabilities(value) {
 	if (!value || typeof value !== "object" || Array.isArray(value)) return void 0;
 	const raw = value;

package/dist/src/retrieval/audit.d.ts

@@ -0,0 +1 @@
+export declare function retrievalQueryAuditValue(query: string): string;

package/dist/src/retrieval/audit.js

@@ -0,0 +1,8 @@
+import { createHash } from "node:crypto";
+//#region src/retrieval/audit.ts
+function retrievalQueryAuditValue(query) {
+	const normalized = query.normalize("NFKC").trim();
+	return `sha256:${createHash("sha256").update(normalized).digest("hex").slice(0, 24)};length=${[...normalized].length}`;
+}
+//#endregion
+export { retrievalQueryAuditValue };

package/dist/src/retrieval/candidateFusion.d.ts

@@ -0,0 +1,5 @@
+export interface RankedCandidateChannel {
+    weight: number;
+    ids: string[];
+}
+export declare function fuseRankedCandidates(channels: RankedCandidateChannel[], rankConstant?: number): Map<string, number>;

package/dist/src/retrieval/candidateFusion.js

@@ -0,0 +1,20 @@
+//#region src/retrieval/candidateFusion.ts
+function fuseRankedCandidates(channels, rankConstant = 60) {
+	const activeChannels = channels.filter((channel) => channel.weight > 0 && channel.ids.length > 0);
+	if (!activeChannels.length) return /* @__PURE__ */ new Map();
+	const maximum = activeChannels.reduce((sum, channel) => sum + channel.weight / (rankConstant + 1), 0);
+	const scores = /* @__PURE__ */ new Map();
+	for (const channel of activeChannels) {
+		const seen = /* @__PURE__ */ new Set();
+		channel.ids.forEach((id, index) => {
+			if (!id || seen.has(id)) return;
+			seen.add(id);
+			const contribution = channel.weight / (rankConstant + index + 1);
+			scores.set(id, (scores.get(id) ?? 0) + contribution);
+		});
+	}
+	for (const [id, score] of scores) scores.set(id, score / maximum);
+	return scores;
+}
+//#endregion
+export { fuseRankedCandidates };

package/dist/src/retrieval/queryProfile.d.ts

@@ -0,0 +1,16 @@
+export type RetrievalTimeHint = 'current' | 'recent' | 'historical' | 'future';
+export interface RetrievalScope {
+    sessionKey?: string;
+    workspaceId?: string;
+    projectId?: string;
+}
+export interface RetrievalQueryProfile {
+    normalized: string;
+    terms: string[];
+    cjkBigrams: string[];
+    identifiers: string[];
+    intentKinds: string[];
+    timeHints: RetrievalTimeHint[];
+    scope: RetrievalScope;
+}
+export declare function buildRetrievalQueryProfile(query: string, scope?: RetrievalScope): RetrievalQueryProfile;

package/dist/src/retrieval/queryProfile.js

@@ -0,0 +1,66 @@
+import { extractCjkBigrams, extractLexicalTerms, extractRetrievalIdentifiers, normalizeRetrievalText } from "./textFeatures.js";
+//#region src/retrieval/queryProfile.ts
+const INTENT_RULES = [
+	{
+		kinds: ["boundary"],
+		pattern: /\b(?:avoid|never|permission|confirm|approval)\b|不要|禁止|避免|确认|授权|边界/i
+	},
+	{
+		kinds: ["preference", "tool_preference"],
+		pattern: /\b(?:prefer|preference|format|language|style)\b|喜欢|偏好|格式|语言|风格|简洁|详细/i
+	},
+	{
+		kinds: [
+			"project_context",
+			"workspace_fact",
+			"task_lesson"
+		],
+		pattern: /\b(?:project|repository|repo|workspace|codebase|deploy|release)\b|项目|仓库|代码库|工作区|发布|部署/i
+	},
+	{
+		kinds: ["long_term_goal", "commitment"],
+		pattern: /\b(?:goal|plan|deadline|commitment)\b|目标|计划|截止|承诺/i
+	},
+	{
+		kinds: ["routine"],
+		pattern: /\b(?:routine|usually|weekly|daily|every time)\b|习惯|通常|每周|每天|每次/i
+	},
+	{
+		kinds: ["relationship"],
+		pattern: /\b(?:person|people|colleague|collaborator|relationship)\b|同事|合作伙伴|关系|联系人/i
+	}
+];
+const TIME_RULES = [
+	{
+		hint: "current",
+		pattern: /\b(?:now|current|today)\b|现在|当前|今天/i
+	},
+	{
+		hint: "recent",
+		pattern: /\b(?:recent|recently|latest)\b|最近|近期|最新/i
+	},
+	{
+		hint: "historical",
+		pattern: /\b(?:previous|before|history|last time)\b|之前|以前|历史|上次/i
+	},
+	{
+		hint: "future",
+		pattern: /\b(?:future|next|later|upcoming)\b|未来|下次|之后|即将/i
+	}
+];
+function buildRetrievalQueryProfile(query, scope = {}) {
+	const normalized = normalizeRetrievalText(query);
+	const intentKinds = INTENT_RULES.filter((rule) => rule.pattern.test(normalized)).flatMap((rule) => rule.kinds);
+	const timeHints = TIME_RULES.filter((rule) => rule.pattern.test(normalized)).map((rule) => rule.hint);
+	return {
+		normalized,
+		terms: extractLexicalTerms(normalized),
+		cjkBigrams: extractCjkBigrams(normalized),
+		identifiers: extractRetrievalIdentifiers(normalized),
+		intentKinds: [...new Set(intentKinds)],
+		timeHints: [...new Set(timeHints)],
+		scope: { ...scope }
+	};
+}
+//#endregion
+export { buildRetrievalQueryProfile };

package/dist/src/retrieval/textFeatures.d.ts

@@ -0,0 +1,5 @@
+export declare function normalizeRetrievalText(value: string): string;
+export declare function extractLexicalTerms(value: string): string[];
+export declare function extractCjkBigrams(value: string): string[];
+export declare function extractRetrievalIdentifiers(value: string): string[];
+export declare function retrievalLexicalSimilarity(left: string, right: string): number;

package/dist/src/retrieval/textFeatures.js

@@ -0,0 +1,71 @@
+//#region src/retrieval/textFeatures.ts
+const ENGLISH_STOP_WORDS = new Set([
+	"a",
+	"an",
+	"and",
+	"are",
+	"can",
+	"did",
+	"do",
+	"does",
+	"for",
+	"how",
+	"i",
+	"in",
+	"is",
+	"it",
+	"me",
+	"my",
+	"of",
+	"on",
+	"or",
+	"the",
+	"to",
+	"was",
+	"what",
+	"when",
+	"where",
+	"which",
+	"who",
+	"why",
+	"with",
+	"you",
+	"your"
+]);
+function normalizeRetrievalText(value) {
+	return value.normalize("NFKC").toLowerCase().replace(/\s+/g, " ").trim();
+}
+function extractLexicalTerms(value) {
+	const terms = normalizeRetrievalText(value).match(/[\p{L}\p{N}_]+/gu)?.filter((term) => term.length > 1 && !ENGLISH_STOP_WORDS.has(term)) ?? [];
+	return [...new Set(terms)];
+}
+function extractCjkBigrams(value) {
+	const features = [];
+	for (const sequence of normalizeRetrievalText(value).match(/\p{Script=Han}+/gu) ?? []) {
+		const characters = [...sequence];
+		for (let index = 0; index < characters.length - 1; index += 1) features.push(`${characters[index]}${characters[index + 1]}`);
+	}
+	return [...new Set(features)];
+}
+function extractRetrievalIdentifiers(value) {
+	const normalized = normalizeRetrievalText(value);
+	const identifiers = [
+		...normalized.match(/@[a-z0-9_.-]+\/[a-z0-9_.-]+/g) ?? [],
+		...normalized.match(/(?:[a-z0-9_.-]+\/)+[a-z0-9_.-]+/g) ?? [],
+		...normalized.match(/\b[a-z0-9_-]+\.[a-z0-9]{1,12}\b/g) ?? [],
+		...normalized.match(/#[0-9]+\b/g) ?? [],
+		...normalized.match(/\b[a-z]+-[a-z0-9-]*[0-9][a-z0-9-]*\b/g) ?? []
+	];
+	const unique = [...new Set(identifiers)];
+	return unique.filter((identifier) => !unique.includes(`@${identifier}`));
+}
+function retrievalLexicalSimilarity(left, right) {
+	const leftFeatures = new Set([...extractLexicalTerms(left).map((term) => `term:${term}`), ...extractCjkBigrams(left).map((term) => `han:${term}`)]);
+	const rightFeatures = new Set([...extractLexicalTerms(right).map((term) => `term:${term}`), ...extractCjkBigrams(right).map((term) => `han:${term}`)]);
+	if (leftFeatures.size === 0 || rightFeatures.size === 0) return 0;
+	let shared = 0;
+	for (const feature of leftFeatures) if (rightFeatures.has(feature)) shared += 1;
+	return 2 * shared / (leftFeatures.size + rightFeatures.size);
+}
+//#endregion
+export { extractCjkBigrams, extractLexicalTerms, extractRetrievalIdentifiers, normalizeRetrievalText, retrievalLexicalSimilarity };