docs: 同步 core/protocols.py 分层、四层治理栈、遥测新字段
ARCHITECTURE.md §2.3/§2.4/§3.1/§4/§5 + CLAUDE.md §4.8/§4.9/§5 + .env.example 对应设计 research-wiki/designs/2026-07-06-core-agent-adapters-llm-design.md §8 Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
This commit is contained in:
@@ -243,7 +243,7 @@ MODE=mock N_SAMPLES=10 bash scripts/<experiment>.sh # smoke test
|
||||
|
||||
### 4.8 Agent 遥测
|
||||
|
||||
每次 LLM/VLM 调用必须经过 `TelemetryRecorder` Protocol(`core/evolution/protocols.py`)记录。完整规范见 `research-wiki/ARCHITECTURE.md §4`。
|
||||
每次 LLM/VLM 调用必须经过 `TelemetryRecorder` Protocol(`core/protocols.py`)记录。完整规范见 `research-wiki/ARCHITECTURE.md §4`。
|
||||
|
||||
| 必录字段 | 类型 | 说明 |
|
||||
|----------|------|------|
|
||||
@@ -254,8 +254,11 @@ MODE=mock N_SAMPLES=10 bash scripts/<experiment>.sh # smoke test
|
||||
| `provider` | str | API 端点标识 |
|
||||
| `messages` | str (JSON) | 原始输入 |
|
||||
| `response` | str | 原始输出 |
|
||||
| `thinking` | str | thinking/reasoning 内容 |
|
||||
| `prompt_tokens` / `completion_tokens` | int | token 用量 |
|
||||
| `latency_ms` | int | 延迟毫秒 |
|
||||
| `ttft_ms` | float? | 首 token 延迟(流式测量) |
|
||||
| `max_inter_token_ms` | float? | 最大 token 间隔(流式测量) |
|
||||
| `cache_hit` | bool | 是否命中 Redis 缓存 |
|
||||
| `error` | str? | 异常信息(正常为 null) |
|
||||
|
||||
@@ -263,17 +266,16 @@ MODE=mock N_SAMPLES=10 bash scripts/<experiment>.sh # smoke test
|
||||
|
||||
### 4.9 LLM 韧性
|
||||
|
||||
所有 LLM/VLM 调用必须经过 `GovernedLLMClient`(`adapters/llm.py`)治理,禁止裸调 OpenAI SDK。治理栈五层(详见 `research-wiki/ARCHITECTURE.md §5`):
|
||||
所有 LLM/VLM 调用必须经过 `GovernedLLMClient`(`adapters/llm.py`)治理,禁止裸调 OpenAI SDK。治理栈四层(详见 `research-wiki/ARCHITECTURE.md §5`):
|
||||
|
||||
| 层 | 机制 | 说明 |
|
||||
|---|------|------|
|
||||
| 1 | 硬超时 | `asyncio.wait_for(call, timeout=config.llm_timeout)` |
|
||||
| 2 | 指数退避重试 | `max_retries`、`base_delay`、`max_delay`(可配置) |
|
||||
| 3 | 熔断器 | 连续 N 失败 → 短路 M 秒 → 探针恢复 |
|
||||
| 4 | Redis 响应缓存 | content-addressed:`hash(model + messages)` → response |
|
||||
| 5 | ARQ 任务队列 | 长时间推理任务异步执行 |
|
||||
| 1 | 熔断器 | 连续 N 失败 → 短路 M 秒 → 探针恢复(`adapters/breaker.py`) |
|
||||
| 2 | Redis 响应缓存 | content-addressed:`hash(model + messages)` → response |
|
||||
| 3 | 流式三层看门狗 | TTFT / inter_token / total 超时保护(`adapters/streaming.py`) |
|
||||
| 4 | 指数退避重试 | `max_retries`、`base_delay`、`max_delay`(可配置) |
|
||||
|
||||
> 熔断参数(`LLM_CIRCUIT_BREAKER_THRESHOLD`、`LLM_CIRCUIT_BREAKER_COOLDOWN`)和超时(`LLM_TIMEOUT`)通过 `.env` 工程配置管理。
|
||||
> 熔断参数(`LLM_CIRCUIT_BREAKER_THRESHOLD`、`LLM_CIRCUIT_BREAKER_COOLDOWN`)和超时(`LLM_TIMEOUT`、`LLM_TTFT_TIMEOUT`、`LLM_INTER_TOKEN_TIMEOUT`)通过 `.env` 工程配置管理。
|
||||
|
||||
## 5. 项目结构规范
|
||||
|
||||
@@ -289,6 +291,7 @@ project_root/
|
||||
├── .claude/ # Claude 配置(skills, hooks, tools)
|
||||
│
|
||||
├── core/ # 可提取内核(不依赖 app/、adapters/)
|
||||
│ ├── protocols.py # 共享端口(LLMProvider, VLMProvider, TelemetryRecorder)
|
||||
│ ├── agent/ # AgentLoop 引擎(loop, types, protocols)
|
||||
│ ├── evolution/ # 诊断+进化引擎(diagnose, evolve, gate)
|
||||
│ └── types.py # 跨模块共享类型
|
||||
|
||||
Reference in New Issue
Block a user