@xyit/wellspring 0.0.0-stage → 1.1.0

package/src/network/web.ts

@@ -0,0 +1,206 @@
+/*
+ * DeepSeek 网页搜索与抓取 API
+ * Search POST /v1/tools/search
+ * Fetch  POST /v1/tools/fetch
+ */
+
+import { Result } from "../api/result/result.ts"
+import { readEnv } from "../platform/os.ts"
+
+export const WEB_CODES = {
+    missingApiKey: "web.missing-api-key",
+    invalidUrl: "web.invalid-url",
+    requestFailed: "web.request-failed",
+    searchFailed: "web.search-failed",
+    fetchFailed: "web.fetch-failed",
+    unsupported: "web.unsupported-provider",
+} as const
+
+export interface WebSearchResult {
+    readonly title: string
+    readonly url: string
+    readonly snippet: string
+    readonly summary: string
+    readonly content: string
+    readonly siteName: string | null
+    readonly date: string | null
+    readonly authority: number
+}
+
+export interface WebFetchResult {
+    readonly title: string
+    readonly content: string
+}
+
+export interface WebClient {
+    search(query: string, count?: number): Promise<Result<readonly WebSearchResult[]>>
+    fetch(url: string): Promise<Result<WebFetchResult>>
+}
+
+export interface WebClientOptions {
+    readonly baseUrl?: string | null
+    readonly apiKey?: string
+    readonly fetch?: typeof fetch
+    readonly timeoutMs?: number
+}
+
+function isObject(value: unknown): value is Record<string, unknown> {
+    return typeof value === "object" && value !== null && !Array.isArray(value)
+}
+
+function endpoint(baseUrl: string | null | undefined, path: string): string | null {
+    const base = (baseUrl ?? "https://api.deepseek.com").trim().replace(/\/+$/, "")
+    if (base === "") {
+        return null
+    }
+    const normalized = base.endsWith("/v1") ? base.slice(0, -3) : base
+    try {
+        return new URL(`${normalized}/v1/tools/${path}`).toString()
+    } catch {
+        return null
+    }
+}
+
+const RETRY_STATUSES = new Set([408, 429, 500, 502, 503, 504])
+
+function sleep(ms: number): Promise<void> {
+    return new Promise((resolve) => setTimeout(resolve, ms))
+}
+
+async function postJson(
+    url: string,
+    apiKey: string,
+    body: unknown,
+    fetchImpl: typeof fetch,
+    timeoutMs: number,
+): Promise<Result<unknown>> {
+    for (let attempt = 0; attempt < 2; attempt += 1) {
+        try {
+            const response = await fetchImpl(url, {
+                method: "POST",
+                headers: {
+                    Authorization: `Bearer ${apiKey}`,
+                    "Content-Type": "application/json",
+                },
+                body: JSON.stringify(body),
+                signal: AbortSignal.timeout(timeoutMs),
+            })
+            if (!response.ok) {
+                const code = `web.http-${response.status}`
+                if (RETRY_STATUSES.has(response.status) && attempt === 0) {
+                    await sleep(300)
+                    continue
+                }
+                return Result.error<unknown>(code)
+            }
+            return Result.successWithData<unknown>(await response.json())
+        } catch (error) {
+            const message = error instanceof Error ? error.message : String(error)
+            const code = `${WEB_CODES.requestFailed}:${message}`
+            if (attempt === 0) {
+                await sleep(300)
+                continue
+            }
+            return Result.error<unknown>(code)
+        }
+    }
+    return Result.error<unknown>(WEB_CODES.requestFailed)
+}
+
+// Markdown 转义清理：DeepSeek Fetch 会把所有 ASCII 标点转义成 `\.` / `\(` 之类
+const MARKDOWN_ESCAPES = /\\([!"#$%&'()*+,\-./:;<=>?@[\\\]^_`{|}~])/g
+
+function unescapeMarkdown(text: string): string {
+    return text.replace(MARKDOWN_ESCAPES, "$1")
+}
+
+function parseSearchResult(value: unknown): WebSearchResult | null {
+    if (!isObject(value) || typeof value["url"] !== "string") {
+        return null
+    }
+    return {
+        title: unescapeMarkdown(typeof value["title"] === "string" ? value["title"] : ""),
+        url: value["url"],
+        snippet: unescapeMarkdown(typeof value["snippet"] === "string" ? value["snippet"] : ""),
+        summary: unescapeMarkdown(typeof value["summary"] === "string" ? value["summary"] : ""),
+        content: unescapeMarkdown(typeof value["content"] === "string" ? value["content"] : ""),
+        siteName: typeof value["site_name"] === "string" ? value["site_name"] : null,
+        date: typeof value["date"] === "string" ? value["date"] : null,
+        authority: typeof value["authority"] === "number" ? value["authority"] : -1,
+    }
+}
+
+// HTTP/HTTPS 校验
+function validUrl(value: string): boolean {
+    try {
+        const url = new URL(value)
+        return (url.protocol === "http:" || url.protocol === "https:") && url.host !== ""
+    } catch {
+        return false
+    }
+}
+
+export function createDeepSeekWebClient(options: WebClientOptions = {}): WebClient {
+    const apiKey = options.apiKey ?? readEnv("OPENAI_API_KEY") ?? ""
+    const fetchImpl = options.fetch ?? fetch
+    const timeoutMs = options.timeoutMs ?? 60_000
+
+    return {
+        async search(query, count = 5) {
+            if (apiKey === "") {
+                return Result.error<readonly WebSearchResult[]>(WEB_CODES.missingApiKey)
+            }
+            const url = endpoint(options.baseUrl, "search")
+            if (url === null) {
+                return Result.error<readonly WebSearchResult[]>(WEB_CODES.unsupported)
+            }
+            const response = await postJson(
+                url,
+                apiKey,
+                { query, count: Math.max(1, Math.min(50, count)), need_content: false },
+                fetchImpl,
+                timeoutMs,
+            )
+            if (!response.isSuccess()) {
+                return Result.error<readonly WebSearchResult[]>(
+                    response.getCode() ?? WEB_CODES.searchFailed,
+                )
+            }
+            const data = response.getData()
+            const results = isObject(data) ? data["results"] : undefined
+            if (!Array.isArray(results)) {
+                return Result.error<readonly WebSearchResult[]>(WEB_CODES.searchFailed)
+            }
+            return Result.successWithData<readonly WebSearchResult[]>(
+                results
+                    .map(parseSearchResult)
+                    .filter((item): item is WebSearchResult => item !== null),
+            )
+        },
+
+        async fetch(targetUrl) {
+            if (apiKey === "") {
+                return Result.error<WebFetchResult>(WEB_CODES.missingApiKey)
+            }
+            if (!validUrl(targetUrl)) {
+                return Result.error<WebFetchResult>(WEB_CODES.invalidUrl)
+            }
+            const url = endpoint(options.baseUrl, "fetch")
+            if (url === null) {
+                return Result.error<WebFetchResult>(WEB_CODES.unsupported)
+            }
+            const response = await postJson(url, apiKey, { url: targetUrl }, fetchImpl, timeoutMs)
+            if (!response.isSuccess()) {
+                return Result.error<WebFetchResult>(response.getCode() ?? WEB_CODES.fetchFailed)
+            }
+            const data = response.getData()
+            if (!isObject(data) || typeof data["content"] !== "string") {
+                return Result.error<WebFetchResult>(WEB_CODES.fetchFailed)
+            }
+            return Result.successWithData<WebFetchResult>({
+                title: unescapeMarkdown(typeof data["title"] === "string" ? data["title"] : ""),
+                content: unescapeMarkdown(data["content"]),
+            })
+        },
+    }
+}

package/src/platform/clipboard.ts

@@ -0,0 +1,107 @@
+/*
+ * 剪贴板读写。
+ * 各平台通过系统命令实现；命令缺失或不可用时按候选顺序回退。
+ * Windows 的文本按 UTF-8 字节经 stdin/stdout 收发，避开控制台代码页。
+ */
+
+import { describeError, powershellArgs, runCommand, type RunCommandResult } from "./exec.ts"
+import { isTermux, platform, type PlatformName } from "./os.ts"
+
+export interface ClipboardCommand {
+    readonly command: string
+    readonly args: readonly string[]
+}
+
+export interface ClipboardCommands {
+    readonly write: readonly ClipboardCommand[]
+    readonly read: readonly ClipboardCommand[]
+}
+
+const POWERSHELL_WRITE = powershellArgs(
+    [
+        "$input = [Console]::OpenStandardInput()",
+        "$buffer = New-Object byte[] 8192",
+        "$memory = New-Object System.IO.MemoryStream",
+        "while (($read = $input.Read($buffer, 0, $buffer.Length)) -gt 0) { $memory.Write($buffer, 0, $read) }",
+        "Set-Clipboard -Value ([System.Text.Encoding]::UTF8.GetString($memory.ToArray()))",
+    ].join("\n"),
+)
+
+const POWERSHELL_READ = powershellArgs(
+    [
+        "$text = Get-Clipboard -Raw",
+        "if ($null -eq $text) { $text = '' }",
+        "$bytes = [System.Text.Encoding]::UTF8.GetBytes($text)",
+        "$output = [Console]::OpenStandardOutput()",
+        "$output.Write($bytes, 0, $bytes.Length)",
+        "$output.Flush()",
+    ].join("\n"),
+)
+
+/** 生成候选命令，按优先级排列。单独导出以便在任意平台测试 */
+export function buildClipboardCommands(
+    targetPlatform: PlatformName = platform,
+    inTermux: boolean = isTermux,
+): ClipboardCommands {
+    switch (targetPlatform) {
+        case "windows":
+            return {
+                write: [{ command: "powershell", args: POWERSHELL_WRITE }],
+                read: [{ command: "powershell", args: POWERSHELL_READ }],
+            }
+        case "macos":
+            return {
+                write: [{ command: "pbcopy", args: [] }],
+                read: [{ command: "pbpaste", args: [] }],
+            }
+        case "android":
+            // Android 应用沙箱内只有 Termux:API 提供的命令
+            if (!inTermux) {
+                return { write: [], read: [] }
+            }
+            return {
+                write: [{ command: "termux-clipboard-set", args: [] }],
+                read: [{ command: "termux-clipboard-get", args: [] }],
+            }
+        default:
+            return {
+                write: [
+                    { command: "wl-copy", args: [] },
+                    { command: "xclip", args: ["-selection", "clipboard"] },
+                    { command: "xsel", args: ["--clipboard", "--input"] },
+                ],
+                read: [
+                    { command: "wl-paste", args: [] },
+                    { command: "xclip", args: ["-selection", "clipboard", "-o"] },
+                    { command: "xsel", args: ["--clipboard", "--output"] },
+                ],
+            }
+    }
+}
+
+async function runCandidates(
+    commands: readonly ClipboardCommand[],
+    input?: string,
+): Promise<RunCommandResult> {
+    const failures: string[] = []
+    for (const candidate of commands) {
+        try {
+            return await runCommand(candidate.command, candidate.args, { input })
+        } catch (error) {
+            failures.push(`${candidate.command}: ${describeError(error)}`)
+        }
+    }
+    const detail = failures.length === 0 ? "当前平台没有可用命令" : failures.join("；")
+    throw new Error(`剪贴板不可用：${detail}`)
+}
+
+/** 写入剪贴板 */
+export async function writeClipboard(text: string): Promise<void> {
+    await runCandidates(buildClipboardCommands().write, text)
+}
+
+/** 读取剪贴板。返回命令的原始输出，不做换行裁剪 */
+export async function readClipboard(): Promise<string> {
+    const result = await runCandidates(buildClipboardCommands().read)
+    return result.stdout
+}

package/src/platform/exec.ts

@@ -0,0 +1,128 @@
+/*
+ * 命令执行。
+ * 命令缺失统一抛 CommandNotFoundError，供候选命令回退；stderr 有内容但退出码为 0 不算失败。
+ */
+
+import { spawn } from "node:child_process"
+
+const DEFAULT_TIMEOUT_MS = 15_000
+
+/** 命令不存在（ENOENT） */
+export class CommandNotFoundError extends Error {
+    readonly command: string
+
+    constructor(command: string) {
+        super(`命令不存在：${command}`)
+        this.name = "CommandNotFoundError"
+        this.command = command
+    }
+}
+
+/** 命令存在但退出码非 0 */
+export class CommandFailedError extends Error {
+    readonly command: string
+    readonly exitCode: number | null
+    readonly stderr: string
+
+    constructor(command: string, exitCode: number | null, stderr: string) {
+        const detail = stderr.trim()
+        super(
+            `命令执行失败：${command}（退出码 ${exitCode ?? "signal"}）${detail === "" ? "" : `：${detail}`}`,
+        )
+        this.name = "CommandFailedError"
+        this.command = command
+        this.exitCode = exitCode
+        this.stderr = stderr
+    }
+}
+
+export interface RunCommandOptions {
+    /** 写入 stdin 的文本 */
+    readonly input?: string
+    readonly env?: NodeJS.ProcessEnv
+    readonly timeoutMs?: number
+}
+
+export interface RunCommandResult {
+    readonly stdout: string
+    readonly stderr: string
+}
+
+/** 运行命令并收集输出 */
+export function runCommand(
+    command: string,
+    args: readonly string[] = [],
+    options: RunCommandOptions = {},
+): Promise<RunCommandResult> {
+    return new Promise((resolve, reject) => {
+        let settled = false
+        let timer: NodeJS.Timeout | undefined
+
+        const finish = (action: () => void): void => {
+            if (settled) {
+                return
+            }
+            settled = true
+            if (timer !== undefined) {
+                clearTimeout(timer)
+            }
+            action()
+        }
+
+        const child = spawn(command, [...args], {
+            env: options.env,
+            windowsHide: true,
+        })
+
+        let stdout = ""
+        let stderr = ""
+        child.stdout.setEncoding("utf8")
+        child.stderr.setEncoding("utf8")
+        child.stdout.on("data", (chunk: string) => {
+            stdout += chunk
+        })
+        child.stderr.on("data", (chunk: string) => {
+            stderr += chunk
+        })
+        // 命令未读取 stdin 就退出时写入会触发 EPIPE
+        child.stdin.on("error", () => undefined)
+
+        timer = setTimeout(() => {
+            child.kill("SIGKILL")
+            finish(() => reject(new Error(`命令执行超时：${command}`)))
+        }, options.timeoutMs ?? DEFAULT_TIMEOUT_MS)
+
+        child.once("error", (error) => {
+            if ((error as NodeJS.ErrnoException).code === "ENOENT") {
+                finish(() => reject(new CommandNotFoundError(command)))
+                return
+            }
+            finish(() => reject(error))
+        })
+
+        child.once("close", (code) => {
+            if (code === 0) {
+                finish(() => resolve({ stdout, stderr }))
+                return
+            }
+            finish(() => reject(new CommandFailedError(command, code, stderr)))
+        })
+
+        child.stdin.end(options.input)
+    })
+}
+
+/** PowerShell 脚本编码为 -EncodedCommand 参数，绕开 cmd 的引号与编码问题 */
+export function powershellArgs(script: string): string[] {
+    const encoded = Buffer.from(script, "utf16le").toString("base64")
+    return ["-NoProfile", "-NonInteractive", "-EncodedCommand", encoded]
+}
+
+/** 合并 message 与 cause 链，用于候选命令全失败时的报错 */
+export function describeError(error: unknown): string {
+    if (!(error instanceof Error)) {
+        return String(error)
+    }
+    const cause = error.cause
+    return cause === undefined ? error.message : `${error.message}（${describeError(cause)}）`
+}

package/src/platform/file.ts

@@ -0,0 +1,235 @@
+/*
+ * 文件落盘。
+ * 流程：临时文件 -> fsync -> rename -> chmod -> fsync 目录。
+ * Windows 不执行 chmod 与目录 fsync；rename 遇文件占用时短暂重试。
+ */
+
+import { randomUUID } from "node:crypto"
+import { closeSync, mkdirSync, openSync, type Stats } from "node:fs"
+import { chmod, mkdir, open, readFile, rename, rm, stat, unlink } from "node:fs/promises"
+import { basename, dirname, join } from "node:path"
+import { setTimeout as sleep } from "node:timers/promises"
+
+import { isWindows } from "./os.ts"
+import type { PathRoots } from "./path.ts"
+
+const FILE_MODE = 0o600
+const DIR_MODE = 0o700
+
+/** 是否为文件不存在（ENOENT） */
+export function isNotFound(error: unknown): boolean {
+    return (
+        typeof error === "object" &&
+        error !== null &&
+        (error as { code?: unknown }).code === "ENOENT"
+    )
+}
+
+/** 创建目录，默认权限 0700 */
+export async function ensureDir(dir: string, mode = DIR_MODE): Promise<void> {
+    await mkdir(dir, { recursive: true, mode })
+}
+
+/** 同步验证文件可写：创建父目录并打开目标，失败时抛出。用于需要提前确认的调用方 */
+export function assertWritableFile(file: string, mode = FILE_MODE): void {
+    mkdirSync(dirname(file), { recursive: true, mode: DIR_MODE })
+    const fd = openSync(file, "a", mode)
+    closeSync(fd)
+}
+
+/** 读取文本文件，不存在时返回 null */
+export async function readTextIfExists(file: string): Promise<string | null> {
+    try {
+        return await readFile(file, "utf8")
+    } catch (error) {
+        if (isNotFound(error)) {
+            return null
+        }
+        throw error
+    }
+}
+
+/** 读取二进制文件，不存在时返回 null */
+export async function readBytesIfExists(file: string): Promise<Buffer | null> {
+    try {
+        return await readFile(file)
+    } catch (error) {
+        if (isNotFound(error)) {
+            return null
+        }
+        throw error
+    }
+}
+
+/** stat，文件不存在时返回 null */
+export async function statIfExists(file: string): Promise<Stats | null> {
+    try {
+        return await stat(file)
+    } catch (error) {
+        if (isNotFound(error)) {
+            return null
+        }
+        throw error
+    }
+}
+
+/** 删除文件或目录，不存在时忽略 */
+export async function removePath(file: string): Promise<void> {
+    await rm(file, { recursive: true, force: true })
+}
+
+/** 读取 JSON 文件，不存在时返回 null。解析失败向上抛出 */
+export async function readJsonIfExists<T>(file: string): Promise<T | null> {
+    const text = await readTextIfExists(file)
+    return text === null ? null : (JSON.parse(text) as T)
+}
+
+export interface WriteFileOptions {
+    /** 文件权限，默认 0600 */
+    readonly mode?: number
+}
+
+/**
+ * 原子写。临时文件必须与目标文件同目录，跨分区 rename 不再具有原子性。
+ */
+export async function writeTextAtomic(
+    file: string,
+    text: string,
+    options: WriteFileOptions = {},
+): Promise<void> {
+    await writeBytesAtomic(file, Buffer.from(text, "utf8"), options)
+}
+
+/** 原子写二进制（会话的 zstd 段用） */
+export async function writeBytesAtomic(
+    file: string,
+    data: Uint8Array,
+    options: WriteFileOptions = {},
+): Promise<void> {
+    const dir = dirname(file)
+    const mode = options.mode ?? FILE_MODE
+    await ensureDir(dir)
+
+    const tmp = join(dir, `.${basename(file)}.tmp-${process.pid}-${randomUUID().slice(0, 8)}`)
+    const handle = await open(tmp, "w", mode)
+    try {
+        await handle.writeFile(data)
+        // 内容先落盘
+        await handle.sync()
+    } catch (error) {
+        await handle.close().catch(() => undefined)
+        await unlink(tmp).catch(() => undefined)
+        throw error
+    }
+    await handle.close()
+
+    try {
+        await renameWithRetry(tmp, file)
+    } catch (error) {
+        await unlink(tmp).catch(() => undefined)
+        throw error
+    }
+
+    if (!isWindows) {
+        // 部分文件系统 rename 后权限跟随临时文件，这里显式重设
+        await chmodQuiet(file, mode)
+    }
+    await syncDir(dir)
+}
+
+/** 原子写 JSON，固定 4 空格缩进并保留末尾换行 */
+export async function writeJsonAtomic(
+    file: string,
+    value: unknown,
+    options: WriteFileOptions & { readonly indent?: number } = {},
+): Promise<void> {
+    const text = `${JSON.stringify(value, null, options.indent ?? 4)}\n`
+    await writeTextAtomic(file, text, options)
+}
+
+/** 将损坏文件移到一边，返回移动后的位置 */
+export async function moveAside(file: string, suffix: string): Promise<string> {
+    const target = `${file}.${suffix}`
+    await rename(file, target)
+    return target
+}
+
+/** 备份与损坏文件用的时间戳，形如 20260919-013045 */
+export function timeStamp(date = new Date()): string {
+    const pad = (n: number): string => String(n).padStart(2, "0")
+    return (
+        `${date.getFullYear()}${pad(date.getMonth() + 1)}${pad(date.getDate())}` +
+        `-${pad(date.getHours())}${pad(date.getMinutes())}${pad(date.getSeconds())}`
+    )
+}
+
+/** 创建四个根目录。POSIX 下将已存在目录权限收紧至 0700 */
+export async function ensureDirs(roots: PathRoots, mode = DIR_MODE): Promise<void> {
+    for (const dir of [roots.configDir, roots.dataDir, roots.cacheDir, roots.logDir]) {
+        await ensureDir(dir, mode)
+        if (isWindows) {
+            continue
+        }
+        const info = await stat(dir)
+        if ((info.mode & 0o777) !== mode) {
+            await chmodQuiet(dir, mode)
+        }
+    }
+}
+
+/** Android 外部存储（FAT/exFAT）与部分挂载点不支持 chmod，权限收紧失败时继续 */
+const CHMOD_IGNORED_CODES = new Set(["EPERM", "EACCES", "EINVAL", "ENOTSUP", "ENOSYS"])
+
+const RENAME_RETRY_CODES = new Set(["EPERM", "EACCES", "EBUSY"])
+const RENAME_ATTEMPTS = 3
+
+function isRetryableRenameError(error: unknown): boolean {
+    if (typeof error !== "object" || error === null) {
+        return false
+    }
+    const code = (error as { code?: unknown }).code
+    return typeof code === "string" && RENAME_RETRY_CODES.has(code)
+}
+
+/** Windows 上杀毒软件与索引服务会短暂占用目标文件，rename 失败时重试 */
+async function renameWithRetry(from: string, to: string): Promise<void> {
+    const attempts = isWindows ? RENAME_ATTEMPTS : 1
+    for (let attempt = 1; ; attempt++) {
+        try {
+            await rename(from, to)
+            return
+        } catch (error) {
+            if (attempt >= attempts || !isRetryableRenameError(error)) {
+                throw error
+            }
+            await sleep(40 * attempt)
+        }
+    }
+}
+
+async function chmodQuiet(file: string, mode: number): Promise<void> {
+    try {
+        await chmod(file, mode)
+    } catch (error) {
+        const code = (error as { code?: unknown }).code
+        if (typeof code !== "string" || !CHMOD_IGNORED_CODES.has(code)) {
+            throw error
+        }
+    }
+}
+
+async function syncDir(dir: string): Promise<void> {
+    if (isWindows) {
+        return
+    }
+    try {
+        const handle = await open(dir, "r")
+        try {
+            await handle.sync()
+        } finally {
+            await handle.close()
+        }
+    } catch {
+        // 目录 fsync 失败时忽略
+    }
+}

package/src/platform/index.ts

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