TimeCamp 技能

两个工具：CLI 用于快速个人操作（计时器、条目增删改查）和数据管道用于分析/报告。

引导（如缺失则克隆）

在使用任一工具前：

1. 1. 询问用户仓库应存放的位置（默认：~/utils，但任何位置均可）。
2. 如果所选位置缺少仓库，请求确认后克隆。

示例流程和命令：

bash

先询问：

本地未找到 TimeCamp 仓库。克隆到 ~/utils，或使用其他位置？

REPOS_DIR=~/utils # 如果用户选择了不同路径则替换
mkdir -p $REPOS_DIR

if [ ! -d $REPOS_DIR/timecamp-cli/.git ]; then
git clone https://github.com/timecamp-org/timecamp-cli.git $REPOS_DIR/timecamp-cli
fi

if [ ! -d $REPOS_DIR/good-enough-timecamp-data-pipeline/.git ]; then
git clone https://github.com/timecamp-org/good-enough-timecamp-data-pipeline.git $REPOS_DIR/good-enough-timecamp-data-pipeline
fi

工具 1：TimeCamp CLI（个人操作）

CLI 位于 ~/utils/timecamp-cli，通过 npm link 全局安装。

意图	命令
当前计时器状态	timecamp status
启动计时器

timecamp start --task 项目A --note 描述 |
| 停止计时器 | timecamp stop |
| 今日条目 | timecamp entries |
| 按日期查询条目 | timecamp entries --date 2026-02-04 |
| 条目日期范围 | timecamp entries --from 2026-02-01 --to 2026-02-04 |
| 所有用户条目 | timecamp entries --from 2026-02-01 --to 2026-02-04 --all-users |
| 添加条目 | timecamp add-entry --date 2026-02-04 --start 09:00 --end 10:30 --duration 5400 --task 项目A --note 描述 |
| 更新条目 | timecamp update-entry --id 101234 --note 已更新 --duration 3600 |
| 删除条目 | timecamp remove-entry --id 101234 |
| 列出任务 | timecamp tasks |

工具 2：数据管道（分析与报告）

Python 管道位于 ~/utils/good-enough-timecamp-data-pipeline。所有分析、报告和批量数据获取均使用此工具。

运行命令

bash
cd ~/utils/good-enough-timecamp-data-pipeline && \
uv run --with-requirements requirements.txt dltfetchtimecamp.py \
--from YYYY-MM-DD --to YYYY-MM-DD \
--datasets DATASETS \
--format jsonl \
--output ~/data/timecamp-data-pipeline

可用数据集

数据集	描述
entries	包含项目/任务详情的时间条目
tasks

项目与任务层级结构，含面包屑路径 | | computer_activities | 桌面应用追踪数据 | | users | 用户详情，含群组信息和启用状态 | | application_names | 应用查找表（ID → 名称、类别） |

格式：jsonl

输出结构

文件存放于 ~/data/timecamp-data-pipeline/timecamp/*.jsonl。

示例

bash
cd ~/utils/good-enough-timecamp-data-pipeline && \
uv run --with-requirements requirements.txt dltfetchtimecamp.py \
--from 2026-02-11 --to 2026-02-14 \
--datasets entries,users,tasks \
--format jsonl --output ~/data/timecamp-data-pipeline

cd ~/utils/good-enough-timecamp-data-pipeline && \
uv run --with-requirements requirements.txt dltfetchtimecamp.py \
--from 2026-01-01 --to 2026-02-14 \
--datasets computeractivities,users,applicationnames \
--format jsonl --output ~/data/timecamp-data-pipeline

cd ~/utils/good-enough-timecamp-data-pipeline && \
uv run --with-requirements requirements.txt dltfetchtimecamp.py \
--from 2026-01-01 --to 2026-02-14 \
--datasets computeractivities,users,applicationnames,entries,tasks \
--format jsonl --output ~/data/timecamp-data-pipeline

使用 DuckDB 进行分析

直接查询持久化数据存储。

bash
DUCKDB=~/.duckdb/cli/latest/duckdb
DATA=~/data/timecamp-data-pipeline/timecamp

每人小时数

$DUCKDB -c SELECT username, round(sum(TRYCAST(duration AS DOUBLE))/3600.0, 1) as hours FROM readjsonauto($DATA/entries*.jsonl) GROUP BY user_name ORDER BY hours DESC

每人每天小时数

$DUCKDB -c SELECT username, date, round(sum(TRYCAST(duration AS DOUBLE))/3600.0, 1) as hours FROM readjsonauto($DATA/entries*.jsonl) GROUP BY username, date ORDER BY username, date

按时间排序的顶级应用（关联活动与应用名称）

$DUCKDB -c SELECT COALESCE(an.fullname, an.applicationname, an.app_name, 未知) as app, round(sum(ca.time_span)/3600.0, 2) as hours FROM readjsonauto($DATA/computer_activities*.jsonl) ca LEFT JOIN readjsonauto($DATA/application_names*.jsonl) an ON ca.applicationid = an.applicationid GROUP BY 1 ORDER BY hours DESC LIMIT 20

某周记录少于 30 小时的人员

$DUCKDB -c SELECT username, round(sum(TRYCAST(duration AS DOUBLE))/3600.0, 1) as hours FROM readjsonauto($DATA/entries*.jsonl) WHERE date BETWEEN 2026-02-03 AND 2026-02-07 GROUP BY user_name HAVING sum(TRY_CAST(duration AS DOUBLE))/3600.0 < 30 ORDER BY hours

模式

1. 1. 使用 DuckDB 检查现有数据范围，如数据缺失则通过管道获取，如已存在则直接使用
2. 使用 DuckDB 查询：$DUCKDB -c SELECT ... FROM readjsonauto($DATA/entries*.jsonl) ...

重要说明

• - 持续时间（条目）以秒为单位（3600 = 1小时）
• timespan（活动）同样以秒为单位
• 管道目录中的 applicationscache.json 缓存应用名称查找结果
• 对于 JSONL 输出，DuckDB 的 *.jsonl 通配符可捕获所有数据集的所有文件

安全

• - 在添加、更新或删除条目前进行确认
• 执行修改前显示命令
• 停止计时器时，先显示正在运行的内容

作者

TimeCamp 时间追踪软件

许可证

MIT