实战：用 TaoToken 搭建个人财务记账 Agent Harness 的配置文件骨架

1. 为什么我要把记账 Agent 拆成 Harness 骨架个人财务记账这件事痛点从来不是「不会写代码」而是「每次想认真记账最后都变成手动填表」。我试过用表格记了三个月结果微信、支付宝、银行卡三份账单格式完全不一样月底对账时字段名对不上分类全靠脑子记最后不了了之。后来我把思路换了一下与其做一个「大而全的记账系统」不如先做一个Agent Harness 骨架——也就是把模型调用通道、配置文件、任务路由这三件事先固定下来让账单解析、分类记账、月度汇总这三类任务能跑通剩下的功能再慢慢往里加。Harness 在这里不是某个具体框架的名字而是指「把 Agent 的运行环境、配置、工具入口统一收口」的那层壳。这篇要交付的东西很具体一份config.toml、一份settings.json加上一次端到端验证动作。你照着填就能在私有环境里复现一个最小可用的记账 Agent。适合谁有基础 Python 能力、想自己掌控财务数据、又不想从零造轮子的开发者。核心检索词就三个Agent、Harness、个人财务记账。我踩过的坑是一开始把 API Key 硬编码在脚本里换模型时改了七八个文件。后来统一走一个 Key/API 通道配置文件只留一份问题就消失了。下面按这个思路展开。2. TaoToken 前置统一 Key 与 API 通道2.1 为什么记账 Agent 需要一个统一通道记账 Agent 的模型调用有三个特点调用频繁每笔账单解析都要过一次模型、任务类型固定解析、分类、汇总、对稳定性敏感月底汇总跑一半失败很烦。如果每个任务各接一个模型供应商Key 管理、限流、计费都会变成负担。统一通道的价值在于你只需要维护一个 API Key模型切换、额度查看、调用日志都在一个地方。对私有部署来说这意味着配置文件里只出现一个base_url和一个api_key迁移环境时改两行就行。2.2 拿到 Key 并确认通道可用进入控制台创建 API Key建议按用途命名比如bill-agent-dev方便后续区分开发和生产。创建后你会得到一串以sk-开头的密钥只显示一次先复制到安全的地方。注意不要把 Key 提交到 Git。配置文件里用占位符真实值放环境变量或本地.env。通道地址统一用https://taotoken.net/api不要带任何多余路径。模型名按你实际开通的填比如gpt-4o-mini这类通用对话模型就够记账场景用。2.3 三类任务与模型的对应关系任务类型输入输出建议模型能力账单解析原始 CSV/文本行结构化 JSON指令遵循强、JSON 稳定分类记账交易备注对手方分类名置信度语义理解好、成本低月度汇总结构化账单列表汇总文本统计长上下文、数值准确这三类任务共用同一个通道但可以在settings.json里给每类任务单独指定模型名和温度互不干扰。3. 可复制配置config.toml 与 settings.json 骨架3.1 目录结构先定下来bill-agent/ ├── config.toml ├── settings.json ├── .env ├── agent/ │ ├── __init__.py │ ├── llm_client.py │ ├── tasks.py │ └── parser.py └── data/ └── bills.dbconfig.toml管通道和运行参数settings.json管任务级配置。分开的原因是前者换环境才动后者调优时经常改。3.2 config.toml 完整骨架# config.toml [llm] base_url https://taotoken.net/api api_key ${TAOTOKEN_API_KEY} timeout 60 max_retries 3 [agent] name bill-harness data_dir ./data db_path ./data/bills.db log_level INFO [harness] # 任务路由把任务名映射到 settings.json 里的配置块 task_map { bill_parse parse, bill_classify classify, monthly_summary summary }api_key用${TAOTOKEN_API_KEY}占位运行时从环境变量读取。这样配置文件可以放心提交Key 留在本地。3.3 settings.json 完整骨架{ parse: { model: gpt-4o-mini, temperature: 0.0, system_prompt: 你是账单解析器。把输入的一行交易记录解析为 JSON字段time, amount, direction, counterpart, remark。只输出 JSON不要解释。, max_tokens: 512 }, classify: { model: gpt-4o-mini, temperature: 0.1, system_prompt: 你是记账分类器。根据 remark 和 counterpart 判断分类从给定分类列表中选择。输出 JSON{category, confidence}。, categories: [餐饮, 交通, 住房, 购物, 娱乐, 医疗, 宠物, 其他], max_tokens: 128 }, summary: { model: gpt-4o-mini, temperature: 0.3, system_prompt: 你是财务汇总助手。根据传入的账单列表输出本月总支出、分类占比、环比变化。用简洁中文。, max_tokens: 1024 } }三个配置块对应三类任务task_map负责把任务名路由过去。加新任务时只需在settings.json加一块、在task_map加一行映射。3.4 读取配置的客户端代码# agent/llm_client.py import os import json import tomllib from openai import OpenAI def load_config(pathconfig.toml): with open(path, rb) as f: cfg tomllib.load(f) cfg[llm][api_key] os.environ.get(TAOTOKEN_API_KEY, cfg[llm][api_key]) return cfg def load_settings(pathsettings.json): with open(path, r, encodingutf-8) as f: return json.load(f) class LLMClient: def __init__(self, config, settings): self.config config self.settings settings self.client OpenAI( base_urlconfig[llm][base_url], api_keyconfig[llm][api_key], timeoutconfig[llm][timeout], ) def run_task(self, task_name, user_input): task_key self.config[harness][task_map][task_name] task_cfg self.settings[task_key] resp self.client.chat.completions.create( modeltask_cfg[model], temperaturetask_cfg[temperature], max_tokenstask_cfg[max_tokens], messages[ {role: system, content: task_cfg[system_prompt]}, {role: user, content: user_input}, ], ) return resp.choices[0].message.content这段代码是 Harness 的核心任务名进配置自动匹配模型调用统一出口。你不需要在每个任务里重复写base_url和api_key。4. 验证请求一次端到端跑通4.1 准备环境变量export TAOTOKEN_API_KEYsk-你的真实KeyWindows 用set或写进.env配合python-dotenv。确认环境变量生效python -c import os; print(os.environ.get(TAOTOKEN_API_KEY)[:6])输出前 6 位说明读取成功。4.2 写一个最小验证脚本# verify.py from agent.llm_client import load_config, load_settings, LLMClient config load_config() settings load_settings() client LLMClient(config, settings) # 任务一账单解析 raw 2024-06-15 12:30:00 | -28.50 | 支出 | 瑞幸咖啡 | 生椰拿铁 parsed client.run_task(bill_parse, raw) print(解析结果:, parsed) # 任务二分类记账 classified client.run_task(bill_classify, parsed) print(分类结果:, classified) # 任务三月度汇总 summary client.run_task(monthly_summary, f账单列表{parsed}) print(汇总结果:, summary)4.3 预期成功结果解析任务应返回类似{time: 2024-06-15 12:30:00, amount: 28.50, direction: 支出, counterpart: 瑞幸咖啡, remark: 生椰拿铁}分类任务应返回{category: 餐饮, confidence: 0.95}汇总任务会输出一段中文包含总支出和分类占比。三个任务都返回结构化结果说明通道、配置、路由全部打通。4.4 把结果落库# agent/parser.py import sqlite3 import json def save_bill(db_path, parsed_json): data json.loads(parsed_json) conn sqlite3.connect(db_path) conn.execute( INSERT INTO bills (time, amount, direction, counterpart, remark) VALUES (?, ?, ?, ?, ?), (data[time], data[amount], data[direction], data[counterpart], data[remark]), ) conn.commit() conn.close()建表语句CREATE TABLE IF NOT EXISTS bills ( id INTEGER PRIMARY KEY AUTOINCREMENT, time TEXT NOT NULL, amount REAL NOT NULL, direction TEXT NOT NULL, counterpart TEXT, remark TEXT, category TEXT );到这里Harness 骨架就跑通了配置驱动、任务路由、模型调用、结果落库四步闭环。5. 本篇常见错排查5.1 401 或鉴权失败最常见原因是环境变量没生效或者 Key 复制时带了空格。先确认python -c import os; print(repr(os.environ.get(TAOTOKEN_API_KEY)))如果输出None说明变量没设上。如果输出带引号或空格说明复制时多了字符。另外检查config.toml里base_url是否写成了带路径的形式统一通道只需要https://taotoken.net/api。5.2 模型返回不是 JSON解析任务对 JSON 稳定性要求高。如果模型返回了多余解释把temperature调到 0并在 system prompt 里加一句「只输出 JSON不要 markdown 代码块」。如果还是不稳定可以在代码里做一次清洗import re def extract_json(text): match re.search(r\{.*\}, text, re.DOTALL) return match.group(0) if match else text5.3 分类结果总是「其他」检查settings.json里categories列表是否和你的实际消费场景匹配。如果分类太少模型只能往「其他」塞。建议先列 8 到 12 个高频分类每个分类在 prompt 里给一两个关键词示例比如「餐饮瑞幸、星巴克、外卖」。5.4 月度汇总数值对不上汇总任务的输入是结构化账单列表如果前面解析阶段金额符号搞错支出记成正数汇总就会偏。建议在解析 prompt 里明确「支出为负数收入为正数」并在落库前做一次校验assert data[direction] in (支出, 收入) if data[direction] 支出: data[amount] -abs(data[amount])5.5 超时或重试风暴timeout设 60 秒够用max_retries设 3 次。如果频繁超时先检查网络再检查是不是单次输入太长。账单解析建议一行一行传不要一次塞几百行。5.6 配置文件改了不生效tomllib是启动时读取的改完config.toml要重启进程。settings.json如果在代码里做了缓存也要注意刷新。调试阶段可以在每次run_task前重新加载生产环境再改成启动加载。6. 下一步把骨架接进你的工作流骨架跑通后接下来三件事按优先级排第一把账单解析接到真实数据源。微信和支付宝的 CSV 编码不同先做编码探测再按行喂给解析任务。第二给分类任务加一个本地缓存同一备注第二次出现直接查缓存省调用也省时间。第三月度汇总做成定时任务每月 1 号自动跑结果推到你的通知渠道。如果你要长期跑编码和 Agent 任务可以了解 Coding Plan把开发环境和运行环境分开管理。需要验证模型对话效果直接进模型对话页面试。接入过程中遇到鉴权或路由问题先看 API Keys 管理页确认 Key 状态再对照接入文档检查base_url和模型名。配置文件骨架的价值不在于一次写完美而在于它把「模型调用」和「业务逻辑」隔开了。你换模型、换供应商、加任务都只动配置不动代码。这才是 Harness 工程化落地最实在的部分。