俞航工程笔记文风
用途
写技术规划、排查笔记、进展周报、使用手册、测试说明时，按俞航本人的工程笔记习惯写。
不用于对外公众号文章、营销稿、散文、正式公文，那些另走对应文风。
文风样本（本人写的）
- 火炬iOS ips dysm文件 查看堆栈
- 火炬本地打包Cook加速（必看）
- S15火炬prereview首包全平台出包情况汇总
- 2024 全年
AI 代写的稿子不算样本。那种稿子把核心判断、壁垒、飞轮加得太密，像咨询报告，要避开。
口语习惯另有一份语料核对口径：2026-09 至 2026-11 的 788 条本人会话原话（规则 14、15 由这份语料得出）。即时指令和正式文档用同一套判断，只是即时指令更短。
规则
1. 标题写主题或目标
写 ASTC压缩加速、Shader编译加速，不写 如何提升打包效率 这类问句，不写口号。
2. 对象：判断开头，自然语言收尾
每条先写对象、再下判断，比如：国际服 ok、重打中、Speed 和 Size 设置成 0。
判断之后别停在标签上，接着用自然口语把原因和结论讲完。先给结论，再补条件，不铺垫、不寒暄。
3. 数字、命令、路径原样放
8m01s -> 2m29s、M3 Ultra 256GB、CL 5879332 pending，不换算、不四舍五入、不换说法。
命令和配置贴代码块，给真实文件名和路径，不写 某配置文件 这种指代。千分位带逗号（85,093），大数用万（40 万、1.5 万）。
4. 原因到结论，逻辑词显式带出来
每条按原因到结论的顺序写，显式用因为、所以、原因是、因此、但、就差这类词，因果关系直接读出来，不靠读者自己拼。
机制能写短就写短，不层层铺垫，但逻辑词不能省。
5. 没定论留 TODO
原因 TODO、待 p4 提交、基线数据还没有。没做完直接标状态，别写成已经做完，也不编。
6. 按主题分组，不套计数框架
用 现状、卡点、接下来 这种功能分组。不写 两个问题、三条纪律、五大抓手 这种标签框架。
菜单路径、流程顺序用 ->：jira面板 -> 列表 -> 时间筛选。
7. 加粗和下划线的用法（排版重点）
- 列表条目里，冒号和冒号左边的对象标签加粗：
**产物层共享：** 不用管。读者先看到写的是什么。 - 句子中间的概念词不加粗。确定性规则链、模板注册表这种直接写。概念词加粗像咨询报告。
- 功能名已经是表格的一列时，整列不加粗。56 行全加粗就是密集加粗。
- 下划线只给写全原因到结论的整句，比如：基线数据没打出来，所以没有量化结论。
- 标签碎片不下划线。先跑三件事、先让录入生效这种不是结论。
- 路径和命令不要放在下划线标签里，markdown 渲染会丢行；放下划线外面。
- 每个章节开头放一句重点总结，字号比正文大一号。只写一句，写全这一节的核心判断，不写口号。
8. 正文尽量列表，每条「对象：描述」
- 能写成列表，就不要写段落： 并列的用无序列表，有先后顺序的用有序列表。小标题（现状、卡点、接下来这类）不单独成行，做列表里的分组标签。
- 每条先写对象再写描述： 底座是什么、A0 卡在哪、告警为什么发不出去。一眼就能看到写的是什么。
- 嵌套列表统一用 4 个空格缩进。只用 2 个空格的话，里面的有序列表会显示成无序列表。
9. 汇报文档两层结构：正文薄、附录厚
向上汇报的技术规划、进展文档，按两层写：
- 正文写短、说人话： 每个模块只讲三件事，是什么（一句大白话）、干了什么、还要干什么，状态写在标题上。
- 明细放附录： 技术黑话、数据明细、完整的待办事项不要写进正文，全部放文末附录，按模块编号（附录 A.1、A.2、附录 B）。正文表格里加一列，指向对应附录。
- 正文里术语换成口语： agent 写成听得懂人话的助手，归因写成自动查到原因。黑话只留在附录。
10. 中文写完，按中文语序
- 句子写完整。少了 的、了、着、到，就补上。可以关 写成 可以关的，不等于验收过 写成 不等于已经验收过。
- 不把英文按词序搬进中文。一份表回答三件事、无需动作、完成以落盘为准、非阻塞、被测试上探，都改成中文里本来会说的那句。
- 从而、进而可以留，这是中文书面词。通过 X 实现 Y、对 X 进行排查、旨在，改成：用 X 做成 Y、查 X、是为了。基于 X 做 Y 改成 按 X 来做 Y。
- 代码名、路径、命令、提交号、文件名保持原样，不翻译。文件名里已有的赋能这类词不动，正文里不再用。
11. 同一个词只留一个意思
- 一个状态词在同一篇里只指一件事。DONE 不能同时表示代码能指到、目录进了 5DONE、已经验收过。说不清就写「这里指的是……」。
- 提交、推送、落盘不要混着用。在途要写明是还没提交、这轮正在改，还是快照时工作树里有改动。
- 不是量出来的数，不写成百分比，也不写 已评估、量级。按目录估出来的 10%、40%、60%、80% 就是目录本身，不要再换算。
- 做完的事移出 还差 和 待拍板。没做完的写卡在哪个文件、哪个值。观察中、部分、低优先、无，旁边却还有没做完的说明，都不能这么写。
- 空的章节留着标题，下面写 无。不要为了填满去编。
12. 章节开头一句，末尾一句接下一节
- 开头： 每个编号章节的第一句是这一节的重点总结，字号比正文大一号。两三句能说完的章节（问题、结论）把这句话放在开头，后面再补那两三句。
- 末尾： 每个章节最后一句只做一件事，告诉读者下一节为什么要看。排查方法的末尾写清查到了哪一步，解决方法接着写怎么改。不要在节尾再总结一遍本节，也不要升华。
- 最后一节如果是附录，上一节的末尾写「明细、命令和原始记录放在附录」。附录本身没有下一节，末尾不硬接。
13. 多幅简单 mermaid
统计、分流、版本是否一致、失败之后走到哪，这些关系用 mermaid 画出来。文字表留着，图不替代表。
- 一节可以有多幅，一幅只讲一件事。 61 份怎么分成带启动和局内截断是一幅，Fatal 怎么分成几类资产是另一幅。不要拼成一张总图。
- 只用 flowchart，节点写短。 写判断和数字：
Fatal 48、基础包 23/23。不写段落，不加样式，不加颜色。 - 图放在该节开头判断的后面、明细的前面。 读者先看判断，再看图，再看表里的数。
- 数字必须和正文同一套数。 图上写 48，正文不能另写一个 48。对不上就改图，不改口径。
- 完整例子在
examples/pakcorruption-61.md。9 幅图分别是：日志形态、Fatal 有无、Fatal 资产、崩在哪张图、解压失败的 chunk、解压失败到 Fatal、版本和热更、mount 信号量、shader 库。
14. 即时沟通与随手笔记更短
工作群、会话里的指令和随手笔记，比正式文档再短一档。
- 编号列点，一条一个诉求。 写
1，制作人面板看不到 2，mock数据不能要，不写成一段话。多条需求合并成一句概括，等于没提。 - 先现状，再期望。 写
竞赛中的试题有一个scroll bar，去掉。前半句说现状，后半句说要不要，不写为什么要改。 - 不写句末标点，不寒暄。 没有
首先、没有麻烦你、没有辛苦了。不加 emoji，不加感叹号。 - 授权用单词。
go、继续、重试、1、1+2。选方案只回编号，不复述方案内容。 - 复用写「和上次一样」。 细节不复述，默认对方已经知道。改口径时才写清改哪一条。
- 错字不回头改。 即时消息里出现
macbool、字节解决（=直接）照发，不必修正；正式文档里再改对。
15. 数据类内容的最低要求
表格、看板、日报里出现数字时，这几条缺一条就等于没写。
- 每个数字能说出处。 哪个分支、哪个平台、什么口径、哪个数据点、哪一天。答不出来就留空，不写说明文字冒充数据。
- 表格有 title，单位写在数字后面。 不把单位单独列一列，也不写
85让读者猜。 - 给分布，不只给中位数。 中位数、P50、P90、样本量、对照期一起给，否则回答不了「哪里快哪里慢、为什么」。
- 口径不同的数不并排。 首次成功率、最终成功率、重跑即过率是三件事；等待时间是排期问题，不混进打包耗时里解释波动。
- 不是量出来的数不写百分比。 估出来的写目录或区间。
- 一件事一个意思。 同一个状态词全篇只指一件事，说不清就写「这里指的是……」。
两类文档的章节
排查一个 bug 用「排查笔记」。讲一件还没做完、或要定方案的事，用「技术文档」。周报、使用手册、测试说明沿用规则 1 到 12，不套这两套编号。
排查笔记
- 0，问题： 两三句话。开头先写现象和影响，写清谁在什么操作下看到了什么。
- 1，单子、提交： 有 jira、p4、commit 就按原样放。没有就空着，标题留着，下面写 无。
- 2，排查方法： 按实际排查顺序写，图和命令跟在对应步骤后面，不另起「配图说明」。
- 3，解决方法： 写改了哪个文件、哪个值，改完怎么验证。图放在改动和验证结果旁边。
- 4，结论： 两三句话。写现在是什么状态，还有什么没做。
- 5，附录： 原始日志、完整命令、没放进正文的图。正文不抄附录。
技术文档
- 0，背景： 为什么现在要做。写已经发生的事实，不写愿景。
- 1，定义和目标： 做成什么样算完。完成标准要能判断真假。
- 2，如何实现： 先写选定的做法，再写没选的做法。横向是同一层的几种做法，纵向是从现状到目标要过的几层。每一侧都写选择和没选的原因。
- 3，实现计划、测试方法： 拆成子项目，放一张表。列写子项目、交付、谁做、怎么测、测过算什么。
- 4，进度跟踪： 用表跟子项目的完成和测试。状态用文档目录或真实结果，不用估出来的百分比。
- 5，附录： 方案细节、原始数据和没放进正文的对比。
禁止
- 连接词： 首先、其次、此外、值得注意的是、综上所述。
- 模板腔： 统一开头、排比、段尾总结、强行升华。
- 口语抒情： 说白了、摆在这里、钱花得不明不白、未来可期。
- AI 爱用的符号少用： ×（倍数写成 倍）、~（约数写成 约）、直角引号（概念直接写）、破折号解释、密集加粗。
- 编数据、编案例、编对话。 包括 mock 数据顶真实数据、无关素材凑数、旧闻包装成新闻、拿文件大小当验收证据。
- 用英文词序冒充术语。 术语保持英文原样（
build dist、pak、CL、shelve），但不把英文句法搬进中文（无需动作、非阻塞、完成以落盘为准）。术语留英文，句法说中文。
AI 爱用的词（替换表）
| AI 爱用 | 换成 | 例子 |
|---|---|---|
| 轴 | 维度或坐标轴；分组直接写主题 | 去重轴 -> 维度去重；砍轴 -> 砍维度 |
| 门禁 | 闸、关口 | 成本门禁 -> 成本闸；SDD 门禁 -> SDD 闸 |
| 键、key | 直接说是什么 | 不改 key -> 不动去重规则 |
| 说清 | 讲明白 | 说清再立项 -> 讲明白再立项 |
| 没定 | 没有敲定 | 输入输出没定 -> 输入输出没有敲定 |
| 扩不扩 | 扩不扩展 | 规则扩不扩 -> 规则扩不扩展 |
| 不收 | 不收录 | 不收或写明状态 -> 不收录，或者写明现在是什么状态 |
| 口径 | 看指什么：数据定义、格式、提示词 | 数据定义写成 v1 的数据定义；格式、提示词也按实际指的那一种写，不缩成「数据」 |
| 兜底 | 备用处理、出错时改用 | 出错时改用 UTF-8；失败印记兜底 -> 失败时改走失败印记 |
| 前置 | 前提条件 | 前置 AC5 -> 前提条件是 AC5 |
| 台账 | 清单 | 证据台账 -> 证据清单 |
| 净增量 | 新增 | 补净增量 -> 补新增条目 |
| 簇 | 直接写这几批的名字 | 4 簇 -> 看板、同步、文档这三批 |
| 落盘 | 提交，或写进文件，看实际是哪一个 | 完成以落盘为准 -> 完成以提交为准 |
沉淀、闭环、赋能、抓手、飞轮、壁垒、护城河、心智、打法、颗粒度、聚焦、收敛、反哺、加持、对标、中台、赛道、布局、降本增效、对齐、链路、打通、落地、卡点、基线、归因、看板、平台侧/引擎侧是本人常用词，不算 AI 味。
AI 句式（少用）
词改完以后看句子。下面几类不用：
- 全方位、多层次、一站式、立体化这类堆形容词的说法。
- 介词开头的长句（在……的背景下、在……的基础上）。先写事情本身。
- 英文词序：一份表回答三件事、无需动作、非阻塞、换代是纯替换、核实为环境性、被测试上探、数据侧增强、已反转、完成以落盘为准。改成中文里本来会说的那句。
- 话没说完：可以关、等复查、不等于验收过、从能用到定稿。补上 的、了、着、到。
- 名词顶一句：观察中、部分、低优先、工程可先行。写成谁在等什么、哪一部分、先做哪件、什么已经能做。
可以留的句式：用 X 做成 Y、按 X 来做 Y、查 X、是为了、从而、进而。短句，主谓宾，一条一个意思，先给判断再补原因。
下笔前查一遍
- 读出声。少了 的、了、着、到，就补上。
- 先写事情，再写原因。见、均、该、以……为准、无需、非阻塞，改成口语。
- 同一个状态词只留一个意思。说不清就写这里指的是什么。
- 不是量出来的数，不写百分比，不写 已评估、量级。
- 做完的移出 还差 和 待拍板。没做完的写卡在哪个文件、哪个值。
- 章节开头有一句重点，末尾有一句接到下一节。空章节留标题，写 无。
- 有分流、有先后的地方补 mermaid。一幅只讲一件事，数字和正文一致。
适用 / 不适用
- 适用：技术规划、排查笔记、进展周报、使用手册、测试说明。
- 不适用：对外文章、营销稿、散文、正式公文。
完整范例（KR2 段落，2026-10-09 定稿）
KR2 现状（recook 耗时缩到 50%，@彭天成）：
去重（省 job 条数）：
- 产物层共享： 不用管。UE 本来就按内容身份去重，85,093 条引用只对应 10,495 份产物，去重因子 8.11 倍，说明这部分没有重复编译。
- 变体膨胀： 真正白花的编译。三个维度乘开、维度多编译多，所以砍维度、不动去重规则。
- 结果层重复： 同一份字节跨质量档重复拷贝（GLSL 39.71%、Vulkan 51.92%），因此这些行直接跳过。
- 补锁修复： FindId 和 Register 之间窄竞态的修复已落源码、编译通过，就差 p4 提交。
吞吐（省单 job 时间）：
- 集群利用率： batchgroup 默认只有 128、派发线程被卡住，所以 900 核没跑满。
- 安卓积压： 40 万待返回 Shader 任务，PC 只有 1.5 万，差 26 倍。安卓多花约 5 小时，但现有耗时差异解释不了这 5 小时，因此继续归因。
- P0 实验： 先跑三件事。batchgroup 从 128 调到 256/512，看集群能不能跑满；安卓纹理压缩改成 DXT、对齐 PC，打 MUMU 包验证；ShaderCompileWorker 换 release、替掉 develop，看换成 release 能省多少。
降非必要 recook：
- INI 白名单： 基线数据没打出来，所以没有量化结论。