@xyit/wellspring 0.0.0-stage → 1.1.0

package/dist/platform/index.js

@@ -0,0 +1,12 @@
+/*
+ * 平台层入口。
+ * 平台识别、目录解析与文件落盘；上层不直接读取 process.platform 或拼接系统目录。
+ */
+export * from "./clipboard.js";
+export * from "./exec.js";
+export * from "./file.js";
+export * from "./notification.js";
+export * from "./open-external.js";
+export * from "./os.js";
+export * from "./path.js";
+//# sourceMappingURL=index.js.map

package/dist/platform/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../src/platform/index.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAEH,cAAc,gBAAgB,CAAA;AAC9B,cAAc,WAAW,CAAA;AACzB,cAAc,WAAW,CAAA;AACzB,cAAc,mBAAmB,CAAA;AACjC,cAAc,oBAAoB,CAAA;AAClC,cAAc,SAAS,CAAA;AACvB,cAAc,WAAW,CAAA"}

package/dist/platform/notification.d.ts

@@ -0,0 +1,14 @@
+import { type PlatformName } from "./os.js";
+export interface NotifyOptions {
+    readonly title: string;
+    readonly body?: string;
+}
+export interface NotifyCommand {
+    readonly command: string;
+    readonly args: readonly string[];
+    readonly env?: Readonly<Record<string, string>>;
+}
+/** 生成候选命令，按优先级排列。单独导出以便在任意平台测试 */
+export declare function buildNotifyCommands(options: NotifyOptions, targetPlatform?: PlatformName, inWsl?: boolean): NotifyCommand[];
+/** 发送系统通知。全部候选失败时抛出聚合错误 */
+export declare function notify(options: NotifyOptions): Promise<void>;

package/dist/platform/notification.js

@@ -0,0 +1,82 @@
+/*
+ * 系统通知。
+ * Windows 走 PowerShell 的 WinRT toast，脚本内容经 -EncodedCommand 传递；
+ * WSL 下优先调用 powershell.exe，其余平台使用各自的通知命令。
+ */
+import { describeError, powershellArgs, runCommand } from "./exec.js";
+import { isWsl, platform } from "./os.js";
+const MACOS_SCRIPT = 'display notification (system attribute "WELLSPRING_NOTIFY_BODY") with title (system attribute "WELLSPRING_NOTIFY_TITLE")';
+/** PowerShell 单引号字符串，内部单引号翻倍 */
+function psQuote(value) {
+    return `'${value.replace(/'/g, "''")}'`;
+}
+function powershellToast(title, body) {
+    const script = [
+        "$ErrorActionPreference = 'Stop'",
+        "[Windows.UI.Notifications.ToastNotificationManager, Windows.UI.Notifications, ContentType = WindowsRuntime] > $null",
+        "$template = [Windows.UI.Notifications.ToastNotificationManager]::GetTemplateContent([Windows.UI.Notifications.ToastTemplateType]::ToastText02)",
+        '$texts = $template.GetElementsByTagName("text")',
+        `$texts.Item(0).AppendChild($template.CreateTextNode(${psQuote(title)})) > $null`,
+        `$texts.Item(1).AppendChild($template.CreateTextNode(${psQuote(body)})) > $null`,
+        "$toast = [Windows.UI.Notifications.ToastNotification]::new($template)",
+        '[Windows.UI.Notifications.ToastNotificationManager]::CreateToastNotifier("Wellspring").Show($toast)',
+    ].join("\n");
+    return powershellArgs(script);
+}
+function normalize(options) {
+    const title = options.title.trim();
+    if (title === "") {
+        throw new Error("通知标题为空");
+    }
+    return { title, body: options.body ?? "" };
+}
+/** 生成候选命令，按优先级排列。单独导出以便在任意平台测试 */
+export function buildNotifyCommands(options, targetPlatform = platform, inWsl = isWsl) {
+    const { title, body } = normalize(options);
+    if (targetPlatform === "windows") {
+        return [{ command: "powershell", args: powershellToast(title, body) }];
+    }
+    if (targetPlatform === "macos") {
+        return [
+            {
+                command: "osascript",
+                args: ["-e", MACOS_SCRIPT],
+                env: { WELLSPRING_NOTIFY_TITLE: title, WELLSPRING_NOTIFY_BODY: body },
+            },
+        ];
+    }
+    if (targetPlatform === "android") {
+        const args = ["--title", title];
+        if (body !== "") {
+            args.push("--content", body);
+        }
+        return [{ command: "termux-notification", args }];
+    }
+    const candidates = [];
+    if (inWsl) {
+        // WSL 没有桌面通知守护进程，转到 Windows 侧显示
+        candidates.push({ command: "powershell.exe", args: powershellToast(title, body) });
+    }
+    const args = ["-a", "wellspring", "--", title];
+    if (body !== "") {
+        args.push(body);
+    }
+    candidates.push({ command: "notify-send", args });
+    return candidates;
+}
+/** 发送系统通知。全部候选失败时抛出聚合错误 */
+export async function notify(options) {
+    const failures = [];
+    for (const candidate of buildNotifyCommands(options)) {
+        try {
+            const env = candidate.env === undefined ? undefined : { ...process.env, ...candidate.env };
+            await runCommand(candidate.command, candidate.args, { env });
+            return;
+        }
+        catch (error) {
+            failures.push(`${candidate.command}: ${describeError(error)}`);
+        }
+    }
+    throw new Error(`通知发送失败：${failures.join("；")}`);
+}
+//# sourceMappingURL=notification.js.map

package/dist/platform/notification.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"notification.js","sourceRoot":"","sources":["../../src/platform/notification.ts"],"names":[],"mappings":"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"}

package/dist/platform/open-external.d.ts

@@ -0,0 +1,10 @@
+import { type PlatformName } from "./os.js";
+/** 候选启动命令 */
+export interface OpenCommand {
+    readonly command: string;
+    readonly args: readonly string[];
+}
+/** 生成候选命令，按优先级排列。单独导出以便在任意平台测试各系统的构造结果 */
+export declare function buildOpenCommands(rawTarget: string, targetPlatform?: PlatformName, inWsl?: boolean, inTermux?: boolean): OpenCommand[];
+/** 依次尝试候选命令，全部失败时抛出聚合错误 */
+export declare function openExternal(rawTarget: string): Promise<void>;

package/dist/platform/open-external.js

@@ -0,0 +1,105 @@
+/*
+ * 用系统默认程序打开 URL 或本地路径。
+ * target 可能来自外部输入，须校验：以 "-" 开头会被 open / cmd start 视为参数，协议限定白名单。
+ */
+import { spawn } from "node:child_process";
+import { isAbsolute } from "node:path";
+import { describeError } from "./exec.js";
+import { isTermux, isWsl, platform } from "./os.js";
+/** 允许的协议 */
+const ALLOWED_PROTOCOLS = new Set(["http:", "https:", "file:"]);
+/** 绝对路径原样返回；其余须为白名单协议 URL。不合法时抛出异常 */
+function normalizeTarget(input) {
+    const target = input.trim();
+    if (target === "") {
+        throw new Error("打开目标为空值");
+    }
+    // 控制字符（含换行）会破坏命令行语义
+    if (/[\u0000-\u001f\u007f]/.test(target)) {
+        throw new Error("打开目标包含控制字符");
+    }
+    if (target.startsWith("-")) {
+        throw new Error(`打开目标不能以 "-" 开头：${target}`);
+    }
+    // 本地路径；Windows 的 "C:\\..." 亦归此类
+    if (isAbsolute(target)) {
+        return { target, isUrl: false };
+    }
+    let parsed;
+    try {
+        parsed = new URL(target);
+    }
+    catch {
+        throw new Error(`目标既非绝对路径也非合法 URL：${target}`);
+    }
+    if (!ALLOWED_PROTOCOLS.has(parsed.protocol)) {
+        throw new Error(`不允许的协议：${parsed.protocol}`);
+    }
+    return { target: parsed.href, isUrl: true };
+}
+/** 生成候选命令，按优先级排列。单独导出以便在任意平台测试各系统的构造结果 */
+export function buildOpenCommands(rawTarget, targetPlatform = platform, inWsl = isWsl, inTermux = isTermux) {
+    const { target, isUrl } = normalizeTarget(rawTarget);
+    if (targetPlatform === "windows") {
+        // 第二个参数为 start 的窗口标题占位；缺失时带引号的路径会被当作标题
+        return [{ command: "cmd", args: ["/c", "start", "", target] }];
+    }
+    if (targetPlatform === "macos") {
+        return [{ command: "open", args: [target] }];
+    }
+    if (targetPlatform === "android") {
+        const candidates = [];
+        if (inTermux) {
+            candidates.push({ command: "termux-open", args: [target] });
+        }
+        candidates.push({ command: "xdg-open", args: [target] });
+        // am 只能打开 URI，本地路径没有对应的 content:// 地址
+        if (isUrl) {
+            candidates.push({
+                command: "am",
+                args: ["start", "-a", "android.intent.action.VIEW", "-d", target],
+            });
+        }
+        return candidates;
+    }
+    const candidates = [];
+    if (inWsl) {
+        // WSL 下 xdg-open 常无效，优先 wslview（wslu），其次 explorer.exe
+        candidates.push({ command: "wslview", args: [target] });
+        candidates.push({ command: "explorer.exe", args: [target] });
+    }
+    candidates.push({ command: "xdg-open", args: [target] });
+    candidates.push({ command: "gio", args: ["open", target] });
+    return candidates;
+}
+function spawnDetached(command, args) {
+    return new Promise((resolve, reject) => {
+        const child = spawn(command, [...args], {
+            detached: true,
+            stdio: "ignore",
+            windowsHide: true,
+        });
+        child.once("error", reject);
+        child.once("spawn", () => {
+            // 不等待退出：浏览器与文件管理器均为长驻进程
+            child.unref();
+            resolve();
+        });
+    });
+}
+/** 依次尝试候选命令，全部失败时抛出聚合错误 */
+export async function openExternal(rawTarget) {
+    const { target } = normalizeTarget(rawTarget);
+    const failures = [];
+    for (const candidate of buildOpenCommands(target)) {
+        try {
+            await spawnDetached(candidate.command, candidate.args);
+            return;
+        }
+        catch (error) {
+            failures.push(`${candidate.command}: ${describeError(error)}`);
+        }
+    }
+    throw new Error(`无法打开 ${target}：已尝试 ${failures.join("；")}`);
+}
+//# sourceMappingURL=open-external.js.map

package/dist/platform/open-external.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"open-external.js","sourceRoot":"","sources":["../../src/platform/open-external.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAEH,OAAO,EAAE,KAAK,EAAE,MAAM,oBAAoB,CAAA;AAC1C,OAAO,EAAE,UAAU,EAAE,MAAM,WAAW,CAAA;AAEtC,OAAO,EAAE,aAAa,EAAE,MAAM,WAAW,CAAA;AACzC,OAAO,EAAE,QAAQ,EAAE,KAAK,EAAE,QAAQ,EAAqB,MAAM,SAAS,CAAA;AAQtE,YAAY;AACZ,MAAM,iBAAiB,GAAG,IAAI,GAAG,CAAC,CAAC,OAAO,EAAE,QAAQ,EAAE,OAAO,CAAC,CAAC,CAAA;AAO/D,sCAAsC;AACtC,SAAS,eAAe,CAAC,KAAa;IAClC,MAAM,MAAM,GAAG,KAAK,CAAC,IAAI,EAAE,CAAA;IAC3B,IAAI,MAAM,KAAK,EAAE,EAAE,CAAC;QAChB,MAAM,IAAI,KAAK,CAAC,SAAS,CAAC,CAAA;IAC9B,CAAC;IACD,oBAAoB;IACpB,IAAI,uBAAuB,CAAC,IAAI,CAAC,MAAM,CAAC,EAAE,CAAC;QACvC,MAAM,IAAI,KAAK,CAAC,YAAY,CAAC,CAAA;IACjC,CAAC;IACD,IAAI,MAAM,CAAC,UAAU,CAAC,GAAG,CAAC,EAAE,CAAC;QACzB,MAAM,IAAI,KAAK,CAAC,kBAAkB,MAAM,EAAE,CAAC,CAAA;IAC/C,CAAC;IACD,gCAAgC;IAChC,IAAI,UAAU,CAAC,MAAM,CAAC,EAAE,CAAC;QACrB,OAAO,EAAE,MAAM,EAAE,KAAK,EAAE,KAAK,EAAE,CAAA;IACnC,CAAC;IAED,IAAI,MAAW,CAAA;IACf,IAAI,CAAC;QACD,MAAM,GAAG,IAAI,GAAG,CAAC,MAAM,CAAC,CAAA;IAC5B,CAAC;IAAC,MAAM,CAAC;QACL,MAAM,IAAI,KAAK,CAAC,oBAAoB,MAAM,EAAE,CAAC,CAAA;IACjD,CAAC;IACD,IAAI,CAAC,iBAAiB,CAAC,GAAG,CAAC,MAAM,CAAC,QAAQ,CAAC,EAAE,CAAC;QAC1C,MAAM,IAAI,KAAK,CAAC,UAAU,MAAM,CAAC,QAAQ,EAAE,CAAC,CAAA;IAChD,CAAC;IACD,OAAO,EAAE,MAAM,EAAE,MAAM,CAAC,IAAI,EAAE,KAAK,EAAE,IAAI,EAAE,CAAA;AAC/C,CAAC;AAED,0CAA0C;AAC1C,MAAM,UAAU,iBAAiB,CAC7B,SAAiB,EACjB,cAAc,GAAiB,QAAQ,EACvC,KAAK,GAAY,KAAK,EACtB,QAAQ,GAAY,QAAQ;IAE5B,MAAM,EAAE,MAAM,EAAE,KAAK,EAAE,GAAG,eAAe,CAAC,SAAS,CAAC,CAAA;IAEpD,IAAI,cAAc,KAAK,SAAS,EAAE,CAAC;QAC/B,uCAAuC;QACvC,OAAO,CAAC,EAAE,OAAO,EAAE,KAAK,EAAE,IAAI,EAAE,CAAC,IAAI,EAAE,OAAO,EAAE,EAAE,EAAE,MAAM,CAAC,EAAE,CAAC,CAAA;IAClE,CAAC;IAED,IAAI,cAAc,KAAK,OAAO,EAAE,CAAC;QAC7B,OAAO,CAAC,EAAE,OAAO,EAAE,MAAM,EAAE,IAAI,EAAE,CAAC,MAAM,CAAC,EAAE,CAAC,CAAA;IAChD,CAAC;IAED,IAAI,cAAc,KAAK,SAAS,EAAE,CAAC;QAC/B,MAAM,UAAU,GAAkB,EAAE,CAAA;QACpC,IAAI,QAAQ,EAAE,CAAC;YACX,UAAU,CAAC,IAAI,CAAC,EAAE,OAAO,EAAE,aAAa,EAAE,IAAI,EAAE,CAAC,MAAM,CAAC,EAAE,CAAC,CAAA;QAC/D,CAAC;QACD,UAAU,CAAC,IAAI,CAAC,EAAE,OAAO,EAAE,UAAU,EAAE,IAAI,EAAE,CAAC,MAAM,CAAC,EAAE,CAAC,CAAA;QACxD,sCAAsC;QACtC,IAAI,KAAK,EAAE,CAAC;YACR,UAAU,CAAC,IAAI,CAAC;gBACZ,OAAO,EAAE,IAAI;gBACb,IAAI,EAAE,CAAC,OAAO,EAAE,IAAI,EAAE,4BAA4B,EAAE,IAAI,EAAE,MAAM,CAAC;aACpE,CAAC,CAAA;QACN,CAAC;QACD,OAAO,UAAU,CAAA;IACrB,CAAC;IAED,MAAM,UAAU,GAAkB,EAAE,CAAA;IACpC,IAAI,KAAK,EAAE,CAAC;QACR,sDAAsD;QACtD,UAAU,CAAC,IAAI,CAAC,EAAE,OAAO,EAAE,SAAS,EAAE,IAAI,EAAE,CAAC,MAAM,CAAC,EAAE,CAAC,CAAA;QACvD,UAAU,CAAC,IAAI,CAAC,EAAE,OAAO,EAAE,cAAc,EAAE,IAAI,EAAE,CAAC,MAAM,CAAC,EAAE,CAAC,CAAA;IAChE,CAAC;IACD,UAAU,CAAC,IAAI,CAAC,EAAE,OAAO,EAAE,UAAU,EAAE,IAAI,EAAE,CAAC,MAAM,CAAC,EAAE,CAAC,CAAA;IACxD,UAAU,CAAC,IAAI,CAAC,EAAE,OAAO,EAAE,KAAK,EAAE,IAAI,EAAE,CAAC,MAAM,EAAE,MAAM,CAAC,EAAE,CAAC,CAAA;IAC3D,OAAO,UAAU,CAAA;AACrB,CAAC;AAED,SAAS,aAAa,CAAC,OAAe,EAAE,IAAuB;IAC3D,OAAO,IAAI,OAAO,CAAO,CAAC,OAAO,EAAE,MAAM,EAAE,EAAE;QACzC,MAAM,KAAK,GAAG,KAAK,CAAC,OAAO,EAAE,CAAC,GAAG,IAAI,CAAC,EAAE;YACpC,QAAQ,EAAE,IAAI;YACd,KAAK,EAAE,QAAQ;YACf,WAAW,EAAE,IAAI;SACpB,CAAC,CAAA;QACF,KAAK,CAAC,IAAI,CAAC,OAAO,EAAE,MAAM,CAAC,CAAA;QAC3B,KAAK,CAAC,IAAI,CAAC,OAAO,EAAE,GAAG,EAAE;YACrB,wBAAwB;YACxB,KAAK,CAAC,KAAK,EAAE,CAAA;YACb,OAAO,EAAE,CAAA;QACb,CAAC,CAAC,CAAA;IACN,CAAC,CAAC,CAAA;AACN,CAAC;AAED,2BAA2B;AAC3B,MAAM,CAAC,KAAK,UAAU,YAAY,CAAC,SAAiB;IAChD,MAAM,EAAE,MAAM,EAAE,GAAG,eAAe,CAAC,SAAS,CAAC,CAAA;IAC7C,MAAM,QAAQ,GAAa,EAAE,CAAA;IAE7B,KAAK,MAAM,SAAS,IAAI,iBAAiB,CAAC,MAAM,CAAC,EAAE,CAAC;QAChD,IAAI,CAAC;YACD,MAAM,aAAa,CAAC,SAAS,CAAC,OAAO,EAAE,SAAS,CAAC,IAAI,CAAC,CAAA;YACtD,OAAM;QACV,CAAC;QAAC,OAAO,KAAK,EAAE,CAAC;YACb,QAAQ,CAAC,IAAI,CAAC,GAAG,SAAS,CAAC,OAAO,KAAK,aAAa,CAAC,KAAK,CAAC,EAAE,CAAC,CAAA;QAClE,CAAC;IACL,CAAC;IAED,MAAM,IAAI,KAAK,CAAC,QAAQ,MAAM,QAAQ,QAAQ,CAAC,IAAI,CAAC,GAAG,CAAC,EAAE,CAAC,CAAA;AAC/D,CAAC"}

package/dist/platform/os.d.ts

@@ -0,0 +1,20 @@
+/** 业务侧平台名，不使用 Node 的 win32 / darwin / linux 原始值 */
+export type PlatformName = "windows" | "macos" | "linux" | "android";
+/** 平台归一化。参数可注入，供测试覆盖各平台 */
+export declare function detectPlatform(nodePlatform?: NodeJS.Platform, env?: NodeJS.ProcessEnv): PlatformName;
+export declare const platform: PlatformName;
+export declare const isWindows: boolean;
+export declare const isMacOS: boolean;
+export declare const isLinux: boolean;
+export declare const isAndroid: boolean;
+/** POSIX 权限与路径语义可用的平台，含 Android */
+export declare const isPosix: boolean;
+export declare const isWsl: boolean;
+/** Android 上的 Termux 用户态 */
+export declare const isTermux: boolean;
+/** 读取环境变量，空串按未设置处理。Windows 下变量名大小写不敏感 */
+export declare function readEnv(name: string, env?: NodeJS.ProcessEnv): string | undefined;
+/** HOME 优先，其次 USERPROFILE 与系统用户目录；Android 沙箱可能三者皆无 */
+export declare function homeDir(env?: NodeJS.ProcessEnv): string;
+/** Windows 可执行文件带 .exe 后缀 */
+export declare function executableName(name: string): string;

package/dist/platform/os.js

@@ -0,0 +1,86 @@
+/*
+ * 平台识别。
+ * 本模块是唯一读取 process.platform 的位置。
+ */
+import { homedir } from "node:os";
+/** Termux 等 Android 用户态 Node 报告 linux，用 Android 环境变量识别 */
+function isAndroidEnv(env) {
+    const has = (name) => {
+        const value = env[name];
+        return value !== undefined && value.trim() !== "";
+    };
+    return has("ANDROID_ROOT") || has("ANDROID_DATA") || has("TERMUX_VERSION");
+}
+/** 平台归一化。参数可注入，供测试覆盖各平台 */
+export function detectPlatform(nodePlatform = process.platform, env = process.env) {
+    switch (nodePlatform) {
+        case "win32":
+            return "windows";
+        case "darwin":
+            return "macos";
+        case "android":
+            return "android";
+        default:
+            return isAndroidEnv(env) ? "android" : "linux";
+    }
+}
+export const platform = detectPlatform();
+export const isWindows = platform === "windows";
+export const isMacOS = platform === "macos";
+export const isLinux = platform === "linux";
+export const isAndroid = platform === "android";
+/** POSIX 权限与路径语义可用的平台，含 Android */
+export const isPosix = platform !== "windows";
+function detectWsl() {
+    if (platform !== "linux") {
+        return false;
+    }
+    // WSL 会注入 WSL_DISTRO_NAME / WSL_INTEROP，该环境下调用外部程序的行为与原生 Linux 不同
+    return process.env["WSL_DISTRO_NAME"] !== undefined || process.env["WSL_INTEROP"] !== undefined;
+}
+export const isWsl = detectWsl();
+/** Android 上的 Termux 用户态 */
+export const isTermux = isAndroid &&
+    (readEnv("TERMUX_VERSION") !== undefined ||
+        (readEnv("PREFIX")?.includes("com.termux") ?? false));
+/** 读取环境变量，空串按未设置处理。Windows 下变量名大小写不敏感 */
+export function readEnv(name, env = process.env) {
+    const direct = env[name];
+    if (direct !== undefined) {
+        const value = direct.trim();
+        return value === "" ? undefined : value;
+    }
+    if (!isWindows) {
+        return undefined;
+    }
+    // Windows 环境变量名不区分大小写
+    const lower = name.toLowerCase();
+    const key = Object.keys(env).find((item) => item.toLowerCase() === lower);
+    const value = key === undefined ? undefined : env[key]?.trim();
+    return value === undefined || value === "" ? undefined : value;
+}
+/** HOME 优先，其次 USERPROFILE 与系统用户目录；Android 沙箱可能三者皆无 */
+export function homeDir(env = process.env) {
+    const fromEnv = readEnv("HOME", env) ?? readEnv("USERPROFILE", env);
+    if (fromEnv !== undefined) {
+        return fromEnv;
+    }
+    try {
+        const home = homedir();
+        if (home !== "") {
+            return home;
+        }
+    }
+    catch {
+        // 无 passwd 条目时回落
+    }
+    return process.cwd();
+}
+/** Windows 可执行文件带 .exe 后缀 */
+export function executableName(name) {
+    if (!isWindows || name.toLowerCase().endsWith(".exe")) {
+        return name;
+    }
+    return `${name}.exe`;
+}
+//# sourceMappingURL=os.js.map

package/dist/platform/os.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"os.js","sourceRoot":"","sources":["../../src/platform/os.ts"],"names":[],"mappings":"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"}

package/dist/platform/path.d.ts

@@ -0,0 +1,32 @@
+import { type PlatformName } from "./os.js";
+/** 各平台统一使用的目录名 */
+export declare const APP_DIR_NAME = "wellspring";
+/** 四个根目录 */
+export interface PathRoots {
+    readonly configDir: string;
+    readonly dataDir: string;
+    readonly cacheDir: string;
+    readonly logDir: string;
+}
+/** 显式覆盖，通常来自 CLI 参数。相对路径按当前工作目录解析 */
+export interface PathOverrides {
+    readonly configDir?: string;
+    readonly dataDir?: string;
+    readonly cacheDir?: string;
+    readonly logDir?: string;
+}
+/** 取值来源，用于诊断 */
+export type PathSource = "override" | "env" | "portable-home" | "os-default";
+export interface ResolvedPaths extends PathRoots {
+    readonly sources: Readonly<Record<keyof PathRoots, PathSource>>;
+}
+/** 平台默认根目录。参数可注入，供测试覆盖各平台 */
+export declare function defaultRoots(platformName: PlatformName, env: NodeJS.ProcessEnv, home: string): PathRoots;
+/** 解析并缓存。重复调用会按最新参数与环境变量重新解析 */
+export declare function initPaths(overrides?: PathOverrides, env?: NodeJS.ProcessEnv): ResolvedPaths;
+/** 取缓存结果，未解析时先解析一次 */
+export declare function getPaths(): ResolvedPaths;
+/** 清空缓存，供测试使用。下次 getPaths 重新读取环境变量 */
+export declare function resetPaths(): void;
+/** 打印四个根目录及其来源，用于诊断 */
+export declare function describePaths(roots?: ResolvedPaths): string;

package/dist/platform/path.js

@@ -0,0 +1,154 @@
+/*
+ * 目录解析。
+ * 根目录：config（配置与凭据）、data（持久数据）、cache（可再生成）、log（日志）。
+ * 优先级：initPaths 显式覆盖 > WELLSPRING_*_DIR > WELLSPRING_HOME 便携模式 > 平台默认。
+ * 仅解析路径，不创建目录；创建见 file.ts 的 ensureDirs。
+ */
+import { isAbsolute, join, normalize } from "node:path";
+import { homeDir, platform, readEnv } from "./os.js";
+/** 各平台统一使用的目录名 */
+export const APP_DIR_NAME = "wellspring";
+const ROOT_KEYS = ["configDir", "dataDir", "cacheDir", "logDir"];
+const ENV_NAMES = {
+    configDir: "WELLSPRING_CONFIG_DIR",
+    dataDir: "WELLSPRING_DATA_DIR",
+    cacheDir: "WELLSPRING_CACHE_DIR",
+    logDir: "WELLSPRING_LOG_DIR",
+};
+const ROOT_LABELS = {
+    configDir: "config",
+    dataDir: "data",
+    cacheDir: "cache",
+    logDir: "log",
+};
+/** 是否 Termux 用户态：目录沿用 XDG，HOME 可用 */
+function isTermuxEnv(env) {
+    return (readEnv("TERMUX_VERSION", env) !== undefined ||
+        (readEnv("PREFIX", env)?.includes("com.termux") ?? false));
+}
+function xdgRoots(env, home) {
+    return {
+        configDir: join(readEnv("XDG_CONFIG_HOME", env) ?? join(home, ".config"), APP_DIR_NAME),
+        dataDir: join(readEnv("XDG_DATA_HOME", env) ?? join(home, ".local", "share"), APP_DIR_NAME),
+        cacheDir: join(readEnv("XDG_CACHE_HOME", env) ?? join(home, ".cache"), APP_DIR_NAME),
+        logDir: join(readEnv("XDG_STATE_HOME", env) ?? join(home, ".local", "state"), APP_DIR_NAME, "logs"),
+    };
+}
+/*
+ * Android 应用沙箱：HOME 通常指向应用私有 files 目录。
+ * 未设置 HOME 时依赖 WELLSPRING_HOME；两者皆无则使用系统用户目录。
+ */
+function androidAppRoots(env, home) {
+    const base = readEnv("HOME", env) ?? home;
+    return {
+        configDir: join(base, "config"),
+        dataDir: join(base, "data"),
+        cacheDir: join(base, "cache"),
+        logDir: join(base, "logs"),
+    };
+}
+/** 平台默认根目录。参数可注入，供测试覆盖各平台 */
+export function defaultRoots(platformName, env, home) {
+    switch (platformName) {
+        case "windows": {
+            const roaming = readEnv("APPDATA", env) ?? join(home, "AppData", "Roaming");
+            const local = readEnv("LOCALAPPDATA", env) ?? join(home, "AppData", "Local");
+            return {
+                configDir: join(roaming, APP_DIR_NAME),
+                dataDir: join(local, APP_DIR_NAME),
+                // Windows 无独立缓存目录约定，缓存与日志置于 data 下
+                cacheDir: join(local, APP_DIR_NAME, "cache"),
+                logDir: join(local, APP_DIR_NAME, "logs"),
+            };
+        }
+        case "macos": {
+            // macOS 惯例：配置与数据同放 Application Support，缓存与日志各自独立
+            const support = join(home, "Library", "Application Support", APP_DIR_NAME);
+            return {
+                configDir: support,
+                dataDir: support,
+                cacheDir: join(home, "Library", "Caches", APP_DIR_NAME),
+                logDir: join(home, "Library", "Logs", APP_DIR_NAME),
+            };
+        }
+        case "android":
+            return isTermuxEnv(env) ? xdgRoots(env, home) : androidAppRoots(env, home);
+        default:
+            return xdgRoots(env, home);
+    }
+}
+/** 便携模式：所有数据落在同一个根下 */
+function portableRoots(home) {
+    return {
+        configDir: join(home, "config"),
+        dataDir: join(home, "data"),
+        cacheDir: join(home, "cache"),
+        logDir: join(home, "logs"),
+    };
+}
+function expandTilde(input, env) {
+    if (input === "~") {
+        return homeDir(env);
+    }
+    if (input.startsWith("~/") || input.startsWith("~\\")) {
+        return join(homeDir(env), input.slice(2));
+    }
+    return input;
+}
+function toAbsolute(input, env) {
+    const expanded = expandTilde(input, env);
+    return normalize(isAbsolute(expanded) ? expanded : join(process.cwd(), expanded));
+}
+let cached = null;
+/** 解析并缓存。重复调用会按最新参数与环境变量重新解析 */
+export function initPaths(overrides = {}, env = process.env) {
+    const home = homeDir(env);
+    const portableHome = readEnv("WELLSPRING_HOME", env);
+    const defaults = portableHome === undefined
+        ? defaultRoots(platform, env, home)
+        : portableRoots(toAbsolute(portableHome, env));
+    const baseSource = portableHome === undefined ? "os-default" : "portable-home";
+    const roots = {
+        configDir: "",
+        dataDir: "",
+        cacheDir: "",
+        logDir: "",
+    };
+    const sources = {
+        configDir: baseSource,
+        dataDir: baseSource,
+        cacheDir: baseSource,
+        logDir: baseSource,
+    };
+    for (const key of ROOT_KEYS) {
+        const override = overrides[key];
+        if (override !== undefined && override.trim() !== "") {
+            roots[key] = toAbsolute(override, env);
+            sources[key] = "override";
+            continue;
+        }
+        const fromEnv = readEnv(ENV_NAMES[key], env);
+        if (fromEnv !== undefined) {
+            roots[key] = toAbsolute(fromEnv, env);
+            sources[key] = "env";
+            continue;
+        }
+        roots[key] = defaults[key];
+    }
+    const resolved = { ...roots, sources };
+    cached = resolved;
+    return resolved;
+}
+/** 取缓存结果，未解析时先解析一次 */
+export function getPaths() {
+    return cached ?? initPaths();
+}
+/** 清空缓存，供测试使用。下次 getPaths 重新读取环境变量 */
+export function resetPaths() {
+    cached = null;
+}
+/** 打印四个根目录及其来源，用于诊断 */
+export function describePaths(roots = getPaths()) {
+    return ROOT_KEYS.map((key) => `${ROOT_LABELS[key].padEnd(7)} ${roots[key]}  (${roots.sources[key]})`).join("\n");
+}
+//# sourceMappingURL=path.js.map

package/dist/platform/path.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"path.js","sourceRoot":"","sources":["../../src/platform/path.ts"],"names":[],"mappings":"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"}

package/dist/plugin/access-guard.d.ts

@@ -0,0 +1 @@
+export declare function ensureAccessGuard(): void;

package/dist/plugin/access-guard.js

@@ -0,0 +1,40 @@
+/*
+ * 插件访问守卫：插件加载/执行期间禁止直接 import 文件、进程等模块，
+ * 统一走宿主 API（api.fs / ctx.fs、api.logger 等）。
+ * 这是软隔离，无法阻止 plugin 通过 process.getBuiltinModule 等宿主逃逸。
+ */
+import { registerHooks } from "node:module";
+import { getHookOwner } from "../api/host/hooks.js";
+const BLOCKED = new Set([
+    "fs",
+    "node:fs",
+    "fs/promises",
+    "node:fs/promises",
+    "child_process",
+    "node:child_process",
+    "worker_threads",
+    "node:worker_threads",
+    "vm",
+    "node:vm",
+    "module",
+    "node:module",
+    "inspector",
+    "node:inspector",
+]);
+let installed = false;
+export function ensureAccessGuard() {
+    if (installed) {
+        return;
+    }
+    installed = true;
+    registerHooks({
+        resolve(specifier, context, nextResolve) {
+            const owner = getHookOwner();
+            if (owner !== null && BLOCKED.has(specifier)) {
+                throw new Error(`插件 ${owner} 禁止直接访问 ${specifier}，请使用 api.fs / ctx.fs 等宿主 API`);
+            }
+            return nextResolve(specifier, context);
+        },
+    });
+}
+//# sourceMappingURL=access-guard.js.map

package/dist/plugin/access-guard.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"access-guard.js","sourceRoot":"","sources":["../../src/plugin/access-guard.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAEH,OAAO,EAAE,aAAa,EAAE,MAAM,aAAa,CAAA;AAE3C,OAAO,EAAE,YAAY,EAAE,MAAM,sBAAsB,CAAA;AAEnD,MAAM,OAAO,GAAG,IAAI,GAAG,CAAC;IACpB,IAAI;IACJ,SAAS;IACT,aAAa;IACb,kBAAkB;IAClB,eAAe;IACf,oBAAoB;IACpB,gBAAgB;IAChB,qBAAqB;IACrB,IAAI;IACJ,SAAS;IACT,QAAQ;IACR,aAAa;IACb,WAAW;IACX,gBAAgB;CACnB,CAAC,CAAA;AAEF,IAAI,SAAS,GAAG,KAAK,CAAA;AAErB,MAAM,UAAU,iBAAiB;IAC7B,IAAI,SAAS,EAAE,CAAC;QACZ,OAAM;IACV,CAAC;IACD,SAAS,GAAG,IAAI,CAAA;IAChB,aAAa,CAAC;QACV,OAAO,CAAC,SAAS,EAAE,OAAO,EAAE,WAAW;YACnC,MAAM,KAAK,GAAG,YAAY,EAAE,CAAA;YAC5B,IAAI,KAAK,KAAK,IAAI,IAAI,OAAO,CAAC,GAAG,CAAC,SAAS,CAAC,EAAE,CAAC;gBAC3C,MAAM,IAAI,KAAK,CACX,MAAM,KAAK,WAAW,SAAS,8BAA8B,CAChE,CAAA;YACL,CAAC;YACD,OAAO,WAAW,CAAC,SAAS,EAAE,OAAO,CAAC,CAAA;QAC1C,CAAC;KACJ,CAAC,CAAA;AACN,CAAC"}

package/dist/plugin/agent-service.d.ts

@@ -0,0 +1,25 @@
+import type { HostAgentApi, HostAgentChatInput, HostAgentChatResult, HostWorkspaceFilesResult } from "../api/host/agent.js";
+import type { AppSetting } from "../config/types.js";
+import type { Logger } from "pino";
+import type { ResolvedPaths } from "../platform/path.js";
+import type { AgentToolRegistry } from "./agent-tools.js";
+import type { PluginRegistry } from "./registry.js";
+export interface HostAgentServiceOptions {
+    readonly settings: AppSetting;
+    readonly paths: ResolvedPaths;
+    readonly logger: Logger;
+    readonly registry: PluginRegistry;
+    readonly agentTools: AgentToolRegistry;
+    readonly cwd?: string;
+}
+export interface HostAgentService extends HostAgentApi {
+    chat(input: HostAgentChatInput): Promise<HostAgentChatResult>;
+}
+/**
+ * 在工作区里按文件名 / 路径搜索（广度优先，浅层条目优先进入扫描预算）。
+ * - query 为空或以 `/` 结尾且路径存在：只列该目录一层
+ * - 单关键字（`app`）：文件名优先，其次路径段 / 路径包含 / 子序列
+ * - 带斜杠（`assets/app`）：按路径段链式匹配，不要求前缀目录真实存在
+ */
+export declare function searchWorkspaceFiles(rootPath: string, query: string): Promise<HostWorkspaceFilesResult>;
+export declare function createHostAgentService(options: HostAgentServiceOptions): HostAgentService;