@coralai/sps-plugin-api 0.13.0 → 0.14.0

package/dist/index.d.ts

@@ -418,6 +418,27 @@ export interface SpsNotifier {
         send(message: string, level?: 'info' | 'success' | 'warning' | 'error'): Promise<void>;
     };
 }
+export interface SpsStorageObject {
+    key: string;
+    /** **内容判据**(单段上传时等于 md5)。不看时间。 */
+    etag: string;
+    size: number;
+}
+/**
+ * 对象存储(读 / 列 / 写)。**由插件提供** —— 没装桶插件时这个服务不存在,
+ * inject 它的插件会 PENDING。
+ *
+ * ⚠️ 桶没配时三个方法都抛 ⇒ **先用 `configured()` 问一句**,别拿异常当分支。
+ * 🔴 读不了的前缀会**抛**,不会回空 —— "库是空的"和"我没权限"混成一个,
+ *    人会去补素材而不是去补策略。
+ */
+export interface SpsStorage {
+    configured(): boolean;
+    /** 不存在 ⇒ `null`;连不上/没权限 ⇒ **抛**。 */
+    get(key: string): Promise<Buffer | null>;
+    list(prefix: string): Promise<SpsStorageObject[]>;
+    put(key: string, bytes: Buffer, contentType?: string): Promise<void>;
+}
 /** 与 `SpsAsyncPoll` 同形 —— async 能力的 `poll` 可以**直接透传**。 */
 export type SpsJobStatus = SpsAsyncPoll;
 /**
@@ -632,6 +653,16 @@ export interface SpsAttachments {
     }>;
 }
 /** 插件 `inject` 里写的名字。 */
+/**
+ * **由插件提供**的服务 —— 宿主装配后它们**不一定在**。
+ *
+ * 🔴 inject 它们的插件要接受"没装那个插件就 PENDING"这件事。
+ * ⚠️ 这张表是给门禁用的单一真源:宿主的 conformance 判据据此
+ *    豁免这些名字("契约里列的服务装配后都在"对它们不成立)。
+ *    2026-08-28 加,起因是把 `sps.storage` 从宿主挪进插件后,
+ *    那条判据把"实现搬家了"报成了"契约说谎"。
+ */
+export declare const PLUGIN_PROVIDED_SERVICES: readonly ["sps.storage", "sps.memory"];
 export declare const SPS_SERVICES: {
     readonly tools: "sps.tools";
     readonly credentials: "sps.credentials";
@@ -651,6 +682,7 @@ export declare const SPS_SERVICES: {
     readonly agents: "sps.agents";
     readonly repo: "sps.repo";
     readonly memory: "sps.memory";
+    readonly storage: "sps.storage";
     readonly workspace: "sps.workspace";
     readonly notifier: "sps.notifier";
 };
@@ -672,6 +704,7 @@ export interface SpsPluginContext {
     'sps.agents': SpsRegistryByFactory;
     'sps.repo': SpsRegistryByFactory;
     'sps.memory': SpsMemory;
+    'sps.storage': SpsStorage;
     'sps.workspace': SpsWorkspace;
     'sps.notifier': SpsNotifier;
     'sps.subprocess': SpsSubprocess;

package/dist/index.js

@@ -117,6 +117,16 @@ export function buildMemoryDigest(entries, opts = {}) {
 }
 // ── 服务名 ───────────────────────────────────────────────────────────────
 /** 插件 `inject` 里写的名字。 */
+/**
+ * **由插件提供**的服务 —— 宿主装配后它们**不一定在**。
+ *
+ * 🔴 inject 它们的插件要接受"没装那个插件就 PENDING"这件事。
+ * ⚠️ 这张表是给门禁用的单一真源:宿主的 conformance 判据据此
+ *    豁免这些名字("契约里列的服务装配后都在"对它们不成立)。
+ *    2026-08-28 加,起因是把 `sps.storage` 从宿主挪进插件后,
+ *    那条判据把"实现搬家了"报成了"契约说谎"。
+ */
+export const PLUGIN_PROVIDED_SERVICES = ['sps.storage', 'sps.memory'];
 export const SPS_SERVICES = {
     tools: 'sps.tools',
     credentials: 'sps.credentials',
@@ -136,6 +146,7 @@ export const SPS_SERVICES = {
     agents: 'sps.agents',
     repo: 'sps.repo',
     memory: 'sps.memory',
+    storage: 'sps.storage',
     workspace: 'sps.workspace',
     notifier: 'sps.notifier',
 };

package/package.json

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