@coralai/sps-plugin-api 0.6.0 → 0.7.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;

package/package.json

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