跳转至

图片目录

各章截图分别放在对应的 chapterN/ 子目录中。正文使用的裁剪图放在章节目录根部，未经裁剪的完整截图放在该目录的 source/ 中。

完整截图的存档要求适用于本规范生效后新增或重拍的图片，不要求为已有截图补齐原图。

book/assets/chapter3/
├── source/
│   └── 3-1-01-tech-editor-created-full.png
└── 3-1-01-tech-editor-created.png

正文截图使用 章-节-序号-内容.png，完整截图沿用相同编号和内容名，并在末尾增加 -full。Markdown 只引用章节目录根部的裁剪图，source/ 中的文件用于以后重新裁剪，不直接进入书稿。

截取完整截图

  • 截取完整的 dsh 应用窗口，不包含桌面、菜单栏和其他应用。
  • 除非正文专门演示主题切换，否则统一使用浅色主题和 100% 页面缩放。
  • 截图前整理界面状态，关闭无关面板、提示和通知，但不能为了画面好看改变需要证明的结果。
  • 使用系统或浏览器产生的原始 PNG，不使用 JPEG，也不使用聊天软件或文档软件转存的图片。
  • 完整截图同样会进入仓库，不能依靠后续裁剪隐藏 API Key、访问令牌、个人路径、内部网址、私人聊天和其他敏感信息。

裁剪正文图片

  • 从完整截图复制出正文图片，保留原图不动。
  • 裁剪只删除外围像素，不先缩小再放大，不拉伸图片。
  • 保留足够的界面上下文，让读者能判断目标位于哪里；同时裁掉与当前观察点无关的大片区域。
  • 不得从中间劈开文字、按钮、输入框、卡片、对话框、圆角、边框或阴影。目标容器四周应保留自然的留白。
  • 不要紧贴一个小控件裁剪后再将它放大到接近整页。局部画面应保持与真实界面相近的视觉比例。
  • 图片画布居中不等于可见内容居中。裁剪后检查左右留白和内容重心，不能让一侧保留大块空白、另一侧贴近内容。
  • 任何文字或界面容器接触图片边缘，都要回到完整截图重新裁剪，不能依靠 PDF 排版掩盖。
  • 前后对比图必须从相同窗口尺寸和页面状态截取，并使用完全相同的裁剪范围。

清晰度

  • 优先在 Retina 原始分辨率下截图。完整窗口截图的宽度尽量达到 2500 像素以上。
  • 接近正文全宽显示的裁剪图，宽度通常应保留至少 1300 至 1600 像素。像素不足时减小书中的显示宽度，不进行插值放大。
  • 可以使用 sips -g pixelWidth -g pixelHeight <图片> 或 ImageMagick 的 identify <图片> 检查像素尺寸。
  • 对白色背景的界面截图，可以用 magick <图片> -fuzz 3% -trim -format '%wx%h %X%Y' info: 辅助检查可见内容的边界。这个结果只用于发现不对称白边，不能代替人工决定裁剪范围。
  • 构建 PDF 后在 100% 视图下检查小字、细线、圆角和浅色边框。高清不仅指像素充足，画面在页面中的大小也要自然。

放入书稿前检查

  1. 完整截图与裁剪图的编号和内容名能够对应。
  2. 裁剪范围没有切断任何文字或界面容器。
  3. 图片内部的左右留白和可见内容重心自然，不能只确认 Markdown 或 Typst 中的图片盒子已经居中。
  4. 正文图片在预定显示宽度下清楚可读，也没有被异常放大。
  5. 图片说明描述可见结果，不写成操作口令，也不重复正文。
  6. 完整截图和裁剪图都不含敏感信息。
  7. 运行 ./scripts/build_typst_pdf.sh，检查图片所在的实际页面。

封面上的鱼形标识保存在 book/assets/fish-mark.svg。它使用 DeepSeek Harness 源码（packages/client/ui-primitives/src/FishLogo.tsx）中的官方矢量路径，缩放到任何尺寸都不会糊。

流程图源文件

使用 TeX 绘制流程图时，将可编辑的 .tex 源文件保存在对应章节的 source/ 目录，并把生成的 SVG 放在章节目录根部供正文引用。.tex 文件只用于维护配图，不参与全书 PDF 的构建。