@coralai/sps-plugin-api 0.3.0 → 0.5.0

package/dist/index.d.ts

@@ -94,6 +94,45 @@ export interface SpsPromptSection {
 export interface SpsSystemPrompt {
     section(section: SpsPromptSection): () => void;
 }
+/** 建一张卡。形状照 MCP 面上的 `add_card`,不另发明。 */
+export interface SpsNewCard {
+    title: string;
+    description?: string;
+    skills?: string[];
+    /** `['AI-PIPELINE']` 让它走流水线;缺省不走。 */
+    labels?: string[];
+    /** 执行波次(正整数)。缺省 = seq(串行)。 */
+    order?: number;
+    /** 只接受 `'tool' | 'join'`;缺省即 worker。 */
+    kind?: 'tool' | 'join';
+    tool?: string;
+    input?: Record<string, unknown>;
+    checklist?: string[];
+}
+export interface SpsCardRef {
+    seq: number;
+    title: string;
+    state: string;
+    order: number;
+    labels: string[];
+    skills: string[];
+}
+/**
+ * 卡片(**建 / 列**)。
+ *
+ * 🔴 它存在的理由是"知识住哪":按你自己的规则建卡(几张、什么内容),
+ *    而 sps **不必认识那些规则**。你在进程内,读工作区文件直接用 fs,
+ *    不需要 sps 开 HTTP 读口、也不需要一张越长越长的文件白名单。
+ *
+ * ⚠️ **幂等归你**:建卡天然不幂等(建两次就是两张),而"什么算重复"只有你知道。
+ *    用 `list` 自己判 —— 别指望这一层替你去重。
+ * ⚠️ 不开 move / delete:那些是流水线在做的事,掺进来就有两个写入方。
+ */
+export interface SpsCards {
+    /** 失败**抛**(建卡没成功而静默返回,你会以为建好了)。 */
+    create(project: string, card: SpsNewCard): Promise<SpsCardRef>;
+    list(project: string): Promise<SpsCardRef[]>;
+}
 /**
  * 一个项目的**身份**信息。
  *
@@ -142,11 +181,27 @@ export interface SpsEvent {
  * 🔴 **别在回调里做慢事**:宿主不 await 你,但你占着的是发布方的调用栈。
  *    要发网络请求就自己排队。
  *
- * 今天宿主发的:
+ * 今天宿主发的(三个前缀,订阅时按前缀过滤):
  * ```
- * card.moved      { seq, to }        card.labeled   { seq, label }
- * card.unlabeled  { seq, label }     card.claimed   { seq, slot }
- * card.released   { seq }            card.created   { seq, title, state }
+ * 卡片 —— 发在**写入漏斗**上,不管是流水线改的、界面改的还是 CLI 改的都收得到
+ *   card.moved      { seq, to }          card.labeled    { seq, label }
+ *   card.unlabeled  { seq, label }       card.claimed    { seq, slot }
+ *   card.released   { seq }              card.created    { seq, title, state }
+ *   card.flagged    { seq, label, reason }   ← 被标成 NEEDS-FIX / BLOCKED 之类
+ *
+ * worker —— 发在**引擎判定的那一刻**(它没有写入漏斗:"这个 worker 丢了"是判断)
+ *   worker.started        { seq, slot }
+ *   worker.stageCompleted { seq, stage, reason }
+ *   worker.completed      { seq, ok, errors? }   ← ok 分开报:干完了 vs 干完了但收尾出错
+ *   worker.failed         { seq, reason, exitCode? }
+ *   worker.lost           { seq, reason, recovered }
+ *   worker.timeout        { seq, elapsedHours }
+ *   worker.retrying       { seq, attempt, limit, reason }
+ *   worker.blocked        { seq, limit }          ← 重试用尽,要人介入
+ *   worker.waiting        { seq, kind, prompt }   ← **要人点头才能继续**
+ *
+ * pipeline
+ *   pipeline.started { pid? }   pipeline.stopped {}   pipeline.completed {}
  * ```
  */
 export interface SpsEvents {
@@ -232,6 +287,7 @@ export declare const SPS_SERVICES: {
     readonly llm: "sps.llm";
     readonly events: "sps.events";
     readonly projects: "sps.projects";
+    readonly cards: "sps.cards";
     readonly subprocess: "sps.subprocess";
     readonly attachments: "sps.attachments";
     readonly media: "sps.media";
@@ -252,6 +308,7 @@ export interface SpsPluginContext {
     'sps.llm': SpsLlm;
     'sps.events': SpsEvents;
     'sps.projects': SpsProjects;
+    'sps.cards': SpsCards;
     'sps.subprocess': SpsSubprocess;
     'sps.attachments': SpsAttachments;
 }

package/dist/index.js

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

package/package.json

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