Model & Tool Config
Model & Tool Config
1. 目标 & 范围
目标：让 admin/researcher 能够在不修改业务代码的情况下，自由切换 LLM provider 与模型；对每种 Agent 角色独立配置模型参数；通过 Tool Registry 集中注册和管理工具；在 study 级别精细控制哪些工具可被 Agent 调用；记录每次模型调用的 token 与成本。
范围（本模块）：
- Provider 与模型配置（经 LiteLLM 多 provider 解耦）
- Model roles（
interviewer/extraction/synthesis/safety/embedding） - 温度、max tokens、fallback、cost limit 等参数
- Tool Registry（
ToolDefinition注册、execution_mode、risk_level） - Study-level tool policy（
enabled_tools/disabled_tools/tool_configs/interaction_limits/approval_required） - Credentials 管理（API key 存储与隔离）
- 成本与 token 使用记录
不含：知识库配置（见模块 08）；study brief / objectives / output schema 配置（见 03_study_builder）；访谈运行时调度逻辑（见 03_architecture/02_agent_harness）。
2. 用户故事
作为 admin，我希望在平台设置页面配置多个 LLM provider（OpenAI、Anthropic、Google、Azure、Ollama…）并存储对应 API key，以便切换 provider 时不改任何业务代码。
作为 admin，我希望为平台设置全局默认的 ModelConfig（含 fallback chain），以便所有新 study 自动继承合理默认值。
作为 researcher，我希望在 Study Builder 中为每种 model role 独立选择模型和参数（温度、max tokens），以便让 interviewer 注重对话质量、extraction model 注重结构化稳定性、synthesis model 注重长上下文。
作为 researcher，我希望在 study 级别开启或禁用特定工具，并对高风险工具设置 approval_required，以便精确控制 Agent 能力边界。
作为 admin，我希望在 Tool Registry 中注册、查看和管理平台所有 ToolDefinition（含 execution_mode 和 risk_level），以便统一维护工具能力清单。
作为 admin，我希望为每次模型调用自动记录 provider、model、输入/输出 token 数和估算成本，并在 study/project 维度汇总，以便控制运营成本。
作为 admin，我希望查看高风险工具的 approval 记录与 audit log，以便满足合规审计需求。
3. 功能需求
3.1 Provider 与凭证管理
FR-09-1（P1）Provider 配置
平台支持配置以下 provider：openai / anthropic / google / azure_openai / ollama / vllm / custom。每个 provider 需填写名称、base URL（可选）、API key（加密存储）、是否启用。
- 验收：配置保存后，admin 可在 model role 选择界面看到对应 provider 的可用模型列表；删除 provider 时，依赖该 provider 的 study 应收到告警而非静默失效。
FR-09-2（P1）Credentials 安全存储 API key 在数据库中加密存储，不以明文出现在任何 API 响应、日志或前端页面；provider 标识符与 key 不进入业务逻辑层（LangGraph graph / Harness）。
- 验收：GET
/api/admin/providers返回 provider 列表时，api_key字段只返回末 4 位掩码；日志中搜索不到完整 key 字符串。
FR-09-3（P1）LiteLLM Gateway 对接
所有模型调用经 LiteLLM 统一网关路由，业务代码只调用 ModelProviderAdapter 接口（见 03_architecture/04_model_tool_kb_abstraction）；更换 provider 只需修改配置，不修改 Harness 代码。
- 验收：在配置层将
interviewer_model.provider从openai改为anthropic，Harness 测试用例无需代码改动即可通过。
3.2 Model Config 与 Roles
FR-09-4（P1）平台全局默认 ModelConfig
admin 可设置平台级默认 ModelConfig（provider、model、temperature、max_tokens、top_p、timeout_ms、retry_policy、structured_output、tool_calling），所有新建 agent_config 自动继承。
- 验收：创建新 study 后，
agent_config_versions.model_config的字段与平台默认值一致（未被 researcher 覆盖时）。
FR-09-5（P1）Model Roles 配置（StudyModelRoles）
Study Builder 的”模型配置”面板允许 researcher 为以下 5 个 role 独立配置 ModelConfig：
interviewer_model：对话质量优先，需支持tool_calling: trueextraction_model：结构化输出优先，需支持structured_output: truesynthesis_model：长上下文和摘要优先safety_model（可选）：用于内容合规检测embedding_model（可选，EmbeddingConfig）：仅在 KB/RAG 启用时生效
Role 配置存入 agent_config_versions.model_config（JSONB，结构对应 StudyModelRoles）。
- 验收：将
extraction_model换为不支持structured_output的模型时，保存时提示警告；interviewer_model需tool_calling: true，否则 study 无法发布。
FR-09-6（P1）温度 / max_tokens / fallback / cost limit
每个 role 可单独设置 temperature（0–2）、max_tokens（1–128000，依模型上限约束）；admin 可配置 fallback model（主模型失败时自动切换）；可为 study 设置单 session 最大 cost limit，达到上限后 Harness 调用 conclude_interview。
- 验收：主模型返回 5xx 时，Harness 自动使用 fallback model 重试，重试次数写入
agent_decision_log；session cost 超过 limit 时，session 状态变为completed，tool_calls中记录 conclude reason =cost_limit_exceeded。
3.3 Tool Registry
FR-09-7（P1）ToolDefinition 注册与管理
admin 可在 Tool Registry 页面查看平台所有 ToolDefinition（对应 tool_definitions 表）。每条记录包含：
-
id、name、display_name、description -
tool_type：interaction/retrieval/extraction/export/analysis/governance -
input_schema/output_schema（JSON Schema） -
version -
execution_mode：frontend/backend/hybrid -
risk_level：low/medium/high -
enabled：全局启停开关 -
验收：
tool_definitions表中，每条记录的input_schema/output_schema为合法 JSON Schema；tool_type枚举值合法；risk_level = high的工具在 UI 中有醒目标注。
FR-09-8（P1）execution_mode 与调用路由
Tool Registry 为每个工具标注 execution_mode：
frontend（如render_interaction）：由前端执行，AG-UI 工具调用事件推送到 assistant-ui；backend（如retrieve_knowledge、extract_fields、export_results）：由 Harness Python 后端执行；hybrid（如文件上传）：前后端协同。
Harness 根据 execution_mode 决定分发路径，不允许 frontend 工具绕过前端直接在 backend 执行。
- 验收：
render_interaction工具调用事件通过 AG-UI SSE 流推送到前端，而非在后端 resolve；retrieve_knowledge调用直接在 Harness 后端执行并返回结果；两者均有对应tool_calls记录。
FR-09-9（P1）全局工具启停
admin 可在 Tool Registry 将某工具的 tool_definitions.enabled 设为 false，该工具全平台不可被任何 study 调用，无论 study 的 study_enabled_tools 如何配置。
- 验收：将
export_results的enabled置为 false 后，任何 study 的study_enabled_tools即使将其设为enabled = true，Harness 调用时仍返回tool_not_available错误，tool_calls.status = failed，tool_calls.error含globally_disabled。
3.4 Study-level Tool Policy
FR-09-10（P1）Study Tool Policy 配置界面
Study Builder 的”工具配置”面板展示所有全局启用的 ToolDefinition，researcher 可为当前 study 设置：
- 启用 / 禁用各工具（
study_enabled_tools.enabled） - 每个工具的自定义参数（
study_enabled_tools.config，基于该工具的input_schema子集） - 交互组件上限（
interaction_limits.max_interactions_per_session、max_modal_interactions） - 需要 approval 的工具列表（
approval_required，对应agent_config_versions.tool_policy.approval_required）
Policy 快照存入 study_versions.enabled_tool_ids（JSONB）及 agent_config_versions.tool_policy（JSONB，对应 StudyToolPolicy）。
- 验收：发布 study 后，
study_versions.enabled_tool_ids包含且只包含研究人员勾选的工具 id；修改工具策略并创建新 version，老 session 仍按老 version 的 policy 执行。
FR-09-11（P1）未启用工具不可调用
Harness 在每次工具调用前，先检查目标工具是否在当前 session 对应的 study_version 的 study_enabled_tools 中且 enabled = true；若不满足则拒绝调用。
- 验收：Harness 单测中，将
retrieve_knowledge从enabled_tools移除，Agent 尝试调用时，tool_calls记录状态为failed，error = tool_not_enabled_for_study，session 不中断，Agent 继续下一步骤。
FR-09-12（P1）Approval 机制
risk_level = high 的工具，若出现在 approval_required 列表，Harness 调用前需等待 admin/researcher 人工审批（可通过 Results 页面 / 邮件通知触发）；审批通过后记录 audit_logs，审批拒绝后工具调用记为 rejected。
- 验收：
export_results（risk_level = high）被加入approval_required后，Harness 调用时 session 状态变为waiting_for_approval；通过审批后自动恢复执行；拒绝时tool_calls.status = rejected；两个路径均有audit_logs记录，含actor_id、action、created_at。
3.5 成本与 Token 记录
FR-09-13（P1）逐次调用 token/cost 记录
每次 LLM 调用完成后，Harness 记录：provider、model、prompt_tokens、completion_tokens、total_tokens、估算 cost（USD）、latency_ms。数据写入 agent_decision_log（token_usage 字段，见 03_architecture/02_agent_harness）及可观测后端（LangSmith / OpenTelemetry）。
- 验收：一次完整 session 结束后，
agent_decision_log中所有记录的token_usage非空；sum(total_tokens) 与 LangSmith traces 的记录误差在 ±5% 以内。
FR-09-14（P1）Study/Session 维度成本汇总 admin/researcher 可在 Results / Settings 页面查看 study 和单 session 的累计 token 用量与估算成本；成本数据按 role（interviewer / extraction / synthesis）分项展示。
- 验收：UI 展示的 study 累计 cost = 所有 session 的各 role cost 之和（误差 ±1%）；数据来源可追溯至
agent_decision_log逐条记录。
4. 关键流程
4.1 Provider 配置 → Study 发布
admin 进入 Settings > Model Providers -> 填写 provider / model / API key -> 保存（key 加密入库） -> LiteLLM gateway 验证可达性 -> 标记 provider 可用
researcher 进入 Study Builder > 模型配置 -> 为各 role 选择 provider + model -> 设置 temperature / max_tokens / fallback -> 保存为 agent_config_version（model_config JSONB）
researcher 进入 Study Builder > 工具配置 -> 勾选 enabled tools -> 设置 tool_configs + interaction_limits + approval_required -> 快照写入 study_versions.enabled_tool_ids + agent_config_versions.tool_policy
study 发布 -> session 绑定 study_version_id -> Harness 以该 version 的配置运行4.2 Harness 工具调用检查链
Agent 决定调用 tool X -> 检查 tool_definitions.enabled == true（全局） -> 检查 study_enabled_tools.enabled == true（study 级） -> 检查 approval_required 列表 -> 若在列表：session 置 waiting_for_approval，写 audit_log，等待人工审批 -> 审批通过：继续；拒绝：tool_calls.status = rejected -> 按 execution_mode 路由（frontend via AG-UI / backend / hybrid） -> 执行完成：写 tool_calls 记录（input / output / status / latency） -> 记录 token_usage 至 agent_decision_log4.3 model role 与 extraction 的配置流
extraction 触发（checkpoint / final） -> Harness 取 agent_config_versions.model_config.extraction_model -> 经 LiteLLM gateway 路由（provider 解耦） -> structured_output = true，pydantic + instructor 解析 -> 结果写 extracted_fields，token_usage 写 agent_decision_log（role=extraction）5. 数据
涉及以下实体（详见 03_architecture/03_data_model）：
| 表 | 本模块关注字段 |
|---|---|
agent_configs | id, project_id, name |
agent_config_versions | model_config（JSONB，StudyModelRoles）, tool_policy（JSONB，StudyToolPolicy）, safety_policy |
tool_definitions | id, name, tool_type, input_schema, output_schema, version, execution_mode, risk_level, enabled |
study_enabled_tools | study_version_id, tool_definition_id, config（JSONB）, enabled |
study_versions | enabled_tool_ids（JSONB）, agent_config_version_id |
audit_logs | 工具 approval 事件、provider 变更事件 |
tool_definitions 表缺少 execution_mode 与 risk_level 列（当前 DDL 只含基本字段）——落地时需补充迁移，或在 metadata JSONB 中扩展，与 03_architecture/03_data_model 保持一致。
6. 接口
涉及以下接口（详见 05_implementation/02_api_contracts）：
| 接口 | 说明 |
|---|---|
GET /api/admin/providers | 列出所有 provider（key 掩码） |
POST /api/admin/providers | 创建 provider（含加密 key） |
PUT /api/admin/providers/{id} | 更新 provider 配置 |
DELETE /api/admin/providers/{id} | 删除 provider（有依赖时告警） |
GET /api/admin/tools | 列出 Tool Registry 所有 ToolDefinition |
PUT /api/admin/tools/{id} | 更新工具全局启停或元数据 |
GET /api/studies/{id}/agent-config | 获取当前 study 的 model config + tool policy |
PUT /api/studies/{id}/agent-config | 保存 model config + tool policy（创建新 agent_config_version） |
GET /api/studies/{id}/cost-summary | 查询 study 维度的 token/cost 汇总 |
POST /api/admin/tool-approvals/{tool_call_id}/approve | 审批通过高风险工具调用 |
POST /api/admin/tool-approvals/{tool_call_id}/reject | 拒绝高风险工具调用 |
7. 验收标准
AC-09-1：admin 在 Provider 设置页面添加 Anthropic provider 并填写 API key，保存后 key 末 4 位可见、前缀掩码；在 Study Builder 的 model role 下拉中可选到 claude-3-5-sonnet；切换 provider 后 Harness 集成测试无需改代码即可通过。
AC-09-2：在 agent_config_versions.model_config 中为 extraction_model 配置不支持 structured_output 的模型时，study 发布接口返回 400 validation_error，提示 extraction_model requires structured_output=true。
AC-09-3：将平台全局 tool_definitions.enabled = false（针对任意工具）后，该 study 的 study_enabled_tools 即使标记 enabled，Harness 调用该工具时 tool_calls.status = failed，error 包含 globally_disabled。
AC-09-4：researcher 在 Study Builder 工具配置中不勾选 retrieve_knowledge，发布后 session 运行时 Agent 尝试调用该工具，tool_calls.status = failed，error = tool_not_enabled_for_study，session 继续执行（不中断）。
AC-09-5：risk_level = high 且在 approval_required 的工具被 Agent 调用时，session 状态变为 waiting_for_approval；admin 调用 approve 接口后 session 恢复执行；拒绝时 tool_calls.status = rejected；两个路径均在 audit_logs 表生成记录，含 actor_id、action、resource_id、created_at。
AC-09-6：session 运行时 interviewer_model 主 provider 返回 HTTP 500，Harness 自动切换 fallback model 并完成该轮调用；agent_decision_log 该条记录包含 retry_count >= 1 和实际使用的 model 标识。
AC-09-7：session cost 超过 study 配置的 cost_limit，Harness 自动调用 conclude_interview，tool_calls 中该次 conclude 的 tool_input.reason = cost_limit_exceeded，session status = completed。
AC-09-8：一次完整 session（含 interviewer / extraction 两个 role 调用）结束后，/api/studies/{id}/cost-summary 返回的 total_cost = 各 agent_decision_log 记录 cost 之和（误差 ±1%），并按 role 分项。
AC-09-9：render_interaction 工具调用通过 AG-UI SSE 事件推送到前端（execution_mode = frontend），不在后端执行；retrieve_knowledge 在后端执行（execution_mode = backend）；两者均有 tool_calls 落库记录。
AC-09-10：修改 study 工具策略后系统创建新 study_version；已运行的 session 仍绑定旧 study_version_id，使用旧 tool policy；新 session 使用新 policy。
8. 边界 & 非目标
- 不含知识库（KB）的配置与 RAG 检索策略，见模块 08。
- 不含用量计费与对外收费系统，本模块只做内部成本记录与告警。
- 不含模型微调（fine-tuning）管理。
- 不含自动化模型评估（eval pipeline），属于未来迭代。
safety_model在 MVP 阶段为可选；安全策略的具体规则不在本模块定义。- Approval 流程 MVP 阶段为同步人工确认（站内通知），不做邮件/Webhook 集成。
embedding_model仅在 KB 模块激活后生效，本模块只负责配置存储。
9. 依赖 & 风险
| 项 | 说明 |
|---|---|
| 依赖：03_architecture/04_model_tool_kb_abstraction | ModelConfig / StudyModelRoles / StudyToolPolicy / ToolDefinition 定义 |
| 依赖：03_architecture/03_data_model | agent_configs / agent_config_versions / tool_definitions / study_enabled_tools 表结构 |
| 依赖：03_architecture/02_agent_harness | Harness 工具调用检查链、AgentDecisionLog.token_usage |
| 依赖：03_architecture/05_tech_stack_decision | LiteLLM 为统一 gateway；可观测采用 LangSmith + OpenTelemetry |
| 依赖：03_study_builder | Study Builder 提供模型配置与工具配置 UI 入口 |
风险：tool_definitions DDL 缺 execution_mode / risk_level 列 | 落地时需补 migration；可在 metadata JSONB 中临时扩展，后期迁出 |
| 风险：LiteLLM token 计数与 provider 实际计费存在差异 | 仅作内部成本参考，需在文档中注明”估算”；长期接入 provider 官方 usage API 对账 |
风险：Approval 等待期间 session 长时间 waiting_for_approval | 需设置超时（如 24h）自动 reject 并通知；MVP 阶段手动处理 |
| 风险：多 provider API key 安全存储 | 采用应用层加密（AES-256）+ 环境变量主密钥；密钥轮转策略待定 |