trove-cli 0.0.0-stage → 0.2.0

package/dist/core/lessons/sidecar.js

@@ -0,0 +1,171 @@
+import { parseFrontmatter, stripFrontmatter } from './frontmatter.js';
+export const SIDECAR_DIRS = [
+    { path: '', name: '学习沉淀概览', brief: '从 AI 会话沉淀的可复用经验与偏好，按偏好、实体、经验、决策、资源五类分层组织。' },
+    { path: 'preferences', name: '用户偏好', brief: '用户偏好配置库，聚焦用户画像、编码风格、写作风格、对话风格与最近事项等个人偏好，回答时自动套用。' },
+    { path: 'entities', name: '实体库', brief: '实体库，卡片式记录项目、人物、组织、工具与技术栈等长期有效的事实。' },
+    { path: 'experiences', name: '经验库', brief: '经验库，沉淀调试模式、操作流程、陷阱坑与纠正教训等可复用经验。' },
+    { path: 'events', name: '决策记录', brief: '决策记录，归档用户拍板的方向与取舍及当时的背景。' },
+    { path: 'resources', name: '资料库', brief: '资料库，收录文档、代码仓库与链接等外部资料。' },
+];
+const COMPONENT = 'ExtractionPipeline';
+const THRESHOLD = 0.1;
+/** 各目录下需要稳定列出的子目录(带中文标签);叶子目录(偏好/经验/决策)只列直接文件。 */
+const SUBDIRS = {
+    '': [
+        { name: 'preferences', label: '用户偏好' },
+        { name: 'entities', label: '实体库' },
+        { name: 'experiences', label: '经验库' },
+        { name: 'events', label: '决策记录' },
+        { name: 'resources', label: '资料库' },
+    ],
+    entities: [
+        { name: 'projects', label: '项目' },
+        { name: 'people', label: '人物' },
+        { name: 'organizations', label: '组织' },
+        { name: 'tools', label: '工具' },
+        { name: 'tech', label: '技术栈' },
+    ],
+    resources: [
+        { name: 'docs', label: '文档' },
+        { name: 'repos', label: '仓库' },
+        { name: 'links', label: '链接' },
+    ],
+};
+function joinRel(path, name) {
+    return path ? `${path}/${name}` : name;
+}
+function directoryField(path) {
+    return path ? `lessons/${path}/` : 'lessons/';
+}
+function sidecarDir(path) {
+    return SIDECAR_DIRS.find((d) => d.path === path);
+}
+/** 从 L1 提取 Brief(H1 之后、首个 ## 之前的那段话),作为 L0 正文的唯一来源。 */
+export function extractBrief(overviewText) {
+    const body = stripFrontmatter(overviewText) ?? overviewText;
+    const lines = body.split('\n');
+    let i = 0;
+    while (i < lines.length && (lines[i].trim() === '' || lines[i].startsWith('# ')))
+        i++;
+    const out = [];
+    while (i < lines.length && !lines[i].startsWith('##')) {
+        out.push(lines[i]);
+        i++;
+    }
+    return out.join('\n').trim();
+}
+/** 强制重建根 + 5 大类目录的 sidecar;返回写入的相对路径。 */
+export async function refreshSidecars(storage, opts = {}) {
+    const written = [];
+    // 自底向上:叶子类目录在前,根在后。
+    for (const d of [...SIDECAR_DIRS].reverse()) {
+        written.push(...(await refreshOne(storage, d, opts)));
+    }
+    return written;
+}
+/** 写入记忆后标记目录变脏:L0/L1 未跨 10% 阈值时只递增 pending,否则整目录刷新。 */
+export async function touchSidecars(storage, dirPaths, opts = {}) {
+    const written = [];
+    for (const p of dirPaths) {
+        const d = sidecarDir(p);
+        const overviewPath = joinRel(p, '.overview.md');
+        const existing = await storage.read(overviewPath);
+        if (existing === null) {
+            written.push(...(await refreshOne(storage, d, opts)));
+            continue;
+        }
+        const pending = fieldInt(existing, 'pending_child_changes') + 1;
+        const total = fieldInt(existing, 'total_entries');
+        if (total === 0 || pending / total >= THRESHOLD) {
+            written.push(...(await refreshOne(storage, d, opts)));
+        }
+        else {
+            await storage.write(overviewPath, setField(existing, 'pending_child_changes', pending));
+            written.push(overviewPath);
+        }
+    }
+    return written;
+}
+async function refreshOne(storage, d, opts) {
+    const nav = await buildNav(storage, d);
+    const meta = {
+        component: COMPONENT,
+        trigger: opts.trigger ?? 'manual_refresh',
+        totalEntries: nav.length,
+        pendingChildChanges: 0,
+        updatedAt: (opts.now ?? (() => new Date()))().toISOString(),
+    };
+    const overviewPath = joinRel(d.path, '.overview.md');
+    const abstractPath = joinRel(d.path, '.abstract.md');
+    const overview = renderOverview(d, nav, meta);
+    const abstract = renderAbstract(d, overview, meta);
+    await storage.write(overviewPath, overview);
+    await storage.write(abstractPath, abstract);
+    return [overviewPath, abstractPath];
+}
+async function buildNav(storage, d) {
+    const lines = [];
+    for (const sub of SUBDIRS[d.path] ?? []) {
+        const count = (await storage.list(joinRel(d.path, sub.name))).filter((f) => !isSidecarOrIndex(f)).length;
+        lines.push(`- \`${sub.name}/\`: ${sub.label}（${count} 个文件）`);
+    }
+    for (const f of await directFiles(storage, d.path)) {
+        lines.push(`- \`${f}\`: ${await describeFile(storage, joinRel(d.path, f))}`);
+    }
+    return lines;
+}
+async function directFiles(storage, path) {
+    const files = await storage.list(path);
+    const prefix = path ? `${path}/` : '';
+    const out = [];
+    for (const f of files) {
+        const rel = prefix ? (f.startsWith(prefix) ? f.slice(prefix.length) : '') : f;
+        if (!rel || rel.startsWith('.') || rel === 'INDEX.md' || rel === 'README.md' || rel.includes('/') || !rel.endsWith('.md'))
+            continue;
+        out.push(rel);
+    }
+    return out.sort();
+}
+async function describeFile(storage, path) {
+    const text = (await storage.read(path)) ?? '';
+    const title = parseFrontmatter(text)?.title;
+    if (title)
+        return title;
+    const body = stripFrontmatter(text) ?? text;
+    const first = body.split('\n').find((l) => l.trim())?.trim() ?? '';
+    return first.length > 60 ? `${first.slice(0, 60)}…` : first;
+}
+function isSidecarOrIndex(path) {
+    const base = path.split('/').pop();
+    return base === '.abstract.md' || base === '.overview.md' || base === 'INDEX.md';
+}
+function renderOverview(d, nav, meta) {
+    return (renderSidecarFrontmatter(directoryField(d.path), meta) +
+        `# ${d.name}\n\n${d.brief}\n\n## Quick Navigation\n${nav.join('\n')}\n`);
+}
+function renderAbstract(d, overview, meta) {
+    return renderSidecarFrontmatter(directoryField(d.path), meta) + `${extractBrief(overview)}\n`;
+}
+function renderSidecarFrontmatter(directory, meta) {
+    return [
+        '---',
+        `directory: ${directory}`,
+        'generated_by:',
+        `  component: ${meta.component}`,
+        `  trigger: ${meta.trigger}`,
+        'freshness:',
+        `  total_entries: ${meta.totalEntries}`,
+        `  pending_child_changes: ${meta.pendingChildChanges}`,
+        `updated_at: ${meta.updatedAt}`,
+        '---',
+        '',
+    ].join('\n');
+}
+function fieldInt(text, key) {
+    const m = text.match(new RegExp(`^\\s*${key}:\\s*(\\d+)\\s*$`, 'm'));
+    return m ? Number(m[1]) : 0;
+}
+function setField(text, key, value) {
+    return text.replace(new RegExp(`^(\\s*${key}:)\\s*\\d+\\s*$`, 'm'), `$1 ${value}`);
+}
+//# sourceMappingURL=sidecar.js.map

package/dist/core/lessons/sidecar.js.map

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

package/dist/core/lessons/storage.d.ts

@@ -0,0 +1,21 @@
+export interface StorageAdapter {
+    /** 读取文本;不存在返回 null。 */
+    read(path: string): Promise<string | null>;
+    /** 覆盖写入文本(自动建父目录)。 */
+    write(path: string, text: string): Promise<void>;
+    exists(path: string): Promise<boolean>;
+    /** 删除文件;不存在静默成功。 */
+    delete(path: string): Promise<void>;
+    /** 递归列出 prefix 下的相对文件路径(`/` 分隔);不存在返回空数组。 */
+    list(prefix?: string): Promise<string[]>;
+}
+export declare class LocalStorageAdapter implements StorageAdapter {
+    private root;
+    constructor(root: string);
+    private abs;
+    read(path: string): Promise<string | null>;
+    exists(path: string): Promise<boolean>;
+    write(path: string, text: string): Promise<void>;
+    delete(path: string): Promise<void>;
+    list(prefix?: string): Promise<string[]>;
+}

package/dist/core/lessons/storage.js

@@ -0,0 +1,65 @@
+/** lessons 落盘的最小文本读写抽象。本地实现直接 fs;远端由现有 sync 引擎(RemoteStore)承担,不在此重复。 */
+import { randomUUID } from 'node:crypto';
+import { constants } from 'node:fs';
+import { access, mkdir, readFile, readdir, rename, rm, writeFile } from 'node:fs/promises';
+import { dirname, join } from 'node:path';
+export class LocalStorageAdapter {
+    root;
+    constructor(root) {
+        this.root = root;
+    }
+    abs(path) {
+        return join(this.root, path);
+    }
+    async read(path) {
+        try {
+            return await readFile(this.abs(path), 'utf8');
+        }
+        catch (err) {
+            if (err.code === 'ENOENT')
+                return null;
+            throw err;
+        }
+    }
+    async exists(path) {
+        try {
+            await access(this.abs(path), constants.F_OK);
+            return true;
+        }
+        catch {
+            return false;
+        }
+    }
+    async write(path, text) {
+        const abs = this.abs(path);
+        await mkdir(dirname(abs), { recursive: true });
+        const tmp = `${abs}.tmp-${randomUUID()}`;
+        await writeFile(tmp, text, 'utf8');
+        await rename(tmp, abs);
+    }
+    async delete(path) {
+        await rm(this.abs(path), { force: true });
+    }
+    async list(prefix = '') {
+        const out = [];
+        const walk = async (dir, rel) => {
+            let entries;
+            try {
+                entries = await readdir(dir, { withFileTypes: true });
+            }
+            catch {
+                return; // 目录不存在
+            }
+            for (const e of entries) {
+                const p = rel ? `${rel}/${e.name}` : e.name;
+                if (e.isDirectory())
+                    await walk(join(dir, e.name), p);
+                else if (e.isFile())
+                    out.push(p);
+            }
+        };
+        await walk(this.abs(prefix), prefix);
+        return out;
+    }
+}
+//# sourceMappingURL=storage.js.map

package/dist/core/lessons/storage.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"storage.js","sourceRoot":"","sources":["../../../src/core/lessons/storage.ts"],"names":[],"mappings":"AAAA,wEAAwE;AACxE,OAAO,EAAE,UAAU,EAAE,MAAM,aAAa,CAAC;AACzC,OAAO,EAAE,SAAS,EAAE,MAAM,SAAS,CAAC;AACpC,OAAO,EAAE,MAAM,EAAE,KAAK,EAAE,QAAQ,EAAE,OAAO,EAAE,MAAM,EAAE,EAAE,EAAE,SAAS,EAAE,MAAM,kBAAkB,CAAC;AAC3F,OAAO,EAAE,OAAO,EAAE,IAAI,EAAE,MAAM,WAAW,CAAC;AAc1C,MAAM,OAAO,mBAAmB;IACV;IAApB,YAAoB,IAAY;QAAZ,SAAI,GAAJ,IAAI,CAAQ;IAAG,CAAC;IAE5B,GAAG,CAAC,IAAY;QACtB,OAAO,IAAI,CAAC,IAAI,CAAC,IAAI,EAAE,IAAI,CAAC,CAAC;IAC/B,CAAC;IAED,KAAK,CAAC,IAAI,CAAC,IAAY;QACrB,IAAI,CAAC;YACH,OAAO,MAAM,QAAQ,CAAC,IAAI,CAAC,GAAG,CAAC,IAAI,CAAC,EAAE,MAAM,CAAC,CAAC;QAChD,CAAC;QAAC,OAAO,GAAG,EAAE,CAAC;YACb,IAAK,GAA6B,CAAC,IAAI,KAAK,QAAQ;gBAAE,OAAO,IAAI,CAAC;YAClE,MAAM,GAAG,CAAC;QACZ,CAAC;IACH,CAAC;IAED,KAAK,CAAC,MAAM,CAAC,IAAY;QACvB,IAAI,CAAC;YACH,MAAM,MAAM,CAAC,IAAI,CAAC,GAAG,CAAC,IAAI,CAAC,EAAE,SAAS,CAAC,IAAI,CAAC,CAAC;YAC7C,OAAO,IAAI,CAAC;QACd,CAAC;QAAC,MAAM,CAAC;YACP,OAAO,KAAK,CAAC;QACf,CAAC;IACH,CAAC;IAED,KAAK,CAAC,KAAK,CAAC,IAAY,EAAE,IAAY;QACpC,MAAM,GAAG,GAAG,IAAI,CAAC,GAAG,CAAC,IAAI,CAAC,CAAC;QAC3B,MAAM,KAAK,CAAC,OAAO,CAAC,GAAG,CAAC,EAAE,EAAE,SAAS,EAAE,IAAI,EAAE,CAAC,CAAC;QAC/C,MAAM,GAAG,GAAG,GAAG,GAAG,QAAQ,UAAU,EAAE,EAAE,CAAC;QACzC,MAAM,SAAS,CAAC,GAAG,EAAE,IAAI,EAAE,MAAM,CAAC,CAAC;QACnC,MAAM,MAAM,CAAC,GAAG,EAAE,GAAG,CAAC,CAAC;IACzB,CAAC;IAED,KAAK,CAAC,MAAM,CAAC,IAAY;QACvB,MAAM,EAAE,CAAC,IAAI,CAAC,GAAG,CAAC,IAAI,CAAC,EAAE,EAAE,KAAK,EAAE,IAAI,EAAE,CAAC,CAAC;IAC5C,CAAC;IAED,KAAK,CAAC,IAAI,CAAC,MAAM,GAAG,EAAE;QACpB,MAAM,GAAG,GAAa,EAAE,CAAC;QACzB,MAAM,IAAI,GAAG,KAAK,EAAE,GAAW,EAAE,GAAW,EAAiB,EAAE;YAC7D,IAAI,OAAO,CAAC;YACZ,IAAI,CAAC;gBACH,OAAO,GAAG,MAAM,OAAO,CAAC,GAAG,EAAE,EAAE,aAAa,EAAE,IAAI,EAAE,CAAC,CAAC;YACxD,CAAC;YAAC,MAAM,CAAC;gBACP,OAAO,CAAC,QAAQ;YAClB,CAAC;YACD,KAAK,MAAM,CAAC,IAAI,OAAO,EAAE,CAAC;gBACxB,MAAM,CAAC,GAAG,GAAG,CAAC,CAAC,CAAC,GAAG,GAAG,IAAI,CAAC,CAAC,IAAI,EAAE,CAAC,CAAC,CAAC,CAAC,CAAC,IAAI,CAAC;gBAC5C,IAAI,CAAC,CAAC,WAAW,EAAE;oBAAE,MAAM,IAAI,CAAC,IAAI,CAAC,GAAG,EAAE,CAAC,CAAC,IAAI,CAAC,EAAE,CAAC,CAAC,CAAC;qBACjD,IAAI,CAAC,CAAC,MAAM,EAAE;oBAAE,GAAG,CAAC,IAAI,CAAC,CAAC,CAAC,CAAC;YACnC,CAAC;QACH,CAAC,CAAC;QACF,MAAM,IAAI,CAAC,IAAI,CAAC,GAAG,CAAC,MAAM,CAAC,EAAE,MAAM,CAAC,CAAC;QACrC,OAAO,GAAG,CAAC;IACb,CAAC;CACF"}

package/dist/core/lessons/usage.d.ts

@@ -0,0 +1,31 @@
+/** 单次 LLM 调用的用量与来源任务(如 learn:summarize)。 */
+export interface LlmUsage {
+    task: string;
+    model: string;
+    promptTokens: number;
+    completionTokens: number;
+    totalTokens: number;
+}
+export interface UsageRecord extends LlmUsage {
+    /** 记录时间,ISO-8601;由 sink 写入时打点。 */
+    at: string;
+}
+export type UsageSink = (usage: LlmUsage) => void | Promise<void>;
+/** 追加写 sink:目录不存在自建,单行 JSON;写失败由调用方决定是否忽略。 */
+export declare function createUsageSink(path: string, now?: () => Date): UsageSink;
+/** 读取台账;文件不存在或单行损坏都跳过,不阻断统计。 */
+export declare function readUsageRecords(path: string): Promise<UsageRecord[]>;
+export interface UsageBucket {
+    calls: number;
+    promptTokens: number;
+    completionTokens: number;
+    totalTokens: number;
+}
+export interface UsageSummary {
+    total: UsageBucket;
+    byTask: Record<string, UsageBucket>;
+    byModel: Record<string, UsageBucket>;
+}
+export declare function summarizeUsage(records: Iterable<UsageRecord>): UsageSummary;
+/** CLI 展示:总计 + 按任务/模型分组。 */
+export declare function formatUsageSummary(summary: UsageSummary, since?: string): string[];

package/dist/core/lessons/usage.js

@@ -0,0 +1,91 @@
+/** trove 自身调用 LLM 的 token 用量台账:一次调用一行,只追加到 usage.jsonl。 */
+import { appendFile, mkdir, readFile } from 'node:fs/promises';
+import { dirname } from 'node:path';
+/** 追加写 sink:目录不存在自建,单行 JSON;写失败由调用方决定是否忽略。 */
+export function createUsageSink(path, now = () => new Date()) {
+    // shortcut: 台账只追加不轮转,单行约 150B;增长到数十万行影响读取时再加轮转。
+    return async (usage) => {
+        const record = { at: now().toISOString(), ...usage };
+        await mkdir(dirname(path), { recursive: true });
+        await appendFile(path, `${JSON.stringify(record)}\n`, 'utf8');
+    };
+}
+/** 读取台账;文件不存在或单行损坏都跳过,不阻断统计。 */
+export async function readUsageRecords(path) {
+    let text;
+    try {
+        text = await readFile(path, 'utf8');
+    }
+    catch (err) {
+        if (err.code === 'ENOENT')
+            return [];
+        throw err;
+    }
+    const out = [];
+    for (const line of text.split('\n')) {
+        if (!line.trim())
+            continue;
+        try {
+            const r = JSON.parse(line);
+            if (typeof r.at !== 'string' || typeof r.task !== 'string' || typeof r.model !== 'string')
+                continue;
+            out.push({
+                at: r.at,
+                task: r.task,
+                model: r.model,
+                promptTokens: nonNegative(r.promptTokens),
+                completionTokens: nonNegative(r.completionTokens),
+                totalTokens: nonNegative(r.totalTokens),
+            });
+        }
+        catch {
+            // 损坏行跳过
+        }
+    }
+    return out;
+}
+export function summarizeUsage(records) {
+    const total = emptyBucket();
+    const byTask = {};
+    const byModel = {};
+    for (const r of records) {
+        addTo(total, r);
+        addTo((byTask[r.task] ??= emptyBucket()), r);
+        addTo((byModel[r.model] ??= emptyBucket()), r);
+    }
+    return { total, byTask, byModel };
+}
+const NUMBER = new Intl.NumberFormat('en-US');
+/** CLI 展示:总计 + 按任务/模型分组。 */
+export function formatUsageSummary(summary, since = 'all') {
+    if (summary.total.calls === 0)
+        return ['暂无 LLM 用量记录'];
+    return [
+        `LLM 用量(${since}): ${NUMBER.format(summary.total.calls)} 次调用 · ` +
+            `输入 ${NUMBER.format(summary.total.promptTokens)} · 输出 ${NUMBER.format(summary.total.completionTokens)} · ` +
+            `合计 ${NUMBER.format(summary.total.totalTokens)} tokens`,
+        '按任务:',
+        ...formatBuckets(summary.byTask),
+        '按模型:',
+        ...formatBuckets(summary.byModel),
+    ];
+}
+function formatBuckets(buckets) {
+    return Object.entries(buckets)
+        .sort(([an, a], [bn, b]) => b.totalTokens - a.totalTokens || an.localeCompare(bn))
+        .map(([name, b]) => `  ${name} · ${NUMBER.format(b.calls)} 次 · 输入 ${NUMBER.format(b.promptTokens)} · ` +
+        `输出 ${NUMBER.format(b.completionTokens)} · 合计 ${NUMBER.format(b.totalTokens)}`);
+}
+function emptyBucket() {
+    return { calls: 0, promptTokens: 0, completionTokens: 0, totalTokens: 0 };
+}
+function addTo(bucket, r) {
+    bucket.calls++;
+    bucket.promptTokens += r.promptTokens;
+    bucket.completionTokens += r.completionTokens;
+    bucket.totalTokens += r.totalTokens;
+}
+function nonNegative(v) {
+    return typeof v === 'number' && Number.isFinite(v) && v >= 0 ? v : 0;
+}
+//# sourceMappingURL=usage.js.map

package/dist/core/lessons/usage.js.map

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

package/dist/core/lessons/write.d.ts

@@ -0,0 +1,18 @@
+/** 阶段 7:把阶段 6 的操作落盘为 .md 文件,并同步 INDEX.md 与 .overview.md。 */
+import type { MemoryOp } from './merge.js';
+import type { StorageAdapter } from './storage.js';
+export interface WriteDeps {
+    storage: StorageAdapter;
+    /** 可控时钟,便于测试 updated_at 变化;缺省用系统时间。 */
+    now?: () => Date;
+    /** 记忆来源会话标识(harness:session 或 session id),写入 frontmatter.source。 */
+    source?: string;
+}
+export interface ApplyResult {
+    added: string[];
+    updated: string[];
+    appended: string[];
+    archived: string[];
+    skipped: string[];
+}
+export declare function applyOperations(ops: MemoryOp[], deps: WriteDeps): Promise<ApplyResult>;

package/dist/core/lessons/write.js

@@ -0,0 +1,131 @@
+import { renderFrontmatter } from './frontmatter.js';
+import { INDEX_TEMPLATE } from './layout.js';
+import { touchSidecars } from './sidecar.js';
+const SECTION = {
+    preferences: 'Preferences',
+    entities: 'Entities',
+    experiences: 'Experiences',
+    events: 'Events',
+    resources: 'Resources',
+};
+export async function applyOperations(ops, deps) {
+    const now = () => (deps.now ?? (() => new Date()))().toISOString();
+    const res = { added: [], updated: [], appended: [], archived: [], skipped: [] };
+    for (const op of ops) {
+        if (op.op === 'add') {
+            await deps.storage.write(op.path, renderFile(op.type, op.title, op.content, { createdAt: now(), updatedAt: now() }, deps.source));
+            res.added.push(op.path);
+            if (op.supersedePath && (await archiveFile(op.supersedePath, op.path, deps.storage))) {
+                res.archived.push(op.supersedePath);
+            }
+        }
+        else if (op.op === 'patch') {
+            const existing = await deps.storage.read(op.path);
+            const createdAt = existing ? (extractField(existing, 'created_at') ?? now()) : now();
+            await deps.storage.write(op.path, renderFile(op.type, op.title, op.content, { createdAt, updatedAt: now() }, deps.source));
+            res.updated.push(op.path);
+        }
+        else if (op.op === 'append') {
+            const existing = (await deps.storage.read(op.path)) ?? '';
+            const sep = existing && !existing.endsWith('\n') ? '\n' : '';
+            await deps.storage.write(op.path, existing + sep + op.content + '\n');
+            res.appended.push(op.path);
+        }
+        else {
+            res.skipped.push(op.title);
+        }
+    }
+    await updateIndex(ops, deps.storage);
+    await touchSidecars(deps.storage, affectedDirs(ops), { trigger: 'memory_write', now: deps.now });
+    return res;
+}
+function renderFile(type, title, content, o, source) {
+    return renderFrontmatter({ type, title, tags: deriveTags(type), createdAt: o.createdAt, updatedAt: o.updatedAt, source }) + '\n' + content + '\n';
+}
+function deriveTags(type) {
+    return type.split('/');
+}
+function deriveSummary(content) {
+    const first = content.split('\n').find((l) => l.trim())?.trim() ?? '';
+    return first.length > 80 ? `${first.slice(0, 80)}…` : first;
+}
+async function archiveFile(oldPath, newPath, storage) {
+    const oldText = await storage.read(oldPath);
+    if (oldText === null)
+        return false;
+    await storage.write(`archive/${oldPath}`, withSupersededBy(oldText, newPath));
+    await storage.delete(oldPath);
+    return true;
+}
+function withSupersededBy(text, newPath) {
+    const closing = text.indexOf('\n---');
+    if (closing === -1)
+        return text;
+    const line = `\nsuperseded_by: ${JSON.stringify(newPath)}`;
+    return text.slice(0, closing) + line + text.slice(closing);
+}
+function extractField(text, key) {
+    const m = text.match(new RegExp(`^${key}: (.+)$`, 'm'));
+    if (!m)
+        return undefined;
+    const raw = m[1].trim();
+    try {
+        return JSON.parse(raw);
+    }
+    catch {
+        return raw;
+    }
+}
+async function updateIndex(ops, storage) {
+    let text = (await storage.read('INDEX.md')) ?? INDEX_TEMPLATE;
+    for (const op of ops) {
+        if (op.op === 'add') {
+            if (op.supersedePath)
+                text = removeIndexRow(text, op.supersedePath);
+            text = addIndexRow(text, op);
+        }
+        else if (op.op === 'patch') {
+            text = patchIndexRow(text, op);
+        }
+        // append / skip 不进 INDEX
+    }
+    await storage.write('INDEX.md', text);
+}
+function indexRow(o) {
+    return `- ${o.title} — ${deriveSummary(o.content)} (${o.path}) · tags: ${deriveTags(o.type).join(', ')}`;
+}
+function addIndexRow(text, o) {
+    const section = SECTION[o.type.split('/')[0]];
+    if (!section)
+        return text;
+    const lines = text.split('\n');
+    const idx = lines.findIndex((l) => l === `## ${section}`);
+    if (idx === -1)
+        return text;
+    lines.splice(idx + 1, 0, indexRow(o));
+    return lines.join('\n');
+}
+function patchIndexRow(text, o) {
+    const lines = text.split('\n');
+    const i = lines.findIndex((l) => l.includes(`(${o.path})`));
+    if (i === -1)
+        return addIndexRow(text, o);
+    lines[i] = indexRow(o);
+    return lines.join('\n');
+}
+function removeIndexRow(text, path) {
+    return text.split('\n').filter((l) => !l.includes(`(${path})`)).join('\n');
+}
+/** 本次写入涉及的顶层目录(根 + 各类目),用于触发对应 sidecar 的脏标记与刷新。 */
+function affectedDirs(ops) {
+    const dirs = new Set(['']);
+    for (const op of ops) {
+        if (op.op === 'add' || op.op === 'patch' || op.op === 'append') {
+            const top = op.type.split('/')[0];
+            if (top)
+                dirs.add(top);
+        }
+    }
+    return [...dirs];
+}
+//# sourceMappingURL=write.js.map

package/dist/core/lessons/write.js.map

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

package/dist/core/library/build.d.ts

@@ -0,0 +1,22 @@
+import type { State } from '../state.js';
+export declare const MAPPER_VERSION = "events@4";
+export interface BuildOptions {
+    vaultRoot: string;
+    deviceId: string;
+    state: State;
+    now?: () => number;
+}
+export interface BuildResult {
+    sessions: number;
+    events: number;
+    skills: number;
+    written: number;
+}
+export declare function shardRelPath(deviceId: string): string;
+/**
+ * 把本设备 raw 归档构建成 library:
+ *   library/sessions/<harness>/<session>/<device>.jsonl  (每设备一份)
+ *   library/index/<device>.json                          (本设备索引分片)
+ * 然后重建统一索引。
+ */
+export declare function buildLibrary(opts: BuildOptions): Promise<BuildResult>;