效果展示

skill下载链接：
https://www.skillhub.cn/skills/finalcial

1、用例图（功能描述）

主用例	功能描述	细分场景 / 关联用例
记录收支情况	用户向系统录入、保存收入 / 支出数据，是记账的基础功能	-
查看收支情况	用户查询自己的收支数据，支持多维度时间筛选	包含 4 种具体查询方式：・今日收支情况：查询当日数据・当月收支情况：查询当前自然月数据・本年收支情况：查询当前自然年数据・自定义日期查询：用户指定任意日期范围查询
收支情况评价	用户对收支状况进行评估（可理解为系统提供收支分析、反馈或用户手动评价功能）	-

2、ER图

这里我打算使用SQLite进行数据持久化
为了AI方便只使用一个实体

属性名	中文名称	数据类型	约束	说明
id	记录 ID	INTEGER	主键、自增	唯一标识每一笔记账
user_id	用户 ID	TEXT/INTEGER	非空	区分不同用户
create_time	发生时间	TEXT	非空	精准到分钟：2025-04-28 15:30
type	收支类型	TEXT	非空	固定值：收入 / 支出
amount	金额	REAL	非空	数字（正数即可，用类型区分收支）
reason	发生原因	TEXT	可空	备注：吃饭、工资、购物等

3、代码

核心思想是，只给AI提供数据crud接口。其余不管

skill.py文件

import sqlite3



class AIBookkeeping:
    def __init__(self, db_name="ai_account.db"):
        self.conn = sqlite3.connect(db_name, check_same_thread=False)
        self.cursor = self.conn.cursor()
        self._create_table()

    # 创建数据表
    def _create_table(self):
        self.cursor.execute('''
        CREATE TABLE IF NOT EXISTS account (
            id INTEGER PRIMARY KEY AUTOINCREMENT,
            user_id TEXT NOT NULL,
            create_time TEXT NOT NULL,
            type TEXT NOT NULL,
            amount REAL NOT NULL,
            reason TEXT DEFAULT ''
        )
        ''')
        self.conn.commit()

    # 1. 新增记录
    def add_record(self, user_id: str, create_time: str, type_name: str, amount: float, reason: str = ""):
        try:
            self.cursor.execute('''
            INSERT INTO account (user_id, create_time, type, amount, reason)
            VALUES (?, ?, ?, ?, ?)
            ''', (user_id, create_time, type_name, amount, reason))
            self.conn.commit()
            return "记账成功"
        except Exception as e:
            return f"记账失败：{str(e)}"


    # 2. 删除记录
    def delete_record(self, user_id: str, record_id: int):
        try:
            self.cursor.execute('''
            DELETE FROM account WHERE id=? AND user_id=?
            ''', (record_id, user_id))
            self.conn.commit()
            return "删除成功" if self.cursor.rowcount > 0 else "删除失败：无此记录"
        except Exception as e:
            return f"删除失败：{str(e)}"

    # 3. 更新记录
    def update_record(self, user_id: str, record_id: int, type_name: str, amount: float, reason: str = ""):
        try:
            self.cursor.execute('''
            UPDATE account 
            SET type=?, amount=?, reason=? 
            WHERE id=? AND user_id=?
            ''', (type_name, amount, reason, record_id, user_id))
            self.conn.commit()
            return "更新成功" if self.cursor.rowcount > 0 else "更新失败：无此记录"
        except Exception as e:
            return f"更新失败：{str(e)}"

    # 4. 自定义时间查询
    def query_records(self, user_id: str, start_date: str, end_date: str):
        try:
            self.cursor.execute('''
            SELECT * FROM account 
            WHERE user_id=? AND create_time BETWEEN ? AND ?
            ''', (user_id, f"{start_date} 00:00", f"{end_date} 23:59"))
            return self.cursor.fetchall()
        except Exception as e:
            return f"查询失败：{str(e)}"

    # 关闭连接
    def close(self):
        self.conn.close()






# AI 调用示例
if __name__ == "__main__":
    ai_book = AIBookkeeping()

    # 1. AI 传入时间记账
    print(ai_book.add_record("user_001", "2025-05-20 15:30", "支出", 25.5, "买咖啡"))



    # 2. AI 传入日期查询
    data = ai_book.query_records("user_001", "2025-05-20", "2025-05-20")
    print("查询数据：", data)

    # 3. 更新/删除
    if data:
        record_id = data[0][0]
        print(ai_book.update_record("user_001", record_id, "收入", 100, "红包"))
        print(ai_book.delete_record("user_001", record_id))

    ai_book.close()

4、基本业务流程

用户向 AI 发送包含收支信息的消息（如 “花了 25.5 元买咖啡”），触发流程，箭头标注为提供收支情况()。

AI 收到消息后，完成意图判断（识别为记账请求），并从消息中提取关键参数：用户 ID、收支时间、类型、金额、备注，对应内部自调用提取参数()。

AI 向技能发起add_record()调用，传入提取到的参数（示例：add_record("user_001","2025-05-20 15:30","支出",25.5,"买咖啡")）。

技能收到请求后，向数据库发起插入数据库()操作，将本次收支记录写入 SQLite。

数据库完成写入后，向技能返回操作结果（成功 / 失败）。

技能把数据库的结果透传给 AI，告知记账操作已完成。

为了生成今日汇总，AI 向技能发起query_records(用户id, 今日, 今日)调用，查询该用户今日的所有收支记录。

技能向数据库发起查看今天的收支情况()查询，获取用户今日的完整记账数据。

数据库将查询结果返回给技能。

技能把今日收支数据透传给 AI。

AI 结合本次记录和今日汇总数据，生成客观分析与评价，最终回复给用户，标注为根据今日收支情况评价本次收支()。

具体看 5、说明文档里的业务流程部分

5、说明文档编写

name: finance_advisor
description: 该技能用于完成记账、收支情况查看任务，解决收支情况的记录与查询的问题。
当用户提及自己的今日收支情况场景时触发。
metadata: {“clawdbot”:{“emoji”:“💰”}}

账单管理技能 (finance_advisor)

优先根据 4、标准业务流程 来处理用户的请求，如果标准业务流程不符合用户意图，则可自行调用函数

1、数据模型

Sqlite数据库表，只有一个收支情况实体

字段名	数据类型	约束条件	字段说明
id	INTEGER	PRIMARY KEY AUTOINCREMENT	记录唯一标识，自增主键，不可修改
user_id	TEXT	NOT NULL	用户唯一 ID，用于隔离不同用户数据
create_time	TEXT	NOT NULL	收支发生时间（格式：YYYY-MM-DD HH:MM），由 AI 传入，不依赖系统时区
type	TEXT	NOT NULL	收支类型，固定值：收入/支出
amount	REAL	NOT NULL	收支金额（正数）
reason	TEXT	DEFAULT ‘’	收支原因 / 备注，可选字段，默认为空

---

2、前置条件

本地运行，无需其它环境

---

3、函数说明

A、数据读写对象函数

创建对象

ai_book = AIBookkeeping()

对象可调用的方法如下

1. add_record()

• 功能：新增一条收支记账记录，数据持久化存储到 SQLite 数据库

• 函数签名：def add_record(self, user_id: str, create_time: str, type_name: str, amount: float, reason: str = "")

• 参数：

  • user_id (str)：用户唯一 ID，用于数据隔离

  • create_time (str)：记账时间，格式：YYYY-MM-DD HH:MM，由 AI 传入，不依赖系统时区，如果用户的消息里没有完整时间，则自行获取当前时间

  • type_name (str)：收支类型，仅支持 收入 / 支出

  • amount (float)：收支金额（正数）

  • reason (str, 可选)：收支原因 / 备注，默认为空字符串

• 返回值：str，操作结果提示（记账成功 / 记账失败：xxx）

• 备注：纯数据写入接口，无业务逻辑，适配 Docker 部署无时区问题

2. delete_record()

• 功能：根据记录 ID 删除指定记账数据，仅允许删除当前用户自己的记录

• 函数签名：def delete_record(self, user_id: str, record_id: int)

• 参数：

  • user_id (str)：用户唯一 ID，权限校验

  • record_id (int)：记账记录的唯一 ID（主键）

• 返回值：str，操作结果提示（删除成功 / 删除失败：无此记录）

• 备注：自带用户权限校验，防止越权删除他人数据

3. update_record()

• 功能：根据记录 ID 修改指定记账数据，仅允许修改当前用户自己的记录

• 函数签名：def update_record(self, user_id: str, record_id: int, type_name: str, amount: float, reason: str = "")

• 参数：

  • user_id (str)：用户唯一 ID，权限校验

  • record_id (int)：记账记录的唯一 ID（主键）

  • type_name (str)：修改后的收支类型（收入 / 支出）

  • amount (float)：修改后的收支金额

  • reason (str, 可选)：修改后的备注信息，默认为空字符串

• 返回值：str，操作结果提示（更新成功 / 更新失败：无此记录）

• 备注：不修改记账时间，仅更新类型、金额、备注

4. query_records()

• 功能：根据用户 ID + 时间范围，查询符合条件的所有记账原始数据

• 函数签名：def query_records(self, user_id: str, start_date: str, end_date: str)

• 参数：

  • user_id (str)：用户唯一 ID

  • start_date (str)：查询开始日期，格式：YYYY-MM-DD

  • end_date (str)：查询结束日期，格式：YYYY-MM-DD

• 返回值：list / str，成功返回原始数据列表，失败返回错误提示

  数据格式示例

  [(1, “user_001”, “2025-05-20 15:30”, “支出”, 25.5, “买咖啡”)]

• 备注：时间范围由 AI 传入，不依赖容器时区，返回原始数据供 AI 处理

5. close()

• 功能：关闭数据库连接，释放资源

• 函数签名：def close(self)

• 参数：无

• 返回值：无

• 备注：程序结束时调用，保证数据库连接安全关闭

---

4、标准业务流程

业务流程A：记录本次收支情况并给出建议

当用户发消息时，按以下流程判断并处理：

步骤 1：意图判断

判断用户消息是否包含记账意图。判断标准（满足任一即可）：

• 包含金额数字（如 “花了 18 块”、“收入 5000”）

• 包含关键词：花了/支出/用了/买了/付了/收入/收到/赚钱/工资/进账

• 包含 “记” 或 “记账”

• 包含 “查”、“看”、“统计”、“月光”、“预算”——这些是查询意图

如果没有记账或查询意图，则不属于该流程

步骤 2：记录支出

1. 从消息中提取参数：

   • user_id (str)：用户唯一 ID，用于数据隔离

   • create_time (str)：记账时间，格式：YYYY-MM-DD HH:MM，由 AI 传入，不依赖系统时区，如果用户的消息里没有完整时间，则自行获取当前时间

   • type_name (str)：收支类型，仅支持 收入 / 支出

   • amount (float)：收支金额（正数）

   • reason (str, 可选)：收支原因 / 备注，默认为空字符串

   • start_time(str)：今日开始时间，格式：YYYY-MM-DD HH:MM，由 AI 传入，不依赖系统时区，如果用户的消息里没有完整时间，则自行获取今日开始时间

2. 调用函数（按顺序）：

   ai_book.add_record(user_id ,create_time, type_name, amount, reason) # 添加收支记录
   today_state = ai_book.query_records(user_id, start_time, create_time) # 获取到目前为止的今日收支情况
   ai_book.close() # 本次业务结束，关闭数据库连接

3. 基于今日收支情况 today_state，生成对用户的客观分析与评价：

4. 回复用户确认消息（格式示例）：

   ✅ 已记录！{{日期}}
   ​
   今日汇总：
   {{today_state}}
   ​
   {{简单的客观分析与评价}}

6、元文件编写

{
  "name": "finance_advisor",
  "description": "对收支情况进行操作",
  "version": "1.0.0",
  "main": "skill.py",
  "permissions": [],
  "author": "邓布利多"
}

7、文件结构