dsh-thesis 1.0.0

package/lib/memory/register.d.ts

@@ -0,0 +1,37 @@
+/**
+ * 跨会话事实的装配层：把 SQLite 事实库挂到 `ctx.memory`
+ * 并注册三个模型工具（`fact_search` / `fact_remember` / `fact_context`）。
+ *
+ * 落点：`$DSH_HOME/dsh-thesis-memory.db`（可用 `memoryPath` 覆盖）。**刻意用一个
+ * 全局库**而不是每篇论文一个库：装配发生在进程启动时、拿不到会话 cwd；而事实
+ * 里跨课题复用的内容（写作风格偏好、导师沟通习惯、学校通用规范）本来就应该
+ * 跨项目活着。课题专属内容用 key 前缀隔离：
+ * `thesis.<课题 slug>.<实体>.<属性>`。
+ *
+ * **面向学生的说法**：这是「记住你的学校和导师要求，换个会话不用重讲」的能力，
+ * 不是「记忆系统」。学生不需要知道它叫 memory。
+ *
+ * @module dsh-thesis/memory
+ */
+import type { Context } from '@deepseek-ai/cordis';
+import type { RecallOptions } from './recall.ts';
+import { type MemoryService } from './service.ts';
+/**
+ * 默认库位置：`$DSH_HOME/dsh-thesis-memory.db`，否则 `~/.dsh-thesis-memory.db`。
+ *
+ * 只有一个位置，没有回退：本插件的包名从未以其它名字发布过，因此不存在
+ * 「数据躺在旧文件里、新文件是空的」这种需要兼容的历史包袱。
+ * 建这种回退只会留下一条永远不成立的分支。
+ */
+export declare function defaultMemoryPath(): string;
+export interface FactRegistration {
+    readonly service: MemoryService;
+    readonly path: string;
+}
+/**
+ * 装配跨会话事实：provider + 三个模型工具，注册为 `ctx.memory`。
+ * Disposal 关闭数据库。
+ */
+export declare function registerFacts(ctx: Context, configured?: string): FactRegistration;
+/** 装配「相关时把已确认事实放回上下文」。 */
+export declare function installFactRecall(ctx: Context, options: RecallOptions): void;

package/lib/memory/register.js

@@ -0,0 +1,52 @@
+/**
+ * 跨会话事实的装配层：把 SQLite 事实库挂到 `ctx.memory`
+ * 并注册三个模型工具（`fact_search` / `fact_remember` / `fact_context`）。
+ *
+ * 落点：`$DSH_HOME/dsh-thesis-memory.db`（可用 `memoryPath` 覆盖）。**刻意用一个
+ * 全局库**而不是每篇论文一个库：装配发生在进程启动时、拿不到会话 cwd；而事实
+ * 里跨课题复用的内容（写作风格偏好、导师沟通习惯、学校通用规范）本来就应该
+ * 跨项目活着。课题专属内容用 key 前缀隔离：
+ * `thesis.<课题 slug>.<实体>.<属性>`。
+ *
+ * **面向学生的说法**：这是「记住你的学校和导师要求，换个会话不用重讲」的能力，
+ * 不是「记忆系统」。学生不需要知道它叫 memory。
+ *
+ * @module dsh-thesis/memory
+ */
+import { homedir } from 'node:os';
+import { join, resolve } from 'node:path';
+import { installFactRecall as installRecall } from "./recall.js";
+import { SqliteMemoryService } from "./service.js";
+import { memoryTools } from "./tools.js";
+/**
+ * 默认库位置：`$DSH_HOME/dsh-thesis-memory.db`，否则 `~/.dsh-thesis-memory.db`。
+ *
+ * 只有一个位置，没有回退：本插件的包名从未以其它名字发布过，因此不存在
+ * 「数据躺在旧文件里、新文件是空的」这种需要兼容的历史包袱。
+ * 建这种回退只会留下一条永远不成立的分支。
+ */
+export function defaultMemoryPath() {
+    const home = process.env.DSH_HOME?.trim();
+    const dir = home !== undefined && home !== '' ? home : homedir();
+    return join(dir, 'dsh-thesis-memory.db');
+}
+/**
+ * 装配跨会话事实：provider + 三个模型工具，注册为 `ctx.memory`。
+ * Disposal 关闭数据库。
+ */
+export function registerFacts(ctx, configured) {
+    const path = configured === ':memory:' || configured === undefined || configured.trim() === ''
+        ? (configured ?? defaultMemoryPath())
+        : resolve(configured);
+    const service = new SqliteMemoryService(path);
+    ctx.provide('memory', service);
+    ctx.effect(() => () => service.close(), 'dsh-thesis.memory.closeDatabase');
+    for (const tool of memoryTools(service)) {
+        ctx.tools.register(tool);
+    }
+    return { service, path };
+}
+/** 装配「相关时把已确认事实放回上下文」。 */
+export function installFactRecall(ctx, options) {
+    installRecall(ctx, options);
+}

package/lib/memory/service.d.ts

@@ -0,0 +1,39 @@
+/**
+ * 跨会话事实：SQLite provider 与它的类型契约。
+ *
+ * **刻意不继承 cordis 的 `Service` 基类**：provider 是个普通类，由
+ * `registerFacts` 通过 `ctx.provide('memory', service)` 注册。这样做的收益：
+ * 整个事实库可以在**没有宿主运行时**的环境里被构造与验证——装配测试
+ * 用一个假的 ctx 就能跑通 `apply()`，而不必把 cordis 拖进测试依赖。
+ *
+ * 面向学生的说法是「记住你的学校和导师要求，换个会话不用重讲」；
+ * `memory` 只是它在宿主里的服务名，不是学生要调用的工具。
+ *
+ * 业务语义在 {@link MemoryStore}（纯 SQLite）；本文件只做参数校验边界。
+ *
+ * @module dsh-thesis/memory/service
+ */
+import type { MemoryContextOptions, MemoryEntry, MemoryInput, MemorySearchOptions, RememberResult } from './types.ts';
+export type { MemoryContextOptions, MemoryEntry, MemoryInput, MemorySearchOptions, MemoryType, RememberResult, } from './types.ts';
+/** 记忆能力的对外契约（`ctx.get('memory')` 拿到的就是这个形状）。 */
+export interface MemoryService {
+    /** 创建或原地更新一条记忆。 */
+    remember(entry: MemoryInput): RememberResult;
+    /** 对 key 与 value 做大小写不敏感子串检索。 */
+    search(query: string, options?: MemorySearchOptions): MemoryEntry[];
+    /** 列出某个命名空间/前缀下的全部条目。 */
+    context(topic: string, options?: MemoryContextOptions): MemoryEntry[];
+}
+/** 唯一的 provider：一个 SQLite 文件（或 `:memory:`）。 */
+export declare class SqliteMemoryService implements MemoryService {
+    private readonly store;
+    /**
+     * @param dbPath - SQLite 文件路径或 `:memory:`；父目录缺失时自动创建。
+     */
+    constructor(dbPath: string);
+    /** 关闭数据库（插件卸载时由 `ctx.effect` 调用）。 */
+    close(): void;
+    remember(entry: MemoryInput): RememberResult;
+    search(query: string, options?: MemorySearchOptions): MemoryEntry[];
+    context(topic: string, options?: MemoryContextOptions): MemoryEntry[];
+}

package/lib/memory/service.js

@@ -0,0 +1,39 @@
+/**
+ * 跨会话事实：SQLite provider 与它的类型契约。
+ *
+ * **刻意不继承 cordis 的 `Service` 基类**：provider 是个普通类，由
+ * `registerFacts` 通过 `ctx.provide('memory', service)` 注册。这样做的收益：
+ * 整个事实库可以在**没有宿主运行时**的环境里被构造与验证——装配测试
+ * 用一个假的 ctx 就能跑通 `apply()`，而不必把 cordis 拖进测试依赖。
+ *
+ * 面向学生的说法是「记住你的学校和导师要求，换个会话不用重讲」；
+ * `memory` 只是它在宿主里的服务名，不是学生要调用的工具。
+ *
+ * 业务语义在 {@link MemoryStore}（纯 SQLite）；本文件只做参数校验边界。
+ *
+ * @module dsh-thesis/memory/service
+ */
+import { MemoryStore } from "./store.js";
+/** 唯一的 provider：一个 SQLite 文件（或 `:memory:`）。 */
+export class SqliteMemoryService {
+    store;
+    /**
+     * @param dbPath - SQLite 文件路径或 `:memory:`；父目录缺失时自动创建。
+     */
+    constructor(dbPath) {
+        this.store = new MemoryStore(dbPath);
+    }
+    /** 关闭数据库（插件卸载时由 `ctx.effect` 调用）。 */
+    close() {
+        this.store.close();
+    }
+    remember(entry) {
+        return this.store.remember(entry);
+    }
+    search(query, options = {}) {
+        return this.store.search(query, options);
+    }
+    context(topic, options = {}) {
+        return this.store.context(topic, options);
+    }
+}

package/lib/memory/store.d.ts

@@ -0,0 +1,45 @@
+/**
+ * 记忆存储：纯 SQLite 实现，**零 cordis 依赖**（可独立单测）。
+ *
+ * 与 `service.ts` 的分工遵循本仓库的通用约定：业务逻辑在 store 里，
+ * 宿主服务外壳（`ctx.memory`）只是它的适配器。这样记忆的语义
+ * （原地更新保留 createdAt、子串检索、前缀上下文）能在没有宿主
+ * 运行时的环境里被直接验证。
+ *
+ * @module dsh-thesis/memory/store
+ */
+import type { MemoryContextOptions, MemoryEntry, MemoryInput, MemorySearchOptions, RememberResult } from './types.ts';
+/** 记忆 key 规范化：去空白后不得为空。 */
+export declare function normalizeKey(key: string): string;
+/** 单次查询返回条数的上限：防止一次把整张表倒进上下文。 */
+export declare const MAX_LIMIT = 500;
+/** 把调用方给的 limit 夹到 `[1, MAX_LIMIT]`；缺省 50（而不是"不限制"）。 */
+export declare function clampLimit(limit: number | undefined): number;
+/**
+ * SQLite 记忆存储。`:memory:` 打开进程内临时库（测试用）。
+ *
+ * 语义约定（与 `MemoryService` 的抽象契约一致）：
+ * - `remember`：新 key 插入，已有 key 原地更新且保留 `createdAt`；
+ * - `search`：对 key 与 value 做大小写不敏感子串匹配，按 key 排序；
+ * - `context`：返回 key 等于 topic 或以 `topic.` 开头的全部条目。
+ */
+export declare class MemoryStore {
+    private readonly db;
+    constructor(dbPath: string);
+    /** 关闭数据库。幂等（插件卸载与测试清理都会调用）。 */
+    close(): void;
+    remember(entry: MemoryInput): RememberResult;
+    /**
+     * 检索事实。
+     *
+     * `query` 为空串时**不当作"匹配一切"**：必须同时给出 `namespace`，否则抛错——
+     * 否则 `search('')` 会静默返回整张表的前 N 条，调用方以为自己在做检索。
+     * 回灌路径要全量取用时请显式给 `namespace`（它内部按命名空间取）。
+     *
+     * `limit` 一律夹到 `[1, 500]`：负数或 0 以前会**完全绕开 SQL 的 LIMIT**，返回整张表。
+     */
+    search(query: string, options?: MemorySearchOptions): MemoryEntry[];
+    context(topic: string, options?: MemoryContextOptions): MemoryEntry[];
+    private getRow;
+    private rows;
+}

package/lib/memory/store.js

@@ -0,0 +1,123 @@
+/**
+ * 记忆存储：纯 SQLite 实现，**零 cordis 依赖**（可独立单测）。
+ *
+ * 与 `service.ts` 的分工遵循本仓库的通用约定：业务逻辑在 store 里，
+ * 宿主服务外壳（`ctx.memory`）只是它的适配器。这样记忆的语义
+ * （原地更新保留 createdAt、子串检索、前缀上下文）能在没有宿主
+ * 运行时的环境里被直接验证。
+ *
+ * @module dsh-thesis/memory/store
+ */
+import { DatabaseSync } from 'node:sqlite';
+import { mkdirSync } from 'node:fs';
+import { dirname, resolve } from 'node:path';
+/** 记忆 key 规范化：去空白后不得为空。 */
+export function normalizeKey(key) {
+    const trimmed = key.trim();
+    if (trimmed.length === 0) {
+        throw new Error('memory: key must be a non-empty string');
+    }
+    return trimmed;
+}
+/** 单次查询返回条数的上限：防止一次把整张表倒进上下文。 */
+export const MAX_LIMIT = 500;
+/** 把调用方给的 limit 夹到 `[1, MAX_LIMIT]`；缺省 50（而不是"不限制"）。 */
+export function clampLimit(limit) {
+    if (limit === undefined || !Number.isFinite(limit))
+        return 50;
+    return Math.min(MAX_LIMIT, Math.max(1, Math.floor(limit)));
+}
+/**
+ * SQLite 记忆存储。`:memory:` 打开进程内临时库（测试用）。
+ *
+ * 语义约定（与 `MemoryService` 的抽象契约一致）：
+ * - `remember`：新 key 插入，已有 key 原地更新且保留 `createdAt`；
+ * - `search`：对 key 与 value 做大小写不敏感子串匹配，按 key 排序；
+ * - `context`：返回 key 等于 topic 或以 `topic.` 开头的全部条目。
+ */
+export class MemoryStore {
+    db;
+    constructor(dbPath) {
+        if (dbPath !== ':memory:') {
+            const target = resolve(dbPath);
+            mkdirSync(dirname(target), { recursive: true });
+            dbPath = target;
+        }
+        this.db = new DatabaseSync(dbPath);
+        this.db.exec('PRAGMA journal_mode = WAL');
+        this.db.exec(`
+      CREATE TABLE IF NOT EXISTS memories (
+        key        TEXT PRIMARY KEY,
+        value      TEXT NOT NULL,
+        type       TEXT NOT NULL,
+        source     TEXT NOT NULL,
+        confidence REAL NOT NULL,
+        created_at INTEGER NOT NULL,
+        updated_at INTEGER NOT NULL
+      ) STRICT
+    `);
+    }
+    /** 关闭数据库。幂等（插件卸载与测试清理都会调用）。 */
+    close() {
+        this.db.close();
+    }
+    remember(entry) {
+        const key = normalizeKey(entry.key);
+        const now = Date.now();
+        const existing = this.getRow(key);
+        if (existing === undefined) {
+            this.db.prepare('INSERT INTO memories (key, value, type, source, confidence, created_at, updated_at) VALUES (?, ?, ?, ?, ?, ?, ?)').run(key, entry.value, entry.type, entry.source, entry.confidence, now, now);
+            return { action: 'created', key, value: entry.value };
+        }
+        this.db.prepare('UPDATE memories SET value = ?, type = ?, source = ?, confidence = ?, updated_at = ? WHERE key = ?').run(entry.value, entry.type, entry.source, entry.confidence, now, key);
+        return { action: 'updated', key, value: entry.value };
+    }
+    /**
+     * 检索事实。
+     *
+     * `query` 为空串时**不当作"匹配一切"**：必须同时给出 `namespace`，否则抛错——
+     * 否则 `search('')` 会静默返回整张表的前 N 条，调用方以为自己在做检索。
+     * 回灌路径要全量取用时请显式给 `namespace`（它内部按命名空间取）。
+     *
+     * `limit` 一律夹到 `[1, 500]`：负数或 0 以前会**完全绕开 SQL 的 LIMIT**，返回整张表。
+     */
+    search(query, options = {}) {
+        if (query === '' && options.namespace === undefined) {
+            throw new Error('fact_search 需要一个非空 query，或一个 namespace（只给 namespace 表示「列出该命名空间下的全部事实」）。');
+        }
+        const clauses = [];
+        const args = [];
+        if (options.namespace !== undefined) {
+            clauses.push('key LIKE ?');
+            args.push(options.namespace + '.%');
+        }
+        if (query !== '') {
+            clauses.push('(key LIKE ? OR value LIKE ?)');
+            const pattern = `%${query}%`;
+            args.push(pattern, pattern);
+        }
+        const where = clauses.length > 0 ? ` WHERE ${clauses.join(' AND ')}` : '';
+        args.push(clampLimit(options.limit));
+        return this.rows(`SELECT key, value, type, source, confidence, created_at, updated_at FROM memories${where} ORDER BY key LIMIT ?`, args);
+    }
+    context(topic, options = {}) {
+        const args = [topic, topic + '.%', clampLimit(options.limit)];
+        return this.rows('SELECT key, value, type, source, confidence, created_at, updated_at FROM memories'
+            + ' WHERE key = ? OR key LIKE ? ORDER BY key LIMIT ?', args);
+    }
+    getRow(key) {
+        return this.db.prepare('SELECT key, value, type, source, confidence, created_at, updated_at FROM memories WHERE key = ?').get(key);
+    }
+    rows(sql, args) {
+        const rows = this.db.prepare(sql).all(...args);
+        return rows.map(row => ({
+            key: row.key,
+            value: row.value,
+            type: row.type,
+            source: row.source,
+            confidence: row.confidence,
+            createdAt: row.created_at,
+            updatedAt: row.updated_at,
+        }));
+    }
+}

package/lib/memory/tools.d.ts

@@ -0,0 +1,19 @@
+/**
+ * 面向模型的跨会话事实工具定义：`fact_search` / `fact_remember` / `fact_context`，
+ * 三个工具共用同一个 {@link MemoryService}。
+ *
+ * 命名空间 `fact_*` 的含义：**跨会话仍然成立的稳定事实**——学校规范、导师要求、
+ * 你的写作偏好。它与 `thesis_*`（操作论文工作区里的东西）并列。
+ * 进度、临时任务、一次性的实验数字不属于这里（它们在进度台账与实验记录里）。
+ *
+ * @module dsh-thesis/memory/tools
+ */
+import type { MemoryService } from './service.ts';
+/**
+ * 三个面向模型的跨会话事实工具。
+ *
+ * 命名空间 `fact_*` 的含义：**跨会话仍然成立的稳定事实**——学校规范、导师要求、
+ * 你的写作偏好。它与 `thesis_*`（操作论文工作区里的东西）是并列的两类。
+ * 进度、临时任务、一次性的实验数字不属于这里（它们在进度台账与实验记录里）。
+ */
+export declare function memoryTools(service: MemoryService): unknown[];

package/lib/memory/tools.js

@@ -0,0 +1,195 @@
+/**
+ * 面向模型的跨会话事实工具定义：`fact_search` / `fact_remember` / `fact_context`，
+ * 三个工具共用同一个 {@link MemoryService}。
+ *
+ * 命名空间 `fact_*` 的含义：**跨会话仍然成立的稳定事实**——学校规范、导师要求、
+ * 你的写作偏好。它与 `thesis_*`（操作论文工作区里的东西）并列。
+ * 进度、临时任务、一次性的实验数字不属于这里（它们在进度台账与实验记录里）。
+ *
+ * @module dsh-thesis/memory/tools
+ */
+import { definePaperTool } from "../shared/index.js";
+const MEMORY_TYPES = ['fact', 'preference', 'entity', 'relation'];
+/** Resolve model-omitted fields into a complete write request. */
+function resolveRememberInput(raw) {
+    const key = raw.key.trim();
+    if (key.length === 0) {
+        throw new Error('fact_remember: `key` must be a non-empty string');
+    }
+    if (raw.value.trim().length === 0) {
+        throw new Error('fact_remember: `value` must be a non-empty string');
+    }
+    const type = (raw.type ?? 'fact');
+    const confidence = raw.confidence ?? 1;
+    if (!Number.isFinite(confidence) || confidence < 0 || confidence > 1) {
+        throw new Error(`fact_remember: confidence must be in 0..1, got ${JSON.stringify(confidence)}`);
+    }
+    return {
+        key,
+        value: raw.value,
+        type,
+        source: raw.source?.trim() || 'manual',
+        confidence,
+    };
+}
+function renderSearchResults(results) {
+    if (results.length === 0)
+        return '没有找到相关记忆。';
+    return results.map(row => `${row.key} = ${row.value}`).join('\n');
+}
+/** Build the inline natural-language projection of a context listing. */
+function renderContext(facts) {
+    if (facts.length === 0)
+        return '这个主题下还没有记忆。';
+    const byNamespace = new Map();
+    for (const fact of facts) {
+        const dot = fact.key.indexOf('.');
+        const namespace = dot === -1 ? fact.key : fact.key.slice(0, dot);
+        const rest = dot === -1 ? fact.key : fact.key.slice(dot + 1);
+        const rows = byNamespace.get(namespace) ?? [];
+        rows.push(`${rest}=${fact.value}`);
+        byNamespace.set(namespace, rows);
+    }
+    let out = '';
+    for (const [namespace, rows] of byNamespace) {
+        out += (out.length === 0 ? '' : '。') + `关于 ${namespace}: ${rows.join(', ')}`;
+    }
+    return `${out}。`;
+}
+/**
+ * 三个面向模型的跨会话事实工具。
+ *
+ * 命名空间 `fact_*` 的含义：**跨会话仍然成立的稳定事实**——学校规范、导师要求、
+ * 你的写作偏好。它与 `thesis_*`（操作论文工作区里的东西）是并列的两类。
+ * 进度、临时任务、一次性的实验数字不属于这里（它们在进度台账与实验记录里）。
+ */
+export function memoryTools(service) {
+    return [
+        definePaperTool({
+            name: 'fact_search',
+            description: '在跨会话事实库里检索：对 key 与 value 做大小写不敏感的子串匹配（可选限定命名空间、限制条数）。'
+                + '用于确认「上次记下的学校规范/导师要求/写作偏好还在不在」，以及回答用户「我之前说过什么」。',
+            parameters: {
+                query: { type: 'string', required: true, description: '要匹配的子串（同时匹配 key 与 value）' },
+                namespace: { type: 'string', description: '可选命名空间；只考虑该前缀下的 key（如 thesis 或 thesis.face-attendance）' },
+                limit: { type: 'integer', description: '返回条数上限，默认 10' },
+            },
+            output: {
+                schema: {
+                    type: 'object',
+                    additionalProperties: false,
+                    properties: {
+                        results: {
+                            type: 'array',
+                            required: true,
+                            items: {
+                                type: 'object',
+                                additionalProperties: false,
+                                properties: {
+                                    key: { type: 'string', required: true },
+                                    value: { type: 'string', required: true },
+                                    source: { type: 'string', required: true },
+                                    confidence: { type: 'number', required: true },
+                                },
+                            },
+                        },
+                    },
+                },
+                render: (_args, value) => [{ type: 'text', text: renderSearchResults(value.results) }],
+            },
+            async execute(args) {
+                const entries = service.search(args.query, {
+                    ...args.namespace !== undefined ? { namespace: args.namespace } : {},
+                    limit: args.limit ?? 10,
+                });
+                return {
+                    results: entries.map(entry => ({
+                        key: entry.key,
+                        value: entry.value,
+                        source: entry.source,
+                        confidence: entry.confidence,
+                    })),
+                };
+            },
+        }),
+        definePaperTool({
+            name: 'fact_remember',
+            description: '写入或更新一条跨会话事实（key 已存在则原地更新，保留原始创建时间）。'
+                + '只记**跨会话仍然成立**的事实：用户偏好（user.*）、学校通用规范（school.*）、课题稳定事实（thesis.<课题>.*）。'
+                + '不要把进度、临时任务或一次性实验数字写进来——那些在进度台账与实验记录里。',
+            parameters: {
+                key: { type: 'string', required: true, description: '记忆 key，三段式 `namespace.entity.attribute`，如 school.dedup.system' },
+                value: { type: 'string', required: true, description: '要记住的值' },
+                type: {
+                    type: 'string',
+                    enum: [...MEMORY_TYPES],
+                    description: '分类：fact（事实）/ preference（偏好）/ entity（实体）/ relation（关系），默认 fact',
+                },
+                source: { type: 'string', description: '来源标注，默认 manual；如 intake（追问确认）、decision（决定日志）' },
+                confidence: { type: 'number', description: '置信度 0..1，默认 1' },
+            },
+            output: {
+                schema: {
+                    type: 'object',
+                    additionalProperties: false,
+                    properties: {
+                        action: { type: 'string', required: true, enum: ['created', 'updated'] },
+                        key: { type: 'string', required: true },
+                        value: { type: 'string', required: true },
+                    },
+                },
+                render: (_args, value) => [{
+                        type: 'text',
+                        text: `${value.action === 'created' ? '已写入' : '已更新'}记忆 ${value.key} = ${value.value}`,
+                    }],
+            },
+            async execute(args) {
+                const input = resolveRememberInput(args);
+                return service.remember(input);
+            },
+        }),
+        definePaperTool({
+            name: 'fact_context',
+            description: '取出某个命名空间/前缀下的全部事实作为上下文，同时给出自然语言投影与 key-value 列表。'
+                + '开新会话时用它把「这个课题/这所学校已知的稳定事实」一次性拉回来。',
+            parameters: {
+                topic: { type: 'string', required: true, description: '命名空间或 key 前缀，如 thesis.face-attendance' },
+                limit: { type: 'integer', description: '返回条数上限，默认不限' },
+            },
+            output: {
+                schema: {
+                    type: 'object',
+                    additionalProperties: false,
+                    properties: {
+                        context: { type: 'string', required: true },
+                        facts: {
+                            type: 'array',
+                            required: true,
+                            items: {
+                                type: 'object',
+                                additionalProperties: false,
+                                properties: {
+                                    key: { type: 'string', required: true },
+                                    value: { type: 'string', required: true },
+                                    confidence: { type: 'number', required: true },
+                                },
+                            },
+                        },
+                    },
+                },
+                render: (_args, value) => [{ type: 'text', text: value.context }],
+            },
+            async execute(args) {
+                const entries = service.context(args.topic, {
+                    ...args.limit !== undefined ? { limit: args.limit } : {},
+                });
+                const facts = entries.map(entry => ({
+                    key: entry.key,
+                    value: entry.value,
+                    confidence: entry.confidence,
+                }));
+                return { context: renderContext(facts), facts };
+            },
+        }),
+    ];
+}

package/lib/memory/types.d.ts

@@ -0,0 +1,55 @@
+/**
+ * 跨会话事实的纯类型：service 与面向模型的工具共用这套词汇。
+ *
+ * @module dsh-thesis/memory/types
+ */
+/** 分类一条事实：fact（事实）/ preference（偏好）/ entity（实体）/ relation（关系）。 */
+export type MemoryType = 'fact' | 'preference' | 'entity' | 'relation';
+/** 一次写入请求（交给 {@link MemoryService.remember}）。 */
+export interface MemoryInput {
+    /** 事实 key，约定三段式 `namespace.entity.attribute`。 */
+    key: string;
+    /** 要记住的值。 */
+    value: string;
+    /** 分类。 */
+    type: MemoryType;
+    /** 来源标注，如文件路径或 `manual`。 */
+    source: string;
+    /** 置信度，取值 `0..1`。 */
+    confidence: number;
+}
+/** 一条已存事实（读取时返回的形态）。 */
+export interface MemoryEntry {
+    key: string;
+    value: string;
+    type: MemoryType;
+    source: string;
+    confidence: number;
+    /** 首次写入的时间戳（epoch 毫秒）。 */
+    createdAt: number;
+    /** 最近一次写入的时间戳（epoch 毫秒）。 */
+    updatedAt: number;
+}
+/** 一次成功写入的结果。 */
+export interface RememberResult {
+    /** 新 key 为 `created`，已存在的 key 为 `updated`。 */
+    action: 'created' | 'updated';
+    key: string;
+    value: string;
+}
+/** {@link MemoryService.search} 的收窄选项。 */
+export interface MemorySearchOptions {
+    /** 只考虑以该命名空间前缀开头的 key（`namespace.`）。 */
+    namespace?: string;
+    /**
+     * 最多返回条数。**缺省 50，一律夹到 `[1, 500]`**：
+     * 传给 SQL 的 LIMIT 不能省（否则一次检索会把整张表倒进上下文），
+     * 负数或 0 也不再被解释为「不限制」。
+     */
+    limit?: number;
+}
+/** {@link MemoryService.context} 的收窄选项。 */
+export interface MemoryContextOptions {
+    /** 最多返回条数；与 `search` 同一套夹取规则。 */
+    limit?: number;
+}

package/lib/memory/types.js

@@ -0,0 +1,6 @@
+/**
+ * 跨会话事实的纯类型：service 与面向模型的工具共用这套词汇。
+ *
+ * @module dsh-thesis/memory/types
+ */
+export {};

package/lib/paper/commands.d.ts

@@ -0,0 +1,13 @@
+/**
+ * 斜杠命令：/thesis-status 与 /thesis-decide。
+ *
+ * 注：DSH 命令名只允许 [a-z][a-z0-9_-]*，因此使用 kebab-case
+ * （DESIGN.md 中的 /thesis:status 在此修正为 /thesis-status）。
+ * 其余命令（/thesis-lit、/thesis-check、/thesis-build）随 M2/M4 工具一并注册。
+ */
+import type { FileSystem } from '@deepseek-ai/dsh-fs';
+export declare function statusCommand(fs: FileSystem): unknown;
+export declare function decideCommand(fs: FileSystem): unknown;
+export declare function litCommand(fs: FileSystem): unknown;
+export declare function checkCommand(fs: FileSystem): unknown;
+export declare function buildCommand(fs: FileSystem): unknown;