@coralai/sps-plugin-api 0.1.0 → 0.3.0

package/dist/index.d.ts

@@ -94,6 +94,98 @@ export interface SpsPromptSection {
 export interface SpsSystemPrompt {
     section(section: SpsPromptSection): () => void;
 }
+/**
+ * 一个项目的**身份**信息。
+ *
+ * ⚠️ 刻意不带卡片/worker 统计:那些每次都要扫盘。要统计走 HTTP API。
+ */
+export interface SpsProjectRef {
+    name: string;
+    /** 显示名。无则 null。 */
+    label: string | null;
+    /**
+     * 目录布局用的分段。
+     * ⚠️ **不是权限主体** —— sps 里它只决定工作区目录长什么样,不参与任何决策。
+     *    要按租户过滤是你自己的事。
+     */
+    namespace: string | null;
+    /** 创建方标记(`sps` / 平台名)。 */
+    origin: string;
+    repoDir: string | null;
+}
+/**
+ * 项目注册表(**只读**)。
+ *
+ * 🔴 v1 不开"建项目" —— 那牵着注册边界那一摊(建项目会改写被认领的树)。
+ */
+export interface SpsProjects {
+    list(): Promise<SpsProjectRef[]>;
+    /** 不存在返回 `undefined`,**不抛**。 */
+    get(name: string): Promise<SpsProjectRef | undefined>;
+}
+export interface SpsEvent {
+    /** 事件名。点分层级,订阅时按前缀过滤(`'card.'` 收全部卡片事件)。 */
+    type: string;
+    /** 发生时刻(ms),由**发布方**打 —— 你拿到的时间可能晚很多。 */
+    at: number;
+    /** 谁发的:`sps` = 宿主,其余是插件 id。 */
+    source: string;
+    project?: string;
+    /** 🔴 只有 sps 自己的概念(project / seq / state / slot …)。**没有租户 id** —— 那是平台自己的映射。 */
+    payload: Record<string, unknown>;
+}
+/**
+ * 订阅"执行侧真的发生了什么"。
+ *
+ * 🔴 **没有重放、没有缓冲。** 进程没跑时发生的事拿不到,你掉线期间的也补不回来。
+ *    **对账走 API**,别把它当可靠队列 —— 否则会出现"我以为我知道、其实漏了一段"。
+ * 🔴 **别在回调里做慢事**:宿主不 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 }
+ * ```
+ */
+export interface SpsEvents {
+    emit(ev: Omit<SpsEvent, 'at' | 'source'> & {
+        source?: string;
+    }): void;
+    subscribe(prefix: string, cb: (ev: SpsEvent) => void): () => void;
+}
+export interface SpsLlmTextRequest {
+    prompt: string;
+    system?: string;
+    /**
+     * 谁在调 —— 你的插件 id。**必填**:插件调模型花的是宿主的额度,
+     * 归因唯一可靠的来源是调用方自报(从调用栈猜会在异步边界上失真)。
+     */
+    by: string;
+    /** 上限,超了当失败。默认 180s。 */
+    timeoutMs?: number;
+}
+export interface SpsLlmTextResult {
+    text: string;
+    /** 实际用的模型。 */
+    model: string;
+}
+/**
+ * 用 sps 配好的模型出一段文本。
+ *
+ * 🔴 **它不是 dsh 的 `llm`。** dsh 的那个是一整套适配器注册表
+ *    (`stream / listModels / resolveModel / registerAdapter / …`)。
+ *    这里只承诺一件事:出一段文本。别照着 dsh 的用法写。
+ */
+export interface SpsLlm {
+    text(req: SpsLlmTextRequest): Promise<SpsLlmTextResult>;
+    /** 现在会用哪个模型(不发请求)。 */
+    describe(): {
+        provider: string;
+        model: string;
+    };
+}
 export interface SpsSpawnSpec {
     argv: readonly string[];
     cwd: string;
@@ -137,6 +229,9 @@ export declare const SPS_SERVICES: {
     readonly webserver: "sps.webserver";
     readonly settings: "sps.settings";
     readonly systemPrompt: "sps.systemPrompt";
+    readonly llm: "sps.llm";
+    readonly events: "sps.events";
+    readonly projects: "sps.projects";
     readonly subprocess: "sps.subprocess";
     readonly attachments: "sps.attachments";
     readonly media: "sps.media";
@@ -154,6 +249,9 @@ export interface SpsPluginContext {
     'sps.webserver': SpsWebServer;
     'sps.settings': SpsSettings;
     'sps.systemPrompt': SpsSystemPrompt;
+    'sps.llm': SpsLlm;
+    'sps.events': SpsEvents;
+    'sps.projects': SpsProjects;
     'sps.subprocess': SpsSubprocess;
     'sps.attachments': SpsAttachments;
 }

package/dist/index.js

@@ -19,6 +19,9 @@ export const SPS_SERVICES = {
     webserver: 'sps.webserver',
     settings: 'sps.settings',
     systemPrompt: 'sps.systemPrompt',
+    llm: 'sps.llm',
+    events: 'sps.events',
+    projects: 'sps.projects',
     subprocess: 'sps.subprocess',
     attachments: 'sps.attachments',
     media: 'sps.media',

package/package.json

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