@pandablessing/dsh-user-sync 0.0.0-stage → 1.0.1

package/lib/state.js

@@ -0,0 +1,123 @@
+import { appendFileSync, copyFileSync, existsSync, mkdirSync, readdirSync, readFileSync, renameSync, rmSync, statSync, writeFileSync, } from 'node:fs';
+import { randomUUID } from 'node:crypto';
+import { dirname, join } from 'node:path';
+export const HISTORY_LIMIT = 200;
+export const LOCK_STALE_MS = 90_000;
+export function emptyState(deviceId = null) {
+    return { deviceId, auth: null, lastApplied: null, lastUploaded: null, files: {} };
+}
+export function loadState(statePath) {
+    try {
+        const raw = JSON.parse(readFileSync(statePath, 'utf8'));
+        return { ...emptyState(), ...raw, files: raw.files ?? {} };
+    }
+    catch {
+        return emptyState();
+    }
+}
+export function saveState(statePath, state) {
+    mkdirSync(dirname(statePath), { recursive: true });
+    const tmp = `${statePath}.tmp-${randomUUID().slice(0, 8)}`;
+    writeFileSync(tmp, `${JSON.stringify(state, null, 2)}\n`);
+    renameSync(tmp, statePath);
+}
+/** 追加一条审计记录，只保留最近 200 行。 */
+export function appendHistory(historyPath, entry) {
+    mkdirSync(dirname(historyPath), { recursive: true });
+    appendFileSync(historyPath, `${JSON.stringify(entry)}\n`);
+    const lines = readFileSync(historyPath, 'utf8').split('\n').filter(Boolean);
+    if (lines.length > HISTORY_LIMIT) {
+        writeFileSync(historyPath, `${lines.slice(-HISTORY_LIMIT).join('\n')}\n`);
+    }
+}
+/**
+ * 获取单实例锁。
+ * 心跳超 staleMs 视为僵死，允许抢占并标注 stolen。
+ */
+export function acquireLock({ lockPath, pid = process.pid, now = Date.now(), staleMs = LOCK_STALE_MS, }) {
+    mkdirSync(dirname(lockPath), { recursive: true });
+    if (existsSync(lockPath)) {
+        let holder = null;
+        try {
+            holder = JSON.parse(readFileSync(lockPath, 'utf8'));
+        }
+        catch {
+            holder = null;
+        }
+        const heartbeat = holder?.heartbeat ?? holder?.startedAt ?? 0;
+        if (holder && now - heartbeat < staleMs) {
+            return { acquired: false, holder, stolen: false };
+        }
+        writeFileSync(lockPath, JSON.stringify({ pid, startedAt: now, heartbeat: now }));
+        return { acquired: true, holder, stolen: true };
+    }
+    writeFileSync(lockPath, JSON.stringify({ pid, startedAt: now, heartbeat: now }));
+    return { acquired: true, holder: null, stolen: false };
+}
+export function heartbeatLock({ lockPath, pid = process.pid, now = Date.now() }) {
+    try {
+        const holder = JSON.parse(readFileSync(lockPath, 'utf8'));
+        if (holder.pid !== pid)
+            return false;
+        writeFileSync(lockPath, JSON.stringify({ ...holder, heartbeat: now }));
+        return true;
+    }
+    catch {
+        return false;
+    }
+}
+export function releaseLock({ lockPath, pid = process.pid }) {
+    try {
+        const holder = JSON.parse(readFileSync(lockPath, 'utf8'));
+        if (holder.pid !== pid)
+            return false;
+        rmSync(lockPath, { force: true });
+        return true;
+    }
+    catch {
+        return false;
+    }
+}
+/**
+ * 只清理本插件产生的包：前缀匹配 + 以 `-<deviceId>.tar.gz` 结尾。
+ * keep <= 0 表示不清理（§11）。
+ */
+export function cleanupPackages({ dir, deviceId = '', keep = 1, prefix = 'dsh-user-sync-', }) {
+    if (keep <= 0 || !existsSync(dir))
+        return { removed: [] };
+    const candidates = readdirSync(dir)
+        .filter((name) => name.startsWith(prefix) && name.endsWith('.tar.gz'))
+        .filter((name) => (deviceId ? name.endsWith(`-${deviceId}.tar.gz`) : true))
+        .map((name) => ({ name, mtime: statSync(join(dir, name)).mtimeMs }))
+        .sort((a, b) => b.mtime - a.mtime);
+    const removed = candidates.slice(keep).map((candidate) => candidate.name);
+    for (const name of removed)
+        rmSync(join(dir, name), { force: true });
+    return { removed };
+}
+/** 把快照目录下的全部文件按相对路径复制回目标根（支持多根映射）。 */
+export function restoreSnapshot({ snapshotRoot, targetRoot, resolveTarget, }) {
+    if (!existsSync(snapshotRoot))
+        return { restored: [] };
+    const toAbs = resolveTarget ?? ((rel) => join(targetRoot, rel));
+    const restored = [];
+    for (const rel of walkFiles(snapshotRoot, '')) {
+        const from = join(snapshotRoot, rel);
+        const to = toAbs(rel);
+        mkdirSync(dirname(to), { recursive: true });
+        copyFileSync(from, to);
+        restored.push(rel);
+    }
+    return { restored };
+}
+function walkFiles(root, prefix) {
+    const out = [];
+    for (const dirent of readdirSync(join(root, prefix), { withFileTypes: true })) {
+        const rel = prefix ? `${prefix}/${dirent.name}` : dirent.name;
+        if (dirent.isDirectory())
+            out.push(...walkFiles(root, rel));
+        else if (dirent.isFile())
+            out.push(rel);
+    }
+    return out;
+}

package/lib/sync.js

@@ -0,0 +1,251 @@
+import { readFileSync } from 'node:fs';
+import { join } from 'node:path';
+import { buildManifest, buildTarGz, MANIFEST_PATH, normalizeManifest, parseTarGz } from './archive.js';
+import { applyEntries, planApply } from './apply.js';
+import { hashBytes } from './hash.js';
+import { decide } from './lww.js';
+import { scanAssets, DEFAULT_MODULES } from './scan.js';
+import { scanBuffer } from './secret.js';
+import { acquireLock, appendHistory, loadState, releaseLock, saveState } from './state.js';
+export function makePackageId({ deviceId = 'local0000', now = new Date() } = {}) {
+    const pad = (n) => String(n).padStart(2, '0');
+    const stamp = `${now.getFullYear()}${pad(now.getMonth() + 1)}${pad(now.getDate())}-${pad(now.getHours())}${pad(now.getMinutes())}`;
+    return `${stamp}-${String(deviceId).toLowerCase().replace(/[^a-z0-9]/g, '').slice(0, 16).padEnd(6, '0')}`;
+}
+/**
+ * 同步编排：扫描 → 打包 → 判定 → 应用 → 审计。
+ * 不直接写界面状态；所有动作返回结果对象，由调用方决定展示与确认。
+ */
+export function createSync({ dshHome, userHome, profileName = 'desktop', transport, statePath, historyPath, lockPath, preRestoreRoot, modules, excludeGlobs = [], clockSkewMs, deviceId, }) {
+    const paths = {
+        state: statePath ?? join(dshHome, 'user-sync', 'state.json'),
+        history: historyPath ?? join(dshHome, 'user-sync', 'history.jsonl'),
+        lock: lockPath ?? join(dshHome, 'user-sync', 'lock'),
+        preRestore: preRestoreRoot ?? join(dshHome, 'user-sync', `pre-restore-${Date.now()}`),
+    };
+    /** 包内路径 → 绝对路径：skills/ 落到 userHome，其余落到 dshHome。 */
+    const resolveTarget = (rel) => {
+        if (rel.startsWith('skills/'))
+            return join(userHome, '.agents', 'skills', rel.slice('skills/'.length));
+        return join(dshHome, rel);
+    };
+    /** 活动传输：folder 用于调试，api 用于多用户。可在运行时切换。 */
+    let activeTransport = transport;
+    function setTransport(next) {
+        if (!next)
+            throw new Error('transport 不能为空');
+        activeTransport = next;
+        return activeTransport.id;
+    }
+    /** 运行时模块配置：显式参数优先，其次 state.json，最后默认四类用户级。会话不参与同步（体积大且不跨机）。 */
+    const modulesNow = () => {
+        const raw = modules ?? (Array.isArray(loadState(paths.state).modules) ? loadState(paths.state).modules : DEFAULT_MODULES);
+        return raw.filter((id) => id !== 'sessions');
+    };
+    function getModules() {
+        return modulesNow();
+    }
+    function setModules(list) {
+        const state = loadState(paths.state);
+        const next = Array.isArray(list) ? list.filter((id) => id !== 'sessions') : DEFAULT_MODULES;
+        state.modules = next;
+        saveState(paths.state, state);
+        return next;
+    }
+    function currentDeviceId() {
+        if (deviceId)
+            return deviceId;
+        const state = loadState(paths.state);
+        return state.deviceId ?? 'local0000';
+    }
+    function currentFiles() {
+        const { entries } = scanAssets({ dshHome, userHome, profileName, modules: modulesNow(), excludeGlobs });
+        const map = new Map();
+        for (const entry of entries) {
+            if (entry.mode === '120000')
+                continue;
+            map.set(entry.path, hashBytes(readFileSync(entry.absPath)));
+        }
+        return { entries, map };
+    }
+    /** 扫描 + 敏感扫描 + 打包。命中敏感数据整包拒绝（G4）。 */
+    function pack() {
+        const { entries, errors } = scanAssets({ dshHome, userHome, profileName, modules: modulesNow(), excludeGlobs });
+        if (errors.length > 0)
+            return { ok: false, code: errors[0].code ?? 'E_SCAN', errors };
+        const hits = [];
+        const files = [];
+        for (const entry of entries) {
+            if (entry.mode === '120000') {
+                files.push({ path: entry.path, sha256: hashBytes(Buffer.from(entry.linkTarget ?? '', 'utf8')), size: 0, mode: '120000' });
+                continue;
+            }
+            const data = readFileSync(entry.absPath);
+            const scan = scanBuffer(data, entry.path);
+            hits.push(...scan.hits);
+            files.push({ path: entry.path, sha256: hashBytes(data), size: data.length, mode: entry.mode });
+        }
+        if (hits.length > 0)
+            return { ok: false, code: 'E_SENSITIVE', hits };
+        const packageId = makePackageId({ deviceId: currentDeviceId() });
+        const manifest = buildManifest(files, {
+            packageId,
+            createdAt: new Date().toISOString(),
+            deviceId: currentDeviceId(),
+            platform: process.platform,
+            arch: process.arch,
+            profile: profileName,
+            modules: modulesNow(),
+        });
+        const tarEntries = [
+            { path: MANIFEST_PATH, data: Buffer.from(`${JSON.stringify(manifest, null, 2)}\n`, 'utf8') },
+        ];
+        for (const entry of entries) {
+            if (entry.mode === '120000') {
+                tarEntries.push({ path: entry.path, mode: '120000', type: 'symlink', linkTarget: entry.linkTarget });
+            }
+            else {
+                tarEntries.push({ path: entry.path, data: readFileSync(entry.absPath), mode: entry.mode });
+            }
+        }
+        return { ok: true, buffer: buildTarGz(tarEntries), manifest };
+    }
+    /** 上传当前本地包；上传前必须由调用方完成覆盖确认。 */
+    async function upload() {
+        const lock = acquireLock({ lockPath: paths.lock });
+        if (!lock.acquired)
+            return { ok: false, code: 'E_LOCKED', holder: lock.holder };
+        const started = Date.now();
+        try {
+            const packed = pack();
+            if (!packed.ok)
+                return packed;
+            const name = `dsh-user-sync-${packed.manifest.packageId}.tar.gz`;
+            await activeTransport.put(name, packed.buffer);
+            const state = loadState(paths.state);
+            state.lastUploaded = { packageId: packed.manifest.packageId, createdAt: packed.manifest.createdAt };
+            // 上传快照：check 用 state.files 判断「上传之后本机有没有再改」，
+            // 否则从未应用过本机时会把「刚上传」误判成两侧并发。
+            state.files = Object.fromEntries(packed.manifest.files.map((file) => [file.path, { sha256: file.sha256, size: file.size, uploadedAt: new Date().toISOString() }]));
+            state.deviceId = state.deviceId ?? currentDeviceId();
+            saveState(paths.state, state);
+            appendHistory(paths.history, {
+                at: new Date().toISOString(),
+                action: 'backup',
+                modules: packed.manifest.modules,
+                files: packed.manifest.files.length,
+                bytes: packed.buffer.length,
+                ok: true,
+                ms: Date.now() - started,
+            });
+            return { ok: true, packageId: packed.manifest.packageId, name, size: packed.buffer.length, manifest: packed.manifest };
+        }
+        catch (error) {
+            appendHistory(paths.history, { at: new Date().toISOString(), action: 'backup', ok: false, ms: Date.now() - started });
+            return { ok: false, code: 'E_UPLOAD_FAILED', detail: error.message };
+        }
+        finally {
+            releaseLock({ lockPath: paths.lock });
+        }
+    }
+    /** 只读远端元数据，返回判定结果；不下载、不写盘。 */
+    async function check() {
+        const remoteList = await activeTransport.list();
+        const latest = remoteList[0] ?? null;
+        const meta = latest ? await activeTransport.meta(latest.name) : null;
+        const state = loadState(paths.state);
+        const { map: localFiles } = currentFiles();
+        const appliedFiles = new Map(Object.entries(state.files ?? {}).map(([path, value]) => [path, value.sha256]));
+        const remote = meta
+            ? { packageId: meta.packageId, createdAt: meta.createdAt }
+            : latest
+                ? { packageId: latest.name, createdAt: latest.modifiedAt }
+                : null;
+        const decision = decide({
+            remote,
+            lastApplied: state.lastApplied,
+            lastUploaded: state.lastUploaded,
+            localFiles,
+            appliedFiles,
+            clockSkewMs,
+        });
+        let plan = null;
+        if (Array.isArray(meta?.files) && meta.files.length > 0) {
+            try {
+                plan = planApply({ manifestFiles: meta.files, localFiles });
+            }
+            catch {
+                plan = null; // 大小写冲突等由应用阶段拒绝，检查阶段不阻塞
+            }
+        }
+        return { decision, latest, meta, plan };
+    }
+    /** 下载并应用远端包；必须先由调用方完成覆盖确认。 */
+    async function applyRemote(name) {
+        const lock = acquireLock({ lockPath: paths.lock });
+        if (!lock.acquired)
+            return { ok: false, code: 'E_LOCKED', holder: lock.holder };
+        const started = Date.now();
+        try {
+            const buffer = await activeTransport.get(name);
+            const entries = parseTarGz(buffer);
+            const manifestEntry = entries.find((entry) => entry.path === MANIFEST_PATH);
+            if (!manifestEntry)
+                return { ok: false, code: 'E_HASH_MISMATCH', reason: 'manifest 缺失' };
+            const manifest = normalizeManifest(JSON.parse(manifestEntry.data.toString('utf8')));
+            for (const file of manifest.files) {
+                const entry = entries.find((item) => item.path === file.path);
+                if (!entry)
+                    return { ok: false, code: 'E_HASH_MISMATCH', detail: `缺少文件 ${file.path}` };
+                if (entry.type === 'file' && hashBytes(entry.data) !== file.sha256) {
+                    return { ok: false, code: 'E_HASH_MISMATCH', detail: `哈希不符 ${file.path}` };
+                }
+            }
+            for (const entry of entries) {
+                if (entry.path === MANIFEST_PATH || entry.type !== 'file')
+                    continue;
+                const scan = scanBuffer(entry.data, entry.path);
+                if (scan.hits.length > 0)
+                    return { ok: false, code: 'E_SENSITIVE', hits: scan.hits };
+            }
+            const { map: localFiles } = currentFiles();
+            const plan = planApply({ manifestFiles: manifest.files, localFiles });
+            const applied = applyEntries({ entries, resolveTarget, preRestoreRoot: paths.preRestore });
+            // PLUG-06：包内 cordis.patch.yml 引用的环境变量在本机缺失时提示（「插件装了但用不了」）
+            const missingEnv = [];
+            for (const entry of entries) {
+                if (!/^profiles\/[^/]+\/cordis\.patch\.yml$/.test(entry.path))
+                    continue;
+                const text = entry.data.toString('utf8');
+                for (const match of text.matchAll(/apiKeyEnv:\s*["']?([A-Za-z_][A-Za-z0-9_]*)/g)) {
+                    const varName = match[1];
+                    if (!process.env[varName] && !missingEnv.includes(varName))
+                        missingEnv.push(varName);
+                }
+            }
+            const state = loadState(paths.state);
+            state.lastApplied = { packageId: manifest.packageId, createdAt: manifest.createdAt };
+            state.deviceId = state.deviceId ?? currentDeviceId();
+            state.files = Object.fromEntries(manifest.files.map((file) => [file.path, { sha256: file.sha256, size: file.size, appliedAt: new Date().toISOString() }]));
+            saveState(paths.state, state);
+            appendHistory(paths.history, {
+                at: new Date().toISOString(),
+                action: 'restore',
+                modules: manifest.modules,
+                files: applied.written.length,
+                skipped: applied.skipped.length,
+                ok: true,
+                ms: Date.now() - started,
+            });
+            return { ok: true, manifest, plan, missingEnv, ...applied };
+        }
+        catch (error) {
+            appendHistory(paths.history, { at: new Date().toISOString(), action: 'restore', ok: false, ms: Date.now() - started });
+            return { ok: false, code: 'E_APPLY_FAILED', detail: error.message };
+        }
+        finally {
+            releaseLock({ lockPath: paths.lock });
+        }
+    }
+    return { paths, pack, upload, check, applyRemote, getModules, setModules, setTransport, getTransportId: () => activeTransport.id };
+}

package/lib/transport/api.js

@@ -0,0 +1,170 @@
+import { existsSync, mkdirSync, readFileSync, rmSync, writeFileSync } from 'node:fs';
+import { dirname } from 'node:path';
+import { isPackageId } from '../archive.js';
+const OFFICIAL_HOST = /(^|\.)deepseek\.com$/i;
+export class ApiError extends Error {
+    code;
+    status;
+    constructor(code, message, status) {
+        super(message);
+        this.code = code;
+        this.status = status;
+    }
+}
+/**
+ * 运营方 API 传输（B 模型）。插件侧只持有用户自己的 token，不接触存储凭据。
+ * 认证：register 首次建账号，login 取回同一 token；token 存 auth.json（0600）。
+ */
+export function createApiTransport({ baseUrl, authPath, token: initialToken, fetchImpl = globalThis.fetch, timeoutMs = 30_000, retries = 3, }) {
+    if (!baseUrl)
+        throw new Error('缺少 baseUrl');
+    const host = new URL(baseUrl).hostname;
+    if (OFFICIAL_HOST.test(host)) {
+        throw new ApiError('E_OFFICIAL_HOST', `拒绝官方域名: ${host}`);
+    }
+    let token = initialToken ?? null;
+    if (!token && authPath && existsSync(authPath)) {
+        try {
+            token = JSON.parse(readFileSync(authPath, 'utf8')).token ?? null;
+        }
+        catch {
+            token = null;
+        }
+    }
+    function persistAuth(next) {
+        token = next.token;
+        if (!authPath)
+            return;
+        mkdirSync(dirname(authPath), { recursive: true });
+        writeFileSync(authPath, `${JSON.stringify(next, null, 2)}\n`, { mode: 0o600 });
+    }
+    function clearAuth() {
+        token = null;
+        if (authPath)
+            rmSync(authPath, { force: true });
+    }
+    const sleep = (ms) => new Promise((resolve) => setTimeout(resolve, ms));
+    async function request(method, path, { body, headers = {}, expectBytes = false } = {}) {
+        const url = `${baseUrl.replace(/\/$/, '')}${path}`;
+        let lastError;
+        for (let attempt = 0; attempt <= retries; attempt++) {
+            try {
+                const response = await fetchImpl(url, {
+                    method,
+                    headers: {
+                        ...(token ? { authorization: `Bearer ${token}` } : {}),
+                        ...(body && !expectBytes ? { 'content-type': 'application/json' } : {}),
+                        ...headers,
+                    },
+                    body: body,
+                    signal: AbortSignal.timeout(timeoutMs),
+                });
+                if (response.status === 401 || response.status === 403) {
+                    throw new ApiError('E_REMOTE_AUTH', `认证失败（${response.status}）`, response.status);
+                }
+                if (response.status >= 400 && response.status < 500) {
+                    const detail = await response.text().catch(() => '');
+                    throw new ApiError(`E_HTTP_${response.status}`, detail.slice(0, 200) || `HTTP ${response.status}`, response.status);
+                }
+                if (!response.ok) {
+                    throw new ApiError('E_REMOTE_5XX', `服务端错误（${response.status}）`, response.status);
+                }
+                return expectBytes ? Buffer.from(await response.arrayBuffer()) : response;
+            }
+            catch (error) {
+                lastError = error;
+                const retryable = !(error instanceof ApiError) || error.code === 'E_REMOTE_5XX';
+                if (!retryable || attempt === retries)
+                    throw error;
+                await sleep(200 * 2 ** attempt);
+            }
+        }
+        throw lastError;
+    }
+    const parseJson = async (response) => {
+        const text = await response.text();
+        return text ? JSON.parse(text) : null;
+    };
+    return {
+        id: 'api',
+        baseUrl,
+        get token() {
+            return token;
+        },
+        /** 首次注册；已存在（409）时改走 login，取回同一个 token。 */
+        async register(accountKey) {
+            try {
+                const response = await request('POST', '/v1/auth/register', { body: JSON.stringify({ accountKey }) });
+                const data = await parseJson(response);
+                const token = String(data?.token ?? '');
+                persistAuth({ token, accountKeyHint: accountKey.slice(0, 6), registeredAt: new Date().toISOString() });
+                return { ok: true, token };
+            }
+            catch (error) {
+                if (error.code === 'E_HTTP_409')
+                    return this.login(accountKey);
+                throw error;
+            }
+        },
+        async login(accountKey) {
+            const response = await request('POST', '/v1/auth/login', { body: JSON.stringify({ accountKey }) });
+            const data = await parseJson(response);
+            const token = String(data?.token ?? '');
+            persistAuth({ token, accountKeyHint: accountKey.slice(0, 6), registeredAt: new Date().toISOString() });
+            return { ok: true, token };
+        },
+        async reset() {
+            await request('POST', '/v1/auth/reset');
+            clearAuth();
+            return { ok: true };
+        },
+        async test() {
+            try {
+                const response = await request('GET', '/v1/quota');
+                const data = await parseJson(response);
+                return { ok: true, detail: `配额 ${data?.used ?? 0}/${data?.limit ?? 0} 字节` };
+            }
+            catch (error) {
+                return { ok: false, detail: error.message };
+            }
+        },
+        async list() {
+            const response = await request('GET', '/v1/packages');
+            const data = await parseJson(response);
+            return (data?.packages ?? []).map((item) => ({
+                name: item.id,
+                size: item.size,
+                modifiedAt: item.createdAt,
+            }));
+        },
+        async meta(id) {
+            if (!isPackageId(id))
+                throw new ApiError('E_BAD_NAME', `非法包名: ${id}`);
+            const response = await request('GET', `/v1/packages/${encodeURIComponent(id)}/meta`);
+            return parseJson(response);
+        },
+        async get(id) {
+            if (!isPackageId(id))
+                throw new ApiError('E_BAD_NAME', `非法包名: ${id}`);
+            return request('GET', `/v1/packages/${encodeURIComponent(id)}`, { expectBytes: true });
+        },
+        async put(id, data) {
+            if (!isPackageId(id))
+                throw new ApiError('E_BAD_NAME', `非法包名: ${id}`);
+            await request('PUT', `/v1/packages/${encodeURIComponent(id)}`, {
+                body: data,
+                expectBytes: true,
+                headers: { 'content-type': 'application/octet-stream' },
+            });
+        },
+        async remove(id) {
+            if (!isPackageId(id))
+                throw new ApiError('E_BAD_NAME', `非法包名: ${id}`);
+            await request('DELETE', `/v1/packages/${encodeURIComponent(id)}`);
+        },
+        /** 导出我的全部数据（服务端打包当前包 + 元数据）。 */
+        async exportPackage() {
+            return request('GET', '/v1/export', { expectBytes: true });
+        },
+    };
+}

package/lib/transport/folder.js

@@ -0,0 +1,71 @@
+import { existsSync, mkdirSync, readdirSync, readFileSync, rmSync, statSync, writeFileSync } from 'node:fs';
+import { join } from 'node:path';
+import { isPackageId, MANIFEST_PATH, parseTarGz } from '../archive.js';
+/**
+ * 同步目录传输（folder）：自用/调试模式。
+ * 布局：<dir>/dsh-user-sync/<stamp>-<deviceId>.tar.gz（§6.2）
+ */
+export function createFolderTransport({ dir }) {
+    const ensureDir = () => {
+        mkdirSync(dir, { recursive: true });
+    };
+    const assertSafeName = (name) => {
+        if (!isPackageId(name))
+            throw new Error(`非法包名: ${name}`);
+    };
+    return {
+        id: 'folder',
+        async test() {
+            try {
+                ensureDir();
+                const probe = join(dir, `.probe-${Date.now()}`);
+                writeFileSync(probe, 'ok');
+                rmSync(probe, { force: true });
+                return { ok: true, detail: `可写: ${dir}` };
+            }
+            catch (error) {
+                return { ok: false, detail: error.message };
+            }
+        },
+        async list() {
+            ensureDir();
+            return readdirSync(dir)
+                .filter((name) => isPackageId(name))
+                .map((name) => ({
+                name,
+                size: statSync(join(dir, name)).size,
+                modifiedAt: statSync(join(dir, name)).mtime.toISOString(),
+            }))
+                .sort((a, b) => (a.modifiedAt < b.modifiedAt ? 1 : -1));
+        },
+        async meta(name) {
+            assertSafeName(name);
+            const abs = join(dir, name);
+            if (!existsSync(abs))
+                return null;
+            try {
+                const entries = parseTarGz(readFileSync(abs));
+                const manifest = entries.find((entry) => entry.path === MANIFEST_PATH);
+                if (!manifest)
+                    return null;
+                return JSON.parse(manifest.data.toString('utf8'));
+            }
+            catch {
+                return null;
+            }
+        },
+        async get(name) {
+            assertSafeName(name);
+            return readFileSync(join(dir, name));
+        },
+        async put(name, data) {
+            assertSafeName(name);
+            ensureDir();
+            writeFileSync(join(dir, name), data);
+        },
+        async remove(name) {
+            assertSafeName(name);
+            rmSync(join(dir, name), { force: true });
+        },
+    };
+}

package/lib/transport/types.js

@@ -0,0 +1,2 @@
+/** 传输层公共契约：folder 与 api 共用，sync 编排只依赖这个结构。 */
+export {};

package/locale/zh.json

@@ -0,0 +1,14 @@
+{
+  "meta": {
+    "title": "设置同步",
+    "description": "把技能、插件清单、配置与记忆在设备间对齐。"
+  },
+  "nav": "设置同步",
+  "empty": "四类用户级资产（技能 / 插件清单 / 配置 / 用户记忆）可在设备间同步。",
+  "status": {
+    "title": "状态",
+    "dshHome": "DSH 主目录",
+    "profile": "Profile",
+    "resolvedBy": "路径来源"
+  }
+}