Timesheet - Time Tracking

# Timesheet CLI Skill

从命令行控制 timesheet.io 时间跟踪。对所有命令使用 `--json` 标志以获取结构化输出。

## 身份验证

在使用其他命令之前检查身份验证状态： ```bash timesheet auth status --json ```

如果未通过身份验证，引导用户运行： ```bash timesheet auth login ```

或者，为了自动化，设置一个 API 密钥： ```bash export TIMESHEET_API_KEY=ts_your.apikey ```

## 计时器操作

### 启动计时器 ```bash # List projects first to get project ID timesheet projects list --json

# Start timer for a project timesheet timer start <project-id> ```

### 检查计时器状态 ```bash timesheet timer status --json ```

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

### 控制计时器 ```bash timesheet timer pause timesheet timer resume timesheet timer stop # Creates a task from the timer ```

### 更新正在运行的计时器 ```bash timesheet timer update --description "Working on feature X" timesheet timer update --billable ```

## 项目管理

### 列出项目 ```bash timesheet projects list --json ```

### 创建项目 ```bash timesheet projects create "Project Name" --json timesheet projects create "Client Project" --billable --json ```

### 显示/更新/删除 ```bash timesheet projects show <id> --json timesheet projects update <id> --title "New Name" timesheet projects delete <id> ```

## 任务管理

### 列出任务 ```bash timesheet tasks list --json # Recent tasks timesheet tasks list --today --json # Today's tasks timesheet tasks list --this-week --json ```

### 手动创建任务 ```bash timesheet tasks create -p <project-id> -s "2024-01-15 09:00" -e "2024-01-15 17:00" --json timesheet tasks create -p <project-id> -s "09:00" -e "17:00" -d "Task description" --json ```

### 更新任务 ```bash timesheet tasks update <id> --description "Updated description" timesheet tasks update <id> --billable timesheet tasks update <id> --start "10:00" --end "12:00" ```

### 删除任务 ```bash timesheet tasks delete <id> ```

## 团队与标签

### 团队 ```bash timesheet teams list --json ```

### 标签 ```bash timesheet tags list --json timesheet tags create "Urgent" --color 1 timesheet tags delete <id> ```

## 报告

### 时间摘要 ```bash 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 ```

### 导出数据 ```bash timesheet reports export -f xlsx -s 2024-01-01 -e 2024-01-31 timesheet reports export -f csv --this-month ```

## 个人资料与配置

```bash 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 <project-id>` 3. 完成后，停止计时器：`timesheet timer stop`

### 快速时间录入 ```bash # Create a completed task directly timesheet tasks create -p <project-id> -s "09:00" -e "12:00" -d "Morning standup and dev work" --json ```

### 按名称查找项目 ```bash timesheet projects list --json | jq '.[] | select(.title | contains("ProjectName"))' ```

## 错误处理

退出代码： - 0：成功 - 1：常规错误 - 2：用法错误（参数无效） - 3：身份验证错误 - 运行 `timesheet auth login` - 4：API 错误 - 5：超过速率限制 - 请等待并重试 - 6：网络错误

## 提示

- 始终使用 `--json` 以编程方式解析输出 - 使用 `--quiet` 或 `-q` 来抑制非必要输出 - 在配置中设置 `defaultProjectId` 以在计时器启动时跳过项目选择 - 当不在终端中时，管道友好的输出是自动的