踩坑实录转录阿波罗 11 号历史汇编时为什么「修正 bug」是错、逐字对齐扫描件才对——GitHub 校对的硬规矩【免费下载链接】Apollo-11Original Apollo 11 Guidance Computer (AGC) source code for the command and lunar modules.项目地址: https://gitcode.com/GitHub_Trending/ap/Apollo-112019 年 7 月为纪念人类登月 50 周年阿波罗 11 号制导计算机AGC的原始汇编源码被上传到 GitHub连续数日霸榜 Trending吸引全球开发者围观那段把人类送上月球的代码。紧接着仓库迎来了两股洪流一是有心人发起的「找茬运动」二是夹杂着大量无意义灌水的 PR。仓库维护者随后亮出了一条与众不同的规矩——你来提的 PR 不是用来「改进代码」的而是用来让代码「更忠实于历史扫描件」的。这份由 Virtual AGC 社区与 MIT 博物馆合作、从纸质打印件手工转录而成的历史档案其校对哲学与今天的开源项目截然相反凡是扫描件上印着的哪怕是错别字也必须保留凡是转录过程中「顺手修正」的正确拼写反而必须改回错误。这篇文章从仓库实际源码出发拆解这套「反向校对」规则背后的三个常见踩坑点。从打印件到仓库一次必须「照抄」的数字化先说背景。仓库中存放的是两套程序指令舱的 Comanche055Colossus 2AAssemble revision 055 of AGC program Comanche by NASA与登月舱的 Luminary099Luminary 1AAssemble revision 001 of AGC program LMY99 by NASA。它们不是由编译器生成的产物而是由 Paul Fjeld 基于 MIT 博物馆保存的硬拷贝逐页转录、再由 Ron Burkey 等人整理成可被 yaYUL 汇编器重新编译的文本。CONTRIBUTING.md 在开篇就把基调定了下来The source code in this repository was digitized manually from paper printouts, so typos and other discrepancies have been introduced accidentally. The code shall be modified to be made consistent with the following scanned printouts.也就是说仓库承认转录过程会引入笔误与偏差而纠偏的唯一参照物是 ibiblio 上公开的 Comanche 055 与 Luminary 099 扫描件。你的 PR 目标不是「让代码更好」而是「让转录文本与扫描页逐字一致」。这正是许多贡献者翻车的第一站——他们带着现代工程师的「洁癖」进来却撞上了一套为「考古」而设计的验收标准。常见错误一按现代习惯改写注释与空格第一个高频踩坑是「善意地」修正注释里的拼写错误。开发者看到SPAECRAFT这种明显少了字母 C 的词第一反应就是补上它。但 CONTRIBUTING.md 给出了严格的反向规定For example, if the digitised comments containedSPACECRAFT, butSPAECRAFTwas printed in the scans, then the digitisationMUSTbe corrected toSPAECRAFT(missingC).这句话描述的场景在仓库里真实存在。打开 Luminary099/INPUT_OUTPUT_CHANNEL_BIT_DESCRIPTIONS.agc 第 73 行# CHANNEL 12 CHAN12; OUTPUT CHANNEL; BITS USED TO DRIVE NAVIGATION AND SPAECRAFT HARDWARE这里保留了SPAECRAFT缺 C——因为这就是当年打印在扫描件上的原始形态。原开发者留下的笔误是历史的一部分转录者的任务不是当语文老师而是当拓印匠。反过来也一样如果转录过程引入的笔误在扫描件上是正确的那么必须把笔误改正过来。判定标准只有一条扫描件印了什么仓库就该是什么。与拼写同样敏感的是空格。注释中字符间的空格数量必须与扫描件对齐默认惯例是新单词之间单个空格、新句子之间双空格、缩进用三空格——但这不是硬规则Not all pages in the scans follow this generalisation, if the scans only have a single space instead of a double space, use a single space.换句话说连「空格风格」都要以扫描件为准扫描件用了单空格哪怕违反「双空格代表新句子」的惯例也得照抄。这正是文档里强调的SHOULD与MUST的层级拼写错误是MUST空格是SHOULD而扫描件永远是最终裁决者。常见错误二用逻辑判断代替扫描件事实第二个高频踩坑是用「这段代码逻辑上肯定是错的」来指导修改。60 年代的 AGC 汇编充满了现代人看来匪夷所思的写法比如 Comanche055/AGC_BLOCK_TWO_SELF-CHECK.agc 中这样成串的符号定义SBIT1 EQUALS BIT1 SBIT2 EQUALS BIT2 ... SZERO EQUALS ZERO S1 EQUALS BIT1 S2 EQUALS BIT2又比如 Comanche055/PINBALL_GAME_BUTTONS_AND_LIGHTS.agc 里以# Page 307、# Page 308、# Page 310形式嵌入的页码标注以及第 200 行一带# MUST LOTEMOUT-1.这类依赖「寄存器相邻布局」的约束注释。面对这些内容贡献者很容易动起「规范化」的念头——调整对齐、统一大小写、删掉「多余」的空行甚至把「显然写错」的操作数改掉。但 CONTRIBUTING.md 用一句话关上了这扇门Any discrepancies between the scans and the source code in this repository.校对者唯一被授权做的事是消除转录文本与扫描件之间的差异而不是消除代码与现代工程直觉之间的差异。你无权判断 1969 年的工程师「应该」怎么写只能确认扫描件「实际」怎么印。把「逻辑上更合理」作为修改依据等于把 50 年前的原始档案当成可以随意重构的普通代码库——这正是维护者在多轮 PR review 中反复纠正的行为。这一原则背后有务实的技术考量仓库的最终目标是可编译的历史存档。用 yaYUL 重新汇编时任何一行与扫描件的偏移少一个空格、多一个空行、换错一个符号都可能影响最终的二进制对比。让重新编译出的结果与当年烧录进 AGC 的 ROM 镜像逐位一致才是这份仓库存在的意义。逻辑「优化」会无声地破坏这条比对链。Tab 宽度、R0000 标识与空行数量的验收红线如果说前两类错误属于「理念分歧」那最后一类是纯格式层面的「硬性红线」也是最容易触发自动化检查的点。归纳起来有三条第一缩进与空白。必须使用 Tab 缩进、Tab 宽度固定为 8、并清除行尾空白。这些规则写在 CONTRIBUTING.md 的 Formatting 一节GitHub 内置的 AGC 语法高亮以及配套的编辑器插件会自动强制。之所以卡得这么死是因为行首的物理位置在汇编源语中承载着语义标签列、操作码列、操作数列的相对关系由 Tab 宽度决定。第二R0000行标识。扫描件中有大量以R0000开头的行它们代表原始行号是逐行对齐扫描件的关键锚点。规则区分两类行含R0000的行行断与空行必须与扫描件完全一致match the scans exactly不含R0000的行连续空行只允许 1 或 2 个超过 2 个必须删掉多余的且R0000行不计入此限制。这条规则的来龙去脉很有意思扫描图像中第 8 列有一个未打印的数字2强制双倍空格即产生 1 个空行3强制三倍空格即产生 2 个空行4–8虽已定义却从未实际使用。也就是说空行数量不是排版噪音而是打印件上编码过的控制信息。随意增删空行等于篡改这份元数据。文档给出的范例可以直观地说明「对」与「错」R0819 SUBROUTINE TO SKIP... R0820 0821 LAMPTEST CS IMODES33应改为R0819 SUBROUTINE TO SKIP... R0820 0820 LAMPTEST CS IMODES33注意连行号0821都被修正为0820——行号本身也是需要与扫描件对齐的内容而不是可以「顺手改掉」的细节。第三PR 验收标准。文档末尾反复强调提交 PR 前务必确保改动与扫描件一致。这意味着任何「看起来更好」的改动如果没有对应的扫描页依据都会被驳回而任何与扫描件不符的转录错误哪怕只是少了一个字母都是合法的修改对象。结语存档者的克制比工程师的创造力更珍贵这个仓库最反常也最迷人的地方在于它要求贡献者放弃改造的冲动。现代开源文化推崇「发现问题、修复问题」而 Apollo-11 仓库把「修复」的定义反了过来真正的 bug是转录文本与扫描件之间的任何偏移真正的修复是逐字逐符地回到 1969 年的那张纸上。保留SPAECRAFT的拼写错误、保留 50 年前的古怪空格、保留看似冗余的空行——这些「不作为」恰恰是让后人能够精确复现当年飞行软件的关键。下次当你打开 Comanche055 或 Luminary099 里某段代码发现一处「明显的错误」时不妨先问自己一个问题扫描件上印的到底是什么在阿波罗 11 号源码的世界里扫描件即真理。你的逻辑判断可以为它让路但永远不能替代它。【免费下载链接】Apollo-11Original Apollo 11 Guidance Computer (AGC) source code for the command and lunar modules.项目地址: https://gitcode.com/GitHub_Trending/ap/Apollo-11创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考