名称： gtasks-cli
描述： 通过命令行管理 Google Tasks - 查看、创建、更新、删除任务和任务列表。当用户要求与 Google Tasks 交互、管理待办事项、创建任务列表、标记任务完成或查看其 Google Tasks 时使用。
许可证： MIT
compatibility: 需要安装并认证 gtasks CLI 工具
元数据：
author: BRO3886
version: "1.0"
允许工具： Bash(gtasks:*)

Google Tasks CLI 技能

本技能使您能够使用 gtasks CLI 工具直接从命令行管理 Google Tasks。

前提条件

在使用任何命令之前，请确保满足以下要求：

1. 安装 GTasks

检查系统上是否已安装 gtasks：

# 跨平台检查（适用于 macOS、Linux、Windows Git Bash）
gtasks --version 2>/dev/null || gtasks.exe --version 2>/dev/null || echo "未找到 gtasks"

# 或使用 which/where 命令
# macOS/Linux：
which gtasks

# Windows (命令提示符)：
where gtasks

# Windows (PowerShell)：
Get-Command gtasks

如果未安装 gtasks：

1. 从 GitHub Releases 下载适用于您系统的二进制文件。
2. 安装它：
   • macOS/Linux：移动到 /usr/local/bin 或添加到 PATH 中。
   • Windows：添加到 PATH 环境变量中的文件夹。
3. 验证安装：gtasks --version

重要提示（对于代理）： 在使用 gtasks 之前，务必检查其是否已安装。如果未找到命令，请通知用户并提供安装说明。

2. 环境变量

设置 Google OAuth2 凭据作为环境变量：

export GTASKS_CLIENT_ID="your-client-id.apps.googleusercontent.com"
export GTASKS_CLIENT_SECRET="your-client-secret"

如何获取凭据：
1. 访问 Google Cloud Console。
2. 创建新项目或选择现有项目。
3. 启用 Google Tasks API。
4. 创建 OAuth2 凭据（应用程序类型："Web 应用程序"）。
5. 添加授权的重定向 URI：
- http://localhost:8080/callback
- http://localhost:8081/callback
- http://localhost:8082/callback
- http://localhost:9090/callback
- http://localhost:9091/callback

如需持久化设置，请将这些添加到您的 shell 配置文件（~/.bashrc、~/.zshrc 等）：

echo 'export GTASKS_CLIENT_ID="your-client-id"' >> ~/.bashrc
echo 'export GTASKS_CLIENT_SECRET="your-client-secret"' >> ~/.bashrc
source ~/.bashrc

3. 身份验证

设置环境变量后，使用 Google 进行身份验证：

gtasks login

这将打开浏览器进行 OAuth2 身份验证。令牌存储在 ~/.gtasks/token.json 中。

核心概念

• 任务列表：存放任务的容器（如"工作"、"个人"、"购物"）。
• 任务：任务列表中的单个待办事项。
• 任务属性：标题（必需）、备注/描述（可选）、截止日期（可选）、状态（待处理/已完成）。

命令结构

所有命令都遵循以下模式：

gtasks [命令] [子命令] [标志] [参数]

身份验证

登录

gtasks login

打开浏览器进行 Google OAuth2 身份验证。在使用任何其他命令之前必需。

登出

gtasks logout

从 ~/.gtasks/token.json 中移除存储的凭据。

任务列表管理

查看所有任务列表

gtasks tasklists view

显示所有带编号索引的任务列表。

输出示例：

[1] 我的任务
[2] 工作
[3] 个人

创建任务列表

gtasks tasklists add -t "工作项目"
gtasks tasklists add --title "购物清单"

使用指定的标题创建新的任务列表。

标志：
- -t, --title：任务列表标题（必需）

删除任务列表

gtasks tasklists rm

交互式提示选择并删除任务列表。

更新任务列表标题

gtasks tasklists update -t "新标题"

交互式提示选择任务列表并更新其标题。

标志：
- -t, --title：任务列表的新标题（必需）

任务管理

所有任务命令都可以使用 -l 标志可选地指定任务列表。如果省略，将通过交互式提示选择。

查看任务

基本查看：

gtasks tasks view
gtasks tasks view -l "工作"

包含已完成的任务：

gtasks tasks view --include-completed
gtasks tasks view -i

仅显示已完成的任务：

gtasks tasks view --completed

排序任务：

gtasks tasks view --sort=due        # 按截止日期排序
gtasks tasks view --sort=title      # 按标题排序
gtasks tasks view --sort=position   # 按位置排序（默认）

输出格式：

gtasks tasks view --format=table    # 表格格式（默认）
gtasks tasks view --format=json     # JSON 输出
gtasks tasks view --format=csv      # CSV 输出

表格输出示例：

工作列表中的任务：
编号  标题               描述               状态       截止日期
1     完成报告           Q4 分析            待处理     2024年12月25日
2     团队会议           每周同步           待处理     -
3     代码审查           PR #123            已完成     2024年12月20日

JSON 输出示例：

[
  {
    "number": 1,
    "title": "完成报告",
    "description": "Q4 分析",
    "status": "pending",
    "due": "2024-12-25"
  }
]

创建任务

交互模式：

gtasks tasks add
gtasks tasks add -l "工作"

提示输入标题、备注和截止日期。

标志模式：

gtasks tasks add -t "购买杂货"
gtasks tasks add -t "完成报告" -n "Q4 分析" -d "2024-12-25"
gtasks tasks add -t "致电牙医" -d "明天"
gtasks tasks add -t "团队会议" -d "12月25日"

标志：
- -t, --title：任务标题（非交互模式必需）
- -n, --note：任务备注/描述（可选）
- -d, --due：截止日期（可选，灵活格式）

日期格式示例：
日期解析器支持多种格式：
- 2024-12-25（ISO 格式）
- 2024年12月25日
- 12月25日
- 明天
- 下周五
- 2024/12/25

有关所有支持的格式，请参阅 dateparse 示例。

标记任务为完成

使用任务编号：

gtasks tasks done 1
gtasks tasks done 3 -l "工作"

交互模式：

gtasks tasks done
gtasks tasks done -l "个人"

提示从列表中选择任务。

删除任务

使用任务编号：

gtasks tasks rm 2
gtasks tasks rm 1 -l "购物"

交互模式：

gtasks tasks rm
gtasks tasks rm -l "工作"

提示选择要删除的任务。

查看任务详情

使用任务编号：

gtasks tasks info 1
gtasks tasks info 3 -l "工作"

交互模式：

gtasks tasks info
gtasks tasks info -l "个人"

输出示例：

任务：完成报告
状态：待处理
截止日期：2024年12月25日
备注：完成 Q4 分析并提交给经理

链接：
  - https://docs.google.com/document/d/...

在 Google Tasks 中查看：https://tasks.google.com/...

常见工作流

快速创建任务

当用户说"将任务添加到我的工作列表"时：

gtasks tasks add -l "工作" -t "任务标题"

检查今天的任务

gtasks tasks view --sort=due

完成多个任务

gtasks tasks done -l "工作"
# 出现交互式提示，选择任务
gtasks tasks done -l "工作"
# 根据需要重复

查看所有列表中的任务

为每个列表多次运行查看命令，或先列出所有任务列表：

gtasks tasklists view
gtasks tasks view -l "工作"
gtasks tasks view -l "个人"

导出任务

gtasks tasks view --format=json > tasks.json
gtasks tasks view --format=csv > tasks.csv

最佳实践

1. 始终首先检查身份验证：如果命令因身份验证错误而失败，请运行 gtasks login。
2. 自动化时使用任务列表标志：编写脚本或用户指定列表名称时，使用 -l 标志以避免交互式提示。
3. 利用灵活的日期解析：--due 标志接受自然语言日期，如"明天"、"下周"等。
4. 使用适当的输出格式：
   • 表格格式用于人类可读的输出。
   • JSON 用于与其他工具解析/集成。
   • CSV 用于电子表格导入。
5. 任务编号是临时的：添加、完成或删除任务时，任务编号会改变。始终先查看列表以获取当前编号。
6. 优雅处理不存在的列表：如果用户指定了不存在的列表名称，命令将出错。始终首先使用 gtasks tasklists view 验证列表名称。

错误处理

常见错误及解决方案：

• "Failed to get service" 或 身份验证错误：
  • 首先，确保环境变量已设置：echo $GTASKS_CLIENT_ID
  • 如果变量未设置，请导出它们（参见前提条件部分）
  • 然后运行 gtasks login 进行身份验证
• "incorrect task-list name"：指定的列表名称不存在。使用 gtasks tasklists view 查看可用列表。
• "Incorrect task number"：任务编号无效。使用 gtasks tasks view 查看当前任务编号。
• "Date format incorrect"：日期字符串无法解析。使用如 "2024-12-25"、"明天" 或 "12月25日" 等格式。

示例

示例 1：创建购物清单并添加项目

gtasks tasklists add -t "购物"
gtasks tasks add -l "购物" -t "牛奶"
gtasks tasks add -l "购物" -t "面包"
gtasks tasks add -l "购物" -t "鸡蛋"

示例 2：查看并完成工作任务

gtasks tasks view -l "工作" --sort=due
gtasks tasks done 1 -l "工作"

示例 3：添加带截止日期的任务

gtasks tasks add -l "工作" -t "提交提案" -n "包含预算和时间线" -d "下周五"

示例 4：导出已完成的任务

gtasks tasks view --completed --format=json -l "工作" > completed_work.json

给代理的提示

运行任何命令之前

1. 首先检查 gtasks 安装：
   bash # 尝试运行 gtasks 版本检查 gtasks --version 2>/dev/null || gtasks.exe --version 2>/dev/null
   如果失败，请告知用户 gtasks 未安装，并提供前提条件部分的安装说明。

2. 验证环境变量是否已设置：
   ```bash
   # 检查变量是否存在（macOS/Linux）
   [ -n "$GTASKS_CLIENT_ID" ] && echo "GTASKS_CLIENT_ID 已设置" || echo "GTASKS_CLIENT_ID 未设置"
   [ -n "$GTASKS_CLIENT_SECRET" ] && echo "GTASKS_CLIENT_SECRET 已设置" || echo "GTASKS_CLIENT_SECRET 未设置"

   Windows PowerShell

   if ($env:GTASKS_CLIENT_ID) { "GTASKS_CLIENT_ID 已设置" } else { "GTASKS_CLIENT_ID 未设置" }
   if ($env:GTASKS_CLIENT_SECRET) { "GTASKS_CLIENT_SECRET 已设置" } else { "GTASKS_CLIENT_SECRET 未设置" }
   ```

3. 检查身份验证状态：
   bash gtasks tasklists view &>/dev/null && echo "已认证" || echo "未认证 - 请运行 'gtasks login'"

通用提示

• 当用户提到"任务"但未指定工具时，询问他们是否想使用 Google Tasks。
• 如果用户询问他们的任务，首先运行 gtasks tasklists view 查看可用列表。
• 如果用户未指定，请始终确认使用哪个任务列表。
• 创建带日期的任务时，为了清晰起见，优先使用显式日期格式（YYYY-MM-DD）而非相对术语。
• 请记住，任务编号从 1 开始，并且在修改后会发生变化。
• 如果命令需要交互但您正在非交互模式下运行，请使用标志提供所有必需信息。