coding-proxy 0.4.1a3__tar.gz → 0.4.1a5__tar.gz

{coding_proxy-0.4.1a3 → coding_proxy-0.4.1a5}/AGENTS.md

@@ -33,15 +33,13 @@
 ### 术 (Tactics - 执行规范)
 
 - **Structured AI-Pair Pipeline (规范化 AI 结对流水线)**: 遵循 **Specification-Driven (规约驱动)** + **Context-Anchored (上下文锚定)** + **AI-Pair (AI 结对)** 模式，将开发固化为可审计的流水线，避免代码腐化为无法维护的“大泥球 (Big Ball of Mud)”。
-- **Visual Documentation (图文并茂)**: 对于复杂逻辑，优先使用 Mermaid 图表（Sequence/Flowchart/Class）辅助说明，构建“图文并茂”的直观文档。
-- **Direct Hyperlinking (直接跳转)**: 在文档中提及 Repo 内其他资源（文档/代码）时，**必须**构建可跳转的相对路径链接（如 `[Doc Name](./path.md)`），严禁使用“死文本”引用，以降低信息检索熵。
 - **Operational Excellence (卓越运营)**:
   1. **Git Discipline**: 默认严禁调用 git commit；当用户显式要求提交时，一律使用 Claude Code 的自定义 Slash Command: `/commit-no-push` 进行操作（若非 Claude Code 运行环境，则读取 /commit-no-push 命令中的规则执行）。严禁执行 Rebase；
   2. **Temp Management**: 临时产物（执行计划等）一律收敛至 `.temp/` 并及时清理；
   3. **Link Validity**: 确保所有引用的 URL 可访问且具备明确的上下文价值；
   4. **Testing**: 统一在 tests/ 下维护测试用例，区分单元测试（unit）和集成测试（integration），所有测试的本地运行总时间控制在 3 min 以内；
   5. **Pre-commit Hooks**: 首次克隆仓库使用 `uv run pre-commit install` 激活本地 Git hooks，使 Ruff lint（含 auto-fix）、Ruff format 及通用代码卫生检查在每次 commit 前自动运行。若 hooks 自动修复了问题，提交会被中断，执行 `git add -p` 审阅修复内容后重新提交即可；
-  6. **Issue**: 在 docs/issue.md 中维护你处理过的 Issue 摘要（问题描述、表因根因、处理方式、后续防范、同类问题影响与处理注意事项等），便于同类问题的跨上下文处理；注意识别相同 Issue，不要同 Issue 多处维护；
+  6. **Issue**: 在 [issue.md](docs/agents/issue.md) 中维护你处理过的 Issue 摘要（问题描述、表因根因、处理方式、后续防范、同类问题影响与处理注意事项等），便于同类问题的跨上下文处理；注意识别相同 Issue，不要同 Issue 多处维护；
 - **Package Management Standardization (包管理规范)**:
   1. **Python**: 严禁使用 pip/poetry，**必须**统一使用 `uv` 进行包管理与脚本执行（如 `uv run`）；
   2. **JavaScript/TypeScript**: 严禁使用 npm/yarn，**必须**统一使用 `pnpm` 进行包管理与脚本执行；
@@ -49,7 +47,11 @@
 - **Browser Validation Protocol (浏览器验证准则)**：Agent 不得自行完成、绕过或模拟任何 OAuth / SSO 认证流程，所有登录态均来源于用户已认证的 Chrome 主 profile（真实用户登录态）。完整协议（连通性自检、凭证管理、E2E 集成、实机回归等）详见 [浏览器验证协议](./docs/agents/browser-validation.md)；
   1. **安全红线**：禁止在 Sandbox 浏览器中跳转 Google 同意屏；禁止以模拟用户或第三方账号替代真实登录态；禁止要求用户在 chat 中粘贴密码、Cookie 或验证码；
 - **Knowledge Map (知识索引)**：项目所有文档索引统一维护在 [知识索引](./docs/agents/knowledge-map.md)，并在文档目录变更时即时同步跟新；
-- **Documentation Standards (文档规范)**：采用**Mermaid Visualization Norms (Mermaid 可视化规范)**；
-  1. **色彩语义与兼容性**：为图表节点配置具备语义辨识度的色彩，并确保在深色模式（Dark Mode）下具有极高的对比度与清晰度；
-  2. **逻辑模块化解构**：针对业务跨度较大的架构流程，强制采用 `subgraph` 容器进行层级解构与边界划分，以增强图表的自解说（Self-explaining）能力；
+- **Documentation Standards (文档规范)**：
+  1. **Visual Documentation (图文并茂)**: 对于复杂逻辑，优先 **Mermaid Visualization Norms (Mermaid 可视化规范)**，构建“图文并茂”的直观文档；
+     - **色彩语义与兼容性**：为图表节点配置具备语义辨识度的色彩，并确保在深色模式（Dark Mode）下具有极高的对比度与清晰度；
+     - **逻辑模块化解构**：针对业务跨度较大的架构流程，强制采用 `subgraph` 容器进行层级解构与边界划分，以增强图表的自解说（Self-explaining）能力；
+  2. **语言叙事**：用语精准，叙事完备，行文专业，聚焦核心，篇幅精炼，形象具体，体现真实作用与用户吸引性，字数恰当；
+  3. **Direct Hyperlinking (直接跳转)**: 在文档中提及 Repo 内其他资源（文档/代码）时，**必须**构建可跳转的相对路径链接（如 `[Doc Name](./path.md)`），严禁使用“死文本”引用，以降低信息检索熵；
+  4. **实操截图**：文档需要引入必要的浏览器实操截图时，需自行通过默认浏览器打开相关页面，通过实操现场截图并保留到文档路径进行文档引用；
 - **Reference Specifications (IEEE)**：为保障工程决策的可追溯性与学术严谨性，核心引用需遵循 [reference-specifications.md](docs/agents/reference-specifications.md)IEEE 标准引用格式；

{coding_proxy-0.4.1a3 → coding_proxy-0.4.1a5}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: coding-proxy
-Version: 0.4.1a3
+Version: 0.4.1a5
 Summary: A High-Availability, Transparent, and Smart Multi-Vendor Proxy for Claude Code. Support Claude Plans, GitHub Copilot, Google Antigravity, ZAI/GLM, MiniMax, Qwen, Xiaomi, Kimi, Doubao...
 Project-URL: Source Code, https://github.com/ThreeFish-AI/coding-proxy
 Project-URL: User Guide, https://github.com/ThreeFish-AI/coding-proxy/blob/master/docs/user-guide.md

coding_proxy-0.4.1a5/docs/agents/browser-validation.md

@@ -0,0 +1,172 @@
+# Browser Validation Protocol（浏览器验证协议）
+
+> 由 [AGENTS.md §Browser Validation Protocol](../../AGENTS.md) 锚定的浏览器自动化与认证态使用协议。本协议是工程行为准则的子集，**任何 AI Agent 在执行浏览器自动化任务前必须完整遵循**。
+>
+> **协议版本**：v1.0 ｜ **生效范围**：所有面向本仓库的 AI Agent 协作场景
+>
+> **关联工具**：`chrome-devtools` MCP、`claude-in-chrome` MCP、`playwright` MCP
+
+[TOC]
+
+---
+
+## 1. 协议目的
+
+为 AI Agent 在浏览器自动化场景下提供**统一、可审计、不可绕过**的认证态使用规范，解决以下问题：
+
+- AI Agent 不应也不可代用户决策"我是谁"——所有登录态归属问题必须由用户本人主导
+- 浏览器自动化能力一旦失控，可能在用户毫不知情时产生不可撤销的副作用（消息发送、订单提交、权限变更等）
+- OAuth / SSO 同意屏在自动化上下文中存在被绕过的潜在风险，违反平台 ToS 与基本伦理
+
+本协议通过"原则—红线—操作流程—验证"四层结构，将上述问题约束在工程可控范围内。
+
+---
+
+## 2. 核心原则
+
+| 原则                       | 具体含义                                                                                              |
+| -------------------------- | ----------------------------------------------------------------------------------------------------- |
+| **登录态归属于用户**       | Agent 不得自行完成、绕过或模拟任何 OAuth / SSO 认证流程；所有登录态来源于用户已认证的 Chrome 主 profile |
+| **真实主 profile 优先**    | 浏览器自动化默认接入用户日常使用的 Chrome 主 profile，复用其 Cookie / Session / SSO 状态              |
+| **可审计、可回放**         | 浏览器路径关键操作（点击、表单填写、跳转）应留下可被 GIF 回放或日志追溯的痕迹                         |
+| **最小副作用**             | 优先以只读方式（查看、提取、断言）完成任务；写操作（提交、发送）需在协议第 5 节框架下显式确认         |
+
+---
+
+## 3. 安全红线
+
+> 以下条款**不可协商**，违反任一条款即视为协议违反。
+
+1. **禁止跳转 Google 同意屏**：在 Sandbox / 自动化浏览器环境内**严禁**触发 Google OAuth 同意屏跳转。同意屏只能在用户主 profile 的真实浏览会话中由用户本人完成。
+2. **禁止模拟身份**：禁止以模拟用户身份、虚构 Cookie、第三方账号或测试账号替代真实登录态完成任务。
+3. **禁止凭证泄露**：禁止要求用户在 chat 中粘贴密码、Cookie、Session Token、二维码扫描结果或任何形式的验证码（含 6 位数字、短信、TOTP）。
+4. **禁止跨账号操作**：在多用户环境下，Agent 不得在未经显式确认的情况下切换 profile 或账号身份。
+5. **禁止规避 ToS**：不得通过 Headless 模式、UA 伪装、Captcha 自动求解等方式规避目标站点的服务条款。
+6. **禁止下载执行**：浏览器路径触发的任何文件下载需在主对话中显式确认；下载文件不得自动执行或注入到项目目录。
+
+---
+
+## 4. 连通性自检（Connectivity Probe）
+
+执行浏览器自动化任务前，Agent **必须**完成以下自检序列：
+
+| 步骤                  | 操作                                                              | 通过判据                                                  |
+| --------------------- | ----------------------------------------------------------------- | --------------------------------------------------------- |
+| 4.1 工具可用性        | 列出当前会话可用的 MCP 工具                                       | 至少存在 `chrome-devtools` / `claude-in-chrome` 之一      |
+| 4.2 主 profile 加载   | 通过工具调用获取当前 Tab 列表或 Page 列表                         | 返回非空，且 Tab 标题来自用户真实浏览历史而非空白会话     |
+| 4.3 目标域名可达      | 通过 `navigate_page` 或 `browser_navigate` 访问目标域名首页       | HTTP 200 / 已登录态正常加载                               |
+| 4.4 登录态识别        | 在目标域名首页定位"已登录"标识（头像、用户名、退出按钮）          | 能在 Snapshot / AOM 中找到一致标识                        |
+| 4.5 异常路径分类      | 若 4.4 失败，按"未登录 vs 会话过期 vs 拒绝服务"分类，**不**自动重登 | 输出明确分类，转入第 5 节的用户接力流程                   |
+
+> **失败处置**：自检任一步骤失败，Agent **必须**停止任务、向用户输出诊断结论，**不得**尝试 OAuth / 凭证补救。
+
+---
+
+## 5. 凭证管理（Credential Lifecycle）
+
+### 5.1 发现路径
+
+凭证通过以下路径**被动**发现，Agent **不**主动读取、导出或日志化：
+
+- 浏览器 Cookie / LocalStorage（仅由浏览器引擎内部使用）
+- 浏览器扩展（如 Claude in Chrome）持有的 Session
+- 用户在 chat 中以"我刚登录了 X"形式给出的事实陈述（非凭证本身）
+
+### 5.2 过期检测信号
+
+| 信号                                     | 处置                                            |
+| ---------------------------------------- | ----------------------------------------------- |
+| HTTP 401 / 403                           | 转 5.3 接力流程                                 |
+| 重定向到登录页（含 `/login`、`/signin`） | 转 5.3 接力流程                                 |
+| 同意屏触发（OAuth scope 变更）           | **立即停止**，由用户在主 profile 完成同意       |
+| Captcha 出现                             | **立即停止**，输出"需用户介入"                  |
+
+### 5.3 用户接力流程（Re-authentication Handoff）
+
+```
+1. Agent 检测到登录态失效
+2. Agent 向用户输出：（a）失效域名 （b）建议在用户主 profile 完成登录的指引
+3. Agent 暂停浏览器任务，**不**触发任何登录流程
+4. 用户在真实浏览器完成登录后，回到 chat 通知 Agent
+5. Agent 重新执行第 4 节连通性自检
+6. 自检通过后恢复任务
+```
+
+### 5.4 凭证刷新约束
+
+- Agent **不**调用任何 refresh_token / device_code 接口
+- Agent **不**触发邮箱链接、短信验证码、TOTP 输入
+- 凭证刷新由用户在原始登录路径自主完成
+
+---
+
+## 6. E2E 集成（End-to-End Integration）
+
+### 6.1 与项目 OAuth 模块的边界
+
+本项目内置 GitHub Device Flow 与 Google OAuth 模块（`src/coding/proxy/auth/`）。浏览器协议与之的边界如下：
+
+- **项目 OAuth 模块**：服务端运行时凭证管理，由 `coding-proxy auth login/reauth` CLI 触发，目标是给 **proxy 自身**获取上游 API 凭证
+- **本协议**：客户端浏览器自动化场景，目标是让 **Agent 协助用户**完成日常任务（如查文档、填表单）
+
+二者**互不调用**：Agent 不调用 `coding-proxy auth` 替用户完成项目 OAuth；项目 OAuth 流程也不依赖本协议第 4 节自检。
+
+### 6.2 与 CLI 命令的协同
+
+| 场景                            | 由谁触发                  |
+| ------------------------------- | ------------------------- |
+| 给 proxy 注入 GitHub PAT        | 用户运行 `auth login`     |
+| 给 proxy 注入 Google OAuth      | 用户运行 `auth login`     |
+| 凭证过期重认证                  | 用户运行 `auth reauth`    |
+| 浏览器查看 GitHub Token 状态    | Agent 通过本协议浏览器访问 |
+
+### 6.3 测试用例的浏览器隔离
+
+- 单元测试（`tests/unit/`）**不**触发任何浏览器路径
+- 集成测试（`tests/integration/`）**不**触发任何浏览器路径
+- 浏览器路径仅在交互式 Agent 会话中触发，不进入 CI 自动化测试链路
+
+---
+
+## 7. 实机回归（Real-Device Regression）
+
+### 7.1 提交前的浏览器路径自检清单
+
+涉及浏览器路径的改动在提交前需手工核验：
+
+- [ ] 第 4 节连通性自检在用户主 profile 通过
+- [ ] 第 3 节安全红线未被触碰（特别是同意屏、密码粘贴）
+- [ ] 浏览器路径的关键操作有 GIF / Snapshot 留痕
+- [ ] 失败路径输出明确的用户接力指引
+
+### 7.2 与 CI 的边界
+
+CI 流水线（详见 [ops/ci-cd.md](../ops/ci-cd.md)）**不**触发浏览器自动化路径。所有浏览器侧验证均在本地实机完成。
+
+### 7.3 回归失败上报
+
+若实机回归失败：
+
+1. 在 [docs/issue.md](../issue.md) 记录现象、根因、防范
+2. 若涉及协议本身缺陷，提交 PR 修订本文件并同步 [AGENTS.md](../../AGENTS.md) 锚点
+3. 不通过的 Agent 行为应在 [knowledge-map.md](./knowledge-map.md) 标注为已知问题
+
+---
+
+## 8. 引用规范
+
+- 本协议章节可被 [AGENTS.md](../../AGENTS.md) / [CLAUDE.md](../../CLAUDE.md) 通过标题锚点形式引用
+- 修订本协议**必须**在 [docs/issue.md](../issue.md) 留存背景与决策记录
+- 协议条款发生变更时，需同步检查 [AGENTS.md §Browser Validation Protocol](../../AGENTS.md) 的兜底原则与本协议是否一致
+
+---
+
+## 附录 A：术语对照
+
+| 术语                | 说明                                                              |
+| ------------------- | ----------------------------------------------------------------- |
+| 主 profile          | 用户日常使用的 Chrome / Edge 浏览器档案，含真实登录态             |
+| Sandbox 浏览器      | 自动化工具启动的临时/隔离浏览器，无真实用户态                     |
+| 同意屏（Consent）   | OAuth 流程中用户授予权限范围的页面                                |
+| 接力流程            | Agent 停止 → 用户介入完成 → Agent 恢复 的三段式协作               |
+| 实机回归            | 在用户真实终端（非 CI）完成的端到端验证                           |

{coding_proxy-0.4.1a3/docs → coding_proxy-0.4.1a5/docs/agents}/issue.md

@@ -186,3 +186,47 @@ litellm 按 Google AI Studio 格式构造请求：
 
 - litellm 在 Gemini 其他端点（`generateContent` / `countTokens`）同样存在 `_check_custom_proxy` 丢失 `v1beta/` 前缀的 bug；本次仅放宽了 `operation.py` 中的路径正则（让分类器能识别此类异常路径），未对这些端点做格式转换，因为非 embedding 端点的 Google AI Studio / Vertex AI 请求体差异较小，多数上游兼容。如未来出现类似失配再做针对性适配。
 - 若上游网关同时支持 OpenAI `/v1/embeddings` 与 Vertex AI 路径，建议优先在客户端配置 OpenAI 兼容路径，减少协议转换链路。
+
+---
+
+## Dashboard Sessions 页 `Tokens` 列漏算缓存 Token
+
+**问题描述**
+
+Dashboard 的 **Sessions** 标签页中，每条会话的 `Tokens` 列与展开详情卡的 `Tokens` 值，仅统计 `input + output`，遗漏了 `cache_creation`（写缓存）与 `cache_read`（读缓存）。在长链路 Anthropic Prompt Cache 场景下，读取命中常常是 input/output 的数倍，导致 Sessions 页总量被显著低估，与 Overview 标签页（卡片、Token 时序图）跨页口径分裂。
+
+**表因**
+
+前端 `dashboard.py:1597 / 1614` 直接渲染 `s.total_tokens`，该值由 `/api/dashboard/sessions` 透传自 `token_logger.query_recent_sessions()` 的聚合结果。
+
+**根因**
+
+`src/coding/proxy/logging/db.py` 中两条按 `session_key` 分组的聚合 SQL 使用了不完整的求和口径：
+
+```sql
+SUM(input_tokens + output_tokens) AS total_tokens   -- 第 607 行（query_recent_sessions）
+SUM(input_tokens + output_tokens) AS total_tokens   -- 第 634 行（query_session_profile）
+```
+
+而同文件内 `query_usage()`（第 465–466 行分别 `SUM(...)` 四列）与 `query_total_tokens_by_vendor()`（第 584 行 `SUM(input + output + cache_creation + cache_read)`）已采用完整四项口径，构成了同文件内的口径双标。
+
+**处理方式**
+
+复用 `query_total_tokens_by_vendor` 的四项求和表达式，将两处 `total_tokens` 改写为：
+
+```sql
+SUM(input_tokens + output_tokens
+    + cache_creation_tokens + cache_read_tokens) AS total_tokens
+```
+
+不改动 API 返回结构、不新增字段、不改前端 detail-card——前端 `fmtTokens(s.total_tokens)` 调用无须变更。同时在 `tests/test_session_aware.py` 的 `test_query_recent_sessions_basic` / `test_query_session_profile_found` 中追加 `cache_creation_tokens` / `cache_read_tokens` 入参与完整口径断言，覆盖回归。
+
+**后续防范**
+
+- SQL 聚合层涉及"总 Tokens"概念时，必须保持**单一权威定义**（Single Source of Truth）：要么所有视图共用同一求和表达式，要么抽取为常量片段集中引用，杜绝多处独立维护造成的语义漂移。
+- 未来若引入新的 token 维度（如 reasoning_tokens、tool_tokens 等），需要全文检索 `SUM(input_tokens + output_tokens` 这一历史模式并同步补齐，避免出现新的口径分裂点。
+
+**同类问题影响与处理注意事项**
+
+- 历次 PR 中 cache token 字段的引入是渐进式的（schema 已有四列、`log()` 入参齐全、Overview 已全口径消费），但部分聚合视图的口径升级被遗漏；任何向 `usage_log` 增列后，**必须**审计所有 `SUM(input_tokens` / `SUM(output_tokens` 出现处的聚合表达式是否需要同步更新。
+- 跨标签页同一指标（如"总 Tokens"）的口径一致性，建议在添加新视图时主动与 Overview 现有口径做交叉核对，必要时在 SQL 注释中标注口径来源，便于后续 review。

coding_proxy-0.4.1a5/docs/agents/knowledge-map.md

@@ -0,0 +1,95 @@
+# Knowledge Map（知识索引）
+
+> 项目所有文档的统一入口与权威索引。由 [AGENTS.md §Knowledge Map](../../AGENTS.md) 锚定，文档目录变更时**必须**即时同步更新本文件。
+>
+> **使用方式**：按"受众 × 目的"二维定位所需文档；不确定起点时，从「入口导航」开始。
+
+[TOC]
+
+---
+
+## 1. 入口导航
+
+| 文档                                          | 角色                                            | 受众            |
+| --------------------------------------------- | ----------------------------------------------- | --------------- |
+| [README.md](../../README.md)                  | 项目首页（英文版门面）                          | 公开访客        |
+| [docs/zh-CN/README.md](../zh-CN/README.md)    | 项目首页中文镜像（与英文版功能对等）            | 中文公开访客    |
+| [docs/user-guide.md](../user-guide.md)        | 用户操作上位导航 + 配置概览速查                 | 终端用户        |
+| [docs/framework.md](../framework.md)          | 架构枢纽（项目动机、设计目标、模块清单）        | 架构师/贡献者   |
+
+---
+
+## 2. 用户向（[docs/guide/](../guide/)）
+
+> 面向最终用户的操作手册，按"安装 → 配置 → 运行 → 观测 → 排障"线性铺陈。
+
+| 文档                                              | 主旨                                                |
+| ------------------------------------------------- | --------------------------------------------------- |
+| [guide/quickstart.md](../guide/quickstart.md)     | 环境要求、安装、最小配置、启动、Claude Code 集成    |
+| [guide/vendors.md](../guide/vendors.md)           | 全部 9 种供应商配置详情、模型映射、定价表           |
+| [guide/cli-reference.md](../guide/cli-reference.md) | start / status / usage / reset / auth 全部命令      |
+| [guide/api-reference.md](../guide/api-reference.md) | /v1/messages、health、status、reset、dashboard 等   |
+| [guide/dashboard.md](../guide/dashboard.md)       | Web 可视化看板功能与交互                            |
+| [guide/monitoring.md](../guide/monitoring.md)     | 日志、用量统计、性能调优、常见场景、故障排查        |
+
+---
+
+## 3. 架构向（[docs/arch/](../arch/)）
+
+> 面向贡献者与维护者的架构与实现细节，从 [framework.md](../framework.md) 正交分解而来。
+
+| 文档                                                  | 主旨                                                  |
+| ----------------------------------------------------- | ----------------------------------------------------- |
+| [arch/config-reference.md](../arch/config-reference.md) | 配置参数权威定义（Single Source of Truth）            |
+| [arch/design-patterns.md](../arch/design-patterns.md) | 13 种设计模式详解（熔断器、状态机、Composite 等）     |
+| [arch/routing.md](../arch/routing.md)                 | 路由引擎 12 个子模块职责                              |
+| [arch/vendors.md](../arch/vendors.md)                 | Vendor 类层次结构与 9 种实现                          |
+| [arch/convert.md](../arch/convert.md)                 | Anthropic ↔ Gemini ↔ OpenAI 三向格式转换              |
+| [arch/testing.md](../arch/testing.md)                 | 测试覆盖矩阵与工具链                                  |
+
+---
+
+## 4. 运维向（[docs/ops/](../ops/)）
+
+> 面向运维与发布工程的流程文档。
+
+| 文档                                | 主旨                                              |
+| ----------------------------------- | ------------------------------------------------- |
+| [ops/ci-cd.md](../ops/ci-cd.md)     | 发布流程、热修复、回滚、CI/CD 故障排查            |
+
+---
+
+## 5. Agent 协作（[docs/agents/](./)）
+
+> AGENTS.md 工程行为准则的卫星文件，定义 AI Agent 协作过程中的规范与协议。
+
+| 文档                                                            | 主旨                                          |
+| --------------------------------------------------------------- | --------------------------------------------- |
+| [agents/knowledge-map.md](./knowledge-map.md)                   | 本文件——项目文档统一索引                      |
+| [agents/reference-specifications.md](./reference-specifications.md) | IEEE 文献引用格式模板与实践指南               |
+| [agents/browser-validation.md](./browser-validation.md)         | 浏览器验证协议（连通性自检、凭证管理、E2E）   |
+
+---
+
+## 6. 问题档案
+
+| 文档                              | 主旨                                                  |
+| --------------------------------- | ----------------------------------------------------- |
+| [docs/issue.md](../issue.md)      | 已处理 Issue 摘要档案（表因、根因、防范）              |
+
+---
+
+## 7. 工程规范（顶层）
+
+| 文档                              | 主旨                                                  |
+| --------------------------------- | ----------------------------------------------------- |
+| [AGENTS.md](../../AGENTS.md)      | 工程行为准则与 AI Agent 协作协议（与 CLAUDE.md 同源） |
+| [CHANGELOG.md](../../CHANGELOG.md)| 版本历史与变更日志                                    |
+
+---
+
+## 维护约束
+
+1. **同步原则**：新增/删除/重命名 `docs/` 下任意 .md 文件时，**必须**同步本索引。
+2. **路径基准**：本文件位于 `docs/agents/`，所有相对路径以此为基准（向上一级 `../` 访问 `docs/`，向上两级 `../../` 访问仓库根）。
+3. **链接验证**：维护者修改本文件后应通过 grep 自检：所有 `[...](path)` 中的 `path` 文件存在。

{coding_proxy-0.4.1a3 → coding_proxy-0.4.1a5}/docs/arch/vendors.md

@@ -1,7 +1,7 @@
 # 供应商模块（vendors/）
 
 > 路径约定：相对于 `src/coding/proxy/`
-> 定位：从 [framework.md](./framework.md) 提取，详述供应商分类体系与各供应商实现。
+> 定位：从 [framework.md](../framework.md) 提取，详述供应商分类体系与各供应商实现。
 
 [TOC]
 

{coding_proxy-0.4.1a3/docs → coding_proxy-0.4.1a5/docs/ops}/ci-cd.md

@@ -211,7 +211,7 @@ CI 流水线中使用的工具及其版本均与项目实际配置严格对齐
 
 | 工具           | 版本 / 引用                         | 来源 (Action)                            | 与项目配置的对齐关系                                                       |
 | -------------- | ----------------------------------- | ---------------------------------------- | -------------------------------------------------------------------------- |
-| Python         | `["3.12", "3.13", "3.14"]` (matrix) | `actions/setup-python@v5`                | 对齐 [`pyproject.toml`](../pyproject.toml) 中 `requires-python = ">=3.12"` |
+| Python         | `["3.12", "3.13", "3.14"]` (matrix) | `actions/setup-python@v5`                | 对齐 [`pyproject.toml`](../../pyproject.toml) 中 `requires-python = ">=3.12"` |
 | uv             | latest (v4)                         | `astral-sh/setup-uv@v4`                  | 项目强制包管理器（见 AGENTS.md 包管理规范）                                |
 | build          | latest                              | `uv pip install --system build`          | PEP 517 构建前端，后端为 hatchling                                         |
 | twine          | latest                              | `uv pip install --system twine`          | 包元数据校验与上传工具                                                     |
@@ -435,7 +435,7 @@ flowchart TD
 
 ### 4.1 promote.yml 工作流架构
 
-[`promote.yml`](../.github/workflows/promote.yml) 由两个 Job 组成，形成 **Validate → Promote** 的串行管线：
+[`promote.yml`](../../.github/workflows/promote.yml) 由两个 Job 组成，形成 **Validate → Promote** 的串行管线：
 
 #### Job 1：validate（验证门控）
 
@@ -629,7 +629,7 @@ flowchart TD
 | 问题现象                        | 可能原因                                               | 排查步骤                                              | 解决方案                                                  |
 | ------------------------------- | ------------------------------------------------------ | ----------------------------------------------------- | --------------------------------------------------------- |
 | `release.yml` 未触发            | Release 创建时未触发 `published` 事件（如 Draft 状态） | 检查 Actions 页面是否有该 workflow run                | 确保 Release 为非 Draft 状态；或重新发布                  |
-| `build` Job 失败                | `twine check` 报错（包元数据不合规）                   | 查看 build Job 日志中的 twine 输出                    | 修复 [`pyproject.toml`](../pyproject.toml) 中的元数据字段 |
+| `build` Job 失败                | `twine check` 报错（包元数据不合规）                   | 查看 build Job 日志中的 twine 输出                    | 修复 [`pyproject.toml`](../../pyproject.toml) 中的元数据字段 |
 | publish 失败 (HTTP 400)         | 包名或版本号冲突（目标仓库已有同版本）                 | 查看 verbose 日志中的响应体（已启用 `verbose: true`） | 检查 TestPyPI/PyPI 是否已有同版本；使用递增版本号         |
 | publish 失败 (HTTP 403)         | 认证失败（Token 无效或缺失）                           | 检查 Job 日志中的认证错误详情                         | 验证 Secret 配置或 Trusted Publisher 设置（参见 §7.2）    |
 | `promote.yml` validate 失败     | Target release 不是 prerelease（已是 stable）          | 查看 validate Job 错误信息                            | 确认输入的 `tag_name` 对应的是 prerelease release         |
@@ -701,7 +701,7 @@ CI 流水线中的工具版本选择并非随意，每一项都与项目配置
 
 | CI 配置                                          | 项目配置                                                              | 对齐关系                                                                    |
 | ------------------------------------------------ | --------------------------------------------------------------------- | --------------------------------------------------------------------------- |
-| `python-version: "${{ matrix.python-version }}"` | `requires-python = ">=3.12"` in [`pyproject.toml`](../pyproject.toml) | CI 构建环境必须满足项目的最低 Python 版本要求（matrix: 3.12 / 3.13 / 3.14） |
+| `python-version: "${{ matrix.python-version }}"` | `requires-python = ">=3.12"` in [`pyproject.toml`](../../pyproject.toml) | CI 构建环境必须满足项目的最低 Python 版本要求（matrix: 3.12 / 3.13 / 3.14） |
 | `hatchling.build` (build-backend)                | `[build-system] requires = ["hatchling"]`                             | 构建后端声明必须一致                                                        |
 | `uv pip install --system`                        | AGENTS.md 强制使用 `uv`                                               | GitHub Actions Runner 默认无激活的 virtualenv，需 `--system` 标志           |
 | `retention-days: 14`                             | —                                                                     | Artifact 保留两周，覆盖正常的验证窗口期（通常 1-3 天）                      |
@@ -714,7 +714,7 @@ CI 流水线中的工具版本选择并非随意，每一项都与项目配置
 
 ### 8.1 release.yml 结构索引
 
-[`.github/workflows/release.yml`](../.github/workflows/release.yml) 文件结构一览：
+[`.github/workflows/release.yml`](../../.github/workflows/release.yml) 文件结构一览：
 
 | 行范围  | 区块                    | 内容摘要                                                                                             |
 | ------- | ----------------------- | ---------------------------------------------------------------------------------------------------- |
@@ -729,7 +729,7 @@ CI 流水线中的工具版本选择并非随意，每一项都与项目配置
 
 ### 8.2 promote.yml 结构索引
 
-[`.github/workflows/promote.yml`](../.github/workflows/promote.yml) 文件结构一览：
+[`.github/workflows/promote.yml`](../../.github/workflows/promote.yml) 文件结构一览：
 
 | 行范围 | 区块            | 内容摘要                                                       |
 | ------ | --------------- | -------------------------------------------------------------- |

{coding_proxy-0.4.1a3 → coding_proxy-0.4.1a5}/pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "coding-proxy"
-version = "0.4.1a3"
+version = "0.4.1a5"
 description = "A High-Availability, Transparent, and Smart Multi-Vendor Proxy for Claude Code. Support Claude Plans, GitHub Copilot, Google Antigravity, ZAI/GLM, MiniMax, Qwen, Xiaomi, Kimi, Doubao..."
 readme = "README.md"
 requires-python = ">=3.12"

{coding_proxy-0.4.1a3 → coding_proxy-0.4.1a5}/src/coding/proxy/convert/vendor_channels.py

@@ -367,6 +367,57 @@ def _strip_cache_control(body: dict[str, Any]) -> int:
     return removed
 
 
+# ── zhipu 共享清洗函数 ──────────────────────────────────────────
+
+# 跨供应商转换时主动剥离的顶层参数（首选 tier 场景由 _prepare_request 原样透传，
+# GLM 原生支持 thinking / 静默忽略 cache_control 和 reasoning_effort，不会触发 400）。
+_ZHIPU_UNSUPPORTED_PARAMS: frozenset[str] = frozenset(
+    {"thinking", "extended_thinking", "reasoning_effort"}
+)
+
+
+def normalize_for_zhipu(body: dict[str, Any]) -> tuple[dict[str, Any], list[str]]:
+    """为 zhipu GLM 的 Anthropic 兼容端点清洗请求体（就地，不 deep copy）.
+
+    为跨供应商转换通道 ``prepare_copilot_to_zhipu`` 提供请求体清洗。
+
+    清洗内容：
+    1. 剥离 cache_control 字段（GLM 静默忽略，主动剥离以减少噪音）
+    2. 移除顶层 thinking/extended_thinking/reasoning_effort 参数（GLM 原生支持
+       thinking、静默忽略 reasoning_effort，但跨供应商场景下这些参数来自原供应商
+       的协议语义，主动剥离以确保请求语义一致性）
+    3. 强制 tool_use/tool_result 配对约束
+
+    不包含 thinking blocks 剥离：跨供应商场景下 history 中的 thinking blocks
+    来自原供应商（签名失效），由调用方在调用本函数之前通过
+    ``strip_thinking_blocks`` 单独处理。
+
+    所有操作均为幂等，安全地在已清洗的请求体上重复调用。
+
+    Returns:
+        (body, adaptations) — body 为就地修改后的同一引用，adaptations 为变换描述列表。
+    """
+    adaptations: list[str] = []
+
+    # Step 1: 剥离 cache_control
+    removed_cc = _strip_cache_control(body)
+    if removed_cc:
+        adaptations.append(f"removed_{removed_cc}_cache_control_fields")
+
+    # Step 2: 移除不支持的顶层参数
+    for param in _ZHIPU_UNSUPPORTED_PARAMS:
+        if param in body:
+            del body[param]
+            adaptations.append(f"removed_{param}_param")
+
+    # Step 3: 强制 tool_use/tool_result 配对
+    pairing_fixes = enforce_anthropic_tool_pairing(body.get("messages", []))
+    if pairing_fixes:
+        adaptations.extend(pairing_fixes)
+
+    return body, adaptations
+
+
 def _remove_vendor_blocks(body: dict[str, Any], block_types: set[str]) -> int:
     """从 messages[].content[] 中就地移除指定 type 的内容块.
 
@@ -544,26 +595,14 @@ def prepare_copilot_to_zhipu(
     prepared = copy.deepcopy(body)
     adaptations: list[str] = []
 
-    # Step 1: 剥离 thinking/redacted_thinking 块
+    # Step 1: 剥离 thinking/redacted_thinking 块（跨供应商签名失效）
     stripped = strip_thinking_blocks(prepared)
     if stripped:
         adaptations.append(f"stripped_{stripped}_thinking_blocks")
 
-    # Step 2: 移除 cache_control 字段
-    removed_cc = _strip_cache_control(prepared)
-    if removed_cc:
-        adaptations.append(f"removed_{removed_cc}_cache_control_fields")
-
-    # Step 3: 移除顶层 thinking/extended_thinking 参数（GLM-5 不支持）
-    for param in ("thinking", "extended_thinking"):
-        if param in prepared:
-            del prepared[param]
-            adaptations.append(f"removed_{param}_param")
-
-    # Step 4: 强制 tool_use/tool_result 配对
-    pairing_fixes = enforce_anthropic_tool_pairing(prepared.get("messages", []))
-    if pairing_fixes:
-        adaptations.extend(pairing_fixes)
+    # Step 2: 共享清洗（cache_control、不支持的顶层参数、tool pairing）
+    _, norm_adaptations = normalize_for_zhipu(prepared)
+    adaptations.extend(norm_adaptations)
 
     return prepared, adaptations
 

{coding_proxy-0.4.1a3 → coding_proxy-0.4.1a5}/src/coding/proxy/logging/db.py

@@ -604,7 +604,8 @@ class TokenLogger:
                       MIN(ts) AS first_seen_ts,
                       MAX(ts) AS last_active_ts,
                       COUNT(*) AS total_requests,
-                      SUM(input_tokens + output_tokens) AS total_tokens,
+                      SUM(input_tokens + output_tokens
+                          + cache_creation_tokens + cache_read_tokens) AS total_tokens,
                       SUM(input_tokens) AS total_input,
                       SUM(output_tokens) AS total_output,
                       GROUP_CONCAT(DISTINCT model_served) AS models,
@@ -631,7 +632,8 @@ class TokenLogger:
                       MIN(ts) AS first_seen_ts,
                       MAX(ts) AS last_active_ts,
                       COUNT(*) AS total_requests,
-                      SUM(input_tokens + output_tokens) AS total_tokens,
+                      SUM(input_tokens + output_tokens
+                          + cache_creation_tokens + cache_read_tokens) AS total_tokens,
                       SUM(input_tokens) AS total_input,
                       SUM(output_tokens) AS total_output,
                       GROUP_CONCAT(DISTINCT model_served) AS models,

{coding_proxy-0.4.1a3 → coding_proxy-0.4.1a5}/src/coding/proxy/routing/executor.py

@@ -602,9 +602,11 @@ class _RouteExecutor:
 
                 if not is_last and is_semantic:
                     logger.warning(
-                        "Tier %s semantic rejection (%s), trying next tier without recording failure",
+                        "Tier %s semantic rejection (type=%s, msg=%s), "
+                        "trying next tier without recording failure",
                         tier.name,
                         resp.error_type or resp.status_code,
+                        (resp.error_message or "N/A")[:200],
                     )
                     failed_tier_name = tier.name
                     continue