docs(user-guide): 二轮校准修正全部事实性偏差 — 锚点断裂、CLI 参数、配置加载语义、迁移条件精确化;

🤖 Generated with [Claude Code](https://github.com/claude), [CodeX](https://openai.com), [Gemini](https://github.com/apps/gemini-code-assist)
Co-Authored-By: Aurelius Huang<threefish.ai@gmail.com>

Author: ThreeFish-AI

docs/guide/api-reference.md

@@ -164,15 +164,17 @@ curl -I http://127.0.0.1:8046/
 | 问题 | 处理方式 |
 |------|---------|
 | `tool_use_id` 格式不符（非 `toolu_` 前缀） | 自动重写为合规格式 |
-| `tool_result` 出现在 `assistant` 消息中 | 剥离该 block（首次触发 WARNING 日志） |
+| `tool_result` 出现在 `assistant` 消息中 | 收集该 block；转发至 Anthropic tier 时执行重定位，其他 vendor 保留原位不变（首次触发 WARNING 日志） |
 | `tool_use` 缺少合法 ID | 自动生成新 ID |
 
 **致命验证错误（返回 HTTP 400）**
 
 | 场景 | 错误示例 |
 |------|---------|
 | `tool_use` block 缺少 `id` 字段 | `"tool_use block is missing 'id' field"` |
+| `tool_use` block 缺少 `name` 字段 | `"tool_use block missing name for id rewrite"` |
 | `tool_result` block 缺少 `tool_use_id` 字段 | `"tool_result block is missing 'tool_use_id' field"` |
+| `tool_result` 引用不存在的 `tool_use_id` | `"tool_result references unknown tool_use_id"` |
 | 消息角色不交替 | `"messages must alternate between user and assistant"` |
 | `messages` 末尾不是 `user` 消息 | `"last message must be from user"` |
 

docs/guide/cli-reference.md

@@ -102,11 +102,11 @@ coding-proxy usage [OPTIONS]
 # 查看最近 7 天统计（默认）
 coding-proxy usage
 
-# 本周统计
-coding-proxy usage -w
+# 本周统计（第 1 周）
+coding-proxy usage -w 1
 
-# 本月统计
-coding-proxy usage -m
+# 本月统计（第 1 月）
+coding-proxy usage -m 1
 
 # 全部历史，按供应商+模型聚合
 coding-proxy usage -t

docs/guide/dashboard.md

@@ -18,12 +18,12 @@ http://127.0.0.1:8046/dashboard
 
 | 卡片 | 说明 |
 |------|------|
-| 今日请求 | 当日总请求数 |
-| 今日 Token | 当日总 Token 消耗（输入 + 输出 + 缓存） |
-| 今日费用 | 基于定价配置的费用估算 |
-| 故障转移次数 | 所选时间范围内的故障转移事件数 |
-| 平均耗时 | 请求平均响应时间 |
-| 区间请求 | 所选时间范围的总请求数 |
+| 今日请求数 | 当日总请求数（子行显示本周累计） |
+| 今日 Token 总量 | 当日总 Token 消耗（子行显示本周累计） |
+| 今日输出 Token | 当日输出 Token 数（子行显示本周累计） |
+| 今日费用估算 | 基于定价配置的费用估算（子行显示本周累计） |
+| 故障转移（今日） | 当日故障转移事件数（子行显示本周累计） |
+| 平均延迟（今日） | 当日请求平均响应时间（子行显示本周累计） |
 
 ### 图表
 
@@ -55,7 +55,7 @@ http://127.0.0.1:8046/dashboard
 
 ## 数据源
 
-看板数据来自以下 API 端点，详见 [API 参考 — Dashboard 端点](./api-reference.md#59-dashboard-端点)：
+看板数据来自以下 API 端点，详见 [API 参考 — Dashboard 端点](./api-reference.md#11-dashboard-端点)：
 
 | 端点 | 说明 |
 |------|------|

docs/guide/monitoring.md

@@ -42,11 +42,11 @@ logging:
 # 最近 7 天（默认）
 coding-proxy usage
 
-# 本周统计
-coding-proxy usage -w
+# 本周统计（第 1 周）
+coding-proxy usage -w 1
 
-# 本月统计
-coding-proxy usage -m
+# 本月统计（第 1 月）
+coding-proxy usage -m 1
 
 # 全部历史
 coding-proxy usage -t
@@ -112,7 +112,7 @@ curl http://127.0.0.1:8046/api/status
 
 ### 7.2 配额耗尽后自动降级
 
-**现象**：上游供应商返回 `403` 错误，消息含 "usage cap" 或 "quota"
+**现象**：上游供应商返回 `403` 错误，消息含 "quota"、"usage cap"、"limit exceeded"、"capacity" 等关键词
 
 **代理行为**：识别关键词 → 配额守卫标记 QUOTA_EXCEEDED → 后续请求自动路由到下一层级。
 

docs/guide/vendors.md

@@ -42,7 +42,7 @@ coding-proxy 支持三类供应商，共 9 种：
 | `vendor` | string | — | 供应商类型标识 |
 | `enabled` | bool | `true` | 是否启用 |
 | `base_url` | string | `""` | API 基础 URL；留空使用供应商默认值 |
-| `timeout_ms` | int | `300000` | 请求超时（毫秒） |
+| `timeout_ms` | int | `300000`/`3000000` | 请求超时（毫秒）；直连/协议转换供应商默认 300000（5 分钟），原生 Anthropic 兼容供应商默认 3000000（50 分钟） |
 
 弹性设施字段（`circuit_breaker`、`quota_guard`、`weekly_quota_guard`、`retry`）参见 [配置字段参考 — 弹性字段](../arch/config-reference.md#5-vendorconfig-弹性字段)。
 
@@ -79,7 +79,7 @@ coding-proxy 支持三类供应商，共 9 种：
 | `models_cache_ttl_seconds` | int | `300` | 模型列表缓存 TTL（秒） |
 
 > 默认已启用（`enabled: true`）。首次启动时若缺少有效凭证，自动触发 GitHub Device Flow 浏览器登录。
-> 可通过 [`GET /api/copilot/diagnostics`](./api-reference.md#57-get-apicopilotdiagnostics) 和 [`GET /api/copilot/models`](./api-reference.md#58-get-apicopilotmodels) 排查认证状态。
+> 可通过 [`GET /api/copilot/diagnostics`](./api-reference.md#7-get-apicopilotdiagnostics) 和 [`GET /api/copilot/models`](./api-reference.md#8-get-apicopilotmodels) 排查认证状态。
 
 ### 3.3 antigravity — Google Antigravity
 
@@ -92,7 +92,6 @@ coding-proxy 支持三类供应商，共 9 种：
 | `refresh_token` | string | `""` | Google OAuth2 Refresh Token，支持 `${ENV_VAR}` |
 | `base_url` | string | `"https://generativelanguage.googleapis.com/v1beta"` | Gemini API 基础地址 |
 | `model_endpoint` | string | `"models/claude-sonnet-4-20250514"` | 模型端点路径（仅作为未命中映射时的默认模型） |
-| `safety_settings` | dict or null | `null` | Gemini API 安全设置键值对（如 `{"HARASSMENT": "block_none"}`） |
 
 > 默认禁用（`enabled: false`）。启用需配置 OAuth 凭据，启动时自动触发 Google OAuth 登录。access_token 过期时优先静默刷新，无需重新登录。
 
@@ -189,7 +188,7 @@ tiers: ["zhipu", "anthropic", "copilot", "antigravity"]
 
 ## 5. model_mapping — 模型映射规则
 
-将 Claude 模型名自动转换为各供应商对应的实际模型名。完整规则列表参见 [`config.default.yaml`](../../config.default.yaml)。
+将 Claude 模型名自动转换为各供应商对应的实际模型名。完整规则列表参见项目内置的 `config.default.yaml`（`src/coding/proxy/config/config.default.yaml`）。
 
 | 字段 | 类型 | 说明 |
 |------|------|------|
@@ -233,7 +232,7 @@ model_mapping:
 
 ## 6. pricing — 模型定价
 
-按 `(vendor, model)` 配置四维定价，用于 [`coding-proxy usage`](./cli-reference.md#43-coding-proxy-usage) 的费用统计展示。完整定价表参见 [`config.default.yaml`](../../config.default.yaml)。
+按 `(vendor, model)` 配置四维定价，用于 [`coding-proxy usage`](./cli-reference.md#3-coding-proxy-usage) 的费用统计展示。完整定价表参见项目内置的 `config.default.yaml`（`src/coding/proxy/config/config.default.yaml`）。
 
 | 字段 | 类型 | 说明 |
 |------|------|------|

docs/user-guide.md

@@ -28,7 +28,7 @@
 
 coding-proxy 是一个面向 Claude Code 的多**供应商(vendor)**智能代理服务。它在 Claude Code 和 API 供应商之间充当透明代理，具备以下核心能力：
 
-- **N-tier 自动故障转移(failover)**：支持多层供应商链式降级（默认链路：智谱 → Anthropic → Copilot → Antigravity），恢复后自动切回
+- **N-tier 自动故障转移(failover)**：支持多层供应商链式降级（默认活跃链路：智谱 → Anthropic → Copilot；Antigravity 默认禁用），恢复后自动切回
 - **9 种供应商支持**：Anthropic Claude、GitHub Copilot、Google Antigravity、智谱 GLM、MiniMax、阿里 Qwen、小米 MiMo、Kimi、豆包 Doubao
 - **模型名称映射**：自动将 Claude 模型名转换为各供应商对应的实际模型名
 - **格式双向转换**：自动转换 Anthropic ↔ Gemini 格式，支持非 Anthropic 兼容供应商
@@ -130,14 +130,13 @@ curl http://127.0.0.1:8046/health
 
 ### 4.1 配置文件位置与加载优先级
 
-按以下优先级加载（找到第一个即停止）：
+加载器先按以下顺序查找用户配置文件（找到第一个即停止）：
 
 1. `--config` 参数指定的路径（最高优先级）
 2. `./config.yaml`（项目根目录）
 3. `~/.coding-proxy/config.yaml`（用户主目录）
-4. 内置默认值（无需配置文件也可启动）
 
-加载器以 `config.default.yaml` 为基础模板进行深度合并，用户配置覆盖模板默认值。
+找到用户配置后，以内置 `config.default.yaml` 为基础模板进行**深度合并**，用户配置覆盖模板默认值。未找到用户配置文件时，直接使用模板默认值。
 
 ### 4.2 vendors — 供应商列表
 
@@ -215,7 +214,7 @@ logging:
 
 `primary`, `copilot`, `antigravity`, `fallback`, `circuit_breaker`, `copilot_circuit_breaker`, `antigravity_circuit_breaker`, `quota_guard`, `copilot_quota_guard`, `antigravity_quota_guard`
 
-如果配置文件中使用上述旧格式，系统启动时**自动迁移**至 vendors 格式并输出日志提示。建议尽快迁移至 vendors 新格式。
+当用户配置中**同时不存在** `vendors` 和 `tiers` 字段，但包含上述旧格式字段时，系统启动时**自动迁移**至 vendors 格式并输出日志提示。建议尽快迁移至 vendors 新格式。
 
 ---
 
@@ -226,8 +225,8 @@ logging:
 | 启动代理 | `coding-proxy start` |
 | 查看状态 | `coding-proxy status` |
 | 查看用量 | `coding-proxy usage` |
-| 查看本周 | `coding-proxy usage -w` |
-| 查看本月 | `coding-proxy usage -m` |
+| 查看本周 | `coding-proxy usage -w 1` |
+| 查看本月 | `coding-proxy usage -m 1` |
 | 重置熔断器 | `coding-proxy reset` |
 | 提升供应商 | `coding-proxy reset -v anthropic` |
 | GitHub 登录 | `coding-proxy auth login -p github` |