@wayfarer35/ccs 0.2.2

package/dist/completion.js

@@ -0,0 +1,116 @@
+/**
+ * Shell 补全：候选生成 + bash/zsh 脚本。
+ *
+ * 模式（cobra/oclif 风格）：
+ * - `ccs __complete <words...>` 隐藏命令，按已输入词序列输出候选项（每行一个）。
+ * - `ccs completion <shell>` 输出对应 shell 的补全脚本，脚本运行时回调 `ccs __complete`。
+ *
+ * 候选数据复用 listProviders() / presetList()，单一真源，不重复维护配置名表。
+ * 本模块为纯函数（IO 委托 config/presets），便于单测。
+ */
+import { listProviders } from './config.js';
+import { presetList } from './presets.js';
+/** 子命令（含别名）。 */
+const SUBCOMMANDS = ['list', 'ls', 'presets', 'create', 'edit', 'remove', 'rm', 'common', 'show', 'config', 'use'];
+/** 全局 flag。 */
+const GLOBAL_FLAGS = ['-h', '--help', '-v', '--version'];
+/** 第一个参数位补 provider 名的子命令。 */
+const PROVIDER_CMDS = new Set(['edit', 'remove', 'rm', 'show']);
+/**
+ * 根据已输入词序列返回补全候选（已按当前光标词前缀过滤）。
+ *
+ * argv = 去掉 `ccs` 与 `__complete` 后的词，最后一个元素是当前光标词 cur（可为空串）。
+ *
+ * 注意：第一位置词同时容纳子命令与具名 provider（`ccs <name>` 直接启动），
+ * 这是该 CLI「子命令与 provider 名共享第一位置词空间」特性的自然映射。
+ */
+export function completeCandidates(argv) {
+    const cur = argv[argv.length - 1] ?? '';
+    const prev = argv.slice(0, -1);
+    // 第一个位置词未输入（prev 为空）→ 子命令 + provider 名 + 全局 flag
+    if (prev.length === 0) {
+        return filterByPrefix([...SUBCOMMANDS, ...listProviders(), ...GLOBAL_FLAGS], cur);
+    }
+    const head = prev[0]; // noUncheckedIndexedAccess：prev 非空，[0] 必存在
+    // 子命令的第一个参数位
+    if (prev.length === 1) {
+        if (PROVIDER_CMDS.has(head))
+            return filterByPrefix(listProviders(), cur);
+        if (head === 'create')
+            return filterByPrefix(presetList().map((p) => p.key), cur);
+        if (head === 'config')
+            return filterByPrefix(['locale'], cur);
+        // list/presets/common/use 无位置参数补全；ccs <name> 已在 prev.length===0 覆盖
+        return [];
+    }
+    // config locale <cur>（仅当 cur 处于 locale 取值位，即 prev 恰为 ['config','locale']）
+    if (head === 'config' && prev.length === 2 && prev[1] === 'locale') {
+        return filterByPrefix(['en', 'zh-CN'], cur);
+    }
+    return [];
+}
+/** 按前缀过滤候选；空前缀返回全部。 */
+function filterByPrefix(cands, prefix) {
+    if (!prefix)
+        return cands;
+    return cands.filter((c) => c.startsWith(prefix));
+}
+/**
+ * bash 补全脚本。`eval "$(ccs completion bash)"` 后生效。
+ * ccs 不在 PATH 时静默不注册；__complete 出错时静默返回。
+ * 注意：模板字面量中所有 shell 的 ${...} 必须转义为 \${...}，避免被 JS 当成插值。
+ */
+export const bashCompletionScript = `# ccs bash completion
+if command -v ccs >/dev/null 2>&1; then
+  _ccs_bash_complete() {
+    local cur cands
+    cur="\${COMP_WORDS[COMP_CWORD]}"
+    # COMP_WORDS[1:] 已含末尾 cur 词，直接传给 ccs __complete
+    cands=$(ccs __complete "\${COMP_WORDS[@]:1}" 2>/dev/null) || return
+    COMPREPLY=($(compgen -W "$cands" -- "$cur"))
+  }
+  complete -F _ccs_bash_complete ccs
+fi
+`;
+/**
+ * zsh 补全脚本。`eval "$(ccs completion zsh)"` 后生效（需 compinit 已加载）。
+ * ccs 不在 PATH 时静默不注册。
+ * 注意：模板字面量中所有 shell 的 ${...} 必须转义为 \${...}，避免被 JS 当成插值。
+ */
+export const zshCompletionScript = `# ccs zsh completion
+if command -v ccs >/dev/null 2>&1; then
+  _ccs_zsh_complete() {
+    local -a cands
+    # \${words[@]:1}：去掉 ccs 本身，末尾即当前词
+    cands=("\${(@f)\$(ccs __complete "\${words[@]:1}" 2>/dev/null)}")
+    compadd -- "\$@" "\${cands[@]}"
+  }
+  compdef _ccs_zsh_complete ccs
+fi
+`;
+/** 支持的 shell。 */
+export const SUPPORTED_SHELLS = ['bash', 'zsh'];
+/** 补全脚本按 shell 取；不支持时返回 null。 */
+export function completionScript(shell) {
+    if (shell === 'bash')
+        return bashCompletionScript;
+    if (shell === 'zsh')
+        return zshCompletionScript;
+    return null;
+}
+/** `ccs completion` 无参/不支持的 shell 时的提示文本。 */
+export function completionHelp(shell) {
+    const supported = SUPPORTED_SHELLS.join(', ');
+    if (shell && !SUPPORTED_SHELLS.includes(shell)) {
+        return `Unsupported shell: ${shell}. Supported: ${supported}.`;
+    }
+    return [
+        'Usage: ccs completion <shell>',
+        `  Outputs a shell completion script. Supported: ${supported}.`,
+        '',
+        'Install (bash):  eval "$(ccs completion bash)"   # or append to ~/.bashrc',
+        'Install (zsh):   eval "$(ccs completion zsh)"    # or append to ~/.zshrc',
+        '',
+        'Global install (npm i -g @wayfarer35/ccs) auto-writes the eval line into your rc.',
+    ].join('\n');
+}

package/dist/config.d.ts

@@ -0,0 +1,21 @@
+export declare const CCS_DIR: string;
+export declare const PROVIDERS_DIR: string;
+export declare const CONFIG_FILE: string;
+export declare const LASTUSED_FILE: string;
+export declare const CACHE_DIR: string;
+/** 通用配置来源：直接用 Claude Code 自身的 settings.json，ccs 只读不写。 */
+export declare const CLAUDE_SETTINGS_FILE: string;
+export declare const PROVIDER_SUFFIX = ".settings.json";
+export declare function ensureDirs(): void;
+/** 读取并解析 JSON 文件；ENOENT 返回 fallback，其余解析错误抛出。 */
+export declare function readJSON<T>(file: string, fallback?: T | null): T | null;
+export declare function writeJSON(file: string, obj: unknown): void;
+/** 写入原始字符串内容（自动创建父目录），用于编辑 ~/.claude/settings.json 等已有文件。 */
+export declare function writeFileSyncSafe(file: string, content: string): void;
+export declare function providerFile(name: string): string;
+export declare function readProvider<T = unknown>(name: string): T | null;
+export declare function providerExists(name: string): boolean;
+export declare function listProviders(): string[];
+export declare function getLastUsed(): string | null;
+export declare function setLastUsed(name: string): void;
+export declare function removeProvider(name: string): void;

package/dist/config.js

@@ -0,0 +1,73 @@
+import { homedir } from 'node:os';
+import { join } from 'node:path';
+import { mkdirSync, readFileSync, writeFileSync, readdirSync, existsSync, rmSync, } from 'node:fs';
+export const CCS_DIR = join(homedir(), '.ccs');
+export const PROVIDERS_DIR = join(CCS_DIR, 'providers');
+export const CONFIG_FILE = join(CCS_DIR, 'config.json');
+export const LASTUSED_FILE = join(CCS_DIR, '.lastused');
+export const CACHE_DIR = join(CCS_DIR, '.cache');
+/** 通用配置来源：直接用 Claude Code 自身的 settings.json，ccs 只读不写。 */
+export const CLAUDE_SETTINGS_FILE = join(homedir(), '.claude', 'settings.json');
+export const PROVIDER_SUFFIX = '.settings.json';
+export function ensureDirs() {
+    mkdirSync(PROVIDERS_DIR, { recursive: true });
+    mkdirSync(CACHE_DIR, { recursive: true });
+}
+/** 读取并解析 JSON 文件；ENOENT 返回 fallback，其余解析错误抛出。 */
+export function readJSON(file, fallback = null) {
+    try {
+        return JSON.parse(readFileSync(file, 'utf8'));
+    }
+    catch (e) {
+        if (e.code === 'ENOENT')
+            return fallback;
+        throw new Error(`Failed to parse JSON / 解析 JSON 失败: ${file}\n${e.message}`);
+    }
+}
+export function writeJSON(file, obj) {
+    mkdirSync(join(file, '..'), { recursive: true });
+    writeFileSync(file, JSON.stringify(obj, null, 2) + '\n');
+}
+/** 写入原始字符串内容（自动创建父目录），用于编辑 ~/.claude/settings.json 等已有文件。 */
+export function writeFileSyncSafe(file, content) {
+    mkdirSync(join(file, '..'), { recursive: true });
+    writeFileSync(file, content);
+}
+export function providerFile(name) {
+    return join(PROVIDERS_DIR, `${name}${PROVIDER_SUFFIX}`);
+}
+export function readProvider(name) {
+    return readJSON(providerFile(name), null);
+}
+export function providerExists(name) {
+    return existsSync(providerFile(name));
+}
+export function listProviders() {
+    ensureDirs();
+    let entries = [];
+    try {
+        entries = readdirSync(PROVIDERS_DIR);
+    }
+    catch { /* dir missing */ }
+    return entries
+        .filter((f) => f.endsWith(PROVIDER_SUFFIX))
+        .map((f) => f.slice(0, -PROVIDER_SUFFIX.length))
+        .sort((a, b) => a.localeCompare(b));
+}
+export function getLastUsed() {
+    try {
+        return readFileSync(LASTUSED_FILE, 'utf8').trim() || null;
+    }
+    catch {
+        return null;
+    }
+}
+export function setLastUsed(name) {
+    try {
+        writeFileSync(LASTUSED_FILE, name);
+    }
+    catch { /* best-effort */ }
+}
+export function removeProvider(name) {
+    rmSync(providerFile(name), { force: true });
+}

package/dist/form.d.ts

@@ -0,0 +1,66 @@
+import type { EffortLevel, FormState, Preset, ProviderSettings, Tier } from './types.js';
+export declare const TIERS: Array<{
+    value: Tier;
+    label: string;
+}>;
+export declare const ALIAS_TIERS: readonly ["FABLE", "OPUS", "SONNET", "HAIKU"];
+export declare const EFFORT_LEVELS: readonly EffortLevel[];
+/** 解析 env 里的布尔值（'1'/'true' → true，'0'/'false' → false，空 → def）。 */
+export declare function parseBoolEnv(v: string | undefined, def: boolean): boolean;
+/** 解析 env 里的正整数（非法 → def）。 */
+export declare function parseNumEnv(v: string | undefined, def: number): number;
+/** 解析 env 里的 effort 档位（非法/空 → def）。大小写不敏感。 */
+export declare function parseEffortEnv(v: string | undefined, def: EffortLevel): EffortLevel;
+/** initState 输入：已有 settings（编辑时）与 preset（创建时预填）。 */
+interface InitInput {
+    env?: Record<string, string>;
+    model?: string;
+}
+/**
+ * 第一步：选内置供应商还是自定义。
+ * @returns {'builtin' | 'custom'}
+ */
+export declare function chooseCreateMode(): Promise<'builtin' | 'custom'>;
+/**
+ * 选择内置供应商预设。返回 { key, preset }。
+ */
+export declare function pickBuiltinPreset(): Promise<{
+    key: string;
+    preset: Preset;
+}>;
+/** 向后兼容：旧 pickPreset 调用点（如有）。 */
+export declare function pickPreset(): Promise<{
+    key: string;
+    preset: Preset | null;
+}>;
+/**
+ * 从 initial（编辑时已有 settings）与 preset（创建时预填）初始化表单状态。
+ * 三项 options 的取值优先级：existing env > preset.options > DEFAULT_OPTIONS。
+ * 档位别名从 preset.model.tiers 读取（取代旧的 preset.models）。
+ */
+export declare function initState(initial: InitInput, preset: Preset | null): FormState;
+/**
+ * 由表单状态构建 settings 片段 { env, model? }。
+ * 三项 CLAUDE_CODE_* 始终写入 env（显式可见，每次启动生效）。
+ * authMethod 决定写入 ANTHROPIC_AUTH_TOKEN 还是 ANTHROPIC_API_KEY。
+ * customParams 解析为 JSON 后，顶层 key-value 合并到 env。
+ */
+export declare function buildResult(state: FormState): ProviderSettings;
+/** 提交前校验：必填项是否齐全。返回错误消息或 null。 */
+export declare function validateState(state: FormState): string | null;
+/**
+ * 持久化 Tab 表单（ink）：API Key / Models / Options / Review（预览+提交）。
+ * Tab 切换时下方内容跟随变化，字段直接原地编辑，无需 Enter 进入。
+ * create/edit 共用。委托给 formUi.runProviderForm。
+ *
+ * @param opts
+ * @param opts.initial  已有 settings（edit 时预填）
+ * @param opts.preset   预设（create 时预填，可为 null=自定义）
+ * @returns 最终 settings 片段
+ */
+export declare function providerFormWithPreview(opts?: {
+    initial?: InitInput;
+    preset?: Preset | null;
+    title?: string;
+}): Promise<ProviderSettings>;
+export {};

package/dist/form.js

@@ -0,0 +1,269 @@
+import { ui } from './tui.js';
+import { getPresets, CUSTOM_KEY } from './presets.js';
+import { t } from './i18n.js';
+import { runProviderForm } from './formUi.js';
+export const TIERS = [
+    { value: 'opus', label: 'opus' },
+    { value: 'sonnet', label: 'sonnet' },
+    { value: 'haiku', label: 'haiku' },
+    { value: 'fable', label: 'fable' },
+];
+// 环境变量后缀的大小写档位（对应 ANTHROPIC_DEFAULT_<TIER>_MODEL）
+export const ALIAS_TIERS = ['FABLE', 'OPUS', 'SONNET', 'HAIKU'];
+// 推理强度档位（对应 CLAUDE_CODE_EFFORT_LEVEL），与 Claude Code 内置取值一致。
+export const EFFORT_LEVELS = ['low', 'medium', 'high', 'xhigh', 'max'];
+// 三项 CLAUDE_CODE_* 配置的默认值。
+// - attributionHeader: 默认关闭（尊重用户全局已禁用 attribution 的设置）。
+// - disableNonEssentialTraffic: 默认开启（减少遥测/分析流量）。
+// - autoCompactWindow: 默认 200k tokens。
+// - effort: 默认 max（最高推理强度），可在供应商上覆盖。
+const DEFAULT_OPTIONS = {
+    attributionHeader: false,
+    disableNonEssentialTraffic: true,
+    autoCompactWindow: 200000,
+    effort: 'max',
+};
+const MODE_BUILTIN = 'builtin';
+const MODE_CUSTOM = 'custom';
+function aliasKey(tierUpper) {
+    return `ANTHROPIC_DEFAULT_${tierUpper}_MODEL`;
+}
+/** /model 选择器中的显示名 key（与 _MODEL 配套，仅显示用，不参与 API 请求）。 */
+function nameKey(tierUpper) {
+    return `ANTHROPIC_DEFAULT_${tierUpper}_MODEL_NAME`;
+}
+/** 剥离 [1m] 上下文后缀，用于派生显示名（claude 发请求前会自行剥离 _MODEL 的后缀，显示名无需带）。 */
+function strip1m(v) {
+    return v.replace(/\[1m\]$/i, '').trim();
+}
+/** 是否存在任一档位别名 env（用于判断当前配置处于档位别名模式）。 */
+function hasAliasEnv(env) {
+    return ALIAS_TIERS.some((tier) => env[aliasKey(tier)]);
+}
+/** 解析 env 里的布尔值（'1'/'true' → true，'0'/'false' → false，空 → def）。 */
+export function parseBoolEnv(v, def) {
+    if (v === undefined || v === null || v === '')
+        return def;
+    const s = String(v).trim().toLowerCase();
+    if (s === '1' || s === 'true')
+        return true;
+    if (s === '0' || s === 'false')
+        return false;
+    return def;
+}
+/** 解析 env 里的正整数（非法 → def）。 */
+export function parseNumEnv(v, def) {
+    if (v === undefined || v === null || v === '')
+        return def;
+    const n = Number(String(v).trim());
+    return Number.isInteger(n) && n > 0 ? n : def;
+}
+/** 解析 env 里的 effort 档位（非法/空 → def）。大小写不敏感。 */
+export function parseEffortEnv(v, def) {
+    if (v === undefined || v === null || v === '')
+        return def;
+    const s = String(v).trim().toLowerCase();
+    return EFFORT_LEVELS.includes(s) ? s : def;
+}
+/**
+ * 第一步：选内置供应商还是自定义。
+ * @returns {'builtin' | 'custom'}
+ */
+export async function chooseCreateMode() {
+    return ui.inkSelect({
+        message: t('create.kindPrompt'),
+        options: [
+            { value: MODE_BUILTIN, label: t('create.kindBuiltin') },
+            { value: MODE_CUSTOM, label: t('create.kindCustom') },
+        ],
+        initialValue: MODE_BUILTIN,
+    });
+}
+/**
+ * 选择内置供应商预设。返回 { key, preset }。
+ */
+export async function pickBuiltinPreset() {
+    const presets = getPresets();
+    const options = Object.entries(presets).map(([key, p]) => ({
+        value: key,
+        label: p.label,
+        hint: p.baseUrl || t('presets.fillUrl'),
+    }));
+    const key = await ui.inkSelect({
+        message: t('create.builtinPrompt'),
+        options,
+        initialValue: Object.keys(presets)[0],
+    });
+    return { key, preset: presets[key] };
+}
+/** 向后兼容：旧 pickPreset 调用点（如有）。 */
+export async function pickPreset() {
+    const mode = await chooseCreateMode();
+    if (mode === MODE_BUILTIN)
+        return pickBuiltinPreset();
+    return { key: CUSTOM_KEY, preset: null };
+}
+/**
+ * 推断本次表单应默认进入哪种模式。
+ * 默认档位别名模式（档位全部显示，配不配置由用户决定，预设只负责预填），
+ * 仅在编辑已有「单一 ANTHROPIC_MODEL」配置时回退到单模型模式。
+ * - 已有档位别名 env → 别名模式
+ * - 已有 ANTHROPIC_MODEL（且无别名）→ 单模型模式
+ * - 其余（含创建/预设，无论 preset 是否带 models）→ 别名模式
+ */
+function detectAliasMode(initial, preset) {
+    const env = initial.env || {};
+    if (hasAliasEnv(env))
+        return true;
+    if (env.ANTHROPIC_MODEL)
+        return false;
+    return true;
+}
+/**
+ * 从 initial（编辑时已有 settings）与 preset（创建时预填）初始化表单状态。
+ * 三项 options 的取值优先级：existing env > preset.options > DEFAULT_OPTIONS。
+ * 档位别名从 preset.model.tiers 读取（取代旧的 preset.models）。
+ */
+export function initState(initial, preset) {
+    const env = initial.env || {};
+    const existingKey = env.ANTHROPIC_AUTH_TOKEN || env.ANTHROPIC_API_KEY || '';
+    const presetOptions = preset?.options || {};
+    const options = {
+        attributionHeader: parseBoolEnv(env.CLAUDE_CODE_ATTRIBUTION_HEADER, presetOptions.attributionHeader ?? DEFAULT_OPTIONS.attributionHeader),
+        disableNonEssentialTraffic: parseBoolEnv(env.CLAUDE_CODE_DISABLE_NONESSENTIAL_TRAFFIC, presetOptions.disableNonEssentialTraffic ?? DEFAULT_OPTIONS.disableNonEssentialTraffic),
+        autoCompactWindow: parseNumEnv(env.CLAUDE_CODE_AUTO_COMPACT_WINDOW, presetOptions.autoCompactWindow ?? DEFAULT_OPTIONS.autoCompactWindow),
+        effort: parseEffortEnv(env.CLAUDE_CODE_EFFORT_LEVEL, presetOptions.effort ?? DEFAULT_OPTIONS.effort),
+    };
+    const aliases = {};
+    const presetTiers = preset?.model?.tiers || {};
+    for (const tierUpper of ALIAS_TIERS) {
+        const k = aliasKey(tierUpper);
+        const tierLower = tierUpper.toLowerCase();
+        aliases[tierUpper] = env[k] ?? presetTiers[tierLower] ?? '';
+    }
+    const mode = detectAliasMode(initial, preset) ? 'alias' : 'single';
+    // 认证方式：编辑时检测 ANTHROPIC_API_KEY 存在则选 'api_key'，否则 'auth_token'
+    const authMethod = env.ANTHROPIC_API_KEY ? 'api_key' : 'auth_token';
+    // 默认档位：从 preset.model.tier 读取，否则 'opus'
+    const tier = initial.model || preset?.model?.tier || 'opus';
+    // 单模型：从 preset.model.default 读取
+    const singleModel = env.ANTHROPIC_MODEL ?? preset?.model?.default ?? '';
+    return {
+        baseUrl: env.ANTHROPIC_BASE_URL ?? preset?.baseUrl ?? '',
+        existingKey,
+        apiKey: '',
+        keepExistingKey: !!existingKey,
+        mode,
+        authMethod,
+        tier,
+        aliases,
+        singleModel,
+        options,
+        customParams: '',
+    };
+}
+/**
+ * 由表单状态构建 settings 片段 { env, model? }。
+ * 三项 CLAUDE_CODE_* 始终写入 env（显式可见，每次启动生效）。
+ * authMethod 决定写入 ANTHROPIC_AUTH_TOKEN 还是 ANTHROPIC_API_KEY。
+ * customParams 解析为 JSON 后，顶层 key-value 合并到 env。
+ */
+export function buildResult(state) {
+    const env = { ANTHROPIC_BASE_URL: state.baseUrl.trim() };
+    // Key：根据 authMethod 写入不同的环境变量
+    // 同时把另一个 key 置为空串占位，覆盖主配置可能存在的残留值。
+    const keyEnv = state.authMethod === 'api_key' ? 'ANTHROPIC_API_KEY' : 'ANTHROPIC_AUTH_TOKEN';
+    const otherKeyEnv = state.authMethod === 'api_key' ? 'ANTHROPIC_AUTH_TOKEN' : 'ANTHROPIC_API_KEY';
+    if (state.apiKey && state.apiKey.trim()) {
+        env[keyEnv] = state.apiKey.trim();
+    }
+    else if (state.keepExistingKey && state.existingKey) {
+        env[keyEnv] = state.existingKey;
+    }
+    // 另一个 key 始终写入空串占位（覆盖主配置残留）
+    env[otherKeyEnv] = '';
+    if (state.mode === 'single') {
+        env.ANTHROPIC_MODEL = state.singleModel.trim();
+    }
+    else if (state.mode === 'alias') {
+        // 别名模式：显式写 ANTHROPIC_MODEL = ''（空串）。
+        // 必须显式置空——省略会让 ~/.claude/settings.json 里残留的 ANTHROPIC_MODEL 透传，
+        // 导致看到错误模型；而空串会覆盖残留值，又不参与模型解析，档位别名
+        // （ANTHROPIC_DEFAULT_*_MODEL）继续生效，会话内 /model 切换可用。
+        env.ANTHROPIC_MODEL = '';
+        for (const tierUpper of ALIAS_TIERS) {
+            const v = (state.aliases[tierUpper] || '').trim();
+            // 始终写入所有档位别名（含空串）及其显示名，确保完美覆盖主配置的同名 key——
+            // 否则主配置里残留的同名别名会透传进来。
+            env[aliasKey(tierUpper)] = v;
+            env[nameKey(tierUpper)] = v ? strip1m(v) : '';
+        }
+    }
+    else {
+        // exhaustive check：新增 mode 时编译期报错，防止漏处理分支。
+        const _exhaustive = state.mode;
+        throw new Error(`unhandled form mode: ${_exhaustive}`);
+    }
+    env.CLAUDE_CODE_ATTRIBUTION_HEADER = state.options.attributionHeader ? '1' : '0';
+    env.CLAUDE_CODE_DISABLE_NONESSENTIAL_TRAFFIC = state.options.disableNonEssentialTraffic ? '1' : '0';
+    env.CLAUDE_CODE_AUTO_COMPACT_WINDOW = String(state.options.autoCompactWindow);
+    env.CLAUDE_CODE_EFFORT_LEVEL = state.options.effort;
+    // 解析 customParams JSON，将顶层 key-value 合并到 env
+    if (state.customParams && state.customParams.trim()) {
+        try {
+            const parsed = JSON.parse(state.customParams);
+            if (parsed && typeof parsed === 'object') {
+                for (const [k, v] of Object.entries(parsed)) {
+                    if (v !== undefined && v !== null) {
+                        env[k] = String(v);
+                    }
+                }
+            }
+        }
+        catch {
+            // 解析失败应在 validateState 阶段拦截，此处静默忽略
+        }
+    }
+    const result = { env };
+    if (state.mode === 'alias') {
+        // model 仅 alias 模式记录初始档位（供 ccs 启动参数与菜单展示）。
+        result.model = state.tier;
+    }
+    return result;
+}
+/** 提交前校验：必填项是否齐全。返回错误消息或 null。 */
+export function validateState(state) {
+    if (!state.baseUrl || !state.baseUrl.trim())
+        return t('form.baseUrlValidate');
+    if (state.mode === 'single' && (!state.singleModel || !state.singleModel.trim())) {
+        return t('form.modelValidate');
+    }
+    // customParams 非空时需合法 JSON
+    if (state.customParams && state.customParams.trim()) {
+        try {
+            JSON.parse(state.customParams);
+        }
+        catch {
+            return t('form.customParamsValidate');
+        }
+    }
+    return null;
+}
+// ---------- form entry ----------
+/**
+ * 持久化 Tab 表单（ink）：API Key / Models / Options / Review（预览+提交）。
+ * Tab 切换时下方内容跟随变化，字段直接原地编辑，无需 Enter 进入。
+ * create/edit 共用。委托给 formUi.runProviderForm。
+ *
+ * @param opts
+ * @param opts.initial  已有 settings（edit 时预填）
+ * @param opts.preset   预设（create 时预填，可为 null=自定义）
+ * @returns 最终 settings 片段
+ */
+export async function providerFormWithPreview(opts = {}) {
+    const { initial = {}, preset = null, title } = opts;
+    const runOpts = { initial, preset };
+    if (title !== undefined)
+        runOpts.title = title;
+    return runProviderForm(runOpts);
+}

package/dist/formUi.d.ts

@@ -0,0 +1,30 @@
+import { ALIAS_TIERS } from './form.js';
+import type { FormState, Preset, ProviderSettings } from './types.js';
+type FieldKind = 'text' | 'password' | 'toggle' | 'select' | 'number' | 'button';
+type FieldId = 'baseUrl' | 'token' | 'authMethod' | 'singleModel' | `alias_${typeof ALIAS_TIERS[number]}` | 'autoCompactWindow' | 'tier' | 'effort' | 'customParams' | 'attributionHeader' | 'disableNonEssentialTraffic' | 'aliases' | 'nextTab' | 'submit' | 'cancel';
+interface Field {
+    id: FieldId;
+    kind: FieldKind;
+    /** 若提供，则该 text 字段聚焦时在下方展开可搜索下拉（输入即过滤）。 */
+    support?: string[] | undefined;
+}
+/** 表单运行态：autoCompactWindow 以字符串编辑，提交时校验/转换。 */
+export interface RuntimeForm extends Omit<FormState, 'options'> {
+    options: Omit<FormState['options'], 'autoCompactWindow'> & {
+        autoCompactWindow: string;
+    };
+    /** 供应商支持的模型列表（用于模型字段的内联下拉）。 */
+    modelSupport?: string[] | undefined;
+}
+/** 当前 tab 的可聚焦字段列表（review 的 preview 是静态展示，不参与聚焦）。 */
+export declare function tabFields(form: RuntimeForm, tabIndex: number): Field[];
+interface RunOpts {
+    initial?: {
+        env?: Record<string, string>;
+        model?: string;
+    };
+    preset?: Preset | null;
+    title?: string;
+}
+export declare function runProviderForm(opts?: RunOpts): Promise<ProviderSettings>;
+export {};