spectra-cli 4.2.0 → 4.3.0

package/dist/scaffold-kb/chunk-splitter.d.ts

@@ -0,0 +1,20 @@
+/**
+ * F190 scaffold-kb — chunk-splitter
+ *
+ * 将 ParsedDoc 按三级策略切分为 Chunk[]:
+ *   1. 标题级（## / ###）— 每个标题节为候选单元
+ *   2. 段落级（\n\n）— 超 400 token 候选按空行切段，组合到接近 400 token
+ *   3. 句子级兜底（句号 / 换行）— 单段落超 400 token 时切
+ *
+ * token 计量：约 4 字符 = 1 token（无外部依赖）
+ * 单 chunk 上限：500 token（≈ 2000 字符）
+ * 最小 chunk：20 token（≈ 80 字符），不足则合并到邻近
+ */
+import type { Chunk, ParsedDoc } from './types.js';
+/**
+ * 将 ParsedDoc 按三级策略切分为 Chunk[]
+ *
+ * 幂等保证：相同输入产出相同 chunkId 集合与顺序
+ */
+export declare function splitDocument(doc: ParsedDoc): Chunk[];
+//# sourceMappingURL=chunk-splitter.d.ts.map

package/dist/scaffold-kb/chunk-splitter.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"chunk-splitter.d.ts","sourceRoot":"","sources":["../../src/scaffold-kb/chunk-splitter.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;GAWG;AAEH,OAAO,KAAK,EAAE,KAAK,EAAE,SAAS,EAAE,MAAM,YAAY,CAAC;AAgQnD;;;;GAIG;AACH,wBAAgB,aAAa,CAAC,GAAG,EAAE,SAAS,GAAG,KAAK,EAAE,CAiFrD"}

package/dist/scaffold-kb/chunk-splitter.js

@@ -0,0 +1,309 @@
+/**
+ * F190 scaffold-kb — chunk-splitter
+ *
+ * 将 ParsedDoc 按三级策略切分为 Chunk[]:
+ *   1. 标题级（## / ###）— 每个标题节为候选单元
+ *   2. 段落级（\n\n）— 超 400 token 候选按空行切段，组合到接近 400 token
+ *   3. 句子级兜底（句号 / 换行）— 单段落超 400 token 时切
+ *
+ * token 计量：约 4 字符 = 1 token（无外部依赖）
+ * 单 chunk 上限：500 token（≈ 2000 字符）
+ * 最小 chunk：20 token（≈ 80 字符），不足则合并到邻近
+ */
+// ── 常量 ────────────────────────────────────────────────────────────────────
+/** 约 4 字符 = 1 token 的估算系数 */
+const CHARS_PER_TOKEN = 4;
+/** 段落级再切阈值（token）— 超过此值的标题节需要继续切 */
+const PARAGRAPH_SPLIT_THRESHOLD_TOKENS = 400;
+/** 单 chunk 上限（token） */
+const MAX_CHUNK_TOKENS = 500;
+/** 最小 chunk 阈值（token）— 不足此值合并到邻近 */
+const MIN_CHUNK_TOKENS = 20;
+// 阈值对应字符数
+const PARAGRAPH_SPLIT_THRESHOLD_CHARS = PARAGRAPH_SPLIT_THRESHOLD_TOKENS * CHARS_PER_TOKEN; // 1600
+const MAX_CHUNK_CHARS = MAX_CHUNK_TOKENS * CHARS_PER_TOKEN; // 2000
+const MIN_CHUNK_CHARS = MIN_CHUNK_TOKENS * CHARS_PER_TOKEN; // 80
+// ── 工具函数 ─────────────────────────────────────────────────────────────────
+/**
+ * 将标题文本转为 URL slug
+ * 小写、空格转 `-`、去除非字母数字和连字符以外的字符
+ */
+function toSlug(heading) {
+    return heading
+        .toLowerCase()
+        .replace(/\s+/g, '-')
+        .replace(/[^a-z0-9一-鿿㐀-䶿\-]/g, '') // 保留中文字符和英文字母数字连字符
+        .replace(/-+/g, '-')
+        .replace(/^-|-$/g, '');
+}
+/**
+ * 估算文本的 token 数（4 字符 = 1 token）
+ */
+function estimateTokens(text) {
+    return Math.ceil(text.length / CHARS_PER_TOKEN);
+}
+/**
+ * 从 Markdown 正文中提取标题文本（去掉 ## / ### 前缀）
+ */
+function extractHeadingText(line) {
+    return line.replace(/^#{1,6}\s+/, '').trim();
+}
+/**
+ * 判断是否为标题行（仅处理 ## 和 ### 级别）
+ */
+function isHeadingLine(line) {
+    return /^#{2,3}\s/.test(line);
+}
+/**
+ * 按 ## / ### 标题将文档正文切成标题节列表
+ */
+function splitByHeadings(content) {
+    const lines = content.split('\n');
+    const sections = [];
+    let currentHeading = null;
+    let bodyLines = [];
+    for (const line of lines) {
+        if (isHeadingLine(line)) {
+            // 遇到新标题：保存上一节（如果有内容）
+            const bodyText = bodyLines.join('\n').trim();
+            if (bodyText.length > 0 || currentHeading !== null) {
+                sections.push({ heading: currentHeading, body: bodyText });
+            }
+            currentHeading = extractHeadingText(line);
+            bodyLines = [];
+        }
+        else {
+            bodyLines.push(line);
+        }
+    }
+    // 最后一节
+    const bodyText = bodyLines.join('\n').trim();
+    if (bodyText.length > 0 || currentHeading !== null) {
+        sections.push({ heading: currentHeading, body: bodyText });
+    }
+    return sections;
+}
+// ── 段落与句子切分 ────────────────────────────────────────────────────────────
+/**
+ * 将文本按空行（\n\n）切成段落列表（过滤空段落）
+ */
+function splitToParagraphs(text) {
+    return text
+        .split(/\n\n+/)
+        .map((p) => p.trim())
+        .filter((p) => p.length > 0);
+}
+/**
+ * 将段落按句子切分（句号、问号、感叹号、换行后兜底）
+ * 尽量不跨语义单元强切
+ */
+function splitToSentences(paragraph) {
+    // 按中英文句号、问号、感叹号切分；保留分隔符在前句末尾
+    // 同时按换行切（代码块等大段落）
+    const parts = [];
+    // 先按换行切，再对每行按句子切
+    const lines = paragraph.split('\n');
+    for (const line of lines) {
+        if (line.trim().length === 0)
+            continue;
+        // 按中英文句号/问号/感叹号切分，保留标点在前面
+        const sentenceBreaks = line.split(/(?<=[。！？.!?])\s*/);
+        for (const s of sentenceBreaks) {
+            const trimmed = s.trim();
+            if (trimmed.length > 0) {
+                parts.push(trimmed);
+            }
+        }
+    }
+    return parts.filter((p) => p.length > 0);
+}
+/**
+ * 将多段落组合为不超过 MAX_CHUNK_CHARS 的文本块
+ * 每个段落超过 PARAGRAPH_SPLIT_THRESHOLD_CHARS 时先拆成句子再组合
+ *
+ * 句子/段落组合目标是接近 400 token（PARAGRAPH_SPLIT_THRESHOLD_CHARS），
+ * 绝对上限是 500 token（MAX_CHUNK_CHARS）。
+ */
+function combineParagraphs(paragraphs) {
+    const chunks = [];
+    let current = '';
+    /**
+     * 将一批"原子单元"（句子）追加合并到 chunks。
+     * 目标大小：PARAGRAPH_SPLIT_THRESHOLD_CHARS（1600 字符 ≈ 400 token）
+     * 绝对上限：MAX_CHUNK_CHARS（2000 字符 ≈ 500 token）
+     */
+    function flushAtoms(atoms) {
+        for (const atom of atoms) {
+            if (atom.length > MAX_CHUNK_CHARS) {
+                // 单个原子超绝对上限：强制截断（兜底，极端情况）
+                if (current.length > 0) {
+                    chunks.push(current);
+                    current = '';
+                }
+                let remaining = atom;
+                while (remaining.length > MAX_CHUNK_CHARS) {
+                    chunks.push(remaining.slice(0, MAX_CHUNK_CHARS));
+                    remaining = remaining.slice(MAX_CHUNK_CHARS);
+                }
+                if (remaining.length > 0) {
+                    current = remaining;
+                }
+            }
+            else {
+                // 追加后超过目标大小（400 token）时关闭当前块，开始新块
+                const separator = current.length > 0 ? '\n' : '';
+                const nextLength = current.length + separator.length + atom.length;
+                if (nextLength > PARAGRAPH_SPLIT_THRESHOLD_CHARS && current.length > 0) {
+                    chunks.push(current);
+                    current = atom;
+                }
+                else {
+                    current = current.length > 0 ? current + '\n' + atom : atom;
+                }
+            }
+        }
+    }
+    for (const para of paragraphs) {
+        if (para.length > PARAGRAPH_SPLIT_THRESHOLD_CHARS) {
+            // 段落过大：先按句子切，再组合
+            const sentences = splitToSentences(para);
+            flushAtoms(sentences);
+        }
+        else if (current.length + (current.length > 0 ? 2 : 0) + para.length > MAX_CHUNK_CHARS) {
+            // 追加后超绝对上限：保存当前，开新 chunk
+            if (current.length > 0) {
+                chunks.push(current);
+                current = '';
+            }
+            current = para;
+        }
+        else {
+            current = current.length > 0 ? current + '\n\n' + para : para;
+        }
+    }
+    if (current.length > 0) {
+        chunks.push(current);
+    }
+    return chunks;
+}
+// ── 最小 chunk 合并 ────────────────────────────────────────────────────────
+/**
+ * 合并过短（< MIN_CHUNK_CHARS）的文本块到邻近块
+ * 优先合并到前一块；若前一块不存在则合并到后一块
+ */
+function mergeSmallChunks(texts) {
+    if (texts.length === 0)
+        return [];
+    // 先收集合并结果
+    const result = [];
+    for (let i = 0; i < texts.length; i++) {
+        const text = texts[i];
+        // 断言：texts[i] 在循环内已通过索引 i 访问，但 noUncheckedIndexedAccess 要求检查
+        if (text === undefined)
+            continue;
+        if (text.length < MIN_CHUNK_CHARS) {
+            if (result.length > 0) {
+                // 合并到前一块
+                const prev = result[result.length - 1];
+                if (prev !== undefined) {
+                    result[result.length - 1] = prev + '\n\n' + text;
+                }
+            }
+            else {
+                // 没有前一块：先缓存，后面尝试合并到下一块
+                result.push(text);
+            }
+        }
+        else {
+            if (result.length > 0 &&
+                (result[result.length - 1]?.length ?? 0) < MIN_CHUNK_CHARS) {
+                // 前一个太小，合并进来
+                const prev = result[result.length - 1];
+                if (prev !== undefined) {
+                    result[result.length - 1] = prev + '\n\n' + text;
+                }
+            }
+            else {
+                result.push(text);
+            }
+        }
+    }
+    return result.filter((t) => t.trim().length > 0);
+}
+// ── 主函数 ──────────────────────────────────────────────────────────────────
+/**
+ * 将 ParsedDoc 按三级策略切分为 Chunk[]
+ *
+ * 幂等保证：相同输入产出相同 chunkId 集合与顺序
+ */
+export function splitDocument(doc) {
+    const sections = splitByHeadings(doc.content);
+    // anchor 序号计数器（同一 anchor 下多个 chunk 时追加序号）
+    const anchorCounts = new Map();
+    /**
+     * 为给定 anchor 分配下一个序号（首次分配返回 1，后续递增）
+     */
+    function nextAnchorIndex(anchor) {
+        const count = (anchorCounts.get(anchor) ?? 0) + 1;
+        anchorCounts.set(anchor, count);
+        return count;
+    }
+    const allChunks = [];
+    // 无标题文档的全局序号（anchor 为 null 时使用 _N）
+    let noHeadingCounter = 0;
+    for (const section of sections) {
+        const anchor = section.heading !== null ? toSlug(section.heading) : null;
+        // 候选文本：标题（如有）+ 正文
+        const sectionText = section.heading !== null
+            ? `## ${section.heading}\n\n${section.body}`.trim()
+            : section.body;
+        if (sectionText.trim().length === 0)
+            continue;
+        // 决定是否需要进一步切分
+        let rawTexts;
+        if (estimateTokens(sectionText) <= PARAGRAPH_SPLIT_THRESHOLD_TOKENS) {
+            // 整节 ≤ 400 token：直接作为一个候选块
+            rawTexts = [sectionText];
+        }
+        else {
+            // 超过 400 token：按段落+句子切分
+            const paragraphs = splitToParagraphs(
+            // 正文部分切段落（不含标题行本身）
+            section.body);
+            const combined = combineParagraphs(paragraphs);
+            const merged = mergeSmallChunks(combined);
+            // 如果正文被切开，把标题前缀加到第一块
+            if (merged.length > 0 && section.heading !== null) {
+                merged[0] = `## ${section.heading}\n\n${merged[0] ?? ''}`;
+            }
+            rawTexts = merged.length > 0 ? merged : [sectionText];
+        }
+        // 最终过滤 + 生成 Chunk 对象
+        for (const text of rawTexts) {
+            if (text.trim().length === 0)
+                continue;
+            // 过短：计入下一次迭代合并（此处已经过 mergeSmallChunks，理论上不应出现）
+            // 但仍做最终检查
+            if (text.length < MIN_CHUNK_CHARS && rawTexts.length > 1)
+                continue;
+            // 生成 chunkId
+            let chunkId;
+            if (anchor !== null) {
+                const idx = nextAnchorIndex(anchor);
+                chunkId = idx === 1 ? `${doc.id}#${anchor}` : `${doc.id}#${anchor}-${idx}`;
+            }
+            else {
+                noHeadingCounter += 1;
+                chunkId = `${doc.id}#_${noHeadingCounter}`;
+            }
+            allChunks.push({
+                chunkId,
+                docId: doc.id,
+                contentRaw: text,
+                anchor,
+            });
+        }
+    }
+    return allChunks;
+}
+//# sourceMappingURL=chunk-splitter.js.map

package/dist/scaffold-kb/chunk-splitter.js.map

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

package/dist/scaffold-kb/doc-graph-builder.d.ts

@@ -0,0 +1,26 @@
+/**
+ * F190 scaffold-kb — doc-graph 构建器
+ *
+ * 将 ParsedDoc 列表转换为 DocGraph（doc-graph.json 结构契约）。
+ * 幂等保证：相同输入（同 docs 同 opts）产出在去掉 builtAt 后字节级一致。
+ * 排序规则：nodes 按 doc.id 升序，edges 按 (source, target) 升序。
+ */
+import type { DocGraph, ParsedDoc } from './types.js';
+/** buildDocGraph 的选项参数 */
+export interface BuildDocGraphOpts {
+    /** 文档来源类型 */
+    source: 'llms.txt' | 'directory';
+    /** SDK 版本（可选），写入产物元数据 */
+    sdkVersion: string | null;
+    /** 构建时间戳（ISO 8601），幂等对比时排除 */
+    builtAt: string;
+}
+/**
+ * 从解析文档列表构建文档图（doc-graph.json）。
+ *
+ * @param docs  ingester 解析出的文档数组
+ * @param opts  来源类型、SDK 版本、构建时间戳
+ * @returns     满足 spec §3.2 结构契约的 DocGraph
+ */
+export declare function buildDocGraph(docs: ParsedDoc[], opts: BuildDocGraphOpts): DocGraph;
+//# sourceMappingURL=doc-graph-builder.d.ts.map

package/dist/scaffold-kb/doc-graph-builder.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"doc-graph-builder.d.ts","sourceRoot":"","sources":["../../src/scaffold-kb/doc-graph-builder.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AAEH,OAAO,KAAK,EAAE,QAAQ,EAAoB,SAAS,EAAE,MAAM,YAAY,CAAC;AAExE,0BAA0B;AAC1B,MAAM,WAAW,iBAAiB;IAChC,aAAa;IACb,MAAM,EAAE,UAAU,GAAG,WAAW,CAAC;IACjC,yBAAyB;IACzB,UAAU,EAAE,MAAM,GAAG,IAAI,CAAC;IAC1B,8BAA8B;IAC9B,OAAO,EAAE,MAAM,CAAC;CACjB;AAED;;;;;;GAMG;AACH,wBAAgB,aAAa,CAAC,IAAI,EAAE,SAAS,EAAE,EAAE,IAAI,EAAE,iBAAiB,GAAG,QAAQ,CA2DlF"}

package/dist/scaffold-kb/doc-graph-builder.js

@@ -0,0 +1,72 @@
+/**
+ * F190 scaffold-kb — doc-graph 构建器
+ *
+ * 将 ParsedDoc 列表转换为 DocGraph（doc-graph.json 结构契约）。
+ * 幂等保证：相同输入（同 docs 同 opts）产出在去掉 builtAt 后字节级一致。
+ * 排序规则：nodes 按 doc.id 升序，edges 按 (source, target) 升序。
+ */
+/**
+ * 从解析文档列表构建文档图（doc-graph.json）。
+ *
+ * @param docs  ingester 解析出的文档数组
+ * @param opts  来源类型、SDK 版本、构建时间戳
+ * @returns     满足 spec §3.2 结构契约的 DocGraph
+ */
+export function buildDocGraph(docs, opts) {
+    // 第一步：构建 id 集合，用于悬空引用过滤
+    const idSet = new Set(docs.map((d) => d.id));
+    // 第二步：映射 ParsedDoc → DocNode，按 id 升序排列确保幂等
+    const nodes = docs
+        .slice()
+        .sort((a, b) => a.id.localeCompare(b.id))
+        .map((doc) => {
+        const node = {
+            id: doc.id,
+            title: doc.title,
+            lang: doc.lang,
+            sourceUrl: doc.sourceUrl,
+        };
+        // summary 和 tags 是可选字段，仅当 ParsedDoc 携带时写入
+        // ParsedDoc 接口本身没有 summary/tags，为 future-proof 保留扩展检查
+        return node;
+    });
+    // 第三步：从 doc.references 提取 DocEdge，跳过悬空引用（目标 id 不在集合内）
+    const edgeMap = new Map();
+    for (const doc of docs) {
+        const refs = doc.references;
+        if (refs === undefined || refs.length === 0) {
+            continue;
+        }
+        for (const targetId of refs) {
+            // 悬空引用跳过（目标文档不存在于 docs 集合）
+            if (!idSet.has(targetId)) {
+                continue;
+            }
+            // 使用 "source|target" 作为 key 去重（同一对可能从多处引用）
+            const key = `${doc.id}\x00${targetId}`;
+            if (!edgeMap.has(key)) {
+                edgeMap.set(key, {
+                    source: doc.id,
+                    target: targetId,
+                    relation: 'references',
+                });
+            }
+        }
+    }
+    // 按 (source, target) 升序排列，保证幂等
+    const edges = Array.from(edgeMap.values()).sort((a, b) => {
+        const cmp = a.source.localeCompare(b.source);
+        if (cmp !== 0)
+            return cmp;
+        return a.target.localeCompare(b.target);
+    });
+    return {
+        schemaVersion: '1.0',
+        source: opts.source,
+        builtAt: opts.builtAt,
+        sdkVersion: opts.sdkVersion,
+        nodes,
+        edges,
+    };
+}
+//# sourceMappingURL=doc-graph-builder.js.map

package/dist/scaffold-kb/doc-graph-builder.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"doc-graph-builder.js","sourceRoot":"","sources":["../../src/scaffold-kb/doc-graph-builder.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AAcH;;;;;;GAMG;AACH,MAAM,UAAU,aAAa,CAAC,IAAiB,EAAE,IAAuB;IACtE,wBAAwB;IACxB,MAAM,KAAK,GAAG,IAAI,GAAG,CAAS,IAAI,CAAC,GAAG,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC;IAErD,2CAA2C;IAC3C,MAAM,KAAK,GAAc,IAAI;SAC1B,KAAK,EAAE;SACP,IAAI,CAAC,CAAC,CAAC,EAAE,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,EAAE,CAAC,aAAa,CAAC,CAAC,CAAC,EAAE,CAAC,CAAC;SACxC,GAAG,CAAC,CAAC,GAAG,EAAE,EAAE;QACX,MAAM,IAAI,GAAY;YACpB,EAAE,EAAE,GAAG,CAAC,EAAE;YACV,KAAK,EAAE,GAAG,CAAC,KAAK;YAChB,IAAI,EAAE,GAAG,CAAC,IAAI;YACd,SAAS,EAAE,GAAG,CAAC,SAAS;SACzB,CAAC;QACF,0CAA0C;QAC1C,sDAAsD;QACtD,OAAO,IAAI,CAAC;IACd,CAAC,CAAC,CAAC;IAEL,sDAAsD;IACtD,MAAM,OAAO,GAAG,IAAI,GAAG,EAAmB,CAAC;IAC3C,KAAK,MAAM,GAAG,IAAI,IAAI,EAAE,CAAC;QACvB,MAAM,IAAI,GAAG,GAAG,CAAC,UAAU,CAAC;QAC5B,IAAI,IAAI,KAAK,SAAS,IAAI,IAAI,CAAC,MAAM,KAAK,CAAC,EAAE,CAAC;YAC5C,SAAS;QACX,CAAC;QACD,KAAK,MAAM,QAAQ,IAAI,IAAI,EAAE,CAAC;YAC5B,2BAA2B;YAC3B,IAAI,CAAC,KAAK,CAAC,GAAG,CAAC,QAAQ,CAAC,EAAE,CAAC;gBACzB,SAAS;YACX,CAAC;YACD,2CAA2C;YAC3C,MAAM,GAAG,GAAG,GAAG,GAAG,CAAC,EAAE,OAAO,QAAQ,EAAE,CAAC;YACvC,IAAI,CAAC,OAAO,CAAC,GAAG,CAAC,GAAG,CAAC,EAAE,CAAC;gBACtB,OAAO,CAAC,GAAG,CAAC,GAAG,EAAE;oBACf,MAAM,EAAE,GAAG,CAAC,EAAE;oBACd,MAAM,EAAE,QAAQ;oBAChB,QAAQ,EAAE,YAAY;iBACvB,CAAC,CAAC;YACL,CAAC;QACH,CAAC;IACH,CAAC;IAED,+BAA+B;IAC/B,MAAM,KAAK,GAAc,KAAK,CAAC,IAAI,CAAC,OAAO,CAAC,MAAM,EAAE,CAAC,CAAC,IAAI,CAAC,CAAC,CAAC,EAAE,CAAC,EAAE,EAAE;QAClE,MAAM,GAAG,GAAG,CAAC,CAAC,MAAM,CAAC,aAAa,CAAC,CAAC,CAAC,MAAM,CAAC,CAAC;QAC7C,IAAI,GAAG,KAAK,CAAC;YAAE,OAAO,GAAG,CAAC;QAC1B,OAAO,CAAC,CAAC,MAAM,CAAC,aAAa,CAAC,CAAC,CAAC,MAAM,CAAC,CAAC;IAC1C,CAAC,CAAC,CAAC;IAEH,OAAO;QACL,aAAa,EAAE,KAAK;QACpB,MAAM,EAAE,IAAI,CAAC,MAAM;QACnB,OAAO,EAAE,IAAI,CAAC,OAAO;QACrB,UAAU,EAAE,IAAI,CAAC,UAAU;QAC3B,KAAK;QACL,KAAK;KACN,CAAC;AACJ,CAAC"}

package/dist/scaffold-kb/entity-extractor.d.ts

@@ -0,0 +1,40 @@
+/**
+ * F192 T004 — API 实体抽取器（LLM 提质 + heuristic 兜底，FR-001/002/003）
+ *
+ * 流程：chunks → section 窗口聚合（W-4，防签名跨 chunk 切碎）→ 逐 section
+ *   LLM 抽取（无认证/--no-llm/返回 null/解析失败 → heuristic 兜底，EC-002）。
+ * 成本护栏：maxSections 截断 + coverage 元字段（FR-001）。
+ * 诚实：LLM prompt 严禁编造；无 LLM 不阻断（FR-003）。
+ *
+ * callLLM/llmAvailable 可注入（仿 ingester fetchImpl），保证测试确定性。
+ */
+import type { ApiEntity, Chunk, ExtractionSection } from './types.js';
+import { type LLMCallOptions } from '../panoramic/utils/llm-facade.js';
+export type CallLLMFn = (prompt: string, options?: LLMCallOptions) => Promise<string | null>;
+export interface ExtractOptions {
+    /** 强制跳过 LLM，只走 heuristic（CLI --no-llm，FR-001） */
+    noLlm?: boolean;
+    /** 成本护栏：最多处理 section 数（超出截断并记 coverage）。缺省全量 */
+    maxSections?: number;
+    /** 成本护栏：累计输入字符上限（token 代理；超出停止后续 section）。缺省无限 */
+    maxInputChars?: number;
+    /** 进度回调（可观测，FR-001） */
+    onProgress?: (done: number, total: number) => void;
+    /** 注入 LLM 调用（测试用），缺省走 facade */
+    callLLM?: CallLLMFn;
+    /** 注入可用性检测（测试用），缺省走 facade */
+    llmAvailable?: () => boolean;
+}
+export interface ExtractResult {
+    entities: ApiEntity[];
+    coverage: {
+        totalSections: number;
+        extractedSections: number;
+    };
+    method: 'llm' | 'heuristic' | 'mixed';
+}
+/** chunks → section 窗口（同 docId+anchor 相邻 chunk 聚合，W-4） */
+export declare function aggregateSections(chunks: Chunk[], docLang: Map<string, string>): ExtractionSection[];
+/** 抽取实体：LLM 优先、heuristic 兜底，带成本护栏 + coverage */
+export declare function extractEntities(sections: ExtractionSection[], opts?: ExtractOptions): Promise<ExtractResult>;
+//# sourceMappingURL=entity-extractor.d.ts.map

package/dist/scaffold-kb/entity-extractor.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"entity-extractor.d.ts","sourceRoot":"","sources":["../../src/scaffold-kb/entity-extractor.ts"],"names":[],"mappings":"AAAA;;;;;;;;;GASG;AAEH,OAAO,KAAK,EAAE,SAAS,EAAE,KAAK,EAAE,iBAAiB,EAAE,MAAM,YAAY,CAAC;AAGtE,OAAO,EAIL,KAAK,cAAc,EACpB,MAAM,kCAAkC,CAAC;AAE1C,MAAM,MAAM,SAAS,GAAG,CAAC,MAAM,EAAE,MAAM,EAAE,OAAO,CAAC,EAAE,cAAc,KAAK,OAAO,CAAC,MAAM,GAAG,IAAI,CAAC,CAAC;AAE7F,MAAM,WAAW,cAAc;IAC7B,iDAAiD;IACjD,KAAK,CAAC,EAAE,OAAO,CAAC;IAChB,gDAAgD;IAChD,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,kDAAkD;IAClD,aAAa,CAAC,EAAE,MAAM,CAAC;IACvB,uBAAuB;IACvB,UAAU,CAAC,EAAE,CAAC,IAAI,EAAE,MAAM,EAAE,KAAK,EAAE,MAAM,KAAK,IAAI,CAAC;IACnD,gCAAgC;IAChC,OAAO,CAAC,EAAE,SAAS,CAAC;IACpB,8BAA8B;IAC9B,YAAY,CAAC,EAAE,MAAM,OAAO,CAAC;CAC9B;AAED,MAAM,WAAW,aAAa;IAC5B,QAAQ,EAAE,SAAS,EAAE,CAAC;IACtB,QAAQ,EAAE;QAAE,aAAa,EAAE,MAAM,CAAC;QAAC,iBAAiB,EAAE,MAAM,CAAA;KAAE,CAAC;IAC/D,MAAM,EAAE,KAAK,GAAG,WAAW,GAAG,OAAO,CAAC;CACvC;AAeD,0DAA0D;AAC1D,wBAAgB,iBAAiB,CAAC,MAAM,EAAE,KAAK,EAAE,EAAE,OAAO,EAAE,GAAG,CAAC,MAAM,EAAE,MAAM,CAAC,GAAG,iBAAiB,EAAE,CAwBpG;AA0ED,gDAAgD;AAChD,wBAAsB,eAAe,CACnC,QAAQ,EAAE,iBAAiB,EAAE,EAC7B,IAAI,GAAE,cAAmB,GACxB,OAAO,CAAC,aAAa,CAAC,CA0DxB"}

package/dist/scaffold-kb/entity-extractor.js.map

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

package/dist/scaffold-kb/entity-heuristic.d.ts

@@ -0,0 +1,14 @@
+/**
+ * F192 T003 — 无 LLM 的确定性 API 实体抽取（heuristic fallback，EC-002）
+ *
+ * 纯函数、零外部依赖、可重复。规则保守（宁可漏抽不可编造，FR-003）：
+ * - 围栏代码块 + 内联里的函数/方法签名 `name(params)`
+ * - 错误码模式（E\d+ / ALL_CAPS_ERROR）
+ * - 段落级 deprecated 标记（@deprecated / 已废弃 / deprecated since X）
+ *
+ * 反过拟合（FR-018）：规则 MUST NOT 匹配任何 eval manifest 的具体 API 名字面量。
+ */
+import type { ApiEntity, ExtractionSection } from './types.js';
+/** 对单个 section 做确定性抽取，返回去重后的实体列表 */
+export declare function extractHeuristic(section: ExtractionSection): ApiEntity[];
+//# sourceMappingURL=entity-heuristic.d.ts.map

package/dist/scaffold-kb/entity-heuristic.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"entity-heuristic.d.ts","sourceRoot":"","sources":["../../src/scaffold-kb/entity-heuristic.ts"],"names":[],"mappings":"AAAA;;;;;;;;;GASG;AAEH,OAAO,KAAK,EAAE,SAAS,EAAE,iBAAiB,EAAE,MAAM,YAAY,CAAC;AAsD/D,oCAAoC;AACpC,wBAAgB,gBAAgB,CAAC,OAAO,EAAE,iBAAiB,GAAG,SAAS,EAAE,CA+CxE"}

package/dist/scaffold-kb/entity-heuristic.js

@@ -0,0 +1,107 @@
+/**
+ * F192 T003 — 无 LLM 的确定性 API 实体抽取（heuristic fallback，EC-002）
+ *
+ * 纯函数、零外部依赖、可重复。规则保守（宁可漏抽不可编造，FR-003）：
+ * - 围栏代码块 + 内联里的函数/方法签名 `name(params)`
+ * - 错误码模式（E\d+ / ALL_CAPS_ERROR）
+ * - 段落级 deprecated 标记（@deprecated / 已废弃 / deprecated since X）
+ *
+ * 反过拟合（FR-018）：规则 MUST NOT 匹配任何 eval manifest 的具体 API 名字面量。
+ */
+import { makeEntityId } from './entity-util.js';
+const HEURISTIC_CONFIDENCE = 0.5;
+// 函数/方法签名：可选前缀(export/async/function/def/fn/func/public...) + 名称 + (参数)
+const SIG_RE = /(?:export\s+|public\s+|async\s+|function\s+|def\s+|fn\s+|func\s+)*([A-Za-z_$][\w$.]{1,})\s*\(([^)]{0,400})\)/g;
+// 错误码：E + ≥2 位数字，或 全大写下划线 + _ERROR/_CODE/_EXCEPTION
+const ERRCODE_RE = /\b(E\d{2,}|[A-Z][A-Z0-9]*(?:_[A-Z0-9]+)*_(?:ERROR|CODE|EXCEPTION))\b/g;
+// deprecated 标记 + 可选 since 版本
+const DEPRECATED_RE = /@deprecated|已废弃|deprecated\s+since\s+([\w.\-]+)|废弃于\s*([\w.\-]+)/i;
+// 噪声名（语言关键字 / 控制流），不作为 API 名
+const NOISE_NAMES = new Set([
+    'if', 'for', 'while', 'switch', 'return', 'function', 'class', 'catch', 'await',
+    'async', 'def', 'fn', 'func', 'import', 'export', 'const', 'let', 'var', 'new',
+    'typeof', 'instanceof', 'in', 'of', 'do', 'else', 'try', 'throw', 'with', 'super',
+]);
+function isNoiseName(name) {
+    if (name.length < 2)
+        return true;
+    const last = name.includes('.') ? (name.split('.').pop() ?? name) : name;
+    return NOISE_NAMES.has(last.toLowerCase());
+}
+/** 解析 `a, b: number, c = 1` → params（name + 可选 type） */
+function parseParams(paramStr) {
+    const trimmed = paramStr.trim();
+    if (!trimmed)
+        return [];
+    return trimmed
+        .split(',')
+        .map((p) => p.trim())
+        .filter((p) => p.length > 0)
+        .map((p) => {
+        // 支持 `name: type` / `name=default` / `type name`(go/java 粗略)
+        const colon = p.split(':');
+        const rawName = (colon[0] ?? p).split('=')[0]?.trim() ?? p;
+        const name = rawName.replace(/^\.\.\./, '').replace(/\?$/, '').trim();
+        const type = colon.length > 1 ? colon.slice(1).join(':').trim() : null;
+        const entry = { name };
+        if (type)
+            entry.type = type;
+        return entry;
+    })
+        .filter((e) => e.name.length > 0 && /^[A-Za-z_$]/.test(e.name));
+}
+function parseDeprecated(text) {
+    const m = DEPRECATED_RE.exec(text);
+    if (!m)
+        return { isDeprecated: false };
+    const since = m[1] ?? m[2] ?? null;
+    return since ? { isDeprecated: true, since } : { isDeprecated: true };
+}
+/** 对单个 section 做确定性抽取，返回去重后的实体列表 */
+export function extractHeuristic(section) {
+    const out = [];
+    const seen = new Set();
+    const primaryChunk = section.chunkIds[0] ?? '';
+    const dep = parseDeprecated(section.text);
+    const push = (name, kind, signature, params) => {
+        const id = makeEntityId(name, kind);
+        if (seen.has(id))
+            return;
+        seen.add(id);
+        const e = {
+            id,
+            name,
+            qualifiedName: name,
+            kind,
+            signature,
+            sourceDocId: section.docId,
+            sourceChunkId: primaryChunk,
+            sourceChunkIds: section.chunkIds,
+            sourceAnchor: section.anchor,
+            lang: section.lang,
+            confidence: HEURISTIC_CONFIDENCE,
+            extractionMethod: 'heuristic',
+        };
+        if (params !== undefined)
+            e.params = params;
+        if (dep.isDeprecated)
+            e.deprecated = dep;
+        out.push(e);
+    };
+    // 1. 错误码
+    for (const m of section.text.matchAll(ERRCODE_RE)) {
+        const code = m[1];
+        if (code)
+            push(code, 'error_code', null, undefined);
+    }
+    // 2. 函数/方法签名
+    for (const m of section.text.matchAll(SIG_RE)) {
+        const name = m[1];
+        const paramStr = m[2] ?? '';
+        if (!name || isNoiseName(name))
+            continue;
+        push(name, 'function', `${name}(${paramStr.trim()})`, parseParams(paramStr));
+    }
+    return out;
+}
+//# sourceMappingURL=entity-heuristic.js.map