klog 格式规范深度解读：从日期、时长到开放范围的精确定义

klog 格式规范深度解读从日期、时长到开放范围的精确定义【免费下载链接】klogCommand-line tool for time tracking in a human-readable, plain-text file format.项目地址: https://gitcode.com/gh_mirrors/klog/klogklog 是一款采用人类可读纯文本格式进行时间追踪的命令行工具而 klog 格式规范文件格式规范 1.4 版正是它的核心灵魂。这份规范完整记录在 Specification.md 中任何符合规范的.klg纯文本文件都能被 klog 准确解析并统计出总时间。无论你是刚接触时间追踪的新手还是想把手账、工时记录迁移到命令行的高级用户读懂 klog 格式规范都能让你少踩坑、更高效。本文将从日期、目标时长、条目类型到开放范围逐层拆解这套精确定义的纯文本时间追踪格式。一、为什么值得先读懂 klog 格式规范klog 与传统时间追踪工具最大的不同在于它把数据文件当作纯文本数据库来对待所有时间记录都保存在一个.klg文本文件中你既可以用任何编辑器直接修改也可以交给 klog 命令行工具来解析、汇总和报告。先看一个完整的示例记录感受一下这套格式的直观程度2024-03-15 (8h!) 春季项目冲刺周专注开发 09:00 - 10:30 团队晨会 #meeting 2h30m 编码时间 1h 午餐休息 14:00 - ? 正在进行的任务短短几行就包含了日期、目标时长、摘要、标签、时间段、时长和开放范围——这正是 klog 格式规范定义的记录Record结构。接下来我们逐一拆解。二、klog 记录Record的基本结构一条 klog 记录必须是一个连续的文本块内部不能出现空行。它的第一行必须以日期开头同一行后面可以跟目标时长随后是可选的记录摘要和任意数量的条目。在源码中这个结构对应 klog/record.go 里的Record接口。2.1 日期格式的精确定义klog 格式规范要求日期必须包含 4 位年份、2 位月份和 2 位日期按年-月-日顺序排列且各部分之间只能用-或/分隔2024-03-15推荐写法2024/03/15等效写法两个值得注意的细节日期必须是格里高利历中的真实日期比如2023-02-30会被判定为非法另外-和/不允许混用例如2024-03/15直接报错。这一逻辑在 klog/date.go 的日期解析函数中实现。2.2 目标时长Should-Total的写法如果想给某一天设定目标工时可以在日期后面加一个括号包裹的目标时长(8h!)表示今天的目标是 8 小时(5h15m!)表示今天的目标是 5 小时 15 分(-3h30m!)目标也可以是负数它的语法就是一段时长加一个感叹号再用括号包起来。对应源码见 klog/shouldtotal.go。三、三种条目类型时长、时间段与开放范围klog 格式规范中的条目Entry是一个抽象概念实际落地为三种类型时长Duration、时间段Range和开放范围Open Range。源码中对应 klog/entry.go 的Entry类型。每条条目必须独占一行并以固定缩进开头。3.1 时长Duration的书写规则时长用来记录一段确定的耗时格式非常直观1h表示 1 小时5m表示 5 分钟4h12m表示 4 小时 12 分-8h30m表示负 8 小时 30 分用于扣减时间klog 格式规范里有几条容易被忽视的细节小时部分可以超过 24例如50h完全合法当出现小时时分钟不能超过 591h59m合法、1h75m非法但如果只有分钟则可以超过 59比如119m。默认时长为正数也可以显式写4h12m负数则必须加-前缀。解析与序列化的实现位于 klog/duration.go。3.2 时间段Range与跨天偏移时间段用两个时间点表示一段区间中间以-连接klog 格式规范推荐在破折号两侧各留一个空格8:00 - 9:0011:00am - 1:00pm23:40 - 3:12从前一天 23:40 到当天 3:120:30 - 4:00从当天 0:30 到次日 4:00规范的硬性要求是开始时间与结束时间必须按时间先后顺序书写两者可以相等。想要表达跨天场景就用前缀把时间移到前一天或用后缀移到后一天。时间段的核心逻辑在 klog/range.go 中接口定义同样位于该文件。3.3 开放范围Open Range的占位符规则开放范围是 klog 格式规范中非常实用的一项设计当你开始一项活动但还没结束时把结束时间用问号?占位即可9:00 - ?4:00pm - ??占位符可以重复书写例如9:00 - ???目的是方便与其他条目做视觉对齐。但有两个约束必须牢记占位符不能被跨天偏移不能写成?之类并且一条记录中最多只能出现一个开放范围。这是因为当用工具结束开放范围时如果存在多个就不知道要关闭哪一个了。开放范围的定义见 klog/range.go 的OpenRange接口它的开始与结束操作Start/EndOpenRange则在 klog/record.go 中。四、时间Time的精细规则24小时制与 am/pm时间值必须包含小时和分钟两部分中间用:分隔默认按 24 小时制解读14:18合法6:30am、2:00pm使用 12 小时制01:00表示次日凌晨 1 点klog 格式规范对时间还有几个硬性规定分钟必须在 0–59 之间且个位数要补零9:05合法9:5非法24 小时制下小时可为 0–2412 小时制下只能为 1–12特殊地24:00被解释为次日0:00但24:00是被禁止的写法。另外前面提到的前一天与后一天偏移是时间跨天的重要语法糖。完整的解析与比较逻辑位于 klog/time.go。五、缩进与标签容易被忽略的格式约束条目必须缩进一次才能被识别klog 格式规范允许三种缩进方式4 个空格推荐、2 或 3 个空格、或 1 个制表符。如果需要第二级缩进例如条目摘要换行书写缩进序列要出现两次。同一记录内部缩进风格必须统一否则解析器无法判断层级——这在规范脚注中有明确说明。相关解析逻辑可参考 klog/parser/txt/indentation.go 和 klog/parser/txt/line.go。标签Tag是 klog 分类记录与条目的利器可以出现在任何摘要文本中#gym、#home-office简单分类#ticket891带值标签#project22/48.3带引号的标签值标签名只能由字母、数字、_和-组成且不区分大小写标签值则区分大小写可以用引号包裹以容纳特殊字符例如项目编号或人名。标签解析实现在 klog/summary.go 与 klog/tag.go 中。六、文件组织多个记录如何存放一个.klg文件可以包含任意数量的记录记录之间必须用空行分隔。文件本身必须使用 UTF-8 编码换行符统一使用 LF 或 CRLF两者不要混用文件末尾建议保留一个换行。规范还强调文件中不允许出现格式规范之外的内容这使得 klog 文件可以完全被视为一种文本数据库便于程序化处理。七、总时间计算klog 的求值规则klog 格式规范对如何求和也有明确约定理解这一点能帮你避免统计偏差总时间 所有条目的累加正数增加、负数扣减重叠的时间段会被全额计入。例如12:00 - 13:00与12:30 - 13:30两条加起来是 2 小时不会去重跨天时间段全部计入记录日期当天不会拆分成两天开放范围默认不参与统计只有显式请求时才纳入计算。八、常见易错点清单 最后把最容易出错的几个点汇总成清单写文件时对照检查即可日期分隔符-与/不要混用有小时单位的时长里分钟不要超过 59开放范围?每记录只能出现一次且不能带跨天偏移同一记录内缩进风格必须一致不要一会儿空格一会儿 Tab记录内部不要出现空行记录之间要有空行文件编码务必是 UTF-8。结语让 klog 格式规范成为你的时间管理底座klog 格式规范的精妙之处在于它用极简的纯文本语法实现了人类可读、机器可解析的完美平衡。只要掌握了日期、时长、时间段与开放范围这几大核心概念你就能写出规范合法的.klg文件再配合 klog 的total、report、start、stop等命令实现自动化的时间统计。规范的完整定义可随时查阅 Specification.md而它的 Go 语言实现则分布在 klog/ 目录中从 klog/date.go、klog/time.go、klog/duration.go 到 klog/range.go每个概念都能在源码中找到一一对应的实现。现在就打开编辑器写下你的第一条 klog 记录吧【免费下载链接】klogCommand-line tool for time tracking in a human-readable, plain-text file format.项目地址: https://gitcode.com/gh_mirrors/klog/klog创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考