Skip to content

7.4 billion tokens per month. 34 free LLM providers. 635 free model endpoints. All behind one /v1 endpoint, plus any custom OpenAI-compatible endpoint. Smart routing, automatic failover, encrypted keys. Personal experimentation only.

TypeScript

docs(zh-cn): finish the per-language tree — translate the four stubs, fix the index, anchors and switchers (#1167)

Tashfeenef1b9ce3b514
diff --git a/README.md b/README.md
index 8ab75c75..1d75a8b1 100644
--- a/README.md
+++ b/README.md
@@ -157,7 +157,7 @@ Based on public documentation, July 2026 — corrections welcome.
- **Fusion (multi-model synthesis)** — request the virtual `fusion` model and the router fans your prompt out to a panel of diverse free models in parallel, then a judge model synthesizes one answer from the drafts. [Details →](docs/en/api/01-rest-api.md#fusion-multi-model-synthesis)
- **Image, video & speech generation** — `/v1/images/generations`, `/v1/videos/generations`, and `/v1/audio/speech` route across the providers that serve media models; images and speech also accept custom OpenAI-compatible media endpoints. Video jobs are normalized across synchronous and queued providers and return a completed MP4.
- **Tool calling & structured outputs** — OpenAI-style `tools` round-trip across providers (plain-text tool calls are rescued into real `tool_calls`), plus `response_format`, `seed`, `logprobs`, penalties, and the rest of the sampling params passed through per provider.
-- **Smart routing, six strategies** — live per-model speed/capability/reliability scores rank your chain; automatic fallover retries the next model on 429/5xx with cooldowns and key rotation. [Routing in detail →](docs/en/architecture/00-high-level-index.md#routing-in-detail)
+- **Smart routing, six strategies** — live per-model speed/capability/reliability scores rank your chain; automatic fallover retries the next model on 429/5xx with cooldowns and key rotation. [Routing in detail →](docs/en/architecture/00-high-level-index.md#how-it-works)
- **Unified models & profiles** — the same model on several providers collapses into one entry with strict in-group failover; named fallback-chain profiles (a coding chain, a vision chain) switch from the dashboard or per request via `auto:<profile>`.
- **Per-key rate tracking** — RPM/RPD/TPM/TPD counters per `(platform, model, key)` that learn providers' reported ceilings, so routing always stays under every cap.
- **Self-updating model catalog** — the router syncs a signed catalog from freellmapi.co twice a day: new models, quota changes, and provider quirk fixes land automatically. Free installs track the monthly snapshot, which each model joins 30 days after it lands in the live feed; premium routers get it same-day. [Premium →](#premium-live-catalog)
diff --git a/README.zh-cn.md b/README.zh-cn.md
index 66f2ec60..7db5984f 100644
--- a/README.zh-cn.md
+++ b/README.zh-cn.md
@@ -48,9 +48,9 @@
- [参与贡献](#参与贡献)
- [免责声明](#免责声明)
-**指南:** [安装与部署](docs/en/install/01-install.md) · [API 参考](docs/en/api/01-rest-api.md) · [客户端与编程智能体](docs/en/clients/01-agent-clients.md) · [提示词压缩](docs/en/compression/01-compression-pipeline.md) · [架构与内部实现](docs/en/architecture/00-high-level-index.md) · [文档索引](docs/en/README.md) · [贡献者指南](CONTRIBUTING.md)
+**指南:** [安装与部署](docs/zh-cn/install/01-install.md) · [API 参考](docs/zh-cn/api/01-rest-api.md) · [客户端与编程智能体](docs/zh-cn/clients/01-agent-clients.md) · [提示词压缩](docs/zh-cn/compression/01-compression-pipeline.md) · [架构与内部实现](docs/zh-cn/architecture/00-high-level-index.md) · [文档索引](docs/zh-cn/README.md) · [贡献者指南](CONTRIBUTING.md)
-> 「安装与部署」和「API 参考」已有中文版。「客户端与编程智能体」「提示词压缩」「架构与内部实现」目前只有英文版,上面的链接直接指向英文原文。完整的翻译状态见 [这里](README.md#status)。
+> 所有指南都已有中文版,上面的链接指向中文页面;少数页面在英文原文更新后尚未同步,以英文版为准,每页页首都可切换到英文原文。完整的翻译状态见 [这里](docs/zh-cn/OVERVIEW.md#翻译状态)。
## 为什么会有这个项目
@@ -131,7 +131,7 @@
其中大多数一条命令就能配好:`npx freellmapi setup-claude`、`setup-codex`、`setup-aider`,还有另外十几个生成器。它们会拉取你当前的实时目录,备份已有配置,并且绝不覆盖你已经写好的内容。Claude Code 和 Codex 另有零留存启动器(`freellmapi launch`、`freellmapi launch-codex`),只把凭据注入子进程。Zed 和 JetBrains AI 通过可选的 [Ollama 模拟](docs/en/clients/01-agent-clients.md#ollama-clients) 接入;Gemini CLI 走它自己的 `/v1beta` 协议。
-各工具的具体配方、setup CLI 参考、给无法发送请求头的客户端用的可撤销 URL 令牌,以及 MCP 服务,都在 **[客户端与编程智能体 →](docs/en/clients/01-agent-clients.md)**
+各工具的具体配方、setup CLI 参考、给无法发送请求头的客户端用的可撤销 URL 令牌,以及 MCP 服务,都在 **[客户端与编程智能体 →](docs/zh-cn/clients/01-agent-clients.md)**
## 横向对比
@@ -143,25 +143,25 @@
![功能概览](repo-assets/features.png)
-- **OpenAI 的全部接口** —— `/v1/chat/completions`、`/v1/responses`(Codex CLI 需要它)、`/v1/completions`(编辑器的幽灵文本补全)、`/v1/images/generations`、`/v1/audio/speech`、`/v1/embeddings` 和 `/v1/models`,流式与非流式均可,来自官方 SDK 或任何 OpenAI 兼容客户端都行。[API 参考 →](docs/en/api/01-rest-api.md)
-- **Anthropic Messages API** —— `/v1/messages` 在同一套路由之上讲 Anthropic 的协议,所以 **Claude Code** 和官方 Anthropic SDK 可以直接跑在你的免费池上。[详情 →](docs/en/api/01-rest-api.md#anthropic-与-claude-客户端)
+- **OpenAI 的全部接口** —— `/v1/chat/completions`、`/v1/responses`(Codex CLI 需要它)、`/v1/completions`(编辑器的幽灵文本补全)、`/v1/images/generations`、`/v1/audio/speech`、`/v1/embeddings` 和 `/v1/models`,流式与非流式均可,来自官方 SDK 或任何 OpenAI 兼容客户端都行。[API 参考 →](docs/zh-cn/api/01-rest-api.md)
+- **Anthropic Messages API** —— `/v1/messages` 在同一套路由之上讲 Anthropic 的协议,所以 **Claude Code** 和官方 Anthropic SDK 可以直接跑在你的免费池上。[详情 →](docs/zh-cn/api/01-rest-api.md#anthropic-与-claude-客户端)
- **原生 Gemini 与 Ollama 接口** —— Gemini CLI 可以用 `/v1beta`(`generateContent`、流式、词元计数、模型列表);可选的 Ollama 模拟则为 Zed、JetBrains 以及其他本地模型客户端提供 NDJSON 的 chat/generate、标签、元数据和嵌入。
-- **Fusion(多模型合成)** —— 请求虚拟模型 `fusion`,路由器会把你的提示词并行分发给一组风格各异的免费模型,再由一个评审模型从这些草稿中合成出一个答案。[详情 →](docs/en/api/01-rest-api.md#fusion-多模型合成)
+- **Fusion(多模型合成)** —— 请求虚拟模型 `fusion`,路由器会把你的提示词并行分发给一组风格各异的免费模型,再由一个评审模型从这些草稿中合成出一个答案。[详情 →](docs/zh-cn/api/01-rest-api.md#fusion-多模型合成)
- **图像生成与文本转语音** —— `/v1/images/generations` 和 `/v1/audio/speech` 会在提供媒体模型的提供方之间路由,也包括自定义的 OpenAI 兼容媒体端点。
- **工具调用与结构化输出** —— OpenAI 风格的 `tools` 可在各提供方之间往返(纯文本形式的工具调用会被救回成真正的 `tool_calls`),另有 `response_format`、`seed`、`logprobs`、惩罚项以及其余采样参数按提供方透传。
-- **智能路由,六种策略** —— 实时的每模型速度、能力、稳定性评分决定你的链路顺序;遇到 429/5xx 时自动转移到下一个模型,并带冷却和密钥轮换。[路由详解 →](docs/en/architecture/00-high-level-index.md#routing-in-detail)
+- **智能路由,六种策略** —— 实时的每模型速度、能力、稳定性评分决定你的链路顺序;遇到 429/5xx 时自动转移到下一个模型,并带冷却和密钥轮换。[路由详解 →](docs/zh-cn/architecture/00-high-level-index.md#工作原理)
- **统一模型与配置档** —— 同一个模型在多家提供方上会合并成一个条目,并在组内严格故障转移;命名的回退链配置档(比如一条编程链、一条视觉链)可以在仪表盘里切换,也可以按请求用 `auto:<profile>` 指定。
- **按密钥的限流跟踪** —— 以 `(平台, 模型, 密钥)` 为单位的 RPM/RPD/TPM/TPD 计数器,会学习提供方公布的上限,让路由始终不越线。
- **自更新的模型目录** —— 路由器每天两次从 freellmapi.co 同步经过签名的目录:新模型、额度变更和提供方的怪癖修复都会自动生效。[Premium →](#premium-实时目录)
- **粘性会话与上下文交接** —— 对话会在同一个模型上停留 30 分钟;如果中途确实换了模型,可选的精简交接说明能让话题保持连贯。[详情 →](docs/en/clients/01-agent-clients.md#context-handoff)
-- **提示词压缩(可选开启)** —— 一条共享且失败即放行的请求流程,可以在缓存查找和路由之前对提示词去重、过滤工具输出、压紧重复的 JSON,并裁掉过时的上下文。[详情 →](docs/en/compression/01-compression-pipeline.md)
+- **提示词压缩(可选开启)** —— 一条共享且失败即放行的请求流程,可以在缓存查找和路由之前对提示词去重、过滤工具输出、压紧重复的 JSON,并裁掉过时的上下文。[详情 →](docs/zh-cn/compression/01-compression-pipeline.md)
- **密钥加密存储,对外只有一个令牌** —— 提供方密钥以 AES-256-GCM 加密存放在 SQLite 中,每次请求时在内存里解密;你的应用自始至终只看到一个统一的 `freellmapi-…` bearer 令牌。
- **管理仪表盘与分析** —— React 界面用来管理密钥、调整链路顺序、使用试验台,并查看 24 小时到 90 天窗口的 p50/p95/首个词元用时分析;带登录保护,支持明暗主题和 [60 种语言](#语言)。
-- **MCP 服务与交互式文档** —— 智能体可以通过 `/mcp` 查询可用模型、提供方健康状况和路由策略;`/v1/docs` 提供一个零依赖的 OpenAPI 浏览器。[编程智能体 →](docs/en/clients/01-agent-clients.md)
-- **运维上的便利** —— 可选的响应缓存、加密的数据库备份、定期密钥健康检查、密钥批量导入导出、声明式启动配置。[安装与部署 →](docs/en/install/01-install.md)
+- **MCP 服务与交互式文档** —— 智能体可以通过 `/mcp` 查询可用模型、提供方健康状况和路由策略;`/v1/docs` 提供一个零依赖的 OpenAPI 浏览器。[编程智能体 →](docs/zh-cn/clients/01-agent-clients.md)
+- **运维上的便利** —— 可选的响应缓存、加密的数据库备份、定期密钥健康检查、密钥批量导入导出、声明式启动配置。[安装与部署 →](docs/zh-cn/install/01-install.md)
- **能跑 Node 20+ 的地方都能跑** —— Windows、macOS、Linux 服务器,或者一块小小的 ARM 单板机(树莓派也行)。在 PM2 / systemd 或你惯用的守护进程下,空闲时常驻内存约 40 MB。
-项目范围是刻意收窄的,参见 [尚不支持的部分](docs/en/architecture/00-high-level-index.md#not-yet-supported)。
+项目范围是刻意收窄的,参见 [尚不支持的部分](docs/zh-cn/architecture/00-high-level-index.md#尚不支持)。
## 快速开始
@@ -175,9 +175,9 @@ curl -fsSL https://freellmapi.co/install.sh | bash
打开 http://localhost:3001 ,在 **密钥** 页添加你的提供方密钥,按喜好调整 **回退链** 的顺序,然后在 **密钥** 页顶部拿到你的统一 API 密钥。这个统一密钥就是你的 OpenAI SDK 要指向的东西。
-在 Windows 上,最省事的方式是下面提到的桌面版 **[Releases 里的 `.exe` 安装包](https://github.com/tashfeenahmed/freellmapi/releases/latest)**。Android 上可参考实验性的 [Termux 指南](docs/en/install/02-android-termux.md)。
+在 Windows 上,最省事的方式是下面提到的桌面版 **[Releases 里的 `.exe` 安装包](https://github.com/tashfeenahmed/freellmapi/releases/latest)**。Android 上可参考实验性的 [Termux 指南](docs/zh-cn/install/02-android-termux.md)。
-其余内容,包括 Docker Compose、本地开发、声明式启动配置、生产构建、局域网访问和备份,都在 **[docs/install.md](docs/en/install/01-install.md)**。
+其余内容,包括 Docker Compose、本地开发、声明式启动配置、生产构建、局域网访问和备份,都在 **[docs/install.md](docs/zh-cn/install/01-install.md)**。
## 桌面应用
@@ -185,11 +185,11 @@ curl -fsSL https://freellmapi.co/install.sh | bash
![FreeLLMAPI 桌面应用](repo-assets/desktop.png)
-**[从 Releases 下载](https://github.com/tashfeenahmed/freellmapi/releases/latest)** —— 每个版本都附带 macOS 的 `.dmg` 和 Windows 的 `.exe` 安装包。不需要注册账号或设置密码:你唯一需要的凭据就是托盘悬浮窗里的统一 API 密钥。从源码构建的步骤,以及数据存放位置,见 [docs/install.md](docs/en/install/01-install.md#桌面应用)。
+**[从 Releases 下载](https://github.com/tashfeenahmed/freellmapi/releases/latest)** —— 每个版本都附带 macOS 的 `.dmg` 和 Windows 的 `.exe` 安装包。不需要注册账号或设置密码:你唯一需要的凭据就是托盘悬浮窗里的统一 API 密钥。从源码构建的步骤,以及数据存放位置,见 [docs/install.md](docs/zh-cn/install/01-install.md#桌面应用)。
## 兼容 OpenAI 的客户端
-任何能指定 OpenAI 兼容 base URL 的东西都能用:把它设成 `http://localhost:3001/v1`,配上仪表盘里的统一密钥。**Claude Code**、**Codex CLI**、**Cline / Roo Code**、**Continue**(含行内补全)、**Aider**、**opencode** 和 **Cursor** 在 **[docs/en/clients/01-agent-clients.md](docs/en/clients/01-agent-clients.md)** 里各有一段简短配方。此外路由器本身还兼作 MCP 服务,你的智能体可以在会话中随时查询它。
+任何能指定 OpenAI 兼容 base URL 的东西都能用:把它设成 `http://localhost:3001/v1`,配上仪表盘里的统一密钥。**Claude Code**、**Codex CLI**、**Cline / Roo Code**、**Continue**(含行内补全)、**Aider**、**opencode** 和 **Cursor** 在 **[docs/en/clients/01-agent-clients.md](docs/zh-cn/clients/01-agent-clients.md)** 里各有一段简短配方。此外路由器本身还兼作 MCP 服务,你的智能体可以在会话中随时查询它。
最快的配置方式是根据你服务器上实际可用的模型生成:
@@ -226,7 +226,7 @@ FreeLLMAPI 在设计上是本地优先、单用户的。你的提供方密钥留
翻译文件以扁平 JSON 的形式放在 [`client/src/i18n/locales/`](client/src/i18n/locales)。想修某个字符串,直接改对应语言 JSON 里的值即可。想加一门语言,复制 `en.json`、翻译其中的值,再到 `client/src/i18n/locale-config.ts` 注册这个语言(托盘文案还需要改 `desktop/src/i18n.ts`);`npm test` 会检查每种语言的键和占位符是否对齐。欢迎提 PR。
-中文的术语约定见 [docs/i18n/01-translating.md](docs/TRANSLATION.md),提交翻译前请先过一遍,这样 README 和仪表盘里的说法能对得上。
+中文的术语约定见 [docs/TRANSLATION.md](docs/TRANSLATION.md),提交翻译前请先过一遍,这样 README 和仪表盘里的说法能对得上。
## Premium 实时目录
@@ -263,7 +263,7 @@ print(resp.choices[0].message.content)
print("Routed via:", resp.headers.get("x-routed-via"))
```
-流式、`auto:*` 路由策略、工具调用、视觉输入、Gemini 的 Google 搜索接地、嵌入,以及 Anthropic Messages 接口,连同各自的 curl 和 Python 示例,全都在 **[docs/en/api/01-rest-api.md](docs/en/api/01-rest-api.md)**。每个响应都带一个 `X-Routed-Via: <平台>/<模型>` 头,你可以据此看出实际是哪家提供方处理的。
+流式、`auto:*` 路由策略、工具调用、视觉输入、Gemini 的 Google 搜索接地、嵌入,以及 Anthropic Messages 接口,连同各自的 curl 和 Python 示例,全都在 **[docs/en/api/01-rest-api.md](docs/zh-cn/api/01-rest-api.md)**。每个响应都带一个 `X-Routed-Via: <平台>/<模型>` 头,你可以据此看出实际是哪家提供方处理的。
## 截图
@@ -295,11 +295,11 @@ print("Routed via:", resp.headers.get("x-routed-via"))
![一个请求进去,最合适的免费模型出来 —— 带实时评分、冷却和额度跟踪的回退链](repo-assets/router-flow.png)
-一个请求进去,最合适的免费模型出来:路由器挑出优先级最高、密钥健康且未超出任何限流的模型,在内存中解密密钥并调用提供方;遇到 429/5xx 就让那个密钥进入冷却,然后重试你链路上的下一个模型。组件走查、路由内部实现和运维细节都在 **[docs/architecture.md](docs/en/architecture/00-high-level-index.md)**。
+一个请求进去,最合适的免费模型出来:路由器挑出优先级最高、密钥健康且未超出任何限流的模型,在内存中解密密钥并调用提供方;遇到 429/5xx 就让那个密钥进入冷却,然后重试你链路上的下一个模型。组件走查、路由内部实现和运维细节都在 **[docs/architecture.md](docs/zh-cn/architecture/00-high-level-index.md)**。
## 局限性
-叠加免费额度是有实实在在的代价的:没有前沿模型,延迟不稳定,没有 SLA。而且到了一天的后半段,顶级模型陆续触及当日上限,这个端点的实际智能水平会下滑,然后在 UTC 午夜重置。在拿它做任何正经东西之前,请先读一遍 **[docs/architecture.md#limitations](docs/en/architecture/00-high-level-index.md#limitations)** 里那份诚实的清单。
+叠加免费额度是有实实在在的代价的:没有前沿模型,延迟不稳定,没有 SLA。而且到了一天的后半段,顶级模型陆续触及当日上限,这个端点的实际智能水平会下滑,然后在 UTC 午夜重置。在拿它做任何正经东西之前,请先读一遍 **[docs/architecture.md#limitations](docs/zh-cn/architecture/00-high-level-index.md#局限性)** 里那份诚实的清单。
## 参与贡献
@@ -321,7 +321,7 @@ print("Routed via:", resp.headers.get("x-routed-via"))
**本项目用于个人实验和学习,不适用于生产环境。** 免费额度的存在是为了让开发者拿来做原型;它们不是稳定、有支持的推理基础设施,也不该被当成这种东西。如果你要在 FreeLLMAPI 之上做真正的产品,上线前请换成付费 API。你和每家上游提供方之间的关系,受你注册账号时接受的条款约束;流量经由本项目代理时这些条款依然适用,遵守它们是你的责任。
-各家提供方的服务条款如何看待一个个人的、单用户的代理,在 2026 年 5 月逐家审查过,结论在 [docs/architecture.md#terms-of-service-review](docs/en/architecture/00-high-level-index.md#terms-of-service-review)。
+各家提供方的服务条款如何看待一个个人的、单用户的代理,在 2026 年 5 月逐家审查过,结论在 [docs/architecture.md#terms-of-service-review](docs/zh-cn/architecture/00-high-level-index.md#服务条款审查)。
## 许可证
diff --git a/docs/OVERVIEW.md b/docs/OVERVIEW.md
index 7a5bd52c..99df8bb2 100644
--- a/docs/OVERVIEW.md
+++ b/docs/OVERVIEW.md
@@ -2,7 +2,7 @@
## Scope
-This file is the domain index for `docs/` — a complete file map of every guide and domain folder (install, API, clients, CLI, compression, architecture deep-dives, env, proxy, deployment, providers, testing, fallback, logs, desktop, troubleshooting, glossary, i18n). It lists where each document lives and how the domain folders relate.
+This file is the domain index for `docs/` — a complete file map of every guide and domain folder (install, API, clients, CLI, compression, architecture deep-dives, env, proxy, deployment, providers, testing, fallback, logs, desktop, troubleshooting, glossary) plus the translation guide. It lists where each document lives and how the domain folders relate.
For getting started as a user, see [en/README.md](en/README.md) (English entry point); for the product overview, see the root [README](../README.md).
@@ -11,7 +11,7 @@ For getting started as a user, see [en/README.md](en/README.md) (English entry p
| File | Description |
| --- | --- |
| [en/](en/OVERVIEW.md) | **English** — all domains (api with 00-high-level-index, cli, clients, desktop, env, fallback, glossary, install, logs, proxy, providers, testing, troubleshooting). |
-| [zh-cn/](zh-cn/OVERVIEW.md) | **简体中文** — Chinese translations (mirrors `en/`, see `en/` for authoritative source; `zh-cn/` currently stubs — see `i18n/` for coverage). |
+| [zh-cn/](zh-cn/OVERVIEW.md) | **简体中文** — Chinese translations, one file per English page with the same name (mirrors `en/` exactly; `en/` is authoritative where the two disagree). |
| [TRANSLATION.md](TRANSLATION.md) | Translating: rules for locale files, the validator, and the settled terminology table. |
| [index.html](index.html) | Static website asset (not a doc): redirect page to freellmapi.co. |
| [success.html](success.html) | Static website asset (not a doc): post-install success page. |
diff --git a/docs/TRANSLATION.md b/docs/TRANSLATION.md
index e73fb2ae..e0dcdc4c 100644
--- a/docs/TRANSLATION.md
+++ b/docs/TRANSLATION.md
@@ -3,8 +3,10 @@
The dashboard ships 60 locales under `client/src/i18n/locales/`. `en.json` is the source of
truth: every other file mirrors its key structure exactly.
-Translating the README and the docs pages is a separate job with its own layout and rules,
-covered in [TRANSLATION.md](TRANSLATION.md) itself. The terminology table below applies to both.
+Translating the README and the docs pages is a separate job: the tree is `docs/<lang>/<domain>/…`,
+one file per English page with the same name, and each language keeps its own index at
+`docs/<lang>/OVERVIEW.md` (see [zh-cn/OVERVIEW.md](zh-cn/OVERVIEW.md)). The terminology table
+below applies to both.
## Before you open a PR
diff --git a/docs/en/CHANGELOG.md b/docs/en/CHANGELOG.md
index 05dea470..b09f7ae6 100644
--- a/docs/en/CHANGELOG.md
+++ b/docs/en/CHANGELOG.md
@@ -1,3 +1,5 @@
+**English** · [简体中文](../zh-cn/CHANGELOG.md)
+
# Changelog — en
| Commit | Date | Summary |
diff --git a/docs/en/OVERVIEW.md b/docs/en/OVERVIEW.md
index ad8c4c18..a231146d 100644
--- a/docs/en/OVERVIEW.md
+++ b/docs/en/OVERVIEW.md
@@ -1,3 +1,5 @@
+**English** · [简体中文](../zh-cn/OVERVIEW.md)
+
# Docs — English
Language-specific index for English documentation.
diff --git a/docs/en/README.md b/docs/en/README.md
index 2cf41811..78a73177 100644
--- a/docs/en/README.md
+++ b/docs/en/README.md
@@ -1,4 +1,4 @@
-**English** · [简体中文](../zh-cn/OVERVIEW.md)
+**English** · [简体中文](../zh-cn/README.md)
# FreeLLMAPI documentation
diff --git a/docs/en/api/01-rest-api.md b/docs/en/api/01-rest-api.md
index 3f155d41..bda6d110 100644
--- a/docs/en/api/01-rest-api.md
+++ b/docs/en/api/01-rest-api.md
@@ -1,4 +1,4 @@
-**English** · [简体中文](../../zh-cn/api/OVERVIEW.md)
+**English** · [简体中文](../../zh-cn/api/01-rest-api.md)
# API reference
@@ -91,7 +91,7 @@ curl http://localhost:3001/v1/chat/completions \
}'
```
-An unknown profile name returns a clear `400` rather than silently falling back. Profiles are named fallback chains (see [Features](../README.md#features)) — create and switch them from the dashboard; whichever is active is what plain `auto` uses.
+An unknown profile name returns a clear `400` rather than silently falling back. Profiles are named fallback chains (see [Features](../../../README.md#features)) — create and switch them from the dashboard; whichever is active is what plain `auto` uses.
## Model listing
diff --git a/docs/en/api/02-idempotency.md b/docs/en/api/02-idempotency.md
index d26b4c85..7c19f465 100644
--- a/docs/en/api/02-idempotency.md
+++ b/docs/en/api/02-idempotency.md
@@ -1,3 +1,5 @@
+**English** · [简体中文](../../zh-cn/api/02-idempotency.md)
+
# Idempotency-Key — Safe Retries for Non-Streaming Chat Completions
> **Sources:** `server/src/services/idempotency.ts`, `server/src/routes/proxy.ts:1793-1835` (entry) + `2640-2656` (persist), `server/src/db/migrations/20260901_000001_idempotency_claims.ts`, commit `36b877d` (feature), `95bc46f` (in-flight clarification), env `IDEMPOTENCY_TTL_MS` documented in `docs/env/01-variables.md#idempotency`.
diff --git a/docs/en/api/CHANGELOG.md b/docs/en/api/CHANGELOG.md
index 660b3b1e..5a0481c0 100644
--- a/docs/en/api/CHANGELOG.md
+++ b/docs/en/api/CHANGELOG.md
@@ -1,3 +1,5 @@
+**English** · [简体中文](../../zh-cn/api/CHANGELOG.md)
+
# API Domain — Changelog
Doc revision history for `docs/api/`, seeded from API-relevant commits.
diff --git a/docs/en/api/OVERVIEW.md b/docs/en/api/OVERVIEW.md
index c3d90698..04879b09 100644
--- a/docs/en/api/OVERVIEW.md
+++ b/docs/en/api/OVERVIEW.md
@@ -1,3 +1,5 @@
+**English** · [简体中文](../../zh-cn/api/OVERVIEW.md)
+
# API Domain — Overview & File Index
This domain documents FreeLLMAPI's OpenAI-compatible HTTP surface and its Anthropic/Gemini-compatible shims. The root [`README.md`](../README.md) and [`OVERVIEW.md`](../OVERVIEW.md) index this as the gateway's external contract.
diff --git a/docs/en/architecture/00-high-level-index.md b/docs/en/architecture/00-high-level-index.md
index cbf15698..f18c4613 100644
--- a/docs/en/architecture/00-high-level-index.md
+++ b/docs/en/architecture/00-high-level-index.md
@@ -1,3 +1,5 @@
+**English** · [简体中文](../../zh-cn/architecture/00-high-level-index.md)
+
# Architecture & internals
[← Back to README](../../../README.md) · [Documentation index](../README.md) · [Deep-dive domain](OVERVIEW.md)
@@ -57,7 +59,7 @@ The scope is deliberately narrow. If a feature isn't in the README's feature lis
- **`n > 1`** (multiple completions per request)
- **Per-user billing / multi-tenant auth** — single-user by design
-PRs that add any of these are very welcome. See [Contributing](../README.md#contributing).
+PRs that add any of these are very welcome. See [Contributing](../../../README.md#contributing).
## Limitations
diff --git a/docs/en/architecture/01-routing-and-bandit-scoring.md b/docs/en/architecture/01-routing-and-bandit-scoring.md
index f4941202..add6f823 100644
--- a/docs/en/architecture/01-routing-and-bandit-scoring.md
+++ b/docs/en/architecture/01-routing-and-bandit-scoring.md
@@ -1,3 +1,5 @@
+**English** · [简体中文](../../zh-cn/architecture/01-routing-and-bandit-scoring.md)
+
# Routing & Bandit Scoring — Deep Dive
> **Source:** `server/src/services/router.ts`, `server/src/services/scoring.ts`
diff --git a/docs/en/architecture/02-quota-and-cooldown-engine.md b/docs/en/architecture/02-quota-and-cooldown-engine.md
index 476dcb78..0b60b9e0 100644
--- a/docs/en/architecture/02-quota-and-cooldown-engine.md
+++ b/docs/en/architecture/02-quota-and-cooldown-engine.md
@@ -1,3 +1,5 @@
+**English** · [简体中文](../../zh-cn/architecture/02-quota-and-cooldown-engine.md)
+
# Quota & Cooldown Engine — Deep Dive
> **Source:** `server/src/services/ratelimit.ts`, `server/src/services/cooldown-probe.ts`, `server/src/services/provider-quota.ts`
diff --git a/docs/en/architecture/03-streaming-pipeline.md b/docs/en/architecture/03-streaming-pipeline.md
index b1e13099..91266baf 100644
--- a/docs/en/architecture/03-streaming-pipeline.md
+++ b/docs/en/architecture/03-streaming-pipeline.md
@@ -1,3 +1,5 @@
+**English** · [简体中文](../../zh-cn/architecture/03-streaming-pipeline.md)
+
# Streaming Pipeline — Deep Dive
> **Source:** `server/src/routes/proxy.ts`, `server/src/routes/responses.ts`, `server/src/routes/anthropic.ts`, `server/src/lib/fallback-loop.ts`
diff --git a/docs/en/architecture/04-degraded-mode-and-failover.md b/docs/en/architecture/04-degraded-mode-and-failover.md
index 0ddf4cc5..1881f1a2 100644
--- a/docs/en/architecture/04-degraded-mode-and-failover.md
+++ b/docs/en/architecture/04-degraded-mode-and-failover.md
@@ -1,3 +1,5 @@
+**English** · [简体中文](../../zh-cn/architecture/04-degraded-mode-and-failover.md)
+
# Degraded Mode & Failover — Deep Dive
> **Source:** `server/src/services/degradation.ts`, `server/src/lib/fallback-loop.ts`, `server/src/routes/proxy.ts`, `server/src/services/ratelimit.ts`, `server/src/services/idempotency.ts`
diff --git a/docs/en/architecture/05-catalog-sync.md b/docs/en/architecture/05-catalog-sync.md
index 6d0d51e6..b54e52de 100644
--- a/docs/en/architecture/05-catalog-sync.md
+++ b/docs/en/architecture/05-catalog-sync.md
@@ -1,3 +1,5 @@
+**English** · [简体中文](../../zh-cn/architecture/05-catalog-sync.md)
+
# Catalog Sync — Deep Dive
> **Source:** `server/src/services/catalog-sync.ts`, `server/src/services/model-state.ts`, `server/src/db/migrations/`
diff --git a/docs/en/architecture/06-observability.md b/docs/en/architecture/06-observability.md
index ac0f655b..d5413016 100644
--- a/docs/en/architecture/06-observability.md
+++ b/docs/en/architecture/06-observability.md
@@ -1,3 +1,5 @@
+**English** · [简体中文](../../zh-cn/architecture/06-observability.md)
+
# Observability — Deep Dive
> **Source:** `server/src/lib/server-logs.ts`, `server/src/routes/logs.ts`, `server/src/lib/request-log.ts`, `server/src/lib/log-redaction.ts`, `server/src/lib/attempt-trace.ts`
diff --git a/docs/en/architecture/CHANGELOG.md b/docs/en/architecture/CHANGELOG.md
index 74205334..0a17e635 100644
--- a/docs/en/architecture/CHANGELOG.md
+++ b/docs/en/architecture/CHANGELOG.md
@@ -1,3 +1,5 @@
+**English** · [简体中文](../../zh-cn/architecture/CHANGELOG.md)
+
# Architecture Domain — Changelog
Doc revision history for `docs/architecture/`, seeded from commits touching architecture-relevant code.
diff --git a/docs/en/architecture/OVERVIEW.md b/docs/en/architecture/OVERVIEW.md
index c16ab72f..01a3d8a6 100644
--- a/docs/en/architecture/OVERVIEW.md
+++ b/docs/en/architecture/OVERVIEW.md
@@ -1,3 +1,5 @@
+**English** · [简体中文](../../zh-cn/architecture/OVERVIEW.md)
+
# Architecture Domain — Overview & File Index
## Scope
diff --git a/docs/en/cli/01-generators.md b/docs/en/cli/01-generators.md
index b1c9b1c2..36dd0045 100644
--- a/docs/en/cli/01-generators.md
+++ b/docs/en/cli/01-generators.md
@@ -1,3 +1,5 @@
+**English** · [简体中文](../../zh-cn/cli/01-generators.md)
+
# Setup generators
## Usage
diff --git a/docs/en/cli/02-config-files.md b/docs/en/cli/02-config-files.md
index 88171de5..1439c162 100644
--- a/docs/en/cli/02-config-files.md
+++ b/docs/en/cli/02-config-files.md
@@ -1,3 +1,5 @@
+**English** · [简体中文](../../zh-cn/cli/02-config-files.md)
+
# Config files
## Registry — `cli/tools.json`
@@ -29,7 +31,7 @@ Before first write, `config-files.ts` copies the existing file to `<path>.bak.<I
1. Add entry to `cli/tools.json` (`id`, `name`, `category`, `configType`, `protocol`, `baseUrlSupport`, `command`, `docsUrl`).
2. Add `function myTool(ctx: GenerateContext): Generation` in `cli/src/tools.ts` — return `files` with correct `path`/`format`/`value` and `notes` for the CLI output. Use helpers `rootUrl()`/`v1Url()`/`primaryModel()`/`contextWindow()`.
3. Add snapshot case in `cli/src/tools.test.ts`.
-4. Document in [01-generators.md](01-generators.md) table + `docs/clients/01-agent-clients.md` section.
+4. Document in [01-generators.md](01-generators.md) table + `docs/en/clients/01-agent-clients.md` section.
5. Sync `client/src/data/agent-tools.json` if the dashboard lists it.
## Related
diff --git a/docs/en/cli/CHANGELOG.md b/docs/en/cli/CHANGELOG.md
index 74ef0153..66305405 100644
--- a/docs/en/cli/CHANGELOG.md
+++ b/docs/en/cli/CHANGELOG.md
@@ -1,3 +1,5 @@
+**English** · [简体中文](../../zh-cn/cli/CHANGELOG.md)
+
# Changelog — cli
| Commit | Date | Summary |
diff --git a/docs/en/cli/OVERVIEW.md b/docs/en/cli/OVERVIEW.md
index 718a676d..78f1e94b 100644
--- a/docs/en/cli/OVERVIEW.md
+++ b/docs/en/cli/OVERVIEW.md
@@ -1,3 +1,5 @@
+**English** · [简体中文](../../zh-cn/cli/OVERVIEW.md)
+
# CLI Domain — Overview & File Index
## Scope
diff --git a/docs/en/clients/01-agent-clients.md b/docs/en/clients/01-agent-clients.md
index a8ff52bd..e24350fd 100644
--- a/docs/en/clients/01-agent-clients.md
+++ b/docs/en/clients/01-agent-clients.md
@@ -1,3 +1,5 @@
+**English** · [简体中文](../../zh-cn/clients/01-agent-clients.md)
+
# Clients & coding agents
[← Back to README](../README.md) · [Documentation index](../README.md)
diff --git a/docs/en/clients/CHANGELOG.md b/docs/en/clients/CHANGELOG.md
index 2fc7a489..2a837290 100644
--- a/docs/en/clients/CHANGELOG.md
+++ b/docs/en/clients/CHANGELOG.md
@@ -1,3 +1,5 @@
+**English** · [简体中文](../../zh-cn/clients/CHANGELOG.md)
+
# Changelog
Doc revision history for `docs/clients/`. Most recent first.
diff --git a/docs/en/clients/OVERVIEW.md b/docs/en/clients/OVERVIEW.md
index efc62a65..2a4ffed3 100644
--- a/docs/en/clients/OVERVIEW.md
+++ b/docs/en/clients/OVERVIEW.md
@@ -1,3 +1,5 @@
+**English** · [简体中文](../../zh-cn/clients/OVERVIEW.md)
+
# Clients Domain
## Scope
diff --git a/docs/en/compression/01-compression-pipeline.md b/docs/en/compression/01-compression-pipeline.md
index 1657a342..8f8d82a8 100644
--- a/docs/en/compression/01-compression-pipeline.md
+++ b/docs/en/compression/01-compression-pipeline.md
@@ -1,3 +1,5 @@
+**English** · [简体中文](../../zh-cn/compression/01-compression-pipeline.md)
+
# Prompt compression
[← Back to README](../README.md) · [Documentation index](../README.md) · [API reference](../api/01-rest-api.md)
diff --git a/docs/en/compression/CHANGELOG.md b/docs/en/compression/CHANGELOG.md
index f457215e..c3821ed8 100644
--- a/docs/en/compression/CHANGELOG.md
+++ b/docs/en/compression/CHANGELOG.md
@@ -1,3 +1,5 @@
+**English** · [简体中文](../../zh-cn/compression/CHANGELOG.md)
+
# Changelog
Doc revision history for `docs/compression/`. Most recent first.
diff --git a/docs/en/compression/OVERVIEW.md b/docs/en/compression/OVERVIEW.md
index 77b64c6b..a0ec269c 100644
--- a/docs/en/compression/OVERVIEW.md
+++ b/docs/en/compression/OVERVIEW.md
@@ -1,3 +1,5 @@
+**English** · [简体中文](../../zh-cn/compression/OVERVIEW.md)
+
# Compression Domain
## Scope
diff --git a/docs/en/deployment/01-docker.md b/docs/en/deployment/01-docker.md
index fa99dc15..9a08e6fd 100644
--- a/docs/en/deployment/01-docker.md
+++ b/docs/en/deployment/01-docker.md
@@ -1,3 +1,5 @@
+**English** · [简体中文](../../zh-cn/deployment/01-docker.md)
+
# Docker
The production image, the Compose quickstart, and everything about running FreeLLMAPI in a container: persistence, ports, health, and the networking gotchas.
diff --git a/docs/en/deployment/02-updates-and-backup.md b/docs/en/deployment/02-updates-and-backup.md
index 45d5c127..a14f6575 100644
--- a/docs/en/deployment/02-updates-and-backup.md
+++ b/docs/en/deployment/02-updates-and-backup.md
@@ -1,3 +1,5 @@
+**English** · [简体中文](../../zh-cn/deployment/02-updates-and-backup.md)
+
# Updates and backup
Keeping a Docker deployment current, protecting the SQLite data volume, and making installs reproducible with declarative configuration.
diff --git a/docs/en/deployment/CHANGELOG.md b/docs/en/deployment/CHANGELOG.md
index f35ad360..75584872 100644
--- a/docs/en/deployment/CHANGELOG.md
+++ b/docs/en/deployment/CHANGELOG.md
@@ -1,3 +1,5 @@
+**English** · [简体中文](../../zh-cn/deployment/CHANGELOG.md)
+
# Changelog
Revision history for `docs/deployment/`, listing the commits that shaped the Docker operations and maintenance behavior documented here. Most recent first.
diff --git a/docs/en/deployment/OVERVIEW.md b/docs/en/deployment/OVERVIEW.md
index f3d1a63b..8d026222 100644
--- a/docs/en/deployment/OVERVIEW.md
+++ b/docs/en/deployment/OVERVIEW.md
@@ -1,3 +1,5 @@
+**English** · [简体中文](../../zh-cn/deployment/OVERVIEW.md)
+
# Deployment overview
## Scope
diff --git a/docs/en/desktop/01-desktop-app.md b/docs/en/desktop/01-desktop-app.md
index 77c68373..633e3f1e 100644
--- a/docs/en/desktop/01-desktop-app.md
+++ b/docs/en/desktop/01-desktop-app.md
@@ -1,3 +1,5 @@
+**English** · [简体中文](../../zh-cn/desktop/01-desktop-app.md)
+
# Desktop app
## Package manifest
diff --git a/docs/en/desktop/02-logging-and-updates.md b/docs/en/desktop/02-logging-and-updates.md
index 8139e7c9..79c7315a 100644
--- a/docs/en/desktop/02-logging-and-updates.md
+++ b/docs/en/desktop/02-logging-and-updates.md
@@ -1,3 +1,5 @@
+**English** · [简体中文](../../zh-cn/desktop/02-logging-and-updates.md)
+
# Logging and updates — desktop
## Why `freeapi.log` exists (#824)
diff --git a/docs/en/desktop/CHANGELOG.md b/docs/en/desktop/CHANGELOG.md
index 2bedaea0..b1184faf 100644
--- a/docs/en/desktop/CHANGELOG.md
+++ b/docs/en/desktop/CHANGELOG.md
@@ -1,3 +1,5 @@
+**English** · [简体中文](../../zh-cn/desktop/CHANGELOG.md)
+
# Changelog — desktop
| Commit | Date | Summary |
diff --git a/docs/en/desktop/OVERVIEW.md b/docs/en/desktop/OVERVIEW.md
index 59963438..9bc46cbe 100644
--- a/docs/en/desktop/OVERVIEW.md
+++ b/docs/en/desktop/OVERVIEW.md
@@ -1,3 +1,5 @@
+**English** · [简体中文](../../zh-cn/desktop/OVERVIEW.md)
+
# Desktop Domain — Overview & File Index
## Scope
diff --git a/docs/en/env/01-variables.md b/docs/en/env/01-variables.md
index 109fa04c..98130714 100644
--- a/docs/en/env/01-variables.md
+++ b/docs/en/env/01-variables.md
@@ -1,3 +1,5 @@
+**English** · [简体中文](../../zh-cn/env/01-variables.md)
+
# Environment variable reference
Every variable FreeLLMAPI reads from `.env`, grouped by concern. Defaults and descriptions are derived only from the comments and values in [`.env.example`](../../../.env.example). Variables shown commented out in `.env.example` are optional; their documented default is listed here.
diff --git a/docs/en/env/02-security-and-keys.md b/docs/en/env/02-security-and-keys.md
index 1313819b..3631ae75 100644
--- a/docs/en/env/02-security-and-keys.md
+++ b/docs/en/env/02-security-and-keys.md
@@ -1,3 +1,5 @@
+**English** · [简体中文](../../zh-cn/env/02-security-and-keys.md)
+
# Security and key handling
How FreeLLMAPI protects the provider API keys you store in it, and how the `ENCRYPTION_KEY` that makes that protection real is generated, stored, and migrated.
diff --git a/docs/en/env/03-outbound-proxies.md b/docs/en/env/03-outbound-proxies.md
index 65644998..79e1e68b 100644
--- a/docs/en/env/03-outbound-proxies.md
+++ b/docs/en/env/03-outbound-proxies.md
@@ -1,3 +1,5 @@
+**English** · [简体中文](../../zh-cn/env/03-outbound-proxies.md)
+
# Outbound proxies
How FreeLLMAPI routes its provider-bound traffic through proxies, which variables win when several are set, and the Docker networking gotchas that come with that.
@@ -5,7 +7,7 @@ How FreeLLMAPI routes its provider-bound traffic through proxies, which variable
Sources: [`.env.example`](../../../.env.example) (proxy block), [`docker-compose.yml`](../../../docker-compose.yml), the container-networking notes in [`docs/install.md`](../install/01-install.md), the proxy transports in [`../proxy/01-fetch-relay.md`](../proxy/01-fetch-relay.md) / [`../proxy/OVERVIEW.md`](../proxy/OVERVIEW.md) (`server/src/lib/proxy.ts:52-414`, `server/src/lib/config.ts:95-110` for `TRUST_PROXY`).
- [Proxy chain precedence](#proxy-chain-precedence)
-- [Fetch Relay transport](#fetch-relay-transport)
+- [Fetch Relay transport](#fetch-relay-transport-summary)
- [Scheme support](#scheme-support)
- [NO_PROXY bypasses](#no_proxy-bypasses)
- [Docker: 127.0.0.1 is the container](#docker-127001-is-the-container)
diff --git a/docs/en/env/CHANGELOG.md b/docs/en/env/CHANGELOG.md
index e56cacb7..1caa4d53 100644
--- a/docs/en/env/CHANGELOG.md
+++ b/docs/en/env/CHANGELOG.md
@@ -1,3 +1,5 @@
+**English** · [简体中文](../../zh-cn/env/CHANGELOG.md)
+
# Changelog
Revision history for `docs/env/`, listing the commits that shaped the runtime configuration surface documented here. Most recent first.
diff --git a/docs/en/env/OVERVIEW.md b/docs/en/env/OVERVIEW.md
index b566cd63..e5b845ff 100644
--- a/docs/en/env/OVERVIEW.md
+++ b/docs/en/env/OVERVIEW.md
@@ -1,3 +1,5 @@
+**English** · [简体中文](../../zh-cn/env/OVERVIEW.md)
+
# Environment configuration overview
## Scope
diff --git a/docs/en/fallback/01-named-chains.md b/docs/en/fallback/01-named-chains.md
index 2ba7f657..baf1d774 100644
--- a/docs/en/fallback/01-named-chains.md
+++ b/docs/en/fallback/01-named-chains.md
@@ -1,3 +1,5 @@
+**English** · [简体中文](../../zh-cn/fallback/01-named-chains.md)
+
# Named Fallback Chains
> **Source:** `server/src/services/router.ts` (`activeChainOrThrow`, `resolveRoutingChain`), `server/src/services/profile-models.ts` (`getActiveProfileId`, `autoIncludeNewModelsForProfiles`), `server/src/routes/fallback.ts`, `server/src/routes/profiles.ts`
diff --git a/docs/en/fallback/CHANGELOG.md b/docs/en/fallback/CHANGELOG.md
index 6644ce69..da6fa06b 100644
--- a/docs/en/fallback/CHANGELOG.md
+++ b/docs/en/fallback/CHANGELOG.md
@@ -1,3 +1,5 @@
+**English** · [简体中文](../../zh-cn/fallback/CHANGELOG.md)
+
# Fallback Domain — Changelog
Doc revision history for `docs/fallback/`, seeded from fallback-relevant commits.
diff --git a/docs/en/fallback/OVERVIEW.md b/docs/en/fallback/OVERVIEW.md
index a845e1d3..8a81631e 100644
--- a/docs/en/fallback/OVERVIEW.md
+++ b/docs/en/fallback/OVERVIEW.md
@@ -1,3 +1,5 @@
+**English** · [简体中文](../../zh-cn/fallback/OVERVIEW.md)
+
# Fallback Domain — Overview & File Index
This domain documents FreeLLMAPI's named fallback-chain system: how chains are stored, how the router resolves the active chain (and refuses when it is empty), how named chains surface to clients as `auto:<name>`, and how catalog sync interacts with curated chains. The root [`README.md`](../README.md) and [`OVERVIEW.md`](../OVERVIEW.md) index this as the operator's primary mechanism for controlling which models the router may use.
diff --git a/docs/en/glossary/01-glossary.md b/docs/en/glossary/01-glossary.md
index 2db58ea9..4ca27abb 100644
--- a/docs/en/glossary/01-glossary.md
+++ b/docs/en/glossary/01-glossary.md
@@ -1,3 +1,5 @@
+**English** · [简体中文](../../zh-cn/glossary/01-glossary.md)
+
# Glossary
| Term | Meaning |
diff --git a/docs/en/glossary/CHANGELOG.md b/docs/en/glossary/CHANGELOG.md
index 2414b5b9..89d8a47f 100644
--- a/docs/en/glossary/CHANGELOG.md
+++ b/docs/en/glossary/CHANGELOG.md
@@ -1,3 +1,5 @@
+**English** · [简体中文](../../zh-cn/glossary/CHANGELOG.md)
+
# Changelog — glossary
| Commit | Date | Summary |
diff --git a/docs/en/glossary/OVERVIEW.md b/docs/en/glossary/OVERVIEW.md
index 9cb9f5ff..61453cdf 100644
--- a/docs/en/glossary/OVERVIEW.md
+++ b/docs/en/glossary/OVERVIEW.md
@@ -1,3 +1,5 @@
+**English** · [简体中文](../../zh-cn/glossary/OVERVIEW.md)
+
# Glossary Domain — Overview & File Index
## Scope
diff --git a/docs/en/install/01-install.md b/docs/en/install/01-install.md
index f3fdc2b3..fa2111ab 100644
--- a/docs/en/install/01-install.md
+++ b/docs/en/install/01-install.md
@@ -1,4 +1,4 @@
-**English** · [简体中文](../../zh-cn/install/OVERVIEW.md)
+**English** · [简体中文](../../zh-cn/install/01-install.md)
# Install & deploy
diff --git a/docs/en/install/02-android-termux.md b/docs/en/install/02-android-termux.md
index e6c54dce..6fc6d482 100644
--- a/docs/en/install/02-android-termux.md
+++ b/docs/en/install/02-android-termux.md
@@ -1,3 +1,5 @@
+**English** · [简体中文](../../zh-cn/install/02-android-termux.md)
+
# Android (Termux) installation
> Experimental and community-supported. FreeLLMAPI runs locally on the Android device.
diff --git a/docs/en/install/CHANGELOG.md b/docs/en/install/CHANGELOG.md
index 9f0b798b..ff06c537 100644
--- a/docs/en/install/CHANGELOG.md
+++ b/docs/en/install/CHANGELOG.md
@@ -1,3 +1,5 @@
+**English** · [简体中文](../../zh-cn/install/CHANGELOG.md)
+
# Changelog
Revision history for `docs/install/`, derived from git commits touching this directory. Most recent first.
diff --git a/docs/en/install/OVERVIEW.md b/docs/en/install/OVERVIEW.md
index 63a7a338..f385f0c2 100644
--- a/docs/en/install/OVERVIEW.md
+++ b/docs/en/install/OVERVIEW.md
@@ -1,3 +1,5 @@
+**English** · [简体中文](../../zh-cn/install/OVERVIEW.md)
+
# Install guides overview
## Scope
diff --git a/docs/en/logs/01-server-logs-viewer.md b/docs/en/logs/01-server-logs-viewer.md
index 2f7213ca..b25c4272 100644
--- a/docs/en/logs/01-server-logs-viewer.md
+++ b/docs/en/logs/01-server-logs-viewer.md
@@ -1,3 +1,5 @@
+**English** · [简体中文](../../zh-cn/logs/01-server-logs-viewer.md)
+
# Server Logs Viewer
The dashboard includes a live **Server Logs** viewer (accessible from the
diff --git a/docs/en/logs/CHANGELOG.md b/docs/en/logs/CHANGELOG.md
index 2511d8cf..8734a3db 100644
--- a/docs/en/logs/CHANGELOG.md
+++ b/docs/en/logs/CHANGELOG.md
@@ -1,3 +1,5 @@
+**English** · [简体中文](../../zh-cn/logs/CHANGELOG.md)
+
# Changelog
Doc revision history for `docs/logs/`. Most recent first.
diff --git a/docs/en/logs/OVERVIEW.md b/docs/en/logs/OVERVIEW.md
index 4b086c6d..ed6c409f 100644
--- a/docs/en/logs/OVERVIEW.md
+++ b/docs/en/logs/OVERVIEW.md
@@ -1,3 +1,5 @@
+**English** · [简体中文](../../zh-cn/logs/OVERVIEW.md)
+
# Logs Domain
## Scope
diff --git a/docs/en/providers/01-supported-platforms.md b/docs/en/providers/01-supported-platforms.md
index a322a1a3..67beb7cf 100644
--- a/docs/en/providers/01-supported-platforms.md
+++ b/docs/en/providers/01-supported-platforms.md
@@ -1,3 +1,5 @@
+**English** · [简体中文](../../zh-cn/providers/01-supported-platforms.md)
+
# Supported platforms
The `Platform` union in [`shared/types.ts` (line 59)](../../../shared/types.ts) is the single source of truth for platform identity; the runtime registry in [`server/src/providers/index.ts`](../../../server/src/providers/index.ts) must match it. The union currently declares **43 members**:
diff --git a/docs/en/providers/02-quotas-and-cooldowns.md b/docs/en/providers/02-quotas-and-cooldowns.md
index 51195b39..dee89c2d 100644
--- a/docs/en/providers/02-quotas-and-cooldowns.md
+++ b/docs/en/providers/02-quotas-and-cooldowns.md
@@ -1,3 +1,5 @@
+**English** · [简体中文](../../zh-cn/providers/02-quotas-and-cooldowns.md)
+
# Quotas, cooldowns, and key health
Free tiers fail in specific, metered ways: per-minute and per-day request caps, token budgets, concurrency limits, and outright quota exhaustion. The gateway models all of them so the router stops spending fallback attempts on keys it already knows are spent. The machinery lives in [`server/src/services/ratelimit.ts`](../../../server/src/services/ratelimit.ts), [`server/src/services/provider-quota.ts`](../../../server/src/services/provider-quota.ts), [`server/src/services/cooldown-probe.ts`](../../../server/src/services/cooldown-probe.ts), [`server/src/services/health.ts`](../../../server/src/services/health.ts), and the shared back-off parsers in [`server/src/providers/base.ts`](../../../server/src/providers/base.ts).
diff --git a/docs/en/providers/03-adding-a-new-provider.md b/docs/en/providers/03-adding-a-new-provider.md
index c0f536bc..f8f5dec8 100644
--- a/docs/en/providers/03-adding-a-new-provider.md
+++ b/docs/en/providers/03-adding-a-new-provider.md
@@ -1,3 +1,5 @@
+**English** · [简体中文](../../zh-cn/providers/03-adding-a-new-provider.md)
+
# Adding a new provider
A contributor walkthrough that mirrors how the existing 41 built-in platforms are wired. Read [`server/src/providers/index.ts`](../../../server/src/providers/index.ts) alongside this guide — it is both the registry and the best documentation of per-platform judgment calls.
diff --git a/docs/en/providers/CHANGELOG.md b/docs/en/providers/CHANGELOG.md
index 87c058ef..7982f7d3 100644
--- a/docs/en/providers/CHANGELOG.md
+++ b/docs/en/providers/CHANGELOG.md
@@ -1,3 +1,5 @@
+**English** · [简体中文](../../zh-cn/providers/CHANGELOG.md)
+
# Changelog
Revision history for `docs/providers/`, listing the upstream commits that shaped the provider layer documented here. Most recent first.
diff --git a/docs/en/providers/OVERVIEW.md b/docs/en/providers/OVERVIEW.md
index 6c6543b3..68860421 100644
--- a/docs/en/providers/OVERVIEW.md
+++ b/docs/en/providers/OVERVIEW.md
@@ -1,3 +1,5 @@
+**English** · [简体中文](../../zh-cn/providers/OVERVIEW.md)
+
# Provider integrations overview
## Scope
diff --git a/docs/en/proxy/01-fetch-relay.md b/docs/en/proxy/01-fetch-relay.md
index 48b15f2c..9d78fd65 100644
--- a/docs/en/proxy/01-fetch-relay.md
+++ b/docs/en/proxy/01-fetch-relay.md
@@ -1,3 +1,5 @@
+**English** · [简体中文](../../zh-cn/proxy/01-fetch-relay.md)
+
# Fetch Relay transport
FreeLLMAPI can route provider HTTP requests through an application-layer
diff --git a/docs/en/proxy/CHANGELOG.md b/docs/en/proxy/CHANGELOG.md
index 6688ad2e..ba9856c3 100644
--- a/docs/en/proxy/CHANGELOG.md
+++ b/docs/en/proxy/CHANGELOG.md
@@ -1,3 +1,5 @@
+**English** · [简体中文](../../zh-cn/proxy/CHANGELOG.md)
+
# Proxy Domain — Changelog
Revision history for `docs/proxy/`, derived from git commits touching the outbound proxy and Fetch Relay surface. Most recent first.
diff --git a/docs/en/proxy/OVERVIEW.md b/docs/en/proxy/OVERVIEW.md
index ab73b2b7..be047f13 100644
--- a/docs/en/proxy/OVERVIEW.md
+++ b/docs/en/proxy/OVERVIEW.md
@@ -1,3 +1,5 @@
+**English** · [简体中文](../../zh-cn/proxy/OVERVIEW.md)
+
# Proxy Domain — Overview & File Index
## Scope
diff --git a/docs/en/testing/01-running-tests.md b/docs/en/testing/01-running-tests.md
index f70c9c64..22c6fa82 100644
--- a/docs/en/testing/01-running-tests.md
+++ b/docs/en/testing/01-running-tests.md
@@ -1,3 +1,5 @@
+**English** · [简体中文](../../zh-cn/testing/01-running-tests.md)
+
# Running tests
## Root chain
diff --git a/docs/en/testing/02-server-suite.md b/docs/en/testing/02-server-suite.md
index 1c1240a0..32f7201b 100644
--- a/docs/en/testing/02-server-suite.md
+++ b/docs/en/testing/02-server-suite.md
@@ -1,3 +1,5 @@
+**English** · [简体中文](../../zh-cn/testing/02-server-suite.md)
+
# Server suite
## Layout
diff --git a/docs/en/testing/03-compatibility-suite.md b/docs/en/testing/03-compatibility-suite.md
index 65e267e9..1cb4b589 100644
--- a/docs/en/testing/03-compatibility-suite.md
+++ b/docs/en/testing/03-compatibility-suite.md
@@ -1,3 +1,5 @@
+**English** · [简体中文](../../zh-cn/testing/03-compatibility-suite.md)
+
# Compatibility suite
## What it is
diff --git a/docs/en/testing/CHANGELOG.md b/docs/en/testing/CHANGELOG.md
index cb92b5f4..c891705b 100644
--- a/docs/en/testing/CHANGELOG.md
+++ b/docs/en/testing/CHANGELOG.md
@@ -1,3 +1,5 @@
+**English** · [简体中文](../../zh-cn/testing/CHANGELOG.md)
+
# Changelog
Revision history for `docs/testing/`, listing the upstream commits that shaped the test infrastructure documented here. Most recent first.
diff --git a/docs/en/testing/OVERVIEW.md b/docs/en/testing/OVERVIEW.md
index c1ad8e70..5027a3ca 100644
--- a/docs/en/testing/OVERVIEW.md
+++ b/docs/en/testing/OVERVIEW.md
@@ -1,3 +1,5 @@
+**English** · [简体中文](../../zh-cn/testing/OVERVIEW.md)
+
# Testing overview
## Scope
diff --git a/docs/en/troubleshooting/01-common-issues.md b/docs/en/troubleshooting/01-common-issues.md
index 7551b029..22532409 100644
--- a/docs/en/troubleshooting/01-common-issues.md
+++ b/docs/en/troubleshooting/01-common-issues.md
@@ -1,3 +1,5 @@
+**English** · [简体中文](../../zh-cn/troubleshooting/01-common-issues.md)
+
# Common issues
## Docker container cannot reach providers
diff --git a/docs/en/troubleshooting/CHANGELOG.md b/docs/en/troubleshooting/CHANGELOG.md
index 0d9e8786..66b4e263 100644
--- a/docs/en/troubleshooting/CHANGELOG.md
+++ b/docs/en/troubleshooting/CHANGELOG.md
@@ -1,3 +1,5 @@
+**English** · [简体中文](../../zh-cn/troubleshooting/CHANGELOG.md)
+
# Changelog — troubleshooting
| Commit | Date | Summary |
diff --git a/docs/en/troubleshooting/OVERVIEW.md b/docs/en/troubleshooting/OVERVIEW.md
index 84cd5134..d7071d9f 100644
--- a/docs/en/troubleshooting/OVERVIEW.md
+++ b/docs/en/troubleshooting/OVERVIEW.md
@@ -1,3 +1,5 @@
+**English** · [简体中文](../../zh-cn/troubleshooting/OVERVIEW.md)
+
# Troubleshooting Domain — Overview & File Index
## Scope
diff --git a/docs/zh-cn/CHANGELOG.md b/docs/zh-cn/CHANGELOG.md
index d23aedc6..8c88def7 100644
--- a/docs/zh-cn/CHANGELOG.md
+++ b/docs/zh-cn/CHANGELOG.md
@@ -1,9 +1,12 @@
+[English](../en/CHANGELOG.md) · **简体中文**
+
# Changelog
-Doc revision history for `docs/i18n/zh-CN/`. Most recent first.
+`docs/zh-cn/` 的文档修订历史(2026-09-05 之前位于 `docs/i18n/zh-CN/`)。最近的在前。
| Date | Commit | Change |
| --- | --- | --- |
+| 2026-09-05 | [`eab992f`](https://github.com/tashfeenahmed/freellmapi/commit/eab992f) | docs: 按语言重排为 `docs/zh-cn/`(#1164);补齐幂等、架构索引、Termux、安装总览四页中文;修正索引与锚点 |
| 2026-08-23 | `e82f85f` | docs(i18n): translate logs/ and architecture/ domains to zh-CN |
| 2026-08-23 | [`2331045`](https://github.com/tashfeenahmed/freellmapi/commit/2331045) | docs(providers): add unorouter and xkiro to platform catalog |
| 2026-08-23 | [`453de80`](https://github.com/tashfeenahmed/freellmapi/commit/453de80) | docs(providers): document xkiro 5M tokens/day and unorouter per-min RPM in quotas |
diff --git a/docs/zh-cn/OVERVIEW.md b/docs/zh-cn/OVERVIEW.md
index 1bb701c2..9deae497 100644
--- a/docs/zh-cn/OVERVIEW.md
+++ b/docs/zh-cn/OVERVIEW.md
@@ -1,50 +1,39 @@
-# zh-CN Translations
+[English](../en/OVERVIEW.md) · **简体中文**
-## Scope
+# 文档 —— 简体中文
-Simplified Chinese translations of the core documentation: the pages that cover
-what FreeLLMAPI is, how to install it, and how to call its API. Each file below
-mirrors an English original at the same position in the tree, with
-`docs/i18n/zh-CN/` removed from the path.
+简体中文文档的语言级索引。每个文件都与 `docs/en/` 中同一位置的英文原文一一对应;术语遵循 [../TRANSLATION.md](../TRANSLATION.md) 中约定的中文术语表(提供方、词元、令牌……),与仪表盘界面保持一致。
-Terminology follows the settled zh-CN table in
-[../TRANSLATION.md](../TRANSLATION.md) so these docs and the dashboard UI
-use the same words (提供方, 词元, 令牌, ...).
+## 域
-## File index
-
-| File | Mirrors | Description |
-| --- | --- | --- |
-| [README.md](README.md) | [../../README.md](../../README.md) | Project overview: what the gateway does, supported providers, quick start, and configuration - the full root README in Simplified Chinese. |
-| [../en/README.md](../en/README.md) | [../en/README.md](../en/README.md) | Documentation index page listing every guide in the docs tree. |
-| [docs/install.md](../en/install/01-install.md) | [../../../docs/install.md](../en/install/01-install.md) | Installation guide covering Docker Compose, local setup, and desktop app installs. |
-| [../en/api/01-rest-api.md](../en/api/01-rest-api.md) | [../en/api/01-rest-api.md](../en/api/01-rest-api.md) | API reference for the OpenAI-compatible `/v1` endpoints, authentication, and request formats. |
-
-### Translated domain subtrees
-
-Each folder below mirrors a `docs/` subdomain (OVERVIEW, numbered topic
-docs, CHANGELOG):
-
-| Folder | Mirrors | Contents |
+| 域 | 对应英文 | 说明 |
| --- | --- | --- |
-| [../en/env/](../en/env/OVERVIEW.md) | [../../../../en/env/](../en/env/) | Runtime configuration surface: the full `.env` variable reference, encryption-key handling, and outbound proxy configuration. |
-| [../en/deployment/](../en/deployment/OVERVIEW.md) | [../../../../en/deployment/](../en/deployment/) | Docker operations: image, Compose quickstart, persistence, healthchecks, upgrades, and backups. |
-| [../en/providers/](../en/providers/OVERVIEW.md) | [../../../../en/providers/](../en/providers/) | Provider layer: supported platforms catalog, quotas/cooldowns/key health, and how to add a new provider. |
-| [../en/testing/](../en/testing/OVERVIEW.md) | [../../../../en/testing/](../en/testing/) | Test matrix across workspaces, server suite conventions, and the coding-agent compatibility suite. |
-| [../en/logs/](../en/logs/OVERVIEW.md) | [../../../../en/logs/](../en/logs/) | Live server log viewer in the dashboard: two-tier store, polling API, level counts, clear endpoint, env vars, redaction integration. |
-| [../en/architecture/](../en/architecture/OVERVIEW.md) | [../../../../en/architecture/](../en/architecture/) | Deep-dive server architecture: bandit router, quota/cooldown engine, streaming pipeline, degraded mode, catalog sync, observability. |
-| [../en/cli/](../en/cli/OVERVIEW.md) | [../../../../en/cli/](../en/cli/) | Setup CLI: `setup-*` generators, config-file merge layer, zero-persistence launchers and `doctor`. |
-| [../en/desktop/](../en/desktop/OVERVIEW.md) | [../../../../en/desktop/](../en/desktop/) | Desktop app: Electron shape, file logging and update delivery. |
-| [../en/fallback/](../en/fallback/OVERVIEW.md) | [../../../../en/fallback/](../en/fallback/) | Named fallback chains: lifecycle, `auto:<name>`, catalog-sync backfill. |
-| [../en/glossary/](../en/glossary/OVERVIEW.md) | [../../../../en/glossary/](../en/glossary/) | Glossary of recurring terms: headroom, RPD/TPD, pool key, `auto:<name>`, model-age gate. |
-| [../en/proxy/](../en/proxy/OVERVIEW.md) | [../../../../en/proxy/](../en/proxy/) | Outbound proxy transports: forward vs fetch-relay, system auto-detect. |
-| [../en/troubleshooting/](../en/troubleshooting/OVERVIEW.md) | [../../../../en/troubleshooting/](../en/troubleshooting/) | 常见问题:Docker 容器网络、空链 `400`、fetch-relay 环回防护、幂等 `409`、额度面板、更新检查、密码重置、反向代理 `TRUST_PROXY`。 |
-
-Pages not listed here have no translation yet; they link to their English
-originals by design.
-
-## Navigation
-
-- Up one level: [../OVERVIEW.md](../OVERVIEW.md)
-- Language toggle: every README above links back to
- **[English](../../README.md)** via the centered language bar at the top.
+| [api/](api/OVERVIEW.md) | [en/api/](api/OVERVIEW.md) | API 参考:聊天补全、流式、工具调用、视觉、嵌入、响应头、Anthropic Messages 接口、幂等键。 |
+| [architecture/](architecture/OVERVIEW.md) | [en/architecture/](architecture/OVERVIEW.md) | 架构深入解析:老虎机路由与评分、额度与冷却引擎、流式管线、降级模式与故障转移、目录同步、可观测性。另见 [00-high-level-index.md](architecture/00-high-level-index.md)。 |
+| [cli/](cli/OVERVIEW.md) | [en/cli/](cli/OVERVIEW.md) | 安装 CLI:`setup-*` 生成器、配置文件合并层。 |
+| [clients/](clients/OVERVIEW.md) | [en/clients/](clients/OVERVIEW.md) | 客户端与编程智能体:兼容 OpenAI 的客户端、配置配方、MCP、编辑器补全。 |
+| [compression/](compression/OVERVIEW.md) | [en/compression/](compression/OVERVIEW.md) | 提示词压缩:模式、安全保护、按请求控制、过滤器、统计。 |
+| [deployment/](deployment/OVERVIEW.md) | [en/deployment/](deployment/OVERVIEW.md) | Docker 运维:镜像、Compose、网络、升级、备份。 |
+| [desktop/](desktop/OVERVIEW.md) | [en/desktop/](desktop/OVERVIEW.md) | 桌面应用:Electron 结构、文件日志、更新分发。 |
+| [env/](env/OVERVIEW.md) | [en/env/](env/OVERVIEW.md) | 运行时配置:`.env` 变量、加密密钥、出站代理。 |
+| [fallback/](fallback/OVERVIEW.md) | [en/fallback/](fallback/OVERVIEW.md) | 命名回退链:生命周期、`auto:<name>`、目录同步回填。 |
+| [glossary/](glossary/OVERVIEW.md) | [en/glossary/](glossary/OVERVIEW.md) | 术语表:余量、RPD/TPD、池键、`auto:<name>`、模型年龄闸。 |
+| [install/](install/OVERVIEW.md) | [en/install/](install/OVERVIEW.md) | 安装:快速开始、Docker Compose、本地开发、桌面应用、Termux。 |
+| [logs/](logs/OVERVIEW.md) | [en/logs/](logs/OVERVIEW.md) | 服务器日志查看器:实时面板、两级存储、轮询 API。 |
+| [providers/](providers/OVERVIEW.md) | [en/providers/](providers/OVERVIEW.md) | 提供方集成:支持的平台目录、额度核算、添加新提供方。 |
+| [proxy/](proxy/OVERVIEW.md) | [en/proxy/](proxy/OVERVIEW.md) | 出站代理传输:正向代理与 Fetch Relay、系统自动检测。 |
+| [testing/](testing/OVERVIEW.md) | [en/testing/](testing/OVERVIEW.md) | 测试:本地矩阵、服务端套件、端到端兼容性套件。 |
+| [troubleshooting/](troubleshooting/OVERVIEW.md) | [en/troubleshooting/](troubleshooting/OVERVIEW.md) | 常见问题:Docker、空链、Fetch Relay、幂等、额度、TRUST_PROXY。 |
+| [i18n](../TRANSLATION.md) | — | 翻译流程与术语表 —— 跨语言指南,位于语言目录之外。 |
+
+## 翻译状态
+
+文件集合与英文完全一致:每个英文页面在这里都有同名的中文页面,且所有页面都已有中文内容。少数较长的页面(如 API 参考、安装、出站代理和几篇架构深入解析)在英文原文新增章节后尚未同步,以英文版为准;每个页面页首的语言切换都能直接跳到对应原文。想补齐其中一篇,欢迎提 PR:直接编辑 `docs/zh-cn/` 下的同名文件即可,不要改动文件名或目录结构。
+
+## 其他入口
+
+- [README.md](README.md) —— 中文文档入口页。
+- [../../README.zh-cn.md](../../README.zh-cn.md) —— 项目总览(中文 README)。
+- [../OVERVIEW.md](../OVERVIEW.md) —— `docs/` 目录总索引。
+
+另见:[English](../en/OVERVIEW.md) · [翻译指南](../TRANSLATION.md)
diff --git a/docs/zh-cn/README.md b/docs/zh-cn/README.md
index 02cf107e..63209fdc 100644
--- a/docs/zh-cn/README.md
+++ b/docs/zh-cn/README.md
@@ -2,22 +2,23 @@
# FreeLLMAPI 文档
-根目录的 [README](../en/README.md) 是产品总览,详细指南在这里。
+这里是用户入口 —— 从这里开始安装网关、调用兼容 OpenAI 的 API、接入编程智能体并了解整体架构。根目录的 [README](../../README.zh-cn.md) 是产品总览;这份索引帮你把服务跑起来。
-> **翻译状态:** 「安装与部署」和「API 参考」已翻译成中文。其余三篇指南目前只有英文版,
-> 链接直接指向英文原文。完整状态见 [这里](../en/README.md#status)。想认领其中一篇,欢迎提 PR。
+> **翻译状态:** 所有页面都已有中文版,下面的链接指向中文页面。少数页面在英文原文更新后尚未同步,以英文版为准;每页页首都可切换到英文原文。完整状态见 [翻译状态](OVERVIEW.md#翻译状态)。想补齐其中一篇,欢迎提 PR。
## 指南
-- **[安装与部署](../en/install/01-install.md)** —— 快速开始、Docker Compose、本地开发、声明式启动配置、Docker 镜像、备份、桌面应用,以及你的数据存放在哪里。
+- **[安装与部署](install/01-install.md)** —— 快速开始、Docker Compose、本地开发、声明式启动配置、Docker 镜像、备份、桌面应用、数据存放位置,以及关于密码重置、日志和卸载的常见问题。
- **[API 参考](api/01-rest-api.md)** —— 聊天补全、`auto:*` 路由策略、流式、工具调用、视觉、Gemini 的 Google 搜索接地、嵌入、响应头,以及 Anthropic Messages 接口。
-- **[客户端与编程智能体](../en/clients/01-agent-clients.md)** —— 兼容 OpenAI 的客户端,Claude Code / Codex CLI / Cline / Continue / Aider / opencode / Cursor 的配方,MCP 服务,编辑器补全,以及上下文交接。
-- **[提示词压缩](../en/compression/01-compression-pipeline.md)** —— 请求侧的各种模式、安全保护、按请求的控制项、自定义工具输出过滤器、统计数据和预览 API。
-- **[架构与内部实现](../en/architecture/00-high-level-index.md)** —— 路由器如何工作、路由与运维细节、哪些还不支持、诚实的局限性说明,以及各提供方的服务条款审查。
+- **[客户端与编程智能体](clients/01-agent-clients.md)** —— 兼容 OpenAI 的客户端,Claude Code / Codex CLI / Cline / Continue / Aider / opencode / Cursor 的配方,MCP 服务,编辑器补全,以及上下文交接。
+- **[提示词压缩](compression/01-compression-pipeline.md)** —— 请求侧的各种模式、安全保护、按请求的控制项、自定义工具输出过滤器、统计数据和预览 API。
+- **[代理传输](proxy/OVERVIEW.md)** —— 出站代理传输:正向代理与 Fetch Relay、系统自动检测、入站的 `TRUST_PROXY`;中继协议与 Cloudflare Worker 参考实现见 [Fetch Relay 传输](proxy/01-fetch-relay.md)。
+- **[架构与内部实现](architecture/00-high-level-index.md)** —— 路由器如何工作、路由与运维细节、哪些还不支持、诚实的局限性说明,以及各提供方的服务条款审查。
## 更多
-- [在 Android 上用 Termux 安装](../en/install/02-android-termux.md) —— 实验性的本地安装方式,使用 Node 内置的 SQLite 驱动。
+- [在 Android 上用 Termux 安装](install/02-android-termux.md) —— 实验性的本地安装方式,使用 Node 内置的 SQLite 驱动。
+- [回退链](fallback/01-named-chains.md) —— 命名回退链的生命周期、空链的权威 `400`、`auto:<name>` 路由,以及目录同步回填。
- [Docker 部署](../../docker/README.md) —— 容器配置与持久化存储。
- [桌面应用](../../desktop/README.md) —— 构建和打包 Electron 应用。
- [贡献者指南](../../CONTRIBUTING.md) —— 开发流程、测试要求和贡献政策。
diff --git a/docs/zh-cn/api/01-rest-api.md b/docs/zh-cn/api/01-rest-api.md
index 94f2ce0a..c4cebef5 100644
--- a/docs/zh-cn/api/01-rest-api.md
+++ b/docs/zh-cn/api/01-rest-api.md
@@ -87,7 +87,7 @@ curl http://localhost:3001/v1/chat/completions \
}'
```
-配置档名写错会返回一个明确的 `400`,而不是悄悄退回默认行为。配置档就是具名的回退链(见 [功能](../README.md#功能)),在仪表盘里创建和切换;当前生效的那条就是单写 `auto` 会用的。
+配置档名写错会返回一个明确的 `400`,而不是悄悄退回默认行为。配置档就是具名的回退链(见 [功能](../../../README.zh-cn.md#功能)),在仪表盘里创建和切换;当前生效的那条就是单写 `auto` 会用的。
## 流式输出
diff --git a/docs/zh-cn/api/02-idempotency.md b/docs/zh-cn/api/02-idempotency.md
index 280e098d..80b47dda 100644
--- a/docs/zh-cn/api/02-idempotency.md
+++ b/docs/zh-cn/api/02-idempotency.md
@@ -1,5 +1,193 @@
-# 02-idempotency — 幂等
+[English](../../en/api/02-idempotency.md) · **简体中文**
-> TODO: 翻译待完成 — 参见 [English](../../en/api/02-idempotency.md)
+# Idempotency-Key —— 非流式聊天补全的安全重试
-英文原文在 [`docs/en/api/02-idempotency.md`](../../en/api/02-idempotency.md)。
+> **来源:** `server/src/services/idempotency.ts`、`server/src/routes/proxy.ts:1793-1835`(入口)+ `2640-2656`(持久化)、`server/src/db/migrations/20260901_000001_idempotency_claims.ts`、提交 `36b877d`(功能)、`95bc46f`(在途请求说明),环境变量 `IDEMPOTENCY_TTL_MS` 记录在 `docs/en/env/01-variables.md#idempotency`。
+
+非流式的 `POST /v1/chat/completions` 支持可选的 `Idempotency-Key` 请求头:客户端超时后重试时,不会为一个已经收到过的答案再消耗一次免费额度。在重放窗口内再次看到相同的键与相同的请求内容时,网关以**零提供方成本**重放已存储的响应;相同的键配上不同的内容则返回 `409`,而不是悄悄给出错误答案。
+
+---
+
+## 1. 请求头
+
+在**非流式**请求上发送 `Idempotency-Key`(大小写不敏感 —— Express 会转为小写的 `idempotency-key`):
+
+```
+Idempotency-Key: <opaque client token>
+```
+
+规范化(`server/src/services/idempotency.ts:176-182` 中的 `normalizeIdempotencyKey`):
+
+- 去掉首尾空白;去掉后为空 → 忽略(不启用幂等)。
+- 必须 `≤ 255` 个 UTF-8 字节(`Buffer.byteLength(..., 'utf8')`);更长 → 忽略。
+- 若请求头重复出现,以**第一个**值为准(`Array.isArray(raw) ? raw[0] : raw`),与 Express 的多值处理一致。
+
+只存储键的 `SHA-256` 十六进制摘要(`hashIdempotencyKey`)—— 原始键永远不会进入 SQLite,与管理令牌、运行时令牌的处理方式相同。
+
+流式请求(`stream: true`)**始终绕过**幂等(`proxy.ts:1805` 中的 `const idemKey = !stream ? normalize... : null`)。一个流无法作为整体重放,而打开的连接本身就是重试信号 —— 与响应缓存的策略相同。
+
+---
+
+## 2. 状态 —— `miss` / `replay` / `409 conflict`
+
+`server/src/services/idempotency.ts:91-119` 中的 `lookupIdempotencyReplay(keyHash, fingerprint)` 在 `idempotency_claims` 表中查询同一 `key_hash` 的**未过期**行,并比较其存储的 `request_fingerprint`:
+
+| 结果 | 条件 | 网关行为 |
+|--------|-----------|-----------------|
+| `miss` | 没有满足 `WHERE key_hash = ? AND expires_at_ms > now` 的行,或存储的正文已损坏,或数据库不可用 | 正常继续;若上游随后以 `finish_reason !== 'length'` 成功,则持久化结果供后续重放。 |
+| `replay` | 行存在**且** `request_fingerprint` 匹配 | `X-Routed-Via: idempotency`,原样重放存储的 `response_status` + `response_body`。**不消耗任何提供方额度** —— 与响应缓存 `HIT` 的零成本理由相同,因此跳过请求与用量记账。 |
+| `conflict` | 行存在但指纹不同 | `409` 并返回 `idempotency_key_conflict`(见 §7)—— 调用方用同一个键发送了不同内容。 |
+
+过期的行按 `miss` 处理;同一键的一次新的成功补全会**替换**之前的记录(`storeIdempotencyResult` 中的 `INSERT ... ON CONFLICT(key_hash) DO UPDATE`)。
+
+数据库故障降级为 `miss` —— 幂等是尽力而为,绝不让热路径失败(与 `services/cache.ts` 一致)。
+
+---
+
+## 3. 仅限非流式
+
+- **仅**适用于 `stream` 为假值的 `POST /v1/chat/completions`。流式、`/v1/responses`、`/v1/messages`(Anthropic)、`/v1/completions`、`/v1/embeddings` 以及媒体端点均不覆盖。
+- 被截断的回合(`finish_reason === 'length'`)**不会存储**也不会重放 —— 重放一个被截断的答案比重新生成更糟。这与响应缓存的策略一致(`proxy.ts:2644-2648` 检查 `result.choices?.[0]?.finish_reason !== 'length'`)。
+
+---
+
+## 4. 指纹的构成
+
+`computeIdempotencyFingerprint`(`server/src/services/idempotency.ts:51-70`)对下列字段的 JSON 序列化结果计算规范化的 `SHA-256`,且只包含这些字段:
+
+```typescript
+{
+ model: input.model ?? null,
+ messages: input.messages,
+ temperature: input.temperature ?? null,
+ top_p: input.top_p ?? null,
+ max_tokens: input.max_tokens ?? null,
+ tools: input.tools ?? null,
+ tool_choice: input.tool_choice ?? null,
+}
+```
+
+`model` 原样取自客户端的 `model` 字段(例如 `auto`、`auto:fast`、`gemini-2.5-flash`);`messages` 是经过 `developer`→`system` 规范化后的完整 OpenAI 形态数组。`tools`/`tool_choice` 包含其 schema,因此改变了工具绑定的重试会正确地产生冲突。
+
+取默认值的采样参数会被规范化(缺省时为 `null`),所以 `top_p: 1` 与省略 `top_p` 不会为同一个逻辑请求产生两个指纹 —— 与缓存键 `v4` 一致。
+
+---
+
+## 5. 在途请求**不会**去重(95bc46f)
+
+在原请求仍在执行时到达的重复请求**不会被合并**:
+
+> 只有**已完成**的响应才可被记录。若两个请求以相同的键与指纹竞争,两者都会执行到底;第二次 `storeIdempotencyResult` 会替换第一次。之后第三个重复该键的请求将重放胜出者。
+
+要守住在途窗口,需要一个带有自身短 TTL 的 `pending` 记录状态,以免崩溃把一个键卡住 24 小时。这被**有意排除在范围之外**(提交 `95bc46f`,`server/src/services/idempotency.ts:17-20`)。需要更强去重的调用方,应等到第一个请求返回或客户端自己的超时触发后再重试。
+
+---
+
+## 6. TTL —— `IDEMPOTENCY_TTL_MS`
+
+| 变量 | 默认值 | 含义 |
+|----------|---------|---------|
+| `IDEMPOTENCY_TTL_MS` | `86400000`(24 小时) | 已完成记录的重放窗口 |
+
+- 通过 `idempotencyTtlMs()` → `envNum('IDEMPOTENCY_TTL_MS', 24*60*60*1000)` **每次调用时**读取,便于测试实时切换;非有限值或负数 → 回退到默认值。
+- `expires_at_ms = now + ttl`;过期行在下一次 `storeIdempotencyResult` 时**按 `key_hash`** 惰性清理(`DELETE ... WHERE key_hash = ? AND expires_at_ms <= ?`),范围扫描则借助 `idx_idempotency_claims_expires` 索引。
+- 权威来源:`server/src/services/idempotency.ts:40-42`、`docs/en/env/01-variables.md#idempotency`。
+
+---
+
+## 7. 409 处理 —— `idempotency_key_conflict`
+
+用同一个键重发**不同**的 `model`/`messages`/采样参数/`tools` 会得到 `409 Conflict`(在调用任何提供方之前):
+
+```json
+HTTP/1.1 409 Conflict
+Content-Type: application/json
+
+{
+ "error": {
+ "message": "idempotency_key_conflict",
+ "type": "invalid_request_error"
+ }
+}
+```
+
+客户端的恢复方式:
+
+1. 为真正的新内容生成一个**新的** `Idempotency-Key`,或
+2. 逐字节重发**原始**请求体以获得重放。
+
+`409` 不消耗任何提供方额度 —— 它直接由查询返回(`proxy.ts:1827-1835`)。把它当作程序错误处理,而不是可重试的状态码。
+
+---
+
+## 8. curl 示例 —— 超时、重试、重放
+
+```bash
+# 1. First attempt — times out on the client side, but the gateway
+# finishes and stores the response under the key hash.
+curl -X POST http://localhost:3001/v1/chat/completions \
+ -H "Authorization: Bearer freellmapi-your-unified-key" \
+ -H "Content-Type: application/json" \
+ -H "Idempotency-Key: 7f3a-2026-09-02-retry-1" \
+ -d '{
+ "model": "auto",
+ "messages": [{"role": "user", "content": "Summarise the fall of Rome in one sentence."}]
+ }' --max-time 10 || echo "client timed out"
+
+# 2. Retry with the SAME key + SAME body → replay, zero provider cost
+curl -i http://localhost:3001/v1/chat/completions \
+ -H "Authorization: Bearer freellmapi-your-unified-key" \
+ -H "Content-Type: application/json" \
+ -H "Idempotency-Key: 7f3a-2026-09-02-retry-1" \
+ -d '{
+ "model": "auto",
+ "messages": [{"role": "user", "content": "Summarise the fall of Rome in one sentence."}]
+ }'
+# Response headers include: X-Routed-Via: idempotency
+# Body is the exact JSON from the first success, including usage/model fields.
+
+# 3. Same key with DIFFERENT content → 409
+curl -i http://localhost:3001/v1/chat/completions \
+ -H "Authorization: Bearer freellmapi-your-unified-key" \
+ -H "Content-Type: application/json" \
+ -H "Idempotency-Key: 7f3a-2026-09-02-retry-1" \
+ -d '{
+ "model": "auto",
+ "messages": [{"role": "user", "content": "Different question"}]
+ }'
+# → 409 {"error":{"message":"idempotency_key_conflict","type":"invalid_request_error"}}
+```
+
+提示:
+
+- 每个逻辑操作使用一个 **UUID v4** 或 KSUID;不要在不相关的调用之间复用键。
+- 超时正是预期的使用场景 —— 把客户端超时设得比网关的提供方预算短,重试才真的会触发。
+- 重放可通过 `X-Routed-Via: idempotency` 识别(正常命中是 `X-Routed-Via: <platform>/<model>`);缓存命中则是 `X-FreeLLM-Cache: HIT`。
+
+---
+
+## 9. 存储与成本模型
+
+| 方面 | 细节 |
+|--------|--------|
+| 表 | `idempotency_claims`(`id`、`key_hash UNIQUE`、`request_fingerprint`、`response_status`、`response_body TEXT`、`execution_id`、`created_at_ms`、`expires_at_ms`)—— 迁移 `20260901_000001_idempotency_claims.ts` |
+| 索引 | `idx_idempotency_claims_expires ON expires_at_ms` |
+| 成本 | 重放 = **零提供方密钥/额度**,不产生 `requests`/`request_attempts` 行,与缓存 `HIT` 相同 |
+| 作用域 | 按调用方的键(键由调用方控制),不同于响应缓存对请求内容做全局精确匹配 |
+| 语义 | 每个 `key_hash` 一行;新的成功补全会**替换**旧的(指纹与正文一并覆盖) |
+
+---
+
+## 10. 与响应缓存及降级模式的关系
+
+- **响应缓存**(`services/cache.ts`,`X-FreeLLM-Cache`)是正交的:全局、受温度门控、内存 LRU;幂等则是持久化的(SQLite)、按调用方、与指纹绑定。两者都会绕过提供方调用。
+- **降级模式**(`../architecture/04-degraded-mode-and-failover.md`)会关闭老虎机探索,但不影响幂等 —— 重放仍然完全绕过路由。
+- **故障转移**:只存储最终成功的正文。若一个请求耗尽了回退循环,该键不会存储任何内容。
+
+---
+
+## 相关
+
+- `docs/en/env/01-variables.md#idempotency` —— `IDEMPOTENCY_TTL_MS` 的默认值与边界。
+- [`../architecture/04-degraded-mode-and-failover.md`](../architecture/04-degraded-mode-and-failover.md) —— `miss` 进入循环后适用的重试预算、对冲和回退响应头。
+- [`01-rest-api.md`](01-rest-api.md) —— 兼容 OpenAI 的接口(`/v1/chat/completions`)与响应头(`X-Routed-Via`、`X-Fallback-Detail`)。
diff --git a/docs/zh-cn/architecture/00-high-level-index.md b/docs/zh-cn/architecture/00-high-level-index.md
index 0528231e..9d90cfef 100644
--- a/docs/zh-cn/architecture/00-high-level-index.md
+++ b/docs/zh-cn/architecture/00-high-level-index.md
@@ -1,5 +1,98 @@
-# 00-high-level-index — 高层索引
+[English](../../en/architecture/00-high-level-index.md) · **简体中文**
-> TODO: 翻译待完成 — 参见 [English](../../en/architecture/00-high-level-index.md)
+# 架构与内部实现
-英文原文在 [`docs/en/architecture/00-high-level-index.md`](../../en/architecture/00-high-level-index.md)。
+[← 返回 README](../../../README.zh-cn.md) · [文档索引](../README.md) · [深入解析域](OVERVIEW.md)
+
+FreeLLMAPI 是一个自托管的、兼容 OpenAI 的网关,把约 34 家提供方的免费额度叠加在一个 `freellmapi-…` Bearer 令牌之后。一个 Express 代理暴露 `/v1/chat/completions`(以及 `/v1/responses`、`/v1/messages`、`/v1/completions`、`/v1/embeddings` 和 `/v1/models`);每次请求时,路由器挑选一个状态健康、且未触及任何限流的最佳模型,在内存中解密其上游密钥,再把响应流式传回。
+
+没有哪一家的免费额度足以单独支撑日常使用,所以路由器把目录当作一条汇聚的回退链来对待:通过 Thompson 采样的老虎机算法实时评估可靠性、速度、能力和余量,用持久化账本执行 RPM/RPD/TPM/TPD 与提供方级上限,并在墙钟预算内跨最多 20 次尝试进行故障转移。当链路顶端的模型耗尽当日额度时,端点会平滑降级到下一档健康模型,并在 UTC 午夜重置。
+
+深入解析见 [OVERVIEW.md](OVERVIEW.md)。
+
+- [工作原理](#工作原理)
+- [尚不支持](#尚不支持)
+- [局限性](#局限性)
+- [服务条款审查](#服务条款审查)
+
+## 工作原理
+
+![一个请求进来,最好的免费模型出去 —— 带实时评分、冷却和额度追踪的回退链](../../../repo-assets/router-flow.png)
+
+```
+┌──────────────────┐ Bearer freellmapi-… ┌─────────────────────────┐
+│ OpenAI SDK / │ ──────────────────────▶ │ Express proxy (:3001) │
+│ curl / any │ ◀────────────────────── │ /v1/chat/completions │
+│ OpenAI client │ streamed tokens └────────────┬────────────┘
+└──────────────────┘ │
+ ▼
+ ┌────────────────────────────────────────────────┐
+ │ Router │
+ │ 1. Pick highest-priority model that │
+ │ (a) has a healthy key and │
+ │ (b) is under all its rate limits. │
+ │ 2. Decrypt key, call provider SDK. │
+ │ 3. On 429/5xx → cooldown + retry next model. │
+ └────────────────────────────────────────────────┘
+ │
+ ┌──────────────┬────────────┬──────────┴─────────┬─────────────┬──────────┐
+ ▼ ▼ ▼ ▼ ▼ ▼
+ Google Groq Cerebras OpenRouter HF …29 more
+```
+
+- **路由器**(`server/src/services/router.ts`)—— 为每次请求挑选模型。
+- **限流账本**(`server/src/services/ratelimit.ts`)—— 由 SQLite 支撑的内存 RPM/RPD/TPM/TPD 计数器,遇到 429 时设置冷却。
+- **提供方适配器**(`server/src/providers/*.ts`)—— 每个提供方一个文件,实现 `Provider` 基类的 `chatCompletion()` 与 `streamChatCompletion()`。
+- **健康服务**(`server/src/services/health.ts`)—— 周期性探测,保持密钥状态最新。
+- **仪表盘**(`client/`)—— 基于 React + Vite + shadcn/ui 的管理界面。
+- **存储** —— SQLite(`better-sqlite3`),密钥使用 AES-256-GCM 信封加密。
+- **工具调用救援**(`server/src/lib/tool-call-rescue.ts`)—— 把工具调用以纯文本而非结构化 JSON 输出的模型,其输出会被自动恢复为真正的 `tool_calls`;带工具的请求只会路由到确实支持工具的模型。
+- **密钥导入与导出** —— 粘贴 `.env` 文件即可批量导入密钥(带预览与逐条选择),也可导出为 JSON、`.env` 或 CSV。
+
+> 路由策略、老虎机评分、额度与冷却核算、流式传输、降级模式故障转移以及提供方目录,在深入解析中有实现层面的说明 —— 见 [OVERVIEW.md](OVERVIEW.md)。
+
+## 尚不支持
+
+范围是有意收窄的。如果某个功能既不在 README 的功能列表里,也不在下面,请默认它还不存在。
+
+- **内容审核**(`/v1/moderations`)
+- **`n > 1`**(单次请求返回多个补全)
+- **按用户计费 / 多租户鉴权** —— 设计上就是单用户
+
+非常欢迎添加上述任一功能的 PR。见[参与贡献](../../../README.zh-cn.md#参与贡献)。
+
+## 局限性
+
+叠加免费额度有实实在在的取舍,请对此保持诚实:
+
+- **天花板是额度和可用性,不是模型级别。** 目录里确实有前沿级的条目 —— GPT-5.x、Grok 4.x、Kimi K3、DeepSeek V4 Pro、Gemini 3.x 都会出现在某家的免费额度里。你得不到的是对它们的*持续*访问:恰恰是这些条目日额度最小、排队最长、最可能在短时间内被下线或转为收费。请按容量和可用时间做预算,而不是按能力上限。
+- **智能程度会随一天的推进而下降。** 排名最高的模型(通常是 Gemini 3.6 Flash、DeepSeek V4、Kimi K2.6)日额度最低。它们触顶后,路由器会顺着优先级链退到更小、更弱的模型。预期端点的有效智能在每天的后半段下降,然后在 UTC 午夜重置。
+- **延迟波动很大。** Cerebras 和 Groq 极快,其他的则未必。你拿到的是当下可用的那一个。
+- **免费额度可能不打招呼就变。** 提供方经常收紧、放宽或取消免费额度。发生时你会看到 429 或鉴权错误,直到目录更新送达 —— 实时源安装几天内就能收到修复,免费安装则跟随 30 天延迟。重新播种脚本在 `server/src/scripts/`。
+- **根据定义,没有 SLA。** 需要可靠性就用有合同的付费提供方。
+- **本地优先。** 没有多租户鉴权。只给自己用,不要暴露到公网。
+
+## 服务条款审查
+
+针对自托管、单用户、个人使用的场景,逐一重新审阅了各提供方的服务条款(2026 年 5 月)。摘要:
+
+| 提供方 | 结论 | 说明 |
+|---|---|---|
+| Google Gemini | ⚠️ 谨慎 | 2026 年 3 月的条款把范围收窄为*“专业或商业用途,而非消费者使用”* —— 自托管的开发者代理仍可辩护,但这是新条款。 |
+| Groq | ✅ 大概率可以 | GroqCloud 服务协议允许集成到客户应用中。 |
+| Cerebras | ✅ 大概率可以 | 允许;明确禁止出售或转让 API 密钥。 |
+| Mistral | ✅ 大概率可以 | API 允许用于个人或内部业务用途。 |
+| OpenRouter | ✅ 大概率可以 | 2026 年 4 月的条款强化了禁止转售、禁止竞争性服务的条款;私有单用户代理仍然没问题。 |
+| Cloudflare Workers AI | ⚠️ 模糊 | 没有反代理条款;受通用的自助订阅协议约束。 |
+| NVIDIA NIM | ⚠️ 谨慎 | 试用条款 §1.2 / §1.4:*“仅供评估,不用于生产。”* 免费访问是持续的 40 RPM 限流(2025 年的积分制已停止),但仅供评估的范围依然有效。 |
+| GitHub Models | ⚠️ 谨慎 | 免费层明确限定为*“实验”*和*“原型验证”*。 |
+| Cohere | ❌ 避免 | 条款 §14 仍禁止*“个人、家庭或家用目的”*。 |
+| 智谱(open.bigmodel.cn) | ✅ 大概率可以 | 平台文档中仍保留个人、非商业研究的豁免。 |
+| Z.ai(api.z.ai) | ⚠️ 谨慎 | 新条目 —— 新加坡实体(与智谱中国不同)。§III.3(l) 的反流量重定向条款有可能被解读为针对代理;没有明确的个人使用豁免。 |
+| Ollama Cloud | ✅ 大概率可以 | 新条目 —— 免费计划允许访问云端模型(1 个并发,5 小时会话上限)。未发现反代理或反转售条款。*(集成见 #14。)* |
+| OVH AI Endpoints | ✅ 大概率可以 | 新条目(2026 年 6 月)—— 匿名访问有官方文档(每 IP 每模型 2 次/分钟)。OVH 保留引入词元或消耗上限的权利。 |
+| AI Horde | ✅ 大概率可以 | 新条目(2026 年 6 月)—— 由 Haidra 非营利组织运营的免费社区公共资源;官方支持匿名使用(密钥 `0000000000`,队列优先级最低)。没有反代理或反转售条款。OpenAI 代理是试点,可能按用量受限。*(集成 #345。)* |
+
+让大多数提供方满意的经验法则:**每家提供方一个账号**、**不转售**、**不与他人共享你的端点**、**不要把免费额度当付费生产后端来狂刷**。以上仅供参考,不构成法律意见 —— 请阅读各提供方的条款并自行判断。
+
+自 2026 年 4 月的审查以来已移除:Moonshot 和 MiniMax 的直接集成已从目录中删除(Moonshot 转为仅付费;MiniMax 被 OpenRouter 的 `minimax/minimax-m2.5:free` 路由取代)。
diff --git a/docs/zh-cn/architecture/OVERVIEW.md b/docs/zh-cn/architecture/OVERVIEW.md
index bd43e0ae..0ccd2475 100644
--- a/docs/zh-cn/architecture/OVERVIEW.md
+++ b/docs/zh-cn/architecture/OVERVIEW.md
@@ -2,7 +2,7 @@
# 架构域 —— 概览与文件索引
-本目录包含 FreeLLMAPI 服务端架构的深度文档。根目录的 [`architecture.md`](../../en/architecture/00-high-level-index.md) 仍是高层索引;这些文件把各子系统展开并给出实现细节。
+本目录包含 FreeLLMAPI 服务端架构的深度文档。根目录的 [`architecture.md`](00-high-level-index.md) 仍是高层索引;这些文件把各子系统展开并给出实现细节。
## 文件索引
@@ -19,4 +19,4 @@
## 导航
- ← [文档根目录](../README.md)
-- ↑ [高层架构索引](../../en/architecture/00-high-level-index.md)
\ No newline at end of file
+- ↑ [高层架构索引](00-high-level-index.md)
\ No newline at end of file
diff --git a/docs/zh-cn/cli/02-config-files.md b/docs/zh-cn/cli/02-config-files.md
index 0e52f6d4..b5ac6ba6 100644
--- a/docs/zh-cn/cli/02-config-files.md
+++ b/docs/zh-cn/cli/02-config-files.md
@@ -31,7 +31,7 @@
1. 在 `cli/tools.json` 中新增条目(`id`、`name`、`category`、`configType`、`protocol`、`baseUrlSupport`、`command`、`docsUrl`)。
2. 在 `cli/src/tools.ts` 中新增 `function myTool(ctx: GenerateContext): Generation` —— 返回正确的 `path`/`format`/`value` 的 `files` 以及供 CLI 输出的 `notes`。使用辅助函数 `rootUrl()`/`v1Url()`/`primaryModel()`/`contextWindow()`。
3. 在 `cli/src/tools.test.ts` 中新增快照用例。
-4. 在 [01-generators.md](01-generators.md) 表格与 `docs/clients/01-agent-clients.md` 章节中补充文档。
+4. 在 [01-generators.md](01-generators.md) 表格与 `docs/en/clients/01-agent-clients.md` 章节中补充文档。
5. 若仪表盘会列出它,需同步 `client/src/data/agent-tools.json`。
## 相关
diff --git a/docs/zh-cn/deployment/01-docker.md b/docs/zh-cn/deployment/01-docker.md
index 42f6170b..c54ad4ce 100644
--- a/docs/zh-cn/deployment/01-docker.md
+++ b/docs/zh-cn/deployment/01-docker.md
@@ -46,7 +46,7 @@ printf "ENCRYPTION_KEY=%s\nPORT=3001\n" "$ENCRYPTION_KEY" > .env
docker compose up -d
```
-Windows PowerShell 版本和 curl 一行命令引导见 [`docs/install.md`](../../en/install/01-install.md#docker-compose)。然后跟踪日志:
+Windows PowerShell 版本和 curl 一行命令引导见 [`docs/install.md`](../install/01-install.md#docker-compose)。然后跟踪日志:
```bash
docker compose logs -f freellmapi
@@ -97,7 +97,7 @@ runtime 阶段在 `EXPOSE 3001` 之前切换到 `USER node`。服务器数据目
宿主机一切正常,容器里的提供方却不可达?容器有自己独立的网络栈,有两件在你机器上顺理成章的事不会自动延续过去:
-- **`127.0.0.1` 上的代理不是你的机器。** 在容器内部,环回地址指容器自己。如果你经由宿主机上的代理客户端(Clash、v2rayN、sing-box 或公司代理)访问提供方,就让 FreeLLMAPI 指向宿主机:`PROXY_URL=socks5h://host.docker.internal:7890`。随附的 `docker-compose.yml` 通过 `extra_hosts` 把 `host.docker.internal` 映射到宿主机网关,所以在原生 Linux Docker 上和 Docker Desktop 里都可用。代理还得接受来自环回之外的连接(在 Clash 里是 `allow-lan: true`)。更多细节见 [../env/03-outbound-proxies.md](../env/03-outbound-proxies.md#docker-127001-指的是容器)。
+- **`127.0.0.1` 上的代理不是你的机器。** 在容器内部,环回地址指容器自己。如果你经由宿主机上的代理客户端(Clash、v2rayN、sing-box 或公司代理)访问提供方,就让 FreeLLMAPI 指向宿主机:`PROXY_URL=socks5h://host.docker.internal:7890`。随附的 `docker-compose.yml` 通过 `extra_hosts` 把 `host.docker.internal` 映射到宿主机网关,所以在原生 Linux Docker 上和 Docker Desktop 里都可用。代理还得接受来自环回之外的连接(在 Clash 里是 `allow-lan: true`)。更多细节见 [../env/03-outbound-proxies.md](../env/03-outbound-proxies.md#docker127001-指的是容器)。
- **纯 IPv6 的宿主机需要在 Docker 里启用 IPv6。** 默认桥接网络只有 IPv4,所以在没有 IPv4 路由的主机上容器什么都够不着,DNS 也一样。在 `/etc/docker/daemon.json` 中以 `"ipv6": true`、`"ip6tables": true` 和一段 `"fixed-cidr-v6"` 网段启用,然后重启 Docker。
想分辨自己撞上的是哪种情况,直接问容器本身:
diff --git a/docs/zh-cn/deployment/CHANGELOG.md b/docs/zh-cn/deployment/CHANGELOG.md
index 59e9bbf0..d75079d8 100644
--- a/docs/zh-cn/deployment/CHANGELOG.md
+++ b/docs/zh-cn/deployment/CHANGELOG.md
@@ -1,3 +1,5 @@
+[English](../../en/deployment/CHANGELOG.md) · **简体中文**
+
# 变更记录
`docs/deployment/` 的修订历史,列出塑造了本文档所述 Docker 运维与维护行为的提交。最新在前。
diff --git a/docs/zh-cn/deployment/OVERVIEW.md b/docs/zh-cn/deployment/OVERVIEW.md
index 4e1dd223..ef45aef5 100644
--- a/docs/zh-cn/deployment/OVERVIEW.md
+++ b/docs/zh-cn/deployment/OVERVIEW.md
@@ -4,9 +4,9 @@
## 范围
-在 Docker 中运营 FreeLLMAPI:已发布的镜像、Compose 快速开始、持久化、健康检查、容器网络坑点,以及日常维护工作——升级、备份和声明式配置。内容取材自 [`Dockerfile`](../../../Dockerfile)、[`docker-compose.yml`](../../../docker-compose.yml)、[`.dockerignore`](../../../.dockerignore) 与 [`docs/install.md`](../../en/install/01-install.md)。
+在 Docker 中运营 FreeLLMAPI:已发布的镜像、Compose 快速开始、持久化、健康检查、容器网络坑点,以及日常维护工作——升级、备份和声明式配置。内容取材自 [`Dockerfile`](../../../Dockerfile)、[`docker-compose.yml`](../../../docker-compose.yml)、[`.dockerignore`](../../../.dockerignore) 与 [`docs/install.md`](../install/01-install.md)。
-Docker 之外的安装路径(一行命令脚本、本地开发、桌面应用)见「[安装与部署](../../en/install/01-install.md)」。
+Docker 之外的安装路径(一行命令脚本、本地开发、桌面应用)见「[安装与部署](../install/01-install.md)」。
## 文件索引
diff --git a/docs/zh-cn/env/03-outbound-proxies.md b/docs/zh-cn/env/03-outbound-proxies.md
index a0bd33b9..9f5d2485 100644
--- a/docs/zh-cn/env/03-outbound-proxies.md
+++ b/docs/zh-cn/env/03-outbound-proxies.md
@@ -4,12 +4,12 @@
FreeLLMAPI 如何把发往提供方的流量经由代理转发、多个变量同时设置时谁说了算,以及随之而来的 Docker 网络坑点。
-来源:[`.env.example`](../../../.env.example)(代理配置块)、[`docker-compose.yml`](../../../docker-compose.yml),以及 [`docs/install.md`](../../en/install/01-install.md) 中的容器网络说明。
+来源:[`.env.example`](../../../.env.example)(代理配置块)、[`docker-compose.yml`](../../../docker-compose.yml),以及 [`docs/install.md`](../install/01-install.md) 中的容器网络说明。
- [代理链优先级](#代理链优先级)
- [协议支持](#协议支持)
- [`NO_PROXY` 直连豁免](#no_proxy-直连豁免)
-- [Docker:`127.0.0.1` 指的是容器](#docker-127001-指的是容器)
+- [Docker:`127.0.0.1` 指的是容器](#docker127001-指的是容器)
- [相关的入站限流旋钮](#相关的入站限流旋钮)
## 代理链优先级
diff --git a/docs/zh-cn/env/CHANGELOG.md b/docs/zh-cn/env/CHANGELOG.md
index 4d8051e8..fae34b97 100644
--- a/docs/zh-cn/env/CHANGELOG.md
+++ b/docs/zh-cn/env/CHANGELOG.md
@@ -1,3 +1,5 @@
+[English](../../en/env/CHANGELOG.md) · **简体中文**
+
# 变更记录
`docs/env/` 的修订历史,列出塑造了本文档所述运行时配置面的提交。最新在前。
diff --git a/docs/zh-cn/env/OVERVIEW.md b/docs/zh-cn/env/OVERVIEW.md
index d7449f66..a721b9c3 100644
--- a/docs/zh-cn/env/OVERVIEW.md
+++ b/docs/zh-cn/env/OVERVIEW.md
@@ -6,7 +6,7 @@
本域文档描述 FreeLLMAPI 的运行时配置面:服务器从 `.env` 读取的每一个变量、提供方 API 密钥如何静态加密存储,以及出站流量如何经由代理转发。唯一的权威来源是仓库根目录的 [`.env.example`](../../../.env.example);这里的参考内容均由它(及其描述的代码路径)推导而来,绝不编造取值。
-如果是第一次把安装跑起来,请看[安装与部署](../../en/install/01-install.md)。
+如果是第一次把安装跑起来,请看[安装与部署](../install/01-install.md)。
## 文件索引
diff --git a/docs/zh-cn/install/01-install.md b/docs/zh-cn/install/01-install.md
index 48026aac..f2ae7603 100644
--- a/docs/zh-cn/install/01-install.md
+++ b/docs/zh-cn/install/01-install.md
@@ -2,7 +2,7 @@
# 安装与部署
-[← 返回 README](../../en/README.md) · [文档索引](../../en/README.md)
+[← 返回 README](../README.md) · [文档索引](../README.md)
把 FreeLLMAPI 跑起来所需的一切:一行命令、Docker Compose、本地开发、声明式配置、生产构建、桌面应用,以及你的数据存放在哪里。
@@ -26,7 +26,7 @@ curl -fsSL https://freellmapi.co/install.sh | bash
在 Windows 上,最省事的方式是桌面版 **[Releases 里的 `.exe` 安装包](https://github.com/tashfeenahmed/freellmapi/releases/latest)**(见[下文](#桌面应用));上面的 Docker 步骤在 WSL 或任意 bash shell 里同样可用。
-在 Android 上,参见实验性的 [Termux 安装指南](../../en/install/02-android-termux.md)。它使用 Node 内置的 SQLite 驱动,不需要 Android NDK。
+在 Android 上,参见实验性的 [Termux 安装指南](02-android-termux.md)。它使用 Node 内置的 SQLite 驱动,不需要 Android NDK。
打开 http://localhost:3001 ,在 **密钥** 页添加你的提供方密钥,按喜好调整 **回退链** 的顺序,然后在 **密钥** 页顶部拿到你的统一 API 密钥。这个统一密钥就是你的 OpenAI SDK 要指向的东西。
@@ -239,7 +239,7 @@ npm run desktop:dist:win # Windows → "desktop/dist-electron/FreeLLMAPI Se
```
> 本地构建出来的应用没有签名,所以 Windows SmartScreen 首次运行时可能会警告(点「更多信息」→「仍要运行」);macOS 构建则不会触发 Gatekeeper 提示。
-> 完整说明见 [desktop/../../en/README.md](../../en/desktop/../../en/README.md)。
+> 完整说明见 [desktop/../../en/README.md](../README.md)。
## 凭据与数据存放位置
diff --git a/docs/zh-cn/install/02-android-termux.md b/docs/zh-cn/install/02-android-termux.md
index b5253a4e..7aad1d78 100644
--- a/docs/zh-cn/install/02-android-termux.md
+++ b/docs/zh-cn/install/02-android-termux.md
@@ -1,5 +1,112 @@
-# 02-android-termux — Termux
+[English](../../en/install/02-android-termux.md) · **简体中文**
-> TODO: 翻译待完成 — 参见 [English](../../en/install/02-android-termux.md)
+# Android(Termux)安装
-英文原文在 [`docs/en/install/02-android-termux.md`](../../en/install/02-android-termux.md)。
+> 实验性功能,由社区维护。FreeLLMAPI 直接运行在 Android 设备本地。
+
+FreeLLMAPI 可以在 [Termux](https://termux.dev/) 中运行,无需 Android NDK 工具链。在 Android 上,服务器使用 Node 内置的 SQLite 驱动,而不是原生的 `better-sqlite3` 包。
+
+## 要求
+
+- Android 7 或更新版本
+- 约 1 GB 可用存储空间
+- [F-Droid 上的 Termux](https://f-droid.org/packages/com.termux/)(Play 商店的版本已过时)
+- Node.js 22.13 或更新版本;推荐 Node 24 LTS
+
+不要混用来自不同商店的 Termux 或其附加包。
+
+## 安装
+
+更新 Termux 并安装所需的包:
+
+```bash
+pkg update
+pkg upgrade -y
+pkg install -y nodejs-lts git
+```
+
+确认 Node 的版本足够新,能提供 `node:sqlite`:
+
+```bash
+node --version
+```
+
+然后克隆并启动 FreeLLMAPI:
+
+```bash
+git clone https://github.com/tashfeenahmed/freellmapi.git
+cd freellmapi
+npm install --no-audit --no-fund
+npm run dev
+```
+
+安装时关于可选包 `better-sqlite3` 的警告在 Android 上无害。如果 npm 要求批准依赖的安装脚本,批准 `esbuild` 的脚本后再运行一次 `npm install`。
+
+在手机浏览器中打开 `http://localhost:5173`。API 位于 `http://localhost:3001/v1`。
+
+## 从其他设备访问
+
+仪表盘包含 API 密钥和管理控制项,只在可信网络中暴露它。
+
+```bash
+HOST=0.0.0.0 npm run dev:lan
+```
+
+在 Android 的 Wi-Fi 设置中查看手机的局域网地址,或运行:
+
+```bash
+ip addr show wlan0
+```
+
+在同一网络的另一台设备上打开 `http://PHONE_IP:5173`。不要把这些开发服务器直接端口转发到公网;需要远程访问时请使用 Tailscale 之类的私有 VPN。
+
+## 保持进程运行
+
+屏幕关闭后 Android 可能会挂起 Termux。从与 Termux 相同的商店安装 Termux:API 附加组件,然后运行:
+
+```bash
+pkg install -y termux-api
+termux-wake-lock
+```
+
+停止服务器后释放唤醒锁:
+
+```bash
+termux-wake-unlock
+```
+
+## 故障排查
+
+### `node:sqlite` 不可用
+
+升级 Termux 的包,并确认 `node --version` 报告 22.13 或更新版本:
+
+```bash
+pkg update
+pkg upgrade -y
+pkg install -y nodejs-lts
+```
+
+### `concurrently: not found`
+
+依赖安装没有完成。再运行一次 `npm install --no-audit --no-fund`,并处理它报告的第一个非可选错误。
+
+### 端口已被占用
+
+停止占用 3001 或 5173 端口的进程,或在仓库的 `.env` 文件中配置另一个 `PORT`。
+
+### 屏幕关闭后进程停止
+
+使用 `termux-wake-lock`,并在 Android 设置中为 Termux 关闭电池优化。
+
+## 更新
+
+先停止正在运行的开发服务器,然后运行:
+
+```bash
+git pull --ff-only
+npm install --no-audit --no-fund
+npm run dev
+```
+
+反馈 Android 相关问题时,请附上 Android 版本、Termux 的来源与版本、设备架构、`node --version` 的输出以及完整的错误信息。
diff --git a/docs/zh-cn/install/CHANGELOG.md b/docs/zh-cn/install/CHANGELOG.md
index fb7f987c..4c3aca36 100644
--- a/docs/zh-cn/install/CHANGELOG.md
+++ b/docs/zh-cn/install/CHANGELOG.md
@@ -1,3 +1,5 @@
+[English](../../en/install/CHANGELOG.md) · **简体中文**
+
# Changelog — install (zh-cn)
| Commit | Date | Summary |
diff --git a/docs/zh-cn/install/OVERVIEW.md b/docs/zh-cn/install/OVERVIEW.md
index 5e0dee45..347e35e0 100644
--- a/docs/zh-cn/install/OVERVIEW.md
+++ b/docs/zh-cn/install/OVERVIEW.md
@@ -1,3 +1,16 @@
-# install — 占位
+[English](../../en/install/OVERVIEW.md) · **简体中文**
-> TODO: 翻译待完成 — 参见 [English](../../en/install/OVERVIEW.md)
+# 安装指南总览
+
+## 范围
+
+本域涵盖 FreeLLMAPI 的全部安装路径:标准路径与特定平台的路径。
+
+先看[安装与部署](01-install.md)了解标准路径:一行命令的 Docker 快速开始、Docker Compose、本地开发、声明式启动配置、Docker 镜像以及桌面应用。下面的指南面向不常见的平台或设备形态。
+
+## 指南
+
+| 文件 | 说明 |
+| --- | --- |
+| [01-install.md](01-install.md) | 安装与部署:一行命令快速开始、Docker Compose、本地开发、声明式启动配置、Docker 镜像、桌面应用,以及数据存放位置。 |
+| [02-android-termux.md](02-android-termux.md) | 实验性的 Android(Termux)安装:在设备本地运行,使用 Node 内置的 SQLite 驱动而非 `better-sqlite3`(无需 NDK 工具链)。涵盖要求(Android 7+、Node 22.13+)、安装与局域网访问、用唤醒锁保持进程运行、故障排查与更新。 |
diff --git a/docs/zh-cn/providers/CHANGELOG.md b/docs/zh-cn/providers/CHANGELOG.md
index f9011b26..2124753d 100644
--- a/docs/zh-cn/providers/CHANGELOG.md
+++ b/docs/zh-cn/providers/CHANGELOG.md
@@ -1,3 +1,5 @@
+[English](../../en/providers/CHANGELOG.md) · **简体中文**
+
# 变更记录
`docs/providers/` 的修订历史,列出塑造了本文档所述提供方层的上游提交。最新在前。
diff --git a/docs/zh-cn/providers/OVERVIEW.md b/docs/zh-cn/providers/OVERVIEW.md
index efdaba88..5143b53c 100644
--- a/docs/zh-cn/providers/OVERVIEW.md
+++ b/docs/zh-cn/providers/OVERVIEW.md
@@ -6,7 +6,7 @@
本域文档描述 FreeLLMAPI 的提供方层:网关聚合了哪些平台、每个平台如何鉴权和适配,以及按密钥的额度记账、冷却和健康检查如何让各家免费额度在同一个 OpenAI 兼容 API 之下保持可用。
-权威来源是 [`shared/types.ts`](../../../shared/types.ts)(`Platform` 联合类型)、[`server/src/providers/index.ts`](../../../server/src/providers/index.ts)(运行时注册表)和 [`server/src/providers/base.ts`](../../../server/src/providers/base.ts)(适配器契约)。公开目录的招牌数字——约 29 家免费提供方、251 个模型系列、358 个免费端点(约合每月 40 亿词元的在册容量)——来自 [README 的提供方表格](../../en/README.md);目录实际跟踪的平台比类型联合声明的要少,因为联合中的部分成员已退役,或者由用户自定义而非由目录管理。
+权威来源是 [`shared/types.ts`](../../../shared/types.ts)(`Platform` 联合类型)、[`server/src/providers/index.ts`](../../../server/src/providers/index.ts)(运行时注册表)和 [`server/src/providers/base.ts`](../../../server/src/providers/base.ts)(适配器契约)。公开目录的招牌数字——约 29 家免费提供方、251 个模型系列、358 个免费端点(约合每月 40 亿词元的在册容量)——来自 [README 的提供方表格](../README.md);目录实际跟踪的平台比类型联合声明的要少,因为联合中的部分成员已退役,或者由用户自定义而非由目录管理。
## 文件索引
diff --git a/docs/zh-cn/testing/CHANGELOG.md b/docs/zh-cn/testing/CHANGELOG.md
index 8812e044..799615a3 100644
--- a/docs/zh-cn/testing/CHANGELOG.md
+++ b/docs/zh-cn/testing/CHANGELOG.md
@@ -1,3 +1,5 @@
+[English](../../en/testing/CHANGELOG.md) · **简体中文**
+
# 变更记录
`docs/testing/` 的修订历史,列出塑造了本文档所述测试基础设施的上游提交。最新在前。