功能描述

个人记账与账本管理工具。支持多账本、自然语言/批量记账、期初结余初始化、跨月余额趋势图、分类统计、多账本对比图、CSV导出、飞书云盘同步等。

使用说明 (SKILL.md)

Ledger - 个人记账技能（优化版）

Name: ledger cn
Author: victor233k

核心职责（触发条件）

当用户提到以下任一场景时，必须使用本技能，不要用其他方式代替：

记账、记录收入/支出、批量添加交易
查看某账本某月/多月汇总、流水、余额
画余额趋势图、支出饼图、柱状图等
导出 CSV / 同步到飞书云盘 / 上传文件
查询/设置分类、预算（未来扩展）
任何提到"账本""期初""结余""画图""同步""飞书"等关键词

数据存储与重要约定（严格遵守）

【重要】每次查询账本时，必须从账本目录读取最新数据，不要使用上下文缓存或假设数据
根路径：~/.openclaw/skills_data/ledger/\x3C账本名>/ （账本名如 "default"，不区分大小写但保持用户输入一致）
后续任何计算余额趋势、累计余额、月度汇总时：
- 查询汇总时：用户说"所有/全部"则包含所有月份数据，否则只统计指定月份
- 所有统计到的月份数据直接累加

日期解析规则（容错增强）

用户输入日期可能简写，必须智能补全为 YYYY-MM-DD：

"0114" / "14" → 当前月份的 14 日（例如当前 2026-03 → 2026-03-14）
"1" → 当前月份 1 日（2026-03-01）
"3月15日" → 当前年 03-15（2026-03-15）
"2026-3-5" → 补零为 2026-03-05
"去年12月" → 2025-12 (当年往前推一年)
无日期 → 默认当天（当前时间：2026-03-15）
如果跨月/跨年模糊，或输入如"上个月""明年"等相对时间，主动询问确认：示例回复："您说的'上个月'是指 2026 年 2 月吗？请确认日期范围。"

处理流程（Agent 必须严格遵循的思考链）

解析用户输入
- 确定账本名（从上下文提取，如"我的账本"，默认 "default"）
- 提取日期、金额、分类、账户、备注
  - 支持批量：多行"日期金额 [分类] [账户] [备注]"
  - 金额识别：正数/负数/"+""-""花了""收入"等关键词判断正负

SQLite CLI 工具（推荐，使用 uv 运行）

# 创建账本
uv run python ~/.openclaw/skills/ledger/src/cli.py create --name 新账本

# 列出账本
uv run python ~/.openclaw/skills/ledger/src/cli.py list

# 查看账本日期范围（输出格式：开始月份 结束月份）
uv run python ~/.openclaw/skills/ledger/src/cli.py range --name 兔兔
# 输出示例：2025-12 2026-03

# 查看所有交易
uv run python ~/.openclaw/skills/ledger/src/cli.py show --name 兔兔

# 查看单月汇总
uv run python ~/.openclaw/skills/ledger/src/cli.py show --name 兔兔 --month 2026-03

# 查看日期范围
uv run python ~/.openclaw/skills/ledger/src/cli.py show --name 兔兔 --from 2026-01 --to 2026-03

# 查看余额趋势
uv run python ~/.openclaw/skills/ledger/src/cli.py trend --name 兔兔

# 绘制账单折线图（单个账本） # 需要先查看记账范围
uv run python ~/.openclaw/skills/ledger/src/cli.py chart --name 兔兔 --from 2026-01 --to 2026-03

# 绘制多账本对比图 # 需要先查看记账范围
uv run python ~/.openclaw/skills/ledger/src/cli.py chart --name 兔兔 vk --from 2026-01 --to 2026-03

# 保存到指定路径
uv run python ~/.openclaw/skills/ledger/src/cli.py chart --name 兔兔 --output /tmp/chart.png

# 添加交易（日期默认当天）
uv run python ~/.openclaw/skills/ledger/src/cli.py add --name 兔兔 --amount -50 --category 餐饮

Markdown 输出（飞书群聊）

添加 --markdown 参数输出 Markdown 格式：

# Markdown 格式查看单月汇总
uv run python ~/.openclaw/skills/ledger/src/cli.py show --name 兔兔 --month 2026-03 --markdown

# Markdown 格式查看余额趋势
uv run python ~/.openclaw/skills/ledger/src/cli.py trend --name 兔兔 --markdown

SQLite 原生命令查询

# 按月统计收支
sqlite3 ~/.openclaw/skills_data/ledger/兔兔/ledger.db -header -column \
  "SELECT substr(date,1,7) as month, 
          SUM(CASE WHEN amount > 0 THEN amount ELSE 0 END) as income,
          SUM(CASE WHEN amount \x3C 0 THEN amount ELSE 0 END) as expense
   FROM transactions GROUP BY month ORDER BY month;"

# 按分类统计支出
sqlite3 ~/.openclaw/skills_data/ledger/兔兔/ledger.db -header -column \
  "SELECT category, SUM(ABS(amount)) as total 
   FROM transactions WHERE amount \x3C 0 
   GROUP BY category ORDER BY total DESC;"

# 查询2025年数据
sqlite3 ~/.openclaw/skills_data/ledger/兔兔/ledger.db -header -column \
  "SELECT id, date, amount, category, account, description 
   FROM transactions WHERE date LIKE '2025%';"

安全与边界

单笔 |amount| > 10000 必须二次确认
输入严重模糊或矛盾时，主动询问澄清，不要擅自假设
所有文件操作使用安全路径，避免越界

安全使用建议

This skill appears to implement a local SQLite ledger and mostly matches its description, but it does not sanitize ledger names before constructing filesystem paths. An attacker-controlled ledger name (e.g., containing '/' or '..' or an absolute path) could let the skill read or write outside the intended ~/.openclaw/skills_data/ledger directory. Before installing or enabling this skill: (1) review or patch get_db_path to reject absolute paths and path separators (e.g., require a safe name like /^[A-Za-z0-9_-]+$/ or use os.path.basename and refuse names containing '..'), (2) run the skill in a restricted environment or container, (3) avoid giving it access to sensitive home directories, and (4) if you do not trust the author, do not enable autonomous invocation or run it with elevated privileges. If you want, I can suggest concrete code changes to harden ledger-name handling and show tests to validate the fix.

功能分析

Type: OpenClaw Skill Name: ledger-by-cn Version: 1.0.1 The skill bundle is a legitimate personal accounting tool that manages financial transactions using a local SQLite database. It features robust date parsing, transaction CRUD operations, and data visualization using Matplotlib. Security analysis shows the use of parameterized SQL queries in 'src/services/ledger.py' to prevent injection and strict adherence to the designated data directory in 'src/db/connection.py'. No malicious behaviors, such as data exfiltration or unauthorized network access, were detected.

能力评估

ℹ Purpose & Capability

Name/description (personal ledger, CSV export, Feishu sync) aligns with the bundled Python CLI and DB code which reads/writes under ~/.openclaw/skills_data/ledger. The requested capabilities (no env vars, no external network) are proportionate. One mismatch: SKILL.md emphasizes 'use safe paths', but code does not sanitize ledger names (see get_db_path), which undermines that claim.

⚠ Instruction Scope

SKILL.md instructs reading the latest data from ~/.openclaw/skills_data/ledger/<ledger>/ and running bundled CLI scripts — which matches the code. However the runtime instructions and code allow ledger names provided by users to become filesystem paths without validation; a ledger name that is absolute or contains '../' can escape the intended base directory and cause read/write to arbitrary locations. This expands the scope beyond the stated safe-path intent.

✓ Install Mechanism

No install spec; code is included and designed to be invoked via local Python (uv run python <path>). There are no remote downloads or external package installs in the spec — lowest install risk. The code does import standard libraries and optional third-party libs (pypinyin, matplotlib) only when used; missing deps will fail but are not silently downloaded.

✓ Credentials

No environment variables, credentials, or external endpoints are requested. File and DB access is limited to the local data directory by design — appropriate for a local ledger tool. The only proportionality concern is the lack of ledger-name sanitization which can effectively broaden filesystem access.

✓ Persistence & Privilege

always is false and the skill does not request permanent/autonomous privileges beyond default agent invocation. It writes/creates files under ~/.openclaw/skills_data/ledger/<name>/ (expected behaviour for a ledger) but does not modify other skills or system-wide agent settings.

版本历史

v1.0.1

**重大变更：账本存储全面升级为 SQLite，命令行工具大幅增强** - 增加 SQLite 存储、全新 CLI 工具，比原有 JSONL 文件方式更高效安全 - 支持账本创建、导入、列出，快速查账、绘图、统计等多种命令 - 新增多账本对比图、多账本查询能力 - 支持 Markdown 输出和原生 SQL 查询，便于在群聊等场景友好展示 - 老版脚本（plot_ledger.py/print_ledger.py）已移除，推荐全部用 CLI 工具操作

v1.0.0

init

元数据

Slug ledger-by-cn

版本 1.0.1

许可证 MIT-0

累计安装 0

当前安装数 0

历史版本数 2

常见问题

ledger cn 是什么？

个人记账与账本管理工具。支持多账本、自然语言/批量记账、期初结余初始化、跨月余额趋势图、分类统计、多账本对比图、CSV导出、飞书云盘同步等。它是一个面向 Claude Code / OpenClaw 的 AI Agent Skill 插件，目前累计下载 262 次。

如何安装 ledger cn？

在 OpenClaw 或 Claude Code 对话框中运行命令「/install ledger-by-cn」即可一键安装，无需额外配置。

ledger cn 是免费的吗？

是的，ledger cn 完全免费，采用 MIT-0 许可证，可自由下载、安装和使用。

ledger cn 支持哪些平台？

ledger cn 跨平台运行，可在任意部署了 OpenClaw / Claude Code 的环境中使用（cross-platform）。

谁开发了 ledger cn？

由 victor233k（@victor233k）开发并维护，当前版本 v1.0.1。

ledger cn