@alilis/k-hat 0.1.0 → 0.2.1

package/README.md

@@ -86,14 +86,14 @@ khat stop
 
 | 命令 | 说明 |
 |---|---|
-| `khat init` | 首次初始化：创建密钥库 + 访问令牌 + 默认配置 |
-| `khat start` | 后台启动代理与 supervisor；使用 `--foreground` 以前台模式诊断 |
+| `khat init` | 首次初始化：创建密钥库 + 访问令牌 + 默认配置；可用 `--port <n>` 指定监听端口 |
+| `khat start` | 后台启动代理与 supervisor；使用 `--foreground` 以前台模式诊断，使用 `--port <n>` 修改并持久化监听端口 |
 | `khat stop` | 请求后台代理优雅停止 |
 | `khat status` | 查看 Provider、key、路由及 key 健康状态 |
 | `khat doctor` | 检测本机 Agent Tool 配置并输出接入提示 |
 | `khat log [--tail <n>]` | 查看最近的脱敏请求日志 |
 | `khat ui` | 签发一次性票据并打开本地管理页 |
-| `khat tui` | 在交互式终端中查看 daemon 状态、Provider/Key、路由和请求日志 |
+| `khat tui` | 终端监控面板：跨 Provider 的 key 健康表（不可用排最前，`e` 一键恢复、`p` 探活）、请求日志与诊断，Tab/1-4 切换区块 |
 
 > Provider、key 和路由的新增、更新、删除与恢复等管理变更通过本地 Admin API 执行；若 daemon 尚未运行，命令会自动启动它。
 

package/dist/admin.js

@@ -1,4 +1,4 @@
-import { addProvider, updateProvider, removeProvider, addKey, updateKey, removeKey, enableKey, addRoute, updateRoute, removeRoute, maskSecret } from './store.js';
+import { addProvider, updateProvider, removeProvider, addKey, updateKey, removeKey, enableKey, setKeyEnabled, addRoute, updateRoute, setRouteEnabled, removeRoute, maskSecret } from './store.js';
 import { LogWriter } from './logger.js';
 import { join } from 'node:path';
 import { UiSessions, serveUi } from './web-ui.js';
@@ -8,6 +8,15 @@ import { ACCESS_TOKEN_REF, generateAccessToken } from './vault.js';
 // client or a process without the token cannot mutate config/state/vault.
 const LOOPBACK = new Set(['127.0.0.1', '::1', '::ffff:127.0.0.1']);
 const uiSessions = new UiSessions();
+const ANTHROPIC_VERSION = '2023-06-01';
+function upstreamHeaders(protocol, secret, contentType = false) {
+    const headers = protocol === 'anthropic'
+        ? { 'x-api-key': secret, 'anthropic-version': ANTHROPIC_VERSION }
+        : { authorization: `Bearer ${secret}` };
+    if (contentType)
+        headers['content-type'] = 'application/json';
+    return headers;
+}
 function json(res, status, value) {
     res.writeHead(status, { 'content-type': 'application/json' });
     res.end(JSON.stringify(value));
@@ -23,6 +32,25 @@ async function readJsonBody(req) {
         throw new Error('Invalid JSON body');
     }
 }
+async function listProviderModels(store, providerId) {
+    const provider = store.config.providers.find((item) => item.id === providerId);
+    if (!provider)
+        throw new Error(`unknown provider: ${providerId}`);
+    const key = provider.keys.find((item) => item.enabled !== false && store.states[`${provider.id}/${item.id}`]?.status !== 'unavailable');
+    if (!key)
+        throw new Error('provider has no available key');
+    const secret = store.vault.get(key.vaultRef);
+    if (!secret)
+        throw new Error('provider key secret is missing');
+    const headers = upstreamHeaders(provider.protocol, secret);
+    const response = await fetch(new URL('/v1/models', provider.baseUrl), { headers, signal: AbortSignal.timeout(10_000) });
+    if (!response.ok)
+        throw new Error(`model query failed with HTTP ${response.status}`);
+    const body = await response.json();
+    const values = Array.isArray(body?.data) ? body.data : Array.isArray(body?.models) ? body.models : [];
+    const ids = values.map((item) => typeof item === 'string' ? item : item?.id).filter((id) => typeof id === 'string' && id.length > 0);
+    return Array.from(new Set(ids)).sort();
+}
 function buildStatus(store) {
     const token = store.vault.get(ACCESS_TOKEN_REF);
     return {
@@ -39,6 +67,7 @@ function buildStatus(store) {
                 return {
                     id: key.id,
                     weight: key.weight,
+                    ...(key.enabled === false ? { enabled: false } : {}),
                     status: state?.status === 'unavailable' ? 'unavailable' : 'available',
                     lastError: state?.lastError,
                     secret: secret ? maskSecret(secret) : null,
@@ -46,7 +75,7 @@ function buildStatus(store) {
                 };
             })
         })),
-        routes: store.config.routes
+        routes: store.config.routes.map((route) => route.enabled === false ? { ...route, enabled: false } : { model: route.model, provider: route.provider })
     };
 }
 async function route(req, res, store, sessionAuthorized = false) {
@@ -91,6 +120,8 @@ async function route(req, res, store, sessionAuthorized = false) {
         return json(res, 200, { logs: logs.filter((entry) => (!model || entry.model === model) && (!key || entry.key === key) && (!status || String(entry.status) === status)) });
     }
     if (sub[0] === 'providers') {
+        if (sub.length === 3 && sub[2] === 'models' && method === 'GET')
+            return json(res, 200, { models: await listProviderModels(store, sub[1]) });
         if (sub.length === 1 && method === 'POST') {
             const body = await readJsonBody(req);
             if (!body.id || !body.protocol || !body.baseUrl)
@@ -136,7 +167,11 @@ async function route(req, res, store, sessionAuthorized = false) {
             return json(res, 200, { ok: true });
         }
         if (sub.length === 5 && sub[2] === 'keys' && sub[4] === 'enable' && method === 'POST') {
-            await store.mutate(() => enableKey(store, sub[1], sub[3]));
+            await store.mutate(async () => { await setKeyEnabled(store, sub[1], sub[3], true); await enableKey(store, sub[1], sub[3]); });
+            return json(res, 200, { ok: true });
+        }
+        if (sub.length === 5 && sub[2] === 'keys' && sub[4] === 'disable' && method === 'POST') {
+            await store.mutate(() => setKeyEnabled(store, sub[1], sub[3], false));
             return json(res, 200, { ok: true });
         }
         if (sub.length === 5 && sub[2] === 'keys' && sub[4] === 'probe' && method === 'POST') {
@@ -149,7 +184,7 @@ async function route(req, res, store, sessionAuthorized = false) {
             if (!secret || !model)
                 throw new Error('a key and route model are required for probing');
             const path = provider.protocol === 'anthropic' ? '/v1/messages' : '/v1/chat/completions';
-            const headers = provider.protocol === 'anthropic' ? { 'content-type': 'application/json', 'x-api-key': secret, 'anthropic-version': '2023-06-01' } : { 'content-type': 'application/json', authorization: `Bearer ${secret}` };
+            const headers = upstreamHeaders(provider.protocol, secret, true);
             const body = provider.protocol === 'anthropic' ? { model, max_tokens: 1, messages: [{ role: 'user', content: 'ping' }] } : { model, max_tokens: 1, messages: [{ role: 'user', content: 'ping' }], stream: false };
             const response = await fetch(new URL(path, provider.baseUrl), { method: 'POST', headers: headers, body: JSON.stringify(body), signal: AbortSignal.timeout(30_000) });
             if (response.ok)
@@ -167,14 +202,20 @@ async function route(req, res, store, sessionAuthorized = false) {
         }
         if (sub.length === 2 && method === 'PUT') {
             const body = await readJsonBody(req);
-            if (!body.provider || typeof body.provider !== 'string')
-                throw new Error('provider is required');
-            await store.mutate(() => updateRoute(store, decodeURIComponent(sub[1]), body.provider));
+            if (body.provider !== undefined)
+                await store.mutate(() => updateRoute(store, decodeURIComponent(sub[1]), body.provider));
+            if (body.enabled !== undefined)
+                await store.mutate(() => setRouteEnabled(store, decodeURIComponent(sub[1]), body.enabled));
+            return json(res, 200, { ok: true });
+        }
+        if (sub.length === 2 && (sub[1] === 'enable' || sub[1] === 'disable') && method === 'POST') {
+            const model = url.searchParams.get('model');
+            if (!model)
+                throw new Error('model query parameter is required');
+            await store.mutate(() => setRouteEnabled(store, model, sub[1] === 'enable'));
             return json(res, 200, { ok: true });
         }
         if (sub.length === 1 && method === 'DELETE') {
-            // The model goes in the query string: model names are not restricted to
-            // the provider/key id alphabet and may contain characters unsafe in a path segment.
             const model = url.searchParams.get('model');
             if (!model)
                 throw new Error('model query parameter is required');

package/dist/cli.js

@@ -27,7 +27,8 @@ Usage: khat <command> [arguments]
 
 Setup
   init                                  first-time setup: create vault + access token + default config
-  start [--foreground]                  start the proxy as a background daemon (or foreground with --foreground)
+  start [--foreground] [--port <n>]     start the proxy as a background daemon (or foreground with --foreground);
+                                        --port <n> changes the persisted listen port
   stop                                  stop the background daemon
   status                                show providers, keys, routes and key health
   doctor                                detect local Agent Tools and show connection guidance
@@ -62,6 +63,9 @@ Routes
   route list
   route remove <model>
 
+Version
+  version | --version | -v              print the khat version
+
 Environment
   KHAT_HOME            data directory (default ~/.khat)
   KHAT_ACCESS_TOKEN    override the vault access token (mainly for tests)`;
@@ -103,6 +107,15 @@ function flagInt(flags, name, fallback) {
         throw new Error(`--${name} must be a positive integer`);
     return parsed;
 }
+function flagPort(flags, name) {
+    const value = flagString(flags, name);
+    if (value === undefined)
+        return undefined;
+    const parsed = Number(value);
+    if (!Number.isInteger(parsed) || parsed < 1 || parsed > 65535)
+        throw new Error(`--${name} must be an integer between 1 and 65535`);
+    return parsed;
+}
 async function promptSecret(label) {
     const rl = createInterface({ input: process.stdin, output: process.stdout });
     try {
@@ -244,10 +257,16 @@ async function runForeground() {
     process.once('SIGINT', shutdown);
     process.once('SIGTERM', shutdown);
 }
-async function runStart(foreground) {
+async function runStart(foreground, port) {
+    const store = await openInitializedStore();
+    if (port !== undefined && port !== store.config.port) {
+        if (await daemonRunning())
+            throw new Error(`khat is already running on port ${store.config.port}; run 'khat stop' first, then start with --port ${port}`);
+        store.config.port = port;
+        await store.saveConfig();
+    }
     if (foreground)
         return runForeground();
-    const store = await openInitializedStore();
     if (await daemonRunning())
         throw new Error('khat is already running; use khat stop first');
     const occupiedPid = await findListeningPid(store.config.port);
@@ -412,18 +431,23 @@ async function runImport(path, force) {
     await importPortable(path, dataDir, createKeyProtector(), password, force);
     console.log(`imported encrypted vault into ${dataDir}`);
 }
-async function runInit() {
+async function runVersion() {
+    const pkg = JSON.parse(await readFile(new URL('../package.json', import.meta.url), 'utf8'));
+    console.log(pkg.version);
+}
+async function runInit(port) {
     await mkdir(dataDir, { recursive: true, mode: 0o700 });
     if (await fileExists(configPath)) {
         console.error(`already initialized at ${configPath} (delete the directory to start over)`);
         process.exitCode = 1;
         return;
     }
+    const config = port === undefined || port === defaultConfig.port ? defaultConfig : { ...defaultConfig, port };
     const vault = await Vault.create(vaultPath, createKeyProtector());
     const token = generateAccessToken();
     vault.set(ACCESS_TOKEN_REF, token);
     await vault.save();
-    await saveJsonAtomic(configPath, defaultConfig);
+    await saveJsonAtomic(configPath, config);
     await saveJsonAtomic(statePath, { keys: {} });
     console.log(`Initialized ${dataDir}`);
     console.log();
@@ -431,7 +455,7 @@ async function runInit() {
     console.log(`  ${token}`);
     console.log();
     console.log('Point your tools at the proxy, e.g.:');
-    console.log(`  base URL:      http://${defaultConfig.bind}:${defaultConfig.port}/v1`);
+    console.log(`  base URL:      http://${config.bind}:${config.port}/v1`);
     console.log(`  Authorization: Bearer ${token}`);
 }
 const [command, ...rest] = process.argv.slice(2);
@@ -443,8 +467,13 @@ try {
         case '-h':
             console.log(USAGE);
             break;
+        case 'version':
+        case '--version':
+        case '-v':
+            await runVersion();
+            break;
         case 'init':
-            await runInit();
+            await runInit(flagPort(flags, 'port'));
             break;
         case 'export':
             await runExport(positionals[0]);
@@ -453,7 +482,7 @@ try {
             await runImport(positionals[0], flags.force === true);
             break;
         case 'start':
-            await runStart(flags.foreground === true);
+            await runStart(flags.foreground === true, flagPort(flags, 'port'));
             break;
         case 'stop':
             await runStop();

package/dist/config.js

@@ -42,6 +42,9 @@ export function validateConfig(config) {
                 throw new Error(`Invalid timeouts.${field}: expected a positive integer`);
         }
     }
+    if (!Number.isInteger(config.port) || config.port < 1 || config.port > 65535) {
+        throw new Error('Invalid config: port must be an integer between 1 and 65535');
+    }
     for (const provider of config.providers) {
         if (!provider.id || !provider.baseUrl || (provider.protocol !== 'openai' && provider.protocol !== 'anthropic') || !Array.isArray(provider.keys))
             throw new Error(`Invalid provider: ${provider.id}`);
@@ -59,6 +62,8 @@ export function validateConfig(config) {
         for (const key of provider.keys) {
             if (!key.id || !Number.isInteger(key.weight) || key.weight < 1)
                 throw new Error(`Invalid key in provider ${provider.id}`);
+            if (key.enabled !== undefined && typeof key.enabled !== 'boolean')
+                throw new Error(`Invalid key ${provider.id}/${key.id}: enabled must be boolean`);
             if (key.vaultRef !== `${provider.id}/${key.id}`)
                 throw new Error(`Invalid key ${provider.id}/${key.id}: vaultRef must match provider and key id`);
         }
@@ -66,6 +71,8 @@ export function validateConfig(config) {
     for (const route of config.routes) {
         if (!route.model || !route.provider)
             throw new Error('Invalid route: model and provider are required');
+        if (route.enabled !== undefined && typeof route.enabled !== 'boolean')
+            throw new Error(`Invalid route ${route.model}: enabled must be boolean`);
         if (!config.providers.some((item) => item.id === route.provider))
             throw new Error(`Invalid route ${route.model}: unknown provider ${route.provider}`);
     }

package/dist/router.js

@@ -1,10 +1,18 @@
-export function resolveProvider(config, model) {
+export function findRoute(config, model) {
     const slash = model.indexOf('/');
     if (slash > 0) {
         const providerId = model.slice(0, slash);
-        const provider = config.providers.find((item) => item.id === providerId);
-        return provider && config.routes.some((route) => route.provider === providerId && route.model === model.slice(slash + 1)) ? provider : undefined;
+        const routeModel = model.slice(slash + 1);
+        return config.routes.find((route) => route.provider === providerId && route.model === routeModel);
     }
-    const route = config.routes.find((item) => item.model === model);
-    return route ? config.providers.find((item) => item.id === route.provider) : undefined;
+    return config.routes.find((route) => route.model === model);
+}
+export function resolveProvider(config, model) {
+    const route = findRoute(config, model);
+    if (!route || route.enabled === false)
+        return undefined;
+    return config.providers.find((item) => item.id === route.provider);
+}
+export function isRouteDisabled(config, model) {
+    return findRoute(config, model)?.enabled === false;
 }

package/dist/selector.js

@@ -1,7 +1,7 @@
 export class WeightedSelector {
     current = new Map();
     select(providerId, keys, states) {
-        const available = keys.filter((key) => states[`${providerId}/${key.id}`]?.status !== 'unavailable');
+        const available = keys.filter((key) => key.enabled !== false && states[`${providerId}/${key.id}`]?.status !== 'unavailable');
         if (!available.length)
             return undefined;
         let total = 0;

package/dist/server.js

@@ -3,7 +3,7 @@ import { watch } from 'node:fs';
 import { readJsonFile, saveJsonAtomic, validateConfig, defaultTimeouts } from './config.js';
 import { LogWriter } from './logger.js';
 import { join, basename } from 'node:path';
-import { resolveProvider } from './router.js';
+import { resolveProvider, isRouteDisabled } from './router.js';
 import { WeightedSelector } from './selector.js';
 import { handleAdmin } from './admin.js';
 import { ACCESS_TOKEN_REF } from './vault.js';
@@ -102,8 +102,11 @@ export function createKhatServer(options) {
             if (!parsed.model || typeof parsed.model !== 'string')
                 return json(res, 400, { error: { message: 'model is required' } });
             const provider = resolveProvider(options.config, parsed.model);
-            if (!provider)
+            if (!provider) {
+                if (isRouteDisabled(options.config, parsed.model))
+                    return json(res, 403, { error: { message: `Route disabled for model: ${parsed.model}` } });
                 return json(res, 404, { error: { message: `No route for model: ${parsed.model}` } });
+            }
             if (provider.protocol !== protocol)
                 return json(res, 400, { error: { message: `Model ${parsed.model} resolves to a ${provider.protocol} provider, but ${req.url} speaks ${protocol}` } });
             const tried = new Set();
@@ -182,13 +185,18 @@ export function createKhatServer(options) {
                         clearTimeout(idleTimer);
                     }
                 }
-                res.end();
-                res.off('close', clientGone);
                 const durationMs = Date.now() - startedAt;
                 const ttfbMs = (firstByteAt ?? Date.now()) - startedAt;
                 const keyRef = `${provider.id}/${key.id}`;
                 options.store?.recordCounter(keyRef, { requests: 1, failed: upstream.ok ? 0 : 1, bytesOut: bytes, tokensIn, tokensOut });
-                void logger?.append({ ts: new Date().toISOString(), event: 'forward', model: parsed.model, provider: provider.id, key: keyRef, status: upstream.status, ttfbMs, durationMs, bytes, tokensIn, tokensOut });
+                try {
+                    await logger?.append({ ts: new Date().toISOString(), event: 'forward', model: parsed.model, provider: provider.id, key: keyRef, status: upstream.status, ttfbMs, durationMs, bytes, tokensIn, tokensOut });
+                }
+                catch (error) {
+                    console.error(`[khat] failed to write request log: ${error?.message ?? error}`);
+                }
+                res.end();
+                res.off('close', clientGone);
                 return;
             }
         }

package/dist/store.js

@@ -195,6 +195,27 @@ export async function removeKey(store, providerId, keyId) {
     await store.vault.save();
     await store.saveState();
 }
+export async function setKeyEnabled(store, providerId, keyId, enabled) {
+    const provider = findProvider(store, providerId);
+    const key = provider.keys.find((item) => item.id === keyId);
+    if (!key)
+        throw new Error(`unknown key: ${providerId}/${keyId}`);
+    const previous = key.enabled;
+    if (enabled)
+        delete key.enabled;
+    else
+        key.enabled = false;
+    try {
+        await persistConfig(store);
+    }
+    catch (error) {
+        if (previous === undefined)
+            delete key.enabled;
+        else
+            key.enabled = previous;
+        throw error;
+    }
+}
 export async function enableKey(store, providerId, keyId) {
     const provider = findProvider(store, providerId);
     if (!provider.keys.some((item) => item.id === keyId))
@@ -231,6 +252,26 @@ export async function updateRoute(store, model, providerId) {
         throw error;
     }
 }
+export async function setRouteEnabled(store, model, enabled) {
+    const route = store.config.routes.find((item) => item.model === model);
+    if (!route)
+        throw new Error(`unknown route: ${model}`);
+    const previous = route.enabled;
+    if (enabled)
+        delete route.enabled;
+    else
+        route.enabled = false;
+    try {
+        await persistConfig(store);
+    }
+    catch (error) {
+        if (previous === undefined)
+            delete route.enabled;
+        else
+            route.enabled = previous;
+        throw error;
+    }
+}
 export async function removeRoute(store, model) {
     const before = store.config.routes.length;
     store.config.routes = store.config.routes.filter((route) => route.model !== model);

package/dist/tui-client.js

@@ -51,6 +51,9 @@ export class AdminClient {
     async deleteKey(providerId, keyId) {
         await this.request(`/_keys/providers/${encodeURIComponent(providerId)}/keys/${encodeURIComponent(keyId)}`, { method: 'DELETE' });
     }
+    async disableKey(providerId, keyId) {
+        await this.request(`/_keys/providers/${encodeURIComponent(providerId)}/keys/${encodeURIComponent(keyId)}/disable`, { method: 'POST' });
+    }
     async enableKey(providerId, keyId) {
         await this.request(`/_keys/providers/${encodeURIComponent(providerId)}/keys/${encodeURIComponent(keyId)}/enable`, { method: 'POST' });
     }
@@ -63,6 +66,8 @@ export class AdminClient {
     async updateRoute(model, provider) {
         await this.request(`/_keys/routes/${encodeURIComponent(model)}`, { method: 'PUT', body: { provider } });
     }
+    async enableRoute(model) { await this.request(`/_keys/routes/enable?model=${encodeURIComponent(model)}`, { method: 'POST' }); }
+    async disableRoute(model) { await this.request(`/_keys/routes/disable?model=${encodeURIComponent(model)}`, { method: 'POST' }); }
     async deleteRoute(model) {
         await this.request(`/_keys/routes?model=${encodeURIComponent(model)}`, { method: 'DELETE' });
     }

package/dist/tui-state.js

@@ -0,0 +1,59 @@
+// Pure state and helpers for the TUI: key-table ordering, log filtering and
+// viewport slicing. No React, no I/O — directly unit-testable.
+export const SECTIONS = ['overview', 'routes', 'logs', 'diagnostics'];
+export const LOG_FILTERS = ['all', 'failed', 'ok'];
+export function keyRows(status) {
+    const rows = [];
+    for (const provider of status?.providers ?? []) {
+        for (const key of provider.keys)
+            rows.push({ providerId: provider.id, keyId: key.id, key });
+    }
+    return rows.sort((a, b) => {
+        const rank = (row) => (row.key.status === 'unavailable' ? 0 : 1);
+        const byRank = rank(a) - rank(b);
+        if (byRank !== 0)
+            return byRank;
+        const byProvider = a.providerId.localeCompare(b.providerId);
+        if (byProvider !== 0)
+            return byProvider;
+        return a.keyId.localeCompare(b.keyId);
+    });
+}
+export function providerOf(status, id) {
+    return status?.providers.find((item) => item.id === id);
+}
+/** Green = available, red = unavailable, yellow = available but failing often. */
+export function keyTone(key) {
+    if (key.status === 'unavailable')
+        return 'red';
+    return key.counters.failed > 0 ? 'yellow' : 'green';
+}
+export function filterLogs(logs, filter) {
+    if (filter === 'failed')
+        return logs.filter((entry) => entry.status >= 400);
+    if (filter === 'ok')
+        return logs.filter((entry) => entry.status < 400);
+    return logs;
+}
+export function newestFirst(logs) {
+    return [...logs].reverse();
+}
+/** Sliding window centered on the cursor, clamped to the list bounds. */
+export function viewport(length, cursor, height) {
+    if (height < 1 || length === 0)
+        return { start: 0, items: [], above: 0, below: 0 };
+    const size = Math.min(length, height);
+    const start = Math.min(Math.max(0, cursor - Math.floor(size / 2)), length - size);
+    const items = [];
+    for (let index = start; index < start + size; index++)
+        items.push(index);
+    return { start, items, above: start, below: length - (start + size) };
+}
+export function moveCursor(current, delta, length) {
+    if (length <= 0)
+        return 0;
+    return Math.min(length - 1, Math.max(0, current + delta));
+}
+export function clampCursor(current, length) {
+    return length <= 0 ? 0 : Math.min(current, length - 1);
+}