@coralai/sps-plugin-api 0.13.0 → 0.15.0

package/dist/index.d.ts

@@ -382,6 +382,29 @@ export interface SpsWorkspace {
     discover(): Promise<SpsWorkspaceProject[]>;
     /** 某产品的用户资产范围。没有声明时回落窄兜底,并把 `usedDefault` 置真。 */
     assetScope(product: string): SpsAssetScope;
+    /**
+     * 构建方声明的产物目录(`<repoDir>/.sps/build.json` 的 `outDir`)。
+     *
+     * 🔴 **三态,别塌成两态**:
+     * ```
+     * undefined  没声明（文件不在 / 没这个字段 / 坏 JSON）
+     * null       声明了「这个项目没有产物目录」
+     * string     声明的相对目录
+     * ```
+     *    把 `null` 和 `undefined` 合成一个,就分不出「构建方说没有」和「构建方没说」——
+     *    而前者该照做,后者只能去猜。
+     *
+     * 🔴 **别自己读 `.sps/build.json`。** 它取代的正是"三方各自猜"那个形状:
+     *    sps 的 play.ts、插件的 publish.mjs 曾各写一份
+     *    `exists(dist/index.html) ? dist : repoDir` 的三元(逐字相同)。
+     *    现有项目全是 vite(默认 `dist`)所以一直没露;webpack 默认 `build`、Next 是 `.next`
+     *    ⇒ 只要有一个项目的打包器输出不是 dist,猜的那份当场就错,而表现是
+     *    "预览到未构建的源码",**零报错**。
+     *
+     * ⚠️ 它在 `sps.workspace` 而不是别处,是因为这是**读工作区里的一个约定文件** ——
+     *    和 `assetScope` 同类:约定由宿主定,插件问宿主要答案,而不是自己拼路径。
+     */
+    declaredOutDir(repoDir: string): string | null | undefined;
 }
 /**
  * `p` 是否在 `root` 之内(含 root 自身)。
@@ -418,6 +441,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 +676,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 +705,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 +727,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.15.0",
   "description": "sps 宿主半区的插件契约:ctx 上那些服务的方法签名。插件装它拿类型。",
   "type": "module",
   "main": "./dist/index.js",