harness_zbt

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

第三阶段完整继承前两个阶段的智能投保、Agentic RAG、长期记忆、多模态材料识别、服务申请和运营分析能力，并新增退保试算、风险分流、人工审批、退款 Worker、失败重试、异常干预和保单终止。

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

项目结构

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

核心技术

• Agent Harness：一个统一内核，客户顾问与运营助手两种人格。
• Agent 运行时：LangChain create_agent、DeepSeek、Persona、Skill、Tool Registry、Policy Engine 和结构化协议。
• 知识服务：Agentic RAG、BGE-M3、BGE Reranker、Milvus、知识引用聚合和拒绝推测。
• 生命周期编排：LangGraph 条件分支、并行风险检查、子图、Interrupt、Resume 和 MySQL Checkpoint。
• 退款执行：独立 Worker、Redis 单实例锁、任务租约、幂等、退避重试和异常恢复。
• 多模态：阿里云百炼 qwen3.5-plus 识别服务申请材料。
• 可观测性：MySQL Run 持久化、Redis 热状态、LangSmith Trace 和 OpenTelemetry。
• 业务后端：Python 3.12、FastAPI、Pydantic、SQLAlchemy、Alembic。
• 前端：Vue 3、TypeScript、Vite、pnpm workspace。
• 依赖与质量：uv、pytest、Ruff、mypy、vue-tsc。

第三阶段新增业务

• H5 对保障中的保单进行退保试算并提交退保申请。
• 确定性规则计算可退金额，Agent/工作流进行风险分析与流程分流。
• 低风险申请自动进入退款流程，高风险申请暂停并等待运营人员审批。
• 运营管理端查看退保申请、风险原因、流程时间线、退款尝试和 Worker 状态。
• 审批不通过时处理意见必填；审批完成或流程结束后控制区不可重复操作。
• 退款 Worker 自动领取任务，执行退款、记录尝试，并在达到重试阈值后转入人工干预。
• 退款成功后终止保单；退款异常时保持可恢复状态，避免错误终止保障。
• 本地 MCP 服务以只读方式向 Agent 提供合作医疗服务资源。

首次初始化

先启动 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 配置后，在项目根目录按顺序运行：

Windows PowerShell：

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

.\scripts\init-databases.ps1
.\scripts\seed-knowledge.ps1

macOS / Linux：

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

./scripts/init-databases.sh
./scripts/seed-knowledge.sh

以上命令依次完成后端依赖安装、前端依赖安装、MySQL 数据导入和 Milvus 知识库初始化。

MySQL 数据来自 database/mysql.sql，其中已经包含前两个阶段继承数据和第三阶段所需业务数据。init-databases 脚本会自动导入 insurance_s3_core、insurance_s3_agent 和 insurance_s3_analytics，因此首次初始化不需要再单独执行迁移、种子或阶段继承命令。

启动

在项目根目录运行：

Windows PowerShell：

.\scripts\dev.ps1

macOS / Linux：

./scripts/dev.sh

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

zbt-serve 是跨平台后端主管进程，会分别启动 FastAPI 和退款 Worker。正常情况下不需要再执行 zbt-refund-worker。

运行地址：

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

测试账号：

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

退款 Worker

退款涉及资金副作用，因此 Worker 默认启用 Redis 单实例锁，避免本地误启动多个主动执行者。zbt-serve 启动后会同时监管 API 和 Worker；任一进程异常退出时，主管进程会停止另一个进程，避免后端处于部分可用状态。

只有调试 Worker 时才单独运行：

Windows PowerShell：

.\scripts\run-refund-worker.ps1

macOS / Linux：

./scripts/run-refund-worker.sh

如果已有 Worker 持有单实例锁，新进程会进入待命或退出，不能同时领取退款任务。管理端“退保工作台”可以查看 Worker 在线状态、退款尝试和失败原因。

LangSmith

在 backend/.env 中配置：

LANGSMITH_TRACING=true
LANGSMITH_API_KEY=你的密钥
LANGSMITH_PROJECT=智保通-第三阶段-智能保全与退款编排
LANGSMITH_OTEL_ENABLED=true

LangSmith 用于查看 Agent、Tool 和 LangGraph 执行链路；MySQL 中的 Run、工作流时间线和退款尝试仍是业务审计记录。

真实模型评测

先启动整个项目，再在 backend 目录执行。Windows PowerShell 和 macOS 使用相同命令：

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

评测会调用真实模型、真实业务 Tool 和真实 HTTP 接口，并检查回答、工具覆盖、工作流行为和 Trace 关联。

质量门禁

Windows PowerShell：

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

macOS / Linux：

./scripts/test.sh

质量门禁检查后端测试、Ruff、mypy、前端类型和双端生产构建。真实模型评测单独执行，避免普通代码检查意外消耗模型额度。

构建后端安装包

Windows PowerShell：

Set-Location backend
uv build

macOS：

cd backend
uv build

构建结果生成在 backend/dist，包括 wheel 和源码包。

相关文档

• docs/第三阶段新增业务与测试.md：第三阶段新增功能和测试场景。
• docs/智保通三阶段业务与ProcessOn技术.md：三个阶段的业务与技术映射。
• docs/项目启动与使用指南.md：项目运行和使用说明。

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