@coralai/sps-plugin-api 0.5.0 → 0.6.0

package/dist/index.d.ts

@@ -94,6 +94,84 @@ export interface SpsPromptSection {
 export interface SpsSystemPrompt {
     section(section: SpsPromptSection): () => void;
 }
+/**
+ * 一个**工具卡能力** —— 由编排驱动、不占 worker 槽位的那类执行体。
+ *
+ * 🔴 和 `sps.tools`(MCP 工具)的区别不是形状,是**谁触发、多久**:
+ *    MCP 工具是 **agent 主动调**,agent 阻塞等它 —— 适合秒级。
+ *    能力是**编排调度的一张卡**,和 worker 并行、可以跑分钟级,
+ *    `mode:'async'` 的甚至返回后任务仍在跑(由 join 卡等终态)。
+ *    要做"生成一批图"这种事,选能力,别选工具。
+ */
+export interface SpsCapability {
+    /** 能力 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;
+    /** 执行体。`async` 能力返回后**任务仍在跑**。 */
+    run(input: unknown, ctx: {
+        /** 项目在共享树下的相对路径(`t<租户>/<产品>/<项目>`)。 */
+        project: string;
+        /** 项目工作区绝对路径。**能力不从卡片收路径**,只从这里取根。 */
+        projectDir: string;
+    }): Promise<Record<string, unknown>>;
+}
+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;
@@ -129,7 +207,16 @@ export interface SpsCardRef {
  * ⚠️ 不开 move / delete:那些是流水线在做的事,掺进来就有两个写入方。
  */
 export interface SpsCards {
-    /** 失败**抛**(建卡没成功而静默返回,你会以为建好了)。 */
+    /**
+     * 失败**抛**(建卡没成功而静默返回,你会以为建好了)。
+     *
+     * 🔴 **你传的 `labels` 会被核对**:落不上会抛,并把 `seq` 带出来。
+     *    底层 `setLabels` 失败是被吞掉的,而回执在某些路径下会拿你传的值填 ——
+     *    两处叠加就是"卡建了、label 没落上、回执还说落上了"。
+     *    对 `AI-PIPELINE` 那只是"没走流水线";
+     *    但拿 label 当**幂等键**时,下一轮找不到键就会**重复建一整套**,全程不报错。
+     *    ⇒ 这一层替你核过了。抛的时候卡**已经建了**,`seq` 在错误消息里,自己收拾。
+     */
     create(project: string, card: SpsNewCard): Promise<SpsCardRef>;
     list(project: string): Promise<SpsCardRef[]>;
 }
@@ -309,6 +396,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.0",
+  "version": "0.6.0",
   "description": "sps 宿主半区的插件契约:ctx 上那些服务的方法签名。插件装它拿类型。",
   "type": "module",
   "main": "./dist/index.js",