@armadra/agent 0.2.1 → 0.3.0

package/dist/cli/subcommands/providers.js

@@ -0,0 +1,433 @@
+/**
+ * `ama providers add|list|channels|remove|refresh`（docs/providers.md「一键接入」「渠道」）。
+ *
+ * - add：只给 baseUrl 与 key，列出中转的模型（`GET /models`）、用 models.dev 补元数据、可选逐渠道
+ *   探测，把渠道与模型追加进用户级 config.json（先备份）；key 从 stdin 读（不回显）存 auth.json，
+ *   或 `--key-env VAR` 写 `"apiKey": "$VAR"`。对已存在的供应商只追加，不改已有条目。
+ * - refresh：重拉 `/models` 与 models.dev，只追加新模型；已下架的只提示。
+ * - list / channels：供应商 → 渠道 → 模型数与 key 来源（从不显示 key）。remove：删配置与 auth.json 条目。
+ *
+ * 计费：`--probe` 每模型每渠道一次最小请求；执行前打印预估，TTY 问 y/N，非 TTY 必须 `--yes`。
+ */
+import { existsSync } from "node:fs";
+import { createInterface } from "node:readline/promises";
+import { withCustomDefaults } from "../../ai/providers/catalog.js";
+import { describeRefresh, refreshModelsDev } from "../../ai/providers/models-dev-cache.js";
+import { modelsDevFields } from "../../ai/providers/models-dev.js";
+import { materializeModel } from "../../ai/providers/registry.js";
+import { PROVIDER_ID_PATTERN, setAuthKey } from "../../config/auth-file.js";
+import { loadConfigFile } from "../../config/load.js";
+import { CONFIG_FILE_VERSION } from "../../config/types.js";
+import { writeConfigFile } from "../../config/write.js";
+import { parseSubArgs, UsageError } from "../args.js";
+import { ExitCode } from "../exit-codes.js";
+import { extractKey } from "./auth.js";
+import { listChannels, listProviders, removeProvider } from "./providers-list.js";
+import { buildRegistry, loadUserLevel } from "./context.js";
+import { attempt, DISCOVER_TIMEOUT_MS, FATAL_STATUS } from "./models-discover.js";
+import { DEFAULT_PREFER, capRequests, defaultChannels, hintedChannels, listingTarget, mergeProvider, orderChannels, parseChannelSpec, parseModelList, probeSelection, renderTable, } from "./providers-plan.js";
+export const DEFAULT_MAX_REQUESTS = 60;
+export const DEFAULT_LIMIT = 30;
+export const PROVIDERS_USAGE = `用法：ama providers add <id> --base-url <url> [--channel <名字>=<协议>@<地址> …]
+                         [--api openai-completions|openai-responses|anthropic-messages|auto]
+                         [--key-env <VAR>] [--probe] [--limit N] [--probe-models a,b,…]
+                         [--max-requests N] [--prefer chat,responses,messages]
+                         [--include-no-tools] [--yes]
+      ama providers list
+      ama providers channels <id>
+      ama providers remove <id>
+      ama providers refresh <id> [--probe] [--limit N] [--probe-models a,b,…] [--max-requests N] [--yes]
+`;
+const VALUE_OPTIONS = [
+    "base-url",
+    "api",
+    "key-env",
+    "limit",
+    "probe-models",
+    "max-requests",
+    "prefer",
+    "name",
+    "profile",
+    "auth-file",
+];
+const FLAG_OPTIONS = ["probe", "include-no-tools", "yes"];
+function intValue(ctx, name, fallback) {
+    const raw = ctx.values.get(name);
+    if (raw === undefined)
+        return fallback;
+    const n = Number(raw);
+    if (!Number.isInteger(n) || n < 1)
+        throw new UsageError(`--${name} 需要正整数：${raw}`);
+    return n;
+}
+function list(raw) {
+    return raw
+        ?.split(",")
+        .map((s) => s.trim())
+        .filter((s) => s !== "");
+}
+export function userConfig(level) {
+    return structuredClone(loadConfigFile("config", level.userConfigPath)?.value ?? { version: CONFIG_FILE_VERSION });
+}
+async function confirm(io, question) {
+    io.stderr(question);
+    const rl = createInterface({ input: process.stdin, output: process.stderr });
+    try {
+        return /^y(es)?$/i.test((await rl.question("继续？[y/N] ")).trim());
+    }
+    finally {
+        rl.close();
+    }
+}
+/** --yes / TTY 确认；非 TTY 且没有 --yes 返回 false 并提示（调用方退出 2）。 */
+async function approved(ctx, what) {
+    if (ctx.flags.has("yes"))
+        return true;
+    if (!ctx.io.stdinIsTTY) {
+        ctx.io.stderr(`ama: ${what}，非交互环境需加 --yes\n`);
+        return "usage";
+    }
+    return confirm(ctx.io, `${what}\n`);
+}
+/**
+ * `GET /models`。OpenAI 系带 `Authorization: Bearer`；Anthropic 形状的渠道先试 Bearer（中转多半只认它），
+ * 401 / 403 再试 `x-api-key` + `anthropic-version`（官方形状）。
+ */
+async function fetchModelList(target, apiKey) {
+    const get = (headers) => fetch(target.url, {
+        headers: { accept: "application/json", ...headers },
+        signal: AbortSignal.timeout(DISCOVER_TIMEOUT_MS),
+    });
+    let response = await get(apiKey !== undefined ? { authorization: `Bearer ${apiKey}` } : {});
+    if ((response.status === 401 || response.status === 403) &&
+        apiKey !== undefined &&
+        target.channel.api === "anthropic-messages")
+        response = await get({ "x-api-key": apiKey, "anthropic-version": "2023-06-01" });
+    if (!response.ok)
+        throw new Error(`HTTP ${response.status} ${target.url}`);
+    return parseModelList(await response.json());
+}
+function channelsOfConfig(config) {
+    if (config.channels !== undefined)
+        return Object.entries(config.channels).map(([name, c]) => ({
+            name,
+            api: c.api,
+            baseUrl: c.baseUrl,
+        }));
+    if (config.baseUrl === undefined)
+        return [];
+    const api = config.api ?? "openai-completions";
+    return [{ name: "default", api, baseUrl: config.baseUrl }];
+}
+/** 渠道的探测用供应商数据（key 由调用方传入）。 */
+function probeProvider(id, channel) {
+    return {
+        id,
+        name: id,
+        api: channel.api,
+        baseUrl: channel.baseUrl,
+        envKeys: [],
+        models: [],
+        requiresApiKey: true,
+        builtin: false,
+    };
+}
+/** 逐模型定渠道（含探测）；返回各模型的计划与是否因鉴权 / 限流提前停止。 */
+async function plan(ctx, input) {
+    const { io } = ctx;
+    const prefer = list(ctx.values.get("prefer")) ?? [...DEFAULT_PREFER];
+    const byId = new Map(input.listed.map((m) => [m.id, m]));
+    const fresh = input.listed.filter((m) => !input.existingIds.has(m.id));
+    const hint = (id) => {
+        const listed = byId.get(id);
+        return listed !== undefined ? hintedChannels(listed, input.candidates) : undefined;
+    };
+    const tryChannels = (id) => orderChannels(hint(id) ?? input.candidates.map((c) => c.name), prefer);
+    const probeable = (id) => tryChannels(id).length > 0;
+    const results = new Map();
+    let stopped;
+    if (input.probe) {
+        const only = list(ctx.values.get("probe-models"));
+        const selected = probeSelection(fresh.map((m) => m.id).filter(probeable), intValue(ctx, "limit", DEFAULT_LIMIT), only);
+        const max = intValue(ctx, "max-requests", DEFAULT_MAX_REQUESTS);
+        const capped = capRequests(selected, tryChannels, max);
+        io.stdout(`\n探测：${capped.ids.length} 个模型、${capped.requests} 次最小请求（每模型每渠道 1 次，上限 ${max}）` +
+            `${capped.dropped > 0 ? `；另有 ${capped.dropped} 个超出上限未探测` : ""}\n`);
+        const ok = await approved(ctx, `将发 ${capped.requests} 次计费请求并写入 ${ctx.level.userConfigPath}`);
+        if (ok === "usage")
+            return { plans: [], cancelled: ExitCode.Usage };
+        if (!ok)
+            return { plans: [], cancelled: ExitCode.Ok };
+        outer: for (const id of capped.ids) {
+            const result = { ok: [] };
+            const failed = [];
+            results.set(id, result);
+            for (const name of tryChannels(id)) {
+                const channel = input.candidates.find((c) => c.name === name);
+                const provider = probeProvider(input.id, channel);
+                const model = materializeModel(withCustomDefaults({ id }, input.id, channel.api), provider);
+                const error = await attempt(input.registry, model, input.apiKey);
+                if (error === undefined)
+                    result.ok.push(name);
+                else {
+                    result.error = error.split("\n")[0]?.slice(0, 120) ?? error;
+                    failed.push(`${name}：${result.error}`);
+                    if (FATAL_STATUS.test(error)) {
+                        stopped = error;
+                        break outer;
+                    }
+                }
+            }
+            io.stdout(`  ${id}  ${result.ok.length > 0 ? result.ok.join(", ") : "全部失败"}` +
+                `${failed.length > 0 ? `（失败 ${failed.join("；")}）` : ""}\n`);
+        }
+    }
+    const includeNoTools = ctx.flags.has("include-no-tools");
+    const plans = input.listed.map((listed) => {
+        const match = input.index?.match(listed.id);
+        const fields = match !== undefined ? modelsDevFields(match.model) : {};
+        const base = { id: listed.id, fields, match };
+        if (input.existingIds.has(listed.id))
+            return { ...base, channels: [], status: "existing" };
+        const probed = results.get(listed.id);
+        if (probed !== undefined) {
+            if (probed.ok.length === 0)
+                return {
+                    ...base,
+                    channels: [],
+                    status: "failed",
+                    ...(probed.error ? { error: probed.error } : {}),
+                };
+            return { ...base, channels: orderChannels(probed.ok, prefer), status: "ok" };
+        }
+        const hinted = hint(listed.id);
+        if (hinted !== undefined && hinted.length === 0)
+            return { ...base, channels: [], status: "no-channel" };
+        const channels = hinted !== undefined
+            ? orderChannels(hinted, prefer)
+            : orderChannels(input.candidates.map((c) => c.name), prefer).slice(0, 1);
+        if (fields.toolCall === false && !includeNoTools)
+            return { ...base, channels, status: "no-tools" };
+        return { ...base, channels, status: "unprobed" };
+    });
+    for (const p of plans)
+        if (p.status === "ok" && p.fields.toolCall === false && !includeNoTools)
+            p.status = "no-tools";
+    return { plans, ...(stopped !== undefined ? { stopped } : {}) };
+}
+async function obtainKey(ctx, id, registry) {
+    const keyEnv = ctx.values.get("key-env");
+    if (keyEnv !== undefined) {
+        if (!/^[A-Za-z_][A-Za-z0-9_]*$/.test(keyEnv))
+            throw new UsageError(`--key-env 不是合法的变量名：${keyEnv}`);
+        const value = ctx.io.env[keyEnv]?.trim();
+        if (!value)
+            ctx.io.stderr(`ama: 警告：环境变量 ${keyEnv} 未设置，列模型与探测将不带 key\n`);
+        return { apiKey: value || undefined, configValue: `$${keyEnv}` };
+    }
+    if (registry.get(id) !== undefined) {
+        const existing = await registry.resolveApiKey(id);
+        if (existing.apiKey !== undefined)
+            return { apiKey: existing.apiKey };
+    }
+    if (ctx.io.stdinIsTTY)
+        ctx.io.stderr(`输入 ${id} 的 API key（不回显），回车结束：`);
+    const key = extractKey(await ctx.io.readStdin());
+    if (ctx.io.stdinIsTTY)
+        ctx.io.stderr("\n");
+    if (key === "")
+        throw new UsageError("没有从 stdin 读到 key（或用 --key-env <VAR>）");
+    return { apiKey: key, store: key };
+}
+async function add(ctx, id, refresh) {
+    const { io, level } = ctx;
+    if (!PROVIDER_ID_PATTERN.test(id) || id.includes("@"))
+        throw new UsageError(`供应商 id 不合法：${id}`);
+    const config = userConfig(level);
+    const existing = config.providers?.[id];
+    if (refresh && existing === undefined) {
+        io.stderr(`ama: ${level.userConfigPath} 里没有供应商 ${id}（先 ama providers add）\n`);
+        return ExitCode.Usage;
+    }
+    const registry = await buildRegistry(level, io, ctx.deps);
+    let candidates;
+    if (refresh)
+        candidates = channelsOfConfig(existing);
+    else if (ctx.channelSpecs.length > 0)
+        candidates = ctx.channelSpecs.map(parseChannelSpec);
+    else {
+        const baseUrl = ctx.values.get("base-url");
+        if (baseUrl === undefined)
+            throw new UsageError("ama providers add 需要 --base-url <url> 或 --channel");
+        if (!/^https?:\/\//.test(baseUrl))
+            throw new UsageError(`--base-url 应为 http(s) URL：${baseUrl}`);
+        candidates = defaultChannels(baseUrl, ctx.values.get("api"));
+    }
+    const target = listingTarget(candidates);
+    if (target === undefined)
+        throw new UsageError(`${id} 没有可用的渠道`);
+    const key = await obtainKey(ctx, id, registry);
+    let listed;
+    try {
+        listed = await fetchModelList(target, key.apiKey);
+    }
+    catch (error) {
+        io.stderr(`ama: ${id} 模型列表获取失败：${error.message}\n`);
+        return ExitCode.RuntimeError;
+    }
+    io.stdout(`${id}：发现 ${listed.length} 个模型（${target.url}）\n`);
+    const md = await refreshModelsDev({ dataDir: level.dataDir, env: io.env, force: refresh });
+    io.stdout(`${describeRefresh(md)}\n`);
+    if (md.warning !== undefined)
+        io.stderr(`ama: 警告：${md.warning}\n`);
+    io.stdout(`候选渠道：${candidates.map((c) => `${c.name}（${c.api} ${c.baseUrl}）`).join(" · ")}\n`);
+    const existingIds = new Set((existing?.models ?? []).map((m) => m.id));
+    const result = await plan(ctx, {
+        id,
+        candidates,
+        listed,
+        index: md.index,
+        existingIds,
+        apiKey: key.apiKey,
+        registry,
+        probe: ctx.flags.has("probe"),
+    });
+    if (result.cancelled !== undefined)
+        return result.cancelled;
+    io.stdout(`\n${renderTable(result.plans)}`);
+    if (refresh) {
+        const gone = [...existingIds].filter((m) => !listed.some((l) => l.id === m));
+        if (gone.length > 0)
+            io.stdout(`上游已不再列出（未删除）：${gone.join(", ")}\n`);
+    }
+    const writable = result.plans.filter((p) => p.status === "ok" || p.status === "unprobed");
+    const legacy = existing !== undefined && existing.channels === undefined;
+    const merged = legacy && refresh
+        ? legacyMerge(existing, writable.map((p) => p.id))
+        : mergeProvider(legacy ? asChannels(existing) : existing, {
+            ...(ctx.values.get("name") !== undefined
+                ? { name: ctx.values.get("name") }
+                : {}),
+            ...(key.configValue !== undefined ? { apiKey: key.configValue } : {}),
+            channels: candidates,
+            models: writable,
+            prefer: list(ctx.values.get("prefer")) ?? [...DEFAULT_PREFER],
+        });
+    const keyNote = key.store !== undefined ? `；key → ${level.authFile}（0600）` : "";
+    const summary = `\n将写入 ${level.userConfigPath}：${id} 新增渠道 ${merged.addedChannels.join(", ") || "无"}，` +
+        `新增模型 ${merged.addedModels.length} 个${keyNote}`;
+    io.stdout(`${summary}\n`);
+    if (merged.addedModels.length === 0 &&
+        merged.addedChannels.length === 0 &&
+        key.store === undefined) {
+        io.stdout("没有要写入的内容\n");
+        return result.stopped !== undefined ? ExitCode.RuntimeError : ExitCode.Ok;
+    }
+    if (!ctx.flags.has("probe")) {
+        const ok = await approved(ctx, "确认写入");
+        if (ok === "usage")
+            return ExitCode.Usage;
+        if (!ok) {
+            io.stderr("ama: 已取消\n");
+            return ExitCode.Ok;
+        }
+    }
+    const providers = (config.providers ??= {});
+    providers[id] = merged.config;
+    const backup = existsSync(level.userConfigPath);
+    writeConfigFile(level.userConfigPath, config, { backup: true });
+    if (key.store !== undefined)
+        setAuthKey(level.authFile, id, key.store);
+    io.stdout(`已写入 ${level.userConfigPath}${backup ? "（原文件备份为 config.json.bak）" : ""}\n`);
+    const sample = result.plans.find((p) => p.status === "ok" && merged.addedModels.includes(p.id))?.id ??
+        merged.addedModels[0];
+    if (sample !== undefined)
+        io.stdout(`试试：ama -p "hi" --model ${id}/${sample}\n`);
+    if (result.stopped !== undefined) {
+        io.stderr(`ama: 探测提前停止（${result.stopped}）\n`);
+        return ExitCode.RuntimeError;
+    }
+    return ExitCode.Ok;
+}
+/** 旧写法（无 channels）的供应商：先把供应商级 api + baseUrl 变成 `default` 渠道。 */
+function asChannels(config) {
+    const { api, baseUrl, ...rest } = structuredClone(config);
+    if (baseUrl === undefined)
+        return rest;
+    return {
+        ...rest,
+        channels: { default: { api: api ?? "openai-completions", baseUrl } },
+        defaultChannel: "default",
+    };
+}
+/** 旧写法供应商的 refresh：只追加 `{ id }`。 */
+function legacyMerge(config, ids) {
+    const next = structuredClone(config);
+    const models = (next.models ??= []);
+    const known = new Set(models.map((m) => m.id));
+    const addedModels = ids.filter((id) => !known.has(id));
+    for (const id of addedModels)
+        models.push({ id });
+    return { config: next, addedChannels: [], addedModels };
+}
+/** `--channel` 可重复：先从 argv 里取出来，其余交给 parseSubArgs。 */
+function takeChannels(argv) {
+    const rest = [];
+    const specs = [];
+    for (let i = 0; i < argv.length; i++) {
+        const token = argv[i] ?? "";
+        if (token === "--channel") {
+            const value = argv[++i];
+            if (value === undefined || value === "")
+                throw new UsageError("--channel 需要一个值");
+            specs.push(value);
+        }
+        else if (token.startsWith("--channel="))
+            specs.push(token.slice("--channel=".length));
+        else
+            rest.push(token);
+    }
+    return { rest, specs };
+}
+export async function runProviders(argv, io, deps) {
+    const { rest, specs } = takeChannels(argv);
+    const { positionals, values, flags } = parseSubArgs(rest, VALUE_OPTIONS, FLAG_OPTIONS);
+    const action = positionals[0];
+    if (flags.has("help") || action === undefined) {
+        io.stdout(PROVIDERS_USAGE);
+        return flags.has("help") ? ExitCode.Ok : ExitCode.Usage;
+    }
+    if (deps === undefined) {
+        io.stderr("ama: providers 尚未装配（供应商注册表由集成批次注入）\n");
+        return ExitCode.RuntimeError;
+    }
+    const level = loadUserLevel(io, {
+        profile: values.get("profile"),
+        authFile: values.get("auth-file"),
+    });
+    for (const warning of level.warnings)
+        io.stderr(`ama: 警告：${warning}\n`);
+    const ctx = { io, deps, level, values, flags, channelSpecs: specs };
+    const target = positionals[1];
+    const need = () => {
+        if (target === undefined)
+            throw new UsageError(`ama providers ${action} 需要 <id>`);
+        if (positionals.length > 2)
+            throw new UsageError(`多余的参数：${positionals.slice(2).join(" ")}`);
+        return target;
+    };
+    switch (action) {
+        case "add":
+            return add(ctx, need(), false);
+        case "refresh":
+            return add(ctx, need(), true);
+        case "list":
+            return listProviders(ctx);
+        case "channels":
+            return listChannels(ctx, need());
+        case "remove":
+            return removeProvider(ctx, need());
+        default:
+            throw new UsageError(`未知的 providers 子命令：${action}`);
+    }
+}

package/dist/config/init.d.ts

@@ -0,0 +1,30 @@
+/**
+ * 配置目录初始化（docs/providers.md「配置目录」）：`ama init` 与 CLI 首次运行的自动初始化。
+ *
+ * - 目录 0700；`config.json` 只在不存在时写最小内容（`--force` 时先备份再重写）；
+ * - `config.schema.json` 不是用户文件，每次 init 都按当前版本重写（内容相同则不动）；
+ * - 不创建 auth.json（只有 `ama auth set` / `ama providers add` 才写，0600）。
+ * - 自动初始化只在 CLI 里、配置目录不存在时触发，`AMA_NO_INIT=1` 关闭；SDK 与测试不走这里。
+ */
+import { type AmaConfig } from "./types.js";
+export declare const NO_INIT_ENV = "AMA_NO_INIT";
+/** 最小 config.json：常用键的缺省值（与 DEFAULT_CONFIG 相同，写出来方便直接改）。 */
+export declare function minimalConfig(): AmaConfig & {
+    $schema: string;
+};
+export type InitStatus = "created" | "exists" | "updated" | "unchanged" | "overwritten";
+export interface InitResult {
+    dir: string;
+    dirCreated: boolean;
+    files: {
+        path: string;
+        status: InitStatus;
+    }[];
+}
+/** 建目录并补齐缺失文件；已有的 config.json 不覆盖（`force` 时备份为 .bak 再重写）。 */
+export declare function initConfigDir(dir: string, options?: {
+    force?: boolean;
+}): InitResult;
+/** CLI 启动时：配置目录不存在就静默初始化；返回是否初始化了。失败不影响启动。 */
+export declare function autoInitConfigDir(dir: string, env: Readonly<Record<string, string | undefined>>): boolean;
+export declare function describeInit(result: InitResult): string;

package/dist/config/init.js

@@ -0,0 +1,92 @@
+/**
+ * 配置目录初始化（docs/providers.md「配置目录」）：`ama init` 与 CLI 首次运行的自动初始化。
+ *
+ * - 目录 0700；`config.json` 只在不存在时写最小内容（`--force` 时先备份再重写）；
+ * - `config.schema.json` 不是用户文件，每次 init 都按当前版本重写（内容相同则不动）；
+ * - 不创建 auth.json（只有 `ama auth set` / `ama providers add` 才写，0600）。
+ * - 自动初始化只在 CLI 里、配置目录不存在时触发，`AMA_NO_INIT=1` 关闭；SDK 与测试不走这里。
+ */
+import { chmodSync, copyFileSync, existsSync, mkdirSync, readFileSync, renameSync, writeFileSync, } from "node:fs";
+import { join } from "node:path";
+import { CONFIG_SCHEMA_FILE, configSchemaText } from "./json-schema.js";
+import { AUTH_FILE, CONFIG_FILE } from "./paths.js";
+import { CONFIG_FILE_VERSION } from "./types.js";
+export const NO_INIT_ENV = "AMA_NO_INIT";
+/** 最小 config.json：常用键的缺省值（与 DEFAULT_CONFIG 相同，写出来方便直接改）。 */
+export function minimalConfig() {
+    return {
+        $schema: `./${CONFIG_SCHEMA_FILE}`,
+        version: CONFIG_FILE_VERSION,
+        thinkingLevel: "medium",
+        permission: { mode: "default" },
+        tools: { preset: "default" },
+        providers: {},
+    };
+}
+function writeAtomic(path, text, mode) {
+    const tmp = `${path}.${process.pid}.tmp`;
+    writeFileSync(tmp, text, { mode });
+    renameSync(tmp, path);
+}
+/** 建目录并补齐缺失文件；已有的 config.json 不覆盖（`force` 时备份为 .bak 再重写）。 */
+export function initConfigDir(dir, options = {}) {
+    const dirCreated = !existsSync(dir);
+    mkdirSync(dir, { recursive: true, mode: 0o700 });
+    if (dirCreated && process.platform !== "win32")
+        chmodSync(dir, 0o700);
+    const files = [];
+    const config = join(dir, CONFIG_FILE);
+    const text = `${JSON.stringify(minimalConfig(), null, 2)}\n`;
+    if (!existsSync(config)) {
+        writeAtomic(config, text, 0o644);
+        files.push({ path: config, status: "created" });
+    }
+    else if (options.force) {
+        copyFileSync(config, `${config}.bak`);
+        writeAtomic(config, text, 0o644);
+        files.push({ path: config, status: "overwritten" });
+    }
+    else
+        files.push({ path: config, status: "exists" });
+    const schema = join(dir, CONFIG_SCHEMA_FILE);
+    const schemaText = configSchemaText();
+    if (!existsSync(schema)) {
+        writeAtomic(schema, schemaText, 0o644);
+        files.push({ path: schema, status: "created" });
+    }
+    else if (readFileSync(schema, "utf8") !== schemaText) {
+        writeAtomic(schema, schemaText, 0o644);
+        files.push({ path: schema, status: "updated" });
+    }
+    else
+        files.push({ path: schema, status: "unchanged" });
+    const auth = join(dir, AUTH_FILE);
+    if (existsSync(auth))
+        files.push({ path: auth, status: "exists" });
+    return { dir, dirCreated, files };
+}
+/** CLI 启动时：配置目录不存在就静默初始化；返回是否初始化了。失败不影响启动。 */
+export function autoInitConfigDir(dir, env) {
+    if (env[NO_INIT_ENV] === "1" || existsSync(dir))
+        return false;
+    try {
+        initConfigDir(dir);
+        return true;
+    }
+    catch {
+        return false;
+    }
+}
+const STATUS_TEXT = {
+    created: "已创建",
+    exists: "已存在，未改动",
+    updated: "已更新为当前版本",
+    unchanged: "已是当前版本",
+    overwritten: "已重写（原文件备份为 .bak）",
+};
+export function describeInit(result) {
+    const lines = [`${result.dir}${result.dirCreated ? "  已创建（0700）" : "  已存在"}`];
+    for (const file of result.files)
+        lines.push(`  ${file.path}  ${STATUS_TEXT[file.status]}`);
+    return `${lines.join("\n")}\n`;
+}

package/dist/config/json-schema.d.ts

@@ -0,0 +1,14 @@
+/**
+ * config.json 的 JSON Schema（draft-07 子集），写到配置目录的 `config.schema.json` 给编辑器补全与校验
+ * （docs/providers.md「配置目录」）。规则与 schema.ts 的 `validateConfig` 一一对应：未知字段在那里是
+ * warning、这里是 `additionalProperties: false`；渠道引用（模型 `channels` 指向已定义的渠道）这类跨字段
+ * 规则 JSON Schema 表达不了，只在 `validateConfig` 里查。一致性由 json-schema.test.ts 的正反例守住。
+ */
+type Schema = Record<string, unknown>;
+export declare const CONFIG_SCHEMA_FILE = "config.schema.json";
+export declare const CONFIG_SCHEMA_ID = "https://github.com/Owlbay/armadra-agent/config.schema.json";
+/** 生成 config.json 的 JSON Schema。 */
+export declare function buildConfigJsonSchema(): Schema;
+/** 写进文件的文本（2 空格缩进 + 换行结尾）。 */
+export declare function configSchemaText(): string;
+export {};