Add offline configuration migration and stream reasoning in realtime mode

.env.example

@@ -1,78 +1,129 @@
 # Copy to .env for first use; preserve existing settings when updating.
-# Compose and native launches read .env; native zero-configuration startup can omit it.
+# 首次使用复制为 .env；升级时保留已有配置。
+# Compose loads every key in this file into the container, so unrelated keys are harmless;
+# native launches read it too, and native zero-configuration startup can omit it.
+# Compose 会把本文件的每个键加载进容器，无关的键不会造成影响；原生启动同样读取它，
+# 零配置的原生启动可以省略该文件。
+# Runtime keys here stay read-only in the WebUI. To let the WebUI own them, stop the
+# service and run `python3 converter.py config migrate` (add --data-dir/--env-file when
+# the paths differ), then delete the printed lines. Deployment keys below are never migrated.
+# 这里列出的运行参数在 WebUI 中只读。要让 WebUI 接管，请停止服务后运行
+# `python3 converter.py config migrate`（路径不同时加 --data-dir/--env-file），
+# 再删除它打印的行；下方的部署类键不会被迁移。
 
 # Native listener and Compose host mapping; explicit --host/--port override native values.
+# 原生监听地址与 Compose 宿主机映射；显式 --host/--port 覆盖原生取值。
 CODEBUDDY2API_BIND=127.0.0.1
 CODEBUDDY2API_PORT=8787
 
-# Compose-only image and host data directory; container data stays in /data/auth.
-CODEBUDDY2API_IMAGE=codebuddy2api:local
+# Compose image; uncomment to override, leaving it commented keeps the published latest tag.
+# Compose 镜像；取消注释才会覆盖，保持注释即使用已发布的 latest 标签。
+# CODEBUDDY2API_IMAGE=ghcr.io/maiphucgiang/codebuddy2api:latest
+# Compose host data directory; container data stays in /data/auth.
+# Compose 宿主机数据目录；容器内数据固定在 /data/auth。
 CODEBUDDY2API_AUTH_PATH=./auth
+# Container time zone; daily guards follow it, and an unset value keeps UTC.
+# 容器时区；每日任务按它跨天，未设置时保持 UTC。
+# TZ=Asia/Shanghai
+# Optional Compose override for the env file path, used instead of .env.
+# 可选的 Compose 覆盖项：改读其他 env 文件而非 .env。
+# CODEBUDDY2API_ENV_FILE=.env
 
 # Optional native data directory; Compose fixes CODEBUDDY_AUTH_DIR to /data/auth.
+# 可选的原生数据目录；Compose 会把 CODEBUDDY_AUTH_DIR 固定为 /data/auth。
 # CODEBUDDY_AUTH_DIR=./auth
 # Import directory defaults to the data directory's imports/; use container paths in Compose.
+# 导入目录默认是数据目录下的 imports/；Compose 中请使用容器内路径。
 # CODEBUDDY_IMPORT_DIR=./auth/imports
 
 # Empty locks management; set a random key before exposing inference beyond loopback.
+# 留空即锁定管理；对外暴露推理端口前请设置随机密钥。
 # Native: omit/comment the variable to use the saved default key (first local start displays it once).
+# 原生：省略或注释该变量会使用已保存的默认 key（首次本地启动会显示一次）。
 CODEBUDDY2API_KEY=
-# Native-only unsafe opt-in; Compose uses its host mapping to control exposure.
+# Opt-in for headless/non-loopback no-auth runs; the image and Compose already force it on.
+# 原生后台或非回环免鉴权运行选项；镜像与 Compose 已固定开启。
 # CODEBUDDY2API_ALLOW_OPEN_NOAUTH=false
 
 # Disabling CSRF checks does not disable authentication; use only on trusted local networks.
+# 关闭 CSRF 校验不等于关闭认证；仅在可信本地网络使用。
 CODEBUDDY2API_ADMIN_CSRF=true
 
 # Extra trusted management origins behind reverse proxies (comma separated; bare domains use HTTPS).
+# 反代后额外信任的管理来源（逗号分隔；裸域名按 HTTPS 处理）。
 # Unset leaves the list configurable in the WebUI; an explicit value locks it.
+# 不设置时列表可在 WebUI 修改；显式设置会锁定。
 # CODEBUDDY2API_ADMIN_ORIGINS=https://chat.example.com
-# 可信代理 IP/CIDR（逗号分隔）；命中时审计改记 X-Forwarded-For/X-Real-IP 的真实客户端地址
+# Trusted proxy IPs/CIDRs; a matching peer makes the audit log record X-Forwarded-For/X-Real-IP.
+# 可信代理 IP/CIDR；命中时审计改记 X-Forwarded-For/X-Real-IP 中的真实客户端地址。
 # CODEBUDDY2API_TRUSTED_PROXIES=127.0.0.1,10.0.0.0/8
 
 # Unset leaves tool metadata configurable in the WebUI; an explicit Boolean locks it.
+# 不设置时工具元数据可在 WebUI 修改；显式布尔值会锁定。
 # CODEBUDDY2API_KEEP_TOOL_METADATA=true
 
 # Image overflow keeps the newest blocks or returns 413; zero forbids all images.
+# 图片超限时保留最新内容或返回 413；设为 0 禁止全部图片。
 CODEBUDDY2API_MAX_IMAGES=16
 CODEBUDDY2API_IMAGE_POLICY=truncate
 # Positive upstream JSON byte limit after image policy and protocol adaptation.
+# 图片策略与协议适配之后，发往上游的 JSON 字节上限（正数）。
 CODEBUDDY2API_MAX_REQUEST_BYTES=33554432
 # Positive raw inbound byte limit, enforced before JSON parsing.
+# 原始入站字节上限（正数），在解析 JSON 之前生效。
 CODEBUDDY2API_MAX_INBOUND_BYTES=67108864
 # Aggregated output bytes and concurrent inference requests; zero disables each limit.
+# 聚合输出字节数与并发推理请求数；设为 0 分别关闭对应限制。
 CODEBUDDY2API_MAX_COLLECT_BYTES=8388608
 CODEBUDDY2API_MAX_CONCURRENT=64
 # Optional bounded upstream connection reuse; restart to apply, disabled by default.
+# 可选的上游连接复用（有上限）；修改后需重启，默认关闭。
 # CODEBUDDY2API_UPSTREAM_KEEPALIVE=false
-# Per-account in-flight limit; zero preserves unlimited account capacity.
+# Per-account in-flight limit; zero keeps account capacity unlimited.
+# 单账号在途请求上限；设为 0 保持账号容量不受限。
 # CODEBUDDY2API_MAX_INFLIGHT_PER_ACCOUNT=0
-# Optional session/attempt tracing; legacy preserves existing upstream header behavior.
+# Optional session/attempt tracing; legacy keeps existing upstream header behavior.
+# 可选的会话/尝试追踪；legacy 保持现有上游请求头行为。
 # CODEBUDDY2API_REQUEST_CONTEXT_MODE=legacy
 # Responses projection is hot and WebUI-editable unless explicitly set here.
-# balanced rewrites only recognized harness blocks with stable summaries; other text stays verbatim.
+# Responses 投影可热生效且默认可在 WebUI 修改，除非在此显式设置。
+# balanced only rewrites recognized harness blocks with stable summaries; other text stays verbatim.
+# balanced 只改写可识别的 harness 块并生成稳定摘要，其余文本保持原样。
 # CODEBUDDY2API_RESPONSES_PROJECTION_MODE=balanced
 # Per-item head/tail limit for generated assistant text, tool arguments and tool results;
 # zero disables per-item trimming. Global request/output gates still apply.
+# 生成文本、工具参数与工具结果的单项首尾截断上限；设为 0 关闭单项截断，
+# 全局请求与输出限制仍然生效。
 # Non-zero values must be between 256 and 33554432 bytes.
+# 非零取值须在 256 至 33554432 字节之间。
 # CODEBUDDY2API_RESPONSES_PROJECTION_MAX_BYTES=40000
-# compatible preserves aggregation; realtime forwards all protocol output incrementally
+# compatible keeps aggregation; realtime forwards all protocol output incrementally
 # and does not regenerate malformed tool arguments.
+# compatible 保持聚合；realtime 增量转发全部协议输出，且不重新生成损坏的工具参数。
 # CODEBUDDY2API_STREAM_MODE=compatible
-# Disable only declared model-capability preflight; other safeguards and Intl image merging remain enabled.
+# Disable only the declared model-capability preflight; other safeguards and Intl image merging remain.
+# 只关闭声明的模型能力预检；其他保护与国际站图片合并仍然生效。
 # CODEBUDDY2API_MODEL_CAPABILITY_GUARD=true
 
 # Retired: this setting only warns; all persistent logs use logs.sqlite3.
+# 已停用：该项只会给出告警；所有持久日志都写入 logs.sqlite3。
 CODEBUDDY2API_LOG=
 # Legacy text-preview limit; text output is retired. SQLite diagnostics have a separate budget.
+# 旧版文本预览上限；文本输出已停用，SQLite 诊断另有独立预算。
 CODEBUDDY2API_LOG_BODY_LIMIT=65536
 
 # International trial credits remain manual-only in the WebUI.
-# Preauthorize first-Buddy tasks, one bounded chat (may use credits), adoption and travel.
+# 国际站试用积分仍需在 WebUI 手动领取。
+# Preauthorize first-Buddy tasks: one bounded chat (may use credits), adoption and travel.
+# 预授权首次 Buddy 任务：一次有上限的对话（可能消耗积分）、领养与旅行。
 CODEBUDDY2API_AUTO_ACCEPT_BUDDY=false
 
 # Extra generations for malformed tool arguments; each may consume credits, zero disables retries.
+# 损坏工具参数的额外生成次数；每次可能消耗积分，设为 0 关闭重试。
 CODEBUDDY2API_TOOL_CALL_MAX_RETRY=3
 # Pre-response credential failovers; zero disables replay. See docs/advanced.md for billing risks.
+# 响应前的凭证故障切换次数；设为 0 关闭重放。计费风险见 docs/advanced.md。
 CODEBUDDY2API_FAILOVER_MAX=0
 # Replay incomplete writes only when partial requests cannot be billed upstream.
+# 仅在部分写入不会被上游计费时才重放未完成的请求。
 CODEBUDDY2API_RETRY_WRITE_TIMEOUT=false

.github/workflows/docker.yml

@@ -119,14 +119,13 @@ jobs:
         uses: docker/metadata-action@dc802804100637a589fabce1cb79ff13a1411302 # v6.2.0
         with:
           images: ghcr.io/${{ github.repository }}
-          flavor: latest=auto
+          # Three published tags: the release version, edge for main, latest for releases.
+          # Pull requests get an unpublished ref tag so the build still has an identity.
           tags: |
-            type=raw,value=edge,enable=${{ github.ref == 'refs/heads/main' }}
             type=ref,event=pr
-            type=sha
             type=semver,pattern={{version}}
-            type=semver,pattern={{major}}.{{minor}}
-            type=semver,pattern={{major}}
+            type=raw,value=edge,enable=${{ github.ref == 'refs/heads/main' }}
+            type=raw,value=latest,enable=${{ startsWith(github.ref, 'refs/tags/v') }}
           labels: |
             org.opencontainers.image.version=${{ needs.test.outputs.version }}
       - name: Build and publish

Dockerfile

@@ -20,7 +20,7 @@
 
 FROM python:3.12-slim@sha256:78387bc3881b8273120a12ebe6c1ab22b018ccc2c9adf565ae1ac9b536e184ea AS runtime
 WORKDIR /app
 ENV CODEBUDDY_AUTH_DIR=/data/auth
 COPY requirements.txt .
 RUN pip install --no-cache-dir --require-hashes --only-binary=:all: -r requirements.txt
 COPY VERSION ./
@@ -30,4 +30,4 @@
 EXPOSE 8787
 # Listen on container interfaces; host port mapping controls external access.
 ENV CODEBUDDY2API_ALLOW_OPEN_NOAUTH=true
-CMD ["python3", "converter.py", "--host", "0.0.0.0", "--port", "8787", "--skip-check"]
+CMD ["python3", "converter.py", "--host", "0.0.0.0", "--port", "8787", "--skip-check", "--desensitize"]

README.md

@@ -19,23 +19,19 @@ cd codebuddy2api
 cp .env.example .env
 ```
 
-Edit `.env`: set `CODEBUDDY2API_KEY` to your own random key and pick the image. Preserve an existing `.env` on upgrades:
-
-```dotenv
-CODEBUDDY2API_IMAGE=ghcr.io/maiphucgiang/codebuddy2api:latest
-```
+Edit `.env`: set `CODEBUDDY2API_KEY` to your own random key. Compose loads the whole file into the container, so every key applies and unknown keys are harmless. Preserve an existing `.env` on upgrades.
 
 ```bash
 docker compose pull
 docker compose up -d --no-build
 ```
 
-`latest` tracks stable releases; pin a published version tag for reproducible deployments. Image features belong to that version, not to unmerged source branches.
+Compose pulls `latest` by default (`CODEBUDDY2API_IMAGE=ghcr.io/maiphucgiang/codebuddy2api:latest`); images also publish the release version (for example `1.3.6`) and `edge` for `main`. Pin a version tag for reproducible deployments; image features belong to that version, not to unmerged source branches.
 
 First use:
 
 1. Open **http://127.0.0.1:8787/dashboard** and sign in with your API key.
-2. In **Credentials**, add a domestic or international account through browser login, or import an `.info` file.
+2. In **Credentials**, add a domestic or international account through browser login, import an `.info` file, or paste refresh tokens for a chosen endpoint.
 3. In **Models**, find an available model and use its public ID in your client.
 
 The template binds to localhost only. Configure HTTPS and restrict network access before allowing remote connections; keep and securely back up the `auth/` data directory. To run current source or log in from a terminal instead, see the [deployment guide](docs/deployment.md).
@@ -82,7 +78,7 @@ The template binds to localhost only. Configure HTTPS and restrict network acces
 ## FAQ
 
 - **WebUI sign-in fails behind an HTTPS domain/reverse proxy?** Trust your public origin via `admin_allowed_origins` — see [Management Origin checks](docs/advanced.md#management-origin--csrf-switch).
-- **No Docker?** After installing dependencies and the WebUI, run `uv run converter.py` or `python3 converter.py` without `.env`. First local startup saves a default key and displays it once — see [Local Python setup](docs/deployment.md#local-python-setup).
+- **No Docker?** After installing dependencies and the WebUI, run `uv run --locked --no-build converter.py` or `python3 converter.py` without `.env`. First local startup saves a default key and displays it once — see [Local Python setup](docs/deployment.md#local-python-setup).
 - **Where is my data?** Everything lives in `auth/` (or `/data/auth` in Docker): credentials, settings and log databases — see [Data and backups](docs/webui.md#data-and-backups).
 - **Which image tag should I use?** `latest` follows stable releases, `edge` follows main, version tags pin one release — see [Published images](docs/deployment.md#use-published-images).
 - **Responses tool output/arguments compressed or need verbatim passthrough?** Set `responses_projection_mode` (default `balanced`, or `passthrough` to disable projection) and `responses_projection_max_bytes` (default `40000`, `0` disables per-item trimming). Balanced trimming keeps the head/tail and reports original bytes, estimated tokens and total lines; client addresses stay unchanged — see [Responses projection](docs/clients.md#responses-projection) and [details](docs/advanced.md#responses-projection).

README.zh-CN.md

@@ -19,23 +19,19 @@ cd codebuddy2api
 cp .env.example .env
 ```
 
-编辑 `.env`：将 `CODEBUDDY2API_KEY` 设置为自己的随机密钥，并指定镜像；升级时保留已有 `.env`：
-
-```dotenv
-CODEBUDDY2API_IMAGE=ghcr.io/maiphucgiang/codebuddy2api:latest
-```
+编辑 `.env`：将 `CODEBUDDY2API_KEY` 设置为自己的随机密钥。Compose 会把整个文件加载进容器，每个键都会生效，无关的键也无影响。升级时保留已有 `.env`。
 
 ```bash
 docker compose pull
 docker compose up -d --no-build
 ```
 
-`latest` 跟随稳定发行版；需固定部署时改用已发布的版本标签。镜像功能以对应版本为准，不包含尚未合并的源码分支改动。
+Compose 默认拉取 `latest`（`CODEBUDDY2API_IMAGE=ghcr.io/maiphucgiang/codebuddy2api:latest`）；镜像同时发布发行版本（例如 `1.3.6`）与跟随 `main` 的 `edge`。需固定部署时改用版本标签；镜像功能以对应版本为准，不包含尚未合并的源码分支改动。
 
 首次使用：
 
 1. 打开 **http://127.0.0.1:8787/dashboard**，使用刚设置的 API key 登录。
-2. 在「凭证管理」扫码添加国内或国际账号，也可导入 `.info` 文件。
+2. 在「凭证管理」扫码添加国内或国际账号，也可导入 `.info` 文件，或按端点粘贴刷新令牌批量导入。
 3. 在「模型路由」查看可用模型，将其对外 ID 填入客户端。
 
 按模板配置时仅允许本机访问。远程访问前请配置 HTTPS 并限制网络访问；保留并妥善备份 `auth/` 数据目录。如需直接运行源码或在终端登录，见[部署指南](docs/deployment.zh-CN.md)。
@@ -82,7 +78,7 @@ docker compose up -d --no-build
 ## 常见问题
 
 - **绑定域名后经 HTTPS 反代无法登录 WebUI？** 将对外来源加入 `admin_allowed_origins` 信任列表——见[管理 Origin 校验](docs/advanced.zh-CN.md#管理-origin--csrf-开关)。
-- **没有 Docker？** 准备依赖和 WebUI 后，直接 `uv run converter.py` 或 `python3 converter.py`，无需 `.env`；首次本地启动保存默认 key 并仅在终端显示一次——见[本地 Python 运行](docs/deployment.zh-CN.md#本地-python-运行)。
+- **没有 Docker？** 准备依赖和 WebUI 后，直接 `uv run --locked --no-build converter.py` 或 `python3 converter.py`，无需 `.env`；首次本地启动保存默认 key 并仅在终端显示一次——见[本地 Python 运行](docs/deployment.zh-CN.md#本地-python-运行)。
 - **数据在哪里？** 全部位于 `auth/`（Docker 中为 `/data/auth`）：凭证、设置与日志数据库——见[数据与备份](docs/webui.zh-CN.md#数据与备份)。
 - **镜像标签怎么选？** `latest` 跟随稳定版，`edge` 跟随 main，版本标签固定某一发行版——见[使用已发布镜像](docs/deployment.zh-CN.md#使用已发布镜像)。
 - **Responses 工具输出/参数被压缩或需要完全原样？** 设置 `responses_projection_mode`（默认 `balanced`，设 `passthrough` 可完全关闭投影）及 `responses_projection_max_bytes`（默认 `40000`，`0` 禁用单项裁剪）。balanced 裁剪保留头尾并显示原始 bytes、估算 tokens 与总行数，客户端地址不变——见 [Responses 投影](docs/clients.zh-CN.md#responses-投影)及[详细说明](docs/advanced.zh-CN.md#responses-投影)。