Release 0.4.0 with rewritten project README

Author: sparrowzhou

README.md

@@ -1,29 +1,189 @@
 # OpenClaw Router
 
-OpenClaw Router is a core execution-governance component for private AI systems. It classifies prompts by complexity and lets requests flow safely, cost-effectively, and auditably across local models, private models, and public models.
+OpenClaw Router is a core execution-governance component for private AI systems.
+
+Its job is simple to describe but hard to do well: let AI requests move across local models, private models, and public models in a way that is safe, cost-aware, and auditable.
+
+Most AI products today still route requests in a very rough way:
+- everything goes to the same expensive model
+- local models are underused
+- sensitive work is mixed with non-sensitive work
+- teams cannot clearly explain why a certain model was chosen
+- quality drops when people try to save cost with manual switching
+
+OpenClaw Router exists to solve that layer.
+
+This repository currently contains one key component in that broader governance stack: a local-first routing plugin for OpenClaw. It is designed for builders, operators, and product teams who want execution control instead of ad hoc prompt-to-model selection.
+
+The project is led by an AI-native builder, product-oriented founder, and direction-setting operator. The repository also reflects an active interest in connecting with aligned investors and project partners who want to help build the execution-governance layer for private AI systems.
+
+## What This Project Is
+
+At a high level, OpenClaw Router acts like a traffic controller for AI execution.
+
+When a user sends a request, the router looks at the request, estimates what kind of capability it needs, and decides whether it should stay on a local model, move to a private deployment, or escalate to a stronger public model.
+
+The goal is not just lower cost.
+
+The goal is better system behavior:
+- easy work should stay cheap
+- sensitive work should stay controlled
+- hard work should still reach strong models
+- every decision should be reviewable later
+
+## Why It Matters
+
+If you are building a serious AI product, model choice is no longer only an engineering detail. It becomes an execution policy problem.
+
+Examples:
+- A short rewrite task should not burn premium API budget.
+- A coding or debugging task should not be forced onto an underpowered local model just because it is cheap.
+- A compliance-sensitive workflow may need to prefer private infrastructure.
+- A repeated failure should trigger escalation instead of silently getting stuck.
+- A team should be able to inspect routing decisions and improve them over time.
+
+This is the gap OpenClaw Router is meant to fill.
+
+## What The Repository Contains
+
+- `router-plugin/`: the main TypeScript plugin that runs inside OpenClaw
+- `docs/`: supporting documentation, examples, roadmap, and API contract
+- `skills/router-rule-tuner/`: a local skill for analyzing router decisions and tuning rules
+- `.github/`: CI and repository workflow templates
+
+## What It Does Today
+
+- Classifies prompts into execution tiers
+- Keeps simple, low-risk work on low-cost paths when possible
+- Escalates code, debugging, complex analysis, and reasoning work to stronger tiers
+- Supports local-first routing instead of API-first routing
+- Tracks retries and session depth so the system can recover from weak routing
+- Logs decisions for auditability and later optimization
+- Learns from historical routing data to improve future routing
+- Exposes `/router`, `/router stats`, and `/router learn`
+
+## How It Works
+
+```mermaid
+flowchart TD
+    A["User prompt enters OpenClaw"] --> B["Router intercepts at before_model_resolve"]
+    B --> C["Extract signals from the prompt
+keywords, code fences, file paths, length, structure, constraints"]
+    C --> D["Classify the request into a capability tier"]
+    D --> E["Apply governance rules
+confidence thresholds, retry handling, session lock, fallback policy"]
+    E --> F{"Best execution path?"}
+    F --> G["Local model
+for simple, cheap, low-risk work"]
+    F --> H["Private model
+for controlled internal execution"]
+    F --> I["Public model
+for selective escalation to stronger external capability"]
+    G --> J["Return answer"]
+    H --> J
+    I --> J
+    J --> K["Log decision and context signals"]
+    K --> L["Analyze patterns and refine routing
+via /router stats and /router learn"]
+```
+
+## The Routing Model In Plain English
+
+The plugin does not think in terms of one model being “best”.
+
+It thinks in terms of matching work to the right execution level.
+
+Current routing tiers:
+
+| Tier | Plain-English meaning | Typical use |
+|------|-----------------------|-------------|
+| `efficient-response` | Fast and cheap execution | short text tasks, summaries, rewrites, translation |
+| `cost-optimized-solving` | Balanced default path | general requests that need more than a tiny local model |
+| `custom-policy` | Complex task path | strategy, architecture, multi-constraint analysis |
+| `control-orchestration` | Formal reasoning path | proof-style reasoning, derivations, structured decision logic |
+| `assured-intelligence` | High-confidence code path | coding, debugging, refactoring, implementation tasks |
+
+In practice, this means a casual prompt and a high-stakes coding task do not need to hit the same model.
+
+## What Makes It Different
+
+This project is not trying to be “just another prompt classifier”.
+
+It is building toward an execution-governance layer with a few important properties:
+
+- Local-first by design: cheap work stays local when it can.
+- Policy-oriented: routing is driven by explicit rules and thresholds, not hidden provider behavior.
+- Auditable: decisions can be logged, reviewed, and tuned later.
+- Adaptive: the system can learn from real traffic instead of staying static.
+- Safe by default: first install starts in `suggest` mode rather than immediately overriding models.
+
+## Who This Is For
+
+OpenClaw Router is especially useful for:
+
+- teams building private AI systems
+- founders who want cost control without quality collapse
+- operators running a mix of local, private, and external models
+- AI product builders who need clearer execution policies
+- anyone who wants an inspectable routing layer instead of opaque model selection
+
+## A Simple Example
+
+Imagine the same system receives these three requests:
+
+1. “Summarize this paragraph.”
+2. “Compare two product strategies and list risks.”
+3. “Debug this TypeScript function and refactor it.”
+
+Without governance, all three might go to the same expensive model.
+
+With OpenClaw Router:
+- the summary can stay on a fast local model
+- the strategy comparison can go to a stronger planning tier
+- the coding task can escalate to a code-focused tier
+
+That is the core value: better model allocation, lower waste, and clearer system behavior.
 
-This repository currently contains one key component in that governance layer: a local-first model routing plugin for OpenClaw. It is designed for teams and builders who want strong execution control instead of ad hoc model switching.
+## Routing Modes
+
+OpenClaw Router supports three operating modes:
+
+- `suggest`: the safest first-install mode; it recommends a route but does not override the active model
+- `override`: it actively applies routing decisions
+- `respect-explicit`: it routes normally except for agents that already have an explicitly assigned primary model
 
 The repository ships in a safe first-install posture: routing defaults to `suggest`, and real model overrides stay disabled until the user explicitly configures all tier models for their own environment.
 
-It is especially useful for people who already run one or more local models on their own machine or home lab and want OpenClaw to keep easy work local while still escalating harder prompts to stronger remote models only when necessary.
+## Learning And Auditability
 
-The project is led by an AI-native builder, product-oriented founder, and direction-setting operator. The repository also explicitly reflects an active intention to connect with aligned investors and project partners who want to help build the execution-governance layer for private AI systems.
+One of the most important parts of the project is that routing decisions are not treated as disposable runtime noise.
 
-## Repository Layout
+They become system data.
 
-- `router-plugin/` - TypeScript plugin, tests, build output, and plugin manifest
-- `docs/` - design notes and host/plugin API contract
-- `skills/router-rule-tuner/` - local skill for analysing router logs and tuning rules
-- `.github/workflows/ci.yml` - CI for build, type-check, and test
+The router can:
+- write structured decision logs
+- track retry behavior
+- track conversation depth
+- surface routing patterns in `/router stats`
+- learn weight adjustments from historical behavior through `/router learn`
+
+This is what makes the project useful as governance infrastructure rather than only a convenience plugin.
+
+## Current Status
 
-## What It Does
+Current repository version: `0.4.0`
 
-- Keeps simple, low-risk tasks on local models when possible
-- Routes code and debugging work to a stronger code-oriented tier
-- Tracks retry and session-depth signals to avoid getting stuck on weak routing
-- Logs routing decisions for offline analysis and learning
-- Supports `/router`, `/router stats`, and `/router learn`
+What is already present:
+- routing tiers and rule-based classification
+- session-aware routing
+- retry-aware escalation
+- structured logging
+- dynamic weight learning
+- TF-IDF-assisted scoring
+- tests for core routing behavior
+
+What this repository represents strategically:
+- one working component inside a larger private-AI execution-governance vision
 
 ## Quick Start
 
@@ -50,7 +210,14 @@ Then enable the plugin in `~/.openclaw/openclaw.json`:
 }
 ```
 
-Before switching to `override`, replace all `router.config.tiers.*` model refs with models that actually exist in the installer's environment. The plugin cannot auto-discover local/provider models from the current OpenClaw host API.
+Before switching to `override`, replace all `router.config.tiers.*` model references with models that actually exist in your own environment.
+
+## Repository Layout
+
+- `router-plugin/` - TypeScript plugin, tests, build output, and plugin manifest
+- `docs/` - design notes and host/plugin API contract
+- `skills/router-rule-tuner/` - local skill for analyzing router logs and tuning rules
+- `.github/workflows/ci.yml` - CI for build, type-check, and test
 
 ## Docs
 
@@ -71,6 +238,17 @@ npm run build
 npm test
 ```
 
+## Collaboration
+
+The project is open to conversations with:
+- investors who understand the long-term importance of execution governance in private AI systems
+- product and technical partners who want to build this layer together
+- operators who can validate real routing and deployment needs
+
 ## License
 
 MIT. See [LICENSE](./LICENSE).
+
+## 📊 Star History
+
+[![Star History Chart](https://api.star-history.com/svg?repos=sparrowzhou/OpenClawRouter&type=Date)](https://www.star-history.com/#sparrowzhou/OpenClawRouter&Date)

README_CN.md

@@ -36,7 +36,7 @@ OpenClaw-Router/
 │   ├── dist/                     # 编译输出
 │   ├── openclaw.plugin.json      # Web 配置 schema
 │   ├── tsconfig.json
-│   └── package.json              # v0.3.0
+│   └── package.json              # v0.4.0
 ├── skills/
 │   └── router-rule-tuner/        # 调参 Skill
 │       ├── SKILL.md              #   Skill 定义

router-plugin/README.md

@@ -1,6 +1,6 @@
 # OpenClaw Router
 
-Local-first model router plugin for OpenClaw. v0.3.0
+Local-first model router plugin for OpenClaw. v0.4.0
 
 This plugin is a strong fit for users who already have locally deployed models and want a practical way to keep simple prompts on those local models while escalating only the harder requests to stronger hosted models.
 

router-plugin/package-lock.json

@@ -1,6 +1,6 @@
 {
   "name": "router",
-  "version": "0.3.0",
+  "version": "0.4.0",
   "description": "Rule-based model router for OpenClaw Router local + CLI backends",
   "type": "module",
   "main": "dist/index.js",

router-plugin/package.json

@@ -57,7 +57,7 @@ const plugin = {
   id: "router",
   name: "OpenClaw Router",
   description: "Local-first token optimization router for OpenClaw Router",
-  version: "0.3.0",
+  version: "0.4.0",
 
   register(api: PluginApi) {
     if (!shutdownHooksRegistered) {