# 智保通（第三阶段：生命周期工作流） 第三阶段完整继承前两个阶段的智能投保、Agentic RAG、长期记忆、多模态材料识别、服务申请和运营分析能力，并新增退保试算、风险分流、人工审批、退款 Worker、失败重试、异常干预和保单终止。 系统由本地 H5 公众号模拟器、PC 运营管理端和统一 FastAPI 后端组成。普通咨询继续使用 LangChain Agent；需要暂停、审批和恢复的长流程由 LangGraph 编排。 ## 项目结构 ```text ./ ├── 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/Docker基础环境使用说明.md)，并使用其中的 `database/compose.yaml`。 项目只读取 `backend/.env`。确认其中的 MySQL、Redis、Milvus、模型服务和 LangSmith 配置后，在项目根目录按顺序运行： Windows PowerShell： ```powershell uv sync --project backend --locked pnpm --dir frontend install --frozen-lockfile .\scripts\init-databases.ps1 .\scripts\seed-knowledge.ps1 ``` macOS / Linux： ```bash 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`，因此首次初始化不需要再单独执行迁移、种子或阶段继承命令。 脚本默认连接名为 `zhibaotong-mysql` 的 MySQL 容器。如果你的容器名称不同，只需将数据库初始化命令替换为： ```powershell .\scripts\init-databases.ps1 -ContainerName 你的容器名 ``` macOS / Linux： ```bash ./scripts/init-databases.sh 你的容器名 ``` ## 启动 在项目根目录运行： Windows PowerShell： ```powershell .\scripts\dev.ps1 ``` macOS / Linux： ```bash ./scripts/dev.sh ``` 启动脚本会检查端口、启动前后端、等待三个服务全部就绪，并在退出时统一清理子进程。 `zbt-serve` 是跨平台后端主管进程，会分别启动 FastAPI 和退款 Worker。正常情况下不需要再执行 `zbt-refund-worker`。 运行地址： - H5： - 管理后台： - API 文档： 测试账号： - H5：`18800000001`，验证码 `147258` - 管理员：`admin / zaq1XSW@` - 运营人员：`operator01 / zaq1XSW@` - 审核人员：`reviewer01 / zaq1XSW@` ## 退款 Worker 退款涉及资金副作用，因此 Worker 默认启用 Redis 单实例锁，避免本地误启动多个主动执行者。`zbt-serve` 启动后会同时监管 API 和 Worker；任一进程异常退出时，主管进程会停止另一个进程，避免后端处于部分可用状态。 只有调试 Worker 时才单独运行： Windows PowerShell： ```powershell .\scripts\run-refund-worker.ps1 ``` macOS / Linux： ```bash ./scripts/run-refund-worker.sh ``` 如果已有 Worker 持有单实例锁，新进程会进入待命或退出，不能同时领取退款任务。管理端“退保工作台”可以查看 Worker 在线状态、退款尝试和失败原因。 ## LangSmith 在 `backend/.env` 中配置： ```dotenv LANGSMITH_TRACING=true LANGSMITH_API_KEY=你的密钥 LANGSMITH_PROJECT=智保通-第三阶段-智能保全与退款编排 LANGSMITH_OTEL_ENABLED=true ``` LangSmith 用于查看 Agent、Tool 和 LangGraph 执行链路；MySQL 中的 Run、工作流时间线和退款尝试仍是业务审计记录。 ## 真实模型评测 先启动整个项目，再在 `backend` 目录执行。Windows PowerShell 和 macOS 使用相同命令： ```bash 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 powershell -ExecutionPolicy Bypass -File .\scripts\test.ps1 ``` macOS / Linux： ```bash ./scripts/test.sh ``` 质量门禁检查后端测试、Ruff、mypy、前端类型和双端生产构建。真实模型评测单独执行，避免普通代码检查意外消耗模型额度。 ## 构建后端安装包 Windows PowerShell： ```powershell Set-Location backend uv build ``` macOS： ```bash cd backend uv build ``` 构建结果生成在 `backend/dist`，包括 wheel 和源码包。 ## 相关文档 - `docs/第三阶段新增业务与测试.md`：第三阶段新增功能和测试场景。 - `docs/智保通三阶段业务与ProcessOn技术.md`：三个阶段的业务与技术映射。 - `docs/项目启动与使用指南.md`：项目运行和使用说明。 所有 `scripts/*.ps1` 均提供同名的 `scripts/*.sh`，分别用于 Windows PowerShell 与 macOS/Linux。