@coralai/sps-plugin-storage-sync 0.1.0

package/dist/FakeStorage.d.ts

@@ -0,0 +1,15 @@
+import { type StorageBackend, type StorageObject } from './StorageBackend.js';
+export declare class FakeStorage implements StorageBackend {
+    readonly objects: Map<string, {
+        bytes: Buffer;
+        contentType?: string;
+        etag: string;
+    }>;
+    putCalls: string[];
+    /** 下一次 put 到这个 key 时抛错(模拟上传失败)。 */
+    failNext: string | null;
+    put(key: string, bytes: Buffer, contentType?: string): Promise<void>;
+    list(prefix: string): Promise<StorageObject[]>;
+    /** 没有这个 key ⇒ `null`(与真后端同语义:不抛)。 */
+    get(key: string): Promise<Buffer | null>;
+}

package/dist/FakeStorage.js

@@ -0,0 +1,36 @@
+/**
+ * @module        providers/storage/FakeStorage
+ * @description   `StorageBackend` 的内存假实现。**它的存在本身就是"接口中性"的证据** ——
+ *                一个不认识 minio 的实现能满足整个接口,说明上层没有漏抽象。
+ *
+ * @layer         providers
+ *
+ * ⚠️ 放在 `.test.ts` 之外是因为 lint 禁止从测试文件导出(`noExportsInTest`),
+ *    而它被两个用例文件共用。**共用的测试替身要有自己的落点**,复制两份才是问题。
+ */
+import { createHash } from 'node:crypto';
+import { StorageUnavailableError } from './StorageBackend.js';
+export class FakeStorage {
+    objects = new Map();
+    putCalls = [];
+    /** 下一次 put 到这个 key 时抛错(模拟上传失败)。 */
+    failNext = null;
+    async put(key, bytes, contentType) {
+        if (this.failNext === key) {
+            this.failNext = null;
+            throw new StorageUnavailableError(`假的上传失败:${key}`);
+        }
+        this.putCalls.push(key);
+        // etag 用 md5:与单段上传的真实语义一致,否则用例会掩盖"分块上传 etag 不是 md5"那个坑
+        this.objects.set(key, { bytes, contentType, etag: createHash('md5').update(bytes).digest('hex') });
+    }
+    async list(prefix) {
+        return [...this.objects.entries()]
+            .filter(([k]) => k.startsWith(prefix))
+            .map(([key, v]) => ({ key, etag: v.etag, size: v.bytes.length }));
+    }
+    /** 没有这个 key ⇒ `null`(与真后端同语义:不抛)。 */
+    async get(key) {
+        return this.objects.get(key)?.bytes ?? null;
+    }
+}

package/dist/MinioBackend.d.ts

@@ -0,0 +1,40 @@
+/**
+ * @module        providers/storage/MinioBackend
+ * @description   `StorageBackend` 的第一个实现:S3 兼容(MinIO)。
+ *
+ * @layer         providers
+ *
+ * 🔴 **依赖走 `optionalDependencies` + 动态 import。**
+ *    `@coralai/sps-cli` 是公共 npm 包,别人装它不需要对象存储。
+ *    没装 ⇒ 抛 `StorageUnavailableError` 并**指名说"未安装"**,
+ *    **绝不静默降级**成"这轮没东西同步" —— 那会让"功能没装"伪装成"没有变化"。
+ *
+ * ⚠️ 这里是**唯一**允许出现 minio 类型的文件。上层只认 `StorageBackend`。
+ *    自检:换掉本文件,上层用例应当全绿(`storageBackend.test.ts` 就是拿假实现证明这一点的)。
+ */
+import type { StorageBackend, StorageObject } from './StorageBackend.js';
+import type { StorageConfig } from './config.js';
+/**
+ * `etag` 从 MinIO 回来时**带引号**(`"d41d8…"`),而本地算的 md5 不带。
+ * 不剥掉的话每一轮对账都判"变了" ⇒ **每轮重传全部文件**,而且完全不报错 ——
+ * 表现是"同步一直在工作",只是流量和耗时莫名其妙。
+ */
+export declare function normalizeEtag(raw: unknown): string;
+export declare class MinioBackend implements StorageBackend {
+    private readonly cfg;
+    private client;
+    constructor(cfg: StorageConfig);
+    private ensure;
+    put(key: string, bytes: Buffer, contentType?: string): Promise<void>;
+    list(prefix: string): Promise<StorageObject[]>;
+    /**
+     * 读一个对象。
+     *
+     * 🔴 **"没有这个 key" 与 "读不了" 必须分开**:
+     *    前者返回 `null`(调用方据此走兜底),后者抛 `StorageUnavailableError`。
+     *    混成一个的表现是"库是空的" —— 而真相可能是**权限不够**,
+     *    那会让人去补素材而不是去补策略。
+     *    MinIO 的 NoSuchKey 走 code,不看消息文本(消息会随版本变)。
+     */
+    get(key: string): Promise<Buffer | null>;
+}

package/dist/MinioBackend.js

@@ -0,0 +1,84 @@
+import { StorageUnavailableError } from './StorageBackend.js';
+/**
+ * `etag` 从 MinIO 回来时**带引号**(`"d41d8…"`),而本地算的 md5 不带。
+ * 不剥掉的话每一轮对账都判"变了" ⇒ **每轮重传全部文件**,而且完全不报错 ——
+ * 表现是"同步一直在工作",只是流量和耗时莫名其妙。
+ */
+export function normalizeEtag(raw) {
+    return String(raw ?? '').replace(/^"|"$/g, '');
+}
+export class MinioBackend {
+    cfg;
+    client = null;
+    constructor(cfg) {
+        this.cfg = cfg;
+    }
+    async ensure() {
+        if (this.client)
+            return this.client;
+        let mod;
+        try {
+            mod = (await import('minio'));
+        }
+        catch (cause) {
+            throw new StorageUnavailableError("对象存储后端未安装:缺可选依赖 'minio'。安装它(npm i minio)或关掉 ~/.coral/storage.json 的 enabled。", cause);
+        }
+        const u = new URL(this.cfg.endpoint);
+        this.client = new mod.Client({
+            endPoint: u.hostname,
+            port: u.port ? Number(u.port) : u.protocol === 'https:' ? 443 : 80,
+            useSSL: u.protocol === 'https:',
+            accessKey: this.cfg.accessKey,
+            secretKey: this.cfg.secretKey,
+            region: this.cfg.region ?? 'us-east-1',
+            pathStyle: this.cfg.pathStyle ?? true,
+        });
+        return this.client;
+    }
+    async put(key, bytes, contentType) {
+        const c = await this.ensure();
+        // 显式给 size:不给的话客户端会走分块流式上传,而**分块上传的 etag 不是 md5**
+        // ⇒ 对账判据(etag == 本地 md5)当场失效,且失效方式是"永远判为不同"。
+        await c.putObject(this.cfg.bucket, key, bytes, bytes.length, contentType ? { 'Content-Type': contentType } : undefined);
+    }
+    async list(prefix) {
+        const c = await this.ensure();
+        const stream = c.listObjectsV2(this.cfg.bucket, prefix, true);
+        return await new Promise((resolve, reject) => {
+            const out = [];
+            stream.on('data', (o) => {
+                // 目录占位项没有 name/etag(MinIO 会回"前缀"条目);跳过它们,别当成对象。
+                if (!o.name)
+                    return;
+                out.push({ key: o.name, etag: normalizeEtag(o.etag), size: o.size ?? 0 });
+            });
+            stream.on('end', () => resolve(out));
+            stream.on('error', (e) => reject(new StorageUnavailableError(`列举失败:${prefix}`, e)));
+        });
+    }
+    /**
+     * 读一个对象。
+     *
+     * 🔴 **"没有这个 key" 与 "读不了" 必须分开**:
+     *    前者返回 `null`(调用方据此走兜底),后者抛 `StorageUnavailableError`。
+     *    混成一个的表现是"库是空的" —— 而真相可能是**权限不够**,
+     *    那会让人去补素材而不是去补策略。
+     *    MinIO 的 NoSuchKey 走 code,不看消息文本(消息会随版本变)。
+     */
+    async get(key) {
+        const c = await this.ensure();
+        try {
+            const stream = await c.getObject(this.cfg.bucket, key);
+            const chunks = [];
+            for await (const ch of stream)
+                chunks.push(ch);
+            return Buffer.concat(chunks);
+        }
+        catch (e) {
+            const code = e.code;
+            if (code === 'NoSuchKey' || code === 'NotFound')
+                return null;
+            throw new StorageUnavailableError(`读取失败:${key}`, e);
+        }
+    }
+}

package/dist/StorageBackend.d.ts

@@ -0,0 +1,51 @@
+/**
+ * @module        providers/storage/StorageBackend
+ * @description   对象存储的**中性接口**。换一个后端(MinIO / S3 / WebDAV / 别的 HTTP 端点),
+ *                上层几乎不用改 —— 与 `AgentBackend` / `RepoBackend` / `MediaProvider` 同一条自检判据。
+ *
+ * @layer         providers
+ *
+ * 🔴 **接口里不出现任何一家存储的类型或词汇。** 这是"独立性"的全部来源:
+ *    独立性来自**接口中性**,不来自代码住在哪个包里。
+ *    (§2.1:插件 ≠ 解耦。解耦是接口的性质,插件是分发的性质。)
+ *
+ * 🔴 **只有 put 与 list 两个动作,而且没有 delete。**
+ *    · 没有 delete 是**有意的**:同步这条路的不变量是「**不删**」——
+ *      本地文件没了不等于用户要删桶里那份(工作区可能被重建、节点可能换了)。
+ *      接口上不给这个动作,比在实现里"记得别调"可靠。
+ *      (同族:授权中心也**不该有 DeleteObject**,理由是 artifacts 未版本化 ⇒ 误删不可恢复。)
+ *    · 没有 `stat` 是因为对账用 `list` 一次拿全前缀更省往返,而且**对账基准必须是桶本身**;
+ *      逐个 stat 会诱使实现方去缓存"上次看到的",那正是要避免的形态。
+ */
+/** 桶里一个对象的对账信息。**etag 是内容判据**(单段上传时等于 md5),不看时间。 */
+export interface StorageObject {
+    key: string;
+    etag: string;
+    size: number;
+}
+export interface StorageBackend {
+    /**
+     * 写一个对象(覆盖同 key)。
+     *
+     * 🔴 `contentType` 不是可选的装饰:桶是**直连**的,没有一层服务器可以在返回时补救 ——
+     * 缺省的 `application/octet-stream` 会让预览图在浏览器里变成一次下载。
+     * 所以推的时候就得写对;拿不准时**由调用方决定**,后端不猜。
+     */
+    put(key: string, bytes: Buffer, contentType?: string): Promise<void>;
+    /** 列一个前缀下的全部对象(递归)。前缀为空即整桶 —— 调用方自己收窄。 */
+    list(prefix: string): Promise<StorageObject[]>;
+    /**
+     * 读一个对象。
+     *
+     * 🔴 **不存在返回 `null`,不抛** —— "有没有"是正常的问题
+     *    (占位兜底就是先问"库里有没有")。而**连不上/没权限要抛**
+     *    `StorageUnavailableError`:那两件事和"这个 key 没有"完全不同,
+     *    混在一起的表现是"库是空的",而真相是这个 key 读不了。
+     */
+    get(key: string): Promise<Buffer | null>;
+}
+/** 后端不可用时抛这个,**不要静默降级**成"这轮没东西同步"。 */
+export declare class StorageUnavailableError extends Error {
+    readonly cause?: unknown | undefined;
+    constructor(message: string, cause?: unknown | undefined);
+}

package/dist/StorageBackend.js

@@ -0,0 +1,28 @@
+/**
+ * @module        providers/storage/StorageBackend
+ * @description   对象存储的**中性接口**。换一个后端(MinIO / S3 / WebDAV / 别的 HTTP 端点),
+ *                上层几乎不用改 —— 与 `AgentBackend` / `RepoBackend` / `MediaProvider` 同一条自检判据。
+ *
+ * @layer         providers
+ *
+ * 🔴 **接口里不出现任何一家存储的类型或词汇。** 这是"独立性"的全部来源:
+ *    独立性来自**接口中性**,不来自代码住在哪个包里。
+ *    (§2.1:插件 ≠ 解耦。解耦是接口的性质,插件是分发的性质。)
+ *
+ * 🔴 **只有 put 与 list 两个动作,而且没有 delete。**
+ *    · 没有 delete 是**有意的**:同步这条路的不变量是「**不删**」——
+ *      本地文件没了不等于用户要删桶里那份(工作区可能被重建、节点可能换了)。
+ *      接口上不给这个动作,比在实现里"记得别调"可靠。
+ *      (同族:授权中心也**不该有 DeleteObject**,理由是 artifacts 未版本化 ⇒ 误删不可恢复。)
+ *    · 没有 `stat` 是因为对账用 `list` 一次拿全前缀更省往返,而且**对账基准必须是桶本身**;
+ *      逐个 stat 会诱使实现方去缓存"上次看到的",那正是要避免的形态。
+ */
+/** 后端不可用时抛这个,**不要静默降级**成"这轮没东西同步"。 */
+export class StorageUnavailableError extends Error {
+    cause;
+    constructor(message, cause) {
+        super(message);
+        this.cause = cause;
+        this.name = 'StorageUnavailableError';
+    }
+}

package/dist/config.d.ts

@@ -0,0 +1,36 @@
+/**
+ * @module        config
+ * @description   本插件的配置**形状**。值来自装配档那一行的 `config:`,
+ *                由宿主的插件页渲染表单、写进 `~/.coral/assembly/base.yml`(0600)。
+ *
+ * 🔴 **不读任何配置文件。** 拆插件前这些值分散在 `~/.coral/storage.json`
+ *    与 `~/.coral/sync-scope.json` 两处;现在合并成一份装配档 config ——
+ *    好处不是"少一个文件",是**卸载插件时配置跟着一起没**
+ *    (`plugin remove` 删整行),而独立文件会留下孤儿密钥。
+ */
+export interface StorageConfig {
+    /** S3 兼容端点,如 `http://127.0.0.1:9000`。 */
+    endpoint: string;
+    /** 桶名。sps 只认这一个名字,不认识桶里的语义分区。 */
+    bucket: string;
+    accessKey: string;
+    secretKey: string;
+    /** S3 region;MinIO 通常用 `us-east-1`,给默认值只是为了签名能算出来。 */
+    region?: string;
+    /**
+     * 路径式寻址(`http://host/bucket/key`)。MinIO 默认需要它;
+     * 虚拟主机式(`http://bucket.host/key`)要求 DNS 配合,自建部署一般没有。
+     */
+    pathStyle?: boolean;
+    /** 🔴 默认关:缺这个字段或为 false ⇒ 同步路径完全不存在。 */
+    enabled: boolean;
+}
+/** 插件在装配档里的完整配置。 */
+export interface StorageSyncConfig extends StorageConfig {
+    /** 扫描间隔(秒),默认 600。 */
+    intervalSec?: number;
+    /** 只看近 N 天有改动的项目;0 = 全量。默认 7 —— 全量扫一遍很贵,老项目通常已同步过。 */
+    sinceDays?: number;
+    /** 单文件大小上限(字节)。超过的跳过并计数。 */
+    maxBytes?: number;
+}

package/dist/config.js

@@ -0,0 +1,11 @@
+/**
+ * @module        config
+ * @description   本插件的配置**形状**。值来自装配档那一行的 `config:`,
+ *                由宿主的插件页渲染表单、写进 `~/.coral/assembly/base.yml`(0600)。
+ *
+ * 🔴 **不读任何配置文件。** 拆插件前这些值分散在 `~/.coral/storage.json`
+ *    与 `~/.coral/sync-scope.json` 两处;现在合并成一份装配档 config ——
+ *    好处不是"少一个文件",是**卸载插件时配置跟着一起没**
+ *    (`plugin remove` 删整行),而独立文件会留下孤儿密钥。
+ */
+export {};

package/dist/index.d.ts

@@ -0,0 +1,36 @@
+/**
+ * @module        @coralai/sps-plugin-storage-sync
+ * @description   工作区 → 对象存储同步 —— 把节点本地盘上的用户产物搬到共享面。
+ *
+ * ## 为什么是插件,不是 sps 的本体能力
+ *
+ * 🔴 **桶是平台的需求,不是 sps 的。** sps 自己跑不需要桶 —— 拆分前
+ *    `sps.storage` seam 的生产消费方是 **0**,那就是证据。
+ *    多节点下"studio 读不到工作区"是 studio 的问题;sps 承接它,就是
+ *    **多了一个不该有的承诺**。
+ *
+ * ⚠️ 但同步必须跑在**有工作区的那台机器上**(物理约束)——
+ *    这正是插件的价值:代码归属可以是平台的,进程跑在 sps 里。
+ *
+ * ## 配置
+ *
+ * 全部来自装配档那一行的 `config:`(`~/.coral/assembly/base.yml`,0600)。
+ * 拆分前它分散在 `~/.coral/storage.json` 与 `~/.coral/sync-scope.json` 两处;
+ * 合并的好处不是"少一个文件",是**卸载时配置跟着一起没** —— 独立文件会留下孤儿密钥。
+ */
+import type { StorageSyncConfig } from './config.js';
+export { Config } from './schema.js';
+export declare const name = "storage-sync";
+export declare const category = "\u5B58\u50A8";
+export declare const description = "\u5DE5\u4F5C\u533A \u2192 \u5BF9\u8C61\u5B58\u50A8\u540C\u6B65:\u6309\u4EA7\u54C1\u58F0\u660E\u7684\u8303\u56F4,\u628A\u7528\u6237\u4EA7\u7269\u589E\u91CF\u642C\u5230 S3 \u517C\u5BB9\u6876\u3002";
+interface ApplyCtx {
+    effect(fn: () => void): void;
+    logger?: {
+        info(msg: string): void;
+        warn(msg: string): void;
+    };
+    reflect: {
+        get(name: string): unknown;
+    };
+}
+export declare function apply(ctx: ApplyCtx, config: StorageSyncConfig): void;

package/dist/index.js

@@ -0,0 +1,69 @@
+import { runSyncPass } from './syncRunner.js';
+export { Config } from './schema.js';
+export const name = 'storage-sync';
+export const category = '存储';
+export const description = '工作区 → 对象存储同步:按产品声明的范围,把用户产物增量搬到 S3 兼容桶。';
+/** 默认 10 分钟一轮。 */
+const DEFAULT_INTERVAL_MS = 10 * 60 * 1000;
+/** 默认只看近 7 天有改动的项目 —— 全量扫一遍很贵,而老项目通常已经同步过。 */
+const DEFAULT_SINCE_DAYS = 7;
+const DEFAULT_MAX_BYTES = 2 * 1024 * 1024;
+/**
+ * 🔴 **惰性取,别在 apply 里取一次存起来。** 声明了 `inject` 的话服务缺席会让整条链
+ *    PENDING;不声明就得容忍"apply 时它可能还没到"——Cordis 不保证无依赖插件的装载顺序。
+ *    ⇒ 在真正要用的那一刻取。(2026-08-27 在记忆插件那轮实测踩过。)
+ */
+const workspaceOf = (ctx) => ctx.reflect.get('sps.workspace') ?? null;
+export function apply(ctx, config) {
+    const log = (l) => ctx.logger?.info(l) ?? console.log(l);
+    if (!config?.endpoint || !config?.bucket) {
+        log('[sps-sync] 未配置桶(endpoint/bucket),同步不启动。');
+        return;
+    }
+    if (config.enabled === false) {
+        log('[sps-sync] 配置里关着,同步不启动。');
+        return;
+    }
+    const intervalMs = config.intervalSec ? config.intervalSec * 1000 : DEFAULT_INTERVAL_MS;
+    const sinceDays = config.sinceDays ?? DEFAULT_SINCE_DAYS;
+    const maxBytes = config.maxBytes ?? DEFAULT_MAX_BYTES;
+    let timer = null;
+    let stopped = false;
+    /**
+     * 🔴 **一轮没跑完不开下一轮** —— 用 `setTimeout` 自排,不用 `setInterval`。
+     *    `setInterval` 在一轮变慢时会叠罗汉:两轮并发对同一个前缀列举 + 上传。
+     *    (这条语义照搬自拆分前的 `daemon/storageSyncLoop`,别改回 setInterval。)
+     */
+    const schedule = () => {
+        if (stopped)
+            return;
+        timer = setTimeout(() => {
+            void tick().finally(schedule);
+        }, intervalMs);
+    };
+    const tick = async () => {
+        try {
+            const workspace = workspaceOf(ctx);
+            if (!workspace) {
+                // 宿主没提供工作区 seam ⇒ 这台部署上没有可同步的东西,静默跳过。
+                return;
+            }
+            const sum = await runSyncPass({ root: workspace.root(), workspace, config, sinceDays, maxBytes, log });
+            if (sum && sum.uploaded > 0) {
+                log(`[sps-sync] 上传 ${sum.uploaded} · 跳过 ${sum.skipped} · 失败 ${sum.failed}`);
+            }
+        }
+        catch (err) {
+            // ⚠️ 同步失败**绝不能掀翻宿主** —— 它是扩展功能,不是主路径。
+            ctx.logger?.warn?.(`[sps-sync] 一轮失败(忽略): ${err instanceof Error ? err.message : String(err)}`);
+        }
+    };
+    log(`[sps-sync] 常驻:间隔=${intervalMs}ms 范围=近 ${sinceDays || '∞'} 天`);
+    void tick().finally(schedule);
+    // 插件卸载/重挂时停掉循环 —— 否则改一次配置就多一个循环在跑。
+    ctx.effect(() => {
+        stopped = true;
+        if (timer)
+            clearTimeout(timer);
+    });
+}

package/dist/keys.d.ts

@@ -0,0 +1,32 @@
+/**
+ * @module        providers/storage/keys
+ * @description   桶 key 的拼法。**与 coral `src/storage/keys.ts` 逐字对齐** —— 这是移交的对账面。
+ *
+ * @layer         providers
+ *
+ * 🔴 **为什么要一个模块而不是各处拼字符串**(照抄 coral 头注里的理由,它是对的):
+ *    桶里**没有"路径不存在"这种错误**。写方把 key 拼错一个字符,PUT 照样 200,
+ *    只是那个对象从此没人读得到;读方拼错,拿到 404 却无法区分"没同步上来"和"key 写法不一致"。
+ *    文件系统会用 ENOENT 立刻告诉你,桶不会。
+ *
+ * 🔴 **移交期间这是两份实现。** 两份实现的安全做法不是"小心点",是**拿真桶内容对账**:
+ *    切换前跑一轮并行比对,逐 key 逐 etag 一致才算数(实施计划任务 5 的验收物)。
+ *    > 判据:一条安全/正确性规则**做对过一次,不代表它在第二条路上也在**。
+ *
+ * ⚠️ 这里只有**同步**这条路用得到的三个(assetKey / assetPrefix / thumbKey)。
+ *    `published/` 与 `library/` 是别的路的写方,**不在本模块** —— 免得看起来像"sps 管着整个桶布局"。
+ */
+/** `./x` → `x`;去掉前导 `/`;`..` 一律抛(围栏在 `syncable`,这里是最后一道形状校验)。 */
+export declare function normalizeRel(rel: string): string;
+/** 项目在共享树下的相对路径(`t<租户>/<产品>/<项目>`),去掉尾部斜杠。 */
+export declare function normalizeProject(projectPath: string): string;
+export declare function assetKey(projectPath: string, rel: string): string;
+/** 某项目全部资源的前缀(对账列举用)。 */
+export declare function assetPrefix(projectPath: string): string;
+/**
+ * 缩略图:与原图同一棵树下的 `.thumbs/`,**后缀直接追加而不是替换**。
+ *
+ * 追加(`hero.png.webp`)而不是替换(`hero.webp`)是有意的:替换会让
+ * `hero.png` 与 `hero.jpg` 撞成同一个缩略图 key,而撞了不报错 —— 后写的赢,预览图随机。
+ */
+export declare function thumbKey(projectPath: string, rel: string): string;

package/dist/keys.js

@@ -0,0 +1,51 @@
+/**
+ * @module        providers/storage/keys
+ * @description   桶 key 的拼法。**与 coral `src/storage/keys.ts` 逐字对齐** —— 这是移交的对账面。
+ *
+ * @layer         providers
+ *
+ * 🔴 **为什么要一个模块而不是各处拼字符串**(照抄 coral 头注里的理由,它是对的):
+ *    桶里**没有"路径不存在"这种错误**。写方把 key 拼错一个字符,PUT 照样 200,
+ *    只是那个对象从此没人读得到;读方拼错,拿到 404 却无法区分"没同步上来"和"key 写法不一致"。
+ *    文件系统会用 ENOENT 立刻告诉你,桶不会。
+ *
+ * 🔴 **移交期间这是两份实现。** 两份实现的安全做法不是"小心点",是**拿真桶内容对账**:
+ *    切换前跑一轮并行比对,逐 key 逐 etag 一致才算数(实施计划任务 5 的验收物)。
+ *    > 判据:一条安全/正确性规则**做对过一次,不代表它在第二条路上也在**。
+ *
+ * ⚠️ 这里只有**同步**这条路用得到的三个(assetKey / assetPrefix / thumbKey)。
+ *    `published/` 与 `library/` 是别的路的写方,**不在本模块** —— 免得看起来像"sps 管着整个桶布局"。
+ */
+/** `./x` → `x`;去掉前导 `/`;`..` 一律抛(围栏在 `syncable`,这里是最后一道形状校验)。 */
+export function normalizeRel(rel) {
+    const clean = rel.replace(/^\.\//, '').replace(/^\/+/, '');
+    if (!clean)
+        throw new Error('相对路径为空');
+    if (clean.split('/').includes('..'))
+        throw new Error(`相对路径含 ..:${rel}`);
+    return clean;
+}
+/** 项目在共享树下的相对路径(`t<租户>/<产品>/<项目>`),去掉尾部斜杠。 */
+export function normalizeProject(projectPath) {
+    return normalizeRel(projectPath).replace(/\/+$/, '');
+}
+export function assetKey(projectPath, rel) {
+    return `assets/${normalizeProject(projectPath)}/${normalizeRel(rel)}`;
+}
+/** 某项目全部资源的前缀(对账列举用)。 */
+export function assetPrefix(projectPath) {
+    return `assets/${normalizeProject(projectPath)}/`;
+}
+/**
+ * 缩略图:与原图同一棵树下的 `.thumbs/`,**后缀直接追加而不是替换**。
+ *
+ * 追加(`hero.png.webp`)而不是替换(`hero.webp`)是有意的:替换会让
+ * `hero.png` 与 `hero.jpg` 撞成同一个缩略图 key,而撞了不报错 —— 后写的赢,预览图随机。
+ */
+export function thumbKey(projectPath, rel) {
+    const clean = normalizeRel(rel);
+    const i = clean.lastIndexOf('/');
+    const dir = i < 0 ? '' : `${clean.slice(0, i)}/`;
+    const base = i < 0 ? clean : clean.slice(i + 1);
+    return `assets/${normalizeProject(projectPath)}/.thumbs/${dir}${base}.webp`;
+}

package/dist/scanWorkspace.d.ts

@@ -0,0 +1,55 @@
+export interface ProjectDir {
+    /** 相对共享根:`t<租户>/<产品>/<项目>`。**这就是 key 里的 projectPath。** */
+    rel: string;
+    abs: string;
+    /** 布局第二段。声明按它取。 */
+    product: string;
+}
+export interface ScannedFile {
+    /** 相对项目根。 */
+    rel: string;
+    abs: string;
+    size: number;
+    /** 内容判据。与桶的 etag 比 —— **不看 mtime**。 */
+    md5: string;
+}
+export interface ScanResult {
+    files: ScannedFile[];
+    /**
+     * 声明里有、但盘上不存在的路径。
+     * 🔴 **与 `unreadable` 分开**:第一轮上线时 61 个 coralplatform 项目被报成"权限读不到",
+     * 实际是**目录不存在**(`ENOENT`)—— 而 `unreadable` 的语义是"基线 0,非 0 即告警",
+     * 于是它每一轮都会假报一次。**别让一个字段同时表示两件事**(今天第三次踩)。
+     */
+    missing: string[];
+    /**
+     * 枚举时跳过的点开头条目(`.sprites.pre-orient.png` 这类中间产物)。
+     * 🔴 它们**不该走安全下限的"整趟拒绝"**:那条是给"声明里点名了不该给的东西"用的。
+     * 中间产物触发整趟拒绝 ⇒ 一个项目会**永久停止同步**,而且理由看起来像安全事件。
+     */
+    skippedDot: string[];
+    /**
+     * 因权限读不到而跳过的相对路径。
+     * 🔴 **基线是 0 ⇒ 非 0 即变化**,是告警不是趋势:它既可能是"防线在生效"(0600 凭据读不到),
+     * 也可能是"误伤了用户数据"。两种含义都不该无声发生。
+     */
+    unreadable: string[];
+}
+/** 发现共享根下的全部项目(三段布局)。不做任何内容判断。 */
+export declare function discoverProjects(root: string): Promise<ProjectDir[]>;
+/**
+ * 声明范围内最近一次改动的时间。
+ *
+ * @returns 毫秒时间戳;**`null` = 范围内一个路径都不存在**(与"存在但很旧"是两件事)
+ */
+export declare function scopeLastModified(projectAbs: string, include: string[]): Promise<number | null>;
+/**
+ * 按声明枚举文件并算 md5。
+ *
+ * ⚠️ `maxBytes`:整份读进内存算 md5(与 coral 同做法 —— 上传时本来也要这份字节)。
+ * 上限**显式**给,不靠运气:树里有 172MB 的项目,一个失控的大文件不该把进程带走。
+ * 超限的算**失败**(计入 errors),不是静默跳过 —— 静默跳过会让"这个资源永远不在桶里"没人知道。
+ */
+export declare function scanByScope(projectAbs: string, include: string[], maxBytes: number): Promise<ScanResult & {
+    oversized: string[];
+}>;