项目一|账本精灵:投资记账 + 基金研究 Agent
2026个人开源 · 仓库可查 · MCP 端点可直接调用 本文件是主简历该项目的完整版。主简历只保留 6 条能力点,其余细节、边界与追问预案在此。 仓库:github.com/imoyao/fundmate
一、完整叙述(主简历已压缩,此处为原稿)
业务背景:把「记账数据查询」与「基金研究」做成可被任意 Agent 调用的工具服务。记账侧 9 个只读工具(收益 / 资产 / 持仓 / 净值 / 温度 / 自选 / 归因 / 基准 / 行为画像),研究侧自建 MCP 客户端(手写 Streamable HTTP)直连 2 家第三方数据服务共 9 个工具(且慢 3 + Wind 6);金融数值一律由确定性代码计算,模型只负责选工具与组织表达。
核心难点:
- 模型会改自己不该决定的东西——归属字段(家庭 / 账户)一旦走参数通道就可能越权。解法:参数不信任模型,归属字段不进参数,由鉴权上下文覆盖;用户私有数据强制用户级 Token,缺失即失败,不回退系统 Token。
- 多轮对话必然撑爆上下文——直接截断丢长程诉求(表现为反复追问同一件事),只做摘要丢最近细节。解法:分层记忆——滚动摘要(≤3000 字)+ 最近 3 轮原文 + 关键信息卡(≤800 字,整体替换、不进摘要);
turn_count > 6且len(messages) > 8双门槛触发,压缩失败降级到 12 条硬上限,先保证有界再谈压缩质量。 - 工具从 6 个扩到 9 个后开始选错——「组合总共赚了多少钱」被错选成资产总览,6 次采样错 4 次。根因不是模型退化,而是老工具描述缺排他边界句:新工具都写了「何时用 / 何时不用」,老工具没有,工具变多放大的正是旧描述的模糊性。
核心工作:
- 工具层:schema + 逐字段校验(类型 / 枚举 / 正则 / 数组递归),业务约束写进描述(出处强制标注、百分比与小数口径区分、取数失败标「未取到」不补全)——工具描述就是 prompt。
- 协议层:同一份工具定义两个方向——服务端用官方 SDK(
mcp.server.lowlevel)走 stdio 对外 9 个只读工具,与内置 agent loop 共用一份 schema;客户端手写 Streamable HTTP(不用官方 SDK,因为 SDK 2.0 只有 async,而本仓是全同步批处理),会话复用、失效重握、SSE 分流解析、8 类错误分类、按数据分级路由 Token、调用审计收敛一处。 - 护栏:越界提问在输入侧零模型调用拦截;输出侧过滤;重复步骤检测防原地打转;单会话轮次上限兜底。
- 可观测与评估:每次工具调用落库(入参 / 出参 / 耗时 / 错误码 / token,敏感参数脱敏),失败链路可按会话回放到具体一步;45 条回归集 + trace 回放。
项目成果:3569 次提交 / 358 个测试文件 / 401 个后端模块;9 个内置工具 + 9 个第三方数据工具(2 家数据服务,自建 Streamable HTTP 客户端);45 条回归集(22 条工具覆盖 + 8 条对抗 + 3 条跨工具混淆 + 12 条归因 / 基准 / 行为),已完成 24 条实跑基线且全绿;补齐边界句后 basic 组 20/20 通过。
边界:单机部署、未做并发压测;评估集只防回归,不代表效果上限;剩余 21 条用例因账号额度待补跑。
二、主简历压缩版(6 条)
用这 6 条替换主简历中的项目一:
- 工具契约:9 个只读工具的 schema + 逐字段校验(类型 / 枚举 / 正则 / 数组递归);业务约束写进描述(出处强制标注、百分比与小数口径区分、取数失败标「未取到」不补全)——工具描述就是 prompt。
- 不信任模型的两条红线:归属字段(家庭 / 账户)不进参数通道,由鉴权上下文覆盖;用户私有数据强制用户级 Token,缺失即失败、不回退系统 Token。
- 协议双向:同一份工具定义两个方向——服务端走 stdio 对外 9 个只读工具(与内置循环共用一份 schema);客户端手写 Streamable HTTP 接入 2 家数据服务 9 个工具,会话复用、失效重握、SSE 分流解析(防无 charset 被猜成 Latin-1 折断汉字)、8 类错误分类、数据分级 Token 路由、调用审计收敛一处;另经客户端配置接入基金数据工具面 28 个,用于晨星评级口径交叉核验。
- 上下文与记忆:分层记忆——滚动摘要(≤3000 字)+ 最近 3 轮原文 + 关键信息卡(≤800 字,整体替换、不进摘要);
turn_count > 6且len(messages) > 8双门槛触发,压缩失败降级到 12 条硬上限。先保证有界,再谈压缩质量——纯截断会表现为反复追问同一件事,纯摘要丢最近细节。 - 评估集与归因:45 条回归集(20 基础 / 2 跨工具 / 8 对抗 / 12 归因·基准·行为 / 3 混淆),24 条已实跑全绿。工具 6→9 后出现选错,根因不是模型退化而是老工具缺排他边界句,补齐「何时用 / 何时不用」后 basic 组 20/20——工具变多放大的正是旧描述的模糊性。
- 规模与可观测:3569 次提交 / 358 个测试文件 / 401 个后端模块;每次工具调用落库(入参 / 出参 / 耗时 / 错误码 / token,敏感参数脱敏),失败链路可按会话回放到具体一步。
三、面试追问预案
Q1:这 9 个工具为什么是只读?
金融场景里写操作的风险不对称——查错一个数字最多答错,改错一个数字会污染账本。所以工具集里没有写接口,写入仍然走原有的人工表单。模型在这个系统里的角色被限定为「取数与表达」,不是「操作」。
Q2:归属字段为什么不放参数里?
因为参数是模型写的。归属字段决定「查谁的数据」,一旦进参数,模型可以填一个不属于当前用户的家庭 ID。做法是把归属从参数里摘出来,由鉴权上下文注入;用户私有数据强制用户级 Token,取不到就失败,不回退到系统 Token——回退等于用高权限兜底,越权就从后门回来了。这个原则后来在知识库项目里复用了一次:可访问文档集合也是闭包注入、不进工具入参。
Q3:你说的三级压缩,三级分别压什么?6 / 8 / 12 怎么定的?
先纠正一下:严格说不是三级,是两层存储加一个兜底。滚动摘要把最旧轮次压成一段摘要、总长卡 3000 字;原文层保留最近 3 轮;再加一张关键信息卡存当前焦点,它整体替换、永远不压进摘要。
触发是双门槛:
turn_count > 6且len(messages) > 8,两个都过才压一次。为什么用「且」——只看轮次,短对话也会触发压缩、白花一次 LLM 调用;只看条数,长轮次短消息会一直不压。12 条不是第三级,是硬上限:压缩失败时保留最近 12 条原文兜底,未触发但原文还在涨时也按 12 截断。摘要层注入提示时会标注「更早轮次已压缩于此」。
这三个值都是经验取值,我没做过 A/B 或保真率测量,不能说是「从真实会话量出来的最优值」。先保证有界,再谈压缩质量——顺序反了会一直在调压缩算法,而上下文其实早就爆了。
Q4:怎么发现「工具变多导致选错」的?
评估集。有一条 "我的组合这些年一共赚了多少" 被错选成资产总览,跑 6 次错 4 次。第一反应是模型退化,但换回 6 工具的旧版本就对了。对比工具描述发现:新加的 3 个工具都写了「何时用 / 何时不用」,老工具没写。工具变多,放大的正是旧描述的模糊性。补齐后 basic 组 20/20。
Q5:45 条怎么分层的?
20 条基础(覆盖 9 个工具的正常路径)、2 条跨工具组合、8 条对抗(越界提问 4 / 参数缺失 2 / 幻觉诱导 1 / 恶意注入 1)、12 条归因·基准·行为画像、3 条跨工具混淆。对抗那 4 条越界断言的是「输入侧零模型调用就拦住」——不赌模型发挥。
Q6:为什么只跑了 24 条?
供应商账号的额度问题。跑批脚本按 token 预算做熔断,剩余 21 条要等额度解锁后补跑。这件事本身我没藏着——评估集的价值在能不能重复跑,不在一次跑完。
Q7:MCP 两个方向都做了?双向的代价是什么?
两个方向都做了,但传输不一样:服务端用官方 SDK(
mcp.server.lowlevel)走 stdio,对外 9 个只读工具,和内置 agent loop 共用一份TOOLS_METADATA;客户端是手写的 Streamable HTTP,接且慢和 Wind 两家 9 个工具。三处代价:① 协议版本演进快,客户端兼容要单独跟;② 会话复用与失效重握必须在统一一层做,否则内外两个出口各写一遍会漂移;③ 工具定义只有一份,但「谁能调」不一样——内部走登录态,外部走 Token,鉴权分支不能混进工具实现里。
Q7b:客户端为什么手写,不用官方 SDK?
算过账,不是不会用——服务端就在用官方 SDK,这是个反证。
① 异步错配:SDK 2.0 的
Client只有 async,我们是全同步 Flask 批处理(23 个模块用requests、5 处call_tool全同步)。硬换三条路——每个调用点asyncio.run会把夜跑从 111 次请求变成 333 次;或者 job 全链 async 化;或者写常驻 loop 桥约 100 行。前两条代价落在错误的层。 ② 能力增量是零:SDK 那套驻留连接、GET 流、断线续传、elicitation,我们一个都用不上;它只替得掉transport.py那 369 行,另外约 1130 行(8 类错误分类、mcp_call_logs审计、DataScope分级 Token 路由、Wind 的网关形状)原样保留。 ③ 协议世代还没到期:且慢2024-11-05、Wind2025-06-18都在 legacy 世代(有 initialize 握手);SDK 最新的2026-07-28属 modern,已取消 initialize 握手改discover。现在换只能开mode='legacy'兼容层——换掉的是维护方,不是能力。所以设了三条触发条件,满足任一即迁:任一上游支持 modern / SDK 出同步客户端 / 接第三家且它是 modern。迁移走常驻 loop 那条路。
判据是分层的:契约层测试一行不改仍全绿(registry / credentials / errors / call_log / Wind 的
map_args·extract),传输层那 21 个用例随实现整体重写(SSE 解析、握手、会话复用、400 双语义)。说「全部测试一行不改」是吹,握手和会话复用变成 SDK 内部行为后那些报文断言无从谈起。
Q8:这个项目证明什么?
它是四个项目里唯一可查的。其他三个是「我做了,你没法验证」,这个是「你现在就能打开看」。所以它承担的不是业务复杂度,是工程完整度与可验证性——358 个测试文件、26 个 CI 工作流、45 条评估集,这三样在企业项目里通常因为工期做不了。
四、主动承认的边界(不要等被问)
| 边界 | 说明 |
|---|---|
| 单机部署 | 未做并发压测,没有多实例与负载均衡 |
| 评估集只防回归 | 45 条是回归护栏,不代表能力上限,也不构成效果 benchmark |
| 21 条待补跑 | 账号额度限制,非实现缺陷 |
| 单用户 | 就是我自己在用(153 持仓 / 1924 流水 / 107 快照),业务复杂度低 |
| 提交密度 | 3569 次提交集中在 2026-05 至 2026-10,五个月。原因是 AI 辅助开发 + 大量小步提交 + 单一开发者,不是历史造假 |
| MCP 服务端走 stdio,无网络鉴权 | 有意设计:鉴权靠 OS 用户边界,family_id 只读环境变量、客户端传值被覆盖。换成 HTTP 出口要补 JWT 与 Origin 校验,属另一张卡 |
| MCP 客户端手写,未迁官方 SDK | 触发条件已写死在 docs/dev/mcp-integration.md §13(任一上游支持 modern / SDK 出同步客户端 / 接第三家是 modern)。是「条件没到」,不是「成本太高懒得做」 |
五、数据出处(可当场核对)
| 数字 | 出处 |
|---|---|
| 3569 次提交 | git rev-list --count HEAD |
| 358 个测试文件 | find . -name "test_*.py" -o -name "*.spec.ts" 计数 |
| 401 个后端模块 | find backend -name "*.py" 去重计数 |
| 9 个内置工具 | backend/app/services/ai_recognizer/tools.py 的 TOOLS_METADATA |
| 9 个第三方工具(2 家) | backend/app/services/mcp/providers/——且慢 3 + Wind 6,provider_names() 实跑可列 |
| 28 个第三方工具面 | 不在仓库代码里:~/.workbuddy/mcp.json 的 seefundgo(fundfof.com/mcp),晨星评级口径核验走它 |
| 45 条评估集 | backend/tests/agent_eval/cases.yaml |
| 24 条实跑 | agent_eval.py --json 输出报告 |
