@coralai/sps-plugin-api 0.5.1 → 0.7.0

package/dist/index.d.ts

@@ -94,6 +94,134 @@ export interface SpsPromptSection {
 export interface SpsSystemPrompt {
     section(section: SpsPromptSection): () => void;
 }
+/**
+ * 一个**工具卡能力** —— 由编排驱动、不占 worker 槽位的那类执行体。
+ *
+ * 🔴 和 `sps.tools`(MCP 工具)的区别不是形状,是**谁触发、多久**:
+ *    MCP 工具是 **agent 主动调**,agent 阻塞等它 —— 适合秒级。
+ *    能力是**编排调度的一张卡**,和 worker 并行、可以跑分钟级,
+ *    `mode:'async'` 的甚至返回后任务仍在跑(由 join 卡等终态)。
+ *    要做"生成一批图"这种事,选能力,别选工具。
+ */
+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';
+    /**
+     * 参数形状由**能力**定,不是卡片里的自由 JSON。
+     * ⚠️ 运行时必须是一个 **Zod schema**(能力表拿它校验卡片参数)——
+     *    这里只声明结构最小面,免得契约包为此依赖 zod。
+     */
+    inputSchema: {
+        parse(value: unknown): unknown;
+    };
+    /**
+     * 这个能力会写什么(相对项目根的路径模式)。
+     * 🔴 **可审计性的来源**:不读代码就知道这张卡会写什么。
+     * ⚠️ 你声明了不等于 sps 会拦 —— 越界靠围栏兜(realpath + 项目根内),不靠这条声明。
+     */
+    produces: string[];
+    /** 可信度来源。卡片不看这一格,**审计要看**。 */
+    source: {
+        kind: 'built-in';
+    } | {
+        kind: 'script';
+        template: string;
+        script: string;
+    };
+    /** 一句话说明,给编排页展示。 */
+    summary: string;
+    /**
+     * 这个能力失败时,**这张卡怎么处置**。缺省 `'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;
+    list(): SpsCapability[];
+}
+/**
+ * ⚠️ 下面四个的**载荷形状**(adapter / factory)住在 sps 里,还没有真实的第三方消费方,
+ *    所以这里只声明**注册表本身**,载荷留 `unknown`。
+ *    要写这四类插件时告诉我们,按真实需求把形状定出来 ——
+ *    凭空定一个大接口,大概率定错位置和粒度。
+ */
+export interface SpsRegistryByKey<T = unknown> {
+    register(key: string, value: T): () => void;
+    get(key: string): T | undefined;
+    list(): string[];
+}
+/** 工厂自带 id,注册时不另给 key。 */
+export interface SpsRegistryByFactory<T = unknown> {
+    register(factory: T): () => void;
+    list(): string[];
+}
+/**
+ * ⚠️ 同上:这两个是**甲·工厂型**(换实现,不是收一组),
+ *    今天没有第三方在换它们。声明方法名,形状留 `unknown`。
+ */
+export interface SpsMemory {
+    buildInjection(refs: unknown[]): string;
+}
+export interface SpsNotifier {
+    open(config: unknown): {
+        send(message: string, level?: 'info' | 'success' | 'warning' | 'error'): Promise<void>;
+    };
+}
 /** 建一张卡。形状照 MCP 面上的 `add_card`,不另发明。 */
 export interface SpsNewCard {
     title: string;
@@ -318,6 +446,13 @@ export interface SpsPluginContext {
     'sps.events': SpsEvents;
     'sps.projects': SpsProjects;
     'sps.cards': SpsCards;
+    'sps.capabilities': SpsCapabilities;
+    'sps.media': SpsRegistryByKey;
+    'sps.im': SpsRegistryByKey;
+    'sps.agents': SpsRegistryByFactory;
+    'sps.repo': SpsRegistryByFactory;
+    'sps.memory': SpsMemory;
+    'sps.notifier': SpsNotifier;
     'sps.subprocess': SpsSubprocess;
     'sps.attachments': SpsAttachments;
 }

package/package.json

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