speccore 6.6.0 → 6.10.0

package/dist/core/rag-engine.d.ts

@@ -0,0 +1,152 @@
+/**
+ * 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;
+}[]>;
+//# sourceMappingURL=rag-engine.d.ts.map

package/dist/core/rag-engine.d.ts.map

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