@customize-agent/knowledge 4.0.42 → 4.0.44

package/dist/core/index-runner.d.ts

@@ -0,0 +1,20 @@
+import type { DiffResult } from '../types.js';
+import type { KnowledgeBaseManager, KnowledgeIndexProgress } from './knowledge-base-manager.js';
+export interface IndexRunJob {
+    relativePath?: string;
+    relativePaths?: string[];
+    forceReindexAll?: boolean;
+    vectorMode?: 'sync' | 'defer';
+    uploadOperationId?: string;
+}
+export interface IndexRunOutcome {
+    diff: DiffResult;
+    vectorStatus: ReturnType<KnowledgeBaseManager['getVectorStatus']>;
+}
+/**
+ * 知识库索引主循环：扫描变更 → 解析分块 → 等待上传批次 → 向量化收尾。
+ * 主进程直跑（CUSTOMIZE_AGENT_DISABLE_KB_CHILD_PROCESS=1）与后台子进程（kb-index-worker.cjs）
+ * 共用同一实现，避免两处逐行重复导致索引行为漂移。
+ * 进度上报通过 onProgress 回调交给调用方（主进程写操作日志、子进程经 IPC 转发），本函数不落盘。
+ */
+export declare function runIndexLoop(project: KnowledgeBaseManager, job: IndexRunJob, onProgress: (progress: KnowledgeIndexProgress) => void): Promise<IndexRunOutcome>;

package/dist/core/index-runner.js

@@ -0,0 +1,45 @@
+/**
+ * 知识库索引主循环：扫描变更 → 解析分块 → 等待上传批次 → 向量化收尾。
+ * 主进程直跑（CUSTOMIZE_AGENT_DISABLE_KB_CHILD_PROCESS=1）与后台子进程（kb-index-worker.cjs）
+ * 共用同一实现，避免两处逐行重复导致索引行为漂移。
+ * 进度上报通过 onProgress 回调交给调用方（主进程写操作日志、子进程经 IPC 转发），本函数不落盘。
+ */
+export async function runIndexLoop(project, job, onProgress) {
+    let diff = job.relativePaths?.length
+        ? await project.incrementalIndex({ vectorMode: job.vectorMode, onProgress, onlyRelativePaths: job.relativePaths })
+        : job.relativePath
+            ? await project.reindexFile(job.relativePath, { vectorMode: job.vectorMode, onProgress })
+            : job.forceReindexAll
+                ? await project.forceReindexAll({ vectorMode: job.vectorMode, onProgress })
+                : await project.consumePendingIndexJobs({ vectorMode: job.vectorMode, onProgress, waitForUploadId: job.uploadOperationId });
+    let idleChecks = 0;
+    // 上传 session 空闲上限：批次间无新文件到达超过该时长即退出等待，避免前端中断后 worker 永久挂起
+    const sessionIdleLimitMs = Math.max(60_000, Number(process.env.CUSTOMIZE_KB_UPLOAD_SESSION_IDLE_MS || 600_000));
+    const maxIdleChecks = Math.max(10, Math.ceil(sessionIdleLimitMs / 1000));
+    // 等待任何未关闭的上传 session（不限于本 operationId），避免重叠上传的后续批次文件无人消费
+    while (!job.relativePath && !job.relativePaths?.length && (project.countPendingIndexJobs() > 0 || (project.hasOpenUploadSessions() && idleChecks < maxIdleChecks))) {
+        if (project.countPendingIndexJobs() === 0) {
+            idleChecks += 1;
+            await new Promise(resolve => setTimeout(resolve, 1000));
+            continue;
+        }
+        idleChecks = 0;
+        const nextDiff = await project.consumePendingIndexJobs({ vectorMode: job.vectorMode, onProgress, waitForUploadId: job.uploadOperationId });
+        diff = {
+            newFiles: [...diff.newFiles, ...nextDiff.newFiles],
+            modifiedFiles: [...diff.modifiedFiles, ...nextDiff.modifiedFiles],
+            deletedFiles: [...diff.deletedFiles, ...nextDiff.deletedFiles],
+            unchangedCount: diff.unchangedCount + nextDiff.unchangedCount,
+            mtimeOnlyCount: diff.mtimeOnlyCount + nextDiff.mtimeOnlyCount,
+            skippedFiles: [...diff.skippedFiles, ...nextDiff.skippedFiles],
+            hasChanges: diff.hasChanges || nextDiff.hasChanges,
+            diffTimeMs: diff.diffTimeMs + nextDiff.diffTimeMs,
+        };
+    }
+    let vectorStatus = project.getVectorStatus();
+    if (job.vectorMode === 'defer' && vectorStatus.status === 'pending') {
+        await project.indexVectors();
+        vectorStatus = project.getVectorStatus();
+    }
+    return { diff, vectorStatus };
+}

package/dist/core/index-state-store.d.ts

@@ -151,6 +151,8 @@ export declare class IndexStateStore {
     listParentChunks(relativePath: string): StoredParentChunk[];
     getParentChunk(relativePath: string, parentId: string): StoredParentChunk | undefined;
     getDocumentChunk(relativePath: string): StoredDocumentChunk | undefined;
+    /** 聚合统计切片数：单条 SUM 查询，避免加载全部索引记录后再求和 */
+    countIndexedChunks(filePaths?: string[]): number;
     getChunksByParent(relativePath: string, parentId: string, limit?: number): StoredChunk[];
     /**
      * 使用关键词搜索切片（支持 FTS5 全文搜索和 LIKE 模糊匹配）
@@ -193,6 +195,7 @@ export declare class IndexStateStore {
     deleteRecord(relativePath: string): void;
     setMetadata(key: string, value: string): void;
     getMetadata(key: string): string | undefined;
+    listMetadataKeys(prefix?: string): string[];
     getStats(): {
         fileCount: number;
         chunkCount: number;

package/dist/core/index-state-store.js

@@ -9,6 +9,9 @@ export class IndexStateStore {
         fs.mkdirSync(path.dirname(dbPath), { recursive: true });
         this.db = new Database(dbPath);
         this.db.pragma('journal_mode = WAL');
+        // P1-8 SQLite 并发读加固：显式 busy_timeout（kb.db 大库并发读曾出现 SQLITE_READONLY 瞬态，
+        // WAL 模式下写锁升级竞争由 busy_timeout 兜底等待，避免立即抛锁错误）
+        this.db.pragma('busy_timeout = 10000');
         this.initTables();
     }
     /** 加载所有活跃的索引记录 */
@@ -279,13 +282,23 @@ export class IndexStateStore {
     `).get(relativePath);
         return row ? this.rowToDocumentChunk(row) : undefined;
     }
+    /** 聚合统计切片数：单条 SUM 查询，避免加载全部索引记录后再求和 */
+    countIndexedChunks(filePaths) {
+        const paths = filePaths?.filter(Boolean) ?? [];
+        const clause = paths.length > 0 ? ` WHERE relative_path IN (${paths.map(() => '?').join(', ')})` : '';
+        const row = this.db.prepare(`SELECT COALESCE(SUM(chunk_count), 0) AS total FROM kb_index_state${clause}`)
+            .get(...paths);
+        return Math.max(0, Math.ceil(Number(row?.total) || 0));
+    }
     getChunksByParent(relativePath, parentId, limit = 6) {
+        // 使用 parent_id 列 + idx_kb_chunks_parent 索引；
+        // 原先的 metadata_json LIKE '%"parentId":"..."%' 无法使用索引，是每次调用的全表扫描
         const rows = this.db.prepare(`
       SELECT rowid, * FROM kb_chunks
-      WHERE relative_path = ? AND metadata_json LIKE ?
+      WHERE relative_path = ? AND parent_id = ?
       ORDER BY chunk_index
       LIMIT ?
-    `).all(relativePath, `%"parentId":"${parentId.replace(/[%_]/gu, '')}"%`, limit);
+    `).all(relativePath, parentId, limit);
         return rows.map(row => this.rowToChunk(row, 0));
     }
     /**
@@ -300,11 +313,11 @@ export class IndexStateStore {
             return [];
         const filePaths = [...new Set((filters.filePaths ?? []).filter(Boolean))];
         const effectiveLimit = this.resolveChunkSearchLimit(limit, filePaths);
-        const results = [
-            ...(this.ftsEnabled ? this.searchChunksFts(terms, effectiveLimit, filePaths) : []),
-            ...this.searchChunksLike(terms, effectiveLimit, filePaths),
-        ];
-        return this.mergeKeywordResults(results, effectiveLimit);
+        const ftsResults = this.ftsEnabled ? this.searchChunksFts(terms, effectiveLimit, filePaths) : [];
+        // FTS 返回充分结果时跳过 LIKE 全表扫描（LOWER(x) LIKE '%term%' 无法使用索引，最多 40 term × 7 列）；
+        // 中文子串匹配 FTS 命中通常不足，此时 LIKE 仍会执行补齐召回，行为与原先一致
+        const likeResults = ftsResults.length >= effectiveLimit ? [] : this.searchChunksLike(terms, effectiveLimit, filePaths);
+        return this.mergeKeywordResults([...ftsResults, ...likeResults], effectiveLimit);
     }
     filePathFilterClause(filePaths, column = 'relative_path') {
         return filePaths.length > 0 ? ` AND ${column} IN (${filePaths.map(() => '?').join(', ')})` : '';
@@ -506,6 +519,12 @@ export class IndexStateStore {
         const row = this.db.prepare('SELECT value FROM kb_metadata WHERE key = ?').get(key);
         return row?.value;
     }
+    listMetadataKeys(prefix) {
+        const rows = prefix
+            ? this.db.prepare('SELECT key FROM kb_metadata WHERE key LIKE ?').all(`${prefix}%`)
+            : this.db.prepare('SELECT key FROM kb_metadata').all();
+        return rows.map(row => row.key);
+    }
     getStats() {
         const stats = this.db.prepare(`
       SELECT

package/dist/core/knowledge-base-manager.d.ts

@@ -4,7 +4,7 @@ import { type FederatedResult, type FederatedSearchItem, type RetrievalWeights,
 import type { DiffResult, IndexStateRecord, KBScope, KnowledgeBaseStats, ProjectConfig } from '../types.js';
 import type { VectorStoreInterface } from '../vector/types.js';
 import { type VectorIndexResult } from '../vector/vector-indexer.js';
-import { IndexStateStore, type ChunkSearchResult, type FileRelationship } from './index-state-store.js';
+import { IndexStateStore, type ChunkSearchResult, type FileRelationship, type StoredChunk } from './index-state-store.js';
 export type KnowledgeIndexStage = 'scanning' | 'parsing' | 'chunking' | 'vectorizing' | 'done' | 'error';
 export interface KnowledgeIndexProgress {
     stage: KnowledgeIndexStage;
@@ -46,6 +46,10 @@ export declare class KnowledgeBaseManager {
     private projectConfig?;
     private lastSkippedFiles;
     private readonly llmProvider?;
+    private readonly queryExpansionCache;
+    private readonly queryExpansionInFlight;
+    private queryExpansionActive;
+    private readonly queryExpansionWaiters;
     private onProgress?;
     constructor(options: KnowledgeBaseManagerOptions);
     initialize(): void;
@@ -87,14 +91,14 @@ export declare class KnowledgeBaseManager {
     listChunks(options?: {
         relativePath?: string;
         limit?: number;
-    }): import("./index-state-store.js").StoredChunk[];
+    }): StoredChunk[];
     getFileDetail(relativePath: string, options?: {
         maxChunkContentChars?: number;
     }): {
         file: IndexStateRecord;
         absolutePath: string;
         directory: string;
-        chunks: import("./index-state-store.js").StoredChunk[];
+        chunks: StoredChunk[];
         totalChunkCount: number;
         parents: import("./index-state-store.js").StoredParentChunk[];
         relationships: FileRelationship[];
@@ -167,6 +171,9 @@ export declare class KnowledgeBaseManager {
     };
     private rewriteQueries;
     private llmExpandQueries;
+    /** 查询扩展 LLM 调用的简易信号量：与文档生成端的全局信号量解耦，避免扩展请求无界并发击穿模型端点 */
+    private acquireQueryExpansionSlot;
+    private releaseQueryExpansionSlot;
     private retrievalWeights;
     private heuristicRerank;
     private normalizeSearchText;
@@ -192,6 +199,8 @@ export declare class KnowledgeBaseManager {
     private consumePendingVectorRelativePaths;
     private ensureVectorIndexFresh;
     uploadSessionIsOpen(operationId: string): boolean;
+    listOpenUploadSessions(): string[];
+    hasOpenUploadSessions(): boolean;
     private emptyDiff;
     private statRelativePaths;
     private moveUploadedFile;

package/dist/core/knowledge-base-manager.js

@@ -17,6 +17,11 @@ import { ChangeTracker } from './change-tracker.js';
 import { KnowledgeFileScanner } from './file-scanner.js';
 import { IndexStateStore } from './index-state-store.js';
 import { getProjectKbPath, ProjectConfigManager } from './project-config.js';
+// 查询扩展（LLM）调用的约束：生成流程会高频触发查询扩展，
+// TTL 缓存吸收重复扩展、信号量避免扩展请求无界并发击穿模型端点
+const QUERY_EXPANSION_TTL_MS = 10 * 60 * 1000;
+const QUERY_EXPANSION_CACHE_MAX = 256;
+const QUERY_EXPANSION_MAX_CONCURRENCY = 2;
 export class KnowledgeBaseManager {
     scope;
     projectRoot;
@@ -37,6 +42,10 @@ export class KnowledgeBaseManager {
     projectConfig;
     lastSkippedFiles = [];
     llmProvider;
+    queryExpansionCache = new Map();
+    queryExpansionInFlight = new Map();
+    queryExpansionActive = 0;
+    queryExpansionWaiters = [];
     onProgress;
     constructor(options) {
         this.scope = options.scope;
@@ -58,7 +67,7 @@ export class KnowledgeBaseManager {
             if (!options.projectRoot || !options.projectId) {
                 throw new Error('project knowledge base requires projectRoot and projectId');
             }
-            this.kbPath = options.kbPath ?? getProjectKbPath(options.projectRoot);
+            this.kbPath = options.kbPath ?? getProjectKbPath(options.projectRoot, storageRoot);
             dbPath = path.join(storageRoot, 'projects', options.projectId, 'kb.db');
         }
         this.store = new IndexStateStore(dbPath);
@@ -339,11 +348,9 @@ export class KnowledgeBaseManager {
     }
     searchCorpusSize(filters) {
         const paths = filters?.filePaths ?? (filters?.filePath ? [filters.filePath] : undefined);
-        const pathSet = new Set(paths?.filter(Boolean));
-        const total = this.store.listRecords()
-            .filter(record => pathSet.size === 0 || pathSet.has(record.relativePath))
-            .reduce((sum, record) => sum + Math.max(0, Math.ceil(Number(record.chunkCount) || 0)), 0);
-        return Math.max(1, total);
+        const pathSet = paths?.filter(Boolean) ?? [];
+        // 单条 SUM 聚合，避免 listRecords 全量加载每条索引记录
+        return Math.max(1, this.store.countIndexedChunks(pathSet.length > 0 ? pathSet : undefined));
     }
     expandContext(item) {
         const chunkIndex = item.chunkIndex ?? this.parseChunkIndex(item.id);
@@ -362,7 +369,14 @@ export class KnowledgeBaseManager {
         const chunks = parentChunks.length > 0 ? parentChunks : this.store.getContextChunks(item.filePath, chunkIndex, 1);
         if (chunks.length === 0) {
             const document = this.store.getDocumentChunk(item.filePath);
-            return document ? { ...item, content: document.content, sectionTitle: item.sectionTitle ?? 'Document Parent' } : item;
+            if (!document)
+                return item;
+            // 文档级兜底必须截断：整份文档全文（可能 10 万字级）会撑爆 LLM 上下文预算并稀释命中片段信噪比
+            const MAX_DOCUMENT_CONTENT_CHARS = 6000;
+            const content = document.content.length > MAX_DOCUMENT_CONTENT_CHARS
+                ? `${document.content.slice(0, MAX_DOCUMENT_CONTENT_CHARS)}\n……（文档过长，已截断，完整内容请查看原文件）`
+                : document.content;
+            return { ...item, content, sectionTitle: item.sectionTitle ?? 'Document Parent' };
         }
         return {
             ...item,
@@ -375,10 +389,13 @@ export class KnowledgeBaseManager {
     }
     async hybridSearch(query, options = {}) {
         const requestedLimit = Number.isFinite(options.limit) && options.limit > 0 ? Math.ceil(options.limit) : undefined;
-        const corpusSize = this.searchCorpusSize(options.filters);
-        const effectiveLimit = requestedLimit ?? corpusSize;
+        // 调用方已显式指定 limit 时无需计算语料总量，避免每次搜索都做一次全量聚合
+        const effectiveLimit = requestedLimit ?? this.searchCorpusSize(options.filters);
         const start = Date.now();
         const weights = this.retrievalWeights(options.weights);
+        // P1-10 检索语义澄清：generationMode=true 表示"生成场景检索"（文档正文生成链路调用），
+        // 该场景刻意跳过 LLM 查询重写——正文生成已占满 LLM 全局信号量，检索侧再触发 LLM 扩展会互相拖慢；
+        // 命名按"调用场景"而非"是否启用 LLM 重写"，因此 true 反而跳过重写。
         const rewrittenQueries = options.generationMode ? [query.trim()].filter(Boolean) : await this.rewriteQueries(query);
         const rankedLists = [];
         const keywordMultiplier = options.generationMode ? 2 : 3;
@@ -725,23 +742,65 @@ export class KnowledgeBaseManager {
     async llmExpandQueries(query) {
         if (!this.llmProvider)
             return [];
-        const prompt = `你是一个搜索查询优化器。用户输入了一个搜索查询，请生成 3-5 个不同的查询变体，用不同的措辞和同义词来表达相同的信息需求，以便在知识库中检索到更全面的结果。
+        // TTL 缓存 + 在途去重：生成流程会在短时间内对相近查询重复扩展，
+        // 缓存避免重复 LLM 调用；同一查询并发进入时复用同一 Promise
+        const cached = this.queryExpansionCache.get(query);
+        if (cached && cached.expiresAt > Date.now())
+            return cached.queries;
+        const inFlight = this.queryExpansionInFlight.get(query);
+        if (inFlight)
+            return inFlight;
+        const run = (async () => {
+            const release = await this.acquireQueryExpansionSlot();
+            try {
+                const prompt = `你是一个搜索查询优化器。用户输入了一个搜索查询，请生成 3-5 个不同的查询变体，用不同的措辞和同义词来表达相同的信息需求，以便在知识库中检索到更全面的结果。
 
 如果查询是中文，请同时生成英文变体；如果查询是英文，请同时生成中文变体。
 
 直接输出查询列表，每行一个，不要编号或其他文字。
 
 原始查询：${query}`;
-        const response = await this.llmProvider.chat([
-            { role: 'system', content: '你是一个精确的搜索查询扩展引擎。只输出查询列表。' },
-            { role: 'user', content: prompt },
-        ], { temperature: 0.3, maxTokens: 500 });
-        return response.content
-            .split('\n')
-            .map(line => line.replace(/^[-*\d.]+\s*/, '').trim())
-            .filter(line => line.length > 0 && line !== query)
-            .slice(0, 5);
+                const response = await this.llmProvider.chat([
+                    { role: 'system', content: '你是一个精确的搜索查询扩展引擎。只输出查询列表。' },
+                    { role: 'user', content: prompt },
+                ], { temperature: 0.3, maxTokens: 500 });
+                const queries = response.content
+                    .split('\n')
+                    .map(line => line.replace(/^[-*\d.]+\s*/, '').trim())
+                    .filter(line => line.length > 0 && line !== query)
+                    .slice(0, 5);
+                if (this.queryExpansionCache.size >= QUERY_EXPANSION_CACHE_MAX)
+                    this.queryExpansionCache.clear();
+                this.queryExpansionCache.set(query, { queries, expiresAt: Date.now() + QUERY_EXPANSION_TTL_MS });
+                return queries;
+            }
+            finally {
+                release();
+                this.queryExpansionInFlight.delete(query);
+            }
+        })();
+        this.queryExpansionInFlight.set(query, run);
+        return run;
+    }
+    /** 查询扩展 LLM 调用的简易信号量：与文档生成端的全局信号量解耦，避免扩展请求无界并发击穿模型端点 */
+    acquireQueryExpansionSlot() {
+        return new Promise(resolve => {
+            if (this.queryExpansionActive < QUERY_EXPANSION_MAX_CONCURRENCY) {
+                this.queryExpansionActive += 1;
+                resolve(this.releaseQueryExpansionSlot);
+            }
+            else {
+                this.queryExpansionWaiters.push(() => {
+                    this.queryExpansionActive += 1;
+                    resolve(this.releaseQueryExpansionSlot);
+                });
+            }
+        });
     }
+    releaseQueryExpansionSlot = () => {
+        this.queryExpansionActive = Math.max(0, this.queryExpansionActive - 1);
+        this.queryExpansionWaiters.shift()?.();
+    };
     retrievalWeights(overrides = {}) {
         return {
             keyword: overrides.keyword ?? Number(process.env.KB_RETRIEVAL_KEYWORD_WEIGHT ?? 1),
@@ -864,10 +923,15 @@ export class KnowledgeBaseManager {
         return [...new Set(labels)];
     }
     hydrateVectorResultsFromSqlite(items) {
+        // 批量按 rowid 取切片，避免对每条向量结果单发一次 SQL（N+1）
+        const rowids = [...new Set(items.filter(item => item.rowid).map(item => item.rowid))];
+        const chunksByRowid = new Map();
+        for (const chunk of this.store.getChunksByRowids(rowids))
+            chunksByRowid.set(chunk.rowid, chunk);
         return items.map(item => {
             if (!item.rowid)
                 return item;
-            const chunk = this.store.getChunkByRowid(item.rowid);
+            const chunk = chunksByRowid.get(item.rowid);
             if (!chunk)
                 return item;
             const hydrated = this.toFederatedItem({ ...chunk, score: item.score, scoreDetails: item.scoreDetails }, 'vector');
@@ -1093,6 +1157,18 @@ export class KnowledgeBaseManager {
     uploadSessionIsOpen(operationId) {
         return this.store.getMetadata(`upload_session:${operationId}`) === 'open';
     }
+    listOpenUploadSessions() {
+        this.initialize();
+        const prefix = 'upload_session:';
+        return this.store.listMetadataKeys(prefix)
+            .filter(key => this.store.getMetadata(key) === 'open')
+            .map(key => key.slice(prefix.length));
+    }
+    hasOpenUploadSessions() {
+        this.initialize();
+        const prefix = 'upload_session:';
+        return this.store.listMetadataKeys(prefix).some(key => this.store.getMetadata(key) === 'open');
+    }
     emptyDiff() {
         return { newFiles: [], modifiedFiles: [], deletedFiles: [], unchangedCount: 0, mtimeOnlyCount: 0, skippedFiles: [], hasChanges: false, diffTimeMs: 0 };
     }
@@ -1125,13 +1201,14 @@ export class KnowledgeBaseManager {
     }
     hasUsableContent(text, metadata) {
         const coverage = String(metadata.contentCoverage ?? '');
-        if (['metadata', 'metadata_filename', 'pdf_metadata_only', 'office_zip_empty_text', 'office_zip_failed'].includes(coverage))
+        if (['metadata', 'metadata_filename', 'pdf_metadata_only', 'office_zip_empty_text', 'office_zip_failed', 'cad_no_extractable_text'].includes(coverage))
             return false;
         return text.trim().length > 0;
     }
     isMetadataOnlyNonBlocking(file, metadata) {
         const coverage = String(metadata.contentCoverage ?? '');
-        return file.category === 'image' && ['image_too_small_for_ocr', 'ocr_no_text'].includes(coverage);
+        return (file.category === 'image' && ['image_too_small_for_ocr', 'ocr_no_text'].includes(coverage))
+            || (file.category === 'cad' && coverage === 'cad_no_extractable_text');
     }
     defaultUploadRelativePath(fileName) {
         const classification = this.classifier.classifyVirtual(fileName);

package/dist/core/multi-project-manager.js

@@ -35,7 +35,7 @@ export class MultiProjectManager {
             scope: 'project',
             projectRoot: resolvedRoot,
             projectId,
-            kbPath: getProjectKbPath(resolvedRoot),
+            kbPath: getProjectKbPath(resolvedRoot, this.storageRoot),
             storageRoot: this.storageRoot,
             llmProvider: this.llmProvider,
         });
@@ -106,7 +106,7 @@ export class MultiProjectManager {
                 scope: 'project',
                 projectRoot: project.projectRoot,
                 projectId: project.projectId,
-                kbPath: project.kbPath,
+                kbPath: getProjectKbPath(project.projectRoot, this.storageRoot),
                 storageRoot: this.storageRoot,
                 llmProvider: this.llmProvider,
             });

package/dist/core/project-config.d.ts

@@ -1,8 +1,8 @@
 import type { ProjectConfig } from '../types.js';
 /** 获取项目配置文件路径 */
 export declare function getProjectConfigPath(projectRoot: string, storageRoot?: string): string;
-/** 获取项目知识库目录路径 */
-export declare function getProjectKbPath(projectRoot: string): string;
+/** 获取项目知识库落盘目录路径（用户数据目录下，与 kb.db 索引同生命周期，不再落在项目根目录） */
+export declare function getProjectKbPath(projectRoot: string, storageRoot?: string): string;
 /** 确保项目存在 CUSTOMIZE.md 文件（如不存在则创建默认模板） */
 export declare function ensureProjectCustomizeFile(projectRoot: string): void;
 /** 项目配置管理器，负责加载和保存项目配置 */

package/dist/core/project-config.js

@@ -8,9 +8,10 @@ export function getProjectConfigPath(projectRoot, storageRoot = path.join(os.hom
     const projectId = computeProjectId(projectRoot);
     return path.join(storageRoot, 'projects', projectId, 'project.json');
 }
-/** 获取项目知识库目录路径 */
-export function getProjectKbPath(projectRoot) {
-    return path.join(projectRoot, KNOWLEDGE_BASE_DIR);
+/** 获取项目知识库落盘目录路径（用户数据目录下，与 kb.db 索引同生命周期，不再落在项目根目录） */
+export function getProjectKbPath(projectRoot, storageRoot = path.join(os.homedir(), USER_DATA_DIR)) {
+    const projectId = computeProjectId(projectRoot);
+    return path.join(storageRoot, 'projects', projectId, KNOWLEDGE_BASE_DIR);
 }
 const DEFAULT_CUSTOMIZE_MD = `# Customize Agent 配置示例
 

package/dist/core/project-registry.js

@@ -8,6 +8,8 @@ export class ProjectRegistry {
         fs.mkdirSync(path.dirname(dbPath), { recursive: true });
         this.db = new Database(dbPath);
         this.db.pragma('journal_mode = WAL');
+        // P1-8 SQLite 并发读加固：显式 busy_timeout，registry.db 并发读写竞争由等待兜底而非立即抛锁
+        this.db.pragma('busy_timeout = 10000');
         this.initTables();
     }
     upsert(project) {

package/dist/extraction/content-extractor.d.ts

@@ -17,6 +17,8 @@ export declare class ContentExtractor {
     private isReadableCadValue;
     private cleanExtractedText;
     private textScore;
+    /** 统计图纸提取片段中的实际字符数据量（汉字/字母/数字），用于判断"无字符数据不入库" */
+    private countCadCharacterData;
     private extractCad;
     private extractDxf;
     private buildCadSemanticNodes;

package/dist/extraction/content-extractor.js

@@ -5,9 +5,15 @@ import { tmpdir } from 'node:os';
 import { fileURLToPath, pathToFileURL } from 'node:url';
 import { resolveAndImport, resolvePackage } from './module-resolver.js';
 import { createOcrProvider } from './ocr-providers.js';
-const CAD_INTERNAL_TOKEN_RE = /\b(?:TDbPipe|TDbPipeValve|TDbPipeFitting|TDbWellh|AcDb\w+|Dwg\w+|ObjectId|Handle|ByLayer|Continuous|Model|Layout\d*)\b/giu;
-const CAD_INTERNAL_LINE_RE = /^(?:TDb\w+|AcDb\w+|[A-F0-9]{8,}|\d+|Model|Layout\d*|ByLayer|Continuous)$/iu;
-const CAD_DOMAIN_SIGNAL_RE = /工程|项目|施工|建筑|结构|装饰|电气|给排水|消防|暖通|平面|立面|剖面|节点|详图|材料|尺寸|标高|轴线|图层|门窗|墙|地面|顶面|照明|配电|弱电|空调|卫生间|楼梯|屋面|基础|柱|梁|板|图号|设计|说明/u;
+const CAD_INTERNAL_TOKEN_RE = /\b(?:TDbPipe|TDbPipeValve|TDbPipeFitting|TDbWellh|AcDb[\w:]+|Dwg\w+|ObjectId|Handle|ByLayer|Continuous|Model|Layout\d*|MLEADERSTYLE|AppInfoHistory|AppInfoDataList|ObjectDBX|Classes|DICTIONARYVARP|ObjFreeSpaceP|AuxHeaderT|\$AUDIT_BAD_\w+)\b/giu;
+const CAD_INTERNAL_LINE_RE = /^(?:TDb\w+|AcDb[\w:]+|\$AUDIT_BAD_\w+|[A-F0-9]{8,}|\d+|Model|Layout\d*|ByLayer|Continuous|MLEADERSTYLE|ObjectDBX)$/iu;
+/** DWG 二进制误读产生的 C1 控制字符（U+0080-U+009F，如 GBK 半字节），正常图纸标注不会出现 */
+const CAD_C1_CONTROL_RE = /[\u0080-\u009F]/gu;
+/** AutoCAD 控制码：%%c=Φ、%%d=°、%%p=±、%%132 等数字码=Φ，统一解码为可读符号 */
+const CAD_CONTROL_CODE_RE = /%%(?:c|d|p|\d{2,3})/giu;
+const CAD_DOMAIN_SIGNAL_RE = /工程|项目|施工|建筑|结构|装饰|电气|给排水|消防|暖通|平面|立面|剖面|节点|详图|材料|尺寸|标高|轴线|图层|门窗|墙|地面|顶面|照明|配电|弱电|空调|卫生间|楼梯|屋面|基础|柱|梁|板|图号|设计|说明|轴|电|井|土|夯/u;
+/** 图纸兜底解析可读字符（汉字/字母/数字）的最低总量，低于该值视为无字符数据，不入库 */
+const MIN_CAD_CHARACTER_DATA = 32;
 const OCR_NATIVE_NOISE_PATTERNS = [/^Image too small to scale!!/u, /^Line cannot be recognized!!$/u];
 /** 文件内容提取器，支持文档、表格、图片、CAD 等多种文件格式的内容抽取 */
 export class ContentExtractor {
@@ -142,6 +148,8 @@ export class ContentExtractor {
     }
     cleanCadReadableText(value) {
         return value
+            .replace(CAD_C1_CONTROL_RE, ' ')
+            .replace(CAD_CONTROL_CODE_RE, code => (code.toLowerCase() === '%%d' ? '°' : code.toLowerCase() === '%%p' ? '±' : 'Φ'))
             .replace(CAD_INTERNAL_TOKEN_RE, '')
             .replace(/\b(?:LINE|LWPOLYLINE|POLYLINE|INSERT|HATCH|CIRCLE|ARC|DIMENSION|TEXT|MTEXT)\b/giu, '')
             .replace(/\s+/gu, ' ')
@@ -162,6 +170,13 @@ export class ContentExtractor {
         const hasDomainSignal = CAD_DOMAIN_SIGNAL_RE.test(compact);
         const hasCommonTextShape = /[，。；：、,.\-/()（）]|\d+(?:\.\d+)?\s*(?:mm|cm|m|㎡|%|°)?/iu.test(compact);
         const latinVowelCount = chars.filter(char => /[aAeEiIoOuU]/u.test(char)).length;
+        // 替换符（U+FFFD）：解码失败的标志，正常标注不会出现
+        if (chars.includes('\uFFFD'))
+            return true;
+        // 罕见符号（箭头补充、CJK 部首、杂项数学/圈符/地图符号）：二进制误读产物，
+        // 正常图纸标注只用常用标点与工程符号
+        if (/[\u2046-\u205F\u2070-\u209F\u2100-\u2102\u2104-\u214F\u21B0-\u21FF\u2270-\u22FF\u2400-\u243F\u249C-\u24FF\u2640-\u26FF\u27C0-\u27EF\u2900-\u297F\u2A00-\u2AFF\u2B00-\u2BFF\u2E00-\u2FFF\u3200-\u33FF]/u.test(compact))
+            return true;
         if (readableRatio < 0.6)
             return true;
         if (symbolRatio > 0.35 && !hasDomainSignal)
@@ -170,6 +185,96 @@ export class ContentExtractor {
             return true;
         if (cjk >= 8 && digits === 0 && !hasDomainSignal && !hasCommonTextShape)
             return true;
+        // 短行内汉字-Latin-汉字交叉混排（考堂f肀、渱潑喲W晀耀）：二进制误读的典型形态；
+        // 正常标注的字母编号在汉字前或后（JD 电井、AB轴），不会夹在汉字中间
+        if (chars.length <= 8 && cjk >= 2 && latin >= 1 && digits === 0 && !hasDomainSignal && /[\p{Script=Han}][\p{Script=Latin}][\p{Script=Han}]/u.test(compact))
+            return true;
+        // 纯 Latin 行含 Latin-1 扩展字符（VdA«UdA«UdANÒg、dAç dA+ dA«）：正常英文标注不用扩展字符
+        if (cjk === 0 && digits === 0 && latin >= 8 && /[\u00A0-\u02AF\u1E00-\u1EFF]/u.test(compact))
+            return true;
+        // 超长无句读行：二进制误读产生的长连续乱码（常混入个别汉字/数字触发域信号豁免，
+        // 因此只认中文句读，数字/单位不再豁免）
+        if (chars.length > 400 && !/[\u3002\uFF0C\uFF1B\uFF1A\u3001、，。；：]/.test(compact))
+            return true;
+        // 行内短片段周期性重复（Ml+Ml+Ml、AM~AM~BM~BM、M|¶M|¶、2dA+2dA+2dA）：
+        // 正常标注不会让同一 2-4 字符片段在一行内重复出现，二进制误读则产生大量循环模式
+        const shortTokens = compact.split(/[^\p{L}\p{N}]+/u).filter(token => token.length >= 1 && token.length <= 4);
+        if (shortTokens.length >= 3 && chars.length >= 8 && !hasDomainSignal) {
+            const tokenFreq = new Map();
+            for (const token of shortTokens)
+                tokenFreq.set(token, (tokenFreq.get(token) ?? 0) + 1);
+            let repeatedChars = 0;
+            for (const [token, count] of tokenFreq) {
+                if (count >= 2)
+                    repeatedChars += token.length * count;
+            }
+            if (repeatedChars / Math.max(1, shortTokens.join('').length) >= 0.4)
+                return true;
+        }
+        // 短行内同一汉字高频重复（摁䭚摁譚摁譚摁、耀U耀W耀Y耀）：正常标注不会在
+        // 14 字符以内的行里让重复汉字占比超过 60%
+        const hanChars = chars.filter(char => /[\p{Script=Han}]/u.test(char));
+        if (hanChars.length >= 4 && chars.length <= 14) {
+            const hanFreq = new Map();
+            for (const char of hanChars)
+                hanFreq.set(char, (hanFreq.get(char) ?? 0) + 1);
+            const repeatedHan = hanChars.filter(char => (hanFreq.get(char) ?? 0) >= 2).length;
+            if (repeatedHan / hanChars.length >= 0.6)
+                return true;
+        }
+        // Latin-1 扩展字符（¡-ÿ 区）密集行：中文图纸标注几乎不用这些字符，
+        // 二进制误读（GBK/CP1252 混读）会批量产生
+        const latinExtended = chars.filter(char => /[\u00A0-\u02AF\u1E00-\u1EFF]/u.test(char)).length;
+        if (latinExtended >= 3 && (latinExtended / chars.length >= 0.3 || latin / Math.max(1, chars.length) >= 0.6))
+            return true;
+        // 纯 Latin-1 扩展字母短行（无 ASCII 字母/数字）：GBK 中文标注被 Latin-1 误读的
+        // 典型产物（"上"→ÉÏ、"柜"→¹ñ），正常标注的英文是 ASCII、中文是汉字，
+        // 不会出现整行全由扩展拉丁字母构成的短行
+        if (cjk === 0 && digits === 0 && latin >= 2 && latinExtended === latin && chars.length <= 12)
+            return true;
+        // GBK 误读标点/字母混入 ASCII 标注（"1APz:P4~P6"→1APz£ºP4~P6、"消防控制"→Ïû·À¿ØÖÆ）：
+        // 正常工程标注只使用 °±×÷·µ²³Ø 等少数 Latin-1 字符，
+        // 无汉字行中出现 2 个以上其他 Latin-1 字符即判定为 GBK 编码误读
+        const gbkMisreadChars = chars.filter(char => /[\u00A0-\u00FF]/u.test(char) && !'°±×÷·µ²³Ø'.includes(char)).length;
+        if (gbkMisreadChars >= 2 && cjk === 0)
+            return true;
+        // 分数符号/上标数字（¼½¾¹）：中文工程图纸标注几乎不用（仅 ²³ 常见保留），
+        // 出现在标注中基本是 GBK 误读（门宽 FM×1524 误读为 FM¼×1524）
+        if (/[¹¼½¾]/u.test(compact) && cjk === 0)
+            return true;
+        // 无空格的超长 Latin 字母串（≥16 字符）：正常标注是词/编号，不会出现连续长字母串
+        if (/[\p{Script=Latin}\u00C0-\u024F]{16,}/u.test(compact))
+            return true;
+        // GUID：DWG 内部结构标识，不是图纸字符数据
+        if (/[0-9A-Fa-f]{8}-[0-9A-Fa-f]{4}-[0-9A-Fa-f]{4}-[0-9A-Fa-f]{4}-[0-9A-Fa-f]{12}/u.test(compact))
+            return true;
+        // 单汉字高频重复：正常标注/文本不会让同一汉字占比超过 20%（如乱码行中
+        // 生僻字“罍”重复 400+ 次仍被 readableRatio 计为可读字符而漏网）
+        const charCounts = new Map();
+        for (const char of chars)
+            charCounts.set(char, (charCounts.get(char) ?? 0) + 1);
+        let mostCommon = '';
+        let mostCommonCount = 0;
+        for (const [char, count] of charCounts) {
+            if (count > mostCommonCount) {
+                mostCommon = char;
+                mostCommonCount = count;
+            }
+        }
+        if (mostCommonCount >= 5 && mostCommonCount / chars.length > 0.2 && /[\p{Script=Han}]/u.test(mostCommon))
+            return true;
+        // CJK 扩展区生僻字（Ext A/B 等）混排：正常图纸标注几乎只用常用字（基本区
+        // U+4E00-U+9FFF），二进制误读会批量产生 U+3400-U+4DBF 等扩展区字符
+        const rareCjk = chars.filter(char => /[\u3400-\u4DBF\u{20000}-\u{2FA1F}]/u.test(char)).length;
+        if (rareCjk >= 2 && rareCjk / chars.length >= 0.1)
+            return true;
+        if (rareCjk >= 1 && rareCjk / chars.length >= 0.2)
+            return true;
+        // 非中/英/希字母脚本混排（韩文、藏文、彝文、泰文等）：中文标注行内混入
+        // 其他文字系统字母是二进制误读的典型产物（希腊字母 ΦφΩ 在图纸中常见，豁免）
+        const foreignLetter = chars.filter(char => /\p{Letter}/u.test(char) && !/[\p{Script=Han}\p{Script=Latin}\p{Script=Greek}]/u.test(char)).length;
+        if (foreignLetter >= 1 && cjk > 0)
+            return true;
         return false;
     }
     isReadableCadValue(value) {
@@ -180,7 +285,8 @@ export class ContentExtractor {
         const normalized = [...value]
             .filter(char => {
             const code = char.charCodeAt(0);
-            return code === 9 || code === 10 || code === 13 || code >= 32;
+            // U+FFFF 非字符：PDF 表单空白下划线/占位符的提取产物，无检索意义，统一剔除
+            return code !== 0xFFFF && (code === 9 || code === 10 || code === 13 || code >= 32);
         })
             .join('');
         if (file.category !== 'cad')
@@ -197,6 +303,10 @@ export class ContentExtractor {
         const alnum = (value.match(/[\p{L}\p{N}]/gu) ?? []).length;
         return cjk * 4 + alnum + Math.min(value.length, 200) / 20;
     }
+    /** 统计图纸提取片段中的实际字符数据量（汉字/字母/数字），用于判断"无字符数据不入库" */
+    countCadCharacterData(fragments) {
+        return (fragments.join('').match(/[\p{Script=Han}\p{L}\p{N}]/gu) ?? []).length;
+    }
     async extractCad(file) {
         const metadata = { extractionMode: 'builtin_cad_structural', vectorizable: true, preferredExtractionMode: 'dwg_to_dxf_semantic' };
         const warnings = [];
@@ -228,7 +338,16 @@ export class ContentExtractor {
             metadata.blockNames = uniqueBlocks.slice(0, 80);
             metadata.entityTypeCount = uniqueEntityTypes.length;
             metadata.entityTypes = uniqueEntityTypes.slice(0, 80);
+            const characterDataCount = this.countCadCharacterData([...textEntities.map(annotation => annotation.text), ...uniqueLayers, ...uniqueBlocks]);
+            if (characterDataCount < MIN_CAD_CHARACTER_DATA) {
+                // 图纸无字符数据（无文字标注、图层/块名均为内部默认值），不入库
+                metadata.contentCoverage = 'cad_no_extractable_text';
+                metadata.characterDataCount = characterDataCount;
+                warnings.push(`${file.format} DXF 未提取到字符数据（仅 ${characterDataCount} 个可读字符），图纸内容未入库`);
+                return { text: this.metadataOnlyText(file), metadata, warnings };
+            }
             metadata.contentCoverage = 'dxf_semantic_layer_block_annotations';
+            metadata.characterDataCount = characterDataCount;
             const semanticNodes = this.buildCadSemanticNodes(file, uniqueLayers, uniqueBlocks, uniqueEntityTypes, textEntities);
             return {
                 text: [
@@ -291,21 +410,59 @@ export class ContentExtractor {
                 return result;
         }
         const binaryFragments = this.extractBinaryReadableFragments(file.absolutePath);
-        const readable = binaryFragments.filter(value => this.isReadableCadValue(value)).slice(0, 5000);
+        // OLE 属性集（<prop_set ...>）是 DWG 文件内部的二进制属性结构，不含图纸标注字符，
+        // 属于解析噪声而非字符数据，直接排除（不锚定行首：误读字符可能混在片段开头）
+        const withoutPropSets = binaryFragments.filter(value => !/<prop_set\b/u.test(value));
+        let readable = withoutPropSets.filter(value => this.isReadableCadValue(value)).slice(0, 5000);
+        // 文档级字符词频过滤：真实标注文字在图纸中会重复出现（标题/图层/图名等），
+        // 随机二进制噪声片段中每个字符几乎只出现一次（孤立字符）；短片段若全部由
+        // 孤立字符构成即为随机噪声，丢弃
+        const charFreq = new Map();
+        for (const value of readable) {
+            for (const char of value)
+                charFreq.set(char, (charFreq.get(char) ?? 0) + 1);
+        }
+        const isolatedNoise = (value) => {
+            if (CAD_DOMAIN_SIGNAL_RE.test(value))
+                return false;
+            const letters = [...value].filter(char => /[\p{L}\p{N}]/u.test(char));
+            if (letters.length > 8)
+                return false;
+            const freqs = letters.map(char => charFreq.get(char) ?? 1);
+            // 短片段中 60% 以上字符在全文只出现一次 → 随机噪声（真实标注文字会重复出现）
+            const isolatedCount = freqs.filter(freq => freq <= 1).length;
+            return isolatedCount / Math.max(1, letters.length) >= 0.6;
+        };
+        readable = readable.filter(value => !isolatedNoise(value));
+        // 可信片段过滤：真实图纸标注至少含 3 个汉字（图名/说明/材料文字）或含域信号词，
+        // 且全部字符落在图纸常用字符白名单内（汉字/ASCII 字母数字/常用标点/工程符号）；
+        // 二进制误读碎片常含 Latin 扩展字母、罕见符号或纯字母数字串，白名单直接排除
+        const trustedCadFragment = (value) => {
+            const hanCount = (value.match(/\p{Script=Han}/gu) ?? []).length;
+            if (hanCount < 3 && !CAD_DOMAIN_SIGNAL_RE.test(value))
+                return false;
+            return !/[^\p{Script=Han}A-Za-z0-9\s\u3000-\u303F\uFF01-\uFF5E\u2460-\u2473\u2160-\u2179°Φφ×±≤≥∠√℃‰※′″〇●○◆■□▲△★☆◇→←↑↓ΩΔαβγθλμω]/u.test(value);
+        };
+        readable = readable.filter(trustedCadFragment);
         const filteredCount = Math.max(0, binaryFragments.length - readable.length);
+        // 图纸"字符数据"= 提取到的标注/标题块中实际可读的文字（汉字/字母/数字）总量；
+        // 低于最低阈值视为无字符数据，不入库
+        const characterDataCount = this.countCadCharacterData(readable);
+        const hasCharacterData = characterDataCount >= MIN_CAD_CHARACTER_DATA;
         metadata.extractionMode = 'builtin_cad_readable_fragments';
         metadata.professionalConversionUsed = false;
-        metadata.contentCoverage = readable.length > 0 ? 'cad_readable_text_fragments_filtered' : 'metadata';
-        metadata.contentConfidence = readable.length > 0 ? 'low_fallback_filtered' : 'metadata_only';
+        metadata.contentCoverage = hasCharacterData ? 'cad_readable_text_fragments_filtered' : 'cad_no_extractable_text';
+        metadata.contentConfidence = hasCharacterData ? 'low_fallback_filtered' : 'metadata_only';
         metadata.stringCandidateCount = binaryFragments.length;
         metadata.stringCount = readable.length;
+        metadata.characterDataCount = characterDataCount;
         metadata.filteredGarbledStringCount = filteredCount;
-        if (readable.length === 0)
-            warnings.push(`${file.format} 内置 CAD 解析器未提取到可用文本，仅记录文件元数据，未生成可检索正文切片`);
+        if (!hasCharacterData)
+            warnings.push(`${file.format} 内置 CAD 解析器未提取到字符数据（仅 ${characterDataCount} 个可读字符），图纸内容未入库`);
         else
             warnings.push(`${file.format} 内置 DWG→DXF 转换未成功，已使用低置信度可读标注/标题块兜底抽取并过滤疑似乱码 ${filteredCount} 条；该结果仅作为兜底证据，不应等同于完整图层、块、标注和尺寸语义解析`);
         return {
-            text: readable.length > 0 ? [this.metadataOnlyText(file), `CAD 图纸可读标注/标题块/属性:\n${readable.join('\n')}`].join('\n') : this.metadataOnlyText(file),
+            text: hasCharacterData ? [this.metadataOnlyText(file), `CAD 图纸可读标注/标题块/属性:\n${readable.join('\n')}`].join('\n') : this.metadataOnlyText(file),
             metadata,
             warnings,
         };
@@ -335,8 +492,17 @@ export class ContentExtractor {
         metadata.blockNames = uniqueBlocks.slice(0, 80);
         metadata.entityTypeCount = uniqueEntityTypes.length;
         metadata.entityTypes = uniqueEntityTypes.slice(0, 80);
-        metadata.contentCoverage = 'dxf_semantic_layer_block_annotations';
         metadata.parsedByDxfParser = Boolean(parsed);
+        const characterDataCount = this.countCadCharacterData([...textEntities.map(annotation => annotation.text), ...uniqueLayers, ...uniqueBlocks]);
+        if (characterDataCount < MIN_CAD_CHARACTER_DATA) {
+            // 图纸无字符数据（无文字标注、图层/块名均为内部默认值），不入库
+            metadata.contentCoverage = 'cad_no_extractable_text';
+            metadata.characterDataCount = characterDataCount;
+            warnings.push(`${file.format} DXF 未提取到字符数据（仅 ${characterDataCount} 个可读字符），图纸内容未入库`);
+            return { text: this.metadataOnlyText(file), metadata, warnings };
+        }
+        metadata.contentCoverage = 'dxf_semantic_layer_block_annotations';
+        metadata.characterDataCount = characterDataCount;
         const semanticNodes = this.buildCadSemanticNodes(file, uniqueLayers, uniqueBlocks, uniqueEntityTypes, textEntities);
         return {
             text: [
@@ -373,10 +539,14 @@ export class ContentExtractor {
             const text = this.cleanCadReadableText(/(?:^|\r?\n)\s*(?:1|3)\s*\r?\n([^\r\n]+)/u.exec(section)?.[1] ?? '');
             if (!text || !this.isReadableCadValue(text))
                 return [];
+            // 图层/块名同样要过可读性过滤：DXF 里 GBK 误读（Ïä¹ñ）或纯数字/内部
+            // 标识（11、AcDb...）会直接混进节点文本，不合格时置空由语义节点回退
+            const layer = /(?:^|\r?\n)\s*8\s*\r?\n([^\r\n]+)/u.exec(section)?.[1]?.trim() ?? '';
+            const block = /(?:^|\r?\n)\s*2\s*\r?\n([^\r\n]+)/u.exec(section)?.[1]?.trim() ?? '';
             return [{
                     text,
-                    layer: /(?:^|\r?\n)\s*8\s*\r?\n([^\r\n]+)/u.exec(section)?.[1]?.trim(),
-                    block: /(?:^|\r?\n)\s*2\s*\r?\n([^\r\n]+)/u.exec(section)?.[1]?.trim(),
+                    layer: layer && this.isReadableCadValue(layer) ? layer : undefined,
+                    block: block && this.isReadableCadValue(block) ? block : undefined,
                     entityType: section.trim().split(/\s+/u)[0],
                     x: Number(/(?:^|\r?\n)\s*10\s*\r?\n([^\r\n]+)/u.exec(section)?.[1]),
                     y: Number(/(?:^|\r?\n)\s*20\s*\r?\n([^\r\n]+)/u.exec(section)?.[1]),
@@ -406,25 +576,42 @@ export class ContentExtractor {
             if (!mod.convertDwgToDxf)
                 return { tool: 'dwgdxf_wasm', warnings: ['内置 dwgdxf WASM 转换器未导出 convertDwgToDxf'] };
             const dwgBytes = fs.readFileSync(filePath);
-            const attempts = [
-                { label: 'package-default' },
-                { label: 'package-dist-wasm', options: { wasmBase: pathToFileURL(path.join(path.dirname(resolvePackage('dwgdxf')), 'wasm')).href } },
-                { label: 'package-root-dist-wasm', options: { wasmBase: pathToFileURL(path.join(path.dirname(path.dirname(resolvePackage('dwgdxf'))), 'wasm')).href } },
-            ];
-            const failures = [];
-            for (const attempt of attempts) {
-                try {
-                    const dxfBytes = await mod.convertDwgToDxf(dwgBytes, attempt.options);
-                    const dxfText = Buffer.from(dxfBytes).toString('utf8');
-                    if (dxfText.trim())
-                        return { dxfText, tool: `dwgdxf_wasm:${attempt.label}`, warnings: [] };
-                    failures.push(`${attempt.label}: 未输出 DXF 文本`);
+            // 注意：dwgdxf 内部对 WASM 基础 URL 有模块级缓存，只有首次调用传入的
+            // wasmBase 才会生效。若首次调用不带 wasmBase，会走到包内硬编码的构建机
+            // 路径（file:///home/runner/work/...）并永久缓存失败结果，后续重试全部
+            // 复用同一失败 Promise。因此第一次调用就必须传本地包内 wasm 目录的
+            // 正确 file:// URL，不允许再回退重试（重试无效且会污染缓存）。
+            let wasmBase;
+            try {
+                const localWasmDir = path.join(path.dirname(resolvePackage('dwgdxf')), 'wasm');
+                if (fs.existsSync(path.join(localWasmDir, 'dwgdxf_bg.wasm'))) {
+                    wasmBase = pathToFileURL(localWasmDir).href;
                 }
-                catch (error) {
-                    failures.push(`${attempt.label}: ${error instanceof Error ? error.message : String(error)}`);
+            }
+            catch { /* 包解析失败时回退到包内默认路径（大概率也会失败，但由下方 catch 统一记录） */ }
+            try {
+                const dxfBytes = await mod.convertDwgToDxf(dwgBytes, wasmBase ? { wasmBase } : undefined);
+                const dxfText = Buffer.from(dxfBytes).toString('utf8');
+                if (dxfText.trim())
+                    return { dxfText, tool: wasmBase ? 'dwgdxf_wasm:local_wasm' : 'dwgdxf_wasm:package_default', warnings: [] };
+                return { tool: 'dwgdxf_wasm', warnings: ['内置 dwgdxf WASM 未输出 DXF 文本'] };
+            }
+            catch (error) {
+                const detail = error instanceof Error ? error.message : String(error);
+                // unreachable 多为 WASM 内存压力下的瞬时失败（批量索引时主进程同时持有
+                // 大型 SQLite 缓存会挤压可用内存），换一个内存状态重试一次；格式类错误
+                // （Invalid file format 等）重试无意义，直接失败降级。
+                if (detail.includes('unreachable')) {
+                    try {
+                        const retryBytes = await mod.convertDwgToDxf(dwgBytes, wasmBase ? { wasmBase } : undefined);
+                        const retryText = Buffer.from(retryBytes).toString('utf8');
+                        if (retryText.trim())
+                            return { dxfText: retryText, tool: wasmBase ? 'dwgdxf_wasm:local_wasm' : 'dwgdxf_wasm:package_default', warnings: ['内置 dwgdxf WASM 首次转换失败（unreachable），重试成功'] };
+                    }
+                    catch { /* 重试仍失败，按原错误降级 */ }
                 }
+                return { tool: 'dwgdxf_wasm', warnings: [`内置 dwgdxf WASM 转换失败${wasmBase ? '' : '（未找到本地 WASM 文件，使用了包内默认路径）'}: ${detail}`] };
             }
-            return { tool: 'dwgdxf_wasm', warnings: [`内置 dwgdxf WASM 转换失败: ${failures.join('；')}`] };
         }
         catch (error) {
             return { tool: 'dwgdxf_wasm', warnings: [`内置 dwgdxf WASM 加载失败: ${error instanceof Error ? error.message : String(error)}`] };
@@ -776,12 +963,20 @@ export class ContentExtractor {
         return fallback;
     }
     extractLegacyOfficeBinary(file) {
-        const strings = this.extractBinaryStrings(file.absolutePath).slice(0, 1_000);
+        const candidates = this.extractBinaryStrings(file.absolutePath).slice(0, 1_000);
+        // 二进制兜底提取出的字符串中混有大量误读乱码（如 OLE 复合文档中 UTF-16LE
+        // 中文被 latin1/utf8 误读产生的长串生僻字），复用 CAD 乱码判定规则过滤，
+        // 避免乱码直接入库污染检索与预览。
+        const strings = candidates.filter(value => !this.isLikelyGarbledCadText(value));
+        const filteredCount = candidates.length - strings.length;
         const text = strings.join('\n').trim();
         return {
             text,
-            metadata: { extractionMode: 'builtin_legacy_office_binary_strings', vectorizable: true, contentCoverage: 'legacy_office_binary_strings', stringCount: strings.length },
-            warnings: text ? [] : ['旧版 Office 二进制文件未提取到正文，未入库'],
+            metadata: { extractionMode: 'builtin_legacy_office_binary_strings', vectorizable: true, contentCoverage: 'legacy_office_binary_strings_filtered', stringCandidateCount: candidates.length, stringCount: strings.length, filteredGarbledStringCount: filteredCount },
+            warnings: [
+                ...(filteredCount > 0 ? [`已过滤疑似乱码字符串 ${filteredCount} 条`] : []),
+                ...(text ? [] : ['旧版 Office 二进制文件未提取到正文，未入库']),
+            ],
         };
     }
     extractLegacyOfficeBinaryWithWarnings(file, warnings) {

package/dist/index.d.ts

@@ -9,6 +9,7 @@ export { ChangeTracker } from './core/change-tracker.js';
 export { KnowledgeFileScanner, type DiskFileStat } from './core/file-scanner.js';
 export { IndexStateStore, type ChunkSearchResult, type FileHashRecord, type FileRelationship, type StoredChunk } from './core/index-state-store.js';
 export { KnowledgeBaseManager, type KnowledgeBaseManagerOptions, type KnowledgeIndexProgress } from './core/knowledge-base-manager.js';
+export { runIndexLoop, type IndexRunJob, type IndexRunOutcome } from './core/index-runner.js';
 export { MultiProjectManager } from './core/multi-project-manager.js';
 export { computeProjectId } from './core/project-id.js';
 export { ensureProjectCustomizeFile, getProjectConfigPath, getProjectKbPath, ProjectConfigManager } from './core/project-config.js';

package/dist/index.js

@@ -11,6 +11,7 @@ export { ChangeTracker } from './core/change-tracker.js';
 export { KnowledgeFileScanner } from './core/file-scanner.js';
 export { IndexStateStore } from './core/index-state-store.js';
 export { KnowledgeBaseManager } from './core/knowledge-base-manager.js';
+export { runIndexLoop } from './core/index-runner.js';
 export { MultiProjectManager } from './core/multi-project-manager.js';
 export { computeProjectId } from './core/project-id.js';
 export { ensureProjectCustomizeFile, getProjectConfigPath, getProjectKbPath, ProjectConfigManager } from './core/project-config.js';

package/dist/llm/llm-search-provider.d.ts

@@ -3,6 +3,11 @@
  *
  * 定义在 knowledge 包内部，避免直接依赖 @customize-agent/llm。
  * CLI 层的 ILLMProvider 在结构上兼容此接口，可直接传入。
+ *
+ * 接入状态（P1-10 检索语义澄清）：当前未接入。
+ * apps/server 的 getMultiProjectManager() 刻意不注入 llmProvider（见 kbService.ts），
+ * 检索查询重写因此退化为本地规则扩展；若未来启用，需配独立低并发 LLM 通道，
+ * 避免与文档正文生成争抢全局 LLM 信号量。
  */
 export interface LLMChatMessage {
     role: 'system' | 'user' | 'assistant';

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@customize-agent/knowledge",
-  "version": "4.0.42",
+  "version": "4.0.44",
   "description": "Local knowledge base infrastructure for customize-agent",
   "type": "module",
   "main": "./dist/index.js",
@@ -12,14 +12,6 @@
       "default": "./dist/index.js"
     }
   },
-  "scripts": {
-    "prebuild": "node -e \"require('node:fs').rmSync('dist',{recursive:true,force:true})\"",
-    "build": "tsc",
-    "typecheck": "tsc --noEmit",
-    "lint": "eslint src/",
-    "postinstall": "node scripts/install-hnsw.cjs",
-    "doctor:hnsw": "node scripts/install-hnsw.cjs"
-  },
   "license": "MIT",
   "engines": {
     "node": ">=20.19.0"
@@ -70,5 +62,13 @@
   "devDependencies": {
     "@types/better-sqlite3": "^7.6.13",
     "@types/node": "^25.9.3"
+  },
+  "scripts": {
+    "prebuild": "node -e \"require('node:fs').rmSync('dist',{recursive:true,force:true})\"",
+    "build": "tsc",
+    "typecheck": "tsc --noEmit",
+    "lint": "eslint src/",
+    "postinstall": "node scripts/install-hnsw.cjs",
+    "doctor:hnsw": "node scripts/install-hnsw.cjs"
   }
-}
+}