todo 描述语言

一个计划的模样

- desc: 放计划描述
  nexttime: 0      # 下一次输出这个任务的时间，0 代表明天，1 就是后天，依次类推
  period: 7        # 循环周期，每 7 天输出一次。如果想每天都输出，改为 1 即可
  assign:
    to: myself
    via: web
  style:
    separator: ,
  comment: 可以删除本行，作用是对任务性质的描述，类似注释

简写

t = times，次数 d = day m = month y = year

星期、月份按照英语中的缩写

计划之间的关系

添加标签

计划如果加字段 tag: tag_name，tag_name 是自定义的字符串，当计划被触发时，此 tag_name 即可被其他计划使用，通过 every、on、except、start_if、stop_if、del_if、delay_if、if 等

  tag: sunday

也可以指定多个

  tag: [sunday, a_week, a_month]

除了某一天 except

搭配匹配模式，符合则不输出。

可以和任何任务搭配，后面可以跟的内容和 if 相同。

- desc: 每天都会输出这个任务，除了周日
  every: day
  except: Sun   # 同样支持列表

延迟执行

添加键值对 delay_if: tagname 后，当要执行时却遇到了 tagname，会在下一次不满足 tagname 时立刻执行。并会提示被延期了。

周六的计划，如果周六要工作就推迟到明天

  every: Sat
  delay_if: workday   # delay_if: [sunday, a_week, a_month]   也可以指定多个

  every: Sat
  delay_if: [sunday, a_week, a_month]

触发后，但是又满足延迟的条件，则增加一个字段 active: true ，只要下次不因 delay_if 延迟就会执行。

内置可用的条件

以 __ 开头，因此建议用户添加 tag 时不要以两个下划线开头，可能会因为和内置条件重复导致非预期行为

查看其他任务的状况，目前支持： - __tag_is_del ，任务要被删除会触发 - __tag_is_off ，只要任务是关闭的状态就会触发 - __tag_is_on ，只要任务是开启的状态就会触发 - __tag_is_delay ，只要任务处于被延迟的状态就会触发

使用时要把 tag 换成实际的 tag 名称

- desc: 执行一次后删除任务
  on: 8-6
  tag: one_time
- desc: 又一个单次任务
  if: __one_time_is_del

这样每次 tag 为 one_time 的计划被删后，都会有一句提醒的话

如果 tag 在多个计划中都有使用，则任意一个满足就会触发

计划的关启和删除

如果是执行几次后停止呢？

关闭和开启计划

手动添加 off: true 就是关闭，删除或者改为 off: false 就是开启

  off: true

自动开启计划

如果计划本来就是开启状态，那么不会有任何变化。

当计划原本是关闭状态，如果满足条件，会把 off 改为 false，也就是开启计划，并在开启之后就判断计划在此次是否被触发

  off: true
  start_if: one_tag_example

自动关闭计划

类似自动开启的

  off: false
  stop_if: one_tag_example

除了在 start_if 和 stop_if 后跟标志外，还可以跟日期。比如

9月3号后开启任务

  off: true
  start_if: 9-3

1、5号开启任务，3、7号关闭任务

  off: true
  start_if: [1, 5]
  stop_if: [3, 7]

在任务开启的状态下，休眠 3 次，也就是原来前 3 次的输出被重置，推理期间的有些更改也要重置（但是延迟的 active 还是要变），第 4 次恢复，并删除 sleep 字段。

如果任务本身就已经关闭，那么无法被触发，因此休眠的次数不会减少。

  off: false
  sleep: 3

删除计划

除了手动删除，还可以满足条件后自动删除

触发若干次数后，自动删除

  max_count: 3 # max_count 只能跟次数

触发条件后，自动删除，不过该次任务如果触发依然会输出

  del_if: one_tag_example

计划内容

desc 后面可以跟任意格式的内容，字符串、列表、字典都可以。

具体怎么使用取决于处理 desc 的模式和指派对象。默认情况下，不管什么内容，都按照字符串输出

  desc: 计划内容

使用变量

内置变量有这些： - 今年的年份 {{year}}，今年第几周 {{week_of_year}}，今天星期几 {{weekday_zh}} - 更多查看 Collection.py 中的 Today 类型 - 今日的任务，{{ todo_and_notice }}，只有用在其他出口类型上才有意义

  desc: 今年年份用{{year}}，今年第几周{{week_of_year-1}}，今天{{weekday_zh}}

假设输出的那天是 2024.01.31 号，是第 5 周的星期三，则实际的输出为“今年年份用2024，今年第几周4，今天星期三”

可以使用 at 变量，查看当前任务的执行日期和时间，或者 at_time 只查看时间

队列模式

每次被触发，从上往下，会输出第一条内容，还会把这条内容删除。

如果 desc 是列表，那么默认就是队列模式。

- desc:
  - 计划1
  - 计划2
  - 计划3
  - 为空时进行提醒

适合每隔一段时间，就需要添加内容的情况。

比如，想要每天听英语，可以在周末把下一周要听的 YouTube 视频网址，一条条地放到队列的后面，这样在下一周，它会从上往下，依次输出，并把输出过的删除。

在任务为空时，不会自动删除，而是关停任务，并会保留最后一条内容，方便继续添加任务，

轮询模式

每次被触发，按顺序输出内容，如第一天输出第一条，第二天输出第二条。

达到最后一条，就重新从第一条开始。

index 指向这次要输出的内容（当然是取模后的结果），1 表示指向第一个任务，index 必须大于等于 1。

- desc:
  - 计划1
  - 计划2
  - 计划3
  index: 1

适合一系列不同的事情，依次放入今日任务。 - 比如 21 号收拾行李，22 号打扫，23 号叫房东检查，下午去火车站 - 又比如，每日空闲时间有限，学习任务串行执行，第一天看编程，第二天 Linux，第三天 电子电路，依次循环

样式

自定义分隔符

添加一个 separator 字段，后面跟单个字符或字符串，在输出的任务描述中，这个字符串会取代默认的逗号，放在这条任务与下条任务之间

- desc: 任务内容
  every: day
  style:
    separator: k
- desc: 下条任务
  every: day

输出为“任务内容k下条任务”

特殊的，\n 代表换行符。

计划预计耗时

比如计划每天看英文视频 30min，那么可以添加字段 time_taken，作用有两点： 1. 在默认输出的任务中，对应任务后会带上这个时长 2. 在 APP 或网页上，该任务的下一个任务的开始时间会根据耗时向后计算，方便查看一天的时间安排，如果当天任务预计耗时超过上限，也可以一眼看出来。

- desc: 任务内容
  every: day
  time_taken: 30min

输入的时长不能超过 24 小时，格式应该为： - 32m - 1.2m - 1.2min - 1.2mins - 1.2minute - 1.2minutes - 2hours - 2hr - 2h - 2hrs - 2hour - 2h32m - 5hr34m56s - 5 hours, 34 minutes, 56 seconds - 5 hrs, 34 mins, 56 secs

• 4:13
• 4:13:02
• 4:13:02.266

指定执行时间精度到秒

增加一个 at 字段，后面跟 hh:mm:ss 这种格式，要严格都是两位的，24 小时制，如 06:30:00，14:01:00 ，可以省略后面的分钟和秒，缺省都是 0。

没有 at 字段代表在生成任务之后立刻执行。

每天的 8 点半吃药

- desc: 吃药
  every: day
  at: 08:30:00   # at: [08:30:00, 13:30, 18]   也可以指定多个

at 后面也可以跟一些语义化的表达，比如破晓时刻 dawn 、日出时刻 sunrise 、日落时刻 sunset 、入夜时刻 dusk

还可以使用加法或减法，不过只能有两个操作数，且左边的必须是语义化的表达，右边的必须是一个时长，如下

睡觉的时间在天亮前 7.5 小时

- desc: 入眠
  every: day
  at: tomorrow_dawn - 07:30

非默认出口任务，执行时间一样的任务，按照在任务列表从上往下的顺序串行执行，执行时间不一样的任务之间是并发的关系。