harness_zbt/backend

智保通第二阶段后端

本目录是智保通第二阶段“知识服务与数据分析”的统一后端。项目完整继承第一阶段的智能投保、订单、支付、保单、推广归因和后台治理能力，并在同一个 Agent Kernel 上增加 Agentic RAG、客户长期记忆、多模态材料识别、保单服务和运营趋势分析。

后端采用 Python 3.12、FastAPI 和 src/zbt 可安装包布局，通过 uv 管理依赖和虚拟环境。

1. 第二阶段新增能力

H5 客户端

• Agentic RAG 保险咨询：复杂问题拆分、查询改写、多轮检索和证据聚合。
• 有依据时展示知识来源；知识库未明确时拒绝推测。
• 客户长期记忆：保存明确表达的保障偏好，在新会话中召回并支持删除。
• 敏感信息保护：手机号、身份证号、银行卡号等内容禁止写入长期记忆。
• 保单服务：从保障中的保单发起申请，上传图片并使用多模态模型识别材料。
• 服务记录：查看申请状态和运营处理结果。

运营管理端

• 知识中心：上传/创建 → 索引 → 检索测试 → 发布。
• 检索测试记录持久化；发布前必须存在有效的检索测试记录。
• 服务申请中心：查看原始材料、识别字段和识别可信度，并进行受理或不受理处理。
• 运营智能体：分析订单量、订单保费、有效保单量和有效保单保费。
• 趋势分析：支持最近 7、30、90 天，并按日期或产品生成图表数据。
• Agent 历史会话和运行记录按用户、人格与权限范围隔离。

2. Agent 技术架构

项目保留“一个内核、两种人格”的设计：

• customer：客户保障顾问，负责保险咨询、投保引导、知识问答和客户记忆。
• operation：运营数据助手，负责业务指标、趋势和推广归因分析。
• Agent Kernel：统一管理 Persona、Skill、Tool 白名单、策略校验、结构化 UI Block、运行事件和异常边界。

主要调用链：

HTTP 请求
  → AgentThreadService
  → Agent Kernel
  → Persona + Skill + Policy
  → LangChain create_agent
  → DeepSeek
  → 受控业务 Tool / 知识检索 Tool
  → 结构化响应
  → MySQL 运行记录 + Redis 热状态 + LangSmith Trace

知识检索链路：

问题拆分与改写
  → BGE-M3 向量化
  → Milvus 向量召回 + 关键词召回
  → BGE Reranker 重排
  → 证据聚合与去重
  → 带来源回答或拒绝推测

医疗材料识别通过阿里云百炼兼容接口调用 qwen3.5-plus，识别结果作为候选字段保存，不能替代用户确认和运营处理。

3. 目录结构

backend/
├── src/zbt/
│   ├── api/                 # FastAPI 路由、鉴权和响应封装
│   ├── commands/            # 数据、知识库和评测命令
│   ├── core/                # 配置、安全、错误和公共能力
│   ├── domains/             # 投保、Agent、知识、记忆、服务申请等领域
│   ├── harness/             # Agent 内核、Persona、Skill、Policy 和结构协议
│   ├── infrastructure/      # MySQL、Redis、Milvus 和外部模型适配器
│   └── main.py              # FastAPI 应用装配入口
├── migrations/              # Core、Agent、Analytics 三库迁移
├── evals/                   # 真实模型评测数据
├── tests/                   # 自动化测试
├── var/                     # 本地服务材料等运行文件
├── alembic.ini
├── pyproject.toml
└── uv.lock

4. 运行环境

需要提前安装并启动：

• Python 3.12
• uv
• MySQL 8
• Redis
• Milvus
• Node.js 22 和 pnpm（启动前端时需要）

后端读取 backend/.env。主要配置包括：

配置类别	环境变量
MySQL	MYSQL_HOST、MYSQL_PORT、MYSQL_USER、MYSQL_PASSWORD、三个 MYSQL_*_DATABASE
Redis	REDIS_URL、REDIS_PREFIX
Milvus	MILVUS_URI、MILVUS_TOKEN、MILVUS_COLLECTION_PREFIX
向量模型	BGE_M3_MODEL_PATH、BGE_M3_DEVICE、BGE_RERANKER_MODEL_PATH、BGE_RERANKER_DEVICE
文本模型	DEEPSEEK_API_KEY、DEEPSEEK_BASE_URL、DEEPSEEK_MODEL
多模态模型	DASHSCOPE_API_KEY、DASHSCOPE_BASE_URL、DASHSCOPE_VISION_MODEL
可观测性	LANGSMITH_TRACING、LANGSMITH_API_KEY、LANGSMITH_ENDPOINT、LANGSMITH_PROJECT
安全配置	JWT_ACCESS_SECRET、JWT_REFRESH_SECRET、FIELD_ENCRYPTION_KEY

如尚未创建 .env：

Windows PowerShell：

Set-Location backend
New-Item -ItemType File -Path .env -ErrorAction SilentlyContinue
notepad .env

macOS：

cd backend
touch .env
open -e .env

不要将包含真实数据库密码和模型密钥的 .env 提交到 Git。

5. 首次初始化

第二阶段首次运行所需的数据库快照、Milvus 初始化脚本和启动说明统一保存在：

../database/项目启动文档与数据准备.zip

请将压缩包解压到当前仓库根目录，然后打开相对路径 ../项目启动文档与数据准备/智保通第一、二、三阶段启动指南.md，按照“第二阶段：知识服务与运营分析”一节执行。该指南及配套脚本会自动定位仓库根目录，不依赖 harness_zbt 或其他固定目录名。

压缩包中的第二阶段 mysql.sql 只初始化 insurance_s2_core、insurance_s2_agent 和 insurance_s2_analytics，并已包含第一阶段继承数据。不要再使用项目内旧 SQL，也不要额外执行 Alembic、seed、inherit_stage_one 或 build_analytics。

6. 启动项目

6.1 Windows 一次启动

在项目根目录执行：

powershell -ExecutionPolicy Bypass -File .\scripts\dev.ps1

该脚本同时启动 FastAPI、H5 和运营管理后台。

6.2 Windows 分别启动

后端：

Set-Location backend
uv run uvicorn zbt.main:app --host 127.0.0.1 --port 8000 --reload

H5：

Set-Location frontend
pnpm dev:h5

管理后台：

Set-Location frontend
pnpm dev:admin

6.3 macOS / Linux 一次启动

./scripts/dev.sh

不要在 frontend/apps/h5 或 frontend/apps/admin 目录执行 pnpm dev:h5、pnpm dev:admin；这两个命令属于前端 workspace 根目录。

6.4 运行地址

• H5：http://127.0.0.1:5173
• 管理后台：http://127.0.0.1:5174
• Swagger：http://127.0.0.1:8000/docs
• OpenAPI JSON：http://127.0.0.1:8000/openapi.json
• 健康检查：http://127.0.0.1:8000/api/v1/system/health/live

测试账号：

• H5：18800000001，验证码 147258
• 管理员：admin / zaq1XSW@
• 运营人员：operator01 / zaq1XSW@
• 审核人员：reviewer01 / zaq1XSW@

7. 单独启动后端

如果只调试 API，可只运行 FastAPI。

Windows PowerShell：

Set-Location backend
uv run uvicorn zbt.main:app --host 127.0.0.1 --port 8000 --reload

macOS：

cd backend
uv run uvicorn zbt.main:app --host 127.0.0.1 --port 8000 --reload

后端启动时会预加载 BGE-M3 和 BGE Reranker。首次下载或首次载入模型时，终端可能长时间显示 Hugging Face 下载和权重加载信息；出现 Application startup complete 后再测试知识问答。

8. 真实模型评测

先启动项目，再在 backend 目录执行。

Windows PowerShell：

uv run python -m zbt.commands.evaluate_agents --suite smoke
uv run python -m zbt.commands.evaluate_agents --suite full

macOS：

uv run python -m zbt.commands.evaluate_agents --suite smoke
uv run python -m zbt.commands.evaluate_agents --suite full

评测会调用真实文本模型、真实业务 Tool 和真实 HTTP 接口。启用 LangSmith 后，可在对应项目中查看运行 Trace 和评测记录。

9. 测试和代码检查

Windows PowerShell（在项目根目录执行）：

powershell -ExecutionPolicy Bypass -File .\scripts\test.ps1

macOS / Linux（在项目根目录执行）：

./scripts/test.sh

普通代码检查不会替代真实模型评测。涉及 Agent 决策、知识引用和 Tool 调用顺序的行为，应另外运行第 8 节的评测命令。

10. 数据库迁移命令

当前推荐使用完整 SQL 快照进行首次初始化。只有在开发新的表结构变更时，才需要手动执行 Alembic。

Windows PowerShell 与 macOS 均在 backend 目录执行：

uv run alembic -c alembic.ini --name alembic_core upgrade head
uv run alembic -c alembic.ini --name alembic_agent upgrade head
uv run alembic -c alembic.ini --name alembic_analytics upgrade head

已经发布的迁移文件不要直接修改；表结构发生变化时应创建新的 revision。

11. 构建后端安装包

Windows PowerShell：

Set-Location backend
uv build

macOS：

cd backend
uv build

构建结果生成在 backend/dist，包括 wheel 和源码包。日常开发继续使用 uv sync --locked 和 uv run，无需手工安装构建产物。

12. 相关文档

• ../README.md：第二阶段项目总览和快速启动。
• ../docs/第二阶段新增能力与测试.md：第二阶段新增业务及建议测试场景。
• ../docs/智保通第一、二阶段启动指南.md：两个阶段的完整启动说明。

项目根目录中的每个 scripts/*.ps1 均提供同名 scripts/*.sh，分别用于 Windows PowerShell 与 macOS/Linux。