@xyit/wellspring 0.0.0-stage → 1.1.0

package/src/config/credentials.ts

@@ -0,0 +1,302 @@
+/*
+ * API Key 凭据（支持多个模型供应商）。
+ *
+ * 与 app-setting.json 分开存放：配置文件可能被分享或进版本库，凭据单独放
+ * <configDir>/credentials.json，权限 0600。v2 结构按供应商分槽，v1 只有 openai 槽。
+ * 读取顺序：显式参数 > 供应商指定的环境变量（内置为 OPENAI_API_KEY）> 本地凭据。
+ * 明文只进请求，界面/日志一律用掩码。
+ */
+
+import { readFileSync } from "node:fs"
+import { join } from "node:path"
+
+import { Result } from "../api/result/result.ts"
+import { CONFIG_CODES } from "./codes.ts"
+import { readJsonIfExists, writeJsonAtomic } from "../platform/file.ts"
+import { readEnv } from "../platform/os.ts"
+import { getPaths } from "../platform/path.ts"
+
+/** 凭据文件在 config 根目录下的文件名 */
+export const CREDENTIALS_FILE_NAME = "credentials.json"
+
+/** 凭据文件结构版本；v2 增加 providers 分槽，v1 只认 openai */
+export const CREDENTIALS_VERSION = 2
+
+/** 单个 key 的长度上限，避免把异常输入写进文件 */
+export const MAX_API_KEY_CHARS = 4096
+
+/** 内置供应商的 id；它的 key 放在 openai 槽，兼容 v1 与 OPENAI_API_KEY */
+export const BUILTIN_PROVIDER_ID = "openai"
+
+/** 凭据文件结构；缺失的槽都视为没有 */
+interface CredentialsFile {
+    readonly version: number
+    readonly openai?: { readonly apiKey?: string | null } | null
+    readonly providers?: Readonly<Record<string, string | null>> | null
+}
+
+/** key 的来源：环境变量或本地凭据文件 */
+export type ApiKeySource = "env" | "credentials"
+
+export interface ResolvedApiKey {
+    readonly apiKey: string
+    readonly source: ApiKeySource
+}
+
+export interface ApiKeyStatus {
+    readonly configured: boolean
+    /** 当前生效来源；未配置为 null */
+    readonly source: ApiKeySource | null
+    /** 掩码后的 key，例如 `sk-…abcd`；未配置为 null */
+    readonly masked: string | null
+    /** 凭据文件路径，便于界面提示 */
+    readonly file: string
+    /** 环境变量是否设置（设置时优先于文件） */
+    readonly envOverride: boolean
+    /** 本地凭据文件里是否有 key（即使被环境变量覆盖也保留，便于界面提供清除） */
+    readonly stored: boolean
+}
+
+/** 单个供应商的 Key 状态 */
+export interface ProviderKeyStatus extends ApiKeyStatus {
+    /** 供应商自己的环境变量名；内置为 OPENAI_API_KEY */
+    readonly envVar: string | null
+}
+
+/** 供应商凭据来源描述（只用于解析，不含明文） */
+export interface ProviderKeyRef {
+    readonly id: string
+    readonly apiKeyEnv: string | null
+}
+
+/** 默认凭据路径；测试/多环境时可显式传 configDir */
+export function credentialsFile(configDir: string = getPaths().configDir): string {
+    return join(configDir, CREDENTIALS_FILE_NAME)
+}
+
+/** 列表展示用的掩码；短 key 直接全遮 */
+export function maskApiKey(apiKey: string): string {
+    const trimmed = apiKey.trim()
+    if (trimmed.length <= 8) {
+        return "••••"
+    }
+    const head = trimmed.slice(0, 3)
+    return `${head}…${trimmed.slice(-4)}`
+}
+
+/** 校验并规范化用户输入的 key；空白、含控制字符或超长都视为非法 */
+export function normalizeApiKey(raw: unknown): string | null {
+    if (typeof raw !== "string") {
+        return null
+    }
+    const trimmed = raw.trim()
+    if (trimmed === "" || trimmed.length > MAX_API_KEY_CHARS) {
+        return null
+    }
+    if (/[\s\u0000-\u001f\u007f]/.test(trimmed)) {
+        return null
+    }
+    return trimmed
+}
+
+function parseCredentials(value: unknown): CredentialsFile | null {
+    if (typeof value !== "object" || value === null || Array.isArray(value)) {
+        return null
+    }
+    const record = value as Record<string, unknown>
+    const openaiRaw = record["openai"]
+    const openai =
+        typeof openaiRaw === "object" && openaiRaw !== null
+            ? (openaiRaw as Record<string, unknown>)
+            : null
+    const providersRaw = record["providers"]
+    const providers: Record<string, string | null> = {}
+    if (typeof providersRaw === "object" && providersRaw !== null) {
+        for (const [id, raw] of Object.entries(providersRaw as Record<string, unknown>)) {
+            providers[id] = normalizeApiKey(raw)
+        }
+    }
+    return {
+        version: typeof record["version"] === "number" ? record["version"] : 1,
+        openai: openai === null ? null : { apiKey: normalizeApiKey(openai["apiKey"]) },
+        providers,
+    }
+}
+
+function readFileValue(file: string): CredentialsFile | null {
+    let text: string
+    try {
+        text = readFileSync(file, "utf8")
+    } catch {
+        return null
+    }
+    try {
+        return parseCredentials(JSON.parse(text))
+    } catch {
+        return null
+    }
+}
+
+async function readFileValueAsync(file: string): Promise<CredentialsFile | null> {
+    try {
+        return parseCredentials(await readJsonIfExists<unknown>(file))
+    } catch {
+        return null
+    }
+}
+
+function storedKey(value: CredentialsFile | null, providerId: string): string | null {
+    if (value === null) {
+        return null
+    }
+    if (providerId === BUILTIN_PROVIDER_ID) {
+        return normalizeApiKey(value.openai?.apiKey)
+    }
+    return normalizeApiKey(value.providers?.[providerId])
+}
+
+function envKey(provider: ProviderKeyRef): { apiKey: string; envVar: string } | null {
+    const envVar =
+        provider.apiKeyEnv ?? (provider.id === BUILTIN_PROVIDER_ID ? "OPENAI_API_KEY" : null)
+    if (envVar === null) {
+        return null
+    }
+    const raw = normalizeApiKey(readEnv(envVar))
+    return raw === null ? null : { apiKey: raw, envVar }
+}
+
+/** 某个供应商本地保存的 key（同步） */
+export function readProviderApiKeySync(
+    providerId: string,
+    file: string = credentialsFile(),
+): string | null {
+    return storedKey(readFileValue(file), providerId)
+}
+
+/** 某个供应商本地保存的 key（异步） */
+export async function readProviderApiKey(
+    providerId: string,
+    file: string = credentialsFile(),
+): Promise<string | null> {
+    return storedKey(await readFileValueAsync(file), providerId)
+}
+
+/** 默认（内置 openai）供应商本地保存的 key */
+export function readStoredApiKeySync(file: string = credentialsFile()): string | null {
+    return readProviderApiKeySync(BUILTIN_PROVIDER_ID, file)
+}
+
+export async function readStoredApiKey(file: string = credentialsFile()): Promise<string | null> {
+    return await readProviderApiKey(BUILTIN_PROVIDER_ID, file)
+}
+
+/** 解析某个供应商的 key：环境变量优先于本地凭据 */
+export function resolveProviderApiKeySync(
+    provider: ProviderKeyRef,
+    file: string = credentialsFile(),
+): ResolvedApiKey | null {
+    const fromEnv = envKey(provider)
+    if (fromEnv !== null) {
+        return { apiKey: fromEnv.apiKey, source: "env" }
+    }
+    const stored = readProviderApiKeySync(provider.id, file)
+    return stored === null ? null : { apiKey: stored, source: "credentials" }
+}
+
+/** 解析默认供应商的 key：OPENAI_API_KEY 优先于本地凭据 */
+export function resolveApiKeySync(file: string = credentialsFile()): ResolvedApiKey | null {
+    return resolveProviderApiKeySync({ id: BUILTIN_PROVIDER_ID, apiKeyEnv: null }, file)
+}
+
+/** 默认供应商的状态（CLI 与 API Key 弹窗用） */
+export function apiKeyStatusSync(file: string = credentialsFile()): ApiKeyStatus {
+    return providerKeyStatusSync({ id: BUILTIN_PROVIDER_ID, apiKeyEnv: null }, file)
+}
+
+/** 指定供应商的 Key 状态（掩码） */
+export function providerKeyStatusSync(
+    provider: ProviderKeyRef,
+    file: string = credentialsFile(),
+): ProviderKeyStatus {
+    const resolved = resolveProviderApiKeySync(provider, file)
+    const envVar =
+        provider.apiKeyEnv ?? (provider.id === BUILTIN_PROVIDER_ID ? "OPENAI_API_KEY" : null)
+    return {
+        configured: resolved !== null,
+        source: resolved?.source ?? null,
+        masked: resolved === null ? null : maskApiKey(resolved.apiKey),
+        file,
+        envOverride: envKey(provider) !== null,
+        stored: readProviderApiKeySync(provider.id, file) !== null,
+        envVar,
+    }
+}
+
+async function writeCredentials(file: string, value: CredentialsFile): Promise<Result<void>> {
+    try {
+        await writeJsonAtomic(file, value, { mode: 0o600 })
+    } catch {
+        return Result.error(CONFIG_CODES.credentialsWriteFailed)
+    }
+    return Result.success()
+}
+
+/** 保存某个供应商的 key；providerId=openai 时写内置槽 */
+export async function saveProviderApiKey(
+    providerId: string,
+    raw: unknown,
+    file: string = credentialsFile(),
+): Promise<Result<void>> {
+    const apiKey = normalizeApiKey(raw)
+    if (apiKey === null) {
+        return Result.error(CONFIG_CODES.invalidApiKey)
+    }
+    const current = readFileValue(file)
+    if (providerId === BUILTIN_PROVIDER_ID) {
+        return await writeCredentials(file, {
+            version: CREDENTIALS_VERSION,
+            openai: { apiKey },
+            providers: current?.providers ?? {},
+        })
+    }
+    return await writeCredentials(file, {
+        version: CREDENTIALS_VERSION,
+        openai: current?.openai ?? { apiKey: null },
+        providers: { ...(current?.providers ?? {}), [providerId]: apiKey },
+    })
+}
+
+/** 清除某个供应商的 key；内置槽清除后 OPENAI_API_KEY 仍可能生效 */
+export async function clearProviderApiKey(
+    providerId: string,
+    file: string = credentialsFile(),
+): Promise<Result<void>> {
+    const current = readFileValue(file)
+    if (providerId === BUILTIN_PROVIDER_ID) {
+        return await writeCredentials(file, {
+            version: CREDENTIALS_VERSION,
+            openai: { apiKey: null },
+            providers: current?.providers ?? {},
+        })
+    }
+    const providers: Record<string, string | null> = { ...(current?.providers ?? {}) }
+    delete providers[providerId]
+    return await writeCredentials(file, {
+        version: CREDENTIALS_VERSION,
+        openai: current?.openai ?? { apiKey: null },
+        providers,
+    })
+}
+
+/** 保存默认供应商的 key（兼容旧调用） */
+export async function saveStoredApiKey(
+    raw: unknown,
+    file: string = credentialsFile(),
+): Promise<Result<void>> {
+    return await saveProviderApiKey(BUILTIN_PROVIDER_ID, raw, file)
+}
+
+/** 清除默认供应商的本地 key（兼容旧调用） */
+export async function clearStoredApiKey(file: string = credentialsFile()): Promise<Result<void>> {
+    return await clearProviderApiKey(BUILTIN_PROVIDER_ID, file)
+}

package/src/config/defaults.ts

@@ -0,0 +1,32 @@
+import { SETTING_VERSION, type AppSetting, type ModelsSetting } from "./types.ts"
+
+/** 单供应商时代的默认模型设置；旧配置缺 models 时用它兜底 */
+export const DEFAULT_MODELS: ModelsSetting = Object.freeze({
+    providers: Object.freeze([]),
+    activeProvider: "openai",
+    activeModel: null,
+    activeReasoning: "off",
+})
+
+/** 缺省配置。缺文件或读取失败时作为回退 */
+export const DEFAULT_SETTINGS: AppSetting = Object.freeze({
+    version: SETTING_VERSION,
+    logger: Object.freeze({ level: "info" as const }),
+    openai: Object.freeze({
+        baseUrl: null,
+        model: "gpt-4o-mini",
+        timeoutMs: 60_000,
+        maxRetries: 2,
+    }),
+    models: DEFAULT_MODELS,
+    network: Object.freeze({ proxy: null }),
+    sandbox: Object.freeze({
+        mode: "strict" as const,
+        backend: "auto" as const,
+        access: "read-only" as const,
+        maxConcurrent: 2,
+        defaultTimeoutMs: 60_000,
+        defaultMemoryMB: 512,
+        outputLimitBytes: 16 * 1024 * 1024,
+    }),
+})

package/src/config/index.ts

@@ -0,0 +1,10 @@
+/*
+ * 配置层入口。
+ * 校验、默认值与读写；错误以 Result code 返回，不抛异常。
+ */
+
+export * from "./codes.ts"
+export * from "./defaults.ts"
+export * from "./loader.ts"
+export * from "./types.ts"
+export * from "./validate.ts"

package/src/config/loader.ts

@@ -0,0 +1,80 @@
+/*
+ * 配置读写。
+ * 默认路径为用户配置目录下的 app-setting.json；缺文件时写入默认值。
+ * 失败时 Result 的 code 说明原因，getData() 回退默认配置，供调用方决定是否继续启动。
+ */
+
+import { join } from "node:path"
+
+import { Result } from "../api/result/result.ts"
+import { readTextIfExists, writeJsonAtomic } from "../platform/file.ts"
+import { getPaths } from "../platform/path.ts"
+import { CONFIG_CODES } from "./codes.ts"
+import { DEFAULT_SETTINGS } from "./defaults.ts"
+import type { AppSetting } from "./types.ts"
+import { validateSettings } from "./validate.ts"
+
+/** 配置文件在 config 根目录下的文件名 */
+export const SETTING_FILE_NAME = "app-setting.json"
+
+/** 默认配置路径 */
+export function settingsFile(): string {
+    return join(getPaths().configDir, SETTING_FILE_NAME)
+}
+
+/** 读取配置。文件不存在时创建默认配置 */
+export async function loadSettings(file: string = settingsFile()): Promise<Result<AppSetting>> {
+    let text: string | null
+    try {
+        text = await readTextIfExists(file)
+    } catch {
+        return Result.errorWithData<AppSetting>(DEFAULT_SETTINGS, CONFIG_CODES.readFailed)
+    }
+
+    if (text === null) {
+        return await writeDefaults(file)
+    }
+
+    let parsed: unknown
+    try {
+        parsed = JSON.parse(text)
+    } catch {
+        // 损坏文件不覆盖，留给调用方决定是否备份
+        return Result.errorWithData<AppSetting>(DEFAULT_SETTINGS, CONFIG_CODES.parseFailed)
+    }
+
+    const validated = validateSettings(parsed)
+    if (!validated.isSuccess()) {
+        return Result.errorWithData<AppSetting>(
+            DEFAULT_SETTINGS,
+            validated.getCode() ?? CONFIG_CODES.invalid,
+        )
+    }
+    return validated
+}
+
+/** 校验后原子写回；字段不合法时不落盘 */
+export async function saveSettings(
+    settings: AppSetting,
+    file: string = settingsFile(),
+): Promise<Result<void>> {
+    const validated = validateSettings(settings)
+    if (!validated.isSuccess()) {
+        return Result.error(validated.getCode() ?? CONFIG_CODES.invalid)
+    }
+    try {
+        await writeJsonAtomic(file, validated.getData())
+    } catch {
+        return Result.error(CONFIG_CODES.writeFailed)
+    }
+    return Result.success()
+}
+
+async function writeDefaults(file: string): Promise<Result<AppSetting>> {
+    try {
+        await writeJsonAtomic(file, DEFAULT_SETTINGS)
+    } catch {
+        return Result.errorWithData<AppSetting>(DEFAULT_SETTINGS, CONFIG_CODES.writeFailed)
+    }
+    return Result.successWithData<AppSetting>(DEFAULT_SETTINGS)
+}

package/src/config/providers.ts

@@ -0,0 +1,133 @@
+/*
+ * 模型供应商与模型解析。
+ *
+ * 内置供应商 id 为 openai，由 app-setting.json 的 openai.* 描述；
+ * 自定义供应商来自 models.providers，接口都按 OpenAI 兼容处理（baseUrl + key）。
+ */
+
+import { BUILTIN_PROVIDER_ID, credentialsFile, resolveProviderApiKeySync } from "./credentials.ts"
+import { DEFAULT_MODELS } from "./defaults.ts"
+import type { AppSetting, ModelProviderSetting, ModelsSetting } from "./types.ts"
+
+export { BUILTIN_PROVIDER_ID }
+
+/** 解析后的供应商：内置项同样带 builtin 标记与可用的模型列表 */
+export interface ResolvedModelProvider extends ModelProviderSetting {
+    readonly builtin: boolean
+}
+
+/** 旧配置没有 models 节时用默认值 */
+export function modelsSetting(settings: AppSetting): ModelsSetting {
+    return settings.models ?? DEFAULT_MODELS
+}
+
+/** 供应商列表：内置 openai 永远排第一，自定义按配置顺序 */
+export function listModelProviders(settings: AppSetting): readonly ResolvedModelProvider[] {
+    const builtin: ResolvedModelProvider = {
+        id: BUILTIN_PROVIDER_ID,
+        name: settings.openai.baseUrl === null ? "OpenAI（默认）" : "默认供应商",
+        baseUrl: settings.openai.baseUrl,
+        models: [settings.openai.model],
+        defaultModel: settings.openai.model,
+        apiKeyEnv: "OPENAI_API_KEY",
+        builtin: true,
+    }
+    return [
+        builtin,
+        ...modelsSetting(settings).providers.map((provider) => ({ ...provider, builtin: false })),
+    ]
+}
+
+export function findModelProvider(settings: AppSetting, id: string): ResolvedModelProvider | null {
+    return listModelProviders(settings).find((provider) => provider.id === id) ?? null
+}
+
+/** 当前生效的供应商；配置里的 id 失效时退回内置 openai */
+export function activeModelProvider(settings: AppSetting): ResolvedModelProvider {
+    const active = findModelProvider(settings, modelsSetting(settings).activeProvider)
+    return active ?? listModelProviders(settings)[0]!
+}
+
+/**
+ * 某次请求实际使用的模型：
+ * 显式覆盖 > 全局 activeModel（仅当前供应商）> 供应商 defaultModel > 模型列表第一个 > 全局 openai.model
+ */
+export function effectiveModel(
+    settings: AppSetting,
+    provider: ResolvedModelProvider,
+    override?: string | null,
+): string {
+    const explicit = typeof override === "string" ? override.trim() : ""
+    if (explicit !== "") {
+        return explicit
+    }
+    const models = modelsSetting(settings)
+    if (provider.id === models.activeProvider && models.activeModel !== null) {
+        return models.activeModel
+    }
+    if (provider.defaultModel !== null && provider.defaultModel !== "") {
+        return provider.defaultModel
+    }
+    if (provider.models.length > 0) {
+        return provider.models[0]!
+    }
+    return settings.openai.model
+}
+
+/** 某次请求使用的供应商：请求里带了就用它，否则用全局当前供应商 */
+export function requestProvider(
+    settings: AppSetting,
+    providerId?: string | null,
+): ResolvedModelProvider {
+    const requested = typeof providerId === "string" ? providerId.trim() : ""
+    if (requested !== "") {
+        const found = findModelProvider(settings, requested)
+        if (found !== null) {
+            return found
+        }
+    }
+    return activeModelProvider(settings)
+}
+
+/**
+ * 某次请求的推理强度：
+ * 显式覆盖 > 全局 activeReasoning（仅当前供应商）> off
+ */
+export function effectiveReasoning(
+    settings: AppSetting,
+    provider: ResolvedModelProvider,
+    override?: string | null,
+): string {
+    const explicit = typeof override === "string" ? override.trim() : ""
+    if (explicit !== "") {
+        return explicit
+    }
+    const models = modelsSetting(settings)
+    if (provider.id === models.activeProvider) {
+        return models.activeReasoning
+    }
+    return "off"
+}
+
+/** 供应商对应的 OpenAI 设置（baseUrl + 实际模型） */
+export function providerOpenAISettings(
+    settings: AppSetting,
+    provider: ResolvedModelProvider,
+    model?: string | null,
+): AppSetting["openai"] {
+    return {
+        ...settings.openai,
+        baseUrl: provider.baseUrl,
+        model: effectiveModel(settings, provider, model),
+    }
+}
+
+/** 供应商的 key：环境变量优先，然后本地凭据；没有返回 null */
+export function providerApiKey(provider: ResolvedModelProvider, configDir: string): string | null {
+    return (
+        resolveProviderApiKeySync(
+            { id: provider.id, apiKeyEnv: provider.apiKeyEnv },
+            credentialsFile(configDir),
+        )?.apiKey ?? null
+    )
+}

package/src/config/types.ts

@@ -0,0 +1,88 @@
+import type { LevelWithSilent } from "pino"
+
+/** 配置文件结构版本，字段变更时递增并在 loader 中迁移 */
+export const SETTING_VERSION = 1
+
+export interface LoggerSetting {
+    readonly level: LevelWithSilent
+}
+
+export interface OpenAISetting {
+    /** 兼容网关地址；null 表示使用 SDK 默认值或 OPENAI_BASE_URL */
+    readonly baseUrl: string | null
+    readonly model: string
+    readonly timeoutMs: number
+    readonly maxRetries: number
+}
+
+/** 自定义模型供应商（OpenAI 兼容接口）；内置供应商 openai 由 openai.* 字段描述 */
+export interface ModelProviderSetting {
+    /** 供应商标识，1-32 位 [a-z0-9-_.]；不能叫 openai */
+    readonly id: string
+    readonly name: string
+    /** null 表示使用 SDK 默认地址 */
+    readonly baseUrl: string | null
+    /** 预置模型列表；可手动维护，也可从供应商接口拉取 */
+    readonly models: readonly string[]
+    /** 该供应商缺省模型；null 时取列表第一个或全局 openai.model */
+    readonly defaultModel: string | null
+    /** 可选：用这个环境变量提供该供应商的 API Key（优先级高于本地凭据） */
+    readonly apiKeyEnv: string | null
+}
+
+/** 推理强度；参考 Harness：off / low / high / max */
+export type ReasoningLevel = "off" | "low" | "high" | "max"
+
+export const REASONING_LEVELS: readonly ReasoningLevel[] = ["off", "low", "high", "max"]
+
+export interface ModelsSetting {
+    /** 自定义供应商；内置 openai 不在列表里 */
+    readonly providers: readonly ModelProviderSetting[]
+    /** 当前使用的供应商 id；openai 表示内置 */
+    readonly activeProvider: string
+    /** 当前使用的模型；null 表示用供应商缺省模型 */
+    readonly activeModel: string | null
+    /** 当前推理强度；off 表示不发推理参数 */
+    readonly activeReasoning: ReasoningLevel
+}
+
+/** 代理类型，一期只支持 http/https 代理 */
+export type ProxyType = "http"
+
+export interface ProxySetting {
+    readonly type: ProxyType
+    /** 代理地址，认证信息可写在 URL 里 */
+    readonly url: string
+    /** 不走代理的主机后缀，例如 example.com、.internal */
+    readonly noProxy: readonly string[]
+}
+
+export interface NetworkSetting {
+    /** null 表示直连 */
+    readonly proxy: ProxySetting | null
+}
+
+export type SandboxMode = "off" | "strict" | "best-effort"
+export type SandboxBackend = "auto" | "bwrap" | "nsjail"
+export type SandboxAccess = "read-only" | "workspace-write" | "danger-full-access"
+
+/** OS 级 sandbox 配置 */
+export interface SandboxSetting {
+    readonly mode: SandboxMode
+    readonly backend: SandboxBackend
+    readonly access: SandboxAccess
+    readonly maxConcurrent: number
+    readonly defaultTimeoutMs: number
+    readonly defaultMemoryMB: number
+    readonly outputLimitBytes: number
+}
+
+export interface AppSetting {
+    readonly version: number
+    readonly logger: LoggerSetting
+    readonly openai: OpenAISetting
+    /** 多供应商/模型设置；旧配置没有这一节时按默认值处理 */
+    readonly models?: ModelsSetting
+    readonly network: NetworkSetting
+    readonly sandbox: SandboxSetting
+}