@xyit/wellspring 0.0.0-stage → 1.1.0

package/src/plugin/models-service.ts

@@ -0,0 +1,383 @@
+/*
+ * 宿主模型服务：给 sandbox 插件提供自定义供应商与模型切换。
+ *
+ * 配置写在 app-setting.json 的 models 节（每次调用实时读写，改完下一轮对话生效），
+ * 每个供应商的 Key 写在 credentials.json；状态只返回掩码。
+ */
+
+import type { Logger } from "pino"
+
+import type {
+    HostModelProvider,
+    HostModelProviderInput,
+    HostModelsApi,
+    HostModelsFetchResult,
+    HostModelsState,
+    HostModelsStateResult,
+} from "../api/host/models.ts"
+import { CONFIG_CODES } from "../config/codes.ts"
+import {
+    clearProviderApiKey,
+    credentialsFile,
+    normalizeApiKey,
+    providerKeyStatusSync,
+    saveProviderApiKey,
+} from "../config/credentials.ts"
+import { DEFAULT_SETTINGS } from "../config/defaults.ts"
+import { REASONING_LEVELS, type ReasoningLevel } from "../config/types.ts"
+import { loadSettings, saveSettings, SETTING_FILE_NAME } from "../config/loader.ts"
+import {
+    BUILTIN_PROVIDER_ID,
+    listModelProviders,
+    modelsSetting,
+    providerApiKey,
+} from "../config/providers.ts"
+import type { AppSetting, ModelProviderSetting } from "../config/types.ts"
+import { OpenAIClient } from "../network/openai.ts"
+import { createProxyFetch } from "../network/proxy.ts"
+
+export interface HostModelsServiceOptions {
+    readonly settings: AppSetting
+    /** app-setting.json 的绝对路径 */
+    readonly settingsFile: string
+    /** 凭据文件所在 config 目录 */
+    readonly configDir: string
+    readonly logger: Logger
+}
+
+export interface HostModelsService extends HostModelsApi {
+    state(): Promise<HostModelsState>
+}
+
+const PROVIDER_ID = /^[a-z0-9][a-z0-9._-]{0,31}$/
+const MAX_MODEL_CHARS = 120
+
+function normalizeModels(value: readonly string[] | undefined): string[] {
+    const models: string[] = []
+    for (const item of value ?? []) {
+        if (typeof item !== "string") {
+            continue
+        }
+        const model = item.trim()
+        if (model === "" || model.length > MAX_MODEL_CHARS || models.includes(model)) {
+            continue
+        }
+        models.push(model)
+    }
+    return models
+}
+
+function slugOf(name: string): string {
+    const slug = name
+        .toLowerCase()
+        .replace(/[^a-z0-9]+/g, "-")
+        .replace(/^-+|-+$/g, "")
+        .slice(0, 32)
+    return PROVIDER_ID.test(slug) ? slug : "provider"
+}
+
+function uniqueId(base: string, taken: ReadonlySet<string>): string {
+    if (!taken.has(base) && base !== BUILTIN_PROVIDER_ID) {
+        return base
+    }
+    for (let index = 2; index < 100; index += 1) {
+        const candidate = `${base}-${index}`
+        if (
+            !taken.has(candidate) &&
+            candidate !== BUILTIN_PROVIDER_ID &&
+            PROVIDER_ID.test(candidate)
+        ) {
+            return candidate
+        }
+    }
+    return `provider-${Date.now().toString(36)}`
+}
+
+export function createHostModelsService(options: HostModelsServiceOptions): HostModelsService {
+    const logger = options.logger.child({ module: "models" })
+    const settingsFile = options.settingsFile
+    const credentialsPath = credentialsFile(options.configDir)
+
+    const currentSettings = async (): Promise<AppSetting> => {
+        const loaded = await loadSettings(settingsFile)
+        return loaded.getData() ?? options.settings ?? DEFAULT_SETTINGS
+    }
+
+    const stateOf = (settings: AppSetting): HostModelsState => {
+        const models = modelsSetting(settings)
+        const providers: HostModelProvider[] = listModelProviders(settings).map((provider) => {
+            const key = providerKeyStatusSync(
+                { id: provider.id, apiKeyEnv: provider.apiKeyEnv },
+                credentialsPath,
+            )
+            return {
+                id: provider.id,
+                name: provider.name,
+                baseUrl: provider.baseUrl,
+                models: provider.models,
+                defaultModel: provider.defaultModel,
+                apiKeyEnv: provider.apiKeyEnv,
+                builtin: provider.builtin,
+                keyConfigured: key.configured,
+                keySource: key.source,
+                keyMasked: key.masked,
+                envVar: key.envVar,
+                keyStored: key.stored,
+            }
+        })
+        const activeProvider = providers.some((provider) => provider.id === models.activeProvider)
+            ? models.activeProvider
+            : BUILTIN_PROVIDER_ID
+        return {
+            providers,
+            activeProvider,
+            activeModel: models.activeModel,
+            activeReasoning: models.activeReasoning,
+            reasoningLevels: REASONING_LEVELS,
+        }
+    }
+
+    const saveProviderConfig = async (
+        settings: AppSetting,
+        provider: ModelProviderSetting,
+    ): Promise<HostModelsStateResult> => {
+        const models = modelsSetting(settings)
+        const providers = [...models.providers]
+        const index = providers.findIndex((item) => item.id === provider.id)
+        if (index === -1) {
+            if (providers.length >= 20) {
+                return { ok: false, code: "models.too-many-providers", state: stateOf(settings) }
+            }
+            providers.push(provider)
+        } else {
+            providers[index] = provider
+        }
+        const next: AppSetting = {
+            ...settings,
+            models: { ...models, providers },
+        }
+        const saved = await saveSettings(next, settingsFile)
+        if (!saved.isSuccess()) {
+            return {
+                ok: false,
+                code: saved.getCode() ?? CONFIG_CODES.invalid,
+                state: stateOf(settings),
+            }
+        }
+        return { ok: true, state: stateOf(next) }
+    }
+
+    const fail = async (code: string): Promise<HostModelsStateResult> => ({
+        ok: false,
+        code,
+        state: stateOf(await currentSettings()),
+    })
+
+    return {
+        async state(): Promise<HostModelsState> {
+            return stateOf(await currentSettings())
+        },
+
+        async setActive(
+            providerId: string,
+            model: string | null,
+            reasoning?: string | null,
+        ): Promise<HostModelsState> {
+            const settings = await currentSettings()
+            const models = modelsSetting(settings)
+            const id = providerId.trim()
+            const exists = listModelProviders(settings).some((provider) => provider.id === id)
+            if (!exists) {
+                throw new Error("models.provider-not-found")
+            }
+            const nextModel = typeof model === "string" && model.trim() !== "" ? model.trim() : null
+            if (nextModel !== null && nextModel.length > MAX_MODEL_CHARS) {
+                throw new Error("models.invalid-model")
+            }
+            const nextReasoning =
+                typeof reasoning === "string" && reasoning.trim() !== ""
+                    ? reasoning.trim()
+                    : models.activeReasoning
+            if (!(REASONING_LEVELS as readonly string[]).includes(nextReasoning)) {
+                throw new Error("models.invalid-reasoning")
+            }
+            const next: AppSetting = {
+                ...settings,
+                models: {
+                    ...models,
+                    activeProvider: id,
+                    activeModel: nextModel,
+                    activeReasoning: nextReasoning as ReasoningLevel,
+                },
+            }
+            const saved = await saveSettings(next, settingsFile)
+            if (!saved.isSuccess()) {
+                throw new Error(saved.getCode() ?? CONFIG_CODES.invalid)
+            }
+            logger.info({ provider: id, model: nextModel, reasoning: nextReasoning }, "切换模型")
+            return stateOf(next)
+        },
+
+        async saveProvider(input: HostModelProviderInput): Promise<HostModelsStateResult> {
+            const settings = await currentSettings()
+            const models = modelsSetting(settings)
+            const name = typeof input.name === "string" ? input.name.trim() : ""
+            if (name === "" || name.length > 60) {
+                return await fail(CONFIG_CODES.invalid)
+            }
+            const explicitId =
+                typeof input.id === "string" && input.id.trim() !== "" ? input.id.trim() : ""
+            const taken = new Set(models.providers.map((provider) => provider.id))
+            let id = explicitId
+            if (id === "") {
+                id = uniqueId(slugOf(name), taken)
+            } else if (!PROVIDER_ID.test(id) || id === BUILTIN_PROVIDER_ID) {
+                return await fail(CONFIG_CODES.invalid)
+            }
+            const apiKey =
+                typeof input.apiKey === "string" && input.apiKey.trim() !== ""
+                    ? normalizeApiKey(input.apiKey)
+                    : null
+            if (typeof input.apiKey === "string" && input.apiKey.trim() !== "" && apiKey === null) {
+                return { ok: false, code: CONFIG_CODES.invalidApiKey, state: stateOf(settings) }
+            }
+            const rawBaseUrl = input.baseUrl
+            const baseUrl =
+                typeof rawBaseUrl === "string" && rawBaseUrl.trim() !== ""
+                    ? rawBaseUrl.trim()
+                    : null
+            const provider: ModelProviderSetting = {
+                id,
+                name,
+                baseUrl,
+                models: normalizeModels(input.models),
+                defaultModel:
+                    typeof input.defaultModel === "string" && input.defaultModel.trim() !== ""
+                        ? input.defaultModel.trim()
+                        : null,
+                apiKeyEnv:
+                    typeof input.apiKeyEnv === "string" && input.apiKeyEnv.trim() !== ""
+                        ? input.apiKeyEnv.trim()
+                        : null,
+            }
+            const result = await saveProviderConfig(settings, provider)
+            if (!result.ok) {
+                return result
+            }
+            if (apiKey !== null) {
+                const keyed = await saveProviderApiKey(id, apiKey, credentialsPath)
+                if (!keyed.isSuccess()) {
+                    return await fail(keyed.getCode() ?? CONFIG_CODES.credentialsWriteFailed)
+                }
+            }
+            return { ok: true, state: stateOf(await currentSettings()) }
+        },
+
+        async removeProvider(id: string): Promise<HostModelsStateResult> {
+            const settings = await currentSettings()
+            const models = modelsSetting(settings)
+            if (id === BUILTIN_PROVIDER_ID) {
+                return await fail("models.builtin-provider")
+            }
+            const providers = models.providers.filter((provider) => provider.id !== id)
+            if (providers.length === models.providers.length) {
+                return await fail("models.provider-not-found")
+            }
+            const next: AppSetting = {
+                ...settings,
+                models: {
+                    ...models,
+                    providers,
+                    activeProvider:
+                        models.activeProvider === id ? BUILTIN_PROVIDER_ID : models.activeProvider,
+                    activeModel: models.activeProvider === id ? null : models.activeModel,
+                },
+            }
+            const saved = await saveSettings(next, settingsFile)
+            if (!saved.isSuccess()) {
+                return await fail(saved.getCode() ?? CONFIG_CODES.invalid)
+            }
+            await clearProviderApiKey(id, credentialsPath)
+            logger.info({ provider: id }, "删除自定义供应商")
+            return { ok: true, state: stateOf(next) }
+        },
+
+        async fetchModels(id: string, candidate?: string): Promise<HostModelsFetchResult> {
+            const settings = await currentSettings()
+            const provider = listModelProviders(settings).find((item) => item.id === id)
+            if (provider === undefined) {
+                return { ok: false, code: "models.provider-not-found" }
+            }
+            let apiKey: string | undefined
+            if (typeof candidate === "string" && candidate.trim() !== "") {
+                const normalized = normalizeApiKey(candidate)
+                if (normalized === null) {
+                    return { ok: false, code: CONFIG_CODES.invalidApiKey }
+                }
+                apiKey = normalized
+            } else {
+                apiKey = providerApiKey(provider, options.configDir) ?? undefined
+            }
+            if (apiKey === undefined) {
+                return { ok: false, code: "openai.missing-api-key" }
+            }
+            let proxyFetch: ReturnType<typeof createProxyFetch> | undefined
+            try {
+                proxyFetch = createProxyFetch(settings.network.proxy)
+            } catch {
+                proxyFetch = undefined
+            }
+            const created = OpenAIClient.create({
+                settings: {
+                    ...settings.openai,
+                    baseUrl: provider.baseUrl,
+                    model: provider.defaultModel ?? provider.models[0] ?? settings.openai.model,
+                },
+                apiKey,
+                credentialsFile: credentialsPath,
+                logger,
+                fetch: proxyFetch,
+            })
+            const client = created.getData()
+            if (!created.isSuccess() || client === null) {
+                return { ok: false, code: created.getCode() ?? "openai.missing-api-key" }
+            }
+            const listed = await client.listModels()
+            const data = listed.getData()
+            if (!listed.isSuccess() || data === null) {
+                return { ok: false, code: listed.getCode() ?? "openai.request-failed" }
+            }
+            return { ok: true, models: data }
+        },
+
+        async saveKey(id: string, apiKey: string): Promise<HostModelsStateResult> {
+            const settings = await currentSettings()
+            const exists = listModelProviders(settings).some((provider) => provider.id === id)
+            if (!exists) {
+                return await fail("models.provider-not-found")
+            }
+            const saved = await saveProviderApiKey(id, apiKey, credentialsPath)
+            if (!saved.isSuccess()) {
+                return {
+                    ok: false,
+                    code: saved.getCode() ?? CONFIG_CODES.invalidApiKey,
+                    state: stateOf(settings),
+                }
+            }
+            return { ok: true, state: stateOf(settings) }
+        },
+
+        async clearKey(id: string): Promise<HostModelsState> {
+            const settings = await currentSettings()
+            const exists = listModelProviders(settings).some((provider) => provider.id === id)
+            if (!exists) {
+                throw new Error("models.provider-not-found")
+            }
+            const cleared = await clearProviderApiKey(id, credentialsPath)
+            if (!cleared.isSuccess()) {
+                throw new Error(cleared.getCode() ?? CONFIG_CODES.credentialsWriteFailed)
+            }
+            return stateOf(settings)
+        },
+    }
+}

package/src/plugin/network-service.ts

@@ -0,0 +1,102 @@
+/*
+ * 宿主网络配置服务：读写 app-setting.json 的 network.proxy。
+ *
+ * 只写这一个字段，其余配置原样保留；写入前经过 validateSettings，
+ * 非法 URL / noProxy 不会落盘。模型调用、拉模型、网页搜索每轮都会重新读配置，
+ * 所以保存后不需要重启服务，下一轮请求生效。
+ */
+
+import type { Logger } from "pino"
+
+import type { HostNetworkApi, HostNetworkResult, HostNetworkState } from "../api/host/network.ts"
+import { CONFIG_CODES, invalidCode } from "../config/codes.ts"
+import { loadSettings, saveSettings } from "../config/loader.ts"
+import type { AppSetting, ProxySetting } from "../config/types.ts"
+
+const MAX_NO_PROXY = 100
+const MAX_NO_PROXY_LENGTH = 256
+
+export interface HostNetworkServiceOptions {
+    /** 启动时的配置；配置文件不存在或读取失败时回退到它 */
+    readonly settings: AppSetting
+    readonly settingsFile: string
+    readonly logger?: Logger
+}
+
+function isHttpUrl(value: string): boolean {
+    try {
+        const url = new URL(value)
+        return url.protocol === "http:" || url.protocol === "https:"
+    } catch {
+        return false
+    }
+}
+
+/** 去空、去重、限长，避免把超大/空白的 noProxy 写进配置 */
+function normalizeNoProxy(values: readonly string[] | undefined): string[] {
+    const result: string[] = []
+    for (const raw of values ?? []) {
+        if (typeof raw !== "string") continue
+        const value = raw.trim()
+        if (value === "" || value.length > MAX_NO_PROXY_LENGTH) continue
+        if (result.includes(value)) continue
+        if (result.length >= MAX_NO_PROXY) break
+        result.push(value)
+    }
+    return result
+}
+
+export function createHostNetworkService(options: HostNetworkServiceOptions): HostNetworkApi {
+    const currentSettings = async (): Promise<AppSetting> => {
+        try {
+            const loaded = await loadSettings(options.settingsFile)
+            return loaded.getData() ?? options.settings
+        } catch {
+            return options.settings
+        }
+    }
+
+    const stateOf = (settings: AppSetting): HostNetworkState => ({
+        proxy: settings.network.proxy,
+    })
+
+    return {
+        async state(): Promise<HostNetworkState> {
+            return stateOf(await currentSettings())
+        },
+
+        async saveProxy(input): Promise<HostNetworkResult> {
+            const settings = await currentSettings()
+            const rawUrl = typeof input.url === "string" ? input.url.trim() : ""
+            if (rawUrl !== "" && !isHttpUrl(rawUrl)) {
+                return {
+                    ok: false,
+                    code: invalidCode("network.proxy.url"),
+                    state: stateOf(settings),
+                }
+            }
+            let proxy: ProxySetting | null = null
+            if (rawUrl !== "") {
+                proxy = {
+                    type: "http",
+                    url: rawUrl,
+                    noProxy: normalizeNoProxy(input.noProxy),
+                }
+            }
+            const next: AppSetting = { ...settings, network: { proxy } }
+            const saved = await saveSettings(next, options.settingsFile)
+            if (!saved.isSuccess()) {
+                return {
+                    ok: false,
+                    code: saved.getCode() ?? CONFIG_CODES.invalid,
+                    state: stateOf(settings),
+                }
+            }
+            options.logger?.info(
+                { proxy: proxy?.url ?? null, noProxy: proxy?.noProxy ?? [] },
+                proxy === null ? "已关闭 HTTP 代理" : "已更新 HTTP 代理",
+            )
+            return { ok: true, state: stateOf(next) }
+        },
+    }
+}

package/src/plugin/package-manager.ts

@@ -0,0 +1,214 @@
+/*
+ * 插件依赖安装：插件自己的 package.json 用 packageManager 字段声明包管理器。
+ *
+ * 只认白名单命令（npm / pnpm / yarn / bun），字段不会变成任意命令执行；
+ * 版本号只作声明，实际使用 PATH 里的同名命令（不安装新版本，也不走 corepack）。
+ */
+
+import { spawn } from "node:child_process"
+import { readdir } from "node:fs/promises"
+
+export type PluginPackageManagerName = "npm" | "pnpm" | "yarn" | "bun"
+
+export interface PluginPackageManager {
+    readonly name: PluginPackageManagerName
+    readonly version: string | null
+}
+
+export interface PluginPackageJsonLike {
+    readonly packageManager?: unknown
+    readonly dependencies?: Record<string, unknown> | null
+    readonly optionalDependencies?: Record<string, unknown> | null
+}
+
+export interface PluginDependencyInstallResult {
+    readonly manager: PluginPackageManager | null
+    readonly installed: boolean
+    readonly reason: string | null
+}
+
+interface ManagerCommand {
+    readonly binary: string
+    readonly args: readonly string[]
+}
+
+const MANAGERS: ReadonlyMap<PluginPackageManagerName, ManagerCommand> = new Map([
+    ["npm", { binary: "npm", args: ["install", "--no-audit", "--no-fund", "--omit=dev"] }],
+    ["pnpm", { binary: "pnpm", args: ["install", "--prod"] }],
+    ["yarn", { binary: "yarn", args: ["install", "--production"] }],
+    ["bun", { binary: "bun", args: ["install", "--production"] }],
+])
+
+const INSTALL_TIMEOUT_MS = 5 * 60 * 1000
+const MAX_OUTPUT_CHARS = 4000
+
+function isManagerName(value: string): value is PluginPackageManagerName {
+    return MANAGERS.has(value as PluginPackageManagerName)
+}
+
+/** 解析 "npm@11.20.0" / "pnpm" 这类声明；不合法返回 null */
+export function parsePackageManager(value: unknown): PluginPackageManager | null {
+    if (typeof value !== "string") {
+        return null
+    }
+    const trimmed = value.trim()
+    const match = /^([A-Za-z][A-Za-z0-9-]*)(?:@(.+))?$/.exec(trimmed)
+    if (match === null) {
+        return null
+    }
+    const name = (match[1] ?? "").toLowerCase()
+    if (!isManagerName(name)) {
+        return null
+    }
+    const version = match[2] ?? null
+    // 允许 corepack 常见的 "pnpm@10.0.0+sha512..." 形式
+    if (version !== null && !/^[0-9A-Za-z][0-9A-Za-z.+-]*$/.test(version)) {
+        return null
+    }
+    return { name, version }
+}
+
+/** 没声明 packageManager 时按 lockfile 推断，兼容旧插件 */
+export function lockfilePackageManager(files: readonly string[]): PluginPackageManager | null {
+    if (files.includes("pnpm-lock.yaml")) {
+        return { name: "pnpm", version: null }
+    }
+    if (files.includes("yarn.lock")) {
+        return { name: "yarn", version: null }
+    }
+    if (files.includes("bun.lockb") || files.includes("bun.lock")) {
+        return { name: "bun", version: null }
+    }
+    if (files.includes("package-lock.json")) {
+        return { name: "npm", version: null }
+    }
+    return null
+}
+
+export function hasPluginDependencies(pkg: PluginPackageJsonLike): boolean {
+    return (
+        Object.keys(pkg.dependencies ?? {}).length > 0 ||
+        Object.keys(pkg.optionalDependencies ?? {}).length > 0
+    )
+}
+
+/** 实际执行的命令；Windows 下 .cmd 需要 shell */
+export function pluginInstallCommand(manager: PluginPackageManager): {
+    readonly command: string
+    readonly args: readonly string[]
+} {
+    const spec = MANAGERS.get(manager.name)
+    if (spec === undefined) {
+        throw new Error(`不支持的包管理器：${manager.name}`)
+    }
+    const command = process.platform === "win32" ? `${spec.binary}.cmd` : spec.binary
+    return { command, args: spec.args }
+}
+
+export interface RunPackageInstallOptions {
+    readonly timeoutMs?: number
+}
+
+/** 在插件目录里执行包管理器安装；失败时抛出带输出尾部的错误 */
+export async function runPackageInstall(
+    directory: string,
+    manager: PluginPackageManager,
+    options: RunPackageInstallOptions = {},
+): Promise<void> {
+    const { command, args } = pluginInstallCommand(manager)
+    const timeoutMs = options.timeoutMs ?? INSTALL_TIMEOUT_MS
+    await new Promise<void>((resolvePromise, rejectPromise) => {
+        let output = ""
+        let settled = false
+        const append = (chunk: Buffer): void => {
+            if (output.length >= MAX_OUTPUT_CHARS) {
+                return
+            }
+            output += chunk.toString("utf8")
+        }
+        const child = spawn(command, [...args], {
+            cwd: directory,
+            env: process.env,
+            stdio: ["ignore", "pipe", "pipe"],
+            // Windows 的 npm.cmd / pnpm.cmd 必须经 shell 才能启动；args 都是固定白名单
+            shell: process.platform === "win32",
+        })
+        const timer = setTimeout(() => {
+            if (settled) return
+            settled = true
+            child.kill("SIGKILL")
+            rejectPromise(
+                new Error(`${manager.name} 安装依赖超时（${Math.round(timeoutMs / 1000)}s）`),
+            )
+        }, timeoutMs)
+        child.stdout?.on("data", append)
+        child.stderr?.on("data", append)
+        child.once("error", (error) => {
+            if (settled) return
+            settled = true
+            clearTimeout(timer)
+            rejectPromise(new Error(`无法运行 ${manager.name}：${error.message}`))
+        })
+        child.once("close", (code) => {
+            if (settled) return
+            settled = true
+            clearTimeout(timer)
+            if (code === 0) {
+                resolvePromise()
+                return
+            }
+            const tail = output.trim().slice(-MAX_OUTPUT_CHARS)
+            rejectPromise(
+                new Error(
+                    `${manager.name} 安装依赖失败（退出码 ${String(code)}）` +
+                        (tail === "" ? "" : `：${tail}`),
+                ),
+            )
+        })
+    })
+}
+
+export interface InstallPluginDependenciesOptions {
+    /** 插件目录里的文件名；默认读目录，用于 lockfile 推断 */
+    readonly files?: readonly string[]
+    /** 测试注入；默认 runPackageInstall */
+    readonly run?: typeof runPackageInstall
+    readonly timeoutMs?: number
+}
+
+/**
+ * 安装插件依赖。
+ *
+ * - 没有 dependencies / optionalDependencies：直接跳过
+ * - 有依赖但没有 packageManager：先用 lockfile 推断；仍没有则报错
+ *   （不允许猜 npm，避免在错误的目录里跑错包管理器）
+ */
+export async function installPluginDependencies(
+    directory: string,
+    pkg: PluginPackageJsonLike,
+    options: InstallPluginDependenciesOptions = {},
+): Promise<PluginDependencyInstallResult> {
+    if (!hasPluginDependencies(pkg)) {
+        return { manager: null, installed: false, reason: null }
+    }
+    const declared = parsePackageManager(pkg.packageManager)
+    if (declared === null && pkg.packageManager !== undefined) {
+        throw new Error(
+            'package.json 的 packageManager 不合法，支持 "npm@11"、"pnpm@10"、"yarn@1"、"bun@1"',
+        )
+    }
+    const files = options.files ?? (await readdir(directory).catch(() => []))
+    const manager = declared ?? lockfilePackageManager(files)
+    if (manager === null) {
+        throw new Error(
+            '插件声明了 dependencies，但 package.json 缺少 packageManager（例如 "npm@11.20.0"）',
+        )
+    }
+    const run = options.run ?? runPackageInstall
+    await run(directory, manager, { timeoutMs: options.timeoutMs ?? INSTALL_TIMEOUT_MS })
+    return { manager, installed: true, reason: null }
+}
+
+export function packageManagerLabel(manager: PluginPackageManager): string {
+    return manager.version === null ? manager.name : `${manager.name}@${manager.version}`
+}