From d4e7e2672c06525b6c09c614eaf507a799476d54 Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?=E5=8D=BF=E4=BA=91=E7=A7=8B=E6=9C=88?= <15273589815@163.com>
Date: Fri, 11 Sep 2026 13:43:46 +0800
Subject: [PATCH] =?UTF-8?q?docs(25):=20=E6=9B=B4=E6=AD=A3=20P1=20#2=20?=
 =?UTF-8?q?=E7=9A=84=E5=AE=9A=E6=80=A7=E2=80=94=E2=80=94=E6=A8=A1=E5=9E=8B?=
 =?UTF-8?q?=E8=87=AA=E5=BB=BA=E5=AE=A2=E6=88=B7=E7=AB=AF=E6=98=AF=E5=9F=BA?=
 =?UTF-8?q?=E5=BA=A7=E8=83=BD=E5=8A=9B=E7=BC=BA=E5=8F=A3=EF=BC=8C=E4=B8=8D?=
 =?UTF-8?q?=E6=98=AF=E8=BF=9D=E8=A7=84?=
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

复核时发现原修复建议（"改走 ModelGenerationService，或用 self.generate_with_model"）
**前提不成立**：

- OpenAICompatibleGateway.generate(endpoint_code, prompt, timeout_ms) -> str
  （model_gateway.py:57）与 ModelDispatchService.generate(endpoints, prompt) -> ModelExecution
  （:248）都是"给一段 prompt、拿一段文本"；ModelExecution 的字段只有
  (endpoint_code, text, attempts, degraded)（:226-231）。
- 而风控需要的是 **messages 数组 + tools（function calling）+ 解析 tool_calls**，
  基座完全没有这种形态的入口。

所以这不是"绕过"，是基座缺能力时的补位，而且补得规矩：端点选择直接用基座的
DatabaseModelEndpointResolver；降级策略与 ModelDispatchService.generate 一致
（顺序尝试 + max_attempts 默认 2）；错误映射也复用基座同一套
UpstreamTimeoutError / DependencyUnavailableError。

仍成立的两点：① bootstrap.py:262-265 的 lambda 让 model_client 注入点形同虚设，
无论走哪条路都该改；② HTTP 调用逻辑与 gateway 重复了一份，gateway 将来的限流/成本统计
风控享受不到。

**正确的修法比原建议大**：给基座**新增** chat(messages, tools) 形态的入口
（ModelGateway → OpenAICompatibleGateway → ModelDispatchService → ModelGenerationService
→ BaseAgent），再让风控改用。因为只是新增方法、不改现有行为，对已有 Agent 零影响；
但涉及基座核心链路，是否做需要项目方定，**本轮未实施**。
---
 docs/25-风控模块代码评审报告.md | 37 ++++++++++++++++++++++++++++++---
 1 file changed, 34 insertions(+), 3 deletions(-)

diff --git a/docs/25-风控模块代码评审报告.md b/docs/25-风控模块代码评审报告.md
index 591239f..eca781f 100644
--- a/docs/25-风控模块代码评审报告.md
+++ b/docs/25-风控模块代码评审报告.md
@@ -21,7 +21,8 @@
 问题集中在**三条断线**和**一批业务正确性缺陷**：
 
 1. **运行期配置没发布** → 风控在当前环境**跑不起来**；
-2. **模型调用绕过基座的模型服务** → 治理链路断了一环；
+2. ~~**模型调用绕过基座的模型服务** → 治理链路断了一环；~~
+   **复核后更正：这是基座的能力缺口（缺 chat + tools 形态的入口），不是风控违规** —— 详见下文「2.」；
 3. **时区口径不统一** → 定时规则判错时段、日报日界错位（两位评审独立发现）。
 
 ---
@@ -51,7 +52,7 @@ agent_intent_config 中 agent_type='risk'：0 条
 
 ## 三、P1 · 安全与治理
 
-### 2. 模型调用绕过基座的模型服务 ✅
+### 2. 模型调用自建客户端（复核后定性：基座能力缺口，不是违规）✅
 
 - 底座**有**公共入口：`base.py:79-84` 的 `generate_with_model()`，且 `base.py:86-95` 把它列入
   **禁止子类覆写**的集合 —— 底座明确视其为治理方法。
@@ -64,7 +65,37 @@ agent_intent_config 中 agent_type='risk'：0 条
 但**没走 gateway 的调用层** —— 降级、端点排序、统一错误映射，以及 gateway 将来的任何改进
 （限流、成本统计）它都享受不到。
 
-**修复**：改走 `ModelGenerationService`，或删掉该文件直接用 `self.generate_with_model`。
+其**修复建议原先写作"改走 `ModelGenerationService`，或直接用 `self.generate_with_model`"——
+该建议不成立，以下为复核后的更正（2026-09-11）。**
+
+**前提复核**：基座的公共入口**做不到风控需要的事**。
+
+- `OpenAICompatibleGateway.generate(endpoint_code, prompt, timeout_ms) -> str`
+  （`model_gateway.py:57`）与 `ModelDispatchService.generate(endpoints, prompt) -> ModelExecution`
+  （`:248`）都是**「给一段 prompt、拿一段文本」**；`ModelExecution` 的字段只有
+  `(endpoint_code, text, attempts, degraded)`（`:226-231`）。
+- 而风控需要的是 **messages 数组 + tools（function calling）+ 解析 tool_calls**，
+  基座完全没有这种形态的入口。
+
+**所以这不是"绕过"，是基座缺能力时的补位。** 而且它补得相当规矩：
+
+| 它复刻的东西 | 与基座的一致性 |
+|---|---|
+| 端点选择 | 直接用基座的 `DatabaseModelEndpointResolver` + `EnvironmentSecretResolver` |
+| 降级策略 | 与 `ModelDispatchService.generate` 一致：按声明顺序尝试、`max_attempts` 默认 2 |
+| 错误映射 | 与基座同一套：`UpstreamTimeoutError` / `DependencyUnavailableError` |
+
+**仍然成立的两点**（与本条前半无关，但值得修）：
+
+1. `bootstrap.py:262-265` 的 `lambda _context: RiskAgent(RiskAgent.definition)` 让 `model_client`
+   **永远是默认值**，注入点形同虚设 —— 无论将来走哪条路，这个 lambda 都该改。
+2. `risk_agent_model_client.py` 里的 HTTP 调用逻辑与 gateway **重复了一份**：
+   gateway 将来加限流、成本统计、统一日志，风控享受不到。
+
+**正确的修法**（比原建议大，且要动基座）：给基座**新增** `chat(messages, tools)` 形态的入口
+（`ModelGateway` Protocol → `OpenAICompatibleGateway` → `ModelDispatchService` →
+`ModelGenerationService` → `BaseAgent`），再让风控改用它。因为**只是新增方法、不改现有行为**，
+对已有 Agent 零影响，但涉及基座核心链路，**是否做需要项目方定**（本轮未实施）。
 
 ### 3. 能力过滤失效，当前能工作只是巧合 🔁 ✅