Taskwarrior 工作周（Work Week）支持设计解读：从 weekstart 到 workweek 的演进

• 开发工具

doc/devel/rfcs/workweek.md 是 Taskwarrior 官方 RFC 设计文档之一，记录了项目对"一周从哪一天开始、哪些天算工作日"这一时间语义的演进思路：从已落地多年的weekstart配置，到计划中完全由用户自定义的workweek配置。本文以该设计文档为骨架，结合 src/Context.cpp、src/commands/CmdCalendar.cpp、src/recur.cpp 等源码与测试用例，完整梳理现有实现的原理、设计提案的语义细节及其对日期引用与循环任务（recurrence）的影响。读完本文，你将理解 Taskwarrior 周界定的底层机制，并掌握workweek提案中soww、eoww与recur:weekday的推导关系。

现状：weekstart只能二选一

配置的来源与用途

Taskwarrior 目前支持"一周从周日或周一开始"这一概念，完全由配置变量weekstart决定。按照设计文档的记载，这一能力大约八年前就已加入，最初仅仅为了在calendar报告中正确排布日历视图——即日历的第一列是从周日还是从周一开始。

此后它的用途逐渐扩散：weekstart不再只影响日历排版，还进一步影响了sow（start of week，周起始日）这一日期引用（date reference）的取值。

默认值与取值约束

在 src/Context.cpp 的默认配置中可以看到它的默认值：

weekstart=sunday # Sunday or Monday only

注释已经明确：这个变量只允许sunday或monday两个值。其解析与校验逻辑位于 src/Context.cpp：

auto weekStart = Datetime::dayOfWeek(config.get("weekstart")); ... "The 'weekstart' configuration variable may only contain 'Sunday' or 'Monday'."); Datetime::weekstart = weekStart;

代码将字符串配置解析为Datetime::weekstart这个静态成员，供全程序共享；一旦传入既非Sunday也非Monday的值，Taskwarrior 会直接抛出错误。CmdShow命令（对应task show）也会把weekstart作为可展示的配置项列出，参见 src/commands/CmdShow.cpp。

calendar 报告中的实际使用

calendar报告是weekstart的主要消费者。在 src/commands/CmdCalendar.cpp 中，日历渲染逻辑首先读取该静态值：

auto weekStart = Datetime::weekstart;

随后在计算每月的首日偏移、周内各列位置时反复参考weekStart（例如 src/commands/CmdCalendar.cpp 中的(weekStart == 1 ? 0 : 1)偏移修正）。测试用例 test/calendar.test.py 也验证了rc.weekstart:Monday下calendar命令能够正常运行。

为什么weekstart不再够用

设计文档明确指出了两方面的诉求：

1. "周末"（weekend）的概念需要可定义。不同地区、不同职业的工作日/休息日划分差异很大，硬编码"周六、周日是周末"无法满足所有用户。相关请求一直存在，希望让"周末"可以被配置。
2. "每一周都有周末"这一假设本身也被质疑。某些工作模式（如排班制）并不存在固定的周末。

正是这些诉求累积之后，设计文档给出了一个明确结论：

现在已经很清楚：一个weekstart设置、加上一个固定的"周末"概念，都不再够用了。

这正是workweek提案的出发点——不再只定义一周的起点，而是让用户完整地定义整个工作周。

提案：workweek配置项

配置语法与编号规则

设计文档给出的核心提案是一种极简的列表式配置：

workweek=1,2,3,4,5

这里的数字是以周日为第 0 天的星期编号（day zero = Sunday），对应关系如下：

因此workweek=1,2,3,4,5表示的就是典型的周一至周五工作周——工作日为周一、周二、周三、周四、周五，而周日（0）与周六（6）自动落入选中的"非工作日"。通过调整数字列表，用户可以自由定义任意组合的工作日，例如六天工作制0,1,2,3,4,5、只上四天班1,2,3,4等，从而天然地解决了"周末可定义"的诉求。

由此推导出soww与eoww

设计文档指出，一旦有了workweek，两个新的日期引用语义就可以被确定：

• soww：start of work week，工作周起始日；
• eoww：end of work week，工作周结束日。

它们不再依赖固定的weekstart或固定的周末假设，而是从用户配置的工作日列表直接计算得出。以workweek=1,2,3,4,5为例，soww就是本周的周一，eoww就是本周的周五。需要说明的是，这两个日期引用目前尚未在源码中实现（在 src 中检索不到soww/eoww的定义），它们属于该 RFC 的设计产物，待功能正式排期后落地。

与recur:weekday的关系

设计文档特别提到，workweek还能决定recur:weekday的语义——即"每个工作日循环"的递归任务应该落在哪些天。

当前仓库中的实现是硬编码的"周一至周五"逻辑，位于 src/recur.cpp 的getNextRecurrence：

else if (period == "weekdays") { auto dow = current.dayOfWeek(); int days; if (dow == 5) days = 3; else if (dow == 6) days = 2; else days = 1; return checked_add_datetime(current, days * 86400); }

这里的逻辑非常直接：若当前是周五（dow == 5），下一次循环向后推 3 天（跨过周六、周日到下周一）；若当前是周六（dow == 6），向后推 2 天（到周一）；其余工作日则推 1 天。这等价于把"周末 = 周六 + 周日"写死在了递归引擎里。测试 test/recurrence.test.py 正是验证这一行为：一个due:friday recur:weekdays的任务，第二次生成实例会落在周一，从而跳过周末。

而在workweek提案下，recur:weekday将不再依赖上述硬编码的周末假设，而是根据用户配置的工作日列表动态计算下一次循环应落在哪一天。这意味着：即使某人定义workweek=0,1,2,3,4,5,6（七天全工作），recur:weekday也能正确地做到每天循环。

关联机制：DOM 中的.weekday

除了日历与循环任务，Taskwarrior 的 DOM（Data Object Model）引用也暴露了星期维度。在 src/DOM.cpp 中，<date>.weekday可以作为 DOM 元素被查询（例如task _get 3.due.weekday，参见测试 test/dom2.test.py）。weekday反映的是某日期的星期序号，这与workweek中使用的编号体系（周日为 0）同源；一旦workweek落地，DOM 查询与脚本化工作流同样可以基于可配置的工作日语义扩展。

影响与状态

兼容性影响

workweek提案一旦实现，会在语义上取代或扩展weekstart的部分作用：

• 周起始不再局限于周日/周一，而是由工作日列表的最小值（或用户显式指定）决定；
• "周末"不再是固定概念，而是workweek列表的补集；
• recur:weekday、soww、eoww的取值全部跟随workweek动态变化。

对于存量用户，weekstart=sunday|monday的语义大致可映射为workweek的一种特殊情况，设计上需要做好向后兼容的过渡方案。

演进状态

按照文档头部的声明，本设计文档仍处于Work in Progress（进行中）状态，内容可能继续调整；一旦定稿，该功能才会被排入后续某个版本的发布计划。因此，workweek、soww、eoww目前属于设计提案而非已实现功能，生产环境使用仍应以现有weekstart（sunday/monday 二选一）为准。关注这一 RFC 的读者，可以持续跟踪 doc/devel/rfcs/workweek.md 的版本变化，并在功能落地后按本文的推导关系配置自己的工作日列表。

• 开发工具