obsidian-plugin-tasks

name	obsidian-plugin-tasks
description	使用Tasks插件在Obsidian中管理和查询任务，支持任务状态跟踪、截止日期、计划日期、创建日期、重复规则、任务依赖等功能。提供强大的查询语法（Tasks Query Language）创建动态任务列表，支持过滤、排序、分组。适用于个人任务管理、项目跟踪、GTD实践、每日计划、习惯追踪等场景。当用户提到Tasks插件、任务管理、TODO列表、任务查询语法、重复任务、任务状态等概念时使用。

重要前提 Tasks插件是主动式任务管理系统：与Dataview不同，Tasks插件会直接修改源文件内容（例如完成任务、更新重复任务）。所有修改都遵循严格的规则，确保数据一致性。查询结果支持交互（如勾选框），勾选后会自动更新源文件。

⚠️ 数据安全关键警告

重要安全提示

• 直接文件修改：Tasks插件直接修改源文件内容，包括自动完成、重复任务生成等操作
• 备份建议：
  • 启用Obsidian的自动备份功能（设置 → 核心插件 → 备份）
  • 配置Git版本控制，定期提交更改
  • 启用重复规则和自动完成前，确保有可靠的备份机制
  • 重要：定期备份 .obsidian/plugins/obsidian-tasks/data.json 文件，它包含你的自定义状态配置
• 数据恢复程序：
  1. 关闭Obsidian
  2. 删除.obsidian/plugins/obsidian-tasks/cache目录（安全操作）
  3. 重启应用并等待索引完成（大型库可能需要5-10分钟）

🚨 最后的手段：重置插件配置

警告：此操作会导致所有自定义状态（Custom Statuses）配置丢失

1. 关闭Obsidian
2. 必须先备份 .obsidian/plugins/obsidian-tasks/data.json 文件
3. 删除库目录下.obsidian/plugins/obsidian-tasks/data.json
4. 重启应用并等待索引完成

后果：data.json存储了所有自定义状态的定义。如果删除了它且没有备份，所有的 [/]、[-] 等符号将失去其背后的"逻辑属性"，导致查询失效。

• 多用户环境警告：在Git同步或团队共享库中，避免在不同设备上同时编辑同一任务。Tasks插件的自动修改可能导致合并冲突

⚠️ 全局过滤器陷阱

• 功能说明：Tasks插件有一个核心设置——Global Filter（例如 #task）
• 行为：如果启用了Global Filter，所有任务必须包含该标签
• 严重后果：
  • 未包含标签的任务在查询中不会显示
  • ignore global query 无法跳过此限制（因为插件根本没索引这些行）
  • 这是索引层面的限制，而非查询层面的过滤

全局过滤器副作用：

• 自动标签：开启全局过滤器后，任务模态框（Create or edit task）生成的任务会自动带上该标签
• 瞬间蒸发：如果你手动删除标签，该任务将从所有Tasks查询结果中瞬间蒸发，且不报任何错误
• 迁移警告：启用全局过滤器后，需要为所有现有任务添加标签，这是一个需要谨慎操作的迁移过程

⚠️ 数据安全附加警告

同步冲突

• 风险：如果你使用 Obsidian Sync 或 iCloud，Tasks 插件的频繁文件修改极易在同步过程中产生 .sync-conflict 副本
• 建议：
  • 关闭“任务状态自动转换”功能，或
  • 确保单设备编辑，避免多设备同时操作
  • 定期检查并清理同步冲突文件

版本控制冲突

• Git注意事项：在使用Git版本控制时，Tasks的自动修改可能导致频繁的合并冲突
• 最佳实践：使用 git pull --rebase 减少冲突，定期提交更改

Tasks插件使用指南

一、基础语法

基本任务结构

- [ ] 基本任务
- [x] 已完成任务
- [/] 部分完成（进行中）
- [-] 已取消

任务元数据字段

任务通过内联字段（行尾元数据）存储丰富信息，严格遵循格式规范：

- [ ] 任务文本 [元数据:: 值]

核心元数据字段

字段	格式	描述	示例
日期（Due）	📅 YYYY-MM-DD 或 due:: YYYY-MM-DD	任务截止日期	📅 2024-12-31
计划日期（Scheduled）	⏳ YYYY-MM-DD 或 scheduled:: YYYY-MM-DD	任务应开始处理的日期	⏳ 2024-12-25
创建日期（Created）	➕ YYYY-MM-DD 或 created:: YYYY-MM-DD	任务创建日期	➕ 2024-12-20
开始日期（Start）	🛫 YYYY-MM-DD 或 start:: YYYY-MM-DD	任务可开始的日期	🛫 2024-12-25
优先级	🔺 highest, ⏫ high, 🔼 medium, 🔽 low, ⏬ lowest 或 priority:: (highest	high	medium
重复规则	🔁 (every day	every week	every month
依赖任务	⛔ task123 或 dependsOn:: task123	任务依赖	⛔ task123
任务ID	🆔 task123	任务标识符，用于依赖引用	🆔 task1
完成日期	✅ YYYY-MM-DD	任务完成时间	✅ 2024-12-31

优先级标识（官方标准）

优先级	Emoji标识	查询值	数值映射
Highest	🔺	highest	1
High	⏫	high	2
Medium	🔼	medium	3
Low	🔽	low	4
Lowest	⏬	lowest	5
None	(无符号)	none	(无数值)

重要：

• 优先级Emoji只有箭头符号，没有🔴🟡🟢颜色圆点！
• 解析逻辑：Tasks插件的解析器是从行尾向前解析元数据的
  • 优先级可以放在日期之前或之后
  • 绝对不能放在描述文本中间
  • 必须与其他内容用空格分隔
• Unicode字符差异警告：这些是Unicode字符，在不同操作系统（iOS vs Windows）和字体下外观会有细微差异，手动输入极易出错。
• 强烈推荐：通过模态框设置优先级：使用 Tasks: Create or edit 命令打开模态框，避免手动输入Emoji的错误。

优先级查询语法扩展

比较查询

• 语法：
  • priority is above medium（高于中等优先级）
  • priority is below high（低于高优先级）
• 优先级顺序：Highest > High > Medium > Low > Lowest
• 示例：
  • priority is above medium 匹配 Highest 和 High
  • priority is below high 匹配 Medium、Low 和 Lowest

数值映射深度说明

• 内部数值：
  • Highest (1) < High (2) < Medium (3) < Low (4) < Lowest (5)
• 比较逻辑：
  • priority is above medium 实际上是查询数值 < 3 的任务
  • priority is below high 实际上是查询数值 > 2 的任务
• 性能优化：数值比较在大型库中比字符串比较更高效

无优先级查询

• 语法：priority is none
• 功能：匹配没有设置优先级的任务
• 使用场景：用于查找未设置优先级的任务，以便进行优先级分类

日期类型映射（官方标准）

日期类型	Emoji标识	内联字段	描述	自动行为
Due（截止）	📅	due::	任务截止日期	手动添加
Scheduled（计划）	⏳	scheduled::	任务计划开始日期	手动添加
Start（开始）	🛫	start::	任务可开始日期	手动添加
Created（创建）	➕	created::	任务创建日期	手动添加
Completion（完成）	✅	completion::	任务完成日期	完成任务时自动添加
Cancelled（取消）	❌	cancelled::	任务取消日期	取消任务时自动添加（需在设置中开启 Record date of cancellation）

completion与done的区别

重要区别：

• completion（完成日期）：Tasks插件自动添加的完成日期，使用✅符号，格式为✅ 2024-12-31，表示任务实际完成的时间
  • 自动添加：完成任务时会自动添加，除非在设置中禁用并重启Obsidian
• done（完成状态）：表示任务的完成状态，在Tasks查询中使用done或not done过滤，在Dataview中对应task.completed布尔值字段

使用场景：

• 使用completion字段：当你需要查询任务的具体完成时间，如completed after last week
• 使用done状态：当你只需要过滤任务的完成状态，不关心具体完成时间

Dataview中的对应关系：

• task.completed（布尔值）：对应Tasks的done状态
• task.text中可能包含✅ 2024-12-31：但需要从文本中提取，Dataview没有直接的task.completion字段

日期格式与时区注意事项

日期格式：

• 严格使用YYYY-MM-DD格式（无时间，无[[wiki links]]）
• 无效日期在查询中会被静默忽略

时区处理：

• 所有日期基于本地时区，无UTC支持
• 跨设备时区不匹配可能导致日期偏移
• 建议所有协作设备使用相同的系统时区设置

任务ID与块引用

任务ID（官方标准）

• 格式：使用🆔符号，如- [ ] 任务描述 🆔 task1
• 内联字段：id:: task1
• 用途：用于依赖引用和任务标识
• 依赖引用：在依赖中使用任务ID值，如dependsOn:: task1或⛔ task1

块引用（Obsidian标准功能）

• 格式：^block-id（Obsidian标准块引用格式）
• 特点：由字母、数字、连字符、下划线组成
• 用途：用于在Obsidian中引用特定段落或任务
• 注意：这是Obsidian的标准功能，与Tasks插件的任务ID是不同的概念

重要区别

• 任务ID：Tasks插件特有，用于依赖关系，格式为🆔 task123
• 块ID：Obsidian标准功能，用于块引用，格式为^block-id
• 依赖引用：使用任务ID值（如task123），不是块引用（如^block-id）

任务依赖详细机制

• 依赖语法：dependsOn:: task123 或使用 ⛔ 符号（如 ⛔ task123）
• 依赖目标：依赖的是任务ID，不是文件块引用（^block-id）
• 示例：
  • dependsOn:: abc123（内联字段格式）
  • ⛔ abc123（Emoji格式）
• 依赖状态：
  • ⛔ 依赖任务未完成时，被阻塞任务显示为'blocked'状态
  • ✅ 依赖任务完成后，被阻塞任务自动变为可用状态，并在查询中显示为'unblocked'
• 依赖传递：支持多级依赖链（任务A依赖任务B，任务B依赖任务C）
• 循环检测：系统会检测并警告依赖循环，避免死锁
  • 显示：在任务旁边显示⚠️图标，悬停显示"循环依赖"
  • 处理：自动将状态设为"cannot-complete"，阻止完成操作
  • 解决：需要手动打破依赖链，移除或修改导致循环的依赖关系
• 重要注意：依赖字段会从下一个重复任务中移除

依赖查询语法

官方查询语法：

• depends on <id> - 查询依赖特定ID的任务
• is blocked - 查询被阻塞的任务
• is blocking - 查询正在阻塞其他任务的任务

示例：

is blocked
not done
sort by due

严格格式要求

日期格式：必须使用ISO格式（YYYY-MM-DD），其他格式将被忽略 Emoji日期标识：系统仅识别预定义Emoji（📅⏳➕🛫），自定义Emoji无效 优先级标识：使用箭头Emoji（�⏫��⏬️），不使用颜色圆点

YAML frontmatter优先级

重要：YAML frontmatter中的字段优先级高于行内元数据。

示例：

---
due: 2024-12-31
---
- [ ] 任务文本 📅 2025-01-15

实际效果：任务的due日期为2024-12-31（YAML值覆盖行内值）

⚠️ YAML Frontmatter 的“只读性”陷阱

关键限制：Tasks 插件无法自动修改 YAML 里的数据

严重后果：

• 如果你在 YAML 定义了 due，当你在 Tasks 界面勾选完成一个重复任务时，插件会因为无法修改 YAML 而导致日期更新失败或生成错误任务
• 这会破坏重复任务的正常工作流

严格禁忌：不要在需要“交互”（如勾选、更新日期）的任务上使用 YAML 元数据

推荐做法：对于需要与 Tasks 插件交互的任务，使用行内元数据（如 📅 2024-12-31）而非 YAML

空格要求

严格规范：元数据必须与任务文本或标签之间存在至少一个空格的分隔边界，推荐使用两个空格以确保解析稳定性

关键提醒：在带有标签的任务中，如果元数据紧跟在标签后面（如 #tag📅2023），解析器 100% 会失败

# 推荐示例
- [ ] 任务文本  📅 2024-12-31
- [ ] 任务文本 #tag  📅 2024-12-31

# 也可工作但不推荐
- [ ] 任务文本 📅 2024-12-31

# 错误示例
- [ ] 任务文本📅 2024-12-31
- [ ] 任务文本 #tag📅2024-12-31

重复任务规则引擎

重复语法（官方标准）

重要规则：所有重复规则必须以 every 开头，这是官方要求的必需语法。

- [ ] 每日任务 🔁 every day
- [ ] 每周任务（完成时更新起始日期） 🔁 every week when done: start
- [ ] 每月15号 🔁 every month on the 15th
- [ ] 每季度首日 🔁 every 3 months on the 1st
- [ ] 每年生日 🔁 every year on December 31

完整重复规则语法表（官方支持的所有模式）

规则类型	语法示例	描述
每日重复	🔁 every day	每天重复
每周重复	🔁 every week	每周重复
每月重复	🔁 every month	每月重复
每年重复	🔁 every year	每年重复
工作日重复	🔁 every weekday	每个工作日重复（周一至周五）
间隔重复	🔁 every 3 days	每3天重复
间隔重复	🔁 every 2 weeks	每2周重复
间隔重复	🔁 every 6 months	每6个月重复
周特定日	🔁 every week on Sunday	每周日重复
周特定日	🔁 every week on Tuesday, Friday	每周二和周五重复
间隔周特定日	🔁 every 2 weeks on Sunday	每2周的周日重复
月特定日	🔁 every month on the 15th	每月15日重复
月最后日	🔁 every month on the last	每月最后一天重复
月最后特定日	🔁 every month on the last Friday	每月最后一个周五重复
月倒数特定日	🔁 every month on the 2nd last Friday	每月倒数第二个周五重复
间隔月特定日	🔁 every 3 months on the 1st	每3个月的1日重复
特定月份特定日	🔁 every January on the 15th	每年1月15日重复
复杂组合	🔁 every April and December on the 1st and 24th	每年4月和12月的1日和24日重复
完成时更新	🔁 every day when done: start	完成时更新start日期
完成时更新	🔁 every week when done: due	完成时更新due日期
完成时更新	🔁 every month when done: both	完成时同时更新start和due日期

重复任务生命周期

1. 创建：初始任务创建
2. 完成：用户勾选任务
   • 重要触发点：必须在Tasks查询结果界面或通过插件命令触发完成操作
   • 注意：如果在纯编辑器模式下手动将 [ ] 改为 [x]，插件可能不会触发新任务的生成（取决于索引状态和设置）
3. 生成新任务：原任务被标记为完成，系统创建一个全新任务
4. 更新：根据规则更新日期字段
   • when done: start：只更新start日期
   • when done: due：只更新due日期
   • when done: both：同时更新start和due日期
   • 默认行为：如果未指定 when done，则使用 "Relative to the original date" 逻辑
     • 深度细节：基于原定日期计算，而非当前日期
     • 重要警告：如果原始任务过期了5天，新生成的任务也会基于原定日期，而非今天。这对习惯追踪至关重要
     • 关键补充：如果任务没有截止日期（Due Date），重复规则将默认基于"完成日期"（Completion Date）计算

锚点日期 (Anchor Date) 逻辑： Tasks 的默认逻辑是根据存在的日期字段优先级来确定的：

1. 如果有 due (截止)，基于原 due 偏移
2. 如果没有 due 但有 scheduled (计划)，基于原 scheduled 偏移
3. 如果没有 due 和 scheduled 但有 start (开始)，基于原 start 偏移
4. 如果没有任何日期字段，强制要求 when done 或默认失败

智能修正特性：

• 使用 every weekday 时，即使原始任务在周六，新任务也会自动修正到周一
• 系统会智能避开周末，确保任务落在工作日内

5. 保留：原任务状态变更为[x]，添加completion日期

重要警告和限制

• 必需条件：重复任务必须至少有一个日期字段（due/scheduled/start）才能正常工作
• 无效日期：无效日期（如2月30日）会导致重复规则消失，不会生成新任务
• 依赖处理：依赖字段（dependsOn）会从下一个重复任务中移除
• 每日笔记注意：不推荐在每日笔记中使用重复任务，可能会创建重复条目
• 功能限制：不支持 "for x times" 或 "until date" 语法
• 块ID保留：重复任务生成时，插件会根据设置决定是否保留块ID（^block-id）
  • Tasks 5.x 默认行为：保留块ID以维持引用完整性
  • 用途：确保与其他笔记的链接和引用保持有效
• 无限循环防御：当任务日期超过100年时，自动停止重复
• 历史记录：原任务不会被删除，而是标记为完成，保留完整历史
• 时区处理：所有日期基于本地时区，无UTC转换

时区边界案例

• 跨时区协作：所有设备应设置相同系统时区，避免日期计算差异
• 重复任务：在时区变更日（如夏令时切换）可能跳过或重复
• 移动设备：自动时区切换可能导致日期偏移
• 查询行为：today 基于本地时区的当前日期，不同时区的设备看到的结果可能不同

二、标准查询

查询基础结构

not done
due after 2024-12-20
sort by due
limit 10

必须在代码块中标记为tasks，每行一个查询指令。

基本查询命令

过滤命令

命令	描述	示例
done/not done	过滤完成/未完成任务	not done
due [before	after] YYYY-MM-DD	过滤截止日期
scheduled [before	after] YYYY-MM-DD	过滤计划日期
start [before	after] YYYY-MM-DD	过滤开始日期
created [before	after] YYYY-MM-DD	过滤创建日期
happens [before	after] YYYY-MM-DD	复合日期查询（包含due、scheduled、start三者之一）
priority is (highest	high	medium
priority is not (highest	high	medium
priority equals (highest	high	medium
path [includes	does not include] "text"	按文件路径过滤
root	只查询根目录下的任务	root
folder/path	查询特定文件夹	"Tasks/Work"
description [includes	does not include] "text"	按任务描述过滤
has [due	scheduled	start
no [due	scheduled	start
is recurring/is not recurring	过滤重复/非重复任务	is recurring

路径查询指令

root 指令

• 功能：只查询根目录下的任务，不包括子文件夹中的任务
• 使用场景：当你只关心根目录中的任务，不需要查看子文件夹内容时
• 示例：

root
not done
sort by due

folder 指令

• 功能：查询特定文件夹中的任务
• 语法：使用文件夹路径，如"Tasks/Work"
• 使用场景：当你需要关注特定文件夹中的任务，如工作任务、个人任务等
• 示例：

"Tasks/Work"
not done
sort by due

日期关键词

• 基础日期：today（今天）、tomorrow（明天）、yesterday（昨天）
• 相对日期：
  • in N days（N天后）、N days ago（N天前）
  • in 2 weeks（2周后）、3 weeks ago（3周前）
  • in 1 month（1个月后）、2 months ago（2个月前）
• 周相关：this week（本周）、next week（下周）、last week（上周）
• 月相关：this month（本月）、next month（下月）、last month（上月）
• 季度相关：this quarter（本季度）、next quarter（下季度）、last quarter（上季度）
• 年相关：this year（今年）、next year（明年）、last year（去年）

三、高级功能

Status Type查询系统 (Tasks 4.0+)

Status Type与自定义状态系统配合，提供五类状态：

状态类型	匹配not done	匹配done	典型符号
TODO	✅	❌	[ ]
IN_PROGRESS	✅	❌	[/]
DONE	❌	✅	[x]
CANCELLED	❌	✅	[-]
NON_TASK	❌	✅	[~]

查询语法：

status.type is IN_PROGRESS
status.type is not CANCELLED

重要区别：

• status.type is TODO 只匹配未开始的任务
• not done 匹配TODO和IN_PROGRESS两种状态
• status.type is DONE 只匹配已完成的任务
• done 匹配DONE、CANCELLED和NON_TASK三种状态

自定义状态说明

配置要求：

• 自定义状态需要在Obsidian设置 → 插件 → Tasks → 状态中配置
• 可能需要自定义CSS来美化显示效果

默认行为：

• 未知的状态符号会默认为TODO类型
• 查询中的状态类型匹配不区分大小写（Tasks 5.0+）

⚠️ 状态转换的“强制符号”陷阱

nextStatus 配置风险：

• 如果 nextStatus 设置为空格 " "，会导致点击后状态循环，无法正常工作
• 建议为每个状态设置明确的下一个状态

CSS 依赖警告：

• 在使用自定义状态（如 [/] IN_PROGRESS）时，如果对应的 CSS 未加载，Obsidian 原生渲染器会将 [/] 渲染为一个带斜杠的复选框，但无法点击交互
• 必须提醒：用户需要安装支持自定义状态的 CSS 主题（如 Minimal）或添加自定义 CSS
• 兼容性：移动端对自定义状态的支持仍然较差，图标可能显示异常

依赖关系管理

任务依赖语法

• 依赖语法：dependsOn:: task123 或使用 ⛔ 符号（如 ⛔ task123）
• 依赖目标：依赖的是任务ID，不是文件块引用
• 示例：
  • dependsOn:: abc123（内联字段格式）
  • ⛔ abc123（Emoji格式）

依赖状态

• 被阻塞：依赖任务未完成时，被阻塞任务显示为'blocked'状态
• 可用：依赖任务完成后，被阻塞任务自动变为可用状态，并在查询中显示为'unblocked'

依赖查询

• 查询被阻塞任务：is blocked
• 查询未被阻塞任务：is not blocked
• 查询有依赖的任务：depends on task123

循环依赖检测

• 显示：在任务旁边显示⚠️图标，悬停显示"循环依赖"
• 处理：自动将状态设为"cannot-complete"，阻止完成操作
• 解决：需要手动打破依赖链，移除或修改导致循环的依赖关系

自定义排序与分组

自定义排序

• 基本排序：sort by due、sort by priority等
• 自定义排序函数：

not done
sort by function(task) {
  return task.description.length;
}

嵌套分组

• 多级分组：支持最多3级嵌套分组
• 示例：

not done
happens in the next 7 days
group by folder
group by priority
sort by due

分组函数（Group by Function）

功能：使用JavaScript函数进行自定义分组，实现复杂的分组逻辑

语法：group by function <expression>

示例：

# 按任务描述长度分组
group by function task.description.length

# 按文件名后缀分组
group by function task.file.filename.split('.').pop()

# 按文件名大写形式分组
group by function task.file.filename.toUpperCase()

# 按文件所在文件夹分组
group by function task.file.folder.split('/').pop()

嵌套任务显示 (show tree)

功能：以树形结构显示嵌套任务，展示任务的层级关系

语法：show tree

使用场景：当你需要查看任务的层级结构，特别是在处理具有子任务的复杂项目时

示例：

not done
path includes "Projects"
show tree
sort by due

高级查询技巧

复杂条件组合

not done
(due before tomorrow) OR (scheduled before tomorrow)
priority is high
path includes "Work"
sort by due
limit 5

过滤函数（Filter by Function）

功能：使用JavaScript逻辑进行极度复杂的过滤，比普通过滤指令更强大

语法：filter by function <expression>

示例：

• filter by function task.description.length > 20
• filter by function task.due && task.due.moment.isBefore(moment(), 'day')

示例：

not done
# 只显示描述中包含数字的任务
filter by function task.description.match(/\d+/) !== null

# 只显示描述长度超过20个字符的任务
filter by function task.description.length > 20

# 只显示截止日期在周末的任务 (Moment.js 语法)
filter by function task.due && [0, 6].includes(task.due.moment.day())

脚本过滤高级指南

日期处理必须使用 Moment.js

• 核心语法：task.due.moment 返回 Moment 对象
• 常用方法：
  • task.due.moment.day() - 获取星期几（0-6，周日为0）
  • task.due.moment.isBefore(moment(), 'day') - 检查是否过期
  • task.due.moment.valueOf() - 获取时间戳（用于排序）

示例：

# 查询过期的任务
filter by function task.due && task.due.moment.isBefore(moment(), 'day')

# 查询本周内到期的任务
filter by function task.due && task.due.moment.isBetween(
  moment().startOf('week'), 
  moment().endOf('week')
)

重要注意事项

• task.description：不包含元数据Emoji，仅包含纯文本描述
• 空值处理：必须处理 task.due、task.priority 等可能为 null 的情况
• 性能考虑：复杂的过滤函数会影响查询速度，建议在大型库中谨慎使用

分组与隐藏选项说明

group by recurrence：按重复规则分组，部分版本可能存在渲染问题

hide recurrence rule：在查询结果中隐藏重复规则，Tasks 5.x 后此选项仍然有效

limit groups：限制每个分组显示的任务数量，避免分组过大

示例：

not done
group by folder
group by priority
limit groups 3  # 每个分组最多显示3个任务
sort by due

移动端注意事项

• 移动端对自定义状态的支持仍然较差，图标可能显示异常
• 建议在移动端使用标准状态符号以获得最佳体验

边缘案例警告

多行任务：

• Tasks插件对多行列表项的支持有限
• 元数据必须在第一行末尾，后续行的内容不会被解析为元数据

列表缩进：

• 任务必须是标准的Markdown列表（使用 -, *, +）
• 缩进必须严格遵循Obsidian的层级结构
• 错误的缩进可能导致查询漏掉子任务

示例：

# 正确格式
- [ ] 任务描述  📅 2024-12-31
  - [ ] 子任务描述

# 错误格式（元数据不在第一行）
- [ ] 任务描述
  额外说明  📅 2024-12-31

查询布尔运算规则

重要规则：

1. 默认关系：所有查询条件默认使用AND关系，即所有条件都必须满足
2. OR操作：使用大写的OR进行或运算，如(due before tomorrow) OR (scheduled before tomorrow)
3. 括号分组：复杂条件需要使用括号分组，确保运算优先级正确
4. 否定操作：不支持NOT前缀，必须使用is not形式，如priority is not high
5. 无显式AND：不支持显式书写AND（默认就是AND关系）

查询执行顺序：

1. 全局过滤 (Settings) - 基于Global Filter标签
2. 指令过滤 (Query Block) - 基础过滤条件
3. 布尔逻辑 (OR 运算) - 复杂条件组合
4. 排序 (sort by) - 结果排序
5. 分组 (group by) - 结果分组
6. 限制 (limit) - 结果数量限制

调试与优化

explain 指令

• 功能：显示查询的解析过程，是排查查询问题的重要工具
• 使用场景：当查询结果不符合预期时，添加此指令查看查询是如何被解析的
• 示例：

not done
due after today
explain

ignore global query 指令

• 功能：忽略插件设置中配置的全局查询条件
• 使用场景：在复杂查询中，当你需要临时绕过全局查询设置，使用完全自定义的条件时
• 示例：
  • 全局设置了 path includes "Tasks/"，但你需要查询其他路径的任务
  • 全局设置了 not done，但你需要查询已完成的任务

查询默认行为

默认排序：

• 未指定排序时的默认顺序：status > due > path
• 优先级：状态 > 截止日期 > 文件路径

全局查询行为：

• 全局查询条件会自动附加到所有查询中，除非使用 ignore global query 指令
• 建议只在全局设置中配置通用过滤条件（如排除归档文件夹）

显示控制指令

展示优化：

• short mode：隐藏任务行尾的所有元数据符号（日期、重复、优先级等），仅显示文本，保持列表整洁
• hide task count：隐藏查询结果顶部的任务数量统计
• hide backlink：隐藏指向源文件的反向链接
• hide edit button：隐藏任务末尾的编辑图标（铅笔）
• hide priority：隐藏优先级符号
• hide created date：隐藏创建日期
• hide start date：隐藏开始日期
• hide scheduled date：隐藏计划日期
• hide due date：隐藏截止日期
• hide recurrence rule：隐藏重复规则

示例：

not done
due in the next 7 days
short mode
hide task count
hide edit button
hide priority
sort by due

占位符 (Placeholders)（Tasks 5.0+ 支持）

功能：在查询中使用动态占位符，实现基于当前上下文的智能查询

常用占位符：

• {{query.file.path}}：当前文件的路径
• {{query.file.title}}：当前文件的标题
• {{query.file.folder}}：当前文件所在的文件夹

示例：

# 仅查询当前文件内的任务
path includes {{query.file.path}}
not done
sort by due

# 查询描述中包含当前文件名的任务
description includes {{query.file.title}}
not done
sort by due

高级查询场景

复杂条件组合

not done
(due before tomorrow) OR (scheduled before tomorrow)
priority equals high
path includes "Work"
sort by due
limit 5

嵌套分组

not done
happens in the next 7 days
group by folder
group by priority

动态日期计算

not done
due after today
due before in 14 days
sort by due ascending

任务操作与交互

交互行为

• 勾选框：点击任务前的勾选框将：
  1. 更新任务状态（[ ] → [x]）
  2. 自动添加completion日期（✅ YYYY-MM-DD）
  3. 如有重复规则，生成新任务
  4. 如有依赖任务，更新依赖状态
• 编辑：点击任务文本进入源文件编辑
• 上下文菜单：右键任务可：
  • 复制任务
  • 删除任务
  • 编辑原始内容
  • 转到源文件

任务状态转换规则

初始状态	操作	结果状态	附加行为
[ ] 未开始	勾选	[x] 完成	添加completion日期，处理重复
[/] 进行中	勾选	[x] 完成	同上
[-] 已取消	勾选	[x] 完成	保留取消状态历史
[x] 已完成	取消勾选	[ ] 未开始	移除completion日期

与Dataview集成

Tasks作为Dataview数据源

方式1：使用TASK查询（推荐）

const result = await dv.query(`
TASK FROM #tasks
WHERE !completed
SORT due ASC
`);
dv.taskList(result.value);

推荐的DataviewJS访问方式

// 推荐的DataviewJS访问方式
const tasks = dv.pages().file.tasks.filter(t => t.text.includes("📅") && !t.completed);
dv.taskList(tasks);

// 示例：只显示描述中包含数字的任务
const tasksWithNumbers = dv.pages().file.tasks.filter(t => 
  t.text.match(/\d+/) !== null && !t.completed
);
dv.taskList(tasksWithNumbers);

方式2：遍历file.tasks（适用于自定义逻辑）

// 遍历所有包含tasks标签的文件中的任务
for (let page of dv.pages('#tasks')) {
  for (let task of page.file.tasks) {
    // 访问任务属性
    // task.completed - 任务是否完成
    // task.due - 截止日期
    // task.text - 任务文本（包含标签）
    // task.section - 任务所在章节
    // task.position - 任务在文件中的位置
  }
}

混合查询（Tasks + Dataview）

TABLE WITHOUT ID
  file.link AS "项目",
  choice(length(filter(file.tasks, (t) => !t.completed)) > 0, "✅", "⏳") AS "状态",
  dateformat(date(today) + dur("7 days"), "yyyy-MM-dd") AS "下周截止"
FROM "Projects"
WHERE contains(file.tasks.due, this.due)

元数据映射规则

Tasks字段	Dataview等效字段	注意事项
📅 due	task.due	必须格式正确才被解析为日期
⏳ scheduled	task.scheduled	同上
➕ created	task.created	同上
🛫 start	task.start	同上
� priority	task.priority	高/中/低映射为数值
🔁 recurrence	task.recurring	布尔值

配置选项详解

全局设置

• 任务完成时间：设置完成任务时自动添加的completion日期格式
• 重复规则设置：配置重复任务的行为（更新哪个日期、保留历史等）
• 默认优先级：新任务的默认优先级
• 日期格式：显示日期的格式（不影响存储格式）
• 任务状态：自定义任务状态符号和含义
• 查询默认排序：未指定排序时的默认顺序

高级配置

• 忽略文件夹：指定不扫描的文件夹
• 忽略标签：指定不索引的标签
• 状态符号映射：自定义状态符号与含义映射

[
{"symbol": " ", "name": "todo"},
{"symbol": "/", "name": "in-progress"},
{"symbol": "x", "name": "done"},
{"symbol": "-", "name": "cancelled"}
]

• 优先级映射：自定义优先级符号与数值映射

• 日期推断规则：配置如何从任务文本推断日期

• 自定义任务状态系统：Tasks 5.0+引入的扩展状态系统

  • 配置路径：Obsidian设置 → 插件 → Tasks → 状态
  • 状态符号映射示例：

  [
    {"symbol": " ", "name": "todo", "nextStatus": "in-progress"},
    {"symbol": "/", "name": "in-progress", "nextStatus": "done"},
    {"symbol": "x", "name": "done", "nextStatus": "todo"},
    {"symbol": "-", "name": "cancelled", "nextStatus": "todo"},
    {"symbol": "p", "name": "pending", "nextStatus": "in-progress"}
  ]
  

  • 工作流转换规则：可配置每个状态的下一个默认状态，支持自定义工作流
  • 查询语法：status is todo 或 status is not done

性能与限制

严格性能准则

1. 索引延迟：文件修改后，Tasks索引更新需要1-3秒

2. 大库优化：根据官方基准测试，在标准硬件上，超过2000个活跃任务时建议使用路径过滤

   • 性能基准（Intel i5/16GB RAM/SSD）：
     • 500任务：索引时间<0.5秒
     • 2000任务：索引时间≈1.8秒
     • 5000+任务：建议使用exclude path参数

3. 排除路径参数：使用exclude path减少索引范围，基于字符串包含匹配

   • exclude path "Archived/" 排除包含Archived的文件夹及子文件夹
   • exclude path "Templates/" 排除包含Templates的文件夹
   • exclude path "/Archive/" 更严格的匹配，避免误匹配My Archive等
   • exclude path "Templates/" exclude path "Archive/" 同时排除多个路径

   性能误区：

   • Tasks的路径过滤是基于字符串包含的，而非精确匹配
   • 如果你的文件夹叫 My Archive，它也会被 exclude path "Archive" 排除
   • 为了严格匹配，建议使用 exclude path "/Archive/" 格式
   • 支持简单的前缀匹配，复杂glob模式的支持程度有限

4. 大型库性能优化（超过10,000个任务）

   • 按需查询：避免在常驻侧边栏的笔记中放置过于复杂的查询
   • 查询策略：将复杂查询放在需要时才打开的专用笔记中
   • 组合优化：结合exclude path和limit指令，减少单次查询的任务数量

5. 避免全局查询：永远不要在大型库中使用无过滤条件的查询

6. 查询缓存：复杂查询结果会被缓存，但源文件修改后会失效

硬性限制

• 最大查询结果：单个查询返回结果限制为10,000条
• 嵌套分组深度：最多支持3级嵌套分组
• 重复规则深度：默认最多生成50个重复实例
  • 限制调整：可通过修改插件设置中的"最大重复实例数"调整此限制
  • 性能影响：超过100可能导致性能下降，特别是在移动设备上
  • 最佳实践：根据实际需要设置合理值，一般项目建议50-100个实例
• 查询语法限制：不支持正则表达式（与Dataview不同）
• 时区限制：所有日期基于系统本地时区，不支持时区转换

移动端功能限制

• iOS/Android交互限制：
  • 点击任务文本可能直接跳转到源文件，而非编辑模式
  • 长按任务显示上下文菜单，包含完成、编辑等选项
• 自动完成行为：
  • 移动端网络延迟可能导致自动完成操作响应较慢
  • 重复任务生成可能在网络恢复后批量执行
• 性能注意事项：
  • 移动设备上建议限制单个查询的任务数量（500条以内）
  • 减少复杂分组和排序操作以提升响应速度
  • 考虑使用exclude path排除不常用文件夹
• 移动端特有限制：
  • 不支持自定义排序/分组函数
  • 长按任务而非右键显示上下文菜单
  • 重复任务生成可能延迟至网络恢复
  • 建议单个查询限制在500条以内

最佳实践与陷阱

推荐实践

• 文件组织：将任务按项目/上下文存放在单独文件夹
• 元数据一致性：统一使用Emoji或内联字段语法，避免混合
• 查询优化：先使用path缩小范围，再应用其他过滤条件
• 块ID管理：为关键任务添加块ID以便建立依赖关系
• 历史保留：定期归档已完成任务，减少活跃任务数量

常见陷阱

1. 日期格式错误：非ISO格式日期（2024/12/31）不会被识别
2. 空格缺失：任务文本与元数据间缺少两个空格导致解析失败
3. 重复规则冲突：多个重复规则在同一任务上导致不可预测行为
4. 依赖循环：任务A依赖任务B，任务B又依赖任务A，形成死锁
5. 移动任务：将任务移动到新文件会破坏块ID依赖关系
6. YAML冲突：YAML frontmatter中的同名字段会覆盖内联字段
7. 时区误解：跨时区协同时，本地日期可能导致不一致

真实场景示例

1. 每日待办清单

not done
(due before today) OR (scheduled before today) OR (start before today)
priority is high
hide recurrence rule
sort by priority, due

2. 项目进度跟踪

path includes "Projects/Website"
not done
group by heading
group by priority
limit 20

3. 习惯追踪器

is recurring
priority is low
scheduled after 7 days ago
group by recurrence
sort by scheduled

4. 依赖任务管理

depends on project-start
not done
sort by due

5. 周回顾模板

本周完成

done
completed after last week
sort by completed

未完成任务

not done
due before next week
sort by due

新任务

created after last week
not done
sort by created

故障排除指南

任务不显示在查询结果中？

• 检查日期格式是否为严格ISO标准（YYYY-MM-DD）
• 验证任务文本与元数据之间是否有两个空格
• 确认文件是否在"忽略文件夹"配置中
• 检查任务是否被YAML frontmatter中的同名字段覆盖

重复任务不生成？

• 验证原始任务是否已完成
• 检查重复规则语法是否精确匹配规范
• 确认时区设置是否影响日期计算

数据恢复程序

• 当查询结果异常时：
  1. 关闭Obsidian
  2. 删除 .obsidian/plugins/obsidian-tasks/cache 目录
  3. 重启应用触发完整索引重建

版本迁移指南

从3.x到4.x的变更

• 破坏性变更：
  • 查询语法更新，部分操作符变更
  • 重复规则引擎重构
  • 性能优化导致索引机制变化
• 迁移建议：
  • 备份现有库
  • 逐步更新查询语句
  • 验证重复任务行为

从4.x到5.x的变更

• 扩展状态系统：引入自定义任务状态
• 依赖机制增强：添加自动状态转换
• 性能参数调整：新增exclude path参数

高级自定义功能

自定义排序函数（Tasks 5.0+ 支持）

基本示例：

sort by function(task) {
  return task.description.length;
}

高性能建议：处理空值情况以提高排序性能

// 按截止日期排序，处理空值
return task.due ? task.due.moment.valueOf() : 0;

// 按优先级排序，处理空值
return task.priority ? task.priority : 999;

自定义渲染器API

• 用于修改任务显示格式
• 支持自定义状态图标
• 可扩展任务属性显示

自定义渲染器示例

// 自定义渲染器配置示例
const customRenderer = (task, element) => {
  // 为高优先级任务添加红色边框和火焰图标
  if (task.priority === 'high') {
    element.style.borderColor = '#ff0000';
    element.style.borderWidth = '2px';
    element.style.borderStyle = 'solid';
    
    // 查找或创建优先级元素
    const priorityElement = element.querySelector('.task-priority');
    if (priorityElement) {
      priorityElement.innerHTML = '🔥';
      priorityElement.title = '高优先级';
    }
  }
  
  // 为接近截止日期的任务添加黄色背景
  if (task.due && task.due.diffNow().days <= 3) {
    element.style.backgroundColor = '#fff3cd';
  }
  
  // 为已完成任务添加绿色对勾
  if (task.status === 'done') {
    const statusElement = element.querySelector('.task-status');
    if (statusElement) {
      statusElement.innerHTML = '✅';
    }
  }
};

// 在插件设置中应用
// settings.customRenderer = customRenderer;

参考资源

• 官方文档: https://github.com/obsidian-tasks-group/obsidian-tasks
• 查询语法详解: https://publish.obsidian.md/tasks/Queries
• 重复规则指南: https://publish.obsidian.md/tasks/Recurring+Tasks
• 社区论坛: https://forum.obsidian.md/c/plugins/tasks/66
• GitHub Issues: https://github.com/obsidian-tasks-group/obsidian-tasks/issues

版本兼容性

• 最低Obsidian版本: 1.0.0
• 推荐Obsidian版本: 1.4.0+
• Tasks插件版本要求: 4.0.0+（推荐5.0.0+以获得完整功能）
• 与Dataview兼容版本: Dataview 0.5.53+

版本特性对应：

• Tasks 4.0+：引入Status Type查询系统，重复规则引擎重构
• Tasks 5.0+：扩展状态系统，自定义排序函数语法更新，show tree功能

重要提示：Tasks插件持续更新，新版本可能引入向后不兼容的变更。升级前请备份库，并查阅更新日志。某些高级功能（如自定义状态符号、show tree）需要最新版本支持。