nasa-handbook

NASA 手册页面

这项技能可制作一页（或少数几页）技术文档，呈现出 1969 年《阿波罗操作手册》页面的风格。页面顶部是打字机字体的页眉，下面是带编号的段落，接着是主图、第二幅图、数据表、警告和乘员检查清单。页边标签和带日期的页脚为页面收尾。主题可以是真实的（代码库、产品、协议），也可以是虚构的（传送枪）。对于真实主题，页面应让读者理解其技术概念；对于虚构主题，则应令人信服。

技能中附有完成的页面。开始前请查看 PNG 图片；它们是质量标准：

• assets/examples/portal-gun-device.png（以及 .html）：一个虚构设备。页面包含带标注、尺寸和剖视图的总布置图、电气原理图，以及一本正经的警告。
• assets/examples/espresso-fluid-system.png（以及 .html）：一台基于真实物理原理打造的虚构机器（在月球栖息地舱压下冲泡咖啡）。页面包含带剖视图的总布置图、带站点标记的流体与电气原理图，以及一张计算得出的图表。一位全新的 Agent 仅凭这项技能，经过六轮渲染就完成了它。

资源路径

此处的路径均相对于这项技能的目录（技能加载时报告的基目录）：

• assets/template.html：包含所有 CSS、共享 SVG 标记和图案、每个区块的框架以及适配检查的页面。每次都从它开始制作页面。
• assets/fonts/：Routed Gothic（Leroy 字体）、Letter Gothic 及其许可文件。将整个文件夹复制到页面旁边。
• scripts/render.sh：使用无头 Chrome 渲染 PDF（打印版）和 2 倍 PNG（预览版）。脚本会输出页脚上方剩余的空间；若页面溢出，则以状态码 3 退出。
• scripts/check.py：检查页面数量、页面尺寸、是否仅使用黑白两色以及字体。它还会裁切出用于视觉检查的 300 dpi 半宽图块（使用 --out DIR 选择输出位置）。它无法检测溢出；这由 render.sh 处理。
• references/style-guide.md：介绍页面结构、空间预算、排版、写作风格、应绘制的图示、绘图风格、常见问题和变体。首次在一个会话中制作页面时，请通读全文。
• references/svg-parts.md：可复制粘贴的绘图组件（方框、滚筒、电线、断路器、开关、通话回路、标注、尺寸线、剖视图、时间线、序列和部件条、阀门、泵、仪表、传感器、站点标记、图表）。
• references/sources.md：扫描版原始资料及其提供的启示。

工作流

1. 了解主题并找到它的核心观点。 这是读者读完后必须记住的一句话（“咖啡在密封回路中以海平面气压冲煮”）。对于真实系统，请阅读其规格说明或 README，以及代码。对你打算写出的每个数字进行搜索（限制、尺寸、间隔、重试次数、按键绑定、UI 字符串），如果文档与代码不一致，优先采用代码中的内容。对于虚构主题，先构思一套一致的规格：名称、功能、五到八个带单位的数字、控制方式，以及一种危险的故障模式。

2. 动笔绘制前，先在纸上规划页面。 按出现顺序确定各个区块：引言（3 行）、主图、功能说明（4 行）、一个带下划线的机制（2 行）、次图（可选 DETAIL 局部图）、数据表（6–8 行）、一则提示、一个清单（6–7 个步骤）。从风格指南 §5 的表格中选择图示类型。现在就写好文字；内容很短，而且写出来后，你就知道图示需要解释什么。

3. 设置文件夹。 使用用户指定的文件夹。否则，在当前项目或工作目录中新建一个文件夹。

   mkdir -p <out> && cp <skill>/assets/template.html <out>/<name>.html && cp -R <skill>/assets/fonts <out>/fonts
   

4. 填充模板。 替换每个 [BRACKETED] 占位符。使用 svg-parts.md 中的部件，以毫米为单位的坐标绘制图示。保留共享的 nh-* defs。不要添加颜色、徽标或纹理。

5. 渲染并调整版面。 运行 sh <skill>/scripts/render.sh <out>/<name>.html。 fit: 行会报告页脚上方剩余的空间；目标是 4–10 mm。溢出时程序会以状态码 3 退出。此时应删减文字或一行表格内容，而不是缩小字号。在下方区域，缩短较高的那一栏（风格指南 §2）。

6. 检查并查看。 运行 uv run --no-project --with pymupdf python <skill>/scripts/check.py <out>/<name>.pdf。 报告必须显示只有一页，且仅使用黑白两色。然后打开它列出的每张切片，检查以下问题：

   • 线条或引线穿过或接触文字（保持 0.6 mm 间距）
   • 标签彼此接触或贴近边框
   • 尺寸标注压在线条上
   • 文字被裁切
   • 同一种图案表达了两种含义
   • 箭头指错了对象

   修正问题，然后重复步骤 5 和 6。质量主要来自这个循环；预计需要三到六轮。

7. 交付。 提供 PDF 作为打印文件，PNG 作为预览文件；如果有预览工具，就展示出来。说明页面解释了什么。对于真实主题，列出用于核对数字的文件。注明任何刻意简化之处。

如何呈现正确的风格

以下这些选择，决定了页面看起来是否可信，而非徒有其表。 style-guide.md 中有完整的理由说明。

• 重结构，不重纹理。 这种风格由页眉、编号段落、图示编号、修订栏、页签和带日期的页脚构成。不要加入咖啡污渍、噪点、倾斜的印章或 NASA 标志。
• 三种字体，各司其职。 正文使用字母间距较宽的衬线打字机字体。图示内部所有内容使用 Leroy 大写字体。清单卡片仅使用 Letter Gothic。此处全大写是风格特征，不是风格错误。
• 一个观点，两幅图。 主图阐释核心观点；次图展示其随时间的表现或细节。其他内容都应为两幅图提供支持。
• 平实、精确的语气。 使用第三人称、现在时，数字带单位，控制项按标牌样式大写，UI 字符串逐字引用。
• 线条绝不穿过文字。 引线从标签外侧起始，终止于部件上。移动标签，不要缩小它。
• 符合制图尺寸的细节。 线宽为 0.16 到 0.5 mm，箭头长约 2 mm，标签为 2.05 到 2.5 mm。模板中的类和标记已预先设定好这些参数；请使用它们，不要临时设置描边。
• 纯黑配纯白。 使用排线和点状轮廓来区分。打印机会将任何色调或灰色都转换为网点。
• 真实主题以准确为先。 数字错误的页面，即使看起来再精确，也不如少一行内容的页面。

变体

US Letter、多页章节、控件与显示页面、工程图纸、Technical Note 封面和 1975 年 Helvetica 风格均已收录在样式指南 §9 中。页面结构、绘图规则和检查循环保持不变。

要求

• Google Chrome 或 Chromium，用于运行 render.sh（如果未找到，请设置 CHROME=/path）。
• uv（或带有 pymupdf 的 Python），用于运行 check.py。
• Iowan Old Style 随 macOS 提供。在其他系统上，正文会回退到 Georgia，效果可以接受。Helvetica Neue（或 Arial）用于绘图标签中带标记的“1”。