@thomas-huang/caosi 0.1.4 → 0.3.0

package/README.md

@@ -1,10 +1,24 @@
+<p align="center">
+  <img src="assets/logo/caosi-icon.svg" width="88" height="88" alt="caosi">
+</p>
+
 # caosi
 
 [中文](README.zh-CN.md)
 
-A local converter between LLM client protocols and named upstream providers. Point Claude Code, Codex, or Gemini CLI at `http://127.0.0.1:9999/{provider_name}`. Same protocol is passed through; OpenAI Chat, OpenAI Responses, Claude Messages, and Gemini are converted when they differ.
+Keep using Claude Code, Codex, or Gemini CLI. Point them at your own upstream — no client switch.
 
-caosi is a converter, not a gateway.
+Set the Base URL to `http://127.0.0.1:9999/{provider_name}`. OpenAI Chat, OpenAI Responses, Claude Messages, and Gemini convert in every direction; same protocol is passed through.
+
+- A single static binary. No Docker.
+- npm ships the binaries: no install script, nothing fetched from GitHub
+- macOS, Linux, and Windows
+
+```bash
+npm install -g @thomas-huang/caosi
+```
+
+No Web UI, no OAuth, no key pool, no client-config rewrite. One process, one file, loopback only.
 
 ## Install
 
@@ -13,7 +27,7 @@ npm install -g @thomas-huang/caosi
 caosi --version
 ```
 
-Needs Node.js 18+ on macOS, Linux, or Windows (amd64). The npm package includes native binaries; there is no install script and nothing is fetched from GitHub at install time.
+Needs Node.js 18+ on macOS or Linux (amd64 and arm64), or Windows (amd64). The npm package includes native binaries; there is no install script and nothing is fetched from GitHub at install time.
 
 ## Run
 
@@ -23,7 +37,7 @@ The first start writes a sample Provider File and exits. That is intentional: ca
 caosi
 ```
 
-Edit `~/.caosi/providers.jsonc`. Set `api_key` and `base_url`. If Claude Code will talk to an OpenAI-compatible upstream, keep `model` (for example `deepseek-chat`) so the upstream does not see `claude-*`.
+Edit `~/.caosi/providers.jsonc`. Set `api_key` and `base_url`. If Claude Code will talk to an OpenAI-compatible upstream, keep `model` (for example `qwen/qwen3-coder`) so the upstream does not see `claude-*`.
 
 Start again:
 
@@ -35,26 +49,26 @@ curl -s http://127.0.0.1:9999/health
 ## Point Claude Code at it
 
 ```bash
-export ANTHROPIC_BASE_URL=http://127.0.0.1:9999/deepseek
+export ANTHROPIC_BASE_URL=http://127.0.0.1:9999/openrouter
 export ANTHROPIC_API_KEY=dummy
 claude
 ```
 
-Replace `deepseek` with your Provider Name. caosi ignores the client key and uses the Provider's `api_key`. Claude Code sends `/v1/messages`; caosi converts when the upstream is not Claude.
+Replace `openrouter` with your Provider Name. caosi ignores the client key and uses the Provider's `api_key`. Claude Code sends `/v1/messages`; caosi converts when the upstream is not Claude.
 
 ## Codex / OpenAI and Gemini CLI
 
 OpenAI SDK, Chat Completions, and Codex:
 
 ```bash
-export OPENAI_BASE_URL=http://127.0.0.1:9999/deepseek/v1
+export OPENAI_BASE_URL=http://127.0.0.1:9999/openrouter/v1
 export OPENAI_API_KEY=dummy
 ```
 
 Gemini CLI (`~/.gemini/.env` or the environment):
 
 ```bash
-export GEMINI_API_BASE=http://127.0.0.1:9999/deepseek
+export GEMINI_API_BASE=http://127.0.0.1:9999/openrouter
 ```
 
 ## Provider File
@@ -63,11 +77,11 @@ export GEMINI_API_BASE=http://127.0.0.1:9999/deepseek
 
 ```jsonc
 {
-  "deepseek": {
-    "base_url": "https://api.deepseek.com",
+  "openrouter": {
+    "base_url": "https://openrouter.ai/api",
     "protocol": "openai_chat",
     "api_key": "sk-...",
-    "model": "deepseek-chat"
+    "model": "qwen/qwen3-coder"
   }
 }
 ```
@@ -79,19 +93,24 @@ export GEMINI_API_BASE=http://127.0.0.1:9999/deepseek
 | `claude_messages` | Claude Messages |
 | `gemini` | Gemini generateContent |
 
-- `model` is optional: when set, it replaces the client's model name on the upstream request.
+- `model` is optional: when set, it replaces the client's model name on the upstream request, including when the protocols already match.
 - `headers` is optional extra request headers (for example OpenRouter).
-- `base_url` is a prefix. caosi does not strip `/v1`. Use the root the upstream actually expects (`https://api.deepseek.com`, not `https://api.deepseek.com/v1`).
+- `base_url` is a prefix. caosi does not strip `/v1`. Use the root the upstream actually expects (`https://openrouter.ai/api`, not `https://openrouter.ai/api/v1`).
+
+Same protocol is copied through. Different protocols remap the body: text, system instruction, tools, thinking, Thinking Signature, in-message images, documents, audio, and video, and Usage Details (reasoning / cache-read / cache-create token counts) are kept when the other protocol can express them; otherwise that part is dropped and the rest is sent. caosi does not fetch URLs or Files API objects (`file_id`, `fileUri`). Dedicated image, files, audio, video, and embeddings paths stay 404.
 
 ## Listen, health, reload
 
 - Loopback only: `127.0.0.1` (or `::1` via `--listen`). Default port `9999` (`--port`).
-- `GET /health`
+- `GET /health` returns JSON with the current Provider Names.
 - Saving `providers.jsonc` hot-reloads; a bad file keeps the last good config.
+- Request and JSON-response bodies over 32MiB are rejected (413).
 - Flags: `--config-dir`, `--port`, `--listen`, `--log-level`, `--version`.
 
 ## What it does not do
 
+caosi is a converter, not a gateway.
+
 No Web UI, OAuth, failover, key pools, or rewriting your Claude Code / Codex / Gemini config files.
 
 ## Without Node.js
@@ -105,7 +124,7 @@ go install github.com/thomas-huang/caosi/cmd/caosi@latest
 go test ./...
 ```
 
-Domain language: [CONTEXT.md](CONTEXT.md). Decisions: [docs/adr](docs/adr).
+Domain language: [CONTEXT.md](CONTEXT.md). Architecture: [docs/architecture.md](docs/architecture.md). Decisions: [docs/adr](docs/adr).
 
 To cut a release, push a tag `vX.Y.Z`. GitHub Actions builds the five binaries, writes checksums, creates the Release, and publishes `@thomas-huang/caosi` to npm with GitHub OIDC trusted publishing (no access token).
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@thomas-huang/caosi",
-  "version": "0.1.4",
+  "version": "0.3.0",
   "description": "Local converter between LLM client protocols and named upstream providers",
   "license": "MIT",
   "homepage": "https://github.com/thomas-huang/caosi",