住房公积金问数智能体 — 系统详细设计文档

文档版本：V1.6 · 基于文档：PRD V1.0 / 产品功能清单（开发排期版）/ 技术架构定稿 / 页面原型文字说明
技术底座：Hermes 0.19.0 + Nuxt3(Vue3) + FastAPI + 文件化存储(MD/JSON) + DeepSeek API

1 文档概述

修订记录

1.1 项目背景

公积金日常业务中，业务人员需要翻阅大量统计报表、政策文件获取缴存、提取、贷款等指标数据；跨报表汇总、同比对比、多文件口径冲突人工处理效率低。同时，公积金数据标准化建设要求日益严格，新版《住房公积金基础数据标准》和新版《住房公积金指标数据标准》相继实施，要求各地公积金信息系统在数据分类、编码规则、指标口径、计算方法等方面实现统一规范。依托Hermes智能体搭建本地智能文档问数平台，实现自然语言问答、指标自动运算、数据溯源、简报一键生成、权限管控与操作审计，同时满足数据标准合规要求，支撑数据治理与跨系统互通。

1.2 产品目标

1. 支持业务人员通过自然语言查询本地入库公积金文档内指标；
2. 自动跨文档汇总、近两年同期同比分析，指标冲突区分多版本来源；
3. 分级权限隔离，不同岗位仅可访问管辖范围内单位、个人及文档；
4. 领导支持一键生成全市概况简报 PDF，普通人员支持导出带水印 Excel；
5. 全操作日志留存，满足监管审计要求；
6. 轻量化部署：无数据库、无向量库、基于 MD/JSON 文件存储，Mac 单机可完整运行；
7. 数据标准合规：全流程遵循新版《住房公积金基础数据标准》和《住房公积金指标数据标准》。

1.3 受众角色

1.4 核心约束

1. 系统仅读取本地入库文档，禁止访问互联网获取业务数据；
2. 知识库原始文件不上传至 DeepSeek API，仅传输问答必要片段；
3. 所有导出文件自动添加操作人员账号 + 时间水印；
4. 用户无法手动删除会话记录，会话永久留存；
5. 指标运算须遵循新版《住房公积金指标数据标准》，禁止智能体自行推断；
6. 无任何数据库依赖：全文件化存储。

2 系统总体架构

2.1 五层标准架构

从上至下：前端展示层 → API 网关业务层 → Hermes 智能体核心层 → 文件服务层 → 本地文件存储层

2.2 部署拓扑

2.3 技术栈清单

3 智能体引擎调用设计

3.1 架构边界

Hermes 0.19.0 Agent 是系统的智能编排核心，负责所有需要多步骤推理、工具调用、LLM 交互的复杂业务流程。系统按功能分为对接 Hermes与不经过 Hermes两个域：

3.2 需对接 Hermes Agent 的功能清单

3.3 不经过 Hermes Agent 的功能清单

3.4 Hermes 五大自定义工具定义

3.5 调用链路说明

AI 问答（完整链路，Hermes 编排 8 步）：

简报导出 / Excel 导出（单工具调用链路）：

3.6 Hermes 调用原则

1. 智能问答必走 Hermes：所有涉及自然语言理解、多步编排、LLM 调用的场景必须通过 Hermes Agent 编排，FastAPI 不得直接调用 DeepSeek API。
2. 工具调用 vs 内联编排：可复用的原子操作注册为自定义工具（文档检索/指标计算/PDF 生成/Excel 导出/反馈记录）；仅当前业务流程特有的逻辑（维度解析、权限校验）在 Agent 内联编排中实现。
3. Hermes 不处理纯 CRUD：文件管理、配置管理、日志查询等纯读写操作由 FastAPI 直接处理，不经过 Hermes，避免不必要的 Agent 调度开销。
4. 审计日志由 FastAPI 统一埋点：Hermes 工具内部不独立写审计日志，统一由 FastAPI 在请求入口/出口埋点，保证审计数据来源唯一。

4 模块详细设计

4.1 登录鉴权模块

4.1.1 数据结构

config/users.json

[
  {
    "user_id": "zhang_san",
    "username": "张三",
    "password_hash": "<sha256>",
    "role": "科员",
    "status": "active",
    "data_scope": ["江汉区"],
    "theme": "light"
  },
  {
    "user_id": "wx_oT9abc...",
    "username": "微信用户_oT9abc",
    "wechat_openid": "oT9abc...",
    "password_hash": null,
    "role": "游客",
    "status": "active",
    "data_scope": [],
    "theme": "light"
  }
]

字段说明：wechat_openid 为微信扫码登录用户的唯一标识；password_hash 为微信用户此项为 null（无需密码）。status 为用户状态，"active" 为正常，"banned" 为封禁，封禁用户登录时提示「你的账号暂时被封禁了，可以联系系统管理员解封」。

初始预置管理员：系统首次部署时 config/users.json 中必须预置一个系统管理员账号，因为系统无注册页面和初始化向导，只能通过文件配置创建用户。若无管理员账号则无人可登录系统。推荐默认值：

{
  "user_id": "admin",
  "username": "系统管理员",
  "password_hash": "<sha256_of_admin123>",
  "wechat_openid": null,
  "role": "系统管理员",
  "status": "active",
  "data_scope": ["全市"],
  "theme": "light"
}

默认密码 admin123，仅限本地 127.0.0.1 访问生效；管理员首次登录后应通过编辑 JSON 修改密码或新增其他用户。
微信新用户自动注册：使用微信扫码登录时，若系统发现 wechat_openid 未在 users.json 中存在，则自动追加一条新用户记录，角色默认为「游客」（见下方角色配置），无需管理员预先创建。

config/role_config.json

{
  "游客":       { "can_export_excel": false, "can_generate_pdf": false, "daily_export_limit": 0 },
  "科员":       { "can_export_excel": true,  "can_generate_pdf": false, "daily_export_limit": 10 },
  "科室领导":   { "can_export_excel": true,  "can_generate_pdf": true,  "daily_export_limit": 20 },
  "中心领导":   { "can_export_excel": true,  "can_generate_pdf": true,  "daily_export_limit": 30 },
  "监管人员":   { "can_export_excel": false, "can_generate_pdf": false, "daily_export_limit": 0 },
  "系统管理员": { "can_export_excel": false, "can_generate_pdf": false, "daily_export_limit": 0 }
}

游客角色说明：微信扫码自动注册的新用户默认分配「游客」角色。游客仅有 AI 智能问答的只读权限，不可导出、不可生成简报、不可访问后台与知识库。管理员可在 users.json 中将其 role 升级为正式角色（如科员）并配置 data_scope。

4.1.2 登录流程

4.1.3 微信扫码登录与自动注册

• 前端展示微信二维码弹窗；
• 用户使用微信扫一扫完成身份认证；
• 系统通过微信 OAuth 回调获取 wechat_openid，在 config/users.json 中查找是否已存在；
  • 已存在 → 加载该用户信息与权限，完成登录；
  • 不存在 → 自动追加新用户记录：
    • user_id = wx_{openid前12位}
    • username = 微信用户_{openid前6位}
    • wechat_openid = 微信返回的 openid
    • password_hash = null
    • role = 游客
    • data_scope = []（空，无管辖范围）
    • theme = light
• 写入成功后执行登录，返回 token；
• 对接微信开放平台 OAuth 接口。

4.1.4 接口定义

4.2 AI智能问答核心模块

4.2.1 整体流程

4.2.2 维度智能解析规则

维度不存在处理：若用户要求的维度在知识库中不存在，回答顶部展示黄色提示条「当前知识库中暂无该维度的统计口径」，下方列出已支持的常用维度列表（可点击选中重新提问），右侧附带【申请统计口径】按钮。

4.2.3 用户问答缓存（qa_cache）

• 文件路径：sessions/qa_cache_{userid}.md
• 写入时机：每次有效问答产生结果后。
• 缓存内容：指标名称、各维度值（时间/周期/机构/分组）、数据结果、来源文档。
• 命中规则：新提问解析出指标名称和维度值后，优先在该文件中精确匹配。若命中，直接返回缓存结果并标注「来自历史问答记录」，无需重新执行文档检索与运算。
• 更新策略：追加记录并去重更新（相同指标+维度组合以最新数据为准）。

4.2.4 Hermes 五大自定义工具

4.2.5 权限后置校验

4.2.6 指标冲突处理

当多份文档同一指标数值不一致时：

4.2.7 结果溯源与数据层级

每条返回结果须附带：

• 来源文档名称
• 标准指标编码
• 数据层级（基础数据 / 明细数据 / 汇总数据 / 分析报告）
• 统计口径说明 + 口径版本
• 权限状态（有权限 / 无权限）

数据信任链优先级：基础数据标准 → 业务明细数据 → 统计汇总数据 → 分析报告

4.2.8 空结果标准化答复

无匹配数据时固定回复：「未检索到相关公开数据」

4.2.9 会话管理

• 会话文件路径：sessions/{userid}/{session_id}.json
• 每轮对话自动保存完整会话记录（提问、思考链路、返回结果）
• 前端不提供删除按钮
• 用户可查看历史会话列表，回溯历史问答

4.2.10 智能体链路可视化

• 对话右侧折叠面板
• Vue-Flow 流程图展示执行链路：文档检索 → 指标读取 → 运算分析 → 结果输出
• 用于演示与问题排查

4.2.11 接口定义

4.3 知识库文件管理模块

4.3.1 文件上传与解析流程

数据标准映射说明（V1.0）：文档解析流程中，数据项到《基础数据标准》分类的映射、指标到《指标数据标准》的提取，采用规则引擎+关键词表实现（基于住建部标准分类编码表做正则匹配和关键词命中），不调用 DeepSeek API。无法自动映射的数据项标记为「待标注」，提示管理员手工处理。V1.0 暂不使用 LLM 做语义映射，避免文件上传时产生大量 token 消耗。

4.3.2 文件存储目录结构

/knowledge/{file_id}/
  ├── original.{pdf|docx|xlsx}      ← 原始文件
  ├── content.md                     ← 清洗后纯文本
  ├── meta.json                      ← 元数据（权限、标签、版本、标准覆盖度）
  └── indicators.index.json           ← 结构化指标体系

4.3.3 meta.json 结构

{
  "file_id": "uuid",
  "file_name": "2025年统计年报.pdf",
  "version": "v1.0",
  "invalid": false,
  "tags": ["统计报表"],
  "allow_roles": ["科员", "科室领导", "中心领导", "监管人员"],
  "upload_time": "2025-06-01T10:00:00",
  "data_standard": {
    "base_data_standard": {
      "categories_mapped": ["个人", "单位", "业务"],
      "data_elements_mapped": 42,
      "data_items_mapped": 128,
      "pending_mark": ["结算信息"]
    },
    "indicator_standard": {
      "indicators_mapped": 15,
      "coverage_rate": "85%",
      "pending_mark": []
    }
  }
}

4.3.4 indicators.index.json 结构

[
  {
    "indicator_code": "I-BIZ-001",
    "indicator_name": "年度缴存总额",
    "category": "业务运行类",
    "calculation_method": "Σ 当年月度缴存额",
    "statistical_scope": "全市正常缴存单位",
    "value_standard": "元（精确到0.01）",
    "data_level": "汇总数据",
    "version": "v2025",
    "dimensions": {
      "time": ["2025"],
      "period": ["本期"],
      "region": ["全市"],
      "business_type": ["正常缴存"],
      "channel": ["全部渠道"]
    },
    "value": 12560000000.00,
    "unit": "元",
    "notes": "含单位配缴、个人缴存、财政配缴",
    "source_document": "2025年统计年报.pdf",
    "standard_citation": "《住房公积金指标数据标准》第X条"
  }
]

4.3.5 文件版本管理

• 上传新版文件：新建目录，旧文件 meta.json 标记 invalid: true
• 系统检索时自动忽略标记为 invalid 的文件
• 支持保留历史版本完整可追溯

4.3.6 文件标签类型

4.3.7 接口定义

4.4 简报与导出模块

4.4.1 一键生成全市概况简报 PDF

• 仅科室领导、中心领导可见按钮
• 一键汇总全市缴存核心指标
• 自动嵌入水印：操作人员账号 + 导出时间
• 仅支持 PDF 格式输出
• 本期不开放自定义指标模板

4.4.2 Excel 数据导出

• 有权限岗位可将问答结果导出 Excel
• 导出前校验单日导出次数（读取 runtime/export_count.json）
• 文件内置账号 + 时间水印
• 水印平铺页面，不可清除

4.4.3 导出风控

• runtime/export_count.json 记录每次导出
• 管理员在 role_config.json 配置各岗位单日上限
• 超限时弹出友好提示，禁止导出

4.4.4 接口定义

4.5 后台管理模块（仅管理员）

4.5.1 角色权限配置

页面路径：后台管理 → 权限配置

• 角色选择下拉框（科员/科室领导/中心领导/监管人员/系统管理员）
• 配置项：是否允许导出 Excel、是否允许生成 PDF 简报、单日最大导出次数
• 保存后写入 config/role_config.json

4.5.2 审计日志管理

页面路径：后台管理 → 审计日志

• 筛选条件：起止时间、操作人员
• 日志列表展示：时间、账号、操作类型、简要内容
• 操作类型：登录、问答查询、文件检索、文件导出

日志文件路径：logs/audit/{date}/{timestamp}_{user_id}_{action_type}.json

{
  "timestamp": "2025-06-01T10:30:00",
  "user_id": "zhang_san",
  "role": "科员",
  "action_type": "问答查询",
  "action_detail": "查询2025年缴存总额",
  "session_id": "session_uuid",
  "result_count": 3
}

4.5.3 用户反馈管理

页面路径：后台管理 → 用户反馈

• 列表展示：反馈时间、操作人、反馈内容、关联会话 ID
• 支持点击跳转查看对应会话详情

文件路径：feedback/{timestamp}_{user_id}.json

4.5.4 权限申请审批管理

页面路径：后台管理 → 权限申请审批

• 列表字段：申请时间、申请人账号及角色、目标文档名称、数据指标、申请理由、状态
• 状态流转：待审批 → 通过 / 驳回（驳回须填写原因）
• 审批通过后：自动更新该用户对目标文档的权限配置（写入相关角色的 allow_roles）

文件路径：config/permission_requests.json

4.5.5 统计口径申请管理

页面路径：后台管理 → 统计口径申请

• 列表字段：申请时间、申请人、指标名称、不支持的维度、已支持常用维度、用户需求描述、状态
• 状态流转：待评估 → 已评估（填写评估意见）

文件路径：config/dimension_requests.json

4.6 数据标准管理模块（仅管理员）

4.6.1 基础数据标准配置

页面路径：数据标准管理 → 基础数据标准配置

展示内容：

• 新版《住房公积金基础数据标准》概况
  • 8 大类一级分类：个人 / 单位 / 房屋 / 业务 / 管理机构 / 渠道 / 财务 / 结算
  • 30 个二级分类
  • 195 个公共数据元
  • 516 个分类数据项
• 知识库覆盖度统计图（已映射 / 待标注 / 未覆盖）
• 标准分类编码表（可展开查看详情）

管理员可操作：编辑本地扩展映射规则

预置标准：住建部标准数据分类编码表

4.6.2 标准化指标口径管理

页面路径：数据标准管理 → 指标口径管理

指标体系分类：

每条指标包含：标准指标编码、指标名称、计算方法、统计范围、取值标准、数据来源层级、口径版本

维度配置：支持按地域 / 业务类型 / 时间 / 渠道四个维度分别配置

口径差异管理：

• 自动列出同一标准指标在不同文档中的口径差异
• 关联至指标数据标准的具体条款
• 管理员可设置「优先口径」用于冲突自动消解

4.6.3 数据标准合规校验

页面路径：数据标准管理 → 合规校验

• 一键校验按钮，扫描全部文档的 indicators.index.json 和 meta.json
• 校验项：
  • 指标编码是否符合新版《住房公积金指标数据标准》编码规则
  • 数据分类是否映射至基础数据标准分类体系
  • 指标口径定义是否完整且版本可追溯
• 校验结果列表：文档路径、不合规项描述、违反的标准条款、建议修正方案
• 支持导出合规校验报告 PDF（含双标准覆盖度）

4.7 公共基础能力

4.7.1 全操作审计埋点

文件存储：logs/audit/{date}/{timestamp}_{user_id}_{action_type}.json

4.7.2 多终端自适应适配

• 最小触控区域 ≥ 44×44 px
• 所有交互组件触摸友好

5 存储设计

5.1 完整文件目录结构

/project_root/
│
├── config/                           # 系统配置
│   ├── users.json                    # 用户账号
│   ├── role_config.json              # 角色权限配置
│   ├── permission_requests.json      # 权限申请记录
│   ├── dimension_requests.json       # 统计口径申请记录
│   └── data_standard/                # 数据标准配置
│       ├── base_data_categories.json # 基础数据标准分类编码表
│       └── indicator_standards.json  # 指标体系配置
│
├── knowledge/                        # 业务知识库
│   └── {file_id}/
│       ├── original.{pdf|docx|xlsx}  # 原始上传文件
│       ├── content.md                # 清洗后纯文本
│       ├── meta.json                 # 元数据（权限/标签/版本/标准覆盖度）
│       └── indicators.index.json     # 结构化指标体系
│
├── sessions/                         # 用户会话记录
│   ├── {user_id}/
│   │   └── {session_id}.json         # 单次会话完整记录
│   └── qa_cache_{user_id}.md         # 用户问答缓存
│
├── logs/
│   └── audit/                        # 审计日志
│       └── {date}/
│           └── {timestamp}_{user_id}_{action_type}.json
│
├── feedback/                         # 用户反馈
│   └── {timestamp}_{user_id}.json
│
├── runtime/                          # 运行时数据
│   ├── export_count.json             # 导出次数计数
│   └── temp/                         # 临时文件
│
└── export_files/                     # 导出的 PDF/Excel 文件
    └── {export_id}.{pdf|xlsx}

5.2 存储规范总结

6 接口设计

6.1 接口总览

6.2 统一响应格式

{
  "code": 0,
  "message": "success",
  "data": { ... },
  "timestamp": "2025-06-01T10:00:00Z"
}

错误时：

{
  "code": 40001,
  "message": "账号或密码错误",
  "data": null,
  "timestamp": "2025-06-01T10:00:00Z"
}

7 权限设计

7.1 三级权限体系

7.2 权限矩阵

8 核心数据流设计

8.1 AI 问答数据流（完整闭环）

8.2 文件上传数据流

8.3 导出数据流

9 前端页面与组件设计

9.1 页面清单

9.2 通用布局规范

9.3 通用 UI 规范

9.4 弹窗清单

10 部署架构

10.1 运行环境

10.2 后端依赖清单

所有依赖统一写入 requirements.txt，一条命令安装：

pip install -r requirements.txt

注意：Hermes 不是独立的服务进程，不需要单独下载、启动或维护。它作为 Python 包安装在虚拟环境中，由 FastAPI 后端进程在启动时初始化并常驻内存。因此在目标笔记本上只需要 pip install 即可。

10.3 启动流程

首次启动说明：系统首次启动时 config/users.json 仅包含预设的 admin 管理员账号。部署人员使用默认密码 admin123 登录后，应直接编辑 config/users.json 修改管理员密码并新增其他业务用户。正式环境迁移时可增加「用户管理」页面和「首次登录强制改密」功能。

10.4 可迁移性

当前文件化架构为原型版本，业务逻辑无需改动，后期可平滑改造接入数据库部署在内网服务器。具体迁移路径：

• 文件存储 → 数据库（SQLite / PostgreSQL）
• 文件检索 → 向量库（可选）
• 配置文件 → 数据库表
• 审计日志 → 日志汇聚服务

10.5 跨机器迁移说明

核心原则：Hermes 0.19.0 只是框架引擎，系统的业务行为（五大自定义工具、系统 Prompt 规则、维度解析逻辑、API 适配）全部写在项目后端源代码中。因此跨机器部署时，必须完整拷贝整个项目目录（含后端代码），而非仅安装 Hermes 包。

正确方式：

# ① 从原笔记本拷贝完整项目（含后端业务代码）
scp -r user@old-mac:/path/to/project /path/to/project

# ② 安装全部依赖（Hermes 框架 + 项目自身代码一起装）
cd /path/to/project/backend
python3 -m venv venv
source venv/bin/activate
pip install -r requirements.txt
# ↑ 安装的 hermes-agent 只是引擎框架
# ↑ 你的自定义工具和业务规则在 backend/tools/ 和 backend/agent/ 中

# ③ 配置 DeepSeek Key，启动
export DEEPSEEK_API_KEY="sk-xxxx"
python main.py

拷贝最小清单：

效果保证：由于全部配置（用户、角色、权限、知识库、数据标准）均为文件化存储，且 Hermes 的业务逻辑由后端代码完整定义，只要上述目录全部拷贝、pip install 安装相同版本的依赖，新笔记本的行为与本机完全一致。

11 约束与备忘

11.1 架构不可变更约束

1. 永远本地 Hermes 调度 + 远端 DeepSeek 推理
2. 永远文件化存储，无数据库（原型阶段）
3. 永远三级权限前置拦截 + 后置校验
4. 永远结果溯源、冲突并列、同比带来源
5. 永远全链路审计文件落地
6. 前端固定 Nuxt3 + NaiveUI 高级政务酷炫风格

说明：以上 6 条是 V1.0 原型阶段的架构底线——不是技术上不能改，而是设计上不允许改。目的是防止开发过程中偏离"轻量原型"定位：

1. 本地 Hermes + 远端 DeepSeek → 防止引入本地大模型增加部署成本
2. 文件化存储，无数据库 → 防止引入 MySQL/Redis/向量库增加运维负担
3. 三级权限拦截 + 后置校验 → 防止权限设计被简化为单一登录校验
4. 结果溯源、冲突并列 → 防止 Agent 合成答案时丢掉数据来源引用
5. 全链路审计文件落地 → 防止审计变成可选功能
6. 前端 Nuxt3 + NaiveUI 固定 → 防止引入 React/Element Plus 等技术栈混用

11.2 开发优先级说明

11.3 后续迭代备选需求

1. 支持存量文件批量导入（P3）
2. 领导简报自定义指标模板（后续）
3. 增加外网公众号接入模块（后续）

11.4 已知风险与限制

1. 系统依赖 DeepSeek API 网络连通，断网状态下无法完成智能问答
2. 文件数量过大时（>500 份），本地文件遍历检索性能下降
3. 全部存储为文件，不支持复杂多条件日志批量筛选（原型阶段可接受）

12 Token 经济设计

12.1 大模型调用点总览

系统共 2 个环节调用 DeepSeek API 产生 token 消耗：

其余所有环节（登录、文档检索、指标计算、权限校验、文件解析、导出生成、审计日志、缓存查询）均在大模型调用链路之外，不产生 token 消耗。

12.2 单次问答 Token 消耗模型

12.3 各场景 Token 消耗估算

12.4 系统 Prompt 固定消耗

每次 T2（合规回答生成）均需携带系统 Prompt（固定业务规则），这是 token 消耗的固定底数：

优化建议：系统 Prompt 应持续精简，去除冗余描述；长文本规则可转换为结构化的 JSON 约束注入，减少自然语言描述的 token 占用。

12.5 缓存对 Token 消耗的削减

典型场景的缓存命中率预期：

• 日报型查询（每天查同样指标） → 缓存命中率 >70%
• 探索型分析（一指标多维度组合） → 缓存命中率 <30%
• 常规业务查询 → 缓存命中率 ~50%

12.6 Token 消耗优化策略

12.7 设计约束

1. 禁止非必要的 LLM 调用：所有可通过本地规则、关键词匹配、JSON 查询完成的操作（权限校验、指标计算、文件解析映射、文档检索）均不得调用 DeepSeek API。
2. 知识库原始文件永不外传：仅传递与提问直接相关的文档片段至 DeepSeek API，遵守「最少传输」原则。
3. 缓存优先：qa_cache 是削减 token 消耗的第一道防线，每次有效问答后必须写入。
4. 系统 Prompt 版本管理：系统 Prompt 的每次变更应记录版本号，便于追踪 token 消耗变化。

住房公积金问数智能体 · 系统详细设计文档 V1.6
技术底座：Hermes 0.19.0 + Nuxt3(Vue3) + FastAPI + 文件化存储(MD/JSON) + DeepSeek API