ezBookkeeping API Tools 实战指南：用 ebktools 命令行脚本完成记账、查询与汇率获取-平芜编程栈

后端
前端
金融科技

【免费下载链接】ezbookkeeping

ezBookkeeping is an open source, powerful, self-hosted personal finance app that is easy to use.

项目地址：https://gitcode.com/gh_mirrors/ez/ezbookkeeping

ezBookkeeping 是开源、可自托管的个人记账应用，其官方 Skills 目录下内置了一套名为ebktools的 API 命令行工具（SKILL.md），允许你无需登录网页端，直接用 Shell 或 PowerShell 调用服务端 REST API 来完成新增交易、查询流水、读取账户/分类/标签以及拉取汇率等操作。阅读本文后，你将掌握 ebktools 的完整用法（list/help/ 直接调用）、全局时区与原始输出选项、12 个内置命令的详细参数，并能理解脚本底层如何与 ezBookkeeping 的/api/v1接口对接，从而把它接入自己的脚本、定时任务或 AI Agent 工作流。

一、认识 ebktools：ezBookkeeping 的 API 命令行封装

ebktools 不是独立的可执行程序，而是随仓库一起分发的两个脚本：

文件	运行环境	依赖
ebktools.sh	Linux / macOS（`sh`兼容 Shell）	`grep`、`sed`、`awk`、`date`、`curl`、`jq`
ebktools.ps1	Windows（PowerShell 5.1+ / 7+）	无需额外依赖（内部使用`Invoke-WebRequest`）

两个脚本共享同一套"API 配置结构"：脚本内部以 JSON（Shell 版）或 PowerShell 哈希表（PS 版）定义了每个命令的名称、HTTP 方法、请求路径、必填/可选参数、参数类型、参数说明、响应结构以及**美化输出（PrettyResponse）**规则。这意味着新增 API 只需扩展这份配置即可，无需改动调用逻辑。

从脚本的main()（ebktools.sh）可以看到，入口在执行前会先做两件事：检查必要依赖是否可用（缺失时报错并返回退出码 127），以及加载环境变量配置。

二、快速上手：配置、验证与三种基本用法

1. 配置服务器地址与 API Token

所有调用都依赖两个环境变量，缺一不可：

变量	是否必填	含义	示例
`EBKTOOL_SERVER_BASEURL`	必填	ezBookkeeping 服务器基础地址（不包含`/api/v1`前缀）	`http://localhost:8080`
`EBKTOOL_TOKEN`	必填	ezBookkeeping API Token（在 Web 端"Token 管理"中生成）	一段 JWT 字符串

Linux / macOS 下通过export设置：

export EBKTOOL_SERVER_BASEURL="http://localhost:8080" export EBKTOOL_TOKEN="YOUR_TOKEN"

Windows PowerShell 下通过$env:设置：

$env:EBKTOOL_SERVER_BASEURL = 'http://localhost:8080' $env:EBKTOOL_TOKEN = 'YOUR_TOKEN'

关于 Token 的生成：脚本配置中tokens-list返回的tokenType字段约定1: Normal Token（普通登录会话）、5: MCP Token、8: API Token。后端在 pkg/api/tokens.go 中提供TokenGenerateAPIHandler生成 API Token，且只有USER_TOKEN_TYPE_NORMAL类型的当前令牌才有权生成 API Token（见TokenGenerateAPIHandler中对claims.Type != core.USER_TOKEN_TYPE_NORMAL的校验），因此建议在网页端登录后用"API Token"渠道生成专用令牌供脚本使用。

2. 列出所有可用命令

Linux / macOS：

sh scripts/ebktools.sh list

Windows：

scripts\ebktools.ps1 list

输出为按名称对齐的命令清单，例如tokens-list、accounts-list、transactions-add、exchangerates-latest、server-version等，每行附一句功能描述。

3. 查看某个命令的帮助

Linux / macOS：

sh scripts/ebktools.sh help <command>

Windows：

scripts\ebktools.ps1 help <command>

例如sh scripts/ebktools.sh help server-version。帮助页会展示：HTTP 方法、请求路径、是否需要当前时区信息、必填参数（含类型与说明）、可选参数、响应结构以及一条可直接复制的调用示例。由于帮助文本会根据当前系统时区动态生成示例，即使你记不住参数也能照着执行。

4. 直接调用 API

通用调用语法：

# Linux / macOS sh scripts/ebktools.sh [global-options] <command> [command-options] # Windows scripts\ebktools.ps1 [global-options] <command> [command-options]

最小示例——查询服务器版本：

sh scripts/ebktools.sh server-version

脚本会打印Calling API: GET http://localhost:8080/api/v1/systems/version.json，随后输出响应结果（默认格式化为 Markdown 表格，而非原始 JSON）。

三、全局选项：时区与输出格式

调用任何命令前可附加三个全局选项（Shell 版以--开头，PowerShell 版以-开头）：

选项	说明
`--tz-name <name>`/`-tzName <name>`	当前时区的 IANA 名称，例如北京时间用`Asia/Shanghai`
`--tz-offset <offset>`/`-tzOffset <offset>`	当前时区相对 UTC 的分钟偏移，例如 UTC+8 填`480`
`--raw-response`/`-rawResponse`	关闭美化输出，直接显示原始 JSON 响应

时区选项存在如下优先级规则（见 ebktools.sh 的call_api实现）：

若同时设置--tz-name与--tz-offset，--tz-name优先；
若两者都未设置，脚本自动探测当前系统时区（Linux 下读取/etc/timezone或解析/etc/localtime符号链接；Windows 下通过[System.TimeZoneInfo]::Local获取，并附带一张 Windows 时区 ID → IANA 名称的映射表，例如China Standard Time→Asia/Shanghai）；
若探测失败，示例帮助文本会回退到Asia/Shanghai与偏移480；
若某个命令标记为RequiresTimezone: true（如transactions-list、transactions-add），而脚本既探测不到系统时区、也未提供上述选项，则会报错退出，提示补全时区信息。

为什么部分命令强制要求时区？因为交易的时间语义依赖"本地时区 + UTC 偏移"才能正确还原为账户所在地的记账时刻。脚本会把时区信息放入请求头X-Timezone-Name或X-Timezone-Offset一并发送给服务端。

--raw-response则适合调试或对接其他程序：此时脚本跳过 Markdown 表格渲染，用jq（Shell 版）对 JSON 做格式化后原样输出。

四、12 个内置命令全景

下面按功能分组列出全部内置命令及其参数。命令名即脚本第二参数，参数以--（Shell）/-（PowerShell）前缀传入。

1. 会话与 Token 查询

tokens-list—GET /tokens/list.json

无参数。返回当前用户的所有会话，字段包括tokenId、tokenType（1普通、5MCP、8API）、userAgent、lastSeen（会话最后刷新的 Unix 时间）、isCurrent（是否为当前会话）。

2. 账户管理

accounts-list—GET /accounts/list.json

无参数。返回当前用户全部账户（含子账户层级），字段：id、name、parentId（0表示一级账户）、category、type、icon、iconType、color（RRGGBB 十六进制）、currency、balance、comment、creditCardStatementDate、displayOrder、isAsset、isLiability、hidden、subAccounts。

其中两个关键枚举：

category（账户类别）：1现金、2活期/支票账户、3信用卡、4虚拟账户、5债务账户、6应收账户、7投资账户、8储蓄账户、9定期存单；
type（账户类型）：1单一账户、2多子账户。

accounts-add—POST /accounts/add.json（需要时区）

参数	必填	类型	说明
`name`	是	string	账户名称
`category`	是	integer	账户类别（枚举同上）
`type`	是	integer	账户类型（`1`/`2`）
`icon`	是	string	图标 ID
`iconType`	是	integer	图标类型，`0`系统图标、`1`用户自定义图标
`color`	是	string	图标颜色 RRGGBB
`currency`	是	string	ISO 4217 货币代码；父账户传`---`
`balance`	否	string	初始余额，支持两位小数；负债账户传负数
`balanceTime`	否	integer	余额对应的 Unix 时间，设置`balance`时必填
`comment`	否	string	账户备注
`creditCardStatementDate`	否	integer	信用卡账单日

3. 交易分类

transaction-categories-list—GET /transaction/categories/list.json

无参数。返回按类型组织的层级分类树：1: Income（收入）、2: Expense（支出）、3: Transfer（转账），每个分类含id、name、parentId（0为一级分类）、type、icon、iconType、color、comment、displayOrder、hidden、subCategories。列表接口允许传type过滤（类型枚举同上）。

transaction-categories-add—POST /transaction/categories/add.json

参数	必填	类型	说明
`name`	是	string	分类名称
`type`	是	integer	分类类型（`1`收入 /`2`支出 /`3`转账）
`icon`	是	string	图标 ID
`iconType`	是	integer	图标类型（`0`系统 /`1`自定义）
`color`	是	string	RRGGBB 颜色
`parentId`	否	string	父分类 ID，`0`表示一级分类
`comment`	否	string	分类备注

4. 交易标签

transaction-tags-list—GET /transaction/tags/list.json

无参数。返回所有标签，字段：id、name、groupId（所属标签组）、displayOrder、hidden。

transaction-tags-add—POST /transaction/tags/add.json

参数	必填	类型	说明
`name`	是	string	标签名称
`groupId`	否	string	标签组 ID，`0`表示默认组

5. 交易流水（查询）

transactions-list—GET /transactions/list.json（需要时区，分页）

参数	必填	类型	说明
`count`	是	integer	每页条数，最大 50
`type`	否	integer	按交易类型过滤：`1`余额调整、`2`收入、`3`支出、`4`转账
`category_ids`	否	string	按分类 ID 过滤，逗号分隔
`account_ids`	否	string	按账户 ID 过滤，逗号分隔
`tag_filter`	否	string	按标签过滤
`amount_filter`	否	string	按金额过滤
`keyword`	否	string	按关键词过滤
`must_have_pictures`	否	boolean	是否只取带凭证图片的交易
`max_time`	否	integer	最大时间序列 ID 游标，`0`表示最新
`min_time`	否	integer	最小时间序列 ID 游标
`page`	否	integer	指定页码
`with_count`	否	boolean	是否返回总条数
`with_pictures`	否	boolean	是否返回图片 ID
`trim_account`	否	boolean	是否只返回账户 ID
`trim_category`	否	boolean	是否只返回分类 ID
`trim_tag`	否	boolean	是否只返回标签 ID

响应结构：items数组（每项含id、timeSequenceId、type、categoryId、category、time、utcOffset、sourceAccountId、sourceAccount、destinationAccountId、destinationAccount、sourceAmount、destinationAmount、hideAmount、tagIds、tags、pictures、comment、geoLocation、editable），外加nextTimeSequenceId（请求更早数据时作为下一次的max_time游标）与totalCount（开启with_count时返回）。

transactions-list-all—GET /transactions/list/all.json（需要时区，一次性返回全部匹配）

参数与transactions-list大致相同，但分页参数替换为时间区间：

参数	必填	类型	说明
`start_time`	否	integer	查询起始 Unix 时间
`end_time`	否	integer	查询结束 Unix 时间

其余可选参数（type、category_ids、account_ids、tag_filter、amount_filter、keyword、must_have_pictures、with_pictures、trim_account、trim_category、trim_tag）语义与transactions-list一致。响应为交易对象数组（无分页元数据），适合一次性导出或全量分析。

6. 新增交易

transactions-add—POST /transactions/add.json（需要时区）

参数	必填	类型	说明
`type`	是	integer	交易类型：`1`余额调整、`2`收入、`3`支出、`4`转账
`categoryId`	是	string	交易分类 ID，支持二级分类
`time`	是	integer	交易 Unix 时间
`utcOffset`	是	integer	交易时区偏移（分钟）
`sourceAccountId`	是	string	来源账户 ID，支持无子账户的账户或子账户
`sourceAmount`	是	integer	来源金额（两位小数整数表示，见下文"金额单位"）
`destinationAccountId`	否	string	转账目标账户 ID
`destinationAmount`	否	integer	转账目标金额
`hideAmount`	否	boolean	是否隐藏金额
`tagIds`	否	string	标签 ID 列表，逗号分隔，如`tagid1,tagid2`
`pictureIds`	否	string	凭证图片 ID 列表，逗号分隔，如`picid1,picid2`
`comment`	否	string	交易备注
`geoLocation`	否	string	地理位置，格式`longitude,latitude`，如`116.33,39.93`

典型调用示例（新增一笔支出，金额 12.34）：

sh scripts/ebktools.sh --tz-name Asia/Shanghai transactions-add \ --type 3 \ --categoryId <分类ID> \ --time 1735689600 \ --utcOffset 480 \ --sourceAccountId <账户ID> \ --sourceAmount 1234 \ --comment "午餐"

7. 汇率与版本

exchangerates-latest—GET /exchange_rates/latest.json

无参数。返回最新汇率快照：dataSource（数据源名称）、referenceUrl（参考来源）、updateTime（更新时间 Unix 时间戳）、baseCurrency（基准货币）、exchangeRates数组（每项为currency货币代码与rate汇率，含义是"1 单位基准货币 = 多少单位该货币"）。

server-version—GET /systems/version.json

无参数。返回version（服务端版本号）与commitHash（Git 提交哈希），可用于脚本自检服务连通性与版本兼容性。

五、参数类型、金额单位与校验规则

脚本会根据配置表中声明的ParamTypes对参数做本地校验，类型不合法会直接报错退出，而不是把错误请求发给服务器。共有五种参数类型：

类型	校验规则	典型参数
`string`	任意字符串	`name`、`comment`、`currency`
`integer`	匹配`^-?[0-9]+$`（含负整数）	`type`、`count`、`time`、`utcOffset`
`boolean`	仅接受`true`/`false`/`1`/`0`	`hideAmount`、`with_count`
`string_array`	逗号分隔字符串，拆分为数组后放入请求体	`tagIds`、`pictureIds`
`geo_location`	匹配`longitude,latitude`格式	`geoLocation`（POST 时被转换为`{"latitude":…,"longitude":…}`JSON 对象）

金额单位是一个必须注意的约定：API 中所有金额字段都以"整数 + 隐含两位小数"传输。例如1234表示12.34，-500表示-5.00。这一规则同时适用于账户余额（balance）与交易金额（sourceAmount/destinationAmount），文档与脚本注释中均有明确说明。

此外脚本还校验必填参数完整性：配置表中RequiredParams声明的参数若未传入，会提示Required parameter '--xxx' is missing并退出；--开头参数若缺少值也会报错。

六、响应输出：从 JSON 到 Markdown 表格

为了让人和 LLM 都能直观阅读结果，脚本默认按PrettyResponse配置将响应渲染为 Markdown 表格，共四种渲染策略（对应 ebktools.sh 的print_result分支）：

策略	适用响应	说明
`simple_array_to_markdown_table`	平铺数组	直接按`Columns`列渲染，如`tokens-list`、`transaction-tags-list`
`hierarchical_array_to_markdown_table`	含子节点的数组	先按`ChildKey`（如`subAccounts`）把父子节点展平再渲染，如`accounts-list`
`hierarchical_object_to_markdown_table`	按类型分组的对象	先展平`ChildKey`（如`subCategories`）再渲染，如`transaction-categories-list`
`nested_array_to_markdown_table`	嵌套在对象中的数组	按`DataPath`（如`.items`、`.exchangeRates`）取出数组渲染，并在表格上方打印`Metadata`元信息（如`Total Count`、`Next Time Sequence ID`），如`transactions-list`、`exchangerates-latest`

当响应没有配置PrettyResponse（如server-version）、数据为空（输出No data to display）或指定了--raw-response时，则回退为格式化 JSON 输出。

七、故障排查指南

脚本在使用中最常见的几类问题及解决办法：

1. 环境变量未设置

错误信息形如Error: Environment variable 'EBKTOOL_SERVER_BASEURL' is not set.或Error: Environment variable 'EBKTOOL_TOKEN' is not set.。解决办法有两种：

在系统中设置环境变量（export/$env:，见上文）；
在当前目录、父目录或用户主目录下创建.env文件并写入两个变量。脚本启动时会按"当前目录 → 父目录 → 主目录"的顺序查找并解析.env（Shell 版实现见 ebktools.sh 的load_env_from_paths），支持#注释、空行、键值对以及带引号的值：
```
# ~/.env EBKTOOL_SERVER_BASEURL="http://localhost:8080" EBKTOOL_TOKEN="YOUR_TOKEN"
```

2. 必要依赖缺失（仅 Shell 版）

check_dependency会逐个检查grep sed awk date curl jq，缺失时输出Error: "curl" is required.并返回退出码 127。安装对应工具（如 Ubuntu 下apt install curl jq）即可。

3. 需要时区的命令缺少时区信息

若探测不到系统时区且未传--tz-name/--tz-offset，会提示Command 'transactions-list' requires timezone information.，按提示补传任一参数即可。

4. API 调用失败

curl 层失败：提示API call failed (curl exit code: N)，通常是服务器地址不可达或网络问题；
业务层失败：脚本解析响应中的success字段，若为false或缺失，则原样打印 JSON 响应，此时应重点检查 Token 是否有效/过期、请求参数是否合法。从源码看，所有/api/v1路由都经过JWTAuthorizationByHeader与APITokenIpLimit两个中间件（cmd/webserver.go），Token 通过Authorization: Bearer <token>请求头传递——如果你的服务器开启了 API Token IP 限制，还需保证脚本所在机器的出口 IP 在允许列表内。

八、源码级原理：脚本与后端的调用链

理解调用链有助于排查问题与二次开发。一次完整的ebktools调用实际发生以下步骤：

URL 拼接：${EBKTOOL_SERVER_BASEURL}/api/v1/${Path}（ebktools.sh）。配置表中的Path均为相对路径（如transactions/add.json），前缀/api/v1由脚本统一补齐；
参数处理：GET 命令把参数 URL 编码后拼入查询字符串（key=value&...）；POST 命令把参数按类型转换后序列化为 JSON 请求体（integer/boolean转成原生类型、string_array拆数组、geo_location转经纬度对象），并设置Content-Type: application/json；
请求头：统一携带Authorization: Bearer <token>；需要时区的命令额外携带X-Timezone-Name或X-Timezone-Offset；
后端路由：服务端在 cmd/webserver.go 中注册了GET /accounts/list.json、POST /accounts/add.json、GET /transactions/list.json、POST /transactions/add.json、GET /transaction/categories/list.json、GET /transaction/tags/list.json等路由，分别绑定到api.Accounts.AccountListHandler、api.Transactions.TransactionListHandler、api.TransactionCategories.CategoryListHandler等处理器（如 pkg/api/accounts.go 的AccountListHandler），与脚本配置表中的Path一一对应；
结果渲染：脚本读取响应的success字段判断业务成功与否，成功则取result按PrettyResponse渲染成 Markdown 表格。

从这些细节可以推断：ebktools 本质上是 ezBookkeeping/api/v1REST 接口的一个"配置驱动"型客户端——只要维护好命令配置表，就能稳定跟随服务端 API 演进，非常适合作为自托管记账的自动化入口（定时同步账单、AI 助手记账、批量导入等场景）。

延伸阅读：核心文档 SKILL.md、Shell 实现 ebktools.sh、PowerShell 实现 ebktools.ps1、服务端路由注册 cmd/webserver.go、API Token 生成逻辑 pkg/api/tokens.go、请求鉴权中间件 pkg/middlewares/authorization.go。