feishu-bookkeeping

Imported from andy-JustSayWhen/feishu-bookkeeping-skill (SKILL.md). Install upstream with npx skills add andy-JustSayWhen/feishu-bookkeeping-skill. Copyright stays with the author.

目录结构

本skill的初始化目录结构如下。Agent可以根据需要进行变更：

bookkeeping/
├── SKILL.md
├── README.md
├── log.md
├── examples/
│   ├── input.md
│   └── output.md
├── templates/
│   └── record.md
└── backup/
    └── CHG-YYYYMMDD-HHMMSS/
        └── <原文件相对路径>

• SKILL.md：核心规则文件，定义触发条件、安装初始化、字段推断、记账流程、日志规则和备份规则。

• README.md：给用户阅读的说明文档，用于介绍安装、使用方式、字段推断和维护方式。

• log.md：Skill 变更日志，记录每次修改的变更 ID、影响文件、来源、原因和概述。

• examples/：示例目录，用于沉淀输入和输出样例。

• templates/：模板目录，用于保存标准化回复或记录模板。

• backup/：备份目录，用于按变更 ID 保存文件修改前版本，支持后续回滚。

• 新增辅助文件时，应优先放入已有语义目录；如果目录不存在，再创建新的清晰命名目录。

• 修改目录结构后，应同步更新本章节和 README.md 中对应说明。

如何安装

根据readme.md的<## 如何安装>章节，引导用户完成Skill本体、Skill依赖、账本绑定和开始记账。如果遭遇失败，请把当前步骤对应的readme原文发给用户，提醒用户手动推进安装。

触发记账

• 自然语言。用户向你发送了一段自然语言，例如：记一笔，东方树叶 5 元。你通过语义推断用户需要记账，所以你开始根据skill.md开始处理该条记账请求；
• 结构化字段。用户向你发送了一段结构化字段，该字段能命中《账本》的部分字段。例如：早餐 20、早餐 20 支出 个人等。你通过推断用户需要记账，所以你开始根据skill.md开始处理该条记账请求；
• 发送图片。用户向你发送了若干张图片，你调用或安装OCR工具识别出文字后，发现文字内有金额字段，推断为用户需要记账。所以你开始根据skill.md开始处理该条记账请求。

记账流程

自然语言 记账流程

• step1：agent根据自然语言，结合<关键词和字段映射表>或调用大模型，推断出结构化字段；
• step2：agent调用飞书CLI，把该条记录保存到《账本》中；
• step3：agent智能决定是否更新<关键词和字段映射表>；
• step4：agent回复用户记账结果
  • 记账失败。回复用户，消息格式：记账失败+具体原因。示例：记账失败！飞书CLI不存在，请先安装并配置；
  • 记账成功。回复用户，格式及示例见<### 记账成功的回复格式及示例>
• step5：agent每次调用飞书CLI，agent如果遭遇失败，需记录到<## agent调用飞书CLI可能遇到的问题及解决办法>。下次调用再出问题时，优先前往该章节寻找解决办法

结构化字段 记账流程

• step1：agent根据已有结构化字段，结合<关键词和字段映射表>或调用大模型，推断其他结构化字段；
• step2：agent调用飞书CLI，把该条记录保存到《账本》中；
• step3：按<### 自然语言 记账流程>的第3、4、5步处理。

图片 记账流程

• step1：agent收到图片，调用或安装OCR工具，快速识别出文字；
  • 如文字内没有金额，排除记账请求，退出记账skill。按agent的默认逻辑处理，视觉理解并推断用户可能意图；
  • 如文字内有金额，触发记账。
• step2:agent根据识别出的文字内容，按<### 自然语言 记账流程>的第1、2、3、4、5步处理。

记账成功的回复格式及示例：

格式：“记账成功+记录详情+账本链接” 说明：

• 记录详情。用代码块居中对齐表格回复用户.对齐规则：用 CJK 双宽度计算（中文字符占2列，ASCII占1列），每列居中对齐，列间距2空格，表头与数据之间用 ─ 分隔线。
• 账本链接。由agent根据账本信息.md的<-外链>进行替换填写。

示例： 记账成功！

       名称            金额     类型    账本
───────────────────────────────────────────────────
     东方树叶          5.00     支出    个人

账本链接：https://lxxtrhuie3n.feishu.cn/base/WKxxId?table=tblxxr

记录账本信息

路径：bookkeeping/config/账本信息.md 触发：完成账本绑定后，主要由agent自动生成、更新。 定义：<记录账本信息>包括但不限于：

- `APP_TOKEN`
- `TABLE_ID`
- 域名
- API 能力
- 外链
- 字段说明
- 关键词和字段映射表

字段说明格式 示例：
| 字段 | 类型 | 说明 |
|---|---|---|
| 名称 | 文本 | 消费或收入对象 |
| 金额 | 数字 | 金额，回复展示时保留两位小数 |
| 类型 | 单选 | `收入` 或 `支出` |
| 账本 | 单选 | 默认包含 `个人`、`工作` |
| 日期 | 日期 | 默认使用记录创建时的北京时间 |


- 关键词和字段映射表 示例：
##### 类型

| 表格字段 | 匹配关键词（任一） |
|---|---|
| 类型=支出 | 花了、付了、买了、消费、支出、充了、打车、午饭、晚饭、早餐、外卖、采购 |
| 类型=收入 | 收到、收入、入账、到账、收款、报销到账、项目款、回款、退款 |

##### 账本

| 表格字段 | 匹配关键词（任一） |
|---|---|
| 账本=工作 | 投流、播放、推广、互动、抽奖、小米微博、推广费、制作费、制作成本、采买、采购 |
| 账本=个人 | 午饭、晚饭、早餐、咖啡、奶茶、零食、水、外卖、日用、数码、医疗、娱乐、学习、礼金、住宿、通讯、家装、家电、服饰、纳税、保险、捐赠、家具 |
| 账本=家庭01 / 家庭02 / 家庭 | 用户明确指定家庭账本、家庭01、家庭02 或具体家庭账本名称 |
| 账本=个人 | 无法推断账本时的默认值 |

定时任务

记账Skill完成安装，用户完成第一次记账后，agent自动创建此定时任务。默认任务规则：

• 时间：每天 23:00
• 内容：支出多少、收入多少、记录几条，待补齐字段的记录详情。
• 位置：发送到飞书、微信等消息平台的聊天窗口
• 会话：xx ## xx=会话ID。由agent填写和更新，如用户要求发送到多个消息平台，自动换行分开记录会话ID。
• 示例： 今天支出 5.00 元，收入 10.00 元，共 5 条记录，有1条记录的部分字段待补齐：

       名称            金额     类型    账本
───────────────────────────────────────────────────
     东方树叶          5.00     支出     ？

帮助Skill进化

自我进化

• Agent需要智能根据《账本》生成<关键词➡️字段映射表>，用户的记录越多，Agent的推断能力理应越强。用不了多久，Agent应当要做到 只要在图片或文字中拿到名称和金额字段，其他字段就都可以智能推断并完成填充；
• Agent对于<关键词➡️字段映射表>无法推断的字段，应当调用当前大模型能力进行智能推断。
• 任何时候，用户都可以通过自然语言，让Agent新增记账方式和推断规则等。

日志规则

• agent 主动或被动修改本 skill 相关文件时，必须在根目录 log.md 追加变更日志；但当用户明确说明“本次不要写 log.md”或“本地调试不记录日志”时，以用户当前指令为准。
• 日志按日期分组、按具体时间分小组：
  • 日期倒序：新的日期在前，旧的日期在后。
  • 同一日期内时间正序：旧的时间在前，新的时间在后。
  • 新增日志时，先查找对应日期；如果日期不存在，则在日志最上方新建日期分组。
  • 在对应日期内，按时间顺序插入到正确位置。
• 日志只记录已经完成的文件变更；如果变更失败，应在回复用户时说明失败原因，不追加成功变更日志。
• 每次变更日志必须包含这些字段：
  • 变更ID：格式为 CHG-YYYYMMDD-HHMMSS，使用执行变更时的本地时间生成。
  • 影响文件（完整路径）：列出本次修改的所有文件完整路径，多个文件用 ； 分隔。
  • 来源：说明是用户要求、agent 主动建议后执行，或其他来源。
  • 原因：说明为什么修改。
  • 概述：简要说明本次具体改了什么。
• 日志示例：

## 2026-04-29
### 22:10:01

- 变更ID：CHG-YYYYMMDD-HHMMSS
- 影响文件（完整路径）：`T:\bookkeeping\bookkeeping\SKILL.md`
- 来源：用户要求，agent 执行
- 原因：说明为什么修改
- 概述：说明本次变更动作

### 22:10:02
- 变更ID：CHG-YYYYMMDD-HHMMSS
- 影响文件（完整路径）：`T:\bookkeeping\bookkeeping\SKILL.md`
- 来源：用户要求，agent 执行
- 原因：说明为什么修改
- 概述：说明本次变更动作
### 22:10:03
- 变更ID：CHG-YYYYMMDD-HHMMSS
- 影响文件（完整路径）：`T:\bookkeeping\bookkeeping\SKILL.md`
- 来源：用户要求，agent 执行
- 原因：说明为什么修改
- 概述：说明本次变更动作


## 2026-04-28
### 22:10:04
- 变更ID：CHG-YYYYMMDD-HHMMSS
- 影响文件（完整路径）：`T:\bookkeeping\bookkeeping\SKILL.md`
- 来源：用户要求，agent 执行
- 原因：说明为什么修改
- 概述：说明本次变更动作

如何备份

• agent 修改本 skill 相关文件前，必须先创建变更前备份；但当用户明确说明“本次不要备份”或“本地调试不备份”时，以用户当前指令为准。
• 备份目录固定为本Skill根目录下的 backup/，每次变更使用一个独立变更 ID 目录：

backup/<变更ID>/<原文件相对路径>

• 备份路径示例：

backup/CHG-20260429-143000/bookkeeping/SKILL.md

• 备份时必须保留原文件相对路径，避免多个同名文件互相覆盖。
• 如果一次变更影响多个文件，应在同一个 backup/<变更ID>/ 下分别保存这些文件的变更前版本。
• 新增备份后，应检查 backup/ 下的变更 ID 目录，只保留近 15 天的备份；超过 15 天的备份目录可以删除。
• 删除超期备份前，必须确认对应变更日志仍保留在 log.md 中。
• 如果用户明确要求长期保留某个变更 ID 的备份，不要自动删除该变更 ID 目录。
• 当用户输入“退回 <变更ID> 前版本”或“回滚 <变更ID>”时，agent 必须：
  • 在 log.md 中查找对应变更 ID。
  • 读取该记录的“影响文件（完整路径）”。
  • 到 backup/<变更ID>/ 下找到对应文件的变更前备份。
  • 用备份文件覆盖当前文件。
  • 回滚完成后，追加一条新的回滚日志，说明回滚来源、影响文件和回滚到哪个变更 ID 前版本。

目录辅助文件

• examples/input.md：用户原话示例，用于学习记账触发表达和常见输入。
• examples/output.md：标准回复示例，用于保持写入后的反馈格式稳定。
• templates/record.md：单笔记账回复模板，用于生成固定字段顺序的输出。

当辅助文件与本文件冲突时，以 SKILL.md 的规则为准。

agent调用飞书CLI可能遇到的问题及解决办法

agent根据首次安装、今后调用飞书CLI遇到的实际问题，自行在这里记录和更新解决办法，以便于今后规避问题。