@coralai/sps-plugin-api 0.6.0 → 0.8.0

package/dist/index.d.ts

@@ -103,7 +103,19 @@ export interface SpsSystemPrompt {
  *    `mode:'async'` 的甚至返回后任务仍在跑(由 join 卡等终态)。
  *    要做"生成一批图"这种事,选能力,别选工具。
  */
-export interface SpsCapability {
+export type SpsAsyncPoll = {
+    done: false;
+} | {
+    done: true;
+    ok: true;
+    result: Record<string, unknown>;
+} | {
+    done: true;
+    ok: false;
+    error: string;
+};
+/** 两种能力共有的那部分。 */
+export interface SpsCapabilityBase {
     /** 能力 id,卡片用它引用。命名 `<域>.<动作>`,如 `art.chromaKey`。 */
     id: string;
     mode: 'sync' | 'async';
@@ -131,14 +143,52 @@ export interface SpsCapability {
     };
     /** 一句话说明,给编排页展示。 */
     summary: string;
-    /** 执行体。`async` 能力返回后**任务仍在跑**。 */
-    run(input: unknown, ctx: {
-        /** 项目在共享树下的相对路径(`t<租户>/<产品>/<项目>`)。 */
-        project: string;
-        /** 项目工作区绝对路径。**能力不从卡片收路径**,只从这里取根。 */
-        projectDir: string;
-    }): Promise<Record<string, unknown>>;
+    /**
+     * 这个能力失败时,**这张卡怎么处置**。缺省 `'block'`。
+     * ```
+     * block  留在原地打 NEEDS-FIX —— 波次屏障挡住后面所有卡,图上看得见它卡住了
+     * skip   标 Canceled ⇒ 屏障**放行**,后续卡照跑(留痕写进卡片 meta)
+     * ```
+     * 🔴 声明式,不是"能力自己去改卡片状态" —— 后者会让卡片有两个写入方。
+     * ⚠️ `'skip'` 给"部分失败是常态"的工序用;scaffold/package 这种别用。
+     */
+    onFailure?: 'block' | 'skip';
+}
+export interface SpsCapabilityCtx {
+    /** 项目在共享树下的相对路径(`t<租户>/<产品>/<项目>`)。 */
+    project: string;
+    /** 项目工作区绝对路径。**能力不从卡片收路径**,只从这里取根。 */
+    projectDir: string;
 }
+/** 同步能力:`run` 返回即完成。 */
+export interface SpsSyncCapability extends SpsCapabilityBase {
+    mode: 'sync';
+    run(input: unknown, ctx: SpsCapabilityCtx): Promise<Record<string, unknown>>;
+}
+/**
+ * 异步能力:`start` 立刻返回,引擎每个 tick `poll` 一次。
+ *
+ * 🔴 **卡片在真正跑完之前不标 Done** —— 波次屏障(`order`)因此天然成为 join。
+ *    "打包必须等美术"用 order 表达即可,没有单独的 join 卡执行路径,也不需要。
+ */
+export interface SpsAsyncCapability extends SpsCapabilityBase {
+    mode: 'async';
+    /** 启动外部任务并**立刻返回**。handle 存进卡片 meta。 */
+    start(input: unknown, ctx: SpsCapabilityCtx): Promise<{
+        handle: string;
+    }>;
+    /**
+     * 问状态。**每个 tick 都会调 ⇒ 必须便宜且幂等。**
+     * 别在这里重新扫盘或重新请求全量 —— 它会按 tick 频率被放大。
+     */
+    poll(handle: string, ctx: SpsCapabilityCtx): Promise<SpsAsyncPoll>;
+    /**
+     * 多久算超时(ms)。缺省 **30 分钟**。
+     * ⚠️ 超时**由引擎按 startedAt 判**,不问你 —— 你可能正好卡死在自己的等待上。
+     */
+    timeoutMs?: number;
+}
+export type SpsCapability = SpsSyncCapability | SpsAsyncCapability;
 export interface SpsCapabilities {
     register(cap: SpsCapability): () => void;
     get(id: string): SpsCapability | undefined;
@@ -155,6 +205,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;
@@ -172,6 +248,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;
@@ -375,6 +472,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";
@@ -396,8 +494,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.6.0",
+  "version": "0.8.0",
   "description": "sps 宿主半区的插件契约:ctx 上那些服务的方法签名。插件装它拿类型。",
   "type": "module",
   "main": "./dist/index.js",