zephyr-routing

概述

路由会处理包含混合内容的文档，并将每条 Zephyr 记录发送到相应的烘焙日志。

此技能刻意设计为独立模块，因此可以替换为不同的路由实现，而无需改动 [[zephyr]] 技能。

文件名解析、重量记法、event_time 标签和参数优先级由 [[zephyr]] 技能负责；路由会使用这些规则，但不会重述它们。

路由前请先阅读 [[zephyr]] 技能，了解烘焙日志的命名约定和参数默认值。

参数

• mode — move 或 copy；默认值为 move
• 烘焙日志目录 — 根据 [[zephyr]] 技能的“参数”部分解析

触发条件

仅在收到明确请求时才进行路由。

切勿仅仅因为打开了烘焙日志或其他文档，就自动进行路由。

请求可以授予会话级的持续指令，例如“接下来持续路由各条记录”——仅在该会话期间遵循此指令。

以下请求会触发路由：

• “路由此日志中的 Zephyr 记录”
• “将烘焙日志 6-10 中的 Zephyr 记录路由到各自的日志”
• “将 Zephyr 9 记录移出此文件”
• “整理此日志中的混合记录”

以下请求不会触发路由（即使涉及 Zephyr 记录）：

• “更新此日志中的事件时间”——这属于 [[zephyr]] 技能
• “为 Zephyr 记录添加 event_time 标签”——这属于 [[zephyr]] 技能
• “应用 Grafana 注释”——这属于 [[grafana-bake-annotation]] 技能
• “更新 Grafana 链接”——这属于 [[zephyr-grafana-links]] 技能
• 出于任何其他目的打开或阅读烘焙日志

识别

一条记录由一个时间戳标题及其下方的正文组成，直到下一个标题为止。

源文档中的记录位于 H2 标题下，而已归档在烘焙日志 ## bake log 部分中的记录位于 H3 标题下。

正文中包含“For Zephyr N”或“For Zephyr N-M”形式键值的记录即为 Zephyr 记录。

没有 Zephyr 键值的记录绝不会被触碰、移动或修改。

这些记录的缺失不属于问题；不包含此类记录的文档只是普通文档，无需报告为问题——请参阅 [[zephyr]] 技能中的“哨兵缺失”。

解析

根据记录标题中的日期解析每个键值，而非使用当天日期。

选择不晚于标题日期、日号相同的最近日期。

示例：“Zephyr 31”位于 6 月 1 日标题下时，应解析为 5 月 31 日，而非 6 月 31 日。

根据 [[zephyr]] 技能中的“烘焙日志命名约定”，将键值解析为文件名。

创建缺失的目标

如果解析出的烘焙日志不存在，则创建该日志。

仅创建最简结构：一个 ## bake log 部分，其中以 H3 标题收录已路由的记录，不添加其他内容。

不要生成菜谱布局——搭建菜谱框架是一个有意为之的独立步骤。

插入

将路由后的记录放到目标文件的 ## bake log 部分下，并将标题从 H2 降为 H3，使其嵌套在该部分中，而非与之并列。

将记录正文中的任何子标题降一级，以保持其为所属记录的子标题。

该部分中的所有 Zephyr 记录按时间倒序排列，最新的在前。

按正文中注明的事件时间排序；若正文未注明时间，则使用标题时间戳。

去重

先对记录进行规范化（重量记法遵循 [[zephyr]] 技能），然后进行比较。

若目标文件中已有一条记录，其标题时间戳、Zephyr 键值和规范化后的正文都相同，则跳过该记录。

覆盖语义

只有当较晚的备忘录是对同一事实的重述或更正时，它才会取代较早的备忘录。

若符合此条件，则保留较晚的记录并删除较早的记录。

时间戳相同或接近的两条记录若记述的是不同事实，则都应保留——仅凭分钟相同绝不能推定存在覆盖关系。

若不确定某条记录是否取代了另一条，则两条都保留，并向用户报告这对记录。

模式：移动或复制

在移动模式（默认）下，每个路由到目标文档的条目都会从源文档中移除。

在复制模式下，源文档保持不变。

删除空源文档

空内容会导致删除源文档，而不是影响路由。

路由是导致源文档变空的原因之一，但并非唯一原因。

检查会在请求的最后执行一次，在所有从源文档中移出条目的步骤完成后进行——包括此技能不负责的步骤。

请求通常会将路由与后续步骤配合使用，例如将未路由的条目移到其他文档。

这些条目也会离开源文档，因此检查会等该步骤完成后再进行。

文档在没有标题和正文内容时即为空——仅包含空白字符或末尾换行符也算空。

仅在以下两项均成立时删除源文件：

• 模式为移动，而非复制
• 请求结束时文档为空

是哪一步将其清空并不重要，此技能是否路由了任何内容也不重要。

如果源文档没有路由任何条目，且后续步骤将其内容全部移出，也会删除该文档。

如果源文档在请求开始时已经为空，也会删除该文档。

只要仍有任何内容，就保留文件。

即使所有 Zephyr 条目都已路由出去，只要还剩一个标题、一行正文或 frontmatter，就足以保留该文件。

写入时规范化

条目写入目标文档时，应用权重标注规则。

对于记录离散烘焙操作的条目，按照 [[zephyr]] 技能添加 event_time 标签。

提交

提交每个已修改的烘焙日志，每个文件单独提交一次。

对于源文档：

• 如果已修改但未删除，将其作为单独提交提交。
• 如果已删除（移动模式下的空源文档），将删除作为单独提交提交。
• 如果未更改（复制模式），则跳过。