@coralai/sps-plugin-api 0.11.0 → 0.13.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;
@@ -343,6 +330,16 @@ export interface SpsMemory {
         project?: string;
         all?: boolean;
     }): MemoryMigrateStats;
+    /**
+     * 要注入 worker 的 Claude Code 插件目录(**绝对路径**)。没有就返回 `[]`。
+     *
+     * 用于把"自动召回"做进会话:hooks 在 worker 的 claude 进程里跑,
+     * 不依赖 agent 主动调工具。
+     *
+     * ⚠️ 只有 claude 后端会用到 —— 别的 agent(openai/codex)没有对应概念,
+     *    它们要等价能力时各自在自己的适配器里解决。
+     */
+    workerPlugins(): string[];
 }
 export interface MemoryGcStats {
     /** 硬删的 tombstone 数。 */
@@ -354,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 标点、压空白。**这是"什么算重复"的唯一判据**。 */
@@ -374,30 +418,6 @@ export interface SpsNotifier {
         send(message: string, level?: 'info' | 'success' | 'warning' | 'error'): Promise<void>;
     };
 }
-export interface SpsStorageObject {
-    key: string;
-    /** **内容判据**(单段上传时等于 md5)。不看时间。 */
-    etag: string;
-    size: number;
-}
-/**
- * 对象存储(读 / 列 / 写)。桶是共享面 —— 多节点下 studio 和工作区不在同一台机器上。
- *
- * 🔴 **它只搬字节,不做账。** 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` 可以**直接透传**。 */
 export type SpsJobStatus = SpsAsyncPoll;
 /**
@@ -623,7 +643,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";
@@ -632,6 +651,7 @@ export declare const SPS_SERVICES: {
     readonly agents: "sps.agents";
     readonly repo: "sps.repo";
     readonly memory: "sps.memory";
+    readonly workspace: "sps.workspace";
     readonly notifier: "sps.notifier";
 };
 /** 插件 ctx 上能拿到的服务(只列已声明契约的那几个)。 */
@@ -646,13 +666,13 @@ 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.workspace': SpsWorkspace;
     'sps.notifier': SpsNotifier;
     'sps.subprocess': SpsSubprocess;
     'sps.attachments': SpsAttachments;

package/dist/index.js

@@ -11,6 +11,66 @@
  * ⚠️ 这里只声明**插件会调的那一面**。服务内部还有别的方法(比如注册表的
  *    `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**(会话自动召回)。
+// 只有 pull 时,工具挂着而 agent 不调 = 等于没记忆 —— 这是实测过的失效模式。
+// push 那一半靠 Claude Code 的 hooks,而 hooks 装在一个 claude 插件目录里。
+//
+// 🔴 宿主**只要一个目录路径**,不解析里面的 hooks.json / .mcp.json ——
+//    那是运行时 substrate 的格式,和"sps 不解析 claude 的 transcript"同源。
+// ⚠️ 目录由 SDK 的 `plugins: [{type:'local', path}]` 加载,**不需要装进
+//    `~/.claude/plugins`**(2026-08-27 实测:任意路径可加载,MCP server 正常注册)。
+//    这也意味着关掉 = 不传参数,零残留。
 // ── 跨后端必须一致的算法 ──────────────────────────────────────────────────
 //
 // 🔴 放这里的判据只有一条:**两个后端对它给出不同答案会出错**。
@@ -68,7 +128,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',
@@ -77,5 +136,6 @@ export const SPS_SERVICES = {
     agents: 'sps.agents',
     repo: 'sps.repo',
     memory: 'sps.memory',
+    workspace: 'sps.workspace',
     notifier: 'sps.notifier',
 };

package/package.json

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