uomtiles 0.1.0

package/dist/src/cli.js

@@ -0,0 +1,255 @@
+#!/usr/bin/env node
+import { existsSync, mkdirSync, readFileSync } from 'node:fs';
+import { createServer } from 'node:net';
+import { basename, dirname, extname, resolve } from 'node:path';
+import { fileURLToPath } from 'node:url';
+import { spawn } from 'node:child_process';
+import { isSea } from 'node:sea';
+import { defineCommand, runMain } from 'citty';
+import { accountFile, uomtilesDataDir, workspaceDirectory } from "./core/paths.js";
+import { DEFAULT_GRID_CRAWL_OPTIONS, runGridCrawl } from "./grid-crawl.js";
+import { FETCH_PROCESS_ENV } from "./core/fetch-process.js";
+import { diffUomtiles, exportTiles, inspectUomtiles, migrateToUomtiles } from "./core/uomtiles.js";
+import { SPACE_APP_ID, UOM_BASE, LOCATION_SSO_PATH } from "./config.js";
+const sea = isSea();
+const cliPath = sea ? null : fileURLToPath(import.meta.url);
+const compiled = cliPath ? extname(cliPath) === '.js' : false;
+const root = cliPath ? (compiled ? resolve(dirname(cliPath), '../..') : resolve(dirname(cliPath), '..')) : process.cwd();
+function readAccount() {
+    const path = accountFile();
+    if (!existsSync(path))
+        throw new Error(`尚未登录。请先运行 npx uomtiles 并在 Web 中登录（认证文件：${path}）`);
+    return JSON.parse(readFileSync(path, 'utf8'));
+}
+async function whoami() {
+    const account = readAccount();
+    if (typeof account.sessionToken !== 'string')
+        throw new Error('固定认证文件中没有 UOM session token');
+    let response;
+    try {
+        response = await fetch(UOM_BASE + LOCATION_SSO_PATH, {
+            method: 'POST',
+            headers: { Authorization: account.sessionToken, language: 'en-US', timezone: 'Asia/Shanghai', 'Content-Type': 'application/json' },
+            body: JSON.stringify({ appId: SPACE_APP_ID, location: '/spaceIndex', params: 'yxAppPath=space' }),
+            signal: AbortSignal.timeout(20_000),
+        });
+    }
+    catch {
+        console.log(JSON.stringify({ authenticated: true, upstream: 'offline', nickname: account.username || null }, null, 2));
+        return;
+    }
+    if (response.status === 401 || response.status === 403) {
+        console.log(JSON.stringify({ authenticated: false, upstream: 'reauth-required', nickname: account.username || null }, null, 2));
+        process.exitCode = 1;
+        return;
+    }
+    const body = await response.json();
+    const location = body.success === true && typeof body.data === 'string' ? new URL(body.data) : null;
+    console.log(JSON.stringify({ authenticated: Boolean(location), upstream: location ? 'ready' : 'invalid-response',
+        nickname: location?.searchParams.get('userName') || account.username || null }, null, 2));
+    if (!location)
+        process.exitCode = 1;
+}
+function workspaceTaskPath(file) {
+    const account = readAccount();
+    const requested = file?.trim();
+    if (requested) {
+        if (requested !== basename(requested) || requested.includes('\\') || requested.includes('\0')) {
+            throw new Error('fetch 只接受工作区内的文件名，不接受路径');
+        }
+        const filename = requested.toLowerCase().endsWith('.uomtiles') ? requested : `${requested}.uomtiles`;
+        return resolve(workspaceDirectory(), filename);
+    }
+    const nickname = String(account.username || 'uom').replace(/[^a-zA-Z0-9_-]+/g, '_');
+    const stamp = new Date().toISOString().replace(/[:.]/g, '-').slice(0, 19);
+    return resolve(workspaceDirectory(), `${nickname}-${stamp}.uomtiles`);
+}
+async function runChild(command, args, env = process.env) {
+    return await new Promise((resolveChild, reject) => {
+        const child = spawn(command, args, { cwd: process.cwd(), env, stdio: 'inherit' });
+        const forward = (signal) => {
+            if (!child.killed)
+                child.kill(signal);
+        };
+        const cleanup = () => {
+            process.off('SIGINT', forward);
+            process.off('SIGTERM', forward);
+        };
+        child.once('error', error => { cleanup(); reject(error); });
+        child.once('close', (code, signal) => { cleanup(); resolveChild(code ?? (signal ? 128 : 1)); });
+        process.once('SIGINT', forward);
+        process.once('SIGTERM', forward);
+    });
+}
+function fetchProcessSpec() {
+    if (sea)
+        return { command: process.execPath, args: ['fetch-child'] };
+    if (!cliPath)
+        throw new Error('CLI entry is unavailable');
+    return {
+        command: process.execPath,
+        args: compiled ? [cliPath, 'fetch-child'] : ['--experimental-strip-types', '--no-warnings', cliPath, 'fetch-child'],
+    };
+}
+function fetchEnvironment(filename, pretty) {
+    return {
+        ...process.env,
+        UOMTILES_DATA_DIR: process.env.UOMTILES_DATA_DIR || uomtilesDataDir(),
+        UOMTILES_TASK_FILENAME: filename,
+        ...(pretty ? { UOMTILES_PRETTY: '1' } : {}),
+    };
+}
+async function fetchTask(file, detached = false) {
+    readAccount();
+    const target = workspaceTaskPath(file);
+    if (existsSync(target) && !target.endsWith('.uomtiles'))
+        throw new Error('继续抓取只接受 .uomtiles 工作数据库');
+    mkdirSync(dirname(target), { recursive: true });
+    const filename = basename(target);
+    const spec = fetchProcessSpec();
+    const env = fetchEnvironment(filename, !detached);
+    if (detached) {
+        const child = spawn(spec.command, spec.args, { cwd: process.cwd(), env, stdio: 'ignore', detached: true });
+        child.once('error', error => console.error(`后台抓取启动失败：${error.message}`));
+        child.unref();
+        console.log(`后台抓取已启动：${filename} (pid ${child.pid ?? 'unknown'})`);
+        return;
+    }
+    console.log(`${existsSync(target) ? '继续' : '创建'}任务：${target}`);
+    process.exitCode = await runChild(spec.command, spec.args, env);
+}
+async function fetchChild(file) {
+    const auth = accountFile();
+    readAccount();
+    const target = workspaceTaskPath(file);
+    await runGridCrawl({ ...DEFAULT_GRID_CRAWL_OPTIONS, db: target, auth });
+}
+async function freePort(preferred) {
+    return await new Promise((resolvePort, reject) => {
+        const server = createServer();
+        server.once('error', reject);
+        server.listen(preferred, '127.0.0.1', () => {
+            const address = server.address();
+            const port = typeof address === 'object' && address ? address.port : preferred;
+            server.close(() => resolvePort(port));
+        });
+    });
+}
+function openUrl(url) {
+    const command = process.platform === 'darwin' ? 'open' : process.platform === 'win32' ? 'cmd' : 'xdg-open';
+    const args = process.platform === 'win32' ? ['/c', 'start', '', url] : [url];
+    const child = spawn(command, args, { detached: true, stdio: 'ignore' });
+    child.on('error', () => { });
+    child.unref();
+}
+async function web() {
+    const entry = resolve(root, '.output/server/index.mjs');
+    if (!existsSync(entry))
+        throw new Error('Web 构建不存在；开发仓库请先运行 pnpm build');
+    const port = await freePort(Number(process.env.UOMTILES_PORT || 4173));
+    const dataDir = uomtilesDataDir();
+    mkdirSync(dataDir, { recursive: true });
+    const url = `http://127.0.0.1:${port}`;
+    console.log(`UOM适飞地图：${url}`);
+    console.log('按 Ctrl+C 停止。');
+    openUrl(url);
+    const code = await runChild(process.execPath, [entry], {
+        ...process.env,
+        HOST: '127.0.0.1',
+        PORT: String(port),
+        NUXT_DATA_DIR: dataDir,
+        UOMTILES_DATA_DIR: dataDir,
+        [FETCH_PROCESS_ENV]: JSON.stringify(fetchProcessSpec()),
+    });
+    process.exitCode = code;
+}
+const webCommand = defineCommand({
+    meta: { name: 'web', description: '打开本地 Web 工作台', hidden: true },
+    run: web,
+});
+const whoamiCommand = defineCommand({
+    meta: { name: 'whoami', description: '验证当前 UOM 账户' },
+    run: whoami,
+});
+const fetchCommand = defineCommand({
+    meta: { name: 'fetch', description: '创建或继续全国抓取' },
+    args: {
+        file: { type: 'positional', description: '任务文件名（可省略）', required: false },
+        detach: { type: 'boolean', description: '脱离终端在后台下载', alias: ['d'] },
+    },
+    run: ({ args }) => fetchTask(args.file, args.detach),
+});
+const fetchChildCommand = defineCommand({
+    meta: { name: 'fetch-child', description: '执行单个抓取任务', hidden: true },
+    args: {
+        file: { type: 'positional', description: '任务文件名', required: true },
+    },
+    run: ({ args }) => fetchChild(args.file),
+});
+const inspectCommand = defineCommand({
+    meta: { name: 'inspect', description: '查看任务或瓦片文件摘要' },
+    args: {
+        file: { type: 'positional', description: '输入文件', required: true },
+    },
+    run: ({ args }) => {
+        console.log(JSON.stringify(inspectUomtiles(args.file), null, 2));
+    },
+});
+const exportCommand = defineCommand({
+    meta: { name: 'export', description: '导出 MBTiles 或 PMTiles' },
+    args: {
+        input: { type: 'positional', description: '输入 .uomtiles 文件', required: true },
+        output: { type: 'positional', description: '输出 .mbtiles 或 .pmtiles 文件', required: true },
+    },
+    run: async ({ args }) => {
+        await exportTiles(args.input, args.output);
+        console.log(`已导出：${resolve(args.output)}`);
+    },
+});
+const diffCommand = defineCommand({
+    meta: { name: 'diff', description: '比较两个 UOMTiles 文件' },
+    args: {
+        left: { type: 'positional', description: '左侧文件', required: true },
+        right: { type: 'positional', description: '右侧文件', required: true },
+        report: { type: 'positional', description: '可选 JSON 报告路径', required: false },
+    },
+    run: async ({ args }) => {
+        const report = diffUomtiles(args.left, args.right);
+        const text = JSON.stringify(report, null, 2);
+        if (args.report)
+            await import('node:fs').then(fs => fs.writeFileSync(resolve(args.report), text));
+        console.log(text);
+        if (!report.identical)
+            process.exitCode = 2;
+    },
+});
+const migrateCommand = defineCommand({
+    meta: { name: 'migrate', description: '迁移旧瓦片数据库为 UOMTiles' },
+    args: {
+        input: { type: 'positional', description: '源文件', required: true },
+        output: { type: 'positional', description: '目标 .uomtiles 文件', required: true },
+    },
+    run: ({ args }) => {
+        const account = existsSync(accountFile()) ? readAccount() : null;
+        console.log(JSON.stringify(migrateToUomtiles(args.input, args.output, account?.username || null), null, 2));
+    },
+});
+const mainCommand = defineCommand({
+    meta: {
+        name: 'uomtiles',
+        version: process.env.npm_package_version || '0.1.0',
+        description: 'UOM适飞地图预览、下载、对比和发布工具',
+    },
+    default: 'web',
+    subCommands: {
+        web: webCommand,
+        whoami: whoamiCommand,
+        fetch: fetchCommand,
+        'fetch-child': fetchChildCommand,
+        inspect: inspectCommand,
+        export: exportCommand,
+        diff: diffCommand,
+        migrate: migrateCommand,
+    },
+});
+await runMain(mainCommand);

package/dist/src/config.js

@@ -0,0 +1,56 @@
+export const PROVINCE_CODES = [
+    '120000', '130000', '140000', '150000',
+    '210000', '220000', '230000',
+    '310000', '320000', '330000', '340000', '350000', '360000', '370000',
+    '410000', '420000', '430000', '440000', '450000', '460000',
+    '500000', '510000', '520000', '530000', '540000',
+    '610000', '620000', '630000', '640000', '650000',
+];
+// Exact layer grouping observed in the official UOM public-map frontend.
+export const OFFICIAL_WMS_LAYER_GROUPS = [
+    ['120000', '130000', '140000', '150000'],
+    ['210000', '220000', '230000'],
+    ['310000', '320000', '330000', '340000', '350000', '360000', '370000'],
+    ['410000', '420000', '430000', '440000', '450000', '460000'],
+    ['500000', '510000', '520000', '530000', '540000'],
+    ['610000', '620000', '630000', '640000', '650000'],
+];
+export const STYLE_NAME = 'QGSFKYFW:shifeikongyu';
+export const CHINA_BBOX_LL = {
+    lonMin: 73,
+    latMin: 17.5,
+    lonMax: 135.5,
+    latMax: 54,
+};
+export const UOM_BASE = 'https://uom.caac.gov.cn';
+export const WMS_PATH = '/map/airspace/wms';
+export const GET_TOKEN_V2_PATH = '/oapi/pub/datang/getTokenV2';
+export const LOCATION_SSO_PATH = '/api/nvwa-certification/v1/location/sso';
+export const PUB_SSO_PATH = '/oapi/pub/api/sso';
+export const SPACE_APP_ID = '54b78ded-14b7-67ed-6030-f899fe4f999c';
+export const DEFAULTS = {
+    qpsStart: 30,
+    qpsMin: 1,
+    qpsMax: 500000,
+    perLayerTimeoutMs: 15_000,
+    retryMax: 5,
+    // Adaptive controller params:
+    // Sliding window of recent request outcomes used by the controller.
+    ctlWindowSize: 200,
+    // After a success-rich window, multiply qps by this factor.
+    ctlIncFactor: 1.15,
+    // After a 429/503, multiply qps by this factor (multiplicative decrease).
+    ctlRateLimitFactor: 0.5,
+    // After repeated soft signals (timeouts, slowing p95), gently back off.
+    ctlSoftBackoffFactor: 0.85,
+    // Re-evaluate at most every N ms.
+    ctlMinIntervalMs: 1_500,
+    // Latency target: if window p95 > targetP95Ms * tolerance, back off.
+    ctlTargetP95Ms: 1_200,
+    ctlP95Tolerance: 1.6,
+    ctlInflightMin: 8,
+    ctlInflightMax: 5000,
+    ctlConnectionsMax: 8192,
+};
+export const MAP_TOKEN_ENV_KEY = 'MAP_TOKEN';
+export const SESSION_TOKEN_ENV_KEY = 'UOM_SESSION_TOKEN';

package/dist/src/core/fetch-process.js

@@ -0,0 +1,19 @@
+export const FETCH_PROCESS_ENV = 'UOMTILES_FETCH_PROCESS';
+export function decodeFetchProcess(value) {
+    if (!value)
+        throw new Error(`${FETCH_PROCESS_ENV} is not configured`);
+    let parsed;
+    try {
+        parsed = JSON.parse(value);
+    }
+    catch {
+        throw new Error(`${FETCH_PROCESS_ENV} is invalid`);
+    }
+    if (!parsed || typeof parsed !== 'object')
+        throw new Error(`${FETCH_PROCESS_ENV} is invalid`);
+    const spec = parsed;
+    if (typeof spec.command !== 'string' || !spec.command || !Array.isArray(spec.args) || spec.args.some(arg => typeof arg !== 'string')) {
+        throw new Error(`${FETCH_PROCESS_ENV} is invalid`);
+    }
+    return { command: spec.command, args: spec.args };
+}

package/dist/src/core/grid-renderer.js

@@ -0,0 +1,149 @@
+import { DatabaseSync } from 'node:sqlite';
+import { geographicGridLines, renderGeographicGridTile } from "../geographic-grid.js";
+import { deriveParentMask } from "../quality.js";
+import { encodeCanonicalMask } from "./png.js";
+export const ROOT_ZOOM = 9;
+export const SOURCE_ZOOM = 12;
+export const DYNAMIC_MAX_ZOOM = 18;
+export const PUBLISH_MAX_ZOOM = 14;
+const sourceRootSize = 256 * 2 ** (SOURCE_ZOOM - ROOT_ZOOM);
+function decodeRectangles(value) {
+    if (value.byteLength % 8 !== 0)
+        throw new Error('invalid grid rectangle payload');
+    const buffer = Buffer.from(value.buffer, value.byteOffset, value.byteLength);
+    const rects = [];
+    for (let offset = 0; offset < buffer.length; offset += 8) {
+        rects.push({
+            col0: buffer.readUInt16LE(offset),
+            row0: buffer.readUInt16LE(offset + 2),
+            col1: buffer.readUInt16LE(offset + 4),
+            row1: buffer.readUInt16LE(offset + 6),
+        });
+    }
+    return rects;
+}
+function rootRange(z, coordinate) {
+    if (z >= ROOT_ZOOM) {
+        const root = Math.floor(coordinate / 2 ** (z - ROOT_ZOOM));
+        return [root, root];
+    }
+    const scale = 2 ** (ROOT_ZOOM - z);
+    return [coordinate * scale, (coordinate + 1) * scale - 1];
+}
+export class GeographicGridRenderer {
+    roots = new Map();
+    masks = new Map();
+    constructor(path) {
+        const db = new DatabaseSync(path, { readOnly: true });
+        try {
+            const table = db.prepare("SELECT 1 ok FROM sqlite_master WHERE type='table' AND name='grid_roots'").get();
+            if (!table)
+                return;
+            const columns = new Set(db.prepare('PRAGMA table_info(grid_roots)').all().map(column => column.name));
+            if (!columns.has('rectangles'))
+                return;
+            const rows = db.prepare(`SELECT root_x x,root_y y,rectangles FROM grid_roots
+        WHERE state='completed' AND rectangles IS NOT NULL AND length(rectangles)>0`).all();
+            for (const row of rows) {
+                const lines = geographicGridLines({ sourceZ: SOURCE_ZOOM, parentZ: ROOT_ZOOM, parentX: row.x, parentY: row.y, width: sourceRootSize });
+                this.roots.set(`${row.x}/${row.y}`, { x: row.x, y: row.y, rects: decodeRectangles(row.rectangles), ...lines });
+            }
+        }
+        finally {
+            db.close();
+        }
+    }
+    get available() { return this.roots.size > 0; }
+    hasGeometry(z, x, y) {
+        const [rootX0, rootX1] = rootRange(z, x);
+        const [rootY0, rootY1] = rootRange(z, y);
+        for (let rootY = rootY0; rootY <= rootY1; rootY++)
+            for (let rootX = rootX0; rootX <= rootX1; rootX++) {
+                if (this.roots.has(`${rootX}/${rootY}`))
+                    return true;
+            }
+        return false;
+    }
+    renderMask(z, x, y) {
+        if (!Number.isInteger(z) || z < 0 || z > DYNAMIC_MAX_ZOOM)
+            throw new RangeError(`unsupported dynamic zoom z${z}`);
+        const key = `${z}/${x}/${y}`;
+        const cached = this.masks.get(key);
+        if (cached)
+            return cached;
+        if (!this.hasGeometry(z, x, y))
+            return new Uint8Array(256 * 256);
+        if (z < ROOT_ZOOM) {
+            const mask = deriveParentMask([
+                this.renderMask(z + 1, x * 2, y * 2),
+                this.renderMask(z + 1, x * 2 + 1, y * 2),
+                this.renderMask(z + 1, x * 2, y * 2 + 1),
+                this.renderMask(z + 1, x * 2 + 1, y * 2 + 1),
+            ]);
+            this.masks.set(key, mask);
+            return mask;
+        }
+        const mask = new Uint8Array(256 * 256);
+        const [rootX0, rootX1] = rootRange(z, x);
+        const [rootY0, rootY1] = rootRange(z, y);
+        for (let rootY = rootY0; rootY <= rootY1; rootY++)
+            for (let rootX = rootX0; rootX <= rootX1; rootX++) {
+                const root = this.roots.get(`${rootX}/${rootY}`);
+                if (!root)
+                    continue;
+                const rendered = renderGeographicGridTile({ rects: root.rects, xLines: root.xLines, yLines: root.yLines }, { sourceZ: SOURCE_ZOOM, parentZ: ROOT_ZOOM, parentX: rootX, parentY: rootY, width: sourceRootSize }, z, x, y);
+                for (let pixel = 0; pixel < mask.length; pixel++)
+                    if (rendered[pixel])
+                        mask[pixel] = 1;
+            }
+        if (this.masks.size < 512)
+            this.masks.set(key, mask);
+        return mask;
+    }
+    renderTile(z, x, y) {
+        const mask = this.renderMask(z, x, y);
+        return mask.some(Boolean) ? encodeCanonicalMask(mask) : null;
+    }
+    *contentCoordinates(z) {
+        const coordinates = new Set();
+        if (z < ROOT_ZOOM) {
+            const scale = 2 ** (ROOT_ZOOM - z);
+            for (const root of this.roots.values())
+                coordinates.add(`${Math.floor(root.x / scale)}/${Math.floor(root.y / scale)}`);
+            for (const coordinate of [...coordinates].sort((left, right) => {
+                const [leftX, leftY] = left.split('/').map(Number), [rightX, rightY] = right.split('/').map(Number);
+                return leftX - rightX || leftY - rightY;
+            })) {
+                const [x, y] = coordinate.split('/').map(Number);
+                yield { z, x: x, y: y };
+            }
+            return;
+        }
+        const scale = 2 ** (z - SOURCE_ZOOM);
+        for (const root of this.roots.values())
+            for (const rect of root.rects) {
+                const sourceX0 = root.x * sourceRootSize;
+                const sourceY0 = root.y * sourceRootSize;
+                const pixelX0 = Math.round((sourceX0 + root.xLines[rect.col0]) * scale);
+                const pixelY0 = Math.round((sourceY0 + root.yLines[rect.row0]) * scale);
+                const pixelX1 = Math.round((sourceX0 + root.xLines[rect.col1]) * scale);
+                const pixelY1 = Math.round((sourceY0 + root.yLines[rect.row1]) * scale);
+                if (pixelX0 >= pixelX1 || pixelY0 >= pixelY1)
+                    continue;
+                const x0 = Math.floor(pixelX0 / 256), y0 = Math.floor(pixelY0 / 256);
+                const x1 = Math.floor((pixelX1 - 1) / 256), y1 = Math.floor((pixelY1 - 1) / 256);
+                const worldMax = 2 ** z - 1;
+                for (let tileY = Math.max(0, y0); tileY <= Math.min(worldMax, y1); tileY++) {
+                    for (let tileX = Math.max(0, x0); tileX <= Math.min(worldMax, x1); tileX++)
+                        coordinates.add(`${tileX}/${tileY}`);
+                }
+            }
+        for (const coordinate of [...coordinates].sort((left, right) => {
+            const [leftX, leftY] = left.split('/').map(Number), [rightX, rightY] = right.split('/').map(Number);
+            return leftX - rightX || leftY - rightY;
+        })) {
+            const [x, y] = coordinate.split('/').map(Number);
+            yield { z, x: x, y: y };
+        }
+    }
+}

package/dist/src/core/lease.js

@@ -0,0 +1,103 @@
+import { randomUUID } from 'node:crypto';
+import { hostname } from 'node:os';
+import { existsSync, mkdirSync } from 'node:fs';
+import { dirname } from 'node:path';
+import { DatabaseSync } from 'node:sqlite';
+const DEFAULT_LEASE_MS = 30_000;
+export function getSqliteLease(databasePath, resource, now = Date.now()) {
+    if (!existsSync(databasePath))
+        return null;
+    let db;
+    try {
+        db = new DatabaseSync(databasePath, { readOnly: true });
+    }
+    catch {
+        return null;
+    }
+    try {
+        const table = db.prepare("SELECT 1 present FROM sqlite_master WHERE type='table' AND name='uomtiles_leases'").get();
+        if (!table)
+            return null;
+        const row = db.prepare(`SELECT resource,owner,pid,hostname,acquired_at,heartbeat_at,expires_at
+      FROM uomtiles_leases WHERE resource=?`).get(resource);
+        if (!row || row.expires_at <= now)
+            return null;
+        return { resource: row.resource, owner: row.owner, pid: row.pid, hostname: row.hostname,
+            acquiredAt: row.acquired_at, heartbeatAt: row.heartbeat_at, expiresAt: row.expires_at };
+    }
+    catch {
+        return null;
+    }
+    finally {
+        db.close();
+    }
+}
+export function hasActiveSqliteLease(databasePath, resource, now = Date.now()) {
+    return Boolean(getSqliteLease(databasePath, resource, now));
+}
+function open(path) {
+    mkdirSync(dirname(path), { recursive: true });
+    const db = new DatabaseSync(path);
+    db.exec(`PRAGMA busy_timeout=5000;
+    CREATE TABLE IF NOT EXISTS uomtiles_leases(
+      resource TEXT PRIMARY KEY,
+      owner TEXT NOT NULL,
+      pid INTEGER NOT NULL,
+      hostname TEXT NOT NULL,
+      acquired_at INTEGER NOT NULL,
+      heartbeat_at INTEGER NOT NULL,
+      expires_at INTEGER NOT NULL);`);
+    return db;
+}
+export function acquireSqliteLease(databasePath, resource, leaseMs = DEFAULT_LEASE_MS) {
+    if (!resource)
+        throw new RangeError('SQLite lease resource cannot be empty');
+    if (!Number.isSafeInteger(leaseMs) || leaseMs <= 0)
+        throw new RangeError('SQLite lease duration must be a positive integer');
+    const db = open(databasePath);
+    const owner = randomUUID();
+    const now = Date.now();
+    try {
+        db.exec('BEGIN IMMEDIATE');
+        const current = db.prepare('SELECT owner,pid,hostname,expires_at FROM uomtiles_leases WHERE resource=?').get(resource);
+        if (current && current.expires_at > now) {
+            throw new Error(`SQLite 资源正被占用：${resource} (pid ${current.pid} on ${current.hostname})`);
+        }
+        db.prepare(`INSERT OR REPLACE INTO uomtiles_leases(resource,owner,pid,hostname,acquired_at,heartbeat_at,expires_at)
+      VALUES(?,?,?,?,?,?,?)`).run(resource, owner, process.pid, hostname(), now, now, now + leaseMs);
+        db.exec('COMMIT');
+    }
+    catch (error) {
+        try {
+            db.exec('ROLLBACK');
+        }
+        catch { }
+        db.close();
+        throw error;
+    }
+    let released = false;
+    return {
+        resource,
+        owner,
+        heartbeat() {
+            if (released)
+                return;
+            const heartbeatAt = Date.now();
+            const result = db.prepare('UPDATE uomtiles_leases SET heartbeat_at=?,expires_at=? WHERE resource=? AND owner=?')
+                .run(heartbeatAt, heartbeatAt + leaseMs, resource, owner);
+            if (result.changes !== 1)
+                throw new Error(`SQLite lease 已丢失：${resource}`);
+        },
+        release() {
+            if (released)
+                return;
+            released = true;
+            try {
+                db.prepare('DELETE FROM uomtiles_leases WHERE resource=? AND owner=?').run(resource, owner);
+            }
+            finally {
+                db.close();
+            }
+        },
+    };
+}

package/dist/src/core/paths.js

@@ -0,0 +1,13 @@
+import { homedir } from 'node:os';
+import { resolve } from 'node:path';
+export function uomtilesDataDir(fallback) {
+    const explicit = process.env.UOMTILES_DATA_DIR?.trim() || process.env.NUXT_DATA_DIR?.trim() || fallback?.trim();
+    return resolve(explicit || resolve(homedir(), '.uomtiles'));
+}
+export function accountFile(fallbackDataDir) {
+    const explicit = process.env.UOMTILES_AUTH_FILE?.trim();
+    return resolve(explicit || uomtilesDataDir(fallbackDataDir), explicit ? '' : 'auth.json');
+}
+export function workspaceDirectory(fallbackDataDir) {
+    return resolve(uomtilesDataDir(fallbackDataDir), 'workspace');
+}