harness_zbt

智保通（第三阶段：生命周期工作流）

本项目完整包含前两个阶段的智能投保、知识服务、多模态材料识别、服务申请和运营分析，并新增退保试算、风险分流、人工审批、Worker 自动退款、技术失败重试、补偿和保单终止。

系统由本地 H5 公众号模拟器、PC 运营管理端和统一 FastAPI 后端组成。普通咨询继续使用 LangChain Agent；需要暂停、审批和恢复的长流程由 LangGraph 编排。

主要能力

• 一个 Agent 内核，客户保障顾问与运营数据助手两种人格。
• H5 完成咨询、投保、支付、保单、服务申请和退保退款进度查询。
• PC 端完成业务运营、知识管理、服务受理、退保审批和退款异常处理。
• 退保金额与风险由确定性规则计算；低风险自动通过，高风险强制人工审批。
• LangGraph 使用并行风险检查、条件分支、子图、Interrupt、Resume 和 MySQL Checkpoint。
• 退款 Outbox Worker 使用租约、幂等、退避重试、死任务恢复和补偿。
• 退款结算在单个 MySQL 事务中同步收口退款尝试、退保申请、保单和审计时间线。
• Worker 抢锁失败后进入轻量待命，原实例退出或租约过期后自动接管。
• 本地 MCP 服务只读提供合作医疗服务资源；异常时返回空结果，Agent 不得编造。
• LangSmith 与 OpenTelemetry 记录 Agent、LangGraph、工具、审批和恢复轨迹。

项目结构

03-zhibaotong-lifecycle-workflow/
├── backend/          # FastAPI、LangChain、LangGraph、Agent Harness
├── frontend/
│   └── apps/
│       ├── h5/       # 本地 H5 公众号模拟器
│       └── admin/    # PC 运营管理端
├── database/         # 第一至第三阶段完整 MySQL 初始化脚本
├── knowledge/        # 知识库初始化内容
├── scripts/          # 启动、知识初始化、退款工作器和质量门禁
└── docs/             # 业务、技术和使用说明

快速启动

首次运行先按 第一、二、三阶段启动指南 完成依赖、MySQL 和 Milvus 初始化。

日常可在项目根目录一次启动后端、H5、管理端和退款工作器：

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

macOS（两个终端）：

# 终端一
cd backend
uv run zbt-serve

# 终端二
cd frontend
pnpm dev

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

H5 验证码为 147258；后台账号及完整操作路径见启动指南。

质量门禁

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

macOS：

cd backend
uv sync --locked
uv run pytest
uv run ruff check .
uv run mypy src/zbt

cd ../frontend
pnpm install --frozen-lockfile
pnpm typecheck
pnpm build

真实模型评测在后端运行后执行：

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

macOS：

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