habits

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

每日打卡技能

Daily Check-in Skill

基于本地 SQLite 数据库记录和管理每日打卡数据。数据文件由脚本通过

import.meta.dirname

自动定位，存放在与 skill 目录同级的

.data/zsspub/habits/

目录下，无需手动配置路径。时间以 UTC 存入数据库，展示时自动按用户配置的时区进行转换。

Record and manage daily check-in data based on local SQLite database. The data file is automatically located by the script through

import.meta.dirname

, stored in the

.data/zsspub/habits/

directory at the same level as the skill directory, no manual path configuration is required. Time is stored in the database in UTC, and will be automatically converted according to the user-configured time zone when displayed.

环境要求

Environment Requirements

Node.js >= 22.5.0（使用内置
```
node:sqlite
```
）

Node.js >= 22.5.0 (uses built-in
```
node:sqlite
```
)

执行方式

Execution Method

所有命令均通过

node

直接运行脚本：

bash

node <本 SKILL.md 所在目录>/scripts/habits.mjs <命令> [选项]

下文中

habits

均代表

node <skill目录>/scripts/habits.mjs

，请替换为实际路径。

All commands are run directly through

node

bash

node <directory where this SKILL.md is located>/scripts/habits.mjs <command> [options]

In the following content,

habits

refers to

node <skill directory>/scripts/habits.mjs

, please replace it with the actual path.

首次使用：配置时区

First Time Use: Configure Time Zone

脚本将时间以 UTC 存入数据库，展示时按用户配置的时区转换。首次使用时，请先判断用户的时区并运行

config --timezone

命令：

若用户提到城市（如"我在上海"），推断为
```
Asia/Shanghai
```
若无法判断，询问用户所在城市或时区，然后运行：

bash

habits config --timezone=Asia/Shanghai

The script stores time in UTC in the database, and converts it according to the user-configured time zone when displaying. When using for the first time, please first determine the user's time zone and run the

config --timezone

command:

If the user mentions a city (e.g. "I am in Shanghai"), infer it as
```
Asia/Shanghai
```
If it cannot be determined, ask the user for their city or time zone, then run:

bash

habits config --timezone=Asia/Shanghai

使用流程

Usage Process

第一步：理解用户意图，映射到命令

Step 1: Understand user intent and map to commands

打卡的核心是从用户自然语言中提取结构化信息：

用户说的话（示例）	提取信息	应执行的命令
"打卡骑行 30 分钟"	主题=骑行, 标签=运动, 时长=30	`add` （同时用 `--raw` 存储原话）
"今天读了一章《原则》"	主题=阅读, 标签=学习, 备注=《原则》一章	`add`
"刚跑完步 5 公里 40 分钟"	主题=跑步, 标签=运动, 时长=40, 备注=5公里	`add`
"冥想打卡"	主题=冥想, 标签=健康	`add` （无时长）
"打卡故宫"	主题=旅行, 标签=生活, 备注=故宫	`add`
"看看我这个月的打卡记录"	—	`list --period=month`
"这周运动了多少时间？"	—	`stats --period=week --tag=运动`
"骑行连续打卡多少天了？"	—	`streak --topic=骑行`
"把第3条打卡改成45分钟"	—	`update 3 --duration=45`
"删掉那条跑步记录"	—	先 `list` 找到 id，再 `delete <id>`
"导出打卡记录" / "备份打卡数据"	—	`export`
"导入打卡记录" / "从文件恢复"	—	`import --file=<路径>`

原话保存： 每次

add

打卡时，将用户说的原始文字通过

--raw

参数原封不动地存储下来，方便日后回溯。

备注提取规则：

--note

用于保存无法归入其他字段的关键信息。例如：

地点信息：城市、景点、餐厅名（“打卡故宫” → 备注=故宫）
具体内容：书名、课程名、食物名称（“读了《原则》第三章” → 备注=《原则》第三章）
量化指标：距离、组数、页数等时长以外的数值（“跑了5公里” → 备注=5公里）

标签自动推断规则：

根据主题自动推断标签，用户可以用

--tags

覆盖：

主题关键词	推断标签
骑行、跑步、游泳、健身、瑜伽、拉伸、健走、跳绳、打球、登山、滑雪、滑冰	运动
阅读、读书、看书、听书	学习
冒想、早睡、早起、喝水、护肤	健康
背单词、刷题、练琴、画画、写作、练字、学英语	学习
做饭、家务、整理、美食、在家练习	生活
旅行、参观、游览、打卡景点	生活
看电影、追剧、听音乐、玩游戏	娱乐

如果主题不在上述列表中，请根据语义合理推断。打卡总应当有标签，方便后续统计筛选。

时长推断规则：

"X 分钟" →
```
--duration=X
```
"X 小时" →
```
--duration=X*60
```
"X 小时 Y 分钟" →
```
--duration=X*60+Y
```
"半小时" →
```
--duration=30
```
"X个半小时" / "X小时半" →
```
--duration=X*90
```
"一个半小时" →
```
--duration=90
```
"一刻钟" / "15分钟" →
```
--duration=15
```
没有提到时长则不传
```
--duration
```

The core of check-in is to extract structured information from the user's natural language:

User's words (example)	Extracted information	Command to execute
"Check in cycling for 30 minutes"	Topic=cycling, Tag=sports, Duration=30	`add` (also use `--raw` to store the original words)
"I read a chapter of Principles today"	Topic=reading, Tag=learning, Note=one chapter of Principles	`add`
"Just finished running 5 kilometers in 40 minutes"	Topic=running, Tag=sports, Duration=40, Note=5km	`add`
"Meditation check-in"	Topic=meditation, Tag=health	`add` (no duration)
"Check in at the Forbidden City"	Topic=travel, Tag=life, Note=Forbidden City	`add`
"Show my check-in records this month"	—	`list --period=month`
"How much time did I spend exercising this week?"	—	`stats --period=week --tag=sports`
"How many consecutive days have I checked in for cycling?"	—	`streak --topic=cycling`
"Change the 3rd check-in to 45 minutes"	—	`update 3 --duration=45`
"Delete that running record"	—	First run `list` to find the id, then run `delete <id>`
"Export check-in records" / "Backup check-in data"	—	`export`
"Import check-in records" / "Restore from file"	—	`import --file=<path>`

Original text saving: Every time you run

add

to record a check-in, store the original text of the user's words as-is through the

--raw

parameter for future review.

Note extraction rules:

--note

is used to save key information that cannot be classified into other fields. For example:

Location information: city, scenic spot, restaurant name ("Check in at the Forbidden City" → Note=Forbidden City)
Specific content: book name, course name, food name ("Read Chapter 3 of Principles" → Note=Chapter 3 of Principles)
Quantitative indicators: distance, number of sets, pages and other values other than duration ("Ran 5 kilometers" → Note=5km)

Automatic tag inference rules:

Infer tags automatically based on the topic, users can override with

--tags

Topic keywords	Inferred tag
Cycling, running, swimming, fitness, yoga, stretching, brisk walking, rope skipping, ball games, mountain climbing, skiing, skating	Sports
Reading, book reading, listening to audiobooks	Learning
Meditation, early bedtime, early rising, drinking water, skincare	Health
Memorizing words, doing exercises, practicing piano, painting, writing, calligraphy practice, learning English	Learning
Cooking, housework, organizing, food, home practice	Life
Travel, visiting, sightseeing, scenic spot check-in	Life
Watching movies, chasing dramas, listening to music, playing games	Entertainment

If the topic is not in the above list, please infer reasonably according to the semantics. Check-in records should always have tags to facilitate subsequent statistics and filtering.

Duration inference rules:

"X minutes" →
```
--duration=X
```
"X hours" →
```
--duration=X*60
```
"X hours Y minutes" →
```
--duration=X*60+Y
```
"Half an hour" →
```
--duration=30
```
"X and a half hours" →
```
--duration=X*60+30
```
"One and a half hours" →
```
--duration=90
```
"A quarter of an hour" / "15 minutes" →
```
--duration=15
```
Do not pass
```
--duration
```
if no duration is mentioned

第二步：执行命令并呈现结果

Step 2: Execute the command and present the result

将命令输出直接展示给用户。打卡成功后，可以给一句简短的鼓励。

Display the command output directly to the user. After a successful check-in, you can give a short encouragement.

命令说明

Command Description

添加打卡

Add check-in

habits add "主题" --raw="用户原话" [--tags=标签1,标签2] [--duration=分钟数] [--note="备注"] [--at="YYYY-MM-DD HH:mm:ss"]

```
--raw
```
：必填，用户说的原话，原封不动存储
```
--tags
```
：逗号分隔的标签列表，例如
```
运动,户外
```
```
--duration
```
：时长（分钟），正整数
```
--note
```
：备注文本
```
--at
```
：打卡时间（用户本地时区），默认当前时间。用于补打卡场景

habits add "topic" --raw="user's original words" [--tags=tag1,tag2] [--duration=minutes] [--note="note"] [--at="YYYY-MM-DD HH:mm:ss"]

```
--raw
```
: Required, the original words of the user, stored as-is
```
--tags
```
: Comma-separated list of tags, e.g.
```
运动,户外
```
```
--duration
```
: Duration (minutes), positive integer
```
--note
```
: Note text
```
--at
```
: Check-in time (user's local time zone), default is current time. Used for retroactive check-in scenarios

查看打卡记录

View check-in records

habits list [--topic=主题] [--tag=标签] [--date=YYYY-MM-DD] [--period=today|week|month|year] [--from="YYYY-MM-DD HH:mm:ss"] [--to="YYYY-MM-DD HH:mm:ss"] [--search=关键字] [--limit=数量]

```
--period
```
：快捷时间范围（today/week/month/year）
```
--date
```
：查看某天的所有打卡
```
--from
```
/
```
--to
```
：时间范围筛选
```
--search
```
：按主题和备注模糊搜索
```
--limit
```
：限制返回条数
默认按时间倒序

habits list [--topic=topic] [--tag=tag] [--date=YYYY-MM-DD] [--period=today|week|month|year] [--from="YYYY-MM-DD HH:mm:ss"] [--to="YYYY-MM-DD HH:mm:ss"] [--search=keyword] [--limit=count]

```
--period
```
: Quick time range (today/week/month/year)
```
--date
```
: View all check-ins on a certain day
```
--from
```
/
```
--to
```
: Time range filtering
```
--search
```
: Fuzzy search by topic and note
```
--limit
```
: Limit the number of returned records
Default sorted in reverse chronological order

修改打卡

Modify check-in

habits update <id> [--topic=...] [--tags=...] [--duration=...] [--note=...] [--at="YYYY-MM-DD HH:mm:ss"]

清除时长：
```
--duration=null
```

别名：

edit

habits update <id> [--topic=...] [--tags=...] [--duration=...] [--note=...] [--at="YYYY-MM-DD HH:mm:ss"]

Clear duration:
```
--duration=null
```

Alias:

edit

删除打卡

Delete check-in

habits delete <id>

别名：

del

、

rm

habits delete <id>

Aliases:

del

rm

统计分析

Statistical analysis

habits stats [--topic=主题] [--tag=标签] [--period=today|week|month|year] [--from="YYYY-MM-DD HH:mm:ss"] [--to="YYYY-MM-DD HH:mm:ss"]

```
--period
```
：快捷时间范围（today/week/month/year）
输出：总打卡次数、总时长、按主题统计、按标签统计

habits stats [--topic=topic] [--tag=tag] [--period=today|week|month|year] [--from="YYYY-MM-DD HH:mm:ss"] [--to="YYYY-MM-DD HH:mm:ss"]

```
--period
```
: Quick time range (today/week/month/year)
Output: total check-in times, total duration, statistics by topic, statistics by tag

连续打卡

Consecutive check-in query

habits streak [--topic=主题] [--tag=标签]

输出：当前连续天数、最长连续天数、累计打卡天数

habits streak [--topic=topic] [--tag=tag]

Output: current consecutive days, longest consecutive days, total check-in days

查看/更新配置

View/update configuration

habits config [--timezone=<IANA时区>]

habits config [--timezone=<IANA time zone>]

导出打卡记录

Export check-in records

habits export [--file=<路径>] [--topic=主题] [--tag=标签]

导出为 CSV 格式
```
--file
```
：指定输出文件路径，不指定则自动生成到数据目录
```
--topic
```
/
```
--tag
```
：可选筛选条件

habits export [--file=<path>] [--topic=topic] [--tag=tag]

Export to CSV format
```
--file
```
: Specify the output file path, if not specified, it will be automatically generated to the data directory
```
--topic
```
/
```
--tag
```
: Optional filtering conditions

导入打卡记录

Import check-in records

habits import --file=<路径>

从 CSV 文件导入，CSV 必须包含
```
topic
```
列
导入前会校验数据格式，校验失败则取消导入

habits import --file=<path>

Import from CSV file, CSV must contain
```
topic
```
column
Data format will be verified before import, import will be canceled if verification fails

示例

Examples

bash

undefined

bash

undefined

打卡骑行 30 分钟

Check in cycling for 30 minutes

habits add "骑行" --tags=运动 --duration=30 --raw="打卡骑行 30 分钟"

打卡阅读，带备注

Check in reading, with note

habits add "阅读" --tags=学习 --note="《原则》第三章"

补打卡（昨天的跑步）

Retroactive check-in (yesterday's run)

habits add "跑步" --tags=运动 --duration=40 --note="5公里" --at="2026-04-01 19:30:00"

查看今天的打卡

View today's check-ins

habits list --date=2026-04-02

查看所有骑行记录

View all cycling records

habits list --topic=骑行

本周运动统计

Weekly exercise statistics

habits stats --period=week --tag=运动

查看骑行连续打卡天数

View consecutive cycling check-in days

habits streak --topic=骑行

修改第 2 条打卡的时长

Modify the duration of the 2nd check-in

habits update 2 --duration=45

删除第 5 条打卡

Delete the 5th check-in

habits delete 5

undefined

habits delete 5

undefined