# Agent LLM Config Implementation Plan

> **For Claude:** REQUIRED SUB-SKILL: Use superpowers:executing-plans to implement this plan task-by-task.

**Goal:** 将 `system_agents.config` 中的 `temperature` / `max_tokens` 以受约束方式加载到运行时，并在调用 LiteLLM 时按需透传。

**Architecture:** 在应用层 `RunService` 读取模型选择时同步读取并校验 `SystemAgents.config`；将校验后的 `SystemAgentLLMConfig` 传入 `CrewAIRuntime`；由 runtime 将配置转交给 LiteLLM client，client 仅在值非 `None` 时向 `completion()` 传参，避免不必要的 provider 兼容风险。

**Tech Stack:** FastAPI, SQLAlchemy (async), Pydantic v2, LiteLLM, pytest

---

## 背景与修正点

- 当前真实调用链为：`RunService._load_agent_model_selection()` -> `create_runtime()` -> `CrewAIRuntime.execute()` -> `run_completion()`，并非 `load_stage_models()`。
- `SystemAgentLLMConfig` 已存在：`backend/src/core/agent/domain/system_agent_config.py`。
- `system_agents.config` 目前在初始化 YAML 侧有约束，但运行时 DB 读取仍需二次校验，防止脏数据绕过。

## 规则约束

- 严格 TDD：先写失败测试，再做实现。
- Python 命令统一使用 `uv run ...`。
- 仅做增量改动，不回滚或覆盖与本任务无关的已有变更。

## 字段映射与透传策略

| 配置字段 | LiteLLM 参数 | 规则 |
|---|---|---|
| `temperature` | `temperature` | `None` 不透传；非空直接透传 |
| `max_tokens` | `max_tokens` | `None` 不透传；非空直接透传 |

---

### Task 1: 应用层加载并校验 Agent LLM Config

**Files:**
- Modify: `backend/src/core/agent/application/run_service.py`
- Test: `backend/tests/unit/core/agent/test_run_resume_service.py`

**Step 1: 写失败测试（RED）**

新增单测覆盖以下行为：
1. `_load_agent_model_selection()` 返回三元组：`(model_code, provider_name, llm_config)`。
2. 当 DB `config` 为 `{}` 时，`llm_config.temperature/max_tokens` 为 `None`。
3. 当 DB `config` 含非法值（如 `temperature=3`）时抛 `ValueError`。

**Step 2: 运行测试确认失败**

Run: `uv run pytest backend/tests/unit/core/agent/test_run_resume_service.py -q`
Expected: 新增断言失败（返回值结构/异常行为不匹配）。

**Step 3: 最小实现（GREEN）**

在 `run_service.py`：
1. 查询 `SystemAgents.config`。
2. 用 `SystemAgentLLMConfig.model_validate(config or {})` 校验。
3. 将 `_load_agent_model_selection()` 改为返回三元组。
4. 在 `run()` 中把 `llm_config` 传递到 `create_runtime(...)`。

**Step 4: 运行测试确认通过**

Run: `uv run pytest backend/tests/unit/core/agent/test_run_resume_service.py -q`
Expected: PASS。

---

### Task 2: Runtime 与 LiteLLM Client 支持可选参数透传

**Files:**
- Modify: `backend/src/core/agent/infrastructure/crewai/factory.py`
- Modify: `backend/src/core/agent/infrastructure/crewai/runtime.py`
- Modify: `backend/src/core/agent/infrastructure/litellm/client.py`
- Test: `backend/tests/unit/core/agent/test_crewai_runtime.py`

**Step 1: 写失败测试（RED）**

在 `test_crewai_runtime.py` 增加用例：
1. 传入 `temperature/max_tokens` 时，`run_completion` 收到对应参数。
2. 参数为 `None` 时，不应被透传到 LiteLLM。

必要时新增 `backend/tests/unit/core/agent/test_litellm_client.py`，单测 `run_completion` 的 kwargs 组装逻辑。

**Step 2: 运行测试确认失败**

Run: `uv run pytest backend/tests/unit/core/agent/test_crewai_runtime.py -q`
Expected: 新增断言失败（参数未透传或未过滤 `None`）。

**Step 3: 最小实现（GREEN）**

1. `create_runtime()` 增加 `llm_config` 参数并传给 `CrewAIRuntime`。
2. `CrewAIRuntime` 保存 `llm_config`，执行时调用：
   - `run_completion(..., temperature=llm_config.temperature, max_tokens=llm_config.max_tokens)`
3. `run_completion()` 改为支持可选 `temperature/max_tokens`，内部仅在非 `None` 时加入 kwargs 再调用 `completion()`。

**Step 4: 运行测试确认通过**

Run: `uv run pytest backend/tests/unit/core/agent/test_crewai_runtime.py -q`
Expected: PASS。

---

### Task 3: 初始化数据补齐与回归验证

**Files:**
- Modify: `backend/src/core/config/static/database/system_agents.yaml`
- Modify: `backend/src/core/config/initial/init_data.py`（如需补充类型兜底）
- Test: `backend/tests/unit/core/agent/test_run_resume_service.py`

**Step 1: 写失败测试（RED）**

补充断言：YAML 读取后 `config` 可为空或包含 `max_tokens: null`，初始化逻辑不会报错，且生成结构符合 `SystemAgentLLMConfig`。

**Step 2: 运行测试确认失败**

Run: `uv run pytest backend/tests/unit/core/agent/test_run_resume_service.py -q`
Expected: 新增断言失败。

**Step 3: 最小实现（GREEN）**

1. 在 `system_agents.yaml` 为各 agent 配置显式补充 `max_tokens: null`。
2. `init_data.py` 保持 `config: SystemAgentLLMConfig | None = None`，写库时统一序列化为 dict。

**Step 4: 运行测试确认通过**

Run: `uv run pytest backend/tests/unit/core/agent/test_run_resume_service.py -q`
Expected: PASS。

---

## 最终验证

1. `uv run pytest backend/tests/unit/core/agent/test_run_resume_service.py backend/tests/unit/core/agent/test_crewai_runtime.py -q`
2. `uv run pytest backend/tests/integration/core/agent/test_queue_run_resume.py -q`
3. `uv run ruff check backend/src backend/tests`
4. `uv run basedpyright`

预期：全部通过；若集成测试依赖本地 DB 状态导致跳过/失败，需记录原因并给出手工验证步骤。

## 完成标准

- `RunService` 从 DB 读取并校验 `config`。
- runtime 到 LiteLLM 链路支持 `temperature/max_tokens` 可选透传。
- `None` 不透传。
- 单测与相关集成测试通过，并给出命令级证据。