OmniFocus

# OmniFocus Task Management

通过 JavaScript for Automation (JXA) 脚本自动化 OmniFocus 任务管理。

## 快速开始

所有脚本均位于 `scripts/` 目录下并使用 JXA。运行方式：

```bash osascript -l JavaScript scripts/<script-name>.js [args] ```

**关键脚本：** - `add_task.js` - 添加任务到收件箱 - `list_tasks.js` - 列出带过滤器的任务 - `search_tasks.js` - 按关键词搜索任务 - `complete_task.js` - 按名称完成任务 - `update_task.js` - 更新任务属性 - `get_stats.js` - 获取 OmniFocus 统计信息

## 核心操作

### 添加任务

```bash osascript -l JavaScript scripts/add_task.js "Task name" ["Note"] ["YYYY-MM-DD"] ```

**示例：** ```bash osascript -l JavaScript scripts/add_task.js "Buy groceries" osascript -l JavaScript scripts/add_task.js "Review doc" "Check sections 1-3" osascript -l JavaScript scripts/add_task.js "Submit report" "Q1" "2026-01-31" ```

**返回：** 任务 ID

### 列出任务

```bash osascript -l JavaScript scripts/list_tasks.js [filter] [limit] ```

**过滤器：** - `inbox` - 收件箱任务 - `available` - 可用（未阻塞）任务（默认） - `flagged` - 已标记任务 - `due-soon` - 3天内到期 - `overdue` - 已逾期 - `all` - 所有未完成任务

**返回：** 包含任务详情的 JSON 数组（name, id, note, dueDate, flagged, project, tags）

### 搜索任务

```bash osascript -l JavaScript scripts/search_tasks.js "keyword" [limit] ```

搜索任务名称和备注。不区分大小写。

**返回：** 匹配任务的 JSON 数组

### 完成任务

```bash osascript -l JavaScript scripts/complete_task.js "Task name" ```

先搜索收件箱，然后搜索所有任务。完成首个匹配项。

### 更新任务

```bash osascript -l JavaScript scripts/update_task.js "Task name" [--note "text"] [--due "YYYY-MM-DD"] [--flag true/false] ```

**示例：** ```bash osascript -l JavaScript scripts/update_task.js "Review" --note "Added notes" osascript -l JavaScript scripts/update_task.js "Submit" --due "2026-02-01" osascript -l JavaScript scripts/update_task.js "Important" --flag true ```

### 获取统计信息

```bash osascript -l JavaScript scripts/get_stats.js ```

**返回：** 包含计数的 JSON： - total, incomplete, inbox - flagged, overdue, dueSoon - available, blocked

## 使用指南

### 回应用户查询时

1. **列出任务** 先于操作，以确认目标 2. **解析 JSON 输出** 以进行结构化处理 3. **展示结果** 使用用户友好的格式（而非原始 JSON） 4. **确认操作** 再完成或修改任务 5. **优雅处理错误**（如任务未找到等）

### 常见模式

**每日回顾：** ```bash # Statistics overview osascript -l JavaScript scripts/get_stats.js

# What needs attention osascript -l JavaScript scripts/list_tasks.js overdue osascript -l JavaScript scripts/list_tasks.js due-soon ```

**任务查询：** ```bash # "What's in my inbox?" osascript -l JavaScript scripts/list_tasks.js inbox

# "What are my next actions?" osascript -l JavaScript scripts/list_tasks.js available 10

# "Show my flagged tasks" osascript -l JavaScript scripts/list_tasks.js flagged ```

**任务管理：** ```bash # "Add a task to call John" osascript -l JavaScript scripts/add_task.js "Call John"

# "Find tasks about the project" osascript -l JavaScript scripts/search_tasks.js "project"

# "Mark 'Buy milk' as complete" osascript -l JavaScript scripts/complete_task.js "Buy milk"

# "Flag the review task" osascript -l JavaScript scripts/update_task.js "Review" --flag true ```

### 输出处理

脚本返回 JSON 用于结构化数据。向用户展示时：

1. 解析 JSON 2. 清晰格式化结果 3. 汇总计数和关键信息 4. 高亮紧急项目（逾期、即将到期）

**示例响应格式：** ``` Found 3 overdue tasks: • Submit Q1 report (due Jan 20) • Review contract (due Jan 23) • Call vendor (due Jan 24)

And 5 tasks due in the next 3 days: • [list tasks]

Would you like me to flag or update any of these? ```

### 错误处理

常见错误： - **Task not found** - 再次检查名称或先搜索 - **No tasks** - 结果为空，明确报告 - **Invalid date** - 使用 YYYY-MM-DD 格式 - **OmniFocus not running** - 脚本需要 OmniFocus 运行

### 多步操作

**先查找后操作：** ```bash # 1. Search for task RESULTS=$(osascript -l JavaScript scripts/search_tasks.js "meeting")

# 2. Parse and identify target task name

# 3. Complete the task osascript -l JavaScript scripts/complete_task.js "Team meeting notes" ```

## 技术参考

有关详细 API 信息和高级用法，请参阅： - **JXA API 参考：** `references/jxa-api.md` - 对象模型和方法 - **自动化指南：** `references/automation-guide.md` - 详细脚本文档和工作流

在以下情况阅读这些文件： - 构建复杂查询 - 理解 OmniFocus 数据模型 - 实现自定义工作流 - 调试脚本

## 系统要求

- macOS - 已安装并运行 OmniFocus - 脚本具有执行权限 (chmod +x)

## 注意事项

- 脚本使用 JXA (JavaScript for Automation)，而非 AppleScript - 任务匹配对于精确名称区分大小写，对于搜索不区分大小写 - 日期格式：YYYY-MM-DD (ISO 8601) - 所有操作均在默认的 OmniFocus 文档上执行 - 脚本除添加、完成和更新操作外均为只读安全