feat(p8.3): 1h prompt caching TTL 启用 - ai/llm_client.py 增加 cache_ttl 参数

默认 "5m" (免费,会话内命中);可选 "1h" (cache_write +25% cost,跨会话命中)

cache_control 改为条件构建:1h 时加 {"ttl": "1h"} 字段
其他不变 (5m 仍走默认 ephemeral)。

7 个 unit test 覆盖参数验证 (5m / 1h 合法,其他值 ValueError)

Why: ADR-009 即将记录 - 重度用户一天内多次生成代码场景下,1h TTL
cache_read 跨会话命中,省 ~70% input token (cache write +25% 只算一次)。

Author: ZhaoXingPeng

src/dbjavagenix/ai/llm_client.py

@@ -147,17 +147,22 @@ def infer_names_via_llm(
     tables: List[Dict[str, Any]],
     model: str = "claude-sonnet-4-6",
     max_tokens: int = 4096,
+    cache_ttl: str = "5m",
 ) -> Optional[LLMResult]:
     """用 Claude API 推断业务命名 (启用 prompt caching)。
 
     Args:
         tables: [{name, columns, foreign_keys}] 列表
         model: Anthropic 模型 ID
         max_tokens: 最大输出 token
+        cache_ttl: prompt caching TTL,"5m" (默认,免费) 或 "1h" (cache write +25%
+                   但跨会话命中)。1h 适合用户一天内多次生成代码的场景。
 
     Returns:
         LLMResult 或 None (key 缺失 / 调用失败时)
     """
+    if cache_ttl not in ("5m", "1h"):
+        raise ValueError(f"cache_ttl must be '5m' or '1h', got {cache_ttl!r}")
     if not is_llm_available():
         logger.info("LLM not available: ANTHROPIC_API_KEY missing or anthropic SDK not installed")
         return None
@@ -175,14 +180,17 @@ def infer_names_via_llm(
 
     try:
         client = anthropic.Anthropic()
+        cache_control_block = {"type": "ephemeral"}
+        if cache_ttl == "1h":
+            cache_control_block["ttl"] = "1h"
         response = client.messages.create(
             model=model,
             max_tokens=max_tokens,
             system=[
                 {
                     "type": "text",
                     "text": NAMING_SYSTEM_PROMPT,
-                    "cache_control": {"type": "ephemeral"},
+                    "cache_control": cache_control_block,
                 }
             ],
             messages=[

tests/unit/test_llm_cache_ttl.py

@@ -0,0 +1,41 @@
+"""Unit tests for cache_ttl parameter in llm_client.infer_names_via_llm."""
+import pytest
+
+from dbjavagenix.ai.llm_client import infer_names_via_llm
+
+
+class TestCacheTtlValidation:
+    """Tests for the cache_ttl parameter — these don't require ANTHROPIC_API_KEY
+    since validation happens before the API call."""
+
+    def test_default_is_5m(self):
+        # Default arg = "5m" — calling with no cache_ttl should not raise
+        # ValueError. It may return None (no API key) but that's fine.
+        result = infer_names_via_llm(tables=[])
+        # result is None either because no API key, or because tables is empty
+        # The point is: no ValueError was raised
+        assert result is None or result.inferences == []
+
+    def test_explicit_5m_valid(self):
+        result = infer_names_via_llm(tables=[], cache_ttl="5m")
+        assert result is None or hasattr(result, "inferences")
+
+    def test_explicit_1h_valid(self):
+        result = infer_names_via_llm(tables=[], cache_ttl="1h")
+        assert result is None or hasattr(result, "inferences")
+
+    def test_invalid_ttl_raises(self):
+        with pytest.raises(ValueError, match="cache_ttl"):
+            infer_names_via_llm(tables=[], cache_ttl="30m")
+
+    def test_invalid_ttl_24h_raises(self):
+        with pytest.raises(ValueError):
+            infer_names_via_llm(tables=[], cache_ttl="24h")
+
+    def test_invalid_ttl_empty_raises(self):
+        with pytest.raises(ValueError):
+            infer_names_via_llm(tables=[], cache_ttl="")
+
+    def test_invalid_ttl_none_raises(self):
+        with pytest.raises(ValueError):
+            infer_names_via_llm(tables=[], cache_ttl=None)