@coralai/sps-plugin-api 0.7.0 → 0.9.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>;
     /**
      * 这个能力会写什么(相对项目根的路径模式)。
      * 🔴 **可审计性的来源**:不读代码就知道这张卡会写什么。
@@ -205,6 +211,32 @@ export interface SpsRegistryByKey<T = unknown> {
     get(key: string): T | undefined;
     list(): string[];
 }
+/** `sps.media`:注册表 + **一个使用方法**。 */
+export interface SpsMedia extends SpsRegistryByKey {
+    /**
+     * 用注册进来的适配器生成一个媒体资产并落盘。
+     *
+     * ⚠️ **同步等待**(一张图几十秒)。async 能力应当把它丢进 `sps.jobs`,
+     *    不要在 `start` 里 await —— 那会把 tick 卡住。
+     */
+    generate(spec: {
+        capability: 'image' | 'video' | 'music' | 'voice' | '3d' | 'embedding' | 'rerank';
+        prompt: string;
+        /** 运行目录(产物落这)。 */
+        cwd: string;
+        /** 相对 cwd 的输出路径;省略则自动命名到 assets/。 */
+        outPath?: string;
+        size?: string;
+        referenceUrl?: string;
+        /** 点名用哪一家;不传 = 按能力解析默认那家。 */
+        providerId?: string;
+    }): Promise<{
+        path: string;
+        provider: string;
+        model?: string;
+        bytes: number;
+    }>;
+}
 /** 工厂自带 id,注册时不另给 key。 */
 export interface SpsRegistryByFactory<T = unknown> {
     register(factory: T): () => void;
@@ -222,6 +254,27 @@ export interface SpsNotifier {
         send(message: string, level?: 'info' | 'success' | 'warning' | 'error'): Promise<void>;
     };
 }
+/** 与 `SpsAsyncPoll` 同形 —— async 能力的 `poll` 可以**直接透传**。 */
+export type SpsJobStatus = SpsAsyncPoll;
+/**
+ * 后台任务表:async 能力用它把长任务跑起来并拿到 handle。
+ *
+ * ```js
+ * start: (input, ctx) => ({ handle: jobs.start(() => media.generate({...})) }),
+ * poll:  (handle) => jobs.poll(handle),      // 形状一样,直接透传
+ * ```
+ *
+ * ⚠️ **在内存里。** `sps tick <project>` 是常驻循环进程,start 与 poll 在同一个进程 ——
+ *    但它会被 stop / 重启,那时 handle 就没了。
+ * 🔴 **认不出的 handle 会当失败并说明原因**,不会回 `{done:false}` ——
+ *    后者的表现是卡片一直等到超时、然后被归因成"任务太慢",而真因是进程重启过。
+ * ⚠️ 不做持久化:重启 ⇒ 那张卡失败并说清楚 ⇒ 重跑它。
+ */
+export interface SpsJobs {
+    /** 立刻返回 handle。`fn` 抛出**不冒泡**(没人接得住),变成 `poll` 的 error。 */
+    start(fn: () => Promise<Record<string, unknown>>): string;
+    poll(handle: string): SpsJobStatus;
+}
 /** 建一张卡。形状照 MCP 面上的 `add_card`,不另发明。 */
 export interface SpsNewCard {
     title: string;
@@ -425,6 +478,7 @@ export declare const SPS_SERVICES: {
     readonly events: "sps.events";
     readonly projects: "sps.projects";
     readonly cards: "sps.cards";
+    readonly jobs: "sps.jobs";
     readonly subprocess: "sps.subprocess";
     readonly attachments: "sps.attachments";
     readonly media: "sps.media";
@@ -446,8 +500,9 @@ export interface SpsPluginContext {
     'sps.events': SpsEvents;
     'sps.projects': SpsProjects;
     'sps.cards': SpsCards;
+    'sps.jobs': SpsJobs;
     'sps.capabilities': SpsCapabilities;
-    'sps.media': SpsRegistryByKey;
+    'sps.media': SpsMedia;
     'sps.im': SpsRegistryByKey;
     'sps.agents': SpsRegistryByFactory;
     'sps.repo': SpsRegistryByFactory;

package/dist/index.js

@@ -23,6 +23,7 @@ export const SPS_SERVICES = {
     events: 'sps.events',
     projects: 'sps.projects',
     cards: 'sps.cards',
+    jobs: 'sps.jobs',
     subprocess: 'sps.subprocess',
     attachments: 'sps.attachments',
     media: 'sps.media',

package/package.json

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