@xyit/wellspring 0.0.0-stage → 1.1.0

package/src/event/event.ts

@@ -0,0 +1,171 @@
+/*
+ * EventEntity / EventBus
+ *
+ * EventEntity 的负载只读，取消状态可变：监听器对事件实例调 cancel 后
+ * isCancelled 立即为 true，EventBus 据此终止后续传播
+ * 取消不回滚已完成的投递
+ */
+
+export class EventEntity<T> {
+    private readonly data: T
+    private cancelled: boolean
+    private cancelReason: string
+
+    private constructor(data: T, cancelled = false, cancelReason = "") {
+        this.data = data
+        this.cancelled = cancelled
+        this.cancelReason = cancelReason
+    }
+
+    public static create<T>(data: T, cancelled = false, cancelReason = ""): EventEntity<T> {
+        return new EventEntity(data, cancelled, cancelReason)
+    }
+
+    public cancel(reason = ""): this {
+        this.cancelled = true
+        this.cancelReason = reason
+        return this
+    }
+
+    public getData(): T {
+        return this.data
+    }
+    public isCancelled(): boolean {
+        return this.cancelled
+    }
+    public getCancelReason(): string {
+        return this.cancelReason
+    }
+}
+
+import { getHostBridge } from "../sandbox/bridge-state.ts"
+
+export type EventListener<T = unknown> = (event: EventEntity<T>) => void
+
+// 存储层擦除负载类型：同一总线容纳各事件名的监听器
+type ListenerRecord = {
+    readonly fn: EventListener<any>
+    active: boolean
+}
+
+export class EventBus {
+    private readonly listeners = new Map<string, ListenerRecord[]>()
+    private readonly bridgeSubscriptions = new Set<string>()
+
+    subscribe<T>(eventName: string, listener: EventListener<T>): () => void {
+        if (typeof listener !== "function") {
+            throw new TypeError(`监听器不是函数：${eventName}`)
+        }
+        const record: ListenerRecord = { fn: listener, active: true }
+        const bridge = getHostBridge()
+        if (bridge !== null && !this.bridgeSubscriptions.has(eventName)) {
+            this.bridgeSubscriptions.add(eventName)
+            void bridge.request("host.event.subscribe", { name: eventName }).catch(() => undefined)
+        }
+        const handlers = this.listeners.get(eventName)
+        if (handlers) {
+            handlers.push(record)
+        } else {
+            this.listeners.set(eventName, [record])
+        }
+
+        return () => this.remove(eventName, record)
+    }
+
+    publish<T>(eventName: string, event: EventEntity<T>): void {
+        const bridge = getHostBridge()
+        if (bridge !== null) {
+            bridge.notify("host.event.publish", { name: eventName, data: event.getData() })
+            return
+        }
+        this.deliverLocal(eventName, event)
+    }
+
+    /** sandbox bridge 收到宿主事件后在本进程投递 */
+    receive<T>(eventName: string, data: T): void {
+        this.deliverLocal(eventName, EventEntity.create(data))
+    }
+
+    private deliverLocal<T>(eventName: string, event: EventEntity<T>): void {
+        const handlers = this.listeners.get(eventName)
+        if (!handlers || handlers.length === 0) {
+            return
+        }
+
+        let firstError: unknown
+        let failed = false
+        // 快照后校验存活状态：本轮回调内的退订对后续监听器生效
+        for (const record of handlers.slice()) {
+            if (!record.active) continue
+            if (event.isCancelled()) break
+            try {
+                record.fn(event)
+            } catch (error) {
+                // 单监听器异常不中断其余监听器，循环结束后抛出首个异常
+                if (!failed) {
+                    firstError = error
+                    failed = true
+                }
+            }
+        }
+        if (failed) {
+            throw firstError
+        }
+    }
+
+    once<T>(eventName: string, listener: EventListener<T>): () => void {
+        const unsubscribe = this.subscribe<T>(eventName, (event) => {
+            // 先退订再回调：回调内重入发布不会二次触发，回调抛错也不残留订阅
+            unsubscribe()
+            listener(event)
+        })
+        return unsubscribe
+    }
+
+    clear(eventName: string): void {
+        this.unsubscribeBridge(eventName)
+        const handlers = this.listeners.get(eventName)
+        if (!handlers) return
+        for (const record of handlers) {
+            record.active = false
+        }
+        this.listeners.delete(eventName)
+    }
+
+    clearAll(): void {
+        for (const eventName of [...this.bridgeSubscriptions]) {
+            this.unsubscribeBridge(eventName)
+        }
+        for (const handlers of this.listeners.values()) {
+            for (const record of handlers) {
+                record.active = false
+            }
+        }
+        this.listeners.clear()
+    }
+
+    private remove(eventName: string, record: ListenerRecord): void {
+        if (!record.active) return
+        record.active = false
+        const handlers = this.listeners.get(eventName)
+        if (!handlers) return
+        const index = handlers.indexOf(record)
+        if (index !== -1) {
+            handlers.splice(index, 1)
+        }
+        if (handlers.length === 0) {
+            this.listeners.delete(eventName)
+            this.unsubscribeBridge(eventName)
+        }
+    }
+
+    private unsubscribeBridge(eventName: string): void {
+        if (!this.bridgeSubscriptions.delete(eventName)) {
+            return
+        }
+        const bridge = getHostBridge()
+        bridge?.notify("host.event.unsubscribe", { name: eventName })
+    }
+}
+
+export const eventBus = new EventBus()

package/src/index.ts

@@ -0,0 +1,344 @@
+#!/usr/bin/env node
+/*
+ * Wellspring CLI 入口。
+ * 解析全局参数 → 应用目录/日志覆盖 → 加载配置与插件 → 分发命令。
+ */
+
+import { resolve } from "node:path"
+
+import type { HostOutput, PluginCommandContext } from "./api/host/plugin.ts"
+import { configureHost, setHostStatus } from "./api/host/host.ts"
+import { setHookErrorHandler, setHookGuard, withHookOwner } from "./api/host/hooks.ts"
+import { runConfigCommand } from "./commands/config.ts"
+import { runConversationCommand } from "./commands/conversation.ts"
+import { runDoctorCommand } from "./commands/doctor.ts"
+import { runHelpCommand } from "./commands/help.ts"
+import { runKeyCommand } from "./commands/key.ts"
+import { runPluginCommand } from "./commands/plugin.ts"
+import {
+    errorMessage,
+    exitCodeFor,
+    failure,
+    type CommandContext,
+    type CommandOutcome,
+} from "./commands/shared.ts"
+import { runSessionCommand } from "./commands/session.ts"
+import { runStartCommand } from "./commands/start.ts"
+import { runStopCommand } from "./commands/stop.ts"
+import { runVersionCommand } from "./commands/version.ts"
+import { credentialsFile } from "./config/credentials.ts"
+import {
+    activeModelProvider,
+    effectiveModel,
+    effectiveReasoning,
+    providerApiKey,
+    providerOpenAISettings,
+} from "./config/providers.ts"
+import { DEFAULT_SETTINGS } from "./config/defaults.ts"
+import { loadSettings, SETTING_FILE_NAME } from "./config/loader.ts"
+import type { AppSetting } from "./config/types.ts"
+import { BUILTIN_NAMES, findBuiltin } from "./input/commands.ts"
+import { parseGlobal } from "./input/parse.ts"
+import type { GlobalOptions } from "./input/types.ts"
+import { getElog, initElog } from "./logger/elog4js.ts"
+import { closeLogger, initLogger } from "./logger/logger.ts"
+import { initOpenAIClient, type OpenAIClient } from "./network/openai.ts"
+import { createProxyFetch } from "./network/proxy.ts"
+import { getPaths } from "./platform/path.ts"
+import { withConsoleGuard } from "./plugin/console-guard.ts"
+import { loadPlugins, type LoadedPlugin } from "./plugin/loader.ts"
+import { createPluginFileApi } from "./plugin/fs.ts"
+import { ensurePluginDataDir, loadPluginConfig } from "./plugin/runtime.ts"
+import { shutdownAllSandboxPlugins } from "./sandbox/plugin-client.ts"
+import { AgentToolRegistry } from "./plugin/agent-tools.ts"
+import { PluginRegistry } from "./plugin/registry.ts"
+
+function printParseError(code: string): void {
+    const elog = getElog()
+    elog.error(errorMessage(code))
+    elog.notice("运行 wellspring --help 查看用法")
+    process.exitCode = 2
+}
+
+function emitOutcome(outcome: CommandOutcome, json: boolean): void {
+    const code = outcome.result.getCode()
+    if (json) {
+        const payload = {
+            success: outcome.result.isSuccess(),
+            code: outcome.result.isSuccess() ? null : code,
+            data: outcome.result.isSuccess() ? outcome.result.getData() : null,
+        }
+        process.stdout.write(`${JSON.stringify(payload)}\n`)
+    } else if (!outcome.result.isSuccess() && code !== null) {
+        getElog().error(errorMessage(code))
+    }
+    process.exitCode = outcome.result.isSuccess() ? 0 : exitCodeFor(code)
+}
+
+function stripJsonFlag(argv: readonly string[]): { argv: string[]; json: boolean } {
+    const next = [...argv]
+    const marker = next.indexOf("--")
+    const limit = marker === -1 ? next.length : marker
+    for (let index = 0; index < limit; index += 1) {
+        if (next[index] === "--json") {
+            next.splice(index, 1)
+            return { argv: next, json: true }
+        }
+    }
+    return { argv: next, json: false }
+}
+
+function createPluginOutput(pluginName: string): HostOutput {
+    const elog = getElog()
+    return {
+        info: (text) => elog.plugin("info", pluginName, text),
+        warn: (text) => elog.plugin("warn", pluginName, text),
+        error: (text) => elog.plugin("error", pluginName, text),
+        print: (text = "") => elog.plugin("info", pluginName, text),
+    }
+}
+
+async function main(argv: readonly string[]): Promise<void> {
+    const parsed = parseGlobal(argv)
+    if (!parsed.isSuccess()) {
+        printParseError(parsed.getCode() ?? "usage.invalid-value")
+        return
+    }
+    const parsedGlobal = parsed.getData()
+    if (parsedGlobal === null) {
+        printParseError("usage.invalid-value")
+        return
+    }
+    const { options: globalOptions } = parsedGlobal
+    let command = parsedGlobal.command
+    let commandArgv = [...parsedGlobal.commandArgv]
+
+    if (globalOptions.version) {
+        command = "version"
+        commandArgv = []
+    }
+
+    const builtin = command === null ? undefined : findBuiltin(command)
+    const builtinName = builtin?.name ?? null
+    let jsonMode = globalOptions.json
+    if (builtinName !== null) {
+        const stripped = stripJsonFlag(commandArgv)
+        commandArgv = stripped.argv
+        jsonMode = jsonMode || stripped.json
+    }
+
+    const options: GlobalOptions = { ...globalOptions, json: jsonMode }
+
+    if (globalOptions.home !== undefined) {
+        process.env["WELLSPRING_HOME"] = globalOptions.home
+    }
+    const paths = getPaths()
+    configureHost({ paths })
+    setHostStatus("starting")
+    const settingsFile = resolve(globalOptions.config ?? `${paths.configDir}/${SETTING_FILE_NAME}`)
+
+    const loaded = await loadSettings(settingsFile)
+    const settings: AppSetting = loaded.getData() ?? DEFAULT_SETTINGS
+    const configCode = loaded.isSuccess() ? null : loaded.getCode()
+
+    initElog({ json: jsonMode })
+    const elog = getElog()
+
+    const logger = await initLogger({
+        settings,
+        level: globalOptions.logLevel ?? (globalOptions.quiet ? "silent" : undefined),
+        json: jsonMode,
+        stdout: false,
+    })
+    if (configCode !== null) {
+        logger.warn({ code: configCode }, "配置加载失败，使用默认配置")
+        elog.warn(`配置加载失败，使用默认配置：${errorMessage(configCode)}`)
+    }
+
+    setHookGuard(async (owner, task) => {
+        await withHookOwner(owner, async () => {
+            await withConsoleGuard(owner, logger.child({ plugin: owner }), task)
+        })
+    })
+
+    setHookErrorHandler(({ hook, owner, error }) => {
+        const message = error instanceof Error ? error.message : String(error)
+        logger.warn({ hook, owner, message }, "插件钩子执行失败")
+        elog.warn(`插件钩子执行失败：${hook}（${owner ?? "-"}）：${message}`)
+    })
+
+    let openai: OpenAIClient | null = null
+    let proxyFetch: ReturnType<typeof createProxyFetch>
+    try {
+        proxyFetch = createProxyFetch(settings.network.proxy)
+    } catch (error) {
+        const reason = error instanceof Error ? error.message : String(error)
+        logger.warn({ reason }, "代理初始化失败")
+        elog.warn(`代理初始化失败：${reason}`)
+        proxyFetch = undefined
+    }
+    // 当前供应商/模型：启动时解析一次，CLI 单轮命令直接用
+    const provider = activeModelProvider(settings)
+    const activeModel = effectiveModel(settings, provider)
+    const activeReasoning = effectiveReasoning(settings, provider)
+    const providerApiKeyValue = providerApiKey(provider, paths.configDir)
+    const openaiResult = initOpenAIClient({
+        settings: providerOpenAISettings(settings, provider),
+        apiKey: providerApiKeyValue ?? "",
+        credentialsFile: credentialsFile(paths.configDir),
+        logger: logger.child({ module: "openai" }),
+        fetch: proxyFetch,
+    })
+    if (openaiResult.isSuccess()) {
+        openai = openaiResult.getData()
+    } else {
+        logger.warn({ code: openaiResult.getCode() }, "OpenAI 客户端不可用")
+    }
+
+    const registry = new PluginRegistry()
+    const agentTools = new AgentToolRegistry()
+    let pluginsCache: readonly LoadedPlugin[] | null = null
+    const ensurePlugins = async (): Promise<readonly LoadedPlugin[]> => {
+        if (pluginsCache !== null) {
+            return pluginsCache
+        }
+        pluginsCache = await loadPlugins({
+            paths,
+            config: settings,
+            logger,
+            registry,
+            agentTools,
+            sandbox: settings.sandbox,
+        })
+        setHostStatus("running")
+        for (const plugin of pluginsCache) {
+            if (plugin.status === "failed") {
+                logger.warn({ plugin: plugin.name, error: plugin.error }, "插件加载失败")
+            }
+        }
+        return pluginsCache
+    }
+
+    const commandHelpRequested =
+        builtinName !== null && commandArgv.some((token) => token === "--help" || token === "-h")
+    const requested = commandHelpRequested ? builtinName : command
+    let commandName: string
+    if ((globalOptions.help || commandHelpRequested) && requested !== null) {
+        commandName = "help"
+        commandArgv = [requested]
+    } else {
+        commandName = requested ?? "help"
+    }
+
+    const ctx: CommandContext = {
+        global: options,
+        settings,
+        settingsFile,
+        configCode,
+        paths,
+        logger,
+        elog,
+        registry,
+        agentTools,
+        openai,
+        activeProvider: provider.id,
+        activeModel,
+        activeReasoning,
+        loadPlugins: ensurePlugins,
+    }
+
+    try {
+        // 钩子与插件命令都可能在任意命令里用到；version / key / plugin 不启动插件
+        // plugin 子命令只改文件，插件是否加载由下次运行决定
+        if (commandName !== "version" && commandName !== "key" && commandName !== "plugin") {
+            await ensurePlugins()
+        }
+        setHostStatus("running")
+
+        let outcome: CommandOutcome
+        switch (commandName) {
+            case "chat":
+                outcome = await runConversationCommand(ctx, commandArgv, "chat")
+                break
+            case "run":
+                outcome = await runConversationCommand(ctx, commandArgv, "run")
+                break
+            case "start":
+                outcome = await runStartCommand(ctx)
+                break
+            case "stop":
+                outcome = await runStopCommand(ctx)
+                break
+            case "session":
+                outcome = await runSessionCommand(ctx, commandArgv)
+                break
+            case "config":
+                outcome = await runConfigCommand(ctx, commandArgv)
+                break
+            case "plugin":
+                outcome = await runPluginCommand(ctx, commandArgv)
+                break
+            case "doctor":
+                outcome = await runDoctorCommand(ctx)
+                break
+            case "key":
+                outcome = await runKeyCommand(ctx, commandArgv)
+                break
+            case "version":
+                outcome = await runVersionCommand(ctx)
+                break
+            case "help":
+                outcome = await runHelpCommand(ctx, commandArgv)
+                break
+            default: {
+                const record = registry.resolve(commandName)
+                if (record === undefined) {
+                    outcome = failure(`usage.unknown-command:${commandName}`)
+                    break
+                }
+                const pluginLogger = logger.child({ plugin: record.pluginName })
+                try {
+                    const pluginDataDir = await ensurePluginDataDir(record.pluginName, paths)
+                    const pluginConfig = await loadPluginConfig(record.pluginName, paths)
+                    const pluginFs = createPluginFileApi(pluginDataDir)
+                    const workspaceFs = createPluginFileApi(process.cwd())
+                    const pluginContext: PluginCommandContext = {
+                        argv: commandArgv,
+                        env: process.env,
+                        paths,
+                        config: settings,
+                        logger: pluginLogger,
+                        output: createPluginOutput(record.pluginName),
+                        pluginDataDir,
+                        pluginConfig,
+                        fs: pluginFs,
+                        workspaceFs,
+                        cwd: process.cwd(),
+                        json: jsonMode,
+                        stdin: process.stdin,
+                        stdout: process.stdout,
+                        stderr: process.stderr,
+                    }
+                    const code = await withHookOwner(record.pluginName, async () =>
+                        withConsoleGuard(record.pluginName, pluginLogger, async () =>
+                            record.command.run(pluginContext),
+                        ),
+                    )
+                    process.exitCode = typeof code === "number" ? code : 0
+                    return
+                } catch (error) {
+                    const message = error instanceof Error ? error.message : String(error)
+                    logger.error({ plugin: record.pluginName, message }, "插件命令执行失败")
+                    outcome = failure(`plugin.command-failed:${message}`)
+                }
+            }
+        }
+        emitOutcome(outcome, jsonMode)
+    } finally {
+        setHostStatus("stopped")
+        await shutdownAllSandboxPlugins()
+        await closeLogger()
+    }
+}
+
+await main(process.argv.slice(2))

package/src/input/codes.ts

@@ -0,0 +1,21 @@
+/** 入参错误码，退出码统一为 2 */
+export const USAGE_CODES = {
+    unknownCommand: "usage.unknown-command",
+    unknownOption: "usage.unknown-option",
+    unknownSubcommand: "usage.unknown-subcommand",
+    missingValue: "usage.missing-value",
+    invalidValue: "usage.invalid-value",
+    missingContext: "usage.missing-context",
+    invalidSessionId: "usage.invalid-session-id",
+    unknownConfigKey: "usage.unknown-config-key",
+    conflictingOptions: "usage.conflicting-options",
+    missingConfirmation: "usage.missing-confirmation",
+} as const
+
+export function usageCode(code: string, detail?: string): string {
+    return detail === undefined || detail === "" ? code : `${code}:${detail}`
+}
+
+export function isUsageCode(code: string | null): boolean {
+    return code !== null && code.startsWith("usage.")
+}

package/src/input/commands.ts

@@ -0,0 +1,76 @@
+/** 内置命令元数据，帮助文本与命令校验共用这一份 */
+
+export interface BuiltinCommandSpec {
+    readonly name: string
+    readonly summary: string
+    readonly usage: string
+    readonly aliases?: readonly string[]
+}
+
+export const BUILTIN_COMMANDS: readonly BuiltinCommandSpec[] = [
+    {
+        name: "chat",
+        summary: "对话模式，单轮对话或进入交互式会话",
+        usage: "wellspring chat [--session-id <id>] [--new] [--model <name>] [--reasoning off|low|high|max] [--system <text>] <context...>",
+    },
+    {
+        name: "run",
+        summary: "Agent 模式，单轮执行或进入交互式会话",
+        usage: "wellspring run [--session-id <id>] [--new] [--agent <name>] [--model <name>] [--reasoning off|low|high|max] [--permission read-only|workspace-write|danger-full-access] [--allow-exec] [--max-steps <n>] <context...>",
+    },
+    {
+        name: "start",
+        summary: "以服务进程启动，加载插件并触发 onInit",
+        usage: "wellspring start",
+    },
+    {
+        name: "stop",
+        summary: "停止正在运行的 Wellspring 服务",
+        usage: "wellspring stop",
+    },
+    {
+        name: "session",
+        summary: "查看、切换与删除会话",
+        usage: "wellspring session <list|show|delete> [args]",
+    },
+    {
+        name: "config",
+        summary: "配置路径、查看与读写配置项",
+        usage: "wellspring config <path|show|get|set> [args]",
+    },
+    {
+        name: "key",
+        summary: "查看、设置、清除与测试 OpenAI API Key",
+        usage: "wellspring key <status|set|clear|test|path> [--provider <id>] [args]",
+    },
+    {
+        name: "plugin",
+        summary: "插件列表、安装与删除",
+        usage: "wellspring plugin <list|new|install|link|enable|disable|remove> [args]",
+    },
+    {
+        name: "doctor",
+        summary: "环境与配置诊断",
+        usage: "wellspring doctor [--json]",
+    },
+    {
+        name: "version",
+        summary: "显示版本与运行环境",
+        usage: "wellspring version [--json]",
+        aliases: ["-v"],
+    },
+    {
+        name: "help",
+        summary: "显示帮助",
+        usage: "wellspring help [command]",
+        aliases: ["-h"],
+    },
+]
+
+export const BUILTIN_NAMES: ReadonlySet<string> = new Set(BUILTIN_COMMANDS.map((spec) => spec.name))
+
+export function findBuiltin(name: string): BuiltinCommandSpec | undefined {
+    return BUILTIN_COMMANDS.find(
+        (spec) => spec.name === name || (spec.aliases ?? []).includes(name),
+    )
+}

package/src/input/help.ts

@@ -0,0 +1,60 @@
+/*
+ * 帮助文本生成。内置命令来自命令表，插件命令来自注册表。
+ */
+
+import { BUILTIN_COMMANDS, findBuiltin } from "./commands.ts"
+
+export interface HelpPluginCommand {
+    readonly name: string
+    readonly summary: string
+    readonly usage: string
+    readonly plugin: string
+}
+
+export function formatGlobalHelp(pluginCommands: readonly HelpPluginCommand[]): string {
+    const lines: string[] = []
+    lines.push("Wellspring 源泉 —— 聚合式 Agent 平台")
+    lines.push("")
+    lines.push("用法：wellspring <command> [args] [options]")
+    lines.push("")
+    lines.push("命令：")
+    for (const spec of BUILTIN_COMMANDS) {
+        lines.push(`  ${spec.name.padEnd(9)} ${spec.summary}`)
+    }
+    if (pluginCommands.length > 0) {
+        lines.push("")
+        lines.push("插件命令：")
+        for (const command of pluginCommands) {
+            lines.push(`  ${command.name.padEnd(9)} ${command.summary}（来自 ${command.plugin}）`)
+        }
+    }
+    lines.push("")
+    lines.push("全局参数：")
+    lines.push("  -c, --config <file>    指定配置文件")
+    lines.push("  --home <dir>           便携模式根目录")
+    lines.push("  -l, --log-level <level> 日志级别")
+    lines.push("  --json                 机器可读输出")
+    lines.push("  -q, --quiet            静默")
+    lines.push("  -h, --help             帮助")
+    lines.push("  -v, --version          版本")
+    lines.push("")
+    lines.push('示例：wellspring chat "解释一下 EventBus"')
+    lines.push('      wellspring run --session-id 20261021-173000-ab12 "读取 package.json"')
+    return lines.join("\n")
+}
+
+export function formatCommandHelp(name: string, pluginCommand?: HelpPluginCommand): string | null {
+    const spec = findBuiltin(name)
+    if (spec !== undefined) {
+        return [`用法：${spec.usage}`, "", spec.summary].join("\n")
+    }
+    if (pluginCommand !== undefined) {
+        return [
+            `用法：${pluginCommand.usage}`,
+            "",
+            pluginCommand.summary,
+            `来自插件：${pluginCommand.plugin}`,
+        ].join("\n")
+    }
+    return null
+}

package/src/input/index.ts

@@ -0,0 +1,10 @@
+/*
+ * 入参层入口。
+ */
+
+export * from "./codes.ts"
+export * from "./commands.ts"
+export * from "./help.ts"
+export * from "./parse-options.ts"
+export * from "./parse.ts"
+export * from "./types.ts"