@coralai/sps-plugin-storage-sync 0.1.0

package/dist/scanWorkspace.js

@@ -0,0 +1,204 @@
+/**
+ * @module        providers/storage/scanWorkspace
+ * @description   按声明枚举工作区里要同步的文件 + 发现项目 + 新鲜度。
+ *
+ * @layer         providers
+ *
+ * 🔴 **发现判据只看布局,不猜产品语义。** coral sidecar 用「目录下含 `assets/`」当发现判据,
+ *    于是"只有 `docs/`、还没有 `assets/`"的**设计师阶段项目整批静默缺席**(实测 163 个里 36 个)。
+ *    这里的判据是**三段布局**(`t<租户>/<产品>/<项目>`)—— 它是 sps 自己的工作区约定,
+ *    不是对产品内容的猜测。
+ *
+ * 🔴 **新鲜度按「同步范围」算,不是按某个固定目录算。** coral 那侧改对了发现判据、
+ *    却坏在紧挨着的下一行:`projectLastModified(p.abs, 'assets')` 对只有 `docs/` 的项目返回 `0`,
+ *    `0 >= cutoff` 恒假 ⇒ 36 个又被当成"30 天没动"跳过。
+ *    > 判据一:**范围一旦放宽,紧跟其后的每一道过滤都要跟着放宽** ——
+ *    >   漏掉的那道会把范围**原样缩回去**,而且报的是**另一个原因**("太旧"),查的人会去看时间。
+ *    > 判据二:**别让一个返回值同时表示两件事** —— 那个 `0` 同时是"从没改过"和"目录不存在"。
+ *    ⇒ 所以这里 `scopeLastModified` 回 `number | null`:**null = 范围内一个路径都不存在**,
+ *      与"存在但很旧"分开,由调用方分别计数、分别报。
+ */
+import { createHash } from 'node:crypto';
+import { readdir, readFile, stat } from 'node:fs/promises';
+import { join } from 'node:path';
+/** 发现共享根下的全部项目(三段布局)。不做任何内容判断。 */
+export async function discoverProjects(root) {
+    const out = [];
+    let tenants;
+    try {
+        tenants = (await readdir(root, { withFileTypes: true })).filter((e) => e.isDirectory()).map((e) => e.name);
+    }
+    catch {
+        return out;
+    }
+    for (const t of tenants) {
+        let products;
+        try {
+            products = (await readdir(join(root, t), { withFileTypes: true })).filter((e) => e.isDirectory()).map((e) => e.name);
+        }
+        catch {
+            continue;
+        }
+        for (const p of products) {
+            let projects;
+            try {
+                projects = (await readdir(join(root, t, p), { withFileTypes: true })).filter((e) => e.isDirectory()).map((e) => e.name);
+            }
+            catch {
+                continue;
+            }
+            for (const g of projects)
+                out.push({ rel: `${t}/${p}/${g}`, abs: join(root, t, p, g), product: p });
+        }
+    }
+    return out;
+}
+/**
+ * 声明范围内最近一次改动的时间。
+ *
+ * @returns 毫秒时间戳;**`null` = 范围内一个路径都不存在**(与"存在但很旧"是两件事)
+ */
+export async function scopeLastModified(projectAbs, include) {
+    let newest = null;
+    const bump = (ms) => {
+        if (newest === null || ms > newest)
+            newest = ms;
+    };
+    for (const entry of include) {
+        const abs = join(projectAbs, entry.replace(/\/+$/, ''));
+        let st;
+        try {
+            st = await stat(abs);
+        }
+        catch {
+            continue; // 这一项不存在 —— 不是"很旧",继续看下一项
+        }
+        if (!st.isDirectory()) {
+            bump(st.mtimeMs);
+            continue;
+        }
+        await walkMtime(abs, bump);
+    }
+    return newest;
+}
+async function walkMtime(dir, bump) {
+    let entries;
+    try {
+        entries = await readdir(dir, { withFileTypes: true });
+    }
+    catch {
+        return;
+    }
+    for (const e of entries) {
+        // 🔴 只看普通文件与目录:软链**不跟随**(跟随会把树外文件的 mtime 当成本项目的动静)。
+        if (e.isSymbolicLink())
+            continue;
+        const p = join(dir, e.name);
+        if (e.isDirectory()) {
+            await walkMtime(p, bump);
+            continue;
+        }
+        try {
+            bump((await stat(p)).mtimeMs);
+        }
+        catch {
+            /* 读不到就不算动静 */
+        }
+    }
+}
+/**
+ * 按声明枚举文件并算 md5。
+ *
+ * ⚠️ `maxBytes`:整份读进内存算 md5(与 coral 同做法 —— 上传时本来也要这份字节)。
+ * 上限**显式**给,不靠运气:树里有 172MB 的项目,一个失控的大文件不该把进程带走。
+ * 超限的算**失败**(计入 errors),不是静默跳过 —— 静默跳过会让"这个资源永远不在桶里"没人知道。
+ */
+export async function scanByScope(projectAbs, include, maxBytes) {
+    const files = [];
+    const unreadable = [];
+    const missing = [];
+    const skippedDot = [];
+    const oversized = [];
+    const seen = new Set();
+    /** ENOENT 不是"读不到",是"没有"。分开归类,否则告警恒响。 */
+    const isMissing = (e) => typeof e === 'object' && e !== null && e.code === 'ENOENT';
+    const addFile = async (abs, rel) => {
+        if (seen.has(rel))
+            return; // 声明里目录与文件重叠时不重复推
+        seen.add(rel);
+        let st;
+        try {
+            st = await stat(abs);
+        }
+        catch (e) {
+            (isMissing(e) ? missing : unreadable).push(rel);
+            return;
+        }
+        if (st.size > maxBytes) {
+            oversized.push(rel);
+            return;
+        }
+        let bytes;
+        try {
+            bytes = await readFile(abs);
+        }
+        catch (e) {
+            // 0600 读不到走 unreadable(必须被报出来);文件刚被删走 ENOENT ⇒ missing
+            (isMissing(e) ? missing : unreadable).push(rel);
+            return;
+        }
+        files.push({ rel, abs, size: st.size, md5: createHash('md5').update(bytes).digest('hex') });
+    };
+    const walk = async (absDir, relDir) => {
+        let entries;
+        try {
+            entries = await readdir(absDir, { withFileTypes: true });
+        }
+        catch (e) {
+            (isMissing(e) ? missing : unreadable).push(relDir);
+            return;
+        }
+        for (const e of entries) {
+            // 软链不跟随:枚举阶段就排除,别指望后面的围栏兜底
+            // (围栏仍然会跑 —— 两道都在,但**枚举不该把它交给围栏去拒**)。
+            if (e.isSymbolicLink())
+                continue;
+            // 点开头条目:枚举阶段就不产出。它们是中间产物(`.sprites.pre-orient.png`),
+            // 交给下限会触发**整趟拒绝** ⇒ 整个项目永久停同步,而且理由看起来像安全事件。
+            if (e.name.startsWith('.')) {
+                skippedDot.push(relDir ? `${relDir}/${e.name}` : e.name);
+                continue;
+            }
+            const abs = join(absDir, e.name);
+            const rel = relDir ? `${relDir}/${e.name}` : e.name;
+            if (e.isDirectory())
+                await walk(abs, rel);
+            else if (e.isFile())
+                await addFile(abs, rel);
+        }
+    };
+    for (const entry of include) {
+        const isDir = entry.endsWith('/');
+        const clean = entry.replace(/^\.\//, '').replace(/\/+$/, '');
+        if (!clean)
+            continue;
+        const abs = join(projectAbs, clean);
+        if (isDir) {
+            await walk(abs, clean);
+            continue;
+        }
+        // 不带尾斜杠的声明可能仍是目录(声明方少写了斜杠)—— 按实际类型走,别按写法猜
+        let st = null;
+        try {
+            st = await stat(abs);
+        }
+        catch {
+            continue; // 声明了但项目里没有:合法(比如设计师还没写 PRD),不是错误
+        }
+        if (st.isDirectory())
+            await walk(abs, clean);
+        else
+            await addFile(abs, clean);
+    }
+    return { files, unreadable, missing, skippedDot, oversized };
+}

package/dist/schema.d.ts

@@ -0,0 +1,37 @@
+/**
+ * @module        schema
+ * @description   配置的**形状声明** —— 宿主的插件页据此通用渲染表单。
+ *
+ * 🔴 `schemastery` 必须是 **peer 依赖**:宿主会把自己那份软链进来
+ *    (`linkHostPeers`)。插件自带一份的话会有两个 Schema 实例,
+ *    而 `Config` 是靠 `JSON.stringify` 出的 `{uid, refs}` 引用表传给前端的 ——
+ *    两个实例的 uid 对不上,表单就渲染不出来。
+ *
+ * ⚠️ `role('secret')` 让插件页把它当密码框。**它不改变落盘方式** ——
+ *    值仍然明文写进装配档(`~/.coral/assembly/base.yml`,0600)。
+ *    个人工具场景下已拍板可接受;要不写进装配档得走 `sps.credentials` 引用。
+ */
+import Schema from '@deepseek-ai/schemastery';
+export declare const Config: Schema<Schemastery.ObjectS<{
+    enabled: Schema<boolean, boolean>;
+    endpoint: Schema<string, string>;
+    bucket: Schema<string, string>;
+    accessKey: Schema<string, string>;
+    secretKey: Schema<string, string>;
+    region: Schema<string, string>;
+    pathStyle: Schema<boolean, boolean>;
+    intervalSec: Schema<number, number>;
+    sinceDays: Schema<number, number>;
+    maxBytes: Schema<number, number>;
+}>, Schemastery.ObjectT<{
+    enabled: Schema<boolean, boolean>;
+    endpoint: Schema<string, string>;
+    bucket: Schema<string, string>;
+    accessKey: Schema<string, string>;
+    secretKey: Schema<string, string>;
+    region: Schema<string, string>;
+    pathStyle: Schema<boolean, boolean>;
+    intervalSec: Schema<number, number>;
+    sinceDays: Schema<number, number>;
+    maxBytes: Schema<number, number>;
+}>>;

package/dist/schema.js

@@ -0,0 +1,32 @@
+/**
+ * @module        schema
+ * @description   配置的**形状声明** —— 宿主的插件页据此通用渲染表单。
+ *
+ * 🔴 `schemastery` 必须是 **peer 依赖**:宿主会把自己那份软链进来
+ *    (`linkHostPeers`)。插件自带一份的话会有两个 Schema 实例,
+ *    而 `Config` 是靠 `JSON.stringify` 出的 `{uid, refs}` 引用表传给前端的 ——
+ *    两个实例的 uid 对不上,表单就渲染不出来。
+ *
+ * ⚠️ `role('secret')` 让插件页把它当密码框。**它不改变落盘方式** ——
+ *    值仍然明文写进装配档(`~/.coral/assembly/base.yml`,0600)。
+ *    个人工具场景下已拍板可接受;要不写进装配档得走 `sps.credentials` 引用。
+ */
+import Schema from '@deepseek-ai/schemastery';
+export const Config = Schema.object({
+    enabled: Schema.boolean()
+        .default(false)
+        .description('是否开启同步。**默认关** —— 没配桶时开着只会每轮打日志。'),
+    endpoint: Schema.string().description('S3 兼容端点,如 http://127.0.0.1:9000'),
+    bucket: Schema.string().description('桶名。插件只认这一个名字,不认识桶里的语义分区。'),
+    accessKey: Schema.string().role('secret').description('访问密钥 ID'),
+    secretKey: Schema.string().role('secret').description('访问密钥'),
+    region: Schema.string().default('us-east-1').description('S3 region。MinIO 通常用 us-east-1,给值只是为了签名能算出来。'),
+    pathStyle: Schema.boolean()
+        .default(true)
+        .description('路径式寻址(http://host/bucket/key)。MinIO 自建部署一般需要它;虚拟主机式要 DNS 配合。'),
+    intervalSec: Schema.number().default(600).description('扫描间隔(秒)'),
+    sinceDays: Schema.number()
+        .default(7)
+        .description('只看近 N 天有改动的项目;0 = 全量。全量扫一遍很贵,而老项目通常已经同步过。'),
+    maxBytes: Schema.number().default(2097152).description('单文件大小上限(字节)。超过的跳过并计数。'),
+});

package/dist/syncProject.d.ts

@@ -0,0 +1,66 @@
+/**
+ * @module        providers/storage/syncProject
+ * @description   一个项目的一轮对账同步:枚举 → 过下限 → 与桶对账 → 上传(缩略图先、原图后)。
+ *
+ * @layer         providers
+ *
+ * 九条不变量见 `docs/design/storage-sync-implementation.md` §〇。落在代码里的要害是这几条:
+ *
+ * 🔴 **对账基准是桶本身,不是本地状态文件。** 本地清单一旦与桶脱节(桶被清过 / 上轮崩在一半 /
+ *    换了机器)会**永久跳过**某些文件且不报错;以桶的实际内容为准,一轮巡检就自愈。
+ *
+ * 🔴 **不删。** 本地文件没了 ≠ 用户要删桶里那份(工作区可能被重建、节点可能换了)。
+ *    `StorageBackend` 接口上**根本没有 delete** —— 比"记得别调"可靠。
+ *
+ * 🔴 **幂等判据的覆盖面必须等于产物面。** 这一轮产出两样(原图 + 缩略图),判据就得同时问两样:
+ *    只问原图 ⇒ 一张生成失败过的缩略图**永远不会被补上**,表现是"同步很成功、预览是空的"。
+ *
+ * 🔴 **缩略图先写、原图后写**,且缩略图**上传**失败时本轮不写原图 ——
+ *    原图 etag 与本地相等是这条流水线的**提交点**,顺序反了会永久停留在旧缩略图且不报错。
+ *    ⚠️ 区分**生成**失败(确定性:图坏了,照常传原图,否则坏文件把自己永远挡在桶外)
+ *       与**上传**失败(会留下陈旧缩略图 ⇒ 必须回退)。
+ *
+ * 🔴 **枚举完再判下限,再推第一个字节。** 下限若写在上传循环里,
+ *    排在拒绝项前面的文件**已经进桶了** —— 「整体失败」是关于**副作用**的断言,不是返回码。
+ *
+ * 🔴🔴 **但被拒的文件是"跳过并报出来",不是"整趟不推"**(coral 2026-08-19 指出,已改):
+ *    同一条下限用在**发布**路上,"整趟失败"是对的 —— 半个包比拒绝更难查;
+ *    用在**周期性**的同步路上就变成**那个项目永久停止同步**,而且理由看起来像安全事件。
+ *    > 判据:**同一条规则,在"一次性动作"和"周期性动作"上后果完全不同。**
+ *    > 周期性的路上,任何"整趟失败"都要能自己恢复,否则它等于一个**不报警的开关**。
+ *    而下限要防的事(凭据进桶)本来就是**逐文件**的 —— 跳过那一个就够了,
+ *    赔上整个项目既不更安全,又制造了一个静默停摆。
+ */
+import type { StorageBackend } from './StorageBackend.js';
+import { type ProjectDir } from './scanWorkspace.js';
+import { type SyncRejection } from './syncable.js';
+export declare const contentTypeOf: (rel: string) => string | undefined;
+export declare const thumbnailable: (rel: string) => boolean;
+export interface SyncStats {
+    project: string;
+    scanned: number;
+    uploaded: number;
+    /** 与 uploaded **分开计** —— 合在一起就看不出预览到底有没有产出。 */
+    thumbs: number;
+    skipped: number;
+    failed: number;
+    unreadable: number;
+    /** 声明里有、盘上没有 —— **不是错误**(设计师还没写 PRD 也走这里)。与 unreadable 分开。 */
+    missing: number;
+    /** 枚举阶段跳过的点开头条目(中间产物)。不触发整趟拒绝。 */
+    skippedDot: number;
+    oversized: number;
+    /** 被安全下限拒的项。**整趟不推**(见模块头)。 */
+    rejected: SyncRejection[];
+    /** 用了窄兜底(该产品没有声明)。**必须被报出来**。 */
+    usedDefaultScope: boolean;
+    errors: string[];
+}
+export interface SyncDeps {
+    storage: StorageBackend;
+    /** 缩略图生成。注入是为了让用例不必依赖 sharp 的原生二进制。 */
+    makeThumb: (input: Buffer) => Promise<Buffer>;
+    /** 单文件上限(字节)。显式给,不靠运气。 */
+    maxBytes: number;
+}
+export declare function syncProject(deps: SyncDeps, project: ProjectDir, include: string[], usedDefaultScope: boolean): Promise<SyncStats>;

package/dist/syncProject.js

@@ -0,0 +1,135 @@
+/**
+ * @module        providers/storage/syncProject
+ * @description   一个项目的一轮对账同步:枚举 → 过下限 → 与桶对账 → 上传(缩略图先、原图后)。
+ *
+ * @layer         providers
+ *
+ * 九条不变量见 `docs/design/storage-sync-implementation.md` §〇。落在代码里的要害是这几条:
+ *
+ * 🔴 **对账基准是桶本身,不是本地状态文件。** 本地清单一旦与桶脱节(桶被清过 / 上轮崩在一半 /
+ *    换了机器)会**永久跳过**某些文件且不报错;以桶的实际内容为准,一轮巡检就自愈。
+ *
+ * 🔴 **不删。** 本地文件没了 ≠ 用户要删桶里那份(工作区可能被重建、节点可能换了)。
+ *    `StorageBackend` 接口上**根本没有 delete** —— 比"记得别调"可靠。
+ *
+ * 🔴 **幂等判据的覆盖面必须等于产物面。** 这一轮产出两样(原图 + 缩略图),判据就得同时问两样:
+ *    只问原图 ⇒ 一张生成失败过的缩略图**永远不会被补上**,表现是"同步很成功、预览是空的"。
+ *
+ * 🔴 **缩略图先写、原图后写**,且缩略图**上传**失败时本轮不写原图 ——
+ *    原图 etag 与本地相等是这条流水线的**提交点**,顺序反了会永久停留在旧缩略图且不报错。
+ *    ⚠️ 区分**生成**失败(确定性:图坏了,照常传原图,否则坏文件把自己永远挡在桶外)
+ *       与**上传**失败(会留下陈旧缩略图 ⇒ 必须回退)。
+ *
+ * 🔴 **枚举完再判下限,再推第一个字节。** 下限若写在上传循环里,
+ *    排在拒绝项前面的文件**已经进桶了** —— 「整体失败」是关于**副作用**的断言,不是返回码。
+ *
+ * 🔴🔴 **但被拒的文件是"跳过并报出来",不是"整趟不推"**(coral 2026-08-19 指出,已改):
+ *    同一条下限用在**发布**路上,"整趟失败"是对的 —— 半个包比拒绝更难查;
+ *    用在**周期性**的同步路上就变成**那个项目永久停止同步**,而且理由看起来像安全事件。
+ *    > 判据:**同一条规则,在"一次性动作"和"周期性动作"上后果完全不同。**
+ *    > 周期性的路上,任何"整趟失败"都要能自己恢复,否则它等于一个**不报警的开关**。
+ *    而下限要防的事(凭据进桶)本来就是**逐文件**的 —— 跳过那一个就够了,
+ *    赔上整个项目既不更安全,又制造了一个静默停摆。
+ */
+import { readFile } from 'node:fs/promises';
+import { extname } from 'node:path';
+import { assetKey, assetPrefix, thumbKey } from './keys.js';
+import { scanByScope } from './scanWorkspace.js';
+import { screenAll } from './syncable.js';
+/** 桶是直连的 —— **没有一层服务器能在返回时补救**,缺省的 octet-stream 会让预览图变成一次下载。 */
+const MIME = {
+    '.png': 'image/png', '.jpg': 'image/jpeg', '.jpeg': 'image/jpeg', '.webp': 'image/webp',
+    '.gif': 'image/gif', '.svg': 'image/svg+xml', '.json': 'application/json', '.txt': 'text/plain',
+    '.mp3': 'audio/mpeg', '.wav': 'audio/wav', '.ogg': 'audio/ogg', '.m4a': 'audio/mp4',
+    '.html': 'text/html', '.js': 'text/javascript', '.css': 'text/css', '.md': 'text/markdown',
+};
+export const contentTypeOf = (rel) => MIME[extname(rel).toLowerCase()];
+/** 能缩略的栅格图。**不认识的类型一律否**,别去猜;SVG 不缩(本来就小,且避开服务端光栅化任意 SVG)。 */
+const RASTER = new Set(['.png', '.jpg', '.jpeg', '.webp', '.gif', '.bmp', '.tiff', '.avif']);
+export const thumbnailable = (rel) => RASTER.has(extname(rel).toLowerCase());
+export async function syncProject(deps, project, include, usedDefaultScope) {
+    const stats = {
+        project: project.rel, scanned: 0, uploaded: 0, thumbs: 0, skipped: 0, failed: 0,
+        unreadable: 0, missing: 0, skippedDot: 0, oversized: 0, rejected: [], usedDefaultScope, errors: [],
+    };
+    const scan = await scanByScope(project.abs, include, deps.maxBytes);
+    stats.scanned = scan.files.length;
+    stats.unreadable = scan.unreadable.length;
+    stats.missing = scan.missing.length;
+    stats.skippedDot = scan.skippedDot.length;
+    stats.oversized = scan.oversized.length;
+    for (const rel of scan.unreadable.slice(0, 3))
+        stats.errors.push(`权限读不到(已跳过) ${rel}`);
+    for (const rel of scan.oversized.slice(0, 3))
+        stats.errors.push(`超过单文件上限(未同步) ${rel}`);
+    // 🔴 下限在**推第一个字节之前**整趟判完(不是边推边判)。
+    //    但结果是**把被拒的那些从名单里摘掉**,不是整趟不推 —— 理由见模块头。
+    stats.rejected = await screenAll(scan.files.map((f) => ({ rel: f.rel, abs: f.abs })), project.abs);
+    const blocked = new Set(stats.rejected.map((r) => r.rel));
+    // 拒绝项要把名字报出去:清单会过期,而**漏掉的必须能被看见**。
+    for (const r of stats.rejected.slice(0, 5))
+        stats.errors.push(`安全下限拒绝 ${r.code}: ${r.rel}`);
+    const allowed = scan.files.filter((f) => !blocked.has(f.rel));
+    let remote;
+    try {
+        remote = new Map((await deps.storage.list(assetPrefix(project.rel))).map((o) => [o.key, o.etag]));
+    }
+    catch (e) {
+        stats.failed++;
+        stats.errors.push(`列举桶失败:${e instanceof Error ? e.message : String(e)}`);
+        return stats;
+    }
+    for (const f of allowed) {
+        const key = assetKey(project.rel, f.rel);
+        const changed = remote.get(key) !== f.md5; // ETag == md5,**不看 mtime**
+        const tKey = thumbnailable(f.rel) ? thumbKey(project.rel, f.rel) : null;
+        const thumbMissing = tKey !== null && !remote.has(tKey);
+        if (!changed && !thumbMissing) {
+            stats.skipped++;
+            continue;
+        }
+        const fail = (e, what) => {
+            stats.failed++;
+            if (stats.errors.length < 8)
+                stats.errors.push(`${what} ${f.rel}: ${e instanceof Error ? e.message : String(e)}`);
+        };
+        let bytes;
+        try {
+            bytes = await readFile(f.abs);
+        }
+        catch (e) {
+            fail(e, '读文件');
+            continue;
+        }
+        let thumbUploadFailed = false;
+        if (tKey !== null && (changed || thumbMissing)) {
+            let thumb = null;
+            try {
+                thumb = await deps.makeThumb(bytes);
+            }
+            catch (e) {
+                fail(e, '生成缩略图'); // 生成失败是确定性的 ⇒ 照常传原图
+            }
+            if (thumb) {
+                try {
+                    await deps.storage.put(tKey, thumb, 'image/webp');
+                    stats.thumbs++;
+                }
+                catch (e) {
+                    fail(e, '上传缩略图');
+                    thumbUploadFailed = true; // ⇒ 本轮不写原图,免得下一轮判"没变"而永远停在旧缩略图
+                }
+            }
+        }
+        if (!changed || thumbUploadFailed)
+            continue;
+        try {
+            await deps.storage.put(key, bytes, contentTypeOf(f.rel));
+            stats.uploaded++;
+        }
+        catch (e) {
+            fail(e, '上传'); // 单文件失败不中断整轮 —— 下轮对账会再试,但原因要留下
+        }
+    }
+    return stats;
+}

package/dist/syncRunner.d.ts

@@ -0,0 +1,82 @@
+/**
+ * @module        providers/storage/syncRunner
+ * @description   对账循环:发现项目 → 新鲜度过滤 → 逐项目同步 → 汇总。
+ *
+ * @layer         providers
+ *
+ * 🔴 **它是对账循环,不是事件驱动**(照抄 coral 的判断,它是对的):
+ *    文件事件会漏(worker 在别的用户下写 / 容器里写 / 进程崩在一半),
+ *    而漏掉的表现是"桶里少了一个文件",**没有任何报错**。对账每轮都会自愈。
+ *
+ * 🔴 **跑在 daemon,不在 console 的请求路径。**
+ *    sidecar 是独立进程,而 console 是**共享事件循环** —— 同一段代码换了宿主就会开始
+ *    阻塞 `/api/health` 探针与 SSE 心跳。
+ *    > 判据:**同步在移交件里是对的 —— 它本来跑在 CLI 里;换了宿主之后才变错。**
+ *
+ * 🔴 **每一类"没做"都要有自己的计数**,别合并成一个"跳过":
+ *    超期跳过 / 范围内一个路径都不存在 / 权限读不到 / 超大 / 被下限拒 —— 五种原因,五个数。
+ *    合并的代价今天实测过:coral 那个 `0` 同时表示"从没改过"和"目录不存在",吃掉了 36 个项目。
+ */
+import type { StorageBackend } from './StorageBackend.js';
+import { type SyncStats } from './syncProject.js';
+import type { StorageSyncConfig } from './config.js';
+export interface SyncPassOptions {
+    /**
+     * 工作区布局 —— **由宿主的 `sps.workspace` seam 提供**,插件不自己扫目录。
+     *
+     * 🔴 发现判据(三段布局)与资产声明都是**宿主知识**。插件各带一份的话两份必漂,
+     *    而漂的症状是**一部分项目静默缺席**,不是报错 ——
+     *    实测同族:用「目录下含 assets/」当判据,163 个项目里 36 个整批缺席。
+     */
+    workspace: {
+        discover(): Promise<Array<{
+            rel: string;
+            abs: string;
+            product: string;
+        }>>;
+        assetScope(product: string): {
+            include: string[];
+            usedDefault: boolean;
+        };
+    };
+    /**
+     * 插件配置(装配档那一行的 `config:`)。**不传 = 没配置**,整条路径静默不存在。
+     * 🔴 别在这里回落读文件 —— "配置在哪"只能有一个答案。
+     */
+    config?: StorageSyncConfig;
+    root: string;
+    /** 只同步近 N 天动过的项目;0 = 全部。 */
+    sinceDays: number;
+    /** 单文件上限。 */
+    maxBytes: number;
+    /** 只跑一个项目(相对共享根),排障用。 */
+    onlyProject?: string;
+    log?: (line: string) => void;
+    /** 注入点:用例用假后端 / 假缩略图,不碰 minio 与 sharp 的原生依赖。 */
+    storage?: StorageBackend;
+    makeThumb?: (input: Buffer) => Promise<Buffer>;
+    now?: number;
+}
+export interface PassSummary {
+    projects: number;
+    scanned: number;
+    uploaded: number;
+    thumbs: number;
+    skipped: number;
+    failed: number;
+    unreadable: number;
+    missing: number;
+    skippedDot: number;
+    oversized: number;
+    rejected: number;
+    /** 因超过 sinceDays 没动而跳过。 */
+    skippedOld: number;
+    /** 🔴 范围内**一个路径都不存在** —— 与"很旧"分开数(它多半意味着声明写错了)。 */
+    skippedEmptyScope: number;
+    /** 用了窄兜底(该产品没有声明)的项目数。 */
+    defaultScope: number;
+    perProject: SyncStats[];
+}
+export declare function runSyncPass(opts: SyncPassOptions): Promise<PassSummary | null>;
+/** 汇总行。每一类"没做"都占一格 —— 一个悄悄缩小了范围的同步器,和一个坏掉的同步器,日志上一模一样。 */
+export declare function formatSummary(sum: PassSummary, started: number, opts: SyncPassOptions): string;