名称： timesheet
描述： 使用 timesheet.io CLI 追踪时间、管理项目与任务
user-invocable: true
主页： https://timesheet.io
元数据： {"requires": {"bins": ["timesheet"]}}

Timesheet CLI 技能

通过命令行控制 timesheet.io 的时间追踪。所有命令均可使用 --json 标志获取结构化输出。

身份验证

使用其他命令前，请先检查认证状态：

timesheet auth status --json

如果未认证，请引导用户运行：

timesheet auth login

或为自动化设置 API 密钥：

export TIMESHEET_API_KEY=ts_your.apikey

计时器操作

启动计时器

# 首先列出项目以获取项目 ID
timesheet projects list --json

# 为项目启动计时器
timesheet timer start <项目-id>

检查计时器状态

timesheet timer status --json

返回：状态（运行中/已暂停/已停止）、项目名称、持续时间、开始时间。

控制计时器

timesheet timer pause
timesheet timer resume
timesheet timer stop  # 从计时器创建任务

更新运行中的计时器

timesheet timer update --description "正在处理功能 X"
timesheet timer update --billable

项目管理

列出项目

timesheet projects list --json

创建项目

timesheet projects create "项目名称" --json
timesheet projects create "客户项目" --billable --json

查看/更新/删除

timesheet projects show <id> --json
timesheet projects update <id> --title "新名称"
timesheet projects delete <id>

任务管理

列出任务

timesheet tasks list --json           # 近期任务
timesheet tasks list --today --json   # 今日任务
timesheet tasks list --this-week --json

手动创建任务

timesheet tasks create -p <项目-id> -s "2024-01-15 09:00" -e "2024-01-15 17:00" --json
timesheet tasks create -p <项目-id> -s "09:00" -e "17:00" -d "任务描述" --json

更新任务

timesheet tasks update <id> --description "更新后的描述"
timesheet tasks update <id> --billable
timesheet tasks update <id> --start "10:00" --end "12:00"

删除任务

timesheet tasks delete <id>

团队与标签

团队

timesheet teams list --json

标签

timesheet tags list --json
timesheet tags create "紧急" --color 1
timesheet tags delete <id>

报告

时间摘要

timesheet reports summary --today --json
timesheet reports summary --this-week --json
timesheet reports summary --this-month --json
timesheet reports summary --from 2024-01-01 --to 2024-01-31 --json

导出数据

timesheet reports export -f xlsx -s 2024-01-01 -e 2024-01-31
timesheet reports export -f csv --this-month

个人资料与配置

timesheet profile show --json
timesheet profile settings --json

timesheet config show
timesheet config set defaultProjectId <id>

常用工作流

记录当前工作时间

1. 检查计时器是否运行：timesheet timer status --json
2. 若未运行，启动计时器：timesheet timer start <项目-id>
3. 完成后，停止计时器：timesheet timer stop

快速时间录入

# 直接创建一个已完成的任务
timesheet tasks create -p <项目-id> -s "09:00" -e "12:00" -d "早站会与开发工作" --json

按名称查找项目

timesheet projects list --json | jq '.[] | select(.title | contains("项目名称"))'

错误处理

退出代码：
- 0: 成功
- 1: 一般错误
- 2: 用法错误（参数无效）
- 3: 认证错误 - 请运行 timesheet auth login
- 4: API 错误
- 5: 超出速率限制 - 请等待后重试
- 6: 网络错误

提示

• 程序化解析输出时，始终使用 --json
• 使用 --quiet 或 -q 抑制非必要输出
• 在配置中设置 defaultProjectId 以跳过计时器的项目选择
• 非终端环境下自动提供管道友好输出