fix: 完成了第三阶段的修复与加强

TODO.md

@@ -1,123 +0,0 @@
-# TODO: PDFMathTranslate-next 重构计划
-
-目标：在不引入过度复杂度的前提下，把当前单体 `gateway.py` 拆成可维护的小块，前端交互更稳、更清晰，后端任务和计费语义更可控。
-
-整个重构分三个阶段推进，每个阶段尽量做到“可随时上线”，避免大爆炸改动。
-
----
-
-## 阶段 1：结构拆分（尽量零功能变更）
-
-### 1.1 后端模块化
-
-- 在 `src/` 下拆出最小模块（文件名可根据实现微调）：
-  - `auth.py`：用户加载、密码校验、Session 生成/校验相关逻辑。
-  - `storage.py`：`sqlite3` 初始化、连接管理、`_db_execute/_db_fetch*` 封装。
-  - `jobs.py`：任务表相关的增删改查函数（创建任务、更新任务、按用户查询任务等）。
-  - `billing.py`：计费记录写入与查询。
-  - `proxy.py`：内部 OpenAI 代理、模型路由表、上游调用逻辑。
-- 调整 `gateway.py`：
-  - 只保留 FastAPI `app` 实例、路由注册、`startup/shutdown` 钩子。
-  - 业务实现从上述模块导入，避免在 `gateway.py` 内直接操作底层细节（例如直接写 SQL）。
-
-### 1.2 前端模板与静态资源拆分
-
-- 创建前端资源目录（示例）：
-  - `src/web/templates/login.html`
-  - `src/web/templates/dashboard.html`
-  - `src/web/static/dashboard.js`
-- 将 `_LOGIN_HTML` 与 `_dashboard_page` 中的 HTML/CSS/JS 内容搬迁到对应文件：
-  - 登录页：只保留错误提示占位符（例如 `__ERROR_BLOCK__`）由后端替换。
-  - 控制台页：将 `<script>...</script>` 中 JS 拆到 `dashboard.js`，HTML 中只通过 `<script src="/static/dashboard.js"></script>` 引入。
-- 不引入模板引擎，保持 KISS：
-  - 在后端用最简单的文件读取+`str.replace` 或 `format` 注入 `username/lang_in/lang_out`。
-  - 为模板文件路径增加最小封装函数，例如 `load_template("dashboard.html")`。
-
-### 1.3 HTTP 路由边界梳理
-
-- 显式整理路由分组（哪一块由哪个模块负责），避免日后继续往一个文件堆：
-  - 认证相关：`/login`, `/logout`, `/_session` 类逻辑。
-  - 页面渲染：`/`（Dashboard）、`/login` HTML。
-  - 任务 API：`/api/jobs*`。
-  - 计费 API：`/api/billing*`。
-  - 内部 OpenAI API：`/internal/openai/v1/*`。
-- 在代码注释中说明“这些路由不保证向后兼容，仅用于当前 Space 原型”，避免后续误用。
-
----
-
-## 阶段 2：任务状态机 + 实时刷新
-
-### 2.1 后端任务状态机收敛
-
-- 将任务状态限定为有限集合（例如）：`queued/running/succeeded/failed/cancelled`。
-- 抽象出状态迁移函数而不是在各处随意 `_update_job(status=...)`：
-  - 示例：`transition_job(job_id, event, **kwargs)`，内部根据 `event` 决定可接受的状态变化并写库。
-  - 常见事件：`queued`, `start`, `progress`, `finish_ok`, `finish_error`, `cancel_requested`, `cancel_immediate`, `restart_failed`。
-- 对非法状态迁移（例如从 `succeeded` 再切回 `running`）直接记录错误日志并拒绝更新，避免数据乱掉。
-
-### 2.2 任务状态实时推送（SSE）
-
-- 新增 SSE 端点（示例）：`GET /api/jobs/stream`：
-  - 只推送当前登录用户的任务更新。
-  - 事件载荷最小化：`{id, status, progress, message, updated_at, artifact_urls}`。
-  - 考虑断线重连：可以用简单方案，从最新更新时间开始重拉最近 N 条记录补齐。
-- 任务执行逻辑中，在关键状态变更点调用“事件推送”钩子：
-  - 入队、开始、进度更新、成功、失败、取消等。
-- 保留原有 `/api/jobs` 列表接口用于页面初次加载与 SSE 失败时的兜底。
-
-### 2.3 前端状态机与 UI 行为统一
-
-- 在 `dashboard.js` 中定义单一状态映射表，例如：
-  - `STATUS_CONFIG = { queued: {...}, running: {...}, succeeded: {...}, failed: {...}, cancelled: {...} }`
-  - 每个状态包含：显示文案、颜色/样式、可用操作（是否允许“取消”、是否有下载按钮等）。
-- 将当前散落在 DOM 拼接里的逻辑统一改为基于 `STATUS_CONFIG` 渲染：
-  - 状态文本：`statusText(status)`。
-  - 按钮可见性：从 `STATUS_CONFIG[status].actions` 派生。
-  - 行样式（例如失败高亮红色、运行中高亮）。
-- 使用 `EventSource` 订阅 `/api/jobs/stream`：
-  - 收到事件后更新内存中的 `jobs` 映射，并局部更新 DOM，而不是整表重绘。
-  - SSE 失败时回退到现有的轮询逻辑（例如每 10 秒调用 `/api/jobs`）。
-- 调整轮询频率：
-  - 页面可见时降低频率或完全依赖 SSE。
-  - 页面不可见（`document.hidden === true`）时进一步降频或暂停轮询。
-
----
-
-## 阶段 3：上传限制 + 计费语义修正
-
-### 3.1 上传与执行约束
-
-- 为上传文件增加硬性大小上限：
-  - 定义常量或环境变量（如 `MAX_UPLOAD_MB`），默认例如 100MB。
-  - 在 `api_create_job` 中根据 `Content-Length` 或实际读取的字节数做校验，超���返回 413 / 400。
-- 如可行，增加 PDF 页数或执行时长限制：
-  - 在任务启动时尝试读取 PDF 元信息，如失败则只按大小限制。
-  - 在 worker 中增加“最大执行时长”（例如 2 小时），超时标记为 `failed` 并附带错误信息。
-
-### 3.2 计费模型与前端展示
-
-- 明确不同模型的计费行为：
-  - 对可以从上游拿到 `usage` 的 OpenAI 风格模型，保持当前“按 tokens 计价”的策略。
-  - 对 `SiliconFlowFree`/chatproxy 这类无法获取准确 usage 的模型：
-    - 方案 A：如果上游按请求提供大致的 token 数或成本，则在 `_forward_to_chatproxy` 中解析并写入 `usage_records`。
-    - 方案 B：如果无法获得 usage，就明确将该模型标记为“不计费模型”，后端不写 `usage_records` 或只写 0，并在前端加注释说明“本模型不产生可计费账单”。
-- 前端账单页面文案调整：
-  - 在“我的账单”区域增加提示：哪些模型的账单是准确计费，哪些只是占位或不计费。
-  - 对 cost 为 0 的记录，明确展示为 “$0.000000（不计费模型）” 或类似说明，避免用户误解。
-
-### 3.3 内部代理观测性增强
-
-- 在 `/internal/openai/v1/chat/completions` 与上游调用逻辑中添加更细的日志：
-  - 每次请求打出 request id（例如 `job_id+uuid`）、模型名、路由目标 URL、耗时、状态码。
-  - 将 chatproxy 调用失败原因分类（网络错误 / 非 2xx / JSON 解析失败 / 缺少字段等），方便排查。
-- 对 OpenAI 上游响应中缺失 `usage` 字段的情况增加保护：
-  - 避免因字段缺失导致异常中断，对缺失 usage 的请求使用安全默认值（0 或 `prompt+completion` 推算）。
-
----
-
-## 建议执行顺序与发布策略
-
-- 阶段 1 完成后先发布一次，确保结构拆分无副作用，再继续后续阶段。
-- 阶段 2 先在后端实现 SSE 和状态机，再逐步切换前端逻辑到 SSE，保留轮询兜底。
-- 阶段 3 在引入限制和计费变更前，准备好简单的回滚方案（例如环境变量开关），以防止因阈值配置不当影响正常用户。 
-

src/gateway.py

@@ -49,6 +49,12 @@ DEFAULT_LANG_IN = os.environ.get("DEFAULT_LANG_IN", "en").strip()
 DEFAULT_LANG_OUT = os.environ.get("DEFAULT_LANG_OUT", "zh").strip()
 TRANSLATION_QPS = int(os.environ.get("TRANSLATION_QPS", "4"))
 
+# 上传与任务执行约束配置
+MAX_UPLOAD_MB = int(os.environ.get("MAX_UPLOAD_MB", "100"))
+MAX_UPLOAD_BYTES = MAX_UPLOAD_MB * 1024 * 1024
+MAX_JOB_RUNTIME_SECONDS = int(os.environ.get("MAX_JOB_RUNTIME_SECONDS", "7200"))
+UPLOAD_CHUNK_SIZE = 1024 * 1024  # 1MB per chunk
+
 logging.basicConfig(
     level=logging.INFO,
     format="%(asctime)s %(levelname)s %(name)s - %(message)s",
@@ -87,6 +93,76 @@ def _build_settings_for_job(row: sqlite3.Row) -> SettingsModel:
     return settings
 
 
+async def _consume_translation_stream(
+    job_id: str,
+    settings: SettingsModel,
+    input_path: Path,
+    output_dir: Path,
+) -> None:
+    """消费翻译流事件并驱动任务状态机。
+
+    注意：本函数不负责超时控制，由上层通过 asyncio.wait_for 约束最大执行时长。
+    """
+    async for event in do_translate_async_stream(settings, input_path):
+        event_type = event.get("type")
+        if event_type in {"progress_start", "progress_update", "progress_end"}:
+            progress = float(event.get("overall_progress", 0.0))
+            stage = event.get("stage", "")
+            await _transition_and_notify(
+                job_id,
+                "progress",
+                progress=max(0.0, min(100.0, progress)),
+                message=f"{stage}" if stage else "Running",
+            )
+        elif event_type == "error":
+            error_msg = str(event.get("error", "Unknown translation error"))
+            await _transition_and_notify(
+                job_id,
+                "finish_error",
+                error=error_msg,
+                message="Translation failed",
+                finished_at=storage.now_iso(),
+            )
+            return
+        elif event_type == "finish":
+            result = event.get("translate_result")
+            mono_path = str(getattr(result, "mono_pdf_path", "") or "")
+            dual_path = str(getattr(result, "dual_pdf_path", "") or "")
+            glossary_path = str(
+                getattr(result, "auto_extracted_glossary_path", "") or ""
+            )
+
+            # 兜底：如果路径为空，尝试在输出目录中扫描常见文件
+            if not mono_path or not dual_path:
+                files = list(output_dir.glob("*.pdf"))
+                for file in files:
+                    name = file.name.lower()
+                    if ".mono.pdf" in name and not mono_path:
+                        mono_path = str(file)
+                    elif ".dual.pdf" in name and not dual_path:
+                        dual_path = str(file)
+
+            await _transition_and_notify(
+                job_id,
+                "finish_ok",
+                progress=100.0,
+                message="Translation finished",
+                finished_at=storage.now_iso(),
+                mono_pdf_path=mono_path or None,
+                dual_pdf_path=dual_path or None,
+                glossary_path=glossary_path or None,
+            )
+            return
+
+    await _transition_and_notify(
+        job_id,
+        "finish_error",
+        error="Translation stream ended unexpectedly",
+        message="Translation failed",
+        finished_at=storage.now_iso(),
+    )
+
+
 async def _run_single_job(job_id: str) -> None:
     row = jobs.get_job_row(job_id)
     if row is None:
@@ -117,62 +193,22 @@ async def _run_single_job(job_id: str) -> None:
 
     try:
         settings = _build_settings_for_job(row)
-        async for event in do_translate_async_stream(settings, input_path):
-            event_type = event.get("type")
-            if event_type in {"progress_start", "progress_update", "progress_end"}:
-                progress = float(event.get("overall_progress", 0.0))
-                stage = event.get("stage", "")
-                await _transition_and_notify(
-                    job_id,
-                    "progress",
-                    progress=max(0.0, min(100.0, progress)),
-                    message=f"{stage}" if stage else "Running",
-                )
-            elif event_type == "error":
-                error_msg = str(event.get("error", "Unknown translation error"))
-                await _transition_and_notify(
-                    job_id,
-                    "finish_error",
-                    error=error_msg,
-                    message="Translation failed",
-                    finished_at=storage.now_iso(),
-                )
-                return
-            elif event_type == "finish":
-                result = event.get("translate_result")
-                mono_path = str(getattr(result, "mono_pdf_path", "") or "")
-                dual_path = str(getattr(result, "dual_pdf_path", "") or "")
-                glossary_path = str(
-                    getattr(result, "auto_extracted_glossary_path", "") or ""
-                )
-
-                # 兜底：如果路径为空，尝试在输出目录中扫描常见文件
-                if not mono_path or not dual_path:
-                    files = list(output_dir.glob("*.pdf"))
-                    for file in files:
-                        name = file.name.lower()
-                        if ".mono.pdf" in name and not mono_path:
-                            mono_path = str(file)
-                        elif ".dual.pdf" in name and not dual_path:
-                            dual_path = str(file)
-
-                await _transition_and_notify(
-                    job_id,
-                    "finish_ok",
-                    progress=100.0,
-                    message="Translation finished",
-                    finished_at=storage.now_iso(),
-                    mono_pdf_path=mono_path or None,
-                    dual_pdf_path=dual_path or None,
-                    glossary_path=glossary_path or None,
-                )
-                return
-
+        await asyncio.wait_for(
+            _consume_translation_stream(
+                job_id=job_id,
+                settings=settings,
+                input_path=input_path,
+                output_dir=output_dir,
+            ),
+            timeout=MAX_JOB_RUNTIME_SECONDS,
+        )
+    except asyncio.TimeoutError:
+        logger.warning("Translation job timed out: job_id=%s", job_id)
         await _transition_and_notify(
             job_id,
             "finish_error",
-            error="Translation stream ended unexpectedly",
-            message="Translation failed",
+            error="Translation timed out",
+            message="Translation timed out",
             finished_at=storage.now_iso(),
         )
     except asyncio.CancelledError:
@@ -455,6 +491,7 @@ async def api_get_job(
 
 @app.post("/api/jobs")
 async def api_create_job(
+    request: Request,
     file: UploadFile = File(...),
     lang_in: str = Form(DEFAULT_LANG_IN),
     lang_out: str = Form(DEFAULT_LANG_OUT),
@@ -464,18 +501,63 @@ async def api_create_job(
     if not filename.lower().endswith(".pdf"):
         raise HTTPException(status_code=400, detail="仅支持 PDF 文件")
 
+    # 如果客户端提供了 Content-Length，可做一次粗略预检，避免明显超大的请求
+    content_length = request.headers.get("content-length")
+    if content_length:
+        try:
+            total_len = int(content_length)
+        except ValueError:
+            total_len = 0
+        if total_len > MAX_UPLOAD_BYTES * 2:
+            logger.warning(
+                "Upload rejected by Content-Length: username=%s size=%s limit=%s",
+                username,
+                total_len,
+                MAX_UPLOAD_BYTES,
+            )
+            raise HTTPException(
+                status_code=413,
+                detail=f"上传文件过大，最大 {MAX_UPLOAD_MB}MB",
+            )
+
     job_id = uuid.uuid4().hex
     safe_filename = Path(filename).name
     input_path = (storage.UPLOAD_DIR / f"{job_id}.pdf").resolve()
     output_dir = (storage.JOB_DIR / job_id).resolve()
     output_dir.mkdir(parents=True, exist_ok=True)
 
+    total_bytes = 0
+    too_large = False
     try:
         with input_path.open("wb") as f:
-            shutil.copyfileobj(file.file, f)
+            while True:
+                chunk = file.file.read(UPLOAD_CHUNK_SIZE)
+                if not chunk:
+                    break
+                total_bytes += len(chunk)
+                if total_bytes > MAX_UPLOAD_BYTES:
+                    too_large = True
+                    break
+                f.write(chunk)
     finally:
         await file.close()
 
+    if too_large:
+        # 删除已写入的部分文件，避免残留
+        with contextlib.suppress(FileNotFoundError):
+            input_path.unlink()
+        logger.warning(
+            "Upload too large: username=%s job_id=%s size=%s limit=%s",
+            username,
+            job_id,
+            total_bytes,
+            MAX_UPLOAD_BYTES,
+        )
+        raise HTTPException(
+            status_code=413,
+            detail=f"上传文件过大，最大 {MAX_UPLOAD_MB}MB",
+        )
+
     job_dict = jobs.create_job_record(
         job_id=job_id,
         username=username,
@@ -599,6 +681,10 @@ async def api_billing_records(
     username: str = Depends(auth._require_user),
 ) -> dict[str, Any]:
     limit = max(1, min(limit, 200))
+    records = billing.get_billing_records(username=username, limit=limit)
+    return {"records": records}
+
+
 @app.post("/internal/openai/v1/chat/completions")
 async def internal_openai_chat_completions(request: Request) -> Response:
     return await proxy.handle_internal_chat_completions(

src/proxy.py

@@ -7,6 +7,7 @@ import logging
 import os
 import uuid
 from datetime import datetime, timezone
+from time import perf_counter
 from typing import Any
 
 import httpx
@@ -36,6 +37,10 @@ MODEL_ROUTE_TABLE: dict[str, dict[str, Any]] = {
             "https://api2.pdf2zh-next.com/chatproxy",
         ],
         "api_key": "",
+        # 计费模式：
+        #   - "none": 不计费（当前 SiliconFlowFree 默认）
+        #   - "upstream_usage": 按上游返回的 usage 字段计费
+        "billing_mode": "none",
     }
 }
 
@@ -136,6 +141,7 @@ async def _forward_to_chatproxy(
     payload: dict[str, Any],
     model: str,
     route: dict[str, Any],
+    request_id: str | None = None,
 ) -> dict[str, Any]:
     base_urls = route.get("base_urls", [])
     if not isinstance(base_urls, list) or not base_urls:
@@ -162,13 +168,20 @@ async def _forward_to_chatproxy(
             )
         except httpx.HTTPError as exc:
             last_error = str(exc)
-            logger.warning("chatproxy call failed: model=%s url=%s error=%s", model, base_url, exc)
+            logger.warning(
+                "chatproxy call failed: request_id=%s model=%s url=%s error=%s",
+                request_id,
+                model,
+                base_url,
+                exc,
+            )
             continue
 
         if upstream.status_code >= 400:
             last_error = f"status={upstream.status_code}"
             logger.warning(
-                "chatproxy upstream returned error: model=%s url=%s status=%s",
+                "chatproxy upstream returned error: request_id=%s model=%s url=%s status=%s",
+                request_id,
                 model,
                 base_url,
                 upstream.status_code,
@@ -180,7 +193,8 @@ async def _forward_to_chatproxy(
         except Exception as exc:  # noqa: BLE001
             last_error = f"invalid json response: {exc}"
             logger.warning(
-                "chatproxy upstream returned invalid json: model=%s url=%s",
+                "chatproxy upstream returned invalid json: request_id=%s model=%s url=%s",
+                request_id,
                 model,
                 base_url,
             )
@@ -190,14 +204,21 @@ async def _forward_to_chatproxy(
         if not isinstance(content, str):
             last_error = "missing content field"
             logger.warning(
-                "chatproxy upstream missing content: model=%s url=%s body=%s",
+                "chatproxy upstream missing content: request_id=%s model=%s url=%s body=%s",
+                request_id,
                 model,
                 base_url,
                 body,
             )
             continue
 
-        return _build_openai_compatible_response(model=model, content=content)
+        return {
+            "openai_response": _build_openai_compatible_response(
+                model=model,
+                content=content,
+            ),
+            "raw_upstream_body": body,
+        }
 
     raise HTTPException(
         status_code=502,
@@ -233,23 +254,59 @@ async def handle_internal_chat_completions(
     if not model:
         raise HTTPException(status_code=400, detail="model is required")
 
+    request_id = uuid.uuid4().hex[:8]
     route = MODEL_ROUTE_TABLE.get(model)
+    job_id = active_job_by_user.get(username)
+    route_type = route.get("route_type") if route else "openai"
+
+    logger.info(
+        "Internal chat request start: request_id=%s username=%s model=%s route_type=%s job_id=%s",
+        request_id,
+        username,
+        model,
+        route_type,
+        job_id,
+    )
+
     if route and route.get("route_type") == "chatproxy":
-        response_json = await _forward_to_chatproxy(
-            http_client=http_client,
-            payload=payload,
-            model=model,
-            route=route,
-        )
-        billing.record_usage(
-            username=username,
-            job_id=active_job_by_user.get(username),
-            model=model,
-            prompt_tokens=0,
-            completion_tokens=0,
-            total_tokens=0,
-        )
-        return JSONResponse(response_json, status_code=200)
+        t0 = perf_counter()
+        try:
+            result = await _forward_to_chatproxy(
+                http_client=http_client,
+                payload=payload,
+                model=model,
+                route=route,
+                request_id=request_id,
+            )
+            response_json = result.get("openai_response") or {}
+            raw_body = result.get("raw_upstream_body") or {}
+
+            billing_mode = str(route.get("billing_mode") or "none")
+            if billing_mode == "upstream_usage":
+                usage = raw_body.get("usage") or {}
+                prompt_tokens = int(usage.get("prompt_tokens") or 0)
+                completion_tokens = int(usage.get("completion_tokens") or 0)
+                total_tokens = int(
+                    usage.get("total_tokens") or (prompt_tokens + completion_tokens)
+                )
+                if total_tokens > 0:
+                    billing.record_usage(
+                        username=username,
+                        job_id=job_id,
+                        model=model,
+                        prompt_tokens=prompt_tokens,
+                        completion_tokens=completion_tokens,
+                        total_tokens=total_tokens,
+                    )
+
+            return JSONResponse(response_json, status_code=200)
+        finally:
+            duration = perf_counter() - t0
+            logger.info(
+                "Internal chat request finished: request_id=%s route_type=chatproxy duration=%.3fs",
+                request_id,
+                duration,
+            )
 
     if not OPENAI_REAL_API_KEY:
         raise HTTPException(status_code=500, detail="OPENAI_API_KEY is not configured")
@@ -259,6 +316,8 @@ async def handle_internal_chat_completions(
         "Content-Type": "application/json",
     }
 
+    upstream: httpx.Response | None = None
+    t0 = perf_counter()
     try:
         upstream = await http_client.post(
             OPENAI_UPSTREAM_CHAT_URL,
@@ -266,8 +325,25 @@ async def handle_internal_chat_completions(
             json=payload,
         )
     except httpx.HTTPError as exc:
-        logger.error("Upstream OpenAI call failed: %s", exc)
+        duration = perf_counter() - t0
+        logger.error(
+            "Upstream OpenAI call failed: request_id=%s model=%s username=%s duration=%.3fs error=%s",
+            request_id,
+            model,
+            username,
+            duration,
+            exc,
+        )
         raise HTTPException(status_code=502, detail="Upstream OpenAI request failed") from exc
+    else:
+        duration = perf_counter() - t0
+        logger.info(
+            "Upstream OpenAI call finished: request_id=%s model=%s status=%s duration=%.3fs",
+            request_id,
+            model,
+            upstream.status_code,
+            duration,
+        )
 
     response_json: dict[str, Any] | None = None
     content_type = upstream.headers.get("content-type", "")
@@ -281,7 +357,21 @@ async def handle_internal_chat_completions(
         usage = response_json.get("usage") or {}
         prompt_tokens = int(usage.get("prompt_tokens") or 0)
         completion_tokens = int(usage.get("completion_tokens") or 0)
-        total_tokens = int(usage.get("total_tokens") or (prompt_tokens + completion_tokens))
+        total_tokens = int(
+            usage.get("total_tokens") or (prompt_tokens + completion_tokens)
+        )
+
+        if (
+            prompt_tokens == 0
+            and completion_tokens == 0
+            and total_tokens == 0
+        ):
+            logger.warning(
+                "Upstream OpenAI response missing or zero usage: request_id=%s model=%s username=%s",
+                request_id,
+                model,
+                username,
+            )
 
         job_id = active_job_by_user.get(username)
 
@@ -302,4 +392,3 @@ async def handle_internal_chat_completions(
         status_code=upstream.status_code,
         media_type=content_type or None,
     )
-

src/web/static/dashboard.js

@@ -24,11 +24,14 @@ async function refreshBilling() {
   document.getElementById("billingSummary").textContent =
     `总 tokens=${summary.total_tokens} | 总费用(USD)=${Number(
       summary.total_cost_usd,
-    ).toFixed(6)}`;
+    ).toFixed(6)}（仅统计计费模型，不含 SiliconFlowFree 等免费模型）`;
 
   const body = document.getElementById("billingBody");
   body.innerHTML = "";
   for (const r of rows.records) {
+    const cost = Number(r.cost_usd).toFixed(6);
+    const costLabel = cost === "0.000000" ? `${cost}（不计费模型）` : cost;
+
     const tr = document.createElement("tr");
     tr.innerHTML = `
       <td>${esc(r.created_at)}</td>
@@ -36,7 +39,7 @@ async function refreshBilling() {
       <td>${r.prompt_tokens}</td>
       <td>${r.completion_tokens}</td>
       <td>${r.total_tokens}</td>
-      <td>${Number(r.cost_usd).toFixed(6)}</td>
+      <td>${costLabel}</td>
     `;
     body.appendChild(tr);
   }

src/web/templates/dashboard.html

@@ -120,6 +120,7 @@
         </thead>
         <tbody id="billingBody"></tbody>
       </table>
+      <div class="hint">说明：仅统计计费模型的使用情况，当前 SiliconFlowFree 等免费模型不会产生账单记录。</div>
     </section>
   </div>
 
@@ -147,4 +148,3 @@
 <script src="/static/dashboard.js"></script>
 </body>
 </html>
-