《每周一龙》写作风格指南
本文档基于对全部 54 期《每周一龙》约 1,836 条报道的定量与定性分析， 总结归纳了本栏目的写作风格规范。风格会随时间演化，本文档反映的是截至 2025 年初的整体面貌。
本文档中凡是涉及自然语言层面的讨论与决策，如句式、措辞、语用等，都仅适用于简体中文内容（zh-Hans
locale）的撰写与审校，原因是截至 2026 年 TWiL 仅有简体中文版。如未来 TWiL
获得了其他语言的翻译或原创内容，针对那些自然语言的句式、措辞、语用讨论与决策，将在那时被另行补充至适用于它们的《自然语言风格指南》，以及本文档。
本文档中其他的规范性内容，如报道准则、科普尺度等，与自然语言无关，故适用于所有当下及未来的 TWiL 语言版本。
本文档的读者包括《每周一龙》的人类编辑与AI 智能体协作者（笔者使用的编码助手）。 目的有二：
- 帮助人类编辑保持风格一致性；
- 告诉 AI 智能体在代写初稿时应遵循何种模式。
分析工具
本风格指南基于本项目仓库中 scripts/analyze-newsletter.py 的计量结果编写。该脚本解析全部周报，输出每条目的字数、句数、超链接挂载于动词上的比例、编辑语气检测、科普深度等指标。复现命令见脚本顶部的文档字符串。
篇幅简明
每个条目的长度
| 统计量 | 数值 |
|---|---|
| 平均字数 | 51 字 |
| 中位字数 | ~35 字 |
| 平均句数 | 1.5 句 |
| 正好 1 句的条目 | 66.1% |
| 1-2 句的条目 | 87.6% |
绝大多数条目只有一到两句话。如果一个条目超过了 3 句话，应当考虑拆分（前提是不影响可读性），或确认其确实构成一个不可分割的报道单元。
篇幅的指导原则
- 常规报道条目控制在 1-2 句，20-80 字。
- 我们信赖读者群体有基本的开发技能，且能检索基本的陌生概念，因此不要对所有概念都做科普性质的补充说明。对于可补可不补的说明，我们倾向于不补。请仅在以下情况下补充信息：
- 无法再预期读者自行得到结论：复杂的技术或非技术细节；不涉密、可披露的内幕消息；复杂的逻辑链条等。
- 可能或已经造成重大影响的事件：解释背景、原因、影响。
- 若必须补充说明，可追加 1-2 句，但总量不宜超过 5 句。
- 位于 Markdown 列表中的条目通常更短：30-40 字，以适应作为列表浏览。
- 每期平均 25-50 条目；合订本可达 60-190 条。
关于上文所述「复杂的细节」，把握标准为：如我们预期目标读者需跨 3 个或更多信息源（包括但不限于文档篇数、程序中函数等的个数、联系人数……）才能独立查证一个细节，则该细节属于「复杂的细节」。
关于上文所述「复杂的逻辑链条」，把握标准为：如一条逻辑链条满足下列任一情况，则该逻辑链条属于「复杂的逻辑链条」：
- 对目标读者而言结论反直觉；
- 结论有 3 个或更多逻辑分支；
- 为得到结论需要的推理步数大于等于 3；
- 为得到结论需要援引跨学科知识，或跨单一学科内不同专业方向的知识。
- 跨学科知识的例子：需要了解生物信息学或计算化学的某个算法，才能证明某编译器或库优化确实有利于原作者所声称的某场景。
- 跨单一学科内不同专业方向的例子：如需要了解高可靠场景编程或游戏编程的某个细节，才能得出某编译器或内核变更的合理性。
句式
主导的句式模板
报道类条目几乎全部遵循以下模板：
X 月 X 日，谁[动词了](链接)什么……。
谁以/用/通过/……什么，[动词了](链接)什么……。
谁[动词了](链接)什么。这解决了/代表着/意味着/……什么……。
示例：
Huacai Chen [发出了](https://lore.kernel.org/...) 适用于龙芯 3 号处理器的自动调频驱动。
Xi Ruoyao [修复了](https://gcc.gnu.org/...) LoongArch 硬件断点的几个实现问题。
Bibo Mao [实现了](https://lore.kernel.org/...) KVM 半虚拟化快速自旋锁。
链接的位置
- 55.3% 的链接直接挂在句子的中心动词上——这是最标志性的风格特征。
- 不合适挂在中心动词上的链接，或一个句子里涉及到的多个次要链接，才被挂在名词短语上。如：
X [提出了](url1)……，见[上游的跟踪 issue](url2)；X [解决了](url1)先前 Y [提交的](url2) Z 的 XXX 问题；X 做了一系列重构：[甲]、[乙]、[丙]。
- 在撰写每个句子时，总是应当优先将超链接挂载在句子的中心动词上，必要时请优先为此组织语言。
高频中心动词
已发布内容中被挂载链接的最高频的 10 个中心动词如下，供参考：
修复了(96)、增加了(47)、贴出了(29)、提交了(24)、优化了(19)、
发布了(18)、实现了(18)、发出了(14)、合并了(12)、允许了(12)
优先使用具体动词
增加、添加、新增、优化等动词都是高度抽象的动作描述，无法传递贡献者究竟做了什么的实际信息。
当遇到这些动词时，应优先考虑是否存在更贴切的具体动词。仅在没有更合适的选择时，才可维持使用这些抽象动词。
特别地，遇到 添加 时，几乎总是应当将其改为 增加，以贴近存量语料的写作风格。
推荐的替换方向：
| 实际动作 | 优选动词 |
|---|---|
| 实现了某项硬件/驱动/子系统支持 | 实现了、引入了 |
| 实现了某项功能/特性 | 实现了、提供了 |
| 启用/开放了某个配置项或能力 | 启用了、打开了 |
| 编写了新的测试或文档 | 编写了 |
| 移植/接入了某架构支持 | 移植了、引入了 |
| 扩展/泛化了既有功能 | 扩展了、泛化了 |
| 实在无法归入以上类别 | 维持原样 |
提交了 只描述「发出了补丁」这一动作，通常不能用来明示或暗示「代码已合入」。除非这样说：「向中心仓库提交了……」，但比起专门动词如「合并」显得冗长。
因此如作者想传达「补丁已合入主线」的意思，应优先使用 合并了 之类的写法。
动词的体态、时间状语
- 绝大部分被报道的事件已经结束，因此最自然的选择是完成体（动词 + 「了」）。
- 对存在明确时间戳的事件，请明确写出时间状语，最好写在句首：
**X 月 X 日，XXX 修复了 XXX 的 XXX……。 - 对发稿时仍在进行中的事件，请给出当前时间参照：
截至目前（X 月 X 日 XX:XX），……或截至发稿时（X 月 X 日 XX:XX），……。 - 位于 Markdown 列表中的条目有时被省略了句尾的句号，但仍保留动词完成体标记
了。
编辑评论
何时进行评论
约 10% 的条目包含明确的编辑评论（不含独立的 :::info 块）。
编辑评论在以下场景出现：
| 场景 | 典型用语 |
|---|---|
| 感谢贡献者 | 辛苦了！、欢迎欢迎！、让我们感谢…、（感谢 … 的线索投递） |
| 更正/道歉 | 更正声明、有失偏颇、在此谨向…道歉 |
| 解释事物意义 | 这意味着…、鉴于此…、因此… |
| 提供历史背景 | 从前…、先前…、在…的年代 |
| 推测/分析 | 大概率…、笔者猜测…、笔者认为… |
| 代码质量评议 | 不可接受、遑论、优雅不能当饭吃 |
| 主编点评 | 对 ABI 决策、工具链变更等重大事项的专门评述 |
:::info 块的使用场景
- 技术深度剖析：解释某机制如何运作（如链接器松弛的原理）
- 历史背景：提供事件的前因后果（如某 PR 为何推迟）
- 更正/澄清：对之前报道内容进行补充或修正
- 主编点评：对重大设计决策发表看法
- 引用声明：如版权合理使用声明
:::tip块用于轻松的花絮或小知识
编辑评论的指导原则
- 编辑语气应自然、有节制。不要给每一条都评论。
:::info块应有明确标题（使用:::info[标题]的语法），其内容应相对独立。- 纠正先前报道时，使用
:::info[更正声明]格式，使用正式、负责的语气与措辞。 - 致谢应真诚而简洁，避免浮夸。
科普
当前科普深度分布
基于对 1,836 条目的自动化分类：
| 科普深度 | 数量 | 比例 |
|---|---|---|
| 无科普（纯报道） | 1,226 | 66.8% |
| 浅度科普（1 个解释线索） | 337 | 18.3% |
| 中度科普（2-3 个解释线索） | 201 | 10.9% |
| 深度科普（≥4 个解释线索） | 72 | 3.9% |
科普率呈上升趋势：2023 年 28.0% → 2024 年 38.7% → 2025 年（早期数据）40.3%。
什么内容需要科普
以下的话题通常伴有深度科普：
| 话题 | 举例 |
|---|---|
| Linux 的内部机制 | 为什么 LoongArch 用 statx 而不是 fstat；vDSO getrandom 的安全性；半虚拟化如何实现 566% 的性能提升 |
| 设计决策 | 为什么 R_LARCH_CALL36 保持其编码；「PC-relative」与「PC-aligned」的语义差异；为什么从未添加 pcalau18i |
| 编译器优化原理 | 为什么 bstrins 优于移位+掩码；链接器松弛与 -mexplicit-relocs 的相互作用；GCC CoreMark 性能劣化事件的四个独立根因 |
| ISA 设计 | FP16/FP128 编码空洞的指令位域分析；LA464 的 32 位除法未定义行为及 LA664 是如何修复它的 |
| 细节或非技术的背景知识 | BOLT 是什么；龙架构文档仓库的状态为何使 binutils 变更受阻 |
以下内容通常不需要科普，纯报道即可：
- 常规缺陷修复（
修复了…后不跟因为…） - 简单功能添加
- 发行版新闻（
X 发布了 ISO） - 大多数 LLVM 或其他项目的 单条补丁
- 相对不严肃的内容：社区整活儿、游戏测试等
科普的推荐结构
当需要科普时，建议遵循「三段式」：
- 事实（1 句，完成体）：X [做了](链接) Y。
- 为什么重要 / 如何运作（1-3 句，以下仅为一种可行的框架，请不要机械遵循此措辞）：这是有必要的，因为 Z。这意味着…
- 影响 / 建议（0-1 句）：因此，用户应该… / 这将启用…
科普的量化标准
自动化脚本检测标志性的词语的数量来估计科普深度。共有七类标记词：
| 类别 | 标记词示例 |
|---|---|
| 原因 | 因为、由于、这是因为、原因是、具体来说 |
| 后果 | 这意味着、这会导致、其作用、其目的是 |
| 目的 | 用于、以实现、来达到、从而、以便 |
| 对比 | 相比之下、与…不同、而非、而不是 |
| 时间 | 先前、此前、过去、原本、现在、随后 |
| 定义 | 是一种、指的是、对应、等同于、相当于 |
| 情态 | 需要、要求、必须、应该、可以 |
| 计数 | 评价 |
|---|---|
| ≥ 4 | 深度科普 |
| 2-3 | 中度 |
| 1 | 浅度 |
| 0 | 纯报道 |
举例
纯报道（无科普）
Tiezhu Yang [修复了](https://lore.kernel.org/...) 用户态断点对线程标志
TIF_LOAD_WATCH 处理的一些细节。
轻度科普
Hui Li [修复了](https://lore.kernel.org/...) LoongArch 硬件断点的几个实现问题。
中度科普
7 月 5 日，Sui Jingfeng [合并了](https://cgit.freedesktop.org/...) 龙芯显示控制器 DRM 驱动。
他在前一天[拿到了](https://gitlab.freedesktop.org/...) drm-misc 仓库的合并权限。
这意味着集显用户应该能用未来的上游内核亮屏了；2D/3D 渲染加速是另外的工作。
深度科普 + 编辑评论
参见历期 :::info 块中关于链接器松弛、ABI 设计决策、ISA 指令编码分析等长篇论述。
这类内容通常位于独立的注释块中，而非内嵌于报道条目。
报道准则
来源链接
TWiL 的每条报道必须带有至少一条来源链接。 这是为了读者可以自行验证、深入了解报道内容，也便于后续追溯。但过渡段落、栏目介绍等模板内容不在此限。
此规则适用于所有栏目，包括 社区整活:儿:。如果内容没有公开链接可引用，则说明编辑无从得知此事，也就不可能被写出。但如果真的存在确实值得报道、但仅见于非公开渠道（如微信聊天记录，微信不支持导出群聊记录为公开链接）的内容：
- 编辑必须先向原作者征得转载许可。
- 获得许可后，编辑应以截图或其他适合引用的形式将内容搬至公开可见的地址，并在报道中引用该地址。
- 编辑不得猜测或编造 URL。如无法合规地提供来源链接，该报道条目必须被删除。
AI 智能体在处理无链接的报道条目时：
- 如果可帮助用户查找到等价的公开来源（包括但不限于 lore.kernel.org、GitHub PR），必须明确告知用户 自己查到了链接，并请用户二次确认，以防幻觉。
- 如果无法查找到等价的公开来源，必须向用户报告，并请求用户提供链接；不得绕过此步骤直接发布。
- 在提交说明中记录链接来源的获取方式（自行查找并提供链接 / 用户提供 / 无法获取、已删除）。
补丁集的报道粒度
补丁集（patchset）是 Linux 内核与工具链新闻的主要素材来源。为保证用户可高效扫读内容，请您：
- 只报道最新版本中出现了重大变化的修订。 「重大变化」指：
- 设计方案大改；
- 在相似设计下重写实现；
- 从他处接管了上游工作（作者变更）；
- 其他不可被解释为小修小补的变更。
- 常规的审阅跟进、小幅修正（如拼写修正、补充注释、cc stable 的添加与移除等）不构成报道条目。
- 如果某补丁集在前几期已被报道过，且本周的新版本无重大变化：删除该条目。
- 换言之，只有以下性质的内容才算作「新闻」。常规跟进工作不算。
- 实质性工作的首次公开亮相或重大变更；
- 实质性工作的正式发布：合入主线、包含它的新版本被 tagged；某发行版提前交付了此功能；……
此规则意味着：大多数来自其他通讯或原始采编素材的「v1 → 审阅 → v2 → 审阅 → v3」链条，要么会被缩减为至多一句话（如果最新版本有实质性变化），要么整个条目被移除（如果最新的变更只是第 N 次的小修小补）。
向后移植（backport）补丁集的特殊处理
向后移植（backport）的补丁集是上述规则的一个例外。虽然此类补丁在内容上与先前报道过的补丁相关，但它们是独立的补丁集， 且对下游发行版维护者具有实际价值：
- 一套向后移植补丁集的首次提交和最终合入通知，算作「新闻」，应当保留。
- 向后移植补丁集内部的例行修订（如拼写修正、cc stable 调整）仍然遵循常规的报道显著度规则，不构成报道条目。
在 AWLY/TWiL 的范畴内，backport 统一译为「向后移植（backport）」而非「回合」。 「回合」更常见的义项是「轮次」（n. turn, round），在「backport」的语境下会产生歧义。 请在 AWLY/TWiL 的范畴内统一使用「向后移植」表述，在首次提及时请一并注明英语术语。举例如下：
- 动词用法：
将其向后移植（backport）到了； - 名词用法：
向后移植（backported）补丁。
详见自然语言风格指南。
改写来自其他通讯的投稿
有时贡献者（包括新编辑）可能同时为其他 LoongArch 通讯供稿。这些通讯的读者群体不同， 导致原始稿件的风格可能与 TWiL 存在系统性差异：
- 面向非技术读者的通讯往往含有大量术语解释，即便这些术语对做 LoongArch 适配超过 3 个月的开发者都很熟悉了；
- 疑似 KPI 驱动的内容有时甚至对代码审查的每个轮次、所有正常的研发跟进工作等细枝末节都作追踪报道；
- 相对地，TWiL 面向技术读者，期望读者能够自行查阅链接或背景知识，且每条目应当相对独立、可扫读。
典型差异与处理方式
| 差异 | 其他通讯的风格 | TWiL 的处理方式 |
|---|---|---|
| 审查周期 | 追踪 v1→审阅→v2→审阅→v3 的完整过程 | 适用补丁集报道粒度：仅保留有实质性变化的最新版本；无实质性变化则整条删除 |
| 术语解释 | PR_SET_SYSCALL_USER_DISPATCH（是一个 Linux prctl 操作，用于…） | 删除括号或单独成句的解释。如果某个概念确实对 TWiL 目标读者而言需要科普，则撰写单独的 :::info 块 |
| 覆盖面 | 详尽的列表（如 Box64 一个周期内的全部 11 条 PRs） | 挑选 2-3 个最重要的亮点；其余可省略或用一句话概括 |
| 动词选择 | 添加了 | 优先替换为更具体的动词（实现了、启用了、引入了 等）；仅在无合适替代时使用 增加了。参见优先使用具体动词。 |
| 编辑声音 | 中性、冷调、无评论 | 如果有值得评论的内容，可补充 :::info 或简短的「这意味着…」；不强求 |
风格适配检查单
收到面向其他通讯撰写（或受其风格影响）的原始稿件时，按以下步骤处理：
- 应用补丁集粒度规则：将包含多个补丁版本或审查轮次的条目拆分或删除。 只保留有重大变化的最新版本（设计大改、实现重写、作者变更等）； 常规跟进工作（拼写修正、cc stable 增删、审阅往返）应被整条删除。
- 检查来源链接：确保每条报道条目至少有 1 条来源链接。
对无链接的条目：自行查找链接并请用户二次确认，或向用户请求提供。无法提供链接的条目应被删除。
需要遵守来源链接的全部可追溯性约束（包括
社区整活:儿:栏目的公开可溯源要求）。 - 精简内联科普：一般需要把括号解释（
（是…，用于…））移除。 如确有必要为 TWiL 受众解释某概念：将其扩展为独立的:::info块。 - 裁减冗长列表：将过长的条目列表（如某个项目的每笔提交都被单独列出）精简为 2-3 个重点。如有可能，连 Markdown 列表格式也一并放弃，改写为自然段。
- 统一措辞：检查并替换偏离风格指南的关键词汇。尤其是将抽象的
添加/增加替换为更具体的动词（如实现了、启用了、引入了）；仅在无合适替代时保留增加。参见优先使用具体动词。 - 检查栏目完整性：确认所有必备栏目（
先「马」再看、杂闻播报、张贴栏）均存在。社区整活:儿:不是必须的栏目：如果本周没有足够有趣的社区内容，不强求，可将其省略。 - 按需补充编辑评论：如果本期有值得深度探讨的技术话题：额外撰写 1-2 个
:::info块。 如果自然出现了值得感谢的贡献者或值得评论的代码质量话题：感谢或评论它们，使用既定的编辑语气。 不强求——对于不合适的一期内容，宁可保持它的干货风格，也不生硬彰显编辑个性。 - 修复元数据：确认
slug、date、draft状态等 frontmatter 字段正确无误。