harness_zbt

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

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

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

项目结构

03-zhibaotong-lifecycle-workflow/
├── 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 提供合作医疗服务资源。

首次初始化

第三阶段的数据库快照、Milvus 初始化入口和完整启动说明统一保存在第二阶段项目提供的公共压缩包中：

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

首次运行时，将压缩包解压到三个阶段项目的共同父目录，然后打开其中的 项目启动文档与数据准备/智保通第一、二、三阶段启动指南.md，按照“第三阶段：全生命周期工作流”一节完成环境准备、依赖安装、第三阶段 MySQL 导入、Milvus 初始化和统一启动。

压缩包中的第三阶段 mysql.sql 只重建 insurance_s3_core、insurance_s3_agent 和 insurance_s3_analytics，并已包含前两个阶段继承后的业务数据。

不要再执行项目内旧 SQL、迁移脚本、种子脚本或阶段继承脚本。数据库和 Milvus 的首次初始化以压缩包内指南为唯一入口。

启动

Windows PowerShell

在项目根目录运行：

powershell -ExecutionPolicy Bypass -File .\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。