Toggl时间追踪

技能简介

通过命令行界面直接操作Toggl Track，实现计时启停、报告查看与条目管理，无需打开浏览器即可完成日常时间记录工作。

业务背景

开发人员与运维人员无需切换浏览器即可快速记录工时，减少上下文中断。命令行操作适合高频使用场景，提升时间记录的及时性与准确性，便于后续项目成本核算与工作效率分析。

落地案例：某后端工程师开始处理客户Bug修复，在终端输入`toggl start "修复支付接口异常 – 客户A"`立即启动计时；中途被会议打断时执行`toggl stop`，会后通过`toggl continue`恢复。每日下班前运行`toggl today`查看当日各项目耗时分布，周末用`toggl list –from 2024-01-01 –to 2024-01-07`导出周报数据。

能做什么

• 启动或停止计时器，支持交互式或带描述/项目的快速开始
• 查看当前运行中的计时状态与今日/本周时间汇总
• 继续之前的计时条目，支持关键词匹配
• 浏览最近14天的时间记录，支持按日期范围筛选与搜索
• 手动补录已完成的时间段，修改进行中的条目信息
• 删除指定条目，管理项目列表

使用说明

安装步骤

1. 全局安装CLI工具：npm install -g @beauraines/toggl-cli
2. 获取API令牌：访问 https://track.toggl.com/profile 复制个人API token
3. 获取工作区ID：从Toggl网址 https://track.toggl.com/{workspace_id}/... 中提取数字
4. 创建配置文件 ~/.toggl-cli.json：

   {"api_token": "YOUR_TOGGL_API_TOKEN", "default_workspace_id": "YOUR_WORKSPACE_ID", "timezone": "Asia/Shanghai"}

5. 设置文件权限：chmod 600 ~/.toggl-cli.json

常用操作

• 查看当前计时：toggl now
• 快速开始计时：toggl start -d "客户会议" -p "项目名称"
• 停止计时：toggl stop
• 今日汇总：toggl today
• 继续上一条：toggl continue

输入与输出

见下方输入与输出表格。

风险提示

• API令牌存储于本地配置文件，需确保文件权限为600防止泄露
• 环境变量可覆盖配置，多用户共享服务器时需注意隔离
• 时间格式依赖dayjs解析，建议使用标准格式如9:00AM或14:30
• 删除操作不可逆，执行toggl rm前请确认条目ID

来源信息

原始链接：https://github.com/openclaw/skills/tree/main/skills/clvrobj/toggl/SKILL.md
来源类型：GitHub仓库