ezllm 0.0.36 → 0.0.37

package/README.md

@@ -1,10 +1,10 @@
 # ezllm
 
-**轻量、安全的本地 LLM 网关**——一条命令安装，一条命令启动，把你的 OpenAI / Anthropic 协议供应商和 API Key 统一收口为一个本地入口。
+**轻量、安全的本地 LLM 网关**——为个人本地使用设计：一条命令安装，一条命令启动，把你的 OpenAI / Anthropic 协议供应商和 API Key 统一收口为一个本地入口。
 
-- **部署成本极低**：单进程、单端口（默认 29770），常驻内存仅约 50 MB，你的日常电脑就能跑，无需服务器
-- **快速启动**：`npm i -g ezllm && ezllm start`，装完即起，首次启动自动创建示例配置，网页向导两分钟完成接入
-- **特别安全**：不收集任何数据、不上传任何数据。API Key 只存在你自己电脑上，请求只发给你自己配置的供应商，日志全部存本地
+- **部署成本极低**：单进程、单端口（默认 29770），常驻内存约 50–60 MB，你的日常电脑就能跑，无需服务器
+- **快速启动**：`npx ezllm install` 一条命令装好并自启动——自带托管 Node 运行时、自动注册 `ezllm` 命令，首次启动自动创建示例配置，网页向导两分钟完成接入
+- **特别安全**：无遥测、无上报、无云端组件——详见「安全与隐私」
 
 ## 安全与隐私
 
@@ -15,16 +15,18 @@
 ## 功能特性
 
 - **协议互转**：客户端与上游可各用各的协议（OpenAI / Anthropic），网关自动转换
-- **多供应商路由**：多家供应商 / 多个 API Key 统一管理，按模型路由、网页在线切换；内置 deepseek、kimi、zhipu、ark、openai 等 10 个供应商模板
-- **管理界面**：供应商管理、连通性测试、用量统计、请求日志，开箱即用零学习成本
+- **多供应商路由**：多家供应商 / 多个 API Key 统一管理，按模型路由、网页在线切换；内置 deepseek、kimi、zhipu、ark、dashscope、openai 等 10 个供应商模板
 - **一键接入 AI 客户端**：网页上点一下，把 Claude Code、Codex、DeepSeek Harness（dsh）的流量指向本机网关（自动备份原配置、可还原）
+- **额度快照**：内置多家供应商的额度查询（DeepSeek、智谱、火山方舟、CPA 等），余量一目了然
+- **管理界面**：供应商管理、连通性测试、用量统计、请求日志，开箱即用零学习成本
+- **配置即文件**：所有功能设置（供应商、路由、密钥、端口、界面与安全）集中在一个可读的 `ezllm.config.json`（应用目录内）——管理界面就是它的编辑器，改动内存热更新、无需重启；CLI 只管进程生命周期，没有散落在命令行的隐藏开关。配置可备份、可整份迁移，排障时直接看文件即可
 - **开机自启**：三平台支持，登录即启动，免管理员权限
-- **自动更新**（可选）：发现新版本一键更新；安装失败或安装后版本与目标不符时**不自动回退**——清掉待更新标记、把原因记入 `lastApply.error`，服务以旧版本继续运行（日志里会给出回退用的命令）。自建 registry / 镜像源可用 `ELLM_UPDATE_REGISTRY` 指定
+- **自动更新**（可选）：发现新版本一键更新（`ezllm update`）；安装失败或安装后版本与目标不符时**不自动回退**——清掉待更新标记、把原因记入 `lastApply.error`，服务以旧版本继续运行（日志里会给出回退用的命令）。自建 registry / 镜像源可用 `ELLM_UPDATE_REGISTRY` 指定
 
 ## 安装
 
 ```bash
-npx ezllm install    # 推荐：装配自带 Node 运行时的环境（命令常驻可用，不受本机 node 版本影响）
+npx ezllm install    # 推荐：装配自带 Node 运行时的环境（装完自动启动；命令常驻可用，不受本机 node 版本影响）
 ```
 
 也可以直接全局安装（命令可用性依赖本机 node 环境）：
@@ -33,7 +35,9 @@ npx ezllm install    # 推荐：装配自带 Node 运行时的环境（命令常
 npm i -g ezllm
 ```
 
-无需为**服务**预装特定 Node 版本——服务启动**总是**用托管运行时（`<appDir>/node`，由 `@doyzheng/ezn` 的 `Node.ensure` 落位，缺失时下载一次并缓存），与本机已装的 node 无关（CLI 进程自身仍由本机 node 启动）；`ezllm install` 另外会把包装配到用户目录（默认 `~/.ezllm`）并把 `ezllm` 命令注册进用户 PATH。
+**为什么不用管 Node 版本**：服务启动**总是**用托管运行时（应用目录下的 `node/`，缺失时自动下载一次并缓存，之后复用），与本机已装的 node 无关；`ezllm install` 还会把包装配到用户目录（默认 `~/.ezllm`）并把 `ezllm` 命令注册进用户 PATH。
+
+**国内网络友好**：运行时下载自带镜像回退（npmmirror → 官方源），装不上会自动换源重试；服务更新可用 `ELLM_UPDATE_REGISTRY` 指定自建 registry。
 
 ## 使用方法
 
@@ -43,7 +47,7 @@ ezllm start    # 后台常驻启动（首次自动创建示例配置）
 
 1. 打开管理界面 `http://127.0.0.1:29770/`，首次访问进入**首启向导**：选择部署形态（本机使用 / 局域网公开），设置主密钥与登录账号（本机使用可全部跳过）
 2. 在「供应商」页添加你的供应商（选内置模板，填 API Key 即可）
-3. 把客户端指向网关：Claude Code 指向 `http://127.0.0.1:29770`，OpenAI SDK 指向 `http://127.0.0.1:29770/v1`（也可在「设置 → 代理开关」一键接入）
+3. 接入客户端：推荐在「设置 → 代理开关」**一键接入**（Claude Code / Codex / dsh，自动备份原配置、可还原）；手动接入则是 Claude Code 指向 `http://127.0.0.1:29770`、OpenAI SDK 指向 `http://127.0.0.1:29770/v1`
 
 常用命令：
 
@@ -51,6 +55,7 @@ ezllm start    # 后台常驻启动（首次自动创建示例配置）
 ezllm          # 显示当前运行状态（服务地址、pid；只读，不启动服务）
 ezllm stop     # 停止
 ezllm restart  # 重启
+ezllm update   # 检查并安装新版本
 ezllm install  # 装配/修复自带 Node 运行时的环境（幂等；自动迁移旧数据目录）
 ```
 
@@ -66,7 +71,7 @@ npx ezllm install --force   # 重装（清理应用目录后重新装配）
 
 如果某个客户端每轮都在请求里塞大量固定内容（工具描述里内嵌的 API 手册、注入的记忆索引等），可以在网关侧裁掉，从根上省 token。
 
-把发布包里的 `hook.example.js` 复制到应用目录（默认 `~/.ezllm`）并改名为 **`hook.cjs`**，按注释改里面的规则，然后 `ezllm restart`。
+把发布包里的 **`hook.example.cjs`** 复制到应用目录（默认 `~/.ezllm`）即可，无需改名。按注释改里面的规则，然后 `ezllm restart`。
 
 - **候选文件名**：`hook.cjs` → `hook.mjs` → `hook.js`，取第一个存在的。**推荐 `hook.cjs`**——`.js` 的解析模式（CJS 还是 ESM）取决于它祖先目录里最近的 `package.json`，不受你控制（比如家目录若有一份 `"type": "module"` 的 package.json，`hook.js` 里的 CJS 写法就会失效）；`.cjs` 强制按 CJS 解析，任何环境都稳。
 - **只有请求侧改写**一个钩子（`onModelRequest`）：在发往上游前改请求体/请求头，**改不了响应**。