@coralai/sps-plugin-api 0.8.0 → 0.10.0

package/dist/index.d.ts

@@ -121,12 +121,18 @@ export interface SpsCapabilityBase {
     mode: 'sync' | 'async';
     /**
      * 参数形状由**能力**定,不是卡片里的自由 JSON。
-     * ⚠️ 运行时必须是一个 **Zod schema**(能力表拿它校验卡片参数)——
-     *    这里只声明结构最小面,免得契约包为此依赖 zod。
+     *
+     * ✅ **两种都收**:Zod schema,或**标准 JSON Schema**
+     * (`{type:'object', properties, required}` —— 和 `sps.tools.inputSchema` 同形)。
+     * 注册时归一成 Zod;两种都不是**当场抛**,插件挂不上。
+     *
+     * 🔴 **为什么要收两种**:`sps.tools.inputSchema` 是 JSON Schema,而这里原本只收 Zod ——
+     *    同一个 API 面上同名字段两种含义,两种插件都写的作者必然会混
+     *    (实测有人 5 个能力全传了 JSON Schema)。而如果他写的是 `.mjs`,类型也拦不住。
      */
     inputSchema: {
         parse(value: unknown): unknown;
-    };
+    } | Record<string, unknown>;
     /**
      * 这个能力会写什么(相对项目根的路径模式)。
      * 🔴 **可审计性的来源**:不读代码就知道这张卡会写什么。
@@ -248,6 +254,30 @@ export interface SpsNotifier {
         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;
 /**
@@ -473,6 +503,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";
@@ -495,6 +526,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

@@ -24,6 +24,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.8.0",
+  "version": "0.10.0",
   "description": "sps 宿主半区的插件契约:ctx 上那些服务的方法签名。插件装它拿类型。",
   "type": "module",
   "main": "./dist/index.js",