@coralai/sps-cli 0.50.24 → 0.51.1

package/dist/core/wiki/reader.js

@@ -0,0 +1,225 @@
+/**
+ * @module        core/wiki/reader
+ * @description   wikiRead()：5 层确定性检索 + 类型优先级 + token 预算
+ *
+ * @layer         core
+ *
+ * doc-28 §10 Wiki 读取原则的代码实现。**这是 Worker prompt 注入的入口**。
+ *
+ * 5 层叠加：
+ *   L1 永远 — hot.md 全文                           ~500 字
+ *   L2 永远 — index.md 节选 top-N 行                ~500 字
+ *   L3 优先 — pinned wiki_pages（card frontmatter）  ~50×N 字
+ *   L4 按 skill — 卡 skills ∩ 页 tags → top-3        ~50×3 字
+ *   L5 按关键词 — BM25(card.title + card.desc)→top-3 ~50×3 字
+ *
+ * 优先级排序（命中多页）：
+ *   lesson = 3 / decision = 3 / concept = 2 / module = 1 / source = 1
+ *   stale page → 跳过（status=stale 或 mtime 太老）
+ *
+ * Token 预算硬上限 1500 字（~2000 token），超出砍 L5 keyword 命中。
+ *
+ * 设计原则（Karpathy）：
+ *   - **确定性**——同输入同输出，纯函数（除文件 I/O）
+ *   - **Push 而非 Pull**——Worker 不需要学怎么查，结果已经摆好
+ *   - **TL;DR 而非全文**——让 Worker 自己决定要不要 Read 完整 page
+ */
+import { readHot } from './hot.js';
+import { readIndexSummary } from './index-builder.js';
+import { getPageById, listValidPages } from './page.js';
+import { extractTLDR, WikiSearcher } from './searcher.js';
+const DEFAULT_OPTS = {
+    indexLines: 30,
+    skillTopN: 3,
+    keywordTopN: 3,
+    budgetTokens: 2000,
+};
+// 类型优先级（数字越大越靠前）
+const TYPE_PRIORITY = {
+    lesson: 3,
+    decision: 3,
+    concept: 2,
+    module: 1,
+    source: 1,
+};
+// 启发式：1 个汉字/英文单词 ≈ 1.5 token（粗估）
+const CHARS_PER_TOKEN = 1.5;
+// ─── 主入口 ───────────────────────────────────────────────────────
+/**
+ * 读取 wiki 注入到 Worker prompt 的上下文。
+ *
+ * 步骤：
+ *   1. Layer 1: hot.md 全文
+ *   2. Layer 2: index.md 节选
+ *   3. Layer 3: pinned pages（按 id 取）
+ *   4. 列所有 page 建临时 searcher
+ *   5. Layer 4: skill 匹配
+ *   6. Layer 5: BM25 关键词
+ *   7. 合并去重 → 类型优先级排序 → 预算截断
+ *   8. 装载 TL;DR 入 PageContextEntry
+ *
+ * 失败模式：任何 layer 失败（文件丢/解析错）单独 swallow，不阻塞其他 layer。
+ */
+export function wikiRead(input, opts = {}) {
+    const cfg = { ...DEFAULT_OPTS, ...opts };
+    // L1
+    const hot = safeRead(() => readHot(input.repoDir), '');
+    // L2
+    const indexSummary = safeRead(() => readIndexSummary(input.repoDir, cfg.indexLines), '');
+    // 拉所有 page 一次（reader.ts 调用频率低 = 卡启动一次；现读 OK）
+    const pages = safeRead(() => listValidPages(input.repoDir), []);
+    // L3: pinned
+    const pinned = (input.pinnedPages ?? [])
+        .map((id) => getPageById(input.repoDir, id))
+        .filter((p) => p !== null);
+    // 临时 searcher 用 IndexedDoc（pageToIndexed 来自 searcher.ts）
+    const searcher = new WikiSearcher(pages.map(pageToIndexedAdapter));
+    // L4: skill
+    const bySkill = searcher
+        .searchByTags(input.cardSkills, cfg.skillTopN)
+        .map((r) => ({ pageId: r.pageId, source: 'skill' }));
+    // L5: keyword
+    const byKeyword = searcher
+        .search(`${input.cardTitle} ${input.cardDesc}`, cfg.keywordTopN)
+        .map((r) => ({ pageId: r.pageId, source: 'keyword' }));
+    // 合并去重（按 source 优先级：pinned > skill > keyword）
+    const dedup = new Map();
+    for (const p of pinned)
+        dedup.set(p.pageId, { source: 'pinned' });
+    for (const r of bySkill) {
+        if (!dedup.has(r.pageId))
+            dedup.set(r.pageId, { source: r.source });
+    }
+    for (const r of byKeyword) {
+        if (!dedup.has(r.pageId))
+            dedup.set(r.pageId, { source: r.source });
+    }
+    // 把每个 page 加载完整 + 排序
+    const entries = [];
+    for (const [pageId, meta] of dedup) {
+        const page = pages.find((p) => p.pageId === pageId);
+        if (!page)
+            continue;
+        if (isStalePage(page))
+            continue;
+        entries.push({
+            pageId,
+            title: page.frontmatter.title,
+            type: page.frontmatter.type,
+            tldr: extractTLDR(page.body),
+            source: meta.source,
+            priority: priorityOf(page.frontmatter.type, meta.source),
+        });
+    }
+    // 优先级排序
+    entries.sort((a, b) => b.priority - a.priority);
+    // 预算截断：估算 token，超出从尾部砍 keyword 命中（保 pinned + skill + 高优类型）
+    const trimmed = applyBudget(entries, hot, indexSummary, cfg.budgetTokens);
+    const tokensEstimate = estimateTokens(hot, indexSummary, trimmed);
+    return {
+        hot,
+        indexSummary,
+        pages: trimmed,
+        tokensEstimate,
+    };
+}
+// ─── Prompt 渲染 ──────────────────────────────────────────────────
+/**
+ * WikiContext → prompt 注入 markdown。
+ *
+ * 格式（doc-28 §10）：
+ *   # 项目知识 - 当前状态
+ *   <hot.md 全文>
+ *   ---
+ *   # 知识地图（节选）
+ *   <index summary>
+ *   ---
+ *   # 与本任务相关的页
+ *   ## [[id]] (type) [via source]
+ *   TL;DR: ...
+ */
+export function formatWikiContext(ctx) {
+    const sections = [];
+    if (ctx.hot.trim().length > 0) {
+        // hot 已经是带 frontmatter 的完整文档；展示时去掉 frontmatter 块
+        const hotBody = stripFrontmatter(ctx.hot).trim();
+        sections.push('# 项目知识 - 当前状态\n\n' + hotBody);
+    }
+    if (ctx.indexSummary.trim().length > 0) {
+        sections.push('# 知识地图（节选）\n\n' + ctx.indexSummary.trim());
+    }
+    if (ctx.pages.length > 0) {
+        const lines = ['# 与本任务相关的页', ''];
+        for (const p of ctx.pages) {
+            const tag = p.source === 'pinned' ? '📌 pinned' : p.source === 'skill' ? 'via skill' : 'via keyword';
+            lines.push(`## [[${p.pageId}]] (${p.type}, ${tag})`);
+            lines.push(`TL;DR: ${p.tldr.replace(/\s+/g, ' ').trim().slice(0, 300)}`);
+            lines.push('');
+        }
+        lines.push('完整内容：直接 Read 文件，或 `sps wiki read "<keyword>"` 找更多。');
+        sections.push(lines.join('\n'));
+    }
+    return sections.join('\n\n---\n\n');
+}
+// ─── Helpers (private) ────────────────────────────────────────────
+function pageToIndexedAdapter(p) {
+    // 复用 searcher 的工厂；这里手写一份避免循环引用复杂度
+    return {
+        pageId: p.pageId,
+        title: p.frontmatter.title,
+        tags: p.frontmatter.tags,
+        tldr: extractTLDR(p.body),
+        body: p.body,
+        type: p.frontmatter.type,
+    };
+}
+function priorityOf(type, source) {
+    // pinned 永远最高（用户/Worker 显式指定）
+    // 其他按类型权重
+    const sourceBonus = source === 'pinned' ? 100 : source === 'skill' ? 10 : 0;
+    return sourceBonus + (TYPE_PRIORITY[type] ?? 1);
+}
+function isStalePage(page) {
+    return page.frontmatter.status === 'stale';
+}
+function applyBudget(entries, hot, indexSummary, budgetTokens) {
+    const baseTokens = estimateChars(hot) + estimateChars(indexSummary);
+    const baseTok = baseTokens / CHARS_PER_TOKEN;
+    if (baseTok >= budgetTokens) {
+        // hot+index 已超预算 → 不加任何 page
+        return [];
+    }
+    const remaining = budgetTokens - baseTok;
+    // 每页 TL;DR 估 ~80 token（300 字符 / 1.5 + 一些 metadata）
+    const PER_PAGE_TOKENS = 80;
+    const maxPages = Math.max(0, Math.floor(remaining / PER_PAGE_TOKENS));
+    if (entries.length <= maxPages)
+        return entries.slice();
+    // 砍法：保留 pinned + skill，只砍 keyword 末尾
+    const pinned = entries.filter((e) => e.source === 'pinned');
+    const skill = entries.filter((e) => e.source === 'skill');
+    const keyword = entries.filter((e) => e.source === 'keyword');
+    const need = Math.max(0, maxPages - pinned.length - skill.length);
+    return [...pinned, ...skill, ...keyword.slice(0, need)];
+}
+function estimateTokens(hot, indexSummary, entries) {
+    const charCount = estimateChars(hot) +
+        estimateChars(indexSummary) +
+        entries.reduce((sum, e) => sum + e.title.length + e.tldr.length + 30, 0);
+    return Math.ceil(charCount / CHARS_PER_TOKEN);
+}
+function estimateChars(s) {
+    return s.length;
+}
+function stripFrontmatter(content) {
+    return content.replace(/^---\r?\n[\s\S]*?\r?\n---\r?\n?/, '');
+}
+function safeRead(fn, fallback) {
+    try {
+        return fn();
+    }
+    catch {
+        return fallback;
+    }
+}
+//# sourceMappingURL=reader.js.map

package/dist/core/wiki/reader.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"reader.js","sourceRoot":"","sources":["../../../src/core/wiki/reader.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;GAyBG;AAEH,OAAO,EAAE,OAAO,EAAE,MAAM,UAAU,CAAC;AACnC,OAAO,EAAE,gBAAgB,EAAE,MAAM,oBAAoB,CAAC;AACtD,OAAO,EAAE,WAAW,EAAE,cAAc,EAAE,MAAM,WAAW,CAAC;AACxD,OAAO,EAAE,WAAW,EAAE,YAAY,EAAE,MAAM,eAAe,CAAC;AAsD1D,MAAM,YAAY,GAA0B;IAC1C,UAAU,EAAE,EAAE;IACd,SAAS,EAAE,CAAC;IACZ,WAAW,EAAE,CAAC;IACd,YAAY,EAAE,IAAI;CACnB,CAAC;AAEF,iBAAiB;AACjB,MAAM,aAAa,GAA6B;IAC9C,MAAM,EAAE,CAAC;IACT,QAAQ,EAAE,CAAC;IACX,OAAO,EAAE,CAAC;IACV,MAAM,EAAE,CAAC;IACT,MAAM,EAAE,CAAC;CACV,CAAC;AAEF,iCAAiC;AACjC,MAAM,eAAe,GAAG,GAAG,CAAC;AAE5B,kEAAkE;AAElE;;;;;;;;;;;;;;GAcG;AACH,MAAM,UAAU,QAAQ,CACtB,KAAgB,EAChB,OAAoB,EAAE;IAEtB,MAAM,GAAG,GAAG,EAAE,GAAG,YAAY,EAAE,GAAG,IAAI,EAAE,CAAC;IAEzC,KAAK;IACL,MAAM,GAAG,GAAG,QAAQ,CAAC,GAAG,EAAE,CAAC,OAAO,CAAC,KAAK,CAAC,OAAO,CAAC,EAAE,EAAE,CAAC,CAAC;IAEvD,KAAK;IACL,MAAM,YAAY,GAAG,QAAQ,CAC3B,GAAG,EAAE,CAAC,gBAAgB,CAAC,KAAK,CAAC,OAAO,EAAE,GAAG,CAAC,UAAU,CAAC,EACrD,EAAE,CACH,CAAC;IAEF,6CAA6C;IAC7C,MAAM,KAAK,GAAG,QAAQ,CAAC,GAAG,EAAE,CAAC,cAAc,CAAC,KAAK,CAAC,OAAO,CAAC,EAAE,EAAE,CAAC,CAAC;IAEhE,aAAa;IACb,MAAM,MAAM,GAAG,CAAC,KAAK,CAAC,WAAW,IAAI,EAAE,CAAC;SACrC,GAAG,CAAC,CAAC,EAAE,EAAE,EAAE,CAAC,WAAW,CAAC,KAAK,CAAC,OAAO,EAAE,EAAE,CAAC,CAAC;SAC3C,MAAM,CAAC,CAAC,CAAC,EAAa,EAAE,CAAC,CAAC,KAAK,IAAI,CAAC,CAAC;IAExC,yDAAyD;IACzD,MAAM,QAAQ,GAAG,IAAI,YAAY,CAAC,KAAK,CAAC,GAAG,CAAC,oBAAoB,CAAC,CAAC,CAAC;IAEnE,YAAY;IACZ,MAAM,OAAO,GAAG,QAAQ;SACrB,YAAY,CAAC,KAAK,CAAC,UAAU,EAAE,GAAG,CAAC,SAAS,CAAC;SAC7C,GAAG,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,EAAE,MAAM,EAAE,CAAC,CAAC,MAAM,EAAE,MAAM,EAAE,OAAgB,EAAE,CAAC,CAAC,CAAC;IAEhE,cAAc;IACd,MAAM,SAAS,GAAG,QAAQ;SACvB,MAAM,CAAC,GAAG,KAAK,CAAC,SAAS,IAAI,KAAK,CAAC,QAAQ,EAAE,EAAE,GAAG,CAAC,WAAW,CAAC;SAC/D,GAAG,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,EAAE,MAAM,EAAE,CAAC,CAAC,MAAM,EAAE,MAAM,EAAE,SAAkB,EAAE,CAAC,CAAC,CAAC;IAElE,8CAA8C;IAC9C,MAAM,KAAK,GAAG,IAAI,GAAG,EAAsD,CAAC;IAC5E,KAAK,MAAM,CAAC,IAAI,MAAM;QAAE,KAAK,CAAC,GAAG,CAAC,CAAC,CAAC,MAAM,EAAE,EAAE,MAAM,EAAE,QAAQ,EAAE,CAAC,CAAC;IAClE,KAAK,MAAM,CAAC,IAAI,OAAO,EAAE,CAAC;QACxB,IAAI,CAAC,KAAK,CAAC,GAAG,CAAC,CAAC,CAAC,MAAM,CAAC;YAAE,KAAK,CAAC,GAAG,CAAC,CAAC,CAAC,MAAM,EAAE,EAAE,MAAM,EAAE,CAAC,CAAC,MAAM,EAAE,CAAC,CAAC;IACtE,CAAC;IACD,KAAK,MAAM,CAAC,IAAI,SAAS,EAAE,CAAC;QAC1B,IAAI,CAAC,KAAK,CAAC,GAAG,CAAC,CAAC,CAAC,MAAM,CAAC;YAAE,KAAK,CAAC,GAAG,CAAC,CAAC,CAAC,MAAM,EAAE,EAAE,MAAM,EAAE,CAAC,CAAC,MAAM,EAAE,CAAC,CAAC;IACtE,CAAC;IAED,qBAAqB;IACrB,MAAM,OAAO,GAAuB,EAAE,CAAC;IACvC,KAAK,MAAM,CAAC,MAAM,EAAE,IAAI,CAAC,IAAI,KAAK,EAAE,CAAC;QACnC,MAAM,IAAI,GAAG,KAAK,CAAC,IAAI,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,MAAM,KAAK,MAAM,CAAC,CAAC;QACpD,IAAI,CAAC,IAAI;YAAE,SAAS;QACpB,IAAI,WAAW,CAAC,IAAI,CAAC;YAAE,SAAS;QAChC,OAAO,CAAC,IAAI,CAAC;YACX,MAAM;YACN,KAAK,EAAE,IAAI,CAAC,WAAW,CAAC,KAAK;YAC7B,IAAI,EAAE,IAAI,CAAC,WAAW,CAAC,IAAI;YAC3B,IAAI,EAAE,WAAW,CAAC,IAAI,CAAC,IAAI,CAAC;YAC5B,MAAM,EAAE,IAAI,CAAC,MAAM;YACnB,QAAQ,EAAE,UAAU,CAAC,IAAI,CAAC,WAAW,CAAC,IAAI,EAAE,IAAI,CAAC,MAAM,CAAC;SACzD,CAAC,CAAC;IACL,CAAC;IAED,QAAQ;IACR,OAAO,CAAC,IAAI,CAAC,CAAC,CAAC,EAAE,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,QAAQ,GAAG,CAAC,CAAC,QAAQ,CAAC,CAAC;IAEhD,2DAA2D;IAC3D,MAAM,OAAO,GAAG,WAAW,CAAC,OAAO,EAAE,GAAG,EAAE,YAAY,EAAE,GAAG,CAAC,YAAY,CAAC,CAAC;IAE1E,MAAM,cAAc,GAAG,cAAc,CAAC,GAAG,EAAE,YAAY,EAAE,OAAO,CAAC,CAAC;IAElE,OAAO;QACL,GAAG;QACH,YAAY;QACZ,KAAK,EAAE,OAAO;QACd,cAAc;KACf,CAAC;AACJ,CAAC;AAED,mEAAmE;AAEnE;;;;;;;;;;;;;GAaG;AACH,MAAM,UAAU,iBAAiB,CAAC,GAAgB;IAChD,MAAM,QAAQ,GAAa,EAAE,CAAC;IAE9B,IAAI,GAAG,CAAC,GAAG,CAAC,IAAI,EAAE,CAAC,MAAM,GAAG,CAAC,EAAE,CAAC;QAC9B,iDAAiD;QACjD,MAAM,OAAO,GAAG,gBAAgB,CAAC,GAAG,CAAC,GAAG,CAAC,CAAC,IAAI,EAAE,CAAC;QACjD,QAAQ,CAAC,IAAI,CAAC,mBAAmB,GAAG,OAAO,CAAC,CAAC;IAC/C,CAAC;IAED,IAAI,GAAG,CAAC,YAAY,CAAC,IAAI,EAAE,CAAC,MAAM,GAAG,CAAC,EAAE,CAAC;QACvC,QAAQ,CAAC,IAAI,CAAC,gBAAgB,GAAG,GAAG,CAAC,YAAY,CAAC,IAAI,EAAE,CAAC,CAAC;IAC5D,CAAC;IAED,IAAI,GAAG,CAAC,KAAK,CAAC,MAAM,GAAG,CAAC,EAAE,CAAC;QACzB,MAAM,KAAK,GAAa,CAAC,YAAY,EAAE,EAAE,CAAC,CAAC;QAC3C,KAAK,MAAM,CAAC,IAAI,GAAG,CAAC,KAAK,EAAE,CAAC;YAC1B,MAAM,GAAG,GAAG,CAAC,CAAC,MAAM,KAAK,QAAQ,CAAC,CAAC,CAAC,WAAW,CAAC,CAAC,CAAC,CAAC,CAAC,MAAM,KAAK,OAAO,CAAC,CAAC,CAAC,WAAW,CAAC,CAAC,CAAC,aAAa,CAAC;YACrG,KAAK,CAAC,IAAI,CAAC,QAAQ,CAAC,CAAC,MAAM,OAAO,CAAC,CAAC,IAAI,KAAK,GAAG,GAAG,CAAC,CAAC;YACrD,KAAK,CAAC,IAAI,CAAC,UAAU,CAAC,CAAC,IAAI,CAAC,OAAO,CAAC,MAAM,EAAE,GAAG,CAAC,CAAC,IAAI,EAAE,CAAC,KAAK,CAAC,CAAC,EAAE,GAAG,CAAC,EAAE,CAAC,CAAC;YACzE,KAAK,CAAC,IAAI,CAAC,EAAE,CAAC,CAAC;QACjB,CAAC;QACD,KAAK,CAAC,IAAI,CAAC,oDAAoD,CAAC,CAAC;QACjE,QAAQ,CAAC,IAAI,CAAC,KAAK,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC,CAAC;IAClC,CAAC;IAED,OAAO,QAAQ,CAAC,IAAI,CAAC,aAAa,CAAC,CAAC;AACtC,CAAC;AAED,qEAAqE;AAErE,SAAS,oBAAoB,CAAC,CAAO;IACnC,kCAAkC;IAClC,OAAO;QACL,MAAM,EAAE,CAAC,CAAC,MAAM;QAChB,KAAK,EAAE,CAAC,CAAC,WAAW,CAAC,KAAK;QAC1B,IAAI,EAAE,CAAC,CAAC,WAAW,CAAC,IAAI;QACxB,IAAI,EAAE,WAAW,CAAC,CAAC,CAAC,IAAI,CAAC;QACzB,IAAI,EAAE,CAAC,CAAC,IAAI;QACZ,IAAI,EAAE,CAAC,CAAC,WAAW,CAAC,IAAI;KACzB,CAAC;AACJ,CAAC;AAED,SAAS,UAAU,CAAC,IAAc,EAAE,MAAsC;IACxE,8BAA8B;IAC9B,UAAU;IACV,MAAM,WAAW,GAAG,MAAM,KAAK,QAAQ,CAAC,CAAC,CAAC,GAAG,CAAC,CAAC,CAAC,MAAM,KAAK,OAAO,CAAC,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC,CAAC,CAAC;IAC5E,OAAO,WAAW,GAAG,CAAC,aAAa,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC,CAAC;AAClD,CAAC;AAED,SAAS,WAAW,CAAC,IAAU;IAC7B,OAAO,IAAI,CAAC,WAAW,CAAC,MAAM,KAAK,OAAO,CAAC;AAC7C,CAAC;AAED,SAAS,WAAW,CAClB,OAAoC,EACpC,GAAW,EACX,YAAoB,EACpB,YAAoB;IAEpB,MAAM,UAAU,GAAG,aAAa,CAAC,GAAG,CAAC,GAAG,aAAa,CAAC,YAAY,CAAC,CAAC;IACpE,MAAM,OAAO,GAAG,UAAU,GAAG,eAAe,CAAC;IAE7C,IAAI,OAAO,IAAI,YAAY,EAAE,CAAC;QAC5B,6BAA6B;QAC7B,OAAO,EAAE,CAAC;IACZ,CAAC;IAED,MAAM,SAAS,GAAG,YAAY,GAAG,OAAO,CAAC;IACzC,mDAAmD;IACnD,MAAM,eAAe,GAAG,EAAE,CAAC;IAC3B,MAAM,QAAQ,GAAG,IAAI,CAAC,GAAG,CAAC,CAAC,EAAE,IAAI,CAAC,KAAK,CAAC,SAAS,GAAG,eAAe,CAAC,CAAC,CAAC;IAEtE,IAAI,OAAO,CAAC,MAAM,IAAI,QAAQ;QAAE,OAAO,OAAO,CAAC,KAAK,EAAE,CAAC;IAEvD,qCAAqC;IACrC,MAAM,MAAM,GAAG,OAAO,CAAC,MAAM,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,MAAM,KAAK,QAAQ,CAAC,CAAC;IAC5D,MAAM,KAAK,GAAG,OAAO,CAAC,MAAM,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,MAAM,KAAK,OAAO,CAAC,CAAC;IAC1D,MAAM,OAAO,GAAG,OAAO,CAAC,MAAM,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,MAAM,KAAK,SAAS,CAAC,CAAC;IAC9D,MAAM,IAAI,GAAG,IAAI,CAAC,GAAG,CAAC,CAAC,EAAE,QAAQ,GAAG,MAAM,CAAC,MAAM,GAAG,KAAK,CAAC,MAAM,CAAC,CAAC;IAClE,OAAO,CAAC,GAAG,MAAM,EAAE,GAAG,KAAK,EAAE,GAAG,OAAO,CAAC,KAAK,CAAC,CAAC,EAAE,IAAI,CAAC,CAAC,CAAC;AAC1D,CAAC;AAED,SAAS,cAAc,CAAC,GAAW,EAAE,YAAoB,EAAE,OAAoC;IAC7F,MAAM,SAAS,GACb,aAAa,CAAC,GAAG,CAAC;QAClB,aAAa,CAAC,YAAY,CAAC;QAC3B,OAAO,CAAC,MAAM,CAAC,CAAC,GAAG,EAAE,CAAC,EAAE,EAAE,CAAC,GAAG,GAAG,CAAC,CAAC,KAAK,CAAC,MAAM,GAAG,CAAC,CAAC,IAAI,CAAC,MAAM,GAAG,EAAE,EAAE,CAAC,CAAC,CAAC;IAC3E,OAAO,IAAI,CAAC,IAAI,CAAC,SAAS,GAAG,eAAe,CAAC,CAAC;AAChD,CAAC;AAED,SAAS,aAAa,CAAC,CAAS;IAC9B,OAAO,CAAC,CAAC,MAAM,CAAC;AAClB,CAAC;AAED,SAAS,gBAAgB,CAAC,OAAe;IACvC,OAAO,OAAO,CAAC,OAAO,CAAC,iCAAiC,EAAE,EAAE,CAAC,CAAC;AAChE,CAAC;AAED,SAAS,QAAQ,CAAI,EAAW,EAAE,QAAW;IAC3C,IAAI,CAAC;QACH,OAAO,EAAE,EAAE,CAAC;IACd,CAAC;IAAC,MAAM,CAAC;QACP,OAAO,QAAQ,CAAC;IAClB,CAAC;AACH,CAAC"}

package/dist/core/wiki/scaffold.d.ts

@@ -0,0 +1,42 @@
+export interface InitWikiOptions {
+    /** Project name used in templates */
+    readonly projectName: string;
+    /** ISO date for created/updated fields (default: today) */
+    readonly today?: string;
+    /** Skip writing .gitignore (default: false) */
+    readonly skipGitignore?: boolean;
+}
+export interface InitWikiReport {
+    /** Wiki dir absolute path */
+    readonly wikiDir: string;
+    /** Subdirs created (already-existing skipped) */
+    readonly created: string[];
+    /** Files written (already-existing skipped) */
+    readonly filesWritten: string[];
+    /** Files left untouched because they already existed */
+    readonly filesSkipped: string[];
+    /** Was .gitignore touched? */
+    readonly gitignoreUpdated: boolean;
+}
+/**
+ * Idempotently scaffold wiki/ in the given repo.
+ *
+ * Creates:
+ *   - wiki/, wiki/{modules,concepts,decisions,lessons,sources}/, wiki/.raw/, wiki/_attachments/
+ *   - wiki/WIKI.md, wiki/index.md, wiki/overview.md, wiki/.hot.md
+ *   - .gitignore: appends per-instance drift entries if missing
+ *
+ * Does NOT write .manifest.json — that's owned by `sps wiki update` and is empty
+ * until first ingest.
+ *
+ * Re-runnable safely: existing files are preserved.
+ */
+export declare function initWiki(repoDir: string, opts: InitWikiOptions): InitWikiReport;
+/**
+ * Append wiki drift entries to .gitignore if missing.
+ *
+ * Returns true when at least one line was appended.
+ * Creates .gitignore if not present.
+ */
+export declare function ensureGitignoreEntries(repoDir: string): boolean;
+//# sourceMappingURL=scaffold.d.ts.map

package/dist/core/wiki/scaffold.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"scaffold.d.ts","sourceRoot":"","sources":["../../../src/core/wiki/scaffold.ts"],"names":[],"mappings":"AAyIA,MAAM,WAAW,eAAe;IAC9B,qCAAqC;IACrC,QAAQ,CAAC,WAAW,EAAE,MAAM,CAAC;IAC7B,2DAA2D;IAC3D,QAAQ,CAAC,KAAK,CAAC,EAAE,MAAM,CAAC;IACxB,+CAA+C;IAC/C,QAAQ,CAAC,aAAa,CAAC,EAAE,OAAO,CAAC;CAClC;AAED,MAAM,WAAW,cAAc;IAC7B,6BAA6B;IAC7B,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAC;IACzB,iDAAiD;IACjD,QAAQ,CAAC,OAAO,EAAE,MAAM,EAAE,CAAC;IAC3B,+CAA+C;IAC/C,QAAQ,CAAC,YAAY,EAAE,MAAM,EAAE,CAAC;IAChC,wDAAwD;IACxD,QAAQ,CAAC,YAAY,EAAE,MAAM,EAAE,CAAC;IAChC,8BAA8B;IAC9B,QAAQ,CAAC,gBAAgB,EAAE,OAAO,CAAC;CACpC;AAED;;;;;;;;;;;;GAYG;AACH,wBAAgB,QAAQ,CAAC,OAAO,EAAE,MAAM,EAAE,IAAI,EAAE,eAAe,GAAG,cAAc,CAiD/E;AAED;;;;;GAKG;AACH,wBAAgB,sBAAsB,CAAC,OAAO,EAAE,MAAM,GAAG,OAAO,CAsC/D"}

package/dist/core/wiki/scaffold.js

@@ -0,0 +1,223 @@
+/**
+ * @module        core/wiki/scaffold
+ * @description   `sps wiki init` 的物理脚手架：建目录、写模板、安装 .gitignore 条目
+ *
+ * @layer         core
+ *
+ * doc-28 §4 目录结构 + §3 三层架构（per-repo）的实施面。
+ *
+ * 设计原则：
+ *   - **幂等**：重复跑不破坏现有内容
+ *   - **不覆盖**：所有写入前先 existsSync 检查
+ *   - **单向同步 .gitignore**：只 append 缺失行，不重排已有内容
+ *
+ * 失败模式：mkdir 失败 → throw（让命令层报错）。
+ */
+import { appendFileSync, existsSync, mkdirSync, readFileSync, writeFileSync } from 'node:fs';
+import { resolve } from 'node:path';
+import { wikiAttachmentsDir, wikiDir, wikiHotFile, wikiIndexFile, wikiMetaFile, wikiOverviewFile, wikiPageDir, wikiRawDir, } from '../../shared/wikiPaths.js';
+// ─── Constants ────────────────────────────────────────────────────
+const ALL_PAGE_TYPES = [
+    'module',
+    'concept',
+    'decision',
+    'lesson',
+    'source',
+];
+/** Lines that wiki ownership requires in .gitignore */
+const GITIGNORE_LINES = [
+    '# Wiki per-instance drift (added by sps wiki init)',
+    'wiki/.hot.md',
+    'wiki/.log.md',
+    'wiki/.manifest.json',
+];
+/**
+ * Default WIKI.md template. Contains schema version + sources config.
+ * Worker reads `sources:` to know what to ingest.
+ */
+function wikiMetaTemplate(projectName, today) {
+    return `---
+type: meta
+title: ${projectName} Wiki
+version: 1
+created: ${today}
+updated: ${today}
+sources:
+  code:
+    - "src/**/*.ts"
+  doc:
+    - "docs/**/*.md"
+    - "README.md"
+  raw:
+    - "wiki/.raw/**/*"
+---
+
+# ${projectName} Wiki
+
+Project knowledge base. See [doc-28](../docs/design/28-wiki-system.md) for design.
+
+## Page Types
+
+- **modules/** — Code modules / services (auto-derived from \`src/\`)
+- **concepts/** — Domain concepts and patterns
+- **decisions/** — Architecture decisions
+- **lessons/** — Bug post-mortems and gotchas
+- **sources/** — External references (PDFs, articles, transcripts)
+
+## Workflow
+
+\`\`\`bash
+sps wiki update <project>          # ingest source diff via Worker + skill
+sps wiki read <project> "query"    # 5-layer retrieval for prompt injection
+\`\`\`
+`;
+}
+const INDEX_PLACEHOLDER = `---
+type: meta
+title: Wiki Index
+updated: 1970-01-01T00:00:00Z
+---
+
+# Wiki Index
+
+(empty — run \`sps wiki update\` to ingest sources)
+`;
+const OVERVIEW_TEMPLATE = (projectName, today) => `---
+type: meta
+title: ${projectName} Overview
+created: ${today}
+updated: ${today}
+---
+
+# ${projectName} Overview
+
+(autogenerated summary — first \`sps wiki update\` will fill this in)
+`;
+const HOT_PLACEHOLDER = `---
+type: meta
+title: Hot Cache
+updated: 1970-01-01T00:00:00Z
+---
+
+# Recent Context
+
+## Last Updated
+（尚无活动。第一次 \`sps wiki update\` 或卡片完成后会自动填充。）
+
+## Key Recent Facts
+（none yet）
+
+## Recent Changes
+（none yet）
+
+## Active Threads
+（none yet）
+`;
+/**
+ * Idempotently scaffold wiki/ in the given repo.
+ *
+ * Creates:
+ *   - wiki/, wiki/{modules,concepts,decisions,lessons,sources}/, wiki/.raw/, wiki/_attachments/
+ *   - wiki/WIKI.md, wiki/index.md, wiki/overview.md, wiki/.hot.md
+ *   - .gitignore: appends per-instance drift entries if missing
+ *
+ * Does NOT write .manifest.json — that's owned by `sps wiki update` and is empty
+ * until first ingest.
+ *
+ * Re-runnable safely: existing files are preserved.
+ */
+export function initWiki(repoDir, opts) {
+    const today = opts.today ?? new Date().toISOString().slice(0, 10);
+    const created = [];
+    const filesWritten = [];
+    const filesSkipped = [];
+    // 1) Subdirs
+    const dirs = [
+        wikiDir(repoDir),
+        ...ALL_PAGE_TYPES.map((t) => wikiPageDir(repoDir, t)),
+        wikiRawDir(repoDir),
+        wikiAttachmentsDir(repoDir),
+    ];
+    for (const d of dirs) {
+        if (!existsSync(d)) {
+            mkdirSync(d, { recursive: true });
+            created.push(d);
+        }
+    }
+    // 2) Templated files (don't overwrite existing user content)
+    const templated = [
+        [wikiMetaFile(repoDir), wikiMetaTemplate(opts.projectName, today)],
+        [wikiIndexFile(repoDir), INDEX_PLACEHOLDER],
+        [wikiOverviewFile(repoDir), OVERVIEW_TEMPLATE(opts.projectName, today)],
+        [wikiHotFile(repoDir), HOT_PLACEHOLDER],
+    ];
+    for (const [path, body] of templated) {
+        if (existsSync(path)) {
+            filesSkipped.push(path);
+        }
+        else {
+            writeFileSync(path, body, { encoding: 'utf-8', mode: 0o644 });
+            filesWritten.push(path);
+        }
+    }
+    // 3) .gitignore — only append missing lines
+    let gitignoreUpdated = false;
+    if (!opts.skipGitignore) {
+        gitignoreUpdated = ensureGitignoreEntries(repoDir);
+    }
+    return {
+        wikiDir: wikiDir(repoDir),
+        created,
+        filesWritten,
+        filesSkipped,
+        gitignoreUpdated,
+    };
+}
+/**
+ * Append wiki drift entries to .gitignore if missing.
+ *
+ * Returns true when at least one line was appended.
+ * Creates .gitignore if not present.
+ */
+export function ensureGitignoreEntries(repoDir) {
+    const gitignorePath = resolve(repoDir, '.gitignore');
+    let existing = '';
+    if (existsSync(gitignorePath)) {
+        existing = readFileSync(gitignorePath, 'utf-8');
+    }
+    const existingLines = new Set(existing.split('\n').map((l) => l.trim()));
+    const toAppend = [];
+    for (const line of GITIGNORE_LINES) {
+        // skip comment header if any drift line already present (we don't want to
+        // re-add the comment if user organized their .gitignore)
+        if (line.startsWith('#'))
+            continue;
+        if (!existingLines.has(line)) {
+            toAppend.push(line);
+        }
+    }
+    if (toAppend.length === 0)
+        return false;
+    // If .gitignore is brand new or empty, include the comment header.
+    const block = [];
+    const needsHeader = !existing.includes('# Wiki per-instance drift');
+    if (existing.length > 0 && !existing.endsWith('\n'))
+        block.push('');
+    if (existing.length > 0)
+        block.push('');
+    if (needsHeader)
+        block.push(GITIGNORE_LINES[0]);
+    block.push(...toAppend);
+    block.push(''); // trailing newline
+    if (existsSync(gitignorePath)) {
+        appendFileSync(gitignorePath, block.join('\n'), { encoding: 'utf-8' });
+    }
+    else {
+        writeFileSync(gitignorePath, block.join('\n').replace(/^\n+/, ''), {
+            encoding: 'utf-8',
+            mode: 0o644,
+        });
+    }
+    return true;
+}
+//# sourceMappingURL=scaffold.js.map

package/dist/core/wiki/scaffold.js.map

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

package/dist/core/wiki/searcher.d.ts

@@ -0,0 +1,73 @@
+/**
+ * @module        core/wiki/searcher
+ * @description   Wiki BM25F 全文检索（field-weighted Best Matching 25）
+ *
+ * @layer         core
+ *
+ * 实现选择：
+ *   - **不**用 lunr.js / minisearch / fuse.js —— 多一个 50KB 依赖不值得
+ *   - **不**做词干提取（stemming）—— SPS 是技术文档库，词形变化少；stemming
+ *     反而把 "Pipeline" 和 "PipelineService" 合并成同一 token，丢辨别力
+ *   - **不**做向量 embedding —— v0 BM25 够用；v1 视召回率决定
+ *
+ * BM25F 通过 field tiling 实现：title 3x / tags 2x / tldr 2x / body 1x
+ * 加权方式 = 该 field 内 token 重复 n 次（等价于 BM25F 的 boosting）。
+ *
+ * 中文支持：ASCII 按词切；中文按字切（朴素 unigram）。够用且无外部依赖。
+ *
+ * 数据规模：项目 wiki 一般 < 1000 page，~MB 级 corpus。in-memory 索引
+ * 占用几 MB，构建 < 100ms，查询 < 10ms。不需要持久化（每次进程启动重建）。
+ */
+import type { Page, PageType } from './types.js';
+export interface BM25Options {
+    /** 词频饱和参数；标准值 1.2-2.0 */
+    k1?: number;
+    /** 长度归一化；0=关 / 0.75=标准 / 1=最大归一 */
+    b?: number;
+    /** 各字段权重 */
+    fieldWeights?: {
+        title?: number;
+        tags?: number;
+        tldr?: number;
+        body?: number;
+    };
+}
+export declare function tokenize(text: string): string[];
+export interface IndexedDoc {
+    readonly pageId: string;
+    readonly title: string;
+    readonly tags: readonly string[];
+    /** 第一段（## TL;DR 之后到下个 ## 之前）；用作字段权重 + 返回值预览 */
+    readonly tldr: string;
+    /** Body 剩余部分（除 TL;DR 之外） */
+    readonly body: string;
+    readonly type: PageType;
+}
+/**
+ * 从 Page 对象抽 IndexedDoc。
+ * TL;DR 提取规则：找 `## TL;DR\n...\n##` 之间的内容；找不到取 body 前 200 字符。
+ */
+export declare function pageToIndexed(page: Page): IndexedDoc;
+export declare function extractTLDR(body: string): string;
+export interface SearchResult {
+    readonly pageId: string;
+    readonly score: number;
+}
+export declare class WikiSearcher {
+    readonly docs: readonly IndexedDoc[];
+    private readonly opts;
+    private readonly postings;
+    private readonly docLengths;
+    private readonly avgDocLength;
+    constructor(docs: readonly IndexedDoc[], opts?: BM25Options);
+    /**
+     * 全字段加权的 token stream。同一个 token 在 title 出现一次 = title weight 个副本。
+     */
+    private tokenizeDoc;
+    search(query: string, limit?: number): SearchResult[];
+    /** 按 tag 集合过滤（OR 语义）—— 用于 reader.ts 的 skill-match layer */
+    searchByTags(tags: readonly string[], limit?: number): SearchResult[];
+    /** 按 type 列出（不打分；reader.ts 排序用） */
+    byType(type: PageType): IndexedDoc[];
+}
+//# sourceMappingURL=searcher.d.ts.map

package/dist/core/wiki/searcher.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"searcher.d.ts","sourceRoot":"","sources":["../../../src/core/wiki/searcher.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;GAmBG;AACH,OAAO,KAAK,EAAE,IAAI,EAAE,QAAQ,EAAE,MAAM,YAAY,CAAC;AAIjD,MAAM,WAAW,WAAW;IAC1B,yBAAyB;IACzB,EAAE,CAAC,EAAE,MAAM,CAAC;IACZ,mCAAmC;IACnC,CAAC,CAAC,EAAE,MAAM,CAAC;IACX,YAAY;IACZ,YAAY,CAAC,EAAE;QACb,KAAK,CAAC,EAAE,MAAM,CAAC;QACf,IAAI,CAAC,EAAE,MAAM,CAAC;QACd,IAAI,CAAC,EAAE,MAAM,CAAC;QACd,IAAI,CAAC,EAAE,MAAM,CAAC;KACf,CAAC;CACH;AAqED,wBAAgB,QAAQ,CAAC,IAAI,EAAE,MAAM,GAAG,MAAM,EAAE,CAW/C;AAID,MAAM,WAAW,UAAU;IACzB,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAC;IACxB,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAC;IACvB,QAAQ,CAAC,IAAI,EAAE,SAAS,MAAM,EAAE,CAAC;IACjC,+CAA+C;IAC/C,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB,4BAA4B;IAC5B,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB,QAAQ,CAAC,IAAI,EAAE,QAAQ,CAAC;CACzB;AAED;;;GAGG;AACH,wBAAgB,aAAa,CAAC,IAAI,EAAE,IAAI,GAAG,UAAU,CASpD;AAID,wBAAgB,WAAW,CAAC,IAAI,EAAE,MAAM,GAAG,MAAM,CAMhD;AAID,MAAM,WAAW,YAAY;IAC3B,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAC;IACxB,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAC;CACxB;AAID,qBAAa,YAAY;aASL,IAAI,EAAE,SAAS,UAAU,EAAE;IAR7C,OAAO,CAAC,QAAQ,CAAC,IAAI,CAEnB;IACF,OAAO,CAAC,QAAQ,CAAC,QAAQ,CAA0C;IACnE,OAAO,CAAC,QAAQ,CAAC,UAAU,CAAgB;IAC3C,OAAO,CAAC,QAAQ,CAAC,YAAY,CAAS;gBAGpB,IAAI,EAAE,SAAS,UAAU,EAAE,EAC3C,IAAI,GAAE,WAAgB;IAqBxB;;OAEG;IACH,OAAO,CAAC,WAAW;IAUnB,MAAM,CAAC,KAAK,EAAE,MAAM,EAAE,KAAK,SAAK,GAAG,YAAY,EAAE;IA2BjD,2DAA2D;IAC3D,YAAY,CAAC,IAAI,EAAE,SAAS,MAAM,EAAE,EAAE,KAAK,SAAK,GAAG,YAAY,EAAE;IAejE,mCAAmC;IACnC,MAAM,CAAC,IAAI,EAAE,QAAQ,GAAG,UAAU,EAAE;CAGrC"}