@coralai/sps-plugin-api 0.1.0

package/README.md

@@ -0,0 +1,32 @@
+# @coralai/sps-plugin-api
+
+sps **宿主半区**的插件契约:`ctx` 上那些服务的方法签名。
+
+```bash
+npm i -D @coralai/sps-plugin-api
+```
+
+```ts
+import type { SpsPluginContext } from '@coralai/sps-plugin-api';
+
+export const name = 'coral-plugin-x';
+export const inject = ['sps.tools'];
+
+export function apply(ctx: SpsPluginContext, config: { greeting?: string }) {
+  ctx.effect(() =>            // 🔴 注册一定要放进 effect,否则停用时收不干净
+    ctx['sps.tools'].register({
+      name: 'my_tool',
+      description: '给 agent 用的工具',
+      inputSchema: { type: 'object', properties: {} },   // 标准 JSON Schema
+      handler: async (args, session) => ({ content: [{ type: 'text', text: 'ok' }] }),
+    }),
+  );
+}
+```
+
+这个包**只声明插件会调的那一面**。服务内部还有别的方法(注册表的 `list()` 之类),
+不写进来 —— 写进来就等于承诺它们不变。
+
+sps-cli 仓里有一道一致性判据钉着这份契约:实现与它对不上,**sps-cli 自己的 check 会红**。
+
+完整写法见 sps-cli 仓的 `docs/guides/writing-plugins.md`。

package/dist/index.d.ts

@@ -0,0 +1,159 @@
+/**
+ * @coralai/sps-plugin-api —— **sps 宿主半区的插件契约**。
+ *
+ * 插件装它拿类型:`ctx['sps.tools']` 这些服务的方法签名。
+ *
+ * 🔴 **这个包是契约的真源,宿主去符合它** —— 不是反过来。
+ *    反过来(从宿主导出类型)的话,包永远滞后于实现,
+ *    而作者看到的类型和实际行为对不上时,他没法判断该信哪个。
+ *    sps-cli 侧有一道一致性判据钉着:seam 与这里的接口对不上,**它自己的 check 会红**。
+ *
+ * ⚠️ 这里只声明**插件会调的那一面**。服务内部还有别的方法(比如注册表的
+ *    `list()`),不写进来 —— 写进来就等于承诺它们不变,而那不是我们打算承诺的。
+ */
+export interface SpsToolSession {
+    cwd: string;
+    project?: string;
+    agentId?: string;
+}
+export interface SpsToolResult {
+    content: {
+        type: 'text';
+        text: string;
+    }[];
+    isError?: boolean;
+}
+export interface SpsToolDef {
+    name: string;
+    description: string;
+    /** 标准 JSON Schema 的 object。宿主会转成 MCP 要的形状。 */
+    inputSchema: {
+        type: 'object';
+        properties?: Record<string, unknown>;
+        required?: string[];
+    };
+    handler: (args: Record<string, unknown>, session: SpsToolSession) => Promise<SpsToolResult>;
+}
+export interface SpsToolsRegistry {
+    /** 返回注销函数 —— **放进 `ctx.effect(...)`**,否则停用时收不干净。 */
+    register(def: SpsToolDef): () => void;
+}
+/** 凭据**引用**(环境变量名的形状),不是值。 */
+export type CredentialRef = string;
+export interface SpsCredentials {
+    /** 取真值。**每次操作现解**,别缓存到闭包里 —— 换密钥就是靠这一点不用重挂。 */
+    resolve(ref: CredentialRef): Promise<{
+        value: string;
+        source: string;
+    } | undefined>;
+    /** 给界面看的描述。**绝不含值。** */
+    describe(ref: CredentialRef): Promise<{
+        ref: string;
+        configured: boolean;
+        source?: string;
+        writable: boolean;
+    }>;
+    set(ref: CredentialRef, value: string): Promise<void>;
+    unset(ref: CredentialRef): Promise<void>;
+}
+export interface SpsWebRoute {
+    kind: 'exact' | 'prefix';
+    /** 相对路径。默认会前缀成 `/plugins/<你的id>/...`。 */
+    path: string;
+    handler: (req: unknown, res: unknown) => void | Promise<void>;
+    /**
+     * 接管宿主已有路径。允许,但**必须显式写出来**,而且会显示在插件页的
+     * 「接管了 N 条宿主路由」里 —— 能接管不可怕,接管了没人知道才可怕。
+     */
+    takeover?: boolean;
+}
+export interface SpsWebServer {
+    register(owner: string, route: SpsWebRoute): () => void;
+}
+export interface SpsSettingsScope<T = unknown> {
+    get(): T;
+    watch(cb: (next: T, prev: T) => void): () => void;
+}
+export interface SpsSettings {
+    /**
+     * 注册一个命名空间。**同名重复注册会抛。**
+     * `base` 一般就是 `apply(ctx, config)` 收到的那个 config。
+     */
+    register<T>(ns: string, schema?: unknown, options?: {
+        base?: T;
+    }): SpsSettingsScope<T>;
+}
+export interface SpsPromptSection {
+    /** 段名,重复会抛。 */
+    name: string;
+    /** 排序键,小的在前。内建规则是 0。 */
+    order: number;
+    /** 字符串,或每次组装现求值的函数。 */
+    text: string | (() => string);
+}
+export interface SpsSystemPrompt {
+    section(section: SpsPromptSection): () => void;
+}
+export interface SpsSpawnSpec {
+    argv: readonly string[];
+    cwd: string;
+    env?: Record<string, string | undefined>;
+    signal?: AbortSignal;
+    /** 收到取消后等它自己退出多久才 SIGKILL。默认 5000。 */
+    graceMs?: number;
+}
+export interface SpsSubprocess {
+    resolveExecutable(cmd: string): Promise<string | undefined>;
+    spawn(spec: SpsSpawnSpec): Promise<{
+        code: number | null;
+        stdout: string;
+        stderr: string;
+    }>;
+}
+export interface SpsImageRef {
+    /** `<sha256>.<ext>` —— 内容寻址,同一张图存两次是同一个 ref。 */
+    id: string;
+    mediaType: string;
+}
+export interface SpsAttachments {
+    validateImage(input: {
+        data: Uint8Array;
+        mediaType: string;
+        name?: string;
+    }): Promise<void>;
+    saveImage(input: {
+        data: Uint8Array;
+        mediaType: string;
+        name?: string;
+    }): Promise<SpsImageRef>;
+    readImage(ref: SpsImageRef): Promise<SpsImageRef & {
+        data: Uint8Array;
+    }>;
+}
+/** 插件 `inject` 里写的名字。 */
+export declare const SPS_SERVICES: {
+    readonly tools: "sps.tools";
+    readonly credentials: "sps.credentials";
+    readonly webserver: "sps.webserver";
+    readonly settings: "sps.settings";
+    readonly systemPrompt: "sps.systemPrompt";
+    readonly subprocess: "sps.subprocess";
+    readonly attachments: "sps.attachments";
+    readonly media: "sps.media";
+    readonly im: "sps.im";
+    readonly capabilities: "sps.capabilities";
+    readonly agents: "sps.agents";
+    readonly repo: "sps.repo";
+    readonly memory: "sps.memory";
+    readonly notifier: "sps.notifier";
+};
+/** 插件 ctx 上能拿到的服务(只列已声明契约的那几个)。 */
+export interface SpsPluginContext {
+    'sps.tools': SpsToolsRegistry;
+    'sps.credentials': SpsCredentials;
+    'sps.webserver': SpsWebServer;
+    'sps.settings': SpsSettings;
+    'sps.systemPrompt': SpsSystemPrompt;
+    'sps.subprocess': SpsSubprocess;
+    'sps.attachments': SpsAttachments;
+}

package/dist/index.js

@@ -0,0 +1,31 @@
+/**
+ * @coralai/sps-plugin-api —— **sps 宿主半区的插件契约**。
+ *
+ * 插件装它拿类型:`ctx['sps.tools']` 这些服务的方法签名。
+ *
+ * 🔴 **这个包是契约的真源,宿主去符合它** —— 不是反过来。
+ *    反过来(从宿主导出类型)的话,包永远滞后于实现,
+ *    而作者看到的类型和实际行为对不上时,他没法判断该信哪个。
+ *    sps-cli 侧有一道一致性判据钉着:seam 与这里的接口对不上,**它自己的 check 会红**。
+ *
+ * ⚠️ 这里只声明**插件会调的那一面**。服务内部还有别的方法(比如注册表的
+ *    `list()`),不写进来 —— 写进来就等于承诺它们不变,而那不是我们打算承诺的。
+ */
+// ── 服务名 ───────────────────────────────────────────────────────────────
+/** 插件 `inject` 里写的名字。 */
+export const SPS_SERVICES = {
+    tools: 'sps.tools',
+    credentials: 'sps.credentials',
+    webserver: 'sps.webserver',
+    settings: 'sps.settings',
+    systemPrompt: 'sps.systemPrompt',
+    subprocess: 'sps.subprocess',
+    attachments: 'sps.attachments',
+    media: 'sps.media',
+    im: 'sps.im',
+    capabilities: 'sps.capabilities',
+    agents: 'sps.agents',
+    repo: 'sps.repo',
+    memory: 'sps.memory',
+    notifier: 'sps.notifier',
+};

package/package.json

@@ -0,0 +1,32 @@
+{
+  "name": "@coralai/sps-plugin-api",
+  "version": "0.1.0",
+  "description": "sps 宿主半区的插件契约:ctx 上那些服务的方法签名。插件装它拿类型。",
+  "type": "module",
+  "main": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "default": "./dist/index.js"
+    }
+  },
+  "files": [
+    "dist",
+    "README.md"
+  ],
+  "keywords": [
+    "sps",
+    "coralai",
+    "plugin",
+    "seam",
+    "api"
+  ],
+  "license": "MIT",
+  "publishConfig": {
+    "access": "public"
+  },
+  "scripts": {
+    "build": "tsc -p tsconfig.json"
+  }
+}