滴答清单任务管理工具

\r \r

首次使用：配置与授权\r

\r

1. 配置凭据: 在 .env 中填写 DIDA_CLIENT_ID 和 DIDA_CLIENT_SECRET。\r
2. 完成授权: 运行 python3 index.py auth 并在浏览器完成操作。\r \r

命令结构\r

\r 所有命令均采用 python3 index.py \x3Ccategory> \x3Csubcommand> [args] 格式。\r \r 注意：\r \r

1. 空格要求：命令名、子命令名和参数之间必须使用空格分隔（例如：project update \x3Cid> 而非 project update\x3Cid>）。\r
2. 安全警告：禁止自动执行任何 delete 操作。在执行 project delete 或 task delete 之前，必须获得用户针对具体 ID 的明确批准。\r \r

Intent Decision Tree\r

\r

用户想要…\r
├─ 项目管理 (project)\r
│  ├─ 列出所有项目 ──────→ project list [--force]\r
│  ├─ 查看项目任务 ──────→ project get \x3CprojectId> [--force]\r
│  ├─ 查看项目元数据 ────→ project info \x3CprojectId>\r
│  ├─ 创建新项目 ────────→ project create "\x3Cname>" [--color x]\r
│  ├─ 更新项目 ──────────→ project update \x3CprojectId> [--name x]\r
│  ├─ 清除本地缓存 ──────→ project clear-cache\r
│  └─ 删除项目 (需确认) ─→ project delete \x3CprojectId> !! ⚠️ 需用户批准\r
├─ 任务操作 (task)\r
│  ├─ 查看任务详情 ──────→ task get \x3CprojectId> \x3CtaskId>\r
│  ├─ 创建新任务 ────────→ task create "\x3Ctitle>" [--project id] [--due YYYY-MM-DD]\r
│  ├─ 创建清单任务 ──────→ task create-checklist "\x3Ctitle>" --project \x3Cid> --items "a|b|c"\r
│  ├─ 更新任务 ──────────→ task update \x3CprojectId> \x3CtaskId> [--title x]\r
│  ├─ 完成任务 ──────────→ task complete \x3CprojectId> \x3CtaskId>\r
│  ├─ 删除任务 (需确认) ─→ task delete \x3CprojectId> \x3CtaskId> !! ⚠️ 需用户批准\r
│  ├─ 移动任务 ──────────→ task move \x3CfromPid> \x3CtoPid> \x3CtaskId>\r
│  └─ 高级 JSON 模式 ────→ task create-raw / update-raw\r
└─ 查询与筛选 (search)\r
   ├─ 今日待办 ──────────→ search today [--force]\r
   ├─ 未来几天到期 ──────→ search upcoming [days] [--force]\r
   ├─ 指定区间到期 ──────→ search due-range \x3Cstart> \x3Cend> [--force]\r
   ├─ 已完成任务 ────────→ search completed \x3Cstart> \x3Cend> [--force]\r
   ├─ 高级筛选 ──────────→ search filter [--project id] [--priority N]\r
   └─ 收集箱 ────────────→ search inbox [--force]\r
```\r
\r
## 核心工作流：性能与缓存优化\r
\r
为了提高响应速度并减少 API 配额消耗，本工具内置了缓存机制（默认 365 分钟）：\r
\r
1.  **主动查询**: 优先使用缓存。\r
    - `python3 index.py project list` 获取缓存的项目列表。\r
    - `python3 index.py project get \x3Cid>` 获取缓存的项目任务。\r
2.  **强制刷新**: 如果怀疑数据陈旧，使用 `--force` 参数。\r
    - 示例：`python3 index.py search today --force`\r
3.  **自动失效**:\r
    - 执行任何 `create`、`update`、`delete` 或 `complete` 操作后，相关项目的缓存会**自动清除**。下一次查询将自动从服务器获取最新数据。无需手动刷新。\r
4.  **手动维护**: 如果发现同步异常，可运行 `python3 index.py project clear-cache`。\r
\r
## 参数说明\r
\r
- `--force`: 忽略本地缓存，强制从服务器拉取最新数据。\r
- `--priority`: 0=无, 1=低, 3=中, 5=高。\r
- `--due`: 格式为 `YYYY-MM-DD`。\r
- `--items`: 清单子项，用 `|` 分隔，例如 `"买牛奶|买鸡蛋"`。\r
- `--tags`: 逗号分隔，例如 `"工作,紧急"`。\r
\r
## 故障排除\r
\r
- **数据不一致**: 如果在网页端修改了任务但在 CLI 没看到，请加 `--force` 重新查询。\r
- **未授权**: 运行 `python3 index.py auth`。\r
- **ID 错误**: 运行 `python3 index.py project list --force` 核对最新 ID。\r
- **获取帮助**: 在任何分类后加 `-h`，如 `python3 index.py task -h`。\r