FinScope：用户画像驱动的金融需求分析 Agent

面向财经业务的金融助手 Agent：确认式跨会话 Memory → MCP 工具链 → 确定性收支计算 → 硬约束过滤与规则排序 → 带来源的条款问答。

把「用户确认的跨会话画像、确定性收支计算、模拟产品约束匹配、带来源的条款检索」串成一条可复现的 Agent 链路：资料先确认再写入，金额由 Decimal 程序计算，产品先过硬约束再排序，条款回答必须逐字回指来源。画像的修改、删除与跨用户隔离全部由业务服务在 SQLite 写事务内控制——模型既不参与数值计算，也不能自行确认资料或指定登录身份。

单机可复现部署，随附完整合成数据集（20 个用户画像 / 9 条模拟产品 / 54 条条款），安装后无需任何外部服务即可跑通全链路。本地 Windows / Python 3.12 通过 100 项测试，20 组独立模拟跨会话序列 20 / 20 通过；跨平台结果以顶部 CI 链接为准。

先看结论

Related MCP server: utopia-mcp

系统架构

flowchart LR
    U[网页 / CLI] --> S[服务端可信身份]
    S --> P[资料提议]
    P -->|版本 + 哈希三方校验| D[(SQLite 已确认画像)]
    S --> A[分析编排]
    D --> T[MCP 工具网关]
    A --> T
    T --> C[Decimal 收支计算]
    T --> M[硬约束过滤 + 规则排序]
    T --> R[生效条款检索]
    C --> O[带版本与工具轨迹的结果]
    M --> O
    R --> O
    R --> Q[条款问答与引用核验]

分层职责、确认事务、删除语义与工具约束见架构与数据边界。

快速开始

需要 Python 3.11 或 3.12。首次安装会从包索引下载依赖。

Windows PowerShell：

git clone https://github.com/fangyunok/finscope-agent.git
cd finscope-agent
python -m venv .venv
.\.venv\Scripts\python.exe -m pip install -r requirements.lock.txt
.\.venv\Scripts\python.exe -m pip install -e ".[dev]"
.\.venv\Scripts\python.exe -m finscope doctor --mode fixture
.\.venv\Scripts\python.exe -m finscope serve --mode fixture

Linux / macOS：

git clone https://github.com/fangyunok/finscope-agent.git
cd finscope-agent
python3 -m venv .venv
.venv/bin/python -m pip install -r requirements.lock.txt
.venv/bin/python -m pip install -e '.[dev]'
.venv/bin/python -m finscope doctor --mode fixture
.venv/bin/python -m finscope serve --mode fixture

访问 http://127.0.0.1:7862 并选择演示用户。登录使用内置演示账号选择器签发 HMAC 会话 Cookie，服务默认只监听回环地址；面向多用户部署时把登录端点替换为外部身份提供方即可，会话校验与业务授权逻辑保持不变。

数据库默认保存到当前工作目录 runs/finscope.sqlite，可用 --db 或进程环境变量 FINSCOPE_DB_PATH 指定路径。种子导入只写入用户目录，不会自动确认任何画像；界面中的示例资料仍需核对后手动确认。

演示与检查

.\.venv\Scripts\python.exe -m finscope demo --db runs/demo.sqlite --mode fixture
.\.venv\Scripts\python.exe -m finscope evaluate --output runs/evaluation.json
.\.venv\Scripts\python.exe -m unittest discover -s tests -v
.\.venv\Scripts\python.exe -m pip check
.\.venv\Scripts\python.exe -m build --wheel

demo 覆盖画像提议与确认、通过 MCP 分析、重建服务实例后读取资料、确认期限变更以及删除验证。evaluate 在独立临时数据库中执行 20 组预先标注的模拟跨会话序列，逐案例记录步骤与标签满足情况，并统计工具调用、模型调用与合成数据标记；退出码非零表示某项验收不满足。

接入 Qwen

.env.example 是配置参考；应用只读取进程环境变量，不会自动加载 .env。密钥与个人数据库请勿提交。

$env:FINSCOPE_QWEN_BASE = "http://127.0.0.1:11435/v1"
$env:FINSCOPE_QWEN_MODEL = "qwen3:4b-instruct"
.\.venv\Scripts\python.exe -m finscope doctor --mode qwen
.\.venv\Scripts\python.exe -m finscope serve --mode qwen

地址需包含 /v1。doctor 会检查模型目录与目标模型是否就绪。本地服务可用可选变量 FINSCOPE_QWEN_KEY 提供密钥；其他 OpenAI 兼容服务改用 FINSCOPE_API_BASE / _MODEL / _KEY 并选择 --mode api。

模型只承担两件事：从明确文本中抽取画像字段补丁、依据给定条款生成带引用的回答。确认画像、指定登录身份、改动计算公式、调整排序权重都不在模型可调用范围内——这些能力只存在于服务端接口，而确认接口不作为模型工具暴露。

设计边界

以下是明确的设计取舍，不是待补的缺口：

• 模型权限被显式收窄。抽取与问答之外的动作一律不通向模型：计算由 calculations.py 的 Decimal 运算完成，排序由 matching.py 的固定规则完成，画像写入必须先经人工确认接口。因此模型输出中的任何数值都不会进入结果。

• 风险偏好只接受显式确认。收藏、排除、点击与聊天语气只作为兴趣信号记录，代码中这些行为与风险字段的更新路径是分开的，互不触发。

• 产品目录是合成数据。9 条模拟产品与 54 条条款由本仓库维护，不含收益率、不接入任何资金操作。替换 src/finscope/data/catalog.json 并保持字段结构，即可迁移到自有条款库。

• 引用核验保证的是可追溯性。逐字校验保证回答片段与被引条款一致、引用 ID 合法，因此结果状态为 pending_review（可进入人工核查）。

• 删除作用于应用数据库。删除会清理该用户的画像、字段来源、历史、提议、反馈与个人运行记录，并递增记忆代次。

更完整的验证范围见项目状态与验证范围，评测口径见评测说明，后续演进见演进路线。

Go 计算侧车

确定性计算与检索热路径（金额校验、现金流目标、产品硬约束匹配与规则打分、条款关键词检索）另有一套语义对等的 Go 实现，位于 go/ 目录，用 math/big.Rat 精确有理数运算与 Python Decimal 语义对齐，通过 go/core/matching_test.go 与 go/core/search_test.go 的黄金对拍测试锁定与 Python oracle 逐字段一致。三个无状态工具（calculate_financial_goal / match_products / search_financial_terms）另以 mark3labs/mcp-go 注册成真正的 stdio MCP Server（go/mcpserver），可被任意 MCP Host 接入。这一层只做纯计算与检索，模型抽取、有状态记忆工具、SQLite 事务与乐观锁仍由 Python 服务负责。详见 Go 计算侧车。

工程资料

依赖版本锁定在 requirements.lock.txt。CI 覆盖 Ubuntu / Windows 与 Python 3.11 / 3.12，并额外检查 wheel 在源码目录之外安装、demo 执行与启动 HTTP 服务。代码与模拟数据采用 MIT License。