Bruce/DEMO-AGENT

Fork 0

Files

bruce d4a236d0db docs(requirements): 统一需求文档中文命名

2026-05-29 22:58:21 +08:00

5.1 KiB

Raw Blame History

智能核心模块需求文档

1. 模块定位

Agent Core 是系统的智能能力核心，负责根据场景配置完成 RAG 检索、工具调用、大模型调用和结构化输出。

该模块应保持独立于 Django View，方便后续迁移为独立服务，或接入 OpenAI Agents SDK、Dify 等外部编排引擎。

2. 模块目标

提供统一 Agent 执行入口。
根据场景配置组织 Prompt。
支持 RAG 检索。
支持工具注册与调用。
支持 OpenAI API 兼容的 LLM 与 Embedding 调用，可自主接入 OpenAI、硅基流动等兼容服务。
支持结构化输出解析。
返回可审计的 AgentResult。

3. 职责边界

3.1 负责

Agent 编排。
场景配置对象消费。
RAG 入库和检索核心逻辑。
工具注册和工具执行。
LLM Provider 适配。
输出结构化解析。
生成 AgentResult。

3.2 不负责

不渲染页面。
不直接处理 Django 表单。
不直接保存 Django Model。
不管理用户登录。
不负责 Docker 部署。

4. 子模块划分

agent_core/
  orchestrator.py
  scenario_loader.py
  llm_provider.py
  tool_registry.py
  structured_output.py

  rag/
    ingest.py
    retriever.py

  tools/
    builtin_tools.py

  schemas/
    outputs.py

5. Orchestrator 需求

orchestrator.py 提供统一入口：

run_agent(
  scenario_config,
  user_input,
  options=None
) -> AgentResult

执行流程：

读取场景配置。
根据配置判断是否启用 RAG。
按 scenario_id 和可选 document_ids 检索相关知识片段。
根据配置加载可用工具。
构造系统提示词。
调用大模型。
执行必要的工具调用。
解析结构化输出。
返回 AgentResult。

V1 可以使用轻量 Orchestrator，不强制引入完整 Agent SDK。

6. RAG 需求

6.1 入库

rag/ingest.py 负责：

接收文档文本。
文本切分。
通过 OpenAI 兼容 Embedding Provider 生成 embedding。
写入 Chroma。
保存 metadata。

metadata 至少包含：

scenario_id
document_id
source_file
chunk_id
created_at

6.2 检索

rag/retriever.py 负责：

根据用户问题检索相关片段。
支持按 scenario_id 过滤。
支持按本次对话选择的 document_ids 过滤；未选择时使用当前场景全部已入库文档。
返回 top_k 结果。
返回内容、来源和分数。

7. 工具系统需求

tool_registry.py 负责工具注册、查找和执行。

V1 内置工具：

工具名	说明
`calculate_rate`	计算通过率、缺陷率、占比等
`query_demo_records`	查询模拟业务数据
`check_required_fields`	检查必填项是否缺失
`generate_action_items`	生成行动项清单

工具执行结果需要统一格式：

{
  "tool_name": "calculate_rate",
  "success": true,
  "arguments": {},
  "result": {},
  "error": ""
}

8. LLM Provider 需求

llm_provider.py 负责模型调用。

V1 需要支持 OpenAI API 兼容 LLM 接口：

LLM_API_KEY
LLM_BASE_URL
LLM_MODEL

接口需要隐藏不同模型供应商差异，对 Orchestrator 暴露统一方法：

generate(messages, response_format=None) -> LLMResponse

Embedding 也通过 OpenAI 兼容接口接入：

EMBEDDING_API_KEY
EMBEDDING_BASE_URL
EMBEDDING_MODEL

当 Embedding 专用 Key 或 Base URL 为空时，可以复用 LLM 的 Key 和 Base URL。RAG 入库和检索必须通过真实 embedding 与 Chroma 完成，模拟 embedding 或简单文本匹配只能作为开发阶段临时桩，不计入 V1 验收。

9. 结构化输出需求

structured_output.py 负责将模型输出转换为业务结构。

V1 输出类型：

general_answer
document_review_report
ticket_response
quality_report
risk_audit_report

解析策略：

优先要求模型直接返回 JSON。
JSON 解析成功则展示结构化结果。
JSON 解析失败则保留原始输出，并返回解析错误。

10. AgentResult 需求

Agent Core 最终返回统一结果对象。

字段：

字段	说明
`answer`	最终自然语言回答
`structured_output`	结构化输出
`references`	RAG 引用片段
`tool_calls`	工具调用记录
`raw_output`	模型原始输出
`model_name`	模型名称
`latency_ms`	执行耗时
`status`	`success` / `failed`
`error`	错误信息

11. Adapter 扩展需求

V1 默认使用 LightweightOrchestrator。

后续可扩展：

OpenAI Agents SDK Adapter。
Dify API Adapter。
LangGraph Adapter。

Adapter 需要保持同样输入输出：

run_agent(scenario_config, user_input, options=None) -> AgentResult

12. 验收标准

Chat 模块可以调用 Agent Core 获得统一 AgentResult。
RAG 可以按场景检索知识片段。
RAG 可以按本次对话选择的文档范围检索知识片段。
工具调用结果可以记录并返回。
LLM 与 Embedding 配置可以通过环境变量切换。
结构化输出解析失败时不会导致整个流程崩溃。
Agent Core 不依赖 Django View。

5.1 KiB Raw Blame History Unescape Escape