harness_zbt

智保通（第二阶段：知识服务与数据分析）

第二阶段完整继承智能投保业务，并增加保险知识检索、知识库管理、多模态材料识别和服务申请能力。系统仍由本地 H5 公众号模拟器、运营管理后台和统一 FastAPI 后端组成。

项目结构

./
├── backend/          # FastAPI、Agent Harness、业务领域与数据访问
├── frontend/
│   └── apps/
│       ├── h5/       # 本地 H5 公众号模拟器
│       └── admin/    # 运营管理后台
├── scripts/          # 环境、迁移、种子、启动和质量门禁
├── docs/             # 技术边界、测试用例和验证报告
└── README.md

核心技术

• Agent Harness：一个统一内核，客户顾问与运营助手两种人格。
• Agent 运行时：LangChain create_agent、DeepSeek、文件化 Prompt/Skill、Tool Registry、Policy Engine、结构化 UI Block/Action。
• 可观测性：统一 SSE 运行事件、本地 Run 持久化、Redis 热状态与限流、LangSmith 精确 Trace 深链。
• 业务后端：Python 3.12、FastAPI、Pydantic、SQLAlchemy、Alembic。
• 数据：本地 MySQL 8、Redis、Milvus；RabbitMQ 通过 TaskDispatcher 抽象保留替换边界。
• 知识服务：BGE-M3 向量化、Milvus 检索、关键词与向量混合召回、知识重排。
• 多模态：阿里云百炼托管 Qwen3.5-Plus，识别服务申请材料。
• 前端：Vue 3、TypeScript、Vite、pnpm workspace。
• 依赖与质量：uv、pytest、Ruff、mypy、vue-tsc。

第二阶段使用独立的 insurance_s2_* 数据库。database/mysql.sql 已包含从第一阶段继承后的业务数据，但只会重建第二阶段数据库。

首次初始化

先启动 Docker Desktop 中的 MySQL、Redis 以及本地 Milvus，并准备 Python 3.12、uv、Node.js 22 和 pnpm。

如果尚未准备 MySQL 和 Redis，请先阅读 Docker 基础环境使用说明，并使用其中的 database/compose.yaml。

项目只读取 backend/.env。确认其中的 MySQL、Redis、Milvus、模型服务和 LangSmith 配置后，在项目根目录按下面的顺序执行。

1. 安装项目依赖

Windows PowerShell、macOS 和 Linux 使用相同命令：

uv sync --project backend --locked
pnpm --dir frontend install --frozen-lockfile

2. 初始化 MySQL 数据

MySQL 数据来自 database/mysql.sql，其中已经包含第一阶段继承数据和第二阶段所需业务数据。下面的命令会自动导入 insurance_s2_core、insurance_s2_agent 和 insurance_s2_analytics。

Windows PowerShell：

.\scripts\init-databases.ps1

macOS / Linux：

./scripts/init-databases.sh

SQL 已经包含完整表结构和初始数据，因此首次初始化不需要再执行迁移、种子或阶段继承命令。

3. 初始化 Milvus 知识库

Windows PowerShell：

.\scripts\seed-knowledge.ps1

macOS / Linux：

./scripts/seed-knowledge.sh

启动

在项目根目录运行：

Windows PowerShell：

.\scripts\dev.ps1

macOS / Linux：

./scripts/dev.sh

启动脚本会检查端口、启动前后端、等待三个服务全部就绪，并在退出时统一清理子进程。

• H5：http://127.0.0.1:5173
• 管理后台：http://127.0.0.1:5174
• API 文档：http://127.0.0.1:8000/docs

本地 H5 验证码为 147258；初始后台账号为 admin，密码为 zaq1XSW@。

LangSmith

在 backend/.env 中配置：

LANGSMITH_TRACING=true
LANGSMITH_API_KEY=你的密钥
LANGSMITH_PROJECT=智保通-第二阶段-知识服务与数据分析

启动项目后，在 H5 Agent 回复或后台“运营智能体 → 智能体运行中心”中点击“打开 LangSmith”，即可进入该次调用的精确 Trace，而不是只打开 LangSmith 首页。Trace 未完成同步时，刷新运行中心即可重新解析深链。

真实模型评测

先启动整个项目，再在 backend 目录执行：

Windows PowerShell：

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

macOS / Linux：

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

两套评测均调用真实 DeepSeek、真实业务工具和真实 HTTP 接口，并检查回答、工具覆盖和 Trace 关联；配置 LangSmith 密钥后，基准样本与自动评分会同步到 LangSmith。

质量门禁

Windows PowerShell：

.\scripts\test.ps1

macOS / Linux：

./scripts/test.sh

该脚本执行后端测试、Ruff、mypy、前端类型检查与双端生产构建。真实 MySQL/Redis 集成测试以及真实模型评测单独执行，避免普通代码检查意外消耗模型额度。

所有 scripts/*.ps1 均提供同名的 scripts/*.sh，分别用于 Windows PowerShell 与 macOS/Linux。