@coralai/sps-plugin-api 0.10.0 → 0.12.0

package/dist/index.d.ts

@@ -242,13 +242,143 @@ export interface SpsRegistryByFactory<T = unknown> {
     register(factory: T): () => void;
     list(): string[];
 }
+/** 作用域:global 跨项目 / project 单项目 / agent(harness 会话)。 */
+export type MemoryScope = 'global' | 'project' | 'agent';
+export type MemoryCategory = 'convention' | 'decision' | 'gotcha' | 'pattern' | 'reference' | 'note';
+/** 出处:agent 主动写 / capture 自动捕获 / human 人(CLI/Console)。 */
+export type MemorySource = 'agent' | 'capture' | 'human';
+/** 定位一个作用域。`project` scope 必带 project;`agent` scope 必带 agentId。 */
+export interface MemoryScopeRef {
+    scope: MemoryScope;
+    project?: string;
+    agentId?: string;
+}
+export interface MemoryEntry {
+    /** 后端内部的裸 id(不带 `<backend>:` 前缀)。 */
+    id: string;
+    title: string;
+    scope: MemoryScope;
+    category: MemoryCategory;
+    tags: string[];
+    /** 显著度 1..5。 */
+    salience: number;
+    /** 被读回全文的次数 —— "真被用到"的硬信号。后端不支持时恒 0 即可。 */
+    uses: number;
+    source: MemorySource;
+    project?: string;
+    created: string;
+    updated: string;
+    body: string;
+}
+/** 不带 id = 新建;带 id = 更新。 */
+export interface MemorySaveInput {
+    id?: string;
+    title: string;
+    body: string;
+    category?: MemoryCategory;
+    tags?: string[];
+    salience?: number;
+    source?: MemorySource;
+    project?: string;
+}
+export interface MemoryRecallHit {
+    /** **必须带 `<backend>:` 前缀** —— 调用方据此知道回哪个后端读全文。 */
+    id: string;
+    /** 产出这条结果的后端 id。 */
+    source: string;
+    title: string;
+    snippet: string;
+    score: number;
+    scope?: string;
+    project?: string;
+    category?: string;
+    tags?: string[];
+}
+export interface MemoryRecallOpts {
+    tags?: string[];
+    limit?: number;
+}
 /**
- * ⚠️ 同上:这两个是**甲·工厂型**(换实现,不是收一组),
- *    今天没有第三方在换它们。声明方法名,形状留 `unknown`。
+ * 记忆后端。**必须实现 6 个,可选 4 个**。
+ *
+ * ⚠️ 可选的四个宿主都有默认实现 —— 不实现不是缺陷:
+ *    没有排序反馈机制的后端不该被迫写 `bumpUses`,没有派生产物的不该写 `reindex`。
+ *
+ * 🔴 读与写**必须一起实现**。只做一半的症状是"存进去的和读出来的不是一回事",
+ *    比彻底不工作难查得多。
  */
 export interface SpsMemory {
-    buildInjection(refs: unknown[]): string;
-}
+    recall(refs: MemoryScopeRef[], query: string, opts?: MemoryRecallOpts): Promise<MemoryRecallHit[]>;
+    listEntries(ref: MemoryScopeRef): MemoryEntry[];
+    readEntry(ref: MemoryScopeRef, id: string): MemoryEntry | null;
+    listAllScopes(): MemoryScopeRef[];
+    saveEntry(ref: MemoryScopeRef, input: MemorySaveInput): MemoryEntry;
+    deleteEntry(ref: MemoryScopeRef, id: string): boolean;
+    /** 后端当前是否可用。返回 false **不是错误** —— 调用方据此静默跳过。 */
+    enabled(): boolean;
+    bumpUses(ref: MemoryScopeRef, id: string): void;
+    /** 重建该作用域的派生产物。批量写入后调一次,不是每条都调。 */
+    reindex(ref: MemoryScopeRef): void;
+    promoteEntry(from: MemoryScopeRef, id: string, to: MemoryScopeRef, opts: {
+        move?: boolean;
+    }): MemoryEntry | null;
+    /**
+     * 宿主写完记忆配置后调一次,让长命进程无需重启即读到新值。
+     * 后端不缓存配置 ⇒ 空实现即可。
+     */
+    reloadConfig(): void;
+    /** 后端支持哪些维护操作。默认两个都不支持。 */
+    readonly supports: {
+        gc?: boolean;
+        migrate?: boolean;
+    };
+    /** 回收一个作用域(硬删 tombstone、去重)。`supports.gc` 为假时不会被调用。 */
+    gc(ref: MemoryScopeRef): Promise<MemoryGcStats>;
+    /**
+     * 迁移该后端自己的历史数据结构。`supports.migrate` 为假时不会被调用。
+     *
+     * ⚠️ 这是**后端的历史包袱**,不是通用能力 —— 一个新后端不该有可迁的旧结构。
+     */
+    migrate(target: {
+        project?: string;
+        all?: boolean;
+    }): MemoryMigrateStats;
+    /**
+     * 要注入 worker 的 Claude Code 插件目录(**绝对路径**)。没有就返回 `[]`。
+     *
+     * 用于把"自动召回"做进会话:hooks 在 worker 的 claude 进程里跑,
+     * 不依赖 agent 主动调工具。
+     *
+     * ⚠️ 只有 claude 后端会用到 —— 别的 agent(openai/codex)没有对应概念,
+     *    它们要等价能力时各自在自己的适配器里解决。
+     */
+    workerPlugins(): string[];
+}
+export interface MemoryGcStats {
+    /** 硬删的 tombstone 数。 */
+    purged: number;
+    /** 去重软删的重复条数。 */
+    deduped: number;
+    /** 收敛后剩余条数。 */
+    kept: number;
+}
+/** 迁移了多少条 —— 键由后端自定(本地实现给 global/agents/projects)。 */
+export type MemoryMigrateStats = Record<string, number>;
+/** 写入被脱敏规则丢弃时,后端抛出的错误应带这个 code。宿主据此与真错误区分。 */
+export declare const MEMORY_REDACTED_CODE = "memory-redacted";
+/** 去重归一化:小写、去 markdown 标点、压空白。**这是"什么算重复"的唯一判据**。 */
+export declare function normalizeMemoryBody(s: string): string;
+export interface MemoryDigestOpts {
+    /** 标题清单最多列几条(默认 60)。 */
+    maxTitles?: number;
+    /** 内联几条高 salience 正文(默认 6)。 */
+    maxBodies?: number;
+    /** 每条正文最多字符(默认 500)。 */
+    bodyChars?: number;
+}
+/** entries → 摘要 markdown(标题清单 + top 高 salience 正文)。空集合返回空串。 */
+export declare function buildMemoryDigest(entries: MemoryEntry[], opts?: MemoryDigestOpts): string;
+/** ⚠️ 甲·工厂型(换实现,不是收一组);今天没有第三方在换它。 */
 export interface SpsNotifier {
     open(config: unknown): {
         send(message: string, level?: 'info' | 'success' | 'warning' | 'error'): Promise<void>;

package/dist/index.js

@@ -11,6 +11,61 @@
  * ⚠️ 这里只声明**插件会调的那一面**。服务内部还有别的方法(比如注册表的
  *    `list()`),不写进来 —— 写进来就等于承诺它们不变,而那不是我们打算承诺的。
  */
+// ── 后端可以往 worker 注入一个 Claude Code 插件 ─────────────────────────────
+//
+// 记忆的读路有两半:**pull**(agent 自己调 `memory_recall`)与 **push**(会话自动召回)。
+// 只有 pull 时,工具挂着而 agent 不调 = 等于没记忆 —— 这是实测过的失效模式。
+// push 那一半靠 Claude Code 的 hooks,而 hooks 装在一个 claude 插件目录里。
+//
+// 🔴 宿主**只要一个目录路径**,不解析里面的 hooks.json / .mcp.json ——
+//    那是运行时 substrate 的格式,和"sps 不解析 claude 的 transcript"同源。
+// ⚠️ 目录由 SDK 的 `plugins: [{type:'local', path}]` 加载,**不需要装进
+//    `~/.claude/plugins`**(2026-08-27 实测:任意路径可加载,MCP server 正常注册)。
+//    这也意味着关掉 = 不传参数,零残留。
+// ── 跨后端必须一致的算法 ──────────────────────────────────────────────────
+//
+// 🔴 放这里的判据只有一条:**两个后端对它给出不同答案会出错**。
+//    "什么算重复"若两个后端不一致,同一条记忆在不同后端行为不同;
+//    摘要格式不一致,人看到的 MEMORY.md 会跟着换后端变形。
+//    ⚠️ 别把"本地实现顺手用得上的工具"塞进来 —— 那属于后端自己。
+/** 写入被脱敏规则丢弃时,后端抛出的错误应带这个 code。宿主据此与真错误区分。 */
+export const MEMORY_REDACTED_CODE = 'memory-redacted';
+/** 去重归一化:小写、去 markdown 标点、压空白。**这是"什么算重复"的唯一判据**。 */
+export function normalizeMemoryBody(s) {
+    return s
+        .toLowerCase()
+        .replace(/[#*`_>\-\s]+/g, ' ')
+        .replace(/[^\p{L}\p{N} ]+/gu, '')
+        .trim();
+}
+/** entries → 摘要 markdown(标题清单 + top 高 salience 正文)。空集合返回空串。 */
+export function buildMemoryDigest(entries, opts = {}) {
+    const maxTitles = opts.maxTitles ?? 60;
+    const maxBodies = opts.maxBodies ?? 6;
+    const bodyChars = opts.bodyChars ?? 500;
+    if (entries.length === 0)
+        return '';
+    const ranked = entries
+        .slice()
+        .sort((a, b) => b.salience - a.salience || b.updated.localeCompare(a.updated));
+    const lines = ['# 记忆摘要', '', '## 索引'];
+    for (const e of ranked.slice(0, maxTitles)) {
+        const tags = e.tags.length ? ` #${e.tags.join(' #')}` : '';
+        lines.push(`- [${e.id}] (${e.category}, s${e.salience}) ${e.title}${tags}`);
+    }
+    if (ranked.length > maxTitles) {
+        lines.push(`- …还有 ${ranked.length - maxTitles} 条(用 memory_recall 检索)`);
+    }
+    const bodies = ranked.slice(0, maxBodies);
+    if (bodies.length) {
+        lines.push('', '## 高显著度');
+        for (const e of bodies) {
+            const body = e.body.length > bodyChars ? `${e.body.slice(0, bodyChars)}…` : e.body;
+            lines.push('', `### ${e.title}`, body);
+        }
+    }
+    return lines.join('\n').trim();
+}
 // ── 服务名 ───────────────────────────────────────────────────────────────
 /** 插件 `inject` 里写的名字。 */
 export const SPS_SERVICES = {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@coralai/sps-plugin-api",
-  "version": "0.10.0",
+  "version": "0.12.0",
   "description": "sps 宿主半区的插件契约:ctx 上那些服务的方法签名。插件装它拿类型。",
   "type": "module",
   "main": "./dist/index.js",