ezllm 0.0.36 → 0.0.38

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` 一条命令装好并自启动——默认装到用户目录下的 `~/.ezllm`（含自带托管 Node 运行时），首次启动自动创建示例配置，网页向导两分钟完成接入
+- **特别安全**：无遥测、无上报、无云端组件——详见「安全与隐私」
 
 ## 安全与隐私
 
@@ -15,45 +15,76 @@
 ## 功能特性
 
 - **协议互转**：客户端与上游可各用各的协议（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）的流量指向本机网关（自动备份原配置、可还原）
-- **开机自启**：三平台支持，登录即启动，免管理员权限
-- **自动更新**（可选）：发现新版本一键更新；安装失败或安装后版本与目标不符时**不自动回退**——清掉待更新标记、把原因记入 `lastApply.error`，服务以旧版本继续运行（日志里会给出回退用的命令）。自建 registry / 镜像源可用 `ELLM_UPDATE_REGISTRY` 指定
+- **额度快照**：内置多家供应商的额度查询（DeepSeek、智谱、火山方舟等），余量一目了然
+- **订阅插件**：接社区 OpenCode 插件（订阅账号当供应商用：CodeBuddy、智谱 Coding Plan 等），插件目录与开关在管理台「插件」页维护
+- **管理界面**：供应商管理、连通性测试、用量统计、请求日志，开箱即用零学习成本
+- **配置即文件**：所有功能设置（供应商、路由、密钥、端口、界面与安全）集中在一个可读的 `ezllm.config.json`（应用目录内）——管理界面就是它的编辑器，改动内存热更新、无需重启；CLI 只管进程生命周期，没有散落在命令行的隐藏开关。配置可备份、可整份迁移，排障时直接看文件即可
+- **开机自启**：三平台支持，登录即启动，免管理员权限。**默认不注册**——自启是显式动作：装的时候加 `--autostart`，或装完后在管理台设置页打开
+- **自动更新**（手动触发）：管理台发现新版本只**提示**，不代你应用——在终端执行 `npx ezllm update` 完成升级；安装失败或安装后版本与目标不符时**不自动回退**——清掉待更新标记、把原因记入 `lastApply.error`，服务以旧版本继续运行（日志里会给出回退用的命令）
 
 ## 安装
 
 ```bash
-npx ezllm install    # 推荐：装配自带 Node 运行时的环境（命令常驻可用，不受本机 node 版本影响）
+npx ezllm install    # 装配到用户目录下的 ~/.ezllm（幂等；装完自动启动）
 ```
 
-也可以直接全局安装（命令可用性依赖本机 node 环境）：
+装完即可用，之后**一律用 `npx ezllm <命令>`**——不需要全局安装，也不需要设置任何环境变量。
 
-```bash
-npm i -g ezllm
-```
+**为什么不用管 Node 版本**：服务启动**总是**用托管运行时（应用目录下的 `node/`，缺失时自动下载一次并缓存，之后复用），与本机已装的 node 无关；`npx ezllm install` 只把发布包产物铺进应用目录，跑它的那个 node（你的系统默认 node）仅用于完成这次装配——它要求 **Node 18 及以上**（`install` / `uninstall` / `update` 三条装配命令共享同一份 CLI 产物，下限见 `package.json` 的 `engines.node`）。
+
+**谁跑在哪个 node 上**：服务、常驻主进程及其子进程一律走托管 `<应用目录>/node`（`node:sqlite` 需要 Node ≥ 22.13）；`install` / `uninstall` / `update` 三条命令跑在你系统默认的 node 上——也就是 `npx` 拉起的那个。
+
+**装到哪个目录**：默认**用户目录下的 `~/.ezllm`**，解析链只有两级（不做任何基于当前目录的推断；`runtime.json` 是归属标记文件，用来认出「这是 ezllm 装的应用目录」）：
+
+1. `--app-dir=<路径>` 参数 / `ELLM_APP_DIR` 环境变量
+2. 缺省 `~/.ezllm`
+
+不写全局命令、不改用户级 PATH、不写 Windows 注册表、不写转发 shim。
+
+**启动参数**（四条各有命令行与环境变量两种写法，**命令行优先于环境变量**；appDir 与引导期两项解析后归一写回同名环境变量、供子进程继承；**port 不写回 env**——端口由 `start` / `install` 写入配置文件，见下）：
 
-无需为**服务**预装特定 Node 版本——服务启动**总是**用托管运行时（`<appDir>/node`，由 `@doyzheng/ezn` 的 `Node.ensure` 落位，缺失时下载一次并缓存），与本机已装的 node 无关（CLI 进程自身仍由本机 node 启动）；`ezllm install` 另外会把包装配到用户目录（默认 `~/.ezllm`）并把 `ezllm` 命令注册进用户 PATH。
+| 参数 | 环境变量 | 说明 |
+| --- | --- | --- |
+| `--app-dir=<路径>` | `ELLM_APP_DIR` | 应用目录（相对值按当前目录展开，归一后写回绝对路径） |
+| `--port=<端口>` | `ELLM_PORT` | 监听端口。**配合 `start` / `install` 使用**：给了就**写入配置文件**（配置是端口的唯一数据源：这样显示、重启、自启、多实例区分全读同一处）；不给则读配置文件。其余命令带它会被忽略并提示 |
+| `--node-mirror=<url>` | `ELLM_NODE_MIRROR` | 引导期：托管 Node 的下载镜像（目录结构需同 nodejs.org/dist） |
+| `--node-bin=<路径>` | `ELLM_NODE_BIN` | 引导期：跳过下载与解压，直接指定 node 可执行文件 |
+
+例：装到别处 —— `npx ezllm install --app-dir=D:\work\ezllm`；换端口并顺便开机自启 —— `npx ezllm install --port=3001 --autostart`。
+
+**端口怎么改**：`--port` 会把端口写进配置文件（配置是唯一数据源），所以在跑着的实例上改端口需要重启主进程——`npx ezllm start --port=3001` 会自动先停再起，之后所有命令（含状态显示）看到的都是新端口。也可以直接编辑配置文件里的 `port` 再 `npx ezllm restart`。（`--port` 只对 `start` / `install` 生效；`restart --port=…` 这类用法会被忽略并提示。另外：shell 里长期导出 `ELLM_PORT` 会在每次 `start` / `install` 时被写进配置文件——要长期以配置管理端口，请勿在 shell 里长期导出它。）
+
+**国内网络友好**：运行时下载自带镜像回退（npmmirror → 官方源），装不上会自动换源重试。
+
+**从旧版本过来**：旧版装在用户级 `~/.ezllm`，新版默认位置相同——跑 `npx ezllm install` 即原地接续（配置与数据都在）。旧版写进用户 PATH 的 `<旧应用目录>/bin` 条目要自己手工清理（新版不再写 PATH）。
 
 ## 使用方法
 
 ```bash
-ezllm start    # 后台常驻启动（首次自动创建示例配置）
+npx 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`
 
 常用命令：
 
 ```bash
-ezllm          # 显示当前运行状态（服务地址、pid；只读，不启动服务）
-ezllm stop     # 停止
-ezllm restart  # 重启
-ezllm install  # 装配/修复自带 Node 运行时的环境（幂等；自动迁移旧数据目录）
+npx ezllm            # 显示当前运行状态（服务地址、pid；只读，不启动服务）
+npx ezllm stop       # 停止
+npx ezllm restart    # 重启
+npx ezllm update     # 检查并安装新版本
+npx ezllm install    # 装配/修复运行环境（幂等）
+npx ezllm uninstall  # 卸载（停服 → 注销自启 → 备份应用目录 → 删除它）
 ```
 
+**升级**：在终端执行 `npx ezllm update`——查最新版本并装配（由新版本自己完成装配，装配逻辑单点复用）。管理台「服务与更新」页只提示「有新版本」，不代你应用。
+
+**卸载**：`npx ezllm uninstall`——停服 → 注销开机自启 → 备份应用目录 → 删除应用目录（配置与数据先备份到同级的 `<应用目录>.backup-<时间戳>`）；**不再注销 PATH**（新版本来就不写它），只有旧版本留下的 PATH 条目才需要你手工清理。
+
 环境坏掉时要「推倒重来」，加 `--force` 重装：它会先停服务、清空应用目录（清理日志与数据、
 重置运行时记录），再重新装配。**保留** `ezllm.config.json` 与 `hook.*` 用户钩子，
 故配置与自写逻辑不丢：
@@ -62,11 +93,26 @@ ezllm install  # 装配/修复自带 Node 运行时的环境（幂等；自动
 npx ezllm install --force   # 重装（清理应用目录后重新装配）
 ```
 
+## 应用目录里有什么
+
+上面说的应用目录按下列布局放置（`dist/` 与 `node/` 由 `install` 装配；不再有 `node/node_modules/ezllm` 这层嵌套）：
+
+| 路径 | 说明 |
+| --- | --- |
+| `dist/` | 程序产物（`server.js` / `daemon.js` / `cli.js` / `plugin-host.js` / `web-ui/`） |
+| `node/` | 托管 Node 运行时（服务与常驻主进程一律用它启动） |
+| `package.json` | 包清单（版本与包根定位靠它） |
+| `runtime.json` | 归属标记（`install` 写入；命令层「尚未安装」判定与卸载护栏共用这一份判据） |
+| `.gitignore` | 内容为 `*`——整个目录不进你的版本库（配置含真实 API Key、运行时上百 MB） |
+| `ezllm.config.json` | 配置唯一数据源（首次启动据示例创建） |
+| `data/` · `logs/` | 运行时数据与日志目录 |
+| `ezllm.config.example.json` · `hook.example.cjs` | 示例配置与钩子示例 |
+
 ## 进阶：改写请求报文（可选）
 
 如果某个客户端每轮都在请求里塞大量固定内容（工具描述里内嵌的 API 手册、注入的记忆索引等），可以在网关侧裁掉，从根上省 token。
 
-把发布包里的 `hook.example.js` 复制到应用目录（默认 `~/.ezllm`）并改名为 **`hook.cjs`**，按注释改里面的规则，然后 `ezllm restart`。
+把发布包里的 **`hook.example.cjs`** 复制到应用目录（默认 `~/.ezllm/`，也可用 `--app-dir` 指定）即可，无需改名。按注释改里面的规则，然后 `npx 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`）：在发往上游前改请求体/请求头，**改不了响应**。