飞书记账助手开发全纪录：从零搭建一个智能记账机器人

🤔简单说一下为什么要使用飞书来做：传统开发方式开发的或需要开发对应的前端，并且只能在网页上使用，体验感不好，而如果开发移动端的话要配置各种环境，开发难度大。而是用飞书应用开发不仅不用开发前端，还能双端通用（其实主要是移动端使用），效果非常好，并且多维表格还支持数据报表分析，体验感进一步优化。

1. 项目背景与目标

• 需求：轻量级记账软件📝，通过飞书机器人发送消息即可记账，并自动生成周/月/年度账单（后期扩展）。
• 技术选型：
  • 飞书开放平台（机器人 + 多维表格）
  • Python 3.11+（轻量，生态丰富）
  • LangChain 1.x + 硅基流动 API（接入大模型实现智能解析）
  • 阿里云 ECS（2核2G，Alibaba Cloud Linux 3）

2. 飞书机器人开发

2.1 创建应用并启用机器人

1. 登录飞书开放平台，创建企业自建应用“飞书记账助手”。
2. 添加机器人能力，并申请以下 API 权限：
3. 在“事件与回调”中，订阅方式选择“使用长连接接收事件”，并添加 im.message.receive_v1 事件。
4. 发布应用，点击创建版本之后再点击保存，之后就能够进行发布。

2.2 使用官方 SDK 接收消息

在飞书提供的三分钟搭建一个自动回复机器人中可以体验整个流程，并下载其示例代码。
所需要的代码文件在echo_bot文件夹中
具体代码文件如下：
运行命令如图所示（注意要在echo_bot文件夹中打开终端运行）：
我们使用 lark-oapi 的 WebSocket 长连接模式，无需公网 IP。

其中需要安装的依赖安装依赖（运行脚本中自动安装）：

pip install lark-oapi

基础消息接收代码（bot.py）：

import json
import lark_oapi as lark
from lark_oapi.api.im.v1 import *

APP_ID = "cli_xxx"
APP_SECRET = "xxx"

def do_p2_im_message_receive_v1(data: P2ImMessageReceiveV1):
    # 解析消息并回复“收到”
    content = json.loads(data.event.message.content)["text"]
    reply_content = json.dumps({"text": f"收到：{content}"})
    # 回复消息（省略实际调用代码）
    # ...

event_handler = lark.EventDispatcherHandler.builder(APP_ID, APP_SECRET)\
    .register_p2_im_message_receive_v1(do_p2_im_message_receive_v1).build()
client = lark.Client.builder().app_id(APP_ID).app_secret(APP_SECRET).build()
ws_client = lark.ws.Client(APP_ID, APP_SECRET, event_handler=event_handler)
ws_client.start()

2.3 写入飞书多维表格

先在飞书云文档中创建一张多维表格（可以使用图形化的方式创建数据库）如图，注意：多维表格一定要在云盘中创建，不要在知识库中创建，在知识库中创建多维表格的话需要额外分配权限再能运行

字段包括：

• 消费时间（自动默认值）
• 金额（数字）
• 分类（单选：餐饮、交通、购物、娱乐、医疗）
• 账户（单选：微信、支付宝、现金）
• 备注（文本）
  
  关键步骤：在表格右上角“更多” → “添加文档应用”，将机器人应用（通过名字搜索可以查到机器人应用）添加为可编辑成员。
  
  写入 API 示例：

from lark_oapi.api.bitable.v1 import *

def add_record(amount, category, account, note):
    client = lark.Client.builder().app_id(APP_ID).app_secret(APP_SECRET).build()
    fields = {
        "金额": amount,
        "分类": category,
        "账户": account,
        "备注": note
    }
    request = CreateAppTableRecordRequest.builder()\
        .app_token(APP_TOKEN)\
        .table_id(TABLE_ID)\
        .request_body(AppTableRecord.builder().fields(fields).build()).build()
    response = client.bitable.v1.app_table_record.create(request)
    return response.success()

3. 解决重复消息问题

飞书服务器要求在 3 秒内返回响应，否则会重推消息。我们的写入操作可能超过 3 秒，导致重复写入（因此写入和回复最好采用异步的方式进行）。

解决方案：消息去重 + 异步处理。

import threading
from concurrent.futures import ThreadPoolExecutor

_executor = ThreadPoolExecutor(max_workers=5)
_processed_ids = set()
_id_lock = threading.Lock()

def process_async(message_id, msg_text):
    # 解析、写入、回复
    pass

def do_p2_im_message_receive_v1(data):
    msg_id = data.event.message.message_id
    with _id_lock:
        if msg_id in _processed_ids:
            return
        _processed_ids.add(msg_id)
    # 立即返回，异步处理
    _executor.submit(process_async, msg_id, msg_text)

4. 接入大模型实现智能解析

使用 硅基流动 平台提供的模型 API（兼容 OpenAI 格式）（可以使用10B以下的免费模型），配合 LangChain 1.x 实现自然语言到结构化数据的转换。API_KEY最好在环境变量中配置。

4.1 安装依赖

pip install langchain langchain-openai python-dotenv

4.2 定义输出模型

from pydantic import BaseModel, Field

class BillInfo(BaseModel):
    amount: float = Field(description="消费金额（元）")
    account: str = Field(default="微信", description="支付账户：微信/支付宝/现金")
    category: str = Field(description="分类：餐饮/交通/购物/娱乐/医疗")
    note: str = Field(description="消费描述")

4.3 初始化模型并创建 Agent

from langchain.chat_models import init_chat_model
from langchain.agents import create_agent

model = init_chat_model(
    model="Qwen/Qwen3-8B",
    model_provider="openai",
    base_url="https://api.siliconflow.cn/v1",
    api_key=os.getenv("SILICON_API_KEY"),
    temperature=0.7  # 通用值,
)
agent = create_agent(model=model, response_format=BillInfo)

4.4 解析函数

def parse_message(message: str):
    res = agent.invoke({"messages": [{"role": "user", "content": message}]})
    bill = res["structured_response"]
    return bill.amount, bill.account, bill.category, bill.note

4.5 系统提示词优化

为了提高分类准确率，可以给 Agent 添加系统提示词：

SYSTEM_PROMPT = """
你是一个记账助手，从用户输入中提取：金额、账户（微信/支付宝/现金）、分类（餐饮/交通/购物/娱乐/医疗）、备注。
- 默认账户为微信
- 金额必须为正数
- 严格按照 JSON 输出，不要解释
"""
agent = create_agent(model=model, response_format=BillInfo, system_prompt=SYSTEM_PROMPT)

5. 阿里云 ECS 部署

想要一直使用飞书记账助手，服务端代码就得一直开启，因此需要一个云服务器，阿里云esc对于大学生和新用户有福利，99元一年，性价比非常高！

5.1 服务器配置

• 镜像：Alibaba Cloud Linux 3（基础版）
• 规格：2核2G
• 安全组：放行 22 端口（SSH）（一般系统自动配置放行了）

5.2 安装必要软件

# 更新系统
sudo dnf update -y

# 安装 Python 3.11（注意：基础版默认源无 3.12，3.11 够用）
sudo yum install -y python3.11 python3.11-pip

# 安装 Git
sudo yum install -y git

# 安装 Docker（可选，后续容器化）
sudo dnf install -y dnf-plugins-core
sudo dnf config-manager --add-repo=https://mirrors.aliyun.com/docker-ce/linux/centos/docker-ce.repo
sudo dnf install -y docker-ce docker-ce-cli containerd.io
sudo systemctl start docker

5.3 拉取代码并配置虚拟环境

git clone <你的仓库URL> ~/feishu-assistant
cd ~/feishu-assistant
python3.11 -m venv venv
source venv/bin/activate
pip install -r requirements.txt

5.4 设置环境变量

# 方式一：写入 .env 文件（推荐）
cat > .env <<EOF
SILICON_API_KEY=sk-xxx
FEISHU_APP_ID=cli_xxx
FEISHU_APP_SECRET=xxx
EOF

# 方式二：全局环境变量
echo "export SILICON_API_KEY='sk-xxx'" >> ~/.bashrc
source ~/.bashrc

5.5 使用 systemd 实现后台运行

创建服务文件 /etc/systemd/system/feishu-bot.service：

[Unit]
Description=Feishu Bot
After=network.target

[Service]
User=root
WorkingDirectory=/root/feishu-assistant
ExecStart=/root/feishu-assistant/venv/bin/python /root/feishu-assistant/bot.py
Restart=always
RestartSec=10

[Install]
WantedBy=multi-user.target

启动服务：

sudo systemctl daemon-reload
sudo systemctl start feishu-bot
sudo systemctl enable feishu-bot
sudo systemctl status feishu-bot

6. 测试与验证

发送消息给飞书机器人，例如：

• 打车28
• 中午吃肯德基花35.5，支付宝给的
• 买书 49

机器人应回复记账成功😄，并可在多维表格中看到新增记录，消费时间由表格自动填充。

7. 踩坑记录与解决方案😭

问题	解决方案
python3.12 无法通过 yum 安装	改用 python3.11 或源码编译
飞书消息重复写入	实现消息 ID 去重 + 异步处理
多维表格写入失败 1254041	table_id 错误，注意 URL 中 table= 后面的部分
日期字段写入失败	飞书的日期格式有所不同，建议表格字段设置默认值，代码中不传递该字段
LangChain 版本不兼容	统一使用 langchain>=1.0 和 langchain-openai>=1.0

8. 完整代码仓库

所有代码已整理至 GitHub：feishu-account-bot（示例链接）

笔者后续还将尝试接入微信的API，试试能不能用微信进行记账（更贴近生活），待笔者研究一下，好消息马上就来！💪