xiaodcs-copilot-api 2.3.9-public.1 → 2.4.1-public.1

package/README.md

@@ -10,13 +10,15 @@
   Chat Completions · OpenAI Responses · Anthropic Messages
 </p>
 
-> **XiaoDcs downstream build:** this public npm artifact is built from a
-> private downstream repository and adds Responses image-body budgeting,
-> stale compaction recovery, and Codex Fast tier routing. The original
-> MIT-licensed project is [caozhiyuan/copilot-api](https://github.com/caozhiyuan/copilot-api).
+> **XiaoDcs package channels:** `xiaodcs-copilot-api-edge` and
+> `xiaodcs-copilot-api` are currently built from the same Edge source. Only the
+> npm identity and executable name differ, so either package runs the same
+> gateway code. The original MIT-licensed project is
+> [caozhiyuan/copilot-api](https://github.com/caozhiyuan/copilot-api).
 
 <p align="center">
-  <a href="https://www.npmjs.com/package/xiaodcs-copilot-api"><img src="https://img.shields.io/npm/v/xiaodcs-copilot-api.svg" alt="npm version"></a>
+  <a href="https://www.npmjs.com/package/xiaodcs-copilot-api-edge"><img src="https://img.shields.io/npm/v/xiaodcs-copilot-api-edge.svg" alt="npm version"></a>
+  <a href="https://www.npmjs.com/package/xiaodcs-copilot-api"><img src="https://img.shields.io/npm/v/xiaodcs-copilot-api.svg" alt="ordinary npm version"></a>
   <a href="https://github.com/caozhiyuan/copilot-api/blob/main/LICENSE"><img src="https://img.shields.io/badge/license-MIT-blue.svg" alt="License"></a>
   <a href="https://github.com/caozhiyuan/copilot-api/stargazers"><img src="https://img.shields.io/github/stars/caozhiyuan/copilot-api.svg" alt="GitHub stars"></a>
   <a href="https://bun.sh"><img src="https://img.shields.io/badge/Bun-%3E%3D1.2.x-orange.svg" alt="Bun >= 1.2.x"></a>
@@ -31,6 +33,12 @@
 
 The fastest way to get a working gateway:
 
+```sh
+npx xiaodcs-copilot-api-edge@latest start
+```
+
+The ordinary package name is an equivalent compatibility channel:
+
 ```sh
 npx xiaodcs-copilot-api@latest start
 ```
@@ -38,7 +46,7 @@ npx xiaodcs-copilot-api@latest start
 The server listens on `http://localhost:4141` by default. Optionally authenticate with GitHub Copilot or configure a third-party provider first:
 
 ```sh
-npx xiaodcs-copilot-api@latest auth login
+npx xiaodcs-copilot-api-edge@latest auth login
 ```
 
 Verify the gateway is up:
@@ -50,19 +58,6 @@ curl http://localhost:4141/v1/models
 > [!NOTE]
 > Token usage storage requires Node.js >= 22.13.0 or Bun. See [Using with npx](#using-with-npx) for details.
 
-### Public package traffic policy
-
-The `xiaodcs-copilot-api` public package applies a fixed, process-local policy before any model upstream request begins:
-
-- at most 4 active upstream model requests;
-- at most 1 request start per second and 20 starts per rolling minute;
-- 300–900 ms of admission jitter;
-- a FIFO queue of 16 requests with a 45-second wait limit;
-- 5% pre-upstream load shedding, returned as HTTP `429` with `Retry-After`;
-- image generation and editing endpoints are not registered. Image inputs to Chat Completions, Responses, and Messages remain supported where the model supports vision.
-
-The counters are local to one running process. Separate machines or gateway processes have independent limits.
-
 From here, jump to the guide for your client: [Claude Code](#using-with-claude-code), [OpenCode](#using-with-opencode), [Codex](#using-with-codex), or run it with [Docker](#using-with-docker).
 
 ## Highlights
@@ -111,7 +106,7 @@ There are two ways to configure Claude Code to use this AI gateway:
 To get started, run the `start` command with the `--claude-code` flag:
 
 ```sh
-npx xiaodcs-copilot-api@latest start --claude-code
+npx xiaodcs-copilot-api-edge@latest start --claude-code
 ```
 
 You will no longer be prompted to pick models manually. The gateway automatically detects the latest available model for each Claude Code size tier — opus maps to the newest Opus model, sonnet to the newest Sonnet model, and haiku to the newest Haiku model — and generates a command that sets `ANTHROPIC_DEFAULT_OPUS_MODEL`, `ANTHROPIC_DEFAULT_SONNET_MODEL`, and `ANTHROPIC_DEFAULT_HAIKU_MODEL` accordingly. Any tier without a matching model available is omitted. The command is copied to your clipboard and sets the environment variables needed for Claude Code to use the gateway.
@@ -180,8 +175,8 @@ OpenCode already has a direct GitHub Copilot provider. Use this section when you
 Start the AI gateway with the OpenCode OAuth app:
 
 ```sh
-npx xiaodcs-copilot-api@latest auth --oauth-app=opencode
-npx xiaodcs-copilot-api@latest start
+npx xiaodcs-copilot-api-edge@latest auth --oauth-app=opencode
+npx xiaodcs-copilot-api-edge@latest start
 ```
 
 Then point OpenCode at the gateway with `@ai-sdk/anthropic`.
@@ -340,6 +335,8 @@ Without this configuration, Codex cannot fetch `/v1/models` while not signed in
 
 When a Codex client (`User-Agent` starts with `codex`) requests the top-level `GET /v1/models`, the gateway merges native Codex models with models available through the Messages adapter. The latter advertise `use_responses_lite: true`, except DeepSeek models, which use `use_responses_lite: false` and `tool_mode: null`. For other models, `/v1/responses` uses **Responses → Messages** for Anthropic providers, while OpenAI-compatible providers and Chat-only Copilot models reuse the existing Messages route for **Responses → Messages → Chat Completions**, then translate streaming or JSON results back to Responses.
 
+> **Note:** DeepSeek models do not use Responses Lite (`use_responses_lite: false`, `tool_mode: null`), so the tool set they advertise to Codex differs from other models, which use `tool_mode: "code_mode_only"`. Switching between a DeepSeek model and a Responses Lite model mid-session is not compatible, because tool calls and conversation history produced under one tool set do not translate to the other. Start a new Codex session when switching between them.
+
 The merged catalog is what Codex shows in its model picker, including the models exposed by your configured providers:
 
 <img src="./docs/screenshots/codex-models.png" alt="Codex model picker showing models provided by the gateway" width="900" />
@@ -381,7 +378,7 @@ On the GitHub Copilot path, the gateway prefers Copilot's native Anthropic-style
 >
 > 3. **OpenCode configuration:** When using with OpenCode, configure `~/.config/opencode/opencode.json` with `@ai-sdk/anthropic`. See [Using with OpenCode](#using-with-opencode).
 >
-> 4. **Built-in `copilot`, `codex` and third-party providers:** Run `npx xiaodcs-copilot-api@latest auth` and choose `copilot`, `codex`, `deepseek`, `custom`, or other providers.
+> 4. **Built-in `copilot`, `codex` and third-party providers:** Run `npx xiaodcs-copilot-api-edge@latest auth` and choose `copilot`, `codex`, `deepseek`, `custom`, or other providers.
 >
 > 5. **Note:** See [GitHub Copilot Security Notice](./NOTICE.md#github-copilot-security-notice) for the warning removed from the README header.
 
@@ -425,29 +422,29 @@ You can run the project directly using npx:
 > [!IMPORTANT]
 > Token usage storage uses Node's built-in `node:sqlite` module when running with `npx`. It is enabled on Node.js >= 22.13.0. On Node.js < 22.13.0, the CLI still starts, but token usage storage is disabled.
 >
-> If you want token usage storage without upgrading Node.js, run the published CLI with Bun instead: `bunx --bun xiaodcs-copilot-api@latest start`.
+> If you want token usage storage without upgrading Node.js, run the published CLI with Bun instead: `bunx --bun xiaodcs-copilot-api-edge@latest start`.
 
 ```sh
-npx xiaodcs-copilot-api@latest start
+npx xiaodcs-copilot-api-edge@latest start
 ```
 
 With options:
 
 ```sh
-npx xiaodcs-copilot-api@latest start --port 8080
+npx xiaodcs-copilot-api-edge@latest start --port 8080
 ```
 
 For authentication or provider configuration only:
 
 ```sh
-npx xiaodcs-copilot-api@latest auth
+npx xiaodcs-copilot-api-edge@latest auth
 ```
 
 To run without GitHub Copilot, configure at least one provider first, then start the server normally:
 
 ```sh
-npx xiaodcs-copilot-api@latest auth login --provider dashscope
-npx xiaodcs-copilot-api@latest start
+npx xiaodcs-copilot-api-edge@latest auth login --provider dashscope
+npx xiaodcs-copilot-api-edge@latest start
 ```
 
 ## Using with Docker
@@ -508,7 +505,7 @@ Add the tool search bridge to the MCP config used by Claude Code:
     "tool_search": {
       "type": "stdio",
       "command": "npx",
-      "args": ["-y", "xiaodcs-copilot-api@latest", "mcp"]
+      "args": ["-y", "xiaodcs-copilot-api-edge@latest", "mcp"]
     }
   }
 }
@@ -521,7 +518,7 @@ Add the tool search bridge to the MCP config used by opencode:
   "mcp": {
     "tool_search": {
       "type": "local",
-      "command": ["npx", "-y", "xiaodcs-copilot-api@latest", "mcp"]
+      "command": ["npx", "-y", "xiaodcs-copilot-api-edge@latest", "mcp"]
     }
   }
 }
@@ -601,7 +598,7 @@ After starting the server, a URL to the Copilot Usage Dashboard will be displaye
 
 1.  Start the server. For example, using npx:
     ```sh
-    npx xiaodcs-copilot-api@latest start
+    npx xiaodcs-copilot-api-edge@latest start
     ```
 2.  The server will output a URL to the usage viewer. Copy and paste this URL into your browser. It will look something like this:
     `http://localhost:4141/usage-viewer?endpoint=http://localhost:4141/usage`
@@ -613,16 +610,16 @@ The dashboard provides a user-friendly interface to view your Copilot usage data
 
 - **API Endpoint URL**: The dashboard is pre-configured to fetch data from your local server endpoint via a URL query parameter. You can manually switch this to any other compatible API endpoint.
 - **API Key Authentication**: If API Key authentication is enabled, enter a raw API key (sent as the `x-api-key` header) or `Authorization: Bearer <key>`. Credentials are remembered in the browser's local storage per endpoint origin, and switching to a different endpoint origin does not automatically send the previous credential.
-- **Period Selector**: Choose from Day, Week, or Month time ranges. The URL query parameter updates automatically when you switch, making it easy to bookmark and share.
+- **Period Selector**: Choose from six time ranges: `today` (the current local calendar day so far), `this_week` (Monday at 00:00 through now), `last_7_days` (the rolling seven calendar days through now), `this_month` (the first day of the current month at 00:00 through now), `last_30_days` (the rolling 30 calendar days through now), and `lifetime` (the earliest recorded event through now). Today is selected by default, and the exact date range appears next to the selector. The URL query parameter updates automatically when you switch, making it easy to bookmark and share. The legacy values `day`, `week`, and `month` are still accepted and mapped to their new equivalents.
 - **Fetch Data**: Click the "Refresh" button to load or refresh the usage data. The dashboard also fetches data automatically on page load.
 - **Copilot Quotas**: View quota usage for services such as Chat and Completions via progress bars. Hover over a card to see used/remaining details.
 - **Token Usage Metric Cards**: See a summary of Total, Input, Output, Cache Read, Cache Write, Requests, and estimated cost for the current period.
-- **Trend Chart (Week / Month)**: An interactive line chart with model and metric filters. Click a data point to inspect the usage breakdown for a specific day.
+- **Trend Chart**: An interactive line chart with model and metric filters for the selected period. Click a data point to inspect the usage breakdown for a day; Lifetime chart data is sampled from the daily buckets and capped at 180 points for readability.
 - **Model Breakdown Table**: A per-model summary of requests, input/output/cache tokens, and estimated cost for the selected period.
 - **Request Events (Paginated)**: A time-sorted list of request event records with pagination support, showing timestamps, models, request IDs, and token counts.
 - **Detailed Information**: See the full JSON response from the API for a detailed breakdown of all available usage statistics.
 - **URL-based Configuration**: You can also specify the API endpoint and period directly via `endpoint` and `period` query parameters. For example:
-  `http://localhost:4141/usage-viewer?endpoint=http://your-api-server/usage&period=week`
+  `http://localhost:4141/usage-viewer?endpoint=http://your-api-server/usage&period=this_week`
 
 ### Usage Viewer Screenshot
 
@@ -715,6 +712,7 @@ Gateway API keys live under `auth.apiKeys` in `config.json`. Manage them with `c
     "useMessagesApi": true,
     "useResponsesApiCompactionRecovery": false,
     "useResponsesApiWebSocket": true,
+    "useCopilotFastTier": true,
     "responsesTransport": {
       "headersTimeoutMsV2": 300000,
       "streamInactivityTimeoutMs": 300000,
@@ -736,8 +734,8 @@ Gateway API keys live under `auth.apiKeys` in `config.json`. Manage them with `c
 - **providers:** Global upstream provider map. Each provider key (for example `dashscope`) becomes a route prefix (`/dashscope/v1/messages`). Supports `type: "anthropic"`, `type: "openai-compatible"`, and `type: "openai-responses"`. Top-level clients can also use `model: "dashscope/model-id"` with `/v1/messages`, `/v1/messages/count_tokens`, `/v1/responses`, and `/v1/chat/completions`; the gateway strips the `dashscope/` prefix before forwarding upstream. The `/v1/responses` route for `anthropic` and `openai-compatible` providers uses the Responses Lite → Messages adapter; `openai-compatible` providers then reuse the Messages → Chat translation. Codex clients (`User-Agent` starting with `codex`) also use the adapter for non-`gpt-*` models on `openai-responses` providers. `GET /v1/models` aggregates enabled provider models with `provider/model-id` IDs, while the top-level Codex-UA catalog also merges these adaptable models as `use_responses_lite` entries (except DeepSeek models, which use `use_responses_lite: false` and `tool_mode: null`). Use `GET /dashscope/v1/models` for a single provider's raw model list.
   - `enabled` defaults to `true` if omitted.
   - `baseUrl` should be provider API base URL without the final endpoint. For Anthropic providers, omit `/v1/messages`; for OpenAI-compatible providers, omit `/v1/chat/completions`; for OpenAI Responses providers, omit `/v1/responses`.
-  - `apiKey` is used as the upstream credential value and is required for regular providers.
-  - `authType` (optional): Controls how `apiKey` is sent upstream. Supports `x-api-key` and `authorization` for regular providers. Anthropic providers default to `x-api-key`; OpenAI-compatible and OpenAI Responses providers default to `authorization`. When set to `authorization`, the proxy sends `Authorization: Bearer <apiKey>`. `oauth2` is reserved for the built-in `codex` provider and is written automatically by `auth login --provider codex`.
+  - `apiKey` is used as the upstream credential value and is required unless `authType` is `azure-entra`.
+  - `authType` (optional): Controls upstream authentication. Supports `x-api-key`, `authorization`, and `azure-entra` for regular providers. Anthropic providers default to `x-api-key`; OpenAI-compatible and OpenAI Responses providers default to `authorization`. `authorization` sends `Authorization: Bearer <apiKey>`. `azure-entra` uses Azure Identity's `DefaultAzureCredential` with the `https://cognitiveservices.azure.com/.default` scope, sends the resulting bearer token, and does not require `apiKey`. For an Azure OpenAI v1 endpoint, use a provider such as `{ "type": "openai-compatible", "baseUrl": "https://<resource-name>.openai.azure.com/openai", "authType": "azure-entra" }`. Authenticate locally with `az login`, use a managed identity in Azure, or set the standard `AZURE_TENANT_ID`, `AZURE_CLIENT_ID`, and `AZURE_CLIENT_SECRET` environment variables. `oauth2` is reserved for the built-in `codex` provider and is written automatically by `auth login --provider codex`.
   - `pricingCurrency` (optional): Provider-level currency used for token cost calculation, for example `USD` or `CNY`. Quick providers default to `CNY` for DashScope and DeepSeek, and `USD` for Codex, Kimi, OpenCode Go, and OpenRouter. Costs are grouped by currency and are not exchange-rate converted.
   - `models` (optional): Per-model configuration map. Each key is a model ID (matching the model name in requests), and the value is:
     - `temperature` (optional): Default temperature value used when the request does not specify one.
@@ -748,12 +746,13 @@ Gateway API keys live under `auth.apiKeys` in `config.json`. Manage them with `c
     - `contextCache` (optional): Defaults to `true` for providers whose name is `dashscope` or whose `baseUrl` contains `aliyuncs.com`; defaults to `false` for other OpenAI-compatible providers. This enables Alibaba Cloud Model Studio/DashScope explicit context cache by injecting `cache_control: { "type": "ephemeral" }` on up to 4 content blocks using the Context Cache format. The cache breakpoint strategy matches opencode's main provider flow: the first 2 system messages plus the last 2 non-system messages. Marked string content is converted to text content part arrays for `system` / `user` / `assistant` / `tool` messages; existing array content is marked on the last part. Set this to `false` when the model already supports implicit caching, or when the upstream does not accept this explicit-cache extension field. Set this to `true` for non-DashScope providers that support the same explicit-cache extension. Applied on both `/v1/messages` and `/v1/chat/completions` routes.
     - `supportPdf` (optional): Controls whether the model supports PDF/document content. Defaults to `false`; unsupported PDFs are converted to a text notice. Set it to `true` to send PDF/document blocks as OpenAI Chat Completions file parts.
     - `toolContentSupportType` (optional): Tool result content capabilities for that model, as an array of `array`, `image`, and `pdf`. Provider routes default to string-only tool content when omitted. If `supportPdf` is `true` but this list does not include `pdf`, file parts in tool results are moved to user role messages. The Copilot main flow uses the same string-only default, because some Copilot models do not support array or image tool content either.
-    - `type` (optional): Per-model override of the provider protocol type. Supports `anthropic`, `openai-compatible`, and `openai-responses`. When set, the provider's `/v1/messages` route uses this model's type instead of the provider-level type for request routing, auth header resolution, and upstream endpoint selection. This is useful for providers like OpenCode Go whose upstream supports both OpenAI-compatible and Anthropic Messages APIs for different models. When the type is overridden, the auth header is resolved from the overridden type's default (Anthropic defaults to `x-api-key`; OpenAI-compatible/Responses default to `authorization`).
+    - `type` (optional): Per-model override of the provider protocol type. Supports `anthropic`, `openai-compatible`, and `openai-responses`. When set, the provider's `/v1/messages` route uses this model's type instead of the provider-level type for request routing, auth header resolution, and upstream endpoint selection. This is useful for providers like OpenCode Go whose upstream supports both OpenAI-compatible and Anthropic Messages APIs for different models. When the type is overridden, the auth header is resolved from the overridden type's default (Anthropic defaults to `x-api-key`; OpenAI-compatible/Responses default to `authorization`). Providers configured with `azure-entra` keep their Entra bearer credential instead of falling back to the overridden type's default.
     - `contextWindow` (optional): Context window token limit advertised when this model is merged into the Codex-UA model catalog; for example, `1000000` declares a 1M-token context window. Missing configured values use upstream metadata first, then the built-in non-GPT model catalog, then `256000`.
     - `maxOutputTokens` (optional): Maximum output token limit advertised in the Codex-UA model catalog. Missing configured values use upstream metadata first, then the built-in non-GPT model catalog, where defaults are capped at `64000`, then `32000`.
     - `inputModalities` (optional): Supported Codex input types. Use `["text", "image"]` for a model that accepts both text and images. Missing configured values use upstream metadata before the built-in non-GPT model catalog. GPT models do not receive these built-in capability defaults and continue to use the native Codex catalog or upstream metadata.
     - `reasoningEfforts` (optional): Reasoning levels advertised for Codex. Missing configured and upstream values use the built-in non-GPT model catalog before falling back to `["high", "xhigh", "max", "ultra"]`. Provider Responses requests with an unsupported effort are normalized to a supported level when these capabilities are known.
     - `defaultReasoningEffort` (optional): Default Codex reasoning level. Built-in model metadata may provide a known default; otherwise it defaults to `max` when available, then the first configured level. Synthetic Codex models always enable parallel tool calls.
+    - `reasoningField` (optional): Assistant thinking field sent upstream on OpenAI-compatible `/v1/messages` requests. Supports `reasoning` and `reasoning_content`; defaults to `reasoning_content`. Use `reasoning` for OpenRouter-style models; the built-in catalog already does this for OpenCode Go `hy3` and `hy4-preview`.
 - **smallModel:** Fallback model used for tool-less warmup messages (e.g., Claude Code probe requests); defaults to gpt-5-mini. The gateway forces this small model on no-tool warmup or probe requests to avoid consuming premium requests. This behavior only applies to non-token-based-billing GitHub Copilot accounts (`token_based_billing` is false); for token-based-billing accounts the warmup small-model fallback is skipped since there is no premium-request quota to preserve.
 - **contextManagement:** Controls whether the proxy adds Responses API `context_management` compaction instructions. `messages` applies when Anthropic-style `/v1/messages` requests are translated to Responses API, including `openai-responses` provider message routes, and defaults to `true`. `responses` applies to native `/v1/responses` traffic, including `provider/model` aliases and the built-in `codex` provider, and defaults to `false`. Enable `responses` only after checking that your client supports context management compaction. When enabled, the request includes `context_management` in the body and keeps only the latest compaction carrier on follow-up turns. The proxy only adds context management and compacts history for `gpt-*` models; both configuration switches have no effect on non-GPT models such as Grok. **Note:** Context management is also forcibly disabled for GPT-5.6 and above models (e.g. `gpt-5.6-sol`, `gpt-5.6-terra`, `gpt-5.6-luna`) because enabling it breaks prompt cache hits on those models. These overrides take precedence over the `contextManagement` and `modelResponsesApiCompactThresholds` settings.
  - **modelResponsesApiCompactThresholds:** Per-model Responses API `compact_threshold` overrides used when the proxy adds `context_management`. These values take precedence over the fallback threshold from `resolveResponsesCompactThreshold` (`max_prompt_tokens * ratio`, or the default fallback). Defaults set `gpt-5.4` and `gpt-5.5` to `217600` (`272000 * 0.8`). Models not listed continue to use the normal fallback logic.
@@ -764,6 +763,7 @@ Gateway API keys live under `auth.apiKeys` in `config.json`. Manage them with `c
 - **useMessagesApi:** When `true`, models that advertise Copilot's native `/v1/messages` endpoint use the Messages API. If Messages is disabled or unavailable for the selected model, the gateway uses Responses when that model advertises a Responses endpoint, then falls back to Chat Completions when supported. Set this to `false` to skip native Messages routing. Defaults to `true`.
 - **useResponsesApiCompactionRecovery (experimental):** When `true`, successful remote Responses compactions enqueue a non-blocking, low-reasoning shadow-summary request and store only that summary under a hash of the opaque compaction item in the private `~/.local/share/copilot-api/compaction-recovery/cache.sqlite` directory. If Copilot later rejects that compaction or connection-bound history, HTTP requests progressively rebuild the request from cached summaries and visible messages. This option defaults to `false` because shadow summaries add one background model request and recovery is lossy. WebSocket errors are recovered on the client's next retry; automatic same-request recovery is HTTP-only.
 - **useResponsesApiWebSocket:** When `true`, Copilot Responses requests use WebSocket for models that advertise `ws:/responses`; models that advertise only `/responses` use HTTP. Streamed Responses requests for the built-in `codex` provider use WebSocket whenever this setting is enabled, while non-streaming Codex requests always use HTTP. Set this to `false` to make Copilot use HTTP `/responses` where the selected model advertises it and to send streamed Codex Responses requests over HTTP. WebSocket failures are not retried automatically over HTTP. Defaults to `true`. If a proxy, VPN, or network blocks or destabilizes WebSocket traffic, disable this setting or switch networks.
+- **useCopilotFastTier:** Controls whether a client request with `service_tier: "fast"` or `"priority"` may route to a paired Copilot `*-fast` model. Defaults to `true`. Set it to `false` to force the standard model even when a Codex task retains a hidden Fast speed-tier selection. When enabled, an explicit upstream Fast 429 falls back once to the paired standard model and temporarily cools Fast routing according to `Retry-After` (30 seconds by default, capped at 5 minutes).
 - **responsesTransport:** Positive integer lifecycle and buffering limits for every upstream Responses transport. Invalid, zero, or negative values fall back to the defaults shown above. `headersTimeoutMsV2` covers connection setup through receipt of HTTP response headers; it is not a total generation deadline. `streamInactivityTimeoutMs` is reset by every HTTP body chunk or WebSocket message, allowing long generations to continue while they remain active. `websocketOpenTimeoutMs` limits the WebSocket handshake, while `websocketPoolIdleTimeoutMs` controls only completed, reusable pooled sockets. The byte and message limits bound queued WebSocket events; exceeding either limit fails that stream and invalidates its socket rather than dropping or reordering events.
 - **useResponsesApiWebSearch:** When `true`, the server keeps Responses API tools with `type: "web_search"` and forwards them upstream. Set to `false` to strip those tools from `/responses` payloads. Defaults to `true`.
 - **alphaSearchCodexPriority:** Defaults to `true`. Top-level alpha-search requests prefer the Codex alpha-search endpoint because it does not consume provider quota. If Codex is unavailable, or this setting is `false`, requests with a `provider/model` alias other than `codex/model` use that provider's `/v1/responses` endpoint, and requests without a provider prefix use GitHub Copilot Responses web search. The adapter recognizes every current Codex search command; unsupported `image_query` and `screenshot` operations return successful no-retry tool output.
@@ -816,11 +816,13 @@ These endpoints mimic the OpenAI API structure.
 
 ### Codex Backend Endpoints
 
-These endpoints implement the supported Codex backend APIs. Alpha search can use either the Codex backend or a Responses web-search adapter. Image generation and editing are disabled in this public package.
+These endpoints implement Codex backend APIs. Top-level image requests require an active Codex login; alpha search can use either the Codex backend or a Responses web-search adapter.
 
 | Endpoint                                                       | Method | Description                                                     |
 | -------------------------------------------------------------- | ------ | --------------------------------------------------------------- |
 | `POST /v1/alpha/search`                | `POST` | Routes Codex alpha-search requests to the Codex backend, or handles supported commands locally and through Responses web search. |
+| `POST /v1/images/generations` | `POST` | Forwards a JSON image generation request to the Codex Images upstream. When the request omits `Content-Type`, the gateway defaults it to `application/json`. Configured model mappings apply to the request `model`; a mapping that resolves to a `provider/model` alias forwards the request to that provider's images endpoint when the provider is configured. |
+| `POST /v1/images/edits` | `POST` | Forwards an image edit request to the Codex Images upstream. Send this request as `multipart/form-data` and let the HTTP client generate the `boundary`; the gateway preserves the incoming content type and buffers up to 64 MiB before forwarding it. Larger requests return `413`. Model mappings and `provider/model` alias routing apply to this endpoint as well. |
 
 For requests routed to the Codex backend, the gateway replaces client authorization and account headers with the active Codex login and preserves compatible request metadata. Responses-backed alpha search instead follows the selected Copilot or provider route.
 
@@ -856,23 +858,23 @@ Common `npx` commands:
 
 ```sh
 # Start the gateway
-npx xiaodcs-copilot-api@latest start
+npx xiaodcs-copilot-api-edge@latest start
 
 # Start on a custom port with verbose logging
-npx xiaodcs-copilot-api@latest start --port 8080 --verbose
+npx xiaodcs-copilot-api-edge@latest start --port 8080 --verbose
 
 # Run the auth flow
-npx xiaodcs-copilot-api@latest auth login
+npx xiaodcs-copilot-api-edge@latest auth login
 
 # Configure a third-party provider, then run without GitHub Copilot
-npx xiaodcs-copilot-api@latest auth login --provider dashscope
-npx xiaodcs-copilot-api@latest start
+npx xiaodcs-copilot-api-edge@latest auth login --provider dashscope
+npx xiaodcs-copilot-api-edge@latest start
 
 # Print debug information as JSON
-npx xiaodcs-copilot-api@latest debug --json
+npx xiaodcs-copilot-api-edge@latest debug --json
 
 # Run the published CLI with Bun instead of Node.js
-bunx --bun xiaodcs-copilot-api@latest start
+bunx --bun xiaodcs-copilot-api-edge@latest start
 ```
 
 OpenAI-compatible provider examples after configuring `dashscope`:

package/README.zh-CN.md

@@ -10,12 +10,14 @@
   Chat Completions · OpenAI Responses · Anthropic Messages
 </p>
 
-> **XiaoDcs 下游构建：** 这个公开 npm 产物由私有下游仓库构建，增加了
-> Responses 图片请求体预算、失效 compaction 恢复和 Codex Fast 档位路由。
-> 原始 MIT 开源项目为 [caozhiyuan/copilot-api](https://github.com/caozhiyuan/copilot-api)。
+> **XiaoDcs 双包名：** `xiaodcs-copilot-api-edge` 与
+> `xiaodcs-copilot-api` 目前都从同一份 Edge 源码构建，只有 npm 身份和命令名不同，
+> 实际运行的网关代码一致。原始 MIT 开源项目为
+> [caozhiyuan/copilot-api](https://github.com/caozhiyuan/copilot-api)。
 
 <p align="center">
-  <a href="https://www.npmjs.com/package/xiaodcs-copilot-api"><img src="https://img.shields.io/npm/v/xiaodcs-copilot-api.svg" alt="npm version"></a>
+  <a href="https://www.npmjs.com/package/xiaodcs-copilot-api-edge"><img src="https://img.shields.io/npm/v/xiaodcs-copilot-api-edge.svg" alt="npm version"></a>
+  <a href="https://www.npmjs.com/package/xiaodcs-copilot-api"><img src="https://img.shields.io/npm/v/xiaodcs-copilot-api.svg" alt="普通版 npm version"></a>
   <a href="https://github.com/caozhiyuan/copilot-api/blob/main/LICENSE"><img src="https://img.shields.io/badge/license-MIT-blue.svg" alt="License"></a>
   <a href="https://github.com/caozhiyuan/copilot-api/stargazers"><img src="https://img.shields.io/github/stars/caozhiyuan/copilot-api.svg" alt="GitHub stars"></a>
   <a href="https://bun.sh"><img src="https://img.shields.io/badge/Bun-%3E%3D1.2.x-orange.svg" alt="Bun >= 1.2.x"></a>
@@ -32,6 +34,12 @@
 
 最快启动一个可用网关的方式：
 
+```sh
+npx xiaodcs-copilot-api-edge@latest start
+```
+
+普通包名是内容相同的兼容发布通道：
+
 ```sh
 npx xiaodcs-copilot-api@latest start
 ```
@@ -39,7 +47,7 @@ npx xiaodcs-copilot-api@latest start
 服务默认监听 `http://localhost:4141`。也可以先登录 GitHub Copilot 或配置第三方 provider：
 
 ```sh
-npx xiaodcs-copilot-api@latest auth login
+npx xiaodcs-copilot-api-edge@latest auth login
 ```
 
 验证网关已启动：
@@ -51,19 +59,6 @@ curl http://localhost:4141/v1/models
 > [!NOTE]
 > token usage 存储需要 Node.js >= 22.13.0 或 Bun。详见[通过 npx 使用](#using-with-npx)。
 
-### 公共包流量策略
-
-公开的 `xiaodcs-copilot-api` 包会在任何模型上游请求开始前执行固定的进程内策略：
-
-- 最多同时运行 4 个上游模型请求；
-- 每秒最多启动 1 个请求，滚动一分钟内最多启动 20 个请求；
-- 准入前增加 300–900ms 抖动；
-- FIFO 队列最多等待 16 个请求，单个请求最多等待 45 秒；
-- 5% 的请求会在访问上游前被负载丢弃，并以带 `Retry-After` 的 HTTP `429` 返回；
-- 不注册图片生成和图片编辑端点。Chat Completions、Responses 和 Messages 中的图片输入仍会在模型支持视觉时正常工作。
-
-计数器只作用于单个运行中的进程。不同电脑或不同网关进程会各自计算限额。
-
 接下来可按你的客户端选择指南：[与 Claude Code 一起使用](#using-with-claude-code)、[与 OpenCode 一起使用](#using-with-opencode)、[与 Codex 一起使用](#using-with-codex)，或通过 [Docker](#using-with-docker) 运行。
 
 <a id="highlights"></a>
@@ -120,7 +115,7 @@ Windows x64（`.exe`）、macOS Apple Silicon（`.dmg`）和 Linux x64（`.AppIm
 执行带 `--claude-code` 的 `start` 命令开始：
 
 ```sh
-npx xiaodcs-copilot-api@latest start --claude-code
+npx xiaodcs-copilot-api-edge@latest start --claude-code
 ```
 
 你不再需要手动选择模型。Gateway 会自动检测每个 Claude Code 尺寸档位对应的最新可用模型——opus 映射到最新的 Opus 模型，sonnet 映射到最新的 Sonnet 模型，haiku 映射到最新的 Haiku 模型——并生成相应设置 `ANTHROPIC_DEFAULT_OPUS_MODEL`、`ANTHROPIC_DEFAULT_SONNET_MODEL` 和 `ANTHROPIC_DEFAULT_HAIKU_MODEL` 的命令。若某个档位没有匹配的可用模型，则会被省略。该命令会被复制到剪贴板，并设置 Claude Code 使用这个 AI gateway 所需的环境变量。
@@ -193,8 +188,8 @@ OpenCode 已经有直接的 GitHub Copilot provider。本节适用于你希望
 使用 OpenCode OAuth app 启动 AI gateway：
 
 ```sh
-npx xiaodcs-copilot-api@latest auth --oauth-app=opencode
-npx xiaodcs-copilot-api@latest start
+npx xiaodcs-copilot-api-edge@latest auth --oauth-app=opencode
+npx xiaodcs-copilot-api-edge@latest start
 ```
 
 然后让 OpenCode 通过 `@ai-sdk/anthropic` 指向这个 AI gateway。
@@ -354,6 +349,8 @@ args = [
 
 Codex 客户端（`User-Agent` 以 `codex` 开头）请求顶层 `GET /v1/models` 时，网关会把原生 Codex 模型与可通过 Messages 适配的模型合并返回。除 DeepSeek 模型外，后者会声明 `use_responses_lite: true`；DeepSeek 模型使用 `use_responses_lite: false` 和 `tool_mode: null`。调用 `/v1/responses` 后，Anthropic provider 走 **Responses → Messages**，OpenAI 兼容 provider 以及只支持 Chat 的 Copilot 模型则复用现有 Messages 路由继续走 **Responses → Messages → Chat Completions**，最终统一翻译回 Responses（包括流式事件）。
 
+> **注意：** DeepSeek 模型不使用 Responses Lite（`use_responses_lite: false`、`tool_mode: null`），因此向 Codex 暴露的工具集合与其他模型（`tool_mode: "code_mode_only"`）不一致。在会话中途切换 DeepSeek 模型与 Responses Lite 模型并不兼容——一套工具集合下产生的工具调用和会话历史无法直接沿用到另一套。切换模型时请新建 Codex 会话。
+
 合并后的模型列表会直接展示在 Codex 的模型选择界面中，包含各 provider 暴露的模型：
 
 <img src="./docs/screenshots/codex-models.png" alt="Codex 模型选择界面展示网关提供的模型列表" width="900" />
@@ -399,7 +396,7 @@ AI gateway 会从同一个本地端点暴露 OpenAI / Anthropic 兼容 API，让
 >
 > 3. **OpenCode 配置：** 与 OpenCode 搭配使用时，请使用 `@ai-sdk/anthropic` 配置 `~/.config/opencode/opencode.json`，详见 [与 OpenCode 一起使用](#与-opencode-一起使用)。
 >
-> 4. **内置 `copilot`、`codex` 与第三方 provider：** 执行 `npx xiaodcs-copilot-api@latest auth`，可选择 `copilot`、`codex`、`deepseek`、`custom` 等 provider。
+> 4. **内置 `copilot`、`codex` 与第三方 provider：** 执行 `npx xiaodcs-copilot-api-edge@latest auth`，可选择 `copilot`、`codex`、`deepseek`、`custom` 等 provider。
 >
 > 5. **注意事项：** README 顶部移除的 GitHub Copilot warning 见 [GitHub Copilot 安全提示](./NOTICE.md#github-copilot-security-notice)。
 
@@ -451,29 +448,29 @@ bun run start start
 > [!IMPORTANT]
 > 通过 `npx` 运行时，token usage 存储会使用 Node 内置的 `node:sqlite` 模块。该能力会在 Node.js >= 22.13.0 时启用；Node.js < 22.13.0 时 CLI 仍可启动，但会禁用 token usage 存储。
 >
-> 如果不升级 Node.js 但仍需要 token usage 存储，可以改用 Bun 运行已发布 CLI：`bunx --bun xiaodcs-copilot-api@latest start`。
+> 如果不升级 Node.js 但仍需要 token usage 存储，可以改用 Bun 运行已发布 CLI：`bunx --bun xiaodcs-copilot-api-edge@latest start`。
 
 ```sh
-npx xiaodcs-copilot-api@latest start
+npx xiaodcs-copilot-api-edge@latest start
 ```
 
 带参数示例：
 
 ```sh
-npx xiaodcs-copilot-api@latest start --port 8080
+npx xiaodcs-copilot-api-edge@latest start --port 8080
 ```
 
 如果只想做认证或 provider 配置：
 
 ```sh
-npx xiaodcs-copilot-api@latest auth
+npx xiaodcs-copilot-api-edge@latest auth
 ```
 
 如果要不依赖 GitHub Copilot 运行，先配置至少一个 provider，然后正常启动服务：
 
 ```sh
-npx xiaodcs-copilot-api@latest auth login --provider dashscope
-npx xiaodcs-copilot-api@latest start
+npx xiaodcs-copilot-api-edge@latest auth login --provider dashscope
+npx xiaodcs-copilot-api-edge@latest start
 ```
 
 <a id="using-with-docker"></a>
@@ -540,7 +537,7 @@ GPT 模型不要设置 Claude Code 原生的 `ENABLE_TOOL_SEARCH`。这个开关
     "tool_search": {
       "type": "stdio",
       "command": "npx",
-      "args": ["-y", "xiaodcs-copilot-api@latest", "mcp"]
+      "args": ["-y", "xiaodcs-copilot-api-edge@latest", "mcp"]
     }
   }
 }
@@ -553,7 +550,7 @@ GPT 模型不要设置 Claude Code 原生的 `ENABLE_TOOL_SEARCH`。这个开关
   "mcp": {
     "tool_search": {
       "type": "local",
-      "command": ["npx", "-y", "xiaodcs-copilot-api@latest", "mcp"]
+      "command": ["npx", "-y", "xiaodcs-copilot-api-edge@latest", "mcp"]
     }
   }
 }
@@ -637,7 +634,7 @@ cp plugin/opencode/subagent-marker.js ~/.config/opencode/plugins/
 
 1. 启动服务。例如使用 npx：
    ```sh
-   npx xiaodcs-copilot-api@latest start
+   npx xiaodcs-copilot-api-edge@latest start
    ```
 2. 服务会输出一个 usage viewer 的 URL。将它复制到浏览器中打开，形式大致如下：
    `http://localhost:4141/usage-viewer?endpoint=http://localhost:4141/usage`
@@ -649,16 +646,16 @@ cp plugin/opencode/subagent-marker.js ~/.config/opencode/plugins/
 
 - **API Endpoint URL**：通过 URL 查询参数指定 API endpoints，默认指向本地服务。支持手动切换为其他兼容 endpoints。
 - **API Key 认证**：如果启用了 API Key 认证，可填入原始 API key（默认通过 `x-api-key` 请求头发送）或 `Authorization: Bearer <key>`。凭据会按 endpoint origin 保存在浏览器本地存储中；切换到不同 endpoint origin 时，不会自动携带其他 origin 的凭据。
-- **Period 选择器**：支持 Day / Week / Month 三种时间范围，切换时 URL 参数会自动同步，方便收藏和分享。
+- **Period 选择器**：支持六种时间范围：`today`（当前本地日历日至今）、`this_week`（本周一 00:00 至现在）、`last_7_days`（滚动 7 个日历日至现在）、`this_month`（本月 1 日 00:00 至现在）、`last_30_days`（滚动 30 个日历日至现在）和 `lifetime`（从最早记录事件至现在）。默认选择 Today，选择器旁会显示具体日期范围；切换时 URL 参数会自动同步，方便收藏和分享。旧版取值 `day`、`week`、`month` 仍被兼容，会自动映射到对应的新值。
 - **Fetch Data**：点击 "Refresh" 按钮加载或刷新使用数据。页面加载时也会自动拉取数据。
 - **Copilot Quotas 额度**：通过进度条展示 Chat、Completions 等不同服务的额度使用情况，悬停可查看已用/剩余详情。
 - **Token Usage 指标卡片**：汇总当前周期的 Total、Input、Output、Cache Read、Cache Write、Requests 和预估费用。
-- **趋势图（Week / Month）**：提供按模型和指标筛选的折线趋势图，点击数据点可查看单日用量明细。
+- **趋势图**：提供按所选周期、模型和指标筛选的折线趋势图，点击数据点可查看用量明细；Lifetime 图表数据从每日数据桶中采样，最多显示 180 个点，以便查看长期趋势。
 - **Model Breakdown 表格**：按模型维度列出周期内的请求数、输入/输出/缓存 token 和预计费用。
 - **Request Events 分页列表**：按时间排序的请求事件记录，支持分页浏览，含时间戳、模型、请求 ID 和 token 用量。
 - **Detailed Information**：展示 API 返回的完整 JSON 响应，便于深入分析所有可用统计数据。
 - **URL-based Configuration**：也可通过 `endpoint` 和 `period` 查询参数直接指定 API 端点与时间范围。例如：
-  `http://localhost:4141/usage-viewer?endpoint=http://your-api-server/usage&period=week`
+  `http://localhost:4141/usage-viewer?endpoint=http://your-api-server/usage&period=this_week`
 
 ### Usage Viewer 截图
 
@@ -757,6 +754,7 @@ Copilot API 现在使用子命令结构，主要命令包括：
     "useMessagesApi": true,
     "useResponsesApiCompactionRecovery": false,
     "useResponsesApiWebSocket": true,
+    "useCopilotFastTier": true,
     "responsesTransport": {
       "headersTimeoutMsV2": 300000,
       "streamInactivityTimeoutMs": 300000,
@@ -778,8 +776,8 @@ Copilot API 现在使用子命令结构，主要命令包括：
 - **providers：** 全局上游 provider 映射。每个 provider key（例如 `dashscope`）都会变成一个路由前缀（`/dashscope/v1/messages`）。支持 `type: "anthropic"`、`type: "openai-compatible"` 和 `type: "openai-responses"`。顶层客户端也可以在 `/v1/messages`、`/v1/messages/count_tokens`、`/v1/responses` 和 `/v1/chat/completions` 中使用 `model: "dashscope/model-id"`；AI gateway 会在转发上游前移除 `dashscope/` 前缀。`anthropic` 和 `openai-compatible` provider 的 `/v1/responses` 会通过 Responses Lite → Messages 适配；其中 `openai-compatible` provider 再复用 Messages → Chat 翻译。Codex 客户端（`User-Agent` 以 `codex` 开头）在 `openai-responses` provider 上请求非 `gpt-*` 模型时同样走该适配路径。`GET /v1/models` 会聚合已启用 provider 的模型，并以 `provider/model-id` 形式返回；Codex UA 的顶层模型列表还会把这些可适配模型合并为 `use_responses_lite` 模型（DeepSeek 模型除外，它们使用 `use_responses_lite: false` 和 `tool_mode: null`）。单个 provider 的原始模型列表仍可使用 `GET /dashscope/v1/models`。
   - `enabled`：可选，若省略则默认为 `true`。
   - `baseUrl`：provider API 的基础 URL，不要带结尾的 endpoint。Anthropic provider 不要带 `/v1/messages`；OpenAI 兼容 provider 不要带 `/v1/chat/completions`；OpenAI Responses provider 不要带 `/v1/responses`。
-  - `apiKey`：作为上游凭据值使用；普通 provider 必须配置。
-  - `authType`：可选，控制 `apiKey` 如何发送到上游。普通 provider 支持 `x-api-key` 和 `authorization`。Anthropic provider 默认 `x-api-key`；OpenAI 兼容和 OpenAI Responses provider 默认 `authorization`。当设置为 `authorization` 时，代理会发送 `Authorization: Bearer <apiKey>`。`oauth2` 仅保留给内置 `codex` provider，并由 `auth login --provider codex` 自动写入。
+  - `apiKey`：作为上游凭据值使用；除 `authType` 为 `azure-entra` 外，普通 provider 必须配置。
+  - `authType`：可选，控制上游认证方式。普通 provider 支持 `x-api-key`、`authorization` 和 `azure-entra`。Anthropic provider 默认 `x-api-key`；OpenAI 兼容和 OpenAI Responses provider 默认 `authorization`。`authorization` 会发送 `Authorization: Bearer <apiKey>`。`azure-entra` 使用 Azure Identity 的 `DefaultAzureCredential` 和 `https://cognitiveservices.azure.com/.default` scope 获取并发送 Bearer token，不需要配置 `apiKey`。Azure OpenAI v1 endpoint 可配置为 `{ "type": "openai-compatible", "baseUrl": "https://<resource-name>.openai.azure.com/openai", "authType": "azure-entra" }`。本地可先执行 `az login`，在 Azure 中可使用托管身份，也可设置标准的 `AZURE_TENANT_ID`、`AZURE_CLIENT_ID` 和 `AZURE_CLIENT_SECRET` 环境变量。`oauth2` 仅保留给内置 `codex` provider，并由 `auth login --provider codex` 自动写入。
   - `pricingCurrency`：可选，provider 维度的 token 费用币种，例如 `USD` 或 `CNY`。快捷 provider 默认 DashScope、DeepSeek 为 `CNY`，Codex、Kimi、OpenCode Go、OpenRouter 为 `USD`。费用按币种分别汇总，不做汇率换算。
   - `models`：可选，按模型 ID 配置的映射。每个键为请求中的模型名，值支持：
     - `temperature`：可选，当请求未指定时使用的默认温度。
@@ -790,12 +788,13 @@ Copilot API 现在使用子命令结构，主要命令包括：
     - `contextCache`：可选，provider name 为 `dashscope` 或 `baseUrl` 包含 `aliyuncs.com` 时默认 `true`，其他 OpenAI 兼容 provider 默认 `false`。用于启用阿里云百炼/DashScope 的显式缓存（explicit context cache），会按其 Context Cache 格式在最多 4 个 content block 上注入 `cache_control: { "type": "ephemeral" }`。缓存断点策略与 opencode 主链路保持一致：前 2 条 system 消息 + 最后 2 条非 system 消息。标记字符串 content 时会把 `system` / `user` / `assistant` / `tool` 消息转换为 text content part 数组；已有数组 content 则标记最后一个 part。如果模型本身已经支持隐式缓存，或上游不支持该显式缓存扩展字段，可在模型配置中设为 `false`。支持相同显式缓存扩展的非 DashScope provider 可设为 `true`。同时适用于 `/v1/messages` 和 `/v1/chat/completions` 路由。
     - `supportPdf`：可选，控制该模型是否支持 PDF/document content。默认 `false`，不支持时会把 PDF 转成提示文本；设为 `true` 时会把 PDF/document 转成 OpenAI Chat Completions 的 file part。
     - `toolContentSupportType`：可选，配置该模型的 tool result content 支持能力，值为 `array`、`image`、`pdf` 的数组。provider 侧未配置时默认只发送 string tool content。若 `supportPdf` 为 `true` 但这里不包含 `pdf`，tool result 里的 file part 会被转成 user role 消息。Copilot 主链路同样默认只发送 string tool content，因为部分 Copilot 模型也不支持数组或图片形式的 tool content。
-    - `type`：可选，按模型覆盖 provider 的协议类型。支持 `anthropic`、`openai-compatible` 和 `openai-responses`。设置后，provider 的 `/v1/messages` 路由会使用该模型的 type 替代 provider 级别的 type 进行请求路由、认证头解析和上游端点选择。适用于 OpenCode Go 等上游对不同模型同时支持 OpenAI 兼容和 Anthropic Messages API 的 provider。覆盖 type 时，认证头按覆盖后 type 的默认值解析（Anthropic 默认 `x-api-key`；OpenAI 兼容/Responses 默认 `authorization`）。
+    - `type`：可选，按模型覆盖 provider 的协议类型。支持 `anthropic`、`openai-compatible` 和 `openai-responses`。设置后，provider 的 `/v1/messages` 路由会使用该模型的 type 替代 provider 级别的 type 进行请求路由、认证头解析和上游端点选择。适用于 OpenCode Go 等上游对不同模型同时支持 OpenAI 兼容和 Anthropic Messages API 的 provider。覆盖 type 时，认证头按覆盖后 type 的默认值解析（Anthropic 默认 `x-api-key`；OpenAI 兼容/Responses 默认 `authorization`）。配置了 `azure-entra` 的 provider 在覆盖 type 时会保留 Entra bearer 凭证，而不会回退到覆盖后 type 的默认值。
     - `contextWindow`：可选，模型合并到 Codex UA 模型列表时声明的上下文窗口 token 上限；例如 `1000000` 表示 1M token 上下文。用户未配置时依次使用上游元数据、非 GPT 模型的内置目录和 `256000`。
     - `maxOutputTokens`：可选，Codex UA 模型列表中声明的最大输出 token 数。用户未配置时优先使用上游元数据，其次使用非 GPT 模型的内置目录（内置默认值最高为 `64000`），最后默认为 `32000`。
     - `inputModalities`：可选，Codex 支持的输入类型；模型同时支持文本和图片时配置为 `["text", "image"]`。用户未配置时优先使用上游元数据，再使用非 GPT 模型的内置目录。GPT 模型不注入这些内置能力默认值，继续使用原生 Codex catalog 或上游元数据。
     - `reasoningEfforts`：可选，Codex 支持的推理档位。配置和上游元数据均未提供时，会先使用非 GPT 模型的内置目录，再回退到 `["high", "xhigh", "max", "ultra"]`。已知模型能力时，Provider Responses 请求中的不支持档位会被归一化为支持的档位。
     - `defaultReasoningEffort`：可选，Codex 默认推理档位；内置模型元数据可以提供已知默认值，否则可用档位包含 `max` 时默认取 `max`，再回退到配置的第一个档位。合成 Codex 模型始终启用并行工具调用。
+    - `reasoningField`：可选，OpenAI-compatible `/v1/messages` 转发 assistant 思考文本时使用的字段，支持 `reasoning` 与 `reasoning_content`，默认 `reasoning_content`；OpenRouter 风格模型设为 `reasoning`，内置目录已为 OpenCode Go `hy3`、`hy4-preview` 配置该值。
 - **smallModel：** 无工具预热消息的回退模型（例如 Claude Code 的探测请求）；默认是 `gpt-5-mini`。网关会对无工具的预热或探测请求强制使用该小模型，以避免消耗 premium 请求。该行为仅在 GitHub Copilot 账户为非 token-based 计费时生效（`token_based_billing` 为 false）；对于 token-based 计费账户，预热小模型回退会被跳过，因为不存在需要节省的 premium 请求配额。
 - **contextManagement：** 控制代理是否为 Responses API 附加 `context_management` 压缩指令。`messages` 作用于被翻译成 Responses API 的 Anthropic 风格 `/v1/messages` 请求，包括 `openai-responses` provider 的 Messages 路由，默认值为 `true`。`responses` 作用于 native `/v1/responses` 流量，包括 `provider/model` 别名和内置 `codex` provider，默认值为 `false`。只有在确认客户端支持 context management compaction 后，才建议在 Responses API 下启用 `responses`。启用后，请求体会带上 `context_management`，并在后续轮次中仅保留最新的压缩承载内容。代理仅为 `gpt-*` 模型添加 context management 并压缩历史；这两个配置开关对 Grok 等非 GPT 模型不生效。**注意：** 对于 GPT-5.6 及以上模型（如 `gpt-5.6-sol`、`gpt-5.6-terra`、`gpt-5.6-luna`），context management 功能同样会被强制禁用，因为开启后会破坏这些模型的 prompt 缓存命中。这些强制覆盖优先于 `contextManagement` 和 `modelResponsesApiCompactThresholds` 配置。
  - **modelResponsesApiCompactThresholds：** 按模型覆盖 Responses API 的 `compact_threshold`，仅在代理自动附加 `context_management` 时使用。它的优先级高于 `resolveResponsesCompactThreshold` 基于 `max_prompt_tokens * ratio` 的兜底阈值。默认将 `gpt-5.4` 和 `gpt-5.5` 设为 `217600`（`272000 * 0.8`）。未列出的模型继续使用原有兜底逻辑。
@@ -806,6 +805,7 @@ Copilot API 现在使用子命令结构，主要命令包括：
 - **useMessagesApi：** 当为 `true` 时，声明了 Copilot 原生 `/v1/messages` 端点的模型会使用 Messages API。如果所选模型未声明 Messages 端点或关闭了该配置，网关会在模型声明了 Responses 端点时使用 Responses，否则在模型支持时回退到 Chat Completions。设为 `false` 可跳过原生 Messages 路由。默认值为 `true`。
 - **useResponsesApiCompactionRecovery（实验性）：** 设为 `true` 后，成功的远程 Responses 压缩会异步生成低推理强度的影子摘要，并仅以 opaque compaction 哈希为键保存摘要。当 Copilot 后续拒绝该压缩内容或连接绑定历史时，HTTP 请求会逐步使用缓存摘要与可见消息重建请求。默认关闭，因为影子摘要会增加一次后台模型请求，且恢复过程存在信息损失。WebSocket 错误会在客户端下一次重试时恢复；同一次请求内的自动恢复仅支持 HTTP。
 - **useResponsesApiWebSocket：** 当为 `true` 时，Copilot Responses 请求会对声明了 `ws:/responses` 的模型使用 WebSocket；仅声明 `/responses` 的模型使用 HTTP。内置 `codex` provider 的流式 Responses 请求只要启用了该配置就会使用 WebSocket，非流式 Codex 请求始终使用 HTTP。设为 `false` 后，Copilot 会在所选模型声明了 `/responses` 时使用 HTTP，Codex 的流式 Responses 请求也会改走 HTTP。WebSocket 失败后不会自动通过 HTTP 重试。默认值为 `true`。如果代理、VPN 或网络会阻断或干扰 WebSocket 流量，请关闭该配置或切换网络。
+- **useCopilotFastTier：** 控制客户端请求中的 `service_tier: "fast"` 或 `"priority"` 是否可以路由到配对的 Copilot `*-fast` 模型，默认值为 `true`。设为 `false` 后，即使 Codex 任务保留了界面中不明显的 Fast 速度档位，也会强制使用标准模型。开启时，若 Fast 上游明确返回 429，会自动回退一次到配对标准模型，并按 `Retry-After` 暂停 Fast 路由（默认 30 秒，最长 5 分钟）。
 - **responsesTransport：** 所有上游 Responses transport 共用的生命周期与缓冲区正整数限制。无效值、零或负数会回退到上面列出的默认值。`headersTimeoutMsV2` 从连接建立开始计算，到收到 HTTP 响应头为止，并不是整个生成过程的总时限。每收到一个 HTTP body chunk 或 WebSocket message 都会重置 `streamInactivityTimeoutMs`，因此持续活跃的长推理任务不会被短总时限中断。`websocketOpenTimeoutMs` 限制 WebSocket 握手时间；`websocketPoolIdleTimeoutMs` 只控制已正常完成且可复用的空闲连接。WebSocket 队列同时受字节数和消息数上限约束；超过任一上限时会终止该 stream 并使 socket 失效，而不会丢弃或重排事件。
 - **useResponsesApiWebSearch：** 当为 `true` 时，服务端会保留 Responses API 中 `type: "web_search"` 的工具并透传到上游。设为 `false` 则会从 `/responses` payload 中移除这些工具。默认值为 `true`。
 - **alphaSearchCodexPriority：** 默认值为 `true`。顶层 alpha-search 请求优先使用 Codex alpha-search 端点，因为它不会消耗 provider 配额。若 Codex 不可用，或该配置设为 `false`，使用非 `codex/model` 的 `provider/model` 别名的请求会调用目标 provider 的 `/v1/responses` 端点，没有 provider 前缀的请求使用 GitHub Copilot Responses web search。该适配器会识别当前所有 Codex search command；不受支持的 `image_query` 和 `screenshot` 会返回成功且明确要求不要重试的 tool output。
@@ -862,11 +862,13 @@ curl http://localhost:4141/admin/config/model-mappings \
 
 ### Codex 后端端点
 
-这些端点实现公共包支持的 Codex 后端 API。alpha-search 可以使用 Codex 后端或 Responses web-search 适配器；公共包不提供图片生成和图片编辑。
+这些端点实现 Codex 后端 API。顶层图片请求要求已有可用的 Codex 登录态；alpha-search 则可以使用 Codex 后端或 Responses web-search 适配器。
 
 | 端点                                                       | 方法 | 说明                                                                                                 |
 | ---------------------------------------------------------- | ---- | ---------------------------------------------------------------------------------------------------- |
 | `POST /v1/alpha/search`            | `POST` | 将 Codex alpha-search 请求路由到 Codex 后端，或在本地及通过 Responses web search 处理支持的命令。 |
+| `POST /v1/images/generations` | `POST` | 将 JSON 图片生成请求转发到 Codex Images 上游。请求未携带 `Content-Type` 时，网关默认补充 `application/json`。请求 `model` 命中已配置的 model mapping 时会被改写；映射结果为已配置 provider 的 `provider/model` 别名时，请求将转发到该 provider 的 images 端点。 |
+| `POST /v1/images/edits` | `POST` | 将图片编辑请求转发到 Codex Images 上游。请使用 `multipart/form-data`，并让 HTTP 客户端自动生成 `boundary`；网关会保留传入的 content type，并在转发前最多缓冲 64 MiB，超限请求返回 `413`。model mapping 与 `provider/model` 别名路由同样适用于此端点。 |
 
 对于路由到 Codex 后端的请求，网关会使用当前 Codex 登录态覆盖客户端的 authorization 和 account header，并保留兼容的请求元数据。基于 Responses 的 alpha-search 则遵循所选 Copilot 或 provider 的路由。
 
@@ -904,23 +906,23 @@ curl http://localhost:4141/admin/config/model-mappings \
 
 ```sh
 # 基础启动
-npx xiaodcs-copilot-api@latest start
+npx xiaodcs-copilot-api-edge@latest start
 
 # 自定义端口并开启详细日志
-npx xiaodcs-copilot-api@latest start --port 8080 --verbose
+npx xiaodcs-copilot-api-edge@latest start --port 8080 --verbose
 
 # 执行认证流程
-npx xiaodcs-copilot-api@latest auth login
+npx xiaodcs-copilot-api-edge@latest auth login
 
 # 配置第三方 provider，然后不依赖 GitHub Copilot 启动
-npx xiaodcs-copilot-api@latest auth login --provider dashscope
-npx xiaodcs-copilot-api@latest start
+npx xiaodcs-copilot-api-edge@latest auth login --provider dashscope
+npx xiaodcs-copilot-api-edge@latest start
 
 # 以 JSON 格式输出调试信息
-npx xiaodcs-copilot-api@latest debug --json
+npx xiaodcs-copilot-api-edge@latest debug --json
 
 # 用 Bun 而不是 Node.js 运行已发布 CLI
-bunx --bun xiaodcs-copilot-api@latest start
+bunx --bun xiaodcs-copilot-api-edge@latest start
 ```
 
 配置 `dashscope` 后的 OpenAI 兼容 provider 调用示例：