/**
 * RAG Engine — 轻量级检索增强生成
 *
 * 设计目标：不引入向量数据库，用规则分块 + 关键词匹配实现文档检索
 * 适用场景：SpecCore CLI 在构建 Prompt 时，从长文档中提取最相关的片段
 *
 * 流程：
 *   分析阶段: 读取文档 → 按标题分块 → 提取摘要/关键词 → 存入 rag-index.json
 *   执行阶段: 根据 task/需求关键词 → 检索相关块 → 按分数排序 → 组装进 Prompt
 */
export interface DocumentChunk {
    /** 唯一标识: hash(文件路径 + 标题) */
    id: string;
    /** 源文件路径 */
    filePath: string;
    /** 源文件名称 */
    fileName: string;
    /** 块标题 */
    title: string;
    /** 标题级别 (2=##, 3=###, 4=####) */
    level: number;
    /** 块原始内容 */
    content: string;
    /** 自动提取的摘要 */
    summary: string;
    /** 关键词标签 */
    keywords: string[];
    /** 字数 */
    charCount: number;
    /** 起始行号（1-based，用于精确读取） */
    startLine?: number;
    /** 结束行号（1-based，含） */
    endLine?: number;
    /** 相关性分数（检索时动态计算） */
    relevanceScore?: number;
}
export interface RagIndex {
    version: string;
    updatedAt: string;
    /** 索引来源的迭代/任务标识 */
    scope: string;
    /** 所有分块 */
    chunks: DocumentChunk[];
    /** 文件摘要映射: filePath → 文件级摘要 */
    fileSummaries: Record<string, string>;
    /** 源文件修改时间: filePath → mtimeMs */
    fileMtimes: Record<string, number>;
}
export interface RetrievalOptions {
    /** 查询语句（task名称/需求关键词） */
    query: string;
    /** 最多返回几块 */
    topK?: number;
    /** 相关性分数阈值（0~1） */
    minScore?: number;
    /** 单块字数上限 */
    maxChunkChars?: number;
    /** 总字数上限 */
    maxTotalChars?: number;
    /** 按端过滤（backend/web/h5/admin/...） */
    platforms?: string[];
}
/**
 * 按 Markdown 标题层级分块
 * 规则：## / ### / #### 作为分块边界，一级标题 # 作为文档开头（不切分）
 */
export declare function chunkByHeaders(content: string, filePath: string): DocumentChunk[];
/**
 * 为多个文档构建 RAG 索引
 */
export declare function buildRagIndex(documents: {
    filePath: string;
    content: string;
    mtime?: number;
}[], scope: string): Promise<RagIndex>;
/**
 * 获取 RAG 索引文件路径
 * 支持按 scope 分文件存储，避免 task/iteration/global 互相覆盖
 */
export declare function getRagIndexPath(cwd: string, fileName?: string): string;
export declare function saveRagIndex(cwd: string, index: RagIndex, fileName?: string): Promise<void>;
export declare function loadRagIndex(cwd: string, fileName?: string): Promise<RagIndex | null>;
/**
 * 检查索引是否匹配当前 scope（迭代/任务变更后需重建）
 */
export declare function isRagIndexStale(index: RagIndex, currentScope: string): boolean;
/**
 * 根据查询语句检索最相关的文档块
 *
 * 评分逻辑：
 * - 标题关键词命中：+3 分/词
 * - 内容关键词命中：+1 分/词
 * - 摘要关键词命中：+2 分/词
 * - 高级别标题（##）bonus：+0.5 分
 * - 文件路径关键词命中：+1 分/词
 */
export declare function retrieveRelevantChunks(index: RagIndex, options: RetrievalOptions): DocumentChunk[];
/**
 * 将检索结果组装为 extraSpecs 格式（兼容现有 prompt-builder 接口）
 */
export declare function assembleChunksForPrompt(chunks: DocumentChunk[], options?: {
    maxCharsPerChunk?: number;
    maxTotalChars?: number;
}): {
    name: string;
    path: string;
    content: string;
}[];
/**
 * 获取文件级摘要（用于快速了解文档全貌）
 */
export declare function getFileSummaries(index: RagIndex): string;
/**
 * 扫描任务目录下的所有参考文档，构建 RAG 索引
 */
export declare function indexTaskDocuments(cwd: string, taskDir: string, iteration?: string, platform?: string, fileName?: string): Promise<RagIndex>;
/**
 * 检查 RAG 索引是否新鲜（对比源文件 mtime）
 * 返回: { fresh: boolean; staleFiles: string[] }
 */
export declare function checkRagIndexFreshness(cwd: string, fileName?: string): Promise<{
    fresh: boolean;
    staleFiles: string[];
    newFiles: string[];
}>;
/**
 * 为任意目录构建 RAG 索引（通用版本，不限于任务目录）
 * 扫描目录下所有 .md 文件，自动分块建索引
 */
export declare function indexDirectoryDocuments(cwd: string, dirPath: string, scope: string, fileName?: string): Promise<RagIndex>;
/**
 * 增量刷新 RAG 索引：只重建有变更的文件
 */
export declare function refreshRagIndex(cwd: string, taskDir: string, iteration?: string, platform?: string, fileName?: string): Promise<RagIndex>;
/**
 * 按 chunk 的行号范围精确读取源文件对应章节
 *
 * 用途：AI 拿到 chunk 的 startLine/endLine 后，用 Read 工具的
 *       offset/limit 只读目标章节，节省 80-95% Token
 *
 * @param chunk  带有 startLine/endLine 的 DocumentChunk
 * @returns      精确读取的文本，若无行号则回退到 chunk.content
 */
export declare function readChunkPrecise(chunk: DocumentChunk): Promise<string>;
/**
 * 批量精确读取多个 chunk
 */
export declare function readChunksPrecise(chunks: DocumentChunk[]): Promise<{
    chunk: DocumentChunk;
    content: string;
}[]>;
/** 知识图谱实体引用（轻量接口，避免循环依赖） */
interface KGLiteEntity {
    id: string;
    title: string;
    type: string;
    semanticTags?: string[];
    description?: string;
    businessRole?: string;
    file?: string;
}
interface KGLiteRelation {
    from: string;
    to: string;
    type: string;
}
interface KGLiteGraph {
    entities: Record<string, KGLiteEntity>;
    relations: KGLiteRelation[];
}
/**
 * 利用知识图谱增强 RAG 检索
 *
 * 流程：
 * 1. 用查询关键词在知识图谱中搜索相关实体
 * 2. 收集这些实体关联的邻居实体（扩展上下文）
 * 3. 在 RAG 索引中优先检索与这些实体相关的 chunk
 * 4. 将检索结果与知识图谱的关联信息一起返回
 */
export declare function retrieveWithGraphContext(index: RagIndex, graph: KGLiteGraph, options: RetrievalOptions): DocumentChunk[];
export {};
//# sourceMappingURL=rag-engine.d.ts.map