@xyit/wellspring 0.0.0-stage → 1.1.0

package/src/plugin/agent-tools.ts

@@ -0,0 +1,43 @@
+// 插件 Agent 工具注册表
+
+import type { AgentTool } from "../api/host/plugin.ts"
+
+const TOOL_NAME = /^[a-z][a-z0-9_-]{1,63}$/
+
+export interface RegisteredAgentTool {
+    readonly pluginId: string
+    readonly tool: AgentTool
+}
+
+export class AgentToolRegistry {
+    readonly #tools = new Map<string, RegisteredAgentTool>()
+
+    register(pluginId: string, tool: AgentTool): void {
+        if (!TOOL_NAME.test(tool.name)) {
+            throw new Error(`Agent 工具名不合法：${tool.name}`)
+        }
+        if (this.#tools.has(tool.name)) {
+            throw new Error(`Agent 工具重名：${tool.name}`)
+        }
+        if (typeof tool.call !== "function") {
+            throw new Error(`Agent 工具缺少 call：${tool.name}`)
+        }
+        this.#tools.set(tool.name, { pluginId, tool })
+    }
+
+    list(): readonly RegisteredAgentTool[] {
+        return [...this.#tools.values()]
+    }
+
+    get(name: string): RegisteredAgentTool | undefined {
+        return this.#tools.get(name)
+    }
+
+    removePlugin(pluginId: string): void {
+        for (const [name, record] of this.#tools) {
+            if (record.pluginId === pluginId) {
+                this.#tools.delete(name)
+            }
+        }
+    }
+}

package/src/plugin/capabilities.ts

@@ -0,0 +1,240 @@
+// 插件可用的宿主能力：sandbox 代码执行与网络工具
+
+import type { Logger } from "pino"
+
+import { loadSettings } from "../config/loader.ts"
+import type { AppSetting } from "../config/types.ts"
+import { credentialsFile, resolveApiKeySync } from "../config/credentials.ts"
+import {
+    WEB_CODES,
+    createDeepSeekWebClient,
+    type WebFetchResult,
+    type WebSearchResult,
+} from "../network/web.ts"
+import { createProxyFetch } from "../network/proxy.ts"
+import type { ResolvedPaths } from "../platform/path.ts"
+import { SandboxManager } from "../sandbox/manager.ts"
+import type { AgentCodeRequest, AgentCodeResult, StopMode } from "../sandbox/types.ts"
+import { getAgentToolContext, type AgentToolContext } from "../agent/tool-context.ts"
+import {
+    queryTask,
+    registerBackgroundTask,
+    stopTask,
+    type AgentTaskInfo,
+} from "../agent/task-registry.ts"
+
+export interface HostCapabilities {
+    executeCode(
+        input: Omit<AgentCodeRequest, "workspaceDir">,
+        context?: AgentToolContext,
+    ): Promise<AgentCodeResult>
+    startBackgroundCode(
+        input: Omit<AgentCodeRequest, "workspaceDir">,
+        context?: AgentToolContext,
+    ): Promise<{ taskId: string; sandboxId: string }>
+    queryTask(taskId?: string): AgentTaskInfo | null
+    stopTask(taskId: string | undefined, mode: StopMode): boolean
+    webSearch(query: string, count?: number): Promise<readonly WebSearchResult[]>
+    webFetch(url: string): Promise<WebFetchResult>
+}
+
+export interface HostCapabilitiesOptions {
+    readonly config: AppSetting
+    readonly paths: ResolvedPaths
+    readonly logger: Logger
+    /** 配置文件路径；提供时每次联网工具调用都重读，网页里改的代理不需要重启 */
+    readonly settingsFile?: string
+}
+
+const ACCESS_RANK: Readonly<Record<string, number>> = {
+    "read-only": 0,
+    "workspace-write": 1,
+    "danger-full-access": 2,
+}
+
+export function createHostCapabilities(options: HostCapabilitiesOptions): HostCapabilities {
+    let manager: SandboxManager | null = null
+    let web: ReturnType<typeof createDeepSeekWebClient> | null = null
+    let webCacheKey: string | null = null
+
+    /** 联网工具用默认供应商（OpenAI/DeepSeek）的 Key：环境变量 > credentials.json */
+    const resolveWebApiKey = (): string | null =>
+        resolveApiKeySync(credentialsFile(options.paths.configDir))?.apiKey ?? null
+
+    /** 配置文件可能存在网页/CLI 运行中修改（Key、Base URL、代理）：每次调用重读 */
+    const currentConfig = async (): Promise<AppSetting> => {
+        if (options.settingsFile === undefined) return options.config
+        try {
+            const loaded = await loadSettings(options.settingsFile)
+            return loaded.getData() ?? options.config
+        } catch {
+            return options.config
+        }
+    }
+
+    /** Key / 代理 / Base URL 都可能在运行中变化，缓存按这些字段失效 */
+    const webClient = async (): Promise<ReturnType<typeof createDeepSeekWebClient>> => {
+        const config = await currentConfig()
+        const apiKey = resolveWebApiKey()
+        const proxy = config.network.proxy
+        const cacheKey = [
+            apiKey ?? "",
+            config.openai.baseUrl ?? "",
+            String(config.openai.timeoutMs),
+            proxy?.url ?? "",
+            (proxy?.noProxy ?? []).join(","),
+        ].join("|")
+        if (web === null || webCacheKey !== cacheKey) {
+            webCacheKey = cacheKey
+            web = createDeepSeekWebClient({
+                baseUrl: config.openai.baseUrl,
+                timeoutMs: config.openai.timeoutMs,
+                fetch: createProxyFetch(proxy) as typeof fetch | undefined,
+                ...(apiKey === null ? {} : { apiKey }),
+            })
+        }
+        return web
+    }
+
+    const webError = (code: string | null, action: string): Error => {
+        if (code === WEB_CODES.missingApiKey) {
+            return new Error(
+                "web.missing-api-key：联网工具缺少 API Key。设置环境变量 OPENAI_API_KEY，或运行 wellspring key set（网页：左下角「供应商」里填写该供应商的 Key）",
+            )
+        }
+        return new Error(code ?? `web.${action}-failed`)
+    }
+    const sandbox = (): SandboxManager => {
+        manager ??= new SandboxManager({
+            settings: options.config.sandbox,
+            paths: options.paths,
+            logger: options.logger,
+        })
+        return manager
+    }
+    const approve = async (
+        input: Omit<AgentCodeRequest, "workspaceDir">,
+        context: AgentToolContext,
+        /** 调用方是 startAgentCode（后台任务）而不是 runAgentCode */
+        background = false,
+    ): Promise<{ access: NonNullable<AgentCodeRequest["access"]>; cwd: string }> => {
+        const current = context.permission
+        const requested = input.access ?? current
+        const cwd = input.cwd ?? context.workspaceDir
+        if ((ACCESS_RANK[requested] ?? 0) > (ACCESS_RANK[current] ?? 0)) {
+            const argv = input.argv ?? []
+            const stdin = typeof input.stdin === "string" ? input.stdin.trim() : ""
+            /*
+             * 参数逐个列出，而不是把 command 和 argv 拼成一行：
+             * 「bash -lc 'curl … | sh'」里危险的是参数边界，拼行会看不出引号归属。
+             */
+            context.elog.action("请求执行命令", [
+                { label: "command", value: input.command, code: true },
+                ...argv.map((arg, index) => ({
+                    label: `参数 ${index + 1}`,
+                    value: arg,
+                    code: true,
+                })),
+                { label: "工作目录", value: cwd },
+                { label: "权限", value: `${current} → ${requested}` },
+                ...(input.network === true ? [{ label: "网络", value: "请求联网" }] : []),
+                ...(background ? [{ label: "运行方式", value: "后台执行" }] : []),
+                ...(typeof input.timeoutMs === "number"
+                    ? [{ label: "超时", value: `${Math.round(input.timeoutMs / 1000)} 秒` }]
+                    : []),
+                ...(stdin === ""
+                    ? []
+                    : [
+                          {
+                              label: "标准输入",
+                              value: stdin.length > 200 ? `${stdin.slice(0, 200)}…` : stdin,
+                              code: true,
+                          },
+                      ]),
+            ])
+            let allowed = context.allowExec
+            if (!allowed && context.approveExec !== undefined) {
+                allowed = await context.approveExec({
+                    command: input.command,
+                    argv: input.argv ?? [],
+                    cwd,
+                    currentPermission: current,
+                    requestedPermission: requested,
+                    justification: input.justification,
+                    ...(input.network === true ? { network: true } : {}),
+                    ...(background ? { background: true } : {}),
+                    ...(typeof input.stdin === "string" && input.stdin !== ""
+                        ? { stdin: input.stdin }
+                        : {}),
+                    ...(typeof input.timeoutMs === "number" ? { timeoutMs: input.timeoutMs } : {}),
+                })
+            }
+            if (!allowed) {
+                throw new Error("工具执行被拒绝")
+            }
+            context.elog.toolResult("已允许提权")
+        }
+        return { access: requested, cwd }
+    }
+    return {
+        async executeCode(input, explicitContext) {
+            const context = explicitContext ?? getAgentToolContext()
+            if (context === null) {
+                throw new Error("executeCode 只能在 Agent 工具调用中使用")
+            }
+            const { access, cwd } = await approve(input, context)
+            const result = await sandbox().runAgentCode({
+                ...input,
+                cwd,
+                workspaceDir: context.workspaceDir,
+                access,
+            })
+            if (result.exitCode !== 0) {
+                context.elog.toolResult(`exit=${String(result.exitCode)}`)
+            }
+            return result
+        },
+        async startBackgroundCode(input, explicitContext) {
+            const context = explicitContext ?? getAgentToolContext()
+            if (context === null) {
+                throw new Error("startBackgroundCode 只能在 Agent 工具调用中使用")
+            }
+            const { access, cwd } = await approve(input, context, true)
+            const handle = await sandbox().startAgentCode({
+                ...input,
+                cwd,
+                workspaceDir: context.workspaceDir,
+                access,
+            })
+            const info = registerBackgroundTask(handle)
+            context.elog.toolResult(`后台任务 ${info.taskId}`)
+            return { taskId: info.taskId, sandboxId: info.sandboxId }
+        },
+        queryTask(taskId?: string) {
+            return queryTask(taskId)
+        },
+        stopTask(taskId: string | undefined, mode: StopMode) {
+            return stopTask(taskId, mode)
+        },
+        async webSearch(query, count) {
+            const client = await webClient()
+            const result = await client.search(query, count)
+            if (!result.isSuccess()) {
+                throw webError(result.getCode(), "search")
+            }
+            return result.getData() ?? []
+        },
+        async webFetch(url) {
+            const client = await webClient()
+            const result = await client.fetch(url)
+            if (!result.isSuccess()) {
+                throw webError(result.getCode(), "fetch")
+            }
+            const page = result.getData()
+            if (page === null) {
+                throw webError(null, "fetch")
+            }
+            return page
+        },
+    }
+}

package/src/plugin/console-guard.ts

@@ -0,0 +1,66 @@
+/*
+ * 插件 console 拦截。
+ * 插件内 console.* 不直接写终端：先记录一条 error，再按原方法级别输出原始消息。
+ * 拦截只覆盖插件 import / register / run 期间，结束后恢复。
+ */
+
+import { format } from "node:util"
+
+import type { Logger } from "pino"
+
+const METHODS = ["log", "info", "debug", "warn", "error", "trace", "dir", "table"] as const
+
+type GuardedMethod = (typeof METHODS)[number]
+
+const LEVEL_OF: Readonly<Record<GuardedMethod, "info" | "debug" | "warn" | "error" | "trace">> = {
+    log: "info",
+    info: "info",
+    debug: "debug",
+    warn: "warn",
+    error: "error",
+    trace: "trace",
+    dir: "info",
+    table: "info",
+}
+
+export async function withConsoleGuard<T>(
+    pluginName: string,
+    logger: Logger,
+    task: () => T | Promise<T>,
+): Promise<T> {
+    const target = console as unknown as Record<string, (...args: unknown[]) => void>
+    const originals = new Map<string, (...args: unknown[]) => void>()
+
+    const emit = (level: "info" | "debug" | "warn" | "error" | "trace", args: unknown[]): void => {
+        logger.error(`插件 [${pluginName}] 使用了不推荐的 console logger ！`)
+        const text = `${pluginName} ${format(...args)}`
+        logger[level](text)
+    }
+
+    for (const method of METHODS) {
+        const original = target[method]
+        if (typeof original !== "function") {
+            continue
+        }
+        originals.set(method, original)
+        target[method] = (...args: unknown[]): void => {
+            emit(LEVEL_OF[method], args)
+        }
+    }
+
+    const originalAssert = console.assert
+    console.assert = (condition: unknown, ...args: unknown[]): void => {
+        if (!condition) {
+            emit("error", args)
+        }
+    }
+
+    try {
+        return await task()
+    } finally {
+        for (const [method, original] of originals) {
+            target[method] = original
+        }
+        console.assert = originalAssert
+    }
+}

package/src/plugin/data-access.ts

@@ -0,0 +1,70 @@
+// 插件数据访问：依赖关系链上的插件可互访 data 目录
+
+import type { HostFileApi } from "../api/host/fs.ts"
+import type { ResolvedPaths } from "../platform/path.ts"
+import { createPluginFileApi } from "./fs.ts"
+import { ensurePluginDataDir } from "./runtime.ts"
+
+interface PluginNode {
+    readonly id: string
+    readonly deps: readonly string[]
+}
+
+export class PluginDataService {
+    readonly #paths: ResolvedPaths
+    readonly #edges = new Map<string, Set<string>>()
+
+    constructor(paths: ResolvedPaths) {
+        this.#paths = paths
+    }
+
+    /** 建立无向依赖图；A 依赖 B 后双方都可访问对方 data */
+    setPlugins(plugins: readonly PluginNode[]): void {
+        this.#edges.clear()
+        for (const plugin of plugins) {
+            this.#edges.set(plugin.id, this.#edges.get(plugin.id) ?? new Set())
+            for (const dep of plugin.deps) {
+                this.#link(plugin.id, dep)
+                this.#link(dep, plugin.id)
+            }
+        }
+    }
+
+    #link(left: string, right: string): void {
+        const set = this.#edges.get(left) ?? new Set<string>()
+        set.add(right)
+        this.#edges.set(left, set)
+    }
+
+    canAccess(from: string, to: string): boolean {
+        if (from === to) {
+            return true
+        }
+        const seen = new Set<string>([from])
+        const queue = [from]
+        while (queue.length > 0) {
+            const current = queue.shift()
+            if (current === undefined) {
+                break
+            }
+            for (const next of this.#edges.get(current) ?? []) {
+                if (next === to) {
+                    return true
+                }
+                if (!seen.has(next)) {
+                    seen.add(next)
+                    queue.push(next)
+                }
+            }
+        }
+        return false
+    }
+
+    async open(from: string, to: string): Promise<HostFileApi | null> {
+        if (!this.canAccess(from, to)) {
+            return null
+        }
+        const root = await ensurePluginDataDir(to, this.#paths)
+        return createPluginFileApi(root)
+    }
+}

package/src/plugin/fs.ts

@@ -0,0 +1,109 @@
+/*
+ * HostFileApi 实现：根目录内的相对路径访问。
+ */
+
+import { readdir } from "node:fs/promises"
+import { isAbsolute, resolve, sep } from "node:path"
+
+import type { HostFileApi, HostFileEntry, HostFileStat, HostFileType } from "../api/host/fs.ts"
+import {
+    ensureDir,
+    readBytesIfExists,
+    readJsonIfExists,
+    readTextIfExists,
+    removePath,
+    statIfExists,
+    writeBytesAtomic,
+    writeJsonAtomic,
+    writeTextAtomic,
+} from "../platform/file.ts"
+
+function safePath(root: string, relative: string): string {
+    if (typeof relative !== "string" || relative.includes("\0")) {
+        throw new Error("文件路径不合法")
+    }
+    if (isAbsolute(relative)) {
+        throw new Error(`不允许绝对路径：${relative}`)
+    }
+    const target = resolve(root, relative)
+    if (target !== root && !target.startsWith(`${root}${sep}`)) {
+        throw new Error(`路径越界：${relative}`)
+    }
+    return target
+}
+
+function fileTypeOf(isFile: boolean, isDirectory: boolean): HostFileType {
+    if (isFile) {
+        return "file"
+    }
+    if (isDirectory) {
+        return "directory"
+    }
+    return "other"
+}
+
+/** 为某个根目录创建 HostFileApi；root 需已存在或首次写入时自动创建 */
+export function createPluginFileApi(root: string): HostFileApi {
+    const base = resolve(root)
+
+    const api: HostFileApi = {
+        root: base,
+        async readText(path) {
+            return await readTextIfExists(safePath(base, path))
+        },
+        async readBytes(path) {
+            const bytes = await readBytesIfExists(safePath(base, path))
+            return bytes === null ? null : new Uint8Array(bytes)
+        },
+        async readJson<T = unknown>(path: string) {
+            return await readJsonIfExists<T>(safePath(base, path))
+        },
+        async writeText(path, text) {
+            await writeTextAtomic(safePath(base, path), text)
+        },
+        async writeBytes(path, bytes) {
+            await writeBytesAtomic(safePath(base, path), bytes)
+        },
+        async writeJson(path, value) {
+            await writeJsonAtomic(safePath(base, path), value)
+        },
+        async list(path = "") {
+            const dir = safePath(base, path)
+            const entries = await readdir(dir, { withFileTypes: true })
+            const result: HostFileEntry[] = []
+            for (const entry of entries) {
+                const info = await statIfExists(resolve(dir, entry.name))
+                result.push({
+                    name: entry.name,
+                    type: fileTypeOf(entry.isFile(), entry.isDirectory()),
+                    size: info?.size ?? 0,
+                    mtimeMs: info?.mtimeMs ?? 0,
+                })
+            }
+            result.sort((left, right) => left.name.localeCompare(right.name))
+            return result
+        },
+        async stat(path) {
+            const info = await statIfExists(safePath(base, path))
+            if (info === null) {
+                return null
+            }
+            const stat: HostFileStat = {
+                type: fileTypeOf(info.isFile(), info.isDirectory()),
+                size: info.size,
+                mtimeMs: info.mtimeMs,
+            }
+            return stat
+        },
+        async mkdir(path) {
+            await ensureDir(safePath(base, path))
+        },
+        async remove(path) {
+            await removePath(safePath(base, path))
+        },
+        async exists(path) {
+            return (await statIfExists(safePath(base, path))) !== null
+        },
+    }
+    return api
+}

package/src/plugin/host-alias.ts

@@ -0,0 +1,61 @@
+/*
+ * 插件侧模块别名。
+ * 插件不在 wellspring 包的解析路径内，用 Node 的 resolve hook 把
+ * "wellspring" / "wellspring/..." 映射到本仓库的 src 目录，
+ * 这样插件可以 import { onMessage, getHost } from "wellspring/api/host/index.ts"。
+ */
+
+import { statSync } from "node:fs"
+import { registerHooks } from "node:module"
+import { join, resolve } from "node:path"
+import { pathToFileURL } from "node:url"
+
+const PROJECT_ROOT = resolve(import.meta.dirname, "../..")
+const SOURCE_ROOT = join(PROJECT_ROOT, "src")
+const PREFIX = "wellspring/"
+
+let installed = false
+
+function existingFile(path: string): string | null {
+    try {
+        const info = statSync(path)
+        return info.isFile() ? path : null
+    } catch {
+        return null
+    }
+}
+
+function resolveHostTarget(specifier: string): string | null {
+    if (specifier === "wellspring") {
+        return existingFile(join(SOURCE_ROOT, "api", "host", "index.ts"))
+    }
+    if (!specifier.startsWith(PREFIX)) {
+        return null
+    }
+    const rest = specifier.slice(PREFIX.length)
+    if (rest === "" || rest.startsWith("..") || rest.startsWith("/") || rest.includes("\\")) {
+        return null
+    }
+    const direct = existingFile(join(SOURCE_ROOT, rest))
+    if (direct !== null) {
+        return direct
+    }
+    return existingFile(join(SOURCE_ROOT, rest, "index.ts"))
+}
+
+/** 注册一次即可；在加载插件前调用 */
+export function ensureHostAlias(): void {
+    if (installed) {
+        return
+    }
+    installed = true
+    registerHooks({
+        resolve(specifier, context, nextResolve) {
+            const target = resolveHostTarget(specifier)
+            if (target !== null) {
+                return { url: pathToFileURL(target).href, shortCircuit: true }
+            }
+            return nextResolve(specifier, context)
+        },
+    })
+}

package/src/plugin/index.ts

@@ -0,0 +1,11 @@
+/*
+ * 插件层入口。
+ */
+
+export * from "./console-guard.ts"
+export * from "./host-alias.ts"
+export * from "./install.ts"
+export * from "./loader.ts"
+export * from "./paths.ts"
+export * from "./registry.ts"
+export * from "./zip.ts"