@coralai/sps-cli 0.50.24 → 0.51.0

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

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

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

@@ -0,0 +1,72 @@
+import { FrontmatterError } from './frontmatter.js';
+import type { Frontmatter, Page, PageType } from './types.js';
+/**
+ * 读单页。文件不存在返 null。frontmatter 损坏抛 FrontmatterError。
+ */
+export declare function readPage(filePath: string): Page | null;
+/**
+ * 读单页（宽松版本）：损坏不抛，返 ParseFailure 标记。
+ * 用于 list 扫描时一页坏不阻塞整体。
+ */
+export type ReadResult = {
+    ok: true;
+    page: Page;
+} | {
+    ok: false;
+    filePath: string;
+    error: FrontmatterError;
+};
+export declare function tryReadPage(filePath: string): ReadResult | null;
+/**
+ * 写一页。父目录不存在自动建。frontmatter 写前 zod 校验（serializeFrontmatter 内部
+ * 假设已校验，这里通过 page.frontmatter 的类型推断保证）。
+ *
+ * - 已存在：覆盖
+ * - 不存在：创建
+ *
+ * 返回写入的最终 filePath（绝对路径）。
+ */
+export declare function writePage(repoDir: string, type: PageType, title: string, frontmatter: Frontmatter, body: string): string;
+/**
+ * 删除一页。文件不存在 = no-op。
+ */
+export declare function deletePage(repoDir: string, type: PageType, title: string): boolean;
+export interface ListOptions {
+    /** 限定类型（默认全部 5 类） */
+    readonly types?: readonly PageType[];
+    /** 是否包含损坏的页（带 ok=false 的 entry）；默认 false（只返成功的） */
+    readonly includeFailures?: boolean;
+}
+/**
+ * 列出指定项目下所有 wiki page。
+ *
+ * 类型 dir 不存在 → 跳过（不算错误，project 可能没创建那种类型）。
+ * 单页损坏 → 默认跳过；includeFailures=true 时保留。
+ */
+export declare function listPages(repoDir: string, opts?: ListOptions): ReadResult[];
+/**
+ * 仅返成功读取的页。语法糖（list 90% 场景）。
+ */
+export declare function listValidPages(repoDir: string, opts?: ListOptions): Page[];
+/**
+ * 按 pageId（如 "modules/PipelineService"）查找 page。
+ * 自动从 id 拆出 type 和 title。
+ */
+export declare function getPageById(repoDir: string, pageId: string): Page | null;
+/**
+ * 按 wikilink "[[Page Name]]" 查找 page。会扫所有 type 直到找到第一个 title 匹配。
+ * 用于解析 frontmatter related 字段或 body 里的 wikilink。
+ *
+ * Wikilink 可以带 type 前缀 "[[modules/PipelineService]]" —— 这种走 getPageById。
+ */
+export declare function findPageByWikilink(repoDir: string, wikilink: string): Page | null;
+/**
+ * 给定文件绝对路径，反推 pageId（type + title）。
+ * 无效路径返 null。
+ */
+export declare function resolvePageId(repoDir: string, filePath: string): {
+    type: PageType;
+    title: string;
+    pageId: string;
+} | null;
+//# sourceMappingURL=page.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"page.d.ts","sourceRoot":"","sources":["../../../src/core/wiki/page.ts"],"names":[],"mappings":"AAoCA,OAAO,EAAE,gBAAgB,EAA0C,MAAM,kBAAkB,CAAC;AAC5F,OAAO,KAAK,EAAE,WAAW,EAAE,IAAI,EAAE,QAAQ,EAAE,MAAM,YAAY,CAAC;AAI9D;;GAEG;AACH,wBAAgB,QAAQ,CAAC,QAAQ,EAAE,MAAM,GAAG,IAAI,GAAG,IAAI,CAWtD;AAWD;;;GAGG;AACH,MAAM,MAAM,UAAU,GAClB;IAAE,EAAE,EAAE,IAAI,CAAC;IAAC,IAAI,EAAE,IAAI,CAAA;CAAE,GACxB;IAAE,EAAE,EAAE,KAAK,CAAC;IAAC,QAAQ,EAAE,MAAM,CAAC;IAAC,KAAK,EAAE,gBAAgB,CAAA;CAAE,CAAC;AAE7D,wBAAgB,WAAW,CAAC,QAAQ,EAAE,MAAM,GAAG,UAAU,GAAG,IAAI,CA0B/D;AAID;;;;;;;;GAQG;AACH,wBAAgB,SAAS,CACvB,OAAO,EAAE,MAAM,EACf,IAAI,EAAE,QAAQ,EACd,KAAK,EAAE,MAAM,EACb,WAAW,EAAE,WAAW,EACxB,IAAI,EAAE,MAAM,GACX,MAAM,CAcR;AAED;;GAEG;AACH,wBAAgB,UAAU,CAAC,OAAO,EAAE,MAAM,EAAE,IAAI,EAAE,QAAQ,EAAE,KAAK,EAAE,MAAM,GAAG,OAAO,CAKlF;AAID,MAAM,WAAW,WAAW;IAC1B,qBAAqB;IACrB,QAAQ,CAAC,KAAK,CAAC,EAAE,SAAS,QAAQ,EAAE,CAAC;IACrC,mDAAmD;IACnD,QAAQ,CAAC,eAAe,CAAC,EAAE,OAAO,CAAC;CACpC;AAUD;;;;;GAKG;AACH,wBAAgB,SAAS,CAAC,OAAO,EAAE,MAAM,EAAE,IAAI,GAAE,WAAgB,GAAG,UAAU,EAAE,CAgC/E;AAED;;GAEG;AACH,wBAAgB,cAAc,CAAC,OAAO,EAAE,MAAM,EAAE,IAAI,GAAE,WAAgB,GAAG,IAAI,EAAE,CAI9E;AAID;;;GAGG;AACH,wBAAgB,WAAW,CAAC,OAAO,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,GAAG,IAAI,GAAG,IAAI,CAYxE;AAED;;;;;GAKG;AACH,wBAAgB,kBAAkB,CAAC,OAAO,EAAE,MAAM,EAAE,QAAQ,EAAE,MAAM,GAAG,IAAI,GAAG,IAAI,CAajF;AAID;;;GAGG;AACH,wBAAgB,aAAa,CAC3B,OAAO,EAAE,MAAM,EACf,QAAQ,EAAE,MAAM,GACf;IAAE,IAAI,EAAE,QAAQ,CAAC;IAAC,KAAK,EAAE,MAAM,CAAC;IAAC,MAAM,EAAE,MAAM,CAAA;CAAE,GAAG,IAAI,CAE1D"}

package/dist/core/wiki/page.js

@@ -0,0 +1,221 @@
+/**
+ * @module        core/wiki/page
+ * @description   Wiki page CRUD：读 / 写 / 列表 / 取
+ *
+ * @layer         core
+ *
+ * 这层负责文件系统操作 + frontmatter 解析。**不做** schema 推断、不做内容生成、
+ * 不做检索——那些是上层 reader/searcher 的事。
+ *
+ * 错误策略：
+ *   - 不存在的 page：返 null，调用方决定怎么处理
+ *   - 损坏的 page（frontmatter 解析失败）：返 ParseFailure，**不抛**——避免一页坏阻塞 list
+ *   - 写入：写前校验 frontmatter，失败时抛 FrontmatterError
+ *
+ * 测试要点：
+ *   - round-trip：write → read → frontmatter / body 等价
+ *   - 损坏 page 不影响 list 其他页
+ *   - parseWikiPageId 反推一致
+ */
+import { existsSync, mkdirSync, readdirSync, readFileSync, rmSync, statSync, writeFileSync, } from 'node:fs';
+import { dirname, resolve } from 'node:path';
+import { parseWikiPageId, wikiPageDir, wikiPageFile, wikiPageId, } from '../../shared/wikiPaths.js';
+import { FrontmatterError, parseFrontmatter, serializeFrontmatter } from './frontmatter.js';
+// ─── 单页读取 ─────────────────────────────────────────────────────
+/**
+ * 读单页。文件不存在返 null。frontmatter 损坏抛 FrontmatterError。
+ */
+export function readPage(filePath) {
+    if (!existsSync(filePath))
+        return null;
+    const content = readFileSync(filePath, 'utf-8');
+    const { frontmatter, body } = parseFrontmatter(content);
+    // 文件路径反推 pageId
+    // 文件路径形如 .../wiki/<type>s/<title>.md ——但我们这里只有绝对 filePath，
+    // 没有 repoDir 上下文。所以 pageId 通过路径基础名推：
+    const pageId = inferPageIdFromPath(filePath, frontmatter);
+    return { pageId, filePath, frontmatter, body };
+}
+/**
+ * 从绝对 filePath + frontmatter.type 推 pageId。
+ * 假设：filePath 形如 `<...>/<type>s/<title>.md`。
+ */
+function inferPageIdFromPath(filePath, fm) {
+    const base = filePath.replace(/\.md$/, '').split('/').pop() ?? fm.title;
+    return wikiPageId(fm.type, base);
+}
+export function tryReadPage(filePath) {
+    if (!existsSync(filePath))
+        return null;
+    let content;
+    try {
+        content = readFileSync(filePath, 'utf-8');
+    }
+    catch (err) {
+        return {
+            ok: false,
+            filePath,
+            error: new FrontmatterError(`read failed: ${errMsg(err)}`, err),
+        };
+    }
+    try {
+        const { frontmatter, body } = parseFrontmatter(content);
+        const pageId = inferPageIdFromPath(filePath, frontmatter);
+        return { ok: true, page: { pageId, filePath, frontmatter, body } };
+    }
+    catch (err) {
+        return {
+            ok: false,
+            filePath,
+            error: err instanceof FrontmatterError
+                ? err
+                : new FrontmatterError(`parse failed: ${errMsg(err)}`, err),
+        };
+    }
+}
+// ─── 单页写入 ─────────────────────────────────────────────────────
+/**
+ * 写一页。父目录不存在自动建。frontmatter 写前 zod 校验（serializeFrontmatter 内部
+ * 假设已校验，这里通过 page.frontmatter 的类型推断保证）。
+ *
+ * - 已存在：覆盖
+ * - 不存在：创建
+ *
+ * 返回写入的最终 filePath（绝对路径）。
+ */
+export function writePage(repoDir, type, title, frontmatter, body) {
+    if (frontmatter.type !== type) {
+        throw new Error(`Page type mismatch: dir says "${type}" but frontmatter says "${frontmatter.type}"`);
+    }
+    const filePath = wikiPageFile(repoDir, type, title);
+    const dir = dirname(filePath);
+    if (!existsSync(dir)) {
+        mkdirSync(dir, { recursive: true });
+    }
+    const content = serializeFrontmatter(frontmatter, body);
+    writeFileSync(filePath, content, { encoding: 'utf-8', mode: 0o644 });
+    return filePath;
+}
+/**
+ * 删除一页。文件不存在 = no-op。
+ */
+export function deletePage(repoDir, type, title) {
+    const filePath = wikiPageFile(repoDir, type, title);
+    if (!existsSync(filePath))
+        return false;
+    rmSync(filePath, { force: true });
+    return true;
+}
+const ALL_PAGE_TYPES = [
+    'module',
+    'concept',
+    'decision',
+    'lesson',
+    'source',
+];
+/**
+ * 列出指定项目下所有 wiki page。
+ *
+ * 类型 dir 不存在 → 跳过（不算错误，project 可能没创建那种类型）。
+ * 单页损坏 → 默认跳过；includeFailures=true 时保留。
+ */
+export function listPages(repoDir, opts = {}) {
+    const types = opts.types ?? ALL_PAGE_TYPES;
+    const out = [];
+    for (const t of types) {
+        const dir = wikiPageDir(repoDir, t);
+        if (!existsSync(dir))
+            continue;
+        let entries;
+        try {
+            entries = readdirSync(dir);
+        }
+        catch {
+            continue;
+        }
+        for (const name of entries) {
+            if (!name.endsWith('.md'))
+                continue;
+            // _index.md 是辅助索引，不算 page
+            if (name.startsWith('_'))
+                continue;
+            const filePath = resolve(dir, name);
+            try {
+                const stat = statSync(filePath);
+                if (!stat.isFile())
+                    continue;
+            }
+            catch {
+                continue;
+            }
+            const result = tryReadPage(filePath);
+            if (!result)
+                continue;
+            if (!result.ok && !opts.includeFailures)
+                continue;
+            out.push(result);
+        }
+    }
+    return out;
+}
+/**
+ * 仅返成功读取的页。语法糖（list 90% 场景）。
+ */
+export function listValidPages(repoDir, opts = {}) {
+    return listPages(repoDir, { ...opts, includeFailures: false })
+        .filter((r) => r.ok)
+        .map((r) => r.page);
+}
+// ─── 按 id 取 ─────────────────────────────────────────────────────
+/**
+ * 按 pageId（如 "modules/PipelineService"）查找 page。
+ * 自动从 id 拆出 type 和 title。
+ */
+export function getPageById(repoDir, pageId) {
+    const slashIdx = pageId.indexOf('/');
+    if (slashIdx === -1)
+        return null;
+    const typeWithS = pageId.slice(0, slashIdx);
+    const title = pageId.slice(slashIdx + 1);
+    // typeWithS 是复数（"modules"），去 s 得到 type
+    if (!typeWithS.endsWith('s'))
+        return null;
+    const type = typeWithS.slice(0, -1);
+    if (!ALL_PAGE_TYPES.includes(type))
+        return null;
+    const filePath = wikiPageFile(repoDir, type, title);
+    return readPage(filePath);
+}
+/**
+ * 按 wikilink "[[Page Name]]" 查找 page。会扫所有 type 直到找到第一个 title 匹配。
+ * 用于解析 frontmatter related 字段或 body 里的 wikilink。
+ *
+ * Wikilink 可以带 type 前缀 "[[modules/PipelineService]]" —— 这种走 getPageById。
+ */
+export function findPageByWikilink(repoDir, wikilink) {
+    const stripped = wikilink.replace(/^\[\[/, '').replace(/\]\]$/, '');
+    if (stripped.includes('/')) {
+        return getPageById(repoDir, stripped);
+    }
+    // 无前缀：扫所有 type 找 title 匹配（注意可能多个 type 同名，按数组顺序取第一个）
+    for (const type of ALL_PAGE_TYPES) {
+        const filePath = wikiPageFile(repoDir, type, stripped);
+        if (existsSync(filePath)) {
+            return readPage(filePath);
+        }
+    }
+    return null;
+}
+// ─── 反向查询：路径 → page meta ───────────────────────────────────
+/**
+ * 给定文件绝对路径，反推 pageId（type + title）。
+ * 无效路径返 null。
+ */
+export function resolvePageId(repoDir, filePath) {
+    return parseWikiPageId(repoDir, filePath);
+}
+// ─── helpers ──────────────────────────────────────────────────────
+function errMsg(err) {
+    return err instanceof Error ? err.message : String(err);
+}
+//# sourceMappingURL=page.js.map

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

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

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

@@ -0,0 +1,102 @@
+/**
+ * @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 type { PageType } from './types.js';
+export interface ReadInput {
+    /** Repo 根目录（用于查 wiki/） */
+    readonly repoDir: string;
+    /** 当前卡片 title + description（用作 BM25 查询） */
+    readonly cardTitle: string;
+    readonly cardDesc: string;
+    /** 卡 frontmatter 的 skills（用作 tag 匹配） */
+    readonly cardSkills: readonly string[];
+    /** 卡 labels（暂未用，预留扩展） */
+    readonly cardLabels?: readonly string[];
+    /** 卡 frontmatter wiki_pages 显式 pin 的 page ids */
+    readonly pinnedPages?: readonly string[];
+}
+export interface PageContextEntry {
+    readonly pageId: string;
+    readonly title: string;
+    readonly type: PageType;
+    readonly tldr: string;
+    /** 命中来源——用于 prompt 渲染时分组显示 */
+    readonly source: 'pinned' | 'skill' | 'keyword';
+    /** 内部排序权重（debug） */
+    readonly priority: number;
+}
+export interface WikiContext {
+    /** L1: hot.md 全文 */
+    readonly hot: string;
+    /** L2: index.md 节选 top-N 行 */
+    readonly indexSummary: string;
+    /** L3+L4+L5 合并去重 + 预算后的 page 列表 */
+    readonly pages: readonly PageContextEntry[];
+    /** 可观察性：本次注入的 token 预估 */
+    readonly tokensEstimate: number;
+}
+export interface ReadOptions {
+    /** Layer 2 节选行数（默认 30） */
+    readonly indexLines?: number;
+    /** Layer 4 skill 命中 top-N（默认 3） */
+    readonly skillTopN?: number;
+    /** Layer 5 keyword 命中 top-N（默认 3） */
+    readonly keywordTopN?: number;
+    /** Token 预算硬上限（默认 2000） */
+    readonly budgetTokens?: number;
+}
+/**
+ * 读取 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 declare function wikiRead(input: ReadInput, opts?: ReadOptions): WikiContext;
+/**
+ * WikiContext → prompt 注入 markdown。
+ *
+ * 格式（doc-28 §10）：
+ *   # 项目知识 - 当前状态
+ *   <hot.md 全文>
+ *   ---
+ *   # 知识地图（节选）
+ *   <index summary>
+ *   ---
+ *   # 与本任务相关的页
+ *   ## [[id]] (type) [via source]
+ *   TL;DR: ...
+ */
+export declare function formatWikiContext(ctx: WikiContext): string;
+//# sourceMappingURL=reader.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"reader.d.ts","sourceRoot":"","sources":["../../../src/core/wiki/reader.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;GAyBG;AAMH,OAAO,KAAK,EAAQ,QAAQ,EAAE,MAAM,YAAY,CAAC;AAIjD,MAAM,WAAW,SAAS;IACxB,0BAA0B;IAC1B,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAC;IACzB,2CAA2C;IAC3C,QAAQ,CAAC,SAAS,EAAE,MAAM,CAAC;IAC3B,QAAQ,CAAC,QAAQ,EAAE,MAAM,CAAC;IAC1B,wCAAwC;IACxC,QAAQ,CAAC,UAAU,EAAE,SAAS,MAAM,EAAE,CAAC;IACvC,yBAAyB;IACzB,QAAQ,CAAC,UAAU,CAAC,EAAE,SAAS,MAAM,EAAE,CAAC;IACxC,iDAAiD;IACjD,QAAQ,CAAC,WAAW,CAAC,EAAE,SAAS,MAAM,EAAE,CAAC;CAC1C;AAED,MAAM,WAAW,gBAAgB;IAC/B,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAC;IACxB,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAC;IACvB,QAAQ,CAAC,IAAI,EAAE,QAAQ,CAAC;IACxB,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB,8BAA8B;IAC9B,QAAQ,CAAC,MAAM,EAAE,QAAQ,GAAG,OAAO,GAAG,SAAS,CAAC;IAChD,oBAAoB;IACpB,QAAQ,CAAC,QAAQ,EAAE,MAAM,CAAC;CAC3B;AAED,MAAM,WAAW,WAAW;IAC1B,oBAAoB;IACpB,QAAQ,CAAC,GAAG,EAAE,MAAM,CAAC;IACrB,8BAA8B;IAC9B,QAAQ,CAAC,YAAY,EAAE,MAAM,CAAC;IAC9B,mCAAmC;IACnC,QAAQ,CAAC,KAAK,EAAE,SAAS,gBAAgB,EAAE,CAAC;IAC5C,0BAA0B;IAC1B,QAAQ,CAAC,cAAc,EAAE,MAAM,CAAC;CACjC;AAID,MAAM,WAAW,WAAW;IAC1B,0BAA0B;IAC1B,QAAQ,CAAC,UAAU,CAAC,EAAE,MAAM,CAAC;IAC7B,mCAAmC;IACnC,QAAQ,CAAC,SAAS,CAAC,EAAE,MAAM,CAAC;IAC5B,qCAAqC;IACrC,QAAQ,CAAC,WAAW,CAAC,EAAE,MAAM,CAAC;IAC9B,2BAA2B;IAC3B,QAAQ,CAAC,YAAY,CAAC,EAAE,MAAM,CAAC;CAChC;AAuBD;;;;;;;;;;;;;;GAcG;AACH,wBAAgB,QAAQ,CACtB,KAAK,EAAE,SAAS,EAChB,IAAI,GAAE,WAAgB,GACrB,WAAW,CAyEb;AAID;;;;;;;;;;;;;GAaG;AACH,wBAAgB,iBAAiB,CAAC,GAAG,EAAE,WAAW,GAAG,MAAM,CA0B1D"}

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":"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"}