llm-api-gateway-cli 1.0.0

package/cli-openai.js

@@ -0,0 +1,212 @@
+#!/usr/bin/env node
+/**
+ * 模式一 · OpenAI 兼容接入
+ *
+ * 通过官方 `openai` SDK 直连网关的 /v1/chat/completions，验证网关可以作为
+ * api.openai.com 的 drop-in 替代 —— 客户端只需把 baseURL 指到网关、apiKey
+ * 换成网关发放的 sk- 密钥，其余代码完全不变。
+ *
+ * 用法示例：
+ *   node cli-openai.js "你好，用一句话介绍你自己"
+ *   node cli-openai.js -p "你好" --model qwen3:8b --system "你是中文助手"
+ *   echo "你好" | node cli-openai.js
+ *   node cli-openai.js --list-models
+ *   node cli-openai.js -i                     # 多轮交互
+ *
+ * 另外：本脚本会额外发一个 W3C `baggage: session.id=<uuid>`（一次运行 = 一次对话），
+ * 好让网关后台的「任务树」把同一会话的多次请求聚成一条。这个头是**可选**的 ——
+ * 不发（或任何客户端不发）功能完全不受影响，网关会退回自己的推断口径。
+ *
+ * 密钥来源（优先级从高到低）：--key 参数 > 环境变量 SK / GATEWAY_KEY / OPENAI_API_KEY > .env 文件
+ * 配置解析统一在 lib/config.js —— 四个入口共用一套优先级，不再各写一份。
+ */
+
+import OpenAI from 'openai';
+import { fileURLToPath } from 'node:url';
+import path from 'node:path';
+import readline from 'node:readline';
+import { randomUUID } from 'node:crypto';
+
+import { loadDotEnv, parseArgs, sessionBaggage, DEFAULT_BASE_URL } from './lib/common.js';
+import { resolveConfig, fail, KEY_HINT } from './lib/config.js';
+
+const SCRIPT_DIR = path.dirname(fileURLToPath(import.meta.url));
+loadDotEnv(SCRIPT_DIR); // 先加载 .env，让 GATEWAY_MODEL 等环境变量参与默认值计算
+
+const DEFAULT_MODEL = process.env.GATEWAY_MODEL || 'qwen3:8b';
+
+const HELP = `用法：node cli-openai.js [选项] [提示词]
+
+选项：
+  -p, --prompt <文本>      单轮提问内容（省略则读位置参数 / 标准输入）
+  -s, --system <文本>      system 提示词
+  -m, --model <模型>       模型名（默认 ${DEFAULT_MODEL}）
+  -k, --key <sk-密钥>      网关发放的密钥（也可用环境变量 SK/GATEWAY_KEY/OPENAI_API_KEY 或 .env）
+      --base-url <地址>    网关地址（默认 ${DEFAULT_BASE_URL}）
+      --temperature <值>   采样温度
+      --max-tokens <值>    最大生成 token 数
+      --no-stream          关闭流式输出（默认开启）
+      --json               输出完整原始响应（非流式）
+      --list-models        列出上游可用模型
+  -i, --interactive        进入多轮交互（REPL）
+  -h, --help               显示帮助
+`;
+
+// 值型选项：会消费下一个参数作为值；布尔型选项：不消费后续参数
+const VALUE_FLAGS = {
+  '--prompt': 'prompt', '-p': 'prompt',
+  '--system': 'system', '-s': 'system',
+  '--model': 'model', '-m': 'model',
+  '--key': 'key', '-k': 'key',
+  '--base-url': 'base-url',
+  '--temperature': 'temperature',
+  '--max-tokens': 'max-tokens',
+};
+const BOOL_FLAGS = {
+  '--no-stream': 'no-stream',
+  '--json': 'json',
+  '--list-models': 'list-models',
+  '--interactive': 'interactive', '-i': 'interactive',
+  '--help': 'help', '-h': 'help',
+};
+
+function readStdin() {
+  return new Promise((resolve) => {
+    if (process.stdin.isTTY) return resolve('');
+    let data = '';
+    process.stdin.setEncoding('utf8');
+    process.stdin.on('data', (c) => (data += c));
+    process.stdin.on('end', () => resolve(data.trim()));
+    process.stdin.on('error', () => resolve(''));
+  });
+}
+
+function fmtUsage(u) {
+  if (!u) return null;
+  const p = u.prompt_tokens ?? '?';
+  const c = u.completion_tokens ?? '?';
+  const t = u.total_tokens ?? (Number.isFinite(p) && Number.isFinite(c) ? p + c : '?');
+  return `输入 ${p} / 输出 ${c} / 合计 ${t} tokens`;
+}
+
+// ---------- 主流程 ----------
+
+async function main() {
+  const args = parseArgs(process.argv.slice(2), VALUE_FLAGS, BOOL_FLAGS);
+
+  if (args.help) {
+    console.log(HELP);
+    return;
+  }
+
+  const { key, baseUrl, model, temperature, maxTokens } = resolveConfig(args, { defaultModel: DEFAULT_MODEL });
+
+  if (!key) {
+    console.error(`[错误] ${KEY_HINT}`);
+    process.exit(1);
+  }
+
+  // 一次进程运行 = 一次对话。把这个身份用 W3C baggage 告诉网关，它才能把同一会话的
+  // 多次请求聚成一条；这是标准头，不是为网关自造的私有约定，上游不认识也只会原样忽略。
+  const sessionId = randomUUID();
+  const baggage = sessionBaggage(sessionId);
+  // 打到 stderr，便于在后台「任务树」里按这个 id 对号入座
+  if (baggage) process.stderr.write(`[gateway] 会话 ${sessionId}（W3C baggage: session.id）\n`);
+
+  const client = new OpenAI({
+    baseURL: `${baseUrl}/v1`,
+    apiKey: key,
+    ...(baggage ? { defaultHeaders: { baggage } } : {}),
+  });
+
+  if (args['list-models']) {
+    try {
+      const res = await client.models.list();
+      const ids = (res.data || []).map((m) => m.id);
+      console.log(ids.length ? ids.join('\n') : '(上游未返回模型列表)');
+    } catch (e) {
+      fail(e);
+    }
+    return;
+  }
+
+  const stream = !args['no-stream'];
+
+  if (args.interactive) {
+    await repl(client, model, { stream, temperature, maxTokens, baseUrl });
+    return;
+  }
+
+  let prompt = args.prompt ?? '';
+  if (!prompt && args._.length) prompt = args._.join(' ');
+  if (!prompt) prompt = await readStdin();
+  if (!prompt) {
+    console.log(HELP);
+    return;
+  }
+
+  const messages = [];
+  if (args.system) messages.push({ role: 'system', content: args.system });
+  messages.push({ role: 'user', content: prompt });
+
+  await chat(client, model, messages, { stream, temperature, maxTokens, json: args.json, baseUrl });
+}
+
+/**
+ * @param {boolean} opts.exitOnError 单轮/管道模式为 true（失败要非零退出，脚本才判断得出）；
+ *   交互模式为 false —— 一次请求失败不该把整个 REPL 结束掉。
+ */
+async function chat(client, model, messages, { stream, temperature, maxTokens, json, baseUrl, exitOnError = true }) {
+  const req = { model, messages, stream, temperature, max_tokens: maxTokens };
+  if (stream) req.stream_options = { include_usage: true }; // 让上游在流末回传 usage
+
+  process.stderr.write(`[gateway] model=${model} base=${baseUrl} stream=${stream}\n`);
+  try {
+    const resp = await client.chat.completions.create(req);
+    if (stream) {
+      let usage = null;
+      for await (const chunk of resp) {
+        const delta = chunk.choices?.[0]?.delta?.content;
+        if (delta) process.stdout.write(delta);
+        if (chunk.usage) usage = chunk.usage;
+      }
+      process.stdout.write('\n');
+      const u = fmtUsage(usage);
+      if (u) process.stderr.write(`[usage] ${u}\n`);
+    } else {
+      const choice = resp.choices?.[0] || {};
+      if (json) {
+        console.log(JSON.stringify(resp, null, 2));
+      } else {
+        console.log(choice.message?.content ?? '');
+      }
+      const u = fmtUsage(resp.usage);
+      if (u) process.stderr.write(`[usage] ${u}\n`);
+    }
+  } catch (e) {
+    fail(e, { exit: exitOnError });
+  }
+}
+
+async function repl(client, model, opts) {
+  console.error(`[gateway] 交互模式 model=${model}，输入文本提问，\`exit\` 退出`);
+  const rl = readline.createInterface({ input: process.stdin, output: process.stdout });
+  const messages = [];
+  const ask = () => new Promise((resolve) => rl.question('你> ', resolve));
+  for (;;) {
+    let line;
+    try {
+      line = (await ask()).trim();
+    } catch {
+      break; // 输入流关闭（Ctrl+D）
+    }
+    if (!line) continue;
+    if (/^(exit|quit)$/i.test(line)) break;
+    messages.push({ role: 'user', content: line });
+    process.stdout.write('助手> ');
+    await chat(client, model, messages, { ...opts, json: false, exitOnError: false });
+  }
+  rl.close();
+}
+
+main();

package/completions/_llm-api-gateway-cli

@@ -0,0 +1,65 @@
+#compdef llm-api-gateway-cli gateway-agent
+# zsh 补全 · cli-agent.js
+#
+# 用法（任选其一）：
+#   source completions/_llm-api-gateway-cli                       # 当前 shell 生效
+#   把本文件所在目录加进 $fpath 后 `compinit`（文件名必须是 _llm-api-gateway-cli）
+
+_llm_api_gateway_cli() {
+  local -a opts
+  # 配置键清单必须与 lib/settings.js 的 SETTINGS_SCHEMA 一致（tests/settings.test.mjs 里有契约断言盯着）
+  local -a config_keys
+  config_keys=(
+    model baseUrl temperature maxTokens system mode maxSteps lastWorkDir
+    store.dir store.sessionDir retention.days retention.maxTasks
+    session.maxBytes history.maxChars history.keepRecentTurns history.readFileDigest
+    ui.persist compat.legacyTaskApi
+  )
+  opts=(
+    '(-p --prompt)'{-p,--prompt}'[单轮任务]:文本:'
+    '(-i --interactive)'{-i,--interactive}'[多轮交互（REPL）]'
+    '(-C --cwd)'{-C,--cwd}'[工作目录]:目录:_files -/'
+    '(-m --model)'{-m,--model}'[模型名]:模型:'
+    '(-k --key)'{-k,--key}'[网关密钥]:密钥:'
+    '--base-url[网关地址]:地址:'
+    '(-s --system)'{-s,--system}'[追加的系统提示词]:文本:'
+    '--temperature[采样温度]:值:'
+    '--max-tokens[最大生成 token 数]:值:'
+    '--max-steps[单个任务最多几轮模型调用]:轮数:'
+    '--continue[接着最近一次会话继续]'
+    '--resume[恢复指定会话]:会话id:'
+    '--session-dir[会话落盘目录]:目录:_files -/'
+    '--no-session[不落盘会话（纯内存）]'
+    '--no-memory[不读取项目记忆]'
+    '--allow-bash[开启 bash 工具（默认关闭）]'
+    '--output-format[输出格式]:格式:(text stream-json)'
+    '--yes[自动批准所有写入（危险）]'
+    '--verbose[打印工具结果正文]'
+    '--no-color[关闭彩色输出]'
+    '(-h --help)'{-h,--help}'[显示帮助]'
+    '1:子命令:((config\:查看或修改持久化配置))'
+    '*:文件:_files'
+  )
+  _arguments -s $opts
+
+  # config 的第二层：list/get/set/unset/path，get/unset/set 后面补键名
+  if [[ "$words[2]" == "config" ]]; then
+    case "$words[3]" in
+      get | unset)
+        _describe -t keys '配置键' config_keys
+        ;;
+      set)
+        if (( CURRENT == 4 )); then
+          _describe -t keys '配置键' config_keys
+        else
+          _message '值（字符串带空格就整段写上）'
+        fi
+        ;;
+      '')
+        _values '子命令' list get set unset path help
+        ;;
+    esac
+  fi
+}
+
+_llm_api_gateway_cli "$@"

package/completions/llm-api-gateway-cli.bash

@@ -0,0 +1,64 @@
+# bash 补全 · cli-agent.js（命令名 llm-api-gateway-cli / gateway-agent）
+#
+# 用法（任选其一）：
+#   source completions/llm-api-gateway-cli.bash          # 当前 shell 生效
+#   cp completions/llm-api-gateway-cli.bash /etc/bash_completion.d/   # 系统级（Linux）
+#   cp completions/llm-api-gateway-cli.bash ~/.local/share/bash-completion/completions/llm-api-gateway-cli
+
+_llm_api_gateway_cli() {
+  local cur prev
+  cur="${COMP_WORDS[COMP_CWORD]}"
+  prev="${COMP_WORDS[COMP_CWORD-1]}"
+
+  local opts="--prompt -p --interactive -i --cwd -C --model -m --key -k --base-url --system -s --temperature --max-tokens --max-steps --continue --resume --session-dir --no-session --no-memory --allow-bash --output-format --yes --verbose --no-color --help -h"
+  # 配置键清单必须与 lib/settings.js 的 SETTINGS_SCHEMA 一致（tests/settings.test.mjs 里有契约断言盯着）
+  local config_keys="model baseUrl temperature maxTokens system mode maxSteps lastWorkDir store.dir store.sessionDir retention.days retention.maxTasks session.maxBytes history.maxChars history.keepRecentTurns history.readFileDigest ui.persist compat.legacyTaskApi"
+
+  # 子命令 config：补子命令本身、以及 set/get/unset 后面的键名
+  if [[ "${COMP_WORDS[1]}" == "config" ]]; then
+    case "$prev" in
+      config)
+        COMPREPLY=($(compgen -W "list get set unset path help" -- "$cur"))
+        return
+        ;;
+      get | unset)
+        COMPREPLY=($(compgen -W "$config_keys" -- "$cur"))
+        return
+        ;;
+      set)
+        # 第 3 个词是键，第 4 个起是自由文本的值，不再补全
+        if [[ "$COMP_CWORD" == 3 ]]; then
+          COMPREPLY=($(compgen -W "$config_keys" -- "$cur"))
+        fi
+        return
+        ;;
+      list | path)
+        return
+        ;;
+    esac
+  fi
+
+  case "$prev" in
+    -C | --cwd | --session-dir)
+      COMPREPLY=($(compgen -d -- "$cur"))
+      return
+      ;;
+    --output-format)
+      COMPREPLY=($(compgen -W "text stream-json" -- "$cur"))
+      return
+      ;;
+    -p | --prompt | -m | --model | -k | --key | -s | --system | --base-url | --temperature | --max-tokens | --max-steps | --resume)
+      return # 需要自由文本，不做补全
+      ;;
+  esac
+
+  if [[ "$cur" == -* ]]; then
+    COMPREPLY=($(compgen -W "$opts" -- "$cur"))
+  elif [[ "$COMP_CWORD" == 1 ]]; then
+    COMPREPLY=($(compgen -W "config" -- "$cur"))
+  else
+    COMPREPLY=($(compgen -f -- "$cur"))
+  fi
+}
+
+complete -F _llm_api_gateway_cli llm-api-gateway-cli gateway-agent

package/completions/llm-api-gateway-cli.fish

@@ -0,0 +1,43 @@
+# fish 补全 · cli-agent.js（命令名 llm-api-gateway-cli / gateway-agent）
+#
+# 用法：
+#   cp completions/llm-api-gateway-cli.fish ~/.config/fish/completions/
+
+set -l cmd llm-api-gateway-cli
+
+complete -c $cmd -s p -l prompt -d '单轮任务' -r
+complete -c $cmd -s i -l interactive -d '多轮交互（REPL）'
+complete -c $cmd -s C -l cwd -d '工作目录' -r -a '(__fish_complete_directories)'
+complete -c $cmd -s m -l model -d '模型名' -r
+complete -c $cmd -s k -l key -d '网关密钥' -r
+complete -c $cmd -l base-url -d '网关地址' -r
+complete -c $cmd -s s -l system -d '追加的系统提示词' -r
+complete -c $cmd -l temperature -d '采样温度' -r
+complete -c $cmd -l max-tokens -d '最大生成 token 数' -r
+complete -c $cmd -l max-steps -d '单个任务最多几轮模型调用' -r
+complete -c $cmd -l continue -d '接着最近一次会话继续'
+complete -c $cmd -l resume -d '恢复指定会话' -r
+complete -c $cmd -l session-dir -d '会话落盘目录' -r -a '(__fish_complete_directories)'
+complete -c $cmd -l no-session -d '不落盘会话（纯内存）'
+complete -c $cmd -l no-memory -d '不读取项目记忆'
+complete -c $cmd -l allow-bash -d '开启 bash 工具（默认关闭）'
+complete -c $cmd -l output-format -d '输出格式' -r -a 'text stream-json'
+complete -c $cmd -l yes -d '自动批准所有写入（危险）'
+complete -c $cmd -l verbose -d '打印工具结果正文'
+complete -c $cmd -l no-color -d '关闭彩色输出'
+complete -c $cmd -s h -l help -d '显示帮助'
+
+# `config` 子命令：键清单必须与 lib/settings.js 的 SETTINGS_SCHEMA 一致
+# （tests/settings.test.mjs 里有契约断言盯着）
+set -l cfg_keys model baseUrl temperature maxTokens system mode maxSteps lastWorkDir \
+  store.dir store.sessionDir retention.days retention.maxTasks \
+  session.maxBytes history.maxChars history.keepRecentTurns history.readFileDigest \
+  ui.persist compat.legacyTaskApi
+
+complete -c $cmd -n '__fish_use_subcommand' -a config -d '查看或修改持久化配置'
+complete -c $cmd -n '__fish_seen_subcommand_from config' -a 'list get set unset path help'
+complete -c $cmd -n '__fish_seen_subcommand_from config; and __fish_seen_subcommand_from get unset' -a "$cfg_keys"
+complete -c $cmd -n '__fish_seen_subcommand_from config; and __fish_seen_subcommand_from set; and test (count (commandline -opc)) -eq 3' -a "$cfg_keys"
+
+# gateway-agent 是同一个脚本的别名，共用这套补全
+complete -c gateway-agent -w $cmd