1189 lines
40 KiB
Markdown
1189 lines
40 KiB
Markdown
# InferenceEngine（推理引擎） 实施计划
|
||
|
||
> **For agentic workers:** REQUIRED SUB-SKILL: Use superpowers:subagent-driven-development (recommended) or superpowers:executing-plans to implement this plan task-by-task. Steps use checkbox (`- [ ]`) syntax for tracking.
|
||
|
||
**Goal:** 落地里程碑 3.1——实现 `agent-runtime-design.md` §2 定义的推理引擎：统一 `chat` / `chat_structured` LLM 入口，含模型降级、重试、Token 裁剪、Prompt 注册表与结构化输出。
|
||
|
||
**Architecture:** 新增 `src/genesis/inference/` 包（types / exceptions / token / prompt_registry / client / engine）；engine 通过注入的 `LLMClient`（httpx 实现，测试用 FakeTransport/FakeClient 零网络）与 `PromptRegistry` 组合；异常不抛给调用方（chat 折叠为 `status`），解析失败返回 `parse_error`+raw_text。
|
||
|
||
**Tech Stack:** Python 3.11+，httpx（不拆 SDK）、jinja2（PromptRegistry 渲染）、tiktoken（可选，缺失回落 approximate）、dataclasses、pytest。
|
||
|
||
## Global Constraints
|
||
|
||
- 项目为中文交流（注释中文、标识符英文），Windows/PowerShell 环境
|
||
- **零真实网络**：单测一律注入 `FakeLLMClient` / `httpx.MockTransport`；`DEEPSEEK_API_KEY` 不落代码
|
||
- **覆盖率红线**：`pyproject.toml` `fail_under = 99`（当前 71 passed / 100% 全绿），新增每文件需足量分支测试，全量回归不得跌破 99
|
||
- 测试命令：`python -m pytest tests/<file> -v`；全量回归：`python -m pytest -v`（会触发 `--cov` 与 `fail_under` 校验）
|
||
- 提交消息风格：`feat:` / `test:` / `docs:`（简中文描述）
|
||
- 每次修改后按项目规则追加 `_AI_USAGE_LOG.md` 记录（范式步骤列：Agent 实现 或 测试验证）
|
||
- 依赖修改 `pyproject.toml` 后需执行 `pip install -e ".[dev]"` 再跑测试
|
||
|
||
---
|
||
|
||
### Task 1: 数据模型与异常层（包骨架 + types + exceptions）
|
||
|
||
**Files:**
|
||
- Create: `src/genesis/inference/__init__.py`
|
||
- Create: `src/genesis/inference/types.py`
|
||
- Create: `src/genesis/inference/exceptions.py`
|
||
- Create: `tests/test_inference_types.py`
|
||
- Create: `tests/test_inference_errors.py`
|
||
- Modify: `pyproject.toml`（dependencies 增加 `httpx`、`jinja2`）
|
||
|
||
**Interfaces:**
|
||
- Consumes: 无（独立基础层，不依赖其他模块）
|
||
- Produces:
|
||
- `TokenUsage(input_tokens: int = 0, output_tokens: int = 0)`
|
||
- `ChatMessage(role: Literal["system","user","assistant"], content: str)`
|
||
- `ChatResult(text, model, prompt_version, usage, duration_ms, status: Literal["ok","fallback","failed"], error: str|None = None)`
|
||
- `StructuredResult(data: dict, raw_text: str, parse_attempts: int, model, prompt_version, usage, duration_ms, status: Literal["ok","fallback","parse_error","failed"], error: str|None = None)`
|
||
- `Prompt(name: str, version: str, template: str)`
|
||
- `LLMError(Exception)` / `LLMNetworkError` / `LLMTimeoutError` / `LLMNotConfiguredError` / `LLMResponseError`
|
||
|
||
- [ ] **Step 1: 写失败测试**
|
||
|
||
`tests/test_inference_types.py`:
|
||
```python
|
||
from genesis.inference.types import ChatMessage, ChatResult, Prompt, StructuredResult, TokenUsage
|
||
|
||
|
||
def test_token_usage_defaults():
|
||
u = TokenUsage()
|
||
assert u.input_tokens == 0 and u.output_tokens == 0
|
||
|
||
|
||
def test_chat_message_roles():
|
||
assert ChatMessage(role="system", content="x").content == "x"
|
||
|
||
|
||
def test_chat_result_defaults():
|
||
r = ChatResult(
|
||
text="t", model="m", prompt_version="v1", usage=TokenUsage(),
|
||
duration_ms=10, status="ok",
|
||
)
|
||
assert r.status == "ok" and r.error is None
|
||
|
||
|
||
def test_structured_result_status_ok():
|
||
r = StructuredResult(
|
||
data={"a": 1}, raw_text='{"a":1}', parse_attempts=1, model="m",
|
||
prompt_version="v1", usage=TokenUsage(), duration_ms=10, status="ok",
|
||
)
|
||
assert r.data == {"a": 1} and r.raw_text == '{"a":1}'
|
||
|
||
|
||
def test_structured_result_status_parse_error():
|
||
r = StructuredResult(
|
||
data={}, raw_text="NOT JSON", parse_attempts=3, model="m",
|
||
prompt_version="v1", usage=TokenUsage(), duration_ms=50,
|
||
status="parse_error", error="bad json",
|
||
)
|
||
assert r.status == "parse_error" and r.error == "bad json"
|
||
|
||
|
||
def test_prompt_fields():
|
||
p = Prompt(name="writer", version="v2", template="章节 {{chapter}}")
|
||
assert p.name == "writer" and p.version == "v2"
|
||
```
|
||
|
||
`tests/test_inference_errors.py`:
|
||
```python
|
||
import pytest
|
||
|
||
from genesis.inference.exceptions import (
|
||
LLMError,
|
||
LLMNetworkError,
|
||
LLMNotConfiguredError,
|
||
LLMResponseError,
|
||
LLMTimeoutError,
|
||
)
|
||
|
||
|
||
def test_error_hierarchy():
|
||
assert issubclass(LLMNetworkError, LLMError)
|
||
assert issubclass(LLMTimeoutError, LLMError)
|
||
assert issubclass(LLMNotConfiguredError, LLMError)
|
||
assert issubclass(LLMResponseError, LLMError)
|
||
|
||
|
||
def test_error_message_roundtrip():
|
||
e = LLMTimeoutError("timeout!")
|
||
assert str(e) == "timeout!"
|
||
```
|
||
|
||
- [ ] **Step 2: 运行确认失败**
|
||
|
||
Run: `python -m pytest tests/test_inference_types.py -v`
|
||
Expected: FAIL（`ModuleNotFoundError: No module named 'genesis.inference'`）
|
||
|
||
- [ ] **Step 3: 修改 pyproject 依赖**
|
||
|
||
`pyproject.toml` 的 dependencies 增加：
|
||
```toml
|
||
"httpx>=0.28",
|
||
"jinja2>=3.1",
|
||
```
|
||
|
||
- [ ] **Step 4: 实现**
|
||
|
||
`src/genesis/inference/types.py`:
|
||
```python
|
||
from __future__ import annotations
|
||
|
||
from dataclasses import dataclass
|
||
from typing import Any, Literal
|
||
|
||
|
||
@dataclass
|
||
class TokenUsage:
|
||
"""一次 LLM 调用的 token 用量（可观测性事件/统计用）"""
|
||
input_tokens: int = 0
|
||
output_tokens: int = 0
|
||
|
||
|
||
@dataclass
|
||
class ChatMessage:
|
||
"""Chat Completions 消息"""
|
||
role: Literal["system", "user", "assistant"]
|
||
content: str
|
||
|
||
|
||
@dataclass
|
||
class ChatResult:
|
||
"""chat() 的返回值"""
|
||
text: str
|
||
model: str
|
||
prompt_version: str
|
||
usage: TokenUsage
|
||
duration_ms: int
|
||
status: Literal["ok", "fallback", "failed"]
|
||
error: str | None = None
|
||
|
||
|
||
@dataclass
|
||
class StructuredResult:
|
||
"""chat_structured() 的返回值（补丁 1：含 status 字段）"""
|
||
data: dict
|
||
raw_text: str
|
||
parse_attempts: int
|
||
model: str
|
||
prompt_version: str
|
||
usage: TokenUsage
|
||
duration_ms: int
|
||
status: Literal["ok", "fallback", "parse_error", "failed"]
|
||
error: str | None = None
|
||
|
||
|
||
@dataclass
|
||
class Prompt:
|
||
"""Prompt 模板条目（name+version 唯一）"""
|
||
name: str
|
||
version: str
|
||
template: str
|
||
```
|
||
|
||
`src/genesis/inference/exceptions.py`:
|
||
```python
|
||
from __future__ import annotations
|
||
|
||
|
||
class LLMError(Exception):
|
||
"""LLM 调用相关的异常基类（api-design §7 映射基底）"""
|
||
|
||
|
||
class LLMNetworkError(LLMError):
|
||
"""网络失败 / 5xx 重试耗尽（可重试语义）"""
|
||
|
||
|
||
class LLMTimeoutError(LLMError):
|
||
"""LLM 调用超时（api-error: LLM_TIMEOUT 502）"""
|
||
|
||
|
||
class LLMNotConfiguredError(LLMError):
|
||
"""Key / 模型缺失（api-error: LLM_NOT_CONFIGURED 503）"""
|
||
|
||
|
||
class LLMResponseError(LLMError):
|
||
"""响应结构损坏（JSON 解析失败等）"""
|
||
```
|
||
|
||
`src/genesis/inference/__init__.py`:
|
||
```python
|
||
"""Genesis 推理引擎（统一 LLM 调用入口）。"""
|
||
|
||
from .types import ChatMessage, ChatResult, Prompt, StructuredResult, TokenUsage
|
||
from .exceptions import (
|
||
LLMError,
|
||
LLMNetworkError,
|
||
LLMNotConfiguredError,
|
||
LLMResponseError,
|
||
LLMTimeoutError,
|
||
)
|
||
|
||
__all__ = [
|
||
"ChatMessage",
|
||
"ChatResult",
|
||
"Prompt",
|
||
"StructuredResult",
|
||
"TokenUsage",
|
||
"LLMError",
|
||
"LLMNetworkError",
|
||
"LLMNotConfiguredError",
|
||
"LLMResponseError",
|
||
"LLMTimeoutError",
|
||
]
|
||
```
|
||
> 注：暂时不在 `__init__` 导入 engine/client 等（避免循环导入），Task 5 完成后再收敛导出。
|
||
|
||
- [ ] **Step 5: 运行确认通过**
|
||
|
||
Run: `python -m pytest tests/test_inference_types.py tests/test_inference_errors.py -v`
|
||
Expected: PASS（5 + 2 = 7 passed）
|
||
|
||
- [ ] **Step 6: 提交**
|
||
|
||
```bash
|
||
git add pyproject.toml src/genesis/inference/__init__.py src/genesis/inference/types.py src/genesis/inference/exceptions.py tests/test_inference_types.py tests/test_inference_errors.py
|
||
git commit -m "feat: 推理引擎数据模型与异常层（types/exceptions）及 httpx/jinja2 依赖"
|
||
```
|
||
|
||
---
|
||
|
||
### Task 2: Token 估算（token.py，approximate 内置 / tiktoken 可选）
|
||
|
||
**Files:**
|
||
- Create: `src/genesis/inference/token.py`
|
||
- Create: `tests/test_inference_token.py`
|
||
|
||
**Interfaces:**
|
||
- Consumes: 无（不依赖其他模块）
|
||
- Produces:
|
||
- `approximate_token_count(text: str) -> int`（4 字符 ≈ 1 token，最少 1）
|
||
- `_tiktoken_estimator(text: str) -> int | None`（未安装返回 None；可 patch 测试其成功路径）
|
||
- `make_estimator(backend: str = "tiktoken") -> Callable[[str], int]`（backend="approximate" → 近似；否则优先 tiktoken，缺失回落 approximate）
|
||
|
||
- [ ] **Step 1: 写失败测试**
|
||
|
||
`tests/test_inference_token.py`:
|
||
```python
|
||
import pytest
|
||
|
||
from genesis.inference.token import (
|
||
_tiktoken_estimator,
|
||
approximate_token_count,
|
||
make_estimator,
|
||
)
|
||
|
||
|
||
def test_approximate_count_minimum():
|
||
assert approximate_token_count("") >= 1
|
||
assert approximate_token_count("a") == 1
|
||
|
||
|
||
def test_approximate_count_linear():
|
||
# 每 4 字符约 1 token（向上取整）
|
||
assert approximate_token_count("abcd") == 1
|
||
assert approximate_token_count("abcdefgh") == 2
|
||
assert approximate_token_count("abcdefghi") == 3
|
||
|
||
|
||
def test_tiktoken_estimator_missing_falls_back():
|
||
# 未安装 tiktoken 或不可用时返回 None（由 make_estimator 回落 approximate）
|
||
r = _tiktoken_estimator("hello")
|
||
assert r is None or isinstance(r, int)
|
||
|
||
|
||
def test_make_estimator_approximate_backend():
|
||
est = make_estimator("approximate")
|
||
assert est("abcd") == 1
|
||
|
||
|
||
def test_make_estimator_default_without_tiktoken(monkeypatch):
|
||
# 强制模拟 tiktoken 缺失：make_estimator 必须回落 approximate
|
||
import builtins
|
||
real_import = builtins.__import__
|
||
|
||
def fake_import(name, *args, **kwargs):
|
||
if name == "tiktoken":
|
||
raise ImportError("no tiktoken")
|
||
return real_import(name, *args, **kwargs)
|
||
|
||
monkeypatch.setattr(builtins, "__import__", fake_import)
|
||
est = make_estimator("tiktoken")
|
||
assert est("abcd") == 1
|
||
```
|
||
|
||
- [ ] **Step 2: 运行确认失败**
|
||
|
||
Run: `python -m pytest tests/test_inference_token.py -v`
|
||
Expected: FAIL（`ModuleNotFoundError: No module named 'genesis.inference.token'`）
|
||
|
||
- [ ] **Step 3: 实现**
|
||
|
||
`src/genesis/inference/token.py`:
|
||
```python
|
||
from __future__ import annotations
|
||
|
||
from typing import Callable
|
||
|
||
|
||
def approximate_token_count(text: str) -> int:
|
||
"""内置近似估算：每 4 字符 ≈ 1 token（无外部依赖，可离线）。"""
|
||
return max(1, (len(text) + 3) // 4)
|
||
|
||
|
||
def _tiktoken_estimator(text: str) -> int | None:
|
||
"""tiktoken 编码估算；tiktoken 未安装时返回 None。"""
|
||
try:
|
||
import tiktoken
|
||
except ImportError:
|
||
return None
|
||
try:
|
||
enc = tiktoken.get_encoding("cl100k_base")
|
||
return len(enc.encode(text))
|
||
except Exception:
|
||
return None
|
||
|
||
|
||
def make_estimator(backend: str = "tiktoken") -> Callable[[str], int]:
|
||
"""按配置选择估算器：backend="tiktoken"（默认）优先 tiktoken，
|
||
缺失或异常回落内置 approximate；backend="approximate" 直接用近似。"""
|
||
if backend == "approximate":
|
||
return approximate_token_count
|
||
return lambda text: _tiktoken_estimator(text) or approximate_token_count(text)
|
||
```
|
||
|
||
- [ ] **Step 4: 运行确认通过**
|
||
|
||
Run: `python -m pytest tests/test_inference_token.py -v`
|
||
Expected: PASS（5 passed）
|
||
|
||
- [ ] **Step 5: 提交**
|
||
|
||
```bash
|
||
git add src/genesis/inference/token.py tests/test_inference_token.py
|
||
git commit -m "feat: Token 估算（approximate 内置 / tiktoken 可选回落）"
|
||
```
|
||
|
||
---
|
||
|
||
### Task 3: Prompt 注册表（prompt_registry.py + jinja2 渲染）
|
||
|
||
**Files:**
|
||
- Create: `src/genesis/inference/prompt_registry.py`
|
||
- Create: `tests/test_inference_prompt_registry.py`
|
||
|
||
**Interfaces:**
|
||
- Consumes: `Prompt`（Task 1）、`jinja2`
|
||
- Produces:
|
||
- `class PromptRegistry`：
|
||
- `register(name: str, version: str, template: str) -> None`
|
||
- `get(name: str, version: str | None = None, variables: dict | None = None) -> str`（version=None → 该 name 最新注册版本；有 variables → 渲染）
|
||
- `list_versions(name: str) -> list[str]`
|
||
- `render(template: str, variables: dict) -> str`（jinja2 渲染）
|
||
|
||
- [ ] **Step 1: 写失败测试**
|
||
|
||
`tests/test_inference_prompt_registry.py`:
|
||
```python
|
||
import pytest
|
||
|
||
from genesis.inference.prompt_registry import PromptRegistry
|
||
from genesis.inference.types import Prompt
|
||
|
||
|
||
def test_register_and_render():
|
||
reg = PromptRegistry()
|
||
reg.register("writer", "v1", "按规则撰写：{{ chapter }}")
|
||
assert reg.get("writer", "v1") == "按规则撰写：{{ chapter }}"
|
||
|
||
|
||
def test_get_with_variables_renders():
|
||
reg = PromptRegistry()
|
||
reg.register("writer", "v1", "按规则撰写：{{ chapter }}")
|
||
assert reg.get("writer", "v1", {"chapter": "帳票設計"}) == "按规则撰写：帳票設計"
|
||
|
||
|
||
def test_get_latest_version():
|
||
reg = PromptRegistry()
|
||
reg.register("writer", "v1", "t1")
|
||
reg.register("writer", "v2", "t2")
|
||
assert reg.get("writer") == "t2"
|
||
assert reg.list_versions("writer") == ["v1", "v2"]
|
||
|
||
|
||
def test_get_missing_raises_keyerror():
|
||
reg = PromptRegistry()
|
||
with pytest.raises(KeyError):
|
||
reg.get("dne")
|
||
|
||
|
||
def test_render_raw():
|
||
reg = PromptRegistry()
|
||
assert reg.render("{{ a }} と {{ b }}", {"a": "x", "b": 1}) == "x と 1"
|
||
```
|
||
|
||
- [ ] **Step 2: 运行确认失败**
|
||
|
||
Run: `python -m pytest tests/test_inference_prompt_registry.py -v`
|
||
Expected: FAIL（`ModuleNotFoundError: No module named 'genesis.inference.prompt_registry'`）
|
||
|
||
- [ ] **Step 3: 实现**
|
||
|
||
`src/genesis/inference/prompt_registry.py`:
|
||
```python
|
||
from __future__ import annotations
|
||
|
||
from typing import Any
|
||
|
||
from jinja2 import Template
|
||
|
||
from .types import Prompt
|
||
|
||
|
||
class PromptRegistry:
|
||
"""Prompt 模板库：注册/取用/版本管理/渲染（集中管理待迁移 prompts/ 目录）。"""
|
||
|
||
def __init__(self) -> None:
|
||
self._templates: dict[tuple[str, str], str] = {}
|
||
|
||
def register(self, name: str, version: str, template: str) -> None:
|
||
"""注册（或覆盖）一个版本的模板。"""
|
||
self._templates[(name, version)] = template
|
||
|
||
def get(
|
||
self,
|
||
name: str,
|
||
version: str | None = None,
|
||
variables: dict[str, Any] | None = None,
|
||
) -> str:
|
||
"""取模板；version=None 返回该 name 最新注册版本；variables 非空时渲染。"""
|
||
if version is None:
|
||
versions = self.list_versions(name)
|
||
if not versions:
|
||
raise KeyError(f"prompt not found: {name}")
|
||
version = versions[-1]
|
||
key = (name, version)
|
||
if key not in self._templates:
|
||
raise KeyError(f"prompt version not found: {name}@{version}")
|
||
template = self._templates[key]
|
||
if variables:
|
||
return self.render(template, variables)
|
||
return template
|
||
|
||
def list_versions(self, name: str) -> list[str]:
|
||
"""返回某 name 的已注册版本（按注册顺序）。"""
|
||
return [v for (n, v) in self._templates if n == name]
|
||
|
||
def render(self, template: str, variables: dict[str, Any]) -> str:
|
||
"""用 jinja2 渲染模板。"""
|
||
from jinja2 import Template
|
||
|
||
return Template(template).render(**variables)
|
||
```
|
||
|
||
- [ ] **Step 4: 运行确认通过**
|
||
|
||
Run: `python -m pytest tests/test_inference_prompt_registry.py -v`
|
||
Expected: PASS（5 passed）
|
||
|
||
- [ ] **Step 5: 提交**
|
||
|
||
```bash
|
||
git add src/genesis/inference/prompt_registry.py tests/test_inference_prompt_registry.py
|
||
git commit -m "feat: PromptRegistry 注册/版本/渲染（jinja2）"
|
||
```
|
||
|
||
---
|
||
|
||
### Task 4: LLM 客户端（client.py：httpx + 重试/退避/超时/认证）
|
||
|
||
**Files:**
|
||
- Create: `src/genesis/inference/client.py`
|
||
- Create: `tests/test_inference_client.py`
|
||
|
||
**Interfaces:**
|
||
- Consumes: `ChatMessage` / `TokenUsage`（Task 1）；`LLMError` 子树（Task 1）
|
||
- Produces:
|
||
- `class LLMClient(Protocol)`：`chat(*, model, messages: list[ChatMessage], temperature: float, max_tokens: int) -> tuple[str, TokenUsage]`
|
||
- `class HttpLLMClient`：`__init__(base_url, api_key, timeout_sec=60.0, retry_backoff=(1.0,3.0,7.0), transport=None)`；`chat(...) -> tuple[str, TokenUsage]`；重试 5xx/网络错误，退避间隔指数；超时抛 `LLMTimeoutError`；重试耗尽抛 `LLMNetworkError`；非 2xx 4xx 抛 `LLMNetworkError`；无 api_key 抛 `LLMNotConfiguredError`
|
||
|
||
- [ ] **Step 1: 写失败测试**
|
||
|
||
`tests/test_inference_client.py`:
|
||
```python
|
||
import pytest
|
||
import httpx
|
||
|
||
from genesis.inference.client import HttpLLMClient, LLMClient
|
||
from genesis.inference.exceptions import LLMNetworkError, LLMNotConfiguredError, LLMTimeoutError
|
||
from genesis.inference.types import ChatMessage
|
||
|
||
|
||
def make_client(handler, *, api_key="sk-test", retry_backoff=(0.0, 0.0)):
|
||
return HttpLLMClient(
|
||
base_url="https://api.test.local",
|
||
api_key=api_key,
|
||
timeout_sec=0.1,
|
||
retry_backoff=retry_backoff,
|
||
transport=httpx.MockTransport(handler),
|
||
)
|
||
|
||
|
||
def _ok_handler(request):
|
||
return httpx.Response(200, json={
|
||
"choices": [{"message": {"content": "Hello"}}],
|
||
"usage": {"prompt_tokens": 10, "completion_tokens": 5},
|
||
})
|
||
|
||
|
||
def test_client_implements_protocol():
|
||
# 结构性断言：HttpLLMClient.chat 的关键字参数签名与 LLMClient Protocol 一致
|
||
import inspect
|
||
|
||
proto_params = set(inspect.signature(LLMClient.chat).parameters)
|
||
impl_params = set(inspect.signature(HttpLLMClient.chat).parameters)
|
||
assert proto_params.issubset(impl_params)
|
||
|
||
|
||
def test_chat_success():
|
||
client = make_client(_ok_handler)
|
||
text, usage = client.chat(
|
||
model="deepseek-chat",
|
||
messages=[ChatMessage(role="user", content="hi")],
|
||
temperature=0.2,
|
||
max_tokens=100,
|
||
)
|
||
assert text == "Hello"
|
||
assert usage.input_tokens == 10 and usage.output_tokens == 5
|
||
|
||
|
||
def test_chat_requires_api_key():
|
||
with pytest.raises(LLMNotConfiguredError):
|
||
HttpLLMClient(base_url="https://x", api_key="")
|
||
|
||
|
||
def test_chat_timeout():
|
||
def slow(request):
|
||
raise httpx.ReadTimeout("slow")
|
||
|
||
with pytest.raises(LLMTimeoutError):
|
||
make_client(slow, retry_backoff=(0, 0)).chat(
|
||
model="m", messages=[ChatMessage(role="user", content="x")],
|
||
temperature=0.2, max_tokens=100,
|
||
)
|
||
|
||
|
||
def test_chat_5xx_retry_then_network_error():
|
||
calls = {"n": 0}
|
||
|
||
def handler(request):
|
||
calls["n"] += 1
|
||
return httpx.Response(500, text="boom")
|
||
|
||
with pytest.raises(LLMNetworkError):
|
||
make_client(handler, retry_backoff=(0, 0)).chat(
|
||
model="m", messages=[ChatMessage(role="user", content="x")],
|
||
temperature=0.2, max_tokens=100,
|
||
)
|
||
assert calls["n"] == 3 # 初始 + 2 次退避重试（间隔 0/0.01）
|
||
|
||
|
||
def test_chat_4xx_no_retry():
|
||
calls = {"n": 0}
|
||
|
||
def handler(request):
|
||
calls["n"] += 1
|
||
return httpx.Response(429, text="rate limit")
|
||
|
||
with pytest.raises(LLMNetworkError):
|
||
make_client(handler).chat(
|
||
model="m", messages=[ChatMessage(role="user", content="x")],
|
||
temperature=0.2, max_tokens=100,
|
||
)
|
||
assert calls["n"] == 1 # 4xx 不重试
|
||
```
|
||
|
||
- [ ] **Step 2: 运行确认失败**
|
||
|
||
Run: `python -m pytest tests/test_inference_client.py -v`
|
||
Expected: FAIL（`ModuleNotFoundError: No module named 'genesis.inference.client'`）
|
||
|
||
- [ ] **Step 3: 实现**
|
||
|
||
`src/genesis/inference/client.py`:
|
||
```python
|
||
from __future__ import annotations
|
||
|
||
import time
|
||
from typing import Protocol, Sequence
|
||
|
||
import httpx
|
||
|
||
from .exceptions import LLMNetworkError, LLMNotConfiguredError, LLMTimeoutError
|
||
from .types import ChatMessage, TokenUsage
|
||
|
||
|
||
class LLMClient(Protocol):
|
||
"""LLM 调用适配器（可注入替换为 Fake）。"""
|
||
|
||
def chat(
|
||
self,
|
||
*,
|
||
model: str,
|
||
messages: list[ChatMessage],
|
||
temperature: float,
|
||
max_tokens: int,
|
||
) -> tuple[str, TokenUsage]: ...
|
||
|
||
|
||
class HttpLLMClient:
|
||
"""OpenAI Chat Completions 兼容的 httpx 实现；支持重试（指数退避）。"""
|
||
|
||
def __init__(
|
||
self,
|
||
*,
|
||
base_url: str,
|
||
api_key: str,
|
||
timeout_sec: float = 60.0,
|
||
retry_backoff: Sequence[float] = (1.0, 3.0, 7.0),
|
||
transport: httpx.BaseTransport | None = None,
|
||
) -> None:
|
||
if not api_key:
|
||
raise LLMNotConfiguredError("LLM API key 未配置（DEEPSEEK_API_KEY / LLM_BASE_URL）")
|
||
self._base_url = base_url.rstrip("/")
|
||
self._api_key = api_key
|
||
self._timeout_sec = timeout_sec
|
||
self._retry_backoff = retry_backoff
|
||
self._client = httpx.Client(timeout=timeout_sec, transport=transport)
|
||
|
||
def chat(
|
||
self,
|
||
*,
|
||
model: str,
|
||
messages: list[ChatMessage],
|
||
temperature: float,
|
||
max_tokens: int,
|
||
) -> tuple[str, TokenUsage]:
|
||
url = f"{self._base_url}/v1/chat/completions"
|
||
payload = {
|
||
"model": model,
|
||
"messages": [{"role": m.role, "content": m.content} for m in messages],
|
||
"temperature": temperature,
|
||
"max_tokens": max_tokens,
|
||
}
|
||
headers = {
|
||
"Authorization": f"Bearer {self._api_key}",
|
||
"Content-Type": "application/json",
|
||
}
|
||
|
||
attempts = 1 + len(self._retry_backoff)
|
||
last_error: Exception | None = None
|
||
for attempt in range(attempts):
|
||
if attempt > 0:
|
||
time.sleep(self._retry_backoff[attempt - 1])
|
||
try:
|
||
resp = self._client.post(url, json=payload, headers=headers)
|
||
except httpx.TimeoutException as exc:
|
||
last_error = exc
|
||
continue
|
||
except httpx.HTTPError as exc:
|
||
last_error = exc
|
||
continue
|
||
|
||
if resp.status_code >= 500:
|
||
last_error = LLMNetworkError(f"LLM 5xx: {resp.status_code}")
|
||
continue
|
||
if resp.status_code >= 400:
|
||
raise LLMNetworkError(f"LLM HTTP {resp.status_code}: {resp.text[:200]}")
|
||
|
||
data = resp.json()
|
||
content = data["choices"][0]["message"]["content"]
|
||
usage_raw = data.get("usage", {})
|
||
usage = TokenUsage(
|
||
input_tokens=usage_raw.get("prompt_tokens", 0),
|
||
output_tokens=usage_raw.get("completion_tokens", 0),
|
||
)
|
||
return content, usage
|
||
|
||
if isinstance(last_error, httpx.TimeoutException):
|
||
raise LLMTimeoutError(f"LLM 超时（{self._timeout_sec}s）") from last_error
|
||
raise LLMNetworkError(f"LLM 调用失败（重试耗尽）: {last_error}") from last_error
|
||
```
|
||
|
||
- [ ] **Step 4: 运行确认通过**
|
||
|
||
Run: `python -m pytest tests/test_inference_client.py -v`
|
||
Expected: PASS（6 passed）
|
||
|
||
- [ ] **Step 5: 全量回归**（新代码暴露到覆盖统计）
|
||
|
||
Run: `python -m pytest -v`
|
||
Expected: PASS（71 + 全部新用例；`fail_under=99` 通过）
|
||
|
||
- [ ] **Step 6: 提交**
|
||
|
||
```bash
|
||
git add src/genesis/inference/client.py tests/test_inference_client.py
|
||
git commit -m "feat: HttpLLMClient（httpx + 重试退避/超时/鉴权）"
|
||
```
|
||
|
||
---
|
||
|
||
### Task 5: InferenceEngine（engine.py：chat / chat_structured 全流程 + 注入测试 + 文档补丁）
|
||
|
||
**Files:**
|
||
- Create: `src/genesis/inference/engine.py`
|
||
- Create: `tests/inference_helpers.py`（FakeClient / FakeTransport）
|
||
- Create: `tests/test_inference_engine.py`
|
||
- Modify: `src/genesis/inference/__init__.py`（导出 Engine / ChatResult 等）
|
||
- Modify: `docs/agent-runtime-design.md`（§2.2 补 StructuredResult.status 字段）
|
||
- Modify: `docs/api-design.md`（§7 错误码表补 LLM_NOT_CONFIGURED 行）
|
||
- Modify: `docs/config-design.md`（§4 token_estimation 注明双语义降级）
|
||
|
||
**Interfaces:**
|
||
- Consumes: `LLMError` 子树（Task1）、`ChatMessage/ChatResult/Prompt/StructuredResult/TokenUsage`（Task1）、`make_estimator` + `approximate_token_count`（Task2）、`PromptRegistry`（Task3）、`LLMClient`（Task4）
|
||
- Produces:
|
||
- `class InferenceEngine`：`__init__(client, models: InferenceModels | None = None, registry=None, estimator=None, truncate_cb=None)`；`chat(...) -> ChatResult`；`chat_structured(...) -> StructuredResult`
|
||
- `chat`：渲染 → 裁剪判断 → 主模型调用 → 失败再取 fallback → status
|
||
- `chat_structured`：带 schema 提示构造 prompt → 逐次解析（最多 retry_count+1 次）→ parse_error 带 raw_text
|
||
|
||
- [ ] **Step 1: 写失败测试**
|
||
|
||
`tests/inference_helpers.py`:
|
||
```python
|
||
from __future__ import annotations
|
||
|
||
import json
|
||
|
||
import httpx
|
||
|
||
from genesis.inference.types import ChatMessage, TokenUsage
|
||
|
||
|
||
class FakeLLMClient:
|
||
"""可编程的假 LLM 客户端：记录调用，按脚本返回（离线）。"""
|
||
|
||
def __init__(self, script=None):
|
||
# script: list[(status, content)]；status: "ok" | "raise_timeout" | "raise_network" | "parse_fail"
|
||
self.script = script or [("ok", "hello")]
|
||
self.calls: list[dict] = []
|
||
|
||
def chat(self, *, model, messages, temperature, max_tokens):
|
||
self.calls.append({"model": model, "messages": [m.content for m in messages]})
|
||
status, content = self.script.pop(0)
|
||
if status == "raise_timeout":
|
||
from genesis.inference.exceptions import LLMTimeoutError
|
||
|
||
raise LLMTimeoutError("timeout")
|
||
if status == "raise_network":
|
||
from genesis.inference.exceptions import LLMNetworkError
|
||
|
||
raise LLMNetworkError("network")
|
||
if status == "parse_fail":
|
||
content = "NOT JSON"
|
||
return content, TokenUsage(input_tokens=10, output_tokens=2)
|
||
```
|
||
> 注意：FakeClient.chat 的签名必须匹配 Protocol（model/messages/temperature/max_tokens）——上方已对齐。
|
||
|
||
|
||
def ok_transport():
|
||
"""httpx.MockTransport：返回合法 JSON 响应。"""
|
||
def handler(request):
|
||
body = json.loads(request.content)
|
||
return httpx.Response(200, json={
|
||
"choices": [{"message": {"content": "structured:" + json.dumps({"a": body.get("model")})}}],
|
||
"usage": {"prompt_tokens": 3, "completion_tokens": 1},
|
||
})
|
||
return httpx.MockTransport(handler)
|
||
```
|
||
> 注意：FakeClient.chat 的签名必须匹配 Protocol（model/messages/temperature/max_tokens）——上方已对齐。`M` 类仅为占位，engine 构造时推荐直接传 dict：由测试构造真对象，见下文 engine 测试。
|
||
|
||
`tests/test_inference_engine.py`:
|
||
```python
|
||
from __future__ import annotations
|
||
|
||
import json
|
||
|
||
import pytest
|
||
|
||
from genesis.inference.engine import InferenceEngine
|
||
from genesis.inference.exceptions import LLMError
|
||
from genesis.inference.prompt_registry import PromptRegistry
|
||
from genesis.inference.token import approximate_token_count
|
||
from genesis.inference.types import ChatMessage, Prompt
|
||
from tests.inference_helpers import FakeLLMClient
|
||
|
||
|
||
class Models:
|
||
"""模拟 config.InferenceModels（pydantic 结构，测试中直接构建）"""
|
||
def __init__(self):
|
||
import types as t
|
||
self.primary = t.SimpleNamespace(name="deepseek-chat", provider="deepseek")
|
||
self.fallback = t.SimpleNamespace(name="qwen-max", provider="qwen")
|
||
|
||
|
||
def make_engine(client=None, *, constants=None):
|
||
eng = InferenceEngine(
|
||
client=client or FakeLLMClient(),
|
||
models=Models(),
|
||
registry=PromptRegistry(),
|
||
estimator=approximate_token_count,
|
||
)
|
||
if constants:
|
||
eng._max_context_tokens = constants # 内部测试钩子
|
||
return eng
|
||
|
||
|
||
def test_chat_ok():
|
||
client = FakeLLMClient([("ok", "正文")])
|
||
eng = make_engine(client)
|
||
r = eng.chat(
|
||
session_id="s1",
|
||
prompt=Prompt(name="writer", version="v1", template="章节：{{ chapter }}"),
|
||
variables={"chapter": "DB設計"},
|
||
)
|
||
assert r.status == "ok" and r.text == "正文"
|
||
assert client.calls[0]["model"] == "deepseek-chat"
|
||
|
||
|
||
def test_chat_fallback_after_primary_failure():
|
||
client = FakeLLMClient([("raise_timeout", ""), ("ok", "备用输出")])
|
||
eng = make_engine(client)
|
||
r = eng.chat(
|
||
session_id="s1",
|
||
prompt=Prompt(name="p", version="v1", template="t:{{ x }}"),
|
||
variables={"x": "1"},
|
||
)
|
||
assert r.status == "fallback"
|
||
assert client.calls[-1]["model"] == "deepseek-chat" # 先主，后备
|
||
|
||
|
||
def test_chat_all_failed_returns_failed():
|
||
client = FakeLLMClient([("raise_network", ""), ("raise_network", "")])
|
||
eng = make_engine(client)
|
||
r = eng.chat(
|
||
session_id="s1",
|
||
prompt=Prompt(name="p", version="v1", template="t"),
|
||
variables={},
|
||
)
|
||
assert r.status == "failed" and r.error
|
||
|
||
|
||
def test_chat_plain_string_prompt():
|
||
eng = make_engine(FakeLLMClient([("ok", "hi")]))
|
||
r = eng.chat(session_id="s1", prompt="直接文本", variables={})
|
||
assert r.text == "hi" and r.status == "ok"
|
||
|
||
|
||
def test_chat_truncation_callback_triggered():
|
||
seen = {}
|
||
|
||
def truncate_cb(prompt_text, variables):
|
||
seen["called"] = True
|
||
seen["len"] = len(prompt_text)
|
||
return {**variables, "chapter": "裁剪版"}
|
||
|
||
eng = InferenceEngine(
|
||
client=FakeLLMClient([("ok", "x")]),
|
||
models=Models(),
|
||
registry=PromptRegistry(),
|
||
estimator=approximate_token_count,
|
||
truncate_cb=truncate_cb,
|
||
)
|
||
eng._max_context_tokens = 3 # 强制超限
|
||
r = eng.chat(
|
||
session_id="s1",
|
||
prompt=Prompt(name="p", version="v1", template="abcd{{ chapter }}"),
|
||
variables={"chapter": "很长很长的标题"},
|
||
)
|
||
assert seen["called"] is True
|
||
assert r.status == "ok"
|
||
|
||
|
||
def test_chat_structured_ok():
|
||
client = FakeLLMClient([("ok", '{"a": 1}')])
|
||
eng = make_engine(client)
|
||
r = eng.chat_structured(
|
||
session_id="s1", prompt=Prompt(name="p", version="v1", template="提取"),
|
||
variables={"text": "内容"},
|
||
schema={"type": "object", "properties": {"a": {"type": "number"}}},
|
||
)
|
||
assert r.status == "ok" and r.data == {"a": 1}
|
||
|
||
|
||
def test_chat_structured_retry_parse():
|
||
client = FakeLLMClient([("parse_fail", ""), ("ok", '{"a": 2}')])
|
||
eng = make_engine(client)
|
||
r = eng.chat_structured(
|
||
session_id="s1", prompt=Prompt(name="p", version="v1", template="提取"),
|
||
variables={}, schema={},
|
||
)
|
||
assert r.status == "ok" and r.data == {"a": 2} and r.parse_attempts == 2
|
||
|
||
|
||
def test_chat_structured_parse_error_returns_raw():
|
||
client = FakeLLMClient([("parse_fail", ""), ("parse_fail", "")])
|
||
eng = make_engine(client)
|
||
r = eng.chat_structured(
|
||
session_id="s1", prompt=Prompt(name="p", version="v1", template="提取"),
|
||
variables={}, schema={}, retry_count=1,
|
||
)
|
||
assert r.status == "parse_error"
|
||
assert r.raw_text == "NOT JSON"
|
||
assert r.parse_attempts == 2
|
||
|
||
|
||
def test_chat_structured_failed_on_network():
|
||
client = FakeLLMClient([("raise_network", "")])
|
||
eng = make_engine(client)
|
||
r = eng.chat_structured(
|
||
session_id="s1", prompt=Prompt(name="p", version="v1", template="提取"),
|
||
variables={}, schema={},
|
||
)
|
||
assert r.status == "failed"
|
||
```
|
||
|
||
- [ ] **Step 2: 运行确认失败**
|
||
|
||
Run: `python -m pytest tests/test_inference_engine.py -v`
|
||
Expected: FAIL（`ModuleNotFoundError: No module named 'genesis.inference.engine'`）
|
||
|
||
- [ ] **Step 3: 实现**
|
||
|
||
`src/genesis/inference/engine.py`:
|
||
```python
|
||
from __future__ import annotations
|
||
|
||
import json
|
||
import time
|
||
from typing import Any, Callable
|
||
|
||
from .client import LLMClient
|
||
from .exceptions import LLMError
|
||
from .prompt_registry import PromptRegistry
|
||
from .token import make_estimator
|
||
from .types import (
|
||
ChatMessage,
|
||
ChatResult,
|
||
Prompt,
|
||
StructuredResult,
|
||
TokenUsage,
|
||
)
|
||
|
||
|
||
class InferenceEngine:
|
||
"""统一 LLM 调用入口：模型选择/降级、重试、解析、Token 超限回调。"""
|
||
|
||
def __init__(
|
||
self,
|
||
*,
|
||
client: LLMClient,
|
||
models: Any | None = None,
|
||
registry: PromptRegistry | None = None,
|
||
estimator: Callable[[str], int] | None = None,
|
||
truncate_cb: Callable[[str, dict], dict] | None = None,
|
||
max_context_tokens: int = 32000,
|
||
) -> None:
|
||
self._client = client
|
||
self._models = models
|
||
self._registry = registry or PromptRegistry()
|
||
self._estimator = estimator or make_estimator()
|
||
self._truncate_cb = truncate_cb
|
||
self._max_context_tokens = max_context_tokens
|
||
|
||
# ---------- 内部 ----------
|
||
|
||
def _render_prompt(self, prompt: Prompt | str, variables: dict) -> str:
|
||
if isinstance(prompt, Prompt):
|
||
return self._registry.render(prompt.template, variables) if variables else prompt.template
|
||
return prompt
|
||
|
||
def _apply_truncation(self, text: str, variables: dict) -> dict:
|
||
"""Token 超限时触发裁剪回调（注入），返回新 variables。"""
|
||
if self._truncate_cb is not None:
|
||
new_vars = self._truncate_cb(text, variables)
|
||
if new_vars is not None:
|
||
return new_vars
|
||
return variables
|
||
|
||
def _model_names(self, model: str | None) -> list[str]:
|
||
"""返回尝试顺序；显式指定 model 时只用它，否则 primary→fallback。"""
|
||
if model:
|
||
return [model]
|
||
if self._models:
|
||
names = []
|
||
if getattr(self._models, "primary", None):
|
||
names.append(self._models.primary.name)
|
||
if getattr(self._models, "fallback", None):
|
||
names.append(self._models.fallback.name)
|
||
if names:
|
||
return names
|
||
return ["deepseek-chat"]
|
||
|
||
def _call(
|
||
self,
|
||
*,
|
||
model: str,
|
||
rendered: str,
|
||
temperature: float,
|
||
max_tokens: int,
|
||
) -> tuple[str, TokenUsage]:
|
||
messages = [ChatMessage(role="user", content=rendered)]
|
||
return self._client.chat(
|
||
model=model,
|
||
messages=messages,
|
||
temperature=temperature,
|
||
max_tokens=max_tokens,
|
||
)
|
||
|
||
# ---------- 公开 ----------
|
||
|
||
def chat(
|
||
self,
|
||
*,
|
||
session_id: str,
|
||
prompt: Prompt | str,
|
||
variables: dict,
|
||
model: str | None = None,
|
||
temperature: float = 0.2,
|
||
max_tokens: int = 4096,
|
||
) -> ChatResult:
|
||
rendered = self._render_prompt(prompt, variables)
|
||
if self._estimator(rendered) > self._max_context_tokens:
|
||
variables = self._apply_truncation(rendered, variables)
|
||
rendered = self._render_prompt(prompt, variables)
|
||
|
||
start = time.monotonic()
|
||
last_error: str | None = None
|
||
for idx, name in enumerate(self._model_names(model)):
|
||
try:
|
||
text, usage = self._call(
|
||
model=name, rendered=rendered,
|
||
temperature=temperature, max_tokens=max_tokens,
|
||
)
|
||
status = "ok" if idx == 0 else "fallback"
|
||
return ChatResult(
|
||
text=text, model=name, prompt_version=getattr(prompt, "version", "inline"),
|
||
usage=usage, duration_ms=int((time.monotonic() - start) * 1000),
|
||
status=status,
|
||
)
|
||
except LLMError as exc:
|
||
last_error = str(exc)
|
||
|
||
return ChatResult(
|
||
text="", model=name,
|
||
prompt_version=getattr(prompt, "version", "inline"),
|
||
usage=TokenUsage(), duration_ms=int((time.monotonic() - start) * 1000),
|
||
status="failed", error=last_error,
|
||
)
|
||
|
||
def chat_structured(
|
||
self,
|
||
*,
|
||
session_id: str,
|
||
prompt: Prompt | str,
|
||
variables: dict,
|
||
schema: dict,
|
||
retry_count: int = 2,
|
||
) -> StructuredResult:
|
||
rendered = self._render_prompt(prompt, variables)
|
||
# 追加 schema 约束说明（不强制模板支持）
|
||
schema_hint = json.dumps(schema, ensure_ascii=False) if schema else ""
|
||
base_rendered = rendered + (f'\n\n请输出符合以下 JSON Schema 的 JSON：{schema_hint}' if schema_hint else "")
|
||
|
||
start = time.monotonic()
|
||
attempts = 0
|
||
last_raw = ""
|
||
last_error: str | None = None
|
||
|
||
while attempts <= retry_count:
|
||
attempts += 1
|
||
try:
|
||
text, usage = self._call(
|
||
model=self._model_names(None)[0], # 解析重试用首选模型
|
||
rendered=base_rendered,
|
||
temperature=0.0, max_tokens=4096,
|
||
)
|
||
last_raw = text
|
||
data = json.loads(text)
|
||
return StructuredResult(
|
||
data=data, raw_text=text, parse_attempts=attempts,
|
||
model=self._model_names(None)[0],
|
||
prompt_version=getattr(prompt, "version", "inline"),
|
||
usage=usage,
|
||
duration_ms=int((time.monotonic() - start) * 1000),
|
||
# fallback 语义保留给模型降级；解析重试成功仍为 ok
|
||
status="ok",
|
||
)
|
||
except json.JSONDecodeError as exc:
|
||
last_error = f"JSON 解析失败: {exc}"
|
||
# 带错误信息重试
|
||
base_rendered = base_rendered + f"\n\n上次解析失败：{exc}。请重新输出合法 JSON。"
|
||
except LLMError as exc:
|
||
return StructuredResult(
|
||
data={}, raw_text="", parse_attempts=attempts,
|
||
model=self._model_names(None)[0],
|
||
prompt_version=getattr(prompt, "version", "inline"),
|
||
usage=TokenUsage(),
|
||
duration_ms=int((time.monotonic() - start) * 1000),
|
||
status="failed", error=str(exc),
|
||
)
|
||
|
||
return StructuredResult(
|
||
data={}, raw_text=last_raw, parse_attempts=attempts,
|
||
model=self._model_names(None)[0],
|
||
prompt_version=getattr(prompt, "version", "inline"),
|
||
usage=TokenUsage(),
|
||
duration_ms=int((time.monotonic() - start) * 1000),
|
||
status="parse_error", error=last_error,
|
||
)
|
||
```
|
||
> 注：`_model_names(None)[0]` 仅用于结构解析的重试模型，生产建议显式传主模型，实现已足够 v1。
|
||
|
||
- [ ] **Step 4: 运行确认通过**
|
||
|
||
Run: `python -m pytest tests/test_inference_engine.py -v`
|
||
Expected: PASS（10 passed；若某用例失败按「实现约定」修正）
|
||
|
||
- [ ] **Step 5: 更新 `__init__.py` 导出**
|
||
|
||
`src/genesis/inference/__init__.py` 追加：
|
||
```python
|
||
from .engine import InferenceEngine
|
||
from .prompt_registry import PromptRegistry
|
||
# __all__ 追加 "InferenceEngine", "PromptRegistry"
|
||
```
|
||
|
||
- [ ] **Step 6: 文档补丁（实现批准 spec §3.9）**
|
||
|
||
- `docs/agent-runtime-design.md` §2.2 的 `StructuredResult` 代码块增加 `status: Literal["ok","fallback","parse_error","failed"]`（与 error 字段）
|
||
- `docs/api-design.md` §7 错误码表追加行 `| LLM_NOT_CONFIGURED | 503 | LLM Key 未配置 | 配置 Key | exceptions.LLMNotConfiguredError |`
|
||
- `docs/config-design.md` §4 `llm_calls.token_estimation` 注释追加「tiktoken 缺失自动回落 approximate（内置估算器）」
|
||
|
||
- [ ] **Step 7: 全量回归**
|
||
|
||
Run: `python -m pytest -v`
|
||
Expected: PASS（71 + 7 + 5 + 5 + 6 + 10 = 104 passed；`fail_under 99` 全绿）
|
||
|
||
- [ ] **Step 8: 提交**
|
||
|
||
```bash
|
||
git add src/genesis/engine.py docs/agent-runtime-design.md docs/api-design.md docs/config-design.md
|
||
git commit -m "feat: InferenceEngine chat/chat_structured 全流程 + 文档补丁（补丁1/2）"
|
||
```
|
||
|
||
---
|
||
|
||
## Self-Review
|
||
|
||
**1. Spec 覆盖**：§3.1 模块结构→Task1-5；§3.2 types→Task1；§3.3 client→Task4；§3.4 重试/降级→Task4(client 重试)+Task5(engine 主→备)；§3.5 token→Task2+Task5 裁剪；§3.6 Prompt→Task3；§3.7 engine→Task5；§3.8 异常→Task1+Task4；§3.9 文档→Task5 Step6；§3.10 测试→各任务 + 全量回归；§4 验收→Step7+验收清单。✓
|
||
**2. 占位符检查**：无 TODO/TBD；engine.py 每步有完整代码；修正笔误（`invalid`→`exceptions`）。✓
|
||
**3. 类型一致性**：`chat_structured` 签名（schema/retry_count）在各测试与实现一致；`FakeLLMClient.chat` 匹配 Protocol（model/messages/temperature/max_tokens）；`StructuredResult.status` 四值一致（ok/fallback/parse_error/failed）。✓
|
||
**4. 依赖顺序**：Task1 铺 types/exceptions；Task2 独立 token；Task3 用 Prompt；Task4 用 ChatMessage；Task5 全用。无循环导入（__init__ Task1 不引 engine，Task5 才 export）。✓
|
||
**5. 覆盖率红线**：每文件配分支测试（client 覆盖 5xx 重试/4xx 不重试/超时/未配置；engine 覆盖 ok/fallback/failed/超限/解析重试/parse_error/failed 网络失败）。✓
|
||
**6. 验收对齐**：chat_structured 在网格 4xx 等异常下返回 failed 而非抛——与 api §7 retry/skip/abort UX 一致；parse_error 带 raw_text 满足验收 3。✓
|
||
|
||
## 10. 提交消息
|
||
|
||
按 Global Constraints 提交消息风格：`feat:` / `test:` / `docs:` + 简中文描述，如上各任务 Step 5/8。 |