@lakphy/local-router 0.0.1

package/README.md

@@ -0,0 +1,178 @@
+# local-router
+
+`local-router` 是一个面向本地使用的 AI 请求网关。  
+你把请求发给它，它会按你的配置自动转发到 OpenAI/Anthropic 兼容上游，并统一提供日志和管理界面。
+
+## 这是什么
+
+适合这几类场景：
+
+- 你希望统一一个本地入口来切换不同模型/供应商
+- 你不想在每个客户端里直接暴露上游 API Key
+- 你需要查看请求日志、会话轨迹和基础统计
+
+支持的协议入口：
+
+- `openai-completions`
+- `openai-responses`
+- `anthropic-messages`
+
+## 5 分钟上手
+
+### 1) 安装依赖
+
+```sh
+bun install
+```
+
+### 2) 初始化配置
+
+```sh
+local-router init
+```
+
+默认会创建配置文件（优先当前目录 `config.json5`，否则 `~/.local-router/config.json5`）。
+
+### 3) 启动服务
+
+```sh
+local-router start
+```
+
+默认地址：
+
+- 服务：`http://127.0.0.1:4099`
+- 管理面板：`http://127.0.0.1:4099/admin`
+- API 文档：`http://127.0.0.1:4099/api/docs`
+
+## 配置示例（最小可用）
+
+```json5
+{
+  providers: {
+    openai: {
+      type: "openai-completions",
+      base: "https://api.openai.com/v1",
+      apiKey: "sk-xxxx",
+      models: {
+        "gpt-4o-mini": {}
+      }
+    }
+  },
+  routes: {
+    "openai-completions": {
+      "*": { provider: "openai", model: "gpt-4o-mini" }
+    }
+  }
+}
+```
+
+配置要点：
+
+- `providers` 定义上游地址、类型和密钥
+- `routes` 定义“你传入的 model”映射到“实际上游 model”
+- 每个入口必须有 `*` 兜底规则
+- `log` 是可选配置，不写就不记录日志
+
+完整 schema 见 `config.schema.json`。
+
+## 如何调用
+
+你只需要把客户端请求地址改到 local-router。
+
+### 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"}]
+  }'
+```
+
+### 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"
+  }'
+```
+
+### Anthropic Messages
+
+```sh
+curl -X POST "http://127.0.0.1:4099/anthropic-messages/v1/messages" \
+  -H "Content-Type: application/json" \
+  -d '{
+    "model": "sonnet",
+    "max_tokens": 64,
+    "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
+```
+
+## 日志与管理面板
+
+- 管理面板：`/admin`
+- 健康检查：`GET /api/health`
+- 日志查询：`GET /api/logs/events`
+- 日志导出：`GET /api/logs/export?format=json|csv`
+- 实时 tail：`GET /api/logs/tail`（SSE）
+
+默认日志目录：`~/.local-router/logs`
+
+- 事件日志：`events/YYYY-MM-DD.jsonl`
+- 流式原文：`streams/YYYY-MM-DD/<request_id>.sse.raw`
+
+## 常见问题
+
+### Q1: 客户端还需要带上游 API Key 吗？
+
+一般不需要。local-router 会按你在 `providers.*.apiKey` 配置的密钥进行转发鉴权。
+
+### Q2: 为什么启动失败？
+
+优先检查：
+
+- 端口 `4099` 是否被占用（可改 `--port`）
+- 配置中是否缺少 `routes.<type>."*"` 兜底
+- `routes` 引用的 provider 是否在 `providers` 中存在
+
+### Q3: 管理面板打不开？
+
+如果是生产/本地打包后运行，先执行：
+
+```sh
+bun run build
+```
+
+开发态可通过 `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`

package/config.schema.json

@@ -0,0 +1,249 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "./config.schema.json",
+  "title": "Local Router Config",
+  "description": "local-router 的主配置文件。用于把不同协议入口的请求路由到具体 provider，并定义 provider 的模型能力与鉴权信息。",
+  "type": "object",
+  "additionalProperties": false,
+  "required": ["routes", "providers"],
+  "properties": {
+    "$schema": {
+      "type": "string",
+      "description": "可选。指向本文件的 schema 路径，便于编辑器提供自动补全与静态校验。",
+      "examples": ["./config.schema.json", "https://example.com/config.schema.json"]
+    },
+    "routes": {
+      "description": "路由映射：按入口协议分组，再按模型别名（或 * 通配）映射到目标 provider 与目标模型。",
+      "markdownDescription": "路由映射：按入口协议分组，再按模型别名（或 `*` 通配）映射到目标 provider 与目标模型。\n\n- 第一层 key：协议入口（例如 `openai-completions`、`openai-responses`、`anthropic-messages`）\n- 第二层 key：模型匹配规则（如 `opus`、`sonnet`、`*`）\n- value：`{ provider, model }`，表示最终转发到哪个 provider、使用哪个上游模型",
+      "type": "object",
+      "minProperties": 1,
+      "propertyNames": {
+        "type": "string",
+        "pattern": "^[a-z0-9][a-z0-9-]*$",
+        "description": "协议入口名称，建议使用 kebab-case。"
+      },
+      "additionalProperties": {
+        "$ref": "#/$defs/routeModelMap"
+      },
+      "examples": [
+        {
+          "openai-completions": {
+            "*": {
+              "provider": "dashscope-openai-completions",
+              "model": "qwen3.5-plus"
+            }
+          },
+          "anthropic-messages": {
+            "opus": {
+              "provider": "dashscope-anthropic-messages",
+              "model": "qwen3.5-plus"
+            },
+            "*": {
+              "provider": "dashscope-anthropic-messages",
+              "model": "qwen3.5-plus"
+            }
+          }
+        }
+      ]
+    },
+    "providers": {
+      "description": "provider 定义集合。key 为 provider 名称，value 为 provider 的协议类型、基础地址、鉴权与模型能力。",
+      "markdownDescription": "provider 定义集合。`routes.*.*.provider` 应引用这里的某个 key。\n\n每个 provider 包含：\n- `type`：协议类型（决定路由层如何拼接上游地址）\n- `base`：上游 API 基础地址（不含末尾具体路径）\n- `apiKey`：访问上游的密钥\n- `models`：上游模型能力开关（如是否支持推理、图像输入）",
+      "type": "object",
+      "minProperties": 1,
+      "propertyNames": {
+        "type": "string",
+        "pattern": "^[a-z0-9][a-z0-9-]*$",
+        "description": "provider 名称，建议使用 kebab-case，并在 routes 中通过该名称引用。"
+      },
+      "additionalProperties": {
+        "$ref": "#/$defs/providerConfig"
+      }
+    },
+    "log": {
+      "$ref": "#/$defs/logConfig",
+      "description": "日志配置。省略此字段或不配置时，日志系统不会启用。配置后默认启用，可通过 enabled: false 暂停。",
+      "markdownDescription": "日志配置。省略此字段时日志系统不启用。\n\n配置后，日志会写入配置文件同目录下的 `logs/` 子目录（如 `~/.local-router/logs/`），包括：\n- `events/YYYY-MM-DD.jsonl`：按天分片的结构化事件日志\n- `streams/YYYY-MM-DD/<request_id>.sse.raw`：流式响应原始 SSE 文本"
+    }
+  },
+  "$defs": {
+    "routeModelMap": {
+      "type": "object",
+      "description": "某个协议入口下的模型匹配表。key 是模型别名（或 *），value 是路由目标。",
+      "minProperties": 1,
+      "required": ["*"],
+      "propertyNames": {
+        "type": "string",
+        "minLength": 1,
+        "description": "模型匹配键。可使用 * 作为兜底通配规则。"
+      },
+      "additionalProperties": {
+        "$ref": "#/$defs/routeTarget"
+      },
+      "examples": [
+        {
+          "opus": {
+            "provider": "dashscope-anthropic-messages",
+            "model": "qwen3.5-plus"
+          },
+          "*": {
+            "provider": "dashscope-anthropic-messages",
+            "model": "qwen3.5-plus"
+          }
+        }
+      ]
+    },
+    "routeTarget": {
+      "type": "object",
+      "description": "路由命中后的转发目标。",
+      "additionalProperties": false,
+      "required": ["provider", "model"],
+      "properties": {
+        "provider": {
+          "type": "string",
+          "minLength": 1,
+          "description": "目标 provider 名称，必须与 providers 下某个 key 一致（跨字段引用关系由运行时或额外校验保证）。",
+          "examples": ["dashscope-openai-completions", "dashscope-anthropic-messages"]
+        },
+        "model": {
+          "type": "string",
+          "minLength": 1,
+          "description": "转发到上游时写入请求体的模型名。",
+          "examples": ["qwen3.5-plus", "qwen3-max", "qwen3.5-flash"]
+        }
+      }
+    },
+    "providerConfig": {
+      "type": "object",
+      "description": "单个 provider 的配置。",
+      "additionalProperties": false,
+      "required": ["type", "base", "apiKey", "models"],
+      "properties": {
+        "type": {
+          "type": "string",
+          "enum": ["openai-completions", "openai-responses", "anthropic-messages"],
+          "description": "provider 协议类型。应与其服务的入口协议/接口形态一致。"
+        },
+        "base": {
+          "type": "string",
+          "format": "uri",
+          "minLength": 1,
+          "description": "上游 API 的基础 URL。建议不带末尾斜杠，避免路径拼接出现重复斜杠。",
+          "examples": [
+            "https://dashscope.aliyuncs.com/compatible-mode",
+            "https://dashscope.aliyuncs.com/response-mode",
+            "https://dashscope.aliyuncs.com/anthropic"
+          ]
+        },
+        "apiKey": {
+          "type": "string",
+          "minLength": 1,
+          "description": "访问上游服务的密钥。建议通过环境变量注入后再生成配置文件，避免在仓库中明文保存。"
+        },
+        "models": {
+          "type": "object",
+          "minProperties": 1,
+          "description": "模型能力定义。key 为模型名，value 为该模型的能力标记（例如 reasoning、image-input）。",
+          "propertyNames": {
+            "type": "string",
+            "minLength": 1,
+            "description": "模型标识，例如 qwen3.5-plus。"
+          },
+          "additionalProperties": {
+            "$ref": "#/$defs/modelCapabilities"
+          }
+        }
+      }
+    },
+    "modelCapabilities": {
+      "type": "object",
+      "description": "模型能力开关。当前已知能力字段为 image-input 与 reasoning；未声明字段默认视为 false 或由上游默认行为决定。",
+      "additionalProperties": false,
+      "properties": {
+        "image-input": {
+          "type": "boolean",
+          "description": "是否支持图像输入能力。"
+        },
+        "reasoning": {
+          "type": "boolean",
+          "description": "是否支持推理/思维链类能力（按你的业务语义定义）。"
+        }
+      },
+      "examples": [
+        {
+          "image-input": false,
+          "reasoning": true
+        }
+      ]
+    },
+    "logConfig": {
+      "type": "object",
+      "description": "日志系统配置。控制请求/响应日志的记录方式、存储路径和隐私脱敏策略。",
+      "additionalProperties": false,
+      "properties": {
+        "enabled": {
+          "type": "boolean",
+          "default": true,
+          "description": "是否启用日志记录。设为 false 可在保留配置的同时暂停日志写入。默认为 true（配置了 log 段即启用）。"
+        },
+        "baseDir": {
+          "type": "string",
+          "description": "日志文件根目录的绝对路径。默认为 ~/.local-router/logs/。仅在需要自定义存储位置时指定。",
+          "examples": ["/home/user/.local-router/logs", "/var/log/local-router"]
+        },
+        "events": {
+          "$ref": "#/$defs/logEventsConfig",
+          "description": "事件日志（JSONL 格式）相关配置。"
+        },
+        "streams": {
+          "$ref": "#/$defs/logStreamsConfig",
+          "description": "流式响应原文（SSE raw）相关配置。"
+        },
+        "bodyPolicy": {
+          "type": "string",
+          "enum": ["off", "masked", "full"],
+          "default": "off",
+          "description": "请求体与响应体的记录策略。off：不记录 body 内容（推荐日常使用）；masked：脱敏后记录（当前版本行为同 full，后续将完善字段级脱敏）；full：完整记录所有内容（仅建议调试时临时开启，注意隐私风险）。",
+          "markdownDescription": "请求体与响应体的记录策略：\n- `off`：不记录 body 内容（推荐日常使用）\n- `masked`：脱敏后记录（当前版本行为同 `full`，后续完善）\n- `full`：完整记录所有内容（仅调试时使用）"
+        }
+      }
+    },
+    "logEventsConfig": {
+      "type": "object",
+      "description": "事件日志（JSONL 格式）相关配置。每个转发请求生成一条 JSON 事件，按天写入独立文件（如 events/2026-02-28.jsonl）。",
+      "additionalProperties": false,
+      "properties": {
+        "retainDays": {
+          "type": "integer",
+          "minimum": 1,
+          "default": 14,
+          "description": "事件日志文件保留天数。超过此天数的 .jsonl 文件将在清理时被删除。默认保留 14 天。"
+        }
+      }
+    },
+    "logStreamsConfig": {
+      "type": "object",
+      "description": "流式响应原文（SSE raw）相关配置。每个流式请求的完整 SSE 文本会保存为独立的 .sse.raw 文件（如 streams/2026-02-28/<request_id>.sse.raw）。",
+      "additionalProperties": false,
+      "properties": {
+        "enabled": {
+          "type": "boolean",
+          "default": true,
+          "description": "是否记录流式响应的原始 SSE 文本到独立文件。关闭后仅在事件日志中记录元数据，不保存原始流内容。默认开启。"
+        },
+        "retainDays": {
+          "type": "integer",
+          "minimum": 1,
+          "default": 7,
+          "description": "流式原文文件保留天数。超过此天数的 .sse.raw 文件将在清理时被删除。默认保留 7 天。"
+        },
+        "maxBytesPerRequest": {
+          "type": "integer",
+          "minimum": 1,
+          "default": 10485760,
+          "description": "单个流式请求最大记录字节数（默认约 10MB = 10485760 字节）。超出部分将被截断并在文件末尾追加 [TRUNCATED] 标记。设置合理上限可防止异常长响应撑爆磁盘。"
+        }
+      }
+    }
+  }
+}