@customize-agent/knowledge 4.0.41 → 4.0.43

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 };
     }

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/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.41",
+  "version": "4.0.43",
   "description": "Local knowledge base infrastructure for customize-agent",
   "type": "module",
   "main": "./dist/index.js",