@coralai/sps-plugin-api 0.12.0 → 0.14.0

package/dist/index.d.ts

@@ -1,16 +1,3 @@
-/**
- * @coralai/sps-plugin-api —— **sps 宿主半区的插件契约**。
- *
- * 插件装它拿类型:`ctx['sps.tools']` 这些服务的方法签名。
- *
- * 🔴 **这个包是契约的真源,宿主去符合它** —— 不是反过来。
- *    反过来(从宿主导出类型)的话,包永远滞后于实现,
- *    而作者看到的类型和实际行为对不上时,他没法判断该信哪个。
- *    sps-cli 侧有一道一致性判据钉着:seam 与这里的接口对不上,**它自己的 check 会红**。
- *
- * ⚠️ 这里只声明**插件会调的那一面**。服务内部还有别的方法(比如注册表的
- *    `list()`),不写进来 —— 写进来就等于承诺它们不变,而那不是我们打算承诺的。
- */
 export interface SpsToolSession {
     cwd: string;
     project?: string;
@@ -364,6 +351,53 @@ export interface MemoryGcStats {
 }
 /** 迁移了多少条 —— 键由后端自定(本地实现给 global/agents/projects)。 */
 export type MemoryMigrateStats = Record<string, number>;
+export interface SpsWorkspaceProject {
+    /** 相对工作区根,如 `t<租户>/<产品>/<项目>`。 */
+    rel: string;
+    /** 绝对路径。 */
+    abs: string;
+    /** 布局第二段 —— 资产声明按它取。 */
+    product: string;
+}
+export interface SpsAssetScope {
+    /** 相对项目根的路径前缀。 */
+    include: string[];
+    /**
+     * 有没有用兜底。
+     * ⚠️ **这一格必须能被报出来** —— "范围内什么都没有"和"根本没声明范围"
+     *    读数一样,处置完全不同。
+     */
+    usedDefault: boolean;
+}
+/**
+ * 工作区布局(**只读**)。给需要遍历用户产物的插件用(如同步到对象存储)。
+ *
+ * ⚠️ `discover()` 与 `sps.projects.list()` 是**两个不同的集合**:
+ *    前者按目录布局扫,后者读注册表。目录里有而没注册的项目只出现在前者。
+ */
+export interface SpsWorkspace {
+    /** 工作区根(绝对路径)。 */
+    root(): string;
+    /** 按布局约定发现项目。 */
+    discover(): Promise<SpsWorkspaceProject[]>;
+    /** 某产品的用户资产范围。没有声明时回落窄兜底,并把 `usedDefault` 置真。 */
+    assetScope(product: string): SpsAssetScope;
+}
+/**
+ * `p` 是否在 `root` 之内(含 root 自身)。
+ *
+ * 🔴 **必须比到分隔符**:裸 `startsWith(root)` 会把 `<root>-old` 当成 root 内。
+ */
+export declare function isUnderRoot(p: string, root: string): boolean;
+/**
+ * 把路径解析到**真实位置**(软链解开)。
+ * 目标可能尚不存在(输出文件),故解析其**父目录**的 realpath 再拼回文件名。
+ *
+ * ⚠️ **异步**:同步 fs 会阻塞事件循环(含健康探针与 SSE 心跳)。
+ */
+export declare function realResolve(p: string): Promise<string>;
+/** realpath 之后再判围栏。**这是唯一该被安全路径调用的那个**;字符串比较不算围栏。 */
+export declare function isRealUnderRoot(p: string, root: string): Promise<boolean>;
 /** 写入被脱敏规则丢弃时,后端抛出的错误应带这个 code。宿主据此与真错误区分。 */
 export declare const MEMORY_REDACTED_CODE = "memory-redacted";
 /** 去重归一化:小写、去 markdown 标点、压空白。**这是"什么算重复"的唯一判据**。 */
@@ -391,21 +425,18 @@ export interface SpsStorageObject {
     size: number;
 }
 /**
- * 对象存储(读 / 列 / 写)。桶是共享面 —— 多节点下 studio 和工作区不在同一台机器上。
+ * 对象存储(读 / 列 / 写)。**由插件提供** —— 没装桶插件时这个服务不存在,
+ * inject 它的插件会 PENDING。
  *
- * 🔴 **它只搬字节,不做账。** id / 索引 / 缩略图 / 分类 / 配额 / 计费都在平台侧。
- *
- * ⚠️ **权限按前缀分,而且很紧**(单写方规则)。
- *    读不了的前缀会**抛**,不会回空 —— "库是空的"和"我没权限"混成一个,
- *    人会去补素材而不是去补策略。
  * ⚠️ 桶没配时三个方法都抛 ⇒ **先用 `configured()` 问一句**,别拿异常当分支。
+ * 🔴 读不了的前缀会**抛**,不会回空 —— "库是空的"和"我没权限"混成一个,
+ *    人会去补素材而不是去补策略。
  */
 export interface SpsStorage {
     configured(): boolean;
     /** 不存在 ⇒ `null`;连不上/没权限 ⇒ **抛**。 */
     get(key: string): Promise<Buffer | null>;
     list(prefix: string): Promise<SpsStorageObject[]>;
-    /** ⚠️ `contentType` 自己决定 —— 桶是直连的,缺省会让预览变成一次下载。 */
     put(key: string, bytes: Buffer, contentType?: string): Promise<void>;
 }
 /** 与 `SpsAsyncPoll` 同形 —— async 能力的 `poll` 可以**直接透传**。 */
@@ -622,6 +653,16 @@ export interface SpsAttachments {
     }>;
 }
 /** 插件 `inject` 里写的名字。 */
+/**
+ * **由插件提供**的服务 —— 宿主装配后它们**不一定在**。
+ *
+ * 🔴 inject 它们的插件要接受"没装那个插件就 PENDING"这件事。
+ * ⚠️ 这张表是给门禁用的单一真源:宿主的 conformance 判据据此
+ *    豁免这些名字("契约里列的服务装配后都在"对它们不成立)。
+ *    2026-08-28 加,起因是把 `sps.storage` 从宿主挪进插件后,
+ *    那条判据把"实现搬家了"报成了"契约说谎"。
+ */
+export declare const PLUGIN_PROVIDED_SERVICES: readonly ["sps.storage", "sps.memory"];
 export declare const SPS_SERVICES: {
     readonly tools: "sps.tools";
     readonly credentials: "sps.credentials";
@@ -633,7 +674,6 @@ export declare const SPS_SERVICES: {
     readonly projects: "sps.projects";
     readonly cards: "sps.cards";
     readonly jobs: "sps.jobs";
-    readonly storage: "sps.storage";
     readonly subprocess: "sps.subprocess";
     readonly attachments: "sps.attachments";
     readonly media: "sps.media";
@@ -642,6 +682,8 @@ export declare const SPS_SERVICES: {
     readonly agents: "sps.agents";
     readonly repo: "sps.repo";
     readonly memory: "sps.memory";
+    readonly storage: "sps.storage";
+    readonly workspace: "sps.workspace";
     readonly notifier: "sps.notifier";
 };
 /** 插件 ctx 上能拿到的服务(只列已声明契约的那几个)。 */
@@ -656,13 +698,14 @@ export interface SpsPluginContext {
     'sps.projects': SpsProjects;
     'sps.cards': SpsCards;
     'sps.jobs': SpsJobs;
-    'sps.storage': SpsStorage;
     'sps.capabilities': SpsCapabilities;
     'sps.media': SpsMedia;
     'sps.im': SpsRegistryByKey;
     'sps.agents': SpsRegistryByFactory;
     'sps.repo': SpsRegistryByFactory;
     'sps.memory': SpsMemory;
+    'sps.storage': SpsStorage;
+    'sps.workspace': SpsWorkspace;
     'sps.notifier': SpsNotifier;
     'sps.subprocess': SpsSubprocess;
     'sps.attachments': SpsAttachments;

package/dist/index.js

@@ -11,6 +11,55 @@
  * ⚠️ 这里只声明**插件会调的那一面**。服务内部还有别的方法(比如注册表的
  *    `list()`),不写进来 —— 写进来就等于承诺它们不变,而那不是我们打算承诺的。
  */
+import { realpath } from 'node:fs/promises';
+import { dirname, join, resolve as nodeResolve, sep } from 'node:path';
+// ── 路径围栏:所有插件共用的安全下限 ──────────────────────────────────────
+//
+// 🔴 **安全判据不能有第二份。** 本仓已经为这个形状付过三次代价:
+//    `providers/art/withinDir.ts`(字符串,理智检查)与 `console/lib/artPaths.ts`
+//    (realpath,安全边界)长得几乎一样、靠头注区分;`scan.ts` 用 Dirent 做对了、
+//    隔壁用 `stat`(跟随软链)就漏了。
+//    > **一条安全规则做对过一次,不代表它在第二条路上也在** ——
+//    > 而两条路写法不同时,正是它只做一半的时候。
+//    ⇒ 插件要围栏时**从这里取**,别自己写第四份。
+//
+// ⚠️ 本节**只做围栏**,不回答"这个文件该不该同步/发布/服务" ——
+//    那三者判据不同、各自命名。合并会制造"它们本该一致"的错觉,
+//    而那个错觉比漂移本身更危险:下一个人会去"修复不一致",把三条用途不同的规则强行统一。
+/**
+ * `p` 是否在 `root` 之内(含 root 自身)。
+ *
+ * 🔴 **必须比到分隔符**:裸 `startsWith(root)` 会把 `<root>-old` 当成 root 内。
+ */
+export function isUnderRoot(p, root) {
+    const r = nodeResolve(root);
+    const t = nodeResolve(p);
+    return t === r || t.startsWith(r + sep);
+}
+/**
+ * 把路径解析到**真实位置**(软链解开)。
+ * 目标可能尚不存在(输出文件),故解析其**父目录**的 realpath 再拼回文件名。
+ *
+ * ⚠️ **异步**:同步 fs 会阻塞事件循环(含健康探针与 SSE 心跳)。
+ */
+export async function realResolve(p) {
+    const abs = nodeResolve(p);
+    try {
+        return await realpath(abs);
+    }
+    catch {
+        try {
+            return join(await realpath(dirname(abs)), abs.slice(dirname(abs).length + 1));
+        }
+        catch {
+            return abs;
+        }
+    }
+}
+/** realpath 之后再判围栏。**这是唯一该被安全路径调用的那个**;字符串比较不算围栏。 */
+export async function isRealUnderRoot(p, root) {
+    return isUnderRoot(await realResolve(p), await realResolve(root));
+}
 // ── 后端可以往 worker 注入一个 Claude Code 插件 ─────────────────────────────
 //
 // 记忆的读路有两半:**pull**(agent 自己调 `memory_recall`)与 **push**(会话自动召回)。
@@ -68,6 +117,16 @@ export function buildMemoryDigest(entries, opts = {}) {
 }
 // ── 服务名 ───────────────────────────────────────────────────────────────
 /** 插件 `inject` 里写的名字。 */
+/**
+ * **由插件提供**的服务 —— 宿主装配后它们**不一定在**。
+ *
+ * 🔴 inject 它们的插件要接受"没装那个插件就 PENDING"这件事。
+ * ⚠️ 这张表是给门禁用的单一真源:宿主的 conformance 判据据此
+ *    豁免这些名字("契约里列的服务装配后都在"对它们不成立)。
+ *    2026-08-28 加,起因是把 `sps.storage` 从宿主挪进插件后,
+ *    那条判据把"实现搬家了"报成了"契约说谎"。
+ */
+export const PLUGIN_PROVIDED_SERVICES = ['sps.storage', 'sps.memory'];
 export const SPS_SERVICES = {
     tools: 'sps.tools',
     credentials: 'sps.credentials',
@@ -79,7 +138,6 @@ export const SPS_SERVICES = {
     projects: 'sps.projects',
     cards: 'sps.cards',
     jobs: 'sps.jobs',
-    storage: 'sps.storage',
     subprocess: 'sps.subprocess',
     attachments: 'sps.attachments',
     media: 'sps.media',
@@ -88,5 +146,7 @@ export const SPS_SERVICES = {
     agents: 'sps.agents',
     repo: 'sps.repo',
     memory: 'sps.memory',
+    storage: 'sps.storage',
+    workspace: 'sps.workspace',
     notifier: 'sps.notifier',
 };

package/package.json

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