@coralai/sps-plugin-api 0.9.0 → 0.11.0

package/dist/index.d.ts

@@ -242,18 +242,162 @@ 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;
+}
+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>;
     };
 }
+export interface SpsStorageObject {
+    key: string;
+    /** **内容判据**(单段上传时等于 md5)。不看时间。 */
+    etag: string;
+    size: number;
+}
+/**
+ * 对象存储(读 / 列 / 写)。桶是共享面 —— 多节点下 studio 和工作区不在同一台机器上。
+ *
+ * 🔴 **它只搬字节,不做账。** id / 索引 / 缩略图 / 分类 / 配额 / 计费都在平台侧。
+ *
+ * ⚠️ **权限按前缀分,而且很紧**(单写方规则)。
+ *    读不了的前缀会**抛**,不会回空 —— "库是空的"和"我没权限"混成一个,
+ *    人会去补素材而不是去补策略。
+ * ⚠️ 桶没配时三个方法都抛 ⇒ **先用 `configured()` 问一句**,别拿异常当分支。
+ */
+export interface SpsStorage {
+    configured(): boolean;
+    /** 不存在 ⇒ `null`;连不上/没权限 ⇒ **抛**。 */
+    get(key: string): Promise<Buffer | null>;
+    list(prefix: string): Promise<SpsStorageObject[]>;
+    /** ⚠️ `contentType` 自己决定 —— 桶是直连的,缺省会让预览变成一次下载。 */
+    put(key: string, bytes: Buffer, contentType?: string): Promise<void>;
+}
 /** 与 `SpsAsyncPoll` 同形 —— async 能力的 `poll` 可以**直接透传**。 */
 export type SpsJobStatus = SpsAsyncPoll;
 /**
@@ -479,6 +623,7 @@ export declare const SPS_SERVICES: {
     readonly projects: "sps.projects";
     readonly cards: "sps.cards";
     readonly jobs: "sps.jobs";
+    readonly storage: "sps.storage";
     readonly subprocess: "sps.subprocess";
     readonly attachments: "sps.attachments";
     readonly media: "sps.media";
@@ -501,6 +646,7 @@ export interface SpsPluginContext {
     'sps.projects': SpsProjects;
     'sps.cards': SpsCards;
     'sps.jobs': SpsJobs;
+    'sps.storage': SpsStorage;
     'sps.capabilities': SpsCapabilities;
     'sps.media': SpsMedia;
     'sps.im': SpsRegistryByKey;

package/dist/index.js

@@ -11,6 +11,50 @@
  * ⚠️ 这里只声明**插件会调的那一面**。服务内部还有别的方法(比如注册表的
  *    `list()`),不写进来 —— 写进来就等于承诺它们不变,而那不是我们打算承诺的。
  */
+// ── 跨后端必须一致的算法 ──────────────────────────────────────────────────
+//
+// 🔴 放这里的判据只有一条:**两个后端对它给出不同答案会出错**。
+//    "什么算重复"若两个后端不一致,同一条记忆在不同后端行为不同;
+//    摘要格式不一致,人看到的 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 = {
@@ -24,6 +68,7 @@ export const SPS_SERVICES = {
     projects: 'sps.projects',
     cards: 'sps.cards',
     jobs: 'sps.jobs',
+    storage: 'sps.storage',
     subprocess: 'sps.subprocess',
     attachments: 'sps.attachments',
     media: 'sps.media',

package/package.json

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