feat: ship v0.7.0 onboarding and diagnostics

Author: anjieyang

README.md

@@ -40,36 +40,25 @@ UncommonRoute picks the cheapest model that still gets the job done — automati
 pip install uncommon-route
 ```
 
-### 2. Connect an upstream — pick one
-
-**Option A — Commonstack (recommended, one key covers all providers)**
-
-Sign up at [commonstack.ai](https://commonstack.ai) and copy your API key from the dashboard. Then:
+### 2. Run the guided setup
 
 ```bash
-export UNCOMMON_ROUTE_UPSTREAM="https://api.commonstack.ai/v1"
-export UNCOMMON_ROUTE_API_KEY="csk-your-key"
-uncommon-route serve
+uncommon-route init
 ```
 
-One key gives you OpenAI, Anthropic, Google, xAI, MiniMax, Moonshot, DeepSeek, and more — consolidated billing, no per-provider setup.
+The wizard walks you through:
 
-**Option B — Bring your own keys (BYOK)**
+- choosing a connection path: Commonstack, local/custom upstream, or BYOK
+- saving upstream credentials locally
+- configuring Claude Code, Codex, or OpenAI SDK / Cursor
+- optionally starting the proxy in background
 
-Register any subset of providers you have direct keys for:
+If you prefer to sanity-check before starting the proxy:
 
 ```bash
-uncommon-route provider add openai     sk-...
-uncommon-route provider add anthropic  sk-ant-...
-uncommon-route provider add google     AIza...
-# also supported: xai, minimax, moonshot, deepseek
-uncommon-route serve
+uncommon-route doctor
 ```
 
-Auto-routing will only consider models backed by a registered provider.
-
-> **Note:** UncommonRoute does **not** auto-read `OPENAI_API_KEY` / `ANTHROPIC_API_KEY`. Use one of the two paths above.
-
 ### 3. Point your client at the proxy
 
 | Client | Change |
@@ -88,6 +77,35 @@ resp = client.chat.completions.create(model="uncommon-route/auto", messages=msgs
 
 Works with **Claude Code**, **Codex**, **Cursor**, the **OpenAI SDK**, and **OpenClaw**.
 
+<details>
+<summary><strong>Manual setup (advanced)</strong></summary>
+
+**Commonstack managed upstream**
+
+```bash
+export UNCOMMON_ROUTE_UPSTREAM="https://api.commonstack.ai/v1"
+export UNCOMMON_ROUTE_API_KEY="csk-your-key"
+uncommon-route serve
+```
+
+One key gives you OpenAI, Anthropic, Google, xAI, MiniMax, Moonshot, DeepSeek, and more — consolidated billing, no per-provider setup.
+
+**Bring your own keys (BYOK)**
+
+```bash
+uncommon-route provider add openai     sk-...
+uncommon-route provider add anthropic  sk-ant-...
+uncommon-route provider add google     AIza...
+# also supported: xai, minimax, moonshot, deepseek
+uncommon-route serve
+```
+
+Auto-routing will only consider models backed by a registered provider.
+
+> **Note:** UncommonRoute does **not** auto-read `OPENAI_API_KEY` / `ANTHROPIC_API_KEY`. Use `uncommon-route init`, a saved connection, or one of the manual paths above.
+
+</details>
+
 ---
 
 ## How It Works
@@ -161,6 +179,19 @@ Real-time monitoring, interactive playground, cost tracking, and model routing c
 
 ---
 
+## Diagnostics
+
+When a user hits a routing or upstream issue, you can export a local support bundle without guessing which logs to collect:
+
+```bash
+uncommon-route support bundle
+uncommon-route support request <request_id>
+```
+
+The bundle includes recent request traces, recent errors, stats summaries, provider/config snapshots, and redacted local state. It stays on your machine until you choose to share it.
+
+---
+
 ## Configuration
 
 ### Routing modes
@@ -209,6 +240,8 @@ Runs entirely on your machine. No data leaves unless you opt in.
 uncommon-route telemetry status
 ```
 
+Diagnostics exports are also local-first: `uncommon-route support bundle` writes a redacted zip under `~/.uncommon-route/support/` by default.
+
 ---
 
 ## Development

README.zh-CN.md

@@ -40,36 +40,25 @@ UncommonRoute 自动选最便宜、又能完成任务的模型。
 pip install uncommon-route
 ```
 
-### 2. 接入上游——二选一
-
-**方式 A — Commonstack 托管（推荐，一把 key 覆盖所有 provider）**
-
-在 [commonstack.ai](https://commonstack.ai) 注册并从 dashboard 拿到你的 API key，然后：
+### 2. 运行引导式配置
 
 ```bash
-export UNCOMMON_ROUTE_UPSTREAM="https://api.commonstack.ai/v1"
-export UNCOMMON_ROUTE_API_KEY="csk-your-key"
-uncommon-route serve
+uncommon-route init
 ```
 
-一把 key 打通 OpenAI、Anthropic、Google、xAI、MiniMax、Moonshot、DeepSeek 等所有主流 provider——统一账单，无需逐家申请。
+这个向导会一步步帮你：
 
-**方式 B — 自带 key（BYOK）**
+- 选择接入方式：Commonstack、BYOK，或者本地 / 自定义 upstream
+- 把 upstream 凭据保存到本地
+- 配置 Claude Code、Codex、OpenAI SDK / Cursor
+- 可选地直接把代理以后台方式启动起来
 
-注册你已经有 key 的任意 provider（可选任意子集）：
+如果你想在启动前先检查一遍：
 
 ```bash
-uncommon-route provider add openai     sk-...
-uncommon-route provider add anthropic  sk-ant-...
-uncommon-route provider add google     AIza...
-# 同样支持：xai、minimax、moonshot、deepseek
-uncommon-route serve
+uncommon-route doctor
 ```
 
-Auto 路由只会在已注册的 provider 范围内选模型。
-
-> **注意：** UncommonRoute **不会**自动读取 `OPENAI_API_KEY` / `ANTHROPIC_API_KEY` 环境变量。请用上面两种方式之一。
-
 ### 3. 把客户端指向代理
 
 | 客户端 | 改动 |
@@ -88,6 +77,35 @@ resp = client.chat.completions.create(model="uncommon-route/auto", messages=msgs
 
 支持 **Claude Code**、**Codex**、**Cursor**、**OpenAI SDK** 和 **OpenClaw**。
 
+<details>
+<summary><strong>手动配置（进阶）</strong></summary>
+
+**方式 A — Commonstack 托管（推荐，一把 key 覆盖所有 provider）**
+
+```bash
+export UNCOMMON_ROUTE_UPSTREAM="https://api.commonstack.ai/v1"
+export UNCOMMON_ROUTE_API_KEY="csk-your-key"
+uncommon-route serve
+```
+
+一把 key 打通 OpenAI、Anthropic、Google、xAI、MiniMax、Moonshot、DeepSeek 等所有主流 provider——统一账单，无需逐家申请。
+
+**方式 B — 自带 key（BYOK）**
+
+```bash
+uncommon-route provider add openai     sk-...
+uncommon-route provider add anthropic  sk-ant-...
+uncommon-route provider add google     AIza...
+# 同样支持：xai、minimax、moonshot、deepseek
+uncommon-route serve
+```
+
+Auto 路由只会在已注册的 provider 范围内选模型。
+
+> **注意：** UncommonRoute **不会**自动读取 `OPENAI_API_KEY` / `ANTHROPIC_API_KEY` 环境变量。请使用 `uncommon-route init`、本地保存的连接配置，或上面的手动方式。
+
+</details>
+
 ---
 
 ## 工作原理
@@ -104,7 +122,7 @@ resp = client.chat.completions.create(model="uncommon-route/auto", messages=msgs
 | 信号 | 分析内容 | 耗时 |
 |---|---|---|
 | **元数据信号** | 对话轮次、工具调用、上下文深度 | <1ms |
-| **语义信号** | 与已知任务模式的相似度（embedding） | ~10ms |
+| **语义信号** | 与已知任务模式的相似度（embedding） | ~20ms |
 | **结构信号** | 文本复杂度特征（影子模式运行） | <1ms |
 
 三个信号投票，集成模型决定 tier，路由器在对应 tier 中选最便宜的模型。遇到不确定的情况，宁可多花一点也不冒失败风险。
@@ -139,7 +157,7 @@ v1 分类器在干净的 benchmark 上跑出了 88.5% 的准确率，我们直
 |---|---|
 | **成本节省** | **82%**（对比全程顶配） |
 | **任务完成率** | **93.4%** |
-| **路由延迟** | **<10ms** |
+| **路由延迟** | **~20–25ms**（warm process, CPU, bge-small embedding） |
 | **准确率** | **78%** tier 匹配 |
 
 ```bash
@@ -159,6 +177,19 @@ uncommon-route serve
 
 ---
 
+## 诊断与排障
+
+如果用户遇到路由异常、上游报错，或者某次请求行为不对，现在可以直接导出本地诊断包，不需要先猜该收集哪些日志：
+
+```bash
+uncommon-route support bundle
+uncommon-route support request <request_id>
+```
+
+诊断包会包含最近请求 trace、最近错误、统计摘要、provider / 配置快照，以及脱敏后的本地状态。默认只写到你的本机，只有你主动分享时才会离开电脑。
+
+---
+
 ## 配置
 
 ### 路由模式
@@ -207,6 +238,8 @@ uncommon-route provider remove <name>
 uncommon-route telemetry status
 ```
 
+`uncommon-route support bundle` 生成的诊断包默认也只会保存在 `~/.uncommon-route/support/`。
+
 ---
 
 ## 开发

openclaw-plugin/README.md

@@ -18,6 +18,7 @@ This plugin:
 - starts `uncommon-route serve`
 - registers the local provider with OpenClaw
 - exposes the virtual routing modes like `uncommon-route/auto`
+- keeps request traces and support diagnostics local on disk
 
 ## Install
 
@@ -85,14 +86,16 @@ If the plugin is installed but responses are failing:
 2. Make sure `UNCOMMON_ROUTE_API_KEY` is set if your provider requires one.
 3. Open `http://127.0.0.1:8403/health`.
 4. Open `http://127.0.0.1:8403/dashboard/`.
+5. Run `uncommon-route support bundle` to export recent traces and diagnostics.
 
 ## Benchmarks
 
 Current repo benchmarks:
 
-- 92.3% held-out routing accuracy
-- ~0.5ms average routing latency
-- 67% lower simulated cost than always using Claude Opus in a coding session
+- 82% lower cost than always routing to a premium model
+- 93.4% task pass rate on CommonRouterBench
+- ~20–25ms warm-process routing overhead on CPU
+- 78% tier-match accuracy through the production routing path
 
 ## Links
 

openclaw-plugin/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@anjieyang/uncommon-route",
-  "version": "0.6.0",
+  "version": "0.7.0",
   "description": "OpenClaw plugin for UncommonRoute, the local LLM router that cuts premium-model spend",
   "type": "module",
   "main": "src/index.js",

openclaw-plugin/src/index.js

@@ -16,7 +16,7 @@
 import { spawn, execSync } from "node:child_process";
 import { setTimeout as sleep } from "node:timers/promises";
 
-const VERSION = "0.4.0";
+const VERSION = "0.7.0";
 const DEFAULT_PORT = 8403;
 const DEFAULT_UPSTREAM = "";
 const HEALTH_TIMEOUT_MS = 15_000;

pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "uncommon-route"
-version = "0.6.0"
+version = "0.7.0"
 description = "Local LLM router that cuts premium-model spend with adaptive 3-tier routing, OpenAI + Anthropic compatible"
 requires-python = ">=3.11"
 license = "MIT"

tests/conftest.py

@@ -4,6 +4,7 @@
 
 import pytest
 
+from uncommon_route.connections_store import ConnectionsStore, InMemoryConnectionsStorage
 from uncommon_route.model_experience import (
     InMemoryModelExperienceStorage,
     ModelExperienceStore,
@@ -20,6 +21,14 @@ def spend_control() -> SpendControl:
 
 @pytest.fixture(autouse=True)
 def _isolate_proxy_defaults(monkeypatch: pytest.MonkeyPatch) -> None:
+    monkeypatch.setattr(
+        "uncommon_route.proxy._LOCAL_CLIENT_HOSTS",
+        {"127.0.0.1", "::1", "localhost", "testclient"},
+    )
+    monkeypatch.setattr(
+        "uncommon_route.proxy.ConnectionsStore",
+        lambda: ConnectionsStore(storage=InMemoryConnectionsStorage()),
+    )
     monkeypatch.setattr(
         "uncommon_route.proxy.load_providers",
         lambda: ProvidersConfig(),

tests/test_anthropic_compat.py

@@ -637,7 +637,18 @@ def test_no_upstream_returns_anthropic_error(self) -> None:
         assert data["type"] == "error"
         assert data["error"]["type"] == "overloaded_error"
 
-    def test_upstream_unreachable_returns_anthropic_error(self, messages_client: TestClient) -> None:
+    def test_upstream_unreachable_returns_anthropic_error(
+        self,
+        messages_client: TestClient,
+        monkeypatch: pytest.MonkeyPatch,
+    ) -> None:
+        class FailingClient:
+            is_closed = False
+
+            async def post(self, *args, **kwargs):
+                raise httpx.ConnectError("connection refused")
+
+        monkeypatch.setattr("uncommon_route.proxy._get_client", lambda: FailingClient())
         resp = messages_client.post("/v1/messages", json={
             "model": "some-model",
             "max_tokens": 100,