@wangmingfa/model-gate 0.0.1-beta.1 → 0.0.1-beta.2

package/README.md

@@ -4,56 +4,71 @@ LLM API 中转网关：在一个配置文件里配置多家运营商的模型（
 
 **解决什么问题**：你有很多 coding agent（Claude Code、Cursor、各种开源 agent），每个都要单独配置各家厂商的 base_url、api_key、模型名。有了 model-gate，agent 只认一个地址 + 一个 key + 一组**模型别名**；换上游、换模型、加厂商都只改网关的配置文件，热加载即生效，agent 侧零改动。
 
----
+## 安装
 
-## 特性
+model-gate 基于 [bun](https://bun.sh/) 运行时，推荐用 bun 全局安装（npm 亦可）。
 
-- **统一 OpenAI 兼容入口**：`POST /v1/chat/completions`（含流式 SSE）+ `GET /v1/models`
-- **模型别名**：agent 只认识别名（如 `fast`、`reason`），不感知背后的真实模型；响应与流式 chunk 中的 model 字段统一改写为别名
-- **有序 failover**：一个别名可绑多个 `provider:model`（数组，顺序即 failover 顺序）；管理界面里每个别名当前从下拉选一个目标（数组格式仍允许配置多个作为 failover 备选）
-- **多下游密钥**：多个 agent 各用一个 key，为按 agent 记账/排查打基础
-- **配置热加载**：改 `config.json` 立即生效，无需重启
-- **请求日志**：控制台每请求一行摘要 + `access.log`（JSONL）逐请求记录 token 用量，可开关
-- **密钥支持环境变量**：`api_key` 可以写 `${ENV_VAR}` 引用环境变量
-- **Web 配置界面**：`/admin` 下的 SPA（Vite+Vue3+Naive UI），可视化编辑提供商(provider)/别名/密钥/默认模型，保存即校验并热加载；本机回环免登录，非本机访问需 `admin_password` 密码登录；`api_key` 以密码框遮挡显示
+**方式一：bun（推荐）**
 
-## 快速开始
+```bash
+bun install -g @wangmingfa/model-gate
+```
 
-前置：安装 [bun](https://bun.sh/)（运行时依赖，版本 >= 1.0.0）：
+**方式二：npm**
 
 ```bash
-curl -fsSL https://bun.sh/install | bash
+npm install -g @wangmingfa/model-gate
 ```
 
+> 安装后会得到一个全局命令 `model-gate`（无需 clone 源码、无需 `bun install` 依赖）。
+
+## 使用
+
 ```bash
-# 1. 安装依赖（会同时安装 admin 子项目依赖）
-bun install
+# 1. 生成示例配置（在当前目录创建 config.json）
+model-gate init
 
-# 2. 复制示例配置并编辑（填你的各家 key）
-cp config.example.json config.json
+# 2. 编辑配置，填入你的各家厂商 key（见下文「配置」章节）
 vim config.json
 
-# 3. 开发模式（api 热重载 + Vite 前端热更新，开箱即用）
-bun run dev
+# 3. 启动网关（默认监听 127.0.0.1:8787，按 config.json 热加载）
+model-gate
+```
 
-# 3'. 生产构建：内联前端资源并打包成单文件二进制 model-gate.js
-bun run build
-bun run model-gate.js          # 运行构建产物（等同于 node 跑这个 bun 二进制）
+启动后：
 
-# 指定配置文件（开发/生产均可）:
-bun run dev -- --config /path/to/config.json
-# 或设环境变量 MODEL_GATE_CONFIG=/path/to/config.json
+- 网关地址：`http://127.0.0.1:8787`
+- OpenAI 兼容接口：`POST http://127.0.0.1:8787/v1/chat/completions`、`GET http://127.0.0.1:8787/v1/models`
+- Web 配置界面：`http://127.0.0.1:8787/admin`（本机回环免登录，非本机需 `admin_password`）
+
+agent 侧只需配置一处即可接入：
+
+```jsonc
+// 以任意 OpenAI 兼容 client 为例
+{
+  "base_url": "http://127.0.0.1:8787/v1",
+  "api_key": "<你在 /admin 里生成的下游密钥>",
+  "model": "fast"   // 模型别名，不暴露真实模型名
+}
 ```
 
+---
+
+## 特性
+
+- **统一 OpenAI 兼容入口**：`POST /v1/chat/completions`（含流式 SSE）+ `GET /v1/models`
+- **模型别名**：agent 只认识别名（如 `fast`、`reason`），不感知背后的真实模型；响应与流式 chunk 中的 model 字段统一改写为别名
+- **有序 failover**：一个别名可绑多个 `provider:model`（数组，顺序即 failover 顺序）；管理界面里每个别名当前从下拉选一个目标（数组格式仍允许配置多个作为 failover 备选）
+- **多下游密钥**：多个 agent 各用一个 key，为按 agent 记账/排查打基础
+- **配置热加载**：改 `config.json` 立即生效，无需重启
+- **请求日志**：控制台每请求一行摘要 + `access.log`（JSONL）逐请求记录 token 用量，可开关
+- **密钥支持环境变量**：`api_key` 可以写 `${ENV_VAR}` 引用环境变量
+- **Web 配置界面**：`/admin` 下的 SPA（Vite+Vue3+Naive UI），可视化编辑提供商(provider)/别名/密钥/默认模型，保存即校验并热加载；本机回环免登录，非本机访问需 `admin_password` 密码登录；`api_key` 以密码框遮挡显示
+
 ## Web 配置界面（/admin）
 
 不用手改 JSON，浏览器里可视化编辑配置：
 
-```bash
-bun run build   # 构建并内联前端资源（Vite 产物 admin/dist/ → src/admin-assets.generated.ts → 打包进二进制）
-bun run model-gate.js   # 启动网关（或开发模式 bun run dev）
-```
-
 打开浏览器：
 
 - **本机访问**：`http://127.0.0.1:8787/admin`（免登录直接进入）
@@ -64,7 +79,6 @@ bun run model-gate.js   # 启动网关（或开发模式 bun run dev）
 - port / host / timeout 等启动参数只读展示（修改需编辑 config.json 后重启）
 - **访问控制**：本机回环（127.0.0.1/::1）免登录直接进入；**非本机访问需密码登录**——在 config.json 顶层配置 `admin_password`（支持 `${ENV_VAR}` 插值，留空 = 未配置）；未配置时登录页会提示去实际配置文件设置。会话为内存态（24 小时过期，重启失效），登录页提供登出；连续 5 次密码错误锁定 60 秒
 - **安全**：`api_key` 返回真实值，前端以密码框（type=password）遮挡显示，明文不外露；编辑时留空 = 保持原值（不清空原密钥），填新值即覆盖；`admin_password` 不进界面编辑范围，只在配置文件改
-- 开发模式：`bun run dev` 会并行起 Vite dev server（端口 5173，代理 `/admin/api` 到网关）和网关 api，前端改动热更新
 
 启动后服务监听在配置的 `host:port`（默认 `http://127.0.0.1:8787`）。
 
@@ -333,9 +347,50 @@ model:    <config.json 里 aliases 的任意键>
 
 ## 开发
 
+### 本地环境
+
+前置：安装 [bun](https://bun.sh/)（运行时依赖，版本 >= 1.0.0）：
+
+```bash
+curl -fsSL https://bun.sh/install | bash
+```
+
+```bash
+# 1. 安装依赖（会同时安装 admin 子项目依赖）
+bun install
+
+# 2. 复制示例配置并编辑（填你的各家 key）
+cp config.example.json config.json
+vim config.json
+```
+
+### 开发模式
+
 ```bash
-bun test        # 单元测试（config 校验 / failover / SSE 改写 / 鉴权路由；默认忽略 admin/ 前端测试）
-bun run typecheck   # 见下
+bun run dev     # api 热重载 + Vite 前端热更新（并行起 Vite dev server 5173，代理 /admin/api 到网关），开箱即用
+```
+
+### 生产构建
+
+```bash
+bun run build                    # 内联前端资源（Vite 产物 admin/dist/ → src/admin-assets.generated.ts）并打包成单文件二进制 model-gate.js
+bun run model-gate.js            # 运行构建产物（等同于 node 跑这个 bun 二进制）
+```
+
+### 指定配置文件
+
+```bash
+# 任意模式下均可：
+bun run dev -- --config /path/to/config.json
+# 或设环境变量：
+MODEL_GATE_CONFIG=/path/to/config.json bun run dev
+```
+
+### 测试与类型检查
+
+```bash
+bun test            # 单元测试（config 校验 / failover / SSE 改写 / 鉴权路由；默认忽略 admin/ 前端测试）
+bun run typecheck   # 后端 tsc + 前端 vue-tsc
 ```
 
 没有真实上游 key 时，可用仓库自带的本地 mock 做端到端自测：
@@ -345,29 +400,29 @@ bun scripts/mock-upstream.ts   # 起一个 OpenAI 兼容 mock 上游（端口 99
 bun scripts/smoke.ts           # 端到端冒烟：health/models/鉴权/chat 转发/流式/failover/热加载
 ```
 
-目录结构：
+### 发布脚本
+
+- `bun run release [版本号]`：交互式（或显式传版本号）选择 latest/beta 通道与升级方式，自动 build 并发布到 npm，发布成功后自动 commit 版本变更。更多用法见 `scripts/release.ts` 顶部注释。
+- `bun run unpublish [版本号]`：撤销已发布的 npm 版本。不指定版本则列出最近 5 个用方向键选择；默认 `deprecate`（软撤销、安全），可加 `--hard` 真删除（仅发布 72h 内允许）。
+
+### 目录结构
 
 ```
 ├── config.example.json   # 配置示例（复制为 config.json 使用）
 ├── src/
-│   ├── index.ts          # 入口：加载配置、热加载、Bun.serve
+│   ├── index.ts          # 入口：加载配置、热加载、Bun.serve（含 init 子命令）
 │   ├── app.ts            # Hono 路由：鉴权、日志中间件、/v1/* 端点
-│   ├── admin.ts          # /admin 管理后端 API（配置读写、测试连接等）
+│   ├── admin.ts          # /admin 管理后端 API（配置读写、测试连接、用量统计等）
 │   ├── config.ts         # 配置类型、校验、${ENV} 插值
 │   ├── providers.ts      # 上游调用：转发、SSE 改写、failover、超时
 │   ├── logger.ts         # 控制台摘要 + access.log
 │   └── *.test.ts         # 测试
 ├── admin/                # Vue3 + Naive UI 管理前端（Vite 构建）
+├── scripts/              # release / unpublish / mock / smoke 等脚本
 ├── docs/adr/             # 架构决策记录
 └── CONTEXT.md            # 领域词汇表
 ```
 
-类型检查（可选）：
-
-```bash
-bun run typecheck
-```
-
 ## 限制与路线图
 
 - 上游仅支持 OpenAI 兼容端点（DeepSeek、Kimi、通义、智谱、SiliconFlow 等均兼容）；Anthropic / Gemini 原生协议待加适配层