@alpsckr/unitycli 0.4.0

package/dist/runtime-code.js

@@ -0,0 +1,232 @@
+import { createHash } from "node:crypto";
+import { constants } from "node:fs";
+import { access, open } from "node:fs/promises";
+import { resolve } from "node:path";
+import { stdin } from "node:process";
+import { executeBridgePayload } from "./bridge/index.js";
+import { StructuredToolError } from "./tools/errors.js";
+const liveDefaultTimeoutMs = 60_000;
+const maxCodeSourceBytes = 768 * 1024;
+const maxBridgePayloadBytes = 900 * 1024;
+/** 只通过已打开 Editor 执行 Runtime Code；提供 completionProbe 时返回业务完成证明。 */
+export async function executeRuntimeCode(request, runtime, requestId) {
+    const timeoutMs = normalizeTimeout(request.timeoutMs);
+    const absoluteDeadlineMs = request.absoluteDeadlineMs ?? Date.now() + timeoutMs;
+    requireRuntimeCodeDeadline(absoluteDeadlineMs);
+    const source = await readCodeSource(request, absoluteDeadlineMs);
+    requireRuntimeCodeDeadline(absoluteDeadlineMs);
+    const parsedArgs = request.args ?? {};
+    const refs = await validateExtraReferences(request.refs, absoluteDeadlineMs);
+    requireRuntimeCodeDeadline(absoluteDeadlineMs);
+    const payload = {
+        sourceKind: source.kind,
+        sourcePath: source.path,
+        sourceText: source.text,
+        sourceSha256: source.sha256,
+        sourceSizeBytes: source.sizeBytes,
+        argsJson: JSON.stringify(parsedArgs),
+        defines: request.define?.join(",") ?? "",
+        refs,
+        ...(request.completionProbe ? { completionProbe: request.completionProbe } : {}),
+    };
+    const payloadBytes = Buffer.byteLength(JSON.stringify(payload), "utf8");
+    if (payloadBytes > maxBridgePayloadBytes)
+        throw new StructuredToolError("E_CODE_INPUT_TOO_LARGE", `Runtime Code Bridge payload exceeds the ${maxBridgePayloadBytes}-byte local limit.`);
+    requireRuntimeCodeDeadline(absoluteDeadlineMs);
+    if (request.dryRun) {
+        return {
+            dryRun: true,
+            preview: {
+                sourceKind: source.kind,
+                ...(source.path ? { sourcePath: source.path } : {}),
+                sourceSha256: source.sha256,
+                sourceSizeBytes: source.sizeBytes,
+                timeoutMs,
+                args: parsedArgs,
+            },
+            plannedEffects: [{ type: "code.exec", sideEffects: "user-code-not-executed" }],
+        };
+    }
+    requireRuntimeCodeDeadline(absoluteDeadlineMs);
+    const result = await executeBridgePayload(requestId, "code.exec", payload, {
+        instance: request.instance ?? "",
+        "timeout-ms": String(timeoutMs),
+        __destructiveConfirmed: true,
+    }, runtime, undefined, { mode: "execute", mutation: true, defaultTimeoutMs: timeoutMs, absoluteDeadlineMs });
+    if (!result.ok)
+        throwCliFailure(result);
+    return (result.data ?? {});
+}
+/** 读取且哈希唯一代码源，所有文件错误均发生在 Unity effect 前。 */
+async function readCodeSource(request, absoluteDeadlineMs) {
+    const selected = [request.file !== undefined, request.code !== undefined, request.stdin === true].filter(Boolean).length;
+    if (selected !== 1)
+        throw new StructuredToolError("E_CODE_SOURCE_INVALID", "Pass exactly one code source: file, stdin, or inline code.");
+    try {
+        if (request.file) {
+            const path = resolve(request.file);
+            return codeSource("file", await readBoundedCodeFile(path, absoluteDeadlineMs), path);
+        }
+        if (request.code !== undefined)
+            return codeSource("inline", request.code);
+        return codeSource("stdin", await readAllStdin(absoluteDeadlineMs));
+    }
+    catch (error) {
+        if (error instanceof StructuredToolError)
+            throw error;
+        throw new StructuredToolError("E_CODE_SOURCE_INVALID", error instanceof Error ? error.message : String(error), ["Check that the source path exists and is UTF-8 readable."]);
+    }
+}
+/** 从同一文件句柄按字节和deadline有界读取代码，避免路径替换、增长或阻塞绕过入口预算。 */
+async function readBoundedCodeFile(path, absoluteDeadlineMs) {
+    const openPromise = open(path, "r");
+    const handle = await beforeRuntimeCodeDeadline(openPromise, absoluteDeadlineMs, () => {
+        void openPromise.then((lateHandle) => lateHandle.close()).catch(() => undefined);
+    });
+    const chunks = [];
+    let total = 0;
+    let closeDeferred = false;
+    try {
+        while (true) {
+            requireRuntimeCodeDeadline(absoluteDeadlineMs);
+            const buffer = Buffer.allocUnsafe(Math.min(64 * 1024, maxCodeSourceBytes + 1 - total));
+            const readPromise = handle.read(buffer, 0, buffer.length, null);
+            const { bytesRead } = await beforeRuntimeCodeDeadline(readPromise, absoluteDeadlineMs, () => {
+                closeDeferred = true;
+                void readPromise.then(() => handle.close(), () => handle.close()).catch(() => undefined);
+            });
+            if (bytesRead === 0)
+                break;
+            total += bytesRead;
+            if (total > maxCodeSourceBytes)
+                throw new StructuredToolError("E_CODE_INPUT_TOO_LARGE", `Runtime Code source file exceeds the ${maxCodeSourceBytes}-byte local limit.`);
+            chunks.push(buffer.subarray(0, bytesRead));
+        }
+        requireRuntimeCodeDeadline(absoluteDeadlineMs);
+        return Buffer.concat(chunks, total).toString("utf8");
+    }
+    finally {
+        if (!closeDeferred)
+            await handle.close();
+    }
+}
+function codeSource(kind, text, path) {
+    if (text.trim().length === 0)
+        throw new StructuredToolError("E_CODE_SOURCE_INVALID", "Code source is empty.");
+    const sizeBytes = Buffer.byteLength(text, "utf8");
+    if (sizeBytes > maxCodeSourceBytes)
+        throw new StructuredToolError("E_CODE_INPUT_TOO_LARGE", `Runtime Code source exceeds the ${maxCodeSourceBytes}-byte local limit.`);
+    return { kind, path, text, sha256: createHash("sha256").update(text, "utf8").digest("hex"), sizeBytes };
+}
+/** 事件式读取Runtime Code源码stdin，达到字节或deadline上限时立即解除监听。 */
+async function readAllStdin(absoluteDeadlineMs) {
+    requireRuntimeCodeDeadline(absoluteDeadlineMs);
+    return new Promise((resolvePromise, rejectPromise) => {
+        let text = "";
+        let sizeBytes = 0;
+        let timer;
+        const cleanup = () => {
+            if (timer)
+                clearTimeout(timer);
+            stdin.off("data", onData);
+            stdin.off("end", onEnd);
+            stdin.off("error", onError);
+            stdin.pause();
+        };
+        const onData = (chunk) => {
+            const value = typeof chunk === "string" ? chunk : chunk.toString("utf8");
+            sizeBytes += Buffer.byteLength(value, "utf8");
+            if (sizeBytes > maxCodeSourceBytes) {
+                cleanup();
+                rejectPromise(new StructuredToolError("E_CODE_INPUT_TOO_LARGE", `Runtime Code stdin exceeds the ${maxCodeSourceBytes}-byte local limit.`));
+                return;
+            }
+            text += value;
+        };
+        const onEnd = () => { cleanup(); resolvePromise(text); };
+        const onError = (error) => { cleanup(); rejectPromise(error); };
+        stdin.setEncoding("utf8");
+        stdin.on("data", onData);
+        stdin.once("end", onEnd);
+        stdin.once("error", onError);
+        timer = setTimeout(() => {
+            cleanup();
+            rejectPromise(new StructuredToolError("E_EXECUTION_TIMEOUT", "Runtime Code stdin did not finish reading before the immutable deadline."));
+        }, Math.max(1, absoluteDeadlineMs - Date.now()));
+        stdin.resume();
+    });
+}
+function requireRuntimeCodeDeadline(absoluteDeadlineMs) {
+    if (!Number.isFinite(absoluteDeadlineMs) || Date.now() >= absoluteDeadlineMs)
+        throw new StructuredToolError("E_EXECUTION_TIMEOUT", "Runtime Code immutable deadline elapsed before Bridge dispatch.", ["Reduce local input size or submit a new request with a sufficient timeout."]);
+}
+function normalizeTimeout(value) {
+    if (!value || value <= 0)
+        return liveDefaultTimeoutMs;
+    return Math.trunc(value);
+}
+/** 引用必须在 effect 前全部存在且可读。 */
+async function validateExtraReferences(refs, absoluteDeadlineMs) {
+    if (!refs)
+        return "";
+    if (refs.length > 64)
+        throw new StructuredToolError("E_REFERENCE_RESOLUTION_FAILED", "Runtime Code accepts at most 64 extra references.");
+    const normalized = refs.map((part) => part.trim()).filter(Boolean);
+    for (const reference of normalized) {
+        if (Buffer.byteLength(reference, "utf8") > 2048)
+            throw new StructuredToolError("E_REFERENCE_RESOLUTION_FAILED", "Runtime Code reference path exceeds 2048 UTF-8 bytes.");
+        requireRuntimeCodeDeadline(absoluteDeadlineMs);
+        try {
+            await accessReferenceBeforeDeadline(reference, absoluteDeadlineMs);
+            requireRuntimeCodeDeadline(absoluteDeadlineMs);
+        }
+        catch (error) {
+            if (error instanceof StructuredToolError)
+                throw error;
+            throw new StructuredToolError("E_REFERENCE_RESOLUTION_FAILED", `Runtime Code reference is not readable: ${reference}.`, [error instanceof Error ? error.message : String(error)]);
+        }
+    }
+    return normalized.join(",");
+}
+/** 将不可取消的代码源I/O等待限制在入口deadline内，并由调用方安排迟到资源回收。 */
+async function beforeRuntimeCodeDeadline(operation, absoluteDeadlineMs, onLate) {
+    requireRuntimeCodeDeadline(absoluteDeadlineMs);
+    let timer;
+    try {
+        return await Promise.race([
+            operation,
+            new Promise((_, rejectPromise) => { timer = setTimeout(() => { onLate?.(); rejectPromise(new StructuredToolError("E_EXECUTION_TIMEOUT", "Runtime Code local I/O exceeded the immutable deadline.")); }, Math.max(1, absoluteDeadlineMs - Date.now())); }),
+        ]);
+    }
+    finally {
+        if (timer)
+            clearTimeout(timer);
+    }
+}
+/** 引用可读性检查与入口deadline竞速，避免本地I/O无限延长请求。 */
+async function accessReferenceBeforeDeadline(reference, absoluteDeadlineMs) {
+    const remainingMs = Math.max(1, absoluteDeadlineMs - Date.now());
+    let timer;
+    try {
+        await Promise.race([
+            access(reference, constants.R_OK),
+            new Promise((_, reject) => { timer = setTimeout(() => reject(new StructuredToolError("E_EXECUTION_TIMEOUT", "Runtime Code reference validation exceeded the immutable deadline.")), remainingMs); }),
+        ]);
+    }
+    finally {
+        if (timer)
+            clearTimeout(timer);
+    }
+}
+function throwCliFailure(result) {
+    const error = result.error ?? {};
+    throw StructuredToolError.from({
+        code: error.code ?? "CODE_EXEC_FAILED",
+        message: error.message ?? "Runtime Code execution failed.",
+        nextActions: error.nextActions,
+        details: error.details,
+        transient: error.transient,
+        retryAfterMs: error.retryAfterMs,
+    });
+}
+//# sourceMappingURL=runtime-code.js.map

package/dist/runtime-code.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"runtime-code.js","sourceRoot":"","sources":["../src/runtime-code.ts"],"names":[],"mappings":"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"}

package/dist/schema/any-json.d.ts

@@ -0,0 +1,4 @@
+/** 明确表示可由 JSON 承载的任意动态值。schema 生成器会为其添加开放标记。 */
+export type AnyJson = string | number | boolean | null | AnyJson[] | {
+    [key: string]: AnyJson;
+};

package/dist/schema/any-json.js

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=any-json.js.map

package/dist/schema/any-json.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"any-json.js","sourceRoot":"","sources":["../../src/schema/any-json.ts"],"names":[],"mappings":""}

package/dist/schema/validator.d.ts

@@ -0,0 +1,7 @@
+export interface SchemaIssue {
+    path: string;
+    expected: string;
+    actual: string;
+}
+/** 校验生成器支持的 JSON Schema 子集；无法解析的 schema 关键字和引用同样 fail closed。 */
+export declare function validateSchema(schema: unknown, value: unknown, path?: string, rootSchema?: unknown): SchemaIssue[];

package/dist/schema/validator.js

@@ -0,0 +1,135 @@
+/** 校验生成器支持的 JSON Schema 子集；无法解析的 schema 关键字和引用同样 fail closed。 */
+export function validateSchema(schema, value, path = "$", rootSchema = schema) {
+    if (!isRecord(schema))
+        return [issue(path, "valid schema", "missing schema")];
+    const rule = schema;
+    if (rule["x-unityCliAnyJson"] === true)
+        return [];
+    const supportedKeywords = new Set(["$schema", "$id", "title", "description", "default", "$ref", "$defs", "allOf", "oneOf", "anyOf", "const", "enum", "type", "properties", "required", "additionalProperties", "items", "prefixItems", "minItems", "maxItems", "minLength", "maxLength", "minimum", "maximum", "pattern", "format", "uniqueItems"]);
+    const unsupported = Object.keys(rule).find((key) => !supportedKeywords.has(key));
+    if (unsupported)
+        return [issue(path, "supported schema keyword", `unsupported keyword ${unsupported}`)];
+    if (Object.keys(rule).length === 0)
+        return [issue(path, "constrained schema", "unconstrained schema")];
+    if (typeof rule.$ref === "string") {
+        const resolved = resolveReference(rootSchema, rule.$ref);
+        if (!resolved)
+            return [issue(path, `resolvable reference ${rule.$ref}`, "unresolved reference")];
+        const referenceIssues = validateSchema(resolved, value, path, rootSchema);
+        if (referenceIssues.length > 0)
+            return referenceIssues;
+    }
+    if (Array.isArray(rule.allOf)) {
+        const issues = rule.allOf.flatMap((candidate) => validateSchema(candidate, value, path, rootSchema));
+        if (issues.length > 0)
+            return issues;
+    }
+    const alternatives = Array.isArray(rule.oneOf) ? rule.oneOf : Array.isArray(rule.anyOf) ? rule.anyOf : undefined;
+    if (alternatives) {
+        const matches = alternatives.filter((candidate) => validateSchema(candidate, value, path, rootSchema).length === 0).length;
+        const valid = Array.isArray(rule.oneOf) ? matches === 1 : matches > 0;
+        if (!valid)
+            return [issue(path, Array.isArray(rule.oneOf) ? "exactly one allowed schema" : "an allowed schema", valueType(value))];
+    }
+    if ("const" in rule && !Object.is(rule.const, value))
+        return [issue(path, `const ${display(rule.const)}`, display(value))];
+    if (Array.isArray(rule.enum) && !rule.enum.some((candidate) => Object.is(candidate, value)))
+        return [issue(path, `enum ${rule.enum.map(display).join(", ")}`, display(value))];
+    const allowedTypes = Array.isArray(rule.type) ? rule.type : typeof rule.type === "string" ? [rule.type] : [];
+    if (allowedTypes.length > 0 && !allowedTypes.some((type) => matchesType(type, value)))
+        return [issue(path, allowedTypes.join(" | "), valueType(value))];
+    if (isRecord(value) && !Array.isArray(value) && (allowedTypes.includes("object") || rule.properties !== undefined || rule.additionalProperties !== undefined)) {
+        const properties = isRecord(rule.properties) ? rule.properties : {};
+        const issues = [];
+        for (const key of Array.isArray(rule.required) ? rule.required.filter((item) => typeof item === "string") : []) {
+            if (!Object.prototype.hasOwnProperty.call(value, key))
+                issues.push(issue(`${path}.${key}`, "required property", "missing"));
+        }
+        for (const [key, child] of Object.entries(value)) {
+            if (key in properties)
+                issues.push(...validateSchema(properties[key], child, `${path}.${key}`, rootSchema));
+            else if (rule.additionalProperties === false)
+                issues.push(issue(`${path}.${key}`, "known property", "unknown property"));
+            else if (isRecord(rule.additionalProperties))
+                issues.push(...validateSchema(rule.additionalProperties, child, `${path}.${key}`, rootSchema));
+        }
+        return issues;
+    }
+    if (Array.isArray(value) && (allowedTypes.includes("array") || rule.items !== undefined || rule.prefixItems !== undefined)) {
+        const issues = [];
+        if (typeof rule.minItems === "number" && value.length < rule.minItems)
+            issues.push(issue(path, `at least ${rule.minItems} items`, `${value.length} items`));
+        if (typeof rule.maxItems === "number" && value.length > rule.maxItems)
+            issues.push(issue(path, `at most ${rule.maxItems} items`, `${value.length} items`));
+        const prefixItems = Array.isArray(rule.prefixItems) ? rule.prefixItems : [];
+        for (let index = 0; index < prefixItems.length && index < value.length; index += 1)
+            issues.push(...validateSchema(prefixItems[index], value[index], `${path}[${index}]`, rootSchema));
+        for (let index = prefixItems.length; index < value.length; index += 1) {
+            if (rule.items === false)
+                issues.push(issue(`${path}[${index}]`, `tuple with ${prefixItems.length} items`, "additional item"));
+            else if (isRecord(rule.items))
+                issues.push(...validateSchema(rule.items, value[index], `${path}[${index}]`, rootSchema));
+        }
+        if (rule.uniqueItems === true && new Set(value.map((item) => JSON.stringify(item))).size !== value.length)
+            issues.push(issue(path, "unique items", "duplicate item"));
+        return issues;
+    }
+    if (typeof value === "string") {
+        if (rule.format === "date-time" && !Number.isFinite(Date.parse(value)))
+            return [issue(path, "date-time", value)];
+        if (rule.format === "uuid" && !/^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$/i.test(value))
+            return [issue(path, "uuid", value)];
+        if (typeof rule.minLength === "number" && value.length < rule.minLength)
+            return [issue(path, `minimum length ${rule.minLength}`, `length ${value.length}`)];
+        if (typeof rule.maxLength === "number" && value.length > rule.maxLength)
+            return [issue(path, `maximum length ${rule.maxLength}`, `length ${value.length}`)];
+        if (typeof rule.pattern === "string") {
+            try {
+                if (!new RegExp(rule.pattern).test(value))
+                    return [issue(path, `pattern ${rule.pattern}`, value)];
+            }
+            catch {
+                return [issue(path, "valid regex pattern", rule.pattern)];
+            }
+        }
+    }
+    if (typeof value === "number") {
+        if (typeof rule.minimum === "number" && value < rule.minimum)
+            return [issue(path, `>= ${rule.minimum}`, String(value))];
+        if (typeof rule.maximum === "number" && value > rule.maximum)
+            return [issue(path, `<= ${rule.maximum}`, String(value))];
+    }
+    return [];
+}
+function resolveReference(rootSchema, reference) {
+    if (!reference.startsWith("#/"))
+        return undefined;
+    let current = rootSchema;
+    for (const encoded of reference.slice(2).split("/")) {
+        if (!isRecord(current))
+            return undefined;
+        const key = encoded.replace(/~1/g, "/").replace(/~0/g, "~");
+        current = current[key];
+    }
+    return current;
+}
+function matchesType(type, value) {
+    if (type === "null")
+        return value === null;
+    if (type === "array")
+        return Array.isArray(value);
+    if (type === "object")
+        return isRecord(value);
+    if (type === "integer")
+        return typeof value === "number" && Number.isInteger(value);
+    if (type === "number")
+        return typeof value === "number" && Number.isFinite(value);
+    return typeof type === "string" && typeof value === type;
+}
+function isRecord(value) {
+    return !!value && typeof value === "object" && !Array.isArray(value);
+}
+function issue(path, expected, actual) { return { path, expected, actual }; }
+function valueType(value) { return value === null ? "null" : Array.isArray(value) ? "array" : typeof value; }
+function display(value) { return typeof value === "string" ? value : JSON.stringify(value); }
+//# sourceMappingURL=validator.js.map

package/dist/schema/validator.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"validator.js","sourceRoot":"","sources":["../../src/schema/validator.ts"],"names":[],"mappings":"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"}

package/dist/services/docs-reflect-cache.d.ts

@@ -0,0 +1,106 @@
+import { StructuredToolError } from "../tools/errors.js";
+export interface CacheEntry {
+    name: string;
+    title?: string;
+    summary?: string;
+    content?: string;
+    url?: string;
+    kind?: string;
+    namespace?: string;
+    version?: string;
+    path?: string;
+    assembly?: string;
+    fullName?: string;
+    signature?: string;
+    returnType?: string;
+    parameters?: unknown;
+    members?: CacheEntry[];
+}
+export interface AssemblyEntry {
+    name: string;
+    path?: string;
+    status?: string;
+    error?: string;
+}
+export interface Diagnostic {
+    level: "info" | "warning" | "error";
+    code: string;
+    message: string;
+    assembly?: string;
+    path?: string;
+}
+export interface CacheIndex {
+    root: string;
+    indexPath?: string;
+    unityVersion?: string;
+    entries: CacheEntry[];
+    assemblies?: AssemblyEntry[];
+    diagnostics: Diagnostic[];
+}
+export interface PageOptions {
+    pageSize?: number;
+    cursor?: string;
+}
+export interface Page<T> {
+    items: T[];
+    pageInfo: {
+        pageSize: number;
+        cursor: string;
+        nextCursor?: string;
+        total: number;
+    };
+}
+export declare class CacheError extends Error {
+    readonly code: string;
+    readonly nextActions: string[];
+    constructor(code: string, message: string, nextActions?: string[]);
+}
+/** 解析文档 cache 目录；只读取显式输入、环境变量和 dataDir。 */
+export declare function docsCacheDir(docsDir: string | undefined, dataDir: string): string;
+/** 解析反射 cache 目录；只读取显式输入、环境变量和 dataDir。 */
+export declare function reflectCacheDir(reflectDir: string | undefined, dataDir: string): string;
+/** 读取文档索引或 Markdown 文件树，返回规范化 cache；副作用仅为文件读取。 */
+export declare function loadDocsCache(root: string): Promise<CacheIndex>;
+/** 读取并规范化反射索引；副作用仅为文件读取。 */
+export declare function loadReflectCache(root: string): Promise<CacheIndex>;
+/** 按请求版本筛选条目；无匹配时抛出带稳定 code 的 cache 错误。 */
+export declare function filterVersion(cache: CacheIndex, requested: string | undefined, code: string): CacheIndex;
+/** 延迟读取文档正文；读取失败时保留索引条目，不产生写入。 */
+export declare function hydrateContent(entry: CacheEntry, root: string): Promise<CacheEntry>;
+/** 按 cursor 和 pageSize 截取结果并生成 continuation 信息。 */
+export declare function paginate<T>(items: T[], options: PageOptions): Page<T>;
+/** 将 cache 异常转换为工具层结构化错误，保留 code 和恢复动作。 */
+export declare function cacheError(error: unknown): StructuredToolError;
+/** 返回适合公开输出的文档字段，可按需携带正文。 */
+export declare function publicDoc(entry: CacheEntry, includeContent: boolean): Record<string, unknown>;
+/** 返回适合公开输出的类型字段，可按需展开成员。 */
+export declare function publicType(entry: CacheEntry, includeMembers: boolean): Record<string, unknown>;
+/** 返回适合公开输出的成员字段，并补充声明类型和程序集。 */
+export declare function publicMember(member: CacheEntry, type: CacheEntry): Record<string, unknown>;
+/** 返回 cache 的公开来源信息。 */
+export declare function cacheSource(cache: CacheIndex): Record<string, unknown>;
+/** 返回 cache 解析出的 Unity 版本。 */
+export declare function unityVersion(cache: CacheIndex): Record<string, unknown>;
+/** 只返回程序集相关诊断，避免混入其他 cache 警告。 */
+export declare function assemblyDiagnostics(cache: CacheIndex): Diagnostic[];
+/** 精确匹配类型短名、全名或标题，匹配不区分大小写。 */
+export declare function typeMatches(entries: CacheEntry[], query: string): CacheEntry[];
+/** 精确匹配文档名、全名或标题，匹配不区分大小写。 */
+export declare function entryMatchesName(entry: CacheEntry, query: string): boolean;
+/** 对 cache 条目进行相关性评分并稳定排序。 */
+export declare function scoreEntries(entries: CacheEntry[], query: string): Array<{
+    entry: CacheEntry;
+    score: number;
+}>;
+/** 计算单条 cache 记录的字段加权相关性。 */
+export declare function scoreEntry(entry: CacheEntry, query: string): number;
+/** 计算文本与查询的精确、前缀或包含匹配分值。 */
+export declare function scoreText(value: string | undefined, query: string): number;
+/** 将文档条目渲染为纯文本输出。 */
+export declare function docText(doc: CacheEntry): string;
+/** 将类型及其成员摘要渲染为纯文本输出。 */
+export declare function typeText(type: Record<string, unknown>): string;
+/** 将单个成员详情渲染为纯文本输出。 */
+export declare function memberText(type: Record<string, unknown>, member: Record<string, unknown>): string;
+/** 将反射搜索项渲染为单行文本。 */
+export declare function reflectSearchLine(item: unknown): string;