@lakphy/local-router 0.0.1 → 0.0.2

package/README.md

@@ -1,51 +1,48 @@
-# local-router
+# @lakphy/local-router
 
-`local-router` 是一个面向本地使用的 AI 请求网关。  
-你把请求发给它，它会按你的配置自动转发到 OpenAI/Anthropic 兼容上游，并统一提供日志和管理界面。
+`@lakphy/local-router` 是一个本地 AI CLI 网关工具。  
+安装后通过 `local-router` 命令启动服务，把 OpenAI/Anthropic 风格请求统一转发到你配置的上游 provider。
 
-## 这是什么
+## 安装（CLI 使用者）
 
-适合这几类场景：
+运行要求：Bun `>=1.2.0`
 
-- 你希望统一一个本地入口来切换不同模型/供应商
-- 你不想在每个客户端里直接暴露上游 API Key
-- 你需要查看请求日志、会话轨迹和基础统计
+全局安装（推荐）：
 
-支持的协议入口：
-
-- `openai-completions`
-- `openai-responses`
-- `anthropic-messages`
-
-## 5 分钟上手
+```sh
+npm i -g @lakphy/local-router
+```
 
-### 1) 安装依赖
+或用 Bun 全局安装：
 
 ```sh
-bun install
+bun add -g @lakphy/local-router
 ```
 
-### 2) 初始化配置
+不全局安装，临时执行：
 
 ```sh
-local-router init
+npx @lakphy/local-router --help
+# 或
+bunx @lakphy/local-router --help
 ```
 
-默认会创建配置文件（优先当前目录 `config.json5`，否则 `~/.local-router/config.json5`）。
+## 快速开始
 
-### 3) 启动服务
+### 1) 初始化配置
 
 ```sh
-local-router start
+local-router init
 ```
 
-默认地址：
+默认配置路径：
 
-- 服务：`http://127.0.0.1:4099`
-- 管理面板：`http://127.0.0.1:4099/admin`
-- API 文档：`http://127.0.0.1:4099/api/docs`
+- 优先当前目录：`./config.json5`
+- 否则全局目录：`~/.local-router/config.json5`
+
+### 2) 编辑配置文件
 
-## 配置示例（最小可用）
+最小可用配置示例：
 
 ```json5
 {
@@ -67,72 +64,76 @@ local-router start
 }
 ```
 
-配置要点：
-
-- `providers` 定义上游地址、类型和密钥
-- `routes` 定义“你传入的 model”映射到“实际上游 model”
-- 每个入口必须有 `*` 兜底规则
-- `log` 是可选配置，不写就不记录日志
+### 3) 启动服务
 
-完整 schema 见 `config.schema.json`。
+```sh
+local-router start
+```
 
-## 如何调用
+默认地址：
 
-你只需要把客户端请求地址改到 local-router。
+- 服务：`http://127.0.0.1:4099`
+- 管理面板：`http://127.0.0.1:4099/admin`
+- API 文档：`http://127.0.0.1:4099/api/docs`
 
-### OpenAI Chat Completions
+## 常用命令
 
 ```sh
-curl -X POST "http://127.0.0.1:4099/openai-completions/v1/chat/completions" \
-  -H "Content-Type: application/json" \
-  -d '{
-    "model": "gpt-4o-mini",
-    "messages": [{"role":"user","content":"请回复 ok"}]
-  }'
+local-router --help
+local-router init
+local-router start
+local-router start --daemon
+local-router stop
+local-router restart --daemon
+local-router status
+local-router status --json
+local-router health
+local-router logs --follow
+local-router version
 ```
 
-### OpenAI Responses
+常用参数：
 
-```sh
-curl -X POST "http://127.0.0.1:4099/openai-responses/v1/responses" \
-  -H "Content-Type: application/json" \
-  -d '{
-    "model": "gpt-4o-mini",
-    "input": "请回复 ok"
-  }'
-```
+- `--config <path>`：指定配置文件路径
+- `--host <host>`：指定监听地址
+- `--port <port>`：指定监听端口
+- `--daemon`：后台运行
+
+## 请求入口（给你的应用调用）
+
+把应用的 base URL 指向 local-router 后，使用以下入口：
+
+- `POST /openai-completions/v1/chat/completions`
+- `POST /openai-responses/v1/responses`
+- `POST /anthropic-messages/v1/messages`
 
-### Anthropic Messages
+示例（OpenAI Chat Completions）：
 
 ```sh
-curl -X POST "http://127.0.0.1:4099/anthropic-messages/v1/messages" \
+curl -X POST "http://127.0.0.1:4099/openai-completions/v1/chat/completions" \
   -H "Content-Type: application/json" \
   -d '{
-    "model": "sonnet",
-    "max_tokens": 64,
+    "model": "gpt-4o-mini",
     "messages": [{"role":"user","content":"请回复 ok"}]
   }'
 ```
 
-## 常用 CLI 命令
+## 配置规则（必须知道）
 
-```sh
-local-router init
-local-router start
-local-router start --daemon
-local-router status --json
-local-router logs --follow
-local-router stop
-local-router restart --daemon
-local-router health
-local-router version
-```
+- `providers`：定义上游服务（类型、地址、密钥、模型）
+- `routes`：定义路由映射（传入 model -> 目标 provider/model）
+- 每个入口都必须有 `*` 兜底规则
+- `routes` 里引用的 `provider` 必须在 `providers` 中存在
+- `log` 是可选，不配置就不记录日志
+
+完整 schema：`config.schema.json`
 
 ## 日志与管理面板
 
-- 管理面板：`/admin`
+- 面板地址：`/admin`
 - 健康检查：`GET /api/health`
-- 日志查询：`GET /api/logs/events`
+- 日志列表：`GET /api/logs/events`
+- 日志详情：`GET /api/logs/events/:id`
 - 日志导出：`GET /api/logs/export?format=json|csv`
 - 实时 tail：`GET /api/logs/tail`（SSE）
 
@@ -143,36 +144,31 @@ local-router version
 
 ## 常见问题
 
-### Q1: 客户端还需要带上游 API Key 吗？
+### 客户端还需要带上游 API Key 吗？
 
-一般不需要。local-router 会按你在 `providers.*.apiKey` 配置的密钥进行转发鉴权。
+一般不需要。local-router 会使用你在配置文件 `providers.*.apiKey` 中设置的密钥转发。
 
-### Q2: 为什么启动失败？
+### 启动失败怎么办？
 
-优先检查：
+先检查：
 
-- 端口 `4099` 是否被占用（可改 `--port`）
-- 配置中是否缺少 `routes.<type>."*"` 兜底
-- `routes` 引用的 provider 是否在 `providers` 中存在
+- 端口 `4099` 是否已占用（可用 `--port` 修改）
+- `routes.<type>` 是否缺少 `*` 规则
+- `routes` 引用的 provider 是否存在
+- 配置文件是否是合法 JSON5
 
-### Q3: 管理面板打不开？
-
-如果是生产/本地打包后运行，先执行：
+### 如何升级？
 
 ```sh
-bun run build
+npm i -g @lakphy/local-router@latest
+# 或
+bun add -g @lakphy/local-router@latest
 ```
 
-开发态可通过 `bun run dev` 启动（包含 Web 开发服务器）。
-
-## 运行要求
+### 如何卸载？
 
-- Bun `>=1.2.0`
-
-## 进阶文档
-
-- `docs/cli-development-and-release.md`
-- `docs/logging-architecture.md`
-- `docs/react-csr-integration.md`
-- `docs/application-performance-analysis.md`
-- `docs/application-performance-high-risk-remediation.md`
+```sh
+npm rm -g @lakphy/local-router
+# 或
+bun remove -g @lakphy/local-router
+```

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@lakphy/local-router",
-  "version": "0.0.1",
+  "version": "0.0.2",
   "packageManager": "bun@1.2.0",
   "workspaces": [
     "web"